Merge origin/main into fix/sanitize-openai-proxy-errors

docs/CURRENT-STATE.md

@@ -1,9 +1,96 @@
 # God's Eye View Current State
 
+AIS encodes speed over ground in 0.1-knot units and course over ground in
+0.1-degree units, reserving the top code of each field for "not available", so
+those reports arrive as 102.3 knots and 360 degrees. Both are stored as unknown,
+and vessel cards, the HUD and analyst queries show a missing measurement rather
+than a reading. Heading keeps its existing separate check for its own sentinel.
+Genuine readings are unchanged, including a stopped vessel's zero and the
+highest speed and course the fields can encode.
+
+Native `<select>` controls declare a dark colour scheme and explicit option
+colours, so the browser-painted option list matches the panel it drops out of.
+The scheme is declared on the controls rather than on the document root, so
+hand-tuned scrollbar and text-input skins are unchanged. Applies to the HUD
+layout, Scenes, CCTV camera, Radio filter and Draw colour menus.
+
+Vessel snapshot completeness is separate from freshness. A current snapshot with
+rejected or duplicate records shows PARTIAL with accepted/received counts; stale
+or unknown freshness and transport failures retain their warnings. Partial
+snapshots still retain missing contacts within the existing age and row limits.
+A complete successful snapshot clears the partial indicator.
+
+Director imports now open a non-mutating preview before Apply. EDIT DETAILS
+authors validated anchor, camera, pack and interaction drafts; SHARE SCENE exports
+a selected scene or a bounded bundle of explicitly chosen pack files. Bundled
+bytes remain in memory until replacement/teardown and require reimport after a
+page reload. Stop releases rendering while retaining replay bytes. Cancellation
+and stale drafts cannot replace newer project state. See [authoring and sharing](DIRECTOR-SHARING.md).
+
+Director version-6 documents add bounded, scene-local feature actions. Settled
+LOAD/seek exposes keyboard-accessible text/source cards, anchor focus, explicit
+shot transitions and admitted layer state changes. Pointer claims take priority;
+Stop/replacement/teardown cancel pending actions and release handlers and UI.
+Same-shot seeks rebuild selected packs and restore declared layer baselines.
+See [scene actions](DIRECTOR-INTERACTIONS.md). Existing scenes/assets and credit remain.
+
+Director version-5 documents add scene-local data-pack manifests and per-shot
+selection. Registered sources acquire bounded, cancellable assets separately from
+GeoJSON, PNG and manually played media presentation. Storage paths, attribution
+and geographic placement remain distinct; Stop/replacement releases resources.
+Import acquires nothing. See [data packs](DIRECTOR-DATA-PACKS.md). Existing scene
+content, assets and credit remain unchanged.
+
+Director version-4 documents add named geographic anchors and optional explicit
+camera moves with easing, duration and holds. Playback and seek share one
+coordinate sampler; navigation/manual input revokes authored motion and pending
+holds. Anchor heights and explicit endpoints require the WGS84 ellipsoid
+reference. Legacy projects retain their ordinary flights, content and edits.
+See [camera directions](DIRECTOR-CAMERA.md).
+
+Realtime voice composes separate connection, response/tool, Radio handoff, input
+and audio-meter, cost, viewport-context and diagnostic owners. The existing
+controller exports and session/backend contracts remain available. Tool protocol,
+response wording, push-to-talk timing, model preferences and Radio confirmation
+order are preserved. Stopped connections, stale offers and delayed captures cannot affect a
+replacement session; audio meters release failed initialization and reject revoked
+frames. Delayed action results and post-capture continuations cannot resume a
+stopped conversation or send output into a replacement. See [voice ownership](VOICE-OWNERSHIP.md).
+
+The application shell composes focused state owners for navigation, destination
+lookup/orbit, Cockpit, visual settings, panel layout, aircraft display and layer
+bindings. Keyboard/display subscriptions have a separate lifetime; existing
+layer, scene and voice methods remain available through a delegation facade.
+Disposal settles pending globe resets and removes camera-entry listeners before
+asynchronous restoration; replacing a manager detaches its old Directions
+services. See [UI ownership](UI-OWNERSHIP.md).
+
+Director's ordered shot runner is exported independently of rendering, UI,
+storage and scene content. The existing scene controller supplies an adapter for
+visual/layer state, camera travel, media holds and release. Playback cancellation,
+preview cleanup, saved projects and all scene assets/attribution are preserved.
+Pure authored-time/seek calculations and a playback clock now own timing,
+hold deadlines and subscriptions. Stop immediately clears timers and settles
+holds; stale tick callbacks cannot publish into a replacement. Registered pack
+rules own presentation overrides and Nepal map fallback without changing saved
+shots or content. Scene-document validation and legacy migration now have separate
+owners. Invalid imports preserve the current project; unreadable saved projects
+are protected from fallback writes. Version 6 is the export format, with
+zero pitch, low camera heights, scope and detection edits preserved. See [the document contract](SCENE-DOCUMENT.md);
+see [Director](DIRECTOR.md) for camera, pack, action and sharing support.
+
 Search framing and annotations request semantic map features from an explicit source. The Overpass adapter owns bounded queries, member/tag decoding and request deadlines; callers retain candidate ranking, outline caching, deferred retries and scene placement. Empty, transient and throttled outcomes remain distinct. Traffic sources return road records and installation sources return mapped records with freshness/saturation metadata, so their layers no longer decode upstream elements. ALPR already normalizes its records in the source. Default providers, footprints, road directions, exact-viewport retries and source attribution are unchanged.
 
 Nepal media preloads survive repeated camera-flight updates, but Stop, event disable and replacement remove abandoned frames and revoke pending Facebook sessions. Fallback evidence-card clicks respect the shared drawing-tool pointer lease.
 
+In the Pinokio browser shell, Nepal provider embeds and hidden preloads are
+disabled before creating frames or loading provider SDKs, because the shell can
+redirect iframe navigation to an external browser. Existing source-linked cards
+remain available, and Open Original is an explicit action. Optional approved
+local clips still use the existing fallback; the public pack bundles no witness
+clips. Chrome and Safari retain embeds even when visiting a Pinokio-launched
+server. This compatibility fallback does not repair Pinokio's navigation handler.
+
 Nepal flood lines classify the active terrain or photoreal surface, and the surge marker follows that surface. Geographic route coordinates are unchanged; dynamic lines do not rely on unsupported depth-failure materials. Later media-only shots keep their completed source-path history throughout arrival and card reveal.
 
 Scene Stop, replacement, seek, and teardown revoke the Upper Valley locator's delayed camera approach and orbit while preserving its visible callout. A revoked timer or camera callback cannot start another flight or interfere with a newer shot.
@@ -20,7 +107,7 @@ The Nepal overview route and lake-shot trail share the river-centerline starting
 
 The event panel omits the WITNESS shortcut. Shot media, source attribution, Open Original links and corridor navigation remain available.
 
