Merge remote-tracking branch 'origin/main' into mazeyar/shared-terrain-surface

# Conflicts:
#	src/app/constructCatalog.js

.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

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.
 
 ---
 

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.

README.md

@@ -60,7 +60,7 @@ Start with the included data sources, then add your own. Each layer is a separat
 - **📡 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 swaps from glyph to 3D model as you close in.
 - **🎨 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.

changelog.d/1579-render-failure-notice.md

@@ -0,0 +1,6 @@
+- When the globe stops drawing after a render error or a lost WebGL context,
+  an alert dialog says so instead of leaving a frozen or black globe behind
+  working controls. Retry restarts drawing (Reload after a lost context), and
+  Reset view reopens the app without the view restored from the address bar.
+  Cesium's "Rendering has stopped" panel no longer appears in the app
+  (German, @gekh, #1579).

changelog.d/1686-cockpit-subjects.md

@@ -0,0 +1,12 @@
+- Let an application add its own Cockpit subjects through
+  `services.cockpitSubjects`. A provider supplies the subject's position,
+  heading and HUD (in the page's language, via `getLocale` and
+  `onLocaleChange` from `./i18n`); the camera can follow it without the
+  ground clamp, anchored exactly on it, and a generic HUD adds source rows, a
+  banner, a veil (off under reduced motion) and a bottom progress line. The
+  Rail and Transit layers expose read and hold APIs so a selected train or
+  vehicle can be ridden, and `./layers/rail/paths` is exported; that export
+  and the read APIs are experimental. `docs/APPLICATION.md` shows a minimal
+  provider. GEV itself registers none, and entry to the built-in aircraft,
+  satellite and vessel views is unchanged; a provider's subject takes entry
+  when it was selected after them (Denis Groshev, @ZloyS, #1686).

changelog.d/1688-transit-terrain-height-cache.md

@@ -0,0 +1,7 @@
+- Fix the page freezing for seconds at a time with Transit on over a terrain
+  globe, most visibly while zooming over a large fleet. Every reread asked the
+  terrain for the height of every trail fix of every vehicle in view; heights
+  are now kept per point, read again only while the camera moves or tiles
+  load, and read within a time budget that puts vehicle positions first.
+  Switching the terrain provider or globe starts the kept heights afresh
+  (mazy1998, review by kvnloo, #1688).

changelog.d/1689-shared-terrain-surface.md

@@ -0,0 +1,5 @@
+- Read terrain heights through one shared, cached and budgeted reader
+  (`src/services/terrainSurface.js`) in Transit, Rail, Bike Share and the local
+  data layers. Opening Data Centers no longer blocks the page for over two
+  seconds, opening Bike Share for most of a second, and Rail asks the terrain
+  about a twentieth as often (mazy1998, #1689).

changelog.d/1698-new-strings-translations.md

@@ -0,0 +1,5 @@
+- Fix the translations of the strings added since the last review (News,
+  Data Library, Wildlife Sightings, Shipwrecks, Rail, the vessel and orbital
+  cockpits) in all twelve languages: neutral side labels and counts no longer
+  break the sentence, terms follow each glossary, and Traditional Chinese
+  follows Simplified Chinese again (German, @gekh, #1698).

changelog.d/1714-fleet-models.md

@@ -0,0 +1,8 @@
+- Draw every 3D model from the project's procedural fleet set: 121 models
+  (about 2 MB, MIT like the code) chosen per vehicle by type and drawn life
+  size, replacing the eight third-party aircraft models. Flights, Military
+  Flights and Local ADS-B pick a model by ICAO type, class and emitter
+  category; Vessels, Transit and Rail now draw models too, under the same 3D
+  toggle and distances, a ship at its AIS length and beam and a tram, bus or
+  train in its mode or category colour. The whole set loads once when a layer
+  starts (samehkhamis, #1714).

changelog.d/1715-vessel-typical-length.md

@@ -0,0 +1,3 @@
+- Draw a vessel whose feed sends no length at its ship type's typical size, so
+  a cruise ship or container ship no longer shows as its type's smallest model
+  (samehkhamis, #1715).

changelog.d/1723-cctv-panel-collapse-on-disable.md

@@ -0,0 +1,5 @@
+- Collapse the CCTV panel when the layer is switched off. It stayed open with
+  an empty frame and a meta line that still described the last camera; the
+  meta line of a disabled layer now reads the catalog count. Contacts, Space
+  Missions and Clear selected data layers leave the panel as it is
+  (asturksever, #1723).

changelog.d/1729-fleet-ground-vehicles.md

@@ -0,0 +1,5 @@
+- Draw airport ground vehicles and ground stations as what they are instead of
+  the generic plane. An airport vehicle (type `ZVEH`) is a fire truck, pushback
+  tug, van or car by its callsign, a ground station (`GRND`) is a new 11.8 m
+  radio mast, and one with no altitude stands on the ground instead of at the
+  10 km airborne default (samehkhamis, #1729).

changelog.d/1730-airport-vehicle-models.md

@@ -0,0 +1,4 @@
+- Draw airport ground vehicles as real shapes instead of stacked boxes: the
+  car is an operations SUV, the van a high-roof panel van, the fire truck an
+  airport crash tender with turrets and the pushback a low tug with a glazed
+  cab, all on the ground at their built size (samehkhamis, #1730).

changelog.d/1731-aircraft-mesh-colours.md

@@ -0,0 +1,3 @@
+- Draw aircraft models in their own mesh colours instead of a 94% flat
+  white (amber for military) over the model; the tracked and emergency
+  colours now tint the mesh without hiding its paint (samehkhamis, #1731).

changelog.d/1732-no-track-true-heading.md

@@ -0,0 +1,4 @@
+- An aircraft that reports no ground track (parked or taxiing, from adsb.lol
+  or a local receiver) now faces its reported true heading instead of north,
+  so one taxiing south no longer looks like it is moving backwards
+  (samehkhamis, #1732).

changelog.d/1733-buoy-models.md

@@ -0,0 +1,11 @@
+- Draw aids to navigation as buoys instead of ships: a buoy, beacon, RACON,
+  light or mark from the vessel feed (or any AIS station numbered 99MIDxxxx)
+  is now the fleet set's buoy of its IALA mark (cardinal, port or starboard
+  hand, safe water, isolated danger or special mark), standing still with no
+  heading, and its icon is a disc rather than a chevron. Its card and readout
+  show its kind of mark with no speed or heading. AISStream now subscribes to
+  aid-to-navigation reports and names each by its kind of mark and its full
+  name; the feed lists every ship ahead of any aid, and `vessels_in_area`
+  counts ships only. A virtual aid (a mark broadcast where nothing physical
+  stands) keeps its disc, is never drawn as a buoy, and its card says it is
+  virtual; vessel sources may mark any record `virtual` (samehkhamis, #1733).

docs/APPLICATION.md

@@ -230,3 +230,125 @@ starts and switches the language with the `./i18n` entry (`startPageLocale`,
 `localePicker: false` to `createApplicationControls` instead of editing the
 markup. Node tests that import application modules register the component
 loader with `node --import=<core package>/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 })`.

docs/CURRENT-STATE.md

@@ -1706,7 +1706,7 @@ Applications supply the existing floor/snap, geoid, picking, sprite, camera,
 trail, focus, readout, context, aircraft presentation and render services.
 The factory never constructs a second application registry. Configure a source
 before initialization; replacing it while initialized is rejected. Model loads
-use the supplied asset resolver, including the preload path. Enrichment receives
+use the supplied asset resolver, including the up-front fleet set load. Enrichment receives
 an abort signal and cannot update a later lifecycle after destruction. Existing
 camera, terrain floor, trail, selection and measured model-size policies remain.
 
@@ -2208,6 +2208,83 @@ the subject (tracking stopped, Satellites off) or tracking another target
 ends the view without refocusing. `src/ui/cockpitOrbitalView.test.mjs`
 covers entry, camera, zoom, look, HUD and exit.
 
+### Application subjects
+
+An application can add its own first-person subjects beside the aircraft,
+vessel and satellite: `services.cockpitSubjects` to `createApplicationControls`,
+a list of subject providers (`src/cockpitSubjectProviders.js`, checked once by
+the coordinator; a malformed one, or one with a member that throws when read,
+is left out with a warning and the rest are kept). A provider names
+its layer, an entry face and labels in the page's language, and supplies four
+operations: `candidate()` (what entry would ride now), `hold(id)`,
+`read(nowMs, ctx)` (a camera frame each update) and `hud(frame, ctx)` (a HUD
+view model), with `release(id, {restore})` on exit. Entry needs the provider's
+layer on, no Context change in flight and the provider's own
+`isEntryAllowed(candidate)`; voice stays aircraft-only and is refused, with
+the reason, while a provider's view is in use.
+
+The built-in kinds keep their fixed entry order (a tracked aircraft, then the
+tracked satellite, then the selected vessel), so without providers entry is
+unchanged. A provider's candidate takes entry only when it was selected after
+every built-in subject present, by when the Cockpit first saw it or saw it
+selected again (its `selectedAt` changing): a train picked after an aircraft
+was tracked takes entry, and an aircraft tracked after it takes it back.
+Providers' candidates are ordered most recently selected first, then by
+priority; one first seen together with a built-in subject comes after it. The
+first in that order decides alone: when its gate is shut there is no entry
+rather than the next subject's.
+
+A frame places the eye `eye.upM` above `heightM` (the shared floor where the
+frame gives none, or where it last stood while that floor is cold; with
+neither, the camera stays where it is and the HUD reads ACQUIRING SURFACE for
+at most `COCKPIT_GROUND_WAIT_TIMEOUT_MS`, after which the view ends and the
+subject is released: no height stands in for a floor never read), slews toward `headingDeg` at the provider's rate, and may
+turn off the floor clamps (`groundClamp: false`, for a subject inside a
+structure) or keep the anchor exactly on the subject (`anchor: 'exact'`, for a
+layer that already moves it smoothly; a frame with no `speedMps` is always
+exact, since an inertial anchor runs on at the frame's speed); `cameraIntervalMs: 0` updates the
+camera every rendered frame. A frame that is null, malformed or for another
+subject ends the view (`restoreTracking: false`), as an aircraft tracked
+meanwhile and the provider's layer turning off do; the exit control asks the
+provider to restore its subject. The generic HUD shows the provider's kicker,
+title, meta line, speed with its unit and tag, readout cards, always-visible
+source rows, banner, route card and Live Signals rows, a veil that darkens the
+picture under the HUD (with passing light streaks, which stop under reduced
+motion), arrow-key look-around when the provider asks for it, and a progress
+line along the bottom edge (`src/cockpitProgress.js`: close ticks merge,
+labels never overlap). Core translates none of the provider's text: a host
+words it for the page's language (`gods-eye-view/i18n`:
+`getLocale`, `onLocaleChange`). Its entry face, labels and look may be
+functions, read again when they are shown and on a change of language, as the
+HUD view is.
+
+The Rail layer offers a read API for such a view: `getSelectedTrain()` and
+`getCockpitSubject()` (a snapshot of the train: where it is along its line,
+which way it runs (`pathBinding.js` learns it), its rail height, speed as
+reported or derived, position source, feed credit and stops, and
+`selectedAtMs`, when the user last selected it by a click or `focusTrain`,
+even again; null after a deselection and for a train only a hold selected),
+`setCockpitSubject(key)` (its marker, 3D model and card hidden, the selection kept, its
+feed held, clicks and Escape left to the view; the held copy stays the one
+drawn of its train while held, another feed's copy hidden, and it keeps
+moving, still selected, when its category is turned off) and
+`focusTrain(key)` (false for a train the layer does not draw); its pure path
+module is exported as `gods-eye-view/layers/rail/paths`. That export
+and these read APIs are experimental and may change without notice. A snapshot read again while nothing in it changed is
+the one read before, and its `path.line` is a frozen copy. Transit
+offers the same for a vehicle (`getSelectedVehicle`, `getCockpitSubject`,
+`setCockpitSubject`, `focusVehicle`): a held vehicle keeps playing when it is
+out of the camera's view, and its sprite, 3D model, card, trail and detection
+box are hidden; released, it is out of play until a visibility sweep finds it in
+view. Its snapshot's `position.groundHeightM` is the floor where playback draws
+it (the drawn marker's height while it is placed, else its segment's two
+reports' floors at the playback fraction), not the newest report's, and null while that floor is unknown. Rail's `path.direction` is the
+way the drawn train runs: once playback has placed it, a report that runs back
+turns it only when playback reaches that report. `docs/APPLICATION.md` (Cockpit subjects) shows a minimal provider. `src/ui/cockpitSubjectView.test.mjs`,
+`src/cockpitSubjectProviders.test.mjs`, `src/cockpitProgress.test.mjs`,
+`src/layers/rail/cockpitSubject.test.mjs` and the Transit lifecycle tests
+cover them.
+
 ## Context coordination
 
 Context controls own Contacts/Space Missions state, entry and exit transactions,
@@ -2229,6 +2306,17 @@ shown without a fade once it is decoded (or after one second if its decode never
 settles), so a new camera's preview is blank only while its frame loads. Disposal
 releases listeners, subscriptions, image handlers, summary timers and chip-hide timers.
 
+The panel opens when a camera becomes active and collapses when the layer is
+switched off, from its own switch or anywhere else. The panel chrome applies
+the collapse, so a panel the desktop accordion only folded has its saved and
+shared state closed too. Clear selected data layers and Context isolation
+(Contacts, Space Missions) switch the layer off without the user asking: the
+panel and its share preference stay as they are, and the layer comes back to an
+open panel. Only the switch-off isolation makes counts (`suspendsLayer`, true
+while `_clearLayersOutsideContextMode` switches the layer off): the user
+switching CCTV off inside Contacts closes the panel as anywhere else. A panel opened by hand while the layer is off stays open, and its
+meta line reads the catalog count, not the last active camera.
+
 ## UI disposal
 
 UI disposal releases the CCTV subscription, command-dock observer, legacy drag
@@ -2420,8 +2508,9 @@ is validated against Cesium 1.138.0 and must be revalidated on upgrades.
 
 `scripts/qa-anime-sky.mjs` checks asset readiness, visible Normal sky and
 Anime band coverage against a Vite dev server.
-`scripts/qa-sky-model-lighting.mjs` compares a lit `airplane.glb` against
-black and white environment maps in isolated scenes.
+`scripts/qa-sky-model-lighting.mjs` compares a lit fleet airliner
+(`public/models/fleet/aircraft/a320.glb`) against black and white environment
+maps in isolated scenes.
 
 ## Model atmosphere on Apple Metal
 
@@ -2442,6 +2531,53 @@ future driver fix restores the effect with no code change; iOS/iPadOS platform
 detection is the backstop for when no probe context can be created. Applied
 during viewer construction, before any tile builds a draw command.
 
+## Render failure notice
+
+When the globe stops drawing, the scene chrome says so instead of leaving a
+black globe behind working controls. `installRenderFailureNotice()`
+(`src/ui/renderFailure.js`) listens for Cesium's `renderError` and the canvas'
+`webglcontextlost`, logs the error, and publishes a notice that
+`RenderFailure.vue` shows as an alert dialog with focus on its first action.
+The app's viewer uses `showRenderLoopErrors: false`, so Cesium's dead-end
+"Rendering has stopped" panel no longer appears; `applicationViewerOptions()`
+keeps it by default for other callers.
+
+- **Retry** restarts the render loop. The notice stays until a frame starts
+  and ends without an error: Cesium raises `postRender` after a failed frame
+  too.
+- **Reload**, after a lost context, reloads the page; the address keeps the
+  view.
+- **Reset view** opens `appRootUrl()`, without the hash or `/share/<code>`
+  path; the query, such as `?lang=`, is kept.
+
+Pitfalls:
+
+- An error thrown outside Scene's error handling (a frame listener, `onTick`,
+  a resize) stops the loop without a `renderError`. The notice wraps the
+  widget's `render()` and `resize()` and raises it as one, once even with
+  `rethrowRenderErrors`.
+- A throwing listener leaves its Cesium event mid-raise, with listener changes
+  only queued. The wrapper finishes those raises first (`finishRaise()` over
+  `frameEvents()`), so a layer turned off or on meanwhile behaves.
+- A render error marks the loop stopped while its next frame is still queued.
+  The wrapper keeps the loop marked running, so a Retry or a shown tab
+  (`src/app/tools.js`) before that frame starts no second loop.
+- After a lost context, later render errors are only logged, so the notice
+  keeps saying why. The listener neither prevents nor restores the loss.
+- When the globe draws again, focus goes back where it was, or to the globe's
+  canvas, which the map's keys read as the map; the canvas is focusable only
+  until focus leaves or the globe is pressed. Focus the user moved stays put.
+- The notice sits above floating panels such as the Québec camera viewer, and
+  its buttons are 44 px tall on touch screens.
+
+An inline conversation panel never reloads or navigates its host's page: it
+offers Retry after a render error only, and no notice after a lost context,
+where the panel runtime's own notice applies (`src/app/globePanelRuntime.js`).
+Its timer (`keepPanelRendering()`) draws only while the render loop is on and
+logs nothing itself, so each render error is logged once, by the notice. An
+error a timer frame throws is caught there: it has already been raised as a
+render error.
+
 ## Map Source control ownership
 
 Map Source controls own chip listeners, source-state subscriptions and selection
@@ -3606,20 +3742,22 @@ This is the current runtime/source-of-truth snapshot for the project.
 >   24.09 m aft (70 % of the model's rendered envelope, so inside it), 2.22 m
 >   below centre (6 %), and 2e-9 m off the centreline.
 > - **The tracked trail attaches to REAL HULL, aft and below (2026-08-23):**
->   `MODEL_TRAIL_ANCHOR_NATIVE` (`src/data/modelVisualAnchor.js`) holds, per GLB
->   and in RAW glTF coordinates (see the transform-chain entry below), the point
->   of the hull's CENTRELINE PROFILE (its y = 0 slice) closest to the aft-belly
->   AABB corner. It is NOT the corner: a bounding-box corner is empty
->   space, 4.80 m off the nearest triangle on `airplane.glb` and 6.14 m on
->   `jet.glb`, so the trail ended in mid air beside the aircraft. The head segment
+>   `FLEET_TRAIL_ANCHORS` (`src/data/fleetTrailAnchors.js`, generated by
+>   `scripts/measure-fleet-trail-anchors.mjs`) holds, per fleet aircraft and
+>   helicopter model and in RAW glTF coordinates (see the transform-chain entry
+>   below), the point of the hull's CENTRELINE PROFILE (its centreline slice)
+>   closest to the aft-belly AABB corner. It is NOT the corner: a bounding-box
+>   corner is empty space (4.80 m off the nearest triangle on the airliner
+>   asset this was first measured on, 6.14 m on the jet), so the trail ended in
+>   mid air beside the aircraft. The head segment
 >   is drawn from a point behind the aircraft to this anchor, so the anchor must
 >   stay aft (83–96 % of each aft extreme) or the segment enters at the tail and
->   stops inside the fuselage. `modelScale.test.mjs` reads the POSITION BUFFERS —
+>   stops inside the fuselage. `fleetModels.test.mjs` reads the POSITION BUFFERS —
 >   real vertices and triangles, because accessor min/max cannot tell a corner
 >   from a surface — and re-derives on-hull, aft, lowest-at-its-station,
 >   on-centreline, and the construction itself. Re-measure, never re-guess.
 > - **The trail anchor rides CESIUM'S transform chain, not a hand-rolled one
->   (2026-08-23 regression fix):** `MODEL_TRAIL_ANCHOR_NATIVE` stores RAW
+>   (2026-08-23 regression fix):** `FLEET_TRAIL_ANCHORS` stores RAW
 >   glTF coordinates and `modelAnchorWorld()` assembles
 >   `modelMatrix × components.transform × axisCorrection` — the same chain
 >   `ModelSceneGraph` renders with, built from Cesium's own exported
@@ -3654,7 +3792,7 @@ This is the current runtime/source-of-truth snapshot for the project.
 >   ENVELOPE, and between them the drawn start slides along the segment so the
 >   visible length grows CONTINUOUSLY from zero. Three earlier cuts are recorded
 >   because their shape matters: testing segment LENGTH against the radius HID
->   real trail (58 m aft of `airplane.glb`'s 34.41 m envelope gives a 33.98 m
+>   real trail (58 m aft of an airliner's 34.41 m envelope gives a 33.98 m
 >   segment, suppressed, though ~23.6 m of it is open air); CLIPPING at the
 >   envelope and keeping only what lay outside stopped a moving trail visibly
 >   SHORT of the aircraft, since a bounding sphere encloses a lot of empty space
@@ -4830,8 +4968,9 @@ activeCameraCardEnabled: true })` may publish it through the retained
 > - **Flights 3D/cockpit hardening:** the destination-direction cue is an
 >   inline SVG rather than a remotely loaded Material Icons ligature, so a
 >   blocked or late font can no longer expand the literal word `navigation`
->   across the cockpit. The grounded `airplane.glb` belly offset is calibrated
->   to the current asset's measured Y-up bounds (`0.063` native units).
+>   across the cockpit. A grounded aircraft stands its fleet model's scaled
+>   clearance (the catalog's `clearance`, measured below the model's origin)
+>   above the ground.
 >   Contact Previous/Next and Live Signals aircraft handoffs now
 >   re-seed the first-person camera anchor at the selected flight immediately;
 >   bounded feed-correction smoothing remains scoped to the same aircraft.
@@ -5821,6 +5960,39 @@ Noir samples also exclude its deliberately vignetted outer field, using shader
 settings and screen position rather than observed brightness. Selected-trail
 diagnostics report every condition even when selection fails.
 
+Heights of the terrain globe's loaded surface come from one shared reader,
+`src/services/terrainSurface.js`, which the ground service hands to every layer
+(`groundFloor.terrainSurface`). `globe.getHeight` is a ray cast against the
+drawn tile's mesh, so the reader keeps each answer per point, about a metre
+apart. While the camera moves or tiles load a kept height is read again after
+2 s; a height read once both have been still for 5 s is kept until either
+changes. Reads are budgeted at 16 ms per 200 ms window across all layers, 12 ms
+of it for re-reads, longest-kept first. A request ranks as a marker (always
+read), drawn geometry, or background (a quarter of each budget). Past the
+budget a kept point keeps its last height and a new point takes the last
+height read in its ~111 m floor cell or waits.
+
+- Transit asks for every vehicle and trail fix: vehicle positions as markers,
+  the path a marker is drawn along next, the undrawn trail history of
+  unselected vehicles as background, and its reread cycle continues until no
+  point waits. Before this, every reread cast a ray for every trail fix of
+  every vehicle in view, which blocked the page for up to 19 s at a time over
+  a 650-vehicle fleet while zooming.
+- Rail asks for each train every frame on a grid about 4 m apart, as a marker,
+  so a moving train reads a few times a second and a standing one not at all.
+- Local data layers (Data Centers, Dams) read terrain floors through it, and
+  their depth samples (`scene.sampleHeight`, a GPU render) stop at 8 ms a
+  frame per layer and continue on the next frames.
+- Bike Share draws a city's stations at once at the fallback height and finds
+  their ground heights afterwards in 4 ms steps, from the terrain reader on a
+  terrain globe and from depth samples where the globe is hidden.
+
+Verified in the browser on a keyless terrain globe only: Boston for Transit,
+Rail and Bike Share, northern Virginia for Data Centers. Not checked there:
+photorealistic 3D Tiles, a terrain globe with a building tileset on top, Dams,
+and any city steeper than Boston. Street Traffic keeps its own height cache
+and ALPR cameras their own sample budget.
+
 Transit brackets use the normal-composite overlay surface: a 1.25 px mode-colour
 stroke over 3.25 px dark backing. Other contact themes retain their existing
 behavior. The selected trail uses a 3 px core over 5 px backing, mode-coloured
@@ -7290,8 +7462,9 @@ pins and share links already supply complete boxes.
   normal four-samples-per-250-ms budget. Retry timestamps more than the maximum
   30-second backoff ahead of the current clock are ignored. A smaller rollback
   can retain a bounded retry delay of up to 30 seconds.
-- Commercial and military aircraft use the same high-level FLEET model regime: 2D billboards when zoomed out, optional glTF models when closer, controlled by the DISPLAY rail `3D` toggle and `Proximity` / `All` modes. Since 2026-08-16 (Hangar fleet) models are PER-CLASS: real CC-BY GLBs for light/bizjet/turboprop/widebody/helicopter/uav (`CLASS_MODEL_REAL` in `src/data/aircraftClass.js` — meters-baked, scale 1, per-model belly/radius; provenance in `public/models/README.md`), the shared `airplane.glb` for the remaining civilian classes, and the military layer maps weight classes (real GLBs / 747 heavies / `jet.glb` fastjets, per-model heading offsets, flat amber or emergency red). Textured civilians carry a HEAVY tint, not a light one: `MODEL_COLOR_BLEND_AMOUNT` is `0.94` in BOTH layers under Cesium's `ColorBlendMode.MIX`, so the class colour supplies 94% of the surface and the asset's own texture ~6%. The visual direction is clean light silhouettes with only a weak diffuse contribution from the approved textures, so liveries deliberately do NOT read. IR boost raises the blend to a full `1.0`. Under NVG/FLIR (map preset or Cockpit vision) models render unlit flat-white at full alpha and scene fog is disabled (fog otherwise blacks out distant models with the globe hidden); state restores on exit.
-- **Aircraft models skip Cesium's dynamic environment map (2026-10-24).** Flights, Military Flights and Local ADS-B pass `environmentMapOptions: AIRCRAFT_ENVIRONMENT_MAP_OPTIONS` (`{ enabled: false }`, `src/data/aircraftModelLighting.js`) to every drawn model. Otherwise each `Model` renders the sky around it and reads it back from the GPU (`readPixels`) when it is first placed, and again whenever it moves more than 1 km, the scene's atmosphere settings change, or (under sunlight dynamic lighting) an hour of scene time passes (`DynamicEnvironmentMapManager`, Cesium 1.138). With the class colour supplying 94% of the surface, the models are lit from Cesium's default spherical harmonics instead, with no specular environment map, so the sky's model-lighting cube map no longer reaches aircraft. `src/data/aircraftModelLighting.test.mjs` pins the option at every drawn model call; the two preload calls only warm the glTF cache and are never drawn.
+- Commercial and military aircraft use the same high-level FLEET model regime: 2D billboards when zoomed out, optional glTF models when closer, controlled by the DISPLAY rail `3D` toggle and `Proximity` / `All` modes. Every model is one of the project's procedural fleet models (`public/models/fleet/`, MIT, 122 GLBs, about 2 MB in all; `public/models/README.md`), chosen per aircraft by `aircraftModelSpec` (`src/data/fleetModels.js`): the first of its ICAO type's callsign rules in `types.json` (`aircraft_callsign`) its callsign matches, else its type's entry, else the model of its `classifyAircraft` class for a type the map lacks, else its ADS-B emitter category's, else the default airliner. It is drawn LIFE SIZE: the type's published length over the model's built length (`src/layers/flights/modelSpec.js`, shared by Flights, Military Flights and Local ADS-B), and a grounded aircraft stands the model's scaled clearance above the ground. An airport ground vehicle (feed type `ZVEH`) is a fire truck (`FIRE…`), pushback tug (`PUSH…`, `TUG…`), van (`DEICER…`, `SQUID…`, `SQB…`) or else a car by its callsign, and a ground station (`GRND`) is an 11.8 m radio mast; these models (catalog category `other`) are drawn at their built size, and such a contact with no altitude stands on the ground instead of at the airborne default (`src/layers/flights/records.js`). `classifyAircraft` still picks the 2D icons. The whole set loads once, up front, when a layer that draws it starts (`loadFleetModelSet`, which logs `[Fleet] N/122 models (X MB) loaded in N ms`); models are built from those bytes, never fetched mid-session, and an aircraft stays its billboard until the set has loaded. Every aircraft model draws its mesh's own colours (`aircraftModelBlend`, `src/data/aircraftModelLighting.js`): Cesium's `ColorBlendMode.HIGHLIGHT` with white, in Flights, Military Flights and Local ADS-B alike; the tracked colour (cyan, or amber in Military Flights) and the emergency red multiply into the mesh, so its paint still shows. IR boost draws them flat white (`MIX` at `1.0`). Under NVG/FLIR (map preset or Cockpit vision) models render unlit flat-white at full alpha and scene fog is disabled (fog otherwise blacks out distant models with the globe hidden); state restores on exit.
+- Vessels, Transit and Rail draw fleet models under the same DISPLAY rail `3D` toggle, at the same altitude ceiling, caps and add/keep radii as the aircraft (`FLEET_MODEL_POLICY`, `src/layers/flights/policy.js`; `createFleetModelLayer`, `src/data/fleetModelInstances.js`). A vessel's model follows its AIS ship type and is drawn at its reported length and beam (AIS static dimensions A+B and C+D, now carried on vessel rows as `length` and `beam`), standing at the sea surface, heading by true heading then course. An aid to navigation is not a hull: a vessel record whose type names a buoy, beacon, mark, RACON or light, or whose MMSI is an aid-to-navigation station's (`99MIDxxxx`), is `isAidToNavigation` (`src/data/vesselTypes.js`) and is drawn as the set's `buoys` model of the IALA mark its type names (`aidToNavigationModel`, `src/data/fleetModels.js`: cardinal N/E/S/W, port or starboard hand, preferred channel by its side, safe water, isolated danger, special mark; a beacon, light, light vessel, RACON or reference point with no mark of its own is the special mark), else a red can (`DEFAULT_AID_MODEL`), at its built size and facing north whatever heading it reports. A type is an aid's when it is one of the 32 kinds an aid report names or uses a word for one (buoy, beacon, cardinal, safe water, RACON, lighthouse and so on); a vessel that works on aids (`Buoy Tender`, `Buoy Layer`) is not one. Its icon is a bone-white ringed disc (`AID_TO_NAVIGATION_STYLE`, `src/data/vesselLabels.js`) instead of a chevron, never rotated, and its card, selected card and HUD readout (`src/layers/vessels/cards.js`) show its kind alone, whole, in that colour: no speed or heading, since a fixed mark has neither. AISStream subscribes to `AidsToNavigationReport` (message 21) by default, and the server names each report's aid type code (0 to 31) as its kind (`aidToNavigationTypeName`: `20` is `Cardinal Mark N`) rather than reading it as a ship type, and its name runs on into the report's `NameExtension`. A virtual aid (the report's `VirtualAtoN` flag: a mark broadcast where nothing physical stands) carries `virtual: true` on its row, and on its vessel source record (the live-source contract's `virtual`, `src/sources/live/contract.js`, false unless a source says true; any source may set it). It keeps its disc but never gets a model (`vesselModelSpec` returns null for it, and the vessel layer gathers no model item for it), and its card and readout add `VIRTUAL` after its kind. `aisStreamRows` (`server/providers/vessels/ais-store.js`) puts every vessel ahead of every aid, so a capped request (the layer asks for 12,000 rows) never gives up a ship for a buoy. The `vessels_in_area` tool (and the brief built on it) counts ships only: it leaves aids out of its rows, counts, breakdowns and speed stats. A transit vehicle's model follows its layer mode (bus, tram, subway, rail or ferry; a vehicle of `unknown` mode keeps its icon), a train's its rail category and mode (rail, metro or tram). Neither the transit nor the rail sources carry a GTFS `route_type` or a finer mode (monorail, gondola, funicular, cable car), so the set's models for those and their `transit.elevation` lifts are not reached by any live source today. Both stand on the road or rail top they are drawn on, without the 1.5 m `GROUND_FLOOR_LIFT_M` their icons carry, and are painted in their mode or category colour where the model's `_TINT` attribute marks it. A vessel model is clipped at its waterline (one clipping plane per model, at the model origin's horizontal plane), so its hull below the water never shows through a plain globe, which Cesium does not depth-test models against. Under the NVG/FLIR styles (the Flights `irBoost` parameter) these models render unlit flat white, as aircraft models do. Each vehicle's icon stays the visual until its model is loaded, ready and placed; a model is picked as its icon is, and a vehicle drawn as its model keeps its selection card and its place in the detection overlay.
+- **Aircraft models skip Cesium's dynamic environment map (2026-10-24).** Flights, Military Flights and Local ADS-B pass `environmentMapOptions: AIRCRAFT_ENVIRONMENT_MAP_OPTIONS` (`{ enabled: false }`, `src/data/aircraftModelLighting.js`) to every drawn model. Otherwise each `Model` renders the sky around it and reads it back from the GPU (`readPixels`) when it is first placed, and again whenever it moves more than 1 km, the scene's atmosphere settings change, or (under sunlight dynamic lighting) an hour of scene time passes (`DynamicEnvironmentMapManager`, Cesium 1.138). The models are lit from Cesium's default spherical harmonics instead, with no specular environment map, so the sky's model-lighting cube map no longer reaches aircraft. `src/data/aircraftModelLighting.test.mjs` pins the option at every drawn model call; every model is built from the fleet set loaded up front, so there is no separate preload.
 - The DISPLAY-rail `3D` toggle is the user-facing activation path for both aircraft layers. Their small approved GLBs build their render resources without Cesium's frame-spread job queue, preventing continuous Photorealistic 3D Tiles streaming from starving model readiness; model caps, tracking, camera, and fallback billboards are unchanged.
 - **The `3D` toggle DEFAULTS ON in `proximity` on a first run.** Proximity is itself the budget — models appear only below `MODEL_ALT_CEIL_M` and only for the nearest `MODEL_MAX` in view — so the default costs nothing at globe scale, and `all` remains a deliberate opt-in. A fresh boot runs NO layer-state restoration (`LayerStateCoordinator.start()` returns early with neither a share payload nor stored state), so four independent initializers decide what a first-run operator sees and must agree: `booleanOption('models3d', 'e', true)` in `src/data/layerState.js`, `_models3dEnabled = true` in BOTH flight layers, `this._models3dEnabled = true` in `src/ui/aircraftDisplay.js`, and the `active` / `visible` classes on `#models3d-toggle` / `#models3d-mode-row` in `index.html`. All four are pinned together in `src/data/layerState.test.mjs`. Explicit state still wins: because the codec omits default-valued options, `models3d: false` is now what travels in a link (`lo=…f.e.0`) and restores OFF at both aircraft layers. **Consequence for returning users:** a stored `gev:layer-state:v2` blob is a FULL options snapshot, so a session that wrote one before this change carries `models3d:false` and keeps 3D off until the operator flips it (or clears the key) — the durable snapshot is treated as the recipient's own state, by design.
 - **Consequence of the flip on the recorded tracked/fleet inversion:** the 150–800 km band where surrounding contacts draw as models while the SELECTED one is still a glyph is now what an operator sees WITHOUT arming anything. The inversion itself is unchanged and still deliberate (see `src/data/trackedModelRegime.js`); only its reachability changed.

docs/INFRASTRUCTURE-LAYERS.md

@@ -34,6 +34,7 @@ const layers = createInfrastructureLayers({
 | `clearSelectedEntityContextForLayer` | `(layerId)`; clear selection only if owned by this layer |
 | `removeEntityContextsForLayer` | `(layerId)`; remove records owned by the layer on destruction or failed setup |
 | `governorRequestRender` | `(reason)`; request a frame through the existing render scheduler |
+| `terrainSurface` | Optional. The application's shared terrain surface (`groundFloor.terrainSurface`), so its layers read each terrain height once; without it each layer keeps its own |
 
 Each returned layer supports `init(viewer)`, `enable(viewer)`, `disable(viewer)`,
 `update(viewer)`, `destroy(viewer)`, `getStats()`, `getLodDiagnostics()` and

docs/PERFORMANCE-AUDIT-2026-11.md

@@ -1,322 +0,0 @@
-# Slowdown audit, November 2026
-
-A sweep of `main` (`c02ede3bb`, 13 November 2026) for bugs that freeze the page
-or hold the frame rate down. This page lists what was found, why it happens and
-how to fix it, and names the pull request that carries each fix.
-
-[PERFORMANCE.md](PERFORMANCE.md) is the measured baseline of a healthy build;
-this page is the list of things that fall outside it.
-
-## How it was measured
-
-- Keyless dev server, headless Chrome at 1440 x 900 on Apple silicon (Metal
-  through ANGLE), default globe map.
-- Per scenario: load, a spell at rest, scripted drags and wheel zooms, then a
-  settle. Long tasks were counted with a `PerformanceObserver`, the hot function
-  named from a CPU profile, and `globe.getHeight`, `scene.sampleHeight`,
-  `scene.pick` and friends wrapped to count calls and time.
-- A long task is one main-thread task over 50 ms. With no layers on, the
-  baseline is two at load (longest about 240 ms) and none afterwards, with zero
-  frames rendered while the camera is still.
-- Four profiling sessions ran on one machine at the same time, so absolute
-  timings carry some noise. Ratios against the baseline are what to read.
-
-Nothing here was measured on Google Photorealistic 3D Tiles, on a discrete or
-integrated PC GPU, or with keyed feeds (AISStream, FIRMS, TomTom). Those rows
-are marked "read in code".
-
-## Findings and fixes
-
-Worst first. "Fix" names the pull request that carries the fix.
-
-### Measured
-
-| # | Where | What happens | Fix |
-| ---: | --- | --- | --- |
-| 1 | Bike Share, local data layers, Transit, Rail | 18 s freeze switching Bike Share on over New York (2,519 stations); 2.7 s on Data Centers; multi-second freezes with Transit while zooming | #1688, #1689 |
-| 2 | Shipwrecks | 3 to 5 s freeze when the markers are built over loaded terrain; a share link with the layer on held the loading screen for 22.9 s in one run | #1703 |
-| 3 | Camera | Rendering stops until reload: at a whole-globe view looking straight down, pan a few times, then scroll one notch | #1704 |
-| 4 | Street Traffic | Zooming at 250 m over Manhattan: 25 long tasks in 24 s, longest 746 ms, 6.6 s in total | #1705 |
-| 5 | ALPR cameras | Depth samples inside the overlay paint, repeated on every re-enable: 240 samples and about 1 s across eight toggles. A first-sample freeze of up to 1.9 s was seen in the sweep but not on a second day | #1706 |
-| 6 | Wind | First zoom after load: up to 14 long tasks (longest 414 ms). Re-measured as one-off shader links, not a standing cost: see below | none proposed |
-| 7 | Submarine cables | About 2 s of long tasks on load, heap briefly at 1 GB, about 0.5 s again on each re-enable | #1707 (first step), #1722 (batched primitives) |
-| 8 | Live Flights at whole-globe view with detection labels | Fine on the test machine; at 4x CPU throttle, 8 fps with 143 long tasks in 15 s | #1708 (fleet pass), #1719 (overlay) |
-| 9 | Radio | 7 to 10 long tasks when the directory loads, longest 447 ms | #1709 |
-| 10 | Pointer pick | Not reproduced on a second look: see below | none needed |
-| 11 | CCTV | A still-image camera holds continuous rendering at 60 frames a second although its picture changes about every 10 s | #1710 |
-
-### Read in code
-
-| # | Where | What happens | Fix |
-| ---: | --- | --- | --- |
-| 12 | `/api/firms` | The whole fire set is filtered, serialised and sent uncompressed on every request; 15 to 55 MB estimated in a heavy season | #1711 |
-| 13 | AIS store | Both vessel maps are walked on every position message, and sorted whole once past the cap | #1712 |
-| 14 | Satellite clouds on the 3D Tiles map | A CPU pass over a 4096 x 2048 image, 90 to 180 ms measured on a synthetic canvas, twice in a row | #1713 (canvas path), #1721 (shader) |
-| 15 | NVG and FLIR styles | Over 100 texture reads per pixel, and 60 renders a second while the style is on. Measured afterwards: the reads cost 0.4 ms a frame at 1440 x 900 and 1.2 ms at 2560 x 1440 | #1718 |
-| 16 | Wind server | Full 0.25 degree GRIB fields decoded on the event loop. Measured afterwards: 68 ms blocked per warm refresh, about 250 ms on the first, about 400 ms when all six keys refresh together | #1717 |
-| 17 | Imported geo files and other per-feature ground clamps | Measured afterwards: imported files do not freeze; see below | none needed |
-
-## Cause and fix, per finding
-
-### 1. Terrain height reads
-
-`globe.getHeight` casts a ray against the mesh of the tile under the point, and
-`scene.sampleHeight` renders a depth pass. Transit asked for every trail fix of
-every vehicle several times per poll; Bike Share sampled every station in one
-go. The fix keeps heights per point in one shared reader with a read budget
-(`src/services/terrainSurface.js`) and spreads the depth samples across frames.
-
-### 2. Shipwrecks
-
-`rebuild()` in `src/layers/shipwrecks/index.js` adds 7,958 billboards with
-`heightReference: CLAMP_TO_GROUND`. Each constructor runs
-`Billboard._updateClamping`, which intersects a ray with the terrain mesh,
-synchronously: 4.8 of the 4.9 s. The cost is only paid when terrain is loaded
-at the time the markers are built, so a cold start with the layer in the URL
-sometimes escapes it.
-
-Fix: do not clamp. Wrecks are at sea and the markers already ignore the depth
-test, so place them on the ellipsoid with `HeightReference.NONE`.
-
-### 3. Camera: rendering stops after pan then zoom
-
-Pure Cesium; no application code is involved. Above 1,000 km,
-`ScreenSpaceCameraController` `handleZoom` rotates the camera about the cross
-product of the picked point's normal and the screen centre's normal whenever
-their dot product is between 0 and 1. With the pointer on the exact centre pixel
-the two are the same vector, yet `n · n` often rounds to `0.9999999999999999`,
-so the check passes with a zero axis. `Camera.rotate` then throws
-`DeveloperError: normalized result is not a number` from
-`Scene.initializeFrame`, outside the scene's own try/catch, so
-`scene.renderError` never fires and Cesium stops its render loop for good. The
-pans in the first reproduction only moved the camera to a pose where the
-rounding goes that way.
-
-Fix: make `camera.rotate` ignore a zero or non-finite axis, and recover from any
-stopped loop by restoring the last drawn camera pose and restarting it a bounded
-number of times before showing Cesium's error panel.
-
-### 4. Street Traffic road loading
-
-Three costs in one task after the detail tiles arrive, in
-`src/layers/traffic/source.js`:
-
-- `outsideDetailTiles` clips every coarse z12 road against every loaded detail
-  tile (up to 16) for four regions.
-- The composed set is then handed on with `replace: true`, so
-  `ingestion.js` parses every road again although each tile was parsed as it
-  streamed.
-- `parseRoads` (`model.js`) asks `cachedGroundFloor` once per coordinate, and
-  each call builds several string keys.
-
-Fix: clip once per coarse tile against the detail tiles' union box and slice the
-work across frames (or do it in the vector-tile worker); reuse the roads parsed
-while streaming and parse only the clipped coarse remainder; look the floor up
-once per floor cell within a parse.
-
-This is separate from the one-viewport-tile-at-a-time loading recorded in
-[KNOWN-ISSUES.md](KNOWN-ISSUES.md).
-
-### 5. ALPR cameras
-
-`refineAnchors` and `anchorFor` in `src/layers/alpr/overlay.js` call
-`scene.sampleHeight` from the overlay's paint, four per paint. Each is a depth
-render and a `readPixels`; the first one also compiles the pick shader. Results
-are kept on the entity, so a rebuild or a re-enable samples everything again.
-
-Fix: on a terrain globe read `globe.getHeight` through the shared terrain reader
-instead of sampling; keep the answers in a map keyed by camera that outlives the
-entities; move what sampling remains out of the paint into a queue of one per
-frame.
-
-### 6. Wind
-
-The first reading blamed the layer's 916,476 vertices for slow depth reads
-during zoom. Measuring again did not support that: depth reads cost the same
-with and without Wind, hiding every wind primitive left pick time unchanged, and
-the stalls appear on the first zoom only, as shader programs link (seven
-programs, about 0.5 s, long tasks up to 166 ms). Later zooms had none.
-
-The roughly 30 renders a second are the animation itself. It is already capped
-at 30 Hz and stops when paused, hidden, out of view or under reduced motion;
-lowering the rate would change how the layer looks. `disable()` releases the
-baked geometry on purpose, at the price of one task of about 130 ms on
-re-enable.
-
-A third look, timing every program link on a preview build, settled it: Wind
-owns two shader programs, both link during load in 9 to 18 ms, and none ever
-linked during a zoom. The programs that do link on a zoom are Cesium's own
-globe-surface variants, with Wind on or off, and Cesium links them
-synchronously. No fix is proposed.
-
-### 7. Submarine cables
-
-`src/layers/submarineCables/ingestion.js` loads both collections through
-`Cesium.GeoJsonDataSource` with `clampToGround`. Switching the layer on is one
-task of about 1.4 s, and 1.2 s of it is Cesium reading the terrain height for
-the 1,917 ground-clamped landing markers, all created in the first frame,
-including the ones behind the globe.
-
-Fix, first step: start the landing markers hidden and let the existing horizon
-sweep show the visible ones a few dozen per frame.
-
-Fix, second step: draw from batched primitives in place of the entity data
-sources: one ground polyline primitive for the lines, one billboard collection
-for the landing markers, one point collection and one static polyline primitive
-for the reference stems, all kept while the layer is off. That removes the
-visualiser tasks, the stall on switch-off and on re-enable, and about 900 MB of
-heap. The first switch-on still links shaders and builds the ground-line
-geometry once.
-
-### 8. Live Flights at whole-globe view
-
-Two costs that scale with the 7,500 aircraft of a full poll:
-
-- The fleet pass (`src/layers/flights/rendering.js`, every 80 ms) dead-reckons
-  each visible aircraft and asks `cachedGroundFloor` for it, including aircraft
-  at cruise altitude that can never touch the floor. Each lookup formats numbers
-  to strings several times and rewrites a cache entry: 40% of the busy time.
-- The detection overlay (`src/data/detection.js` `_drawOverlay`) collects every
-  detectable object and strokes every bracket on every frame.
-
-Fix for the first: skip the floor path for a contact clearly above any terrain,
-make the floor-cell key a number, and stop promoting the cache entry on every
-read.
-
-The second turned out smaller than it looked. The bracket strokes are already
-one path per colour, and collecting the objects is about 3 ms of a 56 ms frame
-at 4x throttle once the first fix is in. What costs is the per-object loop in
-`_drawOverlay` (projection, occlusion, alpha, twelve path calls per bracket).
-
-Fix for the second: keep what a sweep built and reuse it on the next paint when
-the view and every contact are exactly what it was built from, compared value
-by value so no layer has to announce a change. Between two fleet passes most
-paints qualify, which cuts frame work by a fifth to a third on a still camera
-at full speed. At 4x throttle a frame outlasts a fleet pass, no paint
-qualifies, and the gain is a few milliseconds; the fleet pass is what
-dominates there.
-
-### 9. Radio
-
-`stationTags()` in `src/layers/radio/categories.js` splits and normalises a
-station's tags on every `hasTag` call, and `buildRadioCategories` runs that for
-every station against every category, twice.
-
-Fix: normalise once per station at ingest and count categories from that.
-
-### 10. Pointer pick
-
-Three sessions saw a single `scene.pick` of 207 to 342 ms during a gesture and
-attributed it to `pickPointer` in `src/voice/pointerPick.js`. Timing every pick
-across pointer rests, drags and wheel bursts did not bear that out: of 78 picks
-with CCTV on over London all but two took 3 to 8 ms, and with five heavy layers
-on, 81 picks took 5 to 30 ms apart from the first (135 ms). `pickPointer` picks
-at most once per pointer rest.
-
-The slow pick is the first pick after a layer appears, once per page load, most
-likely the pick shader compiling, and its stack is CCTV's own hover pick
-(`src/layers/cctv/hover.js`). No fix is proposed: removing the dwell pick would
-only move the one-off cost to the next click.
-
-### 11. CCTV still-image cameras
-
-`src/layers/cctv/projection.js` holds continuous rendering for as long as any
-projected camera is active and redraws the projection every frame.
-
-Fix: hold only for video. For a still image, request one render when a new image
-lands or while a focus fade runs.
-
-### 12. `/api/firms`
-
-`server/providers/firms.js` builds the payload and calls `JSON.stringify` per
-request, with no kept body and no compression, and the client refetches every
-ten minutes.
-
-Fix: keep the response bytes and their gzip and serve those, as the OpenSky
-provider does. The route filters to the trailing 24 hours at serve time, so the
-bytes can only be reused while that filter keeps the same records (about a
-minute at a time): bursts and several clients gain most, and every response is
-about seven times smaller.
-
-### 13. AIS store
-
-`server/providers/vessels/ais-store.js` calls `pruneAisStreamCache()` for every
-message; the static-data map is never pruned.
-
-Fix: prune on a timer, evict in insertion order, and drop a vessel's static
-entry with the vessel.
-
-### 14. Satellite clouds on the 3D Tiles map
-
-`src/layers/weather/infraredImage.js` runs `getImageData`, a per-pixel power
-curve and `putImageData` over the whole canvas.
-
-Fix: a 256-entry lookup table applied in place for the canvas path, which
-halves it; then, for the shell on the 3D Tiles map, the same curve in its
-fragment shader from a strength uniform, so the image is never read back and a
-strength change builds no new image.
-
-### 15. NVG and FLIR styles
-
-`src/styles/surveillance.js` loops 11 x 11 texture reads per pixel and
-`src/styles/thermal.js` totals 106. Timed on the GPU, those loops cost about
-0.4 ms a frame at 1440 x 900 and 1.2 ms at 2560 x 1440 on the test machine:
-real, but small there. The standing cost is that a style with animated grain
-holds continuous rendering at 60 frames a second.
-
-Fix: split the bloom into a row pass and a column pass, which gives the same
-picture from a fifth to a half of the reads, and step the grain's clock at
-15 Hz, asking for one frame per step instead of holding the render loop. The
-grain then changes 15 times a second, which is visible in motion.
-
-Switching on any style stage at all costs more than the bloom did (1.8 ms a
-frame at 1440 x 900 for the one-line noir style). That was not looked into.
-
-### 16. Wind server
-
-`server/providers/wind/decode.js` decodes about a million doubles per message
-synchronously, hourly, for six keys.
-
-Fix: decode on a worker thread, and keep the sampled U and V of the last
-forecast file per model so that choosing an overlay fetches only its field.
-
-### 17. Per-feature ground clamps
-
-`heightReference: CLAMP_TO_GROUND` per feature is also set in
-`installations/rendering.js`, `alpr/presentation.js`, `ghostMaps/index.js`,
-`earthquakes/index.js`, `airQuality/index.js`, `news/index.js` and
-`osmPlaces/index.js`. Their counts were small in these runs (30 to 1,500) and
-none froze.
-
-Imported geo files were the one unbounded case, and measuring them cleared
-them: 20,000 generated points (the import cap) finish in about 1.5 s with a
-longest task near 0.5 s, because `settleGroundPins` in
-`src/data/geoFileImport.js` already places pins with `HeightReference.NONE` and
-resolves heights 256 at a time with a yield between batches. No fix is needed.
-
-## Checked and fine
-
-- Start-up of a production build: viewer ready in about 0.5 s, loading screen
-  gone at 1.6 s, three long tasks totalling about 300 ms.
-- Idle: no frames rendered with no layers on; every render hold was released
-  when its layer went off.
-- Leaks: all 41 layers toggled three times and ten of them eight times; no
-  timer, scene listener, primitive or data source grew per cycle. The heap
-  levelled off near 320 MB over 7.5 minutes of toggling eleven layers.
-- At most one long task after load: Military, Satellites (including 11,903
-  Starlink points), Earthquakes, News, Wildlife, GNSS, Drone Airspace, Military
-  Installations, Fire Perimeters, rain radar, lightning, and satellite clouds on
-  the globe map.
-- Live Flights at city scale with the same 7,500 aircraft loaded: 60 fps, no
-  long tasks.
-
-## Not covered
-
-- Google Photorealistic 3D Tiles: nothing was run there. Depth sampling is the
-  only height source on that map, so findings 4, 5 and 17 may be worse.
-- Live Vessels, FIRMS with data, TomTom traffic, Local ADS-B.
-- Frame rate on anything but one Apple silicon machine.
-- One all-layers run over Manhattan grew the heap from 346 to 638 MB in 60 s;
-  whether that is retained was not established.
-- One Satellites load showed a 5.2 s long task once and never again in four more
-  loads.

docs/PERFORMANCE.md

@@ -6,9 +6,6 @@ specification and should not be used to predict performance on untested systems.
 The original capture artifacts are not included here, so this page records
 results rather than defining a runnable benchmark.
 
-For slowdowns found since, with their causes and fixes, see
-[PERFORMANCE-AUDIT-2026-11.md](PERFORMANCE-AUDIT-2026-11.md).
-
 ## Test context
 
 The baseline was captured on 22 August 2026 with these conditions:

docs/translations/zh-Hant.md

@@ -4,7 +4,7 @@ Catalog: `src/i18n/locales/zh-Hant.json`. General rules: [TRANSLATORS.md](../TRA
 
 `zh-Hant` is the Simplified Chinese catalog (`zh-CN`, credited to abiyeenzo, #914, and EDIT-Aeterna, #979) written in Traditional characters with OpenCC character conversion. Wording and terminology are the same as in `zh-CN`: change a term in [zh-CN.md](./zh-CN.md) and the `zh-CN` catalog first, then convert. Only the script differs.
 
-After `s2tw` conversion, fix the characters OpenCC picks wrongly: 年曆史 → 年歷史, 下遊 → 下游, 並道 → 併道, 發佈 → 發布, 公佈 → 公布.
+After `s2tw` conversion, fix the characters OpenCC picks wrongly: 年曆史 → 年歷史, 下遊 → 下游, 並道 → 併道, 發佈 → 發布, 公佈 → 公布, 控制檯 → 控制台, and 周 → 週 where it means a week (1 週/秒).
 
 ## Style
 

package.json

@@ -298,6 +298,7 @@
     },
     "./sources/rail-service": "./src/sources/railService.js",
     "./layers/rail/source": "./src/layers/rail/source.js",
+    "./layers/rail/paths": "./src/data/railPaths.js",
     "./sources/map-features": "./src/sources/overpassFeatures.js",
     "./server/providers/mapillary": {
       "node": "./server/providers/mapillary.js"

public/models/README.md

@@ -1,20 +1,39 @@
-# Bundled 3D Model Attribution
+# Bundled 3D Models
 
-The model files in this directory are third-party visual assets. They are not
-covered by the repository's MIT source-code license; each remains available
-under the license listed below.
+Every 3D model shipped in this directory is one of the project's procedural
+fleet models under [`fleet/`](fleet/): aircraft, helicopters, ships, buoys,
+transit and rail vehicles, and a few other airborne and ground objects. They
+are generated from code by the project maintainers, contain no third-party
+artwork, and are covered by the repository's [MIT license](../../LICENSE)
+like the source code.
 
-| File | Original work and creator | Source | License | Project modifications |
-|---|---|---|---|---|
-| `airplane.glb` | “boeing 747” by [zairiq-123](https://sketchfab.com/zairiq-123) | [Sketchfab model](https://sketchfab.com/3d-models/boeing-747-9b16672038ba48f98e6d80a159044ed9) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Substantially modified and optimized for God's Eye View, including geometry/material simplification and coordinate/orientation preparation. The former 24× runtime calibration is baked into the mesh; location, rotation, and scale are applied; the bounding-box centre is at the origin; and the model uses glTF +Y-up with its nose toward local −X. Geometry remains uncompressed so the aircraft asset does not compete with photogrammetry for Draco worker capacity. |
-| `jet.glb` | “Private Jet” by [Nick the Name](https://sketchfab.com/Nick_The_Name) | [Sketchfab model](https://sketchfab.com/3d-models/private-jet-cbdd1de6ced9461e950eafaa302cc82b) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Repackaged as a glTF binary for the project's military-flight visualization. Imported hierarchy transforms are baked into the meshes; location, rotation, and scale are applied; the bounding-box centre is at the origin; and the model uses meter scale, glTF +Y-up, and the shared nose −X convention. Existing materials are preserved. |
-| `bell206.glb` | “Bell 206 JetRanger” by [terran4627](https://sketchfab.com/terran4627) | [Sketchfab model](https://sketchfab.com/3d-models/bell-206-jetranger-d2f7ba1d671549d4b26aaf834139a1dd) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Optimized for God's Eye View: geometry/material simplification, textures resized to 256 px WebP, orientation/scale vertex-baked to real-world meters (Y-up, nose −X), origin centered. |
-| `c172.glb` | “Cessna 172” by [e737](https://sketchfab.com/e0057537) | [Sketchfab model](https://sketchfab.com/3d-models/cessna-172-64cddaee5aff470682659a8c08525046) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Optimized for God's Eye View: geometry/material simplification, textures resized to 256 px WebP, orientation/scale vertex-baked to real-world meters (Y-up, nose −X), origin centered. |
-| `citation2.glb` | “1990 Cessna Citation, Texture Detailed, Exterior” by [BlenderCommunityHead](https://sketchfab.com/aboodgoudagad) | [Sketchfab model](https://sketchfab.com/3d-models/1990-cessna-citation-texture-detailed-exterior-a78839624fe64900a8352cb23462350a) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Optimized for God's Eye View: geometry/material simplification, textures resized to 256 px WebP, orientation/scale vertex-baked to real-world meters (Y-up, nose −X), origin centered. |
-| `mq9.glb` | “MQ-9” by [IProZenoN](https://sketchfab.com/IProZenoN) | [Sketchfab model](https://sketchfab.com/3d-models/mq-9-fabe963feb354c5584b51f9c470c3f7e) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Optimized for God's Eye View: geometry/material simplification, textures resized to 256 px WebP, orientation/scale vertex-baked to real-world meters (Y-up, nose −X), origin centered. |
-| `b789.glb` | “Boeing 787-9” by [Nobilis 2](https://sketchfab.com/nobilishornet2) | [Sketchfab model](https://sketchfab.com/3d-models/boeing-787-9-b6711e2e698e4e469675c1154a50b7a3) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Optimized for God's Eye View: geometry/material simplification, textures resized to 256 px WebP, orientation/scale vertex-baked to real-world meters (Y-up, nose −X), origin centered. |
-| `atr72.glb` | “ATR 72 - 600” by [Oyan3D](https://sketchfab.com/oyan3D) | [Sketchfab model](https://sketchfab.com/3d-models/atr-72-600-1e1a7186f7444d288675262fcee44744) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Optimized for God's Eye View: geometry/material simplification, textures removed with dominant material colors baked into PBR factors (flat “abstracted” style), orientation/scale vertex-baked to real-world meters (Y-up, nose −X), origin centered. |
+| Path | What it holds |
+|---|---|
+| `fleet/catalog.json` | Every model by name: its file, category, built length, beam and bounds (metres, in Cesium's Z-up model frame: x along the length with the nose toward −X, y across the beam, z up), the clearance below its origin, and its 2D icon class. |
+| `fleet/types.json` | Which model draws which vehicle, and at what length: ICAO aircraft and helicopter type codes, ADS-B emitter categories, AIS ship-type and length ranges, GTFS route types, transit modes and rail categories, with the defaults. |
+| `fleet/aircraft/`, `fleet/helicopters/`, `fleet/ships/`, `fleet/buoys/`, `fleet/transit/`, `fleet/other/` | The models, one GLB each (EXT_meshopt_compression and KHR_mesh_quantization, vertex colours, no textures). |
 
-CC BY 4.0 permits sharing and adaptation, including commercial use, provided
-appropriate credit is retained, the license is linked, and modifications are
-identified. These credits do not imply endorsement by the original creators.
+How the layers use them:
+
+- Each layer draws a vehicle with the model its type selects, scaled to the
+  type's published length (a vessel to its reported AIS length and beam), so
+  every model is drawn life size. Ground objects, balloons and obstacles in
+  the `other` category are drawn at the size they are built.
+- An aid to navigation (a vessel record whose type names a buoy, beacon, IALA
+  mark, RACON or light, or whose MMSI is an aid station's `99MIDxxxx`) is
+  drawn as the `buoys` model of its mark (cardinal north, east, south or west,
+  port or starboard hand, safe water, isolated danger, special mark), a red
+  can when its type names no mark, at its built size and with no heading
+  (`vesselModelSpec`, `aidToNavigationModel`).
+- An aircraft model's origin is its axis; it stands that model's scaled
+  clearance above the ground. A ship's origin is its waterline, and a transit
+  or rail vehicle's the road or rail top (a monorail or gondola is raised by
+  its `transit.elevation` entry, for a source that names those modes).
+- Transit and rail models carry a `_TINT` vertex attribute that marks where
+  the route or category colour is painted.
+- The whole set loads once, up front, when a layer that draws it starts; no
+  model is fetched while a session runs.
+
+`src/data/fleetModels.js` reads the set and chooses each vehicle's model;
+`src/data/fleetModels.test.mjs` checks that every model `types.json` names is
+in the catalog and on disk, and that no GLB exceeds 3 MB.