# Pages

Every HTML page the exhibit serves, and what it's for.

**Production base URL: `https://newburynights.hideawaygaming.com.au/`**

**Keep this current.** When a page is added, renamed, or removed, update this
file in the same commit — it's the index there is, since there's no `/admin/`
landing page (admin URLs must be typed in full).

## Visitor

| Path | Page | What it does |
|------|------|--------------|
| `/` | Exhibit | Landing screen → camera AR view. The thing visitors use. Tracking HUD appears in dev mode. |

## Admin

Open in `EXHIBIT_MODE=dev`; password-protected in `EXHIBIT_MODE=final`
(`ADMIN_PASSWORD` in `.env`).

| Path | Page | What it does |
|------|------|--------------|
| `/admin/layout.html` | Layout Editor (3D) | Marker anchors, building occluders, spawn points, wander paths, table size. Save/load named layouts. |
| `/admin/playlist.html` | Playlist | Tracks (set, spawn timing, concurrency, priority), residents, behaviour tuning, time windows. |
| `/admin/characters.html` | Characters | Per-ghost visuals: model, part placement, gradient colours, opacity, height, scale, face/torso textures. |
| `/admin/landing.html` | Landing Page | Visitor landing screen: title, logo, background, accent colour, about text, disclaimer. |
| `/admin/preview.html` | Virtual Viewport | Live orbit view of whatever ghosts are currently active, straight off the same WebSocket feed as the exhibit. Ground truth when the AR view disagrees. |
| `/admin/testsheet.html` | A3 Test Rig | Two printable A3 pages — calibration sheet plus a foldable marker tower — and a one-click load of the matching scene + playlist. See below. |
| `/admin/plan.html` | Placement Plan | Measured plan for physically positioning crests and models on the real table. |
| `/admin/print.html` | Print Crests | Generates printable ArUco markers ("Newbury Crests") at the configured `sizeMM`. |
| `/admin/calibrate.html` | Calibrate | Camera/marker calibration helper. Detects crests **without** filtering against the scene, so it's the quickest way to prove a printed crest is readable at all. |
| `/admin/errors.html` | Client Errors | Errors reported by visitor devices (JS errors, unhandled rejections, ghost build and scene-fetch failures). First stop when something works on one phone but not another. |
| `/admin/login.html` | Login | Only relevant in final mode. |

## The A3 test rig

`/admin/testsheet.html` is a self-contained test environment for evaluating
tracking, occlusion and lighting without the LEGO town in the way. Two pages,
both A3 landscape.

**Print at 100% ("Actual size"), never "Fit to page."** Check the 100 mm scale
bar on page 1 first: if it doesn't measure 100 mm, every crest is the wrong size
and every pose is scaled with it.

**Page 1 — the ground sheet.** The sheet *is* the table: A3 landscape is exactly
42.0 × 29.7 cm, origin at the front-left corner, matching the exhibit's world
frame. Six 60 mm crests (ids 0–5) spread 38.7 cm corner to corner. Marked on it:
the tower footprint at centre, the walker's loop, and the static ghost's spot.

**Page 2 — the tower.** Folds into an 85 mm square × 160 mm tall prism with a
60 mm crest on each of its four sides (ids 6–9, centred 100 mm up) plus one on
top (id 10). Fold printed side OUT, tape the glue tab, fold the top flap over,
and stand it on the dashed square with the FRONT panel toward the front edge.

Why the tower exists, and why it isn't optional: **crests lying flat all share
one plane, and a coplanar point set has two poses that reproject almost equally
well** — the true one and a mirrored twin. With few crests in frame the solver
intermittently returns the twin, which looks like ghosts snapping to the wrong
side of the table and vanishing. Reprojection error can't tell them apart (the
twin fits the pixels). A crest 100 mm above the sheet makes the geometry properly
3D, and no mirrored pose can fit it. `cv-worker.js` also gates poses on physics
(camera must be above the sheet, can't teleport) but that only suppresses the
symptom — the tower is the cure.

The tower doubles as the occluder. The **static ghost** sits at (21, 22) cm,
deliberately *behind* it from the front: walk around and the ghost should
disappear behind the tower. The **walking ghost** runs an 18 × 12 cm loop around
it, 60 cm perimeter, ~40 s per lap at the default 1.5 cm/s.

"Load this layout onto the server" writes both the scene and the playlist, built
from the same constants that drew the sheets, so print and config can never
drift apart. It **replaces** the live scene and playlist — save your current
layout first.

Known gap: the layout editor doesn't understand cylinder occluders or wall-mounted
anchors well, so opening and saving this layout there may mangle the tower.

## Useful API endpoints

Read-only ones are handy to open directly in a phone browser while debugging;
the rest need auth in final mode.

| Endpoint | Returns |
|----------|---------|
| `/api/info` | Mode (`dev`/`final`) and build info |
| `/api/scene` | Live scene: anchors, spawns, paths, buildings, table |
| `/api/playlist` | Live playlist config (tracks, residents, behaviours) |
| `/api/ghosts` | Full ghost roster + colour gradients |
| `/api/characters` | Per-ghost visual overrides |
| `/api/models` | Uploaded OBJ model manifest |
| `/api/landing` | Landing page content |
| `/api/layouts` | Saved named layouts |
| `/api/client-errors` | Reported client errors (auth in final mode) |
| `/ws` | WebSocket: `scene`, `active`, `spawn`, `despawn`, `characters`, `pong` |

## Reading the dev HUD

```
ws open  rx active,pong          WebSocket state + recent message types
scene 11 anchors  ghost recs 2   scene loaded, ghosts held client-side
60 fps  detect 20Hz@960  fov 58  render rate, detect rate/resolution, camera fov
  REJ:jump                       (only when the solver refused a pose)
eng opencv  moving               engine; FROZEN = ghost motion paused
axis std  cv:ready               engine mode + OpenCV worker state
markers 3/4 seen [0,4,6] +1dup   solved/raw crests, ids, duplicate decodes
raw / view / up / pos            solved camera pose
m0 px(0.02,-0.05) proj(0.03,-0.04)   AIM CHECK — see below
ghost ndc(-0.10,0.20) ON-SCREEN  first ghost's screen position
```

**Aim check.** `px` is where the crest actually sits on screen (`0,0` = centre);
`proj` is where the solved pose projects it. Point straight at a crest so `px` is
near `(0,0)`: if `proj` matches, the camera model is right. A sign flip means a
mirrored axis; a constant ratio means the projection doesn't match the lens (tune
`localStorage.nbx.hfovDeg`); an intermittent horizontal flip with correct vertical
is the coplanar ambiguity — stand the tower up.

## Gotchas worth remembering

**Detection filters against the active scene.** A crest that isn't an anchor in
the current layout is detected and then discarded, which used to look exactly
like "the camera can't see anything". The scene is fetched over HTTP at start so
a flapping WebSocket can't break tracking, and the HUD distinguishes the cases.

**The video stream may be portrait.** iOS often hands back 720×1280, so any FOV
assumption must apply to the image's LONG axis, not `videoWidth`. Getting that
wrong made the focal length 1.78× too short.

**Motion amounts live on the server.** `playlist.js` sends explicit `bobAmp`,
`radius`, `speed` values with every spawn, so the client's defaults never apply
to a real ghost. Tune motion in the playlist config (`behaviors.bobAmp`,
`wanderRadius`, `pathSpeed`), not in `behavior.js`.

**An upstream proxy can override cache headers.** The app sends `no-cache` for
JS and HTML, but openresty in front has been seen replacing it with a daily
`expires`. If a deploy doesn't reach a device, check the response headers and
test in a private tab.