-The Mailung Bazzar, Dandaguan YouTube embed follows the provider's playback clock through 0:07, then the scene advances after its 0.65-second media exit. The controller reconciles provider state and source time when the API attaches and while waiting for playback, including missed PLAYING notifications and an already-ended clip. Startup is bounded to five seconds, and stalled playback has a bounded timeout; unavailable or blocked media cannot strand the scene. The authored estimate remains seven seconds plus the exit, replacing older saved holds at runtime without rewriting them. Stop, replacement and teardown revoke pending playback callbacks.
+The Mailung Bazzar, Dandaguan YouTube embed follows the provider's playback clock through 0:07, then the scene advances after its 0.65-second media exit. The controller reconciles provider state and source time when the API attaches and while waiting for playback, including missed PLAYING notifications and an already-ended clip. Startup is bounded to five seconds, and stalled playback has a bounded timeout; unavailable or blocked media cannot strand the scene. When the host deliberately suppresses provider playback and there is no approved local clip, the source card instead uses the authored 7.65-second dwell before the next shot. The authored estimate replaces older saved holds at runtime without rewriting them. Autoplay requires transient Director ownership from Play Scene or Play Shot; LOAD, restoration and seek remain passive. Stop, replacement and teardown revoke that ownership and pending playback callbacks.
 
 Persistent media-led Nepal shots preserve their completed upstream flood path during camera travel. The next reach still reveals after arrival; direct loads reconstruct the prefix and backward replay trims downstream history.
 
@@ -2435,9 +2522,9 @@ its criteria cannot be silently ignored.
 | Traffic | OSM Overpass (+ optional TomTom live flow) | `src/data/traffic.js` | `/api/overpass` + `/api/tomtom` | viewport-driven |
 | CCTV | Austin + Caltrans (CA) + TfL London + Ontario 511 + Fintraffic (FI) + DriveBC (BC) + TxDOT (TX) + Estonia (Tallinn, Tarktee) + Live Traffic NSW + Open Calgary Open Data + Street View fallback | `src/data/cctv.js` | `/api/cctv` | 10s (active) |
 | Radio | Radio Browser (public-domain station directory) | `src/data/radio.js` | `/api/radio/stations`, `/api/radio/click/:uuid` | 45 min directory refresh |
+| Transit 🚌 | Operator GTFS-Realtime VehiclePositions (7 keyless regions, `src/data/transitFeeds.js`) | `src/layers/transit/` via `src/app/layers/transit.js` | `/api/transit` | 15s (poll + delayed playback) |
 | Bikeshare 🚲 | GBFS (Lyft + BCycle) | `src/data/bikeshare.js` | `/api/gbfs` | 60s |
 | Directions 🧭 | OSRM on FOSSGIS servers (OpenStreetMap) | `src/data/directions.js` | `/api/route` (`steps=1`) | on placement / mode change |
-| Transit 🚌 | Operator GTFS-Realtime VehiclePositions (7 keyless regions, `src/data/transitFeeds.js`) | `src/layers/transit/` via `src/app/layers/transit.js` | `/api/transit` | 15s (poll + delayed playback) |
 | Datacenters ▣ | OSM extract (bundled) | `src/data/localLayers.js` | — | static |
 | Dams ▰ | OpenInfraMap/OSM extract (bundled) | `src/data/localLayers.js` | — | static |
 | Submarine Cables ◠ | TeleGeography public map (bundled) | `src/data/telegeographySubmarineCables.js` | — | static |
@@ -2525,7 +2612,9 @@ What a card needs is a resolved ground anchor: a step whose ground cell has not
 answered yet opens nothing rather than a card hanging at sea level. The cells
 are re-read for up to 90 seconds, which outlasts a cold terrain round trip;
 reroute, CLEAR and disable cancel that.
-Transit is off by default, and share links use token `j`. The layer polls
+Transit is off by default, and share links use token `j`. The movement panel order
+places Transit directly after Street Traffic and before Bike Share. Cameras and
+utilities retain their own groups. The layer polls
 registered feeds near the camera every 15 seconds, below a 3,000 km altitude
 gate. Seven keyless regions are available: Boston, Austin, Minneapolis–St Paul,
 Helsinki, the Netherlands, Norway and South East Queensland. Mode silhouettes
@@ -2550,10 +2639,19 @@ clipped to the displayed time. The browser retains up to 15 minutes and 128
 fixes per vehicle, under a global 32 MiB history budget. Capacity pressure may
 shorten that history. Only the selected vehicle has a trail: completed segments
 are batched primitives, and a small moving head ends at the marker. Trail
-geometry is bounded to 2,048 prepared vertices; history changes rebuild the
-body, while ordinary playback updates the head and segment visibility.
-Both normal and depth-fail instance colours follow the age ramp once per display
-second or style change. Subdivision crossings update only changed visibility
+geometry is bounded to 640 prepared vertices, prioritizing the active corridor
+and shortening the oldest geometry first. Active and future marker corridors
+retain their own 640-vertex budget; long report intervals use coarser subdivisions
+than 25 m instead of dropping an admitted vehicle. Supported scenes use ground polylines
+classified against both terrain and 3D tiles, including after map-stack changes,
+with per-segment age colours. History changes rebuild the body. The head is one
+short draped corridor, clipped to displayed time by a material uniform; only
+subdivision crossings rebuild it. Ordinary frames upload no head geometry.
+Without ground-polyline support, ordinary primitives retain a mode-coloured
+0.55-alpha depth-fail path, including the head, without dimming it to near-black.
+Instance attribute updates write back the same typed array returned by Cesium;
+its getters return copies, so reading a second time discards a visibility or colour edit.
+Normal instance colours follow the age ramp once per display second or style change. Subdivision crossings update only changed visibility
 attributes. Deselecting releases selection geometry; marker paths retain only
 active and future corridors.
 
@@ -2571,22 +2669,27 @@ ingestion, eviction uses receipt-ordered queues, and capacity loss is disclosed
 when history is recreated.
 
 **Surface and route limitations.** Heights are aligned to work with Google 3D
-tiles. Unknown historical surfaces leave gaps in a trail. Sparse reports can
+tiles. Draped history is prepared on selection even while marker floors are unresolved;
+Cesium resolves its surface. Without ground-polyline support, unknown historical
+surfaces leave gaps. A selected body follows layer enablement and vehicle existence,
+so an off-screen head does not hide an on-screen tail. Sparse reports can
 cut across corners; these paths are not surveyed route geometry. Subway markers
 are projected to street level because the feed does not provide depth, and the
 selected card explains that choice. Actual street-level views still require
 visual inspection.
 
 **Appearance.** Normal fleet frames are 20 px, growing to 30 px on selection;
-NVG, thermal and noir frames are 30/36 px. Source rasters are 48/96 px before padding.
-External halos are 1/1.5 px in normal and 3/3 px in sensors, calculated from the
+CRT, NVG, thermal and noir frames are 26/39 px. Source rasters are 48/96 px before padding.
+External halos are 1/1.5 px in normal, 1.25/1.25 px in CRT and 2/2 px in sensors, calculated from the
 final unpadded display size. Six modes, two sizes and three profiles cap the
 raster cache at 36 variants. Normal mode colours are bus `#5EF08A`, tram
 `#FFC24A`, subway `#FF4538`, rail `#D9A6FF`, ferry `#5FD6FF`, and unknown
-`#D8DDE5`. Selection keeps the mode colour. Sensor bodies use solid rounded envelopes with at least 60% opaque white coverage
-of the padded display footprint, without interior panel lines. Sensor input is opaque white with a
-fully opaque black halo; black-hot reverses the contrast through the
-thermal effect. Creation, mode changes, selection, deselection, map presets and
+`#D8DDE5`. Selection keeps the mode colour. Sensors reuse each normal silhouette's exact
+outer path, filled opaque white without interior panel lines, with an opaque
+`#05080C` halo. Only the external padding grows; the unpadded silhouette remains
+at CRT size. There is no envelope body. Black-hot reverses the contrast and
+Ironbow maps the white input to its hottest palette entry through the thermal
+effect; sprite code never applies a red tint. Creation, mode changes, selection, deselection, map presets and
 Cockpit vision use the same sprite styling function.
 
 Sensor signatures remain in-scene. The thresholds in `qaMetrics.js` require
