benmichael/gods-eye-view
1
0 Fork 0
mirror of https://github.com/bilawalsidhu/gods-eye-view.git synced 2026-11-05 02:44:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge upstream main into feature/catalonia-cctv-cameras to resolve PR #595 conflicts

Browse Source 
Upstream added Director, Transit/GTFS-Realtime and Bhote Koshi scene work
in the same window; the only real conflict was two adjacent CHANGELOG
entries, resolved by keeping both.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
This commit is contained in:
ulihhhhandClaude Sonnet 5 committed 2026-09-16 10:34:16 +02:00
2 parents ffbe98b4ac a65d9d85f1
commit 25f90692cf
128 files changed
+18562 -6497
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CHANGELOG.md
+46 -9
View File
@@ -7,6 +7,46 @@
matching the empirically observed upstream cadence. `CCTV_CATALONIA_MAX_SOURCES`
sets the cap and `CCTV_CATALONIA_ENABLED=0` turns the pack off.
- Add Director import previews, validated scene/shot detail drafts and selected-scene
JSON or asset-bundle sharing. Preserve attribution; verify bounded bundle bytes
before admission and release staged work on cancellation or teardown.
- Director scene documents now support bounded data-pack manifests, per-shot
selection and registered GeoJSON/PNG/media loaders with explicit placement,
visible attribution and cancellation/disposal on Stop or replacement.
- Director version 4 adds named camera anchors and explicit pose-to-pose moves
with shared playback/seek interpolation, easing and holds. Navigation and
manual input cancel authored motion; older scene files retain existing flights.
- Director validates bounded version-3 scene files before replacing a project,
preserves unreadable browser saves, migrates legacy bloom once and preserves
zero-pitch/low-altitude camera and scope/detection edits. Project normalization has a separate owner.
- Separate Director timing, seek calculations, playback clocks and registered
scene-pack presentation rules. Preserve authored content and controls; Stop
releases pending hold timers and stale ticks cannot affect replacement playback.
- Keep parked transit vehicles aligned to their world course during camera orbits, fall back to reported bearing, and keep vehicles with no course consistently screen-up.
- Separate Realtime connection, response/tool, Radio, input/audio, cost, viewport
and diagnostic ownership while preserving voice controls and protocol behavior.
Revoke stale connection offers/capture callbacks and release failed or stopped audio
meters. Discard late action continuations after Stop or restart; add recorded
push-to-talk acceptance alongside click-start voice.
- Separate application-shell responsibilities and state ownership while preserving
the layer, scene and voice API. Revoke pending globe-reset callbacks on disposal
and detach old Directions services when replacing a data manager.
- Transit: keep the normal vehicle silhouettes under NVG, thermal and noir (opaque white, CRT sizing, a 2 px dark halo) instead of solid bodies; drape the selected vehicle's trail onto Google 3D tiles and terrain so retained history is actually visible, with the head clipped to the sprite and markers recovering as soon as the camera arrives; place Transit in the Movement panel between Street Traffic and Bike Share.
- Extract a portable Director shot runner and connect existing scene playback to
it. Preserve authored content, project files, camera/layer behavior and source
attribution; document the planned timeline, scene-file and data-pack boundaries.
- Separate map-feature acquisition from annotation/search selection. Move road and mapped-installation decoding into source adapters while preserving geometry policy, cancellation, retry outcomes and compatibility exports.
- Cancel hidden Nepal provider preloads on Stop, event disable and replacement, and respect drawing-tool pointer ownership for fallback evidence cards. Preserve @manjunath22466’s Nepal scene contribution and source attribution.
@@ -85,14 +125,12 @@
- Allow compatible endpoints and server-selected models through construction options.
- Cancel pending token/SDP requests on Stop or teardown and reject expired secrets.
## Configurable geospatial services
- Compose geocoding, place context and routes through independent providers.
- Allow compatible endpoint configuration without changing voice tools or annotation behavior.
- Isolate configured source caches and reject results after cancellation.
## ALPR camera locations
- Port Manjunath's (@manjunath22466) cyan camera badges, coral selection brackets,
@@ -172,6 +210,9 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
## [Unreleased]
- Add bounded Director feature actions with accessible controls, explicit camera/layer admission and cancellation; restore pack geometry on same-shot seek. Preserve existing scenes and content attribution.
- Give application request services, terrain/floor caches and annotation lookup state explicit owners and cancellation; share them across controls, layers and voice.
- Construct application layers from explicit sources, with standalone provider selection and catalog-owned aircraft classification; controls and voice queries use those instances.
@@ -322,7 +363,6 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
- Press backtick (`) to toggle a rendered-frame-rate readout beneath the logo.
Typing fields retain the key; monitoring stops when hidden.
- Extract vessel feed, store, rendering, selection, trail and card components with explicit source and scene services.
- Bound contact retention for incomplete vessel observations, preserve source freshness and refresh history references in place.
- Cancel pending vessel history during selection and layer teardown.
@@ -406,10 +446,8 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
- Bound CCTV media response headers to 15 seconds and cancel error bodies.
Cap buffered snapshot downloads at 16 MiB while streaming.
- Cancel the active location lookup when its controls are disposed.
### Fixed
- `DATA_SOURCES.md` states what the project does with camera frame content: a
@@ -460,7 +498,6 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
- GBFS rejects upstream redirects, caps streamed responses at 5 MiB, and keeps
its deadline active through body reads. Rejected downloads are cancelled.
- Split Overpass/installation search, regional briefing/weather, local voice
handlers and standalone key setup into focused modules. Preserve routes,
source behavior, tool schemas and credential restrictions.
@@ -490,7 +527,6 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
fetching, AIS records/tracks and shared request helpers; preserve existing
routes, local setup, fallback behavior and rendering.
### Added
- **Directions layer** — keyless A→B directions without a geocoder or a
@@ -534,7 +570,6 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
- Rename standalone browser startup to `src/standalone/` and add a Node-only
`gods-eye-view/build/vite` export with checked package ownership.
### Development
- The CCTV launcher and preview-server tests resolve their temporary fixture
@@ -593,7 +628,6 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
First-run QA now checks the existing attribution Escape-close/focus-return
behavior while preserving the launcher-underneath regression checks.
- Datacenter and dam factories are available through scoped package exports with
explicit context, overlay and render callbacks. The standalone app uses the
same implementation and bundled datasets.
@@ -756,6 +790,7 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
## [0.1.0] — 2026-08-31 — One-click install, keyless boot, Provider Settings
### Added
- **One-click install** via Pinokio. Keyless boot lands on a live Esri World
Imagery satellite globe with keyless terrain; OSM takes over automatically if
Esri is unreachable, and the globe continues without terrain if its source is
@@ -771,6 +806,7 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
test suite out of the box (#81 — thanks @ethanstoner).
### Changed
- README rewritten keyless-first around the provider ladder: zero keys → free
Cesium ion (eligible personal, non-commercial use) → billing-enabled Google
Maps.
@@ -780,6 +816,7 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
and say so plainly when enrichment is unavailable instead of guessing.
### Security
- Provider Settings answers only local, unproxied requests and disables itself
entirely whenever the server is shared. Public datacenter and dam datasets
omit contact-oriented fields (see the dataset READMEs).
README.md
+1 -1
View File
@@ -284,9 +284,9 @@ Fifteen layers and map sources. **Thirteen have a keyless path.** Some offer add
| 🚗 **Traffic** | Simulated vehicles on OSM roads. With TomTom, live flow speeds drive the simulation and congestion colors below ~8 km; individual vehicle positions are not live observations | TomTom + OSM | 🟢 simulation · 🟡 live flow speeds |
| 📹 **CCTV Mesh** | ~3,600 public cameras projected _into_ the 3D space — Austin · Texas (TxDOT) · California (Caltrans) · London (TfL) · Ontario (511) · Finland (Fintraffic) · British Columbia (DriveBC) · Estonia (Tallinn, Tarktee) · New South Wales (Live Traffic NSW) · Calgary. Positions are published; poses are estimated priors **you calibrate by dragging a gizmo on the camera itself** | City APIs | 🟢 |
| 📻 **Radio** | Geolocated world radio with an **analog tuner** — drag the needle across up to 750 stations and the globe flies to each broadcaster | Radio Browser / broadcasters | 🟢 |
| 🚌 **Transit** | Live buses, trams, metros, trains and ferries with delayed playback between reports, selected-vehicle trails, and mode-coloured DETECT labels — Boston, Austin, Minneapolis, Helsinki, the Netherlands, Norway, South East Queensland | Operator GTFS-Realtime feeds | 🟢 |
| 🚲 **Bikeshare** | Live station availability | GBFS | 🟢 |
| 🧭 **Directions** | Click A and B on the globe for a street-following drive, walk or cycle route draped on the terrain with turn-by-turn steps — then FLY the camera along it. No key, no geocoder, no mic | OSRM on FOSSGIS servers (OpenStreetMap) | 🟢 |
| 🚌 **Transit** | Live buses, trams, metros, trains and ferries with delayed playback between reports, selected-vehicle trails, and mode-coloured DETECT labels — Boston, Austin, Minneapolis, Helsinki, the Netherlands, Norway, South East Queensland | Operator GTFS-Realtime feeds | 🟢 |
| 🔥 **Active Fires** | Live NASA FIRMS detections, trailing 24h | NASA FIRMS | 🟡 |
| 🚀 **Space Missions** | Rolling 30-day launches with payload, stage, and recovery detail | Launch Library 2 | 🟢 (🟡 optional token raises the allowance) |
| 🎖️ **Mapped Installations** | Viewport-bounded military-site context from community mapping — incomplete by nature, and labeled that way | OpenStreetMap | 🟢 |
TESTING.md
+5
View File
@@ -237,3 +237,8 @@ FIRMS refactoring can be checked without a configured server key using
fixture mode exercises populated display, aggregation, cards, keyless and stale
responses, and selection/camera handoff. It does not establish live-source
acceptance; omit `--fixtures` with a configured FIRMS key for that check.
Director authoring and sharing acceptance: `node scripts/qa-director-sharing.mjs`
checks installed import previews, draft validation, file-bundle round trips,
cancellation, resource ownership and narrow-screen controls. Run alongside the
scene-controls, camera, pack, interaction and timing harnesses.
docs/CURRENT-STATE.md
+130 -16
View File
@@ -1,5 +1,64 @@
# God's Eye View Current State
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.
@@ -2435,9 +2494,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 + Catalonia (Servei Català de Trànsit) + 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 +2584,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 +2611,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 +2641,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 +2671,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 +2704,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 +2721,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 +2760,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.
docs/DIRECTOR-CAMERA.md
+110
View File
@@ -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
+115
View File
@@ -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
+66
View File
@@ -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
+96
View File
@@ -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
+108
View File
@@ -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
+105
View File
@@ -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
+35
View File
@@ -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
+48
View File
@@ -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.
package.json
+1
View File
@@ -142,6 +142,7 @@
"./ui/scenes": "./src/ui/scenes.js",
"./ui/shell": "./src/ui/applicationShell.js",
"./ui/styles": "./src/ui/styles.js",
"./director": "./src/director/playback.js",
"./scenes": "./src/scenes/director.js",
"./sources/live": "./src/sources/live/index.js",
"./layers/flights": "./src/layers/flights/index.js",
scripts/check-import-directions.mjs
+6 -3
View File
@@ -35,9 +35,12 @@ const portableExport = (key) =>
/^\.\/layers\/(?:flights|military|vessels)\/(?:records|ingestion)$/.test(
key,
) ||
['./voice/action-schemas', './voice/session', './data/lifecycle'].includes(
key,
);
[
'./director',
'./voice/action-schemas',
'./voice/session',
'./data/lifecycle',
].includes(key);
/** Check every runtime file, plus transitive portable/source graphs, independently of bundler reachability. */
export function checkImportDirections(root) {
scripts/format-scope.json
+19 -1
View File
@@ -181,6 +181,7 @@
"src/ui/layers.js",
"src/ui/layerPanel.js",
"src/ui/layerKeyRequirement.test.mjs",
"src/ui/layerPanel.test.mjs",
"src/ui/clearLayersControl.js",
"scripts/qa-layer-panel.mjs",
"scripts/qa-directions.mjs",
@@ -702,6 +703,7 @@
"src/layers/transit/viewport.js",
"src/layers/transit/lifecycle.test.mjs",
"scripts/qa-transit.mjs",
"scripts/qa-transit-heading.mjs",
"src/tooling/transitProvider.test.mjs",
"src/app/layers/transit.js",
"src/data/transitIcons.js",
@@ -724,7 +726,23 @@
"scripts/qa-transit-controls.mjs",
"src/tooling/transitQa.test.mjs",
"scripts/qa-transit-browser.mjs",
"scripts/qa-transit-recovery.mjs",
"scripts/format-runtime.json",
"src/tooling/transitService.test.mjs",
"src/sources/overpassFeatures.test.mjs"
"src/sources/overpassFeatures.test.mjs",
"src/director/clock.test.mjs",
"src/director/timeline.test.mjs",
"src/scenes/packs/registry.test.mjs",
"scripts/qa-director-timing.mjs",
"src/director/document.test.mjs",
"src/director/camera.test.mjs",
"src/scenes/cameraMotion.test.mjs",
"scripts/qa-director-camera.mjs",
"src/director/packs/packs.test.mjs",
"scripts/qa-director-packs.mjs",
"src/scenes/dataPacks/presentation.test.mjs",
"src/director/interactions/interactions.test.mjs",
"scripts/qa-director-interactions.mjs",
"src/director/sharing/sharing.test.mjs",
"scripts/qa-director-sharing.mjs"
]
scripts/package-boundaries.json
+127 -5
View File
@@ -504,6 +504,8 @@
"src/styles/surveillance.js",
"src/styles/thermal.js",
"src/ui/applicationShell.js",
"src/ui/locationNavigation.js",
"src/ui/cockpitCoordinator.js",
"src/ui/cameraOrientationControls.js",
"src/ui/applicationShortcuts.js",
"src/ui/cctv.js",
@@ -574,7 +576,11 @@
"src/ui/visualPresets.js",
"src/ui/visualSettings.js",
"src/worldFocus.js",
"src/data/feedState.js"
"src/data/feedState.js",
"src/ui/aircraftDisplay.js",
"src/ui/layerBindings.js",
"src/ui/displayBindings.js",
"src/ui/shellFacade.js"
],
"external": ["cesium"]
},
@@ -606,6 +612,29 @@
],
"external": []
},
"director": {
"exports": ["./director"],
"modules": [
"src/director/playback.js",
"src/director/clock.js",
"src/director/timeline.js",
"src/director/document.js",
"src/director/documentFields.js",
"src/director/cameraDocument.js",
"src/director/camera.js",
"src/director/packs/source.js",
"src/director/packs/session.js",
"src/director/packs/geojson.js",
"src/director/packs/manifest.js",
"src/director/interactions/document.js",
"src/director/interactions/session.js",
"src/director/sharing/bundle.js",
"src/director/sharing/preview.js",
"src/director/sharing/lifetime.js",
"src/director/authoring.js"
],
"external": []
},
"scenes": {
"exports": ["./scenes"],
"modules": [
@@ -615,6 +644,8 @@
"src/data/bhoteKoshiFloodPath.js",
"src/maps/catalog.js",
"src/scenes/director.js",
"src/scenes/playbackAdapter.js",
"src/director/playback.js",
"src/scenes/recipes.js",
"src/scenes/scenePolicy.js",
"src/bloom.js",
@@ -622,7 +653,36 @@
"src/ui/scenes.js",
"src/ui/sceneControls.js",
"src/ui/scenePresentation.js",
"src/contextModePolicy.js"
"src/contextModePolicy.js",
"src/director/clock.js",
"src/director/timeline.js",
"src/scenes/shotPresentation.js",
"src/scenes/packs/registry.js",
"src/scenes/packs/defaults.js",
"src/scenes/packs/nepal.js",
"src/director/document.js",
"src/scenes/project.js",
"src/director/documentFields.js",
"src/director/cameraDocument.js",
"src/director/camera.js",
"src/scenes/cameraMotion.js",
"src/director/packs/source.js",
"src/director/packs/session.js",
"src/director/packs/geojson.js",
"src/director/packs/manifest.js",
"src/scenes/dataPacks/controller.js",
"src/scenes/dataPacks/presentation.js",
"src/scenes/dataPacks/geometry.js",
"src/director/interactions/document.js",
"src/director/interactions/session.js",
"src/scenes/interactions.js",
"src/data/inputOwnership.js",
"src/director/sharing/bundle.js",
"src/director/sharing/preview.js",
"src/director/sharing/lifetime.js",
"src/director/authoring.js",
"src/scenes/sharing.js",
"src/ui/sceneSharing.js"
],
"external": ["cesium"]
},
@@ -1105,7 +1165,18 @@
"src/voice/session.js",
"src/voice/sessionCommands.js",
"src/voice/realtimeSession.js",
"src/voice/realtimeEvents.js"
"src/voice/realtimeEvents.js",
"src/voice/realtimePreferences.js",
"src/voice/realtimeProtocol.js",
"src/voice/realtimeDiagnostics.js",
"src/voice/realtimeViewport.js",
"src/voice/realtimeInputPolicy.js",
"src/voice/realtimeInput.js",
"src/voice/realtimeCost.js",
"src/voice/realtimeFacade.js",
"src/voice/realtimeRadio.js",
"src/voice/realtimeTurns.js",
"src/voice/realtimeConnection.js"
],
"external": []
},
@@ -1518,6 +1589,8 @@
"src/renderGovernor.js",
"src/rightRailPolicy.js",
"src/scenes/director.js",
"src/scenes/playbackAdapter.js",
"src/director/playback.js",
"src/scenes/recipes.js",
"src/scenes/scenePolicy.js",
"src/scopeMask.js",
@@ -1547,6 +1620,8 @@
"src/styles/surveillance.js",
"src/styles/thermal.js",
"src/ui/applicationShell.js",
"src/ui/locationNavigation.js",
"src/ui/cockpitCoordinator.js",
"src/ui/cameraOrientationControls.js",
"src/ui/applicationShortcuts.js",
"src/ui/cctv.js",
@@ -1691,7 +1766,50 @@
"src/sources/overpassFeaturesRecords.js",
"src/sources/overpassFeatures.js",
"src/sources/featureSource.js",
"src/sources/overpassRoads.js"
"src/sources/overpassRoads.js",
"src/ui/aircraftDisplay.js",
"src/ui/layerBindings.js",
"src/ui/displayBindings.js",
"src/ui/shellFacade.js",
"src/voice/realtimePreferences.js",
"src/voice/realtimeProtocol.js",
"src/voice/realtimeDiagnostics.js",
"src/voice/realtimeViewport.js",
"src/voice/realtimeInputPolicy.js",
"src/voice/realtimeInput.js",
"src/voice/realtimeCost.js",
"src/voice/realtimeFacade.js",
"src/voice/realtimeRadio.js",
"src/voice/realtimeTurns.js",
"src/voice/realtimeConnection.js",
"src/director/clock.js",
"src/director/timeline.js",
"src/scenes/shotPresentation.js",
"src/scenes/packs/registry.js",
"src/scenes/packs/defaults.js",
"src/scenes/packs/nepal.js",
"src/director/document.js",
"src/scenes/project.js",
"src/director/documentFields.js",
"src/director/cameraDocument.js",
"src/director/camera.js",
"src/scenes/cameraMotion.js",
"src/director/packs/source.js",
"src/director/packs/session.js",
"src/director/packs/geojson.js",
"src/director/packs/manifest.js",
"src/scenes/dataPacks/controller.js",
"src/scenes/dataPacks/presentation.js",
"src/scenes/dataPacks/geometry.js",
"src/director/interactions/document.js",
"src/director/interactions/session.js",
"src/scenes/interactions.js",
"src/director/sharing/bundle.js",
"src/director/sharing/preview.js",
"src/director/sharing/lifetime.js",
"src/director/authoring.js",
"src/scenes/sharing.js",
"src/ui/sceneSharing.js"
],
"external": [
"@mapbox/vector-tile",
@@ -2156,7 +2274,11 @@
},
"ui-navigation": {
"exports": ["./ui/navigation"],
"modules": ["src/navigationPolicy.js", "src/ui/navigationController.js"],
"modules": [
"src/navigationPolicy.js",
"src/ui/navigationController.js",
"src/app/stateChannel.js"
],
"external": ["cesium"]
},
"ui-share-restoration": {
scripts/qa-cockpit-utility.mjs
+3 -2
View File
@@ -2171,7 +2171,8 @@ try {
);
const resetResult = await page.evaluate(() => {
const manager = window.__godsEyeView.styleManager;
// Both the UI and compatibility facade delegate to this navigation owner.
const manager = window.__godsEyeView.styleManager._locationNavigation;
const awareness = window.__godsEyeView.dataManager.layers.get('military-awareness')?.module;
window.__qaCockpitReset = {
calls: 0,
@@ -2203,7 +2204,7 @@ try {
const awareness = gev.dataManager.layers.get('military-awareness')?.module;
const subjectId = awareness?.getContextSnapshot?.()?.subject?.id || null;
const height = gev.viewer.camera.positionCartographic?.height;
gev.styleManager.resetToGlobeView = qa.original;
gev.styleManager._locationNavigation.resetToGlobeView = qa.original;
delete window.__qaCockpitReset;
return {
calls: qa.calls,
scripts/qa-director-camera.mjs
+210
View File
@@ -0,0 +1,210 @@
#!/usr/bin/env node
/** Verify imported camera directions through real rendering and camera authority handoffs. */
import fs from 'node:fs';
import path from 'node:path';
import puppeteer from 'puppeteer';
const output = path.resolve('qa-shots/director-camera');
fs.mkdirSync(output, { recursive: true });
const browser = await puppeteer.launch({
headless: true,
args: ['--no-sandbox', '--disable-dev-shm-usage'],
});
const page = await browser.newPage();
const errors = [];
page.on('pageerror', (error) => errors.push(error.message));
let failed = 0;
function check(name, passed) {
console.log(`[${passed ? 'PASS' : 'FAIL'}] ${name}`);
if (!passed) failed++;
}
try {
await page.setViewport({ width: 1440, height: 900 });
await page.goto(
`${process.env.QA_BASE_URL || 'http://localhost:4173'}/?welcome=0`,
{ waitUntil: 'domcontentloaded' },
);
await page.waitForFunction(
() =>
window.__godsEyeView?.sceneDirector &&
document.getElementById('loading-screen')?.classList.contains('hidden'),
{ timeout: 60000 },
);
const result = await page.evaluate(async () => {
const { sceneDirector: d, styleManager: style } = window.__godsEyeView;
const file = {
version: 4,
scenes: [
{
id: 'directions',
title: 'Camera directions',
anchors: [
{
id: 'start',
title: 'Austin west',
lat: 30.2672,
lon: -97.76,
alt: 6000,
altitudeReference: 'ellipsoid',
},
{
id: 'end',
title: 'Austin east',
lat: 30.2672,
lon: -97.73,
alt: 7000,
altitudeReference: 'ellipsoid',
},
],
shots: [
{
id: 'move',
title: 'Across Austin',
durationSec: 1,
holdSec: 0.2,
camera: { anchorId: 'end', heading: 10, pitch: -45, roll: 0 },
move: {
from: { anchorId: 'start', heading: 350, pitch: -45, roll: 0 },
easing: 'linear',
},
layers: {},
visual: { style: 'normal' },
},
],
},
],
};
await d.importProjectFile(
new File([JSON.stringify(file)], 'directions.json'),
);
const scene = d._project.scenes[0];
const shot = scene.shots[0];
const imported =
scene.anchors.length === 2 && shot.camera.anchorId === 'end';
await d.seekScene(scene.id, 0.5 / 1.2);
const middle = style.getCameraState();
const seekMidpoint =
Math.abs(middle.lon - -97.745) < 1e-6 &&
Math.abs(middle.alt - 6500) < 0.01;
await d.seekScene(scene.id, 0);
const back = style.getCameraState();
const backward = Math.abs(back.lon - -97.76) < 1e-6;
const replay = await d.replayShot(scene.id, shot.id);
const end = style.getCameraState();
const replayEnd =
replay?.started &&
Math.abs(end.lon - -97.73) < 1e-6 &&
Math.abs(end.alt - 7000) < 0.01;
d.stopScene();
await d.startScene(scene.id, { single: true, preview: false });
const completed =
!d.running && d.getPlaybackTimingState().activeTimers === 0;
const settled = Math.abs(style.getCameraState().lon - -97.73) < 1e-6;
// Updating the target creates an explicit inline pose while retaining the authored start.
d.updateSelectedShot();
const saved = JSON.parse(
localStorage.getItem('godsEyeView.sceneProject.v2'),
);
const updated =
saved.scenes[0].shots[0].camera.altitudeReference === 'ellipsoid' &&
saved.scenes[0].shots[0].move.from.anchorId === 'start';
shot.durationSec = 30;
const run = d.startScene(scene.id, { single: true, preview: false });
const deadline = Date.now() + 10000;
while (!d._cameraMotion.active && Date.now() < deadline)
await new Promise((r) => setTimeout(r, 20));
const started = d._cameraMotion.active;
style.runImmediateNavigation('location', () => true);
await run;
const revoked =
started &&
!d.running &&
!d._cameraMotion.active &&
d.getPlaybackTimingState().activeTimers === 0;
const stoppedPose = style.getCameraState();
await new Promise((r) => setTimeout(r, 150));
const stable =
Math.abs(style.getCameraState().lon - stoppedPose.lon) < 1e-7;
return {
imported,
seekMidpoint,
backward,
replayEnd,
completed,
settled,
updated,
revoked,
stable,
};
});
for (const [name, passed] of Object.entries(result)) check(name, passed);
await new Promise((r) => setTimeout(r, 6000));
await page.screenshot({ path: path.join(output, 'austin.png') });
await page.evaluate(() => {
const d = window.__godsEyeView.sceneDirector;
const pose = d.styleManager.getCameraState();
d._setCameraView({ ...pose, heading: pose.heading + 25, pitch: -60 });
d.viewer.scene.requestRender();
});
await new Promise((r) => setTimeout(r, 3000));
await page.screenshot({ path: path.join(output, 'angle.png') });
const inputStarted = await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const scene = d._project.scenes[0];
window.__qaCameraRun = d.startScene(scene.id, {
single: true,
preview: false,
});
const deadline = Date.now() + 10000;
while (!d._cameraMotion.active && Date.now() < deadline)
await new Promise((r) => setTimeout(r, 20));
return d._cameraMotion.active;
});
const canvas =
(await page.$('canvas.cesium-widget-canvas')) ||
(await page.$('.cesium-widget canvas'));
const rect = await canvas.boundingBox();
await page.mouse.move(rect.x + rect.width / 2, rect.y + rect.height / 2);
await page.mouse.down();
await page.mouse.up();
const input =
inputStarted &&
(await page.evaluate(async () => {
await window.__qaCameraRun;
const d = window.__godsEyeView.sceneDirector;
return !d.running && d.getPlaybackTimingState().activeTimers === 0;
}));
check('manual canvas input revokes the move and releases clocks', input);
const hold = await page.evaluate(async () => {
const { sceneDirector: d, styleManager: style } = window.__godsEyeView;
const scene = d._project.scenes[0];
const shot = scene.shots[0];
shot.durationSec = 0.2;
shot.holdSec = 30;
const run = d.startScene(scene.id, { single: true, preview: false });
const deadline = Date.now() + 10000;
while (
(!d._activeSceneTravel || !d.running || d._cameraMotion.active) &&
Date.now() < deadline
)
await new Promise((r) => setTimeout(r, 20));
const holding = d.running && !d._cameraMotion.active;
const began = performance.now();
style.runImmediateNavigation('location', () => true);
await run;
return (
holding &&
performance.now() - began < 1000 &&
d.getPlaybackTimingState().activeTimers === 0
);
});
check('navigation during an authored hold settles immediately', hold);
if (errors.length)
console.error(
errors.map((message) => message.replace(/https?:\/\/\S+/g, '[URL]')),
);
check('no uncaught browser errors', errors.length === 0);
} finally {
await browser.close();
}
if (failed) process.exitCode = 1;
scripts/qa-director-interactions.mjs
+364
View File
@@ -0,0 +1,364 @@
#!/usr/bin/env node
/** Real pointer/keyboard acceptance using a synthetic, self-authored feature pack. */
import fs from 'node:fs';
import puppeteer from 'puppeteer';
const output = 'qa-shots/director-interactions';
fs.mkdirSync(output, { recursive: true });
const browser = await puppeteer.launch({
headless: true,
args: ['--no-sandbox', '--disable-dev-shm-usage'],
});
const page = await browser.newPage();
let failures = 0;
const errors = [];
const check = (name, ok) => {
console.log(`[${ok ? 'PASS' : 'FAIL'}] ${name}`);
if (!ok) failures++;
};
page.on('pageerror', (e) => errors.push(e.message));
await page.setRequestInterception(true);
page.on('request', (request) => {
if (new URL(request.url()).pathname === '/scene-assets/qa/actions.json')
void request
.respond({
status: 200,
contentType: 'application/geo+json',
body: JSON.stringify({
type: 'FeatureCollection',
features: [
{
type: 'Feature',
id: 'point',
geometry: { type: 'Point', coordinates: [-97.742, 30.2672, 600] },
},
],
}),
})
.catch(() => {});
else void request.continue().catch(() => {});
});
const action = (id) => `[data-director-action="${id}"]`;
const load = () =>
page.evaluate(() =>
window.__godsEyeView.sceneDirector.loadShot('interactive', 'one', {
flyDuration: 0.2,
}),
);
try {
await page.setViewport({ width: 1440, height: 900 });
await page.goto(
`${process.env.QA_BASE_URL || 'http://localhost:4173'}/?welcome=0`,
{ waitUntil: 'domcontentloaded' },
);
await page.waitForFunction(
() =>
window.__godsEyeView?.sceneDirector &&
document.getElementById('loading-screen')?.classList.contains('hidden'),
{ timeout: 60000 },
);
await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const camera = {
lat: 30.2672,
lon: -97.742,
alt: 4000,
heading: 0,
pitch: -90,
roll: 0,
altitudeReference: 'ellipsoid',
};
const target = { packId: 'data', featureId: 'point' };
const interaction = (id, label, action) => ({ id, label, target, action });
window.__interactionProject = {
version: 6,
scenes: [
{
id: 'interactive',
title: 'Interactive fixture',
anchors: [
{
id: 'view',
lat: 30.27,
lon: -97.74,
alt: 5000,
altitudeReference: 'ellipsoid',
},
],
dataPacks: [
{
id: 'data',
version: 1,
format: 'geojson',
source: { adapter: 'assets', path: 'qa/actions.json' },
attribution: { text: 'Synthetic fixture', license: 'CC0-1.0' },
placement: { altitudeReference: 'ellipsoid' },
},
],
shots: [
{
id: 'one',
title: 'Choose an action',
camera,
durationSec: 0.2,
holdSec: 0,
move: {
from: { ...camera, alt: 4100, altitudeReference: 'ellipsoid' },
easing: 'linear',
},
visual: { style: 'normal', mapStack: 'photoreal' },
layers: { traffic: false },
dataPackIds: ['data'],
interactions: [
interaction('card', 'Read source', {
type: 'card',
text: '<b>Plain text only</b>',
url: 'https://example.org/source',
}),
interaction('focus', 'Focus anchor', {
type: 'focus',
anchorId: 'view',
}),
interaction('layer', 'Show traffic', {
type: 'layer',
layerId: 'traffic',
enabled: true,
}),
interaction('next', 'Next shot', {
type: 'shot',
shotId: 'two',
}),
],
},
{
id: 'two',
title: 'Next',
camera: { ...camera, heading: 30 },
durationSec: 0.2,
holdSec: 0,
layers: { traffic: false },
},
],
},
],
};
await d.importProjectFile(
new File([JSON.stringify(window.__interactionProject)], 'actions.json'),
);
});
check(
'import installs no action handlers or UI',
await page.evaluate(
() =>
!window.__godsEyeView.sceneDirector.getInteractionState().active &&
!document.querySelector('[data-director-interactions]'),
),
);
await load();
check(
'settled LOAD activates four actions',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getInteractionState().count === 4,
),
);
await page.waitForFunction(
() => window.__godsEyeView.tileset?.tilesLoaded === true,
{ timeout: 60000 },
);
await new Promise((r) => setTimeout(r, 2000));
const point = await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const entity = d.viewer.entities.values.find(
(e) => e.name === 'data / point',
);
const pos = entity.position.getValue(d.viewer.clock.currentTime);
const screen = d.viewer.scene.cartesianToCanvasCoordinates(pos);
const rect = d.viewer.scene.canvas.getBoundingClientRect();
return { x: screen.x + rect.left, y: screen.y + rect.top };
});
await page.mouse.click(point.x, point.y);
check(
'real globe pick selects the feature and focuses its keyboard action',
await page.evaluate(
() =>
document.activeElement?.dataset.directorAction === 'card' &&
document
.querySelector('[data-director-interactions] [role=status]')
.textContent.includes('point'),
),
);
await page.keyboard.press('Enter');
check(
'Enter shows literal text and a safe source link',
await page.evaluate(() => {
const card = document.querySelector('[data-director-action-card]');
return (
card?.textContent.includes('<b>Plain text only</b>') &&
!card.querySelector('b') &&
card.querySelector('a')?.rel === 'noopener noreferrer'
);
}),
);
await page.screenshot({ path: `${output}/selected.png` });
fs.writeFileSync(
`${output}/report.json`,
JSON.stringify(
await page.evaluate(() => ({
tilesSettled: window.__godsEyeView.tileset?.tilesLoaded === true,
})),
null,
2,
),
);
await page.keyboard.press('Tab');
await page.keyboard.press('Space');
check(
'Tab/Space focuses the authored anchor through camera ownership',
await page.evaluate(
() =>
Math.abs(
window.__godsEyeView.sceneDirector.viewer.camera.positionCartographic
.height - 5000,
) < 1,
),
);
await page.screenshot({ path: `${output}/anchor.png` });
const sourceBase = process.env.QA_SOURCE_BASE || '/src';
// Resolve ownership from the same module graph as the active application.
await page.evaluate(async (base) => {
window.__inputOwner = await import(`${base}/data/inputOwnership.js`);
window.__lease = window.__inputOwner.claimPointer('qa-draw');
}, sourceBase);
await page.click(action('card'));
check(
'drawing ownership refuses actions',
await page.evaluate(() =>
document
.querySelector('[data-director-interactions] [role=status]')
.textContent.includes('unavailable'),
),
);
await page.evaluate(() => window.__inputOwner.releasePointer(window.__lease));
// Hold the actual manager admission call to exercise Stop before an enable settles.
await page.evaluate(() => {
const d = window.__godsEyeView.sceneDirector,
m = d.dataManager;
window.__originalEnable = m.setEnabled;
m.setEnabled = function (id, enabled, options) {
if (id !== 'traffic' || !enabled)
return window.__originalEnable.call(this, id, enabled, options);
window.__actionSignal = options.signal;
return new Promise((resolve) => {
window.__lateAction = () => resolve(true);
options.signal.addEventListener('abort', () => resolve(false), {
once: true,
});
});
};
});
await page.click(action('layer'));
await page.waitForFunction(() => window.__actionSignal);
await page.evaluate(() => window.__godsEyeView.sceneDirector.stopScene());
check(
'Stop aborts pending layer admission and removes handlers/cards/selection',
await page.evaluate(
() =>
window.__actionSignal.aborted &&
!window.__godsEyeView.sceneDirector.getInteractionState().active &&
!document.querySelector('[data-director-interactions]'),
),
);
await page.evaluate(() => {
window.__lateAction();
window.__godsEyeView.sceneDirector.dataManager.setEnabled =
window.__originalEnable;
});
await load();
await page.evaluate(() =>
window.__godsEyeView.sceneDirector.seekScene('interactive', 0.1),
);
check(
'same-shot seek restores pack geometry and resets action state',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getInteractionState().count === 4 &&
window.__godsEyeView.sceneDirector.getInteractionState().selected ===
null &&
window.__godsEyeView.sceneDirector.getDataPackState().count === 1,
),
);
await page.evaluate(() => {
window.__oldActionButton = document.querySelector(
'[data-director-action=card]',
);
});
await page.click(action('next'));
await page.waitForFunction(
() => window.__godsEyeView.sceneDirector._selectedShotId === 'two',
);
check(
'explicit shot transition replaces resources and removes actions',
await page.evaluate(
() =>
!window.__godsEyeView.sceneDirector.getInteractionState().active &&
window.__godsEyeView.sceneDirector.getDataPackState().count === 0,
),
);
await load();
await page.evaluate(() => window.__oldActionButton.click());
check(
'detached buttons cannot invoke replacement actions with the same ID',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getInteractionState().selected ===
null &&
!document.querySelector('[data-director-action-card]').textContent,
),
);
await page.evaluate(() => {
window.__godsEyeView.sceneDirector._interactionTransitions = 64;
});
await page.click(action('next'));
check(
'bounded transition chain cannot take another branch',
await page.evaluate(
() => window.__godsEyeView.sceneDirector._selectedShotId === 'one',
),
);
await load();
await page.evaluate(async () => {
const p = structuredClone(window.__interactionProject);
p.scenes[0].shots[0].interactions[0].target.featureId = 'missing';
const d = window.__godsEyeView.sceneDirector;
await d.importProjectFile(new File([JSON.stringify(p)], 'missing.json'));
await d.loadShot('interactive', 'one', { flyDuration: 0.2 });
});
check(
'unknown loaded feature refuses the whole action set',
await page.evaluate(
() =>
!window.__godsEyeView.sceneDirector.getInteractionState().active &&
!document.querySelector('[data-director-interactions]'),
),
);
await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
await d.importProjectFile(
new File([JSON.stringify(window.__interactionProject)], 'restore.json'),
);
await d.loadShot('interactive', 'one', { flyDuration: 0.2 });
await d.destroy();
});
check(
'teardown releases interactive resources',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getInteractionState().count === 0 &&
!document.querySelector('[data-director-interactions]'),
),
);
check('no uncaught browser errors', errors.length === 0);
} finally {
await browser.close();
}
process.exitCode = failures ? 1 : 0;
scripts/qa-director-packs.mjs
+359
View File
@@ -0,0 +1,359 @@
#!/usr/bin/env node
/** Synthetic, self-authored assets exercise import, rendering and pack resource lifetime. */
import fs from 'node:fs';
import path from 'node:path';
import puppeteer from 'puppeteer';
import sharp from 'sharp';
const output = path.resolve('qa-shots/director-packs');
fs.mkdirSync(output, { recursive: true });
const png = await sharp({
create: {
width: 64,
height: 64,
channels: 4,
background: { r: 255, g: 80, b: 30, alpha: 0.65 },
},
})
.png()
.toBuffer();
const wav = Buffer.alloc(44 + 16000);
wav.write('RIFF');
wav.writeUInt32LE(wav.length - 8, 4);
wav.write('WAVEfmt ', 8);
wav.writeUInt32LE(16, 16);
wav.writeUInt16LE(1, 20);
wav.writeUInt16LE(1, 22);
wav.writeUInt32LE(8000, 24);
wav.writeUInt32LE(16000, 28);
wav.writeUInt16LE(2, 32);
wav.writeUInt16LE(16, 34);
wav.write('data', 36);
wav.writeUInt32LE(16000, 40);
const geojson = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
id: 'point',
geometry: { type: 'Point', coordinates: [-97.742, 30.27, 450] },
},
{
type: 'Feature',
id: 'line',
geometry: {
type: 'LineString',
coordinates: [
[-97.745, 30.268, 400],
[-97.735, 30.268, 400],
],
},
},
{
type: 'Feature',
id: 'polygon',
geometry: {
type: 'Polygon',
coordinates: [
[
[-97.746, 30.265, 300],
[-97.74, 30.265, 300],
[-97.74, 30.267, 300],
[-97.746, 30.265, 300],
],
],
},
},
],
};
const browser = await puppeteer.launch({
headless: true,
args: ['--no-sandbox', '--disable-dev-shm-usage'],
});
const page = await browser.newPage();
const errors = [],
requests = [];
let pending,
failures = 0;
const check = (name, passed) => {
console.log(`[${passed ? 'PASS' : 'FAIL'}] ${name}`);
if (!passed) failures++;
};
page.on('pageerror', (e) => errors.push(e.message));
await page.setRequestInterception(true);
page.on('request', (request) => {
const url = new URL(request.url());
if (!url.pathname.startsWith('/scene-assets/'))
return void request.continue();
requests.push(url.pathname);
if (url.pathname.endsWith('/slow.json')) {
pending = request;
return;
}
const reply = url.pathname.endsWith('/outline.json')
? { contentType: 'application/geo+json', body: JSON.stringify(geojson) }
: url.pathname.endsWith('/image.png')
? { contentType: 'image/png', body: png }
: url.pathname.endsWith('/audio.wav')
? { contentType: 'audio/wav', body: wav }
: { status: 404, body: 'missing' };
void request.respond(reply).catch(() => {});
});
try {
await page.setViewport({ width: 1440, height: 900 });
await page.goto(
`${process.env.QA_BASE_URL || 'http://localhost:4173'}/?welcome=0`,
{ waitUntil: 'domcontentloaded' },
);
await page.waitForFunction(
() =>
window.__godsEyeView?.sceneDirector &&
document.getElementById('loading-screen')?.classList.contains('hidden'),
{ timeout: 60000 },
);
await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const manifest = (id, format, file, placement) => ({
id,
version: 1,
format,
source: { adapter: 'assets', path: `qa/${file}` },
attribution: { text: 'Synthetic QA fixture', license: 'CC0-1.0' },
placement,
});
const camera = {
lat: 30.2672,
lon: -97.742,
alt: 4000,
heading: 0,
pitch: -90,
roll: 0,
};
const project = {
version: 5,
scenes: [
{
id: 'packs',
title: 'Data packs QA',
anchors: [
{
id: 'media',
lat: 30.269,
lon: -97.737,
alt: 450,
altitudeReference: 'ellipsoid',
},
],
dataPacks: [
manifest('outline', 'geojson', 'outline.json', {
altitudeReference: 'ellipsoid',
}),
manifest('image', 'image', 'image.png', {
bounds: [-97.738, 30.264, -97.732, 30.267],
height: 300,
altitudeReference: 'ellipsoid',
}),
manifest('media', 'media', 'audio.wav', { anchorId: 'media' }),
manifest('slow', 'geojson', 'slow.json', {
altitudeReference: 'ellipsoid',
}),
manifest('missing', 'geojson', 'missing.json', {
altitudeReference: 'ellipsoid',
}),
],
shots: ['all', 'empty', 'slow', 'missing'].map((id) => ({
id,
title: id,
camera,
durationSec: 0.3,
holdSec: 0.2,
visual: { style: 'normal', mapStack: 'photoreal' },
layers: {},
dataPackIds:
id === 'all'
? ['outline', 'image', 'media']
: id === 'empty'
? []
: [id],
})),
},
],
};
await d.importProjectFile(
new File([JSON.stringify(project)], 'packs.json'),
);
window.__packBaseline = d.viewer.entities.values.length;
window.__packPrimitiveBaseline = d.viewer.scene.primitives.length;
window.__packRevoked = [];
const revoke = URL.revokeObjectURL.bind(URL);
URL.revokeObjectURL = (url) => {
window.__packRevoked.push(url);
revoke(url);
};
});
check('import does not acquire unselected assets', requests.length === 0);
const loaded = await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const result = await d.loadShot('packs', 'all', { flyDuration: 0.3 });
window.__packMaterials = Array.from(
{
length:
d.viewer.scene.primitives.length - window.__packPrimitiveBaseline,
},
(_, i) =>
d.viewer.scene.primitives.get(window.__packPrimitiveBaseline + i)
.appearance?.material,
).filter(Boolean);
return {
started: result?.started,
state: d.getDataPackState(),
count: d.viewer.entities.values.length - window.__packBaseline,
primitives:
d.viewer.scene.primitives.length - window.__packPrimitiveBaseline,
cards: document.querySelectorAll('[data-director-pack]').length,
paused: document.querySelector('[data-director-pack] audio')?.paused,
};
});
check(
'GeoJSON, PNG and media load only through registered sources',
loaded.started && loaded.state.count === 3 && requests.length === 3,
);
check(
'geometry and image batches plus anchored markers render separately',
loaded.count === 2 && loaded.primitives === 3,
);
check(
'attribution is visible and media does not autoplay',
loaded.cards === 3 && loaded.paused === true,
);
await page.waitForFunction(
() => window.__godsEyeView.mapStackController.getActiveId() === 'photoreal',
{ timeout: 15000 },
);
await new Promise((r) => setTimeout(r, 5000));
await page.waitForFunction(
() => window.__godsEyeView.tileset?.tilesLoaded === true,
{ timeout: 60000 },
);
const evidence = await page.evaluate(() => ({
mapStack: window.__godsEyeView.mapStackController.getActiveId(),
tilesSettled: window.__godsEyeView.tileset?.tilesLoaded === true,
}));
fs.writeFileSync(
path.join(output, 'report.json'),
JSON.stringify(evidence, null, 2),
);
check(
'static geometry is ready before visual acceptance',
await page.evaluate(() => {
const primitives = window.__godsEyeView.viewer.scene.primitives;
return Array.from(
{ length: primitives.length - window.__packPrimitiveBaseline },
(_, i) => primitives.get(window.__packPrimitiveBaseline + i),
).every((p) => p.ready !== false);
}),
);
await page.screenshot({ path: path.join(output, 'packs.png') });
await page.evaluate(() => {
const d = window.__godsEyeView.sceneDirector;
d._setCameraView({
...d.styleManager.getCameraState(),
heading: 30,
pitch: -85,
});
});
await page.waitForFunction(
() => window.__godsEyeView.tileset?.tilesLoaded === true,
{ timeout: 60000 },
);
await new Promise((r) => setTimeout(r, 2000));
await page.screenshot({ path: path.join(output, 'angle.png') });
const life = await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const media = document.querySelector('[data-director-pack] audio');
await media.play();
const played = !media.paused;
await d.loadShot('packs', 'empty', { flyDuration: 0.3 });
const cleared =
d.getDataPackState().count === 0 &&
!document.querySelector('[data-director-packs]') &&
d.viewer.entities.values.length === window.__packBaseline &&
d.viewer.scene.primitives.length === window.__packPrimitiveBaseline &&
media.paused &&
!media.getAttribute('src') &&
window.__packRevoked.length === 2 &&
window.__packMaterials.length === 1 &&
window.__packMaterials.every((material) => material.isDestroyed());
await d.seekScene('packs', 0.1);
const seek = d.getDataPackState().count === 3;
d.stopScene();
const stopped =
d.getDataPackState().count === 0 &&
d.viewer.entities.values.length === window.__packBaseline;
const missing = await d.loadShot('packs', 'missing', { flyDuration: 0.3 });
return {
played,
cleared,
seek,
stopped,
missing: missing?.started === false && d.getDataPackState().count === 0,
};
});
for (const [name, passed] of Object.entries(life)) check(name, passed);
await page.evaluate(() => {
window.__pendingPack = window.__godsEyeView.sceneDirector.loadShot(
'packs',
'slow',
);
});
const deadline = Date.now() + 15000;
while (!pending && Date.now() < deadline)
await new Promise((r) => setTimeout(r, 50));
check('pending transport reached', !!pending);
const cancelled = await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const start = performance.now();
d.stopScene();
await window.__pendingPack;
return performance.now() - start < 1000 && d.getDataPackState().count === 0;
});
check('Stop promptly settles a pending transport', cancelled);
if (pending)
await pending
.respond({
contentType: 'application/json',
body: JSON.stringify(geojson),
})
.catch(() => {});
check(
'late response cannot reintroduce entities',
await page.evaluate(
() =>
window.__godsEyeView.viewer.entities.values.length ===
window.__packBaseline &&
window.__godsEyeView.viewer.scene.primitives.length ===
window.__packPrimitiveBaseline,
),
);
await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
await d.loadShot('packs', 'all', { flyDuration: 0.3 });
await d.importProjectFile(
new File([JSON.stringify({ version: 5, scenes: [] })], 'empty.json'),
);
});
check(
'replacement import clears every pack resource',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getDataPackState().count === 0 &&
!document.querySelector('[data-director-packs]'),
),
);
check('no uncaught browser errors', errors.length === 0);
if (errors.length)
console.error(errors.map((e) => e.replace(/https?:\/\/\S+/g, '[URL]')));
} finally {
await browser.close();
}
if (failures) process.exitCode = 1;
scripts/qa-director-sharing.mjs
+482
View File
@@ -0,0 +1,482 @@
#!/usr/bin/env node
/** Sharing/authoring acceptance with local synthetic assets and real installed controls. */
import fs from 'node:fs';
import path from 'node:path';
import puppeteer from 'puppeteer';
const output = path.resolve('qa-shots/director-sharing');
fs.mkdirSync(output, { recursive: true });
const geometry = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
id: 'point',
geometry: { type: 'Point', coordinates: [-97.742, 30.2672, 500] },
},
],
};
fs.writeFileSync(path.join(output, 'data.geojson'), JSON.stringify(geometry));
const camera = {
lat: 30.2672,
lon: -97.742,
alt: 4000,
heading: 0,
pitch: -90,
roll: 0,
};
const project = {
version: 6,
scenes: [
{
id: 'share',
title: 'Sharing fixture',
dataPacks: [
{
id: 'data',
version: 1,
format: 'geojson',
source: { adapter: 'assets', path: 'example/data.geojson' },
attribution: { text: 'Synthetic <b>fixture</b>', license: 'CC0-1.0' },
placement: { altitudeReference: 'ellipsoid' },
},
],
shots: [
{
id: 'shot',
title: 'First',
camera,
durationSec: 0.3,
holdSec: 0,
visual: { style: 'normal', mapStack: 'photoreal' },
layers: {},
dataPackIds: ['data'],
interactions: [
{
id: 'info',
label: 'Read fixture',
target: { packId: 'data', featureId: 'point' },
action: { type: 'card', text: 'Synthetic scene note' },
},
],
},
],
},
{ id: 'second', title: 'Other scene', shots: [] },
],
};
const file = path.join(output, 'project.json');
fs.writeFileSync(file, JSON.stringify(project));
const browser = await puppeteer.launch({
headless: true,
args: ['--no-sandbox', '--disable-dev-shm-usage'],
});
const page = await browser.newPage();
let failures = 0;
const errors = [],
requests = [];
const check = (name, ok) => {
console.log(`[${ok ? 'PASS' : 'FAIL'}] ${name}`);
if (!ok) failures++;
};
page.on('pageerror', (e) => errors.push(e.message));
page.on('request', (r) => {
if (new URL(r.url()).pathname.startsWith('/scene-assets/'))
requests.push(r.url());
});
async function click(label) {
const handle = await page.evaluateHandle(
(label) =>
[...document.querySelectorAll('button')].find(
(b) => b.textContent === label,
),
label,
);
await handle.asElement().click();
await handle.dispose();
}
async function value(label, text) {
await page.$eval(
`[aria-label="${label}"]`,
(node, text) => {
node.value = text;
node.dispatchEvent(new Event('input', { bubbles: true }));
},
text,
);
}
try {
await page.setViewport({ width: 1440, height: 900 });
await page.goto(
`${process.env.QA_BASE_URL || 'http://localhost:4173'}/?welcome=0`,
{ waitUntil: 'domcontentloaded' },
);
await page.waitForFunction(
() =>
window.__godsEyeView?.sceneDirector &&
document.getElementById('loading-screen')?.classList.contains('hidden'),
{ timeout: 60000 },
);
await page.click('[data-collapse-target="scene-panel"]');
const before = await page.evaluate(() =>
JSON.stringify(window.__godsEyeView.sceneDirector._project),
);
const input = await page.$('#scene-import-file');
await input.uploadFile(file);
await page.waitForSelector('[data-director-apply-import]');
check(
'preview parses metadata without acquiring assets or replacing the current project',
requests.length === 0 &&
(await page.evaluate(
(before) =>
JSON.stringify(window.__godsEyeView.sceneDirector._project) ===
before,
before,
)),
);
check(
'preview renders author attribution as literal text',
await page.evaluate(
() =>
document
.querySelector('[data-director-dialog]')
.textContent.includes('Synthetic <b>fixture</b>') &&
!document.querySelector('[data-director-dialog] b'),
),
);
await page.keyboard.press('Escape');
check(
'Escape cancels preview without altering saved work',
await page.evaluate(
(before) =>
!document.querySelector('[data-director-dialog]') &&
JSON.stringify(window.__godsEyeView.sceneDirector._project) === before,
before,
),
);
await input.uploadFile(file);
await page.waitForSelector('[data-director-apply-import]');
await page.click('[data-director-apply-import]');
await page.waitForFunction(
() => !document.querySelector('[data-director-dialog]'),
);
check(
'Apply import replaces metadata but does not start playback or fetch a pack',
requests.length === 0 &&
(await page.evaluate(
() =>
window.__godsEyeView.sceneDirector._project.scenes.length === 2 &&
!window.__godsEyeView.sceneDirector.running,
)),
);
await click('EDIT DETAILS');
await click('Capture camera as anchor');
await page.waitForFunction(() =>
document
.querySelector('[data-director-dialog] [role=status]')
.textContent.includes('Anchor added'),
);
await click('Set move start to current camera');
await page.waitForFunction(() =>
document
.querySelector('[data-director-dialog] [role=status]')
.textContent.includes('Move added'),
);
const draft = await page.$eval(
'[aria-label="Shot camera, timing, packs and actions"]',
(n) => n.value,
);
const bad = JSON.parse(draft);
bad.camera.lat = 91;
await value('Shot camera, timing, packs and actions', JSON.stringify(bad));
const saved = await page.evaluate(() =>
localStorage.getItem('godsEyeView.sceneProject.v2'),
);
await page.click('[data-director-apply-details]');
await page.waitForFunction(() =>
document
.querySelector('[data-director-dialog] [role=status]')
.textContent.includes('camera.lat'),
);
check(
'invalid draft preserves saved bytes and existing authored content',
await page.evaluate(
(saved) => localStorage.getItem('godsEyeView.sceneProject.v2') === saved,
saved,
),
);
await value('Shot camera, timing, packs and actions', draft);
await page.click('[data-director-apply-details]');
await page.waitForFunction(
() => !document.querySelector('[data-director-dialog]'),
);
check(
'author controls preserve selected shot, pack attribution and action definitions',
await page.evaluate(() => {
const d = window.__godsEyeView.sceneDirector,
s = d._getSelectedScene();
return (
d._selectedShotId === 'shot' &&
s.anchors.length === 1 &&
s.shots[0].move.easing === 'cubic-in-out' &&
s.shots[0].interactions.length === 1 &&
s.dataPacks[0].attribution.license === 'CC0-1.0'
);
}),
);
await page.evaluate(() => {
window.__shareExports = [];
const create = URL.createObjectURL.bind(URL);
URL.createObjectURL = (blob) => {
if (blob.type === 'application/json')
window.__shareExports.push(blob.text());
return create(blob);
};
});
await click('SHARE SCENE');
await click('Download scene JSON');
const exported = await page.evaluate(async () =>
JSON.parse(await window.__shareExports.at(-1)),
);
check(
'scene JSON exports only the selected scene and keeps its credit',
exported.scenes.length === 1 &&
exported.scenes[0].dataPacks[0].attribution.license === 'CC0-1.0',
);
await click('Download asset bundle');
await page.waitForFunction(() =>
document
.querySelector('[data-director-dialog] [role=status]')
.textContent.includes('Could not complete'),
);
check(
'missing explicit files produce no partial download or network fallback',
requests.length === 0 &&
(await page.evaluate(() => window.__shareExports.length === 1)),
);
const files = await page.$('[aria-label="Choose data-pack files"]');
await files.uploadFile(path.join(output, 'data.geojson'));
await click('Download asset bundle');
await page.waitForFunction(
() =>
document.querySelector('[data-director-dialog] [role=status]')
.textContent === 'Asset bundle downloaded',
);
const bundle = await page.evaluate(
async () => await window.__shareExports.at(-1),
);
const bundleFile = path.join(output, 'scene.gevbundle.json');
fs.writeFileSync(bundleFile, bundle);
check(
'bundle contains the selected bytes and preserves attribution',
JSON.parse(bundle).assets.length === 1 &&
JSON.parse(bundle).project.scenes[0].dataPacks[0].attribution.license ===
'CC0-1.0',
);
await page.keyboard.press('Escape');
await input.uploadFile(bundleFile);
await page.waitForSelector('[data-director-apply-import]');
check(
'bundle preview verifies bytes and explains session-only storage',
await page.evaluate(
() =>
document
.querySelector('[data-director-dialog]')
.textContent.includes('bundled bytes verified') &&
window.__godsEyeView.sceneDirector.getSharingState().assets.count === 0,
),
);
await page.screenshot({ path: path.join(output, 'preview.png') });
await page.click('[data-director-apply-import]');
await page.waitForFunction(
() => !document.querySelector('[data-director-dialog]'),
);
await page.evaluate(() =>
window.__godsEyeView.sceneDirector.loadShot('share', 'shot', {
flyDuration: 0.3,
}),
);
check(
'imported bundle renders and enables feature actions with zero asset requests',
requests.length === 0 &&
(await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getDataPackState().count === 1 &&
window.__godsEyeView.sceneDirector.getInteractionState().count === 1,
)),
);
await page.waitForFunction(
() => window.__godsEyeView.tileset?.tilesLoaded === true,
{ timeout: 60000 },
);
await page.screenshot({ path: path.join(output, 'rendered.png') });
fs.writeFileSync(
path.join(output, 'report.json'),
JSON.stringify(
await page.evaluate(() => ({
tilesSettled: window.__godsEyeView.tileset?.tilesLoaded === true,
})),
),
);
await page.evaluate(() => window.__godsEyeView.sceneDirector.stopScene());
check(
'Stop releases rendered resources while retaining reusable project bytes',
await page.evaluate(() => {
const d = window.__godsEyeView.sceneDirector;
return (
d.getDataPackState().count === 0 &&
d.getSharingState().assets.count === 1
);
}),
);
await page.evaluate(() =>
window.__godsEyeView.sceneDirector.seekScene('share', 0),
);
check(
'seek reloads the bundle without a network fallback',
requests.length === 0 &&
(await page.evaluate(
() => window.__godsEyeView.sceneDirector.getDataPackState().count === 1,
)),
);
await click('EDIT DETAILS');
await page.evaluate(() => {
window.__godsEyeView.sceneDirector._project.scenes[0].title = 'Newer edit';
});
await page.click('[data-director-apply-details]');
check(
'stale author draft cannot overwrite a newer edit',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector._project.scenes[0].title ===
'Newer edit',
),
);
await page.keyboard.press('Escape');
await click('SHARE SCENE');
await page.setViewport({ width: 390, height: 844 });
check(
'modal remains within a narrow viewport',
await page.$eval('[data-director-dialog]', (n) => {
const r = n.getBoundingClientRect();
return (
r.left >= 0 &&
r.right <= innerWidth &&
r.top >= 0 &&
r.bottom <= innerHeight
);
}),
);
await page.screenshot({ path: path.join(output, 'narrow.png') });
await page.keyboard.press('Escape');
const pending = await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
let finish;
const work = d._sharing.preview({
name: 'pending.json',
text: () => new Promise((r) => (finish = r)),
});
d._sharing.close();
await work;
finish(JSON.stringify({ version: 6, scenes: [] }));
return !d.getSharingState().open;
});
check(
'cancel settles a pending file read and suppresses its late completion',
pending,
);
const cancelledApply = await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const before = JSON.stringify(d._project);
const saved = JSON.stringify({ ...localStorage });
let finish;
const pendingWork = new Promise((resolve) => (finish = resolve));
d._pendingWork.add(pendingWork);
const owner = new AbortController();
const work = d.importProjectFile(
{ name: 'cancelled.json' },
{
prepared: { project: { version: 6, scenes: [] }, assets: new Map() },
expectedProject: JSON.stringify(d._project, null, 2),
signal: owner.signal,
},
);
owner.abort();
finish();
const applied = await work;
d._pendingWork.delete(pendingWork);
return (
applied === false &&
JSON.stringify(d._project) === before &&
JSON.stringify({ ...localStorage }) === saved &&
d.getSharingState().assets.count === 1
);
});
check(
'cancelling Apply during pending scene cleanup preserves saved project and bundle bytes',
cancelledApply,
);
await click('EDIT DETAILS');
await page.evaluate(() => {
const fields = [
...document.querySelectorAll('[data-director-dialog] textarea'),
];
const scene = JSON.parse(fields[0].value),
shot = JSON.parse(fields[1].value);
scene.dataPacks = [];
shot.dataPackIds = [];
shot.interactions = [];
fields[0].value = JSON.stringify(scene);
fields[1].value = JSON.stringify(shot);
});
await page.click('[data-director-apply-details]');
await page.waitForFunction(
() => !document.querySelector('[data-director-dialog]'),
);
check(
'removing a pack through authoring releases its retained bytes',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getSharingState().assets.count === 0,
),
);
await page.evaluate(
(text) =>
window.__godsEyeView.sceneDirector.importProjectFile(
new File([text], 'again.gevbundle.json'),
),
bundle,
);
await page.evaluate(() =>
window.__godsEyeView.sceneDirector.importProjectFile(
new File([JSON.stringify({ version: 6, scenes: [] })], 'empty.json'),
),
);
check(
'replacement releases stored bundle bytes',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getSharingState().assets.count === 0,
),
);
await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
void d._sharing.preview({
name: 'pending.json',
text: () => new Promise(() => {}),
});
await d.destroy();
});
check(
'teardown removes pending dialogs and authoring controls',
await page.evaluate(
() =>
!document.querySelector('[data-director-dialog]') &&
!document.querySelector('[data-director-authoring]') &&
!window.__godsEyeView.sceneDirector.getSharingState().open,
),
);
check('no uncaught browser errors', errors.length === 0);
} finally {
await browser.close();
}
process.exitCode = failures ? 1 : 0;
scripts/qa-director-timing.mjs
+137
View File
@@ -0,0 +1,137 @@
#!/usr/bin/env node
/** Exercise scene-clock ownership and authored seek behavior in the composed browser app. */
import fs from 'node:fs';
import path from 'node:path';
import puppeteer from 'puppeteer';
const shots = path.resolve('qa-shots/director-timing');
fs.mkdirSync(shots, { recursive: true });
const browser = await puppeteer.launch({
headless: true,
args: ['--no-sandbox', '--disable-dev-shm-usage'],
});
const page = await browser.newPage();
const errors = [];
page.on('pageerror', (error) => errors.push(error.message));
let failures = 0;
function check(name, passed) {
console.log(`[${passed ? 'PASS' : 'FAIL'}] ${name}`);
if (!passed) failures++;
}
try {
await page.setViewport({ width: 1440, height: 900 });
await page.goto(
`${process.env.QA_BASE_URL || 'http://localhost:4173'}/?welcome=0`,
{ waitUntil: 'domcontentloaded' },
);
await page.waitForFunction(
() =>
window.__godsEyeView?.sceneDirector &&
document.getElementById('loading-screen')?.classList.contains('hidden'),
{ timeout: 60000 },
);
const result = await page.evaluate(async () => {
const director = window.__godsEyeView.sceneDirector;
const camera = director.styleManager.getCameraState();
const visual = director.styleManager.getVisualState();
const scene = {
id: 'timing-qa',
title: 'Timing QA',
shots: [0, 1].map((index) => ({
id: `timing-${index}`,
title: `Timing ${index}`,
durationSec: 0.4,
holdSec: 0.3,
camera: { ...camera, lon: camera.lon + index * 0.002 },
visual,
layers: {},
})),
};
director._project.scenes.push(scene);
const load = await director.loadShot(scene.id, scene.shots[0].id, {
flyDuration: 0.3,
});
const forward = await director.seekScene(scene.id, 0.9);
const forwardSnapshot = director.getPlaybackTimingState().snapshot;
const backward = await director.seekScene(scene.id, 0.1);
const backwardSnapshot = director.getPlaybackTimingState().snapshot;
const replay = await director.replayShot(scene.id, scene.shots[1].id);
director.stopScene();
await director.startScene(scene.id, { single: true, preview: false });
const completed =
!director.running && director.getPlaybackTimingState().activeTimers === 0;
scene.shots[0].holdSec = 60;
const run = director.startScene(scene.id, { single: true, preview: false });
const deadline = Date.now() + 10000;
while (
director.getPlaybackTimingState().activeTimers < 3 &&
Date.now() < deadline
)
await new Promise((resolve) => setTimeout(resolve, 25));
const holding = director.getPlaybackTimingState().activeTimers >= 3;
const stoppedAt = performance.now();
director.stopScene('QA Stop during hold');
await run;
const stoppedPromptly = performance.now() - stoppedAt < 1000;
const noTimers = director.getPlaybackTimingState().activeTimers === 0;
director._project.scenes = director._project.scenes.filter(
({ id }) => id !== scene.id,
);
return {
loaded: load?.started,
forward: forward && forwardSnapshot.shotId === 'timing-1',
backward: backward && backwardSnapshot.shotId === 'timing-0',
replay: replay?.started,
completed,
holding,
stoppedPromptly,
noTimers,
};
});
for (const [name, passed] of Object.entries(result)) check(name, passed);
const content = await page.evaluate(async () => {
const d = window.__godsEyeView.sceneDirector;
const scene = d._project.scenes.find(({ title }) =>
/Nepal Flood Incident/i.test(title),
);
if (!scene) return { exists: false };
const shot =
scene.shots.find(({ title }) => /Regional Approach/i.test(title)) ||
scene.shots[0];
const loaded = await d.loadShot(scene.id, shot.id, { flyDuration: 0.3 });
return {
exists: true,
shots: scene.shots.length,
loaded: loaded?.started === true,
};
});
check(
'existing Nepal scene and authored shots load',
content.exists && content.shots >= 25 && content.loaded,
);
await new Promise((resolve) => setTimeout(resolve, 2500));
await page.screenshot({ path: path.join(shots, 'nepal-regional.png') });
await page.evaluate(() => {
const g = window.__godsEyeView;
g.sceneDirector.stopScene();
const pose = g.styleManager.getCameraState();
g.sceneDirector._setCameraView({
...pose,
heading: pose.heading + 45,
pitch: -55,
});
});
await new Promise((resolve) => setTimeout(resolve, 1000));
await page.screenshot({ path: path.join(shots, 'nepal-angle.png') });
check(
'no pending clocks after Stop',
await page.evaluate(
() =>
window.__godsEyeView.sceneDirector.getPlaybackTimingState()
.activeTimers === 0,
),
);
check('no browser exceptions', errors.length === 0);
} finally {
await browser.close();
}
if (failures) process.exitCode = 1;
scripts/qa-scene-controls.mjs
+57 -2
View File
@@ -85,6 +85,9 @@ try {
);
promptValue = '<b>QA shot</b>';
await page.click('.scene-shot-label', { count: 2 });
await page.waitForSelector('.scene-shot-rename', { visible: true });
await page.type('.scene-shot-rename', promptValue);
await page.keyboard.press('Enter');
await page.waitForFunction(
() =>
document.querySelector('.scene-shot-label')?.textContent ===
@@ -151,7 +154,20 @@ try {
const projectFile = path.join(shots, 'project.json');
fs.writeFileSync(projectFile, JSON.stringify(fixture));
const input = await page.$('#scene-import-file');
const beforePreview = await page.evaluate(() =>
JSON.stringify(window.__godsEyeView.sceneDirector._project),
);
await input.uploadFile(projectFile);
await page.waitForSelector('[data-director-apply-import]');
check(
'Import preview leaves the current project untouched',
await page.evaluate(
(saved) =>
JSON.stringify(window.__godsEyeView.sceneDirector._project) === saved,
beforePreview,
),
);
await page.click('[data-director-apply-import]');
await page.waitForFunction(
() =>
document.getElementById('scene-status').textContent ===
@@ -259,8 +275,8 @@ try {
await input.uploadFile(badFile);
await page.waitForFunction(() =>
document
.getElementById('scene-status')
.textContent.includes('invalid JSON'),
.querySelector('[data-director-dialog] [role=status]')
?.textContent.includes('invalid JSON'),
);
check(
'Invalid import reports failure and preserves the current project',
@@ -271,6 +287,45 @@ try {
'QA Scene',
),
);
const savedBefore = await page.evaluate(() =>
localStorage.getItem('godsEyeView.sceneProject.v2'),
);
const futureFile = path.join(shots, 'future.json');
fs.writeFileSync(futureFile, JSON.stringify({ version: 99, scenes: [] }));
await input.uploadFile(futureFile);
await page.waitForFunction(() =>
document
.querySelector('[data-director-dialog] [role=status]')
?.textContent.includes('$.version'),
);
check(
'Unsupported versions leave authored state and saved bytes unchanged',
await page.evaluate(
(saved) =>
localStorage.getItem('godsEyeView.sceneProject.v2') === saved &&
window.__godsEyeView.sceneDirector._getSelectedScene().title ===
'QA Scene',
savedBefore,
),
);
const malformed = structuredClone(fixture);
malformed.scenes[0].shots[0].camera.lat = 91;
const malformedFile = path.join(shots, 'malformed.json');
fs.writeFileSync(malformedFile, JSON.stringify(malformed));
await input.uploadFile(malformedFile);
await page.waitForFunction(() =>
document
.querySelector('[data-director-dialog] [role=status]')
?.textContent.includes('camera.lat'),
);
check(
'Invalid camera field identifies its path without replacing the project',
await page.evaluate(
(saved) => localStorage.getItem('godsEyeView.sceneProject.v2') === saved,
savedBefore,
),
);
await page.keyboard.press('Escape');
await page.screenshot({ path: path.join(shots, 'desktop.png') });
await page.setViewport({ width: 390, height: 844 });
await page.screenshot({ path: path.join(shots, 'narrow.png') });
scripts/qa-transit-browser.mjs
+107 -37
View File
@@ -367,7 +367,7 @@ export async function sampleTransitPixels(page, palette) {
const luma = (r, g, b) => (0.299 * r + 0.587 * g + 0.114 * b) / 255;
const readLuma = (cx, cy) => {
const px = Math.floor(cx * scale);
const py = Math.floor(canvas.height - 1 - cy * scale);
const py = canvas.height - 1 - Math.floor(cy * scale);
const buf = new Uint8Array(4);
gl.readPixels(px, py, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, buf);
return luma(buf[0], buf[1], buf[2]);
@@ -399,46 +399,117 @@ export async function sampleTransitPixels(page, palette) {
continue;
}
}
// Pick nine points from a solid patch of the source silhouette,
// before examining framebuffer brightness. Avoid panels/window gaps.
let corePoints = null,
widestBand = -1;
const cosCore = Math.cos(s.rotation),
sinCore = Math.sin(s.rotation);
// A tram's parallel sides have equally wide bands. Prefer its upper
// body band over the geometric centre when those widths tie.
const offsets =
s.mode === 'tram'
? [-0.2, 0.2, -0.1, 0.1, 0]
: [0, -0.1, 0.1, -0.2, 0.2];
for (const offset of offsets) {
const candidates = [];
let solid = true,
bandWidth = Infinity;
// Rank source geometry, never the observed framebuffer brightness.
// A thin tram needs the widest opaque white band, with room for
// the pixel filter on each side of the sampled patch.
for (let dy = -1; dy <= 1; dy++) {
const ry = Math.floor(
((dy + offset * s.rect.height) / s.rect.height + 0.5) *
s.raster.height,
);
const middle = Math.floor(s.raster.width / 2);
const white = (x) =>
x >= 0 &&
x < s.raster.width &&
[0, 1, 2, 3].every(
(c) =>
s.raster.data[(ry * s.raster.width + x) * 4 + c] >= 240,
);
let left = middle,
right = middle;
while (white(left - 1)) left--;
while (white(right + 1)) right++;
bandWidth = Math.min(
bandWidth,
white(middle) ? right - left + 1 : 0,
);
}
for (let dx = -1; dx <= 1; dx++)
for (let dy = -1; dy <= 1; dy++) {
const localY = dy + offset * s.rect.height;
const rx = Math.floor(
(dx / s.rect.width + 0.5) * s.raster.width,
);
const ry = Math.floor(
(localY / s.rect.height + 0.5) * s.raster.height,
);
const i = (ry * s.raster.width + rx) * 4;
if ([0, 1, 2, 3].some((c) => s.raster.data[i + c] < 240))
solid = false;
candidates.push(
screenPoint(
s.screenX + dx * cosCore + localY * sinCore,
s.screenY - dx * sinCore + localY * cosCore,
),
);
}
if (solid && bandWidth > widestBand) {
corePoints = candidates;
widestBand = bandWidth;
}
}
if (!corePoints) {
skipped.push({
key: s.key,
reason: 'no solid silhouette interior for nine samples',
});
continue;
}
// Picking is independent of rendered brightness: an overlapping
// label or sprite must not masquerade as a dim sensor signature.
// Check the whole sampled core, not just its centre pick.
let coreOwned = true;
if (scene.pick) {
const framebuffer = gl.getParameter?.(gl.FRAMEBUFFER_BINDING);
for (let dx = -1; dx <= 1; dx++)
for (let dy = -1; dy <= 1; dy++) {
let u = (s.x + dx) / width,
v = 1 - (s.y + dy) / height;
if (style === 'surveillance') {
const x = u * 2 - 1,
y = v * 2 - 1,
r2 = x * x + y * y;
const d =
1 + r2 * intensity * 0.25 + r2 * r2 * intensity * 0.075;
u = (x * d + 1) / 2;
v = (y * d + 1) / 2;
}
if (sensor) {
const grid = 1 + (pixelation - 1) * intensity;
u +=
((Math.floor((u * canvas.width) / grid) * grid) /
canvas.width -
u) *
intensity;
v +=
((Math.floor((v * canvas.height) / grid) * grid) /
canvas.height -
v) *
intensity;
}
const picked = scene.pick(
{ x: u * width, y: (1 - v) * height },
1,
1,
);
if (picked?.id !== s.key && picked?.primitive?.id !== s.key)
coreOwned = false;
for (const core of corePoints) {
let u = core.x / width,
v = 1 - core.y / height;
if (style === 'surveillance') {
const x = u * 2 - 1,
y = v * 2 - 1,
r2 = x * x + y * y;
const d =
1 + r2 * intensity * 0.25 + r2 * r2 * intensity * 0.075;
u = (x * d + 1) / 2;
v = (y * d + 1) / 2;
}
if (sensor) {
const grid = 1 + (pixelation - 1) * intensity;
u +=
((Math.floor((u * canvas.width) / grid) * grid) /
canvas.width -
u) *
intensity;
v +=
((Math.floor((v * canvas.height) / grid) * grid) /
canvas.height -
v) *
intensity;
}
const picked = scene.pick(
{ x: u * width, y: (1 - v) * height },
1,
1,
);
if (picked?.id !== s.key && picked?.primitive?.id !== s.key)
coreOwned = false;
}
if (gl.bindFramebuffer)
gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
}
@@ -451,9 +522,8 @@ export async function sampleTransitPixels(page, palette) {
continue;
}
let centre = 0;
for (let dx = -1; dx <= 1; dx += 1)
for (let dy = -1; dy <= 1; dy += 1)
centre += readLuma(s.x + dx, s.y + dy) / 9;
for (const core of corePoints)
centre += readLuma(core.x, core.y) / corePoints.length;
let ringMin = 1;
let ringMax = 0;
// Sample the actual rotated raster halo, not a fixed-radius circle
scripts/qa-transit-heading.mjs
+156
View File
@@ -0,0 +1,156 @@
import puppeteer from 'puppeteer';
/** Prove parked and moving headings in the real scene, without live feeds. */
export async function runTransitHeadingRegression(base, check) {
const browser = await puppeteer.launch({
headless: true,
executablePath:
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
args: ['--no-sandbox', '--disable-background-timer-throttling'],
});
try {
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 800 });
await page.goto(
`${base}/?welcome=0#lat=42.3601&lon=-71.0589&alt=1200&heading=0&pitch=-90`,
{ waitUntil: 'domcontentloaded' },
);
await page.waitForFunction(
() => window.__godsEyeView?.dataManager?.layers?.has('transit'),
{ timeout: 90000 },
);
await new Promise((resolve) => setTimeout(resolve, 6000));
await page.evaluate(async () => {
const app = window.__godsEyeView;
await app.dataManager.setEnabled('transit', true, { source: 'qa' });
const layer = app.dataManager.layers.get('transit').module;
layer._loadTransitFleetForTest(4, { lat: 42.3601, lon: -71.0589 }, 100);
const state = layer._transitStateForTest(),
parts = layer._transitPartsForTest();
const { destroyTrack } = await import('/src/data/contactPlayback.js');
const {
initializePlayback,
recordFix,
updatePlayback,
attachFloorToPlace,
} = await import('/src/layers/transit/movement.js');
// The first three are parked: held east, reported east only, unknown.
for (let i = 0; i < 3; i++) {
const entry = state._vehicles.get(`mbta:qa-${i}`);
state._moving.delete(entry);
destroyTrack(entry.track);
initializePlayback(entry, state._historyBudget);
recordFix(entry, {
t: Date.now() - 30000,
lat: entry.record.lat,
lon: entry.record.lon,
});
attachFloorToPlace(entry, entry.record, 20);
updatePlayback(entry, Date.now(), performance.now());
entry.courseDeg = i === 0 ? 90 : null;
entry.record.bearing = i === 1 ? 90 : null;
entry.displayPaths.clear();
parts.rendering.placeSample(entry);
parts.rendering.schedulePlayback(entry);
}
parts.rendering.syncRenderHold();
window.__headingErrors = [];
app.viewer.scene.renderError.addEventListener((scene, error) =>
window.__headingErrors.push(error.message),
);
});
const pose = async (heading) => {
await page.evaluate((heading) => {
const camera = window.__godsEyeView.viewer.camera;
const C = camera.positionCartographic.constructor;
camera.setView({
destination: C.toCartesian(C.fromDegrees(-71.0589, 42.3601, 1200)),
orientation: { heading, pitch: -Math.PI / 2, roll: 0 },
});
}, heading);
await new Promise((resolve) => setTimeout(resolve, 700));
};
const sample = () =>
page.evaluate(async () => {
const app = window.__godsEyeView,
scene = app.viewer.scene;
const state = app.dataManager.layers
.get('transit')
.module._transitStateForTest();
const mul = (m, v) =>
[0, 1, 2, 3].map(
(r) =>
m[r] * v[0] +
m[r + 4] * v[1] +
m[r + 8] * v[2] +
m[r + 12] * v[3],
);
const project = (p) => {
const clip = mul(
scene.camera.frustum.projectionMatrix,
mul(scene.camera.viewMatrix, [p.x, p.y, p.z, 1]),
);
return {
x: ((clip[0] / clip[3] + 1) * scene.canvas.clientWidth) / 2,
y: ((1 - clip[1] / clip[3]) * scene.canvas.clientHeight) / 2,
};
};
return [0, 1, 2, 3].map((i) => {
const entry = state._vehicles.get(`mbta:qa-${i}`);
const p = project(entry.marker.position);
return {
rotation: entry.marker.rotation,
course: entry.courseDeg,
moving: state._moving.has(entry),
visible: entry.marker.show,
x: p.x,
y: p.y,
};
});
});
await pose(0);
const before = await sample();
await pose(Math.PI / 2);
const after = await sample();
const deltaDeg = (a, b) =>
(Math.atan2(Math.sin(b - a), Math.cos(b - a)) * 180) / Math.PI;
for (const [i, label] of ['held course', 'reported bearing'].entries()) {
const delta = deltaDeg(before[i].rotation, after[i].rotation);
check(
`parked ${label} reprojects through a 90 degree camera orbit`,
before[i].visible &&
after[i].visible &&
!before[i].moving &&
!after[i].moving &&
Math.abs(delta - 90) <= 5,
JSON.stringify({ before: before[i], after: after[i], delta }),
);
}
check(
'unknown parked course remains screen-up',
before[2].rotation === 0 && after[2].rotation === 0,
);
await new Promise((resolve) => setTimeout(resolve, 1200));
const moved = (await sample())[3];
const dx = moved.x - after[3].x,
dy = moved.y - after[3].y;
const travelRotation = Math.atan2(-dx, -dy);
const error = Math.abs(deltaDeg(travelRotation, moved.rotation));
check(
'moving vehicle still points along its rendered travel after orbit',
moved.visible && moved.moving && Math.hypot(dx, dy) > 0.5 && error <= 5,
JSON.stringify({
pixels: Math.hypot(dx, dy),
error,
after: after[3],
moved,
}),
);
check(
'heading regression has no scene render errors',
(await page.evaluate(() => window.__headingErrors)).length === 0,
);
} finally {
await browser.close();
}
}
scripts/qa-transit-recovery.mjs
+330
View File
@@ -0,0 +1,330 @@
/** Camera-jump regression against an existing server; never starts a server. */
import puppeteer from 'puppeteer';
import { mkdir, writeFile } from 'node:fs/promises';
import { reduceTrailPixels } from '../src/layers/transit/qaMetrics.js';
const base = process.env.QA_BASE_URL || 'http://localhost:4305';
const shots = process.env.QA_SHOTS || 'qa-shots/transit-recovery';
await mkdir(shots, { recursive: true });
const browser = await puppeteer.launch({
headless: false,
executablePath:
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
args: [
'--disable-background-timer-throttling',
'--disable-renderer-backgrounding',
],
});
try {
const page = await browser.newPage();
await page.setViewport({ width: 1920, height: 1080 });
const errors = [];
page.on('pageerror', (error) => errors.push(error.message));
await page.goto(
`${base}/?welcome=0#lat=30.271&lon=-97.7431&alt=600&heading=0&pitch=-60`,
);
await page.waitForFunction(() =>
window.__godsEyeView?.dataManager?.layers.has('transit'),
);
await page.evaluate(async () => {
const app = window.__godsEyeView;
await app.dataManager.setEnabled('transit', true, { source: 'qa' });
});
await page.waitForFunction(
() => {
const scene = window.__godsEyeView.viewer.scene;
return scene.globe.tilesLoaded && scene.globe.show;
},
{ timeout: 60000 },
);
await page.waitForFunction(
() => {
const cover = document.getElementById('loading-screen');
return !cover || cover.classList.contains('hidden');
},
{ timeout: 60000 },
);
await page.evaluate(() => {
const app = window.__godsEyeView,
camera = app.viewer.camera;
const C = camera.positionCartographic.constructor,
lat = 30.267 + 90 / 111320;
const floor =
app.viewer.scene.globe.getHeight(C.fromDegrees(-97.7431, lat)) || 0;
camera.setView({
destination: C.toCartesian(
C.fromDegrees(
-97.7431,
lat - 600 / Math.tan(Math.PI / 3) / 111320,
floor + 600,
),
),
orientation: { heading: 0, pitch: -Math.PI / 3, roll: 0 },
});
});
await new Promise((resolve) => setTimeout(resolve, 2000));
await page.waitForFunction(
() => window.__godsEyeView.viewer.scene.globe.tilesLoaded,
{ timeout: 60000 },
);
await new Promise((resolve) => setTimeout(resolve, 1500));
const result = await page.evaluate(async () => {
const app = window.__godsEyeView,
scene = app.viewer.scene,
camera = app.viewer.camera;
const layer = app.dataManager.layers.get('transit').module;
const state = layer._transitStateForTest(),
parts = layer._transitPartsForTest();
const { getRegisteredTransitFeed } =
await import('/src/data/transitFeeds.js');
const { setRate } = await import('/src/data/contactPlayback.js');
const C = camera.positionCartographic.constructor;
const feed = {
...getRegisteredTransitFeed('capmetro-austin'),
id: 'qa-camera-recovery',
};
const aim = (lat, height = 600) =>
camera.setView({
destination: C.toCartesian(
C.fromDegrees(
-97.7431,
lat - 600 / Math.tan(Math.PI / 3) / 111320,
height,
),
),
orientation: { heading: 0, pitch: -Math.PI / 3, roll: 0 },
});
parts.selection.clearSelection();
parts.ingestion.abortAllInFlight();
state._activeFeeds.clear();
for (const key of state._vehicles.keys())
parts.ingestion.removeVehicle(key);
// Model an outstanding floor lookup while reports arrive off screen.
// Only acquisition is controlled; selection, visibility, paths and rendering
// use their real owners. Release to the loaded terrain at the camera jump.
const requestHeight = parts.height.requestHeight;
parts.height.requestHeight = (lat, lon) => ({
cell: `${lat},${lon}`,
height: null,
prior: null,
});
aim(30.28);
const now = Date.now();
for (let i = 0; i < 9; i++) {
const timestamp = now - 135000 + i * 15000;
parts.ingestion.applySnapshot(
feed,
{
fetchedAt: timestamp,
vehicles: [
{
id: 'moving-bus',
routeId: '1',
tripId: 'qa',
lat: 30.267 + (i * 90) / 111320,
lon: -97.7431,
timestamp: timestamp / 1000,
timestampSource: 'vehicle',
bearing: 0,
},
],
},
{ stale: false },
);
}
const entry = state._vehicles.get(`${feed.id}:moving-bus`);
entry.qaFixture = true; // Protect this disclosed fixture from live feed eviction.
parts.rendering.sampleIdle(entry);
const before = {
shown: entry.marker.show,
heightPending: entry.heightPending,
phase: entry.sample.phase,
fixes: entry.track.count,
};
clearTimeout(state._floorTimer);
state._floorTimer = null;
const started = performance.now();
parts.selection.selectVehicle(entry.key);
const preparedAtSelection = !!parts.trails.diagnostics()?.body;
parts.height.requestHeight = requestHeight;
const floor =
scene.globe.getHeight(
C.fromDegrees(entry.sample.lon, entry.sample.lat),
) || 0;
aim(entry.sample.lat, floor + 600);
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
let trail;
while (performance.now() - started < 1400) {
trail = parts.trails.diagnostics();
if (entry.marker.show && trail?.body?.show && trail.body.ready) break;
scene.requestRender();
await wait(25);
}
const status = {
before,
preparedAtSelection,
markerShow: entry.marker.show,
body: !!trail?.body,
bodyShow: trail?.body?.show === true,
visibility: layer
._transitVisibilityForTest()
.find((e) => e.key === entry.key),
recoveryMs: performance.now() - started,
};
if (!entry.marker.show || !trail?.body?.show || !trail.body.ready)
return {
...status,
reason: 'marker or body did not recover before pixel deadline',
};
setRate(entry.track, 0, {
wallNowMs: Date.now(),
monoNowMs: performance.now(),
});
parts.rendering.sampleIdle(entry);
parts.rendering.schedulePlayback(entry);
const V = entry.marker.position.constructor;
const points = entry.trailSegments
.filter((s) => s.toT <= entry.sample.displayT)
.flatMap((s) => s.positions);
const lengths = [0];
for (let i = 1; i < points.length; i++)
lengths.push(lengths.at(-1) + V.distance(points[i - 1], points[i]));
const canvas = scene.canvas,
gl = scene.context._gl,
scale = canvas.width / canvas.clientWidth;
const mul = (m, v) =>
[0, 1, 2, 3].map(
(i) =>
m[i] * v[0] + m[i + 4] * v[1] + m[i + 8] * v[2] + m[i + 12] * v[3],
);
const project = (p) => {
const q = mul(
camera.frustum.projectionMatrix,
mul(camera.viewMatrix, [p.x, p.y, p.z, 1]),
);
return {
x: ((q[0] / q[3]) * 0.5 + 0.5) * canvas.clientWidth,
y: (0.5 - (q[1] / q[3]) * 0.5) * canvas.clientHeight,
inFront: q[3] > 0,
};
};
const samples = Array.from({ length: 8 }, (_, i) => {
const d = (lengths.at(-1) * (i + 1)) / 9;
let j = 1;
while (j < lengths.length - 1 && lengths[j] < d) j++;
const p = V.lerp(
points[j - 1],
points[j],
(d - lengths[j - 1]) / Math.max(0.001, lengths[j] - lengths[j - 1]),
new V(),
);
const cart = C.fromCartesian(p);
cart.height = scene.globe.getHeight(cart) || 0;
return {
...project(C.toCartesian(cart)),
radius: (Math.SQRT2 * Math.ceil(3 * scale)) / scale,
};
});
const sprite = {
...project(entry.marker.position),
radius: Math.hypot(entry.marker.width, entry.marker.height) / 2 + 4,
};
const read = () =>
samples.map(({ x, y }) => {
const r = Math.ceil(3 * scale),
px = Math.round(x * scale),
py = Math.round(canvas.height - 1 - y * scale);
if (
px < r ||
py < r ||
px + r >= canvas.width ||
py + r >= canvas.height
)
return null;
const data = new Uint8Array((2 * r + 1) ** 2 * 4);
gl.readPixels(
px - r,
py - r,
2 * r + 1,
2 * r + 1,
gl.RGBA,
gl.UNSIGNED_BYTE,
data,
);
return Array.from(data);
});
const frame = () =>
new Promise((resolve, reject) => {
const timer = setTimeout(() => {
remove();
reject(new Error('No recovery frame'));
}, 500);
const remove = scene.postRender.addEventListener(() => {
remove();
clearTimeout(timer);
resolve(read());
});
scene.requestRender();
});
let visible = true;
const remove = scene.preRender.addEventListener(() => {
trail.body.show = visible;
if (trail.headPrimitive)
trail.headPrimitive.show = visible && trail.head.show;
});
const captures = [];
try {
for (const show of [false, true, false, true]) {
visible = show;
await frame();
captures.push(await frame());
}
} finally {
remove();
parts.trails.update();
}
const [off, on, offAgain, onAgain] = captures;
return {
...status,
samples,
sprite,
off,
on,
offAgain,
onAgain,
tilesReady:
scene.globe.tilesLoaded &&
parts.trails.diagnostics().body === trail.body,
elapsedMs: performance.now() - started,
attributes: Array.from({ length: 4 }, (_, i) => {
const a = trail.body.getGeometryInstanceAttributes(`${i}:1`);
return { show: Array.from(a.show), color: Array.from(a.color) };
}),
};
});
const pixels = reduceTrailPixels(result.on, result.off, result);
result.present = pixels.present;
result.pixelPass = pixels.pass;
result.pixelDetails = pixels;
result.errors = errors;
await page.screenshot({ path: `${shots}/recovery.png` });
await writeFile(`${shots}/recovery.json`, JSON.stringify(result, null, 2));
for (const key of ['on', 'off', 'onAgain', 'offAgain']) delete result[key];
const pass =
result.before?.shown === false &&
result.before?.phase === 'playing' &&
result.preparedAtSelection &&
result.markerShow &&
result.body &&
result.bodyShow &&
result.elapsedMs <= 2000 &&
pixels.pass &&
!errors.length;
console.log(
`${pass ? 'PASS' : 'FAIL'} select moving bus, setView, marker + body + >=6/8 trail pixels within 2 s`,
);
console.log(JSON.stringify(result));
process.exitCode = pass ? 0 : 1;
} finally {
await browser.close();
}
scripts/qa-transit-scenes.mjs
+466
View File
@@ -1,3 +1,12 @@
import { getRegisteredTransitFeed } from '../src/data/transitFeeds.js';
// Not registered or active: camera discovery and live polls never own this feed.
/** CapMetro metadata under a private QA identity for selected-trail pixels. */
export const TRAIL_VISIBILITY_FEED = Object.freeze({
...getRegisteredTransitFeed('capmetro-austin'),
id: 'qa-trail-capmetro',
});
import { reportTransitVisibility } from './qa-transit-browser.mjs';
import { writeFile } from 'node:fs/promises';
import {
@@ -5,6 +14,7 @@ import {
reduceMotion,
reduceBackground,
reduceSensorContrast,
reduceTrailPixels,
} from '../src/layers/transit/qaMetrics.js';
/** CDP includes objects collected during the sample, not just surviving objects. */
@@ -581,3 +591,459 @@ export async function runBostonLive({
JSON.stringify(evidence, null, 2),
);
}
/** Google 3D proof: paired framebuffer reads reject coincidental road colours. */
export async function runTrailVisibility({
page,
check,
wait,
shots,
tag,
selectStyle,
altitude = 600,
pitch = 45,
}) {
const name = 'Google 3D selected trail visible at 6 of 8 projected samples';
await selectStyle(page, 'normal');
await page.evaluate(
async ({ altitude, pitch }) => {
const app = window.__godsEyeView;
await app.dataManager.setEnabled('transit', true, { source: 'qa' });
if (app.mapStackController.isStackAvailable('photoreal'))
await app.mapStackController.setStack('photoreal');
const camera = app.viewer.camera,
C = camera.positionCartographic.constructor;
camera.setView({
destination: C.toCartesian(
C.fromDegrees(
-97.7431,
30.26725 - altitude / Math.tan((pitch * Math.PI) / 180) / 111320,
altitude,
),
),
orientation: { heading: 0, pitch: (-pitch * Math.PI) / 180, roll: 0 },
});
},
{ altitude, pitch },
);
await wait(8000);
const setup = await page.evaluate(
async ({ altitude, pitch, feed }) => {
const app = window.__godsEyeView,
scene = app.viewer.scene;
const layer = app.dataManager.layers.get('transit').module;
const state = layer._transitStateForTest(),
parts = layer._transitPartsForTest();
const google =
!!app.tileset &&
app.tileset.show !== false &&
app.mapStackController.getActiveId() === 'photoreal';
if (!google)
return { google: false, reason: 'visible Google 3D tileset required' };
const C = scene.camera.positionCartographic.constructor;
const centreLat = 30.267 + 90 / 111320;
const floor = scene.sampleHeight(C.fromDegrees(-97.7431, centreLat));
if (Number.isFinite(floor))
scene.camera.setView({
destination: C.toCartesian(
C.fromDegrees(
-97.7431,
centreLat - altitude / Math.tan((pitch * Math.PI) / 180) / 111320,
floor + altitude,
),
),
orientation: { heading: 0, pitch: (-pitch * Math.PI) / 180, roll: 0 },
});
parts.selection.clearSelection();
parts.ingestion.abortAllInFlight();
state._activeFeeds.clear();
for (const key of state._vehicles.keys())
parts.ingestion.removeVehicle(key);
clearTimeout(state._cameraDebounceTimer);
state._cameraDebounceTimer = null;
const { seek, setRate } = await import('/src/data/contactPlayback.js');
const now = Date.now();
// Nine straight street fixes, 30 m apart. Use the production surface path.
for (let i = 0; i < 9; i++) {
const timestamp = (now - 120000 + i * 15000) / 1000;
parts.ingestion.applySnapshot(
feed,
{
fetchedAt: timestamp * 1000,
vehicles: [
{
id: 'trail-visible',
routeId: '1',
tripId: 'trail-visible',
lat: 30.267 + (i * 30) / 111320,
lon: -97.7431,
timestamp,
timestampSource: 'vehicle',
bearing: 0,
},
],
},
{ stale: false },
);
}
const entry = state._vehicles.get(`${feed.id}:trail-visible`);
entry.qaFixture = true;
const clocks = { wallNowMs: now, monoNowMs: performance.now() };
seek(entry.track, now - 45000, clocks);
setRate(entry.track, 1, clocks);
parts.rendering.sampleIdle(entry);
parts.height.anchorFloors();
parts.rendering.refreshVisibility();
parts.rendering.maintainPresentation();
parts.selection.selectVehicle(entry.key);
return {
google,
key: entry.key,
fixes: entry.track.count,
startDisplayT: now - 45000,
startLat: entry.sample.lat,
};
},
{ altitude, pitch, feed: TRAIL_VISIBILITY_FEED },
);
if (!setup.google) {
check(name, false, JSON.stringify(setup), { unexercised: true });
return;
}
const cost = await page.evaluate(async (key) => {
const app = window.__godsEyeView,
scene = app.viewer.scene;
const layer = app.dataManager.layers.get('transit').module;
const parts = layer._transitPartsForTest(),
entry = layer._transitStateForTest()._vehicles.get(key);
const gl = scene.context._gl,
originals = new Map(),
wrapped = new Map();
let owner = null,
headBytes = 0,
bodyBytes = 0,
headUploadMax = 0,
bodyUploadMax = 0,
frames = 0;
const headCpu = [];
const wrap = (primitive, kind) => {
if (!primitive || wrapped.has(primitive)) return;
const update = primitive.update;
wrapped.set(primitive, update);
primitive.update = function (frameState) {
const before = performance.now();
owner = kind;
try {
return update.call(this, frameState);
} finally {
owner = null;
if (kind === 'head') headCpu.push(performance.now() - before);
}
};
};
for (const name of ['bufferData', 'bufferSubData']) {
const original = gl[name];
originals.set(name, original);
gl[name] = function (...args) {
if (owner) {
const value = args[name === 'bufferData' ? 1 : 2],
offset = args[3] || 0,
length = args[4];
const bytes =
typeof value === 'number'
? value
: value
? length !== undefined
? length * (value.BYTES_PER_ELEMENT || 1)
: value.byteLength - offset * (value.BYTES_PER_ELEMENT || 1)
: 0;
if (owner === 'head') headBytes += bytes;
else bodyBytes += bytes;
}
return original.apply(this, args);
};
}
const pre = scene.preRender.addEventListener(() => {
headBytes = bodyBytes = 0;
const trail = parts.trails.diagnostics();
wrap(trail?.body, 'body');
wrap(trail?.headPrimitive || trail?.head?._polylineCollection, 'head');
});
const post = scene.postRender.addEventListener(() => {
frames++;
headUploadMax = Math.max(headUploadMax, headBytes);
bodyUploadMax = Math.max(bodyUploadMax, bodyBytes);
});
try {
// Include a full history upload, even if the first selection already rendered.
entry.pathRevision = -1;
parts.trails.prepareEntry(entry);
scene.requestRender();
await new Promise((resolve) => setTimeout(resolve, 20000));
headCpu.sort((a, b) => a - b);
return {
frames,
headUploadMax,
bodyUploadMax,
headCpuP95Ms: headCpu[Math.floor(headCpu.length * 0.95)] ?? null,
headCpuMaxMs: headCpu.at(-1) ?? null,
};
} finally {
pre();
post();
for (const [name, original] of originals) gl[name] = original;
for (const [primitive, update] of wrapped)
if (!primitive.isDestroyed()) primitive.update = update;
}
}, setup.key);
const result = await page.evaluate(async (setup) => {
const app = window.__godsEyeView,
scene = app.viewer.scene;
const layer = app.dataManager.layers.get('transit').module;
const state = layer._transitStateForTest(),
parts = layer._transitPartsForTest();
const entry = state._vehicles.get(setup.key);
const trail = parts.trails.diagnostics();
if (!entry || !trail)
return { ...setup, present: 0, reason: 'selection disappeared' };
const { setRate } = await import('/src/data/contactPlayback.js');
setRate(entry.track, 0, {
wallNowMs: Date.now(),
monoNowMs: performance.now(),
});
parts.rendering.sampleIdle(entry);
parts.rendering.schedulePlayback(entry);
parts.rendering.syncRenderHold();
const ready = () =>
app.tileset?.show !== false &&
app.tileset?.tilesLoaded === true &&
(scene.globe?.show === false || scene.globe?.tilesLoaded === true) &&
trail.body?.ready === true &&
(!trail.headPrimitive || trail.headPrimitive.ready === true);
// Require sustained readiness after freezing playback, before projecting
// onto the refined surface. Repeated captures still check pixel stability.
const tilesReady = await new Promise((resolve) => {
const started = performance.now();
let readySince = null;
const timer = setInterval(() => {
const now = performance.now();
readySince = ready() ? (readySince ?? now) : null;
scene.requestRender();
if (
(readySince !== null && now - readySince >= 500) ||
now - started >= 30000
) {
clearInterval(timer);
resolve(readySince !== null && now - readySince >= 500);
}
}, 80);
});
if (!tilesReady)
return {
...setup,
present: 0,
reason: 'tiles or trail geometry did not become ready',
};
const canvas = scene.canvas,
gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
const scale = canvas.width / canvas.clientWidth;
const points = entry.trailSegments
.filter((s) => s.toT <= entry.sample.displayT)
.flatMap((s) => s.positions);
if (trail.head?.show) points.push(...trail.head.positions);
if (points.length < 2)
return { ...setup, present: 0, reason: 'no completed path' };
const C = scene.camera.positionCartographic.constructor;
const V = entry.marker.position.constructor;
const lengths = [0];
for (let i = 1; i < points.length; i++)
lengths.push(lengths.at(-1) + V.distance(points[i - 1], points[i]));
const mul = (m, v) =>
[0, 1, 2, 3].map(
(i) =>
m[i] * v[0] + m[i + 4] * v[1] + m[i + 8] * v[2] + m[i + 12] * v[3],
);
const samples = Array.from({ length: 8 }, (_, i) => {
const d = (lengths.at(-1) * (i + 1)) / 9;
let j = 1;
while (j < lengths.length - 1 && lengths[j] < d) j++;
const p = V.lerp(
points[j - 1],
points[j],
(d - lengths[j - 1]) / Math.max(0.001, lengths[j] - lengths[j - 1]),
new V(),
);
const cart = C.fromCartesian(p);
const height = scene.sampleHeight(
cart,
[entry.marker, trail.body, trail.headPrimitive].filter(Boolean),
);
if (Number.isFinite(height)) cart.height = height;
const surface = C.toCartesian(cart);
const q = mul(
scene.camera.frustum.projectionMatrix,
mul(scene.camera.viewMatrix, [surface.x, surface.y, surface.z, 1]),
);
return {
x: ((q[0] / q[3]) * 0.5 + 0.5) * canvas.clientWidth,
y: (0.5 - (q[1] / q[3]) * 0.5) * canvas.clientHeight,
inFront: q[3] > 0,
radius: (Math.SQRT2 * Math.ceil(3 * scale)) / scale,
};
});
const marker = entry.marker.position;
const markerClip = mul(
scene.camera.frustum.projectionMatrix,
mul(scene.camera.viewMatrix, [marker.x, marker.y, marker.z, 1]),
);
const sprite = {
x: ((markerClip[0] / markerClip[3]) * 0.5 + 0.5) * canvas.clientWidth,
y: (0.5 - (markerClip[1] / markerClip[3]) * 0.5) * canvas.clientHeight,
// Include the padded, rotated sprite and its selection bracket.
radius: Math.hypot(entry.marker.width, entry.marker.height) / 2 + 4,
};
const read = () =>
samples.map(({ x, y, inFront }) => {
const r = Math.ceil(3 * scale),
px = Math.round(x * scale),
py = Math.round(canvas.height - 1 - y * scale);
if (
!inFront ||
px < r ||
py < r ||
px + r >= canvas.width ||
py + r >= canvas.height
)
return null;
const data = new Uint8Array((2 * r + 1) ** 2 * 4);
gl.readPixels(
px - r,
py - r,
2 * r + 1,
2 * r + 1,
gl.RGBA,
gl.UNSIGNED_BYTE,
data,
);
return data;
});
const frame = () =>
new Promise((resolve, reject) => {
const timeout = setTimeout(() => {
remove();
reject(new Error('Trail framebuffer did not render within 5 s'));
}, 5000);
const remove = scene.postRender.addEventListener(() => {
remove();
clearTimeout(timeout);
resolve(read());
});
scene.requestRender();
});
const bodyShow = trail.body?.show,
headShow = trail.head?.show,
headPrimitiveShow = trail.headPrimitive?.show,
backingShow = trail.backing?.show;
let showTrail = false;
const applyVisibility = () => {
if (trail.body) trail.body.show = showTrail && bodyShow;
if (trail.headPrimitive)
trail.headPrimitive.show = showTrail && headPrimitiveShow;
if (trail.head) trail.head.show = showTrail && headShow;
if (trail.backing) trail.backing.show = showTrail && backingShow;
};
// Override the layer's frame update in both states; selection stays fixed.
const removeVisibility = scene.preRender.addEventListener(applyVisibility);
const captures = [];
let captureReady = true;
try {
for (const visible of [false, true, false, true]) {
showTrail = visible;
// Let post-processing settle before each measured framebuffer.
for (let i = 0; i < 3; i++) await frame();
captures.push(await frame());
const current = parts.trails.diagnostics();
captureReady &&=
ready() &&
current?.body === trail.body &&
current?.headPrimitive === trail.headPrimitive;
}
} finally {
removeVisibility();
if (trail.body) trail.body.show = bodyShow;
if (trail.headPrimitive) trail.headPrimitive.show = headPrimitiveShow;
if (trail.head) trail.head.show = headShow;
if (trail.backing) trail.backing.show = backingShow;
await frame();
}
const [off, on, offAgain, onAgain] = captures.map((patches) =>
patches.map((p) => (p ? Array.from(p) : null)),
);
return {
...setup,
fixes: entry.track.count,
selected: state._selectedKey === setup.key,
pathMetres: lengths.at(-1),
samples,
on,
off,
onAgain,
offAgain,
sprite,
tilesReady: captureReady,
elapsedDisplayMs: entry.sample.displayT - setup.startDisplayT,
movedMetres: Math.abs(entry.sample.lat - setup.startLat) * 111320,
body: trail.body?.constructor.name,
headStrategy: trail.headStrategy || 'PolylineCollection',
headRebuilds: trail.headRebuilds ?? null,
};
}, setup);
const pixels = reduceTrailPixels(result.on, result.off, result);
result.cost = cost;
result.altitude = altitude;
result.pitch = pitch;
result.present = pixels.present;
result.total = pixels.total;
result.samples = result.samples?.map((s, i) => ({
...s,
hit: pixels.hits[i],
stable: pixels.stable[i],
eligible: pixels.eligible[i],
}));
await page.screenshot({
path: `${shots}/${tag}-${altitude}m-trail-visible.jpg`,
type: 'jpeg',
quality: 95,
});
await writeFile(
`${shots}/${tag}-${altitude}m-trail-visible.json`,
JSON.stringify(result, null, 2),
);
for (const key of ['on', 'off', 'onAgain', 'offAgain']) delete result[key];
check(
name,
result.google &&
result.selected &&
result.fixes >= 5 &&
result.pathMetres > 15 &&
result.elapsedDisplayMs >= 19000 &&
result.movedMetres >= 5 &&
pixels.pass,
JSON.stringify(result),
);
check(
'selected trail stays within 2 MiB rebuild and 2 KiB/frame head uploads',
cost.frames > 30 &&
cost.bodyUploadMax > 0 &&
cost.bodyUploadMax <= 2 * 1024 * 1024 &&
cost.headUploadMax > 0 &&
cost.headUploadMax <= 2048,
JSON.stringify({ altitude, ...cost }),
);
await page.evaluate(() =>
window.__godsEyeView.dataManager.layers
.get('transit')
.module._transitPartsForTest()
.selection.clearSelection(),
);
}
scripts/qa-transit.mjs
+21
View File
@@ -1,4 +1,5 @@
#!/usr/bin/env node
import { runTransitHeadingRegression } from './qa-transit-heading.mjs';
import {
boundPageEvaluations,
reportTransitVisibility,
@@ -16,6 +17,7 @@ import {
runFleetBudgets,
runBostonMatrix,
runBostonLive,
runTrailVisibility,
} from './qa-transit-scenes.mjs';
/**
* Browser proof for the Transit layer against a running app.
@@ -78,6 +80,18 @@ const check = (
failures += 1;
} else if (!passed) failures += 1;
};
// A focused deterministic regression can run independently of live-feed QA.
if (process.argv.includes('--heading-only')) {
try {
await runTransitHeadingRegression(BASE, check);
} catch (error) {
check('heading regression completed', false, error.stack || error.message);
}
console.log(`HEADING: ${failures ? 'FAIL' : 'PASS'} (${failures} failed)`);
process.exit(failures ? 1 : 0);
}
if (runs('heading')) await runTransitHeadingRegression(BASE, check);
const renderingSource = await readFile(
new URL('../src/layers/transit/rendering.js', import.meta.url),
'utf8',
@@ -1774,6 +1788,13 @@ try {
selectStyle,
sampleRendered,
};
if (runs('trail-visible'))
for (const [altitude, pitch] of [
[300, 55],
[600, 45],
[900, 45],
])
await runTrailVisibility({ ...sceneQA, altitude, pitch });
if (runs('budgets')) await runFleetBudgets(sceneQA);
if (runs('matrix')) await runBostonMatrix(sceneQA);
if (runs('boston-live')) await runBostonLive(sceneQA);
scripts/qa-voice-wav.mjs
+34 -5
View File
@@ -2,7 +2,7 @@
/**
* Credentialed AI voice acceptance using a prerecorded Chromium microphone.
*
* Run: node scripts/qa-voice-wav.mjs http://localhost:4189
* Run: node scripts/qa-voice-wav.mjs http://localhost:4189 [--push-to-talk]
*/
import { createHash } from 'node:crypto';
import fs from 'node:fs';
@@ -11,8 +11,13 @@ import { fileURLToPath } from 'node:url';
import puppeteer from 'puppeteer';
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const appUrl = process.argv[2] || 'http://localhost:4189';
const wavPath = process.argv[3]
const pushToTalk = process.argv.includes('--push-to-talk');
const positional = process.argv.slice(2).filter(arg => arg !== '--push-to-talk');
const targetUrl = new URL(positional[0] || 'http://localhost:4189');
// Keep first-run focus changes outside this voice/keyboard acceptance test.
targetUrl.searchParams.set('welcome', '0');
const appUrl = targetUrl.href;
const wavPath = positional[1]
|| path.join(repoRoot, 'scripts', 'fixtures', 'voice', 'full-globe-turn-on-radio.wav');
const expectedFixtureSha256 = 'b57af70db1922b72fec2c6c58348ccd3309e10aa1e8edec2890277dff26cc7bb';
@@ -60,6 +65,7 @@ try {
await page.waitForFunction(() => (
window.__godsEyeView?.voiceCommands
&& document.getElementById('gev-voice-button')
&& document.getElementById('loading-screen')?.classList.contains('hidden')
), { timeout: 30_000 });
const readState = () => page.evaluate(() => {
@@ -81,7 +87,26 @@ try {
});
const initial = await readState();
await page.evaluate(() => document.getElementById('gev-voice-button').click());
let pushToTalkStarted = false;
let microphoneReleased = false;
if (pushToTalk) {
await page.bringToFront();
await page.focus('.cesium-widget canvas');
await page.keyboard.down('Space');
await page.waitForFunction(() => document.querySelector(
'[data-push-to-talk="held"][data-microphone="active"]',
), { timeout: 30_000 });
pushToTalkStarted = true;
// The hash-pinned fixture is 9.2 seconds long and plays once from mic acquisition.
await new Promise(resolve => setTimeout(resolve, 10_000));
await page.keyboard.up('Space');
microphoneReleased = await page.evaluate(() => {
const status = window.__godsEyeView.voiceCommands.status;
return status === 'idle' || Boolean(document.querySelector('[data-microphone="muted"]'));
});
} else {
await page.click('#gev-voice-button');
}
const timeline = [initial];
let lastSignature = JSON.stringify(initial);
@@ -113,10 +138,14 @@ try {
}
const result = {
ok: finalState.voiceStatus === 'idle'
ok: (!pushToTalk || (pushToTalkStarted && microphoneReleased))
&& finalState.voiceStatus === 'idle'
&& finalState.radioAudioState === 'playing'
&& finalState.radioVoiceDucked === false
&& Number(finalState.cameraHeightM) >= 10_000_000,
mode: pushToTalk ? 'push-to-talk' : 'click',
pushToTalkStarted,
microphoneReleased,
fixture: wavPath,
fixtureSha256,
appUrl,
src/app/constructCatalog.js
+1 -1
View File
@@ -117,9 +117,9 @@ export function createApplicationCatalog({
createApplicationTraffic({ source: sources.traffic }),
createApplicationCctv({ surface, source: sources.cctv }),
createApplicationRadio({ surface, source: sources.radio }),
createApplicationTransit({ surface, source: sources.transit }),
createApplicationBikeshare({ source: sources.bikeshare }),
createApplicationDirections(),
createApplicationTransit({ surface, source: sources.transit }),
vessels,
installations,
createApplicationAwareness({
src/app/constructCatalog.test.mjs
+5
View File
@@ -41,6 +41,11 @@ test('catalogs construct distinct layers and classification from their supplied
});
assert.equal(first.layers.length, 21);
assert.ok(first.get('transit'));
const order = first.layers.map(({ id }) => id);
assert.deepEqual(
order.slice(order.indexOf('traffic'), order.indexOf('directions') + 1),
['traffic', 'cctv', 'radio', 'transit', 'bikeshare', 'directions'],
);
assert.ok(first.get('bhote-koshi-2026'));
assert.ok(first.get('bhote-koshi-locator'));
const lifecycle = new LayerLifecycle({});
src/app/tools.js
+2
View File
@@ -21,6 +21,7 @@ export function createApplicationTools({
voice = {},
startChrome,
onSceneDirector,
sceneDataPacks,
signal,
defer,
}) {
@@ -28,6 +29,7 @@ export function createApplicationTools({
const { styleManager, weatherEffects, cockpitCloudEffects } = controls;
const { dataManager } = data;
const sceneDirector = new SceneDirector(viewer, styleManager, dataManager, {
dataPacks: sceneDataPacks,
isMapStackAvailable: (id) =>
mapStackController?.isStackAvailable(id) === true,
});
src/cameraHandoff.test.mjs
+8 -3
View File
@@ -1,3 +1,4 @@
import { LayerBindings } from './ui/layerBindings.js';
import { readShellSource, shellMethod } from './testSupport/readShellSource.mjs';
import { readLayerSource } from './testSupport/readLayerSource.mjs';
import { StyleManager } from './ui/applicationShell.js';
@@ -302,8 +303,8 @@ test('newer navigation, reset, Cockpit, and teardown share one generation', () =
const dispose = body(ui, /async dispose\(\) \{([\s\S]*?)\n \}/, 'dispose');
ordered(dispose, [
'this._disposed = true;',
'this._layerBindings.stop();',
'this._navigation.destroy();',
'this._removeWorldRequestFocusListener?.();',
'await this._contextControls.restoreForDisposal();',
], 'dispose invalidation');
assert.match(shellMethod('destroy').toString(), /this\._stampNavigation\(\)/);
@@ -312,12 +313,16 @@ test('newer navigation, reset, Cockpit, and teardown share one generation', () =
test('teardown synchronously closes immediate camera entry points', () => {
const dispose = body(ui, /async dispose\(\) \{([\s\S]*?)\n \}/, 'dispose');
ordered(dispose, [
'this._disposed = true;',
'this._layerBindings.stop();',
'await this._contextControls.restoreForDisposal();',
], 'synchronous teardown barrier');
ordered(LayerBindings.prototype.stop.toString(), [
'this._disposed = true;',
'this._removeCctvRequestFocusListener?.();',
'this._removeWorldRequestFocusListener?.();',
'this._navigationOwnerChangedRemover?.();',
'await this._contextControls.restoreForDisposal();',
], 'synchronous teardown barrier');
], 'camera bindings close synchronously');
const navigation = body(
ui,
src/cockpitMarkup.test.mjs
+4 -2
View File
@@ -408,7 +408,8 @@ test('fresh Cockpit entry temporarily collapses map panels and exit restores the
assert.match(entryPanels[1], new RegExp(`'${panelId}'`), `${panelId} must collapse on entry`);
}
assert.match(ui, /onEntered: \(\) => this\._panelChrome\.enterCockpit\(\)/);
assert.match(ui, /onEntered: \(\) => this\.enterPanels\(\)/);
assert.match(ui, /enterPanels: \(\) => this\._panelChrome\.enterCockpit\(\)/);
const callback = { 1: shellMethod('enterCockpit').toString() };
assert.ok(callback, 'Cockpit onEntered callback is missing');
assert.match(
@@ -438,7 +439,8 @@ test('fresh Cockpit entry temporarily collapses map panels and exit restores the
'normal Context must not reopen over Cockpit',
);
assert.match(ui, /onExited: \(\) => this\._panelChrome\.exitCockpit\(\)/);
assert.match(ui, /onExited: \(\) => this\.exitPanels\(\)/);
assert.match(ui, /exitPanels: \(\) => this\._panelChrome\.exitCockpit\(\)/);
const exitCallback = { 1: shellMethod('exitCockpit').toString() };
assert.ok(exitCallback, 'Cockpit onExited callback is missing');
assert.match(
src/data/bhoteKoshiLocator.test.mjs
+4
View File
@@ -5,6 +5,8 @@ import { INCIDENT_OVERVIEW_HOLD_SEC, INCIDENT_OVERVIEW_PLACES } from './bhoteKos
import { BHOTE_KOSHI_FLOOD_PATH } from './bhoteKoshiFloodPath.js';
import * as Cesium from 'cesium';
import { SceneDirector } from '../scenes/director.js';
import { createPlaybackClock } from '../director/clock.js';
import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
import {
anchoredCalloutPresentation,
BHOTE_KOSHI_CITY_CONTEXT_PRESENTATION,
@@ -503,6 +505,8 @@ for (const phase of ['timer', 'move-end', 'approach', 'orbit']) {
...nonRunningAnimation(),
});
const director = {
_clock: createPlaybackClock({ isRunning: () => false, timingForShot: () => null, onProgress() {} }),
_scenePacks: createDefaultScenePacks(),
dataManager: { layers: new Map([[layer.id, { module: layer }]]) },
viewer,
_sceneSeekGeneration: 0,
src/data/contactTrailRenderer.js
+132 -52
View File
@@ -21,23 +21,70 @@ export function trailAlpha(ageMs) {
/** One static history batch and one frequently updated head. Never entities. */
export function createContactTrailRenderer(scene) {
const heads = scene.primitives.add(new Cesium.PolylineCollection());
const backing = heads.add({
positions: [],
width: 4,
show: false,
material: Cesium.Material.fromType('Color', {
color: new Cesium.Color(0.02, 0.03, 0.05, 0.8),
}),
});
const head = heads.add({
positions: [],
width: 2,
show: false,
material: Cesium.Material.fromType('Color', {
color: Cesium.Color.WHITE.clone(),
}),
});
const ground =
!!scene.frameState?.context &&
Cesium.GroundPolylinePrimitive.isSupported(scene);
const collection = ground ? scene.groundPrimitives : scene.primitives;
// One 25 m corridor is clipped in material coordinates. Only subdivision
// crossings build geometry; frame updates write a scalar, never vertex buffers.
const headMaterial = (alpha) =>
new Cesium.Material({
fabric: {
type: 'TransitTrailHead',
uniforms: {
color: new Cesium.Color(0.37, 0.94, 0.54, alpha),
fraction: 0,
backing: true,
},
source: `czm_material czm_getMaterial(czm_materialInput materialInput) {
if (materialInput.st.s > fraction) discard;
czm_material m = czm_getDefaultMaterial(materialInput);
bool edge = abs(materialInput.st.t - 0.5) > 0.3;
m.diffuse = czm_gammaCorrect(vec4(edge && backing ? vec3(0.02, 0.03, 0.05) : color.rgb, 1.0)).rgb;
m.alpha = color.a;
return m;
}`,
},
translucent: true,
});
const material = headMaterial(0.8),
depthMaterial = headMaterial(0.55);
depthMaterial.uniforms.backing = false;
const head = { positions: [], show: false, width: 3, material };
const backing = { positions: [], show: false, width: 5 };
let headPrimitive = null,
headRebuilds = 0;
function geometry(positions, width, material = false) {
return ground
? new Cesium.GroundPolylineGeometry({ positions, width, granularity: 0 })
: new Cesium.PolylineGeometry({
positions,
width,
arcType: Cesium.ArcType.NONE,
vertexFormat: material
? Cesium.PolylineMaterialAppearance.VERTEX_FORMAT
: Cesium.PolylineColorAppearance.VERTEX_FORMAT,
});
}
function primitive(instances, appearance, depthFailAppearance) {
return ground
? new Cesium.GroundPolylinePrimitive({
geometryInstances: instances,
appearance,
classificationType: Cesium.ClassificationType.BOTH,
allowPicking: false,
asynchronous: true,
show: visible,
})
: new Cesium.Primitive({
geometryInstances: instances,
appearance,
depthFailAppearance,
allowPicking: false,
asynchronous: false,
show: visible,
});
}
let body = null,
segments = [],
revision = -1,
@@ -68,7 +115,10 @@ export function createContactTrailRenderer(scene) {
completed = -1;
lastSecond = -1;
active = null;
if (body) scene.primitives.remove(body);
if (headPrimitive) collection.remove(headPrimitive);
headPrimitive = null;
head.show = backing.show = false;
if (body) collection.remove(body);
body = null;
const instances = [];
attributeIds.length = 0;
@@ -80,18 +130,13 @@ export function createContactTrailRenderer(scene) {
instances.push(
new Cesium.GeometryInstance({
id: `${i}:${lane}`,
geometry: new Cesium.PolylineGeometry({
positions: segment.positions,
width: lane ? 2 : 4,
arcType: Cesium.ArcType.NONE,
vertexFormat: Cesium.PolylineColorAppearance.VERTEX_FORMAT,
}),
geometry: geometry(segment.positions, lane ? 3 : 5),
attributes: {
color: Cesium.ColorGeometryInstanceAttribute.fromColor(
tint(0.8, !lane),
),
depthFailColor: Cesium.ColorGeometryInstanceAttribute.fromColor(
tint(0.8, !lane),
tint(0.55),
),
show: new Cesium.ShowGeometryInstanceAttribute(false),
},
@@ -100,20 +145,12 @@ export function createContactTrailRenderer(scene) {
}
}
if (instances.length) {
const depthFailAppearance = new Cesium.PolylineColorAppearance({
translucent: true,
fragmentShaderSource:
'in vec4 v_color; void main() { out_FragColor = czm_gammaCorrect(vec4(v_color.rgb, v_color.a * 0.2)); }',
});
body = scene.primitives.add(
new Cesium.Primitive({
geometryInstances: instances,
appearance: new Cesium.PolylineColorAppearance({ translucent: true }),
depthFailAppearance,
allowPicking: false,
asynchronous: false,
show: visible,
}),
body = collection.add(
primitive(
instances,
new Cesium.PolylineColorAppearance({ translucent: true }),
new Cesium.PolylineColorAppearance({ translucent: true }),
),
);
rebuilds++;
}
@@ -122,6 +159,7 @@ export function createContactTrailRenderer(scene) {
if (!sample || !renderedPosition) {
head.show = false;
backing.show = false;
if (headPrimitive) headPrimitive.show = false;
return;
}
const second = Math.floor(sample.displayT / 1000);
@@ -152,8 +190,10 @@ export function createContactTrailRenderer(scene) {
attributeIds[i][lane],
);
if (!attributes) continue;
attributes.show[0] = i <= done ? 1 : 0;
attributes.show = attributes.show;
// Cesium getters return copies. Write back the array we changed.
const show = attributes.show;
show[0] = i <= done ? 1 : 0;
attributes.show = show;
}
}
completed = done;
@@ -166,16 +206,20 @@ export function createContactTrailRenderer(scene) {
attributeIds[i][lane],
);
if (!attributes) continue;
const rgba = attributes.color;
Cesium.ColorGeometryInstanceAttribute.toValue(
tint(alpha, !lane),
attributes.color,
rgba,
);
attributes.color = attributes.color;
Cesium.ColorGeometryInstanceAttribute.toValue(
tint(alpha, !lane),
attributes.depthFailColor,
);
attributes.depthFailColor = attributes.depthFailColor;
attributes.color = rgba;
if (!ground) {
const depthRgba = attributes.depthFailColor;
Cesium.ColorGeometryInstanceAttribute.toValue(
tint(0.55),
depthRgba,
);
attributes.depthFailColor = depthRgba;
}
}
}
lastSecond = second;
@@ -183,16 +227,43 @@ export function createContactTrailRenderer(scene) {
const show = visible && !!segment && sample.fraction < 1;
head.show = show;
backing.show = show;
if (headPrimitive) headPrimitive.show = show;
if (!show) return;
if (active !== segment) {
active = segment;
if (headPrimitive) collection.remove(headPrimitive);
headPrimitive = collection.add(
primitive(
new Cesium.GeometryInstance({
geometry: geometry(segment.positions, 5, true),
}),
new Cesium.PolylineMaterialAppearance({
material,
translucent: true,
}),
new Cesium.PolylineMaterialAppearance({
material: depthMaterial,
translucent: true,
}),
),
);
headRebuilds++;
headPositions[0] = segment.positions[0];
headPositions[1] = endpoint;
}
Cesium.Cartesian3.clone(renderedPosition, endpoint);
head.positions = headPositions;
backing.positions = headPositions;
Cesium.Color.clone(tint(0.8), head.material.uniforms.color);
material.uniforms.fraction = Math.max(
0,
Math.min(
1,
(sample.displayT - segment.fromT) / (segment.toT - segment.fromT),
),
);
depthMaterial.uniforms.fraction = material.uniforms.fraction;
Cesium.Color.clone(tint(0.8), material.uniforms.color);
Cesium.Color.clone(tint(0.55), depthMaterial.uniforms.color);
}
return {
replaceHistory,
@@ -205,12 +276,15 @@ export function createContactTrailRenderer(scene) {
},
setVisible(next) {
visible = next;
heads.show = next;
if (headPrimitive) headPrimitive.show = next && head.show;
if (body) body.show = next;
},
destroy() {
if (body) scene.primitives.remove(body);
scene.primitives.remove(heads);
if (body) collection.remove(body);
if (headPrimitive) collection.remove(headPrimitive);
headPrimitive = null;
material.destroy();
depthMaterial.destroy();
body = null;
segments = [];
},
@@ -222,6 +296,12 @@ export function createContactTrailRenderer(scene) {
body,
head,
backing,
headPrimitive,
headStrategy: ground
? 'draped corridor with material clip'
: 'depth-fail corridor with material clip',
ground,
headRebuilds,
entitiesAdded: 0,
};
},
src/data/contactTrailRenderer.test.mjs
+169 -22
View File
@@ -1,12 +1,14 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import { readFileSync } from 'node:fs';
import { TRAIL_VERTEX_LIMIT } from '../layers/transit/trails.js';
import {
createContactTrailRenderer,
trailAlpha,
} from './contactTrailRenderer.js';
function fixture(t) {
function fixture(t, ground = false) {
for (const key of [
'HTMLCanvasElement',
'HTMLImageElement',
@@ -20,9 +22,21 @@ function fixture(t) {
else globalThis[key] = prior;
});
}
const width = Cesium.ContextLimits._maximumAliasedLineWidth;
Cesium.ContextLimits._maximumAliasedLineWidth = 1;
t.after(() => {
Cesium.ContextLimits._maximumAliasedLineWidth = width;
});
const primitives = new Cesium.PrimitiveCollection();
t.after(() => primitives.destroy());
return { primitives };
const groundPrimitives = new Cesium.PrimitiveCollection();
t.after(() => groundPrimitives.destroy());
return {
primitives,
groundPrimitives,
frameState: { context: { depthTexture: ground } },
globe: { show: false },
};
}
test('body clips future subdivisions, head ends at exact marker, and frames retain geometry', (t) => {
const scene = fixture(t),
@@ -62,7 +76,9 @@ test('body clips future subdivisions, head ends at exact marker, and frames reta
for (const instance of body.geometryInstances) {
assert.deepEqual(
instance.attributes.depthFailColor.value,
instance.attributes.color.value,
Cesium.ColorGeometryInstanceAttribute.toValue(
Cesium.Color.fromCssColorString('#5EF08A').withAlpha(0.55),
),
);
}
body._batchTableAttributeIndices = { color: 0, depthFailColor: 1 };
@@ -81,7 +97,18 @@ test('body clips future subdivisions, head ends at exact marker, and frames reta
);
// Simulate Cesium's completed upload; exercise public attribute writes.
body._ready = true;
body.getGeometryInstanceAttributes = (id) => attributes.get(id);
body.getGeometryInstanceAttributes = (id) => {
const stored = attributes.get(id),
accessor = {};
for (const name of ['show', 'color', 'depthFailColor'])
Object.defineProperty(accessor, name, {
get: () => stored[name].slice(),
set: (value) => {
stored[name] = value.slice();
},
});
return accessor;
};
const marker = Cesium.Cartesian3.lerp(
positions[1],
positions[2],
@@ -95,10 +122,19 @@ test('body clips future subdivisions, head ends at exact marker, and frames reta
[1, 1, 0, 0],
);
for (const a of attributes.values())
assert.deepEqual(a.depthFailColor, a.color);
assert.deepEqual(
a.depthFailColor,
Cesium.ColorGeometryInstanceAttribute.toValue(
Cesium.Color.fromCssColorString('#5EF08A').withAlpha(0.55),
),
);
const result = renderer.diagnostics();
assert.equal(result.body, body);
assert.equal(result.rebuilds, 1);
assert.equal(result.headRebuilds, 1, '120 frames retain head geometry');
assert.equal(result.head.material.uniforms.fraction, 0.5);
assert.equal(result.head.width, 3);
assert.equal(result.backing.width, 5);
assert.ok(Cesium.Cartesian3.equals(result.head.positions.at(-1), marker));
assert.equal(result.head.positions.length, 2);
renderer.setDisplaySample(
@@ -120,24 +156,130 @@ test('trail age curve uses the specified four alpha anchors', () => {
assert.ok(Math.abs(trailAlpha(60000) - 0.625) < 1e-10);
});
test('the maximum prepared body stays below the 2 MiB geometry budget', () => {
const geometry = Cesium.PolylineGeometry.createGeometry(
new Cesium.PolylineGeometry({
positions: [
Cesium.Cartesian3.fromDegrees(-71, 42, 11.5),
Cesium.Cartesian3.fromDegrees(-71, 42.0002, 11.5),
],
width: 2,
arcType: Cesium.ArcType.NONE,
vertexFormat: Cesium.PolylineColorAppearance.VERTEX_FORMAT,
}),
test('ground body and clipped head stay inside rebuild and frame geometry budgets', async () => {
Cesium.ApproximateTerrainHeights._terrainHeights = JSON.parse(
readFileSync(
new URL(
import.meta
.resolve('@cesium/engine/Source/Assets/approximateTerrainHeights.json'),
),
),
);
const bytes =
Object.values(geometry.attributes).reduce(
(total, attribute) => total + (attribute?.values?.byteLength || 0),
const positions = [
Cesium.Cartesian3.fromDegrees(-97.7431, 30.267),
Cesium.Cartesian3.fromDegrees(-97.7431, 30.2672),
];
const start = performance.now();
const instances = async (count) =>
Promise.all(
Array.from(
{ length: count },
async (_, i) =>
new Cesium.GeometryInstance({
id: i,
geometry: await Cesium.GroundPolylineGeometry.createGeometry(
new Cesium.GroundPolylineGeometry({
positions,
width: i % 2 ? 3 : 5,
granularity: 0,
}),
),
}),
),
);
const pipelineBytes = async (count) => {
// Match GroundPolylinePrimitive's internal Primitive options and the
// application's morph-capable scene, including batch IDs and encoding.
const result = Cesium.PrimitivePipeline.combineGeometry({
instances: await instances(count),
projection: new Cesium.GeographicProjection(),
ellipsoid: Cesium.Ellipsoid.WGS84,
modelMatrix: Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY),
elementIndexUintSupported: true,
scene3DOnly: false,
vertexCacheOptimize: false,
compressVertices: false,
createPickOffsets: false,
});
return result.geometries.reduce(
(sum, geometry) =>
sum +
Object.values(geometry.attributes).reduce(
(n, a) => n + (a?.values?.byteLength || 0),
0,
) +
geometry.indices.byteLength,
0,
) + geometry.indices.byteLength;
assert.ok(bytes * 2 * 2047 < 2 * 1024 * 1024);
);
};
const bytes = await pipelineBytes(1);
const bodyInstances = 2 * (TRAIL_VERTEX_LIMIT - 1);
const bodyBytes = await pipelineBytes(bodyInstances);
assert.equal(bytes, 1576, 'measure final encoded and batched geometry');
assert.equal(bodyBytes, 2014128);
const instanceReserve = 64 * bodyInstances;
assert.ok(bodyBytes + instanceReserve <= 2 * 1024 * 1024);
assert.ok(
bytes <= 2048,
'subdivision crossings stay below 2 KiB of head geometry',
);
console.log(
`trail final pipeline: ${bytes} bytes/head crossing, 0 bytes/ordinary head frame, ${bodyBytes} bytes/body (${bodyInstances} instances), ${instanceReserve} bytes instance reserve; geometry CPU ${(performance.now() - start).toFixed(3)} ms`,
);
});
test('supported scenes drape body and clipped head on 3D tiles and retain head geometry', (t) => {
const scene = fixture(t, true),
renderer = createContactTrailRenderer(scene);
const positions = [
Cesium.Cartesian3.fromDegrees(-97.7431, 30.267),
Cesium.Cartesian3.fromDegrees(-97.7431, 30.2672),
];
renderer.replaceHistory({
revision: 1,
segments: [{ fromSeq: 0, toSeq: 1, fromT: 0, toT: 20000, positions }],
});
const first = renderer.diagnostics();
assert.ok(first.body instanceof Cesium.GroundPolylinePrimitive);
assert.equal(first.body.classificationType, Cesium.ClassificationType.BOTH);
assert.ok(scene.groundPrimitives.contains(first.body));
for (const instance of first.body.geometryInstances)
assert.ok(instance.geometry instanceof Cesium.GroundPolylineGeometry);
for (let i = 1; i <= 120; i++)
renderer.setDisplaySample(
{ displayT: i * 100, fromSeq: 0, toSeq: 1, fraction: i / 200 },
positions[1],
);
const result = renderer.diagnostics();
assert.equal(result.body, first.body);
assert.equal(result.headRebuilds, 1);
assert.ok(result.headPrimitive instanceof Cesium.GroundPolylinePrimitive);
assert.equal(result.head.material.uniforms.fraction, 0.6);
assert.match(result.head.material.shaderSource, /discard/);
for (const stack of ['Google', 'OSM', 'Bing', 'Google']) {
scene.globe.show = stack !== 'Google';
renderer.setDisplaySample(
{ displayT: 12000, fromSeq: 0, toSeq: 1, fraction: 0.6 },
positions[1],
);
const retained = renderer.diagnostics();
assert.equal(retained.body, result.body, `${stack}: retained history`);
assert.equal(retained.headPrimitive, result.headPrimitive);
for (const primitive of [retained.body, retained.headPrimitive]) {
assert.equal(
primitive.classificationType,
Cesium.ClassificationType.BOTH,
stack,
);
assert.equal(primitive.show, true, stack);
}
}
renderer.setVisible(false);
assert.equal(result.body.show, false);
assert.equal(result.headPrimitive.show, false);
renderer.destroy();
assert.equal(scene.groundPrimitives.length, 0);
assert.equal(scene.primitives.length, 0);
});
test('subdivision crossings only write the changed show range and age colors once per second', (t) => {
@@ -206,5 +348,10 @@ test('subdivision crossings only write the changed show range and age colors onc
display(1200);
assert.deepEqual(counts, { show: 0, color: 200, depthFailColor: 200 });
for (const a of attributes.values())
assert.deepEqual(a.color, a.depthFailColor);
assert.deepEqual(
a.depthFailColor,
Cesium.ColorGeometryInstanceAttribute.toValue(
Cesium.Color.fromCssColorString('#FF4538').withAlpha(0.55),
),
);
});
src/data/transitIcons.js
+13 -12
View File
@@ -189,20 +189,21 @@ export function transitIcon(kind, px = FLEET_RASTER_PX, options = {}) {
let uri = _iconCache.get(key);
if (!uri) {
const size = VIEW + 2 * frame.pad;
// Sensor signatures use a broad rounded envelope, without dark interior
// joints or a second outline eating into the hot core at display resolution.
const halfW = k === 'bus' || k === 'ferry' || k === 'unknown' ? 48 : 47;
const halfH = 48;
const radius = k === 'subway' ? 8 : k === 'rail' ? 12 : 14;
const capsule = `<path d="M${-halfW + radius},${-halfH} H${halfW - radius} Q${halfW},${-halfH} ${halfW},${-halfH + radius} V${halfH - radius} Q${halfW},${halfH} ${halfW - radius},${halfH} H${-halfW + radius} Q${-halfW},${halfH} ${-halfW},${halfH - radius} V${-halfH + radius} Q${-halfW},${-halfH} ${-halfW + radius},${-halfH} Z" fill="white" />`;
const body = profile === 'mono' ? capsule : BODIES[k];
// Reuse the exact outer path. Sensors fill its interior without panel ink.
const silhouette = BODIES[k].match(/<path d="([^"]+)"/)[1];
const body =
profile === 'mono'
? `<path d="${silhouette}" fill="white" />`
: BODIES[k];
const halo =
frame.units > 0
? body.replace(
/<path d="([^"]+)"\s+fill="white" [^/]*\/>/,
(_m, d) =>
`<path d="${d}" fill="none" stroke="${profile === 'mono' ? '#000000' : '#05080C'}" stroke-opacity="${profile === 'mono' ? 1 : 0.95}" stroke-width="${frame.units.toFixed(2)}" stroke-linejoin="round"/>`,
)
? profile === 'mono'
? `<path d="${silhouette}" fill="none" stroke="#05080C" stroke-opacity="1" stroke-width="${frame.units.toFixed(2)}" stroke-linejoin="round"/>`
: body.replace(
/<path d="([^"]+)"\s+fill="white" [^/]*\/>/,
(_m, d) =>
`<path d="${d}" fill="none" stroke="#05080C" stroke-opacity="0.95" stroke-width="${frame.units.toFixed(2)}" stroke-linejoin="round"/>`,
)
: '';
const svg =
`<svg xmlns="http://www.w3.org/2000/svg" width="${Math.round(px * frame.ratio)}" height="${Math.round(px * frame.ratio)}" viewBox="${-frame.pad} ${-frame.pad} ${size} ${size}">` +
src/data/transitIcons.test.mjs
+128 -24
View File
@@ -32,10 +32,10 @@ test('a haloed glyph draws the dark ring under the shipped white body', () => {
assert.notEqual(plain, haloed);
assert.match(
haloed,
/stroke="#000000" stroke-opacity="1" stroke-width="19\.20"/,
/stroke="#05080C" stroke-opacity="1" stroke-width="14\.77"/,
);
assert.ok(
haloed.indexOf('#000000') < haloed.indexOf('fill="white"'),
haloed.indexOf('#05080C') < haloed.indexOf('fill="white"'),
'ring first, body on top',
);
assert.match(haloed, /viewBox="-\d+ -\d+ \d+ \d+"/, 'padded frame');
@@ -97,40 +97,144 @@ test('all 36 variants retain the specified final halo at both display sizes', as
assert.equal(transitIconCacheSize(), 36);
});
test('sensor bodies cover sixty percent of the padded display with opaque white', async () => {
test('every mono raster preserves the normal silhouette mask and aspect at CRT display size', async () => {
const sharp = (await import('sharp')).default;
const { presetSpriteScale, presetSpriteOutlinePx } =
await import('./transitPresetStyle.js');
const rasterBody = async (svg) => {
// Compare fills in the same frame; the separately tested external halo is excluded.
const d =
[...svg.matchAll(/<path d="([^"]+)" fill="white"/g)][0]?.[1] ??
svg.match(/<path d="([^"]+)"\s+fill="white"/)[1];
const { data, info } = await sharp(
Buffer.from(
`<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" viewBox="-48 -48 96 96"><path d="${d}" fill="white"/></svg>`,
),
)
.ensureAlpha()
.raw()
.toBuffer({ resolveWithObject: true });
const mask = [];
let minX = info.width,
minY = info.height,
maxX = 0,
maxY = 0;
for (let y = 0; y < info.height; y++)
for (let x = 0; x < info.width; x++) {
const alpha = data[(y * info.width + x) * 4 + 3];
mask.push(alpha);
if (alpha > 127) {
minX = Math.min(minX, x);
maxX = Math.max(maxX, x);
minY = Math.min(minY, y);
maxY = Math.max(maxY, y);
}
}
return { mask, aspect: (maxX - minX + 1) / (maxY - minY + 1) };
};
for (const selected of [false, true])
for (const kind of TRANSIT_ICON_KINDS) {
const normal = await rasterBody(
decode(transitIcon(kind, selected ? 96 : 48, { style: 'normal' })),
);
for (const style of ['surveillance', 'thermal', 'noir', 'nvg']) {
const svg = decode(transitIcon(kind, selected ? 96 : 48, { style }));
const mono = await rasterBody(svg);
assert.deepEqual(
mono.mask,
normal.mask,
`${kind}/${style}: no envelope`,
);
assert.ok(
Math.abs(mono.aspect / normal.aspect - 1) <= 0.05,
`${kind}/${style}: aspect`,
);
const display =
(selected ? 30 : 20) * presetSpriteScale(style, selected);
const crt = (selected ? 30 : 20) * presetSpriteScale('retro', selected);
assert.equal(display, crt);
const frame = haloFrame(
presetSpriteOutlinePx(style, selected),
display,
);
const crtFrame = haloFrame(
presetSpriteOutlinePx('retro', selected),
crt,
);
assert.equal(
(display * frame.ratio) / frame.ratio,
(crt * crtFrame.ratio) / crtFrame.ratio,
'unpadded silhouette matches CRT; only external halo padding grows',
);
assert.equal(
(svg.match(/<path /g) || []).length,
2,
'only outer halo and opaque silhouette',
);
assert.match(svg, /fill="white" \/>/);
}
}
});
test('sensor raster halo stays dark across its screen-space band on a white roof', async () => {
const sharp = (await import('sharp')).default;
const { presetSpriteScale, presetSpriteOutlinePx } =
await import('./transitPresetStyle.js');
const { reduceSensorContrast } =
await import('../layers/transit/qaMetrics.js');
const sides = {
bus: 17,
tram: 10,
subway: 11.5,
rail: 10.5,
ferry: 12.5,
unknown: 10,
};
for (const selected of [false, true]) {
const pixels = [];
for (const kind of TRANSIT_ICON_KINDS) {
const display =
(selected ? 30 : 20) * presetSpriteScale('thermal', selected);
assert.equal(display, selected ? 36 : 30);
assert.equal(presetSpriteOutlinePx('thermal', selected), 3);
const frame = haloFrame(
presetSpriteOutlinePx('thermal', selected),
display,
);
const size = Math.round(display * frame.ratio * 8);
const svg = decode(
transitIcon(kind, selected ? 96 : 48, { style: 'thermal' }),
);
const frame = haloFrame(3, display);
const width = Math.round(display * frame.ratio);
const { data, info } = await sharp(Buffer.from(svg))
.resize(width, width)
.ensureAlpha()
.resize(size, size)
.flatten({ background: '#ffffff' })
.raw()
.toBuffer({ resolveWithObject: true });
let white = 0;
for (let i = 0; i < data.length; i += 4)
if (
data[i] >= 240 &&
data[i + 1] >= 240 &&
data[i + 2] >= 240 &&
data[i + 3] >= 240
)
white++;
assert.ok(
white / (info.width * info.height) >= 0.6,
`${kind}/${display}: white ${white / (info.width * info.height)}`,
);
const c = (Math.floor(width / 2) * width + Math.floor(width / 2)) * 4;
assert.deepEqual([...data.subarray(c, c + 4)], [255, 255, 255, 255]);
const sample = (offsetPx) => {
const x = Math.floor(
size / 2 + (offsetPx * size) / (display * frame.ratio),
);
const i = (Math.floor(size / 2) * info.width + x) * info.channels;
return (
(0.299 * data[i] + 0.587 * data[i + 1] + 0.114 * data[i + 2]) / 255
);
};
// The body stays at CRT size; the ring must cover this fixed external band.
const ringMin = sample((sides[kind] * display) / 96 + 1.25);
pixels.push({
key: kind,
verified: true,
centre: sample(0),
ringMin,
ringMax: 1 - ringMin,
background: 1,
});
}
const white = reduceSensorContrast(pixels, 'white', 'thermal');
assert.ok(white.pass, JSON.stringify({ selected, pixels, white }));
const black = reduceSensorContrast(
pixels.map((p) => ({ ...p, centre: 1 - p.centre })),
'black',
'thermal',
);
assert.ok(black.pass, JSON.stringify({ selected, black }));
}
});
src/data/transitPresetStyle.js
+3 -5
View File
@@ -12,7 +12,7 @@
* Encoding per profile, the traffic-dot precedent applied to a glyph:
* - `mono` (surveillance/NVG, thermal/FLIR, noir, cockpit nvg/thermal): the
* sprite is WHITE — the hottest end of grayscale FLIR and of the Ironbow
* ramp, and the brightest phosphor under NVG — drawn larger, with a dark
* ramp, and the brightest phosphor under NVG — at CRT size, with a thin dark
* halo sized in SCREEN pixels so it keeps local contrast on a bright road
* through any luma mapping. Black-hot FLIR inverts it, deliberately: a
* black sprite with a light ring is what a hot object looks like there.
@@ -52,8 +52,8 @@ const PROFILE_BY_STYLE = Object.freeze({
const SPRITE_STYLE = Object.freeze({
mono: Object.freeze({
rgba: Object.freeze([255, 255, 255, 1]),
scale: 1.5,
outlinePx: 3,
scale: 1.3,
outlinePx: 2,
}),
crt: Object.freeze({
scale: 1.3,
@@ -111,8 +111,6 @@ export function presetSpriteRgba(styleName, mode) {
* @returns {number} 1 under the normal profile.
*/
export function presetSpriteScale(styleName, selected = false) {
if (transitStyleProfile(styleName) === 'mono')
return selected ? 36 / 30 : 30 / 20;
return SPRITE_STYLE[transitStyleProfile(styleName)]?.scale ?? 1;
}
src/data/transitPresetStyle.test.mjs
+7 -7
View File
@@ -45,13 +45,13 @@ test('mono: every mode is a white core, larger, with a dark halo in screen pixel
`${style} ${mode}`,
);
}
assert.ok(presetSpriteScale(style) === 1.5, `${style} is drawn larger`);
// At least a whole screen pixel and a half of ring around a five-pixel
// body: thinner than that vanishes through blur and pixelation.
assert.ok(
presetSpriteOutlinePx(style) >= 1.5,
`${style} halo is ${presetSpriteOutlinePx(style)} px`,
);
for (const selected of [false, true]) {
assert.equal(
presetSpriteScale(style, selected),
presetSpriteScale('retro', selected),
);
assert.equal(presetSpriteOutlinePx(style, selected), 2);
}
}
});
src/director/authoring.js
+54
View File
@@ -0,0 +1,54 @@
import { parseSceneDocument, stringifySceneDocument } from './document.js';
/** Build a validated immutable edit while preserving IDs, existing content and provenance. */
export function editSceneDetails(
project,
sceneId,
shotId,
sceneDetails,
shotDetails,
) {
const copy = parseSceneDocument(stringifySceneDocument(project));
const scene = copy.scenes.find((s) => s.id === sceneId),
shot = scene?.shots.find((s) => s.id === shotId);
if (!scene || !shot) throw new Error('Select a scene and shot first');
for (const key of Object.keys(sceneDetails))
if (!['anchors', 'dataPacks'].includes(key))
throw new Error('Unsupported scene detail');
for (const key of Object.keys(shotDetails))
if (
![
'camera',
'move',
'durationSec',
'holdSec',
'dataPackIds',
'interactions',
].includes(key)
)
throw new Error('Unsupported shot detail');
for (const key of ['anchors', 'dataPacks']) {
delete scene[key];
if (Object.hasOwn(sceneDetails, key)) scene[key] = sceneDetails[key];
}
for (const key of [
'camera',
'move',
'durationSec',
'holdSec',
'dataPackIds',
'interactions',
]) {
delete shot[key];
if (Object.hasOwn(shotDetails, key)) shot[key] = shotDetails[key];
}
return parseSceneDocument(stringifySceneDocument(copy));
}
/** Export exactly one authored scene; no live state or service configuration is consulted. */
export function selectSceneDocument(project, sceneId) {
const copy = parseSceneDocument(stringifySceneDocument(project));
const scene = copy.scenes.find((s) => s.id === sceneId);
if (!scene) throw new Error('Select a scene first');
return { ...copy, scenes: [scene] };
}
src/director/camera.js
+54
View File
@@ -0,0 +1,54 @@
/** Portable camera poses and authored motion. Angles are degrees; heights are ellipsoidal meters. */
/** Resolve an inline pose or a scene-local geographic anchor without modifying authored state. */
export function resolveCameraPose(scene, camera) {
if (!camera) return null;
const position = camera.anchorId
? scene?.anchors?.find(({ id }) => id === camera.anchorId)
: camera;
if (!position) throw new Error('Camera anchor is unavailable');
return {
lat: position.lat,
lon: position.lon,
alt: position.alt,
heading: camera.heading ?? 0,
pitch: camera.pitch ?? -35,
roll: camera.roll ?? 0,
};
}
/** Resolve both authored endpoints. An explicit move never depends on the live viewport. */
export function resolveCameraMove(scene, shot) {
if (!shot?.move) return null;
return {
from: resolveCameraPose(scene, shot.move.from),
to: resolveCameraPose(scene, shot.camera),
easing: shot.move.easing,
durationSec: shot.durationSec,
};
}
/** Sample the same authored curve for playback and seeking, taking the short longitude/angle arc. */
export function sampleCameraMove(move, progress) {
const t = Math.max(0, Math.min(1, Number(progress) || 0));
if (t === 0) return { ...move.from };
if (t === 1) return { ...move.to };
const eased =
move.easing === 'linear'
? t
: t < 0.5
? 4 * t ** 3
: 1 - (-2 * t + 2) ** 3 / 2;
const lerp = (a, b) => a + (b - a) * eased;
const angle = (a, b) =>
a + (((((b - a + 540) % 360) + 360) % 360) - 180) * eased;
const { from, to } = move;
return {
lat: lerp(from.lat, to.lat),
lon: ((((angle(from.lon, to.lon) + 180) % 360) + 360) % 360) - 180,
alt: lerp(from.alt, to.alt),
heading: angle(from.heading, to.heading),
pitch: lerp(from.pitch, to.pitch),
roll: angle(from.roll, to.roll),
};
}
src/director/camera.test.mjs
+153
View File
@@ -0,0 +1,153 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { parseSceneDocument, stringifySceneDocument } from './document.js';
import { normalizeProject } from '../scenes/project.js';
import { resolveCameraMove, sampleCameraMove } from './camera.js';
import { sceneSeekState } from './timeline.js';
const fixture = () => ({
version: 4,
scenes: [
{
id: 'scene',
title: 'Cross the dateline',
anchors: [
{
id: 'west',
title: 'Start',
lat: 10,
lon: 179,
alt: 400,
altitudeReference: 'ellipsoid',
},
{
id: 'east',
title: 'End',
lat: 12,
lon: -179,
alt: 800,
altitudeReference: 'ellipsoid',
},
],
shots: [
{
id: 'move',
title: 'Cross',
durationSec: 4,
holdSec: 2,
camera: { anchorId: 'east', heading: 10, pitch: 0, roll: 0 },
move: {
from: { anchorId: 'west', heading: 350, pitch: -40, roll: 0 },
easing: 'linear',
},
},
],
},
],
});
test('version 4 retains anchor identity, references and explicit move edits through normalization', () => {
const raw = fixture();
const project = normalizeProject(parseSceneDocument(JSON.stringify(raw)));
assert.deepEqual(project.scenes[0].anchors, raw.scenes[0].anchors);
assert.deepEqual(
project.scenes[0].shots[0].move,
raw.scenes[0].shots[0].move,
);
assert.deepEqual(
project.scenes[0].shots[0].camera,
raw.scenes[0].shots[0].camera,
);
assert.deepEqual(
normalizeProject(parseSceneDocument(stringifySceneDocument(project))),
project,
);
});
test('v3 unversioned bloom already uses scale 2 and is not migrated again in later formats', () => {
const project = normalizeProject(
parseSceneDocument(
JSON.stringify({
version: 3,
scenes: [
{ shots: [{ visual: { bloom: { enabled: true, intensity: 50 } } }] },
],
}),
),
);
assert.equal(project.version, 6);
assert.equal(project.scenes[0].shots[0].visual.bloom.intensity, 50);
});
test('move endpoints, easing, shortest arcs and hold agree with scene seeking', () => {
const scene = normalizeProject(parseSceneDocument(JSON.stringify(fixture())))
.scenes[0];
const move = resolveCameraMove(scene, scene.shots[0]);
const midpoint = sampleCameraMove(move, 0.5);
assert.equal(midpoint.lon, -180);
assert.equal(midpoint.heading, 360);
assert.equal(midpoint.lat, 11);
assert.equal(midpoint.alt, 600);
assert.equal(midpoint.pitch, -20);
const seek = (p) =>
sceneSeekState(
scene,
p,
(_, shot) => shot.durationSec + shot.holdSec,
(_, shot) => shot.holdSec,
);
assert.deepEqual(seek(1 / 3).camera, midpoint);
assert.deepEqual(seek(0).camera, move.from);
assert.deepEqual(seek(5 / 6).camera, move.to);
assert.equal(seek(5 / 6).holdElapsedSec, 1);
assert.deepEqual(
seek(1 / 3).camera,
midpoint,
'backward seek is independent of previous viewport state',
);
assert.equal(
sampleCameraMove({ ...move, easing: 'cubic-in-out' }, 0.25).lat,
10.125,
);
assert.deepEqual(sampleCameraMove(move, 1), move.to);
});
test('unknown anchors, duplicate IDs, mixed references, bad easing and unspecified altitude are rejected', () => {
for (const mutate of [
(s) => {
s.shots[0].camera.anchorId = 'missing';
},
(s) => {
s.anchors[1].id = 'west';
},
(s) => {
s.anchors[0].altitudeReference = 'terrain';
},
(s) => {
delete s.anchors[0].altitudeReference;
},
(s) => {
s.shots[0].camera.lon = 1;
},
(s) => {
s.shots[0].move.easing = 'bounce';
},
(s) => {
s.shots[0].move.from = { lat: 1, lon: 2, alt: 3 };
},
(s) => {
s.shots[0].durationSec = 0;
},
(s) => {
delete s.shots[0].holdSec;
},
]) {
const project = fixture();
mutate(project.scenes[0]);
assert.throws(() => parseSceneDocument(JSON.stringify(project)), {
name: 'SceneDocumentError',
});
}
const old = fixture();
old.version = 3;
assert.throws(
() => parseSceneDocument(JSON.stringify(old)),
/unsupported field/,
);
});
src/director/cameraDocument.js
+88
View File
@@ -0,0 +1,88 @@
import {
fields,
string,
number,
optional,
array,
fail,
uniqueId,
} from './documentFields.js';
const POSITION = { lat: [-90, 90], lon: [-180, 180], alt: [-12000, 1e9] };
const ORIENTATION = {
heading: [-360, 360],
pitch: [-90, 90],
roll: [-360, 360],
};
function coordinates(value, path, bounds, required, legacy) {
for (const [key, range] of Object.entries(bounds)) {
if (required || Object.hasOwn(value, key))
number(value[key], `${path}.${key}`, ...range, legacy);
}
}
function reference(value, path) {
if (value !== 'ellipsoid')
fail(
path,
'expected ellipsoid height in meters; terrain-relative heights are not supported',
);
}
function pose(value, path, version, anchorIds, explicit = false) {
const anchored = version >= 4 && Object.hasOwn(value || {}, 'anchorId');
fields(value, path, [
...Object.keys(ORIENTATION),
...(anchored
? ['anchorId']
: [
...Object.keys(POSITION),
...(version >= 4 ? ['altitudeReference'] : []),
]),
]);
coordinates(value, path, ORIENTATION, false, version < 3);
if (anchored) {
string(value.anchorId, `${path}.anchorId`);
if (!anchorIds.has(value.anchorId))
fail(`${path}.anchorId`, 'unknown scene anchor');
} else {
coordinates(value, path, POSITION, explicit, version < 3);
if (explicit || Object.hasOwn(value, 'altitudeReference'))
reference(value.altitudeReference, `${path}.altitudeReference`);
}
}
/** Validate scene-local anchor IDs, camera references and explicit motion without reading terrain or applying state. */
export function validateSceneCameras(scene, path, version) {
const anchorIds = new Set();
optional(scene, 'anchors', path, (anchors, field) => {
array(anchors, field, 1024);
anchors.forEach((anchor, i) => {
const at = `${field}[${i}]`;
fields(anchor, at, [
'id',
'title',
...Object.keys(POSITION),
'altitudeReference',
]);
string(anchor.id, `${at}.id`);
uniqueId(anchor, at, anchorIds);
optional(anchor, 'title', at, (v, p) => string(v, p, 4096));
coordinates(anchor, at, POSITION, true, false);
reference(anchor.altitudeReference, `${at}.altitudeReference`);
});
});
scene.shots.forEach((shot, index) => {
const at = `${path}.shots[${index}]`;
optional(shot, 'move', at, (move, field) => {
fields(move, field, ['from', 'easing']);
if (!['linear', 'cubic-in-out'].includes(move.easing))
fail(`${field}.easing`, 'expected linear or cubic-in-out');
pose(move.from, `${field}.from`, version, anchorIds, true);
pose(shot.camera, `${at}.camera`, version, anchorIds, true);
number(shot.durationSec, `${at}.durationSec`, 0.2, 86400, false);
number(shot.holdSec, `${at}.holdSec`, 0, 86400, false);
});
optional(shot, 'camera', at, (camera, field) =>
pose(camera, field, version, anchorIds),
);
});
}
src/director/clock.js
+301
View File
@@ -0,0 +1,301 @@
const clamp01 = (value) => Math.max(0, Math.min(1, value));
/** Own playback timers and scene-clock subscriptions independently of renderer and editor state. */
export function createPlaybackClock(options) {
return new PlaybackClock(options);
}
class PlaybackClock {
constructor({
isRunning,
timingForShot,
onProgress,
now = () => Date.now(),
schedule = (callback, ms) => setInterval(callback, ms),
cancel = (timer) => clearInterval(timer),
}) {
this.isRunning = isRunning;
this.timingForShot = timingForShot;
this.onProgress = onProgress;
this.now = now;
this.schedule = schedule;
this.cancel = cancel;
this._progressTimer = null;
this._shotProgressTimer = null;
this._sceneClockTimer = null;
this._sceneClockListeners = new Set();
this._sceneClockSnapshot = null;
this._destroyed = false;
this._waitGeneration = 0;
this._shotGeneration = 0;
this._sceneGeneration = 0;
this._waiters = new Set();
}
get snapshot() {
return this._sceneClockSnapshot ? { ...this._sceneClockSnapshot } : null;
}
get activeTimers() {
return (
[
this._progressTimer,
this._shotProgressTimer,
this._sceneClockTimer,
].filter((timer) => timer !== null).length + this._waiters.size
);
}
stopShot() {
this._shotGeneration++;
this.cancel(this._shotProgressTimer);
this._shotProgressTimer = null;
}
stopSceneTimer() {
this._sceneGeneration++;
this.cancel(this._sceneClockTimer);
this._sceneClockTimer = null;
}
finish() {
this.cancel(this._progressTimer);
this._progressTimer = null;
this.stopSceneTimer();
}
stop() {
this.cancelWaits();
this.stopShot();
this.finish();
if (
!this._sceneClockSnapshot ||
this._sceneClockSnapshot.stopped ||
this._destroyed
)
return;
this._sceneClockSnapshot = {
...this._sceneClockSnapshot,
running: false,
stopped: true,
};
for (const listener of this._sceneClockListeners) {
try {
listener(this.snapshot);
} catch {
/* Observers cannot block cancellation. */
}
}
}
destroy() {
this.cancelWaits();
this._destroyed = true;
this.stopShot();
this.finish();
this._sceneClockListeners.clear();
this._sceneClockSnapshot = null;
}
cancelWaits() {
this._waitGeneration++;
for (const finish of [...this._waiters]) finish();
}
/** Own cancellable hold delays; Stop and destroy settle pending waiters immediately. */
async wait(ms, token) {
const generation = this._waitGeneration;
const endAt = this.now() + ms;
const current = () =>
!this._destroyed &&
generation === this._waitGeneration &&
!token.cancelled &&
!token.signal?.aborted;
while (current() && this.now() < endAt) {
await new Promise((resolve) => {
const finish = () => {
clearTimeout(timer);
token.signal?.removeEventListener('abort', finish);
this._waiters.delete(finish);
resolve();
};
const timer = setTimeout(finish, 70);
this._waiters.add(finish);
token.signal?.addEventListener('abort', finish, { once: true });
});
}
}
subscribe(listener) {
if (this._destroyed || typeof listener !== 'function') return () => {};
this._sceneClockListeners.add(listener);
if (this._sceneClockSnapshot) listener({ ...this._sceneClockSnapshot });
return () => this._sceneClockListeners.delete(listener);
}
publish(
scene,
shot,
sceneElapsedSec,
{ running = this.isRunning(), seeking = false } = {},
) {
if (this._destroyed || !scene || !shot) return;
const timing = this.timingForShot(scene, shot);
const elapsedSec = Math.max(
0,
Math.min(timing.totalSec, Number(sceneElapsedSec) || 0),
);
this._sceneClockSnapshot = {
sceneId: scene.id,
shotId: shot.id,
shotIndex: timing.shotIndex,
shotCount: scene.shots.length,
sceneElapsedSec: elapsedSec,
sceneDurationSec: timing.totalSec,
sceneProgress: timing.totalSec > 0 ? elapsedSec / timing.totalSec : 0,
running: Boolean(running),
seeking: Boolean(seeking),
};
for (const listener of this._sceneClockListeners) {
try {
listener({ ...this._sceneClockSnapshot });
} catch (error) {
console.warn('[Scenes] Scene clock listener failed:', error);
}
}
}
startRunProgress(totalSec) {
this.cancel(this._progressTimer);
if (this._destroyed) return;
const startMs = this.now();
const totalMs = Math.max(1000, totalSec * 1000);
const timer = this.schedule(() => {
if (this._destroyed || this._progressTimer !== timer || !this.isRunning())
return;
const elapsedMs = this.now() - startMs;
this.onProgress(elapsedMs / totalMs);
}, 100);
this._progressTimer = timer;
}
startShotProgress(token, seconds, from, to, sceneClock = null) {
this.stopShot();
const generation = this._shotGeneration;
if (
generation !== this._shotGeneration ||
this._destroyed ||
token.cancelled ||
token.signal?.aborted ||
this.isRunning()
)
return;
this.onProgress(from);
if (generation !== this._shotGeneration || this._destroyed) return;
if (sceneClock) {
this.publish(
sceneClock.scene,
sceneClock.shot,
sceneClock.sceneElapsedFrom,
{ running: false },
);
}
if (
generation !== this._shotGeneration ||
this._destroyed ||
token.cancelled ||
token.signal?.aborted ||
this.isRunning()
)
return;
if (seconds <= 0) {
this.onProgress(to);
if (generation !== this._shotGeneration || this._destroyed) return;
if (sceneClock) {
this.publish(
sceneClock.scene,
sceneClock.shot,
sceneClock.sceneElapsedTo,
{ running: false },
);
}
return;
}
const startedAt = this.now();
const timer = this.schedule(() => {
if (this._shotProgressTimer !== timer) return;
if (
generation !== this._shotGeneration ||
this._destroyed ||
token.cancelled ||
token.signal?.aborted ||
this.isRunning()
) {
this.cancel(timer);
if (this._shotProgressTimer === timer) this._shotProgressTimer = null;
return;
}
const fraction = clamp01((this.now() - startedAt) / (seconds * 1000));
this.onProgress(from + (to - from) * fraction);
if (generation !== this._shotGeneration || this._destroyed) return;
if (sceneClock) {
this.publish(
sceneClock.scene,
sceneClock.shot,
sceneClock.sceneElapsedFrom +
(sceneClock.sceneElapsedTo - sceneClock.sceneElapsedFrom) *
fraction,
{ running: false },
);
}
if (fraction >= 1) {
this.cancel(timer);
if (this._shotProgressTimer === timer) this._shotProgressTimer = null;
}
}, 100);
timer.unref?.();
this._shotProgressTimer = timer;
}
startScene(scene, shot, token) {
this.stopSceneTimer();
const generation = this._sceneGeneration;
const timing = this.timingForShot(scene, shot);
if (
generation !== this._sceneGeneration ||
this._destroyed ||
token.cancelled ||
token.signal?.aborted
)
return timing;
const startedAt = this.now();
this.publish(scene, shot, timing.startElapsedSec, {
running: true,
});
if (
generation !== this._sceneGeneration ||
this._destroyed ||
token.cancelled ||
token.signal?.aborted
)
return timing;
const timer = this.schedule(() => {
if (this._sceneClockTimer !== timer) return;
if (
this._destroyed ||
token.cancelled ||
token.signal?.aborted ||
!this.isRunning()
) {
this.cancel(timer);
if (this._sceneClockTimer === timer) this._sceneClockTimer = null;
return;
}
const shotElapsedSec = Math.min(
timing.durationSec,
(this.now() - startedAt) / 1000,
);
this.publish(scene, shot, timing.startElapsedSec + shotElapsedSec, {
running: true,
});
}, 50);
timer.unref?.();
this._sceneClockTimer = timer;
return timing;
}
}
src/director/clock.test.mjs
+173
View File
@@ -0,0 +1,173 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createPlaybackClock } from './clock.js';
const scene = { id: 'scene', shots: [{ id: 'shot' }] };
const shot = scene.shots[0];
const timing = {
shotIndex: 0,
totalSec: 4,
durationSec: 4,
startElapsedSec: 0,
};
function fixture() {
const timers = new Map();
let id = 0,
now = 0,
running = true;
const progress = [];
const clock = createPlaybackClock({
isRunning: () => running,
timingForShot: () => timing,
onProgress: (value) => progress.push(value),
now: () => now,
schedule: (callback) => {
timers.set(++id, callback);
return id;
},
cancel: (handle) => timers.delete(handle),
});
return {
clock,
timers,
progress,
time: (value) => {
now = value;
},
running: (value) => {
running = value;
},
};
}
test('Stop releases every clock timer and queued callbacks cannot publish later', () => {
const f = fixture();
const observed = [];
f.clock.subscribe((snapshot) => observed.push(snapshot));
f.clock.startRunProgress(4);
f.clock.startScene(scene, shot, { cancelled: false });
f.time(2000);
for (const tick of f.timers.values()) tick();
assert.equal(f.clock.snapshot.sceneElapsedSec, 2);
const stale = [...f.timers.values()];
f.clock.stop();
assert.equal(f.clock.activeTimers, 0);
assert.equal(f.timers.size, 0);
assert.equal(f.clock.snapshot.stopped, true);
const count = observed.length,
progressCount = f.progress.length;
f.time(3000);
for (const tick of stale) tick();
assert.equal(observed.length, count);
assert.equal(f.progress.length, progressCount);
});
test('replacing a shot clock rejects the old callback without clearing the replacement', () => {
const f = fixture();
f.clock.startScene(scene, shot, {});
const stale = [...f.timers.values()][0];
f.time(1000);
f.clock.startScene(scene, shot, {});
f.time(2000);
stale();
assert.equal(f.clock.snapshot.sceneElapsedSec, 0);
assert.equal(f.clock.activeTimers, 1);
[...f.timers.values()][0]();
assert.equal(f.clock.snapshot.sceneElapsedSec, 1);
f.clock.destroy();
});
test('direct-load progress finishes once and snapshots cannot mutate the clock', () => {
const f = fixture();
f.running(false);
f.clock.startShotProgress({}, 2, 0.25, 0.75, {
scene,
shot,
sceneElapsedFrom: 1,
sceneElapsedTo: 3,
});
const tick = [...f.timers.values()][0];
f.time(1000);
tick();
assert.equal(f.progress.at(-1), 0.5);
assert.equal(f.clock.snapshot.sceneElapsedSec, 2);
const copy = f.clock.snapshot;
copy.sceneElapsedSec = 99;
assert.equal(f.clock.snapshot.sceneElapsedSec, 2);
f.time(2000);
tick();
assert.equal(f.progress.at(-1), 0.75);
assert.equal(f.clock.activeTimers, 0);
const count = f.progress.length;
tick();
assert.equal(f.progress.length, count);
});
test('aborted starts and destruction during initial notification leave no timers or listeners', () => {
const f = fixture();
const controller = new AbortController();
controller.abort();
f.clock.startScene(scene, shot, { signal: controller.signal });
assert.equal(f.timers.size, 0);
let calls = 0;
f.clock.subscribe(() => {
calls++;
f.clock.destroy();
});
f.clock.startScene(scene, shot, {});
assert.equal(calls, 1);
assert.equal(f.clock.activeTimers, 0);
f.clock.startRunProgress(4);
f.clock.publish(scene, shot, 1);
f.clock.subscribe(() => calls++);
assert.equal(calls, 1);
assert.equal(f.timers.size, 0);
});
test('Stop, abort and destroy settle long holds immediately and release their deadlines', async () => {
for (const action of ['stop', 'abort', 'destroy']) {
const clock = createPlaybackClock({
isRunning: () => true,
timingForShot: () => timing,
onProgress() {},
});
const abort = new AbortController();
const wait = clock.wait(60000, { signal: abort.signal });
assert.equal(clock.activeTimers, 1);
if (action === 'abort') abort.abort();
else clock[action]();
await wait;
assert.equal(clock.activeTimers, 0);
clock.destroy();
}
});
test('a subscriber can Stop or replace the initial clock without the old start acquiring a timer', () => {
for (const action of ['stop', 'replace']) {
const f = fixture();
let first = true;
f.clock.subscribe(() => {
if (!first) return;
first = false;
if (action === 'stop') f.clock.stop();
else f.clock.startScene(scene, { id: 'replacement' }, {});
});
f.clock.startScene(scene, shot, {});
assert.equal(f.timers.size, action === 'stop' ? 0 : 1);
assert.equal(
f.clock.snapshot.shotId,
action === 'stop' ? shot.id : 'replacement',
);
f.clock.destroy();
}
const f = fixture();
f.running(false);
f.clock.subscribe(() => f.clock.stop());
f.clock.startShotProgress({}, 10, 0, 1, {
scene,
shot,
sceneElapsedFrom: 0,
sceneElapsedTo: 4,
});
assert.equal(f.timers.size, 0);
});
src/director/document.js
+186
View File
@@ -0,0 +1,186 @@
/** Bounded, renderer-independent validation for authored scene documents. */
import {
SCENE_DOCUMENT_LIMITS,
fail,
object,
fields,
string,
number,
optional,
array,
ids,
uniqueId,
jsonTree,
} from './documentFields.js';
import { validateSceneDataPacks } from './packs/manifest.js';
import { validateSceneCameras } from './cameraDocument.js';
export { SCENE_DOCUMENT_LIMITS, SceneDocumentError } from './documentFields.js';
import { validateSceneInteractions } from './interactions/document.js';
export const SCENE_DOCUMENT_VERSION = 6;
function visual(value, path, legacy) {
fields(value, path, [
'style',
'bloom',
'sharpen',
'hud',
'detection',
'scope',
'mapStack',
'styleParams',
]);
for (const key of ['style', 'mapStack']) optional(value, key, path, string);
optional(value, 'styleParams', path, object);
const specs = {
bloom: { enabled: 'boolean', intensity: [-100, 10000], version: [1, 100] },
sharpen: { enabled: 'boolean', intensity: [0, 100] },
hud: { visible: 'boolean', variant: 'string' },
detection: {
mode: 'string',
density: [0, 100],
allocation: 'string',
fadePct: [0, 100],
outsideOpacityPct: [0, 100],
},
scope: { enabled: 'boolean', featherPct: [0, 100] },
};
for (const [key, spec] of Object.entries(specs))
optional(value, key, path, (entry, field) => {
fields(entry, field, Object.keys(spec));
for (const [name, type] of Object.entries(spec))
optional(entry, name, field, (item, at) => {
if (Array.isArray(type)) number(item, at, ...type, legacy);
else if (type === 'string') string(item, at);
else if (typeof item !== 'boolean') fail(at, 'expected a boolean');
});
});
}
/** Validate a parsed scene project without mutating it or applying any state. */
export function validateSceneDocument(project) {
jsonTree(project, '$', { nodes: 0 });
fields(project, '$', [
'version',
'createdAt',
'updatedAt',
'installedBuiltInSceneIds',
'scenes',
]);
const version = Object.hasOwn(project, 'version') ? project.version : 1;
if (![1, 2, 3, 4, 5, 6].includes(version))
fail('$.version', 'unsupported scene project version');
const legacy = version < 3;
for (const key of ['createdAt', 'updatedAt'])
optional(project, key, '$', string);
optional(project, 'installedBuiltInSceneIds', '$', ids);
array(project.scenes, '$.scenes', SCENE_DOCUMENT_LIMITS.scenes);
const sceneIds = new Set();
let shotCount = 0;
project.scenes.forEach((scene, index) => {
const path = `$.scenes[${index}]`;
fields(scene, path, [
'id',
'title',
'releaseLayerIds',
'appliedShotPacks',
'shots',
...(version >= 4 ? ['anchors'] : []),
...(version >= 5 ? ['dataPacks'] : []),
]);
uniqueId(scene, path, sceneIds);
optional(scene, 'title', path, (v, p) => string(v, p, 4096));
optional(scene, 'releaseLayerIds', path, ids);
optional(scene, 'appliedShotPacks', path, (packs, field) => {
array(packs, field);
const packIds = new Set();
packs.forEach((pack, i) => {
const at = `${field}[${i}]`;
fields(pack, at, ['id', 'version', 'shotBindings']);
string(pack.id, `${at}.id`);
uniqueId(pack, at, packIds);
optional(pack, 'version', at, (v, p) =>
number(v, p, 1, 1000000, legacy),
);
optional(pack, 'shotBindings', at, (bindings, p) => {
object(bindings, p);
for (const [title, id] of Object.entries(bindings))
string(id, `${p}.${title}`);
});
});
});
array(scene.shots, `${path}.shots`);
shotCount += scene.shots.length;
if (shotCount > SCENE_DOCUMENT_LIMITS.shots)
fail(`${path}.shots`, 'too many shots in project');
const shotIds = new Set();
scene.shots.forEach((shot, i) => {
const at = `${path}.shots[${i}]`;
fields(shot, at, [
'id',
'title',
'durationSec',
'holdSec',
'camera',
'visual',
'layers',
'sourcePackId',
'sourcePackVersion',
...(version >= 4 ? ['move'] : []),
...(version >= 5 ? ['dataPackIds'] : []),
...(version >= 6 ? ['interactions'] : []),
]);
uniqueId(shot, at, shotIds);
optional(shot, 'title', at, (v, p) => string(v, p, 4096));
optional(shot, 'sourcePackId', at, string);
optional(shot, 'sourcePackVersion', at, (v, p) =>
number(v, p, 1, 1000000, legacy),
);
optional(shot, 'durationSec', at, (v, p) =>
number(v, p, 0, 86400, legacy),
);
optional(shot, 'holdSec', at, (v, p) => number(v, p, 0, 86400, legacy));
optional(shot, 'visual', at, (v, p) => visual(v, p, legacy));
optional(shot, 'layers', at, (layers, field) => {
object(layers, field);
for (const [id, entry] of Object.entries(layers)) {
string(id, field);
if (typeof entry === 'boolean') continue;
const p = `${field}.${id}`;
fields(entry, p, ['enabled', 'params']);
if (typeof entry.enabled !== 'boolean')
fail(`${p}.enabled`, 'expected a boolean');
optional(entry, 'params', p, object);
}
});
});
validateSceneCameras(scene, path, version);
validateSceneDataPacks(scene, path);
validateSceneInteractions(scene, path);
});
return project;
}
/** Read bounded JSON. No URLs, modules or actions are executed during import. */
export function parseSceneDocument(text) {
if (
typeof text !== 'string' ||
text.length > SCENE_DOCUMENT_LIMITS.bytes ||
new TextEncoder().encode(text).byteLength > SCENE_DOCUMENT_LIMITS.bytes
)
fail('$', 'file exceeds 5 MiB');
let parsed;
try {
parsed = JSON.parse(text);
} catch {
fail('$', 'invalid JSON');
}
return validateSceneDocument(parsed);
}
/** Export authored project fields only; callers pass the project, never run state. */
export function stringifySceneDocument(project) {
// Round-trip drops optional undefined fields created by the editor.
const text = JSON.stringify(project, null, 2);
parseSceneDocument(text);
return text;
}
src/director/document.test.mjs
+161
View File
@@ -0,0 +1,161 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
parseSceneDocument,
stringifySceneDocument,
validateSceneDocument,
SCENE_DOCUMENT_LIMITS,
} from './document.js';
import { createDefaultProject, normalizeProject } from '../scenes/project.js';
const fixture = () => ({
version: 3,
scenes: [
{
id: 'scene',
title: 'My scene',
shots: [
{
id: 'shot',
title: 'My shot',
durationSec: 3,
holdSec: 0,
camera: { lat: 1, lon: 2, alt: 42, pitch: 0 },
layers: {
traffic: { enabled: true, params: { nested: [1, 'two', null] } },
},
},
],
},
],
});
test('all built-in authored content exports and normalizes without edit loss', () => {
const project = createDefaultProject();
const migrated = normalizeProject(
parseSceneDocument(stringifySceneDocument(project)),
);
assert.deepEqual(
JSON.parse(stringifySceneDocument(migrated)),
JSON.parse(stringifySceneDocument(project)),
);
const edited = normalizeProject(fixture());
edited.scenes[0].appliedShotPacks = [
{ id: 'pack', version: 3, shotBindings: { Original: 'shot' } },
];
assert.deepEqual(
normalizeProject(parseSceneDocument(stringifySceneDocument(edited))),
edited,
);
assert.equal(edited.scenes[0].shots[0].camera.pitch, 0);
assert.equal(edited.scenes[0].shots[0].camera.alt, 42);
});
test('v1/v2 bloom migrates once; IDs, edits, pack bindings and zero holds survive', () => {
for (const version of [undefined, 1, 2]) {
const project = fixture();
project.version = version;
project.scenes[0].shots[0].visual = {
bloom: { enabled: true, intensity: 25 },
};
const migrated = normalizeProject(
parseSceneDocument(JSON.stringify(project)),
);
assert.equal(migrated.version, 6);
assert.equal(migrated.scenes[0].shots[0].visual.bloom.intensity, 150);
assert.equal(migrated.scenes[0].shots[0].id, 'shot');
assert.deepEqual(
normalizeProject(parseSceneDocument(stringifySceneDocument(migrated))),
migrated,
);
}
});
test('an intentionally empty project stays empty', () => {
assert.deepEqual(
normalizeProject(parseSceneDocument('{"version":3,"scenes":[]}')).scenes,
[],
);
});
test('missing legacy IDs become stable after the first saved migration', () => {
const project = { scenes: [{ shots: [{}] }] };
const migrated = normalizeProject(validateSceneDocument(project));
assert.ok(migrated.scenes[0].id);
assert.ok(migrated.scenes[0].shots[0].id);
assert.deepEqual(
normalizeProject(parseSceneDocument(stringifySceneDocument(migrated))),
migrated,
);
});
test('invalid shapes, versions, unknown fields and unsafe keys fail with field paths', () => {
for (const text of [
'null',
'[]',
'{}',
'{"version":99,"scenes":[]}',
'{"version":3,"scenes":[],"run":{}}',
'{"scenes":[],"__proto__":{}}',
]) {
assert.throws(() => parseSceneDocument(text), {
name: 'SceneDocumentError',
});
}
const project = fixture();
project.scenes[0].shots[0].camera.lat = 91;
assert.throws(
() => validateSceneDocument(project),
/\$\.scenes\[0\]\.shots\[0\]\.camera.lat/,
);
project.scenes[0].shots[0].camera.lat = 1;
project.scenes[0].shots.push(structuredClone(project.scenes[0].shots[0]));
assert.throws(() => validateSceneDocument(project), /duplicate ID/);
});
test('document byte, nesting, collection, finite-number and string bounds are enforced', () => {
assert.throws(
() => parseSceneDocument(' '.repeat(SCENE_DOCUMENT_LIMITS.bytes + 1)),
/5 MiB/,
);
assert.throws(
() =>
parseSceneDocument(
JSON.stringify({
scenes: [],
createdAt: 'é'.repeat(SCENE_DOCUMENT_LIMITS.bytes / 2),
}),
),
/5 MiB/,
);
const project = fixture();
project.scenes[0].shots[0].camera.lat = Infinity;
assert.throws(() => validateSceneDocument(project), /JSON value/);
project.scenes[0].shots[0].camera.lat = 1;
let nested = project.scenes[0].shots[0].layers.traffic.params;
for (let i = 0; i < 30; i++) nested = nested.child = {};
assert.throws(() => validateSceneDocument(project), /complexity/);
assert.throws(
() => validateSceneDocument({ scenes: Array(257).fill({ shots: [] }) }),
/256/,
);
});
test('captured scope and extended detection edits survive migration', () => {
const project = fixture();
project.scenes[0].shots[0].visual = {
scope: { enabled: true, featherPct: 11 },
detection: {
mode: 'DENSE',
density: 75,
allocation: 'ELASTIC',
fadePct: 7,
outsideOpacityPct: 1,
},
};
const migrated = normalizeProject(
parseSceneDocument(JSON.stringify(project)),
);
assert.deepEqual(
migrated.scenes[0].shots[0].visual.scope,
project.scenes[0].shots[0].visual.scope,
);
assert.deepEqual(
migrated.scenes[0].shots[0].visual.detection,
project.scenes[0].shots[0].visual.detection,
);
});
src/director/documentFields.js
+94
View File
@@ -0,0 +1,94 @@
/** Shared bounded JSON and field checks for scene formats. */
export const SCENE_DOCUMENT_LIMITS = Object.freeze({
bytes: 5 * 1024 * 1024,
scenes: 256,
shots: 10000,
collection: 10000,
depth: 24,
nodes: 200000,
string: 65536,
});
/** A project error identifies a field without echoing its supplied value. */
export class SceneDocumentError extends Error {
constructor(path, reason) {
super(`${path}: ${reason}`);
this.name = 'SceneDocumentError';
this.path = path;
}
}
export const fail = (path, reason) => {
throw new SceneDocumentError(path, reason);
};
export const object = (value, path) => {
if (!value || typeof value !== 'object' || Array.isArray(value))
fail(path, 'expected an object');
};
export function fields(value, path, allowed) {
object(value, path);
for (const key of Object.keys(value)) {
if (!allowed.includes(key)) fail(`${path}.${key}`, 'unsupported field');
}
}
export function string(value, path, max = 256) {
if (typeof value !== 'string' || !value.trim() || value.length > max)
fail(path, `expected nonempty text, at most ${max} characters`);
}
export function number(value, path, min, max, legacy) {
const numeric =
legacy && typeof value === 'string' && value.trim() ? Number(value) : value;
if (
typeof numeric !== 'number' ||
!Number.isFinite(numeric) ||
numeric < min ||
numeric > max
)
fail(path, `expected a number from ${min} to ${max}`);
}
export function optional(value, key, path, check) {
if (Object.hasOwn(value, key)) check(value[key], `${path}.${key}`);
}
export function array(value, path, max = SCENE_DOCUMENT_LIMITS.collection) {
if (!Array.isArray(value) || value.length > max)
fail(path, `expected an array of at most ${max} entries`);
}
export function ids(value, path) {
array(value, path);
value.forEach((id, index) => string(id, `${path}[${index}]`));
}
export function uniqueId(value, path, seen) {
if (!Object.hasOwn(value, 'id')) return; // Legacy omissions receive an ID once during migration.
string(value.id, `${path}.id`);
if (seen.has(value.id)) fail(`${path}.id`, 'duplicate ID');
seen.add(value.id);
}
export function jsonTree(value, path, budget, depth = 0) {
if (
++budget.nodes > SCENE_DOCUMENT_LIMITS.nodes ||
depth > SCENE_DOCUMENT_LIMITS.depth
)
fail(path, 'project complexity limit exceeded');
if (value === null || typeof value === 'boolean') return;
if (typeof value === 'string') {
if (value.length > SCENE_DOCUMENT_LIMITS.string)
fail(path, 'text is too long');
return;
}
if (typeof value === 'number' && Number.isFinite(value)) return;
if (!value || typeof value !== 'object') fail(path, 'expected a JSON value');
if (
Object.getPrototypeOf(value) !== Object.prototype &&
!Array.isArray(value) &&
Object.getPrototypeOf(value) !== null
)
fail(path, 'expected a JSON object');
const entries = Object.entries(value);
if (entries.length > SCENE_DOCUMENT_LIMITS.collection)
fail(path, 'too many entries');
for (const [key, child] of entries) {
if (['__proto__', 'constructor', 'prototype'].includes(key))
fail(path, 'unsafe object key');
if (key.length > 256) fail(path, 'field name is too long');
jsonTree(child, `${path}.${key}`, budget, depth + 1);
}
}
src/director/interactions/document.js
+96
View File
@@ -0,0 +1,96 @@
import {
array,
fields,
string,
optional,
uniqueId,
fail,
} from '../documentFields.js';
/** Validate inert, scene-local actions. Feature existence is checked after asset loading. */
export function validateSceneInteractions(scene, path) {
const packs = new Map((scene.dataPacks || []).map((p) => [p.id, p]));
const anchors = new Set((scene.anchors || []).map((a) => a.id));
const shots = new Map(scene.shots.map((s) => [s.id, s]));
scene.shots.forEach((shot, index) => {
optional(shot, 'interactions', `${path}.shots[${index}]`, (items, at) => {
array(items, at, 64);
const seen = new Set();
items.forEach((item, i) => {
const field = `${at}[${i}]`;
fields(item, field, ['id', 'label', 'target', 'action']);
string(item.id, field);
uniqueId(item, field, seen);
string(item.label, field, 256);
fields(item.target, `${field}.target`, ['packId', 'featureId']);
string(item.target.packId, field);
string(item.target.featureId, field);
if (
packs.get(item.target.packId)?.format !== 'geojson' ||
!shot.dataPackIds?.includes(item.target.packId)
)
fail(field, 'target must belong to a selected GeoJSON pack');
const a = item.action;
const specs = {
card: ['text', 'url'],
focus: ['anchorId'],
shot: ['shotId'],
layer: ['layerId', 'enabled'],
};
if (!a || !Object.hasOwn(specs, a.type))
fail(field, 'unsupported action');
string(a.type, `${field}.action.type`);
fields(a, `${field}.action`, ['type', ...specs[a.type]]);
const reference = {
focus: 'anchorId',
shot: 'shotId',
layer: 'layerId',
}[a.type];
if (reference) string(a[reference], `${field}.action.${reference}`);
if (a.type === 'card') {
string(a.text, field, 4096);
optional(a, 'url', field, (url, at) => {
string(url, at, 2048);
let parsed;
try {
parsed = new URL(url);
} catch {
fail(at, 'expected HTTPS source URL');
}
if (
parsed.protocol !== 'https:' ||
parsed.username ||
parsed.password ||
parsed.search ||
parsed.hash
)
fail(
at,
'expected HTTPS source URL without credentials, query or fragment',
);
});
} else if (a.type === 'focus' && !anchors.has(a.anchorId))
fail(field, 'unknown anchor');
else if (a.type === 'shot') {
const target = shots.get(a.shotId);
if (!target) fail(field, 'unknown shot');
// A transition must restore every layer this shot can change.
for (const entry of items)
if (
entry?.action?.type === 'layer' &&
!Object.hasOwn(target.layers || {}, entry.action.layerId)
)
fail(
field,
'target shot must declare interactive layer baseline',
);
} else if (a.type === 'layer') {
if (!Object.hasOwn(shot.layers || {}, a.layerId))
fail(field, 'layer must have an explicit shot baseline');
if (typeof a.enabled !== 'boolean')
fail(field, 'expected enabled boolean');
}
});
});
});
}
src/director/interactions/interactions.test.mjs
+247
View File
@@ -0,0 +1,247 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { parseSceneDocument, stringifySceneDocument } from '../document.js';
import { normalizeProject } from '../../scenes/project.js';
import { createInteractionSession } from './session.js';
const fixture = () => ({
version: 6,
scenes: [
{
id: 'scene',
anchors: [
{
id: 'view',
lat: 1,
lon: 2,
alt: 3000,
altitudeReference: 'ellipsoid',
},
],
dataPacks: [
{
id: 'data',
version: 1,
format: 'geojson',
source: { adapter: 'assets', path: 'test.json' },
attribution: { text: 'Example', license: 'CC0' },
placement: { altitudeReference: 'ellipsoid' },
},
],
shots: [
{
id: 'one',
layers: { traffic: false },
dataPackIds: ['data'],
interactions: [
{
id: 'card',
label: 'Read',
target: { packId: 'data', featureId: 'point' },
action: {
type: 'card',
text: '<script>text only</script>',
url: 'https://example.org/source',
},
},
{
id: 'focus',
label: 'Focus',
target: { packId: 'data', featureId: 'point' },
action: { type: 'focus', anchorId: 'view' },
},
{
id: 'layer',
label: 'Traffic',
target: { packId: 'data', featureId: 'point' },
action: { type: 'layer', layerId: 'traffic', enabled: true },
},
{
id: 'next',
label: 'Next',
target: { packId: 'data', featureId: 'point' },
action: { type: 'shot', shotId: 'two' },
},
],
},
{ id: 'two', layers: { traffic: false } },
],
},
],
});
test('all four inert actions survive validation, migration and export without executing content', () => {
const input = fixture();
const output = JSON.parse(
stringifySceneDocument(
normalizeProject(parseSceneDocument(JSON.stringify(input))),
),
);
assert.deepEqual(
output.scenes[0].shots[0].interactions,
input.scenes[0].shots[0].interactions,
);
});
test('reject unknown fields, executable syntax, invalid references and missing reset baselines', () => {
const mutations = [
(p) => (p.version = 5),
(p) => {
p.scenes[0].shots[0].layers.undefined = false;
delete p.scenes[0].shots[0].interactions[2].action.layerId;
},
(p) => (p.scenes[0].shots[0].interactions[0].action.type = ['card']),
(p) => (p.scenes[0].shots[0].interactions[2].action.layerId = ['traffic']),
(p) => (p.scenes[0].shots[0].interactions = null),
(p) =>
p.scenes[0].shots[0].interactions.push(
p.scenes[0].shots[0].interactions[0],
),
(p) => (p.scenes[0].shots[0].interactions[0].action.code = 'alert(1)'),
(p) =>
(p.scenes[0].shots[0].interactions[0].action.url = 'javascript:alert(1)'),
(p) =>
(p.scenes[0].shots[0].interactions[0].action.url =
'https://user:[email protected]/'),
(p) =>
(p.scenes[0].shots[0].interactions[0].action.url =
'https://example.org/?token=secret'),
(p) => (p.scenes[0].shots[0].interactions[0].target.packId = 'missing'),
(p) => (p.scenes[0].shots[0].dataPackIds = []),
(p) => (p.scenes[0].shots[0].interactions[1].action.anchorId = 'missing'),
(p) => (p.scenes[0].shots[0].interactions[2].action.layerId = 'missing'),
(p) => (p.scenes[0].shots[0].interactions[2].action.enabled = 'yes'),
(p) => (p.scenes[0].shots[0].interactions[3].action.shotId = 'missing'),
(p) => (p.scenes[0].shots[1].layers = {}),
(p) =>
(p.scenes[0].shots[0].interactions = Array.from(
{ length: 65 },
(_, i) => ({ ...p.scenes[0].shots[0].interactions[0], id: String(i) }),
)),
];
for (const mutate of mutations) {
const p = fixture();
mutate(p);
assert.throws(() => parseSceneDocument(JSON.stringify(p)));
}
});
test('pending actions cancel promptly, refuse overlap and cannot update a replacement session', async () => {
let resolve,
signal,
calls = 0;
const session = createInteractionSession({
execute: (_, s) => {
calls++;
signal = s;
return new Promise((r) => (resolve = r));
},
});
session.activate([{ id: 'old' }]);
const work = session.dispatch('old');
await Promise.resolve();
assert.equal(await session.dispatch('old'), false);
assert.equal(await session.dispatch('missing'), false);
session.activate([{ id: 'new' }]);
assert.equal(signal.aborted, true);
assert.equal(await work, false);
resolve(true);
await Promise.resolve();
assert.deepEqual(session.getState(), {
active: true,
busy: false,
selected: null,
count: 1,
});
assert.equal(calls, 1);
session.clear();
assert.equal(await session.dispatch('new'), false);
});
test('synchronous stop before execution prevents any side effect; rejection unlocks retry', async () => {
let calls = 0;
const session = createInteractionSession({
execute: () => {
calls++;
throw new Error('refused');
},
});
session.activate([{ id: 'a' }]);
const work = session.dispatch('a');
session.clear();
assert.equal(await work, false);
assert.equal(calls, 0);
session.activate([{ id: 'a' }]);
assert.equal(await session.dispatch('a'), false);
assert.equal(session.getState().busy, false);
assert.equal(await session.dispatch('a'), false);
assert.equal(calls, 2);
});
test('settled pack shots cannot take the same-shot seek shortcut after Stop released geometry', async () => {
const { SceneDirector } = await import('../../scenes/director.js');
const shot = { id: 'shot', dataPackIds: ['pack'] };
const director = Object.assign(Object.create(SceneDirector.prototype), {
_destroyed: false,
_loadedSceneId: 'scene',
_selectedShotId: 'shot',
_claimCameraOwnership: () =>
assert.fail('Must reload the released pack before camera seek'),
});
assert.equal(director._seekLoadedShot({ id: 'scene' }, { shot }), false);
});
test('actions preserve camera refusal, layer admission signal and explicit transition cap', async () => {
const { SceneDirector } = await import('../../scenes/director.js');
const owner = new AbortController();
const director = Object.assign(Object.create(SceneDirector.prototype), {
_running: false,
_destroyed: false,
_interactionTransitions: 64,
_getShot: () => ({ scene: { id: 'scene' }, shot: { id: 'shot' } }),
_claimCameraOwnership: () => false,
_setCameraView: () => assert.fail('Refused camera cannot move'),
_updateStatus: () => {},
_loadShot: () => assert.fail('Transition budget exceeded'),
dataManager: {
getAll: () => [{ id: 'traffic' }],
setEnabled: (id, enabled, options) => {
assert.equal(id, 'traffic');
assert.equal(enabled, true);
assert.equal(options.signal, owner.signal);
assert.equal(options.origin, 'scene');
return false;
},
},
});
assert.equal(
await director._executeInteraction({ type: 'focus' }, owner.signal),
false,
);
assert.equal(
await director._executeInteraction(
{ type: 'shot', shotId: 'next' },
owner.signal,
),
false,
);
assert.equal(
await director._executeInteraction(
{ type: 'layer', layerId: 'traffic', enabled: true },
owner.signal,
),
false,
);
assert.equal(
await director._executeInteraction(
{ type: 'layer', layerId: 'unknown', enabled: true },
owner.signal,
),
false,
);
owner.abort();
assert.equal(
await director._executeInteraction({ type: 'focus' }, owner.signal),
false,
);
});
src/director/interactions/session.js
+61
View File
@@ -0,0 +1,61 @@
/** Own one user-triggered action at a time; cancellation settles even an uncooperative adapter. */
export function createInteractionSession({ execute, changed = () => {} }) {
let controller,
active = false,
busy = false,
selected = null;
let actions = new Map();
const state = () => ({ active, busy, selected, count: actions.size });
function clear() {
active = false;
busy = false;
selected = null;
actions.clear();
controller?.abort();
controller = null;
changed(state());
}
return {
clear,
getState: state,
activate(items) {
clear();
actions = new Map(items.map((item) => [item.id, item]));
active = !!actions.size;
changed(state());
},
async dispatch(id) {
const item = actions.get(id);
if (!active || busy || !item) return false;
const current = new AbortController();
controller = current;
busy = true;
selected = id;
changed(state());
let abort;
try {
const cancelled = new Promise((resolve) => {
abort = () => resolve(false);
current.signal.addEventListener('abort', abort, { once: true });
});
const work = Promise.resolve().then(() => {
if (current.signal.aborted) return false;
return execute(item, current.signal);
});
return (
(await Promise.race([work, cancelled])) !== false &&
!current.signal.aborted
);
} catch {
return false;
} finally {
current.signal.removeEventListener('abort', abort);
if (controller === current) {
busy = false;
controller = null;
changed(state());
}
}
},
};
}
src/director/packs/geojson.js
+62
View File
@@ -0,0 +1,62 @@
import { PACK_LIMITS } from './manifest.js';
/** Decode a bounded geometry-only GeoJSON collection; properties never become HTML, styles or URLs. */
export function decodePackGeoJSON(bytes) {
const value = JSON.parse(
new TextDecoder('utf-8', { fatal: true }).decode(bytes),
);
if (
value?.type !== 'FeatureCollection' ||
!Array.isArray(value.features) ||
value.features.length > PACK_LIMITS.features
)
throw new Error('Expected a bounded FeatureCollection');
let positions = 0;
const ids = new Set();
function position(p) {
if (
!Array.isArray(p) ||
![2, 3].includes(p.length) ||
p.some((v) => !Number.isFinite(v)) ||
Math.abs(p[0]) > 180 ||
Math.abs(p[1]) > 90 ||
(p.length === 3 && (p[2] < -12000 || p[2] > 1e9)) ||
++positions > PACK_LIMITS.positions
)
throw new Error('Invalid geographic position');
return [p[0], p[1], p[2] ?? 0];
}
function line(points, ring = false) {
if (!Array.isArray(points) || points.length < (ring ? 4 : 2))
throw new Error('Invalid line');
const normalized = points.map(position);
if (ring && normalized[0].some((v, i) => v !== normalized.at(-1)[i]))
throw new Error('Unclosed ring');
return normalized;
}
return value.features.map((feature) => {
const id = feature?.id;
if (
feature?.type !== 'Feature' ||
typeof id !== 'string' ||
!id.trim() ||
id.length > 256 ||
ids.has(id)
)
throw new Error('Features require distinct string IDs');
ids.add(id);
const g = feature.geometry;
let coordinates;
if (g?.type === 'Point') coordinates = position(g.coordinates);
else if (g?.type === 'LineString') coordinates = line(g.coordinates);
else if (
g?.type === 'Polygon' &&
Array.isArray(g.coordinates) &&
g.coordinates.length &&
g.coordinates.length <= 128
)
coordinates = g.coordinates.map((ring) => line(ring, true));
else throw new Error('Unsupported geometry');
return { id, type: g.type, coordinates };
});
}
src/director/packs/manifest.js
+138
View File
@@ -0,0 +1,138 @@
import {
fields,
string,
number,
array,
optional,
fail,
} from '../documentFields.js';
export const PACK_LIMITS = Object.freeze({
packs: 8,
bytes: 8 * 1024 * 1024,
totalBytes: 32 * 1024 * 1024,
features: 2000,
positions: 50000,
});
/** Asset names are relative directory paths, never requests or executable modules. */
export function validateAssetPath(value, path = 'source.path') {
string(value, path, 1024);
if (
!value
.split('/')
.every((part) => /^[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$/.test(part))
)
fail(
path,
'expected a relative asset path without URL syntax or traversal',
);
}
/** Validate one declarative pack; loading requires separately registered application adapters. */
export function validateDataPack(pack, path, anchorIds) {
fields(pack, path, [
'id',
'version',
'format',
'source',
'attribution',
'placement',
'byteLength',
'sha256',
]);
string(pack.id, `${path}.id`);
if (pack.version !== 1) fail(`${path}.version`, 'unsupported pack version');
if (!['geojson', 'image', 'media'].includes(pack.format))
fail(`${path}.format`, 'unsupported pack format');
fields(pack.source, `${path}.source`, ['adapter', 'path']);
string(pack.source.adapter, `${path}.source.adapter`);
validateAssetPath(pack.source.path, `${path}.source.path`);
fields(pack.attribution, `${path}.attribution`, ['text', 'license', 'url']);
string(pack.attribution.text, `${path}.attribution.text`, 4096);
string(pack.attribution.license, `${path}.attribution.license`, 4096);
optional(pack.attribution, 'url', `${path}.attribution`, (url, at) => {
string(url, at, 2048);
let parsed;
try {
parsed = new URL(url);
} catch {
fail(at, 'expected an HTTPS source link');
}
if (
parsed.protocol !== 'https:' ||
parsed.username ||
parsed.password ||
parsed.search ||
parsed.hash
)
fail(
at,
'expected an HTTPS source link without credentials, query or fragment',
);
});
optional(pack, 'byteLength', path, (v, at) => {
number(v, at, 1, PACK_LIMITS.bytes, false);
if (!Number.isInteger(v)) fail(at, 'expected an integer');
});
optional(pack, 'sha256', path, (v, at) => {
if (typeof v !== 'string' || !/^[a-f0-9]{64}$/.test(v))
fail(at, 'expected a lowercase SHA-256 digest');
});
const p = pack.placement,
at = `${path}.placement`;
fields(
p,
at,
pack.format === 'image'
? ['bounds', 'height', 'altitudeReference']
: pack.format === 'media'
? ['anchorId']
: ['altitudeReference'],
);
if (pack.format === 'media') {
if (!anchorIds.has(p.anchorId))
fail(`${at}.anchorId`, 'unknown scene anchor');
} else {
if (p.altitudeReference !== 'ellipsoid')
fail(`${at}.altitudeReference`, 'expected ellipsoid height in meters');
if (pack.format === 'image') {
array(p.bounds, `${at}.bounds`, 4);
if (p.bounds.length !== 4)
fail(`${at}.bounds`, 'expected west, south, east, north');
p.bounds.forEach((v, i) =>
number(
v,
`${at}.bounds[${i}]`,
i % 2 ? -90 : -180,
i % 2 ? 90 : 180,
false,
),
);
if (p.bounds[0] >= p.bounds[2] || p.bounds[1] >= p.bounds[3])
fail(`${at}.bounds`, 'expected increasing non-dateline bounds');
number(p.height, `${at}.height`, -12000, 1e9, false);
}
}
}
/** Validate scene-local pack IDs and shot references without acquiring assets. */
export function validateSceneDataPacks(scene, path) {
const packs = Object.hasOwn(scene, 'dataPacks') ? scene.dataPacks : [];
array(packs, `${path}.dataPacks`, PACK_LIMITS.packs);
const anchors = new Set((scene.anchors || []).map((a) => a.id));
const seen = new Set();
packs.forEach((pack, i) => {
validateDataPack(pack, `${path}.dataPacks[${i}]`, anchors);
if (seen.has(pack.id))
fail(`${path}.dataPacks[${i}].id`, 'duplicate pack ID');
seen.add(pack.id);
});
scene.shots.forEach((shot, i) => {
optional(shot, 'dataPackIds', `${path}.shots[${i}]`, (ids, at) => {
array(ids, at, PACK_LIMITS.packs);
if (new Set(ids).size !== ids.length || ids.some((id) => !seen.has(id)))
fail(at, 'expected distinct scene pack IDs');
});
});
}
src/director/packs/packs.test.mjs
+365
View File
@@ -0,0 +1,365 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { parseSceneDocument, stringifySceneDocument } from '../document.js';
import { normalizeProject } from '../../scenes/project.js';
import { createDataPackSession } from './session.js';
import { createAssetDirectorySource } from './source.js';
import { decodePackGeoJSON } from './geojson.js';
const pack = () => ({
id: 'outline',
version: 1,
format: 'geojson',
source: { adapter: 'assets', path: 'example/outline.geojson' },
attribution: { text: 'Example author', license: 'CC0-1.0' },
placement: { altitudeReference: 'ellipsoid' },
});
const project = () => ({
version: 5,
scenes: [
{
id: 'scene',
dataPacks: [pack()],
shots: [{ id: 'shot', dataPackIds: ['outline'] }],
},
],
});
const asset = () => ({
bytes: new Uint8Array([1, 2, 3]),
mimeType: 'application/json',
});
const deferred = () => {
let resolve;
const promise = new Promise((r) => {
resolve = r;
});
return { promise, resolve };
};
test('v5 packs and shot references round trip through project migration without acquiring bytes', () => {
const normalized = normalizeProject(
parseSceneDocument(JSON.stringify(project())),
);
assert.deepEqual(
JSON.parse(stringifySceneDocument(normalized)).scenes[0].dataPacks,
project().scenes[0].dataPacks,
);
assert.deepEqual(normalized.scenes[0].shots[0].dataPackIds, ['outline']);
for (const version of [1, 2, 3, 4]) {
const old = normalizeProject(
parseSceneDocument(
JSON.stringify({ version, scenes: [{ id: 'old', shots: [] }] }),
),
);
assert.equal(old.version, 6);
assert.equal(old.scenes[0].dataPacks, undefined);
}
});
test('manifest rejects duplicate/unknown IDs, unsupported placement and request or credential syntax', () => {
const mutations = [
(s) => {
s.dataPacks = null;
},
(s) => s.dataPacks.push(pack()),
(s) => s.shots[0].dataPackIds.push('missing'),
(s) => s.shots[0].dataPackIds.push('outline'),
(s) => (s.dataPacks[0].placement.altitudeReference = 'terrain'),
(s) => (s.dataPacks[0].source.headers = { Authorization: 'secret' }),
(s) => (s.dataPacks[0].attribution.url = 'javascript:alert(1)'),
(s) => (s.dataPacks[0].byteLength = 0),
(s) => (s.dataPacks[0].sha256 = 'wrong'),
...[
'../x',
'/api/status',
'https://example.com/x',
'x?a=1',
'x#key',
'%2e%2e/x',
'a\\b',
'a//b',
].map((path) => (s) => (s.dataPacks[0].source.path = path)),
];
for (const mutate of mutations) {
const p = project();
mutate(p.scenes[0]);
assert.throws(() => parseSceneDocument(JSON.stringify(p)));
}
const old = project();
old.version = 4;
assert.throws(() => parseSceneDocument(JSON.stringify(old)));
});
test('image bounds and media anchor references are explicit and validated', () => {
const p = project(),
s = p.scenes[0],
a = s.dataPacks[0];
a.format = 'image';
a.placement = {
bounds: [-98, 30, -97, 31],
height: 200,
altitudeReference: 'ellipsoid',
};
assert.doesNotThrow(() => parseSceneDocument(JSON.stringify(p)));
a.placement.bounds[2] = -99;
assert.throws(() => parseSceneDocument(JSON.stringify(p)));
a.format = 'media';
a.placement = { anchorId: 'one' };
assert.throws(() => parseSceneDocument(JSON.stringify(p)));
s.anchors = [
{ id: 'one', lat: 30, lon: -97, alt: 200, altitudeReference: 'ellipsoid' },
];
assert.doesNotThrow(() => parseSceneDocument(JSON.stringify(p)));
});
test('directory source confines paths, strips credentials and rejects redirects, oversized streaming bodies and missing assets', async () => {
const requests = [];
const source = createAssetDirectorySource({
baseUrl: 'https://assets.example.org/packs/',
fetchImpl: async (...args) => {
requests.push(args);
return new Response(new Uint8Array([1, 2, 3]), {
headers: { 'Content-Type': 'application/json' },
});
},
});
assert.deepEqual(
(await source({ path: 'a/data.json' })).bytes,
asset().bytes,
);
assert.equal(requests[0][0], 'https://assets.example.org/packs/a/data.json');
assert.equal(requests[0][1].credentials, 'omit');
assert.equal(requests[0][1].redirect, 'error');
assert.equal(requests[0][1].referrerPolicy, 'no-referrer');
await assert.rejects(source({ path: '../api/test' }));
assert.equal(requests.length, 1);
await assert.rejects(source({ path: 'a', maxBytes: 2 }), /byte limit/);
const missing = createAssetDirectorySource({
baseUrl: 'https://example.org/packs/',
fetchImpl: async () => new Response('', { status: 404 }),
});
await assert.rejects(missing({ path: 'a' }), /unavailable/);
});
test('GeoJSON preserves stable geometry IDs but never properties or remote style hints', () => {
const data = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
id: 'p',
properties: { title: '<script>', marker: 'https://bad.example/x' },
geometry: { type: 'Point', coordinates: [-97, 30, 300] },
},
],
};
const decode = () =>
decodePackGeoJSON(new TextEncoder().encode(JSON.stringify(data)));
assert.deepEqual(decode(), [
{ id: 'p', type: 'Point', coordinates: [-97, 30, 300] },
]);
data.features.push(data.features[0]);
assert.throws(decode, /IDs/);
data.features.pop();
data.features[0].geometry.coordinates[1] = 91;
assert.throws(decode, /position/);
data.features[0].geometry = {
type: 'Polygon',
coordinates: [
[
[0, 0],
[1, 0],
[1, 1],
[2, 2],
],
],
};
assert.throws(decode, /ring/);
});
test('pack session removes presentations and cancels the transport on Stop', async () => {
let disposed = 0,
signal;
const session = createDataPackSession({
sources: {
assets: async (options) => {
signal = options.signal;
return asset();
},
},
adapters: {
geojson: async () => ({
dispose() {
disposed++;
},
}),
},
});
await session.load([pack()]);
assert.deepEqual(session.getState(), { status: 'ready', count: 1 });
session.clear();
session.destroy();
assert.equal(disposed, 1);
assert.equal(signal.aborted, true);
assert.equal(session.getState().count, 0);
});
test('replacing a pending source settles promptly and ignores its late bytes', async () => {
const first = deferred();
let mounted = 0,
calls = 0;
const session = createDataPackSession({
sources: { assets: () => (++calls === 1 ? first.promise : asset()) },
adapters: {
geojson: () => {
mounted++;
return {
dispose() {
mounted--;
},
};
},
},
});
const old = session.load([pack()]);
await session.load([pack()]);
assert.equal(await old, false);
first.resolve(asset());
await new Promise((r) => setImmediate(r));
assert.equal(mounted, 1);
session.destroy();
assert.equal(mounted, 0);
});
test('late renderer resources are disposed after cancellation without mutating a replacement', async () => {
const rendering = deferred();
let disposed = 0;
const entered = deferred();
const session = createDataPackSession({
sources: { assets: asset },
adapters: {
geojson: () => {
entered.resolve();
return rendering.promise;
},
},
});
const load = session.load([pack()]);
await entered.promise;
session.clear();
assert.equal(await load, false);
rendering.resolve({
dispose() {
disposed++;
},
});
await new Promise((r) => setImmediate(r));
assert.equal(disposed, 1);
});
test('an abort between renderer settlement and continuation cannot leak the returned resource', async () => {
const controller = new AbortController();
let disposed = 0;
const session = createDataPackSession({
sources: { assets: asset },
adapters: {
geojson: () => {
queueMicrotask(() => controller.abort());
return {
dispose() {
disposed++;
},
};
},
},
});
assert.equal(
await session.load([pack()], { signal: controller.signal }),
false,
);
assert.equal(disposed, 1);
assert.equal(session.getState().count, 0);
});
test('timeout settles an uncooperative adapter and failed packs roll back earlier resources', async () => {
const session = createDataPackSession({
timeoutMs: 10,
sources: { assets: () => new Promise(() => {}) },
adapters: { geojson: () => assert.fail() },
});
await assert.rejects(session.load([pack()]), /could not load/);
assert.equal(session.getState().status, 'idle');
let disposed = 0,
called = 0;
const rollback = createDataPackSession({
sources: {
assets: () => {
if (++called === 2) throw new Error('secret URL');
return asset();
},
},
adapters: {
geojson: () => ({
dispose() {
disposed++;
},
}),
},
});
await assert.rejects(
rollback.load([pack(), { ...pack(), id: 'second' }]),
(e) => !e.message.includes('secret') && /could not load/.test(e.message),
);
assert.equal(disposed, 1);
assert.equal(rollback.getState().count, 0);
});
test('byte and integrity checks run before rendering; adapter names never resolve inherited properties', async () => {
let mounted = 0;
const session = createDataPackSession({
sources: { assets: asset },
adapters: {
geojson: () => {
mounted++;
return { dispose() {} };
},
},
});
for (const overrides of [
{ byteLength: 2 },
{ sha256: '0'.repeat(64) },
{ source: { adapter: 'toString', path: 'a' } },
])
await assert.rejects(session.load([{ ...pack(), ...overrides }]));
assert.equal(mounted, 0);
const digest = await crypto.subtle.digest('SHA-256', asset().bytes);
const sha256 = Buffer.from(digest).toString('hex');
await session.load([{ ...pack(), byteLength: 3, sha256 }]);
assert.equal(mounted, 1);
session.destroy();
});
test('failed responses release their body and an already-cancelled source sends no request', async () => {
let cancelled = 0,
requests = 0;
const source = createAssetDirectorySource({
baseUrl: 'https://example.org/packs/',
fetchImpl: async () => {
requests++;
return new Response(
new ReadableStream({
cancel() {
cancelled++;
},
}),
{ status: 403 },
);
},
});
await assert.rejects(source({ path: 'a.json' }), /unavailable/);
assert.equal(cancelled, 1);
const controller = new AbortController();
controller.abort();
await assert.rejects(source({ path: 'a.json', signal: controller.signal }));
assert.equal(requests, 1);
});
src/director/packs/session.js
+159
View File
@@ -0,0 +1,159 @@
import { PACK_LIMITS, validateDataPack } from './manifest.js';
// Also settle adapters that fail to observe abort; dispose any late resource they return.
function untilAbort(promise, signal, late = () => {}) {
return new Promise((resolve, reject) => {
let ended = false;
const abort = () => {
if (!ended) {
ended = true;
reject(signal.reason);
}
};
signal.addEventListener('abort', abort, { once: true });
if (signal.aborted) abort();
Promise.resolve(promise).then(
(value) => {
signal.removeEventListener('abort', abort);
if (ended) late(value);
else {
ended = true;
resolve(value);
}
},
(error) => {
signal.removeEventListener('abort', abort);
if (!ended) {
ended = true;
reject(error);
}
},
);
});
}
/** Own bounded pack acquisition and disposable presentations for a single shot. */
export function createDataPackSession({
sources = {},
adapters = {},
timeoutMs = 15000,
} = {}) {
const sourceMap = new Map(Object.entries(sources));
const adapterMap = new Map(Object.entries(adapters));
let active = null,
disposed = false;
function clear() {
const run = active;
if (!run) return;
active = null;
run.controller.abort();
run.detach();
clearTimeout(run.timer);
for (const handle of run.handles.splice(0).reverse()) handle.dispose();
}
return {
clear,
destroy() {
disposed = true;
clear();
},
getState() {
return {
status: active?.status || 'idle',
count: active?.handles.length || 0,
};
},
async load(packs, { anchors = [], signal } = {}) {
clear();
if (!Array.isArray(packs) || packs.length > PACK_LIMITS.packs)
throw new Error('Too many data packs');
const anchorIds = new Set(anchors.map((anchor) => anchor.id));
packs.forEach((pack, i) =>
validateDataPack(pack, `packs[${i}]`, anchorIds),
);
if (disposed || signal?.aborted) return false;
if (!packs.length) return true;
const controller = new AbortController();
const run = {
controller,
handles: [],
status: 'loading',
detach: () => signal?.removeEventListener('abort', cancel),
};
const cancel = () => {
if (active === run) clear();
};
active = run;
signal?.addEventListener('abort', cancel, { once: true });
run.timer = setTimeout(
() => controller.abort(new Error('Asset load timed out')),
timeoutMs,
);
let total = 0;
try {
for (const pack of packs) {
const source = sourceMap.get(pack.source.adapter),
adapter = adapterMap.get(pack.format);
if (!source || !adapter)
throw new Error('Data pack adapter unavailable');
const asset = await untilAbort(
source({
path: pack.source.path,
signal: controller.signal,
maxBytes: pack.byteLength || PACK_LIMITS.bytes,
}),
controller.signal,
);
controller.signal.throwIfAborted();
const { bytes } = asset;
if (
!(bytes instanceof Uint8Array) ||
!bytes.length ||
bytes.length > PACK_LIMITS.bytes ||
(pack.byteLength && bytes.length !== pack.byteLength)
)
throw new Error('Asset byte length invalid');
total += bytes.length;
if (total > PACK_LIMITS.totalBytes)
throw new Error('Shot assets exceed byte limit');
if (pack.sha256) {
const digest = await untilAbort(
crypto.subtle.digest('SHA-256', bytes),
controller.signal,
);
const hex = Array.from(new Uint8Array(digest), (b) =>
b.toString(16).padStart(2, '0'),
).join('');
if (hex !== pack.sha256)
throw new Error('Asset integrity mismatch');
}
const handle = await untilAbort(
adapter({ pack, asset, anchors, signal: controller.signal }),
controller.signal,
(late) => late?.dispose(),
);
if (!handle || typeof handle.dispose !== 'function')
throw new Error('Data pack adapter requires disposal');
if (active !== run || controller.signal.aborted) {
handle.dispose();
controller.signal.throwIfAborted();
return false;
}
run.handles.push(handle);
}
controller.signal.throwIfAborted();
clearTimeout(run.timer);
run.status = 'ready';
return true;
} catch (error) {
const superseded = active !== run || signal?.aborted || disposed;
if (active === run) clear();
if (superseded) return false;
// Source errors may include URLs; only stable messages reach the UI.
throw new Error(
'Data pack could not load: check its source, format, size or integrity',
);
}
},
};
}
src/director/packs/source.js
+67
View File
@@ -0,0 +1,67 @@
import { PACK_LIMITS, validateAssetPath } from './manifest.js';
/** Register a fixed asset directory. Scene files cannot replace its origin or escape its path. */
export function createAssetDirectorySource({
baseUrl,
fetchImpl = globalThis.fetch,
}) {
const base = new URL(baseUrl);
if (
!['https:', 'http:'].includes(base.protocol) ||
base.username ||
base.password ||
base.search ||
base.hash ||
!base.pathname.endsWith('/')
)
throw new TypeError(
'Asset source requires an explicit HTTP(S) directory URL',
);
return async ({ path, signal, maxBytes = PACK_LIMITS.bytes }) => {
validateAssetPath(path);
signal?.throwIfAborted();
const response = await fetchImpl(new URL(path, base).href, {
signal,
credentials: 'omit',
redirect: 'error',
referrerPolicy: 'no-referrer',
cache: 'no-store',
});
if (!response.ok) {
await response.body?.cancel().catch(() => {});
throw new Error('Asset unavailable');
}
const reader = response.body?.getReader();
if (!reader) throw new Error('Asset stream unavailable');
const chunks = [];
let length = 0;
try {
if (Number(response.headers.get('content-length')) > maxBytes)
throw new Error('Asset exceeds byte limit');
for (;;) {
signal?.throwIfAborted();
const { done, value } = await reader.read();
if (done) break;
length += value.byteLength;
if (length > maxBytes) throw new Error('Asset exceeds byte limit');
chunks.push(value);
}
} finally {
await reader.cancel().catch(() => {});
reader.releaseLock();
}
const bytes = new Uint8Array(length);
let offset = 0;
for (const chunk of chunks) {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
return {
bytes,
mimeType: (response.headers.get('content-type') || '')
.split(';')[0]
.trim()
.toLowerCase(),
};
};
}
src/director/playback.js
+137
View File
@@ -0,0 +1,137 @@
/**
* Build an ordered shot queue, starting at a scene and optionally wrapping.
* Scene and shot objects are opaque to the runner apart from their identifiers.
* @param {Array<{id:string, shots:Object[]}>} scenes
* @param {string} startSceneId
* @param {{single?:boolean}} [options]
* @returns {Array<{scene:Object, shot:Object}>}
*/
export function buildPlaybackQueue(
scenes,
startSceneId,
{ single = false } = {},
) {
const start = Math.max(
0,
scenes.findIndex((scene) => scene.id === startSceneId),
);
const ordered = single
? scenes.slice(start, start + 1)
: [...scenes.slice(start), ...scenes.slice(0, start)];
return ordered.flatMap((scene) =>
scene.shots.map((shot) => ({ scene, shot })),
);
}
/**
* Run ordered shots through an application-supplied playback adapter.
*
* Each phase receives {scene, shot, index, total, token}. The adapter owns
* camera/rendering resources and must observe token.signal or token.cancelled
* while awaiting work. The runner rechecks both after every phase; it cannot
* interrupt an adapter that ignores cancellation. No timers, UI, storage,
* renderer or authored content are imported here.
*
* releaseScene(scene, token?) leaves a previously loaded scene before playback
* (false refuses that initial handoff). Between scenes and during final cleanup
* it receives no cancelled token, so resource release can finish after Stop.
* An empty/already-cancelled queue acquires and releases no resources.
*
* @param {Array<{scene:Object, shot:Object}>} queue Normalized, fixed shot queue.
* @param {Object} options
* @param {{cancelled?:boolean, signal?:AbortSignal}} options.token Run lifetime.
* @param {Object} options.adapter selectShot/applyVisual/applyLayers/travel/
* settle/hold/completeShot callbacks, releaseScene and optional complete.
* @param {Object|null} [options.previousScene=null] Previously loaded scene.
* @param {boolean} [options.releaseOnFinish=true] Release the final scene.
* @returns {Promise<{status:'completed'|'cancelled', completedShots:number}>}
*/
export async function playSceneQueue(
queue,
{ token, adapter, previousScene = null, releaseOnFinish = true },
) {
const cancelled = () => Boolean(token.cancelled || token.signal?.aborted);
let activeScene = null;
let completedShots = 0;
try {
if (!queue.length || cancelled()) {
return {
status: cancelled() ? 'cancelled' : 'completed',
completedShots,
};
}
if (previousScene && previousScene.id !== queue[0].scene.id) {
const released = await adapter.releaseScene(previousScene, token);
if (!released)
throw new Error(`Could not leave scene: ${previousScene.title}`);
}
for (let index = 0; index < queue.length && !cancelled(); index++) {
const { scene, shot } = queue[index];
if (activeScene && activeScene.id !== scene.id) {
await adapter.releaseScene(activeScene);
activeScene = null;
if (cancelled()) break;
}
activeScene = scene;
const context = { scene, shot, index, total: queue.length, token };
for (const phase of SHOT_PHASES) {
if (cancelled()) break;
await adapter[phase](context);
}
if (!cancelled()) completedShots++;
}
if (!cancelled()) await adapter.complete?.();
return { status: cancelled() ? 'cancelled' : 'completed', completedShots };
} finally {
if (releaseOnFinish && activeScene) await adapter.releaseScene(activeScene);
}
}
const SHOT_PHASES = [
'selectShot',
'applyVisual',
'applyLayers',
'travel',
'settle',
'hold',
'completeShot',
];
export {
sceneTimingForShot,
sceneSeekState,
cameraAtProgress,
} from './timeline.js';
export { createPlaybackClock } from './clock.js';
export {
parseSceneDocument,
validateSceneDocument,
stringifySceneDocument,
SceneDocumentError,
SCENE_DOCUMENT_VERSION,
SCENE_DOCUMENT_LIMITS,
} from './document.js';
export {
resolveCameraPose,
resolveCameraMove,
sampleCameraMove,
} from './camera.js';
export { createAssetDirectorySource } from './packs/source.js';
export { createDataPackSession } from './packs/session.js';
export { validateDataPack, PACK_LIMITS } from './packs/manifest.js';
export { createInteractionSession } from './interactions/session.js';
export {
parseSceneShare,
readSceneShare,
createSceneBundle,
createBundleAssets,
BUNDLE_SOURCE,
SHARE_LIMITS,
} from './sharing/bundle.js';
export { describeSceneShare } from './sharing/preview.js';
export { editSceneDetails, selectSceneDocument } from './authoring.js';
src/director/playback.test.mjs
+198
View File
@@ -0,0 +1,198 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { buildPlaybackQueue, playSceneQueue } from './playback.js';
const scenes = [
{ id: 'a', title: 'A', shots: [{ id: 'a1' }, { id: 'a2' }] },
{ id: 'empty', shots: [] },
{ id: 'b', title: 'B', shots: [{ id: 'b1' }] },
];
const phases = [
'selectShot',
'applyVisual',
'applyLayers',
'travel',
'settle',
'hold',
'completeShot',
];
function fixture(overrides = {}) {
const events = [];
const abort = new AbortController();
const token = { cancelled: false, signal: abort.signal };
const adapter = {
...Object.fromEntries(
phases.map((phase) => [
phase,
({ shot, token: received }) => {
assert.equal(received, token);
events.push(`${shot.id}:${phase}`);
},
]),
),
releaseScene(scene, received) {
events.push(`release:${scene.id}:${received ? 'handoff' : 'cleanup'}`);
return true;
},
complete() {
events.push('complete');
},
...overrides,
};
return { events, abort, token, adapter };
}
test('queues rotate scenes, skip empty scenes, preserve shot identity and support a single scene', () => {
const queue = buildPlaybackQueue(scenes, 'b');
assert.deepEqual(
queue.map(({ shot }) => shot.id),
['b1', 'a1', 'a2'],
);
assert.equal(queue[0].shot, scenes[2].shots[0]);
assert.deepEqual(buildPlaybackQueue(scenes, 'empty', { single: true }), []);
assert.deepEqual(buildPlaybackQueue([], 'missing'), []);
assert.deepEqual(
buildPlaybackQueue(scenes, 'missing').map(({ shot }) => shot.id),
['a1', 'a2', 'b1'],
);
});
test('playback sequences phases, releases only at scene changes, then releases the final scene', async () => {
const f = fixture();
const result = await playSceneQueue(buildPlaybackQueue(scenes, 'a'), f);
assert.deepEqual(result, { status: 'completed', completedShots: 3 });
assert.deepEqual(f.events, [
...phases.map((phase) => `a1:${phase}`),
...phases.map((phase) => `a2:${phase}`),
'release:a:cleanup',
...phases.map((phase) => `b1:${phase}`),
'complete',
'release:b:cleanup',
]);
});
for (const phase of phases) {
for (const cancellation of ['flag', 'signal']) {
test(`${cancellation} cancellation while awaiting ${phase} stops subsequent work and releases resources`, async () => {
let entered;
let resume;
const started = new Promise((resolve) => {
entered = resolve;
});
const pending = new Promise((resolve) => {
resume = resolve;
});
const f = fixture({
[phase]: async () => {
entered();
await pending;
},
});
const run = playSceneQueue(buildPlaybackQueue(scenes, 'a'), f);
await started;
if (cancellation === 'flag') f.token.cancelled = true;
else f.abort.abort();
resume();
assert.deepEqual(await run, { status: 'cancelled', completedShots: 0 });
assert.deepEqual(f.events, [
...phases.slice(0, phases.indexOf(phase)).map((name) => `a1:${name}`),
'release:a:cleanup',
]);
});
}
test(`failure in ${phase} propagates after release, without later shots`, async () => {
const failure = new Error('adapter failed');
const f = fixture({
[phase]: () => {
throw failure;
},
});
await assert.rejects(
playSceneQueue(buildPlaybackQueue(scenes, 'a'), f),
(error) => error === failure,
);
assert.equal(f.events.at(-1), 'release:a:cleanup');
assert.ok(
!f.events.some(
(event) => event.startsWith('a2:') || event === 'complete',
),
);
});
}
test('empty and pre-aborted runs never acquire or release adapter resources', async () => {
const f = fixture();
assert.deepEqual(await playSceneQueue([], f), {
status: 'completed',
completedShots: 0,
});
f.abort.abort();
assert.deepEqual(
await playSceneQueue(buildPlaybackQueue(scenes, 'a'), {
...f,
previousScene: scenes[2],
}),
{ status: 'cancelled', completedShots: 0 },
);
assert.deepEqual(f.events, []);
});
test('a prior scene must release before playback; a refused handoff starts no shot', async () => {
const f = fixture();
await playSceneQueue(buildPlaybackQueue(scenes, 'a', { single: true }), {
...f,
previousScene: scenes[2],
});
assert.equal(f.events[0], 'release:b:handoff');
const refused = fixture({ releaseScene: () => false });
await assert.rejects(
playSceneQueue(buildPlaybackQueue(scenes, 'a'), {
...refused,
previousScene: scenes[2],
}),
/Could not leave scene: B/,
);
assert.deepEqual(refused.events, []);
});
test('cancellation during an inter-scene release never acquires the next scene', async () => {
const f = fixture();
const release = f.adapter.releaseScene;
f.adapter.releaseScene = (...args) => {
f.abort.abort();
return release(...args);
};
const result = await playSceneQueue(buildPlaybackQueue(scenes, 'a'), f);
assert.deepEqual(result, { status: 'cancelled', completedShots: 2 });
assert.equal(f.events.at(-1), 'release:a:cleanup');
assert.equal(
f.events.filter((event) => event.startsWith('release')).length,
1,
);
});
test('non-preview playback retains the final scene but still releases preceding scenes', async () => {
const f = fixture();
await playSceneQueue(buildPlaybackQueue(scenes, 'a'), {
...f,
releaseOnFinish: false,
});
assert.deepEqual(
f.events.filter((event) => event.startsWith('release')),
['release:a:cleanup'],
);
});
test('a cleanup failure rejects for the caller to restore its own controls', async () => {
const failure = new Error('cleanup failed');
const f = fixture({
releaseScene: () => {
throw failure;
},
});
await assert.rejects(
playSceneQueue(buildPlaybackQueue(scenes, 'a', { single: true }), f),
(error) => error === failure,
);
});
src/director/sharing/bundle.js
+221
View File
@@ -0,0 +1,221 @@
import { parseSceneDocument, stringifySceneDocument } from '../document.js';
import { withShareSignal } from './lifetime.js';
import { fields, array, fail } from '../documentFields.js';
import { PACK_LIMITS, validateAssetPath } from '../packs/manifest.js';
export const BUNDLE_SOURCE = 'scene-bundle';
export const SHARE_LIMITS = Object.freeze({
bytes: 50 * 1024 * 1024,
assets: 64,
});
const MIME = new Set([
'application/json',
'application/geo+json',
'image/png',
'video/mp4',
'video/webm',
'audio/mpeg',
'audio/ogg',
'audio/wav',
'audio/webm',
]);
const packsOf = (project) =>
project.scenes.flatMap((scene) => scene.dataPacks || []);
const checkAbort = (signal) => signal?.throwIfAborted();
const digest = async (bytes) =>
Array.from(
new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)),
(n) => n.toString(16).padStart(2, '0'),
).join('');
function encode(bytes) {
const chunks = [];
for (let i = 0; i < bytes.length; i += 32768)
chunks.push(String.fromCharCode(...bytes.subarray(i, i + 32768)));
return btoa(chunks.join(''));
}
function decode(value) {
if (
typeof value !== 'string' ||
!value.length ||
value.length > Math.ceil(PACK_LIMITS.bytes / 3) * 4 ||
value.length % 4 !== 0 ||
/[^A-Za-z0-9+/=]/.test(value) ||
(value.includes('=') && !/^[A-Za-z0-9+/]+={1,2}$/.test(value))
)
fail('assets', 'invalid or oversized base64 asset');
return Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
}
function checkBytes(bytes, total) {
if (
!(bytes instanceof Uint8Array) ||
!bytes.length ||
bytes.length > PACK_LIMITS.bytes ||
total > PACK_LIMITS.totalBytes
)
fail('assets', 'asset byte limit exceeded');
}
function checkMime(mimeType) {
if (!MIME.has(mimeType)) fail('assets', 'unsupported media type');
}
/** Read inert scene JSON or a bounded asset bundle, verifying bytes before admission. */
export async function parseSceneShare(text, { signal } = {}) {
checkAbort(signal);
if (
typeof text !== 'string' ||
text.length > SHARE_LIMITS.bytes ||
new TextEncoder().encode(text).length > SHARE_LIMITS.bytes
)
fail('$', 'share exceeds 50 MiB');
let input;
try {
input = JSON.parse(text);
} catch {
fail('$', 'invalid JSON');
}
if (input?.format !== 'gev-scene-bundle')
return { project: parseSceneDocument(text), assets: new Map() };
fields(input, '$', ['format', 'version', 'project', 'assets']);
if (input.version !== 1) fail('version', 'unsupported bundle version');
const project = parseSceneDocument(JSON.stringify(input.project));
array(input.assets, 'assets', SHARE_LIMITS.assets);
const assets = new Map();
let total = 0;
for (const entry of input.assets) {
checkAbort(signal);
fields(entry, 'assets', ['path', 'mimeType', 'base64', 'sha256']);
validateAssetPath(entry.path);
checkMime(entry.mimeType);
if (assets.has(entry.path)) fail('assets', 'duplicate asset path');
const bytes = decode(entry.base64);
total += bytes.length;
checkBytes(bytes, total);
const hash = await digest(bytes);
checkAbort(signal);
if (entry.sha256 !== hash) fail('assets', 'asset integrity mismatch');
assets.set(entry.path, { bytes, mimeType: entry.mimeType, sha256: hash });
}
const used = new Set();
for (const pack of packsOf(project)) {
if (pack.source.adapter !== BUNDLE_SOURCE)
fail('project', 'bundle must include every declared pack');
const asset = assets.get(pack.source.path);
used.add(pack.source.path);
if (
!asset ||
pack.byteLength !== asset.bytes.length ||
pack.sha256 !== asset.sha256
)
fail('project', 'missing or mismatched bundle asset');
}
if (used.size !== assets.size) fail('assets', 'unreferenced bundle asset');
return { project, assets };
}
/** File reads have a known budget before text decoding; large bundles use a distinct suffix. */
export async function readSceneShare(file, options) {
const limit = file.name?.endsWith('.gevbundle.json')
? SHARE_LIMITS.bytes
: 5 * 1024 * 1024;
if (file.size > limit)
fail(
'$',
limit === SHARE_LIMITS.bytes
? 'share exceeds 50 MiB'
: 'file exceeds 5 MiB',
);
checkAbort(options?.signal);
const text = await withShareSignal(file.text(), options?.signal);
checkAbort(options?.signal);
return parseSceneShare(text, options);
}
/** Export only explicitly supplied pack bytes; never fetch external assets or alter the source project. */
export async function createSceneBundle(
project,
resolveAsset,
{ signal } = {},
) {
const copy = parseSceneDocument(stringifySceneDocument(project));
const assets = [],
known = new Map();
let total = 0;
for (const pack of packsOf(copy)) {
checkAbort(signal);
const key = JSON.stringify([pack.source.adapter, pack.source.path]);
let entry = known.get(key);
if (!entry) {
if (assets.length >= SHARE_LIMITS.assets)
fail('assets', 'too many bundled assets');
const asset = await withShareSignal(
resolveAsset(pack, { signal }),
signal,
);
checkAbort(signal);
if (!asset) fail('assets', 'select a file for every declared data pack');
const bytes = asset.bytes;
total += bytes?.length || 0;
checkBytes(bytes, total);
checkMime(asset.mimeType);
const sha256 = await digest(bytes);
checkAbort(signal);
if (
(pack.byteLength && pack.byteLength !== bytes.length) ||
(pack.sha256 && pack.sha256 !== sha256)
)
fail('assets', 'selected file does not match declared integrity');
const path = `files/${assets.length}-${pack.source.path.split('/').at(-1).slice(0, 160)}`;
entry = {
path,
mimeType: asset.mimeType,
base64: encode(bytes),
sha256,
byteLength: bytes.length,
};
known.set(key, entry);
assets.push(entry);
} else if (
(pack.byteLength && pack.byteLength !== entry.byteLength) ||
(pack.sha256 && pack.sha256 !== entry.sha256)
)
fail('assets', 'conflicting shared asset integrity');
pack.source = { adapter: BUNDLE_SOURCE, path: entry.path };
pack.byteLength = entry.byteLength;
pack.sha256 = entry.sha256;
}
const text = JSON.stringify({
format: 'gev-scene-bundle',
version: 1,
project: copy,
assets: assets.map(({ byteLength, ...entry }) => entry),
});
if (new TextEncoder().encode(text).length > SHARE_LIMITS.bytes)
fail('$', 'share exceeds 50 MiB');
return text;
}
/** Keep bundled bytes in this project lifetime only; never fall back to a network source. */
export function createBundleAssets() {
let assets = new Map();
return {
replace(next = new Map()) {
assets = new Map(next);
},
clear() {
assets.clear();
},
snapshot: () => new Map(assets),
getState: () => ({
count: assets.size,
bytes: [...assets.values()].reduce((n, a) => n + a.bytes.length, 0),
}),
source({ path, signal, maxBytes = PACK_LIMITS.bytes }) {
checkAbort(signal);
validateAssetPath(path);
const asset = assets.get(path);
if (!asset || asset.bytes.length > maxBytes)
throw new Error('Bundle asset unavailable — reimport the bundle');
return { bytes: asset.bytes.slice(), mimeType: asset.mimeType };
},
};
}
src/director/sharing/lifetime.js
+26
View File
@@ -0,0 +1,26 @@
/** Settle cancelled file/adaptor work promptly; late results never regain ownership. */
export function withShareSignal(work, signal) {
if (!signal) return Promise.resolve(work);
return new Promise((resolve, reject) => {
const abort = () => {
signal.removeEventListener('abort', abort);
reject(signal.reason);
};
if (signal.aborted) {
Promise.resolve(work).catch(() => {});
abort();
return;
}
signal.addEventListener('abort', abort, { once: true });
Promise.resolve(work).then(
(value) => {
signal.removeEventListener('abort', abort);
signal.aborted ? reject(signal.reason) : resolve(value);
},
(error) => {
signal.removeEventListener('abort', abort);
reject(error);
},
);
});
}
src/director/sharing/preview.js
+43
View File
@@ -0,0 +1,43 @@
import { BUNDLE_SOURCE } from './bundle.js';
/** Describe an import without fetching assets, applying state or exposing source configuration. */
export function describeSceneShare(
{ project, assets },
{ sourceIds = [], layerIds = [] } = {},
) {
const sources = new Set(sourceIds),
layers = new Set(layerIds);
const packs = project.scenes.flatMap((scene) =>
(scene.dataPacks || []).map((pack) => ({
scene: scene.title || scene.id,
id: pack.id,
path: pack.source.path,
attribution: pack.attribution,
status:
pack.source.adapter === BUNDLE_SOURCE
? assets.has(pack.source.path)
? 'Included in bundle'
: 'Missing bundle file — reimport its bundle'
: sources.has(pack.source.adapter)
? 'Source configured; file checked when loaded'
: 'Source unavailable',
})),
);
return {
scenes: project.scenes.length,
shots: project.scenes.reduce((n, s) => n + s.shots.length, 0),
packs,
missingLayers: [
...new Set(
project.scenes.flatMap((s) =>
s.shots.flatMap((shot) => Object.keys(shot.layers || {})),
),
),
].filter((id) => !layers.has(id)),
externalContent: project.scenes.some(
(s) =>
s.appliedShotPacks?.length || s.shots.some((shot) => shot.sourcePackId),
),
bundledBytes: [...assets.values()].reduce((n, a) => n + a.bytes.length, 0),
};
}
src/director/sharing/sharing.test.mjs
+277
View File
@@ -0,0 +1,277 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
createSceneBundle,
parseSceneShare,
readSceneShare,
createBundleAssets,
BUNDLE_SOURCE,
SHARE_LIMITS,
} from './bundle.js';
import { describeSceneShare } from './preview.js';
import { editSceneDetails, selectSceneDocument } from '../authoring.js';
const bytes = new TextEncoder().encode(
JSON.stringify({ type: 'FeatureCollection', features: [] }),
);
const fixture = () => ({
version: 6,
scenes: [
{
id: 'one',
title: 'Example',
dataPacks: [
{
id: 'data',
version: 1,
format: 'geojson',
source: { adapter: 'assets', path: 'test/data.geojson' },
attribution: {
text: 'Example author',
license: 'CC0-1.0',
url: 'https://example.org/source',
},
placement: { altitudeReference: 'ellipsoid' },
},
],
shots: [
{
id: 'shot',
title: 'Original',
durationSec: 3,
holdSec: 2,
camera: { lat: 1, lon: 2, alt: 300, pitch: -60 },
layers: { traffic: false },
dataPackIds: ['data'],
},
],
},
{ id: 'other', shots: [] },
],
});
const asset = () => ({
bytes: bytes.slice(),
mimeType: 'application/geo+json',
});
test('selected-scene bundles round trip bytes and attribution without mutating the project or fetching', async () => {
const original = fixture(),
before = JSON.stringify(original);
let reads = 0;
const text = await createSceneBundle(
selectSceneDocument(original, 'one'),
() => {
reads++;
return asset();
},
);
const parsed = await parseSceneShare(text);
assert.equal(reads, 1);
assert.equal(JSON.stringify(original), before);
assert.equal(parsed.project.scenes.length, 1);
const pack = parsed.project.scenes[0].dataPacks[0];
assert.equal(pack.source.adapter, BUNDLE_SOURCE);
assert.equal(pack.byteLength, bytes.length);
assert.deepEqual(
pack.attribution,
original.scenes[0].dataPacks[0].attribution,
);
assert.deepEqual(parsed.assets.get(pack.source.path).bytes, bytes);
});
test('bundle rejects malformed bytes, unknown fields, traversal, duplicates, missing files and broken integrity', async () => {
const valid = JSON.parse(await createSceneBundle(fixture(), () => asset()));
const mutations = [
(b) => (b.version = 2),
(b) => (b.assets[0].path = '../secret'),
(b) => (b.assets[0].base64 = 'A==='),
(b) => (b.assets[0].base64 = '____'),
(b) => (b.assets[0].base64 = btoa('different')),
(b) => (b.assets[0].headers = {}),
(b) => (b.assets[0].mimeType = 'text/html'),
(b) => b.assets.push(b.assets[0]),
(b) => (b.assets = []),
(b) => (b.project.scenes[0].dataPacks[0].source.adapter = 'assets'),
(b) => (b.project.scenes[0].dataPacks = []),
(b) => (b.project.scenes[0].dataPacks[0].sha256 = '0'.repeat(64)),
(b) => (b.assets = Array.from({ length: 65 }, () => b.assets[0])),
];
for (const mutate of mutations) {
const b = structuredClone(valid);
mutate(b);
await assert.rejects(parseSceneShare(JSON.stringify(b)));
}
});
test('asset caps and declared integrity are enforced before creating a downloadable bundle', async () => {
await assert.rejects(
createSceneBundle(fixture(), () => ({
bytes: new Uint8Array(8 * 1024 * 1024 + 1),
mimeType: 'image/png',
})),
/limit/,
);
const p = fixture();
p.scenes[0].dataPacks[0].sha256 = '0'.repeat(64);
await assert.rejects(
createSceneBundle(p, () => asset()),
/integrity/,
);
await assert.rejects(
createSceneBundle(fixture(), () => null),
/select a file/,
);
});
test('duplicate pack paths share one asset and reject conflicting integrity', async () => {
const p = fixture();
p.scenes[0].dataPacks.push({
...structuredClone(p.scenes[0].dataPacks[0]),
id: 'second',
});
let reads = 0;
const text = await createSceneBundle(p, () => {
reads++;
return asset();
});
assert.equal(reads, 1);
assert.equal((await parseSceneShare(text)).assets.size, 1);
p.scenes[0].dataPacks[1].byteLength = 1;
await assert.rejects(
createSceneBundle(p, () => asset()),
/integrity/,
);
});
test('preview reports unavailable sources/layers and missing bundle assets without applying anything', () => {
const p = fixture();
const report = describeSceneShare(
{ project: p, assets: new Map() },
{ sourceIds: [], layerIds: [] },
);
assert.equal(report.packs[0].status, 'Source unavailable');
assert.deepEqual(report.missingLayers, ['traffic']);
p.scenes[0].dataPacks[0].source.adapter = BUNDLE_SOURCE;
assert.match(
describeSceneShare({ project: p, assets: new Map() }).packs[0].status,
/Missing bundle/,
);
});
test('bundle byte owner releases replacement data and has no network fallback', async () => {
const parsed = await parseSceneShare(
await createSceneBundle(fixture(), () => asset()),
);
const store = createBundleAssets();
store.replace(parsed.assets);
const path = parsed.project.scenes[0].dataPacks[0].source.path;
const first = store.source({ path });
first.bytes[0] = 0;
assert.deepEqual(store.source({ path }).bytes, bytes);
const controller = new AbortController();
controller.abort();
assert.throws(() => store.source({ path, signal: controller.signal }));
store.clear();
assert.deepEqual(store.getState(), { count: 0, bytes: 0 });
assert.throws(() => store.source({ path }), /unavailable/);
});
test('oversized files fail before reading and cancellation settles a stalled file without a late result', async () => {
let reads = 0;
await assert.rejects(
readSceneShare({
name: 'large.json',
size: 6 * 1024 * 1024,
text: () => {
reads++;
},
}),
/5 MiB/,
);
await assert.rejects(
readSceneShare({
name: 'large.gevbundle.json',
size: SHARE_LIMITS.bytes + 1,
text: () => {
reads++;
},
}),
/50 MiB/,
);
assert.equal(reads, 0);
let resolve;
const owner = new AbortController();
const work = readSceneShare(
{ name: 'pending.json', text: () => new Promise((r) => (resolve = r)) },
{ signal: owner.signal },
);
owner.abort();
await assert.rejects(work, /abort/i);
resolve(JSON.stringify(fixture()));
});
test('cancelled bundle export never resolves another asset or produces partial output', async () => {
let resolve;
const owner = new AbortController();
const work = createSceneBundle(
fixture(),
() => new Promise((r) => (resolve = r)),
{ signal: owner.signal },
);
owner.abort();
await assert.rejects(work, /abort/i);
resolve(asset());
});
test('details editing preserves content IDs, layers and provenance, rejects invalid drafts atomically', () => {
const p = fixture(),
before = JSON.stringify(p);
p.scenes[0].shots[0].sourcePackId = 'existing';
const scene = p.scenes[0],
shot = scene.shots[0];
const edited = editSceneDetails(
p,
'one',
'shot',
{
anchors: [
{ id: 'a', lat: 1, lon: 2, alt: 400, altitudeReference: 'ellipsoid' },
],
dataPacks: scene.dataPacks,
},
{
camera: { anchorId: 'a' },
durationSec: 4,
holdSec: 0,
dataPackIds: ['data'],
},
);
assert.equal(edited.scenes[0].shots[0].sourcePackId, 'existing');
assert.deepEqual(edited.scenes[0].shots[0].layers, shot.layers);
assert.equal(edited.scenes[0].shots[0].id, 'shot');
assert.throws(() =>
editSceneDetails(
p,
'one',
'shot',
{ anchors: [] },
{ camera: { anchorId: 'missing' } },
),
);
assert.throws(() =>
editSceneDetails(p, 'one', 'shot', { source: 'remote' }, {}),
);
assert.throws(() =>
editSceneDetails(p, 'one', 'shot', {}, { sourcePackId: 'replacement' }),
);
delete p.scenes[0].shots[0].sourcePackId;
assert.equal(JSON.stringify(p), before);
});
test('long valid source filenames still produce an importable bundle', async () => {
const p = fixture();
p.scenes[0].dataPacks[0].source.path = 'x'.repeat(1024);
const parsed = await parseSceneShare(
await createSceneBundle(p, () => asset()),
);
assert.equal(parsed.assets.size, 1);
});
src/director/timeline.js
+110
View File
@@ -0,0 +1,110 @@
import {
resolveCameraPose,
resolveCameraMove,
sampleCameraMove,
} from './camera.js';
const DEFAULT_SHOT_DURATION_SEC = 4;
const clamp01 = (value) => Math.max(0, Math.min(1, value));
/** Calculate one shot's boundaries using the supplied content duration resolver. */
export function sceneTimingForShot(scene, shot, durationForShot) {
const durations =
scene?.shots?.map((item) => durationForShot(scene, item)) || [];
const shotIndex = scene?.shots?.findIndex(({ id }) => id === shot?.id) ?? -1;
const totalSec = durations.reduce((sum, duration) => sum + duration, 0);
const startElapsedSec = durations
.slice(0, Math.max(0, shotIndex))
.reduce((sum, duration) => sum + duration, 0);
const durationSec = shotIndex >= 0 ? durations[shotIndex] : 0;
const endElapsedSec = Math.min(totalSec, startElapsedSec + durationSec);
return {
shotIndex,
totalSec,
durationSec,
startElapsedSec,
endElapsedSec,
startProgress: totalSec > 0 ? startElapsedSec / totalSec : 0,
endProgress: totalSec > 0 ? endElapsedSec / totalSec : 1,
durationProgress: totalSec > 0 ? durationSec / totalSec : 0,
};
}
/** Interpolate the existing cubic camera pose, including shortest-angle orientation. */
export function cameraAtProgress(fromCamera, toCamera, progress) {
const target = toCamera || fromCamera;
const source = fromCamera || target;
if (!source || !target) return target || source || null;
const t = clamp01(Number(progress) || 0);
const eased = t < 0.5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2;
const lerp = (from, to) => Number(from) + (Number(to) - Number(from)) * eased;
const lerpAngle = (from, to) => {
const start = Number(from) || 0;
const delta = ((Number(to) - start + 540) % 360) - 180;
return start + delta * eased;
};
return {
lat: lerp(source.lat, target.lat),
lon: lerp(source.lon, target.lon),
alt: lerp(source.alt, target.alt),
heading: lerpAngle(source.heading, target.heading),
pitch: lerp(source.pitch, target.pitch),
roll: lerpAngle(source.roll, target.roll),
};
}
/** Resolve a normalized scene time to a shot, flight/hold phase and camera pose. */
export function sceneSeekState(scene, progress, durationForShot, holdForShot) {
if (!scene?.shots?.length) return null;
const normalized = clamp01(Number(progress) || 0);
const durations = scene.shots.map((shot) => durationForShot(scene, shot));
const totalSec = durations.reduce((sum, duration) => sum + duration, 0);
const targetSec = normalized * Math.max(0, totalSec);
let startElapsedSec = 0;
let shotIndex = scene.shots.length - 1;
for (let index = 0; index < scene.shots.length; index += 1) {
const endElapsedSec = startElapsedSec + durations[index];
if (targetSec < endElapsedSec || index === scene.shots.length - 1) {
shotIndex = index;
break;
}
startElapsedSec = endElapsedSec;
}
const shot = scene.shots[shotIndex];
const flightDurationSec = shot.durationSec || DEFAULT_SHOT_DURATION_SEC;
const holdDurationSec = holdForShot(scene, shot);
const shotDurationSec = Math.max(0.001, flightDurationSec + holdDurationSec);
const shotElapsedSec = Math.max(
0,
Math.min(shotDurationSec, targetSec - startElapsedSec),
);
const cameraProgress = clamp01(
shotElapsedSec / Math.max(0.001, flightDurationSec),
);
const holdElapsedSec = Math.max(0, shotElapsedSec - flightDurationSec);
const holdProgress =
holdDurationSec > 0 ? clamp01(holdElapsedSec / holdDurationSec) : 1;
const targetCamera = resolveCameraPose(scene, shot.camera);
const previousCamera = resolveCameraPose(
scene,
scene.shots[shotIndex - 1]?.camera || shot.camera,
);
const move = resolveCameraMove(scene, shot);
return {
sceneProgress: totalSec > 0 ? targetSec / totalSec : 0,
sceneElapsedSec: targetSec,
sceneDurationSec: totalSec,
shotIndex,
shot,
shotElapsedSec,
shotProgress: clamp01(shotElapsedSec / shotDurationSec),
flightDurationSec,
holdDurationSec,
holdElapsedSec,
cameraProgress,
holdProgress,
camera: move
? sampleCameraMove(move, cameraProgress)
: cameraAtProgress(previousCamera, targetCamera, cameraProgress),
};
}
src/director/timeline.test.mjs
+51
View File
@@ -0,0 +1,51 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
sceneTimingForShot,
sceneSeekState,
cameraAtProgress,
} from './timeline.js';
const camera = (lon, heading) => ({
lat: 10,
lon,
alt: 1000,
heading,
pitch: -40,
roll: 0,
});
const scene = {
shots: [
{ id: 'a', durationSec: 2, holdSec: 1, camera: camera(20, 350) },
{ id: 'b', durationSec: 4, holdSec: 3, camera: camera(24, 10) },
],
};
const duration = (_, shot) => shot.durationSec + shot.holdSec;
const hold = (_, shot) => shot.holdSec;
test('scene time accounts for flight and hold; exact boundaries select the next shot', () => {
const time = sceneTimingForShot(scene, scene.shots[1], duration);
assert.equal(time.startElapsedSec, 3);
assert.equal(time.endElapsedSec, 10);
const seek = (progress) => sceneSeekState(scene, progress, duration, hold);
assert.equal(seek(-1).shot.id, 'a');
assert.equal(seek(0.3).shot.id, 'b');
assert.equal(seek(0.3).cameraProgress, 0);
assert.equal(seek(0.5).cameraProgress, 0.5);
assert.equal(seek(0.5).camera.lon, 22);
assert.equal(seek(0.8).holdElapsedSec, 1);
assert.equal(seek(2).holdProgress, 1);
assert.equal(seek(0).sceneElapsedSec, 0);
assert.equal(sceneSeekState({ shots: [] }, 1, duration, hold), null);
});
test('camera seeking preserves cubic easing and shortest-angle orientation', () => {
assert.equal(
cameraAtProgress(camera(20, 350), camera(24, 10), 0.5).heading,
360,
);
assert.equal(
cameraAtProgress(camera(20, 350), camera(24, 10), 0.25).lon,
20.25,
);
assert.deepEqual(cameraAtProgress(null, camera(20, 350), 0), camera(20, 350));
});
src/layers/transit/lifecycle.test.mjs
+317 -7
View File
@@ -2178,7 +2178,7 @@ test('under FLIR and NVG every sprite is white-hot with a dark halo, and selecti
assert.notEqual(entry.marker.image, plainImage, 'a haloed raster');
assert.match(
Buffer.from(entry.marker.image.split(',')[1], 'base64').toString(),
/#000000/,
/#05080C/,
'with the dark ring',
);
assert.ok(entry.marker.width > plainWidth * 1.2, 'and larger');
@@ -2547,7 +2547,7 @@ test('selected trail and marker share revised start floors, with unknown history
assert.ok(
Cesium.Cartographic.fromCartesian(entry.marker.position).height > 30,
);
assert.ok(entry.trailVertices <= 2048);
assert.ok(entry.trailVertices <= 640);
parts.selection.clearSelection();
assert.equal(parts.trails.diagnostics(), null);
});
@@ -2659,7 +2659,7 @@ test('a long selected history shortens its oldest geometry before sacrificing th
parts.rendering.sampleIdle(entry);
parts.selection.selectVehicle(entry.key);
assert.equal(entry.trailTruncated, true);
assert.ok(entry.trailVertices <= 2048);
assert.ok(entry.trailVertices <= 640);
assert.ok(
entry.displayPaths.has(entry.sample.fromSeq),
'active path is prepared first',
@@ -2671,6 +2671,63 @@ test('a long selected history shortens its oldest geometry before sacrificing th
);
});
test('sparse rail reports preserve a bounded marker corridor with and without selection', async (t) => {
const app = harness(t);
const parts = app.layer._transitPartsForTest();
const { seek } = await import('../../data/contactPlayback.js');
let latitude = 42.36 - 16000 / 111320;
let timestamp = reported();
app.serve('mbta', () => ({
status: 200,
body: snapshot(
'mbta',
'MBTA',
[vehicle('sparse', latitude, -71.06, timestamp, { routeId: 'CR-1' })],
{ fetchedAt: Date.now() },
),
}));
app.layer.enable(app.viewer);
await app.layer.update();
app.settle();
app.advance(180000);
latitude = 42.36;
timestamp += 180;
await app.layer.update();
app.settle();
const entry = app.vehicles()[0];
assert.equal(entry.mode, 'rail');
assert.equal(entry.track.count, 2, 'both 88.9 m/s reports pass admission');
assert.equal(entry.fixes[1].t - entry.fixes[0].t, 180000);
for (let i = 0; i < 1500; i++)
app.ground._warm.set(app.ground._key(42.2 + i * 0.0002, -71.06), 12);
seek(entry.track, entry.fixes[0].t + 90000, {
wallNowMs: Date.now(),
monoNowMs: performance.now(),
});
parts.rendering.sampleIdle(entry);
for (const selected of [false, true, false]) {
if (selected) parts.selection.selectVehicle(entry.key);
else parts.selection.clearSelection();
parts.trails.prepareEntry(entry);
const path = entry.displayPaths.get(entry.sample.fromSeq);
assert.ok(path, 'active corridor survives the body cap');
assert.ok(path.positions.length <= 640);
const position = parts.trails.samplePosition(
entry,
entry.sample,
new Cesium.Cartesian3(),
true,
);
assert.ok(
position && [position.x, position.y, position.z].every(Number.isFinite),
);
parts.rendering.placeSample(entry, true);
assert.equal(entry.marker.show, true);
assert.ok(Cesium.Cartesian3.equals(entry.marker.position, position));
assert.ok(entry.trailVertices <= 640);
}
});
test('missing rectangle still rejects the far side, and frustum rejection wins', async (t) => {
const app = harness(t, { altitude: 100_000 });
app.viewer.camera.computeViewRectangle = () => undefined;
@@ -2783,13 +2840,13 @@ test('every styling path retains the mode palette and exact unpadded size', asyn
parts.rendering.paintMode(entry, 'subway');
check('#FF4538', 30);
app.style('thermal');
check('#FFFFFF', 36);
check('#FFFFFF', 39);
parts.selection.clearSelection();
check('#FFFFFF', 30);
check('#FFFFFF', 26);
app.vision('nvg', true);
check('#FFFFFF', 30);
check('#FFFFFF', 26);
parts.selection.selectVehicle(entry.key);
check('#FFFFFF', 36);
check('#FFFFFF', 39);
app.vision('normal', false);
check('#FF4538', 30);
parts.selection.clearSelection();
@@ -3673,3 +3730,256 @@ test('transit polls the supplied source and cancels it when disabled', async (t)
await app.layer.update();
assert.equal(calls.length, before);
});
test('selected trail QA fixture survives repeated live CapMetro snapshots', async (t) => {
const { TRAIL_VISIBILITY_FEED } =
await import('../../../scripts/qa-transit-scenes.mjs');
const { getRegisteredTransitFeed } =
await import('../../data/transitFeeds.js');
const app = harness(t, { at: { lat: 30.267, lon: -97.7431 } });
app.layer.enable(app.viewer);
const { ingestion, selection } = app.layer._transitPartsForTest();
const now = Date.now();
ingestion.applySnapshot(
TRAIL_VISIBILITY_FEED,
{
fetchedAt: now,
vehicles: [vehicle('trail-visible', 30.267, -97.7431, now / 1000)],
},
{ stale: false },
);
const key = `${TRAIL_VISIBILITY_FEED.id}:trail-visible`;
selection.selectVehicle(key);
assert.equal(app.state()._selectedKey, key);
for (let poll = 0; poll <= MISSED_POLLS_TO_DROP; poll++) {
ingestion.applySnapshot(
getRegisteredTransitFeed('capmetro-austin'),
{
fetchedAt: now + poll,
vehicles: [vehicle('live-bus', 30.268, -97.7431, now / 1000)],
},
{ stale: false },
);
}
assert.ok(
app.state()._vehicles.has(key),
'live polls must not evict the selected fixture',
);
assert.equal(app.state()._selectedKey, key);
assert.ok(
app.state()._vehicles.has('capmetro-austin:live-bus'),
'live ingestion still runs',
);
});
for (const jump of ['setView', 'flyTo']) {
test(`${jump} recovers a cold hidden vehicle within one visibility interval`, async (t) => {
const app = harness(t, { floorAt: () => undefined });
let floor;
app.viewer.scene.globe.show = true;
app.viewer.scene.globe.getHeight = () => floor;
app.serve('mbta', () => ({
status: 200,
body: snapshot('mbta', 'MBTA', [
vehicle('cold', 42.36, -71.06, reported()),
]),
}));
app.layer.enable(app.viewer);
await app.layer.update();
const entry = app.vehicles()[0];
assert.equal(entry.marker.show, false);
assert.equal(entry.heightPending, true);
// Surface tiles are now loaded at the camera destination. No poll, floor
// timer or preRender is allowed to bootstrap the visibility recovery.
clearTimeout(app.state()._floorTimer);
app.state()._floorTimer = null;
app.viewer.camera[jump] = () => {
floor = 12;
app.viewer.camera.changed.raiseEvent();
};
app.viewer.camera[jump]();
app.advance(250);
assert.equal(entry.marker.show, true);
assert.equal(entry.heightPending, false);
assert.equal(entry.surfaceReady, true);
assert.equal(entry.visibility.heightPending, false);
assert.equal(entry.visibility.surfaceReady, true);
});
}
test('selected history is prepared while its head is hidden and remains shown outside the head frustum', async (t) => {
const app = harness(t);
app.layer.enable(app.viewer);
app.layer._loadTransitFleetForTest(1, BOSTON);
const entry = app.vehicles()[0],
parts = app.layer._transitPartsForTest();
entry.marker.show = false;
app.state()._visible.delete(entry);
app.state()._moving.delete(entry);
parts.selection.selectVehicle(entry.key);
const trail = parts.trails.diagnostics();
assert.ok(trail.segments > 0);
assert.ok(trail.body);
assert.equal(trail.body.show, true);
parts.trails.update();
assert.equal(trail.body.show, true);
app.state()._vehicles.delete(entry.key);
parts.trails.update();
assert.equal(trail.body.show, false);
app.state()._vehicles.set(entry.key, entry);
});
test('selected draped history prepares geometry before surface heights resolve', async (t) => {
const app = harness(t, { floorAt: () => undefined });
app.layer.enable(app.viewer);
app.layer._loadTransitFleetForTest(1, BOSTON);
const entry = app.vehicles()[0],
parts = app.layer._transitPartsForTest();
delete entry.qaFloorM;
entry.marker.show = false;
entry.heightPending = true;
// Exercise the real GroundPolylinePrimitive branch, without a WebGL context.
const width = Cesium.ContextLimits._maximumAliasedLineWidth;
Cesium.ContextLimits._maximumAliasedLineWidth = 1;
t.after(() => {
Cesium.ContextLimits._maximumAliasedLineWidth = width;
});
app.viewer.scene.frameState = { context: { depthTexture: true } };
app.viewer.scene.groundPrimitives = app.viewer.scene.primitives;
parts.selection.selectVehicle(entry.key);
const trail = parts.trails.diagnostics();
assert.equal(trail.ground, true);
assert.ok(trail.body instanceof Cesium.GroundPolylinePrimitive);
assert.ok(trail.segments > 0);
assert.equal(trail.body.show, true);
assert.equal(
entry.displayPaths.size,
0,
'unresolved marker corridors remain unavailable',
);
});
// A camera pose can change without a viewport-membership revision (notably
// a top-down orbit). Exercise the actual frame pass with an otherwise idle fleet.
test('parked transit reprojects held and reported courses at the bounded camera cadence', async (t) => {
const { createRendering } = await import('./rendering.js');
t.mock.timers.enable({ apis: ['Date'], now: 1000 });
const position = Cesium.Cartesian3.fromDegrees(0, 0, 20);
const cameraPosition = Cesium.Cartesian3.fromDegrees(0, 0, 1000);
const scene = {
frameState: { mode: Cesium.SceneMode.SCENE3D },
canvas: { clientWidth: 1280, clientHeight: 800 },
camera: {
positionWC: cameraPosition,
heading: 0,
pitch: -Math.PI / 2,
roll: 0,
frustum: new Cesium.PerspectiveFrustum({
fov: Math.PI / 3,
aspectRatio: 1.6,
near: 1,
far: 1e7,
}),
},
};
const pose = (heading) => {
const camera = scene.camera;
camera.heading = heading;
camera.rightWC = new Cesium.Cartesian3(
0,
Math.cos(heading),
-Math.sin(heading),
);
camera.upWC = new Cesium.Cartesian3(
0,
Math.sin(heading),
Math.cos(heading),
);
camera.viewMatrix = Cesium.Matrix4.computeView(
cameraPosition,
new Cesium.Cartesian3(-1, 0, 0),
camera.upWC,
camera.rightWC,
new Cesium.Matrix4(),
);
};
pose(0);
const make = (key, courseDeg, bearing) => ({
key,
courseDeg,
record: { bearing },
sample: { segmentCourseDeg: NaN },
marker: { position, rotation: 0.7, show: true },
});
const held = make('held', 90, 270);
const reportedOnly = make('reported', null, 90);
const unknown = make('unknown', null, null);
const hidden = make('hidden', 90, 90);
const state = {
_viewer: { scene },
_enabled: true,
_vehicles: new Map(
[held, reportedOnly, unknown, hidden].map((e) => [e.key, e]),
),
_visible: new Set([held, reportedOnly, unknown]),
_moving: new Set(),
_heightDirty: new Set(),
_rotationAt: 0,
_rotationRevision: -1,
_cameraRevision: 0,
_rotationDirty: false,
};
const noop = () => {};
const rendering = createRendering({
state,
services: {
render: {
governorRequestRender: noop,
holdContinuousRender: noop,
releaseContinuousRender: noop,
},
},
parts: { height: { nearGround: () => false }, trails: { update: noop } },
});
rendering.onPreRender();
const before = [held.marker.rotation, reportedOnly.marker.rotation];
pose(Math.PI / 2);
t.mock.timers.tick(100);
rendering.onPreRender();
assert.equal(
held.marker.rotation,
before[0],
'no rotation pass before 200 ms',
);
t.mock.timers.tick(100);
rendering.onPreRender();
for (const [i, entry] of [held, reportedOnly].entries()) {
const delta = Math.atan2(
Math.sin(entry.marker.rotation - before[i]),
Math.cos(entry.marker.rotation - before[i]),
);
assert.ok(
Math.abs(delta - Math.PI / 2) < 0.01,
`${entry.key}: rotation delta ${delta}`,
);
assert.equal(entry.courseDeg, 90);
}
assert.equal(
unknown.marker.rotation,
0,
'no course means screen-up, never a stale angle',
);
assert.equal(
hidden.marker.rotation,
0.7,
'hidden vehicles are not projected',
);
state._selectedKey = unknown.key;
unknown.marker.rotation = 0.7;
rendering.onPreRender();
assert.equal(
unknown.marker.rotation,
0,
'selected unknown course also stays screen-up',
);
});
src/layers/transit/movement.js
+4 -1
View File
@@ -264,7 +264,10 @@ export function displayCourse(entry, nowMs) {
const target = Number.isFinite(entry.sample?.segmentCourseDeg)
? entry.sample.segmentCourseDeg
: null;
if (target === null) return entry.courseDeg ?? null;
if (target === null) {
if (Number.isFinite(entry.courseDeg)) return entry.courseDeg;
return Number.isFinite(entry.record?.bearing) ? entry.record.bearing : null;
}
if (entry.courseDeg === null || !Number.isFinite(entry.courseEvalAt)) {
return target;
}
src/layers/transit/movement.test.mjs
+19
View File
@@ -144,3 +144,22 @@ test('mesh-floor sampling owns fully initialized numeric scratch before the firs
assert.deepEqual(Object.keys(value), shapes[i]),
);
});
test('course fallback prefers held course, then finite reported bearing, then unknown', () => {
for (const [held, bearing, expected] of [
[90, 270, 90],
[null, 90, 90],
[NaN, 0, 0],
[null, null, null],
[null, NaN, null],
[null, Infinity, null],
]) {
const e = {
courseDeg: held,
sample: { segmentCourseDeg: NaN },
record: { bearing },
};
applyDisplayCourse(e, 100);
assert.equal(e.courseDeg, expected);
}
});
src/layers/transit/qaMetrics.js
+72
View File
@@ -329,3 +329,75 @@ export function reduceTrailHead(anchor, target) {
selection: anchor?.selection ?? null,
};
}
/** Repeated off/on patches isolate stable, trail-correlated framebuffer changes. */
export function reduceTrailPixels(on, off, evidence = {}) {
const { onAgain, offAgain, samples = [], sprite, tilesReady } = evidence;
const finitePoint = (p) =>
p && [p.x, p.y, p.radius].every(Number.isFinite) && p.radius > 0;
const stable = [],
eligible = [];
const hits = Array.from({ length: 8 }, (_, i) => {
const point = samples[i];
eligible[i] = !!(
tilesReady === true &&
finitePoint(point) &&
point.inFront === true &&
finitePoint(sprite) &&
Math.hypot(point.x - sprite.x, point.y - sprite.y) >
point.radius + sprite.radius &&
samples
.slice(0, i)
.every(
(prior) =>
!finitePoint(prior) ||
Math.hypot(point.x - prior.x, point.y - prior.y) >
point.radius + prior.radius,
)
);
const a = on?.[i],
b = off?.[i],
c = onAgain?.[i],
d = offAgain?.[i];
stable[i] = false;
if (
!eligible[i] ||
!a?.length ||
a.length % 4 ||
[b, c, d].some((p) => !p || p.length !== a.length)
)
return false;
let matches = 0;
const contrast = (lit, baseline, k) => {
const delta = Math.hypot(
lit[k] - baseline[k],
lit[k + 1] - baseline[k + 1],
lit[k + 2] - baseline[k + 2],
);
const green = lit[k + 1] > lit[k] + 30 && lit[k + 1] > lit[k + 2] + 18;
const dark =
lit[k] + lit[k + 1] + lit[k + 2] <
0.6 * (baseline[k] + baseline[k + 1] + baseline[k + 2]);
return delta >= 40 && (green || dark);
};
for (let k = 0; k < a.length; k += 4) {
for (let channel = 0; channel < 3; channel++) {
const j = k + channel;
if (
![a[j], b[j], c[j], d[j]].every(
(v) => Number.isFinite(v) && v >= 0 && v <= 255,
) ||
Math.abs(b[j] - d[j]) > 8 ||
Math.abs(a[j] - c[j]) > 8 ||
Math.abs(a[j] - b[j] - (c[j] - d[j])) > 8
)
return false;
}
if (contrast(a, b, k) && contrast(c, d, k)) matches++;
}
stable[i] = true;
return matches >= 2;
});
const present = hits.filter(Boolean).length;
return { hits, stable, eligible, present, total: 8, pass: present >= 6 };
}
src/layers/transit/qaMetrics.test.mjs
+103
View File
@@ -328,3 +328,106 @@ test('trail-head acceptance names every missing and failed condition', async ()
false,
);
});
const trailPatch = (rgb) =>
Array.from({ length: 49 }, () => [...rgb, 255]).flat();
const trailEvidence = (on, off) => ({
onAgain: on,
offAgain: off,
tilesReady: true,
samples: Array.from({ length: 8 }, (_, i) => ({
x: i * 20 + 20,
y: 20,
radius: 3,
inFront: true,
})),
sprite: { x: 300, y: 20, radius: 24 },
});
test('trail pixels require repeatable contrast at six distinct samples outside the sprite', async () => {
const { reduceTrailPixels } = await import('./qaMetrics.js');
const off = Array.from({ length: 8 }, () => trailPatch([150, 150, 150]));
const on = off.map((p, i) => (i < 6 ? trailPatch([94, 240, 138]) : p));
const evidence = trailEvidence(on, off);
assert.equal(reduceTrailPixels(on, off, evidence).pass, true);
const five = on.map((p, i) => (i === 5 ? off[i] : p));
assert.equal(
reduceTrailPixels(five, off, trailEvidence(five, off)).pass,
false,
);
for (const rgb of [
[5, 8, 12],
[126, 126, 126],
]) {
const patches = off.map(() => trailPatch(rgb));
assert.equal(
reduceTrailPixels(patches, off, trailEvidence(patches, off)).present,
rgb[0] === 5 ? 8 : 0,
);
assert.equal(
reduceTrailPixels(patches, patches, trailEvidence(patches, patches))
.present,
0,
);
}
assert.equal(
reduceTrailPixels(on, off).pass,
false,
'two reads are insufficient',
);
assert.equal(
reduceTrailPixels(on, off, { ...evidence, tilesReady: false }).pass,
false,
);
assert.equal(
reduceTrailPixels(on, off, {
...evidence,
samples: Array(8).fill(evidence.samples[0]),
}).pass,
false,
);
assert.equal(
reduceTrailPixels(on, off, {
...evidence,
sprite: { x: 80, y: 20, radius: 200 },
}).pass,
false,
);
assert.equal(reduceTrailPixels([], [], trailEvidence([], [])).pass, false);
});
test('background refinement without a trail cannot pass repeated off/on acceptance', async () => {
const { reduceTrailPixels } = await import('./qaMetrics.js');
const grey = (n) => Array.from({ length: 8 }, () => trailPatch([n, n, n]));
const off = grey(100),
on = grey(30);
const evidence = trailEvidence(on, off);
assert.equal(
reduceTrailPixels(on, off, { ...evidence, offAgain: grey(30) }).pass,
false,
'one background transition is not a trail',
);
assert.equal(
reduceTrailPixels(on, off, {
...evidence,
offAgain: grey(170),
onAgain: grey(100),
}).pass,
false,
'equal deltas on a drifting baseline are not a trail',
);
assert.equal(
reduceTrailPixels(on, off, { ...evidence, onAgain: off }).pass,
false,
'contrast must repeat',
);
const first = off.map((p) => p.map((v, i) => (i < 8 ? on[0][i] : v)));
const second = off.map((p) =>
p.map((v, i) => (i >= 8 && i < 16 ? on[0][i] : v)),
);
assert.equal(
reduceTrailPixels(first, off, { ...evidence, onAgain: second }).pass,
false,
'the same pixels must change twice',
);
});
src/layers/transit/rendering.js
+35 -20
View File
@@ -1,5 +1,8 @@
import * as Cesium from 'cesium';
import { perspectiveProjectedRotation } from '../../data/iconOrientation.js';
import {
cameraPoseSignature,
perspectiveProjectedRotation,
} from '../../data/iconOrientation.js';
import {
updatePlayback,
applyDisplayCourse,
@@ -97,6 +100,7 @@ export function createRendering({ state, services, parts }) {
nearGround,
);
entry.surfaceReady = !!known;
entry.heightPending = !known;
entry.marker.show = !!known && vehicleInView(entry);
if (known) {
entry.marker.position = state._scratchCartesian;
@@ -307,20 +311,27 @@ export function createRendering({ state, services, parts }) {
const scene = state._viewer?.scene;
if (!scene?.camera) return;
if (now - state._rotationAt < ROTATION_REFRESH_MS) return;
if (
state._rotationRevision === state._cameraRevision &&
!state._rotationDirty &&
state._moving.size === 0
)
return;
state._rotationAt = now;
const cameraChanged = state._rotationRevision !== state._cameraRevision;
const pose = cameraPoseSignature(scene.camera);
const cameraChanged =
state._rotationPose !== pose ||
state._rotationRevision !== state._cameraRevision;
if (!cameraChanged && !state._rotationDirty && state._moving.size === 0)
return;
state._rotationPose = pose;
state._rotationRevision = state._cameraRevision;
state._rotationDirty = false;
const monoNow = performance.now();
for (const entry of state._visible) {
// Idle contacts still need a course when their first usable bearing arrives.
if (!state._moving.has(entry)) applyDisplayCourse(entry, monoNow);
if (entry.key === state._selectedKey) continue;
const course = entry.courseDeg;
if (course === null) continue;
if (!Number.isFinite(course)) {
entry.marker.rotation = 0;
entry.rotationCourse = null;
continue;
}
const position = entry.marker.position;
if (
!cameraChanged &&
@@ -416,17 +427,15 @@ export function createRendering({ state, services, parts }) {
parts.trails.update();
refreshRotations(now);
const selected = state._vehicles.get(state._selectedKey);
if (
selected &&
state._visible.has(selected) &&
selected.courseDeg !== null
) {
selected.marker.rotation = perspectiveProjectedRotation(
state._viewer.scene,
selected.marker.position,
selected.courseDeg,
selected.marker.rotation,
);
if (selected && state._visible.has(selected)) {
selected.marker.rotation = Number.isFinite(selected.courseDeg)
? perspectiveProjectedRotation(
state._viewer.scene,
selected.marker.position,
selected.courseDeg,
selected.marker.rotation,
)
: 0;
}
if (state._heightDirty.size) governorRequestRender('transit-height-batch');
syncRenderHold();
@@ -523,6 +532,10 @@ export function createRendering({ state, services, parts }) {
else state._visible.delete(entry);
if (visible && entry.track?.count) {
if (!wasVisible && !entry.qaFixture) syncPlayback(entry, now);
// Re-entry can advance into an unprepared corridor; loaded tiles can
// also resolve a cold path without a poll or a render-loop wakeup.
if (!wasVisible || entry.surfaceReady === false || entry.heightPending)
parts.trails.prepareEntry(entry);
// Surface completion must recover while requestRenderMode is idle.
// Otherwise surfaceReady=false prevents the very frame that clears it.
if (!state._moving.has(entry)) {
@@ -532,6 +545,8 @@ export function createRendering({ state, services, parts }) {
}
entry.marker.show =
visible && !entry.heightPending && entry.surfaceReady !== false;
visibility.heightPending = !!entry.heightPending;
visibility.surfaceReady = entry.surfaceReady ?? null;
schedulePlayback(entry);
changed ||= visible !== wasVisible || wasShown !== entry.marker.show;
}
src/layers/transit/trails.js
+33 -12
View File
@@ -18,7 +18,9 @@ const MODE_COLOR = {
ferry: '#5FD6FF',
unknown: '#D8DDE5',
};
export const TRAIL_VERTEX_LIMIT = 2048;
// Final Cesium batching uses 3,152 bytes per two-lane edge.
// The 1,278-instance body plus 64 bytes/instance reserve stays below 2 MiB.
export const TRAIL_VERTEX_LIMIT = 640;
const STEP_M = 25;
/** Shared prepared paths. Floors are aligned to work with Google 3D tiles. */
@@ -63,6 +65,7 @@ export function createTrails({ state, services, parts, source }) {
entry.trailSegments = [];
entry.trailVertices = 0;
}
const draped = entry === selected && ensureRenderer()?.diagnostics().ground;
const paths = new Map(),
all = [],
a = {},
@@ -113,16 +116,28 @@ export function createTrails({ state, services, parts, source }) {
if (entry === selected)
for (let i = activeIndex - 1; i >= 0; i--) order.push(i);
entry.trailTruncated = false;
let markerVertices = 0;
let markerIntervals = Math.max(0, entry.track.count - 1 - activeIndex);
for (const i of order) {
readFix(entry.track, i, a);
readFix(entry.track, i + 1, b);
const markerCorridor = i >= activeIndex;
if (markerCorridor) markerIntervals--;
if (a.epoch !== b.epoch || b.flags & FIX_FLAGS.BREAK) continue;
if (entry !== selected && b.t < entry.sample.displayT) continue;
const n = Math.max(1, Math.ceil(fixDistanceM(a, b) / STEP_M));
if (vertices + n + 1 > TRAIL_VERTEX_LIMIT) {
entry.trailTruncated = true;
continue;
}
const desired = Math.max(1, Math.ceil(fixDistanceM(a, b) / STEP_M));
// Reserve endpoints for every future marker interval. Sparse reports
// coarsen the active path instead of losing the vehicle to the body cap.
const n = markerCorridor
? Math.min(
desired,
TRAIL_VERTEX_LIMIT - markerVertices - 2 * markerIntervals - 1,
)
: desired;
const retainBody = vertices + n + 1 <= TRAIL_VERTEX_LIMIT;
if (!retainBody || n < desired) entry.trailTruncated = true;
if (!markerCorridor && !retainBody) continue;
if (markerCorridor) markerVertices += n + 1;
const positions = [],
heights = [];
let valid = true;
@@ -136,17 +151,21 @@ export function createTrails({ state, services, parts, source }) {
heights.push(h);
if (h === null) {
valid = false;
positions.push(null);
// Ground polylines consume longitude/latitude and drape themselves.
// Unknown floors still disqualify the marker corridor.
positions.push(
draped ? Cesium.Cartesian3.fromDegrees(point.lon, point.lat) : null,
);
} else
positions.push(
Cesium.Cartesian3.fromDegrees(point.lon, point.lat, h),
);
}
signature += `${a.seq}/${b.seq}:${heights.join(',')};`;
vertices += n + 1;
if (!valid) continue;
paths.set(a.seq, { positions, toSeq: b.seq });
if (entry === selected && fixDistanceM(a, b) > 0) {
if (retainBody) vertices += n + 1;
if (valid) paths.set(a.seq, { positions, toSeq: b.seq });
if (!valid && !draped) continue;
if (entry === selected && retainBody && fixDistanceM(a, b) > 0) {
for (let k = 0; k < n; k++)
all.push({
fromSeq: a.seq,
@@ -216,7 +235,9 @@ export function createTrails({ state, services, parts, source }) {
}
function update() {
if (!selected || !renderer) return;
renderer.setVisible(state._enabled && selected.marker?.show !== false);
renderer.setVisible(
state._enabled && state._vehicles.get(selected.key) === selected,
);
renderer.setDisplaySample(selected.sample, selected.marker?.position);
}
function select(entry) {
src/radioMarkup.test.mjs
+3 -2
View File
@@ -1,3 +1,4 @@
import { readRealtimeSource } from './testSupport/readRealtimeSource.mjs';
import { GEV_REALTIME_TOOLS } from '../server/providers/openai/tools.js';
import { readShellSource } from './testSupport/readShellSource.mjs';
import { expandApplicationHtml } from '../build/application-html.js';
@@ -18,7 +19,7 @@ const radio = ['playback', 'interaction'].map(name =>
readFileSync(new URL(`./layers/radio/${name}.js`, import.meta.url), 'utf8')
).join('\n').replace(/layerState\.|parts\.\w+\./g, '');
const rocketLaunches = readLayerSource(new URL('./data/rocketLaunches.js', import.meta.url), 'utf8');
const realtime = readFileSync(new URL('./voice/realtimeController.js', import.meta.url), 'utf8');
const realtime = readRealtimeSource();
const voice = readFileSync(new URL('./voice/actionSchemas.js', import.meta.url), 'utf8') + '\n' + ['toolDescriptions', 'instructions'].map(name => readFileSync(new URL(`../server/providers/openai/${name}.js`, import.meta.url), 'utf8')).join('\n');
const css = readStylesheet(new URL('../style.css', import.meta.url));
@@ -334,7 +335,7 @@ test('Radio disclosure is explicit, starts closed while off, and preserves playb
assert.doesNotMatch(renderMethod, /_radioMiniExpanded\s*=\s*false.*audioState === 'playing'/s);
assert.match(ui, /contextRadioDetailsBtn/);
const syncStart = ui.indexOf('\n _syncPanelCollapseButton(panelEl)');
const syncMethod = ui.slice(syncStart, ui.indexOf('\n /**', syncStart + 10));
const syncMethod = ui.slice(syncStart, ui.indexOf('\n }', syncStart + 10));
assert.doesNotMatch(syncMethod, /contextRadioDetailsBtn[\s\S]*?(?:aria-label|textContent|\.title)/);
});
src/reasonableDefaults.test.mjs
+2 -1
View File
@@ -253,8 +253,9 @@ test('detection-on-by-default is a default, not an operator override', () => {
const displayActions = uiSource.slice(uiSource.indexOf('this._displayControls ='));
const detectionButton = displayActions.slice(displayActions.indexOf('cycleDetection:'), displayActions.indexOf('toggleModels:'));
assert.match(detectionButton, /cycleDetectionMode\(\)/, 'the button still invokes the detection action');
assert.match(detectionButton, /this\._detectionUserOverridden = true;/,
assert.match(detectionButton, /this\.claimDetection\(\);/,
'and the detection control still claims the override when the operator uses it');
assert.match(uiSource, /claimDetection: \(\) => \{\s*this\._visualSettings\._detectionUserOverridden = true;/);
// Style-switch semantics are unchanged: Normal is still not a preset owner,
// so switching TO Normal does not re-apply or clear anything.
src/scenes/cameraMotion.js
+70
View File
@@ -0,0 +1,70 @@
import { sampleCameraMove } from '../director/camera.js';
/** Own one authored camera animation and settle it immediately on cancellation or replacement. */
export function createCameraMotion({
applyPose,
now = () => performance.now(),
requestFrame = (callback) => requestAnimationFrame(callback),
cancelFrame = (handle) => cancelAnimationFrame(handle),
} = {}) {
let active = null;
let disposed = false;
const cancel = () => active?.finish(false);
return {
get active() {
return active !== null;
},
cancel,
destroy() {
disposed = true;
cancel();
},
play(move, token) {
cancel();
if (disposed || token?.cancelled || token?.signal?.aborted)
return Promise.resolve(false);
if (!Number.isFinite(move.durationSec) || move.durationSec <= 0)
throw new RangeError('Camera move duration must be positive');
return new Promise((resolve, reject) => {
const run = { handle: null, finish: null };
const startedAt = now();
const onAbort = () => run.finish(false);
run.finish = (completed, error) => {
if (active !== run) return;
active = null;
if (run.handle !== null) cancelFrame(run.handle);
token?.signal?.removeEventListener('abort', onAbort);
if (error) reject(error);
else resolve(completed);
};
active = run;
token?.signal?.addEventListener('abort', onAbort, { once: true });
const tick = () => {
if (active !== run) return;
run.handle = null;
if (disposed || token?.cancelled || token?.signal?.aborted) {
run.finish(false);
return;
}
try {
const progress = Math.min(
1,
Math.max(0, (now() - startedAt) / (move.durationSec * 1000)),
);
if (applyPose(sampleCameraMove(move, progress)) === false) {
run.finish(false);
return;
}
// Applying a pose can synchronously transfer camera ownership.
if (active !== run) return;
if (progress >= 1) run.finish(true);
else run.handle = requestFrame(tick);
} catch (error) {
run.finish(false, error);
}
};
tick();
});
},
};
}
src/scenes/cameraMotion.test.mjs
+85
View File
@@ -0,0 +1,85 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createCameraMotion } from './cameraMotion.js';
const move = {
durationSec: 2,
easing: 'linear',
from: { lat: 0, lon: 0, alt: 100, heading: 0, pitch: 0, roll: 0 },
to: { lat: 2, lon: 2, alt: 200, heading: 0, pitch: 0, roll: 0 },
};
function harness(apply) {
let time = 0;
let next = 0;
const frames = new Map();
const poses = [];
const owner = createCameraMotion({
now: () => time,
requestFrame: (cb) => {
const id = ++next;
frames.set(id, cb);
return id;
},
cancelFrame: (id) => frames.delete(id),
applyPose: (pose) => {
poses.push(pose);
return apply?.(pose);
},
});
return {
owner,
frames,
poses,
tick(ms) {
time = ms;
const callbacks = [...frames.values()];
frames.clear();
callbacks.forEach((cb) => cb());
},
};
}
test('motion uses the authored curve and releases the frame on completion', async () => {
const h = harness();
const done = h.owner.play(move, { cancelled: false });
assert.deepEqual(h.poses[0], move.from);
h.tick(1000);
assert.equal(h.poses.at(-1).alt, 150);
h.tick(2000);
assert.equal(await done, true);
assert.deepEqual(h.poses.at(-1), move.to);
assert.equal(h.frames.size, 0);
assert.equal(h.owner.active, false);
});
test('abort and replacement settle immediately and revoke already queued callbacks', async () => {
const h = harness();
const abort = new AbortController();
const first = h.owner.play(move, { signal: abort.signal });
const stale = [...h.frames.values()][0];
abort.abort();
assert.equal(await first, false);
const second = h.owner.play(move, {});
const count = h.poses.length;
stale();
assert.equal(h.poses.length, count);
h.owner.destroy();
assert.equal(await second, false);
assert.equal(h.frames.size, 0);
assert.equal(await h.owner.play(move, {}), false);
});
test('synchronous cancellation from pose application schedules no abandoned frame', async () => {
let owner;
const h = harness(() => owner.cancel());
owner = h.owner;
assert.equal(await owner.play(move, {}), false);
assert.equal(h.frames.size, 0);
});
test('failed pose application settles and invalid durations cannot schedule a loop', async () => {
const h = harness(() => {
throw new Error('camera unavailable');
});
await assert.rejects(h.owner.play(move, {}), /camera unavailable/);
assert.equal(h.frames.size, 0);
assert.throws(
() => h.owner.play({ ...move, durationSec: 0 }, {}),
/duration/,
);
});
src/scenes/dataPacks/controller.js
+23
View File
@@ -0,0 +1,23 @@
import { createDataPackSession } from '../../director/packs/session.js';
import { createPackPresentations } from './presentation.js';
/** Bind selected shot packs to one viewer and expose copied lifecycle diagnostics. */
export function createSceneDataPacks(viewer, { sources = {} } = {}) {
const targets = new Map();
const session = createDataPackSession({
sources,
adapters: createPackPresentations(viewer, targets),
});
return {
...session,
sourceIds: () => Object.keys(sources),
getTargets: () => new Map(targets),
apply(scene, shot, token) {
const wanted = new Set(shot.dataPackIds || []);
return session.load(
(scene.dataPacks || []).filter((pack) => wanted.has(pack.id)),
{ anchors: scene.anchors, signal: token?.signal },
);
},
};
}
src/scenes/dataPacks/geometry.js
+77
View File
@@ -0,0 +1,77 @@
import * as Cesium from 'cesium';
import { decodePackGeoJSON } from '../../director/packs/geojson.js';
const xyz = (p) => Cesium.Cartesian3.fromDegrees(...p);
/** Render a bounded geometry pack in owned batches; no asynchronous entity geometry or update loop. */
export function renderPackGeometry({ asset, pack }, handle) {
if (!['application/json', 'application/geo+json'].includes(asset.mimeType))
throw new Error('Expected GeoJSON');
const features = decodePackGeoJSON(asset.bytes);
const polygons = [];
let lines;
for (const feature of features) {
const id = { packId: pack.id, featureId: feature.id };
if (feature.type === 'Point') {
const entity = handle.add({
name: `${pack.id} / ${feature.id}`,
position: xyz(feature.coordinates),
point: {
pixelSize: 12,
color: Cesium.Color.CYAN,
outlineColor: Cesium.Color.BLACK,
outlineWidth: 2,
},
});
handle.feature?.(id, entity);
} else if (feature.type === 'LineString') {
handle.feature?.(id, id);
if (!lines) {
lines = new Cesium.PolylineCollection();
handle.primitive(lines);
}
lines.add({
id,
positions: feature.coordinates.map(xyz),
width: 4,
material: Cesium.Material.fromType('Color', {
color: Cesium.Color.CYAN,
}),
});
} else {
handle.feature?.(id, id);
polygons.push(
new Cesium.GeometryInstance({
id,
geometry: new Cesium.PolygonGeometry({
polygonHierarchy: new Cesium.PolygonHierarchy(
feature.coordinates[0].map(xyz),
feature.coordinates
.slice(1)
.map((ring) => new Cesium.PolygonHierarchy(ring.map(xyz))),
),
perPositionHeight: true,
vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT,
arcType: Cesium.ArcType.GEODESIC,
}),
attributes: {
color: Cesium.ColorGeometryInstanceAttribute.fromColor(
Cesium.Color.CYAN.withAlpha(0.35),
),
},
}),
);
}
}
if (polygons.length)
handle.primitive(
new Cesium.Primitive({
asynchronous: false,
geometryInstances: polygons,
appearance: new Cesium.PerInstanceColorAppearance({
translucent: true,
flat: true,
closed: false,
}),
}),
);
}
src/scenes/dataPacks/presentation.js
+224
View File
@@ -0,0 +1,224 @@
import * as Cesium from 'cesium';
import { renderPackGeometry } from './geometry.js';
function caption(viewer, pack) {
const card = document.createElement('section');
card.dataset.directorPack = pack.id;
Object.assign(card.style, {
color: '#e3faff',
background: '#08141eed',
border: '1px solid #2491a8',
padding: '8px',
margin: '4px',
maxWidth: '260px',
font: '12px sans-serif',
});
const title = document.createElement('div');
title.textContent = `${pack.id} · ${pack.attribution.text} · ${pack.attribution.license}`;
card.append(title);
if (pack.attribution.url) {
const link = document.createElement('a');
link.textContent = 'Source';
link.href = pack.attribution.url;
link.target = '_blank';
link.rel = 'noopener noreferrer';
link.style.color = '#6eeaff';
card.append(link);
}
return card;
}
const xyz = (p) => Cesium.Cartesian3.fromDegrees(...p);
/** Create rendering adapters; data acquisition and authored placement stay independent. */
export function createPackPresentations(viewer, targets = new Map()) {
let panel;
function addCard(pack) {
if (!panel) {
panel = document.createElement('div');
panel.dataset.directorPacks = '';
Object.assign(panel.style, {
position: 'absolute',
right: '10px',
bottom: '70px',
maxHeight: '40vh',
overflowY: 'auto',
zIndex: '30',
});
viewer.container.append(panel);
}
const card = caption(viewer, pack);
panel.append(card);
return card;
}
function resource(pack) {
const entities = [],
primitives = [],
materials = [],
urls = [];
const featureKeys = [];
let card,
destroyed = false;
return {
feature(id, pickedId) {
const key = JSON.stringify([id.packId, id.featureId]);
targets.set(key, pickedId);
featureKeys.push(key);
},
add(spec) {
const entity = viewer.entities.add(spec);
entities.push(entity);
viewer.scene.requestRender();
return entity;
},
primitive(value) {
primitives.push(viewer.scene.primitives.add(value));
if (value.appearance?.material)
materials.push(value.appearance.material);
viewer.scene.requestRender();
},
card() {
return (card ||= addCard(pack));
},
url(blob) {
const url = URL.createObjectURL(blob);
urls.push(url);
return url;
},
dispose() {
if (destroyed) return;
destroyed = true;
for (const key of featureKeys.splice(0)) targets.delete(key);
for (const media of card?.querySelectorAll('video,audio') || []) {
media.pause();
media.removeAttribute('src');
media.load();
}
card?.remove();
if (panel && !panel.childElementCount) {
panel.remove();
panel = null;
}
for (const entity of entities.splice(0)) viewer.entities.remove(entity);
for (const primitive of primitives.splice(0))
viewer.scene.primitives.remove(primitive);
for (const material of materials.splice(0)) {
if (!material.isDestroyed()) material.destroy();
}
for (const url of urls.splice(0)) URL.revokeObjectURL(url);
viewer.scene.requestRender();
},
};
}
function guarded(render) {
return async (context) => {
const handle = resource(context.pack);
const abort = () => handle.dispose();
context.signal.addEventListener('abort', abort, { once: true });
try {
context.signal.throwIfAborted();
await render(context, handle);
context.signal.throwIfAborted();
handle.card();
return handle;
} catch (error) {
handle.dispose();
throw error;
} finally {
context.signal.removeEventListener('abort', abort);
}
};
}
return {
geojson: guarded(renderPackGeometry),
image: guarded(async ({ asset, pack, signal }, handle) => {
if (asset.mimeType !== 'image/png') throw new Error('Expected PNG image');
const bytes = asset.bytes;
if (
bytes.length < 24 ||
![137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82].every(
(v, i) => bytes[i] === v,
)
)
throw new Error('Invalid PNG header');
const header = new DataView(
bytes.buffer,
bytes.byteOffset,
bytes.byteLength,
);
const width = header.getUint32(16),
height = header.getUint32(20);
if (!width || !height || width > 4096 || height > 4096)
throw new Error('Image dimensions exceed limit');
const image = new Image();
image.src = handle.url(new Blob([asset.bytes], { type: asset.mimeType }));
const abort = () => {
image.src = '';
};
signal.addEventListener('abort', abort, { once: true });
try {
await image.decode();
} finally {
signal.removeEventListener('abort', abort);
}
signal.throwIfAborted();
if (image.naturalWidth * image.naturalHeight > 16 * 1024 * 1024)
throw new Error('Image dimensions exceed limit');
handle.primitive(
new Cesium.Primitive({
asynchronous: false,
geometryInstances: new Cesium.GeometryInstance({
id: { packId: pack.id },
geometry: new Cesium.RectangleGeometry({
rectangle: Cesium.Rectangle.fromDegrees(...pack.placement.bounds),
height: pack.placement.height,
vertexFormat:
Cesium.MaterialAppearance.MaterialSupport.TEXTURED.vertexFormat,
}),
}),
appearance: new Cesium.MaterialAppearance({
material: Cesium.Material.fromType('Image', { image }),
materialSupport: Cesium.MaterialAppearance.MaterialSupport.TEXTURED,
flat: true,
faceForward: true,
translucent: true,
}),
}),
);
}),
media: guarded(({ asset, pack, anchors }, handle) => {
if (
![
'video/mp4',
'video/webm',
'audio/mpeg',
'audio/ogg',
'audio/wav',
'audio/webm',
].includes(asset.mimeType)
)
throw new Error('Unsupported media');
const anchor = anchors.find(
(item) => item.id === pack.placement.anchorId,
);
if (!anchor) throw new Error('Missing media anchor');
handle.add({
name: pack.id,
position: xyz([anchor.lon, anchor.lat, anchor.alt]),
point: { pixelSize: 16, color: Cesium.Color.YELLOW },
label: {
text: pack.id,
font: '14px sans-serif',
pixelOffset: new Cesium.Cartesian2(0, -24),
},
});
const media = document.createElement(
asset.mimeType.startsWith('video/') ? 'video' : 'audio',
);
media.controls = true;
media.preload = 'none';
media.style.width = '240px';
media.src = handle.url(new Blob([asset.bytes], { type: asset.mimeType }));
handle.card().append(media);
}),
};
}
src/scenes/dataPacks/presentation.test.mjs
+57
View File
@@ -0,0 +1,57 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createPackPresentations } from './presentation.js';
test('abort releases an in-flight image URL before the decoder settles or the viewer is destroyed', async () => {
let settle;
const pending = new Promise((resolve) => {
settle = resolve;
});
const priorImage = globalThis.Image;
const priorRevoke = URL.revokeObjectURL;
const revoked = [];
globalThis.Image = class {
decode() {
return pending;
}
};
URL.revokeObjectURL = (url) => {
revoked.push(url);
priorRevoke(url);
};
const viewer = {
scene: { requestRender() {} },
entities: {
remove() {
assert.fail('No entity should be acquired');
},
},
};
const signalOwner = new AbortController();
const bytes = new Uint8Array(24);
bytes.set([137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82]);
const header = new DataView(bytes.buffer);
header.setUint32(16, 8);
header.setUint32(20, 8);
try {
const rendering = createPackPresentations(viewer).image({
pack: {},
asset: { bytes, mimeType: 'image/png' },
signal: signalOwner.signal,
});
const rejected = assert.rejects(rendering, /abort/i);
signalOwner.abort();
assert.equal(
revoked.length,
1,
'object URL must be released synchronously with cancellation',
);
settle();
await rejected;
assert.equal(revoked.length, 1, 'late decode cannot dispose twice');
} finally {
settle();
globalThis.Image = priorImage;
URL.revokeObjectURL = priorRevoke;
}
});
src/scenes/director.js
+404 -976
View File
File diff suppressed because it is too large. Load diff
src/scenes/director.test.mjs
+123 -3
View File
@@ -614,10 +614,11 @@ function installSceneRuntime(project = PROJECT_FIXTURE) {
removeEventListener() {},
body: { classList: noopClassList, appendChild() {} },
};
const stored = new Map([['godsEyeView.sceneProject.v2', JSON.stringify(project)]]);
globalThis.localStorage = {
getItem: () => JSON.stringify(project),
setItem() {},
removeItem() {},
getItem: (key) => stored.get(key) ?? null,
setItem: (key, value) => stored.set(key, value),
removeItem: (key) => stored.delete(key),
};
return () => {
@@ -1397,3 +1398,122 @@ test('Scene load outcomes exclude superseded and disposed completions', async ()
assert.equal(seen.length, count);
} finally { restore(); }
});
test('invalid and unsupported imports retain the current project, selection and saved bytes', async () => {
const { director, restore } = makeDirector();
try {
const project = director._project;
const selected = director._selectedShotId;
const saved = localStorage.getItem('godsEyeView.sceneProject.v2');
for (const value of ['{}', '{"version":99,"scenes":[]}', '{"scenes":[{"shots":"bad"}]}']) {
await director.importProjectFile({ name: 'bad.json', text: async () => value });
assert.equal(director._project, project);
assert.equal(director._selectedShotId, selected);
assert.equal(localStorage.getItem('godsEyeView.sceneProject.v2'), saved);
assert.match(director._presentation.status, /Import failed: \$/);
}
let read = false;
await director.importProjectFile({ size: 6 * 1024 * 1024, text: async () => { read = true; } });
assert.equal(read, false);
assert.equal(director._project, project);
} finally { restore(); }
});
test('newer imports win delayed file reads, and an empty project is preserved', async () => {
const { director, restore } = makeDirector();
try {
let release;
const older = director.importProjectFile({ name: 'old.json', text: () => new Promise((resolve) => { release = resolve; }) });
await director.importProjectFile({ name: 'empty.json', text: async () => '{"version":3,"scenes":[]}' });
release(JSON.stringify(PROJECT_FIXTURE));
await older;
assert.deepEqual(director._project.scenes, []);
assert.equal(director._selectedSceneId, null);
assert.deepEqual(JSON.parse(localStorage.getItem('godsEyeView.sceneProject.v2')).scenes, []);
} finally { restore(); }
});
test('unsupported stored documents cannot be overwritten by fallback edits', async () => {
const { director, restore } = makeDirector({ project: { version: 99, scenes: [] } });
try {
const saved = localStorage.getItem('godsEyeView.sceneProject.v2');
assert.ok(director._storageReadError);
director._project.scenes[0].title = 'Fallback edit';
director._saveProject();
assert.equal(localStorage.getItem('godsEyeView.sceneProject.v2'), saved);
await director.importProjectFile({ name: 'valid.json', text: async () => JSON.stringify(PROJECT_FIXTURE) });
assert.equal(director._storageReadError, null);
assert.equal(JSON.parse(localStorage.getItem('godsEyeView.sceneProject.v2')).version, 6);
} finally { restore(); }
});
test('valid import settles a cancelled load before replacing the project', async () => {
const { director, styleManager, restore } = makeDirector();
let release;
styleManager.applyVisualState = () => new Promise((resolve) => { release = resolve; });
try {
const before = director._project;
const load = director.loadShot('scene-1', 'shot-a');
await settle();
const importing = director.importProjectFile({ name: 'empty.json', text: async () => '{"version":3,"scenes":[]}' });
await settle();
assert.equal(director._project, before, 'old work still owns cleanup');
release(true);
await Promise.all([load, importing]);
assert.deepEqual(director._project.scenes, []);
assert.equal(director._pendingWork.size, 0);
assert.equal(director.getPlaybackTimingState().activeTimers, 0);
} finally { restore(); }
});
test('a delayed import cannot publish after disposal', async () => {
const { director, restore } = makeDirector();
let release;
try {
const before = director._project;
const reading = director.importProjectFile({ name: 'empty.json', text: () => new Promise((resolve) => { release = resolve; }) });
await director.destroy();
release('{"version":3,"scenes":[]}');
await reading;
assert.equal(director._project, before);
} finally { restore(); }
});
test('invalid authored edits cannot persist an unreadable project over a good save', () => {
const { director, restore } = makeDirector();
try {
const before = localStorage.getItem('godsEyeView.sceneProject.v2');
let notice;
director._toastStorageError = (message) => { notice = message; };
director._project.scenes[0].shots[0].camera.lat = 91;
director._saveProject();
assert.equal(localStorage.getItem('godsEyeView.sceneProject.v2'), before);
assert.match(notice, /camera.lat/);
} finally { restore(); }
});
test('zero camera pitch is preserved by both immediate placement and ordinary flight', async () => {
const { director, viewer, restore } = makeDirector();
try {
let placed;
viewer.camera.setView = (options) => { placed = options; };
const pose = { lat: 10, lon: 20, alt: 500, heading: 0, pitch: 0, roll: 0 };
director._setCameraView(pose);
assert.equal(placed.orientation.pitch, 0);
await director._flyCamera(pose, 0.2, { cancelled: false });
assert.equal(viewer.flights.at(-1).orientation.pitch, 0);
} finally { restore(); }
});
test('camera refusal starts no authored frame or playback clock', async () => {
const { director, styleManager, viewer, restore } = makeDirector();
try {
const shot = director._project.scenes[0].shots[0];
shot.move = { from: { ...shot.camera, altitudeReference: 'ellipsoid' }, easing: 'linear' };
styleManager.runImmediateNavigation = () => false;
assert.equal((await director.startScene('scene-1', { single: true })).reason, 'camera-unavailable');
assert.equal(director._cameraMotion.active, false);
assert.equal(director.getPlaybackTimingState().activeTimers, 0);
assert.deepEqual(viewer.flights, []);
} finally { restore(); }
});
src/scenes/interactions.js
+165
View File
@@ -0,0 +1,165 @@
import * as Cesium from 'cesium';
import { isPointerFree } from '../data/inputOwnership.js';
import { createInteractionSession } from '../director/interactions/session.js';
/** Own the active shot's pick handler, accessible actions and plain-text feedback. */
export function createSceneInteractions(
viewer,
{ execute, available = () => true },
) {
let panel,
status,
card,
handler,
items = [],
targets = new Map();
const buttons = new Map();
const session = createInteractionSession({
execute: (item, signal) => {
if (!isPointerFree() || !available()) return false;
card.replaceChildren();
if (item.action.type === 'card') {
const text = document.createElement('p');
text.textContent = item.action.text;
card.append(text);
if (item.action.url) {
const link = document.createElement('a');
link.textContent = 'Source';
link.style.color = '#6eeaff';
link.href = item.action.url;
link.target = '_blank';
link.rel = 'noopener noreferrer';
card.append(link);
}
return true;
}
return execute(item.action, signal);
},
changed(state) {
for (const [id, button] of buttons) {
button.disabled = state.busy;
button.setAttribute('aria-pressed', String(state.selected === id));
button.style.outline = state.selected === id ? '2px solid #6eeaff' : '';
}
},
});
function clear() {
session.clear();
handler?.destroy();
handler = null;
panel?.remove();
panel = null;
status = null;
card = null;
buttons.clear();
items = [];
targets.clear();
}
async function dispatch(id) {
const current = panel;
const ok = await session.dispatch(id);
if (current && current === panel && status)
status.textContent = ok
? 'Action complete'
: 'Action unavailable or cancelled';
return ok;
}
return {
clear,
destroy: clear,
getState: session.getState,
activate(shot, registered) {
clear();
items = shot.interactions || [];
if (!items.length) return;
targets = registered;
if (
items.some(
(item) =>
!targets.has(
JSON.stringify([item.target.packId, item.target.featureId]),
),
)
) {
items = [];
targets.clear();
throw new Error('Interaction feature is missing from the loaded pack');
}
panel = document.createElement('section');
panel.dataset.directorInteractions = '';
panel.setAttribute('aria-label', 'Scene actions');
Object.assign(panel.style, {
position: 'absolute',
left: '12px',
bottom: '80px',
zIndex: '31',
maxWidth: '300px',
maxHeight: '40vh',
overflowY: 'auto',
background: '#08141eed',
color: '#e3faff',
border: '1px solid #2491a8',
padding: '10px',
font: '13px sans-serif',
});
const owner = panel;
const title = document.createElement('strong');
title.textContent = 'Scene actions';
panel.append(title);
status = document.createElement('p');
status.setAttribute('role', 'status');
status.textContent =
'Select a feature or use Tab and Enter to choose an action.';
panel.append(status);
for (const item of items) {
const button = document.createElement('button');
button.type = 'button';
button.textContent = item.label;
button.dataset.directorAction = item.id;
Object.assign(button.style, {
display: 'block',
background: '#10242e',
color: '#e3faff',
border: '1px solid #397080',
borderRadius: '3px',
padding: '6px 10px',
cursor: 'pointer',
font: 'inherit',
margin: '6px 0',
maxWidth: '100%',
whiteSpace: 'normal',
});
button.addEventListener('click', () => {
if (panel === owner) void dispatch(item.id);
});
buttons.set(item.id, button);
panel.append(button);
}
card = document.createElement('div');
card.dataset.directorActionCard = '';
panel.append(card);
viewer.container.append(panel);
session.activate(items);
handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction((event) => {
if (panel !== owner || !isPointerFree() || !available()) return;
const picked = viewer.scene.pick(event.position)?.id;
const matches = items.filter(
(item) =>
targets.get(
JSON.stringify([item.target.packId, item.target.featureId]),
) === picked,
);
if (!matches.length) return;
for (const item of items) {
const button = buttons.get(item.id);
button.style.outline = matches.includes(item)
? '2px solid #6eeaff'
: '';
}
status.textContent = `Selected feature: ${matches[0].target.featureId}. Choose an action.`;
buttons.get(matches[0].id)?.focus({ preventScroll: true });
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
},
};
}
src/scenes/packs/defaults.js
+11
View File
@@ -0,0 +1,11 @@
import { SCENE_APPEND_RECIPES } from '../recipes.js';
import { createScenePackRegistry } from './registry.js';
import { nepalScenePresentation } from './nepal.js';
/** Compose the installed scene recipes and their trusted presentation rules. */
export function createDefaultScenePacks() {
return createScenePackRegistry({
recipes: SCENE_APPEND_RECIPES,
adapters: [nepalScenePresentation],
});
}
src/scenes/packs/nepal.js
+26
View File
@@ -0,0 +1,26 @@
import { INCIDENT_OVERVIEW_HOLD_SEC } from '../../data/bhoteKoshiIncidentPlaces.js';
/** Existing Nepal presentation rules; authored assets and saved shots stay untouched. */
export const nepalScenePresentation = {
minimumHoldSec(states) {
const overview = states['bhote-koshi-locator'];
return overview?.enabled &&
overview.params?.presentation === 'bhote-koshi-incident-places'
? INCIDENT_OVERVIEW_HOLD_SEC
: 0;
},
resolveVisual(shot, visual, isMapStackAvailable) {
const isNepalShot =
shot?.layers?.['bhote-koshi-2026']?.enabled ||
shot?.layers?.['bhote-koshi-locator']?.enabled;
// A credential is not proof of a loaded tileset. Resolve actual capability at playback time.
return isNepalShot &&
visual.mapStack === 'photoreal' &&
!isMapStackAvailable('photoreal')
? { ...visual, mapStack: 'esri-imagery' }
: visual;
},
cancelMotion(getLayerModule) {
getLayerModule('bhote-koshi-locator')?.cancelSceneMotion?.();
},
};
src/scenes/packs/registry.js
+24
View File
@@ -0,0 +1,24 @@
/** Register trusted scene-pack recipes and presentation adapters at composition time. */
export function createScenePackRegistry({ recipes = [], adapters = [] } = {}) {
const byId = new Map(recipes.map((recipe) => [recipe.id, recipe]));
const rules = [...adapters];
return {
recipeForShot: (shot) => byId.get(shot?.sourcePackId) || null,
minimumHoldSec(states) {
return Math.max(
0,
...rules.map((rule) => rule.minimumHoldSec?.(states) || 0),
);
},
resolveVisual(shot, visual, isMapStackAvailable) {
return rules.reduce(
(result, rule) =>
rule.resolveVisual?.(shot, result, isMapStackAvailable) || result,
visual,
);
},
cancelMotion(getLayerModule) {
for (const rule of rules) rule.cancelMotion?.(getLayerModule);
},
};
}
src/scenes/packs/registry.test.mjs
+56
View File
@@ -0,0 +1,56 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createScenePackRegistry } from './registry.js';
import {
effectiveShotHoldSec,
shotRuntimeDurationSec,
layerStatesForShot,
visualStateForShot,
} from '../shotPresentation.js';
test('registered pack rules apply to another source without editing the Director or saved shots', () => {
const recipe = {
id: 'sample',
runtimeHoldSecByBeat: { arrival: 6 },
runtimeControlsByBeat: {
arrival: { minimumHoldSec: 8, deferEvidenceUntilCameraSettled: true },
},
};
let cancelled = 0;
const packs = createScenePackRegistry({
recipes: [recipe],
adapters: [
{
resolveVisual: (_, visual) => ({ ...visual, mapStack: 'osm' }),
cancelMotion: (getModule) => getModule('sample').cancelSceneMotion(),
},
],
});
const shot = {
id: 'a',
sourcePackId: 'sample',
durationSec: 2,
holdSec: 1,
visual: { style: 'normal' },
layers: {
sample: {
enabled: true,
params: { presentation: 'scene-beat', beatId: 'arrival' },
},
},
};
const scene = { id: 'scene', shots: [shot], releaseLayerIds: ['other'] };
const before = structuredClone(shot);
assert.equal(shotRuntimeDurationSec(scene, shot, packs), 10);
assert.equal(effectiveShotHoldSec(scene, shot, packs), 8);
const states = layerStatesForShot(scene, shot, packs, {
cameraSettled: true,
});
assert.equal(states.sample.params.sceneControls.cameraSettled, true);
assert.equal(states.sample.params.sceneContext.holdSec, 8);
assert.equal(states.other.enabled, false);
assert.equal(visualStateForShot(shot, packs, () => true).mapStack, 'osm');
packs.cancelMotion(() => ({ cancelSceneMotion: () => cancelled++ }));
assert.equal(cancelled, 1);
assert.deepEqual(shot, before);
});
src/scenes/playbackAdapter.js
+77
View File
@@ -0,0 +1,77 @@
/** Connect the portable Director runner to the existing scene presentation. */
export function createScenePlaybackAdapter(director, defaultShotDurationSec) {
let timing;
let travel;
return {
async releaseScene(scene, token) {
const released = await director._releaseSceneLayers(scene, token);
if (!token || released) director._loadedSceneId = null;
return released;
},
selectShot({ scene, shot, index, total }) {
director._selectedSceneId = scene.id;
director._selectedShotId = shot.id;
director._renderSceneSelect();
director._renderShotList();
director._updateStatus(
`Running ${index + 1}/${total}: ${scene.title} / ${shot.title}`,
);
director._logEvent('shot_start', {
sceneId: scene.id,
shotId: shot.id,
title: shot.title,
index,
});
},
applyVisual({ shot, token }) {
return director.styleManager.applyVisualState(
director._visualStateForShot(shot),
{ isCurrent: () => !token.cancelled && !token.signal?.aborted },
);
},
async applyLayers({ scene, shot, token }) {
const result = await director._applyLayerStates(
director._layerStatesForShot(scene, shot),
token,
);
if (
!token.cancelled &&
!result.refused.length &&
!(await director._applyDataPacks(scene, shot, token))
)
throw new Error('Data packs unavailable');
return result;
},
travel({ scene, shot, token }) {
director._loadedSceneId = scene.id;
const duration = shot.durationSec || defaultShotDurationSec;
timing = director._startSceneClockTicker(scene, shot, token);
travel = director._beginShotTravel(scene, shot, duration);
const flight = director._flyShotCamera(scene, shot, duration, token);
director._publishShotTravel(scene, shot, travel);
return flight;
},
settle({ scene, shot, token }) {
director._settleShotLayerStates(scene, shot, token, travel);
},
hold({ scene, shot, token }) {
return director._holdShot(scene, shot, token);
},
completeShot({ scene, shot, index }) {
director._clock.stopSceneTimer();
director._publishSceneClock(scene, shot, timing.endElapsedSec, {
running: true,
});
director._logEvent('shot_end', {
sceneId: scene.id,
shotId: shot.id,
index,
});
},
complete() {
director._setProgress(1);
director._updateStatus('Scene run complete');
director._logEvent('scene_run_complete', {});
},
};
}
src/scenes/project.js
+404
View File
@@ -0,0 +1,404 @@
/** Authored project defaults and legacy migrations; no editor or playback state. */
import { SCENE_DOCUMENT_VERSION } from '../director/document.js';
import { SCENE_RECIPES } from './recipes.js';
import { MAP_STACKS } from '../maps/catalog.js';
import {
BLOOM_INTENSITY_DEFAULT,
BLOOM_SCALE_VERSION,
decodeBloomIntensity,
} from '../bloom.js';
/** @constant {number} Current schema version for project migration */
export const PROJECT_VERSION = SCENE_DOCUMENT_VERSION;
/** @constant {number} Fallback camera flight duration per shot (seconds) */
export const DEFAULT_SHOT_DURATION_SEC = 4;
/** @constant {number} Default hold/pause after a shot completes (seconds) */
export const DEFAULT_HOLD_SEC = 0.9;
const SCENE_MAP_STACK_IDS = new Set(MAP_STACKS.map(({ id }) => id));
/**
* Generate a short random identifier with the given prefix.
* @param {string} prefix - e.g. 'shot', 'scene'
* @returns {string} Identifier like "shot-a1b2c3d4"
*/
export function uid(prefix) {
return `${prefix}-${Math.random().toString(36).slice(2, 10)}`;
}
/**
* Deep-clone a JSON-serializable value via round-trip stringify/parse.
* @param {*} value
* @returns {*}
*/
export function deepClone(value) {
return JSON.parse(JSON.stringify(value));
}
/**
* Normalize a raw layer state entry into a canonical { enabled, params? } shape.
* Accepts both boolean shorthand and full object forms.
* @param {boolean|Object} entry - Raw layer state (boolean or { enabled, params })
* @returns {{ enabled: boolean, params?: Object }}
*/
export function normalizeLayerEntry(entry) {
if (entry && typeof entry === 'object') {
return {
enabled: !!entry.enabled,
params:
entry.params && typeof entry.params === 'object'
? deepClone(entry.params)
: undefined,
};
}
return { enabled: !!entry };
}
/**
* Normalize a raw bloom post-processing state, migrating intensity values
* across bloom scale versions so older saved projects render correctly.
* @param {Object} rawBloom - Raw bloom state from storage or recipe
* @param {Object} [options]
* @param {number} [options.projectVersion] - Schema version of the source project
* @param {number} [options.fallbackIntensity] - Default intensity if not stored
* @returns {{ enabled: boolean, intensity: number, version: number }}
*/
function normalizeBloomState(
rawBloom = {},
{ projectVersion = PROJECT_VERSION, fallbackIntensity = 50 } = {},
) {
// Determine which bloom scale the stored value was encoded under.
// Older projects (version < 3) used scale version 1.
const explicitVersion = Number(rawBloom.version);
const bloomVersion = Number.isFinite(explicitVersion)
? explicitVersion
: projectVersion >= 3
? BLOOM_SCALE_VERSION
: 1;
const rawIntensity = Number.isFinite(Number(rawBloom.intensity))
? Number(rawBloom.intensity)
: fallbackIntensity;
return {
enabled: !!rawBloom.enabled,
intensity: decodeBloomIntensity(rawIntensity, bloomVersion),
version: BLOOM_SCALE_VERSION,
};
}
/**
* Convert a static scene recipe (from recipes.js) into a mutable scene object
* with fully normalized shots. Each keyframe in the recipe's cameraPath becomes
* one shot, inheriting the recipe's style, post, and layer configuration.
* @param {Object} recipe - A SCENE_RECIPES entry
* @returns {{ id: string, title: string, releaseLayerIds: string[], shots: Object[] }}
*/
export function recipeToScene(recipe) {
const post = recipe.post || {};
const ui = recipe.ui || {};
const styleParams =
post.styleParams && typeof post.styleParams === 'object'
? deepClone(post.styleParams)
: {};
// Normalize layer targets from the recipe into canonical form
const layers = {};
for (const [layerId, target] of Object.entries(recipe.layers || {})) {
layers[layerId] = normalizeLayerEntry(target);
}
// Derive HUD visibility/variant from recipe's ui.hudMode string
const hudMode = ui.hudMode || 'minimal';
const hudVisible = hudMode !== 'off';
const hudVariant = hudMode === 'minimal' ? 'minimal' : 'tactical';
// Convert each cameraPath keyframe into a shot with shared visual state
const path = recipe.cameraPath || [];
const shots = path.map((keyframe, idx) => {
const keyframeLayers = deepClone(layers);
for (const [layerId, target] of Object.entries(keyframe.layers || {})) {
keyframeLayers[layerId] = normalizeLayerEntry(target);
}
const mapStack = keyframe.mapStack || post.mapStack;
return {
id: uid('shot'),
title: keyframe.title || `Shot ${idx + 1}`,
durationSec: Math.max(
0.2,
keyframe.duration || DEFAULT_SHOT_DURATION_SEC,
),
holdSec: Math.max(0, keyframe.hold || 0),
camera: {
lat: keyframe.lat,
lon: keyframe.lon,
alt: keyframe.alt,
heading: keyframe.heading || 0,
pitch: keyframe.pitch || -40,
roll: keyframe.roll || 0,
},
visual: {
style: recipe.style || 'normal',
bloom: {
enabled:
typeof post.bloom === 'number' ? post.bloom > 0 : !!post.bloom,
intensity:
typeof post.bloom === 'number'
? decodeBloomIntensity(post.bloom, 1)
: BLOOM_INTENSITY_DEFAULT,
version: BLOOM_SCALE_VERSION,
},
sharpen: {
enabled:
typeof post.sharpen === 'boolean' ? post.sharpen : !!post.sharpen,
intensity: 65,
},
hud: {
visible: hudVisible,
variant: hudVariant,
},
detection: {
mode: post.detectionMode || 'OFF',
density: 35,
},
...(SCENE_MAP_STACK_IDS.has(mapStack) ? { mapStack } : {}),
styleParams,
},
layers: keyframeLayers,
...(recipe.id ? { sourcePackId: recipe.id } : {}),
...(recipe.version ? { sourcePackVersion: recipe.version } : {}),
};
});
return {
id: recipe.id || uid('scene'),
title: recipe.title || 'Untitled Scene',
releaseLayerIds: [
...new Set(
(Array.isArray(recipe.releaseLayerIds)
? recipe.releaseLayerIds
: []
).filter((layerId) => typeof layerId === 'string' && layerId.trim()),
),
],
appliedShotPacks: [],
shots,
};
}
/**
* Create a fresh default project by converting all built-in SCENE_RECIPES.
* @returns {Object} A new project object with version, timestamps, and scenes
*/
export function createDefaultProject() {
return {
version: PROJECT_VERSION,
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
installedBuiltInSceneIds: SCENE_RECIPES.filter(
(recipe) => typeof recipe.installAlongsideSceneId === 'string',
).map((recipe) => recipe.id),
scenes: SCENE_RECIPES.map(recipeToScene),
};
}
/**
* Normalize a raw shot object from storage or capture into a fully validated
* shape with safe defaults for every field. Handles version migration for
* bloom intensity and coerces all numeric fields.
* @param {Object} rawShot - Raw shot data (may be incomplete or from an older schema)
* @param {number} [index=0] - Positional index used for fallback title
* @param {Object} [options]
* @param {number} [options.projectVersion] - Schema version of the enclosing project
* @returns {Object} Fully normalized shot
*/
export function normalizeShot(
rawShot,
index = 0,
{ projectVersion = PROJECT_VERSION } = {},
) {
const camera = rawShot?.camera || {};
const visual = rawShot?.visual || {};
const bloom = visual.bloom || {};
const sharpen = visual.sharpen || {};
const hud = visual.hud || {};
const detection = visual.detection || {};
return {
id: rawShot?.id || uid('shot'),
title: rawShot?.title || `Shot ${index + 1}`,
durationSec: Math.max(
0.2,
Number(rawShot?.durationSec) || DEFAULT_SHOT_DURATION_SEC,
),
holdSec: Math.max(0, Number(rawShot?.holdSec) || 0),
camera: camera.anchorId
? {
anchorId: camera.anchorId,
heading: Number(camera.heading) || 0,
pitch: Number.isFinite(Number(camera.pitch))
? Number(camera.pitch)
: -35,
roll: Number(camera.roll) || 0,
}
: {
lat: Number(camera.lat) || 0,
lon: Number(camera.lon) || 0,
alt: Number.isFinite(Number(camera.alt)) ? Number(camera.alt) : 800,
heading: Number(camera.heading) || 0,
pitch: Number.isFinite(Number(camera.pitch))
? Number(camera.pitch)
: -35,
roll: Number(camera.roll) || 0,
...(camera.altitudeReference || rawShot?.move
? { altitudeReference: camera.altitudeReference || 'ellipsoid' }
: {}),
},
...(rawShot?.interactions
? { interactions: deepClone(rawShot.interactions) }
: {}),
...(rawShot?.dataPackIds ? { dataPackIds: [...rawShot.dataPackIds] } : {}),
...(rawShot?.move ? { move: deepClone(rawShot.move) } : {}),
visual: {
style: visual.style || 'normal',
bloom: normalizeBloomState(bloom, {
projectVersion,
fallbackIntensity: 50,
}),
sharpen: {
enabled: !!sharpen.enabled,
intensity: Math.max(
0,
Math.min(
100,
Number.isFinite(Number(sharpen.intensity))
? Number(sharpen.intensity)
: 65,
),
),
},
hud: {
visible: typeof hud.visible === 'boolean' ? hud.visible : true,
variant: typeof hud.variant === 'string' ? hud.variant : 'tactical',
},
detection: {
...(typeof detection.allocation === 'string'
? { allocation: detection.allocation }
: {}),
...(Number.isFinite(Number(detection.fadePct))
? { fadePct: Number(detection.fadePct) }
: {}),
...(Number.isFinite(Number(detection.outsideOpacityPct))
? { outsideOpacityPct: Number(detection.outsideOpacityPct) }
: {}),
mode: typeof detection.mode === 'string' ? detection.mode : 'OFF',
density: Math.max(
0,
Math.min(
100,
Number.isFinite(Number(detection.density))
? Number(detection.density)
: 35,
),
),
},
...(visual.scope && typeof visual.scope === 'object'
? { scope: deepClone(visual.scope) }
: {}),
...(SCENE_MAP_STACK_IDS.has(visual.mapStack)
? { mapStack: visual.mapStack }
: {}),
styleParams:
visual.styleParams && typeof visual.styleParams === 'object'
? deepClone(visual.styleParams)
: {},
},
layers: Object.fromEntries(
Object.entries(rawShot?.layers || {}).map(([layerId, value]) => [
layerId,
normalizeLayerEntry(value),
]),
),
...(typeof rawShot?.sourcePackId === 'string'
? { sourcePackId: rawShot.sourcePackId }
: {}),
...(Number.isFinite(Number(rawShot?.sourcePackVersion))
? { sourcePackVersion: Number(rawShot.sourcePackVersion) }
: {}),
};
}
/**
* Normalize and migrate an entire project object loaded from storage or import.
* Defaults and migrates validated documents; empty projects remain empty.
* @param {Object|null} rawProject - Raw project data (potentially from an older schema)
* @returns {Object} Fully normalized project at the current PROJECT_VERSION
*/
export function normalizeProject(rawProject) {
if (!rawProject || typeof rawProject !== 'object')
return createDefaultProject();
const projectVersion = Number.isFinite(Number(rawProject.version))
? Number(rawProject.version)
: 1;
const scenesRaw = Array.isArray(rawProject.scenes) ? rawProject.scenes : [];
const scenes = scenesRaw
.map((scene, sceneIdx) => {
const shotsRaw = Array.isArray(scene?.shots) ? scene.shots : [];
const shots = shotsRaw.map((shot, shotIdx) =>
normalizeShot(shot, shotIdx, { projectVersion }),
);
return {
id: scene?.id || uid('scene'),
title: scene?.title || `Scene ${sceneIdx + 1}`,
...(scene?.dataPacks ? { dataPacks: deepClone(scene.dataPacks) } : {}),
...(scene?.anchors ? { anchors: deepClone(scene.anchors) } : {}),
releaseLayerIds: [
...new Set(
(Array.isArray(scene?.releaseLayerIds)
? scene.releaseLayerIds
: []
).filter(
(layerId) => typeof layerId === 'string' && layerId.trim(),
),
),
],
appliedShotPacks: (Array.isArray(scene?.appliedShotPacks)
? scene.appliedShotPacks
: []
)
.filter((entry) => typeof entry?.id === 'string')
.map((entry) => ({
id: entry.id,
version: Number(entry.version) || 1,
...(entry.shotBindings && typeof entry.shotBindings === 'object'
? {
shotBindings: Object.fromEntries(
Object.entries(entry.shotBindings).filter(
([title, shotId]) =>
typeof title === 'string' && typeof shotId === 'string',
),
),
}
: {}),
})),
shots,
};
})
// Keep scenes that have shots or at least a title
.filter((scene) => scene.shots.length > 0 || scene.title);
return {
version: PROJECT_VERSION,
createdAt: rawProject.createdAt || new Date().toISOString(),
updatedAt: rawProject.updatedAt || new Date().toISOString(),
installedBuiltInSceneIds: [
...new Set(
(Array.isArray(rawProject.installedBuiltInSceneIds)
? rawProject.installedBuiltInSceneIds
: []
).filter((sceneId) => typeof sceneId === 'string' && sceneId.trim()),
),
],
scenes,
};
}
src/scenes/sharing.js
+404
View File
@@ -0,0 +1,404 @@
import { withShareSignal } from '../director/sharing/lifetime.js';
import {
readSceneShare,
createSceneBundle,
BUNDLE_SOURCE,
} from '../director/sharing/bundle.js';
import { describeSceneShare } from '../director/sharing/preview.js';
import { stringifySceneDocument } from '../director/document.js';
import {
editSceneDetails,
selectSceneDocument,
} from '../director/authoring.js';
import { createSceneDialog, mountSceneSharing } from '../ui/sceneSharing.js';
import { PACK_LIMITS } from '../director/packs/manifest.js';
function download(text, name) {
const url = URL.createObjectURL(
new Blob([text], { type: 'application/json' }),
);
const link = document.createElement('a');
link.href = url;
link.download = name;
document.body.append(link);
try {
link.click();
} finally {
link.remove();
URL.revokeObjectURL(url);
}
}
const subset = (value, keys) =>
Object.fromEntries(
keys
.filter((key) => Object.hasOwn(value, key))
.map((key) => [key, value[key]]),
);
const sceneKeys = ['anchors', 'dataPacks'];
const shotKeys = [
'camera',
'move',
'durationSec',
'holdSec',
'dataPackIds',
'interactions',
];
const json = (value) => JSON.stringify(value, null, 2);
const mimeFor = (file) =>
file.type ||
{
json: 'application/json',
geojson: 'application/geo+json',
png: 'image/png',
mp4: 'video/mp4',
webm: 'video/webm',
mp3: 'audio/mpeg',
wav: 'audio/wav',
ogg: 'audio/ogg',
}[file.name.split('.').at(-1)];
/** Own staged imports, author drafts and share bytes separately from playback and project state. */
export function createSceneSharing(director) {
let dialog,
controller,
disposed = false,
staged = null,
busy = false;
const alive = (owner) =>
!disposed && controller === owner && !owner.signal.aborted;
function close() {
controller?.abort();
controller = null;
dialog?.dispose();
dialog = null;
staged = null;
busy = false;
}
function open(title) {
close();
if (disposed) return null;
controller = new AbortController();
dialog = createSceneDialog(title, close);
return controller;
}
async function run(owner, job) {
if (!alive(owner) || busy) return;
busy = true;
try {
await job();
} catch (error) {
if (alive(owner))
dialog.status.textContent =
error?.name === 'SceneDocumentError'
? error.message
: 'Could not complete this action. Check the file, references and selected assets.';
} finally {
if (alive(owner)) busy = false;
}
}
const currentProject = () => json(director._project);
function inventory(input) {
const report = describeSceneShare(input, {
sourceIds: director._dataPacks.sourceIds(),
layerIds: director.dataManager.getAll().map((l) => l.id),
});
dialog.text(
`${report.scenes} scenes · ${report.shots} shots · ${report.packs.length} data packs`,
);
for (const pack of report.packs)
dialog.text(
`${pack.scene} / ${pack.id}: ${pack.status}. File: ${pack.path}. ${pack.attribution.text} · ${pack.attribution.license}`,
);
if (report.missingLayers.length)
dialog.text(`Unavailable layers: ${report.missingLayers.join(', ')}`);
if (report.externalContent)
dialog.text(
'This scene uses registered content or linked media. Those external files are not included in a scene bundle. Their original notices still apply.',
);
if (report.bundledBytes)
dialog.text(
`${report.bundledBytes} bundled bytes verified. Files stay in memory for this session. Reimport the bundle after reloading the app.`,
);
return report;
}
async function preview(file) {
const owner = open('Review scene import');
if (!owner) return;
const expected = currentProject();
dialog.text('Nothing is loaded or changed until you apply this file.');
await run(owner, async () => {
const input = await readSceneShare(file, { signal: owner.signal });
if (!alive(owner)) return;
staged = input;
inventory(input);
dialog.status.textContent = 'Ready to import';
dialog.text(
'Apply replaces the current project. Export your current project first if you want to keep both.',
);
const apply = dialog.button('Apply import', () =>
run(owner, async () => {
if (expected !== currentProject()) throw new Error('Project changed');
apply.disabled = true;
const ok = await director.importProjectFile(file, {
prepared: input,
expectedProject: expected,
signal: owner.signal,
});
if (alive(owner)) {
if (ok) close();
else {
apply.disabled = false;
dialog.status.textContent =
'Import was not applied. The current project may have changed.';
}
}
}),
);
apply.dataset.directorApplyImport = '';
});
}
function edit() {
const scene = director._getSelectedScene(),
shot = scene?.shots.find((s) => s.id === director._selectedShotId);
if (!scene || !shot) {
director._updateStatus('Select a scene and shot first');
return;
}
const owner = open('Edit scene details');
if (!owner) return;
const original = structuredClone(director._project),
expected = currentProject();
dialog.text(
'Camera positions use degrees and meters above the ellipsoid. Drafts are validated before they replace your saved scene.',
);
const sceneText = dialog.input(
'Anchors and data packs',
json(subset(scene, sceneKeys)),
{ multiline: true },
);
const shotText = dialog.input(
'Shot camera, timing, packs and actions',
json(subset(shot, shotKeys)),
{ multiline: true },
);
const anchorName = dialog.input('New anchor ID', 'anchor-1');
dialog.button(
'Capture camera as anchor',
() =>
run(owner, async () => {
const details = JSON.parse(sceneText.value),
camera = director.styleManager.getCameraState();
if (!camera) throw new Error('Camera unavailable');
const anchors = details.anchors || [];
if (anchors.some((a) => a.id === anchorName.value))
throw new Error('Duplicate anchor');
details.anchors = [
...anchors,
{
id: anchorName.value,
lat: camera.lat,
lon: camera.lon,
alt: camera.alt,
altitudeReference: 'ellipsoid',
},
];
editSceneDetails(
original,
scene.id,
shot.id,
details,
JSON.parse(shotText.value),
);
sceneText.value = json(details);
dialog.status.textContent = 'Anchor added to draft';
}),
dialog.body,
);
dialog.button(
'Set move start to current camera',
() =>
run(owner, async () => {
const details = JSON.parse(shotText.value),
camera = director.styleManager.getCameraState();
if (!camera) throw new Error('Camera unavailable');
details.move = {
from: {
...subset(camera, [
'lat',
'lon',
'alt',
'heading',
'pitch',
'roll',
]),
altitudeReference: 'ellipsoid',
},
easing: 'cubic-in-out',
};
if (!details.camera.anchorId)
details.camera.altitudeReference = 'ellipsoid';
details.durationSec = Math.max(0.2, details.durationSec || 3);
editSceneDetails(
original,
scene.id,
shot.id,
JSON.parse(sceneText.value),
details,
);
shotText.value = json(details);
dialog.status.textContent =
'Move added to draft; destination remains the shot camera';
}),
dialog.body,
);
dialog.button(
'Use ordinary flight',
() => {
if (!alive(owner)) return;
try {
const details = JSON.parse(shotText.value);
delete details.move;
shotText.value = json(details);
} catch {
dialog.status.textContent = 'Invalid shot JSON';
}
},
dialog.body,
);
const apply = dialog.button('Apply details', () =>
run(owner, async () => {
if (expected !== currentProject()) throw new Error('Project changed');
const project = editSceneDetails(
original,
scene.id,
shot.id,
JSON.parse(sceneText.value),
JSON.parse(shotText.value),
);
const ok = await director.importProjectFile(
{
name: 'scene details',
text: async () => stringifySceneDocument(project),
},
{
prepared: { project, assets: director._bundleAssets.snapshot() },
expectedProject: expected,
signal: owner.signal,
selection: { sceneId: scene.id, shotId: shot.id },
},
);
if (alive(owner) && ok) close();
}),
);
apply.dataset.directorApplyDetails = '';
}
function share() {
let project;
try {
project = selectSceneDocument(
director._project,
director._selectedSceneId,
);
} catch {
director._updateStatus('Select a scene first');
return;
}
const owner = open('Share selected scene');
if (!owner) return;
const paths = new Set(
project.scenes.flatMap((s) =>
(s.dataPacks || [])
.filter((p) => p.source.adapter === BUNDLE_SOURCE)
.map((p) => p.source.path),
),
);
const existing = new Map(
[...director._bundleAssets.snapshot()].filter(([path]) =>
paths.has(path),
),
);
staged = { project, assets: existing };
inventory(staged);
dialog.text(
'Scene JSON preserves authored settings and attribution. It does not include asset files. Bundles include only pack files you choose here or previously imported bundle files.',
);
dialog.button('Download scene JSON', () => {
if (alive(owner)) download(stringifySceneDocument(project), 'scene.json');
});
const files = dialog.input('Choose data-pack files', '', { type: 'file' });
files.multiple = true;
const folder = dialog.input('Or choose a data-pack folder', '', {
type: 'file',
});
folder.multiple = true;
folder.setAttribute('webkitdirectory', '');
dialog.button('Download asset bundle', () =>
run(owner, async () => {
const selected = [...files.files, ...folder.files];
const packs = project.scenes.flatMap((s) => s.dataPacks || []);
const text = await createSceneBundle(
project,
async (pack, { signal }) => {
if (
pack.source.adapter === BUNDLE_SOURCE &&
existing.has(pack.source.path)
)
return existing.get(pack.source.path);
const exact = selected.filter(
(f) =>
f.webkitRelativePath === pack.source.path ||
f.webkitRelativePath?.split('/').slice(1).join('/') ===
pack.source.path,
);
const name = pack.source.path.split('/').at(-1),
matches = exact.length
? exact
: selected.filter((f) => f.name === name);
const keys = new Set(
packs
.filter((p) => p.source.path.split('/').at(-1) === name)
.map((p) => JSON.stringify(p.source)),
);
if (matches.length !== 1 || (!exact.length && keys.size > 1))
throw new Error('Missing or ambiguous file');
const file = matches[0];
if (!file.size || file.size > PACK_LIMITS.bytes)
throw new Error('Asset size limit');
const bytes = new Uint8Array(
await withShareSignal(file.arrayBuffer(), signal),
);
signal.throwIfAborted();
return { bytes, mimeType: mimeFor(file) };
},
{ signal: owner.signal },
);
if (alive(owner)) {
download(text, 'scene.gevbundle.json');
dialog.status.textContent = 'Asset bundle downloaded';
}
}),
);
}
const unmount = () => {};
let removeToolbar = unmount;
return {
preview,
edit,
share,
close,
mount() {
removeToolbar();
removeToolbar = mountSceneSharing({ edit, share });
},
getState: () => ({
open: !!dialog,
busy,
stagedAssets: staged?.assets.size || 0,
}),
destroy() {
disposed = true;
close();
removeToolbar();
},
};
}
src/scenes/shotPresentation.js
+171
View File
@@ -0,0 +1,171 @@
const DEFAULT_SHOT_DURATION_SEC = 4;
const clamp01 = (value) => Math.max(0, Math.min(1, value));
const deepClone = (value) => JSON.parse(JSON.stringify(value));
/** Prepare scene-owned layer state, timing context and seek/travel controls. */
export function layerStatesForShot(
scene,
shot,
packs,
{ cameraSettled = false, cameraTravel = null, sceneSeek = null } = {},
) {
const states = deepClone(shot?.layers || {});
const shotIndex = scene?.shots?.findIndex(({ id }) => id === shot?.id) ?? -1;
const sceneShotDurations =
scene?.shots?.map((sceneShot) =>
shotRuntimeDurationSec(scene, sceneShot, packs),
) || [];
const sceneDurationSec = sceneShotDurations.reduce(
(sum, duration) => sum + duration,
0,
);
const authoredSceneElapsedSec = sceneShotDurations
.slice(0, Math.max(0, shotIndex))
.reduce((sum, duration) => sum + duration, 0);
const sceneElapsedSec = sceneSeek
? Math.max(
0,
Math.min(sceneDurationSec, Number(sceneSeek.sceneElapsedSec) || 0),
)
: authoredSceneElapsedSec;
const sourceRecipe = packs.recipeForShot(shot);
for (const state of Object.values(states)) {
if (state?.params?.presentation !== 'scene-beat') continue;
state.params.sceneSurface ||= shot.sourcePackId
? 'evidence-beat'
: 'panel-only';
const runtimeControls =
sourceRecipe?.runtimeControlsByBeat?.[state.params.beatId];
if (runtimeControls) {
state.params.sceneControls = {
...state.params.sceneControls,
...runtimeControls,
...(runtimeControls.deferEvidenceUntilCameraSettled
? { cameraSettled }
: {}),
...(sceneSeek
? {
timelineSeek: {
shotElapsedSec: Number(sceneSeek.shotElapsedSec) || 0,
flightDurationSec: Number(sceneSeek.flightDurationSec) || 0,
holdDurationSec: Number(sceneSeek.holdDurationSec) || 0,
holdElapsedSec: Number(sceneSeek.holdElapsedSec) || 0,
cameraProgress: clamp01(Number(sceneSeek.cameraProgress) || 0),
holdProgress: clamp01(Number(sceneSeek.holdProgress) || 0),
},
}
: {}),
};
if (runtimeControls.evidencePathDuringCamera && cameraTravel) {
state.params.sceneControls.cameraTravel = { ...cameraTravel };
}
}
state.params.sceneContext = {
sceneId: scene.id,
sceneTitle: scene.title,
shotId: shot.id,
shotTitle: shot.title,
shotIndex,
shotCount: scene.shots.length,
durationSec: shot.durationSec || DEFAULT_SHOT_DURATION_SEC,
holdSec: effectiveShotHoldSec(scene, shot, packs, states),
sceneElapsedSec,
sceneDurationSec,
sceneProgress:
sceneDurationSec > 0 ? sceneElapsedSec / sceneDurationSec : 0,
...(sceneSeek
? {
shotElapsedSec: Number(sceneSeek.shotElapsedSec) || 0,
shotProgress: clamp01(Number(sceneSeek.shotProgress) || 0),
seeking: true,
}
: {}),
};
}
for (const layerId of scene?.releaseLayerIds || []) {
if (!Object.hasOwn(states, layerId)) states[layerId] = { enabled: false };
}
return states;
}
/** Resolve recipe map preferences and registered presentation fallbacks. */
export function visualStateForShot(shot, packs, isMapStackAvailable) {
const sourceRecipe = packs.recipeForShot(shot);
const sceneBeatState = Object.values(shot?.layers || {}).find(
(state) => state?.params?.presentation === 'scene-beat',
);
const controls = {
...sceneBeatState?.params?.sceneControls,
...sourceRecipe?.runtimeControlsByBeat?.[sceneBeatState?.params?.beatId],
};
if (controls.imageryComparison === true) {
return { ...(shot.visual || {}), mapStack: 'esri-imagery' };
}
if (
sourceRecipe?.standaloneSurfaceBeatIds?.includes(
sceneBeatState?.params?.beatId,
)
) {
return { ...(shot.visual || {}), mapStack: 'esri-imagery' };
}
const visual = sourceRecipe?.photorealSurfaceBeatIds?.includes(
sceneBeatState?.params?.beatId,
)
? { ...(shot.visual || {}), mapStack: 'photoreal' }
: shot?.visual || {};
return packs.resolveVisual(shot, visual, isMapStackAvailable);
}
/** Combine authored holds, registered pack overrides and layer reveal requirements. */
export function effectiveShotHoldSec(
scene,
shot,
packs,
resolvedStates = null,
) {
const states = resolvedStates || layerStatesForShot(scene, shot, packs);
const recipe = packs.recipeForShot(shot);
const overrides = Object.values(states)
.filter(
(state) => state?.enabled && state.params?.presentation === 'scene-beat',
)
.map((state) => recipe?.runtimeHoldSecByBeat?.[state.params.beatId])
.filter((value) => Number.isFinite(value) && value >= 0);
const authoredHoldSec = overrides.length
? Math.max(...overrides)
: Number(shot?.holdSec) || 0;
return Object.values(states).reduce(
(holdSec, state) => {
const controls = state?.params?.sceneControls;
return Math.max(
holdSec,
Number(controls?.minimumHoldSec) || 0,
controls?.evidenceSequence === true
? Number(controls.evidenceSequenceDurationSec) || 0
: 0,
);
},
Math.max(packs.minimumHoldSec(states), authoredHoldSec),
);
}
/** Estimate flight plus effective hold without mutating saved layer parameters. */
export function shotRuntimeDurationSec(scene, shot, packs) {
const states = deepClone(shot?.layers || {});
const sourceRecipe = packs.recipeForShot(shot);
for (const state of Object.values(states)) {
if (state?.params?.presentation !== 'scene-beat') continue;
const runtimeControls =
sourceRecipe?.runtimeControlsByBeat?.[state.params.beatId];
if (runtimeControls) {
state.params.sceneControls = {
...state.params.sceneControls,
...runtimeControls,
};
}
}
return (
(shot?.durationSec || DEFAULT_SHOT_DURATION_SEC) +
effectiveShotHoldSec(scene, shot, packs, states)
);
}
src/sharelink.celestial.test.mjs
+8 -4
View File
@@ -1,3 +1,5 @@
import { DisplayBindings } from './ui/displayBindings.js';
import { LocationNavigation } from './ui/locationNavigation.js';
import { VisualSettings } from './ui/visualSettings.js';
import { readShellSource, shellMethod } from './testSupport/readShellSource.mjs';
import { StyleManager } from './ui/applicationShell.js';
@@ -700,13 +702,15 @@ test('visual input listeners are revoked before asynchronous UI teardown', () =>
const firstAwait = disposal.indexOf('await ');
assert.ok(firstAwait > 0);
const synchronous = disposal.slice(0, firstAwait);
assert.match(synchronous, /this\._applicationShortcuts\?\.destroy\(\)/);
assert.match(synchronous, /this\._displayBindings\.destroy\(\)/);
assert.match(synchronous, /this\._visualSettings\.stop\(\)/);
assert.match(synchronous, /this\._mapSourceControls\?\.destroy\(\)/);
assert.match(synchronous, /this\._clearLayersControl\?\.destroy\(\)/);
assert.match(synchronous, /this\._locationControls\?\.destroy\(\)/);
assert.match(synchronous, /this\._locationLookup\?\.destroy\(\)/);
assert.match(synchronous, /this\._displayControls\?\.destroy\(\)/);
assert.match(synchronous, /this\._locationNavigation\.destroy\(\)/);
assert.match(LocationNavigation.prototype.destroy.toString(), /this\._locationControls\?\.destroy\(\)/);
assert.match(LocationNavigation.prototype.destroy.toString(), /this\._locationLookup\?\.destroy\(\)/);
assert.match(DisplayBindings.prototype.destroy.toString(), /this\._displayControls\?\.destroy\(\)/);
assert.match(DisplayBindings.prototype.destroy.toString(), /this\._applicationShortcuts\?\.destroy\(\)/);
assert.match(VisualSettings.prototype.stop.toString(), /this\._styleParameters\?\.destroy\(\)/);
assert.match(VisualSettings.prototype.stop.toString(), /this\._visualEffects\.stop\(\)/);
});
src/standalone/tools.js
+8
View File
@@ -1,8 +1,16 @@
import { createAssetDirectorySource } from '../director/packs/source.js';
import { createApplicationTools } from '../app/tools.js';
import { startStandaloneChrome } from './startupChrome.js';
export function createStandaloneTools(options) {
return createApplicationTools({
startChrome: startStandaloneChrome,
sceneDataPacks: {
sources: {
assets: createAssetDirectorySource({
baseUrl: new URL('/scene-assets/', window.location.href).href,
}),
},
},
...options,
});
}
src/testSupport/readRealtimeSource.mjs
+23
View File
@@ -0,0 +1,23 @@
import { readFileSync } from 'node:fs';
/** Read voice implementations alongside their compatibility/composition surface. */
export function readRealtimeSource() {
return [
'realtimeConnection',
'realtimeCost',
'realtimeDiagnostics',
'realtimeInput',
'realtimeInputPolicy',
'realtimePreferences',
'realtimeProtocol',
'realtimeRadio',
'realtimeTurns',
'realtimeViewport',
'realtimeFacade',
'realtimeController',
]
.map((name) =>
readFileSync(new URL(`../voice/${name}.js`, import.meta.url), 'utf8'),
)
.join('\n');
}
src/testSupport/readShellSource.mjs
+18
View File
@@ -1,4 +1,10 @@
import { ShellFacade } from '../ui/shellFacade.js';
import { AircraftDisplay } from '../ui/aircraftDisplay.js';
import { LayerBindings } from '../ui/layerBindings.js';
import { DisplayBindings } from '../ui/displayBindings.js';
import { readFileSync } from 'node:fs';
import { CockpitCoordinator } from '../ui/cockpitCoordinator.js';
import { LocationNavigation } from '../ui/locationNavigation.js';
import { StyleManager } from '../ui/applicationShell.js';
import { NavigationController } from '../ui/navigationController.js';
import { ShareRestoration } from '../ui/shareRestoration.js';
@@ -8,10 +14,16 @@ import { PanelChrome } from '../ui/panelChrome.js';
/** Read the state owners as well as the compatibility/composition facade. */
export function readShellSource() {
return [
'locationNavigation',
'cockpitCoordinator',
'navigationController',
'shareRestoration',
'visualSettings',
'panelChrome',
'aircraftDisplay',
'layerBindings',
'displayBindings',
'shellFacade',
'applicationShell',
]
.map((name) =>
@@ -27,7 +39,13 @@ export function shellMethod(name) {
ShareRestoration,
VisualSettings,
PanelChrome,
LocationNavigation,
CockpitCoordinator,
AircraftDisplay,
LayerBindings,
DisplayBindings,
StyleManager,
ShellFacade,
]) {
const method = Object.getOwnPropertyDescriptor(
owner.prototype,
src/tooling/transitQa.test.mjs
+59
View File
@@ -328,6 +328,7 @@ test('sensor sampler waits for postRender and reads framebuffer pixels; stopped
globalThis.Image = previousImage;
});
const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
const readRows = [];
let listener,
reads = 0,
render = true;
@@ -336,6 +337,7 @@ test('sensor sampler waits for postRender and reads framebuffer pixels; stopped
UNSIGNED_BYTE: 2,
readPixels(x, y, w, h, format, type, buffer) {
reads++;
readRows.push(y);
buffer.set([255, 255, 255, 255]);
},
};
@@ -408,13 +410,70 @@ test('sensor sampler waits for postRender and reads framebuffer pixels; stopped
},
};
const page = { evaluate: async (fn, ...args) => fn(...args) };
const sampledLayer =
window.__godsEyeView.dataManager.layers.get('transit').module;
const originalState = sampledLayer._transitStateForTest;
sampledLayer._transitStateForTest = () => {
const state = originalState();
state._vehicles.get('bus').marker.position.y = 0.0025; // Screen y = 199.5.
return state;
};
const pixels = await sampleTransitPixels(page, {});
sampledLayer._transitStateForTest = originalState;
assert.deepEqual(
readRows.slice(0, 9),
[201, 200, 199, 201, 200, 199, 201, 200, 199],
'fractional CSS coordinates must invert the floored framebuffer row',
);
assert.ok(
reads >= 13,
'centre, rings and background come from WebGL readPixels',
);
assert.ok(Math.abs(pixels[0].centre - 1) < 1e-6);
assert.equal(listener, null);
// An opaque window/panel is not a sensor core. Choose another solid patch,
// and reject a raster with no white interior even though alpha/picking pass.
for (let i = 0; i < raster.length; i += 4) raster.fill(0, i, i + 3);
assert.equal((await sampleTransitPixels(page, {})).length, 0);
raster.fill(255);
for (let y = 6; y <= 9; y++)
for (let x = 0; x < 16; x++) {
const i = (y * 16 + x) * 4;
raster.fill(0, i, i + 3);
}
assert.equal(
(await sampleTransitPixels(page, {})).length,
1,
'a body patch away from the central panel remains eligible',
);
// A narrow centre can be opaque yet put the framebuffer sample on its
// antialiased side. Prefer the wider solid band above it, before reading luma.
raster.fill(0);
for (let y = 0; y < 16; y++)
for (let x = 0; x < 16; x++) {
const wide = y >= 3 && y <= 5;
if ((wide && x >= 3 && x <= 12) || (x >= 7 && x <= 9))
raster.fill(255, (y * 16 + x) * 4, (y * 16 + x + 1) * 4);
}
const readStart = readRows.length;
assert.equal((await sampleTransitPixels(page, {})).length, 1);
assert.ok(
readRows[readStart] > 204,
'centre samples use the widest solid band',
);
raster.fill(255);
sampledLayer._transitStateForTest = () => {
const state = originalState();
state._vehicles.get('bus').mode = 'tram';
return state;
};
const tramStart = readRows.length;
assert.equal((await sampleTransitPixels(page, {})).length, 1);
assert.ok(
readRows[tramStart] > 204,
'equal-width tram bands prefer the upper solid body',
);
sampledLayer._transitStateForTest = originalState;
scene.pick = () => ({ id: 'overlapping-label' });
assert.equal(
(await sampleTransitPixels(page, {})).length,
src/ui/aircraftDisplay.js
+83
View File
@@ -0,0 +1,83 @@
/** Own the shared aircraft display preference and its controls. */
export class AircraftDisplay {
constructor({ elements, readDataManager, layout }) {
Object.assign(this, elements, {
readDataManager,
_layoutRightPanels: layout,
});
// Both aircraft layers default to models enabled in proximity mode.
this._models3dEnabled = true;
this._models3dMode = 'proximity';
this._models3dModeBtns = [
document.getElementById('models3d-mode-proximity'),
document.getElementById('models3d-mode-all'),
];
}
get _dataManager() {
return this.readDataManager();
}
_setModels3dParams(params, { origin = 'user' } = {}) {
this._dataManager?.setLayerParams('flights', params, { origin });
this._dataManager?.setLayerParams('military', params, { origin });
}
_syncModels3dFromLayerState(state) {
const options = state?.options?.flights;
if (!options) return;
this._models3dEnabled = options.models3d === true;
this._models3dMode = options.models3dMode === 'all' ? 'all' : 'proximity';
this._syncModels3dButtonState();
this._models3dModeRow?.classList.toggle('visible', this._models3dEnabled);
for (const button of this._models3dModeBtns || []) {
if (!button) continue;
const active = button.dataset.mode === this._models3dMode;
button.classList.toggle('active', active);
button.setAttribute('aria-checked', String(active));
}
this._layoutRightPanels();
}
_syncModels3dModeRow() {
if (this._models3dModeRow)
this._models3dModeRow.classList.toggle('visible', this._models3dEnabled);
this._layoutRightPanels();
}
_initModels3dToggle() {
if (!this._models3dBtn) return;
this._syncModels3dButtonState();
this._syncModels3dModeRow();
}
_setModels3dEnabled(enabled) {
this._models3dEnabled = !!enabled;
this._setModels3dParams({ models3d: this._models3dEnabled });
this._syncModels3dButtonState();
}
_setModels3dMode(mode) {
const normalized = mode === 'all' ? 'all' : 'proximity';
this._models3dMode = normalized;
this._setModels3dParams({ models3dMode: normalized });
for (const button of this._models3dModeBtns) {
if (!button) continue;
const active = button.dataset.mode === normalized;
button.classList.toggle('active', active);
button.setAttribute('aria-checked', String(active));
}
this._syncModels3dButtonState();
}
_syncModels3dButtonState() {
this._models3dBtn?.classList.toggle('active', this._models3dEnabled);
// The lit/dark state is a colour to a sighted operator and nothing at all to
// a screen reader without this. It matters more now that the button ships
// ACTIVE from markup (default-on, 2026-08-22): the very first thing assistive
// tech reported was an unpressed-looking control over an armed layer.
// Mirrors #scope-toggle, which has always carried aria-pressed.
this._models3dBtn?.setAttribute(
'aria-pressed',
String(this._models3dEnabled),
);
}
}
src/ui/applicationShell.js
+224 -2466
View File
File diff suppressed because it is too large. Load diff
src/ui/cockpitCoordinator.js
+408
View File
@@ -0,0 +1,408 @@
import { CockpitViewController, CockpitDisplayPortal } from './cockpit.js';
import { STYLE_STATUS_LABELS } from './visualPresets.js';
import { cockpitEntryAllowed } from '../contextModePolicy.js';
import { formatAwarenessLabel } from '../data/militaryAwarenessEngine.js';
import { enterCockpitWithTracking } from '../cockpitTracking.js';
/** Own Cockpit entry/rollback, readouts and the single Display portal. */
export class CockpitCoordinator {
constructor({
viewer,
services,
elements,
operations,
readDataManager,
readContext,
readActiveStyle,
enterPanels,
exitPanels,
}) {
Object.assign(
this,
{
viewer,
services,
readDataManager,
readContext,
readActiveStyle,
enterPanels,
exitPanels,
},
elements,
operations,
);
const {
flightsLayer,
militaryFlightsLayer,
isTr3b,
toggleTr3b,
militaryAwarenessLayer,
cachedGroundFloor,
cachedMeshFloor,
GROUND_FLOOR_LIFT_M,
meshFloorPreferred,
warmGroundFloor,
sampleMeshFloorCells,
holdContinuousRender,
releaseContinuousRender,
fetchRegionalBrief,
regionalDistanceM,
weatherCodeLabel,
} = services;
this._cockpitDisplayPortal = null;
this.cockpitView = new CockpitViewController(viewer, {
services: {
flightsLayer,
militaryFlightsLayer,
isTr3b,
toggleTr3b,
militaryAwarenessLayer,
formatAwarenessLabel,
cachedGroundFloor,
cachedMeshFloor,
GROUND_FLOOR_LIFT_M,
meshFloorPreferred,
warmGroundFloor,
sampleMeshFloorCells,
holdContinuousRender,
releaseContinuousRender,
fetchRegionalBrief,
regionalDistanceM,
weatherCodeLabel,
},
onVisionChange: (mode, active, options) =>
this._setCockpitVision(mode, active, options),
onCameraTakeover: () =>
this._stampNavigation({ cancelPendingSelection: false }),
getInheritedVisionLabel: () =>
STYLE_STATUS_LABELS[this.activeStyle] ||
String(this.activeStyle || 'normal').toUpperCase(),
isEntryAllowed: () =>
cockpitEntryAllowed({
contextMode: this._contextMode,
contextModeChanging: this._contextModeChanging,
flightsEnabled: !!this._dataManager?.isEnabled('flights'),
militaryEnabled: !!this._dataManager?.isEnabled('military'),
}),
onEntered: () => this.enterPanels(),
onExited: () => this.exitPanels(),
restoreTrackingFrame: (entity) => {
const [layerId, ...idParts] = String(entity?.gevTrackedId || '').split(
':',
);
const trackedId = idParts.join(':');
if (!trackedId) return false;
if (layerId === 'flights')
return flightsLayer.refocusTrackedById?.(trackedId) === true;
if (layerId === 'military')
return militaryFlightsLayer.refocusTrackedById?.(trackedId) === true;
return false;
},
});
}
get _dataManager() {
return this.readDataManager();
}
get _contextMode() {
return this.readContext()?.mode ?? null;
}
get _contextModeChanging() {
return !!this.readContext()?.changing;
}
get activeStyle() {
return this.readActiveStyle();
}
getCockpitState() {
const { militaryAwarenessLayer } = this.services;
const snapshot = militaryAwarenessLayer.getContextSnapshot?.();
const info = this.cockpitView?.readAircraftInfo?.();
const active = Boolean(this.cockpitView?.active);
const gateOpen = Boolean(this.cockpitView?.isEntryAllowed?.());
// "Could Cockpit be ENTERED right now" — so it is false while already
// inside, unconditionally. Cockpit takes the entity off
// `viewer.trackedEntity` on entry and NEXT puts one back, which made this
// flip true/false between calls while `active` stayed true; readers
// (including the voice model) read that as a broken half-entered state.
const entryAllowed =
!active &&
Boolean(gateOpen && info && this.viewer?.trackedEntity?.position);
return {
active,
entryAllowed,
// Why entry is unavailable, so a refusal can be explained rather than
// guessed at.
entryBlockedReason:
entryAllowed || active
? null
: !gateOpen
? this._contextModeChanging
? 'contacts-starting'
: 'contacts-inactive'
: 'no-tracked-aircraft',
visionMode: this.cockpitView?.visionMode || null,
subject: info
? {
id: info.icao24 || info.id || null,
layerId: info.layerId || null,
callsign: info.callsign || null,
}
: null,
navigation: snapshot
? {
canPrevious: Boolean(snapshot.navigation?.canPrevious),
canNext: Boolean(snapshot.navigation?.canNext),
canFocus: Boolean(snapshot.navigation?.canFocus),
}
: null,
awareness: snapshot
? {
radiusM: Number.isFinite(snapshot.radiusM)
? snapshot.radiusM
: null,
subject: snapshot.subject
? {
id: snapshot.subject.id || null,
layerId: snapshot.subject.layerId || null,
}
: null,
cohorts: Array.isArray(snapshot.cohorts)
? snapshot.cohorts.map((cohort) => ({
id: cohort?.id || null,
source: cohort?.source || null,
count: Number.isFinite(cohort?.count) ? cohort.count : null,
relationship: cohort?.relationship || null,
reason: cohort?.reason || null,
coverage: cohort?.coverage || null,
}))
: [],
navigation: snapshot.navigation
? {
canPrevious: Boolean(snapshot.navigation.canPrevious),
canNext: Boolean(snapshot.navigation.canNext),
canFocus: Boolean(snapshot.navigation.canFocus),
}
: null,
}
: null,
activeTracked: this.cockpitView?.active
? Boolean(this.cockpitView?.trackedEntity)
: false,
activeMapView: !this.cockpitView?.active && entryAllowed,
};
}
_retargetCockpitEntryLayer({
targetLayer,
aircraftClass,
currentTarget,
selectedTarget,
}) {
const { militaryAwarenessLayer } = this.services;
if (!['flights', 'military'].includes(targetLayer)) {
return {
ok: false,
error: `Cockpit flies aircraft only — ${targetLayer} contacts cannot be entered`,
};
}
const activeLayer =
selectedTarget?.layerId || currentTarget?.layerId || null;
const alreadyOnLayer = activeLayer === targetLayer;
if (alreadyOnLayer && !aircraftClass)
return { ok: true, retargeted: false };
const moved = militaryAwarenessLayer?.navigateNext
? !!militaryAwarenessLayer.navigateNext({
targetLayer,
aircraftClass,
origin: 'voice',
})
: false;
if (moved) return { ok: true, retargeted: true };
// A filter that matched nothing still enters, as long as the layer is
// already right — the operator asked for that layer and is on it.
if (alreadyOnLayer) return { ok: true, retargeted: false };
const label = targetLayer === 'military' ? 'military' : 'civilian';
const filtered = aircraftClass ? `${aircraftClass} ` : '';
return {
ok: false,
error: `No ${filtered}${label} contact is available to enter — track one first, or say "next ${label}"`,
};
}
controlCockpit(
action,
{
notificationToken = null,
targetLayer = null,
aircraftClass = null,
selectedTarget = null,
rollbackTarget = undefined,
} = {},
) {
const { flightsLayer, militaryFlightsLayer } = this.services;
const normalized = String(action || '').toLowerCase();
if (!this.cockpitView) {
return {
ok: false,
action: 'control_cockpit',
error: 'Cockpit controller unavailable',
state: this.getCockpitState(),
};
}
if (normalized === 'status') {
return {
ok: true,
action: 'control_cockpit',
state: this.getCockpitState(),
notificationToken: notificationToken || null,
};
}
if (normalized === 'enter') {
// Entry is gated exactly as the manual entry chip is. Attempting it while
// the gate is shut produced the half-entered look the operator reported
// (a plane anchored under the camera with no cockpit around it), so
// refuse with the reason instead of trying.
if (!this.cockpitView.isEntryAllowed?.()) {
return {
ok: false,
action: 'control_cockpit',
error: this._contextModeChanging
? 'Contacts is still starting up — try Cockpit again in a moment'
: 'Contacts must be active to enter Cockpit — say "open contacts" first',
state: this.getCockpitState(),
};
}
let currentTarget = this.getAircraftTrackingTarget();
const layerForTarget = (target) =>
target?.layerId === 'military'
? militaryFlightsLayer
: target?.layerId === 'flights'
? flightsLayer
: null;
// A requested layer retargets BEFORE entry, through the same filtered
// navigation NEXT uses. Ignoring it entered on whatever was already
// tracked and reported success, so "cockpit in that military helicopter"
// silently put the operator in an airliner.
if (targetLayer) {
const requested = this._retargetCockpitEntryLayer({
targetLayer,
aircraftClass,
currentTarget,
selectedTarget,
});
if (!requested.ok) {
return {
ok: false,
action: 'control_cockpit',
error: requested.error,
state: this.getCockpitState(),
};
}
if (requested.retargeted) {
// The retarget is now the authority; a selection sampled before it
// would drag entry back to the wrong layer.
selectedTarget = null;
rollbackTarget =
rollbackTarget === undefined ? currentTarget : rollbackTarget;
currentTarget = this.getAircraftTrackingTarget();
}
}
const selectedLayer =
selectedTarget?.layerId === 'military'
? militaryFlightsLayer
: selectedTarget?.layerId === 'flights'
? flightsLayer
: null;
const entry = enterCockpitWithTracking({
cockpitView: this.cockpitView,
selectedLayer,
selectedTarget,
currentLayer: layerForTarget(currentTarget),
rollbackLayer: layerForTarget(
rollbackTarget === undefined ? currentTarget : rollbackTarget,
),
rollbackTarget,
selectionOrigin: 'voice',
});
return {
ok: entry.entered,
action: 'control_cockpit',
state: this.getCockpitState(),
error: entry.error,
};
}
if (normalized === 'exit') {
const exited = !!this.cockpitView.exit();
return {
ok: exited,
action: 'control_cockpit',
state: this.getCockpitState(),
error: exited ? null : 'Cockpit was already inactive',
};
}
if (normalized === 'next' || normalized === 'previous') {
const changed = this.cockpitView.navigateContext(
normalized === 'next' ? 1 : -1,
{
targetLayer,
aircraftClass,
origin: 'voice',
},
);
return {
ok: changed,
action: 'control_cockpit',
state: this.getCockpitState(),
error: changed ? null : 'No further context target was available',
};
}
return {
ok: false,
action: 'control_cockpit',
error: `Unknown cockpit action: ${action}`,
state: this.getCockpitState(),
};
}
_initCockpitDisplayPortal() {
this._cockpitDisplayPortal?.destroy();
this._cockpitDisplayPortal = new CockpitDisplayPortal({
standardPanel: this._ppToggles,
cockpitPanel: this._cockpitDisplayPanel,
groups: [
['hud', this._hudBtn?.closest('.pp-toggle-group')],
['detection', this._detectionBtn?.closest('.pp-toggle-group')],
['parameters', this._sliderPanel],
['models3d', this._models3dBtn?.closest('.pp-toggle-group')],
],
layout: () => {
this._layoutRightPanels();
this.cockpitView?.scheduleContextLayout();
},
});
}
_setCockpitDisplayPortalActive(active) {
this._cockpitDisplayPortal?.setActive(active);
}
get _cockpitDisplayPortalActive() {
return this._cockpitDisplayPortal?.active ?? false;
}
get _displayPortalScrollRestoreOwner() {
return this._cockpitDisplayPortal?.restoreOwner ?? null;
}
get _standardDisplayScrollTop() {
return this._cockpitDisplayPortal?.standardScrollTop ?? 0;
}
stop() {
this.cockpitView?.stop();
this._cockpitDisplayPortal?.stop();
}
destroy() {
this.cockpitView?.dispose();
this._cockpitDisplayPortal?.destroy();
this._cockpitDisplayPortal = null;
}
}
Loaded 100 of 128 files, more files were not shown because too many files have changed in this diff. Show more