diff --git a/.env.example b/.env.example index 8b3b5f8316..a9819f100b 100644 --- a/.env.example +++ b/.env.example @@ -176,7 +176,7 @@ VITE_AIS_LIVE_LABEL_MAX_ROWS=900 AISSTREAM_API_KEY= # Optional AISStream subscription filters. # AISSTREAM_BOUNDING_BOXES=[[[-90,-180],[90,180]]] -# AISSTREAM_MESSAGE_TYPES=PositionReport,StandardClassBPositionReport,ExtendedClassBPositionReport,ShipStaticData,StaticDataReport +# AISSTREAM_MESSAGE_TYPES=PositionReport,StandardClassBPositionReport,ExtendedClassBPositionReport,ShipStaticData,StaticDataReport,AidsToNavigationReport # Feed watchdog: silence (ms) after which the feed is REPORTED stale; the socket # is recycled at 2.5x that. Default 120000. The watchdog self-arms only for the # default worldwide subscription — a narrow filter above can be legitimately @@ -280,6 +280,11 @@ AISSTREAM_API_KEY= # CCTV_PREFER_AUSTIN=1 # prioritize Austin cameras in the registry # CCTV_FORCE_AUSTIN= # force live default sources when a source-pack JSON is configured +# Optional: Data Library (DATA LAYERS ▸ Browse data library). Every entry is +# fetched live from its provider; nothing is hosted here. See docs/DATA-LIBRARY.md. +# GEV_LIBRARY_ENABLE= # comma-separated ids of operator opt-in entries to serve (packs use their host's own switch, e.g. CCTV_NYC_ENABLED) +# GEV_LIBRARY_DISABLE= # comma-separated ids to remove from this instance entirely + # Optional: comma-separated Overpass URLs; use only instances you run or pay for. # Also enables voice place search (osm_query, "hospitals in Kathmandu"). OVERPASS_UPSTREAMS= @@ -325,3 +330,38 @@ GEMINI_CHAT_MODEL=gemini-3.5-flash-lite # Each reserves up to 40 stations within the existing 750-station directory. # Restart after changing. Leave blank for the existing global selection. # RADIO_PRIORITY_COUNTRIES=IN,PL + +# Optional: a news server for the News layer (its /api/news/hotspots, /feed +# and /outline routes), such as https://news.example. The local server +# forwards only the layer's own GET requests there, with a 15 s timeout. Set, +# it wins over the settings below. SERVER-SIDE ONLY. +# GEV_NEWS_ORIGIN= +# +# Without a news server Core reads the News layer itself. SERVER-SIDE ONLY. +# Conflicts need no key: the last 24 h of GDELT events (its 15-minute export +# files, about 100 KB each, about 10 MB a day; violence only, one report per +# story at GDELT's place for it), titled from GDELT's GKG files (about 6 MB +# each, about 23 MB an hour: the newest 3 h are read at start, then each new +# one). Optional: Liveuamap's mapped reports beside them (paid API, +# https://liveuamap.com/promo/api), read once every 5 minutes. +# LIVEUAMAP_API_KEY= +# Local: the day's news from the outlets of the country in view (free plan +# of 50 points a day, https://worldnewsapi.com/console/), read once per +# country every 30 minutes, about 1.5 points a read. Without it Local says +# "key required". Each country's news is kept in memory for at most 1 hour. +# World News API's terms (https://worldnewsapi.com/terms/) allow caching +# only with its prior written permission: get that before setting the key. +# The app's Data attribution popover credits World News API with a link. +# WORLDNEWSAPI_KEY= +# The most World News API reads a day (default 30, about 45 points, inside +# the free plan). After that Local says the daily limit is reached. +# Raise it on a paid plan. +# WORLDNEWSAPI_DAILY_READS=30 + +# Rail layer: every feed is keyless, so nothing needs setting. Packs are an +# opt-in extra for live trains (the operator's lines, stop names, next stops): +# scripts/build-rail-paths.mjs (--feed ... or --all) writes path and +# schedule packs, and the server reads them from this directory +# (default .cache/rail-paths). The build reads it from its own environment, +# not from this file: export it, or pass the same folder as --out. +# RAIL_PATHS_DIR= diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 63d1eb29b9..412bf5da86 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -53,6 +53,10 @@ jobs: if: github.event_name == 'pull_request' run: npm run layer-token:check -- --base-ref origin/main + - name: Check Data Library manifests and share tokens + if: github.event_name == 'pull_request' + run: npm run library:check -- --base-ref origin/main + - name: Run unit tests run: npm test @@ -102,6 +106,16 @@ jobs: - name: Street Level gate with Mapillary fixtures run: npm run qa:street-level:fixtures -- --strict --url http://localhost:4173 + - name: The whole application on the stub renderer, with no Cesium loaded + run: | + mkdir -p qa-artifacts + npm run qa:stub-boot -- --json qa-artifacts/stub-boot.json + + - name: The renderer contract's logic checks on Cesium, headless + run: | + mkdir -p qa-artifacts + npm run qa:conformance -- --json qa-artifacts/conformance.json + - name: Preview server log if: failure() run: cat preview.log diff --git a/.github/workflows/discord-merged-pr.yml b/.github/workflows/discord-merged-pr.yml new file mode 100644 index 0000000000..5f927d8930 --- /dev/null +++ b/.github/workflows/discord-merged-pr.yml @@ -0,0 +1,40 @@ +name: Announce merged PRs in Discord + +on: + pull_request_target: + types: [closed] + +permissions: {} + +jobs: + announce: + if: github.repository == 'bilawalsidhu/gods-eye-view' && github.event.pull_request.merged == true + runs-on: ubuntu-latest + timeout-minutes: 2 + steps: + # This uses the trusted base workflow and never checks out or runs PR code. + - name: Post to Discord contributions + shell: bash + env: + DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_CONTRIBUTIONS_WEBHOOK_URL }} + run: | + if [[ ! "$DISCORD_WEBHOOK_URL" =~ ^https://discord\.com/api/webhooks/[0-9]+/[A-Za-z0-9_-]+$ ]]; then + echo '::error::Set DISCORD_CONTRIBUTIONS_WEBHOOK_URL to the Discord channel webhook URL.' + exit 1 + fi + + payload=$(jq -ce ' + .pull_request | { + allowed_mentions: {parse: []}, + embeds: [{ + title: ("Merged #" + (.number | tostring) + ": " + (.title | .[0:115])), + url: .html_url, + footer: {text: ("By " + .user.login + " · into " + (.base.ref | .[0:100]))} + }] + } + ' "$GITHUB_EVENT_PATH") + + curl --silent --show-error --fail --output /dev/null \ + --connect-timeout 10 --max-time 20 --retry 3 --retry-max-time 50 \ + --header 'Content-Type: application/json' --data-binary "$payload" \ + --url "$DISCORD_WEBHOOK_URL?wait=true" diff --git a/.gitignore b/.gitignore index 11e081e7d8..2d63faed07 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,8 @@ qa-shots/ output/ .gev-logs/ .gev-cache/ +# Local build output, e.g. rail path packs (scripts/build-rail-paths.mjs). +.cache/ # Browser QA gate evidence (screenshots, console and network dumps). qa-artifacts/ # Playwright MCP session logs: browser consoles can carry tokens in URLs. diff --git a/.prettierignore b/.prettierignore index 2b2cc755a1..9e1a01ef80 100644 --- a/.prettierignore +++ b/.prettierignore @@ -9,6 +9,8 @@ coverage pinokio/ENVIRONMENT pinokio/.installed src/data/local_data/ +# Written by scripts/record-camera-goldens.mjs and compared byte for byte. +src/render/conformance/goldens/ *.geojson *.geojsonl diff --git a/CHANGELOG.md b/CHANGELOG.md index f49dad02be..995beef5e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,120 @@ ## [Unreleased] +- A double-click on the map no longer follows or zooms to what is under + it. The globe's own double-click did that for some layers' markers and + shapes (earthquakes, cyclones, air quality, news, cables, places and + others); following something is a click, as for aircraft and ships. The + Cockpit's double-click and a drawing's finishing double-click are + unchanged (samehkhamis). +- Aircraft no longer jump ahead or back, and their trails no longer kink, + when the feed is late. The civil and military layers draw as far behind + real time as their feed is late (the 90th percentile of recent report + lags plus 5 s, at least 30 s civil and 15 s military, at most five + minutes), so an aircraft is placed between two real reports rather than + dead reckoned past them; the delay changes slowly, and the icons, the + renderer's live clock, labels, the HUD, detection, the tracked camera and + the trail all read the same one. Between two reports an aircraft flies + one smooth curve that leaves each report along its track, sent to the + renderer as `arc` segments; its trail is its reports joined along that + same curve, so the icon always sits on it. A late report a coasting + aircraft missed is eased onto, at most 30% faster than it flies; past + its newest report an aircraft coasts straight on (samehkhamis). +- The Display panel has a Sky group on a renderer with a sky to set: the + atmosphere, day and night (sun lighting by scene time), the sun, the + moon, the stars and the Milky Way's brightness. The choice is kept for the + next visit; what is not set stays as the renderer draws it (samehkhamis). +- The renderer contract no longer ties a renderer's look to the default + renderer's: `globe.sky` switches parts of the sky on and off, while how + the sky, atmosphere, haze, lighting, tone mapping and exposure look is + the renderer's own. `globe.weather`'s `clouds` is the fraction of the sky + covered, as observed; clouds are placed by scene time and the wind and + shade the ground under them where the sun lights it. New conformance + check `globe.weather.sceneTime` (samehkhamis). +- Selecting an aircraft, a vessel, a train or a transit vehicle no longer + makes it bigger: it keeps the size and form it had and changes colour (a + transit vehicle only widens its dark ring). A click on an aircraft, a + vessel or a train no longer moves the camera to a new framing either: the + camera keeps its distance and viewing angle, the contact slides to the + centre over one second, and the camera then follows it from there (a + vessel, which is never followed, is left centred). A + follow target asks for this glide with `transitionS` (renderer contract, + conformance check `camera.follow.transition`); without it a follow frames + at once, as before. An aircraft chosen by voice, search or a shared link + is still framed as before (samehkhamis). +- The renderer contract's `models` capability draws the procedural fleet + models: a model item can carry its glTF bytes (`gltf`, drawn without a + fetch), a per-axis stretch (`axisScale`), a colour for its tinted parts + (`maskColor`) and a cut below its origin (`clip: 'belowOrigin'`, a hull at + the waterline). Aircraft, military, local ADS-B, vessel, transit and rail + models are drawn through it (samehkhamis). +- A tracked aircraft's trail no longer draws a straight line from its track + history across a landing or take-off that was not seen: a parked or + taxiing aircraft whose history ends in the air (often its previous flight) + starts its trail on the ground (samehkhamis). +- Aircraft from adsb.lol that report no ground track (parked or taxiing + slowly) now face their reported true heading instead of north, so parked + models line up with their gates (samehkhamis). +- A renderer can draw weather: the `weather` capability adds `globe.weather`, + with clouds, fog, haze, rain and snow (each 0 to 1) and the wind they drift + on. `./render/weather` and `./weather/effects` export the shared rules and + the strengths of a weather observation. The Cesium renderer does not draw + weather (samehkhamis). +- Groups of toggles, sliders and notes can be added to the Display panel + under Effects, with `publishDisplayGroup` from `./ui/display/groups` + (samehkhamis). +- The globe opens at planet level, the whole Earth in view, instead of + flying in to Austin. A shared link still flies from + there to its view. The `startView` option of `createApplicationControls` + starts it somewhere else, a city for instance (longitude, latitude and + height, and heading and pitch in degrees) (samehkhamis). - An application's own tool can take the pointer as Draw does, and its click handlers can yield while a tool holds it, as the layers' do (`pointer` from `createApplicationTools`) (samehkhamis, #1641). +- `gods-eye-view/annotations` no longer reaches Cesium: the world annotation + renderer draws its areas, building columns, routes, arrows, rings and + markers through the renderer's draw port (the Cesium renderer now drapes + arrows, draws clamped rings by camera height and pulses shape alpha), and + samples a building's ground through the height service. A click on a + world mark now hits its draw set (`meta: { annotation: id }`) rather than + an entity. A viewer with no renderer bound needs + `gods-eye-view/render/cesium/unbound` loaded once first (samehkhamis). +- `gods-eye-view/application/layers` and `gods-eye-view/standalone/catalog` + no longer reach Cesium: the weather shells and the wind layer's colour + shell and flow draw through the renderer's `draw.field` (`rasterShell` and + `windStreamlines`, which the Cesium renderer now draws), and the wind + relief is the globe port's `hillshade` surface shading. The flow animates + as before, and still falls back to the canvas where the renderer refuses + it. A viewer with no renderer bound needs + `gods-eye-view/render/cesium/unbound` loaded once first (samehkhamis). +- `gods-eye-view/input` no longer reaches Cesium: the dispatcher takes its + pointer events from the renderer's input port and its picks from the query + port. A click's `hit`, `topHit`, `drawHit` and `drill()` hits, and + `pickAt`'s result, are the renderer contract's `Hit`; positions are plain + `{ x, y }`; `HANDLER_EVENT_TYPES` is gone. Cesium's own picks stay on + `event.native` (and `event.pick` and `event.pickWindow`). A viewer with no + renderer bound needs `gods-eye-view/render/cesium/unbound` + loaded once first (samehkhamis). +- `gods-eye-view/application/operations` no longer reaches Cesium: ground + snapping and mesh floor sampling ask the renderer's globe, camera and query + ports, and see through the caller's draw sets by id (the raw + `excludeObjects` option and exclusion callbacks are gone). A viewer with no + renderer bound needs `gods-eye-view/render/cesium/unbound` + loaded once first, or location framing throws and snaps answer nothing + (samehkhamis). +- `gods-eye-view/layers/traffic` (and `gods-eye-view/application/sources`, + which reaches it) no longer reaches Cesium: the layer keys cached road + heights by the globe port's `surfaceVersion()` and waits on + `isSettled('surface')`. Heat-lines are always asked for draped; a renderer + that cannot drape draws them over the surface instead of the layer + dropping them. A viewer with no renderer bound needs + `gods-eye-view/render/cesium/unbound` loaded once first (samehkhamis). +- Where the Cesium renderer cannot drape (a WebGL context without depth + textures), every draped line now draws over the surface, as the renderer + contract asks: along the surface's curve between its positions, in its + colour where the surface hides it, hidden past the horizon. Segment colours + are dropped (it draws in its style colour) and it runs from its first shown + segment to its last (samehkhamis). ## [0.3.0] — 2026-10-27 — Street Level, On Your Phone, in Your Language @@ -788,7 +899,7 @@ - Stop one retired bikeshare feed from reporting the whole layer as failed. City feeds are fetched independently, but failure was recorded in a single - flag that only a successful *activation* cleared — and an already-loaded city + flag that only a successful _activation_ cleared — and an already-loaded city never activates again. A dead feed re-entering camera range therefore latched LOAD FAILED permanently over a map still drawing every other city's stations. Failure is now tracked per city: a city that fails beside others still @@ -1064,7 +1175,7 @@ photo a click opens, and the cones, by each photo's projection and upload date. KartaView's SINCE is the upload date (all its server can filter by); a note under the slider says so while KartaView is lit (`sinceBasis: - 'upload'` in the provider contract). +'upload'` in the provider contract). Mapillary's line coverage and sequence cones are now shared by both (`lineCoverage.js`, `sequenceCones.js`). @@ -1642,6 +1753,7 @@ Add feed provenance to analyst/view answers and HUD context while retaining existing response fields and runner ownership (Matt Van Horn, #347). Analyst records for loaded satellites, datacenters and dams, with explicit bounded count/rank coverage (Matt Van Horn, #351). + - New Fire Perimeters layer (Events group): live NIFC WFIGS interagency wildfire incident perimeters as ground-clamped polygons with a containment-colored fire line, refreshed every 5 minutes from the public @@ -1918,7 +2030,6 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md ### Other changes - - Add ECMWF IFS model selection to Wind (#464, thanks @beneduzi), with model-scoped forecast-step caches, cancellation of replaced requests, and separate issue/valid timestamps. - 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. @@ -2727,4 +2838,3 @@ represent previously published GitHub Releases. ## [0.1.0] — 2026-02-09 - Initial project version. - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 201763748a..438f9da14d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -129,6 +129,7 @@ prints anything; never fix that by renaming or deleting PR A's published token. The highest-leverage places to jump in: - **🌆 Add a CCTV source pack.** Austin is the reference camera source. Follow the [CCTV integration workflow](docs/CCTV_INTEGRATION.md) for source review, provider registration, proxy security, tests, and attribution. The proxy only fetches server-registered URLs — never client-supplied ones; see [SECURITY.md](SECURITY.md). +- **📚 Add a Data Library entry.** A regional or niche source that is not a core layer belongs in the Data Library: one JSON manifest pointing at a live API, provider-hosted file or tile endpoint, with its licence and attribution, and no JavaScript. See [docs/DATA-LIBRARY.md](docs/DATA-LIBRARY.md). Library entries use their own share-token ledger, not the layer tokens below. - **🛰️ Add or improve a data layer.** Layer factories live in `src/layers//`, with source, record, controller and renderer owners implementing the layer interface (`init/enable/disable/update/destroy/getStats`, optional `getDetectableObjects`/`getStats`). Use an existing layer as a template, and see [Adding a new layer](#adding-a-new-layer) for what the PR needs. - **🎙️ Extend voice control.** Voice arguments are defined in `src/voice/actionSchemas.js`, with server-side descriptions in `server/providers/openai/tools.js` and client-side execution in `src/voice/gevActions.js`. Keep the tool surface tight and the responses honest (confirm only what actually happened). - **🎨 Add a visual style.** Styles are GLSL post-process shaders in `src/styles/`. @@ -138,6 +139,7 @@ The highest-leverage places to jump in: - **Vue 3 + Pinia for the interface,** [CesiumJS](https://cesium.com/platform/cesiumjs/) for the globe and [Vite](https://vitejs.dev/) to build. See [Building UI](#building-ui). - **Assembly lives in `src/app/`; standalone defaults live in `src/standalone/`.** UI controllers live in `src/ui/`, layer factories in `src/layers/`, portable sources in `src/sources/`, and application operations in `src/services/`. Existing `src/data/.js` entries retain compatibility; new code belongs with its focused owner. +- **Reach the renderer through its contract** ([docs/RENDERER-CONTRACT.md](docs/RENDERER-CONTRACT.md#moving-code-onto-the-contract)): `findDraw`, `findCamera` and the other ports in `src/render/rendererOf.js`, not Cesium or the viewer's `scene`, `camera` or `entities`. Two ratchet tests hold this: only files on `src/render/cesiumAllowList.json` may import Cesium, and `src/render/viewerAccessAllowList.json` caps the viewer accesses each other file still makes. Neither list may grow; when you port code off them, shrink them (`node scripts/viewer-access-baseline.mjs` lowers the second). - Sources acquire records; renderers own Cesium resources. Import `gods-eye-view/layers//source` when only a source factory is needed. Common voice controls consume the session interface; protocol adapters own connection details. - **Secrets stay server-side.** Anything needing a private key goes through a local proxy under `server/providers/`. The browser only ever sees the Google Maps key (which you restrict) and ephemeral tokens. - `docs/CURRENT-STATE.md` is the authoritative runtime reference — read it first. @@ -228,7 +230,7 @@ ownership and adoption process. 1. Branch off `main`. 2. Keep `npm run build`, `npm test`, and `npm run test:track` green and avoid new console errors, plus the [feature gate](#feature-regression-gates) for the area you touched. 3. If you change runtime behavior, update `docs/CURRENT-STATE.md` in the same PR, and add your changelog entry as `changelog.d/-.md` instead of editing `CHANGELOG.md` — see [changelog.d/README.md](changelog.d/README.md). Distinct filenames don't conflict; a release assembles the directory into `CHANGELOG.md`. A documentation claim that needs a regression test should assert against `docs/CURRENT-STATE.md` or `README.md`, which a PR still edits directly. -4. If you add or change a data source, update [DATA_SOURCES.md](DATA_SOURCES.md) with its license and attribution. **Don't add data you don't have the right to redistribute** — fetch it at runtime instead. +4. If you add or change a data source, update [DATA_SOURCES.md](DATA_SOURCES.md) with its license and attribution (for a Data Library entry, `npm run library:docs` writes its row). **Don't add data you don't have the right to redistribute** — fetch it at runtime instead. 5. Describe what you changed and how you verified it (screenshots welcome for anything visual). 6. If you add a new layer, fill in the new-layer section of the PR template. See [Adding a new layer](#adding-a-new-layer). diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md index 03a37ee5af..8049a412bc 100644 --- a/DATA_SOURCES.md +++ b/DATA_SOURCES.md @@ -1,13 +1,13 @@ # Data Sources & Attribution -God's Eye View's **code** is [MIT](LICENSE)-licensed. **The MIT grant covers the source code only — it does NOT extend to third-party data or visual assets.** Every third-party source keeps its own license and terms. This file documents the live and bundled data sources; bundled 3D-model provenance is recorded in [`public/models/README.md`](public/models/README.md). +God's Eye View's **code** is [MIT](LICENSE)-licensed. **The MIT grant covers the source code only — it does NOT extend to third-party data or visual assets.** Every third-party source keeps its own license and terms. This file documents the live and bundled data sources. The bundled 3D models are the project's own procedural fleet models, MIT-licensed with the code ([`public/models/README.md`](public/models/README.md)). How to read this: - **The non-permissive datasets are carved out, not omitted.** Some bundled data (e.g. TeleGeography, CC BY-NC-SA) isn't MIT-compatible. Rather than hide it, we **bundle it with a clear license carve-out** so the app works out of the box — but it stays under the provider's terms. - **If your use doesn't fit a dataset's license, remove that dataset.** Most importantly: TeleGeography is **NonCommercial** — commercial users must delete it (or license it from TeleGeography). It's one self-contained folder. - **Attribution is shown in-app** and listed here. Keep it intact. The required Google/Cesium credit renders on the on-globe credit line (bottom-left, `#cesium-credits`), and every per-layer credit below is registered into the expandable **"Data attribution"** lightbox on that line (`src/data/dataCredits.js` → `viewer.creditDisplay.addStaticCredit`). Both stay visible in clean-view and recording modes. -- **Bundled model attribution lives beside the model files.** [`public/models/README.md`](public/models/README.md) records each shipped model's creator, source, license, and modification status. +- **The bundled 3D models are the project's own.** Every model under `public/models/` is a procedural fleet model generated by the project maintainers and covered by the repository's MIT license; [`public/models/README.md`](public/models/README.md) describes the set. --- @@ -30,7 +30,8 @@ How to read this: | **adsb.lol point API** | Bounded live-flight fallback when OpenSky has no usable snapshot; GNSS Integrity layer (aircraft-reported NIC/NACp and GPS-loss integrity facts, via `/api/gnss-integrity`, 60 s server cache) | ODbL 1.0 | adsb.lol contributors; `api.adsb.lol/v2/lat/{lat}/lon/{lon}/dist/{radius}` | | **adsb.lol** | Military flights + aircraft traces | ODbL 1.0 | "adsb.lol" (ODbL) | | **adsbdb** (`api.adsbdb.com`) | Aircraft type, model name and registration by ICAO hex for enriched flights; airline and origin/destination airports for the tracked flight's callsign | No licence or rate limit is published for the service. Its own credits: aircraft data from PlaneBase, ICAO-to-N-number conversion by Guillaume Michel, and flight route data that "is the work of David Taylor, Edinburgh and Jim Mason, Glasgow, and may not be copied, published, or incorporated into other databases without the explicit permission of David J Taylor, Edinburgh" | "adsbdb — api.adsbdb.com" (courtesy); route data credited to David Taylor, Edinburgh, and Jim Mason, Glasgow | -| **Planespotters.net** (`api.planespotters.net/pub/photos/hex/{hex}`) | One thumbnail photo of the tracked aircraft, by ICAO hex, in the CONTEXT panel's CONTACTS view under the tracked flight's name | [Planespotters photo API terms](https://www.planespotters.net/photo/api); each photo remains the copyright of its photographer. Thumbnails may be hotlinked on the condition that the photographer is named next to the photo and the photo links to its Planespotters page with a followable link | "Photo © {photographer}" beside every photo, linked to its Planespotters page; "Planespotters.net" in Data attribution | +| **Planespotters.net** (`api.planespotters.net/pub/photos/hex/{hex}`) | One thumbnail photo of the tracked aircraft, by ICAO hex, in the CONTEXT panel's CONTACTS view under the tracked flight's name | [Planespotters photo API terms](https://www.planespotters.net/photo/api); each photo remains the copyright of its photographer. Thumbnails may be hotlinked on the condition that the photographer is named next to the photo and the photo links to its Planespotters page with a followable link | "Photo © {photographer}" beside every photo that names one, linked to its Planespotters page; "Planespotters.net" in Data attribution | +| **Open Vessel Photos** (`openvesselphotos.org/v1/mmsi/{mmsi}`) | One photo of the selected vessel, by MMSI, in the CONTEXT panel's CONTACTS view under the vessel's name and MMSI | Free, keyless public API ([README](https://github.com/louptheron/openvesselphotos)); each photo keeps the open licence its author chose (CC BY, CC BY-SA, CC0, or public domain), given with it in the API | "Photo: {photographer} · {licence}" beside every photo, linked to the vessel's Open Vessel Photos page; "Open Vessel Photos" in Data attribution | | **AISStream.io** | Live vessels (AIS) | Free, beta, no formal ToS; AIS is a public broadcast | "AISStream.io" (courtesy) | | **CelesTrak** | Satellite TLEs (SGP4) and SATCAT records (object type, operational status, owner) that file each satellite under a class | US-government-origin data, no license; citation requested | "CelesTrak (celestrak.org), Dr. T.S. Kelso" | | **The Space Devs — Launch Library 2 v2.3** | Recent launch, payload, stage, and recovery metadata for Space Missions (30d) | [The Space Devs terms of use](https://github.com/TheSpaceDevs/Tutorials/blob/main/faqs/faq_TSD.md#terms-of-use): data may be used and shared in any form; avoid forwarding it without added value; attribution is encouraged (not mandatory). [Official API limits](https://ll.thespacedevs.com/docs/): 15 unauthenticated calls/hour; optional token | "Launch Library 2 — The Space Devs" (courtesy attribution) | @@ -40,6 +41,12 @@ How to read this: | **NASA GIBS** (WMTS tiles + Worldview Snapshots) and **NASA CMR** (granule catalog) | Recent Imagery layer: HLS S30/L30 (Sentinel-2, Landsat 8/9) and VIIRS true-colour tiles draped on the map, per-day thumbnails and PNG exports; the HLS granule catalog (dates, cloud, footprints) for a selected box | U.S. public domain (NASA data); keyless, browser-direct (CORS `*`); no bulk use — one 30-day catalog query per box, tiles bounded to the box, six tile requests in flight | "We acknowledge the use of imagery provided by services from NASA's Global Imagery Browse Services (GIBS), part of NASA's Earth Science Data and Information System (ESDIS)." — [gibs.earthdata.nasa.gov](https://gibs.earthdata.nasa.gov), [HLS](https://lpdaac.usgs.gov/products/hlss30v002/) | | **NIFC WFIGS** (Wildland Fire Interagency Geospatial Services, ArcGIS feature service) | Fire Perimeters layer: current interagency wildfire incident perimeters, containment, and incident facts | U.S. public domain (interagency wildland-fire data published through the [NIFC Open Data portal](https://data-nifc.opendata.arcgis.com/)); fetched keyless through `/api/fire-perimeters` (5-minute server cache) with `exceededTransferLimit` paging | "Wildfire perimeters: National Interagency Fire Center (WFIGS)" | | **S2 Underground GhostMaps** (`github.com/s2underground/GhostMaps`) | S2 GhostMaps layer: the current edition of S2's KMZ intel products (Common Intelligence Picture, 30-day kinetic pull, Border Crisis Map, Iran and Yemen products, newest incident drop). Keyless. `/api/ghostmaps` reads the branch head from git's ref advertisement every 15 s (`GHOSTMAPS_POLL_SECONDS`, minimum 5 s), lists the tree through the GitHub REST API only when the head changes (optional `GITHUB_TOKEN`), downloads files by commit-pinned raw URLs into `.gev-cache/ghostmaps/` and pushes new catalogs to browsers over server-sent events | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) (repository README: "S2 Underground © 2025 by S2A1"); non-commercial, attribution required; files are fetched at runtime, never stored in this repository | "S2 GhostMaps intel products: S2 Underground © by S2A1, CC BY-NC-SA 4.0" — shown in-app | +| **News server** (`GEV_NEWS_ORIGIN`, optional; none by default) | News layer, both sections: the last 24 h of reports from many publishers. Set, the local server forwards the layer's `/api/news/hotspots`, `/feed` and `/outline` GET requests to it and Core reads none of the three sources below. Which providers stand behind its feed is the news server's to state | Each report stays its publisher's: headlines and summaries link to the original article, and pictures are hotlinked from the publisher's site (no referrer), never stored | Per report: publisher name and article link on every card; picture cards name the picture's publisher. The Data attribution popover states that places, categories, severity and English headlines are derived automatically and can be wrong | +| **GDELT 2.0 events and GKG** (`data.gdeltproject.org/gdeltv2/`; no key; used only without a news server) | News layer, Conflicts: the last 24 h of GDELT's 15-minute event exports (`*.export.CSV.zip`, about 100 KB each), read server-side as they appear. Physical violence only (CAMEO roots 18–20); one report per story, copies of one agency story merged; placed at GDELT's location for it (a town the article's words name beats a bare country). Titled by the article's page title from the GKG export of the same quarter hour (`*.gkg.csv.zip`, about 6 MB each) for the newest 3 h, else by the words of the article's address. GDELT's actor coding is never shown. Categories, relevance and severity by bundled rules | [GDELT Terms of Use](https://www.gdeltproject.org/about.html#termsofuse): unrestricted academic, commercial and governmental use, with citation and a link to the GDELT Project. Coded events, page titles and article links only; linked articles keep their publishers' terms | "GDELT Project" with a link to gdeltproject.org in the Data attribution popover; "via GDELT Project", the publisher's domain and the article link on every card | +| **Liveuamap** (`a.liveuamap.com/api`, `LIVEUAMAP_API_KEY`, optional, paid; used only without a news server) | News layer, Conflicts, beside GDELT: Liveuamap's worldwide mapped items of the last 24 h (`a=mpts`), read server-side every 5 minutes; categories and severity are read from the headline by bundled rules | Liveuamap API terms of the operator's own subscription. Headlines, places and links only; item pictures and clips are hotlinked from Liveuamap, never stored | "Liveuamap" with a link in the Data attribution popover once its items show; "Liveuamap" and the item's Liveuamap link on every card | +| **World News API** (`api.worldnewsapi.com/search-news`, `WORLDNEWSAPI_KEY`, optional; used only without a news server) | News layer, Local: the last 24 h of news by the source country at the view centre (country from the bundled Natural Earth admin-0 pack; none in a disputed area), read server-side once per country every 30 minutes, about 1.5 points a read, kept in memory for at most 1 hour and then deleted (a read that fails is served from that copy only within the hour); at most `WORLDNEWSAPI_DAILY_READS` reads a day (default 30), after which Local says the daily limit is reached. Each story keeps World News API's own category (politics, business, else other) with no severity of its own; sport, entertainment, lifestyle and travel left out | [World News API terms](https://worldnewsapi.com/terms/) of the operator's own plan. The terms allow caching only with World News API's prior written permission, and then for at most 1 hour: getting that permission before setting the key is the operator's responsibility. Titles and links only; article text and summaries are not kept or shown; pictures are hotlinked from the publisher | The "World News API" link to worldnewsapi.com, always in the Data attribution popover (a credit; the terms require a backlink only of invited free plans); "via World News API", the publisher's domain and the article link on every card | +| **EMODnet Human Activities — Ship wrecks** (`ows.emodnet-humanactivities.eu/wfs`, layer `emodnet:heritageshipwrecks`) | Shipwrecks layer: about 7,000 wrecks in European waters (name, sinking year and text, vessel type, least depth and its quality, position accuracy, period, cargo, protected status). Keyless WFS GeoJSON, fetched by `/api/shipwrecks` once a day; rows sourced from wrecksite.eu are skipped, and free text that refers to a person by a title or role is dropped by a keyword filter (a bare name can still pass) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) (EMODnet catalogue record `e965088b-a265-4517-84df-c49b156af8a7`; data originator AND-International, compiled from SHOM, National Monuments Service, Historic England and the Oxford Roman Economy Project); fetched at runtime, not stored in this repository | "Shipwrecks (Europe): EMODnet Human Activities (data originator AND-International, …), CC BY 4.0" — shown in-app | +| **Wikidata — shipwrecks** (`query.wikidata.org/sparql`) | Shipwrecks layer: shipwreck items (Q852190) with a coordinate and at least one Wikipedia article, plus sinking events (Q906512, where the death toll lives): name, ship type, sinking date with its precision, deaths and survivors (counts only), description and article link. Keyless, fetched by `/api/shipwrecks` once a day | [CC0](https://creativecommons.org/publicdomain/zero/1.0/); fetched at runtime | "Shipwrecks (worldwide): Wikidata (CC0)" — shown in-app | | **InciWeb** (inciweb.wildfire.gov) | Per-incident "InciWeb ↗" card links to official incident pages (narratives, evacuation/closure notices) | U.S. government public incident information. Links are matched best-effort by incident name and state, with incident page origin and update times checked on selection. Same-origin `/api/fire-perimeters/inciweb` routes cache the catalog for 1 hour and publication metadata for 30 minutes; linked pages remain InciWeb content | "Incident information: InciWeb (inciweb.wildfire.gov)" | | **FAA Special Use Airspace** (`services6.arcgis.com` FeatureServer `Special_Use_Airspace`) | Prohibited & Restricted Airspace layer: US prohibited (P) and restricted (R) special-use airspace polygons (not the UAS Facility Map or UAS flight restrictions), altitude limits from the `*_VAL`/`*_UOM`/`*_CODE` fields, times of use, and controlling agency | U.S. public domain (FAA aeronautical data published through the [FAA AIS Open Data portal](https://adds-faa.opendata.arcgis.com/)); fetched keyless through `/api/drone-airspace` (1-hour server cache). Informational only — not a substitute for official UAS flight-planning tools | "Prohibited & restricted airspace: FAA Special Use Airspace" | | **iNaturalist API** (`api.inaturalist.org/v2/observations`, `/v1/grid/{z}/{x}/{y}.grid.json`) | Wildlife Sightings layer: verifiable wildlife observed within the last 48 h (whales 7 d), by observation time, in the current view, with taxon, observation time, quality grade and eligible photo | Per-record licences; observations default CC BY-NC. Photos CC0/BY/BY-SA/BY-NC/BY-NC-SA shown; ND and all-rights-reserved photos link-only. Keyless via `/api/inaturalist/observations` (5-min cache; global sample 10 min; stale ≤ 1 h; 60 requests/min and 8,000/day upstream caps). **NonCommercial content:** commercial redistributors must filter to CC0/BY/BY-SA or remove the layer. No AI training on this content | "Wildlife sightings: iNaturalist contributors (licences per record; photos credited on each card)" | @@ -92,7 +99,7 @@ How to read this: | **Metro Transit** (Metropolitan Council) | Transit layer live vehicles, Minneapolis–St Paul | Metro Transit / Metropolitan Council open realtime vehicle data, used for the live view; published for developer use and not against their use. | Attribution to Metro Transit / Metropolitan Council (courtesy text) | | **OVapi / Stichting OpenGeo** | Transit layer live vehicles, Netherlands | OVapi / Stichting OpenGeo open realtime vehicle data, used for the live view; published for developer use and not against their use. The client sends a User-Agent and conditional requests. | Attribution to OVapi / Stichting OpenGeo (courtesy text) | | **Entur** (api.entur.io) | Transit layer live vehicles, Norway | Entur open realtime vehicle data, used for the live view; published for developer use and not against their use. The client sends the `ET-Client-Name` identifying header. | Attribution to Entur (courtesy text) | -| **TransLink** (Queensland Government) | Transit layer live vehicles, South East Queensland | TransLink / Queensland Government open realtime vehicle data, used for the live view; published for developer use and not against their use. | Attribution to TransLink / Queensland Government (courtesy text) | +| **TransLink** (Queensland Government) | Transit layer live vehicles, South East Queensland and Cairns | TransLink / Queensland Government open realtime vehicle data, used for the live view; published for developer use and not against their use. | Attribution to Translink, Department of Transport and Main Roads (courtesy text) | | **HSL** (realtime.hsl.fi) | Transit layer live vehicles, Helsinki | HSL (Helsinki Region Transport) open realtime vehicle data, used for the live view; published for developer use and not against their use. | Attribution to HSL (Helsinki Region Transport) (courtesy text) | | **TTC** (bustime.ttc.ca) | Transit layer live vehicles, Toronto — surface vehicles (buses and streetcars) only | Toronto Transit Commission BusTime open realtime vehicle data, published through City of Toronto Open Data and used for the live view. The subway publishes no vehicle positions, so Lines 1/2/4 are absent rather than inferred. | Attribution to Toronto Transit Commission — City of Toronto Open Data, under the Open Government Licence – Toronto | | **MiWay** (miapp.ca) | Transit layer live vehicles, Mississauga ON | MiWay open realtime vehicle data, published by the City of Mississauga under its Open Data Terms of Use, used for the live view. The licence is revocable and asks that the Terms of Use link travel with the data. | Attribution to MiWay — City of Mississauga Open Data, linked to the Terms of Use | @@ -104,6 +111,36 @@ How to read this: | **YRT/Viva** (rtu.york.ca) | Transit layer live vehicles, York Region ON | York Region Transit realtime data, first-party York Region infrastructure under the YRT Open Data Licence v2.0, which permits commercial use and makes attribution optional. Viva route ids are named by colour from York Region’s published GTFS. | "Contains public transit Information made available under YRT’s Open Data Licence" — the licence’s own wording, given though not required | | **Burlington Transit** (opendata.burlington.ca) | Transit layer live vehicles, Burlington ON | Burlington Transit realtime data under the City of Burlington Open Data Terms of Use, which permit any lawful purpose. The terms are revocable and must travel with the data, so the credit links them. Route ids are internal keys and are joined to the City’s published GTFS. | Credit to the City of Burlington plus a link to its Open Data Terms of Use, which the licence requires | | **SMTR Rio de Janeiro** (dados.mobilidade.rio) | Transit layer live vehicles, Rio de Janeiro: municipal buses (SPPO) and the Mobi-Rio BRT, as two feeds | CC BY 4.0, stated on both data.rio catalog pages. Keyless GTFS-Realtime published by the Secretaria Municipal de Transportes, labelled beta, with a gateway limit of 5 requests a second and 60 a minute. Line names come from SMTR’s GTFS `routes.txt` (dados.mobilidade.rio/gtfs/schedule), under the same licence. | Attribution to SMTR / Prefeitura da Cidade do Rio de Janeiro under CC BY 4.0 | +| **Metro-North** (api-endpoint.mta.info, rrgtfsfeeds.s3.amazonaws.com) | Rail layer trains, New York, NY: Metro-North Railroad (MTA). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (api-endpoint.mta.info) add delays at its stops. | [MTA Data Feed Terms and Conditions](https://www.mta.info/developers/terms-and-conditions): "Developers must download and store the MTA data feed on a non-MTA server and redistribute the data to users from that server." This proxy is that server: browsers never contact MTA. The feed stamps every vehicle with the header time, so a fix is aged from the snapshot, not from the train. | "Trains (MTA): [MTA Data Feed Terms and Conditions](https://www.mta.info/developers/terms-and-conditions)" | +| **LIRR** (api-endpoint.mta.info, rrgtfsfeeds.s3.amazonaws.com) | Rail layer trains, New York, NY: Long Island Rail Road (MTA). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (api-endpoint.mta.info) add delays at its stops. | [MTA Data Feed Terms and Conditions](https://www.mta.info/developers/terms-and-conditions): "Developers must download and store the MTA data feed on a non-MTA server and redistribute the data to users from that server." The feed was seen frozen for two days on 2026-11-06; the layer ages trains by their own report time, so a frozen feed empties instead of showing old trains as live. | "Trains (MTA): [MTA Data Feed Terms and Conditions](https://www.mta.info/developers/terms-and-conditions)" | +| **MBTA rail** (cdn.mbta.com) | Rail layer trains, Boston, MA: Massachusetts Bay Transportation Authority. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (cdn.mbta.com) add delays at its stops. | [MassDOT Developers License Agreement](https://cdn.mbta.com/sites/default/files/2023-08/mbta-massdot-develop-license-agreement.pdf): "MassDOT ... hereby grants You (Licensee) non-exclusive, limited, and revocable rights to use, reproduce, and redistribute the Data. ... Clearly acknowledge MassDOT as the provider of the Data." The same feed the Transit layer polls; this layer keeps only Commuter Rail, rapid transit and light rail. | "Trains (MBTA / MassDOT): [MassDOT Developers License Agreement](https://cdn.mbta.com/sites/default/files/2023-08/mbta-massdot-develop-license-agreement.pdf)" | +| **SEPTA Regional Rail** (www3.septa.org, github.com) | Rail layer trains, Philadelphia, PA: Southeastern Pennsylvania Transportation Authority. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (www3.septa.org) add delays at its stops. | [SEPTA Trip Planning Data Agreement](https://www3.septa.org/developer/): "non-exclusive, limited and revocable right to use, reproduce and redistribute the Trip Planning Data". The agreement names the static data; SEPTA publishes the realtime feeds on the same developer page with no separate terms. Credit is text only: SEPTA trademarks may not be used. | "Trains (SEPTA): [SEPTA Trip Planning Data Agreement](https://www3.septa.org/developer/)" | +| **SEPTA trolleys** (www3.septa.org, github.com) | Rail layer trains, Philadelphia, PA: Southeastern Pennsylvania Transportation Authority. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (www3.septa.org) add delays at its stops. | [SEPTA Trip Planning Data Agreement](https://www3.septa.org/developer/): "non-exclusive, limited and revocable right to use, reproduce and redistribute the Trip Planning Data". The bus feed, filtered to the trolley routes and the Norristown High Speed Line. The Market-Frankford and Broad Street lines are in no SEPTA feed. Routes T1–T5, G1, D1 and D2 (trams) and M1, the Norristown High Speed Line (metro). | "Trains (SEPTA): [SEPTA Trip Planning Data Agreement](https://www3.septa.org/developer/)" | +| **MARC** (mdotmta-gtfs-rt.s3.amazonaws.com, feeds.mta.maryland.gov) | Rail layer trains, Baltimore–Washington: Maryland Transit Administration. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (mdotmta-gtfs-rt.s3.amazonaws.com) add delays at its stops. | [MDOT MTA developer feeds (no endorsement implied)](https://www.mta.maryland.gov/developer-resources): "MTA does not guarantee the accuracy of the data nor does it warrant or endorse any application that uses this data." Published for open fetch with this disclaimer and no licence; the site terms cover only the website and apps. Shown with attribution and the no-endorsement wording, and switched off if MDOT MTA publishes restrictive terms. | "Trains (Maryland Transit Administration): [MDOT MTA developer feeds (no endorsement implied)](https://www.mta.maryland.gov/developer-resources)" | +| **Tri-Rail** (gtfsr.tri-rail.com, gtfs.tri-rail.com) | Rail layer trains, South Florida: South Florida Regional Transportation Authority. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (gtfsr.tri-rail.com) add delays at its stops. | [No licence stated (open feed pages)](https://gtfsr.tri-rail.com/): "Download Realtime Feeds Below:". Used without a published licence (project owner decision, 2026-11-10). gtfsr.tri-rail.com (the page quoted above, read 2026-11-10) links the GTFS-RT trip updates, alerts and position updates with no terms, and the static GTFS (gtfs.tri-rail.com/gtfs.zip, publisher ETA Transit Systems) states none either; no SFRTA data terms were found. The realtime vehicles carry the train number as their trip id and no route. | "Trains (South Florida Regional Transportation Authority (Tri-Rail)): [No licence stated (open feed pages)](https://gtfsr.tri-rail.com/)" | +| **RTD** (open-data.rtd-denver.com, www.rtd-denver.com) | Rail layer trains, Denver, CO: Regional Transportation District. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (open-data.rtd-denver.com) add delays at its stops. | [RTD GTFS-Realtime License Agreement](https://www.rtd-denver.com/business-center/open-spatial-data/gtfs-realtime-license-agreement): "non-exclusive, limited and revocable rights to use, reproduce, and redistribute the Data". RTD marks may not be used with the data, so the credit is text only. The published `www` URL redirects off its own origin, which the proxy refuses, so the final host is the one registered. | "Trains (RTD): [RTD GTFS-Realtime License Agreement](https://www.rtd-denver.com/business-center/open-spatial-data/gtfs-realtime-license-agreement)" | +| **CapMetro MetroRail** (data.texas.gov) | Rail layer trains, Austin, TX: Capital Metropolitan Transportation Authority. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. | [CapMetro Open Data Terms](https://www.capmetro.org/metrolabs/): "non-exclusive, limited and revocable rights to use, reproduce, and redistribute CMTA Data". The bus feed the Transit layer polls; MetroRail is route 550. | "Trains (CapMetro): [CapMetro Open Data Terms](https://www.capmetro.org/metrolabs/)" | +| **METRO light rail** (svc.metrotransit.org) | Rail layer trains, Minneapolis–St Paul, MN: Metro Transit (Metropolitan Council). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. | [No licence published](https://svc.metrotransit.org/). Publishes no licence or terms: the data feeds page linked above (read 2026-11-10) lists the GTFS and GTFS-realtime files and shows only "© 2020 Metro Transit", so there is nothing to quote. Used without a published licence, on the same basis as the Transit layer's Metro Transit feed, which polls the same file (DATA_SOURCES.md). Blue Line 901 and Green Line 902 only; Northstar ended on 2026-01-04 and route 888 is now a bus. | "Trains (Metro Transit / Metropolitan Council): [No licence published](https://svc.metrotransit.org/)" | +| **LYNX** (gtfsrealtime.ridetransit.org) | Rail layer trains, Charlotte, NC: Charlotte Area Transit System. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (gtfsrealtime.ridetransit.org) add delays at its stops. | [No licence published](https://www.charlottenc.gov/cats). Publishes no terms; used without a published licence (project owner decision, 2026-11-10). The feed host (gtfsrealtime.ridetransit.org) serves the files with no page and no terms, so there is nothing to quote (2026-11-10: 126 vehicles, 13 of them trains; 205 trip updates, 11 on the two lines; every realtime trip id is a static trip id). No CATS page with terms for them was found: charlottenc.gov answered 403 to automated requests, and the CATS Terms and Conditions found there by search govern the CATS mobile app. Routes 501 LYNX Blue Line (light rail) and 510 CityLYNX Gold Line (streetcar), both route_type 0: transit, tram. | "Trains (Charlotte Area Transit System): [No licence published](https://www.charlottenc.gov/cats)" | +| **GRT ION** (webapps.regionofwaterloo.ca) | Rail layer trains, Waterloo Region, ON: Grand River Transit (Region of Waterloo). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. | [Region of Waterloo Open Data Licence v2.0](https://www.regionofwaterloo.ca/government-and-council/transparency-and-accountability/open-data/): "You are free to: Copy, publish, distribute and transmit the Information ... Use the Information commercially". The registered URL is the `/2` light-rail feed; the suffix-less URL serves a file frozen since February 2026 and is not used. | "Trains (Contains information licensed under the Open Data Licence – Region of Waterloo): [Region of Waterloo Open Data Licence v2.0](https://www.regionofwaterloo.ca/government-and-council/transparency-and-accountability/open-data/)" | +| **Queensland Rail Citytrain** (gtfsrt.api.translink.com.au) | Rail layer trains, South East Queensland, Australia: Translink (Queensland Government). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (gtfsrt.api.translink.com.au) add delays at its stops. | [CC BY 4.0](https://translink.com.au/about-translink/open-data): "Our data is licensed under a Creative Commons Attribution 4.0 International License." The terms add: "You must not represent that the State in any way endorses your Application." | "Trains (Translink / Queensland Government): [CC BY 4.0](https://translink.com.au/about-translink/open-data)" | +| **G:link** (gtfsrt.api.translink.com.au) | Rail layer trains, Gold Coast, Australia: Translink (Queensland Government). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (gtfsrt.api.translink.com.au) add delays at its stops. | [CC BY 4.0](https://translink.com.au/about-translink/open-data): "Our data is licensed under a Creative Commons Attribution 4.0 International License." | "Trains (Translink / Queensland Government): [CC BY 4.0](https://translink.com.au/about-translink/open-data)" | +| **Adelaide Metro** (gtfs.adelaidemetro.com.au) | Rail layer trains, Adelaide, Australia: Adelaide Metro (Rail Commissioner). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (gtfs.adelaidemetro.com.au) add delays at its stops. | [CC BY 4.0](https://data.sa.gov.au/data/dataset/https-gtfs-adelaidemetro-com-au): "Creative Commons Attribution 4.0". Licence as catalogued on data.sa.gov.au; the operator developer page sits behind a bot check. The feed is labelled beta. Its gateway answers base64 text unless the request sends `Accept: application/x-google-protobuf`, so the proxy sends that header for this feed. | "Trains (Adelaide Metro / Government of South Australia): [CC BY 4.0](https://data.sa.gov.au/data/dataset/https-gtfs-adelaidemetro-com-au)" | +| **Irish Rail** (api.irishrail.ie, www.transportforireland.ie) | Rail layer trains, Ireland: Iarnród Éireann / Irish Rail. Placed at the station or timing point last reported, not by GPS. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, the delay each train's report states moves its stops. | [No licence published (positions); CC BY 4.0 (NTA timetable)](https://developer.nationaltransport.ie/usagepolicy). The train positions publish no licence or terms: the Irish Rail realtime API page (api.irishrail.ie/realtime/, read 2026-11-10) documents the calls and says only that "Irish Rail provides this information as is" (quoted under `limits`), so there is nothing to quote. They are used without a published licence, credited "Iarnród Éireann / Irish Rail". The NTA's CC BY 4.0 covers only the NTA's GTFS data (the timetable), not these positions. Positions are the station or timing point the signalling system last reported, not GPS. | "Trains (Iarnród Éireann / Irish Rail; timetable: National Transport Authority, provided as is): [No licence published (positions); CC BY 4.0 (NTA timetable)](https://developer.nationaltransport.ie/usagepolicy)" | +| **VR (Finland)** (rata.digitraffic.fi) | Rail layer trains, Finland: VR, via Fintraffic Digitraffic. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (rata.digitraffic.fi) add delays at its stops. | [CC BY 4.0](https://www.digitraffic.fi/en/terms-of-service/): "Fintraffic's open data is licensed under the Creative Commons 4.0 By license. It gives the right to distribute, remix, tweak, and build upon our data, even commercially, as long as you credit the source for the original creation." The Digitraffic-User header names the application, never a person. | "Trains (Source: Fintraffic / digitraffic.fi, license CC 4.0 BY): [CC BY 4.0](https://www.digitraffic.fi/en/terms-of-service/)" | +| **Renfe long and medium distance** (gtfsrt.renfe.com, ssl.renfe.com) | Rail layer trains, Spain: Renfe (AVE, Avlo, Alvia, Euromed, Intercity, Media Distancia). Live GPS positions. Its vehicles name no route, so it is listed only once its path and schedule packs are built from its static GTFS; trip updates (gtfsrt.renfe.com) then add delays at its stops. | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): "CC-BY-4.0". Licence field of the data.renfe.com datasets (posicion-vehiculos-av-ld-md and the static GTFS). "Esta información se actualiza cada 15 segundos". Iryo and OUIGO España are not in Renfe’s feeds. | "Trains (Renfe): [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)" | +| **Renfe Cercanías** (gtfsrt.renfe.com, ssl.renfe.com) | Rail layer trains, Spain: Renfe Cercanías and Rodalies. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (gtfsrt.renfe.com) add delays at its stops. | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): "CC-BY-4.0". Licence field of the data.renfe.com Cercanías datasets. Every vehicle in this feed is a Cercanías or Rodalies train. | "Trains (Renfe): [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)" | +| **Vy** (api.entur.io, storage.googleapis.com) | Rail layer trains, Norway: Vy (Norway), via Entur. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. | [NLOD 2.0](https://data.norge.no/nlod/en/2.0): "Entur's open data is published under the Norwegian Licence for Open Government Data (NLOD). NLOD permits free reuse for any purpose, including commercial use, subject to attribution requirements". | "Trains (Inneholder data under Norsk lisens for offentlige data (NLOD) tilgjengeliggjort av Entur AS): [NLOD 2.0](https://data.norge.no/nlod/en/2.0)" | +| **Go-Ahead** (api.entur.io, storage.googleapis.com) | Rail layer trains, Norway: Go-Ahead Norge, via Entur. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (api.entur.io) add delays at its stops. | [NLOD 2.0](https://data.norge.no/nlod/en/2.0): "Entur's open data is published under the Norwegian Licence for Open Government Data (NLOD). NLOD permits free reuse for any purpose, including commercial use, subject to attribution requirements". | "Trains (Inneholder data under Norsk lisens for offentlige data (NLOD) tilgjengeliggjort av Entur AS): [NLOD 2.0](https://data.norge.no/nlod/en/2.0)" | +| **Flytoget** (api.entur.io, storage.googleapis.com) | Rail layer trains, Norway: Flytoget, via Entur. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (api.entur.io) add delays at its stops. | [NLOD 2.0](https://data.norge.no/nlod/en/2.0): "Entur's open data is published under the Norwegian Licence for Open Government Data (NLOD). NLOD permits free reuse for any purpose, including commercial use, subject to attribution requirements". | "Trains (Inneholder data under Norsk lisens for offentlige data (NLOD) tilgjengeliggjort av Entur AS): [NLOD 2.0](https://data.norge.no/nlod/en/2.0)" | +| **SJ Nord** (api.entur.io, storage.googleapis.com) | Rail layer trains, Norway: SJ Nord, via Entur. Live GPS positions, read from SIRI VM. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, the delay each train's report states moves its stops. | [NLOD 2.0](https://data.norge.no/nlod/en/2.0): "Entur's open data is published under the Norwegian Licence for Open Government Data (NLOD). NLOD permits free reuse for any purpose, including commercial use, subject to attribution requirements". SJ Nord trains are missing from Entur’s GTFS-RT vehicle positions (0 vehicles on 2026-11-06); they are read from SIRI VM instead (13 trains on 2026-11-09). Its journey refs are DatedServiceJourneys, not the GTFS trip ids, so a train is matched to its run by line and position. | "Trains (Inneholder data under Norsk lisens for offentlige data (NLOD) tilgjengeliggjort av Entur AS): [NLOD 2.0](https://data.norge.no/nlod/en/2.0)" | +| **KTMB** (api.data.gov.my) | Rail layer trains, Peninsular Malaysia: Keretapi Tanah Melayu (ETS, Intercity, KTM Komuter, Shuttle Tebrau). Live GPS positions. Its vehicles name no route, so it is listed only once its path and schedule packs are built from its static GTFS. | [CC BY 4.0](https://developer.data.gov.my/realtime-api/gtfs-realtime): "All GTFS Realtime feeds are licensed under CC BY 4.0". developer.data.gov.my, read 2026-11-09; its GTFS Static page says the same of "All GTFS Static feeds". The static GTFS has no shapes. | "Trains (KTMB, via data.gov.my (Government of Malaysia)): [CC BY 4.0](https://developer.data.gov.my/realtime-api/gtfs-realtime)" | +| **Seattle Streetcar** (s3.amazonaws.com, metro.kingcounty.gov) | Rail layer trains, Seattle, WA: City of Seattle (South Lake Union and First Hill lines), via King County Metro. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (s3.amazonaws.com) add delays at its stops. | [King County Transit Data Terms of Use](https://kingcounty.gov/en/dept/metro/rider-tools/mobile-and-web-apps): "King County grants you a limited, revocable license to use, reproduce, and redistribute the Data in accordance with these Terms." Transit Data Terms of Use on the page linked above (undated; read 2026-11-10), which links the GTFS and GTFS-RT used here and covers "schedule, geographic, real-time, or any other data posted by King County". King County also permits users "to copy, distribute, store (electronically or otherwise), create derivative works based on and perform and display (publicly or otherwise) such Data, and make such Data available to end users", and asks for the legend the credit carries; no King County service marks beyond it. Commercial use is not mentioned. The feed bundles King County Metro, Sound Transit and City of Seattle routes; only the City of Seattle streetcars (agency 23) are kept, `100340` South Lake Union and `102638` First Hill (transit, tram). Link light rail is not in this GTFS. | "Trains (Transit scheduling, geographic, and real-time data provided by permission of King County): [King County Transit Data Terms of Use](https://kingcounty.gov/en/dept/metro/rider-tools/mobile-and-web-apps)" | +| **Connector streetcar** (tmgtfsprd.sorttrpcloud.com, www.go-metro.com) | Rail layer trains, Cincinnati, OH: Southwest Ohio Regional Transit Authority (SORTA/Metro). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (tmgtfsprd.sorttrpcloud.com) add delays at its stops. | [SORTA/Metro developer data Terms](https://www.go-metro.com/about/developer-data/): "The Southwest Ohio Regional Transit Authority (SORTA/Metro) hereby grants you (Licensee) non-exclusive, limited and revocable rights to use, reproduce, and redistribute SORTA/Metro’s transit route schedules, pricing, and other associated data (“Data”) subject to the following Terms:". The developer data page linked above (read 2026-11-10), which links the GTFS and these GTFS-RT files. SORTA/Metro trademarks "may not be used in association with Data unless approved in writing by SORTA/Metro", so the credit is text only; "Any modification, alteration, combination or arrangement of the Data is solely at your own risk." Commercial use is not mentioned. Seen 2026-11-10: 2 streetcars among 147 vehicles, 6 streetcar trips among 265 updates, trip ids those of the static file. The file of 2026-10-01 ends on 2026-12-05. One rail route, `100` Streetcar - OTR - Banks (route_type 0): transit, tram. | "Trains (Southwest Ohio Regional Transit Authority (SORTA/Metro)): [SORTA/Metro developer data Terms](https://www.go-metro.com/about/developer-data/)" | +| **Manyōsen** (gtfs-rt-files.buscatch.jp, api.gtfs-data.jp) | Rail layer trains, Toyama, Japan: 万葉線 Manyōsen (Takaoka–Kōshinokata tram). Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (gtfs-rt-files.buscatch.jp) add delays at its stops. | [CC0 1.0](https://api.gtfs-data.jp/v2/organizations/manyosen/feeds/manyosen): ""feed_license": "CC0 1.0"". GTFS Data Repository record of the feed "万葉線", read 2026-11-10: the record lists the GTFS-RT VehiclePositions and TripUpdates (buscatch.jp, keyless) with the CC0 feed. Tram: transit. | "Trains (万葉線株式会社, via the GTFS Data Repository (gtfs-data.jp)): [CC0 1.0](https://api.gtfs-data.jp/v2/organizations/manyosen/feeds/manyosen)" | +| **Toyama tram** (gtfs-rt-files.buscatch.jp) | Rail layer trains, Toyama, Japan: 富山地方鉄道 Toyama Chihō Railway city tram (city lines, Toyamakō Line, loop line). Live GPS positions. No static GTFS is registered, so there are no path or schedule packs, and its trip updates are not used. | [CC0 1.0](https://api.gtfs-data.jp/v2/organizations/chitetsu/feeds/chitetsushinaidensha): ""feed_license": "CC0 1.0"". GTFS Data Repository record of the feed "富山地方鉄道市内電車", read 2026-11-10: the record lists the GTFS-RT VehiclePositions and TripUpdates (buscatch.jp, keyless) with the CC0 feed. The tram-only feed (the company's buses are a separate feed). Tram: transit. | "Trains (富山地方鉄道株式会社, via the GTFS Data Repository (gtfs-data.jp)): [CC0 1.0](https://api.gtfs-data.jp/v2/organizations/chitetsu/feeds/chitetsushinaidensha)" | +| **Bordeaux tram** (bdx.mecatran.com) | Rail layer trains, Bordeaux, France: TBM (Bordeaux Métropole): trams A to F. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (bdx.mecatran.com) add delays at its stops. | [Licence Ouverte / Open Licence 1.0](https://transport.data.gouv.fr/datasets/offres-de-services-bus-tram-et-scolaire-au-format-gtfs-netex-gtfs-rt-siri-lite): "fr-lo". Licence field of the transport.data.gouv.fr dataset "Réseau urbain et scolaire TBM" (publisher Bordeaux Métropole; read through its API on 2026-11-10), covering its GTFS and its GTFS-RT VehiclePositions and TripUpdates; Licence Ouverte 1.0 (Etalab) allows reuse, commercial included, with attribution. Tram: transit, tram. | "Trains (Bordeaux Métropole (TBM)): [Licence Ouverte / Open Licence 1.0](https://transport.data.gouv.fr/datasets/offres-de-services-bus-tram-et-scolaire-au-format-gtfs-netex-gtfs-rt-siri-lite)" | +| **Montpellier tram** (gtfsproxy.e-tam.fr) | Rail layer trains, Montpellier, France: TaM (Montpellier Méditerranée Métropole): trams 1 to 5. Live GPS positions. Optional path and schedule packs built from its static GTFS add its lines, stop names and next stops. With a built schedule pack, trip updates (gtfsproxy.e-tam.fr) add delays at its stops. | [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/): "odc-odbl". Licence field of the transport.data.gouv.fr dataset "Réseau urbain TaM" (publisher Montpellier Méditerranée Métropole; read through its API on 2026-11-10), covering its GTFS and its GTFS-RT VehiclePositions and TripUpdates. ODbL is share-alike, with the access point's special conditions (doc.transport.data.gouv.fr "Licence ODbL", read 2026-11-10): the share-alike clause covers information "de même nature, de même granularité, de mêmes conditions temporelles et de même emprise géographique", and "Les bases de données ainsi repartagées doivent être publiées sur le Point d'accès national transport.data.gouv.fr, dans le format d'origine." The path and schedule packs built from this GTFS are such a database once shared: offered under ODbL with the attribution kept. Tram: transit, tram. | "Trains (TaM / Montpellier Méditerranée Métropole): [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/)" | | **ZDiTM Szczecin** (zditm.szczecin.pl) | Transit layer live vehicles, Szczecin, Poland: buses and trams as one feed | CC0 1.0, stated on the ZDiTM developer page: “The data are provided free of charge under the CC0 1.0 licence, for use in any context, with no prior notification required.” Keyless GTFS-Realtime; the page says one update a minute, measured at about every 20 seconds. The feed carries no route id, so every vehicle takes the default bus mode. | None required (CC0); credited to ZDiTM Szczecin as a courtesy | | **Carris Metropolitana** (api.carrismetropolitana.pt) | Transit layer live vehicles, Lisbon Metropolitan Area, Portugal | Keyless GTFS-Realtime documented in the operator’s public API repository (github.com/carrismetropolitana/api). No licence is stated for the realtime endpoint; the operator’s static GTFS is CC BY 4.0. Included on the same basis as the Metro Transit and OVapi feeds and credited as a courtesy; it can be switched off if Carris objects. Speeds are published in km/h and converted to m/s by the proxy. Route ids are read as the line number per the operator’s `/v2/routes`. | Courtesy credit to Carris Metropolitana | | **Prague PID** (api.golemio.cz) | Transit layer live vehicles, Prague and Central Bohemia, Czechia | CC BY (https://pid.cz/o-systemu/opendata/). Stated: “Data, která lze stáhnout přímo zde z webu, jsou stejně jako celý obsah webu opatřena licencí CC-BY” The PID open-data page lists this realtime feed and licenses the data it publishes under CC BY, crediting the author and any changes. The same page says data served from other sources follows that source’s licence; the feed is served by Golemio, the city’s data platform, which states none of its own. Keyless since the catalogue moved it off the X-Access-Token endpoint. Speeds are m/s, checked against movement on 2026-11-07. Route ids are `L` plus a number whose range gives the mode and the line (metro `L991` is A, train `L1004` is S4, ferry `L1801` is P1), read from PID’s GTFS routes.txt. | Pražská integrovaná doprava (PID) / Golemio | @@ -186,23 +223,28 @@ The optional Local ADS-B layer and the broadcast-FM receiver use radio you recei The numerical minima come from US 14 CFR 91.227(c), not a published jamming classifier. Readsb's [JSON contract](https://github.com/wiedehopf/readsb/blob/dev/README-json.md) describes the quality field origins and GPS-loss flag. - 2. **GPSJAM aggregation:** score = `100 × max(0, bad − 1) / total`, with percent - bands < 2, 2–10, > 10. One bad aircraft is discounted. This is not the raw - share of bad aircraft. See the [GPSJAM FAQ](https://gpsjam.org/faq). - 3. **GEV window:** 30 minutes over visited views, at least three aircraft per - 0.5° cell. These bands were developed for daily totals; with fewer than ten - observations a cell can skip the middle band. Source timestamps date evidence - even through cache replays, and degraded evidence expires independently. + 2. **GPSJAM aggregation:** aircraft are binned into H3 resolution-4 hexagons + (about 1,770 km² each), and score = `100 × max(0, bad − 1) / total`, with + percent bands < 2, 2–10, > 10. One bad aircraft is discounted. This is not + the raw share of bad aircraft. As on GPSJAM there is no minimum aircraft + count: every hexagon with an aircraft is shown, and the discount is the only + small-sample guard. See the [GPSJAM FAQ](https://gpsjam.org/faq). + 3. **GEV window:** 30 minutes over visited views. These bands were developed + for daily totals; with fewer than ten observations a cell can skip the + middle band. Source timestamps date evidence even through cache replays, + and degraded evidence expires independently. Medium/high cells report navigation-integrity anomalies. Interference is one possible explanation, not a detected or located emitter. Avionics faults and manoeuvring military trainers can also lower reported accuracy. Blank areas - can be outside coverage or lack enough observations. Attribution: adsb.lol - contributors, ODbL 1.0; GPSJAM for aggregation only. + are outside coverage or had no qualifying aircraft in the window. + Attribution: adsb.lol contributors, ODbL 1.0; GPSJAM for the grid and + aggregation only. - **adsbdb enrichment.** `/api/adsbdb` resolves an ICAO hex to aircraft type, model name and registration, and the tracked flight's callsign to an airline and an origin/destination pair. Fan-out is deliberately small because adsbdb is a free community API that publishes no quota: at most 4 requests in flight, dispatches dripped to roughly 5/s, and each key asked for at most once per session (for the flights layer's enrichment, a lookup that failed temporarily, such as an outage, a timeout, a rate limit or an authorization refusal that may clear, may be asked again after a 60-second cool-down; an answer, found or not, and a permanent refusal such as a 404 are final; Local ADS-B lookups are asked once), with route lookups reserved for the tracked aircraft. The dev-server proxy caches each key for 24 hours in `.gev-cache/adsbdb.json`, negative answers included, so fresh entries survive server restarts. That gitignored cache remains local to the deployment and is not bundled with this repo. adsbdb publishes no general service license; its README says the route data may not be copied, published, or incorporated into other databases without the explicit permission of David J Taylor, Edinburgh. Deployers are responsible for obtaining any permission their use requires. Enrichment is best-effort and fail-silent — a flight that gets no answer keeps what the flight feed already gave it. -- **Planespotters photos.** When you track an aircraft, the browser asks `https://api.planespotters.net/pub/photos/hex/{hex}` directly (the API answers cross-origin, so no key and no server proxy are involved) for that aircraft only, once per hex per session, through the same enrichment queue as adsbdb, with an 8-second timeout. A miss is remembered for the session; a request that failed temporarily (an outage, the timeout or a rate limit) may be asked again after a 60-second cool-down while the aircraft stays tracked, as for the flights layer's other enrichment. Either way no photo shows meanwhile. The first photo whose image is an `https://` URL on `*.plnspttrs.net`, whose page is an `https://www.planespotters.net` URL, and which names its photographer is shown in the CONTEXT panel's CONTACTS view, under the tracked flight's name (`src/ui/views/panels/AwarenessPanel.vue`), and nowhere else; a vessel, an installation, a military aircraft or a converted TR-3B has none, and a military aircraft or TR-3B is never looked up. Anything else is dropped, so the app never shows or links outside Planespotters (`src/data/planespottersPhoto.js`, also exported as `gods-eye-view/sources/planespotters` for servers that cache the lookup). The photo follows the attribution rules: the thumbnail is hotlinked from the URL the API gives (never copied or re-hosted), the photographer's name is visible text next to it ("Photo © {photographer}"), and the photo and credit are a plain link to the photo's Planespotters page with `target="_blank" rel="noopener"` and never `rel="nofollow"`. If the image fails to load, the photo and its credit are hidden. +- **Planespotters photos.** When you track an aircraft, the browser asks `https://api.planespotters.net/pub/photos/hex/{hex}` directly (the API answers cross-origin, so no key and no server proxy are involved) for that aircraft only, once per hex per session, through the same enrichment queue as adsbdb, with an 8-second timeout. A miss is remembered for the session; a request that failed temporarily (an outage, the timeout or a rate limit) may be asked again after a 60-second cool-down while the aircraft stays tracked, as for the flights layer's other enrichment. Either way no photo shows meanwhile. The first photo whose image is an `https://` URL on `*.plnspttrs.net`, and whose page is an `https://www.planespotters.net` URL is shown in the CONTEXT panel's CONTACTS view, under the tracked flight's name (`src/ui/views/panels/AwarenessPanel.vue`), and nowhere else; a vessel (see Open Vessel Photos below), an installation, a military aircraft or a converted TR-3B has none, and a military aircraft or TR-3B is never looked up. Anything else is dropped, so the app never shows or links outside Planespotters (`src/data/planespottersPhoto.js`, also exported as `gods-eye-view/sources/planespotters` for servers that cache the lookup). The photo follows the attribution rules: the thumbnail is hotlinked from the URL the API gives (never copied or re-hosted), the photographer's name, when the answer gives one, is visible text next to it ("Photo © {photographer}"; a photo whose answer names no one shows no credit line), and the photo and credit are a plain link to the photo's Planespotters page with `target="_blank" rel="noopener"` and never `rel="nofollow"`. If the image fails to load, the photo and its credit are hidden. +- **Open Vessel Photos.** When you select a vessel with a nine-digit MMSI, the browser asks `https://openvesselphotos.org/v1/mmsi/{mmsi}` directly (the API is keyless and answers cross-origin, so no key and no server proxy are involved; account credentials are never sent) for that vessel only, once per MMSI per session, with an 8-second timeout. A miss (a 404 or a vessel without photos) is remembered for the session; a failed request may be asked again after five minutes. The first photo whose image is an `https://openvesselphotos.org` URL and which names a licence is shown, at the 800 px size, in the CONTEXT panel's CONTACTS view under the vessel's name and MMSI (`src/ui/views/panels/AwarenessPanel.vue`), and nowhere else (`src/data/openVesselPhoto.js`, `src/layers/vessels/photos.js`). The image is hotlinked from the URL the API gives (never copied or re-hosted); the photographer and licence are visible text next to it ("Photo: {photographer} · {licence}", or "Photo · {licence}" when the answer names no one), and the photo and credit link to the vessel's Open Vessel Photos page with `target="_blank" rel="noopener"`. If the image fails to load, the photo and its credit are hidden. - **Launch Library 2.** `/api/launches` makes a server-side rolling-30-day query against the supported v2.3 detailed launch endpoint, caches successful responses for 15 minutes in memory and on disk, and serves the last successful response during a throttle or transient outage. Anonymous access is limited to 15 calls/hour; deployments can provide `LL2_API_TOKEN` for authenticated access. The Space Devs' published terms permit using and sharing the API data in any form, ask users not to forward it without adding value, disclaim complete accuracy, and encourage—but do not require—attribution. This app keeps a courtesy credit. Payload and stage/recovery records are shown only when supplied. Failed launches expose their source status and never receive fallback orbit geometry or a live/estimated marker. LL2 supplies launch context and event timing, not continuous ascent telemetry or live orbital state. - **TfL JamCams.** The camera list comes from the keyless `api.tfl.gov.uk` endpoint (an optional `TFL_APP_KEY` raises its rate limit); frames come from TfL's public S3 bucket. The "Powered by TfL Open Data" attribution is required by TfL's terms and is registered in the Data attribution popover. - **Ontario 511 CCTV.** The camera list comes from the `511on.ca/api/v2/get/cameras` endpoint, which now requires a free developer key (`ONTARIO_511_API_KEY`: sign up at 511on.ca/my511/register, then request it while logged in at 511on.ca/developers/doc; throttled to 10 calls a minute). Without the key the pack is skipped. Frames are server-registered still images under `511on.ca/map/Cctv/`. The source is live-fetched at runtime and attributed under the Open Government Licence - Ontario. Access is governed by Ontario 511's Developer's Access Agreement (511on.ca/developers/resources): the data stays under the Open Government Licence - Ontario unless otherwise specified; key requests are reviewed case by case and ask for the intended use and any third parties that will receive the data; attribution by link to 511on.ca is encouraged, and the Ontario 511 logo may not be altered or used to imply endorsement (this app links and shows no logo); and the data is provided "as is", a disclaimer distributors should pass on, which the credit does. @@ -230,7 +272,8 @@ The optional Local ADS-B layer and the broadcast-FM receiver use radio you recei - **Houston TranStar cameras.** Keyless. The camera list is the public `traffic.houstontranstar.org/data/layers/cctvSnapshots_json.js` catalog (~1,000 cameras across Greater Houston); frames are stills at `www.houstontranstar.org/snapshots/cctv/.jpg`, synthesized from a validated numeric id rather than taken from the payload, and only that host is registered. Cameras whose catalog id is `0` (a different, non-snapshot class) and cameras outside Greater Houston are dropped. TranStar's `dir` field is the side of the freeway the camera sits on, not the way it faces: TranStar's own map shows it as "Traffic closest to the camera is traveling …" (South → eastbound, North → westbound, West → southbound, East → northbound). That travel direction (90°, 270°, 180°, 0°) seeds the heading as a low-confidence prior with the low-confidence pose; `None` or an unknown value uses the shared id-hash fallback at low confidence. Headings are corrected with the in-app calibration gizmo. Off by default. TranStar's [Content Usage terms](https://traffic.houstontranstar.org/disclaimer.aspx) prohibit copying or distributing the site's information, and external framing or linking to specific images, without TxDOT's prior written permission; its FAQ grants permission-free use only for the RSS feeds. This project does not hold that permission for downstream installations, so the pack loads only when an operator who holds TxDOT's written permission sets `CCTV_HOUSTON_ENABLED=1`; with the flag unset, empty or any other value, the server makes no request to TranStar. Once enabled, it loads the 250 cameras nearest downtown, Uptown, the Medical Center, IAH and Galveston; `CCTV_HOUSTON_MAX_SOURCES` (8–400) changes the cap. Snapshots update about every 3 minutes, which is also the ambient still cadence. Frames are fetched from TranStar and relayed to the browser on demand, buffered only transiently per request, sent with `Cache-Control: no-store`, and not archived. - **Autostrada del Brennero (A22) webcams.** Keyless. The camera list is one request to the Open Data Hub tourism API (`tourism.api.opendatahub.com/v1/WebcamInfo?source=a22`), run by NOI Techpark in South Tyrol, which republishes Autobrennero's own list of 13 motorway webcams with coordinates and kilometre markers. Frames are the operator's stills on `www.autobrennero.it/WebCamImg/km.jpg`, refreshed about once a minute, and only the exact image for each camera's kilometre is registered. The feed names no bearing, so headings use the id-hash fallback at low confidence. The road climbs from about 20 m in the Po valley to about 1,370 m at the Brenner Pass, so each camera's ground elevation comes from a per-kilometre table sampled from the Copernicus GLO-90 DEM (via Open-Meteo's elevation API); a camera not in the table uses a 200 m prior. The Open Data Hub tags every record CC0 (`ClosedData: false`, Autobrennero as licence holder), but that tag is the aggregator's metadata and Autobrennero publishes no terms of its own for the images, so they are credited to the operator as a courtesy and are not redistributed. Frames are fetched at request time and never stored. Disable with `CCTV_A22_ENABLED=0`. - **Camera frame content.** Public camera frames can contain people, vehicles and license plates, and the camera layer does nothing with them beyond putting them on the map. A successful upstream response is relayed as the provider served it: nothing in the camera pipeline blurs, redacts, enhances or restores it, and nothing there runs face, plate or object detection or otherwise recognises or classifies what is in the picture. (The ALPR layer described below maps where plate-reader cameras are, from locations contributors tagged in OpenStreetMap; it reads nothing from any camera frame.) When an upstream has no frame for a camera, what you see instead is a Google Street View still or the app's own placeholder card; the panel's source badge names which of them you are looking at, and a refresh that fails after a frame has arrived leaves the last good picture on screen rather than replacing it. The browser resamples each frame for display: onto a fixed 1920x1080 surface for the camera's projection plane in the scene, and onto a 192x108 canvas for the small ambient card. That scaling is the only change made to the picture, and the only pixels the camera layer reads back are a 64x36 downscale hashed to tell whether the picture has changed. Live streams are piped through; the still path reads the image into memory to pass it on — TxDOT wraps its JPEG in a JSON envelope, which is decoded there — and no frame is written to disk (the disk cache, `.gev-cache/`, holds feed JSON for other layers and never camera imagery). Outside that pipeline, the voice assistant is the one feature that sends imagery anywhere: when it answers a question about what is in view it may attach a downscaled screenshot of the rendered scene — including any camera plane on screen — to the request it sends to the voice model. Frames are fetched only from server-registered camera URLs — a client cannot hand the proxy a URL (see [SECURITY.md](SECURITY.md)). What the app does stays inside the line README draws: no named-person search, no face recognition, no tracking individuals. -- **Transit (GTFS-Realtime).** The proxy requests only registered operator feeds, validates redirects, bounds responses, and uses conditional requests, short snapshot caching and failure backoff. All fifty-two registered feeds, covering forty-nine regions, are live-enabled; each can be disabled independently. Vehicles use delayed playback between reports, with report age and waiting states shown separately. Session-local selected trails are available for every feed. MBTA additionally retains up to 15 minutes of recently observed positions in the running proxy, so available history can survive a browser reload; server restart clears it. History reads never fetch upstream, and other feeds have no proxy retention. Nothing is archived to disk or collected in the background. Operator text credits are included as a courtesy and do not imply endorsement. Heights are aligned to work with Google 3D tiles; subway markers are shown at street level because these feeds do not supply depth. The TTC feed is BusTime, the surface system: it carries buses and streetcars and no subway at all. About four in ten of its vehicles report no route at all (unassigned or deadheading), and those are shown with the feed default rather than a route-established mode. It sends no ETag or Last-Modified, so its conditional requests fall through to the ordinary snapshot cache. Three Golden Horseshoe neighbours run alongside it — MiWay, Hamilton HSR and Durham Region Transit — each bus-only and each polled only near its own region. Durham Region Transit publishes no bearing on any vehicle, so those sprites take their heading from observed movement like any other feed that omits it. Guelph, Kingston and Barrie extend the same pattern eastward and north. Hamilton, Guelph, Burlington, YRT and Rio’s SMTR publish route ids that are not the number on the vehicle, so those entries carry a route-name table taken from each operator’s own published GTFS; any id missing from a table renders unchanged rather than blank. A label is never invented: YRT runs a route `9101` that appears nowhere in its published routes, so it stays as the feed sends it. Burlington’s is the one that cannot be shortcut: `351` is route 1 while `3510` is route 10, so the table is a real join rather than a trimmed prefix. GO Transit / Metrolinx is deliberately absent: its REALTIME feed requires an API key issued by manual review, which the keyless admission rule excludes (its static schedule download is keyless, but carries no vehicle positions). Barrie and YRT/Viva each invite acceptance of their licence through a form, and each licence also states that using the data is itself acceptance; this deployment relies on that clause, which is recorded in both entries. Grand River Transit in Waterloo is absent for a different reason: it answers, but its feed header was months stale and it publishes no per-vehicle timestamps, so it would render vehicles that look live and are not. Ottawa’s OC Transpo falls to the same keyless admission rule as GO Transit — its realtime feed requires an API key. London Transit and Thunder Bay Transit publish vehicle positions over plain HTTP with no HTTPS endpoint available. Every other Ontario system — Brampton, Oakville, Niagara, Milton, Windsor, Greater Sudbury, UP Express and a dozen smaller operators — publishes static GTFS schedules only, with no realtime vehicle positions to register. Between the nine included and these exclusions, every Ontario realtime vehicle-position feed catalogued in the Mobility Database is accounted for. +- **Transit (GTFS-Realtime).** The proxy requests only registered operator feeds, validates redirects, bounds responses, and uses conditional requests, short snapshot caching and failure backoff. All fifty-three registered feeds, covering fifty regions, are live-enabled; each can be disabled independently. Vehicles use delayed playback between reports, with report age and waiting states shown separately. Session-local selected trails are available for every feed. MBTA additionally retains up to 15 minutes of recently observed positions in the running proxy, so available history can survive a browser reload; server restart clears it. History reads never fetch upstream, and other feeds have no proxy retention. Nothing is archived to disk or collected in the background. Operator text credits are included as a courtesy and do not imply endorsement. Heights are aligned to work with Google 3D tiles; subway markers are shown at street level because these feeds do not supply depth. The TTC feed is BusTime, the surface system: it carries buses and streetcars and no subway at all. About four in ten of its vehicles report no route at all (unassigned or deadheading), and those are shown with the feed default rather than a route-established mode. It sends no ETag or Last-Modified, so its conditional requests fall through to the ordinary snapshot cache. Three Golden Horseshoe neighbours run alongside it — MiWay, Hamilton HSR and Durham Region Transit — each bus-only and each polled only near its own region. Durham Region Transit publishes no bearing on any vehicle, so those sprites take their heading from observed movement like any other feed that omits it. Guelph, Kingston and Barrie extend the same pattern eastward and north. Hamilton, Guelph, Burlington, YRT and Rio’s SMTR publish route ids that are not the number on the vehicle, so those entries carry a route-name table taken from each operator’s own published GTFS; any id missing from a table renders unchanged rather than blank. A label is never invented: YRT runs a route `9101` that appears nowhere in its published routes, so it stays as the feed sends it. Burlington’s is the one that cannot be shortcut: `351` is route 1 while `3510` is route 10, so the table is a real join rather than a trimmed prefix. TransLink needs no table: its route keys carry a GTFS version suffix (`200-4`) and Cairns puts a `C` before its bus numbers (`C123-33`), so both are stripped by rule to the number on the vehicle. GO Transit / Metrolinx is deliberately absent: its REALTIME feed requires an API key issued by manual review, which the keyless admission rule excludes (its static schedule download is keyless, but carries no vehicle positions). Barrie and YRT/Viva each invite acceptance of their licence through a form, and each licence also states that using the data is itself acceptance; this deployment relies on that clause, which is recorded in both entries. Grand River Transit in Waterloo is absent for a different reason: it answers, but its feed header was months stale and it publishes no per-vehicle timestamps, so it would render vehicles that look live and are not. Ottawa’s OC Transpo falls to the same keyless admission rule as GO Transit — its realtime feed requires an API key. London Transit and Thunder Bay Transit publish vehicle positions over plain HTTP with no HTTPS endpoint available. Every other Ontario system — Brampton, Oakville, Niagara, Milton, Windsor, Greater Sudbury, UP Express and a dozen smaller operators — publishes static GTFS schedules only, with no realtime vehicle positions to register. Between the nine included and these exclusions, every Ontario realtime vehicle-position feed catalogued in the Mobility Database is accounted for. +- **Rail (GTFS-Realtime trains).** Each feed in `src/data/railFeeds.js` records its licence, its credit and the passage of its terms the decision rests on, and a feed is switched on only when those terms were read and cover this use, or, for those that publish no licence at all, on the basis its entry records. Such a basis is never a licence, and the credit does not present it as one: its label says there is no licence ("No licence published", "No licence stated") or names the publication the use rests on. Five enabled feeds publish no licence for their train positions. MARC is used on what its publication says (open publication with a no-endorsement disclaimer), and METRO light rail on the same basis as the Transit layer's Metro Transit feed. Tri-Rail and Charlotte's LYNX are used without a published licence by project owner decision of 2026-11-10. The fifth is Irish Rail, whose train positions publish no licence while its NTA timetable is CC BY 4.0. The registry lists 30 feeds, all switched on, and every one is keyless: its realtime feed and its static timetable are published for anyone to fetch, so no feed needs a key, an account or a registration, and the server holds no rail credential. No rail request carries a credential of the deployer's; one feed's published URL includes a fixed public value its publisher prints for everyone (Bordeaux's `apiKey`). `/api/rail/feeds` lists the offered feeds, `/api/rail/trains/` returns one feed's train snapshot, `/api/rail/updates/` its trip updates, and `/api/rail/paths/` and `/api/rail/schedule/` its path and schedule packs, when built. The proxy requests only registered feeds and reuses the Transit proxy's request policy (a short snapshot cache with single-flight refresh, serve-stale, admission limits, the failure cooldown ladder, redirects followed hop by hop only on the feed's own https origin, and an 8 MiB body cap unless a feed sets its own, at most 64 MiB). Many operators publish trains in the same feed as their buses, so each feed has a classifier: the proxy keeps only vehicles it recognises as trains, tags each with a category (`transit`, `local`, `regional`, `national` or `international`) and a mode (`rail`, `metro` or `tram`), and drops everything else server-side, counted in the snapshot as `dropped`; the browser never receives a bus. Every train shown is live, where its operator last reported it: 29 feeds publish live GPS positions (SJ Nord's through SIRI VM), and Irish Rail reports the station or timing point a train last passed. No train is placed or moved from a timetable; a feed whose live positions fail shows as unavailable, and its trains age out as any quiet train does. 22 feeds register trip updates, polled while one of their trains is selected and that feed's schedule pack is loaded. 28 feeds work out of the box. Packs are an opt-in extra for live trains: nothing is downloaded when the app starts, and `node scripts/build-rail-paths.mjs --feed ` (repeatable) or `--all` downloads a feed's static GTFS (29 of the 30 have one) and writes a path pack (the operator's track shapes) and a schedule pack (the stop times for a window of days) to `.cache/rail-paths/` (or to `RAIL_PATHS_DIR` when set, the directory the server then serves). With them, a live train is drawn on its operator's route line and its card names its stops, its next stop and, from the trip updates, their delays. Renfe long and medium distance and KTMB, whose vehicles name no route, are classified from their pack's routes, so `/api/rail/feeds` lists them only once that pack is built. Lines are the operator's own shapes as published: nothing is routed or redrawn from other map data, and no line is drawn where an operator publishes no shape. **Share-alike sources bind the deployer.** A pack built from a ShareAlike or ODbL source is a derived database of it, so a deployer who serves it publicly makes it subject to the same licence and must offer it under that licence with the attribution kept. That covers the Montpellier packs (ODbL). For the ODbL datasets of France's national access point, its special conditions also require that "Les bases de données ainsi repartagées doivent être publiées sur le Point d'accès national transport.data.gouv.fr, dans le format d'origine" ([Licence ODbL](https://doc.transport.data.gouv.fr/le-point-d-acces-national/cadre-juridique/conditions-dutilisation-des-donnees/licence-odbl), read 2026-11-10): a deployer who serves the Montpellier packs publicly takes on republishing that derived data there, as GTFS. The build downloads each static GTFS itself, over https and with no credential. A feed's `staticRouteTypes` lists the route types it keeps when its classifier accepts every route of a mode-specific feed. A frequency-based trip becomes one run per departure on its template's stops and run times. Packs are build output, not part of the repository, and cover a fixed window of days, so they are rebuilt before it ends, and more often where an operator republishes more often. A build in which any feed fails exits with code 2, the other feeds still built. A stop the GTFS gives no coordinates, which some feeds write as (0, 0), is left out of the run, so no line is ever drawn to it and no stop is placed by guesswork. Where several loaded feeds carry the same train, it is drawn once. Copies are matched by train number within 100 km, or, for a short line name (S1, RB 1, U6), on the same line in the same category within 15 km. A train number is three or more digits, or a shorter number after a long-distance product (EC, ECE, EN, ICE, NJ, RJ, RJX, TGV; not IC, where a short number names a line); a trip id that is an operator prefix and a number, or a headsign that is a bare number, is read too. The copy drawn is scored by its position source (live GPS, then station reports), then by its line (on its operator's shape, then without one), and stays drawn until another scores strictly higher. No train is ever placed in Ukraine, a safety rule: the build leaves out every run with a stop there, a stop whose id names Ukraine or whose position is inside its recognised borders (either is enough: an id naming another country does not keep a stop inside them), and the proxy drops every live position inside those borders (`src/data/railNoPositions.js`). Trains use the Transit layer's delayed playback between reports and move along their line in the path pack where there is one, else in straight lines. No train position is archived to disk, there is no proxy history, and nothing is collected in the background. Operator credits appear when that feed's trains are shown and do not imply endorsement. - **Radio country coverage (optional).** Set `RADIO_PRIORITY_COUNTRIES=IN,PL` in the local `.env` and restart to include stations beyond the global click charts. The operator may choose up to eight unique ISO alpha-2 country codes; no key is needed. Each country adds one bounded query (at most 200 rows) and reserves up to 40 unique, usable stations inside the existing 750-station catalog. Country seeds precede specialist-tag seeds and global popularity fill; unused slots return to the shared pool. This is a coverage preference, not an exhaustive national directory or a guarantee of stations in every city. Countries with no eligible HTTPS MP3/AAC geolocated stations remain empty. An unset list preserves global selection. Country requests share the directory cache and three-worker pool; failed country queries are reported in coverage without blocking a healthy global refresh. Failed/degraded refreshes back off for one minute, with at most three mirrors per query. - **Radio Browser.** In every installation, including when `RADIO_PRIORITY_COUNTRIES` is unset, each request tries at most three mirror candidates (later fallback candidates are skipped), and failed or partial catalog refreshes back off for 60 seconds. A cold-start failure therefore continues returning 503 during that delay even if upstream recovers. `/api/radio/stations` discovers official API mirrors, makes bounded and coalesced healthy/geolocated HTTPS-station queries, caches the normalized public-domain directory for 45 minutes, and may serve the last good catalog for up to seven days during an outage. Refreshes must meet minimum accepted-query and station coverage before replacing a warm catalog; broad/specialist responses whose rows all fail the product's health policy do not count as successful queries. Optional priority-country outcomes are advisory: valid, in-limit responses with no eligible stations succeed as empty results, while failed or malformed country queries report unsuccessful coverage without degrading the global catalog. A usable partial cold catalog is explicitly `DEGRADED`, and non-array or empty broad/specialist payloads are rejected atomically. Individual structurally malformed rows are skipped rather than failing the whole query; the response carries their bounded `rejectedStationCount` (at most 10,000), which the client adds to its own rejected rows and reports as degraded coverage without discarding the accepted generation. Every directory and click-count request rejects redirects, validates all resolved addresses as globally routable (including reserved/documentation IPv4 and special/non-global IPv6 exclusions), and pins the TLS connection to a validated address. Only MP3/AAC non-HLS directory rows with public HTTPS stream targets are returned; favicons are intentionally omitted. Pressing play connects one browser audio element directly to the selected broadcaster and calls the directory's click counter through known-ID-only `POST /api/radio/click/:uuid`. GEV never proxies, caches, records, bundles, or redistributes audio. Radio Browser supplies station-level tags, not dependable current-song or upcoming-program metadata, so Radio filtering never claims either. Direct playback exposes the listener's IP address to the broadcaster, whose own stream terms apply. @@ -251,6 +294,113 @@ The optional Local ADS-B layer and the broadcast-FM receiver use radio you recei --- + + +## Data Library entries (fetched at runtime — not stored in this repo) + +Each Data Library entry is a manifest in `src/library/entries/` pointing at a live upstream its provider hosts; see [docs/DATA-LIBRARY.md](docs/DATA-LIBRARY.md). An entry appears on the map only after a viewer adds it from **DATA LAYERS ▸ Browse data library**, and its attribution is registered in the Data attribution popover while it is in use. This table is generated from the manifests: edit the manifest, then run `npm run library:docs`. + +| Entry | How it is served | Licence / terms | Attribution | +| --- | --- | --- | --- | +| **Alaska Statewide Imagery (2023)** (`ak-statewide-imagery`, `apps.geo.fpac.usda.gov`) | tiles, bbox, browser-direct | [Public Domain (U.S. Government work)](https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits) | "USDA / Alaska Geospatial Council" | +| **Amsterdam traffic and ANPR camera positions** (`amsterdam-traffic-cameras`, `api.data.amsterdam.nl`) | dataset, geojson, browser-direct; operator adds `amsterdam-traffic-cameras` to `GEV_LIBRARY_ENABLE` | [Gemeente Amsterdam open data: public unless stated otherwise; no named licence](https://schemas.data.amsterdam.nl/datasets/verkeersinformatiesystemen/dataset) | "Gemeente Amsterdam, verkeersinformatiesystemen register (entry contributed by @Maher-Reven)" | +| **Arkansas Statewide Imagery (2023)** (`ar-statewide-imagery`, `gis.arkansas.gov`) | tiles, bbox, browser-direct | [Public domain — Arkansas GIS Office open data](https://gis.arkansas.gov/) | "Arkansas GIS Office" | +| **Arizona Statewide Imagery (2017)** (`az-statewide-imagery`, `azgeo.az.gov`) | tiles, xyz, browser-direct; operator adds `az-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://azgeo.az.gov/) | "AZGEO" | +| **Digitales Orthophoto Bayern (DOP 40 cm, open)** (`bayern-dop40`, `geoservices.bayern.de`) | tiles, bbox, browser-direct | [CC BY 4.0](https://geodaten.bayern.de/opengeodata/) | "© Bayerische Vermessungsverwaltung" | +| **Bismarck–Mandan, North Dakota Aerial Photography** (`bismarck-mandan-nd`, `ndgishub.nd.gov`) | tiles, bbox, browser-direct; operator adds `bismarck-mandan-nd` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.gis.nd.gov/) | "95West Aerial Mapping" | +| **TopPlusOpen basemap (BKG)** (`bkg-topplus-open`, `sgx.geodatenzentrum.de`) | tiles, xyz, browser-direct | [Datenlizenz Deutschland – Namensnennung 2.0](https://www.govdata.de/dl-de/by-2-0) | "© BKG, dl-de/by-2-0" | +| **Florida cameras (FL511)** (`cctv-florida-fl511`, `fl511.com`) | CCTV pack; operator sets `CCTV_FLORIDA_ENABLED=1` | [FL511 content: individual personal use only](https://fl511.com/privacy#disclaimer) | "Florida DOT — FL511.com" | +| **Lithuania road cameras (Via Lietuva)** (`cctv-lithuania`, `eismoinfo.lt`) | CCTV pack; operator sets `CCTV_LITHUANIA_ENABLED=1` | [Via Lietuva open-data statement; camera photo coverage unconfirmed](https://eismoinfo.lt/eismoinfo-backend/content?id=44) | "Via Lietuva / eismoinfo.lt" | +| **New York City cameras (NYC DOT TMC)** (`cctv-nyc-dot`, `webcams.nyctmc.org`) | CCTV pack; operator sets `CCTV_NYC_ENABLED=1` | [NYC DOT camera feed: data-sharing agreement required](https://www.nyc.gov/html/dot/html/about/datafeeds.shtml) | "NYC DOT Traffic Management Center" | +| **Connecticut Statewide Imagery (2019)** (`ct-statewide-imagery`, `cteco.uconn.edu`) | tiles, bbox, browser-direct; operator adds `ct-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://ct-deep-gis-open-data-website-ctdeep.hub.arcgis.com/) | "CT ECO — UConn CLEAR / CT DEEP" | +| **Dakota County, Minnesota Air Photo** (`dakota-county-mn`, `gisimg.co.dakota.mn.us`) | tiles, bbox, browser-direct; operator adds `dakota-county-mn` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://gis.co.dakota.mn.us/) | "Dakota County GIS" | +| **District of Columbia Statewide Imagery (2025)** (`dc-statewide-imagery`, `imagery.dcgis.dc.gov`) | tiles, bbox, browser-direct | [Open data — DC public domain terms](https://opendata.dc.gov/pages/terms-of-use) | "Office of the Chief Technology Officer" | +| **Delaware Statewide Imagery (2024)** (`de-statewide-imagery`, `imagery.firstmap.delaware.gov`) | tiles, bbox, browser-direct; operator adds `de-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://firstmap.delaware.gov/) | "This data is meant for use by requested parties. This data cannot be used without express consent.This data is meant for use by requested parties. This data cannot be used without express consent." | +| **Eesti ortofoto (Maa-amet)** (`ee-maa-amet-ortofoto`, `tiles.maaamet.ee`) | tiles, xyz, browser-direct | [Maa-amet open data licence (attribution)](https://geoportaal.maaamet.ee/eng/Spatial-Data/Orthophotos-p309.html) | "© Maa-amet (Estonian Land Board)" | +| **US power plants, 100 MW and up (EIA)** (`eia-power-plants`, `services2.arcgis.com`) | dataset, arcgis, browser-direct | [U.S. Energy Information Administration data: public domain](https://www.eia.gov/about/copyrights_reuse.php) | "U.S. Energy Information Administration (EIA-860, EIA-860M, EIA-923)" | +| **Superfund sites (US EPA)** (`epa-superfund-sites`, `geopub.epa.gov`) | dataset, arcgis, browser-direct | [U.S. EPA data: public domain](https://www.epa.gov/web-policies-and-procedures/epa-disclaimers) | "U.S. Environmental Protection Agency — Facility Registry Service (EnviroMapper)" | +| **Toxic release facilities (US EPA TRI)** (`epa-toxic-release-facilities`, `geopub.epa.gov`) | dataset, arcgis, browser-direct | [U.S. EPA data: public domain](https://www.epa.gov/web-policies-and-procedures/epa-disclaimers) | "U.S. Environmental Protection Agency — Toxics Release Inventory via the Facility Registry Service" | +| **Home energy ratings, England and Wales (EPC)** (`epc-england-wales`, `s3.us-west-2.amazonaws.com`) | dataset, geoparquet, browser-direct | [Open Government Licence v3.0 (EPC data); OS Open UPRN under OGL](https://epc.opendatacommunities.org/docs/copyright) | "Energy Performance of Buildings Data, DLUHC; geocoded by Addresscloud with OS Open UPRN — contains OS data © Crown copyright and database right; via Source Cooperative" | +| **US building footprints (FEMA USA Structures)** (`fema-usa-structures`, `services2.arcgis.com`) | dataset, arcgis, browser-direct | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | "FEMA Response Geospatial Office and Oak Ridge National Laboratory — USA Structures" | +| **Biodiversity records (GBIF)** (`gbif-occurrence-density`, `api.gbif.org`) | tiles, xyz, browser-direct | [GBIF data use agreement (records under CC0, CC BY or CC BY-NC)](https://www.gbif.org/terms) | "GBIF.org — Global Biodiversity Information Facility" | +| **Disaster alerts (GDACS)** (`gdacs-disaster-alerts`, `www.gdacs.org`) | dataset, geojson, browser-direct | [GDACS terms of use (free, attribution required)](https://www.gdacs.org/About/termofuse.aspx) | "GDACS — Global Disaster Alert and Coordination System (UN, European Commission)" | +| **Grand Forks, North Dakota Aerial Photography** (`grand-forks-nd`, `ndgishub.nd.gov`) | tiles, bbox, browser-direct; operator adds `grand-forks-nd` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.gis.nd.gov/) | "Grand Forks/East Grand Forks Metropolitan Planning Organization (MPO)" | +| **Japan standard map (GSI)** (`gsi-japan-map`, `cyberjapandata.gsi.go.jp`) | tiles, xyz, browser-direct | [GSI Tiles terms (free use with attribution)](https://maps.gsi.go.jp/development/ichiran.html) | "Geospatial Information Authority of Japan (GSI Tiles)" | +| **Japan aerial photos (GSI)** (`gsi-japan-photo`, `cyberjapandata.gsi.go.jp`) | tiles, xyz, browser-direct | [GSI Tiles terms (free use with attribution)](https://maps.gsi.go.jp/development/ichiran.html) | "Geospatial Information Authority of Japan (GSI Tiles)" | +| **Holocene volcanoes (Smithsonian GVP)** (`gvp-holocene-volcanoes`, `webservices.volcano.si.edu`) | dataset, geojson, proxied | [Smithsonian Terms of Use (personal, educational, non-commercial use; cite the Global Volcanism Program)](https://www.si.edu/termsofuse) | "Global Volcanism Program, Smithsonian Institution — Volcanoes of the World" | +| **Iowa Statewide Imagery (2023)** (`ia-statewide-imagery`, `ortho.gis.iastate.edu`) | tiles, bbox, browser-direct; operator adds `ia-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://geodata.iowa.gov/) | "USDA NAIP, Iowa State University GIS Facility" | +| **Idaho Statewide Imagery (2023)** (`id-statewide-imagery`, `insideidaho.org`) | tiles, bbox, browser-direct | [Public domain / open — INSIDE Idaho terms](https://insideidaho.org/) | "United States Department of Agriculture, Farm Production and Conservation Business Center, Geospatial Enterprise Operations (FPAC-BC-GEO)" | +| **France aerial photos (IGN)** (`ign-orthophotos-france`, `data.geopf.fr`) | tiles, xyz, browser-direct | [Licence Ouverte / Etalab 2.0](https://www.etalab.gouv.fr/licence-ouverte-open-licence/) | "© IGN — Géoplateforme" | +| **Illinois Statewide Imagery** (`il-statewide-imagery`, `data.isgs.illinois.edu`) | tiles, bbox, browser-direct; operator adds `il-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://clearinghouse.isgs.illinois.edu/) | "Illinois State Geological Survey / IDOT" | +| **Maritime chokepoints (IMF PortWatch)** (`imf-portwatch-chokepoints`, `services9.arcgis.com`) | dataset, arcgis, browser-direct; operator adds `imf-portwatch-chokepoints` to `GEV_LIBRARY_ENABLE` | [IMF PortWatch terms; attribution required (reuse terms under review)](https://www.imf.org/external/terms.htm) | "IMF PortWatch (portwatch.imf.org)" | +| **Port disruptions (IMF PortWatch)** (`imf-portwatch-disruptions`, `services9.arcgis.com`) | dataset, arcgis, browser-direct; operator adds `imf-portwatch-disruptions` to `GEV_LIBRARY_ENABLE` | [IMF PortWatch terms; attribution required (reuse terms under review)](https://www.imf.org/external/terms.htm) | "IMF PortWatch (portwatch.imf.org), with GDACS event data" | +| **Indiana Statewide Imagery (2016)** (`in-statewide-imagery`, `di-ingov.img.arcgis.com`) | tiles, bbox, browser-direct | [CC0 1.0 Universal (public domain dedication)](https://creativecommons.org/publicdomain/zero/1.0/legalcode) | "Indiana Geographic Information Office (CC0)" | +| **Surface water occurrence (JRC)** (`jrc-surface-water`, `storage.googleapis.com`) | tiles, xyz, browser-direct | [Copernicus programme: free, without restriction of use](https://global-surface-water.appspot.com/download) | "Source: EC JRC/Google — Pekel et al. (2016), Global Surface Water" | +| **Norway counties and municipalities (Kartverket)** (`kartverket-admin-units`, `wms.geonorge.no`) | tiles, bbox, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Norway cadastral map (Kartverket)** (`kartverket-cadastre`, `wms.geonorge.no`) | tiles, bbox, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Norway sea depths (Kartverket)** (`kartverket-depth`, `wms.geonorge.no`) | tiles, bbox, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Norway hillshade (Kartverket)** (`kartverket-hillshade`, `wms.geonorge.no`) | tiles, bbox, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Norway nautical charts (Kartverket)** (`kartverket-nautical-charts`, `cache.kartverket.no`) | tiles, xyz, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Norway terrain relief (Kartverket DTM)** (`kartverket-terrain-relief`, `wms.geonorge.no`) | tiles, bbox, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Norway topographic map (Kartverket)** (`kartverket-topo`, `cache.kartverket.no`) | tiles, xyz, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Norway topographic map, greyscale (Kartverket)** (`kartverket-topo-grey`, `cache.kartverket.no`) | tiles, xyz, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Norway topographic raster map (Kartverket)** (`kartverket-toporaster`, `cache.kartverket.no`) | tiles, xyz, browser-direct | [CC BY 4.0 (Kartverket free products)](https://www.kartverket.no/api-og-data/vilkar-for-bruk) | "© Kartverket" | +| **Kansas Statewide Imagery (2021)** (`ks-statewide-imagery`, `services.kgs.ku.edu`) | tiles, bbox, browser-direct; operator adds `ks-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://www.kansasgis.org/) | "FSA, USDA," | +| **Kentucky Statewide Imagery** (`ky-statewide-imagery`, `kyraster.ky.gov`) | tiles, bbox, browser-direct | [Public domain with attribution](https://kygeonet.ky.gov/) | "KyFromAbove" | +| **Lake County, Indiana Aerial Imagery** (`lake-county-in`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `lake-county-in` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.lakecountyin.org/) | "Lake County Surveyor's Office" | +| **Lawrence, Kansas Aerial Photos** (`lawrence-ks`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `lawrence-ks` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://gis-lawrenceks.opendata.arcgis.com/) | "City of Lawrence GIS" | +| **Lee County, Florida Aerial Imagery** (`lee-county-fl`, `gisimageserver.leegov.com`) | tiles, bbox, browser-direct; operator adds `lee-county-fl` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.leegov.com/gis) | "Eagle View, Lee County Property Appraiser, Lee County GIS" | +| **Loudoun County, Virginia Imagery** (`loudoun-county-va`, `logis.loudoun.gov`) | tiles, bbox, browser-direct; operator adds `loudoun-county-va` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://geohub-loudoungis.opendata.arcgis.com/) | "Loudoun County GIS" | +| **Louisville / LOJIC, Kentucky Imagery** (`louisville-lojic-ky`, `services.lojic.org`) | tiles, bbox, browser-direct; operator adds `louisville-lojic-ky` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.lojic.org/) | "LOJIC, USDA-NAIP" | +| **Massachusetts Statewide Imagery** (`ma-statewide-imagery`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `ma-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://gis.data.mass.gov/) | "MassGIS, Commonwealth of Massachusetts" | +| **Geologic map (Macrostrat)** (`macrostrat-geology`, `tiles.macrostrat.org`) | tiles, xyz, browser-direct | [CC BY 4.0 (Macrostrat; source maps credited by their publishers)](https://macrostrat.org/about) | "Macrostrat — geologic maps from their original publishers" | +| **Global terrain shaded relief (Mapterhorn)** (`mapterhorn-terrain`, `tiles.mapterhorn.com`) | tiles, xyz, browser-direct | [Open data, per source (mostly CC BY 4.0 and public domain)](https://mapterhorn.com/attribution) | "© Mapterhorn and its open elevation sources" | +| **MARIS Imagery, Mississippi** (`maris-ms`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `maris-ms` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.gis.ms.gov/) | "MARIS" | +| **Maryland Statewide Imagery** (`md-statewide-imagery`, `mdgeodata.md.gov`) | tiles, bbox, browser-direct; operator adds `md-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://imap.maryland.gov/) | "Maryland iMAP" | +| **Maine Statewide Imagery** (`me-statewide-imagery`, `gis.maine.gov`) | tiles, bbox, browser-direct; operator adds `me-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://www.maine.gov/geolib/) | "USDA Aerial Photography Field Office" | +| **Michigan Statewide Imagery (2024)** (`mi-statewide-imagery`, `imagery.michigan.gov`) | tiles, bbox, browser-direct; operator adds `mi-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://gis-michigan.opendata.arcgis.com/) | "State of Michigan" | +| **Mountain Village, Colorado Orthoimagery** (`mountain-village-co`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `mountain-village-co` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.townofmountainvillage.com/) | "Town of Mountain Village" | +| **Mississippi Statewide Imagery** (`ms-statewide-imagery`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `ms-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://www.gis.ms.gov/) | "USDA-FSA-APFO" | +| **Montana Statewide Imagery (2023)** (`mt-statewide-imagery`, `gisservice.mt.gov`) | tiles, bbox, browser-direct | [Public domain — Montana State Library open data](https://msl.mt.gov/geoinfo/) | "Montana State Library" | +| **NAIP — National Agriculture Imagery Program** (`naip`, `imagery.nationalmap.gov`) | tiles, bbox, browser-direct | [Public Domain (U.S. Government work)](https://naip-usdaonline.hub.arcgis.com/) | "USDA NAIP" | +| **Earth at night (NASA Black Marble 2016)** (`nasa-black-marble`, `gibs.earthdata.nasa.gov`) | tiles, xyz, browser-direct | [NASA data: U.S. public domain; no endorsement implied](https://www.earthdata.nasa.gov/engage/open-data-services-software-policies) | "NASA Earth Observatory / GIBS — VIIRS Black Marble" | +| **NASA EONET open natural events** (`nasa-eonet-events`, `eonet.gsfc.nasa.gov`) | dataset, geojson, browser-direct | [NASA data: U.S. public domain; no endorsement implied](https://www.nasa.gov/nasa-brand-center/images-and-media/) | "NASA Earth Observatory Natural Event Tracker (EONET)" | +| **North Carolina Statewide Imagery (2023)** (`nc-statewide-imagery`, `services.nconemap.gov`) | tiles, bbox, browser-direct | [Public domain — NC OneMap terms of use](https://www.nconemap.gov/pages/terms) | "NC911, NCCGIA" | +| **North Central Texas (NCTCOG) Ortho** (`nctcog-tx`, `mapitimage.tarrantcounty.com`) | tiles, bbox, browser-direct; operator adds `nctcog-tx` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.nctcog.org/) | "North Central Texas Council of Governments" | +| **North Dakota Statewide Imagery (2013)** (`nd-statewide-imagery`, `ndgishub.nd.gov`) | tiles, xyz, browser-direct; operator adds `nd-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open state geodata — attribution requested](https://www.gis.nd.gov/) | "ND Dept. of Transportation, ND Dept. of Emergency Services, and the ND GIS Hub" | +| **New Orleans Regional Planning Commission Imagery** (`new-orleans-rpc-la`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `new-orleans-rpc-la` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.norpc.org/) | "Regional Planning Commission for Jefferson, Orleans, Plaquemines, St. Bernard, St. Charles, St. John the Baptist, St. Tammany, and Tangipahoa Parishes (RPC)" | +| **New Hampshire Statewide Imagery (2022)** (`nh-statewide-imagery`, `nhgeodata.unh.edu`) | tiles, bbox, browser-direct; operator adds `nh-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open — NH GRANIT terms](https://www.granit.unh.edu/) | "NH GRANIT, University of New Hampshire" | +| **New Jersey Statewide Imagery (2015)** (`nj-statewide-imagery`, `maps.nj.gov`) | tiles, xyz, browser-direct; operator adds `nj-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open — State of New Jersey provides data 'as is'](https://njgin.nj.gov/) | "Project definition, funding requests, and data distribution by NJ Office of Information Technology, Office of Geographic Information Systems (NJOIT - OGIS). Funding for the imagery project provided by" | +| **US tide stations (NOAA CO-OPS)** (`noaa-tide-stations`, `api.tidesandcurrents.noaa.gov`) | dataset, json, browser-direct | [NOAA data: U.S. public domain](https://tidesandcurrents.noaa.gov/disclaimers.html) | "NOAA Center for Operational Oceanographic Products and Services (CO-OPS)" | +| **Digitale Orthophotos NRW (DOP 10 cm)** (`nrw-dop`, `www.wms.nrw.de`) | tiles, bbox, browser-direct | [Datenlizenz Deutschland – Zero (public-domain-like)](https://www.govdata.de/dl-de/zero-2-0) | "Geobasis NRW (dl-de/zero-2-0)" | +| **NSW Imagery (Six Maps)** (`nsw-imagery`, `maps.six.nsw.gov.au`) | tiles, xyz, browser-direct | [CC BY 4.0](https://www.spatial.nsw.gov.au/products_and_services/web_services) | "© Spatial Services NSW" | +| **US bridges and their condition (NBI)** (`ntad-national-bridges`, `services.arcgis.com`) | dataset, arcgis, browser-direct | [U.S. government work: unrestricted public use](https://www.bts.gov/ntad) | "USDOT Bureau of Transportation Statistics — National Transportation Atlas Database, National Bridge Inventory" | +| **Northwest Arkansas (Benton & Washington County) Imagery** (`nwa-benton-washington-ar`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `nwa-benton-washington-ar` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://www.nwarpc.org/) | "NWARPC; Washington County; Benton County" | +| **US weather alerts with drawn areas (NWS)** (`nws-active-alerts`, `api.weather.gov`) | dataset, geojson, browser-direct | [NWS data: U.S. public domain](https://www.weather.gov/disclaimer) | "NOAA National Weather Service" | +| **New York Statewide Imagery (2019)** (`ny-statewide-imagery`, `orthos.its.ny.gov`) | tiles, xyz, browser-direct | [Public domain — NYS open data](https://data.gis.ny.gov/) | "USDA; NYS ITS Geospatial Services" | +| **Oakland County, Michigan Ortho Imagery** (`oakland-county-mi`, `gisservices.oakgov.com`) | tiles, bbox, browser-direct; operator adds `oakland-county-mi` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://oakgov.maps.arcgis.com/) | "Oakland County GIS" | +| **Ohio Statewide Imagery** (`oh-statewide-imagery`, `maps.ohio.gov`) | tiles, xyz, browser-direct | [Public domain — Ohio open data](https://maps.ohio.gov/) | "Ohio Geographically Referenced Information Program (OGRIP)" | +| **Oregon Statewide Imagery (2000)** (`or-statewide-imagery`, `imagery.oregonexplorer.info`) | tiles, bbox, browser-direct | [Public domain — Oregon open data](https://www.oregon.gov/geo/) | "Oregon, GEO, DAS" | +| **Pennsylvania Statewide Imagery** (`pa-statewide-imagery`, `imagery.pasda.psu.edu`) | tiles, bbox, browser-direct | [Public domain — PASDA open data](https://www.pasda.psu.edu/) | "PASDA / PAMAP, Commonwealth of Pennsylvania" | +| **Ortofotomapa Polski (GUGiK)** (`pl-ortofotomapa`, `mapy.geoportal.gov.pl`) | tiles, bbox, browser-direct | [Polish open geodata (free reuse, Prawo geodezyjne art. 40a)](https://www.geoportal.gov.pl/) | "© GUGiK / geoportal.gov.pl" | +| **PNOA Máxima Actualidad** (`pnoa-ma`, `www.ign.es`) | tiles, bbox, browser-direct | [CC BY 4.0 (compatible) — Orden FOM/2807/2015](https://www.scne.es/productos.html) | "PNOA © Instituto Geográfico Nacional de España" | +| **Portland Metro (RLIS), Oregon Aerial Photos** (`portland-metro-or`, `utility.arcgis.com`) | tiles, xyz, browser-direct; operator adds `portland-metro-or` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://rlisdiscovery.oregonmetro.gov/) | "Oregon Metro RLIS" | +| **Ortofotos de Portugal Continental (DGT)** (`pt-dgt-ortos`, `ortos.dgterritorio.gov.pt`) | tiles, bbox, browser-direct | [CC BY 4.0](https://www.dgterritorio.gov.pt/) | "© Direção-Geral do Território" | +| **Rhode Island Statewide Imagery (2019)** (`ri-statewide-imagery`, `tiles.arcgis.com`) | tiles, xyz, browser-direct; operator adds `ri-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open — RIGIS terms](https://www.rigis.org/) | "URI EDC, RIGIS" | +| **Switzerland aerial photos (SWISSIMAGE 10 cm)** (`swisstopo-swissimage`, `wmts.geo.admin.ch`) | tiles, xyz, browser-direct | [swisstopo free geodata (OGD): free use, including commercial, with source credit](https://www.swisstopo.admin.ch/en/terms-of-use-free-geodata-and-geoservices) | "©swisstopo — SWISSIMAGE 10 cm" | +| **Texas Statewide Imagery (2022)** (`tx-statewide-imagery`, `imagery.geographic.texas.gov`) | tiles, bbox, browser-direct | [Public domain — TxGIO open data](https://geographic.texas.gov/) | "Texas Geographic Information Office (TxGIO)" | +| **Union County, Ohio Aerial Imagery** (`union-county-oh`, `www7.co.union.oh.us`) | tiles, bbox, browser-direct; operator adds `union-county-oh` to `GEV_LIBRARY_ENABLE` | [Local government open data — see publisher terms](https://union-county-auditor-unionco.hub.arcgis.com/) | "Union County / City of Marysville GIS" | +| **US rivers and lakes (USGS)** (`usgs-hydrography`, `basemap.nationalmap.gov`) | tiles, xyz, browser-direct | [USGS The National Map: U.S. public domain](https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits) | "USGS The National Map — National Hydrography Dataset" | +| **US topographic map (USGS)** (`usgs-topo`, `basemap.nationalmap.gov`) | tiles, xyz, browser-direct | [USGS The National Map: U.S. public domain](https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits) | "USGS The National Map" | +| **Virginia Statewide Imagery** (`va-statewide-imagery`, `vginmaps.vdem.virginia.gov`) | tiles, xyz, browser-direct; operator adds `va-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open — VGIN VBMP terms](https://vgin.vdem.virginia.gov/) | "Virginia Geographic Information Network (VGIN)" | +| **Vermont Statewide Imagery** (`vt-statewide-imagery`, `maps.vcgi.vermont.gov`) | tiles, bbox, browser-direct | [Public domain — Vermont open data](https://vcgi.vermont.gov/) | "Vermont Center for Geographic Information (VCGI)" | +| **Orthophotos de Wallonie** (`wallonie-ortho`, `geoservices.wallonie.be`) | tiles, bbox, browser-direct | [Conditions ouvertes SPW (attribution)](https://geoportail.wallonie.be/catalogue-donnees) | "© Service public de Wallonie" | +| **Wisconsin Statewide Imagery (2020)** (`wi-statewide-imagery`, `di-wisdot.img.arcgis.com`) | tiles, bbox, browser-direct; operator adds `wi-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open — WisconsinView / state open data](https://www.wisconsinview.org/) | "WisDOT - NAIP 2020" | +| **Global power plants (WRI)** (`wri-global-power-plants`, `raw.githubusercontent.com`) | dataset, csv, browser-direct | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | "World Resources Institute, Global Power Plant Database (2021)" | +| **West Virginia Statewide Imagery** (`wv-statewide-imagery`, `services.wvgis.wvu.edu`) | tiles, bbox, browser-direct; operator adds `wv-statewide-imagery` to `GEV_LIBRARY_ENABLE` | [Open — WV GIS Technical Center terms](https://wvgis.wvu.edu/) | "WV GIS Technical Center, West Virginia University" | + + + ## Bundled snapshots Static datasets shipped in the repo for an out-of-the-box experience. **None are MIT** — each keeps its own license (see the carve-out in [LICENSE](LICENSE)). Each folder also has its own provenance README. @@ -262,6 +412,7 @@ The [Bhote Koshi event pack](public/events/bhote-koshi-2026/README.md), under `p | **Datacenters** (4,352) | `datacenters/` | **ODbL 1.0** (OpenStreetMap extract) | ✅ (attribution + share-alike on data) | © OpenStreetMap contributors (shared credit) | | **Dams** (704) | `dams/` | **ODbL 1.0** (OpenInfraMap / OSM extract) | ✅ (attribution + share-alike on data) | © OpenStreetMap contributors (shared credit) + Open Infrastructure Map | | **Military area names** (36,466) | `osm_military_names/` | **ODbL 1.0** (OpenStreetMap, via Overture Maps) | ✅ (attribution + share-alike on data) | © OpenStreetMap contributors (shared credit) + Overture Maps Foundation | +| **Ukraine outline** (Rail layer no-positions rule; 1 ring, 7,801 points) | `src/data/railNoPositions.js` | **ODbL 1.0** (OpenStreetMap, via geoBoundaries gbOpen UKR ADM0, commit 9469f09; simplified to 0.0005°) | ✅ (attribution + share-alike on data) | © OpenStreetMap contributors (shared credit) + geoBoundaries | | **Québec CCTV source catalog** (1,120 locations) | `public/quebec-cameras.json` | Mixed: MTQ locations CC BY 4.0; Montréal camera nodes ODbL 1.0; scenic records retain per-record provenance. No video files are bundled or cached. | Location data is per-record; video remains hosted by Québec 511 and its platform terms apply; scenic source pages may have separate terms | MTQ / Données Québec CC BY 4.0; © OpenStreetMap contributors (ODbL); scenic operator and position source shown in the selected-camera panel | | **World camera image subset** (2,230 locations) | `config/cctv_sources.world-image-cameras.json` | Mixed: ODOT TripCheck public images (ODOT permits use with credit) and MLIT site content under terms compatible with CC BY 4.0. Frames are not bundled or persisted; the server holds a bounded in-memory cache. | Per-source terms apply; NZTA Journey Planner web-cache rows are excluded; Vegagerðin rows are served by the Iceland pack instead | Oregon Department of Transportation (Camera courtesy of ODOT) and Japan Ministry of Land, Infrastructure, Transport and Tourism (出典:国土交通省 川の防災情報) | | **TeleGeography Submarine Cable Map** (712 cables + 1,917 landing points) | `telegeography_submarine_cables/` | **CC BY-NC-SA 3.0** | ❌ **NonCommercial — remove for commercial use** | "© TeleGeography — submarinecablemap.com" | @@ -270,7 +421,9 @@ The [Bhote Koshi event pack](public/events/bhote-koshi-2026/README.md), under `p | **Natural Earth physical regions** (1,046 land + 292 marine named polygons) | `natural_earth/` | **Public domain** | ✅ (no restrictions) | "Made with Natural Earth" (courtesy credit — not legally required) | | **DataSF Analysis Neighborhoods** (41 SF neighborhood polygons) | `neighborhoods/` | **PDDL 1.0** (public domain) | ✅ (no restrictions) | "City & County of San Francisco — DataSF" (courtesy — not legally required) | | **Natural Earth countries, states and provinces** (260 admin-0/map units + 4,587 admin-1 polygons) | `natural_earth/` | **Public domain** | ✅ (no restrictions) | "Made with Natural Earth" (courtesy credit — not legally required) | +| **Natural Earth disputed areas** (11 of the source's 99 features, hand-picked; [list](src/data/local_data/natural_earth/README.md#disputed-areas-disputed_areasjson)) | `natural_earth/` | **Public domain** | ✅ (no restrictions) | "Made with Natural Earth" (courtesy credit — not legally required) | | **Natural Earth populated places** (7,342 points: name, position, rank) | `natural_earth/` | **Public domain** | ✅ (no restrictions) | "Made with Natural Earth" (courtesy credit — not legally required) | +| **Wikidata cities** (31,827 settlements of 15,000 people or more: name, position, population, country) | `wikidata_cities/` | **CC0 1.0** (public domain dedication) | ✅ (no restrictions) | "City, town and village names from Wikidata (CC0)" (courtesy credit — not legally required) | | **US Census Bureau counties** (3,235 county polygons) | `us_census_counties/` | **Public domain** | ✅ (no restrictions) | "U.S. Census Bureau" (courtesy — not legally required) | | **US Census Bureau places** (32,629 city, town and CDP polygons) | `us_census_places/` | **Public domain** | ✅ (no restrictions) | "U.S. Census Bureau" (courtesy — not legally required) | | **Who's On First neighborhoods** (61,441 polygons) | `wof_neighborhoods/` | Per source: CC BY, ODC-By, Open Government licences, CC0, PDDL, public domain (folder `ATTRIBUTION.md`) | ✅ (attribution) | "Neighborhood boundaries: Who's On First and contributors"; per-source credits in the folder | @@ -319,7 +472,7 @@ credits it anyway as `SPECS: CCTV-DATABASE.COM` beside any spec line it renders. ### Bundled OpenStreetMap data -Bundled OSM-derived data is distributed under [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/), separately from the MIT code: [datacenters](src/data/local_data/datacenters/), [dams](src/data/local_data/dams/) (via Open Infrastructure Map), [military names](src/data/local_data/osm_military_names/), and [OSM test fixtures](src/data/fixtures/). Keep © OpenStreetMap contributors and offer modified databases under ODbL. +Bundled OSM-derived data is distributed under [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/), separately from the MIT code: [datacenters](src/data/local_data/datacenters/), [dams](src/data/local_data/dams/) (via Open Infrastructure Map), [military names](src/data/local_data/osm_military_names/), the Rail layer's Ukraine outline in [`railNoPositions.js`](src/data/railNoPositions.js) (OpenStreetMap via geoBoundaries gbOpen, Runfola et al. 2020, simplified; the module's code stays MIT), and [OSM test fixtures](src/data/fixtures/). Keep © OpenStreetMap contributors and offer modified databases under ODbL. ### NASA FIRMS acknowledgement @@ -370,6 +523,20 @@ its width ("Sichuan, China · near Chengdu"), offline, with the states and provi the division. Public domain; credited "Made with Natural Earth" with the other packs. Rebuild: `node scripts/build-admin-packs.mjs --only places`; provenance in the folder README. +### Wikidata cities (`wikidata_cities/`) + +Settlements of 15,000 people or more that Wikidata states a population and coordinates for, +read once from the Wikidata Query Service by `scripts/build-wikidata-cities.mjs`: one row per +place with its English label, latitude and longitude to 3 decimals, largest stated population, +ISO 3166-1 country code and Wikidata id (31,827 places, 1.6 MB). The pack is read the +first time a place name is looked up and gives the nearest city, the places in view and a city +found by name (`findPlace`: "Paris, France", or the nearest namesake in view). Groupings of +settlements (metropolitan areas, agglomerations) and places that no longer stand are left out +unless they are also a living city. Names match without accents ("Sao Paulo" finds São Paulo). +CC0; credited "City, town and village names from Wikidata (CC0)" as a courtesy once a name from +the pack is shown. Rebuild: `node scripts/build-wikidata-cities.mjs`; provenance in the folder +README. The app never calls Wikidata itself. + ### Sky background (`sky/`) Sources, licences, the changes CC BY asks to state, hashes and build commands @@ -540,4 +707,4 @@ NOAA density imagery with the raw GLM product. ## In-app attribution -The required Google Maps / Cesium credit renders on the on-globe credit line (`#cesium-credits`, bottom-left) and must stay visible — including in clean-view and recording modes (the whole line, logo + "Google Maps" + the "Data attribution" link, stays on screen; only the GEV panels/HUD fade). The layer-specific credits (adsb.lol, adsbdb, Planespotters.net, TeleGeography, OSM datacenters/dams/roads, NASA FIRMS, CelesTrak, USGS, City of Austin, Fintraffic, GBFS, Radio Browser, OpenSky, AISStream) are registered into the expandable **"Data attribution"** popover on that credit line via `viewer.creditDisplay.addStaticCredit(new Cesium.Credit(html, /* showOnScreen */ false))` — see `src/data/dataCredits.js`. When you add a new data source, add its license and attribution to this file **and** append an entry to `DATA_CREDITS` in `src/data/dataCredits.js` so it surfaces in the app. +The required Google Maps / Cesium credit renders on the on-globe credit line (`#cesium-credits`, bottom-left) and must stay visible — including in clean-view and recording modes (the whole line, logo + "Google Maps" + the "Data attribution" link, stays on screen; only the GEV panels/HUD fade). The layer-specific credits (adsb.lol, adsbdb, Planespotters.net, Open Vessel Photos, TeleGeography, OSM datacenters/dams/roads, NASA FIRMS, CelesTrak, USGS, City of Austin, Fintraffic, GBFS, Radio Browser, OpenSky, AISStream) are registered into the expandable **"Data attribution"** popover on that credit line via `viewer.creditDisplay.addStaticCredit(new Cesium.Credit(html, /* showOnScreen */ false))` — see `src/data/dataCredits.js`. When you add a new data source, add its license and attribution to this file **and** append an entry to `DATA_CREDITS` in `src/data/dataCredits.js` so it surfaces in the app. diff --git a/LICENSE b/LICENSE index 4f01699a2a..86483f2d6d 100644 --- a/LICENSE +++ b/LICENSE @@ -56,7 +56,6 @@ In short: the MIT grant does not extend to any third-party data. See DATA_SOURCES.md for the full per-source license + attribution summary, and remove any dataset whose terms don't fit your use. -The 3D models under public/models/ are also third-party works and are NOT -licensed under MIT. They remain under their individual licenses. See -public/models/README.md for the author, source, license, modification notice, -and attribution covering each model file. +The 3D models under public/models/ are the project's procedural fleet +models, generated from code by the project maintainers, and are covered by +the MIT license above like the source code. See public/models/README.md. diff --git a/README.md b/README.md index fa9749edf5..dce218cccb 100644 --- a/README.md +++ b/README.md @@ -2,29 +2,25 @@ # 🌐 God's Eye View -[![CI](https://github.com/bilawalsidhu/gods-eye-view/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bilawalsidhu/gods-eye-view/actions/workflows/ci.yml) [![Reached #1 on GitHub Trending](https://img.shields.io/badge/%231_GitHub_Trending-thank_you!-F0A63C?style=flat-square&logo=github)](https://x.com/bilawalsidhu/status/2093798887815348521) +**Official site: [godseyeview.ai](https://godseyeview.ai)** · [Download](https://godseyeview.ai/download/) · [Guide](https://godseyeview.ai/guide/) · [Releases](https://godseyeview.ai/releases/) · [Hosted version waitlist](https://godseyeview.ai/online/) · [Media](https://godseyeview.ai/press/) -### A spy-satellite simulator in your browser — then you realize the sources are public and the data is real. +[![CI](https://github.com/bilawalsidhu/gods-eye-view/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bilawalsidhu/gods-eye-view/actions/workflows/ci.yml) [![Reached #1 on GitHub Trending](https://img.shields.io/badge/%231_GitHub_Trending-thank_you!-F0A63C?style=flat-square&logo=github)](https://www.star-history.com/?type=date&repos=bilawalsidhu%2Fgods-eye-view) [![GitHub stars](https://img.shields.io/github/stars/bilawalsidhu/gods-eye-view?style=flat-square&color=4fe3ff)](https://github.com/bilawalsidhu/gods-eye-view/stargazers) [![MIT License](https://img.shields.io/badge/license-MIT-4fe3ff?style=flat-square)](LICENSE) -Photorealistic 3D globe. Live aircraft, ships, satellites, earthquakes, traffic, and public cameras. Hands-free voice control powered by a realtime AI agent. +### A spy-satellite simulator in your browser. Except the data is real. -_No place left behind._ +_The window through which we see our world._ -![Orbital HUD, a tracked live globe, FLIR terrain — then OPEN SOURCED](docs/media/hero-open-source-reveal.gif) +[![God's Eye View: a live 3D globe indexing the planet's public signals](docs/media/site/hero.webp)](https://godseyeview.ai) - - The God's Eye View video series on YouTube - +Click any satellite, plane, ship or public camera and you can track it. Turn on FLIR mode and suddenly you're wondering, holy crap, is this real? And it's free, and open source. -▶️ **From the project behind the viral God's Eye View series** _(formerly WorldView)_ — [5M+ on YouTube](https://youtube.com/playlist?list=PL6qSg2I-7_koPbDnSMo0QeeHX_RknA2uv&si=nBGYMoHWQw41v93Q) · [25M+ across socials](https://www.google.com/search?q=god%27s+eye+view) +**[One-click install with Pinokio](https://pinokio.co/apps/github-com-bilawalsidhu-gods-eye-view)** · **[Run it from the terminal](#-quick-start)** · **[Hosted version waitlist](https://godseyeview.ai/online/)** -🏆 **Reached #1 on GitHub Trending, daily and weekly · August 2026** +🏆 **#1 on GitHub Trending**, daily and weekly · **[#8 Product of the Day](https://www.producthunt.com/products/god-s-eye-view?launch=god-s-eye-view)**, hunted by Chris Messina · _“pretty cool”_ — [Brendan Eich](https://x.com/BrendanEich/status/2094592096401490266), creator of JavaScript · Featured on **[Pinokio](https://pinokio.co/posts/01m1m4p9xxm3qw7dnnpj2wr93g)** -**[#8 Product of the Day](https://www.producthunt.com/products/god-s-eye-view?launch=god-s-eye-view)** · Hunted by Chris Messina, creator of the hashtag +▶️ **From the project behind the God's Eye View series** _(formerly WorldView)_ — [25M+ views on YouTube](https://youtube.com/playlist?list=PL6qSg2I-7_koPbDnSMo0QeeHX_RknA2uv&si=nBGYMoHWQw41v93Q) -_“pretty cool”_ — [Brendan Eich](https://x.com/BrendanEich/status/2094592096401490266), creator of JavaScript and co-founder of Mozilla and Brave · Featured on **[Pinokio](https://pinokio.co/posts/01m1m4p9xxm3qw7dnnpj2wr93g)** - -⚡ **Start without API keys.** Install with [Pinokio](https://pinokio.co/apps/github-com-bilawalsidhu-gods-eye-view) or run locally from the terminal. Add optional keys inside the app. **[→ Quick Start](#-quick-start)** +**As seen on** [Matt Wolfe](https://www.youtube.com/watch?v=S2VJU5DQqlU) · [Riley Brown](https://www.youtube.com/watch?v=NR_GMq2lDCE) · [Digg](https://digg.com/tech/r7whv988) · [The Escapist](https://www.escapistmagazine.com/news-gods-eye-view-spy-satellite-simulator-setup-focus-keyphrase-gods-eye-view/) · [UNILAD Tech](https://www.uniladtech.com/social-media/youtube/viewers-concerned-youtubers-safety-built-gods-eye-monitor-889810-20260309) · [Al Jazeera](https://www.aljazeera.com/video/the-stream/2026/3/8/how-do-you-track-a-war-in-real-time) · [NDTV](https://www.ndtv.com/video/strait-of-hormuz-news-hormuz-stranglehold-no-end-in-sight-1080351) · [Mojo Story](https://www.youtube.com/watch?v=UXkJjyFfrwc) · [all media](https://godseyeview.ai/press/) @@ -32,7 +28,7 @@ _“pretty cool”_ — [Brendan Eich](https://x.com/BrendanEich/status/20945920
-**[Quick Start](#-quick-start) · [First Five Minutes](#-the-first-five-minutes) · [Talk to It](#-talk-to-it) · [What's Live](#-whats-on-the-globe) · [Under the Hood](#-under-the-hood) · [Keys & Costs](#-api-keys) · [Contributing](CONTRIBUTING.md)** +**[Quick Start](#-quick-start) · [What It Does](#️-what-this-thing-does) · [First Five Minutes](#-the-first-five-minutes) · [Talk to It](#️-talk-to-it) · [What's Live](#️-whats-on-the-globe) · [Keys & Costs](#-api-keys) · [Contributing](CONTRIBUTING.md)**
@@ -56,11 +52,41 @@ Start with the included data sources, then add your own. Each layer is a separat ## 🎛️ What This Thing Does +The world is already broadcasting. We fuse it together into a 3D globe for you and your agents. + +We've got a plurality of sensor systems watching the planet right now. Satellite imagery, flights, ships, weather, public cameras. Each captures a sliver of what's happening. God's Eye View pulls that treasure trove of public data into a single picture. + + + + + + + + + + + + + + + + + + + + + + +
Ask the planet in God's Eye View
Ask the planet
Use voice to ask the planet questions in natural language, and it annotates the 3D globe with the answer.
Flights and vessels in God's Eye View
Flights and vessels
Click on a satellite, plane, ship or public camera and you can track it.
Satellites in God's Eye View
Satellites
Toggle on different kinds of satellites, everything from GPS to Starlink.
Public cameras in God's Eye View
Public cameras
Some layers, like traffic and camera poses, are estimates, and the app says so.
Cockpit in God's Eye View
Cockpit
Visualize a flight from the third-person perspective and jump into a rendered cockpit view.
World class weather in God's Eye View
World class weather
Clouds, rain radar, lightning density and cyclone tracks with forecast cones. And since we say 4D, you can scrub the cloud imagery backwards in time.
Recent imagery in God's Eye View
Recent imagery
Draw a bounding box around a fire and it'll retrieve the Sentinel-2 images, draped on the 3D terrain. All keyless, ladies and gentlemen.
Transit in God's Eye View
Transit
Click a bus in Boston and it starts leaving a trail. This might be the most overkill way to track your bus.
RF and SDR support in God's Eye View
RF and SDR support
Now you can connect your own SDR and visualize everything you're detecting. The SDR nerds know all the other possibilities.
World radio in God's Eye View
World radio
Ask for radio near anywhere and the globe starts broadcasting. Drag the tuner across up to 750 stations.
MCP server in God's Eye View
MCP server
We've built MCP access so your agents can query the same picture and add their findings to a shared canvas.
Director Mode in God's Eye View
Director Mode
Draw outlines, sketch paths, drop your annotations on the map.
+ +
+Everything else it does + - **🛩️ Cockpit view:** Ride inside a tracked flight — the camera holds the terrain under you all the way down. - **📡 Contacts:** A 250 km roster of everything near your target — step through live aircraft and drop into any cockpit. - **🎯 Click-to-track anything:** Camera locks on, draws a fading trail, surfaces full metadata — and a tracked fire or vessel hands you off to the nearest live camera in one click. - **🖊️ Voice whiteboard:** Speak annotations onto the world — real boundary polygons, marks, and routes. -- **🛫 3D hangar:** Real per-class aircraft models — 787, ATR-72, Citation, Bell 206, MQ-9 — and a tracked contact swaps from glyph to 3D model as you close in. +- **🛫 3D fleet:** 122 procedural models drawn life size by type — airliners, business jets, helicopters, drones, ships, buses, trams and trains — and every contact within 3 km of the camera swaps from glyph to its 3D model. - **🎨 Reskin reality:** GLSL sensor looks over the normal globe — CRT, NVG, FLIR/thermal, Noir. - **🟩 Detection overlay:** Screen-space bounding boxes and IDs on everything in view. - **🎖️ Military HUD:** Tactical heads-up display with intelligence-style telemetry. @@ -77,6 +103,8 @@ Start with the included data sources, then add your own. Each layer is a separat - **📦 Shareable scenes:** Import, preview and share Director scenes as files or bundles, with camera anchors, authored moves and data packs. - **🌊 Nepal flood scene:** Replay the Bhote Koshi flood: flood path, witness sources and before-and-after imagery (bundled data is non-commercial; see [DATA_SOURCES.md](DATA_SOURCES.md)). +
+ ---
@@ -156,7 +184,8 @@ See [docs/PERFORMANCE.md](docs/PERFORMANCE.md). **macOS shortcut:** `./scripts/dev-fresh.sh` clears the Vite cache and pulls any configured keys straight from the Keychain. It starts keyless too. -### Path 3 — Docker +
+Path 3 — Docker No Node install needed; the container publishes the same dev server. @@ -212,7 +241,7 @@ Keep the `env`: bash treats `UID` as read-only, so a plain `UID=1026` in front o On SELinux hosts (Fedora, RHEL), compose mounts the checkout with `:z` so the container may read it; Docker may relabel the checkout for container access, which can take a moment on a large checkout. Without that, the start fails with `Cannot find module '/app/scripts/docker-start.mjs'`. -Behind a reverse proxy, put your keys in `.env` or pass them as environment variables - Provider Settings refuses proxied requests on purpose - and add the hostname you serve it on, for example `GEV_ALLOWED_HOSTS=globe.example.lan` (see [Sharing an instance](#-sharing-an-instance)). The map routes compare the browser's `Origin` with the `Host` the server sees, so the proxy must pass the original `Host` and, when it terminates TLS, `X-Forwarded-Proto`. Caddy does both by default; for nginx add `proxy_set_header Host $http_host;`, `proxy_set_header X-Forwarded-Proto $scheme;` and `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`. On an install outside Docker, that forwarding header also rate-limits the proxy's users apart from your own browser. Under the default Docker bridge network every client on the host, your browser included, reaches the container from its gateway address and shares one Overpass bucket. +Behind a reverse proxy, put your keys in `.env` or pass them as environment variables - Provider Settings and the News layer refuse proxied requests on purpose - and add the hostname you serve it on, for example `GEV_ALLOWED_HOSTS=globe.example.lan` (see [Sharing an instance](#-sharing-an-instance)). The map routes compare the browser's `Origin` with the `Host` the server sees, so the proxy must pass the original `Host` and, when it terminates TLS, `X-Forwarded-Proto`. Caddy does both by default; for nginx add `proxy_set_header Host $http_host;`, `proxy_set_header X-Forwarded-Proto $scheme;` and `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`. On an install outside Docker, that forwarding header also rate-limits the proxy's users apart from your own browser. Under the default Docker bridge network every client on the host, your browser included, reaches the container from its gateway address and shares one Overpass bucket.
@@ -234,10 +263,13 @@ the container. -### Path 4 — GitHub Codespaces (cloud, no local install) + -Codespaces requires a GitHub account. Overpass queries and OpenAI voice token -requests return HTTP 403 through its forwarded HTTPS URL, even with API keys +
+Path 4 — GitHub Codespaces (cloud, no local install) + +Codespaces requires a GitHub account. Overpass queries, the News layer and OpenAI +voice token requests return HTTP 403 through its forwarded HTTPS URL, even with API keys in `.env` and `GEV_ALLOWED_HOSTS` configured. Use a local setup for these features. The codespace runs the dev server in a cloud workspace, so Node and the dependencies @@ -272,6 +304,8 @@ wider-publish case in [Sharing an instance](#-sharing-an-instance). Provider Settings is unavailable on the forwarded URL. Never commit your workspace `.env`. [SECURITY.md](SECURITY.md) has the threat model. +
+ ### Then power it up — in the app, not in a file For a local setup, keys are upgrades, not prerequisites. When you want one, @@ -314,54 +348,30 @@ and it carries the LAN-sharing rules alongside [Keys & Costs](#-api-keys). ## 🕐 The First Five Minutes -Choose a first-run mission, or try these in order. The GIFs show Google Photorealistic 3D; your starting basemap depends on the keys you've added. +Choose a first-run mission, or try these in order. Your starting basemap depends on the keys you've added. 1. **Light up the sky.** Take the **Live Contacts** mission (or turn on **Flights** yourself) — thousands of live aircraft, gliding on real telemetry, detection mesh already reading the scene. Click one: the camera locks on, a trail draws behind it, and its live telemetry card comes up. 2. **Take the controls.** Hit **COCKPIT** on your tracked plane and ride it down, switching sensors mid-flight: NVG into Ironbow FLIR. -![Riding with a live aircraft in cockpit view while switching sensor modes](docs/media/06-cockpit-ar.gif) - 3. **Drop into a busy airport.** Search one and descend to the taxiways with **3D** aircraft on — grounded contacts, taxi trails, the whole apron working in real time. -![Moving from a full airport overhead down to close taxiway inspection with 3D flight models](docs/media/start-here/airport-ground-traffic-google-3d.gif) - 4. **Look through a public camera.** Turn on **Cameras** over Austin, London, California, Finland, or Delaware (live video). The feeds aren't webcam embeds — they project _into_ the 3D city. Cycle coverage to **VIEWSHED** and every camera draws its estimated coverage volume — where it reaches, and where it goes blind. -![Diving into an Austin intersection with a live public camera projected into the 3D scene](docs/media/03-austin-cctv.gif) - 5. **Track something in orbit.** Turn on **Satellites** and click the ISS — you ride along at orbital distance, orbit ring and all. -![Tracking the ISS along its orbital path as it crosses over Ukraine](docs/media/14-iss-over-ukraine.gif) - 6. **Switch the optics.** Tap `1`–`6` — CRT, NVG, FLIR — and the whole live planet re-renders through a different sensor. -![Cycling a dense live globe through CRT, FLIR, and NVG in one continuous view](docs/media/01-style-sweep.gif) - 7. **Talk to it** _(needs an OpenAI key)_: _"Take me to LAX and select the nearest airborne aircraft."_ 8. **Come home.** Hit **Reset Globe** — or just say _"zoom out to a globe view."_ **Keyboard:** `1`–`6` visual styles · `H` HUD · `D` detection · `C` CCTV · `` ` `` frame rate · `Esc` out. Trackpad pinch zooms the globe. --- - -## 🛩️ The Cockpit - -> Every plane should let you do this. - -Real-time cockpit mode, built from live flight data: the camera rides your contact with real terrain holding underneath, all the way down — sensor styles come along for the ride, and **Contacts** keeps the 250 km roster one click away: jump plane to plane and fall straight into the next cockpit. - -![Jumping between live aircraft and falling straight into a cockpit view](docs/media/12-switch-aircraft-cockpit.gif) - -The cockpit even carries its own briefing strip: nearby live signals, regional headlines, and real local weather — with an opt-in **WX** mode that renders volumetric clouds from actual observations around your aircraft. - -![A live military contact ridden through Normal, NVG, and Ironbow FLIR with dense detection](docs/media/start-here/military-cockpit-dense-google-3d.gif) - -_Why cockpit mode exists: you're riding a real aircraft over real terrain — and you get to pick which sensor you see the world through._ - ---- - ## 🎙️ Talk to It +
+Providers, chat, ChatGPT OAuth and the voice check + The standalone app offers **OpenAI** and **Gemini** under **AI Provider** in Settings, one choice shared by voice and chat. OpenAI is the initial default; your choice is saved in this browser. To use Gemini, add `GEMINI_API_KEY` in Provider Settings or your local `.env` file, then select Gemini. `GEMINI_LIVE_MODEL` defaults to `gemini-3.8-live`. The permanent key stays on the local server, which issues a constrained, single-use session credential. Changing provider ends the current conversation. If voice is on, the new provider starts with the same open-mic or push-to-talk mode; a held Space key is not carried over. Gemini uses the same map actions and captions, but has no OpenAI cost meter or MINI tier. When Gemini reports that its session has expired, start voice again for a new conversation. The AI Provider setting does not change the OpenAI-backed AI HUD summary. @@ -376,6 +386,8 @@ GEV reads Codex's file credentials but does not write or refresh them. It checks For a live voice check, run `node scripts/qa-voice-auth.mjs http://127.0.0.1:4189 oauth microphone.wav` against your local dev server. Use a WAV with three seconds of leading silence followed by a short spoken reply request. Replace `oauth` with `api-key` to check the API-key path. The check verifies audio input, a completed spoken reply, usage, resource cleanup, and reconnect. It saves screenshots and credential-free results under `.gev-logs/voice-auth/`. +
+ Click **GEV MIC**, grant the microphone, and just talk. This is more than a voice-controlled remote: - **🧠 It knows what it's looking at.** The agent pulls live scene context before answering — including coordinates, street names, active layers, and view scale. Ask _"what city is this?"_ mid-flight and it knows. @@ -384,7 +396,7 @@ Click **GEV MIC**, grant the microphone, and just talk. This is more than a voic - **🎬 Cinematic framing.** _"Show me the planes overhead"_ pulls the camera back, angles it, and frames the live traffic like a director. - **🔒 Honest and secure.** The agent only confirms actions that succeeded. Your `OPENAI_API_KEY` never touches the browser; the client only gets a short-lived session token. If you choose **USE CHATGPT OAUTH** in Provider Settings, the local server uses that sign-in only to mint the same kind of short-lived Realtime credential, and refuses the OAuth path for non-loopback clients. -Thirty tools, four jobs — the commands below come straight from the product's voice test suite and tool playbook: +Thirty-five tools (thirty-four unless an Overpass server is set), four jobs — the commands below come straight from the product's voice test suite and tool playbook: **🎥 Direct it** — drone-operator camera verbs: @@ -400,10 +412,6 @@ camera input stops rotation. **✍️ Or draw it yourself** — UTILITIES ▸ **Draw**: pick Area, Line or Pin and a colour, click the vertices on the real world, double-click to finish, then name, recolour, hide or fly to each shape from its row. Same whiteboard, same persistence, no microphone needed. -![Zilker Park and Lady Bird Lake drawing onto the 3D city as persistent vector annotations, by voice](docs/media/01-voice-annotate-zilker.gif) - -![A spoken distance measurement spanning an airport, inspected from orbit](docs/media/04-airport-distance.gif) - **🔎 Interrogate it** — analyst queries against the live layers: > 🗣️ _"How many flights are over Texas right now?"_ · _"Which ships are headed to Oakland?"_ · _"What is the biggest fire near Los Angeles?"_ · _"Is anything flying above forty thousand feet?"_ · _"When does the ISS pass over next?"_ · _"How many datacenters are in view?"_ @@ -416,17 +424,16 @@ camera input stops rotation. > 🗣️ _"Show me global infrastructure."_ (stages the layers and pulls back to the globe) · _"Play Orbital Watch."_ (a full cinematic scene) · _"Set detection density to fifty percent."_ · _"Next contact — helicopters only."_ (mid-cockpit) · _"Show me space missions."_ · _"Switch to OSM."_ · _"Sharpen the image a touch."_ · _"Switch to the tactical layout."_ · _"What's turned on right now?"_ -![The globe populating with the world's radio stations as another live layer](docs/media/15-global-radio-layer.gif) - -_Ask for radio near anywhere and the globe starts broadcasting — every station is a real place you can fly to._ - --- **💬 Or ask from Claude and Codex.** God's Eye View is also an MCP server: ask Claude Desktop, Codex or ChatGPT desktop to show a place, and the live globe opens right in the conversation. Setup takes a minute — see [docs/MCP_SETUP.md](docs/MCP_SETUP.md). ## 🛰️ What's on the Globe -Twenty-two layers and map sources. **Twenty have a keyless path.** Some offer additional capabilities with a provider key. (🟢 no key · 🟡 free key · 🔴 metered.) +Twenty-three layers and map sources. **Twenty-one have a keyless path.** Some offer additional capabilities with a provider key. (🟢 no key · 🟡 free key · 🔴 metered.) + +
+All twenty-three layers and map sources, with sources and keys | Layer | What you get | Source | Auth | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | @@ -438,13 +445,15 @@ Twenty-two layers and map sources. **Twenty have a keyless path.** Some offer ad | 🚢 **Live Vessels** | Thousands of ships worldwide | AISStream | 🟡 | | 🛰️ **Satellites** | About 1,300 objects in six classes (Stations, Imaging, Telecom, Starlink, Probes, Debris) with a toggle and a live count each; Starlink loads its whole shell | CelesTrak | 🟢 | | 🌍 **Earthquakes** | Global seismic activity, last 24h | USGS | 🟢 | +| 📰 **News** | The last 24 hours of news in the right-rail **NEWS** panel, narrowed to 12, 6, 3 or 1 hours, with picture cards and clips. **Conflicts**: physical violence worldwide from GDELT's event files, one report per story at GDELT's place for it, plus Liveuamap's mapped items with a key. **Local**: the news of the country at the view centre, its outline and name on the globe; a disputed area of the bundled list, or a territory without a country code, is named as itself. Places and categories are machine-coded and can be wrong | GDELT · Liveuamap · World News API, or your own news server | 🟢 Conflicts · 🟡 Local (World News API) · 🔴 Liveuamap items | | ◍ **Air quality** | Live AQHI on the published 1–10+ health-risk scale, with a Weather-panel card showing the band legend and the highest readings in view. **Canada only** — ECCC is the first registered provider | ECCC MSC GeoMet | 🟢 | | 🚗 **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** | up to 7,350 camera locations (4,000 shared round-robin slots, plus room for 1,120 Québec and 2,230 World image cameras) projected _into_ the 3D space — Austin · Texas (TxDOT) · California (Caltrans) · London (TfL) · Ontario (511, free developer key) · Ottawa (City of Ottawa, free access certificate) · Finland (Fintraffic) · British Columbia (DriveBC) · Estonia (Tallinn, Tarktee) · Delaware (DelDOT live video) · New South Wales (Live Traffic NSW) · Calgary · Norway (Statens vegvesen) · Toronto · King County (WA) · Washington (WSDOT) · Catalonia (Servei Català de Trànsit) · Iceland (Vegagerðin) · Hong Kong (Transport Department) · Taiwan (Freeway Bureau, MOTC) · Québec (MTQ locations with Québec 511 links, Montréal locations, regional webcams) · Oregon (TripCheck) · Japan (MLIT river cameras) · Italy (A22 Brennero motorway), plus opt-in New York City (NYC DOT TMC, needs your own NYC DOT agreement), opt-in Lithuania (Via Lietuva / Eismoinfo, photo licence unconfirmed), opt-in Québec 511 in-browser video (embedding terms unconfirmed), opt-in Florida (FL511, individual personal use only; other use needs FDOT's written consent) and opt-in Houston (TranStar, enable only with TxDOT's written permission per TranStar's Content Usage terms). Positions are published or attributed; poses are estimated priors **you calibrate by dragging a gizmo on the camera itself** | City APIs | 🟢 | | 📷 **Mapped ALPR Cameras** | License-plate-reader camera locations tagged by OpenStreetMap contributors, loaded one city-sized view at a time, with **SHOW NEAREST**. Locations and tags only: no plate data, no video | OpenStreetMap (incl. DeFlock mapping) | 🟢 | | 📷 **Street Level** | Street-level photos behind one panel, one chip per provider: coverage on the streets, image cones, an embedded viewer with full-screen **EXPAND**. Mapillary, Google Street View, KartaView and Panoramax | Mapillary · Google · KartaView · Panoramax | 🟢 KartaView, Panoramax · 🟡 Mapillary token · 🔴 Google Maps key | | 📻 **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, Rio de Janeiro (buses and BRT), Szczecin, Lisbon (Carris Metropolitana and the city’s Carris), Prague, Warsaw, Kraków, Poznań, Gdańsk, Rzeszów, Vilnius, Bucharest, Cluj-Napoca, Iași, Rome, Turin, Venice (buses and waterbuses), Bordeaux, Montpellier, Rouen, Toulon, Le Havre, Tours, Málaga, Sendai, Johor Bahru, Kota Bharu, Adelaide, Atlanta, Denver, Edmonton, Halifax, Victoria, and nine in Ontario: Toronto (surface vehicles; the subway publishes no positions), Mississauga, Hamilton, Durham Region, York Region, Guelph, Burlington, Barrie and Kingston | Operator GTFS-Realtime feeds | 🟢 | +| 🚌 **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, Cairns, Rio de Janeiro (buses and BRT), Szczecin, Lisbon (Carris Metropolitana and the city’s Carris), Prague, Warsaw, Kraków, Poznań, Gdańsk, Rzeszów, Vilnius, Bucharest, Cluj-Napoca, Iași, Rome, Turin, Venice (buses and waterbuses), Bordeaux, Montpellier, Rouen, Toulon, Le Havre, Tours, Málaga, Sendai, Johor Bahru, Kota Bharu, Adelaide, Atlanta, Denver, Edmonton, Halifax, Victoria, and nine in Ontario: Toronto (surface vehicles; the subway publishes no positions), Mississauga, Hamilton, Durham Region, York Region, Guelph, Burlington, Barrie and Kingston | Operator GTFS-Realtime feeds | 🟢 | +| 🚆 **Rail** | Live trains across the US, Canada, Australia, Ireland, Finland, Spain, Norway, Malaysia, Japan and France, from 30 keyless operator feeds: live GPS positions from 29 of them and Irish Rail’s station reports, 28 live out of the box, and Renfe long and medium distance and KTMB once their pack is built. No train is placed from a timetable. Opt-in packs (`node scripts/build-rail-paths.mjs --feed ` or `--all`) add the operator’s own route lines, stop names, next stops and trip-update delays. Coloured by service category (urban, local, regional, national, international) with a filter chip and legend for each; trains are drawn once when several feeds carry them, and open a card per train. Buses in mixed feeds are dropped by the server | Operator GTFS-Realtime feeds (static GTFS for opt-in packs) | 🟢 | | 🚲 **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) | 🟢 | | ⌖ **OSM Places** | Voice place search ("hospitals in Kathmandu") from OpenStreetMap, drawn as numbered points that follow-up questions can filter. Needs your own Overpass server (`OVERPASS_UPSTREAMS`); off otherwise | @@ -457,6 +466,8 @@ Twenty-two layers and map sources. **Twenty have a keyless path.** Some offer ad | 🌦️ **Observed Weather** | Rain radar (contiguous US), Satellite clouds (GOES regional or global infrared, Clouds only or Full image) and Lightning density (Americas and Pacific) on one history timeline | NOAA nowCOAST | 🟢 | | 🌀 **Cyclones** | Advisory positions, forecast tracks and uncertainty cones for the Atlantic and eastern/central North Pacific | NOAA NHC / CPHC | 🟢 | +
+ **Weather, keyless.** **Wind** animates 10 m forecast flow from NOAA GFS or ECMWF IFS, with an optional color field and a reading at map center. **Rain radar**, **Satellite clouds** and **Lightning density** are observations on one history timeline in the **WEATHER** panel (step back, **Play**, **Latest**); **Cyclone advisories** draw NHC and CPHC positions, forecast tracks and cones. On Google 3D Tiles the observed layers float above the city as translucent shells, sharpened around your view. In the app, **Data Layers** groups them as Movement, Cameras, Infrastructure, Events, Weather and Audio; Directions and OSM Places sit in the separate **Utilities** panel with Draw and Import. @@ -469,20 +480,17 @@ In the app, **Data Layers** groups them as Movement, Cameras, Infrastructure, Ev | 🟡 A free Cesium ion token | **Google Photorealistic 3D cities** and world terrain — eligible personal, non-commercial use; current ion terms and quotas apply | | 🔴 A Google Maps key | The same 3D direct from Google, plus Google place search — the billing-enabled, metered route | -![A reconstructed Falcon 9 ascent climbing and curving into its projected orbit](docs/media/08-falcon9-replay.gif) - -_The Space Missions layer replaying a Falcon 9 ascent — labeled `RECONSTRUCTED ESTIMATE`, scrubbable 0.25×–4×._ - **Also on the globe:** neighborhood overlays · an optional cockpit WX cloud effect. **Bundled static infrastructure:** Datacenters (4,352), Dams (704), and Submarine Cables (712). -![Diving into the Bahamas and revealing labeled submarine cable routes beneath the globe](docs/media/09-undersea-cables.gif) - **Missing a layer you want?** Open an issue — or add it and send the PR. --- ## 📷 Street Level +
+Street Level setup and use + > Street-level photos from any provider in one panel. This build ships **Mapillary** (a free client token), **Google Street View** (your Google Maps key), **KartaView** and **Panoramax** (no key). **Setup.** At [mapillary.com/dashboard/developers](https://www.mapillary.com/dashboard/developers), register an application with **Read** access and copy its **Client Token** (`MLY|…`). Paste it into **POWER UP → Mapillary**, or set `MAPILLARY_CLIENT_TOKEN` in `.env` and restart. Without it Street Level starts on **KartaView** instead, and the Mapillary chip says which key to add. **Google Street View** uses `GOOGLE_MAPS_API_KEY` with the **Maps JavaScript API** enabled for it in Google Cloud; its chip starts off, since every panorama is billed to the key. **KartaView** and **Panoramax** need nothing: their public APIs are keyless. @@ -491,37 +499,26 @@ _The Space Missions layer replaying a Falcon 9 ascent — labeled `RECONSTRUCTED Share links carry the provider switches and filters (`0.m.0` Mapillary off, `0.m.0_0.r.google-1` Street View on, `0.m.0_0.r.google-0*kartaview-1*panoramax-0` KartaView on and `0.m.0_0.r.google-0*kartaview-0*panoramax-1` Panoramax on, as the app writes them (`0.m.0_0.r.kartaview-1` and `0.m.0_0.r.panoramax-1` work too; a link that leaves out `m` keeps Mapillary, the default, lit), `0.p.p` panoramas only, `0.s.365` the last year). To add a provider, implement the contract in `src/layers/streetLevel/registry.js` and register it in `src/app/layers/streetLevel.js`. -## 🎖️ Field Missions +
-Once the basics click, run these: +## 🎬 Reconstructions and the Series -| Mission | How | -| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **🚁 Ask the planet** | _"Why are all these military helicopters flying in circles?"_ Select a military track — it silently backfills ~24 h of real trace history — and see what it's been doing, resolved as stacked 3D loops. | -| **✈️ Final approach** | Click-track an airliner lining up for a runway, hop into the **cockpit**, and ride it down. | -| **🌃 Night watch** | Fly to your own city, switch to **NVG**, and let the detection mesh and HUD read the scene. | -| **🚢 Port call** | Vessels on over the Port of Long Beach. Click a tanker for its tactical card and wake trail — then hit **NEAREST** in the CCTV panel and look at the same water through a public camera. | -| **📻 Tokyo FM** | Orbit Shibuya with the **Radio** layer on — then drag the analog tuner needle: every position snaps to a real station and the globe flies to whoever's broadcasting. | -| **🔥 Fire line** | FIRMS over California. Click a detection — the camera dives to it — read the intensity, then hit **NEAREST** in the CCTV panel for a ground view. | -| **🚶 Ask for a walking route** _🎙️_ | Tell the world where you want to go and watch a real street-following route trace itself through the 3D city — then _"fly it"_: banked turns, eased ends, a camera that leads the path like a drone shot. | -| **📏 Measure LAX to DFW** _🎙️_ | _"How far is LAX from DFW?"_ — an arrow spans the country, the distance lands in the caption, and the endpoints stay pinned to the real world as you orbit. | -| **🚀 Launch replay** | Open **Space Missions**, pick a launch from the last 30 days, and ride the T-minus countdown through ascent to orbit — scrub it at 0.25×–4×. Labeled `RECONSTRUCTED ESTIMATE`, because it is one. | -| **🪦 Walk the boneyard** | Fly from regional context down into dense, fully resolved rows of retired aircraft. | -| **🏗️ Orbit Three Gorges** | Sweep the dam and its terrain at a glance — then flip on the **Dams** layer and find 703 more. | +This started as a mad science experiment that suddenly blew up. Next thing you know, Iran happened. Bilawal reconstructed it in 4D. The questions we kept getting: when can I use this thing, and can I bring my own data to the party? -_🎙️ = voice missions — they need an OpenAI key._ + + + + + + + + + + + +
God's Eye View Blew Up. Here's What You Can Do With It.
God's Eye View Blew Up. Here's What You Can Do With It.
3.1M views on YouTube
I Built God's Eye View to Monitor Iran in 4D
I Built God's Eye View to Monitor Iran in 4D
1.9M views on YouTube
We Got Open Source God's Eye Before GTA 6
We Got Open Source God's Eye Before GTA 6
1.2M views on YouTube
Florida Learjet Crash - Final 78 Seconds Reconstructed in God's Eye View
Florida Learjet Crash - Final 78 Seconds Reconstructed in God's Eye View
3.5M views on YouTube
God's Eye View Reveals Iran's Chokehold on the Global Economy
God's Eye View Reveals Iran's Chokehold on the Global Economy
700K views on YouTube
God's Eye View Just Got a Massive Upgrade (Thanks To You!)
God's Eye View Just Got a Massive Upgrade (Thanks To You!)
502K views on YouTube
-![Resolving a selected aircraft's recent flight path into stacked 3D loops above the terrain](docs/media/07-helicopter-loops.gif) - -_Ask the planet: a military contact's last ~24 hours of real trace history, resolved as stacked 3D loops._ - -![Asking for a walking route and flying the generated path through the 3D city](docs/media/10-walking-route-flythrough.gif) - -_"Draw the walking route… now fly it" — banked turns, eased ends, the camera leading the path like a drone shot._ - -![Descending from regional context into dense rows of retired aircraft at the boneyard](docs/media/08-boneyard.gif) - -_Walk the boneyard: rows of retired airframes, fully resolved in 3D._ +More reconstructions, interviews and press: [godseyeview.ai/press](https://godseyeview.ai/press/) · [the full series on YouTube](https://youtube.com/playlist?list=PL6qSg2I-7_koPbDnSMo0QeeHX_RknA2uv&si=nBGYMoHWQw41v93Q) --- @@ -530,7 +527,7 @@ _Walk the boneyard: rows of retired airframes, fully resolved in 3D._ How the globe handles live data: - **World-stable icons.** Aircraft and ships point along their _true real-world heading_ at every camera angle — tracked or not, looking straight down or across the horizon — via per-frame screen-space course projection. No spinning, no viewport-locking. -- **Smooth motion from choppy data.** Live feeds arrive every 15–30s; the globe renders one interval behind real time and interpolates between known fixes. Dead reckoning fills the gaps. +- **Smooth motion from choppy data.** Live feeds arrive every 15–30s, often minutes late; the globe renders as far behind real time as the feed is late (at least one interval) and draws each aircraft along a smooth curve between its known fixes. Dead reckoning fills the gaps. - **Honest satellites.** SGP4 propagation with orbit rings that stay locked to their satellites via GMST realignment — no drift, no per-second flicker. - **Sits on the real ground.** Entity heights are aligned to work with Google 3D tiles, so aircraft park on aprons and cameras stand on street corners instead of floating. - **Caching and request budgets.** An OpenSky credit governor, a TomTom daily tile budget, and disk-cached TLEs reduce repeated requests. These controls do not replace provider quotas or billing controls. @@ -547,7 +544,7 @@ src/ ├── voice/ # OpenAI Realtime session + 30 voice tools ├── layers/ # Layer components — weather, wind, cyclones, transit, ALPR, … ├── data/ # One module per layer + orchestration + context store -│ ├── iconOrientation.js # Screen-projected headings + horizon cull +│ ├── iconOrientation.js # Horizon backdrop for labels (headings: screenRotation.js) │ └── local_data/ # Bundled datasets (per-folder provenance) └── scenes/ # Cinematic scene director ``` @@ -567,12 +564,14 @@ and configuration details. No key needed for Wind, Rain radar, Satellite clouds, Lightning density, Cyclone advisories, Mapped ALPR Cameras, Transit, Directions, Delaware live -video, and coordinate or bundled-place search. A layer row waiting on a key +video, the News layer's Conflicts section, and coordinate or bundled-place +search. A layer row waiting on a key names it. ### Choose the capabilities you want -Seven keys. Five have a free tier, and the two 🔴 ones are metered: +Nine keys. Six have a free tier. Of the three 🔴 ones, Google Maps and OpenAI are +metered and Liveuamap is a paid subscription: | | Key | Why | Get it | | --- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -583,10 +582,8 @@ Seven keys. Five have a free tier, and the two 🔴 ones are metered: | 🟡 | **NASA FIRMS** | 🔥 Live active fires | [firms.modaps.eosdis.nasa.gov](https://firms.modaps.eosdis.nasa.gov/api/map_key/) — free | | 🟡 | **TomTom** | 🚦 Live flow speeds and congestion colors for the simulated traffic layer | [my.tomtom.com](https://my.tomtom.com/keys) — free tier available | | 🟡 | **Mapillary** | 📷 Street Level coverage and photos. A public client token by design (see SECURITY.md) | [mapillary.com/dashboard/developers](https://www.mapillary.com/dashboard/developers) — register an app, copy its Client Token | - -![Diving from city-scale live congestion straight into an intersection's public camera](docs/media/05-traffic-to-cctv.gif) - -_What the TomTom key buys you: rush-hour density painted on the city — then dive from the jam straight into the camera watching it._ +| 🟡 | **World News API** | 📰 News layer, Local: the news of the country in view. The free plan allows 50 points a day; `WORLDNEWSAPI_DAILY_READS` (default 30) keeps Core inside it. Core keeps each country's news for up to 1 hour, and World News API's [terms](https://worldnewsapi.com/terms/) allow caching only with its prior written permission, which is yours to get. The Data attribution popover credits it with a link | [worldnewsapi.com/console](https://worldnewsapi.com/console/) — free plan | +| 🔴 | **Liveuamap** | 📰 News layer, Conflicts: Liveuamap's mapped items beside GDELT's reports (🟢 Conflicts works without) | [liveuamap.com/promo/api](https://liveuamap.com/promo/api) — paid API | ### Cherry on top @@ -656,8 +653,8 @@ Honest numbers, roughly, as of mid-2026 — always check the provider pricing pa | | Cost reality | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **🟢 Most layers** | **$0, no signup.** OpenSky anon, USGS, CelesTrak, adsb.lol, city CCTV, Radio Browser, GBFS, Launch Library 2, transit feeds, OSRM routing, NOAA and ECMWF weather, OpenStreetMap ALPR mapping, bundled datasets. | -| **🟡 The free-key tier** | **$0 with a signup.** AISStream, FIRMS, TomTom, OpenSky, plus Cesium ion for eligible personal/non-commercial use. Provider quotas and eligibility still apply. | +| **🟢 Most layers** | **$0, no signup.** OpenSky anon, USGS, CelesTrak, adsb.lol, city CCTV, Radio Browser, GBFS, Launch Library 2, transit feeds, OSRM routing, NOAA and ECMWF weather, OpenStreetMap ALPR mapping, GDELT news events, bundled datasets. | +| **🟡 The free-key tier** | **$0 with a signup.** AISStream, FIRMS, TomTom, OpenSky, World News API, plus Cesium ion for eligible personal/non-commercial use. Provider quotas and eligibility still apply. | | **🗺️ Google 3D tiles** | **Free through an eligible Cesium ion Community account within its quota; metered through a direct Google key.** Use the direct route for Google place search or commercial deployment, verify current provider terms, and set budget alerts where billing is enabled. | | **🔴 OpenAI voice** | API-key sessions keep the live spend readout, STD/MINI model toggle, $2 warning, and **$5 hard cap**. ChatGPT OAuth is an explicit choice in Provider Settings. Its usage is tracked without an API-dollar estimate or spend cap. The voice context window stays deliberately short. | @@ -698,7 +695,7 @@ God's Eye View runs on **public data, clear sources, and local-first execution.* **Maintainers:** [Bilawal Sidhu](https://github.com/bilawalsidhu) and [Sameh Khamis](https://github.com/samehkhamis) at [Halfpixel](https://halfpixel.ai). -Media note: the capture GIFs on this page show Google Photorealistic 3D Tiles and live data layers, used promotionally with in-frame attribution; they aren't licensed for standalone reuse. See [media provenance and permissions](docs/media/README.md); full source terms in [DATA_SOURCES.md](DATA_SOURCES.md). +Media note: the clips on this page are the ones shown on godseyeview.ai. Some show Google Photorealistic 3D Tiles and live data layers, used promotionally with in-frame attribution; they aren't licensed for standalone reuse. See [media provenance and permissions](docs/media/README.md); full source terms in [DATA_SOURCES.md](DATA_SOURCES.md). > [!IMPORTANT] > God's Eye View is an exploratory visualization of public and third-party data. @@ -719,13 +716,13 @@ So here it is. Step inside the spy-thriller cockpit — except the data is real One heads-up from the inside: build in this space for a week and you learn that **the present is the cheap part**. The moment you try to go back in time — tiling, serving, and scrubbing _what happened_ and _what changed_ at any real resolution — the data gets expensive and the compute gets brutal. That's the long game. -**Update — a hosted version is coming.** We originally planned to keep this repository as the open-source client and build a separate professional product. Then the launch happened, and the loudest request wasn't another feature — it was _"just give me a link."_ So we're building an official hosted God's Eye View at [Halfpixel](https://halfpixel.ai): no installation, just open it in your browser. The hosted version is the easiest way into this open-source project. More soon. +**Update — a hosted version is coming.** We originally planned to keep this repository as the open-source client and build a separate professional product. Then the launch happened, and the loudest request wasn't another feature — it was _"just give me a link."_ So we're building an official hosted God's Eye View at [Halfpixel](https://halfpixel.ai): no installation, just open it in your browser. The hosted version is the easiest way into this open-source project. Sign up for the [waitlist](https://godseyeview.ai/online/) and get notified. ---
-▶️ [Watch the God's Eye View series](https://youtube.com/playlist?list=PL6qSg2I-7_koPbDnSMo0QeeHX_RknA2uv&si=nBGYMoHWQw41v93Q) · 📬 [Map the World](https://maptheworld.ai/) — the newsletter behind the project +🌐 [godseyeview.ai](https://godseyeview.ai), the official site · ▶️ [Watch the God's Eye View series](https://youtube.com/playlist?list=PL6qSg2I-7_koPbDnSMo0QeeHX_RknA2uv&si=nBGYMoHWQw41v93Q) · 📬 [Map the World](https://maptheworld.ai/) — the newsletter behind the project **🌐 God's Eye View. No place left behind.** diff --git a/SECURITY.md b/SECURITY.md index 6e3625f715..e67186d648 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -73,7 +73,9 @@ The data proxies under `server/providers/` are written so the browser cannot tur - **Radio is not an audio relay.** `/api/radio/stations` contacts only allowlisted Radio Browser HTTPS hosts and paths, rejects redirects, rejects any hostname with a loopback/private/link-local/metadata/non-public A or AAAA result, and pins each TLS connection to a validated address. It returns normalized public HTTPS stream URLs; `/api/radio/click/:uuid` applies the same destination policy and accepts only station IDs from the current bounded catalog. The browser then connects directly to the broadcaster after an explicit playback action, so the broadcaster sees the listener's IP address. GEV never proxies, caches, records, or redistributes audio. - **Québec 511 video plays in the browser, opt-in and after Play.** With `CCTV_QUEBEC_VIDEO_ENABLED=1`, `/api/cctv/sources` lists, for each MTQ camera, one URL built server-side from its numeric id on `https://www.quebec511.info/Carte/Fenetres/camera.ashx`; the overlay accepts no other host, path or format. The browser loads that clip only after the viewer presses Play for the selected camera, so Québec 511 sees the viewer's IP address, and the panel says so before Play. Selecting a camera by click, auto-hop, a scene or voice never loads it, and switching cameras stops playback. GEV never proxies, caches or reads the video's pixels. With the flag unset (the default) the browser makes no request to Québec 511. - **No verbatim client headers upstream.** The CCTV media route is the one route that relays a request header (`Range`, for video seeking). It is parsed and canonicalized before it is forwarded: one `bytes=` range only, with every accepted form — explicit span, open-ended and suffix — bounded to the same 64 MiB ceiling the relay applies to a declared response body. Multi-range, malformed, inverted and non-`bytes` values are dropped and the request proceeds without a `Range`, as RFC 7233 §3.1 prescribes. Bounding the request bounds what is asked for: a response that declares no length — live streamed media, or a chunked body from an upstream that ignores the `Range` — has no ceiling. An upstream request the browser has stopped waiting for is cancelled rather than left running, whether the viewer leaves before the headers arrive or during the body. +- **The Data Library proxy fetches manifest upstreams only.** `/api/library/data/`, `/api/library/tile////` and `/api/library/index/` (a partitioned GeoParquet entry's file index, built from an S3 ListObjectsV2 listing and one ranged footer read per file, cached in memory for the entry's `cacheSeconds`) resolve the id against the validated manifests in `src/library/entries/`; the browser never supplies a URL, and every derived request must stay on the manifest's https host. Redirects are refused, dataset bodies are capped while streaming at the manifest's `maxBytes` (at most 32 MiB) and tiles at 2 MiB of `image/png`, `image/jpeg` or `image/webp`, responses are cached in memory only (at most 512 tiles), requests are rate-limited per client, and upstream error text is never returned. A keyed entry must be proxied; its key is read from this server's environment through the key registry and its routes refuse cross-site and forwarded requests like the other cost-bearing routes. Browser-direct entries are fetched by the browser with no cookies or referrer. - **Transit fetches registered feeds only.** `/api/transit/vehicles/` resolves the id against `src/data/transitFeeds.js`; the browser never supplies a URL, and a feed that is registered but disabled does not resolve at all. Redirects are followed manually and each hop is validated against the feed's own https origin before it is requested, so an off-origin or downgraded hop is refused rather than contacted. Bodies are capped at 8 MB, the protobuf is decoded server-side under entity-count and string-length ceilings, a differential feed is refused, and snapshots live 15 s in memory with no disk cache. A per-feed admission limiter and a failure cooldown ladder bound what this process can ask of any operator. +- **Rail fetches registered feeds only, and none needs a credential.** `/api/rail/feeds` lists the offered feeds; `/api/rail/trains/`, `/api/rail/updates/`, `/api/rail/paths/` and `/api/rail/schedule/` resolve the id against `src/data/railFeeds.js` (`RAIL_FEED_ID_PATTERN`: lowercase letters, digits and hyphens). The browser never supplies a URL, and an id that is not registered, or a trip-updates route for a feed that registers none, does not resolve at all; any method but GET answers 405 (`Allow: GET`, never cached). Every registered feed and every static timetable is open: no rail request carries a credential of the deployer's; one feed's published URL includes a fixed public value its publisher prints for everyone (Bordeaux's `apiKey`), and the only rail setting the server reads is `RAIL_PATHS_DIR`. Upstream requests follow the Transit proxy's policy: https only, each redirect hop validated against the feed's own https origin before it is requested (three hops at most), a request timeout, bodies capped at 8 MiB unless the registry sets a feed's own cap (never above 64 MiB), and a per-feed admission limiter and the failure cooldown ladder bound what the process asks of any operator. Responses are decoded server-side: GTFS-Realtime under entity-count and string-length ceilings, a differential feed is refused, and an empty or header-less GTFS-Realtime reply (an error page served as 200, say) is refused as unreadable, so the last good snapshot is served stale or the request fails with 502. The Irish Rail and SIRI VM XML is read by small scanners, not an XML library: a document that declares a DTD or an entity is refused, and the whole text, the number of trains and every field are capped. Only vehicles the feed's classifier recognises as trains leave the server, and no train position inside Ukraine is ever sent (`src/data/railNoPositions.js`). Snapshots and trip updates live in memory for the feed's own freshness window, with serve-stale after a failure; there is no disk cache and no history. Path and schedule packs are optional build output, read from disk (`.cache/rail-paths/` or `RAIL_PATHS_DIR`) by a reader that re-checks the id against the same pattern, so a name never leaves that directory. A pack over 24 MiB is refused before it is read and answers 503, never a partial file, and so does a pack that cannot be read: only a missing pack is 404; the rest pass through as bytes, through a 64 MiB in-memory read cache keyed by each file's modification time and size, and are served as JSON holding timetables and track shapes only, `no-cache` with an ETag from that time and size (304 when unchanged). A schedule pack of another format version or another feed, or whose window has ended, is not used, and a feed that cannot be read without it answers 503 rather than an empty list. The pack build (`scripts/build-rail-paths.mjs`) runs only when a person runs it, never on app start: it downloads over https only (a redirect to plain http is refused), caps each download in size and time, sends no credential, and refuses an `--out` folder (or a `RAIL_PATHS_DIR` it writes to) inside `src/` or `public/`. - **Local receiver feeds are operator-configured and local-only.** `/api/local-receivers/aircraft` reads only the `aircraft.json` URLs in the server's `LOCAL_RECEIVER_FEEDS`; the browser never supplies an address. Each host must pass the shared tap address rule (`src/data/tapAddress.js`: loopback, RFC1918, `localhost`, `*.local`; no link-local, IPv6 or other names), the scheme must be http(s), the path must end in `aircraft.json`, and credentials, queries and fragments are refused. Invalid entries are logged at startup and never fetched. Reads use a 2 s timeout, refuse redirects, cap bodies at 2 MB and share one read per second; responses name each feed by band only and never carry upstream error text. - **Voice place search runs only on the operator's Overpass.** `/api/osm/features` answers only when `OVERPASS_UPSTREAMS` is set and never falls back to a public instance. The client sends a curated preset id, a box, a mode and a limit; the server writes and quotes the Overpass query itself, so no client or model text reaches it. Boxes are capped (36 deg² for a count, 4 deg² for a listing), as are the feature limit, the Overpass timeout and memory, and the response bytes read. Each client (IPv6 clients keyed by /64, as on `/api/overpass`) runs one search at a time and two run at once in all, under a per-client rate limit (12/min) and a global one (30/min); a search gets 22 s across every configured endpoint in turn (Overpass itself is told 20 s), which ends before the voice answer stops waiting at 25 s. The route sits behind the cross-site gate below. Answers are cached in memory and on disk (`.gev-cache/osm-features/`, at most 400 entries and 256 MB, kept a day), keyed to the configured instance so a repointed `OVERPASS_UPSTREAMS` never serves the old one's answers; a malformed answer is never cached. - **Validated response formats.** Proxied bodies are relayed only in the format the route serves. CCTV frames and the Street View fallback accept JPEG, PNG, GIF, WebP and AVIF only, sent under their canonical type; any other type falls through to the next fallback. The one exception is a source registered as an MJPEG still (the Taiwan Highway Bureau feeds): its `multipart/x-mixed-replace` answer is read only up to its first JPEG part, capped at 2 MB, and sent as `image/jpeg`; a multipart answer from any other camera falls through. A camera whose API needs an operator credential (the City of Ottawa certificate, `OTTAWA_CAMERA_CERTIFICATE`) has a keyless catalog URL; the frame proxy adds the credential only at fetch time, only for a URL inside that camera's pinned path, so `/api/cctv/sources` and `/api/cctv/stream` never carry it. Live CCTV media must match its feed kind (`video/mp4`, `video/webm`, or `multipart/x-mixed-replace` with a boundary) before it is relayed or the camera counts as healthy, and its redirects stay on the registered origin. GBFS bodies must parse as JSON and are re-serialized as `application/json; charset=utf-8`. Camera catalog URLs are pinned by parsed URL — scheme, exact host, no credentials, default port, and a normalized path inside the agency's image directory — and a redirect on a pinned host must stay inside the same directory. Every `/api/cctv` route uses the keyless cross-site checks described below, so cameras stay reachable behind a reverse proxy; a request carrying forwarding headers never reaches the key-bearing Street View fallback and gets the placeholder frame instead, as when no key is configured. @@ -82,7 +84,7 @@ The data proxies under `server/providers/` are written so the browser cannot tur - **Sanitized errors** — internal error details are not echoed back to clients. - **Coalesced OAuth refresh** and cached successful responses only (OpenSky). - **Redacted debug logging.** The voice debug log (`.gev-logs/`, gitignored) strips API keys, bearer tokens, client secrets, and image data URLs before writing. -- **Cross-site gate on cost/log endpoints.** The cost-bearing (`/api/realtime/token`, `/api/openai/hud-summary`, `/api/google/nearby-places`, `/api/google/text-search`), quota-bearing (`/api/mapillary/*`, with a per-IP limit on tiles, and `/api/tomtom/*`, backed by its persistent daily tile budget) and log (`/api/realtime/debug-log`) endpoints refuse cross-site browser requests: a foreign or opaque `Origin`, a `Sec-Fetch-Site` other than `same-origin`/`none` (this is what blocks an ``/navigation that carries no `Origin`), or any reverse-proxy/CDN forwarding header returns `403`. Non-browser loopback tools (the repo QA harnesses POST the token endpoint with no `Origin`) and the explicit `HOST=0.0.0.0` LAN opt-in keep working — the gate deliberately does not require a loopback remote address; that stricter requirement belongs only to the credential panel (`admitKeySetupRequest`). The Host check (`allowedHosts`, applied by `hostCheckPlugin` ahead of every route, since Vite's own check runs only after plugin middleware) rejects a rebinding `Host` before any handler runs, in every mode, and the gate is defense in depth behind it: the LAN opt-in keeps that check and accepts only IP addresses, `localhost` and names listed in `GEV_ALLOWED_HOSTS`. **Limit:** a name you list there is trusted like the app's own address, so list only names you control. The keyless map routes (`/api/terrain/heights`, `/api/drone-airspace`, `/api/inaturalist/observations`, `/api/acartia/sightings`, `/api/overpass` and voice place search's `/api/osm/features`, which spends the same operator Overpass) use the same cross-site checks, minus the forwarding-header refusal: they guard only per-client quotas and caches, not a key or a bill, and the map and voice need them to work behind a reverse proxy. `/api/overpass` also admits at most 300 POSTs a minute per peer (IPv6 peers keyed by /64) and 900 a minute across all remote peers before it reads a body. A direct loopback request — a loopback socket with none of the forwarding headers `hasProxySignals` checks (`Forwarded`, `Via`, `X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Proto`, `X-Real-IP`, `CF-Connecting-IP`, `CF-Ray`) — draws on its own per-peer admission window, so remote peers cannot exhaust the owner's admission. A reverse proxy on the same machine must add at least one of those headers (Caddy and Cloudflare do by default; nginx needs `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`, plus `proxy_set_header Host $http_host;` and `proxy_set_header X-Forwarded-Proto $scheme;` so the `Origin` check matches), or its traffic is indistinguishable from the owner's and shares the owner's window. With one, its requests are then counted as remote, in one bucket per proxy socket — the forwarded client address is never trusted as identity — so all users behind one proxy share 300/min. The isolation needs a loopback socket: under the default Docker bridge network every host-side client, the owner included, arrives from the container gateway and is one remote peer. **Limit:** this isolates admission only. The upstream budget (90 requests/min per client key, 300/min across all clients) is shared, so once remote traffic has used the global upstream budget, an owner request that misses the cache can still get `429`, or `503` when remote misses hold every upstream concurrency slot; cache hits are unaffected. The CCTV routes (`/api/cctv/*`) use the same keyless checks; their one key-bearing step, the Street View fallback, is skipped for any request with forwarding headers. +- **Cross-site gate on cost/log endpoints.** The cost-bearing (`/api/realtime/token`, `/api/openai/hud-summary`, `/api/google/nearby-places`, `/api/google/text-search`), quota-bearing (`/api/mapillary/*`, with a per-IP limit on tiles, `/api/tomtom/*`, backed by its persistent daily tile budget, and `/api/news/*`, which spends the World News API daily reads, Liveuamap reads and GDELT downloads) and log (`/api/realtime/debug-log`) endpoints refuse cross-site browser requests: a foreign or opaque `Origin`, a `Sec-Fetch-Site` other than `same-origin`/`none` (this is what blocks an ``/navigation that carries no `Origin`), or any reverse-proxy/CDN forwarding header returns `403`. Non-browser loopback tools (the repo QA harnesses POST the token endpoint with no `Origin`) and the explicit `HOST=0.0.0.0` LAN opt-in keep working — the gate deliberately does not require a loopback remote address; that stricter requirement belongs only to the credential panel (`admitKeySetupRequest`). The Host check (`allowedHosts`, applied by `hostCheckPlugin` ahead of every route, since Vite's own check runs only after plugin middleware) rejects a rebinding `Host` before any handler runs, in every mode, and the gate is defense in depth behind it: the LAN opt-in keeps that check and accepts only IP addresses, `localhost` and names listed in `GEV_ALLOWED_HOSTS`. **Limit:** a name you list there is trusted like the app's own address, so list only names you control. The keyless map routes (`/api/terrain/heights`, `/api/drone-airspace`, `/api/inaturalist/observations`, `/api/acartia/sightings`, `/api/overpass` and voice place search's `/api/osm/features`, which spends the same operator Overpass) use the same cross-site checks, minus the forwarding-header refusal: they guard only per-client quotas and caches, not a key or a bill, and the map and voice need them to work behind a reverse proxy. `/api/overpass` also admits at most 300 POSTs a minute per peer (IPv6 peers keyed by /64) and 900 a minute across all remote peers before it reads a body. A direct loopback request — a loopback socket with none of the forwarding headers `hasProxySignals` checks (`Forwarded`, `Via`, `X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Proto`, `X-Real-IP`, `CF-Connecting-IP`, `CF-Ray`) — draws on its own per-peer admission window, so remote peers cannot exhaust the owner's admission. A reverse proxy on the same machine must add at least one of those headers (Caddy and Cloudflare do by default; nginx needs `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`, plus `proxy_set_header Host $http_host;` and `proxy_set_header X-Forwarded-Proto $scheme;` so the `Origin` check matches), or its traffic is indistinguishable from the owner's and shares the owner's window. With one, its requests are then counted as remote, in one bucket per proxy socket — the forwarded client address is never trusted as identity — so all users behind one proxy share 300/min. The isolation needs a loopback socket: under the default Docker bridge network every host-side client, the owner included, arrives from the container gateway and is one remote peer. **Limit:** this isolates admission only. The upstream budget (90 requests/min per client key, 300/min across all clients) is shared, so once remote traffic has used the global upstream budget, an owner request that misses the cache can still get `429`, or `503` when remote misses hold every upstream concurrency slot; cache hits are unaffected. The CCTV routes (`/api/cctv/*`) use the same keyless checks; their one key-bearing step, the Street View fallback, is skipped for any request with forwarding headers. - **Full Content-Security-Policy.** The dev and preview servers send a real CSP (`script-src 'self' 'unsafe-eval' blob:` plus the YouTube, Facebook and X scripts the Nepal event's embedded media loads and the Maps JavaScript API that Street View runs on, with a matching `frame-src` for their players and posts: no inline script and no other script origin; `blob:` covers the object URLs Cesium's bundled workers bootstrap through in the built app), alongside the existing `X-Frame-Options: DENY` and `frame-ancestors 'none'`. `'unsafe-eval'` stays because Knockout, bundled inside Cesium's widgets package, resolves the global object with `eval` at load time and the globe does not initialize without it; styles permit `'unsafe-inline'` and Google Fonts because Vite's dev client injects ` + + +
+

Renderer conformance

+ + + + + + +
+
+
+
+
+
+ + + diff --git a/dev/conformance/main.js b/dev/conformance/main.js new file mode 100644 index 0000000000..a1fb6c48a2 --- /dev/null +++ b/dev/conformance/main.js @@ -0,0 +1,256 @@ +/** + * The conformance page: runs the logic suite in the browser, and draws the + * reference scenes on a renderer to check them against the stored + * references (or record new ones). Driven by hand or through the + * chrome-devtools MCP; `window.conformance` exposes the same actions. + */ +import { + DEFAULT_TOLERANCE, + runConformance, +} from '../../src/render/conformance/index.js'; +import { + REFERENCE_SCENES, + sceneSupport, +} from '../../src/render/conformance/scenes.js'; +import { + compareImages, + drawScene, + referenceName, +} from '../../src/render/conformance/visual.js'; +import { createStubHarness } from '../../src/render/stub/harness.js'; +import { toEcef } from '../../src/render/stub/math.js'; +import { createCesiumSceneRenderer } from '../../src/render/cesium/sceneRenderer.js'; +import { + CESIUM_CHECKS, + createCesiumHarness, +} from '../../src/render/cesium/harness.js'; + +const REFERENCES = '/src/render/conformance/goldens/visual/'; +const SAVE = '/__conformance/references/'; +const ctx = { + toEcef, + assets: { + model: '/models/fleet/aircraft/c172.glb', + // Not served: the model failure check loads it. + missingModel: '/models/conformance-missing.glb', + }, +}; +const $ = (id) => document.getElementById(id); +const status = (text) => ($('status').textContent = text); + +const RENDERERS = { + cesium: () => createCesiumSceneRenderer({ container: $('stage') }), +}; + +const HARNESSES = { + stub: () => [createStubHarness('stub (browser)'), {}], + cesium: () => [ + createCesiumHarness({ + model: ctx.assets.model, + missingModel: ctx.assets.missingModel, + }), + { only: (id) => CESIUM_CHECKS.has(id) }, + ], +}; + +/** + * Runs the logic suite on `which`; `all` runs every check, listed or not; + * `only` (check ids) runs just those of them. + */ +async function runLogic(which = 'stub', { all = false, only } = {}) { + status(`running the logic suite on ${which}…`); + const [harness, options] = HARNESSES[which](); + const listed = all ? () => true : (options.only ?? (() => true)); + const report = await runConformance(harness, { + only: (id) => listed(id) && (!only || only.includes(id)), + }); + $('logicResults').innerHTML = + `

${report.harness}: ${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped

+ ${report.results + .filter((r) => r.status !== 'pass') + .map( + (r) => + ``, + ) + .join('')}
${r.status}${r.id}${escape(r.detail ?? '')}
`; + status(''); + return { + passed: report.passed, + failed: report.failed, + skipped: report.skipped, + failures: report.results.filter((r) => r.status === 'fail'), + skips: report.results.filter((r) => r.status === 'skip'), + }; +} + +const escape = (s) => + s.replace(/[&<>]/g, (c) => ({ '&': '&', '<': '<', '>': '>' })[c]); + +async function pixels(blob) { + const bitmap = await createImageBitmap(blob); + const canvas = new OffscreenCanvas(bitmap.width, bitmap.height); + const g = canvas.getContext('2d'); + g.drawImage(bitmap, 0, 0); + return g.getImageData(0, 0, bitmap.width, bitmap.height); +} + +// Object URLs shown for the current run, revoked when the next one starts. +let objectUrls = []; +function objectUrl(blob) { + const url = URL.createObjectURL(blob); + objectUrls.push(url); + return url; +} + +async function toUrl(imageData) { + const canvas = new OffscreenCanvas(imageData.width, imageData.height); + canvas.getContext('2d').putImageData(imageData, 0, 0); + return objectUrl(await canvas.convertToBlob()); +} + +/** The views the stored manifest lists, or none. */ +async function storedViews() { + try { + const res = await fetch(REFERENCES + 'manifest.json', { + cache: 'no-store', + }); + return res.ok ? ((await res.json()).views ?? []) : []; + } catch { + return []; + } +} + +async function reference(name) { + const res = await fetch(REFERENCES + name, { cache: 'no-store' }); + return res.ok && res.headers.get('content-type')?.startsWith('image/') + ? res.blob() + : null; +} + +/** Draws every scene; records references or compares against them. */ +async function runScenes({ record = false, only } = {}) { + const which = $('renderer').value; + const renderer = await RENDERERS[which](); + const results = []; + $('views').innerHTML = ''; + for (const url of objectUrls) URL.revokeObjectURL(url); + objectUrls = []; + try { + for (const scene of REFERENCE_SCENES) { + if (only && !only.includes(scene.id)) continue; + const unsupported = sceneSupport(scene, renderer, ctx); + if (unsupported) { + results.push({ scene: scene.id, status: 'skip', detail: unsupported }); + continue; + } + status(`${scene.id}…`); + // A scene the renderer refuses fails alone; the others still draw. + try { + await drawScene(renderer, scene, ctx, async (view, capture, settle) => { + const name = referenceName(scene.id, view.name); + const figure = document.createElement('figure'); + $('views').append(figure); + if (settle.state !== 'settled') { + const detail = `${settle.state}: ${settle.blockers.join(', ')}`; + results.push({ + scene: scene.id, + view: view.name, + status: 'fail', + detail, + }); + figure.innerHTML = `
${name}: ${escape(detail)}
`; + return; + } + if (record) { + const res = await fetch(SAVE + name, { + method: 'PUT', + body: capture, + }); + results.push({ + scene: scene.id, + view: view.name, + status: res.ok ? 'recorded' : 'fail', + detail: res.ok ? undefined : `save ${res.status}`, + }); + figure.innerHTML = `
${name}: recorded
`; + return; + } + const refBlob = await reference(name); + if (!refBlob) { + results.push({ + scene: scene.id, + view: view.name, + status: 'fail', + detail: 'no reference', + }); + figure.innerHTML = `
${name}: no reference
`; + return; + } + const [actual, expected] = await Promise.all([ + pixels(capture), + pixels(refBlob), + ]); + const diff = new Uint8ClampedArray(actual.data.length); + const outcome = compareImages(actual, expected, { diff }); + results.push({ + scene: scene.id, + view: view.name, + status: outcome.match ? 'pass' : 'fail', + diffFraction: outcome.diffFraction, + solidPixels: outcome.solidPixels, + mismatchedPixels: outcome.mismatchedPixels, + ...(outcome.reason ? { detail: outcome.reason } : {}), + }); + const diffUrl = outcome.reason + ? '' + : await toUrl(new ImageData(diff, actual.width, actual.height)); + figure.innerHTML = `
+
${name}: ${outcome.solidPixels} solid, ${outcome.mismatchedPixels} unexcused, ${(outcome.diffFraction * 100).toFixed(3)}% differ ${outcome.reason ?? ''}
`; + }); + } catch (error) { + results.push({ + scene: scene.id, + status: 'fail', + detail: String(error?.message ?? error), + }); + } + } + if (record) { + // A partial recording keeps the other scenes' entries. + const kept = only + ? (await storedViews()).filter( + (view) => !only.some((id) => view.startsWith(`${id}-`)), + ) + : []; + const recorded = results + .filter((r) => r.status === 'recorded') + .map((r) => referenceName(r.scene, r.view)); + await fetch(SAVE + 'manifest.json', { + method: 'PUT', + body: + JSON.stringify( + { + renderer: which, + size: { + width: renderer.canvas.width, + height: renderer.canvas.height, + }, + views: [...kept, ...recorded], + }, + null, + 2, + ) + '\n', + }); + } + } finally { + renderer.destroy(); + status(''); + } + return results; +} + +$('logic').onclick = () => runLogic('stub'); +$('logicCesium').onclick = () => runLogic('cesium'); +$('check').onclick = () => runScenes(); +$('record').onclick = () => runScenes({ record: true }); +window.conformance = { runLogic, runScenes }; diff --git a/dev/stub-app/main.js b/dev/stub-app/main.js new file mode 100644 index 0000000000..ecd9e8607f --- /dev/null +++ b/dev/stub-app/main.js @@ -0,0 +1,60 @@ +/** + * The whole application on the stub renderer (`src/render/stub`), with only + * the contract's required members: the proof that the application runs on + * those members alone, and needs no code that knows which renderer it is. + * `scripts/qa-stub-boot.mjs` serves the application's page with this entry + * in place of `src/main.js`, boots it headless, runs its data layers and + * checks that no Cesium module loads. + * + * The stub runs nothing on its own: each animation frame here ticks it once. + * `window.__stubBoot` exposes the application and the renderer it made. + */ +import { createStandaloneApplication } from '../../src/standalone/application.js'; +import { createStubRendererPlugin } from '../../src/render/stub/index.js'; + +const renderers = []; + +/** Tick a renderer once per animation frame until it is destroyed. */ +function drive(renderer) { + const step = () => { + if (!renderers.includes(renderer)) return; + renderer.testing.tick(); + requestAnimationFrame(step); + }; + requestAnimationFrame(step); +} + +// The required tier, no capability at all; `?capabilities=all` gives the +// stub every capability, to see what the layers draw with them. +const allCapabilities = + new URLSearchParams(location.search).get('capabilities') === 'all'; + +const plugin = createStubRendererPlugin( + allCapabilities ? {} : { capabilities: [] }, + (renderer) => { + renderers.push(renderer); + const destroy = renderer.destroy.bind(renderer); + renderer.destroy = () => { + renderers.splice(renderers.indexOf(renderer), 1); + destroy(); + }; + drive(renderer); + }, +); + +const application = createStandaloneApplication({ + renderer: plugin, + allowQaRegistration: true, +}); + +window.__stubBoot = { + application, + renderers, + started: application.start().then( + () => ({ ok: true }), + (error) => { + console.error('Stub application failed to start:', error); + return { ok: false, error: String(error?.stack || error) }; + }, + ), +}; diff --git a/docs/APPLICATION.md b/docs/APPLICATION.md index 8848601d15..301ca53cd2 100644 --- a/docs/APPLICATION.md +++ b/docs/APPLICATION.md @@ -43,7 +43,11 @@ await app.destroy(); ``` The example's containers and three remaining constructors are supplied by the -consumer. The viewer helper preserves the standalone viewer's render settings; +caller. The standalone scene also returns `trimStaleCommands()`, which drops +the draw commands the Cesium scene keeps after a turned-off layer stops drawing; +the application tools call it one frame after each layer disable. A scene +without it keeps those commands, and so the layer's memory, until they are +overwritten. The viewer helper preserves the standalone viewer's render settings; it neither selects map sources nor reads keys. Supply a visible credit container and retain all attribution required by the chosen sources. Cesium is external to this export: the consuming build must provide the same instance used elsewhere @@ -81,6 +85,119 @@ constructed component objects; the component instances themselves remain mutable `ready` means all constructors have returned. Background feed activity and the standalone share-restoration result keep their existing separate contracts. +## Pointer input + +`gods-eye-view/input` exports `inputFor(viewer)`, the scene's one input +dispatcher. Every layer and tool takes its pointer input from it, and so can +the caller: one pointer handler per viewer, and a click picked once and +handed to every subscriber. + +```js +import { inputFor } from 'gods-eye-view/input'; + +const input = inputFor(viewer); +const off = input.onClick((event) => { + if (event.ownerId === 'flights') showFlight(event.id); +}); +// Later: +off(); +``` + +`onClick` runs while no tool holds the pointer (the draw tool, the imagery +box), so a vertex placed on an aircraft is not also a click on it. Its event +reads lazily; a subscriber that reads nothing costs no pick: + +| Member | What it is | +| -------------------- | ------------------------------------------------------------------------- | +| `screenPosition` | Where the user clicked, in CSS pixels; for DOM and overlay hit-tests | +| `position` | Where that lands in the pick buffer (corrected under sensor styles) | +| `gesture` | `{ travelPx, durationMs }` of the press, to tell a click from a drag | +| `topHit` | The renderer's `Hit` on top at `position`, or `null` for the map itself | +| `drawHit` | `topHit` when it is an item of a draw set, else `null` | +| `hit` | `topHit`, or on a coarse pointer the contact under a surface pick | +| `id`, `ownerId` | The hit's pick id and the layer that registered it, or `null` | +| `meta` | The hit's own metadata, when it carries any | +| `surface` | Whether the hit is the map itself | +| `drill(limit)` | The draw-set `Hit`s under the click, shared by every subscriber | +| `windowHit(w, h)` | `{ id, drawHit, surface }` of a pick over a `w`×`h` window | +| `ground()` | The world position under the click, or `null` over the sky | +| `native` | The renderer adapter's own `{ pick, pickWindow(w, h), drill(limit) }` | +| `pick`, `pickWindow` | `native.pick` and `native.pickWindow`, for code bound to the engine picks | + +A hit is the renderer contract's `Hit` (`src/render/contract/query.d.ts`). +Something drawn outside the renderer's draw port is a `Hit` with `set: ''`, +named by the adapter. Positions are plain `{ x, y }` objects. The dispatcher +takes its pointer events from the renderer's input port and its picks from +its query port, so a viewer with no renderer bound needs the Cesium adapter's +factories loaded (`gods-eye-view/render/cesium/unbound`), or `inputFor` throws. + +`onPointer(type, fn, { lease })` subscribes to `down`, `move`, `up`, `click` +or `dblclick`; with a lease it runs only while that lease is current. A tool +takes its lease with `claimPointer(ownerId, { onLost })` from the same export +(and gives it back with `releasePointer(lease)`), which also keeps every +ambient subscriber off its clicks; `isPointerFree()` and `pointerOwner()` +report who holds it. The newest claim takes over, as on the renderer's input +port: the tool holding the pointer has its `onLost` called once and turns +itself off, and its late release frees nothing. `suspendCamera(reason)` and `suppressStockClicks()` return their +own release: camera input and the viewer's stock select and double-click-track +come back when the last hold is released, so two holders cannot undo each +other. The renderer's input port owns the camera controller's `enableInputs`: a direct +write (Cesium's camera flights make one when they start and end) is kept, but +reads true only while no hold is out. A caller-supplied `createScene` that creates its own viewer registers +`defer(() => inputFor(viewer).destroy())` right after it; the standalone scene +does this and returns the dispatcher as `scene.input`. + +## Height queries + +`gods-eye-view/queries/heights` exports `heightsOf(viewer)`, the one place +height queries go. Layers, tools and the camera ask it instead of asking the +renderer's query port (`sampleHeight`, `sampleHeightNow`, `clampToSurface`) +or the scene themselves, so how the renderer answers heights can change +without touching them. Pass the viewer the renderer is bound to, not its +scene. A viewer with no renderer bound is answered by the Cesium adapter's +fallback once the caller has loaded `gods-eye-view/render/cesium/unbound`; +until then, every query answers `null`. + +```js +import { heightsOf } from 'gods-eye-view/queries/heights'; + +const heights = heightsOf(viewer); +const ground = heights.now({ lon, lat }, { exclude: [ownSetId] }); +if (ground !== null) place(ground); +``` + +| Member | What it answers | +| ----------------------------- | ------------------------------------------------------------------------- | +| `now(point, opts)` | Height in metres from what is loaded, or `null` | +| `clampNow(position, opts)` | The ECEF `{ x, y, z }` moved onto the drawn surface, or `null` | +| `batch(points, opts)` | A promise of heights once the most detailed tiles stream; `null` per miss | +| `clampBatch(positions, opts)` | A promise of clamped `{ x, y, z }` copies; `null` per miss | +| `supported()` | `{ surface, clamp }`: whether the drawn surface can be queried at all | + +A point is `{ lon, lat }` in degrees or `{ longitude, latitude }` in radians. +`against: 'surface'` (the default) reads what is drawn, 3D tiles and globe; +`against: 'terrain'` reads the loaded terrain alone; `against: 'tiles'` the +tiles without the globe. Both `surface` and `tiles` include draw sets drawn +with `includeInHeightQueries`; `clampNow` and `clampBatch` always clamp to +the surface. `exclude` lists draw set ids to see through, of those drawn with +`includeInHeightQueries`; every other draw set is seen through already. Every +miss is `null`, and every caller treats it as one; `batch` and `clampBatch` +reject when the query itself fails. Without depth-texture support the Cesium +renderer answers no `surface` or `tiles` height; `now` still answers +`terrain` from the loaded tiles, while `batch` misses terrain too. + +## Cesium internals + +The app reaches private Cesium fields only through +`src/render/cesium/internals.js`, one named helper per field (the main and +offscreen pick views, a billboard's collection, a cluster's point collection, +the widget's render-loop latch, the WebGL context and whether a camera flight +is under way). `internals.test.mjs` fails when the installed Cesium stops +declaring one of them, and when a private field is reached anywhere else. +Imagery that rations its tile requests states the policy as a hook with +`withTileRequestHook(provider, { requestImage, credit })` from +`src/render/cesium/tileRequests.js`, which leaves the provider untouched. + ## Standalone wiring `src/main.js` reads the existing browser configuration and starts @@ -167,7 +284,10 @@ rejects delayed responses; a new start requests a fresh secret. Secret expiry limits connection creation and does not describe the connected session lifetime. `createStandaloneApplication({ voice })` passes these construction options to -the controls. An incompatible protocol needs a separate controller adapter; +the controls. An app can supply `voice.openStories({ isCurrent })` for what the +`open_stories` action does, spoken or typed; it answers true when it opened, +`'already-open'`, or false. Without it the action opens the Stories page. +An incompatible protocol needs a separate controller adapter; changing an endpoint alone does not translate protocol messages. No alternate model is bundled by this extraction. The Node Realtime provider accepts `realtime: { endpoint, models: { standard, mini }, resolveApiKey, fetchImpl }`; @@ -187,7 +307,41 @@ instances. Configure sources with `application/sources` before registration or state restoration, and release them after the consumers stop. The catalog constructor (`application/layers`) also requires `wind`, `weather` and `cyclones` sources with `getSnapshot` for the Weather layers, and owns the -observed-history clock those layers share for the catalog's lifetime. +observed-history clock those layers share for the catalog's lifetime. That +clock, the catalog's `weatherClock`, follows the world clock (`gods-eye-view/time`) +and has no time controls of its own: move time with the world clock's `seek`, +`play`, `pause` and `goLive` (`weatherClock.world` is the one it follows). + +A layer gives the world clock's timeline the time it can show with +`worldClock.register({ id, coverage })` (`gods-eye-view/time`), which returns +the unregister; call `worldClock.coverageChanged()` when that time changes. +`coverage()` returns null while the layer has none, or +`{ start, end, marks? }` in epoch ms. `marks` are the moments worth going to, +drawn as ticks the timeline's arrow keys step to and a tap on or within 6 px of +snaps to. Each mark is a number, or `{ time, label?, id?, kind? }`: `label` is +short text (cut to 60 characters, ending in `…`) shown when the pointer is on +the tick and told with the time while the handle is on the mark, `id` the layer's own key for the event and `kind` +what sort of event it is (`'launch'`, `'earthquake'`). The two forms may be +mixed; a mark without a finite time, and a `label`, `id` or `kind` that is not +a non-empty string, are ignored. `worldClock.coverage()` returns the union of +the registered layers, `{ start, end, marks, markDetails }`, or null: `marks` +is every mark's time once, in order, as numbers, and `markDetails` the marks in +time order, each a frozen `{ time, label?, id?, kind? }` holding only the +fields given, with marks given alike by several layers once and a bare time +left out where a mark with more to say shares it. +A `weather` source may also supply decoded frames: an optional +`getFrameImage({ product, time, size, bbox, signal })` returns a whole-extent or +detail image and an optional `getFrameTile({ product, time, z, x, y, size, +signal })` returns one tile or null for a transparent tile, each as an +`ImageBitmap`, `ImageData`, canvas or `VideoFrame` of exactly the requested +size, which the layer draws once and closes. Without them the layers read the +image and tile routes (`WeatherFrameFeed` in `src/layers/weather/source.js`). +It may also name its source with an optional `sourceName(kind)`, `kind` being +`'radar'`, `'lightning'` or `'satellite'`: the layer's row shows that name until +a manifest names its own, and NOAA nowCOAST when the source names none. The +name is read once, when the layer is built, and held to the same rule as a +manifest's `display.source`. The map credit still comes from each manifest's +`display.credit`, so a source that is not nowCOAST sets that too. `application/services` accepts boundary, terrain, regional-context, weather and summary services; its weather service supplies cockpit local conditions, not the @@ -217,7 +371,131 @@ leaving out `command-dock` the voice control and its pointer reticle; leaving out `context` the Bhote Koshi reconstruction panel; and leaving out `intel-hud` the Intel HUD overlay (`#intel-hud`), whose readouts the HUD implementation publishes to the `gev-hud` store. An unknown -view name is an error. A host that does not initialize Core's locale passes +view name is an error. An application that offers its own language choice +starts and switches the language with the `./i18n` entry (`startPageLocale`, +`followPageLocale`, `switchLocale`; see [I18N.md](./I18N.md)) and passes `localePicker: false` to `createApplicationControls` instead of editing the markup. Node tests that import application modules register the component loader with `node --import=/build/register-vue`. + +### Cockpit subjects + +Core's Cockpit rides a tracked aircraft, the tracked satellite and the +selected AIS vessel. An application adds kinds of its own with +`services.cockpitSubjects` on `createApplicationControls`: a list of +providers, checked once when the controls are built +(`src/cockpitSubjectProviders.js`). A malformed provider, or one with a member +that throws when read (a getter), is left out with a warning and the rest are +kept. A provider's subject takes entry when it was selected after every +built-in subject present (a tracked aircraft or satellite, a selected vessel), +whose own fixed order is unchanged, and needs the provider's `layerId` on; the +provider then holds its subject, hands the camera a frame and the generic HUD +a view model on every update, and releases it on exit. Provider methods are +synchronous and are called on the provider, so a class instance's methods keep +their `this`; one that throws or returns a promise is treated as having +failed. What a method returns may carry getters: one that throws when read +makes a candidate none, a frame malformed (the view ends) and a HUD view keep +the last; a worded member (labels, entry face, look) that throws keeps its +last good words. + +```js +import { getLocale, onLocaleChange } from 'gods-eye-view/i18n'; +import { pointAtS } from 'gods-eye-view/layers/rail/paths'; + +const words = { + en: { view: 'Ride view', exit: 'Exit ride view', exitText: 'EXIT RIDE' }, + de: { + view: 'Fahrtansicht', + exit: 'Fahrtansicht verlassen', + exitText: 'VERLASSEN', + }, +}; + +/** Ride the Rail layer's selected train; `rail` is its layer instance. */ +const ride = { + kind: 'example-ride', + layerId: 'rail', + entryFace: { icon: 'train', label: 'RIDE' }, + // A function is read again when the page's language changes. + labels: () => words[getLocale()] ?? words.en, + candidate() { + const train = rail.getSelectedTrain(); + return ( + train && { + id: train.key, + name: train.label, + selectedAt: train.selectedAtMs, + } + ); + }, + // Only a train bound to its line can be ridden: read() needs its path. + isEntryAllowed: () => Boolean(rail.getSelectedTrain()?.path), + hold: (id) => rail.setCockpitSubject(id), + read(nowMs, ctx) { + const train = rail.getCockpitSubject(); + if (!train?.path) return null; // ends the view + const point = pointAtS(train.path.line, train.path.s); + return { + id: train.key, + latitude: point.lat, + longitude: point.lon, + heightM: train.position.railHeightM, // null stands it on the shared floor + name: train.label, + headingDeg: + train.path.direction < 0 ? point.bearingDeg + 180 : point.bearingDeg, + speedMps: train.motion.reportedSpeedMps ?? train.motion.derivedSpeedMps, + // The layer already moves the train smoothly: sit on it. + anchor: 'exact', + eye: { upM: 3.5 }, + }; + }, + hud: (frame) => ({ title: frame.name }), + release(id, { restore }) { + rail.setCockpitSubject(null); + if (restore) rail.focusTrain(id); + }, +}; + +createApplicationControls({ /* ... */ services: { cockpitSubjects: [ride] } }); +``` + +The `./i18n` entry gives `getLocale()` and `onLocaleChange()`: +Core translates only its own strings, so a provider words its labels, entry +face and HUD for the page's language (labels may be functions, as above; the +HUD is read again on a change). `gods-eye-view/layers/rail/paths` is the +Rail layer's pure path module (`createRailPath`, `pointAtS`, `projectOnPath`) +for a provider placing a train along its line. The frame, HUD view and +candidate fields are documented in `src/cockpitSubjectProviders.js`; the Rail +and Transit read APIs in `src/layers/rail/cockpitSubject.js` and +`src/layers/transit/cockpitSubject.js`. A snapshot read again while nothing in +it changed is the one read before, so `read` may take one on every update; a +train's `path.line` is a frozen copy of its line, for `pointAtS` and +`projectOnPath`. The `layers/rail/paths` export and the +Rail and Transit read APIs (`getSelectedTrain`, `getSelectedVehicle`, +`getCockpitSubject` and the snapshots they return, `path.line` among them) +are experimental and may change without notice. + +A candidate's `selectedAt` is a token that changes each time the user selects +the subject, even the same one again, so entry counts it as selected then; a +new `id` under the same token is the same selection (a train's selection +moving to another feed's copy of it). The Rail and Transit snapshots give one, +`selectedAtMs`: when the user last selected the train or vehicle by a click or +`focusTrain`/`focusVehicle`. It is null after a deselection and for one +selected only by a hold, since a hold is not the user's selection. + +A frame with `heightM: null` stands on the shared floor, or where it last +stood while that floor is cold. If no height has been known since entry, the +view waits, showing ACQUIRING SURFACE, for at most five seconds +(`COCKPIT_GROUND_WAIT_TIMEOUT_MS`), then ends and releases the subject. + +`hold(id)` returns `true` once it holds the subject, or `false` to refuse +entry; any other answer, `undefined` included, refuses entry too, with one +warning. A refused hold, and one that throws or returns a promise, is followed +by `release(id, { restore: false })`, again once a returned promise settles, +so `release` must be harmless for a subject it does not hold and when called +more than once. + +Leaving the view does not track again an aircraft that was tracked before +entry, as with the bridge and orbital views: when the user leaves by the exit +control, the map goes back to the ridden subject through +`release(id, { restore: true })`. diff --git a/docs/CODE-BOUNDARIES.md b/docs/CODE-BOUNDARIES.md index 591db02dcb..2852bea0ae 100644 --- a/docs/CODE-BOUNDARIES.md +++ b/docs/CODE-BOUNDARIES.md @@ -33,12 +33,13 @@ export inventory. Use declared exports rather than reaching into internal files. | `src/layers//` | Source acquisition, records and Cesium resources with explicit controller/renderer owners | | `src/sources/` | Portable protocols and source contracts; request state belongs to each factory instance | | `src/services/` | Supplied application operations; scene construction owns caches and cancellation | +| `src/render/` | The renderer contract, the stub renderer, the conformance suite and Cesium renderer pieces | | `src/voice/` | Portable action schemas/session, common controls, action execution and separate protocol adapters | | `server/providers/` | Node route factories, process-scoped provider caches and shutdown cleanup | | `server/standalone/` | Environment, local settings writes and server composition | See [application construction](APPLICATION.md) and the -[infrastructure contract](INFRASTRUCTURE-LAYERS.md) for construction interfaces. +[infrastructure contract](INFRASTRUCTURE-LAYERS.md) for construction interfaces, and the [renderer contract](RENDERER-CONTRACT.md) for what a renderer provides. ## Import direction gates @@ -149,7 +150,8 @@ Google credentials are resolved on each request; the default uses the existing server-key precedence, and callers may supply `resolveApiKey`. `gods-eye-view/sources/places` exports portable response projections for Google -place results and OSRM route results/profile aliases. These functions own no +place results and OSRM route results/profile aliases, and the turn-by-turn +steps (`normalizeOsrmSteps`) Core's `/api/route` serves with `steps=1`. These functions own no credentials, requests, caches, environment loading, or rendering. Callers retain input validation and upstream-response acceptance. The boundary check builds this entry independently and rejects Node imports. @@ -293,9 +295,9 @@ the user's later collapse choice, including body remounts. Mark the body `max-height` and puts the scroll offset back afterwards. Panel bodies only scroll on an open-card change, with one write, never on a refresh. -Compose `createRailCards({ container, document, onParams, onOpen })` and -`createRailTimeline({ container, document, onCommit, onPreview, onStep, -onLatest, onPlay })`. Cards reconcile `{ id, title, badge, open, compact, +Compose `createRailCards({ container, document, onParams, onOpen })`. Rails +have no time controls of their own; the world timeline moves time. Cards +reconcile `{ id, title, badge, open, compact, compactStatus, blocks }` in place. Their full-width native button headers expose `aria-expanded` and `aria-controls`; articles expose `data-open`. The feature adapter owns accordion state. Generic cards do not select data or enable layers. @@ -330,10 +332,9 @@ consumers. They expose `summary.settings`, `summary.actions` and optional subscriptions still refresh the cards. Cards own configuration and readings. Weather orders cyclones, wind, then a bordered Observed history group containing -the timeline and active radar, satellite and lightning cards. The group heading -and scope name its active products. The timeline stays visible whenever any -observed product is enabled; fewer than two ticks disables transport. Pass -`heading: false` to the timeline when the containing group owns the heading. +the frame time and active radar, satellite and lightning cards. The group +heading and scope name its active products. The frame time shows whenever any +observed product is enabled and has a frame; the world timeline moves time. Exactly one active card is open. Header clicks and newly enabled ids choose it (the last new entry wins a batch); refreshes and clock ticks retain it. First appearance uses cyclones with storms, otherwise the first card. Disabling the @@ -341,7 +342,7 @@ open layer falls back to the first remaining card. A WeakMap per document keeps explicit choices through body remounts without adding share state. Card opening, storm selection and layer enabling remain independent. -Optional card/badge/slider class names provide feature styling. Card titles use +Optional card/badge class names provide feature styling. Card titles use `.data-name` typography; meta/time/badges use `.data-toggle-meta` typography; setting/result labels use `.panel-title`; chips retain `.data-toggle-chip`. Reserve one status line, even without a legend. Use app tokens. Wind's footer @@ -471,6 +472,13 @@ release listeners; pending action feedback is limited to its current owner. rendering, HUD and share operations. `src/standalone/controls.js` provides the running application's instances. The shell imports no standalone bootstrap or concrete live layer implementation. +The shell reaches the renderer through its ports alone, and loads no +renderer: given a viewer with no renderer bound, load +`./render/cesium/unbound` once first, which also provides the celestial +ring's precise ICRF rotation (`src/sky/icrf.js`; until then the ring uses +the TEME approximation). Whether Cockpit's aircraft is an entity of the +viewer's own is the `viewerDrawsEntity` service's to say; the application +scene supplies it. Panel layout, position/drag, notices, recording and deferred UI work have separate owners with synchronous cleanup. Existing scene, share and HUD engines retain their entry points. `ui/styles` loads the ordered stylesheet entry; component @@ -508,6 +516,15 @@ perform no network requests and discover no additional modules. standard sources and their setup/fallback policy. The standalone facade wires these to the application's render governor. +`maps/imagery`, `maps/terrain` and `maps/3d` are the Cesium renderer's +(`src/render/cesium/`). `maps/controller` and `maps/defaults` are +Cesium-free: they make their scene changes and build their providers +through the map engine the renderer provides as it loads +(`src/maps/engine.js`). The application's renderer provides it; with a +viewer with no renderer bound, load `./render/cesium/unbound` once first, or pass the +engine as the controller's and `createDefaultMapSources`' `engine` option. +Without one, constructing a controller throws, naming that export. + A registry supplies `sources`, `defaultId`, `unknownId` and optional `recoveryId`. Each source has a user-facing `descriptor`, availability/reason, and either an `imagery({ signal })` factory or a supplied `tileset`/`createTileset({ signal })`. @@ -572,6 +589,13 @@ separate from standalone setup. Scene construction returns these operations; the catalog and controls use the same surface owner. Layers still own their individual ground-snap caches and model resources. +The entry is Cesium-free: ground snapping and mesh floor sampling ask the +renderer's globe (`isSettled`), camera (`pose`) and query (heights) ports, and +see through the caller's draw sets by id. A viewer with no renderer bound needs +the Cesium adapter's factories loaded (`gods-eye-view/render/cesium/unbound`) +first; until then the snap and the sampler answer nothing and location framing +throws, naming that export. + Terrain cancellation rejects late replies before caching, clears floor queues and removes the map-stack listener. Annotation lookup caches are instance-owned and cleared on cancellation. Geometry selection and floor policies are unchanged. @@ -634,8 +658,9 @@ source-time fallback and model-owned ground policy. The renderer supplies that ownership fact and handles stale-ground lifting, Cesium history and primitives; record reconciliation does not import the engine or application. -`layers/vessels/records` owns plain AIS metadata, stable MMSI identity and bounded -retention. `layers/vessels/ingestion` owns source requests and feed state through +`layers/vessels/records` owns plain AIS metadata, identity by the stable id the +source gives (an MMSI only for a feed that has nothing else; the MMSI itself is +an attribute) and bounded retention. `layers/vessels/ingestion` owns source requests and feed state through explicit operations. Both exports exclude Cesium, DOM and application assembly. The snapshot renderer applies record changes; rendering owns a weak map of geometry and billboard resources used by cards, picking and trails. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 165343fb91..9f7bdf68c6 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1,5 +1,33 @@ # God's Eye View Current State +An aircraft (civil or military) faces its reported ground track, else its +true heading (readsb `true_heading`). With neither, it faces the way its own +fixes went (`courseFromFixes`, `src/data/courseFromFixes.js`): the course runs +from an anchor fix to the newest once they are 30 m apart, and the anchor then +moves on, so frequent fixes of a slow aircraft add up while position noise on +a parked one never makes a course. A fix that is not a second newer (a repeat, +or an older position from another feed) and one reported slower than 2 m/s +give no course and keep the last; an aircraft with no course at all faces +north. + +While anything moves (a layer in motion, the camera, a followed contact), the +globe draws at the display's own refresh rate; there is no fixed 60 FPS cap. +The render governor (`src/renderGovernor.js`) caps a parked scene at +`IDLE_FRAME_RATE` (60) ticks a second while nothing holds the loop, because +Cesium still runs the clock, data sources and update listeners on every +animation frame even when it skips the draw, and lifts the cap while anything +does: the frame port tells it when the loop's first hold is taken and its last +released, its own holds (animated visual styles) included. The viewer starts +at that cap until the governor is installed. Through the idle +render governor, the camera port holds continuous render from `moveStart` to `moveEnd`, and samples its +pose every 250 ms in between, so a camera drifting by rounding errors (no +`moveEnd`) is released after half a second at rest and held again if it moves. The world clock holds continuous render while +it plays away from the live edge (not while it steps or waits for data), so +playback draws at the display's rate too. Waits that used to count frames (a followed contact's first +position, a shared follow view) count drawn time +through `src/time/frameWait.js`, at most 100 ms a frame, so they last the same +at any refresh rate and a background tab does not use them up. + Docker Compose mounts the checkout with the shared SELinux `:z` label so containers can read it on enforcing SELinux hosts. The separate image-owned `node_modules` volume and loopback-only port publishing remain unchanged. @@ -76,7 +104,7 @@ does nothing, wherever it starts. Rotation drags that start on the planet, and zoom, are unchanged. How much of the frame shows the planet's surface is measured by casting a 32×18 grid of view rays at the ellipsoid; while the scope mask is on (the default) only the rays inside its keyhole count, since the mask -hides or dims the rest. Voice tilt and in-place turns of a free 3D camera above +hides or dims the rest. Voice tilt and in-place turns of a free camera above 1,000 km stop when about a tenth of the frame still shows the surface (or about as much as it showed when it started), never less than about 1% of the visible frame, and a view that already shows less only keeps or gains what it has. A @@ -107,7 +135,7 @@ Views with more surface than that, such as the oblique orbital Director shots, are left as they are, and so are tracked or locked cameras, a camera flight in progress, a Director scene while it plays (holds included), a pointer held down on the globe (a drag held still; with several fingers down, until the -last is released) and the 2D and Columbus modes; a check a flight, scene or +last is released); a check a flight, scene or held pointer defers runs once it ends. A release outside the window that the page never sees counts as given once the window loses focus, the page is hidden, the canvas loses the pointer's capture, or the pointer moves with no @@ -118,6 +146,11 @@ it is until the next move. A voice turn requested while the camera is tracked is judged by the pose voice's release of the follow camera will leave, before that release, so a refused turn keeps the tracking. +The app draws only the 3D globe: the renderer it draws through has no 2D or +Columbus view. Voice tilt, in-place turns and the move-end recovery above are +written for that globe alone and carry no check for the other scene modes, +which in Cesium's 2D and Columbus views made them do nothing. + Analyst region queries resolve unique Natural Earth names offline without geocoding, so Gold Coast and Ivory Coast name the West African natural regions. Duplicate names require a geocoded containment anchor; when several entries for @@ -167,6 +200,49 @@ across the antimeridian, so they cannot use the strict ±180 check as-is, and `src/sources/adsbRecords.js` and `server/providers/common/geo.js` keep their own implementations. +## Shipwrecks — EMODnet and Wikidata + +The Events group includes **Shipwrecks** (`shipwrecks`, share-link token `01`), +off by default. `/api/shipwrecks` downloads EMODnet Human Activities' +`emodnet:heritageshipwrecks` WFS layer (about 7,000 wrecks in European waters +compiled from SHOM, Ireland's National Monuments Service, Historic England and +the Oxford Roman Economy Project; CC BY 4.0) and a Wikidata SPARQL query for +shipwreck items with a coordinate and at least one Wikipedia article (about +1,450 worldwide; CC0). A source that answered well is asked again after 24 hours; +one that failed is asked again after 15 minutes. Each source keeps its own last +good records: a source that fails, answers with nothing usable, or answers with +less than half of its last good set keeps serving its earlier records as stale +for up to seven days, and never removes the other source's wrecks. When the +page cannot refresh, the wrecks it shows are marked stale, and it removes them +once even the newest source is past seven days, counted from the ages the +proxy reported (so the page and server clocks are never compared; a wreck +both sources list is one record, so nothing is removed per source). EMODnet rows the portal took from +wrecksite.eu are skipped (that site is not openly licensed). A Wikidata wreck +with the same name within 3 km of an EMODnet wreck is merged into one record +that keeps the article link and takes EMODnet's year, sinking text, depth and +position accuracy. Only ship columns are read: EMODnet's long histories +(`ship_char`, `obj_desc`) are not. Sinking, cargo and description text that +refers to a person by a title or role (Mr, captain, master, owner, crew, +"reported by", …) is dropped whole by a keyword filter; a bare name with no +such word can still pass. Deaths appear only as a Wikidata count. + +The globe draws a round marker with a hull and mast per wreck, all in one +billboard collection, ground-clamped with the depth test off and the horizon +cull GhostMaps uses, sized by deaths (a bigger toll draws on top) and coloured +by era (a legend under the row): before 1900 (ancient wrecks dated only by +period count here), 1900–1945, after 1945, and date unknown. A period filter +under the row picks a start year and an end year side by side (two pickers +over the years that have a wreck; a reversed pair is stored swapped); undated +wrecks show only when every year is selected. The filter is session-only (not +in the share link). Clicking a marker opens a `stateless` card: deaths and +survivors first, then the sinking date or year (or the archaeological dating) +and waters, vessel type, what happened, least depth and its quality, how well +the position is known, period notes or the Wikidata description, cargo or +finds, protected status and source. +Clicking the card opens the Wikipedia article (else the Wikidata item), the +wreck's own web page when EMODnet lists one, else EMODnet's portal. Voice does +not toggle this layer yet (prompt budget, as for the airspace layer). + ## Wildlife Sightings — iNaturalist and Acartia **Wildlife Sightings** (`wildlife-sightings`, share-link token `9`) is off by @@ -322,6 +398,30 @@ The source factories are exported at `layers/directions/source` and `layers/recent-imagery/source`. Configuration is applied at construction time; this does not introduce live source replacement. +Application catalog composition also accepts an optional `placement`, a +host-supplied placement provider (`src/data/placementProvider.js`): an object +whose `layer(kind)` returns, for `aircraft`, `military`, `vessels`, `transit` +or `rail`, either null or `{ place(id, wallMs), observe?(id, fix), +forget?(id) }`. While live, each of those layers tells it every fix it accepts +(time, position, the height it draws the fix at, reported speed, course and +ground state) and draws a contact where `place` puts it: position, height +(the layer's own when none is given), course and speed. A null answer, a +provider that throws, a kind it leaves out, or no provider at all keeps the +layer's own motion, unchanged; following the world clock, the layers never +ask it. A tracked aircraft or military aircraft the provider places keeps its +trail joined to it: the trail runs up to the time read off its own reports +where the aircraft is drawn, not the layer's display delay, so it neither +stops short of the aircraft nor runs on ahead of it, and it is drawn from the +first report behind the aircraft. Transit and rail vehicles a provider places are advanced every frame +in view while their placed position changes; one it holds still lets the +render loop idle and is asked again each second, moving on once its placement +does. A placed transit vehicle is drawn at its placed point, and a placed +train where it is placed rather than on its bound railway line. Live vessels +a provider places move on between refreshes: redrawn in place every frame, +with the next frame asked for as soon as the fastest drawn vessel will have +moved half a pixel on screen, at least once a second while the provider places +any drawn vessel, and none once the layer is off. + Application catalog composition accepts an optional `streetLevelProviders` list. An explicit list replaces the default Mapillary provider; an empty list removes all imagery providers. Without that option, Mapillary is registered only when @@ -341,6 +441,381 @@ provider registration rejects compositions that cannot fit rather than truncatin identities. A malformed or duplicate entry invalidates the complete custom-switch field. Existing whole-link size limits still apply. +## Data Library — October 21, 2026 + +DATA LAYERS keeps its curated core layers; everything else lives in the Data +Library, opened from **Browse data library** at the foot of the panel. An entry +is a manifest in `src/library/entries/` that points at a live upstream its +provider hosts — a query API, a provider-hosted static file or a tile endpoint. +Nothing an entry describes is bundled, so a self-hosted instance serves every +entry without hosting data. Manifests are validated strictly when +`src/library/catalog.js` loads (unknown fields are errors), so an invalid entry +fails the unit suite. Authoring guide: [DATA-LIBRARY.md](DATA-LIBRARY.md). + +Three kinds ship. A `dataset` (GeoJSON, GeoJSON Lines, CSV with lat/lon +columns, a JSON record list read from `source.records` with named or guessed +lat/lon fields, or a paged ArcGIS FeatureServer query) renders through the same +GeoJSON layer as Datacenters and Dams, with the manifest's label, up to two +card fields and an optional `rank` field that orders a capped set and feeds the +layer's level-of-detail priority (0–600, below the named/unnamed gap). A capped +dataset reads PARTIAL. A dataset with `source.view` is view-bounded, +for layers too large to load whole (FEMA USA Structures: ~135 million +footprints): below `view.maxAltitudeM` it queries ArcGIS for what intersects a +window around the point the camera looks at (half the camera height each way, +330 m – 5.5 km, clipped to the visible rectangle), one page per view after the +camera settles, replacing the previous set only when the new one is ready and +aborting a superseded request; above it the row reads "zoom in to load this +layer" and nothing is fetched. Footprints are ground-clamped polygons (draped on +Google 3D tiles too), without outlines. Zoom to layer lands straight above the +manifest's `view.sample` area at 60 % of the altitude limit. View-bounded +entries are ArcGIS or GeoParquet, and browser-direct, in this build. + +`geoparquet` datasets are read in the browser with `hyparquet` (with `fzstd` +for ZSTD), imported lazily on first use; only the columns an entry uses are +decoded, and WKB geometry arrives as GeoJSON. A partitioned set +(`source.partitions`: an S3 ListObjectsV2 `listUrl` and a `keyBase`, both on the +source host) must be view-bounded. Its index — each file's GeoParquet footer +bbox, read with one range request per file — comes from `/api/library/index/` +(built once per `cacheSeconds` and shared), or is built in the browser and kept +in `gev:library:index:` on a static build. Footer bboxes can be stretched +by stray geocodes, so candidates are ranked by how much of each file's bbox +the view covers, read in parallel batches of four (up to eight per view) +until a batch has features in view, and each file read once teaches its real +extent (the box holding 98 % of its points, `gev:library:extent:`), so +later views skip files that do not cover them. The last four decoded files +stay in memory. `display.colorBy` colours each feature by a field's value (a +dotted path such as `categories.0.title` is flattened into the feature's +`__gevColorKey`): view-bounded layers draw 6 px dots or filled polygons, other +datasets keep the GeoJSON layer's stems, cards and level of detail with a +per-feature colour (`featureColor` in `localGeojsonCore.js`). Values sharing a +`colorBy.labels` label form one legend group (coal, gas and oil are "Fossil"); +values the manifest does not colour draw in `display.color` and count as +Other. The row legend lists each group with its count (in view, or in the +loaded set), one item per line as Fire Perimeters' does. Status-like fields +(GDACS and PortWatch alert levels, NWS severity, bridge condition) use the +fixed status palette (good #0ca30c, warning #fab219, serious #ec835a, +critical #d03b3b); categorical ones (fuel, EONET category, building +occupancy) use at most four hues that pass all-pairs colour-vision checks on +the dark globe, plus a neutral Other. Tile layers carry a static +`display.legend` copied from the provider's own scale (GBIF classic.poly, +JRC occurrence, Macrostrat's ICS period colours). Aerial photo layers (IGN, GSI +photos, swisstopo SWISSIMAGE) set `display.outline`: their covered countries' +borders draw as a thin white ground-clamped line, so the imagery's edge is +plain, with a "Coverage outline" legend item. Borders come from Natural +Earth's 1:50m admin-0 countries (public domain, fetched live once per page and +credited); `countries` draws every part (Japan's islands, Liechtenstein beside +Switzerland), `coverage` only the parts inside `coverage.bbox` (metropolitan +France). A failed border fetch costs only the +outline. The same layers set `display.aerial`: they drape above every other +imagery layer and raise themselves again whenever another drape is added, so a +basemap or weather overlay switched on later goes underneath. Each is +`source.bounded` (tiles requested inside `coverage.bbox` only) and names its +provider's no-imagery fill in `display.noDataColor`, drawn transparent through +Cesium's colour-to-alpha (max channel distance 0.02): measured fills are +swisstopo white, IGN's flat ocean blue (#0a3b59) and GSI's ocean grey +(#343434). Without both, a white fill covered the whole globe. A 4xx tile +answer counts as "no imagery here", never as a tile error. IGN's overseas +departments are outside its single bbox and are not shown. The aerial set now holds 60 +entries: 57 imported from the Open Imagery Register (national programmes in +Belgium (Wallonia), Germany, Estonia, Spain, Poland, Portugal, Australia's +NSW, and 49 US services: NAIP plus state, county and city programmes) plus +IGN, GSI and SWISSIMAGE, each with an `imagery` +block (type, published resolution, true ortho, years flown, refresh) that +Browse shows as a spec list. Tiles take `xyz` (with `{reverseY}` for TMS) or +`bbox` templates (`{bbox-epsg-3857}`: WMS GetMap and ArcGIS export, filled +by Cesium in the browser and by the proxy from z/x/y). Sub-national entries +draw a `bbox` rectangle outline without fetching the country borders. 35 +entries whose licence the register gives only as "see publisher terms" are +operator opt-in. Norway comes from Kartverket's open +services (CC BY 4.0, "© Kartverket"; its zoom 12–20 Geovekst data may be shown +in live services but not copied): the topographic, greyscale, raster-topo and +nautical-chart caches (`xyz`), and WMS hillshade, DTM colour relief, sea depths +(from zoom 11, Kartverket's 16-class depth legend), county and municipality +boundaries, and the cadastre (from zoom 14). Norge i bilder needs +authentication and is not included. `mapterhorn-terrain` is the first +`source.encoding: terrarium` entry: Mapterhorn's global 512 px terrain-RGB +tiles are decoded per tile in the browser (`src/library/relief.js`) into +shaded relief with a six-class elevation legend in metres. A `tiles` entry (`{z}/{x}/{y}` template) drapes on the +active imagery host — the globe, or the Google 3D tileset — and follows map +stack switches; with no host it shows the existing "choose a globe map" +guidance, and its row reads DRAPED rather than a count. A `pack` describes an +existing host-layer source pack (today the opt-in CCTV packs): it is +informational in Browse, names the host's own switch (`CCTV_NYC_ENABLED=1` and +so on) and offers no Add. The `provider` kind from the RFC is refused by the +validator until it ships. + +Entries register their layer only when a viewer adds them, after the core +catalog is sealed: `LayerLifecycle.registerLibraryLayer` accepts only ids in +the `lib-` namespace and only after `finalizeRegistrations`, and +`unregisterLibraryLayer` destroys them. Library layers never enter +`LAYER_STATE_REGISTRY` or the core token ledger. The panel groups them under a +**Library** heading after every core group and rebuilds its rows on a +`registrations` activity. Add switches the layer on; Remove destroys it. +A library layer's row carries two icon chips, on or off (the panel shows +row controls for an off layer only for Data Library rows, whose chips are +marked `whileOff`): **Zoom to layer** +(`zoom_in_map`) flies to the extent of the loaded features, or a tiles entry's +declared coverage, taking the shorter way round the antimeridian and showing the +whole globe for world-scale sets; **Remove from Data Layers** (`delete`) +removes the entry. Zoom on a layer that is off switches it on first (a +dataset only knows its extent once loaded). Zoom runs as an immediate +navigation (`layer`), so Cockpit +refuses it with its own message and the current follow owner is released first; +reduced motion flies instantly. Icon chips (`chipGroup.js` `icon`/`action`) use +their label as accessible name and tooltip and carry no `aria-pressed`. + +This browser's selection persists in `gev:library:v1` (`{ added, on }`), written +only for explicit (user, voice, tool) changes, like core layer state, so a +Context session's temporary changes are not remembered. Share links carry the +switched-on entries as `lib=.` with the permanent two-character tokens in +`src/library/ledger.json` (append-only; packs take none). A link's entries join +the viewer's library and, as for core layers, the link alone decides what is +on. Unknown tokens are skipped. The live hash follows the existing +initial-restore suppression. + +Browser-direct entries are fetched without cookies or a referrer, redirects +refused, bodies capped while streaming. Proxied entries go through +`/api/library` (`server/providers/library.js`): `/catalog` reports each entry's +availability and reason (`operator-opt-in`, `operator-disabled`, `key-missing`) +without secrets; `/data/` and `/tile////` reach only the +manifest's fixed upstream (the browser names an id, never a URL), refuse +redirects and off-manifest hosts, cap dataset bodies at the manifest's +`maxBytes` (≤ 32 MiB) and tiles at 2 MiB of `image/png|jpeg|webp`, cache per the +manifest's `cacheSeconds` (60 s – 24 h; at most 512 tiles), serve the last good +dataset as stale on failure, rate-limit per client, and never return upstream +text. A keyed entry must be proxied; its key comes from the server environment +through the key registry and its routes use the strict cross-site gate, while +keyless routes use the keyless gate so they work behind a reverse proxy. +Operators opt entries in with `GEV_LIBRARY_ENABLE` and remove them with +`GEV_LIBRARY_DISABLE`. A static build with no server still serves every +browser-direct, non-opt-in entry; proxied ones say they need the app's server. +The proxy is a fetch handler (`createLibraryHandler`, exported as +`gods-eye-view/sources/library`) that the dev server mounts behind its gates. +Another server can mount it with `listed` (hide entries: the catalog marks them +`listed: false` and Browse leaves them out) and `proxied` (route browser-direct +entries through it: the catalog marks them `fetch: "proxied"`). A routed +view-bounded entry asks for its box snapped to a power-of-two grid +(`libraryViewBox`, `?bbox=` on `/data/`); GeoParquet entries are read on the +server then. Tile, data and complete index answers carry `public, +max-age=` (`private` when keyed). `createApplicationTools` +takes `library.fetchTile` and `library.fetchData` so an application can fetch +library tiles and proxied datasets through its own cache. + +The Browse dialog is a `dialog[data-panel-surface]`: modal, labelled, search +focused on open, Escape and backdrop dismiss and return focus to Browse, and it +closes when clean view, recording or Cockpit hides the panels. Its surface is +frosted glass (a lighter `--glass-bg` than the rails, a 22 px backdrop blur +clipped to the theme's frame, a barely dimmed backdrop), so the globe shows +through without the HUD text behind it competing. An added entry that is on +offers ZOOM, which closes the dialog and flies to it. Above the intro, four +stat tiles summarise the library: Datasets (every entry, broken down by kind), +Themes (how many distinct themes the entries cover), Added (and how many are on +the map), and Map features (features loaded by dataset layers that are on; +tiles have no count). +They refresh with the dialog and once a second while it is open, so counts +land as datasets finish loading. The line beside **REMOVE ALL** answers the +filter ("Showing 2 of 8"). **REMOVE ALL** removes every added entry; its first +press arms a confirm for four seconds. It lists +addable entries first, then entries this instance would need to switch on, then +packs, with kind, status, opt-in or key badges, provider, coverage and a licence +link, and filters by text, theme and "only what this instance serves". +Archived entries are hidden unless added. An entry's attribution and licence are +registered in the Data attribution popover while it is in use. + +Seeds: NASA EONET open events (GeoJSON, browser-direct), EIA US power plants +≥ 100 MW (ArcGIS, browser-direct, ranked by capacity), Smithsonian GVP Holocene +volcanoes (WFS GeoJSON, proxied — the upstream sends no CORS headers), NASA +Black Marble 2016 night lights (tiles), and the NYC, +Lithuania and FL511 CCTV packs. Added from the Ask dataset registry (its live, +mappable sources that are not core layers): the WRI Global Power Plant Database +(provider-hosted CSV, the 10,000 largest of ~35,000 by capacity, so it reads +PARTIAL), NWS active alerts that carry their own polygon (zone-wide alerts have +no geometry and are dropped), NOAA CO-OPS tide stations (JSON records), and IMF +PortWatch chokepoints and port disruptions (ArcGIS, operator opt-in until the +reuse terms are confirmed, as Ask holds them in hosted mode). FEMA/ORNL USA +Structures (CC BY 4.0) is the first view-bounded entry; its service refuses a +query page smaller than its own 2,000 records, so the probe asks for a full +page. Addresscloud's EPC ratings for England and Wales (Source Cooperative, +read from `s3.us-west-2.amazonaws.com/us-west-2.opendata.source.coop`, 344 +local-authority GeoParquet files, OGL v3.0) are the first partitioned +GeoParquet entry, coloured by band A–G with the official EPC colours. From an +open/freemium registry review (commercial sources excluded): GDACS disaster +alerts; the National Bridge Inventory (view-bounded, coloured Good/Fair/Poor); +EPA Superfund sites and Toxics Release Inventory facilities (view-bounded); and +tile overlays for Macrostrat geology, GBIF biodiversity density, USGS +topographic and hydrography maps, IGN (France) aerial photos, BKG +TopPlusOpen, GSI Japan map and photos and JRC surface water occurrence. +Entries whose licence or provider pages no longer resolve (404 or unreachable +host, checked 2026-11-12) were removed: OpenSeaMap seamarks, EMODnet +bathymetry, SEDAC GPW population density, PDOK, basemap.at, Geneva SITG, +ICGC Catalunya, Luxembourg, Vlaanderen, Minnesota and Bangor aerial photos. `npm run library:check` validates manifests, +the ledger (append-only with `--base-ref`, run in CI on pull requests) and the +generated DATA_SOURCES.md section; `npm run library:probe` hits every upstream +once; `npm run qa:data-library` is the browser gate (fixture-backed). + +Shares: the compact `/share/` link carries the switched-on entries in +field 29 (docs/SHARE-LINK-FORMAT.md), so Copy Link keeps them, and a share +opened later in the same tab (pasted address, Back/Forward) restores them too. +Any share decides what is on, as for core layers: one with no library entry +on switches the recipient's stored ones off and leaves them listed. A tile +entry whose coverage needs more than 256 tiles at its minimum zoom (Norway's +cadastre from z14, sea depths from z11) is hidden below that scale through +Cesium's `minimumTerrainLevel`, so zoomed out it requests nothing. EPC +partitions learn two extents (`gev:library:extent:v2:`): every point's box +rules a partition out, the 98 % box only ranks it, so homes at a partition's +edge are found on later visits; the v1 trimmed-only key is dropped. A +partition index whose footers keep failing after two retries is +`complete: false`: neither the server nor the browser keeps it as whole, a +complete earlier index is served instead, and it is rebuilt after five +minutes. A view that leaves partitions touching it unread is PARTIAL. Listing +pages and footer reads are size-capped and ranges are validated. The Browse dialog is a Vue view (src/ui/views/panels/DataLibraryDialog.vue +and DataLibraryCard.vue, teleported to the body from LayerPanelsView) over the +`gev-data-library` Pinia store; src/ui/libraryBrowser.js is its framework-free +owner (open state, filters, the rows they show, Remove all) and the text +helpers the view renders, so every label follows the locale. Only the modal +open/close and focus moves are imperative. + +## Stories — November 13, 2026 + +A Stories button (top right, `#hStories`) opens Explore: a feed of stories +over GEV's own globe with their pins, then a Story screen with a +timeline, chapters and context. Every GEV page loads only what the +closed state needs: the boot shell (`src/stories/boot.js`), the store, +`StoriesView.vue` with the Stories button, first-visit popup and +back-to-story toast, and their styles (`stories-entry.css`). The screens +(`ExploreScreen.vue`, `StoryScreen.vue` and their parts), their styles +(`stories.css`), the story data (`storyMeta.js`, `catalog.js`) and the +controller are separate chunks fetched together on first open, on a +`?stories=` / `?story=` link, or on Back or Forward into Stories; a failed +fetch is reported and the next attempt tries again. Stories keeps its place +in the query, not the share-state hash, with one history entry per screen; +Close steps back over those entries, so Back afterwards does not reopen it, +and share links carry the Stories screen and place. Explore links use +`stories=explore` and optionally `selectedStory`. Player links use `story` +and optionally `storyTime` in milliseconds, opening paused at that time. +GEV's share link keeps +`history.state` when it rewrites the hash, so Stories' entries survive. + +Every story is a GEV scene, played on the person's own globe through +`SceneDirector`, with its labels, embedded media, A/B imagery split (marked +`data-globe-overlay`) and data-pack cards kept while the rest of GEV is +hidden. Explore lists the scenes the person saved to Stories from AUTHORING +first (`SceneDirector.storyScenes()`, refreshed on every `stories-changed`), +then the person's other scenes with a shot as drafts +(`SceneDirector.draftScenes()`, marked DRAFT), then the +scenes GEV ships with a camera path while they are in the project +(`SceneDirector.hasScene`). Zero-shot drafts can be reopened or deleted +from the scene selector in AUTHORING after a reload. A saved scene brings the card image and topics +picked for it in AUTHORING; the topic chips use AUTHORING's tag names and +order. Explore opens at country level +(2,500 km) over the first story and, while idle, flies on to the next story +every few seconds, for a minute after the last touch (never with a story +picked or with reduced motion). The start view and a picked story's place +(at an angle, −60°) are framed in the middle of the map Explore leaves +visible (`.ex-map`: beside the feed on a wide screen, above the sheet on a +phone), not of the whole canvas; a flight that lands after that area has +moved makes one short correction. Stories reaches the globe only +through the renderer's ports (`src/render/rendererOf.js`): its flights, +pose and Close's restore go through the camera port, and after each landing +a continuous-render hold keeps the globe drawing only until the globe port +reports the base settled (at most 10 s). Each story's pin, in the +world overlay's label style (`src/overlays/worldOverlayTokens.js`), is placed +from the query port's projection in the frame port's `postRender`, on every +drawn frame, written straight to the pin's transform, and hidden behind the +globe (`query.isOccluded`); the pins ask for no frames of their own. Card +images are drawn from the keyless Esri World Imagery tiles around the +story's place (`src/stories/thumbs.js`: the same Web Mercator tiles, from +the same host, that GEV's Esri map draws, read as images) unless the scene +has its own; with any other map stack than Esri Satellite +(`mapStackController.getActiveId()`) the card shows its placeholder, and a +card drawn from Esri earlier is dropped. AUTHORING captures thumbnails only +on a ready Esri World Imagery stack and embeds the imagery credit in the +exported image. A shot +tied to an anchor rather than a place pins the whole-globe view. + +A shipped story's context comes from what GEV knows about it +(`src/stories/catalog.js`): what it shows, the place each shot goes, and, +for each layer it turns on, what the layer shows and the data sources +DATA_SOURCES.md lists for it. The Nepal story carries the event pack's own +facts and sources (Vantor imagery and the GeoPera reconstruction, CC BY-NC +4.0), and its key moments are the chapters that show them. Topic chips and +region choices are the ones the listed stories carry. Closing Stories after +a story played puts AUTHORING's own selection back; +Open in GEV leaves the story's scene selected there. Entering Stories +cancels in-flight Authoring work before it captures the view it will +restore. Dragging the timeline previews the time, and releasing +it seeks the globe once. Play after a pause, a seek or a paused link goes on +from that exact moment (`SceneDirector.startScene` with `fromProgress`), even +inside a shot or its final quarter-second: the camera, the hold, the scene +clock and the layers' reveals carry on from there (a clip that moment falls in +starts again from its beginning, and the hold waits for it, with the +timeline held at the shot's end meanwhile). A scene that has actually ended replays from the +beginning. + +Opening Stories claims the camera through the shared navigation policy, so +orbit, a tracked contact or a flight end, and Cockpit refuses with the +policy's own toast ("Exit cockpit to open Stories"). Those owners are not +started again on Close: the camera and the world clock (`src/time/worldClock.js`: +live, or the time it showed, playing on as if never paused) come back, a +follow or orbit does not. While Stories is open it owns the keyboard (`src/stories/keyboard.js`): +a key pressed in Stories stops at its root, and a key pressed anywhere else +stops at the window, so none of GEV's document-level shortcuts act behind it, +except on a playing GEV scene's own on-globe controls (`data-globe-overlay`); +the capture-phase listeners (hold Space to talk, a surface's Tab trap, the +wildlife card's Escape) check `body.stories-mode` themselves. "Open Stories" +works from voice or typed AI chat. Entering Stories ends active or pending +microphone capture and blocks microphone starts while Stories owns the +globe. Stories shows a notice when it turns off an active or connecting +voice session. A typed reply can finish after opening Stories. Globe tool calls +are refused while `stories-mode` is set ("Close Stories first"). + +The address bar names only the story while Stories is open. Stories holds +hash writes (`ShareLinkManager.holdWrites`) and saves a snapshot of the live +globe, including when it opens from a story link without a hash. +Close dismisses the Stories screens and keeps the keyboard and microphone +guards until the previous view is back. The director is waited +on until idle (`SceneDirector.whenIdle`: no run and no pending LOAD, seek or +interaction; at most 15 s). When the 15 s run out, the scene's layer cleanup +still under way is revoked (`SceneDirector.revokeSceneRelease`) before +anything is put back, so it cannot turn off a layer Close restores. The camera and world clock are put back (a clock +nothing moved while Stories was open, with no jump and the same mode and +rate, is left alone), unless a +camera owner took over during the wait (a drag on the globe, a layer's +focus). History steps back over Stories' entries; once that lands (or after +2 s if it never does), the saved share state is re-applied directly +(`ShareLinkManager.restore`, since the share link skips a hash it already +knows) and the share link writes the live view again. Back out of Stories +re-applies it the same way, and Back to Explore from a story re-applies it +once the scene has torn down, with the address still naming only Stories. +"Open in GEV" (GEV scene stories only) closes the +same way but keeps the place and look: nothing is put back, the scene and its +current shot are selected (`SceneDirector.selectShot`) and the Scenes panel +opens for authoring; Back then goes to the page before Stories. A Close or +open made while a traversal is landing runs once it has landed; a second Back +to Explore is ignored. Reopening Stories while a closed GEV scene is still +tearing down keeps the view from before Stories as the one Close restores. +Inside an inline embed Stories is not offered: the URL and history are the +host's. + +The Stories button sits left of whatever holds GEV's top-right corner: the +ACTIVE STYLE readout (`#style-indicator`), or an element marked with +`data-stories-corner` (with or beside the readout; one added after Stories +mounts is found within 20 s). On GEV's phone layout, +where neither shows, it is icon-only under the corner-actions column +(`#corner-actions`), aligned with its right edge. The first-visit popup +is a labelled region that does not take focus. The story page's rail offers +Open in GEV and Share only. Share on Explore reopens the list with the same +shipped story selected. A story link opens paused at the shared +point on its timeline. A scene of the person's own (saved or draft) +shows as theirs ("You") and has no Share: the project lives on this device, +so a link to it would open nothing elsewhere; a link to a story that is not +here opens Explore and says so. GEV's own credit line stays on screen throughout, inside the +Stories map while a scene plays (`creditPlacement` in +`src/stories/format.js`): `stories.css` places the renderer's own credit +display (`#cesium-credits`) and the application's credit line +(`#gev-credits`, `src/ui/creditsView.js`, with its list opening above it) +alike, and exempts both from the rule that hides GEV's chrome. + ## Utilities panel — October 29, 2026 UTILITIES is its own left-side panel, between Data Layers and Scenes, with @@ -361,6 +836,187 @@ panel that holds its row, and `set_panel_open` reaches it as `utilities-panel` or by "utilities", "draw", "drawing" or "import". On a phone it sits collapsed in the Layers sheet under Data Layers. +## The Visual panel — November 14, 2026 + +Visual (`#pp-toggles`, `src/ui/views/panels/DisplayPanel.vue`) is headed +VISUAL, has the edge switch in its header like the other side panels, and is +grouped from the top: Look, the six style presets with their 1–6 keys, and +Map source, the map source chips (`VisualPresets.vue`); Overlay, the HUD, +detection, style parameters, 3D aircraft, Scope and Clean UI; Effects, +Celestial, Bloom and Sharpen; and Reset to default at the foot. Each control +is a card (`src/ui/styles/visual-panel.css`) whose header row ends in an +on/off pill worded in the current language (Clean UI, an action, has none; +the buttons carry their state as `aria-pressed`). Under the Cyber HUD the +cards keep Cyber's own red skin. The presets and chips call the +same Display store actions as the dock's Visual Presets tray, which stays on +desktop and phone as before, along with Location; voice `Visual Presets` +still opens that tray. On a phone the More sheet shows that tray right above +Visual, so Visual leaves out its own presets and chips there. In Cockpit, +the groups that Cockpit's Display popover takes leave the panel as before and +keep their own styling there. + +Scope has an Opacity slider (`#scope-opacity-slider`, 50–100%, default 100%; +`SCOPE_OPACITY_MIN_PCT` in `src/ui/visualSettings.js`, since a fainter mask +reads as Scope off while labels still fade outside the keyhole) +that fades the whole mask (`setScopeMaskOpacity` in `src/scopeMask.js`, the +canvas's CSS opacity) without repainting it or changing the altitude +terminus; it is disabled while Scope is off and keeps its value. Share links +carry it as `sco` in the long form and field 30 in the compact form, written +only below 100%, so links made before it keep their codes and open at full +opacity, and a link without it sets the opacity back to 100%; a link asking +for less than 50% opens at 50%. Scenes do not +save it: a scene shot leaves the opacity as it is. + +Reset to default (`resetVisual` in `src/ui/displayBindings.js`) brings back +the out-of-the-box look: the Normal style, the first-run post defaults +(bloom off, sharpen on at 49%, the HUD shown, Dense detection at 75% +with its fade and outside opacity, the celestial ring off), Elastic +allocation, Scope on at 100% feather and 100% opacity, and 3D aircraft on in +Proximity. The HUD layout follows the Normal style, as choosing it does: the +Tactical HUD, except that the Cyber HUD stays Cyber. Inside Contacts, which +lends detection for the session, the reset's detection becomes what leaving +Contacts puts back and what a share link carries. It leaves the map source, the pinned scope terminus, Sonar's +settings, other styles' parameters, the layers and the panels alone. + +With Scope off the side rails, open panels and the dock's trays carry a soft +drop shadow and the rails' labels and icons a text shadow +(`src/ui/styles/scope-off-shadows.css`), so their edges hold against bright +imagery. + +## Side rails and the screen edge — November 14, 2026 + +Visual (`#pp-toggles`, the display settings, rail item `palette`) is the last +panel of the left column, after Data Layers, Utilities and Authoring, and +opens from the left rail like them (`PanelLayoutController`, falling back to +the right column in a host without a left stack). Context leads the right +column, followed by CCTV, Street Level and the other right panels. An open +Context or CCTV panel takes the column's full height; the other right panels +keep the content-sized layout and its hysteresis band. With nothing open, a +rail's icons and their names show as two glass pieces side by side; once a +panel opens, the icons stay in place and a highlight slides to the open one. + +Each collapsible panel header has an edge switch (`UiPanelEdge.vue`, +`src/ui/panelEdge.js`): it moves that side's panels over their rail to the +screen edge, with the rail as a row of icons above the open panel, and back. +The choice is per side, kept in `localStorage` (`gev.panelEdge`), and applies +on the desktop shell only: phones and Cockpit keep their own layouts and do +not show the switch. + +Scrolling the wheel at a screen edge (`src/ui/railEdgeScroll.js`, from the +edge to just past the rail, at most 84 px) steps that side's rail to its next +or previous panel instead of zooming the globe, wrapping round at either end. +One gesture is one step, trackpad coasting included, with at least half a +second between steps; a step that comes too soon is held until then and is +dropped if the pointer leaves the strip. Panels, controls, dialogs and the +world timeline in the strip keep their own wheel. The strip is off on phones +and touch screens, while the rails are hidden (clean view, recording), and it +follows the rails' sides in a right-to-left language. On a phone, Visual is in +the More sheet with the dock's Visual Presets, as before. + +## Context panel — November 16, 2026 + +Context leads with one card for whatever is picked. A click on anything a +layer can identify (`src/ui/entityContextBridge.js`, through +`src/data/pickedContext.js`) opens its card (`src/ui/stores/entityCard.js`, +`src/ui/views/panels/EntityCard.vue`): the item's facts from its record, a +route with progress for a flight, an altitude graph, the weather, local +time and news where it is, and the flights, vessels, hazards and warnings +within the radius the panel sets (25 to 2,500 km). Aircraft, satellites and +vessels are followed as they are picked; the card says Following only while +the camera follows the card's own item, and closing the card lets go. +Aircraft and satellites offer Enter Cockpit and Enter orbital view; transit +vehicles show their motion and fleet. A camera's card shows its latest frame +from the CCTV panel. + +With nothing picked, the panel describes the view +(`src/ui/views/panels/ViewContext.vue`): the place under the middle of the +screen and the towns around it from the Wikidata cities pack, the height, +the local solar time and daylight, what is in view per layer with live +counts and breakdowns, and the same weather and hazards. A search field in +the header narrows every list. Expanded, Context becomes a full-height +column at the right edge (the left edge right to left) and the map credits +stop short of it. + +The Contacts and Space Missions modes and the Radio strip stay in the +panel's main tab, below the card. When Contacts follows the aircraft the +card shows, its list sits inside the card. Turning Radio or Launches on +opens Context. The Properties tab holds the Labels and 3D aircraft +settings from Visual while a layer they act on is on. + +Context does its reading only while its panel is open. Weather and news +come through the regional brief service; earthquakes, tropical storms and +fire perimeters come from the same feeds as their layers, cached for five +minutes; satellite fire hits only while the FIRMS layer is on. + +The card's top tile previews what is picked. A flight shows its +Planespotters photo once the flights layer has looked one up for the plane +it tracks, its route on a small globe (origin to destination, flown part +solid, the plane on it), its fleet model turning with callouts of what can +be worked out about the flight, and the view ahead from its cockpit with +speed and altitude tapes; the model and the cockpit view take turns. A +vessel shows its Open Vessel Photos photo, a satellite the ground beneath it +from Esri World Imagery with its altitude and speed graphed. The globe, model +and cockpit view are drawn by the renderer through its `cardPreviews` +application hook (`src/render/cesium/cardPreviews.js`), each in a small scene +of its own that frees its graphics context as it closes; the model comes from +the fleet set loaded at startup, so opening a card fetches no model. + +## Wikidata cities pack — November 15, 2026 + +`src/data/local_data/wikidata_cities/cities.json` bundles 31,827 settlements of +15,000 people or more from Wikidata (CC0, 1.6 MB): name, position, population, +country and Wikidata id. `src/data/wikidataCities.js` reads it on the first +lookup and answers `nearestCity` (the largest city within 12 km, else the +nearest within 60 km), `citiesAround`, `findPlace` ("Paris, France", or the +nearest namesake within 150 km of the view, else the largest) and +`countryName`. Names match without case or accents ("lodz" finds Łódź). The +app never calls Wikidata; `scripts/build-wikidata-cities.mjs` rebuilds the +pack and fails if well-known cities are missing or a known grouping such as +the New York metropolitan area gets in. Nothing shows names from it yet; the +Context panel is its first reader. Sources and licence: `DATA_SOURCES.md`. + +## Data Layers finder and section index — November 15, 2026 + +The Data Layers header has a search button and a filter button +(`src/ui/views/panels/LayerFinder.vue`). Search opens a field under the +header that matches each layer's name on screen and its English name; Escape +closes it and leaves the panel open. The filter is a small popover with two +groups, Status (All layers, On, Off: whether the layer is enabled) and +Category (the list's groups, kept by their key, so a language change keeps +the choice). The arrows, Home and End move through it and Escape closes it. +Rows and groups that are left out hide; chips under the header show the +active filters and clear them, and "No layers match" says when nothing is +left. Neither the search nor the filter is saved or put in share links. A +voice request that points at a hidden layer clears the finder first +(`gev:layer-finder-clear`). + +A column of ticks down the list's inline end +(`src/ui/views/panels/LayerSectionIndex.vue`) has one tick per group still +shown; hovering or focusing a tick names its group beside it, on whichever +side has room, and clicking scrolls the list there. The tick for the group in +view is lit. Phones do not show it. + +## Cockpit side panels — November 14, 2026 + +On the desktop, the cockpit's side panels match the main page's +(`src/ui/styles/cockpit-panels.css`). The left rail shows Data Layers only: +Authoring, Utilities and Visual, with their panels, are hidden, since the +cockpit's own Display panel stands in for Visual. Display and Radio +(`CockpitUtilityControls.vue`) become a right rail of two icons with their +names beside them, and each opens one panel at a time beside the rail, with a +header and a "−" to close it. The rail's buttons are disclosures +(`aria-expanded`, `aria-controls`) and go through the `toggleCockpitUtility` +action (`src/ui/radioBindings.js`); closing a panel gives focus back to the +rail. Both rails start at the same height: the left one in CSS, and Display +and Radio through the cockpit layout pass, whose floor +(`COCKPIT_UTILITY_MIN_TOP_PX` / `_RATIO` in `src/ui/cockpitPresentation.js`) +matches it, so an open panel still stops short of the briefing. Contact and +Live Signals are shorter, in the same glass, with the briefing's rows and +weather tiles tightened; Regional News stays a briefing page. In a right-to-left language, the rail keeps its +physical side as the cockpit's other windows do. The Cyber HUD and the phone +keep their own cockpit layouts, with the Display and Radio launchers as +before, and edge mode does not apply in the cockpit. + ## God's Eye View in conversations — October 2, 2026 Tool answers that can be shown in God's Eye View include a view: camera, layers, @@ -453,6 +1109,8 @@ Display's native Scope checkbox defaults ON with feather at 100%, adjustable from 0–200%. OFF disables the slider while retaining its value. HUD layout changes preserve both settings; share links and scenes restore them. The historical missing-`scf` fallback remains 35%; explicit 0% keeps the hard edge. +Its Opacity slider (0–100%, default 100%) fades the mask; share links +restore it (`sco`), scenes do not (see The Visual panel). With Scope OFF, Tactical and Minimal add text-sized black backplates at 70% opacity behind telemetry, vertical metadata and scene chrome. Original @@ -573,9 +1231,10 @@ resources and subscriptions. The globe relief helper is enabled with Wind and released when Wind is disabled. It uses terrain vertex normals for view-directed shading, falling back to global globe-curvature shading when normals are unavailable; the fallback does not show local hillshade. Neither mode -adds elevation data or represents sunlight. Relief declines to replace an -existing globe material, restores the prior empty material only while still -owning it, and leaves later owners intact. +adds elevation data or represents sunlight. Relief is the globe port's +`hillshade` surface shading: the renderer never replaces a globe material +someone else holds (it waits until that one is gone), gives the globe back +when Wind is disabled, and leaves later owners intact. Source acquisition retains deadlines, body budgets, disconnect cancellation, per-model/field singleflight caching and one-minute failure backoff. Application catalog construction owns each instance. @@ -599,7 +1258,9 @@ other map content draws over the shells, and shells are not pickable. A map-source change tears down one renderer and restages the shown observation on the other. A map without an imagery host pauses history while metadata refresh continues, then resumes when a host returns. -Globe tiled products use 256 px tiles to maximum level 6. The tile proxy accepts +Globe tiled products use 256 px tiles to maximum level 6, or to the level a +feed that supplies its own tiles names for the product (`frameMaximumLevel`, +0–12; any other answer keeps 6). The tile proxy accepts size=256 (default), 512 or 1024 and keys cached bytes by size, retaining the 24-hour immutable response and eight upstream slots. The image proxy serves every product as one whole-extent PNG at its advertised bounds, up to 4096×2048 for @@ -641,7 +1302,11 @@ open latest. Global infrared fetches one capped 4 MiB, 2048×1024 mosaic per frame and decodes and processes it before staging. Globe hosts crop that canvas into 256 px tiles to maximum level 3 on a geographic 2×1 root grid bounded to the manifest extent, -avoiding request-dependent contrast seams. +avoiding request-dependent contrast seams. On globe hosts, a feed that supplies +tiles and names a level for global infrared instead has it drawn from its tiles +to that level, +each tile given the same display transfer as regional infrared tiles, and no +mosaic is read. On globe hosts, regional infrared retains network tiles and processes each decoded tile once; shells process each whole frame once. Exact-time tile and image responses are immutable for 24 hours; manifests and @@ -767,13 +1432,13 @@ Consult the linked official advisory for safety decisions. Voice and HUD snapshots reuse the existing feedState classifier. Analyst follow-ups retain their original data provenance; current-view results append provenance without replacing legacy fields. HUD context and deterministic telemetry include non-nominal feed state. -Analyst records come on demand from each layer's `getAnalystRecords`: flights, military, local ADS-B, vessels, satellites, launches, earthquakes, FIRMS (VIIRS and MODIS, with a `sensor` field), fire perimeters, cyclones, transit, bikeshare, ALPR cameras, mapped installations, datacenters and dams. `analyst_query` counts the whole loaded set (up to 250,000 records per layer; past that `coverage.records` reports `returned`, `total` and `truncated: true` and the result carries `complete: false`). Ranking keeps a top-k and scans in 20,000-row slices that yield to the page and stop when superseded. It refuses unknown fields, operators, units that do not convert (`altitudeM(ft)` converts), wrong-typed values, invalid centres, unknown scope kinds and sort fields with `code` and `allowed`, refuses a follow-up with no previous answer (`NO_RESULT_CONTEXT`) or naming other layers than that answer (`FOLLOW_UP_MISMATCH`), and tells `LAYER_OFF`, `NOT_READY` and `FEED_UNAVAILABLE` apart from a real zero; when only some layers can answer the result is `partial` with `unanswered` ids. The Contacts-window path applies the same filters, ranking and item shape to one immutable panel snapshot. Each aircraft layer retains at most 20,000 rows; reaching that bound sets `complete: false` and the spoken/card count becomes “At least”, never an exact claim. A superseded query never replaces follow-up memory, while sibling analyst calls from one assistant response do not cancel one another. Items carry `lat`/`lon`; the feed window (earthquakes and FIRMS: last 24 h), the precise scope and any caveat sit in `display`, which is on-screen detail rather than something the model recites. "In view" is still a radius around the view centre, not the visible footprint. Satellite distance is ground distance. +Analyst records come on demand from each layer's `getAnalystRecords`: flights, military, local ADS-B, vessels, satellites, launches, earthquakes, FIRMS (VIIRS and MODIS, with a `sensor` field), fire perimeters, cyclones, transit, bikeshare, ALPR cameras, mapped installations, datacenters and dams. `analyst_query` counts the whole loaded set (up to 250,000 records per layer; past that `coverage.records` reports `returned`, `total` and `truncated: true` and the result carries `complete: false`). Ranking keeps a top-k and scans in 20,000-row slices that yield to the page and stop when superseded. It refuses unknown fields, operators, units that do not convert (`altitudeM(ft)` converts), wrong-typed values, invalid centres, unknown scope kinds and sort fields with `code` and `allowed`, refuses a follow-up with no previous answer (`NO_RESULT_CONTEXT`) or naming other layers than that answer (`FOLLOW_UP_MISMATCH`), and tells `LAYER_OFF`, `NOT_READY` and `FEED_UNAVAILABLE` apart from a real zero; when only some layers can answer the result is `partial` with `unanswered` ids. The Contacts-window path applies the same filters, ranking and item shape to one immutable panel snapshot. Each aircraft layer retains at most 20,000 rows; reaching that bound sets `complete: false` and the spoken/card count becomes “At least”, never an exact claim. A superseded query never replaces follow-up memory, while sibling analyst calls from one assistant response do not cancel one another. Items carry `lat`/`lon`; the feed window (earthquakes and FIRMS: last 24 h, or for FIRMS the 24 hours to a snapshot's `at`), the precise scope and any caveat sit in `display`, which is on-screen detail rather than something the model recites. "In view" is still a radius around the view centre, not the visible footprint. Satellite distance is ground distance. Keyless terrain tiles retry when Re:Earth throttles them. The browser fetches `terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain` directly; no proxy in this repository sees those requests (`/api/terrain/heights` is the separate point-height endpoint), and the upstream edge answers zoom-out bursts -with HTTP 429 under load. `src/maps/terrain.js` hands Cesium a `Resource` +with HTTP 429 under load. `src/render/cesium/mapTerrain.js` hands Cesium a `Resource` whose retry policy (`src/maps/terrainRetry.js`) every derived tile fetch inherits: 429, 502, 503 and 504 replies retry up to three times, 750 ms doubling to a 15 s cap, with every retry waiting behind one shared cooldown @@ -812,7 +1477,7 @@ Native `. const input = await page.$('#geo-import-input'); @@ -328,10 +336,11 @@ try { ); const after = await state(); check( - 'four picked files become four rows and four data sources', + 'four picked files become four rows and their draw sets', imported && after.rows === 4 && - after.dataSources === before.dataSources + 4, + // Each file draws in up to three sets: pins, lines and shapes. + after.dataSources >= before.dataSources + 4, JSON.stringify( after.files.map((f) => `${f.name}:${f.format}:${f.entityCount}`), ), @@ -361,59 +370,51 @@ try { )), `${JSON.stringify(clockBefore)} → ${JSON.stringify(clockAfter)}`, ); - const inside = await page.evaluate((from) => { - const viewer = window.__godsEyeView.viewer; - const now = viewer.clock.currentTime; - const sources = []; - for (let i = from; i < viewer.dataSources.length; i++) - sources.push(viewer.dataSources.get(i)); - const entities = sources.flatMap( - (ds) => ds.importedEntities || ds.entities.values, - ); - const named = (name) => entities.find((e) => e.name === name); - const gpx = sources[3].importedEntities || sources[3].entities.values; - const kmz = sources[2].importedEntities || sources[2].entities.values; + const inside = await page.evaluate(() => { + const tool = window.__gevGeoImport; + const drawn = tool.list().map((f) => tool.drawn(f.id)); + const itemsOf = (d) => [...d.icons, ...d.lines, ...d.shapes]; + const items = drawn.flatMap(itemsOf); + const [park, kml, kmz, gpx] = drawn; return { - sources: sources.length, - clocks: sources.filter((ds) => ds.clock !== undefined).length, - described: entities.filter((e) => e.description !== undefined).length, - labelled: entities.filter((e) => e.label !== undefined).length, - withProperties: entities.filter((e) => e.properties !== undefined).length, - withKml: entities.filter((e) => e.kml !== undefined).length, - hidden: entities.filter((e) => !e.isAvailable(now)).length, - datedPinNow: Boolean(named('QA KML pin')?.isAvailable(now)), - fallbackPins: ['QA KML pin', 'QA palette pin'].filter((name) => - named(name)?.billboard?.image?.getValue(now), + sources: drawn.length, + clocks: 0, + // Anything a drawn item carries beyond its name. + described: items.filter((i) => + Object.keys(i.meta ?? {}).some((key) => key !== 'name'), ).length, - movingIsLine: Boolean( - named('QA moving')?.polyline && !named('QA moving')?.position, + labelled: 0, + withProperties: 0, + withKml: 0, + hidden: drawn.filter((d) => !d.show).length, + datedPinNow: kml.icons.some((i) => i.meta?.name === 'QA KML pin'), + fallbackPins: ['QA KML pin', 'QA palette pin'].filter((name) => + kml.icons.some((i) => i.meta?.name === name && i.image), + ).length, + movingIsLine: + kml.lines.filter((l) => l.meta?.name === 'QA moving').length === 1 && + !kml.icons.some((i) => i.meta?.name === 'QA moving'), + movingVertices: kml.lines.find((l) => l.meta?.name === 'QA moving') + ?.positions.length, + splitTracks: kml.lines + .filter((l) => l.meta?.name === 'QA split tracks') + .map((l) => l.positions.length), + gpxLines: gpx.lines.length, + gpxPoints: gpx.icons.length, + kmzLocalImage: kmz.icons.some((i) => + String(i.image || '').startsWith('blob:'), ), - movingVertices: - named('QA moving')?.polyline?.positions?.getValue(now)?.length, - splitTracks: (sources[1].importedEntities || sources[1].entities.values) - .filter((e) => e.parent?.name === 'QA split tracks' && e.polyline) - .map((e) => e.polyline.positions.getValue(now).length), - gpxLines: gpx.filter((e) => e.polyline).length, - gpxPoints: gpx.filter((e) => e.billboard || e.point).length, - kmzLocalImage: kmz.some((e) => - String(e.billboard?.image?.getValue(now) || '').startsWith('blob:'), + kmzOverlay: kmz.shapes.some((s) => s.geometry.kind === 'rectangle'), + groundedLines: [kml, kmz].every((d) => + d.lines.every((l) => l.mode === 'draped'), + ), + xyzPolygon: park.shapes.every( + (s) => s.geometry.kind !== 'polygon' || !s.geometry.perPositionHeight, ), - kmzOverlay: kmz.some((e) => e.rectangle), - groundedLines: sources - .slice(1, 3) - .every((ds) => - (ds.importedEntities || ds.entities.values) - .filter((e) => e.polyline) - .every((e) => e.polyline.clampToGround?.getValue(now)), - ), - xyzPolygon: - (sources[0].importedEntities || sources[0].entities.values) - .find((e) => e.polygon) - ?.polygon.perPositionHeight?.getValue(now) !== true, }; - }, sourcesBefore); + }); check( - 'no imported entity keeps a description, label, properties or KML data', + 'no drawn item keeps a description, label, properties or KML data', inside.sources === 4 && inside.described + inside.labelled + @@ -423,7 +424,7 @@ try { JSON.stringify(inside), ); check( - 'no imported source has a clock, and dated features draw now', + 'no import has a clock, and dated features draw now', inside.clocks === 0 && inside.hidden === 0 && inside.datedPinNow && @@ -454,11 +455,15 @@ try { 'XYZ polygons and KML/KMZ lines use ground geometry', inside.xyzPolygon && inside.groundedLines, ); - await page.evaluate((from) => { - for (const entity of window.__godsEyeView.viewer.dataSources.get(from) - .entities.values) - if (entity.billboard) entity.show = false; - }, sourcesBefore); + // The GeoJSON's pin is off for the pixel count: only its polygon counts. + await page.evaluate(() => { + const tool = window.__gevGeoImport; + const { sets } = tool.drawn(tool.list()[0].id); + const primitives = window.__godsEyeView.viewer.scene.primitives; + for (let i = 0; i < primitives.length; i++) + if (primitives.get(i).drawSetId === sets.icons) + primitives.get(i).show = false; + }); await page.evaluate((view) => { const viewer = window.__godsEyeView.viewer; viewer.camera.cancelFlight?.(); @@ -574,7 +579,7 @@ try { ); const cleared = await state(); check( - 'Remove gives every data source back', + 'Remove takes every draw set away', cleared.rows === 0 && cleared.dataSources === before.dataSources, `${cleared.dataSources} vs ${before.dataSources}`, ); diff --git a/scripts/qa-ghostmaps.mjs b/scripts/qa-ghostmaps.mjs index 3c3f0b8804..c4ee2547f9 100644 --- a/scripts/qa-ghostmaps.mjs +++ b/scripts/qa-ghostmaps.mjs @@ -8,7 +8,7 @@ * * (i) LIVE — enabling the layer loads the default products (Common * Intelligence Picture and the 30-day kinetic pull) from the live - * repository through /api/ghostmaps, one data source per product, + * repository through /api/ghostmaps, one pin set per product, * matching the proxy's catalog commit; the row shows one chip per * catalog product with the defaults active, and the page holds an * open event stream to /api/ghostmaps/events. @@ -17,12 +17,14 @@ * and clicking empty ground clears it. * (iii) PUSH (synthetic) — the event stream is replaced in the page and a * catalog naming a new edition of one product is pushed: only that - * product reloads (a new data source replaces the old one, no - * duplicates), the other keeps its data source. A catalog without a + * product reloads (a new pin set replaces the old one, no + * duplicates), the other keeps its pin set. A catalog without a * product removes it. * (iv) CHIPS — clicking an active product chip removes that product, * clicking it again restores it; the choice survives a reload. - * (v) DISABLE — every GhostMaps data source leaves the viewer. + * (v) DISABLE — every GhostMaps pin set leaves the viewer. + * The checks read pins (billboards) only: a product's lines and fills + * are not counted. * (vi) VIEWPORT — at a 390x844 phone viewport the open row and its chips * fit the panel width with no horizontal overflow. * (vii) FAR SIDE — pins skip the depth test, so they are horizon-culled: @@ -78,18 +80,43 @@ async function boot(page) { await page.keyboard.press('Escape'); } -/** GhostMaps data sources on the viewer: name → entity count. */ -function ghostSources(prefix) { - const { dataSources } = window.__godsEyeView.viewer; - const out = []; - for (let i = 0; i < dataSources.length; i++) { - const ds = dataSources.get(i); - if (ds.name?.startsWith(prefix)) - out.push({ name: ds.name, count: ds.entities.values.length }); - } +/** + * The GhostMaps pins drawn, by edition: each product's pins are drawn in a + * billboard collection of their own (a data source's, or a draw set's), so + * whatever draws them is read the same way. In the page: `layerId:product` + * → `{collection, pins: [{show, position}]}`. + */ +function ghostPins(prefix) { + const out = new Map(); + const seen = new Set(); + const visit = (node) => { + if (!node || typeof node !== 'object' || seen.has(node)) return; + seen.add(node); + if (Array.isArray(node._billboards)) { + for (const billboard of node._billboards) { + const id = String(billboard?.id?.id ?? billboard?.id ?? ''); + if (!id.startsWith('ghostmaps:')) continue; + const name = `${prefix}${id.split(':')[1]}`; + if (!out.has(name)) out.set(name, { collection: node, pins: [] }); + out.get(name).pins.push(billboard); + } + return; + } + if (Array.isArray(node._primitives)) node._primitives.forEach(visit); + visit(node._billboardCollection); + }; + visit(window.__godsEyeView.viewer.scene.primitives); return out; } +/** GhostMaps editions drawn: name → pin count. */ +function ghostSources(prefix) { + return [...ghostPins(prefix)].map(([name, { pins }]) => ({ + name, + count: pins.length, + })); +} + function paintedOverlayPixels() { const canvas = document.getElementById('world-overlay-canvas'); if (!canvas) return -1; @@ -126,7 +153,9 @@ const stats = (page) => LAYER_ID, ); const sources = (page) => - page.evaluate(`(${ghostSources})(${JSON.stringify(`${LAYER_ID}:`)})`); + page.evaluate( + `${ghostPins};(${ghostSources})(${JSON.stringify(`${LAYER_ID}:`)})`, + ); async function showRow(page) { await page.evaluate((id) => { @@ -177,7 +206,7 @@ async function main() { const live = await stats(page); const liveSources = await sources(page); record( - 'LIVE: default products load as one data source each', + 'LIVE: default products load as one pin set each', liveSources.length === 2 && liveSources.every((s) => s.count > 0) && live.products.sort().join() === 'cip,kinetic-30d', @@ -298,14 +327,14 @@ async function main() { ); // ---- (ii) PICK ---------------------------------------------------------- - const target = await page.evaluate((id) => { + const target = await page.evaluate(`(() => { + ${ghostPins}; const gev = window.__godsEyeView; - const ds = [...Array(gev.viewer.dataSources.length).keys()] - .map((i) => gev.viewer.dataSources.get(i)) - .find((item) => item.name === `${id}:cip`); - const entity = ds.entities.values.find((e) => e.billboard); + const pin = ghostPins(${JSON.stringify(`${LAYER_ID}:`)}).get( + ${JSON.stringify(`${LAYER_ID}:cip`)}, + ).pins[0]; const carto = gev.viewer.scene.globe.ellipsoid.cartesianToCartographic( - entity.position.getValue(gev.viewer.clock.currentTime), + pin.position, ); try { gev.viewer.camera.cancelFlight(); @@ -321,8 +350,8 @@ async function main() { orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, }); gev.viewer.scene.requestRender?.(); - return entity.id; - }, LAYER_ID); + return String(pin.id?.id ?? pin.id); + })()`); await page .waitForFunction( () => window.__godsEyeView.viewer.scene.globe.tilesLoaded, @@ -373,7 +402,7 @@ async function main() { }; }); record( - 'PICK: the centred marker picks as a GhostMaps entity', + 'PICK: the centred marker picks as a GhostMaps pin', probe.ids.some((id) => id.startsWith('ghostmaps:cip:')), `${target} → [${probe.ids.slice(0, 3).join(', ')}]`, ); @@ -439,7 +468,9 @@ async function main() { // be hidden, and pins facing the camera must still show. const horizonCounts = (lon, lat) => page.evaluate( - async (id, lo, la) => { + async (id, lo, la, pinsSource) => { + // eslint-disable-next-line no-new-func + const ghostPins = new Function(`return (${pinsSource})`)(); const gev = window.__godsEyeView; const d2r = Math.PI / 180; try { @@ -462,12 +493,9 @@ async function main() { const norm = (v) => Math.hypot(v.x, v.y, v.z); let far = 0; let nearShown = 0; - for (let i = 0; i < gev.viewer.dataSources.length; i++) { - const ds = gev.viewer.dataSources.get(i); - if (!ds.name?.startsWith(`${id}:`)) continue; - for (const e of ds.entities.values) { - if (!e.billboard) continue; - const p = e.position.getValue(gev.viewer.clock.currentTime); + for (const { pins } of ghostPins(`${id}:`).values()) { + for (const e of pins) { + const p = e.position; // Angle from the camera's nadir to the pin, against the // geometric horizon angle; the cull's 1 km margin shows pins up // to about 1° past it, so "clearly behind" is beyond 2°. @@ -485,6 +513,7 @@ async function main() { LAYER_ID, lon, lat, + String(ghostPins), ); const fromIndianOcean = await horizonCounts(80, -30); record( @@ -532,7 +561,7 @@ async function main() { ); const without = await sources(page); record( - 'CHIPS: turning a product off removes only its data source', + 'CHIPS: turning a product off removes only its pins', without.length === 1 && without[0].name === `${LAYER_ID}:cip`, without.map((s) => s.name).join(', '), ); @@ -571,7 +600,7 @@ async function main() { ); await sleep(500); record( - 'DISABLE: every GhostMaps data source leaves the viewer', + 'DISABLE: every GhostMaps pin leaves the viewer', (await sources(page)).length === 0, ); await page.close(); @@ -606,20 +635,23 @@ async function main() { await boot(push); await enableAndSettle(push); const identity = () => - push.evaluate((id) => { - const { dataSources } = window.__godsEyeView.viewer; - window.__qaIds ||= new WeakMap(); - window.__qaNext ||= 1; - const out = {}; - for (let i = 0; i < dataSources.length; i++) { - const ds = dataSources.get(i); - if (!ds.name?.startsWith(`${id}:`)) continue; - if (!window.__qaIds.has(ds)) - window.__qaIds.set(ds, window.__qaNext++); - out[ds.name] = window.__qaIds.get(ds); - } - return out; - }, LAYER_ID); + push.evaluate( + (id, pinsSource) => { + // eslint-disable-next-line no-new-func + const ghostPins = new Function(`return (${pinsSource})`)(); + window.__qaIds ||= new WeakMap(); + window.__qaNext ||= 1; + const out = {}; + for (const [name, { collection }] of ghostPins(`${id}:`)) { + if (!window.__qaIds.has(collection)) + window.__qaIds.set(collection, window.__qaNext++); + out[name] = window.__qaIds.get(collection); + } + return out; + }, + LAYER_ID, + String(ghostPins), + ); const first = await identity(); const pushed = Date.now(); await push.evaluate(async (id) => { diff --git a/scripts/qa-gnss.mjs b/scripts/qa-gnss.mjs index 41933141e8..d407853465 100644 --- a/scripts/qa-gnss.mjs +++ b/scripts/qa-gnss.mjs @@ -9,22 +9,24 @@ * stub that route in the page so they are deterministic. * * (i) LIVE — over Poland and the southern Baltic the layer settles with no error, - * one geometry per cell and legend band counts that sum to the cell + * its cells drawn and legend band counts that sum to the cell * count; cells are required only when the returned rows, binned - * with the layer's own rules, reach the per-cell minimum (live - * traffic varies by hour). Requires a non-stale response no older than 60 s. + * into H3 cells with the layer's own rules, give at least one cell + * (live traffic varies by hour). Requires a non-stale response no older than 60 s. * (ii) BANDS (synthetic) — a 10-aircraft cell with 5 degraded is high, * a 30-aircraft cell with 2 degraded is medium, a 3-aircraft cell * with 1 degraded is low (first bad discounted), a clean cell at sea - * is low, a 2-aircraft cell is withheld; `stale: true` reaches + * is low, a 2-aircraft cell with 2 degraded is shown high (no + * minimum aircraft count, as on gpsjam.org); `stale: true` reaches * getStats. Every band is drawn and low is shown over land and sea. * The row reads as low navigation accuracy, and stats carry the - * machine-readable provenance (GEV classifier, gpsjam bands, window). + * machine-readable provenance (GEV classifier, gpsjam bands and H3 + * grid, window). * PICK verifies actual perimeter and empty-ground clicks under GNSS. * CAMERA/GLOBE verify automatic sampling and the screen-centre anchor. * (iii) FAILURE — the route stubbed to 502: stats.error is set and the * cells already on the globe are kept. - * (iv) DISABLE — owned ground primitives are hidden. + * (iv) DISABLE — the cells' ground primitives are hidden. * (v) KEYBOARD — the row's toggle button, focused, turns the layer on * with Enter and off with Space, keeps focus and names its state. * (vi) VIEWPORT — at a 390x844 phone viewport the open row and its legend @@ -114,10 +116,34 @@ async function boot(page, { lon, lat, height }) { ); } +/** + * In the page: the GNSS cells' ground primitives, each with the collection + * drawing it. The layer draws them through the renderer's draw port as + * ground fills that never take part in picks, the only such fills the app + * draws, so they are found by that. + */ +function gnssGround() { + const out = []; + const walk = (collection) => { + for (let i = 0; i < collection.length; i++) { + const item = collection.get(i); + if (typeof item?.length === 'number' && typeof item.get === 'function') + walk(item); + else if ( + item?.allowPicking === false && + item.classificationType !== undefined + ) + out.push({ primitive: item, host: collection }); + } + }; + walk(window.__godsEyeView.viewer.scene.primitives); + return out; +} + /** Enable (or refresh) the layer and poll until it settles. */ async function enableAndSettle(page, { refresh = false } = {}) { return page.evaluate( - async (id, again) => { + async (id, again, findGround) => { const dm = window.__godsEyeView.dataManager; const layer = dm.layers.get(id).module; if (again) await dm.refreshLayer(id); @@ -129,22 +155,21 @@ async function enableAndSettle(page, { refresh = false } = {}) { const rowName = document.querySelector(`[data-layer-id="${id}"] .data-name`) ?.textContent ?? ''; - const all = window.__godsEyeView.viewer.scene.groundPrimitives; - const ds = Array.from({ length: all.length }, (_, i) => all.get(i)).find( - (item) => item.id === id, - ); + // eslint-disable-next-line no-new-func + const ground = new Function(`return (${findGround})()`)(); return { stats, legend, blurb, rowName, name: layer.name, - entities: ds?.get(0)?.geometryInstances.length ?? 0, - shown: ds?.show ?? null, + drawn: ground.length > 0, + shown: ground[0]?.host.show ?? null, }; }, LAYER_ID, refresh, + String(gnssGround), ); } @@ -184,31 +209,21 @@ async function shoot(page, name) { await page.screenshot({ path: path.join(SHOTS_DIR, `gnss-${name}.png`) }); } -/** Bounding-sphere state of every GNSS cell: DONE = 0, PENDING = 1, FAILED = 2. */ -function cellStates(id) { - const { viewer } = window.__godsEyeView; - const all = viewer.scene.groundPrimitives; - const ds = Array.from({ length: all.length }, (_, i) => all.get(i)).find( - (item) => item.id === id, - ); - if (!ds?.length) return []; - return [ds.get(0).ready ? 0 : 1]; -} +/** Build state of every GNSS ground primitive: DONE = 0, PENDING = 1. */ +const cellStates = `() => (${gnssGround})().map(({ primitive }) => (primitive.ready ? 0 : 1))`; -/** Wait until every GNSS cell's ground rectangle has finished building. */ +/** Wait until every GNSS cell's ground polygon has finished building. */ async function waitForBuiltCells(page, timeoutMs = 60000) { const built = await page - .waitForFunction( - `(${cellStates})(${JSON.stringify(LAYER_ID)}).every((state) => state === 0)`, - { timeout: timeoutMs, polling: 250 }, - ) + .waitForFunction(`(${cellStates})().every((state) => state === 0)`, { + timeout: timeoutMs, + polling: 250, + }) .then( () => true, () => false, ); - const states = await page.evaluate( - `(${cellStates})(${JSON.stringify(LAYER_ID)})`, - ); + const states = await page.evaluate(`(${cellStates})()`); return { built, detail: `states=${JSON.stringify(states)}` }; } @@ -223,22 +238,23 @@ const fixtureRow = (hex, lat, lon, degraded) => ({ }); /** - * Synthetic 0.5° cells: high at sea (5/10 bad), medium on land (2/30 bad), - * low on land (1/3 bad), low at sea (0/4 bad), withheld (2 aircraft). + * Synthetic H3 res-4 cells, each group inside one hexagon: high at sea + * (5/10 bad), medium on land (2/30 bad), low on land (1/3 bad), low at sea + * (0/4 bad), and high from only 2 aircraft (2/2 bad; no minimum count). */ function fixturePayload() { const rows = []; const hex = (prefix, i) => `${prefix}${i.toString(16).padStart(2, '0')}`; for (let i = 0; i < 10; i++) - rows.push(fixtureRow(hex('a000', i), 55.1 + i * 0.01, 19.1, i < 5)); + rows.push(fixtureRow(hex('a000', i), 55.1 + i * 0.001, 19.1, i < 5)); for (let i = 0; i < 30; i++) - rows.push(fixtureRow(hex('d000', i), 54.1 + i * 0.01, 19.6, i < 2)); + rows.push(fixtureRow(hex('d000', i), 54.1 + i * 0.001, 19.6, i < 2)); for (let i = 0; i < 3; i++) - rows.push(fixtureRow(hex('b000', i), 54.1 + i * 0.01, 18.1, i === 0)); + rows.push(fixtureRow(hex('b000', i), 54.1 + i * 0.001, 18.1, i === 0)); for (let i = 0; i < 4; i++) - rows.push(fixtureRow(hex('e000', i), 55.1 + i * 0.01, 18.1, false)); + rows.push(fixtureRow(hex('e000', i), 55.1 + i * 0.001, 18.1, false)); for (let i = 0; i < 2; i++) - rows.push(fixtureRow(hex('c000', i), 53.1 + i * 0.01, 17.1, true)); + rows.push(fixtureRow(hex('c000', i), 53.1 + i * 0.001, 17.1, true)); return { fetchedAt: Date.now(), anchor: { lat: 55, lon: 19 }, @@ -385,8 +401,8 @@ async function main() { const l = await enableAndSettle(live); const legendTotal = l.legend.reduce((sum, { count }) => sum + count, 0); // Bin what adsb.lol actually returned with the layer's own rules: live - // traffic varies by hour, so cells are required only when some cell - // really reached the minimum aircraft count. + // traffic varies by hour, so cells are required only when the rows + // really bin into some cell. const liveSnapshots = (await Promise.allSettled(liveBodies)) .filter((r) => r.status === 'fulfilled') .map((r) => r.value); @@ -417,9 +433,9 @@ async function main() { } const expectedCells = binGnssCells(expectedStore).length; record( - 'LIVE: no error, one geometry per cell', - !l.stats.error && l.entities === l.stats.count, - `cells=${l.stats.count} entities=${l.entities} error=${JSON.stringify(l.stats.error)}`, + 'LIVE: no error, cells drawn when there are any', + !l.stats.error && l.drawn === l.stats.count > 0, + `cells=${l.stats.count} drawn=${l.drawn} error=${JSON.stringify(l.stats.error)}`, ); if (expectedCells > 0) { record( @@ -429,7 +445,7 @@ async function main() { ); } else { console.log( - ` [info] ${liveRows} live rows, no cell reaches the minimum — cell count not asserted`, + ` [info] ${liveRows} live rows bin into no cell — cell count not asserted`, ); } record( @@ -439,7 +455,7 @@ async function main() { ); const liveBuilt = await waitForBuiltCells(live); record( - 'LIVE: every cell rectangle is built on a parked camera', + 'LIVE: every cell polygon is built on a parked camera', liveBuilt.built, liveBuilt.detail, ); @@ -454,7 +470,7 @@ async function main() { await page.setViewport({ width: 1440, height: 900 }); page.on('pageerror', (e) => errors.push(e.message)); // Stub the route in-page rather than with request interception: an - // intercepted page stalls Cesium's geometry workers, so ground rectangles + // intercepted page stalls Cesium's geometry workers, so ground polygons // never finish building and the screenshot would not show real behaviour. await stubRoute(page); await boot(page, { lon: 18.6, lat: 54.6, height: 450_000 }); @@ -462,25 +478,27 @@ async function main() { const band = (prefix) => f.legend.find(({ label }) => label.startsWith(prefix))?.count; record( - 'BANDS: 4 cells shown, the 2-aircraft cell withheld', - f.stats.count === 4 && f.entities === 4, - `cells=${f.stats.count} entities=${f.entities}`, + 'BANDS: 5 cells shown, the 2-aircraft cell included', + f.stats.count === 5 && f.drawn, + `cells=${f.stats.count} drawn=${f.drawn}`, ); record( - 'BANDS: 5/10 is high, 2/30 is medium, 1/3 and 0/4 are low', - band('Low-accuracy score >') === 1 && + 'BANDS: 5/10 and 2/2 are high, 2/30 is medium, 1/3 and 0/4 are low', + band('Low-accuracy score >') === 2 && band('Low-accuracy score 2') === 1 && band('Low-accuracy score <') === 2, JSON.stringify(f.legend), ); const prov = f.stats.provenance; record( - 'PROVENANCE: GEV classifier, gpsjam bands and visited-view window are machine-readable', + 'PROVENANCE: GEV classifier, gpsjam bands and H3 grid, and visited-view window are machine-readable', prov?.classifier?.id === 'gev-nic-nacp-v2' && prov.classifier.definedBy === 'GEV' && prov.classifier.validated === false && prov.aggregation?.source === 'https://gpsjam.org/faq' && JSON.stringify(prov.aggregation.bands) === '[2,10]' && + prov.aggregation.grid === 'h3' && + prov.aggregation.h3Resolution === 4 && prov.window?.minutes === 30 && prov.window.scope === 'visited-view' && prov.interpretation?.validated === false, @@ -503,7 +521,7 @@ async function main() { ); const bandsBuilt = await waitForBuiltCells(page); record( - 'BANDS: every cell rectangle is built on a parked camera', + 'BANDS: every cell polygon is built on a parked camera', bandsBuilt.built, bandsBuilt.detail, ); @@ -769,20 +787,22 @@ async function main() { const e = await enableAndSettle(page, { refresh: true }); record( 'FAILURE: error surfaced, cells kept', - Boolean(e.stats.error) && e.stats.count === 4 && e.entities === 4, + Boolean(e.stats.error) && e.stats.count === 5 && e.drawn, `error=${JSON.stringify(e.stats.error)} cells=${e.stats.count}`, ); await shoot(page, 'failure'); // ── (iv) DISABLE ────────────────────────────────────────────────────── console.log('\n(iv) DISABLE...'); - const shown = await page.evaluate(async (id) => { - await window.__godsEyeView.dataManager.setEnabled(id, false); - const all = window.__godsEyeView.viewer.scene.groundPrimitives; - return Array.from({ length: all.length }, (_, i) => all.get(i)).find( - (item) => item.id === id, - )?.show; - }, LAYER_ID); + const shown = await page.evaluate( + async (id, findGround) => { + await window.__godsEyeView.dataManager.setEnabled(id, false); + // eslint-disable-next-line no-new-func + return new Function(`return (${findGround})()`)()[0]?.host.show; + }, + LAYER_ID, + String(gnssGround), + ); record('DISABLE: data source hidden', shown === false, `show=${shown}`); await shoot(page, 'disabled'); @@ -797,7 +817,7 @@ async function main() { 'KEYBOARD: Enter on the focused toggle enables the layer and keeps focus', on.enabled && on.focused && - on.count === 4 && + on.count === 5 && /^GNSS Integrity: /.test(on.label) && !/OFF$/.test(on.label), JSON.stringify(on), @@ -906,7 +926,7 @@ async function main() { return ( layer.enabled && layer.module.getStats().error === null && - layer.module.getStats().count === 4 + layer.module.getStats().count === 5 ); }, { timeout: 20000 }, @@ -948,8 +968,8 @@ async function main() { const old = await enableAndSettle(aged, {}); record( 'AGE: a snapshot observed 31 min ago adds no cells and is not an error', - old.stats.count === 0 && old.entities === 0 && !old.stats.error, - `cells=${old.stats.count} entities=${old.entities} error=${JSON.stringify(old.stats.error)}`, + old.stats.count === 0 && !old.drawn && !old.stats.error, + `cells=${old.stats.count} drawn=${old.drawn} error=${JSON.stringify(old.stats.error)}`, ); await aged.evaluate(() => { window.__gnssQaAgeMs = 29 * 60_000; @@ -957,8 +977,8 @@ async function main() { const recent = await enableAndSettle(aged, { refresh: true }); record( 'AGE: the same snapshot observed 29 min ago is still inside the window', - recent.stats.count === 4 && recent.entities === 4, - `cells=${recent.stats.count} entities=${recent.entities}`, + recent.stats.count === 5 && recent.drawn, + `cells=${recent.stats.count} drawn=${recent.drawn}`, ); await aged.close(); record( diff --git a/scripts/qa-heading-b3.mjs b/scripts/qa-heading-b3.mjs index fb33654b13..645c71d844 100644 --- a/scripts/qa-heading-b3.mjs +++ b/scripts/qa-heading-b3.mjs @@ -40,7 +40,7 @@ * the DISPLAYED (render-delayed) time within 35° — catches * sign/offset inversion in the whole chain (chord lags the * tangent by ≤ half a segment ≈ 22.5°) - * Both layers: flights (airplane.glb, offset 180°) then military (jet.glb, + * Both layers: flights (fleet models, offset 180°) then military (fleet models, * normalized nose -X, offset 180°). * * VISUAL — with the turning flights plane tracked in 3D, capture screenshots @@ -170,8 +170,8 @@ async function observeTrackedHostPaint(page, timeoutMs = 5000) { const tracked = viewer?.trackedEntity; const current = { elapsedMs: Math.round(performance.now() - startedAt), - entryId: tracked?.gevTrackedId || null, - hasPresentationModel: Boolean(tracked?.gevLabelModel?.title), + entryId: window.__godsEyeView?.entityRecords?.read(tracked)?.trackedId || null, + hasPresentationModel: Boolean(window.__godsEyeView?.entityRecords?.read(tracked)?.labelModel?.title), candidateCount: diagnostics.candidateCount || 0, projectedCount: diagnostics.projectedCount || 0, selectedCount: diagnostics.selectedCount || 0, @@ -612,7 +612,7 @@ async function main() { if (!pool.length) return null; const ent = v.trackedEntity; let tracked = null; - if (ent && typeof ent.gevDisplayPosition === 'function') tracked = ent.gevDisplayPosition(); + if (ent && typeof window.__godsEyeView.entityRecords.read(ent)?.displayPosition === 'function') tracked = window.__godsEyeView.entityRecords.read(ent)?.displayPosition(); if (!tracked) return pool[0]; let best = null, bestD = Infinity; for (const m of pool) { @@ -721,7 +721,7 @@ async function main() { // ======================================================================== // Phase 1 — FLIGHTS layer: track TRN001, sample displayed course 30 s // ======================================================================== - console.log('\nPhase 1 — flights layer (airplane.glb, heading offset 180°)'); + console.log('\nPhase 1 — flights layer (fleet models, heading offset 180°)'); await page.evaluate((icao) => { window.__godsEyeView.dataManager.layers.get('flights').module.trackById(icao); }, TURN.flights[0].icao); @@ -807,7 +807,7 @@ async function main() { // ======================================================================== // Phase 2 — MILITARY layer: track TRNMIL1 (flights layer auto-clears) // ======================================================================== - console.log('\nPhase 2 — military layer (jet.glb, heading offset 180°)'); + console.log('\nPhase 2 — military layer (fleet models, heading offset 180°)'); await page.evaluate((hex) => { window.__godsEyeView.dataManager.layers.get('military').module.trackById(hex); }, TURN.military[0].hex); diff --git a/scripts/qa-infra-lod.mjs b/scripts/qa-infra-lod.mjs index 5be19fe640..3c4c75c3a3 100644 --- a/scripts/qa-infra-lod.mjs +++ b/scripts/qa-infra-lod.mjs @@ -218,9 +218,11 @@ try { const gev = window.__godsEyeView; const snap = () => infraIds.map((id) => { const visibleIds = []; + // The app registers each local feature's context as `:`. for (let i = 0; i < gev.viewer.dataSources.length; i++) { for (const entity of gev.viewer.dataSources.get(i).entities.values) { - if (entity.__localLayerId === id && entity.show) visibleIds.push(String(entity.id)); + const contextId = gev.entityRecords.read(entity)?.contextId; + if (contextId?.startsWith(`${id}:`) && entity.show) visibleIds.push(String(entity.id)); } } return visibleIds.sort(); diff --git a/scripts/qa-installation-navigation.mjs b/scripts/qa-installation-navigation.mjs index 5ecf03e1a8..8eff6e99bb 100644 --- a/scripts/qa-installation-navigation.mjs +++ b/scripts/qa-installation-navigation.mjs @@ -40,9 +40,29 @@ try { page.on('console', (m) => { if (m.type() === 'error') result.errors.push(m.text()); }); - await page.evaluateOnNewDocument(() => - sessionStorage.setItem('gev:first-run-mission-session:v1', 'dismissed'), - ); + await page.evaluateOnNewDocument(() => { + sessionStorage.setItem('gev:first-run-mission-session:v1', 'dismissed'); + // The site dots the layer draws, read from its draw-port point set: each + // row is a drawn dot whose pick id is the draw port's `{set, id, meta}`; + // `meta` is the site's carrier, kept while the site's geometry is. + window.__qaInstallationDots = () => { + const out = []; + const visit = (node) => { + if (!node || typeof node.get !== 'function') return; + if (typeof node.length !== 'number') return; + for (let index = 0; index < node.length; index += 1) { + const child = node.get(index); + const id = child?.id; + if (id && typeof id === 'object' && typeof id.set === 'string') { + if (/^military-installations:\d+:dots$/.test(id.set)) + out.push({ id: id.id, meta: id.meta, primitive: child }); + } else visit(child); + } + }; + visit(window.__godsEyeView.viewer.scene.primitives); + return out; + }; + }); await page.goto( args.find((a) => /^https?:/.test(a)), { waitUntil: 'domcontentloaded' }, @@ -156,14 +176,15 @@ try { .catch(() => {}); const snapshot = await page.evaluate(() => { const g = window.__godsEyeView; - const ds = g.viewer.dataSources.getByName('military-installations')[0]; - const points = ds.entities.values.filter((e) => e.point); + const points = window.__qaInstallationDots(); const stable = points.every( (e) => !window.installationEntityRefs.has(e.id) || - window.installationEntityRefs.get(e.id) === e, + window.installationEntityRefs.get(e.id) === e.meta, + ); + window.installationEntityRefs = new Map( + points.map((e) => [e.id, e.meta]), ); - window.installationEntityRefs = new Map(points.map((e) => [e.id, e])); return { ...g.dataManager.layers .get('military-installations') @@ -186,7 +207,7 @@ try { new Set(row.ids).size !== row.ids.length ) result.failures.push( - `${name}/${height}: unstable or duplicate site entities`, + `${name}/${height}: unstable or duplicate site markers`, ); if (name.endsWith('return')) { const first = result.views.find( @@ -244,10 +265,7 @@ try { 0.6, ); await page.waitForFunction( - () => - window.__godsEyeView.viewer.dataSources - .getByName('military-installations')[0] - .entities.values.some((e) => e.point), + () => window.__qaInstallationDots().length > 0, { timeout: 5000 }, ); await page.evaluate(() => { @@ -268,8 +286,7 @@ try { await sleep(1000); await page.evaluate(async () => { const g = window.__godsEyeView; - const ds = g.viewer.dataSources.getByName('military-installations')[0]; - const id = ds.entities.values.find((e) => e.point).id; + const id = window.__qaInstallationDots()[0].id; window.installationSubjectId = id; await g.dataManager.layers .get('military-awareness') diff --git a/scripts/qa-installation-polish.mjs b/scripts/qa-installation-polish.mjs index 6971d85ba5..8a9703e2c3 100644 --- a/scripts/qa-installation-polish.mjs +++ b/scripts/qa-installation-polish.mjs @@ -17,9 +17,11 @@ export async function checkInstallationPan(page, dir) { 'military-installations', ).module; const centerIds = []; + // The app registers each local feature's context as `:`. for (let i = 0; i < g.viewer.dataSources.length; i++) for (const e of g.viewer.dataSources.get(i).entities.values) - if (e.__localLayerId === 'local-datacenters') centerIds.push(e.id); + if (g.entityRecords.read(e)?.contextId?.startsWith('local-datacenters:')) + centerIds.push(e.id); window.__polishPanFrames = []; window.__stopPolishPan = g.viewer.scene.postRender.addEventListener(() => { const sites = [], @@ -175,18 +177,13 @@ export async function checkInstallationSelection( await import('/src/data/contextStore.js'); const { getOverlayPaintRect, getWorldOverlayDiagnostics } = await import('/src/overlays/worldOverlay.js'); - const knownFills = new Set(); - const fillEntities = () => { - const list = []; - for (let i = 0; i < g.viewer.dataSources.length; i++) - for (const e of g.viewer.dataSources.get(i).entities.values) - if (e.id.startsWith(`${record.id}:selected-fill:`)) list.push(e); - for (const e of list) knownFills.add(e); - return list; - }; - // Geometry-instance ids prove the ground primitive actually built, not just an entity declaration. - const primitives = () => { - let count = 0; + // The selected site's fill parts, as the ground primitives built for + // the layer's fill set hold them: each instance's id is the + // draw port's pick id `{set, id}`. Only built, shown instances count, + // so this proves the ground primitive actually built, not just an + // item declaration. + const fillParts = () => { + const parts = []; const walk = (collection) => { if (collection?._collectionsArray) { for (const child of collection._collectionsArray) walk(child); @@ -194,31 +191,44 @@ export async function checkInstallationSelection( } for (let i = 0; i < (collection?.length || 0); i++) { const p = collection.get(i); - if ( - p.ready && - typeof p.getGeometryInstanceAttributes === 'function' - ) { - for (const e of knownFills) { + const ids = p?._primitive?._primitive?._instanceIds; + if (p?.ready && Array.isArray(ids)) + for (const id of ids) { + if ( + !/^military-installations:\d+:fills$/.test(id?.set) || + !String(id.id).startsWith(`${record.id}:selected-fill:`) + ) + continue; try { - const a = p.getGeometryInstanceAttributes(e); - if (a && (!a.show || a.show[0])) count++; + const a = p.getGeometryInstanceAttributes(id); + if (a && (!a.show || a.show[0])) + parts.push({ + id: id.id, + classification: p.classificationType, + }); } catch {} } - } - if (typeof p.get === 'function' || p._collectionsArray) walk(p); + if (typeof p?.get === 'function' || p?._collectionsArray) + walk(p); } }; + // The draw port adds its ground primitives under the scene's + // primitives, in its set's collection. walk(g.viewer.scene.groundPrimitives); - return count; + walk(g.viewer.scene.primitives); + return parts; + }; + window.__polishFillProbe = () => { + const parts = fillParts(); + return { + // Distinct fill parts drawn, and the built instances drawing them + // (a ground swap can draw a part twice while it lasts). + entities: new Set(parts.map((part) => part.id)).size, + primitives: parts.length, + classification: parts.map((part) => part.classification), + selected: getSelectedEntityContext()?.id || null, + }; }; - window.__polishFillProbe = () => ({ - entities: fillEntities().length, - primitives: primitives(), - classification: fillEntities().map((e) => - e.polygon.classificationType.getValue(), - ), - selected: getSelectedEntityContext()?.id || null, - }); window.__stopPolishSelection = g.viewer.scene.postRender.addEventListener(() => { window.__polishSelectionFrames.push({ @@ -333,7 +343,8 @@ export async function checkInstallationSelection( for (let y = 250; y < 650; y += 75) for (let x = 400; x < 850; x += 75) { const pick = g.viewer.scene.pick({ x, y }); - if (!pick?.id?.installationId && !pick?.id?.gevTrackedId) + // Nothing picked: no installation marker, outline or tracked contact. + if (!pick?.id) return { x, y }; } throw new Error('No empty map point'); diff --git a/scripts/qa-label-readability.mjs b/scripts/qa-label-readability.mjs index b7d17752c2..3b5e80ee49 100644 --- a/scripts/qa-label-readability.mjs +++ b/scripts/qa-label-readability.mjs @@ -257,10 +257,6 @@ async function main() { () => window.__godsEyeView?.viewer && window.__godsEyeView?.styleManager, { timeout: 60_000, polling: 100 }, ); - // flyToAustin arrives ~500 ms after init; let it start and land before any - // scene sets its own pose, or the arrival overwrites the first camera. - await new Promise((resolve) => setTimeout(resolve, 2500)); - const selected = SCENE_FILTER.length ? SCENES.filter((scene) => SCENE_FILTER.some((prefix) => scene.id.startsWith(prefix))) : SCENES; diff --git a/scripts/qa-labels.mjs b/scripts/qa-labels.mjs index fb04d00252..911b986c36 100644 --- a/scripts/qa-labels.mjs +++ b/scripts/qa-labels.mjs @@ -267,12 +267,6 @@ async function main() { { timeout: 60000, polling: 100 }, ); - // flyToAustin schedules its 600 m arrival 500 ms after initialization. - // Let that callback start, then cancel it before establishing the global - // measurement camera so startup motion cannot invalidate the sample. - await new Promise((resolve) => setTimeout(resolve, 600)); - await page.evaluate(() => window.__godsEyeView.viewer.camera.cancelFlight()); - const stateChecks = await page.evaluate((storageKey) => { const manager = window.__godsEyeView.styleManager; const restored = manager.getDetectionState(); diff --git a/scripts/qa-map-source-tray.mjs b/scripts/qa-map-source-tray.mjs index 2317259976..b07eb06136 100644 --- a/scripts/qa-map-source-tray.mjs +++ b/scripts/qa-map-source-tray.mjs @@ -342,7 +342,7 @@ try { const before = { activeId: controller.getActiveId(), creditVisible: document.body.innerText.includes('Powered by Esri'), - globeShown: styleManager.viewer.scene.globe.show, + globeShown: window.__godsEyeView.viewer.scene.globe.show, hasLayer: Boolean(controller._imageryLayer), }; provider?.errorEvent?.raiseEvent?.({ timesRetried: 0 }); @@ -369,7 +369,7 @@ try { activeId: controller.getActiveId(), lastError: controller.getState().lastError, creditVisible: document.body.innerText.includes('Powered by Esri'), - globeShown: styleManager.viewer.scene.globe.show, + globeShown: window.__godsEyeView.viewer.scene.globe.show, hasLayer: Boolean(controller._imageryLayer), active: [...document.querySelectorAll('.map-stack-chip')] .filter((chip) => chip.getAttribute('aria-pressed') === 'true') diff --git a/scripts/qa-overpass-offload.mjs b/scripts/qa-overpass-offload.mjs index 8f6594011f..4d5c7c3f0e 100644 --- a/scripts/qa-overpass-offload.mjs +++ b/scripts/qa-overpass-offload.mjs @@ -1277,8 +1277,9 @@ try { outlines = 0; for (let i = 0; i < viewer.dataSources.length; i++) for (const entity of viewer.dataSources.get(i).entities.values) { - if (!ids.has(entity.installationId || entity.id) || !entity.show) - continue; + // Outline entities are `:outline:`. + const recordId = String(entity.id).replace(/:outline:\d+$/, ''); + if (!ids.has(recordId) || !entity.show) continue; if (entity.billboard || entity.point) markers++; if (entity.polyline) outlines++; } diff --git a/scripts/qa-radio.mjs b/scripts/qa-radio.mjs index 83b3596053..bec07d25c5 100644 --- a/scripts/qa-radio.mjs +++ b/scripts/qa-radio.mjs @@ -184,6 +184,50 @@ async function main() { queueMicrotask(() => this.dispatchEvent(new Event('playing'))); return Promise.resolve(); }; + // What Radio draws, read from the renderer's draw-port sets: the + // station dots (`stations`), cluster dots (`clusters`), and the + // selected station's dot (`selected`) and bracket + // (`selected-bracket`). Each row is a drawn point or billboard whose + // pick id is the draw port's `{set, id, meta}`; `show` is whether it + // draws, its set's host included. + window.__qaRadioRows = (kind) => { + const pattern = new RegExp(`^radio:\\d+:${kind}$`); + const out = []; + const visit = (node, shown) => { + if (!node || typeof node.get !== 'function' || typeof node.length !== 'number') return; + const here = shown && node.show !== false; + for (let index = 0; index < node.length; index += 1) { + const child = node.get(index); + const id = child?.id; + if (id && typeof id === 'object' && !Array.isArray(id) && typeof id.set === 'string') { + if (pattern.test(id.set)) { + out.push({ + primitive: child, + id: id.id, + meta: id.meta, + show: here && child.show !== false, + setShown: here, + }); + } + } else visit(child, here); + } + }; + visit(window.__godsEyeView.viewer.scene.primitives, true); + return out; + }; + // The selected station's drawn dot and bracket, with its pick id. + window.__qaRadioSelected = () => { + const dot = window.__qaRadioRows('selected')[0] || null; + if (!dot) return null; + const bracket = window.__qaRadioRows('selected-bracket')[0] || null; + return { + id: dot.id, + show: dot.show, + position: dot.primitive.position, + dot, + bracket, + }; + }; }); await page.setRequestInterception(true); let catalogDegraded = false; @@ -420,7 +464,7 @@ async function main() { await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))); const result = { presentationActive: module.getUIState().presentationActive, - markerSourceVisible: gev.viewer.dataSources.getByName('Radio stations')[0]?.show, + markerSourceVisible: (window.__qaRadioRows('stations')[0]?.setShown ?? false), tunerHidden: document.getElementById('radio-tuner').hidden, filterDisabled: document.getElementById('radio-filter').disabled, prevDisabled: document.getElementById('radio-prev-btn').disabled, @@ -514,7 +558,7 @@ async function main() { const disablingPresentation = await page.evaluate(() => ({ manager: window.__godsEyeView.dataManager.getLayerLifecycleState('radio'), presentationActive: window.__godsEyeView.dataManager.layers.get('radio').module.getUIState().presentationActive, - markerSourceVisible: window.__godsEyeView.viewer.dataSources.getByName('Radio stations')[0]?.show, + markerSourceVisible: (window.__qaRadioRows('stations')[0]?.setShown ?? false), full: document.getElementById('radio-enable-btn').textContent, layerState: document.getElementById('radio-layer-state').textContent, message: document.getElementById('radio-playback-state').textContent, @@ -583,7 +627,7 @@ async function main() { const enablingPresentation = await page.evaluate(() => ({ manager: window.__godsEyeView.dataManager.getLayerLifecycleState('radio'), presentationActive: window.__godsEyeView.dataManager.layers.get('radio').module.getUIState().presentationActive, - markerSourceVisible: window.__godsEyeView.viewer.dataSources.getByName('Radio stations')[0]?.show, + markerSourceVisible: (window.__qaRadioRows('stations')[0]?.setShown ?? false), full: document.getElementById('radio-enable-btn').textContent, layerState: document.getElementById('radio-layer-state').textContent, message: document.getElementById('radio-playback-state').textContent, @@ -687,8 +731,6 @@ async function main() { const sample = await page.evaluate(async () => { const viewer = window.__godsEyeView.viewer; const radio = window.__godsEyeView.dataManager.layers.get('radio').module; - const dataSource = Array.from({ length: viewer.dataSources.length }, (_, index) => viewer.dataSources.get(index)) - .find((item) => item.name === 'Radio stations'); const { getOverlayPaintRect, getWorldOverlayDiagnostics } = await import('/src/overlays/worldOverlay.js'); const { radioStationIdFromPick } = await import('/src/data/radio.js'); return new Promise((resolve) => { @@ -710,7 +752,9 @@ async function main() { host: getWorldOverlayDiagnostics(), paintedSingletonIds, pickableSingletonIds, - nativeLabelCount: dataSource.entities.values.filter((entity) => Boolean(entity.label)).length, + // The station dots are a draw-port point set, which draws no + // labels of its own; a label primitive would be a row here. + nativeLabelCount: window.__qaRadioRows('stations').filter((row) => row.primitive.text !== undefined).length, }); }; const timeout = setTimeout(finish, 500); @@ -1255,12 +1299,10 @@ async function main() { }); await page.select('#radio-filter', 'all'); const allPalette = await page.evaluate(() => { - const source = Array.from({ length: window.__godsEyeView.viewer.dataSources.length }, (_, index) => ( - window.__godsEyeView.viewer.dataSources.get(index) - )).find((item) => item.name === 'Radio stations'); + const rows = new Map(window.__qaRadioRows('stations').map((row) => [row.id, row])); const colorFor = (index) => { const id = `radio:00000000-0000-4000-8000-${index.toString(16).padStart(12, '0')}`; - const color = source?.entities.getById(id)?.point?.color?.getValue?.(); + const color = rows.get(id)?.primitive.color; return color ? [color.red, color.green, color.blue].map((value) => Math.round(value * 255)) : null; }; return { news: colorFor(0), talk: colorFor(1), music: colorFor(7) }; @@ -1277,8 +1319,6 @@ async function main() { const viewer = window.__godsEyeView.viewer; const { getOverlayPaintRect, getWorldOverlayDiagnostics } = await import('/src/overlays/worldOverlay.js'); const baselineSolveRevision = getWorldOverlayDiagnostics().solveRevision; - const source = Array.from({ length: viewer.dataSources.length }, (_, index) => viewer.dataSources.get(index)) - .find((item) => item.name === 'Radio stations'); const ellipsoid = viewer.scene.globe.ellipsoid; viewer.camera.cancelFlight(); viewer.camera.setView({ @@ -1289,26 +1329,25 @@ async function main() { }), orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, }); - source.clustering.enabled = false; viewer.scene.requestRender(); - await new Promise((resolve) => setTimeout(resolve, 100)); + // The camera's move clusters the stations again: wait for a cluster dot. return new Promise((resolve) => { - const originalPixelRange = source.clustering.pixelRange; - const timeout = setTimeout(() => { - remove(); - resolve(null); - }, 2_000); - const remove = source.clustering.clusterEvent.addEventListener(async (entities, cluster) => { - clearTimeout(timeout); - remove(); + const started = performance.now(); + const poll = async () => { + const cluster = window.__qaRadioRows('clusters').find((row) => row.show); + if (!cluster) { + if (performance.now() - started > 2_000) resolve(null); + else setTimeout(poll, 50); + return; + } + // The cluster's dot is a draw-port point, which draws no label. const native = { - count: entities.length, - labelShow: cluster.label.show, - labelText: cluster.label.text, - pointSize: cluster.point.pixelSize, - pointMaxDistance: cluster.point.distanceDisplayCondition?.far ?? null, + count: cluster.meta.stationIds.length, + labelShow: cluster.primitive.text !== undefined, + labelText: cluster.primitive.text ?? '', + pointSize: cluster.primitive.pixelSize, + pointMaxDistance: cluster.primitive.distanceDisplayCondition?.far ?? null, }; - source.clustering.pixelRange = originalPixelRange; const radio = window.__godsEyeView.dataManager.layers.get('radio').module; await new Promise((done) => setTimeout(done, 0)); let painted = null; @@ -1345,9 +1384,8 @@ async function main() { source: radio.getOverlayDiagnostics(), host: painted?.host || getWorldOverlayDiagnostics(), }); - }); - source.clustering.enabled = true; - viewer.scene.requestRender(); + }; + poll(); }); }); check( @@ -1393,15 +1431,13 @@ async function main() { 0, cameraRadius * cameraRadius - ellipsoid.maximumRadius * ellipsoid.maximumRadius, )); - const points = Array.from({ length: viewer.dataSources.length }, (_, index) => viewer.dataSources.get(index)) - .find((item) => item.name === 'Radio stations')?.clustering?._clusterPointCollection; let clusterPoint = null; - // Pool order is not visibility order after a camera change. Choose an - // on-screen point independently of the native pick result being tested. + // Choose an on-screen cluster dot independently of the native pick + // result being tested. const visiblePoints = []; - for (let index = 0; index < (points?.length || 0); index += 1) { - const point = points.get(index); - if (!point?.show || !Array.isArray(point.id) || !point.id.length) continue; + for (const row of window.__qaRadioRows('clusters')) { + const point = row.primitive; + if (!row.show || !row.meta?.stationIds?.length) continue; const anchor = viewer.scene.cartesianToCanvasCoordinates(point.position); if (!anchor) continue; if (anchor.x < 0 || anchor.y < 0 || anchor.x > viewer.canvas.clientWidth || anchor.y > viewer.canvas.clientHeight) continue; @@ -2432,26 +2468,23 @@ async function main() { await sleep(700); const newsClusterTarget = await page.evaluate(() => { const gev = window.__godsEyeView; - const source = Array.from({ length: gev.viewer.dataSources.length }, (_, index) => gev.viewer.dataSources.get(index)) - .find((item) => item.name === 'Radio stations'); - const points = source.clustering._clusterPointCollection; - for (let index = 0; index < (points?.length || 0); index += 1) { - const point = points.get(index); - if (!point.show || !Array.isArray(point.id) || !point.id.length) continue; - const canvasPoint = gev.viewer.scene.cartesianToCanvasCoordinates(point.position); + const rows = window.__qaRadioRows('clusters'); + for (const row of rows) { + if (!row.show || !row.meta?.stationIds?.length) continue; + const canvasPoint = gev.viewer.scene.cartesianToCanvasCoordinates(row.primitive.position); if (!canvasPoint) continue; return { x: canvasPoint.x, y: canvasPoint.y, - firstId: String(point.id[0]?.id || '').replace(/^radio:/, ''), - pointIds: point.id.map((entity) => entity.id), + firstId: row.meta.stationIds[0], + pointIds: row.meta.stationIds.map((id) => `radio:${id}`), }; } return { missing: true, - points: Array.from({ length: points?.length || 0 }, (_, index) => ({ - show: points.get(index).show, - pointIds: Array.isArray(points.get(index)?.id) ? points.get(index).id.length : 0, + points: rows.map((row) => ({ + show: row.show, + pointIds: row.meta?.stationIds?.length || 0, })), }; }); @@ -2654,9 +2687,13 @@ async function main() { const horizon = await page.evaluate(async () => { const viewer = window.__godsEyeView.viewer; const ellipsoid = viewer.scene.globe.ellipsoid; - const source = Array.from({ length: viewer.dataSources.length }, (_, index) => viewer.dataSources.get(index)) - .find((item) => item.name === 'Radio stations'); - const visibleIds = () => source.entities.values.filter((entity) => entity.show).map((entity) => entity.id); + // A station dot standing in a cluster is hidden too; the cluster's + // dot draws its stations' ids. + const visibleIds = () => [ + ...window.__qaRadioRows('stations').filter((row) => row.show).map((row) => row.id), + ...window.__qaRadioRows('clusters').filter((row) => row.show) + .flatMap((row) => row.meta.stationIds.map((id) => `radio:${id}`)), + ]; const setView = (lon, lat = 0) => { viewer.camera.cancelFlight(); viewer.camera.setView({ @@ -2702,8 +2739,7 @@ async function main() { buttons: type === 'pointerup' || type === 'pointercancel' ? 0 : 1, })); const snapshot = () => { - const markerId = gev.viewer.entities.values - .find((entity) => String(entity.id).startsWith('radio:selected:'))?.id || null; + const markerId = window.__qaRadioSelected()?.id || null; return { slot: Number(slider.value), markerId, @@ -2823,8 +2859,7 @@ async function main() { // The tuner renders from the Radio store; let Vue patch before reading. await Promise.resolve(); const shiftedSlot = Number(slider.value); - const previewBeforeCancel = gev.viewer.entities.values - .find((entity) => String(entity.id).startsWith('radio:selected:'))?.id || null; + const previewBeforeCancel = window.__qaRadioSelected()?.id || null; const flyToCallsBeforeCancel = flyToCalls.length; pointer('pointercancel', targetIndex); await Promise.resolve(); @@ -2840,8 +2875,7 @@ async function main() { tuningActive: afterState.tuningActive, }; const flyToCallsAfterCancel = flyToCalls.length; - const selectedEntity = () => gev.viewer.entities.values - .find((entity) => String(entity.id).startsWith('radio:selected:')) || null; + const selectedEntity = () => window.__qaRadioSelected(); const restoredEntity = selectedEntity(); const previewId = restoredEntity?.id || null; after.previewId = previewId; @@ -2858,7 +2892,7 @@ async function main() { filter: changedFilterState.filter, restoredStationId: changedFilterState.tuningRestoredStationId, selectedId: changedFilterState.selected?.id || null, - entityRebuilt: Boolean(changedFilterEntity && changedFilterEntity !== restoredEntity), + entityRebuilt: Boolean(changedFilterEntity && changedFilterEntity.dot.primitive !== restoredEntity?.dot.primitive), entityId: changedFilterEntity?.id || null, snapshotPreserved: radio.getAcceptedCatalogSnapshot() === changedFilterSnapshot, playDelta: window.__qaRadioPlayCalls.length - changedFilterPlays, @@ -2882,7 +2916,7 @@ async function main() { restoredAfter: sameFilterState.tuningRestoredStationId, filter: sameFilterState.filter, selectedId: sameFilterState.selected?.id || null, - entityRebuilt: Boolean(sameFilterEntity && sameFilterEntity !== sameFilterRestoredEntity), + entityRebuilt: Boolean(sameFilterEntity && sameFilterEntity.dot.primitive !== sameFilterRestoredEntity?.dot.primitive), entityId: sameFilterEntity?.id || null, snapshotPreserved: radio.getAcceptedCatalogSnapshot() === sameFilterSnapshot, playDelta: window.__qaRadioPlayCalls.length - sameFilterPlays, @@ -3327,8 +3361,7 @@ async function main() { cancelable: true, key: value, })); - const markerId = () => gev.viewer.entities.values - .find((entity) => String(entity.id).startsWith('radio:selected:'))?.id || null; + const markerId = () => window.__qaRadioSelected()?.id || null; const startIndex = Number(slider.value); const expectedIndex = Math.min(style._radioControls._radioTunerStations.length - 1, startIndex + 1); const expectedId = style._radioControls._radioTunerStations[expectedIndex]?.id || null; @@ -3428,8 +3461,7 @@ async function main() { centerIndex, slot: Number(slider.value), ratio: Number(document.getElementById('radio-tuner').style.getPropertyValue('--radio-tuner-ratio')), - markerId: gev.viewer.entities.values - .find((entity) => String(entity.id).startsWith('radio:selected:'))?.id || null, + markerId: window.__qaRadioSelected()?.id || null, expectedId: style._radioControls._radioTunerStations[centerIndex]?.id || null, }; slider.dispatchEvent(new PointerEvent('pointercancel', { @@ -3554,9 +3586,6 @@ async function main() { const markerTarget = await page.evaluate(async () => { const viewer = window.__godsEyeView.viewer; const radio = window.__godsEyeView.dataManager.layers.get('radio').module; - const source = Array.from({ length: viewer.dataSources.length }, (_, index) => viewer.dataSources.get(index)) - .find((item) => item.name === 'Radio stations'); - source.clustering.enabled = false; const selectedId = radio.getUIState().selected?.id || null; if (selectedId) { radio.selectStation(selectedId, { @@ -3583,9 +3612,6 @@ async function main() { }); viewer.scene.requestRender(); }); - // Cesium clears its private cluster collections during the rendered - // disabled-state update. Publish the same-filter singleton overlay only - // after that frame so this harness mutation cannot leak stale clusters. radio.setFilter('news'); viewer.scene.requestRender(); await new Promise((resolve) => setTimeout(resolve, 500)); @@ -3614,14 +3640,14 @@ async function main() { let visibleEntityCount = 0; let singletonEntityCount = 0; let paintedSingletonCount = 0; - for (const entity of source.entities.values) { - if (!entity.show) continue; + for (const row of window.__qaRadioRows('stations')) { + if (!row.show) continue; visibleEntityCount += 1; - const id = String(entity.id).slice('radio:'.length); + const id = String(row.id).slice('radio:'.length); const overlayId = `station:${id}`; if (!singletonIds.has(overlayId)) continue; singletonEntityCount += 1; - const position = entity.position?.getValue(viewer.clock.currentTime); + const position = row.primitive.position; const canvas = position && viewer.scene.cartesianToCanvasCoordinates(position); const paintRect = getOverlayPaintRect('radio', overlayId); if (paintRect) paintedSingletonCount += 1; @@ -3631,7 +3657,7 @@ async function main() { id, x: canvas.x, y: canvas.y, - ownsNativeLabel: Boolean(entity.label), + ownsNativeLabel: row.primitive.text !== undefined, labelPainted: true, singletonTexts: diagnostics.singletonTexts, }); @@ -3700,8 +3726,6 @@ async function main() { orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, }); radio.stopPlayback(); - Array.from({ length: gev.viewer.dataSources.length }, (_, index) => gev.viewer.dataSources.get(index)) - .find((item) => item.name === 'Radio stations').clustering.enabled = true; // Next plays only while a stream is active, so start from a playing station. radio.selectStation('00000000-0000-4000-8000-000000000001', { autoplay: true, focus: false }); }); @@ -3757,8 +3781,7 @@ async function main() { const playing = await page.evaluate(async () => { const radio = window.__godsEyeView.dataManager.layers.get('radio').module; const viewer = window.__godsEyeView.viewer; - const selectedEntity = window.__godsEyeView.viewer.entities.values - .find((entity) => String(entity.id).startsWith('radio:selected:')); + const selectedEntity = window.__qaRadioSelected(); const { getWorldOverlayDiagnostics } = await import('/src/overlays/worldOverlay.js'); const flightTargets = window.__qaRadioFlyToCalls.map(({ destination }) => { const position = viewer.scene.globe.ellipsoid.cartesianToCartographic(destination); @@ -3775,11 +3798,10 @@ async function main() { flightTargets, cameraHeight: window.__qaRadioCameraHeight, playLabel: document.getElementById('radio-play-btn').getAttribute('aria-label'), - regularMarkerSize: Array.from({ length: window.__godsEyeView.viewer.dataSources.length }, (_, index) => window.__godsEyeView.viewer.dataSources.get(index)) - .find((item) => item.name === 'Radio stations')?.entities.values[0]?.point?.pixelSize?.getValue(), - selectedMarkerSize: selectedEntity?.point?.pixelSize?.getValue(), - selectedBracketWidth: selectedEntity?.billboard?.width?.getValue(), - selectedOwnsNativeLabel: Boolean(selectedEntity?.label), + regularMarkerSize: window.__qaRadioRows('stations')[0]?.primitive.pixelSize, + selectedMarkerSize: selectedEntity?.dot.primitive.pixelSize, + selectedBracketWidth: selectedEntity?.bracket?.primitive.width, + selectedOwnsNativeLabel: Boolean(window.__qaRadioRows('selected-label').length), overlay: radio.getOverlayDiagnostics(), host: getWorldOverlayDiagnostics(), expectedPrimary: window.__qaRadioExpectedPrimary, @@ -3817,7 +3839,7 @@ async function main() { id: `qa:${ownerPrefix}:radio-camera-owner`, position: viewer.camera.positionWC.clone(), }); - owner.gevTrackedId = `${ownerPrefix}:qa-radio-camera-owner`; + window.__godsEyeView.entityRecords.write(owner).trackedId = `${ownerPrefix}:qa-radio-camera-owner`; viewer.trackedEntity = owner; await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))); const beforeStationId = radio.getUIState().selected?.id || null; @@ -3831,7 +3853,7 @@ async function main() { afterStationId: radio.getUIState().selected?.id || null, flyToDelta: window.__qaRadioFlyToCalls.length - beforeFlyToCalls, trackedIdentityPreserved: viewer.trackedEntity === owner, - trackedId: viewer.trackedEntity?.gevTrackedId || null, + trackedId: window.__godsEyeView.entityRecords.read(viewer.trackedEntity)?.trackedId || null, }; viewer.trackedEntity = undefined; viewer.entities.remove(owner); @@ -3867,11 +3889,11 @@ async function main() { id: 'qa:flights:delayed-radio-fallback-owner', position: viewer.camera.positionWC.clone(), }); - owner.gevTrackedId = 'flights:qa-delayed-radio-fallback-owner'; + window.__godsEyeView.entityRecords.write(owner).trackedId = 'flights:qa-delayed-radio-fallback-owner'; viewer.trackedEntity = owner; window.__qaDelayedRadioTrackingOwner = owner; window.__qaRejectRadioPlay(); - return owner.gevTrackedId; + return window.__godsEyeView.entityRecords.read(owner)?.trackedId; }); await page.waitForFunction(() => window.__godsEyeView.dataManager.layers.get('radio').module.getUIState().audioState === 'playing'); const delayedFallbackOwnership = await page.evaluate((beforeFlyToCalls) => { @@ -3880,7 +3902,7 @@ async function main() { const result = { flyToDelta: window.__qaRadioFlyToCalls.length - beforeFlyToCalls, trackedIdentityPreserved: viewer.trackedEntity === owner, - trackedId: viewer.trackedEntity?.gevTrackedId || null, + trackedId: window.__godsEyeView.entityRecords.read(viewer.trackedEntity)?.trackedId || null, selectedId: window.__godsEyeView.dataManager.layers.get('radio').module.getUIState().selected?.id || null, }; viewer.trackedEntity = undefined; @@ -3940,8 +3962,12 @@ async function main() { destination, orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, }); - const selectedEntity = viewer.entities.values - .find((entity) => String(entity.id) === `radio:selected:${selected.id}`); + // The selected station's drawn dot and bracket, read afresh: Radio's + // horizon pass shows them on its own timer. + const selectedEntity = () => { + const drawn = window.__qaRadioSelected(); + return drawn?.id === `radio:selected:${selected.id}` ? drawn : null; + }; const { getOverlayPaintRect, getWorldOverlayDiagnostics } = await import('/src/overlays/worldOverlay.js'); const expectedEntryId = `selected:${selected.id}`; let painted = null; @@ -3949,7 +3975,7 @@ async function main() { // after the camera jump, so a stationary view waits for both to settle. for ( let attempt = 0; - attempt < 20 && !(painted?.rect && selectedEntity?.show === true); + attempt < 20 && !(painted?.rect && selectedEntity()?.show === true); attempt += 1 ) { painted = await new Promise((resolve) => { @@ -3974,7 +4000,7 @@ async function main() { expectedEntryId, rect: painted?.rect || null, host: painted?.host || getWorldOverlayDiagnostics(), - selectedEntityShow: selectedEntity?.show, + selectedEntityShow: selectedEntity()?.show, cameraHeight: viewer.camera.positionCartographic.height, }; }); @@ -3999,8 +4025,12 @@ async function main() { }), orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, }); - const selectedEntity = viewer.entities.values - .find((entity) => String(entity.id) === `radio:selected:${selected.id}`); + // The selected station's drawn dot and bracket, read afresh: Radio's + // horizon pass shows them on its own timer. + const selectedEntity = () => { + const drawn = window.__qaRadioSelected(); + return drawn?.id === `radio:selected:${selected.id}` ? drawn : null; + }; const { getOverlayPaintRect, getWorldOverlayDiagnostics } = await import('/src/overlays/worldOverlay.js'); const expectedEntryId = `selected:${selected.id}`; let rect = null; @@ -4025,7 +4055,8 @@ async function main() { viewer.scene.requestRender(); }); } - const entityPosition = selectedEntity?.position?.getValue?.(); + const selectedDrawn = selectedEntity(); + const entityPosition = selectedDrawn?.position; const entityAnchor = entityPosition && viewer.scene.cartesianToCanvasCoordinates(entityPosition); let selectedNativePick = null; @@ -4035,13 +4066,16 @@ async function main() { // billboard satisfy the loop while the point anchor was still missing. for (let attempt = 0; entityAnchor && attempt < 8 && !selectedPointPick; attempt += 1) { const picks = viewer.scene.drillPick(entityAnchor, 16) || []; - selectedNativePick = picks.find((picked) => picked?.id === selectedEntity); + selectedNativePick = picks.find((picked) => ( + picked?.primitive === selectedDrawn.dot.primitive + || picked?.primitive === selectedDrawn.bracket?.primitive + )); selectedPointPick = picks.find((picked) => ( - picked?.id === selectedEntity + picked?.primitive === selectedDrawn.dot.primitive && String(picked?.primitive?.constructor?.name || '').includes('PointPrimitive') )); selectedBillboardPick = picks.find((picked) => ( - picked?.id === selectedEntity + picked?.primitive === selectedDrawn.bracket?.primitive && String(picked?.primitive?.constructor?.name || '').includes('Billboard') )); if (!selectedPointPick) { @@ -4054,18 +4088,15 @@ async function main() { }); } } - const selectedPointDistance = selectedEntity?.point?.distanceDisplayCondition?.getValue?.(); + const selectedPointDistance = selectedDrawn?.dot.primitive.distanceDisplayCondition; return { rect, selectedNativePickable: Boolean(selectedNativePick), selectedPointPickable: Boolean(selectedPointPick), selectedBillboardPickable: Boolean(selectedBillboardPick), selectedPointMaxDistance: selectedPointDistance?.far ?? null, - selectedEntityShow: selectedEntity?.show, - selectedBracketVisible: Boolean( - selectedEntity?.billboard - && selectedEntity.billboard.show?.getValue?.() !== false - ), + selectedEntityShow: selectedDrawn?.show, + selectedBracketVisible: Boolean(selectedDrawn?.bracket?.show), entityAnchor: entityAnchor ? { x: entityAnchor.x, y: entityAnchor.y } : null, entityDistance: entityPosition ? Math.hypot( @@ -4222,7 +4253,7 @@ async function main() { id: 'qa:flights:radio-recenter-stage-owner', position: viewer.camera.positionWC.clone(), }); - owner.gevTrackedId = 'flights:qa-radio-recenter-stage-owner'; + window.__godsEyeView.entityRecords.write(owner).trackedId = 'flights:qa-radio-recenter-stage-owner'; viewer.trackedEntity = owner; completeFlight(0); const trackingBetweenStagesCalls = calls.length; diff --git a/scripts/qa-scene-controls.mjs b/scripts/qa-scene-controls.mjs index bda4a407ce..7247123d57 100644 --- a/scripts/qa-scene-controls.mjs +++ b/scripts/qa-scene-controls.mjs @@ -45,7 +45,7 @@ try { window.__qaSceneState.push(notification), ); }); - await page.click('[data-collapse-target="scene-panel"]'); + await page.click('[data-rail-item="scene-panel"]'); await page.click('#scene-new-btn'); await page.waitForFunction( () => @@ -278,7 +278,7 @@ try { panel.classList.contains('collapsed'), ) ) - await page.click('[data-collapse-target="scene-panel"]'); + await page.click('[data-rail-item="scene-panel"]'); await page.waitForSelector('#scene-download-btn', { visible: true }); await page.click('#scene-download-btn'); const metadata = await page.evaluate(async () => @@ -426,6 +426,10 @@ try { ); }), ); + promptValue = 'Disposal scene'; + await page.click('#scene-new-btn'); + await page.click('#scene-capture-btn'); + await page.waitForSelector('.scene-shot-label', { visible: true }); const teardown = await page.evaluate(async () => { const director = window.__godsEyeView.sceneDirector; const controls = director._controls; diff --git a/scripts/qa-sky-model-lighting.mjs b/scripts/qa-sky-model-lighting.mjs index 2f401506bf..6352a3be96 100644 --- a/scripts/qa-sky-model-lighting.mjs +++ b/scripts/qa-sky-model-lighting.mjs @@ -32,13 +32,15 @@ try { const results = await page.evaluate(async () => { window.CESIUM_BASE_URL = '/cesium/'; // Use StarrySky's exact Vite dependency URL, including its version query. - const source = await fetch('/src/sky/starrySky.js').then((r) => r.text()); + const source = await fetch('/src/render/cesium/starrySky.js').then((r) => + r.text(), + ); const cesiumUrl = source.match( /from ["']([^"']*\/cesium\.js[^"']*)["']/, )?.[1]; if (!cesiumUrl) throw new Error('run against the Vite dev server'); const C = await import(cesiumUrl); - const { StarrySky } = await import('/src/sky/starrySky.js'); + const { StarrySky } = await import('/src/render/cesium/starrySky.js'); const time = C.JulianDate.fromIso8601('2026-10-19T00:00:00Z'); const results = {}; for (const kind of ['black', 'starry', 'white']) { @@ -75,7 +77,7 @@ try { } const position = C.Cartesian3.fromDegrees(0, 0, 10000); const model = await C.Model.fromGltfAsync({ - url: '/models/airplane.glb', + url: '/models/fleet/aircraft/a320.glb', modelMatrix: C.Transforms.eastNorthUpToFixedFrame(position), }); scene.primitives.add(model); diff --git a/scripts/qa-sprites-b5.mjs b/scripts/qa-sprites-b5.mjs index 7e5b824c0b..7f6815c349 100644 --- a/scripts/qa-sprites-b5.mjs +++ b/scripts/qa-sprites-b5.mjs @@ -13,11 +13,11 @@ * B1 ingest : both layers ingest the synthetic planes * B2 billboards : every fleet billboard carries EXACTLY the expected * per-class glyph (image data-URI === aircraftIcon(klass), - * imported from src) and per-class scale (flights: - * CLASS_SCALE_2D; military: 0.7 × CLASS_SCALE_2D) - * B3 models : with 3D on, fleet Cesium.Model.scale === the layer's - * MODEL_SCALE (both 1; legacy scale is baked into the GLB) - * × CLASS_SCALE_3D[klass] per icao; tracked too + * imported from src) and one scale for every class + * (flights: 1; military: 0.7) + * B3 models : with 3D on, fleet Cesium.Model.scale === the life-size + * scale of the fleet model the aircraft's type or category + * selects (aircraftModelSpec) per icao; tracked too * B4 clean : no console errors * * Visual output (qa-shots/b5/, untracked): top-down 2D spreads of both rows, @@ -33,15 +33,18 @@ import fs from 'node:fs'; import path from 'node:path'; import puppeteer from 'puppeteer'; import { stubPlanespotters } from './qa-photo-stub.mjs'; -import { classifyAircraft, CLASS_SCALE_2D, CLASS_SCALE_3D, CLASS_MODEL_REAL } from '../src/data/aircraftClass.js'; -// Hangar fleet (2026-08-16): real per-class GLBs render at scale 1; military -// heavies (airliner/quadjet/glider) render airplane.glb at 1 x class; only -// fastjet/unknown keep the per-layer jet/airplane MODEL_SCALE formula. -const flightsWantScale = (klass) => (CLASS_MODEL_REAL[klass] ? 1 : FL_MODEL_SCALE * CLASS_SCALE_3D[klass]); -const MIL_PLANE_CLASSES = new Set(['airliner', 'quadjet', 'glider']); -const militaryWantScale = (klass) => (CLASS_MODEL_REAL[klass] ? 1 - : MIL_PLANE_CLASSES.has(klass) ? MIL_PLANE_MODEL_SCALE * CLASS_SCALE_3D[klass] - : MIL_MODEL_SCALE * CLASS_SCALE_3D[klass]); +import { classifyAircraft } from '../src/data/aircraftClass.js'; +import { aircraftModelSpec } from '../src/data/fleetModels.js'; +// Every aircraft draws its fleet model life size: its type's length over the +// model's built length, chosen by type code (military) or category (flights). +const FLEET_SET = Object.freeze({ + catalog: JSON.parse(fs.readFileSync(new URL('../public/models/fleet/catalog.json', import.meta.url), 'utf8')), + types: JSON.parse(fs.readFileSync(new URL('../public/models/fleet/types.json', import.meta.url), 'utf8')), +}); +const flightsWantScale = (icao) => + aircraftModelSpec(FLEET_SET, { category: SPRITES.flights.find((p) => p.icao === icao)?.category }).scale; +const militaryWantScale = (hex) => + aircraftModelSpec(FLEET_SET, { typeCode: SPRITES.military.find((p) => p.hex === hex)?.t }).scale; import { aircraftIcon } from '../src/data/aircraftIcons.js'; // --------------------------------------------------------------------------- @@ -58,9 +61,6 @@ const APP_URL = getOpt('--url', 'http://localhost:4173'); const HEADFUL = getFlag('--headful'); const SHOT_DIR = path.resolve('qa-shots/b5'); -const FL_MODEL_SCALE = 1; // flights.js (airplane.glb is transform-applied and meter-scale) -const MIL_PLANE_MODEL_SCALE = 1; // military heavy classes share the same baked airplane.glb -const MIL_MODEL_SCALE = 1; // militaryFlights.js (jet.glb is already real-world scale, native radius ~29.8 m) const MIL_BILLBOARD_SCALE = 0.7; // militaryFlights BILLBOARD_SCALE const CHROME_EXECUTABLE_CANDIDATES = [ @@ -134,10 +134,9 @@ const SPRITES = { // course 0 like the rest — keeps the row a clean size-comparison line (2D // rotation is demoed by caa004 and gated by qa-heading-b3 anyway). { hex: 'dda008', flight: 'ML-FJ', t: 'F16', lon0: ROW_LON0 + 7 * ROW_STEP_DEG, lat0: 30.28, courseDeg: 0, speedMps: 80, altFt: 15000 }, - // 3D cluster: C17 vs F16 (tracked) vs B744 vs C130. jet.glb is a - // real-world-scale asset (native bounding radius ~29.8) rendered at - // MODEL_SCALE 1, so models are ~22–43 m radius — same 150 m spacing and - // 450–900 m shot ranges as the flights cluster. + // 3D cluster: C17 vs F16 (tracked) vs B744 vs C130, each drawn life size + // (~8–36 m radius) — same 150 m spacing and 450–900 m shot ranges as the + // flights cluster. { hex: 'ddb001', flight: '3DMWID', t: 'C17', lon0: CLUSTER_LON0 - mDegLon(150, 30.05), lat0: 30.05, courseDeg: 0, speedMps: 60, altFt: 12000 }, { hex: 'ddb002', flight: '3DMFJ', t: 'F16', lon0: CLUSTER_LON0, lat0: 30.05, courseDeg: 0, speedMps: 60, altFt: 12000 }, { hex: 'ddb003', flight: '3DMQUA', t: 'B744', lon0: CLUSTER_LON0 + mDegLon(150, 30.05), lat0: 30.05, courseDeg: 0, speedMps: 60, altFt: 12000 }, @@ -382,14 +381,14 @@ async function main() { for (const [id, klass] of expectedFlights) { const bb = bbById.get(id); const wantImg = aircraftIcon(klass); - const wantScale = CLASS_SCALE_2D[klass] || 1; + const wantScale = 1; if (!bb || bb.image !== wantImg) glyphBad.push(`${id}(${klass})${bb ? ':wrong-image' : ':missing'}`); if (bb && Math.abs(bb.scale - wantScale) > 1e-9) scaleBad.push(`${id}: ${bb.scale} != ${wantScale}`); } for (const [id, klass] of expectedMilitary) { const bb = bbById.get(id); const wantImg = aircraftIcon(klass); - const wantScale = MIL_BILLBOARD_SCALE * (CLASS_SCALE_2D[klass] || 1); + const wantScale = MIL_BILLBOARD_SCALE; if (!bb || bb.image !== wantImg) glyphBad.push(`${id}(${klass})${bb ? ':wrong-image' : ':missing'}`); if (bb && Math.abs(bb.scale - wantScale) > 1e-9) scaleBad.push(`${id}: ${bb.scale} != ${wantScale}`); } @@ -464,7 +463,7 @@ async function main() { // ======================================================================== // B3 + 3D screenshots — flights cluster // ======================================================================== - console.log('\n3D — flights cluster (airplane.glb, per-class scale)'); + console.log('\n3D — flights cluster (fleet models, life size)'); await page.evaluate(() => { const dm = window.__godsEyeView.dataManager; dm.layers.get('flights').module.setParams({ models3d: true }); @@ -481,20 +480,20 @@ async function main() { const flModels = await page.evaluate(() => window.__collectModels().filter((m) => m.ready)); const modelScaleBad = []; for (const [id, want] of [ - ['cbb001', flightsWantScale(expectedFlights.get('cbb001'))], - ['cbb003', flightsWantScale(expectedFlights.get('cbb003'))], + ['cbb001', flightsWantScale('cbb001')], + ['cbb003', flightsWantScale('cbb003')], ]) { const m = flModels.find((x) => x.id === id); if (!m || Math.abs(m.scale - want) > 1e-9) modelScaleBad.push(`${id}: ${m ? m.scale : 'missing'} != ${want}`); } const trackedM = flModels.find((x) => x.id === 'cbb002'); - const trackedWant = flightsWantScale(expectedFlights.get('cbb002')); + const trackedWant = flightsWantScale('cbb002'); if (!trackedM || Math.abs(trackedM.scale - trackedWant) > 1e-9) { modelScaleBad.push(`tracked: ${trackedM ? trackedM.scale : 'missing'} != ${trackedWant}`); } - record('B3a flights: model scales match the per-class registry (all GLBs meter-scale; shared @1×class)', + record('B3a flights: model scales match each type's life-size fleet model', modelScaleBad.length === 0, - modelScaleBad.length ? modelScaleBad.join(' ') : 'all exact per registry'); + modelScaleBad.length ? modelScaleBad.join(' ') : 'all exact'); console.log(` world bounding radii (m): ${flModels.filter((m) => m.scale !== undefined).map((m) => `${m.id ?? 'tracked'}=${m.radius?.toFixed(1)}`).join(' ')}`); await sleep(1500); @@ -509,7 +508,7 @@ async function main() { // ======================================================================== // B3 + 3D screenshots — military cluster // ======================================================================== - console.log('\n3D — military cluster (jet.glb, per-class scale)'); + console.log('\n3D — military cluster (fleet models, life size)'); await page.evaluate(() => { const dm = window.__godsEyeView.dataManager; dm.layers.get('military').module.setParams({ models3d: true }); @@ -526,25 +525,25 @@ async function main() { const milModels = await page.evaluate(() => window.__collectModels().filter((m) => m.ready)); const modelScaleBad = []; for (const [id, want] of [ - ['ddb001', militaryWantScale(expectedMilitary.get('ddb001'))], - ['ddb003', militaryWantScale(expectedMilitary.get('ddb003'))], - ['ddb004', militaryWantScale(expectedMilitary.get('ddb004'))], + ['ddb001', militaryWantScale('ddb001')], + ['ddb003', militaryWantScale('ddb003')], + ['ddb004', militaryWantScale('ddb004')], ]) { const m = milModels.find((x) => x.id === id); if (!m || Math.abs(m.scale - want) > 1e-9) modelScaleBad.push(`${id}: ${m ? m.scale : 'missing'} != ${want}`); } const trackedM = milModels.find((x) => x.id === 'ddb002'); - const trackedWant = militaryWantScale(expectedMilitary.get('ddb002')); + const trackedWant = militaryWantScale('ddb002'); if (!trackedM || Math.abs(trackedM.scale - trackedWant) > 1e-9) { modelScaleBad.push(`tracked: ${trackedM ? trackedM.scale : 'missing'} != ${trackedWant}`); } - record('B3b military: model scales match the weight-class registry (real/heavy/jet assets @1×class)', + record('B3b military: model scales match each type's life-size fleet model', modelScaleBad.length === 0, - modelScaleBad.length ? modelScaleBad.join(' ') : 'all exact per registry'); + modelScaleBad.length ? modelScaleBad.join(' ') : 'all exact'); console.log(` world bounding radii (m): ${milModels.filter((m) => m.scale !== undefined).map((m) => `${m.id ?? 'tracked'}=${m.radius?.toFixed(1)}`).join(' ')}`); await sleep(1500); - // jet.glb at MODEL_SCALE 1 is real-world size — same shot ranges as the + // Fleet models are drawn life size — same shot ranges as the // flights cluster (close zoom no longer puts the camera inside a model). await zoomToRange(900); await page.screenshot({ path: path.join(SHOT_DIR, 'b5-3d-military-far.png') }); diff --git a/scripts/qa-stories.mjs b/scripts/qa-stories.mjs new file mode 100644 index 0000000000..bee07f4fa9 --- /dev/null +++ b/scripts/qa-stories.mjs @@ -0,0 +1,146 @@ +/** Run against the built app's preview server (QA_BASE_URL, port 4173 by default). */ +import assert from 'node:assert/strict'; +import puppeteer from 'puppeteer'; + +const browser = await puppeteer.launch({ + headless: true, + args: [ + '--no-sandbox', + ...(process.platform === 'darwin' + ? ['--use-angle=metal', '--enable-gpu'] + : ['--use-gl=angle', '--use-angle=swiftshader']), + ], +}); + +try { + const page = await browser.newPage(); + await page.setViewport({ width: 1440, height: 900 }); + await page.emulateMediaFeatures([ + { name: 'prefers-reduced-motion', value: 'reduce' }, + ]); + const url = new URL(process.env.QA_BASE_URL || 'http://localhost:4173/'); + url.searchParams.set('welcome', '0'); + url.searchParams.set('story', 'gev:flights-radar'); + url.searchParams.set('storyTime', '1250'); + url.hash = + 'v=2&lat=20&lon=10&alt=2500000&heading=0&pitch=-90&roll=0&style=normal&map=esri-imagery'; + await page.goto(url.href, { waitUntil: 'domcontentloaded' }); + + async function waitForPausedStory() { + await page.waitForSelector('#tlTrack', { visible: true, timeout: 60000 }); + await page.waitForFunction( + () => window.__godsEyeView?.styleManager.activeStyle === 'retro', + { timeout: 30000 }, + ); + const timing = await page.evaluate(async () => { + const director = window.__godsEyeView.sceneDirector; + await director.whenIdle(); + return { + elapsed: director.getPlaybackTimingState().snapshot.sceneElapsedSec, + running: director.running, + }; + }); + assert.equal(timing.running, false); + assert.ok(Math.abs(timing.elapsed - 1.25) < 0.001); + } + + await waitForPausedStory(); + await page.evaluate(() => history.back()); + await page.waitForSelector('#scrExplore', { visible: true }); + await page.waitForFunction( + () => window.__godsEyeView.styleManager.activeStyle === 'normal', + ); + await page.evaluate(() => history.forward()); + await waitForPausedStory(); + await page.waitForFunction(() => + document.activeElement.matches( + '#scrStory .s-back, #scrStory .s-trail button', + ), + ); + console.log('Back and Forward restore the style, paused time and focus'); + + await page.click('#tlPlay'); + const resumedAt = await ( + await page.waitForFunction( + () => { + const snap = + window.__godsEyeView.sceneDirector.getPlaybackTimingState().snapshot; + return snap?.running ? snap.sceneElapsedSec : false; + }, + { timeout: 30000 }, + ) + ).jsonValue(); + assert.ok( + resumedAt >= 1.25 && resumedAt < 3, + `Play went on from ${resumedAt} s, not the paused 1.25 s`, + ); + await page.click('#tlPlay'); + await page.waitForFunction(() => !window.__godsEyeView.sceneDirector.running); + await page.evaluate(() => window.__godsEyeView.sceneDirector.whenIdle()); + console.log('Play goes on from the paused time, not the start of the shot'); + + const track = await page.$('#tlTrack'); + const box = await track.boundingBox(); + assert.ok(box.width > 0); + await page.evaluate(() => { + const director = window.__godsEyeView.sceneDirector; + const seek = director.seekScene.bind(director); + window.qaSeekProgress = []; + director.seekScene = (...args) => { + window.qaSeekProgress.push(args[1]); + return seek(...args); + }; + }); + const y = box.y + box.height / 2; + const at = (fraction) => box.x + box.width * fraction; + await page.mouse.move(at(0.25), y); + await page.mouse.down(); + await page.mouse.move(at(0.65), y, { steps: 12 }); + await page.waitForFunction( + () => + Number(document.querySelector('#tlTrack').getAttribute('aria-valuenow')) > + 25, + ); + assert.deepEqual(await page.evaluate(() => window.qaSeekProgress), []); + await page.mouse.up(); + await page.waitForFunction(() => window.qaSeekProgress.length === 1); + await page.evaluate(() => window.__godsEyeView.sceneDirector.whenIdle()); + assert.equal(await page.evaluate(() => window.qaSeekProgress.length), 1); + console.log('A timeline drag updates the preview before one released seek'); + + const pose = () => + page.evaluate(() => window.__godsEyeView.styleManager.getCameraState()); + const before = await pose(); + await page.click('#railGev'); + await page.waitForFunction( + () => + !document.body.classList.contains('stories-mode') && + document + .querySelector('#scene-select option:checked') + ?.textContent.includes('Global Flights Radar'), + ); + const after = await pose(); + assert.ok(Math.abs(after.lat - before.lat) < 0.01); + assert.ok(Math.abs(after.lon - before.lon) < 0.01); + assert.ok(Math.abs(after.alt - before.alt) < 100); + await page.waitForFunction(() => document.activeElement.id === 'hStories'); + console.log('Open in GEV selects the scene without moving its camera'); + await page.click('#scene-thumb-btn'); + await page.waitForFunction(() => + document + .querySelector('#scene-thumb-preview') + ?.src.startsWith('data:image/jpeg;'), + ); + console.log('Authoring captures an Esri thumbnail through the real renderer'); + + // This width is within GEV's phone layout and used to miss Stories' layout. + await page.setViewport({ width: 710, height: 844 }); + await page.goto(url.href, { waitUntil: 'domcontentloaded' }); + await waitForPausedStory(); + await page.waitForFunction(() => + document.activeElement.matches('#scrStory .s-back'), + ); + console.log('The phone layout uses the same breakpoint as GEV'); +} finally { + await browser.close(); +} diff --git a/scripts/qa-street-level.mjs b/scripts/qa-street-level.mjs index 982c4e581f..3dd0a3aa5f 100644 --- a/scripts/qa-street-level.mjs +++ b/scripts/qa-street-level.mjs @@ -46,6 +46,15 @@ const VIEWPORT = { width: 1440, height: 900 }; /** Over downtown Sacramento, above the fixture photo line, looking down. */ const PARK = { lon: PHOTO_LINE.lon, lat: 38.5816, height: 900, pitch: -1.3 }; const DAY_MS = 86_400_000; +/** A Sacramento street with Street View, for the sl=google link step. */ +const STREET_VIEW_STREET = Object.freeze({ lon: -121.49372, lat: 38.57986 }); +/** + * What a Street View lookup and load cost: the Maps JS API's + * SingleImageSearch (the nearest lookup), GetMetadata and the panorama tiles. + * Script loads are not counted. + */ +const STREET_VIEW_REQUEST = + /MapsJsInternalService\/(SingleImageSearch|GetMetadata)|GeoPhotoService|streetviewpixels-pa\.googleapis\.com/; /** * Coverage for any street-zoom tile: a grid of 360°/flat, recent/old @@ -234,6 +243,28 @@ async function boot(page, url) { }); } +/** + * Open a share link as a fresh document. Changing only the hash of a live + * page and reloading races the app's share-link writer, which can put its own + * state back in the hash before the reload reads it. The page's fixtures (a + * CDP session on the page) carry over. + */ +async function bootLink(page, link) { + await page.goto('about:blank'); + await boot(page, link); +} + +/** The camera's position in degrees and metres. */ +const cameraAt = (page) => + page.evaluate(() => { + const c = window.__godsEyeView.viewer.camera.positionCartographic; + return { + lon: (c.longitude * 180) / Math.PI, + lat: (c.latitude * 180) / Math.PI, + height: c.height, + }; + }); + /** Run `test(uiState, arg)` in the page until it is true. */ const uiUntil = (page, test, arg = null, timeout = 30_000) => page.waitForFunction( @@ -347,7 +378,9 @@ const findPick = (page, prefix, { box = null, step = 3 } = {}) => }; for (let py = y; py < y + h; py += stride) for (let px = x; px < x + w; px += stride) { - const id = scene.pick({ x: px, y: py })?.id; + // A drawn item's pick id names its draw set and its own id. + const picked = scene.pick({ x: px, y: py })?.id; + const id = typeof picked === 'string' ? picked : picked?.id; if (typeof id === 'string' && id.startsWith(want)) return { x: rect.left + px, @@ -780,6 +813,219 @@ async function main() { await uiUntil(page, litAlone, 'mapillary'); await park(page); + const base = url.split('#')[0]; + await fixtureStep( + 'a link to street-level photos (sl=) opens the photo at its point once the link restores', + async () => { + const photo = fixture.images[0]; + // The camera sits ~330 m north of the photo: the lookup must use + // the link's point, not the view centre. + const cameraLat = Number((photo.lat + 0.003).toFixed(6)); + await bootLink( + page, + `${base}#v=2&lat=${cameraLat}&lon=${photo.lon}&alt=600&heading=0&pitch=-60&roll=0&sl=mapillary,${photo.lat},${photo.lon}`, + ); + await uiUntil( + page, + (u) => (u.street.imageId && !u.street.loading) || u.street.error, + null, + 90_000, + ); + const { street } = await getUI(page); + assert.equal(street.error, null, `viewer error: ${street.error}`); + assert.equal(street.providerId, 'mapillary'); + assert.equal( + street.imageId, + photo.id, + `the photo at the link's point, not the one nearest the camera: ${street.imageId}`, + ); + assert.equal( + await page.evaluate(() => location.hash.includes('sl=')), + false, + 'the rewritten link no longer carries the one-shot request', + ); + }, + ); + + await fixtureStep( + 'the show_street_level action opens the nearest photo at a point without a pointer', + async () => { + await page.evaluate(() => + window.__godsEyeView.dataManager.layers + .get('street-level') + .module.closeViewer(), + ); + const photo = fixture.images[0]; + const result = await page.evaluate( + (at) => + window.__godsEyeView.voiceCommands.runner('show_street_level', { + latitude: at.lat, + longitude: at.lon, + provider: 'mapillary', + fly: false, + }), + { lat: photo.lat, lon: photo.lon }, + ); + assert.equal( + result.ok, + true, + `action failed: ${result.stage} ${result.error}`, + ); + assert.equal(result.provider, 'mapillary'); + assert.ok( + fixture.images.some((image) => image.id === result.imageId), + `a fixture photo opened: ${result.imageId}`, + ); + assert.match(result.say || '', /^Mapillary at /); + }, + ); + + await step( + 'an sl=google link never loads a photo by itself: keyless it stops at the key, keyed it arms and waits for OPEN', + async ({ skipped }) => { + const point = STREET_VIEW_STREET; + // ~330 m north of the street: a flight would move the camera, and a + // press that ignored the armed point would open something else. + const cameraLat = Number((point.lat + 0.003).toFixed(6)); + const googleRequests = []; + const onRequest = (request) => { + if (STREET_VIEW_REQUEST.test(request.url())) + googleRequests.push(request.url()); + }; + page.on('request', onRequest); + try { + await bootLink( + page, + `${base}#v=2&lat=${cameraLat}&lon=${point.lon}&alt=600&heading=0&pitch=-60&roll=0&map=osm&sl=google,${point.lat},${point.lon}`, + ); + await page.waitForFunction( + (want) => { + const c = + window.__godsEyeView.viewer.camera.positionCartographic; + return Math.abs((c.latitude * 180) / Math.PI - want) < 0.0005; + }, + { timeout: 60_000 }, + cameraLat, + ); + const googleKey = await page.evaluate(() => + Boolean(window.__GOOGLE_MAPS_API_KEY__), + ); + if (!googleKey) { + // Without a key the action stops at the key, before any flight, + // map switch or source change, and the direct call says why. + const direct = await page.evaluate( + (at) => + window.__godsEyeView.voiceCommands.runner( + 'show_street_level', + { + latitude: at.lat, + longitude: at.lon, + provider: 'google', + fly: false, + autoOpen: false, + }, + ), + point, + ); + assert.equal(direct.ok, false); + assert.equal( + direct.stage, + 'key', + `${direct.stage} ${direct.error}`, + ); + const after = await page.evaluate(() => { + const m = + window.__godsEyeView.dataManager.layers.get( + 'street-level', + ).module; + const u = m.getUIState(); + return { + stack: window.__godsEyeView.mapStackController.getActiveId(), + google: m.getParams().google === true, + armed: u.street.armed, + open: u.street.open, + }; + }); + assert.deepEqual( + after, + { stack: 'osm', google: false, armed: null, open: false }, + 'a keyless Street View link changes nothing', + ); + const still = await cameraAt(page); + assert.ok( + Math.abs(still.lat - cameraLat) < 0.0005, + `the camera did not fly: ${still.lat}`, + ); + assert.deepEqual(googleRequests, [], 'no Street View request'); + return; + } + const photoreal = await page.evaluate(() => + window.__godsEyeView.mapStackController.isStackAvailable( + 'photoreal', + ), + ); + if (!photoreal) return skipped('no Google 3D'); + await uiUntil( + page, + (u) => + u.street.armed !== null && + u.providers.some((p) => p.id === 'google' && p.on), + null, + 90_000, + ); + const beforePress = googleRequests.length; + const waiting = await getUI(page); + assert.equal( + waiting.street.open, + false, + 'nothing open without a click', + ); + assert.equal(waiting.street.imageId, null); + assert.deepEqual( + waiting.street.armed.point, + { lat: point.lat, lon: point.lon }, + 'armed at the link point', + ); + assert.equal( + beforePress, + 0, + 'no Street View request before the press', + ); + await expandPanel(page); + await press(page, '#sl-nearest-btn'); + await uiUntil( + page, + (u) => (u.street.imageId && !u.street.loading) || u.street.error, + null, + 90_000, + ); + const { street } = await getUI(page); + assert.equal(street.error, null, `viewer error: ${street.error}`); + assert.equal(street.providerId, 'google'); + assert.ok( + googleRequests.length >= 1, + 'the press made the Street View request', + ); + const metres = Math.hypot( + (street.position.lat - point.lat) * 111_320, + (street.position.lon - point.lon) * + 111_320 * + Math.cos((point.lat * Math.PI) / 180), + ); + assert.ok( + metres <= 250, + `within 250 m of the link point: ${Math.round(metres)} m`, + ); + // Back to Mapillary: the keyless page restores the saved layer + // and expects its KEY REQUIRED. + await press(page, '#sl-provider-chips [data-chip-id="mapillary"]'); + await uiUntil(page, litAlone, 'mapillary'); + } finally { + page.off('request', onRequest); + } + }, + ); + await fixtureStep( // The fixture bundle carries a token, so this covers a keyless // server behind a keyed bundle; the keyless default is checked above. diff --git a/scripts/qa-stub-boot.mjs b/scripts/qa-stub-boot.mjs new file mode 100644 index 0000000000..a3a3292ac7 --- /dev/null +++ b/scripts/qa-stub-boot.mjs @@ -0,0 +1,427 @@ +#!/usr/bin/env node +/** + * Boot the whole application on the stub renderer with only the contract's + * required members (`dev/stub-app/main.js`), headless, and check that: + * + * - it starts, with no Cesium module requested at all (no script, no + * worker, no asset it would fetch; the one Cesium stylesheet the build's + * `vite-plugin-cesium` links into every page is reported, not failed); + * - the credits show in the application's own line, and its list opens + * with the data credits; + * - each data layer named below turns on, and off, without a page error or + * a console error (a feed's failed response is reported as the feed's, + * not failed: without network access or keys a feed answers with an + * error, and the layer must take that without one of its own; the dev + * server's client's own errors are reported as the tooling's); + * - with `--strict`, each of them draws on the stub: items in its draw sets, + * imagery added through the globe port, or a field (`draw.field`). + * + * The page is the application's own (`index.html`), served with the stub + * entry in place of `src/main.js`. Without `--url` it starts a Vite dev + * server of this checkout on `--port` (default 5290) and stops it after. + * Live feeds answer through the dev server's providers, so without network + * access or keys a layer turns on with nothing to draw: the run says so, + * and only `--strict` fails it. + * + * `--all-capabilities` gives the stub every capability instead, to see what + * the layers draw where a renderer has them all. + * + * npm run qa:stub-boot [-- --url http://127.0.0.1:5280] [--strict] + * [--settle-ms 20000] [--json path] [--all-capabilities] + */ +import { writeFileSync } from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import puppeteer from 'puppeteer'; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); + +/** The data layers the stub must run, by catalog id. */ +export const STUB_BOOT_LAYERS = Object.freeze([ + 'flights', + 'military', + 'transit', + 'traffic', + 'cctv', + 'ais-live-vessels', + 'weather-radar', + 'weather-satellite', + 'wind', + 'satellites', + 'local-firms', + 'wildlife-sightings', + 'shipwrecks', + 'news', +]); + +/** A request that is Cesium: the package, its pre-bundle, or its assets. */ +export const isCesiumRequest = (url) => + /(?:^|[/._-])cesium(?:[/._-]|$)/i.test(new URL(url).pathname); + +/** The stylesheet `vite-plugin-cesium` links into every page it serves. */ +const isPluginStylesheet = (url, type) => + type === 'stylesheet' && + new URL(url).pathname === '/cesium/Widgets/widgets.css'; + +/** + * A browser's line for a feed's response that failed: one of the dev + * server's providers (`/api/`) or another origin's. The application's own + * modules and assets failing are the page's. + */ +const isFailedResponse = (text, at, base) => { + if (!/^Failed to load resource:/.test(text)) return false; + try { + const url = new URL(at); + return ( + url.origin !== new URL(base).origin || url.pathname.startsWith('/api/') + ); + } catch { + return false; + } +}; + +/** + * An error the dev server's own client logs (its socket to the server, which + * a headless browser can refuse): the tooling's, not the application's. + */ +const isDevClient = (at) => { + try { + return new URL(at).pathname === '/@vite/client'; + } catch { + return false; + } +}; + +function parseArgs(argv) { + const args = { strict: false, port: 5290, settleMs: 20_000 }; + for (let i = 0; i < argv.length; i++) { + const arg = argv[i]; + if (arg === '--strict') args.strict = true; + else if (arg === '--url') args.url = argv[++i]; + else if (arg === '--port') args.port = Number(argv[++i]); + else if (arg === '--settle-ms') args.settleMs = Number(argv[++i]); + else if (arg === '--json') args.json = argv[++i]; + else if (arg === '--all-capabilities') args.allCapabilities = true; + else throw new Error(`Unknown argument: ${arg}`); + } + return args; +} + +async function startViteServer(port) { + const { createServer } = await import('vite'); + const server = await createServer({ + root: ROOT, + configFile: path.join(ROOT, 'vite.config.js'), + // No hot reload: the page is loaded once and nothing edits it. + server: { port, strictPort: true, host: '127.0.0.1', hmr: false }, + logLevel: 'warn', + }); + await server.listen(); + return server; +} + +/** + * In the page: what the stub renderer draws now, its draw sets with how many + * items each holds and the globe port's imagery layers, and how many calls + * it has had on each port member. + */ +function readDrawn() { + const renderer = window.__stubBoot?.renderers?.[0]; + if (!renderer) return null; + const testing = renderer.testing; + const calls = {}; + for (const call of testing.calls) { + const key = `${call.port}.${call.member}`; + calls[key] = (calls[key] ?? 0) + 1; + } + return { + sets: Object.fromEntries( + testing.sets().map((id) => [id, testing.setRecord(id)?.items?.size ?? 0]), + ), + imagery: renderer.globe.imagery.list().length, + calls, + }; +} + +async function main() { + const args = parseArgs(process.argv.slice(2)); + const server = args.url ? null : await startViteServer(args.port); + try { + await run(args); + } finally { + await server?.close(); + } +} + +async function run(args) { + const base = (args.url ?? `http://127.0.0.1:${args.port}`).replace(/\/$/, ''); + const browser = await puppeteer.launch({ + headless: true, + executablePath: + process.env.PUPPETEER_EXECUTABLE_PATH || + (await puppeteer.executablePath()), + defaultViewport: { width: 1280, height: 800 }, + protocolTimeout: 300_000, + args: ['--no-sandbox'], + }); + /** Every error the page reports, in order: `page`, `console` or `response`. */ + const errors = []; + const cesiumRequests = []; + const cesiumStylesheets = []; + const report = { url: base, layers: {}, ok: false }; + try { + const page = await browser.newPage(); + page.on('console', (message) => { + if (message.type() !== 'error') return; + const text = message.text(); + const at = message.location()?.url ?? null; + errors.push({ + kind: isFailedResponse(text, at, base) + ? 'response' + : isDevClient(at) + ? 'tooling' + : 'console', + text, + at, + }); + }); + page.on('pageerror', (error) => + errors.push({ kind: 'page', text: String(error?.stack || error) }), + ); + await page.setRequestInterception(true); + page.on('request', async (request) => { + const url = request.url(); + if (url.startsWith(base) && isCesiumRequest(url)) + (isPluginStylesheet(url, request.resourceType()) + ? cesiumStylesheets + : cesiumRequests + ).push(url); + // The application's page, with the stub entry in place of its own. + if (request.isNavigationRequest() && url.startsWith(base)) { + const response = await fetch(url); + const html = (await response.text()).replace( + 'src="/src/main.js"', + 'src="/dev/stub-app/main.js"', + ); + if (!html.includes('/dev/stub-app/main.js')) + throw new Error('The page has no /src/main.js entry to replace'); + await request.respond({ + status: response.status, + contentType: 'text/html', + body: html, + }); + return; + } + await request.continue(); + }); + await page.goto( + `${base}/${args.allCapabilities ? '?capabilities=all' : ''}`, + { waitUntil: 'load', timeout: 180_000 }, + ); + await page.waitForFunction(() => window.__stubBoot, { timeout: 180_000 }); + const started = await page.evaluate(() => window.__stubBoot.started); + report.started = started; + if (!started.ok) throw new Error(`Startup failed: ${started.error}`); + await page.waitForFunction(() => window.__godsEyeView?.dataManager, { + timeout: 60_000, + }); + report.renderer = await page.evaluate(() => { + const renderer = window.__stubBoot.renderers[0]; + return { + id: renderer.id, + capabilities: [...renderer.capabilities], + canvasInPage: document.contains(renderer.canvas), + }; + }); + report.startupErrors = errors.slice(); + // The credits show in the application's own line, with no Cesium: the + // line is on screen and its list opens with the data credits in it. + report.credits = await page.evaluate(async () => { + const line = document.getElementById('gev-credits'); + const expand = line?.querySelector('.gev-credits-expand'); + const panel = document.getElementById('gev-credits-panel'); + const box = line?.getBoundingClientRect(); + const visible = + Boolean(box && box.width > 0 && box.height > 0) && + getComputedStyle(line).visibility !== 'hidden'; + expand?.click(); + await new Promise((resolve) => requestAnimationFrame(resolve)); + const listed = + panel?.hidden === false ? panel.querySelectorAll('li').length : 0; + expand?.click(); + return { visible, line: line?.textContent ?? null, listed }; + }); + console.log( + `credits: ${report.credits.visible ? 'shown' : 'NOT shown'}; line "${report.credits.line}"; ${report.credits.listed} listed`, + ); + const known = await page.evaluate(() => + window.__godsEyeView.dataManager.getAll().map((layer) => layer.id), + ); + report.missingLayers = STUB_BOOT_LAYERS.filter((id) => !known.includes(id)); + for (const id of STUB_BOOT_LAYERS) { + if (!known.includes(id)) continue; + const errorsBefore = errors.length; + const before = await page.evaluate(readDrawn); + const enabled = await page.evaluate( + (layerId) => + window.__godsEyeView.dataManager + .setEnabled(layerId, true, { origin: 'user' }) + .then( + // It can answer false rather than throw: on is what it says. + (value) => ({ + ok: + value !== false && + window.__godsEyeView.dataManager.isEnabled(layerId), + value: value ?? null, + }), + (error) => ({ ok: false, error: String(error?.stack || error) }), + ), + id, + ); + // Feeds load on their own schedule; keep ticking until they draw. + const deadline = Date.now() + args.settleMs; + let drawn = { sets: {}, imagery: 0, calls: {}, fields: 0 }; + while (Date.now() < deadline) { + await new Promise((resolve) => setTimeout(resolve, 1_000)); + const now = await page.evaluate(readDrawn); + drawn = { + sets: Object.fromEntries( + Object.entries(now.sets).filter( + ([setId, items]) => items > 0 && before.sets[setId] !== items, + ), + ), + imagery: Math.max(0, now.imagery - before.imagery), + calls: Object.fromEntries( + Object.entries(now.calls) + .map(([key, n]) => [key, n - (before.calls[key] ?? 0)]) + .filter(([, n]) => n > 0), + ), + }; + drawn.fields = drawn.calls['draw.field'] ?? 0; + if (Object.keys(drawn.sets).length || drawn.imagery || drawn.fields) + break; + } + const stats = await page.evaluate((layerId) => { + const row = window.__godsEyeView.dataManager + .getAll() + .find((layer) => layer.id === layerId); + return { + enabled: row?.enabled ?? null, + count: row?.stats?.count ?? null, + error: row?.stats?.error ?? null, + source: row?.stats?.source ?? null, + }; + }, id); + const disabled = await page.evaluate( + (layerId) => + window.__godsEyeView.dataManager + .setEnabled(layerId, false, { origin: 'user' }) + .then( + (value) => ({ + ok: + value !== false && + !window.__godsEyeView.dataManager.isEnabled(layerId), + }), + (error) => ({ ok: false, error: String(error?.stack || error) }), + ), + id, + ); + const layerErrors = errors.slice(errorsBefore); + report.layers[id] = { + enabled, + disabled, + stats, + drawn, + errors: layerErrors.filter( + (error) => error.kind === 'page' || error.kind === 'console', + ), + failedResponses: layerErrors + .filter((error) => error.kind === 'response') + .map((error) => error.at), + }; + const what = [ + ...Object.entries(drawn.sets).map(([setId, n]) => `${setId}=${n}`), + ...(drawn.imagery ? [`${drawn.imagery} imagery layer(s)`] : []), + ...(drawn.fields ? [`${drawn.fields} field(s)`] : []), + ]; + console.log( + `${id}: ${enabled.ok && disabled.ok ? 'ran' : 'FAILED'}; drew ${ + what.length ? what.join(', ') : 'nothing' + }${stats.error ? `; feed: ${stats.error}` : ''}${ + report.layers[id].failedResponses.length + ? `; ${report.layers[id].failedResponses.length} failed response(s)` + : '' + }`, + ); + } + report.ok = true; + } catch (error) { + // Reported with the rest below, so the report and errors are kept. + report.failure = String(error?.stack || error); + } finally { + report.cesiumRequests = cesiumRequests; + report.cesiumStylesheets = cesiumStylesheets; + report.errors = errors; + await browser.close(); + } + const pageErrors = errors.filter((error) => error.kind === 'page'); + const consoleErrors = errors.filter((error) => error.kind === 'console'); + const failedResponses = errors.filter((error) => error.kind === 'response'); + const toolingErrors = errors.filter((error) => error.kind === 'tooling'); + const problems = []; + if (report.failure) problems.push(`the run stopped: ${report.failure}`); + if (!report.started?.ok) problems.push('the application did not start'); + if (!report.renderer?.canvasInPage) + problems.push("the stub's canvas is not in the page"); + if ( + report.started?.ok && + (!report.credits?.visible || !report.credits.listed) + ) + problems.push('the credits line is not shown, or its list is empty'); + if (cesiumRequests.length) + problems.push(`Cesium was requested: ${cesiumRequests.join(', ')}`); + if (pageErrors.length) problems.push(`${pageErrors.length} page error(s)`); + if (consoleErrors.length) + problems.push(`${consoleErrors.length} console error(s)`); + if (report.missingLayers?.length) + problems.push(`layers not in the catalog: ${report.missingLayers}`); + for (const [id, layer] of Object.entries(report.layers)) { + if (!layer.enabled.ok || !layer.disabled.ok) + problems.push(`${id} failed to turn on or off`); + if ( + args.strict && + !Object.keys(layer.drawn.sets).length && + !layer.drawn.imagery && + !layer.drawn.fields + ) + problems.push(`${id} drew nothing`); + } + report.problems = problems; + if (args.json) writeFileSync(args.json, JSON.stringify(report, null, 2)); + for (const error of [...pageErrors, ...consoleErrors]) + console.error(`${error.kind} error: ${error.text} (${error.at ?? '?'})`); + if (cesiumStylesheets.length) + console.log( + `note: the build's Cesium plugin linked ${cesiumStylesheets.join(', ')}`, + ); + if (toolingErrors.length) + console.log( + `note: the dev server's client logged ${toolingErrors.length} error(s): ${[ + ...new Set(toolingErrors.map((error) => error.text)), + ].join(' | ')}`, + ); + if (failedResponses.length) + console.log( + `note: ${failedResponses.length} feed response(s) failed (keys or network)`, + ); + if (problems.length) { + console.error(`FAIL: ${problems.join('; ')}`); + process.exitCode = 1; + } else console.log('ok: the application runs on the stub renderer'); +} + +if (import.meta.url === `file://${process.argv[1]}`) + main().catch((error) => { + console.error(error); + process.exitCode = 1; + }); diff --git a/scripts/qa-terrain-429.mjs b/scripts/qa-terrain-429.mjs index 8164e34b5b..8db513d2c2 100644 --- a/scripts/qa-terrain-429.mjs +++ b/scripts/qa-terrain-429.mjs @@ -8,7 +8,7 @@ * answers HTTP 429 for most of them. This harness drives that burst, counts the * throttled responses, keeps the first 429's headers as evidence, and then * checks whether every throttled tile eventually loaded — the contract the - * client-side retry in `src/maps/terrain.js` provides. + * client-side retry in `src/render/cesium/mapTerrain.js` provides. * * Run against a keyless dev server (no Google or ion credentials): * env -u GOOGLE_MAPS_API_KEY -u CESIUM_ION_TOKEN npm run dev -- --port 4180 diff --git a/scripts/qa-traffic-baseline.mjs b/scripts/qa-traffic-baseline.mjs index 7059bf4381..57b1bea875 100644 --- a/scripts/qa-traffic-baseline.mjs +++ b/scripts/qa-traffic-baseline.mjs @@ -8,13 +8,16 @@ * 1. exact-viewport revisit (traffic module's full-road cache), * 2. adjacent 0.4–2 km pan (new exact bbox with heavy spatial overlap), * 3. cold city (no traffic-module entry for that city), - * 4. degraded upstream (synthetic delay on `/api/overpass` only). + * 4. degraded upstream (synthetic delay on the road requests: OpenFreeMap's + * host, which only traffic reads in this capture, or the Overpass proxy). * - * The proxy's actual `X-Overpass-Cache` result is printed for every network - * pass, so HIT/DISK/MISS/STALE/INFLIGHT is evidence rather than inference. - * The degraded leg delays request release in Puppeteer; it exercises the same - * fetch-start→response boundary without adding a failure switch to the - * application or proxy. Pass `--degraded-delay-ms 0` to skip that leg. + * Keyless roads come from OpenFreeMap vector tiles (`tiles.openfreemap.org`); + * a build that still reads them through the Overpass proxy has its + * `X-Overpass-Cache` result printed for every network pass, so + * HIT/DISK/MISS/STALE/INFLIGHT is evidence rather than inference ("—" for + * tiles). The degraded leg delays the road requests' release in Puppeteer; + * it exercises the same fetch-start→response boundary without adding a + * failure switch to the application or proxy. Pass `--degraded-delay-ms 0` to skip that leg. * TomTom status is intercepted as keyless so no live-flow key is required and * the capture isolates the OSM road-to-visible-dot chain. * @@ -93,9 +96,42 @@ function debugUrl(rawUrl) { return url.toString(); } -/** Position the camera and explicitly raise the boundaries the layer observes. */ +/** + * Let the camera report a move the way a user's does: traffic hears the + * camera port's `changed` at its own 5% threshold (layers/traffic/policy.js + * CAMERA_CHANGED_THRESHOLD), which the port measures on every scene tick + * (the first measurement after a listener subscribes only records its + * baseline pose). Waiting for two drawn frames after the move is the sync + * point that the port has measured it. Cesium's own moveEnd (500 ms after + * stillness) is left to Cesium, as in the app; traffic re-checks the view + * on it. Installed in the page as `window.__qaRenderAfterMove`; throws when + * the frames do not draw within 5 s. + */ +function installRenderAfterMove() { + window.__qaRenderAfterMove = (gev) => new Promise((resolve, reject) => { + const scene = gev.viewer.scene; + let frames = 0; + let remove = null; + const timer = setTimeout(() => { + remove(); + reject(new Error(`the camera move rendered ${frames} frame(s) in 5 s`)); + }, 5000); + remove = scene.postRender.addEventListener(() => { + if (++frames >= 2) { + clearTimeout(timer); + remove(); + resolve(frames); + return; + } + scene.requestRender(); + }); + scene.requestRender(); + }); +} + +/** Position the camera and render, so the layer hears the move as it would a user's. */ async function moveCamera(page, view) { - return page.evaluate((v) => { + return page.evaluate(async (v) => { const gev = window.__godsEyeView; const module = gev.dataManager.layers.get('traffic').module; const beforeLastUpdate = module.getStats().lastUpdate; @@ -115,12 +151,7 @@ async function moveCamera(page, view) { roll: 0, }, }); - // setView normally propagates through Cesium's render loop. Raising these - // explicitly makes the capture boundary deterministic across GPU speeds. - // Pairing still flows through camera.changed's schedule-time anchor; the - // synthetic moveEnd is emitted only as the same diagnostic used naturally. - gev.viewer.camera.changed.raiseEvent(); - gev.viewer.camera.moveEnd.raiseEvent(); + await window.__qaRenderAfterMove(gev); return { beforeLastUpdate, boundaryTime }; }, view); } @@ -159,14 +190,29 @@ function readTrafficMeasures(page, boundaryTime) { })), boundaryTime); } +/** + * Road requests the page sent, counted by the request interceptor: `sent` is + * every road request that reached the network, `delayed` those it held for + * the degraded leg. `requestRoads()` can be answered from decoded tiles + * already in memory, so a `fetch-to-response` measure alone does not prove + * the network was used. + */ +const roadRequests = { sent: 0, delayed: 0 }; + /** Drive one measured state and return its raw User Timing measures. */ async function captureState(page, name, view, setDelay) { setDelay(name === 'degraded-upstream' ? DEGRADED_DELAY_MS : 0); + const before = { ...roadRequests }; const { beforeLastUpdate, boundaryTime } = await moveCamera(page, view); await waitForTrafficCapture(page, beforeLastUpdate, boundaryTime); const measures = await readTrafficMeasures(page, boundaryTime); setDelay(0); - return { name, measures }; + return { + name, + measures, + sent: roadRequests.sent - before.sent, + delayed: roadRequests.delayed - before.delayed, + }; } /** Format a duration without hiding zero-duration measurements. */ @@ -318,13 +364,14 @@ async function main() { const page = await browser.newPage(); await page.setViewport({ width: 1440, height: 900 }); await page.evaluateOnNewDocument(() => localStorage.clear()); + await page.evaluateOnNewDocument(installRenderAfterMove); page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()); }); page.on('pageerror', (error) => consoleErrors.push(error.message)); - // Force keyless traffic and optionally hold Overpass requests to model a - // degraded proxy/upstream. No server key or proxy debug endpoint is needed. + // Force keyless traffic and optionally hold the road requests to model a + // degraded upstream. No server key or proxy debug endpoint is needed. await page.setRequestInterception(true); page.on('request', async (request) => { if (request.url().includes('/api/tomtom/status')) { @@ -335,7 +382,11 @@ async function main() { }); return; } - if (activeProxyDelayMs > 0 && request.url().includes('/api/overpass')) { + const roadRequest = request.url().includes('/api/overpass') + || new URL(request.url()).hostname === 'tiles.openfreemap.org'; + if (roadRequest) roadRequests.sent += 1; + if (activeProxyDelayMs > 0 && roadRequest) { + roadRequests.delayed += 1; await sleep(activeProxyDelayMs); } try { await request.continue(); } catch { /* page closed or already handled */ } @@ -363,8 +414,9 @@ async function main() { orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, }); await gev.dataManager.setEnabled('traffic', true); - gev.viewer.camera.changed.raiseEvent(); - gev.viewer.camera.moveEnd.raiseEvent(); + // Also records the baseline pose traffic's new `changed` listener + // measures the first measured move against. + await window.__qaRenderAfterMove(gev); }, VIEWS.austin); await sleep(500); @@ -386,7 +438,7 @@ async function main() { // Clear the last-bounds gate without clearing the module's road cache, then // revisit the byte-identical camera pose for a true client-cache hit. - await page.evaluate((view) => { + await page.evaluate(async (view) => { const gev = window.__godsEyeView; const ellipsoid = gev.viewer.scene.globe.ellipsoid; const radians = Math.PI / 180; @@ -398,8 +450,7 @@ async function main() { }), orientation: { heading: 0, pitch: -Math.PI / 2, roll: 0 }, }); - gev.viewer.camera.changed.raiseEvent(); - gev.viewer.camera.moveEnd.raiseEvent(); + await window.__qaRenderAfterMove(gev); }, VIEWS.austin); await sleep(500); @@ -428,7 +479,7 @@ async function main() { } for (const capture of captures.slice(1)) { if (!capture.measures.some((entry) => entry.detail?.segment === 'fetch-to-response')) { - throw new Error(`${capture.name} did not issue an Overpass request`); + throw new Error(`${capture.name} did not issue a road request`); } } if (DEGRADED_DELAY_MS > 0) { @@ -438,20 +489,35 @@ async function main() { && entry.duration >= DEGRADED_DELAY_MS * 0.9 )); if (!delayed) throw new Error('degraded-upstream leg did not observe the synthetic delay'); + // The delay has to come from held road requests, not from processing + // that happened to run long. + if (!degraded.delayed) throw new Error('degraded-upstream leg sent no road request to hold'); } + // A city the client has never seen has no tiles in memory: it must reach + // the network. The other legs may legitimately be answered from tiles + // already decoded, so their counts are reported, not asserted. + const cold = captures.find((capture) => capture.name === 'cold city (client)'); + if (!cold?.sent) throw new Error('cold city leg sent no road request to the network'); const rows = captures.flatMap(rowsForCapture); if (!rows.length) throw new Error('no measured traffic renders were captured'); console.log('\nCausal segments (one row per visible major/full pass)'); console.table(rows); + console.log('\nRoad requests sent to the network per leg (held by the degraded leg)'); + console.table(captures.map((capture) => ({ + State: capture.name, + Sent: capture.sent, + Held: capture.delayed, + }))); console.log('\nNotes:'); console.log(' - Render→postRender is the first visible-frame boundary used by Phase 0.'); - console.log(' - Proxy cache is read from X-Overpass-Cache; “—” means the client cache avoided fetch.'); - console.log(' - response.json includes both body transfer and JSON decoding; the production path does not split them.'); - console.log(' - Last change→fetch is approximately the 320 ms FETCH_DEBOUNCE for the first fetch by construction.'); + console.log(' - Proxy cache is read from X-Overpass-Cache; “—” means the client cache avoided fetch, or the roads came from OpenFreeMap tiles.'); + console.log(' - Through the Overpass proxy, Fetch→response is the HTTP response and response.json is body transfer plus JSON decoding.'); + console.log(' - From OpenFreeMap tiles, Fetch→response spans the tile requests, body reads, decoding and composition, and response.json only hands back the built object; a held leg can stack the delay over tiles fetched in turn.'); + console.log(' - Last change→fetch is the 320 ms FETCH_DEBOUNCE for the first fetch by construction, plus timer and main-thread latency (larger under SwiftShader).'); console.log(' - Full-pass Last change→fetch also includes the intentionally sequential major pass.'); - console.log(' - Cesium moveEnd is a diagnostic raised ~500 ms after stillness, typically after fetch starts; fetch never waits for it.'); - console.log(' - Synthetic events bypass camera percentageChanged/inertia but use the same camera.changed schedule-time anchor as natural captures.'); + console.log(' - Cesium moveEnd is raised ~500 ms after stillness, typically after fetch starts; fetch never waits for it, and traffic only re-checks the view on it.'); + console.log(' - Moves are setView plus rendered frames: the camera port measures traffic\'s own 5% changed threshold as for a user move (inertia is bypassed).'); console.log(' - The keyless capture zeroes Flow race and Heat lines work; live-keyed numbers will differ.'); console.log(' - Measurement caveat: timings include instrumentation overhead (observer effect) and browser clock-floor quantization.'); console.log(' - Per-road clock observations inside road-parse-total/waypoint-materialization slightly overstate production work.'); diff --git a/scripts/qa-traffic-motion.mjs b/scripts/qa-traffic-motion.mjs index af73c8d1c2..b9c0f52d5a 100644 --- a/scripts/qa-traffic-motion.mjs +++ b/scripts/qa-traffic-motion.mjs @@ -158,9 +158,13 @@ try { (window.__motion.holdStart === null ? '' : ` | camera stopped +${((now - window.__motion.holdStart) / 1000).toFixed(1)}s`); + // A layer dot is its draw item (`pos`, hidden only when `show` is + // false); a collection's point is Cesium's. const visit = (id, roadId, point) => { - if (!point.show) return; - const s = scene.cartesianToCanvasCoordinates(point.position); + if (point.show === false) return; + const s = scene.cartesianToCanvasCoordinates( + point.pos ?? point.position, + ); if (s && s.x >= 0 && s.y >= 0 && s.x <= 1280 && s.y <= 800) points.set(id, { x: s.x, y: s.y, roadId }); }; @@ -168,7 +172,7 @@ try { offRoad = 0; if (!baseline && layer.visitMotionDots) { layer.visitMotionDots((id, roadId, point, road) => { - if (point.show) { + if (point.show !== false) { const p = road?.roadProperties; const allowed = road?.directFlow ? [ @@ -195,7 +199,7 @@ try { p?.brunnel !== 'tunnel'; if (!allowed) offRoad++; } - if (point.show) n++; + if (point.show !== false) n++; visit(id, roadId, point); }); } else { diff --git a/scripts/qa-traffic-oblique.mjs b/scripts/qa-traffic-oblique.mjs index 6ea1c953d5..a365bcd446 100644 --- a/scripts/qa-traffic-oblique.mjs +++ b/scripts/qa-traffic-oblique.mjs @@ -83,9 +83,10 @@ try { lower = 0; dataManager.layers .get('traffic') - .module.visitMotionDots((id, key, p) => { - if (!p.show) return; - const s = viewer.scene.cartesianToCanvasCoordinates(p.position); + .module.visitMotionDots((id, key, dot) => { + // A dot is its draw item: `pos`, hidden only when `show` is false. + if (dot.show === false) return; + const s = viewer.scene.cartesianToCanvasCoordinates(dot.pos); if (s && s.x >= 240 && s.x <= 1040 && s.y >= 0 && s.y <= 800) { if (s.y < 400) upper++; else lower++; @@ -197,8 +198,10 @@ try { const camera = viewer.camera.positionWC; dataManager.layers .get('traffic') - .module.visitMotionDots((id, key, p) => { - if (!p.show) return; + .module.visitMotionDots((id, key, dot) => { + // A dot is its draw item: `pos`, hidden only when `show` is false. + if (dot.show === false) return; + const p = { position: dot.pos }; const q = viewer.scene.cartesianToCanvasCoordinates(p.position); if (q && q.x >= 240 && q.x <= 1040 && q.y >= 0 && q.y <= 800) { if (q.y < 400) upper++; diff --git a/scripts/qa-trail-freeze.mjs b/scripts/qa-trail-freeze.mjs new file mode 100644 index 0000000000..77d7cbf6ce --- /dev/null +++ b/scripts/qa-trail-freeze.mjs @@ -0,0 +1,241 @@ +#!/usr/bin/env node +/** + * Trail freeze gate: freezing a trail chunk never shows a blank frame. + * + * A tracked aircraft's trail is cut into chunks; every chunk but the newest + * is frozen into static geometry, which Cesium builds asynchronously. Until + * that geometry is in the scene, the chunk keeps being drawn dynamically. + * + * This gate drives the real app and a real Cesium scene: it draws a trail of + * CHUNK_POINTS points (all dynamic), then adds one point so the first chunk + * freezes, and on every rendered frame after that it checks two things: + * 1. every frozen chunk is either still drawn by a dynamic polyline or its + * static geometry is in the scene (DataSourceDisplay reports DONE); + * 2. the number of trail-coloured pixels never drops below 90% of the + * count measured just before the freeze. + * It also checks that clearing the trail releases every chunk entity. + * + * The camera is held still while the gate runs. + * + * Needs a running dev server: + * node scripts/qa-trail-freeze.mjs [--url http://localhost:4173] + */ +import puppeteer from 'puppeteer'; +import { chromeExecutablePath } from './qa-chrome.mjs'; + +const urlFlag = process.argv.indexOf('--url'); +const APP_URL = + urlFlag > 0 ? process.argv[urlFlag + 1] : 'http://localhost:4173'; + +const browser = await puppeteer.launch({ + headless: 'new', + protocolTimeout: 300_000, + executablePath: chromeExecutablePath(), + args: [ + '--no-sandbox', + '--disable-setuid-sandbox', + '--use-gl=angle', + '--use-angle=swiftshader', + '--disable-dev-shm-usage', + '--disable-background-timer-throttling', + '--disable-renderer-backgrounding', + '--window-size=960,640', + ], +}); + +let failed = false; +const report = (name, ok, detail) => { + if (!ok) failed = true; + console.log( + ` [${ok ? 'PASS' : 'FAIL'}] ${name}${detail ? ` — ${detail}` : ''}`, + ); +}; + +try { + const page = await browser.newPage(); + await page.setViewport({ width: 960, height: 640 }); + await page.goto(APP_URL, { waitUntil: 'domcontentloaded', timeout: 120_000 }); + await page.waitForFunction( + () => + window.__godsEyeView?.viewer && + document.getElementById('loading-screen')?.classList.contains('hidden'), + { timeout: 180_000 }, + ); + + const result = await page.evaluate(async () => { + // The exact Cesium module the renderer uses, so classes are shared. + const source = await (await fetch('/src/data/trailRenderer.js')).text(); + const cesiumUrl = source.match(/from\s+["']([^"']*cesium[^"']*)["']/)[1]; + const Cesium = await import(cesiumUrl); + const { createTrail, CHUNK_POINTS } = + await import('/src/data/trailRenderer.js'); + const viewer = window.__godsEyeView.viewer; + const scene = viewer.scene; + const nextFrame = () => + new Promise((resolve) => { + const remove = scene.postRender.addEventListener(() => { + remove(); + resolve(); + }); + scene.requestRender(); + }); + + // A line across the middle of the current view, in mid-air in front of + // the camera, so terrain and buildings never hide it. + viewer.camera.cancelFlight?.(); + const camera = viewer.camera; + const ahead = Cesium.Cartesian3.add( + camera.positionWC, + Cesium.Cartesian3.multiplyByScalar( + camera.directionWC, + 3_000, + new Cesium.Cartesian3(), + ), + new Cesium.Cartesian3(), + ); + const points = Array.from({ length: CHUNK_POINTS + 1 }, (_, i) => + Cesium.Cartesian3.add( + ahead, + Cesium.Cartesian3.multiplyByScalar( + camera.rightWC, + -1_200 + (2_400 * i) / CHUNK_POINTS, + new Cesium.Cartesian3(), + ), + new Cesium.Cartesian3(), + ), + ); + const added = []; + const removed = []; + const add = viewer.entities.add.bind(viewer.entities); + const remove = viewer.entities.remove.bind(viewer.entities); + viewer.entities.add = (definition) => { + const entity = add(definition); + if (String(entity.id).startsWith('gev-trail:')) added.push(entity); + return entity; + }; + viewer.entities.remove = (entity) => { + if (String(entity?.id).startsWith('gev-trail:')) removed.push(entity); + return remove(entity); + }; + + const gl = scene.context._gl; + const width = gl.drawingBufferWidth; + const height = gl.drawingBufferHeight; + const pixels = new Uint8Array(width * height * 4); + // Magenta trail: count pixels that are clearly magenta. + const countTrailPixels = () => { + gl.bindFramebuffer(gl.FRAMEBUFFER, null); + gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels); + let count = 0; + for (let p = 0; p < pixels.length; p += 4) { + const r = pixels[p]; + const g = pixels[p + 1]; + const b = pixels[p + 2]; + if (r > 150 && b > 150 && g < 110) count++; + } + return count; + }; + + const trail = createTrail(viewer, { color: '#ff00ff', width: 8 }); + trail.setPositions(points.slice(0, CHUNK_POINTS)); + for (let i = 0; i < 20; i++) await nextFrame(); + const before = trail._chunksForTest(); + gl.bindFramebuffer(gl.FRAMEBUFFER, null); + gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels); + let lit = 0; + for (let p = 0; p < pixels.length; p += 4) + if (pixels[p] || pixels[p + 1] || pixels[p + 2]) lit++; + const cam = viewer.camera.positionCartographic; + const diagnostics = { + lit, + size: [width, height], + camera: [ + Cesium.Math.toDegrees(cam.longitude), + Cesium.Math.toDegrees(cam.latitude), + cam.height, + ], + preserveDrawingBuffer: gl.getContextAttributes().preserveDrawingBuffer, + }; + let baseline = 0; + for (let i = 0; i < 5; i++) { + await nextFrame(); + baseline = Math.max(baseline, countTrailPixels()); + } + + trail.setPositions(points); + const frames = []; + const sphere = new Cesium.BoundingSphere(); + let resolvedAt = null; + for (let i = 0; i < 400; i++) { + await nextFrame(); + const state = trail._chunksForTest(); + const covered = state.frozen.every( + (chunk) => + chunk.standIn || + viewer.dataSourceDisplay.getBoundingSphere( + chunk.entity, + false, + sphere, + ) === Cesium.BoundingSphereState.DONE, + ); + frames.push({ covered, pixels: countTrailPixels() }); + if (resolvedAt == null && state.frozen.every((c) => !c.standIn)) + resolvedAt = i; + if (resolvedAt != null && i > resolvedAt + 30) break; + } + + trail.clear(); + for (let i = 0; i < 3; i++) await nextFrame(); + const frozenAfterClear = trail._chunksForTest().frozen.length; + trail.destroy(); + const leaked = added.filter((entity) => !removed.includes(entity)).length; + viewer.entities.add = add; + viewer.entities.remove = remove; + return { + chunkPoints: CHUNK_POINTS, + diagnostics, + frozenBefore: before.frozen.length, + baseline, + frames, + resolvedAt, + frozenAfterClear, + entities: added.length, + leaked, + }; + }); + + if (process.env.GEV_TEST_VERBOSE) + console.log(JSON.stringify(result.diagnostics)); + const minPixels = Math.min(...result.frames.map((frame) => frame.pixels)); + report( + 'the trail draws before the freeze', + result.baseline > 200 && result.frozenBefore === 0, + `baseline=${result.baseline} trail pixels, frozen chunks=${result.frozenBefore}`, + ); + report( + 'the frozen chunk reaches the scene as static geometry', + result.resolvedAt != null, + `stand-in dropped after ${result.resolvedAt} frames`, + ); + report( + 'every frame after the freeze draws the frozen chunk (dynamic copy or static geometry)', + result.frames.every((frame) => frame.covered), + `${result.frames.length} frames checked`, + ); + report( + 'no blank frame: trail pixels never drop below 90% of the pre-freeze count', + minPixels >= 0.9 * result.baseline, + `min=${minPixels} baseline=${result.baseline}`, + ); + report( + 'clearing and destroying release every trail entity', + result.frozenAfterClear === 0 && result.leaked === 0, + `entities created=${result.entities} leaked=${result.leaked}`, + ); +} catch (error) { + report('gate ran', false, error.message); +} finally { + await browser.close(); +} +console.log(failed ? 'RESULT: FAIL' : 'RESULT: PASS'); +process.exit(failed ? 1 : 0); diff --git a/scripts/qa-transit-browser.mjs b/scripts/qa-transit-browser.mjs index 23925c7439..7b9f1ee449 100644 --- a/scripts/qa-transit-browser.mjs +++ b/scripts/qa-transit-browser.mjs @@ -177,6 +177,19 @@ export async function sampleTransitPixels(page, palette) { ]; const width = canvas.clientWidth; const height = canvas.clientHeight; + // The billboards the draw port drew for the layer's two sets, by + // vehicle key, with the collection drawing each. + const drawn = new Map(); + const setIds = layer._transitSetIdsForTest(); + for (let i = 0; i < scene.primitives.length; i++) { + const host = scene.primitives.get(i); + if (!setIds.includes(host?.drawSetId)) continue; + for (let j = 0; j < host.length; j++) { + const billboard = host.get(j); + if (typeof billboard?.id?.id === 'string') + drawn.set(billboard.id.id, { billboard, host }); + } + } const sprites = []; const footprints = []; const intersects = (a, b) => @@ -256,20 +269,26 @@ export async function sampleTransitPixels(page, palette) { }; for (const entry of state._vehicles.values()) { if (!entry.marker || entry.marker.show === false) continue; - const p = entry.marker.position; + const row = drawn.get(entry.key); + if (!row || row.billboard.show === false) { + skipped.push({ key: entry.key, reason: 'billboard not drawn' }); + continue; + } + const billboard = row.billboard; + const p = billboard.position; const clip = mul(proj, mul(view, [p.x, p.y, p.z, 1])); if (!(clip[3] > 0)) continue; - const screen = entry.marker.computeScreenSpacePosition?.(scene) || { + const screen = billboard.computeScreenSpacePosition?.(scene) || { x: ((clip[0] / clip[3]) * 0.5 + 0.5) * width, y: (1 - ((clip[1] / clip[3]) * 0.5 + 0.5)) * height, }; - const rect = entry.marker.constructor.getScreenSpaceBoundingBox?.( - entry.marker, + const rect = billboard.constructor.getScreenSpaceBoundingBox?.( + billboard, screen, ) || { x: screen.x - 16, y: screen.y - 16, width: 32, height: 32 }; const { x, y } = screenPoint(screen.x, screen.y); - const c = Math.abs(Math.cos(entry.marker.rotation || 0)), - sn = Math.abs(Math.sin(entry.marker.rotation || 0)); + const c = Math.abs(Math.cos(billboard.rotation || 0)), + sn = Math.abs(Math.sin(billboard.rotation || 0)); const w = rect.width * c + rect.height * sn, h = rect.height * c + rect.width * sn; const footprint = { x: x - w / 2, y: y - h / 2, w, h }; @@ -282,10 +301,7 @@ export async function sampleTransitPixels(page, palette) { rect.y + rect.height > height ) reason = 'billboard rectangle outside frame'; - if ( - entry.marker.color?.alpha < 0.95 || - entry.markerCollection?.show === false - ) + if (billboard.color?.alpha < 0.95 || row.host.show === false) reason = 'billboard not opaque/collection hidden'; const raster = rasters.get(entry.marker.image); if (!raster) reason = 'billboard alpha unavailable'; @@ -351,12 +367,12 @@ export async function sampleTransitPixels(page, palette) { bracketX: entry.detectContact?._candidateScreenX ?? screen.x, bracketY: entry.detectContact?._candidateScreenY ?? screen.y, raster, - rotation: entry.marker.rotation || 0, - halfW: Number.isFinite(entry.marker.width) - ? Math.ceil(entry.marker.width / 2) + 2 + rotation: billboard.rotation || 0, + halfW: Number.isFinite(billboard.width) + ? Math.ceil(billboard.width / 2) + 2 : 11, - halfH: Number.isFinite(entry.marker.height) - ? Math.ceil(entry.marker.height / 2) + 2 + halfH: Number.isFinite(billboard.height) + ? Math.ceil(billboard.height / 2) + 2 : 7, }); } @@ -658,12 +674,23 @@ export function readTransitFleetStyle({ key, resetSelection = false } = {}) { const entry = key ? state._vehicles.get(key) : [...state._vehicles.values()].find((e) => e.marker?.show); - return entry + // The billboard the draw port drew for it, in either of the layer's sets. + const scene = window.__godsEyeView.viewer.scene; + const setIds = layer._transitSetIdsForTest(); + let billboard = null; + for (let i = 0; entry && !billboard && i < scene.primitives.length; i++) { + const host = scene.primitives.get(i); + if (!setIds.includes(host?.drawSetId)) continue; + for (let j = 0; j < host.length; j++) + if (host.get(j)?.id?.id === entry.key) billboard = host.get(j); + } + // An undrawn marker has no style to compare: no answer. + return entry && billboard ? { key: entry.key, selected: state._selectedKey === entry.key, - color: entry.marker.color.toCssColorString(), - width: entry.marker.width, + color: billboard.color.toCssColorString(), + width: billboard.width, image: entry.marker.image, } : null; diff --git a/scripts/qa-transit-recovery.mjs b/scripts/qa-transit-recovery.mjs index a54e812399..6d45e684b7 100644 --- a/scripts/qa-transit-recovery.mjs +++ b/scripts/qa-transit-recovery.mjs @@ -182,7 +182,8 @@ try { }); parts.rendering.sampleIdle(entry); parts.rendering.schedulePlayback(entry); - const V = entry.marker.position.constructor; + // Marker positions are plain records; the camera's eye is a Cartesian3. + const V = scene.camera.positionWC.constructor; const points = entry.trailSegments .filter((s) => s.toT <= entry.sample.displayT) .flatMap((s) => s.positions); diff --git a/scripts/qa-transit-scenes.mjs b/scripts/qa-transit-scenes.mjs index f325cb9f73..d75d235fdc 100644 --- a/scripts/qa-transit-scenes.mjs +++ b/scripts/qa-transit-scenes.mjs @@ -146,11 +146,7 @@ export async function runFleetBudgets({ // The retained delta is conservative: it includes concurrent page growth. const retained = await cdp.send('Runtime.getHeapUsage'); // Timing/upload acceptance runs without the allocation profiler attached. - const trace = await page.evaluate(() => - window.__godsEyeView.dataManager.layers - .get('transit') - .module._measureTransitFramesForTest(8000), - ); + const trace = await page.evaluate(measureTransitFrames, 8000); await page.evaluate(() => window.__godsEyeView.dataManager.layers .get('transit') @@ -166,11 +162,7 @@ export async function runFleetBudgets({ page, `${count} budget visibility before allocation trace`, ); - const allocationTrace = await page.evaluate(() => - window.__godsEyeView.dataManager.layers - .get('transit') - .module._measureTransitFramesForTest(6000), - ); + const allocationTrace = await page.evaluate(measureTransitFrames, 6000); const { profile } = await cdp.send('HeapProfiler.stopSampling'); const allocations = allocationTotals(profile); const retainedBytes = retained.usedSize - before.usedSize; @@ -361,13 +353,23 @@ export async function runBostonMatrix({ const modes = await page.evaluate(() => { const layer = window.__godsEyeView.dataManager.layers.get('transit').module; + // The billboards the draw port drew for the markers, by key. + const scene = window.__godsEyeView.viewer.scene; + const setIds = layer._transitSetIdsForTest(); + const drawn = new Map(); + for (let i = 0; i < scene.primitives.length; i++) { + const host = scene.primitives.get(i); + if (!setIds.includes(host?.drawSetId)) continue; + for (let j = 0; j < host.length; j++) + drawn.set(host.get(j)?.id?.id, host.get(j)); + } return [...layer._transitStateForTest()._vehicles.values()].map( (e) => ({ key: e.key, route: e.record.routeId, image: e.marker.image, - width: e.marker.width, - color: e.marker.color.toCssHexString(), + width: drawn.get(e.key)?.width ?? null, + color: drawn.get(e.key)?.color.toCssHexString() ?? null, }), ); }); @@ -418,15 +420,29 @@ export async function runBostonMatrix({ window.__godsEyeView.dataManager.layers.get('transit').module; layer._transitPartsForTest().selection.clearSelection(); const e = layer._transitStateForTest()._vehicles.get(key); + // The billboard the draw port drew for it: the last under its key, + // as the fleet sample above reads it (the fleet-models set draws + // one under the same key first). + const scene = window.__godsEyeView.viewer.scene; + const setIds = layer._transitSetIdsForTest(); + let drawn = null; + for (let i = 0; i < scene.primitives.length; i++) { + const host = scene.primitives.get(i); + if (!setIds.includes(host?.drawSetId)) continue; + for (let j = 0; j < host.length; j++) + if (host.get(j)?.id?.id === key) drawn = host.get(j); + } return { + drawn: Boolean(drawn), image: e.marker.image, - width: e.marker.width, - color: e.marker.color.toCssHexString(), + width: drawn?.width ?? null, + color: drawn?.color.toCssHexString() ?? null, }; }, target.key); check( `Boston ${background.name}/${look.name}/${target.route}: deselect restores fleet styling`, - restored.image === target.image && + restored.drawn && + restored.image === target.image && restored.width === target.width && restored.color === target.color, ); @@ -727,6 +743,15 @@ export async function runTrailVisibility({ bodyUploadMax = 0, frames = 0; const headCpu = []; + // The Cesium primitives drawing one of the trail's draw-port sets: one, + // or while a rebuild builds, the retiring one and its replacement. + const hostsOf = (set) => { + const hosts = []; + for (let i = 0; set && i < scene.primitives.length; i++) + if (scene.primitives.get(i).drawSetId === set.id) + hosts.push(scene.primitives.get(i)); + return hosts; + }; const wrap = (primitive, kind) => { if (!primitive || wrapped.has(primitive)) return; const update = primitive.update; @@ -767,8 +792,8 @@ export async function runTrailVisibility({ const pre = scene.preRender.addEventListener(() => { headBytes = bodyBytes = 0; const trail = parts.trails.diagnostics(); - wrap(trail?.body, 'body'); - wrap(trail?.headPrimitive || trail?.head?._polylineCollection, 'head'); + for (const host of hostsOf(trail?.body)) wrap(host, 'body'); + for (const host of hostsOf(trail?.headLines)) wrap(host, 'head'); }); const post = scene.postRender.addEventListener(() => { frames++; @@ -807,6 +832,26 @@ export async function runTrailVisibility({ const trail = parts.trails.diagnostics(); if (!entry || !trail) return { ...setup, present: 0, reason: 'selection disappeared' }; + // The Cesium primitives drawing one of the trail's draw-port sets: one, + // or while a rebuild builds, the retiring one and its replacement. + const hostsOf = (set) => { + const hosts = []; + for (let i = 0; set && i < scene.primitives.length; i++) + if (scene.primitives.get(i).drawSetId === set.id) + hosts.push(scene.primitives.get(i)); + return hosts; + }; + // Each part of a set's primitive, for readiness and height exclusion. + const partsOf = (set) => { + const out = []; + for (const host of hostsOf(set)) + for (let i = 0; i < host.length; i++) out.push(host.get(i)); + return out; + }; + // One host (no rebuild under way) whose parts have all built. + const drawnReady = (set) => + hostsOf(set).length === 1 && + partsOf(set).every((part) => part.ready !== false); const { setRate } = await import('/src/data/contactPlayback.js'); setRate(entry.track, 0, { wallNowMs: Date.now(), @@ -819,8 +864,8 @@ export async function runTrailVisibility({ 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); + drawnReady(trail.body) && + (!trail.headLines?.show || drawnReady(trail.headLines)); // Require sustained readiness after freezing playback, before projecting // onto the refined surface. Repeated captures still check pixel stability. const tilesReady = await new Promise((resolve) => { @@ -855,7 +900,18 @@ export async function runTrailVisibility({ if (points.length < 2) return { ...setup, present: 0, reason: 'no completed path' }; const C = scene.camera.positionCartographic.constructor; - const V = entry.marker.position.constructor; + // Marker positions are plain records; the camera's eye is a Cartesian3. + const V = scene.camera.positionWC.constructor; + // The billboard the draw port drew for the marker, seen through. + const setIds = layer._transitSetIdsForTest(); + const markerBillboards = []; + for (let i = 0; i < scene.primitives.length; i++) { + const host = scene.primitives.get(i); + if (!setIds.includes(host?.drawSetId)) continue; + for (let j = 0; j < host.length; j++) + if (host.get(j)?.id?.id === entry.key) + markerBillboards.push(host.get(j)); + } const lengths = [0]; for (let i = 1; i < points.length; i++) lengths.push(lengths.at(-1) + V.distance(points[i - 1], points[i])); @@ -875,10 +931,11 @@ export async function runTrailVisibility({ new V(), ); const cart = C.fromCartesian(p); - const height = scene.sampleHeight( - cart, - [entry.marker, trail.body, trail.headPrimitive].filter(Boolean), - ); + const height = scene.sampleHeight(cart, [ + ...markerBillboards, + ...partsOf(trail.body), + ...partsOf(trail.headLines), + ]); if (Number.isFinite(height)) cart.height = height; const surface = C.toCartesian(cart); const q = mul( @@ -943,13 +1000,12 @@ export async function runTrailVisibility({ }); const bodyShow = trail.body?.show, headShow = trail.head?.show, - headPrimitiveShow = trail.headPrimitive?.show, + headLinesShow = trail.headLines?.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.headLines) trail.headLines.show = showTrail && headLinesShow; if (trail.head) trail.head.show = showTrail && headShow; if (trail.backing) trail.backing.show = showTrail && backingShow; }; @@ -966,13 +1022,13 @@ export async function runTrailVisibility({ const current = parts.trails.diagnostics(); captureReady &&= ready() && - current?.body === trail.body && - current?.headPrimitive === trail.headPrimitive; + current?.rebuilds === trail.rebuilds && + current?.headRebuilds === trail.headRebuilds; } } finally { removeVisibility(); if (trail.body) trail.body.show = bodyShow; - if (trail.headPrimitive) trail.headPrimitive.show = headPrimitiveShow; + if (trail.headLines) trail.headLines.show = headLinesShow; if (trail.head) trail.head.show = headShow; if (trail.backing) trail.backing.show = backingShow; await frame(); @@ -994,7 +1050,7 @@ export async function runTrailVisibility({ tilesReady: captureReady, elapsedDisplayMs: entry.sample.displayT - setup.startDisplayT, movedMetres: Math.abs(entry.sample.lat - setup.startLat) * 111320, - body: trail.body?.constructor.name, + body: hostsOf(trail.body)[0]?.constructor.name, headStrategy: trail.headStrategy || 'PolylineCollection', headRebuilds: trail.headRebuilds ?? null, }; @@ -1048,3 +1104,24 @@ export async function runTrailVisibility({ .selection.clearSelection(), ); } + +/** + * The transit frame probe over the bytes the renderer uploads for the + * layer's marker sets (the Cesium renderer's upload probe), in the page. + * @param {number} durationMs + */ +async function measureTransitFrames(durationMs) { + const { countDrawSetUploads } = + await import('/src/render/cesium/uploadProbe.js'); + const app = window.__godsEyeView; + const layer = app.dataManager.layers.get('transit').module; + const uploads = countDrawSetUploads( + app.viewer, + layer._transitSetIdsForTest(), + ); + try { + return await layer._measureTransitFramesForTest(durationMs, uploads); + } finally { + uploads.stop(); + } +} diff --git a/scripts/qa-transit.mjs b/scripts/qa-transit.mjs index 49a25fd18a..c73a0cafc6 100644 --- a/scripts/qa-transit.mjs +++ b/scripts/qa-transit.mjs @@ -98,7 +98,7 @@ const renderingSource = await readFile( ); const frameSource = renderingSource .split('function onPreRender()')[1] - .split('const occluder')[0]; + .split('const candidatePosition')[0]; check( 'frame pass does not scan the fleet or copy the moving set', !/_vehicles\.values|\[\.\.\.state\._moving\]/.test(frameSource), @@ -801,7 +801,7 @@ try { ); check( `${preset.name}: the icon raster cache stays bounded`, - styling.iconCacheSize <= 6 * 2 * 3, + styling.iconCacheSize <= 6 * 2 * 3 * 2, `${styling.iconCacheSize} rasters`, ); } @@ -815,25 +815,38 @@ try { const layer = window.__godsEyeView.dataManager.layers.get('transit').module; const state = layer._transitStateForTest(); - const entry = state._vehicles.get(key); + const scene = window.__godsEyeView.viewer.scene; + // The billboard the draw port drew for it, and the set drawing it. + const setIds = layer._transitSetIdsForTest(); + let billboard = null, + setId = null; + for (let i = 0; !billboard && i < scene.primitives.length; i++) { + const host = scene.primitives.get(i); + if (!setIds.includes(host?.drawSetId)) continue; + for (let j = 0; j < host.length; j++) + if (host.get(j)?.id?.id === key) { + billboard = host.get(j); + setId = host.drawSetId; + } + } + const set = layer._transitPartsForTest().rendering.setNameOf(setId); return { selected: state._selectedKey === key, - color: entry?.marker.color.toCssColorString(), - width: entry?.marker.width, + color: billboard?.color.toCssColorString(), + width: billboard?.width, pickOwner: (() => { - const p = window.__godsEyeView.viewer.scene.pick( - entry.marker.computeScreenSpacePosition( - window.__godsEyeView.viewer.scene, - ), - ); + const p = billboard + ? scene.pick(billboard.computeScreenSpacePosition(scene)) + : null; return { - id: typeof p?.id === 'string' ? p.id : null, - primitiveId: - typeof p?.primitive?.id === 'string' ? p.primitive.id : null, + id: typeof p?.id?.id === 'string' ? p.id.id : null, + set: typeof p?.id?.set === 'string' ? p.id.set : null, collection: - entry.markerCollection === state._animatedMarkers + set === 'moving' ? 'animated' - : 'stationary', + : set === 'still' + ? 'stationary' + : null, }; })(), }; @@ -1596,7 +1609,8 @@ try { key: entry.key, x, y, - pickKey: picked?.id ?? picked?.primitive?.id ?? null, + // A draw-port pick carries {set, id, meta}; the vehicle is its id. + pickKey: picked?.id?.id ?? picked?.id ?? picked?.primitive?.id ?? null, }; }); let anchor = null; @@ -1849,19 +1863,33 @@ try { await page.$eval(row, (element) => element.scrollIntoView({ block: 'center' }), ); + // The marker sets drawn while on, to look for after disable. + const markerSets = await page.evaluate(() => + window.__godsEyeView.dataManager.layers + .get('transit') + .module._transitSetIdsForTest(), + ); await page.click(`${row} .data-toggle-btn`); await page.waitForFunction( () => !window.__godsEyeView.dataManager.isEnabled('transit'), { timeout: 20_000 }, ); const afterDisable = transitRequests.length; - const teardown = await page.evaluate(() => { + const teardown = await page.evaluate((setIds) => { const layer = window.__godsEyeView.dataManager.layers.get('transit').module; const state = layer._transitStateForTest(); return { vehicles: state._vehicles.size, - primitives: - (state._markers?.length || 0) + (state._animatedMarkers?.length || 0), + // Billboards still drawn in the sets drawn while on. + primitives: (() => { + const scene = window.__godsEyeView.viewer.scene; + let count = 0; + for (let i = 0; i < scene.primitives.length; i++) { + const host = scene.primitives.get(i); + if (setIds.includes(host?.drawSetId)) count += host.length || 0; + } + return count; + })(), visible: state._visible.size, moving: state._moving.size, detect: state._detectCache, @@ -1873,12 +1901,12 @@ try { ], trailPending: layer._transitPartsForTest().trails.requestDiagnostics() .pending, - shown: state._markers ? state._markers.show : null, + shown: state._markersShown ?? null, inFlight: state._inFlight.size, activeFeeds: state._activeFeeds.size, holds: window.__godsEyeView.getRenderGovernorDiagnostics().holds, }; - }); + }, markerSets); check( 'disable leaves no vehicles and no point primitives', teardown.vehicles === 0 && diff --git a/scripts/qa-visual-effects.mjs b/scripts/qa-visual-effects.mjs index f3b9ab8bd3..3c96e66547 100644 --- a/scripts/qa-visual-effects.mjs +++ b/scripts/qa-visual-effects.mjs @@ -169,7 +169,7 @@ try { result.bloom.intensityPct === 98 && snapshot.bloom.intensity === 98 && manager._visualEffects.bloomIntensity === 98 && - manager._bloomStage.enabled + window.__godsEyeView.viewer.scene.postProcessStages.bloom.enabled ); }), ); @@ -183,7 +183,11 @@ try { result.sharpen.intensityPct === 61 && manager.getVisualState().sharpen.intensity === 61 && manager._visualEffects.sharpenIntensity === 0.61 && - Math.abs(manager._sharpenStage.uniforms.amount - 1.32) < 1e-9 + Math.abs( + window.__godsEyeView.viewer.scene.postProcessStages.getStageByName( + 'effects_sharpen', + ).uniforms.amount - 1.32, + ) < 1e-9 ); }), ); @@ -199,9 +203,10 @@ try { const manager = window.__godsEyeView.styleManager; const effects = manager._visualEffects; manager.setStyle('retro'); - const owned = [...Object.values(effects.stages), effects.sharpenStage]; - const collection = manager.viewer.scene.postProcessStages; - const previousBloom = effects.previousBloom; + const collection = window.__godsEyeView.viewer.scene.postProcessStages; + const owned = Object.keys(effects.stages).map((name) => + collection.getStageByName(`effects_style_${name}`), + ); const pending = manager.dispose(); const stoppedBeforeAwait = effects.stopped && @@ -210,12 +215,15 @@ try { await pending; return { stoppedBeforeAwait, - removed: owned.every((stage) => !collection.contains(stage)), - restored: - effects.bloomStage.enabled === previousBloom.enabled && - Object.entries(previousBloom.uniforms).every( - ([name, value]) => effects.bloomStage.uniforms[name] === value, + removed: + owned.every(Boolean) && + Object.keys(effects.stages).every( + (name) => !collection.getStageByName(`effects_style_${name}`), ), + // The renderer gives the scene's bloom back when it goes. + restored: + !collection.bloom.enabled && + !collection.getStageByName('effects_sharpen')?.enabled, }; }); check( @@ -223,7 +231,7 @@ try { teardown.stoppedBeforeAwait, ); check( - 'UI teardown removes owned stages and restores borrowed bloom', + 'UI teardown removes its styles and turns bloom and sharpen off', teardown.removed && teardown.restored, ); check( diff --git a/scripts/qa-visual-input.mjs b/scripts/qa-visual-input.mjs index 3c096acdc1..914476aeb3 100644 --- a/scripts/qa-visual-input.mjs +++ b/scripts/qa-visual-input.mjs @@ -150,7 +150,9 @@ try { manager._bloomSlider.focus(); return { value: Number(manager._bloomSlider.value), - contrast: manager._bloomStage.uniforms.contrast, + contrast: + window.__godsEyeView.viewer.scene.postProcessStages.bloom.uniforms + .contrast, }; }); await page.keyboard.press('ArrowRight'); @@ -160,7 +162,8 @@ try { const manager = window.__godsEyeView.styleManager; return ( Number(manager._bloomSlider.value) > before.value && - manager._bloomStage.uniforms.contrast < before.contrast + window.__godsEyeView.viewer.scene.postProcessStages.bloom.uniforms + .contrast < before.contrast ); }, displayBefore), ); @@ -267,13 +270,16 @@ try { const manager = window.__godsEyeView.styleManager; manager._displayBindings._detachDisplayControls(); const before = manager.bloomEnabled; - const contrast = manager._bloomStage.uniforms.contrast; + const contrast = + window.__godsEyeView.viewer.scene.postProcessStages.bloom.uniforms + .contrast; manager._bloomBtn.click(); manager._bloomSlider.value = '15'; manager._bloomSlider.dispatchEvent(new Event('input', { bubbles: true })); return ( manager.bloomEnabled === before && - manager._bloomStage.uniforms.contrast === contrast + window.__godsEyeView.viewer.scene.postProcessStages.bloom.uniforms + .contrast === contrast ); }), ); diff --git a/scripts/qa-voice-routing.mjs b/scripts/qa-voice-routing.mjs index 0b0a5213a4..e3e5b33c4c 100644 --- a/scripts/qa-voice-routing.mjs +++ b/scripts/qa-voice-routing.mjs @@ -904,6 +904,7 @@ const SLOW_TOOLS = new Set([ 'annotate_map', 'fly_to_location', 'select_nearest_aircraft', + 'show_street_level', 'analyst_query', 'fly_route', 'frame_overhead', diff --git a/scripts/qa-zoom-out-guard.mjs b/scripts/qa-zoom-out-guard.mjs index 770a4148d8..5faf70b9f0 100644 --- a/scripts/qa-zoom-out-guard.mjs +++ b/scripts/qa-zoom-out-guard.mjs @@ -36,7 +36,8 @@ try { ); const renderer = await page.evaluate(async () => { const C = await import('/node_modules/cesium/Build/Cesium/index.js'); - const { maxPitchForHeight } = await import('/src/app/zoomOutGuard.js'); + const { maxPitchForHeight } = + await import('/src/render/cesium/zoomOutGuard.js'); const { readCameraTargetFrame } = await import('/src/ui/cameraOrientationControls.js'); const viewer = window.__godsEyeView.viewer; @@ -86,7 +87,7 @@ try { }; viewer.camera.setView = (options) => { // Cesium itself also calls setView while processing touch movement. - if (new Error().stack.includes('/src/app/zoomOutGuard.js')) + if (new Error().stack.includes('/src/render/cesium/zoomOutGuard.js')) qa.guardWrites++; return original(options); }; diff --git a/scripts/record-camera-goldens.mjs b/scripts/record-camera-goldens.mjs new file mode 100644 index 0000000000..17f4131bc7 --- /dev/null +++ b/scripts/record-camera-goldens.mjs @@ -0,0 +1,28 @@ +#!/usr/bin/env node +// Writes the reference camera traces the conformance suite compares a +// renderer against: src/render/conformance/goldens/camera.json. Run it after +// a Cesium upgrade or a change to the camera scripts, and review the diff. +// +// node scripts/record-camera-goldens.mjs [--check] +// +// With --check it writes nothing and exits 1 when the file is out of date. +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { recordCameraGoldens } from '../src/render/cesium/cameraGoldens.js'; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); +const OUT = path.join(ROOT, 'src/render/conformance/goldens/camera.json'); + +const text = `${JSON.stringify(await recordCameraGoldens(), null, 2)}\n`; +if (process.argv.includes('--check')) { + const current = fs.existsSync(OUT) ? fs.readFileSync(OUT, 'utf8') : ''; + if (current !== text) { + console.error(`${path.relative(ROOT, OUT)} is out of date`); + process.exit(1); + } +} else { + fs.mkdirSync(path.dirname(OUT), { recursive: true }); + fs.writeFileSync(OUT, text); + console.log(`wrote ${path.relative(ROOT, OUT)}`); +} diff --git a/scripts/track-regression.mjs b/scripts/track-regression.mjs index d2e04609b3..fb745e48d6 100644 --- a/scripts/track-regression.mjs +++ b/scripts/track-regression.mjs @@ -33,7 +33,8 @@ * moves the camera — it stays in the follow band). * 3. NO CROSS-LAYER — tracking military then commercial (and vice versa) * ORPHAN clears the FIRST layer (its getTrackedInfo()===null), - * via the per-layer viewer.trackedEntityChanged listener. + * via each layer's follow-changed listener (the follow + * service, data/followed.js: onFollowChanged). * 4. INIT CLEAN — app loads, all 12 layers present, no console errors, * [Detection] Initialized + [TrackedReadout] Initialized. * @@ -42,9 +43,10 @@ * and a real mouse click on the tracked plane is a * NO-OP (no deselect, no camera spike). * M3. AGE-OUT RELEASE — when the tracked plane's fixes stop arriving - * (3 missed polls via the shim), tracking clears and - * the camera is RELEASED IN PLACE: viewer.trackedEntity - * undefined, NO jump (owner decision 2026-07-02 — + * it stays tracked (STALE, then SIGNAL LOST) until + * 10 min after its newest fix; then tracking clears + * and the camera is RELEASED IN PLACE: the camera + * follows nothing (data/followed.js), NO jump (owner decision 2026-07-02 — * the old ~80 km overview flyTo is gone). * * And the landing-ghost polish (2026-07-02): a LOW+SLOW (landed) plane that @@ -73,11 +75,16 @@ * the TRACKED grounded plane gets the standalone tracked model too (the * owner's "tracked SWA143 at 0 kts showed a 2D billboard" case). * - * And arrival-rotation freshness (2026-07-03 ground-polish): camera.moveEnd - * forces a full rotation pass on the next frame (fly-to settles the - * pose-signature gate can eat), and a billboard flipping INTO view while the - * camera idles re-aims the same tick instead of wearing a stale nose for up - * to ROTATION_REFRESH_MS. Both layers. + * And arrival-rotation freshness (2026-07-03 ground-polish): the nose is right + * on the first settled frame after a camera move and on the first frame a + * hidden contact is shown again. Both layers. (The CPU rotation passes that + * once guaranteed it are gone: the icon sets turn every icon along its drawn + * course on the GPU each frame, so the group reads the drawn rows.) + * + * The probes read what the app draws through its own seams: what the camera + * follows through the follow service (data/followed.js), icons from the draw + * port's icon sets as the renderer holds them, models by their `{set, id}` + * pick ids. * * Run: npm run test:track (assumes dev server already up on :4173) * node scripts/track-regression.mjs @@ -96,9 +103,15 @@ import fs from 'node:fs'; import puppeteer from 'puppeteer'; import { respondToPlanespotters } from './qa-photo-stub.mjs'; import { arrivalAngleViolated, arrivalRotationPassed } from '../src/tooling/trackArrivalObservation.mjs'; -import { classifyAircraft, CLASS_SCALE_3D, CLASS_MODEL_REAL } from '../src/data/aircraftClass.js'; +import { aircraftModelSpec } from '../src/data/fleetModels.js'; import { ensureGeoidReady, geoidHeight } from '../src/data/geoid.js'; +/** The fleet model set the aircraft layers draw from, read from disk. */ +const FLEET_SET = Object.freeze({ + catalog: JSON.parse(fs.readFileSync(new URL('../public/models/fleet/catalog.json', import.meta.url), 'utf8')), + types: JSON.parse(fs.readFileSync(new URL('../public/models/fleet/types.json', import.meta.url), 'utf8')), +}); + // --------------------------------------------------------------------------- // Args // --------------------------------------------------------------------------- @@ -265,6 +278,98 @@ async function main() { try { const page = await browser.newPage(); await page.evaluateOnNewDocument((base) => { window.__gevQaSourceBase = base; }, SOURCE_BASE); + // What the camera follows, read through the app's follow service + // (data/followed.js) rather than Cesium's `trackedEntity`: the follow + // camera runs through the renderer's camera port, whose Cesium adapter + // tracks a hidden helper entity, and the tracked aircraft is no longer an + // entity at all. `__qaFollowed()` is null until the app is up (and the + // module loaded), so every wait that reads it simply keeps polling. + await page.evaluateOnNewDocument(() => { + window.__qaFollowed = () => { + // A probe that cannot read the follow service must not read as + // "follows nothing". + if (window.__qaFollowedError) throw new Error(`followed.js: ${window.__qaFollowedError}`); + return window.__qaFollowedOf?.(window.__godsEyeView?.viewer) ?? null; + }; + const timer = setInterval(() => { + if (!window.__godsEyeView?.viewer) return; + clearInterval(timer); + import(`${window.__gevQaSourceBase || '/src'}/data/followed.js`) + .then((module) => { window.__qaFollowedOf = module.followedOf; }) + .catch((error) => { window.__qaFollowedError = String(error?.message || error); }); + }, 100); + // A contact's id from a drawn model's pick id: the draw port's models + // carry `{set, id}`; older builds stamped the bare id. + window.__qaModelIcao = (model) => { + const id = model?.id; + if (id && typeof id === 'object') return id.id == null ? null : String(id.id); + return id == null ? null : String(id); + }; + // A contact's FLEET icon as the renderer draws it, shaped like the + // billboard the probes below were written against: `show`, `scale`, + // `color` (the row's colour with its alpha column applied; focus and + // limb recession, which the shader also folds in, are not), + // `disableDepthTestDistance` and `position` (where the last frame drew + // it). The draw port's icon sets draw on the GPU (one IconSetPrimitive + // per set, rows keyed by item id; before the draw port, one a layer + // drew itself); a set off the GPU draws Cesium + // billboards whose pick id is `{set, id}`. The tracked icon's own set + // (`-tracked-icon:`) is left out: the fleet icon is what these + // probes always read. + window.__qaFindIcon = (wanted) => { + const scene = window.__godsEyeView?.viewer?.scene; + if (!scene) return null; + const trackedSet = (setId) => typeof setId === 'string' && setId.includes('-tracked-icon:'); + let found = null; + const walk = (coll) => { + const n = coll.length; + for (let i = 0; i < n; i++) { + let p; + try { p = coll.get(i); } catch { continue; } + if (!p) continue; + if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } + if (p.set && typeof p.set.row === 'function' && typeof p.set.has === 'function') { + if (!p.set.has(wanted)) continue; + // A primitive a layer drew itself (before the draw port) names + // no set. + const setId = typeof p._pickObject === 'function' + ? p._pickObject(wanted, p.set, p)?.id?.set ?? null + : null; + if (trackedSet(setId)) continue; + const set = p.set; + const row = set.row(wanted); + const color = set.color(row); + color.alpha *= set.alpha(row); + // (A set without the column draws over depth by default.) + const depth = typeof set.depthTestDistance === 'function' + ? set.depthTestDistance(row) + : Number.POSITIVE_INFINITY; + found = { + id: wanted, + setId, + show: set.shown(row), + scale: set.scale(row), + color, + disableDepthTestDistance: depth >= 1e30 ? Number.POSITIVE_INFINITY : depth, + position: set.position(row, p._tau), + // Degrees clockwise from north: the course the last frame + // turned the icon along (its rotation is derived from it on + // the GPU each frame). + course: set.course(row, p._tau), + // Whether the row turns along that course at all (ICON_ROTATES + // in data/iconSet.js); one that does not is drawn upright. + rotates: (set.flags(row) & 2) !== 0, + }; + } else if (p.image !== undefined && p.alignedAxis !== undefined) { + const id = p.id && typeof p.id === 'object' ? p.id : { id: p.id }; + if (id.id === wanted && !trackedSet(id.set)) found = p; + } + } + }; + walk(scene.primitives); + return found; + }; + }); await page.setViewport({ width: 1280, height: 800 }); await page.setRequestInterception(true); page.on('request', (request) => { @@ -362,7 +467,12 @@ async function main() { 'Synthetica', // 2 origin_country Math.floor(Date.now() / 1000), // 3 time_position Math.floor(Date.now() / 1000), // 4 last_contact - f.lon, // 5 longitude + // A plane given `moveFromMs` flies east at its reported speed + // (the trail-head check needs a moving icon); others hold still. + Number.isFinite(f.moveFromMs) + ? f.lon + (f.vel * (Date.now() - f.moveFromMs)) / 1000 + / (111320 * Math.cos((f.lat * Math.PI) / 180)) + : f.lon, // 5 longitude f.lat, // 6 latitude f.alt, // 7 baro_altitude (m) f.onGround === true, // 8 on_ground (ground-traffic phase flips this live) @@ -541,13 +651,13 @@ async function main() { // Independent GLB capability control. Product model absence cannot prove // that the browser backend is incapable: that is the condition this - // harness is meant to catch. Load the already-approved airplane asset + // harness is meant to catch. Load one of the shipped fleet models // directly through Cesium, outside the Flights/Military model pipelines, // then remove the control before exercising product behavior. const glbControlStarted = await evalPage(async () => { window.__qaGlbControl = null; window.__qaGlbControlError = null; - const asset = await fetch('/models/airplane.glb'); + const asset = await fetch('/models/fleet/aircraft/a320.glb'); const assetBytes = asset.ok ? (await asset.arrayBuffer()).byteLength : 0; if (!asset.ok || assetBytes === 0) { throw new Error(`GLB control asset unavailable: HTTP ${asset.status}`); @@ -558,7 +668,7 @@ async function main() { Cesium.Cartesian3.fromDegrees(-97.7431, 30.2672, 9000), ); void Cesium.Model.fromGltfAsync({ - url: '/models/airplane.glb', + url: '/models/fleet/aircraft/a320.glb', modelMatrix, scale: 1, }).then((model) => { @@ -713,7 +823,7 @@ async function main() { const tracked = manager?.layers?.get('flights')?.module?.getTrackedInfo?.(); return manager?.isEnabled?.('flights') && tracked?.icao24 === 'aaa001' - && window.__godsEyeView.viewer.trackedEntity?.gevTrackedId === 'flights:aaa001'; + && window.__qaFollowed()?.key === 'flights:aaa001'; }, { timeout: 30000, polling: 100 }, ); @@ -724,7 +834,7 @@ async function main() { flightsEnabled: manager.isEnabled('flights'), trackedId: flights.getTrackedInfo()?.icao24 || null, durableId: flights.getParams()?.selectedFlightsTrackingId || null, - viewerTrackedId: window.__godsEyeView.viewer.trackedEntity?.gevTrackedId || null, + viewerTrackedId: window.__qaFollowed()?.key || null, }; }); record( @@ -754,7 +864,7 @@ async function main() { const tracked = manager?.layers?.get('flights')?.module?.getTrackedInfo?.(); return manager?.isEnabled?.('flights') && tracked?.icao24 === 'aaa001' - && window.__godsEyeView.viewer.trackedEntity?.gevTrackedId === 'flights:aaa001'; + && window.__qaFollowed()?.key === 'flights:aaa001'; }, { timeout: 30000, polling: 100 }, ); @@ -765,7 +875,7 @@ async function main() { flightsEnabled: manager.isEnabled('flights'), trackedId: flights.getTrackedInfo()?.icao24 || null, durableId: flights.getParams()?.selectedFlightsTrackingId || null, - viewerTrackedId: window.__godsEyeView.viewer.trackedEntity?.gevTrackedId || null, + viewerTrackedId: window.__qaFollowed()?.key || null, }; }); record( @@ -827,7 +937,7 @@ async function main() { const latchedShare = await evalPage(() => ({ tracked: window.__godsEyeView.dataManager.layers .get('flights').module.getTrackedInfo()?.icao24 || null, - viewerTrackedId: window.__godsEyeView.viewer.trackedEntity?.gevTrackedId || null, + viewerTrackedId: window.__qaFollowed()?.key || null, })); record( 'share-v2: the pending subject latches on when it arrives on a later poll', @@ -1341,11 +1451,11 @@ async function main() { ); } - // NOTE: we do NOT manually reposition the camera. Tracking sets - // viewer.trackedEntity + a calibrated viewFrom, so the follow camera lands - // in the few-km band (altitude*1.1+2500, clamped 3–30 km) — far below the - // MODEL_ALT_CEIL_M = 800 km ceiling, so _modelRegimeActive() is true and the - // standalone tracked model renders. That's the exact path the invariants + // NOTE: we do NOT manually reposition the camera. Tracking follows the + // plane with a calibrated viewFrom, so the follow camera lands + // in the few-km band (altitude*1.1+2500, clamped 3–30 km) — below the + // MODEL_ALT_CEIL_M ceiling, so _modelRegimeActive() is true; the checks below + // zoom in to within the 3 km model range so the standalone tracked model renders. That's the exact path the invariants // protect, so we exercise it rather than a synthetic setView. // ============================================================ @@ -1387,12 +1497,12 @@ async function main() { // report the neighbor's id even though the correct tracked model is up. const trackedInfo = fl.getTrackedInfo(); const exactPickModel = trackedInfo - ? pool.find((model) => String(model.id) === trackedInfo.icao24) + ? pool.find((model) => window.__qaModelIcao(model) === trackedInfo.icao24) : null; if (exactPickModel) return exactPickModel; - const ent = window.__godsEyeView.viewer.trackedEntity; + const followed = window.__qaFollowed(); let tracked = null; - if (ent && typeof ent.gevDisplayPosition === 'function') tracked = ent.gevDisplayPosition(); + if (typeof followed?.displayPosition === 'function') tracked = followed.displayPosition(); if (!tracked) return pool[0]; let best = null, bestD = Infinity; for (const m of pool) { @@ -1408,16 +1518,34 @@ async function main() { // is "tracked model not up yet", not a match. return bestD < 1000 * 1000 ? best : null; }; + // Models draw only within 3 km of the camera, and the follow camera + // frames a cruising plane from farther out: zoom in on the followed + // plane until it is within `metres`. Returns the distance reached. + window.__qaFollowWithin = async function (metres) { + const v = window.__godsEyeView.viewer; + for (let i = 0; i < 20; i++) { + const followed = window.__qaFollowed(); + const t = typeof followed?.displayPosition === 'function' ? followed.displayPosition() : null; + if (!t) return null; + const c = v.camera.positionWC; + const d = Math.hypot(c.x - t.x, c.y - t.y, c.z - t.z); + if (d <= metres) return d; + v.camera.zoomIn(d - metres * 0.8); + await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))); + } + return null; + }; }); - // Track a synthetic commercial plane. Tracking sets viewer.trackedEntity + - // viewFrom, so the follow camera lands in the few-km band and the standalone - // 3D model renders (model regime active below the 800 km ceiling). + // Track a synthetic commercial plane, then zoom the follow camera to + // within 2 km of it: models draw only within 3 km, so the standalone 3D + // model renders there. const trackedIcao = SYNTH.flights[0].icao; await evalPage((icao) => { window.__godsEyeView.dataManager.layers.get('flights').module.trackById(icao); }, trackedIcao); - await sleep(1500); // let the follow camera settle + the GLB load kick off + await sleep(1500); // let the follow camera settle + await evalPage(() => window.__qaFollowWithin(2000)); // Wait until the tracked Cesium.Model primitive exists, is ready & shown. const modelUp = await page.waitForFunction((icao) => { @@ -1425,7 +1553,7 @@ async function main() { const ti = fl.getTrackedInfo(); if (!ti || ti.icao24 !== icao) return false; const found = window.__findTrackedModel ? window.__findTrackedModel() : null; - return !!(found && found.ready && found.show && String(found.id) === icao); + return !!(found && found.ready && found.show && window.__qaModelIcao(found) === icao); }, { timeout: 60000, polling: 250 }, trackedIcao).then(() => true).catch(() => false); record('3D: tracked commercial model becomes ready through the DISPLAY toggle', modelUp, modelUp ? `ready+shown id=${trackedIcao}` : 'tracked product model never became ready+shown'); @@ -1438,8 +1566,8 @@ async function main() { jitterResult = await sampleFrames(page, 30, (icao) => { const dm = window.__godsEyeView.dataManager; const fl = dm.layers.get('flights').module; - const ent = window.__godsEyeView.viewer.trackedEntity; - const disp = ent && typeof ent.gevDisplayPosition === 'function' ? ent.gevDisplayPosition() : null; + const followed = window.__qaFollowed(); + const disp = typeof followed?.displayPosition === 'function' ? followed.displayPosition() : null; const dets = fl.getDetectableObjects({ maxCount: 1000 }); const me = dets.find((d) => d.id === icao || d.id === (fl.getTrackedInfo() && fl.getTrackedInfo().callsign)); if (!disp || !me || !me.position) return null; @@ -1448,8 +1576,8 @@ async function main() { }, trackedIcao); console.log(' (3D model did not render under SwiftShader; testing the shared display-position contract directly)'); } else { - // Full check: independently transform airplane.glb's measured AABB centre - // through the actual 3D model matrix, then compare it with detection. + // Full check: independently transform the fleet model's visual centre + // (its origin) through the actual 3D model matrix, then compare it with detection. // glTF [x,y,z] → Cesium-local [x,-z,y]. The effective rendered // computedScale is separate from modelMatrix and includes any // minimumPixelSize enlargement, so include it just as the renderer does. @@ -1463,7 +1591,7 @@ async function main() { const scale = Number.isFinite(model.computedScale) ? model.computedScale : (Number.isFinite(model.scale) ? model.scale : 1); - // airplane.glb is now bounding-box centred with transforms applied. + // Fleet models are drawn about their origin, transforms applied. const x = 0 * scale; const y = 0 * scale; const z = 0 * scale; @@ -1498,6 +1626,110 @@ async function main() { `max=${maxDelta.toFixed(3)} m over ${samples.length} frames (tol ${JITTER_TOL_M} m, mode=${modelUp ? 'model-matrix' : 'display-contract'})`); } + // ============================================================ + // TRAIL HEAD ENDS AT THE DRAWN ICON, every rendered frame. + // The head's last vertex is where the tracked plane is drawn (the + // display position, or the model's tail anchor while the model is the + // visual). getTrackedInfo reports the dead-reckoned position without + // the brief post-report easing; its gap is logged, not asserted. + // ============================================================ + console.log('\nTrail head — ends at the drawn icon on every frame'); + // The fixture planes repeat one position, so the icon holds and draws no + // head. Fly the tracked one east for this check; the display runs 30 s + // behind, so give it time to reach the moving reports. + await evalPage((icao) => { + const f = window.__SYNTH.flights.find((p) => p.icao === icao); + f.moveFromMs = Date.now(); + }, trackedIcao); + await sleep(55_000); + const headSamples = await sampleFrames(page, 40, (icao) => { + const viewer = window.__godsEyeView.viewer; + const fl = window.__godsEyeView.dataManager.layers.get('flights').module; + const ent = viewer.trackedEntity; + const time = viewer.clock.currentTime; + const head = viewer.entities.values.find((e) => String(e.id).startsWith('gev-trail:fl-head-')); + const line = head?.polyline?.positions?.getValue(time); + const drawn = ent?.position?.getValue(time); + if (!line?.length || !drawn) return null; + const end = line[line.length - 1]; + const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z); + const ti = fl.getTrackedInfo(); + let infoGap = null; + if (ti && ti.icao24 === icao) { + // WGS84 lat/lon → ECEF on the ellipsoid; the angle at the centre to + // the drawn position, times the mean radius, is the ground gap. + const a = 6378137, e2 = 6.69437999014e-3; + const lat = (ti.latitude * Math.PI) / 180, lon = (ti.longitude * Math.PI) / 180; + const n = a / Math.sqrt(1 - e2 * Math.sin(lat) ** 2); + const p = { + x: n * Math.cos(lat) * Math.cos(lon), + y: n * Math.cos(lat) * Math.sin(lon), + z: n * (1 - e2) * Math.sin(lat), + }; + const dot = p.x * drawn.x + p.y * drawn.y + p.z * drawn.z; + const cos = dot / (Math.hypot(p.x, p.y, p.z) * Math.hypot(drawn.x, drawn.y, drawn.z)); + infoGap = 6371008.8 * Math.acos(Math.min(1, cos)); + } + // While the 3D model is the visual the head ends at the model's tail + // anchor, which sits on the drawn (pixel-size-enlarged) model. + const model = window.__findTrackedModel ? window.__findTrackedModel() : null; + const sphere = model && model.ready && model.show ? model.boundingSphere : null; + // boundingSphere leaves out the minimum-pixel-size enlargement that + // computedScale carries; the drawn model is that much larger. + const enlarge = sphere && Number.isFinite(model.computedScale) && model.scale > 0 + ? Math.max(1, model.computedScale / model.scale) + : 1; + const radius = sphere ? sphere.radius * enlarge : null; + return { + end: dist(end, drawn), + onModel: sphere ? dist(end, sphere.center) <= radius + 50 : false, + modelRadius: radius, + infoGap, + vertices: line.length, + }; + }, trackedIcao); + // The same reading between frames, the way a page script polls it: the + // head holds the last rendered frame while getTrackedInfo dead-reckons + // the current instant. Logged only, to tell the two apart. + const betweenFrames = []; + for (let i = 0; i < 8; i++) { + await sleep(600); + betweenFrames.push(await evalPage((icao) => { + const viewer = window.__godsEyeView.viewer; + const head = viewer.entities.values.find((e) => String(e.id).startsWith('gev-trail:fl-head-')); + const line = head?.polyline?.positions?.getValue(viewer.clock.currentTime); + const drawn = viewer.trackedEntity?.position?.getValue(viewer.clock.currentTime); + if (!line?.length || !drawn) return null; + const end = line[line.length - 1]; + return Math.hypot(end.x - drawn.x, end.y - drawn.y, end.z - drawn.z); + }, trackedIcao)); + } + console.log(` (between frames: head end vs entity position, m: ${ + betweenFrames.map((v) => (v == null ? '-' : v.toFixed(1))).join(' ')})`); + // Freeze the plane where it got to, so later checks see a still contact. + await evalPage((icao) => { + const f = window.__SYNTH.flights.find((p) => p.icao === icao); + f.lon += (f.vel * (Date.now() - f.moveFromMs)) / 1000 + / (111320 * Math.cos((f.lat * Math.PI) / 180)); + delete f.moveFromMs; + }, trackedIcao); + const headUsable = headSamples.values.filter((v) => v != null); + if (headUsable.length < 10) { + skip('trail head: ends at the drawn icon on every frame', + `only ${headUsable.length} frames with a drawn head (timedOut=${headSamples.timedOut})`); + } else { + const worst = Math.max(...headUsable.map((v) => v.end)); + const off = headUsable.filter((v) => !(v.end <= 50 || v.onModel)); + const onModel = headUsable.filter((v) => v.end > 50 && v.onModel).length; + const radii = headUsable.map((v) => v.modelRadius).filter((v) => v != null); + const gaps = headUsable.map((v) => v.infoGap).filter((v) => v != null); + record('trail head: last vertex on the drawn icon (within 50 m, or on the drawn 3D model) on every frame', + off.length === 0, + `${off.length} of ${headUsable.length} frames off; max end-to-centre=${worst.toFixed(1)} m, ${onModel} frames ending on the model's tail (model radius ${ + radii.length ? Math.max(...radii).toFixed(0) : 'n/a'} m); getTrackedInfo vs drawn icon max=${ + gaps.length ? Math.max(...gaps).toFixed(1) : 'n/a'} m (logged only)`); + } + // ============================================================ // INVARIANT 2: NO PULL-OUT on a track switch // tracking B while tracking A must not fly to ~80 km overview. @@ -1584,7 +1816,7 @@ async function main() { mil.trackById(hex); await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))); const milTrackedBefore = !!mil.getTrackedInfo(); - fl.trackById(icao); // tracking commercial flips viewer.trackedEntity → military listener fires + fl.trackById(icao); // tracking commercial changes what the camera follows → military listener fires await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))); return { milTrackedBefore, @@ -1631,7 +1863,8 @@ async function main() { await evalPage((icao) => { window.__godsEyeView.dataManager.layers.get('flights').module.trackById(icao); }, h1Icao); - await sleep(1500); // follow camera settles; tracked GLB load kicks off + await sleep(1500); // follow camera settles + await evalPage(() => window.__qaFollowWithin(2000)); // within the 3 km model range // (i) The tracked standalone model must expose its pick id (= the icao). const h1ModelUp = await page.waitForFunction((icao) => { @@ -1639,16 +1872,22 @@ async function main() { const ti = fl.getTrackedInfo(); if (!ti || ti.icao24 !== icao) return false; const found = window.__findTrackedModel ? window.__findTrackedModel() : null; - return !!(found && found.ready && found.show && String(found.id) === icao); + return !!(found && found.ready && found.show && window.__qaModelIcao(found) === icao); }, { timeout: 60000, polling: 250 }, h1Icao).then(() => true).catch(() => false); if (h1ModelUp) { const modelPickId = await evalPage(() => { const m = window.__findTrackedModel(); - return m && m.id !== undefined && m.id !== null ? String(m.id) : null; + if (!m || m.id === undefined || m.id === null) return null; + // The draw port's pick id is `{set, id}`: the click resolver keys on + // both, so the set must be this layer's tracked model set. + if (typeof m.id === 'object') return { set: String(m.id.set), id: String(m.id.id) }; + return { set: null, id: String(m.id) }; }); - record('H1: tracked standalone model exposes its pick id', modelPickId === h1Icao, - `model.id=${JSON.stringify(modelPickId)} (want "${h1Icao}")`); + record('H1: tracked standalone model exposes its pick id', + modelPickId?.id === h1Icao + && (modelPickId.set === null || modelPickId.set.startsWith('flights-tracked-model:')), + `model.id=${JSON.stringify(modelPickId)} (want id "${h1Icao}" in the flights tracked-model set)`); } else if (!glbBackendCapable) { skip('H1: tracked standalone model exposes its pick id', `independent GLB control unavailable (${glbControlDetail})`); @@ -1667,15 +1906,21 @@ async function main() { const fl = window.__godsEyeView.dataManager.layers.get('flights').module; const ti = fl.getTrackedInfo(); if (!ti) return null; - const ent = v.trackedEntity; - const disp = ent && typeof ent.gevDisplayPosition === 'function' ? ent.gevDisplayPosition() : null; + const followed = window.__qaFollowed(); + const disp = typeof followed?.displayPosition === 'function' ? followed.displayPosition() : null; const pos = disp || ti.position; if (!pos) return null; const center = v.scene.cartesianToCanvasCoordinates(pos); if (!center) return null; + // The tracked plane is drawn by the layer's own tracked icon and + // tracked model sets; a pick on either names `{set, id}`. const isTrackedPick = (picked) => { if (!picked) return null; - if (picked.id === ent) return 'entity'; + const hit = picked.id && typeof picked.id === 'object' ? picked.id : null; + if (hit && String(hit.id) === ti.icao24 && typeof hit.set === 'string') { + if (hit.set.startsWith('flights-tracked-icon:')) return 'tracked-icon'; + if (hit.set.startsWith('flights-tracked-model:')) return 'tracked-model'; + } const raw = typeof picked.id === 'string' ? picked.id : (picked.primitive && picked.primitive.id); return raw === ti.icao24 ? 'icao-pick' : null; }; @@ -1733,7 +1978,7 @@ async function main() { }, 45); const h1StillTracking = await evalPage((icao) => { const ti = window.__godsEyeView.dataManager.layers.get('flights').module.getTrackedInfo(); - return !!(ti && ti.icao24 === icao) && !!window.__godsEyeView.viewer.trackedEntity; + return !!(ti && ti.icao24 === icao) && !!window.__qaFollowed(); }, h1Icao); record('H1: click on tracked plane keeps tracking (no deselect)', h1StillTracking, `picked via ${h1ClickPoint.via}; still tracking=${h1StillTracking}`); @@ -1744,9 +1989,10 @@ async function main() { // ============================================================ // REGRESSION M3 (rewritten 2026-07-02 — deliberate behavior change): - // when the TRACKED plane ages out (3 missed polls), tracking must clear - // and the camera must be RELEASED IN PLACE — viewer.trackedEntity - // undefined and NO jump (the old contract flew an ~80 km overview; the + // when the TRACKED plane ages out (10 min after its newest fix, past the + // 3 missed polls that remove an untracked plane), tracking must clear + // and the camera must be RELEASED IN PLACE — following nothing + // and NO jump (the old contract flew an ~80 km overview; the // owner field-ruled that wrong: "it randomly zooms way up and loses my // context"). The M3 ordering fix stays: tracking is cleared BEFORE the // removal loop deletes the plane's state, so we never sit mid-follow @@ -1765,31 +2011,52 @@ async function main() { const beforeTracking = !!fl.getTrackedInfo(); // Simulate the age-out via the shim: the plane stops arriving. window.__SYNTH.flights = window.__SYNTH.flights.filter((f) => f.icao !== icao); - // MISSING_POLL_LIMIT = 3 consecutive absent polls → removal + clear. - // Capture the camera pose right BEFORE the removing poll — the follow - // camera drifts with the coasting plane until the instant of release, - // so this is the "where the user was looking" reference. + // The tracked plane outlives MISSING_POLL_LIMIT (3 absent polls): it is + // kept until 10 min after its newest fix, so the camera keeps its target. await fl.update(v); await fl.update(v); - const c0 = v.camera.positionCartographic; - const atAgeOut = { - lonDeg: (c0.longitude * 180) / Math.PI, - latDeg: (c0.latitude * 180) / Math.PI, - height: c0.height, - }; - await fl.update(v); // third miss → removal + clear + in-place release - return { - beforeTracking, - atAgeOut, - stillTrackedAfter: !!fl.getTrackedInfo(), - viewerStillTracking: !!v.trackedEntity, - }; + await fl.update(v); + const trackedThroughMisses = !!fl.getTrackedInfo(); + // Jump the page clock past the 10 min retention instead of waiting. + const realNow = Date.now; + Date.now = () => realNow() + 11 * 60 * 1000; + try { + // Let the follow camera settle on the stopped plane, then capture the + // pose right BEFORE the removing poll: the "where the user was + // looking" reference. + await new Promise((res) => { + const stop = v.scene.postRender.addEventListener(() => { + stop(); + res(); + }); + v.scene.requestRender(); + }); + const c0 = v.camera.positionCartographic; + const atAgeOut = { + lonDeg: (c0.longitude * 180) / Math.PI, + latDeg: (c0.latitude * 180) / Math.PI, + height: c0.height, + }; + await fl.update(v); // past retention → removal + clear + in-place release + return { + beforeTracking, + trackedThroughMisses, + atAgeOut, + stillTrackedAfter: !!fl.getTrackedInfo(), + viewerStillTracking: !!window.__qaFollowed(), + }; + } finally { + Date.now = realNow; + } }, m3Icao); + record('M3: the tracked plane stays tracked through 3 missed polls (kept 10 min after its newest fix)', + m3.trackedThroughMisses, + `trackedThroughMisses=${m3.trackedThroughMisses}`); record('M3: tracking cleared after the tracked plane ages out (getTrackedInfo null)', m3.beforeTracking && !m3.stillTrackedAfter, `before=${m3.beforeTracking} trackedAfter=${m3.stillTrackedAfter}`); - record('M3: camera released after age-out (viewer.trackedEntity undefined)', + record('M3: camera released after age-out (the camera follows nothing)', !m3.viewerStillTracking, `viewerTracked=${m3.viewerStillTracking}`); @@ -1914,16 +2181,17 @@ async function main() { const v = window.__godsEyeView.viewer; const fl = window.__godsEyeView.dataManager.layers.get('flights').module; const labelText = () => { - const ent = v.trackedEntity; + const ent = window.__qaFollowed(); if (!ent) return null; // Post overlay-unification the tracked text lives in the host // presentation model (entities are asserted native-label-free); // the native read stays as a fallback so this probe still fails // loudly if BOTH surfaces are ever absent. - const model = ent.gevLabelModel; + const model = ent.labelModel; if (model) return [model.title, ...(model.details || [])].filter(Boolean).join('\n'); - if (!ent.label || !ent.label.text) return null; - const t = ent.label.text; + const label = ent.entity?.label; + if (!label || !label.text) return null; + const t = label.text; return typeof t === 'string' ? t : (t.getValue ? String(t.getValue(v.clock.currentTime)) : null); }; // Track a cruise plane that IS in the feed (aaa003: 8700 m, 250 m/s — @@ -1968,19 +2236,7 @@ async function main() { const fl = dm.layers.get('flights').module; const mil = dm.layers.get('military').module; const findBB = (id) => { - let found = null; - const walk = (coll) => { - const n = coll.length; - for (let i = 0; i < n; i++) { - let p; - try { p = coll.get(i); } catch { continue; } - if (!p) continue; - if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } - if (p.image !== undefined && p.alignedAxis !== undefined && p.id === id) found = p; - } - }; - walk(v.scene.primitives); - return found; + return window.__qaFindIcon(id); }; const snap = (id) => { const bb = findBB(id); @@ -2097,18 +2353,12 @@ async function main() { // ============================================================ console.log('\nGround 3D — grounded planes are model-eligible + snapped to the sampled skin'); const GROUND3D_STUB_H = 187.5; // stubbed tile-skin height (m, ellipsoid) - // Expected belly offsets (m): native origin-above-lowest-vertex × MODEL_SCALE - // × CLASS_SCALE_3D[klass] — constants match the layers' MODEL_BELLY_OFFSET_NATIVE - // / MODEL_SCALE pairs, which modelScale.test.mjs locks against the GLBs. - // Class is computed with the REAL classifier on the synthetic feed fields. - const g3dFlKlass = classifyAircraft({ typeCode: null, category: null }); - const g3dMilKlass = classifyAircraft({ typeCode: 'C130', category: undefined }); - const g3dFlOffset = 6.719 * 1 * (CLASS_SCALE_3D[g3dFlKlass] || 1); // airplane.glb, flights - // Hangar fleet (2026-08-16): military C130 → turboprop → the real atr72.glb, - // whose belly offset is the registry's measured bellyM (meters, scale 1) — - // NOT the jet.glb 5.631 × class formula. Pinned by modelScale.test.mjs. - const g3dMilOffset = CLASS_MODEL_REAL[g3dMilKlass]?.bellyM - ?? 5.631 * 1 * (CLASS_SCALE_3D[g3dMilKlass] || 1); // jet.glb fallback classes + // Expected belly offsets (m): the fleet model's wheel clearance at its + // life-size scale, the model chosen as the layers choose it + // (aircraftModelSpec) from the synthetic feed's fields: no type for the + // flights contact (the default airliner), a C130 for the military one. + const g3dFlOffset = aircraftModelSpec(FLEET_SET, { typeCode: null }).clearanceM; + const g3dMilOffset = aircraftModelSpec(FLEET_SET, { typeCode: 'C130' }).clearanceM; // Height-datum fix (Task 6): the flights-layer billboard for a grounded synthetic // (no geo_altitude in this stub feed, no warm terrain-height cache in a headless // run) now renders at baroM + geoidHeight(lat, lon) rather than the raw baro @@ -2261,28 +2511,17 @@ async function main() { await fl.update(v); await mil.update(v); const findBB = (id) => { - let found = null; - const walk = (coll) => { - const n = coll.length; - for (let i = 0; i < n; i++) { - let p; - try { p = coll.get(i); } catch { continue; } - if (!p) continue; - if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } - if (p.image !== undefined && p.alignedAxis !== undefined && p.id === id) found = p; - } - }; - walk(v.scene.primitives); - return found; + return window.__qaFindIcon(id); }; const flBB = findBB('aaa077'); const milBB = findBB('bbb177'); if (!flBB || !milBB) return { error: `ground billboards missing (fl=${!!flBB} mil=${!!milBB})` }; const radius = (pos) => Math.hypot(pos.x, pos.y, pos.z); - // Park the camera 8 km radially above the flights plane (both in view nadir-ish). + // Park the camera 2 km radially above the flights plane (both in view + // nadir-ish, both within the 3 km model range). const p = flBB.position; const r = Math.hypot(p.x, p.y, p.z); - const k = (r + 8000) / r; + const k = (r + 2000) / r; v.camera.cancelFlight(); v.camera.setView({ destination: { x: p.x * k, y: p.y * k, z: p.z * k }, @@ -2308,7 +2547,7 @@ async function main() { try { p = coll.get(i); } catch { continue; } if (!p) continue; if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } - if (p.modelMatrix && typeof p.ready !== 'undefined' && p.id === id) found = p; + if (p.modelMatrix && typeof p.ready !== 'undefined' && window.__qaModelIcao(p) === id) found = p; } }; walk(v.scene.primitives); @@ -2337,19 +2576,7 @@ async function main() { const g3dState = await evalPage(() => { const v = window.__godsEyeView.viewer; const findBB = (id) => { - let found = null; - const walk = (coll) => { - const n = coll.length; - for (let i = 0; i < n; i++) { - let p; - try { p = coll.get(i); } catch { continue; } - if (!p) continue; - if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } - if (p.image !== undefined && p.alignedAxis !== undefined && p.id === id) found = p; - } - }; - walk(v.scene.primitives); - return found; + return window.__qaFindIcon(id); }; const modelRadius = (id) => { const m = window.__g3dFindModel(id); @@ -2377,10 +2604,10 @@ async function main() { const flDelta = g3dState.flModelRadius - g3dIngest.flBBRadius; const milDelta = g3dState.milModelRadius - g3dIngest.milBBRadius; const HEIGHT_TOL_M = 1.0; - record(`ground-3d: flights model height = sampled skin + belly offset (${g3dFlKlass})`, + record(`ground-3d: flights model height = sampled skin + belly offset (default airliner)`, Math.abs(flDelta - flWantDelta) <= HEIGHT_TOL_M, `Δradial=${flDelta.toFixed(2)} m want=${flWantDelta.toFixed(2)} m (stub ${GROUND3D_STUB_H} + offset ${g3dFlOffset.toFixed(2)} − alt ${(150 + g3dFlGeoidN).toFixed(2)} [150 baro + ${g3dFlGeoidN.toFixed(2)} geoidN])`); - record(`ground-3d: military model height = sampled skin + belly offset (${g3dMilKlass})`, + record(`ground-3d: military model height = sampled skin + belly offset (C130)`, Math.abs(milDelta - milWantDelta) <= HEIGHT_TOL_M, `Δradial=${milDelta.toFixed(2)} m want=${milWantDelta.toFixed(2)} m (stub ${GROUND3D_STUB_H} + offset ${g3dMilOffset.toFixed(2)} − alt 0)`); record('ground-3d: billboard→model handoff holds on the ground (icons hidden once models render)', @@ -2565,7 +2792,7 @@ async function main() { } // WELD (tracked): the tracked CARD anchors to the model you can see. - // `gevVisualPosition` is a SEPARATE accessor from `gevDisplayPosition` on + // the record's `visualPosition` is a SEPARATE accessor from its `displayPosition` on // purpose — the latter carries the follow-camera anti-jitter contract and // must keep returning the cached dead-reckoned value the camera settled // on. So this asserts both halves: the visual accessor is welded to the @@ -2573,14 +2800,14 @@ async function main() { // dead-reckoned position rather than having been quietly repurposed. if (g3dTrackedUp) { const trackedWeld = await evalPage(() => { - const ent = window.__godsEyeView.viewer.trackedEntity; + const ent = window.__qaFollowed(); const m = window.__g3dFindModel('aaa077'); if (!m) return { error: 'no tracked model' }; const matrix = m.modelMatrix; const scale = Number.isFinite(m.computedScale) ? m.computedScale : (Number.isFinite(m.scale) ? m.scale : 1); - // airplane.glb is now bounding-box centred with transforms applied. + // Fleet models are drawn about their origin, transforms applied. const x = 0 * scale; const y = 0 * scale; const z = 0 * scale; @@ -2592,10 +2819,10 @@ async function main() { const at = (p) => (p ? Math.hypot( p.x - anchor.x, p.y - anchor.y, p.z - anchor.z, ) : null); - const visual = typeof ent?.gevVisualPosition === 'function' ? ent.gevVisualPosition() : null; - const display = typeof ent?.gevDisplayPosition === 'function' ? ent.gevDisplayPosition() : null; + const visual = typeof ent?.visualPosition === 'function' ? ent?.visualPosition() : null; + const display = typeof ent?.displayPosition === 'function' ? ent?.displayPosition() : null; return { - hasVisualAccessor: typeof ent?.gevVisualPosition === 'function', + hasVisualAccessor: typeof ent?.visualPosition === 'function', visualDelta: at(visual), displayDelta: at(display), }; @@ -2611,7 +2838,7 @@ async function main() { // anti-jitter accessor has been repurposed and the follow camera is at // risk. Skipped (not failed) when the DR cache is momentarily invalid. const displayDelta = trackedWeld.displayDelta; - record('weld: gevDisplayPosition still reports the dead-reckoned position (anti-jitter intact)', + record('weld: the record displayPosition still reports the dead-reckoned position (anti-jitter intact)', !Number.isFinite(displayDelta) || displayDelta > ACCESSOR_SEPARATION_EPSILON_M, Number.isFinite(displayDelta) ? `displayΔ=${displayDelta.toFixed(3)} m (must stay > ${ACCESSOR_SEPARATION_EPSILON_M} m — the ground-snap split)` @@ -2700,6 +2927,21 @@ async function main() { // CHANGE 4 (2026-07-03): arrival rotation freshness. Field test: "planes // look weird when you first come to them — rotations are weird". Two // repaired holes, both layers: + // + // SINCE THE GPU ICON SETS (2c4c66c71) there is no CPU rotation pass to + // tamper with or repair: each frame the shader turns every icon along the + // course its row's motion segment carries at that frame's time. The + // invariant — the nose is right on the first settled frame after a + // camera move and on the first frame a hidden contact is shown again — + // is now observed on the drawn rows: the on-screen nose the drawn course + // projects to, against the one the plane's feed course projects to, at + // the same position, on exactly those two frames (same 10° bound, same + // per-frame budgets). That the shader turns an icon to the screen angle + // its course projects to is the renderer's own contract, which the + // renderer conformance reference scenes draw (course-rotated arrows, + // top and tilted views); a CPU readback cannot see the GPU's rotation. The reveal hides and re-shows the row through the + // layer's own icon book, the only thing that hides a fleet icon. + // The two holes the passes repaired, for the record: // (a) SETTLE PASS — camera.moveEnd forces a full rotation pass on the // next frame (the pose-signature gate can eat a fly-to's settle: // the final easing frames land inside one 10 m/0.06° quantization @@ -2708,39 +2950,25 @@ async function main() { // idles gets its rotation refreshed the same tick (it used to // reappear wearing its stale/creation-north nose for up to 1 s). // Staged deterministically: park the camera nadir over the synthetic - // cluster, let rotations settle, TAMPER a billboard's rotation, then - // trigger each path with the camera idle. The fleet runs every 80 ms, - // independently of rendered FPS. Observe the first completed settle frame - // within 500 ms of forcing moveEnd and the first reveal frame within - // 500 ms of that settle frame: each budget sits inside the 1 s idle - // rotation refresh that could otherwise repair an incorrect first reveal, - // and a ~300 ms headless SwiftShader frame fits inside each of them. + // cluster, let it settle, then trigger each path with the camera idle. + // Observe the first completed settle frame within 500 ms of forcing + // moveEnd and the first reveal frame within 500 ms of that settle frame + // (the budgets once sat inside the 1 s idle rotation refresh; they are + // kept as they were). // ============================================================ - console.log('\nChange 4 — arrival rotation: moveEnd settle pass + horizon-reveal pass'); + console.log('\nChange 4 — arrival rotation: the drawn nose on the settle frame and the first reveal'); const arrival = await evalPage(async () => { const v = window.__godsEyeView.viewer; const dm = window.__godsEyeView.dataManager; - const { screenProjectedRotation } = await import(`${window.__gevQaSourceBase || '/src'}/data/iconOrientation.js`); + const { screenProjectedRotation } = await import(`${window.__gevQaSourceBase || '/src'}/render/cesium/iconOrientation.js`); const { observeArrivalRotationWithRetry } = await import(`${window.__gevQaSourceBase || '/src'}/tooling/trackArrivalObservation.mjs`); - // 3D models OFF for this phase: a model-handed-off billboard is hidden - // and skips rotation updates entirely — the probes need live billboards - // (this is also the app's default state the field report came from). + // 3D models OFF for this phase: a model-handed-off icon is hidden, and + // the probes need shown icons (this is also the app's default state the + // field report came from). dm.layers.get('flights').module.setParams({ models3d: false }); dm.layers.get('military').module.setParams({ models3d: false }); const findBB = (id) => { - let found = null; - const walk = (coll) => { - const n = coll.length; - for (let i = 0; i < n; i++) { - let p; - try { p = coll.get(i); } catch { continue; } - if (!p) continue; - if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } - if (p.image !== undefined && p.alignedAxis !== undefined && p.id === id) found = p; - } - }; - walk(v.scene.primitives); - return found; + return window.__qaFindIcon(id); }; const nextFrames = (n) => new Promise((res) => { let count = 0; @@ -2764,8 +2992,8 @@ async function main() { }); // Park the camera straight above the flights cluster (lift a live // billboard's position radially — no Cesium global needed in-page) so - // every probe plane projects on-screen, then let rotations settle at - // the new pose (the setView pose change forces a pass on the next tick). + // every probe plane projects on-screen, then let a few frames draw at + // the new pose. // aaa002 — aaa001 was evicted for good by the M3 age-out phase. const anchor = findBB('aaa002'); if (!anchor) return { error: 'anchor aaa002 missing' }; @@ -2779,62 +3007,99 @@ async function main() { }); await nextFrames(3); const angDiff = (a, b) => Math.abs(Math.atan2(Math.sin(a - b), Math.cos(a - b))); - const probe = async (id, course) => { + const probe = async (layer, id, course) => { const bb = findBB(id); if (!bb || !bb.show) return { error: `${id} missing/hidden` }; - const r0 = bb.rotation; // settled tamper origin; correctness uses a fresh projection below + if (!Number.isFinite(bb.course) && !Number.isFinite(bb.rotation)) { + return { error: `${id} has no drawn course or rotation` }; + } + const setIconShown = layer.testing?._setIconForTest; + if (typeof setIconShown !== 'function') return { error: `${id}: the layer has no icon test seam` }; + // The on-screen nose the drawn row shows now, against the feed's. + const drawnError = () => { + const now = findBB(id); + if (!now) return { shown: false, rotationError: NaN }; + // A GPU row is turned along its drawn course, or drawn upright; a + // billboard carries its screen rotation itself. + const drawn = Number.isFinite(now.course) + ? (now.rotates ? screenProjectedRotation(v.scene, now.position, now.course, null) : 0) + : now.rotation; + return { + shown: !!now.show, + rotationError: angDiff(drawn, screenProjectedRotation(v.scene, now.position, course, null)), + }; + }; const hasModel = !!(window.__g3dFindModel && window.__g3dFindModel(id)); - // A wall-clock timeout is inconclusive, not a wrong angle: the frame - // landed where the 1 s idle refresh could already have repaired it - // (seen once on headless SwiftShader: a 926 ms first frame). Such an - // observation gets one more attempt; one that measured a wrong angle — - // a wrong first reveal, or a wrong settle frame before a reveal - // timeout — never does. + // The settle/reveal budgets and the retry were written for the removed + // CPU passes (a frame late enough for the 1 s idle refresh to repair + // it was inconclusive); they are kept unchanged as a guard. A + // wall-clock timeout gets one more attempt; one that measured a wrong + // angle — a wrong first reveal, or a wrong settle frame before a + // reveal timeout — never does. + // + // The reveal: the row is hidden right after the settle frame, frames + // must actually draw it hidden, and only then is it shown again, so + // the frame measured is the first one that draws it after a hidden + // frame. It stays hidden for two drawn frames, past the frame that + // follows the settle frame, so the reveal is timed on an ordinary + // frame rather than on whether that one was pipelined; each hidden + // frame restarts the reveal's clock, and the setup is `hiddenMs`. + const REVEAL_HIDDEN_FRAMES = 2; + let revealArmed = false; + let hiddenFrames = 0; const observed = await observeArrivalRotationWithRetry({ async prepare() { - // Freshen both layers' rotation passes right before the probe, so - // the settle frame is measured against a pass that just ran rather - // than one left over from the previous probe — with the camera - // idle, a layer otherwise runs a pass only every - // ROTATION_REFRESH_MS. + // One settled camera move and a frame before each attempt, as the + // passes once needed (the layers' moveEnd now runs their fleet + // pass on the next frame). + revealArmed = false; + hiddenFrames = 0; v.camera.moveEnd.raiseEvent(); await nextFrames(1); }, scene: v.scene, startMoveEnd() { - // Only moveEnd can repair the tampered angle at the idle pose. - bb.rotation = r0 + 1.5; v.camera.moveEnd.raiseEvent(); }, startReveal() { - // Hide immediately after the confirmed settle frame. The next - // eligible fleet tick must reveal AND re-aim in that same tick. - bb.rotation = r0 + 1.5; - bb.show = false; + // Hide immediately after the confirmed settle frame, through the + // layer's icon book (written to the draw set as this task ends). + setIconShown(id, { shown: false }); + revealArmed = true; }, read() { - return { - shown: bb.show, - rotationError: angDiff(bb.rotation, - screenProjectedRotation(v.scene, bb.position, course, null)), - }; + const sample = drawnError(); + // A frame drew it hidden: after the last one, show it again for + // the next frame; the reveal is measured from here. + if (revealArmed && sample.shown === false) { + hiddenFrames += 1; + if (hiddenFrames >= REVEAL_HIDDEN_FRAMES) { + revealArmed = false; + setIconShown(id, { shown: true }); + } + return { ...sample, revealStartsNow: true }; + } + return sample; }, }); - return { r0, ...observed, hasModel }; + // A reveal is only one after a frame drew the row hidden. + if (!observed.error && hiddenFrames === 0) { + return { ...observed, error: 'no frame drew the row hidden before its reveal', hasModel }; + } + return { ...observed, hiddenFrames, hasModel }; }; const flightCourse = window.__SYNTH.flights.find((f) => f.icao === 'aaa002')?.track ?? 0; const militaryCourse = window.__SYNTH.military.find((m) => m.hex === 'bbb101')?.track ?? 0; return { - flights: await probe('aaa002', flightCourse), - military: await probe('bbb101', militaryCourse), + flights: await probe(dm.layers.get('flights').module, 'aaa002', flightCourse), + military: await probe(dm.layers.get('military').module, 'bbb101', militaryCourse), }; }); const fmtArr = (a) => (!a ? `no result (${arrival?.error || 'phase error'})` : a.error ? `${a.error}; ${arrivalAngleViolated(a) ? 'angle violation (not retried); ' : ''}${Number.isFinite(a.dMoveEnd) ? `settle-err=${(a.dMoveEnd * 180 / Math.PI).toFixed(1)}° ` : ''}${Number.isFinite(a.dReveal) ? `reveal-err=${(a.dReveal * 180 / Math.PI).toFixed(1)}° ` : ''}elapsed=${Number(a.elapsedMs).toFixed(1)} ms attempts=${a.attempts}` - : `settle-err=${(a.dMoveEnd * 180 / Math.PI).toFixed(1)}° reveal-err=${(a.dReveal * 180 / Math.PI).toFixed(1)}° shown=${a.shown} flipFrame=${a.flipFrame} settle=${a.moveEndMs.toFixed(1)} ms reveal=${a.revealMs.toFixed(1)} ms total=${a.elapsedMs.toFixed(1)} ms attempts=${a.attempts} hasModel=${a.hasModel}`); - const TAMPER_DEG = 1.5 * 180 / Math.PI; // ≈ 86° — an uncorrected nose stays this far off - record(`arrival: moveEnd + first reveal both re-aim before idle refresh, flights (tamper was ${TAMPER_DEG.toFixed(0)}°)`, + : `settle-err=${(a.dMoveEnd * 180 / Math.PI).toFixed(1)}° reveal-err=${(a.dReveal * 180 / Math.PI).toFixed(1)}° shown=${a.shown} flipFrame=${a.flipFrame} settle=${a.moveEndMs.toFixed(1)} ms reveal=${a.revealMs.toFixed(1)} ms hidden=${a.hiddenMs.toFixed(1)} ms total=${a.elapsedMs.toFixed(1)} ms attempts=${a.attempts} hasModel=${a.hasModel}`); + record('arrival: the drawn nose is right on the settle frame and the first reveal, flights', arrivalRotationPassed(arrival.flights), fmtArr(arrival.flights)); - record(`arrival: moveEnd + first reveal both re-aim before idle refresh, military (tamper was ${TAMPER_DEG.toFixed(0)}°)`, + record('arrival: the drawn nose is right on the settle frame and the first reveal, military', arrivalRotationPassed(arrival.military), fmtArr(arrival.military)); // ============================================================ @@ -2895,18 +3160,7 @@ async function main() { }; fl.setParams({ models3d: false }); // billboards own the visual (T7 gate open) window.__dfFindBB = (id) => { - let found = null; - const walk = (coll) => { - const n = coll.length; - for (let i = 0; i < n; i++) { - let p; try { p = coll.get(i); } catch { continue; } - if (!p) continue; - if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } - if (p.image !== undefined && p.alignedAxis !== undefined && p.id === id) found = p; - } - }; - walk(v.scene.primitives); - return found; + return window.__qaFindIcon(id); }; window.__dfCarto = (pos) => { const c = Cesium.Cartographic.fromCartesian(pos, Cesium.Ellipsoid.WGS84); @@ -2992,7 +3246,7 @@ async function main() { if (!p) continue; if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } if (p.activeAnimations !== undefined && p.minimumPixelSize !== undefined) { - if (icao !== undefined && p.id !== icao) continue; + if (icao !== undefined && window.__qaModelIcao(p) !== icao) continue; if (p.show) { shown += 1; if (p.ready === true) rendering += 1; @@ -3017,7 +3271,7 @@ async function main() { if (!p) continue; if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } if (p.activeAnimations !== undefined && p.minimumPixelSize !== undefined - && p.id === icao && p.modelMatrix) { + && window.__qaModelIcao(p) === icao && p.modelMatrix) { const m = p.modelMatrix; // Cesium's default is the IDENTITY matrix — translation (0,0,0), // the Earth's centre, which `Cartographic.fromCartesian` refuses. @@ -3035,23 +3289,18 @@ async function main() { walk(v.scene.primitives); return h; }; - // Tracked-contact model regime (2026-08-20). The tracked contact's model - // is NOT governed by the DISPLAY-rail 3D toggle — that toggle owns the - // FLEET's draw-call budget. The tracked model is default-on and driven by - // camera distance, entering below TRACKED_MODEL_ENTER_ALT_M and handing - // back to the billboard only above TRACKED_MODEL_EXIT_ALT_M (the - // anti-flap band). The CAMERA is therefore what decides whether a model - // or a billboard is the visual for a tracked contact, which is exactly - // what the display floor stands aside for — so these pins drive the - // camera explicitly instead of the toggle. + // Tracked-contact model regime. The tracked contact draws as a model + // exactly when the fleet's rule would draw it so: 3D on, the camera + // below the fleet ceiling, and the contact inside the nearest-first + // add/keep band from the eye. These pins drive the camera across that + // band: a model inside the ADD radius, the billboard past the KEEP one. // - // Read the thresholds from the app's own policy module so a later retune - // of the swap distance moves these pins with it rather than stranding - // them on stale numbers. - const reg = await import(`${window.__gevQaSourceBase || '/src'}/data/trackedModelRegime.js`); + // Read the radii from the app's own policy module so a retune moves + // these pins with it rather than stranding them on stale numbers. + const reg = await import(`${window.__gevQaSourceBase || '/src'}/layers/flights/policy.js`); window.__dfRegime = { - enter: reg.TRACKED_MODEL_ENTER_ALT_M, - exit: reg.TRACKED_MODEL_EXIT_ALT_M, + enter: reg.MODEL_ADD_M, + exit: reg.MODEL_KEEP_M, }; // Zooming while following is safe: the tracked-camera framer positions // the camera ONCE per selection and is deliberately read-only on normal @@ -3397,9 +3646,29 @@ async function main() { // after d0 was read; a lower seed makes the negative model-ownership // assertion impossible even when the clamp correctly stands aside. const seeded = Math.max(d0.h, 400) + 40; - for (let dy = -1; dy <= 1; dy++) { - for (let dx = -1; dx <= 1; dx++) { - gf.reportMeshFloorCell(cell(d0.lat) + dy * 0.001, cell(d0.lon) + dx * 0.001, seeded); + // The contact keeps taxiing while the regimes below are driven (the + // model wait alone can run to 20 s), so the planted floor reaches + // along its heading as well: the 3×3 cells around it, and the same + // three cells across the track every ~100 m for 600 m ahead. A + // contact that left a 3×3 patch was read over an unplanted cell, + // where a DEM floor that had already landed under its raw height + // decided the assertion instead of the regime. + const headingDeg = window.__SYNTH.flights.find((f) => f.icao === 'aaa097')?.track ?? 0; + const headingRad = headingDeg * Math.PI / 180; + const metresPerDegLat = 111320; + const metresPerDegLon = metresPerDegLat * Math.cos(d0.lat * Math.PI / 180); + const plantedCells = new Set(); + for (let aheadM = 0; aheadM <= 600; aheadM += 100) { + const lat = d0.lat + (aheadM * Math.cos(headingRad)) / metresPerDegLat; + const lon = d0.lon + (aheadM * Math.sin(headingRad)) / metresPerDegLon; + for (let dy = -1; dy <= 1; dy++) { + for (let dx = -1; dx <= 1; dx++) { + const c = [cell(lat) + dy * 0.001, cell(lon) + dx * 0.001]; + const key = `${c[0].toFixed(3)},${c[1].toFixed(3)}`; + if (plantedCells.has(key)) continue; + plantedCells.add(key); + gf.reportMeshFloorCell(c[0], c[1], seeded); + } } } const fleetClampDeadline = Date.now() + 5000; @@ -3417,7 +3686,7 @@ async function main() { // the sensor value the data APIs report, at whatever regime the camera // is currently in. const readTracked = () => { - const pos = v.trackedEntity?.position?.getValue(Cesium.JulianDate.now()); + const pos = window.__qaFollowed()?.position?.(); if (!pos) return null; const c = window.__dfCarto(pos); const info = fl.getTrackedInfo(); @@ -3492,19 +3761,19 @@ async function main() { for (let i = 0; i < collection.length; i++) { const item = collection.get(i); if (typeof item?.get === 'function' && typeof item.length === 'number') walk(item); - else if (item?.id === 'aaa097' && item.activeAnimations !== undefined + else if (window.__qaModelIcao(item) === 'aaa097' && item.activeAnimations !== undefined && item.minimumPixelSize !== undefined) found = item; } }; walk(v.scene.primitives); return found; }; - const trackedEntity = v.trackedEntity; + const trackedEntity = window.__qaFollowed(); const trackedModel = findOwnModel(); const achievedOut = await window.__dfZoomAbove(window.__dfRegime.exit + 5000); const zoomedOut = await window.__dfObserveTrackedExit({ scene: v.scene, trackedEntity, trackedModel, getTrackedModel: findOwnModel, - getTrackedEntity: () => v.trackedEntity, + getTrackedEntity: () => window.__qaFollowed(), getTrackedId: () => fl.getTrackedInfo()?.icao24, getCameraHeight: window.__dfCamH, exitHeight: window.__dfRegime.exit, read: readTracked, @@ -3590,8 +3859,8 @@ async function main() { // WARM ground, camera IN: the placement. The model is not merely visible, // it is standing ON the floor — within one class belly offset above it, - // never under it. MAX_BELLY_M clears the largest offset any class adds - // (widebody b789, 7.81 m in CLASS_MODEL_REAL); the floor itself is the + // never under it. MAX_BELLY_M clears the largest wheel clearance any + // fleet aircraft stands on at life size; the floor itself is the // hard lower bound, and a model placed at the raw feed altitude is ~240 m // under it. const MAX_BELLY_M = 12; @@ -3672,7 +3941,7 @@ async function main() { return { skipped: 'no tracked model rendered in this browser' }; } // While the model IS the visual the clamp must stand aside (T7). - const entWith = v.trackedEntity?.position?.getValue(Cesium.JulianDate.now()); + const entWith = window.__qaFollowed()?.position?.(); const withModelH = entWith ? window.__dfCarto(entWith).h : null; // Close the deterministic skin again for the rest of the group. The // model is up on a snap that is already cached, so it stays up until the @@ -3687,7 +3956,7 @@ async function main() { // contact's primitive, and an unrelated model in the scene must not be // able to answer it either way. const afterOut = window.__dfCountModels('aaa097'); - const ent = v.trackedEntity?.position?.getValue(Cesium.JulianDate.now()); + const ent = window.__qaFollowed()?.position?.(); const c = ent ? window.__dfCarto(ent) : null; // Plant a floor above wherever it now renders so "floored" is decisive. // Mesh cells latch ONE-SHOT, so the earlier scenario's seed would win @@ -3708,7 +3977,7 @@ async function main() { // from mistaking a cached same-frame position for a failed clamp. v.scene.requestRender(); await window.__dfSettle(900); - const ent2 = v.trackedEntity?.position?.getValue(Cesium.JulianDate.now()); + const ent2 = window.__qaFollowed()?.position?.(); const c2 = ent2 ? window.__dfCarto(ent2) : null; const out = { toggleOff, @@ -3727,7 +3996,7 @@ async function main() { // Hand the camera back to the CLOSE follow range before releasing. The // LOADING scenario below needs BOTH an active tracked regime and a // fleet model for this contact, and the fleet only admits models within - // MODEL_PROX_ADD_M of the camera — parking just inside the enter + // MODEL_ADD_M of the camera — parking just inside the enter // ceiling satisfies the regime but sits outside that add radius, which // silently starved the fleet half into a skip. await window.__dfZoomBelow(belowH + 500); @@ -3800,7 +4069,7 @@ async function main() { let p; try { p = coll.get(i); } catch { continue; } if (!p) continue; if (typeof p.length === 'number' && typeof p.get === 'function') { walk(p); continue; } - if (p.activeAnimations !== undefined && p.minimumPixelSize !== undefined && p.id === id) found = p; + if (p.activeAnimations !== undefined && p.minimumPixelSize !== undefined && window.__qaModelIcao(p) === id) found = p; } }; walk(v.scene.primitives); @@ -3816,19 +4085,30 @@ async function main() { fl.setParams({ models3d: false }); return { skipped: 'no fleet model for aaa097 in this browser' }; } + // The layer decides who owns the visual from its OWN record of the + // model (data/modelRecord.js: `ready` from the draw set's ready event, + // `show` as it last sent it), not from the renderer's model object, so + // the shown-but-not-ready state is planted on that record. The record + // is the registered layer's own, reached through its test seam. + const fleetRecord = await fl.testing?._ensureFleetModelForTest?.('aaa097'); + if (!fleetRecord || typeof fleetRecord !== 'object') { + fl.setParams({ models3d: false }); + return { error: 'the flights layer has no model record for aaa097' }; + } // Accessors with SWALLOWING setters, not data properties: the fleet tick - // assigns `model.show = false` for a not-ready model, and assigning to a + // assigns `show = false` for a not-ready model, and assigning to a // non-writable own property throws in strict mode — which lands inside - // Cesium's render loop and stops rendering for the rest of the run. - const priorReady = Object.getOwnPropertyDescriptor(fleetModel, 'ready'); - const priorShow = Object.getOwnPropertyDescriptor(fleetModel, 'show'); + // the render loop and stops rendering for the rest of the run. + const priorReady = Object.getOwnPropertyDescriptor(fleetRecord, 'ready'); + const priorShow = Object.getOwnPropertyDescriptor(fleetRecord, 'show'); let armed = false; let processedFrame = null; let sample = null; + let sampledRecord = null; let removePostRender = null; try { - Object.defineProperty(fleetModel, 'ready', { get: () => false, set: () => {}, configurable: true }); - Object.defineProperty(fleetModel, 'show', { + Object.defineProperty(fleetRecord, 'ready', { get: () => false, set: () => {}, configurable: true }); + Object.defineProperty(fleetRecord, 'show', { get: () => true, set: (value) => { // Both the not-ready handoff and horizon cull clear show AFTER @@ -3842,7 +4122,10 @@ async function main() { }); const bb = window.__dfFindBB('aaa097'); if (!bb) return { error: 'aaa097 billboard missing' }; - bb.show = true; // the handoff would not have hidden it: the model is not ready + // (The icon is not forced shown here, as the old billboard fixture did: + // the renderer draws what the layer sends, so the handoff the record + // drives is the only thing that decides it.) + const sameIcon = (a, b) => !!a && !!b && (a === b || (a.setId === b.setId && a.id === b.id)); const d0 = window.__dfCarto(bb.position); gf._clearMeshFloorCellsForTest(); // Earlier display-floor scenarios deliberately leave this contact's @@ -3865,13 +4148,18 @@ async function main() { sample = { fleetTickCompleted: true, fleetFrame: v.scene.frameState.frameNumber, - fleetModelReady: fleetModel.ready, - fleetModelShow: fleetModel.show, + fleetModelReady: fleetRecord.ready, + fleetModelShow: fleetRecord.show, fleetBillboardVisible: !!currentBb?.show, fleetSeeded: seededFleet, fleetH: currentBb ? window.__dfCarto(currentBb.position).h : null, }; - if (currentBb !== bb || currentModel !== fleetModel || fleetModel.isDestroyed() + // (An older build's seam answers asynchronously: its answer is + // checked once the frame is done, below.) + const currentRecord = fl.testing._ensureFleetModelForTest('aaa097'); + if (typeof currentRecord?.then === 'function') sampledRecord = currentRecord; + else if (currentRecord !== fleetRecord) sample.error = 'fleet loading fixture changed before its completed frame'; + if (!sameIcon(currentBb, bb) || currentModel !== fleetModel || fleetModel.isDestroyed() || fl.getTrackedInfo()) sample.error = 'fleet loading fixture changed before its completed frame'; }); armed = true; @@ -3882,14 +4170,17 @@ async function main() { await window.__dfSettle(50); } while (!sample && Date.now() < tickDeadline); if (!sample) return { error: 'fleet loading fixture did not complete an aircraft update within 5000 ms' }; + if (sampledRecord && (await sampledRecord) !== fleetRecord) { + sample.error = 'fleet loading fixture changed before its completed frame'; + } Object.assign(out, sample); } finally { armed = false; removePostRender?.(); - if (priorReady) Object.defineProperty(fleetModel, 'ready', priorReady); - else delete fleetModel.ready; - if (priorShow) Object.defineProperty(fleetModel, 'show', priorShow); - else delete fleetModel.show; + if (priorReady) Object.defineProperty(fleetRecord, 'ready', priorReady); + else delete fleetRecord.ready; + if (priorShow) Object.defineProperty(fleetRecord, 'show', priorShow); + else delete fleetRecord.show; fl.setParams({ models3d: false }); } await window.__dfSettle(400); @@ -3900,7 +4191,7 @@ async function main() { // it finishes. Sample within that window. if (!fl.trackById('aaa097')) return { ...out, error: 'trackById(aaa097) failed' }; await window.__dfSettle(500); - const entBefore = v.trackedEntity?.position?.getValue(Cesium.JulianDate.now()); + const entBefore = window.__qaFollowed()?.position?.(); const cBefore = entBefore ? window.__dfCarto(entBefore) : null; gf._clearMeshFloorCellsForTest(); fl._clearDisplayFloorStateForTest(); @@ -3922,7 +4213,7 @@ async function main() { // billboard-owned. The shared helper keys models by their pick id and // uses the production ownership pair (`show && ready`). out.renderingModelsDuringLoad = window.__dfCountModels('aaa097').rendering; - const entLoad = v.trackedEntity?.position?.getValue(Cesium.JulianDate.now()); + const entLoad = window.__qaFollowed()?.position?.(); out.trackedSeeded = seededTracked; out.trackedLoadH = entLoad ? window.__dfCarto(entLoad).h : null; fl.setParams({ models3d: false }); @@ -4042,7 +4333,12 @@ async function main() { const taxiCarto = window.__dfCarto(taxiPos); const baseMeshM = gfns?.cachedMeshFloor?.(baseCarto.lat, baseCarto.lon) ?? null; const taxiMeshM = gfns?.cachedMeshFloor?.(taxiCarto.lat, taxiCarto.lon) ?? null; + // The layer writes its icon changes to the draw set together once the + // current task's microtasks run (data/aircraftIconLayer.js), so the + // drawn row is read after that write, with no frame in between. + const iconWrites = () => Promise.resolve(); const heldOwns = ns._driveFleetModelHandoffForTest({ icao24: holdIcao, position: taxiPos, course: 90 }); + await iconWrites(); const heldH = window.__dfModelHeight(holdIcao); const heldBb = !!window.__dfFindBB(holdIcao)?.show; @@ -4050,6 +4346,7 @@ async function main() { // been. It is released rather than stretched, and the gate takes over. const farPos = Cesium.Cartesian3.fromDegrees(base.lon + 0.004, base.lat, base.h); const releasedOwns = ns._driveFleetModelHandoffForTest({ icao24: holdIcao, position: farPos, course: 90 }); + await iconWrites(); const releasedBb = !!window.__dfFindBB(holdIcao)?.show; fl.setParams({ models3d: false }); diff --git a/scripts/viewer-access-baseline.mjs b/scripts/viewer-access-baseline.mjs new file mode 100644 index 0000000000..4a2614a9bd --- /dev/null +++ b/scripts/viewer-access-baseline.mjs @@ -0,0 +1,63 @@ +/** + * Lower `src/render/viewerAccessAllowList.json` to the Cesium-shaped viewer + * accesses the files off the Cesium list still hold + * (`src/render/viewerAccess.test.mjs`). It only lowers counts and drops + * entries (files with none left, gone, or back on the Cesium list); it never + * adds a file or raises a count. A file over its count is reported and the + * script exits 1: port that access instead. + * + * `--check` reports what it would change without writing, and exits 1 when + * there is anything to lower. + */ +import { writeFileSync } from 'node:fs'; +import path from 'node:path'; +import { + BASELINE, + countedFiles, + currentHits, + readBaseline, + ROOT, +} from '../src/testSupport/viewerAccess.mjs'; + +const check = process.argv.includes('--check'); +const baseline = readBaseline(); +const hits = currentHits(); +const counted = new Set(countedFiles()); + +const next = {}; +const changes = []; +for (const [file, allowed] of Object.entries(baseline)) { + const found = counted.has(file) ? (hits.get(file)?.length ?? 0) : 0; + const count = Math.min(allowed, found); + if (count > 0) next[file] = count; + if (count !== allowed) changes.push(`${file}: ${allowed} → ${count}`); +} +const over = [...hits] + .filter(([file, found]) => found.length > (baseline[file] ?? 0)) + .map( + ([file, found]) => + `${file}: ${found.length} found, ${baseline[file] ?? 0} recorded`, + ); + +if (changes.length) { + console.log( + `${check ? 'Would lower' : 'Lowered'}:\n ${changes.join('\n ')}`, + ); + if (!check) { + const sorted = Object.fromEntries( + Object.keys(next) + .sort() + .map((file) => [file, next[file]]), + ); + writeFileSync( + path.join(ROOT, BASELINE), + `${JSON.stringify(sorted, null, 2)}\n`, + ); + } else process.exitCode = 1; +} else console.log(`${BASELINE} is as low as it goes.`); +if (over.length) { + console.error( + `Over their counts (never raised; port these):\n ${over.join('\n ')}`, + ); + process.exitCode = 1; +} diff --git a/scripts/voice-bench/phrases.mjs b/scripts/voice-bench/phrases.mjs index 89d531b71e..6ea53f0127 100644 --- a/scripts/voice-bench/phrases.mjs +++ b/scripts/voice-bench/phrases.mjs @@ -35,6 +35,14 @@ export const CORE_PHRASES = Object.freeze([ { phrase: 'Show me the whole earth', expect: 'zoom_to_globe' }, { phrase: 'Frame the aircraft near us from overhead', expect: 'frame_overhead', typedArgs: [where('frame_overhead', (a) => a.target === 'flights')] }, + // — street-level photos: one composite action, never fly + basemap — + { phrase: 'Show me the Eiffel Tower on Street View', expect: 'show_street_level', typedArgs: [where('show_street_level', (a) => a.provider === 'google' && /eiffel/i.test(a.query || ''))] }, + { phrase: 'Street view of 10th Street in Sacramento', expect: 'show_street_level', typedArgs: [where('show_street_level', (a) => a.provider === 'google')] }, + { phrase: 'Show me Times Square on Mapillary', expect: 'show_street_level', typedArgs: [where('show_street_level', (a) => a.provider === 'mapillary')] }, + { phrase: 'Switch to Google Street View', expect: 'show_street_level', typedArgs: [where('show_street_level', (a) => a.provider === 'google' && !a.query)] }, + { phrase: 'Show me the Eiffel Tower', expect: 'fly_to_location' }, + { phrase: 'Turn on street level', expect: 'set_layer_visibility', typedArgs: [where('set_layer_visibility', (a) => a.layerId === 'street-level' && a.enabled === true)] }, + // — the satellites trap: data layer, never basemap — { phrase: 'Show me the satellites', expect: { oneOf: ['set_layer_visibility', 'frame_overhead'] } }, { phrase: 'Turn off the satellites', expect: 'set_layer_visibility', args: { layerId: 'satellites' }, typedArgs: [where('set_layer_visibility', (a) => a.layerId === 'satellites' && a.enabled === false)] }, diff --git a/server/providers/firms.js b/server/providers/firms.js index d21dc296e8..2b0e009445 100644 --- a/server/providers/firms.js +++ b/server/providers/firms.js @@ -150,6 +150,11 @@ export async function fetchFirms( * Keyless (no FIRMS_MAP_KEY): /api/firms → 503 {error:'no_key'}; status → * {hasKey:false}. Upstream is never touched without a key. * + * /api/firms answers the trailing 24 hours to now. A source may instead + * answer the 24 hours to a set time, naming its end as `at` (epoch ms); the + * layer's row then shows that time rather than LIVE. This proxy never sets + * `at`. + * * @returns {import('vite').Plugin} */ export function firmsProxy() { diff --git a/server/providers/gemini/realtime.js b/server/providers/gemini/realtime.js index fa8821afaa..ec2c87cd38 100644 --- a/server/providers/gemini/realtime.js +++ b/server/providers/gemini/realtime.js @@ -63,7 +63,10 @@ export function createGeminiTokenHandler({ return reply(403, 'Gemini voice requires a same-origin app request'); apiKey = String(resolveApiKey() || '').trim(); if (!apiKey) - return reply(503, 'Add a Gemini API key in Provider Settings'); + return reply(503, { + error: 'Add a Gemini API key in Provider Settings', + code: 'API_KEY_MISSING', + }); model = normalizeGeminiModel(resolveModel()); if (!model) return reply(503, 'The Gemini Live model configuration is invalid'); diff --git a/server/providers/library.js b/server/providers/library.js new file mode 100644 index 0000000000..822d912a3e --- /dev/null +++ b/server/providers/library.js @@ -0,0 +1,103 @@ +import { LIBRARY_ENTRIES } from '../../src/library/catalog.js'; +import { createLibraryHandler } from '../../src/library/proxy.js'; +import { makeRateLimiter, clientKey } from './common/rate-limit.js'; +import { admitSameSite, admitSameSiteKeyless } from './common/same-site.js'; + +export { + libraryAvailability, + libraryKeyValue, + parseLibraryTilePath, +} from '../../src/library/proxy.js'; + +/** `content-type` as `Content-Type`: a fetch Response's names, as Node writes them. */ +const headerName = (name) => + name.replace( + /(^|-)([a-z])/g, + (_, dash, letter) => dash + letter.toUpperCase(), + ); + +/** + * The Data Library's one server route on the dev and preview servers: the + * portable handler (`src/library/proxy.js`) behind this server's same-site + * gate and rate limits. + */ +export function libraryProxy({ + entries = LIBRARY_ENTRIES, + env = process.env, + fetchImpl = (...args) => globalThis.fetch(...args), + now = () => Date.now(), +} = {}) { + const byId = new Map(entries.map((entry) => [entry.id, entry])); + const handle = createLibraryHandler({ entries, env, fetchImpl, now }); + const allowData = makeRateLimiter({ + windowMs: 60_000, + max: 30, + globalMax: 600, + }); + const allowTiles = makeRateLimiter({ + windowMs: 60_000, + max: 600, + globalMax: 6000, + }); + + function refuse(res, status, error) { + if (res.destroyed) return; + res.writeHead(status, { + 'Content-Type': 'application/json', + 'Cache-Control': 'no-store', + ...(status === 405 ? { Allow: 'GET' } : {}), + ...(status === 429 ? { 'Retry-After': '60' } : {}), + }); + res.end(JSON.stringify({ error })); + } + + async function handler(req, res) { + if (req.method !== 'GET') return refuse(res, 405, 'method_not_allowed'); + const path = (req.url || '/').split('?')[0]; + const [route, id] = path.split('/').filter(Boolean); + const entry = byId.get(id); + if (route === 'catalog' || !entry) { + if (admitSameSiteKeyless(req, res)) return undefined; + } else { + // A keyed entry spends the operator's credential: refuse forwarded + // requests like the other cost-bearing routes. Keyless entries keep + // working behind a reverse proxy, like terrain heights. + if ( + entry.source?.key + ? admitSameSite(req, res) + : admitSameSiteKeyless(req, res) + ) + return undefined; + const allow = route === 'tile' ? allowTiles : allowData; + if (!allow(clientKey(req))) return refuse(res, 429, 'rate_limited'); + } + const response = await handle( + new Request(`http://library.invalid/api/library${req.url || '/'}`, { + headers: { Accept: String(req.headers?.accept || '*/*') }, + }), + ); + if (res.destroyed) return undefined; + const headers = {}; + for (const [name, value] of response.headers) + headers[headerName(name)] = value; + const body = Buffer.from(await response.arrayBuffer()); + res.writeHead(response.status, headers); + res.end( + String(headers['Content-Type']).startsWith('application/json') + ? body.toString('utf8') + : body, + ); + return undefined; + } + + return { + name: 'data-library', + handler, + configureServer({ middlewares }) { + middlewares.use('/api/library', handler); + }, + configurePreviewServer({ middlewares }) { + middlewares.use('/api/library', handler); + }, + }; +} diff --git a/server/providers/library.test.mjs b/server/providers/library.test.mjs new file mode 100644 index 0000000000..2e009b33ca --- /dev/null +++ b/server/providers/library.test.mjs @@ -0,0 +1,381 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { + libraryAvailability, + libraryProxy, + parseLibraryTilePath, +} from './library.js'; +import { validateLibraryCatalog } from '../../src/library/manifest.js'; +import { libraryEntry } from '../../src/library/catalog.js'; + +const base = { + family: 'events', + provider: 'Fixture', + description: 'Fixture entry.', + maintainer: 'test', + coverage: { global: true }, + licence: { name: 'Public domain', url: 'https://example.org/licence' }, + attribution: { text: 'Fixture' }, + status: 'community', +}; +const { entries, errors } = validateLibraryCatalog([ + { + ...base, + id: 'proxied-points', + kind: 'dataset', + title: 'Proxied points', + source: { + format: 'geojson', + url: 'https://data.example.org/points.json', + fetch: 'proxied', + maxBytes: 4096, + }, + display: { label: 'title' }, + }, + { + ...base, + id: 'direct-points', + kind: 'dataset', + title: 'Direct points', + source: { + format: 'geojson', + url: 'https://data.example.org/direct.json', + fetch: 'browser-direct', + }, + }, + { + ...base, + id: 'keyed-points', + kind: 'dataset', + title: 'Keyed points', + source: { + format: 'geojson', + url: 'https://keyed.example.org/points.json', + fetch: 'proxied', + key: { id: 'firms', in: 'query', name: 'MAP_KEY' }, + }, + }, + { + ...base, + id: 'opt-in-points', + kind: 'dataset', + title: 'Opt-in points', + source: { + format: 'geojson', + url: 'https://data.example.org/opt.json', + fetch: 'proxied', + }, + licence: { ...base.licence, operatorOptIn: true }, + }, + { + ...base, + id: 'proxied-tiles', + kind: 'tiles', + title: 'Proxied tiles', + source: { + format: 'xyz', + url: 'https://tiles.example.org/{z}/{x}/{y}.png', + fetch: 'proxied', + minZoom: 2, + maxZoom: 5, + }, + }, + { + ...base, + id: 'fixture-pack', + kind: 'pack', + family: 'cameras', + title: 'Fixture cameras', + source: { format: 'host', url: 'https://cams.example.org/' }, + pack: { host: 'cctv', env: 'CCTV_FIXTURE_ENABLED' }, + licence: { ...base.licence, operatorOptIn: true }, + }, +]); +assert.deepEqual(errors, []); + +const collection = (features) => + JSON.stringify({ type: 'FeatureCollection', features }); +const point = (title) => ({ + type: 'Feature', + geometry: { type: 'Point', coordinates: [1, 2] }, + properties: { title }, +}); + +function install({ env = {}, fetchImpl, now, catalog = entries } = {}) { + const plugin = libraryProxy({ entries: catalog, env, fetchImpl, now }); + let handler; + plugin.configurePreviewServer({ + middlewares: { + use(path, callback) { + assert.equal(path, '/api/library'); + handler = callback; + }, + }, + }); + return async (url, headers = {}) => { + const res = { + headers: {}, + writeHead(status, values) { + this.status = status; + this.headers = values; + }, + setHeader(name, value) { + this.headers[name] = value; + }, + end(body) { + this.raw = body; + try { + this.body = JSON.parse(body); + } catch { + this.body = null; + } + }, + set statusCode(value) { + this.status = value; + }, + }; + await handler( + { url, method: 'GET', headers, socket: { remoteAddress: '127.0.0.1' } }, + res, + ); + return res; + }; +} + +test('availability is decided by the operator environment and names no secret', () => { + const none = libraryAvailability(entries, {}); + assert.deepEqual(none.get('proxied-points'), { + available: true, + reason: null, + }); + assert.equal(none.get('keyed-points').reason, 'key-missing'); + assert.equal(none.get('opt-in-points').reason, 'operator-opt-in'); + assert.equal(none.get('fixture-pack').reason, 'operator-opt-in'); + const configured = libraryAvailability(entries, { + FIRMS_MAP_KEY: 'secret', + GEV_LIBRARY_ENABLE: 'opt-in-points', + GEV_LIBRARY_DISABLE: 'proxied-points', + CCTV_FIXTURE_ENABLED: '1', + }); + assert.equal(configured.get('keyed-points').available, true); + assert.equal(configured.get('opt-in-points').available, true); + assert.equal(configured.get('proxied-points').reason, 'operator-disabled'); + assert.equal(configured.get('fixture-pack').available, true); + assert.doesNotMatch(JSON.stringify([...configured]), /secret/); +}); + +test('the catalog route lists every entry with its availability', async () => { + const request = install(); + const res = await request('/catalog'); + assert.equal(res.status, 200); + assert.equal(res.body.entries.length, entries.length); + assert.deepEqual( + res.body.entries.find(({ id }) => id === 'opt-in-points'), + { id: 'opt-in-points', available: false, reason: 'operator-opt-in' }, + ); +}); + +test('a proxied dataset reaches only its manifest URL, refuses redirects and is normalized', async () => { + const calls = []; + const request = install({ + now: () => 42, + fetchImpl: async (url, options) => { + calls.push({ url, options }); + return new Response(collection([point('Storm'), { geometry: null }])); + }, + }); + const res = await request('/data/proxied-points?url=https://evil.example'); + assert.equal(res.status, 200); + assert.equal(calls.length, 1); + assert.equal(calls[0].url, 'https://data.example.org/points.json'); + assert.equal(calls[0].options.redirect, 'error'); + assert.ok(calls[0].options.signal instanceof AbortSignal); + assert.equal(res.body.features.length, 1); + assert.equal(res.body.features[0].properties.name, 'Storm'); + assert.equal(res.body.dropped, 1); + assert.equal(res.body.fetchedAt, 42); + // A fresh cache answers without another upstream request. + await request('/data/proxied-points'); + assert.equal(calls.length, 1); +}); + +test('browser-direct, unknown, opt-in and wrong-kind entries are not proxied', async () => { + let calls = 0; + const request = install({ + fetchImpl: async () => { + calls++; + return new Response(collection([])); + }, + }); + assert.equal((await request('/data/direct-points')).status, 404); + assert.equal((await request('/data/nope-nope')).status, 404); + assert.equal((await request('/data/proxied-tiles')).status, 404); + assert.equal((await request('/tile/proxied-points/2/0/0')).status, 404); + const optIn = await request('/data/opt-in-points'); + assert.equal(optIn.status, 403); + assert.equal(optIn.body.error, 'operator-opt-in'); + assert.equal(calls, 0); +}); + +test('a keyed entry gets the operator key server-side and refuses forwarded requests', async () => { + const calls = []; + const request = install({ + env: { FIRMS_MAP_KEY: 'k3y' }, + fetchImpl: async (url) => { + calls.push(new URL(url)); + return new Response(collection([point('Fire')])); + }, + }); + const forwarded = await request('/data/keyed-points', { + 'x-forwarded-for': '203.0.113.9', + }); + assert.equal(forwarded.status, 403); + assert.equal(calls.length, 0); + const res = await request('/data/keyed-points'); + assert.equal(res.status, 200); + assert.equal(calls[0].searchParams.get('MAP_KEY'), 'k3y'); + assert.doesNotMatch(res.raw, /k3y/); +}); + +test('an oversized or failing upstream answers 502 without its text, then serves stale', async () => { + let clock = 0; + let mode = 'ok'; + const request = install({ + now: () => clock, + fetchImpl: async () => { + if (mode === 'big') return new Response('x'.repeat(8192)); + if (mode === 'fail') + return new Response('secret upstream text', { status: 500 }); + return new Response(collection([point('A')])); + }, + }); + mode = 'big'; + const big = await request('/data/proxied-points'); + assert.equal(big.status, 502); + assert.doesNotMatch(big.raw, /x{20}/); + mode = 'ok'; + assert.equal((await request('/data/proxied-points')).status, 200); + clock = 10 * 3600 * 1000; + mode = 'fail'; + const stale = await request('/data/proxied-points'); + assert.equal(stale.status, 200); + assert.equal(stale.body.stale, true); + assert.equal(stale.headers['X-Data-Stale'], 'true'); + assert.doesNotMatch(stale.raw, /secret upstream text/); +}); + +test('cross-site browser requests are refused before any upstream request', async () => { + let calls = 0; + const request = install({ + fetchImpl: async () => { + calls++; + return new Response(collection([])); + }, + }); + const res = await request('/data/proxied-points', { + host: 'localhost:5173', + origin: 'https://evil.example', + 'sec-fetch-site': 'cross-site', + }); + assert.equal(res.status, 403); + assert.equal(calls, 0); +}); + +test('tiles: bounded z/x/y, image types only, cached', async () => { + const calls = []; + const request = install({ + fetchImpl: async (url) => { + calls.push(url); + if (url.includes('/3/')) + return new Response('', { + headers: { 'content-type': 'text/html' }, + }); + return new Response(new Uint8Array([137, 80, 78, 71]), { + headers: { 'content-type': 'image/png' }, + }); + }, + }); + assert.equal((await request('/tile/proxied-tiles/1/0/0')).status, 400); + assert.equal((await request('/tile/proxied-tiles/2/4/0')).status, 400); + assert.equal((await request('/tile/proxied-tiles/2/a/0')).status, 400); + const ok = await request('/tile/proxied-tiles/2/1/3'); + assert.equal(ok.status, 200); + assert.equal(ok.headers['Content-Type'], 'image/png'); + assert.equal(calls[0], 'https://tiles.example.org/2/1/3.png'); + await request('/tile/proxied-tiles/2/1/3'); + assert.equal(calls.length, 1); + assert.equal((await request('/tile/proxied-tiles/3/1/1')).status, 502); +}); + +test('tile paths are parsed against the zoom range', () => { + const source = { minZoom: 0, maxZoom: 3 }; + assert.deepEqual(parseLibraryTilePath(['3', '7', '7'], source), { + z: 3, + x: 7, + y: 7, + }); + assert.equal(parseLibraryTilePath(['3', '8', '0'], source), null); + assert.equal(parseLibraryTilePath(['4', '0', '0'], source), null); + assert.equal(parseLibraryTilePath(['1', '0'], source), null); +}); + +test('only GET is served', async () => { + const plugin = libraryProxy({ entries, env: {} }); + const res = { + writeHead(status, headers) { + this.status = status; + this.headers = headers; + }, + end() {}, + }; + await plugin.handler({ url: '/catalog', method: 'POST', headers: {} }, res); + assert.equal(res.status, 405); +}); + +test('a partition index is cached only when complete; a complete one outlives failed rebuilds', async () => { + const epc = libraryEntry('epc-england-wales'); + let clock = 0; + let footers = 'ok'; + let listings = 0; + const listing = `a.parquet100`; + const fetchImpl = async (url) => { + if (url.includes('list-type')) { + listings += 1; + return new Response(listing); + } + return footers === 'ok' + ? new Response(new Uint8Array(100)) + : new Response('', { status: 503 }); + }; + const request = install({ catalog: [epc], now: () => clock, fetchImpl }); + const first = await request('/index/epc-england-wales'); + assert.equal(first.status, 200); + assert.equal(first.body.complete, true); + const builtAt = first.body.builtAt; + + // Past cacheSeconds the rebuild fails: the complete index is still served, + // and no rebuild runs again until the partial pause has passed. + clock += (epc.source.cacheSeconds + 1) * 1000; + footers = 'fail'; + const kept = await request('/index/epc-england-wales'); + assert.equal(kept.body.complete, true); + assert.equal(kept.body.builtAt, builtAt); + const listed = listings; + await request('/index/epc-england-wales'); + assert.equal(listings, listed); + + // A server that never had a complete index serves the partial one as such, + // and rebuilds after the pause. + const fresh = install({ catalog: [epc], now: () => clock, fetchImpl }); + const partial = await fresh('/index/epc-england-wales'); + assert.equal(partial.status, 200); + assert.equal(partial.body.complete, false); + const before = listings; + await fresh('/index/epc-england-wales'); + assert.equal(listings, before); + clock += 6 * 60_000; + footers = 'ok'; + const rebuilt = await fresh('/index/epc-england-wales'); + assert.equal(rebuilt.body.complete, true); + assert.equal(listings, before + 1); +}); diff --git a/server/providers/local.js b/server/providers/local.js index 41b0fd3a58..76c347db49 100644 --- a/server/providers/local.js +++ b/server/providers/local.js @@ -16,6 +16,7 @@ import { radioBrowserProxy } from './radio.js'; import { gbfsProxy } from './gbfs.js'; import { localReceiversProxy } from './local-receivers.js'; import { transitProxy } from './transit.js'; +import { railProxy } from './rail.js'; import { adsbLolProxy } from './aircraft/adsb-lol.js'; import { aisLiveProxy } from './vessels/ais-live.js'; import { trackBackfillProxies } from './aircraft/tracks.js'; @@ -28,11 +29,14 @@ import { weatherProxy } from './weather.js'; import { firePerimetersProxy } from './firePerimeters.js'; import { gnssIntegrityProxy } from './gnssIntegrity.js'; import { ghostMapsProxy } from './ghostMaps.js'; +import { shipwrecksProxy } from './shipwrecks.js'; import { droneAirspaceProxy } from './droneAirspace.js'; +import { newsProxy } from './news.js'; import { inaturalistProxy } from './inaturalist/observations.js'; import { acartiaProxy } from './acartia.js'; import { cycloneProxy } from './cyclones.js'; import { windProxy } from './wind.js'; +import { libraryProxy } from './library.js'; /** * Construct the local provider plugins in their established order. @@ -69,6 +73,7 @@ function localProviderPlugins({ gbfsProxy(), localReceiversProxy(), transitProxy(), + railProxy(), adsbLolProxy(), aisLiveProxy(), trackBackfillProxies(), @@ -81,8 +86,11 @@ function localProviderPlugins({ mapillaryProxy(), firePerimetersProxy(), gnssIntegrityProxy(), + libraryProxy(), ghostMapsProxy(), + shipwrecksProxy(), droneAirspaceProxy(), + newsProxy(), inaturalistProxy(), acartiaProxy(), keySetupEndpoint(), diff --git a/server/providers/news.js b/server/providers/news.js new file mode 100644 index 0000000000..30f7aa31f2 --- /dev/null +++ b/server/providers/news.js @@ -0,0 +1,191 @@ +import { newsQueryAllowed } from '../../src/layers/news/source.js'; +import { readResponseTextCapped } from './common/http.js'; +import { sameSiteGated } from './common/same-site.js'; +import { createKeyedNews } from './news/keyed.js'; + +// News (/api/news/*). With GEV_NEWS_ORIGIN set (a news server such as +// https://news.example), this forwards exactly the GET requests the news +// layer sends there and relays the JSON. Without it (or with a value that +// is no plain origin, warned of once), Core answers the same routes itself +// (news/keyed.js): Conflicts from GDELT's event exports with no key, and +// Liveuamap's items beside them with LIVEUAMAP_API_KEY; Local from World +// News API, "key required" while WORLDNEWSAPI_KEY is unset. A host that +// serves news only from its own server mounts it with `builtIn: false`. + +const TIMEOUT_MS = 15_000; +const MAX_BYTES = 4 * 1024 * 1024; + +/** + * The configured news server's origin, or null: http(s) only, no + * credentials, query or fragment; a path is ignored. + * @param {string|undefined} raw + */ +export function newsOrigin(raw = process.env.GEV_NEWS_ORIGIN) { + const text = String(raw ?? '').trim(); + if (!text) return null; + try { + const url = new URL(text); + if ( + !['http:', 'https:'].includes(url.protocol) || + url.username || + url.password || + url.search || + url.hash + ) + return null; + return url.origin; + } catch { + return null; + } +} + +/** Text for the log: no address (a key may ride in one), one short line. */ +const logText = (error) => + `${error?.name || 'Error'}: ${String(error?.message ?? '')}` + .replace(/[a-z][a-z0-9+.-]*:\/\/\S*/gi, '') + .replace(/\s+/g, ' ') + .slice(0, 200); + +/** GEV_NEWS_ORIGIN as newsOrigin reads it; a value it refuses is warned of once. */ +function configuredOrigin(env, log) { + let warned = null; + return () => { + const raw = String(env().GEV_NEWS_ORIGIN ?? '').trim(); + const base = newsOrigin(raw); + if (!base && raw && warned !== raw) { + warned = raw; + // Not the value: it may carry credentials. + log( + '[news] GEV_NEWS_ORIGIN is not a plain http(s) origin; answering with the built-in news backend', + ); + } + return base; + }; +} + +/** A 503's known key or configuration state, rebuilt from its fields; else null. */ +async function upstreamState(upstream) { + let body = null; + try { + body = JSON.parse(await readResponseTextCapped(upstream, 16 * 1024)); + } catch { + return null; + } + if (body?.error === 'news_not_configured') + return { error: body.error, unavailable: true, retryable: false }; + if ( + ['no_key', 'key_rejected', 'key_quota'].includes(body?.error) && + typeof body.key === 'string' && + /^[a-z][a-z0-9-]{0,31}$/.test(body.key) + ) + return { error: body.error, key: body.key }; + return null; +} + +/** + * A thin, validated GET proxy for the news layer's three read routes, or + * their keyed answers without a news server. A host that serves news only + * from its own server passes `builtIn: false`: without GEV_NEWS_ORIGIN the + * routes then answer "not configured" and Core reads nothing itself. + * @param {{env?: () => object, log?: (message: string) => void, origin?: () => string|null, fetchImpl?: typeof fetch, timeoutMs?: number, builtIn?: boolean, keyed?: {answer: (path: string, params: URLSearchParams) => Promise<{status: number, body: object}>}|null}} [options] + */ +export function newsProxy({ + env = () => process.env, + log = (message) => console.warn(message), + origin = configuredOrigin(env, log), + fetchImpl = (...args) => globalThis.fetch(...args), + timeoutMs = TIMEOUT_MS, + builtIn = true, + keyed = builtIn ? createKeyedNews({ env, fetchImpl, log }) : null, +} = {}) { + const json = (res, status, value) => { + if (res.destroyed) return; + res.writeHead(status, { + 'Content-Type': 'application/json', + 'Cache-Control': 'no-store', + ...(status === 405 ? { Allow: 'GET' } : {}), + }); + res.end(typeof value === 'string' ? value : JSON.stringify(value)); + }; + + async function handler(req, res) { + if (req.method !== 'GET') + return json(res, 405, { error: 'method_not_allowed' }); + let local, target; + try { + // `//[` and the like are no URL: a 400, not an unhandled rejection. + local = new URL(req.url || '/', 'http://local'); + target = new URL( + `/api/news${local.pathname}${local.search}`, + 'http://local', + ); + } catch { + return json(res, 400, { error: 'invalid_news_request' }); + } + if (!newsQueryAllowed(target)) + return json(res, 400, { error: 'invalid_news_request' }); + const base = origin(); + if (!base) { + if (!keyed) + return json(res, 503, { + error: 'news_not_configured', + unavailable: true, + retryable: false, + }); + try { + const { status, body } = await keyed.answer( + local.pathname, + target.searchParams, + ); + return json(res, status, body); + } catch (error) { + log(`[news] built-in news answer failed: ${logText(error)}`); + return json(res, 502, { error: 'news_unavailable' }); + } + } + try { + const upstream = await fetchImpl( + new URL(`${target.pathname}${target.search}`, base), + { + headers: { Accept: 'application/json' }, + redirect: 'error', + signal: AbortSignal.timeout(timeoutMs), + }, + ); + if (upstream.status === 503) { + // The news server's own key and configuration states reach the + // panel as they are, so it can say which key is missing. + const state = await upstreamState(upstream); + if (state) return json(res, 503, state); + } + if (!upstream.ok) { + await upstream.body?.cancel().catch(() => {}); + return json(res, 502, { + error: 'news_upstream_error', + status: upstream.status, + }); + } + const text = await readResponseTextCapped(upstream, MAX_BYTES); + // Relayed only as JSON; the browser validates every record. + JSON.parse(text); + return json(res, 200, text); + } catch (error) { + return json(res, error?.name === 'TimeoutError' ? 504 : 502, { + error: 'news_unavailable', + }); + } + } + + // The routes spend keys and upstream reads: no other site's page, and no + // proxied request, may drive them (SECURITY.md, cross-site gate). + const gated = sameSiteGated(handler); + return { + name: 'news', + configureServer({ middlewares }) { + middlewares.use('/api/news', gated); + }, + configurePreviewServer({ middlewares }) { + middlewares.use('/api/news', gated); + }, + }; +} diff --git a/server/providers/news.test.mjs b/server/providers/news.test.mjs new file mode 100644 index 0000000000..aeaa6c597e --- /dev/null +++ b/server/providers/news.test.mjs @@ -0,0 +1,294 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { newsOrigin, newsProxy } from './news.js'; +import { createKeyedNews } from './news/keyed.js'; + +/** Mount the proxy on a fake middleware stack and call it like Connect does. */ +function mount(options) { + let handler = null; + newsProxy(options).configureServer({ + middlewares: { + use(prefix, fn) { + assert.equal(prefix, '/api/news'); + handler = fn; + }, + }, + }); + return async (url, method = 'GET', headers = {}) => { + const res = { + destroyed: false, + status: 0, + headers: {}, + body: '', + writeHead(status, headers) { + this.status = status; + this.headers = headers; + }, + setHeader(name, value) { + this.headers[name] = value; + }, + end(body) { + if (this.statusCode) this.status = this.statusCode; + this.body = body; + }, + }; + await handler({ url, method, headers }, res); + return { ...res, json: res.body ? JSON.parse(res.body) : null }; + }; +} + +test('the origin must be a plain http(s) origin', () => { + assert.equal( + newsOrigin('http://news.example:8080'), + 'http://news.example:8080', + ); + assert.equal( + newsOrigin('https://news.example/base/'), + 'https://news.example', + ); + for (const bad of [ + undefined, + '', + ' ', + 'ftp://x', + 'http://u:p@x', + 'http://x/?a=1', + 'http://x/#f', + 'not a url', + ]) + assert.equal(newsOrigin(bad), null, String(bad)); +}); + +test('without GEV_NEWS_ORIGIN Core answers itself: Conflicts from GDELT, Local saying it needs its key', async () => { + const hosts = []; + const fetchImpl = async (url) => { + hosts.push(new URL(String(url)).host); + throw new Error('offline'); + }; + const call = mount({ + origin: () => null, + fetchImpl, + keyed: createKeyedNews({ env: () => ({}), fetchImpl, log: () => {} }), + }); + // GDELT's exports need no key; offline, the read fails like any upstream. + const hotspots = await call('/hotspots'); + assert.equal(hotspots.status, 502); + assert.deepEqual(hotspots.json, { error: 'news_upstream_error' }); + const local = await call('/feed?hotspot=all&at=31.95,35.93'); + assert.equal(local.status, 503); + assert.deepEqual(local.json, { error: 'no_key', key: 'worldnewsapi' }); + // The area is read from the bundled countries, with no key. + const area = await call('/outline?at=31.95,35.93&v=4'); + assert.equal(area.status, 200); + assert.equal(area.json.area.name, 'Jordan'); + // The client's allowlist still holds. + assert.equal((await call('/feed?side=UA')).status, 400); + assert.ok(hosts.length > 0); + assert.ok(hosts.every((host) => host === 'data.gdeltproject.org')); +}); + +test('forwards only the client routes, by GET, and relays the JSON', async () => { + const calls = []; + const call = mount({ + origin: () => 'https://news.example', + fetchImpl: async (url, init) => { + calls.push({ url: String(url), init }); + return new Response('{"reports":[],"nextBefore":null}', { status: 200 }); + }, + }); + const ok = await call('/feed?hotspot=all&limit=60&today=1&events=1'); + assert.equal(ok.status, 200); + assert.deepEqual(ok.json, { reports: [], nextBefore: null }); + assert.equal(ok.headers['Cache-Control'], 'no-store'); + assert.equal( + calls[0].url, + 'https://news.example/api/news/feed?hotspot=all&limit=60&today=1&events=1', + ); + assert.equal(calls[0].init.redirect, 'error'); + assert.ok(calls[0].init.signal instanceof AbortSignal); + + for (const url of [ + '/air-alerts', + '/feed?side=UA', + '/feed?limit=9999', + '/../admin', + '/hotspots?x=1', + ]) { + const refused = await call(url); + assert.equal(refused.status, 400, url); + } + const post = await call('/hotspots', 'POST'); + assert.equal(post.status, 405); + assert.equal(post.headers.Allow, 'GET'); + assert.equal(calls.length, 1); +}); + +test('upstream failures, bad JSON and timeouts become bounded errors', async () => { + const failing = mount({ + origin: () => 'https://news.example', + fetchImpl: async () => new Response('down', { status: 500 }), + }); + const down = await failing('/hotspots'); + assert.equal(down.status, 502); + assert.deepEqual(down.json, { error: 'news_upstream_error', status: 500 }); + + const garbled = mount({ + origin: () => 'https://news.example', + fetchImpl: async () => new Response('', { status: 200 }), + }); + assert.equal((await garbled('/hotspots')).status, 502); + + const slow = mount({ + origin: () => 'https://news.example', + timeoutMs: 10, + // AbortSignal.timeout does not hold the event loop open: the hanging + // fetch does, until its signal aborts, so the run cannot end before it. + fetchImpl: (_url, { signal }) => + new Promise((_, reject) => { + const alive = setTimeout(() => {}, 60_000); + signal.addEventListener('abort', () => { + clearTimeout(alive); + reject(signal.reason); + }); + }), + }); + const timedOut = await slow('/hotspots'); + assert.equal(timedOut.status, 504); + assert.deepEqual(timedOut.json, { error: 'news_unavailable' }); +}); + +test('a GEV_NEWS_ORIGIN that is no plain origin is warned of once, and Core answers itself', async () => { + const logs = []; + const asked = []; + const call = mount({ + env: () => ({ GEV_NEWS_ORIGIN: 'https://user:secret@news.example' }), + log: (line) => logs.push(line), + fetchImpl: async () => assert.fail('nothing is forwarded'), + keyed: { + answer: async (path) => { + asked.push(path); + return { status: 200, body: { reports: [], nextBefore: null } }; + }, + }, + }); + assert.equal((await call('/feed?hotspot=all')).status, 200); + assert.equal((await call('/feed?hotspot=all')).status, 200); + assert.deepEqual(asked, ['/feed', '/feed']); + assert.equal(logs.length, 1); + assert.doesNotMatch(logs[0], /secret|news\.example/); +}); + +test('a built-in answer that throws is a 502, logged in one line without addresses', async () => { + const logs = []; + const call = mount({ + env: () => ({}), + log: (line) => logs.push(line), + keyed: { + answer: async () => { + throw new TypeError('bad https://api.example/?key=abc\nmore'); + }, + }, + }); + const failed = await call('/hotspots'); + assert.equal(failed.status, 502); + assert.deepEqual(failed.json, { error: 'news_unavailable' }); + assert.equal(logs.length, 1); + assert.match(logs[0], /TypeError/); + assert.doesNotMatch(logs[0], /key=abc|\n/); +}); + +test('a host that serves news only from its own server turns the built-in backend off', async () => { + let fetches = 0; + const call = mount({ + origin: () => null, + builtIn: false, + fetchImpl: async () => { + fetches++; + throw new Error('unexpected'); + }, + }); + for (const url of [ + '/hotspots', + '/feed?hotspot=all', + '/outline?at=31.95,35.93&v=4', + ]) { + const answer = await call(url); + assert.equal(answer.status, 503, url); + assert.deepEqual(answer.json, { + error: 'news_not_configured', + unavailable: true, + retryable: false, + }); + } + assert.equal(fetches, 0); +}); + +test('a request line that is no URL is a 400, not a crash', async () => { + const call = mount({ + origin: () => null, + keyed: { answer: async () => assert.fail('nothing is answered') }, + }); + // `GET /api/news//[`: Connect strips the mount prefix and leaves `//[`. + const bad = await call('//['); + assert.equal(bad.status, 400); + assert.deepEqual(bad.json, { error: 'invalid_news_request' }); +}); + +test('cross-site and proxied requests are refused before anything is read', async () => { + let answered = 0; + const call = mount({ + origin: () => null, + keyed: { + answer: async () => { + answered++; + return { status: 200, body: { reports: [], nextBefore: null } }; + }, + }, + }); + const host = 'localhost:5173'; + for (const headers of [ + { host, origin: 'https://evil.example' }, + { host, origin: 'null' }, + { host, 'sec-fetch-site': 'cross-site' }, + { host, 'x-forwarded-for': '203.0.113.9' }, + ]) { + const refused = await call('/feed?hotspot=all', 'GET', headers); + assert.equal(refused.status, 403, JSON.stringify(headers)); + } + assert.equal(answered, 0); + for (const headers of [ + { host }, + { host, origin: `http://${host}`, 'sec-fetch-site': 'same-origin' }, + ]) { + const passed = await call('/feed?hotspot=all', 'GET', headers); + assert.equal(passed.status, 200, JSON.stringify(headers)); + } + assert.equal(answered, 2); +}); + +test("a news server's key and configuration states are relayed as they are", async () => { + for (const body of [ + { error: 'no_key', key: 'worldnewsapi' }, + { error: 'key_rejected', key: 'worldnewsapi' }, + { error: 'key_quota', key: 'worldnewsapi' }, + { error: 'news_not_configured', unavailable: true, retryable: false }, + ]) { + const call = mount({ + origin: () => 'https://news.example', + fetchImpl: async () => + new Response(JSON.stringify(body), { status: 503 }), + }); + const relayed = await call('/feed?hotspot=all&at=31.95,35.93'); + assert.equal(relayed.status, 503, body.error); + assert.deepEqual(relayed.json, body); + } + // Any other 503 stays a bounded upstream error. + const other = mount({ + origin: () => 'https://news.example', + fetchImpl: async () => + new Response('{"error":"maintenance","detail":"x"}', { status: 503 }), + }); + const down = await other('/hotspots'); + assert.equal(down.status, 502); + assert.deepEqual(down.json, { error: 'news_upstream_error', status: 503 }); +}); diff --git a/server/providers/news/areas.js b/server/providers/news/areas.js new file mode 100644 index 0000000000..429e42bec7 --- /dev/null +++ b/server/providers/news/areas.js @@ -0,0 +1,232 @@ +// Areas for the News layer, from the bundled Natural Earth packs (public +// domain): the disputed area or else the country at a point, its outline in +// the /api/news/outline form, and a point inside a country to pin its +// national news at. A disputed area is checked first and named as itself, +// so no one country's name stands for it; so is a territory the countries +// pack gives no code (Somaliland), rather than read as sea. Read once, on +// first use. + +import { readFileSync } from 'node:fs'; + +import { + containsAnchor, + geometryOf, + pointInRing, +} from '../../../src/data/adminBoundaries.js'; + +const PACKS = '../../../src/data/local_data/natural_earth/'; +const PACK = new URL(`${PACKS}countries.json`, import.meta.url); +const DISPUTED = new URL(`${PACKS}disputed_areas.json`, import.meta.url); +const ISO2 = /^[A-Z]{2}$/; + +let countries = null; +let territories = []; + +/** + * One entry per ISO code: its name and every Country part's geometry. The + * Country features without a code ("-99": Somaliland, Northern Cyprus, + * sovereign base areas, no man's lands) are kept apart as territories. + */ +function loadCountries(read = () => JSON.parse(readFileSync(PACK, 'utf8'))) { + if (countries) return countries; + const pack = read(); + const decimals = pack.meta?.decimals ?? 3; + const byCode = new Map(); + const codeless = []; + for (const feature of pack.features || []) { + // The constituent countries of the United Kingdom repeat its part. + if (feature.type !== 'Country') continue; + if (!ISO2.test(feature.iso2 || '')) { + if (feature.name) + codeless.push({ name: feature.name, feature, decimals }); + continue; + } + const entry = byCode.get(feature.iso2) || { + code: feature.iso2, + name: null, + size: 0, + parts: [], + }; + entry.parts.push({ feature, decimals }); + // Named after its largest feature: Kazakhstan, not the Baikonur lease. + const size = JSON.stringify(feature.polygons).length; + if (size > entry.size) { + entry.name = feature.name; + entry.size = size; + } + byCode.set(feature.iso2, entry); + } + countries = byCode; + territories = codeless; + return countries; +} + +/** Test seam: read another pack (or the bundled one again). */ +export function resetCountries(read) { + countries = null; + if (read) loadCountries(read); +} + +const geometries = (entry) => entry.parts.map((part) => geometryOf(part)); + +let disputed = null; +const slug = (name) => + name + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-|-$/g, ''); + +/** The disputed areas: `{key, name, kind, heldBy, claimedBy, rings}`. */ +function loadDisputed() { + if (disputed) return disputed; + const pack = JSON.parse(readFileSync(DISPUTED, 'utf8')); + disputed = (pack.areas || []).map((area) => ({ + key: `disputed-${slug(area.name)}`, + name: area.name, + kind: area.kind, + heldBy: area.heldBy ?? null, + claimedBy: area.claimedBy ?? null, + rings: area.rings, + })); + return disputed; +} + +/** The disputed area at a point, or null. */ +export function disputedAt(lat, lon) { + return ( + loadDisputed().find((area) => + area.rings.some((ring) => pointInRing(ring, lat, lon)), + ) || null + ); +} + +/** + * The area a point is in, as the News layer names it: a disputed area, or + * a territory without a code, as itself (`kind: 'disputed'`, `code` null), + * else its country (`kind: 'country'`, with `country` the countryAt + * entry); null at sea. + */ +export function areaAt(lat, lon) { + const area = disputedAt(lat, lon); + if (area) + return { + ...area, + kind: 'disputed', + held: area.kind, + code: null, + polygons: area.rings.map((outer) => ({ outer, holes: [] })), + }; + const country = countryAt(lat, lon); + if (country) + return { + key: country.code, + name: country.name, + kind: 'country', + code: country.code, + country, + }; + const territory = territoryAt(lat, lon); + return territory + ? { + key: `disputed-${slug(territory.name)}`, + name: territory.name, + kind: 'disputed', + held: null, + code: null, + polygons: geometryOf(territory).polygons.map(([outer, ...holes]) => ({ + outer, + holes, + })), + } + : null; +} + +/** Whether a point lies in a geometry (geometryOf), across the antimeridian. */ +function inGeometry(geometry, lat, lon) { + const [west, south, east, north] = geometry.bbox; + const x = lon - 360 * Math.round((lon - (west + east) / 2) / 360); + if (x < west || x > east || lat < south || lat > north) return false; + return containsAnchor(geometry.polygons, lat, lon); +} + +/** The country at a point, or null at sea or in a territory without a code. */ +export function countryAt(lat, lon) { + for (const entry of loadCountries().values()) + for (const geometry of geometries(entry)) + if (inGeometry(geometry, lat, lon)) return entry; + return null; +} + +/** The territory without a code at a point (Somaliland), or null. */ +function territoryAt(lat, lon) { + loadCountries(); + return ( + territories.find((part) => inGeometry(geometryOf(part), lat, lon)) || null + ); +} + +/** A country by its ISO code, or null. */ +export const countryByCode = (code) => loadCountries().get(code) || null; + +/** + * A country's outline as /api/news/outline answers it (`{outer, holes}`), + * the disputed areas inside it left out as holes (Russia's without Crimea). + */ +export function countryPolygons(entry) { + const areas = loadDisputed(); + return geometries(entry).flatMap((geometry) => + geometry.polygons.map(([outer, ...holes]) => ({ + outer, + holes: [ + ...holes, + ...areas + .flatMap((area) => area.rings) + // By a point inside it: its corners lie on the neighbours' borders. + .filter((ring) => { + const inside = ringInterior(ring); + return inside && pointInRing(outer, inside.lat, inside.lon); + }), + ], + })), + ); +} + +/** + * A point inside the country's largest part, for news placed in the country + * alone: its label point when that lies inside, else the middle of the + * widest span across the part at its middle latitude. + */ +export function countryAnchor(entry) { + const largest = geometries(entry).sort((a, b) => b.areaKm2 - a.areaKm2)[0]; + const { label, polygons, bbox } = largest; + if (containsAnchor(polygons, label.lat, label.lon)) return label; + const [outer] = polygons.reduce((a, b) => + b[0].length > a[0].length ? b : a, + ); + return ringInterior(outer, (bbox[1] + bbox[3]) / 2) || label; +} + +/** + * A point inside a ring: the middle of its widest span at `lat` (its middle + * latitude by default); null when the ring is not crossed there. + */ +function ringInterior(outer, lat = middleLat(outer)) { + const crossings = []; + for (let i = 0, j = outer.length - 1; i < outer.length; j = i++) { + const [x1, y1] = outer[j]; + const [x2, y2] = outer[i]; + if (y1 > lat !== y2 > lat) + crossings.push(x1 + ((lat - y1) * (x2 - x1)) / (y2 - y1)); + } + crossings.sort((a, b) => a - b); + let best = null; + for (let i = 0; i + 1 < crossings.length; i += 2) + if (!best || crossings[i + 1] - crossings[i] > best[1] - best[0]) + best = [crossings[i], crossings[i + 1]]; + return best ? { lat, lon: (best[0] + best[1]) / 2 } : null; +} + +const middleLat = (ring) => { + const lats = ring.map(([, y]) => y); + return (Math.min(...lats) + Math.max(...lats)) / 2; +}; diff --git a/server/providers/news/categorize.js b/server/providers/news/categorize.js new file mode 100644 index 0000000000..c5619e9d83 --- /dev/null +++ b/server/providers/news/categorize.js @@ -0,0 +1,872 @@ +// Rule-based report categories, relevance and severity: the News layer's +// base reading, shared by every news server. Multilingual stems (en, uk, ru, +// ar, he and more) matched at a word start on normalised text; a trailing `$` +// makes a stem whole-word. A title hit counts double. Ties go to the earlier +// category in CATEGORY_ORDER, which runs from most to least specific. +// +// A news server may replace these readings with its own; the rules stay +// as the fallback. + +/** Text as the rules match it: folded case, one apostrophe, no vowel marks. */ +function normaliseForMatch(text) { + return String(text || '') + .normalize('NFKC') + .toLowerCase() + .replace(/ё/g, 'е') + .replace(/[’ʼ`´]/g, "'") + .replace(/[ً-ٰٟ֑-ׇ]/g, '') + .replace(/[أإآ]/g, 'ا'); +} + +export const CATEGORY_ORDER = Object.freeze([ + 'strike', + 'alert', + 'air-defence', + 'ground', + 'casualties', + 'humanitarian', + 'infrastructure', + 'disaster', + 'protest', + 'political', + // Business and trade: the rules' reading, or World News API's business. + 'economy', +]); + +// [stem, weight]; weight defaults to 1. +const RULES = { + strike: [ + 'strike', + 'airstrike', + 'air strike', + 'missile', + 'rocket', + 'drone', + 'shelling', + 'shelled', + 'bomb', + 'explosion', + 'blast', + 'artillery', + 'shahed', + ['attack', 0.5], + 'удар', + 'ракет', + 'дрон', + 'бпла', + 'обстріл', + 'обстрел', + 'вибух', + 'взрыв', + 'шахед', + 'бомб', + ['атак', 0.5], + 'غارة', + 'غارات', + 'قصف', + 'صاروخ', + 'صواريخ', + 'مسيرة', + 'انفجار', + ['استهداف', 0.7], + ['هجوم', 0.5], + 'תקיפה', + 'טיל', + 'רקט', + 'כטב"מ', + 'פיצוץ', + 'הפצצ', + ], + 'air-defence': [ + 'air defen', + 'intercept', + 'shot down', + 'downed', + 'air raid', + 'ппо', + 'збит', + 'сбит', + 'перехоп', + 'перехват', + 'повітряна тривога', + 'воздушная тревога', + 'الدفاع الجوي', + 'اعتراض', + 'יירוט', + 'יורט', + 'כיפת ברזל', + 'אזעק', + ], + ground: [ + 'advance$', + 'advances$', + 'advancing', + 'offensive', + 'captur', + 'liberat', + 'assault', + 'clash', + 'fighting', + 'counteroffensive', + 'frontline', + 'front line', + 'battle', + 'encircl', + ['troops', 0.5], + 'наступ', + 'штурм', + 'звільн', + 'освобо', + 'бої$', + 'бои$', + 'контрнаступ', + 'захоп', + 'захват', + 'оточ', + 'окруж', + 'продвиж', + 'просуван', + 'اشتباك', + 'معارك', + 'تقدم', + 'سيطر', + 'اقتحام', + 'توغل', + 'לחימה', + 'קרב', + 'פשיט', + 'תמרון', + ], + casualties: [ + 'killed', + 'dead$', + 'deaths', + 'wounded', + 'injured', + 'casualt', + 'death toll', + 'загин', + 'поранен', + 'жертв', + 'вбит', + 'погиб', + 'ранен', + 'убит', + 'قتلى', + 'شهداء', + 'شهيد', + 'جرحى', + 'مقتل', + 'اصاب', + 'הרוג', + 'נהרג', + 'פצוע', + 'נפצע', + ], + humanitarian: [ + 'evacuat', + 'aid$', + 'refugee', + 'displac', + 'humanitarian', + 'famine', + 'hunger', + 'convoy', + 'shelter', + 'евакуац', + 'эвакуац', + 'гуманітар', + 'гуманитар', + 'біженц', + 'беженц', + 'انسانية', + 'نازح', + 'نزوح', + 'مساعدات', + 'اجلاء', + 'مجاعة', + 'הומניטרי', + 'פינוי', + 'סיוע', + ], + infrastructure: [ + 'power outage', + 'blackout', + 'electricity', + 'energy', + 'grid$', + 'substation', + 'water supply', + 'bridge', + 'railway', + 'refinery', + 'port$', + 'dam$', + 'power plant', + 'енерг', + 'энерг', + 'знеструм', + 'обесточ', + 'підстанц', + 'подстанц', + 'залізниц', + 'железн', + 'нпз', + 'الكهرباء', + 'محطة', + 'مياه', + 'جسر', + 'חשמל', + 'תשתית', + ], + disaster: [ + 'earthquake', + 'flood', + 'wildfire', + 'landslide', + 'cyclone', + 'hurricane', + 'typhoon', + 'tsunami', + 'eruption', + 'glof$', + 'glacial lake', + 'storm$', + 'lightning', + 'землетрус', + 'землетрясен', + 'повін', + 'паводк', + 'наводнен', + 'زلزال', + 'فيضان', + 'سيول', + 'רעידת אדמה', + 'שיטפון', + ], + protest: [ + 'protest', + 'demonstrat', + 'rally$', + 'rallies', + 'riot', + // Not a bare "протест": "протестировал" is "tested". + 'протест$', + 'протеста', + 'протесту', + 'протестом', + 'протесте$', + 'протесты', + 'протестов', + 'протестн', + 'протестую', + 'протестова', + 'мітинг', + 'митинг', + 'احتجاج', + 'مظاهر', + 'تظاهر', + 'הפגנ', + 'מחאה', + ], + political: [ + 'talks$', + 'negotiat', + 'sanction', + 'summit', + 'ceasefire', + 'truce', + 'peace', + 'election', + 'parliament', + ['president', 0.5], + ['minister', 0.5], + ['statement', 0.5], + // A state visit ("Emir of Qatar arrives in Amman"). + ['visit', 0.5], + ['delegation', 0.5], + ['agreement', 0.5], + 'memorandum', + 'diplomat', + 'bilateral', + 'ambassador', + ['визит', 0.5], + ['делегац', 0.5], + 'дипломат', + 'переговор', + 'санкц', + 'перемир', + 'вибори', + 'выборы', + ['президент', 0.5], + ['міністр', 0.5], + ['министр', 0.5], + 'مفاوضات', + 'عقوبات', + 'هدنة', + 'وقف اطلاق النار', + ['وزير', 0.5], + ['رئيس', 0.5], + 'משא ומתן', + 'הפסקת אש', + 'סנקצי', + ['ראש הממשלה', 0.5], + ], + // Elections and party politics ("How Gina Hinojosa Captured Texas" is a + // governor's race, not a battle). They count toward political only when + // nothing physical happened (categorizeText): a strike in an election week + // is still a strike. + election: [ + 'midterm', + 'electoral', + 'elect$', + 'ballot', + 'voter', + 'vote$', + 'votes$', + 'voting', + 'polls$', + 'candidate', + 'senate race', + 'referendum', + 'inaugurat', + // Plurals only: "Democratic Republic of Congo", "Republican Guard". + 'democrats$', + 'republicans$', + 'gop$', + 'избира', + 'голосован', + 'виборц', + 'голосуван', + 'انتخاب', + 'בחירות', + ], +}; + +// Business, trade, industry and energy, counted only when nothing physical +// happened (categorizeText): an oil depot struck is a strike. English, +// Russian, Ukrainian, Turkish and the European stems. +RULES.economy = [ + 'econom', + 'gdp$', + 'inflation', + 'investment', + 'investor', + 'export', + 'imports$', + 'import$', + 'tariff', + 'trade deal', + 'trade turnover', + 'central bank', + 'stock market', + 'budget', + 'oil and gas', + 'oilfield', + 'oil field', + 'gas field', + 'exploration', + 'drilling', + 'mining', + 'industr', + 'manufactur', + 'business', + 'company', + 'companies', + 'revenue', + 'profit', + 'merger', + 'tourism', + 'agricultur', + 'harvest', + 'экономи', + 'инвест', + 'экспорт', + 'импорт', + 'инфляц', + 'ввп$', + 'бюджет', + 'промышлен', + 'бизнес', + 'компани', + 'товарооборот', + 'економі', + 'інвест', + 'експорт', + 'промисло', + 'ekonomi', + 'yatırım', + 'ihracat', + 'ithalat', + 'enflasyon', + 'sanayi', + 'şirket', + 'wirtschaft', + 'konjunktur', + 'unternehm', + 'inversi', + 'investiss', + 'investiment', + 'empresa', + 'entreprise', + 'impresa', +]; + +// Attack words beyond PHYSICAL's harm, which keep a report off economy. +const ATTACK = new RegExp( + String.raw`(? ({ + category, + rules: stems.map((entry) => { + const [stem, weight = 1] = Array.isArray(entry) ? entry : [entry]; + const whole = stem.endsWith('$'); + const body = escapeRegex( + normaliseForMatch(whole ? stem.slice(0, -1) : stem), + ).replace(/\s+/g, '\\s+'); + const arabic = /\p{Script=Arabic}/u.test(stem) ? '(?:[وفبلك]?(?:ال)?)' : ''; + const hebrew = /\p{Script=Hebrew}/u.test(stem) ? '(?:[ובלמהשכ]{0,2})' : ''; + return { + weight, + regex: new RegExp( + `(? `(? termPattern(term).test(text)); + // Any event reading counts, even when another category wins the title + // ("the accident toll rises to 74": infrastructure first, casualties too). + if ( + EVENT_CATEGORIES.has(category) || + tags.some((tag) => EVENT_CATEGORIES.has(tag)) + ) + return 'core'; + if (conflict && ['humanitarian', 'infrastructure'].includes(category)) + return 'core'; + if (conflict || dedicated || category === 'humanitarian') return 'related'; + return floor; +} + +// Alerts: air-raid alerts and reports of drones or missiles on their way +// ("Реактивний БпЛА курсом на Полтаву", "КАБи на Донеччину", "drone heading +// for Kyiv", "➡️"). Something is in the air; nothing has hit yet. Most of an +// air force's channel is these, and as "strikes" they would merge into real +// strike events and inflate them. +// A direction counts only after a weapon ("БпЛА … з півдня"), so a convoy +// leaving "in the direction of Oleshky" is not an alert. +const WEAPON = + '(?:бпла|дрон|шахед|герань|ракет|каб|балістик|крилат|боєприпас|боеприпас|uav|drone|missile|shahed|ballistic|cruise|munition)'; +const DIRECTION = + '(?:курсом на|у напрямку|в напрямку|в направлении|у бік|в сторону|повз |з (?:північ|півден|схід|сход|захід|заход)|с (?:север|юг|восток|запад)|на |над |heading |on course|toward)'; +const ALERT = new RegExp( + `${WEAPON}[^.!?]{0,40}${DIRECTION}|^[^\\p{L}]*курсом на|тривог|тревог|загроза застосування|угроза применения|air[- ]raid|threat of (?:missile|drone|ballistic|uav)|[➡⬅⬆⬇↗↘↙↖]`, + 'u', +); +// Wording that something did hit: then it is a strike (or air defence), not an alert. +const IMPACT = + /влуч|вибух|уражен|пошкодж|загин|поранен|зруйн|пожеж|атак|удар по|збит|знищ|попадан|взрыв|поражен|поврежд|погиб|ранен|разруш|сбит|уничтож|\bhit\b|\bhits\b|struck|explosion|blast|killed|injur|wounded|damage|destroy|fire\b|shot down|intercept|attack/u; + +/** Whether a report's title is an alert: a threat on its way, nothing hit yet. */ +function isAlertText(title = '', summary = '') { + const t = normaliseForMatch(`${title} ${summary}`.slice(0, 400)); + return ALERT.test(t) && !IMPACT.test(t); +} + +// "Hit" or "struck" says nothing on its own: what hit decides (a missile is a +// strike, a flood or lightning a disaster), and those words score by +// themselves. A few phrases use a category's word for another thing. +const PHRASES = [ + [/storm shadow/gu, 'missile'], + [/lightning strikes?/gu, 'lightning'], + [ + /(?:general|hunger|labou?r|workers?|nationwide|national|transport|rail|teachers?|doctors?|nurses?) strikes?|on strike|strike action/gu, + 'protest', + ], +]; +const rephrase = (text) => + PHRASES.reduce((out, [re, word]) => out.replace(re, word), text); + +// An election story borrows the words of war and disaster ("‘An Earthquake’: +// A Democratic Rout", "captured Texas", "a bloodbath for Republicans"). With +// election wording and nothing physical (no weapon, no one hurt, no quake's +// magnitude), the event categories give way to political. +const ELECTION = + /(? 0) scores.set(category, score); + } + const all = `${t} ${s}`; + const election = scores.get('election') || 0; + scores.delete('election'); + const physical = PHYSICAL.test(all); + // Business words and no harm or attack: "advance exploration" is no + // front-line advance; "attack an industrial facility" stays a strike. + if (physical || ATTACK.test(all)) scores.delete('economy'); + else if (scores.has('economy')) + for (const kind of EVENT_KINDS) scores.delete(kind); + if (!physical) { + if (election) + scores.set('political', (scores.get('political') || 0) + election); + if (ELECTION.test(all)) { + for (const kind of EVENT_KINDS) scores.delete(kind); + scores.set('political', Math.max(scores.get('political') || 0, 1)); + } + } + if (!scores.size) return { category: 'other', tags: [] }; + const ranked = CATEGORY_ORDER.filter((c) => scores.has(c)).sort( + (a, b) => scores.get(b) - scores.get(a), + ); + return { category: ranked[0], tags: ranked }; +} + +// Severity by rule, for reports without a severity of their own (0 none, +// 1 minor incident, 2 significant: deaths, injuries or real damage, 3 major: +// mass casualties). Wording in en, uk, ru, ar, he, es, fr, de. +const SEVERITY_EVENTS = new Set([...EVENT_CATEGORIES, 'infrastructure']); +const MAJOR_HARM = + /mass casualt|massacre|dozens (?:of \p{L}+ )?(?:killed|dead)|hundreds (?:of \p{L}+ )?(?:killed|dead)|масов\p{L}* (?:жертв|загибел|гибел)|десятки (?:загибл|погибш|убит|вбит|людей загин|человек погиб)|مجزرة|عشرات (?:القتلى|الشهداء)|טבח/u; +const HARM_WORDS = + 'kill|dead|died|death|injur|wound|casualt|загин|загибл|погиб|убит|вбит|поранен|ранен|постражд|пострадал|травм|قتل|قتيل|شهيد|شهداء|جرح|جريح|إصاب|اصاب|נהרג|הרוג|פצוע|muert|herid|tué|mort|bless|getötet|tote|verletz'; +const HARM = new RegExp(String.raw`(? 2100) most = Math.max(most, n); + } + return most; +} + +/** A report's severity by rule, 0–3. */ +export function severityByRules({ + category, + tags = [], + title = '', + summary = '', +}) { + const text = normaliseForMatch(`${title} ${summary}`); + const harmed = HARM.test(text) && !NO_HARM.test(text); + if (MAJOR_HARM.test(text) || (harmed && largestCount(text) >= 10)) return 3; + const event = + SEVERITY_EVENTS.has(category) || + tags.some((tag) => SEVERITY_EVENTS.has(tag)); + if (harmed && (event || category === 'humanitarian')) return 2; + if (event && DAMAGE.test(text)) return 2; + return event ? 1 : 0; +} diff --git a/server/providers/news/gdeltEvents.js b/server/providers/news/gdeltEvents.js new file mode 100644 index 0000000000..7afe5ed6d2 --- /dev/null +++ b/server/providers/news/gdeltEvents.js @@ -0,0 +1,546 @@ +// GDELT 2.0 events for the Conflicts section, from the 15-minute export +// files (data.gdeltproject.org, plain downloads; no key, and not the +// rate-limited search API). Each export is one zipped tab-separated table of +// machine-coded events, each placed by GDELT with a point and a place type. +// +// A story counts when GDELT coded physical violence in it (CAMEO roots 18 +// assault, 19 fight, 20 mass violence); its place is read from all its +// placed events (choosePlace). GDELT's actor fields are machine-coded and +// often wrong, so no report says who did what: a report is the story (its +// article, and the copies other outlets ran under the same address words). +// The events carry no headline: a story's title is its page title from the +// GKG export of the same quarter hour (read for the newest hours only, it +// runs to 6 MB), else the words of its address. All of it is rules over +// GDELT's own fields; nothing reads the articles. + +import { promisify } from 'node:util'; +import { inflateRaw } from 'node:zlib'; + +import { readResponseBytesCapped } from '../common/http.js'; +import { categorizeText, relevanceOf, severityByRules } from './categorize.js'; +import { UpstreamError, unescapeHtml, webLink } from './upstream.js'; + +const EXPORTS_URL = 'https://data.gdeltproject.org/gdeltv2/'; +const STEP_MS = 15 * 60_000; +// An events export runs to about 100 KB zipped and 500 KB unzipped; a GKG +// export to about 6 MB and 18 MB. Unzipped off the main thread. +const MAX_ZIP_BYTES = 8 * 1024 * 1024; +const MAX_TABLE_BYTES = 8 * 1024 * 1024; +const MAX_GKG_ZIP_BYTES = 32 * 1024 * 1024; +const MAX_GKG_TABLE_BYTES = 32 * 1024 * 1024; +const inflate = promisify(inflateRaw); +// The most words an address's words make a title of. +const MAX_ADDRESS_WORDS = 24; +const TIMEOUT_MS = 30_000; +const MAX_PLACES = 3; + +// Columns of the 2.0 events table (61). +const COL = { + id: 0, + eventCode: 26, + rootCode: 28, + quadClass: 29, + mentions: 31, + geoType: 51, + place: 52, + lat: 56, + lon: 57, + added: 59, + url: 60, +}; + +// CAMEO event codes as the News layer's categories, and as words for an +// article whose address carries none of its own. +const EVENTS = [ + // Aerial weapons, artillery and tanks, bombings. + [/^19[45]|^183/, 'strike', 'Strike reported'], + [/^186|^185/, 'casualties', 'Killing reported'], + [/^181/, 'humanitarian', 'Abduction reported'], + [/^20/, 'casualties', 'Mass violence reported'], + [/^19/, 'ground', 'Fighting reported'], + [/^18/, 'other', 'Violence reported'], +]; +const eventKind = (code) => + EVENTS.find(([pattern]) => pattern.test(code)) || EVENTS.at(-1); + +// GDELT's place types: 1 country, 2 US state, 3 US city, 4 world city, +// 5 world state. +const PRECISION = { + 1: 'country', + 2: 'region', + 3: 'city', + 4: 'city', + 5: 'region', +}; + +/** The export holding the events GDELT added in the 15 minutes before `ms`. */ +export function exportUrl(ms) { + const at = new Date(Math.floor(ms / STEP_MS) * STEP_MS); + const stamp = at.toISOString().replace(/[-:T]/g, '').slice(0, 14); + return `${EXPORTS_URL}${stamp}.export.CSV.zip`; +} + +/** An events export's quarter hour (ms), from its name, or NaN. */ +export function exportAt(url) { + const match = /(\d{4})(\d\d)(\d\d)(\d\d)(\d\d)00\.export\.CSV\.zip$/.exec( + url, + ); + return match + ? Date.UTC(match[1], match[2] - 1, match[3], match[4], match[5]) + : NaN; +} + +const LASTUPDATE_URL = `${EXPORTS_URL}lastupdate.txt`; + +/** + * The time of the newest events export GDELT lists as published, in ms, or + * null when its list cannot be read. Asking for one not listed yet would + * be answered 404, and GDELT's CDN keeps that 404 for an hour. + */ +export async function fetchLatestExport({ fetchImpl, signal } = {}) { + try { + const response = await fetchImpl(LASTUPDATE_URL, { + redirect: 'error', + signal: signal + ? AbortSignal.any([signal, AbortSignal.timeout(TIMEOUT_MS)]) + : AbortSignal.timeout(TIMEOUT_MS), + }); + if (!response.ok) { + await response.body?.cancel?.().catch?.(() => {}); + return null; + } + const text = new TextDecoder().decode( + await readResponseBytesCapped(response, 16 * 1024, signal), + ); + const at = exportAt( + /\S+\.export\.CSV\.zip/.exec(text)?.[0].replace(/^http:/, 'https:') || '', + ); + return Number.isFinite(at) ? at : null; + } catch { + return null; + } +} + +/** The GKG export of the same quarter hour as an events export. */ +export const gkgUrl = (eventsUrl) => + eventsUrl.replace(/\.export\.CSV\.zip$/, '.gkg.csv.zip'); + +/** The day's exports up to `now`, newest first. */ +export function exportsOfDay(now, hours = 24) { + const urls = []; + const last = Math.floor(now / STEP_MS) * STEP_MS; + for (let ms = last; ms > now - hours * 3_600_000; ms -= STEP_MS) + urls.push(exportUrl(ms)); + return urls; +} + +/** The one table inside an export's zip, as text, up to `maxBytes`. */ +export async function unzipExport(bytes, maxBytes = MAX_TABLE_BYTES) { + const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength); + const fail = () => { + throw new UpstreamError('GDELT export unreadable', { unreadable: true }); + }; + if (bytes.length < 30 || view.getUint32(0, true) !== 0x04034b50) fail(); + // The central directory has the sizes; a local header may leave them 0. + let eocd = -1; + for (let i = bytes.length - 22; i >= Math.max(0, bytes.length - 0x10015); i--) + if (view.getUint32(i, true) === 0x06054b50) { + eocd = i; + break; + } + if (eocd < 0) fail(); + const dir = view.getUint32(eocd + 16, true); + if (dir + 46 > bytes.length || view.getUint32(dir, true) !== 0x02014b50) + fail(); + const method = view.getUint16(dir + 10, true); + const compressed = view.getUint32(dir + 20, true); + const local = view.getUint32(dir + 42, true); + if (local + 30 > bytes.length || view.getUint32(local, true) !== 0x04034b50) + fail(); + const start = + local + + 30 + + view.getUint16(local + 26, true) + + view.getUint16(local + 28, true); + if (start + compressed > bytes.length) fail(); + const data = bytes.subarray(start, start + compressed); + try { + if (method === 0 && data.length > maxBytes) fail(); + const table = + method === 0 + ? data + : method === 8 + ? await inflate(data, { maxOutputLength: maxBytes }) + : fail(); + return new TextDecoder().decode(table); + } catch (error) { + if (error instanceof UpstreamError) throw error; + return fail(); + } +} + +/** + * An article's address as the reports carry it: https, an http one + * upgraded (GDELT keeps the address as it found it), else null. + */ +export const articleLink = (value) => + webLink(value) || webLink(String(value ?? '').replace(/^http:/, 'https:')); + +/** + * The placed events of an export's table, of the stories with physical + * violence in them: those events, and every other placed event of the same + * stories (they help place it). + */ +export function parseEvents(table) { + const all = []; + for (const line of table.split('\n')) { + const f = line.split('\t'); + if (f.length < 61) continue; + const violent = + f[COL.quadClass] === '4' && ['18', '19', '20'].includes(f[COL.rootCode]); + const precision = PRECISION[f[COL.geoType]]; + const lat = Number(f[COL.lat]); + const lon = Number(f[COL.lon]); + const url = articleLink(f[COL.url]); + const added = /^(\d{4})(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)$/.exec(f[COL.added]); + if ( + !precision || + !f[COL.lat] || + !f[COL.lon] || + !Number.isFinite(lat) || + !Number.isFinite(lon) || + Math.abs(lat) > 90 || + Math.abs(lon) > 180 || + (lat === 0 && lon === 0) || + !url || + !added + ) + continue; + all.push({ + id: f[COL.id], + code: f[COL.eventCode], + violent, + lat, + lon, + place: f[COL.place].trim() || null, + precision, + mentions: Math.max(1, Number(f[COL.mentions]) || 1), + addedAt: `${added[1]}-${added[2]}-${added[3]}T${added[4]}:${added[5]}:${added[6]}.000Z`, + url, + }); + } + const stories = new Set(all.filter((e) => e.violent).map(storyKey)); + return all.filter((e) => stories.has(storyKey(e))); +} + +/** + * The words of an article's address, when it is written in them + * ("three-children-die-in-peshawar-cylinder-exp"), as a sentence; else null. + */ +export function addressWords(url) { + let path; + try { + path = decodeURIComponent(new URL(url).pathname); + } catch { + return null; + } + const segment = path + .split('/') + .map((part) => part.replace(/\.(?:s?html?|php|aspx?)$/i, '')) + .filter((part) => /[-_]/.test(part)) + .sort((a, b) => b.length - a.length)[0]; + if (!segment) return null; + const words = segment.split(/[-_]+/).filter(Boolean); + const lettered = words.filter((word) => /^\p{L}+$/u.test(word)); + if (lettered.length < 4 || lettered.length < 0.7 * words.length) return null; + // Numbers stay ("killed nearly 500"); an id does not: a word of letters + // and digits, five digits or more, or four or more at either end. + const kept = words.filter( + (word, i) => + /^\p{L}+$/u.test(word) || + (/^\d{1,4}$/.test(word) && + !(word.length === 4 && (i === 0 || i === words.length - 1))), + ); + const text = kept.slice(0, MAX_ADDRESS_WORDS).join(' ').toLowerCase(); + return text.charAt(0).toUpperCase() + text.slice(1); +} + +/** + * Address words with the places the story is at written as names + * ("killed in amman" → "killed in Amman"), and "u s" as "US". + */ +export function withNames(words, places) { + let text = words.replace(/(? + String(place.place ?? '') + .split(',') + .map((part) => part.replace(/\(.*?\)/g, '').trim()) + .filter((part) => part.length > 2 && !/\(general\)/.test(part)), + ), + ); + for (const name of names) { + const pattern = new RegExp( + `(? 6) break; + title = rest; + } + title = title.trim().slice(0, 300); + return title.length >= 12 && title.split(/\s+/).length >= 3 ? title : null; +} + +/** + * GKG page titles by article address (as articleLink writes it), for the + * addresses in `wanted`. + */ +export function parseTitles(table, wanted) { + const titles = new Map(); + for (const line of table.split('\n')) { + const f = line.split('\t'); + const url = f[4] && articleLink(f[4]); + if (!url || !wanted.has(url)) continue; + const match = /(.*?)<\/PAGE_TITLE>/s.exec(f.at(-1) || ''); + const title = match && cleanTitle(match[1]); + if (title) titles.set(url, title); + } + return titles; +} + +/** + * The story an event belongs to: its article's address words, which the + * copies other outlets run share (an agency story), else its address. + */ +export function storyKey(event) { + return addressWords(event.url)?.toLowerCase() || event.url; +} + +const PLACE_WORD = (name) => + new RegExp( + `(? part.replace(/\(.*?\)/g, '').trim()) + .filter((part) => part.length > 2); + return [parts[0], parts.at(-1)].some( + (part) => part && PLACE_WORD(part).test(words.toLowerCase()), + ); +} + +/** + * A story's places, best first, from all its placed events. GDELT places + * an event at a bare country when the text only names a nationality ("a + * Sri Lankan embassy", an Australian outlet's own country), so a town or + * region wins over a country; of those, the ones the article's own words + * name; then the most mentioned. + */ +export function choosePlaces(events, words) { + const byPlace = new Map(); + for (const event of events) { + const key = `${event.lat},${event.lon}`; + const place = byPlace.get(key) || { ...event, mentions: 0 }; + place.mentions += event.mentions; + byPlace.set(key, place); + } + let places = [...byPlace.values()]; + const specific = places.filter((p) => p.precision !== 'country'); + if (specific.length) places = specific; + const named = places.filter((p) => namedIn(words, p.place)); + if (named.length) places = named; + return places.sort((a, b) => b.mentions - a.mentions).slice(0, MAX_PLACES); +} + +// The earlier of two events: by the time GDELT added it, then by its id. +const earlier = (a, b) => + b.addedAt < a.addedAt || + (b.addedAt === a.addedAt && Number(b.id) < Number(a.id)) + ? b + : a; + +/** + * One report per story (storyKey), its address and id the first copy's (an + * export adding a more-mentioned event keeps both), placed by choosePlaces, + * titled by a copy's page title (`titleOf`), else its address words, else + * its violent event. + */ +export function eventReports(events, { titleOf = () => null } = {}) { + const stories = new Map(); + for (const event of events) { + const key = storyKey(event); + const list = stories.get(key) || []; + list.push(event); + stories.set(key, list); + } + const reports = []; + for (const list of stories.values()) { + const violent = list + .filter((e) => e.violent !== false) + .sort( + (a, b) => b.mentions - a.mentions || a.addedAt.localeCompare(b.addedAt), + ); + if (!violent.length) continue; + const [lead] = violent; + const first = list.reduce(earlier); + const { url } = first; + const address = addressWords(url); + const places = choosePlaces(list, address); + const [, eventCategory, words] = eventKind(lead.code); + const page = [url, ...list.map((e) => e.url)] + .map((copy) => titleOf(copy)) + .find(Boolean); + const own = page || (address ? withNames(address, places) : null); + const title = own || eventTitle(words, places[0].place); + // The article's words decide whether it is conflict, as any headline's + // would: GDELT codes an election story as "fighting" too. GDELT's code + // names the kind only where the words read as conflict without naming + // one. A story with no words at all has GDELT's code alone to go by, + // which is not enough to list it under Conflicts: it is minor (kept + // for Local) until a page title comes in. + const read = own ? categorizeText({ title: own }) : null; + const tags = read?.tags || []; + const relevance = read + ? relevanceOf({ category: read.category, tags, title: own }) + : 'minor'; + const category = !read + ? eventCategory + : read.category !== 'other' + ? read.category + : relevance === 'minor' + ? 'other' + : eventCategory; + const publisher = new URL(url).hostname.replace(/^www\./, ''); + const geo = ({ lat, lon, place, precision }) => ({ + lat, + lon, + place, + precision, + confidence: precision === 'city' ? 0.6 : 0.3, + mappable: true, + method: 'source', + }); + reports.push({ + id: `gdelt-${first.id}`, + title, + url, + publisher, + source: { name: publisher, attribution: 'GDELT Project' }, + kind: 'gdelt', + side: 'unknown', + category, + relevance, + severity: Math.max( + 1, + severityByRules({ category, tags, title: own || '' }), + ), + severityBy: 'rules', + publishedAt: first.addedAt, + geo: geo(places[0]), + locations: places.slice(1).map(geo), + media: [], + mentions: list.reduce((sum, e) => sum + e.mentions, 0), + copies: new Set(list.map((e) => e.url)).size, + // A title of the event's words and its place, when the address had + // none: a renamed place renames it (eventTitle). + ...(own ? {} : { eventWords: words }), + titled: page ? 'page' : own ? 'address' : 'event', + }); + } + return reports; +} + +/** The title of a report without address words, at its (renamed) place. */ +export const eventTitle = (words, place) => + place ? `${words} in ${place}` : words; + +/** + * One export's table, or null while GDELT has not published it (GDELT + * lists the newest in lastupdate.txt; see fetchLatestExport). + */ +async function fetchTable(url, { fetchImpl, signal, maxBytes, tableBytes }) { + let response; + try { + response = await fetchImpl(url, { + redirect: 'error', + signal: signal + ? AbortSignal.any([signal, AbortSignal.timeout(TIMEOUT_MS)]) + : AbortSignal.timeout(TIMEOUT_MS), + }); + } catch { + throw new UpstreamError('GDELT exports unreachable'); + } + if (response.status === 404) { + await response.body?.cancel?.().catch?.(() => {}); + return null; + } + if (!response.ok) { + await response.body?.cancel?.().catch?.(() => {}); + throw new UpstreamError(`GDELT exports answered ${response.status}`, { + status: response.status, + }); + } + let bytes; + try { + bytes = await readResponseBytesCapped(response, maxBytes, signal); + } catch (error) { + // Over the cap stays over it; a read cut short may succeed again. + throw new UpstreamError('GDELT export unreadable', { + unreadable: error?.code === 'RESPONSE_TOO_LARGE', + }); + } + return unzipExport(bytes, tableBytes); +} + +/** One events export's events, or null while it is not published yet. */ +export async function fetchExport(url, { fetchImpl, signal } = {}) { + const table = await fetchTable(url, { + fetchImpl, + signal, + maxBytes: MAX_ZIP_BYTES, + tableBytes: MAX_TABLE_BYTES, + }); + return table === null ? null : parseEvents(table); +} + +/** + * The page titles a GKG export holds for the addresses in `wanted`, or null + * while it is not published yet. + */ +export async function fetchTitles(url, wanted, { fetchImpl, signal } = {}) { + const table = await fetchTable(url, { + fetchImpl, + signal, + maxBytes: MAX_GKG_ZIP_BYTES, + tableBytes: MAX_GKG_TABLE_BYTES, + }); + return table === null ? null : parseTitles(table, wanted); +} diff --git a/server/providers/news/gdeltEvents.test.mjs b/server/providers/news/gdeltEvents.test.mjs new file mode 100644 index 0000000000..fc986fce75 --- /dev/null +++ b/server/providers/news/gdeltEvents.test.mjs @@ -0,0 +1,407 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; + +import { + addressWords, + cleanTitle, + gkgUrl, + parseTitles, + withNames, + eventReports, + exportsOfDay, + exportUrl, + fetchExport, + parseEvents, + unzipExport, +} from './gdeltEvents.js'; +import { eventRow, gkgRow, zipTable } from './gdeltFixtures.mjs'; + +const ARTICLE = + 'https://www.wire.example/rubric-ato/3912-russian-drones-attack-kharkiv-overnight-three-killed.html'; + +test('the day is 96 exports, one each quarter hour, newest first', () => { + const now = Date.parse('2026-11-05T15:07:30Z'); + assert.equal( + exportUrl(now), + 'https://data.gdeltproject.org/gdeltv2/20261105150000.export.CSV.zip', + ); + const day = exportsOfDay(now); + assert.equal(day.length, 96); + assert.equal( + day[1], + 'https://data.gdeltproject.org/gdeltv2/20261105144500.export.CSV.zip', + ); + assert.equal( + day.at(-1), + 'https://data.gdeltproject.org/gdeltv2/20261104151500.export.CSV.zip', + ); +}); + +test('a story with physical violence is kept with all its placed events', () => { + const rows = [ + eventRow({ id: 1, code: '195', url: ARTICLE }), + eventRow({ id: 2, code: '183', url: ARTICLE }), + eventRow({ id: 3, code: '2001', url: ARTICLE }), + // Not physical, but of the same story: kept to place it by. + eventRow({ id: 4, code: '150', url: ARTICLE }), + eventRow({ id: 7, code: '190', quad: '3', url: ARTICLE }), + // A story with no violence in it is left out. + eventRow({ + id: 5, + code: '163', + url: 'https://x.example/talks-resume-in-geneva-today-officials', + }), + eventRow({ + id: 6, + code: '173', + url: 'https://x.example/talks-resume-in-geneva-today-officials', + }), + // Unplaced, at 0,0, or without a link. + eventRow({ id: 8, geoType: '0', url: ARTICLE }), + eventRow({ id: 9, lat: 0, lon: 0, url: ARTICLE }), + eventRow({ id: 10, url: 'javascript:alert(1)' }), + 'short\trow', + ]; + const events = parseEvents(rows.join('\n')); + assert.deepEqual( + events.map((e) => [e.id, e.violent]), + [ + ['1', true], + ['2', true], + ['3', true], + ['4', false], + ['7', false], + ], + ); + assert.equal(events[0].precision, 'city'); + assert.equal(events[0].addedAt, '2026-11-05T11:45:00.000Z'); +}); + +test("an article is one report, at its most-mentioned event, in its address's words", () => { + const events = parseEvents( + [ + eventRow({ id: 11, code: '195', mentions: 2, url: ARTICLE }), + eventRow({ + id: 12, + code: '190', + mentions: 9, + url: ARTICLE, + place: "Kupiansk, Kharkivs'ka Oblast', Ukraine", + lat: 49.71, + lon: 37.61, + }), + eventRow({ + id: 13, + code: '190', + geoType: '1', + place: 'Ukraine', + lat: 49, + lon: 32, + url: 'https://example.com/a/b/12345', + }), + ].join('\n'), + ); + const [drones, bare] = eventReports(events); + // The story's first event (by time, then id) names it. + assert.equal(drones.id, 'gdelt-11'); + // Its address words, with the place it is at written as a name. + assert.equal( + drones.title, + 'Russian drones attack Kharkiv overnight three killed', + ); + // Kupiansk has more mentions; the article's own words name Kharkiv. + assert.equal(drones.geo.place, "Kharkiv, Kharkivs'ka Oblast', Ukraine"); + assert.equal(drones.geo.precision, 'city'); + assert.equal(drones.locations.length, 0, 'Kupiansk is not named'); + assert.equal(drones.category, 'strike'); + assert.equal(drones.relevance, 'core'); + assert.equal(drones.severity, 2); + assert.equal(drones.publisher, 'wire.example'); + assert.equal(drones.source.attribution, 'GDELT Project'); + assert.equal(drones.side, 'unknown', 'no actor is said'); + // No words in the address: GDELT's coding alone, so minor (not listed + // under Conflicts), at least severity 1. + assert.equal(bare.title, 'Fighting reported in Ukraine'); + assert.equal(bare.category, 'ground'); + assert.equal(bare.relevance, 'minor'); + assert.equal(bare.severity, 1); + assert.equal(bare.geo.precision, 'country'); +}); + +test('an article GDELT codes as fighting whose words say otherwise stays out of Conflicts', () => { + const [report] = eventReports( + parseEvents( + eventRow({ + url: 'https://news.example.com/2026/11/05/city-council-approves-new-budget-for-schools', + id: 20, + }), + ), + ); + assert.equal(report.relevance, 'minor'); +}); + +test('address words need four lettered words, most of the address', () => { + assert.equal(addressWords('https://x.example/news/1234567'), null); + assert.equal(addressWords('https://x.example/a/lueop1pzfi'), null); + assert.equal( + addressWords('https://x.example/2026/11/05/a-b-1-2-3-4-5'), + null, + ); + assert.equal( + addressWords( + 'https://x.example/story/2638789/three-children-die-in-peshawar.html', + ), + 'Three children die in peshawar', + ); +}); + +test('an export is unzipped and read; one not published yet is null', async () => { + const zip = zipTable(eventRow({ id: 30, code: '193', url: ARTICLE })); + assert.deepEqual( + parseEvents(await unzipExport(zip)).map((e) => e.id), + ['30'], + ); + const served = await fetchExport('https://data.gdeltproject.org/x.zip', { + fetchImpl: async () => new Response(zip, { status: 200 }), + }); + assert.deepEqual( + served.map((e) => e.id), + ['30'], + ); + const later = await fetchExport('https://data.gdeltproject.org/y.zip', { + fetchImpl: async () => new Response('not found', { status: 404 }), + }); + assert.equal(later, null); + await assert.rejects( + fetchExport('https://data.gdeltproject.org/z.zip', { + fetchImpl: async () => new Response('busy', { status: 503 }), + }), + { name: 'UpstreamError' }, + ); + await assert.rejects(unzipExport(new Uint8Array([1, 2, 3])), { + name: 'UpstreamError', + }); +}); + +test("a nationality is no place: a town the article's words name wins over a bare country", () => { + const url = + 'https://www.sun.example/world/2026/11/05/security-officer-attacked-and-killed-near-sri-lankan-embassy-in-jordans-capital'; + const amman = { place: 'Amman, (JO11), Jordan', lat: 31.95, lon: 35.9333 }; + const cairo = { place: 'Cairo, Al Qahirah, Egypt', lat: 30.05, lon: 31.25 }; + const [report] = eventReports( + parseEvents( + [ + // "Sri Lankan embassy": GDELT's most-mentioned place, a bare country. + eventRow({ + id: 1, + mentions: 12, + geoType: '1', + place: 'Sri Lanka', + lat: 7, + lon: 81, + url, + }), + eventRow({ id: 2, mentions: 6, ...cairo, url }), + eventRow({ id: 3, mentions: 4, ...amman, url }), + eventRow({ id: 4, mentions: 2, ...amman, url }), + ].join('\n'), + ), + ); + assert.equal(report.geo.place, 'Amman, (JO11), Jordan'); + assert.equal(report.geo.precision, 'city'); +}); + +test('an agency story run by several outlets is one report, placed by all their events', () => { + const words = 'jordan-security-officer-killed-near-sri-lanka-embassy'; + const times = `https://www.times.example/story/9386807/${words}/`; + const chronicle = `https://www.chronicle.example/story/9386807/${words}/`; + const reports = eventReports( + parseEvents( + [ + // The outlet's own country, at country level, on its violent events. + eventRow({ + id: 1, + mentions: 6, + geoType: '1', + place: 'Australia', + lat: -25, + lon: 135, + url: times, + added: '20261105141500', + }), + // Its other events are placed in Jordan. + eventRow({ + id: 2, + code: '120', + quad: '3', + mentions: 8, + place: 'Karak, Jordan (general), Jordan', + lat: 31.18, + lon: 35.7, + url: times, + added: '20261105141500', + }), + eventRow({ + id: 3, + mentions: 4, + geoType: '1', + place: 'Syria', + lat: 35, + lon: 38, + url: chronicle, + added: '20261105151500', + }), + ].join('\n'), + ), + ); + assert.equal(reports.length, 1); + const [story] = reports; + assert.equal(story.copies, 2); + assert.equal(story.url, times, 'the first copy'); + assert.equal(story.publishedAt, '2026-11-05T14:15:00.000Z'); + assert.equal(story.geo.place, 'Karak, Jordan (general), Jordan'); +}); + +test("a story's title is a copy's page title from the GKG export", () => { + const titles = parseTitles( + [ + gkgRow( + ARTICLE, + 'Russian drones attack Kharkiv overnight, three killed | Wire', + ), + gkgRow('https://elsewhere.example/a', 'Not one of ours, not kept here'), + ].join('\n'), + new Set([ARTICLE]), + ); + assert.deepEqual( + [...titles], + [[ARTICLE, 'Russian drones attack Kharkiv overnight, three killed']], + ); + const [report] = eventReports( + parseEvents(eventRow({ id: 1, url: ARTICLE })), + { + titleOf: (url) => titles.get(url) || null, + }, + ); + assert.equal( + report.title, + 'Russian drones attack Kharkiv overnight, three killed', + ); + assert.equal(report.titled, 'page'); + assert.equal( + gkgUrl( + 'https://data.gdeltproject.org/gdeltv2/20261105141500.export.CSV.zip', + ), + 'https://data.gdeltproject.org/gdeltv2/20261105141500.gkg.csv.zip', + ); +}); + +test('a page title loses its site name, keeps its words, and must be a headline', () => { + assert.equal( + cleanTitle( + 'Yemen's president sacks ministers | Yemen | The Daily Example', + ), + "Yemen's president sacks ministers", + ); + assert.equal( + cleanTitle('Strike in Kharkiv - live updates - Wire Service'), + 'Strike in Kharkiv - live updates', + ); + // Too little before the dash: the dash is part of the headline. + assert.equal(cleanTitle('Iran - Wire Service'), 'Iran - Wire Service'); + assert.equal(cleanTitle('Home'), null); + assert.equal( + cleanTitle('Jordanian security officer killed in stabbing attack-Newswire'), + 'Jordanian security officer killed in stabbing attack', + ); + assert.equal( + cleanTitle('Five killed in Gaza, sources say-X'), + 'Five killed in Gaza, sources say', + ); + // A hyphenated name is no tag. + assert.equal( + cleanTitle('Talks resume with Jean-Pierre'), + 'Talks resume with Jean-Pierre', + ); +}); + +test('address words keep their numbers and name the places the story is at', () => { + const words = addressWords( + 'https://x.example/2026/11/05/jordan-says-u-s-envoy-met-officials-in-amman-after-500-killed', + ); + assert.equal( + words, + 'Jordan says u s envoy met officials in amman after 500 killed', + ); + assert.equal( + withNames(words, [{ place: 'Amman, (JO11), Jordan' }]), + 'Jordan says US envoy met officials in Amman after 500 killed', + ); +}); + +test("a story's id is its first event's: a later, more-mentioned event keeps it", () => { + const first = eventRow({ id: 40, mentions: 1, url: ARTICLE }); + const [before] = eventReports(parseEvents(first)); + const [after] = eventReports( + parseEvents( + [ + first, + eventRow({ + id: 41, + code: '195', + mentions: 30, + url: ARTICLE, + added: '20261105120000', + }), + ].join('\n'), + ), + ); + assert.equal(before.id, 'gdelt-40'); + assert.equal(after.id, 'gdelt-40'); + assert.equal(after.mentions, 31); +}); + +test('words that read as no conflict leave GDELT no kind to name', () => { + const [report] = eventReports( + parseEvents( + eventRow({ + id: 42, + code: '195', + url: 'https://x.example/2026/11/05/local-bakery-celebrates-fifty-years-of-baking', + }), + ), + ); + assert.equal(report.relevance, 'minor'); + assert.equal(report.category, 'other'); +}); + +test('a GKG address written with http is the https one the events carry', () => { + const plain = ARTICLE.replace('https:', 'http:'); + const [event] = parseEvents(eventRow({ id: 43, url: plain })); + assert.equal(event.url, ARTICLE); + const titles = parseTitles( + gkgRow(plain, 'Russian drones attack Kharkiv overnight, three killed'), + new Set([event.url]), + ); + assert.equal( + titles.get(ARTICLE), + 'Russian drones attack Kharkiv overnight, three killed', + ); +}); + +test('a corrupt or oversized export is an UpstreamError, never a RangeError', async () => { + const zip = zipTable(eventRow({ id: 44, url: ARTICLE })); + const view = new DataView(zip.buffer); + // The central directory's local header offset, pointing past the end. + const dir = view.getUint32(zip.length - 22 + 16, true); + const far = zip.slice(); + new DataView(far.buffer).setUint32(dir + 42, zip.length - 10, true); + await assert.rejects(unzipExport(far), { name: 'UpstreamError' }); + // The end record cut short. + await assert.rejects(unzipExport(zip.subarray(0, zip.length - 30)), { + name: 'UpstreamError', + }); + // Unzipped past the table's cap. + await assert.rejects(unzipExport(zip, 16), { name: 'UpstreamError' }); + assert.equal((await unzipExport(zip)).length > 16, true); +}); diff --git a/server/providers/news/gdeltFixtures.mjs b/server/providers/news/gdeltFixtures.mjs new file mode 100644 index 0000000000..08b947525d --- /dev/null +++ b/server/providers/news/gdeltFixtures.mjs @@ -0,0 +1,72 @@ +// Test fixtures: GDELT 2.0 export rows and their zip, as the export files +// carry them (61 tab-separated columns, one zipped table). +import { deflateRawSync } from 'node:zlib'; + +/** One events row; only the columns the reader looks at are filled. */ +export function eventRow({ + id, + code = '190', + quad = '4', + mentions = 1, + geoType = '4', + place = "Kharkiv, Kharkivs'ka Oblast', Ukraine", + lat = 49.9935, + lon = 36.2304, + added = '20261105114500', + url, +}) { + const f = new Array(61).fill(''); + f[0] = String(id); + f[26] = code; + f[28] = code.slice(0, 2); + f[29] = quad; + f[31] = String(mentions); + f[51] = geoType; + f[52] = place; + f[56] = String(lat); + f[57] = String(lon); + f[59] = added; + f[60] = url; + return f.join('\t'); +} + +/** One GKG 2.1 row: an article's address and its page title (27 columns). */ +export function gkgRow(url, title) { + const f = new Array(27).fill(''); + f[4] = url; + f[26] = `20261105114500${title}`; + return f.join('\t'); +} + +/** A single-entry zip of `text`, deflated, sizes in the central directory. */ +export function zipTable(text, name = 'table.export.CSV') { + const data = Buffer.from(text, 'utf8'); + const packed = deflateRawSync(data); + const nameBytes = Buffer.from(name); + const local = Buffer.alloc(30); + local.writeUInt32LE(0x04034b50, 0); + local.writeUInt16LE(20, 4); + local.writeUInt16LE(0x08, 6); // sizes follow the data (left 0 here) + local.writeUInt16LE(8, 8); + local.writeUInt16LE(nameBytes.length, 26); + const dir = Buffer.alloc(46); + dir.writeUInt32LE(0x02014b50, 0); + dir.writeUInt16LE(20, 4); + dir.writeUInt16LE(20, 6); + dir.writeUInt16LE(0x08, 8); + dir.writeUInt16LE(8, 10); + dir.writeUInt32LE(packed.length, 20); + dir.writeUInt32LE(data.length, 24); + dir.writeUInt16LE(nameBytes.length, 28); + dir.writeUInt32LE(0, 42); + const dirAt = local.length + nameBytes.length + packed.length; + const end = Buffer.alloc(22); + end.writeUInt32LE(0x06054b50, 0); + end.writeUInt16LE(1, 8); + end.writeUInt16LE(1, 10); + end.writeUInt32LE(dir.length + nameBytes.length, 12); + end.writeUInt32LE(dirAt, 16); + return new Uint8Array( + Buffer.concat([local, nameBytes, packed, dir, nameBytes, end]), + ); +} diff --git a/server/providers/news/keyed.js b/server/providers/news/keyed.js new file mode 100644 index 0000000000..574e44e5b3 --- /dev/null +++ b/server/providers/news/keyed.js @@ -0,0 +1,916 @@ +// The News layer's routes answered by Core itself, when no news server is +// configured (GEV_NEWS_ORIGIN). Conflicts: the day's GDELT events (no key; +// gdeltEvents.js), one report per article at GDELT's place for it, and with +// LIVEUAMAP_API_KEY Liveuamap's mapped items too. Local: World News API +// (WORLDNEWSAPI_KEY) by the country at the view centre; without its key the +// section answers 503 {error: 'no_key', key} and reads nothing, and past +// its day's reads (WORLDNEWSAPI_DAILY_READS) 503 {error: 'key_quota', key}. +// Conflicts' categories, relevance and severity are the shared rules +// (categorize.js); a country's own news keeps World News API's category. +// A news server may replace these readings with its own. +// +// A read that has something to serve is not waited for: what was read is +// served while it is read again. A section that cannot be read answers 502, +// never an empty list. +// +// The answers are the same /api/news contract a news server serves +// (src/layers/news/records.js reads both). + +import { + CATEGORY_ORDER, + categorizeText, + relevanceOf, + severityByRules, +} from './categorize.js'; +import { + areaAt, + countryAnchor, + countryByCode, + countryPolygons, +} from './areas.js'; +import { + eventReports, + fetchLatestExport, + eventTitle, + exportAt, + exportsOfDay, + fetchExport, + fetchTitles, + gkgUrl, + storyKey, +} from './gdeltEvents.js'; +import { fetchLiveuamap, fetchWorldNews, UpstreamError } from './upstream.js'; + +/** The keys each section reads with, by the key registry's id. */ +export const NEWS_KEYS = Object.freeze({ + liveuamap: 'LIVEUAMAP_API_KEY', + worldnewsapi: 'WORLDNEWSAPI_KEY', +}); + +/** The one hotspot: the world, its reports drawn as markers at every zoom. */ +export const WORLDWIDE_HOTSPOT = 'worldwide'; +const HOUR_MS = 3_600_000; +const DAY_MS = 24 * HOUR_MS; +// GDELT publishes an export every 15 minutes and lists the newest in +// lastupdate.txt: the day's missing ones up to it are read every 5 minutes, +// newest first, a dozen a read (the first day's 96 fill in over the next +// reads, a few seconds apart, while each reads something new). One listed +// but missing (404) an hour and a half after its time is taken as never +// published; one that fails GDELT_EXPORT_TRIES times (a try a round), or +// cannot be read at all, is given up on, so one bad file never holds the +// rest back. Only while GDELT itself answers is a file given up on. The first +// answer waits at most FIRST_ANSWER_MS for the first exports. +const GDELT_FRESH_MS = 5 * 60_000; +const GDELT_EXPORTS_PER_READ = 12; +const GDELT_PARALLEL = 4; +const GDELT_NEXT_MS = 2_000; +const GDELT_GONE_MS = 90 * 60_000; +const GDELT_EXPORT_TRIES = 3; +const MAX_GDELT_REPORTS = 5000; +// Events kept of one story, to place it by. +const MAX_STORY_EVENTS = 200; +// Page titles are read from the GKG exports of the newest three hours: one +// runs to 6 MB, so the day's 96 are not fetched. A file that fails is tried +// with the next reads, a few times. +const GDELT_TITLED_EXPORTS = 12; +const GKG_TRIES = 3; +const LIVE_FRESH_MS = 5 * 60_000; +const COUNTRY_FRESH_MS = 30 * 60_000; +// A failed read is not tried again for a minute; what was read before is +// served meanwhile, up to these ages (GDELT's: since an export last came in). +const RETRY_MS = 60_000; +// A read with nothing to serve yet is waited for at most this long, well under +// the browser's own 15 s: it goes on, and the next ask is served from it. +const FIRST_ANSWER_MS = 10_000; +const GDELT_STALE_MS = 2 * HOUR_MS; +const LIVE_STALE_MS = HOUR_MS; +// World News API's terms allow a cache of at most an hour, deleted after: +// a country's news is kept no longer, served or not (dropExpiredCountries). +const COUNTRY_STALE_MS = HOUR_MS; +const MAX_COUNTRIES = 64; +// World News API reads a UTC day, across all countries: each is about 1.5 +// of the free plan's 50 daily points. +const DEFAULT_DAILY_READS = 30; +const DEFAULT_LIMIT = 50; +const EMPTY_OUTLINE = Object.freeze({ + polygons: [], + borders: [], + disputed: [], + area: null, +}); +// A country's own news keeps World News API's category: the rules read +// fighting and crises, and in everyday news their words mislead ("advances +// in the rankings" is no ground fighting). Fighting in the country reaches +// Local as the Conflicts reports placed there. +const WORLD_NEWS_CATEGORY = { politics: 'political', business: 'economy' }; + +const list = (value) => + value ? new Set(value.split(',').filter(Boolean)) : null; + +/** The rules' reading of a Conflicts headline: category, relevance, severity. */ +function readTitle(title) { + const read = categorizeText({ title }); + const { category } = read; + return { + category, + relevance: relevanceOf({ + category, + tags: read.tags, + title, + dedicated: true, + }), + severity: severityByRules({ category, tags: read.tags, title }), + }; +} + +/** A one-report event carrying the report's picture, for its card. */ +function pictureEvent(id, report, image, video, publisher) { + return { + id, + status: 'single', + size: 1, + reports: 1, + severity: report.severity, + firstAt: report.publishedAt, + lastAt: report.publishedAt, + sides: [], + image: { url: image, publisher, ...(video ? { video } : {}) }, + }; +} + +const media = ({ image, video }) => + video ? ['video'] : image ? ['photo'] : []; + +/** A Liveuamap item as a report of the Conflicts section. */ +export function liveuamapReport(item) { + const id = `lum-${item.id}`; + const report = { + id, + hotspotId: WORLDWIDE_HOTSPOT, + hotspotIds: [WORLDWIDE_HOTSPOT], + title: item.title, + url: item.url, + publisher: 'Liveuamap', + source: { name: 'Liveuamap' }, + kind: 'liveuamap', + side: 'unknown', + // A conflict map: everything it posts is at least related. + ...readTitle(item.title), + severityBy: 'rules', + publishedAt: item.publishedAt, + geo: { + lat: item.lat, + lon: item.lon, + place: item.place, + precision: 'city', + confidence: 1, + mappable: true, + method: 'source', + }, + media: media(item), + }; + if (item.image) + report.event = pictureEvent( + id, + report, + item.image, + item.video, + 'Liveuamap', + ); + return report; +} + +/** + * A GDELT place named by its town and the area Natural Earth has there (a + * disputed area as itself, else the country): GDELT's own names follow old + * FIPS regions ("Bureij, Yerushalayim, Israel" for a camp in Gaza, "Abuja, + * …, Niger" for Nigeria's capital). Its point stays. A town a disputed + * area is named after ("Jerusalem" in East Jerusalem) lies on both sides + * of its line: GDELT puts the whole city at one point, so it is named as + * the town alone. + */ +export function gdeltPlace(geo) { + const area = areaAt(geo.lat, geo.lon); + const town = String(geo.place ?? '') + .split(',')[0] + .trim(); + const straddles = + area?.kind === 'disputed' && + town && + area.name.toLowerCase().includes(town.toLowerCase()); + const place = + geo.precision === 'country' && area?.kind === 'country' + ? area.name + : straddles + ? town + : [town, area?.name].filter(Boolean).join(', '); + return { ...geo, place: place || null }; +} + +/** + * A World News API article as a report of the Local section: placed in its + * publisher's country alone, at a point inside it. + */ +export function worldNewsReport(article, country) { + const id = `wna-${article.id}`; + const anchor = countryAnchor(country); + const report = { + id, + hotspotId: null, + hotspotIds: [], + title: article.title, + url: article.url, + publisher: article.publisher, + // World News API's free plan asks to be credited where its news shows. + source: { name: article.publisher, attribution: 'World News API' }, + kind: 'worldnewsapi', + side: 'unknown', + category: WORLD_NEWS_CATEGORY[article.category] || 'other', + // Local news: what the country's own outlets publish, with no severity + // of its own. + relevance: 'minor', + publishedAt: article.publishedAt, + geo: { + lat: anchor.lat, + lon: anchor.lon, + place: country.name, + precision: 'country', + confidence: 1, + mappable: true, + method: 'source', + }, + media: media(article), + }; + if (article.image) + report.event = pictureEvent( + id, + report, + article.image, + article.video, + article.publisher, + ); + return report; +} + +const AT = /^(-?\d{1,2}(?:\.\d{1,2})?),(-?\d{1,3}(?:\.\d{1,2})?)$/; +function point(value) { + const match = AT.exec(String(value ?? '')); + if (!match) return null; + const [lat, lon] = [Number(match[1]), Number(match[2])]; + return Math.abs(lat) <= 90 && Math.abs(lon) <= 180 ? { lat, lon } : null; +} + +const noKey = (key) => ({ status: 503, body: { error: 'no_key', key } }); +const rejectedKey = (key) => ({ + status: 503, + body: { error: 'key_rejected', key }, +}); +const spentKey = (key) => ({ status: 503, body: { error: 'key_quota', key } }); + +/** + * The keyed news routes. `answer(path, params)` resolves to `{status, body}` + * for `/hotspots`, `/feed` and `/outline`, whose queries the proxy has + * already checked against the client's allowlist. `later(run, ms)` runs + * the next GDELT read of a day still filling in (an unref'd timer). + * `firstAnswerMs` bounds the wait for a read with nothing to serve yet. + * @param {{env?: () => object, fetchImpl?: typeof fetch, now?: () => number, log?: (message: string) => void, later?: (run: () => void, ms: number) => void, firstAnswerMs?: number}} [options] + */ +export function createKeyedNews({ + env = () => process.env, + fetchImpl = (...args) => globalThis.fetch(...args), + now = () => Date.now(), + log = (message) => console.warn(message), + later = (run, ms) => setTimeout(run, ms).unref(), + firstAnswerMs = FIRST_ANSWER_MS, +} = {}) { + const keyOf = (id) => String(env()[NEWS_KEYS[id]] ?? '').trim(); + const inFlight = new Map(); + // GDELT's stories of the last day (their events and report, by + // storyKey), and the exports read. + const gdelt = { + stories: new Map(), + reports: new Map(), + // Page titles by article address, of the stories kept. + titles: new Map(), + read: new Set(), + // Exports still missing well after their time: not looked for again. + gone: new Set(), + // Failed reads of each export not read yet: `{tries, at}`. + failures: new Map(), + // Exports read among the newest whose GKG titles are not in yet, with + // the tries made: `{tries, triedAt}`. + untitled: new Map(), + titling: null, + // When a read last brought an export in. + readAt: null, + checkedAt: null, + failedAt: null, + }; + const live = new Map(); + const countries = new Map(); + // The keys refused so far, by section: logged once each. + const refused = new Set(); + // World News API reads of the UTC day; `spent` once it answered 402. + const budget = { day: null, reads: 0, spent: false, logged: false }; + // The areas (disputed area or country) of a placed Conflicts report's + // pins, its first and the others, looked up once. + const reportAreas = new WeakMap(); + const areasOf = (report) => { + if (!reportAreas.has(report)) + reportAreas.set( + report, + new Set( + [report.geo, ...(report.locations || [])] + .filter(Boolean) + .map((pin) => areaAt(pin.lat, pin.lon)?.key), + ), + ); + return reportAreas.get(report); + }; + + /** A failed read in the log: a refused key once, never the key itself. */ + function logFailure(section, what, key, error) { + // The day's reads spent: said once, by spendRead. + if (error.quota && error.status === null) return; + if (error.rejected) { + const id = `${section}\0${key}`; + if (refused.has(id)) return; + refused.add(id); + log( + `[news] ${NEWS_KEYS[section]} was refused (${error.status})${section === 'liveuamap' ? "; Conflicts are GDELT's alone" : ''}`, + ); + return; + } + log(`[news] ${what} read failed: ${error.message}`); + } + + /** + * A cached read (`{key, value, readAt, failedAt, error}`, kept in `store` + * under `id`): served as it is within `freshMs`; past that read again, + * and served meanwhile up to `staleMs`, so only a read with nothing to + * serve is waited for. One read at a time per key; a failed read is tried + * again after RETRY_MS. A new key drops what the old one read. + */ + async function cached( + store, + id, + { section, key, freshMs, staleMs, read, what }, + ) { + const at = now(); + const stored = store.get(id); + const prior = stored?.key === key ? stored : { key }; + if (prior.value && at - prior.readAt < freshMs) return prior; + if (prior.failedAt && at - prior.failedAt < RETRY_MS) return prior; + const flight = `${id}\0${key}`; + if (!inFlight.has(flight)) + inFlight.set( + flight, + read(key) + .then( + (value) => ({ key, value, readAt: now() }), + (error) => { + logFailure(section, what, key, error); + // What is held now: news deleted meanwhile stays deleted. + const held = store.get(id); + return { + ...(held?.key === key ? held : { key }), + failedAt: now(), + error, + }; + }, + ) + .then((entry) => { + // A read with a key replaced meanwhile is dropped. + if (keyOf(section) === key) keep(store, id, entry); + return entry; + }) + .finally(() => inFlight.delete(flight)), + ); + if (prior.value && at - prior.readAt < staleMs) return prior; + // Meanwhile a refused key stays refused; an older failure is not this one. + return firstAnswer(inFlight.get(flight), { + ...prior, + error: prior.error?.rejected ? prior.error : null, + }); + } + + /** An entry stored as the most recently used (the countries are capped). */ + function keep(store, id, entry) { + store.delete(id); + store.set(id, entry); + while (store.size > MAX_COUNTRIES) store.delete(store.keys().next().value); + } + + /** `read`, waited for at most firstAnswerMs; then `fallback`, as it goes on. */ + async function firstAnswer(read, fallback) { + let timer; + try { + return await Promise.race([ + read, + new Promise((resolve) => { + timer = setTimeout(() => resolve(fallback), firstAnswerMs); + timer.unref?.(); + }), + ]); + } finally { + clearTimeout(timer); + } + } + + /** An entry's reports while they may be served, else why there are none. */ + function served(entry, staleMs, id) { + if (entry.value && now() - entry.readAt < staleMs) + return { reports: entry.value, readAt: entry.readAt }; + if (entry.error?.rejected) return { rejected: id }; + if (entry.error?.quota) return { quota: id }; + return { failed: true }; + } + + async function liveuamapReports() { + const key = keyOf('liveuamap'); + if (!key) return { missing: 'liveuamap' }; + const entry = await cached(live, 'liveuamap', { + section: 'liveuamap', + key, + freshMs: LIVE_FRESH_MS, + staleMs: LIVE_STALE_MS, + what: 'liveuamap', + read: async (k) => + (await fetchLiveuamap({ key: k, fetchImpl, now: now() })) + .map(liveuamapReport) + .sort((a, b) => b.publishedAt.localeCompare(a.publishedAt)), + }); + return served(entry, LIVE_STALE_MS, 'liveuamap'); + } + + /** + * A story placed (again) from all its events and the titles in: an + * agency story run by several outlets is one report. + */ + function placeStory(key) { + const [report] = eventReports(gdelt.stories.get(key), { + titleOf: (url) => gdelt.titles.get(url) || null, + }); + if (!report) return; + const { eventWords, ...rest } = report; + const geo = gdeltPlace(report.geo); + gdelt.reports.set(key, { + ...rest, + ...(eventWords ? { title: eventTitle(eventWords, geo.place) } : {}), + hotspotId: WORLDWIDE_HOTSPOT, + hotspotIds: [WORLDWIDE_HOTSPOT], + geo, + locations: report.locations.map(gdeltPlace), + }); + } + + /** An export's events into their stories, each placed again. */ + function addEvents(events) { + const changed = new Set(); + for (const event of events) { + const key = storyKey(event); + const list = gdelt.stories.get(key) || []; + if (list.length < MAX_STORY_EVENTS) list.push(event); + gdelt.stories.set(key, list); + changed.add(key); + } + for (const key of changed) placeStory(key); + } + + /** The stories a GKG export titled, re-titled. */ + function addTitles(titles) { + for (const [key, list] of gdelt.stories) { + const titled = list.filter((event) => titles.has(event.url)); + if (!titled.length) continue; + for (const { url } of titled) gdelt.titles.set(url, titles.get(url)); + placeStory(key); + } + } + + /** + * The page titles of the newest exports read, from their GKG exports one + * at a time (each runs to 18 MB unzipped), in the background: no answer + * waits for them, and a story is re-titled as its title comes in. A file + * that fails or is not up yet only leaves address words: it is tried + * again with a later read while among the newest, up to GKG_TRIES times. + */ + function readTitles() { + gdelt.titling ??= (async () => { + let failed = null; + for (const [url, tried] of [...gdelt.untitled]) { + if (!gdelt.untitled.has(url)) continue; + if (tried.triedAt !== null && now() - tried.triedAt < GDELT_FRESH_MS) + continue; + tried.tries += 1; + tried.triedAt = now(); + const wanted = new Set(); + for (const list of gdelt.stories.values()) + for (const event of list) wanted.add(event.url); + let titles = null; + try { + titles = await fetchTitles(gkgUrl(url), wanted, { fetchImpl }); + } catch (error) { + failed ??= error; + } + if (titles || tried.tries >= GKG_TRIES) gdelt.untitled.delete(url); + if (titles?.size) addTitles(titles); + } + if (failed) log(`[news] gdelt titles read failed: ${failed.message}`); + })() + .catch((error) => log(`[news] gdelt titles failed: ${error.message}`)) + .finally(() => { + gdelt.titling = null; + }); + return gdelt.titling; + } + + /** + * Up to a dozen of the day's exports not read yet, newest first; whether + * to carry on at once (the round brought one in, and more are missing). + * One not up yet is looked for again; one still missing GDELT_GONE_MS + * after its time is not. + */ + async function readExports() { + const at = now(); + const day = exportsOfDay(at); + // Up to the newest GDELT lists; all of the day when its list fails. + const latest = await fetchLatestExport({ fetchImpl }); + const listed = (url) => latest === null || exportAt(url) <= latest; + const newest = new Set(day.slice(0, GDELT_TITLED_EXPORTS)); + const wanted = (url) => + listed(url) && !gdelt.read.has(url) && !gdelt.gone.has(url); + const missing = day.filter(wanted).slice(0, GDELT_EXPORTS_PER_READ); + let failed = null; + let added = 0; + const failing = []; + const unreadable = []; + const unpublished = []; + for (let i = 0; i < missing.length; i += GDELT_PARALLEL) + await Promise.all( + missing.slice(i, i + GDELT_PARALLEL).map(async (url) => { + let events; + try { + events = await fetchExport(url, { fetchImpl }); + } catch (error) { + failed = error; + (error.unreadable ? unreadable : failing).push(url); + return; + } + if (!events) { + if (at - exportAt(url) >= GDELT_GONE_MS) unpublished.push(url); + return; + } + // The events count now; the titles follow (readTitles). + gdelt.read.add(url); + gdelt.failures.delete(url); + added += 1; + gdelt.readAt = now(); + addEvents(events); + if (newest.has(url)) + gdelt.untitled.set(url, { tries: 0, triedAt: null }); + }), + ); + if (failed) log(`[news] gdelt read failed: ${failed.message}`); + // A file is blamed only while GDELT itself answers (its list read, or + // another export of the round read): then a 404 long after its time is + // never published, an unreadable file stays so, and a failing one gets a + // few tries, one a GDELT_FRESH_MS. With GDELT down, no file is blamed. + const answering = added > 0 || latest !== null; + if (answering) + for (const url of [...unpublished, ...unreadable]) gdelt.gone.add(url); + if (added) + for (const url of failing) { + const prior = gdelt.failures.get(url); + if (prior && now() - prior.at < GDELT_FRESH_MS) continue; + const tries = (prior?.tries || 0) + 1; + gdelt.failures.set(url, { tries, at: now() }); + if (tries >= GDELT_EXPORT_TRIES) gdelt.gone.add(url); + } + // Nothing read and a failure: tried again after RETRY_MS, not after + // GDELT_FRESH_MS. Something read: the round counts. + if (failed && !added) gdelt.failedAt = now(); + else { + gdelt.checkedAt = now(); + gdelt.failedAt = null; + } + // Only the day is kept, and titled while among the newest. + const kept = new Set(day); + for (const set of [gdelt.read, gdelt.gone]) + for (const url of set) if (!kept.has(url)) set.delete(url); + for (const url of gdelt.failures.keys()) + if (!kept.has(url)) gdelt.failures.delete(url); + for (const url of gdelt.untitled.keys()) + if (!newest.has(url)) gdelt.untitled.delete(url); + return ( + added > 0 && missing.length === GDELT_EXPORTS_PER_READ && day.some(wanted) + ); + } + + /** GDELT's reports of the last day, newest first, or `{failed}`. */ + async function gdeltReports() { + const at = now(); + const fresh = gdelt.checkedAt && at - gdelt.checkedAt < GDELT_FRESH_MS; + const resting = gdelt.failedAt && at - gdelt.failedAt < RETRY_MS; + if (!fresh && !resting && !inFlight.has('gdelt')) { + const round = readExports() + .then( + (more) => { + // More of the day to fill in: carry on shortly, without holding + // the answer. + if (!more) return; + gdelt.checkedAt = null; + later(() => void gdeltReports(), GDELT_NEXT_MS); + }, + (error) => { + log(`[news] gdelt read failed: ${error.message}`); + gdelt.failedAt = now(); + }, + ) + .finally(() => { + inFlight.delete('gdelt'); + void readTitles(); + }); + inFlight.set('gdelt', round); + } + // Only a read with nothing (recent) to serve is waited for: the + // newest exports' events, not their titles. + const current = () => + gdelt.readAt !== null && now() - gdelt.readAt < GDELT_STALE_MS; + // A slow GDELT must not outlast the browser's own timeout: what has come + // in by then is served. + if (!current() && inFlight.has('gdelt')) + await firstAnswer(inFlight.get('gdelt')); + if (!current()) return { failed: true }; + const dayAgo = new Date(now() - DAY_MS).toISOString(); + // Exports are read in parallel, so reports of one time arrive in any + // order: the most mentioned comes first, then by id. + const reports = [...gdelt.reports.values()] + .filter((r) => r.publishedAt >= dayAgo) + .sort( + (a, b) => + b.publishedAt.localeCompare(a.publishedAt) || + b.mentions - a.mentions || + a.id.localeCompare(b.id), + ) + .slice(0, MAX_GDELT_REPORTS); + if (reports.length !== gdelt.reports.size) { + const kept = new Set(reports); + for (const [key, report] of gdelt.reports) + if (!kept.has(report)) { + for (const event of gdelt.stories.get(key) || []) + gdelt.titles.delete(event.url); + gdelt.reports.delete(key); + gdelt.stories.delete(key); + } + } + return { reports, readAt: gdelt.readAt }; + } + + /** + * The Conflicts section's reports: GDELT's, with Liveuamap's when its key + * is set. Liveuamap failing (or refusing its key) leaves GDELT's. + */ + async function conflictReports() { + const [articles, items] = await Promise.all([ + gdeltReports(), + keyOf('liveuamap') ? liveuamapReports() : {}, + ]); + if (!articles.reports && !items.reports) return { failed: true }; + return { + reports: [...(articles.reports || []), ...(items.reports || [])].sort( + (a, b) => b.publishedAt.localeCompare(a.publishedAt), + ), + readAt: Math.max(articles.readAt || 0, items.readAt || 0), + }; + } + + const dailyReads = () => { + const raw = String(env().WORLDNEWSAPI_DAILY_READS ?? '').trim(); + const reads = raw ? Number(raw) : NaN; + return Number.isInteger(reads) && reads >= 0 ? reads : DEFAULT_DAILY_READS; + }; + + /** Whether a World News API read is left today (UTC); counts it if so. */ + function spendRead() { + const day = new Date(now()).toISOString().slice(0, 10); + if (budget.day !== day) + Object.assign(budget, { day, reads: 0, spent: false, logged: false }); + if (!budget.spent && budget.reads < dailyReads()) { + budget.reads += 1; + return true; + } + if (!budget.logged) + log( + "[news] World News API's reads for today are spent; Local reads again after 00:00 UTC", + ); + budget.logged = true; + return false; + } + + /** World News API's news an hour old is deleted, as its terms ask. */ + function dropExpiredCountries() { + for (const [code, entry] of countries) + if (entry.value && now() - entry.readAt >= COUNTRY_STALE_MS) { + const { value, readAt, ...rest } = entry; + countries.set(code, rest); + } + } + + async function countryReports(country) { + const key = keyOf('worldnewsapi'); + if (!key) return { missing: 'worldnewsapi' }; + const stored = countries.get(country.code); + if (stored) keep(countries, country.code, stored); + const entry = await cached(countries, country.code, { + section: 'worldnewsapi', + key, + freshMs: COUNTRY_FRESH_MS, + staleMs: COUNTRY_STALE_MS, + what: `worldnewsapi:${country.code}`, + read: async (k) => { + // Not asked: no status, unlike an answer. + if (!spendRead()) + throw new UpstreamError("World News API's reads for today spent", { + quota: true, + }); + const { day } = budget; + try { + const reports = ( + await fetchWorldNews({ + key: k, + country: country.code, + fetchImpl, + now: now(), + }) + ).map((article) => worldNewsReport(article, country)); + // Deleted an hour on, whether or not anything is asked then. + setTimeout(dropExpiredCountries, COUNTRY_STALE_MS + 1000).unref?.(); + return reports; + } catch (error) { + // Out of points: nothing more is asked today. + if (error.status === 402) budget.spent = true; + // Never reached (offline): no read of the day it was counted in. + if (error.unreached && budget.day === day && budget.reads > 0) + budget.reads -= 1; + throw error; + } + }, + }); + return served(entry, COUNTRY_STALE_MS, 'worldnewsapi'); + } + + const refusal = (read) => + read.missing + ? noKey(read.missing) + : read.rejected + ? rejectedKey(read.rejected) + : read.quota + ? spentKey(read.quota) + : read.failed + ? { status: 502, body: { error: 'news_upstream_error' } } + : null; + + async function hotspots(params) { + const read = await conflictReports(); + const refused = refusal(read); + if (refused) return refused; + const hours = Number(params.get('hours')) || 24; + const since = new Date(now() - hours * HOUR_MS).toISOString(); + // The reports Conflicts lists: a minor one is in no count. + const shown = read.reports.filter( + (r) => r.publishedAt >= since && r.relevance !== 'minor', + ); + return { + status: 200, + body: { + hotspots: [ + { + id: WORLDWIDE_HOTSPOT, + name: 'Worldwide', + kind: 'conflict', + catchAll: true, + bbox: [-180, -90, 180, 90], + parties: [], + developing: [], + counts: { + last24h: shown.length, + mapped24h: shown.filter((r) => r.geo).length, + prev24h: null, + }, + latestAt: shown[0]?.publishedAt ?? null, + }, + ], + categories: CATEGORY_ORDER, + ingest: { lastRunAt: new Date(read.readAt).toISOString() }, + windowHours: hours, + maxWindowHours: 24, + }, + }; + } + + /** Reports filtered, newest first, and paged by `before`. */ + function page(reports, params) { + const since = params.get('since'); + const before = params.get('before'); + const dayAgo = new Date(now() - DAY_MS).toISOString(); + const categories = list(params.get('category')); + const relevance = list(params.get('relevance')); + const hotspot = params.get('hotspot'); + const limit = Number(params.get('limit')) || DEFAULT_LIMIT; + const kept = reports.filter( + (r) => + (!hotspot || hotspot === 'all' || r.hotspotIds.includes(hotspot)) && + (!since || r.publishedAt >= since) && + (!before || r.publishedAt < before) && + (!params.has('today') || r.publishedAt >= dayAgo) && + (!params.has('geo') || r.geo) && + (!categories || categories.has(r.category)) && + (!relevance || relevance.has(r.relevance)), + ); + const shown = kept.slice(0, limit); + // A page ends between two times: the next asks for those `before` the + // last, and a GDELT export's reports all share its quarter hour. + while ( + shown.length < kept.length && + kept[shown.length].publishedAt === shown.at(-1).publishedAt + ) + shown.push(kept[shown.length]); + const events = params.has('events'); + return { + reports: events ? shown : shown.map(({ event, ...report }) => report), + nextBefore: kept.length > shown.length ? shown.at(-1).publishedAt : null, + }; + } + + async function feed(params) { + const at = params.has('at') ? point(params.get('at')) : null; + const area = at ? areaAt(at.lat, at.lon) : null; + if (!area) { + // Conflicts, or Local at sea (by distance, in the browser). + const read = await conflictReports(); + return refusal(read) || { status: 200, body: page(read.reports, params) }; + } + // Local in a country: its own outlets, with the Conflicts reports + // placed inside it (those failing leave the outlets'). In a disputed + // area no country's outlets speak for it: the Conflicts reports there + // alone, so their failing is the answer's. + const country = area.kind === 'country'; + const [national, conflicts] = await Promise.all([ + country ? countryReports(area.country) : { reports: [] }, + conflictReports(), + ]); + const refused = refusal(national) || (!country && refusal(conflicts)); + if (refused) return refused; + const inside = (conflicts.reports || []).filter((r) => + areasOf(r).has(area.key), + ); + const reports = [...national.reports, ...inside].sort((a, b) => + b.publishedAt.localeCompare(a.publishedAt), + ); + return { status: 200, body: page(reports, params) }; + } + + function outline(params) { + if (params.has('at')) { + const at = point(params.get('at')); + const area = at ? areaAt(at.lat, at.lon) : null; + if (!area) return { status: 200, body: EMPTY_OUTLINE }; + return { + status: 200, + body: { + ...EMPTY_OUTLINE, + polygons: + area.kind === 'country' + ? countryPolygons(area.country) + : area.polygons, + area: { + key: area.key, + name: area.name, + kind: area.kind, + country: area.code, + }, + }, + }; + } + // A developing situation's country; the world has no outline. + const country = countryByCode( + String(params.get('country') ?? '').slice(0, 2), + ); + return { + status: 200, + body: country + ? { ...EMPTY_OUTLINE, polygons: countryPolygons(country) } + : EMPTY_OUTLINE, + }; + } + + return { + async answer(path, params) { + dropExpiredCountries(); + if (path === '/hotspots') return hotspots(params); + if (path === '/feed') return feed(params); + if (path === '/outline') return outline(params); + return { status: 404, body: { error: 'not_found' } }; + }, + }; +} diff --git a/server/providers/news/keyed.test.mjs b/server/providers/news/keyed.test.mjs new file mode 100644 index 0000000000..7b836f4a85 --- /dev/null +++ b/server/providers/news/keyed.test.mjs @@ -0,0 +1,1301 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; + +import { + createKeyedNews, + gdeltPlace, + NEWS_KEYS, + WORLDWIDE_HOTSPOT, +} from './keyed.js'; +import { KEY_SETUP_KEYS } from '../../../src/keySetupCore.mjs'; +import { + normalizeFeedPayload, + normalizeHotspotsPayload, + normalizeOutlinePayload, +} from '../../../src/layers/news/records.js'; +import { inPolygons } from '../../../src/layers/news/model.js'; +import { areaAt, countryPolygons } from './areas.js'; +import { exportsOfDay } from './gdeltEvents.js'; +import { eventRow, gkgRow, zipTable } from './gdeltFixtures.mjs'; + +const NOW = Date.parse('2026-11-05T12:00:00Z'); +const seconds = (iso) => Date.parse(iso) / 1000; + +// Liveuamap's `a=mpts` answer, cut down: strings where it writes strings. +const LIVEUAMAP = { + success: true, + key: 'redacted', + venues: [ + { + id: 101, + name: 'Russian drone strike on Kharkiv kills 3, injures 12', + lat: '49.99350', + lng: '36.23040', + location: 'Kharkiv', + timestamp: seconds('2026-11-05T11:00:00Z'), + link: 'https://liveuamap.com/en/2026/5-november-kharkiv', + img_share: 'https://a.liveuamap.com/pics/101.jpg', + video: 'https://a.liveuamap.com/clips/101.mp4', + }, + { + id: 102, + name: 'Floods kill dozens in Amman', + lat: '31.95390', + lng: '35.91060', + location: 'Amman', + timestamp: seconds('2026-11-05T10:00:00Z'), + link: 'https://mideast.liveuamap.com/en/2026/5-november-amman', + img_share: '', + video: '', + }, + { + id: 103, + name: 'Officials in "Kherson" report shelling', + lat: '46.63540', + lng: '32.61690', + timestamp: seconds('2026-11-05T09:00:00Z'), + link: 'https://liveuamap.com/en/2026/5-november-kherson', + }, + // Without a point, a page or a headline: left out. + { id: 104, name: 'No point', timestamp: seconds('2026-11-05T09:00:00Z') }, + { + id: 105, + name: 'No page', + lat: '1', + lng: '1', + timestamp: seconds('2026-11-05T09:00:00Z'), + link: 'javascript:alert(1)', + }, + { + id: 106, + name: '', + lat: '1', + lng: '1', + timestamp: seconds('2026-11-05T09:00:00Z'), + link: 'https://liveuamap.com/x', + }, + ], +}; + +// World News API's search-news answer, cut down. +const WORLD_NEWS = { + offset: 0, + number: 100, + available: 3, + news: [ + { + id: 9001, + title: 'Visiting minister arrives in Amman for talks', + url: 'https://www.daily.example/en/minister-amman-talks', + image: 'https://www.daily.example/pics/visit.jpg', + publish_date: '2026-11-05 08:30:00', + language: 'en', + category: 'politics', + text: 'The whole article, never kept.', + }, + { + id: 9002, + title: 'Two oil firms advance subsalt exploration', + url: 'https://markets.example/economic/oil-firms-exploration', + publish_date: '2026-11-05 07:00:00', + language: 'ru', + category: 'business', + }, + // Sport is left out. + { + id: 9004, + title: 'Al-Faisaly win the cup final', + url: 'https://sport.example/cup', + publish_date: '2026-11-05 09:00:00', + category: 'sports', + }, + // The same story from another outlet is one. + { + id: 9003, + title: 'TWO OIL FIRMS ADVANCE SUBSALT EXPLORATION', + url: 'https://portal.test/oil-firms', + publish_date: '2026-11-05 06:00:00', + }, + ], +}; + +// GDELT's exports around NOW: the newest not published yet, two with +// events, the rest of the day empty. +const KHARKIV = + 'https://www.wire.example/rubric-ato/3912-russian-drones-attack-kharkiv-overnight-three-killed.html'; +const RED_SEA = + 'https://news.example.com/2026/11/05/houthis-claim-missile-attack-on-tanker-in-red-sea'; +const COUNCIL = + 'https://news.example.com/2026/11/05/city-council-approves-new-budget-for-schools'; +const BARE = 'https://news.example.com/a/b/123456'; +const exportName = (stamp) => + `https://data.gdeltproject.org/gdeltv2/${stamp}.export.CSV.zip`; +const EXPORTS = { + [exportName('20261105120000')]: 404, + [exportName('20261105114500')]: [ + eventRow({ + id: 1, + code: '195', + mentions: 3, + url: KHARKIV, + added: '20261105114500', + }), + eventRow({ + id: 2, + code: '195', + mentions: 8, + geoType: '1', + place: 'Yemen', + lat: 15.5, + lon: 47.5, + url: RED_SEA, + added: '20261105114500', + }), + eventRow({ id: 3, url: COUNCIL, added: '20261105114500' }), + ], + [exportName('20261105113000')]: [ + eventRow({ + id: 4, + geoType: '1', + place: 'Ukraine', + lat: 49, + lon: 32, + url: BARE, + added: '20261105113000', + }), + // An article already read is not a second report. + eventRow({ id: 5, code: '190', url: KHARKIV, added: '20261105113000' }), + ], +}; +const EMPTY = zipTable(''); +// The page titles of the newest export's quarter hour. +const GKG = { + [exportName('20261105114500').replace('.export.CSV.zip', '.gkg.csv.zip')]: [ + gkgRow( + KHARKIV, + 'Russian drones attack Kharkiv overnight, three killed - Wire', + ), + ], +}; + +const host = (call) => call.url.host; + +/** + * A fake upstream: answers by host, counts calls, records URLs and headers. + * An answer is a payload, a status, or a function giving a Response (one + * held open). `unlisted` is the status of an export not in `exports` (an + * empty table by default); `gkg` a status for every GKG export. + */ +function upstream(answers = {}) { + const calls = []; + const fetchImpl = async (url, init) => { + const href = String(url); + calls.push({ url: new URL(href), headers: init?.headers || {} }); + if (href.includes('gdeltproject.org')) { + if (typeof answers.gdelt === 'number') + return new Response('busy', { status: answers.gdelt }); + if (href.endsWith('/lastupdate.txt') && answers.lastupdate) + return new Response( + `95141 9197 http://data.gdeltproject.org/gdeltv2/${answers.lastupdate}.export.CSV.zip +`, + { status: 200 }, + ); + if (answers.corrupt?.includes(href)) + return new Response('not a zip at all', { status: 200 }); + if (answers.failing?.includes(href)) + return new Response('busy', { status: 503 }); + const gkg = href.endsWith('.gkg.csv.zip'); + const listed = answers.exports ?? EXPORTS; + const answer = gkg + ? (answers.gkg ?? GKG[href]) + : Object.hasOwn(listed, href) + ? listed[href] + : answers.unlisted; + if (typeof answer === 'number') + return new Response('', { status: answer }); + return new Response(answer ? zipTable(answer.join('\n')) : EMPTY, { + status: 200, + }); + } + const answer = href.includes('liveuamap.com') + ? (answers.liveuamap ?? LIVEUAMAP) + : (answers.worldnews ?? WORLD_NEWS); + if (typeof answer === 'function') return answer(); + if (typeof answer === 'number') + return new Response('{"message":"bad key ABC"}', { status: answer }); + return new Response(JSON.stringify(answer), { status: 200 }); + }; + return { calls, fetchImpl }; +} + +function keyed({ env, answers, clock = { now: NOW }, logs = [] } = {}) { + const fake = upstream(answers); + // The next GDELT reads, run by settle rather than on a timer. + const timers = []; + const news = createKeyedNews({ + env: () => + env ?? { LIVEUAMAP_API_KEY: 'live-key', WORLDNEWSAPI_KEY: 'wna-key' }, + fetchImpl: fake.fetchImpl, + now: () => clock.now, + log: (line) => logs.push(line), + later: (run) => timers.push(run), + }); + const ask = (path, query = '') => + news.answer(path, new URLSearchParams(query)); + /** + * Let the background reads finish (the rest of the day, the titles): + * until nothing is asked for a while, or a bounded number of turns. + */ + async function settle() { + let quiet = 0; + for (let turn = 0; turn < 200 && quiet < 5; turn++) { + const before = fake.calls.length; + for (let i = 0; i < 20; i++) await new Promise((r) => setImmediate(r)); + await new Promise((r) => setTimeout(r, 1)); + for (const run of timers.splice(0)) run(); + quiet = fake.calls.length === before ? quiet + 1 : 0; + } + } + return { ...fake, ask, clock, logs, settle, timers }; +} + +const CONFLICTS = + 'hotspot=all&geo=1&today=1&events=1&relevance=core,related&limit=50'; +const gdeltCalls = (calls) => + calls.filter( + (c) => + host(c) === 'data.gdeltproject.org' && + c.url.pathname.endsWith('.export.CSV.zip'), + ); +const gkgCalls = (calls) => + calls.filter((c) => c.url.pathname.endsWith('.gkg.csv.zip')); + +test('without any key Conflicts are the day of GDELT events, one worldwide hotspot', async () => { + const { ask, calls, settle } = keyed({ env: {} }); + const answer = await ask('/hotspots'); + assert.equal(answer.status, 200); + const payload = normalizeHotspotsPayload(answer.body); + assert.deepEqual( + payload.hotspots.map((h) => [h.id, h.catchAll]), + [[WORLDWIDE_HOTSPOT, true]], + ); + assert.equal(payload.hotspots[0].last24h, 2); + assert.equal(payload.hotspots[0].mapped24h, 2); + assert.equal(payload.maxWindowHours, 24); + // The newest dozen first; the rest of the day after, in the background. + assert.deepEqual( + gdeltCalls(calls) + .slice(0, 12) + .map((c) => String(c.url)), + exportsOfDay(NOW).slice(0, 12), + ); + assert.equal( + String(gdeltCalls(calls)[0].url), + 'https://data.gdeltproject.org/gdeltv2/20261105120000.export.CSV.zip', + ); + await settle(); + assert.ok(gdeltCalls(calls).length >= 96); + assert.ok(calls.every((c) => host(c) === 'data.gdeltproject.org')); + // Page titles only for the newest three hours (a GKG export is 6 MB). + assert.ok(gkgCalls(calls).length > 0 && gkgCalls(calls).length <= 12); +}); + +test('a GDELT article is a report at its place, in its words, credited to GDELT', async () => { + const { ask, settle } = keyed({ env: {} }); + // The first answer has the events in, titled by their address words; the + // page titles follow in the background. + const first = normalizeFeedPayload((await ask('/feed', CONFLICTS)).body); + assert.equal( + first.reports.find((r) => r.id === 'gdelt-5').title, + 'Russian drones attack Kharkiv overnight three killed', + ); + await settle(); + const { reports } = normalizeFeedPayload( + (await ask('/feed', CONFLICTS)).body, + ); + // Kharkiv's story was first seen in the earlier export: its first event + // names it. + assert.deepEqual( + reports.map((r) => r.id), + ['gdelt-2', 'gdelt-5'], + ); + const [redSea, kharkiv] = reports; + // Its page title, from the GKG export. + assert.equal( + kharkiv.title, + 'Russian drones attack Kharkiv overnight, three killed', + ); + assert.equal(kharkiv.category, 'strike'); + assert.equal(kharkiv.relevance, 'core'); + assert.equal(kharkiv.severity, 2); + assert.equal(kharkiv.publisher, 'wire.example'); + assert.equal(kharkiv.attribution, 'GDELT Project'); + assert.equal(kharkiv.kind, 'gdelt'); + assert.equal(kharkiv.side, 'unknown'); + assert.equal(kharkiv.geo.precision, 'city'); + assert.deepEqual( + kharkiv.pins.map(({ lat, lon }) => [lat, lon]), + [[49.9935, 36.2304]], + ); + assert.equal(redSea.geo.place, 'Yemen'); + assert.equal(redSea.geo.precision, 'country'); + // An address without words has GDELT's coding alone: minor, so not in + // Conflicts, until a page title says what it is. + const bare = (await ask('/feed', 'hotspot=all&today=1')).body.reports.find( + (r) => r.id === 'gdelt-4', + ); + assert.equal(bare.title, 'Fighting reported in Ukraine'); + assert.equal(bare.relevance, 'minor'); + // The council story GDELT coded as fighting is minor: not in Conflicts. + assert.ok(!reports.some((r) => r.url.includes('city-council'))); +}); + +test('with a Liveuamap key its mapped items join GDELT in the one hotspot', async () => { + const { ask, calls, settle } = keyed(); + const answer = await ask('/hotspots'); + assert.equal(answer.body.hotspots[0].counts.last24h, 5); + const live = calls.find((c) => host(c) === 'a.liveuamap.com').url; + assert.equal(live.searchParams.get('a'), 'mpts'); + assert.equal(live.searchParams.get('key'), 'live-key'); + assert.equal( + Number(live.searchParams.get('time')), + (NOW - 86_400_000) / 1000, + ); + const { reports } = normalizeFeedPayload( + (await ask('/feed', CONFLICTS)).body, + ); + const kharkiv = reports.find((r) => r.id === 'lum-101'); + assert.equal(kharkiv.category, 'strike'); + assert.equal(kharkiv.severity, 2); + assert.equal(kharkiv.publisher, 'Liveuamap'); + assert.deepEqual( + kharkiv.pins.map(({ lat, lon }) => [lat, lon]), + [[49.9935, 36.2304]], + ); + assert.equal( + kharkiv.event.image.video, + 'https://a.liveuamap.com/clips/101.mp4', + ); + assert.deepEqual(kharkiv.media, ['video']); + assert.equal( + reports.find((r) => r.id === 'lum-103').title, + 'Officials in "Kherson" report shelling', + ); + // Counts over a shorter window. + const short = await ask('/hotspots', 'hours=2'); + assert.equal(short.body.hotspots[0].counts.last24h, 4); + await settle(); +}); + +test('the Conflicts feed pages by time and filters by category and hotspot', async () => { + const { ask, settle } = keyed({ env: {} }); + // Every report of the day, the minor ones too. + const all = 'hotspot=all&today=1&events=1'; + // A page ends between two times: both of 11:45 come together, though + // the page asked for one. + const first = await ask('/feed', `${all}&limit=1`); + assert.deepEqual( + first.body.reports.map((r) => r.id), + ['gdelt-2', 'gdelt-3'], + ); + assert.equal(first.body.nextBefore, '2026-11-05T11:45:00.000Z'); + const next = await ask( + '/feed', + `${all}&limit=1&before=${first.body.nextBefore}`, + ); + assert.deepEqual( + next.body.reports.map((r) => r.id), + ['gdelt-5', 'gdelt-4'], + ); + assert.equal(next.body.nextBefore, null); + const strikes = await ask('/feed', 'hotspot=all&category=strike'); + assert.equal(strikes.body.reports.length, 2); + const elsewhere = await ask('/feed', 'hotspot=ua-ru-war'); + assert.deepEqual(elsewhere.body.reports, []); + await settle(); +}); + +test('an export not published yet is looked for again, and the day is kept a day', async () => { + const exports = { ...EXPORTS }; + const { ask, calls, clock, settle } = keyed({ + env: {}, + answers: { exports }, + }); + await ask('/hotspots'); + await settle(); + const read = gdeltCalls(calls).length; + // Within five minutes nothing is asked again. + clock.now += 2 * 60_000; + await ask('/hotspots'); + assert.equal(gdeltCalls(calls).length, read); + // The late export is published now, with a new article. + exports[exportName('20261105120000')] = [ + eventRow({ + id: 6, + code: '183', + url: 'https://news.example.com/2026/11/05/car-bomb-kills-five-in-mogadishu-market', + place: 'Mogadishu, Banaadir, Somalia', + lat: 2.04, + lon: 45.34, + added: '20261105120000', + }), + ]; + clock.now += 4 * 60_000; + await ask('/hotspots'); + await settle(); + const later = await ask('/hotspots'); + assert.equal(later.body.hotspots[0].counts.last24h, 3, 'added, not replaced'); + assert.equal( + gdeltCalls(calls) + .slice(read) + .filter((c) => String(c.url).includes('20261105120000')).length, + 1, + ); + // A day on, the old ones have aged out. + clock.now += 24 * 3_600_000; + const dayOn = await ask('/hotspots'); + await settle(); + assert.equal(dayOn.body.hotspots[0].counts.last24h, 0); +}); + +test('Local names the country at the point and outlines it, with no key', async () => { + const { ask, calls } = keyed({ env: {} }); + const answer = await ask('/outline', 'at=31.95,35.93&v=4'); + const outline = normalizeOutlinePayload(answer.body); + assert.deepEqual(outline.area, { + key: 'JO', + name: 'Jordan', + kind: 'country', + country: 'JO', + }); + assert.ok(outline.polygons.length > 0); + const sea = await ask('/outline', 'at=0,-30&v=4'); + assert.equal(normalizeOutlinePayload(sea.body).area, null); + const developing = await ask('/outline', 'country=UA&v=4'); + assert.ok(developing.body.polygons.length > 0); + assert.equal(calls.length, 0); +}); + +test("Local in a country is its outlets' everyday news, pinned inside it, plus the Conflicts reports there", async () => { + const { ask, calls } = keyed(); + const answer = await ask( + '/feed', + 'hotspot=all&geo=1&today=1&events=1&limit=40&at=31.95,35.93', + ); + assert.equal(answer.status, 200); + const search = calls.find((c) => host(c) === 'api.worldnewsapi.com'); + assert.equal(search.url.pathname, '/search-news'); + assert.equal(search.url.searchParams.get('source-country'), 'jo'); + assert.equal(search.url.searchParams.has('categories'), false); + assert.equal( + search.url.searchParams.get('earliest-publish-date'), + '2026-11-04 12:00:00', + ); + assert.equal(search.url.searchParams.has('api-key'), false); + assert.equal(search.headers['x-api-key'], 'wna-key'); + + const { reports } = normalizeFeedPayload(answer.body); + assert.deepEqual( + reports.map((r) => r.id), + ['lum-102', 'wna-9001', 'wna-9002'], + ); + const [, visit, exploration] = reports; + assert.equal(visit.category, 'political'); + assert.equal(visit.relevance, 'minor'); + assert.equal(visit.publisher, 'daily.example'); + assert.equal(visit.snippet, null, 'titles and links only'); + assert.equal(visit.geo.precision, 'country'); + assert.equal(visit.geo.place, 'Jordan'); + assert.equal(visit.event.image.publisher, 'daily.example'); + assert.equal(exploration.category, 'economy'); + + // The point each is pinned at lies in the area Local outlines. + const outline = normalizeOutlinePayload( + (await ask('/outline', 'at=31.95,35.93&v=4')).body, + ); + const { inPolygons } = await import('../../../src/layers/news/model.js'); + for (const report of reports) + assert.ok(inPolygons(outline.polygons, report.pins[0]), report.id); +}); + +test('a disputed area is named as itself: outlined alone, left out of the country around it, read from no country', async () => { + const { ask, calls, settle } = keyed(); + const crimea = normalizeOutlinePayload( + (await ask('/outline', 'at=44.95,34.1&v=4')).body, + ); + assert.deepEqual(crimea.area, { + key: 'disputed-crimea', + name: 'Crimea', + kind: 'disputed', + country: null, + }); + const { inPolygons } = await import('../../../src/layers/news/model.js'); + const russia = normalizeOutlinePayload( + (await ask('/outline', 'at=55.75,37.6&v=4')).body, + ); + assert.equal(russia.area.name, 'Russia'); + assert.equal(inPolygons(russia.polygons, { lat: 44.95, lon: 34.1 }), false); + assert.equal(inPolygons(russia.polygons, { lat: 55.75, lon: 37.6 }), true); + // Local in Crimea: no national outlets asked, the Conflicts reports there. + const local = await ask('/feed', 'hotspot=all&at=44.95,34.1'); + assert.equal(local.status, 200); + assert.ok(calls.every((c) => host(c) !== 'api.worldnewsapi.com')); + await settle(); +}); + +test("GDELT's places are named by their town and the area there, not its old regions", () => { + const named = (lat, lon, place, precision = 'city') => + gdeltPlace({ lat, lon, place, precision }).place; + assert.equal( + named(31.43, 34.39, 'Bureij, Yerushalayim, Israel'), + 'Bureij, Palestine', + ); + assert.equal( + named(9.07, 7.48, 'Abuja, Abuja Federal Capital Territory, Niger'), + 'Abuja, Nigeria', + ); + assert.equal( + named(44.95, 34.1, 'Simferopol, Crimea, Ukraine'), + 'Simferopol, Crimea', + ); + assert.equal(named(48.4, 31.2, 'Ukraine', 'country'), 'Ukraine'); +}); + +test("a country's news is read once per half hour and Liveuamap's feed once per five minutes", async () => { + const { ask, calls, clock } = keyed(); + const local = 'hotspot=all&at=31.95,35.93'; + await ask('/feed', local); + await ask('/feed', local); + await ask('/hotspots'); + const count = (name) => calls.filter((c) => host(c) === name).length; + assert.equal(count('api.worldnewsapi.com'), 1); + assert.equal(count('a.liveuamap.com'), 1); + clock.now += 6 * 60_000; + await ask('/feed', local); + assert.equal(count('api.worldnewsapi.com'), 1); + assert.equal(count('a.liveuamap.com'), 2); + clock.now += 25 * 60_000; + await ask('/feed', local); + assert.equal(count('api.worldnewsapi.com'), 2); +}); + +test('Local without its key says which key it needs and reads nothing', async () => { + const noLocal = keyed({ env: { LIVEUAMAP_API_KEY: 'live-key' } }); + assert.deepEqual(await noLocal.ask('/feed', 'at=31.95,35.93'), { + status: 503, + body: { error: 'no_key', key: 'worldnewsapi' }, + }); + assert.ok(noLocal.calls.every((c) => host(c) !== 'api.worldnewsapi.com')); + // At sea Local is the Conflicts reports by distance, keyless. + const sea = await keyed({ env: {} }).ask('/feed', 'hotspot=all&at=0,-30'); + assert.equal(sea.status, 200); +}); + +test('a refused Liveuamap key leaves GDELT; World News API refusing names its key', async () => { + const logs = []; + const refused = keyed({ answers: { liveuamap: 401, worldnews: 403 }, logs }); + const conflicts = await refused.ask('/hotspots'); + assert.equal(conflicts.status, 200); + assert.equal(conflicts.body.hotspots[0].counts.last24h, 2); + assert.deepEqual(await refused.ask('/feed', 'at=31.95,35.93'), { + status: 503, + body: { error: 'key_rejected', key: 'worldnewsapi' }, + }); + // A refused key is logged once, however often it is tried. + for (let i = 0; i < 3; i++) { + refused.clock.now += 61_000; + assert.equal((await refused.ask('/hotspots')).status, 200); + } + assert.equal( + logs.filter((line) => line.includes('LIVEUAMAP_API_KEY was refused')) + .length, + 1, + ); + assert.ok(gdeltCalls(refused.calls).length > 0); + assert.ok( + refused.calls.filter((c) => host(c) === 'a.liveuamap.com').length > 1, + ); + // Neither key nor answer body reaches the log. + assert.ok(logs.length > 0); + for (const line of logs) assert.doesNotMatch(line, /live-key|wna-key|ABC/); + await refused.settle(); +}); + +test('a failing GDELT is tried again after a minute, and what it read is kept', async () => { + const answers = { gdelt: 503 }; + const flaky = keyed({ env: {}, answers }); + assert.deepEqual(await flaky.ask('/hotspots'), { + status: 502, + body: { error: 'news_upstream_error' }, + }); + const tried = gdeltCalls(flaky.calls).length; + await flaky.ask('/hotspots'); + assert.equal(gdeltCalls(flaky.calls).length, tried, 'not within a minute'); + flaky.clock.now += 61_000; + delete answers.gdelt; + assert.equal((await flaky.ask('/hotspots')).status, 200); + await flaky.settle(); + answers.gdelt = 500; + flaky.clock.now += 6 * 60_000; + const kept = await flaky.ask('/hotspots'); + await flaky.settle(); + assert.equal(kept.status, 200); + assert.equal(kept.body.hotspots[0].counts.last24h, 2); +}); + +test('a new key drops what the old one read', async () => { + const env = { LIVEUAMAP_API_KEY: 'old', WORLDNEWSAPI_KEY: 'wna-key' }; + const { ask, calls } = keyed({ env }); + await ask('/hotspots'); + env.LIVEUAMAP_API_KEY = 'new'; + await ask('/hotspots'); + assert.deepEqual( + calls + .filter((c) => host(c) === 'a.liveuamap.com') + .map((c) => c.url.searchParams.get('key')), + ['old', 'new'], + ); +}); + +test('each key is one the key registry names', () => { + for (const [id, envVar] of Object.entries(NEWS_KEYS)) + assert.deepEqual( + KEY_SETUP_KEYS.find((entry) => entry.id === id)?.envVars, + [envVar], + id, + ); +}); + +const MINUTE = 60_000; +const count = (calls, name) => calls.filter((c) => host(c) === name).length; +const UPSTREAM_ERROR = { status: 502, body: { error: 'news_upstream_error' } }; +const KEY_QUOTA = { + status: 503, + body: { error: 'key_quota', key: 'worldnewsapi' }, +}; + +test('exports never published are given up on, not looked for back to back', async () => { + // One export of the day has events; GDELT answers 404 for every other. + const quarter = exportName('20261105114500'); + const { ask, calls, clock, settle } = keyed({ + env: {}, + // GDELT's list names the newest; every other export it answers 404. + answers: { + exports: { [quarter]: EXPORTS[quarter] }, + unlisted: 404, + lastupdate: '20261105120000', + }, + }); + assert.equal((await ask('/hotspots')).body.hotspots[0].counts.last24h, 2); + await settle(); + // A round that brings nothing in is the last until the next five minutes. + let seen = gdeltCalls(calls).length; + assert.ok(seen <= 2 * 12, `${seen} at first`); + const steps = []; + for (let i = 0; i < 20; i++) { + clock.now += 5 * MINUTE; + assert.equal((await ask('/hotspots')).status, 200); + await settle(); + steps.push(gdeltCalls(calls).length - seen); + seen = gdeltCalls(calls).length; + } + // One round each five minutes, until the day has been looked through + // once; then only the exports of the last hour and a half (GDELT's CDN + // keeps a 404 for an hour, so a late one may still come). + assert.ok( + steps.every((n) => n <= 12), + steps.join(), + ); + assert.ok( + steps.slice(-3).every((n) => n <= 7), + steps.join(), + ); + assert.ok(seen <= 2 * 12 + 20 * 12, String(seen)); +}); + +test('GDELT with no export read at all is a 502, not an empty Conflicts', async () => { + const { ask } = keyed({ env: {}, answers: { exports: {}, unlisted: 404 } }); + assert.deepEqual(await ask('/hotspots'), UPSTREAM_ERROR); + assert.deepEqual(await ask('/feed', CONFLICTS), UPSTREAM_ERROR); +}); + +test('GDELT failing for two hours answers 502; until then what it read is served', async () => { + const answers = {}; + const { ask, clock, settle } = keyed({ env: {}, answers }); + await ask('/hotspots'); + await settle(); + answers.gdelt = 503; + clock.now += 60 * MINUTE; + const hour = await ask('/hotspots'); + assert.equal(hour.status, 200); + assert.equal(hour.body.hotspots[0].counts.last24h, 2); + clock.now += 61 * MINUTE; + assert.deepEqual(await ask('/hotspots'), UPSTREAM_ERROR); + assert.deepEqual(await ask('/feed', CONFLICTS), UPSTREAM_ERROR); + await settle(); +}); + +test('a failed GKG read keeps the events, titled by their words, and is tried again', async () => { + const answers = { gkg: 500 }; + const { ask, calls, clock, logs, settle } = keyed({ env: {}, answers }); + const kharkiv = (answer) => + normalizeFeedPayload(answer.body).reports.find((r) => r.id === 'gdelt-5'); + await ask('/hotspots'); + await settle(); + const read = await ask('/feed', CONFLICTS); + assert.equal(read.status, 200); + assert.equal(read.body.reports.length, 2); + assert.equal( + kharkiv(read).title, + 'Russian drones attack Kharkiv overnight three killed', + ); + assert.ok(logs.some((line) => line.includes('titles read failed'))); + // Each GKG export once, not with every read of the day. + assert.equal(gkgCalls(calls).length, 11); + delete answers.gkg; + clock.now += 5 * MINUTE; + await ask('/hotspots'); + await settle(); + assert.equal( + kharkiv(await ask('/feed', CONFLICTS)).title, + 'Russian drones attack Kharkiv overnight, three killed', + ); +}); + +test('Local where only Conflicts reports speak answers 502 when they fail; in a country the outlets stay', async () => { + const { ask, calls } = keyed({ answers: { gdelt: 503, liveuamap: 500 } }); + // Crimea, and Somaliland (a territory without a code). + assert.deepEqual( + await ask('/feed', 'hotspot=all&at=44.95,34.1'), + UPSTREAM_ERROR, + ); + assert.deepEqual( + await ask('/feed', 'hotspot=all&at=9.56,44.06'), + UPSTREAM_ERROR, + ); + assert.equal(count(calls, 'api.worldnewsapi.com'), 0); + const jordan = await ask('/feed', 'hotspot=all&at=31.95,35.93'); + assert.equal(jordan.status, 200); + assert.deepEqual( + jordan.body.reports.map((r) => r.id), + ['wna-9001', 'wna-9002'], + ); +}); + +test('a territory without a code is named as itself, not read as sea', async () => { + const { ask, calls, settle } = keyed(); + for (const [at, key, name] of [ + ['9.56,44.06', 'disputed-somaliland', 'Somaliland'], + ['35.12,33.94', 'disputed-northern-cyprus', 'Northern Cyprus'], + ]) { + const outline = normalizeOutlinePayload( + (await ask('/outline', `at=${at}&v=4`)).body, + ); + assert.deepEqual(outline.area, { + key, + name, + kind: 'disputed', + country: null, + }); + assert.ok(outline.polygons.length > 0); + } + assert.equal( + gdeltPlace({ + lat: 9.56, + lon: 44.06, + place: 'Hargeysa, Somalia', + precision: 'city', + }).place, + 'Hargeysa, Somaliland', + ); + const local = await ask('/feed', 'hotspot=all&at=9.56,44.06'); + assert.equal(local.status, 200); + assert.equal(count(calls, 'api.worldnewsapi.com'), 0); + await settle(); +}); + +test('a stale Liveuamap or World News API read is served while it is read again', async () => { + const answers = {}; + const { ask, calls, clock, settle } = keyed({ answers }); + const local = 'hotspot=all&at=31.95,35.93'; + const ids = (answer) => answer.body.reports.map((r) => r.id); + assert.deepEqual(ids(await ask('/feed', local)), [ + 'lum-102', + 'wna-9001', + 'wna-9002', + ]); + // Both read again, and held open: the answer does not wait for them. + let release; + const held = new Promise((resolve) => { + release = resolve; + }); + const later = (payload) => () => + held.then(() => new Response(JSON.stringify(payload), { status: 200 })); + answers.liveuamap = later({ venues: [] }); + answers.worldnews = later({ news: [] }); + clock.now += 31 * MINUTE; + const served = await ask('/feed', local); + assert.equal(served.status, 200); + assert.deepEqual(ids(served), ['lum-102', 'wna-9001', 'wna-9002']); + assert.equal(count(calls, 'a.liveuamap.com'), 2); + assert.equal(count(calls, 'api.worldnewsapi.com'), 2); + // Once read, the new answers are served. + release(); + await settle(); + assert.deepEqual(ids(await ask('/feed', local)), []); + // A country not read before is waited for. + answers.worldnews = WORLD_NEWS; + assert.equal( + (await ask('/feed', 'hotspot=all&at=48.85,2.35')).body.reports.length, + 2, + ); +}); + +test('a read in flight with a replaced key is not the answer for the new one', async () => { + let release; + const held = new Promise((resolve) => { + release = resolve; + }); + const env = { LIVEUAMAP_API_KEY: 'old' }; + const answers = { + liveuamap: () => + held.then(() => new Response(JSON.stringify({ venues: [] }))), + }; + const { ask, calls, settle } = keyed({ env, answers }); + const before = ask('/hotspots'); + env.LIVEUAMAP_API_KEY = 'new'; + delete answers.liveuamap; + const after = await ask('/hotspots'); + assert.equal(after.body.hotspots[0].counts.last24h, 5); + assert.deepEqual( + calls + .filter((c) => host(c) === 'a.liveuamap.com') + .map((c) => c.url.searchParams.get('key')), + ['old', 'new'], + ); + release(); + await before; + // The old key's late answer does not replace the new one's. + assert.equal((await ask('/hotspots')).body.hotspots[0].counts.last24h, 5); + await settle(); +}); + +test("World News API's reads are a daily budget: spent, Local says key_quota and serves what it read", async () => { + const { ask, calls, clock, logs, settle } = keyed({ + env: { WORLDNEWSAPI_KEY: 'wna-key', WORLDNEWSAPI_DAILY_READS: '2' }, + }); + const at = (point) => ask('/feed', `hotspot=all&at=${point}`); + assert.equal((await at('31.95,35.93')).status, 200); + assert.equal((await at('48.85,2.35')).status, 200); + // Germany would be the third read today. + assert.deepEqual(await at('52.52,13.4'), KEY_QUOTA); + assert.equal(count(calls, 'api.worldnewsapi.com'), 2); + // Jordan, read earlier, is served from what was read. + clock.now += 31 * MINUTE; + const kept = await at('31.95,35.93'); + assert.equal(kept.status, 200); + assert.equal(kept.body.reports.length, 2); + assert.equal(count(calls, 'api.worldnewsapi.com'), 2); + assert.equal( + logs.filter((line) => line.includes('reads for today are spent')).length, + 1, + ); + // A new UTC day has its own reads. + clock.now = Date.parse('2026-11-06T00:30:00Z'); + assert.equal((await at('52.52,13.4')).status, 200); + assert.equal(count(calls, 'api.worldnewsapi.com'), 3); + await settle(); +}); + +test('World News API answering 402 is key_quota, and nothing more is asked today; a 429 is no quota', async () => { + const paid = keyed({ answers: { worldnews: 402 } }); + assert.deepEqual(await paid.ask('/feed', 'at=31.95,35.93'), KEY_QUOTA); + paid.clock.now += 2 * MINUTE; + assert.deepEqual(await paid.ask('/feed', 'at=48.85,2.35'), KEY_QUOTA); + assert.equal(count(paid.calls, 'api.worldnewsapi.com'), 1); + // A 429 is its per-second limit: an ordinary failure, tried again soon. + const busy = keyed({ answers: { worldnews: 429 } }); + assert.deepEqual(await busy.ask('/feed', 'at=31.95,35.93'), UPSTREAM_ERROR); + await paid.settle(); + await busy.settle(); +}); + +test('one unreadable export is given up on and never holds the rest back', async () => { + const bad = exportName('20261105114500'); + const { ask, calls, clock, settle } = keyed({ + env: {}, + answers: { corrupt: [bad] }, + }); + // The other export's stories are served, from the first answer on (its + // copy of the Kharkiv story among them). + const first = await ask('/hotspots'); + assert.equal(first.status, 200); + assert.equal(first.body.hotspots[0].counts.last24h, 1); + await settle(); + clock.now += 6 * MINUTE; + assert.equal((await ask('/hotspots')).status, 200); + await settle(); + const asked = gdeltCalls(calls).filter((c) => String(c.url) === bad).length; + assert.equal(asked, 1, 'an unreadable file is not fetched again'); +}); + +test('no export later than the newest GDELT lists is asked for (its CDN keeps a 404 an hour)', async () => { + const { ask, calls, settle } = keyed({ + env: {}, + answers: { lastupdate: '20261105114500' }, + }); + assert.equal((await ask('/hotspots')).status, 200); + await settle(); + assert.ok( + !gdeltCalls(calls).some( + (c) => String(c.url) === exportName('20261105120000'), + ), + ); + assert.ok( + gdeltCalls(calls).some( + (c) => String(c.url) === exportName('20261105114500'), + ), + ); +}); + +test('a town a disputed area is named after is named as the town alone', () => { + assert.equal( + gdeltPlace({ + lat: 31.7667, + lon: 35.2333, + place: 'Jerusalem, Israel (general), Israel', + precision: 'city', + }).place, + 'Jerusalem', + ); +}); + +test('World News API is credited on each of its reports', async () => { + const { ask, settle } = keyed(); + const { reports } = normalizeFeedPayload( + (await ask('/feed', 'hotspot=all&at=31.95,35.93')).body, + ); + const national = reports.filter((r) => r.kind === 'worldnewsapi'); + assert.ok(national.length > 0); + for (const r of national) assert.equal(r.attribution, 'World News API'); + await settle(); +}); + +test('GDELT down for a few minutes gives up on no export: they are all read once it is back', async () => { + const answers = { gdelt: 503 }; + const { ask, calls, clock, settle } = keyed({ env: {}, answers }); + for (let i = 0; i < 4; i++) { + await ask('/hotspots'); + await settle(); + clock.now += 61_000; + } + delete answers.gdelt; + clock.now += 5 * MINUTE; + const back = await ask('/hotspots'); + await settle(); + assert.equal(back.status, 200); + assert.equal(back.body.hotspots[0].counts.last24h, 2); + assert.ok( + gdeltCalls(calls).some( + (c) => String(c.url) === exportName('20261105114500'), + ), + ); +}); + +test('a GDELT outage answering 404, its list down too, gives up on no export', async () => { + const answers = { exports: {}, unlisted: 404 }; + const { ask, clock, settle } = keyed({ env: {}, answers }); + // Long enough for the stories' exports to be 90 minutes old. + for (let i = 0; i < 20; i++) { + await ask('/hotspots'); + await settle(); + clock.now += 5 * MINUTE; + } + delete answers.exports; + delete answers.unlisted; + for (let i = 0; i < 3; i++) { + clock.now += 5 * MINUTE; + await ask('/hotspots'); + await settle(); + } + const back = await ask('/hotspots'); + assert.equal(back.status, 200); + assert.equal(back.body.hotspots[0].counts.last24h, 2); +}); + +test('a host answering junk for every file gives up on none of them', async () => { + const answers = { + corrupt: [exportName('20261105114500'), exportName('20261105113000')], + exports: {}, + unlisted: 404, + }; + const { ask, clock, settle } = keyed({ env: {}, answers }); + await ask('/hotspots'); + await settle(); + answers.corrupt = []; + delete answers.exports; + delete answers.unlisted; + clock.now += 6 * MINUTE; + await ask('/hotspots'); + await settle(); + const back = await ask('/hotspots'); + assert.equal(back.body.hotspots[0].counts.last24h, 2); +}); + +test('a failing file gets one strike a round, not three within seconds', async () => { + const flaky = exportName('20261105114500'); + const answers = { failing: [flaky] }; + const { ask, calls, clock, settle } = keyed({ env: {}, answers }); + // The startup fill runs several rounds a few seconds apart. + await ask('/hotspots'); + await settle(); + // GDELT answers again for it before three rounds five minutes apart. + answers.failing = []; + clock.now += 6 * MINUTE; + await ask('/hotspots'); + await settle(); + const back = await ask('/hotspots'); + assert.equal(back.body.hotspots[0].counts.last24h, 2); + assert.ok( + gdeltCalls(calls).filter((c) => String(c.url) === flaky).length >= 2, + ); +}); + +test("a country's own news keeps World News API's category and no severity, whatever its words", async () => { + const { worldNewsReport } = await import('./keyed.js'); + const { countryByCode } = await import('./areas.js'); + const country = countryByCode('JO'); + const read = (title, category) => + worldNewsReport( + { + id: 1, + title, + url: 'https://times.example/x', + publisher: 'times.example', + publishedAt: '2026-11-05T08:00:00.000Z', + category, + }, + country, + ); + const rankings = read( + 'Jordan Advances in Global Digital Rankings as AI Infrastructure Expands', + 'technology', + ); + assert.equal(rankings.category, 'other'); + assert.equal(rankings.severity, undefined); + assert.equal( + read('Startup advances to the next funding round', 'business').category, + 'economy', + ); + assert.equal(read('King visits Amman', 'politics').category, 'political'); + assert.equal(read('Parliament session opens', null).category, 'other'); +}); + +test( + 'a first read slower than the browser waits answers unavailable, and the next ask is served from it', + { timeout: 5_000 }, + async () => { + const fake = upstream(); + let release; + const held = new Promise((resolve) => { + release = resolve; + }); + const news = createKeyedNews({ + env: () => ({ WORLDNEWSAPI_KEY: 'wna-key' }), + fetchImpl: async (url, init) => { + if (new URL(url).host === 'api.worldnewsapi.com') await held; + return fake.fetchImpl(url, init); + }, + now: () => NOW, + log: () => {}, + later: () => {}, + firstAnswerMs: 20, + }); + const local = () => + news.answer('/feed', new URLSearchParams('hotspot=all&at=31.95,35.93')); + assert.deepEqual(await local(), UPSTREAM_ERROR); + // The read went on, and is not asked again. + release(); + await new Promise((resolve) => setTimeout(resolve, 5)); + const served = await local(); + assert.equal(served.status, 200); + assert.deepEqual( + served.body.reports.map((r) => r.id), + ['wna-9001', 'wna-9002'], + ); + assert.equal(count(fake.calls, 'api.worldnewsapi.com'), 1); + }, +); + +test( + 'a first GDELT read slower than the browser waits answers unavailable, and the next is served from it', + { timeout: 5_000 }, + async () => { + const fake = upstream(); + let release; + const held = new Promise((resolve) => { + release = resolve; + }); + const news = createKeyedNews({ + env: () => ({}), + fetchImpl: async (url, init) => { + if (new URL(url).host === 'data.gdeltproject.org') await held; + return fake.fetchImpl(url, init); + }, + now: () => NOW, + log: () => {}, + later: () => {}, + firstAnswerMs: 20, + }); + const hotspots = () => news.answer('/hotspots', new URLSearchParams()); + assert.deepEqual(await hotspots(), UPSTREAM_ERROR); + release(); + await new Promise((resolve) => setTimeout(resolve, 20)); + assert.equal((await hotspots()).status, 200); + }, +); + +test( + 'a refused key stays refused while its next read is slow', + { timeout: 5_000 }, + async () => { + let release; + const held = new Promise((resolve) => { + release = resolve; + }); + let reads = 0; + const clock = { now: NOW }; + const fake = upstream({ + worldnews: async () => { + reads++; + if (reads > 1) await held; + return new Response('{"message":"bad key"}', { status: 401 }); + }, + }); + const news = createKeyedNews({ + env: () => ({ WORLDNEWSAPI_KEY: 'wna-key' }), + fetchImpl: fake.fetchImpl, + now: () => clock.now, + log: () => {}, + later: () => {}, + firstAnswerMs: 20, + }); + const local = () => + news.answer('/feed', new URLSearchParams('hotspot=all&at=31.95,35.93')); + const refused = { + status: 503, + body: { error: 'key_rejected', key: 'worldnewsapi' }, + }; + assert.deepEqual(await local(), refused); + // Past the retry wait it is read again, slowly: still refused meanwhile. + clock.now += 61_000; + assert.deepEqual(await local(), refused); + assert.equal(reads, 2); + release(); + }, +); + +test("World News API's news is kept an hour at most, also while it cannot be read again", async () => { + const answers = {}; + const { ask, clock, settle } = keyed({ answers }); + const local = 'hotspot=all&at=31.95,35.93'; + const own = (answer) => + answer.body.reports.filter((r) => r.id.startsWith('wna-')).length; + assert.equal(own(await ask('/feed', local)), 2); + // Its terms: a cache of at most an hour, then deleted. + answers.worldnews = 500; + clock.now += 59 * MINUTE; + assert.equal(own(await ask('/feed', local)), 2); + clock.now += 2 * MINUTE; + assert.deepEqual(await ask('/feed', local), UPSTREAM_ERROR); + await settle(); +}); + +test('a World News API read that never reached it is not counted against the day', async () => { + const answers = { + worldnews: () => { + throw new TypeError('fetch failed'); + }, + }; + const { ask, clock, settle } = keyed({ + env: { WORLDNEWSAPI_KEY: 'wna-key', WORLDNEWSAPI_DAILY_READS: '2' }, + answers, + }); + const paris = () => ask('/feed', 'hotspot=all&at=48.85,2.35'); + for (let i = 0; i < 3; i++) { + assert.deepEqual(await paris(), UPSTREAM_ERROR); + clock.now += 2 * MINUTE; + } + // Back online: the day's reads are all still there. + answers.worldnews = WORLD_NEWS; + assert.equal((await paris()).status, 200); + // An answer, even a failing one, is a read, and so is a request that + // timed out, which it may have read: two of them spend the day. + answers.worldnews = () => { + throw new DOMException('timed out', 'TimeoutError'); + }; + const berlin = () => ask('/feed', 'hotspot=all&at=52.52,13.4'); + assert.deepEqual(await berlin(), UPSTREAM_ERROR); + clock.now += 2 * MINUTE; + assert.deepEqual(await berlin(), KEY_QUOTA); + await settle(); +}); + +test('Local lists a Conflicts report by any of its pins, not its first alone', async () => { + const url = + 'https://news.example.com/2026/11/05/drones-hit-kharkiv-and-belgorod-overnight'; + const exports = { + [exportName('20261105114500')]: [ + eventRow({ id: 1, code: '195', mentions: 9, url }), + eventRow({ + id: 2, + code: '195', + mentions: 2, + place: "Belgorod, Belgorodskaya Oblast', Russia", + lat: 50.6, + lon: 36.6, + url, + }), + ], + }; + const { ask, settle } = keyed({ + env: { WORLDNEWSAPI_KEY: 'wna-key' }, + answers: { exports, worldnews: { news: [] } }, + }); + const urls = async (at) => + (await ask('/feed', `hotspot=all&at=${at}`)).body.reports.map((r) => r.url); + assert.deepEqual(await urls('49.99,36.23'), [url]); + assert.deepEqual(await urls('50.6,36.6'), [url]); + await settle(); +}); + +test('the hotspot counts the reports Conflicts lists: no minor ones', async () => { + const { ask, settle } = keyed({ env: {} }); + const listed = ( + await ask('/feed', 'hotspot=all&today=1&relevance=core,related&limit=60') + ).body.reports; + const { counts } = (await ask('/hotspots')).body.hotspots[0]; + assert.equal(counts.last24h, listed.length); + assert.equal(counts.mapped24h, listed.filter((r) => r.geo).length); + // The council story is among the day's reports, and minor. + const all = (await ask('/feed', 'hotspot=all&today=1&limit=60')).body.reports; + assert.ok(all.length > listed.length); + await settle(); +}); + +test('a disputed area is cut out of the country it lies in, not of the neighbour its first corner touches', () => { + const outline = (lat, lon) => countryPolygons(areaAt(lat, lon).country); + for (const [country, at, name, inside] of [ + ['Israel', [32.08, 34.78], 'Golan Heights', [33.0, 35.75]], + ['Moldova', [47.0, 28.85], 'Transnistria', [47.2, 29.5]], + ['Egypt', [30.0, 31.2], 'Halayib', [22.5, 35.5]], + ]) { + const [lat, lon] = inside; + assert.equal(areaAt(lat, lon).kind, 'disputed', name); + assert.equal( + inPolygons(outline(...at), { lat, lon }), + false, + `${country} without ${name}`, + ); + } +}); diff --git a/server/providers/news/upstream.js b/server/providers/news/upstream.js new file mode 100644 index 0000000000..f82b4611f5 --- /dev/null +++ b/server/providers/news/upstream.js @@ -0,0 +1,283 @@ +// The keyed news APIs Core reads itself when no news server is configured: +// Liveuamap's worldwide feed (`a=mpts`) beside GDELT's events in the +// Conflicts section (gdeltEvents.js), World News API's search by source +// country for Local. Each key stays on the server: Liveuamap's rides in the query, so +// neither a URL nor an error body is ever logged or relayed. + +import { readResponseTextCapped } from '../common/http.js'; + +const LIVEUAMAP_URL = 'https://a.liveuamap.com/api'; +const WORLD_NEWS_URL = 'https://api.worldnewsapi.com/search-news'; +// 100 Liveuamap items run to about 500 KB. +const LIVEUAMAP_COUNT = 500; +const LIVEUAMAP_MAX_BYTES = 16 * 1024 * 1024; +// One search per country: a point, and a hundredth of one per article, so +// about 1.5 points a read (the free plan has 50 points a day). +const WORLD_NEWS_ARTICLES = 50; +const WORLD_NEWS_MAX_BYTES = 8 * 1024 * 1024; +// World News API's categories that are not the news of the day. Its +// `categories` filter is not asked for: it classifies few articles outside +// English, so it would drop most of a country's own outlets; an article it +// left unclassified is kept. +export const WORLD_NEWS_LEFT_OUT = Object.freeze( + new Set(['sports', 'entertainment', 'lifestyle', 'travel']), +); +const DAY_MS = 86_400_000; +const TIMEOUT_MS = 20_000; + +const ENTITIES = { + amp: '&', + quot: '"', + apos: "'", + lt: '<', + gt: '>', + nbsp: ' ', +}; + +/** Text with HTML entities decoded and whitespace collapsed, or ''. */ +export function unescapeHtml(value) { + return String(value ?? '') + .replace( + /&(?:#(\d{1,7})|#x([0-9a-f]{1,6})|([a-z]{2,6}));/gi, + (all, dec, hex, name) => { + if (name) return ENTITIES[name.toLowerCase()] ?? all; + const code = dec ? Number(dec) : parseInt(hex, 16); + return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : all; + }, + ) + .replace(/\s+/g, ' ') + .trim(); +} + +/** An https URL without credentials, or null. */ +export function webLink(value) { + try { + const url = new URL(String(value ?? '').trim()); + return url.protocol === 'https:' && !url.username && !url.password + ? url.href + : null; + } catch { + return null; + } +} + +/** A clip a browser plays itself (an https MP4 or WebM file), or null. */ +export function playableVideo(value) { + const url = webLink(value); + return url && /\.(?:mp4|m4v|webm)$/i.test(new URL(url).pathname) ? url : null; +} + +const finiteNumber = (value) => { + const number = typeof value === 'string' ? Number(value.trim()) : value; + return typeof number === 'number' && Number.isFinite(number) ? number : null; +}; + +/** Why an upstream could not be read; never carries its URL or body. */ +export class UpstreamError extends Error { + constructor( + message, + { + status = null, + rejected = false, + quota = false, + unreadable = false, + unreached = false, + } = {}, + ) { + super(message); + this.name = 'UpstreamError'; + this.status = status; + // The key was refused (401 or 403): the operator's to fix. + this.rejected = rejected; + // The key's allowance is spent (402, or the day's reads): it answers + // again later. A 429 is a per-second limit, not this. + this.quota = quota; + // The answer itself cannot be read (corrupt, or over a size cap): asking + // again gets the same. + this.unreadable = unreadable; + // The request got no answer at all (offline, timed out). + this.unreached = unreached; + } +} + +async function getText( + fetchImpl, + url, + { headers = {}, maxBytes, signal, what }, +) { + let response; + try { + response = await fetchImpl(url, { + headers: { Accept: 'application/json', ...headers }, + redirect: 'error', + signal: signal + ? AbortSignal.any([signal, AbortSignal.timeout(TIMEOUT_MS)]) + : AbortSignal.timeout(TIMEOUT_MS), + }); + } catch (cause) { + // A request that timed out may have been read; one refused was not. + const timedOut = cause?.name === 'TimeoutError'; + throw new UpstreamError( + timedOut ? `${what} timed out` : `${what} unreachable`, + { unreached: !timedOut }, + ); + } + if (!response.ok) { + await response.body?.cancel?.().catch?.(() => {}); + throw new UpstreamError(`${what} answered ${response.status}`, { + status: response.status, + rejected: response.status === 401 || response.status === 403, + quota: response.status === 402, + }); + } + try { + return await readResponseTextCapped(response, maxBytes, signal); + } catch { + throw new UpstreamError(`${what} answer unreadable`); + } +} + +function parseJson(text, what) { + try { + return JSON.parse(text); + } catch { + // Not the parser's message: an error answer may echo the request. + throw new UpstreamError(`${what} answer unreadable`); + } +} + +/** + * Liveuamap's items with a headline, a point and a page: + * `{id, title, lat, lon, place, publishedAt, url, image, video}`. + */ +export function parseLiveuamap(payload) { + if (!Array.isArray(payload?.venues)) + throw new UpstreamError('Liveuamap answer unreadable'); + const items = []; + for (const venue of payload.venues) { + const id = finiteNumber(venue?.id); + const title = unescapeHtml(venue?.name); + const lat = finiteNumber(venue?.lat); + const lon = finiteNumber(venue?.lng); + const seconds = finiteNumber(venue?.timestamp); + const url = webLink(venue?.link); + if ( + id === null || + !title || + lat === null || + lon === null || + Math.abs(lat) > 90 || + Math.abs(lon) > 180 || + (lat === 0 && lon === 0) || + seconds === null || + !url + ) + continue; + items.push({ + id: Math.trunc(id), + title, + lat, + lon, + place: unescapeHtml(venue.location) || null, + publishedAt: new Date(seconds * 1000).toISOString(), + url, + image: webLink(venue.img_share), + video: playableVideo(venue.video), + }); + } + return items; +} + +/** The worldwide feed of the last day, as of `now`. */ +export async function fetchLiveuamap({ key, fetchImpl, now, signal }) { + const url = new URL(LIVEUAMAP_URL); + url.search = new URLSearchParams({ + a: 'mpts', + resid: '1', + time: String(Math.floor((now - DAY_MS) / 1000)), + count: String(LIVEUAMAP_COUNT), + key, + }).toString(); + const text = await getText(fetchImpl, url, { + maxBytes: LIVEUAMAP_MAX_BYTES, + signal, + what: 'Liveuamap', + }); + return parseLiveuamap(parseJson(text, 'Liveuamap')); +} + +// World News API writes times as "2026-10-30 01:31:00", in UTC. +const worldNewsTime = (ms) => + new Date(ms).toISOString().slice(0, 19).replace('T', ' '); +function worldNewsDate(value) { + const match = /^(\d{4}-\d\d-\d\d) (\d\d:\d\d:\d\d)$/.exec( + String(value ?? ''), + ); + const ms = match ? Date.parse(`${match[1]}T${match[2]}Z`) : NaN; + return Number.isFinite(ms) ? new Date(ms).toISOString() : null; +} + +/** + * A search's articles with a title, a link and a time, one per title (the + * same story from several outlets is one), sport and entertainment left + * out, newest first: + * `{id, title, url, publisher, language, category, publishedAt, image, video}`. + */ +export function parseWorldNews(payload) { + if (!Array.isArray(payload?.news)) + throw new UpstreamError('World News API answer unreadable'); + const seen = new Set(); + const articles = []; + for (const article of payload.news) { + const id = finiteNumber(article?.id); + const title = unescapeHtml(article?.title); + const url = webLink(article?.url); + const publishedAt = worldNewsDate(article?.publish_date); + const category = + typeof article?.category === 'string' + ? article.category.toLowerCase() + : null; + if (id === null || !title || !url || !publishedAt) continue; + if (WORLD_NEWS_LEFT_OUT.has(category)) continue; + const same = title.toLowerCase(); + if (seen.has(same)) continue; + seen.add(same); + articles.push({ + id: Math.trunc(id), + title, + url, + publisher: new URL(url).hostname.replace(/^www\./, ''), + language: + typeof article.language === 'string' && + /^[a-z]{2}$/i.test(article.language) + ? article.language.toLowerCase() + : null, + category, + publishedAt, + image: webLink(article.image), + video: playableVideo(article.video), + }); + } + return articles.sort((a, b) => b.publishedAt.localeCompare(a.publishedAt)); +} + +/** A country's everyday news of the last day, as of `now`. */ +export async function fetchWorldNews({ key, country, fetchImpl, now, signal }) { + const url = new URL(WORLD_NEWS_URL); + url.search = new URLSearchParams({ + 'source-country': country.toLowerCase(), + // Both ends: sorted by time with neither, a search is cut to 31 days. + 'earliest-publish-date': worldNewsTime(now - DAY_MS), + 'latest-publish-date': worldNewsTime(now), + sort: 'publish-time', + 'sort-direction': 'DESC', + number: String(WORLD_NEWS_ARTICLES), + }).toString(); + const text = await getText(fetchImpl, url, { + headers: { 'x-api-key': key }, + maxBytes: WORLD_NEWS_MAX_BYTES, + signal, + what: 'World News API', + }); + return parseWorldNews(parseJson(text, 'World News API')); +} diff --git a/server/providers/openai/instructions.js b/server/providers/openai/instructions.js index 8f802ac552..f9125df607 100644 --- a/server/providers/openai/instructions.js +++ b/server/providers/openai/instructions.js @@ -26,7 +26,7 @@ function realtimeDirectives( 'analyst_query ANSWERS questions; it never moves the camera or starts tracking. For requests to FOLLOW or TRACK a specific aircraft/ship, call track_entity (get_entity_context first when the target is ambiguous), never analyst_query as the final or only action. For "follow/track the nearest aircraft", first call analyst_query with the aircraft layer(s), sortBy=distance, and limit=1, then call track_entity with the returned aircraft identity in the same turn. The lookup alone does not fulfill a follow/track command.', 'For a request to enable an aircraft layer and SELECT or FIND the nearest/closest aircraft near a named place — for example, "Turn on flights and select the closest aircraft to Austin" — call select_nearest_aircraft once. It atomically turns on the requested aircraft layer first, waits for location arrival, refreshes that layer for the destination viewport, filters out landed/on-ground records, and selects the nearest airborne result. A healthy fallback feed is valid data, never an enable failure. Do not also call fly_to_location, set_layer_visibility, analyst_query, track_entity, set_context_mode, or control_cockpit for the same request.', 'For ANALYTICAL questions about loaded layer data — how many / which / fastest / highest / biggest / nearest / next flights, ships, fires, earthquakes, satellites, launches, storms, transit, bikes, bases, datacenters or dams ("how many flights over Texas", "anything above 40,000 feet") — call analyst_query, not get_entity_context. Always set scope by WHERE: "around here" or "near this" while pointing is kind pointer, never view. Filter on the attribute the user names ("MODIS" → sensor eq MODIS). Say the count with its scope in a few words ("37 loaded flights over Texas") plus one or two examples by name. If the needed layer is off, say so and offer to turn it on. "Which of THOSE…" about the last answer → followUp=true with only the new filter/sort.', - 'WORLD QUERIES — the query tools (get_weather, get_wind, search_places, places_nearby, plan_route, get_cyclones, get_fire_perimeters, get_bike_share, get_transit_vehicles, get_traffic_flow, situation_brief, military_awareness and the other get_* and find_* tools you have) look up data anywhere in the world without changing the map and without any layer being on. Use them when the user asks about a place they are not looking at or data whose layer is off ("what is the weather in Tokyo", "how do I drive from Austin to Dallas", "any wildfires in California"). For aircraft, ships, earthquakes, active fires, datacenters, dams and satellites overhead, use analyst_query over the layers instead, turning the layer on first when the user wants it. Use analyst_query and get_entity_context for what the app has loaded or what is on screen. Answer from the result summary and data, mention its source when it has one, and never claim the map changed. If the user also wants to SEE it, use the matching app action (fly_to_location, set_layer_visibility) as well.', + 'WORLD QUERIES: query tools (get_weather, get_wind, search_places, places_nearby, plan_route, get_cyclones, get_fire_perimeters, get_bike_share, get_transit_vehicles, get_traffic_flow, situation_brief, military_awareness and other get_* and find_* tools) look up any place without changing the map or enabling layers. Use them for places out of view or data whose layer is off. For aircraft, ships, earthquakes, active fires, datacenters, dams and satellites overhead, use analyst_query over layers instead; enable the layer first if asked. Use analyst_query and get_entity_context for loaded data or what is on screen. Answer from the result; name its source if supplied and never claim the map changed. If asked to show it, also use the matching app action (fly_to_location, set_layer_visibility).', 'WHERE, for every tool that takes a place or scope, in this order: (1) a place the user names, or an areaId you already have; (2) explicit pointing — "this/that one/here/around here" while pointer_context shows pointing or a target → "pointer"; (3) the Contacts subject while Contacts is active, or the selection when the user refers to it; (4) the current view. A selected datacenter, dam, fire or cable never silently becomes the centre.', 'AREAS: resolve_area turns a named boundary (country, state, province, county, city, district, natural region) into an areaId; to outline it pass draw=true; annotate_map is for marks, not boundaries. Count inside it → analyst_query kind=area with the areaId (or kind=region); "the area I drew" → kind=drawn; "the area you outlined" → kind=annotation. Imagery of a place → resolve_area, then find_imagery. Ambiguous name: call resolve_area; on needsClarification ask which, never guess.' + (overpass @@ -38,7 +38,7 @@ function realtimeDirectives( 'READING THE VIEW: with no selected object or overlay entities, answer from get_entity_context\'s basemap context (tiles source, centre target, reverse-geocoded place, altitude, style, enabled layers); say there is nothing only when that is unavailable too. Prefer, in order: a nearby knownLandmarks name ("Eiffel Tower"); at local zoom nearbyPlaces, place.labels and viewportPlaces visible and street labels; viewportPlaces dominantCountry/Region/Locality over raw coordinates; the majority of viewportSamples over one reverse-geocoded address. Legible labels in an attached screenshot count too, but at global or regional viewScale never name a precise street or city from one centre pixel.', 'Do not mention disabled layers or stale selections.', 'POINTING: pointer_context says what the cursor is on (pointing:: resolved by the tools; target "none": not pointing). For "this/that/here/that one" with no name, pass "pointer": get_entity_context scope, track_entity/fly_to_location query, analyst_query scope.kind ("around here" is pointer, not view), annotate_map target, find_imagery area. "The second/last one" is referent:n from the last numbered list. Without a pointer, ask or follow WHERE.', - 'PREAMBLES: for instant commands (layers, styles, HUD, detection, zoom, panels, basemap, radio controls, camera nudges, and lookups such as get_entity_context) call the tool without speaking first. Only for slow or multi-step work (annotate_map, resolve_area, find_imagery, a searched fly_to_location, select_nearest_aircraft, analyst_query over a named place, or two or more tools) you may first say ONE sentence of at most 12 words naming the actual steps ("Finding the Capitol, then outlining its grounds."), then call the tools at once in the same response.', + 'PREAMBLES: for instant commands (layers, styles, HUD, detection, zoom, panels, basemap, radio controls, camera nudges, and lookups such as get_entity_context) call the tool without speaking first. Only for slow or multi-step work (annotate_map, resolve_area, find_imagery, a searched fly_to_location, select_nearest_aircraft, show_street_level, analyst_query over a named place, or two or more tools) you may first say ONE sentence of at most 12 words naming the actual steps ("Finding the Capitol, then outlining its grounds."), then call the tools at once in the same response.', 'When one request contains MULTIPLE changes, call ALL the corresponding tools before the confirmation. Never confirm a partial subset; if one fails, say which.', 'AFTER TOOLS: speak the result\'s say line once, lightly rephrased at most, never repeating your preamble. For a requested analyst list or ranking, also name up to three returned items with the relevant returned values; keep their order. A count alone does not answer that request; if say is null, finish any remaining requested tools before confirming. Never add a count, list or action claim that the executed tool results do not support. Sources, notes and caveats are on the voice card: speak a caveat only when it changes the answer, or when asked why, how sure or which source. Lower bounds ("at least 500"), partial answers, approximate outlines and stale, degraded or unavailable feed states in say are part of the answer — always preserve them. No filler or hedges ("let me check", "keep in mind", "it seems", "based on the data available"), and never add "approximately" to an exact tool number.', 'For "show/open/turn on" layer requests, enable the matching layer. For "hide/close/turn off", disable it.', @@ -65,6 +65,7 @@ function realtimeDirectives( '"Track/follow " (a callsign, ship name, satellite name) uses track_entity. "Take me to the biggest fire" uses track_entity with query "biggest fire" (the fires layer must be enabled). Bare "orbit" means camera orbit of the current landmark. "Stop following/tracking" uses stop_tracking.', '"Show me which planes are overhead"/"frame the ships"/"show me the satellites above" use frame_overhead with the matching target.', 'Confirmations echo the RESULTING state, never the request: "HUD minimal layout", "Density twenty-five percent", "Bing aerial imagery", "Tracking UAL428", "Framed fourteen aircraft". On ok=false, state the failure plainly: "Nothing matched UAL999", "No ships within 120 kilometers". Never claim an action without ok=true in the tool result.', + 'STREET LEVEL: "X on Street View/Mapillary/KartaView/Panoramax", "street view of X" → show_street_level once, not fly_to_location; no place = view centre. Street View is never a basemap.', 'For destination requests such as "take me to Italy", "go to NYC", or "show me the Eiffel Tower", call fly_to_location. Prefer known city IDs when available; otherwise pass the plain place query.', 'Navigation-only requests ("take me to X", "go to X", "fly to X") are NOT descriptions: call fly_to_location alone and do NOT also call annotate_map, unless the user explicitly asks to mark the place or you go on to explain specific places there. Never drop a point pin on a region-scale natural feature (a mountain range, desert, sea, or forest) — a single point in the middle of the Rockies is meaningless. If the user explicitly asks to mark such a region, prefer type=area.', 'For country and city destinations, omit rangeM so GEV frames the whole country or city in view. For landmarks and buildings, omit rangeM so GEV chooses a close landmark view.', diff --git a/server/providers/openai/realtime.js b/server/providers/openai/realtime.js index 4412eb331b..f88171e4ab 100644 --- a/server/providers/openai/realtime.js +++ b/server/providers/openai/realtime.js @@ -238,7 +238,12 @@ function createRealtimeTokenHandler({ if (!bearer) { res.statusCode = 503; res.setHeader('Content-Type', 'application/json'); - res.end(JSON.stringify({ error: 'OPENAI_API_KEY is not set' })); + res.end( + JSON.stringify({ + error: 'OPENAI_API_KEY is not set', + code: 'API_KEY_MISSING', + }), + ); return; } } diff --git a/server/providers/openai/toolDescriptions.js b/server/providers/openai/toolDescriptions.js index c7e78c7d69..490de5c0b0 100644 --- a/server/providers/openai/toolDescriptions.js +++ b/server/providers/openai/toolDescriptions.js @@ -65,6 +65,28 @@ export const ACTION_DESCRIPTIONS = { }, }, }, + show_street_level: { + description: + 'Fly to a place and open its nearest street-level photo; Street View switches to Google 3D (billed). No query: view centre.', + $position: 1, + parameters: { + properties: { + query: { + description: 'Place or address; "pointer" = under the cursor.', + $position: 1, + }, + provider: { + description: + 'google = Street View; others by name; omit: the lit source.', + $position: 1, + }, + referent: { + description: 'Numbered item n from the last result list.', + $position: 1, + }, + }, + }, + }, adjust_camera_zoom: { description: 'Move the current Cesium camera closer to or farther from what it is presently looking at. Use for relative zoom requests without changing location.', @@ -287,6 +309,11 @@ export const ACTION_DESCRIPTIONS = { }, }, }, + open_stories: { + description: + 'Open the Stories Explore list on request ("open Stories", "show the story list"). Turns off voice.', + $position: 1, + }, control_scene: { description: 'Cinematic scene playback: list scenes, play one scene by name, stop, advance, or read status. Play starts a single named scene and returns immediately.', diff --git a/server/providers/places/routes.js b/server/providers/places/routes.js index 7b0a814496..4c38a21f92 100644 --- a/server/providers/places/routes.js +++ b/server/providers/places/routes.js @@ -72,6 +72,14 @@ class UpstreamRateLimitError extends Error { } } +/** Thrown when the routing service failed or sent no JSON; answered as 502. */ +class UpstreamUnavailableError extends Error { + constructor() { + super('routing service unavailable'); + this.name = 'UpstreamUnavailableError'; + } +} + /** * Run one outbound request no sooner than the shared gate allows. * @template T @@ -167,18 +175,26 @@ async function fetchRoute({ `${base.replace(/\/$/, '')}/route/v1/${osrmProfile}/${coords}` + `?overview=full&geometries=geojson&alternatives=false&steps=${withSteps ? 'true' : 'false'}`; const controller = new AbortController(); + // The 12 s budget includes queue wait, so Directions (15 s) hears back. const timer = setTimeout(() => controller.abort(), 12000); let osrm; try { - const upstreamRes = await throughUpstreamGate(() => - fetchImpl(upstream, { - signal: controller.signal, - // The endpoint is configured above; a redirect is the one way out of - // it, so it is refused rather than followed. - redirect: 'error', - headers: { 'User-Agent': 'gods-eye-view/dev (local)' }, - }), - ); + const upstreamRes = await throughUpstreamGate(async () => { + // Expiry before dispatch reflects our backlog, not an upstream outage. + if (controller.signal.aborted) + throw new RouteBusyError(_upstreamIntervalMs); + try { + return await fetchImpl(upstream, { + signal: controller.signal, + // The endpoint is configured above; a redirect is the one way out of + // it, so it is refused rather than followed. + redirect: 'error', + headers: { 'User-Agent': 'gods-eye-view/dev (local)' }, + }); + } catch { + throw new UpstreamUnavailableError(); + } + }); if (upstreamRes.status === 429) { await cancelBody(upstreamRes); const retryAfter = Number(upstreamRes.headers.get('retry-after')); @@ -186,20 +202,28 @@ async function fetchRoute({ Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : 5, ); } - if (!upstreamRes.ok) { + // OSRM answers 400 for a route it cannot find; other failures are outages. + if (upstreamRes.status === 400) { await cancelBody(upstreamRes); return { payload: null, error: 'no route found' }; } + if (!upstreamRes.ok) { + await cancelBody(upstreamRes); + throw new UpstreamUnavailableError(); + } const ctype = upstreamRes.headers.get('content-type') || ''; if (!ctype.includes('json')) { await cancelBody(upstreamRes); - return { payload: null, error: 'no route found' }; + throw new UpstreamUnavailableError(); + } + // Read and parse failures are outages; later ones stay "route proxy error". + try { + osrm = JSON.parse( + await readResponseTextCapped(upstreamRes, ROUTE_MAX_RESPONSE_BYTES), + ); + } catch { + throw new UpstreamUnavailableError(); } - const text = await readResponseTextCapped( - upstreamRes, - ROUTE_MAX_RESPONSE_BYTES, - ); - osrm = JSON.parse(text); } finally { clearTimeout(timer); } @@ -355,6 +379,11 @@ export function installRouteMiddleware( upstreamError.retryAfterSec, ); } + if (upstreamError instanceof UpstreamUnavailableError) { + res.writeHead(502, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ ok: false, error: upstreamError.message })); + return; + } throw upstreamError; } if (error || !payload) return fail(error || 'no route found'); diff --git a/server/providers/rail.js b/server/providers/rail.js new file mode 100644 index 0000000000..c026331ca4 --- /dev/null +++ b/server/providers/rail.js @@ -0,0 +1,285 @@ +import { open, stat } from 'node:fs/promises'; +import path from 'node:path'; +import { Readable } from 'node:stream'; +import { pipeline } from 'node:stream/promises'; +import { fileURLToPath } from 'node:url'; +import { createRailService } from '../../src/sources/railService.js'; +import { RAIL_FEED_ID_PATTERN } from '../../src/data/railFeeds.js'; + +/** + * Where development and preview look for path and schedule packs when + * RAIL_PATHS_DIR is unset: the default output of scripts/build-rail-paths.mjs. + */ +export const DEFAULT_RAIL_PATHS_DIR = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + '../../.cache/rail-paths', +); + +/** + * Pack bytes the development server keeps in memory, across path and + * schedule packs: a few of the largest national packs. + */ +export const RAIL_PACK_CACHE_MAX_BYTES = 64 * 1024 * 1024; + +/** + * A bounded cache of pack files' bytes, by path, least recently read first + * out. An entry is used only while the file's modification time and size + * are the ones it was read with, so a rebuilt pack is read again; a file + * larger than the whole byte budget is never kept. Reads of the same file at + * the same time share one read. + * @param {number} [maxBytes] + * @returns {{load: (file: string, info: {mtimeMs: number, size: number}, + * read: () => Promise) => Promise, bytes: () => number}} + */ +export function createRailPackCache(maxBytes = RAIL_PACK_CACHE_MAX_BYTES) { + /** @type {Map} */ + const entries = new Map(); + /** @type {Map>} */ + const pending = new Map(); + let total = 0; + const drop = (file) => { + const entry = entries.get(file); + if (!entry) return; + entries.delete(file); + total -= entry.bytes.byteLength; + }; + return { + async load(file, info, read) { + const entry = entries.get(file); + if (entry && entry.mtimeMs === info.mtimeMs && entry.size === info.size) { + // Most recently read last: the first entry is the next one out. + entries.delete(file); + entries.set(file, entry); + return entry.bytes; + } + const version = `${file}|${info.mtimeMs}|${info.size}`; + const reading = pending.get(version); + if (reading) return reading; + const promise = (async () => { + const bytes = await read(); + drop(file); + if (bytes.byteLength <= maxBytes) { + entries.set(file, { mtimeMs: info.mtimeMs, size: info.size, bytes }); + total += bytes.byteLength; + for (const [oldest] of entries) { + if (total <= maxBytes) break; + drop(oldest); + } + } + return bytes; + })().finally(() => pending.delete(version)); + pending.set(version, promise); + return promise; + }, + bytes: () => total, + }; +} + +/** + * A pack reader for the rail service that reads `/`. + * Ids are re-checked against the registry's id pattern, so a name can never + * leave the directory; a missing file is "no pack", and a file over the cap is + * refused without being read (an error with `code: 'PACK_TOO_LARGE'`). The + * pack is returned as the file's bytes, never decoded to text; with a + * `cache` (createRailPackCache), an unchanged file is read once. + * @param {string} dir + * @param {string} suffix `.json` (path packs) or `.schedule.json`. + * @param {ReturnType|null} [cache] + * @returns {(feedId: string, options?: {maxBytes?: number}) => + * Promise} + */ +function createFsPackReader(dir, suffix, cache = null) { + const root = path.resolve(dir); + return async (feedId, { maxBytes = Infinity } = {}) => { + if (typeof feedId !== 'string' || !RAIL_FEED_ID_PATTERN.test(feedId)) + return null; + const file = path.join(root, `${feedId}${suffix}`); + let handle; + try { + handle = await open(file, 'r'); + } catch (error) { + if (error?.code === 'ENOENT') return null; + throw error; + } + try { + const info = await handle.stat(); + if (!info.isFile()) return null; + if (info.size > maxBytes) { + const error = new Error(`pack is ${info.size} bytes`); + error.code = 'PACK_TOO_LARGE'; + throw error; + } + return cache + ? await cache.load(file, info, () => handle.readFile()) + : await handle.readFile(); + } finally { + await handle.close(); + } + }; +} + +/** + * A `readPathPack` that reads `/.json`. + * @param {string} dir + * @param {{cache?: ReturnType|null}} [options] + */ +export function createFsPathPackReader(dir, { cache = null } = {}) { + return createFsPackReader(dir, '.json', cache); +} + +/** + * A `readSchedulePack` that reads `/.schedule.json`. + * @param {string} dir + * @param {{cache?: ReturnType|null}} [options] + */ +export function createFsSchedulePackReader(dir, { cache = null } = {}) { + return createFsPackReader(dir, '.schedule.json', cache); +} + +/** + * A `hasSchedulePack` for the rail service: whether + * `/.schedule.json` is a file. Only the directory entry is + * read, never the pack; a missing file is false, any other error is thrown + * (the service then lists the feed, so the read shows the failure). + * @param {string} dir + * @returns {(feedId: string) => Promise} + */ +export function createFsSchedulePackProbe(dir) { + const root = path.resolve(dir); + return async (feedId) => { + if (typeof feedId !== 'string' || !RAIL_FEED_ID_PATTERN.test(feedId)) + return false; + try { + return (await stat(path.join(root, `${feedId}.schedule.json`))).isFile(); + } catch (error) { + if (error?.code === 'ENOENT') return false; + throw error; + } + }; +} + +/** + * A pack version for the rail service: the modification time and size of + * `/`, or null when there is no such file. Only the + * directory entry is read; a rebuilt pack has a new version. + * @param {string} dir + * @param {string} suffix + * @returns {(feedId: string) => Promise} + */ +function createFsPackVersion(dir, suffix) { + const root = path.resolve(dir); + return async (feedId) => { + if (typeof feedId !== 'string' || !RAIL_FEED_ID_PATTERN.test(feedId)) + return null; + try { + const info = await stat(path.join(root, `${feedId}${suffix}`)); + return info.isFile() ? `${info.mtimeMs}:${info.size}` : null; + } catch (error) { + if (error?.code === 'ENOENT') return null; + throw error; + } + }; +} + +/** + * A `schedulePackVersion` for the rail service: the modification time and + * size of `/.schedule.json`, or null when there is no such + * file. + * @param {string} dir + * @returns {(feedId: string) => Promise} + */ +export function createFsSchedulePackVersion(dir) { + return createFsPackVersion(dir, '.schedule.json'); +} + +/** + * A `pathPackVersion` for the rail service: the same for + * `/.json`. + * @param {string} dir + * @returns {(feedId: string) => Promise} + */ +export function createFsPathPackVersion(dir) { + return createFsPackVersion(dir, '.json'); +} + +/** + * Write a service Response to a Node response, streaming its body: a pack's + * bytes go to the socket as they are, with no text decode and no copy. + * @param {Response} response + * @param {import('node:http').ServerResponse} res + * @returns {Promise} + */ +export async function sendRailResponse(response, res) { + res.writeHead(response.status, Object.fromEntries(response.headers)); + if (!response.body) { + res.end(); + return; + } + await pipeline(Readable.fromWeb(response.body), res); +} + +/** Connect the reusable rail request service to development and preview. */ +export function railProxy(options = {}) { + const pathsDir = + options.pathsDir || process.env.RAIL_PATHS_DIR || DEFAULT_RAIL_PATHS_DIR; + // One byte budget for both kinds of pack. + const cache = createRailPackCache(); + const service = createRailService({ + ...options, + readPathPack: + options.readPathPack || createFsPathPackReader(pathsDir, { cache }), + readSchedulePack: + options.readSchedulePack || + createFsSchedulePackReader(pathsDir, { cache }), + // Probe the same directory only when its fs reader is the one in use. + hasSchedulePack: + options.hasSchedulePack || + (options.readSchedulePack ? null : createFsSchedulePackProbe(pathsDir)), + schedulePackVersion: + options.schedulePackVersion || + (options.readSchedulePack ? null : createFsSchedulePackVersion(pathsDir)), + pathPackVersion: + options.pathPackVersion || + (options.readPathPack ? null : createFsPathPackVersion(pathsDir)), + }); + // A throw here would escape into the HTTP server's event loop and end the + // whole dev server (Node exits on an unhandled rejection or a throwing + // 'close' listener), so failures stay inside the rail routes. + function closeService() { + try { + service.close(); + } catch (error) { + console.warn('[rail] provider close failed', error); + } + } + function install(server) { + server.middlewares.use('/api/rail', async (req, res) => { + try { + const response = await service.handle({ + url: `http://localhost/api/rail${req.url || '/'}`, + method: req.method, + // Read for If-None-Match on a pack. + headers: req.headers, + }); + await sendRailResponse(response, res); + } catch (error) { + // An answer already under way (a viewer that left mid-pack) has + // nothing to add: the stream is closed and that is all. + if (res.headersSent) { + res.destroy(); + return; + } + console.warn('[rail] request failed', error); + res.writeHead(500, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ error: 'Rail provider error' })); + } + }); + server.httpServer?.once('close', closeService); + } + return { + name: 'rail-proxy', + closeBundle: closeService, + configureServer: install, + configurePreviewServer: install, + }; +} diff --git a/server/providers/regional/briefing.js b/server/providers/regional/briefing.js index c5b17a12bf..f56c7013c7 100644 --- a/server/providers/regional/briefing.js +++ b/server/providers/regional/briefing.js @@ -3,6 +3,7 @@ import { fetchRegionalPlace } from './place.js'; import { fetchRegionalWeather } from './weather.js'; import { fetchRegionalNews } from './news.js'; import { validRegionalPoint } from './query.js'; +import { REGIONAL_NEWS_WINDOW_HOURS } from '../../../src/data/regionalModel.js'; import { coalesceProxyRequest } from '../common/http.js'; // --------------------------------------------------------------------------- @@ -50,10 +51,11 @@ function regionalBriefProxy({ placeProvider = fetchRegionalPlace } = {}) { if (!regionalBriefHasAnySource({ place, weather, news })) { throw new Error('All regional briefing sources unavailable'); } + const retrievedAt = new Date().toISOString(); const payload = { status: place && weather && news.status !== 'unavailable' ? 'ready' : 'partial', - retrievedAt: new Date().toISOString(), + retrievedAt, coordinates: point, place, placeStatus: place ? 'ready' : 'unavailable', @@ -62,6 +64,9 @@ function regionalBriefProxy({ placeProvider = fetchRegionalPlace } = {}) { newsStatus: news.status, newsQuery: news.query, newsSource: news.source, + newsWindowHours: REGIONAL_NEWS_WINDOW_HOURS, + // A cached or stale answer keeps this, so the client can show its age. + newsFetchedAt: retrievedAt, articles: news.articles, }; _regionalBriefCache.set(key, { payload, cachedAt: Date.now() }); diff --git a/server/providers/regional/news.js b/server/providers/regional/news.js index 155dfa9080..085a6ba727 100644 --- a/server/providers/regional/news.js +++ b/server/providers/regional/news.js @@ -1,5 +1,10 @@ import { fetchRegionalText, fetchRegionalJson } from './http.js'; -import { normalizeRegionalArticles } from '../../../src/data/regionalModel.js'; +import { + REGIONAL_NEWS_WINDOW_HOURS, + googleNewsWindowOperator, + normalizeRegionalArticles, + recentRegionalArticles, +} from '../../../src/data/regionalModel.js'; function decodeRssText(value) { return String(value || '') @@ -22,7 +27,10 @@ function rssTag(block, tag) { ); } -function normalizeRssArticles(xml, limit = 5) { +// Feed items read before the window filter; Google returns about 100. +const RSS_ITEM_CAP = 100; + +function normalizeRssArticles(xml, limit = RSS_ITEM_CAP) { const seen = new Set(); const articles = []; for (const match of String(xml || '').matchAll( @@ -57,12 +65,27 @@ function normalizeRssArticles(xml, limit = 5) { return articles; } -async function fetchRegionalNews(place) { +/** + * Headlines for a place from the last REGIONAL_NEWS_WINDOW_HOURS, newest + * first: Google News RSS, then GDELT when RSS fails or has nothing recent. + * `empty` means a source answered with nothing in the window; `unavailable` + * means there was no place or no source answered. + * @param {{locality?: string, region?: string, country?: string}|null} place + * @param {{now?: () => number}} [options] + */ +async function fetchRegionalNews(place, { now = Date.now } = {}) { const query = place?.locality || place?.region || place?.country; if (!query) return { status: 'unavailable', query: null, articles: [], source: null }; + const recent = (articles) => + recentRegionalArticles(articles, { + now: now(), + windowHours: REGIONAL_NEWS_WINDOW_HOURS, + limit: 5, + }); + let answered = false; const rssParams = new URLSearchParams({ - q: String(query).replace(/["\\]/g, ' ').trim(), + q: `${String(query).replace(/["\\]/g, ' ').trim()} ${googleNewsWindowOperator()}`, hl: 'en-US', gl: 'US', ceid: 'US:en', @@ -75,7 +98,8 @@ async function fetchRegionalNews(place) { timeoutMs: 12_000, }, ); - const articles = normalizeRssArticles(xml, 5); + answered = true; + const articles = recent(normalizeRssArticles(xml)); if (articles.length) return { status: 'ready', query, articles, source: 'Google News RSS' }; } catch { @@ -87,7 +111,7 @@ async function fetchRegionalNews(place) { format: 'json', maxrecords: '5', sort: 'datedesc', - timespan: '48h', + timespan: `${REGIONAL_NEWS_WINDOW_HOURS}h`, }); try { const payload = await fetchRegionalJson( @@ -97,7 +121,7 @@ async function fetchRegionalNews(place) { timeoutMs: 12_000, }, ); - const articles = normalizeRegionalArticles(payload, 5); + const articles = recent(normalizeRegionalArticles(payload, 5)); return { status: articles.length ? 'ready' : 'empty', query, @@ -105,7 +129,10 @@ async function fetchRegionalNews(place) { source: 'GDELT fallback', }; } catch { - return { status: 'unavailable', query, articles: [], source: null }; + // An RSS answer with nothing recent is still a true empty result. + return answered + ? { status: 'empty', query, articles: [], source: 'Google News RSS' } + : { status: 'unavailable', query, articles: [], source: null }; } } diff --git a/server/providers/shipwrecks.js b/server/providers/shipwrecks.js new file mode 100644 index 0000000000..2d38b6c963 --- /dev/null +++ b/server/providers/shipwrecks.js @@ -0,0 +1,218 @@ +import { + EMODNET_WFS_URL, + WIKIDATA_QUERY, + mergeShipwreckRecords, + normalizeEmodnetFeatures, + normalizeWikidataResults, +} from '../../src/layers/shipwrecks/records.js'; +import { coalesceProxyRequest, readResponseJsonCapped } from './common/http.js'; +import { clientKey, makeRateLimiter } from './common/rate-limit.js'; + +const MIB = 1024 * 1024; +/** EMODnet republishes the wreck layer about once a year; Wikidata daily at most. */ +const REFRESH_MS = 24 * 60 * 60 * 1000; +/** A source's last good records keep being served this long, marked stale. */ +const STALE_MAX_MS = 7 * REFRESH_MS; +/** After a source fails, it is not asked again for this long. */ +const RETRY_MS = 15 * 60 * 1000; +/** A refresh with fewer than this share of the last good records is refused. */ +const MIN_KEEP_RATIO = 0.5; +// Only the columns the card uses; ship_char/obj_desc histories can name people +// and are not read beyond a short vessel type. +const EMODNET_PROPERTIES = [ + 'source_id', + 'country', + 'name', + 'least_depth', + 'depth_prec', + 'loc_prec', + 'sink_context', + 'sink_yr', + 'dating', + 'period', + 'statutory', + 'ship_char', + 'obj_type', + 'artefacts', + 'source_inf', + 'website1', + 'point_info', + 'the_geom', +].join(','); +const EMODNET_URL = `${EMODNET_WFS_URL}&propertyName=${EMODNET_PROPERTIES}`; +const WIKIDATA_URL = + 'https://query.wikidata.org/sparql?format=json&query=' + + encodeURIComponent(WIKIDATA_QUERY); +// Wikimedia asks automated clients to name themselves. +const USER_AGENT = + "God's Eye View shipwrecks layer (https://github.com/bilawalsidhu/gods-eye-view)"; + +/** Fixed-origin, cached EMODnet + Wikidata shipwreck snapshot for dev and preview. */ +export function shipwrecksProxy({ + fetchImpl = (...args) => globalThis.fetch(...args), + now = () => Date.now(), +} = {}) { + // Each source keeps its last good records on its own, so one failing (or + // answering with nothing usable) never removes the other's wrecks or its + // own earlier ones. `retryAt` holds a failed source back for RETRY_MS. + const sources = { + emodnet: { load: fetchEmodnet, good: null, retryAt: 0 }, + wikidata: { load: fetchWikidata, good: null, retryAt: 0 }, + }; + let snapshot = null; + const inFlight = new Map(); + const allow = makeRateLimiter({ windowMs: 60_000, max: 30, globalMax: 600 }); + + async function upstreamJson(url, maxBytes) { + const signal = AbortSignal.timeout(90_000); + const response = await fetchImpl(url, { + signal, + redirect: 'error', + headers: { 'User-Agent': USER_AGENT, Accept: 'application/json' }, + }); + if (!response.ok) { + await response.body?.cancel(); + throw new Error('upstream_unavailable'); + } + return readResponseJsonCapped(response, maxBytes, signal); + } + + async function fetchEmodnet() { + const records = normalizeEmodnetFeatures( + await upstreamJson(EMODNET_URL, 32 * MIB), + ); + if (!records.length) throw new Error('invalid_emodnet_layer'); + return records; + } + + async function fetchWikidata() { + const payload = await upstreamJson(WIKIDATA_URL, 16 * MIB); + if (!Array.isArray(payload?.results?.bindings)) + throw new Error('invalid_wikidata_results'); + const records = normalizeWikidataResults(payload); + // Wikidata lists over a thousand wrecks; none at all is a broken answer. + if (!records.length) throw new Error('invalid_wikidata_results'); + return records; + } + + const fresh = (state, at) => + state.good !== null && at - state.good.fetchedAt < REFRESH_MS; + const usable = (state, at) => + state.good !== null && at - state.good.fetchedAt <= STALE_MAX_MS; + const due = (state, at) => !fresh(state, at) && at >= state.retryAt; + + /** Refresh the sources that are due; failures keep their last good records. */ + async function refresh() { + const at = now(); + const names = Object.keys(sources).filter((name) => due(sources[name], at)); + const results = await Promise.allSettled( + names.map((name) => sources[name].load()), + ); + const done = now(); + results.forEach((result, i) => { + const state = sources[names[i]]; + // A valid answer far smaller than the last good set (a truncated or + // half-built upstream) is a failure too, until the old set expires. + const shrunk = + result.status === 'fulfilled' && + usable(state, done) && + result.value.length < state.good.records.length * MIN_KEEP_RATIO; + if (result.status === 'fulfilled' && !shrunk) + state.good = { records: result.value, fetchedAt: done }; + else state.retryAt = done + RETRY_MS; + if (shrunk) + console.warn( + `[shipwrecks] ${names[i]} refresh refused: ${result.value.length} ` + + `records against ${state.good.records.length} last good`, + ); + }); + } + + /** The served snapshot: every source with usable records, merged once. */ + function compose(at) { + const sourceFlags = {}; + // How old each source's records are, on this clock, so the page can + // expire them by its own clock without comparing the two. + const ages = {}; + let stale = false; + let fetchedAt = null; + for (const [name, state] of Object.entries(sources)) { + sourceFlags[name] = usable(state, at); + ages[name] = sourceFlags[name] ? at - state.good.fetchedAt : null; + if (!sourceFlags[name]) continue; + if (!fresh(state, at)) stale = true; + fetchedAt = Math.min(fetchedAt ?? Infinity, state.good.fetchedAt); + } + if (!sourceFlags.emodnet && !sourceFlags.wikidata) return null; + const key = `${sourceFlags.emodnet && sources.emodnet.good.fetchedAt}:${ + sourceFlags.wikidata && sources.wikidata.good.fetchedAt + }`; + if (snapshot?.key !== key) { + // The merge writes EMODnet facts into Wikidata records: work on copies + // so a source's kept records stay as fetched. + const copy = (name) => + sourceFlags[name] + ? sources[name].good.records.map((record) => ({ ...record })) + : []; + snapshot = { + key, + records: mergeShipwreckRecords(copy('emodnet'), copy('wikidata')), + }; + } + return { + value: { + fetchedAt, + version: key, + sources: sourceFlags, + ages, + maxAgeMs: STALE_MAX_MS, + records: snapshot.records, + }, + stale, + }; + } + + async function acquire() { + const at = now(); + if (Object.values(sources).some((state) => due(state, at))) + await coalesceProxyRequest(inFlight, 'refresh', refresh).promise; + const composed = compose(now()); + if (!composed) throw new Error('shipwrecks_unavailable'); + return composed; + } + + async function handler(req, res) { + const json = (status, value, stale = false) => { + if (res.destroyed) return; + res.writeHead(status, { + 'Content-Type': 'application/json', + 'Cache-Control': 'no-store', + ...(status === 405 ? { Allow: 'GET' } : {}), + ...(status === 429 ? { 'Retry-After': '60' } : {}), + ...(stale ? { 'X-Data-Stale': 'true' } : {}), + }); + res.end(JSON.stringify(value)); + }; + if (req.method !== 'GET') return json(405, { error: 'method_not_allowed' }); + const path = (req.url || '/').split('?')[0]; + if (path !== '/' && path !== '') + return json(404, { error: 'unknown_route' }); + if (!allow(clientKey(req))) return json(429, { error: 'rate_limited' }); + try { + const { value, stale } = await acquire(); + json(200, stale ? { ...value, stale: true } : value, stale); + } catch { + json(502, { error: 'shipwrecks_unavailable' }); + } + } + + return { + name: 'shipwrecks', + configureServer({ middlewares }) { + middlewares.use('/api/shipwrecks', handler); + }, + configurePreviewServer({ middlewares }) { + middlewares.use('/api/shipwrecks', handler); + }, + }; +} diff --git a/server/providers/transitHistory.test.mjs b/server/providers/transitHistory.test.mjs index 551fee7a70..aeed8308a2 100644 --- a/server/providers/transitHistory.test.mjs +++ b/server/providers/transitHistory.test.mjs @@ -202,3 +202,25 @@ test('a feed fleet-number mode outranks its route mode in the epoch context', (t assert.equal(h.get('ttc', '4507', 100000).epochs[0].mode, 'tram'); assert.equal(h.get('ttc', 'x1', 100000).epochs[0].mode, 'tram'); }); +test('the epoch mode is the live mode: a route type, else hints, else the default', (t) => { + const h = history(t); + const pid = { + id: 'pid', + historyRetention: true, + defaultMode: 'bus', + routeMode: (route) => (route === 'L22' ? 'tram' : 'unknown'), + }; + h.ingest( + pid, + [ + row(100000, 'a', { routeId: 'L58', routeType: 11 }), + row(100000, 'b', { routeId: 'L22' }), + row(100000, 'c', { routeId: 'L9999' }), + ], + 100000, + ); + assert.equal(h.get('pid', 'a', 100000).epochs[0].mode, 'trolleybus'); + assert.equal(h.get('pid', 'b', 100000).epochs[0].mode, 'tram'); + // A hint that knows nothing leaves the default, as the live layer does. + assert.equal(h.get('pid', 'c', 100000).epochs[0].mode, 'bus'); +}); diff --git a/server/providers/vessels/ais-live.js b/server/providers/vessels/ais-live.js index cb1dd36b05..e525763efc 100644 --- a/server/providers/vessels/ais-live.js +++ b/server/providers/vessels/ais-live.js @@ -27,6 +27,8 @@ const AISSTREAM_DEFAULT_MESSAGE_TYPES = [ 'ExtendedClassBPositionReport', 'ShipStaticData', 'StaticDataReport', + // Buoys, beacons and other aids to navigation (AIS message 21). + 'AidsToNavigationReport', ]; // Watchdog budgets (policy lives in src/data/aisWatchdog.js). Silence is // REPORTED quickly and ACTED ON slowly: a dead feed must read as dead within diff --git a/server/providers/vessels/ais-store.js b/server/providers/vessels/ais-store.js index 71cefceed3..6c4d8a57ac 100644 --- a/server/providers/vessels/ais-store.js +++ b/server/providers/vessels/ais-store.js @@ -1,4 +1,8 @@ import { isRecognizedAisEnvelope } from '../../../src/data/aisStreamAdapter.js'; +import { + aidToNavigationTypeName, + isAidToNavigation, +} from '../../../src/data/vesselTypes.js'; export const AISSTREAM_CACHE_MAX = 50000; export const AISSTREAM_STALE_MS = 30 * 60 * 1000; // Per-MMSI recent-path ring buffers (PRD WS-F F3). Float32 lat/lon (~1m @@ -57,8 +61,13 @@ export function ingestAisStreamEnvelope(envelope) { message.ReportB?.Valid === false ? undefined : message.ReportB?.ShipType, + Dimension: + message.ReportB?.Valid === false + ? undefined + : message.ReportB?.Dimension, } : message; + const dimensions = aisDimensions(fields.Dimension); // Static reports may be partial (including Class B's separate A/B parts). // Keep known values in the cache as well as in the current live row. const staticData = { @@ -84,6 +93,8 @@ export function ingestAisStreamEnvelope(envelope) { staticCode(live?.imo) || staticCode(previous.imo) || '', + length: dimensions.length ?? live?.length ?? previous.length ?? null, + beam: dimensions.beam ?? live?.beam ?? previous.beam ?? null, }; _aisStreamStatic.set(mmsi, staticData); mergeAisStaticIntoLiveVessel(mmsi, staticData); @@ -105,14 +116,24 @@ export function ingestAisStreamEnvelope(envelope) { if (!Number.isFinite(lat) || !Number.isFinite(lon)) return true; const staticData = _aisStreamStatic.get(mmsi) || {}; + const aidReport = messageType === 'AidsToNavigationReport'; _aisStreamVessels.set(mmsi, { lat, lon, - name: vesselNameFromAis(metadata, message, staticData) || `MMSI ${mmsi}`, + name: + (aidReport && aidNameFromAis(message)) || + vesselNameFromAis(metadata, message, staticData) || + `MMSI ${mmsi}`, mmsi, imo: stringValue(message.ImoNumber ?? message.IMO ?? staticData.imo), - type: vesselTypeFromAis(message, staticData), + // An aid-to-navigation report's type is the kind of aid (0 to 31), not + // a ship type: it is carried as the aid's name ("Cardinal Mark N"). + type: aidReport + ? aidToNavigationTypeName(message.Type) + : vesselTypeFromAis(message, staticData), destination: stringValue(message.Destination ?? staticData.destination), + length: staticData.length ?? null, + beam: staticData.beam ?? null, speed: normalizedSpeedOverGround(message.Sog ?? message.SOG), course: normalizedCourseOverGround(message.Cog ?? message.COG), heading: normalizedHeading(message.TrueHeading ?? message.Heading), @@ -122,6 +143,9 @@ export function ingestAisStreamEnvelope(envelope) { // Use the AIS message's own report time, not server ingest wall-clock — // trail spacing and dead reckoning depend on true fix epochs. last_position_epoch: aisEpochSeconds(metadata.time_utc ?? metadata.TimeUtc), + // A virtual aid is broadcast where nothing physical stands. Only such a + // row carries the field, so ship rows stay their size. + ...(aidReport && message.VirtualAtoN === true && { virtual: true }), _updatedAt: Date.now(), }); @@ -236,6 +260,25 @@ function mergeAisStaticIntoLiveVessel(mmsi, staticData) { if (staticData.type) existing.type = staticData.type; if (staticData.destination) existing.destination = staticData.destination; if (staticData.imo) existing.imo = staticData.imo; + if (staticData.length) existing.length = staticData.length; + if (staticData.beam) existing.beam = staticData.beam; +} + +/** + * A static report's hull size from its AIS dimensions: the antenna's + * distances to bow (A), stern (B), port (C) and starboard (D), in metres. + * Zero is AIS's "not available", so a side missing its two parts has none. + * @param {{A?: number, B?: number, C?: number, D?: number}|undefined} dimension + * @returns {{length: number|null, beam: number|null}} + */ +function aisDimensions(dimension) { + const part = (value) => { + const number = numberValue(value); + return number !== null && number > 0 ? number : 0; + }; + const length = part(dimension?.A) + part(dimension?.B); + const beam = part(dimension?.C) + part(dimension?.D); + return { length: length > 0 ? length : null, beam: beam > 0 ? beam : null }; } function vesselNameFromAis(metadata, message, staticData = {}) { @@ -248,6 +291,15 @@ function vesselNameFromAis(metadata, message, staticData = {}) { ); } +/** + * An aid's whole name: an aid-to-navigation report carries the first 20 + * characters in `Name` and the rest, up to 14 more, in `NameExtension`. + */ +function aidNameFromAis(message) { + const name = stringValue(message.Name); + return name ? stringValue(name + stringValue(message.NameExtension)) : ''; +} + function vesselTypeFromAis(message, staticData = {}) { return stringValue( message.Type ?? @@ -257,14 +309,25 @@ function vesselTypeFromAis(message, staticData = {}) { ); } +/** + * The current rows, newest first, with every vessel ahead of every aid to + * navigation: a capped request never gives up a ship for a buoy. + */ export function aisStreamRows(maxRows) { const cutoff = Date.now() - AISSTREAM_STALE_MS; - const rows = []; + const vessels = []; + const aids = []; for (const row of _aisStreamVessels.values()) { - if (row._updatedAt >= cutoff) rows.push(row); + if (row._updatedAt >= cutoff) + (isAidToNavigation(row) ? aids : vessels).push(row); } - rows.sort((a, b) => b._updatedAt - a._updatedAt); - return rows.slice(0, maxRows).map(({ _updatedAt, ...row }) => row); + const newestFirst = (a, b) => b._updatedAt - a._updatedAt; + vessels.sort(newestFirst); + if (vessels.length < maxRows) aids.sort(newestFirst); + return vessels + .concat(aids) + .slice(0, maxRows) + .map(({ _updatedAt, ...row }) => row); } function pruneAisStreamCache() { diff --git a/server/standalone/conformance-references.js b/server/standalone/conformance-references.js new file mode 100644 index 0000000000..669fef616a --- /dev/null +++ b/server/standalone/conformance-references.js @@ -0,0 +1,59 @@ +import { mkdir, writeFile } from 'node:fs/promises'; +import { fileURLToPath } from 'node:url'; + +const DIR = fileURLToPath( + new URL('../../src/render/conformance/goldens/visual/', import.meta.url), +); +const NAME = /^[a-z0-9-]+\.(png|json)$/; +const MAX_BYTES = 8 * 1024 * 1024; + +/** + * Dev server only: lets `/dev/conformance/` save the visual references it + * records into `src/render/conformance/goldens/visual/`. Takes a PUT of one + * PNG or the manifest, named in the path; nothing else is written. + */ +export function conformanceReferencesPlugin() { + return { + name: 'conformance-references', + apply: 'serve', + configureServer(server) { + server.middlewares.use('/__conformance/references/', (req, res) => { + const name = decodeURIComponent((req.url ?? '').replace(/^\//, '')); + // Only the page on this machine: a loopback peer, sent from the + // dev server's own origin. + const peer = req.socket.remoteAddress ?? ''; + const loopback = /^(127\.|::1$|::ffff:127\.)/.test(peer); + let sameOrigin = false; + try { + sameOrigin = new URL(req.headers.origin).host === req.headers.host; + } catch { + // No Origin, or not a URL. + } + if (!loopback || !sameOrigin) { + res.writeHead(403).end(); + return; + } + if (req.method !== 'PUT' || !NAME.test(name)) { + res.writeHead(400).end(); + return; + } + const chunks = []; + let size = 0; + req.on('data', (chunk) => { + size += chunk.length; + if (size > MAX_BYTES) req.destroy(); + else chunks.push(chunk); + }); + req.on('end', async () => { + try { + await mkdir(DIR, { recursive: true }); + await writeFile(DIR + name, Buffer.concat(chunks)); + res.writeHead(204).end(); + } catch (error) { + res.writeHead(500).end(String(error?.message ?? error)); + } + }); + }); + }, + }; +} diff --git a/server/standalone/vite.config.js b/server/standalone/vite.config.js index 76d26ba5d2..f660bfbd33 100644 --- a/server/standalone/vite.config.js +++ b/server/standalone/vite.config.js @@ -5,6 +5,7 @@ import { createBrowserViteConfig } from '../../build/vite.js'; import { localProviderPlugins } from '../providers/local.js'; import { localMcpPlugin } from '../mcp/plugin.js'; import { apiNotFoundPlugin } from './api-not-found.js'; +import { conformanceReferencesPlugin } from './conformance-references.js'; import { googleTokenUnavailablePlugin } from './google-token-unavailable.js'; import { standaloneVoiceTools } from './voiceTools.js'; import { unwatchedRuntimeDirsPlugin } from './unwatched-cache.js'; @@ -30,6 +31,7 @@ export function standaloneConfig( }), localMcpPlugin(), googleTokenUnavailablePlugin(), + conformanceReferencesPlugin(), apiNotFoundPlugin(), unwatchedRuntimeDirsPlugin(), ], diff --git a/src/agent/worldPacket.js b/src/agent/worldPacket.js index 4f8dad144c..9217bd9b39 100644 --- a/src/agent/worldPacket.js +++ b/src/agent/worldPacket.js @@ -1,4 +1,4 @@ -import * as Cesium from 'cesium'; +import { findCamera } from '../render/rendererOf.js'; import { feedProvenanceEnvelope, layerSnapshot, @@ -104,14 +104,12 @@ export function getWorldPacket(options = {}) { // A default parameter only covers undefined; null or NaN would age every // feed against the epoch and report stale data as "just now". const now = Number.isFinite(requestedNow) ? requestedNow : Date.now(); - if (!viewer?.camera?.positionWC) - throw new TypeError('World Packet requires a viewer camera'); + const pose = findCamera(viewer)?.pose(); + if (!pose) throw new TypeError('World Packet requires a viewer camera'); if (!dataManager || typeof dataManager.getAll !== 'function') throw new TypeError('World Packet requires a data manager'); - const cartographic = Cesium.Cartographic.fromCartesian( - viewer.camera.positionWC, - ); + const eye = { lon: pose.lon, lat: pose.lat, height: pose.height }; // Read the roster once. Voice must not rewalk disabled layers: preserving the // current enabled-only view keeps the model's context budget bounded. const rows = dataManager.getAll(); @@ -126,9 +124,9 @@ export function getWorldPacket(options = {}) { ok: true, action: 'get_current_view_state', camera: { - latitude: Cesium.Math.toDegrees(cartographic.latitude), - longitude: Cesium.Math.toDegrees(cartographic.longitude), - heightM: cartographic.height, + latitude: eye.lat, + longitude: eye.lon, + heightM: eye.height, }, style: styleManager?.activeStyle || 'normal', context: contextState diff --git a/src/agent/worldPacket.test.mjs b/src/agent/worldPacket.test.mjs index 063e3652c2..a10b407da6 100644 --- a/src/agent/worldPacket.test.mjs +++ b/src/agent/worldPacket.test.mjs @@ -3,6 +3,8 @@ import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; import { getWorldPacket } from './worldPacket.js'; +import { bindRenderer } from '../render/rendererOf.js'; +import { createStubRenderer } from '../render/stub/index.js'; import { createGevActionRunner } from '../voice/gevActions.js'; function withoutVoicePresentation(result) { @@ -18,6 +20,9 @@ function harness() { const viewer = { trackedEntity: undefined, clock: { onTick: { addEventListener: () => () => {} } }, + get canvas() { + return this.scene.canvas; + }, scene: { canvas: { clientWidth: 1200, @@ -60,6 +65,14 @@ function harness() { getCockpitState: () => null, getControlState: () => ({ hud: { visible: 'auto' } }), }; + // The packet reads the eye from the camera port of the renderer bound to + // the scene object. + const renderer = createStubRenderer(); + renderer.camera.setView({ + destination: { lon: -97.74, lat: 30.26, height: 500 }, + orientation: { heading: 0, pitch: Cesium.Math.toRadians(-45), roll: 0 }, + }); + bindRenderer(viewer, renderer); return { viewer, dataManager, styleManager }; } diff --git a/src/annotations/adminOutline.test.mjs b/src/annotations/adminOutline.test.mjs index 2028fe711f..4bb5cba35e 100644 --- a/src/annotations/adminOutline.test.mjs +++ b/src/annotations/adminOutline.test.mjs @@ -4,11 +4,13 @@ import { test } from 'node:test'; import assert from 'node:assert/strict'; import { FEATURE_SOURCE_METHODS } from '../sources/featureSource.js'; import { createAnnotationResolver } from './resolver.js'; +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; import { createAnnotationEngine } from './annotationEngine.js'; import { _resetRenderGovernorForTest } from '../renderGovernor.js'; function viewerAt(lat, lon, height = 20_000) { - return { + // The resolver reads the camera through the renderer's camera port. + return bindFakeCesiumCamera({ camera: { positionCartographic: { latitude: (lat * Math.PI) / 180, @@ -16,7 +18,7 @@ function viewerAt(lat, lon, height = 20_000) { height, }, }, - }; + }); } /** A resolver whose boundary lookups and geocoder record every call. */ diff --git a/src/annotations/annotationEngine.js b/src/annotations/annotationEngine.js index c8cda0bf0d..352d65f4fd 100644 --- a/src/annotations/annotationEngine.js +++ b/src/annotations/annotationEngine.js @@ -1,6 +1,9 @@ import { isUnavailableCapability } from '../sources/capability.js'; import { defaultGeospatial } from '../search/defaults.js'; -import * as Cesium from 'cesium'; +import { cameraOf, findCamera, findQuery } from '../render/rendererOf.js'; +import { fromDegrees } from '../geo/ellipsoid.js'; +import { sphereFromPoints } from '../geo/sphere.js'; +import { distance, toRadians } from '../geo/vector.js'; import { greatCircleMeters } from '../geoDistance.js'; import { holdContinuousRender, @@ -20,11 +23,6 @@ import { } from '../sources/phaseTiming.js'; import { formatDistanceText } from '../data/distanceFormat.js'; -// Dev convenience: expose the app's Cesium instance for console/preview probing -// (single shared module instance — avoids dual-Cesium state bugs when testing). -if (typeof window !== 'undefined' && !window.__CESIUM__) - window.__CESIUM__ = Cesium; - /** * Annotation engine — the voice agent's "whiteboard" over the 3D world. * @@ -1717,18 +1715,20 @@ export function createAnnotationEngine({ frameAnnotation(marks[0]); return; } - const cart = points.map((p) => - Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0), + const cart = points.map((p) => fromDegrees(p.lon, p.lat, p.height || 0)); + const sphere = sphereFromPoints(cart); + const camera = cameraOf(viewer); + camera.flyToBounds( + { center: sphere.center, radius: sphere.radius }, + { + offset: { + heading: camera.pose().heading, + pitch: toRadians(-35), + range: Math.max(900, sphere.radius * 2.6), + }, + durationS: 1.6, + }, ); - const sphere = Cesium.BoundingSphere.fromPoints(cart); - viewer.camera.flyToBoundingSphere(sphere, { - offset: new Cesium.HeadingPitchRange( - viewer.camera.heading, - Cesium.Math.toRadians(-35), - Math.max(900, sphere.radius * 2.6), - ), - duration: 1.6, - }); } catch { /* camera assist is best-effort */ } @@ -1738,23 +1738,35 @@ export function createAnnotationEngine({ * globe. On any API hiccup, report visible — bad data must never move the camera. */ function isPointOnScreen(p) { try { - const camera = viewer.camera; - const pos = Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0); - const cv = camera.frustum.computeCullingVolume( - camera.position, - camera.direction, - camera.up, - ); - if ( - cv.computeVisibility(new Cesium.BoundingSphere(pos, 1)) === - Cesium.Intersect.OUTSIDE - ) - return false; - const occluder = new Cesium.EllipsoidalOccluder( - Cesium.Ellipsoid.WGS84, - camera.position, - ); - return occluder.isPointVisible(pos); + const camera = findCamera(viewer); + const query = findQuery(viewer); + if (!camera || !query) return true; + const pos = fromDegrees(p.lon, p.lat, p.height || 0); + // Inside the view frustum: a 1 m sphere at the point is not wholly + // outside any of its six planes, read off the view-projection (depth + // runs -1..1). An invalid matrix measures no distance and reads as + // visible. + const { view, projection } = camera.matrices(); + const m = new Float64Array(16); + for (let col = 0; col < 4; col++) + for (let row = 0; row < 4; row++) { + let sum = 0; + for (let k = 0; k < 4; k++) + sum += projection[k * 4 + row] * view[col * 4 + k]; + m[col * 4 + row] = sum; + } + const at = (row, col) => m[col * 4 + row]; + for (const [axis, sign] of FRUSTUM_PLANES) { + const a = at(3, 0) + sign * at(axis, 0); + const b = at(3, 1) + sign * at(axis, 1); + const c = at(3, 2) + sign * at(axis, 2); + const d = at(3, 3) + sign * at(axis, 3); + const distanceM = + (a * pos.x + b * pos.y + c * pos.z + d) / Math.hypot(a, b, c); + if (distanceM < -1) return false; + } + // On the near side of the globe. + return !query.isOccluded(pos); } catch { return true; } @@ -1778,22 +1790,23 @@ export function createAnnotationEngine({ : anno.ring, ) : viewportRange(anno.viewport) || 600; - viewer.camera.flyToBoundingSphere( - new Cesium.BoundingSphere( - Cesium.Cartesian3.fromDegrees( - target.lon, - target.lat, - anno.anchor.height || 0, - ), - range, - ), + const camera = cameraOf(viewer); + camera.flyToBounds( { - offset: new Cesium.HeadingPitchRange( - viewer.camera.heading, - Cesium.Math.toRadians(-35), - range * 2.4, - ), - duration: 1.8, + center: { + lon: target.lon, + lat: target.lat, + height: anno.anchor.height || 0, + }, + radius: range, + }, + { + offset: { + heading: camera.pose().heading, + pitch: toRadians(-35), + range: range * 2.4, + }, + durationS: 1.8, }, ); } catch { @@ -2005,15 +2018,17 @@ export function createAnnotationEngine({ }) { if (destroyed) return; try { - viewer.camera.flyTo({ - destination: Cesium.Cartesian3.fromDegrees(lon, lat, height), - orientation: { - heading: Cesium.Math.toRadians(heading), - pitch: Cesium.Math.toRadians(pitch), - roll: 0, + cameraOf(viewer).flyTo( + { lon, lat, height }, + { + orientation: { + heading: toRadians(heading), + pitch: toRadians(pitch), + roll: 0, + }, + durationS: duration, }, - duration, - }); + ); } catch { /* camera flight best-effort */ } @@ -2175,13 +2190,23 @@ function pendingAnimation(anno, now) { // fly_to_location natural-region heuristic uses (owner field test 2026-07-23). const VIEWPORT_ASSIST_RANGE_CAP_M = 120000; +/** The view frustum's planes as `row 3 ± row axis` of the view-projection. */ +const FRUSTUM_PLANES = [ + [0, 1], + [0, -1], + [1, 1], + [1, -1], + [2, 1], + [2, -1], +]; + /** flyTo range from a Places viewport box (low/high lat-lng corners), or null. */ function viewportRange(vp) { if (!vp?.low || !vp?.high) return null; try { - const span = Cesium.Cartesian3.distance( - Cesium.Cartesian3.fromDegrees(vp.low.longitude, vp.low.latitude), - Cesium.Cartesian3.fromDegrees(vp.high.longitude, vp.high.latitude), + const span = distance( + fromDegrees(vp.low.longitude, vp.low.latitude), + fromDegrees(vp.high.longitude, vp.high.latitude), ); return Number.isFinite(span) && span > 0 ? Math.max(300, Math.min(span * 0.7, VIEWPORT_ASSIST_RANGE_CAP_M)) @@ -2206,9 +2231,9 @@ function ringRange(ring) { if (lon < minLon) minLon = lon; if (lon > maxLon) maxLon = lon; } - const span = Cesium.Cartesian3.distance( - Cesium.Cartesian3.fromDegrees(minLon, minLat), - Cesium.Cartesian3.fromDegrees(maxLon, maxLat), + const span = distance( + fromDegrees(minLon, minLat), + fromDegrees(maxLon, maxLat), ); return Math.max(300, span * 0.7); } diff --git a/src/annotations/annotationEngine.test.mjs b/src/annotations/annotationEngine.test.mjs index da7e4ae06d..c545ac988c 100644 --- a/src/annotations/annotationEngine.test.mjs +++ b/src/annotations/annotationEngine.test.mjs @@ -1,3 +1,4 @@ +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; import { createStandalonePlaceSearch } from '../standalone/placeSearch.js'; // Voice-annotation resilience contract tests — pure logic, no network, no browser. // @@ -25,6 +26,7 @@ import { installRenderGovernor, _resetRenderGovernorForTest, } from '../renderGovernor.js'; +import { framePortFor } from '../testSupport/fakeFramePort.mjs'; // A resolver that replays a scripted sequence of outcomes (undefined = transient, // null = definitive miss, object = footprint) and counts its invocations. @@ -1471,7 +1473,7 @@ test('hand-drawn marks: one mark can be hidden, renamed, recoloured, framed and const { renderer, calls } = fakeRenderer(); const flights = []; const engine = createAnnotationEngine({ - viewer: { camera: { heading: 0, flyToBoundingSphere: (sphere) => flights.push(sphere) } }, + viewer: bindFakeCesiumCamera({ camera: { heading: 0, flyToBoundingSphere: (sphere) => flights.push(sphere) } }), renderer, }); let changes = 0; @@ -1540,12 +1542,12 @@ test('hand-drawn marks: remove, hide, clear, expiry and framing have their effec const { renderer, calls } = fakeRenderer(); const flights = []; const engine = createAnnotationEngine({ - viewer: { + viewer: bindFakeCesiumCamera({ camera: { heading: 0, flyToBoundingSphere: (sphere) => flights.push(sphere), }, - }, + }), renderer, }); let changes = 0; @@ -1757,7 +1759,7 @@ test('hand-drawn marks: with every mark hidden the scene idles, and showing one _resetRenderGovernorForTest(); t.after(() => _resetRenderGovernorForTest()); let renders = 0; - installRenderGovernor({ scene: { requestRenderMode: true, requestRender: () => (renders += 1) } }); + installRenderGovernor(framePortFor({ requestRenderMode: true, requestRender: () => (renders += 1) })); const { renderer } = fakeRenderer(); const engine = createAnnotationEngine({ viewer: {}, renderer }); await engine.annotate([ @@ -1898,3 +1900,67 @@ test('plain recaption keeps the old mark addressable when its removal throws', a ); assert.equal(engine.count(), 0); }); + +// The camera assist frames a fresh mark only when none of it is in view: +// off the frustum or behind the globe, as the renderer's camera and query +// ports see it. A camera that cannot answer leaves the view alone. +test('camera assist frames marks out of view and leaves visible ones alone', async (t) => { + installAnimationFrameStubs(t); + const { bindRenderer } = await import('../render/rendererOf.js'); + const { horizonFrom } = await import('../geo/horizon.js'); + const viewerOver = (lon, lat, height, { broken = false } = {}) => { + const position = Cesium.Cartesian3.fromDegrees(lon, lat, height); + const direction = Cesium.Cartesian3.negate( + Cesium.Cartesian3.normalize(position, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + const right = Cesium.Cartesian3.normalize( + Cesium.Cartesian3.cross(direction, Cesium.Cartesian3.UNIT_Z, new Cesium.Cartesian3()), + new Cesium.Cartesian3(), + ); + const up = Cesium.Cartesian3.cross(right, direction, new Cesium.Cartesian3()); + const view = Cesium.Matrix4.computeView(position, direction, up, right, new Cesium.Matrix4()); + const frustum = new Cesium.PerspectiveFrustum({ + fov: Cesium.Math.toRadians(60), aspectRatio: 16 / 9, near: 1, far: 5e7, + }); + const flights = []; + const viewer = {}; + const horizon = horizonFrom(position); + bindRenderer(viewer, { + camera: { + pose: () => ({ heading: 0 }), + matrices() { + if (broken) throw new Error('no camera'); + return { + view: Float64Array.from(Cesium.Matrix4.toArray(view)), + projection: Float64Array.from(Cesium.Matrix4.toArray(frustum.projectionMatrix)), + }; + }, + flyTo: (...args) => flights.push(['flyTo', ...args]), + flyToBounds: (...args) => flights.push(['flyToBounds', ...args]), + }, + query: { isOccluded: (p) => !horizon.isPointVisible(p) }, + }); + return { viewer, flights }; + }; + const pinAt = async (viewer, lon, lat) => { + const engine = createAnnotationEngine({ viewer, renderer: fakeRenderer().renderer }); + await engine.annotate([{ type: 'pin', manual: true, latitude: lat, longitude: lon }], { persist: true, flyTo: false }); + }; + + const inView = viewerOver(-97.74, 30.27, 9000); + await pinAt(inView.viewer, -97.742, 30.268); + assert.equal(inView.flights.length, 0, 'a mark in view is left alone'); + + const aside = viewerOver(-97.74, 30.27, 9000); + await pinAt(aside.viewer, -97.5, 30.6); + assert.equal(aside.flights.length, 1, 'a mark off the frustum is framed'); + + const behind = viewerOver(60, 30, 9_000_000); + await pinAt(behind.viewer, -120, -30); + assert.equal(behind.flights.length, 1, 'a mark behind the globe is framed'); + + const broken = viewerOver(-97.74, 30.27, 9000, { broken: true }); + await pinAt(broken.viewer, -97.5, 30.6); + assert.equal(broken.flights.length, 0, 'a camera that cannot answer moves nothing'); +}); diff --git a/src/annotations/annotationResolver.test.mjs b/src/annotations/annotationResolver.test.mjs index 2c51213c19..acd84e878e 100644 --- a/src/annotations/annotationResolver.test.mjs +++ b/src/annotations/annotationResolver.test.mjs @@ -13,6 +13,7 @@ import { createPlaceSearch } from '../search/placeSearch.js'; // Run with: npm test (node --test) import { test } from 'node:test'; import assert from 'node:assert/strict'; +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; import { resolveAnnotationTarget as resolveTarget, selectFootprint, @@ -157,7 +158,8 @@ test('refineScope: entityKind refines only an unresolved (auto) scope', () => { }); function closeViewportViewer() { - return { + // The resolver reads the camera through the renderer's camera port. + return bindFakeCesiumCamera({ camera: { positionCartographic: { latitude: 30.2672 * Math.PI / 180, @@ -165,7 +167,7 @@ function closeViewportViewer() { height: 1000, }, }, - }; + }); } function geocodePayload({ lat, lon, types, label }) { @@ -369,11 +371,11 @@ test('ask-side admin bypass: admin level 2/3 result types never grant a township // Synthetic footprints reproduce the real Capitol/YOTEL selection without live APIs. const CAPITOL_ANCHOR = { lat: 38.8899389, lon: -77.0090505 }; function capitolViewer() { - return { camera: { positionCartographic: { + return bindFakeCesiumCamera({ camera: { positionCartographic: { latitude: CAPITOL_ANCHOR.lat * Math.PI / 180, longitude: CAPITOL_ANCHOR.lon * Math.PI / 180, height: 1000, - } } }; + } } }); } function installCapitolMocks(t, elements, components = [ { long_name: 'Washington', types: ['locality', 'political'] }, diff --git a/src/annotations/drawTool.js b/src/annotations/drawTool.js index f44d30753d..b1f8d1d05a 100644 --- a/src/annotations/drawTool.js +++ b/src/annotations/drawTool.js @@ -1,5 +1,5 @@ /** - * Manual whiteboard drawing: the Cesium + DOM half. + * Manual whiteboard drawing: the scene + DOM half. * * UTILITIES ▸ Draw turns the globe into a whiteboard you draw on by hand: pick a * shape (area, line or pin) and a colour, click the vertices on the real world, @@ -15,12 +15,13 @@ * (`src/data/inputOwnership.js`), and every ambient selection handler yields, * so a vertex clicked on top of an aircraft or a camera is a vertex and * nothing else. It is one claim consulted by all of them, not a list of - * exceptions inside each. + * exceptions inside each. Turning Draw on takes the pointer from any tool + * holding it; a newer tool taking it turns Draw off. * - Cesium's Viewer binds its OWN left click (select the entity under the * pointer) and double click (track it) on the viewer's handler, outside every - * layer and therefore outside the shared claim. Both are borrowed for the + * layer and therefore outside the shared claim. Both are suppressed for the * session and given back on the way out, and `destroy()` gives back every - * listener, the Cesium handler, the preview data source and the window + * listener, the pointer subscriptions, the preview draw sets and the window * handle, so the tool can be turned off or the shell disposed without leaving * anything behind. * @@ -30,14 +31,13 @@ * drapes finished areas and routes onto the surface, so the height is dropped * at finish, deliberately and in one place — see `finishSpec` in drawMode.js. */ -import * as Cesium from 'cesium'; import { pickWorldFromScreen } from './annotationResolver.js'; import { claimPointer, pointerOwner, releasePointer, } from '../data/inputOwnership.js'; -import { pointerOwnerName } from '../data/pointerOwnerNames.js'; +import { inputFor } from '../input/dispatcher.js'; import { DRAW_SHAPES, MAX_VERTICES, @@ -59,7 +59,14 @@ import { presentDrawMarks, } from './drawMarks.js'; -import { onLocaleChange, t, translateKnown } from '../i18n/index.js'; +import { onLocaleChange, t } from '../i18n/index.js'; +import { fromDegrees } from '../geo/index.js'; +import { cssColor } from '../render/color.js'; +import { + canvasOf as sceneCanvasOf, + drawOf, + findFrame, +} from '../render/rendererOf.js'; /** The longest note a row action leaves under its row, in characters. */ const NOTE_MAX = 200; /** An action's answer as a row note: trimmed, and cut at a word with an ellipsis. */ @@ -74,7 +81,15 @@ function noteText(text) { /** The id this tool claims the pointer under. */ const DRAW_POINTER_OWNER = 'draw'; -const PREVIEW_DATA_SOURCE_NAME = 'gev-draw-preview'; +/** Each tool's preview sets get their own ids. */ +let previewSerial = 0; +/** + * Preview sets drawn on each viewer by its live tools, so a tool left + * undestroyed beside its replacement shows up in `diagnostics()`. + */ +const livePreviewSets = new WeakMap(); +const countPreviewSets = (viewer, delta) => + livePreviewSets.set(viewer, (livePreviewSets.get(viewer) ?? 0) + delta); const PREVIEW = DRAW_COLOR_CSS; @@ -89,7 +104,7 @@ const PREVIEW = DRAW_COLOR_CSS; * `markActions` are the application's own buttons on an area's or a line's * row (drawMarks.js `drawMarkActions`); a press runs the action with the * shape's id, kind, name and geometry (drawMarks.js `drawMarkGeometry`). - * @param {{viewer: Cesium.Viewer, annotations: {annotate: Function, clear: Function}, navigation?: object, publish?: Function, connect?: Function, markActions?: object[]}} deps + * @param {{viewer: object, annotations: {annotate: Function, clear: Function}, navigation?: object, publish?: Function, connect?: Function, markActions?: object[]}} deps * @returns {{destroy: Function}|null} */ export function initDrawTool({ @@ -115,16 +130,13 @@ export function initDrawTool({ let shape = 'area'; let color = 'primary'; let hint = ''; - let handler = null; + let unbindScene = null; let lease = null; - let savedDoubleClick = null; - let savedSingleClick = null; let cursor = null; // last mouse position on the canvas, for the rubber band // Bumped by anything that supersedes an in-flight finish: cancelling, clearing // the board, leaving draw mode, teardown. An `annotate()` that resolves after // one of those must not write its outcome over the newer state. let generation = 0; - const previewEntities = []; // Every DOM listener this tool adds (the session's keydown), so teardown is // one loop rather than a list that can fall out of step with the bindings. const domListeners = []; @@ -133,14 +145,26 @@ export function initDrawTool({ domListeners.push([target, type, listener, options]); }; - const dataSource = new Cesium.CustomDataSource(PREVIEW_DATA_SOURCE_NAME); - // `add()` resolves on the NEXT tick, so an init-then-immediate-destroy would - // remove a source that had not been attached yet and leave the attachment to - // land afterwards — a preview data source nobody owns. Chain the removal onto - // the attachment instead of racing it. - let attaching = Promise.resolve(viewer.dataSources.add(dataSource)).catch( - () => null, - ); + // The preview: one dashed rubber band and a dot per vertex, drawn through + // the renderer's draw port. Both sets live as long as the tool. + const draw = drawOf(viewer); + const previewId = `draw-preview:${++previewSerial}`; + const previewLines = draw.lines({ id: `${previewId}:line` }); + const previewPoints = draw.points({ id: `${previewId}:vertices` }); + countPreviewSets(viewer, 2); + let previewReleased = false; + const releasePreview = () => { + if (previewReleased) return; + previewReleased = true; + countPreviewSets(viewer, -2); + previewLines.dispose(); + previewPoints.dispose(); + }; + /** The canvas the renderer draws in (the viewer's own when none is bound). */ + const canvasOf = () => sceneCanvasOf(viewer); + const requestRender = () => findFrame(viewer)?.requestRender('draw-preview'); + // Teardown finishes synchronously; `whenSettled()` keeps its promise. + const attaching = Promise.resolve(); const present = () => { const marks = annotations.list?.() || []; @@ -169,70 +193,71 @@ export function initDrawTool({ // ---- preview --------------------------------------------------------- const vertexPositions = () => - session.vertices.map((v) => - Cesium.Cartesian3.fromDegrees(v.lon, v.lat, v.height || 0), - ); - const previewLine = dataSource.entities.add({ - show: false, - polyline: { - positions: new Cesium.CallbackProperty(() => { - if (!session) return []; - const pts = vertexPositions(); - if (cursor && session.shape !== 'pin') pts.push(cursor); - if (session.shape === 'area' && pts.length >= 3) pts.push(pts[0]); - return pts; - }, false), - width: 3, - material: new Cesium.PolylineDashMaterialProperty({ - color: Cesium.Color.fromCssColorString(PREVIEW.primary).withAlpha(0.9), - dashLength: 16, - }), - depthFailMaterial: new Cesium.PolylineDashMaterialProperty({ - color: Cesium.Color.fromCssColorString(PREVIEW.primary).withAlpha(0.35), - dashLength: 16, - }), - clampToGround: false, - }, - }); - const syncPreview = () => { + session.vertices.map((v) => fromDegrees(v.lon, v.lat, v.height || 0)); + /** The rubber band, from the vertices to the pointer (and closed for an area). */ + const syncPreviewLine = () => { if (destroyed) return; - previewEntities.forEach((e) => dataSource.entities.remove(e)); - previewEntities.length = 0; - if (!session) { - previewLine.show = false; - setHint(() => drawHint(null)); - viewer.scene.requestRender(); + if (!session || session.shape === 'pin') { + previewLines.clear(); return; } - const stroke = Cesium.Color.fromCssColorString( - PREVIEW[color] || PREVIEW.primary, - ); - previewLine.polyline.material = new Cesium.PolylineDashMaterialProperty({ - color: stroke.withAlpha(0.9), - dashLength: 16, - }); - previewLine.show = session.shape !== 'pin'; - for (const v of session.vertices) { - previewEntities.push( - dataSource.entities.add({ - position: Cesium.Cartesian3.fromDegrees(v.lon, v.lat, v.height || 0), - point: { - pixelSize: 8, - color: stroke, - outlineColor: Cesium.Color.BLACK.withAlpha(0.6), - outlineWidth: 2, - disableDepthTestDistance: Number.POSITIVE_INFINITY, - }, - }), - ); + const pts = vertexPositions(); + if (cursor) pts.push(cursor); + if (session.shape === 'area' && pts.length >= 3) pts.push(pts[0]); + if (pts.length < 2) { + previewLines.clear(); + return; } + previewLines.upsert([ + { + id: 'band', + positions: pts, + widthPx: 3, + // Along the ellipsoid between vertices, as the entity polyline was. + mode: 'geodesic', + style: { + kind: 'dash', + color: withAlpha(cssColor(PREVIEW[color] || PREVIEW.primary), 0.9), + length: 16, + }, + // Dashed behind the surface too, as the band in front of it is. + depthFail: { + kind: 'dash', + color: withAlpha(cssColor(PREVIEW.primary), 0.35), + length: 16, + }, + }, + ]); + }; + const syncPreview = () => { + if (destroyed) return; + if (!session) { + previewPoints.clear(); + previewLines.clear(); + setHint(() => drawHint(null)); + requestRender(); + return; + } + const stroke = cssColor(PREVIEW[color] || PREVIEW.primary); + previewPoints.set( + session.vertices.map((v, index) => ({ + id: String(index), + pos: { lon: v.lon, lat: v.lat, height: v.height || 0 }, + pixelSize: 8, + color: stroke, + outlineColor: [0, 0, 0, 0.6], + outlineWidth: 2, + disableDepthTest: Number.POSITIVE_INFINITY, + })), + ); + syncPreviewLine(); setHint(() => drawHint(session)); - viewer.scene.requestRender(); + requestRender(); }; // ---- vertices from clicks -------------------------------------------- const worldAt = (position) => { - const canvas = viewer.scene.canvas; + const canvas = canvasOf(); const w = canvas.clientWidth || canvas.width || 1; const h = canvas.clientHeight || canvas.height || 1; return pickWorldFromScreen(viewer, position.x / w, position.y / h); @@ -260,11 +285,12 @@ export function initDrawTool({ }; const onMove = (event) => { if (!session || session.shape === 'pin' || destroyed) return; - const p = worldAt(event.endPosition); - cursor = p - ? Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0) - : null; - viewer.scene.requestRender(); + // The click's own position is sensor-corrected; the rubber band must + // follow the same point the click would place. + const p = worldAt(event.pickPosition ?? event.endPosition); + cursor = p ? fromDegrees(p.lon, p.lat, p.height || 0) : null; + syncPreviewLine(); + requestRender(); }; // ---- finish / cancel ------------------------------------------------- @@ -344,9 +370,7 @@ export function initDrawTool({ t.closest('button, a, select, [role="button"], [role="radio"]') ) return false; - return ( - t === document.body || t === viewer.scene.canvas || t.tagName === 'CANVAS' - ); + return t === document.body || t === canvasOf() || t.tagName === 'CANVAS'; }; const onKey = (event) => { if (!active || destroyed || typingElsewhere(event)) return; @@ -383,18 +407,15 @@ export function initDrawTool({ function setActive(next) { if (destroyed || next === active) return active; if (next) { - lease = claimPointer(DRAW_POINTER_OWNER); - if (!lease) { - // Somebody else is using the pointer — possibly an older instance of - // this same tool that has not finished tearing down. Say so instead of - // half-starting. - setHint(() => - t('{owner} is using the pointer — close it first.', { - owner: translateKnown(pointerOwnerName(pointerOwner())), - }), - ); - return active; - } + // The newest claim takes over: a tool holding the pointer is told and + // turns itself off, and a newer one turns Draw off as if the person had. + const claimed = claimPointer(DRAW_POINTER_OWNER, { + onLost: () => { + if (lease === claimed) setActive(false); + }, + }); + if (!claimed) return active; + lease = claimed; } active = next; present(); @@ -416,50 +437,29 @@ export function initDrawTool({ } function bindSceneHandler() { - if (handler) return; - handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); - handler.setInputAction(onClick, Cesium.ScreenSpaceEventType.LEFT_CLICK); - handler.setInputAction(onMove, Cesium.ScreenSpaceEventType.MOUSE_MOVE); - handler.setInputAction(() => { - void finish(); - }, Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK); - // Cesium's Viewer binds BOTH stock click actions on its own handler: the - // single click picks an entity into `viewer.selectedEntity`, the double - // click tracks it. Neither goes through a layer, so neither can be fixed by - // the shared pointer claim — they have to be borrowed outright for the - // session and given back on the way out. Borrowing the single click is what - // stops a vertex placed on a contact from also selecting it. - const stock = viewer.screenSpaceEventHandler; - savedSingleClick = - stock.getInputAction(Cesium.ScreenSpaceEventType.LEFT_CLICK) || null; - savedDoubleClick = - stock.getInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK) || - null; - stock.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_CLICK); - stock.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK); + if (unbindScene) return; + const input = inputFor(viewer); + const held = { lease: () => lease }; + const offs = [ + input.onPointer('click', onClick, held), + input.onPointer('move', onMove, held), + input.onPointer('dblclick', () => void finish(), held), + // Cesium's Viewer binds BOTH stock click actions on its own handler: the + // single click picks an entity into `viewer.selectedEntity`, the double + // click tracks it. Neither goes through a layer, so neither yields to the + // shared pointer claim — they are suppressed for the session and given + // back on the way out. Suppressing the single click is what stops a + // vertex placed on a contact from also selecting it. + input.suppressStockClicks(), + ]; + unbindScene = () => offs.forEach((off) => off()); listen(document, 'keydown', onKey, true); } function releaseSceneHandler() { - if (handler) { - handler.destroy(); - handler = null; - } - if (savedSingleClick) { - viewer.screenSpaceEventHandler.setInputAction( - savedSingleClick, - Cesium.ScreenSpaceEventType.LEFT_CLICK, - ); - savedSingleClick = null; - } - if (savedDoubleClick) { - viewer.screenSpaceEventHandler.setInputAction( - savedDoubleClick, - Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK, - ); - savedDoubleClick = null; - } - // Drop the keydown listener bound alongside this handler. + unbindScene?.(); + unbindScene = null; + // Drop the keydown listener bound alongside the pointer subscriptions. for (let i = domListeners.length - 1; i >= 0; i -= 1) { const [target, type, listener, options] = domListeners[i]; if (listener !== onKey) continue; @@ -608,26 +608,18 @@ export function initDrawTool({ return { active, destroyed, - sceneHandler: Boolean(handler), + sceneHandler: Boolean(unbindScene), domListeners: domListeners.length, - previewDataSources: countPreviewDataSources(viewer), - previewEntities: destroyed ? 0 : dataSource.entities.values.length, + // Every live tool's on this viewer: 2 while one tool lives. + previewSets: livePreviewSets.get(viewer) ?? 0, + previewItems: previewReleased + ? 0 + : previewLines.size() + previewPoints.size(), pointerOwner: pointerOwner(), - // The viewer's OWN click actions. While a session is open both are - // borrowed (absent here); after it closes both are back. A harness can - // compare the restored functions by identity with what it captured - // before, which is the only way to prove they were given back rather - // than replaced. - stockSingleClick: Boolean( - viewer.screenSpaceEventHandler?.getInputAction?.( - Cesium.ScreenSpaceEventType.LEFT_CLICK, - ), - ), - stockDoubleClick: Boolean( - viewer.screenSpaceEventHandler?.getInputAction?.( - Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK, - ), - ), + // The viewer's own select and follow, which the input port runs: off + // while a session is open, back on after it closes. + stockSingleClick: inputFor(viewer).stockEnabled('select'), + stockDoubleClick: inputFor(viewer).stockEnabled('dblclickFollow'), }; }, /** Resolves once every deferred teardown step has run. */ @@ -649,18 +641,7 @@ export function initDrawTool({ for (const [target, type, listener, options] of domListeners.splice(0)) { target.removeEventListener(type, listener, options); } - previewEntities.length = 0; - dataSource.entities.removeAll(); - // Wait for the pending add() before removing: a destroy() in the same - // tick as init would otherwise remove nothing and let the attachment land - // behind it. - attaching = attaching.then(() => { - try { - viewer.dataSources.remove(dataSource, true); - } catch { - /* viewer already disposed — nothing to detach from */ - } - }); + releasePreview(); document.body.classList.remove('gev-drawing'); hint = ''; present(); @@ -672,13 +653,7 @@ export function initDrawTool({ return api; } -/** How many draw previews are attached — more than one means a leaked tool. */ -function countPreviewDataSources(viewer) { - const sources = viewer?.dataSources; - if (!sources) return 0; - let found = 0; - for (let index = 0; index < sources.length; index += 1) { - if (sources.get(index)?.name === PREVIEW_DATA_SOURCE_NAME) found += 1; - } - return found; +/** `color` at `alpha`. */ +function withAlpha(color, alpha) { + return [color[0], color[1], color[2], alpha]; } diff --git a/src/annotations/drawTool.test.mjs b/src/annotations/drawTool.test.mjs index 67ff94cfa3..2d7b2a6013 100644 --- a/src/annotations/drawTool.test.mjs +++ b/src/annotations/drawTool.test.mjs @@ -205,11 +205,8 @@ test('draped marks classify onto terrain as well as 3D tiles', () => { // rendered proof is in scripts/qa-draw-tool.mjs, which counts stroke pixels // against a keyless server; this stops the constant being narrowed again. const renderer = read('src/annotations/worldAnnotationRenderer.js'); - assert.match(renderer, /const CLASSIFY = Cesium\.ClassificationType\.BOTH;/); - assert.doesNotMatch( - renderer, - /classificationType: Cesium\.ClassificationType\.CESIUM_3D_TILE/, - ); + assert.match(renderer, /const CLAMP_TO = 'both';/); + assert.doesNotMatch(renderer, /clampTo: '(tiles|terrain)'/); }); test('the draw modules are registered for formatting and boundary checks', () => { diff --git a/src/annotations/drawToolBehaviour.test.mjs b/src/annotations/drawToolBehaviour.test.mjs index 4cef4d4fe0..862cae6574 100644 --- a/src/annotations/drawToolBehaviour.test.mjs +++ b/src/annotations/drawToolBehaviour.test.mjs @@ -13,6 +13,8 @@ import { releasePointer, resetPointerOwnership, } from '../data/inputOwnership.js'; +import { fakeInput } from '../input/testDoubles.mjs'; +import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs'; /* ── DOM doubles ───────────────────────────────────────────────────────── */ @@ -68,9 +70,17 @@ class FakeElement { } closest(selector) { // Only what the tool asks: "am I inside an activatable control?" - const activatable = ['button', 'a', 'select', '[role="button"]', '[role="radio"]']; + const activatable = [ + 'button', + 'a', + 'select', + '[role="button"]', + '[role="radio"]', + ]; if (!activatable.some((part) => selector.includes(part))) return null; - return this.tagName === 'BUTTON' || this.tagName === 'A' || this.tagName === 'SELECT' + return this.tagName === 'BUTTON' || + this.tagName === 'A' || + this.tagName === 'SELECT' ? this : null; } @@ -143,39 +153,22 @@ function fakeViewer() { setInputAction: (action, type) => actions.set(type, action), removeInputAction: (type) => actions.delete(type), }; - const attached = []; - const pendingAdds = []; - const dataSources = { - get length() { - return attached.length; - }, - get: (index) => attached[index], - add(source) { - // Cesium resolves this on a later tick — the whole point of finding 7. - const promise = Promise.resolve().then(() => { - attached.push(source); - return source; - }); - pendingAdds.push(promise); - return promise; - }, - remove(source) { - const at = attached.indexOf(source); - if (at >= 0) attached.splice(at, 1); - return at >= 0; - }, - }; return { scene: { canvas, requestRender() {} }, screenSpaceEventHandler: stockHandler, - dataSources, - _attached: attached, _actions: actions, }; } function fakeAnnotations() { - const calls = { annotate: [], clear: 0, restyle: [], setHidden: [], frame: [], remove: [] }; + const calls = { + annotate: [], + clear: 0, + restyle: [], + setHidden: [], + frame: [], + remove: [], + }; const marks = []; const listeners = new Set(); const changed = () => listeners.forEach((listener) => listener()); @@ -223,10 +216,21 @@ function fakeAnnotations() { } /** Stand up a tool against fresh doubles, with globals restored afterwards. */ -function harness({ navigation = null, markActions = [] } = {}) { +function harness({ + navigation = null, + beforeInput = () => {}, + markActions = [], +} = {}) { resetPointerOwnership(); const { byId, documentDouble } = fakeDom(); const viewer = fakeViewer(); + // The viewer's own actions are bound before its input port takes them. + beforeInput(viewer); + const input = fakeInput(viewer); + // The renderer the tool draws its preview with, drawing in the viewer's canvas. + const { draw, unbind: unbindDraw } = bindFakeDraw(viewer, { + canvas: viewer.scene.canvas, + }); const annotations = fakeAnnotations(); const previousDocument = globalThis.document; const previousWindow = globalThis.window; @@ -250,6 +254,7 @@ function harness({ navigation = null, markActions = [] } = {}) { tool, shown, viewer, + draw, annotations, byId, documentDouble, @@ -257,7 +262,10 @@ function harness({ navigation = null, markActions = [] } = {}) { controls, /** A control's change, as the view sends it. */ act: (name, ...args) => controls.actions?.[name]?.(...args), + input, restore() { + input.destroy(); + unbindDraw(); resetPointerOwnership(); if (previousDocument === undefined) delete globalThis.document; else globalThis.document = previousDocument; @@ -288,23 +296,42 @@ test('turning Draw on takes a lease and turning it off gives it back', async () } }); -test('Draw refuses to start when something else holds the pointer', async () => { +test('Draw takes the pointer from another tool, which is told', async () => { const h = harness(); try { - const other = claimPointer('directions'); + let lost = 0; + claimPointer('directions', { onLost: () => (lost += 1) }); h.act('toggleDraw'); - assert.equal(h.tool.active, false, 'it must not half-start'); - assert.equal(pointerOwner(), 'directions', 'and must not steal the claim'); - // Named by its tool, not by the internal owner id. - assert.equal( - h.shown.view.hint, - 'Directions is using the pointer — close it first.', - ); - assert.equal(h.tool.diagnostics().sceneHandler, false, 'no handler was bound'); + assert.equal(h.tool.active, true, 'the newest claim takes over'); + assert.equal(pointerOwner(), 'draw'); + assert.equal(lost, 1, 'the other tool is told once'); + } finally { + h.restore(); + } +}); +test('Draw turns off, as if toggled off, when a newer tool takes the pointer', async () => { + const h = harness({ + beforeInput(viewer) { + viewer.screenSpaceEventHandler.setInputAction(() => {}, LEFT_CLICK); + }, + }); + try { + h.act('toggleDraw'); + assert.equal(h.tool.diagnostics().stockSingleClick, false); + assert.ok(h.tool.addVertex(10, 20), 'a shape is under way'); + const other = claimPointer('directions'); + assert.equal(h.tool.active, false); + assert.equal(h.tool.session, null, 'the half-drawn shape is dropped'); + assert.equal(h.shown.view.active, false, 'the Draw control reads off'); + const after = h.tool.diagnostics(); + assert.equal(after.sceneHandler, false, 'its subscriptions are gone'); + assert.equal(after.stockSingleClick, true, 'the stock clicks are back'); + assert.equal(after.previewItems, 0, 'the preview is cleared'); + assert.equal(pointerOwner(), 'directions', 'the newer tool keeps it'); releasePointer(other); h.act('toggleDraw'); - assert.equal(h.tool.active, true, 'and it starts once the pointer is free'); + assert.equal(h.tool.active, true, 'and it turns on again when asked'); } finally { h.restore(); } @@ -336,30 +363,36 @@ test('a destroyed instance cannot free the pointer its replacement holds', async } }); -test('both stock viewer click actions are borrowed for the session and given back', async () => { - const h = harness(); +test('both stock viewer click actions are held off for the session and given back', async () => { + const stockClick = () => 'viewer picks and selects'; + const stockDouble = () => 'viewer tracks'; + const h = harness({ + beforeInput(viewer) { + viewer.screenSpaceEventHandler.setInputAction(stockClick, LEFT_CLICK); + viewer.screenSpaceEventHandler.setInputAction( + stockDouble, + LEFT_DOUBLE_CLICK, + ); + }, + }); try { - const stockClick = () => 'viewer picks and selects'; - const stockDouble = () => 'viewer tracks'; - h.viewer.screenSpaceEventHandler.setInputAction(stockClick, LEFT_CLICK); - h.viewer.screenSpaceEventHandler.setInputAction(stockDouble, LEFT_DOUBLE_CLICK); - + assert.equal(h.input.stockEnabled('select'), true); h.act('toggleDraw'); assert.equal( - h.viewer.screenSpaceEventHandler.getInputAction(LEFT_CLICK), - undefined, + h.input.stockEnabled('select'), + false, "the viewer's own selecting click must not run while drawing", ); - assert.equal( - h.viewer.screenSpaceEventHandler.getInputAction(LEFT_DOUBLE_CLICK), - undefined, - ); + assert.equal(h.input.stockEnabled('dblclickFollow'), false); h.act('toggleDraw'); + assert.equal(h.input.stockEnabled('select'), true); + assert.equal(h.input.stockEnabled('dblclickFollow'), true); + h.input.destroy(); assert.equal( h.viewer.screenSpaceEventHandler.getInputAction(LEFT_CLICK), stockClick, - 'the exact function is restored, not a replacement', + 'the exact function goes back to the viewer, not a replacement', ); assert.equal( h.viewer.screenSpaceEventHandler.getInputAction(LEFT_DOUBLE_CLICK), @@ -380,20 +413,55 @@ test('Enter finishes from the canvas and the label field, never from a focused b h.tool.addVertex(-97.74, 30.27); // Enter while the Clear button has keyboard focus means "press Clear". - h.documentDouble.emit('keydown', { key: 'Enter', target: h.element('draw-clear') }); + h.documentDouble.emit('keydown', { + key: 'Enter', + target: h.element('draw-clear'), + }); await Promise.resolve(); assert.equal( h.annotations.calls.annotate.length, 0, 'a focused button keeps its own Enter', ); - assert.equal(h.tool.session.vertices.length, 3, 'and the shape is untouched'); + assert.equal( + h.tool.session.vertices.length, + 3, + 'and the shape is untouched', + ); // Enter from the page body (the canvas has focus in practice) finishes it. - h.documentDouble.emit('keydown', { key: 'Enter', target: h.documentDouble.body }); + h.documentDouble.emit('keydown', { + key: 'Enter', + target: h.documentDouble.body, + }); await Promise.resolve(); await Promise.resolve(); - assert.equal(h.annotations.calls.annotate.length, 1, 'Enter on the map finishes'); + assert.equal( + h.annotations.calls.annotate.length, + 1, + 'Enter on the map finishes', + ); + assert.equal(h.annotations.calls.annotate[0].specs[0].type, 'area'); + } finally { + h.restore(); + } +}); + +test('Enter on the globe canvas finishes, as after the render failure notice hands focus back', async () => { + const h = harness(); + try { + h.act('toggleDraw'); + h.tool.setShape('area'); + h.tool.addVertex(-97.75, 30.26); + h.tool.addVertex(-97.74, 30.26); + h.tool.addVertex(-97.74, 30.27); + + // src/ui/views/panels/RenderFailure.vue focuses the canvas when the globe + // draws again and the control that had focus is gone. + h.documentDouble.emit('keydown', { key: 'Enter', target: h.viewer.scene.canvas }); + await Promise.resolve(); + await Promise.resolve(); + assert.equal(h.annotations.calls.annotate.length, 1, 'Enter on the canvas finishes'); assert.equal(h.annotations.calls.annotate[0].specs[0].type, 'area'); } finally { h.restore(); @@ -408,21 +476,29 @@ test('the live preview hangs at the height the click landed on', async () => { h.tool.addVertex(-97.75, 30.26, 187.5); h.tool.addVertex(-97.74, 30.26, 212.25); - await h.tool.whenSettled(); - const source = h.viewer._attached[0] ?? null; - assert.ok(source, 'the preview data source is attached'); - const points = source.entities.values.filter((entity) => entity.point); - assert.equal(points.length, 2, 'one preview dot per vertex'); - const heights = points.map((entity) => { - const position = entity.position.getValue(Cesium.JulianDate.now()); - return Cesium.Cartographic.fromCartesian(position).height; - }); + const dots = [...h.draw.sets.values()].find( + (set) => !set.disposed && set.kind === 'points', + ); + assert.equal(dots.items.size, 2, 'one preview dot per vertex'); + const heights = [...dots.items.values()].map((item) => item.pos.height); + const band = [...h.draw.sets.values()] + .find((set) => !set.disposed && set.kind === 'lines') + .items.get('band'); + assert.equal( + band.positions.length, + 2, + 'the rubber band joins the vertices', + ); + assert.equal(band.mode, 'geodesic', 'it follows the globe, not draped'); assert.ok(Math.abs(heights[0] - 187.5) < 0.5, `got ${heights[0]}`); assert.ok(Math.abs(heights[1] - 212.25) < 0.5, `got ${heights[1]}`); // …and the finished shape is still flattened, deliberately: the renderer // drapes, so a height carried further would be discarded out of sight. - h.documentDouble.emit('keydown', { key: 'Enter', target: h.documentDouble.body }); + h.documentDouble.emit('keydown', { + key: 'Enter', + target: h.documentDouble.body, + }); await Promise.resolve(); await Promise.resolve(); const spec = h.annotations.calls.annotate[0].specs[0]; @@ -435,17 +511,60 @@ test('the live preview hangs at the height the click landed on', async () => { } }); -test('destroy in the same tick as init still removes the preview data source', async () => { +test('the rubber band follows the pointer, closes an area and takes the chosen colour', async () => { const h = harness(); try { - // Nothing has been attached yet — dataSources.add() resolves later. - assert.equal(h.viewer._attached.length, 0, 'the add is still pending'); - await h.tool.destroy(); - await Promise.resolve(); + const sets = () => [...h.draw.sets.values()].filter((set) => !set.disposed); + const band = () => + sets() + .find((set) => set.kind === 'lines') + .items.get('band'); + h.act('toggleDraw'); + h.tool.setShape('area'); + h.tool.addVertex(-97.75, 30.26); + assert.equal(band(), undefined, 'one vertex and no pointer draw no band'); + h.tool.addVertex(-97.74, 30.26); + h.tool.addVertex(-97.74, 30.27); assert.equal( - h.viewer._attached.length, + band().positions.length, + 4, + 'an area of three closes back to its first vertex', + ); + assert.deepEqual(band().positions[3], band().positions[0]); + + h.tool.setColor('red'); + assert.deepEqual( + band().style.color, + [1, 107 / 255, 107 / 255, 0.9], + 'the band takes the colour', + ); + assert.deepEqual( + band().depthFail, + { kind: 'dash', color: [139 / 255, 233 / 255, 1, 0.35], length: 16 }, + 'behind the surface it stays the primary colour, dashed, as before', + ); + assert.equal(band().style.kind, 'dash'); + assert.equal(band().style.length, 16); + assert.equal(band().widthPx, 3); + + h.tool.setShape('pin'); + assert.equal(band(), undefined, 'a pin has no rubber band'); + } finally { + h.restore(); + } +}); + +test('destroy in the same tick as init disposes the preview sets', async () => { + const h = harness(); + try { + const live = () => [...h.draw.sets.values()].filter((set) => !set.disposed); + assert.equal(live().length, 2, 'the rubber band and the vertex dots'); + await h.tool.destroy(); + assert.equal(live().length, 0, 'nothing is left drawn behind the teardown'); + assert.equal( + h.tool.diagnostics().previewSets, 0, - 'the preview must not be left attached behind the teardown', + 'no live tool draws a preview', ); } finally { h.restore(); @@ -469,7 +588,11 @@ test('destroy releases the pointer, the handler, the listeners and the stock act assert.equal(isPointerFree(), true, 'the pointer is free'); const after = h.tool.diagnostics(); assert.equal(after.destroyed, true); - assert.equal(after.sceneHandler, false, 'the Cesium handler is gone'); + assert.equal( + after.sceneHandler, + false, + 'the pointer subscriptions are gone', + ); assert.equal(after.domListeners, 0, 'every DOM listener came off'); assert.equal(h.documentDouble.listeners.length, 0, 'including the keydown'); assert.equal(h.controls.actions, null, 'and the controls are disconnected'); @@ -478,8 +601,12 @@ test('destroy releases the pointer, the handler, the listeners and the stock act stockClick, 'the viewer got its selecting click back', ); - assert.equal(h.viewer._attached.length, 0, 'the preview data source is detached'); - assert.equal(h.annotations.listeners.size, 0, 'and it no longer follows the board'); + assert.equal(after.previewSets, 0, 'the preview sets are disposed'); + assert.equal( + h.annotations.listeners.size, + 0, + 'and it no longer follows the board', + ); // Idempotent: a second destroy is harmless. await h.tool.destroy(); @@ -498,7 +625,11 @@ test('Clear wipes the board and the shape in progress', async () => { h.act('clearDraw'); assert.equal(h.annotations.calls.clear, 1, 'placed marks are removed'); - assert.equal(h.tool.session.vertices.length, 0, 'and so is the shape in progress'); + assert.equal( + h.tool.session.vertices.length, + 0, + 'and so is the shape in progress', + ); } finally { h.restore(); } @@ -512,7 +643,13 @@ test('the controls choose the shape and colour the next shape is drawn with; it h.act('setDrawColor', 'amber'); assert.deepEqual( { ...h.shown.view, hint: undefined }, - { active: true, shape: 'line', color: 'amber', hint: undefined, marks: [] }, + { + active: true, + shape: 'line', + color: 'amber', + hint: undefined, + marks: [], + }, 'the view shows what the controls chose', ); h.act('setDrawColor', 'purple'); @@ -524,7 +661,10 @@ test('the controls choose the shape and colour the next shape is drawn with; it assert.equal(h.tool.session.vertices.length, 0); h.tool.addVertex(-97.75, 30.26); h.tool.addVertex(-97.74, 30.26); - h.documentDouble.emit('keydown', { key: 'Enter', target: h.documentDouble.body }); + h.documentDouble.emit('keydown', { + key: 'Enter', + target: h.documentDouble.body, + }); await Promise.resolve(); await Promise.resolve(); const spec = h.annotations.calls.annotate[0].specs[0]; @@ -549,12 +689,31 @@ test('each drawn shape is a row whose actions reach the board, and fly-to is a n try { const board = h.annotations; board.marks.push( - { id: 'a1', type: 'route', manual: true, name: null, label: '950 m', color: 'amber', hidden: false }, - { id: 'a2', type: 'pin', manual: false, label: 'Voice pin', color: 'primary', hidden: false }, + { + id: 'a1', + type: 'route', + manual: true, + name: null, + label: '950 m', + color: 'amber', + hidden: false, + }, + { + id: 'a2', + type: 'pin', + manual: false, + label: 'Voice pin', + color: 'primary', + hidden: false, + }, ); board.changed(); assert.deepEqual( - h.shown.view.marks.map(({ id, placeholder, hidden }) => ({ id, placeholder, hidden })), + h.shown.view.marks.map(({ id, placeholder, hidden }) => ({ + id, + placeholder, + hidden, + })), [{ id: 'a1', placeholder: 'Line · 950 m', hidden: false }], 'only hand-drawn marks are listed, an unnamed line by its length', ); @@ -569,7 +728,11 @@ test('each drawn shape is a row whose actions reach the board, and fly-to is a n ]); assert.deepEqual(board.calls.setHidden, [['a1', true]]); assert.deepEqual(board.calls.frame, ['a1']); - assert.deepEqual(navigations, ['drawing'], 'fly-to goes through the navigation policy'); + assert.deepEqual( + navigations, + ['drawing'], + 'fly-to goes through the navigation policy', + ); assert.deepEqual(board.calls.remove, ['a1']); assert.deepEqual(h.shown.view.marks, [], 'the row goes with its mark'); } finally { @@ -577,7 +740,7 @@ test('each drawn shape is a row whose actions reach the board, and fly-to is a n } }); -test('an application\'s row actions show on the shapes they are for and run with the shape', async () => { +test("row actions given to the tool show on the shapes they are for and run with the shape", async () => { const ran = []; const h = harness({ markActions: [ @@ -601,30 +764,102 @@ test('an application\'s row actions show on the shapes they are for and run with try { const board = h.annotations; board.marks.push( - { id: 'r1', type: 'area', manual: true, name: 'Strait', color: 'primary', hidden: false, ring: [[29, 41], [29.1, 41], [29.1, 41.1]] }, - { id: 'l1', type: 'route', manual: true, name: null, label: '9 km', color: 'amber', hidden: false, path: [{ lon: 29, lat: 41.05, height: 0 }, { lon: 29.1, lat: 41.05, height: 0 }] }, - { id: 'p1', type: 'pin', manual: true, name: 'Camp', color: 'red', hidden: false }, + { + id: 'r1', + type: 'area', + manual: true, + name: 'Strait', + color: 'primary', + hidden: false, + ring: [ + [29, 41], + [29.1, 41], + [29.1, 41.1], + ], + }, + { + id: 'l1', + type: 'route', + manual: true, + name: null, + label: '9 km', + color: 'amber', + hidden: false, + path: [ + { lon: 29, lat: 41.05, height: 0 }, + { lon: 29.1, lat: 41.05, height: 0 }, + ], + }, + { + id: 'p1', + type: 'pin', + manual: true, + name: 'Camp', + color: 'red', + hidden: false, + }, ); board.changed(); assert.deepEqual( h.shown.view.marks.map(({ id, actions }) => [id, actions]), [ - ['r1', [ - { id: 'tag', icon: 'sell', label: 'Tag Strait' }, - { id: 'measure', icon: 'straighten', label: 'Measure Strait' }, - ]], + [ + 'r1', + [ + { id: 'tag', icon: 'sell', label: 'Tag Strait' }, + { id: 'measure', icon: 'straighten', label: 'Measure Strait' }, + ], + ], ['l1', [{ id: 'tag', icon: 'sell', label: 'Tag Line · 9 km' }]], ['p1', []], ], ); assert.equal(h.act('runDrawMarkAction', 'l1', 'tag'), true); - assert.equal(h.act('runDrawMarkAction', 'l1', 'measure'), false, 'a line is not offered an area action'); + assert.equal( + h.act('runDrawMarkAction', 'l1', 'measure'), + false, + 'a line is not offered an area action', + ); assert.equal(h.act('runDrawMarkAction', 'p1', 'tag'), false); assert.equal(h.act('runDrawMarkAction', 'gone', 'tag'), false); assert.equal(h.act('runDrawMarkAction', 'r1', 'measure'), true); assert.deepEqual(ran, [ - ['tag', { id: 'l1', shape: 'line', name: '', title: 'Line · 9 km', geometry: { type: 'LineString', coordinates: [[29, 41.05], [29.1, 41.05]] } }], - ['measure', { id: 'r1', shape: 'area', name: 'Strait', title: 'Strait', geometry: { type: 'Polygon', coordinates: [[[29, 41], [29.1, 41], [29.1, 41.1], [29, 41]]] } }], + [ + 'tag', + { + id: 'l1', + shape: 'line', + name: '', + title: 'Line · 9 km', + geometry: { + type: 'LineString', + coordinates: [ + [29, 41.05], + [29.1, 41.05], + ], + }, + }, + ], + [ + 'measure', + { + id: 'r1', + shape: 'area', + name: 'Strait', + title: 'Strait', + geometry: { + type: 'Polygon', + coordinates: [ + [ + [29, 41], + [29.1, 41], + [29.1, 41.1], + [29, 41], + ], + ], + }, + }, + ], ]); } finally { h.restore(); @@ -634,16 +869,40 @@ test('an application\'s row actions show on the shapes they are for and run with test('an action that throws is reported and leaves the row alone', async () => { const h = harness({ markActions: [ - { id: 'boom', icon: 'bolt', label: () => { throw new Error('label'); }, shapes: ['area'], run: () => { throw new Error('run'); } }, + { + id: 'boom', + icon: 'bolt', + label: () => { + throw new Error('label'); + }, + shapes: ['area'], + run: () => { + throw new Error('run'); + }, + }, ], }); const warn = console.warn; const warned = []; console.warn = (...args) => warned.push(args[0]); try { - h.annotations.marks.push({ id: 'r1', type: 'area', manual: true, name: null, color: 'primary', hidden: false, ring: [[0, 0], [1, 0], [1, 1]] }); + h.annotations.marks.push({ + id: 'r1', + type: 'area', + manual: true, + name: null, + color: 'primary', + hidden: false, + ring: [ + [0, 0], + [1, 0], + [1, 1], + ], + }); h.annotations.changed(); - assert.deepEqual(h.shown.view.marks[0].actions, [{ id: 'boom', icon: 'bolt', label: 'boom' }]); + assert.deepEqual(h.shown.view.marks[0].actions, [ + { id: 'boom', icon: 'bolt', label: 'boom' }, + ]); assert.equal(h.act('runDrawMarkAction', 'r1', 'boom'), false); assert.deepEqual(warned, ['[draw] boom failed']); } finally { @@ -652,7 +911,7 @@ test('an action that throws is reported and leaves the row alone', async () => { } }); -test('what a row action answers is its row\'s note; the row is busy until then, and a removed shape drops it', async () => { +test("what a row action answers is its row's note; the row is busy until then, and a removed shape drops it", async () => { const pending = []; const h = harness({ markActions: [ @@ -661,34 +920,73 @@ test('what a row action answers is its row\'s note; the row is busy until then, icon: 'straighten', label: (name) => `Measure ${name}`, shapes: ['area'], - run: () => new Promise((resolve, reject) => pending.push({ resolve, reject })), + run: () => + new Promise((resolve, reject) => pending.push({ resolve, reject })), + }, + { + id: 'now', + icon: 'bolt', + label: () => 'Now', + shapes: ['area'], + run: () => ' 12 km² ', + }, + { + id: 'long', + icon: 'notes', + label: () => 'Long', + shapes: ['area'], + run: () => `${'word '.repeat(60)}end`, }, - { id: 'now', icon: 'bolt', label: () => 'Now', shapes: ['area'], run: () => ' 12 km² ' }, - { id: 'long', icon: 'notes', label: () => 'Long', shapes: ['area'], run: () => `${'word '.repeat(60)}end` }, ], }); const warn = console.warn; console.warn = () => {}; try { const board = h.annotations; - const area = (id) => ({ id, type: 'area', manual: true, name: null, color: 'primary', hidden: false, ring: [[0, 0], [1, 0], [1, 1]] }); + const area = (id) => ({ + id, + type: 'area', + manual: true, + name: null, + color: 'primary', + hidden: false, + ring: [ + [0, 0], + [1, 0], + [1, 1], + ], + }); board.marks.push(area('r1'), area('r2')); board.changed(); const row = (id) => h.shown.view.marks.find((entry) => entry.id === id); assert.equal(h.act('runDrawMarkAction', 'r1', 'now'), true); assert.deepEqual([row('r1').busy, row('r1').note], [false, '12 km²']); h.act('runDrawMarkAction', 'r1', 'long'); - assert.ok(row('r1').note.length <= 200 && row('r1').note.endsWith('word…'), 'a long note is cut at a word'); + assert.ok( + row('r1').note.length <= 200 && row('r1').note.endsWith('word…'), + 'a long note is cut at a word', + ); assert.equal(h.act('runDrawMarkAction', 'r1', 'measure'), true); assert.deepEqual([row('r1').busy, row('r1').note], [true, '']); - assert.equal(h.act('runDrawMarkAction', 'r1', 'now'), false, 'a busy row takes no second press'); + assert.equal( + h.act('runDrawMarkAction', 'r1', 'now'), + false, + 'a busy row takes no second press', + ); pending[0].resolve('412 km², 38 km of edge'); await new Promise((resolve) => setTimeout(resolve, 0)); - assert.deepEqual([row('r1').busy, row('r1').note], [false, '412 km², 38 km of edge']); + assert.deepEqual( + [row('r1').busy, row('r1').note], + [false, '412 km², 38 km of edge'], + ); h.act('runDrawMarkAction', 'r1', 'measure'); pending[1].reject(new Error('refused')); await new Promise((resolve) => setTimeout(resolve, 0)); - assert.deepEqual([row('r1').busy, row('r1').note], [false, ''], 'a failure clears the note'); + assert.deepEqual( + [row('r1').busy, row('r1').note], + [false, ''], + 'a failure clears the note', + ); h.act('runDrawMarkAction', 'r2', 'measure'); board.marks.splice(1, 1); board.changed(); @@ -697,7 +995,11 @@ test('what a row action answers is its row\'s note; the row is busy until then, assert.equal(row('r2'), undefined); board.marks.push(area('r2')); board.changed(); - assert.deepEqual([row('r2').busy, row('r2').note], [false, ''], 'a late answer never reaches a shape that went'); + assert.deepEqual( + [row('r2').busy, row('r2').note], + [false, ''], + 'a late answer never reaches a shape that went', + ); } finally { console.warn = warn; h.restore(); @@ -710,30 +1012,49 @@ test('Backspace on the page removes the last vertex', () => { h.act('toggleDraw'); h.tool.addVertex(-97.75, 30.26); h.tool.addVertex(-97.74, 30.26); - h.documentDouble.emit('keydown', { key: 'Backspace', target: h.documentDouble.body }); + h.documentDouble.emit('keydown', { + key: 'Backspace', + target: h.documentDouble.body, + }); assert.equal(h.tool.session.vertices.length, 1); } finally { h.restore(); } }); -test('keys on the shape list are the list\'s, not the drawing\'s', async () => { +test("keys on the shape list are the list's, not the drawing's", async () => { const h = harness(); try { const listButton = new FakeElement('BUTTON'); - listButton.closest = (selector) => (selector === '#draw-mark-list' ? {} : null); + listButton.closest = (selector) => + selector === '#draw-mark-list' ? {} : null; const elsewhere = new FakeElement('INPUT', 'location-search'); h.act('toggleDraw'); h.tool.addVertex(-97.75, 30.26); h.tool.addVertex(-97.74, 30.26); h.documentDouble.emit('keydown', { key: 'Escape', target: listButton }); - assert.equal(h.tool.session.vertices.length, 2, 'Escape in the list keeps the shape'); + assert.equal( + h.tool.session.vertices.length, + 2, + 'Escape in the list keeps the shape', + ); assert.equal(h.tool.active, true, 'and keeps Draw on'); h.documentDouble.emit('keydown', { key: 'Enter', target: elsewhere }); await Promise.resolve(); - assert.equal(h.annotations.calls.annotate.length, 0, 'another field keeps its Enter'); - h.documentDouble.emit('keydown', { key: 'Escape', target: h.documentDouble.body }); - assert.equal(h.tool.session.vertices.length, 0, 'Escape on the page drops the open shape'); + assert.equal( + h.annotations.calls.annotate.length, + 0, + 'another field keeps its Enter', + ); + h.documentDouble.emit('keydown', { + key: 'Escape', + target: h.documentDouble.body, + }); + assert.equal( + h.tool.session.vertices.length, + 0, + 'Escape on the page drops the open shape', + ); } finally { h.restore(); } diff --git a/src/annotations/hybridAnnotationRenderer.test.mjs b/src/annotations/hybridAnnotationRenderer.test.mjs index cf61502c47..ef56dea496 100644 --- a/src/annotations/hybridAnnotationRenderer.test.mjs +++ b/src/annotations/hybridAnnotationRenderer.test.mjs @@ -5,6 +5,9 @@ import { createPinia } from 'pinia'; import { useScreenAnnotationsStore } from '../ui/stores/screenAnnotations.js'; import { createHybridAnnotationRenderer } from './hybridAnnotationRenderer.js'; import { showOsmCredit, hideOsmCredit } from '../data/dataCredits.js'; +import { bindFakeCesiumCredits, fakeCesiumCredits } from '../testSupport/fakeCreditsPort.mjs'; +import { bindRenderer } from '../render/rendererOf.js'; +import { bindFakeCesiumScene } from '../testSupport/fakeCesiumScene.mjs'; /** A hybrid renderer whose screen board is presented to its own store. */ function hybridWithBoard(viewer) { @@ -89,11 +92,41 @@ function installBrowserGlobals(t) { }); } +/** + * `viewer` with the fake scene's camera, query, frame and draw ports and the + * fake credits bound over it as one renderer. + */ +function withScenePorts(viewer) { + const { unbind, ...ports } = bindFakeCesiumScene(viewer); + unbind(); + bindRenderer(viewer, { ...ports, credits: fakeCesiumCredits(viewer) }); + return ports.draw; +} + +/** What the world renderer draws, each item of its live sets (of `kind`). */ +function worldItems(draw, kind) { + const items = []; + for (const record of draw.sets.values()) + if ( + !record.disposed && + record.spec.id.startsWith('annotations:') && + (!kind || record.kind === kind) + ) + items.push(...record.items.values()); + return items; +} + +/** Surface heights the scene samples: `height(lon, lat)` in degrees. */ +function sampleHeights(scene, height) { + scene.sampleHeightSupported = true; + scene.sampleHeight = (carto) => + height(Cesium.Math.toDegrees(carto.longitude), Cesium.Math.toDegrees(carto.latitude)); +} + /** A viewer whose scene/camera is just enough for both sub-renderers. */ function fakeViewer(lon, lat) { const credits = new Set(); const camera = cameraLookingAt(lon, lat); - const dataSources = []; const frames = controlledFrames(); const scene = { camera, @@ -107,31 +140,19 @@ function fakeViewer(lon, lat) { scene.renderRequests += 1; }, }; - return { - dataSources, - frames, - viewer: { - credits, - creditDisplay: { - addStaticCredit: (credit) => credits.add(credit), - removeStaticCredit: (credit) => credits.delete(credit), - }, - scene, - camera, - trackedEntity: null, - dataSources: { - add(dataSource) { - dataSources.push(dataSource); - return dataSource; - }, - remove(dataSource) { - const index = dataSources.indexOf(dataSource); - if (index >= 0) dataSources.splice(index, 1); - return index >= 0; - }, - }, + const viewer = { + credits, + creditDisplay: { + addStaticCredit: (credit) => credits.add(credit), + removeStaticCredit: (credit) => credits.delete(credit), }, + scene, + camera, + canvas: scene.canvas, + trackedEntity: null, }; + const draw = withScenePorts(viewer); + return { draw, frames, viewer }; } function controlledFrames() { @@ -192,7 +213,6 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry' }); const camera = cameraLookingAt(-99, 31); - const dataSources = []; const frames = controlledFrames(); const scene = { camera, @@ -206,19 +226,12 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry' const viewer = { scene, camera, + canvas: scene.canvas, trackedEntity: null, - dataSources: { - add(dataSource) { - dataSources.push(dataSource); - return dataSource; - }, - remove(dataSource) { - const index = dataSources.indexOf(dataSource); - if (index >= 0) dataSources.splice(index, 1); - return index >= 0; - }, - }, }; + // The screen board projects through the renderer's camera and query; the + // world renderer draws through its draw port. + const { draw } = bindFakeCesiumScene(viewer); const { store, renderer } = hybridWithBoard(viewer); const anno = { id: 'anno-hybrid-fb3', @@ -235,8 +248,7 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry' renderer.add(anno); const [before] = annotationGroups(store); assert.equal(childrenWithClass(before, 'gev-anno-ring').length, 2); - assert.equal(dataSources.length, 1); - assert.equal(dataSources[0].entities.values.length, 0); + assert.equal(worldItems(draw).length, 0); const ring = [ [-106, 25], @@ -268,10 +280,10 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry' assert.equal(dot.attrs.cx, expectedWindow.x.toFixed(1)); assert.equal(dot.attrs.cy, expectedWindow.y.toFixed(1)); assert.deepEqual(centroid, { lon: -100.8, lat: 29.4, height: 0 }, 'closed-ring vertex mean stays pinned'); - assert.equal(dataSources[0].entities.values.length, 2, 'world area adds one fill and one outline'); - assert.equal(dataSources[0].entities.values.filter((entity) => entity.polygon).length, 1); - assert.equal(dataSources[0].entities.values.filter((entity) => entity.polyline).length, 1); - assert.equal(Object.hasOwn(anno, '_entities'), false, 'world entity state stays on the inherited proxy'); + assert.equal(worldItems(draw).length, 2, 'world area adds one fill and one outline'); + assert.equal(worldItems(draw, 'shapes').length, 1); + assert.equal(worldItems(draw, 'lines').length, 1); + assert.equal(Object.hasOwn(anno, '_draw'), false, 'world draw state stays on the inherited proxy'); const outer = [ [-99, 31], [-98.999, 31], @@ -298,33 +310,26 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry' buildingHeight: 20, }; const completion = renderer.add(building); - assert.equal(dataSources[0].entities.values.length, 2, 'building geometry waits for all probes'); + assert.equal(worldItems(draw).length, 2, 'building geometry waits for all probes'); for (let frame = 0; frame < 8; frame += 1) frames.emit(); assert.equal((await completion).status, 'installed'); - const added = dataSources[0].entities.values.slice(2); - const fills = added.filter( - (entity) => entity.polygon && entity.polygon.fill?.getValue() !== false, - ); + const fills = worldItems(draw, 'shapes').filter((item) => item.id.startsWith('volume:')); assert.equal( fills.length, 2, - 'every building part gets a classification volume', + 'every building part gets a volume', ); - assert.equal(fills[0].polygon.hierarchy.getValue().holes.length, 1); - assert.equal(fills[1].polygon.hierarchy.getValue().holes.length, 0); + assert.equal(fills[0].geometry.rings.length, 2, 'the first with its hole'); + assert.equal(fills[1].geometry.rings.length, 1); + assert.deepEqual(fills[0].fill, fills[1].fill, 'parts share the fill colour'); assert.equal( - fills[0].polygon.material, - fills[1].polygon.material, - 'parts share the fill material', - ); - assert.equal( - added.filter((entity) => entity.polyline).length, + worldItems(draw, 'lines').filter((item) => item.id.startsWith('base:')).length, 3, 'all outer and hole outlines are retained', ); renderer.remove(building); assert.equal( - dataSources[0].entities.values.length, + worldItems(draw).length, 2, 'multipart removal leaves only the earlier area', ); @@ -341,7 +346,7 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry' test('a sub-renderer throw mid-add leaves state the rollback can still remove', (t) => { installBrowserGlobals(t); - const { viewer, dataSources } = fakeViewer(-99, 31); + const { viewer, draw } = fakeViewer(-99, 31); const { store, renderer } = hybridWithBoard(viewer); const ring = [[-106, 25], [-93, 25], [-93, 36], [-106, 36], [-106, 25]]; const anno = { @@ -369,26 +374,26 @@ test('a sub-renderer throw mid-add leaves state the rollback can still remove', }; assert.throws(() => renderer.add(anno), /screen insert failed/); - assert.equal(dataSources[0].entities.values.length, 2, 'the world drape is already live'); + assert.equal(worldItems(draw).length, 2, 'the world drape is already live'); assert.equal(annotationGroups(store).length, 0, 'the half-built screen group detached itself'); // The engine's rollback path — it must reach the partial state by id. renderer.remove(anno); - assert.equal(dataSources[0].entities.values.length, 0, 'partial world state must be released'); + assert.equal(worldItems(draw).length, 0, 'partial world state must be released'); // …and the id is free again: a retry draws ONE mark, not a second one over // an orphan nothing owns. renderer.add(anno); - assert.equal(dataSources[0].entities.values.length, 2, 'the retry draws exactly one world drape'); + assert.equal(worldItems(draw).length, 2, 'the retry draws exactly one world drape'); assert.equal(annotationGroups(store).length, 1, 'and exactly one screen caption'); renderer.remove(anno); - assert.equal(dataSources[0].entities.values.length, 0); + assert.equal(worldItems(draw).length, 0); renderer.destroy(); }); test('a release that throws keeps the mark addressable for a retry cleanup', (t) => { installBrowserGlobals(t); - const { viewer, dataSources } = fakeViewer(-99, 31); + const { viewer, draw } = fakeViewer(-99, 31); const { store, renderer } = hybridWithBoard(viewer); const ring = [[-106, 25], [-93, 25], [-93, 36], [-106, 36], [-106, 25]]; const anno = { @@ -404,7 +409,7 @@ test('a release that throws keeps the mark addressable for a retry cleanup', (t) }; renderer.add(anno); - assert.equal(dataSources[0].entities.values.length, 2); + assert.equal(worldItems(draw).length, 2); assert.equal(annotationGroups(store).length, 1); // The world route releases fine, then the screen release fails part-way @@ -412,7 +417,7 @@ test('a release that throws keeps the mark addressable for a retry cleanup', (t) const workingSetTimeout = globalThis.window.setTimeout; globalThis.window.setTimeout = () => { throw new Error('teardown scheduling failed'); }; assert.throws(() => renderer.remove(anno), /teardown scheduling failed/); - assert.equal(dataSources[0].entities.values.length, 0, 'the world route did release'); + assert.equal(worldItems(draw).length, 0, 'the world route did release'); assert.equal(annotationGroups(store).length, 1, 'the screen route did NOT — that is the orphan'); // Dropping the routing entry here would make that orphan permanently @@ -420,7 +425,7 @@ test('a release that throws keeps the mark addressable for a retry cleanup', (t) globalThis.window.setTimeout = workingSetTimeout; renderer.remove(anno); assert.equal(annotationGroups(store).length, 0, 'the retry cleanup must reach the orphan'); - assert.equal(dataSources[0].entities.values.length, 0, 'without double-releasing the world route'); + assert.equal(worldItems(draw).length, 0, 'without double-releasing the world route'); // Fully released now — a third call is inert. renderer.remove(anno); @@ -430,7 +435,7 @@ test('a release that throws keeps the mark addressable for a retry cleanup', (t) test('a world add that fails mid-way leaves its landed entities removable', (t) => { installBrowserGlobals(t); - const { viewer, dataSources } = fakeViewer(-99, 31); + const { viewer, draw } = fakeViewer(-99, 31); const { store, renderer } = hybridWithBoard(viewer); const ring = [[-106, 25], [-93, 25], [-93, 36], [-106, 36], [-106, 25]]; const anno = { @@ -446,25 +451,23 @@ test('a world add that fails mid-way leaves its landed entities removable', (t) }; // The draped fill lands; the outline throws (bad geometry / lost context). - const entities = dataSources[0].entities; - const realAdd = entities.add.bind(entities); - let addsLeft = 1; - entities.add = (options) => { - if (addsLeft <= 0) throw new Error('entity add failed'); - addsLeft -= 1; - return realAdd(options); + const realLines = draw.lines; + draw.lines = (spec) => { + const set = realLines(spec); + set.set = () => { throw new Error('draw failed'); }; + return set; }; - assert.throws(() => renderer.add(anno), /entity add failed/); - assert.equal(entities.values.length, 1, 'one entity landed before the failure'); + assert.throws(() => renderer.add(anno), /draw failed/); + assert.equal(worldItems(draw).length, 1, 'one item landed before the failure'); - entities.add = realAdd; + draw.lines = realLines; renderer.remove(anno); - assert.equal(entities.values.length, 0, - 'the rollback must see the entities that landed before the throw'); + assert.equal(worldItems(draw).length, 0, + 'the rollback must see the items that landed before the throw'); renderer.add(anno); - assert.equal(entities.values.length, 2, 'the retry draws a complete mark'); + assert.equal(worldItems(draw).length, 2, 'the retry draws a complete mark'); assert.equal(annotationGroups(store).length, 1); renderer.destroy(); }); @@ -475,7 +478,7 @@ function workTrace() { test('buildings share one probe per frame and preserve probe geometry, filtering and fallback', async (t) => { installBrowserGlobals(t); - const { viewer, dataSources, frames } = fakeViewer(-99, 31); + const { viewer, draw, frames } = fakeViewer(-99, 31); const renderer = createHybridAnnotationRenderer(viewer); t.after(() => renderer.destroy()); const first = buildingAnnotation('sampled-building'); @@ -485,15 +488,12 @@ test('buildings share one probe per frame and preserve probe geometry, filtering showOsmCredit(viewer, otherOwner); const probes = []; const outcomes = [-500, 120, 30, null, new Error('tile unavailable'), 60, 9001, 90]; - viewer.scene.clampToHeight = (position) => { - const cartographic = Cesium.Cartographic.fromCartesian(position); - const lon = Cesium.Math.toDegrees(cartographic.longitude); - const lat = Cesium.Math.toDegrees(cartographic.latitude); + sampleHeights(viewer.scene, (lon, lat) => { probes.push([lon, lat]); const outcome = outcomes[probes.length - 1]; if (outcome instanceof Error) throw outcome; - return outcome == null ? undefined : Cesium.Cartesian3.fromDegrees(lon, lat, outcome); - }; + return outcome == null ? undefined : outcome; + }); // Suppress screen points: these counts concern the eight outside-building // probes, not the screen renderer's separate anchor-height sampling. const firstTrace = workTrace(); @@ -510,14 +510,14 @@ test('buildings share one probe per frame and preserve probe geometry, filtering const firstCompletion = renderer.add(first, { pendingVisible: false, workTrace: firstTrace }); const secondCompletion = renderer.add(second, { pendingVisible: false, workTrace: secondTrace }); assert.equal(probes.length, 0, 'enqueue must not probe synchronously'); - assert.equal(dataSources[0].entities.values.length, 0); + assert.equal(worldItems(draw).length, 0); assert.equal([...viewer.credits].filter(c => c.showOnScreen).length, 1, 'pending outlines add no tile credit to the other owner'); for (let frame = 0; frame < 16; frame += 1) { const before = probes.length; frames.emit(); assert.equal(probes.length, before + 1, 'the two buildings share one total probe budget'); - if (frame < 7) assert.equal(dataSources[0].entities.values.length, 0, 'no partial world parts'); + if (frame < 7) assert.equal(worldItems(draw).length, 0, 'no partial world parts'); } const [installed, fallback] = await Promise.all([firstCompletion, secondCompletion]); assert.equal(installed.status, 'installed'); @@ -540,8 +540,9 @@ test('buildings share one probe per frame and preserve probe geometry, filtering const detail = parent.detail; assert.equal(detail.index, index); assert.equal(detail.status, trace === firstTrace ? 'recorded' : 'missing'); + // The fourth probe finds nothing and the fifth throws: both are misses. assert.equal(detail.clampResult, - trace === firstTrace && index === 4 ? 'threw' : 'returned'); + trace === firstTrace && index !== 3 && index !== 4 ? 'hit' : 'missed'); assert.ok(Number.isFinite(detail.clampStart) && Number.isFinite(detail.clampEnd)); assert.ok(parent.start <= detail.clampStart && detail.clampStart <= detail.clampEnd && detail.clampEnd <= parent.end); if (index === 7) { @@ -571,10 +572,10 @@ test('buildings share one probe per frame and preserve probe geometry, filtering assert.ok(Math.abs(probes[index + 8][1] - probes[index][1]) < 1e-10); } assert.equal(new Set(probes.slice(0, 8).map((point) => point.join(','))).size, 8); - const fills = dataSources[0].entities.values.filter((entity) => entity.polygon?.fill?.getValue() !== false && entity.polygon); + const fills = worldItems(draw, 'shapes').filter((item) => item.id.startsWith('volume:')); assert.equal(fills.length, 2); - assert.ok(Math.abs(fills[0].polygon.height.getValue() - 57) < 1e-6, 'four accepted samples select floor(4 * 0.3), height 60 minus 3'); - assert.ok(Math.abs(fills[1].polygon.height.getValue() - 77) < 1e-6, 'all unavailable probes retain anchor minus building height fallback'); + assert.ok(Math.abs(fills[0].geometry.rings[0][0].height - 57) < 1e-6, 'four accepted samples select floor(4 * 0.3), height 60 minus 3'); + assert.ok(Math.abs(fills[1].geometry.rings[0][0].height - 77) < 1e-6, 'all unavailable probes retain anchor minus building height fallback'); const afterCompletion = probes.length; frames.emit(); assert.equal(probes.length, afterCompletion, 'completion releases the sampler'); @@ -597,7 +598,7 @@ test('a building queued behind others gets its full budget on a slow device', as t.mock.method(globalThis.performance, 'now', () => now); const { viewer, frames } = fakeViewer(-99, 31); const renderer = createHybridAnnotationRenderer(viewer); - viewer.scene.clampToHeight = (position) => position; + sampleHeights(viewer.scene, () => 0); const traces = [workTrace(), workTrace(), workTrace()]; const completions = [0, 0.01, 0.02].map((offset, index) => renderer.add(buildingAnnotation(`queued-${index}`, offset), { @@ -626,10 +627,10 @@ test('building cancellation, queued deadline and destroy prevent saved callbacks installBrowserGlobals(t); t.mock.timers.enable({ apis: ['setTimeout'] }); t.after(() => t.mock.timers.reset()); - const { viewer, dataSources, frames } = fakeViewer(-99, 31); + const { viewer, draw, frames } = fakeViewer(-99, 31); const renderer = createHybridAnnotationRenderer(viewer); let probeCount = 0; - viewer.scene.clampToHeight = (position) => { probeCount += 1; return position; }; + sampleHeights(viewer.scene, () => { probeCount += 1; return 0; }); const cancelled = buildingAnnotation('cancelled-building'); const cancelledTrace = workTrace(); const cancelledCompletion = renderer.add(cancelled, { pendingVisible: false, workTrace: cancelledTrace }); @@ -671,7 +672,7 @@ test('building cancellation, queued deadline and destroy prevent saved callbacks assert.equal(viewer.credits.size, 0); for (const listener of savedTimeout) listener(); assert.equal(probeCount, 1, 'saved callbacks cannot revive timed-out tasks'); - assert.equal(dataSources[0].entities.values.length, 0); + assert.equal(worldItems(draw).length, 0); const pending = buildingAnnotation('destroyed-building'); const destruction = renderer.add(pending, { pendingVisible: false }); @@ -681,7 +682,7 @@ test('building cancellation, queued deadline and destroy prevent saved callbacks for (const listener of savedDestroy) listener(); t.mock.timers.tick(2000); assert.equal(probeCount, 1); - assert.equal(dataSources.length, 0, 'destroy removes the owned data source'); + assert.ok([...draw.sets.values()].every((record) => record.disposed), 'destroy lets every set go'); assert.equal(frames.size, 0, 'destroy removes frame listeners'); assert.equal(viewer.credits.size, 0); }); @@ -690,7 +691,7 @@ test('a timed-out building upgrade keeps its existing pending screen group', asy installBrowserGlobals(t); t.mock.timers.enable({ apis: ['setTimeout'] }); t.after(() => t.mock.timers.reset()); - const { viewer, dataSources, frames } = fakeViewer(-99, 31); + const { viewer, draw, frames } = fakeViewer(-99, 31); const { store, renderer } = hybridWithBoard(viewer); const anno = { ...buildingAnnotation('pending-upgrade'), ring: null, label: 'Building' }; renderer.add(anno); @@ -703,15 +704,15 @@ test('a timed-out building upgrade keeps its existing pending screen group', asy assert.equal(after.key, before.key); assert.equal(others.length, 0); assert.ok(childrenWithClass(after, 'gev-anno-ring').length > 0, 'the honest pending point is not converted'); - assert.equal(dataSources[0].entities.values.length, 0); + assert.equal(worldItems(draw).length, 0); frames.emit(); - assert.equal(dataSources[0].entities.values.length, 0); + assert.equal(worldItems(draw).length, 0); renderer.destroy(); }); test('an asynchronous caption-conversion throw rolls back multipart world geometry and remains removable', async (t) => { installBrowserGlobals(t); - const { viewer, dataSources, frames } = fakeViewer(-99, 31); + const { viewer, draw, frames } = fakeViewer(-99, 31); const { store, renderer } = hybridWithBoard(viewer); const anno = { ...buildingAnnotation('caption-failure'), ring: null, label: 'Building' }; renderer.add(anno); @@ -724,7 +725,7 @@ test('an asynchronous caption-conversion throw rolls back multipart world geomet // Frame projection is still ordinary pending-point work. Arm the failure // only after sampling completes, before its promise converts the caption. for (let frame = 0; frame < 8; frame += 1) frames.emit(); - assert.ok(dataSources[0].entities.values.length > 0, 'multipart world geometry landed before caption conversion'); + assert.ok(worldItems(draw).length > 0, 'multipart world geometry landed before caption conversion'); assert.equal(viewer.credits.size, 2, 'credit belongs to the committed world proxy'); // The caption conversion fails when it presents the converted mark. const publish = store.publish; @@ -747,7 +748,7 @@ test('an asynchronous caption-conversion throw rolls back multipart world geomet assert.equal(captionTrace.slices.filter(s => s.phase === 'ground-step').length, 8); assert.equal(captionTrace.slices.filter(s => s.phase === 'hybrid-complete').length, 1); assert.equal(captionTrace.slices.filter(s => s.phase === 'hybrid-rollback').length, 1); - assert.equal(dataSources[0].entities.values.length, 0, 'all classification, cage and outline parts roll back'); + assert.equal(worldItems(draw).length, 0, 'all classification, cage and outline parts roll back'); assert.equal(viewer.credits.size, 0, 'caption rollback releases that same proxy'); assert.equal(annotationGroups(store).length, 1, 'failed screen cleanup remains addressable'); globalThis.window.setTimeout = workingSetTimeout; @@ -781,6 +782,7 @@ test('a deadline passed during caption conversion leaves a drawn pending point', const live = annotationGroups(store).filter((mark) => !mark.className?.includes('gev-out')); assert.equal(live.length, 1); assert.ok(childrenWithClass(live[0], 'gev-anno-ring').length > 0, 'the pending point still draws'); + assert.notEqual(live[0].display, 'none', 'and is on screen'); renderer.remove(anno); renderer.destroy(); }); diff --git a/src/annotations/outlineRungs.test.mjs b/src/annotations/outlineRungs.test.mjs index 6554e6f61a..016012bbfb 100644 --- a/src/annotations/outlineRungs.test.mjs +++ b/src/annotations/outlineRungs.test.mjs @@ -18,6 +18,7 @@ import { outlineQueryText, } from './outlineRungs.js'; import { createAnnotationResolver } from './resolver.js'; +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; import { decodeOpenFreeMapOutlineTile } from '../sources/openFreeMapOutlines.js'; import { createNominatimOutlineClient } from '../sources/nominatimOutlines.js'; import { createApplicationRequestServices } from '../services/requests.js'; @@ -924,15 +925,17 @@ const PLACES = { }, }; -const viewerAt = (lat, lon, height = 4000) => ({ - camera: { - positionCartographic: { - latitude: (lat * Math.PI) / 180, - longitude: (lon * Math.PI) / 180, - height, +// The resolver reads the camera through the renderer's camera port. +const viewerAt = (lat, lon, height = 4000) => + bindFakeCesiumCamera({ + camera: { + positionCartographic: { + latitude: (lat * Math.PI) / 180, + longitude: (lon * Math.PI) / 180, + height, + }, }, - }, -}); + }); test('default settings: outline, street and building asks send nothing to Overpass', async (t) => { const prior = process.env.OVERPASS_UPSTREAMS; diff --git a/src/annotations/placeOutline.test.mjs b/src/annotations/placeOutline.test.mjs index 7f2acdde36..07e65449a5 100644 --- a/src/annotations/placeOutline.test.mjs +++ b/src/annotations/placeOutline.test.mjs @@ -5,11 +5,14 @@ import assert from 'node:assert/strict'; import { readFileSync } from 'node:fs'; import { FEATURE_SOURCE_METHODS } from '../sources/featureSource.js'; import { createAnnotationResolver } from './resolver.js'; +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; import { polygonsContain } from '../data/adminBoundaries.js'; import { streetFootprint } from './outlineRungs.js'; +import { bindFakeCesiumCredits } from '../testSupport/fakeCreditsPort.mjs'; function viewerAt(lat, lon, height = 20_000) { - return { + // The resolver reads the camera through the renderer's camera port. + return bindFakeCesiumCamera({ camera: { positionCartographic: { latitude: (lat * Math.PI) / 180, @@ -17,7 +20,7 @@ function viewerAt(lat, lon, height = 20_000) { height, }, }, - }; + }); } /** A resolver whose boundary lookups and geocoder record every call. */ @@ -180,10 +183,10 @@ test('a geocoded city or neighborhood upgrades to the bundled outline', async () const credits = []; const cancelled = await city.resolve( 'Austin', - { + bindFakeCesiumCredits({ ...viewerAt(39, -100, 5_000_000), creditDisplay: { addStaticCredit: (credit) => credits.push(credit) }, - }, + }), { signal: controller.signal }, ); const pending = cancelled.resolveOutline(); diff --git a/src/annotations/resolver.js b/src/annotations/resolver.js index 527f451131..5e5506ed44 100644 --- a/src/annotations/resolver.js +++ b/src/annotations/resolver.js @@ -14,7 +14,6 @@ import { nearestPointOnLines, } from '../sources/featureGeometry.js'; import { defaultGeospatial } from '../search/defaults.js'; -import * as Cesium from 'cesium'; import { lookupNeighborhoodRing } from '../data/neighborhoodPolygons.js'; import { lookupNaturalRegionOutline, @@ -45,6 +44,9 @@ import { import { createOutlineRungs } from './outlineRungs.js'; import { unavailablePlaceSearch } from '../search/placeSearch.js'; import { isPickedWorldPosition } from '../data/scenePick.js'; +import { heightsOf } from '../queries/heights.js'; +import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js'; +import { canvasOf, findCamera, findQuery } from '../render/rendererOf.js'; /** Prepare only local dateline outlines for planar admission and centering. */ function localOutlineFrame(fp) { @@ -178,7 +180,7 @@ export function createAnnotationResolver({ * Resolve a single annotation target to a normalized world anchor. * * @param {object} opts - * @param {Cesium.Viewer} opts.viewer + * @param {object} opts.viewer The viewer the renderer is bound to. * @param {string} [opts.target] Place name to geocode. * @param {number} [opts.latitude] Explicit latitude (wins over target). * @param {number} [opts.longitude] Explicit longitude. @@ -2216,11 +2218,10 @@ export function createAnnotationResolver({ */ function viewportProximity(viewer) { try { - const carto = viewer?.camera?.positionCartographic; - if (!carto) return null; - const lat = Cesium.Math.toDegrees(carto.latitude); - const lon = Cesium.Math.toDegrees(carto.longitude); - const radiusKm = Math.max((carto.height / 1000) * 3, 5); + const pose = viewer ? findCamera(viewer)?.pose() : null; + if (!pose) return null; + const { lat, lon } = pose; + const radiusKm = Math.max((pose.height / 1000) * 3, 5); if (![lat, lon, radiusKm].every(Number.isFinite)) return null; return { lat, lon, radiusKm }; } catch { @@ -2231,12 +2232,12 @@ export function createAnnotationResolver({ /** Exported for searchAndFlyTo (src/locations.js), which shares this bias. */ function viewportBias(viewer) { try { - const rect = viewer?.camera?.computeViewRectangle?.(); + const rect = viewer ? findCamera(viewer)?.viewRectangle() : null; if (!rect) return null; - const swLat = Cesium.Math.toDegrees(rect.south).toFixed(4); - const swLng = Cesium.Math.toDegrees(rect.west).toFixed(4); - const neLat = Cesium.Math.toDegrees(rect.north).toFixed(4); - const neLng = Cesium.Math.toDegrees(rect.east).toFixed(4); + const swLat = rect.south.toFixed(4); + const swLng = rect.west.toFixed(4); + const neLat = rect.north.toFixed(4); + const neLng = rect.east.toFixed(4); if ([swLat, swLng, neLat, neLng].some((v) => v === 'NaN')) return null; return `${swLat},${swLng}|${neLat},${neLng}`; } catch { @@ -2289,58 +2290,39 @@ export function createAnnotationResolver({ * name the place, and we anchor the mark to the actual world point under it. */ function pickWorldFromScreen(viewer, nx, ny) { - const scene = viewer?.scene; - if (!scene) return null; - const canvas = scene.canvas; + const query = viewer ? findQuery(viewer) : null; + // The renderer's canvas; a viewer with no renderer bound, its own. + const canvas = canvasOf(viewer); + if (!query || !canvas) return null; const w = canvas.clientWidth || canvas.width || 0; const h = canvas.clientHeight || canvas.height || 0; if (!w || !h) return null; const px = Math.max(0, Math.min(1, nx)) * w; const py = Math.max(0, Math.min(1, ny)) * h; - const pos = new Cesium.Cartesian2(px, py); // Each stage is validated before it is accepted: a depth pick over empty sky - // can return a NaN or centre-of-the-earth Cartesian, and converting one of - // those throws inside Cesium. A degenerate pick IS a missed pick, so it falls - // through to the next stage and ultimately to the caller's null. - let cart = null; - if ( - scene.pickPositionSupported && - typeof scene.pickPosition === 'function' - ) { + // can return a NaN or centre-of-the-earth position, and converting one of + // those throws inside the renderer. A degenerate pick IS a missed pick, so it + // falls through to the next stage and ultimately to the caller's null. + const attempt = (pick) => { try { - cart = scene.pickPosition(pos); + return pick(); } catch { - cart = null; + return null; } - } - if ( - !isPickedWorldPosition(cart) && - typeof viewer.camera.pickEllipsoid === 'function' - ) { - try { - cart = viewer.camera.pickEllipsoid(pos, Cesium.Ellipsoid.WGS84); - } catch { - cart = null; - } - } - if ( - !isPickedWorldPosition(cart) && - typeof viewer.camera.getPickRay === 'function' - ) { - try { - const ray = viewer.camera.getPickRay(pos); - cart = ray ? scene.globe?.pick(ray, scene) || null : null; - } catch { - cart = null; - } - } + }; + // The depth pick answers null where the renderer has no depth support. + let cart = attempt(() => query.pickPosition(px, py)); + if (!isPickedWorldPosition(cart)) + cart = attempt(() => query.pickEllipsoid(px, py)); + if (!isPickedWorldPosition(cart)) + cart = attempt(() => query.pickGlobe(query.pickRay(px, py))); if (!isPickedWorldPosition(cart)) return null; - const carto = Cesium.Cartographic.fromCartesian(cart); + const carto = toLonLatH(cart); if (!carto) return null; return { - lat: Cesium.Math.toDegrees(carto.latitude), - lon: Cesium.Math.toDegrees(carto.longitude), + lat: carto.lat, + lon: carto.lon, // The height the pick actually landed on — a roof, a hillside, or 0 on // the ellipsoid. Callers that only want a coordinate ignore it; the draw // tool's live preview needs it, or the rubber band sinks to sea level @@ -2355,28 +2337,18 @@ export function createAnnotationResolver({ * the tiles for that spot aren't loaded we fall back to the ellipsoid (0). */ function sampleGroundHeight(viewer, lon, lat) { - const scene = viewer?.scene; - if (!scene) return 0; - try { - if ( - scene.clampToHeightSupported && - typeof scene.clampToHeight === 'function' - ) { - const carto = Cesium.Cartographic.fromDegrees(lon, lat); - const surface = Cesium.Cartographic.toCartesian(carto); - const clamped = scene.clampToHeight(surface); - if (clamped) { - const h = Cesium.Cartographic.fromCartesian(clamped).height; - if (Number.isFinite(h)) return h; - } + if (!viewer) return 0; + const heights = heightsOf(viewer); + // A miss is tiles not ready: fall through to the terrain, then 0. + if (heights.supported().clamp) { + const clamped = heights.clampNow(fromDegrees(lon, lat, 0)); + if (clamped) { + const h = toLonLatH(clamped)?.height; + if (Number.isFinite(h)) return h; } - } catch { - /* tiles not ready — fall through */ } - const globeHeight = scene.globe?.getHeight?.( - Cesium.Cartographic.fromDegrees(lon, lat), - ); - return Number.isFinite(globeHeight) && globeHeight > 0 ? globeHeight : 0; + const globeHeight = heights.now({ lon, lat }, { against: 'terrain' }); + return globeHeight !== null && globeHeight > 0 ? globeHeight : 0; } function shortLabel(formattedAddress) { diff --git a/src/annotations/screenAnnotationRenderer.js b/src/annotations/screenAnnotationRenderer.js index 0509a47a56..660a4066a9 100644 --- a/src/annotations/screenAnnotationRenderer.js +++ b/src/annotations/screenAnnotationRenderer.js @@ -1,4 +1,4 @@ -import * as Cesium from 'cesium'; +import { followedOf } from '../data/followed.js'; import { getOverlayPaintRect } from '../overlays/worldOverlay.js'; import { getActiveTrackedReadoutId, @@ -8,6 +8,15 @@ import { t } from '../i18n/index.js'; import { nextTick } from 'vue'; import { useScreenAnnotationsStore } from '../ui/stores/screenAnnotations.js'; import { applicationPinia } from '../ui/vueRuntime.js'; +import { heightsOf } from '../queries/heights.js'; +import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js'; +import { distance } from '../geo/vector.js'; +import { + canvasOf as sceneCanvasOf, + findCamera, + findFrame, + findQuery, +} from '../render/rendererOf.js'; /** A label whose detailed outline could not be resolved. */ function outlineUnavailableLabel(label) { @@ -78,11 +87,13 @@ export function createScreenAnnotationRenderer( const arrowMarkers = new Map(); let viewBox = null; - const scene = viewer.scene; - const occluder = new Cesium.EllipsoidalOccluder( - Cesium.Ellipsoid.WGS84, - scene.camera.positionWC, - ); + // The eye this frame is projected from (the camera port's pose), and the + // query port and canvas it is projected through, read once per pass. + let pose = null; + let passQuery = null; + let passCanvas = null; + // The renderer's canvas; a viewer with no renderer bound, its own. + const canvasOf = () => sceneCanvasOf(viewer); const records = new Map(); // anno.id -> { key, anno, group, parts } const leaving = new Map(); // key -> a removed mark's record while it fades out const byKey = new Map(); // key -> record, live or fading @@ -91,8 +102,6 @@ export function createScreenAnnotationRenderer( let published = ''; // Only the renderer whose board the store shows may change or remove it. const shown = () => store.board?.owner === owner; - const scratch = new Cesium.Cartesian2(); - const scratchDir = new Cesium.Cartesian3(); // Per-point ground height cache. Marks must sit on the real surface, not at // sea level — otherwise in elevated cities (Austin ~150 m) they project // underground and parallax sinks them at oblique angles. Sampled once the @@ -121,7 +130,7 @@ export function createScreenAnnotationRenderer( // Re-project every annotation each rendered frame so marks stay glued to the // world. postRender runs after the camera/tiles update, so positions are exact. const onPostRender = () => projectAll(); - scene.postRender.addEventListener(onPostRender); + const removePostRender = findFrame(viewer)?.on('postRender', onPostRender); function color(anno) { return PALETTE[anno.color] || PALETTE.primary; @@ -141,15 +150,12 @@ export function createScreenAnnotationRenderer( return cached.h; } try { - if ( - scene.clampToHeightSupported && - typeof scene.clampToHeight === 'function' - ) { - const c = scene.clampToHeight( - Cesium.Cartesian3.fromDegrees(lon, lat, 0), - ); + const heights = heightsOf(viewer); + if (heights.supported().clamp) { + // A miss is tiles not ready. + const c = heights.clampNow(fromDegrees(lon, lat, 0)); if (c) { - const h = Cesium.Cartographic.fromCartesian(c).height; + const h = toLonLatH(c)?.height; if (Number.isFinite(h) && h > -430 && h < 9000) { heightCache.set(key, { h, settled: true, gen: projGen }); trimHeightCache(); @@ -278,7 +284,7 @@ export function createScreenAnnotationRenderer( } // Record the mark BEFORE it reaches the board, then unwind on any throw - // from here down (projectAll reaches into Cesium and can fail on a lost + // from here down (projectAll reaches into the renderer and can fail on a lost // context). Previously a throw past the insert left an ORPHANED mark: the // engine's rollback only deletes its own map entry, so the next annotate // of the same geometry stacked a fresh mark on top of the corpse. @@ -363,26 +369,27 @@ export function createScreenAnnotationRenderer( // Anchor at the real surface height (cached + validated), so marks sit on // the ground/building instead of at sea level. The settle-once cache keeps // it stable (no per-frame jitter that earlier broke nearby projections). - const world = Cesium.Cartesian3.fromDegrees( - lon, - lat, - groundHeight(lon, lat), - ); + const world = fromDegrees(lon, lat, groundHeight(lon, lat)); + if (!pose) return null; // Reject points behind the camera (they produce wrapped/extreme coords). - Cesium.Cartesian3.subtract(world, scene.camera.positionWC, scratchDir); - if (Cesium.Cartesian3.dot(scratchDir, scene.camera.directionWC) <= 0) + const eye = pose.position; + const look = pose.direction; + if ( + (world.x - eye.x) * look.x + + (world.y - eye.y) * look.y + + (world.z - eye.z) * look.z <= + 0 + ) return null; // Reject points beyond the globe horizon. - if (!occluder.isPointVisible(world)) return null; - const win = Cesium.SceneTransforms.worldToWindowCoordinates( - scene, - world, - scratch, - ); + const query = passQuery; + if (!query || query.isOccluded(world)) return null; + const win = query.project(world); if (!win || !Number.isFinite(win.x) || !Number.isFinite(win.y)) return null; // Reject absurd off-screen projections (anchor not in view). - const w = scene.canvas.clientWidth || scene.canvas.width; - const h = scene.canvas.clientHeight || scene.canvas.height; + const canvas = passCanvas; + const w = canvas.clientWidth || canvas.width; + const h = canvas.clientHeight || canvas.height; if ( !allowOffscreen && (win.x < -w || win.x > 2 * w || win.y < -h || win.y > 2 * h) @@ -399,9 +406,13 @@ export function createScreenAnnotationRenderer( // from the host's ACTUAL painted rectangle after final layout; the billboard extent // is unioned for aircraft/satellites that also own a native tracked graphic. const TRACKED_BBOX_MARGIN = 8; // px buffer added around the footprint - const TRACKED_FADE_EASE = 0.22; // per-frame ease toward hidden(0) / visible(1) + // Ease toward hidden(0) / visible(1): this share of the gap closes in one + // 60 Hz frame (about 200 ms to settle), scaled by elapsed time so the fade + // takes as long at any refresh rate. + const TRACKED_FADE_EASE = 0.22; + const TRACKED_FADE_FRAME_MS = 1000 / 60; + let trackedFadeAtMs = -Infinity; const TRACKED_HYSTERESIS_PX = 18; // dead-band so the overlap test can't flip-flop - const _scratchTrackedWin = new Cesium.Cartesian2(); // Evaluate a NearFarScalar (billboard scaleByDistance) at a camera distance. function nearFarValue(nfs, dist) { @@ -422,32 +433,23 @@ export function createScreenAnnotationRenderer( let top = painted?.y; let bottom = painted ? painted.y + painted.h : undefined; - const ent = viewer.trackedEntity; - const now = Cesium.JulianDate.now(); + const followed = followedOf(viewer); + const displayPosition = followed?.displayPosition; const world = - typeof ent?.gevDisplayPosition === 'function' - ? ent.gevDisplayPosition() - : null; - const win = world - ? Cesium.SceneTransforms.worldToWindowCoordinates( - scene, - world, - _scratchTrackedWin, - ) - : null; + typeof displayPosition === 'function' ? displayPosition() : null; + const win = world ? (passQuery?.project(world) ?? null) : null; - // Billboard box — centered on the anchor, magnified by scaleByDistance. - const bb = ent?.billboard; - if (bb && win && Number.isFinite(win.x) && Number.isFinite(win.y)) { - const baseW = bb.width?.getValue?.(now) ?? 28; - const baseH = bb.height?.getValue?.(now) ?? 28; + // Billboard box — centered on the anchor, magnified by scaleByDistance, from + // the size the tracking layer recorded for its sprite. + const sprite = followed?.sprite; + if (sprite && win && Number.isFinite(win.x) && Number.isFinite(win.y)) { + const baseW = sprite.width ?? 28; + const baseH = sprite.height ?? 28; let scale = 1; - const sbd = bb.scaleByDistance?.getValue?.(now); - if (sbd) - scale = nearFarValue( - sbd, - Cesium.Cartesian3.distance(scene.camera.positionWC, world), - ); + const sbd = sprite.scaleByDistance; + // No eye to measure from: the sprite's own size. + if (sbd && pose) + scale = nearFarValue(sbd, distance(pose.position, world)); const hw = (baseW * scale) / 2; const hh = (baseH * scale) / 2; const bbLeft = win.x - hw; @@ -476,14 +478,17 @@ export function createScreenAnnotationRenderer( return; } projGen += 1; // new frame: entries touched below are "hot" and survive trimming + pose = findCamera(viewer)?.pose() ?? null; + passQuery = findQuery(viewer); + passCanvas = canvasOf(); const trackedRect = trackedEntityRect(); - occluder.cameraPosition = scene.camera.positionWC; - const h = scene.canvas.clientHeight || scene.canvas.height; - const w = scene.canvas.clientWidth || scene.canvas.width; + const canvas = passCanvas; + const h = canvas.clientHeight || canvas.height; + const w = canvas.clientWidth || canvas.width; viewBox = `0 0 ${w} ${h}`; // Shrink point-marker geometry as the camera pulls back (declutter the blob). const mScale = markScale( - viewer.camera.positionCartographic?.height ?? 1000, + Number.isFinite(pose?.height) ? pose.height : 1000, ); for (const rec of records.values()) { @@ -677,6 +682,14 @@ export function createScreenAnnotationRenderer( // safe and not jarring. function fadeTracked(trackedRect) { if (!shown()) return; + const nowMs = performance.now(); + // A gap longer than a slow frame means the fade was not running (nothing + // followed): it starts again as from one 60 Hz frame. + const gapMs = nowMs - trackedFadeAtMs; + const stepMs = gapMs >= 0 && gapMs <= 100 ? gapMs : TRACKED_FADE_FRAME_MS; + trackedFadeAtMs = nowMs; + const ease = + 1 - Math.pow(1 - TRACKED_FADE_EASE, stepMs / TRACKED_FADE_FRAME_MS); let changed = false; for (const rec of records.values()) { const { anno, group } = rec; @@ -705,10 +718,10 @@ export function createScreenAnnotationRenderer( } } const target = overlapping ? 0 : 1; - const next = cur + (target - cur) * TRACKED_FADE_EASE; + const next = cur + (target - cur) * ease; rec._trackedFade = Math.abs(next - target) < 0.02 ? target : next; // The base alpha applies unless faded. (The CSS `transition: opacity` was - // removed from .gev-anno so this per-frame JS ease is the ONLY easing — + // removed from .gev-anno so this JS ease is the ONLY easing — // previously the two fought and produced an opacity oscillation.) const opacity = String( (anno.alpha ?? 1) * (rec._trackedFade !== 1 ? rec._trackedFade : 1), @@ -821,7 +834,7 @@ export function createScreenAnnotationRenderer( function destroy() { try { - scene.postRender.removeEventListener(onPostRender); + removePostRender?.(); } catch { /* torn down */ } diff --git a/src/annotations/screenAnnotationRenderer.test.mjs b/src/annotations/screenAnnotationRenderer.test.mjs index ce1fb40583..406938cf31 100644 --- a/src/annotations/screenAnnotationRenderer.test.mjs +++ b/src/annotations/screenAnnotationRenderer.test.mjs @@ -6,7 +6,19 @@ import { createApp, nextTick } from 'vue'; import { createPinia } from 'pinia'; import { useScreenAnnotationsStore } from '../ui/stores/screenAnnotations.js'; import ScreenAnnotations from '../ui/views/panels/ScreenAnnotations.vue'; -import { createScreenAnnotationRenderer } from './screenAnnotationRenderer.js'; +import { createScreenAnnotationRenderer as createRenderer } from './screenAnnotationRenderer.js'; +import { bindFakeCesiumScene } from '../testSupport/fakeCesiumScene.mjs'; +import { rendererOf } from '../render/rendererOf.js'; + +/** + * The renderer over a viewer double with the camera, query and frame ports + * bound over it (once per double), and the scene's canvas as the viewer's. + */ +function createScreenAnnotationRenderer(viewer, options) { + if (!rendererOf(viewer)) bindFakeCesiumScene(viewer); + viewer.canvas ??= viewer.scene?.canvas; + return createRenderer(viewer, options); +} // happy-dom does not lay out SVG; every element measures as a 40 x 16 box. for (const type of [globalThis.SVGElement, globalThis.SVGGraphicsElement]) { @@ -53,7 +65,7 @@ function sceneFor(camera, extra = {}) { return { camera, canvas: { clientWidth: 800, clientHeight: 600, width: 800, height: 600 }, - clampToHeightSupported: false, + sampleHeightSupported: false, postRender: { addEventListener() {}, removeEventListener() {} }, ...extra, }; @@ -173,14 +185,13 @@ test('outline upgrade preserves the existing SVG group identity', async (t) => { const sampledAnchors = []; const scene = sceneFor(camera, { canvas: { clientWidth: 1280, clientHeight: 720, width: 1280, height: 720 }, - clampToHeightSupported: true, - clampToHeight(world) { - const cartographic = Cesium.Cartographic.fromCartesian(world); + sampleHeightSupported: true, + sampleHeight(cartographic) { sampledAnchors.push([ Number(Cesium.Math.toDegrees(cartographic.longitude).toFixed(4)), Number(Cesium.Math.toDegrees(cartographic.latitude).toFixed(4)), ]); - return world; + return 0; }, }); const renderer = createScreenAnnotationRenderer( @@ -216,7 +227,7 @@ test('outline upgrade preserves the existing SVG group identity', async (t) => { assert.ok(after === before, 'the rendered group is mutated, not replaced'); assert.deepEqual(sampledAnchors.at(-1), [-97.5, 31.2], 'the existing group projects from the re-seated anchor'); assert.equal(groups().length, 1); - assert.equal(after.querySelector('.gev-anno-ring'), null, 'reticle rings are removed in place'); + assert.equal(after.querySelector('.gev-anno-ring') === null, true, 'reticle rings are removed in place'); assert.ok(after.querySelector('.gev-anno-callout') === callout, 'the original callout remains in the group'); assert.ok(after.querySelector('.gev-anno-dot') === dot, 'the anchor dot remains in the group'); assert.ok(svg()); @@ -330,7 +341,7 @@ test('a removed mark fades out, then leaves the board', async (t) => { assert.equal(group.isConnected, false); renderer.destroy(); await settle(); - assert.equal(document.querySelector('.gev-screen-whiteboard'), null); + assert.equal(document.querySelector('.gev-screen-whiteboard') === null, true); }); // ── Partial-add unwind (review round 2) ─────────────────────────────────────── diff --git a/src/annotations/worldAnnotationRenderer.js b/src/annotations/worldAnnotationRenderer.js index 189d46830c..dd4d802ae0 100644 --- a/src/annotations/worldAnnotationRenderer.js +++ b/src/annotations/worldAnnotationRenderer.js @@ -1,64 +1,156 @@ import { recordWorkSlice } from '../sources/phaseTiming.js'; import { ringCentroid } from '../sources/featureGeometry.js'; -import * as Cesium from 'cesium'; import { showOsmCredit, hideOsmCredit } from '../data/dataCredits.js'; +import { fromDegrees } from '../geo/ellipsoid.js'; +import { + drawOf, + findCamera, + findFrame, + frameOf, +} from '../render/rendererOf.js'; +import { heightsOf } from '../queries/heights.js'; /** * World-space annotation renderer (Direction A). * - * Draws annotations as native Cesium entities anchored to lon/lat. Because they - * live in the 3D scene they track the camera, sit at the right depth, and are - * occluded by the photoreal buildings the way a real marker would be. + * Draws annotations through the renderer's draw port, anchored to lon/lat. + * Because they live in the 3D scene they track the camera, sit at the right + * depth, and are occluded by the photoreal buildings the way a real marker + * would be. * * IMPORTANT — drawing on Google Photorealistic 3D Tiles: - * The Cesium globe is hidden, so there is no terrain to clamp to. Ground - * geometry (areas, rings, connectors) is draped onto the photoreal tiles with - * `classificationType: CESIUM_3D_TILE`; points clamp to the tile - * surface with `heightReference: CLAMP_TO_GROUND` (which requires the tileset - * to have `enableCollision = true`, set in initAnnotations). This keeps marks - * sitting ON the world instead of buried at sea level. + * The globe is hidden, so there is no terrain to clamp to. Ground geometry + * (areas, rings, connectors) is draped onto the photoreal tiles and the + * terrain alike (`clampTo: 'both'`); points clamp to the surface. This + * keeps marks sitting ON the world instead of buried at sea level. * - * Live alpha (fade in/out) and pulsing are driven by CallbackProperty so they - * animate every render without the engine touching them per frame. + * Fades follow the mark's alpha: the engine calls `sync` as it changes, and + * each mark's items take their new colours where they are. Pulsing fills + * are a declarative pulse the renderer runs; target rings follow the + * camera's height, read before each frame, and are sent again at the radius + * it gives when that changes. + * + * Each mark draws into sets of its own, so adding or removing one leaves + * the others' geometry alone. * * Renderer contract (shared with the screen-space renderer): * add(anno) / remove(anno) / sync(map) / destroy() */ +/** Each palette colour as `r, g, b`, 0..1. */ const PALETTE = { - primary: '#8be9ff', - amber: '#ffb547', - cyan: '#39d0ff', - green: '#5dff9f', - red: '#ff6b6b', + primary: rgb('#8be9ff'), + amber: rgb('#ffb547'), + cyan: rgb('#39d0ff'), + green: rgb('#5dff9f'), + red: rgb('#ff6b6b'), }; +const WHITE = [1, 1, 1]; /** - * What a draped mark is allowed to paint onto. - * - * This was CESIUM_3D_TILE, which is right with Google's photoreal tiles under - * the camera and wrong everywhere else: on a keyless boot (Esri or OSM imagery - * on Cesium's own globe) there are no 3D tiles to classify against, so every - * area fill, area outline, route and arrow rendered to nothing. The labels - * showed and the geometry did not, which reads as a broken feature rather than - * an unsupported surface — and it hit spoken annotations exactly as hard as - * hand-drawn ones. - * - * BOTH paints onto terrain AND onto 3D tiles, so one value covers both worlds. + * What a draped mark is allowed to paint onto: terrain AND 3D tiles, so one + * value covers a keyless boot (imagery on the globe, no tiles) and the + * photoreal world alike. Tiles alone rendered every area, route and arrow to + * nothing on a keyless boot. */ -const CLASSIFY = Cesium.ClassificationType.BOTH; -const CLAMP = Cesium.HeightReference.CLAMP_TO_GROUND; +const CLAMP_TO = 'both'; + +/** + * The pulse of a pulsing fill: its alpha swings between 60% and all of its + * own, a sine of about 0.8 Hz on the wall clock. + */ +const PULSE_MS = (2 * Math.PI) / 0.005; +const PULSE_LOW = 0.6; + +/** Target rings: 3% of the camera's height, between 14 m and 170 m. */ +const RING_RADIUS = Object.freeze({ factor: 0.03, min: 14, max: 170 }); + +/** Relative change of the ring radius under which rings are not redrawn. */ +const RING_RESIZE = 1e-3; + +/** + * A target ring's radius, metres, for a camera `height` metres above the + * ellipsoid; 1000 m stands in for a height the camera cannot give. + * @param {number} height + */ +export function ringRadiusAt(height) { + const h = Number.isFinite(height) ? height : 1000; + return Math.max( + RING_RADIUS.min, + Math.min(RING_RADIUS.max, h * RING_RADIUS.factor), + ); +} + +/** + * Each renderer's sets have ids of their own, unique across copies of this + * module on one viewer too. + */ +let rendererSeq = 0; +const MODULE_TOKEN = Math.random().toString(36).slice(2, 8); export function createWorldAnnotationRenderer(viewer) { - const dataSource = new Cesium.CustomDataSource('gev-annotations'); - viewer.dataSources.add(dataSource); + const draw = drawOf(viewer); + const instance = `${MODULE_TOKEN}${(rendererSeq += 1)}`; + let markSeq = 0; const osmAnnotations = new Set(); - // Every mark with entities on the globe, so sync() can take a hidden one out. + // Every mark with sets on the globe, so sync() can take a hidden one out. const drawn = new Set(); const pendingGround = new Map(); const groundQueue = []; - let observingGround = false; + let offGroundFrame = null; let destroyed = false; + // Marks with a target ring, and the radius they are drawn at. + const ringed = new Set(); + let offRingFrame = null; + let ringRadius = ringRadiusAt(cameraHeight()); + + /** The camera's height above the ellipsoid, or NaN when it has none. */ + function cameraHeight() { + try { + return findCamera(viewer)?.pose().height ?? Number.NaN; + } catch { + return Number.NaN; + } + } + + /** The current ring radius, for the items that draw rings. */ + const ringRadiusNow = () => ringRadius; + + /** + * Before each frame: when the camera's height gives the rings another + * radius, every shown mark's ring is sent again at it. A hidden mark's + * ring catches up when it shows (`sync`). + */ + function followRings() { + const radius = ringRadiusAt(cameraHeight()); + if (Math.abs(radius - ringRadius) <= RING_RESIZE * ringRadius) return; + ringRadius = radius; + for (const anno of ringed) if (!anno.hidden) resizeRing(anno); + } + + /** Send a mark's ring again at the current radius, when it differs. */ + function resizeRing(anno) { + const was = anno._drawn; + const set = anno._draw?.shapes; + if (!was?.ring || !set || was.ringRadius === ringRadius) return; + was.ringRadius = ringRadius; + set.upsert([was.ring(was.alpha)]); + } + + /** + * Keep the ring frame listener while any mark has a ring. A host with no + * frame port draws its rings at the radius they were added with. + */ + function watchRings() { + if (ringed.size && !offRingFrame) + offRingFrame = findFrame(viewer)?.on('preRender', followRings) ?? null; + else if (!ringed.size && offRingFrame) { + offRingFrame(); + offRingFrame = null; + } + } + + const requestRender = () => frameOf(viewer).requestRender('annotations'); function sampleBuilding(anno, options) { pendingGround.get(anno)?.finish('cancelled'); @@ -107,7 +199,7 @@ export function createWorldAnnotationRenderer(viewer) { // A task promoted outside a frame (its predecessor timed out or was // cancelled) still needs frames in request-render mode. try { - viewer.scene.requestRender?.(); + requestRender(); } catch { /* the enqueue path reports render failures */ } @@ -120,9 +212,9 @@ export function createWorldAnnotationRenderer(viewer) { clearTimeout(task.timer); if (position === 0) groundQueue[0]?.begin(); options.signal?.removeEventListener('abort', task.abort); - if (!groundQueue.length && observingGround) { - viewer.scene.postRender.removeEventListener(onGroundFrame); - observingGround = false; + if (!groundQueue.length && offGroundFrame) { + offGroundFrame(); + offGroundFrame = null; } timing.elapsedMs = performance.now() - (started ?? queuedAt); if (workTrace) { @@ -174,28 +266,25 @@ export function createWorldAnnotationRenderer(viewer) { const sliceStart = performance.now(); let error; try { - if ( - viewer.scene.clampToHeightSupported && - typeof viewer.scene.clampToHeight === 'function' - ) { + // Without depth support the surface answers nothing: the + // probes are skipped, and the fallback height is taken. + if (heightsOf(viewer).supported().surface) { const [lon, lat] = task.points[task.index++]; timing.probes += 1; try { - const position = Cesium.Cartesian3.fromDegrees(lon, lat, 0); - let c; + let h; note?.('clampStart'); - if (detail) detail.clampResult = 'threw'; try { - c = viewer.scene.clampToHeight(position); - if (detail) detail.clampResult = 'returned'; + // The surface under the probe: the drawn tiles or terrain, + // never a mark (no draw set is in height queries). + h = heightsOf(viewer).now({ lon, lat }); + if (detail) + detail.clampResult = Number.isFinite(h) ? 'hit' : 'missed'; } finally { note?.('clampEnd'); } - if (c) { - const h = Cesium.Cartographic.fromCartesian(c).height; - if (Number.isFinite(h) && h > -430 && h < 9000) - task.samples.push(h); - } + if (Number.isFinite(h) && h > -430 && h < 9000) + task.samples.push(h); } catch { /* surface not ready: preserve the existing sample filter */ } @@ -240,7 +329,7 @@ export function createWorldAnnotationRenderer(viewer) { task.finish('installed'); } finally { // Commit includes sort/selection/add/deadline/finish or rollback, - // including intervening bookkeeping; it is not exclusive entity cost. + // including intervening bookkeeping; it is not exclusive draw cost. if (detail?.commitStatus === 'attempted') note('commitEnd'); if (workTrace) recordWorkSlice( @@ -257,12 +346,10 @@ export function createWorldAnnotationRenderer(viewer) { if (groundQueue[0] === task) task.begin(); options.signal?.addEventListener('abort', task.abort, { once: true }); if (!task.current()) return task.finish('cancelled'); - if (!observingGround) { - viewer.scene.postRender.addEventListener(onGroundFrame); - observingGround = true; - } try { - viewer.scene.requestRender?.(); + if (!offGroundFrame) + offGroundFrame = frameOf(viewer).on('postRender', onGroundFrame); + requestRender(); } catch (error) { task.finish('failed', error); } @@ -274,49 +361,43 @@ export function createWorldAnnotationRenderer(viewer) { const task = groundQueue[0]; try { task?.step(); - if (groundQueue.length) viewer.scene.requestRender?.(); + if (groundQueue.length) requestRender(); } catch (error) { for (const pending of [...groundQueue]) pending.finish('failed', error); } } - - // Register the GevRouteFlow fabric once so Cesium's Material.fromType() can build the - // material the route pipeline renders. The animated `time` uniform is read straight - // from performance.now() inside FlowMaterialProperty.getValue (which Cesium calls each - // rendered frame with the live uniforms object), so the dashes flow with no extra - // per-frame bookkeeping. - ensureFlowFabricRegistered(); - - function colorFor(anno) { - return Cesium.Color.fromCssColorString( - PALETTE[anno.color] || PALETTE.primary, - ); + /** + * The mark's draw sets, made on first use: shapes (fills, volumes, rings), + * lines (outlines, routes, arrows) and points (markers). + */ + function setsOf(anno) { + if (!anno._draw) { + markSeq += 1; + const prefix = `annotations:${instance}:${markSeq}`; + anno._draw = { prefix, shapes: null, lines: null, points: null }; + } + return anno._draw; } - // Target-ring radius (meters) scaled to camera height so it reads at any - // altitude. Read once per frame for BOTH ellipse axes — camera height is - // constant within a frame, so semiMajor === semiMinor always holds. - function ringRadius() { - const h = viewer.camera.positionCartographic?.height ?? 1000; - return Math.max(14, Math.min(170, h * 0.03)); - } - - // A live color that follows the annotation's fade alpha and an optional pulse. - function liveColor(anno, base, { alpha = 0.9, pulse = false } = {}) { - return new Cesium.CallbackProperty(() => { - const a = (anno.alpha ?? 1) * alpha * (pulse ? pulseFactor() : 1); - return base.withAlpha(Math.max(0, Math.min(1, a))); - }, false); + function setOf(anno, kind) { + const sets = setsOf(anno); + if (!sets[kind]) { + sets[kind] = draw[kind]({ + id: `${sets.prefix}:${kind}`, + clampTo: CLAMP_TO, + show: !anno.hidden, + }); + } + return sets[kind]; } function add(anno, options = {}) { - const base = colorFor(anno); - // Published to the mark BEFORE anything is added, and mutated in place as - // each entity lands: a mid-add failure (bad geometry, lost context) must - // leave the entities that DID land visible to remove(), or the rollback - // path cannot reach them and they stay on the globe forever. - const entities = []; - anno._entities = entities; + // A destroyed renderer draws nothing more. + if (destroyed) return; + // Published to the mark BEFORE anything is drawn: a mid-add failure (bad + // geometry, lost context) must leave the sets that DID land visible to + // remove(), or the rollback path cannot reach them and they stay on the + // globe forever. drawn.add(anno); if ( @@ -327,253 +408,43 @@ export function createWorldAnnotationRenderer(viewer) { return sampleBuilding(anno, options); } - if ( - anno.ring && - anno.ring.length >= 3 && - anno.footprintKind === 'building' - ) { - const addBuildingEntity = (definition) => { - if (!(options.isCurrent?.() ?? true)) - throw new Error('Building install cancelled'); - const entity = dataSource.entities.add(definition); - if (!(options.isCurrent?.() ?? true)) { - dataSource.entities.remove(entity); - throw new Error('Building install cancelled'); - } - return entity; - }; - // Single building → the PRIMARY highlight is an extruded CLASSIFICATION - // volume that tints the real photogrammetry mesh (dome, walls, roof — - // everything inside the column) amber and pulses. A flat footprint - // extrusion is only 2.5D and misses domes; classification colors the - // actual tiles. A faint wireframe cage rides on top as a secondary cue. - const parts = - Array.isArray(anno.polygons) && anno.polygons.length - ? anno.polygons - : [[anno.ring]]; - const groundH = - options.sampledGroundHeight ?? - (Number.isFinite(anno.anchor.height) - ? anno.anchor.height - (anno.buildingHeight || 25) - : 0); - const baseH = groundH - 3; - // Tall headroom is free: classification only colors where tiles exist, so - // empty air above the roof isn't tinted — this just guarantees we cover - // under-tagged building heights. - const topH = groundH + Math.max(18, anno.buildingHeight || 25) + 24; - const fillMaterial = new Cesium.ColorMaterialProperty( - liveColor(anno, base, { alpha: 0.45, pulse: true }), - ); - const lineMaterial = new Cesium.PolylineGlowMaterialProperty({ - glowPower: 0.25, - color: liveColor(anno, base, { alpha: 0.7 }), - }); - for (const [outer, ...holes] of parts) { - const buffered = bufferRing(outer, 3); - const positions = Cesium.Cartesian3.fromDegreesArray(buffered.flat()); - // 1) Classification volume — tints the mesh amber, pulsing. - entities.push( - addBuildingEntity({ - polygon: { - hierarchy: new Cesium.PolygonHierarchy( - positions, - holes.map( - (hole) => - new Cesium.PolygonHierarchy( - Cesium.Cartesian3.fromDegreesArray(hole.flat()), - ), - ), - ), - height: baseH, - extrudedHeight: topH, - perPositionHeight: false, - classificationType: CLASSIFY, - material: fillMaterial, - }, - }), - ); - // 2) Faint, SIMPLIFIED wireframe cage — secondary, lower opacity. Decimate - // the footprint so the extruded outline draws ~14 clean verticals, not one - // per (often 100+) ring vertex. - const cagePositions = Cesium.Cartesian3.fromDegreesArray( - decimateRing(buffered, 14).flat(), - ); - entities.push( - addBuildingEntity({ - polygon: { - hierarchy: new Cesium.PolygonHierarchy(cagePositions), - height: baseH, - extrudedHeight: topH, - perPositionHeight: false, - fill: false, - outline: true, - outlineColor: liveColor(anno, base, { alpha: 0.32, pulse: true }), - }, - }), - ); - // 3) Crisp draped base outline so the footprint reads on the ground. - for (const ring of [outer, ...holes]) { - entities.push( - addBuildingEntity({ - polyline: { - positions: Cesium.Cartesian3.fromDegreesArray( - closedRing(ring).flat(), - ), - width: 3, - material: lineMaterial, - clampToGround: true, - classificationType: CLASSIFY, - }, - }), - ); - } + // Rings not yet followed take the camera's height now. + if (!offRingFrame) ringRadius = ringRadiusAt(cameraHeight()); + const items = itemsOf(anno, options, ringRadiusNow); + anno._drawn = { + alpha: alphaOf(anno), + items, + ring: items.ring, + ringRadius, + }; + if (items.ring) ringed.add(anno); + else ringed.delete(anno); + watchRings(); + const current = () => options.isCurrent?.() ?? true; + const building = anno.footprintKind === 'building'; + for (const kind of ['shapes', 'lines', 'points']) { + if (!items[kind].length) { + // Added again as another kind: what it drew before goes. + disposeSet(anno, kind); + continue; } - } else if (anno.ring && anno.ring.length >= 3) { - // Larger area (district / compound / park / state) → flat fill draped on - // the tiles + a glowing outline. Draping is right here: you can't extrude - // a whole neighbourhood, and the GIS overlay shows the boundary clearly. - // A multi-part outline (`anno.polygons`: Hawaii's islands, Berlin as a - // hole in Brandenburg) draws every part with its holes. All parts share - // ONE fill and ONE line material, so Cesium batches the whole mark into a - // ground primitive per kind instead of one per island. - const parts = - Array.isArray(anno.polygons) && anno.polygons.length - ? anno.polygons - : [[anno.ring]]; - const fillMaterial = new Cesium.ColorMaterialProperty( - // Synthesized (approximate) areas get a fainter fill so they don't read as solid. - liveColor(anno, base, { - alpha: anno.synthesized ? 0.1 : 0.2, - pulse: true, - }), - ); - // Synthesized → DASHED outline (signals "approximate, not an authoritative - // boundary", research §8.4/§8.6); real footprints → solid glow. - const lineMaterial = anno.synthesized - ? new Cesium.PolylineDashMaterialProperty({ - color: liveColor(anno, base, { alpha: 0.95 }), - dashLength: 24, - }) - : new Cesium.PolylineGlowMaterialProperty({ - glowPower: 0.35, - color: liveColor(anno, base, { alpha: 1 }), - }); - for (const [outer, ...holes] of parts) { - if (!Array.isArray(outer) || outer.length < 3) continue; - const rings = [outer, ...holes.filter((h) => h?.length >= 3)]; - entities.push( - dataSource.entities.add({ - polygon: { - hierarchy: new Cesium.PolygonHierarchy( - Cesium.Cartesian3.fromDegreesArray(outer.flat()), - rings - .slice(1) - .map( - (hole) => - new Cesium.PolygonHierarchy( - Cesium.Cartesian3.fromDegreesArray(hole.flat()), - ), - ), - ), - material: fillMaterial, - classificationType: CLASSIFY, - }, - }), - ); - for (const ring of rings) { - entities.push( - dataSource.entities.add({ - polyline: { - positions: Cesium.Cartesian3.fromDegreesArray( - closedRing(ring).flat(), - ), - width: 6, - material: lineMaterial, - clampToGround: true, - classificationType: CLASSIFY, - }, - }), - ); - } + if (building && !current()) throw new Error('Building install cancelled'); + setOf(anno, kind).set(items[kind].map((item) => item(anno._drawn.alpha))); + if (building && !current()) { + clearSets(anno); + throw new Error('Building install cancelled'); } - } else if ( - anno.type === 'route' && - Array.isArray(anno.path) && - anno.path.length >= 2 - ) { - // A real path (street-following) draped on the 3D tiles, with dashes that - // FLOW toward the destination (custom st.s + time material; works on the - // clamped/classified ground polyline). - const positions = Cesium.Cartesian3.fromDegreesArray( - anno.path.flatMap((p) => [p.lon, p.lat]), - ); - entities.push( - dataSource.entities.add({ - polyline: { - positions, - width: 9, - material: new FlowMaterialProperty( - PALETTE[anno.color] || PALETTE.primary, - () => anno.alpha ?? 1, - ), - clampToGround: true, - classificationType: CLASSIFY, - }, - }), - ); + } + if (anno.type === 'route' && items.lines.length) { osmAnnotations.add(anno); showOsmCredit(viewer, anno); - } else if (anno.type === 'arrow' && anno.to) { - // Connector draped across the ground from origin to destination. - const positions = [ - Cesium.Cartesian3.fromDegrees(anno.anchor.lon, anno.anchor.lat), - Cesium.Cartesian3.fromDegrees(anno.to.lon, anno.to.lat), - ]; - entities.push( - dataSource.entities.add({ - polyline: { - positions, - width: 16, - material: new Cesium.PolylineArrowMaterialProperty( - liveColor(anno, base, { alpha: 0.95 }), - ), - clampToGround: true, - classificationType: CLASSIFY, - }, - }), - ); - } else { - // pin / highlight / label — a camera-proportional target ring + a marker. - if (anno.type !== 'label') { - // Radius scales with camera height so the ring reads at any altitude. - // semiMajor === semiMinor is required AND must hold every frame, so both - // axes read the SAME ringRadius() (camera height is constant per frame). - entities.push( - dataSource.entities.add({ - position: Cesium.Cartesian3.fromDegrees( - anno.anchor.lon, - anno.anchor.lat, - ), - ellipse: { - semiMajorAxis: new Cesium.CallbackProperty(ringRadius, false), - semiMinorAxis: new Cesium.CallbackProperty(ringRadius, false), - material: new Cesium.ColorMaterialProperty( - liveColor(anno, base, { alpha: 0.38, pulse: true }), - ), - outline: false, - classificationType: CLASSIFY, - }, - }), - ); - } - entities.push(pointMarker(anno, base)); } if ( - entities.length && + (items.shapes.length || items.lines.length || items.points.length) && anno.ring?.length >= 3 && !anno.synthesized && (anno.outlineCredit === 'tiles' || anno.outlineCredit === 'osm') && - (options.isCurrent?.() ?? true) + current() ) { // The actual world proxy owns both geometry and credit, including rollback. osmAnnotations.add(anno); @@ -583,19 +454,19 @@ export function createWorldAnnotationRenderer(viewer) { } } - // Captions belong to the hybrid renderer's screen-space callouts. - function pointMarker(anno, base) { - return dataSource.entities.add({ - position: Cesium.Cartesian3.fromDegrees(anno.anchor.lon, anno.anchor.lat), - point: { - pixelSize: anno.type === 'label' ? 8 : 14, - color: liveColor(anno, base, { alpha: 1 }), - outlineColor: liveColor(anno, Cesium.Color.WHITE, { alpha: 0.95 }), - outlineWidth: 3, - heightReference: CLAMP, - disableDepthTestDistance: Number.POSITIVE_INFINITY, - }, - }); + function disposeSet(anno, kind) { + const sets = anno?._draw; + if (!sets?.[kind]) return; + try { + sets[kind].dispose(); + } catch { + /* already gone */ + } + sets[kind] = null; + } + + function clearSets(anno) { + for (const kind of ['shapes', 'lines', 'points']) disposeSet(anno, kind); } function remove(anno) { @@ -603,27 +474,39 @@ export function createWorldAnnotationRenderer(viewer) { hideOsmCredit(viewer, anno); osmAnnotations.delete(anno); drawn.delete(anno); - if (!anno?._entities) return; - for (const entity of anno._entities) { - try { - dataSource.entities.remove(entity); - } catch { - /* already gone */ - } + ringed.delete(anno); + watchRings(); + clearSets(anno); + if (anno) { + anno._draw = null; + anno._drawn = null; } - anno._entities = null; } /** - * CallbackProperty drives per-frame alpha and pulse. A hidden mark is taken - * out whole, so no material that keeps its own colour (the route's flow), - * ground classification or pick can still show it. + * A hidden mark is taken out whole (its sets hidden), so no fill, line or + * pick can still show it; a mark whose alpha moved (fading in or out) + * takes its new colours in place. */ function sync() { for (const anno of drawn) { + const sets = anno._draw; + if (!sets) continue; const show = !anno.hidden; - for (const entity of anno._entities || []) - if (entity.show !== show) entity.show = show; + for (const kind of ['shapes', 'lines', 'points']) + if (sets[kind] && sets[kind].show !== show) sets[kind].show = show; + const was = anno._drawn; + const alpha = alphaOf(anno); + if (!was || was.alpha === alpha) { + // Shown again: its ring catches up with the camera. + if (show) resizeRing(anno); + continue; + } + was.alpha = alpha; + was.ringRadius = ringRadius; + for (const kind of ['shapes', 'lines', 'points']) + if (sets[kind] && was.items[kind].length) + sets[kind].upsert(was.items[kind].map((item) => item(alpha))); } } @@ -632,114 +515,234 @@ export function createWorldAnnotationRenderer(viewer) { for (const task of [...pendingGround.values()]) task.finish('cancelled'); for (const anno of osmAnnotations) hideOsmCredit(viewer, anno); osmAnnotations.clear(); - drawn.clear(); - try { - viewer.dataSources.remove(dataSource, true); - } catch { - /* scene torn down */ + ringed.clear(); + watchRings(); + for (const anno of drawn) { + clearSets(anno); + anno._draw = null; + anno._drawn = null; } + drawn.clear(); } return { add, remove, sync, destroy }; } -function pulseFactor() { - // 0.6 .. 1.0 sinusoid at ~0.8 Hz - return 0.8 + 0.2 * Math.sin(performance.now() * 0.005); -} +/** A mark's alpha as drawn, 0..1. */ +const alphaOf = (anno) => Math.max(0, Math.min(1, anno.alpha ?? 1)); -/** - * A custom Fabric polyline material whose dashes flow toward the destination. - * `materialInput.st.s` is the along-line coordinate (0 = origin, 1 = destination), - * so `fract(s*repeat - time*speed)` scrolls the pattern toward the end. Works on - * a clamped/classified ground polyline (PolylineMaterialAppearance supports it). - */ -function makeRouteFlowMaterial(colorCss) { - return new Cesium.Material({ - fabric: { - type: 'GevRouteFlow', - uniforms: { - color: Cesium.Color.fromCssColorString(colorCss).withAlpha(0.95), - time: 0.0, - repeat: 64.0, // dash cells along the whole route - duty: 0.46, // fraction of each cell that is "on" - speed: 0.55, // cells per second toward the destination - }, - source: ` - czm_material czm_getMaterial(czm_materialInput materialInput) { - czm_material m = czm_getDefaultMaterial(materialInput); - float s = materialInput.st.s; // 0 origin -> 1 dest - float flow = fract(s * repeat - time * speed); // scroll toward dest - float on = smoothstep(duty + 0.08, duty - 0.08, flow); - // keep a faint baseline so the whole route stays readable between dashes - float a = max(on, 0.18); - m.diffuse = color.rgb; - m.emission = color.rgb * on * 0.9; // glow on the lit cells - m.alpha = color.a * a; - return m; - }`, - }, - }); -} +/** `[r, g, b, a]` for a palette colour at `alpha`. */ +const colour = (base, alpha) => [base[0], base[1], base[2], alpha]; -let _flowFabricRegistered = false; -/** Register the GevRouteFlow fabric ONCE so Cesium's `Material.fromType('GevRouteFlow')` - * can build the material the render pipeline uses. Constructing one Material with the - * fabric caches it under its type name. */ -export function ensureFlowFabricRegistered() { - if (_flowFabricRegistered) return; - makeRouteFlowMaterial('#ffffff'); // side effect: registers the 'GevRouteFlow' type - _flowFabricRegistered = true; -} - -/** - * MaterialProperty for the animated route. Cesium builds the rendered Material once - * from getType() (our registered GevRouteFlow fabric), then EACH FRAME calls - * getValue(time, material.uniforms) and uses whatever we write INTO that uniforms - * object — it ignores the return value. So getValue writes color/time/repeat/duty/ - * speed straight onto `result` (the live uniforms). Writing the animated `time` here - * is what actually makes the dashes flow on the GPU. (The prior versions either - * returned a standalone Material Cesium never rendered, or treated `result` as a - * Material — both left the real uniforms untouched, so nothing animated.) - */ -export function FlowMaterialProperty(colorCss, alphaOf = () => 1) { - this._color = Cesium.Color.fromCssColorString(colorCss).withAlpha(0.95); - // The mark's live alpha (fade in and out, hidden), applied every frame. - this._alphaOf = alphaOf; - this._live = this._color.clone(); - this._definitionChanged = new Cesium.Event(); -} -Object.defineProperties(FlowMaterialProperty.prototype, { - isConstant: { - get() { - return false; - }, - }, // re-evaluated each frame → it animates - definitionChanged: { - get() { - return this._definitionChanged; - }, - }, +/** A fill or outline that pulses about `alpha`. */ +const pulse = (alpha) => ({ + property: 'alpha', + from: alpha * PULSE_LOW, + to: alpha, + periodMs: PULSE_MS, }); -FlowMaterialProperty.prototype.getType = function getType() { - return 'GevRouteFlow'; -}; -FlowMaterialProperty.prototype.getValue = function getValue(time, result) { - // `result` IS the live uniforms object Cesium renders — write into it directly. - // `time` is read straight from the wall clock so the dashes flow every rendered - // frame (the scene renders continuously; no requestRenderMode here). - if (!Cesium.defined(result)) result = {}; - this._live.alpha = this._color.alpha * this._alphaOf(); - result.color = this._live; - result.time = performance.now() / 1000; // the per-frame animated value - result.repeat = 64.0; - result.duty = 0.46; - result.speed = 0.55; - return result; -}; -FlowMaterialProperty.prototype.equals = function equals(other) { - return this === other; -}; + +/** + * What a mark draws, as item makers by kind, each taking the mark's alpha: + * built once per add, called again on each fade step. `ring` is the target + * ring's maker among the shapes, drawn at `ringRadiusNow()`. + */ +function itemsOf(anno, options, ringRadiusNow) { + const base = PALETTE[anno.color] || PALETTE.primary; + const shapes = []; + const lines = []; + const points = []; + const meta = { annotation: anno.id }; + let ring = null; + const draped = (id, positions, widthPx, style) => (alpha) => ({ + id, + positions, + widthPx, + mode: 'draped', + clampTo: CLAMP_TO, + style: style(alpha), + meta, + }); + if (anno.ring?.length >= 3 && anno.footprintKind === 'building') { + // Single building → the PRIMARY highlight is a translucent extruded + // column round the building that pulses, from just under its ground to + // well over its roof, with a faint wireframe cage on it as a secondary + // cue and a crisp draped base outline. + const parts = + Array.isArray(anno.polygons) && anno.polygons.length + ? anno.polygons + : [[anno.ring]]; + const groundH = + options.sampledGroundHeight ?? + (Number.isFinite(anno.anchor.height) + ? anno.anchor.height - (anno.buildingHeight || 25) + : 0); + const baseH = groundH - 3; + // Tall headroom so under-tagged building heights are covered too. + const topH = groundH + Math.max(18, anno.buildingHeight || 25) + 24; + const at = (ring) => + ring.map(([lon, lat]) => ({ lon, lat, height: baseH })); + parts.forEach(([outer, ...holes], p) => { + const buffered = bufferRing(outer, 3); + // Built once: a fade step only changes colours. + const volume = { kind: 'polygon', rings: [buffered, ...holes].map(at) }; + shapes.push((alpha) => ({ + id: `volume:${p}`, + geometry: volume, + fill: colour(base, 0.45 * alpha), + animate: pulse(0.45 * alpha), + extrudeHeight: topH, + height: 'absolute', + meta, + })); + // Faint, SIMPLIFIED wireframe cage: the footprint decimated so the + // extruded outline draws ~14 clean verticals, not one per (often + // 100+) ring vertex. + const cage = { + kind: 'polygon', + rings: [at(decimateRing(buffered, 14))], + }; + shapes.push((alpha) => ({ + id: `cage:${p}`, + geometry: cage, + outline: colour(base, 0.32 * alpha), + outlineOnly: true, + animate: pulse(0.32 * alpha), + extrudeHeight: topH, + height: 'absolute', + meta, + })); + [outer, ...holes].forEach((ring, r) => + lines.push( + draped(`base:${p}:${r}`, ecefOf(closedRing(ring)), 3, (alpha) => ({ + kind: 'glow', + color: colour(base, 0.7 * alpha), + power: 0.25, + })), + ), + ); + }); + } else if (anno.ring?.length >= 3) { + // Larger area (district / compound / park / state) → flat fill draped on + // the tiles + a glowing outline. Draping is right here: you can't extrude + // a whole neighbourhood, and the GIS overlay shows the boundary clearly. + // A multi-part outline (`anno.polygons`: Hawaii's islands, Berlin as a + // hole in Brandenburg) draws every part with its holes. + const parts = + Array.isArray(anno.polygons) && anno.polygons.length + ? anno.polygons + : [[anno.ring]]; + // Synthesized (approximate) areas get a fainter fill so they don't read + // as solid, and a DASHED outline (signals "approximate, not an + // authoritative boundary", research §8.4/§8.6); real footprints a solid + // glow. + const fillAlpha = anno.synthesized ? 0.1 : 0.2; + const style = anno.synthesized + ? (alpha) => ({ + kind: 'dash', + color: colour(base, 0.95 * alpha), + length: 24, + }) + : (alpha) => ({ kind: 'glow', color: colour(base, alpha), power: 0.35 }); + parts.forEach(([outer, ...holes], p) => { + if (!Array.isArray(outer) || outer.length < 3) return; + const rings = [outer, ...holes.filter((h) => h?.length >= 3)]; + const area = { + kind: 'polygon', + rings: rings.map((ring) => ring.map(([lon, lat]) => ({ lon, lat }))), + }; + shapes.push((alpha) => ({ + id: `fill:${p}`, + geometry: area, + fill: colour(base, fillAlpha * alpha), + animate: pulse(fillAlpha * alpha), + height: 'clampGround', + clampTo: CLAMP_TO, + meta, + })); + rings.forEach((ring, r) => + lines.push( + draped(`outline:${p}:${r}`, ecefOf(closedRing(ring)), 6, style), + ), + ); + }); + } else if ( + anno.type === 'route' && + Array.isArray(anno.path) && + anno.path.length >= 2 + ) { + // A real path (street-following) draped on the surface, with dashes that + // FLOW toward the destination. + lines.push( + draped( + 'route', + anno.path.map((p) => fromDegrees(p.lon, p.lat, 0)), + 9, + (alpha) => ({ + kind: 'flow', + color: colour(base, 0.95 * alpha), + repeat: 64, + duty: 0.46, + speed: 0.55, + }), + ), + ); + } else if (anno.type === 'arrow' && anno.to) { + // Connector draped across the ground from origin to destination. + lines.push( + draped( + 'arrow', + [ + fromDegrees(anno.anchor.lon, anno.anchor.lat, 0), + fromDegrees(anno.to.lon, anno.to.lat, 0), + ], + 16, + (alpha) => ({ kind: 'arrow', color: colour(base, 0.95 * alpha) }), + ), + ); + } else { + // pin / highlight / label — a camera-proportional target ring + a marker. + const pos = { lon: anno.anchor.lon, lat: anno.anchor.lat }; + if (anno.type !== 'label') { + ring = (alpha) => ({ + id: 'ring', + geometry: { + kind: 'ellipse', + center: pos, + semiMajor: ringRadiusNow(), + semiMinor: ringRadiusNow(), + }, + fill: colour(base, 0.38 * alpha), + animate: pulse(0.38 * alpha), + height: 'clampGround', + clampTo: CLAMP_TO, + meta, + }); + shapes.push(ring); + } + // Captions belong to the hybrid renderer's screen-space callouts. + points.push((alpha) => ({ + id: 'marker', + pos, + height: 'clampGround', + pixelSize: anno.type === 'label' ? 8 : 14, + color: colour(base, alpha), + outlineColor: colour(WHITE, 0.95 * alpha), + outlineWidth: 3, + disableDepthTest: Number.POSITIVE_INFINITY, + meta, + })); + } + return { shapes, lines, points, ring }; +} + +/** `[lon, lat]` pairs as ECEF positions on the ellipsoid. */ +const ecefOf = (ring) => ring.map(([lon, lat]) => fromDegrees(lon, lat, 0)); + +function rgb(css) { + const n = parseInt(css.slice(1), 16); + return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255]; +} /** The ring with its first vertex repeated at the end, so an outline closes. */ function closedRing(ring) { @@ -763,7 +766,7 @@ function decimateRing(ring, n) { function groundProbePositions(ring) { const { lon: clon, lat: clat } = ringCentroid(ring); const latS = 111320; - const lonS = latS * Math.cos(Cesium.Math.toRadians(clat)); + const lonS = latS * Math.cos((clat * Math.PI) / 180); let maxR = 0; for (const [lon, lat] of ring) { maxR = Math.max(maxR, Math.hypot((lon - clon) * lonS, (lat - clat) * latS)); @@ -801,7 +804,7 @@ function bufferRing(ring, meters) { clon /= ring.length; clat /= ring.length; const latScale = 111320; - const lonScale = latScale * Math.cos(Cesium.Math.toRadians(clat)); + const lonScale = latScale * Math.cos((clat * Math.PI) / 180); return ring.map(([lon, lat]) => { const dx = (lon - clon) * lonScale; const dy = (lat - clat) * latScale; diff --git a/src/annotations/worldAnnotationRenderer.test.mjs b/src/annotations/worldAnnotationRenderer.test.mjs index a05c52373f..62e0b65749 100644 --- a/src/annotations/worldAnnotationRenderer.test.mjs +++ b/src/annotations/worldAnnotationRenderer.test.mjs @@ -1,70 +1,448 @@ -// A mark hidden from Draw's list leaves the globe whole: every entity it put -// there is taken out on sync and comes back when shown, and the line's -// flowing stroke, which keeps its own colour, follows the mark's alpha. +// The world renderer draws each mark through the draw port, in sets of its +// own: a hidden mark has its sets hidden on sync and shown again; a fading +// mark takes its new colours in place; every kind draws what it drew as +// entities, draped and clamped to terrain and tiles alike. import test from 'node:test'; import assert from 'node:assert/strict'; -import * as C from 'cesium'; -import { - FlowMaterialProperty, - createWorldAnnotationRenderer, -} from './worldAnnotationRenderer.js'; +import { bindRenderer } from '../render/rendererOf.js'; +import { fakeDrawPort } from '../testSupport/fakeDrawPort.mjs'; +import { createWorldAnnotationRenderer } from './worldAnnotationRenderer.js'; -const noop = () => {}; -function viewer(t) { - for (const name of ['HTMLCanvasElement', 'HTMLImageElement', 'ImageBitmap', 'OffscreenCanvas']) { - const original = globalThis[name]; - globalThis[name] = class {}; - t.after(() => { if (original === undefined) delete globalThis[name]; else globalThis[name] = original; }); - } - const before = globalThis.document; - globalThis.document = { addEventListener: noop, removeEventListener: noop }; - t.after(() => { if (before === undefined) delete globalThis.document; else globalThis.document = before; }); +/** + * A viewer with a fake draw port, frame, camera and query bound. The camera + * stands at `camera.height`; `preRender()` runs the frame's preRender + * listeners, `emit()` its postRender ones. + */ +function viewer(t, { heights = () => null } = {}) { + const draw = fakeDrawPort(); + const frames = new Set(); + const before = new Set(); + const v = { requests: 0 }; + const frame = { + on(phase, cb) { + const listeners = + phase === 'postRender' ? frames : phase === 'preRender' ? before : null; + if (!listeners) return () => {}; + listeners.add(cb); + return () => listeners.delete(cb); + }, + requestRender() { + v.requests += 1; + }, + }; + const camera = { height: 2000, pose: () => ({ height: camera.height }) }; + const query = { sampleHeightNow: (point) => heights(point) }; + const unbind = bindRenderer(v, { draw, frame, query, camera }); + t.after(unbind); return { - creditDisplay: { addStaticCredit: noop, removeStaticCredit: noop }, - entities: new C.EntityCollection(), - dataSources: new C.DataSourceCollection(), - camera: { moveEnd: new C.Event(), positionCartographic: { height: 1000 } }, - scene: { requestRender: noop, canvas: { addEventListener: noop, removeEventListener: noop }, preRender: new C.Event(), - primitives: { add: (p) => p, remove: noop }, screenSpaceCameraController: { enableInputs: true } }, + v, + draw, + frames, + before, + camera, + emit: () => [...frames].forEach((cb) => cb()), + preRender: () => [...before].forEach((cb) => cb()), }; } const marks = () => [ - { id: 'route', type: 'route', color: 'amber', alpha: 1, anchor: { lat: 0, lon: 0 }, path: [{ lat: 0, lon: 0 }, { lat: 0.01, lon: 0.01 }] }, - { id: 'area', type: 'area', color: 'green', alpha: 1, anchor: { lat: 0.005, lon: 0.005 }, ring: [[0, 0], [0.01, 0], [0.01, 0.01], [0, 0]] }, - { id: 'pin', type: 'pin', color: 'primary', alpha: 1, anchor: { lat: 0.02, lon: 0.02 } }, + { + id: 'route', + type: 'route', + color: 'amber', + alpha: 1, + anchor: { lat: 0, lon: 0 }, + path: [ + { lat: 0, lon: 0 }, + { lat: 0.01, lon: 0.01 }, + ], + }, + { + id: 'area', + type: 'area', + color: 'green', + alpha: 1, + anchor: { lat: 0.005, lon: 0.005 }, + ring: [ + [0, 0], + [0.01, 0], + [0.01, 0.01], + [0, 0], + ], + }, + { + id: 'pin', + type: 'pin', + color: 'primary', + alpha: 1, + anchor: { lat: 0.02, lon: 0.02 }, + }, ]; -test('a hidden mark has every entity taken off on sync, and back when shown', (t) => { - const renderer = createWorldAnnotationRenderer(viewer(t)); +/** The live sets a mark draws into. */ +const setsOf = (draw, anno) => + [...draw.sets.values()].filter( + (record) => + !record.disposed && record.spec.id.startsWith(`${anno._draw.prefix}:`), + ); + +test('each mark draws in sets of its own; a hidden one has them hidden on sync, and back when shown', (t) => { + const { v, draw } = viewer(t); + const renderer = createWorldAnnotationRenderer(v); const [route, area, pin] = marks(); for (const anno of [route, area, pin]) renderer.add(anno); - const shown = (anno) => anno._entities.map((entity) => entity.show); - for (const anno of [route, area, pin]) assert.ok(anno._entities.length > 0, anno.id); + for (const anno of [route, area, pin]) + assert.ok(setsOf(draw, anno).length > 0, anno.id); + const shown = (anno) => setsOf(draw, anno).map((record) => record.show); route.hidden = true; area.hidden = true; renderer.sync(); - assert.ok(shown(route).every((show) => show === false), 'the line is off'); - assert.ok(shown(area).every((show) => show === false), 'the area is off'); - assert.ok(shown(pin).every((show) => show === true), 'a visible mark stays'); + assert.ok( + shown(route).every((show) => show === false), + 'the line is off', + ); + assert.ok( + shown(area).every((show) => show === false), + 'the area is off', + ); + assert.ok( + shown(pin).every((show) => show === true), + 'a visible mark stays', + ); route.hidden = false; renderer.sync(); - assert.ok(shown(route).every((show) => show === true), 'the line is back'); + assert.ok( + shown(route).every((show) => show === true), + 'the line is back', + ); + const areaSets = setsOf(draw, area); renderer.remove(area); + assert.ok( + areaSets.every((record) => record.disposed), + 'a removed mark lets its sets go', + ); renderer.sync(); - assert.equal(area._entities, null, 'a removed mark is no longer synced'); + renderer.destroy(); + assert.equal( + [...draw.sets.values()].filter((record) => !record.disposed).length, + 0, + ); +}); + +test('a fading mark takes its new colours in place, its pulses with them', (t) => { + const { v, draw } = viewer(t); + const renderer = createWorldAnnotationRenderer(v); + const [route, area] = marks(); + renderer.add(route); + renderer.add(area); + const line = () => [...setsOf(draw, route)[0].items.values()][0]; + const fill = () => + setsOf(draw, area) + .find((r) => r.kind === 'shapes') + .items.get('fill:0'); + assert.ok(Math.abs(line().style.color[3] - 0.95) < 1e-9); + assert.ok(Math.abs(fill().fill[3] - 0.2) < 1e-9); + route.alpha = 0.5; + area.alpha = 0.5; + renderer.sync(); + assert.ok(Math.abs(line().style.color[3] - 0.475) < 1e-9, 'fading'); + assert.ok(Math.abs(fill().fill[3] - 0.1) < 1e-9); + assert.deepEqual( + [fill().animate.from, fill().animate.to].map((a) => Math.round(a * 1000)), + [60, 100], + 'its pulse swings between 60% and all of its alpha', + ); + route.alpha = 0; + renderer.sync(); + assert.equal(line().style.color[3], 0, 'faded out: nothing painted'); renderer.destroy(); }); -test('the line\'s flowing stroke follows its mark\'s alpha', () => { - let alpha = 1; - const material = new FlowMaterialProperty('#ffb547', () => alpha); - assert.ok(Math.abs(material.getValue(null, {}).color.alpha - 0.95) < 1e-9); - alpha = 0; - assert.equal(material.getValue(null, {}).color.alpha, 0, 'hidden: nothing painted'); - alpha = 0.5; - assert.ok(Math.abs(material.getValue(null, {}).color.alpha - 0.475) < 1e-9, 'fading'); - assert.equal(new FlowMaterialProperty('#fff').getValue(null, {}).color.alpha, 0.95, 'no alpha source: opaque as before'); +test('every kind draws as it did: draped on terrain and tiles alike, rings by camera height, pulses', (t) => { + const { v, draw } = viewer(t); + const renderer = createWorldAnnotationRenderer(v); + const [route, area, pin] = marks(); + const synth = { ...area, id: 'synth', synthesized: true }; + const arrow = { + id: 'arrow', + type: 'arrow', + color: 'red', + alpha: 1, + anchor: { lon: 0, lat: 0 }, + to: { lon: 0.01, lat: 0 }, + }; + const label = { + id: 'label', + type: 'label', + color: 'amber', + alpha: 1, + anchor: { lon: 0.03, lat: 0 }, + }; + for (const anno of [route, area, pin, synth, arrow, label]) + renderer.add(anno); + const items = (anno, kind) => [ + ...(setsOf(draw, anno) + .find((r) => r.kind === kind) + ?.items.values() ?? []), + ]; + for (const record of [...draw.sets.values()]) + assert.equal(record.spec.clampTo, 'both'); + + const [flow] = items(route, 'lines'); + assert.equal(flow.mode, 'draped'); + assert.equal(flow.widthPx, 9); + assert.deepEqual( + { ...flow.style, color: undefined }, + { kind: 'flow', color: undefined, repeat: 64, duty: 0.46, speed: 0.55 }, + ); + + const [areaFill] = items(area, 'shapes'); + assert.equal(areaFill.height, 'clampGround'); + assert.equal(areaFill.animate.property, 'alpha'); + assert.ok(Math.abs(areaFill.animate.periodMs - (2 * Math.PI) / 0.005) < 1e-9); + const [areaLine] = items(area, 'lines'); + assert.deepEqual( + [areaLine.widthPx, areaLine.style.kind, areaLine.style.power], + [6, 'glow', 0.35], + ); + const [synthLine] = items(synth, 'lines'); + assert.deepEqual( + [synthLine.style.kind, synthLine.style.length], + ['dash', 24], + ); + assert.ok( + Math.abs(items(synth, 'shapes')[0].fill[3] - 0.1) < 1e-9, + 'an approximate area is fainter', + ); + + const [arrowLine] = items(arrow, 'lines'); + assert.deepEqual( + [arrowLine.mode, arrowLine.widthPx, arrowLine.style.kind], + ['draped', 16, 'arrow'], + ); + + const [ring] = items(pin, 'shapes'); + assert.equal(ring.geometry.semiMajor, 60, '3% of the camera height'); + assert.equal(ring.geometry.semiMinor, ring.geometry.semiMajor); + const [marker] = items(pin, 'points'); + assert.deepEqual( + [ + marker.pixelSize, + marker.height, + marker.outlineWidth, + marker.disableDepthTest, + ], + [14, 'clampGround', 3, Infinity], + ); + assert.equal(items(label, 'shapes').length, 0, 'a label has no ring'); + assert.equal(items(label, 'points')[0].pixelSize, 8); + renderer.destroy(); +}); + +test('target rings follow the camera height, sent again only when the radius changes, and catch up once shown', (t) => { + const { v, draw, camera, preRender, before } = viewer(t); + const renderer = createWorldAnnotationRenderer(v); + const [, , pin] = marks(); + const other = { ...pin, id: 'pin2', anchor: { lat: 0.03, lon: 0.03 } }; + renderer.add(pin); + renderer.add(other); + const ringOf = (anno) => + setsOf(draw, anno) + .find((r) => r.kind === 'shapes') + .items.get('ring'); + // Writes to the rings' sets since they were drawn. + const shapeSets = [pin, other].map((anno) => + setsOf(draw, anno).find((r) => r.kind === 'shapes'), + ); + const upserts = { + get length() { + return shapeSets.reduce((n, record) => n + record.writes - 1, 0); + }, + }; + assert.equal(ringOf(pin).geometry.semiMajor, 60); + assert.equal(before.size, 1, 'one listener for every ring'); + // The camera has not moved: nothing is sent. + preRender(); + assert.equal(upserts.length, 0); + // It climbs: both rings are sent at the new radius, once. + camera.height = 4000; + preRender(); + preRender(); + assert.equal(upserts.length, 2); + assert.equal(ringOf(pin).geometry.semiMajor, 120); + assert.equal(ringOf(pin).geometry.semiMinor, 120); + assert.equal(ringOf(other).geometry.semiMajor, 120); + // A change under 0.1% sends nothing. + camera.height = 4002; + preRender(); + assert.equal(upserts.length, 2); + // Held within 14 m and 170 m. + camera.height = 1e6; + preRender(); + assert.equal(ringOf(pin).geometry.semiMajor, 170); + camera.height = 10; + preRender(); + assert.equal(ringOf(pin).geometry.semiMajor, 14); + // A hidden mark waits, and catches up when shown. + other.hidden = true; + renderer.sync(); + camera.height = 3000; + preRender(); + assert.equal(ringOf(pin).geometry.semiMajor, 90); + assert.equal(ringOf(other).geometry.semiMajor, 14, 'hidden: not sent'); + other.hidden = false; + renderer.sync(); + assert.equal(ringOf(other).geometry.semiMajor, 90, 'shown: caught up'); + // The last ring gone, the listener goes with it. + renderer.remove(pin); + renderer.remove(other); + assert.equal(before.size, 0); + renderer.destroy(); +}); + +test('a building waits for its ground probes, then draws a pulsing column, a cage and a draped base', async (t) => { + const { v, draw, emit, frames } = viewer(t, { heights: () => 150 }); + const renderer = createWorldAnnotationRenderer(v); + const ring = [ + [0, 0], + [0.001, 0], + [0.001, 0.001], + [0, 0.001], + [0, 0], + ]; + const anno = { + id: 'b', + type: 'area', + color: 'amber', + alpha: 1, + footprintKind: 'building', + buildingHeight: 40, + anchor: { lon: 0.0005, lat: 0.0005, height: 200 }, + ring, + }; + const done = renderer.add(anno); + assert.equal(frames.size, 1, 'probing on the frames'); + assert.equal( + setsOf(draw, anno).length, + 0, + 'nothing until its ground is known', + ); + for (let i = 0; i < 8; i++) emit(); + assert.equal((await done).status, 'installed'); + assert.equal(frames.size, 0, 'done probing'); + const shapes = [ + ...setsOf(draw, anno) + .find((r) => r.kind === 'shapes') + .items.values(), + ]; + const volume = shapes.find((s) => s.id === 'volume:0'); + assert.equal(volume.extrudeHeight, 150 + 40 + 24); + assert.equal(volume.geometry.rings[0][0].height, 147); + assert.equal(volume.height, 'absolute'); + const cage = shapes.find((s) => s.id === 'cage:0'); + assert.equal(cage.outlineOnly, true); + assert.ok(cage.geometry.rings[0].length <= 14); + const [base] = setsOf(draw, anno) + .find((r) => r.kind === 'lines') + .items.values(); + assert.deepEqual( + [base.mode, base.widthPx, base.style.kind, base.style.power], + ['draped', 3, 'glow', 0.25], + ); + renderer.destroy(); +}); + +test('each kind paints the alphas it painted as entities, at full alpha', (t) => { + const { v, draw } = viewer(t, { heights: () => 150 }); + const renderer = createWorldAnnotationRenderer(v); + const [route, area, pin] = marks(); + const synth = { ...area, id: 'synth', synthesized: true }; + const arrow = { + id: 'arrow', + type: 'arrow', + color: 'red', + alpha: 1, + anchor: { lon: 0, lat: 0 }, + to: { lon: 0.01, lat: 0 }, + }; + const ring = Array.from({ length: 40 }, (_, i) => [ + 0.0005 + 0.0004 * Math.cos((i / 40) * 2 * Math.PI), + 0.0005 + 0.0004 * Math.sin((i / 40) * 2 * Math.PI), + ]); + const building = { + id: 'b', + type: 'area', + color: 'amber', + alpha: 1, + footprintKind: 'building', + buildingHeight: 40, + anchor: { lon: 0.0005, lat: 0.0005, height: 200 }, + ring, + }; + for (const anno of [route, area, pin, synth, arrow]) renderer.add(anno); + renderer.add(building, { sampledGroundHeight: 150 }); + const items = (anno, kind) => [ + ...(setsOf(draw, anno) + .find((r) => r.kind === kind) + ?.items.values() ?? []), + ]; + const alpha = (c) => Math.round(c[3] * 1000) / 1000; + assert.equal(alpha(items(route, 'lines')[0].style.color), 0.95); + assert.equal(alpha(items(area, 'lines')[0].style.color), 1); + assert.equal(alpha(items(synth, 'lines')[0].style.color), 0.95); + assert.equal(alpha(items(arrow, 'lines')[0].style.color), 0.95); + assert.equal(alpha(items(pin, 'shapes')[0].fill), 0.38); + const marker = items(pin, 'points')[0]; + assert.deepEqual( + [alpha(marker.color), alpha(marker.outlineColor)], + [1, 0.95], + ); + assert.deepEqual(marker.outlineColor.slice(0, 3), [1, 1, 1]); + const [volume, cage] = items(building, 'shapes'); + assert.equal(alpha(volume.fill), 0.45); + assert.equal(alpha(cage.outline), 0.32); + assert.equal( + Math.round(cage.animate.from * 1000) / 1000, + 0.192, + 'the cage pulses too', + ); + assert.equal(cage.geometry.rings[0].length, 14, 'decimated to 14'); + assert.equal(alpha(items(building, 'lines')[0].style.color), 0.7); + renderer.destroy(); +}); + +test('a mark removed and added again draws afresh; two renderers on one viewer keep apart', (t) => { + const { v, draw } = viewer(t); + const first = createWorldAnnotationRenderer(v); + const second = createWorldAnnotationRenderer(v); + const [route, area] = marks(); + first.add(route); + const prefix = route._draw.prefix; + first.remove(route); + assert.doesNotThrow(() => first.add(route)); + assert.notEqual(route._draw.prefix, prefix, 'fresh sets'); + assert.doesNotThrow(() => second.add(area)); + assert.ok( + !area._draw.prefix.startsWith( + route._draw.prefix.split(':').slice(0, 2).join(':') + ':', + ), + ); + // Added again as another kind, its old sets go. + const kinds = () => + setsOf(draw, route) + .map((r) => r.kind) + .sort(); + assert.deepEqual(kinds(), ['lines']); + Object.assign(route, { type: 'pin', path: undefined }); + first.add(route); + assert.deepEqual(kinds(), ['points', 'shapes']); + assert.doesNotThrow(() => first.remove(null)); + first.destroy(); + second.destroy(); + assert.equal(route._draw, null); + first.add(route); + assert.equal(route._draw, null, 'a destroyed renderer draws nothing more'); + assert.equal([...draw.sets.values()].filter((r) => !r.disposed).length, 0); }); diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs index c01878d891..00807c0972 100644 --- a/src/app/application.test.mjs +++ b/src/app/application.test.mjs @@ -2,20 +2,74 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { spawnSync } from 'node:child_process'; import { createApplication } from './application.js'; +import { installTrackpadPinchRelay } from '../render/cesium/ctrlWheelZoom.js'; import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js'; import * as Cesium from 'cesium'; -import { - installFreeLookHeightLimit, - installGlobeInViewRecovery, - installTrackpadPinchZoom, -} from './viewer.js'; -import { - FREE_LOOK_MAX_HEIGHT_METERS, - globeFrameShare, - globeOutOfFrame, - lookAngleWithinFrame, - lookStepLosesGlobe, -} from '../globeInView.js'; +import { installFreeLookHeightLimit } from '../render/cesium/freeLookLimit.js'; +import { installGlobeInViewRecovery } from './globeInViewRecovery.js'; +import { FREE_LOOK_MAX_HEIGHT_METERS } from '../globeInView.js'; +import * as globeInView from '../globeInView.js'; +import { createCesiumCamera } from '../render/cesium/camera.js'; +import { bindRenderer } from '../render/rendererOf.js'; +import { entityFollowTarget } from '../data/followed.js'; + +/** The camera port bound over each real Cesium camera a test makes. */ +const cameraPorts = new WeakMap(); + +/** + * Bind `viewer` the Cesium renderer's own camera port over its real camera, + * with the camera's own `moveStart` and `moveEnd` so a test raises them, and + * a frame port that counts render requests on the scene. + */ +function bindCameraPorts(viewer) { + const { camera, scene } = viewer; + const noEvent = { addEventListener: () => () => {} }; + const real = createCesiumCamera({ + scene: { + postUpdate: noEvent, + preUpdate: noEvent, + get screenSpaceCameraController() { + return scene.screenSpaceCameraController; + }, + requestRender: () => scene.requestRender?.(), + }, + camera, + report: (error) => { + throw error; + }, + }).port; + const port = Object.create(real, { + on: { value: (event, cb) => camera[event].addEventListener(cb) }, + }); + cameraPorts.set(camera, port); + bindRenderer(viewer, { + camera: port, + get canvas() { + return scene.canvas; + }, + frame: { + on: () => () => {}, + requestRender: () => scene.requestRender?.(), + }, + }); +} + +// The frame measures take a camera pose; these take the test's camera. +const poseOf = (camera) => cameraPorts.get(camera).pose(); +const LOOKS = { + lookUp: 'up', + lookDown: 'down', + lookLeft: 'left', + lookRight: 'right', +}; +const globeFrameShare = (camera, options) => + globeInView.globeFrameShare(poseOf(camera), options); +const globeOutOfFrame = (camera, options) => + globeInView.globeOutOfFrame(poseOf(camera), options); +const lookAngleWithinFrame = (camera, look, angle, options) => + globeInView.lookAngleWithinFrame(poseOf(camera), LOOKS[look], angle, options); +const lookStepLosesGlobe = (camera, look, angle, options) => + globeInView.lookStepLosesGlobe(poseOf(camera), LOOKS[look], angle, options); const phases = ['Scene', 'Controls', 'Data', 'Tools']; function fixture(overrides = {}) { @@ -235,8 +289,9 @@ test('the separate viewer export imports without constructing a browser viewer', }); test('the viewer gets the starry sky as an option, which keeps the Sun and Moon', async () => { - const { applicationViewerOptions } = await import('./viewer.js'); - const { StarrySky } = await import('../sky/starrySky.js'); + const { applicationViewerOptions } = + await import('../render/cesium/applicationViewer.js'); + const { StarrySky } = await import('../render/cesium/starrySky.js'); const creditContainer = {}; const options = applicationViewerOptions(creditContainer); // CesiumWidget skips scene.sun and scene.moon when skyBox is false. @@ -300,14 +355,13 @@ function pinchFixture({ zoomEventTypes } = {}) { return { viewer, controller, container, handlers, relayed, createEvent }; } -test('trackpad pinch adds the Ctrl+wheel binding without replacing Cesium inputs', () => { +test('the trackpad pinch relay leaves the zoom bindings and plain or line-mode wheels alone', () => { const original = [1, 2, 3]; const f = pinchFixture({ zoomEventTypes: original }); - const dispose = installTrackpadPinchZoom(f.viewer, { + const dispose = installTrackpadPinchRelay(f.viewer, { createWheelEvent: (_type, init) => f.createEvent(init), }); - assert.deepEqual(f.controller.zoomEventTypes.slice(0, 3), original); - assert.equal(f.controller.zoomEventTypes.length, 4); + assert.equal(f.controller.zoomEventTypes, original); const plain = f.createEvent({ deltaY: 2 }); f.container.emit(plain); @@ -325,7 +379,7 @@ test('trackpad pinch adds the Ctrl+wheel binding without replacing Cesium inputs test('trackpad pinch relays pixel deltas once with bounded amplification', () => { const f = pinchFixture({ zoomEventTypes: [1, 2, 3] }); - installTrackpadPinchZoom(f.viewer, { + installTrackpadPinchRelay(f.viewer, { createWheelEvent: (_type, init) => f.createEvent(init), }); @@ -345,7 +399,7 @@ test('trackpad pinch relays pixel deltas once with bounded amplification', () => test('trackpad pinch falls back to the original event when relay construction fails', () => { const f = pinchFixture({ zoomEventTypes: [1, 2, 3] }); - installTrackpadPinchZoom(f.viewer, { + installTrackpadPinchRelay(f.viewer, { createWheelEvent() { throw new Error('unsupported'); }, @@ -382,7 +436,10 @@ function freeLookFixture({ enableLook = true, height = 0 } = {}) { test('free look follows camera height and is restored on dispose', () => { const f = freeLookFixture({ height: 500 }); - const dispose = installFreeLookHeightLimit(f.viewer); + const dispose = installFreeLookHeightLimit( + f.viewer, + FREE_LOOK_MAX_HEIGHT_METERS, + ); assert.equal(f.controller.enableLook, true); f.frame(FREE_LOOK_MAX_HEIGHT_METERS + 1); @@ -402,7 +459,10 @@ test('free look follows camera height and is restored on dispose', () => { test('drags that start on the stars orbit above the free-look height', () => { // Below Cesium's trackball height such a drag turns the camera in place. const f = freeLookFixture({ height: 500 }); - const dispose = installFreeLookHeightLimit(f.viewer); + const dispose = installFreeLookHeightLimit( + f.viewer, + FREE_LOOK_MAX_HEIGHT_METERS, + ); assert.equal( f.controller.minimumTrackBallHeight, FREE_LOOK_MAX_HEIGHT_METERS, @@ -412,7 +472,10 @@ test('drags that start on the stars orbit above the free-look height', () => { const lower = freeLookFixture({ height: 500 }); lower.controller.minimumTrackBallHeight = 500_000; - const disposeLower = installFreeLookHeightLimit(lower.viewer); + const disposeLower = installFreeLookHeightLimit( + lower.viewer, + FREE_LOOK_MAX_HEIGHT_METERS, + ); assert.equal( lower.controller.minimumTrackBallHeight, 500_000, @@ -422,7 +485,10 @@ test('drags that start on the stars orbit above the free-look height', () => { assert.equal(lower.controller.minimumTrackBallHeight, 500_000); const later = freeLookFixture({ height: 500 }); - const disposeLater = installFreeLookHeightLimit(later.viewer); + const disposeLater = installFreeLookHeightLimit( + later.viewer, + FREE_LOOK_MAX_HEIGHT_METERS, + ); later.controller.minimumTrackBallHeight = 2_000_000; disposeLater(); assert.equal( @@ -434,7 +500,10 @@ test('drags that start on the stars orbit above the free-look height', () => { test('free look keeps a setting other code makes after it is installed', () => { const f = freeLookFixture({ height: 500 }); - const dispose = installFreeLookHeightLimit(f.viewer); + const dispose = installFreeLookHeightLimit( + f.viewer, + FREE_LOOK_MAX_HEIGHT_METERS, + ); f.controller.enableLook = false; f.frame(10); assert.equal(f.controller.enableLook, false, 'turned off stays off'); @@ -454,7 +523,7 @@ test('free look keeps a setting other code makes after it is installed', () => { test('free look stays off when the viewer had it disabled', () => { const f = freeLookFixture({ enableLook: false, height: 500 }); - installFreeLookHeightLimit(f.viewer); + installFreeLookHeightLimit(f.viewer, FREE_LOOK_MAX_HEIGHT_METERS); f.frame(10); assert.equal(f.controller.enableLook, false); }); @@ -479,7 +548,9 @@ function realCamera({ width = 1600, height = 900, mode } = {}) { }; const camera = new Cesium.Camera(scene); camera.frustum.aspectRatio = width / height; - return { camera, scene, viewer: { camera, scene } }; + const viewer = { camera, scene }; + bindCameraPorts(viewer); + return { camera, scene, viewer }; } function aim( @@ -573,7 +644,8 @@ test('a move that ends with the globe out of frame turns back to nadir', () => { Cesium.Cartesian3.equalsEpsilon(camera.positionWC, position, 0, 1e-3), ); assert.equal(globeOutOfFrame(camera), false); - assert.equal(scene.renders, 1); + // One render for the new view, one the recovery asks for itself. + assert.equal(scene.renders, 2, 'the turned view is drawn'); // Looking up near the ground, then zoomed out past the limit. aim(camera, { alt: 3_834_000, pitch: 10 }); @@ -602,7 +674,7 @@ function moveEndKeepsView(camera) { return Cesium.Cartesian3.equalsEpsilon(camera.directionWC, direction, 1e-9); } -test('globe recovery leaves partial, low, locked and 2D views alone', () => { +test('globe recovery leaves partial, low, locked and following views alone', () => { for (const view of partialGlobeViews) { const { camera, viewer } = realCamera(); installGlobeInViewRecovery(viewer); @@ -626,19 +698,18 @@ test('globe recovery leaves partial, low, locked and 2D views alone', () => { assert.equal(globeOutOfFrame(locked.camera), true); assert.ok(moveEndKeepsView(locked.camera), 'locked camera'); - // Tracking an entity that has no position yet keeps an identity transform. + // Following an entity that has no position yet keeps an identity transform. const tracked = realCamera(); - tracked.viewer.trackedEntity = { id: 'pending-fix' }; + const pending = entityFollowTarget( + { id: 'pending-fix' }, + { position: () => null }, + ); + Object.defineProperty(cameraPorts.get(tracked.camera), 'followed', { + get: () => pending, + }); installGlobeInViewRecovery(tracked.viewer); aim(tracked.camera, reportedStuckView); assert.ok(moveEndKeepsView(tracked.camera), 'tracked camera'); - - const flat = realCamera({ mode: Cesium.SceneMode.COLUMBUS_VIEW }); - installGlobeInViewRecovery(flat.viewer); - flat.scene.mode = Cesium.SceneMode.SCENE3D; - aim(flat.camera, reportedStuckView); - flat.scene.mode = Cesium.SceneMode.COLUMBUS_VIEW; - assert.ok(moveEndKeepsView(flat.camera), 'Columbus view'); }); test('the look limit from orbit tolerates grid noise and never reaches zero', () => { diff --git a/src/app/constructCatalog.js b/src/app/constructCatalog.js index a76b37bd47..ed6821edda 100644 --- a/src/app/constructCatalog.js +++ b/src/app/constructCatalog.js @@ -1,10 +1,12 @@ import { resolveCatalogSources } from './sourceComposition.js'; import { createWeatherClock } from '../layers/weather/clock.js'; import { worldClock } from '../time/worldClock.js'; +import { NEWS_LAYER_ID } from '../layers/news/model.js'; import { createWeatherLayer } from '../layers/weather/index.js'; import { createApplicationCyclones } from './layers/cyclones.js'; import { createWindLayer } from '../layers/wind/index.js'; import { createLayerCatalog } from './catalog.js'; +import { layerPlacement } from '../data/placementProvider.js'; import { LAYER_STATE_REGISTRY } from '../data/layerState.js'; import { createMilitaryRegistry } from '../layers/aircraft/classification.js'; import { createApplicationFlights } from './layers/flights.js'; @@ -18,6 +20,7 @@ import { createApplicationDirections } from './layers/directions.js'; import { createApplicationRecentImagery } from './layers/recentImagery.js'; import { createApplicationOsmPlaces } from './layers/osmPlaces.js'; import { createApplicationTransit } from './layers/transit.js'; +import { createApplicationRail } from './layers/rail.js'; import { createApplicationInstallations } from './layers/militaryInstallations.js'; import { createApplicationSatellites } from './layers/satellites.js'; import { createApplicationLaunches } from './layers/rocketLaunches.js'; @@ -30,7 +33,9 @@ import { createApplicationAirQuality } from './layers/airQuality.js'; import { createApplicationFirePerimeters } from './layers/perimeters.js'; import { createApplicationGnssIntegrity } from './layers/gnss.js'; import { createApplicationGhostMaps } from './layers/ghostMaps.js'; +import { createApplicationShipwrecks } from './layers/shipwrecks.js'; import { createApplicationDroneAirspace } from './layers/droneAirspace.js'; +import { createApplicationNews } from './layers/news.js'; import { createApplicationWildlifeSightings } from './layers/wildlifeSightings.js'; import { createApplicationCables } from './layers/submarineCables.js'; import { createOsmOverlayLayers } from '../data/osmOverlays.js'; @@ -59,6 +64,9 @@ export const APPLICATION_LAYER_METADATA = Object.freeze([ /** Construct the current catalog without choosing any source provider. * Scene engines remain page-owned; layers and classification have this app's lifetime. * The manager owns layer destruction, while abort releases classification even if startup fails. + * `placement`, a host-supplied placement provider (../data/placementProvider.js), + * places live aircraft, vessels, transit and trains; without one each layer + * uses its own motion. */ export function createApplicationCatalog({ surface, @@ -66,9 +74,11 @@ export function createApplicationCatalog({ signal, metadata = APPLICATION_LAYER_METADATA, vesselOptions, + newsOptions, resolveAsset, nepalBoundaryResolver, streetLevelProviders, + placement = null, }) { if (!signal?.addEventListener) throw new TypeError('An application lifetime signal is required'); @@ -92,18 +102,23 @@ export function createApplicationCatalog({ const flights = createApplicationFlights({ surface, source: sources.flights, + placement: layerPlacement(placement, 'aircraft'), militaryRegistry, resolveAsset, }); const military = createApplicationMilitary({ surface, source: sources.military, + placement: layerPlacement(placement, 'military'), militaryRegistry, resolveAsset, }); const vessels = createApplicationVessels({ source: sources.vessels, + placement: layerPlacement(placement, 'vessels'), options: vesselOptions, + displayParams: () => flights.getParams(), + ...(resolveAsset ? { resolveAsset } : {}), }); const installations = createApplicationInstallations({ surface, @@ -136,9 +151,17 @@ export function createApplicationCatalog({ windowMs: sources['gnss-integrity'].windowMs, }), createApplicationGhostMaps({ source: sources['s2-ghostmaps'] }), + createApplicationShipwrecks({ source: sources.shipwrecks }), createApplicationDroneAirspace({ source: sources['drone-airspace'], }), + // Ages, the window and the counts read the world clock: a host that + // follows it for the layer shows the news at the time on the timeline. + createApplicationNews({ + now: worldClock.timeFor(NEWS_LAYER_ID), + ...newsOptions, + source: sources.news, + }), createApplicationWildlifeSightings({ source: sources['wildlife-sightings'], groundFloor: surface.groundFloor, @@ -154,7 +177,13 @@ export function createApplicationCatalog({ createApplicationTraffic({ source: sources.traffic, surface }), createApplicationCctv({ surface, source: sources.cctv }), createApplicationRadio({ surface, source: sources.radio }), - createApplicationTransit({ surface, source: sources.transit }), + createApplicationTransit({ + surface, + source: sources.transit, + placement: layerPlacement(placement, 'transit'), + displayParams: () => flights.getParams(), + ...(resolveAsset ? { resolveAsset } : {}), + }), createApplicationBikeshare({ source: sources.bikeshare }), createApplicationDirections({ source: sources.directions }), createApplicationRecentImagery({ source: sources['recent-imagery'] }), @@ -187,6 +216,13 @@ export function createApplicationCatalog({ ...createOsmOverlayLayers(), ...createInfrastructureLayers(localGeoJsonServices), createApplicationCables({ source: sources.cables }), + createApplicationRail({ + surface, + source: sources.rail, + placement: layerPlacement(placement, 'rail'), + displayParams: () => flights.getParams(), + ...(resolveAsset ? { resolveAsset } : {}), + }), createApplicationFirms({ surface, id: 'local-firms', diff --git a/src/app/constructCatalog.test.mjs b/src/app/constructCatalog.test.mjs index 3d61df3b3e..ea6b46cd66 100644 --- a/src/app/constructCatalog.test.mjs +++ b/src/app/constructCatalog.test.mjs @@ -6,6 +6,11 @@ import { createStandaloneLayerSources } from '../standalone/layerSources.js'; import { catalogControlServices } from './catalog.js'; import { LayerLifecycle } from '../data/lifecycle.js'; import { fakeStreetLevelProvider } from '../testSupport/streetLevelFakes.mjs'; +import { worldClock } from '../time/worldClock.js'; + +const flush = async () => { + for (let i = 0; i < 20; i++) await Promise.resolve(); +}; function fixtureSources(ids, calls) { const sources = createStandaloneLayerSources(); @@ -27,6 +32,7 @@ test('catalogs construct distinct layers and classification from their supplied t.after(() => { a.abort(); b.abort(); + worldClock.goLive(); }); const callsA = []; const callsB = []; @@ -40,7 +46,7 @@ test('catalogs construct distinct layers and classification from their supplied signal: b.signal, surface: fixtureSurface(b.signal), }); - assert.equal(first.layers.length, 38); + assert.equal(first.layers.length, 41); assert.ok(first.get('local-adsb'), 'Local ADS-B is registered'); assert.deepEqual( first.metadata.find(({ id }) => id === 'osm-places'), @@ -53,7 +59,10 @@ test('catalogs construct distinct layers and classification from their supplied 'the hardware-local layer is never serialized into links', ); assert.notEqual(first.weatherClock, second.weatherClock); - await first.weatherClock.setTarget('2026-09-21T12:00:00.000Z'); + // Time moves on the world clock, which the catalog's weather clock follows. + assert.equal(first.weatherClock.world, worldClock); + worldClock.seek(Date.parse('2026-09-21T12:00:00.000Z')); + await flush(); assert.match( first.get('wind').getRowControls().info, /Forecast · does not follow history/, @@ -68,6 +77,7 @@ test('catalogs construct distinct layers and classification from their supplied assert.ok(first.get('gnss-integrity')); assert.ok(first.get('s2-ghostmaps')); assert.ok(first.get('drone-airspace')); + assert.ok(first.get('news')); assert.ok(first.get('transit')); const order = first.layers.map(({ id }) => id); assert.deepEqual( @@ -110,9 +120,16 @@ test('catalogs construct distinct layers and classification from their supplied assert.equal(first.militaryRegistry.isMilitaryIcao('def456'), false); assert.equal(second.militaryRegistry.isMilitaryIcao('def456'), true); a.abort(); + worldClock.seek(Date.parse('2026-09-21T13:00:00.000Z')); + await flush(); assert.equal( - await first.weatherClock.setTarget('2026-09-21T13:00:00.000Z'), - false, + first.weatherClock.getState().target, + '2026-09-21T12:00:00.000Z', + 'an aborted catalog no longer follows the world clock', + ); + assert.equal( + second.weatherClock.getState().target, + '2026-09-21T13:00:00.000Z', ); assert.equal(callsA[0].aborted, true); assert.equal(first.militaryRegistry.isMilitaryIcao('abc123'), false); @@ -161,7 +178,7 @@ test('Mapillary can be omitted or replaced without changing catalog membership', surface: fixtureSurface(lifetime.signal), }; const catalog = createApplicationCatalog(options); - assert.equal(catalog.layers.length, 38); + assert.equal(catalog.layers.length, 41); assert.deepEqual(catalog.get('street-level').providerIds, []); assert.equal( catalogControlServices(catalog).streetLevelLayer, @@ -217,9 +234,8 @@ test('a GNSS integrity source can set the layer evidence window', (t) => { }; const shows = (layer, minutes) => { assert.equal(layer.provenance.window.minutes, minutes); - const { info, legend } = layer.getRowControls(); + const { info } = layer.getRowControls(); assert.match(info, new RegExp(`visited views over ${minutes} min`)); - assert.match(legend[0].blurb, new RegExp(`over ${minutes} minutes`)); }; shows(gnssLayer({ windowMs: 65 * 60_000 }), 65); shows(gnssLayer({}), 30); diff --git a/src/app/controls.js b/src/app/controls.js index 99bc2555f2..8e152a1e02 100644 --- a/src/app/controls.js +++ b/src/app/controls.js @@ -1,18 +1,31 @@ import { catalogControlServices } from './catalog.js'; import { StyleManager } from '../ui/composition.js'; -import { flyToAustin } from '../camera.js'; -import { installZoomOutGuard } from './zoomOutGuard.js'; +import { applyStartView, START_VIEW } from '../camera.js'; import { initCockpitCloudEffects } from '../cockpitCloudEffects.js'; +import { createViewSky } from '../viewSky.js'; +import { findGlobe } from '../render/rendererOf.js'; +import { useDisplayStore } from '../ui/stores/display.js'; +import { applicationPinia } from '../ui/vueRuntime.js'; import { t } from '../i18n/index.js'; +/** Where the camera starts unless a host gives a `startView`. */ +export { START_VIEW }; + /** * Construct the existing controls and camera presentation. `initialShareCode` * opens a share code (the `` of `/share/`) at start-up, for a host * whose address does not carry one. `localePicker: false` removes the language - * picker, for a host that does not initialize Core's locale. + * picker, for a host that offers its own language choice (`switchLocale` from + * the `./i18n` entry). `startView` is where the camera starts (the whole + * planet by default; a host may pass a city); a shared view flies from there. + * `homeView` is where the title's logo goes back to (with the clock live): the + * start view unless given, for a host whose `startView` only carries a view + * across a rebuild. + * `services.cockpitSubjects` adds the application's own first-person subjects + * to the Cockpit (src/cockpitSubjectProviders.js). */ export function createApplicationControls({ - scene: { viewer, mapStackController, operations }, + scene: { viewer, mapStackController, operations, viewerDrawsEntity }, loaderStatus, Controls = StyleManager, services, @@ -21,16 +34,23 @@ export function createApplicationControls({ defer, initialShareCode = null, localePicker = true, + startView = START_VIEW, + homeView = startView, }) { + // Every boot starts from the same view, before share restoration flies on. + applyStartView(viewer, startView); // Initialize the style manager (post-processing, HUD, locations, share links) const styleManager = new Controls(viewer, { services: { ...services, ...operations.surface.controlServices, searchAndFlyTo: operations.searchAndFlyTo, + pickWorldFromScreen: operations.annotationResolver?.pickWorldFromScreen, fetchRegionalBrief: (...args) => operations.requests.regional.getBrief(...args), ...catalogControlServices(catalog), + // Whether an entity is one of the viewer's own; the scene answers it. + viewerDrawsEntity: viewerDrawsEntity ?? services?.viewerDrawsEntity, }, requestServices: operations.requests, mapStackController, @@ -38,32 +58,32 @@ export function createApplicationControls({ // A share code to open at start-up instead of the page's address. initialShareCode, localePicker, + homeView, }); defer(() => styleManager.orbitController.stop()); defer(() => styleManager.hud.destroy()); defer(() => styleManager.dispose()); - defer( - installZoomOutGuard(viewer, { - subscribeCameraHandoff: (listener) => - styleManager.subscribeCameraHandoff?.(listener), - }), - ); // The previous multi-canvas weather compositor remains disabled. Cockpit // clouds use a separate, capped low-resolution GPU pass that never attaches // Cesium fog or post-process stages and is fully stopped in map mode. const weatherEffects = null; - const cockpitCloudEffects = initCockpitCloudEffects(viewer, { - weatherService: operations.requests.weather, - }); + // Where the renderer draws weather, it draws the cockpit's clouds too. + const cockpitCloudEffects = findGlobe(viewer)?.weather + ? null + : initCockpitCloudEffects(viewer, { + weatherService: operations.requests.weather, + }); defer(() => cockpitCloudEffects?.destroy()); + // The atmosphere, sun lighting, sun, moon, stars and Milky Way the user + // chooses in the Display panel. + const viewSky = createViewSky(viewer, { + store: useDisplayStore(applicationPinia()), + }); + defer(() => viewSky.destroy()); - // If no share link state, do default fly-to Austin - if (!styleManager.hasShareState) { - loaderStatus.textContent = t('Flying to Austin, TX...'); - defer(flyToAustin(viewer)); - } else { - loaderStatus.textContent = t('Restoring shared view...'); - } + loaderStatus.textContent = styleManager.hasShareState + ? t('Restoring shared view...') + : t('Loading'); return { styleManager, weatherEffects, cockpitCloudEffects }; } diff --git a/src/app/controls.test.mjs b/src/app/controls.test.mjs index 3db3b7d8b8..ebf847b077 100644 --- a/src/app/controls.test.mjs +++ b/src/app/controls.test.mjs @@ -1,9 +1,8 @@ import test, { after, before } from 'node:test'; import assert from 'node:assert/strict'; -import * as Cesium from 'cesium'; import '../testSupport/stubMgrs.mjs'; import { installVueDom } from '../testSupport/vueDom.mjs'; -import { MAXIMUM_ZOOM_DISTANCE_M } from './zoomOutGuard.js'; +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; const { createApplicationControls } = await import('./controls.js'); @@ -13,35 +12,20 @@ before(() => { }); after(() => uninstallDom()); -test('application controls install the zoom-out guard and remove it on teardown', () => { - const canvas = document.createElement('canvas'); - const controller = { maximumZoomDistance: Infinity }; - const scene = { - mode: Cesium.SceneMode.SCENE3D, - screenSpaceCameraController: controller, - preRender: new Cesium.Event(), - postUpdate: new Cesium.Event(), - }; - const camera = { - position: Cesium.Cartesian3.fromDegrees(0, 0, 1_000_000), - positionCartographic: { height: 1_000_000 }, - }; - const viewer = { scene, camera, canvas }; - const handoffs = new Set(); +test('the application controls start and stop', () => { class Controls { hasShareState = true; orbitController = { stop() {} }; hud = { destroy() {} }; dispose() {} - subscribeCameraHandoff(listener) { - handoffs.add(listener); - return () => handoffs.delete(listener); - } } const cleanups = []; createApplicationControls({ scene: { - viewer, + viewer: bindFakeCesiumCamera({ + isDestroyed: () => false, + camera: { setView() {} }, + }), mapStackController: {}, operations: { surface: { controlServices: {} }, @@ -54,15 +38,5 @@ test('application controls install the zoom-out guard and remove it on teardown' catalog: { get: (id) => ({ id }) }, defer: (cleanup) => cleanups.push(cleanup), }); - - assert.equal(controller.maximumZoomDistance, MAXIMUM_ZOOM_DISTANCE_M); - assert.equal(scene.preRender.numberOfListeners, 1); - assert.equal(scene.postUpdate.numberOfListeners, 1); - assert.equal(handoffs.size, 1); - for (const cleanup of cleanups.reverse()) cleanup(); - assert.equal(controller.maximumZoomDistance, Infinity); - assert.equal(scene.preRender.numberOfListeners, 0); - assert.equal(scene.postUpdate.numberOfListeners, 0); - assert.equal(handoffs.size, 0); }); diff --git a/src/app/data.js b/src/app/data.js index 022839cd21..7e20f13150 100644 --- a/src/app/data.js +++ b/src/app/data.js @@ -15,7 +15,7 @@ export function createApplicationData({ const dataManager = new LayerLifecycle(viewer, { allowQaRegistration, // A panel's host may report it hidden while it is on screen; its layers - // keep polling (see keepPanelRendering in embed.js). + // keep polling (see keepPanelRendering in app/panelRendering.js). visibilityTarget: panelAwareVisibility(document), getSourceAvailability: catalog?.getSourceAvailability, }); diff --git a/src/app/embed.js b/src/app/embed.js index 21e685a914..c30731d895 100644 --- a/src/app/embed.js +++ b/src/app/embed.js @@ -11,14 +11,27 @@ * embedded or not. */ -import * as Cesium from 'cesium'; -import { announceNavigationAuthority } from '../navigationPolicy.js'; -import { annotationsFromParams, createView } from '../view/index.js'; +import { + announceNavigationAuthority, + watchCameraOwner, +} from '../navigationPolicy.js'; +import { toRadians } from '../geo/index.js'; +import { t, translateKnown } from '../i18n/index.js'; +import { GOOGLE_LABEL } from '../layers/streetLevel/providers/google/policy.js'; +import { cameraOf } from '../render/rendererOf.js'; +import { + annotationsFromParams, + createView, + followFromParams, + groundedLookAt, + streetLevelFromParams, +} from '../view/index.js'; const EMBED_VIEW_MESSAGE = 'gev:view'; const EMBED_APPLIED_MESSAGE = 'gev:view-applied'; const EMBED_READY_MESSAGE = 'gev:ready'; +const STREET_LEVEL_LAYER = 'street-level'; const FOLLOW_LAYERS = { aircraft: 'flights', military_aircraft: 'military', @@ -27,6 +40,8 @@ const FOLLOW_LAYERS = { const FOLLOW_ATTEMPTS = 20; const FOLLOW_RETRY_MS = 1000; const FLIGHT_SECONDS = 2; +/** How long a posted view waits for the terrain under its camera. */ +const TERRAIN_WAIT_MS = 2000; /** * Whether this page shows the app embedded: `?embed=1` when another page @@ -45,9 +60,18 @@ export function isEmbeddedInline() { return globalThis.GEV_EMBED_INLINE === true; } +/** + * Whether the panel page started the app for a tool result issued just now, + * not one its host handed back on mounting the panel again. + */ +function isFreshPanelResult() { + return isEmbeddedInline() && globalThis.GEV_EMBED_FRESH === true; +} + /** * `doc`'s visibility for work that pauses in a hidden page. A panel's host - * may report it hidden while it is on screen (see keepPanelRendering), so an + * may report it hidden while it is on screen (see keepPanelRendering in + * render/cesium/panelRendering.js), so an * inline panel always reads as visible. */ export function panelAwareVisibility(doc = globalThis.document) { @@ -67,69 +91,6 @@ export function panelAwareVisibility(doc = globalThis.document) { }; } -// A panel keeps drawing at about this rate when its host stops animation -// frames; see keepPanelRendering. -const PANEL_FRAME_MS = 33; -const MISSED_FRAMES_MS = 250; - -/** A render error's details, including the plain objects workers report. */ -function describeError(error) { - if (error instanceof Error) - return `${error.name}: ${error.message}\n${error.stack}`; - try { - return JSON.stringify(error, Object.getOwnPropertyNames(error ?? {})); - } catch { - return String(error); - } -} - -/** - * Keep the globe drawing in an inline panel. Some hosts report a panel on - * screen as hidden, which stops the browser's animation frames and with them - * Cesium's render loop; while frames stop arriving, draw from a timer. - * Returns a function that stops it. - */ -export function keepPanelRendering( - viewer, - { windowRef = globalThis.window, now = () => performance.now() } = {}, -) { - let lastFrame = now(); - let frameRequest = null; - const onFrame = () => { - lastFrame = now(); - frameRequest = windowRef.requestAnimationFrame(onFrame); - }; - frameRequest = windowRef.requestAnimationFrame(onFrame); - // Cesium stops drawing after a render error, and so does the timer. - // Report the error in full: workers report plain objects, which Cesium - // prints as [object Object]. - let failed = false; - const removeErrorListener = viewer.scene?.renderError?.addEventListener( - (_scene, error) => { - failed = true; - console.error( - "[God's Eye View panel] render error:", - describeError(error), - ); - }, - ); - const timer = windowRef.setInterval(() => { - if ( - failed || - now() - lastFrame < MISSED_FRAMES_MS || - viewer.isDestroyed?.() - ) - return; - viewer.resize(); - viewer.render(); - }, PANEL_FRAME_MS); - return () => { - windowRef.clearInterval(timer); - windowRef.cancelAnimationFrame(frameRequest); - removeErrorListener?.(); - }; -} - const delay = (ms, signal) => new Promise((resolve) => { const timer = setTimeout(resolve, ms); @@ -147,24 +108,56 @@ const delay = (ms, signal) => function flyTo(viewer, camera) { announceNavigationAuthority('embed-view'); return new Promise((resolve) => { - viewer.camera.flyTo({ - destination: Cesium.Cartesian3.fromDegrees( - camera.lon, - camera.lat, - camera.altitude_m, - ), - orientation: { - heading: Cesium.Math.toRadians(camera.heading_deg), - pitch: Cesium.Math.toRadians(camera.pitch_deg), - roll: 0, + cameraOf(viewer).flyTo( + { lon: camera.lon, lat: camera.lat, height: camera.altitude_m }, + { + orientation: { + heading: toRadians(camera.heading_deg), + pitch: toRadians(camera.pitch_deg), + roll: 0, + }, + durationS: FLIGHT_SECONDS, + onComplete: () => resolve(true), + onCancel: () => resolve(false), }, - duration: FLIGHT_SECONDS, - complete: () => resolve(true), - cancel: () => resolve(false), - }); + ); }); } +/** + * The `show_street_level` arguments for a view's street-level photos. A plain + * link (`autoOpen: false`) only arms a source that bills every load; a view + * posted into the embedded app is the client's own request and opens. + */ +function streetLevelArgs(streetLevel, { autoOpen = true } = {}) { + return { + latitude: streetLevel.lat, + longitude: streetLevel.lon, + ...(streetLevel.provider ? { provider: streetLevel.provider } : {}), + fly: true, + ...(autoOpen ? {} : { autoOpen: false }), + }; +} + +const STREET_LEVEL_PANEL_ID = 'street-level-panel'; +/** Dispatched on the window when a link opened after start-up has restored. */ +const SHARE_NAVIGATION_RESTORED_EVENT = 'gev:share-navigation-restore-settled'; + +/** The armed link's toast, naming the OPEN button as the panel shows it. */ +function armedToast() { + return t('Street View is ready: press {open} to load it', { + open: t('OPEN {labels}', { labels: translateKnown(GOOGLE_LABEL) }), + }); +} + +/** Why a link's photo stays shut: its source has no working key here. */ +function keyToast(result) { + return t( + "{source} cannot open this link's street-level photo without a working key", + { source: translateKnown(result.providerName || 'Street Level') }, + ); +} + /** * Make the app show a view: style and map, exactly the view's layers, * annotations, the camera, and the followed entity. Each step runs through the @@ -173,13 +166,20 @@ function flyTo(viewer, camera) { */ export async function applyView( view, - { viewer, dataManager, run, signal, retryMs = FOLLOW_RETRY_MS }, + { + viewer, + dataManager, + run, + signal, + autoOpen = true, + retryMs = FOLLOW_RETRY_MS, + }, ) { const steps = []; - const act = async (name, args) => { + const act = async (name, args, options) => { let result = null; try { - result = await run(name, args); + result = await run(name, args, options); } catch (error) { result = { ok: false, error: error?.message || String(error) }; } @@ -198,6 +198,8 @@ export async function applyView( await act('set_layer_visibility', { layerId: layer.id, enabled: false }); } for (const layerId of view.layers) { + // The street-level action lights its source first, then the layer. + if (view.street_level && layerId === STREET_LEVEL_LAYER) continue; if (!dataManager.isEnabled(layerId)) await act('set_layer_visibility', { layerId, enabled: true }); } @@ -207,6 +209,29 @@ export async function applyView( await act('clear_annotations', {}); if (view.annotations.length) await act('annotate_map', { annotations: [...view.annotations] }); + if (view.street_level) { + // The photos frame the camera; when the action fails before flying, the + // view's own camera still applies. + // A posted view replays someone else's view, as a link does: the source + // it lights is not saved as the visitor's own choice. + const result = await act( + 'show_street_level', + streetLevelArgs(view.street_level, { autoOpen }), + { origin: 'programmatic' }, + ); + if (result?.ok !== true) { + // Overtaken (a click on the map, a newer request): hands off. + if (result?.cancelled || result?.superseded) return steps; + // An earlier view's photo must not stay over a place this view left. + // From the imagery stage on the action has settled the panel itself + // (a photo it could not load keeps its error). + if (result?.stage !== 'imagery') + dataManager.layers?.get?.(STREET_LEVEL_LAYER)?.module?.closeViewer?.(); + if (!result?.location) + steps.push({ step: 'camera', ok: await flyTo(viewer, view.camera) }); + } + return steps; + } if (!view.follow) { steps.push({ step: 'camera', ok: await flyTo(viewer, view.camera) }); return steps; @@ -243,6 +268,9 @@ export async function applyView( /** * Install embed mode when the page asks for it, and draw any annotations the * opening link carries. Returns a function that removes the message handler. + * `keepRendering({windowRef})` keeps the globe drawing in an inline panel + * whose host stops animation frames, and returns a function that stops it; + * the application scene gives it (`keepPanelRendering`). */ export function installViews({ shell, @@ -250,24 +278,123 @@ export function installViews({ dataManager, run, signal, + keepRendering = null, + terrain = null, location = globalThis.location, windowRef = globalThis.window, }) { const ready = Promise.resolve(shell.initialRestorePromise).catch(() => {}); - const linked = annotationsFromParams( - new URLSearchParams(String(location?.hash || '').replace(/^#/, '')), + const hashParams = new URLSearchParams( + String(location?.hash || '').replace(/^#/, ''), ); - if (linked.length) - void ready.then(() => { - if (!signal?.aborted) void run('annotate_map', { annotations: linked }); + // The link's own steps run first, one at a time, and posted views queue + // behind them; one failing step does not take the next with it. A passive + // link never flies over someone who took the camera: its steps are skipped + // when a newer link superseded it, when its flight never landed (the + // recipient dragged or searched), or after any navigation since the + // generation its restore flight owned. + const cameraLanded = (outcome) => outcome?.share?.camera === 'applied'; + const restoreGeneration = (outcome) => + Number.isInteger(outcome?.navigationToken) + ? outcome.navigationToken + : shell._navigationGeneration; + let generationAtRestore = null; + let startSuperseded = false; + let queue = ready.then((outcome) => { + generationAtRestore = restoreGeneration(outcome); + startSuperseded = + outcome?.status === 'superseded' || + (Boolean(outcome?.share) && !cameraLanded(outcome)); + }); + const navigatedSince = (generation) => + Number.isFinite(generation) && shell._navigationGeneration !== generation; + const linkStep = (work) => + queue.then(async () => { + if (signal?.aborted) return; + try { + await work(); + } catch { + /* reported by the action itself */ + } }); - if (!isEmbedded(location)) return () => {}; + const linked = annotationsFromParams(hashParams); + if (linked.length) + queue = linkStep(() => run('annotate_map', { annotations: linked })); + // A link's street-level photos open once it has restored. A billed source + // only arms, except for the panel page's own link to a result issued just + // now. A link that follows an entity keeps the camera on it. + const linkedStreetLevel = (params) => + followFromParams(params) ? null : streetLevelFromParams(params); + const openLinkedStreetLevel = async ( + streetLevel, + { generation, autoOpen = false }, + ) => { + if (navigatedSince(generation)) return; + // The link replays the sender's view: nothing it switches becomes the + // recipient's own preference. + const result = await run( + 'show_street_level', + streetLevelArgs(streetLevel, { autoOpen }), + { origin: 'programmatic' }, + ); + // A source without a working key changes nothing: say why, or the link + // looks broken. In a frame the host reads the result instead. + if (result?.stage === 'key' && !isEmbedded(location)) { + shell._showToast?.(keyToast(result)); + return; + } + // OPEN must be in view, but embed mode hides the rail that holds it: in + // a frame a posted view is the way to open a photo. + if (result?.armed === true && !isEmbedded(location)) { + // Opened for this link only: the recipient's saved layout stays theirs. + shell.setPanelCollapsed?.(STREET_LEVEL_PANEL_ID, false, { + explicit: true, + persist: false, + }); + // On a phone the panel sits in a tab sheet: open it so OPEN shows. + shell.revealPanel?.(STREET_LEVEL_PANEL_ID); + shell._showToast?.(armedToast()); + } + }; + const startStreetLevel = linkedStreetLevel(hashParams); + if (startStreetLevel) + queue = linkStep(() => + startSuperseded + ? undefined + : openLinkedStreetLevel(startStreetLevel, { + generation: generationAtRestore, + autoOpen: isFreshPanelResult(), + }), + ); + // A link pasted into the open tab: its photos follow once its restore + // settles, under the same rules. + const onNavigatedRestore = (event) => { + if (event?.detail?.status !== 'settled' || !cameraLanded(event.detail)) + return; + const streetLevel = linkedStreetLevel( + new URLSearchParams(String(location?.hash || '').replace(/^#/, '')), + ); + if (!streetLevel) return; + const generation = restoreGeneration(event.detail); + queue = linkStep(() => openLinkedStreetLevel(streetLevel, { generation })); + }; + windowRef?.addEventListener?.( + SHARE_NAVIGATION_RESTORED_EVENT, + onNavigatedRestore, + ); + const stopNavigatedRestores = () => + windowRef?.removeEventListener?.( + SHARE_NAVIGATION_RESTORED_EVENT, + onNavigatedRestore, + ); + if (!isEmbedded(location)) return stopNavigatedRestores; windowRef.document.body.classList.add('ui-embed'); shell.setCleanView?.(true); - const stopRendering = isEmbeddedInline() - ? keepPanelRendering(viewer, { windowRef }) - : () => {}; + const stopRendering = + isEmbeddedInline() && keepRendering + ? keepRendering({ windowRef }) + : () => {}; // A framing page talks to the app across frames; an inline panel shares // the page with it and talks through the page's own window. const peer = isEmbeddedInline() ? windowRef : windowRef.parent; @@ -278,7 +405,6 @@ export function installViews({ peer.postMessage(message, origin); }; // Views apply one at a time, in the order they arrive. - let queue = ready; const onMessage = (event) => { if (event.source !== peer || event.data?.type !== EMBED_VIEW_MESSAGE) return; @@ -302,19 +428,82 @@ export function installViews({ ); return; } - queue = queue.then(async () => { - if (signal?.aborted) return; - const steps = await applyView(view, { viewer, dataManager, run, signal }); - post( - { - type: EMBED_APPLIED_MESSAGE, - id, - ok: steps.every((step) => step.ok), - steps, - }, - replyOrigin, + // A panel's host can hand back old results on a remount: only one issued + // just now may open a billed photo. A framing page's view is its own. + const autoOpen = !isEmbeddedInline() || event.data.fresh === true; + // Photos asked for without a point open where the camera looks, measured + // from the ground under it, as show_in_gods_eye_view places them. + const asked = event.data.view?.street_level; + const unplaced = + asked && + typeof asked === 'object' && + asked.lat == null && + asked.lon == null; + queue = queue + .then(async () => { + if (signal?.aborted) return; + if (unplaced && view.street_level) { + // A terrain service that does not answer soon leaves the view's + // own estimate. + const wait = AbortSignal.timeout(TERRAIN_WAIT_MS); + const owner = watchCameraOwner(viewer, shell); + const point = await groundedLookAt( + view.camera, + terrain, + signal ? AbortSignal.any([signal, wait]) : wait, + ) + .catch(() => null) + .finally(() => owner.stop()); + if (signal?.aborted) return; + // Whoever takes the camera while the terrain answers (a drag, a + // search, the assistant) keeps it: the view stands down. + if (owner.taken()) { + post( + { + type: EMBED_APPLIED_MESSAGE, + id, + ok: false, + steps: [{ step: 'street_level', ok: false, superseded: true }], + }, + replyOrigin, + ); + return; + } + if (point) + view = createView({ + ...event.data.view, + street_level: { ...asked, ...point }, + }); + } + const steps = await applyView(view, { + viewer, + dataManager, + run, + signal, + autoOpen, + }); + post( + { + type: EMBED_APPLIED_MESSAGE, + id, + ok: steps.every((step) => step.ok), + steps, + }, + replyOrigin, + ); + }) + // A view that fails is answered, and the views behind it still apply. + .catch((error) => + post( + { + type: EMBED_APPLIED_MESSAGE, + id, + ok: false, + error: error?.message || String(error), + }, + replyOrigin, + ), ); - }); }; windowRef.addEventListener('message', onMessage); void ready.then(() => { @@ -322,6 +511,7 @@ export function installViews({ }); return () => { stopRendering(); + stopNavigatedRestores(); windowRef.removeEventListener('message', onMessage); }; } diff --git a/src/app/embed.test.mjs b/src/app/embed.test.mjs index 5fa9493426..1889c906ab 100644 --- a/src/app/embed.test.mjs +++ b/src/app/embed.test.mjs @@ -1,18 +1,18 @@ +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; import assert from 'node:assert/strict'; import test from 'node:test'; import { applyView, installViews, isEmbedded, - keepPanelRendering, panelAwareVisibility, } from './embed.js'; import { LayerLifecycle } from '../data/lifecycle.js'; -import { createView } from '../view/index.js'; +import { createView, viewToParams } from '../view/index.js'; const fakeViewer = () => { const flights = []; - return { + return bindFakeCesiumCamera({ flights, camera: { flyTo(options) { @@ -20,7 +20,7 @@ const fakeViewer = () => { options.complete(); }, }, - }; + }); }; const fakeLayers = (enabled) => ({ getAll: () => @@ -32,14 +32,16 @@ const fakeLayers = (enabled) => ({ }); const recorder = (answers = {}) => { const calls = []; - const run = async (name, args) => { + const options = []; + const run = async (name, args, runOptions) => { calls.push([name, args]); + options.push([name, runOptions]); const answer = answers[name]; return typeof answer === 'function' ? answer(calls) : (answer ?? { ok: true }); }; - return { calls, run }; + return { calls, run, options }; }; test('embed mode is opt-in by query parameter', () => { @@ -83,6 +85,19 @@ test('a view is applied through the app actions in order', async () => { assert.ok(steps.some((step) => step.step === 'camera')); }); +test("a view's street-level step replays the sender's view: nothing it switches is the visitor's choice", async () => { + const { options, run } = recorder(); + await applyView( + createView({ + camera: { lat: 48.86, lon: 2.29 }, + street_level: { provider: 'panoramax', lat: 48.8584, lon: 2.2945 }, + }), + { viewer: fakeViewer(), dataManager: fakeLayers(new Set()), run }, + ); + const [, runOptions] = options.find(([name]) => name === 'show_street_level'); + assert.equal(runOptions?.origin, 'programmatic'); +}); + test('a followed entity is retried until its layer has it', async () => { let tries = 0; const { run } = recorder({ @@ -102,6 +117,65 @@ test('a followed entity is retried until its layer has it', async () => { assert.deepEqual(steps.at(-1), { step: 'follow', ok: true }); }); +test('a posted view without a photo point opens its photos where the camera looks over the ground', async () => { + const parent = { postMessage() {} }; + const windowRef = new EventTarget(); + windowRef.parent = parent; + windowRef.document = { body: { classList: new Set() } }; + windowRef.document.body.classList.add = Set.prototype.add; + const shell = { initialRestorePromise: Promise.resolve(), setCleanView() {} }; + const { calls, run } = recorder(); + const asked = []; + // Denver: the ground is 1,590 m above the ellipsoid under a camera at 1,909 m. + const terrain = { + getHeights: async (points) => { + asked.push(points); + return points.map(() => ({ ellipsoid: 1590 })); + }, + }; + const remove = installViews({ + shell, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + terrain, + location: { search: '?embed=1', hash: '' }, + windowRef, + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + const event = new Event('message'); + Object.assign(event, { + source: parent, + origin: 'https://host.example', + data: { + type: 'gev:view', + id: 1, + view: { + camera: { + lat: 39.74, + lon: -104.99, + altitude_m: 1909, + pitch_deg: -30, + heading_deg: 0, + }, + street_level: { provider: 'mapillary' }, + }, + }, + }); + windowRef.dispatchEvent(event); + await new Promise((resolve) => setTimeout(resolve, 10)); + remove(); + const [, args] = calls.find(([name]) => name === 'show_street_level'); + // 319 m above the ground at -30° looks ~550 m ahead, not the ~3.3 km the + // ellipsoid altitude would give. + assert.deepEqual(asked, [[{ lat: 39.74, lon: -104.99 }]]); + assert.ok( + args.latitude > 39.744 && args.latitude < 39.746, + String(args.latitude), + ); + assert.equal(args.longitude, -104.99); +}); + test('an embedded page takes views only from its parent and answers it', async () => { const posted = []; const targets = []; @@ -186,6 +260,59 @@ test('an embedded page takes views only from its parent and answers it', async ( remove(); }); +test('an inline panel opens a billed photo only for a view whose result is fresh', async () => { + const windowRef = new EventTarget(); + windowRef.parent = windowRef; + windowRef.postMessage = () => {}; + windowRef.document = { body: { classList: new Set() } }; + windowRef.document.body.classList.add = Set.prototype.add; + Object.assign(windowRef, { + requestAnimationFrame: () => 1, + cancelAnimationFrame() {}, + setInterval: () => 1, + clearInterval() {}, + }); + const { calls, run } = recorder(); + globalThis.GEV_EMBED_INLINE = true; + try { + const remove = installViews({ + shell: { initialRestorePromise: Promise.resolve() }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { search: '', hash: '' }, + windowRef, + }); + const view = { + camera: { lat: 48.8584, lon: 2.2945 }, + map: 'photoreal', + street_level: { provider: 'google', lat: 48.8584, lon: 2.2945 }, + }; + for (const [id, fresh] of [ + [1, true], + [2, false], + [3, undefined], + ]) { + const event = new Event('message'); + Object.assign(event, { + source: windowRef, + data: { type: 'gev:view', id, view, fresh }, + }); + windowRef.dispatchEvent(event); + } + await new Promise((resolve) => setTimeout(resolve, 20)); + assert.deepEqual( + calls + .filter(([name]) => name === 'show_street_level') + .map(([, args]) => args.autoOpen ?? true), + [true, false, false], + ); + remove(); + } finally { + delete globalThis.GEV_EMBED_INLINE; + } +}); + test('an app loaded inline into a panel page talks through its own window', async () => { const posted = []; const windowRef = new EventTarget(); @@ -202,6 +329,7 @@ test('an app loaded inline into a panel page talks through its own window', asyn globalThis.GEV_EMBED_INLINE = true; try { assert.equal(isEmbedded({ search: '' }), true); + const kept = []; const remove = installViews({ shell: { initialRestorePromise: Promise.resolve() }, viewer: fakeViewer(), @@ -209,7 +337,13 @@ test('an app loaded inline into a panel page talks through its own window', asyn run: recorder().run, location: { search: '', hash: '' }, windowRef, + // The scene's panel rendering, kept on while the views are installed. + keepRendering: (options) => { + kept.push(options.windowRef === windowRef); + return () => kept.push('stopped'); + }, }); + assert.deepEqual(kept, [true]); await new Promise((resolve) => setTimeout(resolve, 0)); assert.deepEqual(posted, [{ type: 'gev:ready' }]); const event = new Event('message'); @@ -222,6 +356,7 @@ test('an app loaded inline into a panel page talks through its own window', asyn assert.equal(posted[1].id, 7); assert.equal(posted[1].ok, true); remove(); + assert.deepEqual(kept, [true, 'stopped']); } finally { delete globalThis.GEV_EMBED_INLINE; } @@ -300,73 +435,6 @@ test('annotations in a link are drawn after it restores, embedded or not', async ]); }); -test('a panel keeps drawing from a timer while animation frames stop', () => { - let clock = 0; - let tick = null; - let frame = null; - const windowRef = { - requestAnimationFrame: (fn) => ((frame = fn), 1), - cancelAnimationFrame: () => (frame = null), - setInterval: (fn) => ((tick = fn), 1), - clearInterval: () => (tick = null), - }; - const drawn = []; - const viewer = { - resize: () => drawn.push('resize'), - render: () => drawn.push('render'), - }; - const stop = keepPanelRendering(viewer, { windowRef, now: () => clock }); - // Frames arrive: the render loop draws, so the timer does nothing. - clock = 100; - frame(); - tick(); - assert.deepEqual(drawn, []); - // Frames stop, as in a panel its host reports hidden: the timer draws. - clock = 400; - tick(); - assert.deepEqual(drawn, ['resize', 'render']); - stop(); - assert.equal(tick, null); - assert.equal(frame, null); -}); - -test('a panel reports a render error in full and stops drawing', () => { - let listener = null; - let tick = null; - const windowRef = { - requestAnimationFrame: () => 1, - cancelAnimationFrame() {}, - setInterval: (fn) => ((tick = fn), 1), - clearInterval() {}, - }; - const drawn = []; - const viewer = { - resize() {}, - render: () => drawn.push('render'), - scene: { - renderError: { - addEventListener: (fn) => ((listener = fn), () => (listener = null)), - }, - }, - }; - const logged = []; - const original = console.error; - console.error = (...args) => logged.push(args.join(' ')); - try { - let clock = 0; - const stop = keepPanelRendering(viewer, { windowRef, now: () => clock }); - listener(viewer.scene, { name: 'RuntimeError', message: 'worker failed' }); - assert.match(logged[0], /render error: .*"message":"worker failed"/); - clock = 1000; - tick(); - assert.deepEqual(drawn, []); - stop(); - assert.equal(listener, null); - } finally { - console.error = original; - } -}); - test('a followed aircraft owns the camera, and cockpit view is entered after it', async () => { const viewer = fakeViewer(); const { calls, run } = recorder(); @@ -393,3 +461,774 @@ test('a followed aircraft owns the camera, and cockpit view is entered after it' /no cockpit view/, ); }); + +test('a view with street-level photos lets the action fly and open them', async () => { + const viewer = fakeViewer(); + const { calls, run } = recorder(); + const view = createView({ + camera: { lat: 38.5799, lon: -121.4937, altitude_m: 500 }, + street_level: { provider: 'google' }, + }); + const steps = await applyView(view, { + viewer, + dataManager: fakeLayers(new Set()), + run, + }); + assert.deepEqual( + calls.map(([name]) => name), + [ + 'set_map_stack', + 'stop_tracking', + 'clear_annotations', + 'show_street_level', + ], + ); + assert.deepEqual(calls.at(-1)[1], { + latitude: 38.5799, + longitude: -121.4937, + provider: 'google', + fly: true, + }); + assert.equal(viewer.flights.length, 0, 'the action frames the camera'); + assert.ok(steps.every((step) => step.ok)); + assert.equal(steps.at(-1).step, 'show_street_level'); +}); + +test('a link to street-level photos opens them after it restores', async () => { + const { calls, run } = recorder(); + const toasts = []; + const panels = []; + installViews({ + shell: { + initialRestorePromise: Promise.resolve(), + _showToast: (text) => toasts.push(text), + setPanelCollapsed: (...args) => panels.push(args), + }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: '', + hash: '#v=2&lat=1&lon=2&sl=mapillary,38.58000,-121.49000', + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, [ + [ + 'show_street_level', + { + latitude: 38.58, + longitude: -121.49, + provider: 'mapillary', + fly: true, + autoOpen: false, + }, + ], + ]); + assert.deepEqual( + [toasts, panels], + [[], []], + 'an opened photo needs no toast or panel nudge', + ); + // A failure (no key) is not an armed state either: it says why instead. + const failed = recorder({ + show_street_level: () => ({ + ok: false, + stage: 'key', + error: 'needs its key', + }), + }); + installViews({ + shell: { + initialRestorePromise: Promise.resolve(), + _showToast: (text) => toasts.push(text), + setPanelCollapsed: (...args) => panels.push(args), + }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run: failed.run, + location: { + search: '', + hash: '#v=2&lat=1&lon=2&sl=google,1.00000,2.00000', + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual( + [toasts, panels], + [ + [ + "Street Level cannot open this link's street-level photo without a working key", + ], + [], + ], + 'it says why, and nothing to press opens', + ); +}); + +test('a link that follows an entity keeps the camera: its photos are not opened', async () => { + const { calls, run } = recorder(); + const params = viewToParams( + createView({ + camera: { lat: 1, lon: 2 }, + follow: { kind: 'satellite', id: '25544' }, + }), + ); + params.set('sl', 'mapillary,1.00000,2.00000'); + installViews({ + shell: { initialRestorePromise: Promise.resolve() }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { search: '', hash: `#${params}` }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, []); +}); + +test('a failing link step does not take the next one with it', async () => { + const calls = []; + const run = async (name, args) => { + calls.push(name); + if (name === 'annotate_map') throw new Error('marks failed'); + return { ok: true, armed: false, ...args }; + }; + const an = encodeURIComponent( + JSON.stringify([{ type: 'pin', target: 'Austin' }]), + ); + installViews({ + shell: { initialRestorePromise: Promise.resolve() }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: '', + hash: `#v=2&lat=1&lon=2&an=${an}&sl=mapillary,1.00000,2.00000`, + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, ['annotate_map', 'show_street_level']); +}); + +test('a link whose source has no working key says why instead of doing nothing; a frame stays quiet', async () => { + for (const embed of [false, true]) { + const toasts = []; + const { calls, run } = recorder({ + show_street_level: () => ({ + ok: false, + stage: 'key', + provider: 'google', + providerName: 'Google Street View', + error: 'Google Street View needs its key', + }), + }); + const windowRef = new EventTarget(); + if (embed) { + windowRef.document = { body: { classList: { add() {} } } }; + windowRef.parent = { postMessage() {} }; + } + installViews({ + shell: { + initialRestorePromise: Promise.resolve(), + setCleanView() {}, + _showToast: (text) => toasts.push(text), + setPanelCollapsed() { + throw new Error('nothing to arm'); + }, + }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: embed ? '?embed=1' : '', + hash: '#v=2&lat=1&lon=2&map=photoreal&sl=google,38.57986,-121.49372', + }, + windowRef, + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.equal(calls[0][0], 'show_street_level'); + assert.deepEqual( + toasts, + embed + ? [] + : [ + "Google Street View cannot open this link's street-level photo without a working key", + ], + ); + } +}); + +test('a plain link never auto-loads a billed photo: it arms the panel and says so; an embedded view opens', async () => { + const toasts = []; + const panels = []; + const revealed = []; + const { calls, run } = recorder({ + show_street_level: () => ({ ok: true, armed: true }), + }); + installViews({ + shell: { + initialRestorePromise: Promise.resolve(), + _showToast: (text) => toasts.push(text), + setPanelCollapsed: (id, collapsed, options) => + panels.push([id, collapsed, options]), + revealPanel: (id) => revealed.push(id), + }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: '', + hash: '#v=2&lat=1&lon=2&map=photoreal&sl=google,38.57986,-121.49372', + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.equal(calls[0][1].autoOpen, false); + assert.deepEqual(toasts, [ + 'Street View is ready: press OPEN GOOGLE STREET VIEW to load it', + ]); + assert.deepEqual( + panels, + [['street-level-panel', false, { explicit: true, persist: false }]], + "the panel opens so OPEN is in view, without saving the layout as the recipient's", + ); + assert.deepEqual(revealed, ['street-level-panel'], 'its phone sheet too'); + // Adding ?embed=1 to a published link does not lift the gate: the page is + // still a plain top-level load. + const framedToasts = []; + const framedPanels = []; + const framed = recorder({ + show_street_level: () => ({ ok: true, armed: true }), + }); + const windowRef = new EventTarget(); + windowRef.document = { body: { classList: { add() {} } } }; + windowRef.parent = { postMessage() {} }; + installViews({ + shell: { + initialRestorePromise: Promise.resolve(), + setCleanView() {}, + _showToast: (text) => framedToasts.push(text), + setPanelCollapsed: (...args) => framedPanels.push(args), + }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run: framed.run, + location: { + search: '?embed=1', + hash: '#v=2&lat=1&lon=2&map=photoreal&sl=google,38.57986,-121.49372', + }, + windowRef, + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.equal(framed.calls[0][1].autoOpen, false); + // In a frame the rail that holds OPEN is hidden: no nudge, no toast. + assert.deepEqual([framedToasts, framedPanels], [[], []]); + // Only the panel page's own link for a result issued just now is the + // client's request: a host that mounts the panel again hands back an old + // result, and that one only arms, like any link. + globalThis.GEV_EMBED_INLINE = true; + try { + for (const fresh of [true, false]) { + globalThis.GEV_EMBED_FRESH = fresh; + const inline = recorder({ show_street_level: () => ({ ok: true }) }); + const inlineWindow = new EventTarget(); + inlineWindow.document = { body: { classList: { add() {} } } }; + inlineWindow.postMessage = () => {}; + // The inline panel keeps rendering from a timer; give it inert clocks. + Object.assign(inlineWindow, { + requestAnimationFrame: () => 1, + cancelAnimationFrame() {}, + setTimeout: () => 1, + clearTimeout() {}, + setInterval: () => 1, + clearInterval() {}, + }); + const stop = installViews({ + shell: { initialRestorePromise: Promise.resolve(), setCleanView() {} }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run: inline.run, + location: { + search: '', + hash: '#v=2&lat=1&lon=2&map=photoreal&sl=google,38.57986,-121.49372', + }, + windowRef: inlineWindow, + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + if (fresh) assert.equal('autoOpen' in inline.calls[0][1], false); + else assert.equal(inline.calls[0][1].autoOpen, false, 'a remount arms'); + stop(); + } + } finally { + delete globalThis.GEV_EMBED_INLINE; + delete globalThis.GEV_EMBED_FRESH; + } + // applyView (a posted view) opens too. + const posted = recorder(); + await applyView( + createView({ + camera: { lat: 1, lon: 2 }, + street_level: { provider: 'google' }, + }), + { + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run: posted.run, + }, + ); + assert.equal('autoOpen' in posted.calls.at(-1)[1], false); +}); + +test('a view whose photos fail before any flight still gets its camera', async () => { + const viewer = fakeViewer(); + const { calls, run } = recorder({ + show_street_level: () => ({ + ok: false, + stage: 'key', + error: 'needs its key', + }), + }); + const view = createView({ + camera: { lat: 1, lon: 2, altitude_m: 500 }, + street_level: { provider: 'google' }, + }); + const steps = await applyView(view, { + viewer, + dataManager: fakeLayers(new Set()), + run, + }); + assert.equal(viewer.flights.length, 1, 'the view flies itself'); + assert.deepEqual( + steps.map((step) => [step.step, step.ok]), + [ + ['set_map_stack', true], + ['stop_tracking', true], + ['clear_annotations', true], + ['show_street_level', false], + ['camera', true], + ], + ); + assert.ok(calls.some(([name]) => name === 'show_street_level')); + // A flight that happened (the action reports where) is not repeated. + const flown = fakeViewer(); + const { run: flownRun } = recorder({ + show_street_level: () => ({ + ok: false, + stage: 'imagery', + location: 'Somewhere', + error: 'no imagery', + }), + }); + await applyView(view, { + viewer: flown, + dataManager: fakeLayers(new Set()), + run: flownRun, + }); + assert.equal(flown.flights.length, 0); +}); + +test('a link runs its marks and photos in order, and posted views wait behind them', async () => { + const log = []; + let releaseStreetLevel = null; + let releaseMarks = null; + const run = async (name, args) => { + log.push(`start:${name}`); + if (name === 'annotate_map') + await new Promise((resolve) => { + releaseMarks = resolve; + }); + if (name === 'show_street_level') + await new Promise((resolve) => { + releaseStreetLevel = resolve; + }); + log.push(`end:${name}`); + return { + ok: true, + ...(name === 'show_street_level' ? { location: 'x' } : {}), + }; + }; + const windowRef = new EventTarget(); + windowRef.document = { body: { classList: { add() {} } } }; + // A framing page: answers go to it, not to the app's own window. + windowRef.parent = { + postMessage: (message) => log.push(`post:${message.type}`), + }; + const an = encodeURIComponent( + JSON.stringify([{ type: 'pin', target: 'Austin' }]), + ); + installViews({ + shell: { initialRestorePromise: Promise.resolve(), setCleanView() {} }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: '?embed=1', + hash: `#v=2&lat=1&lon=2&an=${an}&sl=mapillary,1.00000,2.00000`, + }, + windowRef, + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + // A view arrives while the link's photos are still opening. + windowRef.dispatchEvent( + Object.assign(new Event('message'), { + source: windowRef.parent, + origin: 'null', + data: { + type: 'gev:view', + id: 'v1', + view: { camera: { lat: 3, lon: 4 } }, + }, + }), + ); + await new Promise((resolve) => setTimeout(resolve, 0)); + const actions = () => log.filter((entry) => !entry.startsWith('post:')); + assert.deepEqual( + actions(), + ['start:annotate_map'], + 'the photos wait for the marks', + ); + releaseMarks(); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(actions().slice(0, 3), [ + 'start:annotate_map', + 'end:annotate_map', + 'start:show_street_level', + ]); + assert.ok( + !log.includes('start:stop_tracking'), + 'the posted view waits for the link', + ); + releaseStreetLevel(); + for ( + let tick = 0; + tick < 20 && !log.includes('post:gev:view-applied'); + tick++ + ) + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.equal( + log.indexOf('end:show_street_level') < log.indexOf('start:stop_tracking'), + true, + ); + assert.ok(log.includes('post:gev:view-applied'), log.join(' ')); +}); + +test('an aborted install never runs the link photos', async () => { + const { calls, run } = recorder(); + const controller = new AbortController(); + controller.abort(); + installViews({ + shell: { initialRestorePromise: Promise.resolve() }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + signal: controller.signal, + location: { + search: '', + hash: '#v=2&lat=1&lon=2&sl=google,1.00000,2.00000', + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, []); +}); + +test('a passive link stands down when someone navigated while it waited behind its marks', async () => { + const calls = []; + let releaseMarks = null; + const shell = { + initialRestorePromise: Promise.resolve(), + _navigationGeneration: 7, + }; + const run = async (name) => { + calls.push(name); + if (name === 'annotate_map') + await new Promise((resolve) => { + releaseMarks = resolve; + }); + return { ok: true }; + }; + const an = encodeURIComponent( + JSON.stringify([{ type: 'pin', target: 'Austin' }]), + ); + installViews({ + shell, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: '', + hash: `#v=2&lat=1&lon=2&an=${an}&sl=mapillary,1.00000,2.00000`, + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, ['annotate_map']); + shell._navigationGeneration = 8; // the recipient searched, or the assistant flew + releaseMarks(); + await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual( + calls, + ['annotate_map'], + 'the link did not fly over the newer navigation', + ); + + // Unchanged navigation: the photos open as before. + const quiet = []; + installViews({ + shell: { + initialRestorePromise: Promise.resolve(), + _navigationGeneration: 3, + }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run: async (name) => { + quiet.push(name); + return { ok: true }; + }, + location: { + search: '', + hash: `#v=2&lat=1&lon=2&an=${an}&sl=mapillary,1.00000,2.00000`, + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(quiet, ['annotate_map', 'show_street_level']); +}); + +test('a link replays the sender’s view: its street-level step never writes the recipient’s preferences', async () => { + const { calls, run, options } = recorder(); + installViews({ + shell: { initialRestorePromise: Promise.resolve() }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: '', + hash: '#v=2&lat=1&lon=2&sl=mapillary,38.58000,-121.49000', + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.equal(calls.length, 1); + assert.deepEqual(options, [ + ['show_street_level', { origin: 'programmatic' }], + ]); +}); + +test('a start link whose restore a newer link superseded opens nothing', async () => { + const { calls, run } = recorder(); + installViews({ + shell: { + initialRestorePromise: Promise.resolve({ status: 'superseded' }), + _navigationGeneration: 4, + }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: '', + hash: '#v=2&lat=1&lon=2&sl=mapillary,38.58000,-121.49000', + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, [], 'start link A does not pull the camera from B'); +}); + +test('a start link whose restore flight the recipient interrupted leaves the camera with them', async () => { + for (const [camera, expected] of [ + ['cancelled', 0], + ['skipped', 0], + ['applied', 1], + ]) { + const { calls, run } = recorder(); + installViews({ + shell: { + initialRestorePromise: Promise.resolve({ + status: 'settled', + share: { camera }, + }), + _navigationGeneration: 4, + }, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location: { + search: '', + hash: '#v=2&lat=1&lon=2&sl=mapillary,38.58000,-121.49000', + }, + windowRef: new EventTarget(), + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.equal(calls.length, expected, camera); + } +}); + +test('a link pasted into the open tab opens or arms its photos once its restore settles', async () => { + const { calls, run, options } = recorder(); + const windowRef = new EventTarget(); + const location = { search: '', hash: '#v=2&lat=1&lon=2' }; + const shell = { + initialRestorePromise: Promise.resolve(), + _navigationGeneration: 1, + }; + const remove = installViews({ + shell, + viewer: fakeViewer(), + dataManager: fakeLayers(new Set()), + run, + location, + windowRef, + }); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, [], 'the start link has no photos'); + const settled = (status, camera = 'applied') => + windowRef.dispatchEvent( + Object.assign(new Event('gev:share-navigation-restore-settled'), { + detail: { status, share: { camera } }, + }), + ); + location.hash = '#v=2&lat=3&lon=4&sl=mapillary,48.88740,2.34950'; + shell._navigationGeneration = 2; // the restore's own flight + settled('failed'); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, [], 'a failed restore opens nothing'); + // The recipient dragged or searched during the restore flight: the camera + // is theirs, and the link does not pull it back. + shell._navigationGeneration = 3; + for (const camera of ['cancelled', 'superseded']) { + settled('settled', camera); + await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual( + calls, + [], + `an interrupted restore (${camera}) opens nothing`, + ); + } + settled('settled'); + await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.deepEqual(calls, [ + [ + 'show_street_level', + { + latitude: 48.8874, + longitude: 2.3495, + provider: 'mapillary', + fly: true, + autoOpen: false, + }, + ], + ]); + assert.deepEqual(options.at(-1), [ + 'show_street_level', + { origin: 'programmatic' }, + ]); + remove(); + location.hash = '#v=2&lat=5&lon=6&sl=mapillary,1.00000,2.00000'; + settled('settled'); + await new Promise((resolve) => setTimeout(resolve, 0)); + assert.equal(calls.length, 1, 'removed with the install'); +}); + +test('a view whose photo step the user overtook leaves their photo and camera alone', async () => { + // Photo B, opened by a click while the posted view looked up its photo. + const street = { open: false, imageId: null }; + const dataManager = { + ...fakeLayers(new Set()), + layers: new Map([ + [ + 'street-level', + { + module: { + closeViewer: () => + Object.assign(street, { open: false, imageId: null }), + }, + }, + ], + ]), + }; + const { run } = recorder({ + show_street_level: () => { + Object.assign(street, { open: true, imageId: 'b' }); + return { + ok: false, + stage: 'imagery', + cancelled: true, + superseded: true, + error: 'The camera moved on before the photo opened', + }; + }, + }); + const view = createView({ + camera: { lat: 1, lon: 2, altitude_m: 500 }, + street_level: { provider: 'mapillary' }, + }); + const viewer = fakeViewer(); + const steps = await applyView(view, { viewer, dataManager, run }); + assert.deepEqual(street, { open: true, imageId: 'b' }, 'photo B stays'); + assert.equal(viewer.flights.length, 0, 'the camera stays with the user'); + assert.equal(steps.at(-1).ok, false, 'reported as not applied'); +}); + +test('a view whose photo was found but could not load keeps its error in view', async () => { + const closed = []; + const dataManager = { + ...fakeLayers(new Set()), + layers: new Map([ + ['street-level', { module: { closeViewer: () => closed.push(true) } }], + ]), + }; + const { run } = recorder({ + show_street_level: () => ({ + ok: false, + stage: 'imagery', + imageryError: true, + location: '1.00000, 2.00000', + error: 'Image could not be opened', + }), + }); + const view = createView({ + camera: { lat: 1, lon: 2, altitude_m: 500 }, + street_level: { provider: 'mapillary' }, + }); + await applyView(view, { viewer: fakeViewer(), dataManager, run }); + assert.equal(closed.length, 0, 'the viewer keeps the new photo’s error'); +}); + +test('a view whose photos fail closes the photo an earlier view opened', async () => { + const closed = []; + const dataManager = { + ...fakeLayers(new Set()), + layers: new Map([ + ['street-level', { module: { closeViewer: () => closed.push(true) } }], + ]), + }; + const { run } = recorder({ + show_street_level: () => ({ + ok: false, + stage: 'key', + error: 'needs its key', + }), + }); + const view = createView({ + camera: { lat: 1, lon: 2, altitude_m: 500 }, + street_level: { provider: 'google' }, + }); + const viewer = fakeViewer(); + await applyView(view, { viewer, dataManager, run }); + assert.equal(closed.length, 1, 'closed before the view flies away'); + assert.equal(viewer.flights.length, 1); + const opened = recorder({ show_street_level: () => ({ ok: true }) }); + await applyView(view, { viewer, dataManager, run: opened.run }); + assert.equal(closed.length, 1, 'an opened photo stays'); +}); diff --git a/src/app/embedTerrainTakeover.test.mjs b/src/app/embedTerrainTakeover.test.mjs new file mode 100644 index 0000000000..60ead319d1 --- /dev/null +++ b/src/app/embedTerrainTakeover.test.mjs @@ -0,0 +1,118 @@ +import '../testSupport/registerDom.mjs'; +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { installViews } from './embed.js'; +import { createGevActionRunner } from '../voice/gevActions.js'; +import { createAnnotationEngine } from '../annotations/annotationEngine.js'; +import { fakeCesiumViewer } from '../testSupport/streetLevelFakes.mjs'; + +// A camera taken while a posted view waits on terrain stays with whoever took +// it: the stale view stands down whole, so it neither stops a newer follow nor +// frames its own marks. Offline: real installViews, action runner and +// annotation engine; the viewer, renderer, flights data and terrain are fixtures. +globalThis.fetch = async () => { throw new Error('Unexpected network request in offline reproduction'); }; +globalThis.requestAnimationFrame = () => 1; +globalThis.cancelAnimationFrame = () => {}; +const tick = () => new Promise(resolve => setTimeout(resolve, 0)); +function deferred() { + let resolve; + const promise = new Promise(done => { resolve = done; }); + return { promise, resolve }; +} + +async function scenario(t, effect) { + document.body.className = ''; + const entered = deferred(); + const terrain = deferred(); + const viewer = fakeCesiumViewer(); + viewer.clock = { onTick: new Cesium.Event() }; + viewer.canvas = viewer.scene.canvas; + // A real perspective frustum looking down at 0,0; the old view's mark + // at 48N,2E is outside it. No override of the engine's visibility logic. + Object.assign(viewer.camera, { + position: Cesium.Cartesian3.fromDegrees(0, 0, 1000), + direction: new Cesium.Cartesian3(-1, 0, 0), + up: new Cesium.Cartesian3(0, 0, 1), + heading: 0, + frustum: new Cesium.PerspectiveFrustum({ fov: Math.PI / 3, aspectRatio: 1, near: 1, far: 20000000 }), + }); + const entity = { id: 'fixture-aircraft' }; + const aircraft = { icao24: 'fixture', callsign: 'Fixture', latitude: 0, longitude: 0 }; + let stopCalls = 0; + const flights = { + findByQuery: () => aircraft, + trackById: () => { viewer.trackedEntity = entity; return true; }, + getTrackedInfo: () => viewer.trackedEntity ? aircraft : null, + stopTracking: () => { stopCalls++; viewer.trackedEntity = undefined; return true; }, + }; + const dataManager = { + layers: new Map([['flights', { module: flights }]]), + getAll: () => [{ id: 'flights', enabled: true }], + isEnabled: id => id === 'flights', + setLayerParams: () => true, + }; + const shell = { + _navigationGeneration: 1, + initialRestorePromise: Promise.resolve(), + setCleanView() {}, + runImmediateNavigation(_noun, navigate) { this._navigationGeneration++; return navigate(); }, + }; + const annotations = createAnnotationEngine({ viewer, + renderer: { add() {}, update() {}, remove() {}, sync() {}, destroy() {} }, + }); + const runner = createGevActionRunner({ viewer, dataManager, styleManager: shell, annotations }); + const calls = []; + const run = async (name, args, options) => { + calls.push(name); + return runner(name, args, options); + }; + const replies = []; + const peer = { postMessage: message => replies.push(message) }; + const windowRef = new EventTarget(); + windowRef.parent = peer; + windowRef.document = document; + const remove = installViews({ shell, viewer, dataManager, run, windowRef, + location: { search: '?embed=1', hash: '' }, + terrain: { getHeights: () => { entered.resolve(); return terrain.promise; } }, + }); + t.after(() => { remove(); runner.dispose(); annotations.destroy(); document.body.className = ''; }); + await tick(); + const event = new Event('message'); + Object.assign(event, { source: peer, origin: 'https://host.example', data: { + type: 'gev:view', id: 1, view: { + camera: { lat: 48, lon: 2, altitude_m: 1000, pitch_deg: -45 }, + layers: ['flights'], + street_level: { provider: 'mapillary' }, + annotations: effect === 'annotations' + ? [{ type: 'pin', latitude: 48, longitude: 2, label: 'Old view' }] : [], + }, + } }); + windowRef.dispatchEvent(event); + await entered.promise; + if (effect === 'follow') { + const follow = await runner('track_entity', { query: 'Fixture', layerId: 'flights' }); + assert.equal(follow.ok, true, 'new follow starts through the real runner'); + assert.equal(viewer.trackedEntity, entity); + } else { + viewer.canvas.dispatchEvent(new Event('pointerdown')); + } + terrain.resolve([{ ellipsoid: 200 }]); + for (let n = 0; n < 50 && !replies.some(reply => reply.id === 1); n++) await tick(); + const reply = replies.find(reply => reply.id === 1); + t.diagnostic(JSON.stringify({ effect, calls, stopCalls, followed: viewer.trackedEntity === entity, + annotationCount: annotations.count(), annotationFlights: viewer.flights.started, reply })); + assert.ok(reply, 'host receives completion'); + assert.equal(reply.ok, false, 'superseded view is acknowledged as not applied'); + assert.ok(!calls.includes('show_street_level'), 'superseded request never reaches photo handler'); + if (effect === 'follow') { + assert.equal(stopCalls, 0, 'stale view must not stop the newer follow'); + assert.equal(viewer.trackedEntity, entity, 'the new tracked entity stays selected'); + } else { + assert.equal(viewer.flights.started, 0, 'stale annotations must not fly the camera'); + } +} + +for (const effect of ['follow', 'annotations']) { + test(`a camera taken during the terrain wait keeps the user's ${effect}`, { timeout: 5000 }, t => scenario(t, effect)); +} diff --git a/src/app/globeInViewRecovery.js b/src/app/globeInViewRecovery.js new file mode 100644 index 0000000000..91c1c3062a --- /dev/null +++ b/src/app/globeInViewRecovery.js @@ -0,0 +1,181 @@ +/** + * @module app/globeInViewRecovery + * @description Turns the camera back to the planet when a move ends looking + * away from it, through the renderer's camera and frame ports. + */ +import { PI_OVER_TWO } from '../geo/vector.js'; +import { + FREE_LOOK_MAX_HEIGHT_METERS, + globeOutOfFrame, + isFreeGlobeCamera, +} from '../globeInView.js'; +import { canvasOf, findCamera, findFrame } from '../render/rendererOf.js'; + +/** Whether two vectors agree to `tolerance` in every component. */ +const within = (a, b, tolerance) => + Math.abs(a.x - b.x) <= tolerance && + Math.abs(a.y - b.y) <= tolerance && + Math.abs(a.z - b.z) <= tolerance; + +// How often a moving camera is sampled to see whether it has come to rest, how +// far a pose may drift between samples and still count as at rest, and how +// long after the camera last moved the check gives up if the camera never +// raises moveEnd. +const SETTLE_SAMPLE_MS = 250; +const SETTLE_POSITION_TOLERANCE_M = 1e-3; +const SETTLE_DIRECTION_TOLERANCE = 1e-9; +const SETTLE_GIVE_UP_MS = 5 * 60_000; + +/** + * Turn the camera back to the planet when a move ends above `minHeight` with + * no surface on screen (`globeOutOfFrame`: limb glow and slivers up to about + * one sample cell thick can count as none), and return the disposer. Views with + * more surface, such as an oblique orbital shot, are left as they are. This + * catches a saved or shared view that looked away, or any other move that ends + * looking away from the planet. + * Heading and position are kept. Following cameras, locked ones (a target's + * frame), a camera flight in progress, a pointer held down on the canvas + * (a drag held still), and any time `paused` + * returns true (an authored scene playing) are left alone; a check they defer + * runs once they end, however long they last. + * `keyholeRadius` + * returns the radius of the visible circle when a scope mask hides the rest of + * the frame (see `globeFrameShare`), or 0; it is read at every check. + * + * The camera's `moveEnd` alone is not enough: the default renderer compares + * the camera with the last frame's to the last rounding error, and at some of + * these poses the camera drifts by a rounding error every frame, so it never + * sees it stop. + * So each `moveStart` also starts a check of its own that samples the pose + * every 250 ms, with a tolerance for that drift, and once the pose has held + * for half a second after moving runs the same recovery. It keeps watching + * until the camera raises `moveEnd`, since under that drift it raises no new + * `moveStart` for a later move, and gives up five minutes after the camera + * last moved. + * `setTimeout` and `clearTimeout` can be injected for tests. + */ +export function installGlobeInViewRecovery( + viewer, + { + minHeight = FREE_LOOK_MAX_HEIGHT_METERS, + keyholeRadius = () => 0, + paused = () => false, + setTimeout: schedule = globalThis.setTimeout, + clearTimeout: unschedule = globalThis.clearTimeout, + } = {}, +) { + const camera = findCamera(viewer); + if (!camera) throw new TypeError('A viewer with a camera is required'); + + // A pointer held on the globe is a gesture in progress, even when it holds + // still for half a second: the check waits until every pointer pressed on + // it (each finger of a pinch) is released. A release the page never sees, + // outside the window, is taken as given when the window loses focus, the + // page is hidden, the canvas loses the pointer's capture, or the pointer + // moves with no button down. + const canvas = canvasOf(viewer); + const releaseTarget = canvas?.ownerDocument ?? canvas; + const releaseWindow = canvas?.ownerDocument?.defaultView; + const heldPointers = new Set(); + const onPointerDown = (event) => heldPointers.add(event?.pointerId); + const onPointerUp = (event) => heldPointers.delete(event?.pointerId); + const onPointerMove = (event) => { + if (event?.buttons === 0) heldPointers.delete(event.pointerId); + }; + const releaseAll = () => heldPointers.clear(); + const onVisibilityChange = () => { + if (canvas.ownerDocument.visibilityState === 'hidden') releaseAll(); + }; + const listeners = [ + [canvas, 'pointerdown', onPointerDown], + [canvas, 'lostpointercapture', onPointerUp], + [releaseTarget, 'pointerup', onPointerUp], + [releaseTarget, 'pointercancel', onPointerUp], + [releaseTarget, 'pointermove', onPointerMove], + [canvas?.ownerDocument, 'visibilitychange', onVisibilityChange], + [releaseWindow, 'blur', releaseAll], + ]; + for (const [target, type, listener] of listeners) + target?.addEventListener?.(type, listener); + + // Returns false while a flight, a paused scene or a held pointer defers the + // check, so the caller can try again once it ends. + const recover = () => { + if (!isFreeGlobeCamera(viewer)) return true; + if (camera.flying || paused() || heldPointers.size > 0) return false; + const pose = camera.pose(); + if ( + !(pose.height > minHeight) || + !globeOutOfFrame(pose, { keyholeRadius: keyholeRadius() }) + ) + return true; + camera.setView({ + orientation: { heading: pose.heading, pitch: -PI_OVER_TWO, roll: 0 }, + }); + findFrame(viewer)?.requestRender?.('globe-in-view'); + return true; + }; + + let lastPosition = null; + let lastDirection = null; + const remember = () => { + ({ position: lastPosition, direction: lastDirection } = camera.pose()); + }; + let settleTimer = null; + let settleElapsed = 0; + let restingSamples = 0; + let movedSinceCheck = false; + const stopSettling = () => { + if (settleTimer !== null) unschedule(settleTimer); + settleTimer = null; + }; + const sample = () => { + settleTimer = null; + settleElapsed += SETTLE_SAMPLE_MS; + const now = camera.pose(); + const atRest = + within(now.position, lastPosition, SETTLE_POSITION_TOLERANCE_M) && + within(now.direction, lastDirection, SETTLE_DIRECTION_TOLERANCE); + restingSamples = atRest ? restingSamples + 1 : 0; + if (!atRest) { + movedSinceCheck = true; + settleElapsed = 0; + } + // Two quiet samples in a row after a move: at rest for half a second, as + // for moveEnd. + if (restingSamples >= 2 && movedSinceCheck) { + if (recover()) movedSinceCheck = false; + // A flight or a playing scene bounds its own deferral. + else settleElapsed = 0; + } + if (settleElapsed >= SETTLE_GIVE_UP_MS) return; + remember(); + settleTimer = schedule(sample, SETTLE_SAMPLE_MS); + }; + const startSettling = () => { + stopSettling(); + settleElapsed = 0; + restingSamples = 0; + movedSinceCheck = true; + remember(); + settleTimer = schedule(sample, SETTLE_SAMPLE_MS); + }; + const removeMoveEnd = camera.on('moveEnd', () => { + if (recover()) stopSettling(); + // Deferred: keep sampling so the check runs once the flight or scene ends. + else if (settleTimer === null) startSettling(); + }); + const removeMoveStart = camera.on('moveStart', startSettling); + + let active = true; + return () => { + if (!active) return; + active = false; + stopSettling(); + removeMoveEnd(); + removeMoveStart(); + for (const [target, type, listener] of listeners) + target?.removeEventListener?.(type, listener); + heldPointers.clear(); + }; +} diff --git a/src/app/globePanelRuntime.js b/src/app/globePanelRuntime.js index d10e5717d4..280eff0630 100644 --- a/src/app/globePanelRuntime.js +++ b/src/app/globePanelRuntime.js @@ -462,8 +462,11 @@ export function panelRuntime(config) { * Load God's Eye View into this page from the app's panel build, in * inline embed mode, starting at the first view as its link would. */ - async function startApp(url, view) { + async function startApp(url, view, fresh = false) { window.GEV_EMBED_INLINE = true; + // Whether this result was just issued, not handed back by a host that + // mounted the panel again: only then may its link open a billed photo. + window.GEV_EMBED_FRESH = fresh; window.GEV_APP_BASE_URL = config.appBaseUrl; try { history.replaceState( @@ -551,13 +554,21 @@ export function panelRuntime(config) { ); } - // Tool results: the first view starts the app, later ones move it. + // Tool results: the first view starts the app, later ones move it. A + // result issued longer ago than this was handed back on a remount. + const FRESH_RESULT_MS = 5 * 60 * 1000; let started = false; let ready = false; let queued = null; + let queuedFresh = false; let currentUrl = null; - const postView = (view) => - window.postMessage({ type: 'gev:view', id: nextId++, view }, '*'); + // Every view carries whether its result was issued just now: only those may + // open a billed photo, whichever result on this mount they came in. + const postView = (view, fresh) => + window.postMessage( + { type: 'gev:view', id: nextId++, view, fresh: fresh === true }, + '*', + ); function show(result) { const data = result?.structuredContent; const view = data?.view; @@ -565,13 +576,18 @@ export function panelRuntime(config) { if (!view || !url) return; currentUrl = url; open.hidden = false; - if (ready) return postView(view); + const issuedAt = Number(data.issued_at); + const fresh = + Number.isFinite(issuedAt) && + Math.abs(Date.now() - issuedAt) <= FRESH_RESULT_MS; + if (ready) return postView(view, fresh); queued = view; + queuedFresh = fresh; if (started) return; started = true; // i18n-ignore: host-panel script, no app catalogs say("Loading God's Eye View…"); - startApp(url, view).catch((error) => + startApp(url, view, fresh).catch((error) => // i18n-ignore: host-panel script, no app catalogs say(`God's Eye View could not load here: ${error?.message || error}.`), ); @@ -592,7 +608,7 @@ export function panelRuntime(config) { if (message?.type === 'gev:ready') { ready = true; status.remove(); - if (queued) postView(queued); + if (queued) postView(queued, queuedFresh); queued = null; } return; diff --git a/src/app/globePanelRuntime.test.mjs b/src/app/globePanelRuntime.test.mjs new file mode 100644 index 0000000000..186d2e743a --- /dev/null +++ b/src/app/globePanelRuntime.test.mjs @@ -0,0 +1,71 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { panelRuntime } from './globePanelRuntime.js'; + +const element = () => ({ + isConnected: true, + hidden: true, + textContent: '', + addEventListener() {}, + remove() { + this.isConnected = false; + }, +}); + +test('every view the panel posts says whether its result was issued just now', async () => { + const savedWindow = globalThis.window; + const savedDocument = globalThis.document; + const views = []; + const parent = { postMessage() {} }; + const windowRef = new EventTarget(); + Object.assign(windowRef, { + parent, + postMessage: (message) => { + if (message?.type === 'gev:view') views.push(message); + }, + }); + const elements = { status: element(), open: element(), expand: element() }; + globalThis.window = windowRef; + globalThis.document = { + getElementById: (id) => elements[id] ?? null, + addEventListener() {}, + baseURI: 'https://host.example/panel', + body: { clientWidth: 600 }, + }; + const deliver = (source, data) => { + const event = new Event('message'); + Object.assign(event, { source, data }); + windowRef.dispatchEvent(event); + }; + const result = (issuedAt) => ({ + jsonrpc: '2.0', + method: 'ui/notifications/tool-result', + params: { + structuredContent: { + url: 'http://localhost:4173/#sl=google,48.85840,2.29450', + issued_at: issuedAt, + view: { camera: { lat: 48.8584, lon: 2.2945 } }, + }, + }, + }); + try { + panelRuntime({ + appBaseUrl: 'http://localhost:4173/', + panelBase: '/panel/', + protocolVersion: '2025-06-18', + panelHeight: 480, + }); + deliver(windowRef, { type: 'gev:ready' }); + deliver(parent, result(Date.now())); + // A host replaying an old result on the same mount. + deliver(parent, result(Date.now() - 60 * 60 * 1000)); + deliver(parent, result(undefined)); + } finally { + globalThis.window = savedWindow; + globalThis.document = savedDocument; + } + assert.deepEqual( + views.map((message) => message.fresh), + [true, false, false], + ); +}); diff --git a/src/app/layerPresentation.js b/src/app/layerPresentation.js index eaa0e0b578..d3f1fb4483 100644 --- a/src/app/layerPresentation.js +++ b/src/app/layerPresentation.js @@ -18,6 +18,7 @@ export class LayerPresentation { this.pendingVisible = false; this._unsubscribe = manager.subscribeActivity((change) => { if (change.type === 'status') this.refresh(); + else if (change.type === 'registrations') this._panel?.rerender(); else if (change.type === 'destroy-all') this.destroy(); else { const reason = diff --git a/src/app/layers/aisLiveVessels.js b/src/app/layers/aisLiveVessels.js index cae0bf44c9..1f2a0ed850 100644 --- a/src/app/layers/aisLiveVessels.js +++ b/src/app/layers/aisLiveVessels.js @@ -10,9 +10,21 @@ import * as focus from '../../data/focusDeemphasis.js'; import * as worldFocus from '../../worldFocus.js'; import * as render from '../../renderGovernor.js'; import * as readouts from '../../hudReadouts.js'; +import { fleetModelServices } from './fleetModels.js'; -/** Construct one layer using the application scene owners and a supplied source. */ -export function createApplicationVessels({ source, options = {} }) { +/** + * Construct one layer using the application scene owners and a supplied + * source. `displayParams` reads the Flights layer's DISPLAY-rail 3D + * preference, under which nearby vessels are drawn as fleet models. + * `placement`: a host-supplied placement for its live vessels, or null. + */ +export function createApplicationVessels({ + source, + placement = null, + options = {}, + displayParams = null, + resolveAsset, +}) { return createVesselLayer({ source, options, @@ -28,6 +40,11 @@ export function createApplicationVessels({ source, options = {} }) { worldFocus, render, readouts, + placement, + fleet: fleetModelServices({ + display: displayParams, + ...(resolveAsset ? { resolveAsset } : {}), + }), }, }); } diff --git a/src/app/layers/droneAirspace.js b/src/app/layers/droneAirspace.js index f3472fec49..c9db27a57f 100644 --- a/src/app/layers/droneAirspace.js +++ b/src/app/layers/droneAirspace.js @@ -1,8 +1,6 @@ -import * as Cesium from 'cesium'; import { createDroneAirspaceLayer } from '../../layers/droneAirspace/index.js'; import * as picking from '../../data/pickRegistry.js'; import * as overlays from '../../overlays/worldOverlay.js'; -import { isPointerFree } from '../../data/inputOwnership.js'; /** Wire FAA special-use airspace into the application catalog. */ export function createApplicationDroneAirspace(options) { @@ -13,10 +11,7 @@ export function createApplicationDroneAirspace(options) { clearSource: overlays.clearOverlaySource, hitTest: overlays.hitTestWorldOverlay, }, - screenSpaceEventHandlerFactory: (viewer) => - new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas), picking, - pointer: { isPointerFree }, ...options, }); } diff --git a/src/app/layers/firms.js b/src/app/layers/firms.js index 6e64148784..4bb6518967 100644 --- a/src/app/layers/firms.js +++ b/src/app/layers/firms.js @@ -1,4 +1,3 @@ -import * as Cesium from 'cesium'; import { createFirmsHeatmapLayer as createLayer } from '../../layers/firms/index.js'; import * as render from '../../renderGovernor.js'; import * as sprites from '../../data/spriteOrder.js'; @@ -29,8 +28,5 @@ export function createApplicationFirms({ surface, ...options }) { clearSource: overlays.clearOverlaySource, hitTest: overlays.hitTestWorldOverlay, }, - screenSpaceEventHandlerFactory: - options.screenSpaceEventHandlerFactory ?? - ((viewer) => new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas)), }); } diff --git a/src/app/layers/fleetModels.js b/src/app/layers/fleetModels.js new file mode 100644 index 0000000000..f6c5bcb7dc --- /dev/null +++ b/src/app/layers/fleetModels.js @@ -0,0 +1,19 @@ +import { FLEET_MODEL_POLICY } from '../../layers/flights/policy.js'; + +/** + * The fleet-model service the Vessels, Transit and Rail layers draw their 3D + * models with: the Flights layer's DISPLAY-rail 3D preference + * (`{ models3d, models3dMode }`), the aircraft layers' icon-to-model rules, + * and the resolver the fleet set's files are fetched through. + * @param {{display?: (() => object|null)|null, + * resolveAsset?: (url: string) => string}} [options] + * @returns {object|null} Null without a display preference (no models). + */ +export function fleetModelServices({ + display = null, + resolveAsset = (url) => + `${import.meta.env?.BASE_URL || '/'}${url.replace(/^\//, '')}`, +} = {}) { + if (!display) return null; + return Object.freeze({ display, policy: FLEET_MODEL_POLICY, resolveAsset }); +} diff --git a/src/app/layers/flights.js b/src/app/layers/flights.js index 38f880a055..94fae26ee4 100644 --- a/src/app/layers/flights.js +++ b/src/app/layers/flights.js @@ -12,11 +12,13 @@ import * as context from '../../data/contextStore.js'; import * as render from '../../renderGovernor.js'; import * as recession from '../../data/aircraftRecession.js'; -/** Construct one layer using the application scene owners and a supplied source. */ +/** Construct one layer using the application scene owners and a supplied source. + * `placement`: a host-supplied placement for its live aircraft, or null. */ export function createApplicationFlights({ surface, source, militaryRegistry, + placement = null, resolveAsset = (url) => `${import.meta.env?.BASE_URL || '/'}${url.replace(/^\//, '')}`, }) { @@ -41,6 +43,7 @@ export function createApplicationFlights({ render, groundSnap, recession, + placement, }, }); } diff --git a/src/app/layers/ghostMaps.js b/src/app/layers/ghostMaps.js index ccca188507..56387a80fb 100644 --- a/src/app/layers/ghostMaps.js +++ b/src/app/layers/ghostMaps.js @@ -1,8 +1,6 @@ -import * as Cesium from 'cesium'; import { createGhostMapsLayer } from '../../layers/ghostMaps/index.js'; import * as picking from '../../data/pickRegistry.js'; import * as overlays from '../../overlays/worldOverlay.js'; -import { isPointerFree } from '../../data/inputOwnership.js'; /** Wire the S2 Underground GhostMaps layer into the application catalog. */ export function createApplicationGhostMaps(options) { @@ -14,10 +12,7 @@ export function createApplicationGhostMaps(options) { hitTest: overlays.hitTestWorldOverlay, }, openExternal: (url) => window.open(url, '_blank', 'noopener,noreferrer'), - screenSpaceEventHandlerFactory: (viewer) => - new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas), picking, - pointer: { isPointerFree }, ...options, }); } diff --git a/src/app/layers/militaryFlights.js b/src/app/layers/militaryFlights.js index 839220c545..fbedd20aa9 100644 --- a/src/app/layers/militaryFlights.js +++ b/src/app/layers/militaryFlights.js @@ -12,11 +12,13 @@ import * as context from '../../data/contextStore.js'; import * as render from '../../renderGovernor.js'; import * as recession from '../../data/aircraftRecession.js'; -/** Construct one layer using the application scene owners and a supplied source. */ +/** Construct one layer using the application scene owners and a supplied source. + * `placement`: a host-supplied placement for its live aircraft, or null. */ export function createApplicationMilitary({ surface, source, militaryRegistry, + placement = null, resolveAsset = (url) => `${import.meta.env?.BASE_URL || '/'}${url.replace(/^\//, '')}`, }) { @@ -41,6 +43,7 @@ export function createApplicationMilitary({ render, groundSnap, recession, + placement, }, }); } diff --git a/src/app/layers/news.js b/src/app/layers/news.js new file mode 100644 index 0000000000..552ad20dbb --- /dev/null +++ b/src/app/layers/news.js @@ -0,0 +1,6 @@ +import { createNewsLayer } from '../../layers/news/index.js'; +import { overlayHost } from './overlayHost.js'; +/** Wire the news layer to the application overlay host. */ +export function createApplicationNews(options) { + return createNewsLayer({ overlayHost, ...options }); +} diff --git a/src/app/layers/perimeters.js b/src/app/layers/perimeters.js index f5110f630d..dd1230ce46 100644 --- a/src/app/layers/perimeters.js +++ b/src/app/layers/perimeters.js @@ -1,4 +1,3 @@ -import * as Cesium from 'cesium'; import { createFirePerimetersLayer, createInciwebIndexSource, @@ -6,7 +5,6 @@ import { } from '../../layers/perimeters/index.js'; import * as picking from '../../data/pickRegistry.js'; import * as overlays from '../../overlays/worldOverlay.js'; -import { isPointerFree } from '../../data/inputOwnership.js'; /** Wire WFIGS fire perimeters into the application catalog. */ export function createApplicationFirePerimeters(options) { @@ -20,10 +18,7 @@ export function createApplicationFirePerimeters(options) { inciwebSource: createInciwebIndexSource(), inciwebPublications: createInciwebPublicationSource(), openExternal: (url) => window.open(url, '_blank', 'noopener,noreferrer'), - screenSpaceEventHandlerFactory: (viewer) => - new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas), picking, - pointer: { isPointerFree }, ...options, }); } diff --git a/src/app/layers/rail.js b/src/app/layers/rail.js new file mode 100644 index 0000000000..883b5f8771 --- /dev/null +++ b/src/app/layers/rail.js @@ -0,0 +1,64 @@ +import { createRailLayer } from '../../layers/rail/index.js'; +import * as render from '../../renderGovernor.js'; +import { fleetModelServices } from './fleetModels.js'; +import * as sprites from '../../data/spriteOrder.js'; +import * as picking from '../../data/pickRegistry.js'; +import * as overlays from '../../overlays/worldOverlay.js'; +import { WORLD_FOCUS_FRAMING, requestWorldFocus } from '../../worldFocus.js'; +import { + railFeedCredit, + registerDynamicCredit, +} from '../../data/dataCredits.js'; + +/** + * Construct the Rail layer on the application's scene owners and its shared + * ground floor, the same floor Transit and the aircraft stand on. + * `displayParams` reads the Flights layer's DISPLAY-rail 3D preference, under + * which nearby trains are drawn as fleet models. + * `placement` is a host-supplied placement for its live trains, or null. + * @param {{surface: object, source?: object, placement?: object|null, + * displayParams?: () => object|null, resolveAsset?: (url: string) => string}} options + * @returns {object} + */ +export function createApplicationRail({ + surface, + source, + placement = null, + displayParams = null, + resolveAsset, +}) { + if (!surface?.groundFloor) + throw new TypeError('Rail needs the application surface services'); + const { groundFloor } = surface; + return createRailLayer({ + source, + services: { + render, + sprites, + picking, + overlays, + placement, + credits: { registerDynamicCredit, railFeedCredit }, + ground: { + GROUND_FLOOR_LIFT_M: groundFloor.GROUND_FLOOR_LIFT_M, + cachedGroundFloor: groundFloor.cachedGroundFloor, + warmGroundFloor: groundFloor.warmGroundFloor, + neighborFloorM: groundFloor.neighborFloorM, + coarseFloorCoord: groundFloor.coarseFloorCoord, + }, + // A selected train is followed as a tracked aircraft is, or flown to + // once as a vessel is (src/layers/rail/follow.js). + camera: { + framing: WORLD_FOCUS_FRAMING.train, + requestWorldFocus, + isCockpitActive: () => + globalThis.document?.body?.classList?.contains('cockpit-mode') === + true, + }, + fleet: fleetModelServices({ + display: displayParams, + ...(resolveAsset ? { resolveAsset } : {}), + }), + }, + }); +} diff --git a/src/app/layers/shipwrecks.js b/src/app/layers/shipwrecks.js new file mode 100644 index 0000000000..8f91289f18 --- /dev/null +++ b/src/app/layers/shipwrecks.js @@ -0,0 +1,20 @@ +import { createShipwrecksLayer } from '../../layers/shipwrecks/index.js'; +import * as picking from '../../data/pickRegistry.js'; +import * as overlays from '../../overlays/worldOverlay.js'; +import { isPointerFree } from '../../data/inputOwnership.js'; + +/** Wire the EMODnet + Wikidata shipwrecks layer into the application catalog. */ +export function createApplicationShipwrecks(options) { + return createShipwrecksLayer({ + overlayHost: { + setEntries: overlays.setOverlayEntries, + setVisible: overlays.setOverlaySourceVisible, + clearSource: overlays.clearOverlaySource, + hitTest: overlays.hitTestWorldOverlay, + }, + openExternal: (url) => window.open(url, '_blank', 'noopener,noreferrer'), + picking, + pointer: { isPointerFree }, + ...options, + }); +} diff --git a/src/app/layers/streetLevel.js b/src/app/layers/streetLevel.js index 268216eaaf..3b7c7cc0b9 100644 --- a/src/app/layers/streetLevel.js +++ b/src/app/layers/streetLevel.js @@ -3,9 +3,7 @@ import { createMapillaryProvider } from '../../layers/streetLevel/providers/mapi import { createGoogleProvider } from '../../layers/streetLevel/providers/google/index.js'; import { createKartaViewProvider } from '../../layers/streetLevel/providers/kartaview/index.js'; import { createPanoramaxProvider } from '../../layers/streetLevel/providers/panoramax/index.js'; -import * as sprites from '../../data/spriteOrder.js'; import * as picking from '../../data/pickRegistry.js'; -import * as input from '../../data/inputOwnership.js'; import * as scenePick from '../../data/scenePick.js'; import * as render from '../../renderGovernor.js'; @@ -37,6 +35,6 @@ export function createApplicationStreetLevel({ }) { return createStreetLevelLayer({ providers, - services: { sprites, picking, input, scenePick, render }, + services: { picking, scenePick, render }, }); } diff --git a/src/app/layers/submarineCables.js b/src/app/layers/submarineCables.js index b84c072dbb..1f6dd7d817 100644 --- a/src/app/layers/submarineCables.js +++ b/src/app/layers/submarineCables.js @@ -1,12 +1,9 @@ -import * as Cesium from 'cesium'; import { createSubmarineCableLayer } from '../../layers/submarineCables/index.js'; import { overlayHost } from './overlayHost.js'; /** Wire cable source geometry to the application overlay host. */ export function createApplicationCables(options) { return createSubmarineCableLayer({ overlayHost, - screenSpaceEventHandlerFactory: (canvas) => - new Cesium.ScreenSpaceEventHandler(canvas), mapStackEventTarget: typeof window !== 'undefined' ? window : null, ...options, }); diff --git a/src/app/layers/transit.js b/src/app/layers/transit.js index 367fc425e0..5e89a1f47a 100644 --- a/src/app/layers/transit.js +++ b/src/app/layers/transit.js @@ -1,5 +1,6 @@ import { createTransitLayer } from '../../layers/transit/index.js'; import * as render from '../../renderGovernor.js'; +import { fleetModelServices } from './fleetModels.js'; import * as sprites from '../../data/spriteOrder.js'; import * as picking from '../../data/pickRegistry.js'; import * as overlays from '../../overlays/worldOverlay.js'; @@ -19,10 +20,21 @@ import { * own mesh floors. An earlier cut imported the legacy module-level singleton * instead and could not see either. * - * @param {{surface: object}} options + * `displayParams` reads the Flights layer's DISPLAY-rail 3D preference, under + * which nearby vehicles are drawn as fleet models. + * + * `placement` is a host-supplied placement for its live vehicles, or null. + * @param {{surface: object, source?: object, placement?: object|null, + * displayParams?: () => object|null, resolveAsset?: (url: string) => string}} options * @returns {object} */ -export function createApplicationTransit({ surface, source }) { +export function createApplicationTransit({ + surface, + source, + placement = null, + displayParams = null, + resolveAsset, +}) { if (!surface?.groundFloor || !surface?.meshFloor) throw new TypeError('Transit needs the application surface services'); const { groundFloor, meshFloor } = surface; @@ -33,6 +45,7 @@ export function createApplicationTransit({ surface, source }) { sprites, picking, overlays, + placement, credits: { registerDynamicCredit, transitFeedCredit }, ground: { GROUND_FLOOR_LIFT_M: groundFloor.GROUND_FLOOR_LIFT_M, @@ -44,6 +57,10 @@ export function createApplicationTransit({ surface, source }) { allocateCorridorCells: groundFloor.allocateCorridorCells, }, mesh: { sampleMeshFloorCells: meshFloor.sampleMeshFloorCells }, + fleet: fleetModelServices({ + display: displayParams, + ...(resolveAsset ? { resolveAsset } : {}), + }), }, }); } diff --git a/src/app/layers/wildlifeSightings.js b/src/app/layers/wildlifeSightings.js index 6d181f2c72..6ce091c553 100644 --- a/src/app/layers/wildlifeSightings.js +++ b/src/app/layers/wildlifeSightings.js @@ -1,4 +1,3 @@ -import * as Cesium from 'cesium'; import { createWildlifeSightingsLayer } from '../../layers/wildlifeSightings/index.js'; import * as picking from '../../data/pickRegistry.js'; import * as overlays from '../../overlays/worldOverlay.js'; @@ -17,8 +16,6 @@ export function createApplicationWildlifeSightings(options) { clearSource: overlays.clearOverlaySource, hitTest: overlays.hitTestWorldOverlay, }, - screenSpaceEventHandlerFactory: (viewer) => - new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas), picking, pointer: { isPointerFree }, sprites, diff --git a/src/app/localGeojsonServices.js b/src/app/localGeojsonServices.js index 8103f3b353..a9607e192b 100644 --- a/src/app/localGeojsonServices.js +++ b/src/app/localGeojsonServices.js @@ -2,6 +2,7 @@ import { showOsmCredit, hideOsmCredit } from '../data/dataCredits.js'; import { governorRequestRender } from '../renderGovernor.js'; import { clearSelectedEntityContextForLayer, + getSelectedEntityContext, registerEntityContext, removeEntityContextsForLayer, selectEntityContext, @@ -19,6 +20,7 @@ export const localGeoJsonServices = Object.freeze({ setVisible: setOverlaySourceVisible, }), clearSelectedEntityContextForLayer, + getSelectedEntityContext, registerEntityContext, removeEntityContextsForLayer, selectEntityContext, diff --git a/src/app/mapLifecycle.test.mjs b/src/app/mapLifecycle.test.mjs index ef015bf52a..6286ca71d9 100644 --- a/src/app/mapLifecycle.test.mjs +++ b/src/app/mapLifecycle.test.mjs @@ -1,6 +1,7 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { MapStackController } from '../mapStackController.js'; +import '../render/cesium/mapEngine.js'; import { installRenderGovernor, uninstallRenderGovernor, @@ -8,6 +9,7 @@ import { governorRequestRender, getRenderGovernorDiagnostics, } from '../renderGovernor.js'; +import { framePortFor } from '../testSupport/fakeFramePort.mjs'; test('destroy invalidates a pending imagery provider before it can touch the viewer', async () => { let resolveProvider; @@ -44,11 +46,11 @@ test('uninstall only releases the current viewer and makes later render requests }, }, }; - installRenderGovernor(viewer); + installRenderGovernor(framePortFor(viewer.scene)); holdContinuousRender('fixture'); - uninstallRenderGovernor({}); + uninstallRenderGovernor(framePortFor({})); assert.equal(getRenderGovernorDiagnostics().installed, true); - uninstallRenderGovernor(viewer); + uninstallRenderGovernor(framePortFor(viewer.scene)); const before = renders; governorRequestRender('late'); assert.equal(renders, before); diff --git a/src/app/panelRendering.js b/src/app/panelRendering.js new file mode 100644 index 0000000000..1b3688eb12 --- /dev/null +++ b/src/app/panelRendering.js @@ -0,0 +1,74 @@ +/** + * @module app/panelRendering + * @description Keeping the globe drawing in an inline panel whose host stops + * animation frames (`src/app/embed.js`, embed mode), through the ports alone: the + * application scene hands it to the embed views (`src/app/scene.js`). + */ + +// A panel keeps drawing at about this rate when its host stops animation +// frames; see keepPanelRendering. +const PANEL_FRAME_MS = 33; +const MISSED_FRAMES_MS = 250; + +/** A render error's details, including the plain objects workers report. */ +function describeError(error) { + if (error instanceof Error) + return `${error.name}: ${error.message}\n${error.stack}`; + try { + return JSON.stringify(error, Object.getOwnPropertyNames(error ?? {})); + } catch { + return String(error); + } +} + +/** + * Keep `renderer` drawing in an inline panel. Some hosts report a panel on + * screen as hidden, which stops the browser's animation frames and with them + * the renderer's own loop; while frames stop arriving, draw from a timer + * (`resize`, then a frame of the loop, `frame.renderNow({ifDue: true})`: the + * camera moves, input and the clock run, and it draws when due). While the + * renderer's loop is stopped after a failed frame (`stopped` in its frame + * diagnostics) the timer waits, and goes on once a retry starts the loop + * again; the render failure notice reports the error + * (src/render/cesium/renderFailure.js). Where the renderer never says so, a frame + * that fails stops the timer, its error reported in full. Returns a + * function that stops it. + * @param {import('../render/contract/renderer').Renderer} renderer + * @param {{windowRef?: Window, now?: () => number}} [options] + * @returns {() => void} + */ +export function keepPanelRendering( + renderer, + { windowRef = globalThis.window, now = () => performance.now() } = {}, +) { + let lastFrame = now(); + let frameRequest = null; + const onFrame = () => { + lastFrame = now(); + frameRequest = windowRef.requestAnimationFrame(onFrame); + }; + frameRequest = windowRef.requestAnimationFrame(onFrame); + let failed = false; + const stopped = () => renderer.frame.diagnostics?.().stopped; + const timer = windowRef.setInterval(() => { + if (failed || now() - lastFrame < MISSED_FRAMES_MS || stopped()) return; + try { + renderer.resize(); + renderer.frame.renderNow({ ifDue: true }); + } catch (error) { + // Stopped by now: the render failure notice has the error. + if (stopped() !== undefined) return; + // Report the error in full: workers report plain objects, which + // would print as [object Object]. + failed = true; + console.error( + "[God's Eye View panel] render error:", + describeError(error), + ); + } + }, PANEL_FRAME_MS); + return () => { + windowRef.clearInterval(timer); + windowRef.cancelAnimationFrame(frameRequest); + }; +} diff --git a/src/app/panelRendering.test.mjs b/src/app/panelRendering.test.mjs new file mode 100644 index 0000000000..49af8b2aa0 --- /dev/null +++ b/src/app/panelRendering.test.mjs @@ -0,0 +1,125 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { keepPanelRendering } from './panelRendering.js'; + +const windowWith = () => { + const handles = { tick: null, frame: null }; + handles.windowRef = { + requestAnimationFrame: (fn) => ((handles.frame = fn), 1), + cancelAnimationFrame: () => (handles.frame = null), + setInterval: (fn) => ((handles.tick = fn), 1), + clearInterval: () => (handles.tick = null), + }; + return handles; +}; + +test('a panel keeps drawing from a timer while animation frames stop', () => { + let clock = 0; + const handles = windowWith(); + const drawn = []; + const renderer = { + resize: () => drawn.push('resize'), + frame: { + renderNow: (options) => + drawn.push(options?.ifDue ? 'loop frame' : 'forced frame'), + }, + }; + const stop = keepPanelRendering(renderer, { + windowRef: handles.windowRef, + now: () => clock, + }); + // Frames arrive: the render loop draws, so the timer does nothing. + clock = 100; + handles.frame(); + handles.tick(); + assert.deepEqual(drawn, []); + // Frames stop, as in a panel its host reports hidden: the timer draws. + clock = 400; + handles.tick(); + // A frame of the loop, as the loop's own: the camera moves, input and + // the clock run, and it draws when due. + assert.deepEqual(drawn, ['resize', 'loop frame']); + stop(); + assert.equal(handles.tick, null); + assert.equal(handles.frame, null); +}); + +test('a panel reports a failed frame in full and stops drawing', () => { + const handles = windowWith(); + let renders = 0; + const renderer = { + resize() {}, + frame: { + renderNow() { + renders += 1; + // Workers report plain objects. + throw { name: 'RuntimeError', message: 'worker failed' }; + }, + }, + }; + const logged = []; + const original = console.error; + console.error = (...args) => logged.push(args.join(' ')); + try { + let clock = 0; + const stop = keepPanelRendering(renderer, { + windowRef: handles.windowRef, + now: () => clock, + }); + clock = 1000; + handles.tick(); + assert.match(logged[0], /render error: .*"message":"worker failed"/); + handles.tick(); + assert.equal(renders, 1, 'no frame after the one that failed'); + stop(); + } finally { + console.error = original; + } +}); + +test('a panel waits while its renderer’s loop is stopped after a failed frame, and draws again once it restarts', () => { + let clock = 0; + const handles = windowWith(); + let stopped = false; + let fail = false; + let renders = 0; + const renderer = { + resize() {}, + frame: { + diagnostics: () => ({ stopped }), + renderNow() { + renders += 1; + if (fail) { + // The renderer stops its loop as the frame fails. + stopped = true; + throw new Error('frame failed'); + } + }, + }, + }; + const errors = []; + const error = console.error; + console.error = (...args) => errors.push(args); + try { + const stop = keepPanelRendering(renderer, { + windowRef: handles.windowRef, + now: () => clock, + }); + clock = 1000; + fail = true; + handles.tick(); + assert.equal(renders, 1); + // Stopped: the timer waits, and leaves the error to the notice. + handles.tick(); + assert.equal(renders, 1); + assert.deepEqual(errors, []); + // A retry starts the loop again: the timer draws again. + stopped = false; + fail = false; + handles.tick(); + assert.equal(renders, 2); + stop(); + } finally { + console.error = error; + } +}); diff --git a/src/app/renderFailureInlineRetry.test.mjs b/src/app/renderFailureInlineRetry.test.mjs new file mode 100644 index 0000000000..31dff45918 --- /dev/null +++ b/src/app/renderFailureInlineRetry.test.mjs @@ -0,0 +1,132 @@ +// Retry in an inline panel whose host stops animation frames, so the panel +// draws from keepPanelRendering's timer. Drives Cesium's real startRenderLoop +// and useDefaultRenderLoop setter (CesiumWidget.prototype), through the +// Cesium frame port. +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import { keepPanelRendering } from './panelRendering.js'; +import { renderLoopFixture } from '../render/cesium/renderLoopFixture.mjs'; +import { createSceneFrame } from '../render/cesium/frame.js'; + +function setup() { + let tick = null; + let clock = 0; + // The host reports the panel hidden: its own animation frames never arrive. + const windowRef = { + requestAnimationFrame: () => 1, + cancelAnimationFrame() {}, + setInterval: (fn) => ((tick = fn), 1), + clearInterval() {}, + }; + const previousError = console.error; + console.error = () => {}; + const state = { failure: null, drawn: 0 }; + const scene = { + renderError: new Cesium.Event(), + preUpdate: new Cesium.Event(), + preRender: new Cesium.Event(), + postRender: new Cesium.Event(), + requestRender() {}, + initializeFrame() {}, + // Scene.render: a failing primitive update raises renderError + // (tryAndCatchError) and returns; a failing listener throws. + render() { + state.drawn += 1; + this.preUpdate.raiseEvent(this); + if (state.failure === 'caught') + this.renderError.raiseEvent(this, new Error('boom')); + if (state.failure === 'thrown') throw new Error('boom'); + this.postRender.raiseEvent(this); + }, + }; + const { frames, widget, viewer, store, runFrames, restore } = + renderLoopFixture(scene, { + viewer: { + isDestroyed: () => false, + render: () => widget.render(), + resize: () => widget.resize(), + }, + notice: { allowReload: false }, + }); + const frame = createSceneFrame(viewer); + const renderer = { resize: () => viewer.resize(), frame: frame.port }; + const stopPanel = keepPanelRendering(renderer, { + windowRef, + now: () => clock, + }); + const stop = () => { + stopPanel(); + frame.dispose(); + }; + viewer.useDefaultRenderLoop = true; + const timerFrame = () => { + clock += 400; + tick(); + }; + return { + frames, + state, + store, + timerFrame, + animationFrames: runFrames, + restore: () => { + stop(); + restore(); + console.error = previousError; + }, + }; +} + +for (const failure of ['caught', 'thrown']) { + test(`an error ${failure} in a frame the timer draws: Retry draws again with one render loop`, () => { + const { frames, state, store, timerFrame, animationFrames, restore } = + setup(); + try { + // The host stops animation frames with the loop's next one queued. + assert.equal(frames.length, 1); + state.failure = failure; + timerFrame(); // an error thrown here does not reach the host page + assert.equal(store.renderFailure?.reason, 'render-error'); + assert.equal(typeof store.renderFailure.retry, 'function'); + state.failure = null; + store.renderFailure.retry(); + const before = state.drawn; + timerFrame(); + assert.ok(state.drawn > before, 'the panel draws again after Retry'); + assert.equal( + store.renderFailure, + null, + 'a clean frame clears the notice', + ); + assert.equal(frames.length, 1, 'Retry starts no second loop'); + // The host resumes frames: the globe draws once a frame. + state.drawn = 0; + animationFrames(3); + assert.equal(state.drawn, 3); + } finally { + restore(); + } + }); +} + +test('an error Scene caught in an animation frame right before the host stopped frames: Retry keeps one render loop', () => { + const { frames, state, store, timerFrame, animationFrames, restore } = + setup(); + try { + state.failure = 'caught'; + animationFrames(1); + assert.equal(store.renderFailure?.reason, 'render-error'); + assert.equal(frames.length, 1); + state.failure = null; + store.renderFailure.retry(); + timerFrame(); + assert.equal(store.renderFailure, null); + assert.equal(frames.length, 1, 'Retry starts no second loop'); + state.drawn = 0; + animationFrames(3); + assert.equal(state.drawn, 3); + } finally { + restore(); + } +}); diff --git a/src/app/scene.js b/src/app/scene.js index b9799b8acf..63012fb663 100644 --- a/src/app/scene.js +++ b/src/app/scene.js @@ -1,26 +1,66 @@ import { createApplicationOperations } from './operations.js'; -import * as Cesium from 'cesium'; -import { - createApplicationViewer, - installFreeLookHeightLimit, - installTrackpadPinchZoom, -} from '../app/viewer.js'; import { registerDataCredits } from '../data/dataCredits.js'; -import { configureCreditKeyboardAccess } from '../creditKeyboard.js'; +import { mountCreditsView } from '../ui/creditsView.js'; import { MapStackController } from '../mapStackController.js'; -import { loadPhotorealisticTileset } from '../mapStartup.js'; +import { mapEngineFor } from '../maps/engine.js'; import { initLogoGaze } from '../logoGaze.js'; +import { inputFor } from '../input/dispatcher.js'; import { + holdContinuousRender, + installRenderGovernor, uninstallRenderGovernor, governorRequestRender, + releaseContinuousRender, } from '../renderGovernor.js'; import { describeError } from './errors.js'; +import { isEmbeddedInline } from './embed.js'; import { worldClock, worldTimeFor } from '../time/worldClock.js'; import { followWorldTime } from '../time/viewerClock.js'; -import { onLocaleChange, t } from '../i18n/index.js'; +import { t } from '../i18n/index.js'; +import { + applicationHooksOf, + provideApplicationHooks, +} from '../render/applicationHooks.js'; +import { keepPanelRendering } from './panelRendering.js'; +import { useStatusStore } from '../ui/stores/status.js'; +import { applicationPinia } from '../ui/vueRuntime.js'; +import { createSceneHost } from '../render/rendererOf.js'; -/** Construct the application globe using the caller's local configuration. */ +let defaultLoad = null; + +/** + * The application's composition root picks the renderer: the one given, else + * the default (Cesium), loaded only then, so a page on the stub never + * loads it. This is the only part of an adapter the application imports. A + * page that starts on the default calls this as it starts, so the renderer + * loads beside the rest of the page rather than after it. + * @returns {Promise} The default `RendererPlugin`. + */ +export function loadDefaultRenderer() { + if (defaultLoad) return defaultLoad; + const load = (async () => { + const { cesiumRenderer } = await import('../render/cesium/application.js'); + return cesiumRenderer; + })(); + defaultLoad = load; + // A load that failed is tried again by the next call. + load.catch(() => { + if (defaultLoad === load) defaultLoad = null; + }); + return load; +} + +/** + * Construct the application globe using the caller's local configuration. + * `renderer` is the `RendererPlugin` that draws it, or a promise of one + * (default: Cesium, `loadDefaultRenderer`). The + * application runs on a renderer with only the contract's required members: + * what a renderer's plugin hands it beside the contract + * (`src/render/applicationHooks.js`) it uses where given, and does without + * where not. + */ export async function createApplicationScene({ + renderer: givenPlugin, requestServices, googleApiKey, googleTokens = null, @@ -47,52 +87,117 @@ export async function createApplicationScene({ }); } loaderStatus.textContent = t('Configuring viewer...'); - // Provider attribution stays visible, including clean-view and recording. - const creditContainer = document.createElement('div'); - creditContainer.id = 'cesium-credits'; - document.body.appendChild(creditContainer); - defer(() => creditContainer.remove()); - const viewer = createApplicationViewer({ - container: 'cesiumContainer', - creditContainer, + const rendererPlugin = (await givenPlugin) ?? (await loadDefaultRenderer()); + signal.throwIfAborted(); + const container = document.getElementById('cesiumContainer'); + const renderer = await rendererPlugin.create({ + container, + googleApiKey: googleApiKey || undefined, + googleTokens: googleTokens + ? (options) => googleTokens.token(options) + : undefined, + worldDataToken: cesiumToken || undefined, + signal, }); + // The scene object every layer and tool is handed: the application's own, + // bound to the renderer. + const scene = createSceneHost(renderer, { container }); + const viewer = scene.host; + // The governor keeps its holds on the renderer's frame port. The loop + // draws every frame until the application's tools are up (they release + // 'boot'), as it did before anything could hold it. A camera move holds + // it drawing every frame too. + installRenderGovernor(renderer.frame, { camera: renderer.camera }); + holdContinuousRender('boot'); defer(() => { - uninstallRenderGovernor(viewer); - if (!viewer.isDestroyed()) viewer.destroy(); + try { + uninstallRenderGovernor(renderer.frame); + } finally { + try { + renderer.destroy(); + } finally { + scene.release(); + } + } }); - defer(installTrackpadPinchZoom(viewer)); + // What the plugin hands the application beside the contract, each hook + // optional (render/applicationHooks.js). + if (typeof rendererPlugin.applicationHooks === 'function') + provideApplicationHooks( + renderer, + rendererPlugin.applicationHooks(renderer), + ); + const hooks = applicationHooksOf(renderer); + // The renderer follows its container's size (`Renderer.resize`). + if (typeof ResizeObserver === 'function' && container) { + const resizes = new ResizeObserver(() => renderer.resize()); + resizes.observe(container); + defer(() => resizes.disconnect()); + } + // Before any layer binds a click: every layer and tool shares this one. + // Deferred after the renderer, so it is released before the renderer goes. + const input = inputFor(viewer); + defer(() => input.destroy()); + // Ctrl+wheel and trackpad pinches zoom the globe, not the page. + const { controls } = renderer.camera; + if (!controls.zoomInputs.includes('ctrlWheel')) + controls.zoomInputs = [...controls.zoomInputs, 'ctrlWheel']; + // The user's outward zooms stop at a whole-Earth view, which stays framed. + if (renderer.capabilities.has('keepEarthFramed')) { + controls.keepEarthFramed = true; + defer(() => { + controls.keepEarthFramed = false; + }); + } + // The renderer's own notice when the globe stops drawing, in place of a + // dead-end panel; an inline panel must not reload or navigate its host's + // page. + const offRenderFailure = hooks.renderFailureNotice?.({ + allowReload: !isEmbeddedInline(), + store: useStatusStore(applicationPinia()), + }); + if (offRenderFailure) defer(offRenderFailure); defer( followWorldTime(viewer, worldTimeFor('sky'), { subscribe: worldClock.subscribe, requestRender: () => governorRequestRender('world-time'), + // A playing world time moves something every frame: draw at the + // display's rate meanwhile, not the parked scene's cap. + onPlaying: (playing) => + playing + ? holdContinuousRender('world-time') + : releaseContinuousRender('world-time'), }), ); - defer(installFreeLookHeightLimit(viewer)); registerDataCredits(viewer, credits); - configureCreditKeyboardAccess(document); - defer(onLocaleChange(() => configureCreditKeyboardAccess(document))); + // The credits, in the application's own line, unless the renderer shows + // them in a display of its own. + if (!hooks.ownCreditDisplay) defer(mountCreditsView(viewer)); loaderStatus.textContent = googleApiKey || googleTokens || cesiumToken ? t('Loading Google 3D Tiles...') : t('Loading the keyless globe...'); - const photoreal = await loadPhotorealisticTileset(Cesium, { + // The map stacks, and the photoreal base among them, switch through the + // scene's map engine: the renderer's own, or its globe port. + const engine = mapOptions.engine ?? mapEngineFor(viewer); + const photoreal = (await engine.loadPhotoreal?.(viewer, { googleApiKey, googleTokens, cesiumToken, - }); + })) ?? { tileset: null, route: 'none', errors: [] }; const tileset = photoreal.tileset; // A provider can finish after cancellation; retain ownership of its result. defer(() => { - if (tileset && !tileset.isDestroyed()) { - if (!viewer.scene.primitives.remove(tileset)) tileset.destroy(); - } + if (!tileset || engine.isDestroyed(tileset)) return; + engine.removeTileset(viewer, tileset); + engine.release(tileset); }); signal.throwIfAborted(); if (tileset) { - viewer.scene.primitives.add(tileset); + engine.addTileset(viewer, tileset); // NOTE: Cesium World Terrain intentionally disabled — conflicts with Google 3D Tiles at high zoom. // Google Photorealistic 3D Tiles provide their own terrain/elevation. - viewer.scene.globe.show = false; + renderer.globe.setGlobeVisible(false); console.info(`[Init] Google 3D Tiles loaded via ${photoreal.route}.`); } else { if (photoreal.errors.length) { @@ -109,7 +214,7 @@ export async function createApplicationScene({ }, ); } - viewer.scene.globe.show = true; + renderer.globe.setGlobeVisible(true); } loaderStatus.textContent = t('Initializing systems...'); @@ -117,6 +222,7 @@ export async function createApplicationScene({ const mapStackController = new MapController(viewer, { requestRender: governorRequestRender, ...mapOptions, + engine, googleTileset: tileset, cesiumToken, initialStack: tileset ? 'photoreal' : 'esri-imagery', @@ -138,5 +244,22 @@ export async function createApplicationScene({ }); signal.throwIfAborted(); - return { viewer, tileset, mapStackController, operations }; + return { + renderer, + viewer, + tileset, + mapStackController, + operations, + input, + // Keeps the globe drawing in an inline panel whose host stops animation + // frames (embed mode, src/app/embed.js); returns its disposer. + keepPanelRendering: (options) => keepPanelRendering(renderer, options), + // What the renderer's plugin hands the application beside the contract, + // each optional: trims stale draw commands, says whether an entity is + // the renderer's own, and what QA scripts read + // (render/applicationHooks.js). + trimStaleCommands: hooks.trimStaleCommands, + viewerDrawsEntity: hooks.viewerDrawsEntity, + qaHandles: hooks.qaHandles, + }; } diff --git a/src/app/scene.test.mjs b/src/app/scene.test.mjs new file mode 100644 index 0000000000..b19dac0f81 --- /dev/null +++ b/src/app/scene.test.mjs @@ -0,0 +1,152 @@ +import '../testSupport/registerDom.mjs'; +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { createApplicationScene } from './scene.js'; +import { createApplicationRequestServices } from '../services/requests.js'; +import { createStubRendererPlugin } from '../render/stub/index.js'; +import { rendererOf } from '../render/rendererOf.js'; + +/** Start the scene on a stub renderer with `capabilities`. */ +async function startOnStub(t, { capabilities = [], ...rest } = {}) { + document.body.innerHTML = '
'; + const made = []; + const deferred = []; + t.after(async () => { + for (const fn of deferred.reverse()) await fn(); + }); + const scene = await createApplicationScene({ + renderer: createStubRendererPlugin({ capabilities }, (renderer) => + made.push(renderer), + ), + requestServices: createApplicationRequestServices(), + loaderStatus: { textContent: '' }, + signal: new AbortController().signal, + defer: (fn) => deferred.push(fn), + ...rest, + }); + return { scene, renderer: made[0], deferred }; +} + +test('the scene runs on a renderer with only the required members', async (t) => { + const { scene, renderer, deferred } = await startOnStub(t); + assert.equal(scene.renderer, renderer); + assert.equal(rendererOf(scene.viewer), renderer, 'the scene object is bound'); + assert.equal( + scene.viewer.container, + document.getElementById('cesiumContainer'), + ); + assert.equal(scene.viewer.isDestroyed(), false); + assert.ok( + scene.viewer.container.contains(renderer.canvas), + 'the renderer fills the container', + ); + // Nothing of the engine on the scene object. + assert.deepEqual(Object.keys(scene.viewer).sort(), [ + 'container', + 'isDestroyed', + ]); + // No hooks: each is left out, not faked. + for (const name of ['trimStaleCommands', 'viewerDrawsEntity', 'qaHandles']) + assert.equal(scene[name], undefined, name); + // What the renderer does through its ports. + assert.equal(typeof scene.keepPanelRendering, 'function'); + assert.equal( + renderer.camera.controls.keepEarthFramed, + undefined, + 'no framing on a renderer without it', + ); + // Keyless, the map stack shows Esri on the globe through the globe port. + assert.equal(scene.tileset, null); + assert.equal(scene.mapStackController.getActiveId(), 'esri-imagery'); + const layers = renderer.globe.imagery.list(); + assert.equal(layers.length, 1, 'one base imagery layer'); + assert.ok( + renderer.testing.calls.some( + (call) => + call.port === 'globe' && + call.member === 'imagery.add' && + call.args[0]?.url?.includes('World_Imagery'), + ), + 'Esri imagery through the port', + ); + assert.equal(scene.mapStackController.getDrapeSurface(), 'globe'); + // The credits show in the application's own line: the Esri base's on it, + // the data credits in the list it opens. + const line = document.getElementById('gev-credits'); + assert.ok(line, 'a credits line'); + assert.match(line.textContent, /Esri/); + assert.ok( + document.querySelectorAll('#gev-credits-panel li').length > 10, + 'the data credits', + ); + + // Switching stacks goes through the port too. + await scene.mapStackController.setStack('osm'); + assert.equal(scene.mapStackController.getActiveId(), 'osm'); + assert.equal(renderer.globe.imagery.list().length, 1, 'Esri gave way'); + + for (const fn of deferred.splice(0).reverse()) await fn(); + assert.equal(scene.viewer.isDestroyed(), true); + assert.equal(rendererOf(scene.viewer), null, 'and lets go of the renderer'); + assert.equal(renderer.globe.imagery.list().length, 0, 'imagery released'); + assert.equal(document.getElementById('gev-credits'), null, 'credits gone'); +}); + +test('the scene keeps the Earth framed where the renderer can', async (t) => { + const { renderer, deferred } = await startOnStub(t, { + capabilities: ['keepEarthFramed'], + }); + assert.equal(renderer.camera.controls.keepEarthFramed, true); + const controls = renderer.camera.controls; + for (const fn of deferred.splice(0).reverse()) await fn(); + assert.equal(controls.keepEarthFramed, false, 'and lets go on teardown'); +}); + +test("the scene takes a plugin's application hooks", async (t) => { + const stub = createStubRendererPlugin({ capabilities: [] }); + const given = []; + const handles = Object.freeze({ probe: 'qa' }); + const { scene } = await startOnStub(t, { + renderer: { + id: 'stub-with-hooks', + create: (options) => stub.create(options), + applicationHooks(made) { + given.push(made); + return { qaHandles: handles, ownCreditDisplay: true }; + }, + }, + }); + assert.deepEqual(given, [scene.renderer], 'asked once, for the renderer'); + assert.equal(scene.qaHandles, handles, 'QA scripts read its handles'); + assert.equal( + document.getElementById('gev-credits'), + null, + 'its own display shows the credits', + ); +}); + +test('with credentials, the photoreal base loads through the globe port', async (t) => { + const { scene, renderer } = await startOnStub(t, { + capabilities: ['photoreal', 'globeVisibility'], + googleApiKey: 'stub-key', + }); + assert.ok(scene.tileset, 'a photoreal base'); + assert.equal(scene.mapStackController.getActiveId(), 'photoreal'); + assert.equal(renderer.globe.isGlobeVisible(), false, 'the globe is hidden'); + const photoreal = renderer.testing.calls.filter( + (call) => call.port === 'globe' && call.member === 'setPhotoreal', + ); + assert.equal(photoreal[0]?.args[0]?.key, 'stub-key'); + + // A globe stack hides photoreal through the port, and shows the globe. + await scene.mapStackController.setStack('esri-imagery'); + assert.equal(renderer.globe.isGlobeVisible(), true); + assert.equal( + renderer.testing.calls + .filter((call) => call.port === 'globe' && call.member === 'setPhotoreal') + .at(-1).args[0], + null, + ); + await scene.mapStackController.setStack('photoreal'); + assert.equal(renderer.globe.isGlobeVisible(), false); +}); diff --git a/src/app/sourceComposition.js b/src/app/sourceComposition.js index bc3e3b37cf..fef0136c1d 100644 --- a/src/app/sourceComposition.js +++ b/src/app/sourceComposition.js @@ -49,10 +49,13 @@ export const CATALOG_SOURCE_CONTRACTS = Object.freeze({ 'air-quality': contract(['air-quality'], ['getSnapshot']), 'gnss-integrity': contract(['gnss-integrity'], ['getSnapshot']), 's2-ghostmaps': contract(['s2-ghostmaps'], ['getCatalog', 'getFile']), + shipwrecks: contract(['shipwrecks'], ['getSnapshot']), 'drone-airspace': contract(['drone-airspace'], ['getSnapshot']), + news: contract(['news'], ['getHotspots', 'getFeed', 'getOutline']), 'wildlife-sightings': contract(['wildlife-sightings'], ['getSnapshot']), cables: contract(['telegeography-submarine-cables'], ['fetch']), transit: contract(['transit'], ['requestSnapshot', 'getHistory']), + rail: contract(['rail'], ['requestSnapshot', 'getFeeds']), }); /** An omitted provider is unavailable, never an authoritative empty dataset. */ diff --git a/src/app/sourceComposition.test.mjs b/src/app/sourceComposition.test.mjs index 2a18039f28..e5a3bcb6ee 100644 --- a/src/app/sourceComposition.test.mjs +++ b/src/app/sourceComposition.test.mjs @@ -1,3 +1,5 @@ +// The click dispatcher's input port over a viewer double: the Cesium adapter's. +import '../render/cesium/input.js'; import assert from 'node:assert/strict'; import test from 'node:test'; import { @@ -37,7 +39,7 @@ test('every acquisition source can be omitted without losing catalog membership' test('all acquisition sources may be absent, and enable fails before initializing or fetching', async (t) => { const actual = catalog({}, t); - assert.equal(actual.layers.length, 38); + assert.equal(actual.layers.length, 41); const manager = new LayerLifecycle( {}, { getSourceAvailability: actual.getSourceAvailability }, @@ -150,6 +152,35 @@ test('GhostMaps obeys source omission, replacement and explicit removal', async assert.equal(fetches, 0); }); +test('News is unavailable without a source and the standalone default reads only same-origin /api/news', async (t) => { + const missing = catalog({}, t); + assert.equal(missing.getSourceAvailability('news')?.available, false); + const manager = new LayerLifecycle( + {}, + { getSourceAvailability: missing.getSourceAvailability }, + ); + manager.register(missing.get('news')); + assert.equal(await manager.setEnabled('news', true), false); + assert.equal(manager.layers.get('news').initialized, false); + assert.equal(createStandaloneLayerSources({ news: null }).news, null); + + const urls = []; + t.mock.method(globalThis, 'fetch', async (url) => { + urls.push(url); + return new Response( + JSON.stringify({ + error: 'news_not_configured', + unavailable: true, + retryable: false, + }), + { status: 503 }, + ); + }); + const standalone = createStandaloneLayerSources().news; + await assert.rejects(standalone.getHotspots(), { unavailable: true }); + assert.deepEqual(urls, ['/api/news/hotspots']); +}); + test('empty Street Level uses the shared unavailable lifecycle without initialization', async (t) => { const actual = catalog({}, t); const manager = new LayerLifecycle( @@ -218,3 +249,18 @@ test('absent military acquisition does not poll, suppress flights, or erase supp assert.equal(registry.isMilitaryLayerActive(), false); assert.equal(fetches, 0); }); + +test('a rail source must carry the feed catalog that keeps unbuilt packs out', () => { + // Without getFeeds the layer could never learn which schedule packs are + // built, so the live feeds that read their routes from one would never run. + assert.throws( + () => + resolveCatalogSources({ rail: { requestSnapshot: async () => null } }), + /Invalid catalog source: rail/, + ); + const source = { + requestSnapshot: async () => null, + getFeeds: async () => [], + }; + assert.equal(resolveCatalogSources({ rail: source }).sources.rail, source); +}); diff --git a/src/app/startupCamera.test.mjs b/src/app/startupCamera.test.mjs index 721f9964b1..0c1767cef2 100644 --- a/src/app/startupCamera.test.mjs +++ b/src/app/startupCamera.test.mjs @@ -1,25 +1,41 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { flyToAustin } from '../camera.js'; +import { applyStartView, START_VIEW } from '../camera.js'; +import { bindFakeCesiumCamera } from '../testSupport/fakeCameraPort.mjs'; -test('teardown before the initial camera delay prevents a late flight', (t) => { - t.mock.timers.enable({ apis: ['setTimeout'] }); - let flights = 0; - let cancelled = 0; - const stop = flyToAustin({ +function viewerRecording(views) { + return bindFakeCesiumCamera({ isDestroyed: () => false, camera: { - setView() {}, - flyTo() { - flights++; + setView(view) { + views.push(view); }, - cancelFlight() { - cancelled++; + flyTo() { + assert.fail('a start view is set, not flown to'); }, }, }); - stop(); - t.mock.timers.tick(1000); - assert.equal(flights, 0); - assert.equal(cancelled, 1); +} + +test('the camera starts over the whole planet, looking straight down', () => { + const views = []; + applyStartView(viewerRecording(views)); + assert.equal(views.length, 1); + assert.ok(START_VIEW.height >= 20000000, 'the whole planet is in view'); + assert.ok(Math.abs(views[0].orientation.pitch + Math.PI / 2) < 1e-9); + assert.equal(views[0].orientation.heading, 0); +}); + +test('a host can start the camera at a city instead', () => { + const views = []; + applyStartView(viewerRecording(views), { + lon: 2.35, + lat: 48.86, + height: 5000, + heading: 90, + pitch: -30, + }); + assert.equal(views.length, 1); + assert.ok(Math.abs(views[0].orientation.heading - Math.PI / 2) < 1e-9); + assert.ok(Math.abs(views[0].orientation.pitch + Math.PI / 6) < 1e-9); }); diff --git a/src/app/tools.js b/src/app/tools.js index 9da848c784..86c67ff791 100644 --- a/src/app/tools.js +++ b/src/app/tools.js @@ -1,3 +1,11 @@ +import { onFollowChanged } from '../data/followed.js'; +import { + bootStories, + stopVoiceForStories, + storiesOpener, +} from '../stories/boot.js'; +import { t } from '../i18n/index.js'; +import { useStoriesStore } from '../ui/stores/stories.js'; import { SceneDirector } from '../scenes/director.js'; import { initAnnotations } from '../annotations/index.js'; import { initDrawTool } from '../annotations/drawTool.js'; @@ -11,7 +19,13 @@ import { useDisplayStore } from '../ui/stores/display.js'; import { applicationPinia } from '../ui/vueRuntime.js'; import { initImageryBoxTool } from '../ui/imageryBoxTool.js'; import { createRecentImageryPanel } from '../ui/recentImagery.js'; +import { createDataLibrary } from '../library/controller.js'; +import { flyToLibraryExtent } from '../library/camera.js'; +import { createLibraryBrowser } from '../ui/libraryBrowser.js'; +import { useDataLibraryStore } from '../ui/stores/dataLibrary.js'; +import { localGeoJsonServices } from './localGeojsonServices.js'; import { initGevVoiceCommands } from '../voice/gevRealtime.js'; +import { isStoriesOpen } from '../voice/realtimeInputPolicy.js'; import { installViews, isEmbeddedInline } from './embed.js'; import { installScopeMask, @@ -19,17 +33,26 @@ import { isScopeMaskEnabled, } from '../scopeMask.js'; import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js'; -import { installGlobeInViewRecovery } from './viewer.js'; +import { installGlobeInViewRecovery } from './globeInViewRecovery.js'; import { installLayerReleaseTrim } from '../sceneCommandRelease.js'; import { - installRenderGovernor, getRenderGovernorDiagnostics, governorRequestRender, holdContinuousRender, releaseContinuousRender, } from '../renderGovernor.js'; +import { entityRecord, readEntityRecord } from '../data/entityRecords.js'; +import { overlayHost } from './layers/overlayHost.js'; -/** Attach scene tools, rendering listeners and the application debug handle. */ +/** + * Attach scene tools, rendering listeners and the application debug handle. + * `scene` is what `createApplicationScene` returns; its `trimStaleCommands` + * runs after each layer disable (a scene without one keeps that memory). + * `library.fetchTile` and `library.fetchData` fetch the Data Library's tiles + * and proxied datasets in place of the defaults (`createLibrarySource`). + * `library.requireCatalog` offers only what the server's library catalog + * names, and nothing while it does not answer. + */ export function createApplicationTools({ scene, controls, @@ -41,14 +64,15 @@ export function createApplicationTools({ onSceneDirector, sceneDataPacks, drawMarkActions = [], + library = {}, signal, defer, }) { - const { viewer, tileset, mapStackController, operations } = scene; + const { viewer, renderer, tileset, mapStackController, operations } = scene; const { styleManager, weatherEffects, cockpitCloudEffects } = controls; const { dataManager } = data; const sceneDirector = new SceneDirector(viewer, styleManager, dataManager, { - dataPacks: sceneDataPacks, + dataPacks: { overlayHost, ...sceneDataPacks }, isMapStackAvailable: (id) => mapStackController?.isStackAvailable(id) === true, }); @@ -65,6 +89,26 @@ export function createApplicationTools({ }), ); onSceneDirector?.(sceneDirector); + // Stories: GEV scenes on this globe, from a Stories button. Its screens, + // styles, story data and controller load on first use. + const storiesStore = useStoriesStore(applicationPinia()); + let voiceCommands; + const stories = bootStories({ + // Inline in a host page, the URL and history are the host's. + available: !isEmbeddedInline(), + viewer, + director: sceneDirector, + store: storiesStore, + onEnter: () => { + if (stopVoiceForStories(voiceCommands?.session)) + storiesStore.flashToast(t('Voice is disabled in Stories.'), 4000); + }, + onLoadFailed: () => + styleManager._showToast?.( + t('Stories could not load. Check the connection and try again.'), + ), + }); + defer(() => stories.destroy()); const annotations = initAnnotations({ viewer, tileset, @@ -109,6 +153,56 @@ export function createApplicationTools({ connect: connectDisplay, }); defer(() => geoFileImport?.destroy()); + // DATA ▸ Library: entries register their layers only when a viewer adds + // them, after the core catalog is sealed. The browser dialog and the + // controller share the application lifetime. + const dataLibrary = createDataLibrary({ + dataManager, + services: localGeoJsonServices, + getTileset: () => tileset, + mapStackController, + shareLink: styleManager.shareLinkManager, + requestRender: governorRequestRender, + // An application's own tile and dataset fetches, when it keeps them in + // its own cache. + fetchTile: library.fetchTile ?? null, + fetchData: library.fetchData ?? null, + requireCatalog: library.requireCatalog === true, + // Zoom to layer: an immediate navigation, so Cockpit can refuse it and + // the current follow owner is released first (as for imported files). + zoomTo: (extent) => + styleManager.runImmediateNavigation('layer', () => + flyToLibraryExtent(viewer, extent), + ) !== false, + }); + defer(() => dataLibrary.destroy()); + // Browse: the owner presents the dialog through the store; LayerPanelsView + // draws the Browse button and the dialog from it. + const libraryStore = useDataLibraryStore(applicationPinia()); + const libraryBrowser = createLibraryBrowser({ + library: dataLibrary, + publish: (view) => libraryStore.publish(view), + }); + libraryStore.connect(libraryBrowser.controls); + defer(() => { + libraryBrowser.destroy(); + libraryStore.connect(null); + }); + dataLibrary.start({ signal }).catch((error) => { + if (!signal?.aborted) console.warn('[Library] start failed:', error); + }); + // The live gate's handle (scripts/qa-data-library.mjs). + const libraryHandle = { + library: dataLibrary, + browser: libraryBrowser, + // What Copy Link would copy. + buildShareLink: () => styleManager.shareLinkManager?.buildLink?.() ?? null, + }; + window.__gevDataLibrary = libraryHandle; + defer(() => { + if (window.__gevDataLibrary === libraryHandle) + delete window.__gevDataLibrary; + }); // DATA ▸ Recent Imagery: the box tool claims the pointer like Draw and the // panel lives on the right rail, so both belong to the application // lifetime. The tileset lets the layer drape while the globe is hidden. @@ -148,19 +242,21 @@ export function createApplicationTools({ } if (startChrome) defer(startChrome({ loadingScreen, styleManager, dataManager, signal })); - // Idle render governor: flips the scene into requestRenderMode whenever - // nothing animates per frame. Installed AFTER every module above has had - // its chance to register pre-install holds. (perf wave 2) - installRenderGovernor(viewer); - // Cesium keeps a turned-off layer's draw commands (and so all its entities) - // alive in reused per-pass arrays; trim them after each disable. - defer( - installLayerReleaseTrim({ - scene: viewer.scene, - dataManager, - requestRender: governorRequestRender, - }), - ); + // Idle render governor: the loop draws on demand whenever nothing animates + // per frame. It goes idle only now, after every module above has had its + // chance to hold. (perf wave 2) + releaseContinuousRender('boot'); + // The renderer may keep a turned-off layer's draw commands (and so all its + // entities) alive; trim them after each disable. + if (scene.trimStaleCommands) + defer( + installLayerReleaseTrim({ + frame: renderer.frame, + dataManager, + requestRender: governorRequestRender, + trim: scene.trimStaleCommands, + }), + ); // Install the explicit scope mask used by the DISPLAY controls. installScopeMask(viewer); @@ -168,12 +264,10 @@ export function createApplicationTools({ // The follow camera recomputes the tracked target's dead-reckon position // every frame — tracking anything is a per-frame animation. (perf wave 2) - const removeTrackingListener = viewer.trackedEntityChanged.addEventListener( - () => { - if (viewer.trackedEntity) holdContinuousRender('tracked-entity'); - else releaseContinuousRender('tracked-entity'); - }, - ); + const removeTrackingListener = onFollowChanged(viewer, (followed) => { + if (followed) holdContinuousRender('tracked-entity'); + else releaseContinuousRender('tracked-entity'); + }); // Hidden-state suspension (perf wave 2): when the window/tab is hidden, // stop the default render loop outright — a hidden canvas repaints for @@ -182,9 +276,9 @@ export function createApplicationTools({ // the loop, refresh the one DOM surface we gated, render a frame. const syncVisibilitySuspension = () => { // A panel's host may report it hidden while it is on screen; the panel - // keeps drawing itself (see keepPanelRendering in embed.js). + // keeps drawing itself (see keepPanelRendering in app/panelRendering.js). const hidden = document.hidden && !isEmbeddedInline(); - viewer.useDefaultRenderLoop = !hidden; + renderer.frame.suspend(hidden); cockpitCloudEffects?.setSuspended?.(hidden); if (!hidden) { data.presentation.flushVisible(); @@ -204,26 +298,40 @@ export function createApplicationTools({ // loop burning behind a hidden tab. (perf wave 2 fix) syncVisibilitySuspension(); - window.__godsEyeView = { - viewer, - styleManager, - tileset, - dataManager, - sceneDirector, - mapStackController, - annotations, - weatherEffects, - cockpitCloudEffects, - getRenderGovernorDiagnostics, - surfaceServices: operations.surface, - requestRender: governorRequestRender, - }; + window.__godsEyeView = Object.defineProperties( + { + viewer, + styleManager, + tileset, + dataManager, + sceneDirector, + mapStackController, + annotations, + weatherEffects, + cockpitCloudEffects, + getRenderGovernorDiagnostics, + surfaceServices: operations.surface, + requestRender: governorRequestRender, + entityRecords: { read: readEntityRecord, write: entityRecord }, + }, + // What the renderer's plugin lets QA scripts read (the Cesium viewer and + // its photoreal tileset, for the default renderer), in place of the + // scene's objects above; read as they are when asked. + Object.getOwnPropertyDescriptors(scene.qaHandles ?? {}), + ); const debug = window.__godsEyeView; defer(() => { if (window.__godsEyeView === debug) delete window.__godsEyeView; }); - const voiceCommands = initGevVoiceCommands({ + voiceCommands = initGevVoiceCommands({ ...voice, + canStartVoice: () => !isStoriesOpen(), + // An app may supply what open_stories does; the Stories page by default. + openStories: storiesOpener({ + openStories: voice?.openStories, + store: storiesStore, + stories, + }), floorServices: operations.surface.groundFloor, annotationResolver: operations.annotationResolver, searchNavigation: operations.searchAndFlyTo, @@ -246,12 +354,16 @@ export function createApplicationTools({ shell: styleManager, viewer, dataManager, - run: (name, args) => voiceCommands.runner(name, args, { signal }), + run: (name, args, options = {}) => + voiceCommands.runner(name, args, { ...options, signal }), signal, + keepRendering: scene.keepPanelRendering, + terrain: operations.requests.terrain, }), ); - // An application's own tool takes the pointer as Draw does, and its own - // click handlers yield while a tool holds it, as the layers' do + // Any other tool takes the pointer as Draw does (the newest + // claim takes over; `claim(owner, {onLost})` tells the tool it replaces), + // and its own click handlers yield while a tool holds it, as the layers' do // (data/inputOwnership.js). return { sceneDirector, diff --git a/src/app/viewer.js b/src/app/viewer.js deleted file mode 100644 index e4288e8a3e..0000000000 --- a/src/app/viewer.js +++ /dev/null @@ -1,432 +0,0 @@ -import * as Cesium from 'cesium'; -import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js'; -import { StarrySky } from '../sky/starrySky.js'; -import { - FREE_LOOK_MAX_HEIGHT_METERS, - globeOutOfFrame, - isFreeGlobeCamera, -} from '../globeInView.js'; - -/** - * At the farthest a hand can zoom out, the globe is this share of the - * screen's height across. Cesium sets no limit, so zooming on left the globe - * a speck among the stars. - */ -const MIN_GLOBE_SHARE = 0.3; - -/** - * The farthest a hand can zoom out, in metres above the ellipsoid, for a - * vertical field of view. It follows the screen's shape, as the app's own - * whole-globe view does, so that view always lies within it. - * @param {number} fovy Vertical field of view, radians. - */ -export function zoomOutLimit(fovy) { - const radius = Cesium.Ellipsoid.WGS84.maximumRadius; - const angular = Math.atan(MIN_GLOBE_SHARE * Math.tan(fovy / 2)); - return radius / Math.sin(angular) - radius; -} - -/** - * Hold a hand's zoom out to `zoomOutLimit` on the globe, each frame, since the - * field of view follows the screen's shape. The limit never sits below the - * camera: one already past it (a flight, a screen turned) stops there rather - * than jumping in at the next zoom. Flat maps keep Cesium's own, unlimited. - * @returns {() => void} Stop limiting. - */ -export function limitZoomOut(viewer) { - const { scene, camera } = viewer; - return scene.preRender.addEventListener(() => { - const controller = scene.screenSpaceCameraController; - const fovy = camera.frustum.fovy; - if (scene.mode !== Cesium.SceneMode.SCENE3D || !Number.isFinite(fovy)) { - controller.maximumZoomDistance = Number.POSITIVE_INFINITY; - return; - } - controller.maximumZoomDistance = Math.max( - zoomOutLimit(fovy), - camera.positionCartographic?.height ?? 0, - ); - }); -} - -const PINCH_ZOOM_MULTIPLIER = 8; -const MAX_PINCH_PIXEL_DELTA = 120; - -function boundedPinchDelta(delta) { - if (!Number.isFinite(delta) || delta === 0) return delta; - return ( - Math.sign(delta) * - Math.min(Math.abs(delta) * PINCH_ZOOM_MULTIPLIER, MAX_PINCH_PIXEL_DELTA) - ); -} - -/** - * Add browser trackpad pinch to Cesium's zoom inputs and return its disposer. - * Browsers expose this gesture as a small pixel-mode Ctrl+wheel event. - */ -export function installTrackpadPinchZoom( - viewer, - { createWheelEvent = (type, init) => new WheelEvent(type, init) } = {}, -) { - const controller = viewer?.scene?.screenSpaceCameraController; - const container = viewer?.container; - const canvas = viewer?.canvas; - if (!controller || !container || !canvas) - throw new TypeError('A complete Cesium viewer is required'); - - const originalZoomEventTypes = controller.zoomEventTypes; - const zoomEventTypes = Array.isArray(originalZoomEventTypes) - ? originalZoomEventTypes - : originalZoomEventTypes === undefined - ? [] - : [originalZoomEventTypes]; - const alreadyHandlesControlWheel = zoomEventTypes.some( - (binding) => - binding?.eventType === Cesium.CameraEventType.WHEEL && - binding?.modifier === Cesium.KeyboardEventModifier.CTRL, - ); - const configuredZoomEventTypes = alreadyHandlesControlWheel - ? originalZoomEventTypes - : [ - ...zoomEventTypes, - { - eventType: Cesium.CameraEventType.WHEEL, - modifier: Cesium.KeyboardEventModifier.CTRL, - }, - ]; - if (!alreadyHandlesControlWheel) - controller.zoomEventTypes = configuredZoomEventTypes; - - const relayedEvents = new WeakSet(); - const relayPinch = (event) => { - if ( - !event.ctrlKey || - relayedEvents.has(event) || - event.deltaMode !== 0 || - !Number.isFinite(event.deltaY) || - event.deltaY === 0 - ) - return; - let relayed; - try { - relayed = createWheelEvent('wheel', { - deltaX: event.deltaX, - deltaY: boundedPinchDelta(event.deltaY), - deltaZ: event.deltaZ, - deltaMode: event.deltaMode, - screenX: event.screenX, - screenY: event.screenY, - clientX: event.clientX, - clientY: event.clientY, - ctrlKey: true, - bubbles: true, - cancelable: true, - view: globalThis.window, - }); - } catch { - // The registered Ctrl+wheel binding can still consume the original. - return; - } - relayedEvents.add(relayed); - event.preventDefault(); - event.stopPropagation(); - canvas.dispatchEvent(relayed); - }; - container.addEventListener('wheel', relayPinch, { - capture: true, - passive: false, - }); - - let active = true; - return () => { - if (!active) return; - active = false; - container.removeEventListener('wheel', relayPinch, true); - if ( - !alreadyHandlesControlWheel && - controller.zoomEventTypes === configuredZoomEventTypes - ) - controller.zoomEventTypes = originalZoomEventTypes; - }; -} - -/** - * Allow Cesium's free look only below `maxHeight` and return its disposer. - * Orbit, tilt and zoom stay available at every height. A value other code - * sets later is kept as the one to allow below that height, and restored on - * dispose; a `false` written while the camera is above `maxHeight` cannot be - * told apart from this limit's own write, so dispose restores the earlier - * value then. `enableLook` gates the Shift+drag binding only: below its trackball - * height Cesium also turns the camera in place for a drag that starts on the - * stars. That height is lowered to `maxHeight` too, so above it such a drag - * orbits the globe, as it does above Cesium's own 7,500 km. - */ -export function installFreeLookHeightLimit( - viewer, - maxHeight = FREE_LOOK_MAX_HEIGHT_METERS, -) { - const scene = viewer?.scene; - const controller = scene?.screenSpaceCameraController; - const camera = viewer?.camera; - if (!controller || !camera || !scene?.preUpdate) - throw new TypeError('A complete Cesium viewer is required'); - - const originalTrackBallHeight = controller.minimumTrackBallHeight; - const trackBallHeight = Math.min(originalTrackBallHeight, maxHeight); - controller.minimumTrackBallHeight = trackBallHeight; - let wanted = controller.enableLook; - let written; - const sync = () => { - if (written !== undefined && controller.enableLook !== written) - wanted = controller.enableLook; - const height = camera.positionCartographic?.height; - written = wanted && !(Number.isFinite(height) && height > maxHeight); - controller.enableLook = written; - }; - sync(); - const removeListener = scene.preUpdate.addEventListener(sync); - - let active = true; - return () => { - if (!active) return; - active = false; - removeListener(); - if (controller.enableLook === written) controller.enableLook = wanted; - if (controller.minimumTrackBallHeight === trackBallHeight) - controller.minimumTrackBallHeight = originalTrackBallHeight; - }; -} - -// How often a moving camera is sampled to see whether it has come to rest, how -// far a pose may drift between samples and still count as at rest, and how -// long after the camera last moved the check gives up if Cesium never raises -// moveEnd. -const SETTLE_SAMPLE_MS = 250; -const SETTLE_POSITION_TOLERANCE_M = 1e-3; -const SETTLE_DIRECTION_TOLERANCE = 1e-9; -const SETTLE_GIVE_UP_MS = 5 * 60_000; - -/** - * Turn the camera back to the planet when a move ends above `minHeight` with - * no surface on screen (`globeOutOfFrame`: limb glow and slivers up to about - * one sample cell thick can count as none), and return the disposer. Views with - * more surface, such as an oblique orbital shot, are left as they are. This - * catches a saved or shared view that looked away, or any other move that ends - * looking away from the planet. - * Heading and position are kept. Tracked cameras, locked ones (non-identity - * transform), a camera flight in progress, a pointer held down on the canvas - * (a drag held still), the 2D and Columbus modes, and any time `paused` - * returns true (an authored scene playing) are left alone; a check they defer - * runs once they end, however long they last. - * `keyholeRadius` - * returns the radius of the visible circle when a scope mask hides the rest of - * the frame (see `globeFrameShare`), or 0; it is read at every check. - * - * Cesium's `moveEnd` alone is not enough: Cesium compares the camera with the - * last frame's to the last rounding error, and at some of these poses the - * camera drifts by a rounding error every frame, so Cesium never sees it stop. - * So each `moveStart` also starts a check of its own that samples the pose - * every 250 ms, with a tolerance for that drift, and once the pose has held - * for half a second after moving runs the same recovery. It keeps watching - * until Cesium raises `moveEnd`, since under that drift Cesium raises no new - * `moveStart` for a later move, and gives up five minutes after the camera - * last moved. - * `setTimeout` and `clearTimeout` can be injected for tests. - */ -export function installGlobeInViewRecovery( - viewer, - { - minHeight = FREE_LOOK_MAX_HEIGHT_METERS, - keyholeRadius = () => 0, - paused = () => false, - setTimeout: schedule = globalThis.setTimeout, - clearTimeout: unschedule = globalThis.clearTimeout, - } = {}, -) { - const scene = viewer?.scene; - const camera = viewer?.camera; - if (!scene || !camera?.moveEnd || !camera?.moveStart) - throw new TypeError('A complete Cesium viewer is required'); - - // A pointer held on the globe is a gesture in progress, even when it holds - // still for half a second: the check waits until every pointer pressed on - // it (each finger of a pinch) is released. A release the page never sees, - // outside the window, is taken as given when the window loses focus, the - // page is hidden, the canvas loses the pointer's capture, or the pointer - // moves with no button down. - const canvas = scene.canvas; - const releaseTarget = canvas?.ownerDocument ?? canvas; - const releaseWindow = canvas?.ownerDocument?.defaultView; - const heldPointers = new Set(); - const onPointerDown = (event) => heldPointers.add(event?.pointerId); - const onPointerUp = (event) => heldPointers.delete(event?.pointerId); - const onPointerMove = (event) => { - if (event?.buttons === 0) heldPointers.delete(event.pointerId); - }; - const releaseAll = () => heldPointers.clear(); - const onVisibilityChange = () => { - if (canvas.ownerDocument.visibilityState === 'hidden') releaseAll(); - }; - const listeners = [ - [canvas, 'pointerdown', onPointerDown], - [canvas, 'lostpointercapture', onPointerUp], - [releaseTarget, 'pointerup', onPointerUp], - [releaseTarget, 'pointercancel', onPointerUp], - [releaseTarget, 'pointermove', onPointerMove], - [canvas?.ownerDocument, 'visibilitychange', onVisibilityChange], - [releaseWindow, 'blur', releaseAll], - ]; - for (const [target, type, listener] of listeners) - target?.addEventListener?.(type, listener); - - // Returns false while a flight, a paused scene or a held pointer defers the - // check, so the caller can try again once it ends. - const recover = () => { - if (!isFreeGlobeCamera(viewer)) return true; - // Cesium has no public running-flight flag. - if (camera._currentFlight || paused() || heldPointers.size > 0) - return false; - const height = camera.positionCartographic?.height; - if ( - !(height > minHeight) || - !globeOutOfFrame(camera, { keyholeRadius: keyholeRadius() }) - ) - return true; - camera.setView({ - orientation: { - heading: camera.heading, - pitch: -Cesium.Math.PI_OVER_TWO, - roll: 0, - }, - }); - scene.requestRender?.(); - return true; - }; - - const lastPosition = new Cesium.Cartesian3(); - const lastDirection = new Cesium.Cartesian3(); - let settleTimer = null; - let settleElapsed = 0; - let restingSamples = 0; - let movedSinceCheck = false; - const stopSettling = () => { - if (settleTimer !== null) unschedule(settleTimer); - settleTimer = null; - }; - const sample = () => { - settleTimer = null; - settleElapsed += SETTLE_SAMPLE_MS; - const atRest = - Cesium.Cartesian3.equalsEpsilon( - camera.positionWC, - lastPosition, - 0, - SETTLE_POSITION_TOLERANCE_M, - ) && - Cesium.Cartesian3.equalsEpsilon( - camera.directionWC, - lastDirection, - 0, - SETTLE_DIRECTION_TOLERANCE, - ); - restingSamples = atRest ? restingSamples + 1 : 0; - if (!atRest) { - movedSinceCheck = true; - settleElapsed = 0; - } - // Two quiet samples in a row after a move: at rest for half a second, as - // for moveEnd. - if (restingSamples >= 2 && movedSinceCheck) { - if (recover()) movedSinceCheck = false; - // A flight or a playing scene bounds its own deferral. - else settleElapsed = 0; - } - if (settleElapsed >= SETTLE_GIVE_UP_MS) return; - Cesium.Cartesian3.clone(camera.positionWC, lastPosition); - Cesium.Cartesian3.clone(camera.directionWC, lastDirection); - settleTimer = schedule(sample, SETTLE_SAMPLE_MS); - }; - const startSettling = () => { - stopSettling(); - settleElapsed = 0; - restingSamples = 0; - movedSinceCheck = true; - Cesium.Cartesian3.clone(camera.positionWC, lastPosition); - Cesium.Cartesian3.clone(camera.directionWC, lastDirection); - settleTimer = schedule(sample, SETTLE_SAMPLE_MS); - }; - const removeMoveEnd = camera.moveEnd.addEventListener(() => { - if (recover()) stopSettling(); - // Deferred: keep sampling so the check runs once the flight or scene ends. - else if (settleTimer === null) startSettling(); - }); - const removeMoveStart = camera.moveStart.addEventListener(startSettling); - - let active = true; - return () => { - if (!active) return; - active = false; - stopSettling(); - removeMoveEnd(); - removeMoveStart(); - for (const [target, type, listener] of listeners) - target?.removeEventListener?.(type, listener); - heldPointers.clear(); - }; -} - -/** Cesium.Viewer options of the standard globe viewer. */ -export function applicationViewerOptions(creditContainer) { - return { - timeline: false, - animation: false, - baseLayerPicker: false, - geocoder: false, - homeButton: false, - sceneModePicker: false, - navigationHelpButton: false, - fullscreenButton: false, - vrButton: false, - selectionIndicator: false, - infoBox: false, - baseLayer: false, - // Replaces the blocky Tycho-2 default. An option, not `skyBox: false`, - // which would also stop CesiumWidget from creating the Sun and Moon. - skyBox: new StarrySky(), - creditContainer, - msaaSamples: 4, - contextOptions: { webgl: { preserveDrawingBuffer: true } }, - }; -} - -/** Create the standard globe viewer in caller-owned, visible containers. */ -export function createApplicationViewer({ container, creditContainer }) { - if (!container || !creditContainer) - throw new TypeError('Viewer and credit containers are required'); - const viewer = new Cesium.Viewer( - container, - applicationViewerOptions(creditContainer), - ); - try { - viewer.targetFrameRate = 60; - // A phone pinch spans fewer screen pixels than desktop zoom gestures. - // Keep Cesium's distance-aware zoom and collision limits, with less travel - // required on touch-first screens. Mouse/trackpad sensitivity stays native. - if (globalThis.matchMedia?.('(pointer: coarse)').matches) - viewer.scene.screenSpaceCameraController.zoomFactor *= 3; - limitZoomOut(viewer); - // Before any tile builds a draw command: Cesium's per-vertex model - // atmosphere fails to LINK on Apple's Metal backend and kills the - // render loop. See app/atmosphereCompat.js. - applyModelAtmosphereWorkaround(viewer.scene); - viewer.scene.globe.show = false; - viewer.scene.skyAtmosphere.show = true; - viewer.scene.skyAtmosphere.atmosphereLightIntensity = 18; - viewer.scene.skyAtmosphere.saturationShift = -0.12; - viewer.scene.skyAtmosphere.brightnessShift = -0.08; - return viewer; - } catch (error) { - viewer.destroy(); - throw error; - } -} diff --git a/src/awarenessEcho.js b/src/awarenessEcho.js index 44a5e37fa7..c0f712543a 100644 --- a/src/awarenessEcho.js +++ b/src/awarenessEcho.js @@ -6,11 +6,12 @@ * awareness policy of its own: the publisher passes radius, pulse timing and * echo styling in, so the overlay never imports awareness internals. */ -import * as Cesium from 'cesium'; +import { scaleToGeodeticSurface } from './geo/ellipsoid.js'; +import { distance } from './geo/vector.js'; /** * @typedef {object} AwarenessEchoField - * @property {Cesium.Cartesian3} center Subject's ground point. The publisher + * @property {{x: number, y: number, z: number}} center Subject's ground point. The publisher * may move it in place; it is read on every query. * @property {number} radiusM Range the pulses grow to. * @property {{count: number, periodMs: number, startFraction: number, fadeInFraction?: number}} pulse @@ -22,7 +23,6 @@ import * as Cesium from 'cesium'; /** @type {AwarenessEchoField|null} */ let field = null; let layerIds = new Set(); -const groundScratch = new Cesium.Cartesian3(); /** * Start (or replace) the echo field. @@ -104,7 +104,7 @@ export function awarenessEchoStrength(nowMs, distanceM, radiusM, pulse, echo) { * field is set or the layer does not echo. Distance is measured between * ground points, so an aircraft's altitude does not shift its echo. * @param {string} layerId Owning layer of the contact. - * @param {Cesium.Cartesian3} position Contact's world position. + * @param {{x: number, y: number, z: number}} position Contact's world position. * @param {number} nowMs Monotonic clock in milliseconds. * @returns {number} 0 to 1. */ @@ -112,16 +112,13 @@ export function awarenessEchoAt(layerId, position, nowMs) { if (!field || !position || !layerIds.has(layerId)) return 0; const level = field.level?.(nowMs) ?? 1; if (!(level > 0)) return 0; - const ground = Cesium.Ellipsoid.WGS84.scaleToGeodeticSurface( - position, - groundScratch, - ); + const ground = scaleToGeodeticSurface(position); if (!ground) return 0; return ( level * awarenessEchoStrength( nowMs, - Cesium.Cartesian3.distance(field.center, ground), + distance(field.center, ground), field.radiusM, field.pulse, field.echo, @@ -138,7 +135,7 @@ export function awarenessEchoAt(layerId, position, nowMs) { * outside the contact's bracket, 0 as the front arrives, growing to the * field's `spreadPx` as it fades. * @param {string} layerId Owning layer of the contact. - * @param {Cesium.Cartesian3} position Contact's world position. + * @param {{x: number, y: number, z: number}} position Contact's world position. * @param {number} nowMs Monotonic clock in milliseconds. * @param {number} bracketAlpha The contact bracket's drawn alpha, 0 to 1. * @param {number} steps Alpha bands the overlay batches by. diff --git a/src/camera.js b/src/camera.js index 3fd49b58c0..57547071a2 100644 --- a/src/camera.js +++ b/src/camera.js @@ -1,36 +1,29 @@ -import * as Cesium from 'cesium'; +import { toRadians } from './geo/index.js'; +import { cameraOf } from './render/rendererOf.js'; /** - * Set camera to Austin on load with a cinematic fly-in. - * @returns {Function} Cancels the pending or active startup flight. + * The view the renderer starts from: the whole planet, looking straight + * down, centred where Cesium's default view rectangle is. */ -export function flyToAustin(viewer) { - // Start from a high altitude, then fly down - viewer.camera.setView({ - destination: Cesium.Cartesian3.fromDegrees(-97.7431, 30.2672, 25000), +export const START_VIEW = Object.freeze({ + lon: -82.5, + lat: 35, + height: 23000000, +}); + +/** + * Put the camera at a start view without a flight. A host may pass a city + * (`{ lon, lat, height, heading?, pitch? }`, angles in degrees) instead of + * the planet. + */ +export function applyStartView(viewer, view = START_VIEW) { + const { lon, lat, height, heading = 0, pitch = -90 } = view; + cameraOf(viewer).setView({ + destination: { lon, lat, height }, orientation: { - heading: Cesium.Math.toRadians(0), - pitch: Cesium.Math.toRadians(-90), - roll: 0.0, + heading: toRadians(heading), + pitch: toRadians(pitch), + roll: 0, }, }); - - // Cinematic fly-in after a brief pause - const timer = setTimeout(() => { - if (viewer.isDestroyed()) return; - viewer.camera.flyTo({ - destination: Cesium.Cartesian3.fromDegrees(-97.7431, 30.2672, 600), - orientation: { - heading: Cesium.Math.toRadians(15), - pitch: Cesium.Math.toRadians(-30), - roll: 0.0, - }, - duration: 4.0, - easingFunction: Cesium.EasingFunction.CUBIC_IN_OUT, - }); - }, 500); - return () => { - clearTimeout(timer); - if (!viewer.isDestroyed()) viewer.camera.cancelFlight(); - }; } diff --git a/src/cameraGlobeRotation.test.mjs b/src/cameraGlobeRotation.test.mjs index 8c3f20df23..1952f25e3e 100644 --- a/src/cameraGlobeRotation.test.mjs +++ b/src/cameraGlobeRotation.test.mjs @@ -1,3 +1,14 @@ +import { + bindFakeCesiumCamera, + followEntity, + followedEntity, +} from './testSupport/fakeCameraPort.mjs'; +import { rendererOf } from './render/rendererOf.js'; +import { followedOf } from './data/followed.js'; +import { + fakeSceneFrame, + fakeSceneQuery, +} from './testSupport/fakeCesiumScene.mjs'; import { GLOBE_VIEW } from './locations.js'; import { projectEarthDiscToViewport } from './celestialRing.js'; import assert from 'node:assert/strict'; @@ -13,11 +24,24 @@ import { moveCamera, } from './cameraVerbs.js'; import { getRenderGovernorDiagnostics } from './renderGovernor.js'; -import { - MIN_GLOBE_FRAME_SHARE, - globeFrameShare, - globeOutOfFrame, -} from './globeInView.js'; +import { MIN_GLOBE_FRAME_SHARE } from './globeInView.js'; +import * as globeInView from './globeInView.js'; + +// The frame measures take a camera pose; these read it off the real camera. +const framePose = (camera) => ({ + position: camera.positionWC, + direction: camera.directionWC, + up: camera.upWC, + right: camera.rightWC, + fovy: camera.frustum.fovy, + aspectRatio: camera.frustum.aspectRatio, + height: camera.positionCartographic.height, + pitch: camera.pitch, +}); +const globeFrameShare = (camera, options) => + globeInView.globeFrameShare(framePose(camera), options); +const globeOutOfFrame = (camera, options) => + globeInView.globeOutOfFrame(framePose(camera), options); import { KEYHOLE_OUTER_RADIUS } from './celestialRing.js'; import { setScopeMaskEnabled } from './scopeMask.js'; @@ -136,7 +160,7 @@ function harness( mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL, mode: Cesium.SceneMode.SCENE3D, pixelRatio: 1, - tweens: [], + preUpdate: new Cesium.Event(), requestRender() {}, }; const camera = new Cesium.Camera(scene); @@ -154,13 +178,37 @@ function harness( roll: radians(roll), }, }); - const viewer = { + const double = { camera, scene, - trackedEntity: undefined, + // Cesium's entity tracking, without entities of its own: the camera + // port follows on a tracking widget of the fake's. trackedEntityChanged: new Cesium.Event(), - clock: { onTick: new Cesium.Event() }, + entities: {}, }; + const viewer = bindFakeCesiumCamera(double, { + query: fakeSceneQuery(double), + frame: fakeSceneFrame(double), + }); + // Count who listens for the port's follow changes. + const renderer = rendererOf(viewer); + const port = renderer.camera; + let followListeners = 0; + renderer.camera = Object.create(port, { + on: { + value(event, cb, options) { + const off = port.on(event, cb, options); + if (event !== 'followChanged') return off; + followListeners += 1; + let live = true; + return () => { + if (live) followListeners -= 1; + live = false; + off(); + }; + }, + }, + }); const target = Cesium.Cartesian3.fromDegrees( longitudeDeg, latitude, @@ -174,73 +222,21 @@ function harness( }); const tick = (seconds = 0.1) => { nowMs += seconds * 1000; - viewer.clock.onTick.raiseEvent(viewer.clock); + viewer.scene.preUpdate.raiseEvent(viewer.scene); }; const finishOnce = () => { for (let i = 0; i < 20 && getActiveCameraMotion(); i += 1) tick(); assert.equal(getActiveCameraMotion(), null, 'once motion must finish'); }; - return { viewer, camera, canvas, target, tick, finishOnce }; -} - -for (const [name, sceneMode] of [ - ['2D', Cesium.SceneMode.SCENE2D], - ['Columbus', Cesium.SceneMode.COLUMBUS_VIEW], - ['morphing', Cesium.SceneMode.MORPHING], -]) { - test(`globe rotation refuses ${name} before changing the prior owner`, (t) => { - const { viewer, camera } = harness(t); - assert.equal( - moveCamera({ motion: 'rotate', direction: 'right', mode: 'continuous' }) - .ok, - true, - ); - const priorId = activeCameraMotionId(); - const before = pose(camera); - const transform = Cesium.Matrix4.clone(camera.transform); - viewer.scene.mode = sceneMode; - let handoffs = 0; - let cancellations = 0; - camera.cancelFlight = () => { - cancellations += 1; - }; - for (const mode of ['once', 'continuous']) { - const result = moveCamera( - { motion: 'rotate_globe', direction: 'left', mode }, - () => { - handoffs += 1; - return { ok: true }; - }, - ); - assert.equal(result.ok, false); - assert.match(result.error, /3D/); - } - assert.equal(handoffs, 0); - assert.equal(cancellations, 0); - assert.equal(activeCameraMotionId(), priorId); - assert.equal(hasRenderHold(), true); - assert.ok(Cesium.Matrix4.equals(camera.transform, transform)); - samePose(camera, before); - }); - - test(`active globe rotation yields to ${name} without changing the camera`, (t) => { - const { viewer, camera, tick } = harness(t); - assert.equal( - moveCamera({ motion: 'rotate_globe', mode: 'continuous' }).ok, - true, - ); - viewer.scene.mode = sceneMode; - const before = pose(camera); - let rotations = 0; - camera.rotate = () => { - rotations += 1; - }; - tick(); - assert.equal(rotations, 0); - assert.equal(getActiveCameraMotion(), null); - assert.equal(hasRenderHold(), false); - samePose(camera, before); - }); + return { + viewer, + camera, + canvas, + target, + tick, + finishOnce, + followListeners: () => followListeners, + }; } test('globe rotation yields to tracking acquired and cleared before the next tick', (t) => { @@ -251,15 +247,13 @@ test('globe rotation yields to tracking acquired and cleared before the next tic ); const before = pose(camera); const entity = { id: 'cockpit-aircraft', position: {} }; - viewer.trackedEntity = entity; - viewer.trackedEntityChanged.raiseEvent(entity); + followEntity(viewer, entity); assert.equal( getActiveCameraMotion(), null, 'tracking acquisition must synchronously yield', ); - viewer.trackedEntity = undefined; - viewer.trackedEntityChanged.raiseEvent(undefined); + followEntity(viewer, null); tick(); samePose(camera, before); assert.equal(hasRenderHold(), false); @@ -272,33 +266,34 @@ test('tracking event keeps legacy yaw and an untracked globe rotation active', ( true, ); const yawId = activeCameraMotionId(); - viewer.trackedEntityChanged.raiseEvent({ id: 'aircraft' }); + followEntity(viewer, { id: 'aircraft' }); assert.equal(activeCameraMotionId(), yawId); + followEntity(viewer, null); assert.equal( moveCamera({ motion: 'rotate_globe', mode: 'continuous' }).ok, true, ); const globeId = activeCameraMotionId(); - viewer.trackedEntityChanged.raiseEvent(undefined); + followEntity(viewer, null); assert.equal(activeCameraMotionId(), globeId); }); test('replaced viewer releases the old tracking listener without duplicate subscriptions', (t) => { const first = harness(t); - assert.equal(first.viewer.trackedEntityChanged.numberOfListeners, 1); + assert.equal(first.followListeners(), 1); initCameraVerbs(first.viewer); - assert.equal(first.viewer.trackedEntityChanged.numberOfListeners, 1); + assert.equal(first.followListeners(), 1); const next = harness(t); - assert.equal(first.viewer.trackedEntityChanged.numberOfListeners, 0); - assert.equal(next.viewer.trackedEntityChanged.numberOfListeners, 1); + assert.equal(first.followListeners(), 0); + assert.equal(next.followListeners(), 1); assert.equal( moveCamera({ motion: 'rotate_globe', mode: 'continuous' }).ok, true, ); const id = activeCameraMotionId(); - first.viewer.trackedEntityChanged.raiseEvent({ id: 'stale-aircraft' }); + followEntity(first.viewer, { id: 'stale-aircraft' }); assert.equal(activeCameraMotionId(), id); - next.viewer.trackedEntityChanged.raiseEvent({ id: 'new-aircraft' }); + followEntity(next.viewer, { id: 'new-aircraft' }); assert.equal(getActiveCameraMotion(), null); assert.equal(hasRenderHold(), false); }); @@ -534,7 +529,7 @@ test('replacement motion rejects a stale globe owner cancellation', (t) => { assert.equal(hasRenderHold(), false); }); -test('replacing the viewer retires globe motion and its old clock listener', (t) => { +test('replacing the viewer retires globe motion and its old frame listener', (t) => { const { viewer, camera, tick } = harness(t); assert.equal( moveCamera({ motion: 'rotate_globe', mode: 'continuous' }).ok, @@ -542,15 +537,16 @@ test('replacing the viewer retires globe motion and its old clock listener', (t) ); tick(); const before = pose(camera); - const nextViewer = { - ...viewer, - clock: { onTick: new Cesium.Event() }, - }; + const nextScene = { ...viewer.scene, preUpdate: new Cesium.Event() }; + const nextViewer = bindFakeCesiumCamera( + { ...viewer, scene: nextScene }, + { frame: fakeSceneFrame({ scene: nextScene }) }, + ); initCameraVerbs(nextViewer); assert.equal(getActiveCameraMotion(), null); assert.equal(hasRenderHold(), false); tick(); - nextViewer.clock.onTick.raiseEvent(nextViewer.clock); + nextScene.preUpdate.raiseEvent(nextScene); samePose(camera, before); }); @@ -580,7 +576,7 @@ for (const mode of ['once', 'continuous']) { tick(); assert.equal(hasRenderHold(), true); const tracked = { id: 'new-tracked-aircraft' }; - if (acquisition === 'tracking') viewer.trackedEntity = tracked; + if (acquisition === 'tracking') followEntity(viewer, tracked); else camera.lookAt( target, @@ -591,10 +587,9 @@ for (const mode of ['once', 'continuous']) { tick(); assert.equal(getActiveCameraMotion(), null); assert.equal(hasRenderHold(), false); - assert.equal( - viewer.trackedEntity, - acquisition === 'tracking' ? tracked : undefined, - ); + if (acquisition === 'tracking') + assert.equal(followedEntity(viewer), tracked); + else assert.equal(followedOf(viewer), null); assert.equal(Cesium.Matrix4.equals(camera.transform, transform), true); samePose(camera, before); tick(); @@ -605,7 +600,7 @@ for (const mode of ['once', 'continuous']) { test('direct globe rotation refuses a tracked camera without disturbing its reference frame', (t) => { const { viewer, camera, target } = harness(t); - viewer.trackedEntity = { id: 'tracked-aircraft' }; + followEntity(viewer, { id: 'tracked-aircraft', name: 'tracked-aircraft' }); camera.lookAt(target, new Cesium.HeadingPitchRange(0, radians(-40), 1_000)); const before = pose(camera); const transform = Cesium.Matrix4.clone(camera.transform); @@ -676,18 +671,19 @@ test('close-up refusal preserves an inherited target frame', (t) => { }); test('navigation callback never releases tracking for globe rotation', (t) => { const { viewer, camera } = harness(t); - const tracked = (viewer.trackedEntity = { id: 'tracked-aircraft' }); + const tracked = { id: 'tracked-aircraft' }; + followEntity(viewer, tracked); const before = pose(camera); let calls = 0; assert.equal( moveCamera({ motion: 'rotate_globe' }, () => { calls++; - viewer.trackedEntity = undefined; + followEntity(viewer, null); }).ok, false, ); assert.equal(calls, 0); - assert.equal(viewer.trackedEntity, tracked); + assert.equal(followedEntity(viewer), tracked); samePose(camera, before); }); test('direct globe request refuses Cockpit before navigation mutation', (t) => { @@ -878,8 +874,8 @@ for (const owner of ['tracking', 'cockpit', 'close-up']) height: owner === 'close-up' ? 5000 : GLOBE_VIEW.heightM, }); const before = pose(camera); - if (owner === 'tracking') viewer.trackedEntity = { id: 'tracked-aircraft' }; - const tracked = viewer.trackedEntity; + if (owner === 'tracking') followEntity(viewer, { id: 'tracked-aircraft' }); + const tracked = followedEntity(viewer); let releases = 0, stamps = 0; const styleManager = { @@ -893,7 +889,7 @@ for (const owner of ['tracking', 'cockpit', 'close-up']) }, release() { releases++; - viewer.trackedEntity = undefined; + followEntity(viewer, null); }, navigate, }); @@ -915,7 +911,7 @@ for (const owner of ['tracking', 'cockpit', 'close-up']) assert.equal(result.ok, false); assert.equal(releases, 0); assert.equal(stamps, 0); - assert.equal(viewer.trackedEntity, tracked); + assert.equal(followedEntity(viewer), tracked); samePose(camera, before); if (owner === 'close-up') { assert.equal(result.reason, 'globe-view-required'); @@ -926,29 +922,6 @@ for (const owner of ['tracking', 'cockpit', 'close-up']) } }); -for (const [label, ellipsoid] of [ - ['nonfinite radii', { minimumRadius: 1, maximumRadius: Infinity }], - ['nonpositive radii', { minimumRadius: 0, maximumRadius: 1 }], - ['non-WGS84 radii', new Cesium.Ellipsoid(30_000_000, 30_000_000, 1_000_000)], -]) - test(`globe rotation refuses ${label} before handoff`, (t) => { - const { viewer, camera } = harness(t, { height: 100_000_000 }); - const before = pose(camera); - viewer.scene.globe.ellipsoid = ellipsoid; - let handedOff = false; - const result = moveCamera({ motion: 'rotate_globe' }, () => { - handedOff = true; - }); - assert.equal(result.ok, false); - assert.equal( - result.reason, - label === 'non-WGS84 radii' ? 'unsupported-view' : 'unsafe-ellipsoid', - ); - assert.equal(handedOff, false); - assert.equal(hasRenderHold(), false); - samePose(camera, before); - }); - test('an external radius change retires globe rotation without another write', (t) => { const { camera, tick } = harness(t); moveCamera({ motion: 'rotate_globe', mode: 'continuous' }); @@ -960,16 +933,6 @@ test('an external radius change retires globe rotation without another write', ( samePose(camera, changed); }); -test('a non-WGS84 ellipsoid fails closed rather than borrowing the WGS84 silhouette', (t) => { - const ellipsoid = new Cesium.Ellipsoid(10_000_000, 10_000_000, 8_000_000); - const { camera } = harness(t, { ellipsoid, latitude: 60 }); - const before = pose(camera); - const result = moveCamera({ motion: 'rotate_globe' }); - assert.equal(result.ok, false); - assert.equal(result.reason, 'unsupported-view'); - samePose(camera, before); -}); - test('untouched polar framing permits repeated direction and speed changes below preset altitude', (t) => { const { camera, finishOnce, tick } = harness(t, { latitude: 90 }); const radius = Cesium.Cartesian3.magnitude(camera.positionWC); @@ -1874,7 +1837,7 @@ test('a voice turn reported as done turns at least the half degree its check pro /** Track an entity below `camera`, locking it into that entity's frame. */ function trackFrom(viewer, camera) { - viewer.trackedEntity = { id: 'high-satellite' }; + followEntity(viewer, { id: 'high-satellite' }); const below = Cesium.Cartesian3.fromDegrees(10, 20, 400_000); camera.lookAtTransform(Cesium.Transforms.eastNorthUpToFixedFrame(below)); } @@ -1900,7 +1863,7 @@ test('a voice turn that releases a tracked camera is checked as released', (t) = }); trackFrom(viewer, camera); const releaseThenRun = (start) => { - viewer.trackedEntity = undefined; + followEntity(viewer, null); camera.lookAtTransform(Cesium.Matrix4.IDENTITY); return start(); }; @@ -1941,14 +1904,14 @@ test('a refused voice turn leaves a tracked camera tracking', (t) => { for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60); } trackFrom(viewer, camera); - const tracked = viewer.trackedEntity; + const tracked = followedEntity(viewer); const transform = Cesium.Matrix4.clone(camera.transform); let released = false; const result = moveCamera( { motion: 'tilt', direction: 'up', mode: 'once' }, (start) => { released = true; - viewer.trackedEntity = undefined; + followEntity(viewer, null); camera.lookAtTransform(Cesium.Matrix4.IDENTITY); return start(); }, @@ -1957,7 +1920,7 @@ test('a refused voice turn leaves a tracked camera tracking', (t) => { assert.equal(result.ok, false, label); assert.match(result.error, /globe out of view/, label); assert.equal(released, false, label); - assert.equal(viewer.trackedEntity, tracked, label); + assert.equal(followedEntity(viewer), tracked, label); assert.ok(Cesium.Matrix4.equals(camera.transform, transform), label); } }); @@ -1988,27 +1951,6 @@ test('a turn proven at one position is checked again after a release moves the c assert.match(result.error, /globe out of view/); }); -test('the voice frame limit leaves Columbus view alone', (t) => { - // At its limit in 3D a further tilt up is refused; the same tilt in Columbus - // view is not limited by the frame. - withScope(t, false); - const { viewer, finishOnce } = harness(t, { - pitch: -80, - viewportWidth: 1600, - viewportHeight: 900, - }); - assert.equal( - moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok, - true, - ); - finishOnce(); - const refused = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }); - assert.match(refused.error || '', /globe out of view/); - viewer.scene.mode = Cesium.SceneMode.COLUMBUS_VIEW; - const result = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }); - assert.doesNotMatch(result.error || '', /globe out of view/); -}); - test('voice tilt below the free-look height is not limited by the frame', (t) => { const { camera, finishOnce } = harness(t, { height: 500_000, pitch: -60 }); const result = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }); diff --git a/src/cameraGroundGuard.js b/src/cameraGroundGuard.js index 3f9de0cabe..07c5431eaa 100644 --- a/src/cameraGroundGuard.js +++ b/src/cameraGroundGuard.js @@ -14,8 +14,11 @@ * lifts the eye if it sits below a usable clearance. Heading and pitch are * held, so the correction reads as the shot settling. */ -import * as Cesium from 'cesium'; +import { onFollowChanged } from './data/followed.js'; import { ownCameraArrival } from './data/cameraArrival.js'; +import { distance, dot, fromDegrees, toLonLatH } from './geo/index.js'; +import { heightsOf } from './queries/heights.js'; +import { canvasOf, findCamera } from './render/rendererOf.js'; /** Minimum eye height above the rendered surface for a usable view. */ export const MIN_EYE_CLEARANCE_M = 120; @@ -24,35 +27,79 @@ const GUARD_ATTEMPTS = 8; const GUARD_INTERVAL_MS = 600; /** Ignore sub-metre noise rather than nudging the camera forever. */ const GUARD_EPSILON_M = 2; - -const probeScratch = new Cesium.Cartographic(); +/** Eye travel (m) and turn (cosine) that mean another owner moved the camera. */ +const MOVED_M = 0.01; +const TURNED_COS = 1 - 1e-9; /** * Highest rendered surface across a few cells, with how many cells answered. * A cell whose tiles are not streamed yet contributes nothing. - * @param {Cesium.Scene} scene Live scene. + * @param {import('./queries/heights.js').HeightService|null} heights The + * scene's height service. * @param {Array<{lat: number, lon: number}>} cells Cells to probe. * @returns {{heightM: number, sampled: number}} Reading. */ -function sampleSurfaceM(scene, cells) { +function sampleSurfaceM(heights, cells) { let heightM = Number.NaN; let sampled = 0; - if (typeof scene?.sampleHeight !== 'function') return { heightM, sampled }; + if (!heights) return { heightM, sampled }; for (const cell of cells) { - try { - const height = scene.sampleHeight( - Cesium.Cartographic.fromDegrees(cell.lon, cell.lat, 0, probeScratch), - ); - if (!Number.isFinite(height)) continue; - sampled += 1; - heightM = Number.isFinite(heightM) ? Math.max(heightM, height) : height; - } catch { - /* tiles not ready for this cell */ - } + // A miss is a cell whose tiles are not ready. + const height = heights.now(cell); + if (!Number.isFinite(height)) continue; + sampled += 1; + heightM = Number.isFinite(heightM) ? Math.max(heightM, height) : height; } return { heightM, sampled }; } +/** + * The eye as the camera port poses it: where it is (from its position) and + * which way it looks; null when the pose cannot be read. + */ +function eyeOf(camera) { + try { + const pose = camera?.pose(); + const at = pose?.position && toLonLatH(pose.position); + if (!at || !pose.direction || !pose.up) return null; + return { ...pose, lon: at.lon, lat: at.lat, height: at.height }; + } catch { + return null; + } +} + +/** The eye's ground point (height 0), its height, and which way it looks. */ +function poseOf(eye) { + if (!eye) return null; + return { + ground: fromDegrees(eye.lon, eye.lat), + height: eye.height, + direction: { ...eye.direction }, + up: { ...eye.up }, + }; +} + +/** + * Whether another owner has moved the camera off `pose`: across the ground, + * down, or around. A pure rise is not one: the renderer's terrain collision + * lifts a buried eye straight up as tiles load, which is the case the guard + * exists for, so `pose` follows the highest eye seen and the guard keeps + * measuring. + */ +function moved(now, pose) { + if (!now) return true; + const ground = fromDegrees(now.lon, now.lat); + if ( + distance(ground, pose.ground) > MOVED_M || + now.height < pose.height - MOVED_M || + dot(now.direction, pose.direction) < TURNED_COS || + dot(now.up, pose.up) < TURNED_COS + ) + return true; + pose.height = Math.max(pose.height, now.height); + return false; +} + /** * How far the camera must rise to clear the ground, given a measured surface. * Pure so the policy is testable without a scene. @@ -76,9 +123,11 @@ export function groundClearanceDeficitM( * Watch an arrival and lift the camera once the real surface can be measured. * * Stops quietly on a clear view, exhausted attempts, the user taking the - * controls (pointer or wheel on the canvas), or `isStale()` reporting that a - * newer arrival owns the camera. - * @param {Cesium.Viewer} viewer Live viewer. + * controls (pointer or wheel on the canvas), `isStale()` reporting that a + * newer arrival owns the camera, or any other caller moving the camera or + * starting a flight in the meantime: the guard only ever corrects the pose it + * was started on. + * @param {object} viewer Live viewer. * @param {{lat: number, lon: number}} at Destination being framed. * @param {{clearanceM?: number, attempts?: number, intervalMs?: number, * isStale?: () => boolean, onLift?: (liftM: number) => void}} [options] @@ -92,12 +141,16 @@ export function guardCameraAboveGround(viewer, at, options = {}) { isStale = () => false, onLift = null, } = options; - if (!viewer?.scene || !Number.isFinite(at?.lat) || !Number.isFinite(at?.lon)) + if (!viewer || !Number.isFinite(at?.lat) || !Number.isFinite(at?.lon)) return () => {}; + // Without a readable pose the guard could not tell a later owner's move. + const arrival = poseOf(eyeOf(findCamera(viewer))); + if (!arrival) return () => {}; + let timer = null; let done = false; - const canvas = viewer.scene.canvas; + const canvas = canvasOf(viewer); const documentRef = canvas?.ownerDocument; const removers = []; let release = () => {}; @@ -112,32 +165,7 @@ export function guardCameraAboveGround(viewer, at, options = {}) { release(); }; release = ownCameraArrival(viewer, stop); - // Direct camera API callers (including duration-zero flights) must yield - // before moving the eye. Restore the exact method ownership on completion. - for (const name of [ - 'flyTo', - 'flyToBoundingSphere', - 'setView', - 'lookAt', - 'cancelFlight', - ]) { - const camera = viewer.camera; - const original = camera[name]; - if (typeof original !== 'function') continue; - const descriptor = Object.getOwnPropertyDescriptor(camera, name); - const wrapped = function (...args) { - stop(); - return original.apply(this, args); - }; - camera[name] = wrapped; - removers.push(() => { - if (camera[name] !== wrapped) return; - if (descriptor) Object.defineProperty(camera, name, descriptor); - else delete camera[name]; - }); - } - const removeTracking = viewer.trackedEntityChanged?.addEventListener(stop); - if (removeTracking) removers.push(removeTracking); + removers.push(onFollowChanged(viewer, stop)); documentRef?.addEventListener?.('keydown', stop, true); // A manual gesture ends the guard, as it interrupts camera motion elsewhere. for (const type of ['pointerdown', 'wheel']) @@ -147,40 +175,33 @@ export function guardCameraAboveGround(viewer, at, options = {}) { const attempt = () => { if (done) return; if (isStale() || viewer.isDestroyed?.()) return stop(); + const camera = findCamera(viewer); + const now = eyeOf(camera); + // Another caller owns the camera now; lifting would undo its move. + if (!camera || camera.flying || moved(now, arrival)) return stop(); remaining -= 1; - const camera = viewer.camera; - const carto = camera.positionCartographic; // The eye must clear both the framed target and the ground beneath it. - const below = { - lat: Cesium.Math.toDegrees(carto.latitude), - lon: Cesium.Math.toDegrees(carto.longitude), - }; - const { heightM, sampled } = sampleSurfaceM(viewer.scene, [ - { lat: at.lat, lon: at.lon }, - below, - ]); + const below = { lat: now.lat, lon: now.lon }; + const { heightM, sampled } = sampleSurfaceM( + viewer ? heightsOf(viewer) : null, + [{ lat: at.lat, lon: at.lon }, below], + ); if (sampled > 0 && Number.isFinite(heightM)) { - const deficit = groundClearanceDeficitM( - carto.height, - heightM, - clearanceM, - ); + const deficit = groundClearanceDeficitM(now.height, heightM, clearanceM); if (deficit > 0) { stop(); - camera.flyTo({ - destination: Cesium.Cartesian3.fromRadians( - carto.longitude, - carto.latitude, - carto.height + deficit, - ), - orientation: { - heading: camera.heading, - pitch: camera.pitch, - roll: camera.roll, + camera.flyTo( + { lon: now.lon, lat: now.lat, height: now.height + deficit }, + { + orientation: { + heading: now.heading, + pitch: now.pitch, + roll: now.roll, + }, + durationS: 0.9, + easing: 'cubicInOut', }, - duration: 0.9, - easingFunction: Cesium.EasingFunction.CUBIC_IN_OUT, - }); + ); try { onLift?.(deficit); } catch { diff --git a/src/cameraGroundGuard.test.mjs b/src/cameraGroundGuard.test.mjs index 5c8f530303..fb751ce2a3 100644 --- a/src/cameraGroundGuard.test.mjs +++ b/src/cameraGroundGuard.test.mjs @@ -3,6 +3,12 @@ // Arrival framing is computed before the destination's tiles exist, so it // works from a predicted ground height. The guard measures the real surface // after arrival and lifts the eye; these tests pin when it acts. +import { + bindFakeCesiumCamera, + followEntity, +} from './testSupport/fakeCameraPort.mjs'; +import { rendererOf } from './render/rendererOf.js'; +import { fakeSceneQuery } from './testSupport/fakeCesiumScene.mjs'; import { test } from 'node:test'; import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; @@ -47,24 +53,71 @@ test('the clearance frames a subject without turning into an overflight', () => assert.ok(MIN_EYE_CLEARANCE_M <= 250); }); -function fakeViewer({ cameraHeightM, surfaceM }) { +/** + * Count the listeners for `viewer`'s camera port follow changes, from now on. + * @returns {() => number} + */ +function countFollowListeners(viewer) { + const renderer = rendererOf(viewer); + const port = renderer.camera; + let listeners = 0; + renderer.camera = Object.create(port, { + on: { + value(event, cb, options) { + const off = port.on(event, cb, options); + if (event !== 'followChanged') return off; + listeners += 1; + let live = true; + return () => { + if (live) listeners -= 1; + live = false; + off(); + }; + }, + }, + }); + return () => listeners; +} + +function fakeViewer({ cameraHeightM, surfaceM, tracks = false }) { const flights = []; - const position = Cesium.Cartographic.fromDegrees(-97.7603, 30.3141, cameraHeightM); - return { + const position = Cesium.Cartographic.fromDegrees( + -97.7603, + 30.3141, + cameraHeightM, + ); + const viewer = { flights, scene: { canvas: null, + sampleHeightSupported: true, sampleHeight: (carto) => typeof surfaceM === 'function' ? surfaceM(carto) : surfaceM, }, camera: { positionCartographic: position, + positionWC: Cesium.Cartographic.toCartesian(position), + directionWC: new Cesium.Cartesian3(0, 0, -1), + upWC: new Cesium.Cartesian3(0, 1, 0), heading: 0.5, pitch: -0.55, roll: 0, - flyTo: (options) => flights.push(options), + // As Cesium does: a flight is under way until it completes. + _currentFlight: undefined, + flyTo(options) { + flights.push(options); + this._currentFlight = {}; + }, }, }; + // Cesium's entity tracking, without entities of its own: the camera + // port follows on a tracking widget of the fake's. + if (tracks) + Object.assign(viewer, { + trackedEntityChanged: new Cesium.Event(), + entities: {}, + }); + return bindFakeCesiumCamera(viewer, { query: fakeSceneQuery(viewer) }); } test('the guard lifts a buried arrival once the surface answers', async () => { @@ -104,7 +157,11 @@ test('the guard waits for streaming tiles and yields to a newer arrival', async test('the guard leaves a clear view untouched', async () => { const viewer = fakeViewer({ cameraHeightM: 400, surfaceM: 171 }); - guardCameraAboveGround(viewer, { lat: 30.3125, lon: -97.765 }, { intervalMs: 1 }); + guardCameraAboveGround( + viewer, + { lat: 30.3125, lon: -97.765 }, + { intervalMs: 1 }, + ); await new Promise((resolve) => setTimeout(resolve, 20)); assert.equal(viewer.flights.length, 0); }); @@ -116,39 +173,85 @@ import { LayerLifecycle } from './data/lifecycle.js'; function handoffFixture(t) { t.mock.timers.enable({ apis: ['setTimeout'] }); - const viewer = fakeViewer({ cameraHeightM: 172, surfaceM: 171 }); + const viewer = fakeViewer({ + cameraHeightM: 172, + surfaceM: 171, + tracks: true, + }); + const followListeners = countFollowListeners(viewer); viewer.scene.canvas = new EventTarget(); viewer.scene.canvas.ownerDocument = new EventTarget(); - viewer.trackedEntityChanged = new Cesium.Event(); viewer.camera.cancelFlight = () => {}; viewer.camera.lookAtTransform = () => {}; - viewer.camera.flyToBoundingSphere = () => {}; - viewer.camera.setView = () => {}; + viewer.camera.flyToBoundingSphere = function () { + this._currentFlight = {}; + }; + viewer.camera.setView = function () { + this.positionWC = Cesium.Cartesian3.add( + this.positionWC, + new Cesium.Cartesian3(0, 0, 50), + new Cesium.Cartesian3(), + ); + }; const originalFly = viewer.camera.flyTo; const navigation = new NavigationController({ viewer, - tracking: Object.fromEntries(['flightsLayer', 'militaryFlightsLayer', - 'satellitesLayer', 'aisLiveVesselsLayer', 'militaryAwarenessLayer', - 'rocketLaunchesLayer'].map((key) => [key, {}])), - cancelOrientation() {}, clearLocation() {}, cancelShareSelection() {}, - getDataManager() {}, interruptCameraMotion() {}, stopOrbit() {}, - isCockpitActive: () => false, showToast() {}, + tracking: Object.fromEntries( + [ + 'flightsLayer', + 'militaryFlightsLayer', + 'satellitesLayer', + 'aisLiveVesselsLayer', + 'militaryAwarenessLayer', + 'rocketLaunchesLayer', + ].map((key) => [key, {}]), + ), + cancelOrientation() {}, + clearLocation() {}, + cancelShareSelection() {}, + getDataManager() {}, + interruptCameraMotion() {}, + stopOrbit() {}, + isCockpitActive: () => false, + showToast() {}, }); guardCameraAboveGround(viewer, { lat: 30.3, lon: -97.7 }); - return { viewer, navigation, originalFly }; + return { viewer, navigation, originalFly, followListeners }; } -for (const handoff of ['Director', 'tracking', 'follow', 'keyboard', 'UI', - 'flyTo', 'flyToBoundingSphere', 'setView', 'layer-disable', 'layer-destroy', 'app-stop']) { +for (const handoff of [ + 'Director', + 'tracking', + 'follow', + 'keyboard', + 'UI', + 'flyTo', + 'flyToBoundingSphere', + 'setView', + 'layer-disable', + 'layer-destroy', + 'app-stop', +]) { test(`arrival guard relinquishes and removes hooks on ${handoff}`, async (t) => { - const { viewer, navigation, originalFly } = handoffFixture(t); + const { viewer, navigation, originalFly, followListeners } = + handoffFixture(t); + const methods = [ + 'flyTo', + 'flyToBoundingSphere', + 'setView', + 'lookAt', + 'cancelFlight', + ].map((name) => viewer.camera[name]); if (handoff === 'Director') { SceneDirector.prototype._claimCameraOwnership.call({ - viewer, styleManager: { runImmediateNavigation: (noun, fn) => - navigation._runExplicitNavigation(noun, fn) }, + viewer, + styleManager: { + runImmediateNavigation: (noun, fn) => + navigation._runExplicitNavigation(noun, fn), + }, }); } else if (handoff === 'tracking') { - viewer.trackedEntityChanged.raiseEvent({ id: 'contact' }); + followEntity(viewer, { id: 'contact' }); } else if (handoff === 'follow' || handoff === 'UI') { navigation._stampNavigation({ cancelPendingSelection: false }); } else if (handoff === 'keyboard') { @@ -156,16 +259,81 @@ for (const handoff of ['Director', 'tracking', 'follow', 'keyboard', 'UI', } else if (handoff === 'app-stop') navigation.stop(); else if (handoff.startsWith('layer-')) { const lifecycle = new LayerLifecycle(viewer); - lifecycle.register({ id: 'test', init() {}, enable() {}, disable() {}, destroy() {} }); + lifecycle.register({ + id: 'test', + init() {}, + enable() {}, + disable() {}, + destroy() {}, + }); await lifecycle.setEnabled('test', true); - if (handoff === 'layer-disable') await lifecycle.setEnabled('test', false); + if (handoff === 'layer-disable') + await lifecycle.setEnabled('test', false); else await lifecycle.destroyLayer('test'); } else viewer.camera[handoff]({}); + // A direct flyTo is itself one recorded flight; the guard adds none. const priorFlights = viewer.flights.length; t.mock.timers.tick(10000); - assert.equal(viewer.flights.length, priorFlights, 'the old probe cannot fly'); - assert.equal(viewer.camera.flyTo, originalFly, 'direct-call hook is removed'); - assert.equal(viewer.trackedEntityChanged.numberOfListeners, 0); + assert.equal( + viewer.flights.length, + priorFlights, + 'the old probe cannot fly', + ); + assert.equal(viewer.camera.flyTo, originalFly); + assert.deepEqual( + ['flyTo', 'flyToBoundingSphere', 'setView', 'lookAt', 'cancelFlight'].map( + (name) => viewer.camera[name], + ), + methods, + 'the guard never replaces camera methods', + ); + assert.equal(followListeners(), 0); navigation.destroy(); }); } + +test('the guard yields to a camera moved without any camera method', async () => { + const viewer = fakeViewer({ cameraHeightM: 172, surfaceM: 171 }); + guardCameraAboveGround( + viewer, + { lat: 30.3125, lon: -97.765 }, + { intervalMs: 5 }, + ); + // A cockpit or follow frame writes the pose directly. + viewer.camera.directionWC = new Cesium.Cartesian3(1, 0, 0); + await new Promise((resolve) => setTimeout(resolve, 20)); + assert.equal(viewer.flights.length, 0, 'the moved view is not corrected'); +}); + +test('Cesium lifting a buried eye straight up is not another owner', async () => { + const viewer = fakeViewer({ cameraHeightM: 104, surfaceM: 171 }); + guardCameraAboveGround( + viewer, + { lat: 30.3125, lon: -97.765 }, + { intervalMs: 5 }, + ); + // Terrain collision raises the eye to just above the loaded ground. + const raised = Cesium.Cartographic.fromDegrees(-97.7603, 30.3141, 172); + viewer.camera.positionCartographic = raised; + viewer.camera.positionWC = Cesium.Cartographic.toCartesian(raised); + await new Promise((resolve) => setTimeout(resolve, 30)); + assert.equal(viewer.flights.length, 1, 'the guard still lifts the eye'); + const lifted = Cesium.Cartographic.fromCartesian( + viewer.flights[0].destination, + ); + assert.ok(Math.abs(lifted.height - (171 + MIN_EYE_CLEARANCE_M)) < 0.5); +}); + +test('another owner lowering the eye is not corrected', async () => { + const viewer = fakeViewer({ cameraHeightM: 172, surfaceM: 171 }); + guardCameraAboveGround( + viewer, + { lat: 30.3125, lon: -97.765 }, + { intervalMs: 5 }, + ); + const lowered = Cesium.Cartographic.fromDegrees(-97.7603, 30.3141, 150); + viewer.camera.positionCartographic = lowered; + viewer.camera.positionWC = Cesium.Cartographic.toCartesian(lowered); + await new Promise((resolve) => setTimeout(resolve, 30)); + assert.equal(viewer.flights.length, 0); +}); diff --git a/src/cameraHandoff.test.mjs b/src/cameraHandoff.test.mjs index 1c41139c8a..747a2f0a97 100644 --- a/src/cameraHandoff.test.mjs +++ b/src/cameraHandoff.test.mjs @@ -44,8 +44,8 @@ test('Cockpit takeover invalidates deferred work before camera cancellation', () ordered(enter, [ 'if (!info || (!vessel && !satellite && !entity?.position)) return false;', 'this.onCameraTakeover?.();', - 'this.viewer.camera.cancelFlight();', - 'this.viewer.trackedEntity = undefined;', + 'cameraOf(this.viewer).cancelFlight();', + 'stopFollowing(this.viewer);', ], 'Cockpit takeover'); assert.match( ui, @@ -97,7 +97,7 @@ test('voice Cockpit entry reaches the camera only through stamping seams', () => // The transaction has exactly two camera-owner mutations, and each one // stamps: // 1. selectedLayer.trackById(id) -> viewer.trackedEntity - // -> viewer.trackedEntityChanged -> _stampNavigation() + // -> onFollowChanged(viewer) -> _stampNavigation() // 2. cockpitView.enter() -> onCameraTakeover() -> _stampNavigation() const transaction = body( cockpitTracking, @@ -118,7 +118,7 @@ test('voice Cockpit entry reaches the camera only through stamping seams', () => // Seam 1: any tracker handoff stamps, so the adoption step is covered. assert.match( ui, - /viewer\.trackedEntityChanged\.addEventListener\(\s*\(entity\) => \{\s*if \(entity && !this\._disposed\)\s*this\._stampNavigation\(\{\s*cancelPendingSelection: false,?\s*\}\);/, + /onFollowChanged\(\s*this\.viewer,\s*\(followed\) => \{\s*if \(followed && !this\._disposed\)\s*this\._stampNavigation\(\{\s*cancelPendingSelection: false,?\s*\}\);/, 'tracker handoff must stamp', ); // Seam 2 is pinned by "Cockpit takeover invalidates deferred work" above. @@ -191,10 +191,10 @@ test('accepted navigation releases through PR15-aware ownership before flight', 'origin: trackingOrigin', 'satellitesLayer.stopTracking?.({ origin: trackingOrigin })', 'rocketLaunchesLayer.releaseCameraOwnership?.()', - 'this.viewer.trackedEntity = undefined;', + 'stopFollowing(this.viewer);', "interruptCameraMotion('explicit-navigation')", - 'this.viewer.camera.cancelFlight();', - 'this.viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);', + 'camera?.cancelFlight();', + 'camera?.release();', ], 'follow release'); assert.match(release, /flightsLayer\.stopTracking\?\.\(\{ origin: trackingOrigin \}\)/); assert.match(release, /militaryFlightsLayer\.stopTracking\?\.\(\{ origin: trackingOrigin \}\)/); @@ -282,11 +282,11 @@ test('a direct globe gesture retires delayed camera and selection restore only', ); assert.match( ui, - /viewer\?\.canvas\?\.addEventListener\(\s*'pointerdown',\s*this\._initialShareGestureHandler/, + /canvasOf\(this\.viewer\)\?\.addEventListener\(\s*'pointerdown',\s*this\._initialShareGestureHandler/, ); assert.match( ui, - /viewer\?\.canvas\?\.addEventListener\(\s*'wheel',\s*this\._initialShareGestureHandler/, + /canvasOf\(this\.viewer\)\?\.addEventListener\(\s*'wheel',\s*this\._initialShareGestureHandler/, ); assert.match( ui, @@ -399,7 +399,7 @@ test('vessel and fire layers announce valid clicks and never fly cameras', () => } const vesselClick = body( vessels, - /handler\.setInputAction\(\s*\(click\) => \{([\s\S]*?)\n\s*\},\s*Cesium\.ScreenSpaceEventType\.LEFT_CLICK,?\s*\);/, + /inputFor\(viewer\)\.onClick\(\(event\) => \{([\s\S]*?)\n \}\);/, 'vessel click', ); ordered(vesselClick, [ @@ -415,7 +415,7 @@ test('vessel and fire layers announce valid clicks and never fly cameras', () => assert.match(vesselFocus, /requestWorldFocus\(\{/); const fireClick = body( firms, - /_clickHandler\.setInputAction\(\(click\) => \{([\s\S]*?)\n \}, Cesium\.ScreenSpaceEventType\.LEFT_CLICK\);/, + /input\.onClick\(\(event\) => \{([\s\S]*?)\n \}\);/, 'fire click', ); ordered(fireClick, [ diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs index 8a3d1447f0..cac0d7e14f 100644 --- a/src/cameraTilt.test.mjs +++ b/src/cameraTilt.test.mjs @@ -9,6 +9,14 @@ import { moveCamera, } from './cameraVerbs.js'; import { createGevActionRunner } from './voice/gevActions.js'; +import { + bindFakeCesiumCamera, + followEntity, +} from './testSupport/fakeCameraPort.mjs'; +import { + fakeSceneFrame, + fakeSceneQuery, +} from './testSupport/fakeCesiumScene.mjs'; const radians = Cesium.Math.toRadians; const degrees = Cesium.Math.toDegrees; @@ -39,6 +47,7 @@ function harness( mode: Cesium.SceneMode.SCENE3D, pixelRatio: 1, tweens: [], + preUpdate: new Cesium.Event(), requestRender() {}, }; const camera = new Cesium.Camera(scene); @@ -47,13 +56,21 @@ function harness( destination: Cesium.Cartesian3.fromDegrees(-0.1276, 51.5072, height), orientation: { heading: radians(heading), pitch: radians(pitch), roll: 0 }, }); - const viewer = { + const double = { camera, scene, - trackedEntity: undefined, + // Cesium's entity tracking, without entities of its own: the camera + // port follows on a tracking widget of the fake's. trackedEntityChanged: new Cesium.Event(), + entities: {}, clock: { onTick: new Cesium.Event() }, }; + // The Cesium renderer's own camera port over the real camera; frames from + // the scene's preUpdate. + const viewer = bindFakeCesiumCamera(double, { + query: fakeSceneQuery(double), + frame: fakeSceneFrame(double), + }); // The app's view target: the ground point under the screen centre. const viewTarget = () => { const ray = new Cesium.Ray(camera.positionWC, camera.directionWC); @@ -68,7 +85,7 @@ function harness( }); const tick = (seconds = 1 / 30) => { nowMs += seconds * 1000; - viewer.clock.onTick.raiseEvent(viewer.clock); + viewer.scene.preUpdate.raiseEvent(viewer.scene); }; const finish = () => { for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick(); @@ -239,9 +256,7 @@ test('a pivoting tilt yields when tracking takes the camera', (t) => { const h = harness(t); assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true); h.tick(); - const entity = { id: 'tracked' }; - h.viewer.trackedEntity = entity; - h.viewer.trackedEntityChanged.raiseEvent(entity); + followEntity(h.viewer, { id: 'tracked' }); assert.equal(getActiveCameraMotion(), null); }); @@ -548,10 +563,10 @@ test('a regional tilt-up nudge goes to the camera horizon limit', (t) => { test('a voice tilt from a tracked view judges its limit from the camera pitch', (t) => { const h = harness(t, { height: 20000, pitch: -5.2 }); - h.viewer.trackedEntity = { id: 'tracked' }; + followEntity(h.viewer, { id: 'tracked' }); // Voice releases the follow camera before the motion starts. const release = (start) => { - h.viewer.trackedEntity = undefined; + followEntity(h.viewer, null); return start(); }; const result = moveCamera({ motion: 'tilt', direction: 'up' }, release); diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js index 5ac86bc365..ce61912b88 100644 --- a/src/cameraVerbs.js +++ b/src/cameraVerbs.js @@ -18,13 +18,14 @@ * globe motion, opposite to the camera's travel around Earth. */ -import * as Cesium from 'cesium'; +import { followedOf, isFollowing, onFollowChanged } from './data/followed.js'; import { GLOBE_VIEW } from './locations.js'; import { globeFrameShare, isFreeGlobeCamera, lookAngleWithinFrame, lookStepLosesGlobe, + lookedPose, } from './globeInView.js'; import { projectEarthDiscToViewport, @@ -37,6 +38,43 @@ import { holdContinuousRender, releaseContinuousRender, } from './renderGovernor.js'; +import { + PI_OVER_TWO, + WGS84, + add, + clamp, + cross, + distance, + dot, + eastNorthUp, + framePoint, + fromAxisAngle, + fromDegrees, + fromRadians, + frameVector, + geodeticSurfaceNormal, + headingPitchRollFrame, + inverseFramePoint, + lerpInto, + magnitude, + negativePiToPi, + normalize, + scale, + sub, + toAxes, + toCartographicRadians, + toDegrees, + toRadians, + vec, +} from './geo/index.js'; +import { eyeMoved, eyeRotatedAbout, eyeTurned } from './geo/eyeMoves.js'; +import { heightsOf } from './queries/heights.js'; +import { + cameraOf, + canvasOf, + findCamera, + findFrame, +} from './render/rendererOf.js'; let _isCockpitActive = null; /** °/s by speed word — orbit; pan uses fractions of view height/s. */ @@ -54,8 +92,8 @@ const ONCE = { panViewFraction: 0.25, durationS: 0.9, }; -const PITCH_MIN = Cesium.Math.toRadians(-89); -const PITCH_MAX = Cesium.Math.toRadians(-5); +const PITCH_MIN = toRadians(-89); +const PITCH_MAX = toRadians(-5); /** A bare "tilt the camera" / "oblique view" settles here. */ const TILT_DEFAULT_PITCH_DEG = -45; /** °/s for a tilt to a requested angle; short ones keep the once duration. */ @@ -82,7 +120,7 @@ const TILT_PIVOT_RANGE_SLACK_M = 1; * place's horizon; tilting the rest in place there would lift the crosshair * onto the sky, so the swing stops with the place this far above it. */ -const TILT_MIN_PIVOT_ELEVATION = Cesium.Math.toRadians(0.5); +const TILT_MIN_PIVOT_ELEVATION = toRadians(0.5); /* ── Route dolly: cinematic tuning ────────────────────────────────────────── * Every knob an owner may want to retune lives in this block. The shaping is @@ -341,30 +379,30 @@ export const ROUTE_CINEMA = Object.freeze({ /* ── Route dolly geometry ────────────────────────────────────────────────── */ -const _arcA = new Cesium.Cartesian3(); -const _arcB = new Cesium.Cartesian3(); -const _chordVertical = new Cesium.Cartesian3(); -const _turnCross = new Cesium.Cartesian3(); -const _framePos = new Cesium.Cartesian3(); -const _frameAheadPos = new Cesium.Cartesian3(); -const _frameUp = new Cesium.Cartesian3(); -const _frameIn = new Cesium.Cartesian3(); -const _frameOut = new Cesium.Cartesian3(); -const _frameGaze = new Cesium.Cartesian3(); -const _frameRight = new Cesium.Cartesian3(); -const _frameLevelUp = new Cesium.Cartesian3(); -const _frameDir = new Cesium.Cartesian3(); -const _frameEye = new Cesium.Cartesian3(); -const _frameBankedUp = new Cesium.Cartesian3(); -const _frameCarto = new Cesium.Cartographic(); -const _frameAheadCarto = new Cesium.Cartographic(); -const _bankQuat = new Cesium.Quaternion(); -const _bankMatrix = new Cesium.Matrix3(); -const _headingQuat = new Cesium.Quaternion(); -const _headingMatrix = new Cesium.Matrix3(); -const _warmPos = new Cesium.Cartesian3(); -const _warmCarto = new Cesium.Cartographic(); -const _probeCarto = new Cesium.Cartographic(); +/** Scratch points for the per-frame arc reads. */ +const _arcA = vec(); +const _arcB = vec(); +const _framePos = vec(); +const _frameAheadPos = vec(); +const _warmPos = vec(); + +/** `v` turned by `angle` radians about `axis`: quaternion, then its axes. */ +const rotateAbout = (v, axis, angle) => + frameVector(toAxes(fromAxisAngle(axis, angle)), v); + +/** `v` less its part along unit `up`. */ +function horizontalPart(v, up) { + const along = dot(v, up); + return vec(v.x - up.x * along, v.y - up.y * along, v.z - up.z * along); +} + +/** The ellipsoid's unit normal at geodetic `lon`, `lat` (radians). */ +function surfaceNormal(lon, lat) { + const cosLat = Math.cos(lat); + return normalize( + vec(cosLat * Math.cos(lon), cosLat * Math.sin(lon), Math.sin(lat)), + ); +} /** Point at arc length `s` along the polyline (binary search — queries jump * backwards for the inbound chord, so a forward cursor would not do). */ @@ -381,23 +419,17 @@ function arcPoint(state, s, result) { const segLen = cumM[lo + 1] - cumM[lo]; const t = segLen > 1e-6 ? Math.min(1, Math.max(0, (clamped - cumM[lo]) / segLen)) : 0; - return Cesium.Cartesian3.lerp(pts[lo], pts[lo + 1], t, result); + return lerpInto(pts[lo], pts[lo + 1], t, result); } /** Unit horizontal direction from arc `sA` to arc `sB`, or null when degenerate. */ -function horizontalChord(state, sA, sB, up, result) { +function horizontalChord(state, sA, sB, up) { const a = arcPoint(state, sA, _arcA); const b = arcPoint(state, sB, _arcB); - Cesium.Cartesian3.subtract(b, a, result); - const vertical = Cesium.Cartesian3.multiplyByScalar( - up, - Cesium.Cartesian3.dot(result, up), - _chordVertical, - ); - Cesium.Cartesian3.subtract(result, vertical, result); - const len = Cesium.Cartesian3.magnitude(result); + const horizontal = horizontalPart(vec(b.x - a.x, b.y - a.y, b.z - a.z), up); + const len = magnitude(horizontal); if (!(len > 1e-3)) return null; - return Cesium.Cartesian3.divideByScalar(result, len, result); + return vec(horizontal.x / len, horizontal.y / len, horizontal.z / len); } /** @@ -407,15 +439,14 @@ function horizontalChord(state, sA, sB, up, result) { * floating-point signed zeros, so an out-and-back route would flip the bank * direction frame to frame. A U-turn is resolved as a RIGHT turn, always — * arbitrary, but deterministic, which is the property that matters. - * @param {Cesium.Cartesian3} a Unit horizontal direction turned FROM. - * @param {Cesium.Cartesian3} b Unit horizontal direction turned TO. - * @param {Cesium.Cartesian3} up Local up, the axis the turn is measured about. + * @param {{x: number, y: number, z: number}} a Unit horizontal direction turned FROM. + * @param {{x: number, y: number, z: number}} b Unit horizontal direction turned TO. + * @param {{x: number, y: number, z: number}} up Local up, the axis the turn is measured about. * @returns {number} Radians, + = right. */ export function signedTurnRad(a, b, up) { - const cross = Cesium.Cartesian3.cross(a, b, _turnCross); - const sinLeft = Cesium.Cartesian3.dot(cross, up); - const cosTurn = Cesium.Cartesian3.dot(a, b); + const sinLeft = dot(cross(a, b), up); + const cosTurn = dot(a, b); if (cosTurn <= -1 + ANTIPODAL_EPS && Math.abs(sinLeft) < ANTIPODAL_EPS) return Math.PI; return -Math.atan2(sinLeft, cosTurn); @@ -447,14 +478,9 @@ export function routeCorridorCells( s <= end + 1e-6 && out.length < maxCells; s += ROUTE_WARM_STEP_M ) { - const point = arcPoint(state, s, _warmPos); - const carto = Cesium.Cartographic.fromCartesian( - point, - Cesium.Ellipsoid.WGS84, - _warmCarto, - ); - const lat = Number(Cesium.Math.toDegrees(carto.latitude).toFixed(3)); - const lon = Number(Cesium.Math.toDegrees(carto.longitude).toFixed(3)); + const carto = toCartographicRadians(arcPoint(state, s, _warmPos)); + const lat = Number(toDegrees(carto.lat).toFixed(3)); + const lon = Number(toDegrees(carto.lon).toFixed(3)); const key = `${lat},${lon}`; if (seen.has(key)) continue; seen.add(key); @@ -587,32 +613,24 @@ function acquireCorridorFloor(state, takeWhole) { * Highest rendered surface across a handful of corridor cells, with the number * of cells that actually answered — a cell whose tiles are not streamed yet * contributes nothing, and the caller must not mistake silence for flat ground. - * @param {Cesium.Scene|undefined} scene The live scene. + * @param {object|undefined} viewer The live scene object, asked through its + * renderer's heights (`heightsOf`). * @param {Array<{lat: number, lon: number}>} cells Cells to probe. * @returns {{heightM: number, sampled: number, requested: number}} The reading. */ -export function probeMeshFloorM(scene, cells) { +export function probeMeshFloorM(viewer, cells) { const requested = Array.isArray(cells) ? cells.length : 0; const empty = { heightM: Number.NaN, sampled: 0, requested }; - if (!scene || typeof scene.sampleHeight !== 'function' || !requested) - return empty; + if (!viewer || !requested) return empty; + const heights = heightsOf(viewer); let heightM = Number.NaN; let sampled = 0; for (const cell of cells) { - try { - const carto = Cesium.Cartographic.fromDegrees( - cell.lon, - cell.lat, - 0, - _probeCarto, - ); - const height = scene.sampleHeight(carto); - if (!Number.isFinite(height)) continue; - sampled += 1; - heightM = Number.isFinite(heightM) ? Math.max(heightM, height) : height; - } catch { - /* tiles not ready for this cell */ - } + // A miss is a cell whose tiles are not ready. + const height = heights.now({ lon: cell.lon, lat: cell.lat }); + if (height === null) continue; + sampled += 1; + heightM = Number.isFinite(heightM) ? Math.max(heightM, height) : height; } return { heightM, sampled, requested }; } @@ -620,7 +638,8 @@ export function probeMeshFloorM(scene, cells) { /** * Build the state for one cinematic route flight. * @param {Object} options - * @param {Cesium.Cartesian3[]} options.pts Route vertices. + * @param {Array<{x: number, y: number, z: number}>} options.pts Route + * vertices, ECEF. * @param {number[]} options.cumM Cumulative arc length per vertex. * @param {string} [options.speed] slow | normal | fast. * @param {Function|null} [options.floorFn] (latDeg, lonDeg) => floor metres. @@ -649,11 +668,7 @@ export function createRouteFlight({ // the mean: routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly slower // than asked. Those are shorter than the camera is tall — nothing to see. const durationS = Math.max(0.5, totalM / cruiseMps); - const pathHeightM = Cesium.Cartographic.fromCartesian( - pts[0], - Cesium.Ellipsoid.WGS84, - _warmCarto, - ).height; + const pathHeightM = toCartographicRadians(pts[0]).height; const state = { kind: 'route', mode: 'continuous', @@ -712,8 +727,8 @@ export function createRouteFlight({ * the viewer (so this stays testable without one). * @param {Object} state From createRouteFlight(). * @param {number} dt Seconds elapsed. - * @returns {{finished: boolean, eye: Cesium.Cartesian3, direction: Cesium.Cartesian3, - * up: Cesium.Cartesian3, bankDeg: number, heightM: number, aglM: number, + * @returns {{finished: boolean, eye: Object, direction: Object, + * up: Object, bankDeg: number, heightM: number, aglM: number, * groundSpeedMps: number, progress: number}} The frame. */ export function advanceRouteFlight(state, dt) { @@ -747,37 +762,17 @@ export function advanceRouteFlight(state, dt) { state.groundSpeedMps = cruiseMps * profile.speed; const pos = arcPoint(state, traveled, _framePos); - const carto = Cesium.Cartographic.fromCartesian( - pos, - Cesium.Ellipsoid.WGS84, - _frameCarto, - ); - const up = Cesium.Ellipsoid.WGS84.geodeticSurfaceNormalCartographic( - carto, - _frameUp, - ); + const carto = toCartographicRadians(pos); + const up = surfaceNormal(carto.lon, carto.lat); // Planned turn: compare where we came from with where we are going, over a // window centred on the camera. Peaks AT the corner, tapers either side. const halfWindowM = Math.max(20, (ROUTE_BANK_WINDOW_S * cruiseMps) / 2); - const inbound = horizontalChord( - state, - traveled - halfWindowM, - traveled, - up, - _frameIn, - ); - const outbound = horizontalChord( - state, - traveled, - traveled + halfWindowM, - up, - _frameOut, - ); + const inbound = horizontalChord(state, traveled - halfWindowM, traveled, up); + const outbound = horizontalChord(state, traveled, traveled + halfWindowM, up); const turnRateDegS = inbound && outbound - ? Cesium.Math.toDegrees(signedTurnRad(inbound, outbound, up)) / - ROUTE_BANK_WINDOW_S + ? toDegrees(signedTurnRad(inbound, outbound, up)) / ROUTE_BANK_WINDOW_S : 0; const bankTarget = routeBankTargetDeg(turnRateDegS, state.reducedMotion); state.bankLeadDeg = approachValue( @@ -805,11 +800,10 @@ export function advanceRouteFlight(state, dt) { Math.max(ROUTE_LOOKAHEAD_MIN_M, ROUTE_LOOKAHEAD_S * cruiseMps), ); const gaze = - horizontalChord(state, traveled, traveled + lookaheadM, up, _frameGaze) || + horizontalChord(state, traveled, traveled + lookaheadM, up) || outbound || inbound; - if (gaze && !state.headingDir) - state.headingDir = Cesium.Cartesian3.clone(gaze); + if (gaze && !state.headingDir) state.headingDir = vec(gaze.x, gaze.y, gaze.z); else if (gaze) { // Rotate the heading TOWARD the gaze about the local up, rather than // lerping the two vectors. A Cartesian lerp cannot cross an antipodal pair @@ -820,67 +814,34 @@ export function advanceRouteFlight(state, dt) { const turnToGaze = signedTurnRad(state.headingDir, gaze, up); // signedTurnRad is + for a RIGHT turn; a positive rotation about up is a // LEFT turn, so the step is negated. - const rotation = Cesium.Matrix3.fromQuaternion( - Cesium.Quaternion.fromAxisAngle(up, -turnToGaze * k, _headingQuat), - _headingMatrix, - ); - const turned = Cesium.Matrix3.multiplyByVector( - rotation, - state.headingDir, - _frameDir, - ); - const vertical = Cesium.Cartesian3.multiplyByScalar( + const turned = horizontalPart( + rotateAbout(state.headingDir, up, -turnToGaze * k), up, - Cesium.Cartesian3.dot(turned, up), - _chordVertical, ); - Cesium.Cartesian3.subtract(turned, vertical, turned); - if (Cesium.Cartesian3.magnitude(turned) > 1e-6) { - Cesium.Cartesian3.normalize(turned, state.headingDir); - } + if (magnitude(turned) > 1e-6) state.headingDir = normalize(turned); } // A path with no horizontal extent (identical lat/lon, differing heights) // has no azimuth to fly: point east so the frame stays orthonormal. if (!state.headingDir) { - const east = Cesium.Cartesian3.fromElements(-pos.y, pos.x, 0, _frameGaze); - state.headingDir = - Cesium.Cartesian3.magnitude(east) > 1e-6 - ? Cesium.Cartesian3.normalize(east, new Cesium.Cartesian3()) - : Cesium.Cartesian3.fromElements(1, 0, 0, new Cesium.Cartesian3()); + const east = vec(-pos.y, pos.x, 0); + state.headingDir = magnitude(east) > 1e-6 ? normalize(east) : vec(1, 0, 0); } const heading = state.headingDir; // Locked pitch: heading gives the azimuth, the pitch never wanders. - const pitch = Cesium.Math.toRadians(ROUTE_PITCH_DEG); - const direction = Cesium.Cartesian3.normalize( - Cesium.Cartesian3.add( - Cesium.Cartesian3.multiplyByScalar(heading, Math.cos(pitch), _frameDir), - Cesium.Cartesian3.multiplyByScalar(up, Math.sin(pitch), _frameLevelUp), - _frameDir, - ), - _frameDir, + const pitch = toRadians(ROUTE_PITCH_DEG); + const direction = normalize( + add(scale(heading, Math.cos(pitch)), scale(up, Math.sin(pitch))), ); // Orthonormal camera frame, then roll it about its own forward axis: a // positive rotation drops the right wing, which is what a right turn wants. - const right = Cesium.Cartesian3.normalize( - Cesium.Cartesian3.cross(direction, up, _frameRight), - _frameRight, - ); - const levelUp = Cesium.Cartesian3.normalize( - Cesium.Cartesian3.cross(right, direction, _frameLevelUp), - _frameLevelUp, - ); - const bankRad = Cesium.Math.toRadians(appliedBankDeg); - let bankedUp = levelUp; - if (Math.abs(bankRad) > 1e-6) { - const quat = Cesium.Quaternion.fromAxisAngle(direction, bankRad, _bankQuat); - const rotation = Cesium.Matrix3.fromQuaternion(quat, _bankMatrix); - bankedUp = Cesium.Matrix3.multiplyByVector( - rotation, - levelUp, - _frameBankedUp, - ); - } + const right = normalize(cross(direction, up)); + const levelUp = normalize(cross(right, direction)); + const bankRad = toRadians(appliedBankDeg); + const bankedUp = + Math.abs(bankRad) > 1e-6 + ? rotateAbout(levelUp, direction, bankRad) + : levelUp; // Keep the corridor ahead of the camera warm. The batch dedupes to coarse // cells, skips warm ones and queues contenders, so a repeat costs nothing. @@ -894,20 +855,14 @@ export function advanceRouteFlight(state, dt) { // the camera reaches it. Both are cached reads — nothing samples the mesh. let sampledFloor = Number.NaN; if (typeof state.floorFn === 'function') { - const aheadPos = arcPoint(state, traveled + lookaheadM / 2, _frameAheadPos); - const aheadCarto = Cesium.Cartographic.fromCartesian( - aheadPos, - Cesium.Ellipsoid.WGS84, - _frameAheadCarto, + const aheadCarto = toCartographicRadians( + arcPoint(state, traveled + lookaheadM / 2, _frameAheadPos), ); try { - const here = state.floorFn( - Cesium.Math.toDegrees(carto.latitude), - Cesium.Math.toDegrees(carto.longitude), - ); + const here = state.floorFn(toDegrees(carto.lat), toDegrees(carto.lon)); const ahead = state.floorFn( - Cesium.Math.toDegrees(aheadCarto.latitude), - Cesium.Math.toDegrees(aheadCarto.longitude), + toDegrees(aheadCarto.lat), + toDegrees(aheadCarto.lon), ); const warm = [here, ahead].filter((value) => Number.isFinite(value)); if (warm.length) sampledFloor = Math.max(...warm); @@ -971,13 +926,7 @@ export function advanceRouteFlight(state, dt) { ); } state.appliedHeightM = heightM; - const eye = Cesium.Cartesian3.fromRadians( - carto.longitude, - carto.latitude, - heightM, - Cesium.Ellipsoid.WGS84, - _frameEye, - ); + const eye = fromRadians(carto.lon, carto.lat, heightM); state.appliedBankDeg = appliedBankDeg; return { @@ -997,6 +946,8 @@ let _viewer = null; let _getTarget = null; let _active = null; // { kind, motion, direction, speed, mode, motionId, ...state } let _tickRemover = null; +/** The frame port `_tickRemover` listens to. */ +let _tickPort = null; let _trackingRemover = null; let _inputRemovers = []; /** Monotonic id for the motion currently running; 0 means "no motion". */ @@ -1006,7 +957,7 @@ let _manualInputCount = 0; /** * Lets a caller holding a motion back (behind a fly-to) see whether the user - * took the camera meanwhile; Cesium does not cancel a flight on input. + * took the camera meanwhile; the camera does not cancel a flight on input. * @returns {number} Manual camera inputs so far. */ export function manualCameraInputCount() { @@ -1024,11 +975,25 @@ function setActiveMotion(state) { if (state) { _motionSeq += 1; state.motionId = _motionSeq; + listenForFrames(); } _active = state; return state; } +/** + * Run the motions on the frames of the viewer's frame port, the one there + * is now: a renderer bound after `initCameraVerbs` (which replaces the + * port the viewer had) is picked up when the next motion starts. + */ +function listenForFrames() { + const port = _viewer ? findFrame(_viewer) : null; + if (port === _tickPort) return; + _tickRemover?.(); + _tickPort = port; + _tickRemover = port?.on('preUpdate', onTick) ?? null; +} + /** * @returns {number} Id of the running motion, or 0 when the camera is idle. */ @@ -1066,7 +1031,7 @@ let _lookBaseline = null; // in view: which way, from which position and direction. A motion that starts from that // pose turns at least that far, so a request reported as done really moves // even when a smaller first step lands in a dip of the sampled share. -const PROVEN_TURN_RAD = Cesium.Math.toRadians(0.5); +const PROVEN_TURN_RAD = toRadians(0.5); let _provenLook = null; /** The part of the frame a viewer can see: the scope keyhole when it is on. */ @@ -1074,46 +1039,44 @@ function visibleFrame() { return { keyholeRadius: isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0 }; } -/** The frame share an in-place turn from `cam`'s pose is limited against. */ -function lookBaselineShare(cam) { - const share = globeFrameShare(cam, visibleFrame()); +/** Whether two vectors agree to `tolerance` in every component. */ +const within = (a, b, tolerance) => + Math.abs(a.x - b.x) <= tolerance && + Math.abs(a.y - b.y) <= tolerance && + Math.abs(a.z - b.z) <= tolerance; + +/** The frame share an in-place turn from `pose` is limited against. */ +function lookBaselineShare(pose) { + const share = globeFrameShare(pose, visibleFrame()); const continues = _lookBaseline && - Cesium.Cartesian3.equalsEpsilon( - _lookBaseline.position, - cam.positionWC, - 0, - 1, - ) && - Cesium.Cartesian3.equalsEpsilon( - _lookBaseline.direction, - cam.directionWC, - 0, - 1e-9, - ); + within(_lookBaseline.position, pose.position, 1) && + within(_lookBaseline.direction, pose.direction, 1e-9); _lookBaseline = { - position: Cesium.Cartesian3.clone(cam.positionWC), - direction: Cesium.Cartesian3.clone(cam.directionWC), + position: pose.position, + direction: pose.direction, share: continues ? Math.max(_lookBaseline.share, share) : share, }; return _lookBaseline.share; } /** - * One in-place look step of motion `m`. From orbit a free globe camera turns - * only as far as keeps the planet in frame, measured against the baseline the - * turn started from, then the motion ends there. + * One in-place look step of motion `m` (`look`: 'up', 'down', 'left' or + * 'right'). From orbit a free globe camera turns only as far as keeps the + * planet in frame, measured against the baseline the turn started from, then + * the motion ends there. */ -function lookWithinFrame(cam, m, look, angle) { +function lookWithinFrame(camera, m, look, angle) { let allowed = angle; if (isFreeGlobeCamera(_viewer)) { + const pose = camera.pose(); if (m.globeShareAtStart === undefined) { - m.globeShareAtStart = lookBaselineShare(cam); - m.provenTurnRad = lookProven(cam, look) ? PROVEN_TURN_RAD : 0; + m.globeShareAtStart = lookBaselineShare(pose); + m.provenTurnRad = lookProven(pose, look) ? PROVEN_TURN_RAD : 0; m.turnedRad = 0; } _provenLook = null; - allowed = lookAngleWithinFrame(cam, look, angle, { + allowed = lookAngleWithinFrame(pose, look, angle, { ...visibleFrame(), startShare: m.globeShareAtStart, }); @@ -1121,45 +1084,46 @@ function lookWithinFrame(cam, m, look, angle) { if (allowed < owed) allowed = owed; m.turnedRad += allowed; } - if (allowed > 0) cam[look](allowed); + if (allowed > 0) camera.setView(eyeTurned(camera.pose(), look, allowed)); // The pose this turn leaves, for a turn that continues from it. - if (_lookBaseline) - Cesium.Cartesian3.clone(cam.directionWC, _lookBaseline.direction); + if (_lookBaseline) _lookBaseline.direction = camera.pose().direction; if (allowed < angle) interruptCameraMotion('globe-out-of-frame'); } /** * The in-place look a pitch change from `fromPitch` to `goalPitch` makes: - * 'lookUp', 'lookDown', or null when it does not move. A tilt is judged by - * the way its pitch moves, whatever form or direction word it came in. + * 'up', 'down', or null when it does not move. A tilt is judged by the way + * its pitch moves, whatever form or direction word it came in. */ function tiltLook(fromPitch, goalPitch) { if (!Number.isFinite(fromPitch) || !Number.isFinite(goalPitch)) return null; - if (goalPitch > fromPitch) return 'lookUp'; - return goalPitch < fromPitch ? 'lookDown' : null; + if (goalPitch > fromPitch) return 'up'; + return goalPitch < fromPitch ? 'down' : null; } /** Tilt `m` in place to `goalPitch`, as far as the frame limit allows. */ -function tiltInPlaceWithinFrame(cam, m, goalPitch) { - const look = tiltLook(cam.pitch, goalPitch); - if (look) lookWithinFrame(cam, m, look, Math.abs(goalPitch - cam.pitch)); +function tiltInPlaceWithinFrame(camera, m, goalPitch) { + const pitch = camera.pose().pitch; + const look = tiltLook(pitch, goalPitch); + if (look) lookWithinFrame(camera, m, look, Math.abs(goalPitch - pitch)); } /** - * The pitch an in-place tilt from `cam`'s pose toward `goalPitch` reaches - * before the frame limit stops it, judged as its steps will be: `goalPitch` - * itself when the planet stays in frame the whole way, or the camera is not a - * free globe camera. The steps run on a copy of the camera, each looking by - * the pitch still to go as the tilt's frames do, because a rolled camera's - * look turns its pitch by less than the look angle. + * The pitch an in-place tilt from the camera's pose toward `goalPitch` + * reaches before the frame limit stops it, judged as its steps will be: + * `goalPitch` itself when the planet stays in frame the whole way, or the + * camera is not a free globe camera. The steps run on a copy of the pose, each + * looking by the pitch still to go as the tilt's frames do, because a rolled + * camera's look turns its pitch by less than the look angle. */ -function tiltPitchWithinFrame(cam, goalPitch) { - const look = tiltLook(cam.pitch, goalPitch); +function tiltPitchWithinFrame(camera, goalPitch) { + const pose = camera.pose(); + const look = tiltLook(pose.pitch, goalPitch); if (!look || !isFreeGlobeCamera(_viewer)) return goalPitch; - const frame = { ...visibleFrame(), startShare: lookBaselineShare(cam) }; + const frame = { ...visibleFrame(), startShare: lookBaselineShare(pose) }; // A proven half degree is turned whatever the sampled share says. - let owed = lookProven(cam, look) ? PROVEN_TURN_RAD : 0; - const probe = Cesium.Camera.clone(cam); + let owed = lookProven(pose, look) ? PROVEN_TURN_RAD : 0; + let probe = pose; for (let i = 0; i < 32; i += 1) { if (tiltLook(probe.pitch, goalPitch) !== look) return goalPitch; const angle = Math.abs(goalPitch - probe.pitch); @@ -1169,7 +1133,7 @@ function tiltPitchWithinFrame(cam, goalPitch) { Math.min(angle, owed), ); owed -= allowed; - if (allowed > 0) probe[look](allowed); + if (allowed > 0) probe = lookedPose(probe, look, allowed); if (allowed < angle) return probe.pitch; } return probe.pitch; @@ -1177,31 +1141,22 @@ function tiltPitchWithinFrame(cam, goalPitch) { /** The reply's note for a tilt the frame limit stops short of its angle. */ function tiltFrameNote(pitch) { - return `Stopped at ${Math.round(Cesium.Math.toDegrees(pitch))}°: from this height a shallower angle would turn the globe out of view. Zoom in to tilt further.`; + return `Stopped at ${Math.round(toDegrees(pitch))}°: from this height a shallower angle would turn the globe out of view. Zoom in to tilt further.`; } -/** True when the pre-check proved a half-degree `look` from `cam`'s pose. */ -function lookProven(cam, look) { +/** True when the pre-check proved a half-degree `look` from `pose`. */ +function lookProven(pose, look) { return ( _provenLook?.look === look && - Cesium.Cartesian3.equalsEpsilon( - _provenLook.position, - cam.positionWC, - 0, - 1, - ) && - Cesium.Cartesian3.equalsEpsilon( - _provenLook.direction, - cam.directionWC, - 0, - 1e-9, - ) + pose != null && + within(_provenLook.position, pose.position, 1) && + within(_provenLook.direction, pose.direction, 1e-9) ); } /** - * The check a voice in-place turn (`look`: 'lookUp', 'lookDown', 'lookLeft' - * or 'lookRight') must pass from orbit: refused when even half a degree would + * The check a voice in-place turn (`look`: 'up', 'down', 'left' or 'right') + * must pass from orbit: refused when even half a degree would * cross the frame limit, otherwise proven for that half degree from this pose. * With `released`, the turn runs through a navigation that first releases a * tracked or locked camera and keeps its world pose. The frame measure and the @@ -1212,13 +1167,13 @@ function lookProven(cam, look) { */ function checkLookFromOrbit(look, { released = false } = {}) { _provenLook = null; - if (_viewer.scene.mode !== Cesium.SceneMode.SCENE3D) return null; - const cam = _viewer.camera; if (!released && !isFreeGlobeCamera(_viewer)) return null; + const pose = findCamera(_viewer)?.pose(); + if (!pose) return null; if ( - lookStepLosesGlobe(cam, look, PROVEN_TURN_RAD, { + lookStepLosesGlobe(pose, look, PROVEN_TURN_RAD, { ...visibleFrame(), - startShare: lookBaselineShare(cam), + startShare: lookBaselineShare(pose), }) ) return { @@ -1229,15 +1184,15 @@ function checkLookFromOrbit(look, { released = false } = {}) { }; _provenLook = { look, - position: Cesium.Cartesian3.clone(cam.positionWC), - direction: Cesium.Cartesian3.clone(cam.directionWC), + position: pose.position, + direction: pose.direction, }; return null; } function clearLookAt() { try { - _viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY); + findCamera(_viewer)?.release(); } catch { /* teardown race */ } @@ -1246,7 +1201,7 @@ function clearLookAt() { /** * Put the horizon back. * - * The route dolly is the only motion that rolls the camera, and Cesium keeps + * The route dolly is the only motion that rolls the camera, and the camera keeps * whatever world-space up vector it was last handed — so releasing a flight * mid-bank leaves the user holding a tilted horizon until some later motion * happens to level it. Heading, pitch and position are preserved; only the @@ -1255,13 +1210,11 @@ function clearLookAt() { */ function levelCameraRoll() { try { - const cam = _viewer?.camera; - if (!cam || typeof cam.setView !== 'function') return false; - const roll = Cesium.Math.negativePiToPi(cam.roll || 0); - if (Math.abs(roll) < 1e-5) return false; - cam.setView({ - orientation: { heading: cam.heading, pitch: cam.pitch, roll: 0 }, - }); + const camera = findCamera(_viewer); + if (!camera) return false; + const { heading, pitch, roll } = camera.pose(); + if (Math.abs(negativePiToPi(roll || 0)) < 1e-5) return false; + camera.setView({ orientation: { heading, pitch, roll: 0 } }); return true; } catch { return false; // teardown race @@ -1274,7 +1227,7 @@ export function interruptCameraMotion(reason = 'interrupt') { // While an entity is TRACKED, the follow camera owns the reference frame — // resetting the lookAt transform here flings the camera into space (field // finding). Leave the transform to the tracker; it re-asserts every frame. - const tracking = Boolean(_viewer?.trackedEntity); + const tracking = isFollowing(_viewer); const wasRoute = wasActive && _active.kind === 'route'; if ( wasActive && @@ -1316,6 +1269,9 @@ export function getActiveCameraMotion() { return info; } +/** A pan's direction as the camera move it makes; any other is down. */ +const PAN_MOVES = Object.freeze({ left: 'left', right: 'right', up: 'up' }); + function onTick() { if (!_active || !_viewer) return; // Wall-clock dt: clock.currentTime FREEZES when the app clock isn't @@ -1326,7 +1282,6 @@ function onTick() { Math.max(0.001, (nowMs - (_active.lastMs ?? nowMs)) / 1000), ); _active.lastMs = nowMs; - const cam = _viewer.camera; const m = _active; // `once` motions ease out and self-stop on budget exhaustion. @@ -1341,6 +1296,7 @@ function onTick() { } try { + const camera = cameraOf(_viewer); if (m.kind === 'orbit' && m.pending) { // Armed but target-less (started mid-flight, e.g. "fly to X and orbit // it"): keep trying for a ground target until the camera settles. @@ -1350,11 +1306,11 @@ function onTick() { return; } // pickEllipsoid hits the globe from ANY altitude — target existence - // alone is not arrival. Camera flights are scene tweens, and multi-stage - // flights have GAPS between tweens: require the tween queue quiet for a + // alone is not arrival. Multi-stage flights have GAPS between flights: + // require the camera out of any flight for a // continuous 0.8 s before capturing the orbit framing at the REAL // destination (field finding: Eiffel chain orbited from mid-flight). - if (_viewer.scene.tweens.length > 0) { + if (cameraFlying()) { m.settledS = 0; return; } @@ -1362,86 +1318,74 @@ function onTick() { if (m.settledS < 0.8) return; const target = _getTarget?.(_viewer); if (!target) return; - const cam2 = _viewer.camera; - const range = Cesium.Cartesian3.distance(cam2.positionWC, target); - const carto2 = Cesium.Cartographic.fromCartesian(cam2.positionWC); - const tCarto2 = Cesium.Cartographic.fromCartesian(target); - const dh2 = carto2.height - tCarto2.height; + const pose = camera.pose(); m.target = target; - m.hpr = new Cesium.HeadingPitchRange( - cam2.heading, - -Math.asin(Math.min(1, Math.max(-1, dh2 / Math.max(1, range)))), - range, - ); - m.hprStartHeading = cam2.heading; + m.hpr = orbitFraming(pose, target); + m.hprStartHeading = pose.heading; m.pending = false; m.elapsed = 0; // once-mode budget starts when the orbit actually begins return; } if (m.kind === 'orbit') { const rate = - Cesium.Math.toRadians(ORBIT_DEG_S[m.speed]) * - (m.direction === 'left' ? -1 : 1); + toRadians(ORBIT_DEG_S[m.speed]) * (m.direction === 'left' ? -1 : 1); if (m.mode === 'once') { const total = - Cesium.Math.toRadians(ONCE.orbitDeg) * - (m.direction === 'left' ? -1 : 1); + toRadians(ONCE.orbitDeg) * (m.direction === 'left' ? -1 : 1); m.hpr.heading = m.hprStartHeading + total * scale; } else { m.hpr.heading += rate * dt; } - cam.lookAt(m.target, m.hpr); + camera.lookAt(m.target, m.hpr); } else if (m.kind === 'pan') { - const heightM = Math.max(50, cam.positionCartographic.height); + const heightM = Math.max(50, camera.pose().height); const step = m.mode === 'once' ? heightM * ONCE.panViewFraction * (scale - (m.lastScale || 0)) : heightM * PAN_VIEW_FRACTION_S[m.speed] * dt; m.lastScale = scale; - if (m.direction === 'left') cam.moveLeft(step); - else if (m.direction === 'right') cam.moveRight(step); - else if (m.direction === 'up') cam.moveUp(step); - else cam.moveDown(step); + camera.setView( + eyeMoved(camera.pose(), PAN_MOVES[m.direction] ?? 'down', step), + ); } else if (m.kind === 'tilt') { - tickTilt(cam, m, scale, dt); + tickTilt(camera, m, scale, dt); } else if (m.kind === 'rotate' || m.kind === 'rotate_globe') { const degS = TILT_DEG_S[m.speed]; const stepRad = m.mode === 'once' - ? Cesium.Math.toRadians(ONCE.rotateDeg) * (scale - (m.lastScale || 0)) - : Cesium.Math.toRadians(degS) * dt; + ? toRadians(ONCE.rotateDeg) * (scale - (m.lastScale || 0)) + : toRadians(degS) * dt; m.lastScale = scale; if (m.kind === 'rotate_globe') { // Tracking can acquire the camera without going through navigation. // Yield without resetting its pose/frame: the world-space arc proof - // only describes Cesium's rotation while the frame is identity. + // only describes the camera's rotation while the frame is identity. + const pose = camera.pose(); if (!isFreeGlobeCamera(_viewer) || _isCockpitActive?.()) { interruptCameraMotion('globe-camera-owner-changed'); return; } - // Cesium rotates both position and basis about the reference-frame + // The camera rotates both position and basis about the reference-frame // origin. The captured screen-up axis keeps left/right horizontal even // in a tilted or rolled view; a positive angle moves the globe right. const angle = m.direction === 'left' ? -stepRad : stepRad; - if (globeRotationFitsKeyhole() !== true) { + if (globeRotationFitsKeyhole(liveView(camera, pose)) !== true) { interruptCameraMotion('globe-framing-changed'); return; } if ( - !globeRotationHasClearance(cam.positionWC) || - Math.abs( - Cesium.Cartesian3.magnitude(cam.positionWC) - m.rotationRadius, - ) > 0.01 + !globeRotationHasClearance(pose.position) || + Math.abs(magnitude(pose.position) - m.rotationRadius) > 0.01 ) { interruptCameraMotion('globe-surface-limit'); return; } - cam.rotate(m.rotationAxis, angle); + camera.setView(eyeRotatedAbout(pose, m.rotationAxis, angle)); } else { lookWithinFrame( - cam, + camera, m, - m.direction === 'left' ? 'lookLeft' : 'lookRight', + m.direction === 'left' ? 'left' : 'right', stepRad, ); } @@ -1453,7 +1397,7 @@ function onTick() { // user left it rather than teleporting to an altitude derived from // nothing. An interrupt during the arm is still instant. if (frame.arming) return; - cam.setView({ + camera.setView({ destination: frame.eye, orientation: { direction: frame.direction, up: frame.up }, }); @@ -1467,6 +1411,25 @@ function onTick() { } } +/** Whether the camera is in a flight. */ +const cameraFlying = () => Boolean(findCamera(_viewer)?.flying); + +/** + * An orbit offset that reproduces the current framing of `target` exactly: + * the view's heading, and pitch and range from the geometry. + */ +function orbitFraming(pose, target) { + const range = distance(pose.position, target); + const dh = + toCartographicRadians(pose.position).height - + toCartographicRadians(target).height; + return { + heading: pose.heading, + pitch: -Math.asin(Math.min(1, Math.max(-1, dh / Math.max(1, range)))), + range, + }; +} + /** * One frame of tilt. With a ground pivot the camera swings about it (lookAt), * so the place under the crosshair stays centred; without one it looks up or @@ -1481,15 +1444,14 @@ function onTick() { * keeps the place centred: tilting in place there would lift the crosshair * onto the sky. */ -function tickTilt(cam, m, scale, dt) { - const from = cam.pitch; +function tickTilt(camera, m, scale, dt) { + const pitchNow = () => camera.pose().pitch; + const from = pitchNow(); const want = m.mode === 'once' ? m.startPitch + (m.goalPitch - m.startPitch) * scale : from + - Cesium.Math.toRadians(TILT_DEG_S[m.speed]) * - dt * - (m.direction === 'up' ? 1 : -1); + toRadians(TILT_DEG_S[m.speed]) * dt * (m.direction === 'up' ? 1 : -1); const up = want > from; const limited = up ? Math.min(want, Math.max(from, PITCH_MAX)) @@ -1498,25 +1460,25 @@ function tickTilt(cam, m, scale, dt) { if (m.hpr) { // Apply a range a zoom set since the last frame, even when the pitch // then has nowhere to go (a zoom in to the clearance ends the pivot). - cam.lookAt(m.target, m.hpr); + camera.lookAt(m.target, m.hpr); // Up toward the horizon the swing lowers the camera: hold the clearance, // and keep the place below the horizon. const cap = up ? Math.max(m.hpr.pitch, tiltPivotPitchMax(m.hpr.range)) : Infinity; - for (let i = 0; i < 3 && Math.abs(limited - cam.pitch) > 1e-6; i += 1) { + for (let i = 0; i < 3 && Math.abs(limited - pitchNow()) > 1e-6; i += 1) { const pitch = Math.min( cap, - Math.max(-Cesium.Math.PI_OVER_TWO, m.hpr.pitch + limited - cam.pitch), + Math.max(-PI_OVER_TWO, m.hpr.pitch + limited - pitchNow()), ); if (pitch === m.hpr.pitch) break; m.hpr.pitch = pitch; - cam.lookAt(m.target, m.hpr); + camera.lookAt(m.target, m.hpr); } // A once motion that just completed released the lookAt frame before // this last step re-took it. if (_active !== m) clearLookAt(); - if (up && m.hpr.pitch >= cap && cam.pitch < limited - 1e-6) { + if (up && m.hpr.pitch >= cap && pitchNow() < limited - 1e-6) { if (tiltClearanceBinds(m.hpr.range)) { // Down to its clearance: let go of the pivot and tilt the rest in // place, which keeps the height. @@ -1529,7 +1491,7 @@ function tickTilt(cam, m, scale, dt) { } } } - if (!m.hpr) tiltInPlaceWithinFrame(cam, m, limited); + if (!m.hpr) tiltInPlaceWithinFrame(camera, m, limited); if (m.mode !== 'once' && (limited !== want || atLimit)) interruptCameraMotion('tilt-clamp'); } @@ -1580,36 +1542,27 @@ function tiltUpLimit({ target, pivot }) { /** The camera pitch lookAt gives for this pivot at the given pivot pitch. */ function pivotCameraPitch(target, { heading, range }, pitch) { - const offset = new Cesium.Cartesian3( - -range * Math.cos(pitch) * Math.sin(heading), - -range * Math.cos(pitch) * Math.cos(heading), - -range * Math.sin(pitch), - ); - const eye = Cesium.Matrix4.multiplyByPoint( - Cesium.Transforms.eastNorthUpToFixedFrame(target), - offset, - new Cesium.Cartesian3(), - ); - const look = Cesium.Cartesian3.subtract(target, eye, new Cesium.Cartesian3()); - Cesium.Cartesian3.normalize(look, look); - const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84; - const upAtEye = ellipsoid.geodeticSurfaceNormal(eye, new Cesium.Cartesian3()); - return Math.asin( - Cesium.Math.clamp(Cesium.Cartesian3.dot(look, upAtEye), -1, 1), - ); + const eye = framePoint(eastNorthUp(target), { + x: -range * Math.cos(pitch) * Math.sin(heading), + y: -range * Math.cos(pitch) * Math.cos(heading), + z: -range * Math.sin(pitch), + }); + const look = normalize(sub(target, eye)); + return Math.asin(clamp(dot(look, geodeticSurfaceNormal(eye)), -1, 1)); } /** * Where a tilt starts. It swings about the ground under the crosshair so the * place stays centred. It tilts in place with no ground there, from globe - * range, or while an entity is tracked (the follow camera owns that frame; + * range, or while something is followed (the follow camera owns that frame; * voice releases it before moving, so a voice tilt still pivots). */ -function tiltStartFrame(cam) { - const target = _viewer.trackedEntity ? null : _getTarget?.(_viewer); - let pivot = target ? tiltPivot(cam, target) : null; +function tiltStartFrame(camera) { + const pose = camera.pose(); + const target = isFollowing(_viewer) ? null : _getTarget?.(_viewer); + let pivot = target ? tiltPivot(pose, target) : null; if (pivot && !tiltPivotInReach(pivot.range)) pivot = null; - return { target, pivot, from: cam.pitch }; + return { target, pivot, from: pose.pitch }; } /** Whether a tilt may pivot at this range: up to and including the cutoff. */ @@ -1619,87 +1572,84 @@ function tiltPivotInReach(range) { /** The reply's note for a tilt the place's horizon stops short of its angle. */ function tiltHorizonNote(pitch) { - return `Stopped at ${Math.round(Cesium.Math.toDegrees(pitch))}°: from this range a shallower angle puts the place past the horizon. Zoom in to tilt further.`; + return `Stopped at ${Math.round(toDegrees(pitch))}°: from this range a shallower angle puts the place past the horizon. Zoom in to tilt further.`; } /** Ground pivot for a tilt: heading, pitch and range in the target's own frame. */ -function tiltPivot(cam, target) { - const local = Cesium.Matrix4.multiplyByPoint( - Cesium.Matrix4.inverseTransformation( - Cesium.Transforms.eastNorthUpToFixedFrame(target), - new Cesium.Matrix4(), - ), - cam.positionWC, - new Cesium.Cartesian3(), - ); - const range = Cesium.Cartesian3.magnitude(local); +function tiltPivot(pose, target) { + const local = inverseFramePoint(eastNorthUp(target), pose.position); + const range = magnitude(local); if (!(range > 1) || local.z <= 0) return null; // Near straight overhead the offset's heading is float noise (it flipped a // north-up London view to south); keep the camera's own. const heading = Math.hypot(local.x, local.y) > range * 0.01 ? Math.atan2(-local.x, -local.y) - : cam.heading; - return new Cesium.HeadingPitchRange( + : pose.heading; + return { heading, - -Math.asin(Math.min(1, local.z / range)), + pitch: -Math.asin(Math.min(1, local.z / range)), range, - ); + }; } -/** Rigid origin-centred rotation stays outside the actual ellipsoid's bounding sphere. */ +/** Rigid origin-centred rotation stays outside the ellipsoid's bounding sphere. */ function globeRotationHasClearance(position) { - const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84; - const { minimumRadius, maximumRadius } = ellipsoid; - const radius = Cesium.Cartesian3.magnitude(position); - return ( - Number.isFinite(minimumRadius) && - minimumRadius > 0 && - Number.isFinite(maximumRadius) && - maximumRadius >= minimumRadius && - Number.isFinite(radius) && - radius > maximumRadius * (1 + 1e-12) - ); + const radius = magnitude(position); + return Number.isFinite(radius) && radius > WGS84.radii.x * (1 + 1e-12); } +/** + * The camera's view for the keyhole test: its pose, its projection, and + * whether it is the live camera (whose Earth disc the overlay projects). + */ +function liveView(camera, pose = camera.pose()) { + let projection = null; + try { + projection = camera.matrices().projection; + } catch { + /* no projection for these depth limits: unsupported below */ + } + return { ...pose, projection, live: true }; +} + +/** + * Whether a projection is a perspective one centred on the view: what the + * keyhole cone below assumes. Column-major, so element 11 is row 3 of + * column 2 (−1 for a perspective divide), 15 row 3 of column 3 (0), and 8 + * and 9 the off-centre shifts. + */ +const centredPerspective = (p) => + p?.[11] === -1 && p[15] === 0 && p[8] === 0 && p[9] === 0; + /** Use the existing WGS84/CSS-pixel projection; null means unsupported, not close-up. */ -function globeRotationFitsKeyhole(camera = _viewer.camera) { - const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84; - if (!Cesium.Cartesian3.equals(ellipsoid.radii, Cesium.Ellipsoid.WGS84.radii)) - return null; - const canvas = _viewer.scene.canvas; +function globeRotationFitsKeyhole(view) { + const canvas = canvasOf(_viewer); const width = canvas.clientWidth; const height = canvas.clientHeight; - const frustum = camera.frustum; if ( !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0 || - !(frustum instanceof Cesium.PerspectiveFrustum) || - !Number.isFinite(frustum.near) || - frustum.near <= 0 || - !Number.isFinite(frustum.far) || - frustum.far <= frustum.near || - frustum.xOffset !== 0 || - frustum.yOffset !== 0 + !centredPerspective(view.projection) || + !Number.isFinite(view.near) || + view.near <= 0 || + !Number.isFinite(view.far) || + view.far <= view.near ) return null; try { - const cam = camera; - const distance = Cesium.Cartesian3.magnitude(cam.positionWC); - const sphereRadius = ellipsoid.maximumRadius; - if (!Number.isFinite(distance) || distance <= 0) return null; - if (distance <= sphereRadius) return false; // Near-surface polar views are close-up too. - const radiusPx = earthDiscScreenRadius(distance, height, frustum.fovy); + const distanceM = magnitude(view.position); + const sphereRadius = WGS84.radii.x; + if (!Number.isFinite(distanceM) || distanceM <= 0) return null; + if (distanceM <= sphereRadius) return false; // Near-surface polar views are close-up too. + const radiusPx = earthDiscScreenRadius(distanceM, height, view.fovy); if (!radiusPx) return null; const keyhole = getKeyholeGeometry(width, height); // The known nadir reset probe uses the same exact cone below; projecting - // through SceneTransforms would read the live scene.camera instead. - if ( - camera === _viewer.camera && - !projectEarthDiscToViewport(_viewer, width, height) - ) { + // through the query port would read the live camera instead. + if (view.live && !projectEarthDiscToViewport(_viewer, width, height)) { // A near-surface horizon view cannot fit even when pointed at Earth; // an orbital camera looking away is unsupported, not a close-up offer. return radiusPx > Math.min(keyhole.radius, width / 2, height / 2) @@ -1710,33 +1660,26 @@ function globeRotationFitsKeyhole(camera = _viewer.camera) { // against the existing keyhole cone. Canvas-edge clipping does not change // framing during rigid globe rotation and is not a clearance condition, // without changing the UI projection or defining another keyhole/mask. - const toCenter = Cesium.Cartesian3.negate( - cam.positionWC, - new Cesium.Cartesian3(), - ); - const depth = Cesium.Cartesian3.dot(toCenter, cam.directionWC); - const right = Math.abs(Cesium.Cartesian3.dot(toCenter, cam.rightWC)); - const up = Math.abs(Cesium.Cartesian3.dot(toCenter, cam.upWC)); - const focalY = height / (2 * Math.tan(frustum.fovy / 2)); - const focalX = - width / (2 * Math.tan(frustum.fovy / 2) * frustum.aspectRatio); + const toCenter = vec(-view.position.x, -view.position.y, -view.position.z); + const depth = dot(toCenter, view.direction); + const right = Math.abs(dot(toCenter, view.right)); + const up = Math.abs(dot(toCenter, view.up)); + const focalY = height / (2 * Math.tan(view.fovy / 2)); + const focalX = width / (2 * Math.tan(view.fovy / 2) * view.aspectRatio); if ( ![depth, right, up, focalX, focalY].every(Number.isFinite) || focalX <= 0 || focalY <= 0 ) return null; - const halfAngle = Math.asin(sphereRadius / distance); + const halfAngle = Math.asin(sphereRadius / distanceM); const centerAngle = Math.atan2(Math.hypot(right, up), depth); const keyholeAngle = Math.atan(keyhole.radius / Math.max(focalX, focalY)); // No overlay visibility hysteresis: a fully contained smaller globe needs no reset. const framed = centerAngle + halfAngle <= keyholeAngle; if (!framed) return false; // Projection alone does not prove that a tiny globe is within depth planes. - if ( - depth - sphereRadius < frustum.near || - depth + sphereRadius > frustum.far - ) + if (depth - sphereRadius < view.near || depth + sphereRadius > view.far) return null; return true; } catch { @@ -1744,25 +1687,36 @@ function globeRotationFitsKeyhole(camera = _viewer.camera) { } } -/** Check the unchanged reset destination without moving the live camera. */ +/** + * Check the unchanged reset destination without moving the live camera: the + * view the Globe View preset sets above the current point, with the live + * camera's projection. Its axes are the camera convention's: heading, + * pitch and roll in the east-north-up frame, the view along the frame's x + * once heading is turned a quarter back. + */ function globeResetFitsKeyhole() { try { - const camera = Cesium.Camera.clone(_viewer.camera); - const { longitude, latitude } = _viewer.camera.positionCartographic; - camera.setView({ - destination: Cesium.Cartesian3.fromRadians( - longitude, - latitude, - GLOBE_VIEW.heightM, - ), - orientation: { - heading: 0, - pitch: Cesium.Math.toRadians(GLOBE_VIEW.pitchDeg), - roll: 0, - }, - endTransform: Cesium.Matrix4.IDENTITY, + const camera = cameraOf(_viewer); + const pose = camera.pose(); + const here = toCartographicRadians(pose.position); + const position = fromRadians(here.lon, here.lat, GLOBE_VIEW.heightM); + const axes = headingPitchRollFrame(position, { + heading: 0 - Math.PI / 2, + pitch: toRadians(GLOBE_VIEW.pitchDeg), + roll: 0, }); - return globeRotationFitsKeyhole(camera) === true; + const direction = axes.x; + const up = axes.z; + return ( + globeRotationFitsKeyhole({ + ...liveView(camera, pose), + live: false, + position, + direction, + up, + right: cross(direction, up), + }) === true + ); } catch { return false; } @@ -1809,21 +1763,20 @@ export function initCameraVerbs( typeof isCockpitActive === 'function' ? isCockpitActive : null; _viewer = viewer; _lookBaseline = null; - if (_tickRemover) _tickRemover(); - _tickRemover = viewer.clock.onTick.addEventListener(onTick); + listenForFrames(); if (_trackingRemover) _trackingRemover(); // Cockpit can acquire then clear tracking before the next clock tick. // Yield on acquisition itself without changing legacy camera motions. - _trackingRemover = viewer.trackedEntityChanged?.addEventListener((entity) => { - if (entity && _active?.kind === 'rotate_globe') + _trackingRemover = onFollowChanged(viewer, (followed) => { + if (followed && _active?.kind === 'rotate_globe') interruptCameraMotion('globe-camera-owner-changed'); // A pivoting tilt's lookAt would fight the follow camera every frame. - else if (entity && _active?.kind === 'tilt' && _active.hpr) + else if (followed && _active?.kind === 'tilt' && _active.hpr) interruptCameraMotion('tilt-camera-owner-changed'); }); for (const rm of _inputRemovers) rm(); _inputRemovers = []; - const canvas = viewer.scene.canvas; + const canvas = canvasOf(viewer); // ANY manual camera input reclaims control — the cancelFlight reflex. for (const evt of ['pointerdown', 'touchstart', 'wheel']) { const h = () => { @@ -1850,14 +1803,8 @@ function requestedTiltPitch(args, direction) { // The camera never looks above the horizon, so a positive angle can only // mean the same angle below it ("tilt 45 degrees" sent as 45). if (Number.isFinite(requested)) - return Cesium.Math.clamp( - Cesium.Math.toRadians(-Math.abs(requested)), - PITCH_MIN, - PITCH_MAX, - ); - return direction === null - ? Cesium.Math.toRadians(TILT_DEFAULT_PITCH_DEG) - : null; + return clamp(toRadians(-Math.abs(requested)), PITCH_MIN, PITCH_MAX); + return direction === null ? toRadians(TILT_DEFAULT_PITCH_DEG) : null; } /** @@ -1958,14 +1905,11 @@ export function moveCamera(args = {}, runNavigation = null) { if (motion === 'tilt' && tiltToPitch !== null) { // Angles and limits are the camera's own pitch, whatever the swing pivots // about; releasing the follow camera does not change it. - const from = _viewer.camera.pitch; + const from = cameraOf(_viewer).pose().pitch; // -89 or -90 means top-down, which a -90° view already is: the clamp // must not tilt it up 1°. const atTopDown = tiltToPitch <= PITCH_MIN && from <= PITCH_MIN; - if ( - atTopDown || - Math.abs(tiltToPitch - from) < Cesium.Math.toRadians(0.5) - ) { + if (atTopDown || Math.abs(tiltToPitch - from) < toRadians(0.5)) { // Still a camera request: it stops a running motion and releases the // follow camera, as a tilt that moves would. const hold = () => { @@ -1974,9 +1918,7 @@ export function moveCamera(args = {}, runNavigation = null) { ok: true, action: 'move_camera', motion, - pitchDeg: Math.round( - Cesium.Math.toDegrees(atTopDown ? from : tiltToPitch), - ), + pitchDeg: Math.round(toDegrees(atTopDown ? from : tiltToPitch)), unchanged: true, }; }; @@ -1986,8 +1928,8 @@ export function moveCamera(args = {}, runNavigation = null) { // as {direction:'down', pitchDeg:10} would tilt up from -45°. const towards = tiltToPitch > from ? 'up' : 'down'; if ((direction === 'up' || direction === 'down') && direction !== towards) { - const target = Math.round(Cesium.Math.toDegrees(tiltToPitch)); - const now = Math.round(Cesium.Math.toDegrees(from)); + const target = Math.round(toDegrees(tiltToPitch)); + const now = Math.round(toDegrees(from)); return { ok: false, action: 'move_camera', @@ -1996,25 +1938,20 @@ export function moveCamera(args = {}, runNavigation = null) { } if ( towards === 'up' && - from >= - tiltUpLimit(tiltStartFrame(_viewer.camera)) - Cesium.Math.toRadians(0.5) + from >= tiltUpLimit(tiltStartFrame(cameraOf(_viewer))) - toRadians(0.5) ) return tiltUpLimitRefusal(); } else if (motion === 'tilt') { // Honest limits: at the clamp a tilt is a no-op — say so instead of // reporting success and letting the model gaslight itself (field test). - const pitch = _viewer.camera.pitch; + const pitch = cameraOf(_viewer).pose().pitch; if ( direction === 'up' && - pitch >= - tiltUpLimit(tiltStartFrame(_viewer.camera)) - Cesium.Math.toRadians(0.5) + pitch >= tiltUpLimit(tiltStartFrame(cameraOf(_viewer))) - toRadians(0.5) ) { return tiltUpLimitRefusal(); } - if ( - direction === 'down' && - pitch <= PITCH_MIN + Cesium.Math.toRadians(0.5) - ) { + if (direction === 'down' && pitch <= PITCH_MIN + toRadians(0.5)) { return { ok: false, action: 'move_camera', @@ -2027,16 +1964,15 @@ export function moveCamera(args = {}, runNavigation = null) { const look = motion === 'tilt' ? tiltLook( - _viewer.camera.pitch, + cameraOf(_viewer).pose().pitch, tiltToPitch ?? - _viewer.camera.pitch + - Cesium.Math.toRadians(ONCE.tiltDeg) * - (direction === 'up' ? 1 : -1), + cameraOf(_viewer).pose().pitch + + toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1), ) : motion === 'rotate' ? direction === 'left' - ? 'lookLeft' - : 'lookRight' + ? 'left' + : 'right' : null; // Honest limits from orbit too: a stopped turn rests within 0.05° of its // limit, so one that cannot go half a degree further is refused rather than @@ -2053,15 +1989,14 @@ export function moveCamera(args = {}, runNavigation = null) { if ( (motion === 'rotate_globe' || (motion === 'orbit' && typeof runNavigation !== 'function')) && - _viewer?.trackedEntity + isFollowing(_viewer) ) { // The follow camera owns a tracked view; a lookAt orbit fights it frame // by frame and stop rips the camera out (field finding). Honest refusal // until tracked-orbit rides the follow camera natively (roadmap). + const followed = followedOf(_viewer); const label = - _viewer.trackedEntity?.name || - _viewer.trackedEntity?.id || - 'the tracked target'; + followed?.name || followed?.labelModel?.title || 'the tracked target'; return { ok: false, action: 'move_camera', @@ -2070,19 +2005,23 @@ export function moveCamera(args = {}, runNavigation = null) { } let globePose; if (motion === 'rotate_globe') { - if (_viewer.scene.mode !== Cesium.SceneMode.SCENE3D) { + const camera = cameraOf(_viewer); + let pose; + try { + pose = camera.pose(); + } catch { + // A frustum the camera cannot describe (depth limits out of order). return { ok: false, action: 'move_camera', - error: 'Globe rotation requires a 3D view.', + reason: 'unsupported-view', + error: 'Globe rotation requires a supported perspective view.', }; } - const cam = _viewer.camera; globePose = { - position: Cesium.Cartesian3.clone(cam.positionWC), - direction: Cesium.Cartesian3.clone(cam.directionWC), - up: Cesium.Cartesian3.normalize(cam.upWC, new Cesium.Cartesian3()), - right: Cesium.Cartesian3.clone(cam.rightWC), + position: vec(pose.position.x, pose.position.y, pose.position.z), + direction: vec(pose.direction.x, pose.direction.y, pose.direction.z), + up: normalize(pose.up), }; if (_isCockpitActive?.()) return { @@ -2091,14 +2030,7 @@ export function moveCamera(args = {}, runNavigation = null) { reason: 'camera-owned', error: 'Exit Cockpit before rotating the globe.', }; - const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84; - if (!( - Number.isFinite(ellipsoid.minimumRadius) && - ellipsoid.minimumRadius > 0 && - Number.isFinite(ellipsoid.maximumRadius) && - ellipsoid.maximumRadius >= ellipsoid.minimumRadius && - Number.isFinite(Cesium.Cartesian3.magnitude(globePose.position)) - )) + if (!Number.isFinite(magnitude(globePose.position))) return { ok: false, action: 'move_camera', @@ -2106,7 +2038,7 @@ export function moveCamera(args = {}, runNavigation = null) { error: 'Globe rotation requires a finite supported ellipsoid and a clear globe view.', }; - const fits = globeRotationFitsKeyhole(); + const fits = globeRotationFitsKeyhole(liveView(camera, pose)); if (fits === null) return { ok: false, @@ -2140,7 +2072,7 @@ export function moveCamera(args = {}, runNavigation = null) { interruptCameraMotion('replaced'); // Checked again only if the release left the camera somewhere other than // where the check above expected it. - if (look && !lookProven(_viewer.camera, look)) { + if (look && !lookProven(findCamera(_viewer)?.pose(), look)) { const refusal = checkLookFromOrbit(look); if (refusal) return refusal; } @@ -2151,7 +2083,7 @@ export function moveCamera(args = {}, runNavigation = null) { mode, }; if (motion === 'tilt') { - const frame = tiltStartFrame(_viewer.camera); + const frame = tiltStartFrame(cameraOf(_viewer)); const { target, pivot, from } = frame; if (pivot) { state.target = target; @@ -2170,7 +2102,7 @@ export function moveCamera(args = {}, runNavigation = null) { // From orbit an in-place tilt stops where the planet would leave the // frame: aim it there, and say so. if (!pivot) { - const framed = tiltPitchWithinFrame(_viewer.camera, goal); + const framed = tiltPitchWithinFrame(cameraOf(_viewer), goal); if (framed !== goal) { goal = framed; stopNote = tiltFrameNote(goal); @@ -2184,13 +2116,12 @@ export function moveCamera(args = {}, runNavigation = null) { state.askedPitch = tiltToPitch; state.durationS = Math.max( ONCE.durationS, - Math.abs(Cesium.Math.toDegrees(goal - from)) / TILT_TO_DEG_S, + Math.abs(toDegrees(goal - from)) / TILT_TO_DEG_S, ); if (goal !== tiltToPitch) stoppedAt = goal; } else { // A nudge stops at the limit it travels toward. - const step = - Cesium.Math.toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1); + const step = toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1); state.goalPitch = step > 0 ? Math.min(from + step, Math.max(from, upLimit)) @@ -2200,21 +2131,28 @@ export function moveCamera(args = {}, runNavigation = null) { if (motion === 'rotate_globe') { // Convert an inherited ground-target frame without changing the world // pose. Rotation must pivot about Earth, never the previous local target. - const cam = _viewer.camera; - cam.cancelFlight(); - cam.lookAtTransform(Cesium.Matrix4.IDENTITY); - // Handoff may level a route's bank. Keep the caller's exact world pose. - // Copy the basis directly: setView's heading/pitch conversion is singular - // at nadir and can change the captured orientation near the poles. - Cesium.Cartesian3.clone(globePose.position, cam.position); - Cesium.Cartesian3.clone(globePose.direction, cam.direction); - Cesium.Cartesian3.clone(globePose.up, cam.up); - Cesium.Cartesian3.clone(globePose.right, cam.right); + const camera = cameraOf(_viewer); + camera.cancelFlight(); + camera.release(); + // Handoff may level a route's bank. Keep the caller's world pose, but + // write it only when the handoff changed it: a heading and pitch + // conversion inside the camera is singular at nadir, so an unchanged + // pose is left exactly as it is. + const now = camera.pose(); + if ( + distance(now.position, globePose.position) > 1e-6 || + distance(now.direction, globePose.direction) > 1e-9 || + distance(normalize(now.up), globePose.up) > 1e-9 + ) + camera.setView({ + destination: globePose.position, + orientation: { direction: globePose.direction, up: globePose.up }, + }); state.rotationAxis = globePose.up; - state.rotationRadius = Cesium.Cartesian3.magnitude(globePose.position); + state.rotationRadius = magnitude(globePose.position); } if (motion === 'orbit') { - if (_viewer.scene.tweens.length > 0) { + if (cameraFlying()) { // A camera flight is in progress — ALWAYS arm and capture at the // destination; a target existing right now is meaningless (the globe // is always under the crosshair). The voice runner already holds an @@ -2260,18 +2198,11 @@ export function moveCamera(args = {}, runNavigation = null) { armed: 'waiting-for-arrival', }; } - const cam = _viewer.camera; - const range = Cesium.Cartesian3.distance(cam.positionWC, target); // Pitch from geometry so lookAt reproduces the CURRENT framing exactly. - const carto = Cesium.Cartographic.fromCartesian(cam.positionWC); - const tCarto = Cesium.Cartographic.fromCartesian(target); - const dh = carto.height - tCarto.height; - const pitch = -Math.asin( - Math.min(1, Math.max(-1, dh / Math.max(1, range))), - ); + const pose = cameraOf(_viewer).pose(); state.target = target; - state.hpr = new Cesium.HeadingPitchRange(cam.heading, pitch, range); - state.hprStartHeading = cam.heading; + state.hpr = orbitFraming(pose, target); + state.hprStartHeading = pose.heading; } setActiveMotion(state); // Verb motion drives the camera per clock tick — hold until interrupted; @@ -2285,15 +2216,13 @@ export function moveCamera(args = {}, runNavigation = null) { speed, mode: state.mode, ...(tiltToPitch !== null && { - pitchDeg: Math.round(Cesium.Math.toDegrees(stoppedAt ?? tiltToPitch)), + pitchDeg: Math.round(toDegrees(stoppedAt ?? tiltToPitch)), }), ...(stopNote !== null && { note: stopNote }), }; }; const preserveCameraFlight = - motion === 'orbit' && - _viewer.scene.tweens.length > 0 && - !_viewer.trackedEntity; + motion === 'orbit' && cameraFlying() && !isFollowing(_viewer); return typeof runNavigation === 'function' ? runNavigation(start, { preserveCameraFlight }) : start(); @@ -2344,7 +2273,7 @@ export function adjustOrbitRange(factor) { function retargetTiltAfterZoom(m) { if (m.kind !== 'tilt' || m.mode !== 'once' || m.askedPitch === undefined) return {}; - let from = _viewer.camera.pitch; + let from = cameraOf(_viewer).pose().pitch; if (!(m.askedPitch > from)) return {}; if (m.hpr) { // At the same pivot pitch a longer range looks down more steeply (the @@ -2356,11 +2285,7 @@ function retargetTiltAfterZoom(m) { for (let i = 0; i < 4; i += 1) { const error = from - pivotCameraPitch(m.target, m.hpr, m.hpr.pitch); if (Math.abs(error) < 1e-7) break; - const pitch = Cesium.Math.clamp( - m.hpr.pitch + error, - -Cesium.Math.PI_OVER_TWO, - cap, - ); + const pitch = clamp(m.hpr.pitch + error, -PI_OVER_TWO, cap); if (pitch === m.hpr.pitch) break; m.hpr.pitch = pitch; } @@ -2380,14 +2305,14 @@ function retargetTiltAfterZoom(m) { m.elapsed = 0; m.durationS = Math.max( ONCE.durationS, - Math.abs(Cesium.Math.toDegrees(goal - from)) / TILT_TO_DEG_S, + Math.abs(toDegrees(goal - from)) / TILT_TO_DEG_S, ); const limited = goal !== m.askedPitch; return { - pitchDeg: Math.round(Cesium.Math.toDegrees(goal)), + pitchDeg: Math.round(toDegrees(goal)), note: limited ? tiltHorizonNote(goal) - : `The tilt now reaches ${Math.round(Cesium.Math.toDegrees(goal))}°.`, + : `The tilt now reaches ${Math.round(toDegrees(goal))}°.`, }; } @@ -2462,12 +2387,10 @@ export function flyRoute( error: 'The selected route has an invalid waypoint.', }; } - const pts = route.path.map((p) => - Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0), - ); + const pts = route.path.map((p) => fromDegrees(p.lon, p.lat, p.height || 0)); const cumM = [0]; for (let i = 1; i < pts.length; i += 1) { - cumM.push(cumM[i - 1] + Cesium.Cartesian3.distance(pts[i - 1], pts[i])); + cumM.push(cumM[i - 1] + distance(pts[i - 1], pts[i])); } if (!Number.isFinite(cumM.at(-1)) || cumM.at(-1) <= 0) { return { @@ -2485,8 +2408,8 @@ export function flyRoute( speed, floorFn, warmFn, - probeFn: (cells) => probeMeshFloorM(_viewer?.scene, cells), - cameraHeightM: _viewer?.camera?.positionCartographic?.height, + probeFn: (cells) => probeMeshFloorM(_viewer, cells), + cameraHeightM: findCamera(_viewer)?.pose().height, reducedMotion: prefersReducedMotion(), }), ); diff --git a/src/cctvFocusPolicy.js b/src/cctvFocusPolicy.js index e11c1e1caa..1cabba37f3 100644 --- a/src/cctvFocusPolicy.js +++ b/src/cctvFocusPolicy.js @@ -1,22 +1,23 @@ /** * Activates the nearest CCTV record on layer enable and flies only when no - * aircraft tracker or cockpit camera owns the view. + * followed target or cockpit camera owns the view. * @param {Object} options Layer-enable focus inputs. - * @param {*} options.trackedEntity Current Cesium tracked entity, if any. + * @param {*} options.followed What the camera follows, if anything + * (`followedOf`). * @param {boolean} options.cockpitActive Whether cockpit mode owns the camera. * @param {() => (string|null)} options.activate Nearest-camera activation. * @param {(cameraId: string) => *} options.fly Optional camera flight. * @returns {*} Activated camera ID for a held view, or the flight result. */ export function runCctvLayerEnableFocus({ - trackedEntity = null, + followed = null, cockpitActive = false, activate, fly, } = {}) { const cameraId = activate?.(); if (!cameraId) return false; - if (trackedEntity || cockpitActive) return cameraId; + if (followed || cockpitActive) return cameraId; return fly?.(cameraId); } @@ -25,11 +26,11 @@ export function runCctvLayerEnableFocus({ * chain. Either observation suppresses the optional CCTV focus flight. * @param {Object} [before={}] Ownership immediately before the await. * @param {Object} [after={}] Ownership immediately after the await. - * @returns {{ trackedEntity: *, cockpitActive: boolean }} Conservative ownership. + * @returns {{ followed: *, cockpitActive: boolean }} Conservative ownership. */ function mergeCctvEnableOwnership(before = {}, after = {}) { return { - trackedEntity: before.trackedEntity || after.trackedEntity || null, + followed: before.followed || after.followed || null, cockpitActive: !!(before.cockpitActive || after.cockpitActive), }; } @@ -60,7 +61,7 @@ export async function runCctvLayerEnableTransition({ const ownershipBefore = readOwnership?.() || {}; if (target === true) { debug?.('[UI:CCTV] ownership before setEnabled await', { - trackedId: ownershipBefore.trackedEntity?.id ?? null, + trackedId: ownershipBefore.followed?.key ?? null, cockpitActive: !!ownershipBefore.cockpitActive, }); } @@ -68,7 +69,7 @@ export async function runCctvLayerEnableTransition({ const ownershipAfter = readOwnership?.() || {}; if (target === true) { debug?.('[UI:CCTV] ownership after setEnabled await', { - trackedId: ownershipAfter.trackedEntity?.id ?? null, + trackedId: ownershipAfter.followed?.key ?? null, cockpitActive: !!ownershipAfter.cockpitActive, }); } diff --git a/src/cctvFocusPolicy.test.mjs b/src/cctvFocusPolicy.test.mjs index 333926a0f9..fd0913294d 100644 --- a/src/cctvFocusPolicy.test.mjs +++ b/src/cctvFocusPolicy.test.mjs @@ -8,8 +8,8 @@ import { test('CCTV layer enable activates nearest without stealing a tracked or cockpit view', () => { for (const ownership of [ - { trackedEntity: { id: 'tracked-plane' }, cockpitActive: false }, - { trackedEntity: null, cockpitActive: true }, + { followed: { key: 'tracked-plane' }, cockpitActive: false }, + { followed: null, cockpitActive: true }, ]) { const calls = []; const result = runCctvLayerEnableFocus({ @@ -48,15 +48,15 @@ test('CCTV layer enable activates nearest without stealing a tracked or cockpit }); test('CCTV enable retains a pre-await tracking snapshot when tracking clears during enable', async () => { - let trackedEntity = { id: 'tracked-plane' }; + let followed = { key: 'tracked-plane' }; let flyCalls = 0; const diagnostics = []; const result = await runCctvLayerEnableTransition({ target: true, - readOwnership: () => ({ trackedEntity, cockpitActive: false }), + readOwnership: () => ({ followed, cockpitActive: false }), setEnabled: async () => { await Promise.resolve(); - trackedEntity = null; + followed = null; }, shouldFocus: () => true, activate: () => 'cam-near', @@ -83,7 +83,7 @@ test('CCTV disable transition does not emit enable-ownership diagnostics', async const result = await runCctvLayerEnableTransition({ target: false, - readOwnership: () => ({ trackedEntity: { id: 'tracked-plane' }, cockpitActive: false }), + readOwnership: () => ({ followed: { key: 'tracked-plane' }, cockpitActive: false }), setEnabled: async (target) => transitions.push(target), shouldFocus: () => true, activate: () => 'cam-near', diff --git a/src/celestialRing.js b/src/celestialRing.js index 525ded44ef..65e128ea85 100644 --- a/src/celestialRing.js +++ b/src/celestialRing.js @@ -1,5 +1,25 @@ -import * as Cesium from 'cesium'; import { governorRequestRender } from './renderGovernor.js'; +import { + cameraOf, + canvasOf, + findCamera, + findFrame, + findQuery, +} from './render/rendererOf.js'; +import { + moonPositionInertial, + sunPositionInertial, + temeToPseudoFixed, +} from './geo/celestial.js'; +import { WGS84 } from './geo/ellipsoid.js'; +import { frameVector } from './geo/frames.js'; +import { + dot, + magnitude, + normalize, + PI_OVER_TWO, + toRadians, +} from './geo/vector.js'; import { worldClock, worldTimeFor } from './time/worldClock.js'; // The ring shows the sun and moon at the time the sky is drawn. @@ -38,7 +58,13 @@ const EPHEMERIS_WORLD_STEP_MS = 60_000; const RING_INSET_PX = 11; const MARKER_INSET_PX = 36; const COLLIDING_MARKER_EXTRA_INSET_PX = 32; -const MARKER_COLLISION_ANGLE = Cesium.Math.toRadians(6); +const MARKER_COLLISION_ANGLE = toRadians(6); +/** The ellipsoid's largest radius, metres. */ +const EARTH_MAX_RADIUS_M = Math.max( + WGS84.radii.x, + WGS84.radii.y, + WGS84.radii.z, +); const FULL_GLOBE_RADIUS_RATIO = 0.61; const TAU = Math.PI * 2; // This overlay is a secondary HUD treatment. Keep it smooth while reserving @@ -218,7 +244,7 @@ export function isFullGlobeInsideKeyhole(geometry, wasVisible = false) { /** Return the Earth-disc radius in CSS pixels for a perspective camera. */ export function earthDiscScreenRadius(cameraDistance, viewportHeight, fovy) { - const earthRadiusM = Cesium.Ellipsoid.WGS84.maximumRadius; + const earthRadiusM = EARTH_MAX_RADIUS_M; if ( !Number.isFinite(cameraDistance) || cameraDistance <= earthRadiusM || @@ -234,15 +260,19 @@ export function earthDiscScreenRadius(cameraDistance, viewportHeight, fovy) { return Number.isFinite(radius) && radius > 0 ? radius : null; } +const EARTH_CENTRE = Object.freeze({ x: 0, y: 0, z: 0 }); + /** - * Project the visible Earth disc into viewport coordinates. + * Project the visible Earth disc into viewport coordinates, through the + * renderer's camera pose and its query port's projection. * Shared by full-globe UI treatments that must agree on visual containment. * - * @param {object} viewer - Cesium Viewer-like object. + * @param {object} viewer - The scene object the renderer is found from. * @param {number} width - Viewport width in CSS pixels. * @param {number} height - Viewport height in CSS pixels. - * @param {object} [scratchCenter] - Reusable Cesium Cartesian2 result. - * @param {object} [scratchToCenter] - Reusable Cesium Cartesian3 result. + * @param {{x:number,y:number}} [scratchCenter] - Takes the projected centre. + * @param {{x:number,y:number,z:number}} [scratchToCenter] - Takes the + * vector from the eye to the Earth's centre. * @returns {object|null} */ export function projectEarthDiscToViewport( @@ -252,36 +282,32 @@ export function projectEarthDiscToViewport( scratchCenter = undefined, scratchToCenter = undefined, ) { - const camera = viewer?.camera; - const scene = viewer?.scene; - if (!camera || !scene || !(width > 0) || !(height > 0)) return null; + const camera = findCamera(viewer); + if (!camera || !(width > 0) || !(height > 0)) return null; + const pose = camera.pose(); + const eye = pose.position; - const distance = Cesium.Cartesian3.magnitude(camera.positionWC); + const distance = magnitude(eye); + if (!Number.isFinite(distance) || distance <= EARTH_MAX_RADIUS_M) return null; + + const toCenter = scratchToCenter || { x: 0, y: 0, z: 0 }; + toCenter.x = -eye.x; + toCenter.y = -eye.y; + toCenter.z = -eye.z; + if (dot(pose.direction, toCenter) <= 0) return null; + + const projected = findQuery(viewer)?.project(EARTH_CENTRE); if ( - !Number.isFinite(distance) || - distance <= Cesium.Ellipsoid.WGS84.maximumRadius + !projected || + !Number.isFinite(projected.x) || + !Number.isFinite(projected.y) ) return null; + const center = scratchCenter || { x: 0, y: 0 }; + center.x = projected.x; + center.y = projected.y; - const toCenter = Cesium.Cartesian3.negate( - camera.positionWC, - scratchToCenter || new Cesium.Cartesian3(), - ); - if (Cesium.Cartesian3.dot(camera.directionWC, toCenter) <= 0) return null; - - const center = Cesium.SceneTransforms.worldToWindowCoordinates( - scene, - Cesium.Cartesian3.ZERO, - scratchCenter, - ); - if (!center || !Number.isFinite(center.x) || !Number.isFinite(center.y)) - return null; - - const earthRadius = earthDiscScreenRadius( - distance, - height, - camera.frustum?.fovy, - ); + const earthRadius = earthDiscScreenRadius(distance, height, pose.fovy); if (!earthRadius) return null; const keyhole = getKeyholeGeometry(width, height); @@ -396,14 +422,23 @@ let rings = 0; */ export class CelestialRing { /** - * @param {Cesium.Viewer} viewer - * @param {{enabled?:boolean,onAutoDisable?:Function,store:object}} options + * @param {object} viewer - The scene object the renderer is found from; + * the ring reads its canvas and container (DOM) and reaches the rest + * through the renderer's camera, frame and query ports. + * @param {{enabled?:boolean,onAutoDisable?:Function,store:object,preciseFrameAt?:Function}} options * `store` is the celestial ring store (src/ui/stores/celestialRing.js); * the keyhole helpers here stay free of Vue for the packages that use - * them. + * them. `preciseFrameAt(ms)` gives the ICRF-to-fixed rotation as axes, + * or null while its tables have not loaded; without it, or while it has + * no answer, the ring uses the pseudo-fixed frame. */ - constructor(viewer, { enabled = true, onAutoDisable = null, store }) { + constructor( + viewer, + { enabled = true, onAutoDisable = null, store, preciseFrameAt = null }, + ) { this.viewer = viewer; + this._preciseFrameAt = + typeof preciseFrameAt === 'function' ? preciseFrameAt : null; this.enabled = !!enabled; this.visible = false; this._onAutoDisable = @@ -426,18 +461,14 @@ export class CelestialRing { this._moonCanvas = null; this._moonCtx = null; - this._sunInertial = new Cesium.Cartesian3(); - this._moonInertial = new Cesium.Cartesian3(); - this._sunFixed = new Cesium.Cartesian3(); - this._moonFixed = new Cesium.Cartesian3(); - this._toCenter = new Cesium.Cartesian3(); - this._screenCenter = new Cesium.Cartesian2(); - this._fixedMatrix = new Cesium.Matrix3(); + this._sunFixed = { x: 0, y: 0, z: 0 }; + this._moonFixed = { x: 0, y: 0, z: 0 }; + this._toCenter = { x: 0, y: 0, z: 0 }; + this._screenCenter = { x: 0, y: 0 }; this._initView(store); - this._removePostRender = viewer.scene.postRender.addEventListener(() => - this._draw(), - ); + this._removePostRender = + findFrame(viewer)?.on('postRender', () => this._draw()) ?? null; // Pre-existing staleness fix (perf wave 2 review): the ephemeris was // sampled once per visible-enable from the FROZEN app clock, so the // sun/moon markers aged with the app. Resample real wall time each @@ -453,8 +484,6 @@ export class CelestialRing { governorRequestRender('celestial-ephemeris'); }, 60_000); // A jump in the world time moves the sun and moon at once. - this._skyDate = new Date(); - this._skyTime = new Cesium.JulianDate(); // Played through, the sky moves on each minute of world time it passes. this._ephemerisWorldMs = null; this._unsubscribeWorldTime = worldClock.subscribe(({ timeMs }) => { @@ -554,9 +583,14 @@ export class CelestialRing { }); } + /** The renderer's canvas; a viewer with no renderer bound, its own. */ + _canvas() { + return canvasOf(this.viewer); + } + /** Whether the current camera already frames the complete globe inside the keyhole. */ isGlobeFullyVisible() { - const canvas = this.viewer.scene.canvas; + const canvas = this._canvas(); const width = canvas.clientWidth || canvas.width; const height = canvas.clientHeight || canvas.height; if (!(width > 0 && height > 0)) return false; @@ -571,13 +605,15 @@ export class CelestialRing { * @returns {boolean} Whether a valid camera flight was started. */ focusFullGlobe({ duration = 2.4 } = {}) { - const canvas = this.viewer.scene.canvas; + const canvas = this._canvas(); const height = canvas.clientHeight || canvas.height; - const cartographic = this.viewer.camera.positionCartographic; - const fovy = this.viewer.camera.frustum?.fovy; + const camera = cameraOf(this.viewer); + const pose = camera.pose(); + const fovy = pose.fovy; if ( !(height > 0) || - !cartographic || + !Number.isFinite(pose.lon) || + !Number.isFinite(pose.lat) || !Number.isFinite(fovy) || fovy <= 0 || fovy >= Math.PI @@ -585,7 +621,7 @@ export class CelestialRing { return false; } - const earthRadius = Cesium.Ellipsoid.WGS84.maximumRadius; + const earthRadius = EARTH_MAX_RADIUS_M; const keyholeRadius = getKeyholeGeometry( canvas.clientWidth || canvas.width, height, @@ -600,27 +636,25 @@ export class CelestialRing { this._focusInProgress = true; const finishFocus = () => { this._focusInProgress = false; - this.viewer.scene.requestRender?.(); + findFrame(this.viewer)?.requestRender('celestial-focus'); }; - this.viewer.camera.flyTo({ - destination: Cesium.Cartesian3.fromRadians( - cartographic.longitude, - cartographic.latitude, - altitude, - ), - orientation: { - heading: this.viewer.camera.heading, - pitch: -Cesium.Math.PI_OVER_TWO, - roll: 0, + camera.flyTo( + { lon: pose.lon, lat: pose.lat, height: altitude }, + { + orientation: { + heading: pose.heading, + pitch: -PI_OVER_TWO, + roll: 0, + }, + durationS: duration, + easing: 'cubicInOut', + onComplete: finishFocus, + onCancel: () => { + finishFocus(); + if (!this.isGlobeFullyVisible()) this._autoDisable(); + }, }, - duration, - easingFunction: Cesium.EasingFunction.CUBIC_IN_OUT, - complete: finishFocus, - cancel: () => { - finishFocus(); - if (!this.isGlobeFullyVisible()) this._autoDisable(); - }, - }); + ); return true; } @@ -671,31 +705,16 @@ export class CelestialRing { /** * Sample Earth-fixed directions once per enable. Camera movement only * re-projects these cached vectors; it never re-runs the planetary model. + * The precise ICRF frame serves once its tables have loaded, the + * pseudo-fixed one before. + * @param {number} ms Epoch milliseconds. */ - _updateEphemeris(time) { + _updateEphemeris(ms) { if (!this._ephemerisDirty) return true; - Cesium.Simon1994PlanetaryPositions.computeSunPositionInEarthInertialFrame( - time, - this._sunInertial, - ); - Cesium.Simon1994PlanetaryPositions.computeMoonPositionInEarthInertialFrame( - time, - this._moonInertial, - ); - const matrix = - Cesium.Transforms.computeIcrfToFixedMatrix(time, this._fixedMatrix) || - Cesium.Transforms.computeTemeToPseudoFixedMatrix(time, this._fixedMatrix); - if (!matrix) return false; - - Cesium.Matrix3.multiplyByVector(matrix, this._sunInertial, this._sunFixed); - Cesium.Matrix3.multiplyByVector( - matrix, - this._moonInertial, - this._moonFixed, - ); - Cesium.Cartesian3.normalize(this._sunFixed, this._sunFixed); - Cesium.Cartesian3.normalize(this._moonFixed, this._moonFixed); + const frame = this._preciseFrameAt?.(ms) ?? temeToPseudoFixed(ms); + this._sunFixed = normalize(frameVector(frame, sunPositionInertial(ms))); + this._moonFixed = normalize(frameVector(frame, moonPositionInertial(ms))); this._ephemerisDirty = false; this._ephemerisUpdateCount += 1; return true; @@ -792,7 +811,7 @@ export class CelestialRing { const now = performance.now(); if (now < this._nextDrawAt) return; this._nextDrawAt = now + 1000 / CELESTIAL_MAX_FRAME_RATE; - const canvas = this.viewer.scene.canvas; + const canvas = this._canvas(); const width = canvas.clientWidth || canvas.width; const height = canvas.clientHeight || canvas.height; if (!(width > 0 && height > 0)) return; @@ -822,19 +841,17 @@ export class CelestialRing { return; } - this._skyDate.setTime(skyTime()); - const time = Cesium.JulianDate.fromDate(this._skyDate, this._skyTime); - if (!this._updateEphemeris(time)) return; + if (!this._updateEphemeris(skyTime())) return; this._present({ ephemerisUpdates: String(this._ephemerisUpdateCount) }); - const camera = this.viewer.camera; + const pose = cameraOf(this.viewer).pose(); const sunProjection = celestialScreenAngle( - Cesium.Cartesian3.dot(this._sunFixed, camera.rightWC), - Cesium.Cartesian3.dot(this._sunFixed, camera.upWC), + dot(this._sunFixed, pose.right), + dot(this._sunFixed, pose.up), this._sunAngle, ); const moonProjection = celestialScreenAngle( - Cesium.Cartesian3.dot(this._moonFixed, camera.rightWC), - Cesium.Cartesian3.dot(this._moonFixed, camera.upWC), + dot(this._moonFixed, pose.right), + dot(this._moonFixed, pose.up), this._moonAngle, ); if (sunProjection.stable) this._sunAngle = sunProjection.angle; diff --git a/src/celestialRingView.test.mjs b/src/celestialRingView.test.mjs index c834ed53a6..841f42d746 100644 --- a/src/celestialRingView.test.mjs +++ b/src/celestialRingView.test.mjs @@ -9,7 +9,14 @@ import { createPinia } from 'pinia'; import { useCelestialRingStore } from './ui/stores/celestialRing.js'; import CelestialRingView from './ui/views/panels/CelestialRing.vue'; import * as Cesium from 'cesium'; -import { CelestialRing } from './celestialRing.js'; +import { + CelestialRing, + earthDiscScreenRadius, + projectEarthDiscToViewport, +} from './celestialRing.js'; +import { bindRenderer } from './render/rendererOf.js'; +import { bindFakeCesiumCamera } from './testSupport/fakeCameraPort.mjs'; +import { fakeSceneFrame } from './testSupport/fakeCesiumScene.mjs'; // happy-dom has no 2D context; a stand-in takes every drawing call. const context = new Proxy( @@ -19,18 +26,26 @@ const context = new Proxy( globalThis.HTMLCanvasElement.prototype.getContext = () => context; function fakeViewer(container) { - return { + const canvas = { + clientWidth: 400, + clientHeight: 300, + width: 400, + height: 300, + }; + const viewer = { container, + canvas, camera: { rightWC: new Cesium.Cartesian3(1, 0, 0), upWC: new Cesium.Cartesian3(0, 1, 0), }, scene: { - canvas: { clientWidth: 400, clientHeight: 300, width: 400, height: 300 }, + canvas, postRender: { addEventListener: () => () => {} }, requestRender() {}, }, }; + return bindFakeCesiumCamera(viewer, { frame: fakeSceneFrame(viewer) }); } function fixture(t) { @@ -157,8 +172,7 @@ const FRAMED = { /** Run one rendered frame, past the frame-rate throttle. */ function frame(ring, disc) { ring._projectedEarthDisc = () => disc; - // Fixed sun and moon directions; Cesium's own model would fetch its - // orientation data. + // Fixed sun and moon directions, so markers do not move with the clock. ring._updateEphemeris = () => { if (ring._ephemerisDirty) { Cesium.Cartesian3.clone(new Cesium.Cartesian3(1, 0, 0), ring._sunFixed); @@ -249,3 +263,119 @@ test('a ring the store no longer shows stops drawing', async (t) => { assert.equal(earlier.enabled, true); assert.equal(disabled, 0); }); + +test('the sun and moon directions are the planetary model in the pseudo-fixed frame', () => { + const pinia = createPinia(); + const ring = new CelestialRing(fakeViewer({}), { + enabled: false, + store: useCelestialRingStore(pinia), + // The precise frame's tables have not loaded. + preciseFrameAt: () => null, + }); + const ms = Date.UTC(2026, 10, 7, 12, 30); + ring._ephemerisDirty = true; + assert.equal(ring._updateEphemeris(ms), true); + // Cesium's own, before the sky has loaded the precise frame's tables. + const time = Cesium.JulianDate.fromDate(new Date(ms)); + const matrix = Cesium.Transforms.computeTemeToPseudoFixedMatrix(time); + const expected = (inertial) => + Cesium.Cartesian3.normalize( + Cesium.Matrix3.multiplyByVector( + matrix, + inertial, + new Cesium.Cartesian3(), + ), + new Cesium.Cartesian3(), + ); + const sun = expected( + Cesium.Simon1994PlanetaryPositions.computeSunPositionInEarthInertialFrame( + time, + ), + ); + const moon = expected( + Cesium.Simon1994PlanetaryPositions.computeMoonPositionInEarthInertialFrame( + time, + ), + ); + for (const [got, want] of [ + [ring._sunFixed, sun], + [ring._moonFixed, moon], + ]) + for (const axis of ['x', 'y', 'z']) + assert.ok(Object.is(got[axis], want[axis]), axis); + assert.equal(ring._ephemerisUpdateCount, 1); + ring.destroy(); +}); + +test('the projected disc reads the camera and query ports', () => { + const canvas = { clientWidth: 800, clientHeight: 600 }; + const viewer = { canvas }; + const distance = 3 * 6378137; + const pose = { + position: { x: distance, y: 0, z: 0 }, + direction: { x: -1, y: 0, z: 0 }, + fovy: Math.PI / 3, + }; + const unbind = bindRenderer(viewer, { + canvas, + camera: { pose: () => pose }, + query: { project: () => ({ x: 410, y: 290 }) }, + }); + const toCenter = { x: 0, y: 0, z: 0 }; + const centre = { x: 0, y: 0 }; + const disc = projectEarthDiscToViewport(viewer, 800, 600, centre, toCenter); + assert.equal(disc.earthCenterX, 410); + assert.equal(disc.earthCenterY, 290); + assert.deepEqual(centre, { x: 410, y: 290 }); + // The scratch takes the eye-to-centre vector, as callers read it after. + assert.deepEqual(toCenter, { x: -distance, y: -0, z: -0 }); + assert.ok( + Math.abs( + disc.earthRadius - earthDiscScreenRadius(distance, 600, pose.fovy), + ) < 1e-9, + ); + // Facing away: null, with the eye-to-centre vector still written, as + // radio navigation reads it after. + pose.direction = { x: 1, y: 0, z: 0 }; + const away = { x: 0, y: 0, z: 0 }; + assert.equal(projectEarthDiscToViewport(viewer, 800, 600, null, away), null); + assert.deepEqual(away, { x: -distance, y: -0, z: -0 }); + // Inside the ellipsoid's largest radius: null, the scratch untouched. + pose.position = { x: 6378137, y: 0, z: 0 }; + const inside = { x: 1, y: 2, z: 3 }; + assert.equal( + projectEarthDiscToViewport(viewer, 800, 600, null, inside), + null, + ); + assert.deepEqual(inside, { x: 1, y: 2, z: 3 }); + unbind(); +}); + +test('the precise frame serves once it answers', () => { + const pinia = createPinia(); + // A quarter turn about z: x goes to y. + const quarter = { + x: { x: 0, y: 1, z: 0 }, + y: { x: -1, y: 0, z: 0 }, + z: { x: 0, y: 0, z: 1 }, + }; + const ring = new CelestialRing(fakeViewer({}), { + enabled: false, + store: useCelestialRingStore(pinia), + preciseFrameAt: () => quarter, + }); + const ms = Date.UTC(2026, 10, 7, 12, 30); + ring._ephemerisDirty = true; + ring._updateEphemeris(ms); + const time = Cesium.JulianDate.fromDate(new Date(ms)); + const sun = Cesium.Cartesian3.normalize( + Cesium.Simon1994PlanetaryPositions.computeSunPositionInEarthInertialFrame( + time, + ), + new Cesium.Cartesian3(), + ); + assert.ok(Math.abs(ring._sunFixed.x + sun.y) < 1e-12); + assert.ok(Math.abs(ring._sunFixed.y - sun.x) < 1e-12); + assert.ok(Math.abs(ring._sunFixed.z - sun.z) < 1e-12); + ring.destroy(); +}); diff --git a/src/cockpitCloudEffects.js b/src/cockpitCloudEffects.js index c1cc796b45..db1495391d 100644 --- a/src/cockpitCloudEffects.js +++ b/src/cockpitCloudEffects.js @@ -1,5 +1,6 @@ import { applicationServices } from './services/application.js'; -import * as Cesium from 'cesium'; +import { toRadians } from './geo/vector.js'; +import { findCamera } from './render/rendererOf.js'; import { greatCircleMeters } from './geoDistance.js'; import { deriveWeatherEffectProfile, @@ -341,15 +342,14 @@ class CockpitCloudEffectsController { } cameraPoint() { - const cartographic = this.viewer?.camera?.positionCartographic; - if (!cartographic) return null; - const latitude = Cesium.Math.toDegrees(cartographic.latitude); - const longitude = Cesium.Math.toDegrees(cartographic.longitude); + const pose = this.viewer ? findCamera(this.viewer)?.pose() : null; + if (!pose) return null; + const { lat: latitude, lon: longitude } = pose; if (![latitude, longitude].every(Number.isFinite)) return null; return { latitude, longitude, - altitudeM: Math.max(0, Number(cartographic.height) || 0), + altitudeM: Math.max(0, Number(pose.height) || 0), }; } @@ -543,7 +543,7 @@ class CockpitCloudEffectsController { render(timeSec) { const gl = this.gl; if (!gl || !this.program || !this.locations) return; - const windRadians = Cesium.Math.toRadians(this.windDirectionDeg); + const windRadians = toRadians(this.windDirectionDeg); const windScale = 0.008 + this.windStrength * 0.022; gl.useProgram(this.program); gl.uniform2f( diff --git a/src/cockpitMarkup.test.mjs b/src/cockpitMarkup.test.mjs index 06db3aeff1..3c1e3ed142 100644 --- a/src/cockpitMarkup.test.mjs +++ b/src/cockpitMarkup.test.mjs @@ -26,10 +26,7 @@ import { setSignalCollapsed, } from './ui/cockpitLayout.js'; import { createBriefState } from './ui/cockpitBriefPages.js'; -import { - publishBriefView, - setBriefAutoRotate, -} from './ui/cockpitBriefing.js'; +import { publishBriefView, setBriefAutoRotate } from './ui/cockpitBriefing.js'; import { CockpitDisplayPortal } from './ui/cockpitDisplayPortal.js'; import { _handleContextLayerChange } from './ui/contextLayerChanges.js'; import { clearSelectedLayers } from './ui/contextActions.js'; @@ -228,7 +225,7 @@ test('Cockpit Escape handling precedes form-control shortcut suppression and foc assert.doesNotMatch(exit, /applyTrackedCameraFrame/); assert.match( ui, - /restoreTrackingFrame: \(entity\) => \{[\s\S]*?gevTrackedId[\s\S]*?flightsLayer\.refocusTrackedById[\s\S]*?militaryFlightsLayer\.refocusTrackedById/, + /restoreTrackingFrame: \(entity\) => \{[\s\S]*?readEntityRecord\(entity\)\?\.trackedId[\s\S]*?flightsLayer\.refocusTrackedById[\s\S]*?militaryFlightsLayer\.refocusTrackedById/, 'Cockpit exit must return camera-frame ownership through the source layer so Contact Focus cannot accumulate a second owner', ); }); @@ -294,14 +291,14 @@ test('the Contact panel never hides itself out from under its own NEXT button', ); }); -test('the cockpit reads its aircraft from the layer that owns Cesium tracking', () => { +test('the cockpit reads its aircraft from the layer the camera follows', () => { const read = readAircraftInfo.toString(); assert.ok(read, 'readAircraftInfo is missing'); assert.match(read, /resolveTrackedAircraftInfo\(\{/); - assert.match(read, /gevTrackedId/); - // In cockpit mode the controller moves the entity off viewer.trackedEntity, - // so its own handle is the tracked identity there. - assert.match(read, /this\.viewer\?\.trackedEntity \|\| this\.trackedEntity/); + assert.match(read, /trackedId: followed\?\.key/); + // In cockpit mode the controller stops the camera following, so its own + // handle is the tracked identity there. + assert.match(read, /followedOf\(this\.viewer\) \|\| this\.trackedFollow/); }); test('programmatic Context layer changes cannot bypass explicit expansion policy', () => { @@ -438,13 +435,10 @@ test('Cockpit owns a focused shared Display portal and compact Radio controls', /data-cockpit-launcher="radio"[\s\S]*?id="cockpit-radio-toggle-btn"/, ); const cockpitRadio = html.match( - /id="cockpit-radio-panel"[\s\S]*?<\/div>\s*<\/div>\s*<\/aside>/, + /id="cockpit-radio-panel"[\s\S]*?<\/div>\s*<\/div>\s*
Effects<[\s\S]*?id="celestial-toggle"/, ); assert.equal( (html.match(/id="param-slider-panel"/g) || []).length, @@ -811,18 +805,27 @@ test('Reset releases Contact camera ownership through its selection-preserving r ); assert.match(ui, /onReset: \(\) => this\.resetToGlobeView\(\)/); assert.match(ui, /this\._connectGlobeReset\?\.\(this\._locationControls\)/); - assert.match(controls, /reset\(\) \{\s*if \(!this\.destroyed\) return this\.onReset\(\);/); + assert.match( + controls, + /reset\(\) \{\s*if \(!this\.destroyed\) return this\.onReset\(\);/, + ); // Both reset buttons ask the one reset owner. const globeActions = fs.readFileSync( path.join(ROOT, 'src', 'ui', 'views', 'panels', 'GlobeActions.vue'), 'utf8', ); - assert.match(globeActions, /id="reset-globe-view"[^>]*@click="act\('reset'\)"/); + assert.match( + globeActions, + /id="reset-globe-view"[^>]*@click="act\('reset'\)"/, + ); const cockpitView = readRadioSource( new URL('./ui/views/CockpitView.vue', import.meta.url), 'utf8', ); - assert.match(cockpitView, /id="cockpit-reset-globe"[^>]*@click="globe\.act\('reset'\)"/); + assert.match( + cockpitView, + /id="cockpit-reset-globe"[^>]*@click="globe\.act\('reset'\)"/, + ); assert.match( cockpitEnter.toString(), /Object\.assign\(this\.presence, \{\s*active: true,/, @@ -1170,7 +1173,7 @@ test('cockpit route direction uses self-contained vector artwork, not a font lig test('cockpit aircraft handoff invalidates the prior world-position anchor', () => { const match = _adoptTrackedEntity.toString(); assert.ok(match, 'cockpit tracked-entity handoff block is missing'); - assert.match(match, /this\.viewer\.trackedEntity = undefined;/); + assert.match(match, /stopFollowing\(this\.viewer\);/); assert.match(match, /this\.cockpitAnchorValid = false;/); assert.match( match, @@ -1193,7 +1196,10 @@ test('cockpit summary presents the focused item as Contact', () => { const match = html.match(/