@@ -2596,14 +2699,17 @@ of its phosphor peak white (0.65992 from RGB 0.16/1/0.22), halo minimum ≤0.25
 with the centre minus sampled background reported without gating. Each preset needs at least
 six verified, unobscured sprites; insufficient coverage is UNEXERCISED.
 The sampler excludes overlapping footprints, including otherwise ineligible
-sprites, and verifies pick ownership across all nine sampled core pixels.
+sprites, and chooses nine source-raster points in the widest solid white band, avoiding
+window/panel gaps. Equal-width tram bands prefer the upper solid body over the
+geometric centre; the nine-point spacing and all thresholds remain unchanged.
+The sampler then verifies pick ownership at all nine points.
 Noir samples also exclude its deliberately vignetted outer field, using shader
 settings and screen position rather than observed brightness. Selected-trail
 diagnostics report every condition even when selection fails.
 
 Transit brackets use the normal-composite overlay surface: a 1.25 px mode-colour
 stroke over 3.25 px dark backing. Other contact themes retain their existing
-behavior. The selected trail uses a 2 px core over 4 px backing, mode-coloured
+behavior. The selected trail uses a 3 px core over 5 px backing, mode-coloured
 in normal and white input in sensors. Alpha falls linearly from 0.80 at the head
 to 0.45 at two minutes, 0.20 at ten minutes and 0.08 at fifteen minutes.
 
@@ -2626,7 +2732,10 @@ heights, and reuses caller-owned sample and segment storage.
 collections above CCTV and Bikeshare. Traffic, Bikeshare and Transit share camera
 sensitivity claims; the original sensitivity returns after the last release.
 Visibility checks combine the camera frustum and ellipsoid occlusion at no more
-than 4 Hz; missing map bounds do not admit the globe's far side. Frame work
+than 4 Hz; missing map bounds do not admit the globe's far side. Camera arrivals
+rebuild an unprepared or cold marker corridor during that visibility sweep,
+adopt a loaded surface, and update both heightPending and surfaceReady diagnostics.
+A resolved display sample clears its pending-height gate without waiting for a poll. Frame work
 visits moving visible vehicles, up to 64 pending height changes, and the selected
 head. Rotation visits visible membership at 5 Hz, with selected rotation per
 frame. The transit render hold exists only for visible positional or orientation
@@ -2640,6 +2749,15 @@ destruction also releases collections and registrations.
 QA_BASE_URL=http://localhost:4305 QA_TAG=keyless node scripts/qa-transit.mjs
 ```
 
+`QA_BASE_URL=http://localhost:4305 node scripts/qa-transit-recovery.mjs` is the
+focused keyless camera-arrival regression. With destination tiles loaded, it
+injects nine disclosed moving-bus reports and delays their floor acquisition,
+selects the hidden vehicle, then releases the floor and calls camera.setView.
+Within two seconds it requires a visible marker, a prepared visible body and
+at least six of eight paired off/on trail pixel samples. It uses production
+selection, visibility and geometry owners and writes screenshots plus JSON;
+it does not establish Google 3D acceptance.
+
 The full run samples completed frames at 1920×1080 CSS pixels, records DPR, and
 measures moving fleets of 800 and 3,000 vehicles with 128 fixes each and DETECT
 on. Street/metro targets are respectively: transit frame CPU p95 ≤1/4 ms, frame
@@ -2670,6 +2788,30 @@ injected playback independently of live fleet activity. Thermal checks verify
 style activation before reading generated controls; DETECT checks set density
 and exercise the real OFF/restore button. Cesium render errors fail selection
 acceptance.
+The `trail-visible` section requires a visible Google 3D tileset. It selects a
+scripted straight bus with CapMetro metadata under the isolated `qa-trail-capmetro`
+feed ID, with nine retained fixes, runs for 20 seconds at each
+300/600/900 m view (55/45/45 degrees), then freezes playback and waits for sustained tile and primitive readiness.
+It captures off/on/off/on framebuffer patches at eight distinct projected surface
+points outside the padded sprite and selection bracket. `Google 3D selected trail visible at 6 of 8 projected samples`
+prints the selected key, fix count, elapsed display time, path length, hit count,
+per-point coordinates/hits and renderer strategy. At least six points need a
+repeatably changed green core or dark backing at the same pixels. Repeated off
+and on channels and their contrast deltas must agree within 8 RGB levels;
+background refinement, overlapping samples and unchanged dark roads fail. The dark
+backing must reduce summed RGB by at least 40%, and either match needs RGB
+distance of at least 40, so a faint depth-fail wash cannot satisfy visibility. Artifacts are
+`<tag>-<altitude>m-trail-visible.jpg` and matching JSON. Run the same harness
+against the base and patched keyed builds; partial runs remain diagnostic.
+Node checks run Cesium's final geometry pipeline, including batch IDs and
+position encoding: 1,576 bytes per head subdivision and 2,014,128 bytes for the
+1,278-instance body. The body plus a separate 81,792-byte instance reserve totals
+2,095,920 bytes, below the 2 MiB body limit; the head remains below its separate
+2 KiB/frame geometry limit. Ordinary frames upload no head geometry. These are
+pipeline buffer measurements, not measured GPU time or instance-texture uploads. The same 20-second browser interval scopes
+WebGL uploads to the trail body/head, forces one body rebuild, reports head CPU
+p95/max, and gates body uploads at 2 MiB and head uploads at 2 KiB/frame.
+
 Required empty or unexercised checks fail acceptance. The passing final line is
 `HARNESS: PASS (0 unexercised)`. A `QA_SECTIONS` subset is diagnostic only and
 cannot claim full acceptance.
@@ -3415,6 +3557,7 @@ are omitted rather than framing the wrong part of the globe.
 - Build gate: `npm run build`
 - Network access: local-only by default (`HOST=localhost` in dev-fresh.sh); LAN is an explicit opt-in via `HOST=0.0.0.0` (launcher prints a key-exposure warning + LAN URL; see SECURITY.md)
 - OpenSky default mode: OAuth (`OPENSKY_AUTH_MODE=oauth`; `anon` works without credentials)
+- Setup doctor resolves `OPENSKY_AUTH_MODE` from the environment and dotenv files. Explicit `anon` and OAuth mode without a client pair report keyless anonymous access (rate-limited); a complete OAuth pair retains the existing presence-only capability wording. Basic and auto modes report the selected mode without guessing which credentials runtime will accept. The proxy's auth behavior is unchanged.
 - Google key expected in Keychain service `google-maps-api` (or `GOOGLE_MAPS_API_KEY`, or `.env`)
 - OpenSky credentials expected in Keychain service `opensky-network` (or env, or `.env`); `OPENSKY_AUTH_MODE` and `OPENSKY_CREDENTIALS_FILE` read from `.env` too
 - Optional-key precedence in `dev-fresh.sh` is uniform — explicit shell env, then `.env`, then Keychain: `OPENAI_API_KEY` (Keychain `openai-api`/`api-key` — voice + HUD summary), `AISSTREAM_API_KEY` (`aisstream-api`/`api-key` — live vessels), `CESIUM_ION_TOKEN` (`cesium-ion`/`token` — Bing stacks), `TOMTOM_API_KEY` (`tomtom-api`/`api-key` — live traffic flow), `FIRMS_MAP_KEY` (`firms-map`/`map-key` — live fires), `LL2_API_TOKEN` (`.env` only)
@@ -3673,7 +3816,8 @@ easier to meet (detection is now on more often), but does not create it.
 - Traffic runs in `sim` mode (white dots, hardcoded speeds) unless `TOMTOM_API_KEY`
   is configured (env or Keychain `tomtom-api`/`api-key`), which enables `live` mode:
   TomTom flow vector tiles via the budget-governed `/api/tomtom` proxy
