newbury-exhibit-v3/.claude-context/00-overview.md

Newbury Exhibit — Overview

Fan-made shared multi-viewer AR experience for a physical LEGO® Hidden Side™ town display (tribute project — not affiliated with the LEGO Group). Multiple phones point at printed "Newbury Crests" (ArUco markers) and see the same server-driven ghosts anchored to real-world positions, each from their own viewpoint.

Shape of the thing

• Delivery: web, no app install. Visitors open a URL and press Start.
• Tracking: printed fiducials + a joint multi-marker solve. No SLAM, no cloud AR service — self-hosted end to end.
• Authority: the server owns which ghosts exist and where; clients own only their own camera pose. That's what keeps multiple phones consistent.
• Motion: deterministic functions of (spawn record, wall-clock time), so phones agree without streaming positions.

Current state (v3)

v3 is a tracking-core transplant into v2's body: the playlist engine, residents/tracks, character editor, admin suite, error overlay, password-gated final mode and deployment all carry over unchanged. What changed is how the camera pose is recovered — see 01-architecture.md.

Deployed in place of v2: same host port, container name and exhibit-live volume, so live state carries over and rollback is one command.

• Repo: newbury-exhibit-v3 (v2 retained as the rollback path)
• Deploy: cd ~/newbury-exhibit-v3 && bash deploy.sh
• Rollback: cd ~/newbury-exhibit && docker compose up -d --build
• Page index, API list and HUD guide: docs/PAGES.md

Conventions

• World units cm; origin at the front-left table corner; +X right, +Z back, +Y up. Marker print sizes stay in mm (sizeMM), converted once at the solver boundary.
• data/*.json are committed seeds; data/live/ (a Docker volume) is runtime state.
• Dev mode shows a tracking HUD and an on-screen error overlay; final mode password-gates admin.

Session Log

• 2026-10-12 — Admin Navigation Tidy-up — tool registry driving both the nav bar and a new /admin/ hub; unreachable A3 test rig and an unauthenticated calibrate page fixed.
• 2026-10-07 — Corner Precision and ROI Detection — sub-pixel corner refinement (own implementation; cornerSubPix is absent from the pinned build), ROI-first detection cropping from the native video, and an anchor-coplanarity check surfaced in the HUD.
• 2026-09-23 — AR Tracking Overhaul: Worker Offload, Camera Model, and Coplanar Pose Ambiguity — moved OpenCV off the main thread, fixed the focal/FOV model for portrait streams, deduped marker ids, gated the mirrored coplanar pose, and built a two-page A3 test rig with a foldable marker tower.