Add live-webcam Teblid AR example + examples index (#36)

[kalwalt]

Summary

Adds a working live-webcam AR example using the Teblid tracker, plus an index.html landing page for all examples. This implements the webcam half of #36; the examples-cleanup half (retiring the broken demos) is intentionally deferred — nothing existing is modified or removed here.

• 4 new example files + 1 design doc, ~664 insertions, 0 deletions.
• No library changes, no rebuild — uses the dist/WebARKit.js already on dev (post WebARKitLib#45).

What & why

The existing webcam examples are broken. This is a clean, working live-camera reference built on the now-correct library: it consumes the corrected GL pose (matrixGL_RH) directly — no render-side pose hack — and combines the static example's conventions with a continuous bufferCopy ping-pong loop and a getUserMedia feed.

video → drawImage → getImageData → set() into a recycled ArrayBuffer
   → worker.postMessage(transfer) → process_raw(RGBA)
   → tracker (convert2Grayscale internally) → getMarker(matrixGL_RH)
   → postMessage(transfer buffer BACK) → main → setMatrix(root.matrix) → process() next

Files

File	Role
examples/worker_teblid_webcam_threejs.js	dedicated worker — bufferCopy ping-pong (returns the frame buffer each reply), emits matrixGL_RH
examples/threejs_teblid_webcam_worker_ES6.js	start() module — scene + cube/axes, live loop, hides content when not found
examples/threejs_teblid_webcam_ES6_example.html	page + camera bootstrap (initCamera, actual videoWidth/Height, CAPTURE_W/H constants)
examples/index.html	grouped landing page linking every example
docs/design-webcam-teblid-example.md	design + full decision log

Design decisions (see the design doc for the full log)

• bufferCopy ping-pong — recycle one transferable ArrayBuffer (avoids per-frame GC); the chosen perf path.
• RGBA end-to-end — the tracker converts to grayscale internally (convert2Grayscale).
• Match-aspect, projection as-is — #video + #canvas share the capture aspect and object-fit:cover, so AR overlays the video exactly; projection used unscaled.
• No mirroring of the processed feed (keeps tracker handedness correct).
• 640×480 environment default, resolution as a constant for the higher-res check.
• On-screen status ("Marker tracked" / "Searching…") with console logging preserved.

Testing

Manual / on-device: open examples/threejs_teblid_webcam_ES6_example.html over localhost, allow camera, point at a printed data/pinball.jpg. Verified live tracking with the cube + axes anchored on the marker, right-handed (red→right, green→up, blue→toward viewer); content hides when the marker leaves frame; status badge flips correctly.

Review checklist

• No existing example modified/removed (diff is additive)
• index.html links resolve from examples/
• No leftover debug scaffolding in the new files
• Camera permission failure shows a message and degrades gracefully

Risks / known limitations

• Tracking is not declared lost when the marker leaves frame — the "Marker tracked" status can persist after the marker is gone. This is a library state-machine limitation (optical-flow validity is only updated inside the if(_isDetected) branch), not introduced by this PR. Tracked in Tracking never declared lost when the marker leaves the frame (_valid/_isTracking stuck) WebARKitLib#46.
• Detection runs full-res every frame (the perf guard is deferred to Restore downsampled feature detection + single-marker detection guard for performance (reconcile with ArtoolkitX OCVT) WebARKitLib#44) — 640×480 is the smooth default.
• Aspect mismatch → cover-crop on both #video/#canvas (identical, so alignment holds).

Related

• Implements the webcam half of Clean up examples directory: audit and retire legacy/broken examples #36 (cleanup half deferred).
• Builds on the library fixes in Fix AR pose/localization on >640x480 frames: keypoint scale bug, projection X-sign, marker handedness WebARKitLib#45.
• Known-limitation follow-up: Tracking never declared lost when the marker leaves the frame (_valid/_isTracking stuck) WebARKitLib#46.

Refs #36

🤖 Generated with Claude Code