-  (`.gev-cache/tomtom/`, 120 s TTL, `TOMTOM_DAILY_TILE_BUDGET` default 40k/day),
+  (`.gev-cache/tomtom/`, 120 s TTL, `TOMTOM_DAILY_TILE_BUDGET` default 6k/day,
+  sized so a 31-day month stays inside TomTom's 200K/month free allowance),
   decoded client-side (`flowTiles.js`), matched onto Overpass roads
   (`flowMatch.js`), and rendered as green/amber/red dot color + speed/density
   scaling (`trafficFlowStyle.js`); closures spawn no dots; unmatched roads stay

docs/DIRECTOR-CAMERA.md

@@ -0,0 +1,110 @@
+# Director camera directions
+
+Version 4 scene documents can name geographic anchors and describe an explicit
+camera move followed by a hold. Existing camera-pose shots still use the ordinary
+camera flight. Import, playback, Load, Replay and seek accept the new directions;
+[EDIT DETAILS](DIRECTOR-SHARING.md) captures anchors and move starts; a graphical
+path editor remains a later extension.
+
+```json
+{
+  "version": 4,
+  "scenes": [{
+    "id": "austin",
+    "title": "Across Austin",
+    "anchors": [
+      { "id": "west", "title": "West viewpoint", "lat": 30.2672,
+        "lon": -97.76, "alt": 6000, "altitudeReference": "ellipsoid" },
+      { "id": "east", "title": "East viewpoint", "lat": 30.2672,
+        "lon": -97.73, "alt": 7000, "altitudeReference": "ellipsoid" }
+    ],
+    "shots": [{
+      "id": "crossing",
+      "title": "Cross the city",
+      "durationSec": 4,
+      "holdSec": 2,
+      "camera": { "anchorId": "east", "heading": 10, "pitch": -45, "roll": 0 },
+      "move": {
+        "from": { "anchorId": "west", "heading": 350, "pitch": -45, "roll": 0 },
+        "easing": "cubic-in-out"
+      },
+      "visual": { "style": "normal" },
+      "layers": {}
+    }]
+  }]
+}
+```
+
+## One owner for each authored value
+
+An anchor is a scene-local geographic position, with a stable `id`, optional
+`title`, latitude, longitude, height and explicit altitude reference. Each scene
+accepts at most 1,024 anchors. IDs must be unique within that scene. References to
+missing anchors fail validation before replacing a project.
+
+The shot's `camera` is its destination. It can be an inline pose or an
+`anchorId` plus orientation. The optional `move.from` uses the same pose/reference
+shape. References cannot also carry inline coordinates. They do not form chains.
+Heading, pitch and roll belong to each camera pose, so two shots can look in
+different directions from the same geographic anchor. Omitted orientation uses
+heading 0, pitch −35 and roll 0 degrees.
+
+An explicit move requires `move.from`, `move.easing`, `durationSec` and `holdSec`.
+Its duration is 0.2–86,400 seconds; the hold is 0–86,400 seconds. The destination
+is not copied into another field. `linear` and `cubic-in-out` are the supported
+easings. A shot without `move` retains the existing ordinary flight, even in a
+version-4 file. Its destination may also reference an anchor.
+
+Capture continues to create ordinary camera-pose shots. Update Shot stores the
+current viewport as an inline destination, preserving an explicit move's start
+and easing; it does not change a shared anchor and thereby move other shots.
+Editing imported directions and anchors currently means editing the scene JSON.
+
+## Coordinates and altitude
+
+Latitude/longitude use WGS84 degrees. Orientation uses the application's Cesium
+heading/pitch/roll convention in degrees: heading rotates from local north,
+negative pitch looks down, and zero pitch is horizontal. Camera positions use
+meters above the WGS84 ellipsoid, matching `Cartesian3.fromDegrees` and captured
+camera poses. These heights are not mean-sea-level elevations or heights above
+the visible surface.
+
+Every anchor and every inline endpoint of an explicit move must say
+`"altitudeReference": "ellipsoid"`. Ordinary legacy poses without that field
+already use the same reference. Terrain-relative and mean-sea-level references
+are rejected; no terrain request, default ground estimate or implicit conversion
+is made. Authors must provide ellipsoidal heights with enough clearance for their
+scene. The format does not promise collision avoidance or terrain following.
+
+During an explicit move, latitude and altitude interpolate between endpoints.
+Longitude takes the shortest signed arc across the dateline; heading and roll
+also take their shortest signed arcs. An exact 180-degree tie takes the negative
+arc. This is an authored coordinate interpolation, not a geodesic or a camera
+flight with an automatically raised arc. Endpoints are exact, including zero
+pitch. Curved paths and look-at targets are later extensions.
+
+## Time, seeking and cancellation
+
+Load and Replay of an explicit move start at its authored `from` pose, regardless
+of the current viewport. Play uses that same start. Both live playback and seek
+use `sampleCameraMove`; a seek into the hold uses the exact destination. Backward
+seeks do not depend on a prior camera position. Existing scene-pack media/reveal
+rules can extend holds as before.
+
+Each active explicit move owns one animation-frame callback. Stop, replacement,
+import, teardown, a navigation handoff or manual pointer/wheel input revokes that
+callback and settles the move. Navigation also cancels a run during an authored
+hold, so the next shot cannot retake the camera. Camera claims still respect
+Cockpit's refusal. Already queued callbacks cannot move a replacement scene.
+The timing diagnostic includes the active authored camera animation.
+
+The renderer-independent `gods-eye-view/director` export provides
+`resolveCameraPose(scene, camera)`, `resolveCameraMove(scene, shot)` and
+`sampleCameraMove(move, progress)`. These expect validated/normalized data.
+Rendering and frame ownership live in `src/scenes/cameraMotion.js`; the existing
+scene controller supplies camera application and lifecycle cancellation.
+
+Version-1/2/3 projects migrate to version 4 without converting their ordinary
+shots into explicit moves. IDs, positions, durations, visual settings, packs and
+source attribution survive. The bloom scale remains independent of the document
+version; version-3 bloom is never interpreted as the older inverted scale.

docs/DIRECTOR-DATA-PACKS.md

@@ -0,0 +1,115 @@
+# Director data packs
+
+Version-5 scene documents can declare `dataPacks` on a scene and select them by
+`dataPackIds` on each shot. Import validates declarations without loading assets.
+Loading, seeking or playing a shot acquires only its selected packs. A shot with
+no pack IDs clears the preceding shot's packs. Existing scene recipes and assets
+keep their current paths, notices and behavior.
+
+A pack manifest is version 1 and requires an ID, format, source, attribution and
+placement. Sources describe storage; placement describes geography. Source names
+refer to trusted application registrations, never scripts to import. A document
+cannot supply request headers, keys, cookies, endpoints or executable handlers.
+
+```json
+{
+  "version": 5,
+  "scenes": [{
+    "id": "example",
+    "title": "My geographic notes",
+    "dataPacks": [{
+      "id": "notes",
+      "version": 1,
+      "format": "geojson",
+      "source": { "adapter": "assets", "path": "my-scene/notes.geojson" },
+      "attribution": { "text": "Your name", "license": "Your asset's actual license" },
+      "placement": { "altitudeReference": "ellipsoid" }
+    }],
+    "shots": [{
+      "id": "overview",
+      "camera": { "lat": 30.2672, "lon": -97.742, "alt": 2600, "pitch": -70 },
+      "durationSec": 4,
+      "holdSec": 2,
+      "dataPackIds": ["notes"]
+    }]
+  }]
+}
+```
+
+For the standalone application, put that asset at
+`public/scene-assets/my-scene/notes.geojson`. The registered `assets` source has
+an explicit `/scene-assets/` base on the application's origin. Importing a file
+from disk does not grant access to adjacent local files or infer a remote base.
+Relative paths cannot contain traversal, query strings, fragments, URL syntax,
+percent escapes or empty segments. Asset directories are served as static files;
+this is not a new arbitrary-URL proxy.
+
+## Formats and placement
+
+- **`geojson`:** a UTF-8 `FeatureCollection`, served as `application/geo+json` or
+  `application/json`. Each feature needs a unique string `id`. Point, LineString
+  and Polygon (including holes) are supported. Coordinates are WGS84
+  `[longitude, latitude, ellipsoidHeightMeters]`; missing height means zero,
+  which can be underground. Supply appropriate heights. Geometry properties
+  are ignored: they cannot select external icons, HTML, styling or scripts.
+  Placement is `{ "altitudeReference": "ellipsoid" }`.
+- **`image`:** PNG served as `image/png`, at most 4096×4096 pixels, checked before
+  decoding. Placement is `{ "bounds": [west, south, east, north], "height": 300,
+  "altitudeReference": "ellipsoid" }`. Bounds must increase and cannot cross
+  the dateline. The image is a horizontal geographic rectangle at that height.
+- **`media`:** MP4/WebM video or MPEG/Ogg/WAV/WebM audio, with the matching standard
+  MIME type. Placement is `{ "anchorId": "media-location" }`, referring to a
+  scene-local anchor with explicit ellipsoid height. A labelled marker locates
+  the media; an attribution card provides native, user-operated playback
+  controls. Media never autoplays. Codec support depends on the browser. D5 does
+  not synchronize media time with scene time or embed third-party players.
+
+Pack attribution always includes nonempty `text` and `license`; an optional
+HTTPS `url` opens as a source link with no opener/referrer. Importing or sharing
+an asset never changes its license. D5 adds no third-party content and preserves
+all existing Nepal content and contributor notices.
+
+Optional `byteLength` specifies the exact expected byte count; optional `sha256`
+is a lowercase hexadecimal SHA-256 digest checked before rendering. There are at
+most 8 packs per scene, 8 MiB per asset, and 32 MiB of selected assets per shot.
+GeoJSON additionally allows at most 2,000 features and 50,000 positions.
+Transforms, terrain-relative placement, terrain collision avoidance, arbitrary
+GeoJSON styles and archive extraction are not implemented. Explicit local files
+can be shared through [JSON asset bundles](DIRECTOR-SHARING.md).
+
+## Loading and resource ownership
+
+The `director` package export provides `createAssetDirectorySource` and
+`createDataPackSession`. The former receives an explicit trusted HTTP(S)
+directory `baseUrl` and optional `fetchImpl`; it confines every relative asset
+path to that directory. Cross-origin directories require CORS. Requests omit
+credentials and referrers, reject redirects, and use `cache: 'no-store'`.
+There is no persistent pack cache, offline fallback or silent substitute. A
+missing, invalid, oversized or integrity-mismatched asset fails the shot's pack
+load, removes partial results and reports a stable error without exposing a URL.
+Successful loading leaves the attribution cards visible with the assets.
+
+`createApplicationTools({ sceneDataPacks: { sources } })` and
+`new SceneDirector(viewer, style, data, { dataPacks: { sources } })` accept a
+registry of source functions. Each receives `{ path, signal, maxBytes }` and
+returns `{ bytes: Uint8Array, mimeType }`. Custom transports must honor the
+signal, bound reads and return the real MIME type. They remain application code,
+not scene document fields. Without registrations, referenced sources fail closed.
+
+The portable session receives format adapters separately. Each adapter receives
+`{ pack, asset, anchors, signal }` and returns a resource with an idempotent
+`dispose()`. Core's scene composition supplies Cesium geometry/image rendering
+and text-only attribution/native media controls. The session applies a 15-second
+load deadline and rejects late results, even when an adapter ignores abort.
+
+Stop, replacement, next-shot selection, scene release and destruction cancel
+pending work, remove owned entities/cards, stop media and revoke object URLs.
+Run completion releases packs with its run signal. Direct LOAD and seek retain
+packs until the next operation or Stop. Resources are reacquired per shot;
+there are no disabled pack refresh loops. `getDataPackState()` returns copied
+status and resource counts for lifecycle diagnostics.
+
+Run `node scripts/qa-director-packs.mjs` against a credentialed local server to
+exercise the real import/load/seek/Stop path with self-authored synthetic assets.
+See [actions](DIRECTOR-INTERACTIONS.md) and [authoring/sharing](DIRECTOR-SHARING.md)
+for the controls built on this manifest/loading boundary.

docs/DIRECTOR-INTERACTIONS.md

@@ -0,0 +1,66 @@
+# Director scene actions
+
+Version-6 scene documents can attach actions to stable GeoJSON feature IDs in a
+shot's selected data packs. Existing versions 1–5 migrate without adding actions.
+Import validates data and references; it does not load assets or execute actions.
+
+Add `interactions` to a shot, for example:
+
+```json
+{
+  "id": "read-outline",
+  "label": "About this outline",
+  "target": { "packId": "outline", "featureId": "boundary" },
+  "action": {
+    "type": "card",
+    "text": "An authored explanation, displayed as plain text.",
+    "url": "https://example.org/source"
+  }
+}
+```
+
+The target must be a feature in a GeoJSON pack selected by that shot. Points,
+lines and polygons retain stable pack/feature identities. Assets load before
+feature existence is checked; a missing feature refuses the entire action set.
+Images and native media are not interaction targets in this version.
+
+| Action | Fields | Behavior |
+| --- | --- | --- |
+| `card` | `text`, optional `url` | Show plain text and an optional HTTPS source link; never HTML |
+| `focus` | `anchorId` | Set a top-down camera pose at a scene anchor through camera ownership arbitration |
+| `shot` | `shotId` | Load another shot in the same scene at its authored start |
+| `layer` | `layerId`, boolean `enabled` | Request an explicit state through the ordinary layer admission path |
+
+There are at most 64 interactions per shot. Card text is limited to 4,096
+characters; source links cannot contain credentials, query strings or fragments.
+No script, module, arbitrary fetch endpoint or request header is accepted.
+
+Actions appear after LOAD or seek finishes. Click a pack feature to select its
+actions and focus the first button; choose a button explicitly to execute it.
+Tab traverses buttons and Enter/Space activates them. The selected buttons have
+visible outlines, and status feedback is announced to assistive technology.
+There are no global keyboard shortcuts to collide with navigation or typing.
+Drawing ownership blocks both pointer selection and action execution. Camera
+focus uses existing navigation admission, including Cockpit restrictions.
+
+Actions are inactive during automatic playback and camera travel. They do not
+introduce automatic branching or loops. A chain of user-triggered shot changes
+is limited to 64 transitions; an explicit LOAD starts a new chain. Import/Stop,
+replacement, playback and teardown remove selection, cards and picking handlers,
+and abort pending layer requests. No per-frame interaction loop runs.
+
+A layer action must name a layer with an explicit baseline in the current shot.
+A target shot must declare a baseline for every layer the departing shot can
+change. LOAD and seek reapply those baselines and clear selection. Stop cancels
+pending transitions; already completed layer changes remain visible, consistent
+with ordinary scene controls. Camera focus is an immediate anchor pose, not a
+new timeline segment; seek restores the authored camera pose. Scene JSON is not
+modified by executing an action.
+
+The portable interaction session owns action admission/cancellation. The scene
+interaction owner supplies accessible DOM and picking; pack renderers own the
+feature identities and release them with their geometry. Layer/source admission
+and camera arbitration remain with their existing owners.
+
+Author actions in scene JSON or the validated EDIT DETAILS draft.
+[Import preview and file sharing](DIRECTOR-SHARING.md) preserve those declarations. Existing content, assets, notices and contributor credit are preserved.

docs/DIRECTOR-SHARING.md

@@ -0,0 +1,96 @@
+# Director authoring and file sharing
+
+Open Scenes and select a scene and shot. Existing capture, update, playback and
+whole-project export controls remain available. Authored scene content, source
+links, assets and contributor credit are preserved.
+
+## Review imports before applying
+
+IMPORT accepts scene JSON (including older supported versions) or a
+`.gevbundle.json` asset bundle. A preview lists scenes, shots, data-pack attribution,
+configured or unavailable sources, missing layer IDs and bundled bytes. Preview
+makes no asset requests and does not change the current project. Configured
+sources do not guarantee that a file exists: ordinary assets are checked on LOAD.
+Bundle preview verifies the manifest and byte integrity; format decoding and
+geometry limits are still enforced when rendering.
+
+Apply replaces the current project after validation and playback cleanup. Export
+your current project first if you want to keep both. Cancel or Escape discards
+the staged import. A changed project invalidates an open draft rather than being
+overwritten. Invalid files leave the existing project and browser save intact.
+The programmatic `importProjectFile(file)` API still applies trusted callers'
+imports directly; the installed file chooser supplies the review step.
+
+## Edit scene details
+
+EDIT DETAILS provides validated JSON fields for:
+
+- Scene anchors and data-pack manifests.
+- The selected shot's camera, optional move, duration, hold, pack IDs and actions.
+
+Capture camera as anchor adds a named geographic position to the draft. Set move
+start to current camera creates a pose-to-pose move ending at the shot's existing
+camera; Use ordinary flight removes that explicit move. Heights are meters above
+the WGS84 ellipsoid. Apply details validates the complete project, preserves IDs,
+layer declarations and content notices, and keeps the selected shot. Cancel
+leaves the project unchanged. See [camera directions](DIRECTOR-CAMERA.md),
+[data packs](DIRECTOR-DATA-PACKS.md) and [actions](DIRECTOR-INTERACTIONS.md) for
+field definitions. This is a basic draft editor, not a node graph or path editor.
+
+## Share a selected scene
+
+SHARE SCENE exports only the selected scene. Download scene JSON preserves its
+camera, timing, layers, anchors, manifests, interactions and attribution, but
+contains no asset bytes. The recipient needs the referenced source registrations
+and files. Existing EXPORT PRESETS continues to export the entire project.
+
+For a bundle, select the declared pack files or a folder, then Download asset
+bundle. Folder paths match a manifest path either directly or after removing the
+chosen root directory. Individual filenames must be unambiguous across all pack
+sources; ambiguous or missing matches fail without downloading a partial bundle.
+Previously imported bundle files can be reused. Export never automatically fetches
+remote files or copies registered recipe media. Existing integrity declarations
+must match the files you supply.
+
+Bundles include only declared data-pack files. Registered scene content, linked
+media, map tiles and live data are not included. Source notices and licenses remain
+in the document; packaging a file does not grant permission to redistribute it.
+
+## Bundle format and limits
+
+A bundle is uncompressed JSON with these fields:
+
+```json
+{
+  "format": "gev-scene-bundle",
+  "version": 1,
+  "project": { "version": 6, "scenes": [] },
+  "assets": []
+}
+```
+
+Each asset contains `path`, `mimeType`, `base64` and lowercase hexadecimal `sha256`.
+Export copies the document and rewrites pack references to the reserved
+`scene-bundle` source, adding exact `byteLength` and `sha256`. Paths are confined
+relative names; URLs, traversal, duplicate or unreferenced assets, unknown fields,
+missing packs and mismatched hashes are rejected. Scene documents remain bounded
+at 5 MiB. A bundle allows 50 MiB of JSON, 64 files, 8 MiB per file and 32 MiB of
+asset bytes in total. Supported MIME types are JSON/GeoJSON, PNG, MP4/WebM video
+and MPEG/Ogg/WAV/WebM audio. Normal pack format and geometry checks still apply.
+There are no executable modules, request headers or credentials in the format.
+
+Imported bytes stay in memory for the current project and session. Stop releases
+rendered resources while retaining these bytes for replay. Project replacement
+or application teardown releases them. Only scene JSON is saved in browser
+storage: **reimport the bundle after reloading the app**. Missing bundle bytes
+fail explicitly, with no network fallback. This is file sharing, not a storage
+service or an offline basemap.
+
+Portable helpers are exported through `gods-eye-view/director`: `parseSceneShare`,
+`readSceneShare`, `createSceneBundle`, `createBundleAssets`, `describeSceneShare`,
+`editSceneDetails` and `selectSceneDocument`. Loading and UI remain separate owners.
+`getSharingState()` reports copied dialog/asset counts for lifecycle diagnostics.
+
+Run `node scripts/qa-director-sharing.mjs` against the local server for installed
+controls, cancellation, stale drafts, export/import round trips, resource cleanup
+and narrow-screen acceptance. Fixtures are synthetic and carry their own notices.

docs/DIRECTOR.md

@@ -0,0 +1,108 @@
+# Director: reusable scene playback
+
+Director is the scene playback system. Ordered shot execution, authored timing and playback clocks are separated
+from the scene editor and application rendering. This document
+records implemented camera directions, data packs, declarative interactions and
+file sharing, along with the remaining extensions.
+
+## Implemented boundary
+
+`src/director/playback.js`, exported as `gods-eye-view/director`, provides:
+
+- `buildPlaybackQueue(scenes, startSceneId, { single })`: ordered scenes/shots,
+  retaining the existing round-robin behavior.
+- `playSceneQueue(queue, { token, adapter, previousScene, releaseOnFinish })`:
+  sequential execution, cancellation checks and scene release.
+
+The runner imports no renderer, UI, storage, recipe or dataset. An adapter supplies
+these phases, in order: `selectShot`, `applyVisual`, `applyLayers`, `travel`,
+`settle`, `hold`, `completeShot`. Each receives `{ scene, shot, index, total,
+token }`. It also supplies `releaseScene(scene, token?)` and optionally `complete()`.
+Callbacks may return promises. Each playback invocation requires its own adapter
+state and token; the caller owns camera arbitration and concurrent-run refusal.
+
+The runner checks cancellation after each phase. Adapters must also pass the
+abort signal or liveness predicate into pending work: a check between phases
+cannot stop a camera flight or network request already in progress. Cleanup
+between scenes and on preview exit runs without an aborted token. A refused
+initial handoff starts no shot. Final cleanup runs on completion, Stop or failure;
+`releaseOnFinish: false` retains the final scene for ordinary playback. Exceptions
+propagate so the caller can restore its controls. Empty/already-cancelled queues
+acquire no resources. This low-level API expects normalized scene objects;
+untrusted file validation belongs at the import boundary.
+
+`src/scenes/playbackAdapter.js` connects this runner to the existing
+`SceneDirector`. The latter still owns editor state, saved-project import/export,
+camera ownership and asynchronous load/seek arbitration. Pure seek calculations
+live in `src/director/timeline.js`; `src/director/clock.js` owns the run/load/shot
+tickers, hold deadlines, snapshots and clock subscriptions. Stop settles pending
+holds immediately, and revoked tick callbacks cannot affect a replacement clock.
+`getPlaybackTimingState()` exposes copied snapshots and an active-timer count for
+lifecycle diagnostics without exposing timer handles.
+
+The `director` export also provides `sceneTimingForShot`, `sceneSeekState`,
+`cameraAtProgress` and `createPlaybackClock`. Timeline functions receive duration
+and hold resolvers; the clock receives timing, running-state and progress callbacks.
+They import no renderer, storage, recipe or dataset.
+
+`src/scenes/shotPresentation.js` prepares layer/seek context and resolves holds
+and map preferences through a scene-pack registry. The `scenes` export provides
+`createScenePackRegistry({ recipes, adapters })`; pass the result as `scenePacks`
+in the SceneDirector constructor options. Trusted adapters can supply
+`minimumHoldSec(states)`, `resolveVisual(shot, visual, isMapStackAvailable)` and
+`cancelMotion(getLayerModule)`. Default composition registers the existing Nepal
+presentation rules. These are code-level composition hooks, not executable
+modules imported from scene files. Existing media-owner waits remain bounded.
+
+All authored scenes, assets, IDs, source links, attribution and existing JSON
+projects are preserved. The Nepal sequence remains the contribution introduced
+by @manjunath22466 in #590. Its clips use source links/embeds; comparison images
+and river coordinates are bundled. See the
+[event pack provenance](../public/events/bhote-koshi-2026/README.md).
+
+## Next changes, in order
+
+1. **Timeline and content separation — implemented.** Pure duration/seek
+   calculations, an owned clock and registered presentation rules preserve
+   existing recipes and content. Tests cover direct load, forward/backward seek,
+   replay, bounded media waits and cancellation at pending transitions.
+2. **Versioned scene document — implemented for existing camera-pose shots.**
+   [The scene document](SCENE-DOCUMENT.md) preserves version-1/2/3 imports. Bounded validation
+   rejects malformed files before replacing current state; legacy migration
+   preserves IDs, pack bindings and visual edits. Unreadable saved files are
+   protected from fallback writes. Camera anchors, pack manifests and actions
+   receive stable IDs with their respective later format extensions.
+3. **Camera directions — implemented for pose-to-pose moves.**
+   [Version 4](DIRECTOR-CAMERA.md) adds scene-local geographic anchors, explicit
+   start/destination poses, easing, duration and holds. Playback and seek share
+   the same sampler. Ellipsoidal heights are explicit; terrain-relative input
+   is rejected. Existing shots retain ordinary flights. Basic anchor/move authoring is available through EDIT DETAILS; curved paths and
+   look-at targets remain later extensions.
+4. **Data packs and placement — implemented for bounded assets.**
+   [Version 5](DIRECTOR-DATA-PACKS.md) defines a pack manifest with format/version,
+   source, attribution/license and optional integrity/size metadata. It distinguishes
+   registered asset directories from geographic coordinates, image bounds and
+   media anchors. GeoJSON, PNG and native media adapters load with byte/time
+   limits and explicit ellipsoid heights. Stop and replacement release resources.
+   Paths resolve against a trusted directory base; missing/offline assets fail
+   explicitly. File bundles are available; transforms and terrain-relative placement
+   remain future extensions. Scene files carry no credentials or executable modules.
+5. **Declarative interactions — implemented.** [Version 6](DIRECTOR-INTERACTIONS.md)
+   connects selected feature IDs to accessible text/source cards, anchor focus,
+   shot seek and admitted layer changes. References are validated and pending
+   actions cancel on Stop, replacement or teardown. Scene files contain no
+   JavaScript or arbitrary HTML; actions require explicit user input.
+6. **Sharing and basic authoring — implemented.** [Authoring and sharing](DIRECTOR-SHARING.md)
+   adds import preview, missing-source/layer diagnostics, validated scene/shot
+   drafts and selected-scene JSON or explicit-file bundles. Pack attribution is
+   preserved. Bundle bytes last for the session and must be reimported after a
+   reload. A future node graph can author the same document without becoming a
+   playback or format requirement.
+
+Each step must preserve existing scene editing, keyboard playback, camera
+arbitration, layer cleanup, media timing and provider fallback. Acceptance includes
+portable runner tests, existing Director regressions and browser playback with
+Stop/seek/replay, plus tracking and voice checks. Use reproducible local fixtures
+for failures and cancellation, alongside live visual checks for actual content.
+
+Declarative actions are implemented in version 6; see [scene actions](DIRECTOR-INTERACTIONS.md) for supported targets, execution and reset semantics.

docs/SCENE-DOCUMENT.md

@@ -0,0 +1,105 @@
+# Scene document format
+
+Scenes exports a UTF-8 JSON project. Version 5 adds [data packs](DIRECTOR-DATA-PACKS.md)
+and is the write format. Versions 1, 2, 3, 4 and unversioned legacy files migrate on
+import without converting their existing shots into authored moves. Unknown versions or unsupported fields are rejected with
+a field path before the current project, selection or saved bytes change.
+
+```json
+{
+  "version": 5,
+  "scenes": [{
+    "id": "my-scene",
+    "title": "My scene",
+    "shots": [{
+      "id": "my-shot",
+      "title": "Arrival",
+      "durationSec": 4,
+      "holdSec": 1,
+      "camera": { "lat": 51.5, "lon": -0.12, "alt": 800,
+        "heading": 0, "pitch": -35, "roll": 0 },
+      "visual": { "style": "normal" },
+      "layers": { "traffic": { "enabled": true } }
+    }]
+  }]
+}
+```
+
+## Fields and migration
+
+The root requires `scenes` (an array, which may be empty). Optional root fields
+are `version`, `createdAt`, `updatedAt` and `installedBuiltInSceneIds` (string IDs).
+Each scene requires a `shots` array; optional fields are `id`, `title`,
+`releaseLayerIds`, `appliedShotPacks` and version-4 `anchors`. A pack marker has `id`, optional numeric
+`version` and `shotBindings` (original shot title to saved shot ID). These markers
+retain the editor's existing pack-update and rename behavior.
+
+Shots accept `id`, `title`, `durationSec`, `holdSec`, `camera`, `visual`, `layers`,
+`sourcePackId`, `sourcePackVersion` and version-4 `move`. Scene IDs are unique within the project;
+shot IDs are unique within their scene. Existing IDs and pack bindings survive
+migration. Missing IDs are generated once and persisted by the next save/export.
+Missing titles and optional camera/visual fields receive the editor's defaults.
+Empty scenes and intentionally empty projects remain empty.
+
+Camera latitude/longitude and heading/pitch/roll use degrees. Altitude uses
+meters above the WGS84 ellipsoid. Import preserves finite heights below
+100 meters and zero pitch, which previously fell through to defaults. Anchors and explicit moves require the `ellipsoid` altitude reference;
+terrain-relative inputs are rejected. See the camera contract for exact semantics.
+Flight durations retain the editor's minimum of 0.2 seconds and its 4-second
+fallback for zero; holds may be zero.
+
+Visual fields are `style`, `mapStack`, `styleParams`, `bloom`, `sharpen`, `hud`, and
+`detection`, and `scope`. Bloom has `enabled`, `intensity`, `version`; sharpen has `enabled`,
+`intensity`; HUD has `visible`, `variant`; detection has `mode`, `density`,
+`allocation`, `fadePct` and `outsideOpacityPct`. Scope has `enabled`, `featherPct`.
+The latter settings were written by Update Shot but previously lost during
+normalization; they now survive import and capture.
+Version-1/2 bloom without an explicit scale version uses the original inverted
+scale and migrates once to scale 2. The scene document and bloom scale versions
+are separate. Legacy numeric strings are accepted for numeric fields.
+
+Layer entries accept a boolean shorthand or `{ "enabled": true, "params": {} }`.
+Parameters and style parameters retain nested JSON data. They are interpreted by
+already registered components; importing a file does not fetch its URLs, register
+modules, evaluate code or apply its layers. Unsupported structural fields are
+rejected instead of silently dropping potential edits. Map-stack selection
+retains the existing registered-stack behavior.
+
+## Validation limits
+
+`gods-eye-view/director` exports `parseSceneDocument(text)`,
+`validateSceneDocument(project)`, `stringifySceneDocument(project)`,
+`SceneDocumentError`, `SCENE_DOCUMENT_VERSION` and `SCENE_DOCUMENT_LIMITS`.
+Validation is independent of the renderer, storage and recipes. Parsing checks
+UTF-8 size before JSON decoding; the file importer also checks file size before
+reading it. Migration/defaults live separately in `src/scenes/project.js`.
+
+Limits are 5 MiB, 256 scenes, 10,000 total shots, 10,000 entries per collection,
+24 levels of nesting, 200,000 visited values, 65,536 characters per JSON string,
+256 characters per field/ID, and 4,096 characters per title. Numeric values must
+be finite. Camera limits are latitude ±90, longitude ±180, altitude −12,000 to
+1 billion meters, heading/roll ±360 and pitch ±90; durations/holds are at most
+86,400 seconds. Post-processing values are bounded and normalized to the existing
+slider ranges. Object prototype keys are refused at every depth.
+
+An invalid import leaves the current project and playback untouched. A valid
+import cancels and settles pending playback before replacing the project. If
+multiple files are read concurrently, only the newest request can replace it.
+Disposal prevents a pending import from publishing.
+
+The browser storage key remains `godsEyeView.sceneProject.v2` for compatibility;
+that key's suffix is not the document version. An unreadable saved project stays
+in storage. The app supplies temporary defaults and a visible warning, but blocks
+saving over the original bytes until a valid file is explicitly imported. Export
+can preserve temporary edits. Storage writes use the same validation before replacing saved bytes; invalid
+edits and storage write failures surface an unsaved toast.
+
+Only authored project fields belong in this file. Runtime clocks, camera flights,
+loading progress and run diagnostics remain separate. Camera anchors and authored
+moves arrived in version 4; data packs follow in version 5. Declarative
+interactions remain a planned extension. No scene assets, source links, licenses or contributor attribution
+change with this document boundary.
+
+Version 5 additionally accepts scene `dataPacks` and shot `dataPackIds`, as
+defined in [data packs](DIRECTOR-DATA-PACKS.md). Version-4 camera documents
+continue to import without adding any packs.

docs/UI-OWNERSHIP.md

@@ -0,0 +1,35 @@
+# Application UI ownership
+
+`src/ui/applicationShell.js` constructs controls, connects their explicit inputs
+and coordinates shutdown. `shellFacade.js` preserves the methods used by layers,
+scene playback and voice. It delegates; new behavior belongs with its owner.
+
+| Owner | Responsibility |
+| --- | --- |
+| `navigationController.js` | Navigation generation, tracking release and camera authority |
+| `locationNavigation.js` | Destination lookup/selection, orbit, world jumps and globe-reset completion |
+| `cockpitCoordinator.js` | Cockpit entry/rollback, readouts and the single Display portal |
+| `visualSettings.js` | Effects, detection overrides, visual restoration and render-loop lifetime |
+| `panelChrome.js` | Disclosure, docking, layout and Cockpit panel restoration |
+| `aircraftDisplay.js` | Shared commercial/military 3D display preferences and controls |
+| `layerBindings.js` | Data-manager attachment, selected-tracker adoption and camera-entry listeners |
+| `displayBindings.js` | Keyboard/display subscriptions and frame-rate monitor lifetime |
+| `shareRestoration.js` | Initial share/layer restoration and cancellation |
+| `shellFeedback.js` | Loading feedback, notices and toast lifetime |
+
+Owners receive named services, elements, operations and readers. They do not
+receive the application shell itself. Readers resolve a replaceable collaborator
+at use time; operations cross an ownership boundary without copying its state.
+The facade exposes existing properties as delegates rather than duplicate state.
+
+Shutdown has two phases. First revoke input, deferred navigation, camera-entry
+listeners, lookups, timers and rendering work. Then await Context restoration,
+release sensor overrides while the manager is still attached, detach layer
+services and destroy scene resources. Late callbacks cannot acquire the camera.
+Manager replacement also releases subscriptions and the previous Directions
+module even if the replacement does not provide a Directions layer.
+
+Source-contract tests follow both sides of delegated wiring. Lifecycle tests
+exercise pending reset cancellation, stale camera callbacks, replacement and
+idempotent teardown. Browser acceptance covers the composed application, including
+share restoration, scene commands, navigation, Cockpit, display and voice.

docs/VOICE-OWNERSHIP.md

@@ -0,0 +1,48 @@
+# Realtime voice ownership
+
+`realtimeController.js` composes the session and owns its status, UI bindings and
+overall lifetime. It coordinates startup and shutdown. `realtimeFacade.js`
+preserves existing methods and properties by delegation, without copying state.
+The session adapter, action runner and backend interfaces remain unchanged.
+
+| Owner | State and responsibility |
+| --- | --- |
+| `realtimeConnection.js` | Start generation, request cancellation, peer/data channel, acquired microphone stream and playback element |
+| `realtimeTurns.js` | Active and superseded responses, pending confirmations, deduplicated calls and action cancellation |
+| `realtimeRadio.js` | Speaker ducking, prepared playback, stronger-action reservations and playback observers |
+| `realtimeInput.js` | Physical Space gesture, microphone mute, input/output meters and their frame/listener lifetime |
+| `realtimeCost.js` | Next-session preferences and the current session's model-bound meter |
+| `realtimeViewport.js` | One retained image, bounded deletion identities and capture generation |
+| `realtimeDiagnostics.js` | Bounded error history and sanitized optional diagnostics |
+
+Pure input policy, preferences and protocol-response policy have separate modules.
+Owners receive named readers, operations or focused collaborators. Cross-owner
+cancellation uses operations; response handling does not own Radio's reservations
+or viewport deletion bookkeeping.
+
+Shutdown first invalidates acquisition and action work, then closes transport,
+stops audio analysis, releases media and clears conversation/input state. Full
+removal also detaches UI, keyboard, annotation and Radio observers. Radio takeover
+retains confirmed playback through that same shutdown path. A late offer, peer callback,
+viewport capture or cancelled meter frame cannot enter a replacement session.
+Action and post-capture continuations retain their conversation identity before
+publishing output, queueing a response or changing status.
+
+Behavioral invariants remain in force: a 500 ms Space hold claims push-to-talk;
+short control taps and text entry remain native; a click-started session stays
+open-mic. Every accepted or refused tool call receives its terminal output once.
+New typed input supersedes old intent. Radio waits for the spoken confirmation and
+verified muted playback. A live cost meter stays bound to its negotiated model,
+even when the next-session preference changes.
+
+Run the unit suite and both live recorded-audio modes against a configured local
+server:
+
+```sh
+node scripts/qa-voice-wav.mjs http://localhost:4173
+node scripts/qa-voice-wav.mjs http://localhost:4173 --push-to-talk
+```
+
+The second mode uses the actual Space shortcut, verifies microphone acquisition
+and release, and checks the same globe/Radio outcome. Tracking and scene-control
+acceptance exercise voice's shared application operations separately.