From 81f49406b80f2f4c8076ed739360f79ab2e2c34f Mon Sep 17 00:00:00 2001
From: Wilmer Alzate <wilmeralzateroman@gmail.com>
Date: Wed, 30 Sep 2026 12:31:59 -0500
Subject: [PATCH 01/71] perf(flights): skip dead-reckoning contacts that stay
 behind the horizon

The fleet tick dead-reckoned, floored and distance-tested every contact on
every ~80 ms tick, then hid the ones behind the horizon. The worldwide feed
carries ~13k contacts; zoomed in, well under 1% are on screen, so nearly all
of that work produced a hidden billboard.

A contact that is already hidden and still behind the horizon at its last
position now re-reckons only on its turn in a staggered one-in-12-ticks
rotation (about once a second, HIDDEN_CONTACT_DR_TICKS). Anything that
position puts in view, and any contact with a fleet model, takes the full
pass immediately, so on-screen behaviour is unchanged. Hidden-inclusive
proximity queries (getNearby includeHidden, getAllPositions) read positions
at most about a second old, well inside the 30 s poll's uncertainty.

Measured in Chrome on a Radeon 780M, ~12.9k contacts, 56 on screen over
Colombia at 4 km, same view before and after:
  fleet tick   7.66 -> 2.03 ms/frame, longest tick 50.9 -> ~16 ms
  frame        20.6 -> 14.0 ms, 42.9 -> 57.8 FPS
Teleporting the camera to Madrid showed 975 contacts within 100 ms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  7 ++++
 docs/CURRENT-STATE.md                         |  2 +-
 scripts/format-scope.json                     |  1 +
 .../flights/hiddenContactRotation.test.mjs    | 42 +++++++++++++++++++
 src/layers/flights/policy.js                  | 31 ++++++++++++++
 src/layers/flights/rendering.js               | 24 +++++++++++
 src/layers/flights/state.js                   |  4 ++
 7 files changed, 110 insertions(+), 1 deletion(-)
 create mode 100644 src/layers/flights/hiddenContactRotation.test.mjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58103d04d..4cc44d40c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+- Stop dead-reckoning every flight hidden behind the horizon on every fleet
+  tick. With the worldwide feed (~13k contacts, ~56 on screen over Colombia at
+  4 km), the fleet pass drops from 7.7 ms to 2.0 ms per frame and its longest
+  tick from 51 ms to about 16 ms; the scene goes from 43 to 58 FPS. Hidden
+  contacts re-reckon about once a second, staggered, and appear as soon as
+  their position is in view.
+
 - Public Overpass instances are no longer used by default. Street Traffic
   roads come from TomTom flow tiles, OpenFreeMap vector tiles, or both, chosen
   on the layer row (TomTom / OSM / Hybrid) or with `?trafficRoads=`. With a
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 22ce1eb3b..ee4269a63 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -3469,7 +3469,7 @@ silently demoting every later lookup for the session.
 
 ### Motion & Symbology Correctness (June 10, 2026)
 
-- **Flights (commercial + military)** render one poll interval behind real time (30s/15s) and interpolate between two known feed-stamped fixes (OpenSky `time_position`; adsb.lol `receipt − seen_pos`). The display latency is an intentional product decision — do not "fix" it away. The whole fleet dead-reckons at ~12Hz (1m² write gating); aircraft get a 3-poll grace period (faded icon) before removal. When a position epoch pauses, both layers coast for at least 60 seconds of contact grace with an absolute five-minute ceiling. Source backoff marks each contact and the cockpit `STALE`; the cockpit then holds the exact layer position instead of continuing inertial flight. Repeated-position kinematic changes create a forward-only synthetic fix rather than mutating history, and grounded history is lifted only when no owned 3D model already controls its datum. A nominally successful worldwide OpenSky response whose own snapshot epoch is more than two minutes old prefers the existing 250-nm viewport-scoped adsb.lol fallback and labels the source/coverage accordingly when that upstream is available. If the fallback is also unavailable, the layer's freshness/error fields use the source epoch—never the cache receipt time—so the UI reports an old snapshot rather than “just now.”
+- **Flights (commercial + military)** render one poll interval behind real time (30s/15s) and interpolate between two known feed-stamped fixes (OpenSky `time_position`; adsb.lol `receipt − seen_pos`). The display latency is an intentional product decision — do not "fix" it away. The fleet dead-reckons at ~12Hz (1m² write gating); a contact already hidden behind the horizon whose last position still is re-reckons on a staggered one-in-12-ticks rotation (about once a second) instead, so the worldwide feed's ~13k contacts no longer cost a full pass when well under 1% are on screen. Anything that position puts in view, and any contact with a fleet model, takes the full pass immediately, and hidden-inclusive proximity queries read positions at most about a second old; aircraft get a 3-poll grace period (faded icon) before removal. When a position epoch pauses, both layers coast for at least 60 seconds of contact grace with an absolute five-minute ceiling. Source backoff marks each contact and the cockpit `STALE`; the cockpit then holds the exact layer position instead of continuing inertial flight. Repeated-position kinematic changes create a forward-only synthetic fix rather than mutating history, and grounded history is lifted only when no owned 3D model already controls its datum. A nominally successful worldwide OpenSky response whose own snapshot epoch is more than two minutes old prefers the existing 250-nm viewport-scoped adsb.lol fallback and labels the source/coverage accordingly when that upstream is available. If the fallback is also unavailable, the layer's freshness/error fields use the source epoch—never the cache receipt time—so the UI reports an old snapshot rather than “just now.”
 - **World-space headings at every angle** (`src/data/iconOrientation.js`): aircraft/vessel icon rotation uses the camera right/up basis per tick (alignedAxis always ZERO), which is exact at screen center and for orthographic/nadir views and remains stable through >180° tracked orbits. Perspective rays vary across the viewport, so off-center contacts at oblique pitch can diverge from an exact finite-difference window projection; a regression test pins that known regime, and field evidence decides whether to adopt exact projection with the basis method as fallback. Fleet rotations refresh on camera-pose change; tracked entities per frame. Billboards are horizon-culled via a shared EllipsoidalOccluder.
 - **Military/OpenSky reconciliation** (`src/data/militaryRegistry.js`): known-military ICAOs render amber in the flights layer (60s self-poll of the cached mil endpoint when the military layer is off) and are suppressed there while the military layer renders them.
 - **Satellites**: 838-sat core catalog (stations/visual/GPS/GLONASS/Galileo/GEO), tracking lands ~726km out via `viewFrom` (tracked entity owns a point graphic so the tracking camera engages), rings realign via primitive modelMatrix (no per-second rebuild flicker), optional `setParams({catalog:'dense'})` Starlink mode.
diff --git a/scripts/format-scope.json b/scripts/format-scope.json
index cd836a5cb..a12d5124f 100644
--- a/scripts/format-scope.json
+++ b/scripts/format-scope.json
@@ -308,6 +308,7 @@
   "src/layers/flights/tracking.js",
   "src/layers/flights/rendering.js",
   "src/layers/flights/testing.js",
+  "src/layers/flights/hiddenContactRotation.test.mjs",
   "src/layers/flights/evidence.js",
   "src/layers/flights/ingestion.js",
   "src/layers/flights/queries.js",
diff --git a/src/layers/flights/hiddenContactRotation.test.mjs b/src/layers/flights/hiddenContactRotation.test.mjs
new file mode 100644
index 000000000..23e81c45b
--- /dev/null
+++ b/src/layers/flights/hiddenContactRotation.test.mjs
@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  FLEET_DR_INTERVAL_MS,
+  HIDDEN_CONTACT_DR_INTERVAL_MS,
+  HIDDEN_CONTACT_DR_TICKS,
+  hiddenContactDrPhase,
+} from './policy.js';
+
+// Contacts hidden behind the horizon re-reckon on one fleet tick per rotation
+// instead of every tick. Their positions still feed hidden-inclusive proximity
+// queries, so the rotation must reach every contact about once a second, and
+// it must spread them across ticks so no single tick carries the whole fleet.
+
+const icao = (n) => n.toString(16).padStart(6, '0');
+
+test('the rotation revisits each hidden contact about once a second', () => {
+  const periodMs = HIDDEN_CONTACT_DR_TICKS * FLEET_DR_INTERVAL_MS;
+  assert.ok(HIDDEN_CONTACT_DR_TICKS > 1);
+  assert.ok(
+    Math.abs(periodMs - HIDDEN_CONTACT_DR_INTERVAL_MS) <= FLEET_DR_INTERVAL_MS,
+  );
+});
+
+test('a contact keeps the same slot, inside the rotation', () => {
+  for (let n = 0; n < 500; n++) {
+    const phase = hiddenContactDrPhase(icao(n * 7919));
+    assert.ok(Number.isInteger(phase));
+    assert.ok(phase >= 0 && phase < HIDDEN_CONTACT_DR_TICKS);
+    assert.equal(hiddenContactDrPhase(icao(n * 7919)), phase);
+  }
+});
+
+test('a worldwide fleet is spread evenly enough that no tick carries a burst', () => {
+  const fleet = 13000;
+  const perSlot = new Array(HIDDEN_CONTACT_DR_TICKS).fill(0);
+  // Real ICAO24 addresses cluster by national block; sample several blocks.
+  for (let n = 0; n < fleet; n++)
+    perSlot[hiddenContactDrPhase(icao(0x0a0000 + n * 53))]++;
+  const fair = fleet / HIDDEN_CONTACT_DR_TICKS;
+  for (const count of perSlot) assert.ok(count < fair * 1.5, `${count} > 1.5×`);
+});
diff --git a/src/layers/flights/policy.js b/src/layers/flights/policy.js
index f8358c98f..04313c367 100644
--- a/src/layers/flights/policy.js
+++ b/src/layers/flights/policy.js
@@ -200,6 +200,37 @@ export const FLEET_DR_INTERVAL_MS = 80;
 
 export const ROTATION_REFRESH_MS = 1000;
 
+/**
+ * @constant {number} Dead-reckoning cadence (ms) for contacts hidden behind the
+ * horizon. The worldwide feed carries ~13k contacts and a zoomed-in view shows
+ * well under 1% of them; the rest still need positions for hidden-inclusive
+ * proximity queries, but ~1 s old (≈250 m for an airliner) is well inside the
+ * 30 s poll's own uncertainty. Each hidden contact is re-reckoned on one tick in
+ * every HIDDEN_CONTACT_DR_TICKS, staggered by id so no tick carries them all.
+ */
+
+export const HIDDEN_CONTACT_DR_INTERVAL_MS = 1000;
+
+export const HIDDEN_CONTACT_DR_TICKS = Math.max(
+  1,
+  Math.round(HIDDEN_CONTACT_DR_INTERVAL_MS / FLEET_DR_INTERVAL_MS),
+);
+
+/**
+ * Stable slot in [0, HIDDEN_CONTACT_DR_TICKS) for a contact id, so each hidden
+ * contact re-reckons on the same tick of every rotation.
+ * @param {string} id Contact id (ICAO24).
+ * @returns {number}
+ */
+
+export function hiddenContactDrPhase(id) {
+  const text = String(id);
+  let hash = 0;
+  for (let i = 0; i < text.length; i++)
+    hash = (hash * 31 + text.charCodeAt(i)) >>> 0;
+  return hash % HIDDEN_CONTACT_DR_TICKS;
+}
+
 /** Max course slew (deg/s) — well above real turns (≤4°/s), hides fix-boundary
  *  steps. Scaled down toward COURSE_MIN_DPS at low speed (courseSlewCapDps). */
 
diff --git a/src/layers/flights/rendering.js b/src/layers/flights/rendering.js
index 44e1b02c3..2048128dd 100644
--- a/src/layers/flights/rendering.js
+++ b/src/layers/flights/rendering.js
@@ -33,6 +33,8 @@ import {
   COURSE_SLEW_DT_MAX_SEC,
   ROTATION_REFRESH_MS,
   COURSE_MAX_DPS,
+  HIDDEN_CONTACT_DR_TICKS,
+  hiddenContactDrPhase,
 } from './policy.js';
 
 export function createRendering({
@@ -811,6 +813,12 @@ export function createRendering({
     }
   }
 
+  /** The contact's hidden-rotation slot, cached on its billboard. */
+  function _hiddenDrPhase(bb, icao24) {
+    bb._gevHiddenDrPhase ??= hiddenContactDrPhase(icao24);
+    return bb._gevHiddenDrPhase;
+  }
+
   function _fleetTick() {
     if (
       !flightState._viewer ||
@@ -931,9 +939,25 @@ export function createRendering({
       for (const icao of toRelease) _releaseModel(icao);
     }
 
+    const hiddenDrPhase = flightState._fleetTickSeq++ % HIDDEN_CONTACT_DR_TICKS;
+
     for (const [icao24, bb] of flightState._billboards) {
       if (icao24 === flightState._trackedIcao) continue; // tracked entity owns its own motion
 
+      // A contact still behind the horizon at its last position would only be
+      // re-reckoned to be hidden again, so off its turn it keeps that position
+      // (see HIDDEN_CONTACT_DR_TICKS). Anything the stale position puts in view,
+      // and any contact with a fleet model, takes the full pass below at once.
+      if (
+        !bb.show &&
+        _hiddenDrPhase(bb, icao24) !== hiddenDrPhase &&
+        !flightState._models.has(icao24) &&
+        !occluder.isPointVisible(
+          flightState._cullPositions.get(icao24) || bb.position,
+        )
+      )
+        continue;
+
       const info = flightState.records.data.get(icao24);
 
       const dr = parts.motion._deadReckon(icao24, flightState._scratchFleetPos);
diff --git a/src/layers/flights/state.js b/src/layers/flights/state.js
index 2978ceba4..d1adec064 100644
--- a/src/layers/flights/state.js
+++ b/src/layers/flights/state.js
@@ -204,6 +204,10 @@ export function createFlightState({ source, services }) {
 
   flightState._lastFleetTickMs = 0;
 
+  /** @type {number} Fleet ticks run; selects which hidden contacts re-reckon */
+
+  flightState._fleetTickSeq = 0;
+
   /** @type {string} Camera pose signature at the last rotation pass */
 
   flightState._lastCamPoseSig = '';

From aa745bcee5c4f76353c9426fb9055cb5737f0fc0 Mon Sep 17 00:00:00 2001
From: Trygve Hemminghytt <274629477+trygvehhh@users.noreply.github.com>
Date: Wed, 7 Oct 2026 04:02:05 +0200
Subject: [PATCH 02/71] data: refresh Norway datacenters from Geofabrik extract

Add a maintainer script that merges a pinned, MD5-verified Geofabrik Norway
extract (osmium tags-filter telecom/building=data_center) into the bundled
datacenter layer. Only features inside the Geofabrik Norway boundary are
touched; unchanged features keep their original line.

norway-261005 (OSM 2026-10-05) adds Troll Housing (w1551029155) and updates
tags on four existing features. Provenance is recorded in the dataset README
and the bundled count moves from 4,351 to 4,352.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   6 +
 DATA_SOURCES.md                               |   2 +-
 README.md                                     |   2 +-
 docs/INFRASTRUCTURE-LAYERS.md                 |   2 +-
 scripts/build-datacenters-norway.py           | 196 ++++++++++++++++++
 src/data/infrastructure.test.mjs              |   2 +-
 src/data/local_data/datacenters/README.md     |  16 +-
 .../datacenters/datacenters.geojsonl          |   9 +-
 8 files changed, 226 insertions(+), 9 deletions(-)
 create mode 100644 scripts/build-datacenters-norway.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b433f8c06..031e36751 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+- Refresh Norway's datacenters from a Geofabrik OpenStreetMap extract
+  (2026-10-05). Troll Housing joins the layer (4,352 features) and four
+  Norwegian sites pick up current OSM tags; no site moved or was removed.
+  `scripts/build-datacenters-norway.py` reproduces or `--verify`s the merge,
+  touching only features inside Geofabrik's Norway boundary, and the dataset
+  README records the extract, checksum and filter.
 - Add Norway's road cameras from Statens vegvesen as a CCTV pack. The camera
   list is one keyless GeoJSON request to the agency's OGC API view of its
   DATEX 3.1 CCTV table, so no DATEX account is needed. Every working camera
diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md
index 734e35a69..b4f0dc0cc 100644
--- a/DATA_SOURCES.md
+++ b/DATA_SOURCES.md
@@ -112,7 +112,7 @@ The [Bhote Koshi event pack](public/events/bhote-koshi-2026/README.md), under `p
 
 | Dataset                                                                     | Folder                            | License                                                                                                   | Commercial use?                                  | Attribution                                                                 |
 | --------------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- |
-| **Datacenters** (4,351) | `datacenters/` | **ODbL 1.0** (OpenStreetMap extract) | ✅ (attribution + share-alike on data) | © OpenStreetMap contributors (shared credit) |
+| **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 |
 | **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"                                   |
diff --git a/README.md b/README.md
index 724ea18cb..0500645af 100644
--- a/README.md
+++ b/README.md
@@ -323,7 +323,7 @@ In the app, **Data Layers** groups them as Movement, Cameras, Infrastructure, Ev
 
 _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,351), Dams (704), and Submarine Cables (712).
+**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)
 
diff --git a/docs/INFRASTRUCTURE-LAYERS.md b/docs/INFRASTRUCTURE-LAYERS.md
index 76567e605..1166a9e69 100644
--- a/docs/INFRASTRUCTURE-LAYERS.md
+++ b/docs/INFRASTRUCTURE-LAYERS.md
@@ -58,6 +58,6 @@ factory and supplies its existing functions. Other consumers should use the pack
 exports, which do not import standalone application globals.
 
 Dataset files and source/license notices remain under `src/data/local_data/`.
-Their input counts are 4,351 datacenter features and 704 dam features. Cesium may
+Their input counts are 4,352 datacenter features and 704 dam features. Cesium may
 expand multipart geometries into multiple entities; entity and stem counts are
 different measurements. This change does not refresh or relicense the datasets.
diff --git a/scripts/build-datacenters-norway.py b/scripts/build-datacenters-norway.py
new file mode 100644
index 000000000..01a891a8b
--- /dev/null
+++ b/scripts/build-datacenters-norway.py
@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Maintainer-only Norway refresh of the bundled datacenter extract (osmium-tool).
+
+Downloads a pinned Geofabrik Norway extract, verifies its MD5, filters
+telecom=data_center / building=data_center with osmium, and merges the result
+into datacenters.geojsonl: features inside the Geofabrik Norway boundary are
+added, updated or removed; every other line is kept byte-for-byte.
+"""
+import argparse
+import hashlib
+import json
+import math
+from pathlib import Path
+import shutil
+import subprocess
+import urllib.request
+
+ROOT = Path(__file__).resolve().parent.parent
+EXTRACT = 'norway-261005'
+GEOFABRIK = 'https://download.geofabrik.de/europe/'
+DATASET = ROOT / 'src/data/local_data/datacenters/datacenters.geojsonl'
+CONTACT_TAGS = {'email', 'phone', 'fax', 'mobile', 'whatsapp', 'contact:email', 'contact:phone',
+                'contact:fax', 'contact:mobile', 'contact:whatsapp'}
+SAME_GEOMETRY_METERS = 0.05
+
+
+def fetch(url, target):
+    if not target.exists():
+        with urllib.request.urlopen(url) as response, open(str(target) + '.part', 'wb') as out:
+            shutil.copyfileobj(response, out)
+        Path(str(target) + '.part').rename(target)
+    return target
+
+
+def md5(path):
+    digest = hashlib.md5()
+    with open(path, 'rb') as handle:
+        for block in iter(lambda: handle.read(1 << 20), b''):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def read_poly(path):
+    """Geofabrik .poly -> list of (ring, is_hole)."""
+    rings, ring, hole = [], None, False
+    for raw in path.read_text().splitlines()[1:]:
+        line = raw.strip()
+        if ring is None:
+            if line and line != 'END':
+                ring, hole = [], line.startswith('!')
+        elif line == 'END':
+            rings.append((ring, hole))
+            ring = None
+        elif line:
+            lon, lat = (float(v) for v in line.split())
+            ring.append((lon, lat))
+    return rings
+
+
+def inside(rings, lon, lat):
+    def in_ring(ring):
+        hit = False
+        for (x1, y1), (x2, y2) in zip(ring, ring[1:] + ring[:1]):
+            if (y1 > lat) != (y2 > lat) and lon < x1 + (lat - y1) * (x2 - x1) / (y2 - y1):
+                hit = not hit
+        return hit
+    return any(in_ring(r) for r, h in rings if not h) and not any(in_ring(r) for r, h in rings if h)
+
+
+def points(coordinates):
+    if isinstance(coordinates[0], (int, float)):
+        return [coordinates]
+    return [p for part in coordinates for p in points(part)]
+
+
+def osm_key(feature):
+    osm_id = feature['properties']['osm_id']
+    if osm_id < 0:
+        return 'r%d' % -osm_id
+    return ('n' if feature['geometry']['type'] == 'Point' else 'w') + str(osm_id)
+
+
+def export(osmium, pbf, cache):
+    filtered = cache / (EXTRACT + '-datacenters.osm.pbf')
+    exported = cache / (EXTRACT + '-datacenters.geojsonseq')
+    subprocess.run([osmium, 'tags-filter', '-O', '-o', str(filtered), str(pbf),
+                    'nwr/telecom=data_center', 'nwr/building=data_center'], check=True)
+    subprocess.run([osmium, 'export', '-O', '-f', 'geojsonseq', '--add-unique-id=type_id',
+                    '-o', str(exported), str(filtered)], check=True)
+    fresh = {}
+    for line in exported.read_text().splitlines():
+        line = line.lstrip('\x1e').strip()
+        if not line:
+            continue
+        feature = json.loads(line)
+        tags = {k: v for k, v in feature['properties'].items() if k not in CONTACT_TAGS}
+        if tags.get('telecom') != 'data_center' and tags.get('building') != 'data_center':
+            continue  # untagged member ways exported only for geometry
+        key = feature['id']
+        geometry = feature['geometry']
+        if key[0] == 'a':  # osmium area id: way * 2 or relation * 2 + 1
+            number = int(key[1:])
+            key = ('w%d' % (number // 2)) if number % 2 == 0 else ('r%d' % (number // 2))
+            if key[0] == 'r':
+                tags = {**tags, 'type': 'multipolygon'}
+            if geometry['type'] == 'MultiPolygon' and len(geometry['coordinates']) == 1:
+                geometry = {'type': 'Polygon', 'coordinates': geometry['coordinates'][0]}
+        elif key in fresh or geometry['type'] == 'LineString':
+            continue  # closed ways are taken from their area export
+        fresh[key] = {'geometry': geometry, 'tags': tags}
+    return fresh
+
+
+def same_geometry(old, new):
+    """Same type and vertex set within tolerance; ring start and winding may differ."""
+    if old['type'] != new['type']:
+        return False
+    a, b = points(old['coordinates']), points(new['coordinates'])
+    if len(a) != len(b):
+        return False
+
+    def meters(p, q):
+        dx = (p[0] - q[0]) * 111320 * math.cos(math.radians(p[1]))
+        return math.hypot(dx, (p[1] - q[1]) * 110540)
+    return all(min(meters(p, q) for q in b) <= SAME_GEOMETRY_METERS for p in a) and \
+        all(min(meters(q, p) for p in a) <= SAME_GEOMETRY_METERS for q in b)
+
+
+def feature_line(key, sequence, fresh):
+    osm_id = int(key[1:]) * (-1 if key[0] == 'r' else 1)
+    feature = {'id': osm_id, 'type': 'Feature', 'geometry': fresh['geometry'],
+               'properties': {'id': sequence, 'tags': fresh['tags'], 'type': 'data_center',
+                              'osm_id': osm_id}}
+    return json.dumps(feature, separators=(',', ':'), ensure_ascii=False)
+
+
+def merge(lines, fresh, rings):
+    out, seen, sequence = [], set(), 0
+    report = {'kept': 0, 'updated': [], 'removed': [], 'added': []}
+    for line in lines:
+        feature = json.loads(line)
+        sequence = max(sequence, feature['properties']['id'])
+        key = osm_key(feature)
+        if key in fresh:
+            seen.add(key)
+            old_tags = feature['properties']['tags']
+            if old_tags == fresh[key]['tags'] and same_geometry(feature['geometry'], fresh[key]['geometry']):
+                out.append(line)
+                report['kept'] += 1
+            else:
+                out.append(feature_line(key, feature['properties']['id'], fresh[key]))
+                report['updated'].append(key)
+            continue
+        lon, lat = points(feature['geometry']['coordinates'])[0][:2]
+        if inside(rings, lon, lat):
+            report['removed'].append(key)
+            continue
+        out.append(line)
+    for key in sorted(set(fresh) - seen, key=lambda k: (k[0], int(k[1:]))):
+        sequence += 1
+        out.append(feature_line(key, sequence, fresh[key]))
+        report['added'].append(key)
+    if len({osm_key(json.loads(line)) for line in out}) != len(out):
+        raise ValueError('Duplicate OSM identity')
+    return out, report
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--cache', type=Path, required=True)
+    parser.add_argument('--osmium', default=shutil.which('osmium') or 'osmium')
+    parser.add_argument('--verify', action='store_true')
+    args = parser.parse_args()
+    args.cache.mkdir(parents=True, exist_ok=True)
+    pbf = fetch(GEOFABRIK + EXTRACT + '.osm.pbf', args.cache / (EXTRACT + '.osm.pbf'))
+    expected = fetch(GEOFABRIK + EXTRACT + '.osm.pbf.md5',
+                     args.cache / (EXTRACT + '.osm.pbf.md5')).read_text().split()[0]
+    actual = md5(pbf)
+    if actual != expected:
+        raise RuntimeError('MD5 mismatch for %s: %s != %s' % (pbf.name, actual, expected))
+    rings = read_poly(fetch(GEOFABRIK + 'norway.poly', args.cache / 'norway.poly'))
+    fresh = export(args.osmium, pbf, args.cache)
+    current = [line for line in DATASET.read_text().splitlines() if line.strip()]
+    merged, report = merge(current, fresh, rings)
+    payload = '\n'.join(merged) + '\n'
+    if args.verify:
+        if payload != DATASET.read_text():
+            raise SystemExit('datacenters.geojsonl is not the %s merge' % EXTRACT)
+    else:
+        DATASET.write_text(payload)
+    print(json.dumps({'extract': EXTRACT, 'md5': actual, 'norway': len(fresh),
+                      'features': len(merged), **report}))
+
+
+if __name__ == '__main__':
+    main()
diff --git a/src/data/infrastructure.test.mjs b/src/data/infrastructure.test.mjs
index 45fb3d317..c7f1b5a23 100644
--- a/src/data/infrastructure.test.mjs
+++ b/src/data/infrastructure.test.mjs
@@ -82,7 +82,7 @@ test('infrastructure factory preserves identity and creates independent state wi
 
 test('dataset URLs still name the complete bundled sources', () => {
   for (const [file, count] of [
-    ['datacenters', 4351],
+    ['datacenters', 4352],
     ['dams', 704],
   ]) {
     const lines = readFileSync(
diff --git a/src/data/local_data/datacenters/README.md b/src/data/local_data/datacenters/README.md
index 454a15007..ef0720ae4 100644
--- a/src/data/local_data/datacenters/README.md
+++ b/src/data/local_data/datacenters/README.md
@@ -5,7 +5,7 @@ layer.
 
 - Source: OpenStreetMap contributors
 - License: Open Database License (ODbL) 1.0
-- Feature count: 4,351
+- Feature count: 4,352
 - Runtime file: `datacenters.geojsonl`
 
 The public-release snapshot removes contact-oriented tags such as email, phone,
@@ -16,3 +16,17 @@ ODbL 1.0 with the required OpenStreetMap attribution.
 
 The original extraction date and query were not recorded alongside this
 snapshot. Future refreshes should record both before replacing the file.
+
+## Norway refresh
+
+Features inside the Geofabrik Norway boundary (`norway.poly`, which includes
+Svalbard) were refreshed separately, so this file mixes two vintages: Norway
+reflects OSM as of the extract below, everything else the original snapshot.
+
+- Extract: Geofabrik `norway-261005.osm.pbf`, OSM data
+  2026-10-05T20:21:35Z, MD5 `1d2cfdeb98980fce11b8891d0f9146c0`
+- Filter: `osmium tags-filter nwr/telecom=data_center nwr/building=data_center`
+- Contact tags are dropped as above; unchanged features keep their original
+  line, so geometry is only rewritten when tags or vertices actually changed.
+- Rebuild or check: `python3 scripts/build-datacenters-norway.py --cache <dir>`
+  (add `--verify` to check without writing; requires `osmium-tool`)
diff --git a/src/data/local_data/datacenters/datacenters.geojsonl b/src/data/local_data/datacenters/datacenters.geojsonl
index f7f5fc89f..b02bd57b3 100644
--- a/src/data/local_data/datacenters/datacenters.geojsonl
+++ b/src/data/local_data/datacenters/datacenters.geojsonl
@@ -3770,15 +3770,15 @@
 {"id":939340882,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[21.021364183,52.315373019],[21.02232433,52.315435883],[21.022363641,52.315209656],[21.021403578,52.315146875],[21.021364183,52.315373019]]]},"properties":{"id":11407,"tags":{"name":"T-Mobile Warszawa-Szlachecka","telecom":"data_center","building":"office","building:levels":"3"},"type":"data_center","osm_id":939340882}}
 {"id":1005973518,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[21.021325375,52.315595978],[21.022285857,52.315658423],[21.02232433,52.315435883],[21.021364183,52.315373019],[21.021325375,52.315595978]]]},"properties":{"id":11976,"tags":{"telecom":"data_center","building":"office","building:levels":"3"},"type":"data_center","osm_id":1005973518}}
 {"id":1156823776,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[21.115130857,52.235385942],[21.115189866,52.236349777],[21.115232027,52.236667954],[21.115818174,52.237174556],[21.116175578,52.237468677],[21.117262124,52.236985628],[21.11728157,52.236976576],[21.117262795,52.236960985],[21.117340495,52.236926033],[21.117360276,52.2369433],[21.117447532,52.236904491],[21.11804097,52.236654459],[21.118030996,52.236645742],[21.118041054,52.236641719],[21.116603055,52.235624072],[21.116518984,52.235676375],[21.115986231,52.235696659],[21.115954966,52.235361551],[21.115130857,52.235385942]]]},"properties":{"id":15342,"tags":{"name":"Atman Data Center Warsaw-1","telecom":"data_center","website":"https://www.atman.pl"},"type":"data_center","osm_id":1156823776}}
-{"id":7405586142,"type":"Feature","geometry":{"type":"Point","coordinates":[5.598350034,58.860111293]},"properties":{"id":24849,"tags":{"name":"Maan Group","telecom":"data_center","operator":"Privat"},"type":"data_center","osm_id":7405586142}}
+{"id":7405586142,"type":"Feature","geometry":{"type":"Point","coordinates":[5.5983501,58.8601113]},"properties":{"id":24849,"tags":{"name":"Maan Group","opening_hours":"24/7","operator":"Privat","telecom":"data_center"},"type":"data_center","osm_id":7405586142}}
 {"id":481615983,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[9.572510149,56.481777951],[9.574069938,56.484921751],[9.57465357,56.48483349],[9.574639572,56.484805243],[9.574700676,56.484795939],[9.574714925,56.484824857],[9.575298557,56.484736595],[9.57454888,56.483225422],[9.574609229,56.483216369],[9.574510155,56.483016629],[9.574449722,56.483025849],[9.573738769,56.481592795],[9.573155137,56.481680972],[9.573170643,56.481712321],[9.573109539,56.481721625],[9.573093781,56.48168969],[9.572510149,56.481777951]]]},"properties":{"id":7881,"tags":{"telecom":"data_center","building":"data_center","operator":"Apple","wikidata":"Q19721053","wikipedia":"en:Foulum Data Center","description":"Apple Datacenter"},"type":"data_center","osm_id":481615983}}
 {"id":618756435,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.500360092,57.318668738],[10.500399236,57.318671672],[10.500382891,57.318734871],[10.500552038,57.318744175],[10.500545249,57.318787677],[10.500501495,57.318785666],[10.500458999,57.318957746],[10.500970295,57.31899647],[10.501009187,57.318847189],[10.501084959,57.318852888],[10.50111966,57.318719197],[10.500843896,57.318698159],[10.500865521,57.318615178],[10.500859235,57.318614759],[10.500869461,57.318575699],[10.500954537,57.318582153],[10.501022347,57.31832223],[10.500736691,57.318300437],[10.500669133,57.318559689],[10.500674162,57.318560025],[10.500664272,57.318598498],[10.500383981,57.318577124],[10.500360092,57.318668738]]]},"properties":{"id":8842,"tags":{"ref":"AAL01-01","name":"Prime Data Centers - Saeby Campus AAL01","telecom":"data_center","website":"https://primedatacenters.com/locations/saeby/","building":"industrial","operator":"Prime Data Centers"},"type":"data_center","osm_id":618756435}}
-{"id":-14367602,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.002243225,59.633471864],[11.003903261,59.633446551],[11.007046726,59.633399696],[11.006983443,59.632420941],[11.006982772,59.63227057],[11.006911023,59.632265289],[11.006852936,59.632253973],[11.006765848,59.632228576],[11.00671782,59.632205275],[11.006119687,59.632213573],[11.006119352,59.632202592],[11.006118933,59.63219245],[11.005930424,59.632194378],[11.005923635,59.632120869],[11.005980799,59.632120031],[11.005979542,59.632104524],[11.005977027,59.63206865],[11.00597225,59.631998242],[11.005412171,59.632035541],[11.005286945,59.632043839],[11.00527848,59.632044342],[11.003707962,59.632147272],[11.003107483,59.63219178],[11.002741864,59.632235533],[11.002729375,59.63223788],[11.002345987,59.632309294],[11.002308352,59.632316251],[11.002302066,59.632477351],[11.002277088,59.632913881],[11.002243225,59.633471864]]]},"properties":{"id":107,"tags":{"name":"STACK Infrastructure OSL04","type":"multipolygon","telecom":"data_center","website":"https://www.stackinfra.com","operator":"Stack Infrastructure","operator:wikidata":"Q115477173"},"type":"data_center","osm_id":-14367602}}
+{"id":-14367602,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.0022433,59.6334719],[11.0022771,59.6329139],[11.0023021,59.6324774],[11.0023084,59.6323163],[11.002346,59.6323093],[11.0027294,59.6322379],[11.0027419,59.6322356],[11.0031075,59.6321918],[11.003708,59.6321473],[11.0052785,59.6320444],[11.005287,59.6320439],[11.0054122,59.6320356],[11.0059723,59.6319983],[11.0059771,59.6320687],[11.0059796,59.6321046],[11.0059808,59.6321201],[11.0059237,59.6321209],[11.0059305,59.6321944],[11.006119,59.6321925],[11.0061194,59.6322026],[11.0061197,59.6322136],[11.0067179,59.6322053],[11.0067659,59.6322286],[11.006853,59.632254],[11.0069111,59.6322653],[11.0069828,59.6322706],[11.0069835,59.632421],[11.0070468,59.6333997],[11.0039033,59.6334466],[11.0022433,59.6334719]]]},"properties":{"id":107,"tags":{"landuse":"industrial","name":"STACK Infrastructure OSL04","operator":"Stack Infrastructure","operator:wikidata":"Q115477173","telecom":"data_center","website":"https://www.stackinfra.com","type":"multipolygon"},"type":"data_center","osm_id":-14367602}}
 {"id":1028687251,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.004111886,59.632578437],[11.004142983,59.633037262],[11.004275166,59.633034999],[11.004274998,59.63303173],[11.00505133,59.633019157],[11.005056443,59.633099372],[11.005224416,59.63309669],[11.005190637,59.632562344],[11.005060885,59.632564439],[11.005060969,59.632567457],[11.004587978,59.632575419],[11.00458538,59.632536527],[11.004459819,59.632538623],[11.004462418,59.632576844],[11.004242476,59.6325807],[11.004242141,59.632576174],[11.004111886,59.632578437]]]},"properties":{"id":12226,"tags":{"building":"data_center","ref:bygningsnr":"300783262"},"type":"data_center","osm_id":1028687251}}
 {"id":1164840308,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.002600126,59.632599392],[11.002631223,59.633058217],[11.00276349,59.633055954],[11.002763238,59.633052685],[11.00353957,59.633040196],[11.003544683,59.633120327],[11.00371274,59.633117645],[11.003678961,59.632583382],[11.003549042,59.632585478],[11.003549293,59.632588495],[11.003076135,59.632596458],[11.00307362,59.632557566],[11.002948143,59.632559661],[11.002950657,59.632597883],[11.002730716,59.632601571],[11.002730465,59.632597129],[11.002600126,59.632599392]]]},"properties":{"id":15459,"tags":{"building":"data_center","ref:bygningsnr":"300783262"},"type":"data_center","osm_id":1164840308}}
 {"id":1164840309,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.005613672,59.632723444],[11.005644769,59.633182269],[11.005776951,59.633179922],[11.005776784,59.633176737],[11.006553199,59.633164164],[11.006558229,59.633244463],[11.006726286,59.633241781],[11.006692423,59.632707351],[11.006562671,59.632709446],[11.006562839,59.632712464],[11.006089764,59.632720426],[11.006087166,59.632681534],[11.005961772,59.632683797],[11.005964287,59.632721851],[11.005744262,59.632725623],[11.005743927,59.632721181],[11.005613672,59.632723444]]]},"properties":{"id":15460,"tags":{"building":"data_center","ref:bygningsnr":"300783262"},"type":"data_center","osm_id":1164840309}}
-{"id":935092287,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.991467366,59.759024056],[10.992780978,59.759406942],[10.992773937,59.759423957],[10.992948197,59.759474248],[10.993073842,59.759363859],[10.993022293,59.759348939],[10.993291688,59.759112653],[10.993128827,59.759065547],[10.993181885,59.759019027],[10.993083062,59.758990445],[10.992976947,59.759083484],[10.992845519,59.759045346],[10.992813584,59.759073342],[10.9927876,59.759065798],[10.993409789,59.758524243],[10.99263002,59.758297094],[10.991938848,59.758898663],[10.991693594,59.758827165],[10.991467366,59.759024056]]]},"properties":{"id":11377,"tags":{"name":"Green Mountain Ytre Enebakk","telecom":"data_center","website":"https://greenmountain.no/","building":"warehouse","ref:bygningsnr":"300752944"},"type":"data_center","osm_id":935092287}}
-{"id":1161764012,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.992826324,59.757448761],[10.994530281,59.757601396],[10.994634888,59.757303168],[10.992928332,59.757152545],[10.992826324,59.757448761]]]},"properties":{"id":15426,"tags":{"name":"Green Mountain Ytre Enebakk","telecom":"data_center","website":"https://greenmountain.no/","building":"industrial"},"type":"data_center","osm_id":1161764012}}
+{"id":935092287,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.9914674,59.7590241],[10.9916936,59.7588272],[10.9919389,59.7588987],[10.9926301,59.7582971],[10.9934098,59.7585243],[10.9927876,59.7590658],[10.9928136,59.7590734],[10.9928456,59.7590454],[10.992977,59.7590835],[10.9930831,59.7589905],[10.9931819,59.7590191],[10.9931289,59.7590656],[10.9932917,59.7591127],[10.9930223,59.759349],[10.9930739,59.7593639],[10.9929482,59.7594743],[10.992774,59.759424],[10.992781,59.759407],[10.9914674,59.7590241]]]},"properties":{"id":11377,"tags":{"building":"warehouse","name":"Green Mountain Ytre Enebakk","ref:bygningsnr":"300752944","source":"Norway Orthophoto 2024;https://greenmountain.no/data-center/osl1-enebakk/","telecom":"data_center","website":"https://greenmountain.no/"},"type":"data_center","osm_id":935092287}}
+{"id":1161764012,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.9928264,59.7574488],[10.9929284,59.7571526],[10.9946349,59.7573032],[10.9945303,59.7576014],[10.9928264,59.7574488]]]},"properties":{"id":15426,"tags":{"building":"industrial","name":"Green Mountain Ytre Enebakk","source":"Norway Orthophoto 2024;https://greenmountain.no/data-center/osl1-enebakk/","telecom":"data_center","website":"https://greenmountain.no/"},"type":"data_center","osm_id":1161764012}}
 {"id":30724580,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.808790995,59.924984985],[10.808893925,59.925031923],[10.80893793,59.92500594],[10.808982941,59.925025972],[10.809042955,59.92501298],[10.809083943,59.925031923],[10.809012948,59.925077856],[10.80926583,59.925189755],[10.80955115,59.925025972],[10.809676543,59.925081293],[10.81032899,59.924701928],[10.809890365,59.924508138],[10.80982155,59.924515347],[10.809691631,59.924457847],[10.808820667,59.924557592],[10.809099365,59.924699581],[10.808806418,59.924865291],[10.808918149,59.924914828],[10.808875988,59.924937962],[10.808790995,59.924984985]]]},"properties":{"id":261,"tags":{"name":"Stack Infrastructure OSLO1A","telecom":"data_center","building":"office","operator":"Stack Infrastructure","ref:bygningsnr":"80877293","building:levels":"4","operator:wikidata":"Q115477173"},"type":"data_center","osm_id":30724580}}
 {"id":80871917,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.83408892,59.938588981],[10.834305927,59.938720996],[10.834575992,59.938720996],[10.834574987,59.938736],[10.834581943,59.938736922],[10.834579932,59.938771958],[10.834736925,59.938771958],[10.834734997,59.93893792],[10.836717988,59.938944961],[10.836717988,59.938983937],[10.836817984,59.938983937],[10.83681899,59.938944961],[10.836844974,59.938944961],[10.836846985,59.938774976],[10.836841956,59.938774976],[10.836842962,59.938744968],[10.836849919,59.938744968],[10.836851931,59.938653941],[10.836683957,59.938652935],[10.836684125,59.938640278],[10.836686975,59.938414973],[10.83490297,59.938406926],[10.834899953,59.938646984],[10.834812949,59.938645978],[10.83481496,59.938551933],[10.834579932,59.938550927],[10.834580938,59.938564925],[10.834567946,59.938564925],[10.834567946,59.938551933],[10.834089926,59.938549922],[10.83408892,59.938588981]]]},"properties":{"id":1464,"tags":{"name":"Bulk Data Centers Oslo Internet Exchange","telecom":"data_center","website":"https://bulkinfrastructure.com/data-centers/locations/os-ix","building":"industrial","ref:bygningsnr":"80709943"},"type":"data_center","osm_id":80871917}}
 {"id":12158409495,"type":"Feature","geometry":{"type":"Point","coordinates":[9.689363435,62.59439936]},"properties":{"id":28723,"tags":{"name":"VisBook AS","telecom":"data_center","website":"https://visbook.com/"},"type":"data_center","osm_id":12158409495}}
@@ -4349,3 +4349,4 @@
 {"id":540895898,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[101.71747909,56.303855963],[101.71782015,56.304420065],[101.721113819,56.303806929],[101.720772759,56.303242994],[101.71747909,56.303855963]]]},"properties":{"id":8271,"tags":{"name":"Битривер Рус","name:en":"Bitriver Rus","name:ru":"Битривер Рус","telecom":"data_center","website":"https://bitriver.farm/","building":"data_center"},"type":"data_center","osm_id":540895898}}
 {"id":1082803064,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[123.948021193,47.340264299],[123.948354625,47.340268239],[123.948490663,47.340269831],[123.948488568,47.340349292],[123.948809762,47.340353064],[123.948811942,47.340267485],[123.948918643,47.340268658],[123.948922918,47.340137817],[123.948023959,47.340126082],[123.948021193,47.340264299]]]},"properties":{"id":13377,"tags":{"name":"联通云数据中心·齐齐哈尔","name:en":"Unicom Data Center of Qiqihar","name:zh":"联通云数据中心·齐齐哈尔","telecom":"data_center","building":"yes","name:zh-Hans":"联通云数据中心·齐齐哈尔","name:zh-Hant":"聯通雲數據中心·齊齊哈爾"},"type":"data_center","osm_id":1082803064}}
 {"id":442479059,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[142.76019226,46.910096898],[142.760192427,46.910325724],[142.760447656,46.910328155],[142.760460397,46.910102263],[142.76019226,46.910096898]]]},"properties":{"id":7471,"tags":{"telecom":"data_center","building":"yes"},"type":"data_center","osm_id":442479059}}
+{"id":1551029155,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[7.1069147,62.8627625],[7.1071207,62.8621617],[7.1075917,62.8616616],[7.1088647,62.8620476],[7.1106308,62.862645],[7.1098655,62.8632827],[7.1089604,62.8630042],[7.1086734,62.8632156],[7.1069147,62.8627625]]]},"properties":{"id":29471,"tags":{"layer":"-1","loc_name":"Troll Housing Klempertåsen","name":"Troll Housing","operator":"Troll Housing AS","telecom":"data_center","website":"https://www.trollhousing.no/"},"type":"data_center","osm_id":1551029155}}

From 5b5d942d95dddd56b3bacb465c69098913688d1f Mon Sep 17 00:00:00 2001
From: Trygve Hemminghytt <274629477+trygvehhh@users.noreply.github.com>
Date: Fri, 16 Oct 2026 22:23:02 +0200
Subject: [PATCH 03/71] fix(data): make the Norway datacenter script portable
 and re-runnable

Read and write files as UTF-8 with LF line endings so the script and
--verify work on Windows, where the default codec is cp1252 (thanks to
quanticsoul4772 for the report). Geofabrik keeps only its newest dated
extract, so --extract now defaults to the current one and accepts a dated
name for --verify while it is listed; the dataset README says so. Downloads
time out instead of hanging.
---
 CHANGELOG.md                              |  1 +
 scripts/build-datacenters-norway.py       | 52 +++++++++++++++--------
 src/data/local_data/datacenters/README.md |  8 +++-
 3 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 20a9da4e6..067ca16b6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -184,6 +184,7 @@
   `scripts/build-datacenters-norway.py` reproduces or `--verify`s the merge,
   touching only features inside Geofabrik's Norway boundary, and the dataset
   README records the extract, checksum and filter.
+
 - Add a keyless Air quality layer to the Weather group, with Environment and
   Climate Change Canada's AQHI as the first registered provider. Readings carry
   `{ provider, scale, value, band }` so another network can be added without
diff --git a/scripts/build-datacenters-norway.py b/scripts/build-datacenters-norway.py
index 01a891a8b..687395f7b 100644
--- a/scripts/build-datacenters-norway.py
+++ b/scripts/build-datacenters-norway.py
@@ -1,10 +1,13 @@
 #!/usr/bin/env python3
 """Maintainer-only Norway refresh of the bundled datacenter extract (osmium-tool).
 
-Downloads a pinned Geofabrik Norway extract, verifies its MD5, filters
+Downloads a dated Geofabrik Norway extract, verifies its MD5, filters
 telecom=data_center / building=data_center with osmium, and merges the result
 into datacenters.geojsonl: features inside the Geofabrik Norway boundary are
 added, updated or removed; every other line is kept byte-for-byte.
+
+Geofabrik keeps only its newest dated extract, so --extract defaults to the
+current one and a recorded extract can be re-verified only while it is listed.
 """
 import argparse
 import hashlib
@@ -16,17 +19,28 @@ import subprocess
 import urllib.request
 
 ROOT = Path(__file__).resolve().parent.parent
-EXTRACT = 'norway-261005'
 GEOFABRIK = 'https://download.geofabrik.de/europe/'
 DATASET = ROOT / 'src/data/local_data/datacenters/datacenters.geojsonl'
 CONTACT_TAGS = {'email', 'phone', 'fax', 'mobile', 'whatsapp', 'contact:email', 'contact:phone',
                 'contact:fax', 'contact:mobile', 'contact:whatsapp'}
 SAME_GEOMETRY_METERS = 0.05
+TIMEOUT_SECONDS = 60
+
+
+def latest_extract():
+    """Resolve norway-latest to the dated name Geofabrik redirects it to."""
+    request = urllib.request.Request(GEOFABRIK + 'norway-latest.osm.pbf', method='HEAD')
+    with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+        name = response.geturl().rsplit('/', 1)[-1]
+    if not name.startswith('norway-') or not name.endswith('.osm.pbf') or name == 'norway-latest.osm.pbf':
+        raise RuntimeError('Unexpected Geofabrik latest target: %s' % name)
+    return name[:-len('.osm.pbf')]
 
 
 def fetch(url, target):
     if not target.exists():
-        with urllib.request.urlopen(url) as response, open(str(target) + '.part', 'wb') as out:
+        with urllib.request.urlopen(url, timeout=TIMEOUT_SECONDS) as response, \
+                open(str(target) + '.part', 'wb') as out:
             shutil.copyfileobj(response, out)
         Path(str(target) + '.part').rename(target)
     return target
@@ -43,7 +57,7 @@ def md5(path):
 def read_poly(path):
     """Geofabrik .poly -> list of (ring, is_hole)."""
     rings, ring, hole = [], None, False
-    for raw in path.read_text().splitlines()[1:]:
+    for raw in path.read_text(encoding='utf-8').splitlines()[1:]:
         line = raw.strip()
         if ring is None:
             if line and line != 'END':
@@ -80,15 +94,15 @@ def osm_key(feature):
     return ('n' if feature['geometry']['type'] == 'Point' else 'w') + str(osm_id)
 
 
-def export(osmium, pbf, cache):
-    filtered = cache / (EXTRACT + '-datacenters.osm.pbf')
-    exported = cache / (EXTRACT + '-datacenters.geojsonseq')
+def export(osmium, pbf, cache, extract):
+    filtered = cache / (extract + '-datacenters.osm.pbf')
+    exported = cache / (extract + '-datacenters.geojsonseq')
     subprocess.run([osmium, 'tags-filter', '-O', '-o', str(filtered), str(pbf),
                     'nwr/telecom=data_center', 'nwr/building=data_center'], check=True)
     subprocess.run([osmium, 'export', '-O', '-f', 'geojsonseq', '--add-unique-id=type_id',
                     '-o', str(exported), str(filtered)], check=True)
     fresh = {}
-    for line in exported.read_text().splitlines():
+    for line in exported.read_text(encoding='utf-8').splitlines():
         line = line.lstrip('\x1e').strip()
         if not line:
             continue
@@ -169,26 +183,30 @@ def main():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument('--cache', type=Path, required=True)
     parser.add_argument('--osmium', default=shutil.which('osmium') or 'osmium')
+    parser.add_argument('--extract', default='latest',
+                        help="dated Geofabrik name such as norway-261005, or 'latest'")
     parser.add_argument('--verify', action='store_true')
     args = parser.parse_args()
     args.cache.mkdir(parents=True, exist_ok=True)
-    pbf = fetch(GEOFABRIK + EXTRACT + '.osm.pbf', args.cache / (EXTRACT + '.osm.pbf'))
-    expected = fetch(GEOFABRIK + EXTRACT + '.osm.pbf.md5',
-                     args.cache / (EXTRACT + '.osm.pbf.md5')).read_text().split()[0]
+    extract = latest_extract() if args.extract == 'latest' else args.extract
+    pbf = fetch(GEOFABRIK + extract + '.osm.pbf', args.cache / (extract + '.osm.pbf'))
+    expected = fetch(GEOFABRIK + extract + '.osm.pbf.md5',
+                     args.cache / (extract + '.osm.pbf.md5')).read_text(encoding='utf-8').split()[0]
     actual = md5(pbf)
     if actual != expected:
         raise RuntimeError('MD5 mismatch for %s: %s != %s' % (pbf.name, actual, expected))
     rings = read_poly(fetch(GEOFABRIK + 'norway.poly', args.cache / 'norway.poly'))
-    fresh = export(args.osmium, pbf, args.cache)
-    current = [line for line in DATASET.read_text().splitlines() if line.strip()]
+    fresh = export(args.osmium, pbf, args.cache, extract)
+    current = [line for line in DATASET.read_text(encoding='utf-8').splitlines() if line.strip()]
     merged, report = merge(current, fresh, rings)
     payload = '\n'.join(merged) + '\n'
     if args.verify:
-        if payload != DATASET.read_text():
-            raise SystemExit('datacenters.geojsonl is not the %s merge' % EXTRACT)
+        if payload != DATASET.read_text(encoding='utf-8'):
+            raise SystemExit('datacenters.geojsonl is not the %s merge' % extract)
     else:
-        DATASET.write_text(payload)
-    print(json.dumps({'extract': EXTRACT, 'md5': actual, 'norway': len(fresh),
+        with open(DATASET, 'w', encoding='utf-8', newline='\n') as handle:
+            handle.write(payload)
+    print(json.dumps({'extract': extract, 'md5': actual, 'norway': len(fresh),
                       'features': len(merged), **report}))
 
 
diff --git a/src/data/local_data/datacenters/README.md b/src/data/local_data/datacenters/README.md
index ef0720ae4..8b803dcc7 100644
--- a/src/data/local_data/datacenters/README.md
+++ b/src/data/local_data/datacenters/README.md
@@ -28,5 +28,9 @@ reflects OSM as of the extract below, everything else the original snapshot.
 - Filter: `osmium tags-filter nwr/telecom=data_center nwr/building=data_center`
 - Contact tags are dropped as above; unchanged features keep their original
   line, so geometry is only rewritten when tags or vertices actually changed.
-- Rebuild or check: `python3 scripts/build-datacenters-norway.py --cache <dir>`
-  (add `--verify` to check without writing; requires `osmium-tool`)
+- Refresh: `python3 scripts/build-datacenters-norway.py --cache <dir>` uses
+  Geofabrik's current Norway extract and prints the dated name it used; record
+  that name, its OSM timestamp and MD5 here. Requires `osmium-tool`.
+- Check: add `--extract <dated name> --verify` to compare without writing.
+  Geofabrik keeps only its newest dated extract, so a recorded extract can be
+  re-verified only while it is still listed; the MD5 above identifies it.

From 4318f51de4114bfb68137ff48bedd070b976f771 Mon Sep 17 00:00:00 2001
From: Trygve Hemminghytt <274629477+trygvehhh@users.noreply.github.com>
Date: Sun, 18 Oct 2026 20:03:23 +0200
Subject: [PATCH 04/71] docs: move the changelog entry to changelog.d

---
 CHANGELOG.md                                  | 7 -------
 changelog.d/953-datacenters-norway-refresh.md | 6 ++++++
 2 files changed, 6 insertions(+), 7 deletions(-)
 create mode 100644 changelog.d/953-datacenters-norway-refresh.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a285bc555..98d32365f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -284,13 +284,6 @@
 
 ## [Unreleased]
 
-- Refresh Norway's datacenters from a Geofabrik OpenStreetMap extract
-  (2026-10-05). Troll Housing joins the layer (4,352 features) and four
-  Norwegian sites pick up current OSM tags; no site moved or was removed.
-  `scripts/build-datacenters-norway.py` reproduces or `--verify`s the merge,
-  touching only features inside Geofabrik's Norway boundary, and the dataset
-  README records the extract, checksum and filter.
-
 - Add a keyless Air quality layer to the Weather group, with Environment and
   Climate Change Canada's AQHI as the first registered provider. Readings carry
   `{ provider, scale, value, band }` so another network can be added without
diff --git a/changelog.d/953-datacenters-norway-refresh.md b/changelog.d/953-datacenters-norway-refresh.md
new file mode 100644
index 000000000..48a019605
--- /dev/null
+++ b/changelog.d/953-datacenters-norway-refresh.md
@@ -0,0 +1,6 @@
+- Refresh Norway's datacenters from a Geofabrik OpenStreetMap extract
+  (2026-10-05). Troll Housing joins the layer (4,352 features) and four
+  Norwegian sites pick up current OSM tags; no site moved or was removed.
+  `scripts/build-datacenters-norway.py` reproduces or `--verify`s the merge,
+  touching only features inside Geofabrik's Norway boundary, and the dataset
+  README records the extract, checksum and filter (trygvehhh, #953).

From a4c7b20ca825a731531b61fc2935f1a47621248a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Itallo=20Brand=C3=A3o?=
 <45429643+IMBrandao@users.noreply.github.com>
Date: Thu, 29 Oct 2026 16:11:10 -0300
Subject: [PATCH 05/71] feat(transit): add Rio de Janeiro buses and BRT (SMTR
 GTFS-RT, CC BY 4.0)

Register Rio's two keyless GTFS-Realtime VehiclePositions feeds from the
city transport secretariat (SMTR): municipal buses (SPPO) and the
Mobi-Rio BRT, the Transit layer's first Latin American region.

Both feeds publish Position.speed in km/h instead of m/s. A new optional
registry field, speedUnit: 'kmh', makes buildTransitSnapshot convert it
once, so every speedMps consumer stays correct and other feeds are
untouched.

Document the source in DATA_SOURCES.md and update the region lists in
README.md and docs/CURRENT-STATE.md.

Refs #1480

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 DATA_SOURCES.md                |  3 +-
 README.md                      |  2 +-
 docs/CURRENT-STATE.md          |  8 ++++--
 src/data/transitFeeds.js       | 50 ++++++++++++++++++++++++++++++++++
 src/data/transitFeeds.test.mjs | 43 +++++++++++++++++++++++++++++
 src/data/transitProxy.js       | 21 +++++++++++++-
 src/data/transitProxy.test.mjs | 26 ++++++++++++++++++
 7 files changed, 147 insertions(+), 6 deletions(-)

diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md
index e31d0d3f0..2b989c509 100644
--- a/DATA_SOURCES.md
+++ b/DATA_SOURCES.md
@@ -95,6 +95,7 @@ How to read this:
 | **Barrie Transit** (myridebarrie.ca) | Transit layer live vehicles, Barrie ON | Barrie Transit realtime data, published by the City of Barrie under a licence accepted by use of the data. The licence is revocable and requires no attribution. | Courtesy credit to the City of Barrie (the licence requires none, and its trademark clause is broad) |
 | **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. Speeds arrive in km/h rather than m/s and are converted by the proxy. Route ids are internal keys and are shown raw. | Attribution to SMTR / Prefeitura da Cidade do Rio de Janeiro under CC BY 4.0 |
 | **Radio Browser**                                                     | Geolocated internet-radio station directory and station-level tags                                                                  | Public-domain directory data under PDDL 1.0; individual broadcaster stream terms apply                                                                                                                                                                                                                                                                | "Radio Browser" plus a link to the selected broadcaster                                                                                     |
 | **Re:Earth Terrain** (Mapterhorn)                                     | Terrain (keyless globe stacks — OSM etc. — + `/api/terrain/heights` ellipsoidal-height lookups)                                     | Terrain mesh: CC BY 4.0; geoid: EGM2008 (NGA, public domain)                                                                                                                                                                                                                                                                                          | "Terrain (keyless globe stacks): Re:Earth Terrain / Mapterhorn (CC BY 4.0) / EGM2008 (NGA)"                                                 |
 | **OSRM on the FOSSGIS routing servers** (`routing.openstreetmap.de`) | Street-following routes for the Directions layer and voice route annotations, via `/api/route` | [FOSSGIS routing usage policy](https://routing.openstreetmap.de/about.html): "Display the required attribution and display a link to 'fix the map'", "Use a valid user agent and, if applicable, a correct referrer", "One request per second max", "No scraping, no heavy usage". The full policy is the German [FOSSGIS Nutzungsbedingungen](https://www.fossgis.de/arbeitsgruppen/osm-server/nutzungsbedingungen/); FOSSGIS also states that the server may be embedded in your own pages but "eine gewerbliche Nutzung ist nur mit Einschränkungen erlaubt" (commercial use only with restrictions). Route data derives from OpenStreetMap (ODbL 1.0) | "Routing: OSRM on the FOSSGIS servers" + a "fix the map" link — shown in the Data attribution popover |
@@ -177,7 +178,7 @@ The optional Local ADS-B layer and the broadcast-FM receiver use radio you recei
 - **NYC DOT Traffic Management Center cameras.** Off by default. NYC DOT's [developer data feeds page](https://www.nyc.gov/html/dot/html/about/datafeeds.shtml) asks developers who want the camera feed to contact `tmcdot@dot.nyc.gov` and sign a data-sharing agreement. This project does not hold one that covers downstream installations, so the pack loads only when an operator who holds their own agreement sets `CCTV_NYC_ENABLED=1`; with the flag unset, empty or any other value, the server makes no request to NYC DOT. The endpoint needs no key. The camera list is the public `webcams.nyctmc.org/api/cameras` catalog (~980 cameras across the five boroughs); frames are stills at `webcams.nyctmc.org/api/cameras/<uuid>/image`, synthesized from a validated UUID rather than taken from the payload, and only that host is registered. Cameras the feed reports as offline are dropped. The catalog publishes no camera facing, so headings use the shared id-hash fallback at low confidence and are corrected with the in-app calibration gizmo. Once enabled, the 250 cameras nearest the borough cores load; `CCTV_NYC_MAX_SOURCES` (8–400) changes the cap. Frames are fetched at request time and never stored or redistributed. NYC DOT asks every application that uses its data to carry its disclaimer; it is registered verbatim in the Data attribution popover.
 - **City of Toronto RESCU cameras.** Keyless. The camera list is the City's public `tmcearthcameras.json` on `opendata.toronto.ca` (dataset "Traffic Cameras", Transportation Services), served as JSONP and unwrapped with an anchored pattern. This is the municipal network the Ontario 511 pack does not carry: downtown arterials plus the Gardiner, DVP, Allen and Lake Shore. The list publishes no frame URL, so frame URLs are BUILT from the documented `CameraImages/loc####.jpg` convention and a strictly-digits camera number, pinning the frame proxy to the portal origin by construction; the list fetch refuses redirects and bounds the body it buffers. Frames are fetched at request time and never stored or redistributed. The dataset publishes no camera facing: the `D1`-`D4` fields are the directions of the *comparison* images (static reference stills captured in 2016 under a different path), not a bearing for the live pan-tilt-zoom frame, so headings use the shared id-hash fallback at low confidence and are corrected with the in-app calibration gizmo. A camera that is temporarily out of service still answers 200 with a byte-identical "Image Unavailable" placeholder rather than an error (about 6% of the network at any moment), so such a camera reads as healthy; the frame it shows is the agency's, not a synthesized one. The licence requires the attribution statement above. Disable with `CCTV_TORONTO_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 sixteen registered 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 and YRT 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 eighteen registered feeds, covering seventeen 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 and YRT 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.
 - **Radio Browser.** `/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; schema-valid responses whose rows all fail the product's health policy do not count as successful queries. A usable partial cold catalog is explicitly `DEGRADED`, and non-array or empty successful 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.
 - **TomTom Traffic.** Optional and BYOK: without `TOMTOM_API_KEY` the traffic layer runs its built-in simulation and no TomTom data (or attribution) appears. With a key, flow vector tiles are fetched through the server-side `/api/tomtom` proxy (120 s cache + a daily tile-budget governor — `TOMTOM_DAILY_TILE_BUDGET`, default 6,000 — sized so a 31-day month stays inside TomTom's 200K monthly free allowance; still a configurable application safety ceiling, not a guarantee; TomTom's [current pricing](https://docs.tomtom.com/pricing/) lists 200K free tile requests per month) and the "Traffic flow data © TomTom" credit is registered in the Data attribution popover the moment live mode activates. TomTom data is served live and cached only transiently (≤120 s TTL under `.gev-cache/`, gitignored) — it is not bundled or redistributed. One 23 KB point-in-time tile snapshot is committed as a decode-test fixture (`src/data/fixtures/`, © TomTom, never served to the app).
 - **Routing (OSRM / FOSSGIS).** `/api/route` proxies the public OSRM instances FOSSGIS e.V. runs for the OpenStreetMap community (car, bike, foot profiles). They are keyless and intended for fair, interactive use — the proxy rate-limits clients (60/min, 200/min total), caps route span and response size, caches each route for 10 minutes, and identifies itself in the User-Agent. Heavy or automated use must run its own OSRM. Routes are computed from OpenStreetMap data (ODbL); the Directions layer and voice routes never redistribute them. A route the router cannot find is reported as such; the Directions layer draws nothing in that case, and voice routes fall back to a clearly labeled straight line.
diff --git a/README.md b/README.md
index 745bec3d8..965c0e283 100644
--- a/README.md
+++ b/README.md
@@ -403,7 +403,7 @@ Twenty layers and map sources. **Eighteen have a keyless path.** Some offer addi
 | 📷 **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, 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, Rio de Janeiro (buses and BRT), 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            | 🟢                                                                                                  |
 | 🚲 **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) | 🟢                                                                                                  |
 | 🔥 **Active Fires**         | Live NASA FIRMS detections, trailing 24h                                                                                                                                                                                                                                                                                                                                            | NASA FIRMS                              | 🟡                                                                                                  |
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 966bb3878..2adac270e 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -4295,11 +4295,13 @@ Transit is off by default, and share links use token `j`. The movement panel ord
 places Transit directly after Street Traffic and before Bike Share. Cameras and
 utilities retain their own groups. The layer polls
 registered feeds near the camera every 15 seconds, below a 3,000 km altitude
-gate. Sixteen keyless regions are available: Boston, Austin, Minneapolis–St Paul,
-Helsinki, the Netherlands, Norway, South East Queensland, and nine in
+gate. Seventeen keyless regions are available: Boston, Austin, Minneapolis–St Paul,
+Helsinki, the Netherlands, Norway, South East Queensland, Rio de Janeiro
+(municipal buses and the Mobi-Rio BRT, two feeds), and nine in
 Ontario — Toronto (TTC surface vehicles; the subway publishes no
 positions), MiWay, Hamilton HSR, Durham Region, YRT/Viva, Guelph,
-Burlington, Barrie and Kingston. Mode silhouettes
+Burlington, Barrie and Kingston. Rio's feeds publish speed in km/h, which
+the proxy converts to m/s before any card reads it. Mode silhouettes
 identify buses, trams, subways, trains, ferries and unclassified vehicles.
 
 Retained transit history uses the same outlier quarantine as live observations and
diff --git a/src/data/transitFeeds.js b/src/data/transitFeeds.js
index b8476a6ee..e871a2e89 100644
--- a/src/data/transitFeeds.js
+++ b/src/data/transitFeeds.js
@@ -385,7 +385,12 @@ function burlingtonRouteLabel(routeId) {
  *   url: string, headers?: Record<string, string>,
  *   license: string, licenseUrl: string, attribution: string,
  *   defaultMode: string, routeMode?: (routeId: string|null) => string,
+ *   speedUnit?: 'kmh',
  * }>>}
+ *
+ * `speedUnit: 'kmh'` marks a feed that publishes `Position.speed` in km/h
+ * instead of the m/s the spec requires; the proxy converts it before anything
+ * downstream reads `speedMps`.
  */
 export const TRANSIT_FEED_REGISTRY = Object.freeze([
   Object.freeze({
@@ -729,6 +734,51 @@ export const TRANSIT_FEED_REGISTRY = Object.freeze([
     defaultMode: 'bus',
     routeLabel: burlingtonRouteLabel,
   }),
+  Object.freeze({
+    id: 'smtr-rio-onibus',
+    name: 'Rio buses (SPPO)',
+    operator: 'Secretaria Municipal de Transportes (SMTR), Rio de Janeiro',
+    region: 'Rio de Janeiro, RJ',
+    // Every vehicle in a 2026-10-29 snapshot, from Santa Cruz in the west to
+    // the Zona Sul, sat within 31 km of this point.
+    center: Object.freeze({ lat: -22.92, lon: -43.42 }),
+    loadRadiusKm: 45,
+    url: 'https://dados.mobilidade.rio/gtfs/realtime/onibus/vehicle-positions',
+    license: 'CC BY 4.0',
+    licenseUrl:
+      'https://www.data.rio/documents/997bc16cc4344a5cb0e48ab06cbdfd1f',
+    attribution: 'SMTR / Prefeitura da Cidade do Rio de Janeiro (CC BY 4.0)',
+    defaultEnabled: true,
+    terms: Object.freeze({
+      quote:
+        'This work is licensed under a Creative Commons Attribution 4.0 International License',
+      note: 'The data.rio catalog page labels the feed [beta] and states a gateway limit of 5 requests a second and 60 a minute behind a 10-second cache, which the 15-second proxy TTL stays inside. It is the named replacement for the JSON GPS endpoints SMTR deprecated on 2026-10-07 and says it will switch off by 2026-11-30. SMTR relays the concessionaires’ ITS data and repairs trips with its own matching; the page places accuracy with the suppliers. Speeds arrive in km/h, not m/s (a 2026-10-29 snapshot peaked at 89), hence `speedUnit`. Route ids are internal keys: `O0313AAA0A` carried service 313 in the same day’s JSON feed. They are shown raw until a published table is joined.',
+    }),
+    defaultMode: 'bus',
+    speedUnit: 'kmh',
+  }),
+  Object.freeze({
+    id: 'smtr-rio-brt',
+    name: 'Mobi-Rio BRT',
+    operator:
+      'Secretaria Municipal de Transportes (SMTR), Rio de Janeiro, for the Mobi-Rio BRT fleet',
+    region: 'Rio de Janeiro, RJ',
+    center: Object.freeze({ lat: -22.92, lon: -43.42 }),
+    loadRadiusKm: 45,
+    url: 'https://dados.mobilidade.rio/gtfs/realtime/brt/vehicle-positions',
+    license: 'CC BY 4.0',
+    licenseUrl:
+      'https://www.data.rio/documents/8bb196cc02174d25b77437bb2f6443d4',
+    attribution: 'SMTR / Prefeitura da Cidade do Rio de Janeiro (CC BY 4.0)',
+    defaultEnabled: true,
+    terms: Object.freeze({
+      quote:
+        'This work is licensed under a Creative Commons Attribution 4.0 International License',
+      note: 'Same catalog terms, [beta] label and gateway limits as the bus feed. The fleet is operated by Mobi-Rio and tracked by SONDA, whose data SMTR relays. Speeds are km/h here too (peak 62 in the same snapshot). Route ids are opaque (`20000461130`) and are shown raw.',
+    }),
+    defaultMode: 'bus',
+    speedUnit: 'kmh',
+  }),
 ]);
 
 /**
diff --git a/src/data/transitFeeds.test.mjs b/src/data/transitFeeds.test.mjs
index fd990af45..51903b7db 100644
--- a/src/data/transitFeeds.test.mjs
+++ b/src/data/transitFeeds.test.mjs
@@ -482,3 +482,46 @@ test('Burlington is live and carries its terms link, which its licence requires'
   assert.match(bur.licenseUrl, /Open%20Data%20Terms%20of%20Use\.pdf$/);
   assert.match(bur.url, /^https:\/\//, 'port 80 has no listener at all');
 });
+
+test('Rio buses and BRT cover the city from Centro to Santa Cruz, and not São Paulo', () => {
+  const ids = (lat, lon) =>
+    transitFeedsInRange(lat, lon).map((feed) => feed.id);
+  for (const [place, lat, lon] of [
+    ['Centro', -22.9068, -43.1729],
+    ['Barra da Tijuca', -23.0004, -43.3659],
+    ['Santa Cruz', -22.9194, -43.6847],
+  ]) {
+    assert.ok(
+      ids(lat, lon).includes('smtr-rio-onibus'),
+      `buses reach ${place}`,
+    );
+    assert.ok(ids(lat, lon).includes('smtr-rio-brt'), `BRT reaches ${place}`);
+  }
+  assert.deepEqual(
+    ids(-23.5505, -46.6333).filter((id) => id.startsWith('smtr-rio')),
+    [],
+    'São Paulo, 360 km away, never polls Rio',
+  );
+});
+
+test('Rio feeds are CC BY 4.0, live, and declare the km/h speeds they publish', () => {
+  for (const id of ['smtr-rio-onibus', 'smtr-rio-brt']) {
+    const feed = getTransitFeed(id);
+    assert.equal(feed.defaultEnabled, true, `${id} is live`);
+    assert.equal(feed.license, 'CC BY 4.0');
+    assert.match(feed.licenseUrl, /^https:\/\/www\.data\.rio\/documents\//);
+    assert.match(feed.attribution, /Prefeitura da Cidade do Rio de Janeiro/);
+    assert.equal(feed.speedUnit, 'kmh', `${id} publishes km/h`);
+    assert.equal(transitModeFor(feed, null), 'bus');
+  }
+  const sources = readFileSync(
+    new URL('../../DATA_SOURCES.md', import.meta.url),
+    'utf8',
+  );
+  assert.ok(
+    sources
+      .split('\n')
+      .some((line) => line.startsWith('| **SMTR Rio de Janeiro')),
+    'Rio has a DATA_SOURCES row',
+  );
+});
diff --git a/src/data/transitProxy.js b/src/data/transitProxy.js
index 458240e9d..2923c9c32 100644
--- a/src/data/transitProxy.js
+++ b/src/data/transitProxy.js
@@ -224,6 +224,25 @@ export function repairVehicleTimestamps(vehicles, headerTimestamp, fetchedAtS) {
   });
 }
 
+/**
+ * Bring a feed's speeds to the m/s the spec requires. A feed registered with
+ * `speedUnit: 'kmh'` publishes km/h in `Position.speed`, and read as m/s a
+ * 44 km/h bus would be reported at 158 km/h. Converting here, once, keeps every
+ * consumer of `speedMps` honest without each one knowing about the feed.
+ *
+ * @param {object} feed Registry entry.
+ * @param {object[]} vehicles Normalized vehicle records.
+ * @returns {object[]}
+ */
+export function normalizeFeedSpeeds(feed, vehicles) {
+  if (feed?.speedUnit !== 'kmh') return vehicles;
+  return vehicles.map((vehicle) =>
+    Number.isFinite(vehicle.speedMps)
+      ? { ...vehicle, speedMps: vehicle.speedMps / 3.6 }
+      : vehicle,
+  );
+}
+
 /**
  * Decode upstream bytes into the JSON snapshot the browser consumes.
  *
@@ -257,7 +276,7 @@ export function buildTransitSnapshot(feed, bytes, now = Date.now()) {
     truncated: decoded.truncated,
     count: decoded.vehicles.length,
     vehicles: repairVehicleTimestamps(
-      decoded.vehicles,
+      normalizeFeedSpeeds(feed, decoded.vehicles),
       decoded.timestamp,
       Math.floor(now / 1000),
     ),
diff --git a/src/data/transitProxy.test.mjs b/src/data/transitProxy.test.mjs
index dea10ab25..445e658f2 100644
--- a/src/data/transitProxy.test.mjs
+++ b/src/data/transitProxy.test.mjs
@@ -137,6 +137,7 @@ function encodeFeed({
     const position = new PbfWriter();
     position.writeFloatField(1, entity.lat);
     position.writeFloatField(2, entity.lon);
+    if (entity.speed != null) position.writeFloatField(5, entity.speed);
     vehicle.writeBytesField(2, position.finish());
     if (entity.timestamp) vehicle.writeVarintField(5, entity.timestamp);
     const descriptor = new PbfWriter();
@@ -284,6 +285,31 @@ test('the snapshot builder fills timestamps from the header it decoded', () => {
   assert.equal(snapshot.feedTimestamp, 1_700_000_000);
 });
 
+test('a feed that publishes km/h has its speeds converted to m/s, and only that feed', () => {
+  // Rio's SMTR feeds put km/h in Position.speed; read as m/s, a 36 km/h bus
+  // would be reported at 130 km/h.
+  const bytes = encodeFeed({
+    entities: [
+      { id: 'moving', lat: -22.9, lon: -43.2, speed: 36 },
+      { id: 'still', lat: -22.9, lon: -43.2, speed: 0 },
+      { id: 'silent', lat: -22.9, lon: -43.2 },
+    ],
+  });
+  const rio = buildTransitSnapshot(getTransitFeed('smtr-rio-onibus'), bytes, 1);
+  const speeds = Object.fromEntries(
+    rio.vehicles.map((vehicle) => [vehicle.id, vehicle.speedMps]),
+  );
+  assert.ok(Math.abs(speeds.moving - 10) < 1e-6, '36 km/h is 10 m/s');
+  assert.equal(speeds.still, 0);
+  assert.equal(speeds.silent, null, 'an absent speed stays absent');
+  const mbta = buildTransitSnapshot(getTransitFeed('mbta'), bytes, 1);
+  assert.equal(
+    mbta.vehicles.find((vehicle) => vehicle.id === 'moving').speedMps,
+    36,
+    'a spec-conforming feed is left alone',
+  );
+});
+
 test('conditional-request validators and gzip ride along with feed identification', () => {
   const entur = getTransitFeed('entur-norway');
   const plain = transitUpstreamHeaders(entur);

From 53d30c9e80d765b14eb2a2c35a957168cad2bf4b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Itallo=20Brand=C3=A3o?=
 <45429643+IMBrandao@users.noreply.github.com>
Date: Thu, 29 Oct 2026 16:30:47 -0300
Subject: [PATCH 06/71] docs(changelog): add fragment for #1481

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 changelog.d/1481-rio-transit.md | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 changelog.d/1481-rio-transit.md

diff --git a/changelog.d/1481-rio-transit.md b/changelog.d/1481-rio-transit.md
new file mode 100644
index 000000000..62b4ede04
--- /dev/null
+++ b/changelog.d/1481-rio-transit.md
@@ -0,0 +1,4 @@
+- Add Rio de Janeiro to the Transit layer: municipal buses and the Mobi-Rio BRT
+  from SMTR's keyless GTFS-Realtime feeds (CC BY 4.0), the layer's first Latin
+  American region. A feed that publishes speed in km/h declares
+  `speedUnit: 'kmh'` and the proxy converts it to m/s (IMBrandao, #1481).

From 04d626a4b190149ffcb017290c5d9aa17d32748d Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Tue, 3 Nov 2026 15:02:42 +0400
Subject: [PATCH 07/71] fix(datacenters): preserve missing geometry and compare
 ring topology

---
 scripts/build-datacenters-norway.py        | 64 ++++++++++++---
 src/data/datacentersNorwayRefresh.test.mjs | 93 ++++++++++++++++++++++
 src/data/local_data/datacenters/README.md  |  4 +-
 3 files changed, 148 insertions(+), 13 deletions(-)
 create mode 100644 src/data/datacentersNorwayRefresh.test.mjs

diff --git a/scripts/build-datacenters-norway.py b/scripts/build-datacenters-norway.py
index 687395f7b..03286b864 100644
--- a/scripts/build-datacenters-norway.py
+++ b/scripts/build-datacenters-norway.py
@@ -4,7 +4,8 @@
 Downloads a dated Geofabrik Norway extract, verifies its MD5, filters
 telecom=data_center / building=data_center with osmium, and merges the result
 into datacenters.geojsonl: features inside the Geofabrik Norway boundary are
-added, updated or removed; every other line is kept byte-for-byte.
+added, updated or removed once no longer tagged; every other line is kept
+byte-for-byte.
 
 Geofabrik keeps only its newest dated extract, so --extract defaults to the
 current one and a recorded extract can be re-verified only while it is listed.
@@ -16,6 +17,7 @@ import math
 from pathlib import Path
 import shutil
 import subprocess
+import sys
 import urllib.request
 
 ROOT = Path(__file__).resolve().parent.parent
@@ -95,10 +97,15 @@ def osm_key(feature):
 
 
 def export(osmium, pbf, cache, extract):
+    """Exported features by key, and the keys of every tagged object in the extract."""
     filtered = cache / (extract + '-datacenters.osm.pbf')
+    listed = cache / (extract + '-datacenters.opl')
     exported = cache / (extract + '-datacenters.geojsonseq')
     subprocess.run([osmium, 'tags-filter', '-O', '-o', str(filtered), str(pbf),
                     'nwr/telecom=data_center', 'nwr/building=data_center'], check=True)
+    subprocess.run([osmium, 'tags-filter', '-O', '-R', '-f', 'opl', '-o', str(listed), str(filtered),
+                    'nwr/telecom=data_center', 'nwr/building=data_center'], check=True)
+    tagged = {line.split(' ', 1)[0] for line in listed.read_text(encoding='utf-8').splitlines() if line}
     subprocess.run([osmium, 'export', '-O', '-f', 'geojsonseq', '--add-unique-id=type_id',
                     '-o', str(exported), str(filtered)], check=True)
     fresh = {}
@@ -122,22 +129,48 @@ def export(osmium, pbf, cache, extract):
         elif key in fresh or geometry['type'] == 'LineString':
             continue  # closed ways are taken from their area export
         fresh[key] = {'geometry': geometry, 'tags': tags}
-    return fresh
+    return fresh, tagged
 
 
 def same_geometry(old, new):
-    """Same type and vertex set within tolerance; ring start and winding may differ."""
+    """Same type and rings within tolerance; ring start, winding and part or hole order may differ."""
     if old['type'] != new['type']:
         return False
-    a, b = points(old['coordinates']), points(new['coordinates'])
-    if len(a) != len(b):
-        return False
 
     def meters(p, q):
         dx = (p[0] - q[0]) * 111320 * math.cos(math.radians(p[1]))
         return math.hypot(dx, (p[1] - q[1]) * 110540)
-    return all(min(meters(p, q) for q in b) <= SAME_GEOMETRY_METERS for p in a) and \
-        all(min(meters(q, p) for p in a) <= SAME_GEOMETRY_METERS for q in b)
+
+    def same_line(a, b):
+        return len(a) == len(b) and all(meters(p, q) <= SAME_GEOMETRY_METERS for p, q in zip(a, b))
+
+    def same_ring(a, b):
+        a, b = a[:-1], b[:-1]  # closed rings repeat their first vertex
+        return len(a) == len(b) and \
+            any(same_line(a[i:] + a[:i], c) for c in (b, b[::-1]) for i in range(len(a)))
+
+    def same_parts(a, b, same):
+        rest = list(b)
+        for part in a:
+            match = next((i for i, other in enumerate(rest) if same(part, other)), None)
+            if match is None:
+                return False
+            rest.pop(match)
+        return not rest
+
+    def same_polygon(a, b):
+        return same_ring(a[0], b[0]) and same_parts(a[1:], b[1:], same_ring)
+
+    a, b = old['coordinates'], new['coordinates']
+    if old['type'] == 'Point':
+        return same_line([a], [b])
+    if old['type'] == 'LineString':
+        return same_line(a, b)
+    if old['type'] == 'Polygon':
+        return same_polygon(a, b)
+    if old['type'] == 'MultiPolygon':
+        return same_parts(a, b, same_polygon)
+    return a == b
 
 
 def feature_line(key, sequence, fresh):
@@ -148,9 +181,9 @@ def feature_line(key, sequence, fresh):
     return json.dumps(feature, separators=(',', ':'), ensure_ascii=False)
 
 
-def merge(lines, fresh, rings):
+def merge(lines, fresh, rings, tagged):
     out, seen, sequence = [], set(), 0
-    report = {'kept': 0, 'updated': [], 'removed': [], 'added': []}
+    report = {'kept': 0, 'updated': [], 'removed': [], 'added': [], 'unexported': []}
     for line in lines:
         feature = json.loads(line)
         sequence = max(sequence, feature['properties']['id'])
@@ -165,6 +198,10 @@ def merge(lines, fresh, rings):
                 out.append(feature_line(key, feature['properties']['id'], fresh[key]))
                 report['updated'].append(key)
             continue
+        if key in tagged:  # still tagged, but osmium built no usable geometry: keep the old line
+            report['unexported'].append(key)
+            out.append(line)
+            continue
         lon, lat = points(feature['geometry']['coordinates'])[0][:2]
         if inside(rings, lon, lat):
             report['removed'].append(key)
@@ -196,9 +233,12 @@ def main():
     if actual != expected:
         raise RuntimeError('MD5 mismatch for %s: %s != %s' % (pbf.name, actual, expected))
     rings = read_poly(fetch(GEOFABRIK + 'norway.poly', args.cache / 'norway.poly'))
-    fresh = export(args.osmium, pbf, args.cache, extract)
+    fresh, tagged = export(args.osmium, pbf, args.cache, extract)
     current = [line for line in DATASET.read_text(encoding='utf-8').splitlines() if line.strip()]
-    merged, report = merge(current, fresh, rings)
+    merged, report = merge(current, fresh, rings, tagged)
+    if report['unexported']:
+        print('warning: kept the old line of tagged features osmium did not export: %s'
+              % ', '.join(report['unexported']), file=sys.stderr)
     payload = '\n'.join(merged) + '\n'
     if args.verify:
         if payload != DATASET.read_text(encoding='utf-8'):
diff --git a/src/data/datacentersNorwayRefresh.test.mjs b/src/data/datacentersNorwayRefresh.test.mjs
new file mode 100644
index 000000000..2b7b7d5bf
--- /dev/null
+++ b/src/data/datacentersNorwayRefresh.test.mjs
@@ -0,0 +1,93 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT = fileURLToPath(
+  new URL('../../scripts/build-datacenters-norway.py', import.meta.url),
+);
+
+function python(t, source) {
+  const result = spawnSync('python3', ['-c', source, SCRIPT], {
+    encoding: 'utf8',
+  });
+  if (result.error?.code === 'ENOENT') return t.skip('python3 is not installed');
+  assert.equal(result.status, 0, result.stderr);
+}
+
+test('Norway refresh compares rings, not vertex sets', (t) => {
+  python(
+    t,
+    String.raw`
+import runpy, sys
+same = runpy.run_path(sys.argv[1])['same_geometry']
+poly = lambda *rings: {'type': 'Polygon', 'coordinates': list(rings)}
+multi = lambda *polys: {'type': 'MultiPolygon', 'coordinates': [p['coordinates'] for p in polys]}
+a, b, c, d, e = [0, 0], [4, 0], [4, 4], [0, 4], [2, 1]
+assert not same(poly([a, b, c, d, e, a]), poly([a, b, e, c, d, a])), 'reordered edges'
+assert same(poly([a, b, c, d, e, a]), poly([c, b, a, e, d, c])), 'ring start and winding'
+assert same(poly([a, b, c, d, a]), poly([[0, 1e-7], b, c, d, [0, 1e-7]])), 'tolerance'
+outer = [[0, 0], [9, 0], [9, 9], [0, 9], [0, 0]]
+one, two = [[1, 1], [2, 1], [2, 2], [1, 1]], [[5, 5], [6, 5], [6, 6], [5, 5]]
+assert same(poly(outer, one, two), poly(outer, two, one)), 'hole order'
+assert not same(poly(outer, one), poly(one, outer)), 'outer and inner roles swapped'
+assert same(multi(poly(one), poly(two)), multi(poly(two), poly(one))), 'part order'
+p, q, r, s, u, v = [0, 0], [1, 0], [0, 1], [5, 5], [6, 5], [5, 6]
+assert not same(multi(poly([p, q, r, p]), poly([s, u, v, s])),
+                multi(poly([p, q, s, p]), poly([r, u, v, r]))), 'vertices moved between parts'
+`,
+  );
+});
+
+test('Norway refresh keeps a still-tagged feature osmium did not export', (t) => {
+  python(
+    t,
+    String.raw`
+import json, runpy, sys
+merge = runpy.run_path(sys.argv[1])['merge']
+square = [[[10, 60], [10.01, 60], [10.01, 60.01], [10, 60.01], [10, 60]]]
+def line(osm_id, sequence):
+    return json.dumps({'id': osm_id, 'type': 'Feature', 'geometry': {'type': 'Polygon', 'coordinates': square},
+                       'properties': {'id': sequence, 'tags': {'building': 'data_center'},
+                                      'type': 'data_center', 'osm_id': osm_id}})
+norway = [([(0, 0), (20, 0), (20, 80), (0, 80)], False)]
+lines = [line(7, 1), line(8, 2)]
+out, report = merge(lines, {}, norway, {'w7'})
+assert out == [lines[0]], out
+assert report['unexported'] == ['w7'] and report['removed'] == ['w8'], report
+`,
+  );
+});
+
+test('Norway refresh lists tagged objects apart from the exported geometry', (t) => {
+  python(
+    t,
+    String.raw`
+import json, runpy, subprocess, sys, tempfile
+from pathlib import Path
+export = runpy.run_path(sys.argv[1])['export']
+tags = {'building': 'data_center'}
+ring = [[10, 60], [10.01, 60], [10.01, 60.01], [10, 60]]
+features = [
+    {'id': 'n1', 'properties': {'telecom': 'data_center'}, 'geometry': {'type': 'Point', 'coordinates': [10, 60]}},
+    {'id': 'w5', 'properties': tags, 'geometry': {'type': 'LineString', 'coordinates': ring}},
+    {'id': 'a10', 'properties': tags, 'geometry': {'type': 'MultiPolygon', 'coordinates': [[ring]]}},
+    {'id': 'w7', 'properties': tags, 'geometry': {'type': 'LineString', 'coordinates': ring[:3]}},
+]
+outputs = {
+    '.opl': 'n1 v1 Ttelecom=data_center x10 y60\nw5 v1 Tbuilding=data_center Nn2,n3,n4,n2\n'
+            'w7 v1 Tbuilding=data_center Nn2,n3,n4\nr9 v1 Ttelecom=data_center Mw8@outer\n',
+    '.geojsonseq': ''.join(chr(30) + json.dumps({'type': 'Feature', **f}) + '\n' for f in features),
+}
+def run(args, check=False):
+    target = Path(args[args.index('-o') + 1])
+    target.write_text(outputs.get(target.suffix, ''), encoding='utf-8')
+subprocess.run = run
+with tempfile.TemporaryDirectory() as cache:
+    fresh, tagged = export('osmium', Path(cache) / 'norway-test.osm.pbf', Path(cache), 'norway-test')
+assert sorted(fresh) == ['n1', 'w5'], fresh
+assert fresh['w5']['geometry'] == {'type': 'Polygon', 'coordinates': [ring]}, fresh['w5']
+assert tagged == {'n1', 'w5', 'w7', 'r9'}, tagged
+`,
+  );
+});
diff --git a/src/data/local_data/datacenters/README.md b/src/data/local_data/datacenters/README.md
index 8b803dcc7..5a80df267 100644
--- a/src/data/local_data/datacenters/README.md
+++ b/src/data/local_data/datacenters/README.md
@@ -27,7 +27,9 @@ reflects OSM as of the extract below, everything else the original snapshot.
   2026-10-05T20:21:35Z, MD5 `1d2cfdeb98980fce11b8891d0f9146c0`
 - Filter: `osmium tags-filter nwr/telecom=data_center nwr/building=data_center`
 - Contact tags are dropped as above; unchanged features keep their original
-  line, so geometry is only rewritten when tags or vertices actually changed.
+  line, so geometry is only rewritten when tags or rings actually changed.
+  A feature is removed only once it is no longer tagged; one still tagged but
+  without an exportable geometry keeps its line and is reported as unexported.
 - Refresh: `python3 scripts/build-datacenters-norway.py --cache <dir>` uses
   Geofabrik's current Norway extract and prints the dated name it used; record
   that name, its OSM timestamp and MD5 here. Requires `osmium-tool`.

From c68f167acb5b20c692aa0632b5de48c446b05e40 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Tue, 3 Nov 2026 15:07:00 +0400
Subject: [PATCH 08/71] fix(transit): count distinct coverage regions

---
 src/layers/transit/queries.js       |  7 ++++++-
 src/layers/transit/queries.test.mjs | 28 ++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 src/layers/transit/queries.test.mjs

diff --git a/src/layers/transit/queries.js b/src/layers/transit/queries.js
index b86613160..dc3ea4d79 100644
--- a/src/layers/transit/queries.js
+++ b/src/layers/transit/queries.js
@@ -12,6 +12,11 @@ import {
 } from '../../data/transitFeeds.js';
 import { transitModeTier } from '../../data/transitPresetStyle.js';
 
+/** Regions, not feeds: one region can carry several feeds (Rio has two). */
+const TRANSIT_REGION_COUNT = new Set(
+  TRANSIT_ENABLED_FEEDS.map((feed) => feed.region),
+).size;
+
 /**
  * The registry entry behind a vehicle. Live feeds answer first so a feed the
  * session disabled stops supplying vocabulary; the registry is the fallback,
@@ -249,7 +254,7 @@ export function createQueries({ state, parts }) {
           // English data (the analyst's empty note to the model); the voice
           // card shows it through NOTE_PATTERNS (voice/resultDisplay.js).
           coverage: state._altitudeGateOpen
-            ? `No feed here yet · ${TRANSIT_ENABLED_FEEDS.length} regions available`
+            ? `No feed here yet · ${TRANSIT_REGION_COUNT} regions available`
             : `Fly below ${Math.round(ACTIVATION_ALTITUDE_M / 1000).toLocaleString('en-US')} km to a covered region`,
         };
       }
diff --git a/src/layers/transit/queries.test.mjs b/src/layers/transit/queries.test.mjs
new file mode 100644
index 000000000..a7ac1224c
--- /dev/null
+++ b/src/layers/transit/queries.test.mjs
@@ -0,0 +1,28 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createQueries } from './queries.js';
+import { TRANSIT_ENABLED_FEEDS } from '../../data/transitFeeds.js';
+
+test('the empty-coverage note counts regions, not feeds', () => {
+  const rio = TRANSIT_ENABLED_FEEDS.filter(
+    (feed) => feed.region === 'Rio de Janeiro, RJ',
+  );
+  assert.equal(rio.length, 2, 'Rio is one region with two feeds');
+  const regions = new Set(TRANSIT_ENABLED_FEEDS.map((feed) => feed.region));
+  assert.ok(regions.size < TRANSIT_ENABLED_FEEDS.length);
+
+  const stats = createQueries({
+    state: {
+      _activeFeeds: new Map(),
+      _vehicles: new Map(),
+      _enabled: true,
+      _altitudeGateOpen: true,
+    },
+    parts: {},
+  }).methods.getStats();
+  assert.equal(stats.status, 'zoom-in');
+  assert.equal(
+    stats.coverage,
+    `No feed here yet · ${regions.size} regions available`,
+  );
+});

From 69152868e4eff63d17b8cbeef8bdffbd68e71c05 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@Mac.mshome.net>
Date: Tue, 3 Nov 2026 16:42:18 +0530
Subject: [PATCH 09/71] Fix voice camera tilt from a top-down view

A voice fly-to frames a city top-down, at pitch -90. The tilt clamp
rejected any step that left the pitch below -89, so the first frame of
"tilt up" stopped the motion and "tilt down" was refused: from the view
voice lands on, no tilt ever moved the camera. A bare "tilt the camera"
also failed because tilt required a direction.

- Clamp tilt only in the direction of travel, so -90 can tilt up.
- Swing the camera about the ground under the crosshair, so the place
  stays centred and the heading is kept. A tracked view still tilts in
  place, and a pivot tilt yields when tracking takes the camera.
- Add an optional move_camera pitchDeg for "tilt 45 degrees"; a tilt
  with neither angle nor direction settles at -45 (oblique view).
- Re-derive the voice tool schema pins for the new argument and wording,
  and keep the Realtime prompt under its 52,000-character budget.
---
 docs/CURRENT-STATE.md                       |   2 +-
 scripts/format-scope.json                   |   1 +
 server/providers/openai/toolDescriptions.js |   7 +-
 src/cameraTilt.test.mjs                     | 224 ++++++++++++++++++++
 src/cameraVerbs.js                          | 163 ++++++++++++--
 src/firstRunExperience.test.mjs             |   7 +
 src/radioMarkup.test.mjs                    |   7 +-
 src/voice/actionSchemas.js                  |   5 +
 src/voice/actionSchemas.test.mjs            |  14 +-
 9 files changed, 403 insertions(+), 27 deletions(-)
 create mode 100644 src/cameraTilt.test.mjs

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index be0718fd1..3c17ed79f 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5364,7 +5364,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair (the tracked view excepted, which tilts in place), so the place stays centred and the heading is kept; pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/scripts/format-scope.json b/scripts/format-scope.json
index 447dbf199..79117e775 100644
--- a/scripts/format-scope.json
+++ b/scripts/format-scope.json
@@ -1108,6 +1108,7 @@
   "scripts/qa-status-badges.mjs",
   "src/dockerTrustedPeers.test.mjs",
   "src/cameraGlobeRotation.test.mjs",
+  "src/cameraTilt.test.mjs",
   "src/voice/globeResetConfirmation.test.mjs",
   "src/hudDms.test.mjs",
   "src/hudSummaryGate.test.mjs",
diff --git a/server/providers/openai/toolDescriptions.js b/server/providers/openai/toolDescriptions.js
index 23d5da9de..873a52c8a 100644
--- a/server/providers/openai/toolDescriptions.js
+++ b/server/providers/openai/toolDescriptions.js
@@ -523,7 +523,7 @@ export const ACTION_DESCRIPTIONS = {
       properties: {
         direction: {
           description:
-            'Required for pan/tilt/rotate; orbit/rotate_globe default right.',
+            'Required for pan/rotate and a tilt nudge; orbit/rotate_globe default right.',
           $position: 2,
         },
         mode: {
@@ -531,6 +531,11 @@ export const ACTION_DESCRIPTIONS = {
             'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.',
           $position: 2,
         },
+        pitchDeg: {
+          description:
+            'Tilt to this angle below the horizon (-45 oblique, -89 top-down). Bare tilt: -45.',
+          $position: 2,
+        },
       },
     },
   },
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
new file mode 100644
index 000000000..babe95807
--- /dev/null
+++ b/src/cameraTilt.test.mjs
@@ -0,0 +1,224 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import {
+  getActiveCameraMotion,
+  initCameraVerbs,
+  interruptCameraMotion,
+  moveCamera,
+} from './cameraVerbs.js';
+
+const radians = Cesium.Math.toRadians;
+const degrees = Cesium.Math.toDegrees;
+
+/** Real Cesium camera over London with no renderer: the voice fly-to frame. */
+function harness(
+  t,
+  { height = 4000, heading = 0, pitch = -90, pivot = true } = {},
+) {
+  const realPerformance = globalThis.performance;
+  let nowMs = 0;
+  globalThis.performance = { now: () => nowMs };
+  const canvas = Object.assign(new EventTarget(), {
+    clientWidth: 1280,
+    clientHeight: 800,
+    width: 1280,
+    height: 800,
+  });
+  const ellipsoid = Cesium.Ellipsoid.WGS84;
+  const scene = {
+    canvas,
+    drawingBufferWidth: 1280,
+    drawingBufferHeight: 800,
+    frameState: { mode: Cesium.SceneMode.SCENE3D },
+    mapProjection: new Cesium.GeographicProjection(ellipsoid),
+    globe: { ellipsoid },
+    mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
+    mode: Cesium.SceneMode.SCENE3D,
+    pixelRatio: 1,
+    tweens: [],
+    requestRender() {},
+  };
+  const camera = new Cesium.Camera(scene);
+  scene.camera = camera;
+  camera.setView({
+    destination: Cesium.Cartesian3.fromDegrees(-0.1276, 51.5072, height),
+    orientation: { heading: radians(heading), pitch: radians(pitch), roll: 0 },
+  });
+  const viewer = {
+    camera,
+    scene,
+    trackedEntity: undefined,
+    trackedEntityChanged: new Cesium.Event(),
+    clock: { onTick: new Cesium.Event() },
+  };
+  // The app's view target: the ground point under the screen centre.
+  const viewTarget = () => {
+    const ray = new Cesium.Ray(camera.positionWC, camera.directionWC);
+    const hit = Cesium.IntersectionTests.rayEllipsoid(ray, ellipsoid);
+    return hit ? Cesium.Ray.getPoint(ray, hit.start) : undefined;
+  };
+  const target = viewTarget();
+  initCameraVerbs(viewer, pivot ? viewTarget : () => undefined);
+  t.after(() => {
+    interruptCameraMotion('test-cleanup');
+    globalThis.performance = realPerformance;
+  });
+  const tick = (seconds = 1 / 30) => {
+    nowMs += seconds * 1000;
+    viewer.clock.onTick.raiseEvent(viewer.clock);
+  };
+  const finish = () => {
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
+    assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  };
+  return { viewer, camera, target, tick, finish, viewTarget };
+}
+
+const pitchDeg = (camera) => degrees(camera.pitch);
+const headingDeg = (camera) =>
+  degrees(Cesium.Math.negativePiToPi(camera.heading));
+
+/** Metres between the original centre and the ground now under the crosshair. */
+function centreDrift(h) {
+  return Cesium.Cartesian3.distance(h.viewTarget(), h.target);
+}
+
+test('tilt up leaves a top-down view and keeps the place centred', (t) => {
+  const h = harness(t);
+  const result = moveCamera({ motion: 'tilt', direction: 'up' });
+  assert.equal(result.ok, true);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -75) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+  assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
+  assert.ok(Cesium.Matrix4.equals(h.camera.transform, Cesium.Matrix4.IDENTITY));
+});
+
+test('continuous tilt up from top-down keeps moving', (t) => {
+  const h = harness(t);
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' }).ok,
+    true,
+  );
+  for (let i = 0; i < 30; i += 1) h.tick();
+  assert.equal(getActiveCameraMotion()?.kind, 'tilt');
+  assert.ok(pitchDeg(h.camera) > -82, `pitch ${pitchDeg(h.camera)}`);
+});
+
+test('a requested angle tilts to that pitch', (t) => {
+  const h = harness(t);
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -45 });
+  assert.equal(result.ok, true);
+  assert.equal(result.direction, 'up');
+  assert.equal(result.pitchDeg, -45);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -45) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+  assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
+});
+
+test('a bare tilt settles on the default oblique angle', (t) => {
+  const h = harness(t);
+  const result = moveCamera({ motion: 'tilt' });
+  assert.equal(result.ok, true);
+  assert.equal(result.pitchDeg, -45);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
+});
+
+test('a requested angle can tilt back down toward top-down', (t) => {
+  const h = harness(t, { pitch: -30 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -80 });
+  assert.equal(result.direction, 'down');
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -80) < 0.5);
+});
+
+test('requested angles clamp to the tilt limits', (t) => {
+  const h = harness(t);
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -2 }).pitchDeg, -5);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('a positive angle is read as the same angle below the horizon', (t) => {
+  const h = harness(t);
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: 45 }).pitchDeg, -45);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
+});
+
+for (const pitch of ['', null, false, ' ', 'steep'])
+  test(`a blank or non-numeric angle ${JSON.stringify(pitch)} is ignored`, (t) => {
+    harness(t);
+    const result = moveCamera({ motion: 'tilt', pitchDeg: pitch });
+    // No angle and no direction: the default oblique view, never the horizon.
+    assert.equal(result.pitchDeg, -45);
+  });
+
+test('a requested angle the camera already holds is a no-op', (t) => {
+  harness(t, { pitch: -45 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -45 });
+  assert.equal(result.ok, true);
+  assert.equal(result.unchanged, true);
+  assert.equal(getActiveCameraMotion(), null);
+});
+
+test('tilt down from top-down still refuses honestly', (t) => {
+  harness(t);
+  const result = moveCamera({ motion: 'tilt', direction: 'down' });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /straight down/);
+});
+
+test('a tilt up nudge stops at the horizon limit', (t) => {
+  const h = harness(t, { pitch: -12 });
+  assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('without a ground pivot a tilt still leaves top-down in place', (t) => {
+  const h = harness(t, { pivot: false });
+  const before = Cesium.Cartesian3.clone(h.camera.positionWC);
+  assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -75) < 0.5);
+  assert.ok(Cesium.Cartesian3.distance(h.camera.positionWC, before) < 1e-6);
+});
+
+for (const heading of [0, 30, -120])
+  test(`tilt from top-down keeps the ${heading}° heading`, (t) => {
+    const h = harness(t, { heading, height: 67000 });
+    // Top-down float noise must not pick a new heading for the pivot.
+    assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true);
+    h.finish();
+    assert.ok(
+      Math.abs(headingDeg(h.camera) - heading) < 1,
+      `heading ${headingDeg(h.camera)}`,
+    );
+    assert.ok(centreDrift(h) < 50, `centre drifted ${centreDrift(h)} m`);
+  });
+
+test('an oblique tilt keeps its heading toward the pivot', (t) => {
+  const h = harness(t, { heading: 75, pitch: -60 });
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -30 }).ok, true);
+  h.finish();
+  assert.ok(Math.abs(headingDeg(h.camera) - 75) < 0.5);
+  assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
+});
+
+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);
+  assert.equal(getActiveCameraMotion(), null);
+});
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index e037472cb..3898acaa7 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -48,6 +48,10 @@ const ONCE = {
 };
 const PITCH_MIN = Cesium.Math.toRadians(-89);
 const PITCH_MAX = Cesium.Math.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. */
+const TILT_TO_DEG_S = 30;
 
 /* ── Route dolly: cinematic tuning ──────────────────────────────────────────
  * Every knob an owner may want to retune lives in this block. The shaping is
@@ -1052,7 +1056,9 @@ export function interruptCameraMotion(reason = 'interrupt') {
   if (
     wasActive &&
     !tracking &&
-    (_active.kind === 'orbit' || _active.kind === 'route')
+    (_active.kind === 'orbit' ||
+      _active.kind === 'route' ||
+      (_active.kind === 'tilt' && _active.hpr))
   )
     clearLookAt();
   // Instant, not eased: the user grabbed the camera, or the flight is over.
@@ -1104,7 +1110,7 @@ function onTick() {
   let scale = 1;
   if (m.mode === 'once') {
     m.elapsed = (m.elapsed || 0) + dt;
-    const t = Math.min(1, m.elapsed / ONCE.durationS);
+    const t = Math.min(1, m.elapsed / (m.durationS || ONCE.durationS));
     scale = 1 - (1 - t) * (1 - t); // ease-out progress share
     if (t >= 1) {
       interruptCameraMotion('once-complete');
@@ -1173,18 +1179,13 @@ function onTick() {
       else if (m.direction === 'right') cam.moveRight(step);
       else if (m.direction === 'up') cam.moveUp(step);
       else cam.moveDown(step);
-    } else if (
-      m.kind === 'tilt' ||
-      m.kind === 'rotate' ||
-      m.kind === 'rotate_globe'
-    ) {
+    } else if (m.kind === 'tilt') {
+      tickTilt(cam, 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(
-              m.kind === 'tilt' ? ONCE.tiltDeg : ONCE.rotateDeg,
-            ) *
-            (scale - (m.lastScale || 0))
+          ? Cesium.Math.toRadians(ONCE.rotateDeg) * (scale - (m.lastScale || 0))
           : Cesium.Math.toRadians(degS) * dt;
       m.lastScale = scale;
       if (m.kind === 'rotate_globe') {
@@ -1218,16 +1219,6 @@ function onTick() {
           return;
         }
         cam.rotate(m.rotationAxis, angle);
-      } else if (m.kind === 'tilt') {
-        const up = m.direction === 'up';
-        // Clamp pitch to [-89°, -5°]: never through the ground, never at the sky.
-        const next = cam.pitch + (up ? stepRad : -stepRad);
-        if (next > PITCH_MAX || next < PITCH_MIN) {
-          interruptCameraMotion('tilt-clamp');
-          return;
-        }
-        if (up) cam.lookUp(stepRad);
-        else cam.lookDown(stepRad);
       } else if (m.direction === 'left') cam.lookLeft(stepRad);
       else cam.lookRight(stepRad);
     } else if (m.kind === 'route') {
@@ -1252,6 +1243,67 @@ function onTick() {
   }
 }
 
+/**
+ * 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
+ * down in place. Pitch is clamped to [-89°, -5°] only in the direction of
+ * travel: a top-down view sits at -90°, below the limit, and must still be
+ * able to tilt up out of it.
+ */
+function tickTilt(cam, m, scale, dt) {
+  let step;
+  if (m.mode === 'once') {
+    step = m.tiltRad * (scale - (m.lastScale || 0));
+    m.lastScale = scale;
+  } else {
+    step =
+      Cesium.Math.toRadians(TILT_DEG_S[m.speed]) *
+      dt *
+      (m.direction === 'up' ? 1 : -1);
+  }
+  const from = m.hpr ? m.hpr.pitch : cam.pitch;
+  const next = from + step;
+  const limited =
+    step > 0
+      ? Math.min(next, Math.max(from, PITCH_MAX))
+      : Math.max(next, Math.min(from, PITCH_MIN));
+  if (m.hpr) {
+    m.hpr.pitch = limited;
+    cam.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();
+  } else {
+    cam.lookUp(limited - from);
+  }
+  if (limited !== next) interruptCameraMotion('tilt-clamp');
+}
+
+/** 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);
+  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(
+    heading,
+    -Math.asin(Math.min(1, local.z / range)),
+    range,
+  );
+}
+
 /** Rigid origin-centred rotation stays outside the actual ellipsoid's bounding sphere. */
 function globeRotationHasClearance(position) {
   const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84;
@@ -1421,6 +1473,9 @@ export function initCameraVerbs(
   _trackingRemover = viewer.trackedEntityChanged?.addEventListener((entity) => {
     if (entity && _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)
+      interruptCameraMotion('tilt-camera-owner-changed');
   });
   for (const rm of _inputRemovers) rm();
   _inputRemovers = [];
@@ -1472,9 +1527,32 @@ export function moveCamera(args = {}, runNavigation = null) {
       error: `Unknown motion "${args.motion}" — use orbit, pan, tilt, rotate, rotate_globe, or stop.`,
     };
   }
+  // Tilt to an angle: the one asked for, or a default oblique view when a
+  // bare "tilt the camera" names neither angle nor direction.
+  let tiltToPitch = null;
+  if (motion === 'tilt') {
+    // Only a real number or numeric text: Number('') and Number(null) are 0,
+    // which would swing the camera to the horizon.
+    const raw = args.pitchDeg;
+    const requested =
+      typeof raw === 'number' || (typeof raw === 'string' && raw.trim() !== '')
+        ? Number(raw)
+        : NaN;
+    // 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))
+      tiltToPitch = Cesium.Math.clamp(
+        Cesium.Math.toRadians(-Math.abs(requested)),
+        PITCH_MIN,
+        PITCH_MAX,
+      );
+    else if (direction === null)
+      tiltToPitch = Cesium.Math.toRadians(TILT_DEFAULT_PITCH_DEG);
+  }
   if (
     motion !== 'orbit' &&
     motion !== 'rotate_globe' &&
+    tiltToPitch === null &&
     !['left', 'right', 'up', 'down'].includes(direction)
   ) {
     return {
@@ -1501,7 +1579,19 @@ export function moveCamera(args = {}, runNavigation = null) {
       error: 'rotate_globe needs left or right.',
     };
   }
-  if (motion === 'tilt') {
+  if (motion === 'tilt' && tiltToPitch !== null) {
+    if (
+      Math.abs(tiltToPitch - _viewer.camera.pitch) < Cesium.Math.toRadians(0.5)
+    ) {
+      return {
+        ok: true,
+        action: 'move_camera',
+        motion,
+        pitchDeg: Math.round(Cesium.Math.toDegrees(tiltToPitch)),
+        unchanged: true,
+      };
+    }
+  } 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;
@@ -1615,6 +1705,30 @@ export function moveCamera(args = {}, runNavigation = null) {
       speed,
       mode,
     };
+    if (motion === 'tilt') {
+      const cam = _viewer.camera;
+      // Swing about the ground under the crosshair so the place stays
+      // centred. The follow camera owns a tracked view's frame.
+      const target = _viewer.trackedEntity ? null : _getTarget?.(_viewer);
+      const pivot = target ? tiltPivot(cam, target) : null;
+      if (pivot) {
+        state.target = target;
+        state.hpr = pivot;
+      }
+      const from = pivot ? pivot.pitch : cam.pitch;
+      if (tiltToPitch !== null) {
+        state.mode = 'once';
+        state.direction = tiltToPitch > from ? 'up' : 'down';
+        state.tiltRad = tiltToPitch - from;
+        state.durationS = Math.max(
+          ONCE.durationS,
+          Math.abs(Cesium.Math.toDegrees(state.tiltRad)) / TILT_TO_DEG_S,
+        );
+      } else {
+        state.tiltRad =
+          Cesium.Math.toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1);
+      }
+    }
     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.
@@ -1699,7 +1813,10 @@ export function moveCamera(args = {}, runNavigation = null) {
       motion,
       direction: state.direction,
       speed,
-      mode,
+      mode: state.mode,
+      ...(tiltToPitch !== null && {
+        pitchDeg: Math.round(Cesium.Math.toDegrees(tiltToPitch)),
+      }),
     };
   };
   const preserveCameraFlight =
diff --git a/src/firstRunExperience.test.mjs b/src/firstRunExperience.test.mjs
index 87229e5c5..9ca5262a4 100644
--- a/src/firstRunExperience.test.mjs
+++ b/src/firstRunExperience.test.mjs
@@ -1014,6 +1014,13 @@ test('the voice TOOL SCHEMA matches the pinned contract — the mission mapping
     'noir',
   ]);
   visualStyle.enum = [...visualStyle.enum, 'snow'];
+  // Tilt to an angle adds pitchDeg and rewords direction; restore
+  // the legacy camera fields to keep the pin.
+  const camera = legacyTools.find((tool) => tool.name === 'move_camera')
+    .parameters.properties;
+  delete camera.pitchDeg;
+  camera.direction.description =
+    'Required for pan/tilt/rotate; orbit/rotate_globe default right.';
   const block = JSON.stringify(legacyTools);
   // Re-derived for the voice layer manifest (generated layer enums, alias and
   // field hints), point-and-ask's pointer/referent arguments and the prompt
diff --git a/src/radioMarkup.test.mjs b/src/radioMarkup.test.mjs
index 74a44e77d..cfc2da5a7 100644
--- a/src/radioMarkup.test.mjs
+++ b/src/radioMarkup.test.mjs
@@ -225,10 +225,15 @@ test('no unchanged Realtime tool definition drifts silently', () => {
     camera.description,
     'Direct the camera like a drone operator: orbit the current view target, pan, tilt, or rotate — one bounded nudge (mode=once) or continuous motion until stopped (mode=continuous). Continuous motion also stops on any manual camera input or when a navigation tool runs. Say the RESULTING state when confirming ("Orbiting slowly"). Globe rotation (rotate_globe) spins Earth right continuously by default; explicit direction, mode and speed take precedence. It checks fit and may refuse.',
   );
+  // Tilt to an angle adds pitchDeg and says a tilt nudge needs a
+  // direction; check them, then restore the legacy fields for the pin.
   assert.equal(
     camera.parameters.properties.direction.description,
-    'Required for pan/tilt/rotate; orbit/rotate_globe default right.',
+    'Required for pan/rotate and a tilt nudge; orbit/rotate_globe default right.',
   );
+  assert.equal(camera.parameters.properties.pitchDeg.type, 'number');
+  assert.match(camera.parameters.properties.pitchDeg.description, /-45 oblique/);
+  delete camera.parameters.properties.pitchDeg;
   assert.equal(camera.parameters.properties.mode.description, 'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.');
   camera.parameters.properties.mode.description = 'once = bounded eased nudge (default); continuous = until stop/manual input.';
   camera.parameters.properties.motion.enum =
diff --git a/src/voice/actionSchemas.js b/src/voice/actionSchemas.js
index 9ec47028c..2b31c26d6 100644
--- a/src/voice/actionSchemas.js
+++ b/src/voice/actionSchemas.js
@@ -749,6 +749,11 @@ const schemas = [
           type: 'string',
           enum: ['once', 'continuous'],
         },
+        pitchDeg: {
+          type: 'number',
+          minimum: -90,
+          maximum: 90,
+        },
       },
       required: ['motion'],
     },
diff --git a/src/voice/actionSchemas.test.mjs b/src/voice/actionSchemas.test.mjs
index d15a7c25e..d7805e215 100644
--- a/src/voice/actionSchemas.test.mjs
+++ b/src/voice/actionSchemas.test.mjs
@@ -49,7 +49,8 @@ test('the complete Realtime tool payload pins the manifest-generated layer relea
     // Snow leaves the set_visual_style enum.
     // The Operator HUD layout leaves set_hud's layout enum.
     // The layer alias hint leaves out aliases the layer id already spells.
-    'dc2bac1be93a503dc88d637beea2f1bc457e1f9167422bd91548b44756a8aca5',
+    // move_camera tilt takes an optional pitchDeg angle.
+    '35261624ef8596608b80e2876f83760723ecf6592acc43fd77691cdb0a972608',
   );
 });
 
@@ -134,6 +135,8 @@ test('all legacy action arguments are byte-identical after removing the delibera
     'stop',
   ]);
   motion.enum = motion.enum.filter((value) => value !== 'rotate_globe');
+  // Tilt to an angle is additive.
+  delete property('move_camera').pitchDeg;
   const panels = property('set_panel_open').panelId;
   panels.enum = panels.enum.filter(
     (id) =>
@@ -272,3 +275,12 @@ test('direct voice timeout schema accepts None and exact integers, rejects malfo
   for (const minutes of [-1, 61, 1.5, '5'])
     assert.ok(validateArgs(tool.parameters, { minutes }).length > 0);
 });
+
+test('tilt accepts an angle with no direction', () => {
+  const schema = GEV_ACTION_SCHEMAS.find(
+    (tool) => tool.name === 'move_camera',
+  ).parameters;
+  assert.deepEqual(validateArgs(schema, { motion: 'tilt', pitchDeg: -45 }), []);
+  assert.deepEqual(validateArgs(schema, { motion: 'tilt' }), []);
+  assert.ok(validateArgs(schema, { motion: 'tilt', pitchDeg: 120 }).length > 0);
+});

From 91a3f787d4bc4afd4495c5ff6a5b77e5d2bedd9a Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@Mac.mshome.net>
Date: Tue, 3 Nov 2026 16:42:39 +0530
Subject: [PATCH 10/71] Hold a voice tilt until its fly-to lands

"Fly to London and tilt the camera" reaches the app as two sibling tool
calls, and OpenAI runs them concurrently. The tilt's navigation step
cancelled the flight already in the air, so the camera tilted where it
was; when the place still needed a lookup, the late flight replaced the
tilt and London came out top-down.

The voice runner now tracks its latest flight. A tilt sent while that
flight is still looking up or flying waits for it to land (up to 30 s),
then tilts at the destination. If the flight is cancelled, finds nothing
or times out, the tilt is not run and says so.
---
 docs/CURRENT-STATE.md         |   2 +-
 src/voice/gevActions.js       |  90 +++++++++++++++++++++++--
 src/voice/gevActions.test.mjs | 123 ++++++++++++++++++++++++++++++++++
 3 files changed, 207 insertions(+), 8 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 3c17ed79f..2730ae8de 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5364,7 +5364,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair (the tracked view excepted, which tilts in place), so the place stays centred and the heading is kept; pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair (the tracked view excepted, which tilts in place), so the place stays centred and the heading is kept; pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. A voice tilt sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" arrives as two sibling calls) waits for that flight to land, up to 30 s, so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the tilt is not run and says so. A tilt sent before its fly-to is not reordered. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index fbb6cc5ce..985dece53 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -276,6 +276,10 @@ export function createGevActionRunner({
     ? { ...SPEECH_BUILDERS, ...speechBuilders }
     : SPEECH_BUILDERS;
   const _layerEnabledAt = new Map();
+  // The latest voice flight. A tilt in the same reply as "fly to X" waits for
+  // it to land: run at once, its navigation cancelled the flight, or the
+  // flight (still geocoding) then replaced the tilt.
+  let voiceFlight = null;
   let analystEngine;
   const resolveRegionRing = (name, signal) =>
     annotationResolver.resolveRegionRingForQuery(name, signal, placeSearch);
@@ -1103,7 +1107,10 @@ export function createGevActionRunner({
           runOptions,
         );
       }
-      return flyToRequestedLocation(viewer, args, {
+      const flight = trackVoiceFlight();
+      voiceFlight = flight;
+      const flown = flyToRequestedLocation(viewer, args, {
+        onFlightEnd: flight.settle,
         onProgress: reportProgress,
         placeSearch,
         searchNavigation,
@@ -1131,6 +1138,14 @@ export function createGevActionRunner({
           if (viewer.trackedEntity) stopAllTracking(viewer, dataManager);
         },
       });
+      // No flight started (not found, refused, cancelled): nothing to wait for.
+      flown.then(
+        (result) => {
+          if (result?.ok !== true) flight.settle('failed');
+        },
+        () => flight.settle('failed'),
+      );
+      return flown;
     }
 
     if (name === 'adjust_camera_zoom') {
@@ -1173,6 +1188,23 @@ export function createGevActionRunner({
     }
 
     if (name === 'move_camera') {
+      if (
+        String(args.motion || '').toLowerCase() === 'tilt' &&
+        voiceFlight &&
+        !voiceFlight.done
+      ) {
+        const status = await waitForVoiceFlight(voiceFlight, runOptions.signal);
+        if (!current())
+          return { ok: false, action: 'move_camera', cancelled: true };
+        if (status !== 'arrived')
+          return {
+            ok: false,
+            action: 'move_camera',
+            motion: 'tilt',
+            error:
+              'Not run: the flight this tilt was waiting for did not arrive.',
+          };
+      }
       return moveCamera(args, (navigate, releaseOptions) =>
         runManagedVoiceNavigation(
           styleManager,
@@ -2690,6 +2722,42 @@ async function frameOverhead(viewer, dataManager, styleManager, args = {}) {
 }
 
 /** Run one validated voice camera mutation through the UI-owned authority seam. */
+/** A voice flight's end: 'arrived', 'cancelled' or 'failed', settled once. */
+function trackVoiceFlight() {
+  let resolve;
+  const flight = {
+    done: false,
+    ended: new Promise((settle) => {
+      resolve = settle;
+    }),
+    settle: (status) => {
+      if (flight.done) return;
+      flight.done = true;
+      resolve(status);
+    },
+  };
+  return flight;
+}
+
+/** Longest a tilt waits for a flight (geocode plus flight) before giving up. */
+const VOICE_FLIGHT_WAIT_MS = 30_000;
+
+/** Wait for a voice flight to end; 'timeout' or 'aborted' if it does not. */
+function waitForVoiceFlight(flight, signal) {
+  if (signal?.aborted) return Promise.resolve('aborted');
+  return new Promise((resolve) => {
+    const finish = (status) => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+      resolve(status);
+    };
+    const onAbort = () => finish('aborted');
+    const timer = setTimeout(() => finish('timeout'), VOICE_FLIGHT_WAIT_MS);
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    flight.ended.then(finish);
+  });
+}
+
 function runManagedVoiceNavigation(
   styleManager,
   noun,
@@ -3252,6 +3320,7 @@ async function flyToRequestedLocation(
     runImmediate = null,
     beginDeferred = null,
     reassertDeferred = null,
+    onFlightEnd = null,
   } = {},
 ) {
   const requestedRangeM = Number(args.rangeM);
@@ -3275,12 +3344,19 @@ async function flyToRequestedLocation(
           settleArrival = resolve;
         })
       : null;
-  const arrivalHooks = arrival
-    ? {
-        onComplete: () => settleArrival?.('arrived'),
-        onCancel: () => settleArrival?.('cancelled'),
-      }
-    : {};
+  const arrivalHooks =
+    arrival || onFlightEnd
+      ? {
+          onComplete: () => {
+            settleArrival?.('arrived');
+            onFlightEnd?.('arrived');
+          },
+          onCancel: () => {
+            settleArrival?.('cancelled');
+            onFlightEnd?.('cancelled');
+          },
+        }
+      : {};
   const afterArrival = async (result, label) => {
     if (!arrival || result?.ok !== true) return result;
     onProgress('fly', label);
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index f6bccdfa9..ddf29babe 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -217,6 +217,129 @@ test('dependent voice navigation waits for the destination viewport to arrive',
   assert.equal(result.arrived, true);
 });
 
+// "fly to London and tilt the camera" arrives as two sibling calls.
+// Run at once, the tilt's navigation cancelled the flight; with a geocoded
+// place, the late flight replaced the tilt.
+function tiltAfterFlightHarness() {
+  globalThis.window = globalThis.window || { clearTimeout, setTimeout, requestIdleCallback: null };
+  const harness = createVoiceNavigationHarness();
+  const { viewer, styleManager } = harness;
+  const flights = [];
+  viewer.camera.flyTo = (options) => {
+    harness.order.push('fly');
+    flights.push(options);
+  };
+  styleManager.runImmediateLocationNavigation = (navigate) => (
+    styleManager.runImmediateNavigation('location', navigate)
+  );
+  return { ...harness, flights };
+}
+
+const settledYet = (promise) => {
+  let settled = false;
+  promise.then(() => { settled = true; });
+  return () => settled;
+};
+
+test('a tilt in the same reply as a fly-to waits for the flight to land', async () => {
+  const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  const fly = await runner('fly_to_location', { locationId: 'austin' });
+  assert.equal(fly.ok, true);
+  const tilt = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  const tiltDone = settledYet(tilt);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(tiltDone(), false, 'the tilt must wait while the camera flies');
+  assert.equal(
+    order.slice(order.indexOf('fly')).includes('cancel'),
+    false,
+    'the tilt must not cancel the flight',
+  );
+  flights[0].complete();
+  const result = await tilt;
+  assert.equal(result.ok, true);
+  assert.equal(result.motion, 'tilt');
+});
+
+test('a tilt waits through a geocoded fly-to search, then for its flight', async () => {
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  let finishSearch;
+  let landFlight;
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+      finishSearch = () => {
+        landFlight = options.onComplete;
+        resolve({ label: query, navigationMode: 'city-overview' });
+      };
+    }),
+  });
+  const fly = runner('fly_to_location', { query: 'Somewhere Far' });
+  const tilt = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  const tiltDone = settledYet(tilt);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(tiltDone(), false, 'the tilt must wait for the place lookup');
+  finishSearch();
+  assert.equal((await fly).ok, true);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(tiltDone(), false, 'the tilt must wait for the flight too');
+  landFlight();
+  assert.equal((await tilt).ok, true);
+});
+
+test('a tilt waiting on a flight that never lands is not run', async () => {
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  await runner('fly_to_location', { locationId: 'austin' });
+  const tilt = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  flights[0].cancel();
+  const result = await tilt;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /did not arrive/);
+});
+
+test('a tilt beside a fly-to that found nothing is not run', async () => {
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: async () => null,
+  });
+  const fly = runner('fly_to_location', { query: 'Nowhere' });
+  const tilt = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  assert.equal((await fly).ok, false);
+  // Nothing flew: the tilt answers at once and honestly, never at the old view.
+  const result = await tilt;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /did not arrive/);
+  // A later, separate tilt is not held by the failed lookup.
+  assert.equal((await runner('move_camera', { motion: 'tilt', pitchDeg: -45 })).ok, true);
+});
+
+test('a tilt with no voice flight pending runs at once', async () => {
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  await runner('fly_to_location', { locationId: 'austin' });
+  flights[0].complete();
+  const result = await runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  assert.equal(result.ok, true);
+});
+
 test('nearest-aircraft voice action serializes layer enable, arrival, refresh, airborne query, and selection', async () => {
   globalThis.window = globalThis.window || { clearTimeout, setTimeout, requestIdleCallback: null };
   const { viewer, styleManager } = createVoiceNavigationHarness();

From 75000cf6a9f71fb8f534a47c5844160ce6b95e1c Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@Mac.mshome.net>
Date: Tue, 3 Nov 2026 16:42:50 +0530
Subject: [PATCH 11/71] Hold a voice orbit, pan or rotate until its fly-to
 lands

"Fly to Paris and orbit it" reaches the app as two sibling tool calls,
which OpenAI runs at once. With a place that needs a lookup, the orbit
started over the old view and the late flight then replaced it; with a
known place, pan and rotate cancelled the flight already in the air.

Orbit, pan and rotate now wait for a pending voice flight the same way
tilt does: up to 30 s, and not run (saying so) if the flight is
cancelled, finds nothing or times out. Stop and rotate_globe do not
wait. Orbit keeps its own arming for flights the voice runner does not
track.
---
 docs/CURRENT-STATE.md         |  2 +-
 src/cameraVerbs.js            |  8 +--
 src/voice/gevActions.js       | 24 ++++++---
 src/voice/gevActions.test.mjs | 93 +++++++++++++++++++++++++++++++++++
 4 files changed, 117 insertions(+), 10 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 2730ae8de..6f20b01ad 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5364,7 +5364,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair (the tracked view excepted, which tilts in place), so the place stays centred and the heading is kept; pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. A voice tilt sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" arrives as two sibling calls) waits for that flight to land, up to 30 s, so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the tilt is not run and says so. A tilt sent before its fly-to is not reordered. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair (the tracked view excepted, which tilts in place), so the place stays centred and the heading is kept; pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 30 s, so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered. Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 3898acaa7..0b0f06792 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -1747,9 +1747,11 @@ export function moveCamera(args = {}, runNavigation = null) {
     }
     if (motion === 'orbit') {
       if (_viewer.scene.tweens.length > 0) {
-        // A camera flight is in progress ("fly to X and orbit it") — ALWAYS arm
-        // and capture at the destination; a target existing right now is
-        // meaningless (the globe is always under the crosshair).
+        // 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
+        // orbit until its own fly-to lands; this covers any other
+        // flight.
         setActiveMotion({
           kind: 'orbit',
           direction: direction || 'right',
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index 985dece53..6d9411dfe 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -1188,8 +1188,9 @@ export function createGevActionRunner({
     }
 
     if (name === 'move_camera') {
+      const motion = String(args.motion || '').toLowerCase();
       if (
-        String(args.motion || '').toLowerCase() === 'tilt' &&
+        VOICE_FLIGHT_WAITING_MOTIONS.has(motion) &&
         voiceFlight &&
         !voiceFlight.done
       ) {
@@ -1200,9 +1201,8 @@ export function createGevActionRunner({
           return {
             ok: false,
             action: 'move_camera',
-            motion: 'tilt',
-            error:
-              'Not run: the flight this tilt was waiting for did not arrive.',
+            motion,
+            error: `Not run: the flight this ${motion} was waiting for did not arrive.`,
           };
       }
       return moveCamera(args, (navigate, releaseOptions) =>
@@ -2721,7 +2721,6 @@ async function frameOverhead(viewer, dataManager, styleManager, args = {}) {
   );
 }
 
-/** Run one validated voice camera mutation through the UI-owned authority seam. */
 /** A voice flight's end: 'arrived', 'cancelled' or 'failed', settled once. */
 function trackVoiceFlight() {
   let resolve;
@@ -2739,9 +2738,21 @@ function trackVoiceFlight() {
   return flight;
 }
 
-/** Longest a tilt waits for a flight (geocode plus flight) before giving up. */
+/** Longest a motion waits for a flight (geocode plus flight) before giving up. */
 const VOICE_FLIGHT_WAIT_MS = 30_000;
 
+/**
+ * Motions that act on the place the camera ends up at, so one sent beside a
+ * fly-to waits for it. Stop is not one, and rotate_globe turns the
+ * whole Earth from Globe View rather than at a place.
+ */
+const VOICE_FLIGHT_WAITING_MOTIONS = new Set([
+  'tilt',
+  'orbit',
+  'pan',
+  'rotate',
+]);
+
 /** Wait for a voice flight to end; 'timeout' or 'aborted' if it does not. */
 function waitForVoiceFlight(flight, signal) {
   if (signal?.aborted) return Promise.resolve('aborted');
@@ -2758,6 +2769,7 @@ function waitForVoiceFlight(flight, signal) {
   });
 }
 
+/** Run one validated voice camera mutation through the UI-owned authority seam. */
 function runManagedVoiceNavigation(
   styleManager,
   noun,
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index ddf29babe..ee078ac57 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -340,6 +340,99 @@ test('a tilt with no voice flight pending runs at once', async () => {
   assert.equal(result.ok, true);
 });
 
+// Orbit, pan and rotate also act at the place the camera ends up, so "fly to
+// Paris and orbit it" holds the orbit the same way.
+for (const motion of [
+  { motion: 'orbit' },
+  { motion: 'pan', direction: 'left' },
+  { motion: 'rotate', direction: 'right' },
+]) {
+  test(`${motion.motion} in the same reply as a fly-to waits for the flight to land`, async () => {
+    const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
+    const runner = createGevActionRunner({
+      viewer,
+      styleManager,
+      dataManager: { layers: new Map(), getAll: () => [] },
+    });
+    assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+    const moved = runner('move_camera', motion);
+    const movedDone = settledYet(moved);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.equal(movedDone(), false, `the ${motion.motion} must wait while the camera flies`);
+    assert.equal(
+      order.slice(order.indexOf('fly')).includes('cancel'),
+      false,
+      `the ${motion.motion} must not cancel the flight`,
+    );
+    flights[0].complete();
+    const result = await moved;
+    assert.equal(result.ok, true);
+    assert.equal(result.motion, motion.motion);
+    interruptCameraMotion('test-cleanup');
+  });
+
+  test(`${motion.motion} waits through a geocoded fly-to search, then for its flight`, async () => {
+    const { viewer, styleManager } = tiltAfterFlightHarness();
+    let finishSearch;
+    let landFlight;
+    const runner = createGevActionRunner({
+      viewer,
+      styleManager,
+      dataManager: { layers: new Map(), getAll: () => [] },
+      searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+        finishSearch = () => {
+          landFlight = options.onComplete;
+          resolve({ label: query, navigationMode: 'city-overview' });
+        };
+      }),
+    });
+    const fly = runner('fly_to_location', { query: 'Somewhere Far' });
+    const moved = runner('move_camera', motion);
+    const movedDone = settledYet(moved);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.equal(movedDone(), false, `the ${motion.motion} must wait for the place lookup`);
+    assert.equal(getActiveCameraMotion(), null, 'nothing moves before the flight');
+    finishSearch();
+    assert.equal((await fly).ok, true);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.equal(movedDone(), false, `the ${motion.motion} must wait for the flight too`);
+    landFlight();
+    assert.equal((await moved).ok, true);
+    assert.equal(getActiveCameraMotion()?.kind, motion.motion);
+    interruptCameraMotion('test-cleanup');
+  });
+
+  test(`${motion.motion} waiting on a flight that never lands is not run`, async () => {
+    const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+    const runner = createGevActionRunner({
+      viewer,
+      styleManager,
+      dataManager: { layers: new Map(), getAll: () => [] },
+    });
+    await runner('fly_to_location', { locationId: 'austin' });
+    const moved = runner('move_camera', motion);
+    flights[0].cancel();
+    const result = await moved;
+    assert.equal(result.ok, false);
+    assert.equal(result.motion, motion.motion);
+    assert.match(result.error, new RegExp(`this ${motion.motion} was waiting for did not arrive`));
+    assert.equal(getActiveCameraMotion(), null);
+  });
+}
+
+test('stop does not wait for a voice flight', async () => {
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  await runner('fly_to_location', { locationId: 'austin' });
+  const result = await runner('move_camera', { motion: 'stop' });
+  assert.equal(result.ok, true);
+  assert.equal(result.motion, 'stop');
+});
+
 test('nearest-aircraft voice action serializes layer enable, arrival, refresh, airborne query, and selection', async () => {
   globalThis.window = globalThis.window || { clearTimeout, setTimeout, requestIdleCallback: null };
   const { viewer, styleManager } = createVoiceNavigationHarness();

From 2ac73519ec71a5c54da96e3544f18d96985a35d2 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@Mac.mshome.net>
Date: Tue, 3 Nov 2026 16:43:01 +0530
Subject: [PATCH 12/71] Add changelog fragment for voice camera tilt (#1520)

---
 changelog.d/1520-voice-camera-tilt.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 changelog.d/1520-voice-camera-tilt.md

diff --git a/changelog.d/1520-voice-camera-tilt.md b/changelog.d/1520-voice-camera-tilt.md
new file mode 100644
index 000000000..87d2aef3a
--- /dev/null
+++ b/changelog.d/1520-voice-camera-tilt.md
@@ -0,0 +1,5 @@
+- Voice "tilt the camera" works from the top-down view a fly-to lands on: the
+  camera swings about the place under the crosshair, keeps its heading, and can
+  tilt to a spoken angle ("tilt 45 degrees") or a default oblique view. A tilt,
+  orbit, pan or rotate said with a fly-to ("fly to Paris and orbit it") now
+  waits for the flight to land (Manjunath, @manjunath22466, #1520).

From 415f23739f7c81dc9f798fb5107f0e9e1044b2bf Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Tue, 3 Nov 2026 16:26:55 +0400
Subject: [PATCH 13/71] Name the reporting provider in Contacts and Cockpit
 counts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Cockpit Contact counts named fixed providers (OpenSky, adsb.lol,
AISStream) while the Layers panel and Contacts named the provider the last
snapshot reported, and the vessels layer kept that name out of getStats(),
so Contacts always said AISStream. Each cohort now carries the provider and
whether it answered as a fallback or from a stale snapshot, and both views
show it the way the Layers row does ("adsb.lol · FALLBACK").

Fixes HAL-721.
---
 docs/CURRENT-STATE.md                  |  1 +
 scripts/package-boundaries.json        |  7 ++++
 src/layers/awareness/model.js          |  1 +
 src/layers/awareness/panel.js          |  3 +-
 src/layers/awareness/panel.test.mjs    | 38 +++++++++++++++++++++
 src/layers/awareness/queries.test.mjs  | 26 +++++++++++++++
 src/layers/awareness/subject.js        | 12 +++++++
 src/layers/vessels/ownership.test.mjs  | 14 ++++++++
 src/layers/vessels/queries.js          |  2 ++
 src/ui/cockpitContext.js               |  3 ++
 src/ui/cockpitContext.test.mjs         | 46 ++++++++++++++++++++++++++
 src/ui/cockpitContextState.js          |  5 ++-
 src/ui/layerNames.js                   | 14 ++++++++
 src/ui/layerNames.test.mjs             | 17 ++++++++++
 src/ui/views/panels/CockpitContext.vue |  8 ++---
 15 files changed, 191 insertions(+), 6 deletions(-)
 create mode 100644 src/layers/awareness/panel.test.mjs

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 35d81dd05..9f5a40e63 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -4965,6 +4965,7 @@ silently demoting every later lookup for the session.
 - Enabled Data Layer controls report normalized feed health on the button (`LOADING`, `DEGRADED`, `STALE`, `FALLBACK`, or `UNAVAILABLE`) while the metadata line retains the source and reason. A partial CelesTrak group failure keeps the usable catalog and reports `DEGRADED`; a total outage keeps last-good catalog data visible but reports `UNAVAILABLE`.
 - On activation it focuses the nearest currently observed aircraft across the civilian and military feeds, with military winning an exact distance tie; if none are available, it focuses an observed AIS vessel. The aircraft search is deliberately uncapped and one refresh-tick retry handles initially empty feeds. This is an attention-priority navigation shortcut, not a high-risk, affiliation, or threat classification.
 - A selected aircraft, AIS vessel, or mapped installation gets a 250 km **context window** with nearby cohort counts, nearest examples, source labels, and stale/unavailable reasons. It emits `NEARBY` or `UNKNOWN`; no detection, engagement, affiliation, or sensor-activity conclusion is calculated.
+- Contacts rows and the Cockpit Contact counts name each cohort's provider as its layer row does: the source the last snapshot reported, marked `FALLBACK` or `STALE` in the same cases. A flight snapshot answered by the adsb.lol regional fallback reads `adsb.lol · FALLBACK` everywhere, never `OpenSky`.
 - For a selected live aircraft or vessel, the context window refreshes from the existing tracker/feed position every 750 ms, so nearest distances and cohort counts follow the subject without introducing a duplicate poll loop.
 - Aircraft cohort membership uses every locally loaded, selectable contact inside the 250 km window, including a plane hidden only by horizon culling or because its 3D model owns the visual. Counts and navigation therefore do not change with the current camera angle or billboard/model handoff.
 - Nearby examples in the context panel are focus controls: they use their owning layer's existing selection/tracking path, then frame that contact. Static-installation distances use ellipsoidal surface distance so the count matches the ground-projected context disk.
diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json
index 6d55213e7..f5529e731 100644
--- a/scripts/package-boundaries.json
+++ b/scripts/package-boundaries.json
@@ -871,6 +871,7 @@
       "src/i18n/locales/uk.json",
       "src/i18n/locales/zh-CN.json",
       "src/i18n/locales/zh-Hant.json",
+      "src/ui/layerNames.js",
       "src/ui/unitLabels.js"
     ],
     "external": ["cesium"]
@@ -1713,6 +1714,10 @@
       "src/i18n/locales/uk.json",
       "src/i18n/locales/zh-CN.json",
       "src/i18n/locales/zh-Hant.json",
+      "src/data/feedState.js",
+      "src/loadingFeedback.js",
+      "src/data/installationFeedback.js",
+      "src/ui/layerNames.js",
       "src/ui/unitLabels.js"
     ],
     "external": ["cesium"]
@@ -3208,6 +3213,8 @@
   "application-layer-construction": {
     "exports": ["./application/layers"],
     "modules": [
+      "src/data/feedState.js",
+      "src/loadingFeedback.js",
       "src/sources/adsbFields.js",
       "src/data/headingDegrees.js",
       "src/data/distanceFormat.js",
diff --git a/src/layers/awareness/model.js b/src/layers/awareness/model.js
index 1a399c5af..1ff2c93cf 100644
--- a/src/layers/awareness/model.js
+++ b/src/layers/awareness/model.js
@@ -196,6 +196,7 @@ export function createModel({ state: layerState, services, parts, source }) {
         id: cohort.id,
         label: cohort.label,
         source: cohort.source,
+        sourceStatus: cohort.sourceStatus || null,
         coverage: cohort.coverage || null,
         relationship: cohort.summary.relationship,
         count: cohort.summary.count,
diff --git a/src/layers/awareness/panel.js b/src/layers/awareness/panel.js
index c0c71ed01..5396a0390 100644
--- a/src/layers/awareness/panel.js
+++ b/src/layers/awareness/panel.js
@@ -8,6 +8,7 @@ import {
   t,
   translateKnown,
 } from '../../i18n/index.js';
+import { sourceStatusLabel } from '../../ui/layerNames.js';
 import { formatQuantity } from '../../ui/unitLabels.js';
 import { AWARENESS_PAGE_SIZE, AWARENESS_PAGE_ROTATE_MS } from './policy.js';
 import { distanceParts } from '../../data/distanceFormat.js';
@@ -150,7 +151,7 @@ export function createPanel({ state: layerState, parts }) {
       relationship: summary.relationship.toLowerCase(),
       label: cohort.label,
       count: `${presentAwarenessCount(summary)}${pageLabel}`,
-      detail: `${cohort.source}${coverage} · ${presentAwarenessReason(summary)}`,
+      detail: `${sourceStatusLabel(cohort.source, cohort.sourceStatus)}${coverage} · ${presentAwarenessReason(summary)}`,
       nearest,
     };
   }
diff --git a/src/layers/awareness/panel.test.mjs b/src/layers/awareness/panel.test.mjs
new file mode 100644
index 000000000..eaaac70e9
--- /dev/null
+++ b/src/layers/awareness/panel.test.mjs
@@ -0,0 +1,38 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createPanel } from './panel.js';
+
+test('a Contacts row names its provider as the Layers panel does, with its feed state', () => {
+  const cohort = (id, source, sourceStatus) => ({
+    id,
+    label: id,
+    source,
+    sourceStatus,
+    summary: { relationship: 'OBSERVED', count: 1, nearest: [], reason: 'observed' },
+  });
+  const state = {
+    enabled: true,
+    results: {
+      subject: { label: 'AFR38JF' },
+      cohorts: [
+        cohort('flights', 'adsb.lol', 'fallback'),
+        cohort('military', 'adsb.lol', null),
+        cohort('ais-live-vessels', 'Datalastic', 'stale'),
+      ],
+    },
+    cohortPages: new Map(),
+    panelListeners: new Set(),
+    panelSignature: '',
+    navigationIndex: 0,
+  };
+  const parts = {
+    navigation: { canNavigateNext: () => false },
+    rendering: { hideDirectionOverlay() {} },
+  };
+  createPanel({ state, parts }).renderResults();
+  assert.deepEqual(
+    state.panelView.rows.map((row) => row.detail),
+    ['adsb.lol · FALLBACK · observed', 'adsb.lol · observed', 'Datalastic · STALE · observed'],
+  );
+  state.offPanelLocale?.();
+});
diff --git a/src/layers/awareness/queries.test.mjs b/src/layers/awareness/queries.test.mjs
index 04e8a8982..07686dcfc 100644
--- a/src/layers/awareness/queries.test.mjs
+++ b/src/layers/awareness/queries.test.mjs
@@ -81,3 +81,29 @@ test('Contacts excludes square corners and measures from the current moving subj
   assert.equal(moved.reason, 'mapped matches within 100 km of the subject');
   assert.deepEqual(installationState.contextAnchor, { latitude: 0, longitude: 0 });
 });
+
+test('Contacts cohorts carry the provider and whether it answered as a fallback or stale', () => {
+  const services = { installations: { getNearby: () => [], getStats: () => ({}) },
+    flights: { getNearby: () => [] }, military: { getNearby: () => [] }, vessels: { getNearby: () => [] } };
+  const parts = { navigation: { summarizeAwarenessCohortForNavigation: (items, source) =>
+    summarizeAwarenessCohort(items, source) } };
+  parts.queries = createQueries({ state: {}, services, parts });
+  const subjectOwner = createSubject({ state: {}, services, parts });
+  const states = {
+    // The OpenSky proxy answers from adsb.lol when OpenSky fails.
+    flights: { available: true, stats: { source: 'adsb.lol', coverage: '250nm regional fallback', count: 4, lastUpdate: 1 } },
+    military: { available: true, stats: { source: 'adsb.lol', fallback: false, count: 2, lastUpdate: 1 } },
+    'ais-live-vessels': { available: true, stats: { source: 'Datalastic', stale: true, count: 3, lastUpdate: 1 } },
+    'military-installations': { available: true, stats: { coverage: { kind: 'subject', radiusM: 100000 } } },
+  };
+  const { cohorts } = subjectOwner.evaluateSubject({
+    id: 'subject', layerId: 'flights', position: Cesium.Cartesian3.fromDegrees(0, 0, 10000),
+  }, states);
+  const byId = Object.fromEntries(cohorts.map((cohort) => [cohort.id, cohort]));
+  assert.equal(byId.flights.source, 'adsb.lol');
+  assert.equal(byId.flights.sourceStatus, 'fallback');
+  assert.equal(byId.military.sourceStatus, null);
+  assert.equal(byId['ais-live-vessels'].source, 'Datalastic');
+  assert.equal(byId['ais-live-vessels'].sourceStatus, 'stale');
+  assert.equal(byId['military-installations'].sourceStatus, null);
+});
diff --git a/src/layers/awareness/subject.js b/src/layers/awareness/subject.js
index 1baf54ec4..a555d332e 100644
--- a/src/layers/awareness/subject.js
+++ b/src/layers/awareness/subject.js
@@ -3,6 +3,7 @@ import {
   AWARENESS_RELATIONSHIP,
 } from '../../data/militaryAwarenessEngine.js';
 import * as Cesium from 'cesium';
+import { layerFeedState } from '../../data/feedState.js';
 import { t } from '../../i18n/index.js';
 import {
   AWARENESS_QUERY_LIMIT,
@@ -52,6 +53,13 @@ export function createSubject({ state: layerState, services, parts, source }) {
     const vesselsState = sourceStates['ais-live-vessels'];
     const installationsState = sourceStates['military-installations'];
     const evaluatedAt = Date.now();
+    // Whether the provider answered as a fallback or from a stale snapshot.
+    const sourceStatus = (sourceState) => {
+      const feedState = layerFeedState(sourceState.stats);
+      return feedState === 'fallback' || feedState === 'stale'
+        ? feedState
+        : null;
+    };
     const retainedProvenance = (id, label, sourceState, fallbackSource) => {
       const retainedSource = sourceState.stats.source || fallbackSource;
       return {
@@ -94,6 +102,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
           id: 'flights',
           label: t('Flights'),
           source: flightsState.stats.source || SOURCE_LABEL.flights,
+          sourceStatus: sourceStatus(flightsState),
           provenance: retainedProvenance(
             'flights',
             'Flights',
@@ -113,6 +122,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
           id: 'military',
           label: t('Military flights'),
           source: militaryState.stats.source || SOURCE_LABEL.military,
+          sourceStatus: sourceStatus(militaryState),
           provenance: retainedProvenance(
             'military',
             'Military flights',
@@ -132,6 +142,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
           id: 'ais-live-vessels',
           label: t('AIS vessels'),
           source: vesselsState.stats.source || SOURCE_LABEL['ais-live-vessels'],
+          sourceStatus: sourceStatus(vesselsState),
           provenance: retainedProvenance(
             'ais-live-vessels',
             'AIS vessels',
@@ -149,6 +160,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
           source:
             installationsState.stats.source ||
             SOURCE_LABEL['military-installations'],
+          sourceStatus: sourceStatus(installationsState),
           provenance: retainedProvenance(
             'military-installations',
             'Mapped installations',
diff --git a/src/layers/vessels/ownership.test.mjs b/src/layers/vessels/ownership.test.mjs
index 4ef9b7525..a838a8099 100644
--- a/src/layers/vessels/ownership.test.mjs
+++ b/src/layers/vessels/ownership.test.mjs
@@ -409,3 +409,17 @@ test('empty coverage cannot hide stale, incomplete or rejected source data', asy
     assert.ok(layer.getStats().error, JSON.stringify(patch));
   }
 });
+
+test('vessel stats name the provider the last snapshot reported', async () => {
+  // HAL-721: Contacts named a fixed AIS provider while this layer showed the
+  // one its server reported.
+  const { layer } = setup({
+    label: 'Vessels',
+    async getSnapshot() {
+      return snapshot([observation('111')], { source: 'Datalastic' });
+    },
+  });
+  assert.equal(layer.getStats().source, 'Vessels');
+  await layer.update();
+  assert.equal(layer.getStats().source, 'Datalastic');
+});
diff --git a/src/layers/vessels/queries.js b/src/layers/vessels/queries.js
index c848acc2d..48ded012b 100644
--- a/src/layers/vessels/queries.js
+++ b/src/layers/vessels/queries.js
@@ -548,6 +548,8 @@ export function createQueries({
         // backing off, say how long until the next attempt instead of leaving
         // the user to guess whether anything is still happening.
         retryInSec: aisRetryInSec(),
+        // The provider the last snapshot named, as flights and military report it.
+        source: layer.source,
       };
     },
   };
diff --git a/src/ui/cockpitContext.js b/src/ui/cockpitContext.js
index 1158c632b..ad73869db 100644
--- a/src/ui/cockpitContext.js
+++ b/src/ui/cockpitContext.js
@@ -1,6 +1,7 @@
 /** Contact readouts and nearby-signal presentation for the Cockpit controller. */
 import * as Cesium from 'cesium';
 import { formatNumber, t, tn } from '../i18n/index.js';
+import { sourceStatusLabel } from './layerNames.js';
 import { unitLabel } from './unitLabels.js';
 import {
   bearingBetweenCoordinates,
@@ -110,6 +111,8 @@ export function updateContext(info, heading) {
     if (shown) {
       shown.count = cohort.count === null ? '?' : String(cohort.count);
       shown.unknown = cohort.relationship === 'UNKNOWN';
+      // The provider that answered, named as the Layers panel names it.
+      shown.source = sourceStatusLabel(cohort.source, cohort.sourceStatus);
     }
     if (cohort.count === null) unknownCount += 1;
     for (const item of cohort.nearest) nearest.push({ ...item, cohort });
diff --git a/src/ui/cockpitContext.test.mjs b/src/ui/cockpitContext.test.mjs
index 47d3719c7..a8d6616d5 100644
--- a/src/ui/cockpitContext.test.mjs
+++ b/src/ui/cockpitContext.test.mjs
@@ -96,6 +96,13 @@ test('before the controller presents, the card shows the state it starts in', (t
     ),
     ['—', '—', '—', '—'],
   );
+  // No provider is named before a snapshot reports one.
+  assert.deepEqual(
+    [...document.querySelectorAll('[data-context-cohort] small')].map(
+      (source) => source.textContent,
+    ),
+    ['—', '—', '—', '—'],
+  );
   assert.equal(text('#cockpit-context-nearest-label'), 'NO AVAILABLE EXAMPLE');
   assert.equal(
     $('#cockpit-context-nearest-label').hasAttribute('aria-label'),
@@ -159,6 +166,45 @@ test('a snapshot fills the card and keeps classes other code sets', async (t) =>
   assert.equal(layouts.length, 1);
 });
 
+test('each count names the provider its snapshot reports, with its feed state', async (t) => {
+  // HAL-721: the counters named fixed providers while the layer and the
+  // Contacts list named the one that answered.
+  const reported = snapshot();
+  reported.cohorts[0].source = 'adsb.lol';
+  reported.cohorts[0].sourceStatus = 'fallback';
+  reported.cohorts[1].source = 'Plane Finder';
+  reported.cohorts.push(
+    {
+      id: 'ais-live-vessels',
+      label: 'AIS vessels',
+      source: 'Datalastic',
+      sourceStatus: 'stale',
+      count: 3,
+      relationship: 'OBSERVED',
+      nearest: [],
+    },
+    {
+      id: 'military-installations',
+      label: 'Mapped installations',
+      source: 'OpenStreetMap',
+      sourceStatus: null,
+      count: 0,
+      relationship: 'MAPPED',
+      nearest: [],
+    },
+  );
+  const { $, owner } = fixture(t, reported);
+  updateContext.call(owner, INFO, 0);
+  await nextTick();
+  const source = (id) => $(`[data-context-cohort="${id}"] small`);
+  assert.equal(source('flights').textContent, 'adsb.lol · FALLBACK');
+  assert.equal(source('military').textContent, 'Plane Finder');
+  assert.equal(source('ais-live-vessels').textContent, 'Datalastic · STALE');
+  assert.equal(source('military-installations').textContent, 'OpenStreetMap');
+  // The tile ellipsizes; the full name stays readable on hover.
+  assert.equal(source('flights').title, 'adsb.lol · FALLBACK');
+});
+
 test('a lost contact holds its readout behind the CONTACT LOST cue', async (t) => {
   const { $, text, owner, layouts } = fixture(t, snapshot());
   updateContext.call(owner, INFO, 0);
diff --git a/src/ui/cockpitContextState.js b/src/ui/cockpitContextState.js
index dafffc11f..3c2db3c5a 100644
--- a/src/ui/cockpitContextState.js
+++ b/src/ui/cockpitContextState.js
@@ -25,7 +25,10 @@ export function createContextState() {
     canPrevious: true,
     canNext: true,
     cohorts: Object.fromEntries(
-      COCKPIT_CONTEXT_COHORTS.map((id) => [id, { count: '—', unknown: false }]),
+      COCKPIT_CONTEXT_COHORTS.map((id) => [
+        id,
+        { count: '—', unknown: false, source: '—' },
+      ]),
     ),
     nearest: { label: t('NO AVAILABLE EXAMPLE'), ariaLabel: null },
     distance: { text: '—', ariaLabel: null },
diff --git a/src/ui/layerNames.js b/src/ui/layerNames.js
index 2c918ad95..519b3e207 100644
--- a/src/ui/layerNames.js
+++ b/src/ui/layerNames.js
@@ -137,3 +137,17 @@ export function sourceLabel(source) {
     ? source.split(' · ').map(translateKnown).join(' · ')
     : translateKnown(source);
 }
+
+/**
+ * A provider name with the feed state it answered in, so a fallback or stale
+ * snapshot does not read as the live primary feed.
+ * @param {string} source English source name.
+ * @param {'fallback'|'stale'|null} status Feed state from `layerFeedState`.
+ * @returns {string}
+ */
+export function sourceStatusLabel(source, status) {
+  const name = sourceLabel(source);
+  if (status === 'fallback') return `${name} · ${t('FALLBACK')}`;
+  if (status === 'stale') return `${name} · ${t('STALE')}`;
+  return name;
+}
diff --git a/src/ui/layerNames.test.mjs b/src/ui/layerNames.test.mjs
index df15c79bf..e1815e477 100644
--- a/src/ui/layerNames.test.mjs
+++ b/src/ui/layerNames.test.mjs
@@ -7,6 +7,7 @@ import {
   LAYER_NAME_KEYS,
   PANEL_LABEL_KEYS,
   sourceLabel,
+  sourceStatusLabel,
 } from './layerNames.js';
 
 // Layers whose module name is a proper name and stays as it is in every
@@ -51,3 +52,19 @@ for (const locale of ['es', 'ru']) {
     }
   });
 }
+
+test('a provider name carries the fallback or stale state it answered in', () => {
+  assert.equal(sourceStatusLabel('Plane Finder', null), 'Plane Finder');
+  assert.equal(sourceStatusLabel('adsb.lol', 'fallback'), 'adsb.lol · FALLBACK');
+  assert.equal(sourceStatusLabel('OpenSky Network', 'stale'), 'OpenSky Network · STALE');
+  setLocale('ru');
+  try {
+    assert.equal(
+      sourceStatusLabel('adsb.lol', 'fallback'),
+      `adsb.lol · ${t('FALLBACK')}`,
+    );
+    assert.notEqual(t('FALLBACK'), 'FALLBACK');
+  } finally {
+    setLocale('en');
+  }
+});
diff --git a/src/ui/views/panels/CockpitContext.vue b/src/ui/views/panels/CockpitContext.vue
index ed6df8362..2374deb3e 100644
--- a/src/ui/views/panels/CockpitContext.vue
+++ b/src/ui/views/panels/CockpitContext.vue
@@ -49,10 +49,10 @@ const weatherLabel = computed(() =>
       <span class="cockpit-context-qualifier">{{ t('CONTEXT ONLY') }}</span>
     </header>
     <div class="cockpit-context-cohorts" role="list" :aria-label="t('Nearby cohort counts')">
-      <div v-class-toggle="{ unknown: c.cohorts.flights.unknown }" role="listitem" data-context-cohort="flights"><span>{{ t('FLT') }}</span><strong>{{ c.cohorts.flights.count }}</strong><small translate="no">OpenSky</small></div>
-      <div v-class-toggle="{ unknown: c.cohorts.military.unknown }" role="listitem" data-context-cohort="military"><span>{{ t('MIL') }}</span><strong>{{ c.cohorts.military.count }}</strong><small translate="no">adsb.lol</small></div>
-      <div v-class-toggle="{ unknown: c.cohorts['ais-live-vessels'].unknown }" role="listitem" data-context-cohort="ais-live-vessels"><span translate="no">AIS</span><strong>{{ c.cohorts['ais-live-vessels'].count }}</strong><small translate="no">AISStream</small></div>
-      <div v-class-toggle="{ unknown: c.cohorts['military-installations'].unknown }" role="listitem" data-context-cohort="military-installations"><span>{{ t('SITE') }}</span><strong>{{ c.cohorts['military-installations'].count }}</strong><small translate="no">OpenStreetMap</small></div>
+      <div v-class-toggle="{ unknown: c.cohorts.flights.unknown }" role="listitem" data-context-cohort="flights"><span>{{ t('FLT') }}</span><strong>{{ c.cohorts.flights.count }}</strong><small translate="no" :title="c.cohorts.flights.source">{{ c.cohorts.flights.source }}</small></div>
+      <div v-class-toggle="{ unknown: c.cohorts.military.unknown }" role="listitem" data-context-cohort="military"><span>{{ t('MIL') }}</span><strong>{{ c.cohorts.military.count }}</strong><small translate="no" :title="c.cohorts.military.source">{{ c.cohorts.military.source }}</small></div>
+      <div v-class-toggle="{ unknown: c.cohorts['ais-live-vessels'].unknown }" role="listitem" data-context-cohort="ais-live-vessels"><span translate="no">AIS</span><strong>{{ c.cohorts['ais-live-vessels'].count }}</strong><small translate="no" :title="c.cohorts['ais-live-vessels'].source">{{ c.cohorts['ais-live-vessels'].source }}</small></div>
+      <div v-class-toggle="{ unknown: c.cohorts['military-installations'].unknown }" role="listitem" data-context-cohort="military-installations"><span>{{ t('SITE') }}</span><strong>{{ c.cohorts['military-installations'].count }}</strong><small translate="no" :title="c.cohorts['military-installations'].source">{{ c.cohorts['military-installations'].source }}</small></div>
     </div>
     <div class="cockpit-context-nearest">
       <span id="cockpit-context-direction" v-class-toggle="{ unknown: c.direction.unknown }" class="material-symbols-outlined" :style="directionStyle" aria-hidden="true">navigation</span>

From 490c8d1769cc96fd9c93c4daff7986028e9a02e7 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Tue, 3 Nov 2026 16:27:25 +0400
Subject: [PATCH 14/71] Add the changelog entry for #1521

---
 changelog.d/1521-provider-labels.md | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 changelog.d/1521-provider-labels.md

diff --git a/changelog.d/1521-provider-labels.md b/changelog.d/1521-provider-labels.md
new file mode 100644
index 000000000..d921d9d7b
--- /dev/null
+++ b/changelog.d/1521-provider-labels.md
@@ -0,0 +1,4 @@
+- Name the provider that answered in the Cockpit Contact counts and the
+  Contacts list, as the Layers panel does, marked `FALLBACK` or `STALE` when
+  it is. The counts no longer read OpenSky while flights come from the adsb.lol
+  fallback, and vessels no longer always read AISStream (German, @gekh, #1521).

From 5c74b860b77aa83ddbc36fa87442d6db620d28bc Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Tue, 3 Nov 2026 19:35:02 +0530
Subject: [PATCH 15/71] Address review: zoom, drag, clearance and pitchDeg for
 voice tilt

- A zoom during a pivoting tilt now scales the range the tilt holds,
  as it already did for orbit, instead of being undone on the next
  frame while reporting success. The zoom limits no longer move a view
  the wrong way: a zoom in leaves a view closer than 80 m in place, and
  a zoom out leaves an orbit beyond 5,000 km where it is.
- A grab, touch or wheel on the map while a voice fly-to is in flight
  drops the motion queued behind it. Cesium lands the flight anyway,
  so the orbit or tilt would otherwise take the camera back. Chained
  fly-tos in one reply keep the earliest snapshot.
- A pivot tilt toward the horizon stops lowering the camera at 150 m
  above the pivot and tilts the rest in place, so a close view no
  longer ends inside tiles or a hillside.
- pitchDeg is an absolute angle. A direction that contradicts it is
  refused, judged from the pitch the swing starts at, and the tool
  description says so.
---
 changelog.d/1520-voice-camera-tilt.md       |   3 +-
 docs/CURRENT-STATE.md                       |   2 +-
 server/providers/openai/toolDescriptions.js |   2 +-
 src/cameraTilt.test.mjs                     | 146 ++++++++++++++++++++
 src/cameraVerbs.js                          | 113 ++++++++++++---
 src/voice/actionSchemas.test.mjs            |   5 +-
 src/voice/gevActions.js                     |  22 ++-
 src/voice/gevActions.test.mjs               |  69 +++++++++
 8 files changed, 331 insertions(+), 31 deletions(-)

diff --git a/changelog.d/1520-voice-camera-tilt.md b/changelog.d/1520-voice-camera-tilt.md
index 87d2aef3a..f46ae3c51 100644
--- a/changelog.d/1520-voice-camera-tilt.md
+++ b/changelog.d/1520-voice-camera-tilt.md
@@ -2,4 +2,5 @@
   camera swings about the place under the crosshair, keeps its heading, and can
   tilt to a spoken angle ("tilt 45 degrees") or a default oblique view. A tilt,
   orbit, pan or rotate said with a fly-to ("fly to Paris and orbit it") now
-  waits for the flight to land (Manjunath, @manjunath22466, #1520).
+  waits for the flight to land, and is dropped if you move the map meanwhile
+  (Manjunath, @manjunath22466, #1520).
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 6f20b01ad..15aeddfec 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5364,7 +5364,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair (the tracked view excepted, which tilts in place), so the place stays centred and the heading is kept; pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 30 s, so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered. Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair (the tracked view excepted, which tilts in place), so the place stays centred and the heading is kept; pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. A zoom during a pivoting tilt scales the range it holds, as for orbit; a zoom in moves the camera along its view line and may take it below that height, as any zoom does, and the tilt then continues in place. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 30 s, so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered. Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/server/providers/openai/toolDescriptions.js b/server/providers/openai/toolDescriptions.js
index 873a52c8a..c79511e14 100644
--- a/server/providers/openai/toolDescriptions.js
+++ b/server/providers/openai/toolDescriptions.js
@@ -533,7 +533,7 @@ export const ACTION_DESCRIPTIONS = {
         },
         pitchDeg: {
           description:
-            'Tilt to this angle below the horizon (-45 oblique, -89 top-down). Bare tilt: -45.',
+            'Absolute angle below the horizon, not a step (-45 oblique, -89 top-down). Bare tilt: -45.',
           $position: 2,
         },
       },
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index babe95807..d70b07cbb 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import * as Cesium from 'cesium';
 import {
+  adjustOrbitRange,
   getActiveCameraMotion,
   initCameraVerbs,
   interruptCameraMotion,
@@ -222,3 +223,148 @@ test('a pivoting tilt yields when tracking takes the camera', (t) => {
   h.viewer.trackedEntityChanged.raiseEvent(entity);
   assert.equal(getActiveCameraMotion(), null);
 });
+
+/** Metres between the camera and the point it pivots about. */
+const pivotRange = (h) =>
+  Cesium.Cartesian3.distance(h.camera.positionWC, h.target);
+const heightM = (camera) =>
+  Cesium.Cartographic.fromCartesian(camera.positionWC).height;
+
+test('a zoom during a pivoting tilt changes the range it holds', (t) => {
+  const h = harness(t);
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' }).ok,
+    true,
+  );
+  h.tick();
+  const before = pivotRange(h);
+  assert.equal(adjustOrbitRange(0.5), true, 'the tilt must take the zoom');
+  for (let i = 0; i < 5; i += 1) h.tick();
+  // The next frame's lookAt must not put the old range back.
+  assert.ok(
+    Math.abs(pivotRange(h) - before / 2) < 1,
+    `range ${pivotRange(h)} m, wanted ${before / 2} m`,
+  );
+});
+
+test('a zoom with no pivot to hold is left to the camera', (t) => {
+  harness(t, { pivot: false });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  assert.equal(adjustOrbitRange(0.5), false);
+});
+
+test('a pivot tilt toward the horizon keeps its clearance above the ground', (t) => {
+  // A close top-down view: swinging 250 m of range to -5° would end ~22 m up.
+  const h = harness(t, { height: 250 });
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -5 }).ok, true);
+  let lowest = Infinity;
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    lowest = Math.min(lowest, heightM(h.camera));
+  }
+  assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  assert.ok(lowest > 149, `camera dropped to ${lowest} m`);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -5) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+  assert.ok(Cesium.Matrix4.equals(h.camera.transform, Cesium.Matrix4.IDENTITY));
+});
+
+test('a continuous tilt up from close in keeps its clearance', (t) => {
+  const h = harness(t, { height: 250 });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
+  }
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('a city-scale pivot tilt keeps the place centred to the horizon limit', (t) => {
+  const h = harness(t);
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  h.finish();
+  // 4 km of range clears the floor at every pitch: all pivot, no drift.
+  assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
+});
+
+test('pitchDeg against a contradicting direction is refused', (t) => {
+  harness(t, { pitch: -45 });
+  // "tilt down 10 degrees": -10° is an absolute angle, which is up from -45°.
+  const result = moveCamera({
+    motion: 'tilt',
+    direction: 'down',
+    pitchDeg: 10,
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /absolute angle/);
+  assert.equal(getActiveCameraMotion(), null);
+});
+
+test('pitchDeg with a direction that agrees still tilts', (t) => {
+  const h = harness(t, { pitch: -45 });
+  const result = moveCamera({
+    motion: 'tilt',
+    direction: 'down',
+    pitchDeg: -80,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.direction, 'down');
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -80) < 0.5);
+});
+
+test('the pitchDeg and direction check uses the pitch the swing starts from', (t) => {
+  // At regional range the Earth curves away: the pivot pitch is a degree or
+  // two shallower than the camera's (-30°), so -29° is still down from it.
+  harness(t, { height: 150000, pitch: -30 });
+  const up = moveCamera({ motion: 'tilt', direction: 'up', pitchDeg: -29 });
+  assert.equal(up.ok, false);
+  assert.match(up.error, /tilts down, not up/);
+  const down = moveCamera({ motion: 'tilt', direction: 'down', pitchDeg: -29 });
+  assert.equal(down.ok, true);
+  assert.equal(down.direction, 'down');
+});
+
+test('after a zoom in, a pivoting tilt never lowers the camera further', (t) => {
+  const h = harness(t, { height: 1000 });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  while (pitchDeg(h.camera) < -30) h.tick();
+  adjustOrbitRange(1 / 2.4);
+  adjustOrbitRange(1 / 2.4);
+  h.tick();
+  const afterZoom = heightM(h.camera);
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    assert.ok(
+      heightM(h.camera) > afterZoom - 1,
+      `camera fell from ${afterZoom} m to ${heightM(h.camera)} m`,
+    );
+  }
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('a zoom in during a close pivot tilt never pushes the camera out', (t) => {
+  // 62 m of range, under the 80 m zoom floor.
+  const h = harness(t, { height: 40, pitch: -40 });
+  moveCamera({ motion: 'tilt', direction: 'down', mode: 'continuous' });
+  h.tick();
+  const before = pivotRange(h);
+  assert.ok(before < 80, `range ${before} m`);
+  adjustOrbitRange(1 / 1.6);
+  h.tick();
+  assert.ok(pivotRange(h) <= before + 0.01, `range grew to ${pivotRange(h)} m`);
+});
+
+test('a zoom out during a far orbit never pulls the camera in', (t) => {
+  // 15,000 km up, beyond the 5,000 km zoom cap.
+  const h = harness(t, { height: 15_000_000 });
+  assert.equal(moveCamera({ motion: 'orbit', mode: 'continuous' }).ok, true);
+  h.tick();
+  const before = pivotRange(h);
+  assert.ok(before > 5_000_000, `range ${before} m`);
+  assert.equal(adjustOrbitRange(2.4), true);
+  h.tick();
+  assert.ok(pivotRange(h) >= before - 1, `range fell to ${pivotRange(h)} m`);
+});
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 0b0f06792..7e94d0edf 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -52,6 +52,11 @@ const PITCH_MAX = Cesium.Math.toRadians(-5);
 const TILT_DEFAULT_PITCH_DEG = -45;
 /** °/s for a tilt to a requested angle; short ones keep the once duration. */
 const TILT_TO_DEG_S = 30;
+/**
+ * A pivoting tilt keeps the range, so its height above the pivot is
+ * range × sin|pitch|. It swings no lower than this; the rest tilts in place.
+ */
+const TILT_MIN_CLEARANCE_M = 150;
 
 /* ── Route dolly: cinematic tuning ──────────────────────────────────────────
  * Every knob an owner may want to retune lives in this block. The shaping is
@@ -970,6 +975,17 @@ let _trackingRemover = null;
 let _inputRemovers = [];
 /** Monotonic id for the motion currently running; 0 means "no motion". */
 let _motionSeq = 0;
+/** Canvas grabs, touches and wheel turns since load. */
+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.
+ * @returns {number} Manual camera inputs so far.
+ */
+export function manualCameraInputCount() {
+  return _manualInputCount;
+}
 
 /**
  * Install a motion and stamp it with a fresh id. The id is what lets a caller
@@ -1248,7 +1264,8 @@ function onTick() {
  * so the place under the crosshair stays centred; without one it looks up or
  * down in place. Pitch is clamped to [-89°, -5°] only in the direction of
  * travel: a top-down view sits at -90°, below the limit, and must still be
- * able to tilt up out of it.
+ * able to tilt up out of it. A pivot swing toward the horizon lowers the
+ * camera, so it stops at TILT_MIN_CLEARANCE_M and the rest tilts in place.
  */
 function tickTilt(cam, m, scale, dt) {
   let step;
@@ -1261,24 +1278,58 @@ function tickTilt(cam, m, scale, dt) {
       dt *
       (m.direction === 'up' ? 1 : -1);
   }
-  const from = m.hpr ? m.hpr.pitch : cam.pitch;
-  const next = from + step;
-  const limited =
-    step > 0
-      ? Math.min(next, Math.max(from, PITCH_MAX))
-      : Math.max(next, Math.min(from, PITCH_MIN));
   if (m.hpr) {
+    const from = m.hpr.pitch;
+    const next = from + step;
+    const limited =
+      step > 0
+        ? Math.min(next, Math.max(from, tiltPivotPitchMax(m.hpr.range)))
+        : Math.max(next, Math.min(from, PITCH_MIN));
     m.hpr.pitch = limited;
     cam.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();
-  } else {
-    cam.lookUp(limited - from);
+    if (limited === next) return;
+    if (step < 0 || limited >= PITCH_MAX) {
+      interruptCameraMotion('tilt-clamp');
+      return;
+    }
+    // Down to its clearance: let go of the pivot and tilt the rest in place,
+    // which keeps the height.
+    if (_active === m) clearLookAt();
+    m.hpr = null;
+    m.target = null;
+    step = next - limited;
   }
+  const from = cam.pitch;
+  const next = from + step;
+  const limited =
+    step > 0
+      ? Math.min(next, Math.max(from, PITCH_MAX))
+      : Math.max(next, Math.min(from, PITCH_MIN));
+  cam.lookUp(limited - from);
   if (limited !== next) interruptCameraMotion('tilt-clamp');
 }
 
+/** Shallowest pivot pitch that keeps the clearance at this range. */
+function tiltPivotPitchMax(range) {
+  return Math.min(
+    PITCH_MAX,
+    -Math.asin(Math.min(1, TILT_MIN_CLEARANCE_M / range)),
+  );
+}
+
+/**
+ * Where a tilt starts. It swings about the ground under the crosshair so the
+ * place stays centred; the follow camera owns a tracked view's frame.
+ */
+function tiltStartFrame(cam) {
+  const target = _viewer.trackedEntity ? null : _getTarget?.(_viewer);
+  const pivot = target ? tiltPivot(cam, target) : null;
+  return { target, pivot, from: pivot ? pivot.pitch : cam.pitch };
+}
+
 /** Ground pivot for a tilt: heading, pitch and range in the target's own frame. */
 function tiltPivot(cam, target) {
   const local = Cesium.Matrix4.multiplyByPoint(
@@ -1482,7 +1533,10 @@ export function initCameraVerbs(
   const canvas = viewer.scene.canvas;
   // ANY manual camera input reclaims control — the cancelFlight reflex.
   for (const evt of ['pointerdown', 'touchstart', 'wheel']) {
-    const h = () => interruptCameraMotion('manual-input');
+    const h = () => {
+      _manualInputCount += 1;
+      interruptCameraMotion('manual-input');
+    };
     canvas.addEventListener(evt, h, { passive: true });
     _inputRemovers.push(() => canvas.removeEventListener(evt, h));
   }
@@ -1580,9 +1634,10 @@ export function moveCamera(args = {}, runNavigation = null) {
     };
   }
   if (motion === 'tilt' && tiltToPitch !== null) {
-    if (
-      Math.abs(tiltToPitch - _viewer.camera.pitch) < Cesium.Math.toRadians(0.5)
-    ) {
+    // Judge from the pitch the motion will start at: the pivot's, which at
+    // regional range is a degree or two shallower than the camera's.
+    const { from } = tiltStartFrame(_viewer.camera);
+    if (Math.abs(tiltToPitch - from) < Cesium.Math.toRadians(0.5)) {
       return {
         ok: true,
         action: 'move_camera',
@@ -1591,6 +1646,18 @@ export function moveCamera(args = {}, runNavigation = null) {
         unchanged: true,
       };
     }
+    // pitchDeg is an absolute angle, not a step: "tilt down 10 degrees" sent
+    // 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));
+      return {
+        ok: false,
+        action: 'move_camera',
+        error: `pitchDeg is an absolute angle, not a step: ${target}° from ${now}° tilts ${towards}, not ${direction}. Send direction alone for a nudge, or pitchDeg alone for an angle.`,
+      };
+    }
   } 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).
@@ -1706,16 +1773,11 @@ export function moveCamera(args = {}, runNavigation = null) {
       mode,
     };
     if (motion === 'tilt') {
-      const cam = _viewer.camera;
-      // Swing about the ground under the crosshair so the place stays
-      // centred. The follow camera owns a tracked view's frame.
-      const target = _viewer.trackedEntity ? null : _getTarget?.(_viewer);
-      const pivot = target ? tiltPivot(cam, target) : null;
+      const { target, pivot, from } = tiltStartFrame(_viewer.camera);
       if (pivot) {
         state.target = target;
         state.hpr = pivot;
       }
-      const from = pivot ? pivot.pitch : cam.pitch;
       if (tiltToPitch !== null) {
         state.mode = 'once';
         state.direction = tiltToPitch > from ? 'up' : 'down';
@@ -1833,14 +1895,19 @@ export function moveCamera(args = {}, runNavigation = null) {
 /**
  * Zoom while orbiting: scale the orbit RADIUS instead of letting the zoom
  * fight the per-frame lookAt (field test: "zoom out did literally nothing").
+ * A tilt swinging about its pivot holds a range the same way.
  * @param {number} factor  >1 zooms out (radius grows), <1 zooms in.
- * @returns {boolean} true when an orbit consumed the zoom.
+ * @returns {boolean} true when an orbit or pivoting tilt consumed the zoom.
  */
 export function adjustOrbitRange(factor) {
-  if (!_active || _active.kind !== 'orbit' || !_active.hpr) return false;
+  if (!_active || !['orbit', 'tilt'].includes(_active.kind) || !_active.hpr)
+    return false;
+  // The limits never move a view the wrong way: a zoom in leaves a closer
+  // view in place, and a zoom out leaves a farther one.
+  const range = _active.hpr.range;
   _active.hpr.range = Math.max(
-    80,
-    Math.min(5_000_000, _active.hpr.range * factor),
+    Math.min(80, range),
+    Math.min(Math.max(5_000_000, range), range * factor),
   );
   return true;
 }
diff --git a/src/voice/actionSchemas.test.mjs b/src/voice/actionSchemas.test.mjs
index d7805e215..436828dba 100644
--- a/src/voice/actionSchemas.test.mjs
+++ b/src/voice/actionSchemas.test.mjs
@@ -49,8 +49,9 @@ test('the complete Realtime tool payload pins the manifest-generated layer relea
     // Snow leaves the set_visual_style enum.
     // The Operator HUD layout leaves set_hud's layout enum.
     // The layer alias hint leaves out aliases the layer id already spells.
-    // move_camera tilt takes an optional pitchDeg angle.
-    '35261624ef8596608b80e2876f83760723ecf6592acc43fd77691cdb0a972608',
+    // move_camera tilt takes an optional pitchDeg angle, described as
+    // absolute rather than a step.
+    '7258f48a19dead97d1a52cd897355ac84cb1f9077f1e8573fd64e3937660f5d0',
   );
 });
 
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index 6d9411dfe..07d0e4021 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -47,6 +47,7 @@ import {
   flyRoute,
   interruptCameraMotion,
   adjustOrbitRange,
+  manualCameraInputCount,
 } from '../cameraVerbs.js';
 import * as defaultFloorServices from '../data/groundFloor.js';
 import { isPickedWorldPosition } from '../data/scenePick.js';
@@ -1107,7 +1108,10 @@ export function createGevActionRunner({
           runOptions,
         );
       }
-      const flight = trackVoiceFlight();
+      // Chained fly-tos in one reply: a grab during the earlier one counts.
+      const flight = trackVoiceFlight(
+        voiceFlight && !voiceFlight.done ? voiceFlight.inputCount : undefined,
+      );
       voiceFlight = flight;
       const flown = flyToRequestedLocation(viewer, args, {
         onFlightEnd: flight.settle,
@@ -1194,7 +1198,8 @@ export function createGevActionRunner({
         voiceFlight &&
         !voiceFlight.done
       ) {
-        const status = await waitForVoiceFlight(voiceFlight, runOptions.signal);
+        const flight = voiceFlight;
+        const status = await waitForVoiceFlight(flight, runOptions.signal);
         if (!current())
           return { ok: false, action: 'move_camera', cancelled: true };
         if (status !== 'arrived')
@@ -1204,6 +1209,15 @@ export function createGevActionRunner({
             motion,
             error: `Not run: the flight this ${motion} was waiting for did not arrive.`,
           };
+        // The flight lands even when the user grabs the globe mid-flight;
+        // the queued motion must not take the camera back from them.
+        if (manualCameraInputCount() !== flight.inputCount)
+          return {
+            ok: false,
+            action: 'move_camera',
+            motion,
+            error: `Not run: the user moved the camera during the flight, so the ${motion} was dropped.`,
+          };
       }
       return moveCamera(args, (navigate, releaseOptions) =>
         runManagedVoiceNavigation(
@@ -2722,10 +2736,12 @@ async function frameOverhead(viewer, dataManager, styleManager, args = {}) {
 }
 
 /** A voice flight's end: 'arrived', 'cancelled' or 'failed', settled once. */
-function trackVoiceFlight() {
+function trackVoiceFlight(inputCount = manualCameraInputCount()) {
   let resolve;
   const flight = {
     done: false,
+    // Manual input after this means the user took the camera mid-flight.
+    inputCount,
     ended: new Promise((settle) => {
       resolve = settle;
     }),
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index ee078ac57..d71892130 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -420,6 +420,75 @@ for (const motion of [
   });
 }
 
+// Cesium lands a flight even when the user grabs the globe mid-flight, so the
+// motion queued behind it must not then take the camera back.
+for (const motion of [
+  { motion: 'orbit' },
+  { motion: 'tilt', pitchDeg: -45 },
+]) {
+  test(`${motion.motion} queued behind a fly-to is dropped when the user drags mid-flight`, async () => {
+    const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+    const canvasListeners = new Map();
+    viewer.scene.canvas.addEventListener = (type, listener) => {
+      canvasListeners.set(type, listener);
+    };
+    const runner = createGevActionRunner({
+      viewer,
+      styleManager,
+      dataManager: { layers: new Map(), getAll: () => [] },
+    });
+    assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+    const moved = runner('move_camera', motion);
+    canvasListeners.get('pointerdown')();
+    flights[0].complete();
+    const result = await moved;
+    assert.equal(result.ok, false);
+    assert.equal(result.motion, motion.motion);
+    assert.match(result.error, /moved the camera during the flight/);
+    assert.equal(getActiveCameraMotion(), null);
+  });
+}
+
+test('a drag during the first of two chained fly-tos still drops the queued motion', async () => {
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const canvasListeners = new Map();
+  viewer.scene.canvas.addEventListener = (type, listener) => {
+    canvasListeners.set(type, listener);
+  };
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  canvasListeners.get('touchstart')();
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'orbit' });
+  flights.at(-1).complete();
+  const result = await moved;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /moved the camera during the flight/);
+});
+
+test('input before a fly-to does not drop the motion queued behind it', async () => {
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const canvasListeners = new Map();
+  viewer.scene.canvas.addEventListener = (type, listener) => {
+    canvasListeners.set(type, listener);
+  };
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  canvasListeners.get('wheel')();
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'orbit' });
+  flights[0].complete();
+  assert.equal((await moved).ok, true);
+  interruptCameraMotion('test-cleanup');
+});
+
 test('stop does not wait for a voice flight', async () => {
   const { viewer, styleManager } = tiltAfterFlightHarness();
   const runner = createGevActionRunner({

From 9e64d517adf3e6c8c538a92c1ba6736fd3a97483 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Tue, 3 Nov 2026 20:05:34 +0530
Subject: [PATCH 16/71] Follow up voice tilt review: superseded flights, wait,
 globe range

- A motion waiting on a voice fly-to follows a later fly-to in the
  same reply that cancels it, within one deadline, instead of
  reporting that its flight did not arrive. A stale reply stops
  following.
- The wait is 15 s, down from 30 s: it holds the tool output, and on
  Gemini the later tools in the turn.
- Beyond 1,000 km of range a tilt happens in place instead of
  swinging thousands of km about the crosshair point.
- The tilt-nudge limits read the pivot pitch the motion starts from,
  including for a voice tilt from a tracked view, whose follow camera
  is released before it moves.
- move_camera's argument checks run before the flight wait, so a
  malformed call is refused at once.
- Tests: t.after cleanup in the fly-then-motion loop, the pitchDeg
  pin asserts the field before removing it, and the handoff-order
  pin follows the extracted argument checks.
---
 docs/CURRENT-STATE.md           |   2 +-
 src/cameraHandoff.test.mjs      |  11 ++-
 src/cameraTilt.test.mjs         |  32 +++++++
 src/cameraVerbs.js              | 165 +++++++++++++++++++-------------
 src/firstRunExperience.test.mjs |   1 +
 src/voice/gevActions.js         |  38 ++++++--
 src/voice/gevActions.test.mjs   |  96 +++++++++++++++++--
 7 files changed, 266 insertions(+), 79 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 5b3b88201..babe26a0b 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5372,7 +5372,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair (the tracked view excepted, which tilts in place), so the place stays centred and the heading is kept; pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. A zoom during a pivoting tilt scales the range it holds, as for orbit; a zoom in moves the camera along its view line and may take it below that height, as any zoom does, and the tilt then continues in place. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 30 s, so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered. Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. A zoom during a pivoting tilt scales the range it holds, as for orbit; a zoom in moves the camera along its view line and may take it below that height, as any zoom does, and the tilt then continues in place. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (following a later fly-to in the same reply that cancels it), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered. Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/cameraHandoff.test.mjs b/src/cameraHandoff.test.mjs
index 2c0d356b2..398c51c34 100644
--- a/src/cameraHandoff.test.mjs
+++ b/src/cameraHandoff.test.mjs
@@ -223,11 +223,20 @@ test('validated voice camera destinations share the UI navigation authority faca
     'move camera',
   );
   ordered(move, [
-    "if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion))",
+    'if (argsError) return argsError;',
     'const start = () => {',
     /const preserveCameraFlight =\s*motion === 'orbit'/,
     'runNavigation(start, { preserveCameraFlight })',
   ], 'move validation before handoff');
+  const moveArgs = body(
+    cameraVerbs,
+    /export function moveCameraArgsError\(args = \{\}\) \{([\s\S]*?)\n\}/,
+    'move camera argument checks',
+  );
+  assert.ok(
+    moveArgs.includes("if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion))"),
+    'unknown motions are refused before handoff',
+  );
 
   const route = body(
     cameraVerbs,
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index d70b07cbb..592098445 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -368,3 +368,35 @@ test('a zoom out during a far orbit never pulls the camera in', (t) => {
   h.tick();
   assert.ok(pivotRange(h) >= before - 1, `range fell to ${pivotRange(h)} m`);
 });
+
+test('from globe range a tilt happens in place', (t) => {
+  // A pivot 2,000 km out would swing the camera thousands of km.
+  const h = harness(t, { height: 2_000_000 });
+  const before = Cesium.Cartesian3.clone(h.camera.positionWC);
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
+  assert.ok(Cesium.Cartesian3.distance(h.camera.positionWC, before) < 1e-3);
+});
+
+test('a regional tilt-up nudge at the pivot limit refuses honestly', (t) => {
+  // 20 km up at -7°, the pivot 186 km out sits at -5.3°: already at the limit.
+  harness(t, { height: 20000, pitch: -7 });
+  const result = moveCamera({ motion: 'tilt', direction: 'up' });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /upper tilt limit/);
+  assert.equal(getActiveCameraMotion(), null);
+});
+
+test('a voice tilt from a tracked view judges its limit from the pivot it will use', (t) => {
+  const h = harness(t, { height: 20000, pitch: -7 });
+  h.viewer.trackedEntity = { id: 'tracked' };
+  // Voice releases the follow camera before the motion starts.
+  const release = (start) => {
+    h.viewer.trackedEntity = undefined;
+    return start();
+  };
+  const result = moveCamera({ motion: 'tilt', direction: 'up' }, release);
+  assert.equal(result.ok, false);
+  assert.match(result.error, /upper tilt limit/);
+});
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 7e94d0edf..1c12a9a74 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -57,6 +57,11 @@ const TILT_TO_DEG_S = 30;
  * range × sin|pitch|. It swings no lower than this; the rest tilts in place.
  */
 const TILT_MIN_CLEARANCE_M = 150;
+/**
+ * Beyond this range a pivot would swing the camera thousands of km about the
+ * crosshair point, so the tilt happens in place instead.
+ */
+const TILT_PIVOT_MAX_RANGE_M = 1_000_000;
 
 /* ── Route dolly: cinematic tuning ──────────────────────────────────────────
  * Every knob an owner may want to retune lives in this block. The shaping is
@@ -1322,11 +1327,15 @@ function tiltPivotPitchMax(range) {
 
 /**
  * Where a tilt starts. It swings about the ground under the crosshair so the
- * place stays centred; the follow camera owns a tracked view's frame.
+ * 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;
+ * voice releases it before moving, so a voice tilt still pivots).
  */
-function tiltStartFrame(cam) {
-  const target = _viewer.trackedEntity ? null : _getTarget?.(_viewer);
-  const pivot = target ? tiltPivot(cam, target) : null;
+function tiltStartFrame(cam, { releasesTracking = false } = {}) {
+  const tracked = Boolean(_viewer.trackedEntity) && !releasesTracking;
+  const target = tracked ? null : _getTarget?.(_viewer);
+  let pivot = target ? tiltPivot(cam, target) : null;
+  if (pivot && pivot.range > TILT_PIVOT_MAX_RANGE_M) pivot = null;
   return { target, pivot, from: pivot ? pivot.pitch : cam.pitch };
 }
 
@@ -1542,6 +1551,83 @@ export function initCameraVerbs(
   }
 }
 
+/**
+ * A tilt's angle: the one asked for, the default oblique view when a bare
+ * "tilt the camera" names neither angle nor direction, or null for a nudge.
+ */
+function requestedTiltPitch(args, direction) {
+  // Only a real number or numeric text: Number('') and Number(null) are 0,
+  // which would swing the camera to the horizon.
+  const raw = args.pitchDeg;
+  const requested =
+    typeof raw === 'number' || (typeof raw === 'string' && raw.trim() !== '')
+      ? Number(raw)
+      : NaN;
+  // 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;
+}
+
+/**
+ * Argument errors move_camera refuses whatever the camera is doing, so a
+ * caller holding a motion back behind a flight can refuse it before waiting.
+ * @param {Object} args
+ * @returns {Object|null} The refusal, or null when the arguments are usable.
+ */
+export function moveCameraArgsError(args = {}) {
+  const motion = String(args.motion || '').toLowerCase();
+  const direction = args.direction
+    ? String(args.direction).toLowerCase()
+    : null;
+  if (motion === 'stop') return null;
+  if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion)) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: `Unknown motion "${args.motion}" — use orbit, pan, tilt, rotate, rotate_globe, or stop.`,
+    };
+  }
+  if (
+    motion !== 'orbit' &&
+    motion !== 'rotate_globe' &&
+    (motion !== 'tilt' || requestedTiltPitch(args, direction) === null) &&
+    !['left', 'right', 'up', 'down'].includes(direction)
+  ) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: `${motion} needs a direction (left/right${motion !== 'rotate' ? '/up/down' : ''}).`,
+    };
+  }
+  if (motion === 'rotate' && !['left', 'right'].includes(direction)) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: 'rotate needs left or right.',
+    };
+  }
+  if (
+    motion === 'rotate_globe' &&
+    direction !== null &&
+    !['left', 'right'].includes(direction)
+  ) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: 'rotate_globe needs left or right.',
+    };
+  }
+  return null;
+}
+
 /**
  * move_camera implementation. Returns the house result shape; rejections are
  * plain-English `ok:false` errors.
@@ -1574,69 +1660,17 @@ export function moveCamera(args = {}, runNavigation = null) {
     };
     return typeof runNavigation === 'function' ? runNavigation(stop) : stop();
   }
-  if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion)) {
-    return {
-      ok: false,
-      action: 'move_camera',
-      error: `Unknown motion "${args.motion}" — use orbit, pan, tilt, rotate, rotate_globe, or stop.`,
-    };
-  }
-  // Tilt to an angle: the one asked for, or a default oblique view when a
-  // bare "tilt the camera" names neither angle nor direction.
-  let tiltToPitch = null;
-  if (motion === 'tilt') {
-    // Only a real number or numeric text: Number('') and Number(null) are 0,
-    // which would swing the camera to the horizon.
-    const raw = args.pitchDeg;
-    const requested =
-      typeof raw === 'number' || (typeof raw === 'string' && raw.trim() !== '')
-        ? Number(raw)
-        : NaN;
-    // 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))
-      tiltToPitch = Cesium.Math.clamp(
-        Cesium.Math.toRadians(-Math.abs(requested)),
-        PITCH_MIN,
-        PITCH_MAX,
-      );
-    else if (direction === null)
-      tiltToPitch = Cesium.Math.toRadians(TILT_DEFAULT_PITCH_DEG);
-  }
-  if (
-    motion !== 'orbit' &&
-    motion !== 'rotate_globe' &&
-    tiltToPitch === null &&
-    !['left', 'right', 'up', 'down'].includes(direction)
-  ) {
-    return {
-      ok: false,
-      action: 'move_camera',
-      error: `${motion} needs a direction (left/right${motion !== 'rotate' ? '/up/down' : ''}).`,
-    };
-  }
-  if (motion === 'rotate' && !['left', 'right'].includes(direction)) {
-    return {
-      ok: false,
-      action: 'move_camera',
-      error: 'rotate needs left or right.',
-    };
-  }
-  if (
-    motion === 'rotate_globe' &&
-    direction !== null &&
-    !['left', 'right'].includes(direction)
-  ) {
-    return {
-      ok: false,
-      action: 'move_camera',
-      error: 'rotate_globe needs left or right.',
-    };
-  }
+  const argsError = moveCameraArgsError(args);
+  if (argsError) return argsError;
+  const tiltToPitch =
+    motion === 'tilt' ? requestedTiltPitch(args, direction) : null;
+  // A managed (voice) navigation releases the follow camera before start(),
+  // so checks made now must judge from the frame start() will see.
+  const releasesTracking = typeof runNavigation === 'function';
   if (motion === 'tilt' && tiltToPitch !== null) {
     // Judge from the pitch the motion will start at: the pivot's, which at
     // regional range is a degree or two shallower than the camera's.
-    const { from } = tiltStartFrame(_viewer.camera);
+    const { from } = tiltStartFrame(_viewer.camera, { releasesTracking });
     if (Math.abs(tiltToPitch - from) < Cesium.Math.toRadians(0.5)) {
       return {
         ok: true,
@@ -1661,7 +1695,8 @@ export function moveCamera(args = {}, runNavigation = null) {
   } 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;
+    // The clamp reads the pitch the motion starts from.
+    const pitch = tiltStartFrame(_viewer.camera, { releasesTracking }).from;
     if (direction === 'up' && pitch >= PITCH_MAX - Cesium.Math.toRadians(0.5)) {
       return {
         ok: false,
diff --git a/src/firstRunExperience.test.mjs b/src/firstRunExperience.test.mjs
index 9ca5262a4..60a37f73c 100644
--- a/src/firstRunExperience.test.mjs
+++ b/src/firstRunExperience.test.mjs
@@ -1018,6 +1018,7 @@ test('the voice TOOL SCHEMA matches the pinned contract — the mission mapping
   // the legacy camera fields to keep the pin.
   const camera = legacyTools.find((tool) => tool.name === 'move_camera')
     .parameters.properties;
+  assert.equal(camera.pitchDeg.type, 'number');
   delete camera.pitchDeg;
   camera.direction.description =
     'Required for pan/tilt/rotate; orbit/rotate_globe default right.';
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index 926876f6d..66199e277 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -48,6 +48,7 @@ import {
   interruptCameraMotion,
   adjustOrbitRange,
   manualCameraInputCount,
+  moveCameraArgsError,
 } from '../cameraVerbs.js';
 import * as defaultFloorServices from '../data/groundFloor.js';
 import { isPickedWorldPosition } from '../data/scenePick.js';
@@ -1198,8 +1199,26 @@ export function createGevActionRunner({
         voiceFlight &&
         !voiceFlight.done
       ) {
-        const flight = voiceFlight;
-        const status = await waitForVoiceFlight(flight, runOptions.signal);
+        // Bad arguments are refused now, not after waiting on the flight.
+        const argsError = moveCameraArgsError(args);
+        if (argsError) return argsError;
+        const deadline = Date.now() + VOICE_FLIGHT_WAIT_MS;
+        let flight = voiceFlight;
+        let status = await waitForVoiceFlight(
+          flight,
+          runOptions.signal,
+          deadline,
+        );
+        // A later fly-to in the same reply cancels this one: follow it to
+        // where the camera lands, within the same deadline.
+        while (status === 'cancelled' && voiceFlight !== flight && current()) {
+          flight = voiceFlight;
+          status = await waitForVoiceFlight(
+            flight,
+            runOptions.signal,
+            deadline,
+          );
+        }
         if (!current())
           return { ok: false, action: 'move_camera', cancelled: true };
         if (status !== 'arrived')
@@ -2759,8 +2778,12 @@ function trackVoiceFlight(inputCount = manualCameraInputCount()) {
   return flight;
 }
 
-/** Longest a motion waits for a flight (geocode plus flight) before giving up. */
-const VOICE_FLIGHT_WAIT_MS = 30_000;
+/**
+ * Longest a motion waits for its flight (geocode plus flight, which is about
+ * 2 s) before giving up. The wait also holds the tool output, and on Gemini
+ * the later tools in the turn.
+ */
+const VOICE_FLIGHT_WAIT_MS = 15_000;
 
 /**
  * Motions that act on the place the camera ends up at, so one sent beside a
@@ -2775,7 +2798,7 @@ const VOICE_FLIGHT_WAITING_MOTIONS = new Set([
 ]);
 
 /** Wait for a voice flight to end; 'timeout' or 'aborted' if it does not. */
-function waitForVoiceFlight(flight, signal) {
+function waitForVoiceFlight(flight, signal, deadline) {
   if (signal?.aborted) return Promise.resolve('aborted');
   return new Promise((resolve) => {
     const finish = (status) => {
@@ -2784,7 +2807,10 @@ function waitForVoiceFlight(flight, signal) {
       resolve(status);
     };
     const onAbort = () => finish('aborted');
-    const timer = setTimeout(() => finish('timeout'), VOICE_FLIGHT_WAIT_MS);
+    const timer = setTimeout(
+      () => finish('timeout'),
+      Math.max(0, deadline - Date.now()),
+    );
     signal?.addEventListener?.('abort', onAbort, { once: true });
     flight.ended.then(finish);
   });
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index e4bffb26b..08af6b288 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -347,7 +347,8 @@ for (const motion of [
   { motion: 'pan', direction: 'left' },
   { motion: 'rotate', direction: 'right' },
 ]) {
-  test(`${motion.motion} in the same reply as a fly-to waits for the flight to land`, async () => {
+  test(`${motion.motion} in the same reply as a fly-to waits for the flight to land`, async (t) => {
+    t.after(() => interruptCameraMotion('test-cleanup'));
     const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
     const runner = createGevActionRunner({
       viewer,
@@ -368,10 +369,10 @@ for (const motion of [
     const result = await moved;
     assert.equal(result.ok, true);
     assert.equal(result.motion, motion.motion);
-    interruptCameraMotion('test-cleanup');
   });
 
-  test(`${motion.motion} waits through a geocoded fly-to search, then for its flight`, async () => {
+  test(`${motion.motion} waits through a geocoded fly-to search, then for its flight`, async (t) => {
+    t.after(() => interruptCameraMotion('test-cleanup'));
     const { viewer, styleManager } = tiltAfterFlightHarness();
     let finishSearch;
     let landFlight;
@@ -399,7 +400,6 @@ for (const motion of [
     landFlight();
     assert.equal((await moved).ok, true);
     assert.equal(getActiveCameraMotion()?.kind, motion.motion);
-    interruptCameraMotion('test-cleanup');
   });
 
   test(`${motion.motion} waiting on a flight that never lands is not run`, async () => {
@@ -470,7 +470,8 @@ test('a drag during the first of two chained fly-tos still drops the queued moti
   assert.match(result.error, /moved the camera during the flight/);
 });
 
-test('input before a fly-to does not drop the motion queued behind it', async () => {
+test('input before a fly-to does not drop the motion queued behind it', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
   const { viewer, styleManager, flights } = tiltAfterFlightHarness();
   const canvasListeners = new Map();
   viewer.scene.canvas.addEventListener = (type, listener) => {
@@ -486,7 +487,90 @@ test('input before a fly-to does not drop the motion queued behind it', async ()
   const moved = runner('move_camera', { motion: 'orbit' });
   flights[0].complete();
   assert.equal((await moved).ok, true);
-  interruptCameraMotion('test-cleanup');
+});
+
+test('a motion follows a later fly-to in the same reply that cancels its flight', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'orbit' });
+  const movedDone = settledYet(moved);
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  // The second flight supersedes the first, as Cesium's flyTo does.
+  flights[0].cancel();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(movedDone(), false, 'the orbit must wait for the second flight');
+  flights[1].complete();
+  const result = await moved;
+  assert.equal(result.ok, true);
+  assert.equal(result.motion, 'orbit');
+});
+
+test('a stale motion does not follow a newer reply\'s fly-to', async () => {
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  let live = true;
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'orbit' }, { isCurrent: () => live });
+  // A newer reply takes over and flies elsewhere; this reply is stale.
+  live = false;
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  flights[0].cancel();
+  // The newer flight never lands here: following it would hold this answer.
+  const result = await Promise.race([
+    moved,
+    new Promise((resolve) => setTimeout(() => resolve('still waiting'), 50)),
+  ]);
+  assert.notEqual(result, 'still waiting');
+  assert.equal(result.ok, false);
+  assert.equal(result.cancelled, true);
+});
+
+test('a motion gives up on a flight that has not landed in 15 s', async (t) => {
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
+  const moved = runner('move_camera', { motion: 'orbit' });
+  const movedDone = settledYet(moved);
+  await Promise.resolve();
+  t.mock.timers.tick(14_999);
+  await Promise.resolve();
+  assert.equal(movedDone(), false);
+  t.mock.timers.tick(1);
+  const result = await moved;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /did not arrive/);
+});
+
+test('bad move_camera arguments are refused without waiting for a flight', async () => {
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'pan' });
+  const movedDone = settledYet(moved);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(movedDone(), true, 'the refusal must not wait on the flight');
+  const result = await moved;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /needs a direction/);
 });
 
 test('stop does not wait for a voice flight', async () => {

From 2c936ae131ed8b24abfc45cc861c8de75df50061 Mon Sep 17 00:00:00 2001
From: Said Turksever <asturksever@gmail.com>
Date: Tue, 3 Nov 2026 16:26:45 +0000
Subject: [PATCH 17/71] docs: correct hidden-contact rotation interval

---
 docs/CURRENT-STATE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 5be325222..2a6dc5fdb 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -4989,7 +4989,7 @@ silently demoting every later lookup for the session.
 
 ### Motion & Symbology Correctness (June 10, 2026)
 
-- **Flights (commercial + military)** render one poll interval behind real time (30s/15s) and interpolate between two known feed-stamped fixes (OpenSky `time_position`; adsb.lol `receipt − seen_pos`). The display latency is an intentional product decision — do not "fix" it away. The fleet dead-reckons at ~12Hz (1m² write gating); a contact already hidden behind the horizon whose last position still is re-reckons on a staggered one-in-12-ticks rotation (about once a second) instead, so the worldwide feed's ~13k contacts no longer cost a full pass when well under 1% are on screen. Anything that position puts in view, and any contact with a fleet model, takes the full pass immediately, and hidden-inclusive proximity queries read positions at most about a second old; aircraft get a 3-poll grace period (faded icon) before removal. When a position epoch pauses, both layers coast for at least 60 seconds of contact grace with an absolute five-minute ceiling. Source backoff marks each contact and the cockpit `STALE`; the cockpit then holds the exact layer position instead of continuing inertial flight. Repeated-position kinematic changes create a forward-only synthetic fix rather than mutating history, and grounded history is lifted only when no owned 3D model already controls its datum. A nominally successful worldwide OpenSky response whose own snapshot epoch is more than two minutes old prefers the existing 250-nm viewport-scoped adsb.lol fallback and labels the source/coverage accordingly when that upstream is available. If the fallback is also unavailable, the layer's freshness/error fields use the source epoch—never the cache receipt time—so the UI reports an old snapshot rather than “just now.”
+- **Flights (commercial + military)** render one poll interval behind real time (30s/15s) and interpolate between two known feed-stamped fixes (OpenSky `time_position`; adsb.lol `receipt − seen_pos`). The display latency is an intentional product decision — do not "fix" it away. The fleet dead-reckons at ~12Hz (1m² write gating); a contact already hidden behind the horizon whose last position still is re-reckons on a staggered one-in-13-ticks rotation (about once a second) instead, so the worldwide feed's ~13k contacts no longer cost a full pass when well under 1% are on screen. Anything that position puts in view, and any contact with a fleet model, takes the full pass immediately, and hidden-inclusive proximity queries read positions at most about a second old; aircraft get a 3-poll grace period (faded icon) before removal. When a position epoch pauses, both layers coast for at least 60 seconds of contact grace with an absolute five-minute ceiling. Source backoff marks each contact and the cockpit `STALE`; the cockpit then holds the exact layer position instead of continuing inertial flight. Repeated-position kinematic changes create a forward-only synthetic fix rather than mutating history, and grounded history is lifted only when no owned 3D model already controls its datum. A nominally successful worldwide OpenSky response whose own snapshot epoch is more than two minutes old prefers the existing 250-nm viewport-scoped adsb.lol fallback and labels the source/coverage accordingly when that upstream is available. If the fallback is also unavailable, the layer's freshness/error fields use the source epoch—never the cache receipt time—so the UI reports an old snapshot rather than “just now.”
 - **World-space headings at every angle** (`src/data/iconOrientation.js`): aircraft/vessel icon rotation uses the camera right/up basis per tick (alignedAxis always ZERO), which is exact at screen center and for orthographic/nadir views and remains stable through >180° tracked orbits. Perspective rays vary across the viewport, so off-center contacts at oblique pitch can diverge from an exact finite-difference window projection; a regression test pins that known regime, and field evidence decides whether to adopt exact projection with the basis method as fallback. Fleet rotations refresh on camera-pose change; tracked entities per frame. Billboards are horizon-culled via a shared EllipsoidalOccluder.
 - **Military/OpenSky reconciliation** (`src/data/militaryRegistry.js`): known-military ICAOs render amber in the flights layer (60s self-poll of the cached mil endpoint when the military layer is off) and are suppressed there while the military layer renders them.
 - **Satellites**: 838-sat core catalog (stations/visual/GPS/GLONASS/Galileo/GEO), tracking lands ~726km out via `viewFrom` (tracked entity owns a point graphic so the tracking camera engages), rings realign via primitive modelMatrix (no per-second rebuild flicker), optional `setParams({catalog:'dense'})` Starlink mode.

From fdecc8c5818e8ad4d1a0d09749472b76957e69f1 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Tue, 3 Nov 2026 22:23:38 +0530
Subject: [PATCH 18/71] Keep the tilt clearance through a zoom in

A zoom in during a pivoting tilt stops at the range that keeps the camera 150 m above the pivot at its current pitch. A zoom that moves the range by less than half a metre (at the clearance, the 80 m floor or the 5,000 km cap) now answers not zoomed instead of ok, and a tilt reports tiltRangeAdjusted rather than orbitRadiusAdjusted.
---
 docs/CURRENT-STATE.md   |  2 +-
 src/cameraTilt.test.mjs | 49 ++++++++++++++++++++++++++++++++++++++---
 src/cameraVerbs.js      | 24 +++++++++++++-------
 src/voice/gevActions.js | 18 ++++++++++++---
 4 files changed, 78 insertions(+), 15 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 5eb025b1f..55a46973f 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5381,7 +5381,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. A zoom during a pivoting tilt scales the range it holds, as for orbit; a zoom in moves the camera along its view line and may take it below that height, as any zoom does, and the tilt then continues in place. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (following a later fly-to in the same reply that cancels it), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered. Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor or the 5,000 km cap) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (following a later fly-to in the same reply that cancels it), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered. Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index 592098445..58cdbc05f 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -8,6 +8,7 @@ import {
   interruptCameraMotion,
   moveCamera,
 } from './cameraVerbs.js';
+import { createGevActionRunner } from './voice/gevActions.js';
 
 const radians = Cesium.Math.toRadians;
 const degrees = Cesium.Math.toDegrees;
@@ -238,7 +239,11 @@ test('a zoom during a pivoting tilt changes the range it holds', (t) => {
   );
   h.tick();
   const before = pivotRange(h);
-  assert.equal(adjustOrbitRange(0.5), true, 'the tilt must take the zoom');
+  assert.deepEqual(
+    adjustOrbitRange(0.5),
+    { kind: 'tilt', changed: true },
+    'the tilt must take the zoom',
+  );
   for (let i = 0; i < 5; i += 1) h.tick();
   // The next frame's lookAt must not put the old range back.
   assert.ok(
@@ -250,7 +255,7 @@ test('a zoom during a pivoting tilt changes the range it holds', (t) => {
 test('a zoom with no pivot to hold is left to the camera', (t) => {
   harness(t, { pivot: false });
   moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
-  assert.equal(adjustOrbitRange(0.5), false);
+  assert.equal(adjustOrbitRange(0.5), null);
 });
 
 test('a pivot tilt toward the horizon keeps its clearance above the ground', (t) => {
@@ -364,11 +369,49 @@ test('a zoom out during a far orbit never pulls the camera in', (t) => {
   h.tick();
   const before = pivotRange(h);
   assert.ok(before > 5_000_000, `range ${before} m`);
-  assert.equal(adjustOrbitRange(2.4), true);
+  assert.deepEqual(adjustOrbitRange(2.4), { kind: 'orbit', changed: false });
   h.tick();
   assert.ok(pivotRange(h) >= before - 1, `range fell to ${pivotRange(h)} m`);
 });
 
+test('a zoom in during a pivot tilt stops at the clearance', (t) => {
+  // 400 m of range at -40°, then "zoom in a lot" twice: unfloored, that left
+  // the camera about 107 m up, then at the 80 m zoom floor.
+  const h = harness(t, { height: 400 });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  while (pitchDeg(h.camera) < -40) h.tick();
+  assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: true });
+  // At -40° the floor is 150 / sin 40° ≈ 233 m, which the first zoom reached.
+  assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: false });
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
+  }
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('a voice zoom during a pivot tilt says what it changed', async (t) => {
+  const h = harness(t, { height: 400 });
+  const runner = createGevActionRunner({
+    viewer: h.viewer,
+    styleManager: {},
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  h.tick();
+  const zoom = { direction: 'in', amount: 'lot' };
+  const first = await runner('adjust_camera_zoom', zoom);
+  assert.equal(first.ok, true);
+  assert.equal(first.tiltRangeAdjusted, true);
+  assert.equal('orbitRadiusAdjusted' in first, false);
+  // 400 m → 167 m → the 150 m clearance; a third zoom in moves nothing, and
+  // says so.
+  assert.equal((await runner('adjust_camera_zoom', zoom)).ok, true);
+  const third = await runner('adjust_camera_zoom', zoom);
+  assert.equal(third.ok, false);
+  assert.match(third.error, /tilt is already at its closest range/);
+});
+
 test('from globe range a tilt happens in place', (t) => {
   // A pivot 2,000 km out would swing the camera thousands of km.
   const h = harness(t, { height: 2_000_000 });
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 1c12a9a74..16888d73e 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -1932,19 +1932,27 @@ export function moveCamera(args = {}, runNavigation = null) {
  * fight the per-frame lookAt (field test: "zoom out did literally nothing").
  * A tilt swinging about its pivot holds a range the same way.
  * @param {number} factor  >1 zooms out (radius grows), <1 zooms in.
- * @returns {boolean} true when an orbit or pivoting tilt consumed the zoom.
+ * @returns {{kind: string, changed: boolean}|null} the motion that consumed
+ *   the zoom, and whether its range moved; null when none did.
  */
 export function adjustOrbitRange(factor) {
   if (!_active || !['orbit', 'tilt'].includes(_active.kind) || !_active.hpr)
-    return false;
-  // The limits never move a view the wrong way: a zoom in leaves a closer
-  // view in place, and a zoom out leaves a farther one.
-  const range = _active.hpr.range;
-  _active.hpr.range = Math.max(
-    Math.min(80, range),
+    return null;
+  // A tilt's zoom in stops at the range that keeps its clearance. The limits
+  // never move a view the wrong way: a zoom in leaves a closer view in place,
+  // and a zoom out leaves a farther one.
+  const { kind, hpr } = _active;
+  const floor =
+    kind === 'tilt'
+      ? Math.max(80, TILT_MIN_CLEARANCE_M / Math.abs(Math.sin(hpr.pitch)))
+      : 80;
+  const range = hpr.range;
+  hpr.range = Math.max(
+    Math.min(floor, range),
     Math.min(Math.max(5_000_000, range), range * factor),
   );
-  return true;
+  // Under half a metre counts as not moved, as for a plain zoom.
+  return { kind, changed: Math.abs(hpr.range - range) >= 0.5 };
 }
 
 /**
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index 66199e277..e851827df 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -411,13 +411,25 @@ export function createGevActionRunner({
       const zoomOut = String(args.direction || '').toLowerCase() === 'out';
       const amt = String(args.amount || 'medium').toLowerCase();
       const factor = { little: 1.25, medium: 1.6, lot: 2.4 }[amt] || 1.6;
-      if (adjustOrbitRange(zoomOut ? factor : 1 / factor)) {
+      const held = adjustOrbitRange(zoomOut ? factor : 1 / factor);
+      if (held) {
+        const direction = zoomOut ? 'out' : 'in';
+        if (!held.changed) {
+          return {
+            ok: false,
+            action: 'adjust_camera_zoom',
+            direction,
+            amount: amt,
+            error: `Not zoomed: the ${held.kind} is already at its ${zoomOut ? 'farthest' : 'closest'} range.`,
+          };
+        }
         return {
           ok: true,
           action: 'adjust_camera_zoom',
-          direction: zoomOut ? 'out' : 'in',
+          direction,
           amount: amt,
-          orbitRadiusAdjusted: true,
+          [held.kind === 'tilt' ? 'tiltRangeAdjusted' : 'orbitRadiusAdjusted']:
+            true,
         };
       }
     }

From 99520b529c4d1a3a4adc7268ca935d66bcdba923 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Tue, 3 Nov 2026 20:02:54 +0530
Subject: [PATCH 19/71] fix(camera): keep the globe in view from orbit

From the whole-globe view the camera could end up facing empty space with
only stars on screen. Cesium's free look (Shift+drag) turns the camera in
place, and from 18,000 km the planet's edge is only about 15 degrees from
nadir, so a few drags turned it out of frame. The rolled pose was then
saved into the share hash, so a reload or shared link opened on stars too.

- Allow free look only below 1,000 km. Orbit, tilt and zoom are unchanged.
- Measure how much of the frame shows the planet's surface by casting a
  32x18 grid of view rays at the WGS84 ellipsoid. While the scope mask is
  on (the default) only the rays inside its keyhole count, since the mask
  hides or dims the rest of the frame.
- When a camera move ends above 1,000 km with no ray on the surface, turn
  straight down at the same position and heading. Limb glow and a sliver
  up to about one grid cell thick can count as out of view. The end of a
  move comes from Cesium's moveEnd and from a check of its own that
  samples the pose every 250 ms after moveStart and acts once it has held
  for half a second: at some of these poses the camera drifts by a
  rounding error every frame, so Cesium never sees it stop and never
  raises moveEnd. The zoom-out guard from #1522 keeps wheel and pinch
  zoom-outs in view; this catches the other ways a move can end looking
  away, such as a saved or shared view that did, or a
  drag that Cesium turns into an in-place look below its 7,500 km
  trackball height (one that starts on the stars, or a tilt drag with the
  screen centre off the planet). Views with more surface, tracked or
  locked cameras and the 2D and Columbus modes are left alone.
- Voice tilt and in-place turns of a free 3D globe camera above 1,000 km
  stop when about a tenth of the frame still shows the planet (or about as
  much as it showed when it started, two grid cells of sampling noise
  allowed), never below about 1% of the visible frame; a view that already
  shows less only keeps or gains what it has. A turn that cannot go half a
  degree further without crossing that limit is refused with a reason
  instead of reported as done, and a turn it accepts turns at least that
  half degree. A turn that keeps or gains surface is not refused, even
  after the window has been resized, except that near the limit, where the
  planet's edge crosses the sample grid, sampling wobble can occasionally
  refuse one (most often above about 15,000 km and on phone or ultrawide
  frames); nothing then turns away from the planet. A turn that starts
  where the last voice turn left the camera keeps that turn's limit, or a
  higher one if the planet now fills more, so repeating the request does
  not take any more; once anything else has moved or turned the camera, a
  turn is measured from what is on screen. A request made 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 frame measure and the look-step limit live in src/globeInView.js,
shared by the viewer and the voice camera verbs.
---
 docs/CURRENT-STATE.md            |  40 +++
 scripts/package-boundaries.json  |   5 +
 src/app/application.test.mjs     | 431 ++++++++++++++++++++++++++-
 src/app/scene.js                 |  11 +
 src/app/viewer.js                | 172 +++++++++++
 src/cameraGlobeRotation.test.mjs | 491 +++++++++++++++++++++++++++++++
 src/cameraVerbs.js               | 179 ++++++++++-
 src/globeInView.js               | 167 +++++++++++
 8 files changed, 1491 insertions(+), 5 deletions(-)
 create mode 100644 src/globeInView.js

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 87b918a4e..3fde50e05 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -65,6 +65,46 @@ settling. Oblique views below 300 km are left alone.
 `QA_BASE_URL=http://localhost:4173 node scripts/qa-zoom-out-guard.mjs` exercises
 the real browser controller at desktop and phone widths with keyless fixtures.
 
+Cesium's free look (Shift+drag, which turns the camera in place) works only
+below 1,000 km. Above that height a few drags could turn the whole planet out of
+frame and leave only stars, so Shift+drag does nothing there. Orbit, tilt and
+zoom are unchanged at every height. 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 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 turn that cannot go half a degree further without crossing that
+limit is refused with a reason instead of reported as done, and a turn it
+accepts turns at least that half degree. A turn that keeps or gains surface is
+not refused, even after the window has been resized, except that near the limit,
+where the planet's edge crosses the sample grid, sampling wobble can
+occasionally refuse one (most often above about 15,000 km and on phone or
+ultrawide frames); nothing then turns away from the planet. A turn that starts
+where the last voice turn left the camera keeps that turn's limit, or a higher
+one if the planet now fills more, so repeating the request does not take any
+more; once anything else has moved or turned the camera, a turn is measured from
+what is on screen. When a camera move ends above 1,000 km with no ray on the
+surface, the camera turns straight down at the same position and heading. The
+end of a move is taken from Cesium's move-end event and from a check of its own
+that samples the pose every 250 ms after a move starts and acts once it has held
+for half a second, because at some of these poses the camera drifts by a
+rounding error every frame and Cesium never sees it stop. That check keeps
+watching until move-end arrives, recovering once after each move that comes to
+rest, and gives up five minutes after the camera last moved. Limb glow, and a
+surface sliver up to about one grid cell thick (some 50 px on a 900 px tall
+frame), can count as out of view. The zoom-out guard above keeps wheel and
+pinch zoom-outs in view; this catches the other ways a move can end looking
+away, such as a saved or shared view that did, or a drag
+that Cesium turns into an in-place look below its 7,500 km trackball height (one
+that starts on the stars, or a tilt drag with the screen centre off the planet).
+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 and the 2D and
+Columbus modes. 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.
+
 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
diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json
index 44c481152..b029af646 100644
--- a/scripts/package-boundaries.json
+++ b/scripts/package-boundaries.json
@@ -158,6 +158,7 @@
     "modules": [
       "src/app/viewer.js",
       "src/app/atmosphereCompat.js",
+      "src/globeInView.js",
       "src/sky/starrySky.js",
       "src/sky/stars.js",
       "src/data/bundledJson.js",
@@ -2297,6 +2298,7 @@
       "src/camera.js",
       "src/cameraGroundGuard.js",
       "src/cameraVerbs.js",
+      "src/globeInView.js",
       "src/cctvFocusPolicy.js",
       "src/cctvFocusRequest.js",
       "src/celestialRing.js",
@@ -3604,6 +3606,9 @@
       "src/annotations/worldAnnotationRenderer.js",
       "src/cameraGroundGuard.js",
       "src/cameraVerbs.js",
+      "src/globeInView.js",
+      "src/scopeMaskPolicy.js",
+      "src/scopeMask.js",
       "src/services/groundFloor.js",
       "src/data/routeSteps.js",
       "src/layers/directions/index.js",
diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs
index 3e9079b87..401eefa0b 100644
--- a/src/app/application.test.mjs
+++ b/src/app/application.test.mjs
@@ -2,7 +2,20 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { createApplication } from './application.js';
-import { installTrackpadPinchZoom } from './viewer.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';
 
 const phases = ['Scene', 'Controls', 'Data', 'Tools'];
 function fixture(overrides = {}) {
@@ -343,3 +356,419 @@ test('trackpad pinch falls back to the original event when relay construction fa
   assert.equal(event.propagationStopped, false);
   assert.equal(f.relayed.length, 0);
 });
+
+function freeLookFixture({ enableLook = true, height = 0 } = {}) {
+  const listeners = new Set();
+  const controller = { enableLook };
+  const camera = { positionCartographic: { height } };
+  const viewer = {
+    camera,
+    scene: {
+      screenSpaceCameraController: controller,
+      preUpdate: {
+        addEventListener(listener) {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+      },
+    },
+  };
+  const frame = (nextHeight) => {
+    camera.positionCartographic = { height: nextHeight };
+    for (const listener of listeners) listener();
+  };
+  return { viewer, controller, listeners, frame };
+}
+
+test('free look follows camera height and is restored on dispose', () => {
+  const f = freeLookFixture({ height: 500 });
+  const dispose = installFreeLookHeightLimit(f.viewer);
+  assert.equal(f.controller.enableLook, true);
+
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS + 1);
+  assert.equal(f.controller.enableLook, false);
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS);
+  assert.equal(f.controller.enableLook, true);
+  f.frame(Number.NaN);
+  assert.equal(f.controller.enableLook, true);
+
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
+  dispose();
+  dispose();
+  assert.equal(f.controller.enableLook, true);
+  assert.equal(f.listeners.size, 0);
+});
+
+test('free look stays off when the viewer had it disabled', () => {
+  const f = freeLookFixture({ enableLook: false, height: 500 });
+  installFreeLookHeightLimit(f.viewer);
+  f.frame(10);
+  assert.equal(f.controller.enableLook, false);
+});
+
+// A real Cesium camera on the smallest scene its constructor reads, so the
+// frustum test runs on Cesium's own view math rather than a stub.
+function realCamera({ width = 1600, height = 900, mode } = {}) {
+  const scene = {
+    canvas: { clientWidth: width, clientHeight: height },
+    drawingBufferWidth: width,
+    drawingBufferHeight: height,
+    mapProjection: new Cesium.GeographicProjection(),
+    mode: mode ?? Cesium.SceneMode.SCENE3D,
+    pixelRatio: 1,
+    ellipsoid: Cesium.Ellipsoid.WGS84,
+    mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
+    renders: 0,
+    requestRender() {
+      this.renders += 1;
+    },
+  };
+  const camera = new Cesium.Camera(scene);
+  camera.frustum.aspectRatio = width / height;
+  return { camera, scene, viewer: { camera, scene } };
+}
+
+function aim(
+  camera,
+  { lon = -94.69, lat = 18.87, alt, heading = 0, pitch, roll = 0 },
+) {
+  camera.setView({
+    destination: Cesium.Cartesian3.fromDegrees(lon, lat, alt),
+    orientation: {
+      heading: Cesium.Math.toRadians(heading),
+      pitch: Cesium.Math.toRadians(pitch),
+      roll: Cesium.Math.toRadians(roll),
+    },
+  });
+}
+
+const reportedStuckView = {
+  alt: 17_996_811,
+  heading: 180,
+  pitch: -42,
+  roll: 180,
+};
+// Oblique poses that still show part of the planet: Director recipe shots
+// (Global Flights Radar, Omniscience Pullback) and a voice tilt from orbit.
+const partialGlobeViews = [
+  { lon: -30, lat: 20, alt: 19_000_000, pitch: -65 },
+  { lon: 2, lat: 46, alt: 8_000_000, pitch: -52 },
+  { lon: 110, lat: 20, alt: 9_500_000, pitch: -66 },
+  { lon: 0, lat: 0, alt: 2_000_000, pitch: -30 },
+];
+
+// Stars and a few pixels of limb, no surface: where a frame limit measured
+// against a sphere of the planet's largest radius used to stop a voice tilt.
+const limbOnlyView = { alt: 18_000_000, pitch: -56.75 };
+
+/**
+ * An oracle independent of the code under test: the share of an 80×45 grid of
+ * Cesium pick rays across the canvas that hit the ellipsoid surface.
+ */
+function surfacePixelShare(camera, width, height, { keyhole = false } = {}) {
+  const radius = (KEYHOLE_OUTER_RADIUS * height) / 2;
+  let hits = 0;
+  let counted = 0;
+  for (let row = 0; row < 45; row += 1) {
+    for (let column = 0; column < 80; column += 1) {
+      const x = ((column + 0.5) * width) / 80;
+      const y = ((row + 0.5) * height) / 45;
+      if (keyhole && Math.hypot(x - width / 2, y - height / 2) > radius)
+        continue;
+      counted += 1;
+      const ray = camera.getPickRay(new Cesium.Cartesian2(x, y));
+      if (Cesium.IntersectionTests.rayEllipsoid(ray, Cesium.Ellipsoid.WGS84))
+        hits += 1;
+    }
+  }
+  return hits / counted;
+}
+
+test('the globe is out of frame only when no surface is on screen', () => {
+  const cases = [
+    [reportedStuckView, 1225, 923, true],
+    [limbOnlyView, 1600, 900, true],
+    [{ alt: 17_996_811, pitch: -90 }, 1225, 923, false],
+    ...partialGlobeViews.map((view) => [view, 1600, 900, false]),
+  ];
+  for (const [view, width, height, out] of cases) {
+    const { camera } = realCamera({ width, height });
+    aim(camera, view);
+    const label = JSON.stringify(view);
+    assert.equal(globeOutOfFrame(camera), out, label);
+    assert.equal(surfacePixelShare(camera, width, height) === 0, out, label);
+    assert.ok(
+      Math.abs(
+        globeFrameShare(camera) - surfacePixelShare(camera, width, height),
+      ) < 0.03,
+      `${label}: the frame share matches the pick-ray oracle`,
+    );
+  }
+});
+
+test('a move that ends with the globe out of frame turns back to nadir', () => {
+  const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
+  const dispose = installGlobeInViewRecovery(viewer);
+  aim(camera, reportedStuckView);
+  const position = Cesium.Cartesian3.clone(camera.positionWC);
+  const heading = camera.heading;
+  camera.moveEnd.raiseEvent();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+  assert.ok(Cesium.Math.equalsEpsilon(camera.heading, heading, 1e-6));
+  assert.ok(
+    Cesium.Cartesian3.equalsEpsilon(camera.positionWC, position, 0, 1e-3),
+  );
+  assert.equal(globeOutOfFrame(camera), false);
+  assert.equal(scene.renders, 1);
+
+  // Looking up near the ground, then zoomed out past the limit.
+  aim(camera, { alt: 3_834_000, pitch: 10 });
+  camera.moveEnd.raiseEvent();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+
+  // Only the limb on a 16:9 screen still counts as lost.
+  const wide = realCamera({ width: 1600, height: 900 });
+  const disposeWide = installGlobeInViewRecovery(wide.viewer);
+  aim(wide.camera, limbOnlyView);
+  wide.camera.moveEnd.raiseEvent();
+  assert.ok(Cesium.Math.equalsEpsilon(wide.camera.pitch, -Math.PI / 2, 1e-6));
+  disposeWide();
+
+  dispose();
+  dispose();
+  aim(camera, reportedStuckView);
+  camera.moveEnd.raiseEvent();
+  assert.equal(globeOutOfFrame(camera), true, 'disposed recovery is inert');
+});
+
+// True when a moveEnd leaves the camera's view direction as it was.
+function moveEndKeepsView(camera) {
+  const direction = Cesium.Cartesian3.clone(camera.directionWC);
+  camera.moveEnd.raiseEvent();
+  return Cesium.Cartesian3.equalsEpsilon(camera.directionWC, direction, 1e-9);
+}
+
+test('globe recovery leaves partial, low, locked and 2D views alone', () => {
+  for (const view of partialGlobeViews) {
+    const { camera, viewer } = realCamera();
+    installGlobeInViewRecovery(viewer);
+    aim(camera, view);
+    assert.ok(moveEndKeepsView(camera), JSON.stringify(view));
+  }
+
+  const low = realCamera();
+  installGlobeInViewRecovery(low.viewer);
+  aim(low.camera, { alt: 900_000, pitch: 85 });
+  assert.equal(globeOutOfFrame(low.camera), true);
+  assert.ok(moveEndKeepsView(low.camera), 'below the limit');
+
+  // Locked on a point in space, between it and the planet, facing away.
+  const locked = realCamera();
+  installGlobeInViewRecovery(locked.viewer);
+  locked.camera.lookAtTransform(
+    Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(30_000_000, 0, 0)),
+    new Cesium.Cartesian3(-1_000_000, 0, 0),
+  );
+  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.
+  const tracked = realCamera();
+  tracked.viewer.trackedEntity = { id: 'pending-fix' };
+  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', () => {
+  const radians = Cesium.Math.toRadians;
+  // About 2% of a 16:9 frame on the planet, below the 10% limit.
+  const sliver = { alt: 18_000_000, pitch: -60 };
+  const { camera } = realCamera();
+  aim(camera, sliver);
+  const start = surfacePixelShare(camera, 1600, 900);
+  assert.ok(start > 0 && start < 0.1, `starts below the limit: ${start}`);
+
+  // Sideways across the sliver: the share wobbles by a cell, the planet stays.
+  assert.equal(lookStepLosesGlobe(camera, 'lookLeft', radians(0.5)), false);
+  const startShare = globeFrameShare(camera);
+  for (let i = 0; i < 20; i += 1) {
+    const step = lookAngleWithinFrame(camera, 'lookLeft', radians(0.25), {
+      startShare,
+    });
+    assert.equal(step, radians(0.25), `sideways step ${i + 1}`);
+    camera.lookLeft(step);
+  }
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+
+  // Toward the planet is always allowed.
+  aim(camera, sliver);
+  assert.equal(
+    lookAngleWithinFrame(camera, 'lookDown', radians(10)),
+    radians(10),
+  );
+
+  // Away from it stops short of losing it.
+  aim(camera, sliver);
+  const away = lookAngleWithinFrame(camera, 'lookUp', radians(30));
+  assert.ok(away < radians(30));
+  camera.lookUp(away);
+  assert.ok(globeFrameShare(camera) > 0);
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+});
+
+test('the look limit leaves a view with no surface to the move-end recovery', () => {
+  const { camera } = realCamera({ width: 1225, height: 923 });
+  aim(camera, reportedStuckView);
+  assert.equal(
+    lookAngleWithinFrame(camera, 'lookUp', Cesium.Math.toRadians(5)),
+    Cesium.Math.toRadians(5),
+  );
+});
+
+// Surface only in the corners of a 16:9 frame, all of it outside the scope's
+// keyhole: the full frame shows some planet, the scope shows none.
+const cornerOnlyView = { alt: 18_000_000, pitch: -52, roll: 60 };
+
+test('with a scope keyhole, surface hidden in the masked corners counts as none', () => {
+  const { camera } = realCamera();
+  aim(camera, cornerOnlyView);
+  const keyhole = { keyholeRadius: KEYHOLE_OUTER_RADIUS };
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+  assert.equal(surfacePixelShare(camera, 1600, 900, { keyhole: true }), 0);
+  assert.equal(globeOutOfFrame(camera), false);
+  assert.equal(globeOutOfFrame(camera, keyhole), true);
+  aim(camera, { alt: 18_000_000, pitch: -90 });
+  assert.ok(
+    Math.abs(
+      globeFrameShare(camera, keyhole) -
+        surfacePixelShare(camera, 1600, 900, { keyhole: true }),
+    ) < 0.03,
+    'the keyhole share matches the pick-ray oracle',
+  );
+});
+
+test('the recovery follows the scope: corner-only views are turned back only behind it', () => {
+  for (const [scopeOn, expectRecovery] of [
+    [true, true],
+    [false, false],
+  ]) {
+    const { camera, viewer } = realCamera();
+    installGlobeInViewRecovery(viewer, {
+      keyholeRadius: () => (scopeOn ? KEYHOLE_OUTER_RADIUS : 0),
+    });
+    aim(camera, cornerOnlyView);
+    camera.moveEnd.raiseEvent();
+    assert.equal(
+      Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
+      expectRecovery,
+      `scope ${scopeOn ? 'on' : 'off'}`,
+    );
+  }
+});
+
+function fakeTimers() {
+  let next = 1;
+  const pending = new Map();
+  return {
+    setTimeout: (callback) => {
+      const id = next++;
+      pending.set(id, callback);
+      return id;
+    },
+    clearTimeout: (id) => pending.delete(id),
+    pending: () => pending.size,
+    /** Run the earliest pending callback, as 250 ms passing would. */
+    tick() {
+      const [id, callback] = pending.entries().next().value ?? [];
+      if (id === undefined) return false;
+      pending.delete(id);
+      callback();
+      return true;
+    },
+  };
+}
+
+test('a stuck view is recovered once it has held still, without waiting for moveEnd', () => {
+  // At this pose the camera can drift by a rounding error every frame, so
+  // Cesium never sees it stop and never raises moveEnd for it.
+  const timers = fakeTimers();
+  const { camera, viewer } = realCamera({ width: 1225, height: 923 });
+  installGlobeInViewRecovery(viewer, timers);
+  aim(camera, reportedStuckView);
+  camera.moveStart.raiseEvent();
+  timers.tick();
+  assert.equal(globeOutOfFrame(camera), true, 'one quiet sample is not enough');
+  // A rounding-error drift between samples still counts as at rest.
+  camera.lookUp(1e-15);
+  timers.tick();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+  // Under that drift Cesium raises no new moveStart, so a later move that
+  // ends looking away is caught by the same check.
+  aim(camera, reportedStuckView);
+  timers.tick();
+  timers.tick();
+  assert.equal(globeOutOfFrame(camera), true, 'not yet at rest');
+  timers.tick();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+  camera.moveEnd.raiseEvent();
+  assert.equal(timers.pending(), 0, 'moveEnd ends the check');
+});
+
+test('the settle check follows a long move and gives up five minutes after the last one', () => {
+  // A drag of half a minute that stops at a stuck pose is still recovered.
+  const long = fakeTimers();
+  const dragged = realCamera({ width: 1225, height: 923 });
+  installGlobeInViewRecovery(dragged.viewer, long);
+  aim(dragged.camera, reportedStuckView);
+  dragged.camera.moveStart.raiseEvent();
+  for (let i = 0; i < 120; i += 1) {
+    dragged.camera.moveLeft(0.01);
+    long.tick();
+  }
+  assert.equal(globeOutOfFrame(dragged.camera), true, 'still moving');
+  while (long.tick());
+  assert.ok(
+    Cesium.Math.equalsEpsilon(dragged.camera.pitch, -Math.PI / 2, 1e-6),
+    'recovered once it stopped',
+  );
+
+  // A camera that keeps moving is followed, and left alone, for as long as it
+  // moves; once it rests the check gives up five minutes later.
+  const timers = fakeTimers();
+  const { camera, viewer } = realCamera({ width: 1225, height: 923 });
+  installGlobeInViewRecovery(viewer, timers);
+  aim(camera, reportedStuckView);
+  camera.moveStart.raiseEvent();
+  for (let i = 0; i < 2000; i += 1) {
+    camera.moveLeft(0.01);
+    timers.tick();
+  }
+  assert.equal(timers.pending(), 1, 'still following after eight minutes');
+  assert.equal(globeOutOfFrame(camera), true, 'a moving camera is left alone');
+  let idleSamples = 0;
+  while (timers.tick()) idleSamples += 1;
+  assert.ok(
+    Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
+    'recovered once it stopped',
+  );
+  assert.ok(
+    idleSamples >= 1200 && idleSamples <= 1205,
+    `gave up ${idleSamples} samples after it stopped`,
+  );
+
+  const disposed = fakeTimers();
+  const other = realCamera({ width: 1225, height: 923 });
+  const dispose = installGlobeInViewRecovery(other.viewer, disposed);
+  aim(other.camera, reportedStuckView);
+  other.camera.moveStart.raiseEvent();
+  dispose();
+  assert.equal(disposed.pending(), 0, 'dispose cancels the pending check');
+});
diff --git a/src/app/scene.js b/src/app/scene.js
index 1455b8268..9c115638d 100644
--- a/src/app/scene.js
+++ b/src/app/scene.js
@@ -2,9 +2,13 @@ import { createApplicationOperations } from './operations.js';
 import * as Cesium from 'cesium';
 import {
   createApplicationViewer,
+  installFreeLookHeightLimit,
+  installGlobeInViewRecovery,
   installTrackpadPinchZoom,
 } from '../app/viewer.js';
 import { registerDataCredits } from '../data/dataCredits.js';
+import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
+import { isScopeMaskEnabled } from '../scopeMask.js';
 import { configureCreditKeyboardAccess } from '../creditKeyboard.js';
 import { MapStackController } from '../mapStackController.js';
 import { loadPhotorealisticTileset } from '../mapStartup.js';
@@ -58,6 +62,13 @@ export async function createApplicationScene({
     if (!viewer.isDestroyed()) viewer.destroy();
   });
   defer(installTrackpadPinchZoom(viewer));
+  defer(installFreeLookHeightLimit(viewer));
+  defer(
+    installGlobeInViewRecovery(viewer, {
+      // The scope mask hides everything outside its keyhole.
+      keyholeRadius: () => (isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0),
+    }),
+  );
   registerDataCredits(viewer, credits);
   configureCreditKeyboardAccess(document);
   defer(onLocaleChange(() => configureCreditKeyboardAccess(document)));
diff --git a/src/app/viewer.js b/src/app/viewer.js
index c8b841352..ce182a0ab 100644
--- a/src/app/viewer.js
+++ b/src/app/viewer.js
@@ -1,6 +1,10 @@
 import * as Cesium from 'cesium';
 import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js';
 import { StarrySky } from '../sky/starrySky.js';
+import {
+  FREE_LOOK_MAX_HEIGHT_METERS,
+  globeOutOfFrame,
+} from '../globeInView.js';
 
 const PINCH_ZOOM_MULTIPLIER = 8;
 const MAX_PINCH_PIXEL_DELTA = 120;
@@ -103,6 +107,174 @@ export function installTrackpadPinchZoom(
   };
 }
 
+/**
+ * Allow Cesium's free look only below `maxHeight` and return its disposer.
+ * Orbit, tilt and zoom stay available at every height. `enableLook` gates the
+ * Shift+drag binding only; a drag that starts on the stars below Cesium's
+ * trackball height still turns the camera in place, which
+ * `installGlobeInViewRecovery` catches.
+ */
+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 originalEnableLook = controller.enableLook;
+  const sync = () => {
+    const height = camera.positionCartographic?.height;
+    controller.enableLook =
+      originalEnableLook && !(Number.isFinite(height) && height > maxHeight);
+  };
+  sync();
+  const removeListener = scene.preUpdate.addEventListener(sync);
+
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    removeListener();
+    controller.enableLook = originalEnableLook;
+  };
+}
+
+// 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, and a drag that Cesium turns
+ * into an in-place look below its trackball height whatever `enableLook` says.
+ * Heading and position are kept. Tracked cameras, locked ones (non-identity
+ * transform) and the 2D and Columbus modes are left alone. `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,
+    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');
+
+  const recover = () => {
+    if (scene.mode !== Cesium.SceneMode.SCENE3D || viewer.trackedEntity) return;
+    if (!Cesium.Matrix4.equals(camera.transform, Cesium.Matrix4.IDENTITY))
+      return;
+    const height = camera.positionCartographic?.height;
+    if (
+      !(height > minHeight) ||
+      !globeOutOfFrame(camera, { keyholeRadius: keyholeRadius() })
+    )
+      return;
+    camera.setView({
+      orientation: {
+        heading: camera.heading,
+        pitch: -Cesium.Math.PI_OVER_TWO,
+        roll: 0,
+      },
+    });
+    scene.requestRender?.();
+  };
+
+  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) {
+      movedSinceCheck = false;
+      recover();
+    }
+    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(() => {
+    stopSettling();
+    recover();
+  });
+  const removeMoveStart = camera.moveStart.addEventListener(startSettling);
+
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    stopSettling();
+    removeMoveEnd();
+    removeMoveStart();
+  };
+}
+
 /** Cesium.Viewer options of the standard globe viewer. */
 export function applicationViewerOptions(creditContainer) {
   return {
diff --git a/src/cameraGlobeRotation.test.mjs b/src/cameraGlobeRotation.test.mjs
index 814e4de1e..f15ae4978 100644
--- a/src/cameraGlobeRotation.test.mjs
+++ b/src/cameraGlobeRotation.test.mjs
@@ -13,6 +13,9 @@ import {
   moveCamera,
 } from './cameraVerbs.js';
 import { getRenderGovernorDiagnostics } from './renderGovernor.js';
+import { MIN_GLOBE_FRAME_SHARE, globeFrameShare } from './globeInView.js';
+import { KEYHOLE_OUTER_RADIUS } from './celestialRing.js';
+import { setScopeMaskEnabled } from './scopeMask.js';
 
 const radians = Cesium.Math.toRadians;
 const clone = (value) => Cesium.Cartesian3.clone(value);
@@ -1347,3 +1350,491 @@ test('close-up ultrawide refusal does not offer an unfit reset or move the camer
   samePose(h.camera, before);
   assert.equal(hasRenderHold(), false);
 });
+
+/**
+ * An oracle independent of the code under test: the share of an 80×45 grid of
+ * Cesium pick rays across the canvas that hit the ellipsoid surface. With
+ * `keyhole`, only the pixels inside the scope's visible circle count.
+ */
+function surfacePixelShare(camera, width, height, { keyhole = false } = {}) {
+  const radius = (KEYHOLE_OUTER_RADIUS * height) / 2;
+  let hits = 0;
+  let counted = 0;
+  for (let row = 0; row < 45; row += 1) {
+    for (let column = 0; column < 80; column += 1) {
+      const x = ((column + 0.5) * width) / 80;
+      const y = ((row + 0.5) * height) / 45;
+      if (keyhole && Math.hypot(x - width / 2, y - height / 2) > radius)
+        continue;
+      counted += 1;
+      const ray = camera.getPickRay(new Cesium.Cartesian2(x, y));
+      if (Cesium.IntersectionTests.rayEllipsoid(ray, Cesium.Ellipsoid.WGS84))
+        hits += 1;
+    }
+  }
+  return hits / counted;
+}
+
+/** Run a test with the scope mask on or off, restoring the default after. */
+function withScope(t, enabled) {
+  setScopeMaskEnabled(enabled);
+  t.after(() => setScopeMaskEnabled(true));
+}
+
+// The frame limit is measured on a coarser grid than the oracle.
+const SHARE_SLACK = 0.02;
+// Far-out poses, height in metres and pitch in degrees, where a few tilts up
+// are accepted before the limit refuses the next one.
+const FAR_OUT_POSES = [
+  [35_884_000, -86.26],
+  [35_884_000, -89],
+  [30_000_000, -86],
+  [25_000_000, -80],
+  [40_000_000, -88],
+];
+
+test('voice tilt from orbit stops with the planet still on screen and then says so', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // Slightly off nadir: from straight down a tilt is clamped before it moves.
+  const { camera, finishOnce } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const results = [];
+  for (let i = 0; i < 4; i += 1) {
+    const result = moveCamera({
+      motion: 'tilt',
+      direction: 'up',
+      mode: 'once',
+    });
+    results.push(result);
+    if (result.ok) finishOnce();
+    assert.ok(
+      surfacePixelShare(camera, 1600, 900) >=
+        MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+      `after tilt ${i + 1}`,
+    );
+  }
+  // From 18,000 km a 16:9 frame keeps a tenth of its area on the planet down
+  // to about -67°: the first tilt stops there, and later ones are refused.
+  assert.deepEqual(
+    results.map((result) => result.ok),
+    [true, false, false, false],
+  );
+  assert.match(results[1].error, /globe out of view/);
+  assert.ok(camera.pitch > radians(-68.5) && camera.pitch < radians(-66));
+});
+
+test('voice turn in place from orbit stops with the planet still on screen', (t) => {
+  withScope(t, false); // the whole frame is visible
+  const { camera, tick } = harness(t, { pitch: -75 });
+  assert.equal(
+    moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' }).ok,
+    true,
+  );
+  const heading = camera.heading;
+  for (let i = 0; i < 400 && getActiveCameraMotion(); i += 1) {
+    tick();
+    assert.ok(
+      surfacePixelShare(camera, 1280, 800) >=
+        MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+      `tick ${i + 1}`,
+    );
+  }
+  assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
+  assert.notEqual(camera.heading, heading, 'the turn moved before stopping');
+});
+
+test('a long voice turn below the limit keeps the share it started with', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // About 2% of a 16:9 frame on the planet: the limit is that share, less two
+  // grid cells of sampling noise, for the whole motion rather than per step.
+  const { camera, tick } = harness(t, {
+    pitch: -60,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const start = globeFrameShare(camera);
+  assert.ok(start > 0 && start < MIN_GLOBE_FRAME_SHARE);
+  assert.equal(
+    moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' }).ok,
+    true,
+  );
+  for (let i = 0; i < 400 && getActiveCameraMotion(); i += 1) {
+    tick();
+    assert.ok(
+      globeFrameShare(camera) >= start - 2 / (32 * 18) - 1e-9,
+      `tick ${i + 1}`,
+    );
+  }
+  assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+});
+
+test('repeated voice turns from one spot cannot each take a little more', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // About 2% of a 16:9 frame on the planet. Every turn from this position is
+  // measured against the same baseline, so asking again stops being allowed.
+  const { camera, finishOnce, tick } = harness(t, {
+    pitch: -60,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const start = globeFrameShare(camera);
+  const floor = start - 2 / (32 * 18) - 1e-9;
+  const results = [];
+  for (const mode of ['once', 'once', 'continuous', 'once', 'continuous']) {
+    for (let i = 0; i < 4; i += 1) {
+      const result = moveCamera({ motion: 'rotate', direction: 'left', mode });
+      results.push(result.ok);
+      if (!result.ok) continue;
+      if (mode === 'once') finishOnce();
+      else for (let j = 0; j < 400 && getActiveCameraMotion(); j += 1) tick();
+      assert.ok(globeFrameShare(camera) >= floor, `${mode} turn ${i + 1}`);
+    }
+  }
+  assert.ok(results.includes(false), 'a turn at the limit is refused');
+  assert.equal(results.at(-1), false);
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+});
+
+test('a voice turn after something else turned the camera starts over', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // The same spot, first framed straight down, then turned to about 2% of the
+  // frame by something other than voice: a turn left is measured from there.
+  const { camera, finishOnce } = harness(t, {
+    pitch: -90,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  assert.equal(
+    moveCamera({ motion: 'rotate', direction: 'left', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  camera.setView({
+    orientation: { heading: 0, pitch: radians(-60), roll: 0 },
+  });
+  const start = globeFrameShare(camera);
+  assert.ok(start > 0 && start < MIN_GLOBE_FRAME_SHARE);
+  assert.equal(
+    moveCamera({ motion: 'rotate', direction: 'left', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  assert.ok(globeFrameShare(camera) >= start - 2 / (32 * 18) - 1e-9);
+});
+
+test('nudging the camera between voice turns cannot slide the planet away', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // A wheel notch or an orbit drag between requests starts each turn afresh;
+  // the 1% floor still holds, and below it a turn may only keep what it has.
+  for (const [nudge, pitch] of [
+    [(camera) => camera.moveBackward(2), -60],
+    [(camera) => camera.rotateRight(radians(0.2)), -60],
+    [(camera) => camera.moveBackward(2), -58],
+  ]) {
+    const { camera, tick } = harness(t, {
+      pitch,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    const start = globeFrameShare(camera);
+    const floor = Math.min(0.01, start) - 1e-9;
+    for (let i = 0; i < 12; i += 1) {
+      nudge(camera);
+      if (
+        moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' })
+          .ok
+      )
+        for (let j = 0; j < 400 && getActiveCameraMotion(); j += 1) tick();
+      assert.ok(
+        globeFrameShare(camera) >= floor,
+        `start ${start}, turn ${i + 1}`,
+      );
+    }
+    assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+  }
+});
+
+test('after the frame changes size, a voice turn toward the planet is allowed', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // A tilt stops at its limit; then the window widens at the same pose, so the
+  // frame shows less than the carried limit. Toward the planet must still go.
+  const { camera, canvas, viewer, finishOnce } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  canvas.clientWidth = canvas.width = viewer.scene.drawingBufferWidth = 3200;
+  camera.frustum.aspectRatio = 3200 / 900;
+  const narrowed = globeFrameShare(camera);
+  assert.ok(narrowed < MIN_GLOBE_FRAME_SHARE, `frame now shows ${narrowed}`);
+
+  const down = moveCamera({ motion: 'tilt', direction: 'down', mode: 'once' });
+  assert.equal(down.ok, true, down.error);
+  finishOnce();
+  assert.ok(globeFrameShare(camera) > narrowed);
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'down', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  const up = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' });
+  if (up.ok) finishOnce();
+  assert.ok(surfacePixelShare(camera, 3200, 900) > 0);
+});
+
+test('with the scope on, a voice tilt stops while the keyhole still shows the planet', (t) => {
+  withScope(t, true);
+  const { camera, finishOnce } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const results = [];
+  for (let i = 0; i < 4; i += 1) {
+    const result = moveCamera({
+      motion: 'tilt',
+      direction: 'up',
+      mode: 'once',
+    });
+    results.push(result.ok);
+    if (result.ok) finishOnce();
+    assert.ok(
+      surfacePixelShare(camera, 1600, 900, { keyhole: true }) >=
+        MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+      `after tilt ${i + 1}`,
+    );
+  }
+  assert.equal(results[0], true);
+  assert.equal(results.at(-1), false, 'a tilt past the limit is refused');
+});
+
+test('with the scope on, a voice turn cannot leave the planet only in the masked corners', (t) => {
+  // An oblique orbit view: turning in place swings the planet toward a corner,
+  // where the full frame still shows it but the scope mask hides it.
+  for (const [height, pitch] of [
+    [5_000_000, -70],
+    [3_000_000, -75],
+    [18_000_000, -80],
+  ]) {
+    withScope(t, true);
+    const { camera, tick } = harness(t, {
+      height,
+      pitch,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    assert.equal(
+      moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' })
+        .ok,
+      true,
+    );
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
+    assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
+    assert.ok(
+      surfacePixelShare(camera, 1600, 900, { keyhole: true }) >=
+        MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+      `${height / 1000} km at ${pitch}°`,
+    );
+  }
+});
+
+test('far out, a voice tilt is either refused or really moves, at display frame rates', (t) => {
+  // A small planet disc: its sampled share wobbles as it crosses the grid.
+  // Whatever the limit decides, "done" must mean the camera turned, and some
+  // of these tilts must be accepted for that to be checked at all.
+  let accepted = 0;
+  for (const [height, pitch] of FAR_OUT_POSES) {
+    withScope(t, true);
+    const { camera, tick } = harness(t, {
+      latitude: 45.37,
+      longitudeDeg: -33.33,
+      height,
+      heading: 89.9,
+      pitch,
+      viewportWidth: 1280,
+      viewportHeight: 1024,
+    });
+    for (let i = 0; i < 4; i += 1) {
+      const before = camera.pitch;
+      const result = moveCamera({
+        motion: 'tilt',
+        direction: 'up',
+        mode: 'once',
+      });
+      if (!result.ok) {
+        assert.match(result.error, /zoom in first/);
+        continue;
+      }
+      accepted += 1;
+      for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
+      assert.ok(
+        camera.pitch - before > radians(0.5) - 1e-9,
+        `${height / 1000} km at ${pitch}°: tilt ${i + 1} reported done but moved ${Cesium.Math.toDegrees(camera.pitch - before)}°`,
+      );
+    }
+    assert.ok(surfacePixelShare(camera, 1280, 1024, { keyhole: true }) > 0);
+  }
+  assert.ok(accepted > 0, 'no far-out tilt was accepted');
+});
+
+test('a voice turn reported as done turns at least the half degree its check proved', (t) => {
+  // A grazing sliver: the first frame's small step lands in a dip of the
+  // sampled share, which used to stop the turn before it moved at all.
+  for (const scope of [true, false]) {
+    withScope(t, scope);
+    const { camera, tick } = harness(t, {
+      latitude: 20,
+      longitudeDeg: 10,
+      height: 18_000_000,
+      pitch: -58,
+      heading: 37,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    const before = Cesium.Cartesian3.clone(camera.directionWC);
+    const result = moveCamera({
+      motion: 'rotate',
+      direction: 'left',
+      mode: 'once',
+    });
+    if (!result.ok) {
+      assert.match(result.error, /globe out of view/);
+      continue;
+    }
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick(1 / 60);
+    const turned = Cesium.Cartesian3.angleBetween(before, camera.directionWC);
+    assert.ok(
+      turned >= radians(0.5) - 1e-9,
+      `scope ${scope ? 'on' : 'off'}: turned ${Cesium.Math.toDegrees(turned)}°`,
+    );
+    assert.ok(surfacePixelShare(camera, 1600, 900, { keyhole: scope }) > 0);
+  }
+});
+
+/** Track an entity below `camera`, locking it into that entity's frame. */
+function trackFrom(viewer, camera) {
+  viewer.trackedEntity = { id: 'high-satellite' };
+  const below = Cesium.Cartesian3.fromDegrees(10, 20, 400_000);
+  camera.lookAtTransform(Cesium.Transforms.eastNorthUpToFixedFrame(below));
+}
+
+test('a voice turn that releases a tracked camera is checked as released', (t) => {
+  // Voice releases the follow camera inside the navigation that runs the
+  // motion, so the request is judged by the pose the release will leave.
+  let accepted = 0;
+  for (const [scope, direction, motion] of [
+    [true, 'up', 'tilt'],
+    [false, 'up', 'tilt'],
+    [false, 'left', 'rotate'],
+  ]) {
+    withScope(t, scope);
+    const { camera, viewer, tick } = harness(t, {
+      latitude: 20,
+      longitudeDeg: 10,
+      height: 18_000_000,
+      pitch: -58,
+      heading: 37,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    trackFrom(viewer, camera);
+    const releaseThenRun = (start) => {
+      viewer.trackedEntity = undefined;
+      camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+      return start();
+    };
+    const before = Cesium.Cartesian3.clone(camera.directionWC);
+    const result = moveCamera(
+      { motion, direction, mode: 'once' },
+      releaseThenRun,
+    );
+    const label = `${motion} ${direction}, scope ${scope ? 'on' : 'off'}`;
+    if (!result.ok) {
+      assert.match(result.error, /globe out of view/, label);
+      continue;
+    }
+    accepted += 1;
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick(1 / 60);
+    const turned = Cesium.Cartesian3.angleBetween(before, camera.directionWC);
+    assert.ok(turned >= radians(0.5) - 1e-9, `${label}: turned ${turned}`);
+    assert.ok(
+      surfacePixelShare(camera, 1600, 900, { keyhole: scope }) > 0,
+      `${label}: the planet stays on screen`,
+    );
+  }
+  assert.ok(accepted > 0, 'no released turn was accepted');
+});
+
+test('a refused voice turn leaves a tracked camera tracking', (t) => {
+  for (const scope of [true, false]) {
+    withScope(t, scope);
+    const { camera, viewer, tick } = harness(t, {
+      pitch: -80,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    // Tilt up to the limit untracked, then track from there.
+    for (let i = 0; i < 40; i += 1) {
+      if (!moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok)
+        break;
+      for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
+    }
+    trackFrom(viewer, camera);
+    const tracked = viewer.trackedEntity;
+    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;
+        camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+        return start();
+      },
+    );
+    const label = `scope ${scope ? 'on' : 'off'}`;
+    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.ok(Cesium.Matrix4.equals(camera.transform, transform), label);
+  }
+});
+
+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' });
+  assert.equal(result.ok, true);
+  finishOnce();
+  near(camera.pitch, radians(-45), 1e-6, 'full 15° tilt');
+});
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index e037472cb..964b5c1a7 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -20,11 +20,18 @@
 
 import * as Cesium from 'cesium';
 import { GLOBE_VIEW } from './locations.js';
+import {
+  globeFrameShare,
+  lookAngleWithinFrame,
+  lookStepLosesGlobe,
+} from './globeInView.js';
 import {
   projectEarthDiscToViewport,
   earthDiscScreenRadius,
   getKeyholeGeometry,
+  KEYHOLE_OUTER_RADIUS,
 } from './celestialRing.js';
+import { isScopeMaskEnabled } from './scopeMask.js';
 import {
   holdContinuousRender,
   releaseContinuousRender,
@@ -1008,6 +1015,137 @@ export function interruptCameraMotionIfActive(
   return interruptCameraMotion(reason);
 }
 
+/**
+ * A free globe camera: 3D, not tracking, not locked to a frame. The frame
+ * limit for in-place turns applies to it alone, as the move-end recovery does.
+ */
+function isFreeGlobeCamera(cam) {
+  return (
+    _viewer.scene.mode === Cesium.SceneMode.SCENE3D &&
+    !_viewer.trackedEntity &&
+    Cesium.Matrix4.equals(cam.transform, Cesium.Matrix4.IDENTITY)
+  );
+}
+
+// The frame share that in-place voice turns measure their limit against, with
+// the pose the last voice turn left the camera in. A turn that starts where
+// the last one left off keeps that baseline (raised if the planet now fills
+// more of the frame), so repeating a request cannot take a little more each
+// time. Once anything else has moved or turned the camera, a turn starts over
+// from what is on screen.
+let _lookBaseline = null;
+
+// The pre-check's proof that a half-degree turn from this pose keeps the planet
+// in view: which way, from which 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);
+let _provenLook = null;
+
+/** The part of the frame a viewer can see: the scope keyhole when it is on. */
+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());
+  const continues =
+    _lookBaseline &&
+    Cesium.Cartesian3.equalsEpsilon(
+      _lookBaseline.position,
+      cam.positionWC,
+      0,
+      1,
+    ) &&
+    Cesium.Cartesian3.equalsEpsilon(
+      _lookBaseline.direction,
+      cam.directionWC,
+      0,
+      1e-9,
+    );
+  _lookBaseline = {
+    position: Cesium.Cartesian3.clone(cam.positionWC),
+    direction: Cesium.Cartesian3.clone(cam.directionWC),
+    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.
+ */
+function lookWithinFrame(cam, m, look, angle) {
+  let allowed = angle;
+  if (isFreeGlobeCamera(cam)) {
+    if (m.globeShareAtStart === undefined) {
+      m.globeShareAtStart = lookBaselineShare(cam);
+      m.provenTurnRad = lookProven(cam, look) ? PROVEN_TURN_RAD : 0;
+      m.turnedRad = 0;
+    }
+    _provenLook = null;
+    allowed = lookAngleWithinFrame(cam, look, angle, {
+      ...visibleFrame(),
+      startShare: m.globeShareAtStart,
+    });
+    const owed = Math.min(angle, m.provenTurnRad - m.turnedRad);
+    if (allowed < owed) allowed = owed;
+    m.turnedRad += allowed;
+  }
+  if (allowed > 0) cam[look](allowed);
+  // The pose this turn leaves, for a turn that continues from it.
+  if (_lookBaseline)
+    Cesium.Cartesian3.clone(cam.directionWC, _lookBaseline.direction);
+  if (allowed < angle) interruptCameraMotion('globe-out-of-frame');
+}
+
+/** True when the pre-check proved a half-degree `look` from `cam`'s pose. */
+function lookProven(cam, look) {
+  return (
+    _provenLook?.look === look &&
+    Cesium.Cartesian3.equalsEpsilon(
+      _provenLook.direction,
+      cam.directionWC,
+      0,
+      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
+ * 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
+ * turn are the same in any reference frame, so such a camera is judged as it
+ * is, before the release, and a refusal leaves tracking as it was. Otherwise a
+ * camera that is not a free globe camera is not checked. Returns the refusal,
+ * or null.
+ */
+function checkLookFromOrbit(look, { released = false } = {}) {
+  _provenLook = null;
+  if (_viewer.scene.mode !== Cesium.SceneMode.SCENE3D) return null;
+  const cam = _viewer.camera;
+  if (!released && !isFreeGlobeCamera(cam)) return null;
+  if (
+    lookStepLosesGlobe(cam, look, PROVEN_TURN_RAD, {
+      ...visibleFrame(),
+      startShare: lookBaselineShare(cam),
+    })
+  )
+    return {
+      ok: false,
+      action: 'move_camera',
+      error:
+        'From this height that would turn the globe out of view — zoom in first, or turn the other way.',
+    };
+  _provenLook = { look, direction: Cesium.Cartesian3.clone(cam.directionWC) };
+  return null;
+}
+
 function clearLookAt() {
   try {
     _viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
@@ -1226,10 +1364,15 @@ function onTick() {
           interruptCameraMotion('tilt-clamp');
           return;
         }
-        if (up) cam.lookUp(stepRad);
-        else cam.lookDown(stepRad);
-      } else if (m.direction === 'left') cam.lookLeft(stepRad);
-      else cam.lookRight(stepRad);
+        lookWithinFrame(cam, m, up ? 'lookUp' : 'lookDown', stepRad);
+      } else {
+        lookWithinFrame(
+          cam,
+          m,
+          m.direction === 'left' ? 'lookLeft' : 'lookRight',
+          stepRad,
+        );
+      }
     } else if (m.kind === 'route') {
       // The dolly's shaping lives in advanceRouteFlight(); the tick only
       // applies the pose and honours the same completion path as before.
@@ -1413,6 +1556,7 @@ export function initCameraVerbs(
   _isCockpitActive =
     typeof isCockpitActive === 'function' ? isCockpitActive : null;
   _viewer = viewer;
+  _lookBaseline = null;
   if (_tickRemover) _tickRemover();
   _tickRemover = viewer.clock.onTick.addEventListener(onTick);
   if (_trackingRemover) _trackingRemover();
@@ -1524,6 +1668,27 @@ export function moveCamera(args = {}, runNavigation = null) {
       };
     }
   }
+  const look =
+    motion === 'tilt' || motion === 'rotate'
+      ? {
+          up: 'lookUp',
+          down: 'lookDown',
+          left: 'lookLeft',
+          right: 'lookRight',
+        }[direction]
+      : 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
+  // run and reported as done, and one that can is then turned at least that
+  // far. Near the limit the sampled share wobbles as the planet's edge crosses
+  // the grid, so a turn that would keep the planet can occasionally be refused
+  // too.
+  // A camera that is tracked or locked now is judged as the navigation that
+  // runs the turn will release it, so a refusal keeps the tracking.
+  const lookRefusal =
+    look &&
+    checkLookFromOrbit(look, { released: typeof runNavigation === 'function' });
+  if (lookRefusal) return lookRefusal;
   if (
     (motion === 'rotate_globe' ||
       (motion === 'orbit' && typeof runNavigation !== 'function')) &&
@@ -1609,6 +1774,12 @@ export function moveCamera(args = {}, runNavigation = null) {
   }
   const start = () => {
     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)) {
+      const refusal = checkLookFromOrbit(look);
+      if (refusal) return refusal;
+    }
     const state = {
       kind: motion,
       direction: direction || 'right',
diff --git a/src/globeInView.js b/src/globeInView.js
new file mode 100644
index 000000000..1ccbcda23
--- /dev/null
+++ b/src/globeInView.js
@@ -0,0 +1,167 @@
+import * as Cesium from 'cesium';
+
+// Cesium's free look (Shift+drag) turns the camera in place. Near the ground
+// that surveys a city; from orbit a few drags turn the whole planet out of
+// frame and leave only stars.
+export const FREE_LOOK_MAX_HEIGHT_METERS = 1_000_000;
+
+// A voice turn from orbit stops when about this share of the frame still shows
+// the planet's surface.
+export const MIN_GLOBE_FRAME_SHARE = 0.1;
+
+const GRID_COLUMNS = 32;
+const GRID_ROWS = 18;
+// A turn across a sliver of planet moves its edge through sample points, so
+// the share wobbles by a cell or two without the planet leaving.
+const GRID_NOISE_CELLS = 2;
+// Whatever the baseline, a voice turn never takes the planet below this share
+// of the frame; a view that already shows less may only keep what it has.
+const LOOK_ABSOLUTE_FLOOR_SHARE = 0.01;
+const sampleRay = new Cesium.Ray();
+const sampleOffset = new Cesium.Cartesian3();
+
+/**
+ * Cast a 32×18 grid of view rays, one through the centre of each cell, at the
+ * WGS84 ellipsoid. With `keyholeRadius` (a radius around the frame centre, in
+ * units of half the frame height) only the cells inside that circle count: the
+ * scope mask hides the rest. Returns the surface hits and the cells counted, or
+ * null for a frustum other than a perspective one.
+ */
+function sampleFrame(camera, keyholeRadius) {
+  const frustum = camera.frustum;
+  if (!(frustum instanceof Cesium.PerspectiveFrustum)) return null;
+  const aspect = frustum.aspectRatio;
+  const tanY = Math.tan(frustum.fovy / 2);
+  const tanX = tanY * aspect;
+  const keyholeSquared = keyholeRadius > 0 ? keyholeRadius * keyholeRadius : 0;
+  Cesium.Cartesian3.clone(camera.positionWC, sampleRay.origin);
+  let hits = 0;
+  let cells = 0;
+  for (let row = 0; row < GRID_ROWS; row += 1) {
+    const rowY = (2 * (row + 0.5)) / GRID_ROWS - 1;
+    for (let column = 0; column < GRID_COLUMNS; column += 1) {
+      const columnX = (2 * (column + 0.5)) / GRID_COLUMNS - 1;
+      if (
+        keyholeSquared &&
+        (columnX * aspect) ** 2 + rowY * rowY > keyholeSquared
+      )
+        continue;
+      cells += 1;
+      Cesium.Cartesian3.multiplyByScalar(
+        camera.rightWC,
+        columnX * tanX,
+        sampleOffset,
+      );
+      Cesium.Cartesian3.add(
+        camera.directionWC,
+        sampleOffset,
+        sampleRay.direction,
+      );
+      Cesium.Cartesian3.multiplyByScalar(
+        camera.upWC,
+        rowY * tanY,
+        sampleOffset,
+      );
+      Cesium.Cartesian3.add(
+        sampleRay.direction,
+        sampleOffset,
+        sampleRay.direction,
+      );
+      Cesium.Cartesian3.normalize(sampleRay.direction, sampleRay.direction);
+      if (
+        Cesium.IntersectionTests.rayEllipsoid(sampleRay, Cesium.Ellipsoid.WGS84)
+      )
+        hits += 1;
+    }
+  }
+  return { hits, cells };
+}
+
+/**
+ * Share of the frame, from 0 to 1, that shows the planet's surface: the
+ * fraction of a 32×18 grid of view rays, one through the centre of each cell,
+ * that hit the WGS84 ellipsoid. With `keyholeRadius` (see `sampleFrame`) it is
+ * the share of the visible circle instead. A frustum other than a perspective
+ * one counts as fully covered.
+ */
+export function globeFrameShare(camera, { keyholeRadius = 0 } = {}) {
+  const sample = sampleFrame(camera, keyholeRadius);
+  if (!sample || sample.cells === 0) return 1;
+  return sample.hits / sample.cells;
+}
+
+/** True when none of the planet's surface is in `camera`'s visible frame. */
+export function globeOutOfFrame(camera, options) {
+  return globeFrameShare(camera, options) === 0;
+}
+
+const lookProbes = new WeakMap();
+const LOOK_EDGE_TOLERANCE = Cesium.Math.toRadians(0.05);
+
+/**
+ * How much of one in-place look step (`lookUp`, `lookDown`, `lookLeft` or
+ * `lookRight` by a non-negative `angle` in radians) keeps the planet in frame
+ * from orbit. Above the free-look height the step may not leave less than
+ * `MIN_GLOBE_FRAME_SHARE` of the visible frame on the planet, or less than
+ * `startShare` when that is lower, give or take two grid cells of sampling
+ * noise. However the baseline was taken, it never leaves less than 1% of the
+ * frame, and a view that already shows less may only keep or gain what it has.
+ * `startShare` is the baseline the turn is measured against (the current share
+ * by default): callers pass one value to every step of a motion, and to every
+ * turn that continues from where the last one left off, so the limit cannot
+ * slide down a step or a command at a time. `keyholeRadius` limits the measure
+ * to the scope's visible circle, as in `globeFrameShare`.
+ * With nothing on screen the limit is nothing either, so the step is left to
+ * the move-end recovery. Returns `angle` when the whole step fits, otherwise a
+ * smaller angle that fits, found by bisection to within 0.05°, so a stopped
+ * motion rests at the limit. Steps are tried on a copy; `camera` is not moved.
+ */
+export function lookAngleWithinFrame(
+  camera,
+  look,
+  angle,
+  { startShare, keyholeRadius = 0 } = {},
+) {
+  if (
+    !(angle > 0) ||
+    !(camera.positionCartographic?.height > FREE_LOOK_MAX_HEIGHT_METERS)
+  )
+    return angle;
+  const sample = sampleFrame(camera, keyholeRadius);
+  if (!sample || sample.cells === 0) return angle;
+  const share = sample.hits / sample.cells;
+  const baseline = startShare ?? share;
+  // Capped at what is on screen now, so a step that keeps or gains surface is
+  // never refused, even when the frame has shrunk since the baseline was taken
+  // (a resized window or a turned phone).
+  const floor = Math.min(
+    share,
+    Math.max(
+      Math.min(MIN_GLOBE_FRAME_SHARE, baseline) -
+        GRID_NOISE_CELLS / sample.cells,
+      Math.min(LOOK_ABSOLUTE_FLOOR_SHARE, baseline),
+    ),
+  );
+  const fits = (step) => {
+    const probe = Cesium.Camera.clone(camera, lookProbes.get(camera));
+    lookProbes.set(camera, probe);
+    probe[look](step);
+    // Shares are whole grid cells; the epsilon keeps rounding in `floor` from
+    // costing a cell.
+    return globeFrameShare(probe, { keyholeRadius }) >= floor - 1e-9;
+  };
+  if (fits(angle)) return angle;
+  let inside = 0;
+  let outside = angle;
+  while (outside - inside > LOOK_EDGE_TOLERANCE) {
+    const middle = (inside + outside) / 2;
+    if (fits(middle)) inside = middle;
+    else outside = middle;
+  }
+  return inside;
+}
+
+/** True when an in-place look step of `angle` would lose part of its turn. */
+export function lookStepLosesGlobe(camera, look, angle, options) {
+  return lookAngleWithinFrame(camera, look, angle, options) < angle;
+}

From d36b28f352389c7f9caff1c46801cd698f93b209 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Wed, 4 Nov 2026 01:19:22 +0530
Subject: [PATCH 20/71] docs(changelog): add the globe-in-view fragment

---
 changelog.d/1532-globe-in-view.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 changelog.d/1532-globe-in-view.md

diff --git a/changelog.d/1532-globe-in-view.md b/changelog.d/1532-globe-in-view.md
new file mode 100644
index 000000000..f697959b2
--- /dev/null
+++ b/changelog.d/1532-globe-in-view.md
@@ -0,0 +1,8 @@
+- Keep the globe in view from orbit. Cesium's free look (Shift+drag) turned
+  the camera in place, so a few drags from the whole-globe view left only
+  stars, and the pose stayed in the share link. Free look now works only below
+  1,000 km; a camera move that ends above it with no planet surface in view
+  (inside the scope keyhole when the scope is on) turns straight down; and
+  voice tilt and turns from orbit stop while the planet is still on screen and
+  say so instead of reporting a turn they could not make (Manjunath,
+  @manjunath22466, #1532).

From 1f0a8b5f1640921d0742cd94cdd8520310a90e2f Mon Sep 17 00:00:00 2001
From: Trygve Hemminghytt <274629477+trygvehhh@users.noreply.github.com>
Date: Tue, 3 Nov 2026 22:58:09 +0100
Subject: [PATCH 21/71] fix(datacenters): report newly tagged features osmium
 cannot export

A still-tagged feature without exportable geometry already keeps its old
line. A newly tagged one had nowhere to go and was dropped silently; it is
now listed as skipped with a warning, so a refresh never loses a site or
hides a broken one.
---
 scripts/build-datacenters-norway.py        | 10 ++++++++--
 src/data/datacentersNorwayRefresh.test.mjs |  3 ++-
 src/data/local_data/datacenters/README.md  |  3 ++-
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/scripts/build-datacenters-norway.py b/scripts/build-datacenters-norway.py
index 03286b864..d1203f38d 100644
--- a/scripts/build-datacenters-norway.py
+++ b/scripts/build-datacenters-norway.py
@@ -182,12 +182,13 @@ def feature_line(key, sequence, fresh):
 
 
 def merge(lines, fresh, rings, tagged):
-    out, seen, sequence = [], set(), 0
-    report = {'kept': 0, 'updated': [], 'removed': [], 'added': [], 'unexported': []}
+    out, seen, known, sequence = [], set(), set(), 0
+    report = {'kept': 0, 'updated': [], 'removed': [], 'added': [], 'unexported': [], 'skipped': []}
     for line in lines:
         feature = json.loads(line)
         sequence = max(sequence, feature['properties']['id'])
         key = osm_key(feature)
+        known.add(key)
         if key in fresh:
             seen.add(key)
             old_tags = feature['properties']['tags']
@@ -211,6 +212,8 @@ def merge(lines, fresh, rings, tagged):
         sequence += 1
         out.append(feature_line(key, sequence, fresh[key]))
         report['added'].append(key)
+    # newly tagged, but osmium built no usable geometry: nothing to add yet
+    report['skipped'] = sorted(set(tagged) - set(fresh) - known, key=lambda k: (k[0], int(k[1:])))
     if len({osm_key(json.loads(line)) for line in out}) != len(out):
         raise ValueError('Duplicate OSM identity')
     return out, report
@@ -239,6 +242,9 @@ def main():
     if report['unexported']:
         print('warning: kept the old line of tagged features osmium did not export: %s'
               % ', '.join(report['unexported']), file=sys.stderr)
+    if report['skipped']:
+        print('warning: did not add newly tagged features osmium did not export: %s'
+              % ', '.join(report['skipped']), file=sys.stderr)
     payload = '\n'.join(merged) + '\n'
     if args.verify:
         if payload != DATASET.read_text(encoding='utf-8'):
diff --git a/src/data/datacentersNorwayRefresh.test.mjs b/src/data/datacentersNorwayRefresh.test.mjs
index 2b7b7d5bf..88527295b 100644
--- a/src/data/datacentersNorwayRefresh.test.mjs
+++ b/src/data/datacentersNorwayRefresh.test.mjs
@@ -52,9 +52,10 @@ def line(osm_id, sequence):
                                       'type': 'data_center', 'osm_id': osm_id}})
 norway = [([(0, 0), (20, 0), (20, 80), (0, 80)], False)]
 lines = [line(7, 1), line(8, 2)]
-out, report = merge(lines, {}, norway, {'w7'})
+out, report = merge(lines, {}, norway, {'w7', 'w12'})
 assert out == [lines[0]], out
 assert report['unexported'] == ['w7'] and report['removed'] == ['w8'], report
+assert report['skipped'] == ['w12'] and report['added'] == [], report
 `,
   );
 });
diff --git a/src/data/local_data/datacenters/README.md b/src/data/local_data/datacenters/README.md
index 5a80df267..86f573c61 100644
--- a/src/data/local_data/datacenters/README.md
+++ b/src/data/local_data/datacenters/README.md
@@ -29,7 +29,8 @@ reflects OSM as of the extract below, everything else the original snapshot.
 - Contact tags are dropped as above; unchanged features keep their original
   line, so geometry is only rewritten when tags or rings actually changed.
   A feature is removed only once it is no longer tagged; one still tagged but
-  without an exportable geometry keeps its line and is reported as unexported.
+  without an exportable geometry keeps its line and is reported as unexported,
+  and a newly tagged one osmium cannot export is reported as skipped.
 - Refresh: `python3 scripts/build-datacenters-norway.py --cache <dir>` uses
   Geofabrik's current Norway extract and prints the dated name it used; record
   that name, its OSM timestamp and MD5 here. Requires `osmium-tool`.

From 44860df90e78d854c0523f9563d32f56d0c86e03 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Wed, 4 Nov 2026 13:40:43 +0530
Subject: [PATCH 22/71] Follow a replacement voice flight whatever its
 predecessor reports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A motion queued behind a voice fly-to now follows a later fly-to in the same reply whether the earlier one arrived, was cancelled or failed. A geocode that loses navigation reports failed, so the motion used to be dropped; and a flight left flying while the next place is looked up could land and run the motion there, taking navigation and cancelling the newer flight. The deadline, abort and stale-reply checks still end the wait.

pitchDeg -90 or -89 from a top-down view is now unchanged rather than a 1° tilt up, and the tilt tests' pitch loops are bounded.
---
 src/cameraTilt.test.mjs       | 23 +++++++++++--
 src/cameraVerbs.js            |  8 ++++-
 src/voice/gevActions.js       | 14 ++++++--
 src/voice/gevActions.test.mjs | 65 +++++++++++++++++++++++++++++++++++
 4 files changed, 104 insertions(+), 6 deletions(-)

diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index 7d2664c9f..93bbf246e 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -78,6 +78,11 @@ function harness(
 }
 
 const pitchDeg = (camera) => degrees(camera.pitch);
+/** Tick until done() holds; a regression fails here instead of hanging. */
+const tickUntil = (h, done, frames = 600) => {
+  for (let i = 0; i < frames && !done(); i += 1) h.tick();
+  assert.ok(done(), `not reached in ${frames} frames`);
+};
 const headingDeg = (camera) =>
   degrees(Cesium.Math.negativePiToPi(camera.heading));
 
@@ -171,6 +176,20 @@ test('a requested angle the camera already holds is a no-op', (t) => {
   assert.equal(getActiveCameraMotion(), null);
 });
 
+for (const pitch of [-90, -89]) {
+  test(`a top-down view asked for ${pitch}° stays put`, (t) => {
+    // The tool description calls -89 top-down; the clamp must not tilt a
+    // -90° view up 1° and report it as a move up.
+    const h = harness(t);
+    const before = pitchDeg(h.camera);
+    const result = moveCamera({ motion: 'tilt', pitchDeg: pitch });
+    assert.equal(result.ok, true);
+    assert.equal(result.unchanged, true);
+    assert.equal(getActiveCameraMotion(), null);
+    assert.equal(pitchDeg(h.camera), before);
+  });
+}
+
 test('tilt down from top-down still refuses honestly', (t) => {
   harness(t);
   const result = moveCamera({ motion: 'tilt', direction: 'down' });
@@ -335,7 +354,7 @@ test('the pitchDeg and direction check uses the pitch the swing starts from', (t
 test('after a zoom in, a pivoting tilt never lowers the camera further', (t) => {
   const h = harness(t, { height: 1000 });
   moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
-  while (pitchDeg(h.camera) < -30) h.tick();
+  tickUntil(h, () => pitchDeg(h.camera) >= -30);
   adjustOrbitRange(1 / 2.4);
   adjustOrbitRange(1 / 2.4);
   h.tick();
@@ -390,7 +409,7 @@ test('a zoom in during a pivot tilt stops at the clearance', (t) => {
   // the camera about 107 m up, then at the 80 m zoom floor.
   const h = harness(t, { height: 400 });
   moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
-  while (pitchDeg(h.camera) < -40) h.tick();
+  tickUntil(h, () => pitchDeg(h.camera) >= -40);
   assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: true });
   // At -40° the floor is 150 / sin 40° ≈ 233 m, which the first zoom reached.
   assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: false });
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 16888d73e..380a737f0 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -1671,7 +1671,13 @@ export function moveCamera(args = {}, runNavigation = null) {
     // Judge from the pitch the motion will start at: the pivot's, which at
     // regional range is a degree or two shallower than the camera's.
     const { from } = tiltStartFrame(_viewer.camera, { releasesTracking });
-    if (Math.abs(tiltToPitch - from) < Cesium.Math.toRadians(0.5)) {
+    // -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)
+    ) {
       return {
         ok: true,
         action: 'move_camera',
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index f7573075e..c9bc811a4 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -1302,9 +1302,17 @@ export function createGevActionRunner({
           runOptions.signal,
           deadline,
         );
-        // A later fly-to in the same reply cancels this one: follow it to
-        // where the camera lands, within the same deadline.
-        while (status === 'cancelled' && voiceFlight !== flight && current()) {
+        // A later fly-to in the same reply replaces this one: follow it to
+        // where the camera lands, within the same deadline. Its status does
+        // not matter. A geocode that loses navigation reports failed, and a
+        // flight left flying while the next place is looked up can still
+        // land; running there would take navigation and cancel the newer one.
+        while (
+          voiceFlight !== flight &&
+          status !== 'aborted' &&
+          status !== 'timeout' &&
+          current()
+        ) {
           flight = voiceFlight;
           status = await waitForVoiceFlight(
             flight,
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index a464c94bd..14d008933 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -570,6 +570,71 @@ test('a motion follows a later fly-to in the same reply that cancels its flight'
   assert.equal(result.motion, 'orbit');
 });
 
+test('a motion follows a later fly-to whose start cancels its geocode', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  const searches = [];
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+      searches.push({ query, options, resolve });
+    }),
+  });
+  const flyA = runner('fly_to_location', { query: 'Place A' });
+  const moved = runner('move_camera', { motion: 'orbit' });
+  const movedDone = settledYet(moved);
+  const flyB = runner('fly_to_location', { query: 'Place B' });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  // B takes navigation authority, so A's lookup comes back cancelled.
+  searches[0].resolve({ cancelled: true });
+  assert.equal((await flyA).cancelled, true);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(movedDone(), false, 'the orbit must follow B, not drop');
+  searches[1].resolve({ label: 'Place B', navigationMode: 'city-overview' });
+  assert.equal((await flyB).ok, true);
+  searches[1].options.onComplete();
+  const result = await moved;
+  assert.equal(result.ok, true);
+  assert.equal(result.motion, 'orbit');
+});
+
+test('a motion does not run at a flight that lands while the next place is looked up', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
+  const searches = [];
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+      searches.push({ query, options, resolve });
+    }),
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  const movedDone = settledYet(moved);
+  const flyB = runner('fly_to_location', { query: 'Place B' });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  // Deferred navigation leaves A flying while B is looked up, and A lands.
+  const before = order.length;
+  flights[0].complete();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(movedDone(), false, 'the tilt must wait for B');
+  assert.equal(
+    order.slice(before).includes('cancel'),
+    false,
+    'the tilt must not take navigation and cancel B',
+  );
+  searches[0].resolve({ label: 'Place B', navigationMode: 'city-overview' });
+  assert.equal((await flyB).ok, true);
+  searches[0].options.onComplete();
+  const result = await moved;
+  assert.equal(result.ok, true);
+  assert.equal(result.motion, 'tilt');
+});
+
 test('a stale motion does not follow a newer reply\'s fly-to', async () => {
   const { viewer, styleManager, flights } = tiltAfterFlightHarness();
   const runner = createGevActionRunner({

From b683b8a64b7d71e33f468469e4b7494f60f6c6ff Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Wed, 4 Nov 2026 14:29:37 +0530
Subject: [PATCH 23/71] Look past voice lookups that found nothing

A motion queued behind a voice fly-to acts on the last flight that moved the camera. A later lookup that was not found, threw, or was cancelled once a newer voice fly-to had begun moved nothing, so the motion looks past it rather than refusing or running early and cancelling the flight still in the air. It never acts at a flight older than the one it started waiting on. A lookup cancelled while still the latest voice flight (a search, a share link, Cockpit) still refuses.

The top-down no-op now reports the camera's real pitch.
---
 src/cameraTilt.test.mjs       |   1 +
 src/cameraVerbs.js            |   4 +-
 src/voice/gevActions.js       | 108 ++++++++++++++++-------
 src/voice/gevActions.test.mjs | 156 ++++++++++++++++++++++++++++++++++
 4 files changed, 237 insertions(+), 32 deletions(-)

diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index 93bbf246e..d372d0746 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -185,6 +185,7 @@ for (const pitch of [-90, -89]) {
     const result = moveCamera({ motion: 'tilt', pitchDeg: pitch });
     assert.equal(result.ok, true);
     assert.equal(result.unchanged, true);
+    assert.equal(result.pitchDeg, Math.round(before));
     assert.equal(getActiveCameraMotion(), null);
     assert.equal(pitchDeg(h.camera), before);
   });
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 380a737f0..c1e5c5d1a 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -1682,7 +1682,9 @@ export function moveCamera(args = {}, runNavigation = null) {
         ok: true,
         action: 'move_camera',
         motion,
-        pitchDeg: Math.round(Cesium.Math.toDegrees(tiltToPitch)),
+        pitchDeg: Math.round(
+          Cesium.Math.toDegrees(atTopDown ? from : tiltToPitch),
+        ),
         unchanged: true,
       };
     }
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index c9bc811a4..83cdea367 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -288,9 +288,10 @@ export function createGevActionRunner({
     ? { ...SPEECH_BUILDERS, ...speechBuilders }
     : SPEECH_BUILDERS;
   const _layerEnabledAt = new Map();
-  // The latest voice flight. A tilt in the same reply as "fly to X" waits for
-  // it to land: run at once, its navigation cancelled the flight, or the
-  // flight (still geocoding) then replaced the tilt.
+  // The latest voice flight. A tilt, orbit, pan or rotate in the same reply
+  // as "fly to X" waits for it to land: run at once, its navigation
+  // cancelled the flight, or the flight (still geocoding) then replaced the
+  // motion. The wait follows later fly-tos (voiceFlightTarget).
   let voiceFlight = null;
   let analystEngine;
   // Area handles live for this runner (the page): resolve_area, the
@@ -1143,10 +1144,11 @@ export function createGevActionRunner({
           runOptions,
         );
       }
-      // Chained fly-tos in one reply: a grab during the earlier one counts.
-      const flight = trackVoiceFlight(
-        voiceFlight && !voiceFlight.done ? voiceFlight.inputCount : undefined,
-      );
+      // Chained fly-tos: a grab during the earlier one counts. The flight
+      // replaced is the last one that moved, past lookups that found nothing.
+      const prior = voiceFlightTarget(voiceFlight);
+      const replaced = prior && !prior.done ? prior : null;
+      const flight = trackVoiceFlight(replaced?.inputCount, replaced);
       voiceFlight = flight;
       const flown = flyToRequestedLocation(viewer, args, {
         onFlightEnd: flight.settle,
@@ -1177,13 +1179,23 @@ export function createGevActionRunner({
           if (viewer.trackedEntity) stopAllTracking(viewer, dataManager);
         },
       });
-      // No flight started (not found, refused, cancelled): nothing to wait for.
-      flown.then(
-        (result) => {
-          if (result?.ok !== true) flight.settle('failed');
-        },
-        () => flight.settle('failed'),
-      );
+      // No flight started: nothing to wait for. A lookup that was not found,
+      // threw, or was cancelled once a newer voice fly-to had begun (which
+      // takes navigation from it) moved nothing, so a queued motion looks
+      // past it to the flight it replaced. One cancelled while still the
+      // latest voice flight lost navigation to something else (a search, a
+      // share link, Cockpit): the motion then refuses. A flight its own hooks
+      // already settled (cancelled mid-air) keeps its status.
+      const notStarted = () => {
+        if (!flight.done) flight.movedNothing = true;
+        flight.settle('failed');
+      };
+      flown.then((result) => {
+        if (result?.ok === true) return;
+        if (result?.cancelled && voiceFlight === flight)
+          flight.settle('failed');
+        else notStarted();
+      }, notStarted);
       return flown;
     }
 
@@ -1287,39 +1299,45 @@ export function createGevActionRunner({
 
     if (name === 'move_camera') {
       const motion = String(args.motion || '').toLowerCase();
+      // A lookup that already found nothing does not hide the last flight
+      // that moved: running now would cancel that flight mid-air.
+      const pending = voiceFlightTarget(voiceFlight);
       if (
         VOICE_FLIGHT_WAITING_MOTIONS.has(motion) &&
-        voiceFlight &&
-        !voiceFlight.done
+        pending &&
+        !pending.done
       ) {
         // Bad arguments are refused now, not after waiting on the flight.
         const argsError = moveCameraArgsError(args);
         if (argsError) return argsError;
         const deadline = Date.now() + VOICE_FLIGHT_WAIT_MS;
-        let flight = voiceFlight;
+        const start = pending;
+        let flight = start;
         let status = await waitForVoiceFlight(
           flight,
           runOptions.signal,
           deadline,
         );
-        // A later fly-to in the same reply replaces this one: follow it to
-        // where the camera lands, within the same deadline. Its status does
-        // not matter. A geocode that loses navigation reports failed, and a
-        // flight left flying while the next place is looked up can still
-        // land; running there would take navigation and cancel the newer one.
-        while (
-          voiceFlight !== flight &&
-          status !== 'aborted' &&
-          status !== 'timeout' &&
-          current()
-        ) {
-          flight = voiceFlight;
+        // A later fly-to replaces this one: follow it to where the camera
+        // lands, within the same deadline, whatever this flight reported. A
+        // geocode that loses navigation reports failed, and a flight left
+        // flying while the next place is looked up can still land; running
+        // there would take navigation and cancel the newer one. A later
+        // lookup that found nothing moved nothing, so the motion acts on the
+        // last flight it saw that did move the camera.
+        let landed = flight.movedNothing ? null : { flight, status };
+        while (status !== 'aborted' && status !== 'timeout' && current()) {
+          const target = voiceFlightTarget(voiceFlight, start);
+          if (!target || target === flight) break;
+          flight = target;
           status = await waitForVoiceFlight(
             flight,
             runOptions.signal,
             deadline,
           );
+          if (!flight.movedNothing) landed = { flight, status };
         }
+        if (flight.movedNothing && landed) ({ flight, status } = landed);
         if (!current())
           return { ok: false, action: 'move_camera', cancelled: true };
         if (status !== 'arrived')
@@ -2939,11 +2957,25 @@ async function frameOverhead(viewer, dataManager, styleManager, args = {}) {
   );
 }
 
-/** A voice flight's end: 'arrived', 'cancelled' or 'failed', settled once. */
-function trackVoiceFlight(inputCount = manualCameraInputCount()) {
+let voiceFlightCount = 0;
+
+/**
+ * A voice flight's end: 'arrived', 'cancelled' or 'failed', settled once.
+ * `replaced` is the last flight that moved, if still pending when this one
+ * began (past lookups that found nothing). It is kept only
+ * while this one may turn out to have moved nothing (a lookup that found no
+ * place), so a queued motion can look past it.
+ */
+function trackVoiceFlight(
+  inputCount = manualCameraInputCount(),
+  replaced = null,
+) {
   let resolve;
   const flight = {
     done: false,
+    seq: (voiceFlightCount += 1),
+    replaced,
+    movedNothing: false,
     // Manual input after this means the user took the camera mid-flight.
     inputCount,
     ended: new Promise((settle) => {
@@ -2952,12 +2984,26 @@ function trackVoiceFlight(inputCount = manualCameraInputCount()) {
     settle: (status) => {
       if (flight.done) return;
       flight.done = true;
+      if (!flight.movedNothing) flight.replaced = null;
       resolve(status);
     },
   };
   return flight;
 }
 
+/**
+ * The flight a motion queued since `start` acts on: the latest one that
+ * actually started. A lookup that found nothing moved nothing, so look past
+ * it to the flight it replaced, but never to one older than `start` (a flight
+ * from an earlier reply). Null when every later lookup found nothing. With
+ * no `start`, the latest flight that started, however old.
+ */
+function voiceFlightTarget(latest, start = null) {
+  let flight = latest;
+  while (flight?.movedNothing) flight = flight.replaced;
+  return flight && (!start || flight.seq >= start.seq) ? flight : null;
+}
+
 /**
  * Longest a motion waits for its flight (geocode plus flight, which is about
  * 2 s) before giving up. The wait also holds the tool output, and on Gemini
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index 14d008933..ece2f92e0 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -635,6 +635,162 @@ test('a motion does not run at a flight that lands while the next place is looke
   assert.equal(result.motion, 'tilt');
 });
 
+// A later fly-to that finds nothing moves nothing: the motion still runs where
+// the earlier flight lands, whether the lookup fails before or after that.
+for (const order of ['lands first', 'not found first']) {
+  test(`a motion runs at its flight when a later fly-to finds nothing (${order})`, async (t) => {
+    t.after(() => interruptCameraMotion('test-cleanup'));
+    const harness = tiltAfterFlightHarness();
+    const { viewer, styleManager, flights } = harness;
+    const searches = [];
+    const runner = createGevActionRunner({
+      viewer,
+      styleManager,
+      dataManager: { layers: new Map(), getAll: () => [] },
+      searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+        searches.push({ query, options, resolve });
+      }),
+    });
+    assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+    const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+    const flyB = runner('fly_to_location', { query: 'Nowhere' });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    if (order === 'lands first') flights[0].complete();
+    searches[0].resolve(null);
+    assert.equal((await flyB).ok, false);
+    if (order !== 'lands first') flights[0].complete();
+    const result = await moved;
+    assert.equal(result.ok, true, result.error);
+    assert.equal(result.motion, 'tilt');
+  });
+}
+
+test('a motion beside a fly-to that finds nothing never acts at an earlier reply\'s flight', async () => {
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const searches = [];
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+      searches.push({ query, options, resolve });
+    }),
+  });
+  // Reply 1: "fly to Austin", still flying.
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  // Reply 2: "fly to Nowhere and tilt".
+  const flyB = runner('fly_to_location', { query: 'Nowhere' });
+  const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  searches[0].resolve(null);
+  assert.equal((await flyB).ok, false);
+  flights[0].complete();
+  const result = await moved;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /did not arrive/);
+});
+
+// Two later lookups that both find nothing, in either order, leave the motion
+// acting where the first flight landed.
+for (const first of [0, 1]) {
+  test(`a motion looks past two lookups that found nothing (lookup ${first + 1} fails first)`, async (t) => {
+    t.after(() => interruptCameraMotion('test-cleanup'));
+    const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+    const searches = [];
+    const runner = createGevActionRunner({
+      viewer,
+      styleManager,
+      dataManager: { layers: new Map(), getAll: () => [] },
+      searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+        searches.push({ query, options, resolve });
+      }),
+    });
+    assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+    const moved = runner('move_camera', { motion: 'orbit' });
+    const flyB = runner('fly_to_location', { query: 'Nowhere B' });
+    const flyC = runner('fly_to_location', { query: 'Nowhere C' });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    searches[first].resolve(null);
+    searches[1 - first].resolve(null);
+    assert.equal((await flyB).ok, false);
+    assert.equal((await flyC).ok, false);
+    flights[0].complete();
+    const result = await moved;
+    assert.equal(result.ok, true, result.error);
+  });
+}
+
+test('a lookup cancelled by a newer one that finds nothing does not hide the flight that landed', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const searches = [];
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+      searches.push({ query, options, resolve });
+    }),
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  const flyB = runner('fly_to_location', { query: 'Place B' });
+  const flyC = runner('fly_to_location', { query: 'Nowhere C' });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  flights[0].complete();
+  // C's start takes navigation from B's lookup; C then finds nothing.
+  searches[0].resolve({ cancelled: true });
+  searches[1].resolve(null);
+  assert.equal((await flyB).cancelled, true);
+  assert.equal((await flyC).ok, false);
+  const result = await moved;
+  assert.equal(result.ok, true, result.error);
+});
+
+test('a motion sent after a fly-to that found nothing still waits for the flight before it', async (t) => {
+  // Serial dispatch: "fly to Austin, fly to Nowhere, tilt", one call at a time.
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: async () => null,
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  assert.equal((await runner('fly_to_location', { query: 'Nowhere' })).ok, false);
+  const before = order.length;
+  const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  const movedDone = settledYet(moved);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(movedDone(), false, 'the tilt must wait for the Austin flight');
+  assert.equal(order.slice(before).includes('cancel'), false);
+  flights[0].complete();
+  assert.equal((await moved).ok, true);
+});
+
+test('two lookups that found nothing in a row still leave the motion waiting for the flight', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: async () => null,
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  assert.equal((await runner('fly_to_location', { query: 'Nowhere' })).ok, false);
+  assert.equal((await runner('fly_to_location', { query: 'Nowhere 2' })).ok, false);
+  const before = order.length;
+  const moved = runner('move_camera', { motion: 'orbit' });
+  const movedDone = settledYet(moved);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(movedDone(), false, 'the orbit must wait for the Austin flight');
+  assert.equal(order.slice(before).includes('cancel'), false);
+  flights[0].complete();
+  assert.equal((await moved).ok, true);
+});
+
 test('a stale motion does not follow a newer reply\'s fly-to', async () => {
   const { viewer, styleManager, flights } = tiltAfterFlightHarness();
   const runner = createGevActionRunner({

From 4c9b27dc204d52603942be7803e2432d2e8b1b0e Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Wed, 4 Nov 2026 14:48:07 +0530
Subject: [PATCH 24/71] Keep a settled flight in reach of a later failed lookup

A new voice fly-to now records the last flight that moved as the one it replaced, landed or not; only a still-flying one passes on its manual-input count. A slow lookup cancelled by a direct flight that landed, followed by a lookup that found nothing, used to drop the queued motion, and a cancelled direct flight in the same place let it fall back to an older landing.
---
 src/voice/gevActions.js       | 22 +++++++------
 src/voice/gevActions.test.mjs | 59 +++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+), 9 deletions(-)

diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index 83cdea367..089d95be0 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -1144,11 +1144,14 @@ export function createGevActionRunner({
           runOptions,
         );
       }
-      // Chained fly-tos: a grab during the earlier one counts. The flight
-      // replaced is the last one that moved, past lookups that found nothing.
+      // Chained fly-tos: a grab during an earlier one still flying counts.
+      // The flight replaced is the last one that moved, past lookups that
+      // found nothing.
       const prior = voiceFlightTarget(voiceFlight);
-      const replaced = prior && !prior.done ? prior : null;
-      const flight = trackVoiceFlight(replaced?.inputCount, replaced);
+      const flight = trackVoiceFlight(
+        prior && !prior.done ? prior.inputCount : undefined,
+        prior,
+      );
       voiceFlight = flight;
       const flown = flyToRequestedLocation(viewer, args, {
         onFlightEnd: flight.settle,
@@ -2961,10 +2964,10 @@ let voiceFlightCount = 0;
 
 /**
  * A voice flight's end: 'arrived', 'cancelled' or 'failed', settled once.
- * `replaced` is the last flight that moved, if still pending when this one
- * began (past lookups that found nothing). It is kept only
- * while this one may turn out to have moved nothing (a lookup that found no
- * place), so a queued motion can look past it.
+ * `replaced` is the last flight that moved when this one began (past lookups
+ * that found nothing), landed or not. It is kept only while this one may turn
+ * out to have moved nothing (a lookup that found no place), so a queued
+ * motion can look past it to that flight and its outcome.
  */
 function trackVoiceFlight(
   inputCount = manualCameraInputCount(),
@@ -2996,7 +2999,8 @@ function trackVoiceFlight(
  * actually started. A lookup that found nothing moved nothing, so look past
  * it to the flight it replaced, but never to one older than `start` (a flight
  * from an earlier reply). Null when every later lookup found nothing. With
- * no `start`, the latest flight that started, however old.
+ * no `start`, the latest flight that started, back through lookups that
+ * found nothing.
  */
 function voiceFlightTarget(latest, start = null) {
   let flight = latest;
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index ece2f92e0..678a13659 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -791,6 +791,65 @@ test('two lookups that found nothing in a row still leave the motion waiting for
   assert.equal((await moved).ok, true);
 });
 
+// A flight that already settled is still what a later failed lookup replaced.
+test('a motion acts at a landed flight that a later failed lookup replaced', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const searches = [];
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+      searches.push({ query, options, resolve });
+    }),
+  });
+  const flyA = runner('fly_to_location', { query: 'Slow A' });
+  const moved = runner('move_camera', { motion: 'orbit' });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  flights[0].complete();
+  const flyC = runner('fly_to_location', { query: 'Nowhere C' });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  // B's start made A's lookup stale; C then finds nothing.
+  searches[0].resolve({ cancelled: true });
+  searches[1].resolve(null);
+  assert.equal((await flyA).cancelled, true);
+  assert.equal((await flyC).ok, false);
+  const result = await moved;
+  assert.equal(result.ok, true, result.error);
+});
+
+test('a motion refuses when the flight a later failed lookup replaced was cancelled', async () => {
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const searches = [];
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+      searches.push({ query, options, resolve });
+    }),
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'orbit' });
+  const flyA = runner('fly_to_location', { query: 'Slow A' });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  // The motion sees Austin land, then follows A's lookup.
+  flights[0].complete();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  flights[1].cancel();
+  const flyC = runner('fly_to_location', { query: 'Nowhere C' });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  searches[0].resolve({ cancelled: true });
+  searches[1].resolve(null);
+  assert.equal((await flyA).cancelled, true);
+  assert.equal((await flyC).ok, false);
+  const result = await moved;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /did not arrive/);
+});
+
 test('a stale motion does not follow a newer reply\'s fly-to', async () => {
   const { viewer, styleManager, flights } = tiltAfterFlightHarness();
   const runner = createGevActionRunner({

From 99831ea19b2ff5b9fff9d40e26a11422e277bb99 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Wed, 4 Nov 2026 16:34:39 +0400
Subject: [PATCH 25/71] Keep STALE on Contacts while a poll is in flight

A poll that returned the same stale snapshot dropped STALE from the
Contacts cohort until the next answer, because the in-flight loading flag
outranked stale and the source revision ignored the provider name. A
source that has answered now reads its status without the loading flag;
one that has never answered (AIS first connect) still reads as loading,
so it shows no STALE before any snapshot exists.
---
 src/layers/awareness/queries.js               |   1 +
 .../awareness/staleAfterLoading.test.mjs      | 159 ++++++++++++++++++
 src/layers/awareness/subject.js               |   8 +-
 src/layers/vessels/ownership.test.mjs         |   2 -
 src/ui/cockpitContext.test.mjs                |   2 -
 5 files changed, 167 insertions(+), 5 deletions(-)
 create mode 100644 src/layers/awareness/staleAfterLoading.test.mjs

diff --git a/src/layers/awareness/queries.js b/src/layers/awareness/queries.js
index 593c85ebf..0c5bd78f3 100644
--- a/src/layers/awareness/queries.js
+++ b/src/layers/awareness/queries.js
@@ -91,6 +91,7 @@ export function createQueries({ state: layerState, services, parts, source }) {
         stats.count ?? null,
         stats.status || null,
         stats.error || null,
+        stats.source || null,
       ];
     })
       .map((parts) => parts.join(':'))
diff --git a/src/layers/awareness/staleAfterLoading.test.mjs b/src/layers/awareness/staleAfterLoading.test.mjs
new file mode 100644
index 000000000..7128f4958
--- /dev/null
+++ b/src/layers/awareness/staleAfterLoading.test.mjs
@@ -0,0 +1,159 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { createQueries } from './queries.js';
+import { createSubject } from './subject.js';
+import { createModel } from './model.js';
+import { summarizeAwarenessCohort } from '../../data/militaryAwarenessEngine.js';
+import { layerFeedState } from '../../data/feedState.js';
+import aisLiveVesselsLayer, {
+  _setVesselStateForTest,
+  _beginAisSessionForTest,
+  _applyAisFeedSnapshotForTest,
+  _setAisRuntimeForTest,
+} from '../../data/aisLiveVessels.js';
+
+test('a poll that returns the same stale AIS snapshot restores STALE on Contacts cohorts', () => {
+  globalThis.document ??= { body: null };
+  const services = {
+    installations: { getNearby: () => [], getStats: () => ({}) },
+    flights: { getNearby: () => [] },
+    military: { getNearby: () => [] },
+    vessels: { getNearby: () => [] },
+  };
+  const layerState = {
+    enabled: true,
+    passive: true,
+    sourceRevision: '',
+    cohortPages: new Map(),
+    subject: {
+      id: 'site-1',
+      layerId: 'military-installations',
+      label: 'Site',
+      position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
+    },
+  };
+  let states;
+  const parts = {
+    navigation: {
+      summarizeAwarenessCohortForNavigation: (items, source) =>
+        summarizeAwarenessCohort(items, source),
+      isFlightLayer: (id) => id === 'flights' || id === 'military',
+    },
+    rendering: { renderVisual() {}, scheduleDirectionOverlayUpdate() {} },
+    panel: { renderResults() {} },
+  };
+  const realQueries = createQueries({ state: layerState, services, parts });
+  parts.queries = { ...realQueries, collectSourceStates: () => states };
+  parts.model = createModel({ state: layerState, services, parts });
+  const subject = createSubject({ state: layerState, services, parts });
+  const flights = (lastUpdate) => ({
+    available: true, enabled: true, stale: false,
+    stats: { source: 'OpenSky Network', count: 4, lastUpdate },
+  });
+  const vessels = (loading) => ({
+    available: true, enabled: true, stale: true,
+    stats: { source: 'Datalastic', stale: true, count: 3, lastUpdate: 1000, loading },
+  });
+  const rest = {
+    military: { available: true, enabled: true, stale: false, stats: { source: 'adsb.lol', fallback: false, count: 1, lastUpdate: 1 } },
+    'military-installations': { available: true, enabled: true, stale: false, stats: { coverage: { kind: 'subject', radiusM: 100000 } } },
+  };
+  const ais = () => layerState.results.cohorts.find((c) => c.id === 'ais-live-vessels');
+
+  // 1. Stale AIS cache, nothing loading.
+  states = { flights: flights(1), 'ais-live-vessels': vessels(false), ...rest };
+  subject.refreshSelectedSubject(true);
+  assert.equal(ais().sourceStatus, 'stale');
+
+  // 2. AIS re-poll in flight while the flights poll lands (revision changes).
+  states = { flights: flights(2), 'ais-live-vessels': vessels(true), ...rest };
+  subject.refreshSelectedSubject();
+  assert.equal(ais().sourceStatus, 'stale', 'a poll in flight keeps the snapshot stale');
+
+  // 3. AIS poll returns the same stale snapshot; only loading flips back.
+  states = { flights: flights(2), 'ais-live-vessels': vessels(false), ...rest };
+  subject.refreshSelectedSubject();
+  subject.refreshSelectedSubject();
+  assert.equal(ais().sourceStatus, 'stale', 'Layers reads STALE again; Contacts/Cockpit must too');
+});
+
+function fakeRuntime() {
+  return {
+    now: () => 1000,
+    setTimeout: () => ({}),
+    clearTimeout() {},
+  };
+}
+
+test('first AIS connect (no snapshot yet) carries no STALE on the Contacts cohort', () => {
+  globalThis.document ??= { body: null };
+  _setAisRuntimeForTest(fakeRuntime());
+  _setVesselStateForTest({ viewer: {}, records: [] });
+  try {
+    _beginAisSessionForTest();
+    // What server/providers/vessels/ais-live.js answers while its socket connects.
+    _applyAisFeedSnapshotForTest({}, {
+      rows: [], source: 'AISStream', status: 'connecting', refreshing: true,
+    });
+    const vesselStats = aisLiveVesselsLayer.getStats();
+    assert.equal(vesselStats.loading, true);
+    assert.equal(vesselStats.stale, true);
+    assert.equal(vesselStats.lastUpdate, null);
+    assert.equal(layerFeedState(vesselStats), 'loading', 'Layers chip reads LOADING');
+
+    const flightsStats = { source: 'OpenSky Network', count: 2, lastUpdate: 5 };
+    const militaryStats = { source: 'adsb.lol', fallback: false, count: 1, lastUpdate: 5 };
+    const installStats = { coverage: { kind: 'subject', radiusM: 100000 } };
+    const statsById = {
+      flights: flightsStats,
+      military: militaryStats,
+      'ais-live-vessels': vesselStats,
+      'military-installations': installStats,
+    };
+    const services = {
+      installations: { getNearby: () => [], getStats: () => installStats },
+      flights: { getNearby: () => [] },
+      military: { getNearby: () => [] },
+      vessels: aisLiveVesselsLayer,
+    };
+    const layerState = {
+      enabled: true,
+      passive: true,
+      sourceRevision: '',
+      cohortPages: new Map(),
+      dataManager: {
+        isEnabled: () => true,
+        getLayerLifecycleState: () => ({ enabled: true, lifecycleState: 'enabled' }),
+        layers: new Map(Object.entries(statsById).map(([id, s]) => [id, { module: { getStats: () => s } }])),
+      },
+      subject: {
+        id: 'site-1',
+        layerId: 'military-installations',
+        label: 'Site',
+        position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
+      },
+    };
+    const parts = {
+      navigation: {
+        summarizeAwarenessCohortForNavigation: (items, source) => summarizeAwarenessCohort(items, source),
+        isFlightLayer: (id) => id === 'flights' || id === 'military',
+      },
+      rendering: { renderVisual() {}, scheduleDirectionOverlayUpdate() {} },
+      panel: { renderResults() {} },
+    };
+    parts.queries = createQueries({ state: layerState, services, parts });
+    parts.model = createModel({ state: layerState, services, parts });
+    const subject = createSubject({ state: layerState, services, parts });
+
+    const vesselsSource = parts.queries.collectSourceStates()['ais-live-vessels'];
+    assert.equal(vesselsSource.available, false, 'never-answered source is unavailable');
+
+    subject.refreshSelectedSubject(true);
+    const ais = layerState.results.cohorts.find((c) => c.id === 'ais-live-vessels');
+    assert.equal(ais.sourceStatus, null, 'no snapshot yet: no STALE label, Layers says LOADING');
+  } finally {
+    _setVesselStateForTest({ enabled: false });
+    _setAisRuntimeForTest();
+  }
+});
diff --git a/src/layers/awareness/subject.js b/src/layers/awareness/subject.js
index a555d332e..32123d248 100644
--- a/src/layers/awareness/subject.js
+++ b/src/layers/awareness/subject.js
@@ -54,8 +54,14 @@ export function createSubject({ state: layerState, services, parts, source }) {
     const installationsState = sourceStates['military-installations'];
     const evaluatedAt = Date.now();
     // Whether the provider answered as a fallback or from a stale snapshot.
+    // A poll in flight does not change that, and the source revision ignores it.
+    // Before the first answer there is no snapshot, so loading stays.
     const sourceStatus = (sourceState) => {
-      const feedState = layerFeedState(sourceState.stats);
+      const feedState = layerFeedState(
+        sourceState.available
+          ? { ...sourceState.stats, loading: false }
+          : sourceState.stats,
+      );
       return feedState === 'fallback' || feedState === 'stale'
         ? feedState
         : null;
diff --git a/src/layers/vessels/ownership.test.mjs b/src/layers/vessels/ownership.test.mjs
index a838a8099..2404434a0 100644
--- a/src/layers/vessels/ownership.test.mjs
+++ b/src/layers/vessels/ownership.test.mjs
@@ -411,8 +411,6 @@ test('empty coverage cannot hide stale, incomplete or rejected source data', asy
 });
 
 test('vessel stats name the provider the last snapshot reported', async () => {
-  // HAL-721: Contacts named a fixed AIS provider while this layer showed the
-  // one its server reported.
   const { layer } = setup({
     label: 'Vessels',
     async getSnapshot() {
diff --git a/src/ui/cockpitContext.test.mjs b/src/ui/cockpitContext.test.mjs
index a8d6616d5..c2f20abcf 100644
--- a/src/ui/cockpitContext.test.mjs
+++ b/src/ui/cockpitContext.test.mjs
@@ -167,8 +167,6 @@ test('a snapshot fills the card and keeps classes other code sets', async (t) =>
 });
 
 test('each count names the provider its snapshot reports, with its feed state', async (t) => {
-  // HAL-721: the counters named fixed providers while the layer and the
-  // Contacts list named the one that answered.
   const reported = snapshot();
   reported.cohorts[0].source = 'adsb.lol';
   reported.cohorts[0].sourceStatus = 'fallback';

From 53ea76251f46fd2b6f0c08914a30bbbb74a1f423 Mon Sep 17 00:00:00 2001
From: manjunath22466 <301209272+manjunath22466@users.noreply.github.com>
Date: Wed, 4 Nov 2026 19:34:30 +0530
Subject: [PATCH 26/71] fix(voice): keep chat's view across a provider switch
 and clear stale errors

Switching AI Provider in Settings opened from chat rebuilt the voice
control, so Settings fell back to voice and the dock went idle, widening
the wings. The switch now carries chat's Settings, or chat itself, to the
new provider as it already carries the input mode; the conversation still
starts fresh and focus stays on the provider choice.

After a voice error, opening chat or closing the voice panel left the dock
red on ERROR, because both stopped only an active session. They now also
end a session left in error, which returns the dock to idle.
---
 docs/CURRENT-STATE.md               |  7 ++++--
 src/voice/chatControl.js            | 34 ++++++++++++++++++++++++++++-
 src/voice/chatControlView.test.mjs  | 31 ++++++++++++++++++++++++++
 src/voice/panel/host.test.mjs       | 21 ++++++++++++++++++
 src/voice/providerCommands.js       |  7 ++++--
 src/voice/providerCommands.test.mjs | 15 +++++++++++++
 src/voice/sessionCommands.js        | 11 +++++++++-
 7 files changed, 120 insertions(+), 6 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index c3e15ea4d..fa2287567 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -766,9 +766,12 @@ each side, and the empty Voice Preview suggests things to say until voice
 starts. Settings opened from chat keep chat's frame and show the shared AI
 provider, the quick-commands option and then the voice preferences (Voice
 Preview, inactivity timeout and model tier), so they stay in reach while
-Preview is off, with Back to chat; voice Settings show Back to voice. Escape steps back from either Settings view, closes Voice
+Preview is off, with Back to chat; voice Settings show Back to voice. Switching
+AI Provider keeps that view: chat's Settings, or chat itself, stay as they were
+for the new provider. Escape steps back from either Settings view, closes Voice
 Preview, and does nothing in chat. Closing chat ends a typed session, and the
-voice panel's close turns voice off. Asking the assistant from chat to open
+voice panel's close turns voice off. Opening chat or closing the voice panel
+also clears a voice error left on the dock. Asking the assistant from chat to open
 Voice Settings or Voice Preview puts chat away, minimized or not, and shows the
 voice panel; the typed conversation and its running reply carry on, and the
 chat button brings them back.
diff --git a/src/voice/chatControl.js b/src/voice/chatControl.js
index 6ab5bf494..d366181a7 100644
--- a/src/voice/chatControl.js
+++ b/src/voice/chatControl.js
@@ -94,7 +94,10 @@ export function bindChatControl({ ui, session, onOpen, dataManager }) {
       : '';
   function open({ focus = true } = {}) {
     leaveChatSettings();
-    if (!isTyped() && session.isActive()) session.stop();
+    // Chat replaces voice, a stale voice error included, so the dock stops
+    // showing it.
+    if (!isTyped() && (session.isActive() || session.state === 'error'))
+      session.stop();
     onOpen?.();
     ui.update('chat', { open: true, minimized: false, rows: 2, authNote });
     sync();
@@ -413,10 +416,39 @@ export function bindChatControl({ ui, session, onOpen, dataManager }) {
     }),
   ];
   sync();
+  // What a provider switch carries to the next mount: chat's Settings or
+  // chat itself, never the conversation.
+  function presentation() {
+    if (inChatSettings()) {
+      const { frameWidth, frameHeight } = ui.state.voicePanel;
+      return { view: 'settings', frameWidth, frameHeight };
+    }
+    if (chat().open) return { view: chat().minimized ? 'minimized' : 'open' };
+    return null;
+  }
+  // Restored without moving focus: the switch keeps it on the provider choice.
+  function restorePresentation(state) {
+    if (disposed || !state) return;
+    if (state.view === 'settings') {
+      ui.update('voicePanel', {
+        context: 'chat',
+        ...(state.frameWidth && {
+          frameWidth: state.frameWidth,
+          frameHeight: state.frameHeight,
+        }),
+      });
+      ui.update('chat', { backVisible: true });
+      return sync();
+    }
+    open({ focus: false });
+    if (state.view === 'minimized') minimize({ focus: false });
+  }
   return {
     close,
     minimize,
     restore: open,
+    presentation,
+    restorePresentation,
     get minimized() {
       return chat().open && chat().minimized;
     },
diff --git a/src/voice/chatControlView.test.mjs b/src/voice/chatControlView.test.mjs
index 5dee1ad97..e329a2dc3 100644
--- a/src/voice/chatControlView.test.mjs
+++ b/src/voice/chatControlView.test.mjs
@@ -364,3 +364,34 @@ test('the chat gear is named for the settings it opens', async (t) => {
     'Settings',
   );
 });
+
+test('a provider switch carries chat Settings or chat itself to the next mount', async (t) => {
+  const mount = () => {
+    const ui = createTestVoiceUi({ panel: true });
+    const chat = bindChatControl({ ui, session: typedSession() });
+    t.after(() => chat.destroy());
+    return { ui, chat };
+  };
+  // Chat's Settings: the next mount shows Settings in chat's frame again.
+  const before = mount();
+  before.ui.emit('chat-button');
+  before.ui.update('voicePanel', { hidden: false });
+  before.ui.emit('settings-button');
+  const settings = before.chat.presentation();
+  assert.equal(settings.view, 'settings');
+  const after = mount();
+  after.chat.restorePresentation(settings);
+  assert.equal(after.ui.state.voicePanel.context, 'chat');
+  assert.equal(after.ui.state.chat.backVisible, true);
+  assert.equal(after.ui.state.root.assistantMode, 'chat');
+  // Open and minimized chat come back as they were, without taking focus.
+  for (const view of ['open', 'minimized']) {
+    const next = mount();
+    next.chat.restorePresentation({ view });
+    assert.equal(next.ui.state.chat.open, true);
+    assert.equal(next.ui.state.chat.minimized, view === 'minimized');
+    assert.equal(next.chat.presentation().view, view);
+  }
+  // Idle chat carries nothing.
+  assert.equal(mount().chat.presentation(), null);
+});
diff --git a/src/voice/panel/host.test.mjs b/src/voice/panel/host.test.mjs
index 3c3b3332a..ae5cd1994 100644
--- a/src/voice/panel/host.test.mjs
+++ b/src/voice/panel/host.test.mjs
@@ -1298,6 +1298,27 @@ test('undocking while a tray is open brings the panel back as its bar', async (t
   assert.equal($('#gev-chat-panel').dataset.placement, 'compact');
 });
 
+test('opening chat or closing the voice panel clears a stale voice error', async (t) => {
+  for (const leave of ['chat', 'close']) {
+    const f = mounted(t, { view: true });
+    await f.commands.session.start();
+    f.commands.voicePanel.select('preview');
+    f.instances[0].hooks.emit({
+      type: 'state',
+      state: 'error',
+      detail: 'Lost',
+    });
+    await f.settle();
+    assert.equal($('#gev-voice-control').dataset.status, 'error');
+    assert.equal(f.commands.session.isActive(), false);
+    if (leave === 'chat') $('#gev-chat-button').click();
+    else $('#gev-voice-settings-close').click();
+    await f.settle();
+    assert.equal(f.commands.session.state, 'idle', leave);
+    assert.notEqual($('#gev-voice-control').dataset.status, 'error', leave);
+  }
+});
+
 test('the voice panel close turns voice off', async (t) => {
   const f = mounted(t, { view: true });
   await f.commands.session.start();
diff --git a/src/voice/providerCommands.js b/src/voice/providerCommands.js
index 66201141e..756215c7b 100644
--- a/src/voice/providerCommands.js
+++ b/src/voice/providerCommands.js
@@ -64,6 +64,8 @@ export function createProviderCommands(options, { bind, factories, storage }) {
     const textOnly = Boolean(
       current.session.adapter.getStartOptions?.().textOnly,
     );
+    // The panel stays where the user is: chat's Settings or chat itself.
+    const presentation = current.chatPresentation?.() ?? null;
     const generation = ++mountGeneration;
     voiceEnabled = false;
     current.session.destroy();
@@ -80,7 +82,7 @@ export function createProviderCommands(options, { bind, factories, storage }) {
     } catch {
       /* Storage is optional. */
     }
-    mount();
+    mount(presentation);
     if (resume && !disposed && provider === next)
       void current.session.start({
         pushToTalk,
@@ -142,7 +144,7 @@ export function createProviderCommands(options, { bind, factories, storage }) {
       return typeof value === 'function' ? value.bind(current) : value;
     },
   });
-  function mount() {
+  function mount(presentation = null) {
     voiceEnabled = false;
     const generation = ++mountGeneration;
     current = bind({
@@ -158,6 +160,7 @@ export function createProviderCommands(options, { bind, factories, storage }) {
           handleSessionEvent(event);
       },
       createSession: factories[provider],
+      presentation,
     });
     window.__gevVoiceCommands = facade;
   }
diff --git a/src/voice/providerCommands.test.mjs b/src/voice/providerCommands.test.mjs
index 41d092e73..dfcf77052 100644
--- a/src/voice/providerCommands.test.mjs
+++ b/src/voice/providerCommands.test.mjs
@@ -856,3 +856,18 @@ for (const action of ['stop', 'destroy']) {
     });
   }
 }
+
+test('a provider switch hands chat Settings or chat to the new mount', async (t) => {
+  const f = compositionFixture(t);
+  const first = f.facade.provider;
+  const next = first === 'openai' ? 'gemini' : 'openai';
+  // Without chat open there is nothing to carry.
+  assert.equal(f.mounts[0].controls.chatPresentation(), null);
+  const shown = { view: 'settings', frameWidth: 320, frameHeight: 480 };
+  f.mounts[0].controls.chatPresentation = () => shown;
+  f.select(next);
+  await settle();
+  assert.equal(f.mounts.length, 2);
+  assert.deepEqual(f.mounts[1].options.presentation, shown);
+  assert.equal(f.facade.provider, next);
+});
diff --git a/src/voice/sessionCommands.js b/src/voice/sessionCommands.js
index 78a1816b3..5a8a7e90c 100644
--- a/src/voice/sessionCommands.js
+++ b/src/voice/sessionCommands.js
@@ -40,6 +40,8 @@ export function createVoiceCommands({
   createReticle = createDefaultReticle,
   panelHost = null,
   nativePanelProvider = null,
+  // Chat's Settings or chat itself, carried across a provider switch.
+  presentation = null,
 }) {
   if (resetExisting) window.__gevVoiceCommands?.stop?.({ removeUi: true });
   const ui = createControl(panelHost ? { panel: true } : {});
@@ -225,6 +227,8 @@ export function createVoiceCommands({
         onOpen: () => panelMount?.panel.close(),
       })
     : null;
+  chat?.restorePresentation(presentation);
+  controls.chatPresentation = () => chat?.presentation() ?? null;
   function minimizeVoicePanel() {
     const panel = ui.element('voicePanel');
     const holdsFocus = panel?.contains?.(globalThis.document?.activeElement);
@@ -284,7 +288,12 @@ export function createVoiceCommands({
   // The panel's close turns voice off, as chat's close ends the chat. A typed
   // session belongs to chat, which handles its own close.
   const offClose = ui.on('settings-close', () => {
-    if (!session.isActive() || adapter.getStartOptions?.().textOnly) return;
+    // A voice error the user closes is over too; stopping returns to idle.
+    if (
+      (!session.isActive() && session.state !== 'error') ||
+      adapter.getStartOptions?.().textOnly
+    )
+      return;
     const ticket = panelMount?.stopTicket();
     session.stop();
     panelMount?.closeAfterStop(ticket);

From 46dde909ccc403585d0dc4958430ab2822f790ce Mon Sep 17 00:00:00 2001
From: manjunath22466 <301209272+manjunath22466@users.noreply.github.com>
Date: Wed, 4 Nov 2026 19:37:47 +0530
Subject: [PATCH 27/71] docs(changelog): add #1546 fragment

---
 changelog.d/1546-chat-provider-switch.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 changelog.d/1546-chat-provider-switch.md

diff --git a/changelog.d/1546-chat-provider-switch.md b/changelog.d/1546-chat-provider-switch.md
new file mode 100644
index 000000000..1c3210330
--- /dev/null
+++ b/changelog.d/1546-chat-provider-switch.md
@@ -0,0 +1,5 @@
+- Keep typed chat's view when switching AI Provider: Settings opened from
+  chat, or chat itself, stay as they were for the new provider instead of
+  falling back to voice and widening the dock. Opening chat or closing the
+  voice panel now also clears a voice error left on the dock (Manjunath,
+  @manjunath22466, #1546).

From 55e6c0017c79215220421c6a727742ec8005839d Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Wed, 4 Nov 2026 18:15:16 +0400
Subject: [PATCH 28/71] Tighten the provider-label comments and docs

---
 changelog.d/1521-provider-labels.md | 8 ++++----
 docs/CURRENT-STATE.md               | 2 +-
 src/layers/awareness/subject.js     | 3 +--
 src/layers/vessels/queries.js       | 2 +-
 src/ui/cockpitContext.js            | 1 -
 5 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/changelog.d/1521-provider-labels.md b/changelog.d/1521-provider-labels.md
index d921d9d7b..887d6a775 100644
--- a/changelog.d/1521-provider-labels.md
+++ b/changelog.d/1521-provider-labels.md
@@ -1,4 +1,4 @@
-- Name the provider that answered in the Cockpit Contact counts and the
-  Contacts list, as the Layers panel does, marked `FALLBACK` or `STALE` when
-  it is. The counts no longer read OpenSky while flights come from the adsb.lol
-  fallback, and vessels no longer always read AISStream (German, @gekh, #1521).
+- Cockpit Contact counts and the Contacts list name the provider that
+  answered, marked `FALLBACK` or `STALE` as in the Layers panel. Flights from
+  the adsb.lol fallback no longer read OpenSky, and vessels no longer always
+  read AISStream (German, @gekh, #1521).
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index e845b1472..c6abbf74a 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5112,7 +5112,7 @@ silently demoting every later lookup for the session.
 - Enabled Data Layer controls report normalized feed health on the button (`LOADING`, `DEGRADED`, `STALE`, `FALLBACK`, or `UNAVAILABLE`) while the metadata line retains the source and reason. A partial CelesTrak group failure keeps the usable catalog and reports `DEGRADED`; a total outage keeps last-good catalog data visible but reports `UNAVAILABLE`.
 - On activation it focuses the nearest currently observed aircraft across the civilian and military feeds, with military winning an exact distance tie; if none are available, it focuses an observed AIS vessel. The aircraft search is deliberately uncapped and one refresh-tick retry handles initially empty feeds. This is an attention-priority navigation shortcut, not a high-risk, affiliation, or threat classification.
 - A selected aircraft, AIS vessel, or mapped installation gets a 250 km **context window** with nearby cohort counts, nearest examples, source labels, and stale/unavailable reasons. It emits `NEARBY` or `UNKNOWN`; no detection, engagement, affiliation, or sensor-activity conclusion is calculated.
-- Contacts rows and the Cockpit Contact counts name each cohort's provider as its layer row does: the source the last snapshot reported, marked `FALLBACK` or `STALE` in the same cases. A flight snapshot answered by the adsb.lol regional fallback reads `adsb.lol · FALLBACK` everywhere, never `OpenSky`.
+- Contacts rows and the Cockpit Contact counts name each cohort's provider: the source of the last snapshot, marked `FALLBACK` or `STALE` as its layer row would be. A poll in flight keeps the mark, where the layer row shows `LOADING`. A flight snapshot from the adsb.lol regional fallback reads `adsb.lol · FALLBACK`, not `OpenSky`.
 - The window's edge is drawn on the globe as a 250 km range ring: a 4 px polyline with a 2 px Context-blue core inside a 1 px dark halo on each side, 2.5 km above the ellipsoid (`AWARENESS_RANGE_RING_STYLE` in `src/layers/awareness/policy.js`). The halo keeps it legible over bright desert and snow, dark ocean and forest, and under the FLIR, NVG and CRT styles, where the earlier 1 px ellipse outline disappeared. It is a polyline because WebGL draws ellipse outlines at 1 px whatever width is asked for, drawn as an unpickable primitive rather than an entity so a click or tap on its edge reaches the contact underneath (headless viewers without a primitive collection get a static entity instead); it is rebuilt when the subject moves. Three dim sonar pulses (3 px with a 1 px dark outline, same colours, at most 60% opacity) grow slowly from the subject at constant speed, one every 3 s and each taking 9 s, and arrive at the ring at about a third of that. Behind each pulse a radial gradient in the same blue fades inward over 35% of the radius. One unpickable 250 km disc draws both the pulse lines and the gradient, its shader reading the pulse radii and opacities each frame, so a click or tap near a pulse still reaches the contact underneath; the disc follows the subject by a model-matrix rotation and is rebuilt only after the subject moves 20 km, and not at all while the pulses rest. While the camera is below the disc's 2.5 km height, where it would sweep across the sky, the pulses rest: the disc is hidden and there is no ring flash, no echo and no frame request. Terrain or 3D tiles higher than 2.5 km (the Alps, Andes, Rockies) still cut through the disc and the ring when seen from above, as the ring alone already did; the height check uses the camera's height above the ellipsoid, not above the ground. While pulses run, the ring dims to 40% and flashes to full strength as each pulse reaches it, fading over 1.8 s. As a pulse front crosses a flight, military aircraft or AIS vessel, the detection overlay draws a second bracket around that contact's own bracket, in the pulse blue on the default detection style and in the style's own line colour under NVG, FLIR and CRT, which spreads outward as it fades over 1.4 s (`AWARENESS_RANGE_ECHO`, read through `src/awarenessEcho.js`; no layer's icon is restyled, and mapped installations have no detection bracket). Pulses are born 5 km out, so the subject itself and anything nearer never echo. Pulses run for 9 s (three ring flashes) after a selection or a camera move, fading in and out over 1.2 s, then rest: the ring stays on screen at full strength, the pulses, gradient and echoes are hidden, and nothing asks for frames, so a parked Contacts view is quiet again. Only a camera move within 1.5 s of the user handling the map (pointer, wheel or touch on the Cesium canvas, which covers a drag's inertia, and a drag or touch begun there keeps counting until its last finger or button lifts, even outside the canvas, unless the window loses focus or the page is hidden first; keys typed elsewhere do not count, nor does input while Cesium's camera controls are off, as in the cockpit view, and a gesture still pending when the cockpit or another owner takes the camera is dropped) wakes them; a moving subject and the app's own camera moves (a tracked aircraft, the cockpit view, an orbit, a fly-to) do not, since they move on every refresh. While they run they never hold continuous rendering: each drawn frame arms one render request 80 ms later (the Cyber sonar cadence, `CYBER_SONAR_RENDER_INTERVAL_MS`), so they repaint at about 12.5 fps and never beat the detection lane's 80 ms gate. Under `prefers-reduced-motion`, or in a scene without primitives or preRender and postRender hooks, there are no pulses or echoes and the ring stays on screen; changing the preference mid-session rebuilds the ring. The ring follows a moving subject once it has moved 250 m.
 - For a selected live aircraft or vessel, the context window refreshes from the existing tracker/feed position every 750 ms, so nearest distances and cohort counts follow the subject without introducing a duplicate poll loop.
 - Aircraft cohort membership uses every locally loaded, selectable contact inside the 250 km window, including a plane hidden only by horizon culling or because its 3D model owns the visual. Counts and navigation therefore do not change with the current camera angle or billboard/model handoff.
diff --git a/src/layers/awareness/subject.js b/src/layers/awareness/subject.js
index 32123d248..60f622e29 100644
--- a/src/layers/awareness/subject.js
+++ b/src/layers/awareness/subject.js
@@ -53,8 +53,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
     const vesselsState = sourceStates['ais-live-vessels'];
     const installationsState = sourceStates['military-installations'];
     const evaluatedAt = Date.now();
-    // Whether the provider answered as a fallback or from a stale snapshot.
-    // A poll in flight does not change that, and the source revision ignores it.
+    // A poll in flight keeps FALLBACK or STALE: the revision key ignores loading.
     // Before the first answer there is no snapshot, so loading stays.
     const sourceStatus = (sourceState) => {
       const feedState = layerFeedState(
diff --git a/src/layers/vessels/queries.js b/src/layers/vessels/queries.js
index 48ded012b..d4d9ef796 100644
--- a/src/layers/vessels/queries.js
+++ b/src/layers/vessels/queries.js
@@ -548,7 +548,7 @@ export function createQueries({
         // backing off, say how long until the next attempt instead of leaving
         // the user to guess whether anything is still happening.
         retryInSec: aisRetryInSec(),
-        // The provider the last snapshot named, as flights and military report it.
+        // Same field as flights and military, so Contacts names the provider.
         source: layer.source,
       };
     },
diff --git a/src/ui/cockpitContext.js b/src/ui/cockpitContext.js
index ad73869db..6dc209977 100644
--- a/src/ui/cockpitContext.js
+++ b/src/ui/cockpitContext.js
@@ -111,7 +111,6 @@ export function updateContext(info, heading) {
     if (shown) {
       shown.count = cohort.count === null ? '?' : String(cohort.count);
       shown.unknown = cohort.relationship === 'UNKNOWN';
-      // The provider that answered, named as the Layers panel names it.
       shown.source = sourceStatusLabel(cohort.source, cohort.sourceStatus);
     }
     if (cohort.count === null) unknownCount += 1;

From 82f17e694e9fe2f1b49d0ca322572fcbfa39d51d Mon Sep 17 00:00:00 2001
From: Denis Groshev <denis@halfpixel.ai>
Date: Wed, 4 Nov 2026 17:03:52 +0100
Subject: [PATCH 29/71] refactor(cockpit): place the camera from a per-subject
 eye profile

Split the Cockpit camera update into the aircraft's own front half and a
shared placeCamera that reads the eye's forward and up offsets, pitch and
ground clearance from a profile. The aircraft profile carries the existing
constants, so the aircraft view is unchanged; other subjects can now supply
their own eye.
---
 src/ui/cockpitCamera.js | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/src/ui/cockpitCamera.js b/src/ui/cockpitCamera.js
index c33ba3c15..0a2d1f372 100644
--- a/src/ui/cockpitCamera.js
+++ b/src/ui/cockpitCamera.js
@@ -19,6 +19,14 @@ import {
   COCKPIT_GROUND_WAIT_TIMEOUT_MS,
 } from './cockpitPresentation.js';
 
+/** The aircraft eye: just ahead of and above the reported position. */
+const AIRCRAFT_CAMERA_PROFILE = Object.freeze({
+  forwardM: COCKPIT_FORWARD_OFFSET_M,
+  upM: COCKPIT_UP_OFFSET_M,
+  pitchDeg: COCKPIT_VIEW_PITCH_DEG,
+  minClearanceM: COCKPIT_MIN_GROUND_CLEARANCE_M,
+});
+
 export function update() {
   if (this.destroyed) return false;
   if (!this.active) {
@@ -75,7 +83,20 @@ export function update() {
       COCKPIT_HEADING_SLEW_DPS * dtSec,
     );
   }
+  placeCamera.call(this, target, info, nowMs, dtSec, AIRCRAFT_CAMERA_PROFILE);
+}
 
+/**
+ * Place the camera for one update: advance the inertial anchor, clamp it and
+ * the eye against the rendered surface, and look along the slewed heading.
+ * @param {Cesium.Cartesian3} target Authoritative subject position.
+ * @param {object} info Subject info.
+ * @param {number} nowMs Frame time.
+ * @param {number} dtSec Seconds since the previous camera update.
+ * @param {{forwardM: number, upM: number, pitchDeg: number,
+ *   minClearanceM: number}} profile Eye offsets for the subject kind.
+ */
+function placeCamera(target, info, nowMs, dtSec, profile) {
   if (!this.cockpitAnchorValid) {
     Cesium.Cartesian3.clone(target, this.cockpitAnchor);
     this.cockpitAnchorValid = true;
@@ -89,7 +110,7 @@ export function update() {
   // 15/30-second interpolation and per-frame cache without exposing its
   // sample-boundary corrections to the camera.
   const headingRad = Cesium.Math.toRadians(this.heading ?? 0);
-  const pitchRad = Cesium.Math.toRadians(COCKPIT_VIEW_PITCH_DEG);
+  const pitchRad = Cesium.Math.toRadians(profile.pitchDeg);
   const speedMps = Number.isFinite(info.velocityMps)
     ? Math.max(0, info.velocityMps)
     : 0;
@@ -248,7 +269,7 @@ export function update() {
     const minimumAnchorHeightM = cockpitGroundSafeHeight(
       anchorCartographic.height,
       cockpitFloorM,
-      COCKPIT_MIN_GROUND_CLEARANCE_M - COCKPIT_UP_OFFSET_M,
+      profile.minClearanceM - profile.upM,
     );
     if (minimumAnchorHeightM !== anchorCartographic.height) {
       anchorCartographic.height = minimumAnchorHeightM;
@@ -297,7 +318,7 @@ export function update() {
 
   Cesium.Cartesian3.multiplyByScalar(
     this.scratchHorizontal,
-    COCKPIT_FORWARD_OFFSET_M,
+    profile.forwardM,
     this.scratchCamera,
   );
   Cesium.Cartesian3.add(
@@ -309,7 +330,7 @@ export function update() {
   Cesium.Cartesian3.normalize(this.scratchTarget, this.scratchTarget);
   Cesium.Cartesian3.multiplyByScalar(
     this.scratchTarget,
-    COCKPIT_UP_OFFSET_M,
+    profile.upM,
     this.scratchTarget,
   );
   Cesium.Cartesian3.add(
@@ -338,7 +359,7 @@ export function update() {
     const safeHeightM = cockpitGroundSafeHeight(
       cameraCartographic.height,
       cockpitFloorM,
-      COCKPIT_MIN_GROUND_CLEARANCE_M,
+      profile.minClearanceM,
     );
     if (safeHeightM !== cameraCartographic.height) {
       cameraCartographic.height = safeHeightM;

From 3577d195133fc28f7c8bbc1ada3155188a85f3fa Mon Sep 17 00:00:00 2001
From: manjunath22466 <301209272+manjunath22466@users.noreply.github.com>
Date: Thu, 5 Nov 2026 00:17:08 +0530
Subject: [PATCH 30/71] Cover the real provider switch and share chat Settings
 and stop checks

- Host test switches AI Provider from chat Settings through the real
  provider commands and checks the new mount keeps chat's context, frame,
  Back to chat and focus on the provider choice.
- Drop the open and minimized branches of the carried presentation: the
  provider choice lives only in Settings, so chat is never open then.
- One showChatSettings helper for the gear and the restore, and one
  isStoppable helper for the live-or-error check in chat and the panel close.
---
 changelog.d/1546-chat-provider-switch.md |  4 +-
 docs/CURRENT-STATE.md                    |  4 +-
 src/voice/chatControl.js                 | 56 ++++++++++--------------
 src/voice/chatControlView.test.mjs       | 23 +++++-----
 src/voice/panel/host.test.mjs            | 50 +++++++++++++++++++++
 src/voice/providerCommands.js            |  2 +-
 src/voice/providerCommands.test.mjs      |  4 +-
 src/voice/session.js                     |  4 ++
 src/voice/sessionCommands.js             | 10 ++---
 9 files changed, 99 insertions(+), 58 deletions(-)

diff --git a/changelog.d/1546-chat-provider-switch.md b/changelog.d/1546-chat-provider-switch.md
index 1c3210330..69cdbc939 100644
--- a/changelog.d/1546-chat-provider-switch.md
+++ b/changelog.d/1546-chat-provider-switch.md
@@ -1,5 +1,5 @@
 - Keep typed chat's view when switching AI Provider: Settings opened from
-  chat, or chat itself, stay as they were for the new provider instead of
-  falling back to voice and widening the dock. Opening chat or closing the
+  chat stay chat's Settings for the new provider instead of falling back to
+  voice and widening the dock. Opening chat or closing the
   voice panel now also clears a voice error left on the dock (Manjunath,
   @manjunath22466, #1546).
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index fa2287567..c01693e3d 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -767,8 +767,8 @@ starts. Settings opened from chat keep chat's frame and show the shared AI
 provider, the quick-commands option and then the voice preferences (Voice
 Preview, inactivity timeout and model tier), so they stay in reach while
 Preview is off, with Back to chat; voice Settings show Back to voice. Switching
-AI Provider keeps that view: chat's Settings, or chat itself, stay as they were
-for the new provider. Escape steps back from either Settings view, closes Voice
+AI Provider keeps that view: Settings opened from chat stay chat's Settings,
+in chat's frame, for the new provider. Escape steps back from either Settings view, closes Voice
 Preview, and does nothing in chat. Closing chat ends a typed session, and the
 voice panel's close turns voice off. Opening chat or closing the voice panel
 also clears a voice error left on the dock. Asking the assistant from chat to open
diff --git a/src/voice/chatControl.js b/src/voice/chatControl.js
index d366181a7..0525b9bc5 100644
--- a/src/voice/chatControl.js
+++ b/src/voice/chatControl.js
@@ -1,6 +1,7 @@
 import { bindChatAttachments } from './chatAttachments.js';
 import { bindChatPreferences } from './chatPreferences.js';
 import { readStoredCloudVoiceAuthMode } from './cloudVoiceAuth.js';
+import { isStoppable } from './session.js';
 import { t } from '../i18n/index.js';
 
 /**
@@ -96,8 +97,7 @@ export function bindChatControl({ ui, session, onOpen, dataManager }) {
     leaveChatSettings();
     // Chat replaces voice, a stale voice error included, so the dock stops
     // showing it.
-    if (!isTyped() && (session.isActive() || session.state === 'error'))
-      session.stop();
+    if (!isTyped() && isStoppable(session)) session.stop();
     onOpen?.();
     ui.update('chat', { open: true, minimized: false, rows: 2, authNote });
     sync();
@@ -392,15 +392,7 @@ export function bindChatControl({ ui, session, onOpen, dataManager }) {
       }
       const frame = ui.element('chatPanel')?.getBoundingClientRect?.();
       close();
-      ui.update('voicePanel', {
-        context: 'chat',
-        ...(frame?.width && {
-          frameWidth: frame.width,
-          frameHeight: frame.height,
-        }),
-      });
-      ui.update('chat', { backVisible: true });
-      sync();
+      showChatSettings(frame);
       void ui.focus(['chatBack']);
     }),
     // The panel clears its context as it closes, so chat tracks its own.
@@ -416,32 +408,30 @@ export function bindChatControl({ ui, session, onOpen, dataManager }) {
     }),
   ];
   sync();
-  // What a provider switch carries to the next mount: chat's Settings or
-  // chat itself, never the conversation.
+  // Settings shown from chat, in chat's frame when it has one.
+  function showChatSettings(frame) {
+    ui.update('voicePanel', {
+      context: 'chat',
+      ...(frame?.width && {
+        frameWidth: frame.width,
+        frameHeight: frame.height,
+      }),
+    });
+    ui.update('chat', { backVisible: true });
+    sync();
+  }
+  // What a provider switch carries to the next mount: chat's Settings, never
+  // the conversation. The provider choice lives only in Settings, so chat
+  // itself is never open during a switch.
   function presentation() {
-    if (inChatSettings()) {
-      const { frameWidth, frameHeight } = ui.state.voicePanel;
-      return { view: 'settings', frameWidth, frameHeight };
-    }
-    if (chat().open) return { view: chat().minimized ? 'minimized' : 'open' };
-    return null;
+    if (!inChatSettings()) return null;
+    const { frameWidth: width, frameHeight: height } = ui.state.voicePanel;
+    return { view: 'settings', frame: width ? { width, height } : null };
   }
   // Restored without moving focus: the switch keeps it on the provider choice.
   function restorePresentation(state) {
-    if (disposed || !state) return;
-    if (state.view === 'settings') {
-      ui.update('voicePanel', {
-        context: 'chat',
-        ...(state.frameWidth && {
-          frameWidth: state.frameWidth,
-          frameHeight: state.frameHeight,
-        }),
-      });
-      ui.update('chat', { backVisible: true });
-      return sync();
-    }
-    open({ focus: false });
-    if (state.view === 'minimized') minimize({ focus: false });
+    if (disposed || state?.view !== 'settings') return;
+    showChatSettings(state.frame);
   }
   return {
     close,
diff --git a/src/voice/chatControlView.test.mjs b/src/voice/chatControlView.test.mjs
index e329a2dc3..c0175456c 100644
--- a/src/voice/chatControlView.test.mjs
+++ b/src/voice/chatControlView.test.mjs
@@ -365,7 +365,7 @@ test('the chat gear is named for the settings it opens', async (t) => {
   );
 });
 
-test('a provider switch carries chat Settings or chat itself to the next mount', async (t) => {
+test('a provider switch carries chat Settings to the next mount', async (t) => {
   const mount = () => {
     const ui = createTestVoiceUi({ panel: true });
     const chat = bindChatControl({ ui, session: typedSession() });
@@ -377,21 +377,22 @@ test('a provider switch carries chat Settings or chat itself to the next mount',
   before.ui.emit('chat-button');
   before.ui.update('voicePanel', { hidden: false });
   before.ui.emit('settings-button');
+  before.ui.update('voicePanel', { frameWidth: 320, frameHeight: 480 });
   const settings = before.chat.presentation();
-  assert.equal(settings.view, 'settings');
+  assert.deepEqual(settings, {
+    view: 'settings',
+    frame: { width: 320, height: 480 },
+  });
   const after = mount();
   after.chat.restorePresentation(settings);
   assert.equal(after.ui.state.voicePanel.context, 'chat');
+  assert.equal(after.ui.state.voicePanel.frameWidth, 320);
+  assert.equal(after.ui.state.voicePanel.frameHeight, 480);
   assert.equal(after.ui.state.chat.backVisible, true);
   assert.equal(after.ui.state.root.assistantMode, 'chat');
-  // Open and minimized chat come back as they were, without taking focus.
-  for (const view of ['open', 'minimized']) {
-    const next = mount();
-    next.chat.restorePresentation({ view });
-    assert.equal(next.ui.state.chat.open, true);
-    assert.equal(next.ui.state.chat.minimized, view === 'minimized');
-    assert.equal(next.chat.presentation().view, view);
-  }
-  // Idle chat carries nothing.
+  // Chat itself, or no chat at all, carries nothing.
+  const open = mount();
+  open.ui.emit('chat-button');
+  assert.equal(open.chat.presentation(), null);
   assert.equal(mount().chat.presentation(), null);
 });
diff --git a/src/voice/panel/host.test.mjs b/src/voice/panel/host.test.mjs
index ae5cd1994..57b512ac0 100644
--- a/src/voice/panel/host.test.mjs
+++ b/src/voice/panel/host.test.mjs
@@ -1319,6 +1319,56 @@ test('opening chat or closing the voice panel clears a stale voice error', async
   }
 });
 
+test('switching AI Provider from chat Settings keeps chat Settings on the new mount', async (t) => {
+  const view = mountVoiceView(t);
+  const host = createVoicePanelHost({ storage: null });
+  const instances = [];
+  const commands = createProviderCommands(
+    {
+      runner: async () => ({}),
+      dataManager: { layers: new Map() },
+      supportedProviders: ['openai', 'gemini'],
+    },
+    {
+      bind: (options) =>
+        bind({
+          ...options,
+          panelHost: host,
+          createControl: (control) =>
+            createTestVoiceUi({ ...control, pinia: view.pinia }),
+        }),
+      factories: { openai: factory(instances), gemini: factory(instances) },
+      storage: null,
+    },
+  );
+  t.after(() => {
+    commands.destroy();
+    host.destroy();
+  });
+  await view.settle();
+  $('#gev-chat-button').click();
+  await view.settle();
+  $('#gev-chat-panel').getBoundingClientRect = () => ({
+    width: 320,
+    height: 480,
+  });
+  $('#gev-voice-settings-button').click();
+  await view.settle();
+  const old = commands.ui;
+  assert.equal(old.state.voicePanel.context, 'chat');
+  old.emit('provider-change', 'gemini');
+  await view.settle();
+  const { ui } = commands;
+  assert.notEqual(ui, old);
+  assert.equal(ui.state.voicePanel.context, 'chat');
+  assert.equal(ui.state.voicePanel.frameWidth, 320);
+  assert.equal(ui.state.voicePanel.frameHeight, 480);
+  assert.equal(ui.state.chat.backVisible, true);
+  assert.equal(ui.state.root.assistantMode, 'chat');
+  assert.equal($('#gev-chat-back').hidden, false);
+  assert.equal(active(), 'gev-voice-provider');
+});
+
 test('the voice panel close turns voice off', async (t) => {
   const f = mounted(t, { view: true });
   await f.commands.session.start();
diff --git a/src/voice/providerCommands.js b/src/voice/providerCommands.js
index 756215c7b..5d77ebef6 100644
--- a/src/voice/providerCommands.js
+++ b/src/voice/providerCommands.js
@@ -64,7 +64,7 @@ export function createProviderCommands(options, { bind, factories, storage }) {
     const textOnly = Boolean(
       current.session.adapter.getStartOptions?.().textOnly,
     );
-    // The panel stays where the user is: chat's Settings or chat itself.
+    // Settings opened from chat stay chat's Settings.
     const presentation = current.chatPresentation?.() ?? null;
     const generation = ++mountGeneration;
     voiceEnabled = false;
diff --git a/src/voice/providerCommands.test.mjs b/src/voice/providerCommands.test.mjs
index dfcf77052..a9acd2804 100644
--- a/src/voice/providerCommands.test.mjs
+++ b/src/voice/providerCommands.test.mjs
@@ -857,13 +857,13 @@ for (const action of ['stop', 'destroy']) {
   }
 }
 
-test('a provider switch hands chat Settings or chat to the new mount', async (t) => {
+test('a provider switch hands chat Settings to the new mount', async (t) => {
   const f = compositionFixture(t);
   const first = f.facade.provider;
   const next = first === 'openai' ? 'gemini' : 'openai';
   // Without chat open there is nothing to carry.
   assert.equal(f.mounts[0].controls.chatPresentation(), null);
-  const shown = { view: 'settings', frameWidth: 320, frameHeight: 480 };
+  const shown = { view: 'settings', frame: { width: 320, height: 480 } };
   f.mounts[0].controls.chatPresentation = () => shown;
   f.select(next);
   await settle();
diff --git a/src/voice/session.js b/src/voice/session.js
index 21400f04c..7c31f17d2 100644
--- a/src/voice/session.js
+++ b/src/voice/session.js
@@ -185,6 +185,10 @@ export function createVoiceSession({ createAdapter, runner, signal }) {
   };
 }
 
+// Live, or left in error: stopping either returns the session to idle.
+export const isStoppable = (session) =>
+  session.isActive() || session.state === 'error';
+
 function abortError() {
   return new DOMException('Voice action cancelled', 'AbortError');
 }
diff --git a/src/voice/sessionCommands.js b/src/voice/sessionCommands.js
index 5a8a7e90c..242a2126b 100644
--- a/src/voice/sessionCommands.js
+++ b/src/voice/sessionCommands.js
@@ -3,7 +3,7 @@ import { bindAssistantPanelLayout, bindLayoutDock } from './panelLayout.js';
 import { bindChatControl } from './chatControl.js';
 import { bindVoiceMiniPreview } from './voiceMiniPreview.js';
 import { createVoiceControl, voiceStatusLabel } from './control.js';
-import { createVoiceSession } from './session.js';
+import { createVoiceSession, isStoppable } from './session.js';
 import { VoiceCardControls } from './voiceCard.js';
 import { PointerReticle } from './pointerReticle.js';
 import { VOICE_PROVIDERS } from './providerCapabilities.js';
@@ -40,7 +40,7 @@ export function createVoiceCommands({
   createReticle = createDefaultReticle,
   panelHost = null,
   nativePanelProvider = null,
-  // Chat's Settings or chat itself, carried across a provider switch.
+  // Chat's Settings, carried across a provider switch.
   presentation = null,
 }) {
   if (resetExisting) window.__gevVoiceCommands?.stop?.({ removeUi: true });
@@ -289,11 +289,7 @@ export function createVoiceCommands({
   // session belongs to chat, which handles its own close.
   const offClose = ui.on('settings-close', () => {
     // A voice error the user closes is over too; stopping returns to idle.
-    if (
-      (!session.isActive() && session.state !== 'error') ||
-      adapter.getStartOptions?.().textOnly
-    )
-      return;
+    if (!isStoppable(session) || adapter.getStartOptions?.().textOnly) return;
     const ticket = panelMount?.stopTicket();
     session.stop();
     panelMount?.closeAfterStop(ticket);

From 219f3e1079cb8efb0a60068677d9cb942348d5a2 Mon Sep 17 00:00:00 2001
From: Denis Groshev <denis@halfpixel.ai>
Date: Wed, 4 Nov 2026 17:04:05 +0100
Subject: [PATCH 31/71] feat(cockpit): enter Cockpit with only the ridden
 aircraft's layer on
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cockpit entry no longer needs Contacts or both flight feeds: a civilian
aircraft needs Live Flights, a military one Military Flights. Contacts and
every other layer can be turned on or off before or during a session, and
turning off the ridden layer ends it. A Context mode change in flight still
blocks entry.

When the other air feed is off, Live Signals and the Contact card say
FLIGHTS FEED OFF or MILITARY FEED OFF · PARTIAL PICTURE instead of
presenting a partial picture as complete. Voice refuses entry with
subject-layer-off rather than contacts-inactive, and its tool description
says Contacts is not required.

Double-clicking the followed aircraft enters Cockpit through the same gate.
The Cockpit takes the scene's double-click before Cesium's stock handler,
which would otherwise untrack a followed aircraft whose model is a
primitive. The entry also shows under the Intel HUD readout, sharing the
Contacts button's face. A test keeps the classes the Cockpit adds to the
body from matching another element's rule.
---
 docs/CURRENT-STATE.md                       |  18 +-
 scripts/package-boundaries.json             |   5 +
 scripts/qa-voice-routing.mjs                |  29 ++-
 server/providers/openai/toolDescriptions.js |   2 +-
 src/cockpitMarkup.test.mjs                  |  25 ++-
 src/cockpitSignalFocus.test.mjs             |  34 +++
 src/contextModePolicy.js                    |  39 ++--
 src/contextModePolicy.test.mjs              |  41 ++--
 src/firstRunExperience.test.mjs             |   5 +-
 src/i18n/locales/ar.json                    |   3 +
 src/i18n/locales/de.json                    |   3 +
 src/i18n/locales/es.json                    |   3 +
 src/i18n/locales/fr.json                    |   3 +
 src/i18n/locales/it.json                    |   3 +
 src/i18n/locales/ja.json                    |   5 +-
 src/i18n/locales/pt.json                    |   5 +-
 src/i18n/locales/ru.json                    |   5 +-
 src/i18n/locales/uk.json                    |   5 +-
 src/i18n/locales/zh-CN.json                 |   5 +-
 src/i18n/locales/zh-Hant.json               |   5 +-
 src/materialSymbolsSubset.test.mjs          |  22 +-
 src/ui/cockpitBodyClasses.test.mjs          |  91 ++++++++
 src/ui/cockpitContext.js                    |  51 ++++-
 src/ui/cockpitContext.test.mjs              |  57 +++++
 src/ui/cockpitController.js                 |  37 +++-
 src/ui/cockpitCoordinator.js                |  78 +++++--
 src/ui/cockpitEntryGate.test.mjs            | 234 ++++++++++++++++++++
 src/ui/cockpitInput.js                      |  94 ++++++++
 src/ui/cockpitPresentation.js               |  18 ++
 src/ui/cockpitSignals.js                    |  65 +++++-
 src/ui/cockpitTrackingController.js         |  31 ++-
 src/ui/contextLayerChanges.js               |  16 +-
 src/ui/contextTransactions.js               |   9 +-
 src/ui/styles/cockpit.css                   |  30 +++
 src/ui/views/ContextView.vue                |   7 +-
 src/ui/views/IntelHudView.vue               |  12 +
 src/voice/actionSchemas.test.mjs            |   3 +-
 37 files changed, 964 insertions(+), 134 deletions(-)
 create mode 100644 src/ui/cockpitBodyClasses.test.mjs
 create mode 100644 src/ui/cockpitEntryGate.test.mjs

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index c3e15ea4d..ad0dc30e4 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -4799,7 +4799,7 @@ cannot claim full acceptance.
 
 **Lifecycle and proxy.** Contacts temporarily disables Transit and restores its
 prior state on exit; Space Missions refuses enablement while isolating replay
-data. Cockpit enters through Contacts and does not independently enable Transit.
+data. Cockpit does not need Contacts and does not independently enable Transit.
 The proxy fetches registered URLs only, validates redirect origins, bounds
 responses and decoding, caches successful snapshots, and backs off after failed
 refreshes. A 304 confirms contact without appending history. Missing vehicles
@@ -6017,12 +6017,16 @@ apply to `public/` assets or built-preview serving.
 - Panoptic mode shows labels on ALL items (no stride skipping). Tracked/selected items keep bounding box but suppress label (skipLabel flag). Tracked items get enlarged bounding boxes (56×44 vs default 22×14).
 - The 3D aircraft toggle reveals `Proximity` and `All` modes and drives both commercial and military aircraft layers. It ships ON in `Proximity`, so the button paints lit and the mode row paints open from markup; the panel is therefore ~36 px taller than before, which Cockpit's Display/Radio strip absorbs through its existing primary-only corridor solver.
 - The host-painted tracked-target readout sits above the post-FX layer and follows tracked aircraft/satellites or selected mapped installations using each layer's display-position contract.
-- Cockpit entry is gated to the operational Contacts context bundle. The
-  Context chooser must be in Contacts mode, Live Flights and Military Flights must both
-  be enabled, and a civilian or military aircraft must be tracked. The visible
-  Cockpit actions and the `C` shortcut use the same gate, so ordinary standalone
-  flight-layer selection cannot enter a context-dependent cockpit.
-- **Aircraft cockpit view:** selecting a commercial or military aircraft reveals a `COCKPIT` action (`C`). Cockpit mode temporarily releases Cesium's orbit-follow transform and drives a first-person camera from the tracked aircraft's existing smoothed display position and course. Its concave helmet-visor HUD shows callsign, UTC time, coordinates, curved roll/pitch guides, and a seven-division heading tape. Ambient commercial and military AIR contacts use a Cockpit near/far band selected by the shared Display 3D mode: Proximity admits at 150 km and retains to 185 km; All admits at 400 km and retains to 450 km. The shared 3D toggle now applies in Cockpit: Off keeps in-range contacts as rotating 2D aircraft silhouettes, while On lets a ready admitted glTF take over without a drawing gap. The Cockpit model cap remains 60 and can only lower the map budget; in-range contacts that are capped or still loading remain 2D silhouettes instead of degrading to out-of-range dots. Contacts outside the selected band use small rotation-free cyan-white pips for civilian aircraft and amber pips for military. The pilot's own airframe is not drawn in first person, and exiting clears the Cockpit band and restores normal map silhouettes/models. The normal left accordion remains available for Layers and Authoring and keeps the same 26vh HUD-aligned anchor used in map mode, independent of whether the bottom-left Contact card is expanded or collapsed; the right-rail CCTV and Context chooser are hidden to avoid duplicating or overlapping the cockpit presentation. When the intelligence HUD is enabled, its classification, scene summary, collection/orbit metadata, coordinates, and imaging-status text remain visible as reduced peripheral cockpit telemetry; the optical center and flight instruments stay clear, and turning the HUD off still hides it. Ground speed, exact heading, and rendered altitude form one compact lower-center instrument cluster, keeping the horizon and peripheral view open. A second live altitude tape hugs the inside-right visor rim: its rail and nine moving ticks are derived from the same responsive keyhole radius, remain 20 px inside the circular edge even on wide displays, fade deeply at both vertical ends, and move continuously behind a fixed current-altitude pointer; its interval tightens automatically near the surface and it is suppressed on narrow screens. Cockpit mode also has a weather-backed transparent volumetric-cloud pass derived from the supplied FBM/domain-warped R&D shader. It renders at no more than 520×320, uses 24 ray steps/three FBM octaves at 12 FPS, is clipped to the visor, fails clear when Open-Meteo is unavailable, and stops its animation completely on cockpit exit. It does not restore the prior CPU weather canvases, precipitation, scene fog, or any map-mode effect. When Contacts is active for the tracked aircraft, the compact `CONTACT` rail adds the 250 km subject window, four cohort counts, nearest observed/mapped example with relative bearing and distance, freshness, explicit uncertainty, and Previous and Next controls plus its own collapse control. The mirrored right rail is a three-page **cockpit briefing carousel**: source-backed live signals, location-matched regional headlines, and physical-region/current-weather context from bundled Natural Earth polygons and Open-Meteo. It is manual-first: Previous, Next, and direct page controls are always available, and the visible `CYCLE OFF` / `CYCLE ON` control starts or stops the nine-second page cycle. The cycle pauses on hover or keyboard focus and stops while collapsed, hidden, or outside cockpit mode; live signal data continues refreshing either way. Empty news matches and unavailable news use compact text states rather than reserving an empty media frame; partial local data remains explicit. Article links open their original publisher, and no headline is treated as verified risk intelligence. On desktop both cockpit rails use the same width and share a bottom-aligned safe baseline in opposite corners above the peripheral MGRS/GSD/time telemetry, leaving both that text and the lower-center instrument cluster readable. They collapse independently to slim tabs without stopping live data updates. Narrow screens use separated top/bottom fallbacks. Empty-space globe clicks are inert while cockpit owns the camera; `C`, `Escape`, or `EXIT COCKPIT` explicitly exits and restores the same tracked entity and standard follow camera. Unknown feeds remain unknown, selection loss still exits safely without inventing a replacement track, and the cockpit never presents the summary as threat scoring or an all-clear. This is a desktop first-person presentation, not a WebXR session.
+- Cockpit entry needs only the layer of the aircraft it rides and that aircraft
+  tracked: Live Flights for a civilian, Military Flights for a military aircraft
+  (the tracked info's `layerId`; `cockpitEntryAllowed` in
+  `src/contextModePolicy.js`). Contacts is not required, and the other aircraft
+  layer, Live AIS Vessels and every other layer may be turned on or off before or
+  during a session. A Context mode change still in flight blocks entry until it
+  settles. Turning off the layer the view rides ends it. The visible Cockpit
+  actions, the `C` shortcut and voice use the same gate; voice entry still opens
+  Contacts first, as its layer-targeted entry navigates through Contacts.
+- **Aircraft cockpit view:** selecting a commercial or military aircraft reveals a `COCKPIT` action (`C`) once that aircraft's own layer is on; Contacts is not required. The action shows in Contacts (`#cockpit-entry`) and under the Intel HUD's bottom-right readout (`#cockpit-entry-readout`, with the HUD on, in its Tactical and Cyber layouts), so entry needs no Contacts panel. Turning off the ridden aircraft's layer ends the view (the layer clears its tracking). When an air feed the surrounding picture uses is off, the Cockpit says so instead of blocking: Live Signals leads with `MILITARY FEED OFF · PARTIAL PICTURE` or `FLIGHTS FEED OFF · PARTIAL PICTURE`, and the Contact card shows that line in place of its inputs status, so a partial picture is never presented as complete. `control_cockpit` refuses entry with `entryBlockedReason` `contacts-starting` (a Context change in flight), `subject-layer-off` (the aircraft's layer, or with none tracked any aircraft layer, is off) or `no-tracked-aircraft`. Cockpit mode temporarily releases Cesium's orbit-follow transform and drives a first-person camera from the tracked aircraft's existing smoothed display position and course. Its concave helmet-visor HUD shows callsign, UTC time, coordinates, curved roll/pitch guides, and a seven-division heading tape. Ambient commercial and military AIR contacts use a Cockpit near/far band selected by the shared Display 3D mode: Proximity admits at 150 km and retains to 185 km; All admits at 400 km and retains to 450 km. The shared 3D toggle now applies in Cockpit: Off keeps in-range contacts as rotating 2D aircraft silhouettes, while On lets a ready admitted glTF take over without a drawing gap. The Cockpit model cap remains 60 and can only lower the map budget; in-range contacts that are capped or still loading remain 2D silhouettes instead of degrading to out-of-range dots. Contacts outside the selected band use small rotation-free cyan-white pips for civilian aircraft and amber pips for military. The pilot's own airframe is not drawn in first person, and exiting clears the Cockpit band and restores normal map silhouettes/models. The normal left accordion remains available for Layers and Authoring and keeps the same 26vh HUD-aligned anchor used in map mode, independent of whether the bottom-left Contact card is expanded or collapsed; the right-rail CCTV and Context chooser are hidden to avoid duplicating or overlapping the cockpit presentation. When the intelligence HUD is enabled, its classification, scene summary, collection/orbit metadata, coordinates, and imaging-status text remain visible as reduced peripheral cockpit telemetry; the optical center and flight instruments stay clear, and turning the HUD off still hides it. Ground speed, exact heading, and rendered altitude form one compact lower-center instrument cluster, keeping the horizon and peripheral view open. A second live altitude tape hugs the inside-right visor rim: its rail and nine moving ticks are derived from the same responsive keyhole radius, remain 20 px inside the circular edge even on wide displays, fade deeply at both vertical ends, and move continuously behind a fixed current-altitude pointer; its interval tightens automatically near the surface and it is suppressed on narrow screens. Cockpit mode also has a weather-backed transparent volumetric-cloud pass derived from the supplied FBM/domain-warped R&D shader. It renders at no more than 520×320, uses 24 ray steps/three FBM octaves at 12 FPS, is clipped to the visor, fails clear when Open-Meteo is unavailable, and stops its animation completely on cockpit exit. It does not restore the prior CPU weather canvases, precipitation, scene fog, or any map-mode effect. When Contacts is active for the tracked aircraft, the compact `CONTACT` rail adds the 250 km subject window, four cohort counts, nearest observed/mapped example with relative bearing and distance, freshness, explicit uncertainty, and Previous and Next controls plus its own collapse control. The mirrored right rail is a three-page **cockpit briefing carousel**: source-backed live signals, location-matched regional headlines, and physical-region/current-weather context from bundled Natural Earth polygons and Open-Meteo. It is manual-first: Previous, Next, and direct page controls are always available, and the visible `CYCLE OFF` / `CYCLE ON` control starts or stops the nine-second page cycle. The cycle pauses on hover or keyboard focus and stops while collapsed, hidden, or outside cockpit mode; live signal data continues refreshing either way. Empty news matches and unavailable news use compact text states rather than reserving an empty media frame; partial local data remains explicit. Article links open their original publisher, and no headline is treated as verified risk intelligence. On desktop both cockpit rails use the same width and share a bottom-aligned safe baseline in opposite corners above the peripheral MGRS/GSD/time telemetry, leaving both that text and the lower-center instrument cluster readable. They collapse independently to slim tabs without stopping live data updates. Narrow screens use separated top/bottom fallbacks. Empty-space globe clicks are inert while cockpit owns the camera; `C`, `Escape`, or `EXIT COCKPIT` explicitly exits and restores the same tracked entity and standard follow camera. Unknown feeds remain unknown, selection loss still exits safely without inventing a replacement track, and the cockpit never presents the summary as threat scoring or an all-clear. This is a desktop first-person presentation, not a WebXR session.
 - **Cockpit left-panel clearance:** the Cockpit Contact card and peripheral HUD participate in the adaptive left accordion's live obstacle measurements, including live viewport-height changes. Expanding Layers or Authoring keeps the active panel in the available upper-left corridor with internal scrolling; it does not cover the Contact card, lower Cockpit controls, or Cesium credit line. Outside Cockpit the hidden card does not alter the normal corridor.
 - **Cockpit Context scope:** the 250 km radius applies to the air/sea proximity cohorts. Installation counts come only from the currently loaded viewport and are labeled `CURRENT VIEWPORT ONLY` in the cockpit as well as the normal Context panel; neither surface presents them as a complete 250 km installation survey.
 - **Cockpit camera anchor:** first-person mode does not write feed-boundary corrections directly into the camera. A cockpit-only inertial anchor advances from the selected aircraft's displayed course and speed, then converges toward the authoritative delayed track with correction capped below forward motion. The displayed kinematics are derived from the same consecutive fix segment as the rendered position, with raw feed speed/course used only as fallback; a transient zero/missing feed speed therefore cannot freeze a visibly moving aircraft after layer enable or a map/cockpit handoff. Rendered altitude continues to come from that interpolated track position. Late ADS-B fixes and short render stalls can remove drift without accelerating or reversing the view. Camera placement runs before scene update/culling at a bounded 20 Hz so a moving cockpit does not force Photoreal 3D Tiles to retraverse on every display frame; textual instruments update at 10 Hz and context/layout work at 4 Hz. Every far Cockpit contact pip shares one stable Cesium texture-atlas entry and skips unused screen-projected course calculations, while only in-range 2D aircraft silhouettes pay the screen-projected rotation cost; ambient glTF collections are hidden/retained rather than synchronously destroyed at cockpit entry, and context rails lay out only on explicit content/state changes and viewport resize. The deliberate 15/30-second layer interpolation delays and per-Cesium-frame position caches remain unchanged.
diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json
index a774993b2..842ec9920 100644
--- a/scripts/package-boundaries.json
+++ b/scripts/package-boundaries.json
@@ -39,6 +39,9 @@
       "src/ui/views/panels/CockpitBriefing.vue",
       "src/ui/views/panels/CockpitContext.vue",
       "src/ui/views/panels/CockpitRoute.vue",
+      "src/ui/cockpitPresentation.js",
+      "src/data/headingDegrees.js",
+      "src/data/distanceFormat.js",
       "src/ui/views/panels/CockpitRollingValue.vue",
       "src/ui/views/panels/CockpitSignalList.vue",
       "src/ui/views/panels/CockpitUtilityControls.vue",
@@ -866,6 +869,7 @@
       "src/ui/cockpitDisplayPortal.js",
       "src/ui/displayPanelScroll.js",
       "src/ui/cockpitInput.js",
+      "src/data/inputOwnership.js",
       "src/ui/cockpitInstruments.js",
       "src/ui/cockpitLayout.js",
       "src/ui/cockpitPresentation.js",
@@ -992,6 +996,7 @@
       "src/ui/cockpitDisplayPortal.js",
       "src/ui/displayPanelScroll.js",
       "src/ui/cockpitInput.js",
+      "src/data/inputOwnership.js",
       "src/ui/cockpitInstruments.js",
       "src/ui/cockpitLayout.js",
       "src/ui/cockpitPresentation.js",
diff --git a/scripts/qa-voice-routing.mjs b/scripts/qa-voice-routing.mjs
index 094119030..0b0a5213a 100644
--- a/scripts/qa-voice-routing.mjs
+++ b/scripts/qa-voice-routing.mjs
@@ -2321,9 +2321,11 @@ async function runBehaviorLayer() {
       `result=${JSON.stringify(r)?.slice(0, 120)} state=${JSON.stringify(contextExited)?.slice(0, 80)}`,
     );
 
-    // (9f) With Contacts OFF the entry gate is shut. Entry must refuse with the
-    // reason rather than produce the half-entered state the operator saw: a
-    // plane anchored under the camera with no HUD and no exit control.
+    // (9f) Cockpit needs only the tracked aircraft's own layer, not Contacts.
+    // With Contacts OFF, status must explain a shut gate without blaming
+    // Contacts, and entry must either enter cleanly or refuse with the reason
+    // rather than produce the half-entered state the operator saw: a plane
+    // anchored under the camera with no HUD and no exit control.
     r = await run('control_cockpit', { action: 'status' });
     const gateReport = r?.state || {};
     const cockpitBeforeGate = await page.evaluate(() =>
@@ -2331,10 +2333,13 @@ async function runBehaviorLayer() {
     );
     report(
       gateReport.active === false &&
-        gateReport.entryAllowed === false &&
-        gateReport.entryBlockedReason === 'contacts-inactive' &&
+        (gateReport.entryAllowed === true
+          ? gateReport.entryBlockedReason === null
+          : ['subject-layer-off', 'no-tracked-aircraft'].includes(
+              gateReport.entryBlockedReason,
+            )) &&
         !cockpitBeforeGate,
-      'behavior: cockpit status names why entry is blocked with Contacts off',
+      'behavior: cockpit status explains its gate without requiring Contacts',
       `state=${JSON.stringify(gateReport)?.slice(0, 150)}`,
     );
 
@@ -2348,12 +2353,16 @@ async function runBehaviorLayer() {
       Boolean(window.__godsEyeView?.styleManager?.cockpitView?.active),
     );
     report(
-      gated?.ok === false &&
-        /contacts/i.test(gated?.error || '') &&
-        !cockpitAfterGate,
-      'behavior: cockpit entry with Contacts off is refused, not half-entered',
+      gated?.ok === true
+        ? cockpitAfterGate
+        : !cockpitAfterGate && !/contacts/i.test(gated?.error || ''),
+      'behavior: cockpit entry with Contacts off follows the own-layer gate, never half-entered',
       `ok=${gated?.ok} error=${String(gated?.error || '').slice(0, 90)} active=${cockpitAfterGate}`,
     );
+    if (cockpitAfterGate)
+      await page.evaluate(() =>
+        window.__godsEyeView?.styleManager?.controlCockpit?.('exit'),
+      );
 
     await runBundledOutlineScenarios({
       page,
diff --git a/server/providers/openai/toolDescriptions.js b/server/providers/openai/toolDescriptions.js
index 7b25d34db..891145021 100644
--- a/server/providers/openai/toolDescriptions.js
+++ b/server/providers/openai/toolDescriptions.js
@@ -135,7 +135,7 @@ export const ACTION_DESCRIPTIONS = {
   },
   control_cockpit: {
     description:
-      'Explicit Cockpit requests only: enter from a selected/tracked aircraft (establishes Contacts itself; no set_context_mode), exit, status, or next/previous. Explicit exit-and-show voice: voicePanel preview/settings (Voice Settings), no confirmation.',
+      'Explicit Cockpit requests only: enter from a selected/tracked aircraft (needs only its own Flights/Military layer on, not Contacts; opens Contacts itself, no set_context_mode), exit, status, or next/previous. Explicit exit-and-show voice: voicePanel preview/settings (Voice Settings), no confirmation.',
     $position: 1,
     parameters: {
       properties: {
diff --git a/src/cockpitMarkup.test.mjs b/src/cockpitMarkup.test.mjs
index 64d03914b..aa06193ba 100644
--- a/src/cockpitMarkup.test.mjs
+++ b/src/cockpitMarkup.test.mjs
@@ -1306,12 +1306,12 @@ test('voice Cockpit entry honours a requested contact layer before it enters', (
     ui.indexOf("if (normalized === 'exit') {"),
   );
   assert.ok(branch, 'cockpit enter branch is missing');
-  const gateIndex = branch.indexOf('isEntryAllowed?.()');
+  const gateIndex = branch.indexOf('this._cockpitEntryRefusal()');
   const retargetIndex = branch.indexOf('_retargetCockpitEntryLayer(');
   const enterIndex = branch.indexOf('enterCockpitWithTracking({');
   assert.ok(
     gateIndex >= 0,
-    'entry consults the same gate the manual chip uses',
+    'entry refuses on the gate it can check before tracking',
   );
   assert.ok(
     retargetIndex > gateIndex,
@@ -1362,9 +1362,21 @@ test('voice Cockpit entry refuses when the entry gate is shut', () => {
     ui.indexOf("if (normalized === 'enter') {"),
     ui.indexOf("if (normalized === 'exit') {"),
   );
-  assert.match(branch, /if \(!this\.cockpitView\.isEntryAllowed\?\.\(\)\) \{/);
-  assert.match(branch, /Contacts must be active to enter Cockpit/);
-  assert.match(branch, /Contacts is still starting up/);
+  // Contacts is not required: only a Context change in flight or no aircraft
+  // layer to ride shuts the gate before tracking, and the entry itself then
+  // applies the manual chip's gate to the aircraft it rides.
+  assert.match(
+    branch,
+    /const refusal = this\._cockpitEntryRefusal\(\);\s*if \(refusal\) \{/,
+  );
+  assert.doesNotMatch(branch, /Contacts must be active/);
+  const refusal = ui.slice(
+    ui.indexOf('  _cockpitEntryRefusal() {'),
+    ui.indexOf('  getCockpitState() {'),
+  );
+  assert.match(refusal, /Context is still changing/);
+  assert.match(refusal, /No aircraft layer is on/);
+  assert.doesNotMatch(refusal, /[Cc]ontacts/);
 });
 
 test('cockpit state cannot report entryAllowed while already active', () => {
@@ -1382,7 +1394,8 @@ test('cockpit state cannot report entryAllowed while already active', () => {
   );
   assert.match(state, /entryBlockedReason:/, 'and a refusal can be explained');
   assert.match(state, /'contacts-starting'/);
-  assert.match(state, /'contacts-inactive'/);
+  assert.match(state, /'subject-layer-off'/);
+  assert.doesNotMatch(state, /'contacts-inactive'/, 'Contacts is not required');
   assert.match(state, /'no-tracked-aircraft'/);
 });
 
diff --git a/src/cockpitSignalFocus.test.mjs b/src/cockpitSignalFocus.test.mjs
index a4f73c4ce..89ee1cac1 100644
--- a/src/cockpitSignalFocus.test.mjs
+++ b/src/cockpitSignalFocus.test.mjs
@@ -147,6 +147,40 @@ const snapshot = (distanceM = 2000) => ({
   ],
 });
 
+test('a feed-off row leads the rebuilt rows and the list stays five long', async (t) => {
+  const f = fixture(t);
+  const crowded = {
+    ...snapshot(),
+    cohorts: [
+      {
+        id: 'flights',
+        count: 6,
+        nearest: [1, 2, 3, 4, 5, 6].map((n) => ({
+          id: `n${n}`,
+          label: `N${n}`,
+          distanceM: n * 1000,
+        })),
+      },
+    ],
+  };
+  updateCockpitSignals.call(f.owner, crowded, 0, {
+    title: 'MILITARY FEED OFF · PARTIAL PICTURE',
+    detail: 'NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR',
+  });
+  await nextTick();
+  assert.equal(f.owner.signalItems.length, 5);
+  assert.equal(f.owner.signalItems[0].key, 'feed-status');
+  assert.equal(f.owner.signalItems[0].tone, 'warning');
+  assert.equal(f.owner.signalItems[0].target, null);
+  assert.match(f.list.textContent, /MILITARY FEED OFF · PARTIAL PICTURE/);
+  updateCockpitSignals.call(f.owner, crowded, 0);
+  assert.equal(
+    f.owner.signalItems.some((item) => item.key === 'feed-status'),
+    false,
+    'with the feed back, the row goes',
+  );
+});
+
 test('rows render the signals the controller presents', async (t) => {
   const f = fixture(t);
   await render(f, [
diff --git a/src/contextModePolicy.js b/src/contextModePolicy.js
index 4c0b7c9cb..fd3324760 100644
--- a/src/contextModePolicy.js
+++ b/src/contextModePolicy.js
@@ -411,30 +411,37 @@ export function contextRestoreLayerIds(snapshot = {}) {
   return restored;
 }
 
+/** The layers an aircraft Cockpit subject can come from. */
+export const COCKPIT_AIRCRAFT_LAYER_IDS = Object.freeze([
+  'flights',
+  'military',
+]);
+
 /**
- * Cockpit entry belongs to the operational Contacts context bundle. A tracked
- * aircraft alone is not sufficient: both observed-flight feeds must still be
- * active so the cockpit's surrounding-contact picture is not presented as a
- * complete context view when one source is disabled.
+ * Cockpit entry needs only the aircraft it rides: that aircraft's own layer
+ * (Live Flights for a civilian, Military Flights for a military aircraft) must
+ * be on. Contacts and the other feeds are not required. When a source the
+ * surrounding picture uses is off, the Cockpit's Contact card and Live
+ * Signals say the picture is partial instead of blocking entry, so a partial
+ * picture is never presented as complete. A Context mode change in flight
+ * still owns the camera, so entry waits it out.
  *
- * @param {object} input Current context and dependency visibility.
- * @param {string|null} input.contextMode Active Context mode.
- * @param {boolean} input.contextModeChanging Whether the Context transaction is unsettled.
- * @param {boolean} input.flightsEnabled Whether Live Flights is enabled.
- * @param {boolean} input.militaryEnabled Whether Military Flights is enabled.
+ * @param {object} input Current subject and Context state.
+ * @param {string|null} input.subjectLayerId Layer of the tracked aircraft
+ *   ('flights' or 'military'), or null with none tracked.
+ * @param {boolean} input.subjectLayerEnabled Whether that layer is enabled.
+ * @param {boolean} input.contextModeChanging Whether a Context transaction is unsettled.
  * @returns {boolean} Whether cockpit entry may be offered or activated.
  */
 export function cockpitEntryAllowed({
-  contextMode,
+  subjectLayerId,
+  subjectLayerEnabled,
   contextModeChanging,
-  flightsEnabled,
-  militaryEnabled,
 }) {
   return (
-    contextMode === 'flights' &&
-    !contextModeChanging &&
-    Boolean(flightsEnabled) &&
-    Boolean(militaryEnabled)
+    COCKPIT_AIRCRAFT_LAYER_IDS.includes(subjectLayerId) &&
+    Boolean(subjectLayerEnabled) &&
+    !contextModeChanging
   );
 }
 
diff --git a/src/contextModePolicy.test.mjs b/src/contextModePolicy.test.mjs
index 40a7b291e..0453bd9b8 100644
--- a/src/contextModePolicy.test.mjs
+++ b/src/contextModePolicy.test.mjs
@@ -400,37 +400,32 @@ test('explicit layer intent finishing during restore overrides the stale queued
   }
 });
 
-test('cockpit entry requires Contacts context with both aircraft feeds enabled', () => {
+test("cockpit entry needs only the tracked aircraft's own layer", () => {
   assert.equal(cockpitEntryAllowed({
-    contextMode: 'flights',
+    subjectLayerId: 'flights',
+    subjectLayerEnabled: true,
     contextModeChanging: false,
-    flightsEnabled: true,
-    militaryEnabled: true,
-  }), true);
+  }), true, 'a civilian needs Live Flights alone: no Contacts, no Military');
   assert.equal(cockpitEntryAllowed({
-    contextMode: 'flights',
+    subjectLayerId: 'military',
+    subjectLayerEnabled: true,
+    contextModeChanging: false,
+  }), true, 'a military aircraft needs Military Flights alone');
+  assert.equal(cockpitEntryAllowed({
+    subjectLayerId: 'flights',
+    subjectLayerEnabled: true,
     contextModeChanging: true,
-    flightsEnabled: true,
-    militaryEnabled: true,
-  }), false, 'Cockpit remains unavailable until Contacts activation settles');
+  }), false, 'Cockpit remains unavailable until a Context mode change settles');
   assert.equal(cockpitEntryAllowed({
-    contextMode: null,
+    subjectLayerId: 'military',
+    subjectLayerEnabled: false,
     contextModeChanging: false,
-    flightsEnabled: true,
-    militaryEnabled: true,
-  }), false, 'ordinary layer selection is not an operational Contacts context');
+  }), false, "the ridden aircraft's own layer is required");
   assert.equal(cockpitEntryAllowed({
-    contextMode: 'flights',
+    subjectLayerId: null,
+    subjectLayerEnabled: false,
     contextModeChanging: false,
-    flightsEnabled: true,
-    militaryEnabled: false,
-  }), false, 'the military contact feed is required');
-  assert.equal(cockpitEntryAllowed({
-    contextMode: 'flights',
-    contextModeChanging: false,
-    flightsEnabled: false,
-    militaryEnabled: true,
-  }), false, 'the civilian contact feed is required');
+  }), false, 'there is no aircraft to ride');
 });
 
 test('context teardown guard restores coordination state after success and failure', async () => {
diff --git a/src/firstRunExperience.test.mjs b/src/firstRunExperience.test.mjs
index 8d6317cb2..ddcdbbd53 100644
--- a/src/firstRunExperience.test.mjs
+++ b/src/firstRunExperience.test.mjs
@@ -1039,10 +1039,11 @@ test('the voice TOOL SCHEMA matches the pinned contract — the mission mapping
   // The Utilities panel adds one set_panel_open target; Sea Marks and Ski
   // Pistes extend the generated layer enums and alias hint; voice geometry
   // adds the analyst area scopes and the osm-places layer.
-  assert.equal(block.length, 31318, 'serialized tool schema length drifted');
+  // control_cockpit states the own-layer entry rule (Contacts not required).
+  assert.equal(block.length, 31372, 'serialized tool schema length drifted');
   assert.equal(
     crypto.createHash('sha256').update(block).digest('hex'),
-    'f5b42f41c2f575838f979e88a1dbff615a77ccd85fdf8fcd0a0a47d02f7d3ddc',
+    '7f593e78c232db972b04441f830b6a60f93916a6e5bc5a68eca7422cd1035508',
     'the first-run missions must ride EXISTING tools: no schema edit, no cache bust',
   );
   const instructions = fs.readFileSync(
diff --git a/src/i18n/locales/ar.json b/src/i18n/locales/ar.json
index deb68ec36..93ec661f8 100644
--- a/src/i18n/locales/ar.json
+++ b/src/i18n/locales/ar.json
@@ -2187,6 +2187,9 @@
   "{value} KM/H": "{value} كم/س",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · نطاق جو/بحر {radius}",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · المنشآت {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "مصدر البيانات العسكرية متوقف · صورة جزئية",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "مصدر الرحلات متوقف · صورة جزئية",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "قائمة الطائرات القريبة غير مكتملة · لا يعني أن الوضع آمن",
   "SQUAWK {code} · {status}": "SQUAWK {code} · {status}",
   "ADS-B PRIORITY · {status}": "أولوية ADS-B · {status}",
   "ADS-B EMERGENCY · {status}": "طوارئ ADS-B · {status}",
diff --git a/src/i18n/locales/de.json b/src/i18n/locales/de.json
index 6876199d1..e4a41e7f2 100644
--- a/src/i18n/locales/de.json
+++ b/src/i18n/locales/de.json
@@ -2087,6 +2087,9 @@
   "{value} KM/H": "{value} KM/H",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · {radius} LUFT-/SEEFENSTER",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · ANLAGEN {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "MILITÄR-FEED AUS · UNVOLLSTÄNDIGES LAGEBILD",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "FLUG-FEED AUS · UNVOLLSTÄNDIGES LAGEBILD",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "FLUGZEUGE IN DER NÄHE UNVOLLSTÄNDIG · KEINE ENTWARNUNG",
   "SQUAWK {code} · {status}": "SQUAWK {code} · {status}",
   "ADS-B PRIORITY · {status}": "ADS-B-PRIORITÄT · {status}",
   "ADS-B EMERGENCY · {status}": "ADS-B-NOTFALL · {status}",
diff --git a/src/i18n/locales/es.json b/src/i18n/locales/es.json
index df11469ab..1066d8aea 100644
--- a/src/i18n/locales/es.json
+++ b/src/i18n/locales/es.json
@@ -1920,6 +1920,9 @@
   "N/A": "N/D",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · VENTANA AIRE/MAR {radius}",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · INSTALACIONES: {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "FUENTE MILITAR DESACTIVADA · PANORAMA PARCIAL",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "FUENTE DE VUELOS DESACTIVADA · PANORAMA PARCIAL",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "AERONAVES CERCANAS INCOMPLETAS · NO IMPLICA TODO DESPEJADO",
   "{source} · LOCATION QUERY · RECENT": "{source} · CONSULTA POR UBICACIÓN · RECIENTE",
   "ft": "ft",
   "kts": "kn",
diff --git a/src/i18n/locales/fr.json b/src/i18n/locales/fr.json
index 69d19c9f7..ab3032a3f 100644
--- a/src/i18n/locales/fr.json
+++ b/src/i18n/locales/fr.json
@@ -1660,6 +1660,9 @@
   "REGIONAL NEWS": "ACTUS RÉGIONALES",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · AIR/MER {radius}",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · INSTALLATIONS : {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "FLUX MILITAIRE COUPÉ · SITUATION PARTIELLE",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "FLUX DES VOLS COUPÉ · SITUATION PARTIELLE",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "AÉRONEFS PROCHES INCOMPLETS · PAS UN FEU VERT",
   "CONTEXT STANDBY": "CONTEXTE EN VEILLE",
   "ENABLE GLOBAL CONTEXT FOR PROXIMITY PINGS": "ACTIVER LE CONTEXTE GLOBAL POUR LES PINGS DE PROXIMITÉ",
   "CONTACT LOST · LAST KNOWN READOUT · NOT AN ALL-CLEAR": "CONTACT PERDU · DERNIER RELEVÉ CONNU · PAS UN FEU VERT",
diff --git a/src/i18n/locales/it.json b/src/i18n/locales/it.json
index f33721cbb..cd5c23cef 100644
--- a/src/i18n/locales/it.json
+++ b/src/i18n/locales/it.json
@@ -1660,6 +1660,9 @@
   "REGIONAL NEWS": "NOTIZIE REGIONALI",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · ARIA/MARE {radius}",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · SITI {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "FEED MILITARE DISATTIVATO · QUADRO PARZIALE",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "FEED VOLI DISATTIVATO · QUADRO PARZIALE",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "AEREI VICINI INCOMPLETI · NON È UN VIA LIBERA",
   "CONTEXT STANDBY": "CONTESTO IN ATTESA",
   "ENABLE GLOBAL CONTEXT FOR PROXIMITY PINGS": "ATTIVA IL CONTESTO GLOBALE PER I PING DI PROSSIMITÀ",
   "CONTACT LOST · LAST KNOWN READOUT · NOT AN ALL-CLEAR": "CONTATTO PERSO · ULTIMA LETTURA NOTA · NON È UN VIA LIBERA",
diff --git a/src/i18n/locales/ja.json b/src/i18n/locales/ja.json
index e47708830..84499fd8a 100644
--- a/src/i18n/locales/ja.json
+++ b/src/i18n/locales/ja.json
@@ -1612,6 +1612,9 @@
   "REGIONAL NEWS": "地域ニュース",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · 航空機/船舶の範囲 {radius}",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · 施設 {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "軍用フィードオフ · 部分的な状況",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "フライトフィードオフ · 部分的な状況",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "付近の航空機情報は不完全 · 安全の保証ではありません",
   "CONTEXT STANDBY": "コンテキスト待機",
   "ENABLE GLOBAL CONTEXT FOR PROXIMITY PINGS": "グローバルコンテキストを有効にすると近接ピングを表示",
   "CONTACT LOST · LAST KNOWN READOUT · NOT AN ALL-CLEAR": "コンタクト喪失 · 最終既知の値 · 安全の保証ではありません",
@@ -1684,7 +1687,7 @@
   "Restore real aircraft": "実際の航空機に戻す",
   "Reclassify as TR-3B": "TR-3Bに再分類",
   "TRACK ACQUIRED": "追跡開始",
-  "{label} · COURSE {heading}°": "{label} · 針路 {heading}°",
+  "{label} · COURSE {heading}°": "{label} · 対地針路 {heading}°",
   "Context could not restore every layer; try again": "コンテキストがすべてのレイヤーを復元できませんでした。もう一度お試しください",
   "No selected data layers": "選択中のデータレイヤーはありません",
   "{count} data layers could not be cleared": {
diff --git a/src/i18n/locales/pt.json b/src/i18n/locales/pt.json
index 23c44f786..56c56f36f 100644
--- a/src/i18n/locales/pt.json
+++ b/src/i18n/locales/pt.json
@@ -1660,6 +1660,9 @@
   "REGIONAL NEWS": "NOTÍCIAS DA ÁREA",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · AR/MAR {radius}",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · INSTALAÇÕES: {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "FEED MILITAR DESLIGADO · QUADRO PARCIAL",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "FEED DE VOOS DESLIGADO · QUADRO PARCIAL",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "AERONAVES PRÓXIMAS INCOMPLETAS · NÃO GARANTE SEGURANÇA",
   "CONTEXT STANDBY": "CONTEXTO EM ESPERA",
   "ENABLE GLOBAL CONTEXT FOR PROXIMITY PINGS": "ATIVE O CONTEXTO GLOBAL PARA PINGS DE PROXIMIDADE",
   "CONTACT LOST · LAST KNOWN READOUT · NOT AN ALL-CLEAR": "CONTATO PERDIDO · ÚLTIMA LEITURA CONHECIDA · NÃO GARANTE SEGURANÇA",
@@ -1736,7 +1739,7 @@
   "Restore real aircraft": "Restaurar a aeronave real",
   "Reclassify as TR-3B": "Reclassificar como TR-3B",
   "TRACK ACQUIRED": "RASTRO ADQUIRIDO",
-  "{label} · COURSE {heading}°": "{label} · CURSO {heading}°",
+  "{label} · COURSE {heading}°": "{label} · RUMO {heading}°",
   "Context could not restore every layer; try again": "O contexto não conseguiu restaurar todas as camadas; tente novamente",
   "No selected data layers": "Nenhuma camada de dados selecionada",
   "{count} data layers could not be cleared": {
diff --git a/src/i18n/locales/ru.json b/src/i18n/locales/ru.json
index b364d3bf1..764260167 100644
--- a/src/i18n/locales/ru.json
+++ b/src/i18n/locales/ru.json
@@ -458,7 +458,7 @@
   "SOURCE STATUS UNAVAILABLE": "СТАТУС ИСТОЧНИКА НЕДОСТУПЕН",
   "Select flight {title}": "Выбрать рейс {title}",
   "TRACK ACQUIRED": "ЦЕЛЬ ЗАХВАЧЕНА",
-  "{label} · COURSE {heading}°": "{label} · КУРС {heading}°",
+  "{label} · COURSE {heading}°": "{label} · ПУТЕВОЙ УГОЛ {heading}°",
   "Restore real aircraft": "Вернуть реальный самолёт",
   "Reclassify as TR-3B": "Переклассифицировать как TR-3B",
   "No selected data layers": "Нет выбранных слоёв данных",
@@ -1953,6 +1953,9 @@
   "N/A": "Н/Д",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · ОКНО ВОЗДУХ/МОРЕ {radius}",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · ОБЪЕКТЫ: {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "ВОЕННЫЙ ПОТОК ВЫКЛ · КАРТИНА НЕПОЛНАЯ",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "ПОТОК РЕЙСОВ ВЫКЛ · КАРТИНА НЕПОЛНАЯ",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "БЛИЖНИЕ ВОЗДУШНЫЕ СУДА: ДАННЫЕ НЕПОЛНЫЕ · ОТСУТСТВИЕ УГРОЗ НЕ ПОДТВЕРЖДЕНО",
   "{source} · LOCATION QUERY · RECENT": "{source} · ЗАПРОС ПО МЕСТУ · НЕДАВНИЕ",
   "ft": "фт",
   "kts": "уз",
diff --git a/src/i18n/locales/uk.json b/src/i18n/locales/uk.json
index d01a6af13..abf5a81a1 100644
--- a/src/i18n/locales/uk.json
+++ b/src/i18n/locales/uk.json
@@ -1683,6 +1683,9 @@
   "REGIONAL NEWS": "РЕГІОНАЛЬНІ НОВИНИ",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · РЕЙСИ / СУДНА · РАДІУС {radius}",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · ОБʼЄКТИ: {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "ВІЙСЬКОВИЙ ПОТІК ВИМК. · КАРТИНА НЕПОВНА",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "ПОТІК РЕЙСІВ ВИМК. · КАРТИНА НЕПОВНА",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "БЛИЗЬКІ ПОВІТРЯНІ СУДНА: ДАНІ НЕПОВНІ · НЕ ОЗНАЧАЄ «УСЕ ЧИСТО»",
   "CONTEXT STANDBY": "КОНТЕКСТ: ОЧІКУВАННЯ",
   "ENABLE GLOBAL CONTEXT FOR PROXIMITY PINGS": "УВІМКНІТЬ ГЛОБАЛЬНИЙ КОНТЕКСТ, ЩОБ БАЧИТИ КОНТАКТИ ПОБЛИЗУ",
   "CONTACT LOST · LAST KNOWN READOUT · NOT AN ALL-CLEAR": "КОНТАКТ ВТРАЧЕНО · ОСТАННІ ВІДОМІ ПОКАЗНИКИ · НЕ ОЗНАЧАЄ «УСЕ ЧИСТО»",
@@ -1761,7 +1764,7 @@
   "Restore real aircraft": "Повернути справжній літак",
   "Reclassify as TR-3B": "Перекласифікувати як TR-3B",
   "TRACK ACQUIRED": "ТРЕК ЗАХОПЛЕНО",
-  "{label} · COURSE {heading}°": "{label} · КУРС {heading}°",
+  "{label} · COURSE {heading}°": "{label} · ШЛЯХОВИЙ КУТ {heading}°",
   "Context could not restore every layer; try again": "Не вдалося відновити всі шари контексту; спробуйте ще раз",
   "No selected data layers": "Шари даних не вибрано",
   "{count} data layers could not be cleared": {
diff --git a/src/i18n/locales/zh-CN.json b/src/i18n/locales/zh-CN.json
index 07b1083ab..4259d04a0 100644
--- a/src/i18n/locales/zh-CN.json
+++ b/src/i18n/locales/zh-CN.json
@@ -1588,6 +1588,9 @@
   "REGIONAL NEWS": "地区新闻",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · {radius} 空/海监视窗口",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · 设施 {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "军用数据源已关闭 · 态势不完整",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "航班数据源已关闭 · 态势不完整",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "附近航空器信息不完整 · 不代表安全无虞",
   "CONTEXT STANDBY": "态势待机",
   "ENABLE GLOBAL CONTEXT FOR PROXIMITY PINGS": "启用全局态势以接收邻近目标提醒",
   "CONTACT LOST · LAST KNOWN READOUT · NOT AN ALL-CLEAR": "目标丢失 · 最后已知读数 · 不代表安全无虞",
@@ -1660,7 +1663,7 @@
   "Restore real aircraft": "恢复真实飞机",
   "Reclassify as TR-3B": "重新归类为 TR-3B",
   "TRACK ACQUIRED": "已获取航迹",
-  "{label} · COURSE {heading}°": "{label} · 航向 {heading}°",
+  "{label} · COURSE {heading}°": "{label} · 对地航向 {heading}°",
   "Context could not restore every layer; try again": "态势未能恢复所有图层，请重试",
   "No selected data layers": "没有已选数据图层",
   "{count} data layers could not be cleared": {
diff --git a/src/i18n/locales/zh-Hant.json b/src/i18n/locales/zh-Hant.json
index c13b7d39c..805255ca4 100644
--- a/src/i18n/locales/zh-Hant.json
+++ b/src/i18n/locales/zh-Hant.json
@@ -1578,6 +1578,9 @@
   "REGIONAL NEWS": "地區新聞",
   "{label} · {radius} AIR/SEA WINDOW": "{label} · {radius} 空/海監視窗口",
   "{scope} · INSTALLATIONS {coverage}": "{scope} · 設施 {coverage}",
+  "MILITARY FEED OFF · PARTIAL PICTURE": "軍用數據源已關閉 · 態勢不完整",
+  "FLIGHTS FEED OFF · PARTIAL PICTURE": "航班數據源已關閉 · 態勢不完整",
+  "NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR": "附近航空器資訊不完整 · 不代表安全無虞",
   "CONTEXT STANDBY": "態勢待機",
   "ENABLE GLOBAL CONTEXT FOR PROXIMITY PINGS": "啟用全局態勢以接收鄰近目標提醒",
   "CONTACT LOST · LAST KNOWN READOUT · NOT AN ALL-CLEAR": "目標丟失 · 最後已知讀數 · 不代表安全無虞",
@@ -1650,7 +1653,7 @@
   "Restore real aircraft": "恢復真實飛機",
   "Reclassify as TR-3B": "重新歸類為 TR-3B",
   "TRACK ACQUIRED": "已獲取航跡",
-  "{label} · COURSE {heading}°": "{label} · 航向 {heading}°",
+  "{label} · COURSE {heading}°": "{label} · 對地航向 {heading}°",
   "Context could not restore every layer; try again": "態勢未能恢復所有圖層，請重試",
   "No selected data layers": "沒有已選數據圖層",
   "{count} data layers could not be cleared": {
diff --git a/src/materialSymbolsSubset.test.mjs b/src/materialSymbolsSubset.test.mjs
index fdba1c49f..ab77d7c0c 100644
--- a/src/materialSymbolsSubset.test.mjs
+++ b/src/materialSymbolsSubset.test.mjs
@@ -11,6 +11,9 @@ const INDEX_HTML = path.join(REPO_ROOT, 'index.html');
 /** The glyph written as element text: `<span class="material-symbols-outlined">radar</span>`. */
 const SPAN_TEXT =
   /class="[^"]*material-symbols-outlined[^"]*"[^>]*>\s*([a-z0-9_]+)\s*</g;
+/** A glyph chosen in a Vue template: `<span class="material-symbols-outlined">{{ a ? 'x' : 'y' }}</span>`. */
+const SPAN_MUSTACHE =
+  /class="[^"]*material-symbols-outlined[^"]*"[^>]*>\s*\{\{([^}]{0,400})\}\}\s*</g;
 /** A whole `textContent =` statement, across lines, so a multi-line ternary is read once. */
 const TEXT_ASSIGNMENT = /(?:textContent|innerText)\s*=\s*([^;]{0,400})/gs;
 const STRING_LITERAL = /['"`]([a-z0-9_]{2,})['"`]/g;
@@ -64,7 +67,24 @@ function referencedGlyphs() {
     };
     for (const match of source.matchAll(SPAN_TEXT)) add(match[1]);
     for (const match of source.matchAll(ICON_PROPERTY)) add(match[1]);
-    for (const match of source.matchAll(TEXT_ASSIGNMENT)) {
+    // A template glyph bound to a computed (`{{ entryIcon }}`) is whatever
+    // that computed returns.
+    for (const [, expression] of source.matchAll(SPAN_MUSTACHE)) {
+      const name = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(expression)?.[1];
+      if (!name) continue;
+      const body = new RegExp(
+        `\\b${name}\\s*=\\s*computed\\(\\(\\)\\s*=>\\s*\\{([\\s\\S]{0,600}?)\\n\\}\\);`,
+      ).exec(source)?.[1];
+      for (const literal of body?.matchAll(
+        /\breturn\s+['"`]([a-z0-9_]{2,})['"`]/g,
+      ) ?? [])
+        add(literal[1]);
+    }
+    const expressions = [
+      ...source.matchAll(TEXT_ASSIGNMENT),
+      ...source.matchAll(SPAN_MUSTACHE),
+    ];
+    for (const match of expressions) {
       const statement = match[1].replaceAll('?.', '.');
       const assigned = statement.includes('?')
         ? statement.slice(statement.indexOf('?') + 1)
diff --git a/src/ui/cockpitBodyClasses.test.mjs b/src/ui/cockpitBodyClasses.test.mjs
new file mode 100644
index 000000000..adf897ce8
--- /dev/null
+++ b/src/ui/cockpitBodyClasses.test.mjs
@@ -0,0 +1,91 @@
+// src/ui/cockpitBodyClasses.test.mjs — the classes the Cockpit puts on
+// <body> must not also name an element's rule. A bare `.name { … }` written
+// for a panel matches <body> the moment <body> carries `name`, and its
+// pointer-events, position and overflow then apply to the whole page.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const UI_ROOT = fileURLToPath(new URL('.', import.meta.url));
+const SRC_ROOT = path.resolve(UI_ROOT, '..');
+const CONTROLLER = path.join(UI_ROOT, 'cockpitTrackingController.js');
+
+/** Every stylesheet the app ships. */
+function stylesheets(directory = SRC_ROOT) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const absolute = path.join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...stylesheets(absolute));
+    else if (entry.isFile() && entry.name.endsWith('.css'))
+      files.push(absolute);
+  }
+  return files;
+}
+
+/** A selector list split on its top-level commas, not those in `:not(a, b)`. */
+function splitSelectorList(list) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < list.length; i += 1) {
+    if (list[i] === '(') depth += 1;
+    else if (list[i] === ')') depth -= 1;
+    else if (list[i] === ',' && depth === 0) {
+      parts.push(list.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(list.slice(start));
+  return parts;
+}
+
+/** The classes the tracking controller adds to <body>. */
+function cockpitBodyClasses() {
+  const source = readFileSync(CONTROLLER, 'utf8');
+  const names = [
+    ...source.matchAll(/body\.classList\.add\(\s*'([a-z0-9-]+)'/g),
+  ].map((match) => match[1]);
+  return [...new Set(names)];
+}
+
+test('the Cockpit adds its subject classes to <body>', () => {
+  const classes = cockpitBodyClasses();
+  for (const name of ['cockpit-mode']) {
+    assert.ok(classes.includes(name), `${name} is not added to <body>`);
+  }
+});
+
+test('no stylesheet rule matches a Cockpit body class on another element', () => {
+  const offenders = [];
+  for (const name of cockpitBodyClasses()) {
+    // `.name` as a whole class token, not as `.name-suffix`.
+    const token = new RegExp(`\\.${name}(?![\\w-])`);
+    for (const file of stylesheets()) {
+      const css = readFileSync(file, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '');
+      for (const [, selectors] of css.matchAll(/([^{}]+)\{/g)) {
+        for (const selector of splitSelectorList(selectors)) {
+          // Prettier wraps long `:not(\n  .name\n)` arguments; unwrap them.
+          const compound = selector
+            .trim()
+            .replace(/\(\s+/g, '(')
+            .replace(/\s+\)/g, ')');
+          if (!token.test(compound)) continue;
+          // Allowed only on <body> itself: `body.name` or `body:not(.name)`.
+          const onBody = new RegExp(
+            `(^|[\\s>+~])body[^\\s>+~]*\\.${name}(?![\\w-])`,
+          );
+          if (onBody.test(compound)) continue;
+          offenders.push(`${path.relative(SRC_ROOT, file)}: ${compound}`);
+        }
+      }
+    }
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    'Selectors that match a Cockpit body class without `body.`: ' +
+      offenders.join('; '),
+  );
+});
diff --git a/src/ui/cockpitContext.js b/src/ui/cockpitContext.js
index 1158c632b..a343bbb91 100644
--- a/src/ui/cockpitContext.js
+++ b/src/ui/cockpitContext.js
@@ -24,6 +24,27 @@ const LOCALIZED_CONTEXT_SCOPE = Object.freeze({
     t('{scope} · INSTALLATIONS {coverage}', { scope, coverage }),
 });
 
+/**
+ * Which air feed the aircraft Cockpit's surrounding picture is missing. Entry
+ * needs only the ridden aircraft's own layer, so the other one may be off;
+ * the panels then say the picture is partial rather than present it as
+ * complete. Null with both feeds on, or when the owner cannot tell.
+ * @returns {?{title: string, detail: string}}
+ */
+export function readPartialPicture() {
+  const isLayerEnabled = this.services.isLayerEnabled;
+  if (typeof isLayerEnabled !== 'function') return null;
+  const militaryOff = !isLayerEnabled('military');
+  const flightsOff = !isLayerEnabled('flights');
+  if (!militaryOff && !flightsOff) return null;
+  return {
+    title: militaryOff
+      ? t('MILITARY FEED OFF · PARTIAL PICTURE')
+      : t('FLIGHTS FEED OFF · PARTIAL PICTURE'),
+    detail: t('NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR'),
+  };
+}
+
 /** Hand a fresh copy of the Contact card to the view. */
 export function publishContextView() {
   const view = this.contextView;
@@ -52,6 +73,7 @@ export function updateContext(info, heading) {
     this.services.militaryAwarenessLayer.getContextSnapshot?.() || null;
   const trackedId = info.icao24 || info.id;
   const readout = resolveCockpitContextReadout({ snapshot, info });
+  const partial = readPartialPicture.call(this);
   if (!readout.visible) {
     this.showContextCard(false);
     this.contextLayoutStamp = null;
@@ -61,6 +83,14 @@ export function updateContext(info, heading) {
       t('CONTEXT STANDBY'),
       t('ENABLE GLOBAL CONTEXT FOR PROXIMITY PINGS'),
     );
+    if (partial)
+      this.pushCockpitSignal(
+        'feed-status',
+        'warning',
+        partial.title,
+        partial.detail,
+      );
+    else this.dropCockpitSignal?.('feed-status');
     return;
   }
 
@@ -171,19 +201,22 @@ export function updateContext(info, heading) {
       angle: `${String(Math.round(Math.abs(relative))).padStart(3, '0')}°`,
     });
   }
-  view.uncertainty = unknownCount
-    ? tn(
-        unknownCount,
-        '{count} INPUT UNKNOWN · NOT AN ALL-CLEAR',
-        '{count} INPUTS UNKNOWN · NOT AN ALL-CLEAR',
-      )
-    : t('AVAILABLE INPUTS CURRENT · NOT AN ALL-CLEAR');
+  // A feed that is off outranks unknown inputs: the picture is partial.
+  view.uncertainty = partial
+    ? partial.title
+    : unknownCount
+      ? tn(
+          unknownCount,
+          '{count} INPUT UNKNOWN · NOT AN ALL-CLEAR',
+          '{count} INPUTS UNKNOWN · NOT AN ALL-CLEAR',
+        )
+      : t('AVAILABLE INPUTS CURRENT · NOT AN ALL-CLEAR');
   view.updated = Number.isFinite(snapshot.evaluatedAt)
     ? new Date(snapshot.evaluatedAt).toISOString().slice(11, 19) + 'Z'
     : '--:--:--Z';
-  view.state = unknownCount ? 'uncertain' : 'current';
+  view.state = unknownCount || partial ? 'uncertain' : 'current';
   this.publishContextView();
-  this.updateCockpitSignals(snapshot, unknownCount);
+  this.updateCockpitSignals(snapshot, unknownCount, partial);
   if (this.contextLayoutStamp !== snapshot.evaluatedAt) {
     this.contextLayoutStamp = snapshot.evaluatedAt;
     this.scheduleContextLayout();
diff --git a/src/ui/cockpitContext.test.mjs b/src/ui/cockpitContext.test.mjs
index 47d3719c7..4896d238e 100644
--- a/src/ui/cockpitContext.test.mjs
+++ b/src/ui/cockpitContext.test.mjs
@@ -204,6 +204,63 @@ test('without a snapshot the card stands by, hidden', async (t) => {
   assert.equal(signals.at(-1)[2], 'CONTEXT STANDBY');
 });
 
+test('a feed that is off makes the card and Live Signals say the picture is partial', async (t) => {
+  // Every input known, so only the feed that is off can make it partial.
+  const { $, text, owner } = fixture(
+    t,
+    snapshot({
+      cohorts: [
+        {
+          id: 'flights',
+          label: 'Flights',
+          count: 12,
+          relationship: 'OBSERVED',
+          nearest: [{ id: 'N1', distanceM: 4200 }],
+        },
+      ],
+    }),
+  );
+  const rebuilt = [];
+  owner.updateCockpitSignals = (...args) => rebuilt.push(args);
+  owner.services.isLayerEnabled = () => true;
+  updateContext.call(owner, INFO, 0);
+  await nextTick();
+  assert.equal($('#cockpit-context').dataset.state, 'current');
+  assert.equal(rebuilt.at(-1)[2], null, 'both feeds on: nothing to add');
+
+  owner.services.isLayerEnabled = (layerId) => layerId !== 'military';
+  updateContext.call(owner, INFO, 0);
+  await nextTick();
+  assert.equal($('#cockpit-context').dataset.state, 'uncertain');
+  assert.equal(
+    text('#cockpit-context-uncertainty'),
+    'MILITARY FEED OFF · PARTIAL PICTURE',
+  );
+  assert.deepEqual(rebuilt.at(-1)[2], {
+    title: 'MILITARY FEED OFF · PARTIAL PICTURE',
+    detail: 'NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR',
+  });
+});
+
+test('without Contacts, a feed that is off adds a signal until it is back', async (t) => {
+  const { owner, signals } = fixture(t, null);
+  const dropped = [];
+  owner.dropCockpitSignal = (key) => dropped.push(key);
+  // Riding a military aircraft with Live Flights off.
+  owner.services.isLayerEnabled = (layerId) => layerId === 'military';
+  updateContext.call(owner, { ...INFO, layerId: 'military' }, 0);
+  assert.equal(signals.at(-2)[2], 'CONTEXT STANDBY');
+  assert.deepEqual(signals.at(-1), [
+    'feed-status',
+    'warning',
+    'FLIGHTS FEED OFF · PARTIAL PICTURE',
+    'NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR',
+  ]);
+  owner.services.isLayerEnabled = () => true;
+  updateContext.call(owner, { ...INFO, layerId: 'military' }, 0);
+  assert.deepEqual(dropped, ['feed-status']);
+});
+
 test('the weather toggle renders its state and the action it offers', async (t) => {
   const { $, text, owner } = fixture(t);
   syncWeatherToggle.call(owner, true);
diff --git a/src/ui/cockpitController.js b/src/ui/cockpitController.js
index 50a397fc8..1e69146e3 100644
--- a/src/ui/cockpitController.js
+++ b/src/ui/cockpitController.js
@@ -1,6 +1,8 @@
 /** Coordinate Cockpit lifecycle through supplied aircraft, terrain, rendering and briefing operations. */
 import {
   readAircraftInfo,
+  readSubjectLayerId,
+  resolveEntryKind,
   dispatchCockpitModeChanged,
   toggleTrackedTr3b,
   syncTr3bToggle,
@@ -48,6 +50,7 @@ import {
   relocalizeBrief,
 } from './cockpitBriefing.js';
 import {
+  dropCockpitSignal,
   handleSignalClick,
   publishCockpitSignals,
   pushCockpitSignal,
@@ -60,7 +63,11 @@ import {
   syncContextLayout,
   syncSignalLayout,
 } from './cockpitLayout.js';
-import { onKeyDown } from './cockpitInput.js';
+import {
+  onKeyDown,
+  onSceneDoubleClick,
+  routeSceneDoubleClick,
+} from './cockpitInput.js';
 import * as Cesium from 'cesium';
 
 export class CockpitViewController {
@@ -205,6 +212,13 @@ export class CockpitViewController {
       }),
     );
     this._listen(this.entry, 'click', () => this.enter());
+    // Double-clicking the followed track is a third way in.
+    this._listenerRemovers.push(routeSceneDoubleClick.call(this));
+    // The readout's entry renders inside the Intel HUD, which may mount after
+    // this controller, so its clicks are delegated.
+    this._listen(document, 'click', (event) => {
+      if (event.target?.closest?.('#cockpit-entry-readout')) this.enter();
+    });
     this._listen(this.tr3bToggle, 'click', () => this.toggleTrackedTr3b());
     this._listen(this.mapViewButton, 'click', () => this.exit());
     this._listen(this.visionPrevious, 'click', () => this.cycleVisionMode(-1));
@@ -272,6 +286,12 @@ export class CockpitViewController {
   readAircraftInfo() {
     return readAircraftInfo.call(this);
   }
+  readSubjectLayerId() {
+    return readSubjectLayerId.call(this);
+  }
+  resolveEntryKind() {
+    return resolveEntryKind.call(this);
+  }
   dispatchCockpitModeChanged(active, info) {
     return dispatchCockpitModeChanged.call(this, active, info);
   }
@@ -371,8 +391,16 @@ export class CockpitViewController {
   pushCockpitSignal(key, tone, title, detail, target) {
     return pushCockpitSignal.call(this, key, tone, title, detail, target);
   }
-  updateCockpitSignals(snapshot, unknownCount) {
-    return updateCockpitSignals.call(this, snapshot, unknownCount);
+  dropCockpitSignal(key) {
+    return dropCockpitSignal.call(this, key);
+  }
+  updateCockpitSignals(snapshot, unknownCount, partialPicture) {
+    return updateCockpitSignals.call(
+      this,
+      snapshot,
+      unknownCount,
+      partialPicture,
+    );
   }
   scheduleContextLayout() {
     return scheduleContextLayout.call(this);
@@ -392,6 +420,9 @@ export class CockpitViewController {
   onKeyDown(event) {
     return onKeyDown.call(this, event);
   }
+  onSceneDoubleClick(position) {
+    return onSceneDoubleClick.call(this, position);
+  }
 
   handleSignalClick(event) {
     return handleSignalClick.call(this, event);
diff --git a/src/ui/cockpitCoordinator.js b/src/ui/cockpitCoordinator.js
index b71889b4c..7140f3172 100644
--- a/src/ui/cockpitCoordinator.js
+++ b/src/ui/cockpitCoordinator.js
@@ -1,6 +1,9 @@
 import { nextTick } from 'vue';
 import { CockpitViewController, CockpitDisplayPortal } from './cockpit.js';
-import { cockpitEntryAllowed } from '../contextModePolicy.js';
+import {
+  COCKPIT_AIRCRAFT_LAYER_IDS,
+  cockpitEntryAllowed,
+} from '../contextModePolicy.js';
 import { formatAwarenessLabel } from '../data/militaryAwarenessEngine.js';
 import { enterCockpitWithTracking } from '../cockpitTracking.js';
 import { cockpitVisionModeForStyle } from '../cockpitVisionPolicy.js';
@@ -72,19 +75,24 @@ export class CockpitCoordinator {
         fetchRegionalBrief,
         regionalDistanceM,
         weatherCodeLabel,
+        // The Contact card and Live Signals say which feeds are off.
+        isLayerEnabled: (layerId) => this._isLayerEnabled(layerId),
       },
       onVisionChange: (mode, active, options) =>
         this._setCockpitVision(mode, active, options),
       getInitialVisionMode: () => cockpitVisionModeForStyle(this.activeStyle),
       onCameraTakeover: () =>
         this._stampNavigation({ cancelPendingSelection: false }),
-      isEntryAllowed: () =>
-        cockpitEntryAllowed({
-          contextMode: this._contextMode,
+      // Only the tracked aircraft's own layer gates entry (see the policy).
+      isEntryAllowed: () => {
+        const subjectLayerId =
+          this.cockpitView?.readAircraftInfo?.()?.layerId ?? null;
+        return cockpitEntryAllowed({
+          subjectLayerId,
+          subjectLayerEnabled: this._isLayerEnabled(subjectLayerId),
           contextModeChanging: this._contextModeChanging,
-          flightsEnabled: !!this._dataManager?.isEnabled('flights'),
-          militaryEnabled: !!this._dataManager?.isEnabled('military'),
-        }),
+        });
+      },
       publish: this.publishCockpit,
       isUtilityDisclosureOpen: () => !!this.readUtilityDisclosureOpen?.(),
       onEntered: () => this.enterPanels(),
@@ -115,6 +123,28 @@ export class CockpitCoordinator {
   get activeStyle() {
     return this.readActiveStyle();
   }
+  /** Whether a data layer is enabled; false for no layer. */
+  _isLayerEnabled(layerId) {
+    return Boolean(layerId) && !!this._dataManager?.isEnabled(layerId);
+  }
+  /** Whether either aircraft layer is on, so there is an aircraft to ride. */
+  get _aircraftLayerEnabled() {
+    return COCKPIT_AIRCRAFT_LAYER_IDS.some((layerId) =>
+      this._isLayerEnabled(layerId),
+    );
+  }
+  /**
+   * Why voice entry must refuse before it touches tracking, or null. The
+   * tracked aircraft's own layer is checked again by the entry itself.
+   * @returns {string|null}
+   */
+  _cockpitEntryRefusal() {
+    if (this._contextModeChanging)
+      return 'Context is still changing — try Cockpit again in a moment';
+    if (!this._aircraftLayerEnabled)
+      return 'No aircraft layer is on — turn on Flights or Military Flights and track an aircraft to enter Cockpit';
+    return null;
+  }
   getCockpitState() {
     const { militaryAwarenessLayer } = this.services;
     const snapshot = militaryAwarenessLayer.getContextSnapshot?.();
@@ -129,19 +159,24 @@ export class CockpitCoordinator {
     const entryAllowed =
       !active &&
       Boolean(gateOpen && info && this.viewer?.trackedEntity?.position);
+    // Entry needs only the ridden aircraft's own layer: with one tracked,
+    // that layer; with none, any aircraft layer to track one from.
+    const subjectLayerOff = info
+      ? !this._isLayerEnabled(info.layerId)
+      : !this._aircraftLayerEnabled;
     return {
       active,
       entryAllowed,
       // Why entry is unavailable, so a refusal can be explained rather than
-      // guessed at.
+      // guessed at. Contacts is not required, so it is never the reason.
       entryBlockedReason:
         entryAllowed || active
           ? null
-          : !gateOpen
-            ? this._contextModeChanging
-              ? 'contacts-starting'
-              : 'contacts-inactive'
-            : 'no-tracked-aircraft',
+          : this._contextModeChanging
+            ? 'contacts-starting'
+            : subjectLayerOff
+              ? 'subject-layer-off'
+              : 'no-tracked-aircraft',
       visionMode: this.cockpitView?.visionMode || null,
       subject: info
         ? {
@@ -260,17 +295,18 @@ export class CockpitCoordinator {
       };
     }
     if (normalized === 'enter') {
-      // Entry is gated exactly as the manual entry chip is. Attempting it while
-      // the gate is shut produced the half-entered look the operator reported
-      // (a plane anchored under the camera with no cockpit around it), so
-      // refuse with the reason instead of trying.
-      if (!this.cockpitView.isEntryAllowed?.()) {
+      // Attempting entry while the gate is shut produced the half-entered look
+      // the operator reported (a plane anchored under the camera with no
+      // cockpit around it), so refuse with the reason instead of trying. The
+      // aircraft may not be tracked yet (a selection or a requested layer is
+      // adopted below), so this checks what can be known now; the entry
+      // itself then applies the manual chip's gate to the aircraft it rides.
+      const refusal = this._cockpitEntryRefusal();
+      if (refusal) {
         return {
           ok: false,
           action: 'control_cockpit',
-          error: this._contextModeChanging
-            ? 'Contacts is still starting up — try Cockpit again in a moment'
-            : 'Contacts must be active to enter Cockpit — say "open contacts" first',
+          error: refusal,
           state: this.getCockpitState(),
         };
       }
diff --git a/src/ui/cockpitEntryGate.test.mjs b/src/ui/cockpitEntryGate.test.mjs
new file mode 100644
index 000000000..5931ca5b2
--- /dev/null
+++ b/src/ui/cockpitEntryGate.test.mjs
@@ -0,0 +1,234 @@
+// src/ui/cockpitEntryGate.test.mjs — first person needs only the layer of
+// the vehicle it rides: Contacts and the other feeds may be off before or
+// during a session, turning the ridden layer off ends it, and the voice gate
+// and state say so without claiming Contacts is required. Over happy-dom.
+import '../testSupport/registerDom.mjs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createPinia } from 'pinia';
+import { createApp, defineComponent, h, nextTick } from 'vue';
+import { CockpitCoordinator } from './cockpitCoordinator.js';
+import { _handleContextLayerChange } from './contextLayerChanges.js';
+import { useCockpitStore } from './stores/cockpit.js';
+import { useHudStore } from './stores/hud.js';
+import ContextView from './views/ContextView.vue';
+import IntelHudView from './views/IntelHudView.vue';
+
+const CIVIL = Object.freeze({
+  icao24: 'abc123',
+  callsign: 'UAL123',
+  track: 92,
+  latitude: 30,
+  longitude: -97,
+});
+const MILITARY = Object.freeze({
+  ...CIVIL,
+  icao24: 'ae0001',
+  callsign: 'RCH1',
+});
+
+function fixture(
+  t,
+  {
+    enabled = [],
+    tracked = null,
+    contextMode = null,
+    changing = false,
+  } = {},
+) {
+  document.body.replaceChildren();
+  const host = document.body.appendChild(document.createElement('div'));
+  const pinia = createPinia();
+  const app = createApp(
+    defineComponent(() => () => [h(ContextView), h(IntelHudView)]),
+  ).use(pinia);
+  app.mount(host);
+  const store = useCockpitStore(pinia);
+  const layers = new Set(enabled);
+  const dataManager = { isEnabled: (layerId) => layers.has(layerId) };
+  // A layer that is off has no tracked aircraft, as the flight layers clear
+  // tracking on disable.
+  const trackedFrom = (layerId) => () =>
+    tracked?.layerId === layerId && layers.has(layerId) ? tracked.info : null;
+  const entity = {
+    position: { getValue: () => null },
+    show: true,
+    gevTrackedId: tracked ? `${tracked.layerId}:${tracked.info.icao24}` : '',
+  };
+  const listeners = () => ({ addEventListener: () => () => {} });
+  const viewer = {
+    trackedEntity: tracked ? entity : undefined,
+    clock: { currentTime: null },
+    camera: { cancelFlight() {}, frustum: { fov: 1, aspectRatio: 1 } },
+    entities: { contains: (candidate) => candidate === entity },
+    scene: {
+      preUpdate: listeners(),
+      screenSpaceCameraController: { enableInputs: true },
+    },
+    trackedEntityChanged: listeners(),
+  };
+  const context = { mode: contextMode, changing };
+  const coordinator = new CockpitCoordinator({
+    viewer,
+    services: {
+      flightsLayer: { getTrackedInfo: trackedFrom('flights') },
+      militaryFlightsLayer: { getTrackedInfo: trackedFrom('military') },
+      militaryAwarenessLayer: { getContextSnapshot: () => null },
+      isTr3b: () => false,
+      holdContinuousRender() {},
+      releaseContinuousRender() {},
+    },
+    elements: {},
+    operations: {
+      publishCockpit: { presence: (view) => store.publishPresence(view) },
+      _stampNavigation() {},
+      getAircraftTrackingTarget: () =>
+        tracked ? { layerId: tracked.layerId, id: tracked.info.icao24 } : null,
+    },
+    readDataManager: () => dataManager,
+    readContext: () => context,
+    readActiveStyle: () => 'normal',
+    readUtilityDisclosureOpen: () => false,
+    enterPanels() {},
+    exitPanels() {},
+  });
+  const cockpit = coordinator.cockpitView;
+  // The HUD, briefing and signals have their own tests.
+  Object.assign(cockpit, {
+    updateHud() {},
+    setVisionMode() {},
+    showBriefPage() {},
+    startBriefRotation() {},
+    stopBriefRotation() {},
+    pushCockpitSignal() {},
+    scheduleContextLayout() {},
+    clearPredictiveRoute() {},
+  });
+  t.after(() => {
+    coordinator.stop();
+    app.unmount();
+    document.body.classList.remove('cockpit-mode');
+  });
+  /** Turn a layer off and tell the Context owner, as the data manager does. */
+  const disable = (layerId) => {
+    layers.delete(layerId);
+    _handleContextLayerChange.call(
+      {
+        cockpitView: cockpit,
+        _dataManager: dataManager,
+        _contextMode: null,
+        _contextModeChanging: false,
+        _contextSessionSnapshot: null,
+        _contextRestoreState: null,
+        _syncContextModeButtons() {},
+      },
+      { type: 'visibility', layerId, enabled: false, origin: 'user' },
+    );
+  };
+  const $ = (selector) => document.querySelector(selector);
+  return { $, coordinator, cockpit, store, layers, disable, pinia };
+}
+
+test('a civilian aircraft enters with Live Flights alone: no Contacts, no Military', (t) => {
+  const { coordinator, cockpit } = fixture(t, {
+    enabled: ['flights'],
+    tracked: { layerId: 'flights', info: CIVIL },
+  });
+  const state = coordinator.getCockpitState();
+  assert.equal(state.entryAllowed, true);
+  assert.equal(state.entryBlockedReason, null);
+  assert.equal(cockpit.enter(), true);
+});
+
+test('a military aircraft enters with Military Flights alone', (t) => {
+  const { coordinator, cockpit } = fixture(t, {
+    enabled: ['military'],
+    tracked: { layerId: 'military', info: MILITARY },
+  });
+  assert.equal(coordinator.getCockpitState().entryAllowed, true);
+  assert.equal(cockpit.enter(), true);
+});
+
+test('a Context change in flight still blocks entry, and says so', (t) => {
+  const { coordinator, cockpit } = fixture(t, {
+    enabled: ['flights', 'military'],
+    tracked: { layerId: 'flights', info: CIVIL },
+    contextMode: 'flights',
+    changing: true,
+  });
+  const state = coordinator.getCockpitState();
+  assert.equal(state.entryAllowed, false);
+  assert.equal(state.entryBlockedReason, 'contacts-starting');
+  assert.equal(cockpit.enter(), false);
+  const voice = coordinator.controlCockpit('enter');
+  assert.equal(voice.ok, false);
+  assert.match(voice.error, /Context is still changing/);
+  assert.equal(cockpit.active, false);
+});
+
+test('with no aircraft layer on, entry is refused for that reason, never for Contacts', (t) => {
+  const { coordinator, cockpit } = fixture(t);
+  const state = coordinator.getCockpitState();
+  assert.equal(state.entryBlockedReason, 'subject-layer-off');
+  const voice = coordinator.controlCockpit('enter');
+  assert.equal(voice.ok, false);
+  assert.match(voice.error, /No aircraft layer is on/);
+  assert.doesNotMatch(voice.error, /contacts/i);
+  assert.equal(voice.state.entryBlockedReason, 'subject-layer-off');
+  assert.equal(cockpit.active, false);
+});
+
+test('with an aircraft layer on but nothing tracked, the reason is the missing aircraft', (t) => {
+  const { coordinator } = fixture(t, { enabled: ['military'] });
+  assert.equal(
+    coordinator.getCockpitState().entryBlockedReason,
+    'no-tracked-aircraft',
+  );
+});
+
+test('voice enters without Contacts when the ridden layer is on', (t) => {
+  const { coordinator, cockpit } = fixture(t, {
+    enabled: ['flights'],
+    tracked: { layerId: 'flights', info: CIVIL },
+  });
+  const result = coordinator.controlCockpit('enter');
+  assert.equal(result.ok, true, result.error);
+  assert.equal(cockpit.active, true);
+});
+
+test('other layers may be turned off during a session; the ridden layer ends it', (t) => {
+  const { cockpit, disable } = fixture(t, {
+    enabled: ['flights', 'military', 'ais-live-vessels'],
+    tracked: { layerId: 'flights', info: CIVIL },
+  });
+  assert.equal(cockpit.enter(), true);
+  disable('military');
+  disable('ais-live-vessels');
+  assert.equal(cockpit.active, true, 'other feeds are free to go off');
+  disable('flights');
+  assert.equal(cockpit.active, false, 'the ridden layer going off ends it');
+});
+
+test('the readout offers the same entry, labelled by kind, and enters on click', async (t) => {
+  const { $, cockpit, pinia } = fixture(t, {
+    enabled: ['flights'],
+    tracked: { layerId: 'flights', info: CIVIL },
+  });
+  useHudStore(pinia);
+  const readoutEntry = $('#cockpit-entry-readout');
+  assert.equal(readoutEntry.hidden, true, 'hidden until entry is available');
+  cockpit.syncEntry();
+  await nextTick();
+  assert.equal(readoutEntry.hidden, false);
+  assert.match(readoutEntry.textContent, /flight/);
+  assert.match(readoutEntry.textContent, /COCKPIT/);
+  assert.equal(
+    $('#cockpit-entry').hidden,
+    false,
+    'the Contacts entry follows the same presence',
+  );
+  readoutEntry.click();
+  await nextTick();
+  assert.equal(cockpit.active, true);
+  assert.equal(readoutEntry.hidden, true, 'inside, there is nothing to enter');
+});
diff --git a/src/ui/cockpitInput.js b/src/ui/cockpitInput.js
index 54b8f56a9..15b4207e1 100644
--- a/src/ui/cockpitInput.js
+++ b/src/ui/cockpitInput.js
@@ -1,5 +1,99 @@
 /** Route Cockpit keys while preserving the active disclosure and form-control owner. */
+import * as Cesium from 'cesium';
+import { isPointerFree } from '../data/inputOwnership.js';
 
+/** How far from the followed track a double-click may land, CSS pixels. */
+export const SUBJECT_DOUBLE_CLICK_RADIUS_PX = 32;
+
+/**
+ * Whether a double-click landed on the followed track's mark.
+ * @param {{x: number, y: number}|null} click Canvas position of the click.
+ * @param {{x: number, y: number}|null|undefined} subject Canvas position of
+ *   the track, or nothing when it is off screen.
+ * @param {number} [radiusPx]
+ */
+export function doubleClickHitsSubject(
+  click,
+  subject,
+  radiusPx = SUBJECT_DOUBLE_CLICK_RADIUS_PX,
+) {
+  if (!click || !subject) return false;
+  const distance = Math.hypot(click.x - subject.x, click.y - subject.y);
+  return Number.isFinite(distance) && distance <= radiusPx;
+}
+
+/** Where the track `kind` would ride is drawn now, as a world position. */
+function subjectWorldPosition(kind) {
+  if (kind !== 'aircraft') return null;
+  return (
+    this.viewer.trackedEntity?.position?.getValue?.(
+      this.viewer.clock?.currentTime,
+    ) ?? null
+  );
+}
+
+/** The followed track's canvas position now, or null off screen. */
+function subjectCanvasPosition() {
+  const kind = this.resolveEntryKind();
+  const world = kind ? subjectWorldPosition.call(this, kind) : null;
+  const scene = this.viewer.scene;
+  if (!world || typeof scene?.cartesianToCanvasCoordinates !== 'function')
+    return null;
+  return (
+    scene.cartesianToCanvasCoordinates(world, new Cesium.Cartesian2()) ?? null
+  );
+}
+
+/**
+ * Enter first person when the followed track itself is double-clicked: the
+ * same entry, and the same gates, as C and the entry buttons. A
+ * double-click anywhere else, or one a tool owns (drawing ends a shape with
+ * one), is left alone.
+ * @param {{x: number, y: number}|null|undefined} position Canvas position.
+ * @returns {boolean} True when it landed on the followed track, entered or
+ *   refused by the gate: the caller does nothing else with it.
+ */
+export function onSceneDoubleClick(position) {
+  if (this.active || this.destroyed || !isPointerFree()) return false;
+  if (!Number.isFinite(position?.x) || !Number.isFinite(position?.y))
+    return false;
+  if (!doubleClickHitsSubject(position, subjectCanvasPosition.call(this)))
+    return false;
+  this.enter();
+  return true;
+}
+
+/**
+ * Take the scene's double-click through the Cockpit first. Cesium's Viewer
+ * installs its own (pickAndTrackObject), which untracks whenever the pick is
+ * not an Entity: on a followed aircraft's model, a primitive, it would drop
+ * the very track the double-click means to ride. A double-click on the
+ * followed track is the Cockpit's; any other goes on to Cesium's.
+ * @returns {() => void} Puts Cesium's handler back, unless another owner
+ *   (the draw tool borrows it) has replaced ours since.
+ */
+export function routeSceneDoubleClick() {
+  const handler = this.viewer.screenSpaceEventHandler;
+  if (typeof handler?.setInputAction !== 'function') return () => {};
+  const type = Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK;
+  const stock = handler.getInputAction?.(type) ?? null;
+  const routed = (event) => {
+    if (this.onSceneDoubleClick(event?.position)) return;
+    stock?.(event);
+  };
+  handler.setInputAction(routed, type);
+  return () => {
+    if (handler.isDestroyed?.() || handler.getInputAction?.(type) !== routed)
+      return;
+    if (stock) handler.setInputAction(stock, type);
+    else handler.removeInputAction(type);
+  };
+}
+
+/**
+ * The Cockpit's capture-phase keydown: Escape and C.
+ * @param {KeyboardEvent} event
+ */
 export function onKeyDown(event) {
   if (this.destroyed) return false;
   if (event.repeat || event.isComposing) return;
diff --git a/src/ui/cockpitPresentation.js b/src/ui/cockpitPresentation.js
index fc62ceaad..b56a81892 100644
--- a/src/ui/cockpitPresentation.js
+++ b/src/ui/cockpitPresentation.js
@@ -144,3 +144,21 @@ export function formatCockpitWindDirection(value) {
   const degrees = roundHeadingDegrees(value);
   return `${compassPointLabel(labels[Math.round(normalized / 45) % labels.length])} · ${degrees}°`;
 }
+
+/**
+ * The Cockpit entry for each subject it can ride: an aircraft's cockpit.
+ * Both entry buttons (Contacts and the Intel HUD readout) show it.
+ */
+const COCKPIT_ENTRY_FACES = Object.freeze({
+  aircraft: Object.freeze({ icon: 'flight', label: msg('COCKPIT') }),
+});
+
+/**
+ * The entry's glyph and localized label for the subject it would ride.
+ * @param {'aircraft'|null|undefined} kind
+ * @returns {{icon: string, label: string}}
+ */
+export function cockpitEntryFace(kind) {
+  const face = COCKPIT_ENTRY_FACES[kind] ?? COCKPIT_ENTRY_FACES.aircraft;
+  return { icon: face.icon, label: t(face.label) };
+}
diff --git a/src/ui/cockpitSignals.js b/src/ui/cockpitSignals.js
index 2319a6d21..395db8116 100644
--- a/src/ui/cockpitSignals.js
+++ b/src/ui/cockpitSignals.js
@@ -62,7 +62,31 @@ export function pushCockpitSignal(key, tone, title, detail, target = null) {
   this.publishCockpitSignals();
 }
 
-export function updateCockpitSignals(snapshot, unknownCount) {
+/**
+ * Take a status row off the list, as when the feed it warned about is back.
+ * @param {string} key The row's key.
+ */
+export function dropCockpitSignal(key) {
+  this.signalSignatures.delete(key);
+  const kept = this.signalItems.filter((item) => item.key !== key);
+  if (kept.length === this.signalItems.length) return;
+  this.signalItems = kept;
+  this.publishCockpitSignals();
+}
+
+/**
+ * Rebuild the rows from a Contacts snapshot: the nearest flights, a row for
+ * unknown inputs and, first, a row naming an air feed that is off.
+ * @param {object} snapshot `militaryAwareness.getContextSnapshot()` result.
+ * @param {number} unknownCount Cohorts whose count is unknown.
+ * @param {?{title: string, detail: string}} [partialPicture] The feed-off
+ *   row (see `readPartialPicture`), or null with every air feed on.
+ */
+export function updateCockpitSignals(
+  snapshot,
+  unknownCount,
+  partialPicture = null,
+) {
   const previous = new Map(this.signalItems.map((item) => [item.key, item]));
   const contacts = [];
   const subject = snapshot.subject;
@@ -110,7 +134,9 @@ export function updateCockpitSignals(snapshot, unknownCount) {
     }
   }
   contacts.sort((a, b) => a.distanceM - b.distanceM);
-  const nextItems = contacts.slice(0, 5).map((item) => ({
+  // A feed-off row leads, so the list never reads as the whole picture.
+  const reserved = partialPicture ? 1 : 0;
+  const nextItems = contacts.slice(0, 5 - reserved).map((item) => ({
     ...item,
     timestamp:
       previous.get(item.key)?.timestamp || snapshot.evaluatedAt || Date.now(),
@@ -120,18 +146,35 @@ export function updateCockpitSignals(snapshot, unknownCount) {
       .filter((cohort) => cohort.count === null)
       .map((cohort) => cohort.source)
       .join(' · ');
-    nextItems.splice(4, Math.max(0, nextItems.length - 4), {
-      key: 'input-status',
+    nextItems.splice(
+      4 - reserved,
+      Math.max(0, nextItems.length - 4 + reserved),
+      {
+        key: 'input-status',
+        tone: 'warning',
+        title: tn(
+          unknownCount,
+          '{count} INPUT UNKNOWN',
+          '{count} INPUTS UNKNOWN',
+        ),
+        detail: sources || t('SOURCE STATUS UNAVAILABLE'),
+        target: null,
+        timestamp:
+          previous.get('input-status')?.timestamp ||
+          snapshot.evaluatedAt ||
+          Date.now(),
+      },
+    );
+  }
+  if (partialPicture) {
+    nextItems.unshift({
+      key: 'feed-status',
       tone: 'warning',
-      title: tn(
-        unknownCount,
-        '{count} INPUT UNKNOWN',
-        '{count} INPUTS UNKNOWN',
-      ),
-      detail: sources || t('SOURCE STATUS UNAVAILABLE'),
+      title: partialPicture.title,
+      detail: partialPicture.detail,
       target: null,
       timestamp:
-        previous.get('input-status')?.timestamp ||
+        previous.get('feed-status')?.timestamp ||
         snapshot.evaluatedAt ||
         Date.now(),
     });
diff --git a/src/ui/cockpitTrackingController.js b/src/ui/cockpitTrackingController.js
index f308b0d2f..3ad6267ff 100644
--- a/src/ui/cockpitTrackingController.js
+++ b/src/ui/cockpitTrackingController.js
@@ -17,6 +17,30 @@ export function readAircraftInfo() {
   });
 }
 
+/**
+ * The layer the active view rides: the aircraft's own layer. It is read from
+ * the tracked entity's id once the layer has dropped its tracking, so a layer
+ * turned off still names itself.
+ * @returns {'flights'|'military'|null}
+ */
+export function readSubjectLayerId() {
+  if (!this.active) return null;
+  const layerId = this.readAircraftInfo()?.layerId;
+  if (layerId) return layerId;
+  const [prefix] = String(this.trackedEntity?.gevTrackedId || '').split(':');
+  return ['flights', 'military'].includes(prefix) ? prefix : null;
+}
+
+/**
+ * The subject entry would take: a Cesium-tracked aircraft.
+ * @returns {'aircraft'|null}
+ */
+export function resolveEntryKind() {
+  return this.readAircraftInfo() && this.viewer.trackedEntity?.position
+    ? 'aircraft'
+    : null;
+}
+
 export function dispatchCockpitModeChanged(active, info = null) {
   const subjectId = active
     ? String(info?.icao24 || '')
@@ -247,9 +271,12 @@ export function exit({ restoreTracking = true } = {}) {
     this.restoreTrackingFrame(entity);
   }
   this.syncEntry();
+  // Back to whichever entry was used: the Contacts button or the readout's.
+  const readoutEntry = document.getElementById('cockpit-entry-readout');
   const restoreTarget =
-    this.entryFocusOrigin === this.entry
-      ? this.entry
+    this.entryFocusOrigin === this.entry ||
+    (readoutEntry && this.entryFocusOrigin === readoutEntry)
+      ? this.entryFocusOrigin
       : this.entry || this.entryFocusOrigin;
   this.entryFocusOrigin = null;
   // The entry shows when Vue flushes the presence; read it after.
diff --git a/src/ui/contextLayerChanges.js b/src/ui/contextLayerChanges.js
index fc5abe3a7..d4ddd6cd5 100644
--- a/src/ui/contextLayerChanges.js
+++ b/src/ui/contextLayerChanges.js
@@ -1,7 +1,6 @@
 import { t, translateKnown } from '../i18n/index.js';
 import {
   SPACE_MISSIONS_LAYER_BLOCK_REASON,
-  cockpitEntryAllowed,
   isExplicitUserIntentOrigin,
   parseContextLayerBlockReason,
   recordContextRestoreExplicitChange,
@@ -245,15 +244,12 @@ export function _handleContextLayerChange(change) {
       );
     }
   }
-  if (
-    this.cockpitView?.active &&
-    !cockpitEntryAllowed({
-      contextMode: this._contextMode,
-      contextModeChanging: this._contextModeChanging,
-      flightsEnabled: !!this._dataManager?.isEnabled('flights'),
-      militaryEnabled: !!this._dataManager?.isEnabled('military'),
-    })
-  ) {
+  // Turning off the layer the view rides ends it; every other layer may be
+  // turned on or off freely during a session.
+  const riddenLayerId = this.cockpitView?.active
+    ? this.cockpitView.readSubjectLayerId?.()
+    : null;
+  if (riddenLayerId && !this._dataManager?.isEnabled(riddenLayerId)) {
     this.cockpitView.exit({ restoreTracking: false });
   }
   this._syncContextModeButtons();
diff --git a/src/ui/contextTransactions.js b/src/ui/contextTransactions.js
index 729edc654..e8a69b5fc 100644
--- a/src/ui/contextTransactions.js
+++ b/src/ui/contextTransactions.js
@@ -18,7 +18,10 @@ export async function _selectContextMode(
   this._contextModeChanging = true;
   this._syncContextModeButtons();
   try {
-    if (mode !== 'flights' && this.cockpitView?.active) {
+    // Cockpit does not need Contacts, so leaving it keeps the view; the
+    // restore below ends it only by turning off the layer it rides. Another
+    // mode takes the camera, so switching to one ends it.
+    if (mode && mode !== 'flights' && this.cockpitView?.active) {
       this.cockpitView.exit({ restoreTracking: false });
     }
     if (!mode) {
@@ -220,8 +223,8 @@ export async function _deactivateContextForLayerChange({
   this._contextMode = null;
   this._contextModeEntryIntent = null;
   this._contextModeReplacementIntent = null;
-  if (this.cockpitView?.active)
-    this.cockpitView.exit({ restoreTracking: false });
+  // A layer turned off ends Contacts but not the Cockpit: the view ends only
+  // when the layer it rides goes off (see _handleContextLayerChange).
   this._syncContextModeButtons();
   try {
     await this._restoreContextSession({ notificationToken });
diff --git a/src/ui/styles/cockpit.css b/src/ui/styles/cockpit.css
index befbfbbff..d7ad845b6 100644
--- a/src/ui/styles/cockpit.css
+++ b/src/ui/styles/cockpit.css
@@ -33,6 +33,36 @@
   color: #00dcff;
   font-size: 18px;
 }
+/* The same entry under the selected vehicle's Intel HUD readout. The HUD
+   lets clicks through, so the button takes them back. */
+#intel-hud #cockpit-entry-readout {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 6px;
+  min-height: 30px;
+  padding: 0 10px;
+  border: 1px solid var(--hud-border);
+  border-radius: 6px;
+  background: rgba(2, 12, 18, 0.72);
+  font-size: 10px;
+  letter-spacing: 0.14em;
+  pointer-events: auto;
+  cursor: pointer;
+}
+#intel-hud #cockpit-entry-readout[hidden] {
+  display: none;
+}
+#intel-hud #cockpit-entry-readout:hover,
+#intel-hud #cockpit-entry-readout:focus-visible {
+  border-color: var(--hud-color);
+  outline: none;
+}
+#intel-hud #cockpit-entry-readout .material-symbols-outlined {
+  font-family: 'Material Symbols Outlined';
+  font-size: 16px;
+  text-transform: none;
+}
 #cockpit-entry kbd {
   padding: 3px 5px;
   border: 1px solid rgba(220, 238, 255, 0.25);
diff --git a/src/ui/views/ContextView.vue b/src/ui/views/ContextView.vue
index f330391e9..c40665fe4 100644
--- a/src/ui/views/ContextView.vue
+++ b/src/ui/views/ContextView.vue
@@ -14,11 +14,14 @@ import MissionDetail from './panels/MissionDetail.vue';
 import MissionRoster from './panels/MissionRoster.vue';
 import RadioPanel from './panels/RadioPanel.vue';
 import UiButton from '../kit/UiButton.vue';
+import { cockpitEntryFace } from '../cockpitPresentation.js';
 
 // ContextControls presents the mode switch and the nearby sites search and
 // publishes them; until it does, the panel shows its initial markup.
 const { view: ctx } = storeToRefs(useContextStore());
 const { presence: cockpit } = storeToRefs(useCockpitStore());
+// The entry rides the tracked aircraft (cockpitEntryFace).
+const entry = computed(() => cockpitEntryFace('aircraft'));
 // While the Bhote Koshi event is on, its panel is the rail's only content.
 const { panel: bhotePanel } = storeToRefs(useBhoteKoshiPanelStore());
 // The Scene runtime chip SceneControls presents while a scene plays.
@@ -56,8 +59,8 @@ const sceneRuntime = computed(() => scenePanel.value?.runtime ?? '');
         <section id="context-flights-view" class="context-mode-view" role="tabpanel" aria-labelledby="global-context-flights-btn" :hidden="!ctx?.flightsActive">
           <div class="global-context-actions" :aria-label="t('Contact Context actions')">
             <button id="cockpit-entry" type="button" :hidden="!cockpit?.entryAvailable">
-              <span class="material-symbols-outlined" aria-hidden="true">flight</span>
-              <span>{{ t('COCKPIT') }}</span>
+              <span class="material-symbols-outlined" aria-hidden="true">{{ entry.icon }}</span>
+              <span>{{ entry.label }}</span>
             </button>
             <button id="installations-search-btn" class="panel-layer-toggle" type="button" :aria-disabled="ctx && String(ctx.installationsBusy)" :aria-busy="ctx && String(ctx.installationsBusy)">{{ t('SEARCH NEARBY SITES') }}</button>
             <UiButton id="tr3b-toggle" class="tr3b-toggle" :pressed="!!cockpit?.tr3b?.converted" :hidden="!cockpit?.tr3b" :aria-label="t('Reclassify tracked contact as TR-3B')" :title="cockpit?.tr3b?.converted ? t('Restore real aircraft') : t('Reclassify as TR-3B')">🛸</UiButton>
diff --git a/src/ui/views/IntelHudView.vue b/src/ui/views/IntelHudView.vue
index 77cd0c4fd..6f60bce76 100644
--- a/src/ui/views/IntelHudView.vue
+++ b/src/ui/views/IntelHudView.vue
@@ -2,6 +2,8 @@
 import { computed } from 'vue';
 import { storeToRefs } from 'pinia';
 import { useHudStore } from '../stores/hud.js';
+import { useCockpitStore } from '../stores/cockpit.js';
+import { cockpitEntryFace } from '../cockpitPresentation.js';
 
 // The readouts, visibility, layout variant and colors IntelHUD publishes.
 const { hud } = storeToRefs(useHudStore());
@@ -10,6 +12,12 @@ const { hud } = storeToRefs(useHudStore());
 // right after IntelHUD is built.
 const EMPTY = Object.freeze({ vessel: {}, sensor: [], recShown: null });
 const view = computed(() => hud.value ?? EMPTY);
+// The selected vehicle's readout offers the same entry as the Contacts
+// button, so first person needs no Contacts panel. The Cockpit controller
+// answers its clicks.
+const { presence: cockpit } = storeToRefs(useCockpitStore());
+// The entry rides the tracked aircraft (cockpitEntryFace).
+const entry = computed(() => cockpitEntryFace('aircraft'));
 </script>
 
 <template>
@@ -46,6 +54,10 @@ const view = computed(() => hud.value ?? EMPTY);
         <div class="hud-readout"><div id="hud-gsd">{{ view.gsd }}</div></div>
         <div class="hud-readout"><div id="hud-alt">{{ view.alt }}</div></div>
         <div class="hud-readout"><div id="hud-ais-vessel" :class="['hud-ais-vessel', { active: view.vessel.active }]">{{ view.vessel.text }}</div></div>
+        <button id="cockpit-entry-readout" type="button" :hidden="!cockpit?.entryAvailable">
+          <span class="material-symbols-outlined" aria-hidden="true">{{ entry.icon }}</span>
+          <span>{{ entry.label }}</span>
+        </button>
       </div>
       <div class="hud-bracket">┘</div>
     </div>
diff --git a/src/voice/actionSchemas.test.mjs b/src/voice/actionSchemas.test.mjs
index 5c84259ad..bbb1ed13b 100644
--- a/src/voice/actionSchemas.test.mjs
+++ b/src/voice/actionSchemas.test.mjs
@@ -55,7 +55,8 @@ test('the complete Realtime tool payload pins the manifest-generated layer relea
     // Voice geometry adds resolve_area, find_imagery, osm_query, the analyst
     // area scopes and the osm-places layer; natural-region candidates and the
     // tightened area tool wording follow review.
-    'd0c5ad733670972713a54cb10676c42b7c6e78834bfff52b473c0e8a45e742c3',
+    // control_cockpit states the own-layer entry rule (Contacts not required).
+    '9522ff6f6d640bede81c51cea6b9601439b08becc5bc20b7355aec24feb17e8d',
   );
 });
 

From 459b0e8a7113e0555940fd42dabfaa8bb9ed2c75 Mon Sep 17 00:00:00 2001
From: Denis Groshev <denis@halfpixel.ai>
Date: Wed, 4 Nov 2026 20:29:07 +0100
Subject: [PATCH 32/71] docs(changelog): add the #1556 fragment

---
 changelog.d/1556-cockpit-own-layer-entry.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 changelog.d/1556-cockpit-own-layer-entry.md

diff --git a/changelog.d/1556-cockpit-own-layer-entry.md b/changelog.d/1556-cockpit-own-layer-entry.md
new file mode 100644
index 000000000..ca5210120
--- /dev/null
+++ b/changelog.d/1556-cockpit-own-layer-entry.md
@@ -0,0 +1,5 @@
+- Enter Cockpit with only the ridden aircraft's layer on. Contacts is no longer
+  required; turning off the aircraft's own feed ends the view, a missing other
+  feed reads `… FEED OFF · PARTIAL PICTURE`, and double-clicking the followed
+  aircraft or the entry beside its readout enters it (Denis Groshev, @ZloyS,
+  #1556).

From ad48305dac0f4f008a0b94da7db91e6169faf771 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Itallo=20Brand=C3=A3o?=
 <45429643+IMBrandao@users.noreply.github.com>
Date: Wed, 4 Nov 2026 22:49:54 -0300
Subject: [PATCH 33/71] feat(transit): name Rio routes from SMTR's published
 GTFS

SMTR's realtime feeds carry internal route keys, so a Rio card read
"Route O0731AAN0A" where riders know line SN731. Join both feeds to the
route_short_name in SMTR's static GTFS routes.txt (CC BY 4.0, same
publisher and terms). The keys cannot be parsed: O0014AAA0A is LECD135.
A 2026-11-04 snapshot found all 282 bus and 21 BRT routes in service in
the table; an unknown key still falls through raw.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 DATA_SOURCES.md                 |   2 +-
 changelog.d/1481-rio-transit.md |   4 +-
 src/data/rioRouteNames.js       | 515 ++++++++++++++++++++++++++++++++
 src/data/transitFeeds.js        |  19 +-
 src/data/transitFeeds.test.mjs  |  31 ++
 5 files changed, 567 insertions(+), 4 deletions(-)
 create mode 100644 src/data/rioRouteNames.js

diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md
index 743d83978..2ed14c264 100644
--- a/DATA_SOURCES.md
+++ b/DATA_SOURCES.md
@@ -98,7 +98,7 @@ How to read this:
 | **Barrie Transit** (myridebarrie.ca) | Transit layer live vehicles, Barrie ON | Barrie Transit realtime data, published by the City of Barrie under a licence accepted by use of the data. The licence is revocable and requires no attribution. | Courtesy credit to the City of Barrie (the licence requires none, and its trademark clause is broad) |
 | **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. Speeds arrive in km/h rather than m/s and are converted by the proxy. Route ids are internal keys and are shown raw. | Attribution to SMTR / Prefeitura da Cidade do Rio de Janeiro under CC BY 4.0 |
+| **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. Speeds arrive in km/h rather than m/s and are converted by the proxy. Route ids are internal keys and are joined to the line names in SMTR’s published GTFS `routes.txt` (dados.mobilidade.rio/gtfs/schedule), under the same CC BY 4.0 terms. | Attribution to SMTR / Prefeitura da Cidade do Rio de Janeiro under CC BY 4.0 |
 | **Radio Browser**                                                     | Geolocated internet-radio station directory and station-level tags                                                                  | Public-domain directory data under PDDL 1.0; individual broadcaster stream terms apply                                                                                                                                                                                                                                                                | "Radio Browser" plus a link to the selected broadcaster                                                                                     |
 | **Re:Earth Terrain** (Mapterhorn)                                     | Terrain (keyless globe stacks — OSM etc. — + `/api/terrain/heights` ellipsoidal-height lookups)                                     | Terrain mesh: CC BY 4.0; geoid: EGM2008 (NGA, public domain)                                                                                                                                                                                                                                                                                          | "Terrain (keyless globe stacks): Re:Earth Terrain / Mapterhorn (CC BY 4.0) / EGM2008 (NGA)"                                                 |
 | **OpenSeaMap** (`tiles.openseamap.org`) | Sea Marks layer: raster overlay of buoys, lighthouses and ports (#10) | Chart tiles CC BY-SA 2.0; data ODbL 1.0 via OpenStreetMap | "Sea marks © OpenSeaMap contributors (CC BY-SA 2.0) · Data © OpenStreetMap contributors (ODbL)" |
diff --git a/changelog.d/1481-rio-transit.md b/changelog.d/1481-rio-transit.md
index 62b4ede04..b45b1b1fd 100644
--- a/changelog.d/1481-rio-transit.md
+++ b/changelog.d/1481-rio-transit.md
@@ -1,4 +1,6 @@
 - Add Rio de Janeiro to the Transit layer: municipal buses and the Mobi-Rio BRT
   from SMTR's keyless GTFS-Realtime feeds (CC BY 4.0), the layer's first Latin
   American region. A feed that publishes speed in km/h declares
-  `speedUnit: 'kmh'` and the proxy converts it to m/s (IMBrandao, #1481).
+  `speedUnit: 'kmh'` and the proxy converts it to m/s. Rio's internal route
+  keys are joined to SMTR's published GTFS `routes.txt`, so a card reads
+  "Route SN731" rather than "Route O0731AAN0A" (IMBrandao, #1481).
diff --git a/src/data/rioRouteNames.js b/src/data/rioRouteNames.js
new file mode 100644
index 000000000..68a7da7a8
--- /dev/null
+++ b/src/data/rioRouteNames.js
@@ -0,0 +1,515 @@
+// src/data/rioRouteNames.js
+/**
+ * Rio de Janeiro route ids to the line a rider would say.
+ *
+ * SMTR's realtime feeds publish internal route keys: the bus feed sends
+ * `O0868AAA0A` for line 868 and `O0731AAN0A` for SN731, and the BRT feed
+ * sends `20000501110` for line 50. The keys look decodable but are not:
+ * `O0014AAA0A` is LECD135, not 14, and nineteen of the plain-looking keys in
+ * the published table break the pattern. The join is the only correct route.
+ *
+ * Generated verbatim (`route_id` to `route_short_name`, 494 routes) from
+ * `routes.txt` in SMTR's static GTFS, https://dados.mobilidade.rio/gtfs/schedule
+ * (CC BY 4.0, the same publisher and terms as the realtime feeds; file dated
+ * 2026-06-10, feed valid 2024-01-01 to 2026-12-31). A 2026-11-04 snapshot of
+ * both realtime feeds, 282 bus and 21 BRT routes in service, found every one
+ * of its route ids here. An id missing from this table falls through
+ * unchanged, so a route added later degrades to its raw key rather than
+ * disappearing.
+ */
+export const RIO_ROUTE_NAMES = Object.freeze({
+  20000101130: '10',
+  20000111110: '11',
+  20000121130: '12',
+  20000131130: '13',
+  20000141130: '14',
+  20000151130: '15',
+  20000161130: '16',
+  20000171110: '17',
+  20000181130: '18',
+  20000191130: '19',
+  20000201130: '20',
+  20000221110: '22',
+  20000251130: '25',
+  20000281130: '28',
+  20000311140: '31',
+  20000351110: '35',
+  20000401130: '40',
+  20000411130: '41',
+  20000421110: '42',
+  20000431130: '43',
+  20000461130: '46',
+  20000501110: '50',
+  20000511110: '51',
+  20000521110: '52',
+  20000531130: '53',
+  20000601110: '60',
+  20000611130: '61',
+  20000671130: '67',
+  20000681130: '68',
+  20000701110: '70',
+  20000731130: '73',
+  20000801110: '80',
+  20000901110: '90',
+  '20000EXEC1110': 'ESP01',
+  E2110AAA0A: '2110',
+  E2111AAA0A: '2111',
+  E2112AAA0A: '2112',
+  E2114AAA0A: '2114',
+  E2303AAA0A: '2303',
+  E2305AAA0A: '2305',
+  E2307AAA0A: '2307',
+  E2308AAA0A: '2308',
+  E2309AAA0A: '2309',
+  E2310AAA0A: '2310',
+  E2334AAA0A: '2334',
+  E2335AAA0A: '2335',
+  E2336AAA0A: '2336',
+  E2337AAA0A: '2337',
+  E2338AAA0A: '2338',
+  E2339AAA0A: '2339',
+  E2342AAA0A: '2342',
+  E2343AAA0A: '2343',
+  E2344AAA0A: '2344',
+  E2345AAA0A: '2345',
+  E2381AAA0A: '2381',
+  E2383AAA0A: '2383',
+  E2613AAA0A: '2613',
+  E2614AAA0A: '2614',
+  E2802AAA0A: '2802',
+  E2803AAA0A: '2803',
+  E2804AAA0A: '2804',
+  O0006AAA0A: '006',
+  O0007AAA0A: '007',
+  O0007AAN0A: 'SN007',
+  O0010AAA0A: '010',
+  O0014AAA0A: 'LECD135',
+  O0100AAA0A: '100',
+  O0104AAA0A: '104',
+  O0104AAN0A: 'SN104',
+  O0107AAA0A: '107',
+  O0109AAA0A: 'LECD131',
+  O0111AAA0A: 'LECD134',
+  O0117AAA0A: '117',
+  O0133AAA0A: '133',
+  O0133AAN0A: 'SN133',
+  O0157AAA0A: 'LECD127',
+  O0160AAA0A: '160',
+  O0161AAA0A: '161',
+  O0162AAA0A: '162',
+  O0164AAA0A: 'LECD136',
+  O0165AAA0A: '165',
+  O0167AAA0A: '167',
+  O0169AAA0A: '169',
+  O0201AAA0A: '201',
+  O0202AAA0A: '202',
+  O0209AAA0A: '209',
+  O0209AAN0A: 'SN209',
+  O0210AAA0A: '210',
+  O0217AAA0A: '217',
+  O0220AAA0A: '220',
+  O0229AAA0A: '229',
+  O0232AAA0A: '232',
+  O0232AAN0A: 'SN232',
+  O0238AAA0A: '238',
+  O0238AAN0A: 'SN238',
+  O0239AAA0A: '239',
+  O0247AAA0A: '247',
+  O0249AAA0A: '249',
+  O0254AAA0A: '254',
+  O0265AAA0A: '265',
+  O0265AAN0A: 'SN265',
+  O0265AAP0A: 'SP265',
+  O0275AAA0A: '275',
+  O0277AAA0A: '277',
+  O0292AAA0A: '292',
+  O0292AAN0A: 'SN292',
+  O0296AAA0A: '296',
+  O0298AAA0A: '298',
+  O0298AAN0A: 'SN298',
+  O0300AAA0A: '300',
+  O0300AAR0A: 'SR300',
+  O0301AAA0A: '301',
+  O0302AAA0A: '302',
+  O0302AAN0A: 'SN302',
+  O0306AAA0A: '306',
+  O0311AAA0A: '311',
+  O0312AAA0A: '312',
+  O0312AAN0A: 'SN312',
+  O0313AAA0A: '313',
+  O0315AAA0A: '315',
+  O0319AAA0A: '319',
+  O0319AAN0A: 'SN319',
+  O0319AAV0A: 'SV319',
+  O0321AAA0A: '321',
+  O0323AAA0A: '323',
+  O0324AAA0A: '324',
+  O0324AAN0A: 'SN324',
+  O0324AAP0A: 'SP324',
+  O0325AAA0A: '325',
+  O0326AAA0A: '326',
+  O0326AAPBA: 'SPB326',
+  O0327AAA0A: '327',
+  O0328AAA0A: '328',
+  O0328AAN0A: 'SN328',
+  O0328AAP0A: 'SP328',
+  O0328AAR0A: 'SR328',
+  O0329AAA0A: '329',
+  O0329AAP0A: 'SP329',
+  O0335AAA0A: '335',
+  O0338AAA0A: '338',
+  O0341AAA0A: '341',
+  O0342AAA0A: '342',
+  O0342AAR0A: 'SR342',
+  O0343AAA0A: '343',
+  O0343AAP0A: 'SP343',
+  O0348AAA0A: '348',
+  O0349AAA0A: '349',
+  O0350AAA0A: '350',
+  O0352AAA0A: '352',
+  O0353AAA0A: '353',
+  O0353AAN0A: 'SN353',
+  O0355AAA0A: '355',
+  O0355AAN0A: 'SN355',
+  O0355AAR0A: 'SR355',
+  O0361AAA0A: '361',
+  O0362AAA0A: '362',
+  O0362AAR0A: 'SR362',
+  O0363AAA0A: '363',
+  O0363AAN0A: 'SN363',
+  O0363AAV0A: 'SV363',
+  O0368AAA0A: '368',
+  O0368AAN0A: 'SN368',
+  O0369AAA0A: '369',
+  O0371AAA0A: '371',
+  O0378AAA0A: '378',
+  O0378AAR0A: 'SR378',
+  O0380AAA0A: '380',
+  O0383AAA0A: '383',
+  O0383AAN0A: 'SN383',
+  O0384AAA0A: '384',
+  O0384AAR0A: 'SR384',
+  O0385AAA0A: '385',
+  O0386AAA0A: '386',
+  O0386AAR0A: 'SR386',
+  O0388AAA0A: '388',
+  O0388AAN0A: 'SN388',
+  O0388AAR0A: 'SR388',
+  O0389AAP0A: 'SP389',
+  O0390AAA0A: '390',
+  O0391AAV0A: 'SV391',
+  O0393AAA0A: '393',
+  O0393AAN0A: 'SN393',
+  O0393AAR0A: 'SR393',
+  O0397AAA0A: '397',
+  O0397AAN0A: 'SN397',
+  O0397AAR0A: 'SR397',
+  O0399AAA0A: '399',
+  O0399AAN0A: 'SN399',
+  O0399AAR0A: 'SR399',
+  O0404AAP0A: 'SP404',
+  O0409AAA0A: '409',
+  O0410AAA0A: '410',
+  O0410AAN0A: 'LECD139',
+  O0415AAA0A: '415',
+  O0415AAN0A: 'SN415',
+  O0416AAA0A: '416',
+  O0422AAA0A: '422',
+  O0422AAN0A: 'SN422',
+  O0426AAA0A: '426',
+  O0433AAA0A: 'LECD150',
+  O0435AAA0A: 'LECD151',
+  O0448AAA0A: '448',
+  O0455AAA0A: '455',
+  O0456AAA0A: 'LECD132',
+  O0457AAA0A: '457',
+  O0457AAN0A: 'SN457',
+  O0461AAA0A: '461',
+  O0472AAA0A: '472',
+  O0473AAA0A: '473',
+  O0474AAA0A: '474',
+  O0474AAN0A: 'SN474',
+  O0474AAV0A: 'SV474',
+  O0475AAA0A: 'LECD133',
+  O0476AAA0A: '476',
+  O0483AAA0A: '483',
+  O0483AAN0A: 'SN483',
+  O0483AAPAA: 'SPA483',
+  O0483AAPBA: 'SPB483',
+  O0483AAV0A: 'SV483',
+  O0484AAA0A: '484',
+  O0485AAA0A: '485',
+  O0485AAP0A: 'SP485',
+  O0486AAA0A: '486',
+  O0492AAA0A: '492',
+  O0497AAA0A: '497',
+  O0497AAN0A: 'SN497',
+  O0498AAA0A: '498',
+  O0507AAA0A: '507',
+  O0513AAA0A: '513',
+  O0518AAA0A: '518',
+  O0519AAA0A: '519',
+  O0536AAA0A: 'LECD138',
+  O0539AAA0A: '539',
+  O0550AAA0A: '550',
+  O0550AAN0A: 'SN550',
+  O0550AAPAA: 'SPA550',
+  O0550AAPBA: 'SPB550',
+  O0552AAA0A: '552',
+  O0552AAN0A: 'LECD149',
+  O0553AAA0A: '553',
+  O0554AAA0A: '554',
+  O0554AAN0A: 'SN554',
+  O0555AAA0A: '555',
+  O0557AAA0A: '557',
+  O0565AAA0A: '565',
+  O0565AAN0A: 'SN565',
+  O0583AAA0A: '583',
+  O0584AAA0A: '584',
+  O0585AAA0A: '585',
+  O0600AAA0A: '600',
+  O0600AAN0A: 'SN600',
+  O0601AAA0A: '601',
+  O0603AAA0A: '603',
+  O0606AAA0A: '606',
+  O0606AAV0A: 'SV606',
+  O0607AAA0A: '607',
+  O0608AAA0A: '608',
+  O0610AAA0A: '610',
+  O0611AAA0A: '611',
+  O0613AAA0A: '613',
+  O0613AAPAA: 'SPA613',
+  O0614AAA0A: '614',
+  O0616AAA0A: '616',
+  O0621AAA0A: '621',
+  O0622AAA0A: '622',
+  O0623AAA0A: '623',
+  O0624AAA0A: '624',
+  O0624AAN0A: 'SN624',
+  O0624AAV0A: 'SV624',
+  O0625AAA0A: '625',
+  O0626AAA0A: '626',
+  O0627AAA0A: '627',
+  O0628AAA0A: '628',
+  O0629AAA0A: '629',
+  O0629AAN0A: 'SN629',
+  O0630AAA0A: '630',
+  O0634AAA0A: '634',
+  O0635AAA0A: '635',
+  O0635AAP0A: 'SP635',
+  O0636AAA0A: '636',
+  O0636AAN0A: 'SN636',
+  O0638AAA0A: '638',
+  O0639AAA0A: '639',
+  O0639AAN0A: 'SN639',
+  O0645AAA0A: '645',
+  O0649AAA0A: 'LECD126',
+  O0650AAA0A: '650',
+  O0651AAA0A: '651',
+  O0652AAA0A: '652',
+  O0653AAA0A: '653',
+  O0663AAA0A: '663',
+  O0665AAA0A: '665',
+  O0665AAVAA: 'LECD147',
+  O0665AAVBA: 'SVB665',
+  O0669AAA0A: '669',
+  O0669AAV0A: 'SV669',
+  O0678AAA0A: '678',
+  O0679AAA0A: '679',
+  O0685AAA0A: 'LECD140',
+  O0685AAVAA: 'LECD148',
+  O0685AAVBA: 'LECD141',
+  O0687AAA0A: '687',
+  O0688AAA0A: '688',
+  O0691AAA0A: '691',
+  O0692AAA0A: '692',
+  O0692AAV0A: 'SV692',
+  O0693AAA0A: '693',
+  O0696AAA0A: '696',
+  O0696AAN0A: 'SN696',
+  O0711AAA0A: '711',
+  O0712AAA0A: '712',
+  O0721AAA0A: '721',
+  O0731AAA0A: '731',
+  O0731AAN0A: 'SN731',
+  O0737AAA0A: '737',
+  O0741AAA0A: '741',
+  O0743AAA0A: '743',
+  O0745AAA0A: '745',
+  O0746AAA0A: '746',
+  O0753AAA0A: '753',
+  O0754AAA0A: '754',
+  O0756AAA0A: '756',
+  O0757AAA0A: '757',
+  O0759AAA0A: '759',
+  O0759AAP0A: 'SP759',
+  O0764AAA0A: '764',
+  O0765AAA0A: '765',
+  O0766AAA0A: '766',
+  O0766AAP0A: 'SP766',
+  O0770AAA0A: '770',
+  O0771AAA0A: '771',
+  O0774AAA0A: '774',
+  O0774AAV0A: 'LECD142',
+  O0775AAA0A: '775',
+  O0777AAV0A: 'SV777',
+  O0778AAA0A: '778',
+  O0779AAA0A: '779',
+  O0779AAN0A: 'SN779',
+  O0780AAA0A: '780',
+  O0783AAA0A: '783',
+  O0785AAA0A: '785',
+  O0786AAA0A: '786',
+  O0788AAA0A: '788',
+  O0790AAA0A: '790',
+  O0790AAN0A: 'SN790',
+  O0790AAV0A: 'SV790',
+  O0791AAA0A: '791',
+  O0793AAA0A: '793',
+  O0794AAA0A: '794',
+  O0794AAN0A: 'SN794',
+  O0795AAP0A: 'SP795',
+  O0796AAA0A: '796',
+  O0798AAA0A: '798',
+  O0799AAA0A: '799',
+  O0801AAA0A: '801',
+  O0801AAP0A: 'SP801',
+  O0802AAA0A: '802',
+  O0803AAA0A: '803',
+  O0803AAN0A: 'SN803',
+  O0803AAP0A: 'SP803',
+  O0804AAA0A: '804',
+  O0805AAA0A: '805',
+  O0805AAN0A: 'SN805',
+  O0805AAP0A: 'SP805',
+  O0807AAA0A: '807',
+  O0808AAA0A: '808',
+  O0809AAA0A: '809',
+  O0810AAA0A: '810',
+  O0810AAN0A: 'SN810',
+  O0810AAP0A: 'SP810',
+  O0812AAA0A: '812',
+  O0817AAA0A: '817',
+  O0819AAA0A: '819',
+  O0820AAA0A: '820',
+  O0821AAA0A: '821',
+  O0821AAN0A: 'SN821',
+  O0822AAA0A: '822',
+  O0825AAA0A: '825',
+  O0825AAN0A: 'SN825',
+  O0826AAA0A: '826',
+  O0829AAA0A: '829',
+  O0830AAA0A: '830',
+  O0831AAA0A: '831',
+  O0831AAV0A: 'SV831',
+  O0833AAA0A: '833',
+  O0834AAA0A: '834',
+  O0835AAA0A: '835',
+  O0836AAA0A: '836',
+  O0837AAA0A: '837',
+  O0838AAA0A: '838',
+  O0840AAA0A: '840',
+  O0840AAN0A: 'SN840',
+  O0841AAA0A: '841',
+  O0842AAA0A: '842',
+  O0843AAA0A: '843',
+  O0844AAA0A: '844',
+  O0845AAA0A: '845',
+  O0846AAA0A: '846',
+  O0846AAN0A: 'SN846',
+  O0847AAA0A: '847',
+  O0848AAA0A: '848',
+  O0848AAN0A: 'SN848',
+  O0849AAA0A: '849',
+  O0850AAA0A: '850',
+  O0851AAA0A: '851',
+  O0852AAA0A: '852',
+  O0853AAA0A: '853',
+  O0853AAN0A: 'SN853',
+  O0853AAV0A: 'SV853',
+  O0854AAAAA: '854',
+  O0855AAA0A: '855',
+  O0856AAA0A: '856',
+  O0857AAA0A: '857',
+  O0857AAN0A: 'SN857',
+  O0859AAA0A: '859',
+  O0861AAA0A: '861',
+  O0861AAN0A: 'SN861',
+  O0862AAA0A: '862',
+  O0863AAA0A: '863',
+  O0863AAV0A: 'SV863',
+  O0864AAA0A: '864',
+  O0864AAP0A: 'SP864',
+  O0865AAA0A: '865',
+  O0866AAA0A: '866',
+  O0866AAV0A: 'SV866',
+  O0867AAA0A: '867',
+  O0867AAN0A: 'SN867',
+  O0868AAA0A: '868',
+  O0869AAA0A: '869',
+  O0870AAA0A: '870',
+  O0871AAA0A: '871',
+  O0872AAA0A: '872',
+  O0878AAA0A: '878',
+  O0878AAN0A: 'SN878',
+  O0878AAV0A: 'SV878',
+  O0880AAA0A: '880',
+  O0880AAN0A: 'SN880',
+  O0881AAA0A: '881',
+  O0883AAA0A: '883',
+  O0884AAA0A: '884',
+  O0884AAN0A: 'SN884',
+  O0885AAA0A: '885',
+  O0885AAN0A: 'SN885',
+  O0892AAA0A: '892',
+  O0893AAA0A: '893',
+  O0893AAN0A: 'SN893',
+  O0894AAA0A: '894',
+  O0895AAA0A: '895',
+  O0895AAN0A: 'SN895',
+  O0897AAA0A: '897',
+  O0897AAN0A: 'SN897',
+  O0898AAA0A: '898',
+  O0898AAN0A: 'SN898',
+  O0899AAA0A: '899',
+  O0899AAV0A: 'SV899',
+  O0900AAA0A: '900',
+  O0901AAA0A: '901',
+  O0901AAVBA: 'SVB901',
+  O0905AAA0A: '905',
+  O0906AAA0A: '906',
+  O0908AAA0A: '908',
+  O0908AAN0A: 'SN908',
+  O0908AAV0A: 'SV908',
+  O0910AAA0A: '910',
+  O0913AAA0A: '913',
+  O0915AAA0A: '915',
+  O0917AAA0A: '917',
+  O0917AAV0A: 'SV917',
+  O0918AAA0A: '918',
+  O0918AAP0A: 'SP918',
+  O0919AAA0A: '919',
+  O0919AAN0A: 'SN919',
+  O0920AAA0A: '920',
+  O0921AAA0A: '921',
+  O0921AAV0A: 'SV921',
+  O0922AAA0A: '922',
+  O0922AAV0A: 'SV922',
+  O0925AAA0A: '925',
+  O0926AAA0A: '926',
+  O0928AAA0A: '928',
+  O0932AAA0A: '932',
+  O0940AAA0A: '940',
+  O0944AAA0A: 'LECD143',
+  O0946AAA0A: '946',
+  O0950AAA0A: 'LECD144',
+  O0951AAA0A: 'LECD145',
+  O0954AAA0A: '954',
+  O0954AAN0A: 'SN954',
+  O0959AAA0A: 'LECD146',
+  O0961AAA0A: '961',
+  O0975AAA0A: '975',
+  O0979AAA0A: '979',
+  O0987AAA0A: '987',
+  O0990AAA0A: '990',
+});
diff --git a/src/data/transitFeeds.js b/src/data/transitFeeds.js
index e871a2e89..d7993a954 100644
--- a/src/data/transitFeeds.js
+++ b/src/data/transitFeeds.js
@@ -1,4 +1,5 @@
 import { greatCircleKm } from '../geoDistance.js';
+import { RIO_ROUTE_NAMES } from './rioRouteNames.js';
 
 /**
  * @module transitFeeds
@@ -376,6 +377,18 @@ function burlingtonRouteLabel(routeId) {
   return BURLINGTON_ROUTE_NAMES[routeId] || routeId;
 }
 
+/**
+ * Rio route key to the line a rider would say, for both SMTR feeds: one
+ * published `routes.txt` covers the buses and the BRT (see rioRouteNames.js).
+ * @param {string|null} routeId
+ * @returns {string|null}
+ */
+function rioRouteLabel(routeId) {
+  return Object.hasOwn(RIO_ROUTE_NAMES, routeId)
+    ? RIO_ROUTE_NAMES[routeId]
+    : routeId;
+}
+
 /**
  * Registry of feeds. Order is presentation order in the stats/credit text.
  * `loadRadiusKm` is the distance from `center` inside which the feed is polled.
@@ -752,10 +765,11 @@ export const TRANSIT_FEED_REGISTRY = Object.freeze([
     terms: Object.freeze({
       quote:
         'This work is licensed under a Creative Commons Attribution 4.0 International License',
-      note: 'The data.rio catalog page labels the feed [beta] and states a gateway limit of 5 requests a second and 60 a minute behind a 10-second cache, which the 15-second proxy TTL stays inside. It is the named replacement for the JSON GPS endpoints SMTR deprecated on 2026-10-07 and says it will switch off by 2026-11-30. SMTR relays the concessionaires’ ITS data and repairs trips with its own matching; the page places accuracy with the suppliers. Speeds arrive in km/h, not m/s (a 2026-10-29 snapshot peaked at 89), hence `speedUnit`. Route ids are internal keys: `O0313AAA0A` carried service 313 in the same day’s JSON feed. They are shown raw until a published table is joined.',
+      note: 'The data.rio catalog page labels the feed [beta] and states a gateway limit of 5 requests a second and 60 a minute behind a 10-second cache, which the 15-second proxy TTL stays inside. It is the named replacement for the JSON GPS endpoints SMTR deprecated on 2026-10-07 and says it will switch off by 2026-11-30. SMTR relays the concessionaires’ ITS data and repairs trips with its own matching; the page places accuracy with the suppliers. Speeds arrive in km/h, not m/s (a 2026-10-29 snapshot peaked at 89), hence `speedUnit`. Route ids are internal keys (`O0731AAN0A` is line SN731) and are joined to the line names in SMTR’s published GTFS `routes.txt`, under the same CC BY 4.0 terms.',
     }),
     defaultMode: 'bus',
     speedUnit: 'kmh',
+    routeLabel: rioRouteLabel,
   }),
   Object.freeze({
     id: 'smtr-rio-brt',
@@ -774,10 +788,11 @@ export const TRANSIT_FEED_REGISTRY = Object.freeze([
     terms: Object.freeze({
       quote:
         'This work is licensed under a Creative Commons Attribution 4.0 International License',
-      note: 'Same catalog terms, [beta] label and gateway limits as the bus feed. The fleet is operated by Mobi-Rio and tracked by SONDA, whose data SMTR relays. Speeds are km/h here too (peak 62 in the same snapshot). Route ids are opaque (`20000461130`) and are shown raw.',
+      note: 'Same catalog terms, [beta] label and gateway limits as the bus feed. The fleet is operated by Mobi-Rio and tracked by SONDA, whose data SMTR relays. Speeds are km/h here too (peak 62 in the same snapshot). Route ids are opaque (`20000501110` is line 50) and are joined to the same `routes.txt` as the buses.',
     }),
     defaultMode: 'bus',
     speedUnit: 'kmh',
+    routeLabel: rioRouteLabel,
   }),
 ]);
 
diff --git a/src/data/transitFeeds.test.mjs b/src/data/transitFeeds.test.mjs
index 51903b7db..8333207d5 100644
--- a/src/data/transitFeeds.test.mjs
+++ b/src/data/transitFeeds.test.mjs
@@ -15,6 +15,7 @@ import {
   transitModeResolved,
   transitRouteLabel,
 } from './transitFeeds.js';
+import { RIO_ROUTE_NAMES } from './rioRouteNames.js';
 
 test('every registered feed is keyless, https, licensed, and uniquely identified', () => {
   const ids = new Set();
@@ -504,6 +505,36 @@ test('Rio buses and BRT cover the city from Centro to Santa Cruz, and not São P
   );
 });
 
+test('Rio route keys read as the line on the front of the bus', () => {
+  // SMTR publishes internal keys. Plain keys carry the number (`O0868AAA0A`
+  // is 868), variants carry a prefix (`O0731AAN0A` is SN731), and some plain
+  // keys are traps: `O0014AAA0A` is LECD135, so the table is joined, not parsed.
+  const buses = getTransitFeed('smtr-rio-onibus');
+  assert.equal(transitRouteLabel(buses, 'O0868AAA0A'), '868');
+  assert.equal(transitRouteLabel(buses, 'O0731AAN0A'), 'SN731');
+  assert.equal(transitRouteLabel(buses, 'O0759AAP0A'), 'SP759');
+  assert.equal(transitRouteLabel(buses, 'O0014AAA0A'), 'LECD135');
+  assert.equal(transitRouteLabel(buses, 'E2303AAA0A'), '2303');
+  const brt = getTransitFeed('smtr-rio-brt');
+  assert.equal(transitRouteLabel(brt, '20000501110'), '50');
+  assert.equal(transitRouteLabel(brt, '20000EXEC1110'), 'ESP01');
+  // A route added after the table was built keeps its raw key, never a blank
+  // or a name borrowed from the prototype chain.
+  assert.equal(transitRouteLabel(buses, 'O9999AAA0A'), 'O9999AAA0A');
+  assert.equal(transitRouteLabel(buses, 'constructor'), 'constructor');
+  assert.equal(transitRouteLabel(brt, null), null);
+});
+
+test('the Rio route table is a clean join of published keys to names', () => {
+  const entries = Object.entries(RIO_ROUTE_NAMES);
+  assert.ok(entries.length > 400, 'the whole published table is carried');
+  for (const [id, name] of entries) {
+    assert.match(id, /^(?:[OE]\d{4}[A-Z0-9]{5}|2\d{4}[A-Z0-9]{4,8})$/, id);
+    assert.ok(name && name === name.trim(), `${id} has a name`);
+    assert.notEqual(name, id, `${id} is translated`);
+  }
+});
+
 test('Rio feeds are CC BY 4.0, live, and declare the km/h speeds they publish', () => {
   for (const id of ['smtr-rio-onibus', 'smtr-rio-brt']) {
     const feed = getTransitFeed(id);

From 1c59105a80defce5a5e2987b5654505840b55227 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Thu, 5 Nov 2026 11:36:29 +0530
Subject: [PATCH 34/71] Judge tilts by camera pitch and follow a newer flight
 at once

- A tilt's angle, limits and "unchanged" check use the camera's own
  pitch. At regional range the pivot pitch is up to about 8 degrees
  shallower, so "tilt to 5 degrees" from 900 km ended at -12.9 degrees.
  The swing now solves for the pivot pitch that gives the camera angle.
- A zoom out during a pivoting tilt stops at the 1,000 km pivot limit
  instead of the orbit's 5,000 km, and a zoom in that reaches the
  clearance is applied before the pivot ends.
- An angle the camera already holds still takes navigation, so it stops
  a running motion and releases the follow camera.
- A motion queued behind a fly-to moves to a newer fly-to as soon as it
  begins, so a stalled lookup no longer holds it past a flight that
  landed. Wait listeners are removed when a wait ends, and a lookup that
  found nothing points straight at the flight that moved.
- A fly-to that stops a running motion names it (stoppedMotion).
- A tilt left or right is refused, and the pitchDeg description says
  steps use direction.
---
 docs/CURRENT-STATE.md                       |   2 +-
 server/providers/openai/toolDescriptions.js |   2 +-
 src/cameraTilt.test.mjs                     | 115 ++++++++++++---
 src/cameraVerbs.js                          | 154 +++++++++++---------
 src/voice/actionSchemas.test.mjs            |   4 +-
 src/voice/gevActions.js                     | 113 +++++++++-----
 src/voice/gevActions.test.mjs               |  44 ++++++
 src/voice/pointAndAsk.test.mjs              |   4 +-
 8 files changed, 310 insertions(+), 128 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 520085495..e135ec175 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5520,7 +5520,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor or the 5,000 km cap) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (following a later fly-to in the same reply that cancels it), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered. Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/server/providers/openai/toolDescriptions.js b/server/providers/openai/toolDescriptions.js
index ee90434ee..33d1ea68a 100644
--- a/server/providers/openai/toolDescriptions.js
+++ b/server/providers/openai/toolDescriptions.js
@@ -533,7 +533,7 @@ export const ACTION_DESCRIPTIONS = {
         },
         pitchDeg: {
           description:
-            'Absolute pitch, not a step: -45 oblique (default), -89 top-down.',
+            'Absolute; steps use direction. -45 oblique (default), -89 top-down.',
           $position: 1,
         },
       },
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index d372d0746..a82b2ce37 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -340,16 +340,16 @@ test('pitchDeg with a direction that agrees still tilts', (t) => {
   assert.ok(Math.abs(pitchDeg(h.camera) - -80) < 0.5);
 });
 
-test('the pitchDeg and direction check uses the pitch the swing starts from', (t) => {
-  // At regional range the Earth curves away: the pivot pitch is a degree or
-  // two shallower than the camera's (-30°), so -29° is still down from it.
+test('the pitchDeg and direction check uses the camera pitch', (t) => {
+  // At regional range the Earth curves away and the pivot pitch is a degree
+  // or two shallower than the camera's (-30°); -29° is still up from it.
   harness(t, { height: 150000, pitch: -30 });
-  const up = moveCamera({ motion: 'tilt', direction: 'up', pitchDeg: -29 });
-  assert.equal(up.ok, false);
-  assert.match(up.error, /tilts down, not up/);
   const down = moveCamera({ motion: 'tilt', direction: 'down', pitchDeg: -29 });
-  assert.equal(down.ok, true);
-  assert.equal(down.direction, 'down');
+  assert.equal(down.ok, false);
+  assert.match(down.error, /tilts up, not down/);
+  const up = moveCamera({ motion: 'tilt', direction: 'up', pitchDeg: -29 });
+  assert.equal(up.ok, true);
+  assert.equal(up.direction, 'up');
 });
 
 test('after a zoom in, a pivoting tilt never lowers the camera further', (t) => {
@@ -414,6 +414,13 @@ test('a zoom in during a pivot tilt stops at the clearance', (t) => {
   assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: true });
   // At -40° the floor is 150 / sin 40° ≈ 233 m, which the first zoom reached.
   assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: false });
+  // The camera must take that range, not just report it.
+  h.tick();
+  const floor = 150 / Math.sin(radians(40));
+  assert.ok(
+    Math.abs(pivotRange(h) - floor) < floor * 0.02,
+    `range ${pivotRange(h)} m, wanted about ${floor} m`,
+  );
   for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
     h.tick();
     assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
@@ -453,17 +460,39 @@ test('from globe range a tilt happens in place', (t) => {
   assert.ok(Cesium.Cartesian3.distance(h.camera.positionWC, before) < 1e-3);
 });
 
-test('a regional tilt-up nudge at the pivot limit refuses honestly', (t) => {
-  // 20 km up at -7°, the pivot 186 km out sits at -5.3°: already at the limit.
-  harness(t, { height: 20000, pitch: -7 });
-  const result = moveCamera({ motion: 'tilt', direction: 'up' });
-  assert.equal(result.ok, false);
-  assert.match(result.error, /upper tilt limit/);
-  assert.equal(getActiveCameraMotion(), null);
+for (const height of [100_000, 400_000, 900_000])
+  test(`from ${height / 1000} km a tilt to -5° ends with the camera at -5°`, (t) => {
+    // The pivot pitch is shallower than the camera's by up to 8° at this
+    // range; the camera reached only -5.9° to -12.9° when the swing stopped
+    // at a pivot pitch of -5°.
+    const h = harness(t, { height });
+    const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
+    assert.equal(result.pitchDeg, -5);
+    h.finish();
+    assert.ok(
+      Math.abs(pitchDeg(h.camera) - -5) < 0.5,
+      `pitch ${pitchDeg(h.camera)}`,
+    );
+    assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
+    const nudge = moveCamera({ motion: 'tilt', direction: 'up' });
+    assert.equal(nudge.ok, false);
+    assert.match(nudge.error, /upper tilt limit/);
+  });
+
+test('a regional tilt-up nudge goes to the camera horizon limit', (t) => {
+  // 20 km up at -7°: the pivot 186 km out sits at -5.3°, but the camera can
+  // still tilt up 2°.
+  const h = harness(t, { height: 20000, pitch: -7 });
+  assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -5) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
 });
 
-test('a voice tilt from a tracked view judges its limit from the pivot it will use', (t) => {
-  const h = harness(t, { height: 20000, pitch: -7 });
+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' };
   // Voice releases the follow camera before the motion starts.
   const release = (start) => {
@@ -474,3 +503,55 @@ test('a voice tilt from a tracked view judges its limit from the pivot it will u
   assert.equal(result.ok, false);
   assert.match(result.error, /upper tilt limit/);
 });
+
+test('a zoom out during a pivoting tilt stops at the pivot range limit', (t) => {
+  // 900 km top-down, "tilt to 10°", then "zoom out a lot" twice: capped at
+  // the orbit's 5,000 km, the swing reached 2,386 km up at a real -44°.
+  const h = harness(t, { height: 900_000 });
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -10 }).ok, true);
+  h.tick();
+  assert.deepEqual(adjustOrbitRange(2.4), { kind: 'tilt', changed: true });
+  assert.deepEqual(adjustOrbitRange(2.4), { kind: 'tilt', changed: false });
+  let farthest = 0;
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    farthest = Math.max(farthest, pivotRange(h));
+  }
+  assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  assert.ok(farthest <= 1_000_001, `swung ${farthest} m from the pivot`);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -10) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+});
+
+test('an unchanged angle still stops a running motion through navigation', (t) => {
+  const h = harness(t);
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  tickUntil(h, () => pitchDeg(h.camera) >= -45.3);
+  let handoffs = 0;
+  const navigate = (start) => {
+    handoffs += 1;
+    return start();
+  };
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -45 }, navigate);
+  assert.equal(result.ok, true);
+  assert.equal(result.unchanged, true);
+  assert.equal(handoffs, 1, 'the request must take navigation');
+  assert.equal(getActiveCameraMotion(), null, 'the tilt must stop');
+  const held = pitchDeg(h.camera);
+  for (let i = 0; i < 30; i += 1) h.tick();
+  assert.equal(pitchDeg(h.camera), held);
+});
+
+for (const direction of ['left', 'right'])
+  test(`a tilt ${direction} is refused`, (t) => {
+    harness(t, { pitch: -45 });
+    const result = moveCamera({ motion: 'tilt', direction });
+    assert.equal(result.ok, false);
+    assert.match(result.error, /tilt needs up or down/);
+    const angled = moveCamera({ motion: 'tilt', direction, pitchDeg: -30 });
+    assert.equal(angled.ok, false);
+    assert.match(angled.error, /pitchDeg alone/);
+    assert.equal(getActiveCameraMotion(), null);
+  });
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index c1e5c5d1a..70b83eff5 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -1267,62 +1267,63 @@ function onTick() {
 /**
  * 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
- * down in place. Pitch is clamped to [-89°, -5°] only in the direction of
- * travel: a top-down view sits at -90°, below the limit, and must still be
- * able to tilt up out of it. A pivot swing toward the horizon lowers the
- * camera, so it stops at TILT_MIN_CLEARANCE_M and the rest tilts in place.
+ * down in place. Every angle and limit is the camera's own pitch, which at
+ * regional range is several degrees steeper than the pivot's (the Earth
+ * curves away), so the swing solves for the pivot pitch that gives it. Pitch
+ * is clamped to [-89°, -5°] only in the direction of travel: a top-down view
+ * sits at -90°, below the limit, and must still be able to tilt up out of it.
+ * A pivot swing toward the horizon lowers the camera, so it stops at
+ * TILT_MIN_CLEARANCE_M and the rest tilts in place.
  */
 function tickTilt(cam, m, scale, dt) {
-  let step;
-  if (m.mode === 'once') {
-    step = m.tiltRad * (scale - (m.lastScale || 0));
-    m.lastScale = scale;
-  } else {
-    step =
-      Cesium.Math.toRadians(TILT_DEG_S[m.speed]) *
-      dt *
-      (m.direction === 'up' ? 1 : -1);
-  }
+  const from = cam.pitch;
+  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);
+  const up = want > from;
+  const limited = up
+    ? Math.min(want, Math.max(from, PITCH_MAX))
+    : Math.max(want, Math.min(from, PITCH_MIN));
   if (m.hpr) {
-    const from = m.hpr.pitch;
-    const next = from + step;
-    const limited =
-      step > 0
-        ? Math.min(next, Math.max(from, tiltPivotPitchMax(m.hpr.range)))
-        : Math.max(next, Math.min(from, PITCH_MIN));
-    m.hpr.pitch = limited;
+    // 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);
+    // Up toward the horizon the swing lowers the camera: hold the clearance.
+    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) {
+      const pitch = Math.min(
+        cap,
+        Math.max(-Cesium.Math.PI_OVER_TWO, m.hpr.pitch + limited - cam.pitch),
+      );
+      if (pitch === m.hpr.pitch) break;
+      m.hpr.pitch = pitch;
+      cam.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 (limited === next) return;
-    if (step < 0 || limited >= PITCH_MAX) {
-      interruptCameraMotion('tilt-clamp');
-      return;
+    if (up && m.hpr.pitch >= cap && cam.pitch < limited - 1e-6) {
+      // Down to its clearance: let go of the pivot and tilt the rest in
+      // place, which keeps the height.
+      if (_active === m) clearLookAt();
+      m.hpr = null;
+      m.target = null;
     }
-    // Down to its clearance: let go of the pivot and tilt the rest in place,
-    // which keeps the height.
-    if (_active === m) clearLookAt();
-    m.hpr = null;
-    m.target = null;
-    step = next - limited;
   }
-  const from = cam.pitch;
-  const next = from + step;
-  const limited =
-    step > 0
-      ? Math.min(next, Math.max(from, PITCH_MAX))
-      : Math.max(next, Math.min(from, PITCH_MIN));
-  cam.lookUp(limited - from);
-  if (limited !== next) interruptCameraMotion('tilt-clamp');
+  if (!m.hpr) cam.lookUp(limited - cam.pitch);
+  if (m.mode !== 'once' && limited !== want)
+    interruptCameraMotion('tilt-clamp');
 }
 
 /** Shallowest pivot pitch that keeps the clearance at this range. */
 function tiltPivotPitchMax(range) {
-  return Math.min(
-    PITCH_MAX,
-    -Math.asin(Math.min(1, TILT_MIN_CLEARANCE_M / range)),
-  );
+  return -Math.asin(Math.min(1, TILT_MIN_CLEARANCE_M / range));
 }
 
 /**
@@ -1331,12 +1332,11 @@ function tiltPivotPitchMax(range) {
  * range, or while an entity is tracked (the follow camera owns that frame;
  * voice releases it before moving, so a voice tilt still pivots).
  */
-function tiltStartFrame(cam, { releasesTracking = false } = {}) {
-  const tracked = Boolean(_viewer.trackedEntity) && !releasesTracking;
-  const target = tracked ? null : _getTarget?.(_viewer);
+function tiltStartFrame(cam) {
+  const target = _viewer.trackedEntity ? null : _getTarget?.(_viewer);
   let pivot = target ? tiltPivot(cam, target) : null;
   if (pivot && pivot.range > TILT_PIVOT_MAX_RANGE_M) pivot = null;
-  return { target, pivot, from: pivot ? pivot.pitch : cam.pitch };
+  return { target, pivot, from: cam.pitch };
 }
 
 /** Ground pivot for a tilt: heading, pitch and range in the target's own frame. */
@@ -1604,7 +1604,14 @@ export function moveCameraArgsError(args = {}) {
     return {
       ok: false,
       action: 'move_camera',
-      error: `${motion} needs a direction (left/right${motion !== 'rotate' ? '/up/down' : ''}).`,
+      error: `${motion} needs a direction (${motion === 'tilt' ? 'up/down' : motion === 'rotate' ? 'left/right' : 'left/right/up/down'}).`,
+    };
+  }
+  if (motion === 'tilt' && (direction === 'left' || direction === 'right')) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: 'tilt needs up or down, or pitchDeg alone for an angle.',
     };
   }
   if (motion === 'rotate' && !['left', 'right'].includes(direction)) {
@@ -1664,13 +1671,10 @@ export function moveCamera(args = {}, runNavigation = null) {
   if (argsError) return argsError;
   const tiltToPitch =
     motion === 'tilt' ? requestedTiltPitch(args, direction) : null;
-  // A managed (voice) navigation releases the follow camera before start(),
-  // so checks made now must judge from the frame start() will see.
-  const releasesTracking = typeof runNavigation === 'function';
   if (motion === 'tilt' && tiltToPitch !== null) {
-    // Judge from the pitch the motion will start at: the pivot's, which at
-    // regional range is a degree or two shallower than the camera's.
-    const { from } = tiltStartFrame(_viewer.camera, { releasesTracking });
+    // 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;
     // -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;
@@ -1678,15 +1682,21 @@ export function moveCamera(args = {}, runNavigation = null) {
       atTopDown ||
       Math.abs(tiltToPitch - from) < Cesium.Math.toRadians(0.5)
     ) {
-      return {
-        ok: true,
-        action: 'move_camera',
-        motion,
-        pitchDeg: Math.round(
-          Cesium.Math.toDegrees(atTopDown ? from : tiltToPitch),
-        ),
-        unchanged: true,
+      // Still a camera request: it stops a running motion and releases the
+      // follow camera, as a tilt that moves would.
+      const hold = () => {
+        interruptCameraMotion('replaced');
+        return {
+          ok: true,
+          action: 'move_camera',
+          motion,
+          pitchDeg: Math.round(
+            Cesium.Math.toDegrees(atTopDown ? from : tiltToPitch),
+          ),
+          unchanged: true,
+        };
       };
+      return typeof runNavigation === 'function' ? runNavigation(hold) : hold();
     }
     // pitchDeg is an absolute angle, not a step: "tilt down 10 degrees" sent
     // as {direction:'down', pitchDeg:10} would tilt up from -45°.
@@ -1703,8 +1713,7 @@ export function moveCamera(args = {}, runNavigation = null) {
   } 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).
-    // The clamp reads the pitch the motion starts from.
-    const pitch = tiltStartFrame(_viewer.camera, { releasesTracking }).from;
+    const pitch = _viewer.camera.pitch;
     if (direction === 'up' && pitch >= PITCH_MAX - Cesium.Math.toRadians(0.5)) {
       return {
         ok: false,
@@ -1821,17 +1830,23 @@ export function moveCamera(args = {}, runNavigation = null) {
         state.target = target;
         state.hpr = pivot;
       }
+      state.startPitch = from;
       if (tiltToPitch !== null) {
         state.mode = 'once';
         state.direction = tiltToPitch > from ? 'up' : 'down';
-        state.tiltRad = tiltToPitch - from;
+        state.goalPitch = tiltToPitch;
         state.durationS = Math.max(
           ONCE.durationS,
-          Math.abs(Cesium.Math.toDegrees(state.tiltRad)) / TILT_TO_DEG_S,
+          Math.abs(Cesium.Math.toDegrees(tiltToPitch - from)) / TILT_TO_DEG_S,
         );
       } else {
-        state.tiltRad =
+        // A nudge stops at the limit it travels toward.
+        const step =
           Cesium.Math.toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1);
+        state.goalPitch =
+          step > 0
+            ? Math.min(from + step, Math.max(from, PITCH_MAX))
+            : Math.max(from + step, Math.min(from, PITCH_MIN));
       }
     }
     if (motion === 'rotate_globe') {
@@ -1954,10 +1969,13 @@ export function adjustOrbitRange(factor) {
     kind === 'tilt'
       ? Math.max(80, TILT_MIN_CLEARANCE_M / Math.abs(Math.sin(hpr.pitch)))
       : 80;
+  // A tilt pivots only within TILT_PIVOT_MAX_RANGE_M; farther out the swing
+  // would carry the camera thousands of km.
+  const ceiling = kind === 'tilt' ? TILT_PIVOT_MAX_RANGE_M : 5_000_000;
   const range = hpr.range;
   hpr.range = Math.max(
     Math.min(floor, range),
-    Math.min(Math.max(5_000_000, range), range * factor),
+    Math.min(Math.max(ceiling, range), range * factor),
   );
   // Under half a metre counts as not moved, as for a plain zoom.
   return { kind, changed: Math.abs(hpr.range - range) >= 0.5 };
diff --git a/src/voice/actionSchemas.test.mjs b/src/voice/actionSchemas.test.mjs
index ecebe8a5d..15c94c96c 100644
--- a/src/voice/actionSchemas.test.mjs
+++ b/src/voice/actionSchemas.test.mjs
@@ -56,8 +56,8 @@ test('the complete Realtime tool payload pins the manifest-generated layer relea
     // area scopes and the osm-places layer; natural-region candidates and the
     // tightened area tool wording follow review.
     // move_camera tilt takes an optional pitchDeg angle, described as
-    // absolute rather than a step.
-    '1dbdef45a477806046cfe4a74a7766f137d7a2b551fdd0b9595986068a85ee8d',
+    // absolute, with steps sent as a direction.
+    'b192c42d1a1c59bea010da93ed0cfb1ce63d2e3ab5e5685921d3bf66e3f94e26',
   );
 });
 
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index 089d95be0..5a30a8cf3 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -49,6 +49,7 @@ import {
   adjustOrbitRange,
   manualCameraInputCount,
   moveCameraArgsError,
+  getActiveCameraMotion,
 } from '../cameraVerbs.js';
 import * as defaultFloorServices from '../data/groundFloor.js';
 import { isPickedWorldPosition } from '../data/scenePick.js';
@@ -293,6 +294,8 @@ export function createGevActionRunner({
   // cancelled the flight, or the flight (still geocoding) then replaced the
   // motion. The wait follows later fly-tos (voiceFlightTarget).
   let voiceFlight = null;
+  // Waiters to tell when a newer voice flight begins.
+  const voiceFlightWatchers = new Set();
   let analystEngine;
   // Area handles live for this runner (the page): resolve_area, the
   // analyst's region/area/drawn scopes, find_imagery and osm_query all read
@@ -1153,6 +1156,25 @@ export function createGevActionRunner({
         prior,
       );
       voiceFlight = flight;
+      for (const notify of [...voiceFlightWatchers]) notify();
+      // A motion already running (one the model sent before this fly-to) is
+      // stopped when the flight takes navigation; the result says so.
+      let stoppedMotion = null;
+      const noteStop =
+        (hook) =>
+        (...hookArgs) => {
+          const before = getActiveCameraMotion();
+          try {
+            return hook(...hookArgs);
+          } finally {
+            if (
+              before &&
+              !stoppedMotion &&
+              getActiveCameraMotion()?.motionId !== before.motionId
+            )
+              stoppedMotion = before.kind;
+          }
+        };
       const flown = flyToRequestedLocation(viewer, args, {
         onFlightEnd: flight.settle,
         onProgress: reportProgress,
@@ -1161,26 +1183,28 @@ export function createGevActionRunner({
         signal: runOptions.signal,
         runImmediate:
           typeof styleManager?.runImmediateLocationNavigation === 'function'
-            ? (navigate) =>
-                styleManager.runImmediateLocationNavigation(navigate)
+            ? noteStop((navigate) =>
+                styleManager.runImmediateLocationNavigation(navigate),
+              )
             : null,
         beginDeferred:
           typeof styleManager?.beginDeferredLocationNavigation === 'function'
-            ? () => styleManager.beginDeferredLocationNavigation()
+            ? noteStop(() => styleManager.beginDeferredLocationNavigation())
             : null,
         reassertDeferred:
           typeof styleManager?.reassertDeferredLocationNavigation === 'function'
-            ? (generation) =>
-                styleManager.reassertDeferredLocationNavigation(generation)
+            ? noteStop((generation) =>
+                styleManager.reassertDeferredLocationNavigation(generation),
+              )
             : null,
-        onStart: () => {
+        onStart: noteStop(() => {
           if (typeof styleManager?.beginLocationNavigation === 'function') {
             styleManager.beginLocationNavigation();
             return;
           }
           interruptCameraMotion('nav:fly_to_location');
           if (viewer.trackedEntity) stopAllTracking(viewer, dataManager);
-        },
+        }),
       });
       // No flight started: nothing to wait for. A lookup that was not found,
       // threw, or was cancelled once a newer voice fly-to had begun (which
@@ -1199,7 +1223,11 @@ export function createGevActionRunner({
           flight.settle('failed');
         else notStarted();
       }, notStarted);
-      return flown;
+      return flown.then((result) =>
+        stoppedMotion && result && typeof result === 'object'
+          ? { ...result, stoppedMotion }
+          : result,
+      );
     }
 
     if (name === 'adjust_camera_zoom') {
@@ -1315,35 +1343,31 @@ export function createGevActionRunner({
         if (argsError) return argsError;
         const deadline = Date.now() + VOICE_FLIGHT_WAIT_MS;
         const start = pending;
+        // Act on where the camera lands. Whatever a flight reports, a later
+        // fly-to replaces it, and the wait moves to that one as soon as it
+        // begins (a stalled geocode must not hold the motion past a newer
+        // flight that landed). A geocode that loses navigation reports
+        // failed, and a flight left flying while the next place is looked up
+        // can still land; running there would take navigation and cancel the
+        // newer one. A later lookup that found nothing moved nothing, so the
+        // motion looks past it to the last flight that did move the camera.
         let flight = start;
-        let status = await waitForVoiceFlight(
-          flight,
-          runOptions.signal,
-          deadline,
-        );
-        // A later fly-to replaces this one: follow it to where the camera
-        // lands, within the same deadline, whatever this flight reported. A
-        // geocode that loses navigation reports failed, and a flight left
-        // flying while the next place is looked up can still land; running
-        // there would take navigation and cancel the newer one. A later
-        // lookup that found nothing moved nothing, so the motion acts on the
-        // last flight it saw that did move the camera.
-        let landed = flight.movedNothing ? null : { flight, status };
-        while (status !== 'aborted' && status !== 'timeout' && current()) {
-          const target = voiceFlightTarget(voiceFlight, start);
-          if (!target || target === flight) break;
-          flight = target;
+        let status;
+        for (;;) {
           status = await waitForVoiceFlight(
             flight,
             runOptions.signal,
             deadline,
+            voiceFlightWatchers,
           );
-          if (!flight.movedNothing) landed = { flight, status };
+          if (status === 'aborted' || status === 'timeout' || !current()) break;
+          const target = voiceFlightTarget(voiceFlight, start);
+          if (!target || (target === flight && status !== 'newer')) break;
+          flight = target;
         }
-        if (flight.movedNothing && landed) ({ flight, status } = landed);
         if (!current())
           return { ok: false, action: 'move_camera', cancelled: true };
-        if (status !== 'arrived')
+        if (status !== 'arrived' || flight.movedNothing)
           return {
             ok: false,
             action: 'move_camera',
@@ -2973,7 +2997,6 @@ function trackVoiceFlight(
   inputCount = manualCameraInputCount(),
   replaced = null,
 ) {
-  let resolve;
   const flight = {
     done: false,
     seq: (voiceFlightCount += 1),
@@ -2981,14 +3004,20 @@ function trackVoiceFlight(
     movedNothing: false,
     // Manual input after this means the user took the camera mid-flight.
     inputCount,
-    ended: new Promise((settle) => {
-      resolve = settle;
-    }),
+    status: null,
+    // Waiters to tell when this flight ends.
+    watchers: new Set(),
     settle: (status) => {
       if (flight.done) return;
       flight.done = true;
-      if (!flight.movedNothing) flight.replaced = null;
-      resolve(status);
+      flight.status = status;
+      // Kept only past a lookup that found nothing, and then straight to the
+      // flight that moved, so a run of such lookups holds no chain.
+      flight.replaced = flight.movedNothing
+        ? voiceFlightTarget(flight.replaced)
+        : null;
+      for (const notify of [...flight.watchers]) notify(status);
+      flight.watchers.clear();
     },
   };
   return flight;
@@ -3027,22 +3056,32 @@ const VOICE_FLIGHT_WAITING_MOTIONS = new Set([
   'rotate',
 ]);
 
-/** Wait for a voice flight to end; 'timeout' or 'aborted' if it does not. */
-function waitForVoiceFlight(flight, signal, deadline) {
+/**
+ * Wait for a voice flight to end, or for a newer one to begin ('newer'):
+ * 'timeout' or 'aborted' if neither happens. A flight that has ended answers
+ * at once. Every listener is removed when the wait ends, so a flight that
+ * never settles holds nothing.
+ */
+function waitForVoiceFlight(flight, signal, deadline, newerWatchers) {
   if (signal?.aborted) return Promise.resolve('aborted');
+  if (flight.done) return Promise.resolve(flight.status);
   return new Promise((resolve) => {
     const finish = (status) => {
       clearTimeout(timer);
       signal?.removeEventListener?.('abort', onAbort);
+      flight.watchers.delete(finish);
+      newerWatchers?.delete(onNewer);
       resolve(status);
     };
     const onAbort = () => finish('aborted');
+    const onNewer = () => finish('newer');
     const timer = setTimeout(
       () => finish('timeout'),
       Math.max(0, deadline - Date.now()),
     );
     signal?.addEventListener?.('abort', onAbort, { once: true });
-    flight.ended.then(finish);
+    flight.watchers.add(finish);
+    newerWatchers?.add(onNewer);
   });
 }
 
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index 678a13659..b2cdbedc4 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -895,6 +895,50 @@ test('a motion gives up on a flight that has not landed in 15 s', async (t) => {
   assert.match(result.error, /did not arrive/);
 });
 
+test('a motion follows a newer fly-to that lands while its own lookup stalls', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    // Place A's lookup never answers.
+    searchNavigation: () => new Promise(() => {}),
+  });
+  t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
+  runner('fly_to_location', { query: 'Place A' });
+  const moved = runner('move_camera', { motion: 'orbit' });
+  const movedDone = settledYet(moved);
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  t.mock.timers.tick(2_000);
+  await Promise.resolve();
+  assert.equal(movedDone(), false, 'the orbit must wait for the newer flight to land');
+  flights[0].complete();
+  for (let i = 0; i < 5 && !movedDone(); i += 1) await Promise.resolve();
+  assert.equal(movedDone(), true, 'the orbit must not wait out A');
+  const result = await moved;
+  assert.equal(result.ok, true);
+  assert.equal(result.motion, 'orbit');
+});
+
+test('a fly-to that stops a running motion says so', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  // The model sent the orbit first, so it ran at once.
+  const orbit = await runner('move_camera', { motion: 'orbit', mode: 'continuous' });
+  assert.equal(orbit.ok, true);
+  const fly = await runner('fly_to_location', { locationId: 'austin' });
+  assert.equal(fly.ok, true);
+  assert.equal(fly.stoppedMotion, 'orbit');
+  const again = await runner('fly_to_location', { locationId: 'austin' });
+  assert.equal('stoppedMotion' in again, false);
+});
+
 test('bad move_camera arguments are refused without waiting for a flight', async () => {
   const { viewer, styleManager } = tiltAfterFlightHarness();
   const runner = createGevActionRunner({
diff --git a/src/voice/pointAndAsk.test.mjs b/src/voice/pointAndAsk.test.mjs
index 66a8e7eda..1f1993a07 100644
--- a/src/voice/pointAndAsk.test.mjs
+++ b/src/voice/pointAndAsk.test.mjs
@@ -350,8 +350,8 @@ test('deixis prompt lint: one short rule, and every sentinel it names exists in
   // the analyst area scopes) raised the ceiling to 55,500; tightening the
   // AREAS rule and the area tool descriptions left it at 55,103 as measured
   // below (every tool, osm_query included); main's Sea Marks and Ski Pistes
-  // layers bring it to 55,210, and the tilt pitchDeg argument to 55,332.
-  // integrationContract's Overpass prompt is the tightest, at 55,492 (8
+  // layers bring it to 55,210, and the tilt pitchDeg argument to 55,335.
+  // integrationContract's Overpass prompt is the tightest, at 55,495 (5
   // under). A new tool or rule has to fit under this ceiling.
   const size = instructions.length + JSON.stringify(GEV_REALTIME_TOOLS).length;
   assert.ok(size <= 55_500, `prompt size ${size}`);

From 64377db91abbb8d324a3dd90dda715d95f2e6570 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Thu, 5 Nov 2026 11:59:11 +0530
Subject: [PATCH 35/71] fix(camera): leave flights and scenes to their framing

Review follow-ups for the globe-in-view recovery and voice limits.

- Leave a camera flight in progress and a playing Director scene, holds
  included, to their own framing. The recovery is now installed with the
  scene tools, which own the Director, and reads its running state.
- Reuse a voice turn's half-degree proof only from the position and
  direction it was proven at, so a release that moves the camera checks
  the turn again.
- Share one free-globe-camera check between the recovery, the voice
  turn limit and the globe rotation.
- Keep an enableLook setting other code makes after the free-look limit
  is installed, instead of writing back the install-time value.
- Name the nudging test for what it asserts, the 1% floor, and document
  that a view losing its surface without a camera move waits for the
  next one.
---
 docs/CURRENT-STATE.md            |  7 +++--
 src/app/application.test.mjs     | 44 ++++++++++++++++++++++++++++++++
 src/app/scene.js                 |  9 -------
 src/app/tools.js                 | 16 +++++++++++-
 src/app/viewer.js                | 27 +++++++++++++-------
 src/cameraGlobeRotation.test.mjs | 28 +++++++++++++++++++-
 src/cameraVerbs.js               | 38 ++++++++++++---------------
 src/globeInView.js               | 12 +++++++++
 8 files changed, 137 insertions(+), 44 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 3fde50e05..4244d5937 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -100,8 +100,11 @@ away, such as a saved or shared view that did, or a drag
 that Cesium turns into an in-place look below its 7,500 km trackball height (one
 that starts on the stars, or a tilt drag with the screen centre off the planet).
 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 and the 2D and
-Columbus modes. A voice turn requested while the camera is tracked is judged
+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) and the 2D and
+Columbus modes. A view that loses its surface without a camera move (a resize,
+or turning the scope on) is left as 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.
 
diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs
index 401eefa0b..d9d915f20 100644
--- a/src/app/application.test.mjs
+++ b/src/app/application.test.mjs
@@ -399,6 +399,26 @@ test('free look follows camera height and is restored on dispose', () => {
   assert.equal(f.listeners.size, 0);
 });
 
+test('free look keeps a setting other code makes after it is installed', () => {
+  const f = freeLookFixture({ height: 500 });
+  const dispose = installFreeLookHeightLimit(f.viewer);
+  f.controller.enableLook = false;
+  f.frame(10);
+  assert.equal(f.controller.enableLook, false, 'turned off stays off');
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
+  f.frame(10);
+  assert.equal(f.controller.enableLook, false, 'and stays off after orbit');
+  f.controller.enableLook = true;
+  f.frame(10);
+  assert.equal(f.controller.enableLook, true, 'turned back on');
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
+  assert.equal(f.controller.enableLook, false, 'still limited from orbit');
+  f.frame(10);
+  f.controller.enableLook = false;
+  dispose();
+  assert.equal(f.controller.enableLook, false, 'dispose keeps a later setting');
+});
+
 test('free look stays off when the viewer had it disabled', () => {
   const f = freeLookFixture({ enableLook: false, height: 500 });
   installFreeLookHeightLimit(f.viewer);
@@ -418,6 +438,7 @@ function realCamera({ width = 1600, height = 900, mode } = {}) {
     pixelRatio: 1,
     ellipsoid: Cesium.Ellipsoid.WGS84,
     mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
+    tweens: new Cesium.TweenCollection(),
     renders: 0,
     requestRender() {
       this.renders += 1;
@@ -674,6 +695,29 @@ test('the recovery follows the scope: corner-only views are turned back only beh
   }
 });
 
+test('the recovery leaves a camera flight and an authored scene alone', () => {
+  let playing = true;
+  const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
+  scene.camera = camera;
+  scene.screenSpaceCameraController = { enableInputs: true };
+  installGlobeInViewRecovery(viewer, { paused: () => playing });
+  aim(camera, reportedStuckView);
+  camera.moveEnd.raiseEvent();
+  assert.equal(globeOutOfFrame(camera), true, 'a playing scene is left alone');
+  playing = false;
+
+  // A flight that pauses looking away is left alone until it ends.
+  camera.flyTo({
+    destination: Cesium.Cartesian3.fromDegrees(10, 20, 18_000_000),
+    duration: 5,
+  });
+  camera.moveEnd.raiseEvent();
+  assert.equal(globeOutOfFrame(camera), true, 'a flight is left alone');
+  camera.cancelFlight();
+  camera.moveEnd.raiseEvent();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+});
+
 function fakeTimers() {
   let next = 1;
   const pending = new Map();
diff --git a/src/app/scene.js b/src/app/scene.js
index 9c115638d..8792a1f4d 100644
--- a/src/app/scene.js
+++ b/src/app/scene.js
@@ -3,12 +3,9 @@ import * as Cesium from 'cesium';
 import {
   createApplicationViewer,
   installFreeLookHeightLimit,
-  installGlobeInViewRecovery,
   installTrackpadPinchZoom,
 } from '../app/viewer.js';
 import { registerDataCredits } from '../data/dataCredits.js';
-import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
-import { isScopeMaskEnabled } from '../scopeMask.js';
 import { configureCreditKeyboardAccess } from '../creditKeyboard.js';
 import { MapStackController } from '../mapStackController.js';
 import { loadPhotorealisticTileset } from '../mapStartup.js';
@@ -63,12 +60,6 @@ export async function createApplicationScene({
   });
   defer(installTrackpadPinchZoom(viewer));
   defer(installFreeLookHeightLimit(viewer));
-  defer(
-    installGlobeInViewRecovery(viewer, {
-      // The scope mask hides everything outside its keyhole.
-      keyholeRadius: () => (isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0),
-    }),
-  );
   registerDataCredits(viewer, credits);
   configureCreditKeyboardAccess(document);
   defer(onLocaleChange(() => configureCreditKeyboardAccess(document)));
diff --git a/src/app/tools.js b/src/app/tools.js
index 9d91f70a9..68033947d 100644
--- a/src/app/tools.js
+++ b/src/app/tools.js
@@ -8,7 +8,13 @@ import { initImageryBoxTool } from '../ui/imageryBoxTool.js';
 import { createRecentImageryPanel } from '../ui/recentImagery.js';
 import { initGevVoiceCommands } from '../voice/gevRealtime.js';
 import { installViews, isEmbeddedInline } from './embed.js';
-import { installScopeMask, destroyScopeMask } from '../scopeMask.js';
+import {
+  installScopeMask,
+  destroyScopeMask,
+  isScopeMaskEnabled,
+} from '../scopeMask.js';
+import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
+import { installGlobeInViewRecovery } from './viewer.js';
 import { installLayerReleaseTrim } from '../sceneCommandRelease.js';
 import {
   installRenderGovernor,
@@ -44,6 +50,14 @@ export function createApplicationTools({
     .get('bhote-koshi-2026')
     ?.module.attachSceneController(sceneDirector);
   defer(() => sceneDirector.destroy());
+  defer(
+    installGlobeInViewRecovery(viewer, {
+      // The scope mask hides everything outside its keyhole.
+      keyholeRadius: () => (isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0),
+      // An authored scene frames its own shots, holds included.
+      paused: () => sceneDirector.running,
+    }),
+  );
   onSceneDirector?.(sceneDirector);
   const annotations = initAnnotations({
     viewer,
diff --git a/src/app/viewer.js b/src/app/viewer.js
index ce182a0ab..c99a34d07 100644
--- a/src/app/viewer.js
+++ b/src/app/viewer.js
@@ -4,6 +4,7 @@ import { StarrySky } from '../sky/starrySky.js';
 import {
   FREE_LOOK_MAX_HEIGHT_METERS,
   globeOutOfFrame,
+  isFreeGlobeCamera,
 } from '../globeInView.js';
 
 const PINCH_ZOOM_MULTIPLIER = 8;
@@ -109,7 +110,9 @@ export function installTrackpadPinchZoom(
 
 /**
  * Allow Cesium's free look only below `maxHeight` and return its disposer.
- * Orbit, tilt and zoom stay available at every height. `enableLook` gates the
+ * 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. `enableLook` gates the
  * Shift+drag binding only; a drag that starts on the stars below Cesium's
  * trackball height still turns the camera in place, which
  * `installGlobeInViewRecovery` catches.
@@ -124,11 +127,14 @@ export function installFreeLookHeightLimit(
   if (!controller || !camera || !scene?.preUpdate)
     throw new TypeError('A complete Cesium viewer is required');
 
-  const originalEnableLook = controller.enableLook;
+  let wanted = controller.enableLook;
+  let written;
   const sync = () => {
+    if (written !== undefined && controller.enableLook !== written)
+      wanted = controller.enableLook;
     const height = camera.positionCartographic?.height;
-    controller.enableLook =
-      originalEnableLook && !(Number.isFinite(height) && height > maxHeight);
+    written = wanted && !(Number.isFinite(height) && height > maxHeight);
+    controller.enableLook = written;
   };
   sync();
   const removeListener = scene.preUpdate.addEventListener(sync);
@@ -138,7 +144,7 @@ export function installFreeLookHeightLimit(
     if (!active) return;
     active = false;
     removeListener();
-    controller.enableLook = originalEnableLook;
+    if (controller.enableLook === written) controller.enableLook = wanted;
   };
 }
 
@@ -159,7 +165,9 @@ const SETTLE_GIVE_UP_MS = 5 * 60_000;
  * catches a saved or shared view that looked away, and a drag that Cesium turns
  * into an in-place look below its trackball height whatever `enableLook` says.
  * Heading and position are kept. Tracked cameras, locked ones (non-identity
- * transform) and the 2D and Columbus modes are left alone. `keyholeRadius`
+ * transform), a camera flight in progress, the 2D and Columbus modes, and any
+ * time `paused` returns true (an authored scene playing) are left alone.
+ * `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.
  *
@@ -179,6 +187,7 @@ export function installGlobeInViewRecovery(
   {
     minHeight = FREE_LOOK_MAX_HEIGHT_METERS,
     keyholeRadius = () => 0,
+    paused = () => false,
     setTimeout: schedule = globalThis.setTimeout,
     clearTimeout: unschedule = globalThis.clearTimeout,
   } = {},
@@ -189,9 +198,9 @@ export function installGlobeInViewRecovery(
     throw new TypeError('A complete Cesium viewer is required');
 
   const recover = () => {
-    if (scene.mode !== Cesium.SceneMode.SCENE3D || viewer.trackedEntity) return;
-    if (!Cesium.Matrix4.equals(camera.transform, Cesium.Matrix4.IDENTITY))
-      return;
+    if (!isFreeGlobeCamera(viewer)) return;
+    // Cesium has no public running-flight flag.
+    if (camera._currentFlight || paused()) return;
     const height = camera.positionCartographic?.height;
     if (
       !(height > minHeight) ||
diff --git a/src/cameraGlobeRotation.test.mjs b/src/cameraGlobeRotation.test.mjs
index f15ae4978..543c01bff 100644
--- a/src/cameraGlobeRotation.test.mjs
+++ b/src/cameraGlobeRotation.test.mjs
@@ -1526,7 +1526,7 @@ test('a voice turn after something else turned the camera starts over', (t) => {
   assert.ok(globeFrameShare(camera) >= start - 2 / (32 * 18) - 1e-9);
 });
 
-test('nudging the camera between voice turns cannot slide the planet away', (t) => {
+test('nudging the camera between voice turns cannot take the planet below the 1% floor', (t) => {
   withScope(t, false); // the whole frame is visible
   // A wheel notch or an orbit drag between requests starts each turn afresh;
   // the 1% floor still holds, and below it a turn may only keep what it has.
@@ -1810,6 +1810,32 @@ test('a refused voice turn leaves a tracked camera tracking', (t) => {
   }
 });
 
+test('a turn proven at one position is checked again after a release moves the camera', (t) => {
+  withScope(t, false);
+  const { camera, tick } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  // Tilt up to the limit, then check from 4,000 km closer along the same view
+  // direction, where the next tilt fits; the release moves the camera back.
+  for (let i = 0; i < 40; i += 1) {
+    if (!moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok)
+      break;
+    for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
+  }
+  camera.moveForward(4_000_000);
+  const result = moveCamera(
+    { motion: 'tilt', direction: 'up', mode: 'once' },
+    (start) => {
+      camera.moveBackward(4_000_000);
+      return start();
+    },
+  );
+  assert.equal(result.ok, false);
+  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.
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 964b5c1a7..3c8424b82 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -22,6 +22,7 @@ import * as Cesium from 'cesium';
 import { GLOBE_VIEW } from './locations.js';
 import {
   globeFrameShare,
+  isFreeGlobeCamera,
   lookAngleWithinFrame,
   lookStepLosesGlobe,
 } from './globeInView.js';
@@ -1015,18 +1016,6 @@ export function interruptCameraMotionIfActive(
   return interruptCameraMotion(reason);
 }
 
-/**
- * A free globe camera: 3D, not tracking, not locked to a frame. The frame
- * limit for in-place turns applies to it alone, as the move-end recovery does.
- */
-function isFreeGlobeCamera(cam) {
-  return (
-    _viewer.scene.mode === Cesium.SceneMode.SCENE3D &&
-    !_viewer.trackedEntity &&
-    Cesium.Matrix4.equals(cam.transform, Cesium.Matrix4.IDENTITY)
-  );
-}
-
 // The frame share that in-place voice turns measure their limit against, with
 // the pose the last voice turn left the camera in. A turn that starts where
 // the last one left off keeps that baseline (raised if the planet now fills
@@ -1036,7 +1025,7 @@ function isFreeGlobeCamera(cam) {
 let _lookBaseline = null;
 
 // The pre-check's proof that a half-degree turn from this pose keeps the planet
-// in view: which way, from which direction. A motion that starts from that
+// 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);
@@ -1079,7 +1068,7 @@ function lookBaselineShare(cam) {
  */
 function lookWithinFrame(cam, m, look, angle) {
   let allowed = angle;
-  if (isFreeGlobeCamera(cam)) {
+  if (isFreeGlobeCamera(_viewer)) {
     if (m.globeShareAtStart === undefined) {
       m.globeShareAtStart = lookBaselineShare(cam);
       m.provenTurnRad = lookProven(cam, look) ? PROVEN_TURN_RAD : 0;
@@ -1105,6 +1094,12 @@ function lookWithinFrame(cam, m, look, angle) {
 function lookProven(cam, look) {
   return (
     _provenLook?.look === look &&
+    Cesium.Cartesian3.equalsEpsilon(
+      _provenLook.position,
+      cam.positionWC,
+      0,
+      1,
+    ) &&
     Cesium.Cartesian3.equalsEpsilon(
       _provenLook.direction,
       cam.directionWC,
@@ -1129,7 +1124,7 @@ function checkLookFromOrbit(look, { released = false } = {}) {
   _provenLook = null;
   if (_viewer.scene.mode !== Cesium.SceneMode.SCENE3D) return null;
   const cam = _viewer.camera;
-  if (!released && !isFreeGlobeCamera(cam)) return null;
+  if (!released && !isFreeGlobeCamera(_viewer)) return null;
   if (
     lookStepLosesGlobe(cam, look, PROVEN_TURN_RAD, {
       ...visibleFrame(),
@@ -1142,7 +1137,11 @@ function checkLookFromOrbit(look, { released = false } = {}) {
       error:
         'From this height that would turn the globe out of view — zoom in first, or turn the other way.',
     };
-  _provenLook = { look, direction: Cesium.Cartesian3.clone(cam.directionWC) };
+  _provenLook = {
+    look,
+    position: Cesium.Cartesian3.clone(cam.positionWC),
+    direction: Cesium.Cartesian3.clone(cam.directionWC),
+  };
   return null;
 }
 
@@ -1329,12 +1328,7 @@ function onTick() {
         // 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.
-        if (
-          _viewer.scene.mode !== Cesium.SceneMode.SCENE3D ||
-          _viewer.trackedEntity ||
-          _isCockpitActive?.() ||
-          !Cesium.Matrix4.equals(cam.transform, Cesium.Matrix4.IDENTITY)
-        ) {
+        if (!isFreeGlobeCamera(_viewer) || _isCockpitActive?.()) {
           interruptCameraMotion('globe-camera-owner-changed');
           return;
         }
diff --git a/src/globeInView.js b/src/globeInView.js
index 1ccbcda23..98a3445dc 100644
--- a/src/globeInView.js
+++ b/src/globeInView.js
@@ -9,6 +9,18 @@ export const FREE_LOOK_MAX_HEIGHT_METERS = 1_000_000;
 // the planet's surface.
 export const MIN_GLOBE_FRAME_SHARE = 0.1;
 
+/**
+ * A free globe camera: the viewer is in 3D, follows no tracked entity, and its
+ * camera is not locked to a reference frame.
+ */
+export function isFreeGlobeCamera(viewer) {
+  return (
+    viewer.scene.mode === Cesium.SceneMode.SCENE3D &&
+    !viewer.trackedEntity &&
+    Cesium.Matrix4.equals(viewer.camera.transform, Cesium.Matrix4.IDENTITY)
+  );
+}
+
 const GRID_COLUMNS = 32;
 const GRID_ROWS = 18;
 // A turn across a sliver of planet moves its edge through sample points, so

From 2f9d13f39d1b05d60aeded65e4a0334f13952734 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Thu, 5 Nov 2026 12:20:26 +0530
Subject: [PATCH 36/71] fix(camera): orbit on drags from the stars above 1,000
 km

Below Cesium's trackball height (7,500 km by default) a drag that starts
on the stars turns the camera in place, whatever enableLook says, which
was the drag path to a view with no planet in it. Lower that height to
the free-look height with the free-look limit, never raising it, and
restore it on dispose. Above 1,000 km such a drag now orbits the globe,
as it already did above 7,500 km, at a similar rate, and a tilt drag
from the stars there tilts about the planet's edge or does nothing
instead of turning the camera. Drags that start on the planet are
unchanged.
---
 docs/CURRENT-STATE.md        |  9 +++++----
 src/app/application.test.mjs | 23 ++++++++++++++++++++++-
 src/app/viewer.js            | 17 +++++++++++------
 3 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 4244d5937..94c2dc1aa 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -67,7 +67,10 @@ the real browser controller at desktop and phone widths with keyless fixtures.
 
 Cesium's free look (Shift+drag, which turns the camera in place) works only
 below 1,000 km. Above that height a few drags could turn the whole planet out of
-frame and leave only stars, so Shift+drag does nothing there. Orbit, tilt and
+frame and leave only stars, so Shift+drag does nothing there. Cesium also
+turns the camera in place for a drag that starts on the stars below its
+trackball height (7,500 km by default); that height is lowered to 1,000 km, so
+such a drag orbits the globe above it, as it does higher up. Orbit, tilt and
 zoom are unchanged at every height. 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
@@ -96,9 +99,7 @@ rest, and gives up five minutes after the camera last moved. Limb glow, and a
 surface sliver up to about one grid cell thick (some 50 px on a 900 px tall
 frame), can count as out of view. The zoom-out guard above keeps wheel and
 pinch zoom-outs in view; this catches the other ways a move can end looking
-away, such as a saved or shared view that did, or a drag
-that Cesium turns into an in-place look below its 7,500 km trackball height (one
-that starts on the stars, or a tilt drag with the screen centre off the planet).
+away, such as a saved or shared view that did.
 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) and the 2D and
diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs
index d9d915f20..fa489cc69 100644
--- a/src/app/application.test.mjs
+++ b/src/app/application.test.mjs
@@ -359,7 +359,7 @@ test('trackpad pinch falls back to the original event when relay construction fa
 
 function freeLookFixture({ enableLook = true, height = 0 } = {}) {
   const listeners = new Set();
-  const controller = { enableLook };
+  const controller = { enableLook, minimumTrackBallHeight: 7_500_000 };
   const camera = { positionCartographic: { height } };
   const viewer = {
     camera,
@@ -399,6 +399,27 @@ test('free look follows camera height and is restored on dispose', () => {
   assert.equal(f.listeners.size, 0);
 });
 
+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);
+  assert.equal(
+    f.controller.minimumTrackBallHeight,
+    FREE_LOOK_MAX_HEIGHT_METERS,
+  );
+  dispose();
+  assert.equal(f.controller.minimumTrackBallHeight, 7_500_000);
+
+  const lower = freeLookFixture({ height: 500 });
+  lower.controller.minimumTrackBallHeight = 500_000;
+  installFreeLookHeightLimit(lower.viewer)();
+  assert.equal(
+    lower.controller.minimumTrackBallHeight,
+    500_000,
+    'never raised',
+  );
+});
+
 test('free look keeps a setting other code makes after it is installed', () => {
   const f = freeLookFixture({ height: 500 });
   const dispose = installFreeLookHeightLimit(f.viewer);
diff --git a/src/app/viewer.js b/src/app/viewer.js
index c99a34d07..e44d1aa10 100644
--- a/src/app/viewer.js
+++ b/src/app/viewer.js
@@ -112,10 +112,10 @@ export function installTrackpadPinchZoom(
  * 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. `enableLook` gates the
- * Shift+drag binding only; a drag that starts on the stars below Cesium's
- * trackball height still turns the camera in place, which
- * `installGlobeInViewRecovery` catches.
+ * dispose. `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,
@@ -127,6 +127,9 @@ export function installFreeLookHeightLimit(
   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 = () => {
@@ -145,6 +148,8 @@ export function installFreeLookHeightLimit(
     active = false;
     removeListener();
     if (controller.enableLook === written) controller.enableLook = wanted;
+    if (controller.minimumTrackBallHeight === trackBallHeight)
+      controller.minimumTrackBallHeight = originalTrackBallHeight;
   };
 }
 
@@ -162,8 +167,8 @@ const SETTLE_GIVE_UP_MS = 5 * 60_000;
  * 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, and a drag that Cesium turns
- * into an in-place look below its trackball height whatever `enableLook` says.
+ * 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, the 2D and Columbus modes, and any
  * time `paused` returns true (an authored scene playing) are left alone.

From 29935cc094480308ef381a51bd9af14249911699 Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Thu, 5 Nov 2026 14:36:10 +0530
Subject: [PATCH 37/71] fix(camera): run a recovery check a scene deferred once
 it ends

A check skipped because a flight or a playing Director scene was in
progress used to be dropped, so a run that ended or held on a stars-only
shot stayed there until the next camera move. Keep watching instead:
the settle check retries once the flight or scene ends, within its
existing five-minute bound, and a moveEnd that arrives while it is
deferred keeps the check armed rather than stopping it.

Also test that the free-look limit never raises Cesium's trackball
height and that dispose keeps a value set after install, note in its
JSDoc the enableLook case it cannot tell apart, and document the
trackball change and the retry in CURRENT-STATE and the changelog.
---
 changelog.d/1532-globe-in-view.md | 11 +++++----
 docs/CURRENT-STATE.md             | 32 +++++++++++++------------
 src/app/application.test.mjs      | 39 ++++++++++++++++++++++++++++++-
 src/app/viewer.js                 | 25 ++++++++++++--------
 4 files changed, 76 insertions(+), 31 deletions(-)

diff --git a/changelog.d/1532-globe-in-view.md b/changelog.d/1532-globe-in-view.md
index f697959b2..676dfebf3 100644
--- a/changelog.d/1532-globe-in-view.md
+++ b/changelog.d/1532-globe-in-view.md
@@ -1,8 +1,9 @@
 - Keep the globe in view from orbit. Cesium's free look (Shift+drag) turned
   the camera in place, so a few drags from the whole-globe view left only
   stars, and the pose stayed in the share link. Free look now works only below
-  1,000 km; a camera move that ends above it with no planet surface in view
-  (inside the scope keyhole when the scope is on) turns straight down; and
-  voice tilt and turns from orbit stop while the planet is still on screen and
-  say so instead of reporting a turn they could not make (Manjunath,
-  @manjunath22466, #1532).
+  1,000 km, and above it a drag that starts on the stars orbits the globe
+  instead of turning the camera; a camera move that ends above it with no
+  planet surface in view (inside the scope keyhole when the scope is on) turns
+  straight down; and voice tilt and turns from orbit stop while the planet is
+  still on screen and say so instead of reporting a turn they could not make
+  (Manjunath, @manjunath22466, #1532).
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 94c2dc1aa..6fbf52a1e 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -67,10 +67,11 @@ the real browser controller at desktop and phone widths with keyless fixtures.
 
 Cesium's free look (Shift+drag, which turns the camera in place) works only
 below 1,000 km. Above that height a few drags could turn the whole planet out of
-frame and leave only stars, so Shift+drag does nothing there. Cesium also
-turns the camera in place for a drag that starts on the stars below its
-trackball height (7,500 km by default); that height is lowered to 1,000 km, so
-such a drag orbits the globe above it, as it does higher up. Orbit, tilt and
+frame and leave only stars, so Shift+drag does nothing there. Cesium also turns
+the camera in place for a drag that starts on the stars below its trackball
+height (7,500 km by default); that height is lowered to 1,000 km, so such a drag
+orbits the globe above it, as it does higher up, and a tilt drag from the stars
+there tilts about the planet's edge or does nothing. Otherwise orbit, tilt and
 zoom are unchanged at every height. 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
@@ -97,17 +98,18 @@ rounding error every frame and Cesium never sees it stop. That check keeps
 watching until move-end arrives, recovering once after each move that comes to
 rest, and gives up five minutes after the camera last moved. Limb glow, and a
 surface sliver up to about one grid cell thick (some 50 px on a 900 px tall
-frame), can count as out of view. The zoom-out guard above keeps wheel and
-pinch zoom-outs in view; this catches the other ways a move can end looking
-away, such as a saved or shared view that did.
-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) and the 2D and
-Columbus modes. A view that loses its surface without a camera move (a resize,
-or turning the scope on) is left as 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.
+frame), can count as out of view. The zoom-out guard above keeps wheel and pinch
+zoom-outs in view; this catches the other ways a move can end looking away, such
+as a saved or shared view that did. 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) and the 2D and Columbus modes; a check a flight or scene defers
+runs once it ends. A Director shot loaded or replayed outside a run is not a
+playing scene. A view that loses its surface without a camera move (a resize, or
+turning the scope on) is left as 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.
 
 Analyst region queries resolve unique Natural Earth names offline without
 geocoding, so Gold Coast and Ivory Coast name the West African natural regions.
diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs
index fa489cc69..3e4a359e7 100644
--- a/src/app/application.test.mjs
+++ b/src/app/application.test.mjs
@@ -412,12 +412,24 @@ test('drags that start on the stars orbit above the free-look height', () => {
 
   const lower = freeLookFixture({ height: 500 });
   lower.controller.minimumTrackBallHeight = 500_000;
-  installFreeLookHeightLimit(lower.viewer)();
+  const disposeLower = installFreeLookHeightLimit(lower.viewer);
   assert.equal(
     lower.controller.minimumTrackBallHeight,
     500_000,
     'never raised',
   );
+  disposeLower();
+  assert.equal(lower.controller.minimumTrackBallHeight, 500_000);
+
+  const later = freeLookFixture({ height: 500 });
+  const disposeLater = installFreeLookHeightLimit(later.viewer);
+  later.controller.minimumTrackBallHeight = 2_000_000;
+  disposeLater();
+  assert.equal(
+    later.controller.minimumTrackBallHeight,
+    2_000_000,
+    'dispose keeps a value set after install',
+  );
 });
 
 test('free look keeps a setting other code makes after it is installed', () => {
@@ -739,6 +751,31 @@ test('the recovery leaves a camera flight and an authored scene alone', () => {
   assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
 });
 
+test('a check a scene or flight defers runs once it ends', () => {
+  for (const viaMoveEnd of [false, true]) {
+    let playing = true;
+    const timers = fakeTimers();
+    const { camera, viewer } = realCamera({ width: 1225, height: 923 });
+    installGlobeInViewRecovery(viewer, {
+      paused: () => playing,
+      ...timers,
+    });
+    aim(camera, reportedStuckView);
+    camera.moveStart.raiseEvent();
+    // A hold on a stars-only shot: quiet, with or without Cesium's moveEnd.
+    for (let i = 0; i < 4; i += 1) timers.tick();
+    if (viaMoveEnd) camera.moveEnd.raiseEvent();
+    assert.equal(globeOutOfFrame(camera), true, 'left alone while it plays');
+    assert.equal(timers.pending(), 1, 'still watching');
+    playing = false;
+    timers.tick();
+    assert.ok(
+      Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
+      `recovered once the scene ends (${viaMoveEnd ? 'after moveEnd' : 'no moveEnd'})`,
+    );
+  }
+});
+
 function fakeTimers() {
   let next = 1;
   const pending = new Map();
diff --git a/src/app/viewer.js b/src/app/viewer.js
index e44d1aa10..1bc94ddd8 100644
--- a/src/app/viewer.js
+++ b/src/app/viewer.js
@@ -112,7 +112,9 @@ export function installTrackpadPinchZoom(
  * 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. `enableLook` gates the Shift+drag binding only: below its trackball
+ * 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.
@@ -171,7 +173,8 @@ const SETTLE_GIVE_UP_MS = 5 * 60_000;
  * looking away from the planet.
  * Heading and position are kept. Tracked cameras, locked ones (non-identity
  * transform), a camera flight in progress, the 2D and Columbus modes, and any
- * time `paused` returns true (an authored scene playing) are left alone.
+ * time `paused` returns true (an authored scene playing) are left alone; a
+ * check they defer runs again once they end, within the settle check's bound.
  * `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.
@@ -202,16 +205,18 @@ export function installGlobeInViewRecovery(
   if (!scene || !camera?.moveEnd || !camera?.moveStart)
     throw new TypeError('A complete Cesium viewer is required');
 
+  // Returns false while a flight or a paused scene defers the check, so the
+  // caller can try again once it ends.
   const recover = () => {
-    if (!isFreeGlobeCamera(viewer)) return;
+    if (!isFreeGlobeCamera(viewer)) return true;
     // Cesium has no public running-flight flag.
-    if (camera._currentFlight || paused()) return;
+    if (camera._currentFlight || paused()) return false;
     const height = camera.positionCartographic?.height;
     if (
       !(height > minHeight) ||
       !globeOutOfFrame(camera, { keyholeRadius: keyholeRadius() })
     )
-      return;
+      return true;
     camera.setView({
       orientation: {
         heading: camera.heading,
@@ -220,6 +225,7 @@ export function installGlobeInViewRecovery(
       },
     });
     scene.requestRender?.();
+    return true;
   };
 
   const lastPosition = new Cesium.Cartesian3();
@@ -255,10 +261,8 @@ export function installGlobeInViewRecovery(
     }
     // Two quiet samples in a row after a move: at rest for half a second, as
     // for moveEnd.
-    if (restingSamples >= 2 && movedSinceCheck) {
+    if (restingSamples >= 2 && movedSinceCheck && recover())
       movedSinceCheck = false;
-      recover();
-    }
     if (settleElapsed >= SETTLE_GIVE_UP_MS) return;
     Cesium.Cartesian3.clone(camera.positionWC, lastPosition);
     Cesium.Cartesian3.clone(camera.directionWC, lastDirection);
@@ -274,8 +278,9 @@ export function installGlobeInViewRecovery(
     settleTimer = schedule(sample, SETTLE_SAMPLE_MS);
   };
   const removeMoveEnd = camera.moveEnd.addEventListener(() => {
-    stopSettling();
-    recover();
+    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);
 

From 852e93d074761477575cbead33f2f12dd71c7bbf Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Thu, 5 Nov 2026 14:45:29 +0530
Subject: [PATCH 38/71] fix(camera): keep a deferred recovery check through
 long holds

A Director hold longer than the settle check's five-minute bound used
to expire the deferred check, so a run that ended on a stars-only shot
after a long hold stayed there until the next move. While a flight or a
playing scene defers the check, its bound no longer counts down; the
flight or scene bounds the deferral itself.

Also correct the trackball note in CURRENT-STATE: Cesium's tilt tests
the screen centre, so any tilt (drag or touch) with the centre on the
stars between 1,000 and 7,500 km now tilts about the planet's edge or
does nothing, wherever it starts. Rotation drags that start on the
planet are unchanged.
---
 docs/CURRENT-STATE.md        | 80 ++++++++++++++++++------------------
 src/app/application.test.mjs |  2 +
 src/app/viewer.js            |  9 ++--
 3 files changed, 48 insertions(+), 43 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 6fbf52a1e..3dd7a59d0 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -70,46 +70,46 @@ below 1,000 km. Above that height a few drags could turn the whole planet out of
 frame and leave only stars, so Shift+drag does nothing there. Cesium also turns
 the camera in place for a drag that starts on the stars below its trackball
 height (7,500 km by default); that height is lowered to 1,000 km, so such a drag
-orbits the globe above it, as it does higher up, and a tilt drag from the stars
-there tilts about the planet's edge or does nothing. Otherwise orbit, tilt and
-zoom are unchanged at every height. 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 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 turn that cannot go half a degree further without crossing that
-limit is refused with a reason instead of reported as done, and a turn it
-accepts turns at least that half degree. A turn that keeps or gains surface is
-not refused, even after the window has been resized, except that near the limit,
-where the planet's edge crosses the sample grid, sampling wobble can
-occasionally refuse one (most often above about 15,000 km and on phone or
-ultrawide frames); nothing then turns away from the planet. A turn that starts
-where the last voice turn left the camera keeps that turn's limit, or a higher
-one if the planet now fills more, so repeating the request does not take any
-more; once anything else has moved or turned the camera, a turn is measured from
-what is on screen. When a camera move ends above 1,000 km with no ray on the
-surface, the camera turns straight down at the same position and heading. The
-end of a move is taken from Cesium's move-end event and from a check of its own
-that samples the pose every 250 ms after a move starts and acts once it has held
-for half a second, because at some of these poses the camera drifts by a
-rounding error every frame and Cesium never sees it stop. That check keeps
-watching until move-end arrives, recovering once after each move that comes to
-rest, and gives up five minutes after the camera last moved. Limb glow, and a
-surface sliver up to about one grid cell thick (some 50 px on a 900 px tall
-frame), can count as out of view. The zoom-out guard above keeps wheel and pinch
-zoom-outs in view; this catches the other ways a move can end looking away, such
-as a saved or shared view that did. 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) and the 2D and Columbus modes; a check a flight or scene defers
-runs once it ends. A Director shot loaded or replayed outside a run is not a
-playing scene. A view that loses its surface without a camera move (a resize, or
-turning the scope on) is left as 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.
+orbits the globe above it, as it does higher up, and a tilt (drag or touch)
+while the screen centre is on the stars there tilts about the planet's edge or
+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
+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
+turn that cannot go half a degree further without crossing that limit is refused
+with a reason instead of reported as done, and a turn it accepts turns at least
+that half degree. A turn that keeps or gains surface is not refused, even after
+the window has been resized, except that near the limit, where the planet's edge
+crosses the sample grid, sampling wobble can occasionally refuse one (most often
+above about 15,000 km and on phone or ultrawide frames); nothing then turns away
+from the planet. A turn that starts where the last voice turn left the camera
+keeps that turn's limit, or a higher one if the planet now fills more, so
+repeating the request does not take any more; once anything else has moved or
+turned the camera, a turn is measured from what is on screen. When a camera move
+ends above 1,000 km with no ray on the surface, the camera turns straight down
+at the same position and heading. The end of a move is taken from Cesium's
+move-end event and from a check of its own that samples the pose every 250 ms
+after a move starts and acts once it has held for half a second, because at some
+of these poses the camera drifts by a rounding error every frame and Cesium
+never sees it stop. That check keeps watching until move-end arrives, recovering
+once after each move that comes to rest, and gives up five minutes after the
+camera last moved. Limb glow, and a surface sliver up to about one grid cell
+thick (some 50 px on a 900 px tall frame), can count as out of view. The
+zoom-out guard above keeps wheel and pinch zoom-outs in view; this catches the
+other ways a move can end looking away, such as a saved or shared view that did.
+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) and the 2D and
+Columbus modes; a check a flight or scene defers runs once it ends. A Director
+shot loaded or replayed outside a run is not a playing scene. A view that loses
+its surface without a camera move (a resize, or turning the scope on) is left as
+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.
 
 Analyst region queries resolve unique Natural Earth names offline without
 geocoding, so Gold Coast and Ivory Coast name the West African natural regions.
diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs
index 3e4a359e7..da01ff61c 100644
--- a/src/app/application.test.mjs
+++ b/src/app/application.test.mjs
@@ -765,6 +765,8 @@ test('a check a scene or flight defers runs once it ends', () => {
     // A hold on a stars-only shot: quiet, with or without Cesium's moveEnd.
     for (let i = 0; i < 4; i += 1) timers.tick();
     if (viaMoveEnd) camera.moveEnd.raiseEvent();
+    // Longer than the settle check's five-minute bound.
+    for (let i = 0; i < 1500; i += 1) timers.tick();
     assert.equal(globeOutOfFrame(camera), true, 'left alone while it plays');
     assert.equal(timers.pending(), 1, 'still watching');
     playing = false;
diff --git a/src/app/viewer.js b/src/app/viewer.js
index 1bc94ddd8..ef36feb8a 100644
--- a/src/app/viewer.js
+++ b/src/app/viewer.js
@@ -174,7 +174,7 @@ const SETTLE_GIVE_UP_MS = 5 * 60_000;
  * Heading and position are kept. Tracked cameras, locked ones (non-identity
  * transform), a camera flight in progress, the 2D and Columbus modes, and any
  * time `paused` returns true (an authored scene playing) are left alone; a
- * check they defer runs again once they end, within the settle check's bound.
+ * 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.
@@ -261,8 +261,11 @@ export function installGlobeInViewRecovery(
     }
     // Two quiet samples in a row after a move: at rest for half a second, as
     // for moveEnd.
-    if (restingSamples >= 2 && movedSinceCheck && recover())
-      movedSinceCheck = false;
+    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);

From a67c7969fdc52449dfeeef59b495772ab563b7a6 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Thu, 5 Nov 2026 13:48:11 +0400
Subject: [PATCH 39/71] fix(transit): read Rio speeds as the m/s SMTR publishes

Both SMTR feeds now publish Position.speed in m/s. Compared with how far
vehicles moved between reports on 2026-11-05, the published values ran
3.1x (buses) and 3.6x (BRT) below the observed speed, so the km/h
conversion divided real speeds by 3.6. Drop speedUnit and the conversion.
---
 DATA_SOURCES.md                 |  2 +-
 changelog.d/1481-rio-transit.md |  7 +++----
 docs/CURRENT-STATE.md           |  3 +--
 src/data/transitFeeds.js        | 11 ++---------
 src/data/transitFeeds.test.mjs  |  3 +--
 src/data/transitProxy.js        | 21 +--------------------
 src/data/transitProxy.test.mjs  | 25 +++++--------------------
 7 files changed, 14 insertions(+), 58 deletions(-)

diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md
index 2ed14c264..eb20f793e 100644
--- a/DATA_SOURCES.md
+++ b/DATA_SOURCES.md
@@ -98,7 +98,7 @@ How to read this:
 | **Barrie Transit** (myridebarrie.ca) | Transit layer live vehicles, Barrie ON | Barrie Transit realtime data, published by the City of Barrie under a licence accepted by use of the data. The licence is revocable and requires no attribution. | Courtesy credit to the City of Barrie (the licence requires none, and its trademark clause is broad) |
 | **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. Speeds arrive in km/h rather than m/s and are converted by the proxy. Route ids are internal keys and are joined to the line names in SMTR’s published GTFS `routes.txt` (dados.mobilidade.rio/gtfs/schedule), under the same CC BY 4.0 terms. | Attribution to SMTR / Prefeitura da Cidade do Rio de Janeiro under CC BY 4.0 |
+| **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. Route ids are internal keys and are joined to the line names in SMTR’s published GTFS `routes.txt` (dados.mobilidade.rio/gtfs/schedule), under the same CC BY 4.0 terms. | Attribution to SMTR / Prefeitura da Cidade do Rio de Janeiro under CC BY 4.0 |
 | **Radio Browser**                                                     | Geolocated internet-radio station directory and station-level tags                                                                  | Public-domain directory data under PDDL 1.0; individual broadcaster stream terms apply                                                                                                                                                                                                                                                                | "Radio Browser" plus a link to the selected broadcaster                                                                                     |
 | **Re:Earth Terrain** (Mapterhorn)                                     | Terrain (keyless globe stacks — OSM etc. — + `/api/terrain/heights` ellipsoidal-height lookups)                                     | Terrain mesh: CC BY 4.0; geoid: EGM2008 (NGA, public domain)                                                                                                                                                                                                                                                                                          | "Terrain (keyless globe stacks): Re:Earth Terrain / Mapterhorn (CC BY 4.0) / EGM2008 (NGA)"                                                 |
 | **OpenSeaMap** (`tiles.openseamap.org`) | Sea Marks layer: raster overlay of buoys, lighthouses and ports (#10) | Chart tiles CC BY-SA 2.0; data ODbL 1.0 via OpenStreetMap | "Sea marks © OpenSeaMap contributors (CC BY-SA 2.0) · Data © OpenStreetMap contributors (ODbL)" |
diff --git a/changelog.d/1481-rio-transit.md b/changelog.d/1481-rio-transit.md
index b45b1b1fd..ac245a9c8 100644
--- a/changelog.d/1481-rio-transit.md
+++ b/changelog.d/1481-rio-transit.md
@@ -1,6 +1,5 @@
 - Add Rio de Janeiro to the Transit layer: municipal buses and the Mobi-Rio BRT
   from SMTR's keyless GTFS-Realtime feeds (CC BY 4.0), the layer's first Latin
-  American region. A feed that publishes speed in km/h declares
-  `speedUnit: 'kmh'` and the proxy converts it to m/s. Rio's internal route
-  keys are joined to SMTR's published GTFS `routes.txt`, so a card reads
-  "Route SN731" rather than "Route O0731AAN0A" (IMBrandao, #1481).
+  American region. Rio's internal route keys are joined to SMTR's published
+  GTFS `routes.txt`, so a card reads "Route SN731" rather than
+  "Route O0731AAN0A" (IMBrandao, #1481).
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 81e71655c..170605951 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -4649,8 +4649,7 @@ Helsinki, the Netherlands, Norway, South East Queensland, Rio de Janeiro
 (municipal buses and the Mobi-Rio BRT, two feeds), and nine in
 Ontario — Toronto (TTC surface vehicles; the subway publishes no
 positions), MiWay, Hamilton HSR, Durham Region, YRT/Viva, Guelph,
-Burlington, Barrie and Kingston. Rio's feeds publish speed in km/h, which
-the proxy converts to m/s before any card reads it. Mode silhouettes
+Burlington, Barrie and Kingston. Mode silhouettes
 identify buses, trams, subways, trains, ferries and unclassified vehicles.
 
 Retained transit history uses the same outlier quarantine as live observations and
diff --git a/src/data/transitFeeds.js b/src/data/transitFeeds.js
index d7993a954..aa953c00b 100644
--- a/src/data/transitFeeds.js
+++ b/src/data/transitFeeds.js
@@ -398,12 +398,7 @@ function rioRouteLabel(routeId) {
  *   url: string, headers?: Record<string, string>,
  *   license: string, licenseUrl: string, attribution: string,
  *   defaultMode: string, routeMode?: (routeId: string|null) => string,
- *   speedUnit?: 'kmh',
  * }>>}
- *
- * `speedUnit: 'kmh'` marks a feed that publishes `Position.speed` in km/h
- * instead of the m/s the spec requires; the proxy converts it before anything
- * downstream reads `speedMps`.
  */
 export const TRANSIT_FEED_REGISTRY = Object.freeze([
   Object.freeze({
@@ -765,10 +760,9 @@ export const TRANSIT_FEED_REGISTRY = Object.freeze([
     terms: Object.freeze({
       quote:
         'This work is licensed under a Creative Commons Attribution 4.0 International License',
-      note: 'The data.rio catalog page labels the feed [beta] and states a gateway limit of 5 requests a second and 60 a minute behind a 10-second cache, which the 15-second proxy TTL stays inside. It is the named replacement for the JSON GPS endpoints SMTR deprecated on 2026-10-07 and says it will switch off by 2026-11-30. SMTR relays the concessionaires’ ITS data and repairs trips with its own matching; the page places accuracy with the suppliers. Speeds arrive in km/h, not m/s (a 2026-10-29 snapshot peaked at 89), hence `speedUnit`. Route ids are internal keys (`O0731AAN0A` is line SN731) and are joined to the line names in SMTR’s published GTFS `routes.txt`, under the same CC BY 4.0 terms.',
+      note: 'The data.rio catalog page labels the feed [beta] and states a gateway limit of 5 requests a second and 60 a minute behind a 10-second cache, which the 15-second proxy TTL stays inside. It is the named replacement for the JSON GPS endpoints SMTR deprecated on 2026-10-07 and says it will switch off by 2026-11-30. SMTR relays the concessionaires’ ITS data and repairs trips with its own matching; the page places accuracy with the suppliers. Speeds are m/s, as the spec requires: on 2026-11-05 they matched how far vehicles moved between reports, though a 2026-10-29 snapshot read as km/h. Route ids are internal keys (`O0731AAN0A` is line SN731) and are joined to the line names in SMTR’s published GTFS `routes.txt`, under the same CC BY 4.0 terms.',
     }),
     defaultMode: 'bus',
-    speedUnit: 'kmh',
     routeLabel: rioRouteLabel,
   }),
   Object.freeze({
@@ -788,10 +782,9 @@ export const TRANSIT_FEED_REGISTRY = Object.freeze([
     terms: Object.freeze({
       quote:
         'This work is licensed under a Creative Commons Attribution 4.0 International License',
-      note: 'Same catalog terms, [beta] label and gateway limits as the bus feed. The fleet is operated by Mobi-Rio and tracked by SONDA, whose data SMTR relays. Speeds are km/h here too (peak 62 in the same snapshot). Route ids are opaque (`20000501110` is line 50) and are joined to the same `routes.txt` as the buses.',
+      note: 'Same catalog terms, [beta] label and gateway limits as the bus feed. The fleet is operated by Mobi-Rio and tracked by SONDA, whose data SMTR relays. Speeds are m/s here too. Route ids are opaque (`20000501110` is line 50) and are joined to the same `routes.txt` as the buses.',
     }),
     defaultMode: 'bus',
-    speedUnit: 'kmh',
     routeLabel: rioRouteLabel,
   }),
 ]);
diff --git a/src/data/transitFeeds.test.mjs b/src/data/transitFeeds.test.mjs
index 8333207d5..dbae35c24 100644
--- a/src/data/transitFeeds.test.mjs
+++ b/src/data/transitFeeds.test.mjs
@@ -535,14 +535,13 @@ test('the Rio route table is a clean join of published keys to names', () => {
   }
 });
 
-test('Rio feeds are CC BY 4.0, live, and declare the km/h speeds they publish', () => {
+test('Rio feeds are CC BY 4.0 and live', () => {
   for (const id of ['smtr-rio-onibus', 'smtr-rio-brt']) {
     const feed = getTransitFeed(id);
     assert.equal(feed.defaultEnabled, true, `${id} is live`);
     assert.equal(feed.license, 'CC BY 4.0');
     assert.match(feed.licenseUrl, /^https:\/\/www\.data\.rio\/documents\//);
     assert.match(feed.attribution, /Prefeitura da Cidade do Rio de Janeiro/);
-    assert.equal(feed.speedUnit, 'kmh', `${id} publishes km/h`);
     assert.equal(transitModeFor(feed, null), 'bus');
   }
   const sources = readFileSync(
diff --git a/src/data/transitProxy.js b/src/data/transitProxy.js
index 2923c9c32..458240e9d 100644
--- a/src/data/transitProxy.js
+++ b/src/data/transitProxy.js
@@ -224,25 +224,6 @@ export function repairVehicleTimestamps(vehicles, headerTimestamp, fetchedAtS) {
   });
 }
 
-/**
- * Bring a feed's speeds to the m/s the spec requires. A feed registered with
- * `speedUnit: 'kmh'` publishes km/h in `Position.speed`, and read as m/s a
- * 44 km/h bus would be reported at 158 km/h. Converting here, once, keeps every
- * consumer of `speedMps` honest without each one knowing about the feed.
- *
- * @param {object} feed Registry entry.
- * @param {object[]} vehicles Normalized vehicle records.
- * @returns {object[]}
- */
-export function normalizeFeedSpeeds(feed, vehicles) {
-  if (feed?.speedUnit !== 'kmh') return vehicles;
-  return vehicles.map((vehicle) =>
-    Number.isFinite(vehicle.speedMps)
-      ? { ...vehicle, speedMps: vehicle.speedMps / 3.6 }
-      : vehicle,
-  );
-}
-
 /**
  * Decode upstream bytes into the JSON snapshot the browser consumes.
  *
@@ -276,7 +257,7 @@ export function buildTransitSnapshot(feed, bytes, now = Date.now()) {
     truncated: decoded.truncated,
     count: decoded.vehicles.length,
     vehicles: repairVehicleTimestamps(
-      normalizeFeedSpeeds(feed, decoded.vehicles),
+      decoded.vehicles,
       decoded.timestamp,
       Math.floor(now / 1000),
     ),
diff --git a/src/data/transitProxy.test.mjs b/src/data/transitProxy.test.mjs
index 445e658f2..07911a939 100644
--- a/src/data/transitProxy.test.mjs
+++ b/src/data/transitProxy.test.mjs
@@ -285,29 +285,14 @@ test('the snapshot builder fills timestamps from the header it decoded', () => {
   assert.equal(snapshot.feedTimestamp, 1_700_000_000);
 });
 
-test('a feed that publishes km/h has its speeds converted to m/s, and only that feed', () => {
-  // Rio's SMTR feeds put km/h in Position.speed; read as m/s, a 36 km/h bus
-  // would be reported at 130 km/h.
+test('Rio speeds pass through as the m/s they are published in', () => {
+  // SMTR publishes m/s, as the spec requires: checked against how far
+  // vehicles moved between reports on 2026-11-05.
   const bytes = encodeFeed({
-    entities: [
-      { id: 'moving', lat: -22.9, lon: -43.2, speed: 36 },
-      { id: 'still', lat: -22.9, lon: -43.2, speed: 0 },
-      { id: 'silent', lat: -22.9, lon: -43.2 },
-    ],
+    entities: [{ id: 'moving', lat: -22.9, lon: -43.2, speed: 10 }],
   });
   const rio = buildTransitSnapshot(getTransitFeed('smtr-rio-onibus'), bytes, 1);
-  const speeds = Object.fromEntries(
-    rio.vehicles.map((vehicle) => [vehicle.id, vehicle.speedMps]),
-  );
-  assert.ok(Math.abs(speeds.moving - 10) < 1e-6, '36 km/h is 10 m/s');
-  assert.equal(speeds.still, 0);
-  assert.equal(speeds.silent, null, 'an absent speed stays absent');
-  const mbta = buildTransitSnapshot(getTransitFeed('mbta'), bytes, 1);
-  assert.equal(
-    mbta.vehicles.find((vehicle) => vehicle.id === 'moving').speedMps,
-    36,
-    'a spec-conforming feed is left alone',
-  );
+  assert.equal(rio.vehicles[0].speedMps, 10);
 });
 
 test('conditional-request validators and gzip ride along with feed identification', () => {

From 70f405cf1b448e1543b4df527f15a35d556e55f2 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Thu, 5 Nov 2026 13:48:11 +0400
Subject: [PATCH 40/71] chore(transit): register rioRouteNames.js in the
 package and format scopes

---
 scripts/format-scope.json       | 1 +
 scripts/package-boundaries.json | 8 ++++++++
 2 files changed, 9 insertions(+)

diff --git a/scripts/format-scope.json b/scripts/format-scope.json
index 2c589d8cc..b390581d0 100644
--- a/scripts/format-scope.json
+++ b/scripts/format-scope.json
@@ -786,6 +786,7 @@
   "server/providers/transit.js",
   "server/providers/transitHistory.js",
   "server/providers/transitHistory.test.mjs",
+  "src/data/rioRouteNames.js",
   "src/data/transitFeeds.js",
   "src/data/transitFeeds.test.mjs",
   "src/data/transitProxy.js",
diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json
index d008ceaaa..a70878bd1 100644
--- a/scripts/package-boundaries.json
+++ b/scripts/package-boundaries.json
@@ -2954,6 +2954,7 @@
       "src/app/layers/transit.js",
       "src/data/transit.js",
       "src/data/transitFeeds.js",
+      "src/data/rioRouteNames.js",
       "src/data/transitIcons.js",
       "src/data/transitPresetStyle.js",
       "src/layers/transit/controls.js",
@@ -3704,6 +3705,7 @@
       "src/sources/nominatim.js",
       "src/app/layers/transit.js",
       "src/data/transitFeeds.js",
+      "src/data/rioRouteNames.js",
       "src/data/transitIcons.js",
       "src/data/transitPresetStyle.js",
       "src/layers/transit/controls.js",
@@ -4465,6 +4467,7 @@
       "server/providers/transitHistory.js",
       "src/data/gtfsRealtime.js",
       "src/data/transitFeeds.js",
+      "src/data/rioRouteNames.js",
       "src/geoDistance.js",
       "src/data/transitProxy.js",
       "src/sources/httpBody.js",
@@ -4481,6 +4484,7 @@
     "modules": [
       "src/data/gtfsRealtime.js",
       "src/data/transitFeeds.js",
+      "src/data/rioRouteNames.js",
       "src/geoDistance.js",
       "src/data/transitProxy.js",
       "src/sources/transitHistory.js"
@@ -4514,6 +4518,7 @@
       "src/data/terrainHeights.js",
       "src/data/transit.js",
       "src/data/transitFeeds.js",
+      "src/data/rioRouteNames.js",
       "src/data/transitIcons.js",
       "src/data/transitPresetStyle.js",
       "src/data/transitProxy.js",
@@ -4572,6 +4577,7 @@
       "src/data/iconOrientation.js",
       "src/data/inputOwnership.js",
       "src/data/transitFeeds.js",
+      "src/data/rioRouteNames.js",
       "src/geoDistance.js",
       "src/data/transitIcons.js",
       "src/data/transitPresetStyle.js",
@@ -4629,6 +4635,7 @@
     "exports": ["./sources/transit-service"],
     "modules": [
       "src/data/transitFeeds.js",
+      "src/data/rioRouteNames.js",
       "src/geoDistance.js",
       "src/data/transitProxy.js",
       "src/data/gtfsRealtime.js",
@@ -4873,6 +4880,7 @@
       "src/tools/surfaces.js",
       "src/layers/transit/policy.js",
       "src/data/transitFeeds.js",
+      "src/data/rioRouteNames.js",
       "src/layers/transit/movement.js",
       "src/data/contactPlayback.js",
       "src/data/layerSnapshot.js",

From ef4b319f975dcd1515997101226311127867267e Mon Sep 17 00:00:00 2001
From: Manjunath <manjunath@halfpixel.ai>
Date: Thu, 5 Nov 2026 15:57:09 +0530
Subject: [PATCH 41/71] docs(changelog): credit the review behind the
 follow-ups

---
 changelog.d/1532-globe-in-view.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/changelog.d/1532-globe-in-view.md b/changelog.d/1532-globe-in-view.md
index 676dfebf3..4ac444023 100644
--- a/changelog.d/1532-globe-in-view.md
+++ b/changelog.d/1532-globe-in-view.md
@@ -5,5 +5,7 @@
   instead of turning the camera; a camera move that ends above it with no
   planet surface in view (inside the scope keyhole when the scope is on) turns
   straight down; and voice tilt and turns from orbit stop while the planet is
-  still on screen and say so instead of reporting a turn they could not make
-  (Manjunath, @manjunath22466, #1532).
+  still on screen and say so instead of reporting a turn they could not make.
+  Thanks to [Chad Elliott](https://github.com/THEtheChad) for the review that
+  closed the drag path and kept authored scenes framed (Manjunath,
+  @manjunath22466, #1532).

From e4fda9d4e6d7f0d5c8cc8bfba82dd33d959dbc64 Mon Sep 17 00:00:00 2001
From: Mert Kaya <47145541+mertkayacs@users.noreply.github.com>
Date: Thu, 5 Nov 2026 17:39:34 +0300
Subject: [PATCH 42/71] fix(geocode): preserve non-Latin names in keyless
 search

---
 changelog.d/1585-keyless-unicode-search.md  |   3 +
 docs/CURRENT-STATE.md                       |   6 +-
 scripts/package-boundaries.json             |   1 +
 src/data/fixtures/README.md                 |   5 +
 src/data/fixtures/photon-moscow-search.json | 110 ++++++++++++++++++++
 src/keylessGeocoder.js                      |  16 ++-
 src/keylessGeocoder.test.mjs                |  37 ++++++-
 7 files changed, 166 insertions(+), 12 deletions(-)
 create mode 100644 changelog.d/1585-keyless-unicode-search.md
 create mode 100644 src/data/fixtures/photon-moscow-search.json

diff --git a/changelog.d/1585-keyless-unicode-search.md b/changelog.d/1585-keyless-unicode-search.md
new file mode 100644
index 000000000..276ade93f
--- /dev/null
+++ b/changelog.d/1585-keyless-unicode-search.md
@@ -0,0 +1,3 @@
+- Keep keyless place search on a nearby exact match for names written in
+  non-Latin scripts instead of discarding the match and retrying without its
+  proximity ranking (Mert Kaya, @mertkayacs, #PRNUM).
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index f1244947d..45fe2999e 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5720,8 +5720,10 @@ HTTP refusals and outages remain retryable. Searches share a 12-second total
 deadline, with Photon requests capped at six seconds each. Caller/application
 cancellation stops retries and late cache writes. Replacing a location search
 cancels the previous lookup; disposing its controls cancels the active lookup. Photon uses a soft proximity bias, up to five
-candidates, and an unbiased retry for name mismatches. A "place, region" query
-prefers a candidate named exactly for the place whose city, county, state,
+candidates, and an unbiased retry for name mismatches. Name comparison folds
+Latin accents while preserving letters and marks in other scripts, so an exact
+non-Latin name keeps its proximity ranking. A "place, region" query prefers a
+candidate named exactly for the place whose city, county, state,
 country or country code (or USA/UK) contains every word of the region, and a
 settlement or administrative area over a POI when both fit. Nearby results that
 fail that check are retried unbiased. After the region checks of both passes, a
diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json
index d008ceaaa..72652d8da 100644
--- a/scripts/package-boundaries.json
+++ b/scripts/package-boundaries.json
@@ -552,6 +552,7 @@
       "src/search/placeSearch.js",
       "src/search/google.js",
       "src/keylessGeocoder.js",
+      "src/data/placeNames.js",
       "src/search/geospatial.js",
       "src/search/http.js",
       "src/search/defaults.js",
diff --git a/src/data/fixtures/README.md b/src/data/fixtures/README.md
index e9dd55f50..257eaf8a5 100644
--- a/src/data/fixtures/README.md
+++ b/src/data/fixtures/README.md
@@ -1,5 +1,10 @@
 # Test fixtures
 
+- `photon-moscow-search.json` - Photon responses for `Москва`, captured
+  2026-11-05 with and without a proximity bias near the Tajikistan namesake.
+  The fixture is trimmed to the fields the keyless geocoder consumes and is
+  used only by offline search tests. Data from OpenStreetMap contributors,
+  ODbL 1.0 (https://www.openstreetmap.org/copyright).
 - `tomtom-flow-austin-12-935-1686.pbf` — one real TomTom traffic-flow vector
   tile (Mapbox Vector Tile protobuf, layer `"Traffic flow"`), downtown Austin
   z12 x935 y1686, captured 2026-07-16 from
diff --git a/src/data/fixtures/photon-moscow-search.json b/src/data/fixtures/photon-moscow-search.json
new file mode 100644
index 000000000..7b1a4d25a
--- /dev/null
+++ b/src/data/fixtures/photon-moscow-search.json
@@ -0,0 +1,110 @@
+{
+  "biased": {
+    "features": [
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [71.8339931, 38.948412]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Тоҷикистон"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.6063916, 55.625578]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.6174782, 55.7505412]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.0536908, 55.7098009]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [32.163334, 56.917778]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      }
+    ]
+  },
+  "unbiased": {
+    "features": [
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.6063916, 55.625578]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.6174782, 55.7505412]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.0536908, 55.7098009]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [32.163334, 56.917778]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [71.8339931, 38.948412]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Тоҷикистон"
+        }
+      }
+    ]
+  }
+}
diff --git a/src/keylessGeocoder.js b/src/keylessGeocoder.js
index 4e01f1c74..eb881f970 100644
--- a/src/keylessGeocoder.js
+++ b/src/keylessGeocoder.js
@@ -1,3 +1,5 @@
+import { foldPlaceName } from './data/placeNames.js';
+
 /** Photon/OpenStreetMap place-search adapter. */
 const PHOTON_ENDPOINT = 'https://photon.komoot.io/api/';
 
@@ -233,19 +235,15 @@ export function photonSearchUrl(
 }
 
 /**
- * Place name reduced to comparable form: unaccented, lowercased, punctuation
- * collapsed to single spaces. "Huế" and "Hue" have to compare equal, because a
- * user typing either means the same city.
+ * Place name reduced to comparable form: lowercased, Latin accents removed,
+ * other scripts preserved, and punctuation collapsed to single spaces. "Huế"
+ * and "Hue" have to compare equal, because a user typing either means the same
+ * city.
  * @param {string} text
  * @returns {string}
  */
 export function normalizeToponym(text) {
-  return String(text ?? '')
-    .normalize('NFD')
-    .replace(/[\u0300-\u036f]/g, '')
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, ' ')
-    .trim();
+  return foldPlaceName(text);
 }
 
 /**
diff --git a/src/keylessGeocoder.test.mjs b/src/keylessGeocoder.test.mjs
index 95098a10c..e4c762f62 100644
--- a/src/keylessGeocoder.test.mjs
+++ b/src/keylessGeocoder.test.mjs
@@ -35,6 +35,12 @@ import {
 import { geocodeNavigationMode } from './locations.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const MOSCOW_RESPONSES = JSON.parse(
+  fs.readFileSync(
+    path.join(ROOT, 'src/data/fixtures/photon-moscow-search.json'),
+    'utf8',
+  ),
+);
 
 /** Photon's real answer for "Hanoi", trimmed to the fields we consume. */
 const HANOI = {
@@ -223,7 +229,6 @@ const HUE = {
     extent: [107.3763, 16.7739, 108.0518, 16.1276],
   },
 };
-
 /** Answers biased requests with `nearby`, unbiased ones with `anywhere`. */
 function photonPair(nearby, anywhere) {
   const urls = [];
@@ -249,6 +254,36 @@ test('a biased near-miss is refused, and the unbiased answer is taken instead',
   assert.equal(fetchImpl.urls.length, 2, 'the refused bias costs exactly one extra request');
 });
 
+test('a non-Latin exact match keeps the nearby namesake', async () => {
+  const fetchImpl = photonPair(
+    MOSCOW_RESPONSES.biased.features,
+    MOSCOW_RESPONSES.unbiased.features,
+  );
+
+  const result = await geocodeKeyless('Москва', {
+    bias: '38.90,71.80|39.00,71.90',
+    fetchImpl,
+  });
+
+  assert.equal(result.label, 'Москва, Тоҷикистон');
+  assert.equal(fetchImpl.urls.length, 1);
+});
+
+test('toponym folding preserves non-Latin scripts', () => {
+  const cases = [
+    ['Huế', 'hue'],
+    ['Москва', 'москва'],
+    ['Αθήνα', 'αθήνα'],
+    ['القاهرة', 'القاهرة'],
+    ['東京', '東京'],
+    ['São 東京', 'sao 東京'],
+  ];
+
+  for (const [input, expected] of cases) {
+    assert.equal(normalizeToponym(input), expected, input);
+  }
+});
+
 test('a biased match that leads with the name is taken without a second request', async () => {
   // The other half of the rule, and the reason bias exists at all: "Sixth
   // Street" over Austin must stay Austin's.

From bc65c274da4418edc80df8d3b4fa3b1ed4bb42aa Mon Sep 17 00:00:00 2001
From: Said Turksever <asturksever@gmail.com>
Date: Thu, 5 Nov 2026 17:13:00 +0000
Subject: [PATCH 43/71] fix(geocode): keep a leading "the" in keyless name
 matching
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

foldPlaceName drops a leading "the", so "The Hague" over upstate New
York accepted Hague, NY as an exact nearby match. Split the script-aware
fold into foldPlaceText and use it for keyless toponyms; foldPlaceName
keeps its behaviour for the packs and street matchers.

Also: changelog fragment credits #1585, folding test pins the Latin
letters NFD does not decompose (ß, ø, ł), and CURRENT-STATE notes that
non-Latin names match only when spelled with their marks.
---
 changelog.d/1585-keyless-unicode-search.md |  2 +-
 docs/CURRENT-STATE.md                      |  5 ++--
 src/data/placeNames.js                     | 28 +++++++++++++++-------
 src/keylessGeocoder.js                     |  4 ++--
 src/keylessGeocoder.test.mjs               | 23 ++++++++++++++++++
 5 files changed, 48 insertions(+), 14 deletions(-)

diff --git a/changelog.d/1585-keyless-unicode-search.md b/changelog.d/1585-keyless-unicode-search.md
index 276ade93f..1f8b3af41 100644
--- a/changelog.d/1585-keyless-unicode-search.md
+++ b/changelog.d/1585-keyless-unicode-search.md
@@ -1,3 +1,3 @@
 - Keep keyless place search on a nearby exact match for names written in
   non-Latin scripts instead of discarding the match and retrying without its
-  proximity ranking (Mert Kaya, @mertkayacs, #PRNUM).
+  proximity ranking (mertkayacs, #1585).
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 45fe2999e..d60b351cc 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5721,8 +5721,9 @@ deadline, with Photon requests capped at six seconds each. Caller/application
 cancellation stops retries and late cache writes. Replacing a location search
 cancels the previous lookup; disposing its controls cancels the active lookup. Photon uses a soft proximity bias, up to five
 candidates, and an unbiased retry for name mismatches. Name comparison folds
-Latin accents while preserving letters and marks in other scripts, so an exact
-non-Latin name keeps its proximity ranking. A "place, region" query prefers a
+Latin accents while preserving letters and marks in other scripts, so a
+non-Latin name spelled exactly, marks included, keeps its proximity ranking. A
+leading "the" counts: "The Hague" does not take a nearby "Hague". A "place, region" query prefers a
 candidate named exactly for the place whose city, county, state,
 country or country code (or USA/UK) contains every word of the region, and a
 settlement or administrative area over a POI when both fit. Nearby results that
diff --git a/src/data/placeNames.js b/src/data/placeNames.js
index 300d09209..90b458dd3 100644
--- a/src/data/placeNames.js
+++ b/src/data/placeNames.js
@@ -11,17 +11,16 @@ const FOLD = {
 };
 
 /**
- * Comparable form of a place name, shared by the bundled packs, the
- * OpenFreeMap street and grounds matchers and the Nominatim server: case
- * folded, accents removed from Latin letters only, punctuation and symbols
- * collapsed to single spaces, and a leading "the" dropped. Other scripts keep
- * their marks, so "कुल मार्ग" and "काली मार्ग" stay distinct while "São Paulo",
- * "sao paulo" and "SÃO PAULO!" meet.
+ * Script-aware fold of a place name: case folded, accents removed from Latin
+ * letters only, punctuation and symbols collapsed to single spaces. Other
+ * scripts keep their marks, so "कुल मार्ग" and "काली मार्ग" stay distinct while
+ * "São Paulo", "sao paulo" and "SÃO PAULO!" meet. Every word is kept: "The
+ * Hague" is not "Hague".
  *
  * @param {unknown} value
  * @returns {string}
  */
-export function foldPlaceName(value) {
+export function foldPlaceText(value) {
   return String(value ?? '')
     .toLowerCase()
     .replace(/[ßøæłđıœþ]/g, (c) => FOLD[c])
@@ -29,8 +28,19 @@ export function foldPlaceName(value) {
     .replace(/(\p{Script=Latin})\p{M}+/gu, '$1')
     .normalize('NFKC')
     .replace(/[^\p{L}\p{M}\p{N}]+/gu, ' ')
-    .trim()
-    .replace(/^the /, '');
+    .trim();
+}
+
+/**
+ * Comparable form of a place name, shared by the bundled packs, the
+ * OpenFreeMap street and grounds matchers and the Nominatim server:
+ * `foldPlaceText` with a leading "the" dropped.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function foldPlaceName(value) {
+  return foldPlaceText(value).replace(/^the /, '');
 }
 
 /**
diff --git a/src/keylessGeocoder.js b/src/keylessGeocoder.js
index eb881f970..3a5cd0035 100644
--- a/src/keylessGeocoder.js
+++ b/src/keylessGeocoder.js
@@ -1,4 +1,4 @@
-import { foldPlaceName } from './data/placeNames.js';
+import { foldPlaceText } from './data/placeNames.js';
 
 /** Photon/OpenStreetMap place-search adapter. */
 const PHOTON_ENDPOINT = 'https://photon.komoot.io/api/';
@@ -243,7 +243,7 @@ export function photonSearchUrl(
  * @returns {string}
  */
 export function normalizeToponym(text) {
-  return foldPlaceName(text);
+  return foldPlaceText(text);
 }
 
 /**
diff --git a/src/keylessGeocoder.test.mjs b/src/keylessGeocoder.test.mjs
index e4c762f62..7f50ebc2e 100644
--- a/src/keylessGeocoder.test.mjs
+++ b/src/keylessGeocoder.test.mjs
@@ -229,6 +229,7 @@ const HUE = {
     extent: [107.3763, 16.7739, 108.0518, 16.1276],
   },
 };
+
 /** Answers biased requests with `nearby`, unbiased ones with `anywhere`. */
 function photonPair(nearby, anywhere) {
   const urls = [];
@@ -277,6 +278,10 @@ test('toponym folding preserves non-Latin scripts', () => {
     ['القاهرة', 'القاهرة'],
     ['東京', '東京'],
     ['São 東京', 'sao 東京'],
+    ['Straße', 'strasse'],
+    ['Tromsø', 'tromso'],
+    ['Łódź', 'lodz'],
+    ['The Hague', 'the hague'],
   ];
 
   for (const [input, expected] of cases) {
@@ -284,6 +289,24 @@ test('toponym folding preserves non-Latin scripts', () => {
   }
 });
 
+test('a leading "the" is part of the name a nearby match must equal', async () => {
+  // "The Hague" over upstate New York means the Dutch city, not Hague, NY.
+  const hagueNy = {
+    geometry: { type: 'Point', coordinates: [-73.5004, 43.6967] },
+    properties: { osm_key: 'place', osm_value: 'town', type: 'city', name: 'Hague', country: 'United States' },
+  };
+  const theHague = {
+    geometry: { type: 'Point', coordinates: [4.3113, 52.0799] },
+    properties: { osm_key: 'place', osm_value: 'city', type: 'city', name: 'The Hague', country: 'Nederland' },
+  };
+  const fetchImpl = photonPair([hagueNy], [theHague]);
+
+  const result = await geocodeKeyless('The Hague', { bias: '43.65,-73.55|43.75,-73.45', fetchImpl });
+
+  assert.equal(Math.round(result.lat), 52, `got ${result.label}`);
+  assert.equal(fetchImpl.urls.length, 2);
+});
+
 test('a biased match that leads with the name is taken without a second request', async () => {
   // The other half of the rule, and the reason bias exists at all: "Sixth
   // Street" over Austin must stay Austin's.

From b5cef8daf4c3518340cd8d76fc1e318308a1b818 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Thu, 5 Nov 2026 21:29:21 +0400
Subject: [PATCH 44/71] Tighten the Rio comments, notes and credits

Name each Rio feed in its credit instead of repeating the licence, drop the
deprecation history from the bus note, list Rio among the feeds with a
route-name table, and shorten the route-table header and test comments.
---
 DATA_SOURCES.md                |  4 ++--
 src/data/rioRouteNames.js      | 20 +++++---------------
 src/data/transitFeeds.js       | 13 +++++++------
 src/data/transitFeeds.test.mjs |  7 ++-----
 src/data/transitProxy.test.mjs |  3 +--
 5 files changed, 17 insertions(+), 30 deletions(-)

diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md
index eb20f793e..ed0895b0a 100644
--- a/DATA_SOURCES.md
+++ b/DATA_SOURCES.md
@@ -98,7 +98,7 @@ How to read this:
 | **Barrie Transit** (myridebarrie.ca) | Transit layer live vehicles, Barrie ON | Barrie Transit realtime data, published by the City of Barrie under a licence accepted by use of the data. The licence is revocable and requires no attribution. | Courtesy credit to the City of Barrie (the licence requires none, and its trademark clause is broad) |
 | **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. Route ids are internal keys and are joined to the line names in SMTR’s published GTFS `routes.txt` (dados.mobilidade.rio/gtfs/schedule), under the same CC BY 4.0 terms. | Attribution to SMTR / Prefeitura da Cidade do Rio de Janeiro under CC BY 4.0 |
+| **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 |
 | **Radio Browser**                                                     | Geolocated internet-radio station directory and station-level tags                                                                  | Public-domain directory data under PDDL 1.0; individual broadcaster stream terms apply                                                                                                                                                                                                                                                                | "Radio Browser" plus a link to the selected broadcaster                                                                                     |
 | **Re:Earth Terrain** (Mapterhorn)                                     | Terrain (keyless globe stacks — OSM etc. — + `/api/terrain/heights` ellipsoidal-height lookups)                                     | Terrain mesh: CC BY 4.0; geoid: EGM2008 (NGA, public domain)                                                                                                                                                                                                                                                                                          | "Terrain (keyless globe stacks): Re:Earth Terrain / Mapterhorn (CC BY 4.0) / EGM2008 (NGA)"                                                 |
 | **OpenSeaMap** (`tiles.openseamap.org`) | Sea Marks layer: raster overlay of buoys, lighthouses and ports (#10) | Chart tiles CC BY-SA 2.0; data ODbL 1.0 via OpenStreetMap | "Sea marks © OpenSeaMap contributors (CC BY-SA 2.0) · Data © OpenStreetMap contributors (ODbL)" |
@@ -186,7 +186,7 @@ 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/<id>.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<N>.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 eighteen registered feeds, covering seventeen 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 and YRT 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 eighteen registered feeds, covering seventeen 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.
 - **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.
diff --git a/src/data/rioRouteNames.js b/src/data/rioRouteNames.js
index 68a7da7a8..1341f873a 100644
--- a/src/data/rioRouteNames.js
+++ b/src/data/rioRouteNames.js
@@ -1,21 +1,11 @@
-// src/data/rioRouteNames.js
 /**
  * Rio de Janeiro route ids to the line a rider would say.
  *
- * SMTR's realtime feeds publish internal route keys: the bus feed sends
- * `O0868AAA0A` for line 868 and `O0731AAN0A` for SN731, and the BRT feed
- * sends `20000501110` for line 50. The keys look decodable but are not:
- * `O0014AAA0A` is LECD135, not 14, and nineteen of the plain-looking keys in
- * the published table break the pattern. The join is the only correct route.
- *
- * Generated verbatim (`route_id` to `route_short_name`, 494 routes) from
- * `routes.txt` in SMTR's static GTFS, https://dados.mobilidade.rio/gtfs/schedule
- * (CC BY 4.0, the same publisher and terms as the realtime feeds; file dated
- * 2026-06-10, feed valid 2024-01-01 to 2026-12-31). A 2026-11-04 snapshot of
- * both realtime feeds, 282 bus and 21 BRT routes in service, found every one
- * of its route ids here. An id missing from this table falls through
- * unchanged, so a route added later degrades to its raw key rather than
- * disappearing.
+ * SMTR's realtime feeds send internal keys (`O0731AAN0A` is SN731,
+ * `20000501110` is BRT line 50). They look decodable but are not:
+ * `O0014AAA0A` is LECD135, not 14. The table is copied from `routes.txt` in
+ * SMTR's static GTFS (https://dados.mobilidade.rio/gtfs/schedule, CC BY 4.0),
+ * valid to 2026-12-31. An id missing here renders as its raw key.
  */
 export const RIO_ROUTE_NAMES = Object.freeze({
   20000101130: '10',
diff --git a/src/data/transitFeeds.js b/src/data/transitFeeds.js
index aa953c00b..48ca450a1 100644
--- a/src/data/transitFeeds.js
+++ b/src/data/transitFeeds.js
@@ -378,8 +378,8 @@ function burlingtonRouteLabel(routeId) {
 }
 
 /**
- * Rio route key to the line a rider would say, for both SMTR feeds: one
- * published `routes.txt` covers the buses and the BRT (see rioRouteNames.js).
+ * Rio route key to the line a rider would say. One SMTR `routes.txt` covers
+ * both feeds (see rioRouteNames.js).
  * @param {string|null} routeId
  * @returns {string|null}
  */
@@ -755,12 +755,12 @@ export const TRANSIT_FEED_REGISTRY = Object.freeze([
     license: 'CC BY 4.0',
     licenseUrl:
       'https://www.data.rio/documents/997bc16cc4344a5cb0e48ab06cbdfd1f',
-    attribution: 'SMTR / Prefeitura da Cidade do Rio de Janeiro (CC BY 4.0)',
+    attribution: 'SMTR / Prefeitura da Cidade do Rio de Janeiro — buses (SPPO)',
     defaultEnabled: true,
     terms: Object.freeze({
       quote:
         'This work is licensed under a Creative Commons Attribution 4.0 International License',
-      note: 'The data.rio catalog page labels the feed [beta] and states a gateway limit of 5 requests a second and 60 a minute behind a 10-second cache, which the 15-second proxy TTL stays inside. It is the named replacement for the JSON GPS endpoints SMTR deprecated on 2026-10-07 and says it will switch off by 2026-11-30. SMTR relays the concessionaires’ ITS data and repairs trips with its own matching; the page places accuracy with the suppliers. Speeds are m/s, as the spec requires: on 2026-11-05 they matched how far vehicles moved between reports, though a 2026-10-29 snapshot read as km/h. Route ids are internal keys (`O0731AAN0A` is line SN731) and are joined to the line names in SMTR’s published GTFS `routes.txt`, under the same CC BY 4.0 terms.',
+      note: 'The data.rio catalog page labels the feed [beta] and states a gateway limit of 5 requests a second and 60 a minute behind a 10-second cache, which the 15-second proxy TTL stays inside. SMTR relays the concessionaires’ ITS data and repairs trips with its own matching; the page places accuracy with the suppliers. Speeds are m/s, as the spec requires: checked against vehicle movement on 2026-11-05, though a 2026-10-29 snapshot read as km/h. Line names come from SMTR’s GTFS `routes.txt`, under the same CC BY 4.0 terms.',
     }),
     defaultMode: 'bus',
     routeLabel: rioRouteLabel,
@@ -777,12 +777,13 @@ export const TRANSIT_FEED_REGISTRY = Object.freeze([
     license: 'CC BY 4.0',
     licenseUrl:
       'https://www.data.rio/documents/8bb196cc02174d25b77437bb2f6443d4',
-    attribution: 'SMTR / Prefeitura da Cidade do Rio de Janeiro (CC BY 4.0)',
+    attribution:
+      'SMTR / Prefeitura da Cidade do Rio de Janeiro — BRT (Mobi-Rio)',
     defaultEnabled: true,
     terms: Object.freeze({
       quote:
         'This work is licensed under a Creative Commons Attribution 4.0 International License',
-      note: 'Same catalog terms, [beta] label and gateway limits as the bus feed. The fleet is operated by Mobi-Rio and tracked by SONDA, whose data SMTR relays. Speeds are m/s here too. Route ids are opaque (`20000501110` is line 50) and are joined to the same `routes.txt` as the buses.',
+      note: 'Same catalog terms, [beta] label and gateway limits as the bus feed. The fleet is operated by Mobi-Rio and tracked by SONDA, whose data SMTR relays. Speeds are m/s too. Line names come from the same `routes.txt`.',
     }),
     defaultMode: 'bus',
     routeLabel: rioRouteLabel,
diff --git a/src/data/transitFeeds.test.mjs b/src/data/transitFeeds.test.mjs
index dbae35c24..d6dc93eb6 100644
--- a/src/data/transitFeeds.test.mjs
+++ b/src/data/transitFeeds.test.mjs
@@ -506,9 +506,7 @@ test('Rio buses and BRT cover the city from Centro to Santa Cruz, and not São P
 });
 
 test('Rio route keys read as the line on the front of the bus', () => {
-  // SMTR publishes internal keys. Plain keys carry the number (`O0868AAA0A`
-  // is 868), variants carry a prefix (`O0731AAN0A` is SN731), and some plain
-  // keys are traps: `O0014AAA0A` is LECD135, so the table is joined, not parsed.
+  // Some keys look parseable and are not (`O0014AAA0A` is LECD135).
   const buses = getTransitFeed('smtr-rio-onibus');
   assert.equal(transitRouteLabel(buses, 'O0868AAA0A'), '868');
   assert.equal(transitRouteLabel(buses, 'O0731AAN0A'), 'SN731');
@@ -518,8 +516,7 @@ test('Rio route keys read as the line on the front of the bus', () => {
   const brt = getTransitFeed('smtr-rio-brt');
   assert.equal(transitRouteLabel(brt, '20000501110'), '50');
   assert.equal(transitRouteLabel(brt, '20000EXEC1110'), 'ESP01');
-  // A route added after the table was built keeps its raw key, never a blank
-  // or a name borrowed from the prototype chain.
+  // Unknown ids, prototype names included, keep their raw key.
   assert.equal(transitRouteLabel(buses, 'O9999AAA0A'), 'O9999AAA0A');
   assert.equal(transitRouteLabel(buses, 'constructor'), 'constructor');
   assert.equal(transitRouteLabel(brt, null), null);
diff --git a/src/data/transitProxy.test.mjs b/src/data/transitProxy.test.mjs
index 07911a939..f03ea2e30 100644
--- a/src/data/transitProxy.test.mjs
+++ b/src/data/transitProxy.test.mjs
@@ -286,8 +286,7 @@ test('the snapshot builder fills timestamps from the header it decoded', () => {
 });
 
 test('Rio speeds pass through as the m/s they are published in', () => {
-  // SMTR publishes m/s, as the spec requires: checked against how far
-  // vehicles moved between reports on 2026-11-05.
+  // Checked against vehicle movement on 2026-11-05.
   const bytes = encodeFeed({
     entities: [{ id: 'moving', lat: -22.9, lon: -43.2, speed: 10 }],
   });

From 067383fda80b7bbc66bf792275433df771910426 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Thu, 5 Nov 2026 21:42:22 +0400
Subject: [PATCH 45/71] fix(datacenters): drop the redundant seen set and test
 skipped against exports

The merge test now passes an exported newly tagged feature, so removing
'- set(fresh)' from the skipped report fails it.
---
 scripts/build-datacenters-norway.py        | 5 ++---
 src/data/datacentersNorwayRefresh.test.mjs | 7 ++++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/scripts/build-datacenters-norway.py b/scripts/build-datacenters-norway.py
index d1203f38d..3c5eb92dd 100644
--- a/scripts/build-datacenters-norway.py
+++ b/scripts/build-datacenters-norway.py
@@ -182,7 +182,7 @@ def feature_line(key, sequence, fresh):
 
 
 def merge(lines, fresh, rings, tagged):
-    out, seen, known, sequence = [], set(), set(), 0
+    out, known, sequence = [], set(), 0
     report = {'kept': 0, 'updated': [], 'removed': [], 'added': [], 'unexported': [], 'skipped': []}
     for line in lines:
         feature = json.loads(line)
@@ -190,7 +190,6 @@ def merge(lines, fresh, rings, tagged):
         key = osm_key(feature)
         known.add(key)
         if key in fresh:
-            seen.add(key)
             old_tags = feature['properties']['tags']
             if old_tags == fresh[key]['tags'] and same_geometry(feature['geometry'], fresh[key]['geometry']):
                 out.append(line)
@@ -208,7 +207,7 @@ def merge(lines, fresh, rings, tagged):
             report['removed'].append(key)
             continue
         out.append(line)
-    for key in sorted(set(fresh) - seen, key=lambda k: (k[0], int(k[1:]))):
+    for key in sorted(set(fresh) - known, key=lambda k: (k[0], int(k[1:]))):
         sequence += 1
         out.append(feature_line(key, sequence, fresh[key]))
         report['added'].append(key)
diff --git a/src/data/datacentersNorwayRefresh.test.mjs b/src/data/datacentersNorwayRefresh.test.mjs
index 88527295b..99278769e 100644
--- a/src/data/datacentersNorwayRefresh.test.mjs
+++ b/src/data/datacentersNorwayRefresh.test.mjs
@@ -52,10 +52,11 @@ def line(osm_id, sequence):
                                       'type': 'data_center', 'osm_id': osm_id}})
 norway = [([(0, 0), (20, 0), (20, 80), (0, 80)], False)]
 lines = [line(7, 1), line(8, 2)]
-out, report = merge(lines, {}, norway, {'w7', 'w12'})
-assert out == [lines[0]], out
+fresh = {'w13': {'geometry': {'type': 'Polygon', 'coordinates': square}, 'tags': {'building': 'data_center'}}}
+out, report = merge(lines, fresh, norway, {'w7', 'w12', 'w13'})
+assert out[0] == lines[0] and len(out) == 2, out
 assert report['unexported'] == ['w7'] and report['removed'] == ['w8'], report
-assert report['skipped'] == ['w12'] and report['added'] == [], report
+assert report['skipped'] == ['w12'] and report['added'] == ['w13'], report
 `,
   );
 });

From 14f88b3e08f61f5b069660dd593471544d3c93db Mon Sep 17 00:00:00 2001
From: Yehe Liu <yxl448@case.edu>
Date: Thu, 5 Nov 2026 16:07:16 -0500
Subject: [PATCH 46/71] feat: Wildlife Sightings layer from iNaturalist and
 Acartia

Recent community wildlife observations, as a new Wildlife group in the
layer panel.

- Server: keyless iNaturalist proxy (v2 observations with only the
  projected fields; undocumented v1 UTFGrid density tiles, decoded on the
  server) sharing one paced queue (burst 4, ~1/s, 60/min, 8,000/day budget,
  up to four in flight), in-memory caches and upstream-only cooldowns;
  Acartia Salish Sea marine-mammal feed rounded to 0.01 degrees with
  comments dropped.
- Layer: grid counts drawn as a soft view-ranked density glow; real sampled
  sightings as taxon badges at their true positions with ambient photo
  thumbnails and labels; obscured records stay privacy cells; a clicked
  sighting stays pinned through camera moves and refreshes.
- Anchored photo card per selection with the single iNaturalist link;
  attribution in the layer row and the Data attribution popover.
- Filters (CONFIRMED, taxa presets) round-trip in share links with token 9.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 DATA_SOURCES.md                               |    5 +
 README.md                                     |    3 +-
 SECURITY.md                                   |    2 +-
 changelog.d/0000-wildlife-sightings.md        |   12 +
 docs/CURRENT-STATE.md                         |   90 +
 docs/KNOWN-ISSUES.md                          |   16 +
 index.html                                    |    2 +-
 package.json                                  |    7 +-
 scripts/format-scope.json                     |   86 +-
 scripts/package-boundaries.json               |  157 +-
 scripts/run-perf-tests.mjs                    |   59 +
 server/providers/acartia.js                   |  179 ++
 server/providers/acartia.test.mjs             |  381 +++
 server/providers/common/userAgent.js          |    4 +
 server/providers/inaturalist/client.js        |  370 +++
 server/providers/inaturalist/client.test.mjs  |  163 ++
 server/providers/inaturalist/grid.fixture.mjs |   51 +
 server/providers/inaturalist/grid.js          |  127 +
 server/providers/inaturalist/grid.test.mjs    |  374 +++
 server/providers/inaturalist/observations.js  |  343 +++
 .../inaturalist/observations.test.mjs         |  893 +++++++
 .../providers/inaturalist/proxy.fixture.mjs   |   70 +
 server/providers/inaturalist/queue.js         |  109 +
 server/providers/inaturalist/queue.test.mjs   |  111 +
 server/providers/inaturalist/speed.test.mjs   |  218 ++
 server/providers/local.js                     |    4 +
 src/app/catalog.js                            |    1 +
 src/app/catalog.test.mjs                      |    2 +
 src/app/constructCatalog.js                   |    5 +
 src/app/constructCatalog.test.mjs             |    4 +-
 src/app/layers/wildlifeSightings.js           |   30 +
 src/app/sourceComposition.js                  |    1 +
 src/app/sourceComposition.test.mjs            |    2 +-
 src/data/dataCredits.js                       |   12 +
 src/data/layerState.js                        |   23 +
 src/data/layerState.test.mjs                  |   41 +-
 src/data/layerStateTokenLedger.test.mjs       |   40 +-
 src/data/layerStateTokenReservations.json     |    1 +
 src/data/spriteOrder.js                       |    1 +
 src/i18n/locales/ar.json                      |   59 +-
 src/i18n/locales/de.json                      |   59 +-
 src/i18n/locales/es.json                      |   59 +-
 src/i18n/locales/fr.json                      |   59 +-
 src/i18n/locales/it.json                      |   59 +-
 src/i18n/locales/ja.json                      |   59 +-
 src/i18n/locales/pt.json                      |   59 +-
 src/i18n/locales/ru.json                      |   59 +-
 src/i18n/locales/uk.json                      |   59 +-
 src/i18n/locales/zh-CN.json                   |   59 +-
 src/i18n/locales/zh-Hant.json                 |   59 +-
 src/i18n/same-as-english.json                 |   76 +-
 src/layers/wildlifeSightings/acartiaTaxa.js   |  155 ++
 .../wildlifeSightings/acartiaTaxa.test.mjs    |   37 +
 .../wildlifeSightings/acquisition.test.mjs    |  944 +++++++
 .../wildlifeSightings/billboardModel.js       |  114 +
 src/layers/wildlifeSightings/bounds.js        |   51 +
 .../cache.integration.test.mjs                |  111 +
 src/layers/wildlifeSightings/cards.js         |  281 +++
 src/layers/wildlifeSightings/cards.test.mjs   |  627 +++++
 src/layers/wildlifeSightings/controls.js      |  250 ++
 src/layers/wildlifeSightings/density.js       |  462 ++++
 src/layers/wildlifeSightings/density.test.mjs |  508 ++++
 src/layers/wildlifeSightings/docs.test.mjs    |  111 +
 src/layers/wildlifeSightings/gridViewport.js  |  178 ++
 .../wildlifeSightings/gridViewport.test.mjs   |  142 ++
 src/layers/wildlifeSightings/index.js         |  130 +
 src/layers/wildlifeSightings/lifecycle.js     |  804 ++++++
 src/layers/wildlifeSightings/model.js         |  208 ++
 .../wildlifeSightings/model.perf.test.mjs     |   76 +
 src/layers/wildlifeSightings/model.test.mjs   |  162 ++
 .../wildlifeSightings/ownership.test.mjs      | 2224 +++++++++++++++++
 src/layers/wildlifeSightings/performance.js   |  115 +
 .../wildlifeSightings/performance.test.mjs    |  299 +++
 src/layers/wildlifeSightings/photoText.js     |   36 +
 src/layers/wildlifeSightings/photos.js        |  183 ++
 src/layers/wildlifeSightings/photos.test.mjs  |  147 ++
 src/layers/wildlifeSightings/policy.js        |  142 ++
 src/layers/wildlifeSightings/records.js       |  350 +++
 src/layers/wildlifeSightings/records.test.mjs |  542 ++++
 .../wildlifeSightings/render.perf.test.mjs    |  166 ++
 .../renderPerformanceFixtures.mjs             |  185 ++
 src/layers/wildlifeSightings/rendering.js     |  691 +++++
 .../wildlifeSightings/rendering.test.mjs      |  544 ++++
 src/layers/wildlifeSightings/selection.js     |  560 +++++
 .../wildlifeSightings/selection.test.mjs      |  301 +++
 src/layers/wildlifeSightings/source.js        |  557 +++++
 src/layers/wildlifeSightings/source.test.mjs  |  816 ++++++
 src/layers/wildlifeSightings/sprites.js       |  136 +
 src/layers/wildlifeSightings/sprites.test.mjs |  189 ++
 src/layers/wildlifeSightings/viewport.js      |   83 +
 .../wildlifeSightings/viewport.test.mjs       |  136 +
 src/materialSymbolsSubset.test.mjs            |    3 +
 src/navigationPolicy.js                       |    2 +
 src/overlays/wildlifeSightingOverlay.test.mjs |  186 ++
 src/overlays/worldOverlay.js                  |  203 +-
 src/overlays/worldOverlay.test.mjs            |  174 ++
 src/overlays/worldOverlayChrome.js            |   29 +
 src/overlays/worldOverlayDraw.js              |  115 +-
 src/overlays/worldOverlayDraw.test.mjs        |  474 +++-
 src/perfTestRunner.test.mjs                   |   81 +
 src/share/viewCodec.js                        |    1 +
 src/sources/rateLimit.js                      |   19 +-
 src/sources/rateLimit.test.mjs                |   23 +
 src/sources/reference.js                      |    2 +
 src/sources/reference.test.mjs                |    3 +
 src/testSupport/wildlifeBillboardModel.mjs    |   82 +
 src/tooling/previewServing.test.mjs           |    4 +
 src/tooling/transitQa.test.mjs                |    2 +-
 src/ui/applicationShell.js                    |   16 +
 src/ui/layerNames.js                          |    1 +
 src/ui/layerPanel.js                          |    4 +
 src/ui/layerPanel.test.mjs                    |   21 +
 src/ui/styles/cyber.css                       |    9 +-
 src/ui/views/panels/WildlifeSightingCard.vue  |  131 +
 src/ui/wildlifeSightingCard.js                |  270 ++
 src/ui/wildlifeSightingCard.test.mjs          |  767 ++++++
 src/ui/wildlifeSightingPlacement.js           |  274 ++
 src/voice/layerManifest.js                    |    4 +-
 src/worldFocus.js                             |    8 +-
 src/worldFocus.test.mjs                       |  160 +-
 120 files changed, 21260 insertions(+), 285 deletions(-)
 create mode 100644 changelog.d/0000-wildlife-sightings.md
 create mode 100644 scripts/run-perf-tests.mjs
 create mode 100644 server/providers/acartia.js
 create mode 100644 server/providers/acartia.test.mjs
 create mode 100644 server/providers/common/userAgent.js
 create mode 100644 server/providers/inaturalist/client.js
 create mode 100644 server/providers/inaturalist/client.test.mjs
 create mode 100644 server/providers/inaturalist/grid.fixture.mjs
 create mode 100644 server/providers/inaturalist/grid.js
 create mode 100644 server/providers/inaturalist/grid.test.mjs
 create mode 100644 server/providers/inaturalist/observations.js
 create mode 100644 server/providers/inaturalist/observations.test.mjs
 create mode 100644 server/providers/inaturalist/proxy.fixture.mjs
 create mode 100644 server/providers/inaturalist/queue.js
 create mode 100644 server/providers/inaturalist/queue.test.mjs
 create mode 100644 server/providers/inaturalist/speed.test.mjs
 create mode 100644 src/app/layers/wildlifeSightings.js
 create mode 100644 src/layers/wildlifeSightings/acartiaTaxa.js
 create mode 100644 src/layers/wildlifeSightings/acartiaTaxa.test.mjs
 create mode 100644 src/layers/wildlifeSightings/acquisition.test.mjs
 create mode 100644 src/layers/wildlifeSightings/billboardModel.js
 create mode 100644 src/layers/wildlifeSightings/bounds.js
 create mode 100644 src/layers/wildlifeSightings/cache.integration.test.mjs
 create mode 100644 src/layers/wildlifeSightings/cards.js
 create mode 100644 src/layers/wildlifeSightings/cards.test.mjs
 create mode 100644 src/layers/wildlifeSightings/controls.js
 create mode 100644 src/layers/wildlifeSightings/density.js
 create mode 100644 src/layers/wildlifeSightings/density.test.mjs
 create mode 100644 src/layers/wildlifeSightings/docs.test.mjs
 create mode 100644 src/layers/wildlifeSightings/gridViewport.js
 create mode 100644 src/layers/wildlifeSightings/gridViewport.test.mjs
 create mode 100644 src/layers/wildlifeSightings/index.js
 create mode 100644 src/layers/wildlifeSightings/lifecycle.js
 create mode 100644 src/layers/wildlifeSightings/model.js
 create mode 100644 src/layers/wildlifeSightings/model.perf.test.mjs
 create mode 100644 src/layers/wildlifeSightings/model.test.mjs
 create mode 100644 src/layers/wildlifeSightings/ownership.test.mjs
 create mode 100644 src/layers/wildlifeSightings/performance.js
 create mode 100644 src/layers/wildlifeSightings/performance.test.mjs
 create mode 100644 src/layers/wildlifeSightings/photoText.js
 create mode 100644 src/layers/wildlifeSightings/photos.js
 create mode 100644 src/layers/wildlifeSightings/photos.test.mjs
 create mode 100644 src/layers/wildlifeSightings/policy.js
 create mode 100644 src/layers/wildlifeSightings/records.js
 create mode 100644 src/layers/wildlifeSightings/records.test.mjs
 create mode 100644 src/layers/wildlifeSightings/render.perf.test.mjs
 create mode 100644 src/layers/wildlifeSightings/renderPerformanceFixtures.mjs
 create mode 100644 src/layers/wildlifeSightings/rendering.js
 create mode 100644 src/layers/wildlifeSightings/rendering.test.mjs
 create mode 100644 src/layers/wildlifeSightings/selection.js
 create mode 100644 src/layers/wildlifeSightings/selection.test.mjs
 create mode 100644 src/layers/wildlifeSightings/source.js
 create mode 100644 src/layers/wildlifeSightings/source.test.mjs
 create mode 100644 src/layers/wildlifeSightings/sprites.js
 create mode 100644 src/layers/wildlifeSightings/sprites.test.mjs
 create mode 100644 src/layers/wildlifeSightings/viewport.js
 create mode 100644 src/layers/wildlifeSightings/viewport.test.mjs
 create mode 100644 src/overlays/wildlifeSightingOverlay.test.mjs
 create mode 100644 src/overlays/worldOverlayChrome.js
 create mode 100644 src/perfTestRunner.test.mjs
 create mode 100644 src/sources/rateLimit.test.mjs
 create mode 100644 src/testSupport/wildlifeBillboardModel.mjs
 create mode 100644 src/ui/views/panels/WildlifeSightingCard.vue
 create mode 100644 src/ui/wildlifeSightingCard.js
 create mode 100644 src/ui/wildlifeSightingCard.test.mjs
 create mode 100644 src/ui/wildlifeSightingPlacement.js

diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md
index ed0895b0a..1153015b8 100644
--- a/DATA_SOURCES.md
+++ b/DATA_SOURCES.md
@@ -41,6 +41,8 @@ How to read this:
 | **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 |
 | **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)" |
+| **Acartia** (`acartia.io/api/v1/sightings/current`) | Wildlife Sightings layer: Salish Sea marine mammal reports with validated species, observation time, reporting provider and trust flag; WHALES includes only the frozen cetacean list | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), each provider credited per sighting. Keyless via `/api/acartia/sightings` (10-min cache; stale ≤ 24 h). Positions rounded to 0.01° on the server; free-text comments excluded. Marine-conservation use; Be Whale Wise | "Wildlife sightings: Acartia (CC BY 4.0; each provider credited per sighting) · Be Whale Wise" |
 | **OpenFreeMap / OpenMapTiles** | Vector tiles | OpenStreetMap data under ODbL 1.0 | OpenFreeMap © OpenMapTiles |
 | **Overture Maps Foundation** | Military area names pack | [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/) | Overture Maps Foundation |
 | **TomTom Traffic API** (flow vector tiles)                            | Traffic roads and live congestion (optional, BYOK)                                                                     | [TomTom for Developers terms](https://docs.tomtom.com/legal/terms-and-conditions) (proprietary, your own key; free tier currently 200K tile requests/month — see [current pricing](https://docs.tomtom.com/pricing/))                                                                                                                                                       | "Traffic flow data © TomTom" — registered when live mode activates                                                                          |
@@ -195,6 +197,9 @@ The optional Local ADS-B layer and the broadcast-FM receiver use radio you recei
 - **Re:Earth Terrain.** Keyless (no API key). Used two ways: (1) `src/mapStackController.js` swaps in a `Cesium.CesiumTerrainProvider` pointed at Re:Earth's `cesium-mesh/ellipsoid` quantized-mesh endpoint for globe stacks without a Cesium ion token (e.g. OSM), replacing a flat `EllipsoidTerrainProvider`; falls back to the flat provider if the endpoint can't be reached. (2) The server-side `/api/terrain/heights` proxy (disk-cached, serve-stale) resolves per-point ellipsoidal ground height for entity placement. Both are best-effort with a keyless-safe fallback (bundled EGM96 geoid math) if Re:Earth is unreachable.
 - **OSRM on the FOSSGIS routing servers.** Keyless (no API key). Every route is requested by a person: clicking A and B in the Directions layer, or a voice "route from A to B". The server-side `/api/route` proxy sends an identifying `User-Agent`, pins the upstream host, accepts 2-12 coordinates, rejects any leg over 600 km or a total over 2,500 km, caps the buffered response at 8 MB, times the upstream out at 12 s, rate-limits per client, caches each route for 10 minutes, and coalesces identical requests that are in flight at the same time. Turn-by-turn maneuvers are asked for only when a caller wants them (`steps=1`), so the callers that do not read them send the smaller request. The "fix the map" link the policy asks for is in the Data attribution popover beside the OpenStreetMap credit.
 - **FAA Special Use Airspace.** Keyless. `/api/drone-airspace` queries the public FAA AIS FeatureServer for prohibited (P) and restricted (R) zones only — not MOAs, TFRs or other SUA types — with simplified geometry, a body cap, paging, a one-hour cache and stale-on-error. The layer is US coverage, informational only, and is not a substitute for B4UFLY, LAANC or a preflight briefing. Data is fetched at request time and never stored or redistributed. US government public domain; courtesy attribution is registered in the Data attribution popover.
+- **iNaturalist.** Keyless. `/api/inaturalist/observations` returns cached random view samples (newest first globally), at most 200 per request. Recency uses observation time: the v1 `d1` filter and a rolling 48 h cutoff (whales 7 d); date-only rows qualify when their day starts within the window. Observation caches last 5 min (global 10 min), with stale fallback ≤1 h. `/api/inaturalist/grid` supplies density counts, cached 15 min. Both share a paced queue capped at 60/min and 8,000/day; only request counters persist in `.gev-cache/`. The server caches projected records, never raw responses. Private records are excluded; obscured coordinates become 0.2° cells. Observer identity is retained only for photo attribution. Eligible photos load directly from `inaturalist-open-data.s3.amazonaws.com`, with creator credit on ambient cards and creator/licence on selection. Per-record licences and noncommercial restrictions apply as listed above. Attribution appears in the layer row and Data attribution popover. Coverage follows community observations, not a census; Acartia adds Salish Sea marine mammals.
+- **iNaturalist grid (undocumented endpoint risk).** `/api/inaturalist/grid` shares observation-date, taxa, quality, pacing and budget rules with observations. A strict 64×64 UTFGrid schema guard fails closed; only logical-cell keys, counts and coordinates survive projection. Raw tiles, observation identifiers and free text are not retained. Projected tiles use a 400-entry LRU, 15-minute freshness and at most one hour of stale fallback. Views request at most six tiles; cached and adjacent-zoom coverage publishes before network waits, independently of observation pages. Cells supply a noninteractive density glow ranked within the view, from teal to amber with mono/CRT support. Every sighting badge comes from a real observation at its public position. Counts describe observations, not a population census. The endpoint is outside the documented v1 contract; schema drift disables grids until revalidated. See `docs/KNOWN-ISSUES.md`.
+- **Acartia.** Keyless. `/api/acartia/sightings` reads the current 7-day marine-mammal feed for ALL, MAMMALS and WHALES views intersecting 45.5–50.5° N, 126–121° W in the Salish Sea. WHALES accepts recognized cetaceans; other identified marine mammals appear under ALL/MAMMALS. The server rounds positions to 0.01° and drops comments before caching projected records (10 min fresh, stale ≤24 h); raw responses are not retained. Selected text cards credit the reporting provider under CC BY 4.0 and show Be Whale Wise guidance. Attribution also appears in the layer row and Data attribution popover. Opportunistic sightings, not a census.
 - **Mapped installations.** OpenFreeMap military polygons use a bundled Overture/OSM name index; wide views show named points. Optional operator-configured Overpass and explicit Google Places searches keep their own source paths. Mapped data does not establish current activity or complete coverage.
 - **Place search.** Named-place fly-to uses Google Geocoding when a Maps key is configured, then Photon (`PHOTON_URL`; unset uses the public instance, empty disables it), then `/api/geocode` (Nominatim search) when neither answers. `/api/geocode` and the voice outline route `/api/geocode/outline` share one Nominatim queue (`NOMINATIM_URL`; unset, empty and invalid values disable it; an operator must explicitly select an authorized endpoint): one request at a time at least 1.1 s apart, an identifying `User-Agent` and `Referer`, a short queue that refuses a burst, a pause after 429/403/5xx answers (honouring `Retry-After` in full), at most one retry after a network failure, and a per-install daily cap on public-instance requests (`NOMINATIM_DAILY_CAP`, default 50). Processes using the same installation state file hold one lock through the actual fetch invocation and recording the next public start, with the daily slot persisted before invocation; restarts share that count, spacing and any pause. An unfinished dispatch marker fails closed until operator recovery; it is never automatically reclaimed. Public access fails closed if the state file cannot be read, locked, written or semantically validated. This coordination does not span independent installations or state directories and does not establish an application-wide public-service allowance or authorize public use. An operator-selected non-public endpoint is outside the public cap, spacing and durable-state requirement; an upstream cooldown is kept with the endpoint that returned it rather than leaking across operator URLs. Answers are cached on disk (outlines 90 days, places 30 days, no-results 24 hours); failures are not cached. Outlines are looked up only for an explicit ask, after bundled data and any configured Overpass, and only results whose type suits the ask are used. Administrative outline responses expose country/admin-1/admin-2 identity only when the selected Nominatim row has a recognized, unambiguous address type consistent with its own name; numeric rank, ambiguous types, missing fields and contradictory names do not manufacture identity. It is not used for systematic or bulk queries.
 - **Street and building outlines.** Voice street highlights, pointed-at buildings and grounds use the OpenFreeMap vector tiles the traffic layer already loads. Traffic and outlines share one bounded pending fetch/decode owner per immutable XYZ tile; materialized outline geometry is charged to the retained-byte ceiling and capped by coordinate count. Consumer result caches and request lifetimes remain independent, while eviction or explicit teardown cancels queued idle projections and releases their decoded owner. No Overpass request is made unless `OVERPASS_UPSTREAMS` is configured. Named grounds require a returned name matching the selected place, except that an ask whose head noun names a kind of grounds (a school, university or college, hospital, cemetery, stadium or zoo) may use the part of the smallest unnamed tile area of that class that holds the resolved place; a differently named area never answers. Other anonymous landcover polygons cannot establish identity, so unsupported grounds stay unavailable rather than borrowing a nearby POI name.
diff --git a/README.md b/README.md
index 6212f3991..bce41b190 100644
--- a/README.md
+++ b/README.md
@@ -426,7 +426,7 @@ _Ask for radio near anywhere and the globe starts broadcasting — every station
 
 ## 🛰️ What's on the Globe
 
-Twenty-one layers and map sources. **Nineteen have a keyless path.** Some offer additional capabilities with a provider key. (🟢 no key · 🟡 free key · 🔴 metered.)
+Twenty-two layers and map sources. **Twenty have a keyless path.** Some offer additional capabilities with a provider key. (🟢 no key · 🟡 free key · 🔴 metered.)
 
 | Layer                       | What you get                                                                                                                                                                                                                                                                                                                                                                        | Source                                  | Auth                                                                                                |
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- |
@@ -452,6 +452,7 @@ Twenty-one layers and map sources. **Nineteen have a keyless path.** Some offer
 | 🚀 **Space Missions**       | Rolling 30-day launches with payload, stage, and recovery detail                                                                                                                                                                                                                                                                                                                    | Launch Library 2                        | 🟢 (🔴 optional paid token raises the allowance)                                                         |
 | 🎖️ **Mapped Installations** | Viewport-bounded military-site context from community mapping — incomplete by nature, and labeled that way                                                                                                                                                                                                                                                                          | OpenStreetMap                           | 🟢                                                                                                  |
 | 🚫 **Prohibited & Restricted Airspace** | FAA prohibited (P) and restricted (R) special-use airspace as ground polygons, with name, altitude range and times of use on select. Not the UAS Facility Map or UAS flight restrictions; informational only, not for flight planning | FAA SUA                                 | 🟢                                                                                                  |
+| 🦉 **Wildlife Sightings** | Wildlife observed within 48 h (whales 7 d): density glow, taxon badges and anchored photo cards with creator/licence credit. Salish Sea marine mammals via Acartia; sensitive locations shown as 0.2° cells. Not a census | iNaturalist, Acartia | 🟢 |
 | 🌬️ **Wind**                 | Animated 10 m forecast wind with an optional speed, temperature or pressure color field and a reading at map center                                                                                                                                                                                                                                                                 | NOAA GFS / ECMWF IFS                    | 🟢                                                                                                  |
 | 🌦️ **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                         | 🟢                                                                                                  |
diff --git a/SECURITY.md b/SECURITY.md
index 4dceaed6f..7b894c346 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -81,7 +81,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 `<img>`/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/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, 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 `<img>`/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 `<style>` elements.
 
 Allowing `maps.googleapis.com` in `script-src` also trusts its JSONP endpoints, which can bypass the script allowlist if an HTML-injection bug exists; this is an accepted limitation of loading the Maps JavaScript API, alongside the existing `'unsafe-eval'` allowance.
diff --git a/changelog.d/0000-wildlife-sightings.md b/changelog.d/0000-wildlife-sightings.md
new file mode 100644
index 000000000..75abdd8dd
--- /dev/null
+++ b/changelog.d/0000-wildlife-sightings.md
@@ -0,0 +1,12 @@
+- Add Wildlife Sightings in the Wildlife layer group, off by default, using
+  keyless iNaturalist observations within 48 h (whales 7 d) and Acartia Salish
+  Sea marine mammals. CONFIRMED and taxa filters share via token `9`.
+  A noninteractive density glow accompanies real-sighting taxon badges,
+  decluttered species labels and credited ambient photos. Selection stays
+  pinned across camera and sample changes and opens an anchored photo card
+  with a contained image, creator/licence and one iNaturalist source link.
+  Obscured and Acartia sightings use text-only cards; private records and
+  Acartia comments are excluded. Attribution appears in the layer row and
+  Data attribution popover. Cached progressive tiles, bounded image/billboard
+  work and a paced queue preserve iNaturalist's 60/minute and 8,000/day limits.
+  All 11 locales supported. (lyehe, #0000)
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index abfa3fc04..c1ce3af7b 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -98,6 +98,93 @@ 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.
 
+## Wildlife Sightings — iNaturalist and Acartia
+
+**Wildlife Sightings** (`wildlife-sightings`, share-link token `9`) is off by
+default in the Wildlife group between Events and Weather. CONFIRMED and six
+taxa presets round-trip in share links. Voice is off for this layer for now;
+it is outside analyst queries and DETECT. Community observations are not a
+census; private records are excluded.
+
+`/api/inaturalist/observations` requests verifiable wildlife in view within
+48 h (whales 7 d). Recency uses observation time: the `d1` date filter and a
+strict rolling cutoff. Date-only rows qualify only when their day starts
+within the window. Close views use a cached random sample of at most 200 rows;
+global samples use newest observations first. Observation caches last five
+minutes (global ten minutes), with stale fallback for at most one hour.
+
+Observations and grid tiles share a paced priority queue: a four-call burst,
+then one request per second, at most four in flight, ≤60/minute and a persisted
+8,000/day budget. Superseded consumers leave before dispatch. The recovered
+queue tail isolates failures; ordinary grid failures do not fail observations.
+Provider 429 cooldown is shared; 5xx cooldown is resource-specific. Failed tiles
+retain good cells for at most one hour. Stale replies carry `X-Data-Stale` and
+known `Retry-After`. Failures keep filters and drawn rows, reporting DEGRADED
+with retry timing; logs exclude request URLs and upstream exception text.
+
+`/api/acartia/sightings` adds Salish Sea marine mammals within 45.5–50.5° N,
+126–121° W, cached ten minutes and stale for at most 24 h. WHALES accepts only
+recognized cetaceans; other identified marine mammals appear under ALL or
+MAMMALS. Sensitive iNaturalist locations remain 0.2° privacy cells; Acartia
+positions are rounded to 0.01° on the server. Acartia comments are never retained.
+Observer identity is retained only for photo attribution.
+
+`/api/inaturalist/grid` supplies a dedicated, nonpickable billboard density glow,
+with a view-relative density ramp from cool teal to warm amber. Overlapping
+Gaussian splats span four logical cell widths; mono and CRT styles follow map
+and cockpit vision changes. Empty snapshots paint nothing. Full footprints
+stay inside the globe limb with a 5% radius margin; opacity fades from full at
+3,000 km to zero at 8,000 km camera altitude. Culling and cached coordinates
+add no per-frame work and leave sighting counts intact.
+
+Only real sampled observation rows produce taxon badges at their public
+positions. The badges use 28 px screen buckets, a 22 px overlap check and a
+5,000-observation cap. Tinted circles have a white Material Symbols glyph and
+1.5 px dark outline, remaining 12–22 px at all distances, including selection.
+Glyphs: birds `raven`, mammals `pets`, reptiles `egg_alt`, amphibians
+`water_drop`, fishes `set_meal`, insects `bug_report`, arachnids `pest_control`,
+plants `eco`, fungi `umbrella`, other animals `category`, unknown `question_mark`.
+A plain circle displays while the icon font loads. Row counts read
+“{n} sightings in view”, using visible grid totals when available.
+
+Views request at most six tiles, coarsening zoom for complete coverage. Server
+and client keep bounded 400-tile caches for 15 minutes. Cached, stale and
+adjacent-zoom tiles publish before network waits; each arriving tile replaces
+its covered area, including healthy empty tiles. Grid tiles publish even while
+the independent observation request is pending or failed. Enable waits for one
+camera settle; camera acquisition uses moveEnd with a 600 ms debounce. The
+undocumented UTFGrid endpoint has a schema guard; see `KNOWN-ISSUES.md`.
+
+Ambient cards use a fixed 96 px image width and a short creator name credit,
+with a bounded frame cache. New cards fill free screen regions; visible cards
+survive a random sample refresh until they leave the view or observation
+window. The 110/125 km show/hide thresholds provide hysteresis; cards scale
+and fade gradually through 120 km. Only painted photos suppress their own
+badge and label. Labels yield to painted cards, then compete by ambient score;
+repeated translated names within 80 screen pixels yield to higher-priority
+content. At most 150 labels enter the host. Titles prefer a word boundary for
+ellipses; accessible names remain complete. Selected thumbnails or names use
+the shared selected chrome and paint lane, with no canvas source link.
+
+Clicking a badge, label or photo flies to its supplied position and opens a
+compact anchored photo card. Selection stays pinned across camera, filter and
+sample changes until explicit deselection or layer disable. Its medium image
+uses `object-fit: contain`, with names, compact observed age and creator/licence.
+The card is the single source link to iNaturalist. Obscured sightings also stay
+text-only; Acartia stays text-only with provider credit and whale guidance.
+Placement avoids actual HUD, toolbar and rail rectangles, panning only when
+necessary while preserving zoom. Escape, close or an outside click closes the
+card and clears selection. Camera/layout changes reposition the card without
+an idle frame listener; shell teardown also removes its host and subscription.
+
+Attribution appears in the layer row and Data attribution popover:
+“iNaturalist contributors · licences per record”, plus Acartia when drawn.
+Disable/destroy releases the glow collection, texture atlas, timers, queues and
+style listeners. Synthetic fixtures cover privacy, acquisition, rendering,
+selection and card placement. Deterministic operation checks run in `npm test`;
+wall-clock budgets run in `npm run test:perf`. All 11 locales are supported.
+
+
 ## Prohibited & Restricted Airspace — FAA special-use airspace
 
 The Infrastructure group includes **Prohibited & Restricted Airspace** (`drone-airspace`,
@@ -1541,6 +1628,8 @@ are owned by a renderer-free panel component. The layer manager supplies current
 snapshots, lifecycle actions and row descriptors. Remount and teardown remove
 listeners and row subscriptions; obsolete completions do not repaint old rows.
 The clear control presents busy state while its existing action owns the transaction.
+The Wildlife group follows Events and precedes Weather; Wildlife Sightings
+provides its confirmed toggle, taxa presets and fixed-order, nonempty legend.
 
 ## Sky background
 
@@ -4212,6 +4301,7 @@ its criteria cannot be silently ignored.
 | Ski Pistes ⛷ (`ski-pistes`) | OpenSnowMap piste raster tiles (keyless; CC BY-SA tiles, OSM data ODbL; no bulk download) | `src/data/osmOverlays.js` | — (browser-direct tiles) | on view (Cesium tile requests; no polling) |
 | Fire Perimeters 🔥 | NIFC WFIGS current interagency perimeters (keyless, paged past the 2000-record cap); InciWeb catalog + incident page origin and update time checks for verified incident-page links | `src/layers/perimeters/` via `src/app/layers/perimeters.js` | `/api/fire-perimeters` + `/api/fire-perimeters/inciweb/*` | 5 min (server caches: catalog 1 h; publication 30 min) |
 | Prohibited & Restricted Airspace 🚫 | FAA Special Use Airspace prohibited (P) and restricted (R) zones (keyless FeatureServer, simplified geometry) | `src/layers/droneAirspace/` via `src/app/layers/droneAirspace.js` | `/api/drone-airspace` | 1 h (server cache 1 h; stale-on-error) |
+| Wildlife Sightings 🦉 | iNaturalist wildlife observed within 48 h (whales 7 d), per view; Acartia Salish Sea marine mammal coverage (keyless) | `src/layers/wildlifeSightings/` via `src/app/layers/wildlifeSightings.js` | `/api/inaturalist/observations`, `/api/inaturalist/grid`, `/api/acartia/sightings` | camera moveEnd (600 ms debounce; enable settles 300 ms) + 5 min (observations 5 / 10 min; tiles 15 min; stale ≤ 1 h / 24 h) |
 
 GNSS Integrity samples a 250 nm circle around the Earth point under the screen
 centre. Camera reads debounce for 600 ms with a monotonic 2.5 s minimum gap;
diff --git a/docs/KNOWN-ISSUES.md b/docs/KNOWN-ISSUES.md
index 53c7949c6..ccd3ed906 100644
--- a/docs/KNOWN-ISSUES.md
+++ b/docs/KNOWN-ISSUES.md
@@ -10,6 +10,22 @@ For the roadmap and open backlog, see the repository issue tracker.
 
 ## Open
 
+### Wildlife grid is an undocumented iNaturalist endpoint
+
+Status: Open (guarded fallback)
+
+The operational `/v1/grid/{z}/{x}/{y}.grid.json` endpoint is not part of the
+published v1 Swagger contract. Its 64×64 UTFGrid shape, keys and cell records
+are validated in full at the allow-list proxy. A schema change or unavailable
+tile retains its last good cells for at most one hour; a cold unavailable grid
+uses sampled observations with the same badges and screen buckets, without
+claiming complete worldwide coverage. Tests use
+synthetic fixtures with the locally inspected tile's exact structure. Retest
+and update the schema guard before accepting an upstream shape change. Grid
+and observation calls share the paced queue, provider budget and 429 cooldown;
+ordinary tile failures do not block observation queries.
+
+
 ### Street traffic can be slow/uneven when panning across dense city blocks
 Status: Open (partially mitigated)
 
diff --git a/index.html b/index.html
index 614ef389e..72893cf8c 100644
--- a/index.html
+++ b/index.html
@@ -26,7 +26,7 @@
        with the sources: src/materialSymbolsSubset.test.mjs fails when a source
        names a glyph this list is missing, because a missing glyph does not draw
        a box — the ligature never forms and the element renders the literal word. -->
-  <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20,400,0,0&icon_names=adjust,arrow_drop_down,arrow_forward,arrow_left,arrow_right,bolt,chevron_left,chevron_right,close,close_fullscreen,dark_mode,draw,east,flare,flight,handyman,layers,layers_clear,light_mode,local_fire_department,location_on,more_horiz,movie,my_location,navigation,normal,on,open_in_full,partly_cloudy_day,pentagon,public,radar,radio,right_panel_close,right_panel_open,rocket_launch,satellite_alt,search,settings,skip_next,skip_previous,streetview,timeline,tune,upload_file,videocam,view_in_ar,visibility,visibility_off" rel="stylesheet" />
+  <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20,400,0,0&icon_names=adjust,arrow_drop_down,arrow_forward,arrow_left,arrow_right,bolt,bug_report,category,chevron_left,chevron_right,close,close_fullscreen,dark_mode,draw,east,eco,egg_alt,flare,flight,handyman,layers,layers_clear,light_mode,local_fire_department,location_on,more_horiz,movie,my_location,navigation,normal,on,open_in_full,partly_cloudy_day,pentagon,pest_control,pets,public,question_mark,radar,radio,raven,right_panel_close,right_panel_open,rocket_launch,satellite_alt,search,set_meal,settings,skip_next,skip_previous,streetview,timeline,tune,umbrella,upload_file,videocam,view_in_ar,visibility,visibility_off,water_drop" rel="stylesheet" />
 </head>
 <body>
   <div class="gev-view" data-gev-view="scene-chrome"></div>
diff --git a/package.json b/package.json
index 42121974f..ffc554d7b 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
   "name": "gods-eye-view",
   "private": true,
   "version": "0.3.0",
-  "description": "A real-time intelligence console for planet Earth — photorealistic 3D globe, live aircraft/ships/satellites/earthquakes/CCTV, and hands-free voice control. Runs in a browser.",
+  "description": "A real-time intelligence console for planet Earth \u2014 photorealistic 3D globe, live aircraft/ships/satellites/earthquakes/CCTV, and hands-free voice control. Runs in a browser.",
   "type": "module",
   "license": "MIT",
   "author": "Bilawal Sidhu",
@@ -47,6 +47,7 @@
     "build:panel": "node scripts/build-panel.mjs",
     "preview": "vite preview",
     "test": "node scripts/run-unit-tests.mjs",
+    "test:perf": "node scripts/run-perf-tests.mjs",
     "test:track": "node scripts/track-regression.mjs",
     "qa:map-source-tray": "node scripts/qa-map-source-tray.mjs",
     "qa:street-level": "node scripts/qa-street-level.mjs",
@@ -292,6 +293,8 @@
     "./tools/panel": "./src/tools/panel.js",
     "./tools/services": "./src/tools/services.js",
     "./view": "./src/view/index.js",
-    "./agent/world-packet": "./src/agent/worldPacket.js"
+    "./agent/world-packet": "./src/agent/worldPacket.js",
+    "./layers/wildlife-sightings": "./src/layers/wildlifeSightings/index.js",
+    "./layers/wildlife-sightings/source": "./src/layers/wildlifeSightings/source.js"
   }
 }
diff --git a/scripts/format-scope.json b/scripts/format-scope.json
index b390581d0..1b0d1454c 100644
--- a/scripts/format-scope.json
+++ b/scripts/format-scope.json
@@ -1268,5 +1268,89 @@
   "src/voice/geminiTextChat.js",
   "src/voice/panelLayout.js",
   "src/voice/textChat.js",
-  "src/voice/textProtocol.js"
+  "src/voice/textProtocol.js",
+  "src/app/sourceComposition.js",
+  "src/app/sourceComposition.test.mjs",
+  "src/data/dataCredits.js",
+  "src/data/layerState.js",
+  "src/data/layerState.test.mjs",
+  "src/data/spriteOrder.js",
+  "src/i18n/locales/ar.json",
+  "src/i18n/locales/de.json",
+  "src/i18n/locales/es.json",
+  "src/i18n/locales/fr.json",
+  "src/i18n/locales/it.json",
+  "src/i18n/locales/ja.json",
+  "src/i18n/locales/pt.json",
+  "src/i18n/locales/ru.json",
+  "src/i18n/locales/uk.json",
+  "src/i18n/locales/zh-CN.json",
+  "src/i18n/locales/zh-Hant.json",
+  "src/i18n/same-as-english.json",
+  "src/navigationPolicy.js",
+  "src/overlays/worldOverlayDraw.js",
+  "src/overlays/worldOverlayDraw.test.mjs",
+  "src/sources/rateLimit.js",
+  "src/ui/layerNames.js",
+  "src/ui/styles/cyber.css",
+  "src/voice/layerManifest.js",
+  "src/worldFocus.js",
+  "src/worldFocus.test.mjs",
+  "server/providers/acartia.js",
+  "server/providers/acartia.test.mjs",
+  "server/providers/common/userAgent.js",
+  "server/providers/inaturalist/client.js",
+  "server/providers/inaturalist/observations.js",
+  "server/providers/inaturalist/observations.test.mjs",
+  "src/app/layers/wildlifeSightings.js",
+  "src/layers/wildlifeSightings/cards.js",
+  "src/layers/wildlifeSightings/cards.test.mjs",
+  "src/layers/wildlifeSightings/controls.js",
+  "src/layers/wildlifeSightings/docs.test.mjs",
+  "src/layers/wildlifeSightings/index.js",
+  "src/layers/wildlifeSightings/lifecycle.js",
+  "src/layers/wildlifeSightings/model.js",
+  "src/layers/wildlifeSightings/model.test.mjs",
+  "src/layers/wildlifeSightings/ownership.test.mjs",
+  "src/layers/wildlifeSightings/photos.js",
+  "src/layers/wildlifeSightings/photos.test.mjs",
+  "src/layers/wildlifeSightings/policy.js",
+  "src/layers/wildlifeSightings/records.js",
+  "src/layers/wildlifeSightings/records.test.mjs",
+  "src/layers/wildlifeSightings/rendering.js",
+  "src/layers/wildlifeSightings/selection.js",
+  "src/layers/wildlifeSightings/source.js",
+  "src/layers/wildlifeSightings/source.test.mjs",
+  "src/layers/wildlifeSightings/viewport.js",
+  "src/layers/wildlifeSightings/viewport.test.mjs",
+  "src/sources/rateLimit.test.mjs",
+  "src/layers/wildlifeSightings/bounds.js",
+  "src/layers/wildlifeSightings/acartiaTaxa.js",
+  "src/layers/wildlifeSightings/acquisition.test.mjs",
+  "server/providers/inaturalist/client.test.mjs",
+  "src/layers/wildlifeSightings/acartiaTaxa.test.mjs",
+  "src/ui/wildlifeSightingCard.test.mjs",
+  "src/overlays/wildlifeSightingOverlay.test.mjs",
+  "scripts/run-perf-tests.mjs",
+  "src/perfTestRunner.test.mjs",
+  "src/testSupport/wildlifeBillboardModel.mjs",
+  "src/layers/wildlifeSightings/gridViewport.test.mjs",
+  "src/layers/wildlifeSightings/rendering.test.mjs",
+  "src/layers/wildlifeSightings/sprites.test.mjs",
+  "src/layers/wildlifeSightings/performance.test.mjs",
+  "src/layers/wildlifeSightings/model.perf.test.mjs",
+  "src/ui/wildlifeSightingPlacement.js",
+  "server/providers/inaturalist/queue.js",
+  "server/providers/inaturalist/queue.test.mjs",
+  "server/providers/inaturalist/grid.js",
+  "server/providers/inaturalist/grid.test.mjs",
+  "server/providers/inaturalist/grid.fixture.mjs",
+  "src/layers/wildlifeSightings/performance.js",
+  "src/layers/wildlifeSightings/renderPerformanceFixtures.mjs",
+  "server/providers/inaturalist/speed.test.mjs",
+  "src/layers/wildlifeSightings/render.perf.test.mjs",
+  "src/layers/wildlifeSightings/cache.integration.test.mjs",
+  "src/layers/wildlifeSightings/density.test.mjs",
+  "src/layers/wildlifeSightings/selection.test.mjs",
+  "server/providers/inaturalist/proxy.fixture.mjs"
 ]
diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json
index b7556f434..fb91e177d 100644
--- a/scripts/package-boundaries.json
+++ b/scripts/package-boundaries.json
@@ -151,7 +151,8 @@
       "src/ui/views/panels/GlobeCompass.vue",
       "src/ui/stores/recording.js",
       "src/ui/styleParameters.js",
-      "src/ui/i18n.js"
+      "src/ui/i18n.js",
+      "src/ui/surfaceKeyboard.js"
     ],
     "external": ["vue", "pinia", "vue-i18n"]
   },
@@ -199,7 +200,22 @@
       "src/data/aisStreamAdapter.js",
       "src/data/aisWatchdog.js",
       "src/sources/httpBody.js",
-      "src/i18n/marker.js"
+      "src/i18n/marker.js",
+      "server/providers/acartia.js",
+      "server/providers/common/rate-limit.js",
+      "server/providers/common/same-site.js",
+      "server/providers/common/userAgent.js",
+      "server/providers/inaturalist/client.js",
+      "server/providers/inaturalist/observations.js",
+      "src/layers/wildlifeSightings/records.js",
+      "src/layers/wildlifeSightings/policy.js",
+      "src/localRequestGate.mjs",
+      "src/sources/rateLimit.js",
+      "src/layers/wildlifeSightings/bounds.js",
+      "src/layers/wildlifeSightings/acartiaTaxa.js",
+      "server/providers/inaturalist/grid.js",
+      "src/layers/wildlifeSightings/gridViewport.js",
+      "server/providers/inaturalist/queue.js"
     ],
     "external": ["ws"]
   },
@@ -1149,7 +1165,14 @@
       "src/ui/stores/globeActions.js",
       "src/ui/stores/recording.js",
       "src/ui/i18n.js",
-      "src/ui/kit/UiSegmented.vue"
+      "src/ui/kit/UiSegmented.vue",
+      "src/ui/wildlifeSightingCard.js",
+      "src/layers/wildlifeSightings/records.js",
+      "src/layers/wildlifeSightings/acartiaTaxa.js",
+      "src/ui/views/panels/WildlifeSightingCard.vue",
+      "src/ui/wildlifeSightingPlacement.js",
+      "src/overlays/worldOverlayChrome.js",
+      "src/layers/wildlifeSightings/photoText.js"
     ],
     "external": ["cesium", "vue", "pinia", "vue-i18n"]
   },
@@ -3263,7 +3286,32 @@
       "src/voice/osmActions.js",
       "src/layers/osmPlaces/index.js",
       "src/app/layers/osmPlaces.js",
-      "src/voice/areaActions.js"
+      "src/voice/areaActions.js",
+      "src/app/layers/wildlifeSightings.js",
+      "src/layers/wildlifeSightings/cards.js",
+      "src/layers/wildlifeSightings/controls.js",
+      "src/layers/wildlifeSightings/index.js",
+      "src/layers/wildlifeSightings/lifecycle.js",
+      "src/layers/wildlifeSightings/model.js",
+      "src/layers/wildlifeSightings/photos.js",
+      "src/layers/wildlifeSightings/policy.js",
+      "src/layers/wildlifeSightings/records.js",
+      "src/layers/wildlifeSightings/rendering.js",
+      "src/layers/wildlifeSightings/density.js",
+      "src/layers/wildlifeSightings/selection.js",
+      "src/layers/wildlifeSightings/source.js",
+      "src/layers/wildlifeSightings/viewport.js",
+      "src/layers/wildlifeSightings/bounds.js",
+      "src/layers/wildlifeSightings/acartiaTaxa.js",
+      "src/ui/wildlifeSightingCard.js",
+      "src/ui/views/panels/WildlifeSightingCard.vue",
+      "src/layers/wildlifeSightings/gridViewport.js",
+      "src/layers/wildlifeSightings/billboardModel.js",
+      "src/layers/wildlifeSightings/sprites.js",
+      "src/ui/wildlifeSightingPlacement.js",
+      "src/overlays/worldOverlayChrome.js",
+      "src/layers/wildlifeSightings/photoText.js",
+      "src/layers/wildlifeSightings/performance.js"
     ],
     "external": [
       "hls.js",
@@ -3886,7 +3934,30 @@
       "src/data/local_data/wof_neighborhoods/files.js",
       "src/layers/osmPlaces/model.js",
       "src/layers/osmPlaces/index.js",
-      "src/app/layers/osmPlaces.js"
+      "src/app/layers/osmPlaces.js",
+      "src/app/layers/wildlifeSightings.js",
+      "src/layers/wildlifeSightings/cards.js",
+      "src/layers/wildlifeSightings/controls.js",
+      "src/layers/wildlifeSightings/index.js",
+      "src/layers/wildlifeSightings/lifecycle.js",
+      "src/layers/wildlifeSightings/model.js",
+      "src/layers/wildlifeSightings/photos.js",
+      "src/layers/wildlifeSightings/policy.js",
+      "src/layers/wildlifeSightings/records.js",
+      "src/layers/wildlifeSightings/rendering.js",
+      "src/layers/wildlifeSightings/density.js",
+      "src/layers/wildlifeSightings/selection.js",
+      "src/layers/wildlifeSightings/source.js",
+      "src/layers/wildlifeSightings/viewport.js",
+      "src/ui/rail/utcClock.js",
+      "src/layers/wildlifeSightings/bounds.js",
+      "src/layers/wildlifeSightings/acartiaTaxa.js",
+      "src/layers/wildlifeSightings/gridViewport.js",
+      "src/layers/wildlifeSightings/billboardModel.js",
+      "src/layers/wildlifeSightings/sprites.js",
+      "src/overlays/worldOverlayChrome.js",
+      "src/layers/wildlifeSightings/photoText.js",
+      "src/layers/wildlifeSightings/performance.js"
     ],
     "external": [
       "hls.js",
@@ -4422,7 +4493,15 @@
       "src/layers/airQuality/model.js",
       "src/layers/airQuality/source.js",
       "src/layers/droneAirspace/source.js",
-      "src/layers/droneAirspace/records.js"
+      "src/layers/droneAirspace/records.js",
+      "src/layers/wildlifeSightings/policy.js",
+      "src/layers/wildlifeSightings/records.js",
+      "src/layers/wildlifeSightings/source.js",
+      "src/layers/wildlifeSightings/viewport.js",
+      "src/layers/wildlifeSightings/bounds.js",
+      "src/layers/wildlifeSightings/acartiaTaxa.js",
+      "src/layers/wildlifeSightings/gridViewport.js",
+      "src/layers/wildlifeSightings/performance.js"
     ],
     "external": []
   },
@@ -4573,7 +4652,8 @@
       "src/i18n/locales/ru.json",
       "src/i18n/locales/uk.json",
       "src/i18n/locales/zh-CN.json",
-      "src/i18n/locales/zh-Hant.json"
+      "src/i18n/locales/zh-Hant.json",
+      "src/overlays/worldOverlayChrome.js"
     ],
     "external": ["cesium", "egm96-universal", "pbf"]
   },
@@ -5055,5 +5135,68 @@
       "src/i18n/marker.js"
     ],
     "external": ["cesium"]
+  },
+  "wildlife-sightings": {
+    "exports": ["./layers/wildlife-sightings"],
+    "modules": [
+      "src/data/dataCredits.js",
+      "src/data/iconOrientation.js",
+      "src/i18n/index.js",
+      "src/i18n/locale.js",
+      "src/i18n/locales/ar.json",
+      "src/i18n/locales/de.json",
+      "src/i18n/locales/es.json",
+      "src/i18n/locales/fr.json",
+      "src/i18n/locales/it.json",
+      "src/i18n/locales/ja.json",
+      "src/i18n/locales/pt.json",
+      "src/i18n/locales/ru.json",
+      "src/i18n/locales/uk.json",
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
+      "src/i18n/marker.js",
+      "src/layers/wildlifeSightings/cards.js",
+      "src/layers/wildlifeSightings/controls.js",
+      "src/layers/wildlifeSightings/index.js",
+      "src/layers/wildlifeSightings/lifecycle.js",
+      "src/layers/wildlifeSightings/model.js",
+      "src/layers/wildlifeSightings/photos.js",
+      "src/layers/wildlifeSightings/policy.js",
+      "src/layers/wildlifeSightings/records.js",
+      "src/layers/wildlifeSightings/rendering.js",
+      "src/layers/wildlifeSightings/density.js",
+      "src/layers/wildlifeSightings/selection.js",
+      "src/layers/wildlifeSightings/source.js",
+      "src/layers/wildlifeSightings/viewport.js",
+      "src/overlays/worldOverlayDraw.js",
+      "src/overlays/worldOverlayTokens.js",
+      "src/sources/httpBody.js",
+      "src/layers/wildlifeSightings/bounds.js",
+      "src/layers/wildlifeSightings/acartiaTaxa.js",
+      "src/ui/statusText.js",
+      "src/ui/layerNames.js",
+      "src/layers/wildlifeSightings/gridViewport.js",
+      "src/layers/wildlifeSightings/billboardModel.js",
+      "src/layers/wildlifeSightings/sprites.js",
+      "src/layers/wildlifeSightings/photoText.js",
+      "src/layers/wildlifeSightings/performance.js"
+    ],
+    "external": ["cesium"]
+  },
+  "wildlife-sightings-source": {
+    "exports": ["./layers/wildlife-sightings/source"],
+    "modules": [
+      "src/i18n/marker.js",
+      "src/layers/wildlifeSightings/policy.js",
+      "src/layers/wildlifeSightings/records.js",
+      "src/layers/wildlifeSightings/source.js",
+      "src/layers/wildlifeSightings/viewport.js",
+      "src/sources/httpBody.js",
+      "src/layers/wildlifeSightings/bounds.js",
+      "src/layers/wildlifeSightings/acartiaTaxa.js",
+      "src/layers/wildlifeSightings/gridViewport.js",
+      "src/layers/wildlifeSightings/performance.js"
+    ],
+    "external": []
   }
 }
diff --git a/scripts/run-perf-tests.mjs b/scripts/run-perf-tests.mjs
new file mode 100644
index 000000000..7d84d950f
--- /dev/null
+++ b/scripts/run-perf-tests.mjs
@@ -0,0 +1,59 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  discoverUnitTestFiles,
+  UNIT_TEST_NODE_FLAGS,
+} from './run-unit-tests.mjs';
+
+/** Discover every layer/provider benchmark, including those added by other branches. */
+export function discoverPerfTestFiles(root = process.cwd()) {
+  return discoverUnitTestFiles(root).filter((file) =>
+    file.endsWith('.perf.test.mjs'),
+  );
+}
+
+/** Shared by benchmarks so normal unit runs visibly skip timing assertions. */
+export function perfBudgetTestOptions(env = process.env) {
+  return {
+    skip:
+      env.GEV_PERF_BUDGETS === '1'
+        ? false
+        : 'Timing budgets are opt-in; run npm run test:perf (GEV_PERF_BUDGETS=1). Deterministic delta/write checks still run in the normal suite.',
+  };
+}
+
+/** Build a serial invocation so benchmarks do not compete for CPU time. */
+export function perfTestArgs(files) {
+  // A single serial test process keeps benchmark files from competing with
+  // each other; the normal suite still discovers them and reports their skips.
+  return [
+    ...UNIT_TEST_NODE_FLAGS,
+    '--test',
+    '--test-concurrency=1',
+    '--test-isolation=none',
+    ...files,
+  ];
+}
+
+/** Run discovered benchmarks with wall-clock budgets enabled. */
+export function runPerfTests({
+  root = process.cwd(),
+  env = process.env,
+  run = spawnSync,
+} = {}) {
+  const files = discoverPerfTestFiles(root);
+  if (!files.length) throw new Error('No *.perf.test.mjs benchmarks found');
+  const result = run(process.execPath, perfTestArgs(files), {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...env, GEV_PERF_BUDGETS: '1' },
+  });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+}
+
+const invoked = process.argv[1]
+  ? pathToFileURL(path.resolve(process.argv[1])).href
+  : '';
+if (import.meta.url === invoked) process.exitCode = runPerfTests();
diff --git a/server/providers/acartia.js b/server/providers/acartia.js
new file mode 100644
index 000000000..e3dafd220
--- /dev/null
+++ b/server/providers/acartia.js
@@ -0,0 +1,179 @@
+import { normalizeAcartiaSightings } from '../../src/layers/wildlifeSightings/records.js';
+import { coalesceProxyRequest, readResponseJsonCapped } from './common/http.js';
+import { makeRateLimiter, clientKey } from './common/rate-limit.js';
+import { admitSameSiteKeyless } from './common/same-site.js';
+import { providerUserAgent } from './common/userAgent.js';
+
+const API_URL = 'https://acartia.io/api/v1/sightings/current';
+// All views share the provider's seven-day snapshot.
+const TTL_MS = 600_000;
+const STALE_MAX_MS = 24 * 60 * 60_000;
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const TIMEOUT_MS = 15_000;
+const COOLDOWN_MS = 60_000;
+const COOLDOWN_MIN_MS = 5000;
+const COOLDOWN_MAX_MS = 60 * 60_000;
+const FAILURE_COOLDOWN_MS = 15_000;
+
+/** Bound upstream Retry-After seconds or dates to five seconds–one hour. */
+export function acartiaRetryCooldownMs(raw, nowMs) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (value) {
+    const seconds = /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : NaN;
+    const deadline =
+      !Number.isFinite(seconds) && /[a-z]/i.test(value)
+        ? Date.parse(value)
+        : NaN;
+    const delay = Number.isFinite(seconds) ? seconds * 1000 : deadline - nowMs;
+    if (Number.isFinite(delay) && delay >= 0)
+      return Math.min(COOLDOWN_MAX_MS, Math.max(COOLDOWN_MIN_MS, delay));
+  }
+  return COOLDOWN_MS;
+}
+
+/** Salish Sea coverage. Precise coordinates and comments never enter cache. */
+export function acartiaProxy({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+  cache = new Map(),
+  warn = (...args) => console.warn(...args),
+} = {}) {
+  const inFlight = new Map();
+  const allow = makeRateLimiter({
+    windowMs: 60_000,
+    max: 60,
+    globalMax: 600,
+    now,
+  });
+  let cooldownUntil = 0;
+  let cooldownStatus = 429;
+  let warnedClamp = false;
+
+  const retrySeconds = () =>
+    Math.max(1, Math.ceil((cooldownUntil - now()) / 1000));
+  const unavailable = (status = 502) =>
+    Object.assign(new Error('acartia_unavailable'), {
+      status,
+      retryAfterS: retrySeconds(),
+    });
+
+  function coolDown(status, delay) {
+    const until = now() + delay;
+    if (until > cooldownUntil) {
+      cooldownUntil = until;
+      cooldownStatus = status;
+    } else if (status === 429 && now() < cooldownUntil) cooldownStatus = 429;
+  }
+
+  async function load() {
+    if (now() < cooldownUntil) throw unavailable(cooldownStatus);
+    const signal = AbortSignal.timeout(TIMEOUT_MS);
+    try {
+      const response = await fetchImpl(API_URL, {
+        signal,
+        redirect: 'error',
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': providerUserAgent('wildlife-sightings'),
+        },
+      });
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {});
+        if (response.status === 429) {
+          const delay = acartiaRetryCooldownMs(
+            response.headers.get('retry-after'),
+            now(),
+          );
+          if (delay === COOLDOWN_MAX_MS && !warnedClamp) {
+            warnedClamp = true;
+            warn('[acartia-proxy] upstream cooldown capped at one hour');
+          }
+          coolDown(429, delay);
+          throw unavailable(429);
+        }
+        throw unavailable();
+      }
+      // This endpoint documents a JSON array, not a results/data envelope.
+      const payload = await readResponseJsonCapped(
+        response,
+        MAX_RESPONSE_BYTES,
+        signal,
+      );
+      const rows = normalizeAcartiaSightings(payload, now());
+      if (!rows?.length) throw new Error('invalid_snapshot');
+      return { fetchedAt: now(), rows };
+    } catch (error) {
+      if (error.status !== 429) coolDown(502, FAILURE_COOLDOWN_MS);
+      warn('[acartia-proxy] upstream refresh failed');
+      throw unavailable(error.status === 429 ? 429 : 502);
+    }
+  }
+
+  function age(entry) {
+    if (!entry) return Infinity;
+    const elapsed = now() - entry.savedAt;
+    return elapsed < 0 ? Infinity : elapsed;
+  }
+
+  async function acquire() {
+    const previous = cache.get('sightings');
+    if (age(previous) < TTL_MS) return { value: previous.value, stale: false };
+    if (age(previous) > STALE_MAX_MS) cache.delete('sightings');
+    try {
+      const { promise } = coalesceProxyRequest(
+        inFlight,
+        'sightings',
+        async () => {
+          const value = await load();
+          cache.set('sightings', { value, savedAt: now() });
+          return value;
+        },
+      );
+      return { value: await promise, stale: false };
+    } catch (error) {
+      if (age(previous) <= STALE_MAX_MS)
+        return { value: previous.value, stale: true };
+      throw error;
+    }
+  }
+
+  async function handler(req, res) {
+    const json = (status, value, { stale = false, retryAfterS } = {}) => {
+      if (res.destroyed) return;
+      res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+        ...(status === 405 ? { Allow: 'GET' } : {}),
+        ...(retryAfterS ? { 'Retry-After': String(retryAfterS) } : {}),
+        ...(stale ? { 'X-Data-Stale': 'true' } : {}),
+      });
+      res.end(JSON.stringify(value));
+    };
+    if (admitSameSiteKeyless(req, res)) return;
+    if (req.method !== 'GET') return json(405, { error: 'method_not_allowed' });
+    const pathname = (req.url || '/').split('?')[0];
+    if (pathname !== '/sightings') return json(404, { error: 'unknown_route' });
+    if (!allow(clientKey(req)))
+      return json(429, { error: 'rate_limited' }, { retryAfterS: 60 });
+    try {
+      const { value, stale } = await acquire();
+      return json(200, stale ? { ...value, stale: true } : value, { stale });
+    } catch (error) {
+      return json(
+        error.status === 429 ? 429 : 502,
+        { error: 'acartia_unavailable' },
+        { retryAfterS: error.retryAfterS },
+      );
+    }
+  }
+
+  return {
+    name: 'acartia',
+    configureServer({ middlewares }) {
+      middlewares.use('/api/acartia', handler);
+    },
+    configurePreviewServer({ middlewares }) {
+      middlewares.use('/api/acartia', handler);
+    },
+  };
+}
diff --git a/server/providers/acartia.test.mjs b/server/providers/acartia.test.mjs
new file mode 100644
index 000000000..bf61d987c
--- /dev/null
+++ b/server/providers/acartia.test.mjs
@@ -0,0 +1,381 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { acartiaProxy, acartiaRetryCooldownMs } from './acartia.js';
+
+const NOW = Date.parse('2026-11-04T18:05:00Z');
+const sighting = (id = 'synthetic-1') => ({
+  entry_id: id,
+  latitude: 48.12345,
+  longitude: -123.12345,
+  created: '2026-11-04 17:00:00',
+  type: 'Orca',
+  no_sighted: '5',
+  photo_url: 'https://provider.example/photos/synthetic.jpg',
+  data_source_name: 'Synthetic Whale Network',
+  data_source_entity: 'Community reports',
+  trusted: true,
+  data_source_comments: 'private-observer@example.test +1-555-000-0000',
+});
+
+function install(options = {}, hook = 'configureServer') {
+  let handler;
+  const plugin = acartiaProxy({ now: () => NOW, warn() {}, ...options });
+  assert.equal(plugin.name, 'acartia');
+  assert.equal(typeof plugin.configureServer, 'function');
+  assert.equal(typeof plugin.configurePreviewServer, 'function');
+  plugin[hook]({
+    middlewares: {
+      use(mount, callback) {
+        assert.equal(mount, '/api/acartia');
+        handler = callback;
+      },
+    },
+  });
+  return async (
+    url = '/sightings',
+    { method = 'GET', peer = 'local', headers = {} } = {},
+  ) => {
+    const res = {
+      headers: {},
+      writeHead(status, headers) {
+        this.status = status;
+        this.headers = headers;
+      },
+      setHeader(key, value) {
+        this.headers[key] = value;
+      },
+      end(value) {
+        this.status ??= this.statusCode;
+        this.body = JSON.parse(value);
+      },
+    };
+    await handler(
+      { url, method, headers, socket: { remoteAddress: peer } },
+      res,
+    );
+    return res;
+  };
+}
+
+test('cache stores only supported marine mammals inside the coverage box', async () => {
+  const cache = new Map();
+  const request = install({
+    cache,
+    fetchImpl: async () =>
+      Response.json([
+        sighting('orca'),
+        { ...sighting('seal'), type: 'Harbor seal' },
+        { ...sighting('unknown'), type: 'Unknown' },
+        { ...sighting('fish'), type: 'Whale shark' },
+        { ...sighting('outside'), latitude: 37.8 },
+        { ...sighting('rounded-edge'), latitude: 45.49999 },
+      ]),
+  });
+  const result = await request();
+  assert.equal(result.status, 200);
+  for (const rows of [result.body.rows, cache.get('sightings').value.rows]) {
+    assert.deepEqual(
+      rows.map((row) => [row.stableId, row.cetacean]),
+      [
+        ['acartia:orca', true],
+        ['acartia:seal', false],
+      ],
+    );
+  }
+});
+
+for (const hook of ['configureServer', 'configurePreviewServer']) {
+  test(`${hook}: documented array is normalized and coarsened before caching`, async () => {
+    const cache = new Map();
+    let calls = 0;
+    const request = install(
+      {
+        cache,
+        fetchImpl: async (url, options) => {
+          calls += 1;
+          assert.equal(url, 'https://acartia.io/api/v1/sightings/current');
+          assert.equal(options.redirect, 'error');
+          assert.ok(options.signal instanceof AbortSignal);
+          assert.equal(options.headers.Accept, 'application/json');
+          assert.equal(
+            options.headers['User-Agent'],
+            'gods-eye-view-wildlife-sightings-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)',
+          );
+          return Response.json([sighting()]);
+        },
+      },
+      hook,
+    );
+    assert.equal(calls, 0);
+    assert.equal(cache.size, 0);
+    const result = await request(
+      '/sightings?url=https://attacker.example&latitude=1',
+    );
+    assert.equal(result.status, 200);
+    assert.equal(result.headers['Cache-Control'], 'no-store');
+    assert.equal(result.body.fetchedAt, NOW);
+    assert.equal(result.body.rows[0].stableId, 'acartia:synthetic-1');
+    assert.equal(result.body.rows[0].lat, 48.12);
+    assert.equal(result.body.rows[0].lon, -123.12);
+    assert.equal(result.body.rows[0].provider.name, 'Synthetic Whale Network');
+    const retained = cache.get('sightings');
+    assert.equal(retained.value.rows[0].lat, 48.12);
+    assert.equal(retained.value.rows[0].lon, -123.12);
+    for (const value of [result.body, [...cache.values()]])
+      assert.doesNotMatch(
+        JSON.stringify(value),
+        /private-observer|555|data_source_comments|48\.12345|123\.12345/,
+      );
+    assert.equal(calls, 1);
+  });
+}
+
+test('gate, method and fixed route run before cache or upstream', async () => {
+  const cache = new Map();
+  let calls = 0;
+  const request = install({
+    cache,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json([sighting()]);
+    },
+  });
+  for (let i = 0; i < 65; i += 1) {
+    assert.equal(
+      (
+        await request('/sightings', {
+          headers: {
+            host: 'localhost:5173',
+            origin: 'https://foreign.example',
+            'sec-fetch-site': 'cross-site',
+          },
+        })
+      ).status,
+      403,
+    );
+  }
+  const method = await request('/sightings', { method: 'POST' });
+  assert.equal(method.status, 405);
+  assert.equal(method.headers.Allow, 'GET');
+  for (const route of ['/', '/unknown', '/sightings/extra']) {
+    const result = await request(route);
+    assert.equal(result.status, 404);
+    assert.equal(result.body.error, 'unknown_route');
+  }
+  assert.equal(calls, 0);
+  assert.equal(cache.size, 0);
+  const sameOrigin = await request('/sightings', {
+    headers: {
+      host: 'gev.example',
+      origin: 'https://gev.example',
+      'sec-fetch-site': 'same-origin',
+      'x-forwarded-proto': 'https',
+      'x-forwarded-for': '203.0.113.9',
+    },
+  });
+  assert.equal(sameOrigin.status, 200);
+});
+
+test('request 61 is locally limited even with a fresh cache', async () => {
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json([sighting()]);
+    },
+  });
+  for (let i = 0; i < 60; i += 1) assert.equal((await request()).status, 200);
+  const limited = await request();
+  assert.equal(limited.status, 429);
+  assert.equal(limited.body.error, 'rate_limited');
+  assert.equal(limited.headers['Retry-After'], '60');
+  assert.equal(calls, 1);
+});
+
+test('one global snapshot single-flights and stays fresh for ten minutes', async () => {
+  let at = NOW;
+  let calls = 0;
+  let release;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      if (calls === 1)
+        await new Promise((resolve) => {
+          release = resolve;
+        });
+      return Response.json([sighting()]);
+    },
+  });
+  const first = request();
+  const concurrent = request();
+  await new Promise(setImmediate);
+  assert.equal(calls, 1);
+  release();
+  assert.deepEqual((await first).body, (await concurrent).body);
+  at += 599_999;
+  await request();
+  assert.equal(calls, 1);
+  at += 1;
+  await request();
+  assert.equal(calls, 2);
+});
+
+test('empty, unprojectable and invented wrapped snapshots never replace the cache', async () => {
+  for (const bad of [
+    [],
+    [null],
+    [{ ...sighting(), data_source_name: '' }],
+    { results: [sighting()] },
+  ]) {
+    let at = NOW;
+    let fail = false;
+    const cache = new Map();
+    const request = install({
+      cache,
+      now: () => at,
+      fetchImpl: async () => Response.json(fail ? bad : [sighting()]),
+    });
+    const fresh = await request();
+    const retained = cache.get('sightings');
+    fail = true;
+    at += 600_001;
+    const stale = await request();
+    assert.equal(stale.status, 200);
+    assert.equal(stale.headers['X-Data-Stale'], 'true');
+    assert.equal(stale.body.stale, true);
+    assert.equal(stale.body.fetchedAt, fresh.body.fetchedAt);
+    assert.equal(cache.get('sightings'), retained);
+    const coldCache = new Map();
+    const cold = install({
+      cache: coldCache,
+      fetchImpl: async () => Response.json(bad),
+    });
+    const result = await cold();
+    assert.equal(result.status, 502);
+    assert.equal(result.body.error, 'acartia_unavailable');
+    assert.equal(coldCache.size, 0);
+  }
+});
+
+test('failure serves stale for at most 24 hours and never reports a cold success', async () => {
+  let at = NOW;
+  let fail = false;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      if (fail) throw new Error('private upstream detail');
+      return Response.json([sighting()]);
+    },
+  });
+  const first = await request();
+  fail = true;
+  at += 23 * 60 * 60_000 + 59 * 60_000;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, first.body.fetchedAt);
+  at += 2 * 60_000;
+  const expired = await request();
+  assert.equal(expired.status, 502);
+  assert.deepEqual(expired.body, { error: 'acartia_unavailable' });
+});
+
+test('upstream 429 honors Retry-After, caps it, and spends no requests while cooling down', async () => {
+  assert.equal(acartiaRetryCooldownMs('2', NOW), 5000);
+  assert.equal(acartiaRetryCooldownMs('999999', NOW), 3_600_000);
+  assert.equal(
+    acartiaRetryCooldownMs(new Date(NOW + 120_000).toUTCString(), NOW),
+    120_000,
+  );
+  assert.equal(acartiaRetryCooldownMs(null, NOW), 60_000);
+  let at = NOW;
+  let calls = 0;
+  const warnings = [];
+  const request = install({
+    now: () => at,
+    warn: (message) => warnings.push(message),
+    fetchImpl: async () => {
+      calls += 1;
+      return new Response('limit', {
+        status: 429,
+        headers: { 'Retry-After': '999999' },
+      });
+    },
+  });
+  const first = await request();
+  assert.equal(first.status, 429);
+  assert.equal(first.body.error, 'acartia_unavailable');
+  assert.equal(first.headers['Retry-After'], '3600');
+  at += 5000;
+  const cooling = await request();
+  assert.equal(cooling.headers['Retry-After'], '3595');
+  assert.equal(calls, 1);
+  assert.equal(
+    warnings.filter((message) => message.includes('capped')).length,
+    1,
+  );
+  at += 3_600_000;
+  await request();
+  assert.equal(calls, 2);
+  assert.equal(
+    warnings.filter((message) => message.includes('capped')).length,
+    1,
+  );
+});
+
+test('upstream 429 also serves a prior snapshot stale', async () => {
+  let at = NOW;
+  let fail = false;
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      return fail
+        ? new Response('limit', { status: 429 })
+        : Response.json([sighting()]);
+    },
+  });
+  const first = await request();
+  fail = true;
+  at += 600_001;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, first.body.fetchedAt);
+  at += 1000;
+  assert.equal((await request()).body.stale, true);
+  assert.equal(calls, 2);
+});
+
+test('bad JSON, 5xx and capped bodies start a 15 second failure cooldown', async () => {
+  for (const bad of [
+    () => new Response('{malformed'),
+    () => new Response('private upstream message', { status: 503 }),
+    () =>
+      new Response('{}', {
+        headers: { 'Content-Length': String(2 * 1024 * 1024 + 1) },
+      }),
+  ]) {
+    let at = NOW;
+    let calls = 0;
+    const request = install({
+      now: () => at,
+      fetchImpl: async () => {
+        calls += 1;
+        return calls === 1 ? bad() : Response.json([sighting()]);
+      },
+    });
+    const first = await request();
+    assert.equal(first.status, 502);
+    assert.deepEqual(first.body, { error: 'acartia_unavailable' });
+    assert.equal(first.headers['Retry-After'], '15');
+    at += 14_999;
+    assert.equal((await request()).headers['Retry-After'], '1');
+    assert.equal(calls, 1);
+    at += 1;
+    assert.equal((await request()).status, 200);
+    assert.equal(calls, 2);
+  }
+});
diff --git a/server/providers/common/userAgent.js b/server/providers/common/userAgent.js
new file mode 100644
index 000000000..63479f7cc
--- /dev/null
+++ b/server/providers/common/userAgent.js
@@ -0,0 +1,4 @@
+/** Identify each provider while keeping the project contact URL consistent. */
+export function providerUserAgent(name) {
+  return `gods-eye-view-${name}-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)`;
+}
diff --git a/server/providers/inaturalist/client.js b/server/providers/inaturalist/client.js
new file mode 100644
index 000000000..0ba59124b
--- /dev/null
+++ b/server/providers/inaturalist/client.js
@@ -0,0 +1,370 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { normalizeInatObservations } from '../../../src/layers/wildlifeSightings/records.js';
+import { readResponseJsonCapped } from '../common/http.js';
+import { clampInt } from '../common/query.js';
+import { providerUserAgent } from '../common/userAgent.js';
+import { projectInatGrid, validInatGridTile } from './grid.js';
+import { createInatQueue } from './queue.js';
+
+const DAILY_BUDGET = 8000;
+const DAY_MS = 24 * 60 * 60_000;
+// One page is capped independently of upstream Content-Length.
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const TIMEOUT_MS = 20_000;
+const API_URL = 'https://api.inaturalist.org/v1';
+// Request only the fields used by the public observation projection.
+const OBSERVATIONS_URL = 'https://api.inaturalist.org/v2/observations';
+const OBSERVATION_FIELDS =
+  '(id:!t,uri:!t,location:!t,geojson:all,geoprivacy:!t,taxon_geoprivacy:!t,' +
+  'obscured:!t,quality_grade:!t,observed_on:!t,' +
+  'time_observed_at:!t,faves_count:!t,' +
+  'num_identification_agreements:!t,' +
+  'photos:(url:!t,attribution:!t,license_code:!t),' +
+  'taxon:(name:!t,preferred_common_name:!t,iconic_taxon_name:!t,' +
+  'threatened:!t))';
+const COOLDOWN_MS = 60_000;
+const FAILURE_COOLDOWN_MS = 15_000;
+
+/** Seconds and HTTP dates are accepted; a missing value earns one minute. */
+export function inatRetryCooldownMs(raw, nowMs) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (value) {
+    const seconds = /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : NaN;
+    const deadline =
+      !Number.isFinite(seconds) && /[a-z]/i.test(value)
+        ? Date.parse(value)
+        : NaN;
+    const delay = Number.isFinite(seconds) ? seconds * 1000 : deadline - nowMs;
+    if (Number.isFinite(delay) && delay >= 0) return delay;
+  }
+  return COOLDOWN_MS;
+}
+
+function upstreamError(code, status, retryAfterS, upstreamStatus) {
+  return Object.assign(new Error(code), {
+    code,
+    status,
+    retryAfterS,
+    upstreamStatus,
+  });
+}
+
+function observationFilters(params) {
+  const query = new URLSearchParams({
+    verifiable: 'true',
+    captive: 'false',
+    // d1 is an observation DATE, unlike creation-time created_d1.
+    d1: params.observedD1,
+  });
+  if (params.taxa !== 'whales') query.set('photos', 'true');
+  if (params.quality === 'research') query.set('quality_grade', 'research');
+  if (params.taxa === 'whales') query.set('taxon_id', '152871');
+  else if (['Aves', 'Mammalia', 'Insecta', 'Plantae'].includes(params.taxa))
+    query.set('iconic_taxa', params.taxa);
+  return query;
+}
+
+/**
+ * Shared iNaturalist governor. Only request counters are persisted; observation
+ * payloads are projected immediately and are never written to disk.
+ */
+export function createInatClient({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+  cacheDir = path.join(process.cwd(), '.gev-cache', 'inaturalist'),
+  warn = (...args) => console.warn(...args),
+  queueOptions,
+} = {}) {
+  const enqueue = createInatQueue(queueOptions);
+  let budget = null;
+  let budgetLoaded = false;
+  let budgetTail = Promise.resolve();
+  let cooldownUntil = 0;
+  // An unavailable UTFGrid tile must never place observation queries into a
+  // 502 cooldown. Only an upstream 429 is a provider-wide restriction.
+  const failures = new Map();
+
+  function dailyLimit() {
+    return clampInt(
+      process.env.INATURALIST_DAILY_BUDGET,
+      1,
+      Number.MAX_SAFE_INTEGER,
+      DAILY_BUDGET,
+    );
+  }
+
+  function day() {
+    return new Date(now()).toISOString().slice(0, 10);
+  }
+
+  function currentBudget() {
+    const date = day();
+    if (budget?.date !== date) budget = { date, count: 0 };
+    return budget;
+  }
+
+  async function readBudgetOnce() {
+    if (budgetLoaded) return;
+    budgetLoaded = true;
+    if (cacheDir === null) return;
+    try {
+      const value = JSON.parse(
+        await fs.readFile(path.join(cacheDir, 'budget.json'), 'utf8'),
+      );
+      if (
+        typeof value?.date === 'string' &&
+        /^\d{4}-\d{2}-\d{2}$/.test(value.date) &&
+        Number.isSafeInteger(value.count) &&
+        value.count >= 0
+      )
+        budget = { date: value.date, count: value.count };
+    } catch (error) {
+      if (error.code !== 'ENOENT')
+        warn('[inaturalist-proxy] budget read failed');
+    }
+  }
+
+  async function persistBudget(value) {
+    if (cacheDir === null) return;
+    const destination = path.join(cacheDir, 'budget.json');
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    try {
+      await fs.mkdir(cacheDir, { recursive: true });
+      await fs.writeFile(temporary, JSON.stringify(value), 'utf8');
+      await fs.rename(temporary, destination);
+    } catch {
+      await fs.rm(temporary, { force: true }).catch(() => {});
+      warn('[inaturalist-proxy] budget write failed');
+    }
+  }
+
+  function retrySeconds(until = cooldownUntil) {
+    return Math.max(0, Math.ceil((until - now()) / 1000));
+  }
+
+  function checkCooldown(resource) {
+    if (now() < cooldownUntil)
+      throw upstreamError('inaturalist_rate_limited', 429, retrySeconds(), 429);
+    const failure = failures.get(resource);
+    if (failure && now() < failure.until)
+      throw upstreamError(
+        'inaturalist_unavailable',
+        502,
+        retrySeconds(failure.until),
+        failure.status,
+      );
+    failures.delete(resource);
+  }
+
+  // Reserve and atomically persist one attempt before issuing it. A recovered
+  // tail prevents one disk/reservation failure from poisoning future calls.
+  function reserveAttempt(signal, resource) {
+    const result = budgetTail.then(async () => {
+      signal?.throwIfAborted();
+      checkCooldown(resource);
+      await readBudgetOnce();
+      signal?.throwIfAborted();
+      checkCooldown(resource);
+      const value = currentBudget();
+      if (value.count >= dailyLimit()) {
+        const retry = Math.max(
+          1,
+          Math.ceil((Date.parse(`${day()}T00:00:00Z`) + DAY_MS - now()) / 1000),
+        );
+        throw upstreamError('inaturalist_budget_exhausted', 503, retry);
+      }
+      value.count += 1;
+      await persistBudget({ ...value });
+    });
+    budgetTail = result.catch(() => {});
+    return result;
+  }
+
+  async function requestProjected(url, project, resource, { signal } = {}) {
+    signal?.throwIfAborted();
+    checkCooldown(resource);
+    return enqueue(() => dispatch(url, project, resource, signal), {
+      signal,
+      priority: resource === 'observations' ? 0 : 1,
+    });
+  }
+
+  async function dispatch(url, project, resource, signal) {
+    signal?.throwIfAborted();
+    await reserveAttempt(signal, resource);
+    signal?.throwIfAborted();
+    checkCooldown(resource);
+    const timeout = AbortSignal.timeout(TIMEOUT_MS);
+    const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    let upstreamStatus;
+    let retryDelay = FAILURE_COOLDOWN_MS;
+    try {
+      const response = await fetchImpl(url, {
+        signal: requestSignal,
+        redirect: 'error',
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': providerUserAgent('wildlife-sightings'),
+        },
+      });
+      upstreamStatus = response.status;
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {});
+        if (response.status === 429) {
+          const delay = inatRetryCooldownMs(
+            response.headers.get('retry-after'),
+            now(),
+          );
+          cooldownUntil = Math.max(cooldownUntil, now() + delay);
+          throw upstreamError(
+            'inaturalist_rate_limited',
+            429,
+            retrySeconds(),
+            429,
+          );
+        }
+        if (response.headers.has('retry-after'))
+          retryDelay = inatRetryCooldownMs(
+            response.headers.get('retry-after'),
+            now(),
+          );
+        throw upstreamError('inaturalist_unavailable', 502);
+      }
+      const payload = await readResponseJsonCapped(
+        response,
+        MAX_RESPONSE_BYTES,
+        requestSignal,
+      );
+      return project(payload);
+    } catch (error) {
+      // Log only safe diagnostic categories, never a URL, body, status text or
+      // exception message (each can contain request/private information).
+      const reason = signal?.aborted
+        ? 'abort'
+        : timeout.aborted || error.name === 'TimeoutError'
+          ? 'timeout'
+          : upstreamStatus && upstreamStatus >= 400
+            ? 'http'
+            : error.code === 'RESPONSE_TOO_LARGE'
+              ? 'response-too-large'
+              : upstreamStatus
+                ? 'invalid-payload'
+                : 'network';
+      warn(
+        `[inaturalist-proxy] upstream refresh failed resource=${resource} status=${upstreamStatus ?? 'none'} reason=${reason}`,
+      );
+      if (signal?.aborted) throw error;
+      // Network, abort, schema and size failures are not upstream cooldown
+      // signals. A later healthy request may recover immediately.
+      if (upstreamStatus >= 500)
+        failures.set(resource, {
+          until: now() + retryDelay,
+          status: upstreamStatus,
+        });
+      const failure = failures.get(resource);
+      throw upstreamError(
+        error.status === 429
+          ? 'inaturalist_rate_limited'
+          : 'inaturalist_unavailable',
+        error.status === 429 ? 429 : 502,
+        error.status === 429
+          ? retrySeconds()
+          : failure
+            ? retrySeconds(failure.until)
+            : undefined,
+        upstreamStatus === 429 || upstreamStatus >= 500
+          ? upstreamStatus
+          : undefined,
+      );
+    }
+  }
+
+  /** Request one bounded observation sample and project its public fields. */
+  async function getObservations(params, options = {}) {
+    const query = observationFilters(params);
+    // View samples stay stable in the route cache until their TTL expires.
+    query.set('order_by', params.scope === 'view' ? 'random' : 'observed_on');
+    if (params.scope !== 'view') query.set('order', 'desc');
+    query.set('per_page', '200');
+    query.set('fields', OBSERVATION_FIELDS);
+    if (params.scope === 'view') {
+      query.set('swlat', String(params.box.south));
+      query.set('swlng', String(params.box.west));
+      query.set('nelat', String(params.box.north));
+      query.set('nelng', String(params.box.east));
+    }
+    return requestProjected(
+      `${OBSERVATIONS_URL}?${query}`,
+      (payload) => {
+        if (
+          !Array.isArray(payload?.results) ||
+          !Number.isSafeInteger(payload.total_results) ||
+          payload.total_results < 0
+        )
+          throw upstreamError('inaturalist_unavailable', 502);
+        const rows = normalizeInatObservations(payload.results, {
+          nowMs: now(),
+          windowMs: (params.taxa === 'whales' ? 7 : 2) * DAY_MS,
+        });
+        // Empty views need total_results: 0. A wholly invalid page must not
+        // replace good data. Valid rows excluded by the finer rolling-time
+        // cutoff are a healthy empty result of the upstream DATE over-fetch.
+        if (
+          !rows ||
+          (!rows.length &&
+            (payload.results.length || payload.total_results) &&
+            !normalizeInatObservations(payload.results)?.length)
+        )
+          throw upstreamError('inaturalist_unavailable', 502);
+        return {
+          rows,
+          totalResults: payload.total_results,
+          ...(payload.total_results > payload.results.length
+            ? { partial: true, rawRowCount: payload.total_results }
+            : {}),
+        };
+      },
+      'observations',
+      options,
+    );
+  }
+
+  /** Decode one validated density tile without observation identifiers. */
+  async function getGrid(params, options = {}) {
+    if (!validInatGridTile(params)) throw new TypeError('Invalid grid tile');
+    const query = observationFilters(params);
+    return requestProjected(
+      `${API_URL}/grid/${params.z}/${params.x}/${params.y}.grid.json?${query}`,
+      (payload) => projectInatGrid(payload, params),
+      'grid',
+      options,
+    );
+  }
+
+  return {
+    getObservations,
+    getGrid,
+    /** Current provider-wide or resource-specific retry information. */
+    cooldownState(resource) {
+      if (now() < cooldownUntil)
+        return {
+          upstreamStatus: 429,
+          retryAfterS: retrySeconds(),
+        };
+      const failure = failures.get(resource);
+      if (failure && now() < failure.until)
+        return {
+          upstreamStatus: failure.status,
+          retryAfterS: retrySeconds(failure.until),
+        };
+      return undefined;
+    },
+    /** The current UTC day's reserved upstream attempts and configured limit. */
+    budgetState() {
+      const value = currentBudget();
+      return { ...value, budget: dailyLimit() };
+    },
+  };
+}
diff --git a/server/providers/inaturalist/client.test.mjs b/server/providers/inaturalist/client.test.mjs
new file mode 100644
index 000000000..d509396a8
--- /dev/null
+++ b/server/providers/inaturalist/client.test.mjs
@@ -0,0 +1,163 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createInatClient } from './client.js';
+import { syntheticGrid } from './grid.fixture.mjs';
+
+const NOW = Date.parse('2026-11-04T18:05:00Z');
+const observation = (id, time) => ({
+  id,
+  geojson: { coordinates: [-122.3, 47.6] },
+  quality_grade: 'research',
+  time_observed_at: time,
+  observed_on: time.slice(0, 10),
+  // Upload age does not determine whether an observation is recent.
+  created_at: '2026-11-04T18:00:00Z',
+  taxon: { name: 'Synthetic taxon', iconic_taxon_name: 'Aves' },
+});
+
+function clientFor(results) {
+  return createInatClient({
+    now: () => NOW,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0 },
+    warn() {},
+    fetchImpl: async () =>
+      Response.json({ results, total_results: results.length }),
+  });
+}
+
+test('iNaturalist drops ancient and boundary-expired observations uploaded today', async () => {
+  const client = clientFor([
+    observation(1, '2010-11-04T18:00:00Z'),
+    observation(2, '2026-11-02T18:04:59Z'),
+    observation(3, '2026-11-02T18:05:00Z'),
+  ]);
+  const result = await client.getObservations({
+    scope: 'global',
+    taxa: 'all',
+    observedD1: '2026-11-02',
+  });
+  assert.deepEqual(
+    result.rows.map((row) => row.stableId),
+    ['inat:3'],
+  );
+});
+
+test('a valid date-filtered page can be empty after the exact recency cutoff', async () => {
+  const client = clientFor([observation(1, '2026-11-02T06:00:00Z')]);
+  const result = await client.getObservations({
+    scope: 'global',
+    taxa: 'all',
+    observedD1: '2026-11-02',
+  });
+  assert.deepEqual(result.rows, []);
+  assert.equal(result.totalResults, 1);
+});
+
+const params = {
+  scope: 'view',
+  box: { south: 47, west: -123, north: 48, east: -122 },
+  taxa: 'all',
+  observedD1: '2026-11-02',
+};
+
+test('observations and tiles share pacing, and observation priority wins a cold burst', async () => {
+  let at = 0;
+  const calls = [];
+  const client = createInatClient({
+    cacheDir: null,
+    now: () => NOW + at,
+    queueOptions: {
+      now: () => at,
+      wait: async (ms) => {
+        at += ms;
+      },
+    },
+    fetchImpl: async (url) => {
+      const isGrid = new URL(url).pathname.includes('/grid/');
+      calls.push([isGrid ? 'grid' : 'observations', at]);
+      return Response.json(
+        isGrid ? syntheticGrid() : { results: [], total_results: 0 },
+      );
+    },
+  });
+  const tiles = Array.from({ length: 3 }, (_, x) =>
+    client.getGrid({ ...params, z: 2, x, y: 1 }),
+  );
+  await Promise.all([...tiles, client.getObservations(params)]);
+  assert.deepEqual(calls, [
+    ['observations', 0],
+    ['grid', 0],
+    ['grid', 0],
+    ['grid', 0],
+  ]);
+  assert.equal(client.budgetState().count, 4);
+});
+
+test('upstream status and safe failure reasons are logged without upstream messages or URLs', async () => {
+  for (const [response, expected] of [
+    [
+      () =>
+        new Response('request-secret', {
+          status: 503,
+          statusText: 'request-secret',
+        }),
+      /status=503 reason=http/,
+    ],
+    [
+      () => Promise.reject(new DOMException('request-secret', 'TimeoutError')),
+      /status=none reason=timeout/,
+    ],
+    [
+      () => Response.json({ unexpected: 'request-secret' }),
+      /status=200 reason=invalid-payload/,
+    ],
+  ]) {
+    const warnings = [];
+    const client = createInatClient({
+      cacheDir: null,
+      now: () => NOW,
+      queueOptions: { intervalMs: 0 },
+      warn: (message) => warnings.push(message),
+      fetchImpl: response,
+    });
+    await assert.rejects(client.getObservations(params), { status: 502 });
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0], expected);
+    assert.doesNotMatch(warnings[0], /request-secret|https?:|swlat|d1=/);
+  }
+});
+
+test('a dispatched abort is diagnosed, spends only its attempt, and leaves the next request healthy', async () => {
+  const warnings = [];
+  const controller = new AbortController();
+  let started;
+  const didStart = new Promise((resolve) => {
+    started = resolve;
+  });
+  let calls = 0;
+  const client = createInatClient({
+    cacheDir: null,
+    now: () => NOW,
+    queueOptions: { intervalMs: 0 },
+    warn: (message) => warnings.push(message),
+    fetchImpl: async (url, { signal }) => {
+      calls += 1;
+      if (calls > 1) return Response.json({ results: [], total_results: 0 });
+      started();
+      return new Promise((resolve, reject) =>
+        signal.addEventListener('abort', () => reject(signal.reason), {
+          once: true,
+        }),
+      );
+    },
+  });
+  const pending = client.getObservations(params, { signal: controller.signal });
+  const failed = assert.rejects(pending, { name: 'AbortError' });
+  await didStart;
+  controller.abort();
+  await failed;
+  assert.match(warnings[0], /resource=observations status=none reason=abort/);
+  await client.getObservations(params);
+  assert.equal(calls, 2);
+});
diff --git a/server/providers/inaturalist/grid.fixture.mjs b/server/providers/inaturalist/grid.fixture.mjs
new file mode 100644
index 000000000..4ba6e05c5
--- /dev/null
+++ b/server/providers/inaturalist/grid.fixture.mjs
@@ -0,0 +1,51 @@
+/** Build a synthetic UTFGrid with logical cell counts and repeated hit pixels. */
+export function syntheticGrid({
+  z = 2,
+  x = 1,
+  y = 1,
+  cells = [
+    { row: 1, column: 51, count: 6, iconic: 3 },
+    { row: 3, column: 49, count: 12, iconic: 47170 },
+  ],
+} = {}) {
+  const pixels = Array.from({ length: 64 }, () => Array(64).fill(' '));
+  const keys = [''];
+  const data = {};
+  cells.forEach((cell, index) => {
+    const key = String(900_000_000 + index);
+    keys.push(key);
+    const value = index + 1;
+    let code = value + 32;
+    if (code >= 34) code += 1;
+    if (code >= 92) code += 1;
+    const character = String.fromCharCode(code);
+    for (const [row, column] of [
+      [cell.row, cell.column],
+      [cell.row - 1, cell.column],
+      [cell.row + 1, cell.column],
+      [cell.row, cell.column - 1],
+      [cell.row, cell.column + 1],
+    ]) {
+      if (row >= 0 && row < 64 && column >= 0 && column < 64)
+        pixels[row][column] = character;
+    }
+    data[key] = {
+      captive: null,
+      cellCount: cell.count,
+      geoprivacy: null,
+      id: Number(key),
+      latitude:
+        (Math.atan(
+          Math.sinh(Math.PI * (1 - 2 * ((y + cell.row / 64) / 2 ** z))),
+        ) *
+          180) /
+        Math.PI,
+      longitude: ((x + cell.column / 64) / 2 ** z) * 360 - 180,
+      private_location: null,
+      quality_grade: 'needs_id',
+      'taxon.iconic_taxon_id': cell.iconic,
+      uuid: `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`,
+    };
+  });
+  return { grid: pixels.map((row) => row.join('')), keys, data };
+}
diff --git a/server/providers/inaturalist/grid.js b/server/providers/inaturalist/grid.js
new file mode 100644
index 000000000..5d4e0aeb2
--- /dev/null
+++ b/server/providers/inaturalist/grid.js
@@ -0,0 +1,127 @@
+// iNaturalist's operational /v1/grid/{z}/{x}/{y}.grid.json endpoint is not
+// covered by its v1 Swagger contract. Validate the entire UTFGrid shape before
+// accepting any cell; callers preserve the last good sample on schema drift.
+import {
+  wildlifeGridCellId,
+  WILDLIFE_GRID_MAX_ZOOM,
+} from '../../../src/layers/wildlifeSightings/gridViewport.js';
+
+const INAT_GRID_SIZE = 64;
+export const INAT_GRID_DECODE_MEASURE = 'wildlife:server:tile-decode';
+const grades = new Set(['research', 'needs_id', 'casual']);
+const object = (value) =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
+/** Accept only integer XYZ coordinates within the supported zoom range. */
+export function validInatGridTile({ z, x, y } = {}) {
+  return (
+    Number.isInteger(z) &&
+    z >= 0 &&
+    z <= WILDLIFE_GRID_MAX_ZOOM &&
+    Number.isInteger(x) &&
+    Number.isInteger(y) &&
+    x >= 0 &&
+    y >= 0 &&
+    x < 2 ** z &&
+    y < 2 ** z
+  );
+}
+
+/** Pure allow-list projection. A UTFGrid key is an observation identifier and
+ * its repeated pixels form a dilated hit area, not additional occupied cells.
+ * Neither those keys nor representative/private fields cross this boundary. */
+export function projectInatGrid(payload, tile) {
+  const start = `${INAT_GRID_DECODE_MEASURE}:start`;
+  const end = `${INAT_GRID_DECODE_MEASURE}:end`;
+  performance.mark(start);
+  try {
+    return decodeInatGrid(payload, tile);
+  } finally {
+    performance.mark(end);
+    // Keep the latest sample inspectable without retaining every tile forever.
+    // PerformanceObservers still receive each individual decode measurement.
+    performance.clearMeasures(INAT_GRID_DECODE_MEASURE);
+    performance.measure(INAT_GRID_DECODE_MEASURE, start, end);
+    performance.clearMarks(start);
+    performance.clearMarks(end);
+  }
+}
+
+function decodeInatGrid(payload, tile) {
+  const invalid = () => {
+    throw new TypeError('Invalid iNaturalist UTFGrid');
+  };
+  if (
+    !validInatGridTile(tile) ||
+    !object(payload) ||
+    !Array.isArray(payload.grid) ||
+    payload.grid.length !== INAT_GRID_SIZE ||
+    !payload.grid.every(
+      (row) => typeof row === 'string' && row.length === INAT_GRID_SIZE,
+    ) ||
+    !Array.isArray(payload.keys) ||
+    !payload.keys.length ||
+    payload.keys.length > INAT_GRID_SIZE ** 2 + 1 ||
+    payload.keys[0] !== '' ||
+    !payload.keys.every(
+      (key) => typeof key === 'string' && key.length <= 128,
+    ) ||
+    new Set(payload.keys).size !== payload.keys.length ||
+    !object(payload.data)
+  )
+    invalid();
+  const dataKeys = Object.keys(payload.data);
+  if (dataKeys.length !== payload.keys.length - 1) invalid();
+  for (const key of payload.keys.slice(1)) {
+    if (!key || !Object.hasOwn(payload.data, key)) invalid();
+    const value = payload.data[key];
+    if (
+      !object(value) ||
+      !Number.isSafeInteger(value.cellCount) ||
+      value.cellCount <= 0 ||
+      !Number.isFinite(value.latitude) ||
+      Math.abs(value.latitude) > 90 ||
+      !Number.isFinite(value.longitude) ||
+      Math.abs(value.longitude) > 180 ||
+      !grades.has(value.quality_grade) ||
+      !(
+        value['taxon.iconic_taxon_id'] === null ||
+        (Number.isSafeInteger(value['taxon.iconic_taxon_id']) &&
+          value['taxon.iconic_taxon_id'] > 0)
+      )
+    )
+      invalid();
+  }
+  const occupied = new Set();
+  for (const line of payload.grid) {
+    for (let column = 0; column < INAT_GRID_SIZE; column += 1) {
+      let code = line.charCodeAt(column);
+      if (code < 32 || code === 34 || code === 92) invalid();
+      if (code >= 93) code -= 1;
+      if (code >= 35) code -= 1;
+      const index = code - 32;
+      if (index < 0 || index >= payload.keys.length) invalid();
+      if (index) occupied.add(payload.keys[index]);
+    }
+  }
+  if (occupied.size !== dataKeys.length) invalid();
+  const cells = new Map();
+  for (const key of occupied) {
+    const value = payload.data[key];
+    const id = wildlifeGridCellId(value.latitude, value.longitude, tile.z);
+    const cell = {
+      id,
+      cellCount: value.cellCount,
+      lat: value.latitude,
+      lon: value.longitude,
+    };
+    // Two different representatives claiming one logical cell are a contract
+    // change; summing or choosing one silently would fabricate the count.
+    if (cells.has(id)) invalid();
+    cells.set(id, cell);
+  }
+  const rows = [...cells.values()];
+  const totalResults = rows.reduce((total, cell) => total + cell.cellCount, 0);
+  if (!Number.isSafeInteger(totalResults)) invalid();
+  return { cells: rows, totalResults };
+}
diff --git a/server/providers/inaturalist/grid.test.mjs b/server/providers/inaturalist/grid.test.mjs
new file mode 100644
index 000000000..b40c69dbe
--- /dev/null
+++ b/server/providers/inaturalist/grid.test.mjs
@@ -0,0 +1,374 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { projectInatGrid } from './grid.js';
+import { syntheticGrid } from './grid.fixture.mjs';
+import { installInatProxy, NOW } from './proxy.fixture.mjs';
+import { createInatClient } from './client.js';
+
+const tile = { z: 2, x: 1, y: 1 };
+const gridUrl = '/grid?z=2&x=1&y=1&taxa=Aves&quality=research';
+const install = (options, hook) => installInatProxy(gridUrl, options, hook);
+
+test('UTFGrid projection validates the full shape and counts each logical occupied cell once', () => {
+  const raw = syntheticGrid();
+  const projected = projectInatGrid(raw, tile);
+  assert.equal(raw.grid.length, 64);
+  assert.ok(raw.grid.every((row) => row.length === 64));
+  assert.equal(
+    raw.grid.join('').split('!').length - 1,
+    5,
+    'one key is repeated by its hit area',
+  );
+  assert.equal(projected.cells.length, 2);
+  assert.equal(projected.totalResults, 18);
+  assert.deepEqual(projected.cells[0], {
+    id: 'grid:2/1/1:1:51',
+    cellCount: 6,
+    lat: raw.data[raw.keys[1]].latitude,
+    lon: raw.data[raw.keys[1]].longitude,
+  });
+  for (const cell of projected.cells)
+    assert.deepEqual(Object.keys(cell).sort(), [
+      'cellCount',
+      'id',
+      'lat',
+      'lon',
+    ]);
+  for (const privateField of [
+    '900000000',
+    'uuid',
+    'geoprivacy',
+    'private_location',
+    'captive',
+    'quality_grade',
+  ])
+    assert.ok(!JSON.stringify(projected).includes(privateField));
+});
+
+test('legitimate blank grid and null/unknown iconic ids remain safe', () => {
+  assert.deepEqual(projectInatGrid(syntheticGrid({ cells: [] }), tile), {
+    cells: [],
+    totalResults: 0,
+  });
+  const raw = syntheticGrid({
+    cells: [{ row: 1, column: 1, count: 1, iconic: null }],
+  });
+  const projected = projectInatGrid(raw, tile);
+  assert.equal(projected.cells[0].cellCount, 1);
+  raw.data[raw.keys[1]]['taxon.iconic_taxon_id'] = 999999;
+  assert.deepEqual(projectInatGrid(raw, tile), projected);
+});
+
+test('schema drift anywhere fails closed, including unused, malformed and orphan cells', () => {
+  const changes = [
+    (raw) => {
+      raw.grid.pop();
+    },
+    (raw) => {
+      raw.grid[0] = '';
+    },
+    (raw) => {
+      raw.grid[0] = '~'.repeat(64);
+    },
+    (raw) => {
+      raw.keys[0] = 'not-empty';
+    },
+    (raw) => {
+      raw.keys.push(raw.keys[1]);
+    },
+    (raw) => {
+      delete raw.data[raw.keys[1]];
+    },
+    (raw) => {
+      raw.data.extra = {};
+    },
+    (raw) => {
+      raw.data[raw.keys[1]].cellCount = -1;
+    },
+    (raw) => {
+      raw.data[raw.keys[1]].latitude = '47';
+    },
+    (raw) => {
+      raw.data[raw.keys[1]].longitude = 181;
+    },
+    (raw) => {
+      raw.data[raw.keys[1]].quality_grade = 'new-grade';
+    },
+    (raw) => {
+      delete raw.data[raw.keys[1]]['taxon.iconic_taxon_id'];
+    },
+    (raw) => {
+      raw.data[raw.keys[1]]['taxon.iconic_taxon_id'] = 'Aves';
+    },
+    (raw) => {
+      raw.grid = Array(64).fill(' '.repeat(64));
+    },
+  ];
+  for (const change of changes) {
+    const raw = syntheticGrid();
+    change(raw);
+    assert.throws(
+      () => projectInatGrid(raw, tile),
+      /Invalid iNaturalist UTFGrid/,
+    );
+  }
+});
+
+for (const hook of ['configureServer', 'configurePreviewServer']) {
+  test(`${hook}: fixed grid URL shares filters, caps and allow-list cache`, async () => {
+    const calls = [];
+    const cache = new Map();
+    const request = install(
+      {
+        cache,
+        fetchImpl: async (url, options) => {
+          calls.push(new URL(url));
+          assert.equal(options.redirect, 'error');
+          assert.ok(options.signal instanceof AbortSignal);
+          assert.match(
+            options.headers['User-Agent'],
+            /^gods-eye-view-wildlife-sightings-proxy/,
+          );
+          return Response.json(syntheticGrid());
+        },
+      },
+      hook,
+    );
+    assert.equal(calls.length, 0);
+    const response = await request(
+      `${gridUrl}&url=https://attacker.test&per_page=999`,
+    );
+    assert.equal(response.status, 200);
+    assert.equal(response.body.cells.length, 2);
+    assert.equal(response.body.fetchedAt, NOW);
+    assert.equal(response.headers['Cache-Control'], 'no-store');
+    assert.equal(
+      calls[0].origin + calls[0].pathname,
+      'https://api.inaturalist.org/v1/grid/2/1/1.grid.json',
+    );
+    assert.deepEqual(Object.fromEntries(calls[0].searchParams), {
+      verifiable: 'true',
+      captive: 'false',
+      d1: '2026-11-02',
+      photos: 'true',
+      quality_grade: 'research',
+      iconic_taxa: 'Aves',
+    });
+    await request(gridUrl);
+    assert.equal(calls.length, 1, 'fresh stable tile/filter key is cached');
+    assert.ok(!JSON.stringify([...cache]).includes('private_location'));
+    assert.ok(!JSON.stringify([...cache]).includes('900000000'));
+    const whale = await request('/grid?z=2&x=1&y=1&taxa=whales&confirmed=true');
+    assert.equal(whale.status, 200);
+    assert.equal(calls[1].searchParams.get('taxon_id'), '152871');
+    assert.equal(calls[1].searchParams.get('d1'), '2026-10-28');
+    assert.equal(calls[1].searchParams.has('photos'), false);
+  });
+}
+
+test('grid admission rejects cross-site/method/path/tile before acquisition', async () => {
+  const request = install({
+    fetchImpl() {
+      assert.fail('invalid grid request acquired');
+    },
+  });
+  assert.equal(
+    (
+      await request(gridUrl, {
+        headers: {
+          host: 'localhost:5173',
+          origin: 'https://other.test',
+          'sec-fetch-site': 'cross-site',
+        },
+      })
+    ).status,
+    403,
+  );
+  assert.equal((await request('/grid', { method: 'POST' })).status, 405);
+  assert.equal((await request('/grid/extra')).status, 404);
+  for (const query of [
+    '',
+    'z=2&x=4&y=0',
+    'z=-1&x=0&y=0',
+    'z=23&x=0&y=0',
+    'z=2&x=1.5&y=0',
+    'z=2&x=&y=0',
+    'z=2&x=0&y=4',
+  ]) {
+    const result = await request(`/grid?${query}`);
+    assert.equal(result.status, 400, query);
+    assert.equal(result.body.error, 'invalid_tile');
+  }
+});
+
+test('grid refresh single-flight, stale fallback and hour-key expiry keep the original age', async () => {
+  let time = NOW;
+  let calls = 0;
+  let resolve;
+  let mode = 'pending';
+  const request = install({
+    now: () => time,
+    fetchImpl: async () => {
+      calls += 1;
+      if (mode === 'pending')
+        return new Promise((done) => {
+          resolve = done;
+        });
+      if (mode === 'bad') return Response.json({ grid: [] });
+      return Response.json(syntheticGrid());
+    },
+  });
+  const first = request();
+  const second = request();
+  for (let i = 0; i < 100 && !resolve; i += 1) await new Promise(setImmediate);
+  assert.equal(calls, 1);
+  resolve(Response.json(syntheticGrid()));
+  assert.equal((await first).status, 200);
+  assert.equal((await second).status, 200);
+  time += 900_001;
+  mode = 'bad';
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, NOW);
+  assert.equal(stale.headers['X-Data-Stale'], 'true');
+  time = NOW + 3_600_001;
+  const expired = await request();
+  assert.equal(expired.status, 502);
+  assert.equal(expired.body.error, 'inaturalist_unavailable');
+});
+
+test('grid and observations share the upstream cooldown and daily reservations', async () => {
+  let calls = 0;
+  const client = createInatClient({
+    now: () => NOW,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0 },
+    warn() {},
+    fetchImpl: async () => {
+      calls += 1;
+      return new Response('', {
+        status: 429,
+        headers: { 'Retry-After': '120' },
+      });
+    },
+  });
+  await assert.rejects(
+    client.getGrid({ ...tile, taxa: 'all', observedD1: '2026-11-02' }),
+    (error) => error.status === 429 && error.retryAfterS === 120,
+  );
+  await assert.rejects(
+    client.getObservations({
+      scope: 'global',
+      taxa: 'all',
+      observedD1: '2026-11-02',
+    }),
+    (error) => error.status === 429,
+  );
+  assert.equal(calls, 1);
+  assert.equal(client.budgetState().count, 1);
+});
+
+test('grid body cap and upstream failures return fixed errors; only real 5xx cools down', async () => {
+  for (const [response, retryAfter] of [
+    [() => new Response('x'.repeat(8 * 1024 * 1024 + 1)), undefined],
+    [() => new Response('', { status: 503 }), '15'],
+  ]) {
+    const request = install({ fetchImpl: async () => response() });
+    const result = await request();
+    assert.equal(result.status, 502);
+    assert.deepEqual(result.body, { error: 'inaturalist_unavailable' });
+    assert.equal(result.headers['Retry-After'], retryAfter);
+  }
+});
+
+test('a failed tile preserves last good cells and cannot send unrelated observations into 502', async () => {
+  let at = NOW;
+  let failGrid = false;
+  const calls = [];
+  const warnings = [];
+  const request = install({
+    now: () => at,
+    warn: (message) => warnings.push(message),
+    fetchImpl: async (url) => {
+      const isGrid = new URL(url).pathname.includes('/grid/');
+      calls.push(isGrid ? 'grid' : 'observations');
+      if (isGrid && failGrid)
+        return new Response('private upstream text', {
+          status: 503,
+          headers: { 'Retry-After': '45' },
+        });
+      return Response.json(
+        isGrid ? syntheticGrid() : { results: [], total_results: 0 },
+      );
+    },
+  });
+  const first = await request();
+  at += 900_001;
+  failGrid = true;
+  const failed = await request();
+  assert.equal(failed.status, 200);
+  assert.equal(failed.headers['X-Data-Stale'], 'true');
+  assert.equal(failed.body.stale, true);
+  assert.equal(failed.body.fetchedAt, first.body.fetchedAt);
+  assert.deepEqual(failed.body.cells, first.body.cells);
+  assert.equal(
+    (await request('/observations?scope=global&taxa=whales')).status,
+    200,
+  );
+  assert.deepEqual(calls, ['grid', 'grid', 'observations']);
+  assert.match(warnings[0], /resource=grid status=503 reason=http/);
+  assert.doesNotMatch(warnings[0], /private upstream text/);
+  // The tile cooldown also preserves its data without another upstream try.
+  const cooling = await request();
+  assert.equal(cooling.body.stale, true);
+  assert.equal(cooling.headers['Retry-After'], '45');
+  assert.equal(cooling.headers['X-Upstream-Status'], '503');
+  assert.equal(calls.length, 3);
+  at += 45_000;
+  failGrid = false;
+  const refreshing = await request();
+  assert.equal(refreshing.body.stale, true);
+  await new Promise(setImmediate);
+  const recovered = await request();
+  assert.equal(recovered.status, 200);
+  assert.equal(recovered.body.stale, undefined);
+  assert.equal(
+    calls.length,
+    4,
+    'a failed queue task does not poison later tile work',
+  );
+});
+
+test('twelve queued tiles leave observation capacity and give the next dispatch to observations', async () => {
+  const calls = [];
+  let release;
+  const request = install({
+    fetchImpl: (url) => {
+      const path = new URL(url).pathname;
+      calls.push(path);
+      if (calls.length === 1)
+        return new Promise((resolve) => {
+          release = resolve;
+        });
+      return Response.json(
+        path.includes('/grid/')
+          ? syntheticGrid()
+          : { results: [], total_results: 0 },
+      );
+    },
+  });
+  const first = request('/grid?z=4&x=0&y=1');
+  for (let i = 0; i < 100 && !release; i += 1) await new Promise(setImmediate);
+  assert.ok(release);
+  const tiles = Array.from({ length: 11 }, (_, i) =>
+    request(`/grid?z=4&x=${i + 1}&y=1`),
+  );
+  const observation = request('/observations?scope=global');
+  const queuedTile = request('/grid?z=4&x=12&y=1');
+  release(Response.json(syntheticGrid()));
+  const results = await Promise.all([first, observation, ...tiles, queuedTile]);
+  assert.ok(results.every((result) => result.status === 200));
+  assert.equal(calls.length, 14);
+  assert.equal(calls[1], '/v2/observations');
+});
diff --git a/server/providers/inaturalist/observations.js b/server/providers/inaturalist/observations.js
new file mode 100644
index 000000000..1477dc1a8
--- /dev/null
+++ b/server/providers/inaturalist/observations.js
@@ -0,0 +1,343 @@
+import { createInatClient } from './client.js';
+import { coalesceProxyRequest } from '../common/http.js';
+import { admitSameSiteKeyless } from '../common/same-site.js';
+import { requiredFiniteQueryNumber } from '../common/query.js';
+import { snapWildlifeBox } from '../../../src/layers/wildlifeSightings/bounds.js';
+import { validInatGridTile } from './grid.js';
+
+// The upstream advertises five-minute freshness; global samples cost less often.
+const TTL_MS = 300_000;
+const GLOBAL_TTL_MS = 600_000;
+const INAT_GRID_CACHE_TTL_MS = 15 * 60_000;
+const STALE_MAX_MS = 3_600_000;
+const INAT_CACHE_MAX = 400;
+const HOUR_MS = 3_600_000;
+const TAXA = Object.freeze([
+  'all',
+  'Aves',
+  'Mammalia',
+  'Insecta',
+  'Plantae',
+  'whales',
+]);
+
+function requestParams(pathname, query, nowMs) {
+  const grid = pathname === '/grid';
+  const scope = grid ? 'grid' : (query.get('scope') ?? 'view');
+  if (!grid && scope !== 'view' && scope !== 'global')
+    return { error: 'invalid_scope' };
+  const quality =
+    query.get('quality') === 'research' ||
+    (grid && query.get('confirmed') === 'true')
+      ? 'research'
+      : 'all';
+  const taxa = TAXA.includes(query.get('taxa')) ? query.get('taxa') : 'all';
+  let box = null;
+  let tile;
+  if (grid) {
+    tile = Object.fromEntries(
+      ['z', 'x', 'y'].map((name) => [
+        name,
+        requiredFiniteQueryNumber(query, name),
+      ]),
+    );
+    if (!validInatGridTile(tile)) return { error: 'invalid_tile' };
+  } else if (scope === 'view') {
+    const south = requiredFiniteQueryNumber(query, 'south');
+    const west = requiredFiniteQueryNumber(query, 'west');
+    const north = requiredFiniteQueryNumber(query, 'north');
+    const east = requiredFiniteQueryNumber(query, 'east');
+    box = snapWildlifeBox({ south, west, north, east });
+    if (!box) return { error: 'invalid_bbox' };
+  }
+  const windowMs = (taxa === 'whales' ? 7 * 24 : 48) * HOUR_MS;
+  const windowKey = new Date(Math.floor((nowMs - windowMs) / HOUR_MS) * HOUR_MS)
+    .toISOString()
+    .replace('.000Z', 'Z');
+  const bounds = box ? `${box.south},${box.west},${box.north},${box.east}` : '';
+  const baseKey = grid
+    ? `grid:v1:${tile.z}/${tile.x}/${tile.y}:${quality}:${taxa}`
+    : `v1:${scope}:${bounds}:${quality}:${taxa}`;
+  return {
+    scope,
+    ...(grid
+      ? { ...tile, waitForFresh: query.get('refresh') === 'wait' }
+      : { box }),
+    quality,
+    taxa,
+    observedD1: windowKey.slice(0, 10),
+    baseKey,
+    key: `${baseKey}:${windowKey}`,
+  };
+}
+
+/** A shared-provider route for dev and preview; acquisition starts on demand. */
+export function inaturalistProxy({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+  cacheDir,
+  cache = new Map(),
+  warn = (...args) => console.warn(...args),
+  queueOptions,
+} = {}) {
+  const inFlight = new Map();
+  const consumers = new Map();
+  let client = null;
+
+  function age(entry) {
+    if (!entry) return Infinity;
+    const elapsed = now() - entry.savedAt;
+    return elapsed < 0 ? Infinity : elapsed;
+  }
+
+  function joinFlight(promise, group, signal) {
+    group.count += 1;
+    return new Promise((resolve, reject) => {
+      let released = false;
+      function release() {
+        if (released) return;
+        released = true;
+        signal?.removeEventListener('abort', abort);
+        group.count -= 1;
+        if (!group.count && !group.background && !group.settled) {
+          group.controller.abort();
+          // A fresh consumer must not join an abandoned queued generation.
+          if (inFlight.get(group.key) === promise) inFlight.delete(group.key);
+          if (consumers.get(group.key) === group) consumers.delete(group.key);
+        }
+      }
+      function abort() {
+        release();
+        reject(signal.reason);
+      }
+      signal?.addEventListener('abort', abort, { once: true });
+      if (signal?.aborted) abort();
+      promise.then(
+        (value) => {
+          release();
+          resolve(value);
+        },
+        (error) => {
+          release();
+          reject(error);
+        },
+      );
+    });
+  }
+
+  function refresh(params, background = false) {
+    // Global samples share pending refreshes across hourly window changes.
+    const flightKey = params.scope === 'global' ? params.baseKey : params.key;
+    let group = consumers.get(flightKey);
+    if (!group) {
+      group = {
+        key: flightKey,
+        controller: new AbortController(),
+        count: 0,
+        settled: false,
+        background,
+      };
+      consumers.set(flightKey, group);
+    }
+    group.background ||= background;
+    const { promise, shared } = coalesceProxyRequest(
+      inFlight,
+      flightKey,
+      async () => {
+        client ??= createInatClient({
+          fetchImpl,
+          now,
+          cacheDir,
+          warn,
+          queueOptions,
+        });
+        const options = { signal: group.controller.signal };
+        const result = await (params.scope === 'grid'
+          ? client.getGrid(params, options)
+          : client.getObservations(params, options));
+        const value = {
+          fetchedAt: now(),
+          ...(params.scope === 'grid'
+            ? {}
+            : { scope: params.scope, box: params.box }),
+          ...result,
+        };
+        cache.delete(params.key);
+        cache.set(params.key, {
+          value,
+          savedAt: now(),
+          baseKey: params.baseKey,
+        });
+        while (cache.size > INAT_CACHE_MAX)
+          cache.delete(cache.keys().next().value);
+        return value;
+      },
+    );
+    if (!shared) {
+      const settle = () => {
+        group.settled = true;
+        if (consumers.get(flightKey) === group) consumers.delete(flightKey);
+      };
+      void promise.then(settle, settle);
+    }
+    return { promise, group };
+  }
+
+  async function acquire(params, signal) {
+    signal?.throwIfAborted();
+    for (const [key, entry] of cache) {
+      if (age(entry) > STALE_MAX_MS) cache.delete(key);
+    }
+    const current = cache.get(params.key);
+    const ttl =
+      params.scope === 'grid'
+        ? INAT_GRID_CACHE_TTL_MS
+        : params.scope === 'global'
+          ? GLOBAL_TTL_MS
+          : TTL_MS;
+    if (current && age(current) < ttl) {
+      cache.delete(params.key);
+      cache.set(params.key, current);
+      return { value: current.value, stale: false };
+    }
+    // Window-hour rollover can reuse prior cells without claiming a new age.
+    let previous = current;
+    let previousKey = params.key;
+    if (!previous) {
+      for (const [key, entry] of cache) {
+        if (
+          entry.baseKey === params.baseKey &&
+          (!previous || entry.savedAt > previous.savedAt)
+        ) {
+          previous = entry;
+          previousKey = key;
+        }
+      }
+    }
+    if (params.scope === 'global' && age(previous) < GLOBAL_TTL_MS)
+      return { value: previous.value, stale: false };
+    if (
+      params.scope === 'grid' &&
+      !params.waitForFresh &&
+      age(previous) <= STALE_MAX_MS
+    ) {
+      cache.delete(previousKey);
+      cache.set(previousKey, previous);
+      // Retain one background consumer after this HTTP response closes. A stale
+      // tile is useful immediately; waiting for the token queue defeats SWR.
+      const cooling = client?.cooldownState('grid');
+      if (!cooling) {
+        const { promise } = refresh(params, true);
+        void promise.catch(() => {});
+      }
+      return {
+        value: previous.value,
+        stale: true,
+        ...cooling,
+      };
+    }
+    try {
+      const { promise, group } = refresh(params);
+      return { value: await joinFlight(promise, group, signal), stale: false };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      if (age(previous) <= STALE_MAX_MS)
+        return {
+          value: previous.value,
+          stale: true,
+          retryAfterS: error.retryAfterS,
+          upstreamStatus: error.upstreamStatus,
+        };
+      throw error;
+    }
+  }
+
+  async function handler(req, res) {
+    const json = (
+      status,
+      value,
+      { stale = false, retryAfterS, upstreamStatus } = {},
+    ) => {
+      if (res.destroyed) return;
+      res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+        ...(status === 405 ? { Allow: 'GET' } : {}),
+        ...(Number.isFinite(retryAfterS)
+          ? { 'Retry-After': String(retryAfterS) }
+          : {}),
+        ...(upstreamStatus
+          ? { 'X-Upstream-Status': String(upstreamStatus) }
+          : {}),
+        ...(stale ? { 'X-Data-Stale': 'true' } : {}),
+      });
+      res.end(JSON.stringify(value));
+    };
+    if (admitSameSiteKeyless(req, res)) return;
+    if (req.method !== 'GET') return json(405, { error: 'method_not_allowed' });
+    const url = String(req.url || '/');
+    const queryAt = url.indexOf('?');
+    const pathname = queryAt < 0 ? url : url.slice(0, queryAt);
+    if (pathname !== '/observations' && pathname !== '/grid')
+      return json(404, { error: 'unknown_route' });
+    const params = requestParams(
+      pathname,
+      new URLSearchParams(queryAt < 0 ? '' : url.slice(queryAt + 1)),
+      now(),
+    );
+    if (params.error) return json(400, { error: params.error });
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    // IncomingMessage.close also fires after a complete request body. The
+    // response close identifies the abandoned browser fetch, while aborted
+    // covers a request cut short before it reached the response stage.
+    req.once?.('aborted', abort);
+    res.once?.('close', abort);
+    try {
+      const { value, stale, retryAfterS, upstreamStatus } = await acquire(
+        params,
+        controller.signal,
+      );
+      return json(200, stale ? { ...value, stale: true } : value, {
+        stale,
+        retryAfterS,
+        upstreamStatus,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) return;
+      const status =
+        error.code === 'inaturalist_budget_exhausted'
+          ? 503
+          : error.status === 429
+            ? 429
+            : 502;
+      const code =
+        error.code === 'inaturalist_budget_exhausted'
+          ? error.code
+          : status === 429
+            ? 'inaturalist_rate_limited'
+            : 'inaturalist_unavailable';
+      return json(
+        status,
+        { error: code },
+        {
+          retryAfterS: error.retryAfterS,
+          upstreamStatus: error.upstreamStatus,
+        },
+      );
+    } finally {
+      req.removeListener?.('aborted', abort);
+      res.removeListener?.('close', abort);
+    }
+  }
+
+  return {
+    name: 'inaturalist',
+    configureServer({ middlewares }) {
+      middlewares.use('/api/inaturalist', handler);
+    },
+    configurePreviewServer({ middlewares }) {
+      middlewares.use('/api/inaturalist', handler);
+    },
+  };
+}
diff --git a/server/providers/inaturalist/observations.test.mjs b/server/providers/inaturalist/observations.test.mjs
new file mode 100644
index 000000000..1bf36a0f8
--- /dev/null
+++ b/server/providers/inaturalist/observations.test.mjs
@@ -0,0 +1,893 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { installInatProxy, NOW } from './proxy.fixture.mjs';
+import { createInatClient, inatRetryCooldownMs } from './client.js';
+
+const observation = (id = 1) => ({
+  id,
+  uri: `https://www.inaturalist.org/observations/${id}`,
+  geojson: { coordinates: [-122.351, 47.613] },
+  time_observed_at: '2026-11-04T17:00:00Z',
+  observed_on: '2026-11-04',
+  created_at: '2026-11-04T17:01:00Z',
+  quality_grade: 'research',
+  license_code: 'cc-by',
+  positional_accuracy: 12,
+  faves_count: 2,
+  num_identification_agreements: 3,
+  taxon: {
+    name: 'Calypte anna',
+    preferred_common_name: "Anna's hummingbird",
+    iconic_taxon_name: 'Aves',
+  },
+  photos: [
+    {
+      url: 'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpeg',
+      license_code: 'cc-by',
+      attribution: 'Synthetic photographer, CC BY',
+    },
+  ],
+  user: { login: 'must-never-leave-server' },
+});
+const envelope = (rows = [observation()], total = rows.length) => ({
+  total_results: total,
+  page: 1,
+  per_page: 200,
+  results: rows,
+});
+const boxUrl = (index = 0, extra = '') =>
+  `/observations?south=47.51&west=${-122.49 + index * 0.2}&north=47.69&east=${-122.31 + index * 0.2}${extra}`;
+
+function install(options = {}, hook = 'configureServer') {
+  return installInatProxy(
+    boxUrl(),
+    {
+      // Serial dispatch makes queued cancellation and coalescing observable.
+      queueOptions: { intervalMs: 0, windowMs: 0, maxInFlight: 1 },
+      ...options,
+    },
+    hook,
+  );
+}
+
+async function until(check) {
+  for (let i = 0; i < 100; i += 1) {
+    if (check()) return;
+    await new Promise(setImmediate);
+  }
+  assert.fail('expected fake upstream calls were not dispatched');
+}
+
+for (const hook of ['configureServer', 'configurePreviewServer']) {
+  test(`${hook}: actual v2 envelope, fixed query, projection and privacy`, async () => {
+    const calls = [];
+    const cache = new Map();
+    const request = install(
+      {
+        cache,
+        fetchImpl: async (url, options) => {
+          calls.push(new URL(url));
+          assert.equal(options.redirect, 'error');
+          assert.ok(options.signal instanceof AbortSignal);
+          assert.equal(options.headers.Accept, 'application/json');
+          assert.equal(
+            options.headers['User-Agent'],
+            'gods-eye-view-wildlife-sightings-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)',
+          );
+          return Response.json(envelope());
+        },
+      },
+      hook,
+    );
+    assert.equal(calls.length, 0, 'construction and mounting do not acquire');
+    const result = await request(
+      boxUrl(0, '&url=https://attacker.example&per_page=999'),
+    );
+    assert.equal(result.status, 200);
+    assert.equal(result.headers['Cache-Control'], 'no-store');
+    assert.equal(result.body.rows[0].stableId, 'inat:1');
+    assert.equal(result.body.fetchedAt, NOW);
+    assert.equal(result.body.scope, 'view');
+    assert.deepEqual(result.body.box, {
+      south: 47.5,
+      west: -122.5,
+      north: 47.7,
+      east: -122.3,
+    });
+    const query = calls[0].searchParams;
+    assert.equal(
+      calls[0].origin + calls[0].pathname,
+      'https://api.inaturalist.org/v2/observations',
+    );
+    // Only the projected fields are requested, never user or identification data.
+    assert.match(query.get('fields'), /^\(id:!t,uri:!t,.*photos:\(url:!t/);
+    assert.doesNotMatch(query.get('fields'), /user|identifications/);
+    assert.equal(query.get('swlat'), '47.5');
+    assert.equal(query.get('swlng'), '-122.5');
+    assert.equal(query.get('nelat'), '47.7');
+    assert.equal(query.get('nelng'), '-122.3');
+    assert.equal(query.get('d1'), '2026-11-02');
+    assert.equal(query.has('created_d1'), false);
+    assert.equal(query.get('per_page'), '200');
+    assert.equal(query.get('verifiable'), 'true');
+    assert.equal(query.get('photos'), 'true');
+    assert.equal(query.get('captive'), 'false');
+    assert.equal(query.get('order_by'), 'random');
+    assert.equal(query.has('order'), false);
+    assert.doesNotMatch(
+      JSON.stringify(result.body),
+      /must-never-leave-server|"user"/,
+    );
+    assert.doesNotMatch(
+      JSON.stringify([...cache.values()]),
+      /must-never-leave-server|"user"/,
+    );
+  });
+}
+
+test('gate, method, route and query validation run before quota, cache or upstream', async () => {
+  const cache = new Map();
+  let calls = 0;
+  const request = install({
+    cache,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  for (let i = 0; i < 32; i += 1) {
+    const response = await request('/observations?scope=global', {
+      headers: {
+        host: 'localhost:5173',
+        origin: 'https://foreign.example',
+        'sec-fetch-site': 'cross-site',
+      },
+    });
+    assert.equal(response.status, 403);
+  }
+  const method = await request('/observations', { method: 'POST' });
+  assert.equal(method.status, 405);
+  assert.equal(method.headers.Allow, 'GET');
+  for (const route of ['/', '/unknown', '/observations/extra', '//[invalid'])
+    assert.equal((await request(route)).body.error, 'unknown_route');
+  assert.equal(
+    (await request('/observations?scope=planet')).body.error,
+    'invalid_scope',
+  );
+  for (const query of [
+    '',
+    'south=NaN&west=0&north=1&east=1',
+    'south=&west=0&north=1&east=1',
+    'south=0&west=0&north=0&east=1',
+    'south=0&west=1&north=1&east=0',
+    'south=-91&west=0&north=1&east=1',
+    'south=0&west=-181&north=1&east=1',
+    'south=0&west=0&north=41&east=1',
+    'south=0&west=0&north=1&east=41',
+  ]) {
+    const result = await request(`/observations?${query}`);
+    assert.equal(result.status, 400, query);
+    assert.equal(result.body.error, 'invalid_bbox', query);
+  }
+  assert.equal(cache.size, 0);
+  assert.equal(calls, 0);
+  const allowed = await request('/observations?scope=global', {
+    headers: {
+      host: 'gev.example',
+      origin: 'https://gev.example',
+      'sec-fetch-site': 'same-origin',
+      'x-forwarded-proto': 'https',
+      'x-forwarded-for': '203.0.113.9',
+    },
+  });
+  assert.equal(allowed.status, 200);
+});
+
+test('cached requests never exhaust a local request admission limiter', async () => {
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  for (let i = 0; i < 30; i += 1) assert.equal((await request()).status, 200);
+  const cached = await request();
+  assert.equal(cached.status, 200);
+  assert.equal(cached.headers['Retry-After'], undefined);
+  assert.equal(calls, 1);
+});
+
+test('proxy rejects oversized snapped spans before acquisition and preserves canonical client boxes', async () => {
+  const urls = [];
+  const request = install({
+    fetchImpl: async (url) => {
+      urls.push(new URL(url));
+      return Response.json(envelope());
+    },
+  });
+  for (const query of [
+    'south=10.2&west=0&north=50.1&east=1',
+    'south=0&west=10.2&north=1&east=50.1',
+  ]) {
+    const result = await request(`/observations?${query}`);
+    assert.equal(result.status, 400);
+    assert.equal(result.body.error, 'invalid_bbox');
+  }
+  assert.equal(urls.length, 0);
+  const canonical =
+    '/observations?south=47.4&west=-122.3&north=47.6&east=-122.1';
+  const first = await request(canonical);
+  assert.equal(first.status, 200);
+  assert.deepEqual(first.body.box, {
+    south: 47.4,
+    west: -122.3,
+    north: 47.6,
+    east: -122.1,
+  });
+  assert.equal(urls[0].searchParams.get('swlat'), '47.4');
+  assert.equal(urls[0].searchParams.get('swlng'), '-122.3');
+  const second = await request(canonical);
+  assert.deepEqual(second.body, first.body);
+  assert.equal(urls.length, 1, 'canonical boxes share their cache key');
+});
+
+test('view snapping, whales, research and global queries obey the requested policy', async () => {
+  const urls = [];
+  const request = install({
+    fetchImpl: async (url) => {
+      urls.push(new URL(url));
+      return Response.json(envelope());
+    },
+  });
+  await request(
+    '/observations?south=40.2&west=-123.7&north=46.1&east=-121.4&quality=research&taxa=Aves',
+  );
+  assert.equal(urls[0].searchParams.get('swlat'), '40');
+  assert.equal(urls[0].searchParams.get('nelat'), '47');
+  assert.equal(urls[0].searchParams.get('per_page'), '200');
+  assert.equal(urls[0].searchParams.get('quality_grade'), 'research');
+  assert.equal(urls[0].searchParams.get('iconic_taxa'), 'Aves');
+  await request(boxUrl(0, '&taxa=whales'));
+  const whales = urls[1].searchParams;
+  assert.equal(whales.get('taxon_id'), '152871');
+  assert.equal(whales.get('d1'), '2026-10-28');
+  assert.equal(whales.has('created_d1'), false);
+  assert.equal(whales.has('photos'), false);
+  assert.equal(whales.has('iconic_taxa'), false);
+  await request('/observations?scope=global&quality=typo&taxa=typo&south=bad');
+  const global = urls[2].searchParams;
+  for (const field of [
+    'swlat',
+    'swlng',
+    'nelat',
+    'nelng',
+    'quality_grade',
+    'iconic_taxa',
+  ])
+    assert.equal(global.has(field), false, field);
+  assert.equal(global.get('per_page'), '200');
+  assert.equal(global.get('d1'), '2026-11-02');
+  assert.equal(global.has('created_d1'), false);
+  assert.equal(global.get('order_by'), 'observed_on');
+  assert.equal(global.get('order'), 'desc');
+  await request('/observations?scope=global&taxa=whales');
+  const globalWhales = urls[3].searchParams;
+  assert.equal(globalWhales.get('d1'), '2026-10-28');
+  assert.equal(globalWhales.has('created_d1'), false);
+  assert.equal(globalWhales.get('order_by'), 'observed_on');
+  assert.equal(globalWhales.get('order'), 'desc');
+});
+
+test('fresh cache hits and global ten-minute TTL spend no upstream quota', async () => {
+  let at = NOW;
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  const first = await request();
+  at += 299_999;
+  assert.deepEqual((await request()).body, first.body);
+  at += 1;
+  await request();
+  assert.equal(calls, 2);
+  await request('/observations?scope=global');
+  at += 599_999;
+  await request('/observations?scope=global');
+  assert.equal(calls, 3);
+  at += 1;
+  await request('/observations?scope=global');
+  assert.equal(calls, 4);
+});
+
+test('the same snapped view and window hour returns one cached random sample until expiry', async () => {
+  let at = NOW;
+  let draws = 0;
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: async (url) => {
+      const query = new URL(url).searchParams;
+      assert.equal(query.get('order_by'), 'random');
+      assert.equal(query.get('per_page'), '200');
+      return Response.json(envelope([observation(++draws)]));
+    },
+  });
+  const first = await request();
+  for (const elapsed of [1, 1000, 60_000, 299_999]) {
+    at = NOW + elapsed;
+    const next = await request();
+    assert.deepEqual(next.body, first.body);
+  }
+  assert.equal(draws, 1);
+  assert.match(cache.keys().next().value, /2026-11-02T18:00:00Z$/);
+  at = NOW + 300_000;
+  const refresh = await request();
+  assert.equal(refresh.body.rows[0].stableId, 'inat:2');
+  assert.equal(draws, 2);
+});
+
+test('disconnected queued views are dropped while a remaining coalesced consumer keeps its request', async () => {
+  const calls = [];
+  const releases = [];
+  const cache = new Map();
+  const request = install({
+    cache,
+    fetchImpl: (url, { signal }) => {
+      calls.push({ url: new URL(url), signal });
+      return new Promise((resolve) => releases.push(resolve));
+    },
+  });
+  const first = request(boxUrl(0));
+  await until(() => releases.length === 1);
+  const superseded = new AbortController();
+  const oldView = request(boxUrl(1), { signal: superseded.signal });
+  const oneConsumer = new AbortController();
+  const one = request(boxUrl(2), { signal: oneConsumer.signal });
+  const other = request(boxUrl(2));
+  superseded.abort();
+  oneConsumer.abort();
+  await Promise.all([oldView, one]);
+  // Rejoining the abandoned key creates a healthy generation; the old
+  // coalescing promise must not later delete or cancel this replacement.
+  const replacement = request(boxUrl(1));
+  releases[0](Response.json(envelope()));
+  await until(() => releases.length === 2);
+  assert.equal(calls[1].url.searchParams.get('swlng'), '-122.1');
+  assert.equal(calls[1].signal.aborted, false);
+  releases[1](Response.json(envelope([observation(2)])));
+  await until(() => releases.length === 3);
+  assert.equal(calls[2].url.searchParams.get('swlng'), '-122.3');
+  releases[2](Response.json(envelope([observation(3)])));
+  const results = await Promise.all([first, other, replacement]);
+  assert.ok(results.every((result) => result.status === 200));
+  assert.equal(
+    calls.length,
+    3,
+    'the abandoned queued generation never dispatched',
+  );
+  assert.equal(cache.size, 3);
+  assert.equal(results[1].body.rows[0].stableId, 'inat:2');
+  assert.equal(results[2].body.rows[0].stableId, 'inat:3');
+});
+
+test('observation windows reject old sightings uploaded today and keep recent observations', async () => {
+  for (const [taxa, recentTime, expectedD1] of [
+    ['all', '2026-11-04T17:00:00Z', '2026-11-02'],
+    ['whales', '2026-10-30T17:00:00Z', '2026-10-28'],
+  ]) {
+    let upstreamQuery;
+    const request = install({
+      fetchImpl: async (url) => {
+        upstreamQuery = new URL(url).searchParams;
+        return Response.json(
+          envelope([
+            {
+              ...observation(80),
+              time_observed_at: '2010-06-01T12:00:00Z',
+              observed_on: '2010-06-01',
+            },
+            {
+              ...observation(81),
+              time_observed_at: recentTime,
+              observed_on: recentTime.slice(0, 10),
+            },
+          ]),
+        );
+      },
+    });
+    const result = await request(boxUrl(0, `&taxa=${taxa}`));
+    assert.equal(result.status, 200, taxa);
+    assert.equal(upstreamQuery.get('d1'), expectedD1);
+    assert.equal(upstreamQuery.has('created_d1'), false);
+    assert.equal(upstreamQuery.get('order_by'), 'random');
+    assert.deepEqual(
+      result.body.rows.map((row) => row.stableId),
+      ['inat:81'],
+    );
+  }
+});
+
+test('same-key requests single-flight and a seventeenth distinct in-flight key queues', async () => {
+  const releases = [];
+  const request = install({
+    fetchImpl: () => new Promise((resolve) => releases.push(resolve)),
+  });
+  const a = request();
+  const b = request();
+  await until(() => releases.length === 1);
+  releases.shift()(Response.json(envelope()));
+  assert.deepEqual((await a).body, (await b).body);
+  const pending = Array.from({ length: 16 }, (_, i) => request(boxUrl(i + 1)));
+  await until(() => releases.length === 1);
+  pending.push(request(boxUrl(18)));
+  for (let i = 0; i < 17; i += 1) {
+    await until(() => releases.length > i);
+    releases[i](Response.json(envelope()));
+  }
+  assert.ok((await Promise.all(pending)).every(({ status }) => status === 200));
+});
+
+test('a fresh global sample survives the hourly observation-window rollover without another fetch', async () => {
+  let at = Date.parse('2026-11-04T18:59:00Z');
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  const first = await request('/observations?scope=global');
+  at += 60_000;
+  const nextHour = await request('/observations?scope=global');
+  assert.deepEqual(nextHour.body, first.body);
+  assert.equal(nextHour.body.stale, undefined);
+  assert.equal(calls, 1);
+  at += 9 * 60_000;
+  await request('/observations?scope=global');
+  assert.equal(calls, 2);
+});
+
+test('pending global refresh coalesces across the hourly observation-window rollover with a busy queue', async () => {
+  let at = Date.parse('2026-11-04T18:59:59Z');
+  const releases = [];
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: (url) =>
+      new Promise((resolve) =>
+        releases.push({
+          resolve,
+          url: new URL(url),
+        }),
+      ),
+  });
+  const first = request(
+    '/observations?scope=global&quality=research&taxa=Aves',
+  );
+  const views = Array.from({ length: 15 }, (_, i) => request(boxUrl(i)));
+  await until(() => releases.length === 1);
+  assert.equal(releases[0].url.searchParams.get('d1'), '2026-11-02');
+  at = Date.parse('2026-11-04T19:00:01Z');
+  const nextHour = request(
+    '/observations?scope=global&quality=research&taxa=Aves',
+  );
+  await new Promise(setImmediate);
+  assert.equal(
+    releases.length,
+    1,
+    'the same global query joins the pending refresh',
+  );
+  const distinct = request(
+    '/observations?scope=global&quality=research&taxa=Mammalia',
+  );
+  for (let i = 0; i < 17; i += 1) {
+    await until(() => releases.length > i);
+    releases[i].resolve(Response.json(envelope()));
+  }
+  const [original, joined] = await Promise.all([first, nextHour]);
+  assert.equal(original.status, 200);
+  assert.equal((await distinct).status, 200);
+  assert.deepEqual(joined.body, original.body);
+  assert.ok((await Promise.all(views)).every(({ status }) => status === 200));
+  const globalEntries = [...cache.entries()].filter(
+    ([, entry]) => entry.value.scope === 'global',
+  );
+  assert.equal(globalEntries.length, 2);
+  assert.match(globalEntries[0][0], /2026-11-02T18:00:00Z$/);
+  assert.equal(
+    (await request('/observations?scope=global&quality=research&taxa=Aves'))
+      .status,
+    200,
+  );
+  assert.equal(
+    releases.length,
+    17,
+    'the accepted global answer keeps its ten-minute freshness',
+  );
+});
+
+test('view refreshes retain distinct hourly keys while a previous-hour request is pending', async () => {
+  let at = Date.parse('2026-11-04T18:59:59Z');
+  const releases = [];
+  const request = install({
+    now: () => at,
+    fetchImpl: () => new Promise((resolve) => releases.push(resolve)),
+  });
+  const first = request();
+  await until(() => releases.length === 1);
+  at = Date.parse('2026-11-04T19:00:01Z');
+  const nextHour = request();
+  await new Promise(setImmediate);
+  assert.equal(
+    releases.length,
+    1,
+    'the next view queues behind the current call',
+  );
+  releases[0](Response.json(envelope()));
+  await until(() => releases.length === 2);
+  releases[1](Response.json(envelope()));
+  assert.ok(
+    (await Promise.all([first, nextHour])).every(
+      ({ status }) => status === 200,
+    ),
+  );
+});
+
+test('upstream minute ceiling waits for request 61 across client addresses', async () => {
+  let at = NOW;
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    queueOptions: {
+      now: () => at,
+      intervalMs: 0,
+      wait: async (ms) => {
+        at += ms;
+      },
+    },
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  for (let i = 0; i < 60; i += 1)
+    assert.equal(
+      (await request(boxUrl(i), { peer: `10.0.0.${i}` })).status,
+      200,
+    );
+  const queued = await request(boxUrl(60), { peer: '10.0.1.1' });
+  assert.equal(queued.status, 200);
+  assert.equal(queued.headers['Retry-After'], undefined);
+  assert.equal(at, NOW + 60_000);
+  assert.equal(calls, 61);
+});
+
+test('views refresh after many prior requests without fabricating an upstream limit', async () => {
+  let at = NOW;
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  const first = await request();
+  at += 300_001;
+  for (let i = 1; i <= 60; i += 1)
+    await request(boxUrl(i), { peer: `10.0.0.${i}` });
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, undefined);
+  assert.notEqual(stale.body.fetchedAt, first.body.fetchedAt);
+  assert.equal(calls, 62);
+});
+
+test('bounded samples preserve partial metadata, and well-formed empty views are valid', async () => {
+  let at = NOW;
+  let fail = false;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () =>
+      fail
+        ? new Response('unavailable', { status: 503 })
+        : Response.json(envelope([observation()], 500)),
+  });
+  const first = await request();
+  assert.equal(first.body.partial, true);
+  assert.equal(first.body.rawRowCount, 500);
+  fail = true;
+  at += 59 * 60_000;
+  const stale = await request();
+  assert.equal(
+    stale.status,
+    200,
+    'hourly window changes still permit stale fallback',
+  );
+  assert.equal(stale.headers['X-Data-Stale'], 'true');
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, first.body.fetchedAt);
+  assert.equal(stale.body.partial, true);
+  at += 2 * 60_000;
+  const expired = await request();
+  assert.equal(expired.status, 502);
+  assert.equal(expired.body.error, 'inaturalist_unavailable');
+  const empty = install({
+    fetchImpl: async () => Response.json(envelope([], 0)),
+  });
+  const result = await empty();
+  assert.equal(result.status, 200);
+  assert.deepEqual(result.body.rows, []);
+});
+
+test('bad envelopes, JSON and capped bodies fail closed without inventing a cooldown', async () => {
+  for (const bad of [
+    () => Response.json({ total_results: 1, results: {} }),
+    () => Response.json({ total_results: 1, observations: [observation()] }),
+    () => Response.json({ total_results: '1', results: [observation()] }),
+    () => Response.json(envelope([], 1)),
+    () => Response.json(envelope([{ ...observation(), id: null }], 1)),
+    () => new Response('{malformed'),
+    () =>
+      new Response('{}', {
+        headers: { 'Content-Length': String(8 * 1024 * 1024 + 1) },
+      }),
+  ]) {
+    let at = NOW;
+    let calls = 0;
+    const request = install({
+      now: () => at,
+      fetchImpl: async () => {
+        calls += 1;
+        return calls === 1 ? bad() : Response.json(envelope());
+      },
+    });
+    const first = await request();
+    assert.equal(first.status, 502);
+    assert.equal(first.body.error, 'inaturalist_unavailable');
+    assert.equal(first.headers['Retry-After'], undefined);
+    assert.equal((await request(boxUrl(1))).status, 200);
+    assert.equal(calls, 2);
+  }
+});
+
+test('a wholly invalid iNat page cannot replace a previously valid snapshot', async () => {
+  let at = NOW;
+  let fail = false;
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: async () =>
+      Response.json(
+        fail
+          ? envelope([{ ...observation(), quality_grade: 'casual' }])
+          : envelope(),
+      ),
+  });
+  const first = await request();
+  const original = cache.values().next().value;
+  fail = true;
+  at += 300_001;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, first.body.fetchedAt);
+  assert.equal(cache.values().next().value, original);
+});
+
+test('429 cooldown honors seconds, HTTP dates, and long upstream deadlines', async () => {
+  assert.equal(inatRetryCooldownMs(null, NOW), 60_000);
+  assert.equal(inatRetryCooldownMs('0', NOW), 0);
+  assert.equal(inatRetryCooldownMs('2', NOW), 2000);
+  assert.equal(inatRetryCooldownMs('999999', NOW), 999_999_000);
+  assert.equal(inatRetryCooldownMs('7200', NOW), 7_200_000);
+  assert.equal(
+    inatRetryCooldownMs(new Date(NOW + 7_200_000).toUTCString(), NOW),
+    7_200_000,
+  );
+  let at = NOW;
+  const releases = [];
+  const warnings = [];
+  const request = install({
+    now: () => at,
+    warn: (message) => warnings.push(message),
+    fetchImpl: () => new Promise((resolve) => releases.push(resolve)),
+  });
+  const first = request();
+  const later = request(boxUrl(1));
+  await until(() => releases.length === 1);
+  releases[0](
+    new Response('limit', {
+      status: 429,
+      headers: { 'Retry-After': '999999' },
+    }),
+  );
+  assert.equal((await first).headers['Retry-After'], '999999');
+  assert.equal((await later).headers['Retry-After'], '999999');
+  at += 1000;
+  assert.equal((await request(boxUrl(1))).headers['Retry-After'], '999998');
+  at += 5000;
+  const cooling = await request(boxUrl(2));
+  assert.equal(cooling.status, 429);
+  assert.equal(cooling.headers['Retry-After'], '999993');
+  assert.equal(
+    releases.length,
+    1,
+    'queued calls do not dispatch during cooldown',
+  );
+  assert.equal(
+    warnings.filter((message) => message.includes('capped')).length,
+    0,
+  );
+});
+
+for (const [upstreamStatus, expectedStatus, code, retryAfterS] of [
+  [429, 429, 'inaturalist_rate_limited', 120],
+  [503, 502, 'inaturalist_unavailable', 120],
+]) {
+  test(`concurrent reservations honor an immediate upstream ${upstreamStatus} before dispatch`, async () => {
+    let calls = 0;
+    const warnings = [];
+    const client = createInatClient({
+      now: () => 0,
+      cacheDir: null,
+      queueOptions: { intervalMs: 0 },
+      warn: (message) => warnings.push(message),
+      fetchImpl: async () => {
+        calls += 1;
+        return new Response('synthetic failure', {
+          status: upstreamStatus,
+          headers: { 'Retry-After': '120' },
+        });
+      },
+    });
+    const params = {
+      scope: 'global',
+      quality: 'all',
+      taxa: 'all',
+      observedD1: '1969-12-30',
+    };
+    const results = await Promise.allSettled(
+      Array.from({ length: 3 }, () => client.getObservations(params)),
+    );
+    assert.equal(
+      calls,
+      1,
+      'pending reservations must not dispatch during cooldown',
+    );
+    for (const result of results) {
+      assert.equal(result.status, 'rejected');
+      assert.equal(result.reason.status, expectedStatus);
+      assert.equal(result.reason.code, code);
+      assert.equal(result.reason.retryAfterS, retryAfterS);
+    }
+    assert.equal(
+      warnings.length,
+      1,
+      'only the dispatched refresh logs a failure',
+    );
+    await assert.rejects(client.getObservations(params), {
+      status: expectedStatus,
+      code,
+      retryAfterS,
+    });
+    assert.equal(calls, 1);
+  });
+}
+
+test('budget is read lazily, persisted as counters only, enforced across restart and UTC rollover', async (t) => {
+  const parent = await mkdtemp(path.join(os.tmpdir(), 'gev-inat-budget-'));
+  t.after(() => rm(parent, { recursive: true, force: true }));
+  const cacheDir = path.join(parent, 'not-created');
+  const before = process.env.INATURALIST_DAILY_BUDGET;
+  process.env.INATURALIST_DAILY_BUDGET = '2';
+  t.after(() =>
+    before === undefined
+      ? delete process.env.INATURALIST_DAILY_BUDGET
+      : (process.env.INATURALIST_DAILY_BUDGET = before),
+  );
+  let at = NOW;
+  let calls = 0;
+  const options = {
+    now: () => at,
+    cacheDir,
+    warn() {},
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  };
+  const client = createInatClient(options);
+  assert.deepEqual(
+    await readdir(parent),
+    [],
+    'construction performs no directory write',
+  );
+  const params = {
+    scope: 'global',
+    quality: 'all',
+    taxa: 'all',
+    observedD1: '2026-11-02',
+  };
+  await Promise.all([
+    client.getObservations(params),
+    client.getObservations(params),
+  ]);
+  assert.deepEqual(
+    JSON.parse(await readFile(path.join(cacheDir, 'budget.json'), 'utf8')),
+    { date: '2026-11-04', count: 2 },
+  );
+  assert.deepEqual(
+    await readdir(cacheDir),
+    ['budget.json'],
+    'atomic temporary files are retired',
+  );
+  const restarted = createInatClient(options);
+  await assert.rejects(restarted.getObservations(params), {
+    status: 503,
+    code: 'inaturalist_budget_exhausted',
+  });
+  assert.equal(calls, 2);
+  at = Date.parse('2026-11-05T00:00:00Z');
+  await restarted.getObservations(params);
+  assert.deepEqual(restarted.budgetState(), {
+    date: '2026-11-05',
+    count: 1,
+    budget: 2,
+  });
+  assert.deepEqual(
+    JSON.parse(await readFile(path.join(cacheDir, 'budget.json'), 'utf8')),
+    { date: '2026-11-05', count: 1 },
+  );
+  assert.equal(calls, 3);
+});
+
+test('memory cache is an LRU bounded to 400 projected entries', async () => {
+  let at = NOW;
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: async () => Response.json(envelope()),
+  });
+  for (let i = 0; i < 400; i += 1) {
+    if (i && i % 20 === 0) at += 61_000;
+    await request(boxUrl(i), { peer: String(i) });
+  }
+  assert.equal(cache.size, 400);
+  const firstKey = cache.keys().next().value;
+  const secondKey = [...cache.keys()][1];
+  await request(boxUrl(0));
+  await request(boxUrl(400));
+  assert.equal(cache.size, 400);
+  assert.equal(cache.has(firstKey), true);
+  assert.equal(cache.has(secondKey), false);
+});
+
+test('aborted client calls spend no budget and never fetch', async () => {
+  const controller = new AbortController();
+  controller.abort();
+  const client = createInatClient({
+    now: () => NOW,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0 },
+    fetchImpl: () => assert.fail('aborted call fetched'),
+  });
+  await assert.rejects(
+    client.getObservations({}, { signal: controller.signal }),
+    { name: 'AbortError' },
+  );
+  assert.equal(client.budgetState().count, 0);
+});
diff --git a/server/providers/inaturalist/proxy.fixture.mjs b/server/providers/inaturalist/proxy.fixture.mjs
new file mode 100644
index 000000000..8df662749
--- /dev/null
+++ b/server/providers/inaturalist/proxy.fixture.mjs
@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { inaturalistProxy } from './observations.js';
+
+export const NOW = Date.parse('2026-11-04T18:05:00Z');
+
+/** Mount the proxy over synthetic HTTP objects, without opening a socket. */
+export function installInatProxy(
+  defaultUrl,
+  options = {},
+  hook = 'configureServer',
+) {
+  let handler;
+  const plugin = inaturalistProxy({
+    now: () => NOW,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0, windowMs: 0 },
+    warn() {},
+    ...options,
+  });
+  assert.equal(plugin.name, 'inaturalist');
+  assert.equal(typeof plugin.configureServer, 'function');
+  assert.equal(typeof plugin.configurePreviewServer, 'function');
+  plugin[hook]({
+    middlewares: {
+      use(mount, callback) {
+        assert.equal(mount, '/api/inaturalist');
+        handler = callback;
+      },
+    },
+  });
+  return async (
+    url = defaultUrl,
+    { method = 'GET', peer = 'local', headers = {}, signal } = {},
+  ) => {
+    const res = Object.assign(new EventEmitter(), {
+      headers: {},
+      writeHead(status, headers) {
+        this.status = status;
+        Object.assign(this.headers, headers);
+      },
+      setHeader(key, value) {
+        this.headers[key] = value;
+      },
+      end(value) {
+        this.status ??= this.statusCode;
+        this.body = JSON.parse(value);
+      },
+    });
+    const abort = () => {
+      res.destroyed = true;
+      res.emit('close');
+    };
+    signal?.addEventListener('abort', abort, { once: true });
+    try {
+      await handler(
+        Object.assign(new EventEmitter(), {
+          url,
+          method,
+          headers,
+          socket: { remoteAddress: peer },
+        }),
+        res,
+      );
+    } finally {
+      signal?.removeEventListener('abort', abort);
+    }
+    return res;
+  };
+}
diff --git a/server/providers/inaturalist/queue.js b/server/providers/inaturalist/queue.js
new file mode 100644
index 000000000..fb449615a
--- /dev/null
+++ b/server/providers/inaturalist/queue.js
@@ -0,0 +1,109 @@
+import { setTimeout as delay } from 'node:timers/promises';
+
+// A four-request burst keeps a cold view responsive; thereafter every provider
+// call shares the same one-per-second token supply. The rolling minute ceiling
+// queues the few requests a token bucket alone could allow above 60/min.
+const INAT_INTERVAL_MS = 1000;
+const INAT_BURST = 4;
+const INAT_WINDOW_MS = 60_000;
+const INAT_MAX_PER_WINDOW = 60;
+const INAT_MAX_IN_FLIGHT = 4;
+
+/** Observation queries outrank tiles waiting for a token. Aborted consumers
+ * leave the queue before an attempt or daily-budget reservation is spent. */
+export function createInatQueue({
+  now = () => performance.now(),
+  wait = (ms) => delay(ms),
+  intervalMs = INAT_INTERVAL_MS,
+  burst = INAT_BURST,
+  windowMs = INAT_WINDOW_MS,
+  maxInFlight = INAT_MAX_IN_FLIGHT,
+} = {}) {
+  const pending = [];
+  const dispatchedAt = [];
+  let tokens = burst;
+  let refilledAt = null;
+  let running = false;
+  let inFlight = 0;
+  let slotFreed = null;
+
+  function refill() {
+    const at = now();
+    if (refilledAt !== null && intervalMs > 0)
+      tokens = Math.min(
+        burst,
+        tokens + Math.max(0, at - refilledAt) / intervalMs,
+      );
+    if (intervalMs <= 0) tokens = burst;
+    refilledAt = at;
+  }
+
+  function schedule() {
+    if (running) return;
+    running = true;
+    // A microtask also lets same-turn observation queries take priority.
+    void Promise.resolve().then(drain);
+  }
+
+  async function drain() {
+    try {
+      while (pending.length) {
+        if (inFlight >= maxInFlight) {
+          await new Promise((resolve) => (slotFreed = resolve));
+          continue;
+        }
+        refill();
+        const at = now();
+        while (dispatchedAt.length && dispatchedAt[0] <= at - windowMs)
+          dispatchedAt.shift();
+        const tokenWait = tokens < 1 ? (1 - tokens) * intervalMs : 0;
+        const windowWait =
+          windowMs > 0 && dispatchedAt.length >= INAT_MAX_PER_WINDOW
+            ? dispatchedAt[0] + windowMs - at
+            : 0;
+        if (tokenWait > 0 || windowWait > 0) {
+          await wait(Math.ceil(Math.max(tokenWait, windowWait)));
+          continue;
+        }
+        // Stable sorting preserves FIFO order within each priority.
+        pending.sort((a, b) => a.priority - b.priority);
+        const job = pending.shift();
+        job.signal?.removeEventListener('abort', job.abort);
+        if (job.signal?.aborted) {
+          job.reject(job.signal.reason);
+          continue;
+        }
+        tokens -= 1;
+        if (windowMs > 0) dispatchedAt.push(at);
+        inFlight += 1;
+        // A rejected task releases its slot without stopping the queue.
+        void new Promise((resolve) => resolve(job.task()))
+          .then(job.resolve, job.reject)
+          .finally(() => {
+            inFlight -= 1;
+            const wake = slotFreed;
+            slotFreed = null;
+            wake?.();
+          });
+      }
+    } finally {
+      running = false;
+    }
+  }
+
+  return function enqueue(task, { signal, priority = 1 } = {}) {
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+      const job = { task, signal, priority, resolve, reject };
+      job.abort = () => {
+        const index = pending.indexOf(job);
+        if (index >= 0) pending.splice(index, 1);
+        signal.removeEventListener('abort', job.abort);
+        reject(signal.reason);
+      };
+      signal?.addEventListener('abort', job.abort, { once: true });
+      pending.push(job);
+      schedule();
+    });
+  };
+}
diff --git a/server/providers/inaturalist/queue.test.mjs b/server/providers/inaturalist/queue.test.mjs
new file mode 100644
index 000000000..a017883a8
--- /dev/null
+++ b/server/providers/inaturalist/queue.test.mjs
@@ -0,0 +1,111 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createInatQueue } from './queue.js';
+
+async function until(check) {
+  for (let i = 0; i < 100; i += 1) {
+    if (check()) return;
+    await new Promise(setImmediate);
+  }
+  assert.fail('queue did not reach its expected state');
+}
+
+test('shared governor paces a four-call burst within the rolling minute ceiling', async () => {
+  let at = 0;
+  const waits = [];
+  const queue = createInatQueue({
+    now: () => at,
+    wait: async (ms) => {
+      waits.push(ms);
+      at += ms;
+    },
+  });
+  const dispatched = [];
+  await Promise.all(
+    Array.from({ length: 65 }, () => queue(() => dispatched.push(at))),
+  );
+  assert.equal(dispatched.length, 65);
+  assert.deepEqual(dispatched.slice(0, 7), [0, 0, 0, 0, 1000, 2000, 3000]);
+  assert.deepEqual(waits.slice(0, 3), [1000, 1000, 1000]);
+  for (const time of dispatched)
+    assert.ok(
+      dispatched.filter((other) => other > time - 60_000 && other <= time)
+        .length <= 60,
+    );
+  assert.equal(dispatched[60], 60_000);
+});
+
+test('an observation arriving during the pacing wait overtakes queued tiles', async () => {
+  let at = 0;
+  const waits = [];
+  const queue = createInatQueue({
+    burst: 1,
+    now: () => at,
+    wait: (ms) => new Promise((resolve) => waits.push({ ms, resolve })),
+  });
+  const dispatched = [];
+  await queue(() => dispatched.push('first tile'));
+  const tile = queue(() => dispatched.push('waiting tile'));
+  await until(() => waits.length === 1);
+  const observation = queue(() => dispatched.push('observation'), {
+    priority: 0,
+  });
+  at += waits[0].ms;
+  waits[0].resolve();
+  await observation;
+  assert.deepEqual(dispatched, ['first tile', 'observation']);
+  await until(() => waits.length === 2);
+  at += waits[1].ms;
+  waits[1].resolve();
+  await tile;
+  assert.deepEqual(dispatched, ['first tile', 'observation', 'waiting tile']);
+});
+
+test('superseded tasks leave before dispatch, and a rejection cannot poison the tail', async () => {
+  const queue = createInatQueue({ intervalMs: 0 });
+  const dispatched = [];
+  let release;
+  const first = queue(
+    () =>
+      new Promise((resolve) => {
+        release = resolve;
+      }),
+  );
+  await until(() => release);
+  const controller = new AbortController();
+  const superseded = queue(() => assert.fail('superseded tile dispatched'), {
+    signal: controller.signal,
+  });
+  const dropped = assert.rejects(superseded, { name: 'AbortError' });
+  controller.abort();
+  await dropped;
+  const failed = queue(() => {
+    dispatched.push('failed');
+    throw new Error('synthetic');
+  });
+  const failure = assert.rejects(failed, /synthetic/);
+  const succeeding = queue(() => dispatched.push('recovered'));
+  release();
+  await Promise.all([first, failure, succeeding]);
+  assert.deepEqual(dispatched, ['failed', 'recovered']);
+});
+
+test('a slow call does not hold later calls; at most four run at once', async () => {
+  const queue = createInatQueue({ intervalMs: 0, windowMs: 0 });
+  const releases = [];
+  const started = [];
+  const slow = (id) => () =>
+    new Promise((resolve) => {
+      started.push(id);
+      releases.push(() => resolve(id));
+    });
+  const jobs = [1, 2, 3, 4, 5].map((id) => queue(slow(id)));
+  await until(() => started.length === 4);
+  assert.deepEqual(started, [1, 2, 3, 4], 'four start without waiting');
+  releases[1]();
+  assert.equal(await jobs[1], 2, 'a later call finishes before the first');
+  await until(() => started.length === 5);
+  assert.deepEqual(started, [1, 2, 3, 4, 5], 'a freed slot starts the next');
+  for (const release of releases) release();
+  assert.deepEqual(await Promise.all(jobs), [1, 2, 3, 4, 5]);
+});
diff --git a/server/providers/inaturalist/speed.test.mjs b/server/providers/inaturalist/speed.test.mjs
new file mode 100644
index 000000000..e9f02fda4
--- /dev/null
+++ b/server/providers/inaturalist/speed.test.mjs
@@ -0,0 +1,218 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createInatClient } from './client.js';
+import { installInatProxy, NOW } from './proxy.fixture.mjs';
+import { syntheticGrid } from './grid.fixture.mjs';
+import { INAT_GRID_DECODE_MEASURE } from './grid.js';
+
+const gridUrl = '/grid?z=2&x=1&y=1&taxa=Aves';
+const params = {
+  scope: 'global',
+  taxa: 'all',
+  observedD1: '2026-11-02',
+};
+const tick = () => new Promise(setImmediate);
+
+const install = (options, hook) => installInatProxy(gridUrl, options, hook);
+
+test('tile cache lasts fifteen minutes, then returns stale before revalidation finishes', async () => {
+  let at = NOW;
+  let calls = 0;
+  let release;
+  const request = install({
+    now: () => at,
+    fetchImpl: () => {
+      calls += 1;
+      return calls === 1
+        ? Response.json(syntheticGrid())
+        : new Promise((resolve) => {
+            release = resolve;
+          });
+    },
+  });
+  const first = await request();
+  at += 899_999;
+  const freshPromise = request();
+  await tick();
+  assert.equal(calls, 1, 'a fresh tile never spends another upstream attempt');
+  assert.deepEqual((await freshPromise).body, first.body);
+  at += 1;
+  const stalePromise = request();
+  let resolved = false;
+  void stalePromise.then(() => {
+    resolved = true;
+  });
+  await tick();
+  try {
+    assert.equal(
+      resolved,
+      true,
+      'stale cells publish while refresh is pending',
+    );
+    const stale = await stalePromise;
+    assert.equal(stale.body.stale, true);
+    assert.equal(stale.body.fetchedAt, NOW);
+    assert.deepEqual(stale.body.cells, first.body.cells);
+    await request();
+    assert.equal(calls, 2, 'all stale consumers share one background refresh');
+    const refreshPromise = request(`${gridUrl}&refresh=wait`);
+    let refreshed = false;
+    void refreshPromise.then(() => {
+      refreshed = true;
+    });
+    await tick();
+    assert.equal(
+      refreshed,
+      false,
+      'a background consumer can await the same refresh',
+    );
+    release(Response.json(syntheticGrid()));
+    const fresh = await refreshPromise;
+    assert.equal(fresh.body.stale, undefined);
+    assert.equal(fresh.body.fetchedAt, at);
+    assert.equal(
+      calls,
+      2,
+      'waiting for fresh cells never duplicates upstream work',
+    );
+    release = null;
+  } finally {
+    release?.(Response.json(syntheticGrid()));
+  }
+});
+
+test('more than sixteen queued views and thirty local requests never report local rate limiting', async () => {
+  let release;
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls += 1;
+      if (calls === 1)
+        await new Promise((resolve) => {
+          release = resolve;
+        });
+      return Response.json(syntheticGrid());
+    },
+  });
+  const pending = Array.from({ length: 40 }, (_, x) =>
+    request(`/grid?z=6&x=${x}&y=1`),
+  );
+  await tick();
+  release();
+  const results = await Promise.all(pending);
+  assert.ok(results.every((result) => result.status === 200));
+  assert.equal(calls, 40);
+});
+
+test('only real upstream 429 or 5xx failures start cooldown', async () => {
+  for (const bad of [
+    () => Promise.reject(new Error('network')),
+    () => Response.json({ malformed: true }),
+    () => new Response('', { status: 404 }),
+  ]) {
+    let calls = 0;
+    const client = createInatClient({
+      now: () => NOW,
+      cacheDir: null,
+      queueOptions: { intervalMs: 0, windowMs: 0 },
+      warn() {},
+      fetchImpl: () => {
+        calls += 1;
+        return calls === 1
+          ? bad()
+          : Response.json({ results: [], total_results: 0 });
+      },
+    });
+    await assert.rejects(client.getObservations(params), { status: 502 });
+    await client.getObservations(params);
+    assert.equal(
+      calls,
+      2,
+      'a non-cooldown failure must not hold the next attempt',
+    );
+  }
+});
+
+test('actual upstream cooldown is marked separately from a local budget stop', async () => {
+  for (const upstream of [429, 503]) {
+    let calls = 0;
+    const request = install({
+      fetchImpl: () => {
+        calls += 1;
+        return new Response('', {
+          status: upstream,
+          headers: { 'Retry-After': '120' },
+        });
+      },
+    });
+    const first = await request();
+    assert.equal(first.headers['X-Upstream-Status'], String(upstream));
+    assert.equal(first.headers['Retry-After'], '120');
+    await request();
+    assert.equal(calls, 1);
+  }
+});
+
+test('upstream Retry-After zero survives the HTTP response and permits an immediate next request', async () => {
+  for (const upstream of [429, 503]) {
+    let calls = 0;
+    const request = install({
+      fetchImpl: () => {
+        calls += 1;
+        return calls === 1
+          ? new Response('', {
+              status: upstream,
+              headers: { 'Retry-After': '0' },
+            })
+          : Response.json(syntheticGrid());
+      },
+    });
+    const first = await request();
+    assert.equal(first.headers['X-Upstream-Status'], String(upstream));
+    assert.equal(first.headers['Retry-After'], '0');
+    assert.equal((await request()).status, 200);
+    assert.equal(calls, 2);
+  }
+});
+
+test('a local daily budget stop has a distinct code and no upstream cooldown marker', async (t) => {
+  const before = process.env.INATURALIST_DAILY_BUDGET;
+  process.env.INATURALIST_DAILY_BUDGET = '1';
+  t.after(() => {
+    if (before === undefined) delete process.env.INATURALIST_DAILY_BUDGET;
+    else process.env.INATURALIST_DAILY_BUDGET = before;
+  });
+  let calls = 0;
+  const request = install({
+    fetchImpl: () => {
+      calls += 1;
+      return Response.json(syntheticGrid());
+    },
+  });
+  assert.equal((await request()).status, 200);
+  const stopped = await request('/grid?z=2&x=0&y=1');
+  assert.equal(stopped.status, 503);
+  assert.equal(stopped.body.error, 'inaturalist_budget_exhausted');
+  assert.equal(stopped.headers['X-Upstream-Status'], undefined);
+  assert.equal((await request()).status, 200, 'cached data remains available');
+  assert.equal(calls, 1);
+});
+
+test('cached tiles avoid UTFGrid decode and decode timing entries stay bounded', async () => {
+  const request = install({
+    fetchImpl: () => Response.json(syntheticGrid()),
+  });
+  await request();
+  const sample = performance.getEntriesByName(INAT_GRID_DECODE_MEASURE)[0];
+  assert.ok(sample.duration >= 0);
+  for (let i = 0; i < 10; i += 1) await request();
+  assert.equal(
+    performance.getEntriesByName(INAT_GRID_DECODE_MEASURE)[0],
+    sample,
+  );
+  for (let x = 0; x < 4; x += 1) await request(`/grid?z=3&x=${x}&y=1`);
+  assert.equal(
+    performance.getEntriesByName(INAT_GRID_DECODE_MEASURE).length,
+    1,
+  );
+});
diff --git a/server/providers/local.js b/server/providers/local.js
index 7067f3ec5..41b0fd3a5 100644
--- a/server/providers/local.js
+++ b/server/providers/local.js
@@ -29,6 +29,8 @@ import { firePerimetersProxy } from './firePerimeters.js';
 import { gnssIntegrityProxy } from './gnssIntegrity.js';
 import { ghostMapsProxy } from './ghostMaps.js';
 import { droneAirspaceProxy } from './droneAirspace.js';
+import { inaturalistProxy } from './inaturalist/observations.js';
+import { acartiaProxy } from './acartia.js';
 import { cycloneProxy } from './cyclones.js';
 import { windProxy } from './wind.js';
 
@@ -81,6 +83,8 @@ function localProviderPlugins({
     gnssIntegrityProxy(),
     ghostMapsProxy(),
     droneAirspaceProxy(),
+    inaturalistProxy(),
+    acartiaProxy(),
     keySetupEndpoint(),
   ];
 }
diff --git a/src/app/catalog.js b/src/app/catalog.js
index 9dc641fef..30fb42084 100644
--- a/src/app/catalog.js
+++ b/src/app/catalog.js
@@ -5,6 +5,7 @@ const CONTROL_LAYER_IDS = Object.freeze({
   satellitesLayer: 'satellites',
   cctvLayer: 'cctv',
   streetLevelLayer: 'street-level',
+  wildlifeSightingsLayer: 'wildlife-sightings',
   radioLayer: 'radio',
   bikeshareLayer: 'bikeshare',
   transitLayer: 'transit',
diff --git a/src/app/catalog.test.mjs b/src/app/catalog.test.mjs
index 2b558939b..28000818d 100644
--- a/src/app/catalog.test.mjs
+++ b/src/app/catalog.test.mjs
@@ -139,6 +139,7 @@ test('controls bind catalog instances rather than similarly named defaults', ()
     'rocket-launches',
     'street-level',
     'local-adsb',
+    'wildlife-sightings',
   ];
   const layers = ids.map((id) => ({ id }));
   const catalog = createLayerCatalog(layers, metadata(layers));
@@ -147,6 +148,7 @@ test('controls bind catalog instances rather than similarly named defaults', ()
   assert.equal(services.transitLayer, layers[7]);
   assert.equal(services.aisLiveVesselsLayer, layers[8]);
   assert.equal(services.localAdsbLayer, layers[13]);
+  assert.equal(services.wildlifeSightingsLayer, layers[14]);
   assert.equal(new Set(Object.values(services)).size, layers.length);
   assert.throws(
     () => catalogControlServices(createLayerCatalog([], [])),
diff --git a/src/app/constructCatalog.js b/src/app/constructCatalog.js
index 488a5e9ab..0946b6ceb 100644
--- a/src/app/constructCatalog.js
+++ b/src/app/constructCatalog.js
@@ -30,6 +30,7 @@ import { createApplicationFirePerimeters } from './layers/perimeters.js';
 import { createApplicationGnssIntegrity } from './layers/gnss.js';
 import { createApplicationGhostMaps } from './layers/ghostMaps.js';
 import { createApplicationDroneAirspace } from './layers/droneAirspace.js';
+import { createApplicationWildlifeSightings } from './layers/wildlifeSightings.js';
 import { createApplicationCables } from './layers/submarineCables.js';
 import { createOsmOverlayLayers } from '../data/osmOverlays.js';
 import { createApplicationStreetLevel } from './layers/streetLevel.js';
@@ -137,6 +138,10 @@ export function createApplicationCatalog({
         createApplicationDroneAirspace({
           source: sources['drone-airspace'],
         }),
+        createApplicationWildlifeSightings({
+          source: sources['wildlife-sightings'],
+          groundFloor: surface.groundFloor,
+        }),
         createApplicationAlpr({ surface, source: sources.alpr }),
         createApplicationStreetLevel({
           surface,
diff --git a/src/app/constructCatalog.test.mjs b/src/app/constructCatalog.test.mjs
index 82a1dbcf0..3d61df3b3 100644
--- a/src/app/constructCatalog.test.mjs
+++ b/src/app/constructCatalog.test.mjs
@@ -40,7 +40,7 @@ test('catalogs construct distinct layers and classification from their supplied
     signal: b.signal,
     surface: fixtureSurface(b.signal),
   });
-  assert.equal(first.layers.length, 37);
+  assert.equal(first.layers.length, 38);
   assert.ok(first.get('local-adsb'), 'Local ADS-B is registered');
   assert.deepEqual(
     first.metadata.find(({ id }) => id === 'osm-places'),
@@ -161,7 +161,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, 37);
+  assert.equal(catalog.layers.length, 38);
   assert.deepEqual(catalog.get('street-level').providerIds, []);
   assert.equal(
     catalogControlServices(catalog).streetLevelLayer,
diff --git a/src/app/layers/wildlifeSightings.js b/src/app/layers/wildlifeSightings.js
new file mode 100644
index 000000000..6d181f2c7
--- /dev/null
+++ b/src/app/layers/wildlifeSightings.js
@@ -0,0 +1,30 @@
+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';
+import * as sprites from '../../data/spriteOrder.js';
+import * as render from '../../renderGovernor.js';
+import * as context from '../../data/contextStore.js';
+import * as focus from '../../worldFocus.js';
+import { isPointerFree } from '../../data/inputOwnership.js';
+
+/** Bind the wildlife layer to the application's scene and selection owners. */
+export function createApplicationWildlifeSightings(options) {
+  return createWildlifeSightingsLayer({
+    overlayHost: {
+      setEntries: overlays.setOverlayEntries,
+      setVisible: overlays.setOverlaySourceVisible,
+      clearSource: overlays.clearOverlaySource,
+      hitTest: overlays.hitTestWorldOverlay,
+    },
+    screenSpaceEventHandlerFactory: (viewer) =>
+      new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas),
+    picking,
+    pointer: { isPointerFree },
+    sprites,
+    render,
+    context,
+    focus,
+    ...options,
+  });
+}
diff --git a/src/app/sourceComposition.js b/src/app/sourceComposition.js
index a12378260..bc3e3b37c 100644
--- a/src/app/sourceComposition.js
+++ b/src/app/sourceComposition.js
@@ -50,6 +50,7 @@ export const CATALOG_SOURCE_CONTRACTS = Object.freeze({
   'gnss-integrity': contract(['gnss-integrity'], ['getSnapshot']),
   's2-ghostmaps': contract(['s2-ghostmaps'], ['getCatalog', 'getFile']),
   'drone-airspace': contract(['drone-airspace'], ['getSnapshot']),
+  'wildlife-sightings': contract(['wildlife-sightings'], ['getSnapshot']),
   cables: contract(['telegeography-submarine-cables'], ['fetch']),
   transit: contract(['transit'], ['requestSnapshot', 'getHistory']),
 });
diff --git a/src/app/sourceComposition.test.mjs b/src/app/sourceComposition.test.mjs
index cee9c1246..2a18039f2 100644
--- a/src/app/sourceComposition.test.mjs
+++ b/src/app/sourceComposition.test.mjs
@@ -37,7 +37,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, 37);
+  assert.equal(actual.layers.length, 38);
   const manager = new LayerLifecycle(
     {},
     { getSourceAvailability: actual.getSourceAvailability },
diff --git a/src/data/dataCredits.js b/src/data/dataCredits.js
index 29075550c..7d88c6462 100644
--- a/src/data/dataCredits.js
+++ b/src/data/dataCredits.js
@@ -34,6 +34,14 @@ export const OPENMAPTILES_CREDIT = {
   html: 'Vector tiles: <a href="https://openfreemap.org" target="_blank" rel="noopener">OpenFreeMap</a> © <a href="https://openmaptiles.org" target="_blank" rel="noopener">OpenMapTiles</a>',
 };
 
+/** Conditional Salish Sea coverage; registered when its sightings first render. */
+export const ACARTIA_CREDIT = Object.freeze({
+  key: 'acartia',
+  html:
+    'Wildlife sightings: <a href="https://acartia.io" target="_blank" rel="noopener">Acartia</a> (CC BY 4.0; each provider credited per sighting) · ' +
+    '<a href="https://www.bewhalewise.org" target="_blank" rel="noopener">Be Whale Wise</a>',
+});
+
 const osmDisplays = new WeakMap();
 
 function updateOsmDisplay(viewer, state) {
@@ -188,6 +196,10 @@ export const DATA_CREDITS = [
       '<a href="https://adds-faa.opendata.arcgis.com/" target="_blank" rel="noopener">FAA Special Use Airspace</a>' +
       ' (prohibited and restricted zones; informational only)',
   },
+  {
+    key: 'inaturalist',
+    html: 'Wildlife sightings: <a href="https://www.inaturalist.org" target="_blank" rel="noopener">iNaturalist</a> contributors (licences per record; photos credited on each card)',
+  },
   OSM_CREDIT,
   OPENMAPTILES_CREDIT,
   {
diff --git a/src/data/layerState.js b/src/data/layerState.js
index 46dadf9a0..4c679f7af 100644
--- a/src/data/layerState.js
+++ b/src/data/layerState.js
@@ -312,6 +312,23 @@ const OPTION_GROUPS = Object.freeze({
       high: 'h',
     }),
   ]),
+  'wildlife-sightings': Object.freeze([
+    booleanOption('confirmed', 'c', false),
+    enumOption(
+      'taxa',
+      't',
+      'all',
+      ['all', 'Aves', 'Mammalia', 'whales', 'Insecta', 'Plantae'],
+      {
+        all: 'a',
+        Aves: 'b',
+        Mammalia: 'm',
+        whales: 'w',
+        Insecta: 'i',
+        Plantae: 'p',
+      },
+    ),
+  ]),
   traffic: Object.freeze([
     enumOption('roadMode', 'r', null, ['tomtom', 'osm', 'hybrid'], {
       tomtom: 't',
@@ -733,6 +750,12 @@ export const LAYER_STATE_REGISTRY = Object.freeze([
     disposition: 'enabled+options',
     optionOwner: 'weather-satellite',
   }),
+  Object.freeze({
+    id: 'wildlife-sightings',
+    token: '9',
+    disposition: 'enabled+options',
+    optionOwner: 'wildlife-sightings',
+  }),
   Object.freeze({
     id: 'wind',
     token: 'k',
diff --git a/src/data/layerState.test.mjs b/src/data/layerState.test.mjs
index 9d30e8973..b75565285 100644
--- a/src/data/layerState.test.mjs
+++ b/src/data/layerState.test.mjs
@@ -203,8 +203,8 @@ function encode(state) {
 
 test('production registry is exact, canonical, and rejects incomplete contracts', async () => {
   assert.equal(validateLayerStateRegistry(), true);
-  assert.equal(REGISTERED_LAYER_IDS.length, 35);
-  assert.equal(new Set(REGISTERED_LAYER_IDS).size, 35);
+  assert.equal(REGISTERED_LAYER_IDS.length, 36);
+  assert.equal(new Set(REGISTERED_LAYER_IDS).size, 36);
   assert.ok(REGISTERED_LAYER_IDS.includes('transit'));
   assert.deepEqual(REGISTERED_LAYER_IDS, [...REGISTERED_LAYER_IDS].sort());
   assert.deepEqual(LEGACY_LAYER_STATE_TOKENS, {
@@ -243,7 +243,7 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
   for (const [id, token] of Object.entries(LEGACY_LAYER_STATE_TOKENS)) {
     assert.equal(LAYER_STATE_TOKEN_RESERVATIONS[id], token);
   }
-  assert.equal(nextLayerStateToken(), '9');
+  assert.equal(nextLayerStateToken(), '00');
   assert.equal(
     nextLayerStateToken({
       ...LAYER_STATE_TOKEN_RESERVATIONS,
@@ -306,8 +306,8 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
   assert.equal(
     validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
       ...LAYER_STATE_TOKEN_RESERVATIONS,
-      future: '9',
-      next: '00',
+      future: '00',
+      next: '01',
     }),
     true,
   );
@@ -315,12 +315,13 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
     () =>
       validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
         ...LAYER_STATE_TOKEN_RESERVATIONS,
-        future: '00',
+        future: '01',
       }),
-    /next free token 9/,
+    /next free token 00/,
   );
   const beforeLastDigit = { ...digitsExhausted };
   delete beforeLastDigit['prior-9'];
+  delete beforeLastDigit['wildlife-sightings'];
   assert.equal(
     validateLayerStateAllocations(beforeLastDigit, {
       ...beforeLastDigit,
@@ -2695,6 +2696,32 @@ test('the recent-imagery split is share-link only: never stored locally, and a s
   );
 });
 
+test('wildlife confirmed and every taxa preset round-trip through the full share codec', () => {
+  assert.equal(
+    LAYER_STATE_REGISTRY.find(({ id }) => id === 'wildlife-sightings').token,
+    '9',
+  );
+  for (const taxa of [
+    'all',
+    'Aves',
+    'Mammalia',
+    'whales',
+    'Insecta',
+    'Plantae',
+  ]) {
+    const state = normalizeLayerState({
+      enabledLayerIds: ['wildlife-sightings'],
+      options: { 'wildlife-sightings': { confirmed: true, taxa } },
+    });
+    const encoded = encode(state);
+    assert.doesNotMatch(encoded, /undefined/);
+    assert.deepEqual(
+      decodeLayerStateParams(new URLSearchParams(encoded)),
+      state,
+    );
+  }
+});
+
 test('drone restrictions uses digit 8 without colliding with fire perimeters', () => {
   const decoded = decodeLayerStateParams(new URLSearchParams('v=2&l=8.2'));
   assert.deepEqual(decoded.enabledLayerIds, [
diff --git a/src/data/layerStateTokenLedger.test.mjs b/src/data/layerStateTokenLedger.test.mjs
index d46782378..a6c3390ec 100644
--- a/src/data/layerStateTokenLedger.test.mjs
+++ b/src/data/layerStateTokenLedger.test.mjs
@@ -97,6 +97,10 @@ function withPublishedBase(
   }
 }
 
+const preWildlifeRows = reservationRows.filter(
+  ([id]) => id !== 'wildlife-sightings',
+);
+
 function writeCodecFixture(cwd, rows, entries) {
   const providerCodec = path.join(cwd, 'src/data/idSwitches.js');
   mkdirSync(path.dirname(providerCodec), { recursive: true });
@@ -104,7 +108,12 @@ function writeCodecFixture(cwd, rows, entries) {
     providerCodec,
     readFileSync(new URL('./idSwitches.js', import.meta.url)),
   );
-  const source = readFileSync(CODEC_SOURCE_PATH, 'utf8');
+  let source = readFileSync(CODEC_SOURCE_PATH, 'utf8');
+  if (!rows.some(([id]) => id === 'wildlife-sightings'))
+    source = source.replace(
+      /  Object\.freeze\(\{\s*id: 'wildlife-sightings',[\s\S]*?\}\),\n/,
+      '',
+    );
   const registryEnd = ']);\n\nexport const REGISTERED_LAYER_IDS';
   assert.equal(source.split(registryEnd).length, 2);
   const additions = entries
@@ -128,7 +137,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
     { ...parseLayerStateTokenReservations(reservationRows) },
     { ...LAYER_STATE_TOKEN_RESERVATIONS },
   );
-  assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 35);
+  assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 36);
   assert.deepEqual(
     { ...LAYER_STATE_TOKEN_RESERVATIONS },
     {
@@ -140,6 +149,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
       'sea-marks': '6',
       'ski-pistes': '7',
       'drone-airspace': '8',
+      'wildlife-sightings': '9',
     },
   );
   assert.throws(
@@ -165,9 +175,9 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
     /Duplicate layer-state token reservation/,
   );
   assert.equal(
-    parseLayerStateTokenReservations([...reservationRows, ['future', '9']])
+    parseLayerStateTokenReservations([...reservationRows, ['future', '00']])
       .future,
-    '9',
+    '00',
   );
   assert.throws(
     () =>
@@ -185,7 +195,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
 
 test('published retired digits and competing PRs advance the merge-time allocation', () => {
   withPublishedBase(
-    { rows: [...reservationRows, ['retired-layer', '9']] },
+    { rows: [...preWildlifeRows, ['retired-layer', '9']] },
     (cwd) => {
       const published = readPublishedLayerStateReservations('HEAD', cwd);
       assert.equal(nextLayerStateToken(published), '00');
@@ -217,7 +227,7 @@ test('published retired digits and competing PRs advance the merge-time allocati
 });
 
 test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () => {
-  withPublishedBase({ rows: [...reservationRows, ['pr-a', '9']] }, (cwd) => {
+  withPublishedBase({ rows: [...preWildlifeRows, ['pr-a', '9']] }, (cwd) => {
     mkdirSync(path.join(cwd, 'scripts'));
     const fixtureChecker = path.join(
       cwd,
@@ -238,7 +248,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
 
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-b', '9']],
+      [...preWildlifeRows, ['pr-b', '9']],
       [{ id: 'pr-b', token: '9' }],
     );
     const beforeRebase = runCheck();
@@ -247,7 +257,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
 
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-a', '9'], ['pr-b', '9']],
+      [...preWildlifeRows, ['pr-a', '9'], ['pr-b', '9']],
       [
         { id: 'pr-a', token: '9' },
         { id: 'pr-b', token: '9' },
@@ -259,7 +269,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
 
     const published = readPublishedLayerStateReservations('HEAD', cwd);
     assert.equal(nextLayerStateToken(published), '00');
-    const validBaselineRows = [...reservationRows, ['pr-a', '9']];
+    const validBaselineRows = [...preWildlifeRows, ['pr-a', '9']];
     writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '9' }]);
     const helper = spawnSync(
       process.execPath,
@@ -275,7 +285,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
     );
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-a', '9'], ['pr-b', '00']],
+      [...preWildlifeRows, ['pr-a', '9'], ['pr-b', '00']],
       [
         { id: 'pr-a', token: '9' },
         { id: 'pr-b', token: '00' },
@@ -290,7 +300,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
 test('allocation batches cross the last digit and base-36 pair boundaries in order', () => {
   const digitRows = [...'9'].map((digit) => [`retired-${digit}`, digit]);
   const allDigits = parseLayerStateTokenReservations([
-    ...reservationRows,
+    ...preWildlifeRows,
     ...digitRows,
   ]);
   const beforeNine = { ...allDigits };
@@ -349,7 +359,7 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
       token,
     }));
     const fixtureRows = [
-      ...reservationRows,
+      ...preWildlifeRows,
       ...priorDigits,
       ...fixtureLayers.map(({ id, token }) => [id, token]),
     ];
@@ -358,13 +368,13 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
     assert.equal(codec.validateLayerStateRegistry(), true);
     assert.equal(
       nextLayerStateToken(
-        parseLayerStateTokenReservations([...reservationRows, ...priorDigits]),
+        parseLayerStateTokenReservations([...preWildlifeRows, ...priorDigits]),
       ),
       '00',
     );
     assert.equal(
       validateLayerStateAllocations(
-        LAYER_STATE_TOKEN_RESERVATIONS,
+        parseLayerStateTokenReservations(preWildlifeRows),
         codec.LAYER_STATE_TOKEN_RESERVATIONS,
       ),
       true,
@@ -395,7 +405,7 @@ test('checker reads a complete future base ledger and rejects retired-token reus
     },
     (cwd) => {
       const published = readPublishedLayerStateReservations('HEAD', cwd);
-      assert.equal(Object.keys(published).length, 36);
+      assert.equal(Object.keys(published).length, 37);
       assert.equal(published['retired-layer'], '00');
       assert.throws(
         () =>
diff --git a/src/data/layerStateTokenReservations.json b/src/data/layerStateTokenReservations.json
index 836112713..8a79800e1 100644
--- a/src/data/layerStateTokenReservations.json
+++ b/src/data/layerStateTokenReservations.json
@@ -33,5 +33,6 @@
   ["weather-lightning", "l"],
   ["weather-radar", "v"],
   ["weather-satellite", "o"],
+  ["wildlife-sightings", "9"],
   ["wind", "k"]
 ]
diff --git a/src/data/spriteOrder.js b/src/data/spriteOrder.js
index 2dd10925c..28f83cb4e 100644
--- a/src/data/spriteOrder.js
+++ b/src/data/spriteOrder.js
@@ -2,6 +2,7 @@
 export const SPRITE_LAYER_ORDER = Object.freeze([
   'cctv',
   'firms',
+  'wildlife-sightings',
   'bikeshare',
   'transit',
   'transit-motion',
diff --git a/src/i18n/locales/ar.json b/src/i18n/locales/ar.json
index c9fca14ce..ad79b816a 100644
--- a/src/i18n/locales/ar.json
+++ b/src/i18n/locales/ar.json
@@ -3404,5 +3404,62 @@
   "FAA prohibited and restricted special-use airspace only, not the UAS Facility Map or UAS flight restrictions. Informational only — not a substitute for official UAS flight-planning tools (B4UFLY / LAANC).": "المجال الجوي الخاص المحظور والمقيّد لدى FAA فقط، ولا يشمل UAS Facility Map أو قيود طيران UAS. للعلم فقط — ولا يغني عن الأدوات الرسمية لتخطيط رحلات UAS (B4UFLY / LAANC).",
   "Prohibited": "محظور",
   "Restricted": "مقيّد",
-  "Prohibited & Restricted Airspace": "المجال الجوي المحظور والمقيّد"
+  "Prohibited & Restricted Airspace": "المجال الجوي المحظور والمقيّد",
+  "SIGHTING": "مشاهدة",
+  "Show {name} sighting": "إظهار مشاهدة {name}",
+  "seen {age} ago": "شوهد قبل {age}",
+  "observed {age} ago": "رُصد قبل {age}",
+  "Be Whale Wise": "راقب الحيتان بمسؤولية",
+  "Reported by {name} ({entity})": "أبلغ عنه {name} ({entity})",
+  "Reported by {name}": "أبلغ عنه {name}",
+  "Salish Sea": "بحر ساليش",
+  "Birds": "الطيور",
+  "Mammals": "الثدييات",
+  "Reptiles": "الزواحف",
+  "Amphibians": "البرمائيات",
+  "Ray-finned fishes": "الأسماك شعاعية الزعانف",
+  "Insects": "الحشرات",
+  "Arachnids": "العنكبوتيات",
+  "Plants": "النباتات",
+  "Fungi": "الفطريات",
+  "Other animals": "حيوانات أخرى",
+  "Other or unknown": "أخرى أو غير معروفة",
+  "{label} {detail} — click to retry": "{label} {detail} — انقر لإعادة المحاولة",
+  "Wildlife sightings source unavailable": "مصدر مشاهدات الحياة البرية غير متاح",
+  "Show only community-confirmed (research-grade) sightings": "إظهار المشاهدات المؤكدة مجتمعياً (بدرجة بحثية) فقط",
+  "No recent sightings in view": "لا توجد مشاهدات حديثة في العرض",
+  "Acartia feed unavailable": "تعذر الوصول إلى مصدر Acartia",
+  "Show all taxa": "إظهار جميع المجموعات التصنيفية",
+  "BIRDS": "الطيور",
+  "Show only birds": "إظهار الطيور فقط",
+  "MAMMALS": "الثدييات",
+  "Show only mammals": "إظهار الثدييات فقط",
+  "WHALES": "الحيتان",
+  "Show only whales and dolphins (7 days)": "إظهار الحيتان والدلافين فقط (7 أيام)",
+  "INSECTS": "الحشرات",
+  "Show only insects": "إظهار الحشرات فقط",
+  "PLANTS": "النباتات",
+  "Show only plants": "إظهار النباتات فقط",
+  "All rights reserved": "جميع الحقوق محفوظة",
+  "Cetacean": "حوتي",
+  "Wildlife Sightings": "مشاهدات الحياة البرية",
+  "Exit cockpit to fly to a sighting": "اخرج من قمرة القيادة للانتقال إلى مشاهدة",
+  "Exit cockpit to fly to a sighting area": "اخرج من قمرة القيادة للانتقال إلى منطقة مشاهدة",
+  "Wildlife": "الحياة البرية",
+  "Zoom in for local sightings": "قرّب لرؤية المشاهدات المحلية",
+  "Loading photo...": "جارٍ تحميل الصورة…",
+  "Photo unavailable": "الصورة غير متاحة",
+  "Location obscured to a 0.2° cell": "الموقع مخفي ضمن خلية بمقدار 0.2°",
+  "Open on Acartia ↗": "فتح على Acartia ↗",
+  "Photo of {name}": "صورة {name}",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "{count} مشاهدة ضمن النطاق",
+  "Close sighting": "إغلاق المشاهدة",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "حياة برية شوهدت خلال 48 ساعة (الحيتان 7 أيام). يوضح اللون ورمز الشارة المجموعة التصنيفية. تُعرض الأنواع الحساسة في خلايا بحجم 0.2° فقط؛ وتُقرّب مشاهدات الثدييات البحرية في بحر ساليش عبر Acartia إلى 0.01°. ليست إحصاءً شاملاً.",
+  "Open {name} on iNaturalist": "فتح {name} على iNaturalist",
+  "Open {name} on Acartia": "فتح {name} على Acartia",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "مساهمو iNaturalist · التراخيص لكل سجل",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "مساهمو iNaturalist · Acartia {count} (بحر ساليش) · التراخيص لكل سجل"
 }
diff --git a/src/i18n/locales/de.json b/src/i18n/locales/de.json
index bb683ed9f..4b7a8c501 100644
--- a/src/i18n/locales/de.json
+++ b/src/i18n/locales/de.json
@@ -3104,5 +3104,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "Der Anbieter hat den API-Schlüssel abgelehnt. Den Schlüssel in den Anbieter-Einstellungen prüfen.",
   "Too many chat requests. Try again in {seconds} s.": "Zu viele Chat-Anfragen. In {seconds} s erneut versuchen.",
   "The provider refused access for this key. Check the key's project, region or permissions.": "Der Anbieter hat den Zugriff für diesen Schlüssel verweigert. Projekt, Region oder Berechtigungen des Schlüssels prüfen.",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "Das Anbieterkonto hat kein Guthaben mehr. Die Abrechnung prüfen oder in den Einstellungen einen anderen KI-Anbieter wählen."
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "Das Anbieterkonto hat kein Guthaben mehr. Die Abrechnung prüfen oder in den Einstellungen einen anderen KI-Anbieter wählen.",
+  "SIGHTING": "BEOBACHTUNG",
+  "Show {name} sighting": "Beobachtung von {name} anzeigen",
+  "seen {age} ago": "vor {age} gesichtet",
+  "observed {age} ago": "vor {age} beobachtet",
+  "Be Whale Wise": "Wale respektvoll beobachten",
+  "Reported by {name} ({entity})": "Gemeldet von {name} ({entity})",
+  "Reported by {name}": "Gemeldet von {name}",
+  "Salish Sea": "Salish-See",
+  "Birds": "Vögel",
+  "Mammals": "Säugetiere",
+  "Reptiles": "Reptilien",
+  "Amphibians": "Amphibien",
+  "Ray-finned fishes": "Strahlenflosser",
+  "Insects": "Insekten",
+  "Arachnids": "Spinnentiere",
+  "Plants": "Pflanzen",
+  "Fungi": "Pilze",
+  "Other animals": "Andere Tiere",
+  "Other or unknown": "Andere oder unbekannt",
+  "{label} {detail} — click to retry": "{label} {detail} — zum Wiederholen klicken",
+  "Wildlife sightings source unavailable": "Quelle für Naturbeobachtungen nicht verfügbar",
+  "Show only community-confirmed (research-grade) sightings": "Nur gemeinschaftlich bestätigte Beobachtungen (Forschungsqualität) anzeigen",
+  "No recent sightings in view": "Keine aktuellen Beobachtungen im Ausschnitt",
+  "Acartia feed unavailable": "Acartia-Datenstrom nicht verfügbar",
+  "Show all taxa": "Alle Artengruppen anzeigen",
+  "BIRDS": "VÖGEL",
+  "Show only birds": "Nur Vögel anzeigen",
+  "MAMMALS": "SÄUGETIERE",
+  "Show only mammals": "Nur Säugetiere anzeigen",
+  "WHALES": "WALE",
+  "Show only whales and dolphins (7 days)": "Nur Wale und Delfine anzeigen (7 Tage)",
+  "INSECTS": "INSEKTEN",
+  "Show only insects": "Nur Insekten anzeigen",
+  "PLANTS": "PFLANZEN",
+  "Show only plants": "Nur Pflanzen anzeigen",
+  "All rights reserved": "Alle Rechte vorbehalten",
+  "Cetacean": "Wal oder Delfin",
+  "Wildlife Sightings": "Naturbeobachtungen",
+  "Exit cockpit to fly to a sighting": "Cockpit verlassen, um zu einer Beobachtung zu fliegen",
+  "Exit cockpit to fly to a sighting area": "Cockpit verlassen, um zu einem Beobachtungsgebiet zu fliegen",
+  "Wildlife": "Tierwelt",
+  "Zoom in for local sightings": "Für lokale Beobachtungen vergrößern",
+  "Loading photo...": "Foto wird geladen…",
+  "Photo unavailable": "Foto nicht verfügbar",
+  "Location obscured to a 0.2° cell": "Standort auf eine 0,2°-Rasterzelle verschleiert",
+  "Open on Acartia ↗": "Auf Acartia öffnen ↗",
+  "Photo of {name}": "Foto von {name}",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "{count} Sichtungen im Ausschnitt",
+  "Close sighting": "Sichtung schließen",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "In den letzten 48 h beobachtete Wildtiere (Wale 7 Tage). Farbe und Abzeichensymbol zeigen die Artengruppe. Empfindliche Arten erscheinen nur als 0,2°-Zellen; Acartia-Meldungen zu Meeressäugern aus der Salish-See werden auf 0,01° gerundet. Keine Bestandszählung.",
+  "Open {name} on iNaturalist": "{name} auf iNaturalist öffnen",
+  "Open {name} on Acartia": "{name} auf Acartia öffnen",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "iNaturalist-Beitragende · Lizenzen je Eintrag",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "iNaturalist-Beitragende · Acartia {count} (Salish-See) · Lizenzen je Eintrag"
 }
diff --git a/src/i18n/locales/es.json b/src/i18n/locales/es.json
index 10dcbef8f..f05227a6a 100644
--- a/src/i18n/locales/es.json
+++ b/src/i18n/locales/es.json
@@ -3179,5 +3179,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "El proveedor rechazó la clave de API. Revísala en Ajustes de proveedores.",
   "Too many chat requests. Try again in {seconds} s.": "Demasiadas solicitudes de chat. Vuelve a intentarlo en {seconds} s.",
   "The provider refused access for this key. Check the key's project, region or permissions.": "El proveedor denegó el acceso a esta clave. Revisa el proyecto, la región o los permisos de la clave.",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "La cuenta del proveedor no tiene crédito. Revisa la facturación o elige otro proveedor de IA en Ajustes."
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "La cuenta del proveedor no tiene crédito. Revisa la facturación o elige otro proveedor de IA en Ajustes.",
+  "SIGHTING": "AVISTAMIENTO",
+  "Show {name} sighting": "Mostrar avistamiento de {name}",
+  "seen {age} ago": "visto hace {age}",
+  "observed {age} ago": "observado hace {age}",
+  "Be Whale Wise": "Observa cetáceos con respeto",
+  "Reported by {name} ({entity})": "Reportado por {name} ({entity})",
+  "Reported by {name}": "Reportado por {name}",
+  "Salish Sea": "Mar de Salish",
+  "Birds": "Aves",
+  "Mammals": "Mamíferos",
+  "Reptiles": "Reptiles",
+  "Amphibians": "Anfibios",
+  "Ray-finned fishes": "Peces de aletas radiadas",
+  "Insects": "Insectos",
+  "Arachnids": "Arácnidos",
+  "Plants": "Plantas",
+  "Fungi": "Hongos",
+  "Other animals": "Otros animales",
+  "Other or unknown": "Otros o desconocidos",
+  "{label} {detail} — click to retry": "{label} {detail} — haz clic para reintentar",
+  "Wildlife sightings source unavailable": "Fuente de avistamientos no disponible",
+  "Show only community-confirmed (research-grade) sightings": "Mostrar solo observaciones confirmadas por la comunidad (grado de investigación)",
+  "No recent sightings in view": "No hay avistamientos recientes en la vista",
+  "Acartia feed unavailable": "Fuente Acartia no disponible",
+  "Show all taxa": "Mostrar todos los grupos taxonómicos",
+  "BIRDS": "AVES",
+  "Show only birds": "Mostrar solo aves",
+  "MAMMALS": "MAMÍFEROS",
+  "Show only mammals": "Mostrar solo mamíferos",
+  "WHALES": "CETÁCEOS",
+  "Show only whales and dolphins (7 days)": "Mostrar solo ballenas y delfines (7 días)",
+  "INSECTS": "INSECTOS",
+  "Show only insects": "Mostrar solo insectos",
+  "PLANTS": "PLANTAS",
+  "Show only plants": "Mostrar solo plantas",
+  "All rights reserved": "Todos los derechos reservados",
+  "Cetacean": "Cetáceo",
+  "Wildlife Sightings": "Avistamientos de fauna y flora",
+  "Exit cockpit to fly to a sighting": "Sal de la cabina para volar a un avistamiento",
+  "Exit cockpit to fly to a sighting area": "Sal de la cabina para volar a un área de avistamiento",
+  "Wildlife": "Vida silvestre",
+  "Zoom in for local sightings": "Acerca para ver avistamientos locales",
+  "Loading photo...": "Cargando foto…",
+  "Photo unavailable": "Foto no disponible",
+  "Location obscured to a 0.2° cell": "Ubicación oculta en una celda de 0,2°",
+  "Open on Acartia ↗": "Abrir en Acartia ↗",
+  "Photo of {name}": "Foto de {name}",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "{count} avistamientos en la vista",
+  "Close sighting": "Cerrar avistamiento",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "Fauna observada en las últimas 48 h (cetáceos 7 días). El color y el símbolo de la insignia indican el grupo taxonómico. Las especies sensibles solo se muestran en celdas de 0,2°; los informes de mamíferos marinos de Acartia en el mar de Salish se redondean a 0,01°. No es un censo.",
+  "Open {name} on iNaturalist": "Abrir {name} en iNaturalist",
+  "Open {name} on Acartia": "Abrir {name} en Acartia",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "Colaboradores de iNaturalist · licencias por registro",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "Colaboradores de iNaturalist · Acartia {count} (mar de Salish) · licencias por registro"
 }
diff --git a/src/i18n/locales/fr.json b/src/i18n/locales/fr.json
index 108e56f36..4f8bb2fd2 100644
--- a/src/i18n/locales/fr.json
+++ b/src/i18n/locales/fr.json
@@ -3179,5 +3179,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "Le fournisseur a refusé la clé API. Vérifiez-la dans les paramètres des fournisseurs.",
   "Too many chat requests. Try again in {seconds} s.": "Trop de requêtes de discussion. Réessayez dans {seconds} s.",
   "The provider refused access for this key. Check the key's project, region or permissions.": "Le fournisseur a refusé l'accès pour cette clé. Vérifiez le projet, la région ou les autorisations de la clé.",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "Le compte du fournisseur n'a plus de crédit. Vérifiez la facturation ou choisissez un autre fournisseur d'IA dans les paramètres."
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "Le compte du fournisseur n'a plus de crédit. Vérifiez la facturation ou choisissez un autre fournisseur d'IA dans les paramètres.",
+  "SIGHTING": "OBSERVATION",
+  "Show {name} sighting": "Afficher l’observation de {name}",
+  "seen {age} ago": "vu il y a {age}",
+  "observed {age} ago": "observé il y a {age}",
+  "Be Whale Wise": "Respectez les cétacés",
+  "Reported by {name} ({entity})": "Signalé par {name} ({entity})",
+  "Reported by {name}": "Signalé par {name}",
+  "Salish Sea": "Mer des Salish",
+  "Birds": "Oiseaux",
+  "Mammals": "Mammifères",
+  "Reptiles": "Reptiles",
+  "Amphibians": "Amphibiens",
+  "Ray-finned fishes": "Poissons à nageoires rayonnées",
+  "Insects": "Insectes",
+  "Arachnids": "Arachnides",
+  "Plants": "Plantes",
+  "Fungi": "Champignons",
+  "Other animals": "Autres animaux",
+  "Other or unknown": "Autres ou inconnus",
+  "{label} {detail} — click to retry": "{label} {detail} — cliquer pour réessayer",
+  "Wildlife sightings source unavailable": "Source des observations naturalistes indisponible",
+  "Show only community-confirmed (research-grade) sightings": "Afficher uniquement les observations confirmées par la communauté (qualité recherche)",
+  "No recent sightings in view": "Aucune observation récente dans la vue",
+  "Acartia feed unavailable": "Flux Acartia indisponible",
+  "Show all taxa": "Afficher tous les groupes taxonomiques",
+  "BIRDS": "OISEAUX",
+  "Show only birds": "Afficher uniquement les oiseaux",
+  "MAMMALS": "MAMMIFÈRES",
+  "Show only mammals": "Afficher uniquement les mammifères",
+  "WHALES": "CÉTACÉS",
+  "Show only whales and dolphins (7 days)": "Afficher uniquement les baleines et dauphins (7 jours)",
+  "INSECTS": "INSECTES",
+  "Show only insects": "Afficher uniquement les insectes",
+  "PLANTS": "PLANTES",
+  "Show only plants": "Afficher uniquement les plantes",
+  "All rights reserved": "Tous droits réservés",
+  "Cetacean": "Cétacé",
+  "Wildlife Sightings": "Observations naturalistes",
+  "Exit cockpit to fly to a sighting": "Quittez le cockpit pour rejoindre une observation",
+  "Exit cockpit to fly to a sighting area": "Quittez le cockpit pour rejoindre une zone d’observation",
+  "Wildlife": "Faune et flore",
+  "Zoom in for local sightings": "Zoomez pour les observations locales",
+  "Loading photo...": "Chargement de la photo…",
+  "Photo unavailable": "Photo indisponible",
+  "Location obscured to a 0.2° cell": "Localisation masquée dans une cellule de 0,2°",
+  "Open on Acartia ↗": "Ouvrir sur Acartia ↗",
+  "Photo of {name}": "Photo de {name}",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "{count} observations dans la vue",
+  "Close sighting": "Fermer l’observation",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "Faune observée au cours des dernières 48 h (cétacés 7 jours). La couleur et le pictogramme du badge indiquent le groupe taxonomique. Les espèces sensibles sont limitées à des cellules de 0,2° ; les signalements de mammifères marins Acartia en mer des Salish sont arrondis à 0,01°. Pas un recensement.",
+  "Open {name} on iNaturalist": "Ouvrir {name} sur iNaturalist",
+  "Open {name} on Acartia": "Ouvrir {name} sur Acartia",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "Contributeurs iNaturalist · licences par observation",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "Contributeurs iNaturalist · Acartia {count} (mer des Salish) · licences par observation"
 }
diff --git a/src/i18n/locales/it.json b/src/i18n/locales/it.json
index 6768f93c7..d27010c5b 100644
--- a/src/i18n/locales/it.json
+++ b/src/i18n/locales/it.json
@@ -3179,5 +3179,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "Il provider ha rifiutato la chiave API. Controllala in Impostazioni provider.",
   "Too many chat requests. Try again in {seconds} s.": "Troppe richieste di chat. Riprova tra {seconds} s.",
   "The provider refused access for this key. Check the key's project, region or permissions.": "Il provider ha negato l'accesso per questa chiave. Controlla progetto, regione o autorizzazioni della chiave.",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "L'account del provider ha esaurito il credito. Controlla la fatturazione o scegli un altro provider IA in Impostazioni."
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "L'account del provider ha esaurito il credito. Controlla la fatturazione o scegli un altro provider IA in Impostazioni.",
+  "SIGHTING": "AVVISTAMENTO",
+  "Show {name} sighting": "Mostra avvistamento di {name}",
+  "seen {age} ago": "avvistato {age} fa",
+  "observed {age} ago": "osservato {age} fa",
+  "Be Whale Wise": "Rispetta i cetacei",
+  "Reported by {name} ({entity})": "Segnalato da {name} ({entity})",
+  "Reported by {name}": "Segnalato da {name}",
+  "Salish Sea": "Mare dei Salish",
+  "Birds": "Uccelli",
+  "Mammals": "Mammiferi",
+  "Reptiles": "Rettili",
+  "Amphibians": "Anfibi",
+  "Ray-finned fishes": "Pesci con pinne raggiate",
+  "Insects": "Insetti",
+  "Arachnids": "Aracnidi",
+  "Plants": "Piante",
+  "Fungi": "Funghi",
+  "Other animals": "Altri animali",
+  "Other or unknown": "Altri o sconosciuti",
+  "{label} {detail} — click to retry": "{label} {detail} — fai clic per riprovare",
+  "Wildlife sightings source unavailable": "Fonte degli avvistamenti non disponibile",
+  "Show only community-confirmed (research-grade) sightings": "Mostra solo osservazioni confermate dalla comunità (grado di ricerca)",
+  "No recent sightings in view": "Nessun avvistamento recente nella vista",
+  "Acartia feed unavailable": "Feed Acartia non disponibile",
+  "Show all taxa": "Mostra tutti i gruppi tassonomici",
+  "BIRDS": "UCCELLI",
+  "Show only birds": "Mostra solo uccelli",
+  "MAMMALS": "MAMMIFERI",
+  "Show only mammals": "Mostra solo mammiferi",
+  "WHALES": "CETACEI",
+  "Show only whales and dolphins (7 days)": "Mostra solo balene e delfini (7 giorni)",
+  "INSECTS": "INSETTI",
+  "Show only insects": "Mostra solo insetti",
+  "PLANTS": "PIANTE",
+  "Show only plants": "Mostra solo piante",
+  "All rights reserved": "Tutti i diritti riservati",
+  "Cetacean": "Cetaceo",
+  "Wildlife Sightings": "Avvistamenti naturalistici",
+  "Exit cockpit to fly to a sighting": "Esci dalla cabina per volare a un avvistamento",
+  "Exit cockpit to fly to a sighting area": "Esci dalla cabina per volare a un’area di avvistamento",
+  "Wildlife": "Natura",
+  "Zoom in for local sightings": "Ingrandisci per gli avvistamenti locali",
+  "Loading photo...": "Caricamento della foto…",
+  "Photo unavailable": "Foto non disponibile",
+  "Location obscured to a 0.2° cell": "Posizione oscurata in una cella di 0,2°",
+  "Open on Acartia ↗": "Apri su Acartia ↗",
+  "Photo of {name}": "Foto di {name}",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "{count} avvistamenti nella vista",
+  "Close sighting": "Chiudi avvistamento",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "Fauna osservata nelle ultime 48 h (cetacei 7 giorni). Colore e simbolo del contrassegno indicano il gruppo tassonomico. Le specie sensibili sono mostrate solo in celle di 0,2°; le segnalazioni di mammiferi marini di Acartia nel mar dei Salish sono arrotondate a 0,01°. Non è un censimento.",
+  "Open {name} on iNaturalist": "Apri {name} su iNaturalist",
+  "Open {name} on Acartia": "Apri {name} su Acartia",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "Contributori di iNaturalist · licenze per osservazione",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "Contributori di iNaturalist · Acartia {count} (Mare dei Salish) · licenze per osservazione"
 }
diff --git a/src/i18n/locales/ja.json b/src/i18n/locales/ja.json
index b4566b4cb..ec7ec7373 100644
--- a/src/i18n/locales/ja.json
+++ b/src/i18n/locales/ja.json
@@ -3029,5 +3029,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "プロバイダーがAPIキーを拒否しました。プロバイダー設定で確認してください。",
   "Too many chat requests. Try again in {seconds} s.": "チャットのリクエストが多すぎます。{seconds}秒後にもう一度お試しください。",
   "The provider refused access for this key. Check the key's project, region or permissions.": "プロバイダーがこのキーでのアクセスを拒否しました。キーのプロジェクト、リージョン、権限を確認してください。",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "プロバイダーアカウントのクレジットが不足しています。課金状況を確認するか、設定で別のAIプロバイダーを選んでください。"
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "プロバイダーアカウントのクレジットが不足しています。課金状況を確認するか、設定で別のAIプロバイダーを選んでください。",
+  "SIGHTING": "目撃情報",
+  "Show {name} sighting": "{name}の目撃情報を表示",
+  "seen {age} ago": "{age}前に目撃",
+  "observed {age} ago": "{age}前に観察",
+  "Be Whale Wise": "クジラに配慮しましょう",
+  "Reported by {name} ({entity})": "報告元 {name}（{entity}）",
+  "Reported by {name}": "報告元 {name}",
+  "Salish Sea": "セイリッシュ海",
+  "Birds": "鳥類",
+  "Mammals": "哺乳類",
+  "Reptiles": "爬虫類",
+  "Amphibians": "両生類",
+  "Ray-finned fishes": "条鰭類",
+  "Insects": "昆虫",
+  "Arachnids": "クモ類",
+  "Plants": "植物",
+  "Fungi": "菌類",
+  "Other animals": "その他の動物",
+  "Other or unknown": "その他・不明",
+  "{label} {detail} — click to retry": "{label} {detail} — クリックして再試行",
+  "Wildlife sightings source unavailable": "野生生物の目撃情報源を利用できません",
+  "Show only community-confirmed (research-grade) sightings": "コミュニティが確認した研究グレードの目撃情報のみ表示",
+  "No recent sightings in view": "表示範囲に最近の目撃情報はありません",
+  "Acartia feed unavailable": "Acartiaのフィードを利用できません",
+  "Show all taxa": "すべての分類群を表示",
+  "BIRDS": "鳥類",
+  "Show only birds": "鳥類のみ表示",
+  "MAMMALS": "哺乳類",
+  "Show only mammals": "哺乳類のみ表示",
+  "WHALES": "クジラ類",
+  "Show only whales and dolphins (7 days)": "クジラとイルカのみ表示（7日間）",
+  "INSECTS": "昆虫",
+  "Show only insects": "昆虫のみ表示",
+  "PLANTS": "植物",
+  "Show only plants": "植物のみ表示",
+  "All rights reserved": "無断転載禁止",
+  "Cetacean": "クジラ類",
+  "Wildlife Sightings": "野生生物の目撃情報",
+  "Exit cockpit to fly to a sighting": "目撃地点に移動するにはコックピットを終了",
+  "Exit cockpit to fly to a sighting area": "目撃範囲に移動するにはコックピットを終了",
+  "Wildlife": "野生生物",
+  "Zoom in for local sightings": "拡大して地域の目撃情報を表示",
+  "Loading photo...": "写真を読み込み中…",
+  "Photo unavailable": "写真を表示できません",
+  "Location obscured to a 0.2° cell": "位置は0.2°のセル内に秘匿されています",
+  "Open on Acartia ↗": "Acartiaで開く ↗",
+  "Photo of {name}": "{name}の写真",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "表示範囲に{count}件の目撃情報",
+  "Close sighting": "目撃情報を閉じる",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "過去48時間以内に観察された野生生物（クジラ類は7日間）。色とバッジのアイコンは分類群を表します。保護が必要な種は0.2°の区画のみ表示し、セイリッシュ海のAcartia海生哺乳類目撃情報は0.01°に丸めます。個体数調査ではありません。",
+  "Open {name} on iNaturalist": "iNaturalistで{name}を開く",
+  "Open {name} on Acartia": "Acartiaで{name}を開く",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "iNaturalist の投稿者 · ライセンスは記録ごと",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "iNaturalist の投稿者 · Acartia {count}（セイリッシュ海） · ライセンスは記録ごと"
 }
diff --git a/src/i18n/locales/pt.json b/src/i18n/locales/pt.json
index 3f37cde2e..79e4d1066 100644
--- a/src/i18n/locales/pt.json
+++ b/src/i18n/locales/pt.json
@@ -3179,5 +3179,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "O provedor recusou a chave de API. Verifique-a em \"Configurações de provedores\".",
   "Too many chat requests. Try again in {seconds} s.": "Chat: limite de requisições atingido. Tente novamente em {seconds} s.",
   "The provider refused access for this key. Check the key's project, region or permissions.": "O provedor negou o acesso para esta chave. Verifique o projeto, a região ou as permissões da chave.",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "A conta do provedor está sem crédito. Verifique o faturamento ou escolha outro provedor de IA em \"Configurações\"."
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "A conta do provedor está sem crédito. Verifique o faturamento ou escolha outro provedor de IA em \"Configurações\".",
+  "SIGHTING": "AVISTAMENTO",
+  "Show {name} sighting": "Mostrar avistamento de {name}",
+  "seen {age} ago": "visto há {age}",
+  "observed {age} ago": "observado há {age}",
+  "Be Whale Wise": "Respeite os cetáceos",
+  "Reported by {name} ({entity})": "Relatado por {name} ({entity})",
+  "Reported by {name}": "Relatado por {name}",
+  "Salish Sea": "Mar de Salish",
+  "Birds": "Aves",
+  "Mammals": "Mamíferos",
+  "Reptiles": "Répteis",
+  "Amphibians": "Anfíbios",
+  "Ray-finned fishes": "Peixes de nadadeiras raiadas",
+  "Insects": "Insetos",
+  "Arachnids": "Aracnídeos",
+  "Plants": "Plantas",
+  "Fungi": "Fungos",
+  "Other animals": "Outros animais",
+  "Other or unknown": "Outros ou desconhecidos",
+  "{label} {detail} — click to retry": "{label} {detail} — clique para tentar novamente",
+  "Wildlife sightings source unavailable": "Fonte de avistamentos indisponível",
+  "Show only community-confirmed (research-grade) sightings": "Mostrar apenas observações confirmadas pela comunidade (grau de pesquisa)",
+  "No recent sightings in view": "Nenhum avistamento recente na vista",
+  "Acartia feed unavailable": "Feed Acartia indisponível",
+  "Show all taxa": "Mostrar todos os grupos taxonômicos",
+  "BIRDS": "AVES",
+  "Show only birds": "Mostrar apenas aves",
+  "MAMMALS": "MAMÍFEROS",
+  "Show only mammals": "Mostrar apenas mamíferos",
+  "WHALES": "CETÁCEOS",
+  "Show only whales and dolphins (7 days)": "Mostrar apenas baleias e golfinhos (7 dias)",
+  "INSECTS": "INSETOS",
+  "Show only insects": "Mostrar apenas insetos",
+  "PLANTS": "PLANTAS",
+  "Show only plants": "Mostrar apenas plantas",
+  "All rights reserved": "Todos os direitos reservados",
+  "Cetacean": "Cetáceo",
+  "Wildlife Sightings": "Avistamentos de vida selvagem",
+  "Exit cockpit to fly to a sighting": "Saia da cabine para voar até um avistamento",
+  "Exit cockpit to fly to a sighting area": "Saia da cabine para voar até uma área de avistamento",
+  "Wildlife": "Vida selvagem",
+  "Zoom in for local sightings": "Amplie para ver avistamentos locais",
+  "Loading photo...": "Carregando foto…",
+  "Photo unavailable": "Foto indisponível",
+  "Location obscured to a 0.2° cell": "Localização ocultada em uma célula de 0,2°",
+  "Open on Acartia ↗": "Abrir no Acartia ↗",
+  "Photo of {name}": "Foto de {name}",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "{count} avistamentos na vista",
+  "Close sighting": "Fechar avistamento",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "Fauna observada nas últimas 48 h (cetáceos 7 dias). A cor e o símbolo do emblema indicam o grupo taxonômico. Espécies sensíveis aparecem apenas em células de 0,2°; os relatos de mamíferos marinhos da Acartia no mar de Salish são arredondados para 0,01°. Não é um censo.",
+  "Open {name} on iNaturalist": "Abrir {name} no iNaturalist",
+  "Open {name} on Acartia": "Abrir {name} no Acartia",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "Colaboradores do iNaturalist · licenças por registro",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "Colaboradores do iNaturalist · Acartia {count} (mar de Salish) · licenças por registro"
 }
diff --git a/src/i18n/locales/ru.json b/src/i18n/locales/ru.json
index e279508ef..452cf7e35 100644
--- a/src/i18n/locales/ru.json
+++ b/src/i18n/locales/ru.json
@@ -3254,5 +3254,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "Провайдер отклонил ключ API. Проверьте его в «Настройках провайдеров».",
   "Too many chat requests. Try again in {seconds} s.": "Слишком много запросов в чате. Повторите попытку через {seconds} с.",
   "The provider refused access for this key. Check the key's project, region or permissions.": "Провайдер отказал этому ключу в доступе. Проверьте проект, регион или разрешения ключа.",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "На вашем счёте у провайдера закончились средства. Проверьте оплату или выберите другого провайдера ИИ в настройках."
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "На вашем счёте у провайдера закончились средства. Проверьте оплату или выберите другого провайдера ИИ в настройках.",
+  "SIGHTING": "НАБЛЮДЕНИЕ",
+  "Show {name} sighting": "Показать наблюдение: {name}",
+  "seen {age} ago": "замечено {age} назад",
+  "observed {age} ago": "наблюдалось {age} назад",
+  "Be Whale Wise": "Наблюдайте китов бережно",
+  "Reported by {name} ({entity})": "Сообщил: {name} ({entity})",
+  "Reported by {name}": "Сообщил: {name}",
+  "Salish Sea": "Селишское море",
+  "Birds": "Птицы",
+  "Mammals": "Млекопитающие",
+  "Reptiles": "Пресмыкающиеся",
+  "Amphibians": "Земноводные",
+  "Ray-finned fishes": "Лучепёрые рыбы",
+  "Insects": "Насекомые",
+  "Arachnids": "Паукообразные",
+  "Plants": "Растения",
+  "Fungi": "Грибы",
+  "Other animals": "Другие животные",
+  "Other or unknown": "Прочие или неизвестные",
+  "{label} {detail} — click to retry": "{label} {detail} — нажмите, чтобы повторить",
+  "Wildlife sightings source unavailable": "Источник наблюдений живой природы недоступен",
+  "Show only community-confirmed (research-grade) sightings": "Показать только подтверждённые сообществом наблюдения исследовательского уровня",
+  "No recent sightings in view": "Нет недавних наблюдений в области обзора",
+  "Acartia feed unavailable": "Лента Acartia недоступна",
+  "Show all taxa": "Показать все группы организмов",
+  "BIRDS": "ПТИЦЫ",
+  "Show only birds": "Показать только птиц",
+  "MAMMALS": "МЛЕКОПИТАЮЩИЕ",
+  "Show only mammals": "Показать только млекопитающих",
+  "WHALES": "КИТООБРАЗНЫЕ",
+  "Show only whales and dolphins (7 days)": "Показать только китов и дельфинов (7 дней)",
+  "INSECTS": "НАСЕКОМЫЕ",
+  "Show only insects": "Показать только насекомых",
+  "PLANTS": "РАСТЕНИЯ",
+  "Show only plants": "Показать только растения",
+  "All rights reserved": "Все права защищены",
+  "Cetacean": "Китообразное",
+  "Wildlife Sightings": "Наблюдения живой природы",
+  "Exit cockpit to fly to a sighting": "Выйдите из кабины, чтобы перейти к наблюдению",
+  "Exit cockpit to fly to a sighting area": "Выйдите из кабины, чтобы перейти к области наблюдения",
+  "Wildlife": "Живая природа",
+  "Zoom in for local sightings": "Приблизьте для местных наблюдений",
+  "Loading photo...": "Загрузка фото…",
+  "Photo unavailable": "Фото недоступно",
+  "Location obscured to a 0.2° cell": "Местоположение скрыто в ячейке 0,2°",
+  "Open on Acartia ↗": "Открыть на Acartia ↗",
+  "Photo of {name}": "Фото {name}",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "{count} наблюдений в области просмотра",
+  "Close sighting": "Закрыть наблюдение",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "Наблюдения дикой природы за 48 ч (китообразные — 7 дней). Цвет и символ значка обозначают таксономическую группу. Уязвимые виды показаны только ячейками 0,2°; сообщения Acartia о морских млекопитающих моря Селиш округлены до 0,01°. Не перепись.",
+  "Open {name} on iNaturalist": "Открыть {name} в iNaturalist",
+  "Open {name} on Acartia": "Открыть {name} в Acartia",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "Участники iNaturalist · лицензия у каждой записи",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "Участники iNaturalist · Acartia {count} (море Сэлиш) · лицензия у каждой записи"
 }
diff --git a/src/i18n/locales/uk.json b/src/i18n/locales/uk.json
index 8c3b634b9..64256b687 100644
--- a/src/i18n/locales/uk.json
+++ b/src/i18n/locales/uk.json
@@ -3254,5 +3254,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "Постачальник відхилив ключ API. Перевірте його в «Налаштуваннях постачальників».",
   "Too many chat requests. Try again in {seconds} s.": "Забагато запитів до чату. Спробуйте ще раз через {seconds} с.",
   "The provider refused access for this key. Check the key's project, region or permissions.": "Постачальник відмовив цьому ключу в доступі. Перевірте проєкт, регіон або дозволи ключа.",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "На вашому рахунку в постачальника закінчилися кошти. Перевірте оплату або виберіть іншого постачальника ШІ в налаштуваннях."
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "На вашому рахунку в постачальника закінчилися кошти. Перевірте оплату або виберіть іншого постачальника ШІ в налаштуваннях.",
+  "SIGHTING": "СПОСТЕРЕЖЕННЯ",
+  "Show {name} sighting": "Показати спостереження: {name}",
+  "seen {age} ago": "помічено {age} тому",
+  "observed {age} ago": "спостерігалося {age} тому",
+  "Be Whale Wise": "Спостерігайте за китами дбайливо",
+  "Reported by {name} ({entity})": "Повідомив: {name} ({entity})",
+  "Reported by {name}": "Повідомив: {name}",
+  "Salish Sea": "Салішське море",
+  "Birds": "Птахи",
+  "Mammals": "Ссавці",
+  "Reptiles": "Плазуни",
+  "Amphibians": "Земноводні",
+  "Ray-finned fishes": "Променепері риби",
+  "Insects": "Комахи",
+  "Arachnids": "Павукоподібні",
+  "Plants": "Рослини",
+  "Fungi": "Гриби",
+  "Other animals": "Інші тварини",
+  "Other or unknown": "Інші або невідомі",
+  "{label} {detail} — click to retry": "{label} {detail} — натисніть, щоб повторити",
+  "Wildlife sightings source unavailable": "Джерело спостережень живої природи недоступне",
+  "Show only community-confirmed (research-grade) sightings": "Показати лише підтверджені спільнотою спостереження дослідницького рівня",
+  "No recent sightings in view": "Немає недавніх спостережень в області огляду",
+  "Acartia feed unavailable": "Стрічка Acartia недоступна",
+  "Show all taxa": "Показати всі групи організмів",
+  "BIRDS": "ПТАХИ",
+  "Show only birds": "Показати лише птахів",
+  "MAMMALS": "ССАВЦІ",
+  "Show only mammals": "Показати лише ссавців",
+  "WHALES": "КИТОПОДІБНІ",
+  "Show only whales and dolphins (7 days)": "Показати лише китів і дельфінів (7 днів)",
+  "INSECTS": "КОМАХИ",
+  "Show only insects": "Показати лише комах",
+  "PLANTS": "РОСЛИНИ",
+  "Show only plants": "Показати лише рослини",
+  "All rights reserved": "Усі права захищено",
+  "Cetacean": "Китоподібне",
+  "Wildlife Sightings": "Спостереження живої природи",
+  "Exit cockpit to fly to a sighting": "Вийдіть із кабіни, щоб перейти до спостереження",
+  "Exit cockpit to fly to a sighting area": "Вийдіть із кабіни, щоб перейти до області спостереження",
+  "Wildlife": "Жива природа",
+  "Zoom in for local sightings": "Наблизьте для місцевих спостережень",
+  "Loading photo...": "Завантаження фото…",
+  "Photo unavailable": "Фото недоступне",
+  "Location obscured to a 0.2° cell": "Місцеположення приховано в комірці 0,2°",
+  "Open on Acartia ↗": "Відкрити на Acartia ↗",
+  "Photo of {name}": "Фото {name}",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "{count} спостережень у полі зору",
+  "Close sighting": "Закрити спостереження",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "Спостереження дикої природи за 48 год (китоподібні — 7 днів). Колір і символ значка позначають таксономічну групу. Вразливі види показано лише клітинками 0,2°; повідомлення Acartia про морських ссавців моря Селіш округлено до 0,01°. Не перепис.",
+  "Open {name} on iNaturalist": "Відкрити {name} в iNaturalist",
+  "Open {name} on Acartia": "Відкрити {name} в Acartia",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "Учасники iNaturalist · ліцензія в кожного запису",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "Учасники iNaturalist · Acartia {count} (море Селіш) · ліцензія в кожного запису"
 }
diff --git a/src/i18n/locales/zh-CN.json b/src/i18n/locales/zh-CN.json
index 6125315f2..90e6a41b1 100644
--- a/src/i18n/locales/zh-CN.json
+++ b/src/i18n/locales/zh-CN.json
@@ -3029,5 +3029,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "服务商拒绝了 API 密钥。请在服务商设置中检查。",
   "Too many chat requests. Try again in {seconds} s.": "聊天请求过多。请在 {seconds} 秒后重试。",
   "The provider refused access for this key. Check the key's project, region or permissions.": "服务商拒绝了此密钥的访问请求。请检查该密钥所属的项目、区域或权限。",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "服务商账户余额不足。请检查账户的计费信息，或在设置中选择其他 AI 服务商。"
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "服务商账户余额不足。请检查账户的计费信息，或在设置中选择其他 AI 服务商。",
+  "SIGHTING": "目击",
+  "Show {name} sighting": "显示{name}目击",
+  "seen {age} ago": "{age}前目击",
+  "observed {age} ago": "{age}前观察",
+  "Be Whale Wise": "负责任地观鲸",
+  "Reported by {name} ({entity})": "报告方 {name}（{entity}）",
+  "Reported by {name}": "报告方 {name}",
+  "Salish Sea": "萨利希海",
+  "Birds": "鸟类",
+  "Mammals": "哺乳类",
+  "Reptiles": "爬行动物",
+  "Amphibians": "两栖动物",
+  "Ray-finned fishes": "辐鳍鱼类",
+  "Insects": "昆虫",
+  "Arachnids": "蛛形动物",
+  "Plants": "植物",
+  "Fungi": "真菌",
+  "Other animals": "其他动物",
+  "Other or unknown": "其他或未知",
+  "{label} {detail} — click to retry": "{label} {detail} — 点击重试",
+  "Wildlife sightings source unavailable": "野生生物目击来源不可用",
+  "Show only community-confirmed (research-grade) sightings": "仅显示社区确认（研究级）的目击",
+  "No recent sightings in view": "视野内无近期目击",
+  "Acartia feed unavailable": "Acartia数据源不可用",
+  "Show all taxa": "显示所有分类群",
+  "BIRDS": "鸟类",
+  "Show only birds": "仅显示鸟类",
+  "MAMMALS": "哺乳类",
+  "Show only mammals": "仅显示哺乳类",
+  "WHALES": "鲸类",
+  "Show only whales and dolphins (7 days)": "仅显示鲸和海豚（7天）",
+  "INSECTS": "昆虫",
+  "Show only insects": "仅显示昆虫",
+  "PLANTS": "植物",
+  "Show only plants": "仅显示植物",
+  "All rights reserved": "保留所有权利",
+  "Cetacean": "鲸类",
+  "Wildlife Sightings": "野生生物目击",
+  "Exit cockpit to fly to a sighting": "退出驾驶舱以飞往目击地点",
+  "Exit cockpit to fly to a sighting area": "退出驾驶舱以飞往目击区域",
+  "Wildlife": "野生生物",
+  "Zoom in for local sightings": "放大查看当地目击",
+  "Loading photo...": "正在加载照片…",
+  "Photo unavailable": "照片不可用",
+  "Location obscured to a 0.2° cell": "位置已模糊至0.2°网格",
+  "Open on Acartia ↗": "在Acartia上打开 ↗",
+  "Photo of {name}": "{name}的照片",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "视野内有 {count} 次目击",
+  "Close sighting": "关闭目击记录",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "近48小时内观察到的野生生物（鲸类为7天）。颜色与徽章图标表示分类群。敏感物种仅以0.2°网格显示；Acartia提供的萨利希海海洋哺乳动物目击位置四舍五入到0.01°。并非种群普查。",
+  "Open {name} on iNaturalist": "在 iNaturalist 上打开 {name}",
+  "Open {name} on Acartia": "在 Acartia 上打开 {name}",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "iNaturalist 贡献者 · 各记录单独授权",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "iNaturalist 贡献者 · Acartia {count}（萨利希海） · 各记录单独授权"
 }
diff --git a/src/i18n/locales/zh-Hant.json b/src/i18n/locales/zh-Hant.json
index 66eb37b96..4c54652a3 100644
--- a/src/i18n/locales/zh-Hant.json
+++ b/src/i18n/locales/zh-Hant.json
@@ -3029,5 +3029,62 @@
   "The provider rejected the API key. Check it in Provider Settings.": "服務商拒絕了 API 密鑰。請在服務商設置中檢查。",
   "Too many chat requests. Try again in {seconds} s.": "聊天請求過多。請在 {seconds} 秒後重試。",
   "The provider refused access for this key. Check the key's project, region or permissions.": "服務商拒絕了此密鑰的訪問請求。請檢查該密鑰所屬的項目、區域或權限。",
-  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "服務商賬戶餘額不足。請檢查賬戶的計費信息，或在設置中選擇其他 AI 服務商。"
+  "The provider account is out of credit. Check its billing, or choose another AI Provider in Settings.": "服務商賬戶餘額不足。請檢查賬戶的計費信息，或在設置中選擇其他 AI 服務商。",
+  "SIGHTING": "目擊",
+  "Show {name} sighting": "顯示{name}目擊",
+  "seen {age} ago": "{age}前目擊",
+  "observed {age} ago": "{age}前觀察",
+  "Be Whale Wise": "負責任地賞鯨",
+  "Reported by {name} ({entity})": "通報方 {name}（{entity}）",
+  "Reported by {name}": "通報方 {name}",
+  "Salish Sea": "薩利希海",
+  "Birds": "鳥類",
+  "Mammals": "哺乳類",
+  "Reptiles": "爬行動物",
+  "Amphibians": "兩棲動物",
+  "Ray-finned fishes": "輻鰭魚類",
+  "Insects": "昆蟲",
+  "Arachnids": "蛛形動物",
+  "Plants": "植物",
+  "Fungi": "真菌",
+  "Other animals": "其他動物",
+  "Other or unknown": "其他或未知",
+  "{label} {detail} — click to retry": "{label} {detail} — 點擊重試",
+  "Wildlife sightings source unavailable": "野生生物目擊來源無法使用",
+  "Show only community-confirmed (research-grade) sightings": "僅顯示社群確認（研究級）的目擊",
+  "No recent sightings in view": "視野內無近期目擊",
+  "Acartia feed unavailable": "Acartia資料來源無法使用",
+  "Show all taxa": "顯示所有分類群",
+  "BIRDS": "鳥類",
+  "Show only birds": "僅顯示鳥類",
+  "MAMMALS": "哺乳類",
+  "Show only mammals": "僅顯示哺乳類",
+  "WHALES": "鯨類",
+  "Show only whales and dolphins (7 days)": "僅顯示鯨和海豚（7天）",
+  "INSECTS": "昆蟲",
+  "Show only insects": "僅顯示昆蟲",
+  "PLANTS": "植物",
+  "Show only plants": "僅顯示植物",
+  "All rights reserved": "保留所有權利",
+  "Cetacean": "鯨類",
+  "Wildlife Sightings": "野生生物目擊",
+  "Exit cockpit to fly to a sighting": "退出駕駛艙以飛往目擊地點",
+  "Exit cockpit to fly to a sighting area": "退出駕駛艙以飛往目擊區域",
+  "Wildlife": "野生生物",
+  "Zoom in for local sightings": "放大查看當地目擊",
+  "Loading photo...": "正在載入照片…",
+  "Photo unavailable": "照片無法使用",
+  "Location obscured to a 0.2° cell": "位置已模糊至0.2°網格",
+  "Open on Acartia ↗": "在Acartia上開啟 ↗",
+  "Photo of {name}": "{name}的照片",
+  "Acartia": "Acartia",
+  "CC BY 4.0": "CC BY 4.0",
+  "{count} sightings in view": "視野內有 {count} 次目擊",
+  "Close sighting": "關閉目擊紀錄",
+  "Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.": "近48小時內觀察到的野生生物（鯨類為7天）。顏色與徽章圖示表示分類群。敏感物種僅以0.2°網格顯示；Acartia提供的薩利希海海洋哺乳動物目擊位置四捨五入到0.01°。並非族群普查。",
+  "Open {name} on iNaturalist": "在 iNaturalist 上打開 {name}",
+  "Open {name} on Acartia": "在 Acartia 上打開 {name}",
+  "iNaturalist": "iNaturalist",
+  "iNaturalist contributors · licences per record": "iNaturalist 貢獻者 · 各紀錄個別授權",
+  "iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record": "iNaturalist 貢獻者 · Acartia {count}（薩利希海） · 各紀錄個別授權"
 }
diff --git a/src/i18n/same-as-english.json b/src/i18n/same-as-english.json
index 7edaad647..0dc9841f7 100644
--- a/src/i18n/same-as-english.json
+++ b/src/i18n/same-as-english.json
@@ -4,10 +4,12 @@
     "978 MHz UAT",
     "AIS: --",
     "AIS: {name}",
+    "Acartia",
     "BRG {value}°",
     "BRG —",
     "CAL {value}",
     "CAL · {badge}",
+    "CC BY 4.0",
     "CCTV",
     "CRS {value}°",
     "CRT",
@@ -28,8 +30,11 @@
     "SRC {value}",
     "Sentinel-2",
     "WHOT/BHOT",
+    "acartia.io ↗",
     "dB",
     "hPa",
+    "iNaturalist",
+    "iNaturalist ↗",
     "{source} HTTP {status}",
     "▲ {frp} MW"
   ],
@@ -40,6 +45,7 @@
     "AIS: {name}",
     "ANIME",
     "AUTO",
+    "Acartia",
     "Alternative",
     "Ambient",
     "Anime",
@@ -50,6 +56,7 @@
     "Bloom",
     "Blues",
     "Bus",
+    "CC BY 4.0",
     "CCTV",
     "CHAT",
     "COCKPIT",
@@ -178,11 +185,14 @@
     "WSW",
     "Washington DC",
     "Wind",
+    "acartia.io ↗",
     "dB",
     "feed status|live",
     "fire behavior|Minimal",
     "ft",
     "hPa",
+    "iNaturalist",
+    "iNaturalist ↗",
     "km",
     "km/h",
     "min",
@@ -334,15 +344,24 @@
     "≥ {value} MW",
     "ΔE",
     "ΔN",
-    "▲ {frp} MW"
+    "▲ {frp} MW",
+    "ANIMAL · {name}",
+    "Acartia",
+    "CC BY 4.0",
+    "Reptiles",
+    "acartia.io ↗",
+    "iNaturalist ↗",
+    "iNaturalist"
   ],
   "fr": [
     "1090 MHz",
     "978 MHz UAT",
     "ALTITUDE",
     "ALTITUDE · FT",
+    "ANIMAL · {name}",
     "ANIME",
     "AUTO",
+    "Acartia",
     "Action",
     "Allocation",
     "Altitude {altitude}",
@@ -361,6 +380,7 @@
     "CALIBRATION",
     "CARGO",
     "CAUSE",
+    "CC BY 4.0",
     "CCTV",
     "CCTV OFF",
     "CCTV ON",
@@ -437,6 +457,7 @@
     "OK",
     "ON",
     "ON/OFF",
+    "Obs. {licence}",
     "Oldies",
     "PAUSE",
     "POSITION {age}",
@@ -452,8 +473,10 @@
     "RADAR · {units}",
     "RADIO",
     "REC",
+    "REPTILE · {name}",
     "Radio",
     "Reggae",
+    "Reptiles",
     "Rock",
     "S2 GhostMaps",
     "SAR",
@@ -488,10 +511,13 @@
     "VOLUME",
     "VS",
     "WHOT/BHOT",
+    "acartia.io ↗",
     "audio {state}",
     "dB",
     "ft",
     "hPa",
+    "iNaturalist",
+    "iNaturalist ↗",
     "image",
     "installation class|BASE",
     "installation class|INSTALLATION",
@@ -694,17 +720,24 @@
     "≥ {value} MW",
     "ΔE",
     "ΔN",
-    "▲ {frp} MW"
+    "▲ {frp} MW",
+    "Acartia",
+    "CC BY 4.0",
+    "acartia.io ↗",
+    "iNaturalist ↗",
+    "iNaturalist"
   ],
   "ja": [
     "1090 MHz",
     "978 MHz UAT",
     "AIS: --",
     "AIS: {name}",
+    "Acartia",
     "BRG {value}°",
     "BRG —",
     "CAL {value}",
     "CAL · {badge}",
+    "CC BY 4.0",
     "CCTV",
     "CH {index} / {total}",
     "CRS {value}°",
@@ -729,9 +762,12 @@
     "Sentinel-2",
     "USB {rate} msg/s",
     "WHOT/BHOT",
+    "acartia.io ↗",
     "dB",
     "ft",
     "hPa",
+    "iNaturalist",
+    "iNaturalist ↗",
     "km",
     "km/h",
     "kt",
@@ -877,11 +913,19 @@
     "{value} KM/S",
     "ΔN",
     "▲ {frp} MW",
-    "≥ {value} MW"
+    "≥ {value} MW",
+    "ANIMAL · {name}",
+    "Acartia",
+    "CC BY 4.0",
+    "acartia.io ↗",
+    "iNaturalist ↗",
+    "iNaturalist"
   ],
   "ru": [
     "AIS: --",
     "AIS: {name}",
+    "Acartia",
+    "CC BY 4.0",
     "CCTV",
     "CRT",
     "FLIR",
@@ -895,11 +939,16 @@
     "S2 GhostMaps",
     "S2 · {name}",
     "VS",
-    "WHOT/BHOT"
+    "WHOT/BHOT",
+    "acartia.io ↗",
+    "iNaturalist",
+    "iNaturalist ↗"
   ],
   "uk": [
     "AIS: --",
     "AIS: {name}",
+    "Acartia",
+    "CC BY 4.0",
     "CCTV",
     "CRT",
     "FLIR",
@@ -908,7 +957,10 @@
     "NVG",
     "REC",
     "S2 GhostMaps",
-    "WHOT/BHOT"
+    "WHOT/BHOT",
+    "acartia.io ↗",
+    "iNaturalist",
+    "iNaturalist ↗"
   ],
   "zh-CN": [
     "1090 MHz",
@@ -966,7 +1018,12 @@
     "≥ {value} MW",
     "ΔE",
     "ΔN",
-    "▲ {frp} MW"
+    "▲ {frp} MW",
+    "Acartia",
+    "CC BY 4.0",
+    "acartia.io ↗",
+    "iNaturalist ↗",
+    "iNaturalist"
   ],
   "zh-Hant": [
     "1090 MHz",
@@ -1024,6 +1081,11 @@
     "≥ {value} MW",
     "ΔE",
     "ΔN",
-    "▲ {frp} MW"
+    "▲ {frp} MW",
+    "Acartia",
+    "CC BY 4.0",
+    "acartia.io ↗",
+    "iNaturalist ↗",
+    "iNaturalist"
   ]
 }
diff --git a/src/layers/wildlifeSightings/acartiaTaxa.js b/src/layers/wildlifeSightings/acartiaTaxa.js
new file mode 100644
index 000000000..d5396c04d
--- /dev/null
+++ b/src/layers/wildlifeSightings/acartiaTaxa.js
@@ -0,0 +1,155 @@
+// The regional feed includes sightings outside the layer's Salish Sea coverage.
+export const ACARTIA_GUARD_BOX = Object.freeze({
+  south: 45.5,
+  west: -126,
+  north: 50.5,
+  east: -121,
+});
+
+// Frozen, conservative cetacean species/alias list for this regional feed.
+// Exact normalized names only: an unfamiliar name must never become a whale
+// merely because it contains "whale", "dolphin" or a known species name.
+export const ACARTIA_CETACEAN_NAMES = Object.freeze([
+  'Orcinus orca',
+  'Orca',
+  'Killer whale',
+  'Southern resident killer whale',
+  'Northern resident killer whale',
+  'Resident killer whale',
+  "Bigg's killer whale",
+  'Transient killer whale',
+  'Offshore killer whale',
+  'Megaptera novaeangliae',
+  'Humpback whale',
+  'Humpback',
+  'Eschrichtius robustus',
+  'Gray whale',
+  'Grey whale',
+  'Balaenoptera acutorostrata',
+  'Common minke whale',
+  'Minke whale',
+  'Balaenoptera physalus',
+  'Fin whale',
+  'Finback whale',
+  'Balaenoptera musculus',
+  'Blue whale',
+  'Balaenoptera borealis',
+  'Sei whale',
+  'Eubalaena japonica',
+  'North Pacific right whale',
+  'Physeter macrocephalus',
+  'Sperm whale',
+  'Kogia breviceps',
+  'Pygmy sperm whale',
+  'Kogia sima',
+  'Dwarf sperm whale',
+  'Berardius bairdii',
+  "Baird's beaked whale",
+  'Ziphius cavirostris',
+  "Cuvier's beaked whale",
+  'Mesoplodon carlhubbsi',
+  "Hubbs' beaked whale",
+  'Mesoplodon stejnegeri',
+  "Stejneger's beaked whale",
+  'Mesoplodon ginkgodens',
+  'Ginkgo-toothed beaked whale',
+  'Phocoena phocoena',
+  'Harbor porpoise',
+  'Harbour porpoise',
+  'Phocoenoides dalli',
+  "Dall's porpoise",
+  'Lagenorhynchus obliquidens',
+  'Pacific white-sided dolphin',
+  'Lissodelphis borealis',
+  'Northern right whale dolphin',
+  'Grampus griseus',
+  "Risso's dolphin",
+  'Delphinus delphis',
+  'Short-beaked common dolphin',
+  'Common dolphin',
+  'Delphinus capensis',
+  'Long-beaked common dolphin',
+  'Tursiops truncatus',
+  'Common bottlenose dolphin',
+  'Bottlenose dolphin',
+  'Delphinapterus leucas',
+  'Beluga whale',
+  'Beluga',
+  'Pseudorca crassidens',
+  'False killer whale',
+  'Globicephala macrorhynchus',
+  'Short-finned pilot whale',
+]);
+
+// These names clearly identify a marine mammal but do not establish a species
+// in the cetacean list. Retain them for ALL/MAMMALS, never for WHALES.
+const OTHER_MARINE_MAMMAL_NAMES = Object.freeze([
+  'Phoca vitulina',
+  'Harbor seal',
+  'Harbour seal',
+  'Mirounga angustirostris',
+  'Northern elephant seal',
+  'Zalophus californianus',
+  'California sea lion',
+  'Eumetopias jubatus',
+  'Steller sea lion',
+  "Steller's sea lion",
+  'Callorhinus ursinus',
+  'Northern fur seal',
+  'Enhydra lutris',
+  'Sea otter',
+  'Seal',
+  'Unidentified seal',
+  'Sea lion',
+  'Unidentified sea lion',
+  'Pinniped',
+  'Unidentified pinniped',
+  'Marine mammal',
+  'Unidentified marine mammal',
+  'Unknown marine mammal',
+  'Cetacean',
+  'Unidentified cetacean',
+  'Unknown cetacean',
+  'Whale',
+  'Unidentified whale',
+  'Unknown whale',
+  'Dolphin',
+  'Unidentified dolphin',
+  'Unknown dolphin',
+  'Porpoise',
+  'Unidentified porpoise',
+  'Unknown porpoise',
+]);
+
+function speciesKey(value) {
+  return typeof value === 'string'
+    ? value
+        .trim()
+        .toLowerCase()
+        .replace(/[\u2018\u2019]/g, "'")
+        .replace(/[\u2010-\u2015]/g, '-')
+        .replace(/\s+/g, ' ')
+    : '';
+}
+
+const CETACEANS = new Set(ACARTIA_CETACEAN_NAMES.map(speciesKey));
+const OTHER_MARINE_MAMMALS = new Set(OTHER_MARINE_MAMMAL_NAMES.map(speciesKey));
+
+/** Classify exact normalized species names; ambiguous sightings stay noncetacean. */
+export function acartiaSpeciesGroup(value) {
+  const key = speciesKey(value);
+  if (CETACEANS.has(key)) return 'cetacean';
+  return OTHER_MARINE_MAMMALS.has(key) ? 'marine-mammal' : null;
+}
+
+/** Accept only positions inside the supported Salish Sea coverage. */
+export function inAcartiaCoverage(lat, lon) {
+  return (
+    Number.isFinite(lat) &&
+    Number.isFinite(lon) &&
+    lat >= ACARTIA_GUARD_BOX.south &&
+    lat <= ACARTIA_GUARD_BOX.north &&
+    lon >= ACARTIA_GUARD_BOX.west &&
+    lon <= ACARTIA_GUARD_BOX.east
+  );
+}
diff --git a/src/layers/wildlifeSightings/acartiaTaxa.test.mjs b/src/layers/wildlifeSightings/acartiaTaxa.test.mjs
new file mode 100644
index 000000000..c17cbd4fc
--- /dev/null
+++ b/src/layers/wildlifeSightings/acartiaTaxa.test.mjs
@@ -0,0 +1,37 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ACARTIA_CETACEAN_NAMES, acartiaSpeciesGroup } from './acartiaTaxa.js';
+
+test('frozen cetacean names accept only normalized exact species or aliases', () => {
+  assert.equal(Object.isFrozen(ACARTIA_CETACEAN_NAMES), true);
+  assert.throws(() => ACARTIA_CETACEAN_NAMES.push('Whale shark'), TypeError);
+  for (const name of ACARTIA_CETACEAN_NAMES) {
+    assert.equal(acartiaSpeciesGroup(name), 'cetacean');
+    assert.equal(acartiaSpeciesGroup(`  ${name.toUpperCase()}  `), 'cetacean');
+    assert.equal(acartiaSpeciesGroup(`${name} or another animal`), null);
+  }
+  assert.equal(acartiaSpeciesGroup('Dall’s porpoise'), 'cetacean');
+  assert.equal(acartiaSpeciesGroup('Pacific white–sided dolphin'), 'cetacean');
+  assert.equal(acartiaSpeciesGroup('  HARBOR  PORPOISE '), 'cetacean');
+});
+
+test('clearly marine mammal names remain distinct from validated cetacean species', () => {
+  for (const name of [
+    'Harbor seal',
+    'Phoca vitulina',
+    'Sea otter',
+    'Unidentified whale',
+  ]) {
+    assert.equal(acartiaSpeciesGroup(name), 'marine-mammal');
+  }
+  for (const name of [
+    'Unknown',
+    'Whale shark',
+    'Elephant',
+    '',
+    null,
+    { species: 'Orca' },
+  ]) {
+    assert.equal(acartiaSpeciesGroup(name), null);
+  }
+});
diff --git a/src/layers/wildlifeSightings/acquisition.test.mjs b/src/layers/wildlifeSightings/acquisition.test.mjs
new file mode 100644
index 000000000..ea1d6fc1a
--- /dev/null
+++ b/src/layers/wildlifeSightings/acquisition.test.mjs
@@ -0,0 +1,944 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { getLocale, setLocale } from '../../i18n/index.js';
+import { translateFeedError } from '../../ui/statusText.js';
+import { createControls } from './controls.js';
+import { createLifecycle } from './lifecycle.js';
+import { createWildlifeSightingsSource } from './source.js';
+import { wildlifeGridCellId } from './gridViewport.js';
+import { LayerLifecycle } from '../../data/lifecycle.js';
+import { layerFeedState } from '../../data/feedState.js';
+
+const NOW = Date.UTC(2026, 10, 4, 18);
+const rectangle = { south: 10, west: 10, north: 12, east: 12 };
+const noop = () => {};
+
+function harness(source = { getSnapshot: async () => [] }) {
+  let time = NOW;
+  let bounds = rectangle;
+  let timerId = 0;
+  let notifications = 0;
+  let managerRequests = 0;
+  const timers = new Map();
+  const cameraListeners = new Set();
+  const document = { hidden: false };
+  const state = {
+    viewer: {
+      camera: {
+        moveEnd: {
+          addEventListener(fn) {
+            cameraListeners.add(fn);
+            return () => cameraListeners.delete(fn);
+          },
+        },
+        positionCartographic: { height: 30_000 },
+        computeViewRectangle: () =>
+          bounds &&
+          Object.fromEntries(
+            Object.entries(bounds).map(([key, value]) => [
+              key,
+              (value * Math.PI) / 180,
+            ]),
+          ),
+      },
+    },
+    enabled: true,
+    destroyed: false,
+    points: {},
+    rows: new Map(),
+    renderedRows: [],
+    rowById: new Map(),
+    selectedId: null,
+    selectedRow: null,
+    confirmed: false,
+    taxa: 'all',
+    drawnParams: null,
+    pendingParams: null,
+    failedParams: null,
+    lastUpdate: null,
+    retryAt: 0,
+    failures: 0,
+    controlsListener: () => notifications++,
+  };
+  const services = {
+    source,
+    now: () => time,
+    eventTarget: { document },
+    setTimer(fn, delay) {
+      const id = ++timerId;
+      timers.set(id, { fn, delay, due: time + delay });
+      return id;
+    },
+    clearTimer: (id) => timers.delete(id),
+  };
+  const parts = {
+    rendering: {
+      rebuild() {
+        state.renderedRows = [...state.rows.values()];
+        state.rowById = new Map(state.rows);
+        state.sightingCount = state.gridAvailable
+          ? state.gridTotal
+          : state.renderedRows.length;
+        return true;
+      },
+      cull: noop,
+      clear: noop,
+      destroy: noop,
+      requestRender: noop,
+    },
+    photos: { clear: noop, destroy: noop },
+    selection: {
+      sourceIds: [],
+      install: noop,
+      refreshAmbient: noop,
+      publishSelected: noop,
+      notify: noop,
+      destroy: noop,
+      refreshContexts: noop,
+      syncCredits: noop,
+      remove: noop,
+      clear() {
+        state.selectedId = null;
+        state.selectedRow = null;
+      },
+    },
+  };
+  const owner = { state, services, parts };
+  parts.controls = createControls(owner);
+  parts.lifecycle = createLifecycle(owner);
+  const layer = {
+    ...parts.controls.methods,
+    ...parts.lifecycle.methods,
+  };
+  layer.attachDataManager({
+    refreshLayer(_id, options) {
+      managerRequests++;
+      return layer.update(undefined, options);
+    },
+  });
+  return {
+    state,
+    layer,
+    parts,
+    timers,
+    document,
+    chip: (id = 'taxa-all') =>
+      layer.getRowControls().chips.find((chip) => chip.id === id),
+    bounds: (value) => {
+      bounds = value;
+    },
+    notifications: () => notifications,
+    managerRequests: () => managerRequests,
+    moveEnd: () => {
+      for (const listener of cameraListeners) listener();
+    },
+    async advance(ms) {
+      time += ms;
+      for (const [id, timer] of [...timers]) {
+        if (timer.due <= time) {
+          timers.delete(id);
+          timer.fn();
+        }
+      }
+      // Timer callbacks intentionally detach manager work. Flush the promise
+      // chain to observe its result without wall-clock time or network access.
+      await new Promise((resolve) => setImmediate(resolve));
+    },
+  };
+}
+
+test('retrying a failed chip during cooldown schedules its deadline through the manager', async () => {
+  let attempts = 0;
+  const h = harness({
+    getSnapshot: async () => {
+      if (++attempts === 1)
+        throw Object.assign(new Error('iNaturalist rate limited'), {
+          status: 429,
+        });
+      return [];
+    },
+  });
+  await h.layer.update();
+  assert.equal(h.chip().state, 'error');
+  assert.equal(h.layer.getStats().retryInSec, 30);
+  h.layer.setParams(h.chip().params);
+  assert.equal(h.chip().state, 'loading');
+  assert.equal(h.timers.size, 1, 'retry retains one scheduled acquisition');
+  assert.equal([...h.timers.values()][0].delay, 30_000);
+  await h.advance(29_999);
+  assert.equal(attempts, 1);
+  await h.advance(1);
+  assert.equal(attempts, 2);
+  assert.equal(h.managerRequests(), 1);
+  assert.equal(h.chip().state, 'active');
+  assert.equal(h.chip().busy, false);
+  assert.equal(h.timers.size, 0);
+  assert.equal(h.layer.getStats().retryInSec, undefined);
+});
+
+test('parameter chips stop being pending when acquisition has no usable viewport or is disabled', async () => {
+  for (const scenario of ['no viewport', 'disabled']) {
+    const h = harness();
+    if (scenario === 'no viewport') h.bounds(null);
+    else h.layer.disable();
+    h.layer.setParams({ taxa: 'Aves' });
+    assert.equal(h.chip('taxa-birds').busy, false, scenario);
+    assert.equal(h.chip('taxa-birds').disabled, false, scenario);
+    assert.equal(h.timers.size, 0, scenario);
+    assert.ok(h.notifications() > 0, scenario);
+  }
+  const h = harness();
+  h.layer.setParams({ taxa: 'Aves' });
+  assert.equal(h.chip('taxa-birds').busy, true);
+  h.layer.disable();
+  assert.equal(h.chip('taxa-birds').busy, false);
+  assert.equal(h.timers.size, 0);
+});
+
+test('an unusable viewport at a local height never invents zoom-in guidance', async () => {
+  const h = harness({
+    getSnapshot: () =>
+      assert.fail('oversized snapped boxes must not be fetched'),
+  });
+  h.bounds({ south: 10.2, west: 0, north: 50.1, east: 1 });
+  assert.equal(await h.layer.update(), true);
+  assert.equal(h.layer.getStats().status, undefined);
+  assert.equal(h.state.query, null);
+  assert.equal(h.timers.size, 0);
+});
+
+test('deferred acquisition clears pending chips if its view disappears, the page hides or the manager declines', async () => {
+  for (const scenario of ['no viewport', 'hidden', 'manager declined']) {
+    const h = harness({
+      getSnapshot: () => assert.fail('acquisition must not proceed'),
+    });
+    h.layer.setParams({ taxa: 'Aves' });
+    assert.equal(h.chip('taxa-birds').busy, true);
+    if (scenario === 'no viewport') h.bounds(null);
+    if (scenario === 'hidden') h.document.hidden = true;
+    if (scenario === 'manager declined')
+      h.layer.attachDataManager({ refreshLayer: async () => false });
+    await h.advance(600);
+    assert.equal(h.chip('taxa-birds').busy, false, scenario);
+    assert.equal(h.chip('taxa-birds').disabled, false, scenario);
+    assert.equal(h.timers.size, 0, scenario);
+  }
+});
+
+test('a filter deferred by an unavailable viewport becomes pending when acquisition can resume', async () => {
+  let resolve;
+  let ready = true;
+  const h = harness({
+    getSnapshot: () =>
+      ready
+        ? Promise.resolve([])
+        : new Promise((done) => {
+            resolve = done;
+          }),
+  });
+  await h.layer.update();
+  h.bounds(null);
+  h.layer.setParams({ taxa: 'Aves' });
+  assert.equal(h.chip('taxa-birds').busy, false);
+  assert.equal(h.chip().active, true, 'the last accepted filter stays active');
+  ready = false;
+  await h.advance(500);
+  h.bounds(rectangle);
+  const update = h.layer.update();
+  assert.equal(h.chip('taxa-birds').busy, true);
+  assert.equal(h.chip('taxa-birds').active, false);
+  resolve([]);
+  await update;
+  assert.equal(h.chip('taxa-birds').active, true);
+  assert.equal(h.chip('taxa-birds').busy, false);
+});
+
+test('long Retry-After and daily-budget deadlines survive source errors and control manager retries', async () => {
+  const nextMidnight = Date.UTC(2026, 10, 5);
+  for (const [retryAfter, expectedSeconds] of [
+    ['3600', 3600],
+    [new Date(nextMidnight).toUTCString(), 21_600],
+  ]) {
+    let requests = 0;
+    const source = createWildlifeSightingsSource({
+      now: () => NOW,
+      fetchImpl: async (url) => {
+        if (url.startsWith('/api/inaturalist/grid?'))
+          return Response.json({ cells: [], totalResults: 0, fetchedAt: NOW });
+        requests++;
+        return requests === 1
+          ? new Response('', {
+              status: 429,
+              headers: {
+                'Retry-After': retryAfter,
+                'X-Upstream-Status': '429',
+              },
+            })
+          : Response.json({ rows: [], totalResults: 0 });
+      },
+    });
+    const h = harness(source);
+    await h.layer.update();
+    assert.equal(h.layer.getStats().retryInSec, expectedSeconds);
+    h.layer.setParams(h.chip().params);
+    assert.equal([...h.timers.values()][0]?.delay, expectedSeconds * 1000);
+    await h.advance(expectedSeconds * 1000 - 1);
+    assert.equal(
+      requests,
+      1,
+      'neither debounce nor the normal poll shortens the deadline',
+    );
+    await h.layer.update();
+    assert.equal(requests, 1, 'manager polling also observes the cooldown');
+    await h.advance(1);
+    assert.equal(requests, 2);
+    assert.equal(h.managerRequests(), 1);
+    assert.equal(h.chip().state, 'active');
+  }
+});
+
+test('failed-chip titles translate feed error patterns in German', () => {
+  const locale = getLocale();
+  try {
+    setLocale('de');
+    const h = harness();
+    h.state.failedParams = { confirmed: false, taxa: 'all', keys: ['taxa'] };
+    for (const error of [
+      'iNaturalist rate limited',
+      'Malformed iNaturalist response',
+    ]) {
+      h.state.error = error;
+      const translated = translateFeedError(error);
+      assert.notEqual(translated, error);
+      assert.ok(h.chip().title.includes(translated), h.chip().title);
+      assert.equal(h.chip().title.includes(error), false);
+    }
+  } finally {
+    setLocale(locale);
+  }
+});
+
+const sighting = {
+  stableId: 'inat:101',
+  origin: 'inaturalist',
+  lat: 11,
+  lon: 11,
+  observedAt: NOW - 3_600_000,
+  iconic: 'Mammalia',
+  commonName: 'Synthetic whale',
+};
+
+test('SF WHALES failure keeps chosen error chip, drawn rows and manager DEGRADED with retry at 250 km', async () => {
+  const drawn = { ...sighting, lat: 37.7, lon: -122.5 };
+  let fail = false;
+  let gridRequests = 0;
+  const h = harness({
+    getSnapshotDetail: async () => {
+      if (fail)
+        throw Object.assign(new Error('iNaturalist HTTP 502'), {
+          status: 502,
+          retryAfterSec: 45,
+        });
+      return { rows: [drawn], totalResults: 1, fetchedAt: NOW };
+    },
+    getGridSnapshot: async () => {
+      gridRequests++;
+      return { cells: [], totalResults: 12, fetchedAt: NOW };
+    },
+  });
+  h.bounds({ south: 37.2, west: -123, north: 38.2, east: -122 });
+  h.state.viewer.camera.positionCartographic.height = 250_000;
+  const manager = new LayerLifecycle(h.state.viewer);
+  manager.register({ ...h.layer, init: () => true, updateInterval: 0 });
+  h.layer.attachDataManager(manager);
+  try {
+    assert.equal(await manager.setEnabled(h.layer.id, true), true);
+    const previousUpdate = h.layer.getStats().lastUpdate;
+    const previousRows = h.state.renderedRows;
+    fail = true;
+    h.layer.setParams({ taxa: 'whales' });
+    await h.advance(2500);
+    const chip = h.chip('taxa-whales');
+    assert.deepEqual(h.layer.getParams(), { confirmed: false, taxa: 'whales' });
+    assert.equal(chip.active, true);
+    assert.equal(chip.state, 'error');
+    assert.equal(chip.disabled, false);
+    assert.match(chip.title, /iNaturalist HTTP 502.*click to retry/);
+    assert.equal(h.chip('taxa-all').active, false);
+    assert.equal(h.state.renderedRows, previousRows);
+    assert.deepEqual([...h.state.rows.values()], [drawn]);
+    assert.equal(h.layer.getStats().lastUpdate, previousUpdate);
+    const stats = manager.getAll()[0].stats;
+    assert.equal(stats.error, 'iNaturalist HTTP 502');
+    assert.equal(stats.managerRefreshError, 'iNaturalist HTTP 502');
+    assert.equal(stats.retryInSec, 45);
+    assert.equal(layerFeedState(stats), 'degraded');
+    assert.equal(stats.status, undefined);
+    assert.equal(stats.statusMessage, undefined);
+    assert.equal(
+      gridRequests,
+      2,
+      'a successful grid cannot mask failed observations',
+    );
+    // A later unavailable rectangle must not replace the deck error with a
+    // fabricated camera-height instruction or reset the chosen filter.
+    h.bounds(null);
+    await h.layer.update();
+    assert.equal(h.chip('taxa-whales').active, true);
+    assert.equal(h.chip('taxa-whales').state, 'error');
+    assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+    assert.equal(h.layer.getStats().status, undefined);
+  } finally {
+    await manager.destroyLayer(h.layer.id);
+  }
+});
+
+test('ordinary WHALES refresh failure keeps the same active chip and last good rows', async () => {
+  let fail = false;
+  const h = harness({
+    getSnapshot: async () => {
+      if (fail) throw new Error('iNaturalist HTTP 503');
+      return [sighting];
+    },
+  });
+  h.layer.setParams({ taxa: 'whales' });
+  await h.layer.update();
+  const rows = h.state.renderedRows;
+  const update = h.state.lastUpdate;
+  fail = true;
+  await h.advance(3000);
+  await h.layer.update();
+  assert.equal(h.chip('taxa-whales').active, true);
+  assert.equal(h.chip('taxa-whales').state, 'error');
+  assert.equal(h.state.renderedRows, rows);
+  assert.equal(h.state.lastUpdate, update);
+  assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+  assert.equal(h.layer.getStats().retryInSec, 30);
+  h.layer.setParams(h.chip('taxa-whales').params);
+  assert.equal(h.chip('taxa-whales').state, 'loading');
+  assert.equal([...h.timers.values()][0].delay, 30_000);
+});
+
+test('grid acquisition runs in close views and its failure keeps cells while accepting observations', async () => {
+  let fail = false;
+  let observationRequests = 0;
+  let gridRequests = 0;
+  const cells = [{ id: 'synthetic-grid-cell', lat: 11, lon: 11, cellCount: 9 }];
+  const h = harness({
+    getSnapshotDetail: async () => ({
+      rows: [{ ...sighting, stableId: `inat:${++observationRequests}` }],
+      totalResults: 1,
+      fetchedAt: NOW,
+    }),
+    getGridSnapshot: async () => {
+      gridRequests++;
+      if (fail)
+        throw Object.assign(new Error('iNaturalist HTTP 502'), {
+          status: 502,
+          retryAfterSec: 60,
+        });
+      return { cells, totalResults: 9, fetchedAt: NOW };
+    },
+  });
+  h.bounds({ south: 10.5, west: 10.5, north: 11.5, east: 11.5 });
+  await h.layer.update();
+  assert.equal(gridRequests, 1);
+  assert.equal(h.layer.getStats().countLabel, '9 sightings in view');
+  fail = true;
+  await h.advance(3000);
+  assert.equal(await h.layer.update(), true);
+  assert.equal(observationRequests, 2);
+  assert.equal(gridRequests, 2);
+  assert.equal(h.state.gridCells, cells);
+  assert.equal(h.state.gridAvailable, true);
+  assert.deepEqual([...h.state.rows.keys()], ['inat:2']);
+  assert.equal(h.layer.getStats().countLabel, '9 sightings in view');
+  assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+  assert.equal(h.layer.getStats().retryInSec, 60);
+});
+
+test('a new sample preserves rows behind incumbent ambient cards until eligibility or parameters change', async () => {
+  const oldCard = { ...sighting, photo: { square: 'synthetic-open-photo' } };
+  let rows = [oldCard];
+  const h = harness({ getSnapshot: async () => rows });
+  let retained = [oldCard];
+  h.parts.selection.retainedAmbientRows = () => retained;
+  await h.layer.update();
+  rows = [{ ...sighting, stableId: 'inat:202' }];
+  await h.advance(3000);
+  await h.layer.update();
+  assert.equal(h.state.rows.get(oldCard.stableId), oldCard);
+  assert.equal(h.state.rowById.get(oldCard.stableId), oldCard);
+  retained = [];
+  await h.advance(3000);
+  await h.layer.update();
+  assert.equal(h.state.rows.has(oldCard.stableId), false);
+  assert.equal(h.state.selectedId, null);
+  retained = [oldCard];
+  h.layer.setParams({ taxa: 'whales' });
+  await h.advance(3000);
+  await h.layer.update();
+  assert.equal(h.state.rows.has(oldCard.stableId), false);
+});
+
+test('a selected observation survives omitted samples, zoom, changed filters and the observation window', async () => {
+  let rows = [sighting];
+  const h = harness({ getSnapshot: async () => rows });
+  await h.layer.update();
+  h.state.selectedId = sighting.stableId;
+  h.state.selectedRow = sighting;
+  rows = [{ ...sighting, stableId: 'inat:202' }];
+  await h.layer.update();
+  assert.equal(h.state.rows.get(sighting.stableId), sighting);
+  assert.equal(h.state.selectedId, sighting.stableId);
+  h.state.viewer.camera.positionCartographic.height = 3_500_000;
+  h.bounds({ south: 40, west: 40, north: 42, east: 42 });
+  await h.layer.update();
+  assert.equal(h.state.query.scope, 'global');
+  assert.equal(h.state.rowById.get(sighting.stableId), sighting);
+  h.layer.setParams({ taxa: 'Aves', confirmed: true });
+  await h.advance(49 * 3_600_000);
+  await h.layer.update();
+  assert.equal(h.state.rows.get(sighting.stableId), sighting);
+  assert.equal(h.state.selectedRow, sighting);
+  assert.equal(h.state.selectedId, sighting.stableId);
+  const refreshed = { ...sighting, commonName: 'Updated synthetic whale' };
+  rows = [refreshed];
+  await h.layer.update();
+  assert.equal(h.state.selectedRow, refreshed);
+  h.parts.selection.clear();
+  rows = [];
+  await h.layer.update();
+  assert.equal(h.state.rows.has(sighting.stableId), false);
+  assert.equal(h.state.selectedRow, null);
+});
+
+test('the bounded observation LRU evicts other rows before a pinned sighting', async () => {
+  let rows = [sighting];
+  const h = harness({ getSnapshot: async () => rows });
+  await h.layer.update();
+  h.state.selectedId = sighting.stableId;
+  h.state.selectedRow = sighting;
+  rows = Array.from({ length: 2100 }, (_, index) => ({
+    ...sighting,
+    stableId: `inat:${index + 1000}`,
+  }));
+  await h.layer.update();
+  assert.equal(h.state.rows.size, 2000);
+  assert.equal(h.state.rows.get(sighting.stableId), sighting);
+  assert.equal(h.state.selectedId, sighting.stableId);
+});
+
+test('retention never revives an incumbent card after the observation window expires', async () => {
+  const expired = { ...sighting, observedAt: NOW - 49 * 3_600_000 };
+  const h = harness({ getSnapshot: async () => [] });
+  h.parts.selection.retainedAmbientRows = () => [expired];
+  await h.layer.update();
+  await h.advance(3000);
+  await h.layer.update();
+  assert.equal(h.state.rows.has(expired.stableId), false);
+});
+
+test('all heights and the sampled fallback use the same sightings-in-view count label', () => {
+  const h = harness();
+  h.state.renderedRows = [sighting];
+  assert.equal(h.layer.getStats().countLabel, '1 sightings in view');
+  h.state.sightingCount = 2000;
+  assert.equal(h.layer.getStats().count, 2000);
+  assert.equal(
+    h.layer.getStats().countLabel,
+    '2,000 sightings in view',
+    'sample totals survive reduction of many sightings into one screen bucket',
+  );
+  h.state.gridAvailable = true;
+  h.state.gridTotal = 1000;
+  h.state.sightingCount = 870;
+  for (const height of [30_000, 1_500_000]) {
+    h.state.viewer.camera.positionCartographic.height = height;
+    assert.equal(h.layer.getStats().count, 870);
+    assert.equal(h.layer.getStats().countLabel, '870 sightings in view');
+  }
+});
+
+test('a stale fallback with a failed-refresh deadline remains DEGRADED, retryable and dated to the cached data', async () => {
+  const h = harness({
+    getSnapshotDetail: async () => ({
+      rows: [sighting],
+      totalResults: 1,
+      stale: true,
+      retryAfterSec: 90,
+      fetchedAt: NOW - 300_000,
+    }),
+  });
+  h.layer.setParams({ taxa: 'whales' });
+  await h.layer.update();
+  assert.equal(h.state.lastUpdate, NOW - 300_000);
+  assert.equal(h.layer.getStats().retryInSec, 90);
+  assert.equal(
+    h.layer.getStats().error,
+    'Wildlife sightings source unavailable',
+  );
+  assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+  assert.equal(h.chip('taxa-whales').active, true);
+  assert.equal(h.chip('taxa-whales').state, 'error');
+  assert.match(h.chip('taxa-whales').title, /click to retry/);
+});
+
+test('first enable settles one camera burst before dispatch and does not restart its first fetch set', async () => {
+  let observations = 0;
+  let tiles = 0;
+  let requestSignal;
+  const h = harness({
+    getSnapshotDetail: async ({ signal }) => {
+      observations++;
+      requestSignal = signal;
+      return { rows: [sighting], totalResults: 1, fetchedAt: NOW };
+    },
+    getGridSnapshot: async () => {
+      tiles++;
+      return { cells: [], totalResults: 0, fetchedAt: NOW };
+    },
+  });
+  h.state.enabled = false;
+  h.layer.enable();
+  const pending = h.layer.update();
+  assert.equal(observations, 0);
+  await h.advance(100);
+  h.moveEnd();
+  assert.equal(h.timers.size, 1);
+  await h.advance(299);
+  assert.equal(observations, 0);
+  await h.advance(1);
+  await pending;
+  assert.equal(observations, 1);
+  assert.equal(tiles, 1);
+  assert.equal(h.state.renderedRows[0].stableId, sighting.stableId);
+  h.moveEnd();
+  await h.advance(600);
+  assert.equal(observations, 1);
+  assert.equal(tiles, 1);
+  assert.equal(requestSignal.aborted, false);
+  assert.equal(h.timers.size, 0);
+});
+
+test('observations and each tile publish progressively without waiting for remaining tiles', async () => {
+  let emit;
+  let complete;
+  let tileOptions;
+  const h = harness({
+    getSnapshotDetail: async () => ({
+      rows: [sighting],
+      totalResults: 1,
+      fetchedAt: NOW,
+    }),
+    getGridSnapshot: (options) => {
+      tileOptions = options;
+      emit = options.onTile;
+      return new Promise((resolve) => {
+        complete = resolve;
+      });
+    },
+  });
+  assert.equal(
+    await h.layer.update(),
+    true,
+    'the manager receives observations without waiting for tiles',
+  );
+  assert.equal(h.state.renderedRows.length, 1);
+  assert.equal(h.state.gridAvailable, false);
+  const first = { id: 'grid:first', lat: 11, lon: 11, cellCount: 4 };
+  emit(
+    { cells: [first], totalResults: 4, fetchedAt: NOW },
+    { tile: tileOptions.tiles[0] },
+  );
+  assert.deepEqual(h.state.gridCells, [first]);
+  const second = { id: 'grid:second', lat: 11.5, lon: 11.5, cellCount: 3 };
+  complete({ cells: [first, second], totalResults: 7, fetchedAt: NOW });
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(h.state.gridCells, [first, second]);
+  assert.equal(h.state.loading, false);
+});
+
+test('Europe density tiles publish before a slow observation page and survive its failure', async () => {
+  let rejectObservation;
+  let completeGrid;
+  let tileOptions;
+  const h = harness({
+    getSnapshotDetail: () =>
+      new Promise((_resolve, reject) => {
+        rejectObservation = reject;
+      }),
+    getGridSnapshot: (options) => {
+      tileOptions = options;
+      return new Promise((resolve) => {
+        completeGrid = resolve;
+      });
+    },
+  });
+  h.bounds({ south: 44, west: -8, north: 55, east: 24 });
+  h.state.viewer.scene = { canvas: { clientWidth: 1280, clientHeight: 800 } };
+  h.state.viewer.camera.positionCartographic.height = 1_500_000;
+  const updating = h.layer.update();
+  assert.equal(tileOptions.tiles.length, 3);
+  const first = { id: 'grid:first', lat: 48, lon: 8, cellCount: 4 };
+  tileOptions.onTile(
+    { cells: [first], totalResults: 4, fetchedAt: NOW },
+    { tile: tileOptions.tiles[0] },
+  );
+  assert.deepEqual(h.state.gridCells, [first]);
+  assert.equal(h.state.gridAvailable, true);
+  assert.equal(h.layer.getStats().count, 4);
+  assert.equal(h.state.rows.size, 0);
+  assert.equal(h.state.drawnParams, null);
+  await h.advance(20_000);
+  assert.deepEqual(
+    h.state.gridCells,
+    [first],
+    'a stalled observation request does not withhold accepted density',
+  );
+  rejectObservation(new Error('iNaturalist HTTP 503'));
+  assert.equal(await updating, true);
+  assert.equal(tileOptions.signal.aborted, false);
+  assert.equal(h.state.error, 'iNaturalist HTTP 503');
+  const second = { id: 'grid:second', lat: 49, lon: 10, cellCount: 7 };
+  tileOptions.onTile(
+    { cells: [second], totalResults: 7, fetchedAt: NOW },
+    { tile: tileOptions.tiles[1] },
+  );
+  assert.deepEqual(h.state.gridCells, [first, second]);
+  completeGrid({ cells: [first, second], totalResults: 11, fetchedAt: NOW });
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(h.state.loading, false);
+  assert.equal(h.state.error, 'iNaturalist HTTP 503');
+  assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+});
+
+test('a completed density response needs no per-tile callback or observation page to publish', async () => {
+  let completeObservations;
+  const cells = [{ id: 'grid:first', lat: 11, lon: 11, cellCount: 2 }];
+  const h = harness({
+    getSnapshotDetail: () =>
+      new Promise((resolve) => {
+        completeObservations = resolve;
+      }),
+    getGridSnapshot: async () => ({ cells, totalResults: 2, fetchedAt: NOW }),
+  });
+  const updating = h.layer.update();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(h.state.gridCells, cells);
+  completeObservations({ rows: [sighting], totalResults: 1, fetchedAt: NOW });
+  await updating;
+  assert.equal(h.state.rows.get(sighting.stableId), sighting);
+  assert.equal(h.state.gridCells, cells);
+});
+
+test('density arriving first cannot replace a previous filter transaction before observations validate', async () => {
+  let rejectObservations;
+  let first = true;
+  const oldCells = [{ id: 'grid:old', lat: 11, lon: 11, cellCount: 2 }];
+  const h = harness({
+    getSnapshotDetail: () =>
+      first
+        ? Promise.resolve({ rows: [sighting], totalResults: 1, fetchedAt: NOW })
+        : new Promise((_resolve, reject) => {
+            rejectObservations = reject;
+          }),
+    getGridSnapshot: async () => ({
+      cells: first
+        ? oldCells
+        : [{ id: 'grid:new', lat: 11, lon: 11, cellCount: 6 }],
+      totalResults: first ? 2 : 6,
+      fetchedAt: NOW,
+    }),
+  });
+  await h.layer.update();
+  first = false;
+  h.layer.setParams({ taxa: 'Aves' });
+  const updating = h.layer.update();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(h.state.gridCells, oldCells);
+  rejectObservations(new Error('iNaturalist HTTP 503'));
+  await updating;
+  assert.equal(h.state.gridCells, oldCells);
+  assert.equal(h.state.rows.get(sighting.stableId), sighting);
+  assert.equal(h.chip('taxa-birds').state, 'error');
+});
+
+test('an empty tile retires its old zoom cells while uncovered density survives a failed sibling', async () => {
+  let first = true;
+  let oldZoom;
+  let oldCells;
+  let tileOptions;
+  let rejectObservations;
+  let completeGrid;
+  const h = harness({
+    getSnapshotDetail: () =>
+      first
+        ? Promise.resolve({ rows: [], totalResults: 0, fetchedAt: NOW })
+        : new Promise((_resolve, reject) => {
+            rejectObservations = reject;
+          }),
+    getGridSnapshot: (options) => {
+      if (first) {
+        oldZoom = options.tiles[0].z;
+        oldCells = [-4, 4].map((lon) => ({
+          id: wildlifeGridCellId(48, lon, oldZoom),
+          lat: 48,
+          lon,
+          cellCount: 2,
+        }));
+        return Promise.resolve({
+          cells: oldCells,
+          totalResults: 4,
+          fetchedAt: NOW,
+        });
+      }
+      tileOptions = options;
+      return new Promise((resolve) => {
+        completeGrid = resolve;
+      });
+    },
+  });
+  h.bounds({ south: 44, west: -8, north: 55, east: 24 });
+  h.state.viewer.scene = { canvas: { clientWidth: 160, clientHeight: 100 } };
+  h.state.viewer.camera.positionCartographic.height = 1_500_000;
+  await h.layer.update();
+  first = false;
+  h.state.viewer.scene.canvas.clientWidth = 1280;
+  h.state.viewer.scene.canvas.clientHeight = 800;
+  const updating = h.layer.update();
+  const zoom = tileOptions.tiles[0].z;
+  assert.ok(zoom > oldZoom);
+  const emptyTile = tileOptions.tiles.find((tile) =>
+    wildlifeGridCellId(48, -4, zoom).startsWith(
+      `grid:${tile.z}/${tile.x}/${tile.y}:`,
+    ),
+  );
+  assert.ok(emptyTile);
+  tileOptions.onTile(
+    { cells: [], totalResults: 0, fetchedAt: NOW },
+    { tile: emptyTile },
+  );
+  assert.deepEqual(h.state.gridCells, [oldCells[1]]);
+  rejectObservations(new Error('iNaturalist HTTP 503'));
+  await updating;
+  completeGrid({
+    cells: [],
+    totalResults: 0,
+    fetchedAt: NOW,
+    error: new Error('iNaturalist HTTP 502'),
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(h.state.gridCells, [oldCells[1]]);
+  assert.equal(h.state.gridTotal, 2);
+});
+
+test('only marked upstream failures create cooldown; local pacing, network and schema errors can retry on the next view', async () => {
+  for (const error of [
+    Object.assign(new Error('iNaturalist HTTP 503'), {
+      status: 503,
+      upstreamStatus: 0,
+      retryAfterSec: 30,
+    }),
+    new TypeError('Failed to fetch'),
+    new Error('Malformed iNaturalist response'),
+  ]) {
+    let calls = 0;
+    const h = harness({
+      getSnapshot: async () => {
+        if (++calls === 1) throw error;
+        return [sighting];
+      },
+    });
+    await h.layer.update();
+    assert.equal(h.state.retryAt, 0, error.message);
+    assert.equal(h.layer.getStats().retryInSec, undefined);
+    assert.doesNotMatch(h.state.error, /rate limited/i);
+    await h.layer.update();
+    assert.equal(calls, 2);
+    assert.equal(h.state.renderedRows.length, 1);
+  }
+  const h = harness({
+    getSnapshot: async () => {
+      throw Object.assign(new Error('iNaturalist rate limited'), {
+        status: 429,
+        upstreamStatus: 429,
+        retryAfterSec: 2,
+      });
+    },
+  });
+  await h.layer.update();
+  assert.equal(
+    h.layer.getStats().retryInSec,
+    2,
+    'actual Retry-After is honored without imposing a 30s local floor',
+  );
+});
+
+test('stale cached tiles with local pacing metadata keep their display and do not enter cooldown', async () => {
+  const h = harness({
+    getSnapshotDetail: async () => ({
+      rows: [sighting],
+      totalResults: 1,
+      fetchedAt: NOW,
+      stale: true,
+      retryAfterSec: 30,
+      upstreamStatus: 0,
+    }),
+  });
+  await h.layer.update();
+  assert.equal(h.state.renderedRows.length, 1);
+  assert.equal(h.state.stale, true);
+  assert.equal(h.state.error, null);
+  assert.equal(h.state.retryAt, 0);
+});
+
+test('an explicit upstream Retry-After zero retries immediately while a missing header keeps the default backoff', async () => {
+  for (const status of [429, 503]) {
+    for (const explicitZero of [true, false]) {
+      let attempts = 0;
+      const source = createWildlifeSightingsSource({
+        now: () => NOW,
+        fetchImpl: async (url) => {
+          if (url.startsWith('/api/inaturalist/grid?'))
+            return Response.json({
+              cells: [],
+              totalResults: 0,
+              fetchedAt: NOW,
+            });
+          if (++attempts > 1)
+            return Response.json({ rows: [], totalResults: 0, fetchedAt: NOW });
+          return new Response('', {
+            status,
+            headers: {
+              'X-Upstream-Status': String(status),
+              ...(explicitZero ? { 'Retry-After': '0' } : {}),
+            },
+          });
+        },
+      });
+      const h = harness(source);
+      await h.layer.update();
+      if (explicitZero) {
+        assert.equal(
+          h.state.retryAt,
+          NOW,
+          `${status}: zero remains an immediate deadline`,
+        );
+        assert.equal(h.layer.getStats().retryInSec, undefined);
+        await h.layer.update();
+        assert.equal(attempts, 2);
+        assert.equal(h.state.error, null);
+      } else {
+        assert.equal(
+          h.state.retryAt,
+          NOW + 30_000,
+          `${status}: no header uses the default backoff`,
+        );
+        assert.equal(h.layer.getStats().retryInSec, 30);
+        await h.layer.update();
+        assert.equal(attempts, 1);
+      }
+    }
+  }
+});
diff --git a/src/layers/wildlifeSightings/billboardModel.js b/src/layers/wildlifeSightings/billboardModel.js
new file mode 100644
index 000000000..6b5b1093a
--- /dev/null
+++ b/src/layers/wildlifeSightings/billboardModel.js
@@ -0,0 +1,114 @@
+import { drainWildlifeWork, WILDLIFE_WORK_UNIT } from './performance.js';
+import { wildlifeIconicGroup } from './model.js';
+
+/** Incremental billboard reconciliation, independent of Cesium and the DOM.
+ * A refresh changes only added/removed contacts and properties that differ.
+ * Position sampling and appearance construction run only for changed rows. */
+export function createWildlifeBillboardModel({
+  collection,
+  pointById,
+  positions,
+  positionForRow,
+  appearanceForGroup,
+}) {
+  const previous = new Map();
+
+  function update(rows, options = {}) {
+    return drainWildlifeWork(updateWork(rows, options));
+  }
+
+  function* updateWork(rows, { onOperations = null } = {}) {
+    const nextIds = new Set();
+    const result = { created: 0, removed: 0, updated: 0, writes: 0 };
+    let visits = 0;
+    for (const row of rows) {
+      if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'billboard-update';
+      const id = row.stableId;
+      if (nextIds.has(id)) continue;
+      nextIds.add(id);
+      const group = wildlifeIconicGroup(row.iconic);
+      const old = previous.get(id);
+      const point = pointById.get(id);
+      if (
+        old &&
+        point &&
+        old.lat === row.lat &&
+        old.lon === row.lon &&
+        old.group === group
+      )
+        continue;
+      const appearance =
+        old && old.group === group ? old.appearance : appearanceForGroup(group);
+      const positionChanged =
+        !old || old.lat !== row.lat || old.lon !== row.lon;
+      const position = positionChanged
+        ? positionForRow(row)
+        : positions.get(id);
+      if (!point) {
+        const options = { id: `wildlife:${id}`, position, ...appearance };
+        pointById.set(id, collection.add(options));
+        positions.set(id, position);
+        result.created += 1;
+        result.writes += Object.keys(options).length;
+      } else {
+        let writes = 0;
+        if (positionChanged) {
+          point.position = position;
+          positions.set(id, position);
+          writes += 1;
+        }
+        for (const key of Object.keys(appearance)) {
+          // Cesium clones Color and NearFarScalar values on assignment. Our
+          // last descriptor, rather than getter reference identity, records
+          // whether the appearance has actually changed.
+          if (old?.appearance?.[key] === appearance[key]) continue;
+          point[key] = appearance[key];
+          writes += 1;
+        }
+        result.writes += writes;
+        if (writes) result.updated += 1;
+      }
+      previous.set(id, {
+        lat: row.lat,
+        lon: row.lon,
+        group,
+        appearance,
+      });
+    }
+    for (const [id, point] of pointById) {
+      if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'billboard-update';
+      if (nextIds.has(id)) continue;
+      collection.remove(point);
+      pointById.delete(id);
+      positions.delete(id);
+      previous.delete(id);
+      result.removed += 1;
+    }
+    onOperations?.({ billboardVisits: visits, billboardWrites: result.writes });
+    return result;
+  }
+
+  function clear() {
+    collection.removeAll();
+    pointById.clear();
+    positions.clear();
+    previous.clear();
+  }
+
+  // Font readiness replaces just the cached texture. Never resample anchors,
+  // clear the collection or allocate replacement billboards for this swap.
+  function refreshImages(imageForGroup) {
+    let writes = 0;
+    for (const [id, old] of previous) {
+      const point = pointById.get(id);
+      const image = imageForGroup(old.group);
+      if (!point || old.appearance.image === image) continue;
+      point.image = image;
+      old.appearance = { ...old.appearance, image };
+      writes += 1;
+    }
+    return writes;
+  }
+
+  return { update, updateWork, clear, refreshImages };
+}
diff --git a/src/layers/wildlifeSightings/bounds.js b/src/layers/wildlifeSightings/bounds.js
new file mode 100644
index 000000000..64293c3a2
--- /dev/null
+++ b/src/layers/wildlifeSightings/bounds.js
@@ -0,0 +1,51 @@
+// Shared by browser viewport queries and the provider's cache-key validation.
+export const WILDLIFE_MAX_VIEW_DEGREES = 40;
+
+const cleanDegree = (value) => Math.round(value * 1e8) / 1e8;
+const spanOf = (box) => Math.max(box.north - box.south, box.east - box.west);
+
+/** Snap non-crossing boxes outward to one canonical grid. Validate the final
+ * span too: a legal raw box may expand past the supported query size. */
+export function snapWildlifeBox(box) {
+  if (
+    !box ||
+    !['south', 'west', 'north', 'east'].every((key) =>
+      Number.isFinite(box[key]),
+    ) ||
+    box.south < -90 ||
+    box.north > 90 ||
+    box.west < -180 ||
+    box.east > 180 ||
+    box.north <= box.south ||
+    box.east <= box.west ||
+    spanOf(box) > WILDLIFE_MAX_VIEW_DEGREES + 1e-8
+  )
+    return null;
+  let grid = spanOf(box) > 5 ? 1 : 0.1;
+  const snap = () => ({
+    south: Math.max(
+      -90,
+      cleanDegree(Math.floor((box.south + 1e-10) / grid) * grid),
+    ),
+    west: Math.max(
+      -180,
+      cleanDegree(Math.floor((box.west + 1e-10) / grid) * grid),
+    ),
+    north: Math.min(
+      90,
+      cleanDegree(Math.ceil((box.north - 1e-10) / grid) * grid),
+    ),
+    east: Math.min(
+      180,
+      cleanDegree(Math.ceil((box.east - 1e-10) / grid) * grid),
+    ),
+  });
+  let snapped = snap();
+  // Crossing the five-degree boundary while snapping must pick the same grid
+  // on the browser and proxy, and on every subsequent snap of this box.
+  if (grid === 0.1 && spanOf(snapped) > 5 + 1e-8) {
+    grid = 1;
+    snapped = snap();
+  }
+  return spanOf(snapped) <= WILDLIFE_MAX_VIEW_DEGREES ? snapped : null;
+}
diff --git a/src/layers/wildlifeSightings/cache.integration.test.mjs b/src/layers/wildlifeSightings/cache.integration.test.mjs
new file mode 100644
index 000000000..69b7b6e4f
--- /dev/null
+++ b/src/layers/wildlifeSightings/cache.integration.test.mjs
@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { inaturalistProxy } from '../../../server/providers/inaturalist/observations.js';
+import { syntheticGrid } from '../../../server/providers/inaturalist/grid.fixture.mjs';
+import {
+  createWildlifeSightingsSource,
+  WILDLIFE_GRID_TTL_MS,
+} from './source.js';
+
+// Exercise both real cache owners through their projected response contract.
+// Only the HTTP transport and upstream data are synthetic; no socket is needed.
+test('client and proxy share stale revalidation and publish its fresh result in the same view', async () => {
+  let now = Date.parse('2026-11-04T18:05:00Z');
+  let upstreamCalls = 0;
+  let proxyCalls = 0;
+  let finishRefresh;
+  let handler;
+  inaturalistProxy({
+    now: () => now,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0, windowMs: 0 },
+    warn() {},
+    fetchImpl() {
+      upstreamCalls++;
+      return upstreamCalls === 1
+        ? Response.json(syntheticGrid())
+        : new Promise((resolve) => {
+            finishRefresh = resolve;
+          });
+    },
+  }).configureServer({
+    middlewares: {
+      use(_mount, middleware) {
+        handler = middleware;
+      },
+    },
+  });
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    async fetchImpl(url) {
+      proxyCalls++;
+      let status;
+      let headers;
+      let response;
+      await handler(
+        {
+          method: 'GET',
+          url: url.slice('/api/inaturalist'.length),
+          headers: {},
+          socket: { remoteAddress: 'synthetic' },
+        },
+        {
+          writeHead(code, values) {
+            status = code;
+            headers = values;
+          },
+          end(body) {
+            response = new Response(body, { status, headers });
+          },
+        },
+      );
+      return response;
+    },
+  });
+  const options = { tiles: [{ z: 2, x: 1, y: 1 }], taxa: 'Aves' };
+  const first = await source.getGridSnapshot(options);
+  assert.equal(first.cells.length, 2);
+  await source.getGridSnapshot(options);
+  assert.equal(upstreamCalls, 1);
+  assert.equal(proxyCalls, 1, 'client hits do not even call the proxy');
+  now += WILDLIFE_GRID_TTL_MS;
+  const publications = [];
+  let settled = false;
+  const refreshing = source
+    .getGridSnapshot({
+      ...options,
+      onTile: (value) => publications.push(value),
+    })
+    .then((value) => {
+      settled = true;
+      return value;
+    });
+  try {
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(settled, false, 'revalidation is still waiting for upstream');
+    assert.equal(
+      publications[0]?.stale,
+      true,
+      'old cells already reached the renderer',
+    );
+    assert.deepEqual(publications[0].cells, first.cells);
+    assert.equal(
+      upstreamCalls,
+      2,
+      'normal stale GET and refresh=wait share one upstream attempt',
+    );
+    finishRefresh(Response.json(syntheticGrid()));
+    const fresh = await refreshing;
+    assert.equal(fresh.stale, false);
+    assert.equal(fresh.fetchedAt, now);
+    assert.equal(publications.at(-1).fetchedAt, now);
+    assert.notEqual(publications.at(-1).stale, true);
+    const before = proxyCalls;
+    await source.getGridSnapshot(options);
+    assert.equal(proxyCalls, before);
+    assert.equal(upstreamCalls, 2);
+  } finally {
+    finishRefresh?.(Response.json(syntheticGrid()));
+    await refreshing;
+  }
+});
diff --git a/src/layers/wildlifeSightings/cards.js b/src/layers/wildlifeSightings/cards.js
new file mode 100644
index 000000000..61dbbc01b
--- /dev/null
+++ b/src/layers/wildlifeSightings/cards.js
@@ -0,0 +1,281 @@
+import { photoCreator } from './photoText.js';
+import { getLocale, t, translateKnown } from '../../i18n/index.js';
+import { CCTV_THUMBNAIL_STYLE } from '../../overlays/worldOverlayTokens.js';
+import { truncateOverlayTitle } from '../../overlays/worldOverlayDraw.js';
+import { isOpenPhoto } from './records.js';
+import { compareWildlifeIds, wildlifeIconicGroup } from './model.js';
+import {
+  ICONIC_TINTS,
+  WILDLIFE_CARD_LIMIT,
+  WILDLIFE_CARD_MIN_SEP_PX,
+  WILDLIFE_CARD_REGION_COLUMNS,
+  WILDLIFE_CARD_REGION_ROWS,
+  WILDLIFE_CARD_ALTITUDE_SCALE,
+  WILDLIFE_CARD_FADE_LOW_METERS,
+  WILDLIFE_CARD_FADE_HIGH_METERS,
+  WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS,
+  WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS,
+  WILDLIFE_SELECTED_LABEL_MAX_CHARS,
+  WILDLIFE_CARD_MAX_DISTANCE_METERS,
+  WILDLIFE_LABEL_LIMIT,
+} from './policy.js';
+
+export const WILDLIFE_OVERLAY_SOURCE_ID = 'wildlife-sightings';
+export const WILDLIFE_LABEL_SOURCE_ID = 'wildlife-sightings-labels';
+export const WILDLIFE_SELECTED_SOURCE_ID = 'wildlife-sightings-selected';
+export const WILDLIFE_LABEL_SOURCE_OPTIONS = Object.freeze({
+  cohortLimit: WILDLIFE_LABEL_LIMIT,
+  collisionCapacity: WILDLIFE_LABEL_LIMIT,
+  moving: false,
+});
+export const WILDLIFE_OVERLAY_SOURCE_OPTIONS = Object.freeze({
+  cohortLimit: WILDLIFE_CARD_LIMIT,
+  collisionCapacity: WILDLIFE_CARD_LIMIT,
+  moving: false,
+});
+export const WILDLIFE_SELECTED_SOURCE_OPTIONS = Object.freeze({
+  cohortLimit: 1,
+  collisionCapacity: 1,
+  moving: false,
+});
+
+/** Match cards and labels to the sighting sprite's taxon tint. */
+export function wildlifeAccent(iconic) {
+  return ICONIC_TINTS[wildlifeIconicGroup(iconic)];
+}
+
+/** Importance score for open, non-sensitive iNaturalist photos. Other rows
+ * cannot consume a slot, even if an accidental photo field reaches a caller. */
+export function ambientScore(row, nowMs) {
+  if (row?.obscured || !isOpenPhoto(row?.photo) || !photoCreator(row.photo))
+    return -Infinity;
+  const nonnegative = (n) => (Number.isFinite(n) ? Math.max(0, n) : 0);
+  const time = Number.isFinite(row.observedAt)
+    ? row.observedAt
+    : Date.parse(row.observedOn);
+  const ageH =
+    Number.isFinite(time) && Number.isFinite(nowMs)
+      ? Math.max(0, (nowMs - time) / 3_600_000)
+      : Infinity;
+  return (
+    (row.quality === 'research' ? 2 : 0) +
+    (row.threatened ? 1 : 0) +
+    Math.log1p(nonnegative(row.favesCount)) +
+    0.5 * Math.log1p(nonnegative(row.identificationAgreements)) +
+    2 * 0.5 ** (ageH / 12)
+  );
+}
+
+/** Named rows without eligible photos rank below eligible photo rows. */
+export function wildlifeLabelScore(row, nowMs) {
+  const score = ambientScore(row, nowMs);
+  return Number.isFinite(score) ? score : -1;
+}
+
+/** Visible incumbents own their slots until they leave the view/window. A new
+ * random sample or a higher-scoring challenger can only fill a free slot. */
+function rankWildlifeAmbientRows(rows, currentIds, nowMs) {
+  const incumbent = new Map(currentIds.map((id, index) => [id, index]));
+  const scored = rows
+    .map((row) => ({
+      row,
+      score: ambientScore(row, nowMs),
+      current: incumbent.get(row.stableId),
+    }))
+    .filter((item) => Number.isFinite(item.score));
+  scored.sort((a, b) => {
+    if (a.current !== undefined || b.current !== undefined) {
+      if (a.current === undefined) return 1;
+      if (b.current === undefined) return -1;
+      return a.current - b.current;
+    }
+    return (
+      b.score - a.score || compareWildlifeIds(a.row.stableId, b.row.stableId)
+    );
+  });
+  return scored.map((item) => item.row);
+}
+
+/** Spread newly admitted cards over screen regions. Once shown, a card stays
+ * even when a pan moves it into another incumbent's region; region quotas only
+ * govern free slots, so a camera movement never replaces a visible photo. */
+export function selectWildlifeAmbientRows(
+  rows,
+  currentIds = [],
+  nowMs,
+  limit = WILDLIFE_CARD_LIMIT,
+  { screens = null, width = 0, height = 0 } = {},
+) {
+  const incumbent = new Set(currentIds);
+  const accepted = [];
+  const regions = new Set();
+  const regionFor = (screen) =>
+    `${Math.min(WILDLIFE_CARD_REGION_COLUMNS - 1, Math.floor((screen.x / width) * WILDLIFE_CARD_REGION_COLUMNS))}:${Math.min(WILDLIFE_CARD_REGION_ROWS - 1, Math.floor((screen.y / height) * WILDLIFE_CARD_REGION_ROWS))}`;
+  for (const row of rankWildlifeAmbientRows(rows, currentIds, nowMs)) {
+    if (accepted.length >= Math.max(0, limit)) break;
+    const screen = screens?.get(row.stableId);
+    const region = screen && width > 0 && height > 0 ? regionFor(screen) : null;
+    if (!incumbent.has(row.stableId)) {
+      if (region !== null && regions.has(region)) continue;
+      if (
+        screen &&
+        accepted.some((other) => {
+          const prior = screens.get(other.stableId);
+          return (
+            prior &&
+            Math.hypot(prior.x - screen.x, prior.y - screen.y) <
+              WILDLIFE_CARD_MIN_SEP_PX
+          );
+        })
+      )
+        continue;
+    }
+    accepted.push(row);
+    if (region !== null) regions.add(region);
+  }
+  return accepted;
+}
+
+function nameFor(row) {
+  return translateKnown(row.commonName || row.scientificName) || t('SIGHTING');
+}
+
+/** Return a trimmed common name, or null for unnamed observations. */
+export function wildlifeCommonName(row) {
+  const name = row.commonName;
+  return typeof name === 'string' && name.trim() ? name.trim() : null;
+}
+
+/** Full translated display name, shared by titles and screen-space deduping. */
+export function wildlifeDisplayName(row) {
+  const commonName = wildlifeCommonName(row);
+  const name = commonName ? translateKnown(commonName).trim() : '';
+  return name.replace(/\s+/g, ' ').trim().toLocaleUpperCase(getLocale());
+}
+
+function compactName(row) {
+  return truncateOverlayTitle(
+    wildlifeDisplayName(row),
+    WILDLIFE_SELECTED_LABEL_MAX_CHARS,
+  );
+}
+
+/** One-line common names for identified observations. The caller adds the
+ * Cartesian anchor after ranking and front-side/screen-space filtering. */
+export function buildWildlifeLabelEntry(
+  row,
+  { select, hasRow, nowMs = Date.now() } = {},
+) {
+  if (!wildlifeCommonName(row)) return null;
+  return {
+    id: `wildlife-sightings-label:${row.stableId}`,
+    variant: 'label',
+    title: compactName(row),
+    accent: wildlifeAccent(row.iconic),
+    priority: wildlifeLabelScore(row, nowMs),
+    collisionGroup: 'ambient-label',
+    // The host checks actual card placements, including sticky/fading cards,
+    // before spending the remaining space on labels in score order.
+    yieldToCollisionGroup: 'ambient-card',
+    stateless: true,
+    paintLane: 'ambient-label',
+    gapPx: 15,
+    verticalOnly: true,
+    placement: 'above',
+    horizonCull: true,
+    edgeFade: 'keyhole',
+    interactive: false,
+    accessibilityLabel: nameFor(row),
+    ...selectionAction(row, { select, hasRow }),
+  };
+}
+
+function selectionAction(row, { select, hasRow } = {}) {
+  if (typeof select !== 'function') return {};
+  return {
+    interactive: true,
+    accessibilityLabel: t('Show {name} sighting', { name: nameFor(row) }),
+    activate() {
+      if (typeof hasRow === 'function' && !hasRow(row.stableId)) return false;
+      return select(row.stableId) !== false;
+    },
+  };
+}
+
+/** Build an attributed ambient photo; the runtime supplies the decoded image. */
+export function buildWildlifeThumbnailEntry(
+  row,
+  nowMs,
+  { image = null, select, hasRow, selected = false } = {},
+) {
+  const score = ambientScore(row, nowMs);
+  if (!Number.isFinite(score)) return null;
+  return {
+    id: `sighting:${row.stableId}`,
+    variant: 'thumbnail',
+    title: nameFor(row),
+    image,
+    requireImage: true,
+    accent: wildlifeAccent(row.iconic),
+    interactive: false,
+    accessibilityLabel: t('Show {name} sighting', { name: nameFor(row) }),
+    collisionGroup: 'ambient-card',
+    horizonCull: true,
+    edgeFade: 'keyhole',
+    verticalOnly: true,
+    gapPx: 15,
+    thumbnailPadX: CCTV_THUMBNAIL_STYLE.padding,
+    thumbnailPadTop: CCTV_THUMBNAIL_STYLE.padding,
+    thumbnailPadBottom: CCTV_THUMBNAIL_STYLE.padding,
+    thumbnailTitleGap: 2,
+    thumbnailTitleHeight: CCTV_THUMBNAIL_STYLE.titleHeight,
+    thumbnailTitleChars: CCTV_THUMBNAIL_STYLE.titleChars,
+    thumbnailTitleWordBoundary: true,
+    thumbnailBackground: CCTV_THUMBNAIL_STYLE.background,
+    thumbnailTitleColor: CCTV_THUMBNAIL_STYLE.titleColor,
+    thumbnailTitleFont: CCTV_THUMBNAIL_STYLE.titleFont,
+    thumbnailLeaderColor: CCTV_THUMBNAIL_STYLE.leader,
+    thumbnailRuleColor: CCTV_THUMBNAIL_STYLE.rule,
+    thumbnailRuleHeight: CCTV_THUMBNAIL_STYLE.ruleHeight,
+    thumbnailRadius: CCTV_THUMBNAIL_STYLE.radius,
+    ...selectionAction(row, { select, hasRow }),
+    // i18n-ignore: the creator is verbatim feed attribution with a copyright mark
+    details: [`© ${photoCreator(row.photo)}`],
+    thumbnailFixedWidth: true,
+    thumbnailFit: 'contain',
+    thumbnailWidth: 96,
+    thumbnailHeight: 72,
+    priority: selected ? Number.MAX_SAFE_INTEGER : score,
+    minAnchorSeparationPx: WILDLIFE_CARD_MIN_SEP_PX,
+    maxDistance: WILDLIFE_CARD_MAX_DISTANCE_METERS,
+    altitudeScale: WILDLIFE_CARD_ALTITUDE_SCALE,
+    altitudeFadeStart: WILDLIFE_CARD_FADE_LOW_METERS,
+    altitudeFadeEnd: WILDLIFE_CARD_FADE_HIGH_METERS,
+    ...(selected ? { selected: true, paintLane: 'selected' } : {}),
+  };
+}
+
+/** A bounded selected name uses the host's shared selected card treatment. */
+export function buildWildlifeSelectedLabel(row) {
+  if (!wildlifeCommonName(row)) return null;
+  return {
+    id: `wildlife-sightings-label:${row.stableId}`,
+    variant: 'label',
+    selected: true,
+    protected: true,
+    yieldToCollisionGroup: 'ambient-card',
+    paintLane: 'selected',
+    priority: Number.MAX_SAFE_INTEGER,
+    title: compactName(row),
+    accent: wildlifeAccent(row.iconic),
+    gapPx: 15,
+    verticalOnly: true,
+    placement: 'above',
+    horizonCull: true,
+    edgeFade: 'keyhole',
+    interactive: false,
+    accessibilityLabel: nameFor(row),
+    altitudeFadeStart: WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS,
+    altitudeFadeEnd: WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS,
+  };
+}
diff --git a/src/layers/wildlifeSightings/cards.test.mjs b/src/layers/wildlifeSightings/cards.test.mjs
new file mode 100644
index 000000000..a6a27c977
--- /dev/null
+++ b/src/layers/wildlifeSightings/cards.test.mjs
@@ -0,0 +1,627 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  ambientScore,
+  selectWildlifeAmbientRows,
+  buildWildlifeThumbnailEntry,
+  buildWildlifeLabelEntry,
+  buildWildlifeSelectedLabel,
+  wildlifeAccent,
+  WILDLIFE_OVERLAY_SOURCE_OPTIONS,
+  WILDLIFE_LABEL_SOURCE_ID,
+  WILDLIFE_LABEL_SOURCE_OPTIONS,
+  WILDLIFE_SELECTED_SOURCE_OPTIONS,
+} from './cards.js';
+import { CCTV_THUMBNAIL_STYLE } from '../../overlays/worldOverlayTokens.js';
+import {
+  WILDLIFE_SELECTED_LABEL_MAX_CHARS,
+  WILDLIFE_CARD_SHOW_MAX_METERS,
+  WILDLIFE_CARD_HIDE_MAX_METERS,
+  WILDLIFE_LABEL_LIMIT,
+} from './policy.js';
+import { formatAge } from './photoText.js';
+import { createSelection } from './selection.js';
+import { setLocale } from '../../i18n/index.js';
+import {
+  altitudeFade,
+  altitudeScale,
+  measureOverlayEntry,
+} from '../../overlays/worldOverlayDraw.js';
+
+const now = Date.UTC(2026, 10, 4, 18, 40);
+const hour = 3_600_000;
+const photo = {
+  square:
+    'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpeg',
+  medium:
+    'https://inaturalist-open-data.s3.amazonaws.com/photos/123/medium.jpeg',
+  licence: 'cc-by-nc',
+  attribution: '(c) Synthetic Photographer, some rights reserved',
+};
+const row = (overrides = {}) => ({
+  stableId: 'inat:123',
+  origin: 'inaturalist',
+  lat: 47.6,
+  lon: -122.3,
+  observedAt: now - 2 * hour,
+  observedOn: '2026-11-04',
+  obscured: false,
+  cell: null,
+  quality: 'research',
+  accuracyM: 12,
+  commonName: "Anna's Hummingbird",
+  scientificName: 'Calypte anna',
+  iconic: 'Aves',
+  threatened: false,
+  conservation: null,
+  count: null,
+  provider: null,
+  obsLicence: 'cc-by-nc',
+  link: 'https://www.inaturalist.org/observations/123',
+  photo,
+  favesCount: 0,
+  identificationAgreements: 0,
+  ...overrides,
+});
+const acartia = (overrides = {}) =>
+  row({
+    stableId: 'acartia:abc',
+    origin: 'acartia',
+    iconic: 'Mammalia',
+    commonName: 'Orca',
+    scientificName: null,
+    accuracyM: null,
+    count: 5,
+    provider: { name: 'Synthetic Network', entity: 'Whale Alert' },
+    obsLicence: null,
+    photo: null,
+    link: 'https://acartia.io',
+    ...overrides,
+  });
+
+test('ambient photo score prioritizes grade, threat, appreciation and recency exactly', () => {
+  const base = row({ quality: 'needs_id' });
+  assert.ok(
+    Math.abs(ambientScore(row(), now) - ambientScore(base, now) - 2) < 1e-12,
+  );
+  assert.equal(
+    ambientScore(row({ threatened: true, observedAt: now }), now) -
+      ambientScore(row({ observedAt: now }), now),
+    1,
+  );
+  assert.ok(
+    ambientScore(row({ favesCount: 8 }), now) >
+      ambientScore(row({ favesCount: 1 }), now),
+  );
+  assert.ok(
+    Math.abs(
+      ambientScore(row({ identificationAgreements: 3 }), now) -
+        ambientScore(row(), now) -
+        0.5 * Math.log1p(3),
+    ) < 1e-12,
+  );
+  assert.ok(
+    ambientScore(row({ quality: 'needs_id', observedAt: now - hour }), now) >
+      ambientScore(
+        row({ quality: 'needs_id', observedAt: now - 48 * hour }),
+        now,
+      ),
+  );
+  for (const input of [
+    row({ obscured: true }),
+    row({ photo: null }),
+    row({ photo: { ...photo, licence: 'cc-by-nd' } }),
+  ])
+    assert.equal(ambientScore(input, now), -Infinity);
+});
+
+test('ambient ranking ties by stable id and never replaces a visible incumbent', () => {
+  const a = row({ stableId: 'inat:a' });
+  const b = row({ stableId: 'inat:b' });
+  assert.deepEqual(
+    selectWildlifeAmbientRows([b, a], [], now).map((item) => item.stableId),
+    ['inat:a', 'inat:b'],
+  );
+  const slightlyBetter = row({ stableId: 'inat:b', observedAt: now - hour });
+  assert.ok(ambientScore(slightlyBetter, now) - ambientScore(a, now) < 0.5);
+  assert.equal(
+    selectWildlifeAmbientRows([a, slightlyBetter], ['inat:a'], now, 1)[0]
+      .stableId,
+    'inat:a',
+  );
+  assert.equal(
+    selectWildlifeAmbientRows(
+      [a, row({ stableId: 'inat:b', threatened: true })],
+      ['inat:a'],
+      now,
+      1,
+    )[0].stableId,
+    'inat:a',
+  );
+  assert.equal(
+    selectWildlifeAmbientRows([a], ['gone'], now, 24)[0].stableId,
+    a.stableId,
+  );
+});
+
+test('ambient entries are stable, accessible and select in place until their row is gone', () => {
+  const selected = [];
+  let exists = true;
+  const entry = buildWildlifeThumbnailEntry(row(), now, {
+    select(id) {
+      selected.push(id);
+    },
+    hasRow: () => exists,
+  });
+  assert.equal(entry.id, 'sighting:inat:123');
+  assert.equal(entry.interactive, true);
+  assert.equal(entry.accessibilityLabel, "Show Anna's Hummingbird sighting");
+  assert.equal(entry.activate(), true);
+  assert.deepEqual(selected, ['inat:123']);
+  exists = false;
+  assert.equal(entry.activate(), false);
+  assert.equal(selected.length, 1);
+  assert.equal(buildWildlifeThumbnailEntry(row({ obscured: true }), now), null);
+});
+
+test('all wildlife name labels prefer a complete word before their ellipsis and retain the full accessible name', () => {
+  const commonName =
+    'Great Blue Heron With An Unusually Lengthy Synthetic Common Name';
+  for (const build of [buildWildlifeLabelEntry, buildWildlifeSelectedLabel]) {
+    const entry = build(row({ commonName }));
+    assert.equal(entry.title, 'GREAT BLUE HERON WITH AN UNUSUALLY…');
+    assert.ok(
+      Array.from(entry.title).length <= WILDLIFE_SELECTED_LABEL_MAX_CHARS,
+    );
+    assert.ok(entry.accessibilityLabel.includes(commonName));
+    const unbroken = build(row({ commonName: '𓅃'.repeat(60) }));
+    assert.equal(
+      Array.from(unbroken.title).length,
+      WILDLIFE_SELECTED_LABEL_MAX_CHARS,
+    );
+    assert.ok(unbroken.title.endsWith('…'));
+    assert.ok(!unbroken.title.includes('\ufffd'));
+  }
+});
+
+test('thumbnail entries use every shared thumbnail token and wildlife altitude curves', () => {
+  const entry = buildWildlifeThumbnailEntry(row(), now);
+  assert.deepEqual([entry.thumbnailWidth, entry.thumbnailHeight], [96, 72]);
+  for (const key of ['thumbnailPadX', 'thumbnailPadTop', 'thumbnailPadBottom'])
+    assert.equal(entry[key], CCTV_THUMBNAIL_STYLE.padding);
+  const mapping = {
+    thumbnailTitleHeight: 'titleHeight',
+    thumbnailTitleChars: 'titleChars',
+    thumbnailBackground: 'background',
+    thumbnailTitleColor: 'titleColor',
+    thumbnailTitleFont: 'titleFont',
+    thumbnailLeaderColor: 'leader',
+    thumbnailRuleColor: 'rule',
+    thumbnailRuleHeight: 'ruleHeight',
+    thumbnailRadius: 'radius',
+  };
+  for (const [field, token] of Object.entries(mapping))
+    assert.equal(entry[field], CCTV_THUMBNAIL_STYLE[token]);
+  assert.equal(entry.altitudeScale.fullEnd, 20_000);
+  assert.equal(entry.altitudeScale.midEnd, 120_000);
+  assert.equal(entry.altitudeFadeStart, 70_000);
+  assert.equal(entry.altitudeFadeEnd, 125_000);
+  assert.equal(entry.maxDistance, 600_000);
+  assert.equal(entry.minAnchorSeparationPx, 112);
+  assert.equal(entry.accent, wildlifeAccent('Aves'));
+  assert.equal(entry.horizonCull, true);
+  assert.equal(entry.requireImage, true);
+  assert.deepEqual(entry.details, ['© Synthetic Photographer']);
+  assert.equal(entry.thumbnailFixedWidth, true);
+  assert.equal(entry.thumbnailFit, 'contain');
+  assert.deepEqual(JSON.parse(JSON.stringify(entry)), entry);
+  assert.equal(entry.interactive, false);
+  assert.equal(Object.isFrozen(WILDLIFE_OVERLAY_SOURCE_OPTIONS), true);
+  assert.equal(WILDLIFE_OVERLAY_SOURCE_OPTIONS.cohortLimit, 24);
+  assert.equal(WILDLIFE_SELECTED_SOURCE_OPTIONS.cohortLimit, 1);
+  assert.equal(WILDLIFE_SELECTED_SOURCE_OPTIONS.collisionCapacity, 1);
+});
+
+test('ambient cards retain only the credited creator and leave names for host truncation', () => {
+  const commonName = 'An extremely long synthetic organism name';
+  for (const [attribution, creator] of [
+    [
+      '(c) Synthetic Photographer, some rights reserved (CC BY-NC)',
+      'Synthetic Photographer',
+    ],
+    ['© Doe, Jane, some rights reserved (CC BY)', 'Doe, Jane'],
+    ['(c) Synthetic Observer, no rights reserved (CC0)', 'Synthetic Observer'],
+    ['Doe, Jane, CC BY', 'Doe, Jane'],
+    ['Synthetic Photographer, CC BY-NC', 'Synthetic Photographer'],
+    ['© Synthetic Photographer (CC BY-SA 4.0)', 'Synthetic Photographer'],
+    ['Synthetic Photographer, CC0', 'Synthetic Photographer'],
+    ['Synthetic Photographer', 'Synthetic Photographer'],
+  ]) {
+    const input = row({ commonName, photo: { ...photo, attribution } });
+    const entry = buildWildlifeThumbnailEntry(input, now);
+    assert.equal(
+      entry.title,
+      commonName,
+      'the overlay host truncates the title',
+    );
+    assert.equal(entry.thumbnailFixedWidth, true);
+    assert.deepEqual(entry.details, [`© ${creator}`]);
+    assert.doesNotMatch(
+      entry.details.join(' '),
+      /Photo:|reserved|CC BY|Not a census/,
+    );
+  }
+  for (const attribution of [
+    'some rights reserved (CC BY)',
+    '(c) ',
+    'CC BY',
+    'CC-BY-NC',
+    '© (CC BY)',
+  ]) {
+    assert.equal(
+      buildWildlifeThumbnailEntry(
+        row({ photo: { ...photo, attribution } }),
+        now,
+      ),
+      null,
+      'a missing creator never becomes a made-up ambient credit',
+    );
+  }
+});
+
+test('ambient cards fade and scale gradually through the 120 km height band', () => {
+  const entry = buildWildlifeThumbnailEntry(row(), now);
+  const options = {
+    fadeStart: entry.altitudeFadeStart,
+    fadeEnd: entry.altitudeFadeEnd,
+  };
+  assert.equal(altitudeFade(70_000, options), 1);
+  assert.ok(altitudeFade(100_000, options) > altitudeFade(120_000, options));
+  assert.ok(altitudeFade(120_000, options) > 0);
+  assert.equal(altitudeFade(125_000, options), 0);
+  assert.equal(altitudeScale(20_000, entry.altitudeScale), 1);
+  assert.equal(altitudeScale(120_000, entry.altitudeScale), 0.9);
+  assert.ok(
+    Math.abs(
+      altitudeScale(119_999, entry.altitudeScale) -
+        altitudeScale(120_001, entry.altitudeScale),
+    ) < 0.001,
+  );
+});
+
+test('selected rows use the shared selected treatment without duplicating photo content', () => {
+  for (const input of [
+    row(),
+    row({ photo: null }),
+    row({ obscured: true, observedAt: null, accuracyM: null }),
+    acartia(),
+  ]) {
+    const label = buildWildlifeSelectedLabel(input);
+    assert.equal(label.id, `wildlife-sightings-label:${input.stableId}`);
+    assert.equal(label.title, input.commonName.toLocaleUpperCase('en'));
+    assert.equal(label.variant, 'label');
+    assert.equal(label.placement, 'above');
+    assert.equal(label.verticalOnly, true);
+    assert.equal(label.protected, true);
+    assert.equal(label.paintLane, 'selected');
+    assert.equal(label.priority, Number.MAX_SAFE_INTEGER);
+    assert.equal(label.interactive, false);
+    assert.equal(label.selected, true);
+    assert.equal(label.details, undefined, 'no link line on canvas cards');
+    assert.equal(label.horizonCull, true);
+    assert.equal(label.edgeFade, 'keyhole');
+    assert.equal(label.accent, wildlifeAccent(input.iconic));
+    for (const field of ['image', 'thumbnailWidth', 'pinned', 'activate'])
+      assert.equal(
+        Object.hasOwn(label, field),
+        false,
+        `${field} is absent from the selected name label`,
+      );
+    assert.deepEqual(JSON.parse(JSON.stringify(label)), label);
+  }
+  const ctx = { measureText: (value) => ({ width: String(value).length * 6 }) };
+  const measured = measureOverlayEntry(ctx, buildWildlifeSelectedLabel(row()));
+  assert.equal(
+    measured.titleH,
+    15,
+    'selected names use the shared selected title metrics',
+  );
+  assert.equal(measured.padX, 12);
+  assert.equal(measured.padY, 8);
+});
+
+test('selected labels normalize one bounded common-name line and stay absent when unnamed', () => {
+  const label = buildWildlifeSelectedLabel(
+    row({
+      commonName: `Synthetic\n  ${'organism '.repeat(10)}`,
+    }),
+  );
+  assert.doesNotMatch(label.title, /\n|  /);
+  assert.ok(
+    Array.from(label.title).length <= WILDLIFE_SELECTED_LABEL_MAX_CHARS,
+  );
+  assert.equal(label.title, 'SYNTHETIC ORGANISM ORGANISM ORGANISM…');
+  assert.ok(label.title.endsWith('…'));
+  assert.equal(buildWildlifeSelectedLabel(row({ commonName: null })), null);
+  assert.equal(
+    buildWildlifeSelectedLabel(row({ commonName: null, scientificName: null })),
+    null,
+  );
+});
+
+test('detail labels show only common names, with no age, grade, accuracy or photo details', () => {
+  const label = buildWildlifeLabelEntry(row());
+  assert.equal(label.id, 'wildlife-sightings-label:inat:123');
+  assert.equal(label.title, "ANNA'S HUMMINGBIRD");
+  assert.equal(label.variant, 'label');
+  assert.equal(label.collisionGroup, 'ambient-label');
+  assert.equal(label.yieldToCollisionGroup, 'ambient-card');
+  assert.equal(
+    label.stateless,
+    true,
+    'labels never retain overlapping incumbent or exit placements',
+  );
+  assert.equal(label.paintLane, 'ambient-label');
+  assert.equal(label.horizonCull, true);
+  assert.equal(label.edgeFade, 'keyhole');
+  assert.equal(label.interactive, false);
+  assert.equal(label.accent, wildlifeAccent('Aves'));
+  for (const field of [
+    'details',
+    'image',
+    'accuracyM',
+    'quality',
+    'observedAt',
+    'maxDistance',
+    'altitudeFadeStart',
+    'altitudeFadeEnd',
+    'selected',
+  ])
+    assert.equal(Object.hasOwn(label, field), false, field);
+  assert.equal(WILDLIFE_LABEL_SOURCE_ID, 'wildlife-sightings-labels');
+  assert.equal(WILDLIFE_LABEL_LIMIT, 150);
+  assert.equal(Object.isFrozen(WILDLIFE_LABEL_SOURCE_OPTIONS), true);
+  assert.equal(WILDLIFE_LABEL_SOURCE_OPTIONS.cohortLimit, WILDLIFE_LABEL_LIMIT);
+  assert.equal(
+    WILDLIFE_LABEL_SOURCE_OPTIONS.collisionCapacity,
+    WILDLIFE_LABEL_LIMIT,
+  );
+  assert.deepEqual(JSON.parse(JSON.stringify(label)), label);
+});
+
+test('unnamed observations have no ambient label and names come only from the row', () => {
+  for (const commonName of [null, undefined, '', ' \n\t '])
+    assert.equal(buildWildlifeLabelEntry({ ...row(), commonName }), null);
+  assert.equal(
+    buildWildlifeLabelEntry({ ...row(), commonName: 'Red-tailed hawk' }).title,
+    'RED-TAILED HAWK',
+  );
+});
+
+test('ambient names select in place and reject activation after their row disappears', () => {
+  let selectedId = null;
+  let exists = true;
+  const label = buildWildlifeLabelEntry(row(), {
+    select(id) {
+      selectedId = id;
+    },
+    hasRow: () => exists,
+  });
+  assert.equal(label.interactive, true);
+  assert.equal(label.accessibilityLabel, "Show Anna's Hummingbird sighting");
+  assert.equal(label.activate(), true);
+  assert.equal(selectedId, 'inat:123');
+  exists = false;
+  assert.equal(label.activate(), false);
+});
+
+test('selected name labels retain the existing altitude fade through 400 km', () => {
+  for (const input of [row(), row({ photo: null }), acartia()]) {
+    const entry = buildWildlifeSelectedLabel(input);
+    const options = {
+      fadeStart: entry.altitudeFadeStart,
+      fadeEnd: entry.altitudeFadeEnd,
+    };
+    assert.equal(altitudeFade(30_000, options), 1);
+    assert.ok(altitudeFade(300_000, options) > 0);
+    assert.equal(altitudeFade(400_000, options), 0);
+    assert.equal(altitudeFade(5_000_000, options), 0);
+  }
+});
+
+test('compact ages follow shared translated minute, hour and day forms', () => {
+  assert.equal(formatAge(59_999), '1m');
+  assert.equal(formatAge(60 * 60_000), '1h');
+  assert.equal(formatAge(2 * 24 * hour), '2d');
+  assert.equal(formatAge(-1), null);
+  assert.equal(formatAge(NaN), null);
+  assert.equal(wildlifeAccent('Protozoa'), '#9aa7b3');
+});
+
+function ambientFixture(rows, screens) {
+  const state = {
+    enabled: true,
+    renderedRows: rows,
+    ambientRows: [],
+    ambientIds: [],
+    labelRows: [],
+    selectedId: null,
+    positions: new Map(
+      rows.map((row) => [row.stableId, screens.get(row.stableId)]),
+    ),
+    pointById: new Map(),
+    rowById: new Map(rows.map((row) => [row.stableId, row])),
+    viewer: {
+      scene: { canvas: { clientWidth: 1200, clientHeight: 900 } },
+      camera: { positionCartographic: { height: 30_000 } },
+    },
+  };
+  const photos = [];
+  const painted = [];
+  const entries = new Map();
+  let cardSourceOptions;
+  const selection = createSelection({
+    state,
+    services: {
+      now: () => now,
+      project: (_scene, position) => position,
+      overlayHost: {
+        setEntries(id, _entries, options) {
+          entries.set(id, _entries);
+          if (id === 'wildlife-sightings') cardSourceOptions = options;
+        },
+      },
+    },
+    parts: {
+      rendering: {
+        occluder: () => null,
+        requestRender() {},
+        setPhotoCardVisibility: (ids) => painted.push([...ids]),
+      },
+      photos: { get: () => null, setAmbient: (rows) => photos.push(rows) },
+    },
+  });
+  return {
+    state,
+    selection,
+    photos,
+    painted,
+    entries,
+    get cardSourceOptions() {
+      return cardSourceOptions;
+    },
+  };
+}
+
+test('label candidates and host priorities use ambientScore before the candidate cap', () => {
+  const rows = Array.from({ length: WILDLIFE_LABEL_LIMIT + 20 }, (_, i) =>
+    row({
+      stableId: `inat:${String(i).padStart(3, '0')}`,
+      commonName: `Synthetic bird ${i}`,
+      favesCount: i,
+    }),
+  );
+  const f = ambientFixture(
+    rows,
+    new Map(
+      rows.map((r, i) => [
+        r.stableId,
+        { x: 10 + (i % 40) * 28, y: 200 + Math.floor(i / 40) * 28 },
+      ]),
+    ),
+  );
+  f.selection.refreshAmbient();
+  const entries = f.entries.get('wildlife-sightings-labels');
+  assert.equal(entries.length, WILDLIFE_LABEL_LIMIT);
+  assert.deepEqual(
+    entries.map((entry) => entry.id),
+    rows
+      .slice(20)
+      .reverse()
+      .map((r) => `wildlife-sightings-label:${r.stableId}`),
+  );
+  for (const r of f.state.labelRows)
+    assert.equal(
+      buildWildlifeLabelEntry(r, { nowMs: now }).priority,
+      ambientScore(r, now),
+    );
+});
+
+test('ambient source forwards actual painted membership to badge visibility', () => {
+  const r = row();
+  const f = ambientFixture([r], new Map([[r.stableId, { x: 150, y: 150 }]]));
+  f.selection.refreshAmbient();
+  assert.deepEqual(f.painted, [], 'a queued photo is not a painted card');
+  f.cardSourceOptions.onVisibilityChange(new Set([`sighting:${r.stableId}`]));
+  assert.deepEqual(f.painted, [[`sighting:${r.stableId}`]]);
+  f.cardSourceOptions.onVisibilityChange(new Set());
+  assert.deepEqual(f.painted.at(-1), []);
+});
+
+test('new ambient cards admit at most one highest-score photo per screen region', () => {
+  const rows = Array.from({ length: 24 }, (_, i) =>
+    row({ stableId: `inat:${i}`, favesCount: i }),
+  );
+  const screens = new Map(
+    rows.map((row, i) => [
+      row.stableId,
+      {
+        x: 150 + (Math.floor(i / 2) % 4) * 300,
+        y: 150 + Math.floor(i / 8) * 300,
+      },
+    ]),
+  );
+  const f = ambientFixture(rows, screens);
+  f.selection.refreshAmbient();
+  assert.equal(f.state.ambientRows.length, 12);
+  assert.ok(
+    f.state.ambientRows.every(
+      (row) => Number(row.stableId.split(':')[1]) % 2 === 1,
+    ),
+  );
+  assert.equal(
+    new Set(
+      f.state.ambientRows.map((row) => {
+        const p = screens.get(row.stableId);
+        return `${Math.floor(p.x / 300)}:${Math.floor(p.y / 300)}`;
+      }),
+    ).size,
+    12,
+  );
+});
+
+test('pans retain every on-screen photo and refreshes only fill free slots', () => {
+  const a = row({ stableId: 'inat:a' });
+  const b = row({ stableId: 'inat:b' });
+  const c = row({ stableId: 'inat:c', favesCount: 1000 });
+  const screens = new Map([
+    [a.stableId, { x: 150, y: 150 }],
+    [b.stableId, { x: 450, y: 150 }],
+    [c.stableId, { x: 170, y: 150 }],
+  ]);
+  const f = ambientFixture([a, b], screens);
+  f.selection.refreshAmbient();
+  const initial = f.state.ambientIds.slice();
+  // This pan moves the two incumbents into one region. Neither may be evicted.
+  f.state.positions.set(b.stableId, { x: 200, y: 160 });
+  f.selection.refreshAmbient();
+  assert.deepEqual(f.state.ambientIds, initial);
+  f.state.rowById.set(c.stableId, c);
+  f.state.positions.set(c.stableId, screens.get(c.stableId));
+  // A new random sample can omit both incumbent rows from the rendered batch.
+  f.state.renderedRows = [c];
+  f.selection.refreshAmbient();
+  assert.deepEqual(f.state.ambientIds, initial);
+  assert.deepEqual(
+    new Set(f.selection.retainedAmbientRows().map((row) => row.stableId)),
+    new Set(initial),
+  );
+  f.state.positions.set(a.stableId, { x: -1, y: 150 });
+  assert.deepEqual(
+    f.selection.retainedAmbientRows().map((row) => row.stableId),
+    [b.stableId],
+  );
+});
+
+test('ambient show/hide thresholds have hysteresis without small-zoom toggles', () => {
+  const a = row();
+  const f = ambientFixture([a], new Map([[a.stableId, { x: 150, y: 150 }]]));
+  const height = f.state.viewer.camera.positionCartographic;
+  height.height = WILDLIFE_CARD_SHOW_MAX_METERS - 1;
+  f.selection.refreshAmbient();
+  assert.equal(f.state.ambientRows.length, 1);
+  for (const altitude of [110_001, 119_999, 120_001, 124_999, 110_001]) {
+    height.height = altitude;
+    f.selection.refreshAmbient();
+    assert.equal(f.state.ambientRows.length, 1);
+  }
+  height.height = WILDLIFE_CARD_HIDE_MAX_METERS;
+  f.selection.refreshAmbient();
+  assert.equal(f.state.ambientRows.length, 0);
+  height.height = WILDLIFE_CARD_HIDE_MAX_METERS - 1;
+  f.selection.refreshAmbient();
+  assert.equal(f.state.ambientRows.length, 0);
+  height.height = WILDLIFE_CARD_SHOW_MAX_METERS;
+  f.selection.refreshAmbient();
+  assert.equal(f.state.ambientRows.length, 1);
+});
diff --git a/src/layers/wildlifeSightings/controls.js b/src/layers/wildlifeSightings/controls.js
new file mode 100644
index 000000000..ced04364f
--- /dev/null
+++ b/src/layers/wildlifeSightings/controls.js
@@ -0,0 +1,250 @@
+import { t, formatNumber, translateKnown } from '../../i18n/index.js';
+import { msg } from '../../i18n/marker.js';
+import { translateFeedError } from '../../ui/statusText.js';
+import { wildlifeIconicGroup } from './model.js';
+import { formatAge } from './photoText.js';
+import {
+  ICONIC_TINTS,
+  ICONIC_LEGEND_ORDER,
+  TAXA_PRESETS,
+  WILDLIFE_CONFIRMED_CHIP_ID,
+  WILDLIFE_GRID_HEIGHT_METERS,
+  WILDLIFE_UPDATE_INTERVAL_MS,
+} from './policy.js';
+
+const LEGEND_LABELS = Object.freeze({
+  Aves: msg('Birds'),
+  Mammalia: msg('Mammals'),
+  Reptilia: msg('Reptiles'),
+  Amphibia: msg('Amphibians'),
+  Actinopterygii: msg('Ray-finned fishes'),
+  Insecta: msg('Insects'),
+  Arachnida: msg('Arachnids'),
+  Plantae: msg('Plants'),
+  Fungi: msg('Fungi'),
+  Animalia: msg('Other animals'),
+  Unknown: msg('Other or unknown'),
+});
+
+/** Own layer-row descriptors and serializable filter options. */
+export function createControls({ state, services, parts }) {
+  function notify() {
+    try {
+      state.controlsListener?.();
+    } catch {
+      /* repaint listeners are optional */
+    }
+  }
+
+  function chip({ id, label, title, params, key, value }) {
+    const pending =
+      state.pendingParams?.keys.includes(key) &&
+      (key === 'confirmed' || state.pendingParams[key] === value);
+    const failedKey = state.failedParams?.keys.includes(key);
+    const failed =
+      failedKey && (key === 'confirmed' || state.failedParams[key] === value);
+    const active =
+      !pending &&
+      (failedKey
+        ? state[key] === value
+        : !!state.drawnParams && state.drawnParams[key] === value);
+    return {
+      id,
+      label: `${label}${pending ? ' ···' : failed ? ' ✕' : ''}`,
+      title: failed
+        ? t('{label} {detail} — click to retry', {
+            label,
+            detail: translateFeedError(
+              state.error || msg('Wildlife sightings source unavailable'),
+            ),
+          })
+        : title,
+      active,
+      busy: !!pending,
+      disabled: !!pending,
+      state: pending
+        ? 'loading'
+        : failed
+          ? 'error'
+          : active
+            ? 'active'
+            : 'idle',
+      params,
+    };
+  }
+
+  const methods = {
+    id: 'wildlife-sightings',
+    name: 'Wildlife Sightings',
+    icon: '🦉',
+    source: 'iNaturalist',
+    updateInterval: WILDLIFE_UPDATE_INTERVAL_MS,
+
+    /** Route camera refreshes through the application's lifecycle manager. */
+    attachDataManager(manager) {
+      state.manager = manager;
+    },
+    /** Connect the layer row's repaint listener. */
+    setRowControlsListener(listener) {
+      state.controlsListener = typeof listener === 'function' ? listener : null;
+    },
+    /** Snapshot the requested filters for share links and restoration. */
+    getParams() {
+      return { confirmed: state.confirmed, taxa: state.taxa };
+    },
+    /** Apply filters while retaining the last accepted display until success. */
+    setParams(params = {}) {
+      const next = {
+        confirmed:
+          typeof params.confirmed === 'boolean'
+            ? params.confirmed
+            : state.confirmed,
+        taxa: TAXA_PRESETS.some((preset) => preset.value === params.taxa)
+          ? params.taxa
+          : state.taxa,
+      };
+      const changed = ['confirmed', 'taxa'].filter(
+        (key) => next[key] !== state[key],
+      );
+      if (!changed.length && !state.failedParams) return true;
+      // Compare with the displayed filters so disjoint edits stay pending.
+      // Initially taxa awaits data while the default-off toggle remains idle.
+      const drawn = state.drawnParams || { confirmed: false, taxa: null };
+      const keys = ['confirmed', 'taxa'].filter(
+        (key) => next[key] !== drawn[key],
+      );
+      if (!changed.length && state.failedParams) {
+        for (const key of state.failedParams.keys) {
+          if (!keys.includes(key)) keys.push(key);
+        }
+      }
+      state.confirmed = next.confirmed;
+      state.taxa = next.taxa;
+      state.pendingParams = keys.length ? { ...next, keys } : null;
+      state.failedParams = null;
+      // Replace the LRU with the accepted result so taxa never get mixed.
+      state.pendingClear = true;
+      state.lastQueryKey = null;
+      state.request?.abort();
+      state.background?.abort();
+      parts.lifecycle.scheduleRefresh();
+      notify();
+      return true;
+    },
+    /** Describe filter chips, nonempty legend groups and provider attribution. */
+    getRowControls() {
+      const confirmedFailed = state.failedParams?.keys.includes('confirmed');
+      const chips = [
+        chip({
+          id: WILDLIFE_CONFIRMED_CHIP_ID,
+          label: t('CONFIRMED'),
+          title: t('Show only community-confirmed (research-grade) sightings'),
+          params: {
+            confirmed: confirmedFailed ? state.confirmed : !state.confirmed,
+          },
+          key: 'confirmed',
+          value: true,
+        }),
+        ...TAXA_PRESETS.map((preset) =>
+          chip({
+            id: preset.id,
+            label: translateKnown(preset.label),
+            title: translateKnown(preset.title),
+            params: { taxa: preset.value },
+            key: 'taxa',
+            value: preset.value,
+          }),
+        ),
+      ];
+      const counts = new Map();
+      for (const row of state.renderedRows) {
+        const group = wildlifeIconicGroup(row.iconic);
+        counts.set(group, (counts.get(group) || 0) + 1);
+      }
+      const legend = ICONIC_LEGEND_ORDER.filter((key) => counts.has(key)).map(
+        (key, index) => ({
+          label: translateKnown(LEGEND_LABELS[key]),
+          color: ICONIC_TINTS[key],
+          count: counts.get(key),
+          ...(index === 0
+            ? {
+                blurb: t(
+                  'Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.',
+                ),
+              }
+            : {}),
+        }),
+      );
+      if (!state.lastUpdate && !legend.length) return { chips, legend: [] };
+      const acartiaCount = state.renderedRows.filter(
+        (row) => row.origin === 'acartia',
+      ).length;
+      const info = acartiaCount
+        ? t(
+            'iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record',
+            { count: formatNumber(acartiaCount) },
+          )
+        : t('iNaturalist contributors · licences per record');
+      return { chips, legend, info };
+    },
+    /** Report the visible count, feed state and retry guidance. */
+    getStats() {
+      const grid = state.gridAvailable === true;
+      const count =
+        state.sightingCount ??
+        (grid ? (state.gridTotal ?? 0) : state.renderedRows.length);
+      const loading = state.loading && !state.lastUpdate;
+      const refreshing = state.loading && !!state.lastUpdate;
+      const age = state.lastUpdate
+        ? formatAge(services.now() - state.lastUpdate)
+        : '';
+      const minutes = state.lastUpdate
+        ? Math.max(0, (services.now() - state.lastUpdate) / 60_000)
+        : 0;
+      const liveAge =
+        minutes < 1
+          ? t('<1m ago')
+          : minutes < 90
+            ? t('{count}m ago', { count: Math.floor(minutes) })
+            : t('{count}h ago', { count: Math.round(minutes / 60) });
+      const stats = {
+        count,
+        lastUpdate: state.lastUpdate,
+        error: state.error,
+        stale: state.stale,
+        loading,
+        refreshing,
+        countLabel: t('{count} sightings in view', {
+          count: formatNumber(count),
+        }),
+        loadingLabel: loading
+          ? t('loading...')
+          : refreshing
+            ? t('refreshing...')
+            : state.stale
+              ? t('STALE · cached {age}', { age })
+              : state.lastUpdate
+                ? t('LIVE · updated {age}', { age: liveAge })
+                : '',
+      };
+      if (
+        !state.error &&
+        !state.query &&
+        state.viewer?.camera?.positionCartographic?.height >
+          WILDLIFE_GRID_HEIGHT_METERS
+      ) {
+        // i18n-ignore: feed-state protocol value
+        stats.status = 'zoom-in';
+        stats.statusMessage = msg('Zoom in for local sightings');
+      } else if (!state.error && state.lastUpdate && !count) {
+        // i18n-ignore: feed-state protocol value
+        stats.status = 'empty';
+        stats.statusMessage = msg('No recent sightings in view');
+      }
+      if (state.retryAt > services.now())
+        stats.retryInSec = Math.ceil((state.retryAt - services.now()) / 1000);
+      return stats;
+    },
+  };
+  return { methods, notify };
+}
diff --git a/src/layers/wildlifeSightings/density.js b/src/layers/wildlifeSightings/density.js
new file mode 100644
index 000000000..503b8d86a
--- /dev/null
+++ b/src/layers/wildlifeSightings/density.js
@@ -0,0 +1,462 @@
+import { wildlifeGridCellBounds } from './gridViewport.js';
+import {
+  createWildlifeWorkQueue,
+  drainWildlifeWork,
+  WILDLIFE_WORK_UNIT,
+} from './performance.js';
+
+export const WILDLIFE_DENSITY_OVERLAP = 4;
+const KERNEL_SIGMA = 0.7;
+export const WILDLIFE_DENSITY_MAX_ALPHA = 0.34;
+const DENSITY_MIN_ALPHA = 0.012;
+const DENSITY_RAMP_GAMMA = 3;
+const METERS_PER_DEGREE = (2 * Math.PI * 6378137) / 360;
+const FADE_STEPS = 3;
+const FADE_STEP_MS = 60;
+const SPRITE_SIZE = 128;
+// Fade coarse splats before they read as haze across the whole Earth disc.
+const ALTITUDE_FADE_START = 3_000_000;
+const ALTITUDE_FADE_END = 8_000_000;
+// Sparse cells read cool teal; hotspots warm toward amber. Sensor styles keep
+// one neutral or phosphor tint.
+const NORMAL_TINT = { low: [0.3, 0.8, 0.78], high: [1, 0.78, 0.38] };
+const MONO_TINT = { low: [0.96, 0.96, 0.96], high: [0.96, 0.96, 0.96] };
+const CRT_TINT = { low: [0.48, 1, 0.72], high: [0.48, 1, 0.72] };
+
+/** View-relative alpha keeps hotspots distinct as cell counts grow on zoom-out. */
+export function wildlifeDensityIntensity(rank) {
+  if (!(rank > 0) || !Number.isFinite(rank)) return 0;
+  return (
+    DENSITY_MIN_ALPHA +
+    (WILDLIFE_DENSITY_MAX_ALPHA - DENSITY_MIN_ALPHA) *
+      Math.min(1, rank) ** DENSITY_RAMP_GAMMA
+  );
+}
+
+/** Rank function over the snapshot's positive counts: the share of cells with
+ * a count at or below the given one. */
+export function wildlifeDensityRanks(cells = []) {
+  const counts = [];
+  for (const cell of cells)
+    if (Number.isSafeInteger(cell?.cellCount) && cell.cellCount > 0)
+      counts.push(cell.cellCount);
+  counts.sort((a, b) => a - b);
+  return (count) => {
+    if (!counts.length || !(count > 0)) return 0;
+    let low = 0;
+    let high = counts.length;
+    while (low < high) {
+      const mid = (low + high) >>> 1;
+      if (counts[mid] <= count) low = mid + 1;
+      else high = mid;
+    }
+    return low / counts.length;
+  };
+}
+
+/** Truncated Gaussian in source-cell widths; overlapping splats hide the grid. */
+export function wildlifeDensityKernel(distance) {
+  const radius = WILDLIFE_DENSITY_OVERLAP / 2;
+  if (!Number.isFinite(distance) || distance < 0 || distance >= radius)
+    return 0;
+  const edge = Math.exp(-(radius ** 2) / (2 * KERNEL_SIGMA ** 2));
+  return (
+    (Math.exp(-(distance ** 2) / (2 * KERNEL_SIGMA ** 2)) - edge) / (1 - edge)
+  );
+}
+
+const DENSITY_IMAGE = `data:image/svg+xml,${encodeURIComponent(
+  `<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128"><defs><radialGradient id="g">${Array.from(
+    { length: 33 },
+    (_, i) =>
+      `<stop offset="${i / 32}" stop-color="white" stop-opacity="${wildlifeDensityKernel(((i / 32) * WILDLIFE_DENSITY_OVERLAP) / 2).toFixed(5)}"/>`,
+  ).join(
+    '',
+  )}</radialGradient></defs><circle cx="64" cy="64" r="64" fill="url(#g)"/></svg>`,
+)}`;
+
+function tintForStyle(style) {
+  if (['mono', 'surveillance', 'thermal', 'noir', 'nvg'].includes(style))
+    return MONO_TINT;
+  return ['crt', 'retro'].includes(style) ? CRT_TINT : NORMAL_TINT;
+}
+
+function intersects(bounds, boxes, padding = 0) {
+  if (!boxes?.length) return true;
+  const latitude = (bounds.north - bounds.south) * padding;
+  const longitude = (bounds.east - bounds.west) * padding;
+  for (const box of boxes) {
+    if (
+      bounds.north + latitude < box.south ||
+      bounds.south - latitude > box.north
+    )
+      continue;
+    // Both a padded splat and the viewport can straddle the antimeridian.
+    const east = box.east < box.west ? box.east + 360 : box.east;
+    const left = bounds.west - longitude;
+    const right = bounds.east + longitude;
+    if (
+      (right >= box.west && left <= east) ||
+      (right + 360 >= box.west && left + 360 <= east) ||
+      (right - 360 >= box.west && left - 360 <= east)
+    )
+      return true;
+  }
+  return false;
+}
+
+// Fit the entire kernel inside the globe's tangent cone, plus 5% of its radius.
+// A visible centre alone lets a depth-free billboard bleed across the limb.
+// The inscribed sphere is conservative for WGS84 and needs no projections.
+function horizonTest(cameraPosition, radius) {
+  const { x, y, z } = cameraPosition || {};
+  const distance = Math.hypot(x, y, z);
+  if (!Number.isFinite(distance) || distance <= radius) return null;
+  const nx = x / distance;
+  const ny = y / distance;
+  const nz = z / distance;
+  const sinAngle = radius / distance;
+  const cosAngleSquared = 1 - sinAngle ** 2;
+  const horizonPlane = radius * sinAngle;
+  return (position, kernelRadius) => {
+    const along = position.x * nx + position.y * ny + position.z * nz;
+    if (along <= horizonPlane) return false;
+    const clearance = sinAngle * (distance - along) - kernelRadius * 1.05;
+    const acrossSquared = Math.max(
+      0,
+      position.x ** 2 + position.y ** 2 + position.z ** 2 - along ** 2,
+    );
+    return clearance > 0 && acrossSquared * cosAngleSquared < clearance ** 2;
+  };
+}
+
+/** Own noninteractive, world-sized glow splats, arrival fades and style changes. */
+/** A world-sized kernel fills the screen once the camera is inside it, e.g.
+ * while flying in before the closer view's tiles arrive. Cesium fades it on the
+ * GPU: gone within half its width, full beyond twice its width. */
+export const WILDLIFE_DENSITY_NEAR_FADE = Object.freeze({ near: 0.5, far: 2 });
+
+export function createWildlifeDensity({
+  cesium: C,
+  viewer,
+  positionForCell = (cell) => C.Cartesian3.fromDegrees(cell.lon, cell.lat),
+  requestRender = () => {},
+  setTimer = (fn, delay) => setTimeout(fn, delay),
+  clearTimer = (timer) => clearTimeout(timer),
+  requestIdle,
+  cancelIdle,
+  eventTarget = globalThis.window,
+  documentRef = globalThis.document,
+} = {}) {
+  let collection = null;
+  const nearFade = (width) =>
+    new C.NearFarScalar(
+      width * WILDLIFE_DENSITY_NEAR_FADE.near,
+      0,
+      width * WILDLIFE_DENSITY_NEAR_FADE.far,
+      1,
+    );
+  let metadata = new WeakMap();
+  const entries = new Map();
+  const fading = new Set();
+  let fadeTimer = null;
+  let destroyed = false;
+  let generation = 0;
+  let cockpitVision = false;
+  let tint = tintForStyle(documentRef?.documentElement?.dataset?.gevStyle);
+  let listening = false;
+  const fadeQueue = createWildlifeWorkQueue({ requestIdle, cancelIdle });
+  const styleQueue = createWildlifeWorkQueue({ requestIdle, cancelIdle });
+
+  // BillboardCollection does not implement Primitive's allowPicking option.
+  // Skipping its public pick update prevents its translucent quads from
+  // intercepting observations, including pixels with a faint glow alpha.
+  class DensityCollection extends C.BillboardCollection {
+    constructor() {
+      // Cesium's TRANSLUCENT-only option writes depth and occludes badges.
+      super();
+      this.allowPicking = false;
+    }
+    update(frameState) {
+      if (frameState.passes?.pick) return;
+      return super.update(frameState);
+    }
+  }
+
+  function color(entry) {
+    const mix = (i) => tint.low[i] + (tint.high[i] - tint.low[i]) * entry.rank;
+    return new C.Color(
+      mix(0),
+      mix(1),
+      mix(2),
+      (wildlifeDensityIntensity(entry.rank) * entry.opacity * entry.fade) /
+        FADE_STEPS,
+    );
+  }
+
+  function* styleWork() {
+    let visits = 0;
+    for (const entry of entries.values()) {
+      if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'density-style';
+      entry.point.color = color(entry);
+    }
+  }
+
+  function setStyle(style) {
+    const next = tintForStyle(style);
+    if (next === tint) return;
+    tint = next;
+    if (entries.size)
+      styleQueue.start(styleWork(), () => requestRender('density-style'));
+  }
+
+  function onStyle(event) {
+    if (!cockpitVision) setStyle(event?.detail?.style);
+  }
+
+  function onVision(event) {
+    cockpitVision = event?.detail?.cockpit === true;
+    setStyle(event?.detail?.style);
+  }
+
+  function ensureCollection() {
+    if (collection) return;
+    collection = new DensityCollection();
+    viewer.scene.primitives.add(collection);
+    if (!listening) {
+      tint = tintForStyle(documentRef?.documentElement?.dataset?.gevStyle);
+      eventTarget?.addEventListener?.('gev:style-change', onStyle);
+      eventTarget?.addEventListener?.('gev:vision-change', onVision);
+      listening = true;
+    }
+  }
+
+  function* fadeWork() {
+    let visits = 0;
+    for (const entry of fading) {
+      if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'density-fade';
+      entry.fade++;
+      entry.point.color = color(entry);
+      if (entry.fade >= FADE_STEPS) fading.delete(entry);
+    }
+  }
+
+  function scheduleFade() {
+    if (fadeTimer !== null || fadeQueue.pending || !fading.size || destroyed)
+      return;
+    fadeTimer = setTimer(() => {
+      fadeTimer = null;
+      fadeQueue.start(fadeWork(), () => {
+        requestRender('density-fade');
+        scheduleFade();
+      });
+    }, FADE_STEP_MS);
+  }
+
+  function dataForCell(cell, operations) {
+    if (
+      !cell ||
+      !Number.isFinite(cell.lat) ||
+      Math.abs(cell.lat) > 90 ||
+      !Number.isFinite(cell.lon) ||
+      Math.abs(cell.lon) > 180 ||
+      !Number.isSafeInteger(cell.cellCount) ||
+      cell.cellCount <= 0
+    )
+      return null;
+    const old = metadata.get(cell);
+    if (
+      old?.id === cell.id &&
+      old.lat === cell.lat &&
+      old.lon === cell.lon &&
+      old.count === cell.cellCount
+    )
+      return old;
+    const bounds =
+      old?.id === cell.id ? old.bounds : wildlifeGridCellBounds(cell.id);
+    if (!bounds) return null;
+    const samePosition = old?.lat === cell.lat && old?.lon === cell.lon;
+    const data = {
+      id: cell.id,
+      lat: cell.lat,
+      lon: cell.lon,
+      count: cell.cellCount,
+      bounds,
+      width:
+        WILDLIFE_DENSITY_OVERLAP *
+        METERS_PER_DEGREE *
+        Math.max(
+          (bounds.east - bounds.west) * Math.cos((cell.lat * Math.PI) / 180),
+          bounds.north - bounds.south,
+        ),
+      position: samePosition ? old.position : positionForCell(cell),
+    };
+    operations.densityMetadataBuilds++;
+    if (!samePosition) operations.densityPositionBuilds++;
+    metadata.set(cell, data);
+    return data;
+  }
+
+  /** Reconcile the authoritative snapshot, including successful empty tiles. */
+  function* updateWork(
+    cells = [],
+    { boxes, isPointVisible, onOperations = () => {} } = {},
+  ) {
+    const token = ++generation;
+    const operations = {
+      densityVisits: 0,
+      densityRetirementVisits: 0,
+      densityMetadataBuilds: 0,
+      densityPositionBuilds: 0,
+      densityWrites: 0,
+      densityCreated: 0,
+      densityRemoved: 0,
+    };
+    let sightingCount = 0;
+    let changed = false;
+    const height = viewer.camera?.positionCartographic?.height ?? 0;
+    const opacity = Math.max(
+      0,
+      Math.min(
+        1,
+        (ALTITUDE_FADE_END - height) /
+          (ALTITUDE_FADE_END - ALTITUDE_FADE_START),
+      ),
+    );
+    const insideHorizon = horizonTest(
+      viewer.camera?.positionWC,
+      C.Ellipsoid?.WGS84?.minimumRadius ?? 6_356_752.314245,
+    );
+    const rankOf = wildlifeDensityRanks(cells);
+    for (const cell of cells) {
+      if (operations.densityVisits++ % WILDLIFE_WORK_UNIT === 0) {
+        yield 'density';
+        if (destroyed || token !== generation)
+          return { sightingCount: 0, changed: false, size: entries.size };
+      }
+      const data = dataForCell(cell, operations);
+      if (
+        !data ||
+        !intersects(data.bounds, boxes, (WILDLIFE_DENSITY_OVERLAP - 1) / 2) ||
+        isPointVisible?.(data.position) === false
+      )
+        continue;
+      if (intersects(data.bounds, boxes))
+        sightingCount = Math.min(
+          Number.MAX_SAFE_INTEGER,
+          sightingCount + data.count,
+        );
+      // These are visual decisions only; counts retain every visible cell.
+      if (
+        opacity === 0 ||
+        insideHorizon?.(data.position, data.width / 2) === false
+      )
+        continue;
+      const rank = rankOf(data.count);
+      let entry = entries.get(data.id);
+      if (!entry) {
+        ensureCollection();
+        entry = { data, rank, opacity, fade: 1, seen: token, point: null };
+        entry.point = collection.add({
+          position: data.position,
+          image: DENSITY_IMAGE,
+          // Cesium packs width in 16 bits even for meter-sized billboards.
+          // Put the world diameter in its unrestricted scale attribute so
+          // continental kernels never clamp into thin vertical ellipses.
+          width: SPRITE_SIZE,
+          height: SPRITE_SIZE,
+          scale: data.width / SPRITE_SIZE,
+          sizeInMeters: true,
+          color: color(entry),
+          disableDepthTestDistance: Number.POSITIVE_INFINITY,
+          translucencyByDistance: nearFade(data.width),
+        });
+        entries.set(data.id, entry);
+        fading.add(entry);
+        operations.densityCreated++;
+        changed = true;
+      } else {
+        entry.seen = token;
+        if (entry.data.position !== data.position) {
+          entry.point.position = data.position;
+          operations.densityWrites++;
+          changed = true;
+        }
+        if (entry.data.width !== data.width) {
+          entry.point.scale = data.width / SPRITE_SIZE;
+          entry.point.translucencyByDistance = nearFade(data.width);
+          operations.densityWrites++;
+          changed = true;
+        }
+        if (entry.rank !== rank || entry.opacity !== opacity) {
+          entry.rank = rank;
+          entry.opacity = opacity;
+          entry.point.color = color(entry);
+          operations.densityWrites++;
+          changed = true;
+        }
+        entry.data = data;
+      }
+    }
+    for (const [id, entry] of entries) {
+      if (operations.densityRetirementVisits++ % WILDLIFE_WORK_UNIT === 0) {
+        yield 'density';
+        if (destroyed || token !== generation)
+          return { sightingCount: 0, changed: false, size: entries.size };
+      }
+      if (entry.seen === token) continue;
+      collection.remove(entry.point);
+      fading.delete(entry);
+      entries.delete(id);
+      operations.densityRemoved++;
+      changed = true;
+    }
+    if (!entries.size && collection) clear(true);
+    else scheduleFade();
+    if (changed) requestRender('density');
+    onOperations(operations);
+    return { sightingCount, changed, size: entries.size };
+  }
+
+  /** Release the texture atlas, billboards, cached coordinates and all work. */
+  function clear(keepMetadata = false) {
+    generation++;
+    fadeQueue.cancel();
+    styleQueue.cancel();
+    if (fadeTimer !== null) clearTimer(fadeTimer);
+    fadeTimer = null;
+    entries.clear();
+    fading.clear();
+    if (!keepMetadata) metadata = new WeakMap();
+    if (collection) {
+      if (
+        viewer.scene.primitives.remove(collection) !== true &&
+        !collection.isDestroyed?.()
+      )
+        collection.destroy();
+      collection = null;
+    }
+    if (listening) {
+      eventTarget?.removeEventListener?.('gev:style-change', onStyle);
+      eventTarget?.removeEventListener?.('gev:vision-change', onVision);
+      listening = false;
+    }
+    cockpitVision = false;
+  }
+
+  return {
+    updateWork,
+    update: (cells, options) => drainWildlifeWork(updateWork(cells, options)),
+    clear,
+    destroy() {
+      clear();
+      destroyed = true;
+    },
+    get collection() {
+      return collection;
+    },
+    get size() {
+      return entries.size;
+    },
+  };
+}
diff --git a/src/layers/wildlifeSightings/density.test.mjs b/src/layers/wildlifeSightings/density.test.mjs
new file mode 100644
index 000000000..f4c610c7f
--- /dev/null
+++ b/src/layers/wildlifeSightings/density.test.mjs
@@ -0,0 +1,508 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { wildlifeGridCellBounds } from './gridViewport.js';
+import {
+  createWildlifeDensity,
+  wildlifeDensityIntensity,
+  wildlifeDensityRanks,
+  wildlifeDensityKernel,
+  WILDLIFE_DENSITY_MAX_ALPHA,
+  WILDLIFE_DENSITY_NEAR_FADE,
+  WILDLIFE_DENSITY_OVERLAP,
+} from './density.js';
+import { WILDLIFE_WORK_UNIT } from './performance.js';
+
+function cell(column, count = 1, options = {}) {
+  const id = `grid:3/4/2:31:${column * 2 + 1}`;
+  const bounds = wildlifeGridCellBounds(id);
+  return {
+    id,
+    lat: (bounds.south + bounds.north) / 2,
+    lon: (bounds.west + bounds.east) / 2,
+    cellCount: count,
+    ...options,
+  };
+}
+
+function harness({ documentStyle = 'normal', camera = {} } = {}) {
+  const counts = { positions: 0, writes: 0, created: 0, updates: 0 };
+  class BillboardCollection extends Cesium.BillboardCollection {
+    add(options) {
+      counts.created++;
+      const point = super.add(options);
+      return new Proxy(point, {
+        get: (target, key) => Reflect.get(target, key, target),
+        set(target, key, value) {
+          counts.writes++;
+          return Reflect.set(target, key, value, target);
+        },
+      });
+    }
+    update() {
+      counts.updates++;
+    }
+  }
+  const primitives = new Cesium.PrimitiveCollection();
+  let handle = 0;
+  const timers = new Map();
+  const idle = new Map();
+  const renders = [];
+  const listeners = new Map();
+  const eventTarget = {
+    addEventListener(name, listener) {
+      if (!listeners.has(name)) listeners.set(name, new Set());
+      listeners.get(name).add(listener);
+    },
+    removeEventListener(name, listener) {
+      listeners.get(name)?.delete(listener);
+    },
+    emit(name, detail) {
+      for (const listener of listeners.get(name) || []) listener({ detail });
+    },
+  };
+  const density = createWildlifeDensity({
+    cesium: { ...Cesium, BillboardCollection },
+    viewer: { scene: { primitives }, camera },
+    positionForCell(row) {
+      counts.positions++;
+      return Cesium.Cartesian3.fromDegrees(row.lon, row.lat);
+    },
+    requestRender: (reason) => renders.push(reason),
+    setTimer(fn) {
+      timers.set(++handle, fn);
+      return handle;
+    },
+    clearTimer: (id) => timers.delete(id),
+    requestIdle(fn) {
+      idle.set(++handle, fn);
+      return handle;
+    },
+    cancelIdle: (id) => idle.delete(id),
+    eventTarget,
+    documentRef: { documentElement: { dataset: { gevStyle: documentStyle } } },
+  });
+  function flushIdle() {
+    while (idle.size) {
+      const [id, fn] = idle.entries().next().value;
+      idle.delete(id);
+      fn();
+    }
+  }
+  function fadeStep() {
+    for (const [id, fn] of [...timers]) {
+      timers.delete(id);
+      fn();
+    }
+    flushIdle();
+  }
+  return {
+    density,
+    primitives,
+    counts,
+    renders,
+    timers,
+    idle,
+    listeners,
+    eventTarget,
+    flushIdle,
+    fadeStep,
+    settle() {
+      while (timers.size || idle.size) {
+        fadeStep();
+        flushIdle();
+      }
+    },
+  };
+}
+
+test('density intensity rises with view rank, is bounded, and leaves no background for zero data', () => {
+  for (const empty of [0, -1, null, undefined, NaN, Infinity])
+    assert.equal(wildlifeDensityIntensity(empty), 0);
+  const ranks = [0.01, 0.1, 0.25, 0.5, 0.75, 0.9, 1];
+  const values = ranks.map(wildlifeDensityIntensity);
+  assert.ok(values[0] > 0, 'the sparsest cell still leaves a trace');
+  assert.ok(values[0] < 0.02, 'sparse cells stay a trace, not a haze');
+  for (let i = 1; i < values.length; i++) assert.ok(values[i] > values[i - 1]);
+  assert.equal(values.at(-1), WILDLIFE_DENSITY_MAX_ALPHA);
+  assert.ok(
+    values[3] < WILDLIFE_DENSITY_MAX_ALPHA / 3,
+    'a median cell is well below a hotspot',
+  );
+});
+
+test('density ranks are relative to the view, so hotspots stay distinct at any zoom', () => {
+  const cells = (counts) => counts.map((cellCount) => ({ cellCount }));
+  const near = wildlifeDensityRanks(cells([1, 2, 3, 40]));
+  const far = wildlifeDensityRanks(cells([100, 200, 300, 4000]));
+  assert.equal(near(40), 1);
+  assert.equal(far(4000), 1, 'the top cell is brightest whatever its count');
+  assert.equal(near(1), far(100), 'the same position ranks the same');
+  assert.equal(wildlifeDensityRanks(cells([0, -1]))(5), 0);
+  assert.equal(wildlifeDensityRanks([])(5), 0);
+});
+
+test('an empty density snapshot creates no glow', () => {
+  const h = harness();
+  assert.deepEqual(h.density.update([]), {
+    sightingCount: 0,
+    changed: false,
+    size: 0,
+  });
+  h.density.update([
+    cell(0, 0),
+    cell(1, -1),
+    cell(2, 0.5),
+    cell(3, 1, { id: 'invalid' }),
+  ]);
+  assert.equal(h.density.collection, null);
+  assert.equal(h.primitives.length, 0);
+  assert.equal(h.timers.size, 0);
+  h.density.destroy();
+});
+
+test('uniform occupied cells make a continuous field with no visible lattice', () => {
+  assert.ok(WILDLIFE_DENSITY_OVERLAP >= 1.5);
+  assert.equal(wildlifeDensityKernel(0), 1);
+  assert.equal(wildlifeDensityKernel(WILDLIFE_DENSITY_OVERLAP / 2), 0);
+  const samples = [];
+  for (let x = 0; x < 1; x += 0.1)
+    for (let y = 0; y < 1; y += 0.1) {
+      let value = 0;
+      for (let dx = -3; dx <= 3; dx++)
+        for (let dy = -3; dy <= 3; dy++)
+          value += wildlifeDensityKernel(Math.hypot(x - dx, y - dy));
+      samples.push(value);
+    }
+  const modulation =
+    (Math.max(...samples) - Math.min(...samples)) / Math.max(...samples);
+  assert.ok(modulation < 0.007, `${(100 * modulation).toFixed(3)}% modulation`);
+});
+
+test('each glow kernel fades on the GPU as the camera comes inside it, scaled to its own width', () => {
+  const h = harness();
+  h.density.update([cell(0, 4), cell(1, 9)]);
+  const collection = h.density.collection;
+  assert.equal(collection.length, 2);
+  for (let i = 0; i < collection.length; i++) {
+    const point = collection.get(i);
+    const width = point.scale * point.width;
+    const fade = point.translucencyByDistance;
+    assert.ok(fade, 'no screen-filling kernel when zoomed inside it');
+    assert.ok(
+      Math.abs(fade.near - width * WILDLIFE_DENSITY_NEAR_FADE.near) < 1e-6,
+    );
+    assert.equal(fade.nearValue, 0);
+    assert.ok(
+      Math.abs(fade.far - width * WILDLIFE_DENSITY_NEAR_FADE.far) < 1e-6,
+    );
+    assert.equal(fade.farValue, 1);
+  }
+  h.density.destroy();
+});
+
+test('occupied grid counts produce unlabelled world-sized glow billboards that never enter Cesium picking', () => {
+  const h = harness();
+  const rows = [cell(0, 1), cell(1, 100), cell(2, 1000000)];
+  const result = h.density.update(rows);
+  assert.equal(result.sightingCount, 1000101);
+  assert.equal(h.primitives.length, 1);
+  const collection = h.density.collection;
+  assert.equal(collection.allowPicking, false);
+  assert.equal(collection.length, 3);
+  const first = collection.get(0);
+  assert.equal(
+    first.id,
+    undefined,
+    'density has no sighting identity or pick payload',
+  );
+  assert.equal(first.sizeInMeters, true);
+  assert.equal(first.scaleByDistance, undefined);
+  assert.match(decodeURIComponent(first.image), /radialGradient/);
+  assert.doesNotMatch(decodeURIComponent(first.image), /text|badge|raven/);
+  const bounds = wildlifeGridCellBounds(rows[0].id);
+  const logicalHeight =
+    (((bounds.north - bounds.south) * Math.PI) / 180) * 6378137;
+  assert.ok(first.width * first.scale >= 1.5 * logicalHeight);
+  assert.equal(first.width, first.height);
+  assert.ok(
+    first.width <= 65536,
+    'encoded dimensions fit Cesium width packing',
+  );
+  assert.ok(
+    first.width * first.scale > 65536,
+    'continental splats retain their true footprint through scale',
+  );
+  collection.update({ passes: { pick: true } });
+  assert.equal(
+    h.counts.updates,
+    0,
+    'the real public pick update is suppressed',
+  );
+  collection.update({ passes: { render: true } });
+  assert.equal(h.counts.updates, 1);
+  h.settle();
+  const rankOf = wildlifeDensityRanks(rows);
+  for (let i = 0; i < collection.length; i++)
+    assert.ok(
+      Math.abs(
+        collection.get(i).color.alpha -
+          wildlifeDensityIntensity(rankOf(rows[i].cellCount)),
+      ) < 1e-12,
+    );
+  h.density.destroy();
+});
+
+test('progressive tile arrival fades only new cells and reuses existing glow without flashing', () => {
+  const h = harness();
+  const one = cell(0, 4);
+  const two = cell(1, 10);
+  h.density.update([one]);
+  const first = h.density.collection.get(0);
+  const starting = first.color.alpha;
+  h.fadeStep();
+  assert.ok(first.color.alpha > starting);
+  const middle = first.color.alpha;
+  h.density.update([one, two]);
+  // The arriving tile re-ranks the incumbent (alone it was the hotspot; now
+  // it is the median) but its fade progress is kept, not restarted.
+  const progress = middle / wildlifeDensityIntensity(1);
+  assert.ok(
+    Math.abs(first.color.alpha - wildlifeDensityIntensity(0.5) * progress) <
+      1e-12,
+    'a streamed tile re-ranks but does not restart incumbents',
+  );
+  assert.equal(h.density.collection.get(0), first);
+  assert.equal(h.density.size, 2);
+  h.settle();
+  const settled = first.color.alpha;
+  h.density.update([one, two]);
+  assert.equal(first.color.alpha, settled);
+  h.density.update([two]);
+  assert.equal(h.density.size, 1);
+  assert.equal(h.density.collection.length, 1);
+  h.density.update([]);
+  assert.equal(h.density.size, 0);
+  assert.equal(
+    h.density.collection,
+    null,
+    'empty data releases the atlas and collection',
+  );
+  assert.equal(
+    h.primitives.length,
+    0,
+    'no full-view fill remains over empty data',
+  );
+  h.density.destroy();
+});
+
+test('visibility and antimeridian padding are applied on data/moveEnd work only', () => {
+  const h = harness();
+  const west = cell(1);
+  const east = cell(28);
+  const box = { ...wildlifeGridCellBounds(west.id) };
+  assert.equal(h.density.update([west, east], { boxes: [box] }).size, 1);
+  assert.equal(
+    h.density.update([west], { boxes: [box], isPointVisible: () => false })
+      .size,
+    0,
+  );
+  const id = 'grid:3/0/2:31:1';
+  const bounds = wildlifeGridCellBounds(id);
+  const wrapped = {
+    ...west,
+    id,
+    lat: (bounds.south + bounds.north) / 2,
+    lon: -179.3,
+  };
+  const crossed = {
+    south: bounds.south,
+    north: bounds.north,
+    west: 179,
+    east: -179,
+  };
+  assert.equal(h.density.update([wrapped], { boxes: [crossed] }).size, 1);
+  h.density.destroy();
+});
+
+test('density culls far-side cells and front-side kernels that would spill over the limb', () => {
+  const camera = {
+    positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 5_000_000),
+    positionCartographic: { height: 5_000_000 },
+  };
+  const h = harness({ camera });
+  const occluder = new Cesium.EllipsoidalOccluder(
+    Cesium.Ellipsoid.WGS84,
+    camera.positionWC,
+  );
+  const cells = [
+    cell(0, 1, { lat: 0, lon: 0 }),
+    cell(1, 2, { lat: 0, lon: 54 }),
+    cell(2, 4, { lat: 0, lon: 110 }),
+  ];
+  assert.equal(
+    occluder.isPointVisible(Cesium.Cartesian3.fromDegrees(54, 0)),
+    true,
+    'the limb fixture has a visible centre but an overflowing footprint',
+  );
+  const result = h.density.update(cells, {
+    isPointVisible: (anchor) => occluder.isPointVisible(anchor),
+  });
+  assert.equal(result.size, 1, 'only the fully front-side kernel can glow');
+  assert.equal(
+    result.sightingCount,
+    3,
+    'visual limb padding never removes visible counts',
+  );
+  h.density.destroy();
+});
+
+test('density fades from regional detail to a clear whole-globe view without frame work or count loss', () => {
+  const camera = { positionCartographic: { height: 3_000_000 } };
+  const h = harness({ camera });
+  const cells = [cell(0, 12)];
+  h.density.update(cells);
+  h.settle();
+  const point = h.density.collection.get(0);
+  const fullAlpha = point.color.alpha;
+  camera.positionCartographic.height = 5_500_000;
+  h.density.update(cells);
+  assert.equal(h.density.collection.get(0), point);
+  assert.ok(Math.abs(point.color.alpha - fullAlpha / 2) < 1e-12);
+  const writes = h.counts.writes;
+  h.density.update(cells);
+  assert.equal(h.counts.writes, writes, 'unchanged height writes nothing');
+  camera.positionCartographic.height = 8_000_000;
+  assert.equal(h.density.update(cells).sightingCount, 12);
+  assert.equal(h.density.collection, null);
+  assert.equal(h.timers.size, 0, 'no invisible fade or frame loop');
+  const positions = h.counts.positions;
+  camera.positionCartographic.height = 3_000_000;
+  h.density.update(cells);
+  h.settle();
+  assert.equal(
+    h.counts.positions,
+    positions,
+    'altitude changes reuse decoded positions',
+  );
+  assert.equal(h.density.collection.get(0).color.alpha, fullAlpha);
+  h.density.destroy();
+});
+
+test('styles follow persisted mono/CRT and cockpit vision overrides, without adding a second ramp', () => {
+  const h = harness({ documentStyle: 'thermal' });
+  h.density.update([cell(0)]);
+  h.settle();
+  const point = h.density.collection.get(0);
+  assert.equal(point.color.red, point.color.green);
+  assert.equal(point.color.green, point.color.blue);
+  const alpha = point.color.alpha;
+  h.eventTarget.emit('gev:style-change', { style: 'retro' });
+  h.flushIdle();
+  assert.ok(point.color.green > point.color.red);
+  h.eventTarget.emit('gev:vision-change', { cockpit: true, style: 'nvg' });
+  h.flushIdle();
+  assert.equal(point.color.red, point.color.green);
+  h.eventTarget.emit('gev:style-change', { style: 'normal' });
+  h.flushIdle();
+  assert.equal(
+    point.color.red,
+    point.color.green,
+    'cockpit vision wins while active',
+  );
+  h.eventTarget.emit('gev:vision-change', { cockpit: false, style: 'normal' });
+  h.flushIdle();
+  assert.notEqual(point.color.red, point.color.green);
+  assert.equal(point.color.alpha, alpha);
+  h.density.destroy();
+});
+
+test('clear/disable and destroy release the atlas, primitives, coordinates, timers and listeners', () => {
+  const h = harness();
+  const row = cell(0);
+  h.density.update([row]);
+  const old = h.density.collection;
+  assert.equal(h.timers.size, 1);
+  h.fadeStep();
+  h.density.clear();
+  assert.equal(old.isDestroyed(), true);
+  assert.equal(h.density.collection, null);
+  assert.equal(h.density.size, 0);
+  assert.equal(h.primitives.length, 0);
+  assert.equal(h.timers.size, 0);
+  assert.equal(h.idle.size, 0);
+  for (const values of h.listeners.values()) assert.equal(values.size, 0);
+  const priorPositions = h.counts.positions;
+  h.density.update([row]);
+  assert.equal(
+    h.counts.positions,
+    priorPositions + 1,
+    'disable released cached coordinates',
+  );
+  const work = h.density.updateWork([cell(2)]);
+  work.next();
+  h.density.destroy();
+  assert.equal(
+    work.next().done,
+    true,
+    'obsolete data work cannot resurrect a destroyed layer',
+  );
+  assert.equal(h.density.collection, null);
+  assert.equal(h.primitives.length, 0);
+  assert.equal(h.timers.size, 0);
+  assert.equal(h.idle.size, 0);
+});
+
+test('dense six-tile updates have a deterministic linear operation budget and no warmed writes/projections', (t) => {
+  const h = harness();
+  const cells = [];
+  for (let x = 1; x < 3; x++)
+    for (let y = 1; y < 4; y++)
+      for (let row = 1; row < 64; row += 2)
+        for (let column = 1; column < 64; column += 2) {
+          const id = `grid:3/${x}/${y}:${row}:${column}`;
+          const box = wildlifeGridCellBounds(id);
+          cells.push({
+            id,
+            lat: (box.south + box.north) / 2,
+            lon: (box.west + box.east) / 2,
+            cellCount: row * 64 + column,
+          });
+        }
+  let operations;
+  h.density.update(cells, {
+    onOperations: (value) => {
+      operations = value;
+    },
+  });
+  h.settle();
+  assert.equal(operations.densityVisits, 6144);
+  assert.equal(operations.densityMetadataBuilds, 6144);
+  assert.equal(operations.densityPositionBuilds, 6144);
+  assert.equal(operations.densityCreated, 6144);
+  const positions = h.counts.positions;
+  const writes = h.counts.writes;
+  let units = 0;
+  const work = h.density.updateWork(cells, {
+    onOperations: (value) => {
+      operations = value;
+    },
+  });
+  while (!work.next().done) units++;
+  assert.deepEqual(operations, {
+    densityVisits: 6144,
+    densityRetirementVisits: 6144,
+    densityMetadataBuilds: 0,
+    densityPositionBuilds: 0,
+    densityWrites: 0,
+    densityCreated: 0,
+    densityRemoved: 0,
+  });
+  assert.equal(units, Math.ceil(6144 / WILDLIFE_WORK_UNIT) * 2);
+  assert.equal(h.counts.positions, positions);
+  assert.equal(h.counts.writes, writes);
+  t.diagnostic(
+    `6,144 occupied cells: ${units} bounded units, 12,288 linear visits, zero warmed metadata/Cartesian builds, projections or billboard writes`,
+  );
+  h.density.destroy();
+});
diff --git a/src/layers/wildlifeSightings/docs.test.mjs b/src/layers/wildlifeSightings/docs.test.mjs
new file mode 100644
index 000000000..3f84357d3
--- /dev/null
+++ b/src/layers/wildlifeSightings/docs.test.mjs
@@ -0,0 +1,111 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { VOICE_OFF_LAYERS } from '../../voice/layerManifest.js';
+import { ANALYST_LAYERS } from '../../data/analystEngine.js';
+
+const read = (path) =>
+  readFileSync(new URL(`../../../${path}`, import.meta.url), 'utf8');
+const current = read('docs/CURRENT-STATE.md');
+const start = current.indexOf('## Wildlife Sightings —');
+const section = current
+  .slice(start, current.indexOf('\n## ', start + 1))
+  .replace(/\s+/g, ' ');
+
+test('Wildlife docs name the permanent token, voice policy and coverage limits', () => {
+  const token = JSON.parse(
+    read('src/data/layerStateTokenReservations.json'),
+  ).find(([id]) => id === 'wildlife-sightings')?.[1];
+  assert.ok(token);
+  assert.match(section, new RegExp(`share-link token \`${token}\``));
+  assert.match(section, /Voice is off for this layer for now/);
+  assert.ok(Object.hasOwn(VOICE_OFF_LAYERS, 'wildlife-sightings'));
+  assert.ok(!Object.hasOwn(ANALYST_LAYERS, 'wildlife-sightings'));
+  assert.match(section, /not a census/i);
+  assert.match(section, /Salish Sea/);
+  assert.match(section, /0\.01°/);
+  assert.match(section, /private records are excluded/);
+});
+
+test('Wildlife documentation defines recency by observation time and compact ambient credit', () => {
+  assert.match(section, /observation time/i);
+  assert.match(section, /\bd1\b/);
+  assert.match(section, /48 h/);
+  assert.match(section, /96 px/);
+  assert.match(section, /creator name/i);
+  assert.match(section, /110\/125 km/);
+  assert.match(section, /120 km/);
+  assert.match(section, /random sample/);
+  assert.match(section, /bounded frame cache/);
+  assert.match(read('DATA_SOURCES.md'), /observation time/i);
+});
+
+test('Wildlife docs describe direct photo selection and text-only privacy rows', () => {
+  assert.match(section, /compact anchored\s+photo card/);
+  assert.match(section, /object-fit: contain/);
+  assert.match(section, /preserving zoom/);
+  assert.match(section, /compact observed\s+age/);
+  assert.match(section, /Obscured sightings also stay\s+text-only/);
+  assert.match(section, /Acartia stays text-only/);
+  assert.match(section, /closes the card and clears selection/);
+  assert.match(
+    section,
+    /shell teardown also removes its host and subscription/,
+  );
+  assert.doesNotMatch(
+    section,
+    /opens\s+the \*\*Sighting\*\* panel|Clicking the panel photo/,
+  );
+});
+
+test('Wildlife docs record queue failure isolation and the complete badge mapping', () => {
+  assert.match(section, /recovered queue tail/);
+  assert.match(section, /ordinary grid failures/);
+  assert.match(section, /DEGRADED/);
+  assert.match(section, /1.5 px dark outline/);
+  for (const glyph of [
+    'raven',
+    'pets',
+    'egg_alt',
+    'water_drop',
+    'set_meal',
+    'bug_report',
+    'pest_control',
+    'eco',
+    'umbrella',
+    'category',
+    'question_mark',
+  ])
+    assert.ok(section.includes('`' + glyph + '`'), glyph);
+});
+
+test('Wildlife docs separate density from real observation icons and define persistent selection', () => {
+  assert.match(section, /dedicated, nonpickable billboard/);
+  assert.match(section, /view-relative density ramp/);
+  assert.match(section, /four logical cell widths/);
+  assert.match(
+    section,
+    /Only real sampled observation rows produce taxon badges/,
+  );
+  assert.match(
+    section,
+    /Grid tiles publish even while the independent observation/,
+  );
+  assert.match(section, /until explicit\s+deselection or layer disable/);
+  assert.match(
+    section,
+    /releases\s+the glow collection, texture atlas, timers, queues and style listeners/,
+  );
+  assert.doesNotMatch(section, /grid badge|Clicking a grid cell/);
+});
+
+test('Wildlife docs describe one source link, name declutter and globe glow limits', () => {
+  assert.match(section, /selected chrome and paint lane/);
+  assert.match(section, /single source link/);
+  assert.match(section, /80 screen pixels/);
+  assert.match(section, /word boundary/);
+  assert.match(section, /3,000 km/);
+  assert.match(section, /8,000 km/);
+  assert.match(section, /5% radius margin/);
+  assert.match(section, /add no per-frame work/);
+});
diff --git a/src/layers/wildlifeSightings/gridViewport.js b/src/layers/wildlifeSightings/gridViewport.js
new file mode 100644
index 000000000..0fdf421b0
--- /dev/null
+++ b/src/layers/wildlifeSightings/gridViewport.js
@@ -0,0 +1,178 @@
+// Observation icons share 28px screen buckets. The density glow uses finer
+// 8–14px logical cells, coarsened until the complete view fits the tile budget.
+export const WILDLIFE_GRID_TARGET_SPACING_PX = 28;
+export const WILDLIFE_GRID_SAMPLE_SPACING_PX = 14;
+export const WILDLIFE_GRID_TILE_CAP = 6;
+export const WILDLIFE_GRID_MAX_ZOOM = 22;
+// The 64×64 UTFGrid is a hit mask: each logical 8px observation bin
+// occupies 2×2 of its 4px pixels, plus a dilated hit outline. Returned centres
+// are at odd pixel coordinates. Count logical bins once, not hit-mask pixels.
+export const WILDLIFE_GRID_LOGICAL_SIZE = 32;
+const MAX_LATITUDE = 85.0511287798066;
+const degrees = (radians) => (radians * 180) / Math.PI;
+const latitudeY = (latitude) => {
+  const radians =
+    (Math.max(-MAX_LATITUDE, Math.min(MAX_LATITUDE, latitude)) * Math.PI) / 180;
+  return (1 - Math.asinh(Math.tan(radians)) / Math.PI) / 2;
+};
+const yLatitude = (value) =>
+  degrees(Math.atan(Math.sinh(Math.PI * (1 - 2 * value))));
+const validBox = (box) =>
+  !!box &&
+  ['south', 'west', 'north', 'east'].every((key) =>
+    Number.isFinite(box[key]),
+  ) &&
+  box.south >= -90 &&
+  box.north <= 90 &&
+  box.north > box.south &&
+  box.west >= -180 &&
+  box.west <= 180 &&
+  box.east >= -180 &&
+  box.east <= 180 &&
+  box.west !== box.east;
+
+function normalizedBoxes(boxes) {
+  if (!Array.isArray(boxes) || !boxes.length || !boxes.every(validBox))
+    return [];
+  return boxes
+    .flatMap((box) =>
+      box.west < box.east
+        ? [box]
+        : [
+            { ...box, east: 180 },
+            { ...box, west: -180 },
+          ],
+    )
+    .filter((box) => box.east > box.west);
+}
+
+function tileRanges(boxes, z) {
+  const count = 2 ** z;
+  const index = (value) => Math.max(0, Math.min(count - 1, Math.floor(value)));
+  return normalizedBoxes(boxes).map((box) => ({
+    left: index(((box.west + 180) / 360) * count),
+    right: index(((box.east + 180) / 360) * count - 1e-9),
+    top: index(latitudeY(box.north) * count),
+    bottom: index(latitudeY(box.south) * count - 1e-9),
+  }));
+}
+
+function tileCount(boxes, z) {
+  // Split antimeridian ranges cannot overlap except at z=0. Counting that
+  // shared tile twice merely makes the request cap slightly conservative.
+  return tileRanges(boxes, z).reduce(
+    (sum, range) =>
+      sum + (range.right - range.left + 1) * (range.bottom - range.top + 1),
+    0,
+  );
+}
+
+/** Choose the finest glow spacing whose full viewport fits the tile budget. */
+export function chooseWildlifeGridZoom({ boxes, width, height } = {}) {
+  const visible = normalizedBoxes(boxes);
+  if (!visible.length || !(width > 0) || !(height > 0)) return 0;
+  const horizontalSpan = Math.min(
+    1,
+    visible.reduce((sum, box) => sum + (box.east - box.west) / 360, 0),
+  );
+  const verticalSpan = Math.max(
+    ...visible.map((box) => latitudeY(box.south) - latitudeY(box.north)),
+  );
+  const pixelsPerWorld = Math.min(
+    width / horizontalSpan,
+    height / Math.max(1e-9, verticalSpan),
+  );
+  let z = Math.max(
+    0,
+    Math.min(
+      WILDLIFE_GRID_MAX_ZOOM,
+      Math.ceil(
+        Math.log2(
+          pixelsPerWorld /
+            (WILDLIFE_GRID_LOGICAL_SIZE * WILDLIFE_GRID_SAMPLE_SPACING_PX),
+        ) - 1e-9,
+      ),
+    ),
+  );
+  while (z > 0 && tileCount(visible, z) > WILDLIFE_GRID_TILE_CAP) z -= 1;
+  return z;
+}
+
+/** Only intersecting tiles, in stable XYZ order, with no neighboring padding.
+ * Direct oversized requests fail closed; zoom selection coarsens beforehand. */
+export function wildlifeGridTiles({ boxes, z } = {}) {
+  if (!Number.isInteger(z) || z < 0 || z > WILDLIFE_GRID_MAX_ZOOM) return [];
+  if (tileCount(boxes, z) > WILDLIFE_GRID_TILE_CAP) return [];
+  const tiles = new Map();
+  for (const range of tileRanges(boxes, z)) {
+    for (let x = range.left; x <= range.right; x += 1) {
+      for (let y = range.top; y <= range.bottom; y += 1) {
+        tiles.set(`${x}/${y}`, { z, x, y });
+      }
+    }
+  }
+  return [...tiles.values()].sort((a, b) => a.x - b.x || a.y - b.y);
+}
+
+/** Unlike detail-row viewport queries, grids cover full globe views too. */
+export function wildlifeGridViewportBoxes(viewer) {
+  const rectangle = viewer?.camera?.computeViewRectangle?.(
+    viewer?.scene?.globe?.ellipsoid,
+  );
+  if (!rectangle) return [];
+  return normalizedBoxes([
+    Object.fromEntries(
+      ['south', 'west', 'north', 'east'].map((key) => [
+        key,
+        Math.round(degrees(rectangle[key]) * 1e8) / 1e8,
+      ]),
+    ),
+  ]);
+}
+
+/** Return the geographic footprint of one logical occupied cell. */
+export function wildlifeGridCellBounds(id) {
+  const match = /^grid:(\d+)\/(\d+)\/(\d+):(\d+):(\d+)$/.exec(id);
+  if (!match) return null;
+  const [z, x, y, row, column] = match.slice(1).map(Number);
+  const count = 2 ** z;
+  if (
+    z > WILDLIFE_GRID_MAX_ZOOM ||
+    x >= count ||
+    y >= count ||
+    row >= 64 ||
+    column >= 64
+  )
+    return null;
+  return {
+    south: yLatitude((y + (Math.floor(row / 2) + 1) / 32) / count),
+    west: ((x + Math.floor(column / 2) / 32) / count) * 360 - 180,
+    north: yLatitude((y + Math.floor(row / 2) / 32) / count),
+    east: ((x + (Math.floor(column / 2) + 1) / 32) / count) * 360 - 180,
+  };
+}
+
+/** Shared with the proxy and cached-coverage matching. A tile's hit area can
+ * bleed into its neighbor; the geographic owner makes ids stable. */
+export function wildlifeGridCellId(lat, lon, z) {
+  if (
+    !Number.isFinite(lat) ||
+    Math.abs(lat) > 90 ||
+    !Number.isFinite(lon) ||
+    Math.abs(lon) > 180 ||
+    !Number.isInteger(z) ||
+    z < 0 ||
+    z > WILDLIFE_GRID_MAX_ZOOM
+  )
+    return null;
+  const count = 2 ** z;
+  const worldX = ((((lon + 180) / 360) % 1) + 1) % 1;
+  const worldY = Math.max(0, Math.min(1 - Number.EPSILON, latitudeY(lat)));
+  const tileX = Math.min(count - 1, Math.floor(worldX * count));
+  const tileY = Math.min(count - 1, Math.floor(worldY * count));
+  const column =
+    Math.min(31, Math.floor((worldX * count - tileX) * 32 + 1e-8)) * 2 + 1;
+  const row =
+    Math.min(31, Math.floor((worldY * count - tileY) * 32 + 1e-8)) * 2 + 1;
+  return `grid:${z}/${tileX}/${tileY}:${row}:${column}`;
+}
diff --git a/src/layers/wildlifeSightings/gridViewport.test.mjs b/src/layers/wildlifeSightings/gridViewport.test.mjs
new file mode 100644
index 000000000..a1b843510
--- /dev/null
+++ b/src/layers/wildlifeSightings/gridViewport.test.mjs
@@ -0,0 +1,142 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  chooseWildlifeGridZoom,
+  wildlifeGridTiles,
+  wildlifeGridViewportBoxes,
+  wildlifeGridCellBounds,
+  wildlifeGridCellId,
+  WILDLIFE_GRID_LOGICAL_SIZE,
+  WILDLIFE_GRID_TILE_CAP,
+} from './gridViewport.js';
+
+const globe = [
+  { south: -85.0511287798066, west: -180, north: 85.0511287798066, east: 180 },
+];
+const regional = [{ south: 0, west: 0, north: 40.979898069620134, east: 45 }];
+
+test('glow sampling uses roughly 8–14px cells independently of the 28px icon buckets', () => {
+  for (const [boxes, width, height, expected] of [
+    [globe, 448, 448, 0],
+    [regional, 448, 448, 3],
+    [
+      [{ south: 0, west: 0, north: 0.08789059053082508, east: 0.087890625 }],
+      448,
+      448,
+      12,
+    ],
+  ]) {
+    const zoom = chooseWildlifeGridZoom({ boxes, width, height });
+    assert.equal(zoom, expected);
+    const worldPixels = (width * 360) / (boxes[0].east - boxes[0].west);
+    const spacing = worldPixels / 2 ** zoom / WILDLIFE_GRID_LOGICAL_SIZE;
+    assert.ok(spacing >= 8 && spacing <= 14, `${zoom}: ${spacing}px`);
+    assert.ok(
+      wildlifeGridTiles({ boxes, z: zoom }).length <= WILDLIFE_GRID_TILE_CAP,
+    );
+  }
+});
+
+test('the named six-tile budget preserves complete coverage for common views', () => {
+  for (const [boxes, width, height, expected] of [
+    [globe, 896, 896, 1],
+    [regional, 896, 896, 4],
+    [[{ south: 7, west: -168, north: 72, east: -48 }], 1400, 900, 2],
+    [globe, 4000, 4000, 1],
+    [globe, 30_000, 400, 0],
+  ]) {
+    const z = chooseWildlifeGridZoom({ boxes, width, height });
+    assert.equal(z, expected);
+    const tiles = wildlifeGridTiles({ boxes, z });
+    assert.ok(tiles.length > 0 && tiles.length <= WILDLIFE_GRID_TILE_CAP);
+  }
+});
+
+test('tile ranges contain only intersecting tiles, no offscreen neighbors or duplicate boundary tiles', () => {
+  assert.deepEqual(wildlifeGridTiles({ boxes: regional, z: 3 }), [
+    { z: 3, x: 4, y: 3 },
+  ]);
+  assert.deepEqual(wildlifeGridTiles({ boxes: globe, z: 0 }), [
+    { z: 0, x: 0, y: 0 },
+  ]);
+  const crossing = [{ south: 10, west: 179, north: 12, east: -178 }];
+  const split = [
+    { south: 10, west: 179, north: 12, east: 180 },
+    { south: 10, west: -180, north: 12, east: -178 },
+  ];
+  const z = chooseWildlifeGridZoom({
+    boxes: crossing,
+    width: 896,
+    height: 600,
+  });
+  assert.deepEqual(
+    wildlifeGridTiles({ boxes: crossing, z }),
+    wildlifeGridTiles({ boxes: split, z }),
+  );
+  assert.ok(
+    wildlifeGridTiles({ boxes: crossing, z }).every(
+      (tile) =>
+        ((tile.x + 1) / 2 ** z) * 360 - 180 > 179 ||
+        (tile.x / 2 ** z) * 360 - 180 < -178,
+    ),
+  );
+});
+
+test('tile cap degrades zoom to preserve complete coverage and oversized direct requests fail closed', () => {
+  const z = chooseWildlifeGridZoom({
+    boxes: globe,
+    width: 30_000,
+    height: 400,
+  });
+  assert.ok(
+    wildlifeGridTiles({ boxes: globe, z }).length <= WILDLIFE_GRID_TILE_CAP,
+  );
+  assert.deepEqual(wildlifeGridTiles({ boxes: globe, z: 12 }), []);
+  assert.equal(chooseWildlifeGridZoom({ boxes: [], width: 0, height: 0 }), 0);
+  assert.deepEqual(wildlifeGridTiles({ boxes: [], z: 2 }), []);
+});
+
+test('grid camera viewport supports globe and antimeridian without detail-query degree limits', () => {
+  const radians = (value) => (value * Math.PI) / 180;
+  const viewer = {
+    camera: {
+      computeViewRectangle: () => ({
+        south: radians(-80),
+        west: radians(120),
+        north: radians(80),
+        east: radians(-120),
+      }),
+    },
+  };
+  const boxes = wildlifeGridViewportBoxes(viewer);
+  assert.equal(boxes.length, 2);
+  assert.ok(Math.abs(boxes[0].west - 120) < 1e-8);
+  assert.equal(boxes[0].east, 180);
+  assert.equal(boxes[1].west, -180);
+  assert.deepEqual(wildlifeGridViewportBoxes({}), []);
+});
+
+test('logical cell ids and bounds share geographic coverage and wrap antimeridian', () => {
+  const id = wildlifeGridCellId(65.94004866768753, -18.28125, 2);
+  assert.equal(id, 'grid:2/1/1:1:51');
+  const bounds = wildlifeGridCellBounds(id);
+  assert.equal(bounds.west, -19.6875);
+  assert.equal(bounds.east, -16.875);
+  assert.ok(bounds.south < 65.94 && bounds.north > 65.94);
+  assert.equal(
+    wildlifeGridCellId(
+      (bounds.south + bounds.north) / 2,
+      (bounds.west + bounds.east) / 2,
+      2,
+    ),
+    id,
+  );
+  assert.equal(wildlifeGridCellId(0, 180, 2), wildlifeGridCellId(0, -180, 2));
+  for (const invalid of [
+    'bad',
+    'grid:23/0/0:1:1',
+    'grid:2/4/0:1:1',
+    'grid:2/0/0:64:1',
+  ])
+    assert.equal(wildlifeGridCellBounds(invalid), null);
+});
diff --git a/src/layers/wildlifeSightings/index.js b/src/layers/wildlifeSightings/index.js
new file mode 100644
index 000000000..75cedb093
--- /dev/null
+++ b/src/layers/wildlifeSightings/index.js
@@ -0,0 +1,130 @@
+import * as Cesium from 'cesium';
+import { horizonOccluder } from '../../data/iconOrientation.js';
+import { createPhotoSlots } from './photos.js';
+import { createRendering } from './rendering.js';
+import { createSelection } from './selection.js';
+import { createControls } from './controls.js';
+import { createLifecycle } from './lifecycle.js';
+
+/** Compose recent wildlife observations without acquiring data at construction. */
+export function createWildlifeSightingsLayer({
+  source,
+  overlayHost = null,
+  screenSpaceEventHandlerFactory = null,
+  picking = null,
+  pointer = null,
+  sprites = null,
+  badgeSprites = null,
+  render = null,
+  context = null,
+  focus = null,
+  groundFloor = null,
+  now = () => Date.now(),
+  setTimer = (fn, delay) => setTimeout(fn, delay),
+  clearTimer = (timer) => clearTimeout(timer),
+  requestIdleCallback,
+  cancelIdleCallback,
+  imageFactory,
+  eventTarget = globalThis.window,
+  cesium = Cesium,
+  project = (scene, position) =>
+    Cesium.SceneTransforms.worldToWindowCoordinates(scene, position),
+  occluderFactory = horizonOccluder,
+} = {}) {
+  if (typeof source?.getSnapshot !== 'function')
+    throw new TypeError('Wildlife sightings require a snapshot source');
+  const state = {
+    viewer: null,
+    enabled: false,
+    destroyed: false,
+    manager: null,
+    request: null,
+    background: null,
+    cameraTimer: null,
+    removeCamera: null,
+    removeContext: null,
+    clickHandler: null,
+    rows: new Map(),
+    renderedRows: [],
+    rowById: new Map(),
+    points: null,
+    pointById: new Map(),
+    positions: new Map(),
+    cells: [],
+    staging: null,
+    selectedId: null,
+    selectedRow: null,
+    carriers: new Map(),
+    contextIds: new Set(),
+    publishingContext: false,
+    ambientIds: [],
+    ambientRows: [],
+    confirmed: false,
+    taxa: 'all',
+    drawnParams: null,
+    pendingParams: null,
+    failedParams: null,
+    controlsListener: null,
+    lastUpdate: null,
+    error: null,
+    stale: false,
+    loading: false,
+    gridCells: [],
+    gridParams: null,
+    gridAvailable: false,
+    gridTotal: 0,
+    labelRows: [],
+    query: null,
+    band: null,
+    lastQueryKey: null,
+    retryAt: 0,
+    failures: 0,
+  };
+  const parts = {};
+  const services = {
+    source,
+    overlayHost,
+    screenSpaceEventHandlerFactory,
+    picking,
+    pointer,
+    sprites,
+    badgeSprites,
+    render,
+    context,
+    focus,
+    groundFloor,
+    now,
+    setTimer,
+    clearTimer,
+    requestIdleCallback,
+    cancelIdleCallback,
+    eventTarget,
+    cesium,
+    project,
+    occluderFactory,
+  };
+  const owner = { state, services, parts };
+  parts.photos = createPhotoSlots({
+    imageFactory,
+    now,
+    setTimer,
+    clearTimer,
+    onChange() {
+      if (!state.enabled) return;
+      parts.selection.publishAmbient();
+    },
+  });
+  parts.rendering = createRendering(owner);
+  parts.selection = createSelection(owner);
+  parts.controls = createControls(owner);
+  parts.lifecycle = createLifecycle(owner);
+  return Object.assign({}, parts.controls.methods, parts.lifecycle.methods, {
+    selectSighting: parts.selection.selectAndFocus,
+    clearSightingSelection: parts.selection.clearAndRebuild,
+    subscribeSelection: parts.selection.subscribe,
+    /** Return the current surface anchor for a retained observation. */
+    getSightingPosition(id) {
+      return state.positions.get(id) || null;
+    },
+  });
+}
diff --git a/src/layers/wildlifeSightings/lifecycle.js b/src/layers/wildlifeSightings/lifecycle.js
new file mode 100644
index 000000000..e092a6ef1
--- /dev/null
+++ b/src/layers/wildlifeSightings/lifecycle.js
@@ -0,0 +1,804 @@
+import { msg } from '../../i18n/marker.js';
+import { getWildlifeHeightBand, rowInWildlifeBoxes } from './model.js';
+import { combineWildlifeGridSnapshots } from './source.js';
+import { wildlifeMeasure } from './performance.js';
+import { isRecentWildlifeSighting } from './records.js';
+import {
+  wildlifeGridViewportBoxes,
+  chooseWildlifeGridZoom,
+  wildlifeGridTiles,
+  wildlifeGridCellId,
+} from './gridViewport.js';
+import {
+  wildlifeViewportBoxes,
+  snapWildlifeBox,
+  retryDelayMs,
+} from './viewport.js';
+import {
+  WILDLIFE_DEBOUNCE_MS,
+  WILDLIFE_MAX_ROWS,
+  WILDLIFE_GRID_HEIGHT_METERS,
+} from './policy.js';
+
+/** Manager-owned acquisition with camera debounce and guarded transactions. */
+export function createLifecycle({ state, services, parts }) {
+  let requestQueryKey = null;
+  let removeManagerListener = null;
+  let lifetimeEpoch = 0;
+  let initialCameraDeadline = 0;
+  let initialSettle = null;
+  // The manager invokes update immediately after enable. Settle startup camera
+  // events before dispatching anything, then acquire only the resulting view.
+  const INITIAL_CAMERA_SETTLE_MS = 300;
+
+  function settleInitialCamera(signal) {
+    if (!initialCameraDeadline || services.now() >= initialCameraDeadline) {
+      initialCameraDeadline = 0;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const finish = () => {
+        services.clearTimer(state.cameraTimer);
+        state.cameraTimer = null;
+        initialSettle = null;
+        initialCameraDeadline = 0;
+        signal?.removeEventListener('abort', finish);
+        resolve();
+      };
+      initialSettle = {
+        schedule() {
+          services.clearTimer(state.cameraTimer);
+          state.cameraTimer = services.setTimer(
+            finish,
+            Math.max(0, initialCameraDeadline - services.now()),
+          );
+        },
+        finish,
+      };
+      signal?.addEventListener('abort', finish, { once: true });
+      initialSettle.schedule();
+    });
+  }
+
+  function renderBatch(fn) {
+    parts.rendering.beginBatch?.();
+    try {
+      return fn();
+    } finally {
+      parts.rendering.endBatch?.();
+    }
+  }
+
+  function clearPending() {
+    if (!state.pendingParams) return;
+    if (state.error) state.failedParams = state.pendingParams;
+    state.pendingParams = null;
+    parts.controls.notify();
+  }
+
+  function failParams(params) {
+    // An acquisition can fail during an ordinary refresh, when no option is
+    // pending. Keep the chosen taxa visible and retryable in that case too.
+    state.failedParams = {
+      ...params,
+      keys: [
+        ...new Set([
+          ...(state.pendingParams?.keys || []),
+          'taxa',
+          ...(params.confirmed ? ['confirmed'] : []),
+        ]),
+      ],
+    };
+    state.pendingParams = null;
+  }
+
+  function applyRetry(error, retryAfterSec = null) {
+    // Only upstream failures impose cooldown; network/schema errors retry on pan.
+    const status =
+      error?.upstreamStatus ??
+      error?.status ??
+      Number(/HTTP (\d{3})/.exec(error?.message || '')?.[1]);
+    const retryDelays = [error?.retryAfterSec, retryAfterSec].filter(
+      (value) => Number.isFinite(value) && value >= 0,
+    );
+    const retryFromSnapshot =
+      Number.isFinite(retryAfterSec) && retryAfterSec >= 0;
+    if (!(status === 429 || status >= 500) && !retryFromSnapshot) {
+      state.failures = 0;
+      state.retryAt = 0;
+      return;
+    }
+    const backoff = retryDelays.length
+      ? Math.max(...retryDelays) * 1000
+      : retryDelayMs(state.failures || 0);
+    state.failures = backoff;
+    state.retryAt = services.now() + backoff;
+  }
+
+  function pageHidden() {
+    return (
+      services.eventTarget?.document?.hidden || globalThis.document?.hidden
+    );
+  }
+
+  function currentQuery() {
+    const height = state.viewer?.camera?.positionCartographic?.height;
+    state.band = getWildlifeHeightBand(height ?? Infinity, state.band);
+    const boxes =
+      state.band === 'global'
+        ? null
+        : wildlifeViewportBoxes(state.viewer)?.map((box) =>
+            snapWildlifeBox(box),
+          );
+    const visibleBoxes = wildlifeGridViewportBoxes(state.viewer);
+    const scope =
+      state.band === 'global' ||
+      (!boxes && (height ?? Infinity) > WILDLIFE_GRID_HEIGHT_METERS)
+        ? 'global'
+        : 'view';
+    if (scope === 'view' && (!boxes?.length || boxes.some((box) => !box)))
+      return null;
+    const baseKey = JSON.stringify([
+      scope,
+      scope === 'global' ? null : boxes,
+      state.confirmed,
+      state.taxa,
+    ]);
+    const canvas = state.viewer?.scene?.canvas;
+    const zoom = visibleBoxes?.length
+      ? chooseWildlifeGridZoom({
+          boxes: visibleBoxes,
+          width: canvas?.clientWidth || 1400,
+          height: canvas?.clientHeight || 900,
+        })
+      : 0;
+    const tiles = visibleBoxes?.length
+      ? wildlifeGridTiles({ boxes: visibleBoxes, z: zoom })
+      : [];
+    return {
+      scope,
+      boxes: scope === 'global' ? null : boxes,
+      visibleBoxes,
+      tiles,
+      key: JSON.stringify([baseKey, tiles]),
+    };
+  }
+
+  function refreshView() {
+    const query = currentQuery();
+    const superseded = state.query?.key !== query?.key;
+    state.query = query;
+    if (superseded) {
+      state.request?.abort();
+      state.background?.abort();
+    }
+    // Keep the previous validated display while changing filters. Its rows
+    // and parameter chips are replaced together when acquisition succeeds.
+    renderBatch(() => {
+      const pending =
+        !state.pendingClear && parts.rendering.rebuild() === 'pending';
+      parts.rendering.cull();
+      if (pending) return;
+      parts.selection.refreshAmbient();
+      parts.selection.refreshContexts();
+      parts.selection.syncCredits();
+    });
+    return query;
+  }
+
+  async function refresh() {
+    if (!state.enabled || pageHidden()) {
+      clearPending();
+      return;
+    }
+    const controller = new AbortController();
+    const pendingParams = state.pendingParams;
+    state.background?.abort();
+    state.background = controller;
+    try {
+      if (state.manager)
+        await state.manager.refreshLayer('wildlife-sightings', {
+          signal: controller.signal,
+        });
+      else await methods.update(undefined, { signal: controller.signal });
+    } catch {
+      // update exposes expected source errors through stats; manager failures
+      // already have their own normalized status path.
+    } finally {
+      if (state.background === controller) {
+        state.background = null;
+        // A manager may decline acquisition while it is enabling, or the view
+        // may disappear before update. Only queued/in-flight work is busy.
+        if (
+          state.pendingParams === pendingParams &&
+          !state.loading &&
+          state.cameraTimer == null
+        )
+          clearPending();
+      }
+    }
+  }
+
+  function scheduleRefresh() {
+    services.clearTimer(state.cameraTimer);
+    state.cameraTimer = null;
+    if (!state.enabled || pageHidden()) {
+      clearPending();
+      return;
+    }
+    if (initialSettle) {
+      initialSettle.schedule();
+      return;
+    }
+    const query = currentQuery();
+    if (!query || query.key === state.lastQueryKey) {
+      clearPending();
+      return;
+    }
+    if (
+      query.key === requestQueryKey &&
+      state.request &&
+      !state.request.signal.aborted
+    )
+      return;
+    state.cameraTimer = services.setTimer(
+      () => {
+        state.cameraTimer = null;
+        if (!state.enabled || pageHidden()) {
+          clearPending();
+          return;
+        }
+        const query = currentQuery();
+        if (!query || query.key === state.lastQueryKey) {
+          clearPending();
+          return;
+        }
+        if (
+          query.key === requestQueryKey &&
+          state.request &&
+          !state.request.signal.aborted
+        )
+          return;
+        if (services.now() < state.retryAt) {
+          scheduleRefresh();
+          return;
+        }
+        void refresh();
+      },
+      Math.max(WILDLIFE_DEBOUNCE_MS, state.retryAt - services.now()),
+    );
+  }
+
+  function applyAccepted({
+    snapshot,
+    grid,
+    gridError,
+    query,
+    params,
+    request,
+    signal,
+    epoch,
+    replaceRows = true,
+  }) {
+    const current = currentQuery();
+    if (
+      !state.enabled ||
+      state.destroyed ||
+      epoch !== lifetimeEpoch ||
+      request.signal.aborted ||
+      signal?.aborted ||
+      params.taxa !== state.taxa ||
+      params.confirmed !== state.confirmed ||
+      current?.key !== query.key
+    )
+      return;
+    renderBatch(() => {
+      const sameParams =
+        params.taxa === state.drawnParams?.taxa &&
+        params.confirmed === state.drawnParams?.confirmed;
+      const gridParams = state.gridParams || state.drawnParams;
+      const sameGridParams =
+        params.taxa === gridParams?.taxa &&
+        params.confirmed === gridParams?.confirmed;
+      // Tiles may beat a slow observation page. Publish their density without
+      // replacing observations or claiming their filter transaction succeeded.
+      // A pending filter keeps its previous display until both paths agree.
+      if (!snapshot) {
+        if (state.drawnParams && !sameParams) return;
+        if (grid) {
+          state.gridCells = grid.cells || [];
+          state.gridParams = params;
+          state.gridAvailable = true;
+          state.gridTotal = grid.totalResults || 0;
+          if (state.lastUpdate == null)
+            state.lastUpdate = Number.isFinite(grid.fetchedAt)
+              ? grid.fetchedAt
+              : services.now();
+          const pendingRender = parts.rendering.rebuild() === 'pending';
+          if (!pendingRender) {
+            parts.selection.refreshAmbient();
+            parts.selection.publishSelected();
+            parts.selection.refreshContexts();
+            parts.selection.syncCredits();
+          }
+          parts.controls.notify();
+        }
+        return;
+      }
+      if (replaceRows) {
+        if (state.selectedId && !state.selectedRow)
+          state.selectedRow =
+            state.rowById.get(state.selectedId) ||
+            state.rows.get(state.selectedId) ||
+            null;
+        const retainedRows = sameParams
+          ? (parts.selection.retainedAmbientRows?.() || []).filter(
+              (row) =>
+                state.rows.has(row.stableId) &&
+                isRecentWildlifeSighting(row, services.now(), params.taxa),
+            )
+          : [];
+        const retainedIds = new Set(retainedRows.map((row) => row.stableId));
+        if (state.selectedRow) retainedIds.add(state.selectedRow.stableId);
+        if (state.pendingClear || state.loadedScope !== query.scope)
+          state.rows.clear();
+        state.loadedScope = query.scope;
+        state.pendingClear = false;
+        // A successful page replaces this queried area, including a healthy
+        // empty page. Keep only other visited areas in the bounded LRU.
+        for (const [id, row] of state.rows) {
+          if (rowInWildlifeBoxes(row, query.boxes, 0)) state.rows.delete(id);
+        }
+        for (const row of snapshot.rows) {
+          state.rows.delete(row.stableId);
+          state.rows.set(row.stableId, row);
+          if (row.stableId === state.selectedId) state.selectedRow = row;
+        }
+        // Selection owns a real observation until explicit deselection. It is
+        // independent of sample/window/filter and ambient-card eligibility.
+        if (state.selectedRow && !state.rows.has(state.selectedId))
+          state.rows.set(state.selectedId, state.selectedRow);
+        // Random samples may omit a photograph already displayed. Its bounded
+        // incumbent row stays selectable until the card leaves the view/window.
+        for (const row of retainedRows) {
+          if (!state.rows.has(row.stableId)) state.rows.set(row.stableId, row);
+        }
+        if (state.rows.size > WILDLIFE_MAX_ROWS) {
+          for (const id of state.rows.keys()) {
+            if (!retainedIds.has(id)) state.rows.delete(id);
+            if (state.rows.size <= WILDLIFE_MAX_ROWS) break;
+          }
+        }
+        if (state.rows.size > WILDLIFE_MAX_ROWS) {
+          for (const id of state.rows.keys()) {
+            if (id !== state.selectedId) state.rows.delete(id);
+            if (state.rows.size <= WILDLIFE_MAX_ROWS) break;
+          }
+        }
+      }
+      const failedStale = [snapshot, grid].filter(
+        (value) =>
+          value?.stale === true &&
+          Number.isFinite(value.retryAfterSec) &&
+          (value.upstreamStatus === undefined ||
+            value.upstreamStatus === 429 ||
+            value.upstreamStatus >= 500),
+      );
+      const staleError = failedStale.length
+        ? Object.assign(
+            new Error(msg('Wildlife sightings source unavailable')),
+            {
+              retryAfterSec: Math.max(
+                ...failedStale.map((value) => value.retryAfterSec),
+              ),
+            },
+          )
+        : null;
+      const sourceError =
+        gridError ||
+        staleError ||
+        (snapshot.sources?.acartia?.ok === false
+          ? new Error(msg('Acartia feed unavailable'))
+          : null);
+      state.stale =
+        !sourceError && (snapshot.stale === true || grid?.stale === true);
+      const fetchedAt = [snapshot.fetchedAt, grid?.fetchedAt].filter(
+        Number.isFinite,
+      );
+      state.lastUpdate =
+        (snapshot.stale === true || grid?.stale === true) && fetchedAt.length
+          ? Math.min(...fetchedAt)
+          : services.now();
+      state.error = sourceError?.message || null;
+      state.drawnParams = params;
+      const retryAfter = [snapshot, grid]
+        .filter(
+          (value) =>
+            value &&
+            (value.upstreamStatus === undefined ||
+              value.upstreamStatus === 429 ||
+              value.upstreamStatus >= 500),
+        )
+        .map((value) => value.retryAfterSec)
+        .filter(Number.isFinite);
+      if (sourceError) {
+        failParams(params);
+        applyRetry(
+          sourceError,
+          retryAfter.length ? Math.max(...retryAfter) : null,
+        );
+      } else {
+        state.pendingParams = null;
+        state.failedParams = null;
+        state.retryAt = retryAfter.length
+          ? services.now() + Math.max(...retryAfter) * 1000
+          : 0;
+        state.failures = 0;
+      }
+      state.query = currentQuery();
+      if (grid !== undefined || !sameGridParams) {
+        state.gridCells = grid?.cells || [];
+        state.gridParams = grid ? params : null;
+        state.gridAvailable = !!grid;
+        state.gridTotal = grid?.totalResults || 0;
+      }
+      const pendingRender = parts.rendering.rebuild() === 'pending';
+      if (pendingRender) {
+        state.lastQueryKey = sourceError ? null : state.query?.key || query.key;
+        parts.controls.notify();
+        return;
+      }
+      parts.selection.refreshAmbient();
+      parts.selection.publishSelected();
+      parts.selection.notify();
+      parts.selection.refreshContexts();
+      parts.selection.syncCredits();
+      state.lastQueryKey = sourceError ? null : state.query?.key || query.key;
+      parts.controls.notify();
+    });
+  }
+
+  function disable() {
+    lifetimeEpoch += 1;
+    initialSettle?.finish();
+    initialCameraDeadline = 0;
+    state.enabled = false;
+    services.clearTimer(state.cameraTimer);
+    state.cameraTimer = null;
+    state.request?.abort();
+    state.request = null;
+    requestQueryKey = null;
+    state.background?.abort();
+    state.background = null;
+    state.loading = false;
+    clearPending();
+    state.removeCamera?.();
+    state.removeCamera = null;
+    parts.rendering.deactivate?.();
+    removeManagerListener?.();
+    removeManagerListener = null;
+    parts.selection.remove();
+    services.picking?.unregisterPickOwner?.('wildlife-sightings');
+    parts.rendering.clear();
+    parts.photos.clear();
+    parts.controls.notify();
+    parts.rendering.requestRender('disable');
+    return true;
+  }
+
+  const methods = {
+    /** Attach this layer's Cesium resources to one viewer. */
+    init(viewer, { signal } = {}) {
+      if (state.viewer)
+        throw new Error('Wildlife sightings layer is already initialized');
+      if (state.destroyed || signal?.aborted) return false;
+      state.viewer = viewer;
+      parts.rendering.init();
+      return true;
+    },
+    /** Show retained observations and acquire the settled camera view. */
+    enable(_viewer, { signal } = {}) {
+      if (state.destroyed || signal?.aborted) return false;
+      if (!state.viewer)
+        throw new Error('Wildlife sightings layer must be initialized');
+      if (state.enabled) return true;
+      state.enabled = true;
+      initialCameraDeadline = services.now() + INITIAL_CAMERA_SETTLE_MS;
+      parts.rendering.activate?.();
+      state.points.show = true;
+      refreshView();
+      for (const id of parts.selection.sourceIds)
+        services.overlayHost?.setVisible?.(id, true);
+      parts.selection.install();
+      services.picking?.registerPickOwner?.(
+        'wildlife-sightings',
+        (id) =>
+          typeof id === 'string' &&
+          id.startsWith('wildlife:') &&
+          state.rowById.has(id.slice(9)),
+      );
+      state.removeCamera = state.viewer.camera?.moveEnd?.addEventListener?.(
+        () => {
+          if (!state.enabled) return;
+          wildlifeMeasure('moveEnd', () => {
+            if (
+              initialCameraDeadline &&
+              services.now() < initialCameraDeadline
+            ) {
+              initialCameraDeadline = services.now() + INITIAL_CAMERA_SETTLE_MS;
+              refreshView();
+              initialSettle?.schedule();
+            } else {
+              refreshView();
+              scheduleRefresh();
+            }
+            parts.controls.notify();
+          });
+        },
+      );
+      // A debounce can expire while the manager is still enabling and cannot
+      // accept refreshLayer yet. Its settled visibility event is the one
+      // catch-up edge; completed initial queries are skipped by their key.
+      removeManagerListener =
+        state.manager?.subscribe?.((change) => {
+          if (
+            change.type === 'visibility' &&
+            change.layerId === 'wildlife-sightings' &&
+            change.enabled === true &&
+            state.enabled
+          )
+            scheduleRefresh();
+        }) || null;
+      if (services.sprites?.restoreSpriteOrderOnEnable)
+        services.sprites.restoreSpriteOrderOnEnable(
+          'wildlife-sightings',
+          state.viewer,
+        );
+      else services.sprites?.restoreSpriteOrder?.(state.viewer);
+      return true;
+    },
+    /** Refresh observations and density independently for the current filters. */
+    async update(_viewer, { signal } = {}) {
+      if (
+        !state.enabled ||
+        !state.points ||
+        state.destroyed ||
+        signal?.aborted
+      ) {
+        if (!state.request) clearPending();
+        return false;
+      }
+      if (initialCameraDeadline && services.now() < initialCameraDeadline)
+        await settleInitialCamera(signal);
+      initialCameraDeadline = 0;
+      if (!state.enabled || state.destroyed || signal?.aborted) return false;
+      const query = currentQuery();
+      state.query = query;
+      if (!query || pageHidden()) {
+        clearPending();
+        return true;
+      }
+      if (services.now() < state.retryAt) {
+        if (state.pendingParams && state.cameraTimer == null) scheduleRefresh();
+        return true;
+      }
+      if (
+        requestQueryKey === query.key &&
+        state.request &&
+        !state.request.signal.aborted
+      )
+        return true;
+      state.request?.abort();
+      const request = new AbortController();
+      const requestLifetime = lifetimeEpoch;
+      const supersededResult = () =>
+        state.enabled &&
+        !state.destroyed &&
+        lifetimeEpoch === requestLifetime &&
+        !signal?.aborted;
+      state.request = request;
+      requestQueryKey = query.key;
+      const onAbort = () => request.abort(signal.reason);
+      signal?.addEventListener?.('abort', onAbort, { once: true });
+      const params = { confirmed: state.confirmed, taxa: state.taxa };
+      state.loading = true;
+      if (!state.pendingParams) {
+        const drawn = state.drawnParams || { confirmed: false, taxa: null };
+        const keys = ['confirmed', 'taxa'].filter(
+          (key) => params[key] !== drawn[key],
+        );
+        if (keys.length) state.pendingParams = { ...params, keys };
+      }
+      parts.controls.notify();
+      let received = false;
+      let gridPending = false;
+      let acceptedSnapshot = null;
+      let gridRequest = null;
+      let gridResult = null;
+      const tileSnapshots = new Map();
+      const gridParams = state.gridParams || state.drawnParams;
+      const retainedGrid =
+        params.taxa === gridParams?.taxa &&
+        params.confirmed === gridParams?.confirmed
+          ? state.gridCells || []
+          : [];
+      function aggregateTiles(complete = false) {
+        if (!tileSnapshots.size) return undefined;
+        const grid = combineWildlifeGridSnapshots([...tileSnapshots.values()]);
+        if (!complete && retainedGrid.length) {
+          const zoom = query.tiles[0]?.z;
+          const covered = new Set(tileSnapshots.keys());
+          const retained = retainedGrid.filter(
+            (cell) =>
+              !covered.has(
+                wildlifeGridCellId(cell.lat, cell.lon, zoom)?.split(':')[1],
+              ),
+          );
+          return combineWildlifeGridSnapshots([
+            { ...grid, cells: [...retained, ...grid.cells] },
+          ]);
+        }
+        return grid;
+      }
+      function completedGrid(value) {
+        if (!value) return value;
+        const aggregate = aggregateTiles(!value.error);
+        return aggregate
+          ? combineWildlifeGridSnapshots([aggregate, value], value.error)
+          : value;
+      }
+      function publish(grid, gridError = null, replaceRows = false) {
+        applyAccepted({
+          snapshot: acceptedSnapshot,
+          grid,
+          gridError,
+          replaceRows,
+          query,
+          params,
+          request,
+          signal,
+          epoch: requestLifetime,
+        });
+      }
+      function finishTiles() {
+        signal?.removeEventListener?.('abort', onAbort);
+        if (state.request === request) {
+          state.request = null;
+          requestQueryKey = null;
+          state.loading = false;
+          if (request.signal.aborted && state.cameraTimer == null)
+            clearPending();
+          parts.controls.notify();
+        }
+      }
+      function continueTiles() {
+        if (!gridRequest || gridResult) return;
+        gridPending = true;
+        void gridRequest
+          .then((result) => {
+            if (
+              acceptedSnapshot &&
+              !request.signal.aborted &&
+              state.request === request &&
+              state.enabled
+            )
+              publish(result?.value, result?.error || result?.value?.error);
+          })
+          .finally(finishTiles);
+      }
+      try {
+        const options = {
+          signal: request.signal,
+          boxes: query.boxes,
+          box: query.boxes?.[0] || null,
+          scope: query.scope,
+          ...params,
+        };
+        // Observation requests enter the shared proxy queue first. A slow tile
+        // never holds the manager's initial enable or the first observations.
+        const observationRequest =
+          typeof services.source.getSnapshotDetail === 'function'
+            ? services.source.getSnapshotDetail(options)
+            : Promise.resolve(services.source.getSnapshot(options)).then(
+                (rows) => ({ rows, stale: false, fetchedAt: services.now() }),
+              );
+        const hasGrid =
+          typeof services.source.getGridSnapshot === 'function' &&
+          query.tiles.length;
+        gridRequest = hasGrid
+          ? services.source
+              .getGridSnapshot({
+                signal: request.signal,
+                tiles: query.tiles,
+                ...params,
+                onTile(value, { tile }) {
+                  if (request.signal.aborted || state.request !== request)
+                    return;
+                  tileSnapshots.set(`${tile.z}/${tile.x}/${tile.y}`, value);
+                  publish(aggregateTiles());
+                },
+              })
+              .then(
+                (value) => {
+                  gridResult = { value: completedGrid(value) };
+                  if (!acceptedSnapshot)
+                    publish(gridResult.value, value?.error);
+                  return gridResult;
+                },
+                (error) => (gridResult = { error }),
+              )
+          : null;
+        const snapshot = await observationRequest;
+        if (
+          request.signal.aborted ||
+          state.request !== request ||
+          !state.enabled
+        )
+          return supersededResult();
+        if (!Array.isArray(snapshot?.rows))
+          throw new Error('Malformed iNaturalist response');
+        received = true;
+        acceptedSnapshot = snapshot;
+        publish(
+          gridResult?.value || aggregateTiles(),
+          gridResult?.error || gridResult?.value?.error,
+          true,
+        );
+        if (hasGrid && !gridResult) {
+          continueTiles();
+        } else if (gridResult && !gridResult.value && gridResult.error) {
+          // Observation rows remain visible when the first tile set fails.
+          publish(undefined, gridResult.error);
+        }
+        return true;
+      } catch (error) {
+        if (
+          request.signal.aborted ||
+          state.request !== request ||
+          !state.enabled
+        )
+          return supersededResult();
+        if (received) throw error;
+        // Observation failures must not cancel independent density tiles.
+        continueTiles();
+        state.stale = false;
+        state.error =
+          error?.message || msg('Wildlife sightings source unavailable');
+        failParams(params);
+        state.lastQueryKey = null;
+        requestQueryKey = null;
+        applyRetry(error);
+        console.warn('[Data:WildlifeSightings] Update failed:', state.error);
+        return true;
+      } finally {
+        if (!gridPending) finishTiles();
+      }
+    },
+    /** Stop acquisition and release visible resources while retaining filters. */
+    disable,
+    /** Release requests, subscriptions, caches and scene resources. */
+    destroy() {
+      if (state.destroyed) return;
+      disable();
+      state.destroyed = true;
+      parts.selection.destroy();
+      parts.photos.destroy();
+      parts.rendering.destroy();
+      state.rows.clear();
+      state.lastUpdate = null;
+      state.error = null;
+      state.stale = false;
+      state.drawnParams = null;
+      state.gridParams = null;
+      state.pendingParams = null;
+      state.failedParams = null;
+      state.controlsListener = null;
+      state.manager = null;
+      state.viewer = null;
+    },
+  };
+  return {
+    methods,
+    scheduleRefresh,
+  };
+}
diff --git a/src/layers/wildlifeSightings/model.js b/src/layers/wildlifeSightings/model.js
new file mode 100644
index 000000000..c853a45e1
--- /dev/null
+++ b/src/layers/wildlifeSightings/model.js
@@ -0,0 +1,208 @@
+import {
+  WILDLIFE_HEIGHT_BANDS,
+  WILDLIFE_HEIGHT_HYSTERESIS,
+  WILDLIFE_RENDER_LIMIT,
+  WILDLIFE_VIEW_PADDING,
+} from './policy.js';
+import { WILDLIFE_GRID_TARGET_SPACING_PX } from './gridViewport.js';
+import { drainWildlifeWork, WILDLIFE_WORK_UNIT } from './performance.js';
+
+const BAND_ORDER = Object.freeze(['cards', 'cells', 'regional', 'global']);
+const BAND_THRESHOLDS = Object.freeze([
+  WILDLIFE_HEIGHT_BANDS.cards,
+  WILDLIFE_HEIGHT_BANDS.cells,
+  WILDLIFE_HEIGHT_BANDS.global,
+]);
+
+/** A previous band is retained until a boundary is crossed by ten percent. */
+export function getWildlifeHeightBand(heightM, previous) {
+  const height = Number.isFinite(heightM) ? Math.max(0, heightM) : 0;
+  let index = BAND_ORDER.indexOf(previous);
+  if (index < 0)
+    return BAND_ORDER[
+      BAND_THRESHOLDS.filter((boundary) => height > boundary).length
+    ];
+  while (
+    index < BAND_ORDER.length - 1 &&
+    height > BAND_THRESHOLDS[index] * (1 + WILDLIFE_HEIGHT_HYSTERESIS)
+  )
+    index += 1;
+  while (
+    index > 0 &&
+    height < BAND_THRESHOLDS[index - 1] * (1 - WILDLIFE_HEIGHT_HYSTERESIS)
+  )
+    index -= 1;
+  return BAND_ORDER[index];
+}
+
+/** Share the legend's animal grouping and unknown fallback with sprites. */
+export function wildlifeIconicGroup(iconic) {
+  if (iconic === 'Mollusca' || iconic === 'Animalia') return 'Animalia';
+  return [
+    'Aves',
+    'Mammalia',
+    'Reptilia',
+    'Amphibia',
+    'Actinopterygii',
+    'Insecta',
+    'Arachnida',
+    'Plantae',
+    'Fungi',
+  ].includes(iconic)
+    ? iconic
+    : 'Unknown';
+}
+
+function validIconPosition(row) {
+  return (
+    Number.isFinite(row?.lat) &&
+    Math.abs(row.lat) <= 90 &&
+    Number.isFinite(row?.lon) &&
+    Math.abs(row.lon) <= 180
+  );
+}
+
+/** Compare provider IDs consistently across locales. */
+export function compareWildlifeIds(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Prefer a selected/identified recent contact when a population exceeds its
+ * cap. Density is never converted into a larger billboard. */
+export function wildlifeIconRelevance(row, selectedId = null) {
+  return (
+    (row.stableId === selectedId ? 1e15 : 0) +
+    (row.commonName ? 1e13 : 0) +
+    (row.quality === 'research' ? 1e12 : 0) +
+    (Number.isFinite(row.observedAt) ? row.observedAt / 1000 : 0)
+  );
+}
+
+/** Real observations alone compete for 28px screen buckets. Density is an
+ * independent visual and can never supply or suppress a sighting's identity.
+ * A selected observation keeps its slot even outside the new camera view. */
+export function buildWildlifeIconModel(options = {}) {
+  return drainWildlifeWork(wildlifeIconModelWork(options));
+}
+
+/** Yield bounded units while selecting real observations for screen buckets. */
+export function* wildlifeIconModelWork({
+  rows = [],
+  boxes = null,
+  selectedId = null,
+  selectedRow = null,
+  preferredIds = [],
+  limit = WILDLIFE_RENDER_LIMIT,
+  projectRow = null,
+  onOperations = null,
+} = {}) {
+  const operations = {
+    observationVisits: 0,
+    projections: 0,
+    rankComparisons: 0,
+  };
+  const preferred = new Set(preferredIds);
+  const seen = new Set();
+  const buckets = new Map();
+  let sightingCount = 0;
+  let acartiaCount = 0;
+  const score = (row) =>
+    wildlifeIconRelevance(row, selectedId) +
+    (preferred.has(row.stableId) ? 1e14 : 0);
+  const candidates =
+    selectedRow && !rows.includes(selectedRow) ? [...rows, selectedRow] : rows;
+  yield 'bucket';
+  for (const row of candidates) {
+    if (
+      operations.observationVisits &&
+      operations.observationVisits % WILDLIFE_WORK_UNIT === 0
+    )
+      yield 'bucket';
+    operations.observationVisits++;
+    if (
+      typeof row?.stableId !== 'string' ||
+      !row.stableId.length ||
+      !validIconPosition(row) ||
+      seen.has(row.stableId)
+    )
+      continue;
+    seen.add(row.stableId);
+    const selected = row.stableId === selectedId;
+    const inView = rowInWildlifeBoxes(row, boxes, 0);
+    if (!selected && !inView) continue;
+    let key = row.stableId;
+    let visible = inView;
+    if (typeof projectRow === 'function') {
+      operations.projections++;
+      const screen = projectRow(row);
+      visible &&=
+        !!screen && Number.isFinite(screen.x) && Number.isFinite(screen.y);
+      if (!visible && !selected) continue;
+      if (visible) {
+        const x = Math.floor(screen.x / WILDLIFE_GRID_TARGET_SPACING_PX);
+        const y = Math.floor(screen.y / WILDLIFE_GRID_TARGET_SPACING_PX);
+        key =
+          Math.abs(x) < 1048576 && Math.abs(y) < 1048576
+            ? x * 2097152 + y
+            : `${x}:${y}`;
+      }
+    }
+    if (visible) {
+      sightingCount++;
+      if (row.origin === 'acartia') acartiaCount++;
+    }
+    const incumbent = buckets.get(key);
+    if (
+      !incumbent ||
+      score(row) > score(incumbent) ||
+      (score(row) === score(incumbent) && row.stableId < incumbent.stableId)
+    )
+      buckets.set(key, row);
+  }
+  yield 'rank';
+  const population = [...buckets.values()];
+  const cap = Math.max(selectedId ? 1 : 0, Math.floor(limit));
+  const saturated = population.length > cap;
+  if (saturated)
+    population.sort((a, b) => {
+      operations.rankComparisons++;
+      return score(b) - score(a) || compareWildlifeIds(a.stableId, b.stableId);
+    });
+  onOperations?.(operations);
+  return {
+    rows: saturated ? population.slice(0, cap) : population,
+    saturated,
+    totalPoints: population.length,
+    sightingCount,
+    acartiaCount,
+  };
+}
+
+/** Test the padded view in degrees, including across the antimeridian. Null
+ * boxes are the global sample, whose rows all remain candidates. */
+export function rowInWildlifeBoxes(
+  row,
+  boxes,
+  padding = WILDLIFE_VIEW_PADDING,
+) {
+  if (!Number.isFinite(row?.lat) || !Number.isFinite(row?.lon)) return false;
+  if (!Array.isArray(boxes)) return true;
+  for (const box of boxes) {
+    const latPad = (box.north - box.south) * padding;
+    const width =
+      box.east >= box.west ? box.east - box.west : 360 - box.west + box.east;
+    const lonPad = width * padding;
+    if (
+      row.lat < Math.max(-90, box.south - latPad) ||
+      row.lat > Math.min(90, box.north + latPad)
+    )
+      continue;
+    const relative = row.lon - box.west;
+    if (relative >= -lonPad && relative <= width + lonPad) return true;
+    if (relative + 360 >= -lonPad && relative + 360 <= width + lonPad)
+      return true;
+    if (relative - 360 >= -lonPad && relative - 360 <= width + lonPad)
+      return true;
+  }
+  return false;
+}
diff --git a/src/layers/wildlifeSightings/model.perf.test.mjs b/src/layers/wildlifeSightings/model.perf.test.mjs
new file mode 100644
index 000000000..19539b7ec
--- /dev/null
+++ b/src/layers/wildlifeSightings/model.perf.test.mjs
@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { performance } from 'node:perf_hooks';
+import test from 'node:test';
+import { perfBudgetTestOptions } from '../../../scripts/run-perf-tests.mjs';
+import {
+  harness,
+  syntheticRows,
+  changePositions,
+  WILDLIFE_BENCHMARK_REFRESHES,
+} from '../../testSupport/wildlifeBillboardModel.mjs';
+
+// Pure model and incremental reconciliation, measured after warmup.
+// The 2,000-contact allowance is a fraction of one 60Hz frame; the 5,000 cap
+// gets a proportional allowance. No renderer, network or real sightings run.
+const WILDLIFE_MODEL_UPDATE_BUDGET_MS = Object.freeze({
+  500: 4,
+  2000: 8,
+  5000: 20,
+});
+test(
+  '500 / 2,000 / 5,000 icon model updates stay within their named timing budgets',
+  perfBudgetTestOptions(),
+  (t) => {
+    // Warm the same pure hot paths before recording CPU time.
+    const warm = harness();
+    let warmRows = syntheticRows(2000);
+    warm.apply(warmRows);
+    for (let i = 0; i < 25; i++) {
+      warmRows = changePositions(warmRows, i);
+      warm.apply(warmRows);
+    }
+    for (const n of [500, 2000, 5000]) {
+      const h = harness();
+      let rows = syntheticRows(n);
+      const start = performance.now();
+      const initial = h.apply(rows);
+      const initialMs = performance.now() - start;
+      assert.equal(initial.created, n);
+      const durations = [];
+      for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
+        rows = changePositions(rows, refresh);
+        const before = performance.now();
+        const update = h.apply(rows);
+        durations.push(performance.now() - before);
+        assert.deepEqual(update, {
+          created: 0,
+          removed: 0,
+          updated: n / 10,
+          writes: n / 10,
+        });
+      }
+      const meanMs =
+        durations.reduce((sum, value) => sum + value, 0) / durations.length;
+      const maxMs = Math.max(...durations);
+      assert.ok(
+        maxMs <= WILDLIFE_MODEL_UPDATE_BUDGET_MS[n],
+        `${n}: ${maxMs.toFixed(3)}ms update exceeds ${WILDLIFE_MODEL_UPDATE_BUDGET_MS[n]}ms`,
+      );
+      const before = { ...h.counters };
+      assert.deepEqual(h.apply([...rows].reverse()), {
+        created: 0,
+        removed: 0,
+        updated: 0,
+        writes: 0,
+      });
+      assert.deepEqual(
+        h.counters,
+        before,
+        'unchanged content performs zero billboard writes or allocations',
+      );
+      t.diagnostic(
+        `N=${n}; initial=${initialMs.toFixed(3)}ms; incremental10% mean=${meanMs.toFixed(3)}ms, max=${maxMs.toFixed(3)}ms; budget=${WILDLIFE_MODEL_UPDATE_BUDGET_MS[n]}ms; unchanged writes=0`,
+      );
+    }
+  },
+);
diff --git a/src/layers/wildlifeSightings/model.test.mjs b/src/layers/wildlifeSightings/model.test.mjs
new file mode 100644
index 000000000..680be10c1
--- /dev/null
+++ b/src/layers/wildlifeSightings/model.test.mjs
@@ -0,0 +1,162 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  wildlifeIconicGroup,
+  rowInWildlifeBoxes,
+  buildWildlifeIconModel,
+} from './model.js';
+import { ICONIC_TINTS, ICONIC_LEGEND_ORDER, TAXA_PRESETS } from './policy.js';
+
+const row = {
+  stableId: 'inat:1',
+  lat: 47.6,
+  lon: -122.3,
+  cell: null,
+  iconic: 'Aves',
+  quality: 'research',
+  count: null,
+  obscured: false,
+};
+
+test('unknown groups are slate and molluscs fold into other animals', () => {
+  assert.equal(wildlifeIconicGroup('Mollusca'), 'Animalia');
+  for (const iconic of ['Unknown', 'Protozoa', 'Chromista', undefined])
+    assert.equal(wildlifeIconicGroup(iconic), 'Unknown');
+  assert.equal(ICONIC_TINTS.Unknown, '#9aa7b3');
+  assert.equal(ICONIC_LEGEND_ORDER.at(-1), 'Unknown');
+  assert.equal(ICONIC_LEGEND_ORDER.length, 11);
+  assert.equal(TAXA_PRESETS.length, 6);
+  assert.equal(TAXA_PRESETS.filter((item) => item.label === 'ALL').length, 1);
+  assert.equal(Object.isFrozen(ICONIC_TINTS), true);
+  assert.equal(Object.isFrozen(TAXA_PRESETS[0]), true);
+});
+
+test('view filtering includes padding and both sides of the antimeridian', () => {
+  const boxes = [{ south: 47, west: -123, north: 48, east: -122 }];
+  assert.equal(rowInWildlifeBoxes(row, boxes), true);
+  assert.equal(rowInWildlifeBoxes({ ...row, lat: 48.2 }, boxes), true);
+  assert.equal(rowInWildlifeBoxes({ ...row, lat: 48.4 }, boxes), false);
+  assert.equal(
+    rowInWildlifeBoxes({ ...row, lat: 10.5, lon: -179.9 }, [
+      { south: 10, west: 179, north: 11, east: 180 },
+    ]),
+    true,
+  );
+  assert.equal(rowInWildlifeBoxes(row, null), true);
+  assert.equal(rowInWildlifeBoxes(row, []), false);
+});
+
+test('grid cells never enter the observation icon model', () => {
+  const cells = [
+    { id: 'grid:2/0/0:1:1', lat: 47.6, lon: -122.3, cellCount: 999 },
+  ];
+  assert.deepEqual(buildWildlifeIconModel({ rows: cells }).rows, []);
+  assert.deepEqual(buildWildlifeIconModel({ rows: [...cells, row] }).rows, [
+    row,
+  ]);
+});
+
+test('screen buckets retain incumbent photos at their real sighting positions', () => {
+  const incumbent = {
+    ...row,
+    commonName: 'Incumbent',
+    photo: { square: 'synthetic.jpg' },
+  };
+  const challenger = {
+    ...row,
+    stableId: 'inat:2',
+    commonName: 'Challenger',
+    observedAt: Date.UTC(2026, 10, 4),
+  };
+  const distant = { ...row, stableId: 'inat:3', lon: row.lon + 1 };
+  const model = buildWildlifeIconModel({
+    rows: [challenger, incumbent, distant],
+    preferredIds: [incumbent.stableId],
+    projectRow: (item) => ({ x: (item.lon - row.lon) * 28 + 14, y: 14 }),
+  });
+  assert.deepEqual(model.rows, [incumbent, distant]);
+  assert.equal(model.sightingCount, 3);
+  assert.equal(model.rows[0].photo, incumbent.photo);
+});
+
+test('visible observation counts precede per-area and global caps', () => {
+  const rows = Array.from({ length: 6000 }, (_, i) => ({
+    ...row,
+    stableId: `inat:${i}`,
+    lon: -160 + i * 0.01,
+  }));
+  let projections = 0;
+  const model = buildWildlifeIconModel({
+    rows,
+    projectRow(item) {
+      projections++;
+      return { x: (item.lon + 160) * 5600 + 14, y: 14 };
+    },
+  });
+  assert.equal(projections, 6000);
+  assert.equal(model.rows.length, 5000);
+  assert.equal(model.totalPoints, 6000);
+  assert.equal(model.saturated, true);
+  assert.equal(model.sightingCount, 6000);
+});
+
+test('selected observations win their bucket and survive a sample, viewport and projection change', () => {
+  const selected = { ...row, commonName: 'Selected sighting' };
+  const challenger = {
+    ...row,
+    stableId: 'inat:2',
+    commonName: 'Newer',
+    observedAt: Date.UTC(2026, 10, 4),
+  };
+  const input = {
+    selectedId: row.stableId,
+    selectedRow: selected,
+    rows: [challenger],
+    limit: 1,
+  };
+  assert.deepEqual(
+    buildWildlifeIconModel({ ...input, projectRow: () => ({ x: 14, y: 14 }) })
+      .rows,
+    [selected],
+  );
+  const offscreen = buildWildlifeIconModel({
+    ...input,
+    boxes: [{ south: 0, west: 0, north: 1, east: 1 }],
+    projectRow: () => null,
+  });
+  assert.deepEqual(offscreen.rows, [selected]);
+  assert.equal(
+    offscreen.sightingCount,
+    0,
+    'an offscreen pin is not a visible observation',
+  );
+});
+
+test('observation reduction is stable under input order, selected priority and visible filtering', () => {
+  const named = { ...row, stableId: 'inat:2', commonName: 'Known bird' };
+  const outside = { ...row, stableId: 'inat:3', lat: 0 };
+  const input = {
+    boxes: [{ south: 47, west: -123, north: 48, east: -122 }],
+    limit: 1,
+  };
+  const model = buildWildlifeIconModel({
+    ...input,
+    rows: [row, named, outside],
+  });
+  assert.equal(model.saturated, true);
+  assert.equal(model.totalPoints, 2);
+  assert.equal(model.sightingCount, 2);
+  assert.deepEqual(model.rows, [named]);
+  assert.deepEqual(
+    buildWildlifeIconModel({ ...input, rows: [outside, named, row] }),
+    model,
+  );
+  assert.deepEqual(
+    buildWildlifeIconModel({
+      ...input,
+      rows: [named, row],
+      selectedId: row.stableId,
+    }).rows,
+    [row],
+  );
+});
diff --git a/src/layers/wildlifeSightings/ownership.test.mjs b/src/layers/wildlifeSightings/ownership.test.mjs
new file mode 100644
index 000000000..c8bfaac62
--- /dev/null
+++ b/src/layers/wildlifeSightings/ownership.test.mjs
@@ -0,0 +1,2224 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { createWildlifeSightingsLayer } from './index.js';
+import { layerFeedState } from '../../data/feedState.js';
+import { LayerLifecycle } from '../../data/lifecycle.js';
+import { ICONIC_LEGEND_ORDER, WILDLIFE_MAX_ROWS } from './policy.js';
+import { wildlifeGridCellId } from './gridViewport.js';
+
+const NOW = Date.parse('2026-11-04T18:00:00Z');
+const base = {
+  stableId: 'inat:1',
+  origin: 'inaturalist',
+  lat: 47.6,
+  lon: -122.4,
+  obscured: false,
+  cell: null,
+  observedAt: NOW - 3_600_000,
+  observedOn: '2026-11-04',
+  quality: 'research',
+  commonName: 'Synthetic bird',
+  scientificName: 'Avis synthetica',
+  iconic: 'Aves',
+  threatened: false,
+  provider: null,
+  link: 'https://www.inaturalist.org/observations/1',
+  photo: null,
+};
+const photographed = {
+  ...base,
+  photo: {
+    square:
+      'https://inaturalist-open-data.s3.amazonaws.com/photos/1/square.jpg',
+    medium:
+      'https://inaturalist-open-data.s3.amazonaws.com/photos/1/medium.jpg',
+    attribution: '(c) Synthetic Photographer',
+    licence: 'cc-by',
+  },
+};
+
+function event() {
+  const listeners = new Set();
+  return {
+    addEventListener(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    emit(value) {
+      for (const fn of [...listeners]) fn(value);
+    },
+    count: () => listeners.size,
+  };
+}
+
+function primitives() {
+  const values = [];
+  const primitiveAdded = event();
+  const primitiveRemoved = event();
+  return {
+    values,
+    primitiveAdded,
+    primitiveRemoved,
+    get length() {
+      return values.length;
+    },
+    get: (index) => values[index],
+    add(value) {
+      values.push(value);
+      primitiveAdded.emit(value);
+      return value;
+    },
+    remove(value) {
+      const index = values.indexOf(value);
+      if (index < 0) return false;
+      values.splice(index, 1);
+      primitiveRemoved.emit(value);
+      value.destroy?.();
+      return true;
+    },
+  };
+}
+
+class PointCollection {
+  values = [];
+  show = false;
+  add(point) {
+    this.values.push(point);
+    return point;
+  }
+  remove(point) {
+    const index = this.values.indexOf(point);
+    if (index < 0) return false;
+    this.values.splice(index, 1);
+    return true;
+  }
+  removeAll() {
+    this.values = [];
+  }
+  destroy() {
+    this.destroyed = true;
+  }
+}
+class Ground {
+  constructor(options) {
+    Object.assign(this, options);
+    this.ready = false;
+  }
+  destroy() {
+    this.destroyed = true;
+  }
+  isDestroyed() {
+    return !!this.destroyed;
+  }
+}
+
+function harness(
+  source = { getSnapshot: async () => [base] },
+  extra = {},
+  { autoEnable = true, width = 2000, height = 1200 } = {},
+) {
+  let time = NOW;
+  let picked = null;
+  let cardHit = null;
+  let pointerFree = true;
+  let rectangle = { south: 47.4, west: -122.7, north: 47.9, east: -122.1 };
+  const events = new EventTarget();
+  const moveEnd = event();
+  const postRender = event();
+  const pointOwners = primitives();
+  const groundOwners = primitives();
+  const owners = new Map();
+  const overlay = {
+    entries: new Map(),
+    visible: new Map(),
+    options: new Map(),
+  };
+  const renders = [];
+  const focus = [];
+  const links = [];
+  const credits = new Set();
+  const store = { entities: new Map(), selectedEntityId: null };
+  const clicks = {};
+  const timers = new Map();
+  const idleTasks = new Map();
+  let nextTimer = 0;
+  let nextIdle = 0;
+  const images = [];
+  const viewer = {
+    scene: {
+      primitives: pointOwners,
+      groundPrimitives: groundOwners,
+      postRender,
+      canvas: { clientWidth: width, clientHeight: height },
+      globe: {
+        tileLoadProgressEvent: event(),
+        terrainProviderChanged: event(),
+      },
+      sampleHeightSupported: true,
+      sampleHeight: () =>
+        assert.fail('scene.sampleHeight renders per call; use groundFloor'),
+      pick: () => picked,
+      requestRender: () => assert.fail('must use render governor'),
+    },
+    camera: {
+      positionCartographic: { height: 30_000 },
+      positionWC: Cesium.Cartesian3.fromDegrees(-122, 47, 30_000),
+      moveEnd,
+      computeViewRectangle: () =>
+        Object.fromEntries(
+          Object.entries(rectangle).map(([key, value]) => [
+            key,
+            Cesium.Math.toRadians(value),
+          ]),
+        ),
+    },
+    creditDisplay: {
+      addStaticCredit: (credit) => credits.add(credit),
+      removeStaticCredit: (credit) => credits.delete(credit),
+    },
+  };
+  const ground = { sample: () => 123, resolves: 0 };
+  const layer = createWildlifeSightingsLayer({
+    source,
+    groundFloor: {
+      cachedGroundFloor: (lat, lon) => ground.sample(lat, lon),
+      resolveGroundFloorCellsBounded: async () => {
+        ground.resolves++;
+      },
+    },
+    cesium: {
+      ...Cesium,
+      BillboardCollection: PointCollection,
+      GroundPrimitive: Ground,
+      GroundPolylinePrimitive: Ground,
+    },
+    now: () => time,
+    setTimer(fn, delay) {
+      const id = ++nextTimer;
+      timers.set(id, { fn, delay });
+      return id;
+    },
+    clearTimer: (id) => timers.delete(id),
+    requestIdleCallback(fn) {
+      const id = ++nextIdle;
+      idleTasks.set(id, fn);
+      return id;
+    },
+    cancelIdleCallback: (id) => idleTasks.delete(id),
+    imageFactory: () => {
+      const image = {};
+      images.push(image);
+      return image;
+    },
+    eventTarget: events,
+    occluderFactory: () => ({
+      isPointVisible: (position) => position.visible !== false,
+    }),
+    project: (_scene, position) => {
+      const cartographic = Cesium.Cartographic.fromCartesian(position);
+      return {
+        x:
+          400 +
+          (Cesium.Math.toDegrees(cartographic.longitude) -
+            (rectangle.west + rectangle.east) / 2) *
+            1000,
+        y:
+          400 +
+          ((rectangle.south + rectangle.north) / 2 -
+            Cesium.Math.toDegrees(cartographic.latitude)) *
+            1000,
+      };
+    },
+    overlayHost: {
+      setEntries: (id, entries, options) => {
+        assert.equal(options.moving, false);
+        overlay.entries.set(id, entries);
+        overlay.options.set(id, options);
+      },
+      setVisible: (id, value) => overlay.visible.set(id, value),
+      clearSource: (id) => overlay.entries.delete(id),
+      hitTest: (_x, _y, { sourceId }) =>
+        cardHit?.sourceId === sourceId ? cardHit : null,
+    },
+    screenSpaceEventHandlerFactory: () => ({
+      setInputAction(fn) {
+        clicks.callback = fn;
+      },
+      destroy() {
+        clicks.destroyed = true;
+        clicks.callback = null;
+      },
+    }),
+    pointer: { isPointerFree: () => pointerFree },
+    picking: {
+      registerPickOwner: (id, fn) => owners.set(id, fn),
+      unregisterPickOwner: (id) => owners.delete(id),
+      resolvePickId: (pick) => pick?.id ?? pick?.primitive?.id,
+      isOwnedByOtherLayer: (_layerId, id) => id?.startsWith('other:'),
+    },
+    sprites: {
+      registerSpriteCollection: (_id, collection) => {
+        clicks.collection = collection;
+      },
+      unregisterSpriteCollection: () => {
+        clicks.unregistered = true;
+      },
+      restoreSpriteOrderOnEnable: (id) => {
+        assert.equal(id, 'wildlife-sightings');
+      },
+    },
+    render: { governorRequestRender: (reason) => renders.push(reason) },
+    focus: { requestWorldFocus: (request) => focus.push(request) },
+    openExternal: (url) => links.push(url),
+    context: {
+      getContextStore: () => store,
+      registerEntityContext(entity, metadata) {
+        entity.__gevContextId = metadata.id;
+        store.entities.set(metadata.id, { ...metadata, entity });
+      },
+      selectEntityContext(entity) {
+        store.selectedEntityId = entity.__gevContextId;
+        const selected = new Event('gev:entity-selected');
+        selected.detail = store.entities.get(entity.__gevContextId);
+        events.dispatchEvent(selected);
+      },
+      clearSelectedEntityContextForLayer: () => {
+        store.selectedEntityId = null;
+      },
+      removeEntityContextsForLayer: () => store.entities.clear(),
+    },
+    ...extra,
+  });
+  if (autoEnable) {
+    layer.init(viewer);
+    layer.enable(viewer);
+  }
+  function flushIdle() {
+    for (let steps = 0; idleTasks.size; steps++) {
+      assert.ok(steps < 1000, 'idle work finishes without a frame loop');
+      const [id, fn] = idleTasks.entries().next().value;
+      idleTasks.delete(id);
+      fn({ timeRemaining: () => 10 });
+    }
+  }
+  return {
+    ground,
+    layer,
+    async update(...args) {
+      // Explicit refreshes stand for successive poll batches, not push bursts.
+      time += 500;
+      const result = await layer.update(...args);
+      flushIdle();
+      return result;
+    },
+    flushIdle,
+    viewer,
+    overlay,
+    clicks,
+    owners,
+    renders,
+    focus,
+    links,
+    credits,
+    images,
+    groundOwners,
+    pointOwners,
+    events,
+    postRender,
+    moveEnd,
+    store,
+    timers,
+    pick: (value) => {
+      picked = value;
+    },
+    hit: (value) => {
+      cardHit = value;
+    },
+    free: (value) => {
+      pointerFree = value;
+    },
+    rectangle: (value) => {
+      rectangle = value;
+    },
+    time: (value) => {
+      time = value;
+    },
+    contextSelect(id) {
+      const selected = new Event('gev:entity-selected');
+      selected.detail = store.entities.get(id);
+      events.dispatchEvent(selected);
+    },
+  };
+}
+
+test('construction validates source and does not acquire; double init throws', () => {
+  assert.throws(() => createWildlifeSightingsLayer(), TypeError);
+  const h = harness({ getSnapshot: () => assert.fail('enable fetched') });
+  assert.throws(() => h.layer.init(h.viewer), /already initialized/);
+  assert.equal(h.clicks.collection.show, true);
+  h.layer.destroy();
+});
+
+test('terrain warming resamples unchanged point, card and context anchors without a frame loop', async () => {
+  const h = harness(
+    {
+      getSnapshot: async () => [
+        photographed,
+        { ...base, stableId: 'acartia:sea', origin: 'acartia', lon: -122.3 },
+      ],
+    },
+    {},
+    { autoEnable: false },
+  );
+  let height = 0;
+  let samples = 0;
+  h.ground.sample = () => {
+    samples++;
+    return height;
+  };
+  h.layer.init(h.viewer);
+  h.layer.enable(h.viewer);
+  await h.update();
+  h.layer.selectSighting('inat:1');
+  const point = h.clicks.collection.values[0];
+  const sea = h.clicks.collection.values[1];
+  const before = samples;
+  height = 600;
+  await h.update();
+  h.moveEnd.emit();
+  assert.equal(
+    samples,
+    before,
+    'unchanged snapshots and camera movement do not resample per point',
+  );
+  h.viewer.scene.globe.tileLoadProgressEvent.emit(1);
+  assert.equal(samples, before, 'wait for terrain loading to settle');
+  h.viewer.scene.globe.tileLoadProgressEvent.emit(0);
+  assert.ok(
+    Math.abs(Cesium.Cartographic.fromCartesian(point.position).height - 600) <
+      0.01,
+  );
+  assert.equal(
+    samples,
+    before + 1,
+    'Acartia sea anchors are never terrain-sampled',
+  );
+  assert.ok(
+    Math.abs(Cesium.Cartographic.fromCartesian(sea.position).height) < 0.01,
+  );
+  assert.equal(
+    h.clicks.collection.values[0],
+    point,
+    'resampling preserves the point primitive',
+  );
+  assert.deepEqual(
+    h.overlay.entries.get('wildlife-sightings')[0].position,
+    point.position,
+  );
+  assert.ok(
+    h.overlay.entries
+      .get('wildlife-sightings-selected')
+      .every((entry) =>
+        Cesium.Cartesian3.equals(entry.position, point.position),
+      ),
+  );
+  assert.deepEqual(
+    h.store.entities.get('inat:1').entity.__localBaseCartesian,
+    point.position,
+  );
+  assert.ok(h.renders.includes('wildlife-sightings-terrain'));
+  assert.equal(h.postRender.count(), 0);
+  h.layer.disable();
+  assert.equal(h.viewer.scene.globe.tileLoadProgressEvent.count(), 0);
+  assert.equal(h.viewer.scene.globe.terrainProviderChanged.count(), 0);
+  const disabledSamples = samples;
+  h.viewer.scene.globe.tileLoadProgressEvent.emit(0);
+  assert.equal(samples, disabledSamples);
+  height = 900;
+  h.layer.enable(h.viewer);
+  assert.ok(
+    Math.abs(
+      Cesium.Cartographic.fromCartesian(h.clicks.collection.values[0].position)
+        .height - 900,
+    ) < 0.01,
+  );
+  assert.equal(h.viewer.scene.globe.tileLoadProgressEvent.count(), 1);
+  h.layer.destroy();
+  assert.equal(h.viewer.scene.globe.tileLoadProgressEvent.count(), 0);
+});
+
+test('terrain provider, loaded tilesets and map-source changes refresh anchors and release listeners', async () => {
+  const h = harness(undefined, {}, { autoEnable: false });
+  const tileset = { allTilesLoaded: event() };
+  h.pointOwners.add(tileset);
+  let height = 20;
+  h.ground.sample = () => height;
+  h.layer.init(h.viewer);
+  h.layer.enable(h.viewer);
+  await h.update();
+  const point = h.clicks.collection.values[0];
+  const assertHeight = (expected) =>
+    assert.ok(
+      Math.abs(
+        Cesium.Cartographic.fromCartesian(point.position).height - expected,
+      ) < 0.01,
+    );
+  height = 200;
+  h.viewer.scene.globe.terrainProviderChanged.emit({});
+  assertHeight(200);
+  height = 400;
+  tileset.allTilesLoaded.emit();
+  assertHeight(400);
+  const nextTileset = { allTilesLoaded: event() };
+  height = 600;
+  h.pointOwners.add(nextTileset);
+  assert.equal(
+    nextTileset.allTilesLoaded.count(),
+    1,
+    'new tilesets are subscribed without polling',
+  );
+  nextTileset.allTilesLoaded.emit();
+  assertHeight(600);
+  height = 800;
+  h.events.dispatchEvent(new Event('gev:map-stack-changed'));
+  assertHeight(800);
+  height = 0;
+  h.pointOwners.remove(nextTileset);
+  assertHeight(0);
+  assert.equal(nextTileset.allTilesLoaded.count(), 0);
+  h.layer.disable();
+  assert.equal(tileset.allTilesLoaded.count(), 0);
+  assert.equal(h.pointOwners.primitiveAdded.count(), 0);
+  assert.equal(h.pointOwners.primitiveRemoved.count(), 0);
+  height = 1000;
+  h.events.dispatchEvent(new Event('gev:map-stack-changed'));
+  assertHeight(0);
+  h.layer.destroy();
+  assert.equal(h.postRender.count(), 0);
+});
+
+test('camera rebuilds expire unselected sightings while a selected observation stays pinned', async () => {
+  for (const [taxa, windowHours] of [
+    ['all', 48],
+    ['whales', 7 * 24],
+  ]) {
+    let requests = 0;
+    const h = harness({
+      getSnapshot: async () =>
+        ++requests === 1
+          ? [photographed]
+          : [{ ...base, stableId: 'inat:other-area', lat: 49.1, lon: -124.2 }],
+    });
+    h.layer.setParams({ taxa });
+    await h.update();
+    h.rectangle({ south: 48.8, west: -124.5, north: 49.4, east: -124 });
+    h.moveEnd.emit();
+    await h.update();
+    h.rectangle({ south: 47.4, west: -122.7, north: 47.9, east: -122.1 });
+    h.moveEnd.emit();
+    assert.equal(
+      h.clicks.collection.values[0].id,
+      'wildlife:inat:1',
+      'the prior area is retained in the LRU',
+    );
+    assert.equal(h.layer.selectSighting('inat:1'), true);
+    assert.ok(h.overlay.entries.get('wildlife-sightings-selected').length > 0);
+    h.time(NOW + windowHours * 3_600_000);
+    h.moveEnd.emit();
+    assert.equal(
+      h.clicks.collection.values.length,
+      1,
+      `${taxa} keeps the explicitly selected observation beyond its window`,
+    );
+    assert.equal(h.overlay.entries.get('wildlife-sightings').length, 0);
+    assert.equal(
+      h.overlay.entries.get('wildlife-sightings-selected').length,
+      1,
+    );
+    h.layer.clearSightingSelection();
+    h.moveEnd.emit();
+    assert.equal(
+      h.clicks.collection.values.length,
+      0,
+      'expired rows retire on deselection',
+    );
+    assert.equal(requests, 2, 'expiry needs no new source success');
+    h.layer.destroy();
+  }
+});
+
+test('pending filter changes retain the accepted recency window until their result validates', async () => {
+  const h = harness({
+    getSnapshot: async () => [
+      { ...photographed, observedAt: NOW - 3 * 86_400_000 },
+    ],
+  });
+  h.layer.setParams({ taxa: 'whales' });
+  await h.update();
+  h.layer.setParams({ taxa: 'all' });
+  assert.equal(h.layer.selectSighting('inat:1'), true);
+  assert.equal(
+    h.clicks.collection.values.length,
+    1,
+    'three-day whale remains while ALL is pending',
+  );
+  assert.ok(h.overlay.entries.get('wildlife-sightings-selected').length > 0);
+  h.layer.destroy();
+});
+
+test('sampled ground and sea heights keep badges on top and update them in place', async () => {
+  let rows = [
+    base,
+    {
+      ...base,
+      stableId: 'acartia:2',
+      origin: 'acartia',
+      lon: -122.5,
+      iconic: 'Mammalia',
+    },
+  ];
+  const h = harness({ getSnapshot: async () => rows });
+  await h.update();
+  const first = h.clicks.collection.values[0];
+  assert.equal(first.disableDepthTestDistance, Infinity);
+  assert.ok(
+    Math.abs(Cesium.Cartographic.fromCartesian(first.position).height - 123) <
+      0.01,
+  );
+  assert.ok(
+    Math.abs(
+      Cesium.Cartographic.fromCartesian(h.clicks.collection.values[1].position)
+        .height,
+    ) < 0.01,
+  );
+  await h.update();
+  assert.equal(h.clicks.collection.values[0], first);
+  for (const change of [
+    { lon: -122.3 },
+    { iconic: 'Fungi' },
+    { quality: 'needs_id' },
+  ]) {
+    const before = h.clicks.collection.values[0];
+    rows = [{ ...rows[0], ...change }];
+    await h.update();
+    assert.equal(
+      h.clicks.collection.values[0],
+      before,
+      'changed contacts update in place',
+    );
+  }
+  assert.ok(h.renders.length > 0);
+  h.layer.destroy();
+  const unsupported = harness(undefined);
+  unsupported.ground.sample = () => null;
+  await unsupported.update();
+  assert.ok(
+    Math.abs(
+      Cesium.Cartographic.fromCartesian(
+        unsupported.clicks.collection.values[0].position,
+      ).height,
+    ) < 0.01,
+  );
+  unsupported.layer.destroy();
+});
+
+test('a painted card hides its anchored badge across rebuilds while retaining its context and selection', async (t) => {
+  const h = harness({ getSnapshot: async () => [photographed] });
+  t.after(() => h.layer.destroy());
+  await h.update();
+  const point = h.clicks.collection.values[0];
+  assert.equal(point.show, true);
+  const visibility =
+    h.overlay.options.get('wildlife-sightings').onVisibilityChange;
+  visibility(new Set(['sighting:inat:1']));
+  assert.equal(point.show, false);
+  h.moveEnd.emit();
+  assert.equal(
+    point.show,
+    false,
+    'a camera rebuild must not resurrect the represented badge',
+  );
+  assert.equal(
+    h.store.entities.get('inat:1').entity.show,
+    true,
+    'visual badge suppression must not hide the sighting context',
+  );
+  assert.equal(h.layer.selectSighting('inat:1'), true);
+  assert.equal(
+    point.show,
+    false,
+    'selection must not resurrect the represented badge',
+  );
+  visibility(new Set());
+  assert.equal(point.show, true);
+});
+
+test('a painted thumbnail hides the repeat name label, ambient and selected, until it leaves', async (t) => {
+  const h = harness({ getSnapshot: async () => [photographed] });
+  t.after(() => h.layer.destroy());
+  await h.update();
+  const labelIds = () =>
+    [
+      ...(h.overlay.entries.get('wildlife-sightings-labels') || []),
+      ...(h.overlay.entries.get('wildlife-sightings-selected') || []),
+    ]
+      .filter((entry) => entry.variant === 'label')
+      .map((entry) => entry.id);
+  const visibility =
+    h.overlay.options.get('wildlife-sightings').onVisibilityChange;
+  assert.ok(h.layer.selectSighting('inat:1'));
+  assert.deepEqual(labelIds(), ['wildlife-sightings-label:inat:1']);
+  visibility(new Set(['sighting:inat:1']));
+  assert.deepEqual(labelIds(), [], 'the thumbnail already names it');
+  h.moveEnd.emit();
+  assert.deepEqual(labelIds(), [], 'a rebuild keeps the label hidden');
+  h.layer.clearSelection?.();
+  assert.deepEqual(labelIds(), [], 'ambient labels also yield to the card');
+  visibility(new Set());
+  assert.ok(labelIds().length <= 1);
+});
+
+test('dot, ambient card and context clicks focus the true sighting; cards win over scene picks', async () => {
+  const h = harness({ getSnapshot: async () => [photographed] });
+  const selections = [];
+  h.layer.subscribeSelection((row, metadata) =>
+    selections.push({ row, metadata }),
+  );
+  await h.update();
+  h.pick({ id: 'wildlife:inat:1' });
+  h.clicks.callback({ position: { x: 20, y: 30 } });
+  assert.equal(h.focus.length, 1);
+  assert.equal(h.clicks.collection.values[0].scale, 1);
+  assert.equal(h.store.selectedEntityId, 'inat:1');
+  assert.deepEqual(selections.at(-1), {
+    row: photographed,
+    metadata: { explicitSelection: true },
+  });
+  const ambient = h.overlay.entries.get('wildlife-sightings')[0];
+  assert.equal(ambient.interactive, true);
+  // The anchored photo card owns the single iNaturalist link; canvas cards
+  // only select and focus.
+  assert.match(ambient.accessibilityLabel, /Show Synthetic bird sighting/);
+  assert.equal(ambient.activate(), true);
+  assert.equal(h.focus.length, 2);
+  assert.deepEqual(h.links, []);
+  assert.deepEqual(selections.at(-1).metadata, { explicitSelection: true });
+  const selected = h.overlay.entries.get('wildlife-sightings-selected');
+  assert.equal(selected.length, 1);
+  assert.equal(selected[0].variant, 'label');
+  assert.equal(selected[0].title, base.commonName.toUpperCase());
+  assert.equal(selected[0].placement, 'above');
+  assert.equal(selected[0].interactive, false);
+  assert.equal(selected[0].selected, true);
+  assert.equal(selected[0].image, undefined);
+  assert.equal(selected[0].details, undefined);
+  assert.equal(selected[0].pinned, undefined);
+  assert.ok(
+    h.images.every((image) => /square.jpg$/.test(image.src)),
+    'selection never starts an overlay medium image',
+  );
+  h.hit({ sourceId: 'wildlife-sightings', entry: ambient });
+  h.pick({ id: 'other:aircraft' });
+  h.clicks.callback({ position: {} });
+  assert.deepEqual(h.links, [], 'canvas cards select; they never open links');
+  assert.equal(h.focus.length, 3);
+  assert.equal(
+    h.store.selectedEntityId,
+    'inat:1',
+    'ambient cards win over scene picks',
+  );
+  h.hit(null);
+  h.clicks.callback({ position: {} });
+  assert.equal(h.store.selectedEntityId, 'inat:1', 'sibling picks yield');
+  h.free(false);
+  h.pick(null);
+  h.clicks.callback({ position: {} });
+  assert.equal(h.store.selectedEntityId, 'inat:1');
+  h.contextSelect('inat:1');
+  assert.equal(
+    h.focus.length,
+    4,
+    'context selection focuses the same true observation position',
+  );
+  assert.deepEqual(selections.at(-1).metadata, { explicitSelection: true });
+  h.free(true);
+  h.clicks.callback({ position: {} });
+  assert.equal(h.store.selectedEntityId, null);
+  h.layer.disable();
+  assert.equal(ambient.activate(), false);
+  h.layer.destroy();
+});
+
+test('selection subscriptions publish current rows, accepted refreshes, reselection and real deselection', async () => {
+  let rows = [photographed];
+  const h = harness({ getSnapshot: async () => rows });
+  const seen = [];
+  const metadata = [];
+  const unsubscribe = h.layer.subscribeSelection((selected, details) => {
+    seen.push(selected);
+    metadata.push(details);
+  });
+  assert.deepEqual(
+    seen,
+    [null],
+    'subscription immediately publishes its empty state',
+  );
+  assert.deepEqual(metadata.at(-1), { explicitSelection: false });
+  await h.update();
+  assert.deepEqual(metadata.at(-1), { explicitSelection: false });
+  assert.equal(h.layer.selectSighting('inat:1'), true);
+  assert.equal(seen.at(-1), photographed);
+  assert.deepEqual(metadata.at(-1), { explicitSelection: true });
+  const immediately = [];
+  const removeImmediate = h.layer.subscribeSelection((selected, details) =>
+    immediately.push({ selected, details }),
+  );
+  assert.deepEqual(
+    immediately,
+    [{ selected: photographed, details: { explicitSelection: false } }],
+    'late subscribers immediately receive the selected row without an explicit reselection',
+  );
+  removeImmediate();
+  rows = [{ ...photographed, commonName: 'Updated synthetic bird' }];
+  await h.update();
+  assert.equal(seen.at(-1), rows[0]);
+  assert.deepEqual(
+    metadata.at(-1),
+    { explicitSelection: false },
+    'an accepted snapshot preserves disclosure',
+  );
+  assert.equal(
+    h.overlay.entries.get('wildlife-sightings-selected')[0].title,
+    rows[0].commonName.toUpperCase(),
+  );
+  const beforeReselect = seen.length;
+  h.layer.selectSighting('inat:1');
+  assert.equal(
+    seen.length,
+    beforeReselect + 1,
+    'reselection notifies the dialog',
+  );
+  assert.deepEqual(
+    metadata.at(-1),
+    { explicitSelection: true },
+    'explicitly reselecting the same row can reopen it',
+  );
+  assert.equal(h.layer.clearSightingSelection(), true);
+  assert.equal(seen.at(-1), null);
+  assert.deepEqual(metadata.at(-1), { explicitSelection: false });
+  assert.equal(h.store.selectedEntityId, null);
+  assert.equal(h.clicks.collection.values[0].scale, 1);
+  assert.equal(
+    Cesium.Color.equals(
+      h.clicks.collection.values[0].color,
+      Cesium.Color.WHITE,
+    ),
+    true,
+  );
+  assert.deepEqual(h.overlay.entries.get('wildlife-sightings-selected'), []);
+  assert.equal(h.layer.clearSightingSelection(), false);
+  h.layer.selectSighting('inat:1');
+  const beforeUnsubscribe = seen.length;
+  unsubscribe();
+  await h.update();
+  h.layer.clearSightingSelection();
+  assert.equal(seen.length, beforeUnsubscribe);
+  h.layer.destroy();
+});
+
+test('selection subscriptions retain omitted rows and clear on disable and destroy, without an overlay host', async () => {
+  let rows = [base];
+  const eventListeners = new Map();
+  const eventTarget = {
+    addEventListener(type, listener) {
+      if (!eventListeners.has(type)) eventListeners.set(type, new Set());
+      eventListeners.get(type).add(listener);
+    },
+    removeEventListener(type, listener) {
+      eventListeners.get(type)?.delete(listener);
+    },
+  };
+  const h = harness(
+    { getSnapshot: async () => rows },
+    { overlayHost: null, eventTarget },
+  );
+  assert.equal(eventListeners.get('gev:entity-selected').size, 1);
+  const seen = [];
+  const unsubscribe = h.layer.subscribeSelection((selected) =>
+    seen.push(selected),
+  );
+  h.layer.subscribeSelection(() => {
+    throw new Error('Disconnected dialog');
+  });
+  await h.update();
+  h.layer.selectSighting('inat:1');
+  rows = [];
+  await h.update();
+  assert.equal(
+    seen.at(-1),
+    base,
+    'an accepted result omitting the selected row preserves the dialog',
+  );
+  rows = [base];
+  await h.update();
+  h.layer.selectSighting('inat:1');
+  h.layer.disable();
+  assert.equal(seen.at(-1), null);
+  assert.equal(eventListeners.get('gev:entity-selected').size, 0);
+  const disabledCount = seen.length;
+  h.layer.enable(h.viewer);
+  assert.equal(eventListeners.get('gev:entity-selected').size, 1);
+  await h.update();
+  h.layer.selectSighting('inat:1');
+  assert.equal(seen.at(-1), base);
+  assert.ok(
+    seen.length > disabledCount,
+    'disable retains subscriptions for re-enable',
+  );
+  h.layer.destroy();
+  assert.equal(seen.at(-1), null);
+  assert.equal(h.clicks.callback, null);
+  assert.equal(eventListeners.get('gev:entity-selected').size, 0);
+  const destroyedCount = seen.length;
+  h.layer.clearSightingSelection();
+  assert.equal(
+    seen.length,
+    destroyedCount,
+    'destroy removes existing subscribers',
+  );
+  const afterDestroy = [];
+  const removeDestroyed = h.layer.subscribeSelection((selected) =>
+    afterDestroy.push(selected),
+  );
+  assert.deepEqual(afterDestroy, [null]);
+  h.layer.clearSightingSelection();
+  assert.deepEqual(
+    afterDestroy,
+    [null],
+    'destroyed layers never retain new subscribers',
+  );
+  removeDestroyed();
+  unsubscribe();
+});
+
+test('privacy cells stage nonempty batches, request frames until ready, supersede and cancel cleanly', async () => {
+  let rows = [
+    {
+      ...base,
+      obscured: true,
+      cell: { south: 47.6, west: -122.4, north: 47.8, east: -122.2 },
+    },
+  ];
+  const h = harness({ getSnapshot: async () => rows });
+  await h.update();
+  assert.equal(h.groundOwners.values.length, 2);
+  assert.equal(h.postRender.count(), 1);
+  const pending = [...h.groundOwners.values];
+  h.postRender.emit();
+  assert.equal(h.renders.at(-1), 'wildlife-sightings-staging');
+  rows = [{ ...rows[0], iconic: 'Fungi' }];
+  await h.update();
+  assert.ok(pending.every((primitive) => primitive.destroyed));
+  assert.equal(h.groundOwners.values.length, 2);
+  for (const primitive of h.groundOwners.values) primitive.ready = true;
+  h.postRender.emit();
+  assert.ok(h.groundOwners.values.every((primitive) => primitive.show));
+  assert.equal(h.postRender.count(), 0);
+  h.layer.selectSighting(base.stableId);
+  assert.equal(h.focus.at(-1).kind, 'sighting-area');
+  const selectedRing = h.clicks.collection.values[0];
+  assert.equal(
+    Cesium.Color.equals(selectedRing.color, Cesium.Color.WHITE),
+    true,
+  );
+  assert.equal(selectedRing.scale, 1);
+  assert.match(selectedRing.image, /^data:image\/svg/);
+  assert.equal(
+    h.postRender.count(),
+    0,
+    'selection reuses unchanged privacy geometry',
+  );
+  h.layer.disable();
+  assert.equal(h.postRender.count(), 0);
+  assert.equal(h.groundOwners.values.length, 0);
+  h.layer.destroy();
+});
+
+test('disable ignores late successes and failures, unregisters owners and hides both overlay sources and credits', async () => {
+  for (const reject of [false, true]) {
+    let settle;
+    let signal;
+    const h = harness({
+      getSnapshot: ({ signal: requestSignal }) => {
+        signal = requestSignal;
+        return new Promise((resolve, fail) => {
+          settle = reject ? fail : resolve;
+        });
+      },
+    });
+    const pending = h.update();
+    assert.equal(h.owners.size, 1);
+    h.layer.disable();
+    assert.equal(signal.aborted, true);
+    settle(reject ? Error('iNaturalist HTTP 502') : [photographed]);
+    assert.equal(await pending, false);
+    assert.equal(h.layer.getStats().error, null);
+    assert.equal(h.clicks.collection.values.length, 0);
+    assert.equal(h.owners.size, 0);
+    assert.equal(h.credits.size, 0);
+    assert.deepEqual([...h.overlay.visible.values()], [false, false, false]);
+    assert.equal(h.overlay.entries.size, 0);
+    assert.equal(h.moveEnd.count(), 0);
+    h.layer.destroy();
+    assert.equal(h.pointOwners.values.length, 0);
+    assert.equal(h.clicks.unregistered, true);
+  }
+});
+
+test('first failure stays enabled; stale timestamps and subsequent failure preserve data with honest feed states', async () => {
+  let snapshot = null;
+  const h = harness({
+    getSnapshot: async () => [],
+    getSnapshotDetail: async () => {
+      if (!snapshot) throw new Error('iNaturalist HTTP 502');
+      return snapshot;
+    },
+  });
+  assert.equal(await h.update(), true);
+  assert.equal(layerFeedState(h.layer.getStats()), 'unavailable');
+  assert.equal(h.owners.size, 1);
+  snapshot = { rows: [base], stale: true, fetchedAt: NOW - 300_000 };
+  h.time(NOW + 31_000);
+  await h.update();
+  assert.equal(h.layer.getStats().lastUpdate, snapshot.fetchedAt);
+  assert.equal(layerFeedState(h.layer.getStats()), 'stale');
+  snapshot = null;
+  await h.update();
+  assert.equal(h.layer.getStats().count, 1);
+  assert.equal(h.layer.getStats().stale, false);
+  assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+  h.layer.destroy();
+});
+
+test('camera boxes supersede pending fetches through one manager debounce', async () => {
+  let signal;
+  let settle;
+  const h = harness({
+    getSnapshot: ({ signal: requestSignal }) => {
+      signal = requestSignal;
+      return new Promise((resolve) => {
+        settle = resolve;
+      });
+    },
+  });
+  let refreshes = 0;
+  h.layer.attachDataManager({
+    refreshLayer: async (id) => {
+      assert.equal(id, 'wildlife-sightings');
+      refreshes++;
+      return true;
+    },
+  });
+  const pending = h.update();
+  h.rectangle({ south: 48, west: -123, north: 48.4, east: -122.6 });
+  h.moveEnd.emit();
+  assert.equal(signal.aborted, true);
+  assert.equal(h.timers.size, 1);
+  const timer = [...h.timers.values()][0];
+  assert.equal(timer.delay, 600);
+  h.time(NOW + 2500);
+  timer.fn();
+  await Promise.resolve();
+  assert.equal(refreshes, 1);
+  settle([base]);
+  assert.equal(await pending, true);
+  h.layer.destroy();
+});
+
+test('a deferred A to B to A pan starts a new A request after aborting the first', async () => {
+  const requests = [];
+  const h = harness({
+    getSnapshot: ({ signal, boxes }) =>
+      new Promise((resolve) => {
+        requests.push({ signal, boxes, resolve });
+      }),
+  });
+  const boxA = { south: 47.4, west: -122.7, north: 47.9, east: -122.1 };
+  const pending = h.update();
+  h.rectangle({ south: 48, west: -123, north: 48.4, east: -122.6 });
+  h.moveEnd.emit();
+  assert.equal(requests[0].signal.aborted, true);
+  h.rectangle(boxA);
+  h.moveEnd.emit();
+  assert.equal(
+    h.timers.size,
+    1,
+    'returning to aborted A schedules its replacement',
+  );
+  requests[0].resolve([base]);
+  assert.equal(await pending, true);
+  assert.equal(h.layer.getStats().count, 0);
+  const [timerId, timer] = [...h.timers][0];
+  h.timers.delete(timerId);
+  h.time(NOW + timer.delay);
+  timer.fn();
+  assert.equal(requests.length, 2);
+  assert.deepEqual(requests[1].boxes, requests[0].boxes);
+  assert.equal(requests[1].signal.aborted, false);
+  requests[1].resolve([base]);
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(h.layer.getStats().count, 1);
+  assert.equal(h.layer.getStats().error, null);
+  assert.equal(h.timers.size, 0);
+  h.layer.destroy();
+});
+
+test('a completed A stays reusable when only the B debounce was pending', async () => {
+  let calls = 0;
+  const h = harness({
+    getSnapshot: async () => {
+      calls++;
+      return [base];
+    },
+  });
+  await h.update();
+  h.rectangle({ south: 48, west: -123, north: 48.4, east: -122.6 });
+  h.moveEnd.emit();
+  assert.equal(h.timers.size, 1);
+  h.rectangle({ south: 47.4, west: -122.7, north: 47.9, east: -122.1 });
+  h.moveEnd.emit();
+  assert.equal(h.timers.size, 0);
+  assert.equal(calls, 1);
+  assert.equal(h.layer.getStats().count, 1);
+  h.layer.destroy();
+});
+
+test('an externally aborted attempt does not suppress a camera retry in the same box', async () => {
+  const requests = [];
+  const h = harness({
+    getSnapshot: ({ signal }) =>
+      new Promise((resolve) => {
+        requests.push({ signal, resolve });
+      }),
+  });
+  const controller = new AbortController();
+  const pending = h.update(undefined, { signal: controller.signal });
+  controller.abort();
+  h.moveEnd.emit();
+  assert.equal(requests[0].signal.aborted, true);
+  assert.equal(h.timers.size, 1);
+  requests[0].resolve([base]);
+  assert.equal(await pending, false);
+  const [timerId, timer] = [...h.timers][0];
+  h.timers.delete(timerId);
+  h.time(NOW + timer.delay);
+  timer.fn();
+  assert.equal(requests.length, 2);
+  requests[1].resolve([base]);
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(h.layer.getStats().count, 1);
+  h.layer.destroy();
+});
+
+test('the real manager keeps first enable on after a pan supersedes either a success or a failure', async () => {
+  for (const reject of [false, true]) {
+    for (const debounceBeforeSettlement of [false, true]) {
+      const requests = [];
+      const h = harness(
+        {
+          getSnapshot: ({ signal, boxes }) =>
+            new Promise((resolve, fail) => {
+              requests.push({ signal, boxes, resolve, fail });
+            }),
+        },
+        {},
+        { autoEnable: false },
+      );
+      const manager = new LayerLifecycle(h.viewer);
+      manager.register(h.layer);
+      h.layer.attachDataManager(manager);
+      const fireCameraTimer = () => {
+        assert.equal(h.timers.size, 1);
+        const [timerId, timer] = [...h.timers][0];
+        h.timers.delete(timerId);
+        h.time(NOW + 2500);
+        timer.fn();
+      };
+      try {
+        const enabling = manager.setEnabled(h.layer.id, true);
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.equal(requests.length, 0, 'startup settles before dispatch');
+        fireCameraTimer();
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.equal(requests.length, 1);
+        h.rectangle({ south: 48, west: -123, north: 48.4, east: -122.6 });
+        h.moveEnd.emit();
+        assert.equal(requests[0].signal.aborted, true);
+        if (debounceBeforeSettlement) {
+          fireCameraTimer();
+          await new Promise((resolve) => setImmediate(resolve));
+          assert.equal(
+            requests.length,
+            1,
+            'manager cannot refresh during initial enable',
+          );
+          assert.equal(h.timers.size, 0);
+        }
+        if (reject) requests[0].fail(Error('iNaturalist HTTP 502'));
+        else requests[0].resolve([base]);
+        assert.equal(await enabling, true);
+        assert.equal(manager.isEnabled(h.layer.id), true);
+        assert.equal(h.owners.size, 1);
+        assert.equal(
+          h.layer.getStats().count,
+          0,
+          'superseded rows never publish',
+        );
+        assert.equal(
+          h.layer.getStats().error,
+          null,
+          'superseded errors never publish',
+        );
+        assert.equal(h.layer.getStats().lastUpdate, null);
+        fireCameraTimer();
+        assert.equal(
+          requests.length,
+          2,
+          'settled enable recovers the latest query',
+        );
+        assert.equal(requests[1].boxes[0].south, 48);
+        requests[1].resolve([
+          { ...base, stableId: 'inat:2', lat: 48.2, lon: -122.8 },
+        ]);
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.equal(manager.isEnabled(h.layer.id), true);
+        assert.equal(h.layer.getStats().count, 1);
+        assert.equal(manager.layers.get(h.layer.id).managerRefreshError, null);
+        assert.equal(h.owners.get(h.layer.id)('wildlife:inat:2'), true);
+      } finally {
+        await manager.destroyLayer(h.layer.id);
+      }
+      assert.equal(h.owners.size, 0);
+      assert.equal(h.moveEnd.count(), 0);
+      assert.equal(manager._listeners.size, 0);
+    }
+  }
+});
+
+test('first enable settles once and publishes badges within two seconds without restarting its fetch set', async (t) => {
+  let finishObservations;
+  const requests = [];
+  let gridSets = 0;
+  const row = { ...base, lat: 48.2, lon: -122.8 };
+  const h = harness(
+    {
+      getSnapshot({ signal, boxes }) {
+        requests.push({ signal, boxes });
+        return new Promise((resolve) => {
+          finishObservations = resolve;
+        });
+      },
+      async getGridSnapshot({ tiles, signal }) {
+        gridSets++;
+        assert.ok(tiles.length <= 6);
+        assert.equal(signal.aborted, false);
+        return {
+          cells: [
+            gridCell(tiles[0].z, {
+              id: wildlifeGridCellId(row.lat, row.lon, tiles[0].z),
+              lat: row.lat,
+              lon: row.lon,
+            }),
+          ],
+          totalResults: 12,
+          fetchedAt: NOW,
+        };
+      },
+    },
+    {},
+    { autoEnable: false },
+  );
+  const manager = new LayerLifecycle(h.viewer);
+  manager.register(h.layer);
+  h.layer.attachDataManager(manager);
+  try {
+    const enabling = manager.setEnabled(h.layer.id, true);
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(requests.length, 0);
+    h.time(NOW + 100);
+    h.rectangle({ south: 48, west: -123, north: 48.4, east: -122.6 });
+    h.moveEnd.emit();
+    assert.equal(h.timers.size, 1, 'one camera settle timer');
+    const [id, timer] = [...h.timers][0];
+    h.timers.delete(id);
+    h.time(NOW + 400);
+    timer.fn();
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(requests.length, 1);
+    assert.equal(requests[0].boxes[0].south, 48);
+    h.moveEnd.emit();
+    assert.equal(requests[0].signal.aborted, false);
+    h.time(NOW + 550); // Ordinary upstream response after 150 ms.
+    finishObservations([row]);
+    assert.equal(await enabling, true);
+    assert.equal(h.clicks.collection.values[0]?.id, 'wildlife:inat:1');
+    assert.equal(requests.length, 1);
+    assert.equal(gridSets, 1);
+    assert.equal(
+      h.timers.size,
+      1,
+      'only the bounded density fade is scheduled',
+    );
+    t.diagnostic(
+      'Deterministic first badge: 550 ms (100 ms camera adjustment + 300 ms settle + 150 ms upstream); one observation set and one tile set, zero aborts.',
+    );
+  } finally {
+    finishObservations?.([row]);
+    await manager.destroyLayer(h.layer.id);
+  }
+});
+
+test('the real manager does not report a refresh error when a pan supersedes periodic acquisition', async () => {
+  let ready = true;
+  let settle;
+  const h = harness(
+    {
+      getSnapshot: async () => {
+        if (ready) return [base];
+        return new Promise((resolve) => {
+          settle = resolve;
+        });
+      },
+    },
+    {},
+    { autoEnable: false },
+  );
+  const manager = new LayerLifecycle(h.viewer);
+  manager.register(h.layer);
+  h.layer.attachDataManager(manager);
+  try {
+    const enabling = manager.setEnabled(h.layer.id, true);
+    await new Promise((resolve) => setImmediate(resolve));
+    const [id, timer] = [...h.timers][0];
+    h.timers.delete(id);
+    h.time(NOW + timer.delay);
+    timer.fn();
+    assert.equal(await enabling, true);
+    ready = false;
+    const refreshing = manager.refreshLayer(h.layer.id);
+    h.rectangle({ south: 48, west: -123, north: 48.4, east: -122.6 });
+    h.moveEnd.emit();
+    settle([base]);
+    assert.equal(await refreshing, true);
+    assert.equal(manager.isEnabled(h.layer.id), true);
+    assert.equal(manager.layers.get(h.layer.id).managerRefreshError, null);
+    assert.equal(h.layer.getStats().error, null);
+  } finally {
+    await manager.destroyLayer(h.layer.id);
+  }
+});
+
+test('legend keeps semantic order, omits zero groups and puts one blurb first; stats expose only contract fields', async () => {
+  const rows = [
+    base,
+    { ...base, stableId: 'inat:2', iconic: 'Fungi', lon: -122.3 },
+    { ...base, stableId: 'inat:3', iconic: 'Unknown', lon: -122.2 },
+  ];
+  const h = harness({ getSnapshot: async () => rows });
+  await h.update();
+  const controls = h.layer.getRowControls();
+  assert.equal(controls.chips.length, 7);
+  assert.equal(controls.chips.filter((chip) => chip.label === 'ALL').length, 1);
+  assert.deepEqual(
+    controls.legend.map((entry) => entry.label),
+    ['Birds', 'Fungi', 'Other or unknown'],
+  );
+  assert.deepEqual(
+    ICONIC_LEGEND_ORDER.filter((group) =>
+      ['Aves', 'Fungi', 'Unknown'].includes(group),
+    ),
+    ['Aves', 'Fungi', 'Unknown'],
+  );
+  assert.equal(controls.legend.filter((entry) => entry.blurb).length, 1);
+  assert.match(controls.legend[0].blurb, /Not a census/);
+  const allowed = new Set([
+    'count',
+    'lastUpdate',
+    'error',
+    'stale',
+    'loading',
+    'refreshing',
+    'loadingLabel',
+    'partial',
+    'rawRowCount',
+    'countLabel',
+    'status',
+    'statusMessage',
+    'retryInSec',
+  ]);
+  assert.ok(Object.keys(h.layer.getStats()).every((key) => allowed.has(key)));
+  h.layer.destroy();
+});
+
+test('filter chips keep failed desired params active, expose retry and activate normally after recovery', async () => {
+  let fail = false;
+  const h = harness({
+    getSnapshot: async () => {
+      if (fail) throw Error('iNaturalist HTTP 502');
+      return [base];
+    },
+  });
+  await h.update();
+  h.layer.setParams({ taxa: 'whales', confirmed: true, ignored: 'x' });
+  let chips = h.layer.getRowControls().chips;
+  const whale = () => chips.find((chip) => chip.id === 'taxa-whales');
+  assert.equal(whale().state, 'loading');
+  assert.equal(whale().active, false);
+  assert.equal(whale().disabled, true);
+  fail = true;
+  await h.update();
+  chips = h.layer.getRowControls().chips;
+  assert.equal(whale().state, 'error');
+  assert.equal(whale().disabled, false);
+  assert.deepEqual(h.layer.getParams(), { confirmed: true, taxa: 'whales' });
+  assert.deepEqual(chips[0].params, { confirmed: true });
+  fail = false;
+  assert.equal(whale().active, true);
+  h.layer.setParams(whale().params);
+  h.time(NOW + 31_000);
+  await h.update();
+  chips = h.layer.getRowControls().chips;
+  assert.equal(whale().state, 'active');
+  assert.equal(chips[0].active, true);
+  h.layer.destroy();
+});
+
+test('disjoint option edits retain every unresolved chip through revert, failure, retry and success', async () => {
+  let fail = false;
+  const h = harness({
+    getSnapshot: async () => {
+      if (fail) throw Error('iNaturalist HTTP 502');
+      return [base];
+    },
+  });
+  await h.update();
+  const chip = (id) =>
+    h.layer.getRowControls().chips.find((item) => item.id === id);
+  h.layer.setParams({ confirmed: true });
+  h.layer.setParams({ taxa: 'Aves' });
+  for (const id of ['quality-confirmed', 'taxa-birds']) {
+    assert.equal(chip(id).state, 'loading');
+    assert.equal(chip(id).busy, true);
+    assert.equal(chip(id).disabled, true);
+    assert.equal(chip(id).active, false);
+  }
+  assert.equal(
+    chip('taxa-all').active,
+    true,
+    'the last accepted taxa remains active',
+  );
+  h.layer.setParams({ confirmed: false });
+  assert.equal(chip('quality-confirmed').state, 'idle');
+  assert.equal(chip('quality-confirmed').busy, false);
+  assert.equal(chip('taxa-birds').state, 'loading');
+  h.layer.setParams({ confirmed: true });
+  fail = true;
+  await h.update();
+  for (const id of ['quality-confirmed', 'taxa-birds']) {
+    assert.equal(chip(id).state, 'error');
+    assert.equal(chip(id).disabled, false);
+    assert.equal(chip(id).active, true);
+    assert.match(chip(id).title, /click to retry/);
+  }
+  assert.deepEqual(chip('quality-confirmed').params, { confirmed: true });
+  h.layer.setParams(chip('taxa-birds').params);
+  for (const id of ['quality-confirmed', 'taxa-birds'])
+    assert.equal(
+      chip(id).state,
+      'loading',
+      'unchanged desired params retry all unresolved options',
+    );
+  fail = false;
+  h.time(NOW + 31_000);
+  await h.update();
+  for (const id of ['quality-confirmed', 'taxa-birds']) {
+    assert.equal(chip(id).state, 'active');
+    assert.equal(chip(id).active, true);
+    assert.equal(chip(id).busy, false);
+    assert.equal(chip(id).disabled, false);
+  }
+  assert.equal(chip('taxa-all').active, false);
+  assert.deepEqual(h.layer.getParams(), { confirmed: true, taxa: 'Aves' });
+  h.layer.destroy();
+});
+
+test('the initial load keeps ALL pending and the default-off CONFIRMED chip idle', async () => {
+  let resolve;
+  const h = harness({
+    getSnapshot: () =>
+      new Promise((done) => {
+        resolve = done;
+      }),
+  });
+  const pending = h.update();
+  h.layer.setParams({ taxa: 'all', confirmed: false });
+  let chips = h.layer.getRowControls().chips;
+  assert.equal(chips.find((chip) => chip.id === 'taxa-all').state, 'loading');
+  assert.equal(
+    chips.find((chip) => chip.id === 'quality-confirmed').state,
+    'idle',
+  );
+  resolve([base]);
+  assert.equal(await pending, true);
+  chips = h.layer.getRowControls().chips;
+  assert.equal(chips.find((chip) => chip.id === 'taxa-all').state, 'active');
+  assert.equal(
+    chips.find((chip) => chip.id === 'quality-confirmed').state,
+    'idle',
+  );
+  h.layer.destroy();
+});
+
+test('global fallback hides cards and upstream totals, and caps retained observations', async () => {
+  let options;
+  const h = harness({
+    getSnapshot: async (value) => {
+      options = value;
+      return Array.from({ length: WILDLIFE_MAX_ROWS + 2 }, (_, index) => ({
+        ...photographed,
+        stableId: `inat:${index}`,
+      }));
+    },
+  });
+  h.viewer.camera.positionCartographic.height = 5_000_000;
+  await h.update();
+  assert.equal(options.scope, 'global');
+  assert.equal(options.boxes, null);
+  assert.equal(h.layer.getStats().count, WILDLIFE_MAX_ROWS);
+  assert.equal(layerFeedState(h.layer.getStats()), 'nominal');
+  assert.equal(h.layer.getStats().partial, undefined);
+  assert.match(h.layer.getStats().countLabel, /sightings in view/);
+  assert.equal(h.overlay.entries.get('wildlife-sightings').length, 0);
+  h.layer.destroy();
+});
+
+test('a missing regional query does not claim zoom guidance at a local camera height', async () => {
+  const h = harness({
+    getSnapshot: () => assert.fail('wide regional view fetched'),
+  });
+  h.rectangle({ south: 20, west: -150, north: 60, east: -90 });
+  assert.equal(await h.update(), true);
+  assert.equal(h.layer.getStats().status, undefined);
+  assert.equal(h.layer.getStats().statusMessage, undefined);
+  h.layer.destroy();
+});
+
+test('a successful empty page keeps the selected observation until explicit deselection', async () => {
+  let rows = [base];
+  const h = harness({ getSnapshot: async () => rows });
+  await h.update();
+  h.layer.selectSighting(base.stableId);
+  rows = [];
+  await h.update();
+  assert.equal(h.clicks.collection.values.length, 1);
+  assert.equal(h.store.selectedEntityId, base.stableId);
+  h.layer.clearSightingSelection();
+  await h.update();
+  assert.equal(h.clicks.collection.values.length, 0);
+  assert.equal(h.store.selectedEntityId, null);
+  h.layer.destroy();
+});
+
+test('provider credits sit in the layer row, never on the globe; Acartia failure still surfaces degradation', async () => {
+  let healthy = true;
+  const acartia = {
+    ...base,
+    stableId: 'acartia:1',
+    origin: 'acartia',
+    iconic: 'Mammalia',
+    provider: { name: 'Synthetic Provider', entity: null },
+  };
+  const h = harness({
+    getSnapshot: async () => [],
+    getSnapshotDetail: async () => ({
+      rows: healthy ? [base, acartia] : [base],
+      sources: { acartia: { ok: healthy } },
+    }),
+  });
+  await h.update();
+  const onGlobe = () =>
+    [...h.credits].filter((credit) => credit.showOnScreen).length;
+  assert.equal(onGlobe(), 0, 'no credit on the globe credit line');
+  assert.equal(
+    h.layer.getRowControls().info,
+    'iNaturalist contributors · Acartia 1 (Salish Sea) · licences per record',
+  );
+  healthy = false;
+  await h.update();
+  assert.equal(h.layer.getStats().error, 'Acartia feed unavailable');
+  assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+  assert.equal(
+    h.layer.getRowControls().info,
+    'iNaturalist contributors · licences per record',
+  );
+  assert.equal(onGlobe(), 0);
+  h.layer.disable();
+  assert.equal(onGlobe(), 0);
+  h.layer.destroy();
+});
+
+test('ambient cards prefilter the horizon, spread over screen regions and retain visible slots', async () => {
+  const rows = Array.from({ length: 32 }, (_, i) => ({
+    ...photographed,
+    stableId: `inat:${String(i + 1).padStart(2, '0')}`,
+    lon: -122.5 + i * 0.01,
+    favesCount: 1000 - i,
+  }));
+  const screens = new Map(
+    rows.map((row, i) => [
+      row.stableId,
+      {
+        x: 130 + (i % 8) * 150,
+        y: 130 + Math.floor(i / 8) * 150,
+      },
+    ]),
+  );
+  rows.push(
+    {
+      ...photographed,
+      stableId: 'inat:overlap',
+      lon: -122.17,
+      favesCount: 999.5,
+    },
+    {
+      ...photographed,
+      stableId: 'inat:edge',
+      lon: -122.16,
+      favesCount: 999.25,
+    },
+  );
+  screens.set('inat:overlap', { x: 241, y: 130 }); // Same occupied region.
+  screens.set('inat:edge', { x: 130, y: 242 }); // Spacing alone cannot admit a second card in that region.
+  rows.unshift({
+    ...photographed,
+    stableId: 'inat:far',
+    lon: -122.6,
+    favesCount: 100000,
+  });
+  const h = harness(
+    { getSnapshot: async () => rows },
+    {
+      occluderFactory: () => ({
+        isPointVisible: (position) =>
+          Cesium.Math.toDegrees(
+            Cesium.Cartographic.fromCartesian(position).longitude,
+          ) > -122.55,
+      }),
+      project: (_scene, position) =>
+        screens.get(
+          rows.find(
+            (row) =>
+              Math.abs(
+                row.lon -
+                  Cesium.Math.toDegrees(
+                    Cesium.Cartographic.fromCartesian(position).longitude,
+                  ),
+              ) < 1e-7,
+          )?.stableId,
+        ),
+    },
+  );
+  await h.update();
+  const entries = h.overlay.entries.get('wildlife-sightings');
+  assert.equal(entries.length, 6);
+  const expected = [
+    'inat:01',
+    'inat:04',
+    'inat:07',
+    'inat:17',
+    'inat:20',
+    'inat:23',
+  ];
+  const assertCohort = (cohort) => {
+    assert.deepEqual(
+      cohort.map((entry) => entry.id),
+      expected.map((id) => `sighting:${id}`),
+    );
+    for (let i = 0; i < cohort.length; i++) {
+      const a = screens.get(cohort[i].id.slice('sighting:'.length));
+      for (let j = i + 1; j < cohort.length; j++) {
+        const b = screens.get(cohort[j].id.slice('sighting:'.length));
+        assert.ok(
+          Math.hypot(a.x - b.x, a.y - b.y) >= 112,
+          `${cohort[i].id} overlaps ${cohort[j].id}`,
+        );
+      }
+    }
+  };
+  assertCohort(entries);
+  const farDot = h.clicks.collection.values.find(
+    (point) => point.id === 'wildlife:inat:far',
+  );
+  assert.ok(!farDot || farDot.show === false);
+  assert.equal(h.postRender.count(), 0);
+  h.layer.selectSighting('inat:01');
+  const selected = h.overlay.entries.get('wildlife-sightings-selected');
+  h.moveEnd.emit();
+  assert.equal(
+    h.overlay.entries.get('wildlife-sightings-selected'),
+    selected,
+    'moveEnd never republishes selected cards',
+  );
+  assert.equal(h.overlay.entries.get('wildlife-sightings').length, 6);
+  assertCohort(h.overlay.entries.get('wildlife-sightings'));
+  h.layer.destroy();
+});
+
+function gridCell(z, extra = {}) {
+  return {
+    id: wildlifeGridCellId(base.lat, base.lon, z),
+    lat: base.lat,
+    lon: base.lon,
+    cellCount: 12,
+    ...extra,
+  };
+}
+
+// Keep request/selection fixtures compact enough for the six-tile budget.
+function gridHarness(source, extra) {
+  return harness(source, extra, { width: 896, height: 896 });
+}
+
+test('observations publish real badges while grid acquisition is still pending', async () => {
+  let finishGrid;
+  const h = gridHarness({
+    getSnapshot: async () => [base],
+    getGridSnapshot: () =>
+      new Promise((resolve) => {
+        finishGrid = resolve;
+      }),
+  });
+  h.time(NOW + 500);
+  const updating = h.layer.update();
+  try {
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(h.clicks.collection.values[0]?.id, 'wildlife:inat:1');
+    assert.equal(h.layer.getStats().count, 1);
+    assert.equal(h.postRender.count(), 0, 'acquisition adds no frame work');
+  } finally {
+    finishGrid({ cells: [], totalResults: 0, fetchedAt: NOW });
+    await updating;
+    await new Promise((resolve) => setImmediate(resolve));
+    h.layer.destroy();
+  }
+});
+
+test('each arriving tile extends the density glow before the remaining tiles finish', async () => {
+  let publishTile;
+  let finishGrid;
+  let cells;
+  let tiles;
+  const h = gridHarness({
+    getSnapshot: async () => [],
+    getGridSnapshot(options) {
+      publishTile = options.onTile;
+      tiles = options.tiles;
+      cells = [
+        gridCell(tiles[0].z),
+        gridCell(tiles[0].z, {
+          id: wildlifeGridCellId(base.lat, base.lon + 0.2, tiles[0].z),
+          lon: base.lon + 0.2,
+          cellCount: 9,
+        }),
+      ];
+      return new Promise((resolve) => {
+        finishGrid = resolve;
+      });
+    },
+  });
+  h.time(NOW + 500);
+  const updating = h.layer.update();
+  try {
+    await new Promise((resolve) => setImmediate(resolve));
+    publishTile?.(
+      { cells: [cells[0]], totalResults: 12, fetchedAt: NOW },
+      { tile: tiles[0] },
+    );
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(h.clicks.collection.values.length, 0);
+    const glow = h.pointOwners.values.find(
+      (collection) => collection.allowPicking === false,
+    );
+    assert.equal(glow.values.length, 1);
+    assert.equal(h.layer.getStats().countLabel, '12 sightings in view');
+    publishTile?.(
+      { cells: [cells[1]], totalResults: 9, fetchedAt: NOW },
+      { tile: tiles[1] || tiles[0] },
+    );
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(h.clicks.collection.values.length, 0);
+    assert.equal(glow.values.length, 2);
+    assert.equal(h.layer.getStats().countLabel, '21 sightings in view');
+    assert.equal(h.postRender.count(), 0);
+  } finally {
+    finishGrid({ cells, totalResults: 21, fetchedAt: NOW });
+    await updating;
+    await new Promise((resolve) => setImmediate(resolve));
+    h.layer.destroy();
+  }
+});
+
+test('grid-only views draw nonpickable glow without observation badges, labels or cards', async () => {
+  const h = gridHarness({
+    getSnapshot: async () => [],
+    getGridSnapshot: async ({ tiles }) => ({
+      cells: [gridCell(tiles[0].z)],
+      totalResults: 12,
+      fetchedAt: NOW,
+    }),
+  });
+  h.viewer.camera.positionCartographic.height = 1_500_000;
+  await h.update();
+  assert.equal(h.clicks.collection.values.length, 0);
+  const glow = h.pointOwners.values.find(
+    (collection) => collection.allowPicking === false,
+  );
+  assert.ok(glow);
+  assert.equal(glow.values.length, 1);
+  assert.equal(glow.values[0].id, undefined, 'density has no pick identity');
+  assert.equal(h.layer.getStats().countLabel, '12 sightings in view');
+  assert.deepEqual(h.overlay.entries.get('wildlife-sightings-labels'), []);
+  assert.deepEqual(h.overlay.entries.get('wildlife-sightings-selected'), []);
+  assert.equal(h.focus.length, 0);
+  assert.equal(h.postRender.count(), 0);
+  h.layer.disable();
+  assert.equal(glow.destroyed, true);
+  assert.equal(h.timers.size, 0);
+  assert.equal(
+    h.pointOwners.values.length,
+    1,
+    'only the empty observation collection remains',
+  );
+  h.layer.enable(h.viewer);
+  await h.update();
+  const restored = h.pointOwners.values.find(
+    (collection) => collection.allowPicking === false,
+  );
+  assert.ok(restored);
+  h.layer.destroy();
+  assert.equal(restored.destroyed, true);
+  assert.equal(h.pointOwners.values.length, 0);
+  assert.equal(h.timers.size, 0);
+});
+
+test('height and upstream sample totals retain the same loaded sighting and grid count', async () => {
+  let partialSample = false;
+  let gridRequests = 0;
+  const h = gridHarness({
+    getSnapshot: async () => [base],
+    getSnapshotDetail: async () => ({
+      rows: [base],
+      totalResults: partialSample ? 100 : 1,
+      partial: partialSample,
+    }),
+    async getGridSnapshot({ tiles }) {
+      gridRequests++;
+      return {
+        cells: [gridCell(tiles[0].z)],
+        totalResults: 12,
+        fetchedAt: NOW,
+      };
+    },
+  });
+  await h.update();
+  assert.equal(h.clicks.collection.values[0].id, 'wildlife:inat:1');
+  h.viewer.camera.positionCartographic.height = 450_000;
+  await h.update();
+  assert.equal(h.clicks.collection.values[0].id, 'wildlife:inat:1');
+  h.viewer.camera.positionCartographic.height = 410_000;
+  h.moveEnd.emit();
+  assert.equal(h.clicks.collection.values[0].id, 'wildlife:inat:1');
+  h.viewer.camera.positionCartographic.height = 350_000;
+  await h.update();
+  assert.equal(h.clicks.collection.values[0].id, 'wildlife:inat:1');
+  h.viewer.camera.positionCartographic.height = 30_000;
+  partialSample = true;
+  await h.update();
+  assert.equal(h.clicks.collection.values[0].id, 'wildlife:inat:1');
+  assert.equal(gridRequests, 4);
+  assert.equal(h.layer.getStats().countLabel, '12 sightings in view');
+  assert.equal(layerFeedState(h.layer.getStats()), 'nominal');
+  h.layer.destroy();
+});
+
+test('close and wide views wait for loaded common-name labels without unnamed label candidates or frame work', async (t) => {
+  for (const heightM of [30_000, 7_000_000]) {
+    let rows = [{ ...base, commonName: null }];
+    let projections = 0;
+    const h = gridHarness(
+      {
+        getSnapshot: async () => rows,
+        getGridSnapshot: async ({ tiles }) => ({
+          cells: [gridCell(tiles[0].z)],
+          fetchedAt: NOW,
+        }),
+      },
+      {
+        project() {
+          projections++;
+          return { x: 400, y: 400 };
+        },
+      },
+    );
+    t.after(() => h.layer.destroy());
+    h.viewer.camera.positionCartographic.height = heightM;
+    await h.update();
+    const point = h.clicks.collection.values[0];
+    assert.ok(point, `${heightM}m: unnamed contacts still have icons`);
+    assert.deepEqual(h.overlay.entries.get('wildlife-sightings-labels'), []);
+    // Only observation icons require screen projections; unnamed contacts
+    // never add the separate label candidate pass.
+    assert.equal(
+      projections,
+      1,
+      'only the real observation is projected; unnamed rows add no label pass',
+    );
+    assert.equal(h.postRender.count(), 0);
+
+    rows = [{ ...base, commonName: 'Red-tailed Hawk' }];
+    await h.update();
+    assert.equal(
+      h.clicks.collection.values[0],
+      point,
+      `${heightM}m: a newly known name reuses the icon`,
+    );
+    const labels = h.overlay.entries.get('wildlife-sightings-labels');
+    assert.equal(labels.length, 1);
+    assert.equal(labels[0].title, 'RED-TAILED HAWK');
+    assert.equal(labels[0].collisionGroup, 'ambient-label');
+    assert.equal(labels[0].protected, undefined);
+    assert.equal(labels[0].selected, undefined);
+    const settled = projections;
+    for (let frame = 0; frame < 10; frame++) h.postRender.emit();
+    assert.equal(
+      projections,
+      settled,
+      `${heightM}m: parked frames never rebuild label candidates`,
+    );
+
+    rows = [{ ...base, commonName: '  ' }];
+    await h.update();
+    assert.deepEqual(h.overlay.entries.get('wildlife-sightings-labels'), []);
+    h.layer.destroy();
+  }
+});
+
+test('selecting an unnamed observation preserves the selection without inventing a category label', async (t) => {
+  const h = harness({
+    getSnapshot: async () => [{ ...base, commonName: null }],
+  });
+  t.after(() => h.layer.destroy());
+  const selections = [];
+  h.layer.subscribeSelection((row) => selections.push(row));
+  await h.update();
+  h.pick({ id: h.clicks.collection.values[0].id });
+  h.clicks.callback({ position: { x: 400, y: 400 } });
+  assert.equal(selections.at(-1).stableId, base.stableId);
+  assert.deepEqual(h.overlay.entries.get('wildlife-sightings-selected'), []);
+  assert.deepEqual(h.overlay.entries.get('wildlife-sightings-labels'), []);
+});
+
+test('unavailable grids fail closed to visible sampled sprites without a global newest-total claim', async () => {
+  const h = gridHarness({
+    getSnapshot: async () => [base],
+    getSnapshotDetail: async () => ({
+      rows: [base],
+      totalResults: 160645,
+      partial: true,
+    }),
+    getGridSnapshot: async () => {
+      throw Error('Malformed iNaturalist grid response');
+    },
+  });
+  h.viewer.camera.positionCartographic.height = 5_000_000;
+  await h.update();
+  assert.equal(h.clicks.collection.values[0].id, 'wildlife:inat:1');
+  assert.ok(h.clicks.collection.values[0].width * 0.5 >= 8);
+  assert.equal(h.layer.getStats().count, 1);
+  assert.match(h.layer.getStats().countLabel, /sightings in view/);
+  assert.equal(h.layer.getStats().partial, undefined);
+  assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+  assert.match(h.layer.getStats().error, /Malformed iNaturalist grid response/);
+  assert.equal(
+    h.layer.getStats().retryInSec,
+    undefined,
+    'schema errors do not start upstream cooldown',
+  );
+  assert.equal(
+    h.overlay.entries.get('wildlife-sightings-labels')[0].title,
+    'SYNTHETIC BIRD',
+  );
+  h.layer.destroy();
+});
+
+test('an oversized view coarsens to a complete grid within the six-tile cap', async () => {
+  const h = harness(
+    {
+      getSnapshot: async () => [base],
+      getGridSnapshot: async ({ tiles }) => {
+        assert.ok(tiles.length > 0 && tiles.length <= 6);
+        return {
+          cells: [gridCell(tiles[0].z)],
+          totalResults: 12,
+          fetchedAt: NOW,
+        };
+      },
+    },
+    { project: () => ({ x: 400, y: 400 }) },
+    { width: 4000, height: 4000 },
+  );
+  h.rectangle({ south: -85, west: -180, north: 85, east: 180 });
+  h.viewer.camera.positionCartographic.height = 7_000_000;
+  await h.update();
+  assert.equal(h.clicks.collection.values.length, 1);
+  assert.equal(h.clicks.collection.values[0].id, 'wildlife:inat:1');
+  assert.match(h.layer.getStats().countLabel, /sightings in view/);
+  assert.equal(layerFeedState(h.layer.getStats()), 'nominal');
+  h.layer.destroy();
+});
+
+test('label candidates are bounded after on-screen and horizon filtering, with names only', async () => {
+  const rows = Array.from({ length: 220 }, (_, index) => ({
+    ...base,
+    stableId: `inat:${index}`,
+    commonName: `Synthetic bird ${index}`,
+    lat: 47.5 + index / 2000,
+    lon: -122.5 + index / 2000,
+  }));
+  const h = harness(
+    { getSnapshot: async () => rows },
+    {
+      project: (_scene, position) => ({
+        x:
+          Cesium.Cartographic.fromCartesian(position).latitude >
+          Cesium.Math.toRadians(47.6)
+            ? 3000
+            : 30 +
+              (Math.round(
+                (Cesium.Math.toDegrees(
+                  Cesium.Cartographic.fromCartesian(position).latitude,
+                ) -
+                  47.5) *
+                  2000,
+              ) %
+                50) *
+                28,
+        y:
+          30 +
+          Math.floor(
+            Math.round(
+              (Cesium.Math.toDegrees(
+                Cesium.Cartographic.fromCartesian(position).latitude,
+              ) -
+                47.5) *
+                2000,
+            ) / 50,
+          ) *
+            28,
+      }),
+      occluderFactory: () => ({
+        isPointVisible: (position) =>
+          Cesium.Cartographic.fromCartesian(position).latitude <
+          Cesium.Math.toRadians(47.59),
+      }),
+    },
+  );
+  await h.update();
+  const labels = h.overlay.entries.get('wildlife-sightings-labels');
+  assert.equal(labels.length, 150);
+  assert.ok(
+    labels.every(
+      (entry) =>
+        entry.title.startsWith('SYNTHETIC BIRD ') &&
+        entry.details === undefined,
+    ),
+  );
+  assert.ok(
+    labels.every(
+      (entry) =>
+        Cesium.Cartographic.fromCartesian(entry.position).latitude <
+        Cesium.Math.toRadians(47.59),
+    ),
+  );
+  assert.equal(h.postRender.count(), 0);
+  h.layer.destroy();
+});
+
+test('accepted observation refreshes publish immediately and disable clears their badges', async () => {
+  let rows = [base];
+  const h = harness({ getSnapshot: async () => rows });
+  await h.update();
+  const point = h.clicks.collection.values[0];
+  for (const lon of [-122.35, -122.3, -122.25]) {
+    rows = [{ ...base, lon }];
+    await h.layer.update();
+    assert.equal(h.clicks.collection.values[0], point);
+    assert.ok(
+      Math.abs(
+        Cesium.Cartographic.fromCartesian(point.position).longitude -
+          Cesium.Math.toRadians(lon),
+      ) < 1e-12,
+    );
+    assert.equal(h.timers.size, 0, 'observation rendering adds no batch delay');
+  }
+  h.layer.disable();
+  assert.equal(h.timers.size, 0);
+  assert.equal(h.clicks.collection.values.length, 0);
+  h.layer.destroy();
+});
+
+test('a grid result for the previous global view cannot mark new camera tiles loaded', async () => {
+  let settle;
+  let requests = 0;
+  const h = gridHarness({
+    getSnapshot: async () => [base],
+    getGridSnapshot: ({ tiles }) => {
+      requests++;
+      return new Promise((resolve) => {
+        settle = () =>
+          resolve({
+            cells: [gridCell(tiles[0].z)],
+            totalResults: 12,
+            fetchedAt: NOW,
+          });
+      });
+    },
+  });
+  h.viewer.camera.positionCartographic.height = 5_000_000;
+  h.time(NOW + 500);
+  const updating = h.layer.update();
+  await new Promise((resolve) => setImmediate(resolve));
+  h.rectangle({ south: -30, west: 60, north: 20, east: 120 });
+  settle();
+  await updating;
+  assert.equal(
+    h.clicks.collection.values.filter((point) =>
+      point.id.startsWith('wildlife:grid:'),
+    ).length,
+    0,
+    'old tile result is rejected before moveEnd',
+  );
+  h.moveEnd.emit();
+  assert.equal(h.timers.size, 1, 'new camera view remains due for acquisition');
+  assert.equal(requests, 1);
+  h.layer.destroy();
+});
+
+test('clearing a selected contact restores its cached ambient label without projecting candidates again', async () => {
+  let projects = 0;
+  const h = harness(undefined, {
+    project: () => {
+      projects++;
+      return { x: 400, y: 400 };
+    },
+  });
+  await h.update();
+  const baseline = projects;
+  assert.equal(h.overlay.entries.get('wildlife-sightings-labels').length, 1);
+  h.pick({ id: 'wildlife:inat:1' });
+  const renders = h.renders.length;
+  h.clicks.callback({ position: { x: 1, y: 1 } });
+  assert.equal(h.renders.length - renders, 1);
+  assert.equal(h.overlay.entries.get('wildlife-sightings-labels').length, 0);
+  assert.equal(h.overlay.entries.get('wildlife-sightings-selected').length, 1);
+  h.layer.clearSightingSelection();
+  assert.equal(h.overlay.entries.get('wildlife-sightings-labels').length, 1);
+  assert.equal(h.overlay.entries.get('wildlife-sightings-selected').length, 0);
+  assert.equal(projects, baseline);
+  h.layer.destroy();
+});
+
+test('visible photo cards survive a pan into the same icon bucket and a different random sample', async () => {
+  let rows = [
+    photographed,
+    { ...photographed, stableId: 'inat:2', lon: -122.2 },
+  ];
+  let collapsed = false;
+  const h = harness(
+    { getSnapshot: async () => rows },
+    {
+      project: (_scene, position) => ({
+        x:
+          collapsed ||
+          Cesium.Math.toDegrees(
+            Cesium.Cartographic.fromCartesian(position).longitude,
+          ) < -122.3
+            ? 400
+            : 700,
+        y: 400,
+      }),
+    },
+  );
+  await h.update();
+  for (const image of h.images) image.onload?.();
+  const ids = () =>
+    h.overlay.entries
+      .get('wildlife-sightings')
+      .map((entry) => entry.id)
+      .sort();
+  const initial = ids();
+  assert.equal(initial.length, 2);
+  collapsed = true;
+  h.moveEnd.emit();
+  assert.equal(
+    h.clicks.collection.values.length,
+    1,
+    'one icon in the shared bucket',
+  );
+  assert.deepEqual(
+    ids(),
+    initial,
+    'both visible incumbent photo cards keep their anchors',
+  );
+  rows = [];
+  await h.update();
+  assert.deepEqual(
+    ids(),
+    initial,
+    'a fresh random sample cannot evict visible cards',
+  );
+  assert.equal(
+    h.layer.selectSighting('inat:2'),
+    true,
+    'retained card remains selectable',
+  );
+  h.layer.destroy();
+});
+
+test('cold ground cells start on the ellipsoid and one bounded resolve per batch lifts them, without scene sampling', async () => {
+  const h = harness(undefined, {}, { autoEnable: false });
+  let warm = false;
+  let reads = 0;
+  h.ground.sample = () => {
+    reads++;
+    return warm ? 250 : null;
+  };
+  h.layer.init(h.viewer);
+  h.layer.enable(h.viewer);
+  await h.update();
+  const point = h.clicks.collection.values[0];
+  const heightOf = () =>
+    Cesium.Cartographic.fromCartesian(point.position).height;
+  assert.ok(Math.abs(heightOf()) < 0.01, 'cold cell anchors on the ellipsoid');
+  assert.equal(h.ground.resolves, 1, 'one bounded resolve for the batch');
+  warm = true;
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.ok(Math.abs(heightOf() - 250) < 0.01, 'resolved cell lifts in place');
+  assert.equal(h.clicks.collection.values[0], point);
+  const before = reads;
+  h.moveEnd.emit();
+  assert.ok(reads - before <= h.clicks.collection.values.length);
+  assert.equal(h.ground.resolves, 1, 'warm cells do not resolve again');
+  h.layer.destroy();
+});
diff --git a/src/layers/wildlifeSightings/performance.js b/src/layers/wildlifeSightings/performance.js
new file mode 100644
index 000000000..da4c13717
--- /dev/null
+++ b/src/layers/wildlifeSightings/performance.js
@@ -0,0 +1,115 @@
+/** Camera work runs on moveEnd/data arrival only. Measures remain observable
+ * through PerformanceObserver while clearing entries prevents a long session
+ * accumulating one timing record for every pan and streamed tile. */
+export const WILDLIFE_MOVE_END_BUDGET_MS = 4;
+const measureSpans = new Map();
+
+function measureSpan(stage) {
+  let span = measureSpans.get(stage);
+  if (!span) {
+    span = { name: `wildlife-sightings:${stage}`, depth: 0, frames: [] };
+    measureSpans.set(stage, span);
+  }
+  const depth = span.depth++;
+  if (!span.frames[depth]) {
+    const start = `${span.name}:start:${depth}`;
+    span.frames[depth] = { start, options: { start } };
+  }
+  return span;
+}
+
+/** Measure a render phase without accumulating performance entries. */
+export function wildlifeMeasure(stage, work) {
+  const clock = globalThis.performance;
+  if (typeof clock?.mark !== 'function' || typeof clock?.measure !== 'function')
+    return work();
+  // Reuse names/options; nesting depth distinguishes simultaneous spans.
+  const span = measureSpan(stage);
+  const frame = span.frames[span.depth - 1];
+  clock.mark(frame.start);
+  try {
+    return work();
+  } finally {
+    clock.measure(span.name, frame.options);
+    clock.clearMarks?.(frame.start);
+    clock.clearMeasures?.(span.name);
+    span.depth--;
+  }
+}
+
+// A unit is at most 128 cells/billboards. The one-millisecond target leaves
+// room for the last unit, Cesium setters and the overlay host within 4ms.
+export const WILDLIFE_WORK_UNIT = 128;
+const WILDLIFE_WORK_SLICE_MS = 1;
+export const WILDLIFE_SYNC_CELL_LIMIT = 256;
+
+function wildlifeWorkStep(work, stage = 'bucket') {
+  return wildlifeMeasure(stage, () => work.next());
+}
+
+/** Run bounded work synchronously for a small population. */
+export function drainWildlifeWork(work) {
+  let stage = 'bucket';
+  for (;;) {
+    const step = wildlifeWorkStep(work, stage);
+    if (step.done) return step.value;
+    stage = step.value || stage;
+  }
+}
+
+/** A cancellable idle queue, never a frame listener. Superseding a camera view
+ * drops unrun work. No network or requestAnimationFrame enters this queue. */
+export function createWildlifeWorkQueue({
+  requestIdle = globalThis.requestIdleCallback?.bind(globalThis),
+  cancelIdle = globalThis.cancelIdleCallback?.bind(globalThis),
+  now = () => performance.now(),
+  onSlice = () => {},
+} = {}) {
+  let active = null;
+  function cancel() {
+    if (!active) return;
+    const old = active;
+    active = null;
+    if (requestIdle) cancelIdle?.(old.handle);
+    else clearTimeout(old.handle);
+    old.work.return?.();
+  }
+  function start(work, complete) {
+    cancel();
+    const job = { work, handle: null, stage: 'bucket' };
+    active = job;
+    function schedule() {
+      job.handle = requestIdle
+        ? requestIdle(run, { timeout: 32 })
+        : setTimeout(run, 0);
+    }
+    function run() {
+      if (active !== job) return;
+      const began = now();
+      let units = 0;
+      let result;
+      wildlifeMeasure('moveEnd:slice', () => {
+        do {
+          result = wildlifeWorkStep(work, job.stage);
+          units++;
+          if (result.done) {
+            active = null;
+            complete(result.value);
+            break;
+          }
+          job.stage = result.value || job.stage;
+        } while (units < 8 && now() - began < WILDLIFE_WORK_SLICE_MS);
+      });
+      onSlice({ startTimeMs: began, durationMs: now() - began, units });
+      if (!result.done && active === job) schedule();
+    }
+    schedule();
+  }
+  return {
+    start,
+    cancel,
+    get pending() {
+      return active !== null;
+    },
+  };
+}
diff --git a/src/layers/wildlifeSightings/performance.test.mjs b/src/layers/wildlifeSightings/performance.test.mjs
new file mode 100644
index 000000000..013ea958c
--- /dev/null
+++ b/src/layers/wildlifeSightings/performance.test.mjs
@@ -0,0 +1,299 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  harness,
+  syntheticRows,
+  changePositions,
+  WILDLIFE_BENCHMARK_REFRESHES,
+} from '../../testSupport/wildlifeBillboardModel.mjs';
+
+test('500 / 2,000 / 5,000 contacts write only position deltas and do no work for unchanged input', () => {
+  for (const n of [500, 2000, 5000]) {
+    const h = harness();
+    let rows = syntheticRows(n);
+    assert.equal(h.apply(rows).created, n);
+    const retained = h.pointById.get(rows[1].stableId);
+    for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
+      rows = changePositions(rows, refresh);
+      assert.deepEqual(h.apply(rows), {
+        created: 0,
+        removed: 0,
+        updated: n / 10,
+        writes: n / 10,
+      });
+      assert.equal(h.pointById.get(rows[1].stableId), retained);
+    }
+    assert.equal(h.counters.created, n);
+    assert.equal(h.counters.destroyed, 0);
+    const before = { ...h.counters };
+    assert.deepEqual(h.apply([...rows].reverse()), {
+      created: 0,
+      removed: 0,
+      updated: 0,
+      writes: 0,
+    });
+    assert.deepEqual(
+      h.counters,
+      before,
+      'unchanged content writes and allocates nothing',
+    );
+  }
+});
+
+test('ten 10% membership refreshes allocate and remove exactly their delta', (t) => {
+  const n = 2000;
+  const h = harness();
+  let rows = syntheticRows(n);
+  h.apply(rows);
+  const retainedId = rows[1].stableId;
+  const retained = h.pointById.get(retainedId);
+  for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
+    rows = rows.map((row, i) =>
+      i % 10 === 0 ? { ...row, stableId: `replacement:${refresh}:${i}` } : row,
+    );
+    assert.deepEqual(h.apply(rows), {
+      created: n / 10,
+      removed: n / 10,
+      updated: 0,
+      writes: (n / 10) * 5,
+    });
+    assert.equal(h.pointById.get(retainedId), retained);
+    assert.equal(h.points.size, n);
+  }
+  assert.equal(h.counters.created, n + (n / 10) * WILDLIFE_BENCHMARK_REFRESHES);
+  assert.equal(h.counters.destroyed, (n / 10) * WILDLIFE_BENCHMARK_REFRESHES);
+  t.diagnostic(
+    `N=${n}, 10 refreshes: initial creates=${n}, delta creates=2000, delta removes=2000, retained billboard identity unchanged`,
+  );
+});
+
+test('count, grade and name edits produce no billboard writes or resampling', () => {
+  const h = harness();
+  const rows = syntheticRows(500);
+  h.model.update(rows);
+  const before = { ...h.counters };
+  assert.deepEqual(
+    h.model.update(
+      rows.map((row) => ({
+        ...row,
+        count: 1000,
+        quality: 'needs_id',
+        commonName: 'Synthetic name',
+      })),
+    ),
+    { created: 0, removed: 0, updated: 0, writes: 0 },
+  );
+  assert.deepEqual(h.counters, before);
+});
+
+import { PerformanceObserver } from 'node:perf_hooks';
+import {
+  denseContinentalRendering,
+  DENSE_CONTINENT_CELLS,
+  DENSE_CONTINENT_ROWS,
+} from './renderPerformanceFixtures.mjs';
+import {
+  WILDLIFE_MOVE_END_BUDGET_MS,
+  WILDLIFE_WORK_UNIT,
+  createWildlifeWorkQueue,
+} from './performance.js';
+
+test('dense continental moveEnd has a deterministic linear operation budget and reuses decoded metadata/coordinates', () => {
+  const h = denseContinentalRendering();
+  try {
+    assert.equal(
+      h.moveEnd(),
+      'pending',
+      'dense work must yield before blocking camera input',
+    );
+    assert.equal(
+      h.metrics.projections,
+      0,
+      'moveEnd enqueues work without processing a tile',
+    );
+    const cold = h.flush();
+    assert.ok(
+      cold.glowPrimitives > 4000 &&
+        cold.billboards > 50 &&
+        cold.billboards <= DENSE_CONTINENT_ROWS,
+      'benchmark exercises a dense glow with only real sampled sighting badges',
+    );
+    assert.equal(
+      h.state.renderPipelineOperations.densityVisits,
+      DENSE_CONTINENT_CELLS,
+    );
+    assert.equal(
+      h.state.renderPipelineOperations.densityMetadataBuilds,
+      DENSE_CONTINENT_CELLS,
+    );
+    assert.ok(cold.slices.length > 1);
+    for (let move = 1; move <= 4; move++) {
+      h.moveEnd(move * 3);
+      const result = h.flush();
+      const ops = h.state.renderPipelineOperations;
+      assert.equal(ops.densityVisits, DENSE_CONTINENT_CELLS);
+      assert.equal(ops.observationVisits, DENSE_CONTINENT_ROWS);
+      assert.equal(ops.densityMetadataBuilds, 0);
+      assert.equal(ops.densityWrites, 0);
+      assert.equal(ops.densityPositionBuilds, 0);
+      assert.ok(ops.densityRetirementVisits <= DENSE_CONTINENT_CELLS);
+      assert.equal(ops.densityCreated, 0);
+      assert.equal(ops.densityRemoved, 0);
+      assert.equal(
+        result.cartesianBuilds,
+        0,
+        'no repeated longitude/latitude trig per camera pass',
+      );
+      assert.ok(ops.projections <= DENSE_CONTINENT_ROWS);
+      assert.ok(result.projections <= DENSE_CONTINENT_ROWS + 150);
+      assert.ok(
+        ops.billboardVisits <= result.billboards * 3 + WILDLIFE_WORK_UNIT,
+      );
+      assert.equal(
+        ops.rankComparisons,
+        0,
+        'continental buckets never sort the source population',
+      );
+      assert.ok(ops.spacingTests <= result.billboards * 9);
+      assert.ok(result.slices.length <= 144);
+      assert.ok(result.slices.every((slice) => slice.units <= 8));
+      assert.equal(
+        result.publications,
+        3,
+        'publish overlays once after the accepted view is ready',
+      );
+    }
+    h.moveEnd(12);
+    h.flush();
+    assert.equal(h.state.renderPipelineOperations.billboardWrites, 0);
+    assert.equal(
+      h.state.renderPipelineOperations.billboardVisits,
+      h.state.renderedRows.length * 2,
+      'the delta owner scans each row and retained billboard once',
+    );
+  } finally {
+    h.destroy();
+  }
+});
+
+test('superseded dense camera work is dropped and idle callbacks are removed at teardown', () => {
+  const h = denseContinentalRendering();
+  assert.equal(h.moveEnd(0), 'pending');
+  assert.equal(h.moveEnd(12), 'pending');
+  const result = h.flush();
+  assert.equal(
+    h.state.renderPipelineOperations.densityVisits,
+    DENSE_CONTINENT_CELLS,
+  );
+  assert.equal(result.publications, 3);
+  assert.equal(h.moveEnd(24), 'pending');
+  h.destroy();
+  assert.equal(h.flush().slices.length, 0);
+});
+
+test('performance marks cover each render phase and leave no accumulated entries', async () => {
+  const observed = [];
+  const observer = new PerformanceObserver((list) =>
+    observed.push(...list.getEntries()),
+  );
+  observer.observe({ entryTypes: ['measure'] });
+  const h = denseContinentalRendering();
+  try {
+    h.moveEnd();
+    h.flush();
+    await new Promise((resolve) => setImmediate(resolve));
+    for (const phase of [
+      'density',
+      'bucket',
+      'rank',
+      'billboard-update',
+      'overlay-publish',
+      'moveEnd:slice',
+    ])
+      assert.ok(
+        observed.some((entry) => entry.name === `wildlife-sightings:${phase}`),
+        phase,
+      );
+    assert.deepEqual(
+      performance
+        .getEntriesByType('mark')
+        .filter((entry) => entry.name.startsWith('wildlife-sightings:')),
+      [],
+    );
+    assert.deepEqual(
+      performance
+        .getEntriesByType('measure')
+        .filter((entry) => entry.name.startsWith('wildlife-sightings:')),
+      [],
+    );
+    assert.equal(WILDLIFE_MOVE_END_BUDGET_MS, 4);
+  } finally {
+    observer.disconnect();
+    h.destroy();
+  }
+});
+
+test('idle work has a fixed unit ceiling even when the clock does not advance', () => {
+  const callbacks = new Map();
+  let id = 0;
+  let slices = 0;
+  let done = false;
+  const queue = createWildlifeWorkQueue({
+    requestIdle(fn) {
+      callbacks.set(++id, fn);
+      return id;
+    },
+    cancelIdle(handle) {
+      callbacks.delete(handle);
+    },
+    now: () => 0,
+    onSlice({ units }) {
+      assert.ok(units <= 8);
+      slices++;
+    },
+  });
+  function* work() {
+    for (let i = 0; i < 20; i++) yield 'bucket';
+    return 42;
+  }
+  queue.start(work(), (result) => {
+    assert.equal(result, 42);
+    done = true;
+  });
+  assert.equal(done, false);
+  while (callbacks.size) {
+    const [handle, fn] = callbacks.entries().next().value;
+    callbacks.delete(handle);
+    fn();
+  }
+  assert.equal(done, true);
+  assert.equal(slices, 3);
+  assert.equal(queue.pending, false);
+});
+
+test('returning to a previous camera after partially applying a billboard delta still reconciles the collection', (t) => {
+  // Slices end after eight units or 1 ms. A clock that advances 2 ms per read
+  // makes every slice one unit, so the half-applied delta is observable.
+  let clock = 0;
+  t.mock.method(performance, 'now', () => (clock += 2));
+  const h = denseContinentalRendering();
+  try {
+    h.moveEnd(0);
+    h.flush();
+    const originalIds = [...h.state.pointById.keys()].sort();
+    const membership = () => [...h.state.pointById.keys()].sort();
+    h.moveEnd(12);
+    // Advance just until real billboard mutations begin, then supersede the
+    // partially applied view by returning to the original camera.
+    for (let i = 0; i < 5000; i++) {
+      h.flush(1);
+      if (JSON.stringify(membership()) !== JSON.stringify(originalIds)) break;
+    }
+    assert.notDeepEqual(membership(), originalIds);
+    h.moveEnd(0);
+    h.flush();
+    assert.deepEqual(membership(), originalIds);
+  } finally {
+    h.destroy();
+  }
+});
diff --git a/src/layers/wildlifeSightings/photoText.js b/src/layers/wildlifeSightings/photoText.js
new file mode 100644
index 000000000..048805f3c
--- /dev/null
+++ b/src/layers/wildlifeSightings/photoText.js
@@ -0,0 +1,36 @@
+import { t } from '../../i18n/index.js';
+
+/** Compact card ages in translated minutes, hours or days. */
+export function formatAge(deltaMs) {
+  if (!Number.isFinite(deltaMs) || deltaMs < 0) return null;
+  const hours = Math.floor(deltaMs / 3_600_000);
+  if (hours < 1)
+    return t('{count}m', {
+      context: 'age',
+      count: Math.max(1, Math.floor(deltaMs / 60_000)),
+    });
+  if (hours < 24) return t('{count}h', { context: 'age', count: hours });
+  return t('{count}d', { context: 'age', count: Math.floor(hours / 24) });
+}
+
+/** Use the creator portion of the supplied attribution, never a guessed
+ * observer/login. iNaturalist appends rights and licence text after it. */
+export function photoCreator(photo) {
+  if (typeof photo?.attribution !== 'string') return null;
+  const creator = photo.attribution
+    .replace(/^\s*(?:\(c\)|©|copyright)\s*/i, '')
+    .replace(/,\s*(?:some|no|all)\s+rights\s+reserved\b.*$/i, '')
+    .replace(
+      /(?:,\s*|\s*\()(?:CC[\s-]+BY(?:[\s-]+(?:NC|SA|ND))*|CC0|public\s+domain)(?:\s+\d(?:\.\d)?)?\)?\s*$/i,
+      '',
+    )
+    .trim();
+  if (
+    !creator ||
+    /^(?:(?:some|no|all)\s+rights\s+reserved\b|CC(?:0|[\s-]+BY)\b)/i.test(
+      creator,
+    )
+  )
+    return null;
+  return creator;
+}
diff --git a/src/layers/wildlifeSightings/photos.js b/src/layers/wildlifeSightings/photos.js
new file mode 100644
index 000000000..6590baf59
--- /dev/null
+++ b/src/layers/wildlifeSightings/photos.js
@@ -0,0 +1,183 @@
+import { ambientScore } from './cards.js';
+import { compareWildlifeIds } from './model.js';
+import { WILDLIFE_PHOTO_FETCH, WILDLIFE_PHOTO_CACHE_MAX } from './policy.js';
+
+/** Own decoded ambient images and their cancellable, ranked queue. */
+export function createPhotoSlots({
+  imageFactory = () => new Image(),
+  now = () => Date.now(),
+  setTimer = (fn, delay) => setTimeout(fn, delay),
+  clearTimer = (timer) => clearTimeout(timer),
+  onChange = null,
+} = {}) {
+  const slots = new Map();
+  let queue = [];
+  let timer = null;
+  let destroyed = false;
+  let liveKeys = new Set();
+  let cohortKey = null;
+
+  function notify() {
+    if (!destroyed) onChange?.();
+  }
+
+  function release(slot) {
+    slot.cancelled = true;
+    if (!slot.image) return;
+    slot.image.onload = null;
+    slot.image.onerror = null;
+    // Detaching listeners alone would leave pending network and decoded data.
+    slot.image.src = '';
+  }
+
+  function prune() {
+    if (slots.size <= WILDLIFE_PHOTO_CACHE_MAX) return;
+    const ranked = [...slots].sort(([a, slotA], [b, slotB]) => {
+      const keepA = liveKeys.has(a);
+      const keepB = liveKeys.has(b);
+      const frameA = slotA.displayed;
+      const frameB = slotB.displayed;
+      // Decoded photographs that have actually been painted outrank unseen
+      // prefetches. Preserve their Image objects for a flash-free return pan.
+      return Number(keepA) - Number(keepB) || Number(frameA) - Number(frameB);
+    });
+    for (const [key, slot] of ranked) {
+      if (slots.size <= WILDLIFE_PHOTO_CACHE_MAX) break;
+      release(slot);
+      slots.delete(key);
+    }
+  }
+
+  function ensure(row) {
+    const url = row?.photo?.square;
+    if (!url) return null;
+    const key = row.stableId;
+    let slot = slots.get(key);
+    if (slot && slot.url !== url) {
+      release(slot);
+      slots.delete(key);
+      slot = null;
+    }
+    if (!slot) {
+      slot = {
+        key,
+        url,
+        image: null,
+        state: 'queued',
+        cancelled: false,
+        displayed: false,
+      };
+    } else slots.delete(key);
+    slots.set(key, slot);
+    return slot;
+  }
+
+  function launch(slot) {
+    if (
+      destroyed ||
+      slot.cancelled ||
+      slots.get(slot.key) !== slot ||
+      slot.state !== 'queued'
+    )
+      return;
+    slot.state = 'loading';
+    let image;
+    try {
+      image = imageFactory();
+      slot.image = image;
+      // Deliberately non-CORS: the overlay canvas is display-only and is
+      // never read back. Viewport capture reads the separate Cesium canvas.
+      image.onload = () => {
+        if (destroyed || slot.cancelled || slots.get(slot.key) !== slot) return;
+        slot.state = 'ready';
+        image.onload = null;
+        image.onerror = null;
+        notify();
+      };
+      image.onerror = () => {
+        if (destroyed || slot.cancelled || slots.get(slot.key) !== slot) return;
+        slot.state = 'error';
+        image.onload = null;
+        image.onerror = null;
+        notify();
+      };
+      image.src = slot.url;
+    } catch {
+      slot.state = 'error';
+      notify();
+    }
+  }
+
+  function pace() {
+    timer = null;
+    if (destroyed) return;
+    while (queue.length) {
+      const slot = queue.shift();
+      if (slot.cancelled || slots.get(slot.key) !== slot) continue;
+      launch(slot);
+      break;
+    }
+    if (queue.length) timer = setTimer(pace, WILDLIFE_PHOTO_FETCH.intervalMs);
+  }
+
+  function setAmbient(rows) {
+    if (destroyed) return;
+    const ranked = [...rows].sort(
+      (a, b) =>
+        ambientScore(b, now()) - ambientScore(a, now()) ||
+        compareWildlifeIds(a.stableId, b.stableId),
+    );
+    const nextKey = JSON.stringify(
+      ranked.map((row) => [row.stableId, row.photo?.square]),
+    );
+    // A same-cohort refresh must not turn the paced tail into another burst.
+    if (cohortKey === nextKey) return;
+    cohortKey = nextKey;
+    clearTimer(timer);
+    timer = null;
+    liveKeys = new Set(ranked.map((row) => row.stableId));
+    queue = ranked.map(ensure).filter(Boolean);
+    prune();
+    queue = queue.filter(
+      (slot) => slots.get(slot.key) === slot && slot.state === 'queued',
+    );
+    for (
+      let index = 0;
+      index < WILDLIFE_PHOTO_FETCH.burst && queue.length;
+      index++
+    )
+      launch(queue.shift());
+    if (queue.length) timer = setTimer(pace, WILDLIFE_PHOTO_FETCH.intervalMs);
+  }
+
+  function get(row) {
+    const key = row?.stableId;
+    const slot = slots.get(key);
+    if (!slot || slot.state !== 'ready') return null;
+    slot.displayed = true;
+    slots.delete(key);
+    slots.set(key, slot);
+    return slot.image;
+  }
+
+  function clear() {
+    clearTimer(timer);
+    timer = null;
+    queue = [];
+    for (const slot of slots.values()) release(slot);
+    slots.clear();
+    liveKeys.clear();
+    cohortKey = null;
+  }
+
+  return {
+    setAmbient,
+    get,
+    clear,
+    destroy() {
+      destroyed = true;
+      clear();
+    },
+    diagnostics: () => ({ slots: slots.size, queued: queue.length }),
+  };
+}
diff --git a/src/layers/wildlifeSightings/photos.test.mjs b/src/layers/wildlifeSightings/photos.test.mjs
new file mode 100644
index 000000000..c9de75c63
--- /dev/null
+++ b/src/layers/wildlifeSightings/photos.test.mjs
@@ -0,0 +1,147 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createPhotoSlots } from './photos.js';
+
+function clock() {
+  let time = 0;
+  let next = 0;
+  const timers = new Map();
+  return {
+    now: () => time,
+    setTimer(fn, delay) {
+      const id = ++next;
+      timers.set(id, { fn, at: time + delay });
+      return id;
+    },
+    clearTimer(id) {
+      timers.delete(id);
+    },
+    tick(ms) {
+      const until = time + ms;
+      while (true) {
+        const pending = [...timers].sort((a, b) => a[1].at - b[1].at)[0];
+        if (!pending || pending[1].at > until) break;
+        time = pending[1].at;
+        timers.delete(pending[0]);
+        pending[1].fn();
+      }
+      time = until;
+    },
+    count: () => timers.size,
+  };
+}
+
+const row = (index) => ({
+  stableId: `inat:${index}`,
+  quality: 'research',
+  observedAt: 0,
+  favesCount: 100 - index,
+  identificationAgreements: 0,
+  photo: {
+    square: `https://inaturalist-open-data.s3.amazonaws.com/photos/${index}/square.jpg`,
+    medium: `https://inaturalist-open-data.s3.amazonaws.com/photos/${index}/medium.jpg`,
+    licence: 'cc-by',
+    attribution: '(c) Synthetic Photographer',
+  },
+});
+
+function harness() {
+  const time = clock();
+  const launches = [];
+  const images = [];
+  let changes = 0;
+  const slots = createPhotoSlots({
+    ...time,
+    onChange: () => changes++,
+    imageFactory: () => {
+      const image = {
+        set src(url) {
+          this.url = url;
+          if (url) launches.push({ at: time.now(), url });
+        },
+      };
+      images.push(image);
+      return image;
+    },
+  });
+  return { slots, time, images, launches, changes: () => changes };
+}
+
+test('24 photos start in rank order: eight immediately, then one per 250 ms', () => {
+  const h = harness();
+  const rows = Array.from({ length: 24 }, (_, index) => row(index + 1));
+  h.slots.setAmbient([...rows].reverse());
+  assert.equal(h.launches.length, 8);
+  h.time.tick(249);
+  assert.equal(h.launches.length, 8);
+  h.time.tick(1);
+  assert.equal(h.launches.length, 9);
+  h.time.tick(3750);
+  assert.equal(h.launches.length, 24);
+  assert.deepEqual(
+    h.launches.map(({ url }) => Number(url.match(/photos\/(\d+)/)[1])),
+    rows.map((_, index) => index + 1),
+  );
+  assert.deepEqual(
+    h.launches.slice(8).map(({ at }) => at),
+    Array.from({ length: 16 }, (_, i) => (i + 1) * 250),
+  );
+  h.slots.destroy();
+});
+
+test('same-cohort refresh keeps the ambient queue pacing without restarting its burst', () => {
+  const h = harness();
+  const rows = Array.from({ length: 24 }, (_, i) => row(i + 1));
+  h.slots.setAmbient(rows);
+  assert.equal(h.launches.length, 8);
+  h.time.tick(100);
+  h.slots.setAmbient(rows);
+  assert.equal(h.launches.length, 8);
+  h.time.tick(150);
+  assert.equal(h.launches.length, 9);
+  assert.ok(h.launches.every(({ url }) => /square.jpg$/.test(url)));
+  h.slots.destroy();
+});
+
+test('images settle through slots, are pruned to 96, and late loads cannot publish after clear', () => {
+  const h = harness();
+  h.slots.setAmbient([row(1)]);
+  const loaded = h.images[0];
+  loaded.onload();
+  assert.equal(h.slots.get(row(1)), loaded);
+  assert.equal(h.changes(), 1);
+  for (let index = 2; index <= 130; index++) h.slots.setAmbient([row(index)]);
+  assert.equal(h.slots.diagnostics().slots, 96);
+  const last = h.images.at(-1);
+  const late = last.onload;
+  h.slots.clear();
+  late();
+  assert.equal(h.changes(), 1);
+  assert.equal(h.slots.diagnostics().slots, 0);
+  assert.equal(h.time.count(), 0);
+  assert.ok(h.images.every((image) => image.url === ''));
+});
+
+test('returning cards reuse their decoded frame after a pan or height-band hide', () => {
+  const h = harness();
+  const first = row(1);
+  h.slots.setAmbient([first]);
+  const frame = h.images[0];
+  frame.onload();
+  assert.equal(h.slots.get(first), frame);
+  h.slots.setAmbient([]);
+  h.slots.setAmbient([row(2)]);
+  h.images[1].onload();
+  for (let index = 3; index < 105; index++) h.slots.setAmbient([row(index)]);
+  h.slots.setAmbient([first]);
+  assert.equal(
+    h.slots.get(first),
+    frame,
+    'the returning image is already ready, with no empty frame',
+  );
+  assert.equal(
+    h.launches.filter(({ url }) => url.includes('/photos/1/')).length,
+    1,
+  );
+  h.slots.destroy();
+});
diff --git a/src/layers/wildlifeSightings/policy.js b/src/layers/wildlifeSightings/policy.js
new file mode 100644
index 000000000..4af9d7d17
--- /dev/null
+++ b/src/layers/wildlifeSightings/policy.js
@@ -0,0 +1,142 @@
+import { msg } from '../../i18n/marker.js';
+
+export const WILDLIFE_UNKNOWN_COLOR = '#9aa7b3';
+export const WILDLIFE_ACCENT = '#7bd88f';
+export const ICONIC_TINTS = Object.freeze({
+  Aves: '#9fa8ff',
+  Mammalia: '#e0a96d',
+  Reptilia: '#c5d86d',
+  Amphibia: '#5fd3bc',
+  Actinopterygii: '#6fa8dc',
+  Insecta: '#f0b35a',
+  Arachnida: '#d98c6a',
+  Plantae: WILDLIFE_ACCENT,
+  Fungi: '#e8a0a8',
+  Animalia: '#b0bec5',
+  Unknown: WILDLIFE_UNKNOWN_COLOR,
+});
+
+export const ICONIC_LEGEND_ORDER = Object.freeze([
+  'Aves',
+  'Mammalia',
+  'Reptilia',
+  'Amphibia',
+  'Actinopterygii',
+  'Insecta',
+  'Arachnida',
+  'Plantae',
+  'Fungi',
+  'Animalia',
+  'Unknown',
+]);
+
+// Keep badges compact among dense anchors, labels and photo cards.
+export const WILDLIFE_SCALE_BY_DISTANCE = Object.freeze([
+  1_000, 1.1, 8_000_000, 0.6,
+]);
+export const WILDLIFE_SPRITE_PX = 20;
+export const WILDLIFE_BADGE_MAX_PX =
+  WILDLIFE_SPRITE_PX * WILDLIFE_SCALE_BY_DISTANCE[1];
+
+export const WILDLIFE_GRID_HEIGHT_METERS = 400_000;
+// Bound billboard population after screen bucketing.
+export const WILDLIFE_RENDER_LIMIT = 5_000;
+// Bound candidates before the overlay host's final declutter.
+export const WILDLIFE_LABEL_LIMIT = 150;
+export const WILDLIFE_LABEL_NAME_SEPARATION_PX = 80;
+// Hidden ground batches may need several render passes to compile. Retire a
+// failed staging batch after a bounded number instead of holding rendering.
+export const WILDLIFE_GROUND_READY_MAX_CHECKS = 16;
+
+// Camera-height thresholds use +/-10% hysteresis to keep representations still
+// while a camera settles near a boundary.
+export const WILDLIFE_HEIGHT_HYSTERESIS = 0.1;
+export const WILDLIFE_HEIGHT_BANDS = Object.freeze({
+  global: 3_000_000,
+  cells: 1_500_000,
+  cards: 400_000,
+});
+export const WILDLIFE_MAX_ROWS = 2_000;
+export const WILDLIFE_CARD_LIMIT = 24;
+export const WILDLIFE_CARD_MIN_SEP_PX = 112;
+export const WILDLIFE_CARD_REGION_COLUMNS = 4;
+export const WILDLIFE_CARD_REGION_ROWS = 3;
+export const WILDLIFE_PHOTO_CACHE_MAX = 96;
+
+// Static S3 thumbnails do not spend the API quota.
+export const WILDLIFE_PHOTO_FETCH = Object.freeze({
+  burst: 8,
+  intervalMs: 250,
+});
+
+export const WILDLIFE_DEBOUNCE_MS = 600;
+export { WILDLIFE_MAX_VIEW_DEGREES } from './bounds.js';
+export const WILDLIFE_VIEW_PADDING = 0.3;
+export const WILDLIFE_RETRY_MIN_MS = 30_000;
+export const WILDLIFE_RETRY_MAX_MS = 240_000;
+
+// Faster polling would reread the proxy's five-minute cache.
+export const WILDLIFE_UPDATE_INTERVAL_MS = 5 * 60_000;
+
+export const WILDLIFE_CARD_SCALE_FULL_METERS = 20_000;
+export const WILDLIFE_CARD_SCALE_MID_METERS = 120_000;
+export const WILDLIFE_CARD_SCALE_END_METERS = 125_000;
+// Separate entry and exit thresholds prevent churn during small zooms.
+export const WILDLIFE_CARD_SHOW_MAX_METERS = 110_000;
+export const WILDLIFE_CARD_HIDE_MAX_METERS = 125_000;
+export const WILDLIFE_CARD_FADE_LOW_METERS = 70_000;
+export const WILDLIFE_CARD_FADE_HIGH_METERS = 125_000;
+export const WILDLIFE_SELECTED_LABEL_MAX_CHARS = 40;
+export const WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS = 250_000;
+export const WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS = 400_000;
+export const WILDLIFE_CARD_MAX_DISTANCE_METERS = 600_000;
+export const WILDLIFE_CARD_ALTITUDE_SCALE = Object.freeze({
+  fullEnd: WILDLIFE_CARD_SCALE_FULL_METERS,
+  midEnd: WILDLIFE_CARD_SCALE_MID_METERS,
+  end: WILDLIFE_CARD_SCALE_END_METERS,
+  midValue: 0.9,
+  endValue: 0.85,
+  smoothToMid: true,
+});
+
+export { ACARTIA_GUARD_BOX } from './acartiaTaxa.js';
+export const WILDLIFE_CONFIRMED_CHIP_ID = 'quality-confirmed';
+
+export const TAXA_PRESETS = Object.freeze([
+  Object.freeze({
+    value: 'all',
+    id: 'taxa-all',
+    label: msg('ALL'),
+    title: msg('Show all taxa'),
+  }),
+  Object.freeze({
+    value: 'Aves',
+    id: 'taxa-birds',
+    label: msg('BIRDS'),
+    title: msg('Show only birds'),
+  }),
+  Object.freeze({
+    value: 'Mammalia',
+    id: 'taxa-mammals',
+    label: msg('MAMMALS'),
+    title: msg('Show only mammals'),
+  }),
+  Object.freeze({
+    value: 'whales',
+    id: 'taxa-whales',
+    label: msg('WHALES'),
+    title: msg('Show only whales and dolphins (7 days)'),
+  }),
+  Object.freeze({
+    value: 'Insecta',
+    id: 'taxa-insects',
+    label: msg('INSECTS'),
+    title: msg('Show only insects'),
+  }),
+  Object.freeze({
+    value: 'Plantae',
+    id: 'taxa-plants',
+    label: msg('PLANTS'),
+    title: msg('Show only plants'),
+  }),
+]);
diff --git a/src/layers/wildlifeSightings/records.js b/src/layers/wildlifeSightings/records.js
new file mode 100644
index 000000000..a1e50f52c
--- /dev/null
+++ b/src/layers/wildlifeSightings/records.js
@@ -0,0 +1,350 @@
+// The server imports this module. Keep the projection independent of Cesium,
+// DOM and the translation catalog, and never copy an upstream record wholesale.
+import { msg } from '../../i18n/marker.js';
+import { acartiaSpeciesGroup, inAcartiaCoverage } from './acartiaTaxa.js';
+
+const OPEN_PHOTO_LICENCES = Object.freeze([
+  'cc0',
+  'cc-by',
+  'cc-by-sa',
+  'cc-by-nc',
+  'cc-by-nc-sa',
+]);
+
+const DAY_MS = 86_400_000;
+const ACARTIA_MAX_AGE_MS = 8 * DAY_MS;
+const OBSERVATION_FUTURE_TOLERANCE_MS = 10 * 60_000;
+// A JavaScript $ can match before a final newline; require the true end too.
+const INAT_PHOTO =
+  /^https:\/\/inaturalist-open-data\.s3\.amazonaws\.com\/photos\/\d+\/square\.(jpe?g|png)$(?![\s\S])/i;
+const INAT_OBSERVATION =
+  /^https:\/\/www\.inaturalist\.org\/observations\/\d+$(?![\s\S])/;
+
+/** Accept only canonical iNaturalist observation pages, without URL suffixes. */
+function inatObservationUri(value) {
+  return typeof value === 'string' && INAT_OBSERVATION.test(value)
+    ? value
+    : null;
+}
+
+function cleanText(value, maxLength) {
+  if (typeof value !== 'string') return null;
+  const text = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').trim();
+  return text ? text.slice(0, maxLength) : null;
+}
+
+function numberOrNull(value) {
+  if (typeof value !== 'number' && typeof value !== 'string') return null;
+  if (typeof value === 'string' && !value.trim()) return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function validPosition(lat, lon) {
+  return (
+    Number.isFinite(lat) &&
+    Math.abs(lat) <= 90 &&
+    Number.isFinite(lon) &&
+    Math.abs(lon) <= 180
+  );
+}
+
+function dateOnly(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+    return null;
+  const time = Date.parse(value);
+  return Number.isFinite(time) &&
+    new Date(time).toISOString().slice(0, 10) === value
+    ? value
+    : null;
+}
+
+/** Date-only records cannot prove a time within a partly expired cutoff day.
+ * Use its start conservatively, including for privacy-preserving cached cells. */
+function withinObservationWindow(observedAt, observedOn, nowMs, windowMs) {
+  const time = Number.isFinite(observedAt)
+    ? observedAt
+    : dateOnly(observedOn)
+      ? Date.parse(`${observedOn}T00:00:00Z`)
+      : NaN;
+  return (
+    Number.isFinite(time) &&
+    Number.isFinite(nowMs) &&
+    Number.isFinite(windowMs) &&
+    windowMs >= 0 &&
+    time >= nowMs - windowMs &&
+    time <= nowMs + OBSERVATION_FUTURE_TOLERANCE_MS
+  );
+}
+
+/** Apply the displayed observation window to projected and retained LRU rows. */
+export function isRecentWildlifeSighting(row, nowMs, taxa = 'all') {
+  return withinObservationWindow(
+    row?.observedAt,
+    row?.observedOn,
+    nowMs,
+    (taxa === 'whales' ? 7 : 2) * DAY_MS,
+  );
+}
+
+/** Strictly parse the two documented Acartia forms. A timezone-free SQL-style
+ * value is UTC; ISO timestamps must carry a timezone rather than using the host's. */
+export function parseAcartiaTime(value) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  const sql = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(text);
+  const iso =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/i.test(
+      text,
+    );
+  if (!sql && !iso) return null;
+  const day = dateOnly(text.slice(0, 10));
+  if (!day) return null;
+  const [hour, minute, second] = text.slice(11, 19).split(':').map(Number);
+  if (hour > 23 || minute > 59 || second > 59) return null;
+  const time = Date.parse(sql ? `${text.replace(' ', 'T')}Z` : text);
+  return Number.isFinite(time) ? time : null;
+}
+
+function coarsen(value, precision = 2) {
+  const scale = 10 ** precision;
+  return Math.round(value * scale) / scale;
+}
+
+/** Public iNaturalist obscuration is a 0.2-degree cell aligned to zero. The
+ * rounding removes floating-point noise, including at negative longitudes. */
+export function obscuredCell(lat, lon) {
+  if (!validPosition(lat, lon)) return null;
+  const south = Math.min(89.8, Math.floor(lat * 5) / 5);
+  const west = Math.min(179.8, Math.floor(lon * 5) / 5);
+  return {
+    south: coarsen(south, 1),
+    north: coarsen(south + 0.2, 1),
+    west: coarsen(west, 1),
+    east: coarsen(west + 0.2, 1),
+  };
+}
+
+/** Only the documented open-data square URL can be transformed to a display size. */
+export function inatPhotoUrl(url, size = 'square') {
+  if (typeof url !== 'string' || !INAT_PHOTO.test(url)) return null;
+  if (size !== 'square' && size !== 'medium') return null;
+  return size === 'square' ? url : url.replace(/\/square\./i, `/${size}.`);
+}
+
+/** Accept either the first upstream photo or the explicitly projected photo. */
+export function isOpenPhoto(photo) {
+  if (!photo || typeof photo !== 'object') return false;
+  const licence = photo.license_code ?? photo.licence;
+  return (
+    OPEN_PHOTO_LICENCES.includes(licence) &&
+    inatPhotoUrl(photo.url ?? photo.square) !== null &&
+    cleanText(photo.attribution, 160) !== null
+  );
+}
+
+/** Licence codes remain provider data; the all-rights-reserved fallback is
+ * marked for translation when cards display it. */
+export function inatLicenceLabel(code) {
+  switch (code) {
+    case 'cc0':
+      return 'CC0';
+    case 'cc-by':
+      return 'CC BY';
+    case 'cc-by-sa':
+      return 'CC BY-SA';
+    case 'cc-by-nc':
+      return 'CC BY-NC';
+    case 'cc-by-nc-sa':
+      return 'CC BY-NC-SA';
+    case 'cc-by-nd':
+      return 'CC BY-ND';
+    case 'cc-by-nc-nd':
+      return 'CC BY-NC-ND';
+    default:
+      return msg('All rights reserved');
+  }
+}
+
+/**
+ * Project API-v1 observation results (the results ARRAY, not the response
+ * envelope). Malformed rows are skipped; only a non-array rejects a snapshot.
+ */
+export function normalizeInatObservations(
+  payload,
+  { nowMs, windowMs = 2 * DAY_MS } = {},
+) {
+  if (!Array.isArray(payload)) return null;
+  const rows = [];
+  const ids = new Set();
+  for (const raw of payload) {
+    if (!raw || !Number.isSafeInteger(raw.id) || raw.id <= 0) continue;
+    if (raw.geoprivacy === 'private' || raw.taxon_geoprivacy === 'private')
+      continue;
+    if (raw.quality_grade !== 'research' && raw.quality_grade !== 'needs_id')
+      continue;
+    const stableId = `inat:${raw.id}`;
+    if (ids.has(stableId)) continue;
+    let lon = raw.geojson?.coordinates?.[0];
+    let lat = raw.geojson?.coordinates?.[1];
+    if (!validPosition(lat, lon) && typeof raw.location === 'string') {
+      const parts = raw.location.split(',');
+      if (parts.length === 2) [lat, lon] = parts.map(numberOrNull);
+    }
+    if (!validPosition(lat, lon)) continue;
+    const obscured =
+      raw.obscured === true ||
+      raw.geoprivacy === 'obscured' ||
+      raw.taxon_geoprivacy === 'obscured';
+    const cell = obscured ? obscuredCell(lat, lon) : null;
+    const time = parseAcartiaTime(raw.time_observed_at);
+    const observedOn =
+      dateOnly(raw.observed_on) ||
+      (time !== null ? new Date(time).toISOString().slice(0, 10) : null);
+    // The v1 d1 parameter is a DATE filter, so its first day over-fetches the
+    // exact rolling window. Filter before hiding an obscured record's time.
+    if (
+      Number.isFinite(nowMs) &&
+      !withinObservationWindow(time, observedOn, nowMs, windowMs)
+    )
+      continue;
+    const photo = Array.isArray(raw.photos) ? raw.photos[0] : null;
+    const taxon = raw.taxon;
+    const faves = numberOrNull(raw.faves_count);
+    const agreements = numberOrNull(raw.num_identification_agreements);
+    ids.add(stableId);
+    rows.push({
+      stableId,
+      origin: 'inaturalist',
+      lat: cell ? coarsen((cell.south + cell.north) / 2, 1) : lat,
+      lon: cell ? coarsen((cell.west + cell.east) / 2, 1) : lon,
+      obscured,
+      cell,
+      observedAt: obscured ? null : time,
+      observedOn,
+      quality: raw.quality_grade,
+      commonName: cleanText(taxon?.preferred_common_name, 100),
+      scientificName: cleanText(taxon?.name, 100),
+      iconic: cleanText(taxon?.iconic_taxon_name, 40) || 'Unknown',
+      threatened: taxon?.threatened === true,
+      provider: null,
+      link:
+        inatObservationUri(raw.uri) ||
+        `https://www.inaturalist.org/observations/${raw.id}`,
+      photo: isOpenPhoto(photo)
+        ? {
+            square: inatPhotoUrl(photo.url),
+            licence: photo.license_code,
+            attribution: cleanText(photo.attribution, 160),
+          }
+        : null,
+      // These public aggregate counters are used only for ambient photo rank.
+      favesCount: faves !== null && faves >= 0 ? Math.floor(faves) : 0,
+      identificationAgreements:
+        agreements !== null && agreements >= 0 ? Math.floor(agreements) : 0,
+    });
+  }
+  return rows;
+}
+
+function acartiaLink(value) {
+  if (typeof value !== 'string' || value.length > 500)
+    return 'https://acartia.io';
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' && !url.username && !url.password
+      ? url.href
+      : 'https://acartia.io';
+  } catch {
+    return 'https://acartia.io';
+  }
+}
+
+/** Acartia documents flat rows only. Name and entity are text fields; unknown
+ * shapes are skipped rather than guessing nested provider data. */
+export function normalizeAcartiaSightings(payload, nowMs) {
+  if (!Array.isArray(payload)) return null;
+  const rows = [];
+  const ids = new Set();
+  for (const raw of payload) {
+    const id =
+      typeof raw?.entry_id === 'string'
+        ? cleanText(raw.entry_id, 120)
+        : Number.isFinite(raw?.entry_id)
+          ? String(raw.entry_id)
+          : null;
+    if (!id) continue;
+    const stableId = `acartia:${id}`;
+    if (ids.has(stableId)) continue;
+    const lat = numberOrNull(raw.latitude);
+    const lon = numberOrNull(raw.longitude);
+    const observedAt = parseAcartiaTime(raw.created);
+    const name = cleanText(raw.data_source_name, 60);
+    const species = cleanText(raw.type, 100);
+    // Validate the original field: truncating a long, ambiguous name could
+    // otherwise turn a prefix such as "Orca ... or seal" into a valid species.
+    const speciesGroup = acartiaSpeciesGroup(raw.type);
+    if (
+      !validPosition(lat, lon) ||
+      !inAcartiaCoverage(lat, lon) ||
+      !name ||
+      !speciesGroup ||
+      observedAt === null ||
+      !Number.isFinite(nowMs) ||
+      nowMs - observedAt > ACARTIA_MAX_AGE_MS ||
+      observedAt - nowMs > OBSERVATION_FUTURE_TOLERANCE_MS
+    )
+      continue;
+    ids.add(stableId);
+    rows.push({
+      stableId,
+      origin: 'acartia',
+      lat: coarsen(lat),
+      lon: coarsen(lon),
+      obscured: false,
+      cell: null,
+      observedAt,
+      observedOn: new Date(observedAt).toISOString().slice(0, 10),
+      quality:
+        raw.trusted === true || raw.trusted === 1 || raw.trusted === 'true'
+          ? 'research'
+          : 'needs_id',
+      commonName: species,
+      scientificName: null,
+      iconic: 'Mammalia',
+      cetacean: speciesGroup === 'cetacean',
+      threatened: false,
+      provider: { name, entity: cleanText(raw.data_source_entity, 60) },
+      link: acartiaLink(raw.photo_url),
+      photo: null,
+      favesCount: 0,
+      identificationAgreements: 0,
+    });
+  }
+  return rows;
+}
+
+/** Recheck observation age on projected snapshots, including stale cache rows. */
+export function mergeSightings(
+  inatRows,
+  acartiaRows,
+  { nowMs, taxa = 'all', confirmed = false } = {},
+) {
+  const byId = new Map();
+  for (const row of Array.isArray(inatRows) ? inatRows : []) {
+    if (isRecentWildlifeSighting(row, nowMs, taxa)) byId.set(row.stableId, row);
+  }
+  for (const row of Array.isArray(acartiaRows) ? acartiaRows : []) {
+    if (
+      !inAcartiaCoverage(row.lat, row.lon) ||
+      !isRecentWildlifeSighting(row, nowMs, taxa)
+    )
+      continue;
+    if (confirmed && row.quality !== 'research') continue;
+    if (/inaturalist/i.test(row.provider?.name || '')) continue;
+    if (!['all', 'Mammalia', 'whales'].includes(taxa)) continue;
+    if (taxa === 'whales' && row.cetacean !== true) continue;
+    byId.set(row.stableId, row);
+  }
+  return [...byId.values()];
+}
diff --git a/src/layers/wildlifeSightings/records.test.mjs b/src/layers/wildlifeSightings/records.test.mjs
new file mode 100644
index 000000000..18a1693d8
--- /dev/null
+++ b/src/layers/wildlifeSightings/records.test.mjs
@@ -0,0 +1,542 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  normalizeInatObservations,
+  normalizeAcartiaSightings,
+  parseAcartiaTime,
+  inatPhotoUrl,
+  isOpenPhoto,
+  obscuredCell,
+  inatLicenceLabel,
+  mergeSightings,
+  isRecentWildlifeSighting,
+} from './records.js';
+
+const now = Date.UTC(2026, 10, 4, 18);
+const hour = 3_600_000;
+const photo = {
+  url: 'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpeg',
+  license_code: 'cc-by-nc',
+  attribution: '(c) Synthetic Photographer, some rights reserved',
+};
+const observation = (overrides = {}) => ({
+  id: 123,
+  uri: 'https://www.inaturalist.org/observations/123',
+  geojson: { coordinates: [-122.351, 47.613] },
+  positional_accuracy: 12,
+  public_positional_accuracy: 12,
+  obscured: false,
+  geoprivacy: null,
+  taxon_geoprivacy: null,
+  time_observed_at: '2026-11-04T16:00:00Z',
+  observed_on: '2026-11-04',
+  created_at: '2026-11-04T17:00:00Z',
+  quality_grade: 'research',
+  license_code: 'cc-by-nc',
+  faves_count: 6,
+  num_identification_agreements: 3,
+  taxon: {
+    name: 'Calypte anna',
+    preferred_common_name: "Anna's Hummingbird",
+    iconic_taxon_name: 'Aves',
+    threatened: false,
+  },
+  photos: [photo],
+  user: { login: 'SHOULD_NEVER_ESCAPE' },
+  ...overrides,
+});
+const sighting = (overrides = {}) => ({
+  entry_id: 'abc',
+  latitude: 48.12345,
+  longitude: -122.54321,
+  created: '2026-11-04 16:00:00',
+  type: 'Orca',
+  no_sighted: '5',
+  photo_url: 'https://provider.example/photo.jpg',
+  data_source_name: 'Synthetic Network',
+  data_source_entity: 'Whale Alert',
+  trusted: true,
+  data_source_comments: 'PRIVATE PHONE AND NAME',
+  ...overrides,
+});
+
+test('normalizers reject only non-array snapshots and dedupe validated ids', () => {
+  for (const input of [null, {}, { results: [] }, '']) {
+    assert.equal(normalizeInatObservations(input), null);
+    assert.equal(normalizeAcartiaSightings(input, now), null);
+  }
+  assert.deepEqual(normalizeInatObservations([]), []);
+  assert.equal(
+    normalizeInatObservations([null, observation(), observation()]).length,
+    1,
+  );
+  assert.equal(
+    normalizeAcartiaSightings([null, sighting(), sighting()], now).length,
+    1,
+  );
+});
+
+test('iNaturalist projection retains only the listed display fields and aggregate photo rank', () => {
+  const [row] = normalizeInatObservations([observation()]);
+  assert.equal(row.stableId, 'inat:123');
+  assert.equal(row.favesCount, 6);
+  assert.equal(row.identificationAgreements, 3);
+  assert.equal(row.photo.attribution, photo.attribution);
+  assert.equal(row.observedAt, now - 2 * hour);
+  for (const key of [
+    'user',
+    'login',
+    'public_positional_accuracy',
+    'geojson',
+    'created_at',
+  ])
+    assert.equal(key in row, false);
+  assert.doesNotMatch(JSON.stringify(row), /SHOULD_NEVER_ESCAPE/);
+});
+
+test('observation links accept only canonical source pages and fall back to the id', () => {
+  for (const uri of [
+    undefined,
+    'https://www.inaturalist.org/observations/123\n',
+    'https://www.inaturalist.org/observations/123?redirect=elsewhere',
+    'http://www.inaturalist.org/observations/123',
+    'https://www.inaturalist.org.evil.example/observations/123',
+  ]) {
+    const [row] = normalizeInatObservations([observation({ uri })]);
+    assert.equal(
+      row.link,
+      observation().uri,
+      'the existing detail card keeps its canonical fallback',
+    );
+  }
+});
+
+test('wildlife package entries construct without acquiring data or a DOM', async () => {
+  const api = await import('gods-eye-view/layers/wildlife-sightings');
+  const sources =
+    await import('gods-eye-view/layers/wildlife-sightings/source');
+  const layer = api.createWildlifeSightingsLayer({
+    source: sources.createWildlifeSightingsSource({
+      fetchImpl() {
+        assert.fail('construction must not acquire');
+      },
+    }),
+  });
+  assert.equal(layer.id, 'wildlife-sightings');
+  layer.destroy();
+});
+
+test('only allow-listed photo licences with square open-data hosts and attribution render', () => {
+  for (const license_code of [
+    'cc0',
+    'cc-by',
+    'cc-by-sa',
+    'cc-by-nc',
+    'cc-by-nc-sa',
+  ]) {
+    assert.equal(isOpenPhoto({ ...photo, license_code }), true);
+    assert.ok(
+      normalizeInatObservations([
+        observation({ photos: [{ ...photo, license_code }] }),
+      ])[0].photo,
+    );
+  }
+  for (const badPhoto of [
+    { ...photo, license_code: null },
+    { ...photo, license_code: 'cc-by-nd' },
+    { ...photo, license_code: 'cc-by-nc-nd' },
+    { ...photo, license_code: 'all rights reserved' },
+    { ...photo, url: 'https://static.inaturalist.org/photos/123/square.jpg' },
+    { ...photo, url: `${photo.url}?size=square` },
+    { ...photo, url: photo.url.replace('https:', 'http:') },
+    { ...photo, attribution: '' },
+    { ...photo, url: photo.url.replace('/square.', '/medium.') },
+  ]) {
+    assert.equal(isOpenPhoto(badPhoto), false);
+    assert.equal(
+      normalizeInatObservations([observation({ photos: [badPhoto] })])[0].photo,
+      null,
+    );
+  }
+  assert.equal(
+    inatPhotoUrl(photo.url, 'medium'),
+    'https://inaturalist-open-data.s3.amazonaws.com/photos/123/medium.jpeg',
+  );
+  for (const extension of ['jpg', 'jpeg', 'PNG']) {
+    const square = photo.url.replace('square.jpeg', `square.${extension}`);
+    assert.equal(
+      inatPhotoUrl(square, 'medium'),
+      square.replace('/square.', '/medium.'),
+    );
+  }
+  for (const invalid of [
+    null,
+    new URL(photo.url),
+    photo.url.replace('https:', 'http:'),
+    photo.url.replace('amazonaws.com', 'amazonaws.com.evil.example'),
+    photo.url.replace('https://', 'https://user:secret@'),
+    photo.url.replace('https://', 'https://evil.example@'),
+    photo.url.replace('/photos/', '/other/photos/'),
+    photo.url.replace('/123/', '/abc/'),
+    photo.url.replace('/square.', '/medium.'),
+    photo.url.replace('/square.', '/large.'),
+    photo.url.replace('.jpeg', '.webp'),
+    `${photo.url}?size=large`,
+    `${photo.url}#large`,
+    `${photo.url}\n`,
+  ]) {
+    assert.equal(inatPhotoUrl(invalid, 'medium'), null, String(invalid));
+  }
+  for (const invalidSize of [
+    'original',
+    'small',
+    'large',
+    'Medium',
+    '../medium',
+    'medium?query=1',
+    null,
+  ]) {
+    assert.equal(inatPhotoUrl(photo.url, invalidSize), null);
+  }
+  assert.equal(inatLicenceLabel('cc-by-nc-sa'), 'CC BY-NC-SA');
+  assert.equal(inatLicenceLabel(null), 'All rights reserved');
+});
+
+test('photo attribution is trimmed, control-free and bounded', () => {
+  const attribution = `  Photo\u0000\n${'A'.repeat(200)} `;
+  const [row] = normalizeInatObservations([
+    observation({ photos: [{ ...photo, attribution }] }),
+  ]);
+  assert.equal(row.photo.attribution.length, 160);
+  assert.match(row.photo.attribution, /^PhotoA/);
+  assert.doesNotMatch(row.photo.attribution, /[\u0000-\u001f]/);
+});
+
+test('obscured rows reveal only cell centres and date, without accuracy', () => {
+  assert.deepEqual(obscuredCell(47.613, -122.351), {
+    south: 47.6,
+    north: 47.8,
+    west: -122.4,
+    east: -122.2,
+  });
+  for (const hiding of [
+    { obscured: true },
+    { geoprivacy: 'obscured' },
+    { taxon_geoprivacy: 'obscured' },
+  ]) {
+    const [row] = normalizeInatObservations([observation(hiding)]);
+    assert.equal(row.obscured, true);
+    assert.equal(row.lat, 47.7);
+    assert.equal(row.lon, -122.3);
+    assert.equal('accuracyM' in row, false);
+    assert.equal(row.observedAt, null);
+    assert.equal(row.observedOn, '2026-11-04');
+    assert.doesNotMatch(JSON.stringify(row), /47\.613|-122\.351|16:00/);
+  }
+  assert.deepEqual(obscuredCell(90, 180), {
+    south: 89.8,
+    north: 90,
+    west: 179.8,
+    east: 180,
+  });
+});
+
+test('private, casual, invalid coordinates and invalid ids are skipped', () => {
+  const invalid = [
+    observation({ geoprivacy: 'private' }),
+    observation({ taxon_geoprivacy: 'private' }),
+    observation({ quality_grade: 'casual' }),
+    observation({ id: -1 }),
+    observation({ id: 1.5 }),
+    observation({ geojson: { coordinates: [181, 47] } }),
+    observation({ geojson: null }),
+  ];
+  assert.deepEqual(normalizeInatObservations(invalid), []);
+  const [fallback] = normalizeInatObservations([
+    observation({
+      geojson: null,
+      location: '47.613,-122.351',
+      uri: 'https://bad.example',
+    }),
+  ]);
+  assert.equal(fallback.lat, 47.613);
+  assert.equal(fallback.link, 'https://www.inaturalist.org/observations/123');
+  assert.deepEqual(
+    normalizeInatObservations([observation({ geojson: null, location: ',0' })]),
+    [],
+  );
+});
+
+test('Acartia accepts only the two stated UTC timestamp formats', () => {
+  assert.equal(parseAcartiaTime('2026-11-04 16:00:00'), now - 2 * hour);
+  assert.equal(parseAcartiaTime('2026-11-04T16:00:00Z'), now - 2 * hour);
+  assert.equal(parseAcartiaTime('2026-11-04T18:00:00+02:00'), now - 2 * hour);
+  for (const value of [
+    '2026-11-04T16:00:00',
+    '11/04/2026',
+    '2026-02-30 12:00:00',
+    '2026-11-04 25:00:00',
+    123,
+    null,
+  ])
+    assert.equal(parseAcartiaTime(value), null);
+});
+
+test('Acartia coarsens before returning data, keeps provider, and never reads comments', () => {
+  const raw = sighting();
+  Object.defineProperty(raw, 'data_source_comments', {
+    get() {
+      assert.fail('comments read');
+    },
+  });
+  const [row] = normalizeAcartiaSightings([raw], now);
+  assert.equal(row.lat, 48.12);
+  assert.equal(row.lon, -122.54);
+  assert.deepEqual(row.provider, {
+    name: 'Synthetic Network',
+    entity: 'Whale Alert',
+  });
+  assert.equal(row.quality, 'research');
+  assert.equal(row.photo, null);
+  assert.doesNotMatch(
+    JSON.stringify(row),
+    /data_source_comments|PRIVATE|48\.12345|-122\.54321/,
+  );
+});
+
+test('Acartia requires flat provider text, handles trust, and sanitizes type', () => {
+  for (const provider of ['', null, {}, { name: 'Invented nested shape' }]) {
+    assert.deepEqual(
+      normalizeAcartiaSightings(
+        [sighting({ data_source_name: provider })],
+        now,
+      ),
+      [],
+    );
+  }
+  for (const trusted of [true, 1, 'true'])
+    assert.equal(
+      normalizeAcartiaSightings([sighting({ trusted })], now)[0].quality,
+      'research',
+    );
+  for (const trusted of [false, 0, 'false', '1'])
+    assert.equal(
+      normalizeAcartiaSightings([sighting({ trusted })], now)[0].quality,
+      'needs_id',
+    );
+  assert.deepEqual(
+    normalizeAcartiaSightings([sighting({ type: ' \u0000 ' })], now),
+    [],
+  );
+});
+
+test('Acartia rejects invalid times/positions and unsafe photo links become the canonical page', () => {
+  for (const overrides of [
+    { created: new Date(now - 8 * 24 * hour - 1).toISOString() },
+    { created: new Date(now + 10 * 60_000 + 1).toISOString() },
+    { created: 'not a timestamp' },
+    { latitude: 91 },
+    { longitude: -181 },
+    { entry_id: '' },
+  ])
+    assert.deepEqual(normalizeAcartiaSightings([sighting(overrides)], now), []);
+  for (const photo_url of [
+    'http://provider.example/p.jpg',
+    'https://user:secret@provider.example/p.jpg',
+    'javascript:bad()',
+    'https://' + 'x'.repeat(501),
+    null,
+  ]) {
+    assert.equal(
+      normalizeAcartiaSightings([sighting({ photo_url })], now)[0].link,
+      'https://acartia.io',
+    );
+  }
+});
+
+test('merge applies Acartia windows, trust, preset and iNat dedupe', () => {
+  const inat = normalizeInatObservations([observation()]);
+  const rows = normalizeAcartiaSightings(
+    [
+      sighting(),
+      sighting({
+        entry_id: 'old',
+        created: new Date(now - 3 * 24 * hour).toISOString(),
+      }),
+      sighting({ entry_id: 'untrusted', trusted: false }),
+      sighting({
+        entry_id: 'inat',
+        data_source_name: 'iNaturalist observations',
+      }),
+    ],
+    now,
+  );
+  const ids = (options) =>
+    mergeSightings(inat, rows, { nowMs: now, ...options }).map(
+      (row) => row.stableId,
+    );
+  assert.deepEqual(ids({}), ['inat:123', 'acartia:abc', 'acartia:untrusted']);
+  assert.deepEqual(ids({ confirmed: true }), ['inat:123', 'acartia:abc']);
+  assert.ok(ids({ taxa: 'whales' }).includes('acartia:old'));
+  assert.deepEqual(ids({ taxa: 'Aves' }), ['inat:123']);
+});
+
+test('iNaturalist recency uses observation time and the exact preset window', () => {
+  const raw = [
+    observation({
+      id: 1,
+      time_observed_at: '2010-11-04T16:00:00Z',
+      observed_on: '2010-11-04',
+      created_at: new Date(now).toISOString(),
+    }),
+    observation({
+      id: 2,
+      time_observed_at: new Date(now - 48 * hour - 1).toISOString(),
+      observed_on: '2026-11-02',
+    }),
+    observation({
+      id: 3,
+      time_observed_at: new Date(now - 48 * hour).toISOString(),
+      observed_on: '2026-11-02',
+      created_at: '2026-10-01T00:00:00Z',
+    }),
+    observation({
+      id: 4,
+      time_observed_at: new Date(now - 3 * 24 * hour).toISOString(),
+      observed_on: '2026-11-01',
+    }),
+  ];
+  const ids = (rows) => rows.map((row) => row.stableId);
+  assert.deepEqual(ids(normalizeInatObservations(raw, { nowMs: now })), [
+    'inat:3',
+  ]);
+  assert.deepEqual(
+    ids(
+      normalizeInatObservations(raw, { nowMs: now, windowMs: 7 * 24 * hour }),
+    ),
+    ['inat:2', 'inat:3', 'inat:4'],
+  );
+  // Recheck cached/projected rows as the clock moves between server refreshes.
+  assert.deepEqual(
+    ids(mergeSightings(normalizeInatObservations(raw), [], { nowMs: now })),
+    ['inat:3'],
+  );
+  assert.deepEqual(
+    mergeSightings(normalizeInatObservations([raw[2]]), [], { nowMs: now + 1 }),
+    [],
+  );
+});
+
+test('date-only and obscured iNaturalist recency never includes a partly expired date', () => {
+  const rows = normalizeInatObservations(
+    [
+      observation({ id: 1, time_observed_at: null, observed_on: '2026-11-02' }),
+      observation({ id: 2, time_observed_at: null, observed_on: '2026-11-03' }),
+      observation({ id: 3, time_observed_at: null, observed_on: null }),
+      observation({
+        id: 4,
+        obscured: true,
+        time_observed_at: '2010-11-04T16:00:00Z',
+        observed_on: '2010-11-04',
+      }),
+    ],
+    { nowMs: now },
+  );
+  assert.deepEqual(
+    rows.map((row) => row.stableId),
+    ['inat:2'],
+  );
+});
+
+test('retained sightings use the same exact, date-only and preset recency limits', () => {
+  const boundary = { observedAt: now - 48 * hour };
+  assert.equal(isRecentWildlifeSighting(boundary, now), true);
+  assert.equal(isRecentWildlifeSighting(boundary, now + 1), false);
+  assert.equal(isRecentWildlifeSighting(boundary, now + 1, 'whales'), true);
+  const whaleBoundary = { observedAt: now - 7 * 24 * hour };
+  assert.equal(isRecentWildlifeSighting(whaleBoundary, now, 'whales'), true);
+  assert.equal(
+    isRecentWildlifeSighting(whaleBoundary, now + 1, 'whales'),
+    false,
+  );
+  assert.equal(isRecentWildlifeSighting(whaleBoundary, now, 'Mammalia'), false);
+  for (const [observedOn, expected] of [
+    ['2026-11-02', false],
+    ['2026-11-03', true],
+    ['2026-11-04', true],
+  ]) {
+    assert.equal(
+      isRecentWildlifeSighting({ observedAt: null, observedOn }, now),
+      expected,
+    );
+  }
+  assert.equal(
+    isRecentWildlifeSighting({ observedOn: '2026-11-03' }, now + 24 * hour),
+    false,
+  );
+  for (const row of [
+    null,
+    {},
+    { observedOn: '2010-11-04' },
+    { observedOn: 'invalid' },
+  ]) {
+    assert.equal(isRecentWildlifeSighting(row, now), false);
+  }
+  assert.equal(isRecentWildlifeSighting(boundary, NaN), false);
+});
+
+test('Acartia validates the documented type field before applying the WHALES preset', () => {
+  const rows = normalizeAcartiaSightings(
+    [
+      sighting({ entry_id: 'orca', type: 'Orca' }),
+      sighting({ entry_id: 'scientific', type: 'Phocoena phocoena' }),
+      sighting({ entry_id: 'seal', type: 'Harbor seal' }),
+      sighting({
+        entry_id: 'unidentified',
+        type: 'Unidentified marine mammal',
+      }),
+      sighting({ entry_id: 'unknown-whale', type: 'Unidentified whale' }),
+      sighting({ entry_id: 'unknown', type: 'Unknown' }),
+      sighting({ entry_id: 'empty', type: '' }),
+      sighting({ entry_id: 'fish', type: 'Whale shark' }),
+      sighting({ entry_id: 'text', type: 'Maybe an Orca or a seal' }),
+      sighting({ entry_id: 'prefix', type: `Orca${' '.repeat(120)}or a seal` }),
+      sighting({ entry_id: 'invented-shape', type: { species: 'Orca' } }),
+    ],
+    now,
+  );
+  const ids = (taxa) =>
+    mergeSightings([], rows, { nowMs: now, taxa }).map((row) => row.stableId);
+  assert.deepEqual(ids('whales'), ['acartia:orca', 'acartia:scientific']);
+  const mammals = [
+    'acartia:orca',
+    'acartia:scientific',
+    'acartia:seal',
+    'acartia:unidentified',
+    'acartia:unknown-whale',
+  ];
+  assert.deepEqual(ids('all'), mammals);
+  assert.deepEqual(ids('Mammalia'), mammals);
+  assert.deepEqual(ids('Aves'), []);
+});
+
+test('Acartia rejects out-of-coverage rows before rounding or caching', () => {
+  for (const position of [
+    { latitude: 45.49999 },
+    { latitude: 50.50001 },
+    { longitude: -126.00001 },
+    { longitude: -120.99999 },
+    { latitude: 37.8, longitude: -122.4 },
+  ]) {
+    assert.deepEqual(normalizeAcartiaSightings([sighting(position)], now), []);
+  }
+  for (const position of [
+    { latitude: 45.5, longitude: -126 },
+    { latitude: 50.5, longitude: -121 },
+  ]) {
+    assert.equal(
+      normalizeAcartiaSightings([sighting(position)], now).length,
+      1,
+    );
+  }
+});
diff --git a/src/layers/wildlifeSightings/render.perf.test.mjs b/src/layers/wildlifeSightings/render.perf.test.mjs
new file mode 100644
index 000000000..fe3357ce6
--- /dev/null
+++ b/src/layers/wildlifeSightings/render.perf.test.mjs
@@ -0,0 +1,166 @@
+import assert from 'node:assert/strict';
+import { performance, PerformanceObserver } from 'node:perf_hooks';
+import test from 'node:test';
+import { perfBudgetTestOptions } from '../../../scripts/run-perf-tests.mjs';
+import { denseContinentalRendering } from './renderPerformanceFixtures.mjs';
+import { WILDLIFE_MOVE_END_BUDGET_MS } from './performance.js';
+
+const median = (values) =>
+  [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
+const percentile95 = (values) =>
+  [...values].sort((a, b) => a - b)[Math.floor(values.length * 0.95)];
+
+// A GC pause is outside the layer's CPU work. Keep raw wall times in the
+// diagnostic and subtract only directly observed, overlapping GC intervals
+// for the strict CPU budget; never hide a slow layer phase as an outlier.
+function activeMs(slice, collections) {
+  const start = slice.startTimeMs;
+  const end = start + slice.durationMs;
+  return (
+    slice.durationMs -
+    collections.reduce(
+      (sum, gc) =>
+        sum +
+        Math.max(
+          0,
+          Math.min(end, gc.startTime + gc.duration) -
+            Math.max(start, gc.startTime),
+        ),
+      0,
+    )
+  );
+}
+
+test(
+  'dense continental production moveEnd pipeline yields every 4ms, including cold tiles and real Cesium billboard updates',
+  perfBudgetTestOptions(),
+  async (t) => {
+    // Settle CPU-triggered runtime startup before creating the cold layer;
+    // cells, coordinates and billboard collections remain unwarmed.
+    const calibrationStart = performance.now();
+    let calibrationChecksum = 0;
+    for (;;) {
+      const cpu = process.threadCpuUsage();
+      if (cpu.user + cpu.system >= 1_100_000) break;
+      for (let i = 0; i < 65536; i++)
+        calibrationChecksum =
+          (calibrationChecksum + i) ^ (calibrationChecksum >>> 16);
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+    const runtimeSettleMs = performance.now() - calibrationStart;
+    const collections = [];
+    const phases = [];
+    const observer = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries())
+        (entry.entryType === 'gc' ? collections : phases).push(entry);
+    });
+    observer.observe({ entryTypes: ['gc', 'measure'] });
+    const h = denseContinentalRendering();
+    const runs = [];
+    try {
+      for (let i = 0; i < 65; i++) {
+        const start = performance.now();
+        assert.equal(h.moveEnd((i % 4) * 3), 'pending');
+        const enqueueMs = performance.now() - start;
+        const result = h.flush();
+        runs.push({
+          startTimeMs: start,
+          endTimeMs: performance.now(),
+          enqueueMs,
+          ...result,
+        });
+        await new Promise((resolve) => setImmediate(resolve));
+      }
+      await new Promise((resolve) => setImmediate(resolve));
+      for (const entry of observer.takeRecords())
+        (entry.entryType === 'gc' ? collections : phases).push(entry);
+      const warm = runs.slice(25);
+      const allSlices = runs.flatMap((run) => run.slices);
+      const warmSlices = warm.flatMap((run) => run.slices);
+      const activeSlices = allSlices.map((slice) =>
+        activeMs(slice, collections),
+      );
+      const warmTotal = warm.map((run) =>
+        run.slices.reduce(
+          (sum, slice) => sum + activeMs(slice, collections),
+          run.enqueueMs,
+        ),
+      );
+      const enqueueMax = Math.max(...runs.map((run) => run.enqueueMs));
+      const coldMax = Math.max(
+        ...runs[0].slices.map((slice) => activeMs(slice, collections)),
+      );
+      const sliceMax = Math.max(...activeSlices);
+      if (sliceMax > WILDLIFE_MOVE_END_BUDGET_MS) {
+        const slow = allSlices[activeSlices.indexOf(sliceMax)];
+        const entries = phases
+          .filter(
+            (entry) =>
+              entry.entryType === 'measure' &&
+              entry.name !== 'wildlife-sightings:moveEnd:slice' &&
+              entry.startTime >= slow.startTimeMs &&
+              entry.startTime < slow.startTimeMs + slow.durationMs,
+          )
+          .map((entry) => ({
+            phase: entry.name,
+            durationMs: entry.duration,
+            activeMs: activeMs(
+              { startTimeMs: entry.startTime, durationMs: entry.duration },
+              collections,
+            ),
+          }));
+        t.diagnostic(
+          `Slow slice ${JSON.stringify({ slice: slow, phases: entries, gc: collections.map((entry) => ({ start: entry.startTime, duration: entry.duration })), now: performance.now(), uptimeMs: process.uptime() * 1000 })}`,
+        );
+      }
+      assert.ok(
+        enqueueMax <= WILDLIFE_MOVE_END_BUDGET_MS,
+        `moveEnd enqueue ${enqueueMax.toFixed(3)}ms`,
+      );
+      assert.ok(
+        sliceMax <= WILDLIFE_MOVE_END_BUDGET_MS,
+        `longest layer CPU slice ${sliceMax.toFixed(3)}ms exceeds 4ms`,
+      );
+      assert.ok(
+        median(warmTotal) <= WILDLIFE_MOVE_END_BUDGET_MS,
+        `median full moveEnd CPU ${median(warmTotal).toFixed(3)}ms exceeds 4ms`,
+      );
+      assert.equal(warm.at(-1).cartesianBuilds, 0);
+      const phaseMeans = Object.fromEntries(
+        [
+          'density',
+          'bucket',
+          'rank',
+          'billboard-update',
+          'overlay-publish',
+        ].map((name) => {
+          const duration = phases
+            .filter(
+              (entry) =>
+                entry.name === `wildlife-sightings:${name}` &&
+                entry.startTime >= warm[0].startTimeMs,
+            )
+            .reduce(
+              (sum, entry) =>
+                sum +
+                activeMs(
+                  {
+                    startTimeMs: entry.startTime,
+                    durationMs: entry.duration,
+                  },
+                  collections,
+                ),
+              0,
+            );
+          return [name, (duration / warm.length).toFixed(3)];
+        }),
+      );
+      t.diagnostic(
+        `6,144 cells + 500 observations, ${runs.at(-1).glowPrimitives} glow splats + ${runs.at(-1).billboards} real icons; moveEnd enqueue max=${enqueueMax.toFixed(3)}ms; cold max CPU slice=${coldMax.toFixed(3)}ms; all max CPU slice=${sliceMax.toFixed(3)}ms; warm total CPU median=${median(warmTotal).toFixed(3)}ms; warm slice p95=${percentile95(warmSlices.map((slice) => activeMs(slice, collections))).toFixed(3)}ms; raw wall slice max=${Math.max(...allSlices.map((slice) => slice.durationMs)).toFixed(3)}ms; observed GC pauses=${collections.length}; repeated Cartesian builds=0; CPU startup calibration=${runtimeSettleMs.toFixed(0)}ms, checksum=${calibrationChecksum} (cold fixture created afterward); warm phase mean ms=${JSON.stringify(phaseMeans)}`,
+      );
+    } finally {
+      h.destroy();
+      observer.disconnect();
+    }
+  },
+);
diff --git a/src/layers/wildlifeSightings/renderPerformanceFixtures.mjs b/src/layers/wildlifeSightings/renderPerformanceFixtures.mjs
new file mode 100644
index 000000000..30ef52361
--- /dev/null
+++ b/src/layers/wildlifeSightings/renderPerformanceFixtures.mjs
@@ -0,0 +1,185 @@
+import * as Cesium from 'cesium';
+import { createRendering } from './rendering.js';
+import { createSelection } from './selection.js';
+
+export const DENSE_CONTINENT_CELLS = 6 * 32 * 32;
+export const DENSE_CONTINENT_ROWS = 500;
+const NOW = Date.parse('2026-11-04T18:00:00Z');
+
+/** The real render + selection pipeline with Cesium coordinates/billboards.
+ * Only the WebGL scene and external overlay host are replaced. Six fully
+ * occupied logical tiles deliberately include off-window cells and collisions. */
+export function denseContinentalRendering({ onOperations } = {}) {
+  const cells = [];
+  const z = 3;
+  for (let x = 1; x < 3; x++)
+    for (let y = 1; y < 4; y++)
+      for (let row = 1; row < 64; row += 2)
+        for (let column = 1; column < 64; column += 2)
+          cells.push({
+            id: `grid:${z}/${x}/${y}:${row}:${column}`,
+            lat:
+              (Math.atan(
+                Math.sinh(Math.PI * (1 - (2 * (y + row / 64)) / 2 ** z)),
+              ) *
+                180) /
+              Math.PI,
+            lon: ((x + column / 64) / 2 ** z) * 360 - 180,
+            cellCount: row * 64 + column,
+          });
+  const rows = cells
+    .slice(1200, 1200 + DENSE_CONTINENT_ROWS)
+    .map((cell, i) => ({
+      stableId: `synthetic:continent:${i}`,
+      origin: 'inaturalist',
+      lat: cell.lat,
+      lon: cell.lon,
+      iconic: 'Aves',
+      commonName: i % 2 ? `Synthetic bird ${i}` : null,
+      observedAt: NOW - i * 1000,
+      quality: 'research',
+      obscured: false,
+      cell: null,
+    }));
+  const primitives = {
+    add: (value) => value,
+    remove(value) {
+      value.destroy();
+      return true;
+    },
+  };
+  const scene = {
+    canvas: { clientWidth: 1440, clientHeight: 900 },
+    primitives,
+  };
+  const state = {
+    enabled: true,
+    viewer: {
+      scene,
+      camera: { positionWC: {}, positionCartographic: { height: 2_000_000 } },
+    },
+    rows: new Map(rows.map((row) => [row.stableId, row])),
+    gridCells: cells,
+    gridAvailable: true,
+    renderedRows: [],
+    rowById: new Map(),
+    pointById: new Map(),
+    positions: new Map(),
+    cells: [],
+    staging: null,
+    taxa: 'all',
+    selectedId: null,
+    query: { visibleBoxes: [{ south: 5, west: -130, north: 75, east: -50 }] },
+    band: 'regional',
+    ambientRows: [],
+    ambientIds: [],
+    labelRows: [],
+    carriers: new Map(),
+    contextIds: new Set(),
+  };
+  const centre = Cesium.Cartesian3.fromDegrees(-90, 42);
+  const frame = Cesium.Transforms.eastNorthUpToFixedFrame(centre);
+  const east = Cesium.Matrix4.getColumn(frame, 0, new Cesium.Cartesian4());
+  const north = Cesium.Matrix4.getColumn(frame, 1, new Cesium.Cartesian4());
+  const metrics = { projections: 0, publications: 0, cartesianBuilds: 0 };
+  let pan = 0;
+  let nextIdle = 0;
+  const idle = new Map();
+  const slices = [];
+  const timers = new Map();
+  let nextTimer = 0;
+  const parts = {};
+  const services = {
+    now: () => NOW,
+    setTimer(fn, delay) {
+      timers.set(++nextTimer, { fn, delay });
+      return nextTimer;
+    },
+    clearTimer: (id) => timers.delete(id),
+    requestIdleCallback(fn) {
+      idle.set(++nextIdle, fn);
+      return nextIdle;
+    },
+    cancelIdleCallback(id) {
+      idle.delete(id);
+    },
+    performanceSlice(slice) {
+      slices.push(slice);
+    },
+    cesium: {
+      ...Cesium,
+      Cartesian3: class extends Cesium.Cartesian3 {
+        static fromDegrees(...args) {
+          metrics.cartesianBuilds++;
+          return Cesium.Cartesian3.fromDegrees(...args);
+        }
+      },
+    },
+    project(_scene, anchor) {
+      metrics.projections++;
+      return {
+        x:
+          720 +
+          (anchor.x * east.x + anchor.y * east.y + anchor.z * east.z) / 8000 +
+          pan,
+        y:
+          450 -
+          (anchor.x * north.x + anchor.y * north.y + anchor.z * north.z) / 8000,
+      };
+    },
+    occluderFactory: () => ({ isPointVisible: () => true }),
+    badgeSprites: {
+      get: (group) => `data:image/svg+xml,${group}`,
+      subscribe: () => () => {},
+    },
+    render: { governorRequestRender() {} },
+    overlayHost: {
+      setEntries() {
+        metrics.publications++;
+      },
+    },
+    performanceOperations: onOperations,
+  };
+  parts.rendering = createRendering({ state, services, parts });
+  parts.photos = { get: () => null, setAmbient() {} };
+  parts.selection = createSelection({ state, services, parts });
+  parts.rendering.init();
+  return {
+    state,
+    metrics,
+    moveEnd(offset = 0) {
+      pan = offset;
+      metrics.projections = metrics.publications = metrics.cartesianBuilds = 0;
+      slices.length = 0;
+      const result = parts.rendering.rebuild();
+      if (result !== 'pending') {
+        parts.selection.refreshAmbient();
+        parts.selection.publishSelected();
+        parts.selection.refreshContexts();
+      }
+      return result;
+    },
+    flush(maxSlices = Infinity) {
+      let count = 0;
+      while (idle.size && count++ < maxSlices) {
+        const [id, fn] = idle.entries().next().value;
+        idle.delete(id);
+        const threadStart = process.threadCpuUsage();
+        fn({ timeRemaining: () => 8, didTimeout: false });
+        const threadUsed = process.threadCpuUsage(threadStart);
+        if (slices.length)
+          slices.at(-1).threadCpuMs =
+            (threadUsed.user + threadUsed.system) / 1000;
+      }
+      return {
+        ...metrics,
+        billboards: state.renderedRows.length,
+        glowPrimitives: parts.rendering.density?.size ?? 0,
+        slices: [...slices],
+      };
+    },
+    destroy() {
+      parts.rendering.destroy();
+    },
+  };
+}
diff --git a/src/layers/wildlifeSightings/rendering.js b/src/layers/wildlifeSightings/rendering.js
new file mode 100644
index 000000000..811e98d29
--- /dev/null
+++ b/src/layers/wildlifeSightings/rendering.js
@@ -0,0 +1,691 @@
+import { wildlifeAccent } from './cards.js';
+import {
+  wildlifeIconModelWork,
+  wildlifeIconRelevance,
+  compareWildlifeIds,
+} from './model.js';
+import { createWildlifeBillboardModel } from './billboardModel.js';
+import { createWildlifeDensity } from './density.js';
+import { wildlifeSpriteCache } from './sprites.js';
+import { isRecentWildlifeSighting } from './records.js';
+import {
+  drainWildlifeWork,
+  createWildlifeWorkQueue,
+  WILDLIFE_SYNC_CELL_LIMIT,
+  WILDLIFE_WORK_UNIT,
+} from './performance.js';
+import {
+  WILDLIFE_SCALE_BY_DISTANCE,
+  WILDLIFE_BADGE_MAX_PX,
+  WILDLIFE_GROUND_READY_MAX_CHECKS,
+  WILDLIFE_SPRITE_PX,
+} from './policy.js';
+
+/** Own sighting billboards, density glow and batched privacy cells. */
+export function createRendering({ state, services, parts }) {
+  const C = services.cesium;
+  const badgeSprites = services.badgeSprites ?? wildlifeSpriteCache();
+  let batchDepth = 0;
+  let pendingRenderReason = null;
+  let billboards = null;
+  let density = null;
+  let cellsSignature = null;
+  let ambientAnchorIds = new Set();
+  const badgeScreens = new Map();
+  const crowdedBadgeIds = new Set();
+  const photoCardIds = new Set();
+  const appearances = new Map();
+  const surfaceAnchors = new WeakMap();
+  let operations = null;
+  const workQueue = createWildlifeWorkQueue({
+    requestIdle: services.requestIdleCallback,
+    cancelIdle: services.cancelIdleCallback,
+    onSlice: (slice) => services.performanceSlice?.(slice),
+  });
+
+  function surfaceAnchor(row) {
+    const old = surfaceAnchors.get(row);
+    if (old && old.lat === row.lat && old.lon === row.lon) return old.anchor;
+    const anchor = C.Cartesian3.fromDegrees(row.lon, row.lat);
+    surfaceAnchors.set(row, { lat: row.lat, lon: row.lon, anchor });
+    if (operations) operations.positionBuilds++;
+    return anchor;
+  }
+  const requestRender = (reason) => {
+    if (batchDepth) {
+      pendingRenderReason = reason;
+      return;
+    }
+    services.render?.governorRequestRender?.(`wildlife-sightings-${reason}`);
+  };
+  function beginBatch() {
+    batchDepth += 1;
+  }
+  function endBatch() {
+    batchDepth = Math.max(0, batchDepth - 1);
+    if (batchDepth || !pendingRenderReason) return;
+    const reason = pendingRenderReason;
+    pendingRenderReason = null;
+    requestRender(reason);
+  }
+  const surfaceRemovers = [];
+  const tilesetRemovers = new Map();
+
+  // Reuse the shared ground cache. One bounded resolve lifts cold anchors
+  // without per-sighting scene renders and pixel readback.
+  let floorResolve = null;
+  let floorColdPending = false;
+  function position(row) {
+    if (row.origin === 'acartia') return surfaceAnchor(row);
+    const floor = services.groundFloor?.cachedGroundFloor?.(row.lat, row.lon);
+    if (floor == null && !floorColdPending) {
+      // Anchors are built after the rows publish; warm once the pass ends.
+      floorColdPending = true;
+      queueMicrotask(warmColdFloors);
+    }
+    return Number.isFinite(floor) && floor !== 0
+      ? C.Cartesian3.fromDegrees(row.lon, row.lat, floor)
+      : surfaceAnchor(row);
+  }
+
+  function warmColdFloors() {
+    if (!floorColdPending || floorResolve) return;
+    floorColdPending = false;
+    const resolve = services.groundFloor?.resolveGroundFloorCellsBounded;
+    if (!state.enabled || typeof resolve !== 'function') return;
+    const points = state.renderedRows
+      .filter((row) => row.origin !== 'acartia')
+      .map((row) => ({ lat: row.lat, lon: row.lon }));
+    if (!points.length) return;
+    floorResolve = Promise.resolve(resolve(points))
+      .catch(() => {})
+      .then(() => {
+        floorResolve = null;
+        resampleAnchors();
+      });
+  }
+
+  function occluder() {
+    const camera = state.viewer?.camera;
+    return camera?.positionWC ? services.occluderFactory?.(camera) : null;
+  }
+
+  function cull() {
+    if (!state.enabled) return false;
+    const horizon = occluder();
+    let changed = false;
+    // Only observation badges yield at adjacent bucket edges or to a painted
+    // card. Density never participates in picking or icon spacing.
+    for (const [id, point] of state.pointById) {
+      const anchor = state.positions.get(id);
+      const show =
+        !photoCardIds.has(id) &&
+        !crowdedBadgeIds.has(id) &&
+        (!horizon || horizon.isPointVisible(anchor) === true);
+      if (point.show === show) continue;
+      point.show = show;
+      changed = true;
+    }
+    if (changed) requestRender('cull');
+    return changed;
+  }
+
+  function updateBadgeSpacing() {
+    return drainWildlifeWork(updateBadgeSpacingWork());
+  }
+
+  function* updateBadgeSpacingWork() {
+    yield 'rank';
+    crowdedBadgeIds.clear();
+    const buckets = new Map();
+    const rows = [...state.renderedRows].sort(
+      (a, b) =>
+        wildlifeIconRelevance(b, state.selectedId) -
+          wildlifeIconRelevance(a, state.selectedId) ||
+        compareWildlifeIds(a.stableId, b.stableId),
+    );
+    yield 'rank';
+    let visits = 0;
+    for (const row of rows) {
+      if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'rank';
+      if (photoCardIds.has(row.stableId)) continue;
+      const screen = badgeScreens.get(row.stableId);
+      if (!screen) continue;
+      const x = Math.floor(screen.x / WILDLIFE_BADGE_MAX_PX);
+      const y = Math.floor(screen.y / WILDLIFE_BADGE_MAX_PX);
+      let overlaps = false;
+      for (let dx = -1; dx <= 1 && !overlaps; dx++) {
+        for (let dy = -1; dy <= 1 && !overlaps; dy++) {
+          for (const other of buckets.get((x + dx) * 65536 + y + dy) || []) {
+            if (operations) operations.spacingTests++;
+            if (
+              (screen.x - other.x) ** 2 + (screen.y - other.y) ** 2 <
+              WILDLIFE_BADGE_MAX_PX ** 2
+            ) {
+              overlaps = true;
+              break;
+            }
+          }
+        }
+      }
+      if (overlaps) crowdedBadgeIds.add(row.stableId);
+      else {
+        const key = x * 65536 + y;
+        if (!buckets.has(key)) buckets.set(key, []);
+        buckets.get(key).push(screen);
+      }
+    }
+  }
+
+  // Called only when the host's painted membership changes, never per idle
+  // frame. Requested/loading/rejected cards must leave their badges visible.
+  function setPhotoCardVisibility(entryIds) {
+    const next = new Set();
+    for (const id of entryIds)
+      if (id.startsWith('sighting:')) next.add(id.slice(9));
+    const changed =
+      next.size !== photoCardIds.size ||
+      [...next].some((id) => !photoCardIds.has(id));
+    photoCardIds.clear();
+    for (const id of next) photoCardIds.add(id);
+    if (!state.enabled) return;
+    updateBadgeSpacing();
+    cull();
+    // A painted thumbnail already names its sighting; drop the repeat label.
+    if (changed) parts.selection?.photoCardsChanged?.();
+  }
+
+  function resampleAnchors() {
+    if (!state.enabled || !state.points) return;
+    let changed = false;
+    for (const row of state.renderedRows) {
+      if (row.origin === 'acartia') continue;
+      const point = state.pointById.get(row.stableId);
+      if (!point) continue;
+      const anchor = position(row);
+      if (C.Cartesian3.equals(anchor, state.positions.get(row.stableId)))
+        continue;
+      point.position = anchor;
+      state.positions.set(row.stableId, anchor);
+      changed = true;
+    }
+    if (!changed) return;
+    beginBatch();
+    try {
+      cull();
+      parts.selection.refreshAmbient();
+      parts.selection.publishSelected();
+      parts.selection.notify?.();
+      parts.selection.refreshContexts();
+      requestRender('terrain');
+    } finally {
+      endBatch();
+    }
+  }
+
+  function trackTileset(primitive) {
+    if (
+      tilesetRemovers.has(primitive) ||
+      typeof primitive?.allTilesLoaded?.addEventListener !== 'function'
+    )
+      return false;
+    tilesetRemovers.set(
+      primitive,
+      primitive.allTilesLoaded.addEventListener(resampleAnchors),
+    );
+    return true;
+  }
+
+  function deactivate() {
+    workQueue.cancel();
+    operations = null;
+    for (const remove of surfaceRemovers.splice(0)) remove?.();
+    for (const remove of tilesetRemovers.values()) remove?.();
+    tilesetRemovers.clear();
+  }
+
+  function activate() {
+    deactivate();
+    if (!state.enabled || !state.viewer) return;
+    const scene = state.viewer.scene;
+    const refreshBadgeImages = () => {
+      if (!state.enabled) return;
+      appearances.clear();
+      if (billboards?.refreshImages((group) => badgeSprites.get(group)))
+        requestRender('font-ready');
+    };
+    surfaceRemovers.push(badgeSprites.subscribe(refreshBadgeImages));
+    refreshBadgeImages();
+    const ownEvent = (event, listener) => {
+      const remove = event?.addEventListener?.(listener);
+      if (typeof remove === 'function') surfaceRemovers.push(remove);
+    };
+    ownEvent(scene.globe?.tileLoadProgressEvent, (pending) => {
+      if (pending === 0) resampleAnchors();
+    });
+    // Scene forwards the globe event in Cesium; deduplicate that alias.
+    for (const event of new Set([
+      scene.terrainProviderChanged,
+      scene.globe?.terrainProviderChanged,
+    ]))
+      ownEvent(event, resampleAnchors);
+    const primitives = scene.primitives;
+    for (let i = 0; i < (primitives?.length || 0); i++)
+      trackTileset(primitives.get(i));
+    ownEvent(primitives?.primitiveAdded, (primitive) => {
+      if (trackTileset(primitive)) resampleAnchors();
+    });
+    ownEvent(primitives?.primitiveRemoved, (primitive) => {
+      if (!tilesetRemovers.has(primitive)) return;
+      tilesetRemovers.get(primitive)?.();
+      tilesetRemovers.delete(primitive);
+      resampleAnchors();
+    });
+    services.eventTarget?.addEventListener?.(
+      'gev:map-stack-changed',
+      resampleAnchors,
+    );
+    surfaceRemovers.push(() =>
+      services.eventTarget?.removeEventListener?.(
+        'gev:map-stack-changed',
+        resampleAnchors,
+      ),
+    );
+  }
+
+  function removeCell(primitive) {
+    const owners =
+      state.viewer?.scene?.groundPrimitives || state.viewer?.scene?.primitives;
+    if (owners?.remove?.(primitive) !== true && !primitive.isDestroyed?.())
+      primitive.destroy?.();
+  }
+
+  function cancelStaging() {
+    const pending = state.staging;
+    if (!pending) return;
+    state.staging = null;
+    pending.remove?.();
+    for (const primitive of pending.primitives) removeCell(primitive);
+  }
+
+  function clearCells() {
+    cancelStaging();
+    for (const primitive of state.cells) removeCell(primitive);
+    state.cells = [];
+    cellsSignature = null;
+  }
+
+  function stageCells(rows) {
+    const cellsVisible = state.band === 'cells' || state.band === 'cards';
+    const unique = new Map();
+    if (cellsVisible) {
+      for (const row of rows) {
+        if (!row.cell) continue;
+        const cell = row.cell;
+        const key = `${cell.south},${cell.west},${cell.north},${cell.east}:${wildlifeAccent(row.iconic)}`;
+        if (!unique.has(key)) unique.set(key, row);
+      }
+    }
+    const signature = JSON.stringify([...unique.keys()].sort());
+    if (signature === cellsSignature) return false;
+    cancelStaging();
+    if (!unique.size) {
+      clearCells();
+      cellsSignature = signature;
+      return true;
+    }
+    cellsSignature = signature;
+    const fills = [];
+    const outlines = [];
+    for (const row of unique.values()) {
+      const { south, west, north, east } = row.cell;
+      const tint = C.Color.fromCssColorString(wildlifeAccent(row.iconic));
+      fills.push(
+        new C.GeometryInstance({
+          geometry: new C.RectangleGeometry({
+            rectangle: C.Rectangle.fromDegrees(west, south, east, north),
+            vertexFormat: C.PerInstanceColorAppearance.VERTEX_FORMAT,
+          }),
+          attributes: {
+            color: C.ColorGeometryInstanceAttribute.fromColor(
+              tint.withAlpha(0.25),
+            ),
+          },
+        }),
+      );
+      outlines.push(
+        new C.GeometryInstance({
+          geometry: new C.GroundPolylineGeometry({
+            positions: C.Cartesian3.fromDegreesArray([
+              west,
+              south,
+              east,
+              south,
+              east,
+              north,
+              west,
+              north,
+              west,
+              south,
+            ]),
+            width: 2,
+          }),
+          attributes: {
+            color: C.ColorGeometryInstanceAttribute.fromColor(
+              tint.withAlpha(0.8),
+            ),
+          },
+        }),
+      );
+    }
+    // Hidden primitives still compile their geometry. Poll only these two
+    // nonempty batches, then atomically retire the previous privacy cells.
+    const primitives = [
+      new C.GroundPrimitive({
+        geometryInstances: fills,
+        appearance: new C.PerInstanceColorAppearance({
+          flat: true,
+          translucent: true,
+        }),
+        classificationType: C.ClassificationType.BOTH,
+        allowPicking: false,
+        releaseGeometryInstances: false,
+        show: false,
+      }),
+      new C.GroundPolylinePrimitive({
+        geometryInstances: outlines,
+        appearance: new C.PolylineColorAppearance(),
+        classificationType: C.ClassificationType.BOTH,
+        allowPicking: false,
+        releaseGeometryInstances: false,
+        show: false,
+      }),
+    ];
+    const owners =
+      state.viewer.scene.groundPrimitives || state.viewer.scene.primitives;
+    for (const primitive of primitives) owners.add(primitive);
+    const pending = { primitives, remove: null, checks: 0 };
+    state.staging = pending;
+    const ready = () => {
+      if (state.staging !== pending || !state.enabled) return;
+      if (!primitives.every((primitive) => primitive.ready === true)) {
+        pending.checks += 1;
+        if (pending.checks >= WILDLIFE_GROUND_READY_MAX_CHECKS) {
+          cancelStaging();
+          cellsSignature = null;
+          return;
+        }
+        requestRender('staging');
+        return;
+      }
+      pending.remove?.();
+      state.staging = null;
+      for (const primitive of state.cells) removeCell(primitive);
+      state.cells = primitives;
+      for (const primitive of primitives) primitive.show = true;
+      requestRender('render');
+    };
+    pending.remove = state.viewer.scene.postRender?.addEventListener?.(ready);
+    ready();
+    return true;
+  }
+
+  function init() {
+    density = createWildlifeDensity({
+      cesium: C,
+      viewer: state.viewer,
+      positionForCell: surfaceAnchor,
+      requestRender,
+      setTimer: services.setTimer,
+      clearTimer: services.clearTimer,
+      requestIdle: services.requestIdleCallback,
+      cancelIdle: services.cancelIdleCallback,
+      eventTarget: services.eventTarget,
+    });
+    state.points = new C.BillboardCollection();
+    state.points.show = false;
+    state.viewer.scene.primitives.add(state.points);
+    services.sprites?.registerSpriteCollection?.(
+      'wildlife-sightings',
+      state.points,
+    );
+    const distanceScale = new C.NearFarScalar(...WILDLIFE_SCALE_BY_DISTANCE);
+    billboards = createWildlifeBillboardModel({
+      collection: state.points,
+      pointById: state.pointById,
+      positions: state.positions,
+      positionForRow: position,
+      appearanceForGroup(group) {
+        if (!appearances.has(group))
+          appearances.set(group, {
+            image: badgeSprites.get(group),
+            width: WILDLIFE_SPRITE_PX,
+            height: WILDLIFE_SPRITE_PX,
+            // The sprite includes its tint and white glyph. Multiplication
+            // by a taxon colour would tint the glyph as well.
+            color: C.Color.WHITE,
+            scale: 1,
+            scaleByDistance: distanceScale,
+            disableDepthTestDistance: Number.POSITIVE_INFINITY,
+          });
+        return appearances.get(group);
+      },
+    });
+  }
+
+  function rebuild() {
+    if (!state.enabled || !state.points) return false;
+    workQueue.cancel();
+    operations = null;
+    const work = rebuildWork();
+    if (
+      (state.gridCells?.length || 0) > WILDLIFE_SYNC_CELL_LIMIT ||
+      state.rows.size > WILDLIFE_SYNC_CELL_LIMIT
+    ) {
+      workQueue.start(work, () => {
+        if (!state.enabled) return;
+        parts.selection.refreshAmbient();
+        parts.selection.publishSelected();
+        parts.selection.refreshContexts();
+        parts.selection.syncCredits?.();
+        parts.selection.notify?.();
+        parts.controls?.notify?.();
+      });
+      return 'pending';
+    }
+    return drainWildlifeWork(work);
+  }
+
+  function* rebuildWork() {
+    operations = {
+      positionBuilds: 0,
+      spacingTests: 0,
+      billboardVisits: 0,
+      billboardWrites: 0,
+    };
+    const nowMs = services.now();
+    const taxa = state.drawnParams?.taxa ?? state.taxa;
+    const scene = state.viewer.scene;
+    const horizon = occluder();
+    const densityResult = yield* density.updateWork(
+      state.gridAvailable ? state.gridCells || [] : [],
+      {
+        boxes: state.query?.visibleBoxes ?? state.query?.boxes,
+        isPointVisible: horizon
+          ? (anchor) => horizon.isPointVisible(anchor) === true
+          : null,
+        onOperations: (counts) => Object.assign(operations, counts),
+      },
+    );
+    if (densityResult.changed)
+      services.sprites?.restoreSpriteOrder?.(state.viewer);
+    const model = yield* wildlifeIconModelWork({
+      rows: [...state.rows.values()].filter(
+        (row) =>
+          row.stableId === state.selectedId ||
+          isRecentWildlifeSighting(row, nowMs, taxa),
+      ),
+      boxes: state.query?.visibleBoxes ?? state.query?.boxes,
+      selectedId: state.selectedId,
+      selectedRow: state.selectedRow,
+      preferredIds: state.ambientIds,
+      onOperations: (counts) => Object.assign(operations, counts),
+      projectRow:
+        typeof services.project === 'function'
+          ? (row) => {
+              const anchor = surfaceAnchor(row);
+              const cached = surfaceAnchors.get(row);
+              cached.screen = null;
+              if (horizon && horizon.isPointVisible(anchor) !== true)
+                return null;
+              const screen = services.project(scene, anchor);
+              if (
+                !screen ||
+                screen.x < 0 ||
+                screen.y < 0 ||
+                screen.x >= (scene.canvas?.clientWidth ?? Infinity) ||
+                screen.y >= (scene.canvas?.clientHeight ?? Infinity)
+              )
+                return null;
+              cached.screen = screen;
+              return screen;
+            }
+          : null,
+    });
+    yield 'rank';
+    badgeScreens.clear();
+    for (const row of model.rows) {
+      const screen = surfaceAnchors.get(row)?.screen;
+      if (screen) badgeScreens.set(row.stableId, screen);
+    }
+    state.renderPipelineOperations = operations;
+    state.renderedRows = model.rows;
+    yield* updateBadgeSpacingWork();
+    yield 'rank';
+    state.sightingCount = state.gridAvailable
+      ? Math.max(
+          densityResult.sightingCount,
+          model.sightingCount - model.acartiaCount,
+        ) + model.acartiaCount
+      : model.sightingCount;
+    const previousRows = state.rowById;
+    state.rowById = new Map(
+      state.renderedRows.map((row) => [row.stableId, row]),
+    );
+    // Panning can bring two visible photo incumbents into one icon bucket.
+    // Keep the single billboard winner, but preserve both card identities and
+    // anchors until selection's front-side/window/height checks release them.
+    const ambientAnchors = new Map();
+    for (const incumbent of state.ambientRows || []) {
+      const row = state.rows.get(incumbent.stableId);
+      if (!row || !isRecentWildlifeSighting(row, nowMs, taxa)) continue;
+      if (state.rowById.has(row.stableId)) continue;
+      const old = previousRows.get(row.stableId);
+      const cached = state.positions.get(row.stableId);
+      ambientAnchors.set(
+        row.stableId,
+        cached && old?.lat === row.lat && old?.lon === row.lon
+          ? cached
+          : position(row),
+      );
+      state.rowById.set(row.stableId, row);
+    }
+    function restoreAmbientAnchors() {
+      for (const id of ambientAnchorIds)
+        if (!ambientAnchors.has(id) && !state.pointById.has(id))
+          state.positions.delete(id);
+      for (const [id, anchor] of ambientAnchors)
+        state.positions.set(id, anchor);
+      ambientAnchorIds = new Set(ambientAnchors.keys());
+    }
+    if (state.selectedId && !state.rowById.has(state.selectedId))
+      parts.selection.clear();
+    yield 'billboard-update';
+    const billboardUpdate = yield* billboards.updateWork(state.renderedRows, {
+      onOperations: (counts) => Object.assign(operations, counts),
+    });
+    yield 'overlay-publish';
+    let changed = densityResult.changed;
+    beginBatch();
+    try {
+      restoreAmbientAnchors();
+      changed = stageCells(state.renderedRows) || changed;
+      changed = cull() || changed;
+      if (
+        billboardUpdate.created ||
+        billboardUpdate.removed ||
+        billboardUpdate.writes
+      )
+        changed = true;
+      if (changed) requestRender('render');
+    } finally {
+      endBatch();
+    }
+    services.performanceOperations?.(operations);
+    operations = null;
+    return changed;
+  }
+
+  function refreshSelection() {
+    if (!state.enabled || !billboards) return false;
+    // Selection changes spacing priority without reprojecting the view.
+    updateBadgeSpacing();
+    return cull();
+  }
+
+  function clear() {
+    workQueue.cancel();
+    operations = null;
+    clearCells();
+    density?.clear();
+    billboards?.clear();
+    if (state.points) state.points.show = false;
+    state.pointById.clear();
+    state.positions.clear();
+    state.renderedRows = [];
+    state.rowById.clear();
+    state.sightingCount = 0;
+    ambientAnchorIds.clear();
+    badgeScreens.clear();
+    crowdedBadgeIds.clear();
+    photoCardIds.clear();
+  }
+
+  function destroy() {
+    deactivate();
+    clear();
+    services.sprites?.unregisterSpriteCollection?.(
+      'wildlife-sightings',
+      state.points,
+    );
+    if (state.points) state.viewer?.scene?.primitives?.remove?.(state.points);
+    state.points = null;
+    billboards = null;
+    density?.destroy();
+    density = null;
+    appearances.clear();
+  }
+
+  return {
+    get density() {
+      return density;
+    },
+    get pending() {
+      return workQueue.pending;
+    },
+    init,
+    activate,
+    deactivate,
+    occluder,
+    cull,
+    rebuild,
+    refreshSelection,
+    setPhotoCardVisibility,
+    hasPhotoCard: (id) => photoCardIds.has(id),
+    clear,
+    destroy,
+    requestRender,
+    beginBatch,
+    endBatch,
+  };
+}
diff --git a/src/layers/wildlifeSightings/rendering.test.mjs b/src/layers/wildlifeSightings/rendering.test.mjs
new file mode 100644
index 000000000..9cea12530
--- /dev/null
+++ b/src/layers/wildlifeSightings/rendering.test.mjs
@@ -0,0 +1,544 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { createRendering } from './rendering.js';
+import { nearFarScalarValueAtDistance } from '../../data/focusDeemphasis.js';
+import { wildlifeGridCellId } from './gridViewport.js';
+import {
+  WILDLIFE_GROUND_READY_MAX_CHECKS,
+  WILDLIFE_SCALE_BY_DISTANCE,
+} from './policy.js';
+
+const NOW = Date.parse('2026-11-04T18:00:00Z');
+const base = {
+  stableId: 'synthetic:1',
+  origin: 'inaturalist',
+  lat: 47.6,
+  lon: -122.3,
+  iconic: 'Aves',
+  observedAt: NOW - 60_000,
+  quality: 'research',
+  count: null,
+  obscured: false,
+  cell: null,
+};
+
+function event() {
+  const listeners = new Set();
+  return {
+    addEventListener(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    emit(...args) {
+      for (const listener of [...listeners]) listener(...args);
+    },
+    get size() {
+      return listeners.size;
+    },
+  };
+}
+
+function harness(rows = [base], extra = {}) {
+  const counts = {
+    collections: 0,
+    created: 0,
+    removed: 0,
+    cleared: 0,
+    writes: [],
+  };
+  const tracked = new Set([
+    'position',
+    'image',
+    'color',
+    'scale',
+    'show',
+    'width',
+    'height',
+    'scaleByDistance',
+  ]);
+  class BillboardCollection extends Cesium.BillboardCollection {
+    constructor() {
+      super();
+      counts.collections += 1;
+    }
+    add(options) {
+      counts.created += 1;
+      const point = super.add(options);
+      return new Proxy(point, {
+        get: (target, key) => Reflect.get(target, key, target),
+        set(target, key, value) {
+          if (tracked.has(key)) counts.writes.push(key);
+          return Reflect.set(target, key, value, target);
+        },
+      });
+    }
+    remove(point) {
+      counts.removed += 1;
+      return super.remove(point);
+    }
+    removeAll() {
+      counts.cleared += 1;
+      return super.removeAll();
+    }
+  }
+  class GroundBatch {
+    constructor(options) {
+      Object.assign(this, options);
+      this.ready = false;
+    }
+    destroy() {
+      this.destroyed = true;
+    }
+    isDestroyed() {
+      return this.destroyed === true;
+    }
+  }
+  function primitives() {
+    const values = [];
+    return {
+      values,
+      get length() {
+        return values.length;
+      },
+      get: (i) => values[i],
+      add(primitive) {
+        values.push(primitive);
+        return primitive;
+      },
+      remove(primitive) {
+        const i = values.indexOf(primitive);
+        if (i < 0) return false;
+        values.splice(i, 1);
+        primitive.destroy();
+        return true;
+      },
+    };
+  }
+  const postRender = event();
+  const terrain = event();
+  const tileProgress = event();
+  const scene = {
+    primitives: primitives(),
+    groundPrimitives: primitives(),
+    postRender,
+    terrainProviderChanged: terrain,
+    globe: {
+      terrainProviderChanged: terrain,
+      tileLoadProgressEvent: tileProgress,
+    },
+  };
+  const state = {
+    enabled: true,
+    viewer: { scene, camera: { positionWC: {} } },
+    rows: new Map(rows.map((row) => [row.stableId, row])),
+    renderedRows: [],
+    rowById: new Map(),
+    pointById: new Map(),
+    positions: new Map(),
+    cells: [],
+    staging: null,
+    taxa: 'all',
+    selectedId: null,
+    query: { visibleBoxes: [{ south: -90, west: -180, north: 90, east: 180 }] },
+    band: 'cards',
+  };
+  const renders = [];
+  let visible = true;
+  const registration = new Set();
+  const rendering = createRendering({
+    state,
+    services: {
+      now: () => NOW,
+      cesium: {
+        ...Cesium,
+        BillboardCollection,
+        GroundPrimitive: GroundBatch,
+        GroundPolylinePrimitive: GroundBatch,
+      },
+      occluderFactory: () => ({ isPointVisible: () => visible }),
+      render: { governorRequestRender: (reason) => renders.push(reason) },
+      sprites: {
+        registerSpriteCollection: (_id, value) => registration.add(value),
+        unregisterSpriteCollection: (_id, value) => registration.delete(value),
+      },
+      ...extra,
+    },
+    parts: {
+      selection: {
+        clear() {
+          state.selectedId = null;
+        },
+        refreshAmbient() {},
+        publishSelected() {},
+        refreshContexts() {},
+      },
+    },
+  });
+  rendering.init();
+  rendering.activate();
+  return {
+    state,
+    scene,
+    rendering,
+    counts,
+    renders,
+    postRender,
+    terrain,
+    tileProgress,
+    registration,
+    visible(value) {
+      visible = value;
+    },
+    rows(next) {
+      state.rows = new Map(next.map((row) => [row.stableId, row]));
+    },
+  };
+}
+
+test('real Cesium billboard values update in place, and unchanged refreshes write nothing', () => {
+  const second = { ...base, stableId: 'synthetic:2', lon: -120 };
+  const h = harness([base, second]);
+  h.rendering.rebuild();
+  const collection = h.state.points;
+  const incumbent = h.state.pointById.get(base.stableId);
+  assert.equal(h.counts.collections, 1);
+  assert.equal(h.counts.created, 2);
+  assert.equal(incumbent.width * incumbent.scaleByDistance.farValue, 12);
+  assert.deepEqual(
+    incumbent.scaleByDistance,
+    new Cesium.NearFarScalar(...WILDLIFE_SCALE_BY_DISTANCE),
+  );
+  assert.equal(incumbent.color.alpha, 1);
+  h.counts.writes.length = 0;
+  h.renders.length = 0;
+  h.rows([{ ...second }, { ...base }]);
+  assert.equal(h.rendering.rebuild(), false);
+  assert.equal(h.rendering.cull(), false);
+  assert.deepEqual(h.counts.writes, []);
+  assert.deepEqual(h.renders, []);
+  h.rows([{ ...base, lat: base.lat + 0.01 }, second]);
+  assert.equal(h.rendering.rebuild(), true);
+  assert.deepEqual(h.counts.writes, ['position']);
+  assert.equal(h.state.pointById.get(base.stableId), incumbent);
+  assert.equal(h.state.points, collection);
+  h.rows([
+    { ...base, lat: base.lat + 0.01 },
+    { ...second, stableId: 'synthetic:3' },
+  ]);
+  h.rendering.rebuild();
+  assert.equal(h.counts.created, 3);
+  assert.equal(h.counts.removed, 1);
+  assert.equal(h.counts.cleared, 0);
+  h.rendering.destroy();
+  assert.equal(h.registration.size, 0);
+  assert.equal(h.scene.primitives.length, 0);
+  assert.equal(h.state.pointById.size, 0);
+  assert.equal(h.terrain.size, 0);
+  assert.equal(h.tileProgress.size, 0);
+});
+
+test('horizon changes write only changed visibility, with one governor request per batch', () => {
+  const h = harness();
+  h.rendering.rebuild();
+  h.counts.writes.length = 0;
+  h.renders.length = 0;
+  h.visible(false);
+  h.rendering.beginBatch();
+  h.rendering.cull();
+  h.rendering.requestRender('labels');
+  h.rendering.endBatch();
+  assert.deepEqual(h.counts.writes, ['show']);
+  assert.equal(h.renders.length, 1);
+  h.rendering.cull();
+  assert.deepEqual(h.counts.writes, ['show']);
+  assert.equal(h.renders.length, 1);
+  h.rendering.destroy();
+});
+
+test('badge pixels stay between 12 and 22 at near, mid and far heights, including selection', () => {
+  const h = harness();
+  h.rendering.rebuild();
+  const wildlife = h.state.pointById.get(base.stableId);
+  for (const selectedId of [null, base.stableId]) {
+    h.state.selectedId = selectedId;
+    h.rendering.refreshSelection();
+    for (const heightM of [
+      0, 1000, 9000, 120_000, 400_000, 1_500_000, 8_000_000, 10_000_000,
+    ]) {
+      const pixels =
+        wildlife.width *
+        wildlife.scale *
+        nearFarScalarValueAtDistance(wildlife.scaleByDistance, heightM);
+      assert.ok(
+        pixels >= 12 && pixels <= 22,
+        `${heightM}m, selected=${!!selectedId}: ${pixels}px`,
+      );
+    }
+  }
+  assert.deepEqual(
+    wildlife.color,
+    Cesium.Color.WHITE,
+    'keep the baked white glyph white',
+  );
+  h.rendering.destroy();
+});
+
+test('adjacent 28px bucket edges never overlap badges or erase sighting counts', () => {
+  const rows = [27, 29, 56, 84].map((x, i) => ({
+    ...base,
+    stableId: `edge:${i}`,
+    lon: base.lon + i * 0.01,
+    x,
+  }));
+  const h = harness(rows, {
+    project: (_scene, anchor) => {
+      const lon = Cesium.Math.toDegrees(
+        Cesium.Cartographic.fromCartesian(anchor).longitude,
+      );
+      return {
+        x: rows.find((row) => Math.abs(row.lon - lon) < 1e-7).x,
+        y: 100,
+      };
+    },
+  });
+  h.rendering.rebuild();
+  assert.equal(h.state.sightingCount, 4);
+  assert.equal(
+    h.state.pointById.size,
+    4,
+    'all occupied buckets retain their identities',
+  );
+  const visible = rows.filter(
+    (row) => h.state.pointById.get(row.stableId).show,
+  );
+  assert.equal(visible.length, 3);
+  for (let i = 0; i < visible.length; i++)
+    for (let j = i + 1; j < visible.length; j++)
+      assert.ok(Math.abs(visible[i].x - visible[j].x) >= 22);
+  h.counts.writes.length = 0;
+  h.renders.length = 0;
+  h.rendering.rebuild();
+  h.rendering.cull();
+  assert.deepEqual(h.counts.writes, []);
+  assert.deepEqual(h.renders, []);
+  h.rendering.destroy();
+});
+
+test('only painted photo cards hide their anchored badges, with zero repeated visibility writes', () => {
+  const h = harness();
+  h.rendering.rebuild();
+  const point = h.state.pointById.get(base.stableId);
+  assert.equal(
+    point.show,
+    true,
+    'a requested or loading card does not hide its badge',
+  );
+  h.counts.writes.length = 0;
+  h.renders.length = 0;
+  h.rendering.setPhotoCardVisibility(new Set([`sighting:${base.stableId}`]));
+  assert.equal(point.show, false);
+  assert.deepEqual(h.counts.writes, ['show']);
+  h.rendering.rebuild();
+  h.rendering.cull();
+  h.rendering.setPhotoCardVisibility(new Set([`sighting:${base.stableId}`]));
+  assert.deepEqual(h.counts.writes, ['show']);
+  assert.equal(h.renders.length, 1);
+  h.rendering.setPhotoCardVisibility(new Set());
+  assert.equal(
+    point.show,
+    true,
+    'a card that no longer paints restores its badge',
+  );
+  assert.deepEqual(h.counts.writes, ['show', 'show']);
+  h.rendering.destroy();
+});
+
+test('sampled fallback buckets allocate only representatives at every height, with zero idle writes', () => {
+  for (const heightM of [1000, 7_000_000]) {
+    const rows = ['a', 'b', 'c'].map((id, index) => ({
+      ...base,
+      stableId: `synthetic:${id}`,
+      lon: base.lon + index * 0.01,
+    }));
+    const screens = new Map(
+      rows.map((row) => [row.lon.toFixed(6), { x: 100, y: 100 }]),
+    );
+    const h = harness(rows, {
+      project: (_scene, anchor) => {
+        const lon = Cesium.Math.toDegrees(
+          Cesium.Cartographic.fromCartesian(anchor).longitude,
+        );
+        return screens.get(lon.toFixed(6));
+      },
+    });
+    h.state.viewer.camera.positionWC = Cesium.Cartesian3.fromDegrees(
+      base.lon,
+      base.lat,
+      heightM,
+    );
+    h.rendering.rebuild();
+    assert.equal(
+      h.state.pointById.size,
+      1,
+      'same bucket reduction near and far',
+    );
+    assert.equal(h.counts.created, 1);
+    screens.set(rows[2].lon.toFixed(6), { x: 200, y: 100 });
+    assert.equal(h.rendering.cull(), false);
+    h.rendering.rebuild(); // moveEnd recomputes buckets, never an idle frame.
+    assert.equal(h.state.pointById.size, 2);
+    assert.equal(h.counts.created, 2);
+    h.counts.writes.length = 0;
+    assert.equal(h.rendering.cull(), false);
+    assert.equal(h.rendering.rebuild(), false);
+    assert.deepEqual(h.counts.writes, []);
+    assert.equal(h.postRender.size, 0);
+    h.rendering.destroy();
+  }
+});
+
+test('UTFGrid creates a dedicated unpickable glow and observations alone create badges', () => {
+  let projections = 0;
+  const h = harness([base], {
+    project() {
+      projections++;
+      return { x: 100, y: 100 };
+    },
+  });
+  h.scene.canvas = { clientWidth: 280, clientHeight: 200 };
+  h.state.gridAvailable = true;
+  h.state.gridCells = [1, 50, 2].map((cellCount, index) => ({
+    id: wildlifeGridCellId(base.lat, base.lon + index * 0.01, 16),
+    lat: base.lat,
+    lon: base.lon + index * 0.01,
+    cellCount,
+  }));
+  h.rendering.rebuild();
+  const glow = h.rendering.density.collection;
+  assert.ok(glow);
+  assert.equal(glow.allowPicking, false);
+  assert.equal(glow.length, 3);
+  assert.equal(h.scene.primitives.length, 2);
+  assert.deepEqual([...h.state.pointById.keys()], [base.stableId]);
+  assert.deepEqual(h.state.renderedRows, [base]);
+  assert.equal(h.state.sightingCount, 53);
+  assert.equal(projections, 1, 'only observations require screen projections');
+  assert.equal(h.postRender.size, 0, 'density installs no frame listener');
+  h.state.gridCells = [...h.state.gridCells].reverse();
+  h.counts.writes.length = 0;
+  assert.equal(h.rendering.rebuild(), false);
+  assert.equal(h.rendering.density.collection, glow);
+  assert.deepEqual(h.counts.writes, []);
+  h.rendering.clear();
+  assert.equal(glow.isDestroyed(), true);
+  assert.equal(h.scene.primitives.length, 1);
+  assert.equal(h.state.points.length, 0);
+  h.rendering.destroy();
+  assert.equal(h.scene.primitives.length, 0);
+});
+
+test('tile arrival or loss cannot replace a real observation with a grid badge', () => {
+  const h = harness();
+  h.rendering.rebuild();
+  const badge = h.state.pointById.get(base.stableId);
+  h.state.gridAvailable = true;
+  h.state.gridCells = [
+    {
+      id: wildlifeGridCellId(base.lat, base.lon, 2),
+      lat: base.lat,
+      lon: base.lon,
+      cellCount: 10_000,
+    },
+  ];
+  h.rendering.rebuild();
+  const glow = h.rendering.density.collection;
+  assert.equal(h.state.sightingCount, 10_000);
+  assert.equal(h.state.pointById.get(base.stableId), badge);
+  h.state.gridAvailable = false;
+  h.rendering.rebuild();
+  assert.equal(h.state.pointById.get(base.stableId), badge);
+  assert.equal(h.state.sightingCount, 1);
+  assert.equal(glow.isDestroyed(), true);
+  h.rendering.destroy();
+});
+
+test('a selected observation remains rendered outside the viewport and observation window after a zoom', () => {
+  const selected = { ...base, observedAt: NOW - 49 * 3_600_000 };
+  const h = harness([]);
+  h.state.selectedId = selected.stableId;
+  h.state.selectedRow = selected;
+  h.state.query.visibleBoxes = [{ south: 0, west: 0, north: 1, east: 1 }];
+  h.rendering.rebuild();
+  assert.deepEqual(h.state.renderedRows, [selected]);
+  assert.equal(h.state.rowById.get(selected.stableId), selected);
+  assert.equal(h.state.pointById.has(selected.stableId), true);
+  h.state.band = 'regional';
+  h.state.viewer.camera.positionCartographic = { height: 1_500_000 };
+  h.rendering.rebuild();
+  assert.equal(h.state.selectedId, selected.stableId);
+  assert.equal(h.state.rowById.get(selected.stableId), selected);
+  h.rendering.destroy();
+});
+
+test('privacy ground staging has a bounded readiness listener and complete teardown', () => {
+  const h = harness([
+    {
+      ...base,
+      obscured: true,
+      cell: { south: 47.6, west: -122.4, north: 47.8, east: -122.2 },
+    },
+  ]);
+  h.rendering.rebuild();
+  assert.equal(h.postRender.size, 1);
+  assert.equal(h.scene.groundPrimitives.length, 2);
+  for (let i = 0; i < WILDLIFE_GROUND_READY_MAX_CHECKS; i++)
+    h.postRender.emit();
+  assert.equal(h.postRender.size, 0);
+  assert.equal(h.state.staging, null);
+  assert.equal(h.scene.groundPrimitives.length, 0);
+  h.rendering.destroy();
+  assert.equal(h.postRender.size, 0);
+});
+
+test('font readiness swaps images in place without billboard recreation or position work', () => {
+  const listeners = new Set();
+  let ready = false;
+  const badgeSprites = {
+    get: (group) =>
+      `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg"><circle r="${ready ? 9 : 8}" data-group="${group}"/></svg>`)}`,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+  const rows = [
+    base,
+    { ...base, stableId: 'synthetic:mammal', iconic: 'Mammalia', lon: -120 },
+  ];
+  const h = harness(rows, { badgeSprites });
+  h.rendering.rebuild();
+  const collection = h.state.points;
+  const points = new Map(h.state.pointById);
+  const before = new Map([...points].map(([id, point]) => [id, point.image]));
+  h.counts.writes.length = 0;
+  h.renders.length = 0;
+  ready = true;
+  for (const listener of listeners) listener();
+  assert.equal(h.state.points, collection);
+  assert.equal(h.counts.created, 2);
+  assert.equal(h.counts.removed, 0);
+  assert.equal(h.counts.cleared, 0);
+  assert.deepEqual(h.counts.writes, ['image', 'image']);
+  assert.equal(h.renders.length, 1);
+  for (const [id, point] of points) {
+    assert.equal(h.state.pointById.get(id), point);
+    assert.notEqual(point.image, before.get(id));
+  }
+  h.counts.writes.length = 0;
+  h.rows(rows.map((row) => ({ ...row, lat: row.lat + 0.01 })));
+  h.rendering.rebuild();
+  assert.deepEqual(h.counts.writes, ['position', 'position']);
+  h.rendering.destroy();
+  assert.equal(listeners.size, 0);
+});
diff --git a/src/layers/wildlifeSightings/selection.js b/src/layers/wildlifeSightings/selection.js
new file mode 100644
index 000000000..050da3fb5
--- /dev/null
+++ b/src/layers/wildlifeSightings/selection.js
@@ -0,0 +1,560 @@
+import { t } from '../../i18n/index.js';
+import { wildlifeMeasure } from './performance.js';
+import { compareWildlifeIds } from './model.js';
+import { isRecentWildlifeSighting } from './records.js';
+import {
+  ACARTIA_CREDIT,
+  registerDynamicCredit,
+} from '../../data/dataCredits.js';
+import {
+  WILDLIFE_OVERLAY_SOURCE_ID,
+  WILDLIFE_SELECTED_SOURCE_ID,
+  WILDLIFE_LABEL_SOURCE_ID,
+  WILDLIFE_LABEL_SOURCE_OPTIONS,
+  WILDLIFE_OVERLAY_SOURCE_OPTIONS,
+  WILDLIFE_SELECTED_SOURCE_OPTIONS,
+  buildWildlifeThumbnailEntry,
+  buildWildlifeSelectedLabel,
+  buildWildlifeLabelEntry,
+  wildlifeCommonName,
+  wildlifeDisplayName,
+  wildlifeLabelScore,
+  selectWildlifeAmbientRows,
+} from './cards.js';
+import {
+  WILDLIFE_CARD_LIMIT,
+  WILDLIFE_CARD_SHOW_MAX_METERS,
+  WILDLIFE_CARD_HIDE_MAX_METERS,
+  WILDLIFE_LABEL_NAME_SEPARATION_PX,
+  WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS,
+  WILDLIFE_LABEL_LIMIT,
+} from './policy.js';
+
+const CONTEXT_LIMIT = 30;
+
+/** Overlay sources, pinned observation selection and external focus. */
+export function createSelection({ state, services, parts }) {
+  const overlay = services.overlayHost;
+  const sourceIds = [
+    WILDLIFE_OVERLAY_SOURCE_ID,
+    WILDLIFE_LABEL_SOURCE_ID,
+    WILDLIFE_SELECTED_SOURCE_ID,
+  ];
+  const listeners = new Set();
+  // Coordinates are refreshed only by the existing camera/data label pass.
+  const labelScreens = new Map();
+  const ambientSourceOptions = {
+    ...WILDLIFE_OVERLAY_SOURCE_OPTIONS,
+    onVisibilityChange: (ids) => parts.rendering.setPhotoCardVisibility?.(ids),
+  };
+
+  function renderBatch(fn) {
+    parts.rendering.beginBatch?.();
+    try {
+      return fn();
+    } finally {
+      parts.rendering.endBatch?.();
+    }
+  }
+
+  function selectionRow() {
+    if (!state.enabled || !state.selectedId) return null;
+    return state.selectedRow || state.rowById.get(state.selectedId) || null;
+  }
+
+  function dispatch(listener, row, metadata) {
+    try {
+      listener(row, metadata);
+    } catch {
+      // A disconnected UI surface must not prevent map selection or teardown.
+    }
+  }
+
+  function notify({ explicitSelection = false } = {}) {
+    const row = selectionRow();
+    const metadata = { explicitSelection: explicitSelection === true };
+    for (const listener of listeners) dispatch(listener, row, metadata);
+  }
+
+  function subscribe(listener) {
+    if (typeof listener !== 'function') return () => {};
+    if (!state.destroyed) listeners.add(listener);
+    dispatch(listener, selectionRow(), { explicitSelection: false });
+    return () => listeners.delete(listener);
+  }
+
+  const cardActions = {
+    select: selectAndFocus,
+    hasRow: (id) => state.enabled && state.rowById.has(id),
+  };
+
+  function publishAmbient() {
+    return wildlifeMeasure('overlay-publish', publishAmbientEntries);
+  }
+
+  function publishAmbientEntries() {
+    if (!state.enabled || !overlay) return;
+    overlay.setEntries(
+      WILDLIFE_OVERLAY_SOURCE_ID,
+      state.ambientRows.map((row) => ({
+        ...buildWildlifeThumbnailEntry(row, services.now(), {
+          ...cardActions,
+          image: parts.photos.get(row),
+          selected: row.stableId === state.selectedId,
+        }),
+        position: state.positions.get(row.stableId),
+      })),
+      ambientSourceOptions,
+    );
+    parts.rendering.requestRender('photos');
+  }
+
+  function publishSelected() {
+    return wildlifeMeasure('overlay-publish', publishSelectedEntries);
+  }
+
+  function publishSelectedEntries() {
+    if (!state.enabled || !overlay) return;
+    const row = selectionRow();
+    // The selected sighting's painted thumbnail already shows its name.
+    const label =
+      row && !parts.rendering.hasPhotoCard?.(row.stableId)
+        ? buildWildlifeSelectedLabel(row)
+        : null;
+    overlay.setEntries(
+      WILDLIFE_SELECTED_SOURCE_ID,
+      label
+        ? [
+            {
+              ...label,
+              position: state.positions.get(row.stableId),
+            },
+          ]
+        : [],
+      WILDLIFE_SELECTED_SOURCE_OPTIONS,
+    );
+  }
+
+  function publishLabels() {
+    return wildlifeMeasure('overlay-publish', publishLabelsEntries);
+  }
+
+  function publishLabelsEntries() {
+    if (!state.enabled || !overlay) return;
+    const names = new Map();
+    const remember = (row) => {
+      const screen = labelScreens.get(row.stableId);
+      if (!screen) return;
+      const name = wildlifeDisplayName(row);
+      if (!names.has(name)) names.set(name, []);
+      names.get(name).push(screen);
+    };
+    // Painted photos win regardless of score. Queued or rejected images do not
+    // suppress neighbors. Selection wins over ambient names using the same cache.
+    for (const row of state.ambientRows)
+      if (parts.rendering.hasPhotoCard?.(row.stableId)) remember(row);
+    const selected = selectionRow();
+    if (
+      selected &&
+      (state.viewer.camera?.positionCartographic?.height ?? 0) <
+        WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS
+    )
+      remember(selected);
+    const entries = [];
+    for (const row of state.labelRows || []) {
+      if (
+        row.stableId === state.selectedId ||
+        parts.rendering.hasPhotoCard?.(row.stableId)
+      )
+        continue;
+      const screen = labelScreens.get(row.stableId);
+      const nearby = names.get(wildlifeDisplayName(row));
+      if (
+        screen &&
+        nearby?.some(
+          (other) =>
+            (screen.x - other.x) ** 2 + (screen.y - other.y) ** 2 <
+            WILDLIFE_LABEL_NAME_SEPARATION_PX ** 2,
+        )
+      )
+        continue;
+      const entry = buildWildlifeLabelEntry(row, {
+        ...cardActions,
+        nowMs: services.now(),
+      });
+      if (!entry) continue;
+      entries.push({ ...entry, position: state.positions.get(row.stableId) });
+      remember(row);
+      if (entries.length >= WILDLIFE_LABEL_LIMIT) break;
+    }
+    overlay.setEntries(
+      WILDLIFE_LABEL_SOURCE_ID,
+      entries,
+      WILDLIFE_LABEL_SOURCE_OPTIONS,
+    );
+    parts.rendering.requestRender('labels');
+  }
+
+  function refreshLabels() {
+    if (!state.enabled || !overlay) return;
+    const scene = state.viewer.scene;
+    const horizon = parts.rendering.occluder();
+    const width = scene.canvas?.clientWidth || 0;
+    const height = scene.canvas?.clientHeight || 0;
+    // Rank during camera/data passes; the host handles pixel collisions.
+    const nowMs = services.now();
+    const candidates = [];
+    labelScreens.clear();
+    const rows = new Map(state.renderedRows.map((row) => [row.stableId, row]));
+    for (const row of state.ambientRows) rows.set(row.stableId, row);
+    for (const row of rows.values()) {
+      if (!wildlifeCommonName(row)) continue;
+      const position = state.positions.get(row.stableId);
+      if (!position || (horizon && horizon.isPointVisible(position) !== true))
+        continue;
+      const screen = services.project(scene, position);
+      if (
+        !screen ||
+        screen.x < 0 ||
+        screen.y < 0 ||
+        screen.x > width ||
+        screen.y > height
+      )
+        continue;
+      labelScreens.set(row.stableId, { x: screen.x, y: screen.y });
+      candidates.push(row);
+    }
+    candidates.sort(
+      (a, b) =>
+        wildlifeLabelScore(b, nowMs) - wildlifeLabelScore(a, nowMs) ||
+        compareWildlifeIds(a.stableId, b.stableId),
+    );
+    // Keep ranked candidates so a disappearing photo or cleared selection can
+    // restore suppressed names without another projection pass. Cap after dedup.
+    state.labelRows = candidates;
+    publishLabels();
+  }
+
+  function ambientCandidates(rows) {
+    const scene = state.viewer.scene;
+    const horizon = parts.rendering.occluder();
+    const width = scene.canvas?.clientWidth ?? Infinity;
+    const height = scene.canvas?.clientHeight ?? Infinity;
+    const screens = new Map();
+    const nowMs = services.now();
+    const taxa = state.drawnParams?.taxa ?? state.taxa;
+    const eligible = rows.filter((row) => {
+      if (
+        !row.photo ||
+        row.obscured ||
+        !isRecentWildlifeSighting(row, nowMs, taxa)
+      )
+        return false;
+      const position = state.positions.get(row.stableId);
+      if (!position || (horizon && horizon.isPointVisible(position) !== true))
+        return false;
+      const screen = services.project(scene, position);
+      if (
+        !screen ||
+        screen.x < 0 ||
+        screen.y < 0 ||
+        screen.x > width ||
+        screen.y > height
+      )
+        return false;
+      screens.set(row.stableId, { x: screen.x, y: screen.y });
+      return true;
+    });
+    return { eligible, screens, width, height };
+  }
+
+  /** Snapshot before acquisition replaces its sample. Only currently visible
+   * photos survive; acquisition also checks the observation window/params. */
+  function retainedAmbientRows() {
+    if (!state.enabled) return [];
+    const height =
+      state.viewer?.camera?.positionCartographic?.height ?? Infinity;
+    if (height >= WILDLIFE_CARD_HIDE_MAX_METERS) return [];
+    return ambientCandidates(state.ambientRows).eligible;
+  }
+
+  function refreshAmbient() {
+    if (!state.enabled) return;
+    refreshLabels();
+    const height =
+      state.viewer?.camera?.positionCartographic?.height ?? Infinity;
+    if (state.ambientActive) {
+      if (height >= WILDLIFE_CARD_HIDE_MAX_METERS) state.ambientActive = false;
+    } else if (height <= WILDLIFE_CARD_SHOW_MAX_METERS)
+      state.ambientActive = true;
+    if (!state.ambientActive) {
+      state.ambientRows = [];
+      state.ambientIds = [];
+      parts.photos.setAmbient([]);
+      publishAmbient();
+      return;
+    }
+    // A bucket rebuild may hide an incumbent behind a newly sampled neighbor.
+    // Retain its actual loaded row; rendering gives ambient IDs bucket priority.
+    const byId = new Map(state.renderedRows.map((row) => [row.stableId, row]));
+    for (const row of state.ambientRows) {
+      const current = state.rowById.get(row.stableId);
+      if (current) byId.set(row.stableId, current);
+    }
+    const candidates = ambientCandidates([...byId.values()]);
+    state.ambientRows = selectWildlifeAmbientRows(
+      candidates.eligible,
+      state.ambientIds,
+      services.now(),
+      WILDLIFE_CARD_LIMIT,
+      candidates,
+    );
+    state.ambientIds = state.ambientRows.map((row) => row.stableId);
+    parts.photos.setAmbient(state.ambientRows);
+    publishAmbient();
+  }
+
+  // iNaturalist is static; Acartia enters the attribution popover on first use.
+  function syncCredits() {
+    if (!state.enabled) return;
+    if (state.renderedRows.some((row) => row.origin === 'acartia'))
+      registerDynamicCredit(state.viewer, ACARTIA_CREDIT);
+  }
+
+  function registerContext(row) {
+    if (!services.context?.registerEntityContext) return null;
+    let carrier = state.carriers.get(row.stableId);
+    if (!carrier) {
+      carrier = { show: true };
+      state.carriers.set(row.stableId, carrier);
+    }
+    carrier.__localBaseCartesian = state.positions.get(row.stableId);
+    // A badge yielding to its photo or a neighbor is still a visible sighting.
+    // Context visibility follows the anchor, independently of badge declutter.
+    const horizon = parts.rendering.occluder();
+    carrier.show =
+      !horizon || horizon.isPointVisible(carrier.__localBaseCartesian) === true;
+    const name = row.commonName || row.scientificName || t('Cetacean');
+    // i18n-ignore: provider names and feed-supplied organism names are verbatim
+    const label = `${name} · ${row.origin === 'acartia' ? 'Acartia' : 'iNaturalist'}`;
+    services.context.registerEntityContext(carrier, {
+      id: row.stableId,
+      layerId: 'wildlife-sightings',
+      layerName: t('Wildlife Sightings'),
+      source: row.origin === 'acartia' ? 'Acartia' : 'iNaturalist',
+      label,
+      latitude: row.lat,
+      longitude: row.lon,
+      properties: {
+        quality: row.quality,
+        iconic: row.iconic,
+        obscured: row.obscured,
+      },
+      select: () => selectAndFocus(row.stableId),
+    });
+    return carrier;
+  }
+
+  function refreshContexts() {
+    if (!services.context) return;
+    const rows = state.renderedRows.slice(0, CONTEXT_LIMIT);
+    const selected = selectionRow();
+    if (selected && !rows.includes(selected)) rows.push(selected);
+    const next = new Set(rows.map((row) => row.stableId));
+    try {
+      for (const row of rows) registerContext(row);
+      const store = services.context.getContextStore?.();
+      for (const id of state.contextIds) {
+        if (!next.has(id)) {
+          if (store?.entities?.get(id)?.layerId === 'wildlife-sightings')
+            store.entities.delete(id);
+          state.carriers.delete(id);
+        }
+      }
+    } catch {
+      // Optional context surfaces must not prevent data or cards rendering.
+    }
+    state.contextIds = next;
+  }
+
+  function select(id, { publishContext = true } = {}) {
+    return renderBatch(() => selectRecord(id, { publishContext }));
+  }
+
+  function selectRecord(id, { publishContext = true } = {}) {
+    if (!state.enabled || !state.rowById.has(id)) return false;
+    const row = state.rowById.get(id);
+    state.selectedId = id;
+    state.selectedRow = row;
+    parts.rendering.refreshSelection();
+    publishAmbient();
+    publishLabels();
+    publishSelected();
+    try {
+      const carrier = registerContext(row);
+      state.contextIds.add(id);
+      if (publishContext && carrier) {
+        state.publishingContext = true;
+        try {
+          services.context?.selectEntityContext?.(carrier);
+        } finally {
+          state.publishingContext = false;
+        }
+      }
+    } catch {
+      state.publishingContext = false;
+    }
+    notify({ explicitSelection: true });
+    parts.rendering.requestRender('select');
+    return true;
+  }
+
+  function selectAndFocus(id, options = {}) {
+    const row = state.rowById.get(typeof id === 'string' ? id : id?.stableId);
+    if (!state.enabled || !row) return false;
+    if (!select(row.stableId, options)) return false;
+    services.focus?.requestWorldFocus?.({
+      kind: row.obscured ? 'sighting-area' : 'sighting',
+      id: row.stableId,
+      label: row.commonName || row.scientificName || t('SIGHTING'),
+      position: state.positions.get(row.stableId),
+    });
+    return true;
+  }
+
+  function clear() {
+    return renderBatch(clearRecord);
+  }
+
+  function clearRecord() {
+    const hadSelection = state.selectedId !== null;
+    state.selectedId = null;
+    state.selectedRow = null;
+    try {
+      services.context?.clearSelectedEntityContextForLayer?.(
+        'wildlife-sightings',
+      );
+    } catch {
+      /* optional context host is already gone */
+    }
+    if (state.enabled) {
+      if (hadSelection) publishAmbient();
+      publishSelected();
+      if (hadSelection) publishLabels();
+      if (hadSelection) parts.rendering.requestRender('select');
+    }
+    notify();
+    return hadSelection;
+  }
+
+  function clearAndRebuild() {
+    return renderBatch(() => {
+      const hadSelection = clear();
+      if (hadSelection) parts.rendering.refreshSelection();
+      return hadSelection;
+    });
+  }
+
+  function install() {
+    const onContext = (event) => {
+      if (!state.enabled || state.publishingContext) return;
+      const record =
+        event.detail || services.context?.getSelectedEntityContext?.();
+      if (record?.layerId === 'wildlife-sightings')
+        selectAndFocus(record.id, { publishContext: false });
+    };
+    services.eventTarget?.addEventListener?.('gev:entity-selected', onContext);
+    state.removeContext = () =>
+      services.eventTarget?.removeEventListener?.(
+        'gev:entity-selected',
+        onContext,
+      );
+    if (typeof services.screenSpaceEventHandlerFactory !== 'function') return;
+    state.clickHandler = services.screenSpaceEventHandlerFactory(state.viewer);
+    state.clickHandler.setInputAction((click) => {
+      if (!state.enabled || services.pointer?.isPointerFree?.() === false)
+        return;
+      const hit =
+        overlay?.hitTest?.(click.position?.x, click.position?.y, {
+          sourceId: WILDLIFE_SELECTED_SOURCE_ID,
+        }) ||
+        overlay?.hitTest?.(click.position?.x, click.position?.y, {
+          sourceId: WILDLIFE_OVERLAY_SOURCE_ID,
+        }) ||
+        overlay?.hitTest?.(click.position?.x, click.position?.y, {
+          sourceId: WILDLIFE_LABEL_SOURCE_ID,
+        });
+      if (hit) {
+        hit.entry?.activate?.();
+        return;
+      }
+      const picked = state.viewer.scene.pick(click.position);
+      const id =
+        services.picking?.resolvePickId?.(picked) ??
+        picked?.id ??
+        picked?.primitive?.id;
+      if (
+        typeof id === 'string' &&
+        id.startsWith('wildlife:') &&
+        selectAndFocus(id.slice(9))
+      )
+        return;
+      if (
+        id &&
+        services.picking?.isOwnedByOtherLayer?.('wildlife-sightings', id)
+      )
+        return;
+      clearAndRebuild();
+    }, services.cesium.ScreenSpaceEventType.LEFT_CLICK);
+  }
+
+  function remove() {
+    state.clickHandler?.destroy();
+    state.clickHandler = null;
+    state.removeContext?.();
+    state.removeContext = null;
+    clear();
+    try {
+      services.context?.removeEntityContextsForLayer?.('wildlife-sightings');
+    } catch {
+      /* optional context host is already gone */
+    }
+    state.carriers.clear();
+    state.contextIds.clear();
+    state.ambientIds = [];
+    state.ambientRows = [];
+    state.ambientActive = false;
+    state.labelRows = [];
+    labelScreens.clear();
+    for (const id of sourceIds) {
+      overlay?.clearSource?.(id);
+      overlay?.setVisible?.(id, false);
+    }
+  }
+
+  return {
+    selectAndFocus,
+    clear,
+    clearAndRebuild,
+    subscribe,
+    notify,
+    destroy() {
+      listeners.clear();
+    },
+    install,
+    remove,
+    refreshAmbient,
+    retainedAmbientRows,
+    publishAmbient,
+    publishSelected,
+    photoCardsChanged() {
+      renderBatch(() => {
+        publishLabels();
+        publishSelected();
+      });
+    },
+    refreshContexts,
+    syncCredits,
+    sourceIds,
+  };
+}
diff --git a/src/layers/wildlifeSightings/selection.test.mjs b/src/layers/wildlifeSightings/selection.test.mjs
new file mode 100644
index 000000000..2263fd25e
--- /dev/null
+++ b/src/layers/wildlifeSightings/selection.test.mjs
@@ -0,0 +1,301 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createSelection } from './selection.js';
+
+const row = {
+  stableId: 'inat:123',
+  origin: 'inaturalist',
+  lat: 48.1,
+  lon: 8.2,
+  commonName: 'Synthetic bird',
+  iconic: 'Aves',
+  observedAt: Date.UTC(2026, 10, 4),
+  link: 'https://www.inaturalist.org/observations/123',
+};
+
+function fixture(sighting = row) {
+  const position = { x: 300, y: 300, z: 0 };
+  const entries = new Map();
+  const flights = [];
+  const seen = [];
+  const painted = new Set();
+  let hit = null;
+  let projections = 0;
+  let picked = null;
+  let click;
+  const state = {
+    enabled: true,
+    destroyed: false,
+    selectedId: null,
+    selectedRow: null,
+    rowById: new Map([[sighting.stableId, sighting]]),
+    positions: new Map([[sighting.stableId, position]]),
+    renderedRows: [sighting],
+    carriers: new Map(),
+    contextIds: new Set(),
+    ambientIds: [],
+    ambientRows: [],
+    labelRows: [],
+    viewer: {
+      scene: {
+        pick: () => picked,
+        canvas: { clientWidth: 1200, clientHeight: 900 },
+      },
+      camera: { positionCartographic: { height: 30_000 } },
+    },
+  };
+  const selection = createSelection({
+    state,
+    services: {
+      overlayHost: {
+        setEntries: (id, value) => entries.set(id, value),
+        clearSource: (id) => entries.delete(id),
+        setVisible() {},
+        hitTest: (_x, _y, { sourceId }) =>
+          hit?.sourceId === sourceId ? hit : null,
+      },
+      now: () => row.observedAt + 60_000,
+      project: (_scene, anchor) => {
+        projections++;
+        return anchor;
+      },
+      focus: { requestWorldFocus: (request) => flights.push(request) },
+      screenSpaceEventHandlerFactory: () => ({
+        setInputAction: (fn) => (click = fn),
+        destroy() {},
+      }),
+      cesium: { ScreenSpaceEventType: { LEFT_CLICK: 0 } },
+      eventTarget: new EventTarget(),
+    },
+    parts: {
+      rendering: {
+        refreshSelection() {},
+        requestRender() {},
+        occluder: () => null,
+        hasPhotoCard: (id) => painted.has(id),
+      },
+      photos: { get: () => ({ width: 75, height: 75 }), setAmbient() {} },
+    },
+  });
+  selection.subscribe((value, metadata) => seen.push({ value, metadata }));
+  return {
+    state,
+    selection,
+    position,
+    flights,
+    entries,
+    seen,
+    get projections() {
+      return projections;
+    },
+    hit(sourceId, entryId) {
+      const entry = entries
+        .get(sourceId)
+        ?.find((entry) => entry.id === entryId);
+      hit = entry ? { sourceId, entryId, entry } : null;
+    },
+    paint(ids) {
+      painted.clear();
+      for (const id of ids) painted.add(id);
+      selection.photoCardsChanged();
+    },
+    click(id = `wildlife:${sighting.stableId}`) {
+      picked = id ? { id } : null;
+      click({ position: { x: 10, y: 20 } });
+    },
+  };
+}
+
+test('a real sighting click pins its row, opens its label and focuses its true position', () => {
+  const f = fixture();
+  f.selection.install();
+  f.click();
+  assert.equal(f.state.selectedId, row.stableId);
+  assert.equal(f.state.selectedRow, row);
+  assert.equal(f.flights.length, 1);
+  assert.deepEqual(f.flights[0], {
+    kind: 'sighting',
+    id: row.stableId,
+    label: row.commonName,
+    position: f.position,
+  });
+  assert.deepEqual(f.seen.at(-1), {
+    value: row,
+    metadata: { explicitSelection: true },
+  });
+  assert.equal(f.entries.get('wildlife-sightings-selected').length, 1);
+  f.selection.remove();
+});
+
+test('selected photo and name cards use the selected lane, select on click and never open links themselves', () => {
+  for (const photo of [
+    null,
+    {
+      square:
+        'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpg',
+      licence: 'cc-by',
+      attribution: 'Synthetic Photographer',
+    },
+  ]) {
+    const sighting = { ...row, photo };
+    const f = fixture(sighting);
+    f.selection.install();
+    f.selection.refreshAmbient();
+    const source = photo ? 'wildlife-sightings' : 'wildlife-sightings-labels';
+    const id = photo
+      ? 'sighting:inat:123'
+      : 'wildlife-sightings-label:inat:123';
+    f.hit(source, id);
+    f.click();
+    assert.equal(f.flights.length, 1);
+    if (photo) f.paint([row.stableId]);
+    const selectedSource = photo ? source : 'wildlife-sightings-selected';
+    const card = f.entries.get(selectedSource)[0];
+    assert.equal(card.selected, true);
+    assert.equal(card.paintLane, 'selected');
+    assert.ok(
+      !(card.details || []).some((line) => line.includes('↗')),
+      'the anchored photo card owns the single source link',
+    );
+    assert.match(card.accessibilityLabel, /Synthetic bird/);
+    if (photo) {
+      assert.equal(card.variant, 'thumbnail');
+      assert.ok(card.image);
+      assert.deepEqual(f.entries.get('wildlife-sightings-selected'), []);
+    }
+    f.hit(selectedSource, card.id);
+    f.click('other:aircraft');
+    assert.equal(f.flights.length, photo ? 2 : 1);
+    f.selection.clearAndRebuild();
+    if (photo) {
+      const ambient = f.entries.get(source)[0];
+      assert.equal(ambient.selected, undefined);
+      assert.deepEqual(ambient.details, ['© Synthetic Photographer']);
+    }
+  }
+});
+
+test('nearby duplicate display names yield to painted cards and higher-ranked labels using cached screens', () => {
+  const low = {
+    ...row,
+    stableId: 'inat:low',
+    quality: 'research',
+    photo: {
+      square:
+        'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpg',
+      licence: 'cc-by',
+      attribution: 'Synthetic Photographer',
+    },
+  };
+  const high = { ...low, stableId: 'inat:high', favesCount: 50 };
+  const far = { ...row, stableId: 'inat:far' };
+  const different = {
+    ...row,
+    stableId: 'inat:different',
+    commonName: 'Other bird',
+  };
+  const f = fixture();
+  f.state.renderedRows = [low, high, far, different];
+  f.state.rowById = new Map(
+    f.state.renderedRows.map((row) => [row.stableId, row]),
+  );
+  f.state.positions = new Map([
+    [low.stableId, { x: 300, y: 300 }],
+    [high.stableId, { x: 379, y: 300 }],
+    [far.stableId, { x: 460, y: 300 }],
+    [different.stableId, { x: 310, y: 300 }],
+  ]);
+  const labelIds = () =>
+    f.entries.get('wildlife-sightings-labels').map((entry) => entry.id);
+  f.selection.refreshAmbient();
+  assert.ok(!labelIds().includes('wildlife-sightings-label:inat:low'));
+  assert.ok(labelIds().includes('wildlife-sightings-label:inat:high'));
+  assert.ok(
+    labelIds().includes('wildlife-sightings-label:inat:far'),
+    '81px names survive',
+  );
+  assert.ok(labelIds().includes('wildlife-sightings-label:inat:different'));
+  const projections = f.projections;
+  f.state.ambientRows = [low];
+  f.paint([low.stableId]);
+  assert.ok(
+    !labelIds().includes('wildlife-sightings-label:inat:high'),
+    'a painted lower-score card wins',
+  );
+  assert.equal(
+    f.projections,
+    projections,
+    'paint membership uses the last label pass',
+  );
+  f.paint([]);
+  assert.ok(
+    labelIds().includes('wildlife-sightings-label:inat:high'),
+    'a queued/unpainted card suppresses nothing',
+  );
+  f.selection.selectAndFocus(low.stableId);
+  assert.ok(
+    !labelIds().includes('wildlife-sightings-label:inat:high'),
+    'selected labels outrank ambient names',
+  );
+  assert.equal(
+    f.projections,
+    projections,
+    'selection never projects the population',
+  );
+  f.selection.clearAndRebuild();
+  f.state.positions.set(high.stableId, { x: 600, y: 300 });
+  f.selection.refreshAmbient();
+  assert.ok(
+    labelIds().includes('wildlife-sightings-label:inat:low'),
+    'moveEnd admits separated names',
+  );
+});
+
+test('selection remains published while a new sample or camera pass replaces rendered lookup rows', () => {
+  const f = fixture();
+  f.selection.selectAndFocus(row.stableId);
+  f.state.rowById.clear();
+  f.state.renderedRows = [];
+  f.selection.publishSelected();
+  f.selection.notify();
+  assert.equal(f.seen.at(-1).value, row);
+  assert.equal(
+    f.entries.get('wildlife-sightings-selected')[0].position,
+    f.position,
+  );
+  assert.equal(
+    f.flights.length,
+    1,
+    'refresh notifications never start another flight',
+  );
+  f.selection.clearAndRebuild();
+  assert.equal(f.state.selectedId, null);
+  assert.equal(f.state.selectedRow, null);
+  assert.equal(f.seen.at(-1).value, null);
+  assert.deepEqual(f.entries.get('wildlife-sightings-selected'), []);
+});
+
+test('an obscured observation focuses only its existing privacy-safe anchor', () => {
+  const obscured = { ...row, obscured: true, lat: 48.1, lon: 8.3 };
+  const f = fixture(obscured);
+  assert.equal(f.selection.selectAndFocus(obscured.stableId), true);
+  assert.equal(f.flights[0].kind, 'sighting-area');
+  assert.equal(f.flights[0].position, f.position);
+  assert.equal(f.state.selectedRow, obscured);
+});
+
+test('empty clicks and layer removal release the selected row and its overlay', () => {
+  const f = fixture();
+  f.selection.install();
+  f.click();
+  f.click(null);
+  assert.equal(f.state.selectedRow, null);
+  assert.equal(f.state.selectedId, null);
+  f.click();
+  f.state.enabled = false;
+  f.selection.remove();
+  assert.equal(f.state.selectedRow, null);
+  assert.equal(f.state.selectedId, null);
+  assert.equal(f.seen.at(-1).value, null);
+  assert.equal(f.entries.size, 0);
+});
diff --git a/src/layers/wildlifeSightings/source.js b/src/layers/wildlifeSightings/source.js
new file mode 100644
index 000000000..7af6d1e72
--- /dev/null
+++ b/src/layers/wildlifeSightings/source.js
@@ -0,0 +1,557 @@
+import { readResponseJsonCapped } from '../../sources/httpBody.js';
+import { mergeSightings } from './records.js';
+import { wildlifeMeasure } from './performance.js';
+import { ACARTIA_GUARD_BOX, TAXA_PRESETS } from './policy.js';
+import { boxIntersects } from './viewport.js';
+import {
+  WILDLIFE_GRID_MAX_ZOOM,
+  WILDLIFE_GRID_TILE_CAP,
+  wildlifeGridCellId,
+} from './gridViewport.js';
+
+// Leave room for projected observations while bounding malformed proxy replies.
+const SNAPSHOT_MAX_BYTES = 2 * 1024 * 1024;
+// The proxy owns upstream pacing; observation requests precede these workers.
+export const WILDLIFE_GRID_CONCURRENCY = 4;
+export const WILDLIFE_GRID_CACHE_MAX = 400;
+export const WILDLIFE_GRID_TTL_MS = 15 * 60_000;
+// Match the proxy's one-hour stale allowance. Keep the original data time so
+// repeated refresh failures never extend a tile's usable life.
+const GRID_STALE_MAX_MS = 3_600_000;
+const HOUR_MS = 3_600_000;
+
+function validTile(tile) {
+  return (
+    !!tile &&
+    Number.isInteger(tile.z) &&
+    tile.z >= 0 &&
+    tile.z <= WILDLIFE_GRID_MAX_ZOOM &&
+    Number.isInteger(tile.x) &&
+    Number.isInteger(tile.y) &&
+    tile.x >= 0 &&
+    tile.y >= 0 &&
+    tile.x < 2 ** tile.z &&
+    tile.y < 2 ** tile.z
+  );
+}
+
+function validProjectedGrid(payload) {
+  return (
+    Number.isFinite(payload?.fetchedAt) &&
+    Number.isSafeInteger(payload.totalResults) &&
+    payload.totalResults >= 0 &&
+    (payload.stale === undefined || typeof payload.stale === 'boolean') &&
+    Array.isArray(payload.cells) &&
+    payload.cells.length <= 4096 &&
+    payload.cells.every(
+      (cell) =>
+        cell &&
+        Object.keys(cell).sort().join(',') === 'cellCount,id,lat,lon' &&
+        /^grid:\d+\/\d+\/\d+:\d+:\d+$/.test(cell.id) &&
+        Number.isSafeInteger(cell.cellCount) &&
+        cell.cellCount > 0 &&
+        Number.isFinite(cell.lat) &&
+        Math.abs(cell.lat) <= 90 &&
+        Number.isFinite(cell.lon) &&
+        Math.abs(cell.lon) <= 180 &&
+        wildlifeGridCellId(
+          cell.lat,
+          cell.lon,
+          Number(cell.id.split(':')[1].split('/')[0]),
+        ) === cell.id,
+    ) &&
+    new Set(payload.cells.map((cell) => cell.id)).size ===
+      payload.cells.length &&
+    payload.cells.reduce((sum, cell) => sum + cell.cellCount, 0) ===
+      payload.totalResults
+  );
+}
+
+function retryAfterSeconds(value, nowMs) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const text = value.trim();
+  if (/^\d+(?:\.\d+)?$/.test(text)) {
+    const seconds = Number(text);
+    return Number.isFinite(seconds) ? Math.ceil(seconds) : null;
+  }
+  // Reject malformed numeric values rather than letting Date.parse interpret
+  // them as calendar dates. HTTP dates include a named weekday or month.
+  if (!/[a-z]/i.test(text)) return null;
+  const deadline = Date.parse(text);
+  return Number.isFinite(deadline) && Number.isFinite(nowMs)
+    ? Math.max(0, Math.ceil((deadline - nowMs) / 1000))
+    : null;
+}
+
+function validProjectedRows(rows, origin) {
+  return (
+    Array.isArray(rows) &&
+    rows.every(
+      (row) =>
+        row &&
+        typeof row.stableId === 'string' &&
+        row.stableId.startsWith(
+          origin === 'inaturalist' ? 'inat:' : 'acartia:',
+        ) &&
+        row.origin === origin &&
+        Number.isFinite(row.lat) &&
+        Math.abs(row.lat) <= 90 &&
+        Number.isFinite(row.lon) &&
+        Math.abs(row.lon) <= 180,
+    )
+  );
+}
+
+/** Merge occupied cells incrementally; neighboring UTFGrid hit tiles can
+ * report the same geographic cell, so source ids remain the dedupe key. */
+export function combineWildlifeGridSnapshots(snapshots, error = null) {
+  const cells = [
+    ...new Map(
+      snapshots
+        .flatMap((snapshot) => snapshot.cells)
+        .map((cell) => [cell.id, cell]),
+    ).values(),
+  ];
+  const totalResults = cells.reduce((sum, cell) => sum + cell.cellCount, 0);
+  if (!Number.isSafeInteger(totalResults))
+    throw new Error('Malformed iNaturalist grid response');
+  const retryAfter = [
+    ...snapshots.map((snapshot) => snapshot.retryAfterSec),
+    error?.retryAfterSec,
+  ].filter(Number.isFinite);
+  const stale = snapshots.some((snapshot) => snapshot.stale === true);
+  return {
+    cells,
+    totalResults,
+    fetchedAt: Math.min(...snapshots.map((snapshot) => snapshot.fetchedAt)),
+    stale,
+    ...(stale
+      ? {
+          upstreamStatus: Math.max(
+            0,
+            ...snapshots.map((snapshot) => snapshot.upstreamStatus || 0),
+          ),
+        }
+      : {}),
+    ...(error ? { error } : {}),
+    ...(retryAfter.length ? { retryAfterSec: Math.max(...retryAfter) } : {}),
+  };
+}
+
+/** Request both provider proxies when coverage calls for it. API-specific
+ * parameters (Cetacea, photo requirement, observation window) belong to the proxy. */
+export function createWildlifeSightingsSource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+} = {}) {
+  const gridCache = new Map();
+  const gridInFlight = new Map();
+  async function readProxy(url, provider, signal, { grid = false } = {}) {
+    signal?.throwIfAborted();
+    const response = await fetchImpl(url, { signal });
+    signal?.throwIfAborted();
+    const retryAfterSec = retryAfterSeconds(
+      response.headers?.get?.('Retry-After'),
+      now(),
+    );
+    const upstreamStatus =
+      Number(response.headers?.get?.('X-Upstream-Status')) || 0;
+    if (!response.ok) {
+      await response.body?.cancel?.();
+      signal?.throwIfAborted();
+      const error = new Error(
+        provider === 'iNaturalist' && upstreamStatus === 429
+          ? 'iNaturalist rate limited'
+          : `${provider} HTTP ${response.status}`,
+      );
+      error.status = response.status;
+      error.upstreamStatus = upstreamStatus;
+      if (retryAfterSec !== null) error.retryAfterSec = retryAfterSec;
+      throw error;
+    }
+    let payload;
+    try {
+      payload = await readResponseJsonCapped(
+        response,
+        SNAPSHOT_MAX_BYTES,
+        signal,
+      );
+    } catch (error) {
+      signal?.throwIfAborted();
+      throw new Error(`Malformed ${provider} response`, { cause: error });
+    }
+    signal?.throwIfAborted();
+    if (
+      payload &&
+      typeof payload === 'object' &&
+      (payload.stale === true ||
+        response.headers?.get?.('X-Data-Stale') === 'true')
+    ) {
+      payload.stale = true;
+      if (retryAfterSec !== null) payload.retryAfterSec = retryAfterSec;
+      payload.upstreamStatus = upstreamStatus;
+    }
+    if (grid) {
+      if (!wildlifeMeasure('tile-decode', () => validProjectedGrid(payload)))
+        throw new Error('Malformed iNaturalist grid response');
+      return payload;
+    }
+    const origin = provider === 'iNaturalist' ? 'inaturalist' : 'acartia';
+    if (
+      !validProjectedRows(payload?.rows, origin) ||
+      (origin === 'inaturalist' &&
+        (!Number.isSafeInteger(payload.totalResults) ||
+          payload.totalResults < 0))
+    ) {
+      throw new Error(`Malformed ${provider} response`);
+    }
+    return payload;
+  }
+
+  function readGridTile(key, url, metadata, signal) {
+    signal?.throwIfAborted();
+    let pending = gridInFlight.get(key);
+    if (!pending || pending.controller.signal.aborted) {
+      const controller = new AbortController();
+      pending = { controller, consumers: new Set(), promise: null };
+      const entry = pending;
+      pending.promise = readProxy(url, 'iNaturalist', controller.signal, {
+        grid: true,
+      })
+        .then((value) => {
+          gridCache.delete(key);
+          gridCache.set(key, {
+            value,
+            savedAt: value.stale ? Math.min(now(), value.fetchedAt) : now(),
+            ...metadata,
+          });
+          while (gridCache.size > WILDLIFE_GRID_CACHE_MAX)
+            gridCache.delete(gridCache.keys().next().value);
+          return value;
+        })
+        .finally(() => {
+          if (gridInFlight.get(key) === entry) gridInFlight.delete(key);
+        });
+      gridInFlight.set(key, pending);
+    }
+    const consumer = {};
+    pending.consumers.add(consumer);
+    return new Promise((resolve, reject) => {
+      const finish = (aborted = false) => {
+        signal?.removeEventListener('abort', abort);
+        pending.consumers.delete(consumer);
+        if (aborted && !pending.consumers.size) pending.controller.abort();
+      };
+      const abort = () => {
+        finish(true);
+        reject(signal.reason);
+      };
+      signal?.addEventListener('abort', abort, { once: true });
+      pending.promise.then(
+        (value) => {
+          finish();
+          resolve(value);
+        },
+        (error) => {
+          finish();
+          reject(error);
+        },
+      );
+    });
+  }
+
+  /** Publish cached tiles immediately and refresh their occupied cells. */
+  async function getGridSnapshot({
+    tiles,
+    confirmed = false,
+    taxa = 'all',
+    signal,
+    onTile,
+  } = {}) {
+    signal?.throwIfAborted();
+    if (
+      !Array.isArray(tiles) ||
+      !tiles.length ||
+      tiles.length > WILDLIFE_GRID_TILE_CAP ||
+      !tiles.every(validTile)
+    )
+      throw new TypeError('Wildlife grid requires visible tiles');
+    const preset = TAXA_PRESETS.some((item) => item.value === taxa)
+      ? taxa
+      : 'all';
+    const unique = [
+      ...new Map(
+        tiles.map((tile) => [`${tile.z}/${tile.x}/${tile.y}`, tile]),
+      ).values(),
+    ].sort((a, b) => a.z - b.z || a.x - b.x || a.y - b.y);
+    const windowKey = Math.floor(
+      (now() - (preset === 'whales' ? 168 : 48) * HOUR_MS) / HOUR_MS,
+    );
+    const snapshots = new Array(unique.length);
+    const failures = new Array(unique.length);
+    const usable = (entry) => {
+      const age = now() - entry.value.fetchedAt;
+      return age >= 0 && age <= GRID_STALE_MAX_MS;
+    };
+    const touch = (key, entry) => {
+      gridCache.delete(key);
+      gridCache.set(key, entry);
+    };
+    function cachedFallback(tile, tileKey) {
+      let exact = null;
+      const adjacent = [];
+      for (const [key, entry] of gridCache) {
+        if (!usable(entry)) continue;
+        if (key.startsWith(tileKey)) {
+          if (!exact || entry.savedAt > exact.savedAt) exact = entry;
+        } else if (
+          entry.preset === preset &&
+          entry.confirmed === confirmed &&
+          Math.abs(entry.tile.z - tile.z) === 1 &&
+          (entry.tile.z < tile.z
+            ? entry.tile.x === Math.floor(tile.x / 2) &&
+              entry.tile.y === Math.floor(tile.y / 2)
+            : Math.floor(entry.tile.x / 2) === tile.x &&
+              Math.floor(entry.tile.y / 2) === tile.y)
+        ) {
+          adjacent.push(entry);
+        }
+      }
+      if (exact) return { ...exact.value, stale: true };
+      if (!adjacent.length) return null;
+      // Preserve cached geographic centres and counts while exact tiles load.
+      const newest = [
+        ...new Map(
+          adjacent
+            .sort((a, b) => a.savedAt - b.savedAt)
+            .map((entry) => [
+              `${entry.tile.z}/${entry.tile.x}/${entry.tile.y}`,
+              entry,
+            ]),
+        ).values(),
+      ];
+      const parent = newest.find((entry) => entry.tile.z < tile.z);
+      const values = parent
+        ? [parent.value]
+        : newest.map((entry) => entry.value);
+      const value = combineWildlifeGridSnapshots(values);
+      value.cells = value.cells.filter((cell) =>
+        wildlifeGridCellId(cell.lat, cell.lon, tile.z)?.startsWith(
+          `grid:${tile.z}/${tile.x}/${tile.y}:`,
+        ),
+      );
+      value.totalResults = value.cells.reduce(
+        (sum, cell) => sum + cell.cellCount,
+        0,
+      );
+      return { ...value, stale: true };
+    }
+    function publish(index, value) {
+      signal?.throwIfAborted();
+      snapshots[index] = value;
+      onTile?.(value, { tile: unique[index] });
+    }
+    const requests = [];
+    // Publish all cached coverage before slow misses can occupy the workers.
+    for (let index = 0; index < unique.length; index += 1) {
+      const tile = unique[index];
+      const tileKey = `${tile.z}/${tile.x}/${tile.y}:${preset}:${confirmed ? 'research' : 'all'}:`;
+      const key = `${tileKey}${windowKey}`;
+      const cached = gridCache.get(key);
+      const age = cached ? now() - cached.savedAt : Infinity;
+      if (
+        age >= 0 &&
+        age < WILDLIFE_GRID_TTL_MS &&
+        !cached.value.stale &&
+        usable(cached)
+      ) {
+        touch(key, cached);
+        publish(index, cached.value);
+        continue;
+      }
+      const fallback = cachedFallback(tile, tileKey);
+      if (fallback) publish(index, fallback);
+      requests.push({ index, tile, key });
+    }
+    let cursor = 0;
+    async function worker() {
+      while (cursor < requests.length) {
+        signal?.throwIfAborted();
+        const { index, tile, key } = requests[cursor++];
+        const query = new URLSearchParams({
+          z: String(tile.z),
+          x: String(tile.x),
+          y: String(tile.y),
+          taxa: preset,
+        });
+        if (confirmed) query.set('quality', 'research');
+        try {
+          let value = await readGridTile(
+            key,
+            `/api/inaturalist/grid?${query}`,
+            { tile, preset, confirmed },
+            signal,
+          );
+          signal?.throwIfAborted();
+          publish(index, value);
+          if (value.stale && !value.upstreamStatus) {
+            // A server SWR response paints immediately. Join its existing
+            // refresh so this same view receives the new cells when ready.
+            query.set('refresh', 'wait');
+            value = await readGridTile(
+              key,
+              `/api/inaturalist/grid?${query}`,
+              { tile, preset, confirmed },
+              signal,
+            );
+            publish(index, value);
+          }
+        } catch (error) {
+          signal?.throwIfAborted();
+          failures[index] = error;
+          // Other tiles can already be cached or in flight. Keep their
+          // progressive coverage even if one upstream request fails.
+        }
+      }
+    }
+    await Promise.all(
+      Array.from(
+        { length: Math.min(WILDLIFE_GRID_CONCURRENCY, requests.length) },
+        worker,
+      ),
+    );
+    signal?.throwIfAborted();
+    const failure = failures.find(Boolean);
+    if (!snapshots.some(Boolean) && failure) throw failure;
+    return combineWildlifeGridSnapshots(snapshots.filter(Boolean), failure);
+  }
+
+  /** Merge recent provider rows with source availability and cache age. */
+  async function getSnapshotDetail({
+    signal,
+    box = null,
+    boxes = null,
+    scope = 'view',
+    confirmed = false,
+    taxa = 'all',
+  } = {}) {
+    signal?.throwIfAborted();
+    const preset = TAXA_PRESETS.some((item) => item.value === taxa)
+      ? taxa
+      : 'all';
+    const requestBoxes =
+      scope === 'global'
+        ? [null]
+        : Array.isArray(boxes)
+          ? boxes
+          : box
+            ? [box]
+            : [];
+    if (!requestBoxes.length)
+      throw new TypeError('Wildlife sightings require a view box');
+    const useAcartia =
+      scope !== 'global' &&
+      ['all', 'Mammalia', 'whales'].includes(preset) &&
+      requestBoxes.some((bounds) => boxIntersects(bounds, ACARTIA_GUARD_BOX));
+
+    const inatRequest = Promise.all(
+      requestBoxes.map((bounds) => {
+        const params = new URLSearchParams({
+          scope: scope === 'global' ? 'global' : 'view',
+          taxa: preset,
+        });
+        if (confirmed) params.set('quality', 'research');
+        if (scope !== 'global') {
+          for (const key of ['south', 'west', 'north', 'east'])
+            params.set(key, String(bounds[key]));
+        }
+        return readProxy(
+          `/api/inaturalist/observations?${params}`,
+          'iNaturalist',
+          signal,
+        );
+      }),
+    );
+    const acartiaRequest = useAcartia
+      ? readProxy('/api/acartia/sightings', 'Acartia', signal)
+      : Promise.resolve(null);
+    const [inatResult, acartiaResult] = await Promise.allSettled([
+      inatRequest,
+      acartiaRequest,
+    ]);
+    signal?.throwIfAborted();
+    if (inatResult.status === 'rejected') throw inatResult.reason;
+    const inatSnapshots = inatResult.value;
+    const inatRows = inatSnapshots.flatMap((snapshot) => snapshot.rows);
+    const acartiaSnapshot =
+      acartiaResult.status === 'fulfilled' ? acartiaResult.value : null;
+    const acartiaRows = acartiaSnapshot?.rows || [];
+    const rows = mergeSightings(inatRows, acartiaRows, {
+      nowMs: now(),
+      taxa: preset,
+      confirmed,
+    });
+    const inatDates = inatSnapshots
+      .map((snapshot) => snapshot.fetchedAt)
+      .filter(Number.isFinite);
+    const inatFetchedAt = inatDates.length ? Math.min(...inatDates) : null;
+    const inatStale = inatSnapshots.some((snapshot) => snapshot.stale === true);
+    const acartiaStale = acartiaSnapshot?.stale === true;
+    const drawnAcartia = rows.filter((row) => row.origin === 'acartia').length;
+    const dates = [
+      inatFetchedAt,
+      drawnAcartia ? acartiaSnapshot?.fetchedAt : null,
+    ].filter(Number.isFinite);
+    const retryAfter = [
+      ...inatSnapshots.map((snapshot) => snapshot.retryAfterSec),
+      drawnAcartia ? acartiaSnapshot?.retryAfterSec : null,
+    ].filter(Number.isFinite);
+    return {
+      rows,
+      stale: inatStale || (drawnAcartia > 0 && acartiaStale),
+      ...(inatStale || acartiaStale
+        ? {
+            upstreamStatus: Math.max(
+              0,
+              ...inatSnapshots.map((snapshot) => snapshot.upstreamStatus || 0),
+              acartiaSnapshot?.upstreamStatus || 0,
+            ),
+          }
+        : {}),
+      fetchedAt: dates.length ? Math.min(...dates) : null,
+      totalResults:
+        inatSnapshots.reduce(
+          (total, snapshot) => total + snapshot.totalResults,
+          0,
+        ) + drawnAcartia,
+      scope: scope === 'global' ? 'global' : 'view',
+      partial: inatSnapshots.some((snapshot) => snapshot.partial === true),
+      ...(retryAfter.length ? { retryAfterSec: Math.max(...retryAfter) } : {}),
+      sources: {
+        inaturalist: {
+          ok: true,
+          stale: inatStale,
+          fetchedAt: inatFetchedAt,
+          count: rows.filter((row) => row.origin === 'inaturalist').length,
+        },
+        acartia: {
+          ok: !useAcartia || acartiaResult.status === 'fulfilled',
+          stale: acartiaStale,
+          fetchedAt: Number.isFinite(acartiaSnapshot?.fetchedAt)
+            ? acartiaSnapshot.fetchedAt
+            : null,
+          count: drawnAcartia,
+        },
+      },
+    };
+  }
+
+  return {
+    /** Return recent, privacy-projected rows without source status metadata. */
+    async getSnapshot(options = {}) {
+      return (await getSnapshotDetail(options)).rows;
+    },
+    getSnapshotDetail,
+    getGridSnapshot,
+  };
+}
diff --git a/src/layers/wildlifeSightings/source.test.mjs b/src/layers/wildlifeSightings/source.test.mjs
new file mode 100644
index 000000000..7c1191e4b
--- /dev/null
+++ b/src/layers/wildlifeSightings/source.test.mjs
@@ -0,0 +1,816 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createWildlifeSightingsSource,
+  WILDLIFE_GRID_TTL_MS,
+} from './source.js';
+import { wildlifeGridCellId } from './gridViewport.js';
+
+const now = Date.UTC(2026, 10, 4, 18);
+const seattle = { south: 47.5, west: -122.5, north: 47.7, east: -122.2 };
+const outside = { south: 10, west: 10, north: 12, east: 12 };
+const inat = {
+  stableId: 'inat:123',
+  origin: 'inaturalist',
+  lat: 47.6,
+  lon: -122.3,
+  observedAt: now - 3_600_000,
+  observedOn: '2026-11-04',
+};
+const acartia = {
+  stableId: 'acartia:abc',
+  origin: 'acartia',
+  lat: 48.12,
+  lon: -122.54,
+  observedAt: now - 3_600_000,
+  cetacean: true,
+  quality: 'research',
+  provider: { name: 'Provider', entity: null },
+};
+const inatEnvelope = (extra = {}) => ({
+  fetchedAt: now,
+  rows: [inat],
+  scope: 'view',
+  totalResults: 1,
+  ...extra,
+});
+const acartiaEnvelope = (extra = {}) => ({
+  fetchedAt: now,
+  rows: [acartia],
+  ...extra,
+});
+
+test('construction performs no acquisition', () => {
+  createWildlifeSightingsSource({
+    fetchImpl: () => assert.fail('construction fetched'),
+  });
+});
+
+test('source sends proxy-only scope, box, taxa and confirmed parameters for all presets', async () => {
+  for (const taxa of [
+    'all',
+    'Aves',
+    'Mammalia',
+    'whales',
+    'Insecta',
+    'Plantae',
+  ]) {
+    const urls = [];
+    const source = createWildlifeSightingsSource({
+      now: () => now,
+      fetchImpl: async (url) => {
+        urls.push(new URL(url, 'https://example.test'));
+        return Response.json(inatEnvelope());
+      },
+    });
+    await source.getSnapshotDetail({ box: outside, taxa, confirmed: true });
+    assert.equal(urls.length, 1);
+    assert.equal(urls[0].pathname, '/api/inaturalist/observations');
+    assert.deepEqual(Object.fromEntries(urls[0].searchParams), {
+      scope: 'view',
+      taxa,
+      quality: 'research',
+      south: '10',
+      west: '10',
+      north: '12',
+      east: '12',
+    });
+    // taxon_id, d1 (observed date), photos and quality_grade are upstream
+    // choices owned and tested by the server, never browser query controls.
+  }
+});
+
+test('confirmed false omits quality, and global sample omits bbox and Acartia', async () => {
+  const urls = [];
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) => {
+      urls.push(url);
+      return Response.json(inatEnvelope({ scope: 'global' }));
+    },
+  });
+  const result = await source.getSnapshotDetail({
+    scope: 'global',
+    taxa: 'whales',
+    confirmed: false,
+    box: seattle,
+  });
+  assert.equal(result.scope, 'global');
+  assert.deepEqual(
+    Object.fromEntries(new URL(urls[0], 'https://example.test').searchParams),
+    { scope: 'global', taxa: 'whales' },
+  );
+  assert.equal(urls.length, 1);
+});
+
+test('Acartia loads only inside coverage for the three mammal-inclusive presets', async () => {
+  for (const box of [seattle, outside])
+    for (const taxa of [
+      'all',
+      'Aves',
+      'Mammalia',
+      'whales',
+      'Insecta',
+      'Plantae',
+    ]) {
+      const urls = [];
+      const source = createWildlifeSightingsSource({
+        now: () => now,
+        fetchImpl: async (url) => {
+          urls.push(url);
+          return Response.json(
+            url.startsWith('/api/acartia') ? acartiaEnvelope() : inatEnvelope(),
+          );
+        },
+      });
+      const result = await source.getSnapshotDetail({ box, taxa });
+      const expected =
+        box === seattle && ['all', 'Mammalia', 'whales'].includes(taxa);
+      assert.equal(
+        urls.some((url) => url === '/api/acartia/sightings'),
+        expected,
+      );
+      assert.equal(result.rows.length, expected ? 2 : 1);
+    }
+});
+
+test('Acartia failure preserves iNat rows with an explicit failed source', async () => {
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) =>
+      url.startsWith('/api/acartia')
+        ? new Response('', { status: 502 })
+        : Response.json(inatEnvelope()),
+  });
+  const result = await source.getSnapshotDetail({ box: seattle });
+  assert.deepEqual(result.rows, [inat]);
+  assert.equal(result.sources.acartia.ok, false);
+  assert.equal(result.sources.inaturalist.ok, true);
+});
+
+test('proxy staleness and original fetch dates pass through with per-source counts', async () => {
+  const fetchedAt = now - 50 * 60_000;
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) =>
+      Response.json(
+        url.startsWith('/api/acartia')
+          ? acartiaEnvelope()
+          : inatEnvelope({
+              fetchedAt,
+              stale: true,
+              partial: true,
+              totalResults: 400,
+            }),
+      ),
+  });
+  const result = await source.getSnapshotDetail({ box: seattle });
+  assert.equal(result.stale, true);
+  assert.equal(result.fetchedAt, fetchedAt);
+  assert.equal(result.partial, true);
+  assert.equal(result.totalResults, 401);
+  assert.deepEqual(result.sources.inaturalist, {
+    ok: true,
+    stale: true,
+    fetchedAt,
+    count: 1,
+  });
+  assert.equal(result.sources.acartia.count, 1);
+});
+
+test('antimeridian boxes fetch once each and merge duplicate boundary rows', async () => {
+  const urls = [];
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) => {
+      urls.push(url);
+      return Response.json(inatEnvelope());
+    },
+  });
+  const boxes = [
+    { south: 10, west: 179, north: 12, east: 180 },
+    { south: 10, west: -180, north: 12, east: -178 },
+  ];
+  const result = await source.getSnapshotDetail({ boxes });
+  assert.equal(urls.length, 2);
+  assert.equal(result.rows.length, 1);
+  assert.equal(result.totalResults, 2);
+});
+
+test('iNat non-OK responses carry stable status messages and status values', async () => {
+  for (const status of [429, 502]) {
+    const source = createWildlifeSightingsSource({
+      fetchImpl: async () =>
+        new Response('', {
+          status,
+          headers: { 'X-Upstream-Status': String(status) },
+        }),
+    });
+    await assert.rejects(source.getSnapshot({ box: outside }), (error) => {
+      assert.equal(
+        error.message,
+        status === 429 ? 'iNaturalist rate limited' : 'iNaturalist HTTP 502',
+      );
+      assert.equal(error.status, status);
+      return true;
+    });
+  }
+});
+
+test('Retry-After delta seconds and HTTP dates use the injected source clock', async () => {
+  for (const [header, seconds] of [
+    ['3600', 3600],
+    [new Date(now + 12 * 3_600_000).toUTCString(), 43_200],
+    [new Date(now - 1000).toUTCString(), 0],
+    ['0', 0],
+    ['not a deadline', undefined],
+    ['-10', undefined],
+    ['', undefined],
+  ]) {
+    const source = createWildlifeSightingsSource({
+      now: () => now,
+      fetchImpl: async () =>
+        new Response('', {
+          status: 429,
+          headers: { 'Retry-After': header },
+        }),
+    });
+    await assert.rejects(source.getSnapshot({ box: outside }), (error) => {
+      assert.equal(error.status, 429);
+      assert.equal(error.retryAfterSec, seconds, header);
+      return true;
+    });
+  }
+});
+
+test('malformed envelopes and invalid rows reject instead of becoming empty', async () => {
+  for (const payload of [
+    {},
+    { rows: {} },
+    { rows: [], totalResults: null },
+    { rows: [{}], totalResults: 1 },
+    { results: [], total_results: 0 },
+  ]) {
+    const source = createWildlifeSightingsSource({
+      fetchImpl: async () => Response.json(payload),
+    });
+    await assert.rejects(
+      source.getSnapshot({ box: outside }),
+      /Malformed iNaturalist response/,
+    );
+  }
+  const source = createWildlifeSightingsSource({
+    fetchImpl: async () => new Response('{bad'),
+  });
+  await assert.rejects(
+    source.getSnapshot({ box: outside }),
+    /Malformed iNaturalist response/,
+  );
+});
+
+test('well-formed empty projected snapshot is legitimate and getSnapshot returns only rows', async () => {
+  const source = createWildlifeSightingsSource({
+    fetchImpl: async () =>
+      Response.json(inatEnvelope({ rows: [], totalResults: 0 })),
+  });
+  assert.deepEqual(await source.getSnapshot({ box: outside }), []);
+});
+
+test('abort is checked before acquisition and after a late fetch resolves', async () => {
+  const early = new AbortController();
+  early.abort();
+  const idle = createWildlifeSightingsSource({
+    fetchImpl: () => assert.fail('aborted fetch ran'),
+  });
+  await assert.rejects(
+    idle.getSnapshot({ box: outside, signal: early.signal }),
+    { name: 'AbortError' },
+  );
+  let resolve;
+  const source = createWildlifeSightingsSource({
+    fetchImpl: () =>
+      new Promise((done) => {
+        resolve = done;
+      }),
+  });
+  const late = new AbortController();
+  const request = source.getSnapshot({ box: outside, signal: late.signal });
+  late.abort();
+  resolve(Response.json(inatEnvelope()));
+  await assert.rejects(request, { name: 'AbortError' });
+});
+
+const gridCell = {
+  id: 'grid:2/1/1:1:51',
+  cellCount: 6,
+  lat: 65.94,
+  lon: -18.28125,
+};
+const gridEnvelope = (extra = {}) => ({
+  cells: [gridCell],
+  totalResults: 6,
+  fetchedAt: now,
+  ...extra,
+});
+const gridTile = { z: 2, x: 1, y: 1 };
+
+test('grid source sends visible XYZ/filter parameters only, dedupes tiles and keeps source untouched', async () => {
+  const urls = [];
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url, options) => {
+      urls.push(new URL(url, 'https://example.test'));
+      assert.ok(options.signal instanceof AbortSignal);
+      return Response.json(gridEnvelope());
+    },
+  });
+  const result = await source.getGridSnapshot({
+    tiles: [gridTile, gridTile],
+    confirmed: true,
+    taxa: 'Aves',
+  });
+  assert.equal(urls.length, 1);
+  assert.equal(urls[0].pathname, '/api/inaturalist/grid');
+  assert.deepEqual(Object.fromEntries(urls[0].searchParams), {
+    z: '2',
+    x: '1',
+    y: '1',
+    taxa: 'Aves',
+    quality: 'research',
+  });
+  assert.deepEqual(result, {
+    cells: [gridCell],
+    totalResults: 6,
+    fetchedAt: now,
+    stale: false,
+  });
+});
+
+test('grid source caches stable tile/filter/hour keys and combines neighbor edge cells once', async () => {
+  let clock = now;
+  let calls = 0;
+  const source = createWildlifeSightingsSource({
+    now: () => clock,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(gridEnvelope());
+    },
+  });
+  const options = { tiles: [gridTile, { z: 2, x: 2, y: 1 }] };
+  const result = await source.getGridSnapshot(options);
+  assert.equal(calls, 2);
+  assert.equal(
+    result.cells.length,
+    1,
+    'same geographic cell can bleed into a neighboring hit tile',
+  );
+  assert.equal(result.totalResults, 6);
+  await source.getGridSnapshot({ tiles: [...options.tiles].reverse() });
+  assert.equal(calls, 2, 'ordering does not change stable keys');
+  await source.getGridSnapshot({ ...options, confirmed: true });
+  assert.equal(calls, 4, 'quality changes the key');
+  clock += WILDLIFE_GRID_TTL_MS + 1;
+  await source.getGridSnapshot(options);
+  assert.equal(calls, 6, 'fifteen minute refresh cap');
+});
+
+test('grid source preserves stale metadata and rejects invalid projected schema/privacy fields', async () => {
+  const staleSource = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async () =>
+      Response.json(gridEnvelope({ stale: true, fetchedAt: now - 1000 })),
+  });
+  const stale = await staleSource.getGridSnapshot({ tiles: [gridTile] });
+  assert.equal(stale.stale, true);
+  assert.equal(stale.fetchedAt, now - 1000);
+  for (const payload of [
+    {},
+    gridEnvelope({ cells: {} }),
+    gridEnvelope({ totalResults: -1 }),
+    gridEnvelope({ totalResults: 5 }),
+    gridEnvelope({ fetchedAt: null }),
+    gridEnvelope({ cells: [{ ...gridCell, uuid: 'must-not-leave-proxy' }] }),
+    gridEnvelope({ cells: [{ ...gridCell, iconic: 'Aves' }] }),
+    gridEnvelope({ cells: [{ ...gridCell, lat: 91 }] }),
+    gridEnvelope({ cells: [{ ...gridCell, id: 'grid:99/0/0:1:1' }] }),
+    gridEnvelope({ cells: [{ ...gridCell, id: 'grid:2/1/1:3:51' }] }),
+    gridEnvelope({ cells: [gridCell, gridCell], totalResults: 12 }),
+  ]) {
+    const source = createWildlifeSightingsSource({
+      fetchImpl: async () => Response.json(payload),
+    });
+    await assert.rejects(
+      source.getGridSnapshot({ tiles: [gridTile] }),
+      /Malformed iNaturalist grid response/,
+    );
+  }
+});
+
+test('grid source validates request bounds before fetching and aborts superseded loads', async () => {
+  const idle = createWildlifeSightingsSource({
+    fetchImpl: () => assert.fail('invalid/aborted grid acquired'),
+  });
+  for (const tiles of [
+    undefined,
+    [],
+    [{ z: 2, x: 4, y: 0 }],
+    [{ z: -1, x: 0, y: 0 }],
+    Array(13).fill(gridTile),
+  ]) {
+    await assert.rejects(
+      idle.getGridSnapshot({ tiles }),
+      /requires visible tiles/,
+    );
+  }
+  const early = new AbortController();
+  early.abort();
+  await assert.rejects(
+    idle.getGridSnapshot({ tiles: [gridTile], signal: early.signal }),
+    { name: 'AbortError' },
+  );
+  let resolve;
+  let passedSignal;
+  const source = createWildlifeSightingsSource({
+    fetchImpl: (_url, options) => {
+      passedSignal = options.signal;
+      return new Promise((done) => {
+        resolve = done;
+      });
+    },
+  });
+  const late = new AbortController();
+  const loading = source.getGridSnapshot({
+    tiles: [gridTile],
+    signal: late.signal,
+  });
+  late.abort();
+  assert.equal(passedSignal.aborted, true);
+  resolve(Response.json(gridEnvelope()));
+  await assert.rejects(loading, { name: 'AbortError' });
+});
+
+test('grid worker concurrency is bounded and a failed tile preserves progressive siblings', async () => {
+  const waiting = [];
+  const source = createWildlifeSightingsSource({
+    fetchImpl: (_url, options) =>
+      new Promise((resolve, reject) => {
+        waiting.push({ resolve, signal: options.signal });
+        options.signal.addEventListener(
+          'abort',
+          () => reject(options.signal.reason),
+          { once: true },
+        );
+      }),
+  });
+  const tiles = Array.from({ length: 6 }, (_, x) => ({ z: 3, x, y: 0 }));
+  const loading = source.getGridSnapshot({ tiles });
+  assert.equal(waiting.length, 4);
+  waiting[0].resolve(new Response('', { status: 502 }));
+  await new Promise((resolve) => setImmediate(resolve));
+  for (let i = 1; i < 4; i++) waiting[i].resolve(Response.json(gridEnvelope()));
+  await new Promise((resolve) => setImmediate(resolve));
+  for (let i = 4; i < waiting.length; i++)
+    waiting[i].resolve(Response.json(gridEnvelope()));
+  const result = await loading;
+  assert.equal(result.error.message, 'iNaturalist HTTP 502');
+  assert.deepEqual(result.cells, [gridCell]);
+  assert.ok(waiting.every((item) => !item.signal.aborted));
+});
+
+test('failed grid refresh keeps the tile last good cells across its window-hour key, without extending stale life', async () => {
+  let clock = now + 55 * 60_000;
+  let fail = false;
+  let calls = 0;
+  const source = createWildlifeSightingsSource({
+    now: () => clock,
+    fetchImpl: async () => {
+      calls++;
+      return fail
+        ? new Response('', { status: 502, headers: { 'Retry-After': '40' } })
+        : Response.json(gridEnvelope({ fetchedAt: clock }));
+    },
+  });
+  const good = await source.getGridSnapshot({
+    tiles: [gridTile],
+    taxa: 'whales',
+  });
+  const fetchedAt = clock;
+  fail = true;
+  clock += 300_001;
+  const stale = await source.getGridSnapshot({
+    tiles: [gridTile],
+    taxa: 'whales',
+  });
+  assert.deepEqual(stale.cells, good.cells);
+  assert.equal(stale.totalResults, good.totalResults);
+  assert.equal(stale.stale, true);
+  assert.equal(stale.fetchedAt, fetchedAt);
+  assert.equal(stale.error.message, 'iNaturalist HTTP 502');
+  assert.equal(stale.retryAfterSec, 40);
+  assert.equal(calls, 2);
+  await assert.rejects(
+    source.getGridSnapshot({ tiles: [gridTile], taxa: 'Aves' }),
+    /iNaturalist HTTP 502/,
+    'a different filter cannot borrow the last tile',
+  );
+  clock = fetchedAt + 3_600_001;
+  await assert.rejects(
+    source.getGridSnapshot({ tiles: [gridTile], taxa: 'whales' }),
+    /iNaturalist HTTP 502/,
+    'failed refresh did not renew original data age',
+  );
+});
+
+test('a rejected grid request never rejects a parallel observations acquisition', async () => {
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) =>
+      url.startsWith('/api/inaturalist/grid?')
+        ? new Response('', { status: 502 })
+        : Response.json(inatEnvelope()),
+  });
+  const [grid, observations] = await Promise.allSettled([
+    source.getGridSnapshot({ tiles: [gridTile] }),
+    source.getSnapshotDetail({ box: outside }),
+  ]);
+  assert.equal(grid.status, 'rejected');
+  assert.equal(grid.reason.status, 502);
+  assert.equal(observations.status, 'fulfilled');
+  assert.deepEqual(observations.value.rows, [inat]);
+});
+
+test('one failed cached tile retains its cells while neighboring tiles refresh successfully', async () => {
+  let clock = now;
+  let refreshing = false;
+  const neighbor = {
+    ...gridCell,
+    id: wildlifeGridCellId(30, 20, 2),
+    lat: 30,
+    lon: 20,
+  };
+  const signals = [];
+  const source = createWildlifeSightingsSource({
+    now: () => clock,
+    fetchImpl: async (url, { signal }) => {
+      signals.push(signal);
+      const isFailedTile =
+        new URL(url, 'https://example.test').searchParams.get('x') === '1';
+      if (refreshing && isFailedTile) return new Response('', { status: 502 });
+      const cell = isFailedTile
+        ? gridCell
+        : { ...neighbor, cellCount: refreshing ? 10 : 6 };
+      return Response.json({
+        cells: [cell],
+        totalResults: cell.cellCount,
+        fetchedAt: clock,
+      });
+    },
+  });
+  const options = { tiles: [gridTile, { z: 2, x: 2, y: 1 }] };
+  await source.getGridSnapshot(options);
+  refreshing = true;
+  clock += WILDLIFE_GRID_TTL_MS + 1;
+  const result = await source.getGridSnapshot(options);
+  assert.equal(result.cells.length, 2);
+  assert.equal(
+    result.cells.find((cell) => cell.id === gridCell.id).cellCount,
+    6,
+  );
+  assert.equal(
+    result.cells.find((cell) => cell.id === neighbor.id).cellCount,
+    10,
+  );
+  assert.equal(result.totalResults, 16);
+  assert.equal(result.stale, true);
+  assert.equal(result.error.message, 'iNaturalist HTTP 502');
+  assert.ok(signals.every((signal) => !signal.aborted));
+});
+
+test('stale successful proxy answers preserve Retry-After for observation and grid retry guidance', async () => {
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) =>
+      Response.json(
+        url.startsWith('/api/inaturalist/grid?')
+          ? gridEnvelope({ stale: true })
+          : inatEnvelope({ stale: true }),
+        { headers: { 'X-Data-Stale': 'true', 'Retry-After': '75' } },
+      ),
+  });
+  const rows = await source.getSnapshotDetail({ box: outside });
+  const grid = await source.getGridSnapshot({ tiles: [gridTile] });
+  assert.equal(rows.stale, true);
+  assert.equal(rows.retryAfterSec, 75);
+  assert.equal(grid.stale, true);
+  assert.equal(grid.retryAfterSec, 75);
+});
+
+test('client stale tiles publish before revalidation finishes and retain the original data date', async () => {
+  let clock = now;
+  let refresh;
+  let calls = 0;
+  const source = createWildlifeSightingsSource({
+    now: () => clock,
+    fetchImpl: () =>
+      ++calls === 1
+        ? Promise.resolve(Response.json(gridEnvelope()))
+        : new Promise((resolve) => {
+            refresh = resolve;
+          }),
+  });
+  await source.getGridSnapshot({ tiles: [gridTile] });
+  clock += WILDLIFE_GRID_TTL_MS + 1;
+  const paints = [];
+  const pending = source.getGridSnapshot({
+    tiles: [gridTile],
+    onTile: (tile) => paints.push(tile),
+  });
+  assert.equal(
+    paints.length,
+    1,
+    'stale cache is synchronous, before the fetch settles',
+  );
+  assert.equal(paints[0].stale, true);
+  assert.equal(paints[0].fetchedAt, now);
+  refresh(
+    Response.json(
+      gridEnvelope({
+        cells: [{ ...gridCell, cellCount: 9 }],
+        totalResults: 9,
+        fetchedAt: clock,
+      }),
+    ),
+  );
+  const result = await pending;
+  assert.equal(paints.length, 2);
+  assert.equal(paints[1].stale, undefined);
+  assert.equal(result.totalResults, 9);
+});
+
+test('cached coverage publishes before slow misses earlier in XYZ order fill all workers', async () => {
+  const waiting = [];
+  let cold = false;
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: (url) => {
+      const x = Number(
+        new URL(url, 'https://example.test').searchParams.get('x'),
+      );
+      const cell = {
+        id: wildlifeGridCellId(83, x * 45 - 157.5, 3),
+        lat: 83,
+        lon: x * 45 - 157.5,
+        cellCount: 6,
+      };
+      const value = { cells: [cell], totalResults: 6, fetchedAt: now };
+      return cold
+        ? new Promise((resolve) =>
+            waiting.push(() => resolve(Response.json(value))),
+          )
+        : Promise.resolve(Response.json(value));
+    },
+  });
+  const tiles = Array.from({ length: 6 }, (_, x) => ({ z: 3, x, y: 0 }));
+  await source.getGridSnapshot({ tiles: tiles.slice(4) });
+  cold = true;
+  const paints = [];
+  const pending = source.getGridSnapshot({
+    tiles,
+    onTile: (value, metadata) => paints.push({ value, metadata }),
+  });
+  assert.deepEqual(
+    paints.map(({ metadata }) => metadata.tile.x),
+    [4, 5],
+    'known cells paint synchronously even though the four earlier misses are unresolved',
+  );
+  assert.equal(waiting.length, 4);
+  for (const finish of waiting) finish();
+  const result = await pending;
+  assert.equal(result.cells.length, 6);
+  assert.equal(result.totalResults, 36);
+});
+
+test('an adjacent zoom cache fills the new tile immediately while its exact cells load', async () => {
+  let resolve;
+  let calls = 0;
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: () =>
+      ++calls === 1
+        ? Promise.resolve(Response.json(gridEnvelope()))
+        : new Promise((done) => {
+            resolve = done;
+          }),
+  });
+  await source.getGridSnapshot({ tiles: [gridTile] });
+  const parent = { z: 1, x: 0, y: 0 };
+  const paints = [];
+  const pending = source.getGridSnapshot({
+    tiles: [parent],
+    onTile: (value) => paints.push(value),
+  });
+  assert.equal(paints.length, 1);
+  assert.deepEqual(paints[0].cells, [gridCell]);
+  assert.equal(calls, 2, 'the exact zoom still loads in the background');
+  const cell = {
+    ...gridCell,
+    id: wildlifeGridCellId(gridCell.lat, gridCell.lon, 1),
+  };
+  resolve(Response.json(gridEnvelope({ cells: [cell] })));
+  await pending;
+  assert.equal(paints.length, 2);
+  assert.deepEqual(paints[1].cells, [cell]);
+});
+
+test('concurrent client views share an in-flight tile without one consumer aborting the other', async () => {
+  let resolve;
+  let calls = 0;
+  let signal;
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: (_url, options) => {
+      calls++;
+      signal = options.signal;
+      return new Promise((done) => {
+        resolve = done;
+      });
+    },
+  });
+  const first = new AbortController();
+  const one = source.getGridSnapshot({
+    tiles: [gridTile],
+    signal: first.signal,
+  });
+  const two = source.getGridSnapshot({ tiles: [gridTile] });
+  first.abort();
+  await assert.rejects(one, { name: 'AbortError' });
+  assert.equal(signal.aborted, false);
+  resolve(Response.json(gridEnvelope()));
+  assert.equal((await two).totalResults, 6);
+  assert.equal(calls, 1);
+  await source.getGridSnapshot({ tiles: [gridTile] });
+  assert.equal(calls, 1);
+});
+
+test('local HTTP pacing errors never become iNaturalist rate-limited errors', async () => {
+  for (const status of [429, 503]) {
+    const source = createWildlifeSightingsSource({
+      fetchImpl: async () =>
+        new Response('', { status, headers: { 'Retry-After': '30' } }),
+    });
+    await assert.rejects(
+      source.getSnapshotDetail({ box: outside }),
+      (error) => {
+        assert.equal(error.upstreamStatus, 0);
+        assert.doesNotMatch(error.message, /rate limited/i);
+        return true;
+      },
+    );
+  }
+});
+
+test('a server stale-while-revalidate answer joins its refresh and publishes fresh cells in the same view', async () => {
+  const urls = [];
+  let resolve;
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: (url) => {
+      urls.push(url);
+      return urls.length === 1
+        ? Promise.resolve(
+            Response.json(
+              gridEnvelope({
+                stale: true,
+                fetchedAt: now - WILDLIFE_GRID_TTL_MS - 1,
+              }),
+            ),
+          )
+        : new Promise((done) => {
+            resolve = done;
+          });
+    },
+  });
+  const paints = [];
+  const pending = source.getGridSnapshot({
+    tiles: [gridTile],
+    onTile: (value) => paints.push(value),
+  });
+  await new Promise((done) => setImmediate(done));
+  assert.equal(paints.length, 1);
+  assert.equal(paints[0].stale, true);
+  assert.equal(
+    new URL(urls[1], 'https://example.test').searchParams.get('refresh'),
+    'wait',
+  );
+  resolve(
+    Response.json(
+      gridEnvelope({
+        cells: [{ ...gridCell, cellCount: 11 }],
+        totalResults: 11,
+      }),
+    ),
+  );
+  assert.equal((await pending).totalResults, 11);
+  assert.equal(paints.length, 2);
+  assert.equal(paints[1].stale, undefined);
+});
diff --git a/src/layers/wildlifeSightings/sprites.js b/src/layers/wildlifeSightings/sprites.js
new file mode 100644
index 000000000..94f963b05
--- /dev/null
+++ b/src/layers/wildlifeSightings/sprites.js
@@ -0,0 +1,136 @@
+import { ICONIC_TINTS, WILDLIFE_SPRITE_PX } from './policy.js';
+
+// Missing taxon symbols use related shapes from Material Symbols Outlined.
+export const WILDLIFE_BADGE_GLYPHS = Object.freeze({
+  bird: 'raven',
+  mammal: 'pets',
+  reptile: 'egg_alt',
+  amphibian: 'water_drop',
+  fish: 'set_meal',
+  insect: 'bug_report',
+  arachnid: 'pest_control',
+  plant: 'eco',
+  fungus: 'umbrella',
+  other: 'category',
+  unknown: 'question_mark',
+});
+export const WILDLIFE_SPRITE_GROUPS = Object.freeze(
+  Object.keys(WILDLIFE_BADGE_GLYPHS),
+);
+export const WILDLIFE_SPRITE_ICONIC = Object.freeze({
+  bird: 'Aves',
+  mammal: 'Mammalia',
+  reptile: 'Reptilia',
+  amphibian: 'Amphibia',
+  fish: 'Actinopterygii',
+  insect: 'Insecta',
+  arachnid: 'Arachnida',
+  plant: 'Plantae',
+  fungus: 'Fungi',
+  other: 'Animalia',
+  unknown: 'Unknown',
+});
+const ICONIC_GROUPS = Object.freeze(
+  Object.fromEntries(
+    Object.entries(WILDLIFE_SPRITE_ICONIC).map(([group, iconic]) => [
+      iconic,
+      group,
+    ]),
+  ),
+);
+
+/** Resolve a taxon or sprite group to one of the shared badge textures. */
+export function wildlifeSpriteGroup(groupOrIconic) {
+  if (groupOrIconic === 'Mollusca') return 'other';
+  return Object.hasOwn(WILDLIFE_SPRITE_ICONIC, groupOrIconic)
+    ? groupOrIconic
+    : Object.hasOwn(ICONIC_GROUPS, groupOrIconic)
+      ? ICONIC_GROUPS[groupOrIconic]
+      : 'unknown';
+}
+
+export const WILDLIFE_BADGE_OUTLINE_PX = 1.5;
+const OUTLINE_COLOR = '#040c10';
+const FONT = '400 14px "Material Symbols Outlined"';
+const FONT_GLYPHS = Object.values(WILDLIFE_BADGE_GLYPHS).join(' ');
+const FALLBACKS = new Map(
+  WILDLIFE_SPRITE_GROUPS.map((group) => [
+    group,
+    `data:image/svg+xml,${encodeURIComponent(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 20 20"><circle cx="10" cy="10" r="9.1" fill="${ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]}" stroke="${OUTLINE_COLOR}" stroke-width="${WILDLIFE_BADGE_OUTLINE_PX}"/></svg>`,
+    )}`,
+  ]),
+);
+
+/** One bounded set of canvas sprites per document, painted only after the
+ * icon font is decoded. Until then the very same billboards use plain badges. */
+export function createWildlifeSpriteCache({
+  documentRef = globalThis.document,
+} = {}) {
+  const sprites = new Map();
+  const listeners = new Set();
+  let ready = false;
+  let loading = null;
+
+  function paint(group) {
+    const canvas = documentRef.createElement('canvas');
+    canvas.width = canvas.height = WILDLIFE_SPRITE_PX * 2;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return FALLBACKS.get(group);
+    ctx.scale(2, 2);
+    ctx.beginPath();
+    ctx.arc(10, 10, 9.1, 0, Math.PI * 2);
+    ctx.fillStyle = ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]];
+    ctx.fill();
+    ctx.lineWidth = WILDLIFE_BADGE_OUTLINE_PX;
+    ctx.strokeStyle = OUTLINE_COLOR;
+    ctx.stroke();
+    ctx.font = FONT;
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillStyle = '#ffffff';
+    ctx.fillText(WILDLIFE_BADGE_GLYPHS[group], 10, 10, 16);
+    return canvas;
+  }
+
+  function load() {
+    if (loading) return loading;
+    if (!documentRef?.fonts?.load) return Promise.resolve(false);
+    loading = Promise.resolve()
+      .then(() => documentRef.fonts.load(FONT, FONT_GLYPHS))
+      .then((faces) => {
+        if (!faces?.length) return false;
+        // Paint once per group, never once per observation or refresh.
+        for (const group of WILDLIFE_SPRITE_GROUPS)
+          sprites.set(group, paint(group));
+        ready = true;
+        for (const listener of [...listeners]) listener();
+        return true;
+      })
+      .catch(() => false);
+    return loading;
+  }
+
+  return {
+    get(groupOrIconic) {
+      const group = wildlifeSpriteGroup(groupOrIconic);
+      return (ready ? sprites : FALLBACKS).get(group);
+    },
+    load,
+    subscribe(listener) {
+      listeners.add(listener);
+      void load();
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+const caches = new WeakMap();
+let headlessCache;
+/** Share the bounded sprite cache among layer instances in one document. */
+export function wildlifeSpriteCache(documentRef = globalThis.document) {
+  if (!documentRef) return (headlessCache ??= createWildlifeSpriteCache());
+  if (!caches.has(documentRef))
+    caches.set(documentRef, createWildlifeSpriteCache({ documentRef }));
+  return caches.get(documentRef);
+}
diff --git a/src/layers/wildlifeSightings/sprites.test.mjs b/src/layers/wildlifeSightings/sprites.test.mjs
new file mode 100644
index 000000000..ae82b7f96
--- /dev/null
+++ b/src/layers/wildlifeSightings/sprites.test.mjs
@@ -0,0 +1,189 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import sharp from 'sharp';
+import { aircraftIcon } from '../../data/aircraftIcons.js';
+import { ICONIC_TINTS, WILDLIFE_SPRITE_PX } from './policy.js';
+import {
+  WILDLIFE_SPRITE_GROUPS,
+  WILDLIFE_SPRITE_ICONIC,
+  WILDLIFE_BADGE_GLYPHS,
+  WILDLIFE_BADGE_OUTLINE_PX,
+  createWildlifeSpriteCache,
+  wildlifeSpriteCache,
+  wildlifeSpriteGroup,
+} from './sprites.js';
+
+const sprites = wildlifeSpriteCache();
+
+test('every taxon group has an explicit Material Symbol and tinted circle fallback', () => {
+  assert.equal(Object.isFrozen(WILDLIFE_BADGE_GLYPHS), true);
+  assert.deepEqual(WILDLIFE_BADGE_GLYPHS, {
+    bird: 'raven',
+    mammal: 'pets',
+    reptile: 'egg_alt',
+    amphibian: 'water_drop',
+    fish: 'set_meal',
+    insect: 'bug_report',
+    arachnid: 'pest_control',
+    plant: 'eco',
+    fungus: 'umbrella',
+    other: 'category',
+    unknown: 'question_mark',
+  });
+  const textures = new Set();
+  for (const group of WILDLIFE_SPRITE_GROUPS) {
+    const texture = sprites.get(group);
+    textures.add(texture);
+    assert.equal(wildlifeSpriteGroup(WILDLIFE_SPRITE_ICONIC[group]), group);
+    assert.equal(sprites.get(WILDLIFE_SPRITE_ICONIC[group]), texture);
+    assert.equal(sprites.get(group), texture);
+    const svg = decodeURIComponent(texture.slice(texture.indexOf(',') + 1));
+    assert.match(svg, /<circle /);
+    assert.ok(
+      svg.includes(`fill="${ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]}"`),
+    );
+    assert.match(svg, /stroke="#040c10"/);
+    assert.match(svg, /stroke-width="1.5"/);
+    assert.doesNotMatch(svg, /<path|<text|<image|href=|<script|<foreignObject/);
+  }
+  assert.equal(textures.size, Object.keys(ICONIC_TINTS).length);
+});
+
+test('unknown taxon keys share the slate fallback without allocating textures', () => {
+  for (const value of [
+    undefined,
+    null,
+    'Unknown',
+    'Synthetic kingdom',
+    '__proto__',
+    'constructor',
+    'toString',
+  ]) {
+    assert.equal(wildlifeSpriteGroup(value), 'unknown');
+    assert.equal(sprites.get(value), sprites.get('unknown'));
+  }
+  assert.equal(sprites.get('Mollusca'), sprites.get('other'));
+});
+
+test('canvas badges wait for the icon font, paint once and notify existing consumers', async () => {
+  let resolveFont;
+  let fontLoads = 0;
+  const canvases = [];
+  const documentRef = {
+    fonts: {
+      load(font, glyphs) {
+        fontLoads += 1;
+        assert.match(font, /Material Symbols Outlined/);
+        for (const glyph of Object.values(WILDLIFE_BADGE_GLYPHS))
+          assert.ok(glyphs.includes(glyph));
+        return new Promise((resolve) => {
+          resolveFont = resolve;
+        });
+      },
+    },
+    createElement(tag) {
+      assert.equal(tag, 'canvas');
+      const commands = [];
+      const ctx = {
+        scale(...args) {
+          commands.push(['scale', ...args]);
+        },
+        beginPath() {},
+        arc(...args) {
+          commands.push(['arc', ...args]);
+        },
+        fill() {
+          commands.push(['fill', this.fillStyle]);
+        },
+        stroke() {
+          commands.push(['stroke', this.strokeStyle, this.lineWidth]);
+        },
+        fillText(...args) {
+          commands.push(['text', this.fillStyle, this.font, ...args]);
+        },
+      };
+      const canvas = { commands, getContext: () => ctx };
+      canvases.push(canvas);
+      return canvas;
+    },
+  };
+  const cache = createWildlifeSpriteCache({ documentRef });
+  const fallback = cache.get('Aves');
+  let notifications = 0;
+  const unsubscribe = cache.subscribe(() => {
+    notifications += 1;
+  });
+  const loading = cache.load();
+  assert.equal(cache.load(), loading);
+  await Promise.resolve();
+  assert.equal(fontLoads, 1);
+  assert.equal(canvases.length, 0, 'no glyph is rasterized in a fallback font');
+  assert.equal(cache.get('Aves'), fallback);
+  resolveFont([{}]);
+  assert.equal(await loading, true);
+  assert.equal(notifications, 1);
+  assert.equal(canvases.length, WILDLIFE_SPRITE_GROUPS.length);
+  for (const group of WILDLIFE_SPRITE_GROUPS) {
+    const canvas = cache.get(group);
+    assert.equal(canvas, cache.get(WILDLIFE_SPRITE_ICONIC[group]));
+    assert.equal(canvas.width, WILDLIFE_SPRITE_PX * 2);
+    assert.equal(canvas.height, WILDLIFE_SPRITE_PX * 2);
+    assert.deepEqual(
+      canvas.commands.find(([op]) => op === 'fill'),
+      ['fill', ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]],
+    );
+    assert.deepEqual(
+      canvas.commands.find(([op]) => op === 'stroke'),
+      ['stroke', '#040c10', WILDLIFE_BADGE_OUTLINE_PX],
+    );
+    const glyph = canvas.commands.find(([op]) => op === 'text');
+    assert.equal(glyph[1], '#ffffff');
+    assert.match(glyph[2], /Material Symbols Outlined/);
+    assert.equal(glyph[3], WILDLIFE_BADGE_GLYPHS[group]);
+  }
+  await cache.load();
+  assert.equal(canvases.length, WILDLIFE_SPRITE_GROUPS.length);
+  unsubscribe();
+});
+
+test('unavailable font keeps plain badges and does not paint a ligature word', async () => {
+  const cache = createWildlifeSpriteCache({
+    documentRef: {
+      fonts: { load: async () => [] },
+      createElement() {
+        assert.fail('no canvas before the icon font is ready');
+      },
+    },
+  });
+  const fallback = cache.get('Aves');
+  assert.equal(await cache.load(), false);
+  assert.equal(cache.get('Aves'), fallback);
+});
+
+async function visiblePixels(texture, size) {
+  const svg = texture.includes(';base64,')
+    ? Buffer.from(texture.slice(texture.indexOf(',') + 1), 'base64')
+    : Buffer.from(decodeURIComponent(texture.slice(texture.indexOf(',') + 1)));
+  const { data, info } = await sharp(svg)
+    .resize(size, size)
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  let pixels = 0;
+  for (let i = 0; i < data.length; i += info.channels)
+    if (Math.max(data[i], data[i + 1], data[i + 2]) > 150 && data[i + 3] > 127)
+      pixels += 1;
+  return pixels;
+}
+
+test('compact badge fill remains legible at its near and far footprints', async () => {
+  assert.equal(WILDLIFE_SPRITE_PX, 20);
+  for (const size of [12, 16, WILDLIFE_SPRITE_PX, 22]) {
+    const flightPixels = await visiblePixels(aircraftIcon('airliner'), size);
+    for (const group of WILDLIFE_SPRITE_GROUPS)
+      assert.ok(
+        (await visiblePixels(sprites.get(group), size)) >= flightPixels,
+        `${group} at ${size}px`,
+      );
+  }
+});
diff --git a/src/layers/wildlifeSightings/viewport.js b/src/layers/wildlifeSightings/viewport.js
new file mode 100644
index 000000000..a217a010d
--- /dev/null
+++ b/src/layers/wildlifeSightings/viewport.js
@@ -0,0 +1,83 @@
+import {
+  WILDLIFE_MAX_VIEW_DEGREES,
+  WILDLIFE_RETRY_MIN_MS,
+  WILDLIFE_RETRY_MAX_MS,
+} from './policy.js';
+
+export { snapWildlifeBox } from './bounds.js';
+
+const degrees = (radians) => (radians * 180) / Math.PI;
+const cleanDegree = (value) => Math.round(value * 1e8) / 1e8;
+
+function validBox(box) {
+  return (
+    !!box &&
+    ['south', 'west', 'north', 'east'].every((key) =>
+      Number.isFinite(box[key]),
+    ) &&
+    box.south >= -90 &&
+    box.north <= 90 &&
+    box.north >= box.south &&
+    box.west >= -180 &&
+    box.west <= 180 &&
+    box.east >= -180 &&
+    box.east <= 180
+  );
+}
+
+function longitudeRanges(box) {
+  return box.west <= box.east
+    ? [[box.west, box.east]]
+    : [
+        [box.west, 180],
+        [-180, box.east],
+      ];
+}
+
+/** Test geographic overlap, including boxes that cross the antimeridian. */
+export function boxIntersects(a, b) {
+  if (!validBox(a) || !validBox(b) || a.south > b.north || a.north < b.south)
+    return false;
+  return longitudeRanges(a).some(([aw, ae]) =>
+    longitudeRanges(b).some(([bw, be]) => aw <= be && ae >= bw),
+  );
+}
+
+/** Split a local camera rectangle into noncrossing observation query boxes. */
+export function wildlifeViewportBoxes(viewer) {
+  const camera = viewer?.camera;
+  if (typeof camera?.computeViewRectangle !== 'function') return null;
+  const rectangle = camera.computeViewRectangle(
+    viewer?.scene?.globe?.ellipsoid,
+  );
+  if (!rectangle) return null;
+  const box = Object.fromEntries(
+    ['south', 'west', 'north', 'east'].map((key) => [
+      key,
+      cleanDegree(degrees(rectangle[key])),
+    ]),
+  );
+  if (!validBox(box) || box.north <= box.south) return null;
+  const width =
+    box.east >= box.west ? box.east - box.west : 360 - box.west + box.east;
+  if (
+    width <= 0 ||
+    Math.max(box.north - box.south, width) > WILDLIFE_MAX_VIEW_DEGREES
+  )
+    return null;
+  return longitudeRanges(box)
+    .filter(([west, east]) => east > west)
+    .map(([west, east]) => ({
+      south: box.south,
+      west,
+      north: box.north,
+      east,
+    }));
+}
+
+/** 30 seconds, doubling to a four-minute ceiling, for local retry guidance. */
+export function retryDelayMs(previousMs) {
+  return Number.isFinite(previousMs) && previousMs > 0
+    ? Math.min(WILDLIFE_RETRY_MAX_MS, previousMs * 2)
+    : WILDLIFE_RETRY_MIN_MS;
+}
diff --git a/src/layers/wildlifeSightings/viewport.test.mjs b/src/layers/wildlifeSightings/viewport.test.mjs
new file mode 100644
index 000000000..410086886
--- /dev/null
+++ b/src/layers/wildlifeSightings/viewport.test.mjs
@@ -0,0 +1,136 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  wildlifeViewportBoxes,
+  snapWildlifeBox,
+  boxIntersects,
+  retryDelayMs,
+} from './viewport.js';
+import { ACARTIA_GUARD_BOX } from './policy.js';
+import { getWildlifeHeightBand } from './model.js';
+
+const viewer = ({ south, west, north, east }) => ({
+  camera: {
+    computeViewRectangle: () =>
+      Object.fromEntries(
+        Object.entries({ south, west, north, east }).map(([key, value]) => [
+          key,
+          (value * Math.PI) / 180,
+        ]),
+      ),
+  },
+  scene: { globe: { ellipsoid: {} } },
+});
+
+test('local boxes snap outward to 0.1 degrees; wider views to whole degrees', () => {
+  assert.deepEqual(
+    snapWildlifeBox({
+      south: 47.61,
+      west: -122.35,
+      north: 47.79,
+      east: -122.21,
+    }),
+    { south: 47.6, west: -122.4, north: 47.8, east: -122.2 },
+  );
+  assert.deepEqual(
+    snapWildlifeBox({ south: 40.1, west: -126.2, north: 46.1, east: -121.1 }),
+    { south: 40, west: -127, north: 47, east: -121 },
+  );
+  assert.deepEqual(
+    snapWildlifeBox({ south: 47.6, west: -122.4, north: 47.8, east: -122.2 }),
+    { south: 47.6, west: -122.4, north: 47.8, east: -122.2 },
+  );
+  assert.equal(
+    snapWildlifeBox({ south: -20, west: -30, north: 21, east: 10 }),
+    null,
+  );
+});
+
+test('the final snapped span stays within 40 degrees and snapping is idempotent', () => {
+  for (const box of [
+    { south: 10.2, west: 0, north: 50.1, east: 1 },
+    { south: 0, west: 10.2, north: 1, east: 50.1 },
+  ])
+    assert.equal(snapWildlifeBox(box), null, JSON.stringify(box));
+  for (const box of [
+    { south: 47.4, west: -122.3, north: 47.6, east: -122.1 },
+    { south: 10.01, west: -122.3, north: 14.99, east: -117.31 },
+    { south: 10.01, west: 0, north: 15, east: 5 },
+    { south: 10.01, west: 0, north: 15.01, east: 5 },
+    { south: 10, west: 0, north: 50, east: 1 },
+  ]) {
+    const snapped = snapWildlifeBox(box);
+    assert.ok(snapped, JSON.stringify(box));
+    assert.deepEqual(snapWildlifeBox(snapped), snapped);
+  }
+});
+
+test('intersections handle guard coverage, point boxes and antimeridian', () => {
+  const seattle = { south: 47.5, west: -122.5, north: 47.7, east: -122.2 };
+  assert.equal(boxIntersects(seattle, ACARTIA_GUARD_BOX), true);
+  assert.equal(
+    boxIntersects({ ...seattle, west: 20, east: 21 }, ACARTIA_GUARD_BOX),
+    false,
+  );
+  const dateline = { south: 10, west: 175, north: 20, east: -175 };
+  assert.equal(
+    boxIntersects(dateline, { south: 11, west: 178, north: 12, east: 179 }),
+    true,
+  );
+  assert.equal(
+    boxIntersects(dateline, { south: 11, west: -1, north: 12, east: 1 }),
+    false,
+  );
+  assert.equal(boxIntersects(null, seattle), false);
+});
+
+test('viewport rectangles split at 180 degrees and reject overly large or missing views', () => {
+  assert.deepEqual(
+    wildlifeViewportBoxes(
+      viewer({ south: 10, west: 179, north: 12, east: -178 }),
+    ),
+    [
+      { south: 10, west: 179, north: 12, east: 180 },
+      { south: 10, west: -180, north: 12, east: -178 },
+    ],
+  );
+  assert.deepEqual(
+    wildlifeViewportBoxes(
+      viewer({ south: 47, west: -123, north: 48, east: -122 }),
+    ),
+    [{ south: 47, west: -123, north: 48, east: -122 }],
+  );
+  assert.equal(
+    wildlifeViewportBoxes(
+      viewer({ south: -21, west: -10, north: 20, east: 10 }),
+    ),
+    null,
+  );
+  assert.equal(
+    wildlifeViewportBoxes(
+      viewer({ south: 0, west: 170, north: 10, east: -140 }),
+    ),
+    null,
+  );
+  assert.equal(wildlifeViewportBoxes({}), null);
+});
+
+test('height bands retain representations across +/-5% and switch beyond +/-10%', () => {
+  assert.equal(getWildlifeHeightBand(3_000_001), 'global');
+  assert.equal(getWildlifeHeightBand(3_000_000), 'regional');
+  assert.equal(getWildlifeHeightBand(3_150_000, 'regional'), 'regional');
+  assert.equal(getWildlifeHeightBand(2_850_000, 'global'), 'global');
+  assert.equal(getWildlifeHeightBand(3_310_000, 'regional'), 'global');
+  assert.equal(getWildlifeHeightBand(2_690_000, 'global'), 'regional');
+  assert.equal(getWildlifeHeightBand(1_600_000), 'regional');
+  assert.equal(getWildlifeHeightBand(1_000_000), 'cells');
+  assert.equal(getWildlifeHeightBand(30_000), 'cards');
+  assert.equal(getWildlifeHeightBand(30_000, 'global'), 'cards');
+});
+
+test('retry guidance doubles from 30 seconds to a four-minute ceiling', () => {
+  assert.deepEqual(
+    [undefined, 30_000, 60_000, 120_000, 240_000].map(retryDelayMs),
+    [30_000, 60_000, 120_000, 240_000, 240_000],
+  );
+});
diff --git a/src/materialSymbolsSubset.test.mjs b/src/materialSymbolsSubset.test.mjs
index fdba1c49f..1402f62ac 100644
--- a/src/materialSymbolsSubset.test.mjs
+++ b/src/materialSymbolsSubset.test.mjs
@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
 import { readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { WILDLIFE_BADGE_GLYPHS } from './layers/wildlifeSightings/sprites.js';
 
 const SRC_ROOT = fileURLToPath(new URL('.', import.meta.url));
 const REPO_ROOT = path.resolve(SRC_ROOT, '..');
@@ -56,6 +57,8 @@ function sourceFiles(directory = SRC_ROOT) {
  */
 function referencedGlyphs() {
   const found = new Map();
+  for (const glyph of Object.values(WILDLIFE_BADGE_GLYPHS))
+    found.set(glyph, 'src/layers/wildlifeSightings/sprites.js');
   for (const file of sourceFiles()) {
     const source = readFileSync(file, 'utf8');
     const relative = path.relative(REPO_ROOT, file).split(path.sep).join('/');
diff --git a/src/navigationPolicy.js b/src/navigationPolicy.js
index f69cb54c0..bd268ced5 100644
--- a/src/navigationPolicy.js
+++ b/src/navigationPolicy.js
@@ -23,6 +23,8 @@ const COCKPIT_REFUSALS = Object.freeze({
   target: msg('Exit cockpit to fly to a target'),
   vessel: msg('Exit cockpit to fly to a vessel'),
   fire: msg('Exit cockpit to fly to a fire'),
+  sighting: msg('Exit cockpit to fly to a sighting'),
+  'sighting-area': msg('Exit cockpit to fly to a sighting area'),
   route: msg('Exit cockpit to fly to a route'),
   file: msg('Exit cockpit to fly to a file'),
   drawing: msg('Exit cockpit to fly to a drawing'),
diff --git a/src/overlays/wildlifeSightingOverlay.test.mjs b/src/overlays/wildlifeSightingOverlay.test.mjs
new file mode 100644
index 000000000..503f177d8
--- /dev/null
+++ b/src/overlays/wildlifeSightingOverlay.test.mjs
@@ -0,0 +1,186 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  buildWildlifeSelectedLabel,
+  buildWildlifeThumbnailEntry,
+} from '../layers/wildlifeSightings/cards.js';
+import {
+  normalizeOverlayEntry,
+  paintLaneForOverlayEntry,
+} from './worldOverlay.js';
+import {
+  clearWorldOverlayTextMeasureCache,
+  measureOverlayEntry,
+  paintOverlayEntry,
+} from './worldOverlayDraw.js';
+import { WORLD_OVERLAY_STYLE } from './worldOverlayTokens.js';
+
+function paintingContext(glyphWidth = 6) {
+  const text = [];
+  const fills = [];
+  const strokes = [];
+  const images = [];
+  return {
+    text,
+    fills,
+    strokes,
+    images,
+    measureText: (text) => ({ width: Array.from(text).length * glyphWidth }),
+    save() {},
+    restore() {},
+    beginPath() {},
+    roundRect() {},
+    moveTo() {},
+    lineTo() {},
+    fillRect() {},
+    fill() {
+      fills.push(this.fillStyle);
+    },
+    stroke() {
+      strokes.push(this.strokeStyle);
+    },
+    fillText(value) {
+      text.push(value);
+    },
+    drawImage(...args) {
+      images.push(args);
+    },
+  };
+}
+
+test('wildlife thumbnail titles paint a word-boundary ellipsis after normalization and width fitting', () => {
+  for (const [commonName, glyphWidth, expected] of [
+    ["Bullock's Oriole", 6, "BULLOCK'S…"],
+    ['Great Blue Heron', 11, 'GREAT…'],
+    ['Superlongunbrokentaxon', 6, 'SUPERLONGUNBRO…'],
+  ]) {
+    clearWorldOverlayTextMeasureCache();
+    const entry = normalizeOverlayEntry('wildlife-sightings', {
+      ...buildWildlifeThumbnailEntry(
+        {
+          stableId: 'inat:1',
+          commonName,
+          observedAt: 0,
+          photo: {
+            square:
+              'https://inaturalist-open-data.s3.amazonaws.com/photos/1/square.jpg',
+            licence: 'cc-by',
+            attribution: 'Synthetic Photographer',
+          },
+        },
+        0,
+        { image: { width: 75, height: 75 } },
+      ),
+      position: { x: 1, y: 2, z: 3 },
+    });
+    const ctx = paintingContext(glyphWidth);
+    entry._overlayLayout = measureOverlayEntry(ctx, entry);
+    paintOverlayEntry(ctx, entry, {
+      rect: {
+        x: 10,
+        y: 20,
+        w: entry._overlayLayout.w,
+        h: entry._overlayLayout.h,
+      },
+    });
+    assert.equal(ctx.text[0], expected);
+    assert.ok(ctx.measureText(ctx.text[0]).width <= 96);
+    assert.ok(entry.accessibilityLabel.includes(commonName));
+  }
+});
+
+test('selected thumbnails retain their image in the host selected chrome and lane, without a link line', () => {
+  const entry = normalizeOverlayEntry('wildlife-sightings', {
+    ...buildWildlifeThumbnailEntry(
+      {
+        stableId: 'inat:1',
+        commonName: 'Synthetic bird',
+        observedAt: 0,
+        uri: 'https://www.inaturalist.org/observations/1',
+        photo: {
+          square:
+            'https://inaturalist-open-data.s3.amazonaws.com/photos/1/square.jpg',
+          licence: 'cc-by',
+          attribution: 'Synthetic Photographer',
+        },
+      },
+      0,
+      { selected: true, image: { width: 75, height: 75 } },
+    ),
+    position: { x: 1, y: 2, z: 3 },
+  });
+  const ctx = paintingContext();
+  entry._overlayLayout = measureOverlayEntry(ctx, entry);
+  paintOverlayEntry(ctx, entry, {
+    rect: {
+      x: 10,
+      y: 20,
+      w: entry._overlayLayout.w,
+      h: entry._overlayLayout.h,
+    },
+  });
+  assert.equal(entry.selected, true);
+  assert.equal(
+    paintLaneForOverlayEntry(entry),
+    paintLaneForOverlayEntry({ selected: true }),
+  );
+  assert.equal(entry._overlayLayout.thumbH, 72);
+  assert.equal(ctx.images.length, 1);
+  assert.ok(ctx.fills.includes(WORLD_OVERLAY_STYLE.selectedBackground));
+  assert.ok(ctx.strokes.includes(WORLD_OVERLAY_STYLE.selectedBorder));
+  assert.ok(!ctx.text.some((line) => String(line).includes('↗')));
+});
+
+test('selected wildlife names retain a bounded title with the host selected metrics', () => {
+  for (const origin of ['inaturalist', 'acartia']) {
+    clearWorldOverlayTextMeasureCache();
+    const row = {
+      stableId: `${origin}:1`,
+      origin,
+      commonName:
+        'Synthetic bird with a very long common name that cannot widen the globe label',
+      scientificName: 'Avis synthetica',
+      iconic: 'Aves',
+      photo: {
+        square:
+          'https://inaturalist-open-data.s3.amazonaws.com/photos/1/square.jpg',
+        attribution:
+          'Synthetic Photographer, full attribution belongs in the dialog',
+        licence: 'cc-by',
+      },
+    };
+    const entry = normalizeOverlayEntry('wildlife-sightings-selected', {
+      ...buildWildlifeSelectedLabel(row),
+      position: { x: 1, y: 2, z: 3 },
+    });
+    const fonts = [];
+    const ctx = {
+      font: '',
+      measureText(text) {
+        fonts.push(this.font);
+        return { width: [...text].length * 6 };
+      },
+    };
+    const layout = measureOverlayEntry(ctx, entry);
+    assert.equal(entry.variant, 'label');
+    assert.equal(
+      entry.selected,
+      true,
+      'selected names use the host selected painter',
+    );
+    assert.equal(entry.protected, true);
+    assert.equal(entry.paintLane, 'selected');
+    assert.equal(
+      paintLaneForOverlayEntry(entry),
+      paintLaneForOverlayEntry({ selected: true }),
+    );
+    assert.equal(entry.pinned, false);
+    assert.equal(entry.interactive, false);
+    assert.equal(entry.placement, 'above');
+    assert.deepEqual(entry.details, []);
+    assert.equal(entry.image, null);
+    assert.equal(layout.h, 31, 'shared selected title and padding');
+    assert.ok(layout.w <= 264, `bounded name, got ${layout.w}px`);
+    assert.deepEqual(fonts, [WORLD_OVERLAY_STYLE.fontSelected]);
+  }
+});
diff --git a/src/overlays/worldOverlay.js b/src/overlays/worldOverlay.js
index 7b0b9d5fd..748e02fda 100644
--- a/src/overlays/worldOverlay.js
+++ b/src/overlays/worldOverlay.js
@@ -1,3 +1,5 @@
+import { WORLD_OVERLAY_OCCLUDER_SELECTORS } from './worldOverlayChrome.js';
+export { WORLD_OVERLAY_OCCLUDER_SELECTORS } from './worldOverlayChrome.js';
 import * as Cesium from 'cesium';
 import {
   createCyberSonarSampler,
@@ -19,6 +21,7 @@ import {
   measureOverlayEntry,
   paintOverlayEntry,
   placementVariants,
+  truncateOverlayTitle,
 } from './worldOverlayDraw.js';
 import { WORLD_OVERLAY_STYLE } from './worldOverlayTokens.js';
 import { t } from '../i18n/index.js';
@@ -72,57 +75,6 @@ const PAINT_LANE_INDEX = new Map(
   WORLD_OVERLAY_PAINT_LANES.map((lane, index) => [lane, index]),
 );
 
-/**
- * Unified UI exclusion inventory. Selectors may match multiple elements; the
- * service caches their rectangles and observes layout/visibility changes.
- *
- * These rectangles are a PLACEMENT policy, never a paint mask. Every element
- * listed here composites ABOVE the overlay host — map chrome sits at z90–z1000
- * and the cockpit HUD at z145, against this host's z5/z6 — so the browser
- * already keeps overlay pixels off it and no canvas needs clipping. What the
- * inventory buys is readability: a card placed under solid chrome is simply
- * lost, so the solver PREFERS placements clear of it. When nothing is clear the
- * entry still renders and the chrome covers it, exactly as it did before the
- * host existed.
- *
- * The list therefore holds only chrome dense enough to swallow a card. The
- * cockpit's thin translucent line art — rims, arcs, rails, tapes, toplines,
- * readouts — is deliberately ABSENT under the owner's AR-HUD ruling:
- * world-space overlay content renders beneath the cockpit's screen-space HUD,
- * which paints over it by z-order. Those elements are also enormous (the
- * altitude rim is keyhole-tall, the topline viewport-wide), and excluding them
- * suppressed essentially the entire cockpit view. Only the two solid,
- * backdrop-filled cockpit windows survive as exclusions.
- */
-export const WORLD_OVERLAY_OCCLUDER_SELECTORS = Object.freeze([
-  '#title-bar',
-  '#style-indicator',
-  '#top-center-actions',
-  '#traffic-sync-chip',
-  '#cctv-sync-chip',
-  '#left-panel-stack',
-  '#right-context-rail',
-  '.weather-summary',
-  '#pp-toggles',
-  '#command-dock',
-  '#gev-voice-control',
-  '#cesium-credits',
-  '.hud-top-left',
-  '.hud-top-right',
-  '.hud-bottom-left',
-  '.hud-bottom-right',
-  '.hud-bottom-bar',
-  '#space-mission-panel',
-  '#space-mission-panel-host',
-  '#military-awareness-panel',
-  '#bhote-koshi-event-panel',
-  // Cockpit: solid backdrop-filled windows only (both bounded to
-  // `min(340px, 28vw)` wide and `min(42vh, 410px)` tall, both `hidden` until
-  // toggled). Every other cockpit selector was removed — see the block comment.
-  '#cockpit-context',
-  '#cockpit-signal-stream',
-]);
-
 /** @typedef {{x:number,y:number,w:number,h:number}} OverlayRect */
 /**
  * @typedef {object} WorldOverlayEntry
@@ -143,6 +95,8 @@ export const WORLD_OVERLAY_OCCLUDER_SELECTORS = Object.freeze([
  * @property {number} [maxVisible=Infinity] Source ceiling within a shared domain.
  * @property {boolean} [moving=false] Enables bounded interval re-solves.
  * @property {number} [solveIntervalMs=125]
+ * @property {function(Set<string>):void} [onVisibilityChange] Painted entry ids,
+ *   reported only on membership changes. The borrowed Set is read-only.
  */
 
 /** @type {Cesium.Viewer|null} */
@@ -470,6 +424,11 @@ export function normalizeOverlayEntry(sourceId, entry) {
     collisionGroup: String(
       entry.collisionGroup || defaultCollisionGroup(variant),
     ),
+    // Optional lower-priority content must fit around the actual painted
+    // members of another domain, including its sticky positions and exit fades.
+    yieldToCollisionGroup: entry.yieldToCollisionGroup
+      ? String(entry.yieldToCollisionGroup)
+      : null,
     // Explicit field pick rather than `{ ...entry, variant }`: the lane
     // resolver reads only these four, and a full spread re-invokes every
     // accessor the source put on its entry (a throwing one would abort
@@ -592,12 +551,15 @@ export function normalizeOverlayEntry(sourceId, entry) {
     metadata: entry.metadata ?? null,
     thumbnailWidth: entry.thumbnailWidth,
     thumbnailHeight: entry.thumbnailHeight,
+    thumbnailFit: entry.thumbnailFit === 'contain' ? 'contain' : null,
+    thumbnailFixedWidth: entry.thumbnailFixedWidth === true,
     thumbnailPadX: entry.thumbnailPadX,
     thumbnailPadTop: entry.thumbnailPadTop,
     thumbnailPadBottom: entry.thumbnailPadBottom,
     thumbnailTitleGap: entry.thumbnailTitleGap,
     thumbnailTitleHeight: entry.thumbnailTitleHeight,
     thumbnailTitleChars: entry.thumbnailTitleChars,
+    thumbnailTitleWordBoundary: entry.thumbnailTitleWordBoundary === true,
     thumbnailBackground: entry.thumbnailBackground,
     thumbnailTitleColor: entry.thumbnailTitleColor,
     thumbnailTitleFont: entry.thumbnailTitleFont,
@@ -611,13 +573,21 @@ export function normalizeOverlayEntry(sourceId, entry) {
     _overlayTrackDisplayText: '',
     _overlayThumbnailTitle:
       variant === 'thumbnail'
-        ? String(entry.title ?? '')
-            .toUpperCase()
-            .slice(
-              0,
+        ? entry.thumbnailTitleWordBoundary === true
+          ? truncateOverlayTitle(
+              String(entry.title ?? '').toUpperCase(),
               Math.max(0, Math.floor(Number(entry.thumbnailTitleChars) || 0)) ||
-                undefined,
+                Infinity,
             )
+          : String(entry.title ?? '')
+              .toUpperCase()
+              .slice(
+                0,
+                Math.max(
+                  0,
+                  Math.floor(Number(entry.thumbnailTitleChars) || 0),
+                ) || undefined,
+              )
         : '',
   };
   normalized._overlayKey = entryKey(source, id);
@@ -714,6 +684,12 @@ function normalizeSourceOptions(options = {}, previous = {}) {
           DEFAULT_MOVING_SOLVE_MS,
       ) || 0,
     ),
+    onVisibilityChange:
+      options.onVisibilityChange === undefined
+        ? previous.onVisibilityChange || null
+        : typeof options.onVisibilityChange === 'function'
+          ? options.onVisibilityChange
+          : null,
   };
 }
 
@@ -844,6 +820,7 @@ function getOrCreateSource(sourceId, options = {}) {
       cohortLists: [],
       cohortCount: 0,
       demandByDomain: new Map(),
+      visibleIds: new Set(),
       options: normalizeSourceOptions(options),
     };
     _sources.set(id, source);
@@ -1157,18 +1134,17 @@ export function isOverlayPointVisible(
  */
 function overlayRectIntersectsAny(rect, exclusions, count = exclusions.length) {
   for (let i = 0; i < count; i++) {
-    const other = exclusions[i];
-    if (
-      rect.x < other.x + other.w &&
-      rect.x + rect.w > other.x &&
-      rect.y < other.y + other.h &&
-      rect.y + rect.h > other.y
-    )
-      return true;
+    if (overlayRectsOverlap(rect, exclusions[i])) return true;
   }
   return false;
 }
 
+function overlayRectsOverlap(a, b) {
+  return (
+    a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y
+  );
+}
+
 /**
  * Like `overlayRectIntersectsAny`, but only against exclusions that composite
  * BELOW the host — the ones a placement may never overlap at any cost.
@@ -1180,14 +1156,7 @@ function overlayRectIntersectsAnyHard(
 ) {
   for (let i = 0; i < count; i++) {
     const other = exclusions[i];
-    if (!other.hard) continue;
-    if (
-      rect.x < other.x + other.w &&
-      rect.x + rect.w > other.x &&
-      rect.y < other.y + other.h &&
-      rect.y + rect.h > other.y
-    )
-      return true;
+    if (other.hard && overlayRectsOverlap(rect, other)) return true;
   }
   return false;
 }
@@ -2253,6 +2222,7 @@ function addPaintItem(record, placement, temporalAlpha, selected) {
   item.lane = paintLaneForOverlayEntry(record.entry);
   item.zIndex = record.entry.zIndex;
   item.key = record.key;
+  item.collisionHidden = false;
   _paintQueue[_paintCount++] = item;
 }
 
@@ -2454,6 +2424,7 @@ function paintCustomLane(lane) {
 }
 
 function paintEntryItem(item, keyhole, sonar) {
+  if (item.collisionHidden) return;
   const { record, placement } = item;
   const entry = record.entry;
   let keyholeAlpha = 1;
@@ -2517,6 +2488,90 @@ function paintEntryItem(item, keyhole, sonar) {
   _paintedBySource[entry.source]++;
 }
 
+function compareYieldingPaintItems(a, b) {
+  const aYields = !!a.record.entry.yieldToCollisionGroup;
+  const bYields = !!b.record.entry.yieldToCollisionGroup;
+  return (
+    Number(aYields) - Number(bYields) ||
+    b.record.entry.priority - a.record.entry.priority ||
+    compareStableKeys(a.key, b.key)
+  );
+}
+
+/** Recheck yielding content every painted frame, even between camera solves.
+ * The arbiter's sticky/exit placements are intentionally retained for cards;
+ * labels can only use the remaining rectangles. All buffers are reused. */
+function declutterYieldingEntries() {
+  let hasYielding = false;
+  for (let i = 0; i < _paintCount; i++)
+    if (_paintQueue[i].record.entry.yieldToCollisionGroup) {
+      hasYielding = true;
+      break;
+    }
+  if (!hasYielding) return;
+  sortPooledRange(_paintQueue, _paintCount, compareYieldingPaintItems);
+  for (let i = 0; i < _paintCount; i++) {
+    const item = _paintQueue[i];
+    const entry = item.record.entry;
+    if (!entry.yieldToCollisionGroup) continue;
+    const placements = item.record.placements;
+    let accepted = null;
+    // Try the arbiter's chosen corner first, then its other valid placements.
+    for (let p = -1; p < placements.length; p++) {
+      const placement = p < 0 ? item.placement : placements[p];
+      if (p >= 0 && placement === item.placement) continue;
+      let blocked = false;
+      for (let j = 0; j < i; j++) {
+        const other = _paintQueue[j];
+        if (other.collisionHidden) continue;
+        const group = other.record.entry.collisionGroup;
+        if (
+          (group === entry.collisionGroup ||
+            group === entry.yieldToCollisionGroup) &&
+          overlayRectsOverlap(placement.rect, other.placement.rect)
+        ) {
+          blocked = true;
+          break;
+        }
+      }
+      if (!blocked) {
+        accepted = placement;
+        break;
+      }
+    }
+    if (accepted) item.placement = accepted;
+    else item.collisionHidden = true;
+  }
+}
+
+function syncPaintVisibility(painted = true) {
+  for (let s = 0; s < _sourceList.length; s++) {
+    const source = _sourceList[s];
+    const callback = source.options.onVisibilityChange;
+    if (!callback) continue;
+    const count = painted ? _paintedBySource[source.id] || 0 : 0;
+    let changed = count !== source.visibleIds.size;
+    if (!changed && painted) {
+      for (const id of source.visibleIds) {
+        if (
+          _paintRectByKey.get(entryKey(source.id, id))?.stamp !== _frameStamp
+        ) {
+          changed = true;
+          break;
+        }
+      }
+    }
+    if (!changed) continue;
+    source.visibleIds.clear();
+    if (painted)
+      for (let i = 0; i < _paintRectCount; i++) {
+        const rect = _paintRectPool[i];
+        if (rect.sourceId === source.id) source.visibleIds.add(rect.entryId);
+      }
+    callback(source.visibleIds);
+  }
+}
+
 function paintFrame(keyhole) {
   const started = nowMs();
   const sonar = isCyberSonarActive()
@@ -2531,6 +2586,7 @@ function paintFrame(keyhole) {
     clearCanvas(false, true);
   _paintRectCount = 0;
   _hitRectCount = 0;
+  declutterYieldingEntries();
   sortPooledRange(_paintQueue, _paintCount, comparePaintItems);
   // The shared canvas is not clipped either. Cards already avoid solid chrome
   // by placement, and every occluder composites above this host in the DOM, so
@@ -2553,6 +2609,7 @@ function paintFrame(keyhole) {
   _diagnostics.paintRectPoolSize = _paintRectPool.length;
   _diagnostics.paintMs = nowMs() - started;
   syncAccessibleActions();
+  syncPaintVisibility();
   _canvasNeedsClear =
     _paintRectCount > 0 || activeCustomPaintLaneCount(PAINT_TARGET_SHARED) > 0;
 }
@@ -2609,6 +2666,7 @@ function drawWorldOverlay() {
       _hitRectCount = 0;
       syncAccessibleActions();
     }
+    syncPaintVisibility(false);
     return;
   }
   if (_resizeDirty) ensureCanvasSize();
@@ -2743,6 +2801,7 @@ export function destroyWorldOverlay() {
   ) {
     delete window.__gevWorldOverlay;
   }
+  syncPaintVisibility(false);
   _sources.clear();
   _sourceList.length = 0;
   for (let i = 0; i < _customPaintLaneList.length; i++) {
diff --git a/src/overlays/worldOverlay.test.mjs b/src/overlays/worldOverlay.test.mjs
index f2e608b78..881353b07 100644
--- a/src/overlays/worldOverlay.test.mjs
+++ b/src/overlays/worldOverlay.test.mjs
@@ -12,6 +12,15 @@ import {
 } from '../celestialRing.js';
 import { createCctvThumbnailOverlayEntry, createFrameSlot } from '../data/cctvCards.js';
 import { combinedOverlayAlpha } from './worldOverlayDraw.js';
+import {
+  buildWildlifeLabelEntry,
+  buildWildlifeThumbnailEntry,
+  buildWildlifeSelectedLabel,
+  WILDLIFE_OVERLAY_SOURCE_ID,
+  WILDLIFE_OVERLAY_SOURCE_OPTIONS,
+  WILDLIFE_LABEL_SOURCE_ID,
+  WILDLIFE_LABEL_SOURCE_OPTIONS,
+} from '../layers/wildlifeSightings/cards.js';
 import {
   AMBIENT_CARD_COLLISION_CAPACITY,
   WORLD_OVERLAY_OCCLUDER_SELECTORS,
@@ -1596,6 +1605,171 @@ test('bounded per-source cohorts feed the domain arbiter without universal selec
   env.cleanup();
 });
 
+test('wildlife common names use the host ambient collision domain and never paint overlapping labels', (t) => {
+  const env = installMockEnvironment({ width: 1000, height: 600, dpr: 1 });
+  t.after(() => env.cleanup());
+  initWorldOverlay(env.viewer);
+  const entries = [
+    ['hawk', 'Red-tailed Hawk', position()],
+    ['maple', 'Red Maple', position()],
+    ['butterfly', 'Monarch', new Cesium.Cartesian3(-0.6, 0.6, 0)],
+    ['unknown', null, position()],
+  ].map(([stableId, commonName, anchor]) => {
+    const entry = buildWildlifeLabelEntry({ stableId, commonName, iconic: 'Aves' });
+    return entry && { ...entry, position: anchor, horizonCull: false, edgeFade: 'none' };
+  }).filter(Boolean);
+  assert.equal(entries.length, 3, 'unidentified icons never enter the overlay host');
+  setOverlayEntries(WILDLIFE_LABEL_SOURCE_ID, entries, WILDLIFE_LABEL_SOURCE_OPTIONS);
+  env.postRender.raise();
+  env.advanceTime(200);
+  env.postRender.raise();
+  const rects = entries.map((entry) => getOverlayPaintRect(WILDLIFE_LABEL_SOURCE_ID, entry.id)).filter(Boolean);
+  assert.ok(rects.length >= 2 && rects.length <= 3, 'the host places separated names and relocates or drops coincident names');
+  for (let i = 0; i < rects.length; i++) {
+    assert.equal(rects[i].entry.collisionGroup, 'ambient-label');
+    assert.equal(rects[i].entry.protected, false);
+    for (let j = i + 1; j < rects.length; j++) {
+      const a = rects[i], b = rects[j];
+      assert.ok(a.x + a.w <= b.x || b.x + b.w <= a.x || a.y + a.h <= b.y || b.y + b.h <= a.y);
+    }
+  }
+});
+
+const CITY_NOW = Date.parse('2026-11-04T18:00:00Z');
+function citySighting(id, overrides = {}) {
+  return {
+    stableId: id, commonName: `Synthetic city species ${id}`, iconic: 'Aves',
+    observedAt: CITY_NOW - 60_000, quality: 'research', favesCount: 1,
+    photo: {
+      square: 'https://inaturalist-open-data.s3.amazonaws.com/photos/1/square.jpg',
+      licence: 'cc-by', attribution: 'Synthetic Photographer',
+    },
+    ...overrides,
+  };
+}
+function cityLabel(row, x, y, width = 1000, height = 600) {
+  return {
+    ...buildWildlifeLabelEntry(row, { nowMs: CITY_NOW }),
+    position: positionAtScreen(x, y, width, height), horizonCull: false, edgeFade: 'none',
+  };
+}
+function cityCard(row, x, y, width = 1000, height = 600, image = { width: 75, height: 75 }) {
+  return {
+    ...buildWildlifeThumbnailEntry(row, CITY_NOW, { image }),
+    position: positionAtScreen(x, y, width, height), horizonCull: false, edgeFade: 'none',
+    maxDistance: Infinity,
+  };
+}
+function assertDisjointPaint(entries) {
+  const rects = entries.map(([source, entry]) => getOverlayPaintRect(source, entry.id)).filter(Boolean);
+  for (let i = 0; i < rects.length; i++)
+    for (let j = i + 1; j < rects.length; j++) {
+      const a = rects[i], b = rects[j];
+      assert.ok(a.x + a.w <= b.x || b.x + b.w <= a.x || a.y + a.h <= b.y || b.y + b.h <= a.y,
+        `${a.entryId} overlaps ${b.entryId}`);
+    }
+  return rects;
+}
+
+test('close-range dense city labels and photo cards never overlap, including frames between camera solves', (t) => {
+  const env = installMockEnvironment({ width: 1000, height: 600, dpr: 1 });
+  t.after(() => env.cleanup());
+  env.viewer.camera.positionCartographic.height = 9000;
+  initWorldOverlay(env.viewer);
+  const labels = Array.from({ length: 150 }, (_, i) =>
+    cityLabel(citySighting(`city:${i}`, { favesCount: 150 - i }), 65 + (i % 30) * 28, 150 + Math.floor(i / 30) * 62));
+  const cards = Array.from({ length: 8 }, (_, i) =>
+    cityCard(citySighting(`photo:${i}`), 140 + (i % 4) * 210, 180 + Math.floor(i / 4) * 240));
+  const all = [...labels.map((e) => [WILDLIFE_LABEL_SOURCE_ID, e]), ...cards.map((e) => [WILDLIFE_OVERLAY_SOURCE_ID, e])];
+  setOverlayEntries(WILDLIFE_LABEL_SOURCE_ID, labels, WILDLIFE_LABEL_SOURCE_OPTIONS);
+  setOverlayEntries(WILDLIFE_OVERLAY_SOURCE_ID, cards, WILDLIFE_OVERLAY_SOURCE_OPTIONS);
+  for (const ms of [0, 75, 125]) {
+    env.advanceTime(ms);
+    env.postRender.raise();
+    assertDisjointPaint(all);
+  }
+  assert.equal(cards.filter((e) => getOverlayPaintRect(WILDLIFE_OVERLAY_SOURCE_ID, e.id)).length, 8);
+  const placedLabels = labels.filter((e) => getOverlayPaintRect(WILDLIFE_LABEL_SOURCE_ID, e.id));
+  assert.ok(placedLabels.length > 5 && placedLabels.length < labels.length, 'label count is capped by the remaining space');
+  // A pan/zoom reprojects sticky placements on every frame before moveEnd.
+  env.viewer.camera.frustum.projectionMatrix[0] = 0.7;
+  env.viewer.camera.frustum.projectionMatrix[5] = 0.8;
+  env.advanceTime(16);
+  env.postRender.raise();
+  assertDisjointPaint(all);
+  env.moveEnd.raise();
+  env.advanceTime(75);
+  env.postRender.raise();
+  assertDisjointPaint(all);
+});
+
+test('labels yield immediately to photo cards, then compete by ambientScore without disturbing the card', (t) => {
+  const env = installMockEnvironment({ width: 400, height: 350, dpr: 1 });
+  t.after(() => env.cleanup());
+  initWorldOverlay(env.viewer);
+  const low = cityLabel(citySighting('low'), 200, 210, 400, 350);
+  const high = cityLabel(citySighting('high', { favesCount: 1000 }), 200, 210, 400, 350);
+  const card = cityCard(citySighting('card', { quality: 'needs_id' }), 200, 210, 400, 350);
+  const all = [[WILDLIFE_LABEL_SOURCE_ID, low], [WILDLIFE_LABEL_SOURCE_ID, high], [WILDLIFE_OVERLAY_SOURCE_ID, card]];
+  setOverlayEntries(WILDLIFE_LABEL_SOURCE_ID, [low, high], WILDLIFE_LABEL_SOURCE_OPTIONS);
+  env.postRender.raise();
+  env.advanceTime(200);
+  env.postRender.raise();
+  assert.equal(assertDisjointPaint(all).length, 2, 'both label slots are initially free');
+  setOverlayEntries(WILDLIFE_OVERLAY_SOURCE_ID, [card], WILDLIFE_OVERLAY_SOURCE_OPTIONS);
+  env.postRender.raise();
+  for (const ms of [1, 74, 125]) {
+    env.advanceTime(ms);
+    env.postRender.raise();
+    assertDisjointPaint(all);
+    assert.ok(getOverlayPaintRect(WILDLIFE_OVERLAY_SOURCE_ID, card.id));
+    assert.ok(getOverlayPaintRect(WILDLIFE_LABEL_SOURCE_ID, high.id));
+    assert.equal(getOverlayPaintRect(WILDLIFE_LABEL_SOURCE_ID, low.id), null);
+  }
+  const before = { ...getOverlayPaintRect(WILDLIFE_OVERLAY_SOURCE_ID, card.id) };
+  const promoted = cityLabel(citySighting('low', { favesCount: 1_000_000 }), 200, 210, 400, 350);
+  setOverlayEntries(WILDLIFE_LABEL_SOURCE_ID, [promoted, high], WILDLIFE_LABEL_SOURCE_OPTIONS);
+  env.postRender.raise();
+  assertDisjointPaint(all);
+  assert.ok(getOverlayPaintRect(WILDLIFE_LABEL_SOURCE_ID, low.id));
+  assert.equal(getOverlayPaintRect(WILDLIFE_LABEL_SOURCE_ID, high.id), null);
+  const after = getOverlayPaintRect(WILDLIFE_OVERLAY_SOURCE_ID, card.id);
+  assert.deepEqual([after.x, after.y, after.w, after.h], [before.x, before.y, before.w, before.h], 'the card retains its sticky placement');
+  const selected = { ...buildWildlifeSelectedLabel(citySighting('selected')), position: card.position, horizonCull: false, edgeFade: 'none' };
+  setOverlayEntries('wildlife-sightings-selected', [selected]);
+  env.postRender.raise();
+  assertDisjointPaint([...all, ['wildlife-sightings-selected', selected]]);
+  // Exit fades still occupy space; labels must wait until the card is gone.
+  setOverlayEntries(WILDLIFE_OVERLAY_SOURCE_ID, [], WILDLIFE_OVERLAY_SOURCE_OPTIONS);
+  for (const ms of [1, 149, 151]) {
+    env.advanceTime(ms);
+    env.postRender.raise();
+    assertDisjointPaint([...all, ['wildlife-sightings-selected', selected]]);
+  }
+});
+
+test('photo visibility reports only painted membership changes, ignoring loading cards and idle frames', (t) => {
+  const env = installMockEnvironment({ width: 400, height: 350, dpr: 1 });
+  t.after(() => env.cleanup());
+  initWorldOverlay(env.viewer);
+  const changes = [];
+  const options = { ...WILDLIFE_OVERLAY_SOURCE_OPTIONS, onVisibilityChange: (ids) => changes.push([...ids]) };
+  const r = citySighting('anchor');
+  setOverlayEntries(WILDLIFE_OVERLAY_SOURCE_ID, [cityCard(r, 200, 210, 400, 350, null)], options);
+  env.postRender.raise();
+  assert.deepEqual(changes, []);
+  setOverlayEntries(WILDLIFE_OVERLAY_SOURCE_ID, [cityCard(r, 200, 210, 400, 350)], options);
+  env.postRender.raise();
+  env.advanceTime(200);
+  env.postRender.raise();
+  assert.deepEqual(changes, [['sighting:anchor']]);
+  for (let i = 0; i < 10; i++) env.postRender.raise();
+  assert.equal(changes.length, 1, 'unchanged visibility emits nothing');
+  setOverlaySourceVisible(WILDLIFE_OVERLAY_SOURCE_ID, false);
+  env.postRender.raise();
+  assert.deepEqual(changes, [['sighting:anchor'], []]);
+});
+
 test('FIRMS and vessels enlarge the ambient-card lane under an explicit aggregate budget', () => {
   const env = installMockEnvironment({ width: 1600, height: 900, dpr: 1 });
   initWorldOverlay(env.viewer);
diff --git a/src/overlays/worldOverlayChrome.js b/src/overlays/worldOverlayChrome.js
new file mode 100644
index 000000000..0142377bf
--- /dev/null
+++ b/src/overlays/worldOverlayChrome.js
@@ -0,0 +1,29 @@
+// Solid chrome that card placement should avoid. It composites above the
+// overlay; the host needs no paint mask. Cockpit line art is intentionally
+// excluded so its large bounds cannot suppress world-space content.
+export const WORLD_OVERLAY_OCCLUDER_SELECTORS = Object.freeze([
+  '#title-bar',
+  '#style-indicator',
+  '#top-center-actions',
+  '#traffic-sync-chip',
+  '#cctv-sync-chip',
+  '#left-panel-stack',
+  '#right-context-rail',
+  '.weather-summary',
+  '#pp-toggles',
+  '#command-dock',
+  '#gev-voice-control',
+  '#cesium-credits',
+  '.hud-top-left',
+  '.hud-top-right',
+  '.hud-bottom-left',
+  '.hud-bottom-right',
+  '.hud-bottom-bar',
+  '#space-mission-panel',
+  '#space-mission-panel-host',
+  '#military-awareness-panel',
+  '#bhote-koshi-event-panel',
+  // Only the cockpit's solid windows obstruct readable cards.
+  '#cockpit-context',
+  '#cockpit-signal-stream',
+]);
diff --git a/src/overlays/worldOverlayDraw.js b/src/overlays/worldOverlayDraw.js
index f64a3170d..e5db5d5b7 100644
--- a/src/overlays/worldOverlayDraw.js
+++ b/src/overlays/worldOverlayDraw.js
@@ -312,9 +312,10 @@ function trackDisplayText(entry) {
  * @returns {{w:number,h:number,padX:number,padY:number,titleH:number,lineH:number,thumbW:number,thumbH:number}}
  */
 export function measureOverlayEntry(ctx, entry, out = {}) {
-  const variant = entry?.selected
-    ? 'selected'
-    : String(entry?.variant || 'label');
+  const variant =
+    entry?.selected && entry?.variant !== 'thumbnail'
+      ? 'selected'
+      : String(entry?.variant || 'label');
   const details = Array.isArray(entry?.details) ? entry.details : [];
   const selected = variant === 'selected';
   const tracked = variant === 'tracked';
@@ -391,7 +392,13 @@ export function measureOverlayEntry(ctx, entry, out = {}) {
     out.thumbW = Math.max(1, Number(entry?.thumbnailWidth) || 96);
     out.thumbH = Math.max(1, Number(entry?.thumbnailHeight) || 54);
     out.w = out.thumbW + out.padX * 2;
-    out.h = out.padY + out.thumbH + out.titleGap + out.titleH + out.padBottom;
+    out.h =
+      out.padY +
+      out.thumbH +
+      out.titleGap +
+      out.titleH +
+      details.length * out.lineH +
+      out.padBottom;
   } else {
     out.w = Math.ceil(Math.max(titleWidth, detailWidth)) + out.padX * 2;
     out.h = out.padY * 2 + out.titleH + details.length * out.lineH;
@@ -912,6 +919,38 @@ export function paintCard(
   return placement.rect;
 }
 
+/** Bound a title by code points, preferring a whole word before the ellipsis. */
+export function truncateOverlayTitle(value, maxChars) {
+  const text = String(value ?? '');
+  if (text.length <= maxChars) return text;
+  const glyphs = Array.from(text);
+  if (glyphs.length <= maxChars) return text;
+  const length = Math.max(0, maxChars - 1);
+  const prefix = glyphs.slice(0, length).join('');
+  const atBoundary = /\s$/u.test(prefix) || /\s/u.test(glyphs[length] || '');
+  const words = atBoundary
+    ? prefix.trimEnd()
+    : prefix.replace(/\s+\S*$/u, '').trimEnd();
+  return `${words || prefix.trimEnd()}…`;
+}
+
+function fitThumbnailText(ctx, value, font, maxWidth, wordBoundary = false) {
+  const text = String(value ?? '');
+  if (measureWorldOverlayText(ctx, text, font) <= maxWidth) return text;
+  const glyphs = Array.from(text);
+  let low = 0;
+  let high = glyphs.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const candidate = `${glyphs.slice(0, mid).join('')}…`;
+    if (measureWorldOverlayText(ctx, candidate, font) <= maxWidth) low = mid;
+    else high = mid - 1;
+  }
+  return wordBoundary
+    ? truncateOverlayTitle(text, low + 1)
+    : `${glyphs.slice(0, low).join('')}…`;
+}
+
 /** Paint a thumbnail card. The image slot remains source-owned. */
 export function paintThumbnail(
   ctx,
@@ -928,6 +967,7 @@ export function paintThumbnail(
   const thumbW = layout.thumbW || Number(entry.thumbnailWidth) || 96;
   const thumbH = layout.thumbH || Number(entry.thumbnailHeight) || 54;
   const titleH = Number.isFinite(layout.titleH) ? layout.titleH : 13;
+  const details = Array.isArray(entry.details) ? entry.details : [];
   const image = entry.image?.frame ?? entry.image;
   ctx.save();
   ctx.globalAlpha = alpha;
@@ -942,16 +982,38 @@ export function paintThumbnail(
   );
   drawAnchorDot(ctx, entry, placement);
   ctx.globalAlpha = alpha * Math.max(0, Math.min(1, Number(contentAlpha) || 0));
-  ctx.beginPath();
-  roundedRectPath(ctx, x, y, w, h, Number(entry.thumbnailRadius) || 4);
-  ctx.fillStyle = entry.thumbnailBackground || WORLD_OVERLAY_STYLE.background;
-  ctx.fill();
+  if (entry.selected) {
+    drawCardChrome(ctx, entry, placement, true, false);
+  } else {
+    ctx.beginPath();
+    roundedRectPath(ctx, x, y, w, h, Number(entry.thumbnailRadius) || 4);
+    ctx.fillStyle = entry.thumbnailBackground || WORLD_OVERLAY_STYLE.background;
+    ctx.fill();
+  }
 
   const imageX = x + padX;
   const imageY = y + padY;
   if (image && typeof ctx.drawImage === 'function') {
     try {
-      ctx.drawImage(image, imageX, imageY, thumbW, thumbH);
+      const sourceW = Number(
+        image.naturalWidth || image.videoWidth || image.width,
+      );
+      const sourceH = Number(
+        image.naturalHeight || image.videoHeight || image.height,
+      );
+      const scale =
+        entry.thumbnailFit === 'contain' && sourceW > 0 && sourceH > 0
+          ? Math.min(thumbW / sourceW, thumbH / sourceH)
+          : null;
+      const width = scale == null ? thumbW : sourceW * scale;
+      const height = scale == null ? thumbH : sourceH * scale;
+      ctx.drawImage(
+        image,
+        imageX + (thumbW - width) / 2,
+        imageY + (thumbH - height) / 2,
+        width,
+        height,
+      );
     } catch {
       // A source may replace/close a live image slot between frames. Chrome
       // and text remain valid; the next source update supplies the next frame.
@@ -978,12 +1040,41 @@ export function paintThumbnail(
   ctx.fillStyle = entry.thumbnailTitleColor || WORLD_OVERLAY_STYLE.title;
   ctx.font = entry.thumbnailTitleFont || WORLD_OVERLAY_STYLE.fontTitle;
   if (title && titleH > 0) {
+    const label =
+      titleChars > 0
+        ? entry.thumbnailTitleWordBoundary
+          ? truncateOverlayTitle(title, titleChars)
+          : title.slice(0, titleChars)
+        : title;
     ctx.fillText(
-      titleChars > 0 ? title.slice(0, titleChars) : title,
+      entry.thumbnailFixedWidth === true
+        ? fitThumbnailText(
+            ctx,
+            label,
+            ctx.font,
+            thumbW,
+            entry.thumbnailTitleWordBoundary,
+          )
+        : label,
       imageX,
       imageY + thumbH + titleH - 3,
     );
   }
+  if (details.length) {
+    ctx.fillStyle = WORLD_OVERLAY_STYLE.detail;
+    ctx.font = WORLD_OVERLAY_STYLE.fontDetail;
+    const lineH = Number.isFinite(layout.lineH) ? layout.lineH : 13;
+    const titleGap = Number.isFinite(layout.titleGap) ? layout.titleGap : 0;
+    for (let i = 0; i < details.length; i++) {
+      ctx.fillText(
+        entry.thumbnailFixedWidth === true
+          ? fitThumbnailText(ctx, details[i], ctx.font, thumbW)
+          : details[i],
+        imageX,
+        imageY + thumbH + titleGap + titleH + (i + 1) * lineH - 3,
+      );
+    }
+  }
   ctx.restore();
   return placement.rect;
 }
@@ -1125,8 +1216,6 @@ export function paintOverlayEntry(
     return paintTacticalCard(ctx, entry, placement, alpha);
   if (entry.variant === 'tracked')
     return paintTracked(ctx, entry, placement, alpha);
-  if (entry.selected || entry.variant === 'selected')
-    return paintSelected(ctx, entry, placement, alpha);
   if (entry.variant === 'thumbnail') {
     return paintThumbnail(
       ctx,
@@ -1137,6 +1226,8 @@ export function paintOverlayEntry(
       contentAlpha,
     );
   }
+  if (entry.selected || entry.variant === 'selected')
+    return paintSelected(ctx, entry, placement, alpha);
   if (entry.variant === 'card') {
     return paintCard(
       ctx,
diff --git a/src/overlays/worldOverlayDraw.test.mjs b/src/overlays/worldOverlayDraw.test.mjs
index 10ec8179d..f5d89f758 100644
--- a/src/overlays/worldOverlayDraw.test.mjs
+++ b/src/overlays/worldOverlayDraw.test.mjs
@@ -25,7 +25,11 @@ import {
   placementVariants,
   roundedRectPath,
 } from './worldOverlayDraw.js';
-import { createCctvThumbnailOverlayEntry, createFrameSlot } from '../data/cctvCards.js';
+import {
+  createCctvThumbnailOverlayEntry,
+  createFrameSlot,
+} from '../data/cctvCards.js';
+import { normalizeOverlayEntry } from './worldOverlay.js';
 import {
   CARD_PLATE_ALPHA,
   DETECTION_PLATE_BAND,
@@ -35,7 +39,9 @@ import {
 } from './worldOverlayTokens.js';
 
 function alphaOf(rgba) {
-  const match = /rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*([0-9.]+)\s*\)/.exec(String(rgba));
+  const match = /rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*([0-9.]+)\s*\)/.exec(
+    String(rgba),
+  );
   assert.ok(match, `expected an rgba() colour, got ${rgba}`);
   return Number(match[1]);
 }
@@ -48,28 +54,64 @@ function mockContext() {
     calls,
     font: '',
     globalAlpha: 1,
-    get strokeStyle() { return strokeStyle; },
-    set strokeStyle(value) { strokeStyle = value; calls.push(['strokeStyle', value]); },
-    get lineWidth() { return lineWidth; },
-    set lineWidth(value) { lineWidth = value; calls.push(['lineWidth', value]); },
+    get strokeStyle() {
+      return strokeStyle;
+    },
+    set strokeStyle(value) {
+      strokeStyle = value;
+      calls.push(['strokeStyle', value]);
+    },
+    get lineWidth() {
+      return lineWidth;
+    },
+    set lineWidth(value) {
+      lineWidth = value;
+      calls.push(['lineWidth', value]);
+    },
     measureCount: 0,
     measureText(text) {
       this.measureCount++;
       return { width: String(text).length * 6 };
     },
-    save() { calls.push(['save']); },
-    restore() { calls.push(['restore']); },
-    beginPath() { calls.push(['beginPath']); },
-    roundRect(...args) { calls.push(['roundRect', ...args]); },
-    moveTo(...args) { calls.push(['moveTo', ...args]); },
-    lineTo(...args) { calls.push(['lineTo', ...args]); },
-    arcTo(...args) { calls.push(['arcTo', ...args]); },
-    closePath() { calls.push(['closePath']); },
-    fill() { calls.push(['fill']); },
-    stroke() { calls.push(['stroke']); },
-    fillRect(...args) { calls.push(['fillRect', ...args]); },
-    fillText(...args) { calls.push(['fillText', ...args]); },
-    drawImage(...args) { calls.push(['drawImage', ...args]); },
+    save() {
+      calls.push(['save']);
+    },
+    restore() {
+      calls.push(['restore']);
+    },
+    beginPath() {
+      calls.push(['beginPath']);
+    },
+    roundRect(...args) {
+      calls.push(['roundRect', ...args]);
+    },
+    moveTo(...args) {
+      calls.push(['moveTo', ...args]);
+    },
+    lineTo(...args) {
+      calls.push(['lineTo', ...args]);
+    },
+    arcTo(...args) {
+      calls.push(['arcTo', ...args]);
+    },
+    closePath() {
+      calls.push(['closePath']);
+    },
+    fill() {
+      calls.push(['fill']);
+    },
+    stroke() {
+      calls.push(['stroke']);
+    },
+    fillRect(...args) {
+      calls.push(['fillRect', ...args]);
+    },
+    fillText(...args) {
+      calls.push(['fillText', ...args]);
+    },
+    drawImage(...args) {
+      calls.push(['drawImage', ...args]);
+    },
   };
 }
 
@@ -85,14 +127,17 @@ test('every detection theme carries a callout plate inside the ambient band', ()
     const plate = alphaOf(theme.calloutPlate);
     const space = alphaOf(theme.calloutPlateSpace);
     assert.ok(
-      plate >= DETECTION_PLATE_BAND.min * CARD_PLATE_ALPHA
-        && plate <= DETECTION_PLATE_BAND.max * CARD_PLATE_ALPHA,
+      plate >= DETECTION_PLATE_BAND.min * CARD_PLATE_ALPHA &&
+        plate <= DETECTION_PLATE_BAND.max * CARD_PLATE_ALPHA,
       `${name} callout plate ${plate} outside the ambient band`,
     );
     // The owner's spec: satellites read over the lit Earth disc, so the space
     // tier pops slightly harder — but never as heavy as the tracked card.
     assert.ok(space > plate, `${name} space plate must exceed the base plate`);
-    assert.ok(space < CARD_PLATE_ALPHA, `${name} space plate must stay under the card`);
+    assert.ok(
+      space < CARD_PLATE_ALPHA,
+      `${name} space plate must stay under the card`,
+    );
     // The scanline wash is a separate token and must not have been repurposed.
     assert.notEqual(theme.calloutPlate, theme.labelBg);
   }
@@ -100,47 +145,78 @@ test('every detection theme carries a callout plate inside the ambient band', ()
 
 test('an ambient detection callout paints its backing plate under its text', () => {
   const ctx = mockContext();
-  paintDetectionCallout(ctx, {
-    x: 20, y: 30, w: 80, h: 18,
-    primaryX: 27, microX: 70, baseline: 42,
-    leadFromX: 60, leadFromY: 60, leadToX: 60, leadToY: 48,
-    plate: 'rgba(2, 18, 26, 0.52)',
-    accent: '#22e0ff',
-    label: 'rgba(200, 250, 255, 0.97)',
-    primary: 'JA23NF',
-    micro: 'FL017',
-    font: '10px JetBrains Mono, monospace',
-    microFont: '9px JetBrains Mono, monospace',
-  }, 1);
+  paintDetectionCallout(
+    ctx,
+    {
+      x: 20,
+      y: 30,
+      w: 80,
+      h: 18,
+      primaryX: 27,
+      microX: 70,
+      baseline: 42,
+      leadFromX: 60,
+      leadFromY: 60,
+      leadToX: 60,
+      leadToY: 48,
+      plate: 'rgba(2, 18, 26, 0.52)',
+      accent: '#22e0ff',
+      label: 'rgba(200, 250, 255, 0.97)',
+      primary: 'JA23NF',
+      micro: 'FL017',
+      font: '10px JetBrains Mono, monospace',
+      microFont: '9px JetBrains Mono, monospace',
+    },
+    1,
+  );
 
   const names = ctx.calls.map(([name]) => name);
   const firstFill = names.indexOf('fill');
   const firstText = names.indexOf('fillText');
   assert.ok(firstFill >= 0, 'the callout must fill a backing plate');
-  assert.ok(firstText > firstFill, 'the plate must be painted before the callsign');
+  assert.ok(
+    firstText > firstFill,
+    'the plate must be painted before the callsign',
+  );
   // Plate geometry: a rounded rect covering the whole measured label box.
   assert.deepEqual(
     ctx.calls.find(([name]) => name === 'roundRect'),
     ['roundRect', 20, 30, 80, 18, 3],
   );
-  assert.ok(ctx.calls.some(([name, text]) => name === 'fillText' && text === 'JA23NF'));
-  assert.ok(ctx.calls.some(([name, text]) => name === 'fillText' && text === 'FL017'));
+  assert.ok(
+    ctx.calls.some(([name, text]) => name === 'fillText' && text === 'JA23NF'),
+  );
+  assert.ok(
+    ctx.calls.some(([name, text]) => name === 'fillText' && text === 'FL017'),
+  );
 });
 
 test('a callout with no micro-field paints one text run and still gets a plate', () => {
   const ctx = mockContext();
-  paintDetectionCallout(ctx, {
-    x: 0, y: 0, w: 40, h: 18,
-    primaryX: 7, microX: 30, baseline: 12,
-    leadFromX: 20, leadFromY: 30, leadToX: 20, leadToY: 18,
-    plate: 'rgba(2, 18, 26, 0.52)',
-    accent: '#22e0ff',
-    label: '#fff',
-    primary: 'N12345',
-    micro: '',
-    font: '10px mono',
-    microFont: '9px mono',
-  }, 0.5);
+  paintDetectionCallout(
+    ctx,
+    {
+      x: 0,
+      y: 0,
+      w: 40,
+      h: 18,
+      primaryX: 7,
+      microX: 30,
+      baseline: 12,
+      leadFromX: 20,
+      leadFromY: 30,
+      leadToX: 20,
+      leadToY: 18,
+      plate: 'rgba(2, 18, 26, 0.52)',
+      accent: '#22e0ff',
+      label: '#fff',
+      primary: 'N12345',
+      micro: '',
+      font: '10px mono',
+      microFont: '9px mono',
+    },
+    0.5,
+  );
 
   assert.ok(ctx.calls.some(([name]) => name === 'fill'));
   assert.equal(ctx.calls.filter(([name]) => name === 'fillText').length, 1);
@@ -167,7 +243,7 @@ test('distance scale matches the legacy infrastructure NearFarScalar curve', ()
   assert.equal(distanceScale(1_000_000, null), 1);
 });
 
-test('altitude scale preserves CCTV\'s exact smoothstep and linear waypoints', () => {
+test("altitude scale preserves CCTV's exact smoothstep and linear waypoints", () => {
   const curve = {
     fullEnd: 1800,
     midEnd: 6000,
@@ -185,13 +261,16 @@ test('altitude scale preserves CCTV\'s exact smoothstep and linear waypoints', (
 });
 
 test('the five-channel alpha chain is multiplicative and clamps inputs', () => {
-  assert.equal(combinedOverlayAlpha({
-    sourceAlpha: 0.5,
-    temporalFade: 0.8,
-    distanceFade: 0.5,
-    altitudeFade: 0.5,
-    keyholeEdgeFade: 0.25,
-  }), 0.025);
+  assert.equal(
+    combinedOverlayAlpha({
+      sourceAlpha: 0.5,
+      temporalFade: 0.8,
+      distanceFade: 0.5,
+      altitudeFade: 0.5,
+      keyholeEdgeFade: 0.25,
+    }),
+    0.025,
+  );
   assert.equal(combinedOverlayAlpha({ sourceAlpha: 2, temporalFade: -1 }), 0);
 });
 
@@ -205,7 +284,10 @@ test('placement variants flip below near the top and stay viewport-clamped', ()
     viewportHeight: 100,
     gap: 10,
   });
-  assert.deepEqual(nearTop.map((item) => item.corner), ['below', 'above', 'right', 'left']);
+  assert.deepEqual(
+    nearTop.map((item) => item.corner),
+    ['below', 'above', 'right', 'left'],
+  );
   for (const placement of nearTop) {
     assert.ok(placement.rect.x >= 4);
     assert.ok(placement.rect.y >= 4);
@@ -213,14 +295,20 @@ test('placement variants flip below near the top and stay viewport-clamped', ()
     assert.ok(placement.rect.y + placement.rect.h <= 96);
   }
   const reused = nearTop.slice();
-  assert.equal(placementVariants({
-    anchorX: 100,
-    anchorY: 80,
-    width: 40,
-    height: 20,
-    viewportWidth: 200,
-    viewportHeight: 100,
-  }, reused), reused);
+  assert.equal(
+    placementVariants(
+      {
+        anchorX: 100,
+        anchorY: 80,
+        width: 40,
+        height: 20,
+        viewportWidth: 200,
+        viewportHeight: 100,
+      },
+      reused,
+    ),
+    reused,
+  );
   assert.equal(reused[0].corner, 'above');
 });
 
@@ -236,10 +324,16 @@ test('tactical cards retain vertical-only placement and sprite-edge leaders', ()
     leaderOffset: 14,
     verticalOnly: true,
   });
-  assert.deepEqual(placements.map(({ corner }) => corner), ['above', 'below']);
+  assert.deepEqual(
+    placements.map(({ corner }) => corner),
+    ['above', 'below'],
+  );
   assert.equal(placements[0].leadFromY, 80);
   assert.equal(placements[0].leaderOffset, -14);
-  assert.equal(placements[0].leadToY, placements[0].rect.y + placements[0].rect.h);
+  assert.equal(
+    placements[0].leadToY,
+    placements[0].rect.y + placements[0].rect.h,
+  );
 });
 
 test('edge-clamped CCTV placements keep leaders vertical unless the anchor is outside the card', () => {
@@ -254,7 +348,11 @@ test('edge-clamped CCTV placements keep leaders vertical unless the anchor is ou
     leaderOffset: 16,
     verticalOnly: true,
   })[0];
-  assert.equal(edgeClamped.rect.x, 4, 'card is horizontally clamped at the viewport edge');
+  assert.equal(
+    edgeClamped.rect.x,
+    4,
+    'card is horizontally clamped at the viewport edge',
+  );
   assert.equal(edgeClamped.leadFromX, 20);
   assert.equal(edgeClamped.leadToX, 20, 'leader stays strictly vertical at sx');
 
@@ -277,8 +375,11 @@ test('edge-clamped CCTV placements keep leaders vertical unless the anchor is ou
   // camera". Vertical always, even when the card has been clamped sideways off
   // its anchor.
   assert.equal(offRectAnchor.leadFromX, 2);
-  assert.equal(offRectAnchor.leadToX, 2,
-    'an off-rect anchor keeps the leader vertical rather than slanting it to the card');
+  assert.equal(
+    offRectAnchor.leadToX,
+    2,
+    'an off-rect anchor keeps the leader vertical rather than slanting it to the card',
+  );
 });
 
 test('rounded rectangles use native support and retain a fallback path', () => {
@@ -334,7 +435,8 @@ test('text measurement cache is font-aware and font hooks follow host lifetime',
 test('text measurement cache caps LRU retention at 1024 entries', () => {
   clearWorldOverlayTextMeasureCache();
   const ctx = mockContext();
-  for (let i = 0; i < 1100; i++) measureWorldOverlayText(ctx, `label-${i}`, '10px mono');
+  for (let i = 0; i < 1100; i++)
+    measureWorldOverlayText(ctx, `label-${i}`, '10px mono');
   assert.equal(getWorldOverlayTextMeasureCacheSize(), 1024);
   const measured = ctx.measureCount;
   measureWorldOverlayText(ctx, 'label-0', '10px mono');
@@ -355,10 +457,28 @@ test('variant measurement and all six painters remain renderer-local', () => {
     thumbnailWidth: 96,
     thumbnailHeight: 54,
   };
-  const variants = ['label', 'track', 'card', 'thumbnail', 'selected', 'tracked'];
-  const painters = [paintLabel, paintTrack, paintCard, paintThumbnail, paintSelected, paintTracked];
+  const variants = [
+    'label',
+    'track',
+    'card',
+    'thumbnail',
+    'selected',
+    'tracked',
+  ];
+  const painters = [
+    paintLabel,
+    paintTrack,
+    paintCard,
+    paintThumbnail,
+    paintSelected,
+    paintTracked,
+  ];
   for (let i = 0; i < variants.length; i++) {
-    const variantEntry = { ...entry, variant: variants[i], selected: variants[i] === 'selected' };
+    const variantEntry = {
+      ...entry,
+      variant: variants[i],
+      selected: variants[i] === 'selected',
+    };
     const layout = measureOverlayEntry(ctx, variantEntry, {});
     variantEntry._overlayLayout = layout;
     const placement = placementVariants({
@@ -369,18 +489,27 @@ test('variant measurement and all six painters remain renderer-local', () => {
       viewportWidth: 400,
       viewportHeight: 300,
     })[0];
-    assert.equal(painters[i](ctx, variantEntry, placement, 0.5), placement.rect);
+    assert.equal(
+      painters[i](ctx, variantEntry, placement, 0.5),
+      placement.rect,
+    );
   }
   assert.ok(ctx.calls.some(([name]) => name === 'drawImage'));
-  assert.ok(ctx.calls.filter(([name]) => name === 'fillText').length >= variants.length);
-  const trackLayout = measureOverlayEntry(ctx, { ...entry, variant: 'track' }, {});
+  assert.ok(
+    ctx.calls.filter(([name]) => name === 'fillText').length >= variants.length,
+  );
+  const trackLayout = measureOverlayEntry(
+    ctx,
+    { ...entry, variant: 'track' },
+    {},
+  );
   assert.ok(trackLayout.w >= 'CAMERA 12 · LIVE'.length * 6);
 });
 
 test('thumbnail painter preserves the shipped CCTV 104x77 geometry and drawing coordinates', () => {
   const ctx = mockContext();
   const frameSlot = createFrameSlot();
-  frameSlot.frame = { width: 192, height: 108 };
+  frameSlot.frame = { width: 192, height: 144 };
   frameSlot.stamp = 123;
   const entry = createCctvThumbnailOverlayEntry({
     id: 'cam-a',
@@ -411,7 +540,10 @@ test('thumbnail painter preserves the shipped CCTV 104x77 geometry and drawing c
     ['strokeStyle', 'rgba(107, 232, 255, 0.6)'],
     'CCTV leader uses the source cyan token rather than the generic leader fallback',
   );
-  assert.deepEqual(ctx.calls.find(([name]) => name === 'moveTo'), ['moveTo', 200, 184]);
+  assert.deepEqual(
+    ctx.calls.find(([name]) => name === 'moveTo'),
+    ['moveTo', 200, 184],
+  );
   assert.deepEqual(
     ctx.calls.find(([name]) => name === 'drawImage'),
     ['drawImage', frameSlot.frame, 152, 105, 96, 54],
@@ -422,6 +554,69 @@ test('thumbnail painter preserves the shipped CCTV 104x77 geometry and drawing c
   );
 });
 
+test('photo thumbnails letterbox square images and visibly paint attribution and disclaimers', () => {
+  const ctx = mockContext();
+  const entry = {
+    ...createCctvThumbnailOverlayEntry({
+      id: 'photo',
+      position: { x: 1, y: 2, z: 3 },
+      title: 'Synthetic bird',
+      frameSlot: { frame: { width: 75, height: 75 } },
+    }),
+    thumbnailHeight: 72,
+    thumbnailFit: 'contain',
+    details: ['Photo: Synthetic photographer · CC BY', 'Not a census'],
+  };
+  entry._overlayLayout = measureOverlayEntry(ctx, entry, {});
+  const { w, h, lineH } = entry._overlayLayout;
+  assert.equal(w, 104, 'canvas photos keep the compact image width');
+  assert.equal(h, 4 + 72 + 2 + 13 + 2 * lineH + 4);
+  const placement = { rect: { x: 10, y: 20, w, h } };
+  paintThumbnail(ctx, entry, placement);
+  assert.deepEqual(
+    ctx.calls.find(([name]) => name === 'drawImage'),
+    ['drawImage', entry.image.frame, 26, 24, 72, 72],
+  );
+  for (const detail of entry.details)
+    assert.ok(
+      ctx.calls.some(([name, text]) => name === 'fillText' && text === detail),
+      detail,
+    );
+});
+
+test('fixed-width photo thumbnails truncate the title and creator inside the 96px image width', () => {
+  const ctx = mockContext();
+  const entry = normalizeOverlayEntry('compact-photos', {
+    ...createCctvThumbnailOverlayEntry({
+      id: 'compact-photo',
+      position: { x: 1, y: 2, z: 3 },
+      title: 'A long synthetic organism name',
+      frameSlot: { frame: { width: 75, height: 75 } },
+    }),
+    thumbnailHeight: 72,
+    thumbnailFixedWidth: true,
+    details: ['© A very long synthetic photographer name'],
+  });
+  entry._overlayLayout = measureOverlayEntry(ctx, entry, {});
+  const { w, h, lineH } = entry._overlayLayout;
+  assert.equal(w, 104, '96px image plus the shared 4px padding on each side');
+  assert.equal(h, 4 + 72 + 2 + 13 + lineH + 4, 'exactly one creator line');
+  const placement = { rect: { x: 10, y: 20, w, h } };
+  paintThumbnail(ctx, entry, placement);
+  const text = ctx.calls.filter(([name]) => name === 'fillText');
+  assert.equal(text.length, 2);
+  assert.equal(
+    text[0][1],
+    'A LONG SYNTHETI',
+    'the shared title character limit remains active',
+  );
+  assert.equal(text[1][1], '© A very long s…');
+  for (const [, label, x] of text) {
+    assert.equal(x, 14);
+    assert.ok(ctx.measureText(label).width <= 96, label);
+  }
+});
+
 test('tracked painter preserves centered multi-line readout metrics', () => {
   const ctx = mockContext();
   const entry = {
@@ -482,15 +677,24 @@ test('shared tactical painter preserves FIRMS card metrics and top-rule treatmen
     verticalOnly: true,
   })[0];
   assert.equal(paintTacticalCard(ctx, entry, placement, 0.5), placement.rect);
-  assert.deepEqual(ctx.calls.find(([name]) => name === 'moveTo'), ['moveTo', 200, 146]);
-  assert.equal(ctx.calls.filter(([name]) => name === 'stroke').length, 2, 'leader + selected border');
+  assert.deepEqual(
+    ctx.calls.find(([name]) => name === 'moveTo'),
+    ['moveTo', 200, 146],
+  );
+  assert.equal(
+    ctx.calls.filter(([name]) => name === 'stroke').length,
+    2,
+    'leader + selected border',
+  );
   assert.equal(ctx.calls.filter(([name]) => name === 'fillText').length, 3);
   assert.equal(ctx.calls.at(-1)[0], 'restore');
 });
 
 test('selected elbow leader reveals from the glyph before its card fades in', () => {
   const animation = {
-    leaderAnimationMs: 1000, leaderAnimationStartedAt: 100, leaderDrawRatio: 0.7,
+    leaderAnimationMs: 1000,
+    leaderAnimationStartedAt: 100,
+    leaderDrawRatio: 0.7,
   };
   assert.equal(leaderRevealProgress(animation, 100), 0);
   assert.ok(leaderRevealProgress(animation, 450) > 0.8);
@@ -500,20 +704,44 @@ test('selected elbow leader reveals from the glyph before its card fades in', ()
   assert.equal(tacticalCardRevealAlpha(animation, 1100), 1);
   const ctx = mockContext();
   const entry = {
-    variant: 'selected', selected: true, cardStyle: 'tactical', title: 'ALPR-2516',
-    details: ['OSM MAPPED'], accent: '#ff6474', leaderStyle: 'elbow',
-    leaderAnimationMs: 1, leaderAnimationStartedAt: 0,
+    variant: 'selected',
+    selected: true,
+    cardStyle: 'tactical',
+    title: 'ALPR-2516',
+    details: ['OSM MAPPED'],
+    accent: '#ff6474',
+    leaderStyle: 'elbow',
+    leaderAnimationMs: 1,
+    leaderAnimationStartedAt: 0,
   };
   entry._overlayLayout = measureOverlayEntry(ctx, entry, {});
   const placement = placementVariants({
-    anchorX: 240, anchorY: 180, width: entry._overlayLayout.w, height: entry._overlayLayout.h,
-    viewportWidth: 500, viewportHeight: 300, gap: 20, leaderOffset: 30, verticalOnly: true,
+    anchorX: 240,
+    anchorY: 180,
+    width: entry._overlayLayout.w,
+    height: entry._overlayLayout.h,
+    viewportWidth: 500,
+    viewportHeight: 300,
+    gap: 20,
+    leaderOffset: 30,
+    verticalOnly: true,
   })[0];
   paintTacticalCard(ctx, entry, placement, 1);
-  assert.deepEqual(ctx.calls.find(([name]) => name === 'moveTo'), ['moveTo', 210, 180]);
+  assert.deepEqual(
+    ctx.calls.find(([name]) => name === 'moveTo'),
+    ['moveTo', 210, 180],
+  );
   const lines = ctx.calls.filter(([name]) => name === 'lineTo');
-  assert.ok(lines.length >= 2, 'leader draws horizontally from the glyph, then vertically to the card');
-  assert.ok(ctx.calls.some(([name, value]) => name === 'strokeStyle' && value === 'rgba(255, 100, 116, 0.95)'));
+  assert.ok(
+    lines.length >= 2,
+    'leader draws horizontally from the glyph, then vertically to the card',
+  );
+  assert.ok(
+    ctx.calls.some(
+      ([name, value]) =>
+        name === 'strokeStyle' && value === 'rgba(255, 100, 116, 0.95)',
+    ),
+  );
 });
 
 test('track display text is cached across measure and paint and invalidates on content change', () => {
@@ -558,16 +786,33 @@ function alphaProbe() {
   const ctx = mockContext();
   const alphas = { fill: [], text: [], stroke: [] };
   const inner = { fill: ctx.fill, fillText: ctx.fillText, stroke: ctx.stroke };
-  ctx.fill = function fill(...args) { alphas.fill.push(this.globalAlpha); return inner.fill.apply(this, args); };
-  ctx.fillText = function fillText(...args) { alphas.text.push(this.globalAlpha); return inner.fillText.apply(this, args); };
-  ctx.stroke = function stroke(...args) { alphas.stroke.push(this.globalAlpha); return inner.stroke.apply(this, args); };
+  ctx.fill = function fill(...args) {
+    alphas.fill.push(this.globalAlpha);
+    return inner.fill.apply(this, args);
+  };
+  ctx.fillText = function fillText(...args) {
+    alphas.text.push(this.globalAlpha);
+    return inner.fillText.apply(this, args);
+  };
+  ctx.stroke = function stroke(...args) {
+    alphas.stroke.push(this.globalAlpha);
+    return inner.stroke.apply(this, args);
+  };
   return { ctx, alphas };
 }
 
 const CALLOUT_FIXTURE = Object.freeze({
-  x: 20, y: 30, w: 80, h: 18,
-  primaryX: 27, microX: 70, baseline: 42,
-  leadFromX: 60, leadFromY: 60, leadToX: 60, leadToY: 48,
+  x: 20,
+  y: 30,
+  w: 80,
+  h: 18,
+  primaryX: 27,
+  microX: 70,
+  baseline: 42,
+  leadFromX: 60,
+  leadFromY: 60,
+  leadToX: 60,
+  leadToY: 48,
   plate: 'rgba(2, 18, 26, 0.52)',
   accent: '#22e0ff',
   label: 'rgba(200, 250, 255, 0.97)',
@@ -585,20 +830,36 @@ test('a sky-backed callout feathers its PLATE and nothing else', () => {
   const ground = alphaProbe();
   paintDetectionCallout(ground.ctx, { ...CALLOUT_FIXTURE, plateScale: 1 }, 0.8);
   const sky = alphaProbe();
-  paintDetectionCallout(sky.ctx, { ...CALLOUT_FIXTURE, plateScale: SKY_PLATE_SCALE }, 0.8);
+  paintDetectionCallout(
+    sky.ctx,
+    { ...CALLOUT_FIXTURE, plateScale: SKY_PLATE_SCALE },
+    0.8,
+  );
 
   // The plate is the FIRST fill; the tier accent bar is the second.
-  assert.ok(Math.abs(ground.alphas.fill[0] - 0.8) < 1e-12, 'ground keeps the full plate');
+  assert.ok(
+    Math.abs(ground.alphas.fill[0] - 0.8) < 1e-12,
+    'ground keeps the full plate',
+  );
   assert.ok(
     Math.abs(sky.alphas.fill[0] - 0.8 * SKY_PLATE_SCALE) < 1e-12,
     'sky scales the plate by the token, not by some other number',
   );
   assert.deepEqual(
-    sky.alphas.fill.slice(1), ground.alphas.fill.slice(1),
+    sky.alphas.fill.slice(1),
+    ground.alphas.fill.slice(1),
     'the accent bar must not inherit the plate feather',
   );
-  assert.deepEqual(sky.alphas.text, ground.alphas.text, 'text opacity is untouched');
-  assert.deepEqual(sky.alphas.stroke, ground.alphas.stroke, 'the leader is untouched');
+  assert.deepEqual(
+    sky.alphas.text,
+    ground.alphas.text,
+    'text opacity is untouched',
+  );
+  assert.deepEqual(
+    sky.alphas.stroke,
+    ground.alphas.stroke,
+    'the leader is untouched',
+  );
   // Same fill token in both: the theme's plate hue is scaled, never swapped.
   assert.equal(
     sky.ctx.calls.find(([name]) => name === 'fillStyle')?.[1],
@@ -622,7 +883,12 @@ test('the sky plate scale is a whisper, not a second plate', () => {
   assert.ok(SKY_PLATE_SCALE > 0 && SKY_PLATE_SCALE <= 0.35);
   // Against the lightest shipped plate this must resolve to near-invisible.
   const lightest = Math.min(
-    ...Object.values(DETECTION_THEME_MAP).map((theme) => alphaOf(theme.calloutPlate)),
+    ...Object.values(DETECTION_THEME_MAP).map((theme) =>
+      alphaOf(theme.calloutPlate),
+    ),
+  );
+  assert.ok(
+    lightest * SKY_PLATE_SCALE < 0.12,
+    'the feathered plate must read as bare text',
   );
-  assert.ok(lightest * SKY_PLATE_SCALE < 0.12, 'the feathered plate must read as bare text');
 });
diff --git a/src/perfTestRunner.test.mjs b/src/perfTestRunner.test.mjs
new file mode 100644
index 000000000..a7ab99648
--- /dev/null
+++ b/src/perfTestRunner.test.mjs
@@ -0,0 +1,81 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import {
+  discoverPerfTestFiles,
+  perfBudgetTestOptions,
+  perfTestArgs,
+  runPerfTests,
+} from '../scripts/run-perf-tests.mjs';
+
+test('timing assertions are skipped with an actionable message unless explicitly enabled', () => {
+  for (const env of [
+    {},
+    { GEV_PERF_BUDGETS: '0' },
+    { GEV_PERF_BUDGETS: 'true' },
+  ])
+    assert.match(
+      perfBudgetTestOptions(env).skip,
+      /Timing budgets are opt-in; run npm run test:perf/,
+    );
+  assert.deepEqual(perfBudgetTestOptions({ GEV_PERF_BUDGETS: '1' }), {
+    skip: false,
+  });
+});
+
+test('test:perf discovers every benchmark and enables timing budgets in a serial process', (t) => {
+  const root = mkdtempSync(path.join(tmpdir(), 'gev-perf-runner-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const expected = [
+    'server/providers/example/provider.perf.test.mjs',
+    'src/layers/anotherLayer/model.perf.test.mjs',
+    'src/layers/wildlifeSightings/model.perf.test.mjs',
+  ];
+  for (const file of [
+    ...expected,
+    'src/layers/anotherLayer/functional.test.mjs',
+  ]) {
+    mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
+    writeFileSync(path.join(root, file), '');
+  }
+  assert.deepEqual(discoverPerfTestFiles(root), expected);
+  const calls = [];
+  const run = (...args) => {
+    calls.push(args);
+    return { status: 7 };
+  };
+  assert.equal(
+    runPerfTests({
+      root,
+      env: { GEV_PERF_BUDGETS: '0', SENTINEL: 'kept' },
+      run,
+    }),
+    7,
+  );
+  assert.equal(calls.length, 1);
+  const [command, args, options] = calls[0];
+  assert.equal(command, process.execPath);
+  assert.deepEqual(args, perfTestArgs(expected));
+  assert.ok(args.includes('--test-concurrency=1'));
+  assert.ok(args.includes('--test-isolation=none'));
+  assert.equal(options.cwd, root);
+  assert.equal(options.env.GEV_PERF_BUDGETS, '1');
+  assert.equal(options.env.SENTINEL, 'kept');
+  assert.throws(
+    () =>
+      runPerfTests({ root, run: () => ({ error: new Error('spawn failed') }) }),
+    /spawn failed/,
+  );
+  const pkg = JSON.parse(
+    readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+  );
+  assert.equal(pkg.scripts['test:perf'], 'node scripts/run-perf-tests.mjs');
+});
diff --git a/src/share/viewCodec.js b/src/share/viewCodec.js
index 8ac00f51b..f54ff23d8 100644
--- a/src/share/viewCodec.js
+++ b/src/share/viewCodec.js
@@ -297,6 +297,7 @@ export const SHARE_VIEW_LAYER_OPTION_ABSENT = Object.freeze({
     sinceDays: 0,
   }),
   radio: Object.freeze({ filter: 'all', volume: 0.8 }),
+  'wildlife-sightings': Object.freeze({ confirmed: false, taxa: 'all' }),
 });
 
 /** The frozen meaning of an omitted option; unlisted options are always written. */
diff --git a/src/sources/rateLimit.js b/src/sources/rateLimit.js
index 7c6094cf6..09356eb93 100644
--- a/src/sources/rateLimit.js
+++ b/src/sources/rateLimit.js
@@ -1,21 +1,26 @@
 /** Bounded per-key and aggregate request admission. */
 const RATE_LIMITER_MAX_KEYS = 2000;
 
-export function makeRateLimiter({ windowMs, max, globalMax }) {
+export function makeRateLimiter({
+  windowMs,
+  max,
+  globalMax,
+  now = () => Date.now(),
+}) {
   const hits = new Map(); // key -> number[] (timestamps within window)
   let globalTimes = []; // all hits in window, for the global backstop
   return function allow(key) {
-    const now = Date.now();
-    globalTimes = globalTimes.filter((t) => now - t < windowMs);
+    const at = now();
+    globalTimes = globalTimes.filter((t) => at - t < windowMs);
     if (globalMax && globalTimes.length >= globalMax) return false; // global backstop
-    const recent = (hits.get(key) || []).filter((t) => now - t < windowMs);
+    const recent = (hits.get(key) || []).filter((t) => at - t < windowMs);
     if (recent.length >= max) {
       hits.set(key, recent);
       return false;
     }
-    recent.push(now);
+    recent.push(at);
     hits.set(key, recent);
-    globalTimes.push(now);
+    globalTimes.push(at);
     // Hard key cap so a key-rotating caller can't grow the map without bound.
     if (hits.size > RATE_LIMITER_MAX_KEYS) {
       const oldest = hits.keys().next().value;
@@ -23,7 +28,7 @@ export function makeRateLimiter({ windowMs, max, globalMax }) {
     }
     if (hits.size > 256) {
       for (const [k, v] of hits) {
-        if (!v.length || now - v[v.length - 1] > windowMs) hits.delete(k);
+        if (!v.length || at - v[v.length - 1] > windowMs) hits.delete(k);
       }
     }
     return true;
diff --git a/src/sources/rateLimit.test.mjs b/src/sources/rateLimit.test.mjs
new file mode 100644
index 000000000..eb2ce46c5
--- /dev/null
+++ b/src/sources/rateLimit.test.mjs
@@ -0,0 +1,23 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { makeRateLimiter } from './rateLimit.js';
+
+test('injected time drives per-client and global rolling limits', () => {
+  let at = 1000;
+  const allow = makeRateLimiter({
+    windowMs: 60_000,
+    max: 2,
+    globalMax: 3,
+    now: () => at,
+  });
+  assert.equal(allow('a'), true);
+  assert.equal(allow('a'), true);
+  assert.equal(allow('a'), false);
+  assert.equal(allow('b'), true);
+  assert.equal(allow('c'), false);
+  at += 59_999;
+  assert.equal(allow('a'), false);
+  at += 1;
+  assert.equal(allow('a'), true);
+  assert.equal(allow('c'), true);
+});
diff --git a/src/sources/reference.js b/src/sources/reference.js
index 95ad89d8a..53f22ff67 100644
--- a/src/sources/reference.js
+++ b/src/sources/reference.js
@@ -4,6 +4,7 @@ import { createWfigsPerimeterSource } from '../layers/perimeters/source.js';
 import { createDroneAirspaceSource } from '../layers/droneAirspace/source.js';
 import { createBundledCableSource } from '../layers/submarineCables/bundledSource.js';
 import { createAdsbGnssSource } from '../layers/gnss/source.js';
+import { createWildlifeSightingsSource } from '../layers/wildlifeSightings/source.js';
 
 /** Construct the existing reference feeds independently of application setup. */
 export function createReferenceSources() {
@@ -12,6 +13,7 @@ export function createReferenceSources() {
     'air-quality': createEcccAirQualitySource(),
     'fire-perimeters': createWfigsPerimeterSource(),
     'drone-airspace': createDroneAirspaceSource(),
+    'wildlife-sightings': createWildlifeSightingsSource(),
     cables: createBundledCableSource(),
     'gnss-integrity': createAdsbGnssSource(),
   };
diff --git a/src/sources/reference.test.mjs b/src/sources/reference.test.mjs
index da129f539..130c915d2 100644
--- a/src/sources/reference.test.mjs
+++ b/src/sources/reference.test.mjs
@@ -17,6 +17,7 @@ test('reference factories retain compatibility without starting acquisition or s
     'air-quality',
     'fire-perimeters',
     'drone-airspace',
+    'wildlife-sightings',
     'cables',
     'gnss-integrity',
   ]);
@@ -24,12 +25,14 @@ test('reference factories retain compatibility without starting acquisition or s
   assert.notEqual(first['air-quality'], second['air-quality']);
   assert.notEqual(first['fire-perimeters'], second['fire-perimeters']);
   assert.notEqual(first['drone-airspace'], second['drone-airspace']);
+  assert.notEqual(first['wildlife-sightings'], second['wildlife-sightings']);
   assert.notEqual(first.cables, second.cables);
   assert.notEqual(first['gnss-integrity'], second['gnss-integrity']);
   assert.equal(typeof first.earthquakes.getSnapshot, 'function');
   assert.equal(typeof first['air-quality'].getSnapshot, 'function');
   assert.equal(typeof first['fire-perimeters'].getSnapshot, 'function');
   assert.equal(typeof first['drone-airspace'].getSnapshot, 'function');
+  assert.equal(typeof first['wildlife-sightings'].getSnapshot, 'function');
   assert.equal(typeof first.cables.fetch, 'function');
   assert.equal(typeof first['gnss-integrity'].getSnapshot, 'function');
   assert.equal(requests, 0);
diff --git a/src/testSupport/wildlifeBillboardModel.mjs b/src/testSupport/wildlifeBillboardModel.mjs
new file mode 100644
index 000000000..78e0e5ed2
--- /dev/null
+++ b/src/testSupport/wildlifeBillboardModel.mjs
@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import { createWildlifeBillboardModel } from '../layers/wildlifeSightings/billboardModel.js';
+import { buildWildlifeIconModel } from '../layers/wildlifeSightings/model.js';
+
+export const WILDLIFE_BENCHMARK_REFRESHES = 10;
+const ICONICS = ['Aves', 'Mammalia', 'Reptilia', 'Plantae', 'Unknown'];
+
+export function syntheticRows(n) {
+  return Array.from({ length: n }, (_, i) => ({
+    stableId: `synthetic:${i}`,
+    lat: -60 + (i % 1000) * 0.12,
+    lon: -179 + (i % 2000) * 0.179,
+    iconic: ICONICS[i % ICONICS.length],
+    quality: 'research',
+    count: null,
+    obscured: false,
+    cell: null,
+  }));
+}
+
+export function harness() {
+  const points = new Set();
+  const counters = { created: 0, destroyed: 0, writes: 0, positions: 0 };
+  const collection = {
+    add(options) {
+      const point = new Proxy(
+        { show: true, ...options },
+        {
+          set(target, key, value) {
+            counters.writes += 1;
+            target[key] = value;
+            return true;
+          },
+        },
+      );
+      points.add(point);
+      counters.created += 1;
+      return point;
+    },
+    remove(point) {
+      assert.equal(points.delete(point), true);
+      counters.destroyed += 1;
+    },
+    removeAll() {
+      throw new Error('A refresh must never clear the billboard collection');
+    },
+  };
+  const appearance = new Map(
+    ICONICS.map((iconic) => [
+      iconic,
+      {
+        image: `cached:${iconic}`,
+        color: iconic,
+        scale: 1,
+      },
+    ]),
+  );
+  const pointById = new Map();
+  const model = createWildlifeBillboardModel({
+    collection,
+    pointById,
+    positions: new Map(),
+    positionForRow(row) {
+      counters.positions += 1;
+      return { x: row.lon, y: row.lat };
+    },
+    appearanceForGroup: (group) => appearance.get(group),
+  });
+  const apply = (rows) => {
+    const population = buildWildlifeIconModel({ rows });
+    return model.update(population.rows);
+  };
+  return { apply, counters, model, pointById, points };
+}
+
+export function changePositions(rows, refresh) {
+  return rows.map((row, i) =>
+    i % 10 === 0
+      ? { ...row, lat: row.lat + (refresh % 2 ? 0.001 : -0.001) }
+      : row,
+  );
+}
diff --git a/src/tooling/previewServing.test.mjs b/src/tooling/previewServing.test.mjs
index 1b9232566..daaf78386 100644
--- a/src/tooling/previewServing.test.mjs
+++ b/src/tooling/previewServing.test.mjs
@@ -16,6 +16,8 @@ test('data providers have both hooks; credential editing stays development-only'
   assert.ok(plugins.some(({ name }) => name === 'gnss-integrity'));
   assert.ok(plugins.some(({ name }) => name === 'ghostmaps'));
   assert.ok(plugins.some(({ name }) => name === 'drone-airspace'));
+  assert.ok(plugins.some(({ name }) => name === 'inaturalist'));
+  assert.ok(plugins.some(({ name }) => name === 'acartia'));
   for (const plugin of plugins) {
     if (plugin.name === 'gev-key-setup') {
       assert.equal(plugin.configurePreviewServer, undefined);
@@ -114,6 +116,8 @@ test('real dev and built-preview servers serve provider JSON and terminate unkno
         ['/api/fire-perimeters/inciweb/publication/invalid', 400],
         ['/api/gnss-integrity?lat=invalid', 400],
         ['/api/ghostmaps/unknown', 404],
+        ['/api/inaturalist/unknown', 404],
+        ['/api/acartia/unknown', 404],
         ['/api/terrain/heights?points=invalid', 400],
         ['/api/overpass', 405],
         ['/api/overpass/status', 200],
diff --git a/src/tooling/transitQa.test.mjs b/src/tooling/transitQa.test.mjs
index a879eac5c..0b4af4a16 100644
--- a/src/tooling/transitQa.test.mjs
+++ b/src/tooling/transitQa.test.mjs
@@ -695,7 +695,7 @@ test('public transit documentation uses courtesy attribution and the approved gr
   );
   assert.ok(
     readme.includes(
-      'Twenty-one layers and map sources. **Nineteen have a keyless path.**',
+      'Twenty-two layers and map sources. **Twenty have a keyless path.**',
     ),
   );
   assert.ok(
diff --git a/src/ui/applicationShell.js b/src/ui/applicationShell.js
index c3ad27c14..ac921b34b 100644
--- a/src/ui/applicationShell.js
+++ b/src/ui/applicationShell.js
@@ -17,6 +17,7 @@ import { CockpitCoordinator } from './cockpitCoordinator.js';
 import { ContextControls } from './context.js';
 import { CctvControls } from './cctv.js';
 import { StreetLevelControls } from './streetLevelControls.js';
+import { createWildlifeSightingCard } from './wildlifeSightingCard.js';
 import { RadioControls } from './radio.js';
 import { LocalSdrControls } from './localSdrControls.js';
 import { LocationNavigation } from './locationNavigation.js';
@@ -589,6 +590,7 @@ export class StyleManager extends ShellFacade {
     this._initRadioPanel();
     this._initCctvPanel();
     this._initStreetLevelPanel();
+    this._initWildlifeSightingCard();
     this._initGlobalContextPanel();
     this._initLocationBar();
     this._initMobileShell();
@@ -1073,6 +1075,19 @@ export class StyleManager extends ShellFacade {
     return this._runExplicitNavigation('camera', () => focus(cameraId));
   }
 
+  /** Keep one compact card anchored to the selected wildlife sighting. */
+  _initWildlifeSightingCard() {
+    this._wildlifeSightingCard?.destroy();
+    this._wildlifeSightingCard = null;
+    const layer = this.services.wildlifeSightingsLayer;
+    if (!layer) return;
+    this._wildlifeSightingCard = createWildlifeSightingCard({
+      layer,
+      ui: this._ui,
+      viewer: this.viewer,
+    });
+  }
+
   /** Compose the Street Level panel controls from its layer and application actions. */
   _initStreetLevelPanel() {
     const { streetLevelLayer } = this.services;
@@ -1791,6 +1806,7 @@ export class StyleManager extends ShellFacade {
     this._recording.destroy();
     this._mobileShell?.destroy();
     this._panelNavigation?.destroy();
+    this._wildlifeSightingCard?.destroy();
     this._ui.destroy();
     this._panelChrome.destroy();
     this._feedback.destroy();
diff --git a/src/ui/layerNames.js b/src/ui/layerNames.js
index 694d57066..bba7f96f7 100644
--- a/src/ui/layerNames.js
+++ b/src/ui/layerNames.js
@@ -36,6 +36,7 @@ export const LAYER_NAME_KEYS = Object.freeze({
   'fire-perimeters': msg('Fire Perimeters'),
   'gnss-integrity': msg('GNSS Integrity'),
   'drone-airspace': msg('Prohibited & Restricted Airspace'),
+  'wildlife-sightings': msg('Wildlife Sightings'),
   's2-ghostmaps': msg('S2 GhostMaps'),
   wind: msg('Wind'),
   'weather-radar': msg('Rain radar'),
diff --git a/src/ui/layerPanel.js b/src/ui/layerPanel.js
index b24e8be7b..30e4ec16b 100644
--- a/src/ui/layerPanel.js
+++ b/src/ui/layerPanel.js
@@ -80,6 +80,10 @@ const PANEL_GROUPS = [
       's2-ghostmaps',
     ],
   },
+  {
+    label: msg('Wildlife'),
+    ids: ['wildlife-sightings'],
+  },
   {
     label: msg('Weather'),
     ids: [
diff --git a/src/ui/layerPanel.test.mjs b/src/ui/layerPanel.test.mjs
index 73710e3fc..a87b3abd4 100644
--- a/src/ui/layerPanel.test.mjs
+++ b/src/ui/layerPanel.test.mjs
@@ -34,6 +34,27 @@ test('panel presentation places Transit between Street Traffic and Bike Share in
   assert.equal(order.filter(({ id }) => id === 'transit').length, 1);
 });
 
+test('Wildlife follows Events and precedes Weather', () => {
+  const source = readFileSync(
+    new URL('./layerPanel.js', import.meta.url),
+    'utf8',
+  );
+  const declarations = source.slice(
+    source.indexOf('const PANEL_GROUPS ='),
+    source.indexOf('const PANEL_POSITIONS ='),
+  );
+  const order = JSON.parse(
+    runInNewContext(
+      `const msg = (text) => text;\n${declarations}\nJSON.stringify(PANEL_ORDER)`,
+    ),
+  );
+  const wildlife = order.findIndex(({ id }) => id === 'wildlife-sightings');
+  assert.equal(order[wildlife].label, 'Wildlife');
+  assert.equal(order[wildlife - 1].id, 's2-ghostmaps');
+  assert.equal(order[wildlife + 1].id, 'air-quality');
+  assert.equal(order.filter(({ id }) => id === 'wildlife-sightings').length, 1);
+});
+
 test('partial feed controls distinguish incomplete records from stale data and outages', async () => {
   const { LayerPanel, layerFeedState, presentLayerToggle } =
     await import('./layerPanel.js');
diff --git a/src/ui/styles/cyber.css b/src/ui/styles/cyber.css
index 4957cd769..4aaf5b1c2 100644
--- a/src/ui/styles/cyber.css
+++ b/src/ui/styles/cyber.css
@@ -716,6 +716,11 @@
   .data-icon::before {
   content: '⌁';
 }
+:root[data-ui-theme='cyber']
+  .data-toggle-row[data-layer-id='wildlife-sightings']
+  .data-icon::before {
+  content: '✿';
+}
 :root[data-ui-theme='cyber']
   .data-toggle-row[data-layer-id='radio']
   .data-icon::before {
@@ -1693,7 +1698,9 @@
   :root[data-ui-theme='cyber']
     body:not(.cockpit-mode)
     #left-panel-stack:has(> [data-panel-id]:not(.collapsed))
-    > :is(#data-panel, #cctv-panel, #utilities-panel, #scene-panel):not(.collapsed) {
+    > :is(#data-panel, #cctv-panel, #utilities-panel, #scene-panel):not(
+      .collapsed
+    ) {
     flex: 1 1 auto;
     height: auto;
     max-height: none;
diff --git a/src/ui/views/panels/WildlifeSightingCard.vue b/src/ui/views/panels/WildlifeSightingCard.vue
new file mode 100644
index 000000000..fc92c7ee4
--- /dev/null
+++ b/src/ui/views/panels/WildlifeSightingCard.vue
@@ -0,0 +1,131 @@
+<script setup>
+import { computed, shallowRef, useTemplateRef, watch } from 'vue';
+import { formatDate, t, translateKnown } from '../../../i18n/index.js';
+import { photoCreator, formatAge } from '../../../layers/wildlifeSightings/photoText.js';
+import { inatLicenceLabel, inatPhotoUrl, isOpenPhoto } from '../../../layers/wildlifeSightings/records.js';
+
+const props = defineProps({
+  sighting: { type: Object, required: true },
+  nowMs: { type: Number, required: true },
+  taxa: { type: String, default: 'all' },
+});
+const emit = defineEmits(['close', 'resize']);
+const acartia = computed(() => props.sighting.origin === 'acartia');
+const name = computed(() => translateKnown(props.sighting.commonName || props.sighting.scientificName) || t('SIGHTING'));
+const scientificName = computed(() => translateKnown(props.sighting.scientificName || ''));
+const photo = computed(() => {
+  const row = props.sighting;
+  if (row.obscured || acartia.value || !isOpenPhoto(row.photo)) return null;
+  const src = inatPhotoUrl(row.photo.square ?? row.photo.url, 'medium');
+  const creator = photoCreator(row.photo);
+  return src && creator ? { src, creator, licence: inatLicenceLabel(row.photo.license_code ?? row.photo.licence) } : null;
+});
+const observedDay = computed(() => {
+  const row = props.sighting;
+  const day = row.observedOn || (!row.obscured && Number.isFinite(row.observedAt) ? new Date(row.observedAt).toISOString().slice(0, 10) : '');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return '';
+  const date = new Date(`${day}T00:00:00Z`);
+  return Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === day ? day : '';
+});
+const age = computed(() => {
+  const row = props.sighting;
+  const delta = props.nowMs - row.observedAt;
+  if (row.obscured || !Number.isFinite(row.observedAt) || delta >= 30 * 86_400_000) return '';
+  const compact = formatAge(Math.max(0, delta));
+  return acartia.value ? t('seen {age} ago', { age: compact }) : t('observed {age} ago', { age: compact });
+});
+const observedDate = computed(() => observedDay.value ? formatDate(Date.parse(`${observedDay.value}T00:00:00Z`), { year: 'numeric', month: 'short', day: 'numeric', timeZone: 'UTC' }) : '');
+const link = computed(() => {
+  try {
+    const url = new URL(props.sighting.link);
+    return url.protocol === 'https:' && !url.username && !url.password ? url.href : null;
+  } catch { return null; }
+});
+const providerCredit = computed(() => {
+  if (!acartia.value) return '';
+  const { name = '', entity = '' } = props.sighting.provider || {};
+  return entity ? t('Reported by {name} ({entity})', { name, entity }) : t('Reported by {name}', { name });
+});
+const actionLabel = computed(() => acartia.value ? t('Open {name} on Acartia', { name: name.value }) : t('Open {name} on iNaturalist', { name: name.value }));
+const photoImage = useTemplateRef('photoImage');
+const loaded = shallowRef(false);
+const failed = shallowRef(false);
+const currentImage = (image) => image === photoImage.value && image?.dataset.sightingId === props.sighting.stableId && image?.getAttribute('src') === photo.value?.src;
+async function onPhotoLoad(event) {
+  const image = event.currentTarget;
+  // Ignore late decodes after a different observation replaces this photo.
+  try { await image.decode?.(); } catch { /* onload is sufficient on older engines */ }
+  if (!currentImage(image)) return;
+  loaded.value = true;
+  emit('resize');
+}
+function fail(event) {
+  if (!currentImage(event.currentTarget)) return;
+  failed.value = true;
+  emit('resize');
+}
+watch([() => props.sighting.stableId, () => photo.value?.src], () => { loaded.value = false; failed.value = false; }, { flush: 'sync' });
+</script>
+
+<template>
+  <section class="wildlife-sighting-card" data-wildlife-sighting-card tabindex="-1" :aria-label="name" @keydown.stop @keyup.stop>
+    <button type="button" class="wildlife-sighting-card-close" :aria-label="t('Close sighting')" @click="emit('close')">×</button>
+    <component :is="link ? 'a' : 'div'" class="wildlife-sighting-card-content" :href="link || undefined" :target="link ? '_blank' : undefined" :rel="link ? 'noopener noreferrer' : undefined" :aria-label="link ? actionLabel : undefined">
+      <div v-if="photo" class="wildlife-sighting-card-photo" :aria-busy="!loaded && !failed">
+        <p v-if="!loaded && !failed" role="status">{{ t('Loading photo...') }}</p>
+        <p v-if="failed" role="status">{{ t('Photo unavailable') }}</p>
+        <img v-show="!failed" ref="photoImage" :key="sighting.stableId + photo.src" :data-sighting-id="sighting.stableId" :src="photo.src" :alt="t('Photo of {name}', { name })" referrerpolicy="no-referrer" :class="{ loaded }" @load="onPhotoLoad" @error="fail" />
+      </div>
+      <div class="wildlife-sighting-card-caption">
+        <h2>{{ name }}</h2>
+        <p v-if="scientificName && scientificName !== name"><i>{{ scientificName }}</i></p>
+        <p v-if="age || observedDay"><time :datetime="observedDay || undefined">{{ age || observedDate }}</time></p>
+        <p v-if="sighting.obscured">{{ t('Location obscured to a 0.2° cell') }}</p>
+        <!-- i18n-ignore: creator and licence are provider attribution, copied verbatim -->
+        <p v-if="photo" class="wildlife-sighting-card-credit">© {{ photo.creator }} · {{ photo.licence }}</p>
+        <p v-if="providerCredit" class="wildlife-sighting-card-credit">{{ providerCredit }}</p>
+        <p v-if="acartia" class="wildlife-sighting-card-credit">{{ t('Acartia') }} · {{ t('CC BY 4.0') }} · {{ t('Salish Sea') }}</p>
+        <p v-if="link" class="wildlife-sighting-card-source">{{ acartia ? t('Acartia') : t('iNaturalist') }} ↗</p>
+      </div>
+    </component>
+    <p v-if="acartia || taxa === 'whales'" class="wildlife-sighting-card-guidance">
+      <a v-if="acartia && !/^https:\/\/acartia\.io\/?$/.test(link || '')" href="https://acartia.io" target="_blank" rel="noopener noreferrer">{{ t('Open on Acartia ↗') }}</a>
+      <a href="https://www.bewhalewise.org" target="_blank" rel="noopener noreferrer">{{ t('Be Whale Wise') }}</a>
+    </p>
+  </section>
+</template>
+
+<style scoped>
+.wildlife-sighting-card {
+  position: relative;
+  box-sizing: border-box;
+  width: 100%;
+  max-height: inherit;
+  overflow: auto;
+  padding: 8px;
+  border: 1px solid var(--glass-border-hover);
+  border-radius: var(--btn-radius);
+  background: var(--menu-bg);
+  color: var(--text-primary);
+  font: 11px/1.4 var(--font-mono);
+  box-shadow: 0 3px 16px rgb(0 0 0 / 30%);
+}
+.wildlife-sighting-card-content { display: block; color: inherit; text-decoration: none; }
+.wildlife-sighting-card-content:focus-visible { outline: 2px solid var(--text-primary); outline-offset: 3px; }
+/* Script focus starts inside the card; tab focus still outlines its controls. */
+.wildlife-sighting-card:focus-visible { outline: none !important; }
+.wildlife-sighting-card-close { position: absolute; z-index: 1; inset-block-start: 4px; inset-inline-end: 4px; width: 24px; height: 24px; padding: 0; border: 0; border-radius: var(--btn-radius); background: transparent; color: inherit; font: 20px/1 var(--font-sans); cursor: pointer; }
+.wildlife-sighting-card-close:hover { background: var(--menu-bg); }
+.wildlife-sighting-card-close:focus-visible { outline: 2px solid var(--text-primary); outline-offset: 2px; }
+.wildlife-sighting-card-photo { position: relative; width: 100%; height: 180px; }
+.wildlife-sighting-card-photo > p { position: absolute; inset: 0; display: grid; place-items: center; margin: 0; }
+.wildlife-sighting-card-photo > img { display: block; width: 100%; height: 100%; object-fit: contain; opacity: 0; }
+.wildlife-sighting-card-photo > img.loaded { opacity: 1; }
+.wildlife-sighting-card-caption { padding-top: 6px; overflow-wrap: anywhere; }
+.wildlife-sighting-card-caption h2, .wildlife-sighting-card-caption p { margin: 0 0 3px; }
+.wildlife-sighting-card-caption h2 { padding-inline-end: 20px; font: inherit; font-weight: 700; }
+.wildlife-sighting-card-credit { color: var(--text-secondary); }
+.wildlife-sighting-card-guidance { display: flex; flex-wrap: wrap; gap: 4px 12px; margin: 4px 0 0; color: var(--text-secondary); }
+.wildlife-sighting-card-guidance a { color: inherit; }
+.wildlife-sighting-card-source { text-decoration: underline; text-underline-offset: 2px; }
+</style>
diff --git a/src/ui/wildlifeSightingCard.js b/src/ui/wildlifeSightingCard.js
new file mode 100644
index 000000000..390aedc47
--- /dev/null
+++ b/src/ui/wildlifeSightingCard.js
@@ -0,0 +1,270 @@
+import { h, nextTick, shallowRef } from 'vue';
+import WildlifeSightingCard from './views/panels/WildlifeSightingCard.vue';
+import {
+  panWildlifeSighting,
+  placeWildlifeSightingCard,
+  projectWildlifeSighting,
+  readWildlifeCardSafeArea,
+  WILDLIFE_SELECTED_CARD_WIDTH,
+  WILDLIFE_CARD_CHROME_SELECTORS,
+} from './wildlifeSightingPlacement.js';
+
+/** Anchor the selected sighting's photo and source link clear of map chrome. */
+export function createWildlifeSightingCard({
+  layer,
+  ui,
+  viewer = null,
+  documentRef = globalThis.document,
+  windowRef = globalThis.window,
+  now = () => Date.now(),
+  project = projectWildlifeSighting,
+  pan = panWildlifeSighting,
+}) {
+  const selected = shallowRef(null);
+  const host = documentRef.createElement('div');
+  host.dataset.wildlifeSightingCardHost = '';
+  Object.assign(host.style, {
+    position: 'fixed',
+    zIndex: '89',
+    display: 'none',
+    width: `${WILDLIFE_SELECTED_CARD_WIDTH}px`,
+  });
+  documentRef.body.append(host);
+  let destroyed = false;
+  let moving = false;
+  let removeFrame = null;
+  let returnFocus = null;
+  let panForId = null;
+  const removers = [];
+  const observed = new Set();
+  const resizeObserver = windowRef?.ResizeObserver
+    ? new windowRef.ResizeObserver(() => position())
+    : null;
+  const mutationObserver = windowRef?.MutationObserver
+    ? new windowRef.MutationObserver(() => position())
+    : null;
+
+  const chromeSelector = WILDLIFE_CARD_CHROME_SELECTORS.join(',');
+  const structureObserver = windowRef?.MutationObserver
+    ? new windowRef.MutationObserver((records) => {
+        if (destroyed || !selected.value) return;
+        const hasChromeChange = records.some((record) =>
+          [...record.addedNodes, ...record.removedNodes].some(
+            (node) =>
+              node.nodeType === 1 &&
+              !host.contains(node) &&
+              (node.matches(chromeSelector) ||
+                node.querySelector(chromeSelector)),
+          ),
+        );
+        if (!hasChromeChange) return;
+        // Newly mounted chrome can cover a previously clear anchor.
+        panForId = null;
+        position({ allowPan: true });
+      })
+    : null;
+
+  function observeLayout(elements) {
+    const next = new Set(
+      [host.firstElementChild, viewer?.scene?.canvas, ...elements].filter(
+        Boolean,
+      ),
+    );
+    let changed = false;
+    for (const element of observed) {
+      if (next.has(element)) continue;
+      resizeObserver?.unobserve(element);
+      observed.delete(element);
+      changed = true;
+    }
+    for (const element of next) {
+      if (observed.has(element)) continue;
+      observed.add(element);
+      resizeObserver?.observe(element);
+      changed = true;
+    }
+    if (!changed) return;
+    mutationObserver?.disconnect();
+    for (const element of observed) {
+      // Ignore HUD clock/text changes and the card's own positioning styles.
+      if (!host.contains(element))
+        mutationObserver?.observe(element, {
+          attributes: true,
+          attributeFilter: ['class', 'style', 'hidden'],
+        });
+    }
+  }
+
+  function position({ allowPan = false } = {}) {
+    if (destroyed || !selected.value || !host.firstElementChild) return;
+    const point = project(viewer, selected.value, layer);
+    if (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+      host.style.display = 'none';
+      return;
+    }
+    const safe = readWildlifeCardSafeArea({ documentRef, viewer, windowRef });
+    observeLayout(safe.elements);
+    host.style.width = `${Math.min(WILDLIFE_SELECTED_CARD_WIDTH, safe.bounds.width)}px`;
+    host.style.maxHeight = `${safe.bounds.height}px`;
+    host.style.display = 'block';
+    const rect = host.firstElementChild.getBoundingClientRect();
+    const result = placeWildlifeSightingCard(
+      point,
+      {
+        width:
+          rect.width ||
+          Math.min(WILDLIFE_SELECTED_CARD_WIDTH, safe.bounds.width),
+        height:
+          rect.height ||
+          (selected.value.photo &&
+          !selected.value.obscured &&
+          selected.value.origin !== 'acartia'
+            ? 300
+            : 132),
+      },
+      safe,
+    );
+    if (!result) {
+      host.style.display = 'none';
+      return;
+    }
+    if (
+      (result.pan.x || result.pan.y) &&
+      allowPan &&
+      panForId !== selected.value.stableId
+    ) {
+      panForId = selected.value.stableId;
+      const reduced =
+        windowRef?.matchMedia?.('(prefers-reduced-motion: reduce)').matches ===
+        true;
+      pan(viewer, point, result.anchor, reduced);
+    }
+    host.style.left = `${result.left}px`;
+    host.style.top = `${result.top}px`;
+    host.dataset.placement = result.placement;
+  }
+
+  const unmount = ui.mount(
+    {
+      setup: () => () =>
+        selected.value
+          ? h(WildlifeSightingCard, {
+              sighting: selected.value,
+              nowMs: now(),
+              taxa: layer.getParams?.()?.taxa,
+              onClose: () => {
+                if (!destroyed) layer.clearSightingSelection();
+              },
+              onResize: () => position(),
+            })
+          : null,
+    },
+    host,
+  );
+
+  function restoreFocus() {
+    if (returnFocus?.isConnected) returnFocus.focus?.({ preventScroll: true });
+    returnFocus = null;
+  }
+  const unsubscribe = layer.subscribeSelection((row, metadata) => {
+    if (destroyed) return;
+    const fresh = row?.stableId !== selected.value?.stableId;
+    if (row && !selected.value) {
+      returnFocus = documentRef.activeElement;
+      structureObserver?.observe(documentRef.body, {
+        childList: true,
+        subtree: true,
+      });
+    }
+    selected.value = row;
+    if (!row) {
+      host.style.display = 'none';
+      panForId = null;
+      removeFrame?.();
+      removeFrame = null;
+      resizeObserver?.disconnect();
+      mutationObserver?.disconnect();
+      structureObserver?.disconnect();
+      observed.clear();
+      restoreFocus();
+      return;
+    }
+    if (fresh) panForId = null;
+    nextTick(() => {
+      if (destroyed || !selected.value) return;
+      position({ allowPan: fresh || metadata?.explicitSelection === true });
+      if (moving) startFrameUpdates();
+      // Focus the container so keyboard navigation starts inside the card.
+      if (fresh)
+        host
+          .querySelector('[data-wildlife-sighting-card]')
+          ?.focus?.({ preventScroll: true });
+    });
+  });
+
+  const keydown = (event) => {
+    if (!selected.value || event.key !== 'Escape') return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    layer.clearSightingSelection();
+  };
+  const outside = (event) => {
+    if (!selected.value || host.contains(event.target)) return;
+    // The layer selects on pointer-up; its following click must keep the card open.
+    const canvas = viewer?.scene?.canvas;
+    if (canvas && (event.target === canvas || canvas.contains?.(event.target)))
+      return;
+    layer.clearSightingSelection();
+  };
+  documentRef.addEventListener('keydown', keydown, true);
+  documentRef.addEventListener('click', outside, true);
+  const onResize = () => position();
+  windowRef?.addEventListener('resize', onResize);
+
+  function listen(event, callback) {
+    const remove = event?.addEventListener?.(callback);
+    if (typeof remove === 'function') removers.push(remove);
+    else if (event?.removeEventListener)
+      removers.push(() => event.removeEventListener(callback));
+  }
+  function startFrameUpdates() {
+    if (!selected.value || removeFrame) return;
+    // Installed only for camera motion; an idle card has zero per-frame work.
+    removeFrame =
+      viewer?.scene?.preRender?.addEventListener?.(() => position()) || null;
+  }
+  listen(viewer?.camera?.moveStart, () => {
+    moving = true;
+    startFrameUpdates();
+  });
+  listen(viewer?.camera?.moveEnd, () => {
+    moving = false;
+    removeFrame?.();
+    removeFrame = null;
+    position();
+  });
+  listen(viewer?.camera?.changed, () => {
+    if (!moving) position();
+  });
+
+  return {
+    /** Release the card, selection subscription and placement listeners. */
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      unsubscribe?.();
+      for (const remove of removers) remove();
+      removeFrame?.();
+      resizeObserver?.disconnect();
+      mutationObserver?.disconnect();
+      structureObserver?.disconnect();
+      documentRef.removeEventListener('keydown', keydown, true);
+      documentRef.removeEventListener('click', outside, true);
+      windowRef?.removeEventListener('resize', onResize);
+      unmount();
+      host.remove();
+      selected.value = null;
+      restoreFocus();
+    },
+  };
+}
diff --git a/src/ui/wildlifeSightingCard.test.mjs b/src/ui/wildlifeSightingCard.test.mjs
new file mode 100644
index 000000000..d7837af7f
--- /dev/null
+++ b/src/ui/wildlifeSightingCard.test.mjs
@@ -0,0 +1,767 @@
+import '../testSupport/registerDom.mjs';
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { nextTick } from 'vue';
+import { readFileSync } from 'node:fs';
+import { getLocale, setLocale, t } from '../i18n/index.js';
+import { LOCALES } from '../i18n/locale.js';
+import { createSelection } from '../layers/wildlifeSightings/selection.js';
+import { buildWildlifeThumbnailEntry } from '../layers/wildlifeSightings/cards.js';
+import { createWildlifeSightingCard } from './wildlifeSightingCard.js';
+import {
+  panWildlifeSighting,
+  placeWildlifeSightingCard,
+  readWildlifeCardSafeArea,
+} from './wildlifeSightingPlacement.js';
+import { createUiRuntime } from './vueRuntime.js';
+import { PANEL_RAIL_ITEMS } from './panelRailCatalog.js';
+import { sheetForPanelId } from './mobileShell.js';
+
+const NOW = Date.parse('2026-11-04T13:00:00Z');
+const square =
+  'https://inaturalist-open-data.s3.amazonaws.com/photos/456/square.jpg';
+const row = {
+  stableId: 'inat:456',
+  origin: 'inaturalist',
+  lat: 0,
+  lon: 0,
+  commonName: 'Synthetic bird',
+  scientificName: 'Avis imaginaria',
+  iconic: 'Aves',
+  observedAt: NOW - 3_600_000,
+  observedOn: '2026-11-04',
+  obscured: false,
+  photo: {
+    square,
+    attribution: '(c) Synthetic Photographer, some rights reserved (CC BY-SA)',
+    licence: 'cc-by-sa',
+  },
+  link: 'https://www.inaturalist.org/observations/456',
+};
+const rect = (left, top, width, height) => ({
+  left,
+  top,
+  width,
+  height,
+  right: left + width,
+  bottom: top + height,
+});
+const events = () => {
+  const listeners = new Set();
+  return {
+    addEventListener(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    emit() {
+      for (const fn of listeners) fn();
+    },
+    size: () => listeners.size,
+  };
+};
+const settle = async () => {
+  await nextTick();
+  await Promise.resolve();
+  await nextTick();
+};
+
+// All scene rows, media events and rectangles are synthetic. Browser image
+// requests are disabled; decode resolution below proves the photo is exposed
+// only after it has loaded into the compact card.
+function fixture(
+  context,
+  initialRow = row,
+  point = { x: 600, y: 450 },
+  extraWindow = {},
+) {
+  document.body.replaceChildren();
+  const opener = document.body.appendChild(document.createElement('button'));
+  opener.textContent = 'Globe';
+  opener.focus();
+  const canvas = document.body.appendChild(document.createElement('canvas'));
+  canvas.getBoundingClientRect = () => rect(0, 0, 1200, 900);
+  const windowRef = {
+    innerWidth: 1200,
+    innerHeight: 900,
+    getComputedStyle: window.getComputedStyle.bind(window),
+    addEventListener() {},
+    removeEventListener() {},
+    matchMedia: () => ({ matches: false }),
+    ...extraWindow,
+  };
+  const ui = createUiRuntime();
+  const overlays = new Map();
+  const moveStart = events();
+  const moveEnd = events();
+  const changed = events();
+  const preRender = events();
+  const viewer = {
+    scene: { canvas, preRender, pick: () => picked },
+    camera: { moveStart, moveEnd, changed },
+  };
+  const state = {
+    enabled: true,
+    destroyed: false,
+    selectedId: null,
+    selectedRow: null,
+    ambientRows: [],
+    rowById: new Map([[initialRow.stableId, initialRow]]),
+    positions: new Map([[initialRow.stableId, { x: 1, y: 2, z: 3 }]]),
+    contextIds: new Set(),
+    viewer,
+  };
+  let picked = null;
+  let hit = null;
+  let onClick;
+  let clears = 0;
+  let staleListener;
+  const subscriptions = new Set();
+  const flights = [];
+  const pans = [];
+  const selection = createSelection({
+    state,
+    services: {
+      now: () => NOW,
+      cesium: { ScreenSpaceEventType: { LEFT_CLICK: 0 } },
+      overlayHost: {
+        setEntries: (id, entries) => overlays.set(id, entries),
+        hitTest: (_x, _y, { sourceId }) =>
+          hit?.sourceId === sourceId ? hit : null,
+      },
+      screenSpaceEventHandlerFactory: () => ({
+        setInputAction(fn) {
+          onClick = fn;
+        },
+        destroy() {},
+      }),
+      focus: { requestWorldFocus: (value) => flights.push(value) },
+    },
+    parts: {
+      rendering: { refreshSelection() {}, requestRender() {} },
+    },
+  });
+  const layer = {
+    getParams: () => ({ taxa: 'all' }),
+    subscribeSelection(listener) {
+      staleListener = listener;
+      subscriptions.add(listener);
+      const off = selection.subscribe(listener);
+      return () => {
+        subscriptions.delete(listener);
+        off();
+      };
+    },
+    clearSightingSelection() {
+      clears++;
+      selection.clearAndRebuild();
+    },
+  };
+  let currentPoint = point;
+  let projections = 0;
+  const card = createWildlifeSightingCard({
+    layer,
+    ui,
+    viewer,
+    documentRef: document,
+    windowRef,
+    now: () => NOW,
+    project: () => {
+      projections++;
+      return currentPoint;
+    },
+    pan: (_viewer, from, to, reduced) => {
+      pans.push({ from, to, reduced });
+      currentPoint = to;
+      return true;
+    },
+  });
+  selection.install();
+  context.after(() => {
+    card.destroy();
+    selection.destroy();
+    ui.destroy();
+  });
+  return {
+    state,
+    selection,
+    layer,
+    card,
+    viewer,
+    windowRef,
+    overlays,
+    flights,
+    pans,
+    projections: () => projections,
+    subscriptions,
+    opener,
+    canvas,
+    moveStart,
+    moveEnd,
+    preRender,
+    cardElement: () => document.querySelector('[data-wildlife-sighting-card]'),
+    host: () => document.querySelector('[data-wildlife-sighting-card-host]'),
+    staleListener: () => staleListener,
+    clears: () => clears,
+    async click(kind = 'dot', target = initialRow) {
+      picked =
+        kind === 'icon'
+          ? { primitive: { id: `wildlife:${target.stableId}` } }
+          : { id: `wildlife:${target.stableId}` };
+      hit =
+        kind === 'ambient photo card'
+          ? {
+              sourceId: 'wildlife-sightings',
+              entry: buildWildlifeThumbnailEntry(target, NOW, {
+                select: selection.selectAndFocus,
+              }),
+            }
+          : null;
+      onClick({ position: { x: 50, y: 50 } });
+      await settle();
+    },
+    async publish(next) {
+      if (next) {
+        state.rowById.set(next.stableId, next);
+        if (state.selectedId === next.stableId) state.selectedRow = next;
+      }
+      selection.notify();
+      await settle();
+    },
+    obstacle(selector, bounds) {
+      const element = document.body.appendChild(document.createElement('div'));
+      if (selector.startsWith('#')) element.id = selector.slice(1);
+      else element.className = selector.slice(1);
+      element.getBoundingClientRect = () => bounds;
+      return element;
+    },
+    setPoint(next) {
+      currentPoint = next;
+    },
+  };
+}
+
+test('dot, icon and ambient photo clicks open one contained medium-photo card at the sighting', async (context) => {
+  for (const kind of ['dot', 'icon', 'ambient photo card'])
+    await context.test(kind, async (context) => {
+      const f = fixture(context);
+      await f.click(kind);
+      const card = f.cardElement();
+      const image = card.querySelector('img');
+      assert.equal(f.state.selectedId, row.stableId);
+      assert.equal(
+        document.querySelector('dialog'),
+        null,
+        'there is no fullscreen or modal dialog',
+      );
+      assert.equal(image.src, square.replace('/square.', '/medium.'));
+      assert.equal(image.referrerPolicy, 'no-referrer');
+      assert.equal(card.querySelector('h2').textContent, row.commonName);
+      assert.equal(card.querySelector('i').textContent, row.scientificName);
+      assert.equal(card.querySelector('time').textContent, 'observed 1h ago');
+      assert.ok(
+        card.textContent.includes('© Synthetic Photographer · CC BY-SA'),
+      );
+      const link = card.querySelector('a');
+      assert.equal(link.href, row.link);
+      assert.equal(link.target, '_blank');
+      assert.equal(link.rel, 'noopener noreferrer');
+      assert.equal(
+        link.getAttribute('aria-label'),
+        `Open ${row.commonName} on iNaturalist`,
+      );
+      assert.equal(
+        link.querySelector('.wildlife-sighting-card-source').textContent,
+        'iNaturalist ↗',
+      );
+      assert.ok(
+        link.contains(image),
+        'the photograph and text are one external action',
+      );
+      assert.equal(f.flights.length, 1);
+      assert.equal(f.flights[0].kind, 'sighting');
+      assert.deepEqual(
+        f.flights[0].position,
+        f.state.positions.get(row.stableId),
+      );
+      assert.equal(f.pans.length, 0);
+      assert.equal(
+        f.preRender.size(),
+        0,
+        'an idle card installs no frame work',
+      );
+      let decoded;
+      image.decode = () =>
+        new Promise((resolve) => {
+          decoded = resolve;
+        });
+      image.dispatchEvent(new Event('load'));
+      await settle();
+      assert.equal(
+        image.classList.contains('loaded'),
+        false,
+        'a request alone does not expose an empty frame',
+      );
+      decoded();
+      await settle();
+      assert.equal(
+        image.classList.contains('loaded'),
+        true,
+        'the loaded medium photo is painted inside the card',
+      );
+      assert.equal(card.querySelector('[role=status]'), null);
+      const style = readFileSync(
+        new URL('./views/panels/WildlifeSightingCard.vue', import.meta.url),
+        'utf8',
+      );
+      assert.match(style, /object-fit: contain/);
+      assert.match(style, /height: 180px/);
+    });
+});
+
+test('missing, restricted, obscured and Acartia photos all use the same compact text card', async (context) => {
+  for (const [label, extra] of [
+    ['missing', { photo: null }],
+    ['restricted', { photo: { ...row.photo, licence: 'cc-by-nd' } }],
+    [
+      'untrusted',
+      { photo: { ...row.photo, square: 'https://other.example/square.jpg' } },
+    ],
+    ['uncredited', { photo: { ...row.photo, attribution: '' } }],
+    ['obscured', { obscured: true }],
+    [
+      'Acartia',
+      {
+        origin: 'acartia',
+        stableId: 'acartia:456',
+        provider: { name: 'Synthetic network' },
+        link: 'https://acartia.io',
+      },
+    ],
+  ])
+    await context.test(label, async (context) => {
+      const f = fixture(context, { ...row, ...extra });
+      await f.click();
+      const card = f.cardElement();
+      assert.equal(card.querySelector('img'), null);
+      assert.equal(card.querySelector('[role=status]'), null);
+      assert.equal(card.querySelector('h2').textContent, row.commonName);
+      assert.equal(card.querySelector('i').textContent, row.scientificName);
+      assert.equal(document.querySelector('dialog'), null);
+      if (extra.obscured) {
+        assert.doesNotMatch(card.textContent, /ago|Photographer/);
+        assert.ok(
+          card.textContent.includes('Location obscured to a 0.2° cell'),
+        );
+        assert.equal(
+          card.querySelector('time').getAttribute('datetime'),
+          row.observedOn,
+        );
+      }
+      if (extra.origin === 'acartia') {
+        assert.ok(card.textContent.includes('seen 1h ago'));
+        assert.ok(card.textContent.includes('Reported by Synthetic network'));
+        assert.ok(
+          card.textContent.includes('Acartia · CC BY 4.0 · Salish Sea'),
+        );
+        assert.ok(card.querySelector('a[href="https://www.bewhalewise.org"]'));
+        assert.equal(
+          card.querySelector('a').getAttribute('aria-label'),
+          `Open ${row.commonName} on Acartia`,
+        );
+      }
+    });
+});
+
+test('safe placements near each viewport edge exclude actual HUD, toolbar and rail rects', () => {
+  const obstacles = [
+    rect(0, 0, 260, 160),
+    rect(450, 0, 300, 80),
+    rect(1050, 200, 150, 500),
+    rect(0, 760, 300, 140),
+  ];
+  const safe = { bounds: rect(6, 6, 1188, 888), obstacles };
+  for (const point of [
+    { x: 7, y: 450 },
+    { x: 1193, y: 750 },
+    { x: 850, y: 7 },
+    { x: 600, y: 893 },
+  ]) {
+    const result = placeWildlifeSightingCard(
+      point,
+      { width: 258, height: 300 },
+      safe,
+    );
+    assert.ok(result);
+    assert.deepEqual(result.pan, { x: 0, y: 0 });
+    assert.ok(
+      result.left >= safe.bounds.left && result.right <= safe.bounds.right,
+    );
+    assert.ok(
+      result.top >= safe.bounds.top && result.bottom <= safe.bounds.bottom,
+    );
+    assert.ok(
+      obstacles.every(
+        (r) =>
+          !(
+            result.left < r.right &&
+            result.right > r.left &&
+            result.top < r.bottom &&
+            result.bottom > r.top
+          ),
+      ),
+    );
+  }
+});
+
+test('a selected dot flies to its true position and its card pans clear of chrome', async (context) => {
+  const f = fixture(context, row, { x: 100, y: 100 });
+  const hud = f.obstacle('.hud-top-left', rect(0, 0, 260, 160));
+  f.obstacle('#right-context-rail', rect(1040, 200, 160, 700));
+  f.windowRef.matchMedia = () => ({ matches: true });
+  await f.click();
+  assert.equal(f.pans.length, 1);
+  assert.equal(f.pans[0].reduced, true);
+  assert.deepEqual(
+    f.pans[0].to,
+    { x: 100, y: 178 },
+    'nearest clear point follows the measured HUD bottom',
+  );
+  const safe = readWildlifeCardSafeArea({
+    documentRef: document,
+    viewer: f.viewer,
+    windowRef: f.windowRef,
+  });
+  assert.equal(
+    safe.obstacles[0].bottom,
+    hud.getBoundingClientRect().bottom + 6,
+  );
+  assert.equal(f.flights.length, 1);
+  assert.deepEqual(f.flights[0].position, f.state.positions.get(row.stableId));
+  f.moveEnd.emit();
+  await settle();
+  assert.equal(f.pans.length, 1);
+  f.layer.clearSightingSelection();
+  await settle();
+  f.setPoint({ x: -20, y: 400 });
+  await f.click();
+  assert.equal(f.pans.length, 2);
+  assert.deepEqual(f.pans[1].to, { x: 18, y: 400 });
+});
+
+test('the camera correction preserves altitude and orientation and honors reduced motion', () => {
+  const flights = [];
+  const camera = {
+    positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 250_000),
+    positionCartographic: { height: 250_000 },
+    heading: 0.2,
+    pitch: -1.2,
+    roll: 0.1,
+    pickEllipsoid: (p) => Cesium.Cartesian3.fromDegrees(p.x / 100, p.y / 100),
+    flyTo: (value) => flights.push(value),
+  };
+  const viewer = {
+    camera,
+    scene: {
+      canvas: { getBoundingClientRect: () => rect(0, 0, 1200, 900) },
+      globe: { ellipsoid: Cesium.Ellipsoid.WGS84 },
+    },
+  };
+  for (const reduced of [false, true]) {
+    assert.equal(
+      panWildlifeSighting(viewer, { x: 10, y: 10 }, { x: 30, y: 50 }, reduced),
+      true,
+    );
+    const flight = flights.at(-1);
+    assert.ok(
+      Math.abs(
+        Cesium.Cartographic.fromCartesian(flight.destination).height - 250_000,
+      ) < 0.001,
+    );
+    assert.deepEqual(flight.orientation, {
+      heading: 0.2,
+      pitch: -1.2,
+      roll: 0.1,
+    });
+    assert.equal(flight.duration, reduced ? 0 : 0.22);
+  }
+});
+
+test('the browser click that follows a globe selection does not close the card it opened', async (context) => {
+  const f = fixture(context);
+  await f.click();
+  assert.ok(f.cardElement(), 'the globe click opened the card');
+  assert.equal(
+    document.activeElement,
+    f.cardElement(),
+    'focus lands on the card, not as a ring on its close button',
+  );
+  // Cesium selects on pointer-up; the DOM click event lands on the canvas
+  // afterwards and must not count as an outside click.
+  f.canvas.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+  await settle();
+  assert.ok(f.cardElement(), 'the card stays open');
+  assert.equal(f.clears(), 0);
+  document.body.click();
+  await settle();
+  assert.equal(f.cardElement(), null, 'a real outside click still closes it');
+});
+
+test('one card at a time, Escape, outside clicks and close all clear the selection', async (context) => {
+  const f = fixture(context);
+  await f.click();
+  const second = {
+    ...row,
+    stableId: 'inat:789',
+    commonName: 'Another synthetic bird',
+  };
+  f.state.rowById.set(second.stableId, second);
+  await f.click('dot', second);
+  assert.equal(
+    document.querySelectorAll('[data-wildlife-sighting-card]').length,
+    1,
+  );
+  assert.equal(
+    f.cardElement().querySelector('h2').textContent,
+    second.commonName,
+  );
+  for (const close of ['Escape', 'outside', 'button']) {
+    if (close === 'Escape')
+      document.dispatchEvent(
+        new KeyboardEvent('keydown', {
+          key: 'Escape',
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    if (close === 'outside') document.body.click();
+    if (close === 'button') f.cardElement().querySelector('button').click();
+    await settle();
+    assert.equal(f.cardElement(), null);
+    assert.equal(f.state.selectedId, null);
+    assert.deepEqual(f.overlays.get('wildlife-sightings-selected'), []);
+    assert.equal(document.activeElement, f.opener);
+    await f.click();
+  }
+  assert.equal(f.clears(), 3);
+});
+
+test('camera movement repositions the same card and removes frame work at rest', async (context) => {
+  const f = fixture(context);
+  await f.click();
+  const card = f.cardElement();
+  const before = f.host().style.left;
+  f.moveStart.emit();
+  assert.equal(f.preRender.size(), 1);
+  f.setPoint({ x: 800, y: 450 });
+  f.preRender.emit();
+  assert.equal(f.cardElement(), card);
+  assert.notEqual(f.host().style.left, before);
+  f.moveEnd.emit();
+  assert.equal(f.preRender.size(), 0);
+  await f.publish({ ...row, commonName: 'Updated synthetic bird' });
+  assert.equal(f.cardElement(), card);
+  assert.equal(card.querySelector('h2').textContent, 'Updated synthetic bird');
+  f.state.rowById.delete(row.stableId);
+  await f.publish(null);
+  assert.equal(
+    f.cardElement(),
+    card,
+    'a refreshed sample cannot close the selected card',
+  );
+  f.layer.clearSightingSelection();
+  await settle();
+  assert.equal(f.cardElement(), null);
+});
+
+test('replacement photo loads cannot expose the previous image and failures retain the text card', async (context) => {
+  const f = fixture(context);
+  await f.click();
+  const previous = f.cardElement().querySelector('img');
+  let decoded;
+  previous.decode = () =>
+    new Promise((resolve) => {
+      decoded = resolve;
+    });
+  previous.dispatchEvent(new Event('load'));
+  await f.publish({
+    ...row,
+    photo: { ...row.photo, square: square.replace('/456/', '/789/') },
+  });
+  const current = f.cardElement().querySelector('img');
+  decoded();
+  await settle();
+  assert.equal(current.classList.contains('loaded'), false);
+  current.dispatchEvent(new Event('error'));
+  await settle();
+  assert.equal(
+    f.cardElement().querySelector('[role=status]').textContent,
+    'Photo unavailable',
+  );
+  assert.equal(current.style.display, 'none');
+  assert.equal(f.cardElement().querySelector('a').href, row.link);
+});
+
+test('teardown removes subscriptions, placement listeners and host, and ignores stale notifications', async (context) => {
+  const f = fixture(context);
+  await f.click();
+  f.moveStart.emit();
+  const stale = f.staleListener();
+  f.card.destroy();
+  assert.equal(f.cardElement(), null);
+  assert.equal(f.host(), null);
+  assert.equal(f.subscriptions.size, 0);
+  assert.equal(f.preRender.size(), 0);
+  stale(row);
+  await f.click();
+  assert.equal(f.cardElement(), null);
+  assert.equal(document.activeElement, f.opener);
+});
+
+test('locale changes translate the card without replacing the image or credit', async (context) => {
+  const before = getLocale();
+  context.after(() => setLocale(before));
+  const f = fixture(context);
+  await f.click();
+  const card = f.cardElement();
+  const image = card.querySelector('img');
+  for (const locale of LOCALES) {
+    setLocale(locale);
+    await settle();
+    assert.equal(f.cardElement(), card);
+    assert.equal(card.querySelector('img'), image);
+    assert.equal(
+      card.querySelector('button').getAttribute('aria-label'),
+      t('Close sighting'),
+    );
+    assert.ok(card.textContent.includes('© Synthetic Photographer · CC BY-SA'));
+  }
+});
+
+test('date-only and unsafe-link rows remain readable, and no sighting rail or lightbox is shipped', async (context) => {
+  const f = fixture(context, {
+    ...row,
+    observedAt: null,
+    photo: null,
+    link: 'javascript:alert(1)',
+  });
+  await f.click();
+  assert.equal(f.cardElement().querySelector('a'), null);
+  assert.equal(
+    f.cardElement().querySelector('time').getAttribute('datetime'),
+    row.observedOn,
+  );
+  assert.equal(PANEL_RAIL_ITEMS['wildlife-sighting-panel'], undefined);
+  assert.equal(sheetForPanelId('wildlife-sighting-panel'), null);
+  const source = readFileSync(
+    new URL('./wildlifeSightingCard.js', import.meta.url),
+    'utf8',
+  );
+  assert.doesNotMatch(
+    source,
+    /Lightbox|showModal|requestAnimationFrame|setInterval/,
+  );
+});
+
+test('WHALES cards retain compact whale guidance outside the observation action', async (context) => {
+  const f = fixture(context);
+  f.layer.getParams = () => ({ taxa: 'whales' });
+  await f.click();
+  const guidance = f
+    .cardElement()
+    .querySelector('a[href="https://www.bewhalewise.org"]');
+  assert.equal(guidance.textContent, 'Be Whale Wise');
+  assert.equal(
+    guidance.parentElement.closest('a'),
+    null,
+    'the external guidance link never nests inside the observation action',
+  );
+});
+
+test('opening during camera motion tracks the card and closing stops frame work immediately', async (context) => {
+  const f = fixture(context);
+  f.moveStart.emit();
+  assert.equal(f.preRender.size(), 0);
+  await f.click();
+  assert.equal(f.preRender.size(), 1);
+  f.layer.clearSightingSelection();
+  await settle();
+  assert.equal(f.preRender.size(), 0);
+});
+
+test('newly mounted chrome repositions the open card without camera events or idle text work', async (context) => {
+  const observers = [];
+  class MutationObserver {
+    constructor(callback) {
+      this.callback = callback;
+      this.targets = [];
+      observers.push(this);
+    }
+    observe(target, options) {
+      this.targets.push({ target, options });
+    }
+    disconnect() {
+      this.targets = [];
+    }
+  }
+  const f = fixture(context, row, { x: 600, y: 450 }, { MutationObserver });
+  await f.click();
+  const structural = observers.find((observer) =>
+    observer.targets.some(
+      ({ target, options }) =>
+        target === document.body && options.childList && options.subtree,
+    ),
+  );
+  assert.ok(
+    structural,
+    'structural observation exists only while a card is open',
+  );
+  const original = f.cardElement();
+  const before = f.host().style.top;
+  const hudWrapper = document.body.appendChild(document.createElement('div'));
+  const hud = hudWrapper.appendChild(document.createElement('div'));
+  hud.className = 'hud-top-left';
+  hud.getBoundingClientRect = () => rect(500, 350, 200, 200);
+  structural.callback([{ addedNodes: [hudWrapper], removedNodes: [] }]);
+  await settle();
+  assert.equal(
+    f.pans.length,
+    1,
+    'chrome newly covering the dot triggers one minimal pan',
+  );
+  assert.equal(f.cardElement(), original);
+  assert.notEqual(f.host().style.top, before);
+  assert.equal(f.preRender.size(), 0);
+  const placed = rect(
+    Number.parseFloat(f.host().style.left),
+    Number.parseFloat(f.host().style.top),
+    258,
+    300,
+  );
+  assert.ok(
+    placed.right <= 494 ||
+      placed.left >= 706 ||
+      placed.bottom <= 344 ||
+      placed.top >= 556,
+    'the card clears the measured HUD rect',
+  );
+  const afterChrome = f.projections();
+  // The observer ignores text nodes, ordinary clock wrappers and the card's
+  // own image/caption patches even though body observation sees their records.
+  const clock = hud.appendChild(document.createElement('span'));
+  const text = clock.appendChild(document.createTextNode('13:00:01'));
+  structural.callback([
+    {
+      addedNodes: [clock, text, f.cardElement().querySelector('img')],
+      removedNodes: [],
+    },
+  ]);
+  assert.equal(f.projections(), afterChrome);
+  f.layer.clearSightingSelection();
+  await settle();
+  assert.equal(
+    structural.targets.length,
+    0,
+    'closing disconnects structural observation',
+  );
+});
diff --git a/src/ui/wildlifeSightingPlacement.js b/src/ui/wildlifeSightingPlacement.js
new file mode 100644
index 000000000..e638b9ccb
--- /dev/null
+++ b/src/ui/wildlifeSightingPlacement.js
@@ -0,0 +1,274 @@
+import * as Cesium from 'cesium';
+import { WORLD_OVERLAY_OCCLUDER_SELECTORS } from '../overlays/worldOverlayChrome.js';
+
+// DOM cards also avoid the HUD edges and responsive sheet containers.
+export const WILDLIFE_CARD_CHROME_SELECTORS = Object.freeze([
+  ...WORLD_OVERLAY_OCCLUDER_SELECTORS,
+  '.hud-left-edge',
+  '.hud-right-edge',
+  '#right-panel-stack',
+  '.gev-panel-rail',
+  '#location-bar',
+  '#control-panel',
+  '#param-slider-panel',
+  '#cockpit-hud .cockpit-topline',
+  '[data-mobile-sheet]',
+]);
+const GAP = 12;
+const EDGE = 6;
+export const WILDLIFE_SELECTED_CARD_WIDTH = 258;
+
+const overlaps = (a, b) =>
+  a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
+const contains = (r, p) =>
+  p.x >= r.left && p.x <= r.right && p.y >= r.top && p.y <= r.bottom;
+const clamp = (value, low, high) => Math.max(low, Math.min(high, value));
+const rectAt = (left, top, width, height) => ({
+  left,
+  top,
+  right: left + width,
+  bottom: top + height,
+  width,
+  height,
+});
+
+/** Read visible chrome rectangles inside the viewer's usable screen area. */
+export function readWildlifeCardSafeArea({
+  documentRef,
+  viewer,
+  windowRef = globalThis.window,
+}) {
+  const canvasRect = viewer?.scene?.canvas?.getBoundingClientRect?.();
+  const width =
+    windowRef?.innerWidth || documentRef.documentElement.clientWidth;
+  const height =
+    windowRef?.innerHeight || documentRef.documentElement.clientHeight;
+  const left = Math.max(0, canvasRect?.left || 0) + EDGE;
+  const top = Math.max(0, canvasRect?.top || 0) + EDGE;
+  const right =
+    Math.min(width, canvasRect?.width > 0 ? canvasRect.right : width) - EDGE;
+  const bottom =
+    Math.min(height, canvasRect?.height > 0 ? canvasRect.bottom : height) -
+    EDGE;
+  const bounds = rectAt(
+    left,
+    top,
+    Math.max(0, right - left),
+    Math.max(0, bottom - top),
+  );
+  const obstacles = [];
+  const elements = [
+    ...documentRef.querySelectorAll(WILDLIFE_CARD_CHROME_SELECTORS.join(',')),
+  ];
+  for (const element of elements) {
+    let hidden = false;
+    for (
+      let node = element;
+      node && node !== documentRef.body;
+      node = node.parentElement
+    ) {
+      const style = windowRef?.getComputedStyle?.(node);
+      if (
+        node.hidden ||
+        style?.display === 'none' ||
+        style?.visibility === 'hidden' ||
+        style?.opacity === '0'
+      ) {
+        hidden = true;
+        break;
+      }
+    }
+    if (hidden) continue;
+    const rect = element.getBoundingClientRect();
+    if (!(rect.width > 0 && rect.height > 0) || !overlaps(rect, bounds))
+      continue;
+    obstacles.push(
+      rectAt(
+        rect.left - EDGE,
+        rect.top - EDGE,
+        rect.width + EDGE * 2,
+        rect.height + EDGE * 2,
+      ),
+    );
+  }
+  return { bounds, obstacles, elements };
+}
+
+function nearestSafeAnchor(point, { bounds, obstacles }) {
+  const xs = [clamp(point.x, bounds.left + GAP, bounds.right - GAP)];
+  const ys = [clamp(point.y, bounds.top + GAP, bounds.bottom - GAP)];
+  for (const rect of obstacles) {
+    xs.push(
+      clamp(rect.left - GAP, bounds.left + GAP, bounds.right - GAP),
+      clamp(rect.right + GAP, bounds.left + GAP, bounds.right - GAP),
+    );
+    ys.push(
+      clamp(rect.top - GAP, bounds.top + GAP, bounds.bottom - GAP),
+      clamp(rect.bottom + GAP, bounds.top + GAP, bounds.bottom - GAP),
+    );
+  }
+  return (
+    xs
+      .flatMap((x) => ys.map((y) => ({ x, y })))
+      .filter(
+        (p) => contains(bounds, p) && !obstacles.some((r) => contains(r, p)),
+      )
+      .sort(
+        (a, b) =>
+          Math.hypot(a.x - point.x, a.y - point.y) -
+          Math.hypot(b.x - point.x, b.y - point.y),
+      )[0] || null
+  );
+}
+
+/** Four anchored placements, clamped along their free axis. Chrome is a set of
+ * actual DOM rectangles, so corner HUDs do not erase otherwise clear lanes. */
+export function placeWildlifeSightingCard(point, size, safeArea) {
+  const { bounds, obstacles } = safeArea;
+  const anchor =
+    contains(bounds, point) && !obstacles.some((r) => contains(r, point))
+      ? point
+      : nearestSafeAnchor(point, safeArea);
+  if (!anchor) return null;
+  const width = Math.min(size.width, bounds.width);
+  const height = Math.min(size.height, bounds.height);
+  const centeredX = clamp(
+    anchor.x - width / 2,
+    bounds.left,
+    bounds.right - width,
+  );
+  const centeredY = clamp(
+    anchor.y - height / 2,
+    bounds.top,
+    bounds.bottom - height,
+  );
+  const candidates = [
+    {
+      placement: 'above',
+      ...rectAt(centeredX, anchor.y - GAP - height, width, height),
+    },
+    { placement: 'below', ...rectAt(centeredX, anchor.y + GAP, width, height) },
+    { placement: 'right', ...rectAt(anchor.x + GAP, centeredY, width, height) },
+    {
+      placement: 'left',
+      ...rectAt(anchor.x - GAP - width, centeredY, width, height),
+    },
+  ];
+  const fits = (rect) =>
+    rect.left >= bounds.left &&
+    rect.right <= bounds.right &&
+    rect.top >= bounds.top &&
+    rect.bottom <= bounds.bottom &&
+    !obstacles.some((r) => overlaps(rect, r));
+  let chosen = candidates.find(fits);
+  if (!chosen) {
+    // Crowded chrome may require sliding a side placement farther from its
+    // anchor. Search only obstacle/bounds edges; no pixels or idle frame loop.
+    const xs = [bounds.left, bounds.right - width, centeredX];
+    const ys = [bounds.top, bounds.bottom - height, centeredY];
+    for (const r of obstacles) {
+      xs.push(r.left - width, r.right);
+      ys.push(r.top - height, r.bottom);
+    }
+    const alternatives = xs
+      .flatMap((x) =>
+        ys.map((y) => ({
+          placement:
+            y + height <= anchor.y
+              ? 'above'
+              : y >= anchor.y
+                ? 'below'
+                : x >= anchor.x
+                  ? 'right'
+                  : 'left',
+          ...rectAt(x, y, width, height),
+        })),
+      )
+      .filter((r) => fits(r) && !contains(r, anchor));
+    alternatives.sort(
+      (a, b) =>
+        Math.hypot(
+          clamp(anchor.x, a.left, a.right) - anchor.x,
+          clamp(anchor.y, a.top, a.bottom) - anchor.y,
+        ) -
+        Math.hypot(
+          clamp(anchor.x, b.left, b.right) - anchor.x,
+          clamp(anchor.y, b.top, b.bottom) - anchor.y,
+        ),
+    );
+    chosen = alternatives[0];
+  }
+  return chosen
+    ? {
+        ...chosen,
+        anchor,
+        pan: { x: anchor.x - point.x, y: anchor.y - point.y },
+      }
+    : null;
+}
+
+/** Project a front-side sighting into viewport coordinates. */
+export function projectWildlifeSighting(viewer, row, layer) {
+  if (
+    !viewer?.scene ||
+    !Number.isFinite(row?.lat) ||
+    !Number.isFinite(row?.lon)
+  )
+    return null;
+  const position =
+    layer?.getSightingPosition?.(row.stableId) ||
+    Cesium.Cartesian3.fromDegrees(row.lon, row.lat);
+  const ellipsoid = viewer.scene.globe?.ellipsoid || Cesium.Ellipsoid.WGS84;
+  if (
+    viewer.camera?.positionWC &&
+    new Cesium.EllipsoidalOccluder(
+      ellipsoid,
+      viewer.camera.positionWC,
+    ).isPointVisible(position) !== true
+  )
+    return null;
+  const point = Cesium.SceneTransforms.worldToWindowCoordinates(
+    viewer.scene,
+    position,
+  );
+  if (!point) return null;
+  const rect = viewer.scene.canvas?.getBoundingClientRect?.();
+  return { x: point.x + (rect?.left || 0), y: point.y + (rect?.top || 0) };
+}
+
+/** Translate the camera by the smallest screen correction and preserve its
+ * altitude/orientation. A card must never zoom merely to reveal its anchor. */
+export function panWildlifeSighting(viewer, from, to, reducedMotion = false) {
+  const camera = viewer?.camera;
+  if (!camera?.pickEllipsoid || !camera.flyTo) return false;
+  const rect = viewer.scene.canvas.getBoundingClientRect();
+  const local = (p) => new Cesium.Cartesian2(p.x - rect.left, p.y - rect.top);
+  const ellipsoid = viewer.scene.globe?.ellipsoid || Cesium.Ellipsoid.WGS84;
+  const start = camera.pickEllipsoid(local(from), ellipsoid);
+  const finish = camera.pickEllipsoid(local(to), ellipsoid);
+  if (!start || !finish || !camera.positionWC) return false;
+  const delta = Cesium.Cartesian3.subtract(
+    start,
+    finish,
+    new Cesium.Cartesian3(),
+  );
+  const destination = Cesium.Cartesian3.add(
+    camera.positionWC,
+    delta,
+    new Cesium.Cartesian3(),
+  );
+  const cartographic = ellipsoid.cartesianToCartographic(destination);
+  if (!cartographic) return false;
+  cartographic.height = camera.positionCartographic.height;
+  camera.flyTo({
+    destination: ellipsoid.cartographicToCartesian(cartographic),
+    orientation: {
+      heading: camera.heading,
+      pitch: camera.pitch,
+      roll: camera.roll,
+    },
+    duration: reducedMotion ? 0 : 0.22,
+    easingFunction: Cesium.EasingFunction.QUADRATIC_OUT,
+  });
+  return true;
+}
diff --git a/src/voice/layerManifest.js b/src/voice/layerManifest.js
index 1234fb61e..9b5684243 100644
--- a/src/voice/layerManifest.js
+++ b/src/voice/layerManifest.js
@@ -453,10 +453,12 @@ const layers = [
 export const VOICE_OFF_LAYERS = Object.freeze({
   'bhote-koshi-2026': 'scene-driven event layer (control_scene)',
   'bhote-koshi-locator': 'scene-driven event layer (control_scene)',
-  // The Realtime prompt is at its 52,000-character budget; voice toggle and
+  // The Realtime prompt is at its 55,500-character budget; voice toggle and
   // query for this layer wait until there is room.
   'drone-airspace':
     'informational airspace layer; no room in the prompt budget',
+  'wildlife-sightings':
+    'community observation layer; no room in the prompt budget',
 });
 
 const TYPE_NAMES = Object.freeze({
diff --git a/src/worldFocus.js b/src/worldFocus.js
index 5b5ca7a8e..6ed3a3b32 100644
--- a/src/worldFocus.js
+++ b/src/worldFocus.js
@@ -9,6 +9,12 @@ export const WORLD_CLICK_FOCUS_DURATION_SEC = 1.9;
 export const WORLD_FOCUS_FRAMING = Object.freeze({
   vessel: Object.freeze({ radiusM: 150, rangeM: 1200, pitchDeg: -30 }),
   fire: Object.freeze({ radiusM: 400, rangeM: 3000, pitchDeg: -35 }),
+  sighting: Object.freeze({ radiusM: 250, rangeM: 2500, pitchDeg: -40 }),
+  'sighting-area': Object.freeze({
+    radiusM: 11000,
+    rangeM: 60000,
+    pitchDeg: -55,
+  }),
 });
 
 /** Validate a layer-owned focus target before camera policy can release tracking. */
@@ -23,7 +29,7 @@ export function isValidWorldFocusTarget(detail) {
     !Number.isFinite(position.z)
   )
     return false;
-  // Vessel and fire targets are surface-anchored Earth positions. Merely
+  // These targets are surface-anchored Earth positions. Merely
   // finite coordinates near the ECEF origin cannot be flown to, and must be
   // rejected before the camera policy releases a current follow owner.
   const magnitude = Cesium.Cartesian3.magnitude(position);
diff --git a/src/worldFocus.test.mjs b/src/worldFocus.test.mjs
index f5e8146db..3a10b75eb 100644
--- a/src/worldFocus.test.mjs
+++ b/src/worldFocus.test.mjs
@@ -21,16 +21,28 @@ function stubCamera() {
   return {
     calls,
     heading: Cesium.Math.toRadians(45),
-    cancelFlight() { calls.cancelFlight += 1; },
-    flyToBoundingSphere(sphere, options) { calls.flights.push({ sphere, options }); },
+    cancelFlight() {
+      calls.cancelFlight += 1;
+    },
+    flyToBoundingSphere(sphere, options) {
+      calls.flights.push({ sphere, options });
+    },
   };
 }
 
 test('a focus request carries the clicked target to any registered listener', () => {
   const target = new EventTarget();
   const seen = [];
-  const dispose = registerWorldFocusRequestListener(target, (event) => seen.push(event.detail));
-  assert.equal(requestWorldFocus({ kind: 'vessel', position: POSITION, id: '123' }, target), true);
+  const dispose = registerWorldFocusRequestListener(target, (event) =>
+    seen.push(event.detail),
+  );
+  assert.equal(
+    requestWorldFocus(
+      { kind: 'vessel', position: POSITION, id: '123' },
+      target,
+    ),
+    true,
+  );
   assert.equal(seen.length, 1);
   assert.equal(seen[0].kind, 'vessel');
   assert.equal(seen[0].id, '123');
@@ -44,7 +56,9 @@ test('a focus request carries the clicked target to any registered listener', ()
 test('requests without a kind or a position are dropped, never dispatched', () => {
   const target = new EventTarget();
   let count = 0;
-  target.addEventListener(WORLD_FOCUS_REQUEST_EVENT, () => { count += 1; });
+  target.addEventListener(WORLD_FOCUS_REQUEST_EVENT, () => {
+    count += 1;
+  });
   assert.equal(requestWorldFocus({ position: POSITION }, target), false);
   assert.equal(requestWorldFocus({ kind: 'vessel' }, target), false);
   assert.equal(requestWorldFocus(null, target), false);
@@ -74,51 +88,94 @@ test('a refusing policy (cockpit owns the camera) never reaches the flight', ()
   const result = routeWorldFocusRequest(
     { detail: { kind: 'vessel', id: '123', position: POSITION } },
     () => false,
-    () => { flights += 1; },
+    () => {
+      flights += 1;
+    },
   );
   assert.equal(result, false);
   assert.equal(flights, 0);
 });
 
 test('malformed requests are inert', () => {
-  assert.equal(routeWorldFocusRequest(null, () => 'x', () => 'y'), false);
-  assert.equal(routeWorldFocusRequest({ detail: { kind: 'vessel' } }, () => 'x', () => 'y'), false);
+  assert.equal(
+    routeWorldFocusRequest(
+      null,
+      () => 'x',
+      () => 'y',
+    ),
+    false,
+  );
+  assert.equal(
+    routeWorldFocusRequest(
+      { detail: { kind: 'vessel' } },
+      () => 'x',
+      () => 'y',
+    ),
+    false,
+  );
 });
 
 // A request that cannot fly must never cost the user their tracking: the UI
 // policy releases the follow camera, so validation happens BEFORE it runs.
 test('an unflyable request never reaches the release policy', () => {
   const unflyable = [
-    { kind: 'plane', position: POSITION },                       // no framing for this kind
-    { kind: 'vessel', position: { x: NaN, y: 0, z: 0 } },        // malformed position
-    { kind: 'vessel', position: { x: 0, y: 0 } },                // truthy but incomplete
+    { kind: 'plane', position: POSITION }, // no framing for this kind
+    { kind: 'vessel', position: { x: NaN, y: 0, z: 0 } }, // malformed position
+    { kind: 'vessel', position: { x: 0, y: 0 } }, // truthy but incomplete
     { kind: 'vessel', id: '123', position: { x: 0, y: 0, z: 0 } }, // ECEF origin
     { kind: 'fire', id: 'fire-1', position: { x: 1, y: 1, z: 1 } }, // finite but inside Earth
     { kind: 'vessel', position: 'somewhere' },
-    { kind: 'vessel', position: POSITION },                     // missing owner id
+    { kind: 'vessel', position: POSITION }, // missing owner id
     { position: POSITION },
   ];
   for (const detail of unflyable) {
-    assert.equal(isValidWorldFocusTarget(detail), false, JSON.stringify(detail));
+    assert.equal(
+      isValidWorldFocusTarget(detail),
+      false,
+      JSON.stringify(detail),
+    );
     let policyRuns = 0;
     const result = routeWorldFocusRequest(
       { detail },
-      () => { policyRuns += 1; return 'released'; },
+      () => {
+        policyRuns += 1;
+        return 'released';
+      },
       () => 'flew',
     );
     assert.equal(result, false, JSON.stringify(detail));
-    assert.equal(policyRuns, 0, `the policy must not run for ${JSON.stringify(detail)}`);
+    assert.equal(
+      policyRuns,
+      0,
+      `the policy must not run for ${JSON.stringify(detail)}`,
+    );
     // Nor may such a request be dispatched in the first place.
     assert.equal(requestWorldFocus(detail, new EventTarget()), false);
   }
-  assert.equal(isValidWorldFocusTarget({ kind: 'vessel', id: '123', position: POSITION }), true);
-  assert.equal(isValidWorldFocusTarget({ kind: 'fire', id: 'fire-1', position: POSITION }), true);
+  assert.equal(
+    isValidWorldFocusTarget({ kind: 'vessel', id: '123', position: POSITION }),
+    true,
+  );
+  assert.equal(
+    isValidWorldFocusTarget({ kind: 'fire', id: 'fire-1', position: POSITION }),
+    true,
+  );
 });
 
 test('the transfer flight supersedes any flight in progress and keeps the operator heading', () => {
   const camera = stubCamera();
-  assert.equal(flyToWorldTarget({ camera }, { kind: 'vessel', id: '123', position: POSITION }), true);
-  assert.equal(camera.calls.cancelFlight, 1, 'a prior flight must be cancelled, not queued');
+  assert.equal(
+    flyToWorldTarget(
+      { camera },
+      { kind: 'vessel', id: '123', position: POSITION },
+    ),
+    true,
+  );
+  assert.equal(
+    camera.calls.cancelFlight,
+    1,
+    'a prior flight must be cancelled, not queued',
+  );
   assert.equal(camera.calls.flights.length, 1);
   const { sphere, options } = camera.calls.flights[0];
   assert.equal(sphere.radius, WORLD_FOCUS_FRAMING.vessel.radiusM);
@@ -131,39 +188,82 @@ test('the transfer flight supersedes any flight in progress and keeps the operat
 
 test('fires frame wider than vessels — a fire is read by its surroundings', () => {
   const camera = stubCamera();
-  flyToWorldTarget({ camera }, { kind: 'fire', id: 'fire-1', position: POSITION });
+  flyToWorldTarget(
+    { camera },
+    { kind: 'fire', id: 'fire-1', position: POSITION },
+  );
   const { sphere, options } = camera.calls.flights[0];
   assert.equal(sphere.radius, WORLD_FOCUS_FRAMING.fire.radiusM);
   assert.equal(options.offset.range, WORLD_FOCUS_FRAMING.fire.rangeM);
-  assert.ok(WORLD_FOCUS_FRAMING.fire.rangeM > WORLD_FOCUS_FRAMING.vessel.rangeM);
-  assert.ok(WORLD_FOCUS_FRAMING.fire.radiusM > WORLD_FOCUS_FRAMING.vessel.radiusM);
+  assert.ok(
+    WORLD_FOCUS_FRAMING.fire.rangeM > WORLD_FOCUS_FRAMING.vessel.rangeM,
+  );
+  assert.ok(
+    WORLD_FOCUS_FRAMING.fire.radiusM > WORLD_FOCUS_FRAMING.vessel.radiusM,
+  );
 });
 
 test('every framing is a real oblique standoff, not a nadir or an inside-out sphere', () => {
   const kinds = Object.keys(WORLD_FOCUS_FRAMING);
-  assert.deepEqual(kinds.sort(), ['fire', 'vessel']);
+  assert.deepEqual(kinds.sort(), [
+    'fire',
+    'sighting',
+    'sighting-area',
+    'vessel',
+  ]);
   for (const kind of kinds) {
     const framing = WORLD_FOCUS_FRAMING[kind];
     // Looking DOWN at the target, but obliquely — a nadir drop reads as a map.
-    assert.ok(framing.pitchDeg < 0, `${kind}: pitch must look down, got ${framing.pitchDeg}`);
-    assert.ok(framing.pitchDeg > -80, `${kind}: pitch must stay oblique, got ${framing.pitchDeg}`);
+    assert.ok(
+      framing.pitchDeg < 0,
+      `${kind}: pitch must look down, got ${framing.pitchDeg}`,
+    );
+    assert.ok(
+      framing.pitchDeg > -80,
+      `${kind}: pitch must stay oblique, got ${framing.pitchDeg}`,
+    );
     // Standing off outside the framed sphere, at a human-readable distance.
     assert.ok(framing.radiusM > 0, `${kind}: radius must be positive`);
     assert.ok(
       framing.rangeM > framing.radiusM,
       `${kind}: range ${framing.rangeM} must stand off outside radius ${framing.radiusM}`,
     );
-    assert.ok(framing.rangeM <= 10000, `${kind}: range must stay close-in, got ${framing.rangeM}`);
+    // An obscured sighting frames its entire 0.2° privacy cell.
+    const maximumRange = kind === 'sighting-area' ? 60000 : 10000;
+    assert.ok(
+      framing.rangeM <= maximumRange,
+      `${kind}: range must fit its surface extent, got ${framing.rangeM}`,
+    );
   }
   // Exact shipped values — a silent retune must show up as a failing test.
-  assert.deepEqual({ ...WORLD_FOCUS_FRAMING.vessel }, { radiusM: 150, rangeM: 1200, pitchDeg: -30 });
-  assert.deepEqual({ ...WORLD_FOCUS_FRAMING.fire }, { radiusM: 400, rangeM: 3000, pitchDeg: -35 });
+  assert.deepEqual(
+    { ...WORLD_FOCUS_FRAMING.vessel },
+    { radiusM: 150, rangeM: 1200, pitchDeg: -30 },
+  );
+  assert.deepEqual(
+    { ...WORLD_FOCUS_FRAMING.fire },
+    { radiusM: 400, rangeM: 3000, pitchDeg: -35 },
+  );
+  assert.deepEqual(
+    { ...WORLD_FOCUS_FRAMING.sighting },
+    { radiusM: 250, rangeM: 2500, pitchDeg: -40 },
+  );
+  assert.deepEqual(
+    { ...WORLD_FOCUS_FRAMING['sighting-area'] },
+    { radiusM: 11000, rangeM: 60000, pitchDeg: -55 },
+  );
 });
 
 test('unknown kinds and missing viewers issue no flight', () => {
   const camera = stubCamera();
-  assert.equal(flyToWorldTarget({ camera }, { kind: 'plane', position: POSITION }), false);
+  assert.equal(
+    flyToWorldTarget({ camera }, { kind: 'plane', position: POSITION }),
+    false,
+  );
   assert.equal(flyToWorldTarget({ camera }, { kind: 'vessel' }), false);
-  assert.equal(flyToWorldTarget(null, { kind: 'vessel', position: POSITION }), false);
+  assert.equal(
+    flyToWorldTarget(null, { kind: 'vessel', position: POSITION }),
+    false,
+  );
   assert.equal(camera.calls.flights.length, 0);
 });

From ecbe1d99e67f09f622f1afe6a8bb450edddc0909 Mon Sep 17 00:00:00 2001
From: Yehe Liu <yxl448@case.edu>
Date: Thu, 5 Nov 2026 16:18:27 -0500
Subject: [PATCH 47/71] docs: number the wildlife sightings changelog fragment
 (#1591)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../{0000-wildlife-sightings.md => 1591-wildlife-sightings.md}  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
 rename changelog.d/{0000-wildlife-sightings.md => 1591-wildlife-sightings.md} (95%)

diff --git a/changelog.d/0000-wildlife-sightings.md b/changelog.d/1591-wildlife-sightings.md
similarity index 95%
rename from changelog.d/0000-wildlife-sightings.md
rename to changelog.d/1591-wildlife-sightings.md
index 75abdd8dd..64f4e7c54 100644
--- a/changelog.d/0000-wildlife-sightings.md
+++ b/changelog.d/1591-wildlife-sightings.md
@@ -9,4 +9,4 @@
   Acartia comments are excluded. Attribution appears in the layer row and
   Data attribution popover. Cached progressive tiles, bounded image/billboard
   work and a paced queue preserve iNaturalist's 60/minute and 8,000/day limits.
-  All 11 locales supported. (lyehe, #0000)
+  All 11 locales supported. (lyehe, #1591)

From 63fd559496fa8af42d144a0cc0e5bb8d1071b90c Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 14:01:17 -0800
Subject: [PATCH 48/71] Keep the ridden aircraft's layer when Contacts ends,
 and clear its rows from Live Signals

Riding an aircraft now adopts its layer the way a direct selection does, and
Contacts gives up a dependency the user adopts, so ending Contacts mid-session
(one of its layers off, or Contacts itself) no longer turns off the ridden
layer and ends the Cockpit. When Contacts goes off, Live Signals drops the
rows built from its snapshot instead of leaving stale distances marked
CURRENT, and the feed-off warning is no longer duplicated.
---
 changelog.d/1556-cockpit-own-layer-entry.md |   3 +-
 docs/CURRENT-STATE.md                       |  15 +-
 src/data/militaryAwareness.test.mjs         |  50 ++++
 src/layers/awareness/controls.js            |   1 +
 src/layers/awareness/dependencies.js        |  20 ++
 src/layers/awareness/lifecycle.js           |   1 +
 src/layers/awareness/state.js               |   2 +
 src/ui/cockpitContext.js                    |   3 +
 src/ui/cockpitContext.test.mjs              |  63 +++++
 src/ui/cockpitController.js                 |   6 +
 src/ui/cockpitCoordinator.js                |  17 ++
 src/ui/cockpitEntryGate.test.mjs            | 253 +++++++++++++++++++-
 src/ui/cockpitSignals.js                    |  21 ++
 src/ui/cockpitTrackingController.js         |   2 +
 14 files changed, 441 insertions(+), 16 deletions(-)

diff --git a/changelog.d/1556-cockpit-own-layer-entry.md b/changelog.d/1556-cockpit-own-layer-entry.md
index ca5210120..d88f475f1 100644
--- a/changelog.d/1556-cockpit-own-layer-entry.md
+++ b/changelog.d/1556-cockpit-own-layer-entry.md
@@ -1,5 +1,6 @@
 - Enter Cockpit with only the ridden aircraft's layer on. Contacts is no longer
-  required; turning off the aircraft's own feed ends the view, a missing other
+  required, and ending Contacts mid-session keeps the view and the layer it
+  rides; turning off the aircraft's own feed ends the view, a missing other
   feed reads `… FEED OFF · PARTIAL PICTURE`, and double-clicking the followed
   aircraft or the entry beside its readout enters it (Denis Groshev, @ZloyS,
   #1556).
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index ad0dc30e4..87617f531 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -6021,11 +6021,16 @@ apply to `public/` assets or built-preview serving.
   tracked: Live Flights for a civilian, Military Flights for a military aircraft
   (the tracked info's `layerId`; `cockpitEntryAllowed` in
   `src/contextModePolicy.js`). Contacts is not required, and the other aircraft
-  layer, Live AIS Vessels and every other layer may be turned on or off before or
-  during a session. A Context mode change still in flight blocks entry until it
-  settles. Turning off the layer the view rides ends it. The visible Cockpit
-  actions, the `C` shortcut and voice use the same gate; voice entry still opens
-  Contacts first, as its layer-targeted entry navigates through Contacts.
+  layer, Live AIS Vessels and every other layer may be turned on or off before
+  or during a session. A Context mode change still in flight blocks entry until
+  it settles. Turning off the layer the view rides ends it. Riding an aircraft
+  while Contacts is on adopts its layer as the user's own, as a direct selection
+  does (`adoptLayerVisibility`), so Contacts ending, by its own switch or one of
+  its layers going off, restores the pre-Contacts layers but keeps the ridden
+  one and the view; Live Signals then drops the rows Contacts built and shows
+  `CONTEXT STANDBY`. The visible Cockpit actions, the `C` shortcut and voice use
+  the same gate; voice entry still opens Contacts first, as its layer-targeted
+  entry navigates through Contacts.
 - **Aircraft cockpit view:** selecting a commercial or military aircraft reveals a `COCKPIT` action (`C`) once that aircraft's own layer is on; Contacts is not required. The action shows in Contacts (`#cockpit-entry`) and under the Intel HUD's bottom-right readout (`#cockpit-entry-readout`, with the HUD on, in its Tactical and Cyber layouts), so entry needs no Contacts panel. Turning off the ridden aircraft's layer ends the view (the layer clears its tracking). When an air feed the surrounding picture uses is off, the Cockpit says so instead of blocking: Live Signals leads with `MILITARY FEED OFF · PARTIAL PICTURE` or `FLIGHTS FEED OFF · PARTIAL PICTURE`, and the Contact card shows that line in place of its inputs status, so a partial picture is never presented as complete. `control_cockpit` refuses entry with `entryBlockedReason` `contacts-starting` (a Context change in flight), `subject-layer-off` (the aircraft's layer, or with none tracked any aircraft layer, is off) or `no-tracked-aircraft`. Cockpit mode temporarily releases Cesium's orbit-follow transform and drives a first-person camera from the tracked aircraft's existing smoothed display position and course. Its concave helmet-visor HUD shows callsign, UTC time, coordinates, curved roll/pitch guides, and a seven-division heading tape. Ambient commercial and military AIR contacts use a Cockpit near/far band selected by the shared Display 3D mode: Proximity admits at 150 km and retains to 185 km; All admits at 400 km and retains to 450 km. The shared 3D toggle now applies in Cockpit: Off keeps in-range contacts as rotating 2D aircraft silhouettes, while On lets a ready admitted glTF take over without a drawing gap. The Cockpit model cap remains 60 and can only lower the map budget; in-range contacts that are capped or still loading remain 2D silhouettes instead of degrading to out-of-range dots. Contacts outside the selected band use small rotation-free cyan-white pips for civilian aircraft and amber pips for military. The pilot's own airframe is not drawn in first person, and exiting clears the Cockpit band and restores normal map silhouettes/models. The normal left accordion remains available for Layers and Authoring and keeps the same 26vh HUD-aligned anchor used in map mode, independent of whether the bottom-left Contact card is expanded or collapsed; the right-rail CCTV and Context chooser are hidden to avoid duplicating or overlapping the cockpit presentation. When the intelligence HUD is enabled, its classification, scene summary, collection/orbit metadata, coordinates, and imaging-status text remain visible as reduced peripheral cockpit telemetry; the optical center and flight instruments stay clear, and turning the HUD off still hides it. Ground speed, exact heading, and rendered altitude form one compact lower-center instrument cluster, keeping the horizon and peripheral view open. A second live altitude tape hugs the inside-right visor rim: its rail and nine moving ticks are derived from the same responsive keyhole radius, remain 20 px inside the circular edge even on wide displays, fade deeply at both vertical ends, and move continuously behind a fixed current-altitude pointer; its interval tightens automatically near the surface and it is suppressed on narrow screens. Cockpit mode also has a weather-backed transparent volumetric-cloud pass derived from the supplied FBM/domain-warped R&D shader. It renders at no more than 520×320, uses 24 ray steps/three FBM octaves at 12 FPS, is clipped to the visor, fails clear when Open-Meteo is unavailable, and stops its animation completely on cockpit exit. It does not restore the prior CPU weather canvases, precipitation, scene fog, or any map-mode effect. When Contacts is active for the tracked aircraft, the compact `CONTACT` rail adds the 250 km subject window, four cohort counts, nearest observed/mapped example with relative bearing and distance, freshness, explicit uncertainty, and Previous and Next controls plus its own collapse control. The mirrored right rail is a three-page **cockpit briefing carousel**: source-backed live signals, location-matched regional headlines, and physical-region/current-weather context from bundled Natural Earth polygons and Open-Meteo. It is manual-first: Previous, Next, and direct page controls are always available, and the visible `CYCLE OFF` / `CYCLE ON` control starts or stops the nine-second page cycle. The cycle pauses on hover or keyboard focus and stops while collapsed, hidden, or outside cockpit mode; live signal data continues refreshing either way. Empty news matches and unavailable news use compact text states rather than reserving an empty media frame; partial local data remains explicit. Article links open their original publisher, and no headline is treated as verified risk intelligence. On desktop both cockpit rails use the same width and share a bottom-aligned safe baseline in opposite corners above the peripheral MGRS/GSD/time telemetry, leaving both that text and the lower-center instrument cluster readable. They collapse independently to slim tabs without stopping live data updates. Narrow screens use separated top/bottom fallbacks. Empty-space globe clicks are inert while cockpit owns the camera; `C`, `Escape`, or `EXIT COCKPIT` explicitly exits and restores the same tracked entity and standard follow camera. Unknown feeds remain unknown, selection loss still exits safely without inventing a replacement track, and the cockpit never presents the summary as threat scoring or an all-clear. This is a desktop first-person presentation, not a WebXR session.
 - **Cockpit left-panel clearance:** the Cockpit Contact card and peripheral HUD participate in the adaptive left accordion's live obstacle measurements, including live viewport-height changes. Expanding Layers or Authoring keeps the active panel in the available upper-left corridor with internal scrolling; it does not cover the Contact card, lower Cockpit controls, or Cesium credit line. Outside Cockpit the hidden card does not alter the normal corridor.
 - **Cockpit Context scope:** the 250 km radius applies to the air/sea proximity cohorts. Installation counts come only from the currently loaded viewport and are labeled `CURRENT VIEWPORT ONLY` in the cockpit as well as the normal Context panel; neither surface presents them as a complete 250 km installation survey.
diff --git a/src/data/militaryAwareness.test.mjs b/src/data/militaryAwareness.test.mjs
index 05fd97dc0..98743b03c 100644
--- a/src/data/militaryAwareness.test.mjs
+++ b/src/data/militaryAwareness.test.mjs
@@ -98,6 +98,7 @@ function installAwarenessRuntime({
   // status its module never emits guards nothing. See the settled-but-fetching
   // tests below, which use militaryInstallations' genuine first-fetch readout.
   layerStats = {},
+  subscribe = undefined,
 } = {}) {
   const originalWindow = globalThis.window;
   const originalDocument = globalThis.document;
@@ -215,6 +216,7 @@ function installAwarenessRuntime({
     setEnabled,
     getLayerLifecycleState,
     layers,
+    ...(subscribe ? { subscribe } : {}),
   });
   militaryAwarenessLayer.setParams({ passive: true });
   militaryAwarenessLayer.init(viewer);
@@ -383,6 +385,54 @@ test('Contacts does not claim a dependency already enabling for the user', async
   }
 });
 
+test('a dependency the user adopts stays on when Contacts turns off', async () => {
+  // A direct selection, or the Cockpit riding one of its aircraft, promotes a
+  // layer Contacts turned on into the user's own (adoptLayerVisibility). The
+  // coordinator must give it up, or its OFF release tears the layer down —
+  // and the track or the Cockpit with it — before Context restores it.
+  const calls = [];
+  const subscribers = new Set();
+  const runtime = installAwarenessRuntime({
+    isEnabled: () => false,
+    isEffectivelyEnabled: () => false,
+    setEnabled: (layerId, enabled) => {
+      calls.push({ layerId, enabled });
+      return Promise.resolve(true);
+    },
+    subscribe: (listener) => {
+      subscribers.add(listener);
+      return () => subscribers.delete(listener);
+    },
+  });
+
+  try {
+    militaryAwarenessLayer.setParams({ passive: false });
+    await nextTurn();
+    for (const listener of subscribers)
+      listener({
+        type: 'visibility',
+        layerId: 'flights',
+        enabled: true,
+        origin: 'user',
+        adopted: true,
+        adoptedFromSelection: true,
+      });
+    await militaryAwarenessLayer.disable();
+    const released = calls
+      .filter(({ enabled }) => !enabled)
+      .map(({ layerId }) => layerId)
+      .sort();
+    assert.deepEqual(
+      released,
+      AWARENESS_DEPENDENCIES.filter((layerId) => layerId !== 'flights').sort(),
+      'the adopted layer is the user\'s now; the rest are still released',
+    );
+  } finally {
+    runtime.restore();
+  }
+  assert.equal(subscribers.size, 0, 'destroy drops the manager subscription');
+});
+
 test('operational awareness becomes ready after aircraft while deferred sources keep loading', async () => {
   let enabled = false;
   let releaseAircraft;
diff --git a/src/layers/awareness/controls.js b/src/layers/awareness/controls.js
index 38c273c05..ed543e138 100644
--- a/src/layers/awareness/controls.js
+++ b/src/layers/awareness/controls.js
@@ -23,6 +23,7 @@ export function createControls({ state: layerState, services, parts, source }) {
 
     attachDataManager(dataManager) {
       layerState.dataManager = dataManager;
+      parts.dependencies.watchAdoptions(dataManager);
     },
 
     setParams(params = {}) {
diff --git a/src/layers/awareness/dependencies.js b/src/layers/awareness/dependencies.js
index 15a23e455..80cffad1c 100644
--- a/src/layers/awareness/dependencies.js
+++ b/src/layers/awareness/dependencies.js
@@ -79,6 +79,25 @@ export function createDependencies({
     });
   }
 
+  /**
+   * Give up a dependency the user adopts. A direct selection, or the Cockpit
+   * riding one of its aircraft, promotes a layer Contacts turned on into the
+   * user's own (`DataLayerManager.adoptLayerVisibility`). Releasing it when
+   * Contacts goes off would tear down that track or Cockpit before the
+   * Context restore could put the layer back.
+   */
+  function relinquishAdoptedDependency(change) {
+    if (change?.type === 'visibility' && change.adopted && change.enabled)
+      layerState.ownedDependencies.delete(change.layerId);
+  }
+
+  /** Follow one manager's adoptions; null stops following. */
+  function watchAdoptions(dataManager) {
+    layerState.unwatchAdoptions?.();
+    layerState.unwatchAdoptions =
+      dataManager?.subscribe?.(relinquishAdoptedDependency) || null;
+  }
+
   function activateOperationalContext() {
     const activationId = ++layerState.activationId;
     layerState.autoFocusRetryPending = false;
@@ -113,6 +132,7 @@ export function createDependencies({
     refreshAfterDeferredDependency,
     enableDependencies,
     releaseOwnedDependencies,
+    watchAdoptions,
     activateOperationalContext,
   };
 }
diff --git a/src/layers/awareness/lifecycle.js b/src/layers/awareness/lifecycle.js
index b2e7dfe30..7b6b84610 100644
--- a/src/layers/awareness/lifecycle.js
+++ b/src/layers/awareness/lifecycle.js
@@ -340,6 +340,7 @@ export function createLifecycle({
       layerState.clearListener = null;
       layerState.subjectClearListener = null;
       layerState.viewer = null;
+      parts.dependencies.watchAdoptions(null);
       layerState.dataManager = null;
     },
   };
diff --git a/src/layers/awareness/state.js b/src/layers/awareness/state.js
index 4d7d0d6e7..adc896943 100644
--- a/src/layers/awareness/state.js
+++ b/src/layers/awareness/state.js
@@ -26,6 +26,8 @@ export function createState({ services }) {
     // layers activate only after Contacts is explicitly selected.
     passive: true,
     ownedDependencies: new Set(),
+    /** Stops following the manager's adoptions (see watchAdoptions). */
+    unwatchAdoptions: null,
     subject: null,
     results: null,
     visual: null,
diff --git a/src/ui/cockpitContext.js b/src/ui/cockpitContext.js
index a343bbb91..cfb142e50 100644
--- a/src/ui/cockpitContext.js
+++ b/src/ui/cockpitContext.js
@@ -75,6 +75,9 @@ export function updateContext(info, heading) {
   const readout = resolveCockpitContextReadout({ snapshot, info });
   const partial = readPartialPicture.call(this);
   if (!readout.visible) {
+    // Contacts just went off: the rows its snapshot built stop being
+    // measured, so they go before the standby rows replace them.
+    if (this.presence.context) this.dropContextSnapshotSignals?.();
     this.showContextCard(false);
     this.contextLayoutStamp = null;
     this.pushCockpitSignal(
diff --git a/src/ui/cockpitContext.test.mjs b/src/ui/cockpitContext.test.mjs
index 4896d238e..ca86701ab 100644
--- a/src/ui/cockpitContext.test.mjs
+++ b/src/ui/cockpitContext.test.mjs
@@ -12,6 +12,13 @@ import {
   updateContext,
 } from './cockpitContext.js';
 import { createContextState } from './cockpitContextState.js';
+import {
+  dropCockpitSignal,
+  dropContextSnapshotSignals,
+  publishCockpitSignals,
+  pushCockpitSignal,
+  updateCockpitSignals,
+} from './cockpitSignals.js';
 import { syncWeatherToggle } from './cockpitInstruments.js';
 import { setContextCollapsed } from './cockpitLayout.js';
 import { useCockpitStore } from './stores/cockpit.js';
@@ -261,6 +268,62 @@ test('without Contacts, a feed that is off adds a signal until it is back', asyn
   assert.deepEqual(dropped, ['feed-status']);
 });
 
+/** The fixture's owner with the real Live Signals presenters. */
+function withSignals(owner) {
+  const published = [];
+  Object.assign(owner, {
+    signalItems: [],
+    signalSignatures: new Map(),
+    publishSignals: (rows) => published.push(rows),
+    publishCockpitSignals,
+    pushCockpitSignal,
+    dropCockpitSignal,
+    dropContextSnapshotSignals,
+    updateCockpitSignals,
+  });
+  return () => published.at(-1).map((row) => row.title);
+}
+
+test('Contacts going off clears its contact rows and leaves standby', async (t) => {
+  const { owner } = fixture(t, snapshot());
+  const rows = withSignals(owner);
+  owner.services.isLayerEnabled = () => true;
+  updateContext.call(owner, INFO, 0);
+  assert.ok(
+    owner.signalItems.some((item) => item.key.startsWith('flight:')),
+    'Contacts fills the rows',
+  );
+  assert.ok(owner.signalItems.some((item) => item.key === 'input-status'));
+  // Both feeds stay on; only Contacts goes.
+  owner.snapshot = null;
+  updateContext.call(owner, INFO, 0);
+  assert.deepEqual(rows(), ['CONTEXT STANDBY']);
+  updateContext.call(owner, INFO, 0);
+  assert.deepEqual(rows(), ['CONTEXT STANDBY'], 'standby holds still');
+});
+
+test('Contacts going off with a feed off keeps the feed row beside standby', async (t) => {
+  const { owner } = fixture(t, snapshot());
+  const rows = withSignals(owner);
+  owner.services.isLayerEnabled = (layerId) => layerId !== 'military';
+  updateContext.call(owner, INFO, 0);
+  owner.snapshot = null;
+  updateContext.call(owner, INFO, 0);
+  assert.deepEqual(rows(), [
+    'MILITARY FEED OFF · PARTIAL PICTURE',
+    'CONTEXT STANDBY',
+  ]);
+});
+
+test('standby without Contacts keeps the rows the session already shows', async (t) => {
+  const { owner } = fixture(t, null);
+  const rows = withSignals(owner);
+  owner.services.isLayerEnabled = () => true;
+  owner.pushCockpitSignal('track', 'track', 'TRACK ACQUIRED', 'UAL123');
+  updateContext.call(owner, INFO, 0);
+  assert.deepEqual(rows(), ['CONTEXT STANDBY', 'TRACK ACQUIRED']);
+});
+
 test('the weather toggle renders its state and the action it offers', async (t) => {
   const { $, text, owner } = fixture(t);
   syncWeatherToggle.call(owner, true);
diff --git a/src/ui/cockpitController.js b/src/ui/cockpitController.js
index 1e69146e3..6010c3ce7 100644
--- a/src/ui/cockpitController.js
+++ b/src/ui/cockpitController.js
@@ -51,6 +51,7 @@ import {
 } from './cockpitBriefing.js';
 import {
   dropCockpitSignal,
+  dropContextSnapshotSignals,
   handleSignalClick,
   publishCockpitSignals,
   pushCockpitSignal,
@@ -82,6 +83,7 @@ export class CockpitViewController {
       isUtilityDisclosureOpen = null,
       onEntered = null,
       onExited = null,
+      onRide = null,
       restoreTrackingFrame = null,
       publish = {},
     } = {},
@@ -121,6 +123,7 @@ export class CockpitViewController {
     this.onCameraTakeover = onCameraTakeover;
     this.onEntered = onEntered;
     this.onExited = onExited;
+    this.onRide = onRide;
     this.restoreTrackingFrame =
       typeof restoreTrackingFrame === 'function'
         ? restoreTrackingFrame
@@ -394,6 +397,9 @@ export class CockpitViewController {
   dropCockpitSignal(key) {
     return dropCockpitSignal.call(this, key);
   }
+  dropContextSnapshotSignals() {
+    return dropContextSnapshotSignals.call(this);
+  }
   updateCockpitSignals(snapshot, unknownCount, partialPicture) {
     return updateCockpitSignals.call(
       this,
diff --git a/src/ui/cockpitCoordinator.js b/src/ui/cockpitCoordinator.js
index 7140f3172..3839aa3af 100644
--- a/src/ui/cockpitCoordinator.js
+++ b/src/ui/cockpitCoordinator.js
@@ -97,6 +97,7 @@ export class CockpitCoordinator {
       isUtilityDisclosureOpen: () => !!this.readUtilityDisclosureOpen?.(),
       onEntered: () => this.enterPanels(),
       onExited: () => this.exitPanels(),
+      onRide: (layerId) => this._adoptRiddenLayer(layerId),
       restoreTrackingFrame: (entity) => {
         const [layerId, ...idParts] = String(entity?.gevTrackedId || '').split(
           ':',
@@ -127,6 +128,22 @@ export class CockpitCoordinator {
   _isLayerEnabled(layerId) {
     return Boolean(layerId) && !!this._dataManager?.isEnabled(layerId);
   }
+  /**
+   * Make the ridden aircraft's layer the user's own while Contacts is on.
+   * Contacts may have turned that layer on, and it releases the layers it
+   * owns when it goes off; the Cockpit must outlive Contacts, so riding an
+   * aircraft adopts its layer as a direct selection does. Contacts then stops
+   * owning it and the Context restore keeps it (session `userAdded`).
+   * @param {string|null} layerId The ridden aircraft's layer.
+   */
+  _adoptRiddenLayer(layerId) {
+    if (!COCKPIT_AIRCRAFT_LAYER_IDS.includes(layerId)) return;
+    if (!this._isLayerEnabled('military-awareness')) return;
+    this._dataManager?.adoptLayerVisibility?.(layerId, true, {
+      origin: 'user',
+      adoptedFromSelection: true,
+    });
+  }
   /** Whether either aircraft layer is on, so there is an aircraft to ride. */
   get _aircraftLayerEnabled() {
     return COCKPIT_AIRCRAFT_LAYER_IDS.some((layerId) =>
diff --git a/src/ui/cockpitEntryGate.test.mjs b/src/ui/cockpitEntryGate.test.mjs
index 5931ca5b2..834f1866f 100644
--- a/src/ui/cockpitEntryGate.test.mjs
+++ b/src/ui/cockpitEntryGate.test.mjs
@@ -1,13 +1,17 @@
 // src/ui/cockpitEntryGate.test.mjs — first person needs only the layer of
 // the vehicle it rides: Contacts and the other feeds may be off before or
-// during a session, turning the ridden layer off ends it, and the voice gate
-// and state say so without claiming Contacts is required. Over happy-dom.
+// during a session, turning the ridden layer off ends it, Contacts ending
+// keeps the ridden layer it had turned on, and the voice gate and state say
+// so without claiming Contacts is required. Over happy-dom.
 import '../testSupport/registerDom.mjs';
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { createPinia } from 'pinia';
 import { createApp, defineComponent, h, nextTick } from 'vue';
+import { DataLayerManager } from '../data/manager.js';
+import { createDependencies } from '../layers/awareness/dependencies.js';
 import { CockpitCoordinator } from './cockpitCoordinator.js';
+import { ContextControls } from './contextControls.js';
 import { _handleContextLayerChange } from './contextLayerChanges.js';
 import { useCockpitStore } from './stores/cockpit.js';
 import { useHudStore } from './stores/hud.js';
@@ -34,6 +38,8 @@ function fixture(
     tracked = null,
     contextMode = null,
     changing = false,
+    dataManager: suppliedManager = null,
+    readContext = null,
   } = {},
 ) {
   document.body.replaceChildren();
@@ -45,22 +51,29 @@ function fixture(
   app.mount(host);
   const store = useCockpitStore(pinia);
   const layers = new Set(enabled);
-  const dataManager = { isEnabled: (layerId) => layers.has(layerId) };
+  const dataManager = suppliedManager || {
+    isEnabled: (layerId) => layers.has(layerId),
+  };
   // A layer that is off has no tracked aircraft, as the flight layers clear
   // tracking on disable.
   const trackedFrom = (layerId) => () =>
-    tracked?.layerId === layerId && layers.has(layerId) ? tracked.info : null;
-  const entity = {
+    tracked?.layerId === layerId && dataManager.isEnabled(layerId)
+      ? tracked.info
+      : null;
+  const entityFor = (subject) => ({
     position: { getValue: () => null },
     show: true,
-    gevTrackedId: tracked ? `${tracked.layerId}:${tracked.info.icao24}` : '',
-  };
+    gevTrackedId: subject ? `${subject.layerId}:${subject.info.icao24}` : '',
+  });
+  const entities = new Set();
+  const entity = entityFor(tracked);
+  entities.add(entity);
   const listeners = () => ({ addEventListener: () => () => {} });
   const viewer = {
     trackedEntity: tracked ? entity : undefined,
     clock: { currentTime: null },
     camera: { cancelFlight() {}, frustum: { fov: 1, aspectRatio: 1 } },
-    entities: { contains: (candidate) => candidate === entity },
+    entities: { contains: (candidate) => entities.has(candidate) },
     scene: {
       preUpdate: listeners(),
       screenSpaceCameraController: { enableInputs: true },
@@ -86,7 +99,7 @@ function fixture(
         tracked ? { layerId: tracked.layerId, id: tracked.info.icao24 } : null,
     },
     readDataManager: () => dataManager,
-    readContext: () => context,
+    readContext: readContext || (() => context),
     readActiveStyle: () => 'normal',
     readUtilityDisclosureOpen: () => false,
     enterPanels() {},
@@ -125,8 +138,14 @@ function fixture(
       { type: 'visibility', layerId, enabled: false, origin: 'user' },
     );
   };
+  /** Track another aircraft, as Contacts navigation does mid-session. */
+  const retrack = (subject) => {
+    tracked = subject;
+    viewer.trackedEntity = entityFor(subject);
+    entities.add(viewer.trackedEntity);
+  };
   const $ = (selector) => document.querySelector(selector);
-  return { $, coordinator, cockpit, store, layers, disable, pinia };
+  return { $, coordinator, cockpit, store, layers, disable, retrack, pinia };
 }
 
 test('a civilian aircraft enters with Live Flights alone: no Contacts, no Military', (t) => {
@@ -232,3 +251,217 @@ test('the readout offers the same entry, labelled by kind, and enters on click',
   assert.equal(cockpit.active, true);
   assert.equal(readoutEntry.hidden, true, 'inside, there is nothing to enter');
 });
+
+const AIR_AND_SEA = [
+  'flights',
+  'military',
+  'ais-live-vessels',
+  'military-installations',
+];
+
+/** A source layer that settles at once, as the data manager drives it. */
+function sourceLayer(id) {
+  return {
+    id,
+    name: id,
+    icon: '',
+    source: 'test',
+    updateInterval: -1,
+    init() {},
+    enable() {},
+    disable() {},
+    update() {},
+    getStats: () => ({ count: 0, lastUpdate: null }),
+  };
+}
+
+/**
+ * Contacts as the manager sees it: a coordinator whose real dependency
+ * ownership (src/layers/awareness/dependencies.js) turns on the air and sea
+ * layers it finds off and releases them when it goes off.
+ */
+function contactsCoordinator() {
+  const state = {
+    dataManager: null,
+    enabled: false,
+    passive: true,
+    activationId: 0,
+    ownedDependencies: new Set(),
+    subject: null,
+    autoFocusRetryPending: false,
+  };
+  const dependencies = createDependencies({
+    state,
+    services: {},
+    parts: { subject: {}, focus: {} },
+    source: null,
+  });
+  return {
+    id: 'military-awareness',
+    name: 'Contacts',
+    icon: '',
+    source: 'test',
+    showInTogglePanel: false,
+    updateInterval: -1,
+    attachDataManager(dataManager) {
+      state.dataManager = dataManager;
+      dependencies.watchAdoptions(dataManager);
+    },
+    setParams(params = {}) {
+      if (typeof params.passive === 'boolean') state.passive = params.passive;
+    },
+    getParams: () => ({ passive: state.passive }),
+    init() {},
+    enable() {
+      state.enabled = true;
+      if (!state.passive) return dependencies.enableDependencies();
+      return true;
+    },
+    disable() {
+      state.enabled = false;
+      state.passive = true;
+      return dependencies.releaseOwnedDependencies(++state.activationId);
+    },
+    update() {},
+    getStats: () => ({ count: 0, lastUpdate: null }),
+  };
+}
+
+/**
+ * The Cockpit beside the real Context owner and data manager, so a Contacts
+ * exit runs its whole restore: the coordinator's releases, then the snapshot.
+ */
+async function liveFixture(t, { enabled = [], tracked = null } = {}) {
+  const manager = new DataLayerManager({});
+  for (const layerId of AIR_AND_SEA) manager.register(sourceLayer(layerId));
+  const coordinatorModule = contactsCoordinator();
+  manager.register(coordinatorModule);
+  coordinatorModule.attachDataManager(manager);
+  for (const layerId of enabled) await manager.setEnabled(layerId, true);
+  let cockpit = null;
+  const controls = new ContextControls({
+    elements: {},
+    installations: {},
+    actions: {
+      getCockpit: () => cockpit,
+      claimVisualAuthority() {},
+      showToast() {},
+      setClearBusy() {},
+      syncDetection() {},
+      scheduleLayout() {},
+      refreshRadio() {},
+      setPanelCollapsed() {},
+    },
+  });
+  controls.connect(manager);
+  t.after(() => {
+    controls.stop();
+    controls.disconnect();
+  });
+  const base = fixture(t, {
+    tracked,
+    dataManager: manager,
+    readContext: () => controls.getContextModeState(),
+  });
+  cockpit = base.cockpit;
+  /** Let every Context reaction the last change started settle. */
+  const settle = async () => {
+    for (let turn = 0; turn < 5; turn += 1) {
+      await controls._waitForContextLayerSettlement();
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+  };
+  return { ...base, manager, controls, settle };
+}
+
+const on = (manager) =>
+  [...AIR_AND_SEA, 'military-awareness'].filter((layerId) =>
+    manager.isEnabled(layerId),
+  );
+
+test('Contacts ending in a Cockpit session keeps the ridden layer it had turned on', async (t) => {
+  for (const [label, endContacts] of [
+    [
+      'Military Flights off',
+      ({ manager }) =>
+        manager.setEnabled('military', false, { origin: 'user' }),
+    ],
+    [
+      'Contacts off by its own layer',
+      ({ manager }) =>
+        manager.setEnabled('military-awareness', false, { origin: 'user' }),
+    ],
+    [
+      'Contacts off from its chooser',
+      ({ controls }) => controls._selectContextMode(null),
+    ],
+  ]) {
+    await t.test(label, async (t) => {
+      // Live Flights is off on the map; Contacts turns it on as its own.
+      const live = await liveFixture(t, {
+        tracked: { layerId: 'flights', info: CIVIL },
+      });
+      const { manager, controls, cockpit, settle } = live;
+      assert.equal(await controls._selectContextMode('flights'), true);
+      await settle();
+      assert.deepEqual(on(manager), [...AIR_AND_SEA, 'military-awareness']);
+      assert.equal(cockpit.enter(), true);
+      await endContacts(live);
+      await settle();
+      assert.equal(controls.getContextModeState().mode, null, 'Contacts ended');
+      assert.equal(cockpit.active, true, 'the Cockpit rides on');
+      assert.deepEqual(
+        on(manager),
+        ['flights'],
+        'only the ridden layer outlives the pre-Contacts restore',
+      );
+    });
+  }
+});
+
+test('a ride handed to an aircraft on a layer Contacts turned on keeps that layer', async (t) => {
+  const live = await liveFixture(t, {
+    enabled: ['flights'],
+    tracked: { layerId: 'flights', info: CIVIL },
+  });
+  const { manager, controls, cockpit, retrack, settle } = live;
+  assert.equal(await controls._selectContextMode('flights'), true);
+  await settle();
+  assert.equal(cockpit.enter(), true);
+  // NEXT hands the view to a military aircraft; Contacts turned its layer on.
+  retrack({ layerId: 'military', info: MILITARY });
+  assert.equal(cockpit._adoptTrackedEntity(performance.now()), true);
+  assert.equal(cockpit.readSubjectLayerId(), 'military');
+  await manager.setEnabled('ais-live-vessels', false, { origin: 'user' });
+  await settle();
+  assert.equal(controls.getContextModeState().mode, null);
+  assert.equal(cockpit.active, true);
+  assert.deepEqual(on(manager), ['flights', 'military']);
+});
+
+test('the ridden layer still ends the Cockpit while Contacts is on', async (t) => {
+  const live = await liveFixture(t, {
+    tracked: { layerId: 'flights', info: CIVIL },
+  });
+  const { manager, controls, cockpit, settle } = live;
+  assert.equal(await controls._selectContextMode('flights'), true);
+  await settle();
+  assert.equal(cockpit.enter(), true);
+  await manager.setEnabled('flights', false, { origin: 'user' });
+  await settle();
+  assert.equal(cockpit.active, false);
+  assert.equal(manager.isEnabled('flights'), false);
+});
+
+test('without a Cockpit, ending Contacts restores the layers it found', async (t) => {
+  const live = await liveFixture(t, {
+    tracked: { layerId: 'flights', info: CIVIL },
+  });
+  const { manager, controls, settle } = live;
+  assert.equal(await controls._selectContextMode('flights'), true);
+  await settle();
+  await manager.setEnabled('military', false, { origin: 'user' });
+  await settle();
+  assert.equal(controls.getContextModeState().mode, null);
+  assert.deepEqual(on(manager), [], 'Live Flights goes back off');
+});
diff --git a/src/ui/cockpitSignals.js b/src/ui/cockpitSignals.js
index 395db8116..32f25bdc8 100644
--- a/src/ui/cockpitSignals.js
+++ b/src/ui/cockpitSignals.js
@@ -74,6 +74,27 @@ export function dropCockpitSignal(key) {
   this.publishCockpitSignals();
 }
 
+/** Whether a row is one a Contacts snapshot builds, with its status rows. */
+const isContextSnapshotRow = (key) =>
+  key.startsWith('flight:') ||
+  ['input-status', 'feed-status', 'context-status'].includes(key);
+
+/**
+ * Take off every row a Contacts snapshot built, as when Contacts goes off:
+ * its contacts, distances and CURRENT would otherwise read as live. Rows the
+ * session made without Contacts, such as TRACK ACQUIRED, stay.
+ */
+export function dropContextSnapshotSignals() {
+  for (const key of [...this.signalSignatures.keys()])
+    if (isContextSnapshotRow(key)) this.signalSignatures.delete(key);
+  const kept = this.signalItems.filter(
+    (item) => !isContextSnapshotRow(item.key),
+  );
+  if (kept.length === this.signalItems.length) return;
+  this.signalItems = kept;
+  this.publishCockpitSignals();
+}
+
 /**
  * Rebuild the rows from a Contacts snapshot: the nearest flights, a row for
  * unknown inputs and, first, a row naming an air feed that is off.
diff --git a/src/ui/cockpitTrackingController.js b/src/ui/cockpitTrackingController.js
index 3ad6267ff..8675f3908 100644
--- a/src/ui/cockpitTrackingController.js
+++ b/src/ui/cockpitTrackingController.js
@@ -155,6 +155,7 @@ export function _adoptTrackedEntity(nowMs, suppliedInfo = null) {
   this.lastContextUpdateMs = 0;
   this.lastCameraUpdateMs = 0;
   this.contextNavigationDeadlineMs = 0;
+  this.onRide?.(info.layerId);
   this.dispatchCockpitModeChanged(true, info);
   return true;
 }
@@ -230,6 +231,7 @@ export function enter() {
       this.mapViewButton?.focus({ preventScroll: true });
   });
   this.onEntered?.();
+  this.onRide?.(info.layerId);
   this.dispatchCockpitModeChanged(true, info);
   return true;
 }

From 395eba4548c1b7a7004f528760dff16c16909ab2 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 15:38:32 -0800
Subject: [PATCH 49/71] Fit the tilt wording under the Realtime prompt ceiling

With main merged, the Overpass prompt measured 55,549 against the 55,500 ceiling. The pitchDeg and direction descriptions now read 'Absolute; -89 top-down.' and 'Needed for pan/rotate/tilt steps', bringing it to 55,497. The schema pin and the measured-size note follow.
---
 server/providers/openai/toolDescriptions.js | 5 ++---
 src/radioMarkup.test.mjs                    | 6 +++---
 src/voice/actionSchemas.test.mjs            | 2 +-
 src/voice/pointAndAsk.test.mjs              | 7 ++++---
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/server/providers/openai/toolDescriptions.js b/server/providers/openai/toolDescriptions.js
index 1deff2335..f4000ddad 100644
--- a/server/providers/openai/toolDescriptions.js
+++ b/server/providers/openai/toolDescriptions.js
@@ -523,7 +523,7 @@ export const ACTION_DESCRIPTIONS = {
       properties: {
         direction: {
           description:
-            'Required for pan/rotate and a tilt nudge; orbit/rotate_globe default right.',
+            'Needed for pan/rotate/tilt steps; orbit/rotate_globe default right.',
           $position: 2,
         },
         mode: {
@@ -532,8 +532,7 @@ export const ACTION_DESCRIPTIONS = {
           $position: 2,
         },
         pitchDeg: {
-          description:
-            'Absolute; steps use direction. -45 oblique (default), -89 top-down.',
+          description: 'Absolute; -89 top-down.',
           $position: 1,
         },
       },
diff --git a/src/radioMarkup.test.mjs b/src/radioMarkup.test.mjs
index 6e72d6318..3c59d989d 100644
--- a/src/radioMarkup.test.mjs
+++ b/src/radioMarkup.test.mjs
@@ -232,14 +232,14 @@ test('no unchanged Realtime tool definition drifts silently', () => {
     camera.description,
     'Direct the camera like a drone operator: orbit the current view target, pan, tilt, or rotate — one bounded nudge (mode=once) or continuous motion until stopped (mode=continuous). Continuous motion also stops on any manual camera input or when a navigation tool runs. Say the RESULTING state when confirming ("Orbiting slowly"). Globe rotation (rotate_globe) spins Earth right continuously by default; explicit direction, mode and speed take precedence. It checks fit and may refuse.',
   );
-  // Tilt to an angle adds pitchDeg and says a tilt nudge needs a
+  // Tilt to an angle adds an absolute pitchDeg and says tilt steps need a
   // direction; check them, then restore the legacy fields for the pin.
   assert.equal(
     camera.parameters.properties.direction.description,
-    'Required for pan/rotate and a tilt nudge; orbit/rotate_globe default right.',
+    'Needed for pan/rotate/tilt steps; orbit/rotate_globe default right.',
   );
   assert.equal(camera.parameters.properties.pitchDeg.type, 'number');
-  assert.match(camera.parameters.properties.pitchDeg.description, /-45 oblique/);
+  assert.match(camera.parameters.properties.pitchDeg.description, /^Absolute;/);
   delete camera.parameters.properties.pitchDeg;
   assert.equal(camera.parameters.properties.mode.description, 'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.');
   camera.parameters.properties.mode.description = 'once = bounded eased nudge (default); continuous = until stop/manual input.';
diff --git a/src/voice/actionSchemas.test.mjs b/src/voice/actionSchemas.test.mjs
index 13f593204..fa9d40bec 100644
--- a/src/voice/actionSchemas.test.mjs
+++ b/src/voice/actionSchemas.test.mjs
@@ -58,7 +58,7 @@ test('the complete Realtime tool payload pins the manifest-generated layer relea
     // control_cockpit states the own-layer entry rule (Contacts not required).
     // move_camera tilt takes an optional pitchDeg angle, described as
     // absolute, with steps sent as a direction.
-    '8698aee3cf691351f5c5a68e115a5913ec0f048067ecdf34b252a31afeeec737',
+    '17e54c1a04054edf48f2eddcf88c60ac66ec7c885fb48596b778bfee0be8a544',
   );
 });
 
diff --git a/src/voice/pointAndAsk.test.mjs b/src/voice/pointAndAsk.test.mjs
index 1f1993a07..c413477b8 100644
--- a/src/voice/pointAndAsk.test.mjs
+++ b/src/voice/pointAndAsk.test.mjs
@@ -350,9 +350,10 @@ test('deixis prompt lint: one short rule, and every sentinel it names exists in
   // the analyst area scopes) raised the ceiling to 55,500; tightening the
   // AREAS rule and the area tool descriptions left it at 55,103 as measured
   // below (every tool, osm_query included); main's Sea Marks and Ski Pistes
-  // layers bring it to 55,210, and the tilt pitchDeg argument to 55,335.
-  // integrationContract's Overpass prompt is the tightest, at 55,495 (5
-  // under). A new tool or rule has to fit under this ceiling.
+  // layers bring it to 55,210, and the tilt pitchDeg argument with main's
+  // cockpit entry rule to 55,337. integrationContract's Overpass prompt is
+  // the tightest, at 55,497 (3 under). A new tool or rule has to fit under
+  // this ceiling.
   const size = instructions.length + JSON.stringify(GEV_REALTIME_TOOLS).length;
   assert.ok(size <= 55_500, `prompt size ${size}`);
 });

From c4910d24d03713056affaad92dd67f72606daa98 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 15:43:51 -0800
Subject: [PATCH 50/71] Keep the place centred when a far tilt reaches the
 horizon
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From 550 to 1,000 km of range the camera's -5° limit lies past the place's own horizon. The swing ran into its 150 m clearance, let go of the pivot and tilted the rest in place, which lifted the crosshair onto the sky (28 to 63 km up from 600 to 900 km), and a return to top-down then landed hundreds of km from the place.

The swing now hands over to an in-place tilt only where the clearance is what stops it (within about 17 km). Farther out it stops with the camera 0.5° above the place's horizon, still pivoting: a tilt to an angle reports the angle it reached with a note, a continuous tilt stops there, and a further tilt up is refused as at the limit. Tests check that the crosshair stays on the place, frame by frame for a continuous tilt, and that top-down returns over it.
---
 docs/CURRENT-STATE.md   |   2 +-
 src/cameraTilt.test.mjs |  61 ++++++++++++++++++-
 src/cameraVerbs.js      | 132 +++++++++++++++++++++++++++++++++-------
 3 files changed, 169 insertions(+), 26 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 4b322618c..3166ab976 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5590,7 +5590,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index a82b2ce37..a67ecee86 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -460,10 +460,10 @@ test('from globe range a tilt happens in place', (t) => {
   assert.ok(Cesium.Cartesian3.distance(h.camera.positionWC, before) < 1e-3);
 });
 
-for (const height of [100_000, 400_000, 900_000])
+for (const height of [100_000, 400_000])
   test(`from ${height / 1000} km a tilt to -5° ends with the camera at -5°`, (t) => {
-    // The pivot pitch is shallower than the camera's by up to 8° at this
-    // range; the camera reached only -5.9° to -12.9° when the swing stopped
+    // The pivot pitch is shallower than the camera's by up to 4° at this
+    // range; the camera reached only -5.9° and -8.6° when the swing stopped
     // at a pivot pitch of -5°.
     const h = harness(t, { height });
     const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
@@ -479,6 +479,61 @@ for (const height of [100_000, 400_000, 900_000])
     assert.match(nudge.error, /upper tilt limit/);
   });
 
+// From 550 km out the camera's -5° lies beyond the place's own horizon: the
+// swing ran into its clearance, let go of the pivot and tilted the rest in
+// place, which put the crosshair on the sky (28 to 63 km up), and a return
+// to top-down then landed 600 to 900 km from the place.
+for (const height of [600_000, 700_000, 900_000]) {
+  test(`from ${height / 1000} km a tilt to -5° keeps the place centred`, (t) => {
+    const h = harness(t, { height });
+    const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
+    assert.equal(result.ok, true);
+    h.finish();
+    assert.ok(h.viewTarget(), 'the crosshair is on the sky');
+    assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
+    assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
+    // The reply names the angle the camera reached, not the one asked for.
+    assert.ok(result.pitchDeg < -5, `reported ${result.pitchDeg}°`);
+    assert.ok(
+      Math.abs(pitchDeg(h.camera) - result.pitchDeg) < 0.5,
+      `camera at ${pitchDeg(h.camera)}°, reported ${result.pitchDeg}°`,
+    );
+    assert.match(result.note, /horizon/);
+    const nudge = moveCamera({ motion: 'tilt', direction: 'up' });
+    assert.equal(nudge.ok, false);
+    assert.match(nudge.error, /upper tilt limit/);
+    assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -89 }).ok, true);
+    h.finish();
+    assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
+    // Back over the place at the range it began with (-89° is ~1° off nadir).
+    const range = Cesium.Cartesian3.distance(h.camera.positionWC, h.target);
+    assert.ok(
+      Math.abs(range - height) < height * 0.01,
+      `top-down ${range} m from the place`,
+    );
+  });
+
+  test(`a continuous tilt up from ${height / 1000} km stops with the place centred`, (t) => {
+    const h = harness(t, { height });
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+    for (let i = 0; i < 1200 && getActiveCameraMotion(); i += 1) {
+      h.tick();
+      assert.ok(h.viewTarget(), `the crosshair is on the sky at frame ${i}`);
+    }
+    assert.equal(getActiveCameraMotion(), null, 'tilt must stop at its limit');
+    assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
+  });
+}
+
+test('a pitchDeg tilt toward the horizon limit says it is already there', (t) => {
+  const h = harness(t, { height: 900_000 });
+  moveCamera({ motion: 'tilt', pitchDeg: 5 });
+  h.finish();
+  const again = moveCamera({ motion: 'tilt', pitchDeg: 5 });
+  assert.equal(again.ok, false);
+  assert.match(again.error, /upper tilt limit/);
+});
+
 test('a regional tilt-up nudge goes to the camera horizon limit', (t) => {
   // 20 km up at -7°: the pivot 186 km out sits at -5.3°, but the camera can
   // still tilt up 2°.
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 70b83eff5..4618a434d 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -62,6 +62,13 @@ const TILT_MIN_CLEARANCE_M = 150;
  * crosshair point, so the tilt happens in place instead.
  */
 const TILT_PIVOT_MAX_RANGE_M = 1_000_000;
+/**
+ * The shallowest a pivot swing goes when its clearance is not what stops it.
+ * From several hundred km the camera's own horizon limit lies past the
+ * 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);
 
 /* ── Route dolly: cinematic tuning ──────────────────────────────────────────
  * Every knob an owner may want to retune lives in this block. The shaping is
@@ -1273,7 +1280,10 @@ function onTick() {
  * is clamped to [-89°, -5°] only in the direction of travel: a top-down view
  * sits at -90°, below the limit, and must still be able to tilt up out of it.
  * A pivot swing toward the horizon lowers the camera, so it stops at
- * TILT_MIN_CLEARANCE_M and the rest tilts in place.
+ * TILT_MIN_CLEARANCE_M and the rest tilts in place. Farther out it stops with
+ * the camera TILT_MIN_PIVOT_ELEVATION above the place's horizon instead, and
+ * 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;
@@ -1288,11 +1298,13 @@ function tickTilt(cam, m, scale, dt) {
   const limited = up
     ? Math.min(want, Math.max(from, PITCH_MAX))
     : Math.max(want, Math.min(from, PITCH_MIN));
+  let atLimit = false;
   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);
-    // Up toward the horizon the swing lowers the camera: hold the clearance.
+    // 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;
@@ -1309,21 +1321,77 @@ function tickTilt(cam, m, scale, dt) {
     // this last step re-took it.
     if (_active !== m) clearLookAt();
     if (up && m.hpr.pitch >= cap && cam.pitch < limited - 1e-6) {
-      // Down to its clearance: let go of the pivot and tilt the rest in
-      // place, which keeps the height.
-      if (_active === m) clearLookAt();
-      m.hpr = null;
-      m.target = null;
+      if (tiltClearanceBinds(m.hpr.range)) {
+        // Down to its clearance: let go of the pivot and tilt the rest in
+        // place, which keeps the height.
+        if (_active === m) clearLookAt();
+        m.hpr = null;
+        m.target = null;
+      } else {
+        // The place is at its horizon limit: stop here, still centred.
+        atLimit = true;
+      }
     }
   }
   if (!m.hpr) cam.lookUp(limited - cam.pitch);
-  if (m.mode !== 'once' && limited !== want)
+  if (m.mode !== 'once' && (limited !== want || atLimit))
     interruptCameraMotion('tilt-clamp');
 }
 
+/** The refusal for a tilt up the camera has no room left for. */
+function tiltUpLimitRefusal() {
+  return {
+    ok: false,
+    action: 'move_camera',
+    error:
+      'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
+  };
+}
+
 /** Shallowest pivot pitch that keeps the clearance at this range. */
 function tiltPivotPitchMax(range) {
-  return -Math.asin(Math.min(1, TILT_MIN_CLEARANCE_M / range));
+  return Math.min(
+    -Math.asin(Math.min(1, TILT_MIN_CLEARANCE_M / range)),
+    -TILT_MIN_PIVOT_ELEVATION,
+  );
+}
+
+/**
+ * Whether the clearance, not the horizon, stops a swing at this range. Only
+ * then does the rest of the tilt happen in place: that close in (under ~17
+ * km) the camera's -5° limit stays well below its own horizon.
+ */
+function tiltClearanceBinds(range) {
+  return TILT_MIN_CLEARANCE_M / range >= Math.sin(TILT_MIN_PIVOT_ELEVATION);
+}
+
+/**
+ * The shallowest camera pitch a tilt starting from this frame can reach with
+ * the place under the crosshair still in view: PITCH_MAX, or less where a
+ * far pivot meets its horizon limit first.
+ */
+function tiltUpLimit({ target, pivot }) {
+  if (!pivot || tiltClearanceBinds(pivot.range)) return PITCH_MAX;
+  const pitch = Math.max(pivot.pitch, tiltPivotPitchMax(pivot.range));
+  // The camera's position for that pivot pitch, as lookAt places it.
+  const offset = new Cesium.Cartesian3(
+    -pivot.range * Math.cos(pitch) * Math.sin(pivot.heading),
+    -pivot.range * Math.cos(pitch) * Math.cos(pivot.heading),
+    -pivot.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.min(
+    PITCH_MAX,
+    Math.asin(Cesium.Math.clamp(Cesium.Cartesian3.dot(look, upAtEye), -1, 1)),
+  );
 }
 
 /**
@@ -1710,17 +1778,22 @@ export function moveCamera(args = {}, runNavigation = null) {
         error: `pitchDeg is an absolute angle, not a step: ${target}° from ${now}° tilts ${towards}, not ${direction}. Send direction alone for a nudge, or pitchDeg alone for an angle.`,
       };
     }
+    if (
+      towards === 'up' &&
+      from >=
+        tiltUpLimit(tiltStartFrame(_viewer.camera)) - Cesium.Math.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;
-    if (direction === 'up' && pitch >= PITCH_MAX - Cesium.Math.toRadians(0.5)) {
-      return {
-        ok: false,
-        action: 'move_camera',
-        error:
-          'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
-      };
+    if (
+      direction === 'up' &&
+      pitch >=
+        tiltUpLimit(tiltStartFrame(_viewer.camera)) - Cesium.Math.toRadians(0.5)
+    ) {
+      return tiltUpLimitRefusal();
     }
     if (
       direction === 'down' &&
@@ -1816,6 +1889,7 @@ export function moveCamera(args = {}, runNavigation = null) {
         error: 'Globe rotation requires a clear ellipsoid bounding sphere.',
       };
   }
+  let horizonLimited = null;
   const start = () => {
     interruptCameraMotion('replaced');
     const state = {
@@ -1825,27 +1899,36 @@ export function moveCamera(args = {}, runNavigation = null) {
       mode,
     };
     if (motion === 'tilt') {
-      const { target, pivot, from } = tiltStartFrame(_viewer.camera);
+      const frame = tiltStartFrame(_viewer.camera);
+      const { target, pivot, from } = frame;
       if (pivot) {
         state.target = target;
         state.hpr = pivot;
       }
       state.startPitch = from;
+      const upLimit = tiltUpLimit(frame);
       if (tiltToPitch !== null) {
+        // From far out the place reaches its horizon before the camera
+        // reaches the asked angle: stop there, and say so.
+        const goal =
+          tiltToPitch > from
+            ? Math.min(tiltToPitch, Math.max(from, upLimit))
+            : tiltToPitch;
         state.mode = 'once';
-        state.direction = tiltToPitch > from ? 'up' : 'down';
-        state.goalPitch = tiltToPitch;
+        state.direction = goal > from ? 'up' : 'down';
+        state.goalPitch = goal;
         state.durationS = Math.max(
           ONCE.durationS,
-          Math.abs(Cesium.Math.toDegrees(tiltToPitch - from)) / TILT_TO_DEG_S,
+          Math.abs(Cesium.Math.toDegrees(goal - from)) / TILT_TO_DEG_S,
         );
+        if (goal !== tiltToPitch) horizonLimited = goal;
       } else {
         // A nudge stops at the limit it travels toward.
         const step =
           Cesium.Math.toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1);
         state.goalPitch =
           step > 0
-            ? Math.min(from + step, Math.max(from, PITCH_MAX))
+            ? Math.min(from + step, Math.max(from, upLimit))
             : Math.max(from + step, Math.min(from, PITCH_MIN));
       }
     }
@@ -1937,7 +2020,12 @@ export function moveCamera(args = {}, runNavigation = null) {
       speed,
       mode: state.mode,
       ...(tiltToPitch !== null && {
-        pitchDeg: Math.round(Cesium.Math.toDegrees(tiltToPitch)),
+        pitchDeg: Math.round(
+          Cesium.Math.toDegrees(horizonLimited ?? tiltToPitch),
+        ),
+      }),
+      ...(horizonLimited !== null && {
+        note: `Stopped at ${Math.round(Cesium.Math.toDegrees(horizonLimited))}°: from this range a shallower angle puts the place past the horizon. Zoom in to tilt further.`,
       }),
     };
   };

From 1eef14454ae7bb2b3868578978897c00ed6383a3 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 15:48:21 -0800
Subject: [PATCH 51/71] Drop a queued voice motion when another navigation
 takes the camera mid-flight

A motion queued behind a voice fly-to checked only that its reply was current and that the user had not touched the map. A location-panel search, share link or file import stamps a deferred navigation without stopping the flight, so the flight landed, the motion took navigation, and the search's reassert then failed: the search was silently dropped while the camera kept orbiting.

The runner now counts camera handoffs from subscribeCameraHandoff, less the ones voice fly-tos make themselves, and each voice flight records that count when it starts. A motion whose flight saw another navigation since then is not run and says so. Voice fly-tos' own stamps do not count, so a later fly-to in the same reply, including a lookup that finds nothing, is still followed as before. The test harness now publishes handoffs and stamps its voice lookups, as the shell does.
---
 docs/CURRENT-STATE.md         |  2 +-
 src/voice/gevActions.js       | 26 ++++++++++
 src/voice/gevActions.test.mjs | 91 +++++++++++++++++++++++++++++++++--
 3 files changed, 113 insertions(+), 6 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 3166ab976..2f269ee48 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5590,7 +5590,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, or the user grabs, touches or scrolls the map during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index 5a30a8cf3..045969a4f 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -296,6 +296,16 @@ export function createGevActionRunner({
   let voiceFlight = null;
   // Waiters to tell when a newer voice flight begins.
   const voiceFlightWatchers = new Set();
+  // Camera handoffs (navigation stamps) seen, and how many of them voice
+  // fly-tos made. A search, share link or import that stamps during a flight
+  // leaves it flying; the motion queued behind it then yields to that one.
+  let cameraHandoffs = 0;
+  let voiceFlightHandoffs = 0;
+  const otherHandoffs = () => cameraHandoffs - voiceFlightHandoffs;
+  const unsubscribeCameraHandoff =
+    styleManager?.subscribeCameraHandoff?.(() => {
+      cameraHandoffs += 1;
+    }) ?? null;
   let analystEngine;
   // Area handles live for this runner (the page): resolve_area, the
   // analyst's region/area/drawn scopes, find_imagery and osm_query all read
@@ -1155,6 +1165,8 @@ export function createGevActionRunner({
         prior && !prior.done ? prior.inputCount : undefined,
         prior,
       );
+      // Navigation by anything but a voice fly-to since this one began.
+      flight.handoffs = otherHandoffs();
       voiceFlight = flight;
       for (const notify of [...voiceFlightWatchers]) notify();
       // A motion already running (one the model sent before this fly-to) is
@@ -1164,9 +1176,13 @@ export function createGevActionRunner({
         (hook) =>
         (...hookArgs) => {
           const before = getActiveCameraMotion();
+          const handoffsBefore = cameraHandoffs;
           try {
             return hook(...hookArgs);
           } finally {
+            // A voice fly-to's own stamps are not another navigation, even
+            // for the flight it replaces (a later lookup may find nothing).
+            voiceFlightHandoffs += cameraHandoffs - handoffsBefore;
             if (
               before &&
               !stoppedMotion &&
@@ -1383,6 +1399,15 @@ export function createGevActionRunner({
             motion,
             error: `Not run: the user moved the camera during the flight, so the ${motion} was dropped.`,
           };
+        // A search, share link or import that took navigation during the
+        // flight leaves it flying; running now would cancel that navigation.
+        if (otherHandoffs() !== flight.handoffs)
+          return {
+            ok: false,
+            action: 'move_camera',
+            motion,
+            error: `Not run: another navigation took the camera during the flight, so the ${motion} was dropped.`,
+          };
       }
       return moveCamera(args, (navigate, releaseOptions) =>
         runManagedVoiceNavigation(
@@ -1712,6 +1737,7 @@ export function createGevActionRunner({
     if (disposed) return;
     runVoiceAction.resetConversation();
     disposed = true;
+    unsubscribeCameraHandoff?.();
     voiceAreas.dispose();
   };
   return runVoiceAction;
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index b2cdbedc4..f94eb554b 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -143,6 +143,14 @@ test('track_entity runner narrates a callsign-less aircraft by its registration'
 function createVoiceNavigationHarness({ cockpitActive = false } = {}) {
   const order = [];
   let generation = 0;
+  // Camera handoffs, published on every navigation stamp as the shell does.
+  const handoffListeners = new Set();
+  const stamp = (noun) => {
+    generation += 1;
+    order.push(`stamp:${noun}`);
+    for (const listener of [...handoffListeners]) listener({ generation });
+    return generation;
+  };
   const position = Cesium.Cartesian3.fromDegrees(-97.74, 30.26, 500);
   const viewer = {
     trackedEntity: { id: 'prior-aircraft' },
@@ -179,11 +187,7 @@ function createVoiceNavigationHarness({ cockpitActive = false } = {}) {
       return runExplicitNavigation({
         cockpitActive,
         noun,
-        stamp: () => {
-          generation += 1;
-          order.push(`stamp:${noun}`);
-          return generation;
-        },
+        stamp: () => stamp(noun),
         release: () => {
           order.push('release');
           viewer.trackedEntity = undefined;
@@ -195,12 +199,21 @@ function createVoiceNavigationHarness({ cockpitActive = false } = {}) {
       });
     },
     getDetectionState: () => ({ detectionMode: 'DENSE' }),
+    subscribeCameraHandoff(listener) {
+      handoffListeners.add(listener);
+      return () => handoffListeners.delete(listener);
+    },
+    // A voice lookup stamps when it begins and leaves any flight flying.
+    beginDeferredLocationNavigation: () => stamp('location-lookup'),
+    reassertDeferredLocationNavigation: (stamped) => stamped === generation,
   };
   return {
     order,
     viewer,
     styleManager,
     currentGeneration: () => generation,
+    // A location-panel search: a deferred stamp that leaves a flight flying.
+    panelSearch: () => stamp('panel-search'),
   };
 }
 
@@ -921,6 +934,74 @@ test('a motion follows a newer fly-to that lands while its own lookup stalls', a
   assert.equal(result.motion, 'orbit');
 });
 
+// "Fly to Paris and orbit it", then a location-panel search while the camera
+// flies: the search stamps a deferred navigation without stopping the flight.
+// Run where the flight landed, the orbit took navigation and the search's
+// reassert failed, so the search was silently dropped.
+test('a motion queued behind a fly-to yields to a search started during the flight', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, flights, panelSearch, currentGeneration } =
+    tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'orbit' });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  const search = panelSearch();
+  flights[0].complete();
+  const result = await moved;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /Not run: another navigation took the camera/);
+  assert.equal(getActiveCameraMotion(), null);
+  assert.equal(currentGeneration(), search, 'the search still owns navigation');
+});
+
+test('a motion behind a geocoded fly-to yields to a search started while it flies', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, panelSearch } = tiltAfterFlightHarness();
+  const searches = [];
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
+      searches.push({ query, options, resolve });
+    }),
+  });
+  const fly = runner('fly_to_location', { query: 'Place A' });
+  const moved = runner('move_camera', { motion: 'orbit' });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  searches[0].resolve({ label: 'Place A', navigationMode: 'city-overview' });
+  assert.equal((await fly).ok, true);
+  panelSearch();
+  searches[0].options.onComplete();
+  const result = await moved;
+  assert.equal(result.ok, false);
+  assert.match(result.error, /another navigation took the camera/);
+  assert.equal(getActiveCameraMotion(), null);
+});
+
+test('a search before the fly-to does not drop the motion queued behind it', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, flights, panelSearch } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  panelSearch();
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
+  const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  flights[0].complete();
+  const result = await moved;
+  assert.equal(result.ok, true);
+  assert.equal(result.motion, 'tilt');
+});
+
 test('a fly-to that stops a running motion says so', async (t) => {
   t.after(() => interruptCameraMotion('test-cleanup'));
   const { viewer, styleManager } = tiltAfterFlightHarness();

From dae95e1c7f866d07dba57f10c5bd0675378eba0c Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 15:51:14 -0800
Subject: [PATCH 52/71] Refuse a motion after its reply's fly-to found nothing,
 also on Gemini

Gemini runs one turn's calls one after another. By the time "pan left" ran beside "fly to Xyzzyville", the lookup had already found nothing, so there was no flight to wait on and the pan moved the old view with ok: true. OpenAI's parallel calls refused the same reply.

The runner now remembers, for the latest reply that sent a voice fly-to, whether one moved the camera and whether one found nothing. A tilt, orbit, pan or rotate of that reply with no flight left to wait on is refused when its fly-to found nothing and none moved. The reply is Gemini's turn, passed as a per-turn reply object, or OpenAI's authorityGroup. A motion in a later reply, or beside a fly-to of the same reply that did land, runs as before.
---
 docs/CURRENT-STATE.md            |  2 +-
 src/voice/geminiSession.js       |  9 ++++
 src/voice/geminiSession.test.mjs | 28 ++++++++++++
 src/voice/gevActions.js          | 41 ++++++++++++++++++
 src/voice/gevActions.test.mjs    | 74 ++++++++++++++++++++++++++++++++
 5 files changed, 153 insertions(+), 1 deletion(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 2f269ee48..9036db387 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5590,7 +5590,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. A motion that runs after a fly-to of the same reply has already found nothing (Gemini runs one turn's calls one by one, and passes its turn as the reply) is refused the same way rather than moving the old view; a motion in a later reply runs. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/voice/geminiSession.js b/src/voice/geminiSession.js
index da93b4bb6..8996774b3 100644
--- a/src/voice/geminiSession.js
+++ b/src/voice/geminiSession.js
@@ -184,6 +184,9 @@ export class GeminiSessionController {
     this.model = null;
     this.epoch = 0;
     this.turn = 0;
+    // Identifies one turn's tool calls to the runner as one reply; a new
+    // object each turn, so no two sessions or turns share it.
+    this.turnReply = {};
     this.globeToolsBlocked = false;
     this.globeResetFailed = false;
     this.inputGeneration = 0;
@@ -971,6 +974,7 @@ export class GeminiSessionController {
     const tools = [...this.tools.values()];
     this.turnAbort = new AbortController();
     this.turn++;
+    this.turnReply = {};
     this.typedIntent = null;
     this.radioStrongerCommit = null;
     this.pruneControls();
@@ -1544,6 +1548,7 @@ export class GeminiSessionController {
     )
       throw new Error(msg('Gemini requested too many simultaneous actions'));
     const turn = this.turn;
+    const reply = this.turnReply;
     this.userTurnPending = false;
     this.modelComplete = false;
     // Admit each valid native call ID once per connection.
@@ -1565,6 +1570,7 @@ export class GeminiSessionController {
       const action = new AbortController();
       action.call = { id: call.id, name: call.name };
       action.sequence = ++this.toolSequence;
+      action.reply = reply;
       this.tools.set(call.id, action);
       const priorTools = this.toolQueue;
       const args =
@@ -1674,6 +1680,9 @@ export class GeminiSessionController {
         this.runAction(call.name, args, {
           signal: toolSignal,
           callId: call.id,
+          // Calls run one by one, so a motion can follow a fly-to of the
+          // same reply that already found nothing.
+          reply: action.reply,
           progress: (update) => {
             if (actionCurrent()) this.narration.progress(call.id, update);
           },
diff --git a/src/voice/geminiSession.test.mjs b/src/voice/geminiSession.test.mjs
index 9ce8d351a..82f403ef7 100644
--- a/src/voice/geminiSession.test.mjs
+++ b/src/voice/geminiSession.test.mjs
@@ -1241,6 +1241,34 @@ test('successful stronger Radio stop still invalidates the prepared group', asyn
   h.c.stop();
 });
 
+test('Gemini tools of one turn share a reply identity, and a new turn gets another', async () => {
+  const replies = [];
+  const h = harness({
+    runAction: (name, _args, next) => {
+      replies.push([name, next.reply]);
+      return { ok: true, action: name };
+    },
+  });
+  await h.c.start({ pushToTalk: true });
+  h.c.sendTextCommand('Fly to Xyzzyville and pan left');
+  const ws = h.sockets[0];
+  requestTool(ws, 'fly', 'fly_to_location', { query: 'Xyzzyville' });
+  requestTool(ws, 'pan', 'move_camera', { motion: 'pan', direction: 'left' });
+  await h.c.toolQueue;
+  assert.equal(replies.length, 2);
+  assert.ok(replies[0][1], 'a sequentially run call carries its reply');
+  assert.equal(replies[1][1], replies[0][1]);
+  drainRadioReply(h);
+  await tick();
+  assert.equal(h.c.sendTextCommand('Pan left'), true);
+  requestTool(ws, 'pan-2', 'move_camera', { motion: 'pan', direction: 'left' });
+  await h.c.toolQueue;
+  assert.equal(replies.length, 3);
+  assert.ok(replies[2][1]);
+  assert.notEqual(replies[2][1], replies[0][1]);
+  h.c.stop();
+});
+
 test('slow Gemini tools reuse shared progress timing without injecting a conversation turn', async () => {
   const pending = deferred();
   let options;
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index 045969a4f..a01e3328e 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -299,6 +299,11 @@ export function createGevActionRunner({
   // Camera handoffs (navigation stamps) seen, and how many of them voice
   // fly-tos made. A search, share link or import that stamps during a flight
   // leaves it flying; the motion queued behind it then yields to that one.
+  // The voice fly-tos of the latest reply that sent one: whether any moved
+  // the camera, and whether one found nothing. A motion of that reply run
+  // after its fly-to found nothing (Gemini runs a reply's calls one by one)
+  // has no flight to wait on, and must not move the old view instead.
+  let replyFlights = null;
   let cameraHandoffs = 0;
   let voiceFlightHandoffs = 0;
   const otherHandoffs = () => cameraHandoffs - voiceFlightHandoffs;
@@ -1168,6 +1173,10 @@ export function createGevActionRunner({
       // Navigation by anything but a voice fly-to since this one began.
       flight.handoffs = otherHandoffs();
       voiceFlight = flight;
+      const reply = voiceReplyOf(runOptions);
+      if (reply !== null && replyFlights?.reply !== reply)
+        replyFlights = { reply, moved: false, foundNothing: false };
+      const replyRecord = reply !== null ? replyFlights : null;
       for (const notify of [...voiceFlightWatchers]) notify();
       // A motion already running (one the model sent before this fly-to) is
       // stopped when the flight takes navigation; the result says so.
@@ -1239,6 +1248,13 @@ export function createGevActionRunner({
           flight.settle('failed');
         else notStarted();
       }, notStarted);
+      // After the outcome above, which marks a lookup that moved nothing.
+      const noteReply = (result) => {
+        if (!replyRecord) return;
+        if (result?.ok === true) replyRecord.moved = true;
+        else if (flight.movedNothing) replyRecord.foundNothing = true;
+      };
+      flown.then(noteReply, () => noteReply(null));
       return flown.then((result) =>
         stoppedMotion && result && typeof result === 'object'
           ? { ...result, stoppedMotion }
@@ -1349,6 +1365,21 @@ export function createGevActionRunner({
       // A lookup that already found nothing does not hide the last flight
       // that moved: running now would cancel that flight mid-air.
       const pending = voiceFlightTarget(voiceFlight);
+      const reply = voiceReplyOf(runOptions);
+      if (
+        VOICE_FLIGHT_WAITING_MOTIONS.has(motion) &&
+        !(pending && !pending.done) &&
+        reply !== null &&
+        replyFlights?.reply === reply &&
+        replyFlights.foundNothing &&
+        !replyFlights.moved
+      )
+        return {
+          ok: false,
+          action: 'move_camera',
+          motion,
+          error: `Not run: the fly-to in this reply found nothing, so the ${motion} was not run at the old view.`,
+        };
       if (
         VOICE_FLIGHT_WAITING_MOTIONS.has(motion) &&
         pending &&
@@ -1724,6 +1755,7 @@ export function createGevActionRunner({
    * forget the analyst's "last answer". Area handles stay (page lifetime).
    */
   runVoiceAction.resetConversation = () => {
+    replyFlights = null;
     conversationAbort.abort();
     conversationAbort = new AbortController();
     conversation++;
@@ -3012,6 +3044,15 @@ async function frameOverhead(viewer, dataManager, styleManager, args = {}) {
 
 let voiceFlightCount = 0;
 
+/**
+ * The model reply a voice call belongs to: Gemini's turn (`reply`), or the
+ * OpenAI response its sibling calls share (`authorityGroup`). Null when the
+ * caller names none.
+ */
+function voiceReplyOf(options) {
+  return options?.reply ?? options?.authorityGroup ?? null;
+}
+
 /**
  * A voice flight's end: 'arrived', 'cancelled' or 'failed', settled once.
  * `replaced` is the last flight that moved when this one began (past lookups
diff --git a/src/voice/gevActions.test.mjs b/src/voice/gevActions.test.mjs
index f94eb554b..f4be07148 100644
--- a/src/voice/gevActions.test.mjs
+++ b/src/voice/gevActions.test.mjs
@@ -938,6 +938,80 @@ test('a motion follows a newer fly-to that lands while its own lookup stalls', a
 // flies: the search stamps a deferred navigation without stopping the flight.
 // Run where the flight landed, the orbit took navigation and the search's
 // reassert failed, so the search was silently dropped.
+// Gemini runs one reply's calls one after another: by the time "pan left"
+// runs, "fly to Xyzzyville" has already found nothing, so there is no flight
+// to wait on, and the pan moved the old view with ok: true.
+test('a motion run after its reply\'s fly-to found nothing is not run', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: async () => null,
+  });
+  const reply = { turn: 1 };
+  const fly = await runner('fly_to_location', { query: 'Xyzzyville' }, { reply });
+  assert.equal(fly.ok, false);
+  const pan = await runner(
+    'move_camera',
+    { motion: 'pan', direction: 'left' },
+    { reply },
+  );
+  assert.equal(pan.ok, false);
+  assert.match(pan.error, /Not run: the fly-to in this reply found nothing/);
+  assert.equal(getActiveCameraMotion(), null);
+  // The same holds for OpenAI's reply identity.
+  const group = 'response-1';
+  await runner('fly_to_location', { query: 'Xyzzyville' }, { authorityGroup: group });
+  const tilt = await runner(
+    'move_camera',
+    { motion: 'tilt', pitchDeg: -45 },
+    { authorityGroup: group },
+  );
+  assert.equal(tilt.ok, false);
+  assert.match(tilt.error, /found nothing/);
+});
+
+test('a motion in a later reply runs after a fly-to that found nothing', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: async () => null,
+  });
+  await runner('fly_to_location', { query: 'Xyzzyville' }, { reply: { turn: 1 } });
+  const pan = await runner(
+    'move_camera',
+    { motion: 'pan', direction: 'left' },
+    { reply: { turn: 2 } },
+  );
+  assert.equal(pan.ok, true, pan.error);
+});
+
+test('a motion runs at a flight of its reply that landed after another lookup found nothing', async (t) => {
+  t.after(() => interruptCameraMotion('test-cleanup'));
+  const { viewer, styleManager, flights } = tiltAfterFlightHarness();
+  const runner = createGevActionRunner({
+    viewer,
+    styleManager,
+    dataManager: { layers: new Map(), getAll: () => [] },
+    searchNavigation: async () => null,
+  });
+  const reply = { turn: 1 };
+  await runner('fly_to_location', { query: 'Xyzzyville' }, { reply });
+  assert.equal((await runner('fly_to_location', { locationId: 'austin' }, { reply })).ok, true);
+  flights[0].complete();
+  const pan = await runner(
+    'move_camera',
+    { motion: 'pan', direction: 'left' },
+    { reply },
+  );
+  assert.equal(pan.ok, true, pan.error);
+});
+
 test('a motion queued behind a fly-to yields to a search started during the flight', async (t) => {
   t.after(() => interruptCameraMotion('test-cleanup'));
   const { viewer, styleManager, flights, panelSearch, currentGeneration } =

From a20076fc5ef8976b1007170a05a3fc91765c48d3 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 15:55:52 -0800
Subject: [PATCH 53/71] fix(camera): judge a voice tilt's frame limit by the
 way its pitch moves

The pre-check picked the in-place look from args.direction alone, while the tilt itself turns down for any direction but up. A tilt sent as left or right at the frame limit was checked as a turn left or right, refused as losing the globe, though it turns down toward the planet. A rotate sent as up or down was checked as a look up or down, though it turns right.

A tilt's look now comes from its goal pitch against the current pitch (tiltLook), and the tick tilts in place through tiltInPlaceWithinFrame(cam, m, goalPitch). Neither depends on the direction word, so a tilt to an absolute angle, or a tilt with no direction, can use them as they are.
---
 src/cameraGlobeRotation.test.mjs | 20 ++++++++++++++++
 src/cameraVerbs.js               | 40 +++++++++++++++++++++++++-------
 2 files changed, 51 insertions(+), 9 deletions(-)

diff --git a/src/cameraGlobeRotation.test.mjs b/src/cameraGlobeRotation.test.mjs
index 543c01bff..09fc93f00 100644
--- a/src/cameraGlobeRotation.test.mjs
+++ b/src/cameraGlobeRotation.test.mjs
@@ -1426,6 +1426,26 @@ test('voice tilt from orbit stops with the planet still on screen and then says
   assert.ok(camera.pitch > radians(-68.5) && camera.pitch < radians(-66));
 });
 
+// The frame limit judges a tilt by the way its pitch moves, not by the
+// direction word: a tilt sent as left or right turns down.
+for (const direction of ['left', 'right']) {
+  test(`a tilt ${direction} from the frame limit is judged as the look down it is`, (t) => {
+    withScope(t, false);
+    const { camera, finishOnce } = harness(t, {
+      pitch: -80,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+    finishOnce();
+    const atLimit = camera.pitch;
+    const result = moveCamera({ motion: 'tilt', direction });
+    assert.equal(result.ok, true, result.error);
+    finishOnce();
+    assert.ok(camera.pitch < atLimit - radians(5), 'the tilt turned down');
+  });
+}
+
 test('voice turn in place from orbit stops with the planet still on screen', (t) => {
   withScope(t, false); // the whole frame is visible
   const { camera, tick } = harness(t, { pitch: -75 });
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 3c8424b82..9715e24f7 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -1090,6 +1090,23 @@ function lookWithinFrame(cam, m, look, angle) {
   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.
+ */
+function tiltLook(fromPitch, goalPitch) {
+  if (!Number.isFinite(fromPitch) || !Number.isFinite(goalPitch)) return null;
+  if (goalPitch > fromPitch) return 'lookUp';
+  return goalPitch < fromPitch ? 'lookDown' : 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));
+}
+
 /** True when the pre-check proved a half-degree `look` from `cam`'s pose. */
 function lookProven(cam, look) {
   return (
@@ -1358,7 +1375,7 @@ function onTick() {
           interruptCameraMotion('tilt-clamp');
           return;
         }
-        lookWithinFrame(cam, m, up ? 'lookUp' : 'lookDown', stepRad);
+        tiltInPlaceWithinFrame(cam, m, next);
       } else {
         lookWithinFrame(
           cam,
@@ -1662,15 +1679,20 @@ export function moveCamera(args = {}, runNavigation = null) {
       };
     }
   }
+  // A tilt is judged by the way its pitch will move (any direction other
+  // than up tilts down); a rotate turns left only when told to, as it runs.
   const look =
-    motion === 'tilt' || motion === 'rotate'
-      ? {
-          up: 'lookUp',
-          down: 'lookDown',
-          left: 'lookLeft',
-          right: 'lookRight',
-        }[direction]
-      : null;
+    motion === 'tilt'
+      ? tiltLook(
+          _viewer.camera.pitch,
+          _viewer.camera.pitch +
+            Cesium.Math.toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1),
+        )
+      : motion === 'rotate'
+        ? direction === 'left'
+          ? 'lookLeft'
+          : 'lookRight'
+        : 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
   // run and reported as done, and one that can is then turned at least that

From 44106b2bfbc1634d5ea91175cc530f83c381cae5 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 15:55:52 -0800
Subject: [PATCH 54/71] fix(camera): hold the globe recovery while a pointer is
 down

Holding a drag still for half a second on a view that already showed no surface looked like a camera at rest, so the recovery turned the view down under the user's hand. The recovery now defers while a pointer pressed on the canvas is held, and runs once it is released, as for a flight or a playing scene.
---
 docs/CURRENT-STATE.md        |  5 +++--
 src/app/application.test.mjs | 33 +++++++++++++++++++++++++++++++++
 src/app/viewer.js            | 31 +++++++++++++++++++++++++------
 3 files changed, 61 insertions(+), 8 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 27c31f4ce..545c4efd8 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -103,8 +103,9 @@ zoom-out guard above keeps wheel and pinch zoom-outs in view; this catches the
 other ways a move can end looking away, such as a saved or shared view that did.
 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) and the 2D and
-Columbus modes; a check a flight or scene defers runs once it ends. A Director
+progress, a Director scene while it plays (holds included), a pointer held
+down on the globe (a drag held still) and the 2D and Columbus modes; a check a
+flight, scene or held pointer defers runs once it ends. A Director
 shot loaded or replayed outside a run is not a playing scene. A view that loses
 its surface without a camera move (a resize, or turning the scope on) is left as
 it is until the next move. A voice turn requested while the camera is tracked is
diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs
index da01ff61c..e25b2ce11 100644
--- a/src/app/application.test.mjs
+++ b/src/app/application.test.mjs
@@ -778,6 +778,39 @@ test('a check a scene or flight defers runs once it ends', () => {
   }
 });
 
+// Holding a drag still for half a second on a view that already showed no
+// surface looked like a settled camera, and the view was turned down under
+// the user's hand.
+test('the recovery waits while a pointer is held on the globe', () => {
+  const timers = fakeTimers();
+  const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
+  const document = new EventTarget();
+  scene.canvas = Object.assign(new EventTarget(), {
+    clientWidth: 1225,
+    clientHeight: 923,
+    ownerDocument: document,
+  });
+  const dispose = installGlobeInViewRecovery(viewer, timers);
+  aim(camera, reportedStuckView);
+  scene.canvas.dispatchEvent(new Event('pointerdown'));
+  camera.moveStart.raiseEvent();
+  for (let i = 0; i < 8; i += 1) timers.tick();
+  camera.moveEnd.raiseEvent();
+  for (let i = 0; i < 8; i += 1) timers.tick();
+  assert.equal(globeOutOfFrame(camera), true, 'left alone while held');
+  document.dispatchEvent(new Event('pointerup'));
+  for (let i = 0; i < 3; i += 1) timers.tick();
+  assert.ok(
+    Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
+    'recovered once the pointer is released',
+  );
+  dispose();
+  aim(camera, reportedStuckView);
+  scene.canvas.dispatchEvent(new Event('pointerdown'));
+  document.dispatchEvent(new Event('pointerup'));
+  assert.equal(timers.pending(), 0, 'disposed recovery holds no listeners');
+});
+
 function fakeTimers() {
   let next = 1;
   const pending = new Map();
diff --git a/src/app/viewer.js b/src/app/viewer.js
index ef36feb8a..12ef67269 100644
--- a/src/app/viewer.js
+++ b/src/app/viewer.js
@@ -172,9 +172,10 @@ const SETTLE_GIVE_UP_MS = 5 * 60_000;
  * 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, 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.
+ * 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.
@@ -205,12 +206,27 @@ export function installGlobeInViewRecovery(
   if (!scene || !camera?.moveEnd || !camera?.moveStart)
     throw new TypeError('A complete Cesium viewer is required');
 
-  // Returns false while a flight or a paused scene defers the check, so the
-  // caller can try again once it ends.
+  // A pointer held on the globe is a gesture in progress, even when it holds
+  // still for half a second: the check waits for its release.
+  const canvas = scene.canvas;
+  const releaseTarget = canvas?.ownerDocument ?? canvas;
+  let pointerHeld = false;
+  const onPointerDown = () => {
+    pointerHeld = true;
+  };
+  const onPointerUp = () => {
+    pointerHeld = false;
+  };
+  canvas?.addEventListener?.('pointerdown', onPointerDown);
+  releaseTarget?.addEventListener?.('pointerup', onPointerUp);
+  releaseTarget?.addEventListener?.('pointercancel', onPointerUp);
+
+  // 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()) return false;
+    if (camera._currentFlight || paused() || pointerHeld) return false;
     const height = camera.positionCartographic?.height;
     if (
       !(height > minHeight) ||
@@ -294,6 +310,9 @@ export function installGlobeInViewRecovery(
     stopSettling();
     removeMoveEnd();
     removeMoveStart();
+    canvas?.removeEventListener?.('pointerdown', onPointerDown);
+    releaseTarget?.removeEventListener?.('pointerup', onPointerUp);
+    releaseTarget?.removeEventListener?.('pointercancel', onPointerUp);
   };
 }
 

From 82138478d0ff25c57f5f906e494ed0beca723437 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:03:52 -0800
Subject: [PATCH 55/71] fix(wildlife): treat a valid empty Acartia snapshot as
 a fresh success

A quiet or fully filtered feed raised invalid_snapshot, so the proxy
answered 502 with a 15 s cooldown and re-polled about four times a
minute. Only a non-array payload is malformed now; an empty projection
caches for the normal ten minutes and clears earlier rows.
---
 docs/CURRENT-STATE.md             |  5 +-
 server/providers/acartia.js       |  4 +-
 server/providers/acartia.test.mjs | 84 ++++++++++++++++++++++---------
 3 files changed, 68 insertions(+), 25 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 1b1b73d2c..b615bb70d 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -123,7 +123,10 @@ known `Retry-After`. Failures keep filters and drawn rows, reporting DEGRADED
 with retry timing; logs exclude request URLs and upstream exception text.
 
 `/api/acartia/sightings` adds Salish Sea marine mammals within 45.5–50.5° N,
-126–121° W, cached ten minutes and stale for at most 24 h. WHALES accepts only
+126–121° W, cached ten minutes and stale for at most 24 h. A valid empty
+snapshot, including one whose rows all fall outside coverage or the species
+checks, is a fresh success that clears earlier rows; only a malformed or failed
+upstream reply serves stale and starts a retry cooldown. WHALES accepts only
 recognized cetaceans; other identified marine mammals appear under ALL or
 MAMMALS. Sensitive iNaturalist locations remain 0.2° privacy cells; Acartia
 positions are rounded to 0.01° on the server. Acartia comments are never retained.
diff --git a/server/providers/acartia.js b/server/providers/acartia.js
index e3dafd220..c8f8b90d7 100644
--- a/server/providers/acartia.js
+++ b/server/providers/acartia.js
@@ -100,7 +100,9 @@ export function acartiaProxy({
         signal,
       );
       const rows = normalizeAcartiaSightings(payload, now());
-      if (!rows?.length) throw new Error('invalid_snapshot');
+      // Only a non-array is malformed. A quiet feed, or one whose rows all fall
+      // outside coverage or the species checks, is a valid empty snapshot.
+      if (!rows) throw new Error('invalid_snapshot');
       return { fetchedAt: now(), rows };
     } catch (error) {
       if (error.status !== 429) coolDown(502, FAILURE_COOLDOWN_MS);
diff --git a/server/providers/acartia.test.mjs b/server/providers/acartia.test.mjs
index bf61d987c..e7b3cd32e 100644
--- a/server/providers/acartia.test.mjs
+++ b/server/providers/acartia.test.mjs
@@ -221,43 +221,81 @@ test('one global snapshot single-flights and stays fresh for ten minutes', async
   assert.equal(calls, 2);
 });
 
-test('empty, unprojectable and invented wrapped snapshots never replace the cache', async () => {
-  for (const bad of [
+test('a valid empty or fully filtered snapshot is a fresh success that clears old rows', async () => {
+  for (const quiet of [
     [],
     [null],
     [{ ...sighting(), data_source_name: '' }],
-    { results: [sighting()] },
+    [{ ...sighting(), latitude: 37.8 }],
+    [{ ...sighting(), type: 'Unknown' }],
   ]) {
     let at = NOW;
-    let fail = false;
+    let calls = 0;
+    let empty = false;
     const cache = new Map();
     const request = install({
       cache,
       now: () => at,
-      fetchImpl: async () => Response.json(fail ? bad : [sighting()]),
+      fetchImpl: async () => {
+        calls += 1;
+        return Response.json(empty ? quiet : [sighting()]);
+      },
     });
-    const fresh = await request();
-    const retained = cache.get('sightings');
-    fail = true;
+    assert.equal((await request()).body.rows.length, 1);
+    empty = true;
     at += 600_001;
-    const stale = await request();
-    assert.equal(stale.status, 200);
-    assert.equal(stale.headers['X-Data-Stale'], 'true');
-    assert.equal(stale.body.stale, true);
-    assert.equal(stale.body.fetchedAt, fresh.body.fetchedAt);
-    assert.equal(cache.get('sightings'), retained);
-    const coldCache = new Map();
-    const cold = install({
-      cache: coldCache,
-      fetchImpl: async () => Response.json(bad),
-    });
-    const result = await cold();
-    assert.equal(result.status, 502);
-    assert.equal(result.body.error, 'acartia_unavailable');
-    assert.equal(coldCache.size, 0);
+    const result = await request();
+    assert.equal(result.status, 200);
+    assert.deepEqual(result.body, { fetchedAt: at, rows: [] });
+    assert.equal(result.headers['X-Data-Stale'], undefined);
+    assert.equal(result.headers['Retry-After'], undefined);
+    assert.deepEqual(cache.get('sightings').value.rows, []);
+    // The quiet feed keeps the normal ten-minute cadence, not a failure retry.
+    at += 599_999;
+    assert.equal((await request()).status, 200);
+    assert.equal(calls, 2);
+    at += 1;
+    await request();
+    assert.equal(calls, 3);
+    const cold = install({ fetchImpl: async () => Response.json(quiet) });
+    const coldResult = await cold();
+    assert.equal(coldResult.status, 200);
+    assert.deepEqual(coldResult.body, { fetchedAt: NOW, rows: [] });
   }
 });
 
+test('an invented wrapped snapshot never replaces the cache', async () => {
+  const bad = { results: [sighting()] };
+  let at = NOW;
+  let fail = false;
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: async () => Response.json(fail ? bad : [sighting()]),
+  });
+  const fresh = await request();
+  const retained = cache.get('sightings');
+  fail = true;
+  at += 600_001;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.headers['X-Data-Stale'], 'true');
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, fresh.body.fetchedAt);
+  assert.equal(cache.get('sightings'), retained);
+  const coldCache = new Map();
+  const cold = install({
+    cache: coldCache,
+    fetchImpl: async () => Response.json(bad),
+  });
+  const result = await cold();
+  assert.equal(result.status, 502);
+  assert.equal(result.body.error, 'acartia_unavailable');
+  assert.equal(result.headers['Retry-After'], '15');
+  assert.equal(coldCache.size, 0);
+});
+
 test('failure serves stale for at most 24 hours and never reports a cold success', async () => {
   let at = NOW;
   let fail = false;

From 3cb30c3f975e8dfb87a3e7105a650c509d93b263 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:05:02 -0800
Subject: [PATCH 56/71] fix(wildlife): point the Acartia card link only at
 acartia.io

The card's "Acartia" link was built from the contributor-supplied
photo_url, so any https site could appear labelled as Acartia. Acartia
has no documented per-sighting page, so the source link is now always
the Acartia site, on the server projection and again in the card.
The separate "Open on Acartia" fallback link is no longer needed.
---
 docs/CURRENT-STATE.md                         |  3 +-
 src/i18n/locales/ar.json                      |  1 -
 src/i18n/locales/de.json                      |  1 -
 src/i18n/locales/es.json                      |  1 -
 src/i18n/locales/fr.json                      |  1 -
 src/i18n/locales/it.json                      |  1 -
 src/i18n/locales/ja.json                      |  1 -
 src/i18n/locales/pt.json                      |  1 -
 src/i18n/locales/ru.json                      |  1 -
 src/i18n/locales/uk.json                      |  1 -
 src/i18n/locales/zh-CN.json                   |  1 -
 src/i18n/locales/zh-Hant.json                 |  1 -
 src/layers/wildlifeSightings/records.js       | 17 +++--------
 src/layers/wildlifeSightings/records.test.mjs |  8 +++--
 src/ui/views/panels/WildlifeSightingCard.vue  |  5 ++--
 src/ui/wildlifeSightingCard.test.mjs          | 30 +++++++++++++++++++
 16 files changed, 45 insertions(+), 29 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index b615bb70d..fbbaa19b0 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -174,7 +174,8 @@ compact anchored photo card. Selection stays pinned across camera, filter and
 sample changes until explicit deselection or layer disable. Its medium image
 uses `object-fit: contain`, with names, compact observed age and creator/licence.
 The card is the single source link to iNaturalist. Obscured sightings also stay
-text-only; Acartia stays text-only with provider credit and whale guidance.
+text-only; Acartia stays text-only with provider credit and whale guidance,
+and its source link is always `https://acartia.io/`, never a contributed URL.
 Placement avoids actual HUD, toolbar and rail rectangles, panning only when
 necessary while preserving zoom. Escape, close or an outside click closes the
 card and clears selection. Camera/layout changes reposition the card without
diff --git a/src/i18n/locales/ar.json b/src/i18n/locales/ar.json
index da291e035..b491c3c93 100644
--- a/src/i18n/locales/ar.json
+++ b/src/i18n/locales/ar.json
@@ -3453,7 +3453,6 @@
   "Loading photo...": "جارٍ تحميل الصورة…",
   "Photo unavailable": "الصورة غير متاحة",
   "Location obscured to a 0.2° cell": "الموقع مخفي ضمن خلية بمقدار 0.2°",
-  "Open on Acartia ↗": "فتح على Acartia ↗",
   "Photo of {name}": "صورة {name}",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/de.json b/src/i18n/locales/de.json
index 69b039fc5..d01ff292f 100644
--- a/src/i18n/locales/de.json
+++ b/src/i18n/locales/de.json
@@ -3153,7 +3153,6 @@
   "Loading photo...": "Foto wird geladen…",
   "Photo unavailable": "Foto nicht verfügbar",
   "Location obscured to a 0.2° cell": "Standort auf eine 0,2°-Rasterzelle verschleiert",
-  "Open on Acartia ↗": "Auf Acartia öffnen ↗",
   "Photo of {name}": "Foto von {name}",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/es.json b/src/i18n/locales/es.json
index a34a9bf39..aa403f743 100644
--- a/src/i18n/locales/es.json
+++ b/src/i18n/locales/es.json
@@ -3228,7 +3228,6 @@
   "Loading photo...": "Cargando foto…",
   "Photo unavailable": "Foto no disponible",
   "Location obscured to a 0.2° cell": "Ubicación oculta en una celda de 0,2°",
-  "Open on Acartia ↗": "Abrir en Acartia ↗",
   "Photo of {name}": "Foto de {name}",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/fr.json b/src/i18n/locales/fr.json
index a09806cfa..b3ae72189 100644
--- a/src/i18n/locales/fr.json
+++ b/src/i18n/locales/fr.json
@@ -3228,7 +3228,6 @@
   "Loading photo...": "Chargement de la photo…",
   "Photo unavailable": "Photo indisponible",
   "Location obscured to a 0.2° cell": "Localisation masquée dans une cellule de 0,2°",
-  "Open on Acartia ↗": "Ouvrir sur Acartia ↗",
   "Photo of {name}": "Photo de {name}",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/it.json b/src/i18n/locales/it.json
index b800b010c..4c69e1d4c 100644
--- a/src/i18n/locales/it.json
+++ b/src/i18n/locales/it.json
@@ -3228,7 +3228,6 @@
   "Loading photo...": "Caricamento della foto…",
   "Photo unavailable": "Foto non disponibile",
   "Location obscured to a 0.2° cell": "Posizione oscurata in una cella di 0,2°",
-  "Open on Acartia ↗": "Apri su Acartia ↗",
   "Photo of {name}": "Foto di {name}",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/ja.json b/src/i18n/locales/ja.json
index fbfc9dd96..9a053f869 100644
--- a/src/i18n/locales/ja.json
+++ b/src/i18n/locales/ja.json
@@ -3078,7 +3078,6 @@
   "Loading photo...": "写真を読み込み中…",
   "Photo unavailable": "写真を表示できません",
   "Location obscured to a 0.2° cell": "位置は0.2°のセル内に秘匿されています",
-  "Open on Acartia ↗": "Acartiaで開く ↗",
   "Photo of {name}": "{name}の写真",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/pt.json b/src/i18n/locales/pt.json
index a57f4eeaf..79c507759 100644
--- a/src/i18n/locales/pt.json
+++ b/src/i18n/locales/pt.json
@@ -3228,7 +3228,6 @@
   "Loading photo...": "Carregando foto…",
   "Photo unavailable": "Foto indisponível",
   "Location obscured to a 0.2° cell": "Localização ocultada em uma célula de 0,2°",
-  "Open on Acartia ↗": "Abrir no Acartia ↗",
   "Photo of {name}": "Foto de {name}",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/ru.json b/src/i18n/locales/ru.json
index 2946ba482..11fddb3e9 100644
--- a/src/i18n/locales/ru.json
+++ b/src/i18n/locales/ru.json
@@ -3303,7 +3303,6 @@
   "Loading photo...": "Загрузка фото…",
   "Photo unavailable": "Фото недоступно",
   "Location obscured to a 0.2° cell": "Местоположение скрыто в ячейке 0,2°",
-  "Open on Acartia ↗": "Открыть на Acartia ↗",
   "Photo of {name}": "Фото {name}",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/uk.json b/src/i18n/locales/uk.json
index 7f6c8c3e2..c0fab8533 100644
--- a/src/i18n/locales/uk.json
+++ b/src/i18n/locales/uk.json
@@ -3303,7 +3303,6 @@
   "Loading photo...": "Завантаження фото…",
   "Photo unavailable": "Фото недоступне",
   "Location obscured to a 0.2° cell": "Місцеположення приховано в комірці 0,2°",
-  "Open on Acartia ↗": "Відкрити на Acartia ↗",
   "Photo of {name}": "Фото {name}",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/zh-CN.json b/src/i18n/locales/zh-CN.json
index 28854ce5d..8687af790 100644
--- a/src/i18n/locales/zh-CN.json
+++ b/src/i18n/locales/zh-CN.json
@@ -3078,7 +3078,6 @@
   "Loading photo...": "正在加载照片…",
   "Photo unavailable": "照片不可用",
   "Location obscured to a 0.2° cell": "位置已模糊至0.2°网格",
-  "Open on Acartia ↗": "在Acartia上打开 ↗",
   "Photo of {name}": "{name}的照片",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/i18n/locales/zh-Hant.json b/src/i18n/locales/zh-Hant.json
index 63088293a..a95e71dd5 100644
--- a/src/i18n/locales/zh-Hant.json
+++ b/src/i18n/locales/zh-Hant.json
@@ -3078,7 +3078,6 @@
   "Loading photo...": "正在載入照片…",
   "Photo unavailable": "照片無法使用",
   "Location obscured to a 0.2° cell": "位置已模糊至0.2°網格",
-  "Open on Acartia ↗": "在Acartia上開啟 ↗",
   "Photo of {name}": "{name}的照片",
   "Acartia": "Acartia",
   "CC BY 4.0": "CC BY 4.0",
diff --git a/src/layers/wildlifeSightings/records.js b/src/layers/wildlifeSightings/records.js
index a1e50f52c..1af1cc296 100644
--- a/src/layers/wildlifeSightings/records.js
+++ b/src/layers/wildlifeSightings/records.js
@@ -247,18 +247,9 @@ export function normalizeInatObservations(
   return rows;
 }
 
-function acartiaLink(value) {
-  if (typeof value !== 'string' || value.length > 500)
-    return 'https://acartia.io';
-  try {
-    const url = new URL(value);
-    return url.protocol === 'https:' && !url.username && !url.password
-      ? url.href
-      : 'https://acartia.io';
-  } catch {
-    return 'https://acartia.io';
-  }
-}
+// Acartia has no documented per-sighting page, and photo_url is supplied by the
+// contributor. The source link is therefore always the Acartia site itself.
+export const ACARTIA_SITE = 'https://acartia.io/';
 
 /** Acartia documents flat rows only. Name and entity are text fields; unknown
  * shapes are skipped rather than guessing nested provider data. */
@@ -315,7 +306,7 @@ export function normalizeAcartiaSightings(payload, nowMs) {
       cetacean: speciesGroup === 'cetacean',
       threatened: false,
       provider: { name, entity: cleanText(raw.data_source_entity, 60) },
-      link: acartiaLink(raw.photo_url),
+      link: ACARTIA_SITE,
       photo: null,
       favesCount: 0,
       identificationAgreements: 0,
diff --git a/src/layers/wildlifeSightings/records.test.mjs b/src/layers/wildlifeSightings/records.test.mjs
index 18a1693d8..9909338a1 100644
--- a/src/layers/wildlifeSightings/records.test.mjs
+++ b/src/layers/wildlifeSightings/records.test.mjs
@@ -330,7 +330,7 @@ test('Acartia requires flat provider text, handles trust, and sanitizes type', (
   );
 });
 
-test('Acartia rejects invalid times/positions and unsafe photo links become the canonical page', () => {
+test('Acartia rejects invalid times/positions and its link is always the Acartia site', () => {
   for (const overrides of [
     { created: new Date(now - 8 * 24 * hour - 1).toISOString() },
     { created: new Date(now + 10 * 60_000 + 1).toISOString() },
@@ -341,6 +341,10 @@ test('Acartia rejects invalid times/positions and unsafe photo links become the
   ])
     assert.deepEqual(normalizeAcartiaSightings([sighting(overrides)], now), []);
   for (const photo_url of [
+    // A contributor-supplied URL is never labelled as the Acartia source.
+    'https://provider.example/photo.jpg',
+    'https://phishing.example/acartia.io/login',
+    'https://acartia.io.attacker.example/',
     'http://provider.example/p.jpg',
     'https://user:secret@provider.example/p.jpg',
     'javascript:bad()',
@@ -349,7 +353,7 @@ test('Acartia rejects invalid times/positions and unsafe photo links become the
   ]) {
     assert.equal(
       normalizeAcartiaSightings([sighting({ photo_url })], now)[0].link,
-      'https://acartia.io',
+      'https://acartia.io/',
     );
   }
 });
diff --git a/src/ui/views/panels/WildlifeSightingCard.vue b/src/ui/views/panels/WildlifeSightingCard.vue
index fc92c7ee4..9caac8fdd 100644
--- a/src/ui/views/panels/WildlifeSightingCard.vue
+++ b/src/ui/views/panels/WildlifeSightingCard.vue
@@ -2,7 +2,7 @@
 import { computed, shallowRef, useTemplateRef, watch } from 'vue';
 import { formatDate, t, translateKnown } from '../../../i18n/index.js';
 import { photoCreator, formatAge } from '../../../layers/wildlifeSightings/photoText.js';
-import { inatLicenceLabel, inatPhotoUrl, isOpenPhoto } from '../../../layers/wildlifeSightings/records.js';
+import { ACARTIA_SITE, inatLicenceLabel, inatPhotoUrl, isOpenPhoto } from '../../../layers/wildlifeSightings/records.js';
 
 const props = defineProps({
   sighting: { type: Object, required: true },
@@ -36,6 +36,8 @@ const age = computed(() => {
 });
 const observedDate = computed(() => observedDay.value ? formatDate(Date.parse(`${observedDay.value}T00:00:00Z`), { year: 'numeric', month: 'short', day: 'numeric', timeZone: 'UTC' }) : '');
 const link = computed(() => {
+  // The "Acartia" label only ever points at the Acartia site, never a row URL.
+  if (acartia.value) return ACARTIA_SITE;
   try {
     const url = new URL(props.sighting.link);
     return url.protocol === 'https:' && !url.username && !url.password ? url.href : null;
@@ -89,7 +91,6 @@ watch([() => props.sighting.stableId, () => photo.value?.src], () => { loaded.va
       </div>
     </component>
     <p v-if="acartia || taxa === 'whales'" class="wildlife-sighting-card-guidance">
-      <a v-if="acartia && !/^https:\/\/acartia\.io\/?$/.test(link || '')" href="https://acartia.io" target="_blank" rel="noopener noreferrer">{{ t('Open on Acartia ↗') }}</a>
       <a href="https://www.bewhalewise.org" target="_blank" rel="noopener noreferrer">{{ t('Be Whale Wise') }}</a>
     </p>
   </section>
diff --git a/src/ui/wildlifeSightingCard.test.mjs b/src/ui/wildlifeSightingCard.test.mjs
index d7837af7f..f685c75e0 100644
--- a/src/ui/wildlifeSightingCard.test.mjs
+++ b/src/ui/wildlifeSightingCard.test.mjs
@@ -373,6 +373,36 @@ test('missing, restricted, obscured and Acartia photos all use the same compact
     });
 });
 
+test('an Acartia card labels only the Acartia site as Acartia', async (context) => {
+  for (const link of [
+    'https://provider.example/photos/synthetic.jpg',
+    'https://acartia.io.attacker.example/',
+    'https://acartia.io/',
+  ])
+    await context.test(link, async (context) => {
+      const f = fixture(context, {
+        ...row,
+        origin: 'acartia',
+        stableId: 'acartia:456',
+        provider: { name: 'Synthetic network' },
+        link,
+      });
+      await f.click();
+      const card = f.cardElement();
+      const hrefs = [...card.querySelectorAll('a')].map((a) =>
+        a.getAttribute('href'),
+      );
+      assert.deepEqual(hrefs, [
+        'https://acartia.io/',
+        'https://www.bewhalewise.org',
+      ]);
+      assert.equal(
+        card.querySelector('.wildlife-sighting-card-source').textContent,
+        'Acartia ↗',
+      );
+    });
+});
+
 test('safe placements near each viewport edge exclude actual HUD, toolbar and rail rects', () => {
   const obstacles = [
     rect(0, 0, 260, 160),

From 5391687d4649c3fd9e7f0d0c46624caaf6c7582e Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:06:41 -0800
Subject: [PATCH 57/71] fix(wildlife): draw what arrived when one sighting
 source fails

An iNaturalist rejection discarded a successful Acartia reply, and the
antimeridian Promise.all lost both halves when one failed. Each box now
settles independently; the failed part is reported on
sources.inaturalist (error and failed boxes), the layer keeps that
area's last iNaturalist rows and shows DEGRADED with retry timing, and
the update fails outright only when every requested source failed.
---
 docs/CURRENT-STATE.md                         |  4 +
 src/layers/wildlifeSightings/lifecycle.js     | 16 +++-
 .../wildlifeSightings/ownership.test.mjs      | 41 +++++++++++
 src/layers/wildlifeSightings/source.js        | 26 ++++++-
 src/layers/wildlifeSightings/source.test.mjs  | 73 +++++++++++++++++++
 5 files changed, 155 insertions(+), 5 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index fbbaa19b0..2449130f4 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -121,6 +121,10 @@ Provider 429 cooldown is shared; 5xx cooldown is resource-specific. Failed tiles
 retain good cells for at most one hour. Stale replies carry `X-Data-Stale` and
 known `Retry-After`. Failures keep filters and drawn rows, reporting DEGRADED
 with retry timing; logs exclude request URLs and upstream exception text.
+A partial failure still draws what arrived: a failed iNaturalist request, or
+one failed half of an antimeridian view, keeps a good Acartia reply and the
+other half, retains that area's last iNaturalist rows and reports DEGRADED.
+The update fails outright only when every requested source failed.
 
 `/api/acartia/sightings` adds Salish Sea marine mammals within 45.5–50.5° N,
 126–121° W, cached ten minutes and stale for at most 24 h. A valid empty
diff --git a/src/layers/wildlifeSightings/lifecycle.js b/src/layers/wildlifeSightings/lifecycle.js
index e092a6ef1..6da425c7a 100644
--- a/src/layers/wildlifeSightings/lifecycle.js
+++ b/src/layers/wildlifeSightings/lifecycle.js
@@ -345,8 +345,18 @@ export function createLifecycle({ state, services, parts }) {
         state.loadedScope = query.scope;
         state.pendingClear = false;
         // A successful page replaces this queried area, including a healthy
-        // empty page. Keep only other visited areas in the bounded LRU.
+        // empty page. Keep only other visited areas in the bounded LRU. Areas
+        // whose iNaturalist request failed keep their last iNaturalist rows.
+        const inat = snapshot.sources?.inaturalist;
+        const failedInatBoxes =
+          inat?.ok === false ? inat.failedBoxes || query.boxes : null;
         for (const [id, row] of state.rows) {
+          if (
+            failedInatBoxes &&
+            row.origin === 'inaturalist' &&
+            rowInWildlifeBoxes(row, failedInatBoxes, 0)
+          )
+            continue;
           if (rowInWildlifeBoxes(row, query.boxes, 0)) state.rows.delete(id);
         }
         for (const row of snapshot.rows) {
@@ -397,6 +407,10 @@ export function createLifecycle({ state, services, parts }) {
       const sourceError =
         gridError ||
         staleError ||
+        (snapshot.sources?.inaturalist?.ok === false
+          ? snapshot.sources.inaturalist.error ||
+            new Error(msg('Wildlife sightings source unavailable'))
+          : null) ||
         (snapshot.sources?.acartia?.ok === false
           ? new Error(msg('Acartia feed unavailable'))
           : null);
diff --git a/src/layers/wildlifeSightings/ownership.test.mjs b/src/layers/wildlifeSightings/ownership.test.mjs
index c8bfaac62..e118a87bc 100644
--- a/src/layers/wildlifeSightings/ownership.test.mjs
+++ b/src/layers/wildlifeSightings/ownership.test.mjs
@@ -1568,6 +1568,47 @@ test('provider credits sit in the layer row, never on the globe; Acartia failure
   h.layer.destroy();
 });
 
+test('an iNaturalist failure beside a good Acartia reply keeps both and reports degraded', async () => {
+  let inatHealthy = true;
+  const acartia = {
+    ...base,
+    stableId: 'acartia:1',
+    origin: 'acartia',
+    iconic: 'Mammalia',
+    lon: -122.3,
+    provider: { name: 'Synthetic Provider', entity: null },
+  };
+  const failure = Object.assign(new Error('iNaturalist HTTP 502'), {
+    status: 502,
+    retryAfterSec: 30,
+  });
+  const h = harness({
+    getSnapshot: async () => [],
+    getSnapshotDetail: async ({ boxes }) => ({
+      rows: inatHealthy ? [base, acartia] : [acartia],
+      sources: {
+        inaturalist: inatHealthy
+          ? { ok: true }
+          : { ok: false, error: failure, failedBoxes: boxes },
+        acartia: { ok: true },
+      },
+    }),
+  });
+  await h.update();
+  assert.equal(h.layer.getStats().count, 2);
+  inatHealthy = false;
+  await h.update();
+  // The failed iNaturalist area keeps its last rows; Acartia still refreshes.
+  assert.equal(h.layer.getStats().count, 2);
+  assert.equal(h.layer.getStats().error, 'iNaturalist HTTP 502');
+  assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
+  assert.equal(
+    h.layer.getRowControls().info,
+    'iNaturalist contributors · Acartia 1 (Salish Sea) · licences per record',
+  );
+  h.layer.destroy();
+});
+
 test('ambient cards prefilter the horizon, spread over screen regions and retain visible slots', async () => {
   const rows = Array.from({ length: 32 }, (_, i) => ({
     ...photographed,
diff --git a/src/layers/wildlifeSightings/source.js b/src/layers/wildlifeSightings/source.js
index 7af6d1e72..8bd41bf1d 100644
--- a/src/layers/wildlifeSightings/source.js
+++ b/src/layers/wildlifeSightings/source.js
@@ -454,7 +454,9 @@ export function createWildlifeSightingsSource({
       ['all', 'Mammalia', 'whales'].includes(preset) &&
       requestBoxes.some((bounds) => boxIntersects(bounds, ACARTIA_GUARD_BOX));
 
-    const inatRequest = Promise.all(
+    // Each box settles independently: one failed antimeridian half must not
+    // discard the other half, and neither may discard a good Acartia reply.
+    const inatRequest = Promise.allSettled(
       requestBoxes.map((bounds) => {
         const params = new URLSearchParams({
           scope: scope === 'global' ? 'global' : 'view',
@@ -480,8 +482,23 @@ export function createWildlifeSightingsSource({
       acartiaRequest,
     ]);
     signal?.throwIfAborted();
-    if (inatResult.status === 'rejected') throw inatResult.reason;
-    const inatSnapshots = inatResult.value;
+    const inatSnapshots = [];
+    const failedBoxes = [];
+    let inatError = null;
+    inatResult.value.forEach((result, index) => {
+      if (result.status === 'fulfilled') inatSnapshots.push(result.value);
+      else {
+        failedBoxes.push(requestBoxes[index]);
+        inatError ??= result.reason;
+      }
+    });
+    // Fail outright only when nothing succeeded; otherwise draw what arrived
+    // and report the failed source in its per-source status.
+    if (
+      !inatSnapshots.length &&
+      (!useAcartia || acartiaResult.status !== 'fulfilled')
+    )
+      throw inatError;
     const inatRows = inatSnapshots.flatMap((snapshot) => snapshot.rows);
     const acartiaSnapshot =
       acartiaResult.status === 'fulfilled' ? acartiaResult.value : null;
@@ -529,10 +546,11 @@ export function createWildlifeSightingsSource({
       ...(retryAfter.length ? { retryAfterSec: Math.max(...retryAfter) } : {}),
       sources: {
         inaturalist: {
-          ok: true,
+          ok: !inatError,
           stale: inatStale,
           fetchedAt: inatFetchedAt,
           count: rows.filter((row) => row.origin === 'inaturalist').length,
+          ...(inatError ? { error: inatError, failedBoxes } : {}),
         },
         acartia: {
           ok: !useAcartia || acartiaResult.status === 'fulfilled',
diff --git a/src/layers/wildlifeSightings/source.test.mjs b/src/layers/wildlifeSightings/source.test.mjs
index 7c1191e4b..2a21ca372 100644
--- a/src/layers/wildlifeSightings/source.test.mjs
+++ b/src/layers/wildlifeSightings/source.test.mjs
@@ -148,6 +148,79 @@ test('Acartia failure preserves iNat rows with an explicit failed source', async
   assert.equal(result.sources.inaturalist.ok, true);
 });
 
+test('iNat failure keeps a successful Acartia result and reports iNat degraded', async () => {
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) =>
+      url.startsWith('/api/acartia')
+        ? Response.json(acartiaEnvelope())
+        : new Response('', {
+            status: 502,
+            headers: { 'X-Upstream-Status': '503', 'Retry-After': '30' },
+          }),
+  });
+  const result = await source.getSnapshotDetail({ box: seattle });
+  assert.deepEqual(result.rows, [acartia]);
+  assert.equal(result.totalResults, 1);
+  assert.equal(result.fetchedAt, now);
+  assert.equal(result.sources.acartia.ok, true);
+  assert.equal(result.sources.inaturalist.ok, false);
+  assert.equal(result.sources.inaturalist.count, 0);
+  assert.equal(
+    result.sources.inaturalist.error.message,
+    'iNaturalist HTTP 502',
+  );
+  assert.equal(result.sources.inaturalist.error.retryAfterSec, 30);
+  assert.deepEqual(result.sources.inaturalist.failedBoxes, [seattle]);
+});
+
+test('observations reject only when every requested source failed', async () => {
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) =>
+      new Response('', { status: url.startsWith('/api/acartia') ? 502 : 503 }),
+  });
+  await assert.rejects(source.getSnapshotDetail({ box: seattle }), {
+    message: 'iNaturalist HTTP 503',
+  });
+  const antimeridian = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async () => new Response('', { status: 503 }),
+  });
+  await assert.rejects(
+    antimeridian.getSnapshotDetail({
+      boxes: [
+        { south: 10, west: 179, north: 12, east: 180 },
+        { south: 10, west: -180, north: 12, east: -178 },
+      ],
+    }),
+    { message: 'iNaturalist HTTP 503' },
+  );
+});
+
+test('one failed antimeridian half keeps the other half and reports the failed box', async () => {
+  const east = { south: 10, west: 179, north: 12, east: 180 };
+  const west = { south: 10, west: -180, north: 12, east: -178 };
+  const eastRow = { ...inat, stableId: 'inat:east', lat: 11, lon: 179.5 };
+  const source = createWildlifeSightingsSource({
+    now: () => now,
+    fetchImpl: async (url) =>
+      new URL(url, 'https://example.test').searchParams.get('west') === '179'
+        ? Response.json(inatEnvelope({ rows: [eastRow], totalResults: 3 }))
+        : new Response('', { status: 503 }),
+  });
+  const result = await source.getSnapshotDetail({ boxes: [east, west] });
+  assert.deepEqual(result.rows, [eastRow]);
+  assert.equal(result.totalResults, 3);
+  assert.equal(result.sources.inaturalist.ok, false);
+  assert.equal(result.sources.inaturalist.count, 1);
+  assert.equal(
+    result.sources.inaturalist.error.message,
+    'iNaturalist HTTP 503',
+  );
+  assert.deepEqual(result.sources.inaturalist.failedBoxes, [west]);
+});
+
 test('proxy staleness and original fetch dates pass through with per-source counts', async () => {
   const fetchedAt = now - 50 * 60_000;
   const source = createWildlifeSightingsSource({

From fb0a58ef3c55dd03eae038df8d510140c71f16c0 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:07:48 -0800
Subject: [PATCH 58/71] docs(wildlife): cite the documented iNaturalist UTFGrid
 endpoint and Acartia's key request

/grid/{z}/{x}/{y}.grid.json is documented in the v1 and v2 API docs as
Grid Tiles UTFGrid; only its per-cell records are unspecified, which is
what the schema guard covers. DATA_SOURCES.md now also notes that
Acartia's README asks API users to create an account and an API key,
although /sightings/current answers without one today.
---
 DATA_SOURCES.md                            |  4 ++--
 docs/CURRENT-STATE.md                      |  3 ++-
 docs/KNOWN-ISSUES.md                       |  8 +++++---
 src/layers/wildlifeSightings/docs.test.mjs | 18 ++++++++++++++++++
 4 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md
index 1153015b8..f2b002428 100644
--- a/DATA_SOURCES.md
+++ b/DATA_SOURCES.md
@@ -198,8 +198,8 @@ The optional Local ADS-B layer and the broadcast-FM receiver use radio you recei
 - **OSRM on the FOSSGIS routing servers.** Keyless (no API key). Every route is requested by a person: clicking A and B in the Directions layer, or a voice "route from A to B". The server-side `/api/route` proxy sends an identifying `User-Agent`, pins the upstream host, accepts 2-12 coordinates, rejects any leg over 600 km or a total over 2,500 km, caps the buffered response at 8 MB, times the upstream out at 12 s, rate-limits per client, caches each route for 10 minutes, and coalesces identical requests that are in flight at the same time. Turn-by-turn maneuvers are asked for only when a caller wants them (`steps=1`), so the callers that do not read them send the smaller request. The "fix the map" link the policy asks for is in the Data attribution popover beside the OpenStreetMap credit.
 - **FAA Special Use Airspace.** Keyless. `/api/drone-airspace` queries the public FAA AIS FeatureServer for prohibited (P) and restricted (R) zones only — not MOAs, TFRs or other SUA types — with simplified geometry, a body cap, paging, a one-hour cache and stale-on-error. The layer is US coverage, informational only, and is not a substitute for B4UFLY, LAANC or a preflight briefing. Data is fetched at request time and never stored or redistributed. US government public domain; courtesy attribution is registered in the Data attribution popover.
 - **iNaturalist.** Keyless. `/api/inaturalist/observations` returns cached random view samples (newest first globally), at most 200 per request. Recency uses observation time: the v1 `d1` filter and a rolling 48 h cutoff (whales 7 d); date-only rows qualify when their day starts within the window. Observation caches last 5 min (global 10 min), with stale fallback ≤1 h. `/api/inaturalist/grid` supplies density counts, cached 15 min. Both share a paced queue capped at 60/min and 8,000/day; only request counters persist in `.gev-cache/`. The server caches projected records, never raw responses. Private records are excluded; obscured coordinates become 0.2° cells. Observer identity is retained only for photo attribution. Eligible photos load directly from `inaturalist-open-data.s3.amazonaws.com`, with creator credit on ambient cards and creator/licence on selection. Per-record licences and noncommercial restrictions apply as listed above. Attribution appears in the layer row and Data attribution popover. Coverage follows community observations, not a census; Acartia adds Salish Sea marine mammals.
-- **iNaturalist grid (undocumented endpoint risk).** `/api/inaturalist/grid` shares observation-date, taxa, quality, pacing and budget rules with observations. A strict 64×64 UTFGrid schema guard fails closed; only logical-cell keys, counts and coordinates survive projection. Raw tiles, observation identifiers and free text are not retained. Projected tiles use a 400-entry LRU, 15-minute freshness and at most one hour of stale fallback. Views request at most six tiles; cached and adjacent-zoom coverage publishes before network waits, independently of observation pages. Cells supply a noninteractive density glow ranked within the view, from teal to amber with mono/CRT support. Every sighting badge comes from a real observation at its public position. Counts describe observations, not a population census. The endpoint is outside the documented v1 contract; schema drift disables grids until revalidated. See `docs/KNOWN-ISSUES.md`.
-- **Acartia.** Keyless. `/api/acartia/sightings` reads the current 7-day marine-mammal feed for ALL, MAMMALS and WHALES views intersecting 45.5–50.5° N, 126–121° W in the Salish Sea. WHALES accepts recognized cetaceans; other identified marine mammals appear under ALL/MAMMALS. The server rounds positions to 0.01° and drops comments before caching projected records (10 min fresh, stale ≤24 h); raw responses are not retained. Selected text cards credit the reporting provider under CC BY 4.0 and show Be Whale Wise guidance. Attribution also appears in the layer row and Data attribution popover. Opportunistic sightings, not a census.
+- **iNaturalist grid (cell schema risk).** `/api/inaturalist/grid` shares observation-date, taxa, quality, pacing and budget rules with observations. A strict 64×64 UTFGrid schema guard fails closed; only logical-cell keys, counts and coordinates survive projection. Raw tiles, observation identifiers and free text are not retained. Projected tiles use a 400-entry LRU, 15-minute freshness and at most one hour of stale fallback. Views request at most six tiles; cached and adjacent-zoom coverage publishes before network waits, independently of observation pages. Cells supply a noninteractive density glow ranked within the view, from teal to amber with mono/CRT support. Every sighting badge comes from a real observation at its public position. Counts describe observations, not a population census. The endpoint is documented in the v1 and v2 API docs as “Grid Tiles UTFGrid” (`/grid/{z}/{x}/{y}.grid.json`), but its per-cell records are not specified; schema drift disables grids until revalidated. See `docs/KNOWN-ISSUES.md`.
+- **Acartia.** Keyless. `/api/acartia/sightings` reads the current 7-day marine-mammal feed for ALL, MAMMALS and WHALES views intersecting 45.5–50.5° N, 126–121° W in the Salish Sea. WHALES accepts recognized cetaceans; other identified marine mammals appear under ALL/MAMMALS. The server rounds positions to 0.01° and drops comments before caching projected records (10 min fresh, stale ≤24 h); raw responses are not retained. Selected text cards credit the reporting provider under CC BY 4.0 and show Be Whale Wise guidance. `/sightings/current` answers without a key today, but Acartia's README asks API users to create an account and generate an API key on the [Acartia dashboard](https://acartia.io/) and to follow its [community guidelines](https://acartia.io/register). Attribution also appears in the layer row and Data attribution popover. Opportunistic sightings, not a census.
 - **Mapped installations.** OpenFreeMap military polygons use a bundled Overture/OSM name index; wide views show named points. Optional operator-configured Overpass and explicit Google Places searches keep their own source paths. Mapped data does not establish current activity or complete coverage.
 - **Place search.** Named-place fly-to uses Google Geocoding when a Maps key is configured, then Photon (`PHOTON_URL`; unset uses the public instance, empty disables it), then `/api/geocode` (Nominatim search) when neither answers. `/api/geocode` and the voice outline route `/api/geocode/outline` share one Nominatim queue (`NOMINATIM_URL`; unset, empty and invalid values disable it; an operator must explicitly select an authorized endpoint): one request at a time at least 1.1 s apart, an identifying `User-Agent` and `Referer`, a short queue that refuses a burst, a pause after 429/403/5xx answers (honouring `Retry-After` in full), at most one retry after a network failure, and a per-install daily cap on public-instance requests (`NOMINATIM_DAILY_CAP`, default 50). Processes using the same installation state file hold one lock through the actual fetch invocation and recording the next public start, with the daily slot persisted before invocation; restarts share that count, spacing and any pause. An unfinished dispatch marker fails closed until operator recovery; it is never automatically reclaimed. Public access fails closed if the state file cannot be read, locked, written or semantically validated. This coordination does not span independent installations or state directories and does not establish an application-wide public-service allowance or authorize public use. An operator-selected non-public endpoint is outside the public cap, spacing and durable-state requirement; an upstream cooldown is kept with the endpoint that returned it rather than leaking across operator URLs. Answers are cached on disk (outlines 90 days, places 30 days, no-results 24 hours); failures are not cached. Outlines are looked up only for an explicit ask, after bundled data and any configured Overpass, and only results whose type suits the ask are used. Administrative outline responses expose country/admin-1/admin-2 identity only when the selected Nominatim row has a recognized, unambiguous address type consistent with its own name; numeric rank, ambiguous types, missing fields and contradictory names do not manufacture identity. It is not used for systematic or bulk queries.
 - **Street and building outlines.** Voice street highlights, pointed-at buildings and grounds use the OpenFreeMap vector tiles the traffic layer already loads. Traffic and outlines share one bounded pending fetch/decode owner per immutable XYZ tile; materialized outline geometry is charged to the retained-byte ceiling and capped by coordinate count. Consumer result caches and request lifetimes remain independent, while eviction or explicit teardown cancels queued idle projections and releases their decoded owner. No Overpass request is made unless `OVERPASS_UPSTREAMS` is configured. Named grounds require a returned name matching the selected place, except that an ask whose head noun names a kind of grounds (a school, university or college, hospital, cemetery, stadium or zoo) may use the part of the smallest unnamed tile area of that class that holds the resolved place; a differently named area never answers. Other anonymous landcover polygons cannot establish identity, so unsupported grounds stay unavailable rather than borrowing a nearby POI name.
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 2449130f4..96d85431f 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -160,7 +160,8 @@ adjacent-zoom tiles publish before network waits; each arriving tile replaces
 its covered area, including healthy empty tiles. Grid tiles publish even while
 the independent observation request is pending or failed. Enable waits for one
 camera settle; camera acquisition uses moveEnd with a 600 ms debounce. The
-undocumented UTFGrid endpoint has a schema guard; see `KNOWN-ISSUES.md`.
+documented UTFGrid endpoint's unspecified cell records have a schema guard;
+see `KNOWN-ISSUES.md`.
 
 Ambient cards use a fixed 96 px image width and a short creator name credit,
 with a bounded frame cache. New cards fill free screen regions; visible cards
diff --git a/docs/KNOWN-ISSUES.md b/docs/KNOWN-ISSUES.md
index ccd3ed906..3fdcbe67b 100644
--- a/docs/KNOWN-ISSUES.md
+++ b/docs/KNOWN-ISSUES.md
@@ -10,12 +10,14 @@ For the roadmap and open backlog, see the repository issue tracker.
 
 ## Open
 
-### Wildlife grid is an undocumented iNaturalist endpoint
+### Wildlife grid relies on the iNaturalist UTFGrid cell schema
 
 Status: Open (guarded fallback)
 
-The operational `/v1/grid/{z}/{x}/{y}.grid.json` endpoint is not part of the
-published v1 Swagger contract. Its 64×64 UTFGrid shape, keys and cell records
+The `/v1/grid/{z}/{x}/{y}.grid.json` endpoint is documented in the v1 and v2
+API docs (“Grid Tiles UTFGrid”), but the documented response only defines the
+UTFGrid `grid`, `keys` and `data` members; the per-cell records are not
+specified. Its 64×64 UTFGrid shape, keys and cell records
 are validated in full at the allow-list proxy. A schema change or unavailable
 tile retains its last good cells for at most one hour; a cold unavailable grid
 uses sampled observations with the same badges and screen buckets, without
diff --git a/src/layers/wildlifeSightings/docs.test.mjs b/src/layers/wildlifeSightings/docs.test.mjs
index 3f84357d3..794bd62b5 100644
--- a/src/layers/wildlifeSightings/docs.test.mjs
+++ b/src/layers/wildlifeSightings/docs.test.mjs
@@ -109,3 +109,21 @@ test('Wildlife docs describe one source link, name declutter and globe glow limi
   assert.match(section, /5% radius margin/);
   assert.match(section, /add no per-frame work/);
 });
+
+test('Wildlife docs cite the documented UTFGrid endpoint and the Acartia key request', () => {
+  for (const path of [
+    'docs/KNOWN-ISSUES.md',
+    'DATA_SOURCES.md',
+    'docs/CURRENT-STATE.md',
+  ]) {
+    const text = read(path);
+    assert.doesNotMatch(text, /undocumented (iNaturalist|UTFGrid) endpoint/i);
+    assert.doesNotMatch(text, /grid \(undocumented/i);
+  }
+  for (const path of ['docs/KNOWN-ISSUES.md', 'DATA_SOURCES.md'])
+    assert.match(read(path), /Grid Tiles UTFGrid/);
+  assert.match(
+    read('DATA_SOURCES.md'),
+    /create an account and generate an API key/,
+  );
+});

From 6479167b500357004ca2f0a11aaee1ae23d33a82 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:14:27 -0800
Subject: [PATCH 59/71] Pivot a tilt at exactly 1,000 km and report where a
 zoom now ends it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A pivot range rebuilt from the camera's position came back a hair over the 1,000 km cutoff when the view sat exactly on it, so a tilt from 1,000 km ran in place and lifted the crosshair onto the sky. The cutoff now allows 1 m of slack.

A zoom during a tilt to an angle changes the range the pivot holds, and with it the place's horizon limit, but the tilt kept its old goal and its reply its old angle: from 400 km, a tilt to -5° zoomed out x2.5 reported -5° with no note and ended at -9.4°. The zoom now re-judges the goal at the new range, eases the tilt from where it is to it, and its result names the angle the tilt now ends at, with a note.
---
 docs/CURRENT-STATE.md   |  2 +-
 src/cameraTilt.test.mjs | 76 +++++++++++++++++++++++++++++++++++++++++
 src/cameraVerbs.js      | 64 ++++++++++++++++++++++++++++++----
 src/voice/gevActions.js |  5 +++
 4 files changed, 139 insertions(+), 8 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 9036db387..d41c435f1 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5590,7 +5590,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. A motion that runs after a fly-to of the same reply has already found nothing (Gemini runs one turn's calls one by one, and passes its turn as the reply) is refused the same way rather than moving the old view; a motion in a later reply runs. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. A zoom during a tilt to an angle re-judges the place's horizon limit at the new range: when that moves where the tilt ends, the tilt eases from where it is to the new end, and the zoom's result names that angle (`pitchDeg`) with a `note`. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. A motion that runs after a fly-to of the same reply has already found nothing (Gemini runs one turn's calls one by one, and passes its turn as the reply) is refused the same way rather than moving the old view; a motion in a later reply runs. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index a67ecee86..0dcb2d1b0 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -610,3 +610,79 @@ for (const direction of ['left', 'right'])
     assert.match(angled.error, /pitchDeg alone/);
     assert.equal(getActiveCameraMotion(), null);
   });
+
+// The 1,000 km pivot cutoff includes its boundary: at exactly 1,000 km the
+// pivot range came back a hair over it, so the tilt ran in place and put the
+// crosshair on the sky.
+test('from exactly 1,000 km a tilt to -5° still pivots about the place', (t) => {
+  const h = harness(t, { height: 1_000_000 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
+  assert.equal(result.ok, true);
+  h.finish();
+  assert.ok(h.viewTarget(), 'the crosshair is on the sky');
+  assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - result.pitchDeg) < 0.5,
+    `camera at ${pitchDeg(h.camera)}°, reported ${result.pitchDeg}°`,
+  );
+  assert.match(result.note, /horizon/);
+});
+
+// A zoom mid-tilt moves the pivot's horizon limit: the zoom's reply names the
+// angle the tilt now ends at, and the camera ends there.
+test('a zoom out during a tilt to an angle reports the angle it now ends at', (t) => {
+  const h = harness(t, { height: 400_000 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  assert.equal(result.pitchDeg, -5);
+  assert.equal(result.note, undefined);
+  for (let i = 0; i < 10; i += 1) h.tick();
+  const zoom = adjustOrbitRange(2.5);
+  assert.equal(zoom.kind, 'tilt');
+  assert.equal(zoom.changed, true);
+  h.finish();
+  assert.ok(h.viewTarget(), 'the crosshair is on the sky');
+  assert.ok(zoom.pitchDeg < -5, `zoom reported ${zoom.pitchDeg}°`);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - zoom.pitchDeg) < 0.5,
+    `camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
+  );
+  assert.match(zoom.note, /horizon/);
+});
+
+test('a zoom in during a horizon-limited tilt reports the angle it now reaches', (t) => {
+  const h = harness(t, { height: 900_000 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  assert.ok(result.pitchDeg < -5, `reported ${result.pitchDeg}°`);
+  for (let i = 0; i < 10; i += 1) h.tick();
+  const zoom = adjustOrbitRange(1 / 2.4);
+  assert.equal(zoom.changed, true);
+  h.finish();
+  assert.equal(zoom.pitchDeg, -5);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -5) < 0.5,
+    `camera at ${pitchDeg(h.camera)}°`,
+  );
+});
+
+test('a voice zoom during a tilt to an angle passes on the new end angle', async (t) => {
+  const h = harness(t, { height: 400_000 });
+  const runner = createGevActionRunner({
+    viewer: h.viewer,
+    styleManager: {},
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  for (let i = 0; i < 10; i += 1) h.tick();
+  const zoom = await runner('adjust_camera_zoom', {
+    direction: 'out',
+    amount: 'lot',
+  });
+  assert.equal(zoom.ok, true);
+  assert.equal(zoom.tiltRangeAdjusted, true);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - zoom.pitchDeg) < 0.5,
+    `camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
+  );
+  assert.match(zoom.note, /horizon/);
+});
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 4618a434d..0681d6a2b 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -62,6 +62,12 @@ const TILT_MIN_CLEARANCE_M = 150;
  * crosshair point, so the tilt happens in place instead.
  */
 const TILT_PIVOT_MAX_RANGE_M = 1_000_000;
+/**
+ * A pivot range rebuilt from the camera's position comes back a hair off the
+ * range it was set at: a range this close past the cutoff still counts as on
+ * it.
+ */
+const TILT_PIVOT_RANGE_SLACK_M = 1;
 /**
  * The shallowest a pivot swing goes when its clearance is not what stops it.
  * From several hundred km the camera's own horizon limit lies past the
@@ -1403,10 +1409,20 @@ function tiltUpLimit({ target, pivot }) {
 function tiltStartFrame(cam) {
   const target = _viewer.trackedEntity ? null : _getTarget?.(_viewer);
   let pivot = target ? tiltPivot(cam, target) : null;
-  if (pivot && pivot.range > TILT_PIVOT_MAX_RANGE_M) pivot = null;
+  if (pivot && !tiltPivotInReach(pivot.range)) pivot = null;
   return { target, pivot, from: cam.pitch };
 }
 
+/** Whether a tilt may pivot at this range: up to and including the cutoff. */
+function tiltPivotInReach(range) {
+  return range <= TILT_PIVOT_MAX_RANGE_M + TILT_PIVOT_RANGE_SLACK_M;
+}
+
+/** 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.`;
+}
+
 /** Ground pivot for a tilt: heading, pitch and range in the target's own frame. */
 function tiltPivot(cam, target) {
   const local = Cesium.Matrix4.multiplyByPoint(
@@ -1917,6 +1933,9 @@ export function moveCamera(args = {}, runNavigation = null) {
         state.mode = 'once';
         state.direction = goal > from ? 'up' : 'down';
         state.goalPitch = goal;
+        // A zoom mid-tilt moves the horizon limit; it re-judges the goal
+        // against the angle asked for.
+        state.askedPitch = tiltToPitch;
         state.durationS = Math.max(
           ONCE.durationS,
           Math.abs(Cesium.Math.toDegrees(goal - from)) / TILT_TO_DEG_S,
@@ -2024,9 +2043,7 @@ export function moveCamera(args = {}, runNavigation = null) {
           Cesium.Math.toDegrees(horizonLimited ?? tiltToPitch),
         ),
       }),
-      ...(horizonLimited !== null && {
-        note: `Stopped at ${Math.round(Cesium.Math.toDegrees(horizonLimited))}°: from this range a shallower angle puts the place past the horizon. Zoom in to tilt further.`,
-      }),
+      ...(horizonLimited !== null && { note: tiltHorizonNote(horizonLimited) }),
     };
   };
   const preserveCameraFlight =
@@ -2043,8 +2060,10 @@ export function moveCamera(args = {}, runNavigation = null) {
  * fight the per-frame lookAt (field test: "zoom out did literally nothing").
  * A tilt swinging about its pivot holds a range the same way.
  * @param {number} factor  >1 zooms out (radius grows), <1 zooms in.
- * @returns {{kind: string, changed: boolean}|null} the motion that consumed
- *   the zoom, and whether its range moved; null when none did.
+ * @returns {{kind: string, changed: boolean, pitchDeg?: number,
+ *   note?: string}|null} the motion that consumed the zoom, and whether its
+ *   range moved; null when none did. A tilt to an angle whose end the new
+ *   range moves also names the angle it now ends at (pitchDeg), with a note.
  */
 export function adjustOrbitRange(factor) {
   if (!_active || !['orbit', 'tilt'].includes(_active.kind) || !_active.hpr)
@@ -2066,7 +2085,38 @@ export function adjustOrbitRange(factor) {
     Math.min(Math.max(ceiling, range), range * factor),
   );
   // Under half a metre counts as not moved, as for a plain zoom.
-  return { kind, changed: Math.abs(hpr.range - range) >= 0.5 };
+  const changed = Math.abs(hpr.range - range) >= 0.5;
+  return { kind, changed, ...(changed && retargetTiltAfterZoom(_active)) };
+}
+
+/**
+ * A zoom changed the range a tilt to an angle holds, and with it the place's
+ * horizon limit: aim the tilt at the angle asked for or the new limit,
+ * whichever comes first, from where the camera is now. Returns the end angle
+ * and a note for the reply when that end moved, otherwise nothing.
+ */
+function retargetTiltAfterZoom(m) {
+  if (m.kind !== 'tilt' || m.mode !== 'once' || m.askedPitch === undefined)
+    return {};
+  const from = _viewer.camera.pitch;
+  if (!(m.askedPitch > from)) return {};
+  const limit = tiltUpLimit({ target: m.target, pivot: m.hpr });
+  const goal = Math.min(m.askedPitch, Math.max(from, limit));
+  if (Math.abs(goal - m.goalPitch) < 1e-6) return {};
+  m.goalPitch = goal;
+  m.startPitch = from;
+  m.elapsed = 0;
+  m.durationS = Math.max(
+    ONCE.durationS,
+    Math.abs(Cesium.Math.toDegrees(goal - from)) / TILT_TO_DEG_S,
+  );
+  const limited = goal !== m.askedPitch;
+  return {
+    pitchDeg: Math.round(Cesium.Math.toDegrees(goal)),
+    note: limited
+      ? tiltHorizonNote(goal)
+      : `The tilt now reaches ${Math.round(Cesium.Math.toDegrees(goal))}°.`,
+  };
 }
 
 /**
diff --git a/src/voice/gevActions.js b/src/voice/gevActions.js
index a01e3328e..9692edf94 100644
--- a/src/voice/gevActions.js
+++ b/src/voice/gevActions.js
@@ -471,6 +471,11 @@ export function createGevActionRunner({
           amount: amt,
           [held.kind === 'tilt' ? 'tiltRangeAdjusted' : 'orbitRadiusAdjusted']:
             true,
+          // A tilt to an angle names the angle the new range now ends it at.
+          ...(held.pitchDeg !== undefined && {
+            pitchDeg: held.pitchDeg,
+            note: held.note,
+          }),
         };
       }
     }

From 198c2faf4f9cf11f266e145afaa68b00157b8dff Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:14:27 -0800
Subject: [PATCH 60/71] =?UTF-8?q?Say=20the=20-45=C2=B0=20tilt=20default=20?=
 =?UTF-8?q?in=20the=20pitchDeg=20description=20again?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The trim that fitted the tilt wording under the Realtime prompt ceiling dropped the -45° default from pitchDeg, so the model no longer read why a bare tilt goes oblique. pitchDeg reads 'Absolute; -45 default, -89 top-down.' again, and the direction description becomes 'Pan/rotate/tilt steps; orbit/rotate_globe default right.' to pay for it: the Overpass prompt measures 55,499, 1 under the 55,500 ceiling. The schema pin and the measured-size note follow.
---
 server/providers/openai/toolDescriptions.js | 4 ++--
 src/radioMarkup.test.mjs                    | 8 +++++---
 src/voice/actionSchemas.test.mjs            | 4 ++--
 src/voice/pointAndAsk.test.mjs              | 8 ++++----
 4 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/server/providers/openai/toolDescriptions.js b/server/providers/openai/toolDescriptions.js
index f4000ddad..c7e78c7d6 100644
--- a/server/providers/openai/toolDescriptions.js
+++ b/server/providers/openai/toolDescriptions.js
@@ -523,7 +523,7 @@ export const ACTION_DESCRIPTIONS = {
       properties: {
         direction: {
           description:
-            'Needed for pan/rotate/tilt steps; orbit/rotate_globe default right.',
+            'Pan/rotate/tilt steps; orbit/rotate_globe default right.',
           $position: 2,
         },
         mode: {
@@ -532,7 +532,7 @@ export const ACTION_DESCRIPTIONS = {
           $position: 2,
         },
         pitchDeg: {
-          description: 'Absolute; -89 top-down.',
+          description: 'Absolute; -45 default, -89 top-down.',
           $position: 1,
         },
       },
diff --git a/src/radioMarkup.test.mjs b/src/radioMarkup.test.mjs
index 3c59d989d..324adceb5 100644
--- a/src/radioMarkup.test.mjs
+++ b/src/radioMarkup.test.mjs
@@ -232,14 +232,16 @@ test('no unchanged Realtime tool definition drifts silently', () => {
     camera.description,
     'Direct the camera like a drone operator: orbit the current view target, pan, tilt, or rotate — one bounded nudge (mode=once) or continuous motion until stopped (mode=continuous). Continuous motion also stops on any manual camera input or when a navigation tool runs. Say the RESULTING state when confirming ("Orbiting slowly"). Globe rotation (rotate_globe) spins Earth right continuously by default; explicit direction, mode and speed take precedence. It checks fit and may refuse.',
   );
-  // Tilt to an angle adds an absolute pitchDeg and says tilt steps need a
-  // direction; check them, then restore the legacy fields for the pin.
+  // Tilt to an angle adds an absolute pitchDeg with its -45° default, and
+  // names tilt steps among the direction's uses; check them, then restore
+  // the legacy fields for the pin.
   assert.equal(
     camera.parameters.properties.direction.description,
-    'Needed for pan/rotate/tilt steps; orbit/rotate_globe default right.',
+    'Pan/rotate/tilt steps; orbit/rotate_globe default right.',
   );
   assert.equal(camera.parameters.properties.pitchDeg.type, 'number');
   assert.match(camera.parameters.properties.pitchDeg.description, /^Absolute;/);
+  assert.match(camera.parameters.properties.pitchDeg.description, /-45 default/);
   delete camera.parameters.properties.pitchDeg;
   assert.equal(camera.parameters.properties.mode.description, 'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.');
   camera.parameters.properties.mode.description = 'once = bounded eased nudge (default); continuous = until stop/manual input.';
diff --git a/src/voice/actionSchemas.test.mjs b/src/voice/actionSchemas.test.mjs
index fa9d40bec..296ae0251 100644
--- a/src/voice/actionSchemas.test.mjs
+++ b/src/voice/actionSchemas.test.mjs
@@ -57,8 +57,8 @@ test('the complete Realtime tool payload pins the manifest-generated layer relea
     // tightened area tool wording follow review.
     // control_cockpit states the own-layer entry rule (Contacts not required).
     // move_camera tilt takes an optional pitchDeg angle, described as
-    // absolute, with steps sent as a direction.
-    '17e54c1a04054edf48f2eddcf88c60ac66ec7c885fb48596b778bfee0be8a544',
+    // absolute with its -45 default, with steps sent as a direction.
+    '6a0d154e68beb787c4e20f12d29a5c86577dc343f3e71d8b5651998ea45d8c3c',
   );
 });
 
diff --git a/src/voice/pointAndAsk.test.mjs b/src/voice/pointAndAsk.test.mjs
index c413477b8..5d6d0fdd1 100644
--- a/src/voice/pointAndAsk.test.mjs
+++ b/src/voice/pointAndAsk.test.mjs
@@ -350,10 +350,10 @@ test('deixis prompt lint: one short rule, and every sentinel it names exists in
   // the analyst area scopes) raised the ceiling to 55,500; tightening the
   // AREAS rule and the area tool descriptions left it at 55,103 as measured
   // below (every tool, osm_query included); main's Sea Marks and Ski Pistes
-  // layers bring it to 55,210, and the tilt pitchDeg argument with main's
-  // cockpit entry rule to 55,337. integrationContract's Overpass prompt is
-  // the tightest, at 55,497 (3 under). A new tool or rule has to fit under
-  // this ceiling.
+  // layers bring it to 55,210, and the tilt pitchDeg argument (with its -45
+  // default) and main's cockpit entry rule to 55,339. integrationContract's
+  // Overpass prompt is the tightest, at 55,499 (1 under). A new tool or rule
+  // has to fit under this ceiling.
   const size = instructions.length + JSON.stringify(GEV_REALTIME_TOOLS).length;
   assert.ok(size <= 55_500, `prompt size ${size}`);
 });

From f332150689a889718b1389dc094470d44ca46bd9 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:16:05 -0800
Subject: [PATCH 61/71] fix(camera): hold the globe recovery until every
 pointer is released
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The held-pointer guard was one flag, so with two fingers down, lifting one cleared it and the recovery turned the view down under the other (pitch -42° to -90°). It now tracks each pressed pointer by id and defers until the last is released.

A release outside the window that the page never sees could leave the recovery deferred for good. A lost window focus, a hidden page or a lost pointer capture now releases every held pointer, and a pointer that moves with no button down is released.
---
 docs/CURRENT-STATE.md        |  8 ++-
 src/app/application.test.mjs | 96 ++++++++++++++++++++++++++++++++++++
 src/app/viewer.js            | 43 +++++++++++-----
 3 files changed, 132 insertions(+), 15 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 545c4efd8..08cdf3a49 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -104,8 +104,12 @@ other ways a move can end looking away, such as a saved or shared view that did.
 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) and the 2D and Columbus modes; a check a
-flight, scene or held pointer defers runs once it ends. A Director
+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
+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
+button down. A Director
 shot loaded or replayed outside a run is not a playing scene. A view that loses
 its surface without a camera move (a resize, or turning the scope on) is left as
 it is until the next move. A voice turn requested while the camera is tracked is
diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs
index e25b2ce11..c01878d89 100644
--- a/src/app/application.test.mjs
+++ b/src/app/application.test.mjs
@@ -811,6 +811,102 @@ test('the recovery waits while a pointer is held on the globe', () => {
   assert.equal(timers.pending(), 0, 'disposed recovery holds no listeners');
 });
 
+/** A held-pointer recovery over a canvas in a document in a window. */
+function heldPointerRecovery() {
+  const timers = fakeTimers();
+  const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
+  const window = new EventTarget();
+  const document = Object.assign(new EventTarget(), {
+    defaultView: window,
+    visibilityState: 'visible',
+  });
+  scene.canvas = Object.assign(new EventTarget(), {
+    clientWidth: 1225,
+    clientHeight: 923,
+    ownerDocument: document,
+  });
+  const dispose = installGlobeInViewRecovery(viewer, timers);
+  const pointer = (target, type, pointerId, init = {}) =>
+    target.dispatchEvent(
+      Object.assign(new Event(type), { pointerId, ...init }),
+    );
+  /** Press, move and hold still: the check defers while a pointer is held. */
+  const holdStill = () => {
+    aim(camera, reportedStuckView);
+    camera.moveStart.raiseEvent();
+    for (let i = 0; i < 8; i += 1) timers.tick();
+    camera.moveEnd.raiseEvent();
+    for (let i = 0; i < 8; i += 1) timers.tick();
+  };
+  const settle = () => {
+    for (let i = 0; i < 3; i += 1) timers.tick();
+  };
+  const recovered = () =>
+    Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6);
+  return {
+    camera,
+    document,
+    window,
+    dispose,
+    pointer,
+    holdStill,
+    settle,
+    recovered,
+    canvas: scene.canvas,
+  };
+}
+
+// Releasing one of two fingers cleared the held flag, and the recovery
+// turned the view down under the finger still on the glass.
+test('the recovery waits until every held pointer is released', () => {
+  const h = heldPointerRecovery();
+  h.pointer(h.canvas, 'pointerdown', 1);
+  h.pointer(h.canvas, 'pointerdown', 2);
+  h.holdStill();
+  h.pointer(h.document, 'pointerup', 1);
+  h.settle();
+  assert.equal(h.recovered(), false, 'left alone under the second finger');
+  assert.equal(globeOutOfFrame(h.camera), true);
+  h.pointer(h.document, 'pointercancel', 2);
+  h.settle();
+  assert.equal(h.recovered(), true, 'recovered once both are released');
+  h.dispose();
+});
+
+// A release the page never sees (the pointer let go outside the window)
+// must not hold the recovery off for good.
+for (const [label, lose] of [
+  ['the window loses focus', (h) => h.window.dispatchEvent(new Event('blur'))],
+  [
+    'the page is hidden',
+    (h) => {
+      h.document.visibilityState = 'hidden';
+      h.document.dispatchEvent(new Event('visibilitychange'));
+    },
+  ],
+  [
+    'the canvas loses the pointer capture',
+    (h) => h.pointer(h.canvas, 'lostpointercapture', 1),
+  ],
+  [
+    'the pointer moves with no button down',
+    (h) => h.pointer(h.document, 'pointermove', 1, { buttons: 0 }),
+  ],
+]) {
+  test(`a held pointer whose release is lost stops deferring when ${label}`, () => {
+    const h = heldPointerRecovery();
+    h.pointer(h.canvas, 'pointerdown', 1);
+    h.holdStill();
+    h.pointer(h.document, 'pointermove', 1, { buttons: 1 });
+    h.settle();
+    assert.equal(h.recovered(), false, 'left alone while held');
+    lose(h);
+    h.settle();
+    assert.equal(h.recovered(), true, 'recovered once the hold is let go');
+    h.dispose();
+  });
+}
+
 function fakeTimers() {
   let next = 1;
   const pending = new Map();
diff --git a/src/app/viewer.js b/src/app/viewer.js
index 12ef67269..fc75c0498 100644
--- a/src/app/viewer.js
+++ b/src/app/viewer.js
@@ -207,26 +207,43 @@ export function installGlobeInViewRecovery(
     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 for its release.
+  // 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;
-  let pointerHeld = false;
-  const onPointerDown = () => {
-    pointerHeld = true;
+  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 onPointerUp = () => {
-    pointerHeld = false;
+  const releaseAll = () => heldPointers.clear();
+  const onVisibilityChange = () => {
+    if (canvas.ownerDocument.visibilityState === 'hidden') releaseAll();
   };
-  canvas?.addEventListener?.('pointerdown', onPointerDown);
-  releaseTarget?.addEventListener?.('pointerup', onPointerUp);
-  releaseTarget?.addEventListener?.('pointercancel', onPointerUp);
+  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() || pointerHeld) return false;
+    if (camera._currentFlight || paused() || heldPointers.size > 0)
+      return false;
     const height = camera.positionCartographic?.height;
     if (
       !(height > minHeight) ||
@@ -310,9 +327,9 @@ export function installGlobeInViewRecovery(
     stopSettling();
     removeMoveEnd();
     removeMoveStart();
-    canvas?.removeEventListener?.('pointerdown', onPointerDown);
-    releaseTarget?.removeEventListener?.('pointerup', onPointerUp);
-    releaseTarget?.removeEventListener?.('pointercancel', onPointerUp);
+    for (const [target, type, listener] of listeners)
+      target?.removeEventListener?.(type, listener);
+    heldPointers.clear();
   };
 }
 

From 42fa974ee38a07293df64b70feabc45787737ed5 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:27:19 -0800
Subject: [PATCH 62/71] fix(wildlife): keep each failed source's retry timing
 after a partial failure

A partial failure reset the layer's cooldown, so a camera move retried at
once. Acartia's error was discarded, an absent X-Upstream-Status hid the
HTTP 503 (the proxy's daily-budget reply), and a grid schema error masked
the observation 503. Each failed source now keeps its status and
Retry-After, the HTTP status counts when no upstream status is sent, and the
layer waits for the longest 429/5xx cooldown among them. The shown error is
the one that explains the cooldown.
---
 docs/CURRENT-STATE.md                         |   6 +-
 .../wildlifeSightings/acquisition.test.mjs    | 136 +++++++++++++++++-
 src/layers/wildlifeSightings/lifecycle.js     |  79 ++++++----
 src/layers/wildlifeSightings/source.js        |  41 +++++-
 4 files changed, 229 insertions(+), 33 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index 96d85431f..5166e4a2a 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -124,7 +124,11 @@ with retry timing; logs exclude request URLs and upstream exception text.
 A partial failure still draws what arrived: a failed iNaturalist request, or
 one failed half of an antimeridian view, keeps a good Acartia reply and the
 other half, retains that area's last iNaturalist rows and reports DEGRADED.
-The update fails outright only when every requested source failed.
+The update fails outright only when every requested source failed. Each failed
+source keeps its HTTP status and `Retry-After` (the HTTP status counts when no
+`X-Upstream-Status` is sent), and the next request waits out the longest 429 or
+5xx cooldown among them. One update requests both sources, so the cooldown
+holds the whole layer; a fully successful refresh clears it.
 
 `/api/acartia/sightings` adds Salish Sea marine mammals within 45.5–50.5° N,
 126–121° W, cached ten minutes and stale for at most 24 h. A valid empty
diff --git a/src/layers/wildlifeSightings/acquisition.test.mjs b/src/layers/wildlifeSightings/acquisition.test.mjs
index ea1d6fc1a..d343ad9b0 100644
--- a/src/layers/wildlifeSightings/acquisition.test.mjs
+++ b/src/layers/wildlifeSightings/acquisition.test.mjs
@@ -833,10 +833,10 @@ test('an empty tile retires its old zoom cells while uncovered density survives
   assert.equal(h.state.gridTotal, 2);
 });
 
-test('only marked upstream failures create cooldown; local pacing, network and schema errors can retry on the next view', async () => {
+test('only 429 and 5xx failures create cooldown; client, network and schema errors can retry on the next view', async () => {
   for (const error of [
-    Object.assign(new Error('iNaturalist HTTP 503'), {
-      status: 503,
+    Object.assign(new Error('iNaturalist HTTP 400'), {
+      status: 400,
       upstreamStatus: 0,
       retryAfterSec: 30,
     }),
@@ -873,6 +873,19 @@ test('only marked upstream failures create cooldown; local pacing, network and s
     2,
     'actual Retry-After is honored without imposing a 30s local floor',
   );
+  // The proxy's daily-budget 503 has no upstream status. Its HTTP status and
+  // Retry-After still govern the next request.
+  const budget = harness({
+    getSnapshot: async () => {
+      throw Object.assign(new Error('iNaturalist HTTP 503'), {
+        status: 503,
+        upstreamStatus: 0,
+        retryAfterSec: 3600,
+      });
+    },
+  });
+  await budget.layer.update();
+  assert.equal(budget.layer.getStats().retryInSec, 3600);
 });
 
 test('stale cached tiles with local pacing metadata keep their display and do not enter cooldown', async () => {
@@ -942,3 +955,120 @@ test('an explicit upstream Retry-After zero retries immediately while a missing
     }
   }
 });
+
+const salishSea = { south: 47.5, west: -122.5, north: 47.7, east: -122.2 };
+const inatRow = {
+  stableId: 'inat:301',
+  origin: 'inaturalist',
+  lat: 47.6,
+  lon: -122.3,
+  observedAt: NOW - 3_600_000,
+  iconic: 'Mammalia',
+};
+const acartiaRow = {
+  stableId: 'acartia:301',
+  origin: 'acartia',
+  lat: 47.6,
+  lon: -122.35,
+  observedAt: NOW - 3_600_000,
+  cetacean: true,
+  quality: 'research',
+  provider: { name: 'Provider', entity: null },
+};
+const emptyGrid = () =>
+  Response.json({ cells: [], totalResults: 0, fetchedAt: NOW });
+const unavailable = (headers = {}) =>
+  new Response('', {
+    status: 503,
+    headers: { 'Retry-After': '120', ...headers },
+  });
+
+// Each case runs the real source and lifecycle. A healthy source draws its
+// rows while the failed source's Retry-After holds the next acquisition.
+for (const [name, respond] of [
+  [
+    'Acartia alone returns 503',
+    (url) =>
+      url.startsWith('/api/acartia')
+        ? unavailable()
+        : url.startsWith('/api/inaturalist/grid?')
+          ? emptyGrid()
+          : Response.json({
+              rows: [inatRow],
+              totalResults: 1,
+              fetchedAt: NOW,
+            }),
+  ],
+  [
+    'iNaturalist returns 503 without X-Upstream-Status',
+    (url) =>
+      url.startsWith('/api/acartia')
+        ? Response.json({ rows: [acartiaRow], fetchedAt: NOW })
+        : url.startsWith('/api/inaturalist/grid?')
+          ? emptyGrid()
+          : unavailable(),
+  ],
+  [
+    'iNaturalist returns 503 while every grid tile fails its schema',
+    (url) =>
+      url.startsWith('/api/acartia')
+        ? Response.json({ rows: [acartiaRow], fetchedAt: NOW })
+        : url.startsWith('/api/inaturalist/grid?')
+          ? Response.json({ cells: 'malformed' })
+          : unavailable({ 'X-Upstream-Status': '503' }),
+  ],
+]) {
+  test(`a partial failure keeps its Retry-After: ${name}`, async () => {
+    let healthy = false;
+    let requests = 0;
+    const source = createWildlifeSightingsSource({
+      now: () => NOW,
+      fetchImpl: async (url) => {
+        if (!url.startsWith('/api/inaturalist/grid?')) requests++;
+        if (healthy)
+          return url.startsWith('/api/acartia')
+            ? Response.json({ rows: [acartiaRow], fetchedAt: NOW })
+            : url.startsWith('/api/inaturalist/grid?')
+              ? emptyGrid()
+              : Response.json({
+                  rows: [inatRow],
+                  totalResults: 1,
+                  fetchedAt: NOW,
+                });
+        return respond(url);
+      },
+    });
+    const h = harness(source);
+    h.bounds(salishSea);
+    h.state.enabled = false;
+    h.layer.enable();
+    const first = h.layer.update();
+    await h.advance(300);
+    await first;
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(h.state.renderedRows.length, 1, 'the healthy source draws');
+    assert.ok(h.state.error, 'the failed source is reported');
+    // The source clock stays at NOW; the layer settled 300 ms of camera time.
+    assert.equal(h.state.retryAt, NOW + 300 + 120_000);
+    assert.equal(h.layer.getStats().retryInSec, 120);
+    const attempted = requests;
+    h.bounds({ ...salishSea, north: 47.8 });
+    h.moveEnd();
+    assert.equal([...h.timers.values()][0]?.delay, 120_000);
+    await h.advance(119_999);
+    await h.layer.update();
+    assert.equal(
+      requests,
+      attempted,
+      'neither a camera move nor manager polling skips the cooldown',
+    );
+    healthy = true;
+    await h.advance(1);
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.ok(requests > attempted, 'acquisition resumes at the deadline');
+    assert.equal(h.state.error, null);
+    assert.equal(h.state.retryAt, 0, 'a fully successful refresh clears it');
+    assert.equal(h.layer.getStats().retryInSec, undefined);
+    assert.equal(h.state.renderedRows.length, 2);
+  });
+}
diff --git a/src/layers/wildlifeSightings/lifecycle.js b/src/layers/wildlifeSightings/lifecycle.js
index 6da425c7a..3b2a2999a 100644
--- a/src/layers/wildlifeSightings/lifecycle.js
+++ b/src/layers/wildlifeSightings/lifecycle.js
@@ -1,6 +1,9 @@
 import { msg } from '../../i18n/marker.js';
 import { getWildlifeHeightBand, rowInWildlifeBoxes } from './model.js';
-import { combineWildlifeGridSnapshots } from './source.js';
+import {
+  combineWildlifeGridSnapshots,
+  wildlifeFailureRetryable,
+} from './source.js';
 import { wildlifeMeasure } from './performance.js';
 import { isRecentWildlifeSighting } from './records.js';
 import {
@@ -92,25 +95,26 @@ export function createLifecycle({ state, services, parts }) {
     state.pendingParams = null;
   }
 
-  function applyRetry(error, retryAfterSec = null) {
-    // Only upstream failures impose cooldown; network/schema errors retry on pan.
-    const status =
-      error?.upstreamStatus ??
-      error?.status ??
-      Number(/HTTP (\d{3})/.exec(error?.message || '')?.[1]);
-    const retryDelays = [error?.retryAfterSec, retryAfterSec].filter(
-      (value) => Number.isFinite(value) && value >= 0,
-    );
-    const retryFromSnapshot =
-      Number.isFinite(retryAfterSec) && retryAfterSec >= 0;
-    if (!(status === 429 || status >= 500) && !retryFromSnapshot) {
+  function applyRetry(errors, retryAfterSec = null) {
+    // Only upstream failures impose cooldown; network/schema errors retry on
+    // pan. Several sources can fail together: wait for the longest of them.
+    const failures = [errors].flat().filter(wildlifeFailureRetryable);
+    const snapshotDelay =
+      Number.isFinite(retryAfterSec) && retryAfterSec >= 0
+        ? retryAfterSec * 1000
+        : null;
+    if (!failures.length && snapshotDelay === null) {
       state.failures = 0;
       state.retryAt = 0;
       return;
     }
-    const backoff = retryDelays.length
-      ? Math.max(...retryDelays) * 1000
-      : retryDelayMs(state.failures || 0);
+    const delays = failures.map((error) =>
+      Number.isFinite(error.retryAfterSec) && error.retryAfterSec >= 0
+        ? error.retryAfterSec * 1000
+        : retryDelayMs(state.failures || 0),
+    );
+    if (snapshotDelay !== null) delays.push(snapshotDelay);
+    const backoff = Math.max(...delays);
     state.failures = backoff;
     state.retryAt = services.now() + backoff;
   }
@@ -404,16 +408,39 @@ export function createLifecycle({ state, services, parts }) {
             },
           )
         : null;
-      const sourceError =
-        gridError ||
-        staleError ||
-        (snapshot.sources?.inaturalist?.ok === false
-          ? snapshot.sources.inaturalist.error ||
+      const inat = snapshot.sources?.inaturalist;
+      const acartia = snapshot.sources?.acartia;
+      // Keep each failed source's status and Retry-After; the displayed error
+      // is the one that explains the cooldown.
+      const sourceErrors = [
+        gridError,
+        staleError,
+        inat?.ok === false
+          ? inat.error ||
             new Error(msg('Wildlife sightings source unavailable'))
-          : null) ||
-        (snapshot.sources?.acartia?.ok === false
-          ? new Error(msg('Acartia feed unavailable'))
-          : null);
+          : null,
+        acartia?.ok === false
+          ? Object.assign(new Error(msg('Acartia feed unavailable')), {
+              ...(acartia.error?.status
+                ? { status: acartia.error.status }
+                : {}),
+              ...(acartia.error?.upstreamStatus
+                ? { upstreamStatus: acartia.error.upstreamStatus }
+                : {}),
+              ...(Number.isFinite(acartia.error?.retryAfterSec)
+                ? { retryAfterSec: acartia.error.retryAfterSec }
+                : {}),
+            })
+          : null,
+      ].filter(Boolean);
+      const sourceError =
+        sourceErrors.find(
+          (error) =>
+            wildlifeFailureRetryable(error) ||
+            Number.isFinite(error.retryAfterSec),
+        ) ||
+        sourceErrors[0] ||
+        null;
       state.stale =
         !sourceError && (snapshot.stale === true || grid?.stale === true);
       const fetchedAt = [snapshot.fetchedAt, grid?.fetchedAt].filter(
@@ -438,7 +465,7 @@ export function createLifecycle({ state, services, parts }) {
       if (sourceError) {
         failParams(params);
         applyRetry(
-          sourceError,
+          sourceErrors,
           retryAfter.length ? Math.max(...retryAfter) : null,
         );
       } else {
diff --git a/src/layers/wildlifeSightings/source.js b/src/layers/wildlifeSightings/source.js
index 8bd41bf1d..aa218f34e 100644
--- a/src/layers/wildlifeSightings/source.js
+++ b/src/layers/wildlifeSightings/source.js
@@ -102,6 +102,36 @@ function validProjectedRows(rows, origin) {
   );
 }
 
+/** Return the status a failure reports. The proxy marks upstream failures
+ * with X-Upstream-Status; without it the HTTP status is the signal. */
+function wildlifeFailureStatus(error) {
+  return (
+    error?.upstreamStatus ||
+    error?.status ||
+    Number(/HTTP (\d{3})/.exec(error?.message || '')?.[1]) ||
+    0
+  );
+}
+
+/** Whether a failure asks clients to wait before the next request. */
+export function wildlifeFailureRetryable(error) {
+  const status = wildlifeFailureStatus(error);
+  return status === 429 || status >= 500;
+}
+
+/** Prefer the failure that carries retry timing, then the longest wait. */
+export function preferredWildlifeFailure(errors) {
+  const failures = errors.filter(Boolean);
+  const retryable = failures.filter(wildlifeFailureRetryable);
+  if (!retryable.length) return failures[0] || null;
+  return retryable.reduce((best, error) =>
+    (Number.isFinite(error.retryAfterSec) ? error.retryAfterSec : -1) >
+    (Number.isFinite(best.retryAfterSec) ? best.retryAfterSec : -1)
+      ? error
+      : best,
+  );
+}
+
 /** Merge occupied cells incrementally; neighboring UTFGrid hit tiles can
  * report the same geographic cell, so source ids remain the dedupe key. */
 export function combineWildlifeGridSnapshots(snapshots, error = null) {
@@ -421,7 +451,7 @@ export function createWildlifeSightingsSource({
       ),
     );
     signal?.throwIfAborted();
-    const failure = failures.find(Boolean);
+    const failure = preferredWildlifeFailure(failures);
     if (!snapshots.some(Boolean) && failure) throw failure;
     return combineWildlifeGridSnapshots(snapshots.filter(Boolean), failure);
   }
@@ -494,11 +524,15 @@ export function createWildlifeSightingsSource({
     });
     // Fail outright only when nothing succeeded; otherwise draw what arrived
     // and report the failed source in its per-source status.
+    const acartiaError =
+      useAcartia && acartiaResult.status === 'rejected'
+        ? acartiaResult.reason
+        : null;
     if (
       !inatSnapshots.length &&
       (!useAcartia || acartiaResult.status !== 'fulfilled')
     )
-      throw inatError;
+      throw preferredWildlifeFailure([inatError, acartiaError]);
     const inatRows = inatSnapshots.flatMap((snapshot) => snapshot.rows);
     const acartiaSnapshot =
       acartiaResult.status === 'fulfilled' ? acartiaResult.value : null;
@@ -553,12 +587,13 @@ export function createWildlifeSightingsSource({
           ...(inatError ? { error: inatError, failedBoxes } : {}),
         },
         acartia: {
-          ok: !useAcartia || acartiaResult.status === 'fulfilled',
+          ok: !acartiaError,
           stale: acartiaStale,
           fetchedAt: Number.isFinite(acartiaSnapshot?.fetchedAt)
             ? acartiaSnapshot.fetchedAt
             : null,
           count: drawnAcartia,
+          ...(acartiaError ? { error: acartiaError } : {}),
         },
       },
     };

From 3438a88cc7780058fb971ec3b087addcdbdc404e Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:31:46 -0800
Subject: [PATCH 63/71] Ease a late zoomed tilt to its new limit instead of
 jumping there
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From 400 km, a tilt to -5° that a zoom out x2.5 caught at -8.0005° reported -8°, and the next frame jumped to -9.407° and ended there. The zoom kept the camera's pitch as the goal when it was already past the new range's horizon limit, but at the same pivot pitch the longer range looks down more steeply, so the next lookAt dropped the camera 1.4° at once.

The zoom now re-solves the pivot pitch so the new range keeps the camera's pitch, and aims the tilt at the asked angle or the new limit, even when that limit is below where the camera stands: the tilt eases down to it. The zoom's reply names that end, and the camera reaches it with no frame moving more than 0.1°.
---
 docs/CURRENT-STATE.md   |  2 +-
 src/cameraTilt.test.mjs | 29 ++++++++++++++++++++++
 src/cameraVerbs.js      | 54 ++++++++++++++++++++++++++++++++---------
 3 files changed, 72 insertions(+), 13 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index d41c435f1..d5ef4af05 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5590,7 +5590,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. A zoom during a tilt to an angle re-judges the place's horizon limit at the new range: when that moves where the tilt ends, the tilt eases from where it is to the new end, and the zoom's result names that angle (`pitchDeg`) with a `note`. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. A motion that runs after a fly-to of the same reply has already found nothing (Gemini runs one turn's calls one by one, and passes its turn as the reply) is refused the same way rather than moving the old view; a motion in a later reply runs. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. A zoom during a tilt to an angle re-judges the place's horizon limit at the new range: when that moves where the tilt ends, the tilt eases from where it is to the new end (holding the camera's pitch through the range change, and easing back down to a limit it is already past rather than jumping there), and the zoom's result names that angle (`pitchDeg`) with a `note`. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. A motion that runs after a fly-to of the same reply has already found nothing (Gemini runs one turn's calls one by one, and passes its turn as the reply) is refused the same way rather than moving the old view; a motion in a later reply runs. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index 0dcb2d1b0..738c71e88 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -686,3 +686,32 @@ test('a voice zoom during a tilt to an angle passes on the new end angle', async
   );
   assert.match(zoom.note, /horizon/);
 });
+
+// Late in the tilt the camera is already past the angle the new range's
+// horizon allows (from 400 km at -8°, a zoom out x2.5 reported -8° and the
+// next frame jumped to -9.4°): it eases to that limit with no jump, and the
+// zoom's reply names the angle it ends at, not the one it stood at.
+test('a late zoom out during a tilt eases to the new limit and reports it', (t) => {
+  const h = harness(t, { height: 400_000 });
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  for (let i = 0; i < 70; i += 1) h.tick();
+  const zoom = adjustOrbitRange(2.5);
+  assert.equal(zoom.changed, true);
+  let last = pitchDeg(h.camera);
+  let maxStep = 0;
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    maxStep = Math.max(maxStep, Math.abs(pitchDeg(h.camera) - last));
+    last = pitchDeg(h.camera);
+  }
+  assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  assert.ok(maxStep < 0.5, `pitch jumped ${maxStep}° in one frame`);
+  assert.ok(h.viewTarget(), 'the crosshair is on the sky');
+  // Replies give whole degrees: the reported angle is the reached one rounded.
+  assert.equal(
+    zoom.pitchDeg,
+    Math.round(pitchDeg(h.camera)),
+    `camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
+  );
+  assert.match(zoom.note, /horizon/);
+});
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 0681d6a2b..437688d7a 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -1378,12 +1378,22 @@ function tiltClearanceBinds(range) {
  */
 function tiltUpLimit({ target, pivot }) {
   if (!pivot || tiltClearanceBinds(pivot.range)) return PITCH_MAX;
-  const pitch = Math.max(pivot.pitch, tiltPivotPitchMax(pivot.range));
-  // The camera's position for that pivot pitch, as lookAt places it.
+  return Math.min(
+    PITCH_MAX,
+    pivotCameraPitch(
+      target,
+      pivot,
+      Math.max(pivot.pitch, tiltPivotPitchMax(pivot.range)),
+    ),
+  );
+}
+
+/** The camera pitch lookAt gives for this pivot at the given pivot pitch. */
+function pivotCameraPitch(target, { heading, range }, pitch) {
   const offset = new Cesium.Cartesian3(
-    -pivot.range * Math.cos(pitch) * Math.sin(pivot.heading),
-    -pivot.range * Math.cos(pitch) * Math.cos(pivot.heading),
-    -pivot.range * Math.sin(pitch),
+    -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),
@@ -1394,9 +1404,8 @@ function tiltUpLimit({ target, pivot }) {
   Cesium.Cartesian3.normalize(look, look);
   const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84;
   const upAtEye = ellipsoid.geodeticSurfaceNormal(eye, new Cesium.Cartesian3());
-  return Math.min(
-    PITCH_MAX,
-    Math.asin(Cesium.Math.clamp(Cesium.Cartesian3.dot(look, upAtEye), -1, 1)),
+  return Math.asin(
+    Cesium.Math.clamp(Cesium.Cartesian3.dot(look, upAtEye), -1, 1),
   );
 }
 
@@ -2092,16 +2101,37 @@ export function adjustOrbitRange(factor) {
 /**
  * A zoom changed the range a tilt to an angle holds, and with it the place's
  * horizon limit: aim the tilt at the angle asked for or the new limit,
- * whichever comes first, from where the camera is now. Returns the end angle
- * and a note for the reply when that end moved, otherwise nothing.
+ * whichever comes first, from where the camera is now. The pivot pitch is
+ * re-solved so the new range keeps the camera's pitch, and a limit the camera
+ * is already past is eased down to rather than jumped to. Returns the end
+ * angle and a note for the reply when that end moved, otherwise nothing.
  */
 function retargetTiltAfterZoom(m) {
   if (m.kind !== 'tilt' || m.mode !== 'once' || m.askedPitch === undefined)
     return {};
   const from = _viewer.camera.pitch;
   if (!(m.askedPitch > from)) return {};
-  const limit = tiltUpLimit({ target: m.target, pivot: m.hpr });
-  const goal = Math.min(m.askedPitch, Math.max(from, limit));
+  if (m.hpr) {
+    // At the same pivot pitch a longer range looks down more steeply (the
+    // Earth curves away): find the pivot pitch that holds this camera pitch.
+    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;
+      m.hpr.pitch = Cesium.Math.clamp(
+        m.hpr.pitch + error,
+        -Cesium.Math.PI_OVER_TWO,
+        0,
+      );
+    }
+  }
+  const limit =
+    m.hpr && !tiltClearanceBinds(m.hpr.range)
+      ? Math.min(
+          PITCH_MAX,
+          pivotCameraPitch(m.target, m.hpr, tiltPivotPitchMax(m.hpr.range)),
+        )
+      : PITCH_MAX;
+  const goal = Math.min(m.askedPitch, limit);
   if (Math.abs(goal - m.goalPitch) < 1e-6) return {};
   m.goalPitch = goal;
   m.startPitch = from;

From dac9b5627d629655304f11eddd5e45f861f512b9 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:42:45 -0800
Subject: [PATCH 64/71] fix(wildlife): wait for the longest effective delay
 among every failed request

One error was chosen before each failure's delay was known. An antimeridian
box 400 hid the other box's 503 Retry-After; a grid tile 400 with Retry-After
set a cooldown through the snapshot metadata; a short Retry-After on one tile
undercut a sibling 5xx's default backoff; and a huge Retry-After made the
deadline Infinity.

Every failed request now keeps its status and Retry-After. One function gives
each failure's delay: 4xx other than 429 none, 429 and 5xx their Retry-After
or the default backoff. The layer waits for the longest, and shows the
failure that set it. Retry-After is capped at one day, the proxy's own
daily-budget deadline, and non-finite values are ignored. Each publish of
one acquisition derives the default backoff from the backoff before it
started, so repeated tile publishes no longer double it.
---
 .../wildlifeSightings/acquisition.test.mjs    | 95 +++++++++++++++++++
 src/layers/wildlifeSightings/lifecycle.js     | 74 ++++++++-------
 src/layers/wildlifeSightings/policy.js        |  3 +
 src/layers/wildlifeSightings/source.js        | 89 +++++++++++++----
 4 files changed, 209 insertions(+), 52 deletions(-)

diff --git a/src/layers/wildlifeSightings/acquisition.test.mjs b/src/layers/wildlifeSightings/acquisition.test.mjs
index d343ad9b0..b4ac47813 100644
--- a/src/layers/wildlifeSightings/acquisition.test.mjs
+++ b/src/layers/wildlifeSightings/acquisition.test.mjs
@@ -1072,3 +1072,98 @@ for (const [name, respond] of [
     assert.equal(h.state.renderedRows.length, 2);
   });
 }
+
+// Every failed request keeps its own timing. The layer waits for the longest
+// effective delay: 4xx other than 429 never waits, 429/5xx wait for their
+// Retry-After or the default backoff. The shown error explains that wait.
+async function settleThroughSource(fetchImpl, bounds = salishSea) {
+  const h = harness(
+    createWildlifeSightingsSource({ now: () => NOW, fetchImpl }),
+  );
+  h.bounds(bounds);
+  h.state.enabled = false;
+  h.layer.enable();
+  const first = h.layer.update();
+  await h.advance(300);
+  await first;
+  await new Promise((resolve) => setImmediate(resolve));
+  await new Promise((resolve) => setImmediate(resolve));
+  return h;
+}
+const tileX = (url) =>
+  Number(new URL(url, 'https://example.test').searchParams.get('x'));
+const observations = () =>
+  Response.json({ rows: [inatRow], totalResults: 1, fetchedAt: NOW });
+
+test('an antimeridian box 400 never hides the other box 503 Retry-After', async () => {
+  for (const westFails of [true, false]) {
+    const h = await settleThroughSource(
+      async (url) => {
+        if (url.startsWith('/api/inaturalist/grid?')) return emptyGrid();
+        const west =
+          Number(
+            new URL(url, 'https://example.test').searchParams.get('west'),
+          ) > 0;
+        return west === westFails
+          ? new Response('', { status: 400 })
+          : unavailable();
+      },
+      { south: 10, west: 179, north: 12, east: -179 },
+    );
+    assert.equal(h.state.error, 'iNaturalist HTTP 503');
+    assert.equal(h.state.retryAt, NOW + 300 + 120_000);
+    assert.equal(h.layer.getStats().retryInSec, 120);
+  }
+});
+
+test('a grid tile 400 with Retry-After beside successful tiles creates no cooldown', async () => {
+  let tiles = new Set();
+  const h = await settleThroughSource(async (url) => {
+    if (!url.startsWith('/api/inaturalist/grid?')) return observations();
+    tiles.add(tileX(url));
+    return tileX(url) === Math.min(...tiles) && tiles.size === 1
+      ? new Response('', { status: 400, headers: { 'Retry-After': '120' } })
+      : emptyGrid();
+  });
+  assert.ok(tiles.size > 1, 'the view spans several grid tiles');
+  assert.equal(h.state.error, 'iNaturalist HTTP 400');
+  assert.equal(h.state.retryAt, 0);
+  assert.equal(h.layer.getStats().retryInSec, undefined);
+});
+
+test('a short grid Retry-After never undercuts a sibling 5xx default backoff', async () => {
+  let failed = 0;
+  const h = await settleThroughSource(async (url) => {
+    if (!url.startsWith('/api/inaturalist/grid?')) return observations();
+    failed++;
+    if (failed === 1)
+      return new Response('', { status: 503, headers: { 'Retry-After': '2' } });
+    if (failed === 2) return new Response('', { status: 502 });
+    return emptyGrid();
+  });
+  assert.ok(failed >= 2);
+  assert.equal(h.state.error, 'iNaturalist HTTP 502');
+  assert.equal(h.state.retryAt, NOW + 300 + 30_000);
+  assert.equal(h.layer.getStats().retryInSec, 30);
+});
+
+test('an enormous Retry-After is capped at one day and a non-finite one uses the default backoff', async () => {
+  for (const [header, delay] of [
+    ['1' + '0'.repeat(306), 86_400_000],
+    ['1' + '0'.repeat(400), 30_000],
+  ]) {
+    const h = await settleThroughSource(async (url) =>
+      url.startsWith('/api/inaturalist/grid?')
+        ? emptyGrid()
+        : url.startsWith('/api/acartia')
+          ? Response.json({ rows: [], fetchedAt: NOW })
+          : new Response('', {
+              status: 503,
+              headers: { 'Retry-After': header },
+            }),
+    );
+    assert.equal(h.state.error, 'iNaturalist HTTP 503');
+    assert.ok(Number.isFinite(h.state.retryAt));
+    assert.equal(h.state.retryAt, NOW + 300 + delay, header.length);
+  }
+});
diff --git a/src/layers/wildlifeSightings/lifecycle.js b/src/layers/wildlifeSightings/lifecycle.js
index 3b2a2999a..0fe430fbe 100644
--- a/src/layers/wildlifeSightings/lifecycle.js
+++ b/src/layers/wildlifeSightings/lifecycle.js
@@ -2,7 +2,10 @@ import { msg } from '../../i18n/marker.js';
 import { getWildlifeHeightBand, rowInWildlifeBoxes } from './model.js';
 import {
   combineWildlifeGridSnapshots,
-  wildlifeFailureRetryable,
+  preferredWildlifeFailure,
+  wildlifeFailureDelayMs,
+  wildlifeFailures,
+  wildlifeRetryAfterMs,
 } from './source.js';
 import { wildlifeMeasure } from './performance.js';
 import { isRecentWildlifeSighting } from './records.js';
@@ -12,11 +15,7 @@ import {
   wildlifeGridTiles,
   wildlifeGridCellId,
 } from './gridViewport.js';
-import {
-  wildlifeViewportBoxes,
-  snapWildlifeBox,
-  retryDelayMs,
-} from './viewport.js';
+import { wildlifeViewportBoxes, snapWildlifeBox } from './viewport.js';
 import {
   WILDLIFE_DEBOUNCE_MS,
   WILDLIFE_MAX_ROWS,
@@ -95,25 +94,25 @@ export function createLifecycle({ state, services, parts }) {
     state.pendingParams = null;
   }
 
-  function applyRetry(errors, retryAfterSec = null) {
-    // Only upstream failures impose cooldown; network/schema errors retry on
-    // pan. Several sources can fail together: wait for the longest of them.
-    const failures = [errors].flat().filter(wildlifeFailureRetryable);
-    const snapshotDelay =
-      Number.isFinite(retryAfterSec) && retryAfterSec >= 0
-        ? retryAfterSec * 1000
-        : null;
-    if (!failures.length && snapshotDelay === null) {
+  function applyRetry(
+    errors,
+    retryAfterSec = null,
+    previousMs = state.failures || 0,
+  ) {
+    // Only 429/5xx failures impose cooldown; client, network and schema
+    // errors retry on pan. Several requests can fail together: wait for the
+    // longest effective delay among them.
+    const delays = [
+      ...wildlifeFailures(errors).map((error) =>
+        wildlifeFailureDelayMs(error, previousMs),
+      ),
+      wildlifeRetryAfterMs(retryAfterSec),
+    ].filter((delay) => delay !== null);
+    if (!delays.length) {
       state.failures = 0;
       state.retryAt = 0;
       return;
     }
-    const delays = failures.map((error) =>
-      Number.isFinite(error.retryAfterSec) && error.retryAfterSec >= 0
-        ? error.retryAfterSec * 1000
-        : retryDelayMs(state.failures || 0),
-    );
-    if (snapshotDelay !== null) delays.push(snapshotDelay);
     const backoff = Math.max(...delays);
     state.failures = backoff;
     state.retryAt = services.now() + backoff;
@@ -282,6 +281,7 @@ export function createLifecycle({ state, services, parts }) {
     request,
     signal,
     epoch,
+    previousFailures,
     replaceRows = true,
   }) {
     const current = currentQuery();
@@ -398,10 +398,14 @@ export function createLifecycle({ state, services, parts }) {
             value.upstreamStatus === 429 ||
             value.upstreamStatus >= 500),
       );
+      // The filter above admits only 429/5xx or an unmarked stale answer.
       const staleError = failedStale.length
         ? Object.assign(
             new Error(msg('Wildlife sightings source unavailable')),
             {
+              upstreamStatus: Math.max(
+                ...failedStale.map((value) => value.upstreamStatus || 503),
+              ),
               retryAfterSec: Math.max(
                 ...failedStale.map((value) => value.retryAfterSec),
               ),
@@ -410,8 +414,8 @@ export function createLifecycle({ state, services, parts }) {
         : null;
       const inat = snapshot.sources?.inaturalist;
       const acartia = snapshot.sources?.acartia;
-      // Keep each failed source's status and Retry-After; the displayed error
-      // is the one that explains the cooldown.
+      // Keep each failed request's status and Retry-After; the displayed
+      // error is the one whose effective delay sets the cooldown.
       const sourceErrors = [
         gridError,
         staleError,
@@ -433,14 +437,10 @@ export function createLifecycle({ state, services, parts }) {
             })
           : null,
       ].filter(Boolean);
-      const sourceError =
-        sourceErrors.find(
-          (error) =>
-            wildlifeFailureRetryable(error) ||
-            Number.isFinite(error.retryAfterSec),
-        ) ||
-        sourceErrors[0] ||
-        null;
+      const sourceError = preferredWildlifeFailure(
+        sourceErrors,
+        previousFailures,
+      );
       state.stale =
         !sourceError && (snapshot.stale === true || grid?.stale === true);
       const fetchedAt = [snapshot.fetchedAt, grid?.fetchedAt].filter(
@@ -467,12 +467,13 @@ export function createLifecycle({ state, services, parts }) {
         applyRetry(
           sourceErrors,
           retryAfter.length ? Math.max(...retryAfter) : null,
+          previousFailures,
         );
       } else {
         state.pendingParams = null;
         state.failedParams = null;
         state.retryAt = retryAfter.length
-          ? services.now() + Math.max(...retryAfter) * 1000
+          ? services.now() + wildlifeRetryAfterMs(Math.max(...retryAfter))
           : 0;
         state.failures = 0;
       }
@@ -632,6 +633,9 @@ export function createLifecycle({ state, services, parts }) {
       state.request?.abort();
       const request = new AbortController();
       const requestLifetime = lifetimeEpoch;
+      // One acquisition publishes several times (tiles, rows, final grid).
+      // Each derives its default backoff from the backoff before it started.
+      const previousFailures = state.failures || 0;
       const supersededResult = () =>
         state.enabled &&
         !state.destroyed &&
@@ -699,6 +703,7 @@ export function createLifecycle({ state, services, parts }) {
           request,
           signal,
           epoch: requestLifetime,
+          previousFailures,
         });
       }
       function finishTiles() {
@@ -804,11 +809,12 @@ export function createLifecycle({ state, services, parts }) {
         continueTiles();
         state.stale = false;
         state.error =
-          error?.message || msg('Wildlife sightings source unavailable');
+          preferredWildlifeFailure(error, previousFailures)?.message ||
+          msg('Wildlife sightings source unavailable');
         failParams(params);
         state.lastQueryKey = null;
         requestQueryKey = null;
-        applyRetry(error);
+        applyRetry(error, null, previousFailures);
         console.warn('[Data:WildlifeSightings] Update failed:', state.error);
         return true;
       } finally {
diff --git a/src/layers/wildlifeSightings/policy.js b/src/layers/wildlifeSightings/policy.js
index 4af9d7d17..f1b6df277 100644
--- a/src/layers/wildlifeSightings/policy.js
+++ b/src/layers/wildlifeSightings/policy.js
@@ -74,6 +74,9 @@ export { WILDLIFE_MAX_VIEW_DEGREES } from './bounds.js';
 export const WILDLIFE_VIEW_PADDING = 0.3;
 export const WILDLIFE_RETRY_MIN_MS = 30_000;
 export const WILDLIFE_RETRY_MAX_MS = 240_000;
+// Cap a Retry-After so one reply can never stall refresh forever. The proxy's
+// daily-budget reply waits until the next UTC midnight, so allow one day.
+export const WILDLIFE_RETRY_AFTER_MAX_SEC = 86_400;
 
 // Faster polling would reread the proxy's five-minute cache.
 export const WILDLIFE_UPDATE_INTERVAL_MS = 5 * 60_000;
diff --git a/src/layers/wildlifeSightings/source.js b/src/layers/wildlifeSightings/source.js
index aa218f34e..e2e3f1b80 100644
--- a/src/layers/wildlifeSightings/source.js
+++ b/src/layers/wildlifeSightings/source.js
@@ -1,8 +1,12 @@
 import { readResponseJsonCapped } from '../../sources/httpBody.js';
 import { mergeSightings } from './records.js';
 import { wildlifeMeasure } from './performance.js';
-import { ACARTIA_GUARD_BOX, TAXA_PRESETS } from './policy.js';
-import { boxIntersects } from './viewport.js';
+import {
+  ACARTIA_GUARD_BOX,
+  TAXA_PRESETS,
+  WILDLIFE_RETRY_AFTER_MAX_SEC,
+} from './policy.js';
+import { boxIntersects, retryDelayMs } from './viewport.js';
 import {
   WILDLIFE_GRID_MAX_ZOOM,
   WILDLIFE_GRID_TILE_CAP,
@@ -72,14 +76,19 @@ function retryAfterSeconds(value, nowMs) {
   const text = value.trim();
   if (/^\d+(?:\.\d+)?$/.test(text)) {
     const seconds = Number(text);
-    return Number.isFinite(seconds) ? Math.ceil(seconds) : null;
+    return Number.isFinite(seconds)
+      ? Math.min(WILDLIFE_RETRY_AFTER_MAX_SEC, Math.ceil(seconds))
+      : null;
   }
   // Reject malformed numeric values rather than letting Date.parse interpret
   // them as calendar dates. HTTP dates include a named weekday or month.
   if (!/[a-z]/i.test(text)) return null;
   const deadline = Date.parse(text);
   return Number.isFinite(deadline) && Number.isFinite(nowMs)
-    ? Math.max(0, Math.ceil((deadline - nowMs) / 1000))
+    ? Math.min(
+        WILDLIFE_RETRY_AFTER_MAX_SEC,
+        Math.max(0, Math.ceil((deadline - nowMs) / 1000)),
+      )
     : null;
 }
 
@@ -119,17 +128,56 @@ export function wildlifeFailureRetryable(error) {
   return status === 429 || status >= 500;
 }
 
-/** Prefer the failure that carries retry timing, then the longest wait. */
-export function preferredWildlifeFailure(errors) {
-  const failures = errors.filter(Boolean);
-  const retryable = failures.filter(wildlifeFailureRetryable);
-  if (!retryable.length) return failures[0] || null;
-  return retryable.reduce((best, error) =>
-    (Number.isFinite(error.retryAfterSec) ? error.retryAfterSec : -1) >
-    (Number.isFinite(best.retryAfterSec) ? best.retryAfterSec : -1)
-      ? error
-      : best,
-  );
+/** Return a Retry-After in milliseconds, capped at one day, or null when
+ * it is missing, negative or not finite. */
+export function wildlifeRetryAfterMs(seconds) {
+  return Number.isFinite(seconds) && seconds >= 0
+    ? Math.min(WILDLIFE_RETRY_AFTER_MAX_SEC, seconds) * 1000
+    : null;
+}
+
+/** Return how long a failure asks the layer to wait, or null for none:
+ * 429 and 5xx wait for their Retry-After, else the default backoff after
+ * `previousMs`; other failures may retry on the next view. */
+export function wildlifeFailureDelayMs(error, previousMs = 0) {
+  if (!error || !wildlifeFailureRetryable(error)) return null;
+  return wildlifeRetryAfterMs(error.retryAfterSec) ?? retryDelayMs(previousMs);
+}
+
+/** Flatten failures, expanding a group into every request that failed. */
+export function wildlifeFailures(errors) {
+  return [errors]
+    .flat()
+    .filter(Boolean)
+    .flatMap((error) =>
+      Array.isArray(error.failures) && error.failures.length
+        ? error.failures
+        : [error],
+    );
+}
+
+/** Return the failure with the longest effective delay (the first failure
+ * when none waits), carrying every failure so the caller can recompute. */
+export function preferredWildlifeFailure(errors, previousMs = 0) {
+  const failures = wildlifeFailures(errors);
+  if (!failures.length) return null;
+  let chosen = failures[0];
+  let longest = wildlifeFailureDelayMs(chosen, previousMs) ?? -1;
+  for (const error of failures.slice(1)) {
+    const delay = wildlifeFailureDelayMs(error, previousMs) ?? -1;
+    if (delay > longest) [chosen, longest] = [error, delay];
+  }
+  if (failures.length === 1) return chosen;
+  // Grid errors are shared between consumers of one tile request; describe
+  // the group with a new error rather than mutating any of them.
+  return Object.assign(new Error(chosen.message, { cause: chosen }), {
+    ...(chosen.status ? { status: chosen.status } : {}),
+    ...(chosen.upstreamStatus ? { upstreamStatus: chosen.upstreamStatus } : {}),
+    ...(Number.isFinite(chosen.retryAfterSec)
+      ? { retryAfterSec: chosen.retryAfterSec }
+      : {}),
+    failures,
+  });
 }
 
 /** Merge occupied cells incrementally; neighboring UTFGrid hit tiles can
@@ -145,9 +193,12 @@ export function combineWildlifeGridSnapshots(snapshots, error = null) {
   const totalResults = cells.reduce((sum, cell) => sum + cell.cellCount, 0);
   if (!Number.isSafeInteger(totalResults))
     throw new Error('Malformed iNaturalist grid response');
+  // A failure's Retry-After counts only when its status asks for a wait.
   const retryAfter = [
     ...snapshots.map((snapshot) => snapshot.retryAfterSec),
-    error?.retryAfterSec,
+    ...wildlifeFailures(error)
+      .filter(wildlifeFailureRetryable)
+      .map((failure) => failure.retryAfterSec),
   ].filter(Number.isFinite);
   const stale = snapshots.some((snapshot) => snapshot.stale === true);
   return {
@@ -514,14 +565,16 @@ export function createWildlifeSightingsSource({
     signal?.throwIfAborted();
     const inatSnapshots = [];
     const failedBoxes = [];
-    let inatError = null;
+    const inatErrors = [];
     inatResult.value.forEach((result, index) => {
       if (result.status === 'fulfilled') inatSnapshots.push(result.value);
       else {
         failedBoxes.push(requestBoxes[index]);
-        inatError ??= result.reason;
+        inatErrors.push(result.reason);
       }
     });
+    // Keep every failed box; the layer waits for the longest of them.
+    const inatError = preferredWildlifeFailure(inatErrors);
     // Fail outright only when nothing succeeded; otherwise draw what arrived
     // and report the failed source in its per-source status.
     const acartiaError =

From 6d7fe53570465f0fabf19a678ae1ba3795cdf23b Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:55:54 -0800
Subject: [PATCH 65/71] Let a shell without its navigation owner report no
 camera handoffs

The voice runner subscribes to camera handoffs as it is created. The Cyber sonar test builds its runner on a StyleManager made from the prototype, which has no navigation owner, so the facade's delegation threw and both Node jobs failed. The facade now returns nothing there, like its other optional owners; the real shell builds its navigation owner before voice creates a runner.
---
 scripts/format-scope.json   |  1 +
 src/ui/shellFacade.js       |  2 +-
 src/ui/shellFacade.test.mjs | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 src/ui/shellFacade.test.mjs

diff --git a/scripts/format-scope.json b/scripts/format-scope.json
index a28a8c53c..40bca019a 100644
--- a/scripts/format-scope.json
+++ b/scripts/format-scope.json
@@ -1128,6 +1128,7 @@
   "src/dockerTrustedPeers.test.mjs",
   "src/cameraGlobeRotation.test.mjs",
   "src/cameraTilt.test.mjs",
+  "src/ui/shellFacade.test.mjs",
   "src/voice/globeResetConfirmation.test.mjs",
   "src/hudDms.test.mjs",
   "src/hudSummaryGate.test.mjs",
diff --git a/src/ui/shellFacade.js b/src/ui/shellFacade.js
index 95bf791d4..678b69c79 100644
--- a/src/ui/shellFacade.js
+++ b/src/ui/shellFacade.js
@@ -6,7 +6,7 @@
 export class ShellFacade {
   /** Observe camera ownership transfers through the navigation owner. */
   subscribeCameraHandoff(listener) {
-    return this._navigation.subscribeCameraHandoff(listener);
+    return this._navigation?.subscribeCameraHandoff(listener);
   }
 
   get _models3dEnabled() {
diff --git a/src/ui/shellFacade.test.mjs b/src/ui/shellFacade.test.mjs
new file mode 100644
index 000000000..abb892b37
--- /dev/null
+++ b/src/ui/shellFacade.test.mjs
@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { ShellFacade } from './shellFacade.js';
+
+// A shell assembled without its navigation owner (as unit tests build one
+// from the prototype) has no handoffs to report, like the facade's other
+// optional owners; the voice runner subscribes as it is created.
+test('camera handoffs without a navigation owner subscribe to nothing', () => {
+  const shell = Object.create(ShellFacade.prototype);
+  assert.equal(
+    shell.subscribeCameraHandoff(() => {}),
+    undefined,
+  );
+});
+
+test('camera handoffs reach listeners through the navigation owner', () => {
+  const listeners = new Set();
+  const shell = Object.create(ShellFacade.prototype);
+  shell._navigation = {
+    subscribeCameraHandoff(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+  let handoffs = 0;
+  const unsubscribe = shell.subscribeCameraHandoff(() => {
+    handoffs += 1;
+  });
+  for (const listener of listeners) listener();
+  assert.equal(handoffs, 1);
+  unsubscribe();
+  assert.equal(listeners.size, 0);
+});

From 495139399719ad56fe38606931987331387ffdf9 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 16:55:54 -0800
Subject: [PATCH 66/71] Keep the place in view when a late zoom out catches a
 tilt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From 400 km, a tilt to -5° that a zoom out x2.5 caught 70 frames in eased down from the camera's old pitch at the new range. That put the camera below the place's horizon: the first frame's crosshair hit the ground 186 km from London, and London stayed hidden for about 11 frames. The re-solve also left the pivot pitch at 0°, so a zoom in before the next frame computed an infinite clearance floor, was refused, and stayed at 1,000 km.

The re-solved pivot pitch now stops at the place's horizon limit, or where the pivot already was. A camera that the zoom leaves past that limit steps down to it with the zoom and holds it, and the zoom still reports that angle. A zoom in straight after brings the range back to 400 km.
---
 docs/CURRENT-STATE.md   |  2 +-
 src/cameraTilt.test.mjs | 66 +++++++++++++++++++++++++++++++++++++----
 src/cameraVerbs.js      | 13 ++++++--
 3 files changed, 72 insertions(+), 9 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index d5ef4af05..390c61c4a 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -5590,7 +5590,7 @@ and unreachable upstream (502/504) separately from road geometry.
 > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
 > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
 
-- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. A zoom during a tilt to an angle re-judges the place's horizon limit at the new range: when that moves where the tilt ends, the tilt eases from where it is to the new end (holding the camera's pitch through the range change, and easing back down to a limit it is already past rather than jumping there), and the zoom's result names that angle (`pitchDeg`) with a `note`. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. A motion that runs after a fly-to of the same reply has already found nothing (Gemini runs one turn's calls one by one, and passes its turn as the reply) is refused the same way rather than moving the old view; a motion in a later reply runs. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
+- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. A zoom during a tilt to an angle re-judges the place's horizon limit at the new range: when that moves where the tilt ends, the tilt eases from where it is to the new end (holding the camera's pitch through the range change; a camera the zoom leaves past the new range's limit steps down to it with the zoom, since past it the place would drop behind the Earth), and the zoom's result names that angle (`pitchDeg`) with a `note`. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. A motion that runs after a fly-to of the same reply has already found nothing (Gemini runs one turn's calls one by one, and passes its turn as the reply) is refused the same way rather than moving the old view; a motion in a later reply runs. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee.
   - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
   - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
   - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
diff --git a/src/cameraTilt.test.mjs b/src/cameraTilt.test.mjs
index 738c71e88..8a3d1447f 100644
--- a/src/cameraTilt.test.mjs
+++ b/src/cameraTilt.test.mjs
@@ -688,15 +688,18 @@ test('a voice zoom during a tilt to an angle passes on the new end angle', async
 });
 
 // Late in the tilt the camera is already past the angle the new range's
-// horizon allows (from 400 km at -8°, a zoom out x2.5 reported -8° and the
-// next frame jumped to -9.4°): it eases to that limit with no jump, and the
-// zoom's reply names the angle it ends at, not the one it stood at.
-test('a late zoom out during a tilt eases to the new limit and reports it', (t) => {
+// horizon allows (from 400 km at -8°, a zoom out x2.5 reported -8°): past it
+// the place is behind the Earth, so the camera steps down to that limit with
+// the zoom, then holds it with no further jump, and the zoom's reply names
+// the angle it ends at, not the one it stood at.
+test('a late zoom out during a tilt steps to the new limit and reports it', (t) => {
   const h = harness(t, { height: 400_000 });
   moveCamera({ motion: 'tilt', pitchDeg: -5 });
   for (let i = 0; i < 70; i += 1) h.tick();
   const zoom = adjustOrbitRange(2.5);
   assert.equal(zoom.changed, true);
+  h.tick();
+  assert.equal(zoom.pitchDeg, Math.round(pitchDeg(h.camera)));
   let last = pitchDeg(h.camera);
   let maxStep = 0;
   for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
@@ -705,7 +708,7 @@ test('a late zoom out during a tilt eases to the new limit and reports it', (t)
     last = pitchDeg(h.camera);
   }
   assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
-  assert.ok(maxStep < 0.5, `pitch jumped ${maxStep}° in one frame`);
+  assert.ok(maxStep < 0.1, `pitch jumped ${maxStep}° in one frame`);
   assert.ok(h.viewTarget(), 'the crosshair is on the sky');
   // Replies give whole degrees: the reported angle is the reached one rounded.
   assert.equal(
@@ -715,3 +718,56 @@ test('a late zoom out during a tilt eases to the new limit and reports it', (t)
   );
   assert.match(zoom.note, /horizon/);
 });
+
+// Easing from the camera's old pitch at the zoomed-out range put the camera
+// below the place's horizon: the first frame's crosshair hit the ground
+// 186 km from London, and London stayed hidden for ~11 frames.
+test('a late zoom out during a tilt keeps the place under the crosshair', (t) => {
+  const h = harness(t, { height: 400_000 });
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  for (let i = 0; i < 70; i += 1) h.tick();
+  const zoom = adjustOrbitRange(2.5);
+  assert.equal(zoom.changed, true);
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    const hit = h.viewTarget();
+    assert.ok(hit, `frame ${i}: the crosshair is on the sky`);
+    const drift = centreDrift(h);
+    assert.ok(
+      drift < 100,
+      `frame ${i}: crosshair ${Math.round(drift)} m off the place`,
+    );
+  }
+  assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  assert.ok(
+    Math.abs(pivotRange(h) - 1_000_000) < 1,
+    `range ${pivotRange(h)} m`,
+  );
+  assert.equal(
+    zoom.pitchDeg,
+    Math.round(pitchDeg(h.camera)),
+    `camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
+  );
+  assert.match(zoom.note, /horizon/);
+});
+
+// The zoom out left the pivot pitch level with the place, so the zoom in's
+// clearance floor came out infinite and it was refused at 1,000 km.
+test('a zoom in right after a late zoom out brings the tilt back in', (t) => {
+  const h = harness(t, { height: 400_000 });
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  for (let i = 0; i < 70; i += 1) h.tick();
+  const range = pivotRange(h);
+  assert.equal(adjustOrbitRange(2.5).changed, true);
+  const zoomIn = adjustOrbitRange(0.4);
+  assert.equal(zoomIn.changed, true, 'the zoom in must not be refused');
+  h.finish();
+  assert.ok(
+    Math.abs(pivotRange(h) - range) < 1,
+    `range ${pivotRange(h)} m, wanted ${range} m`,
+  );
+  assert.ok(
+    centreDrift(h) < 100,
+    `crosshair ${centreDrift(h)} m off the place`,
+  );
+});
diff --git a/src/cameraVerbs.js b/src/cameraVerbs.js
index 437688d7a..d7127c2f7 100644
--- a/src/cameraVerbs.js
+++ b/src/cameraVerbs.js
@@ -2109,20 +2109,27 @@ export function adjustOrbitRange(factor) {
 function retargetTiltAfterZoom(m) {
   if (m.kind !== 'tilt' || m.mode !== 'once' || m.askedPitch === undefined)
     return {};
-  const from = _viewer.camera.pitch;
+  let from = _viewer.camera.pitch;
   if (!(m.askedPitch > from)) return {};
   if (m.hpr) {
     // At the same pivot pitch a longer range looks down more steeply (the
     // Earth curves away): find the pivot pitch that holds this camera pitch.
+    // It stays below the place's horizon limit (or where the pivot already
+    // was): past it the place drops behind the Earth, so a camera the zoom
+    // leaves past that limit steps down to it with the zoom.
+    const cap = Math.max(m.hpr.pitch, tiltPivotPitchMax(m.hpr.range));
     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;
-      m.hpr.pitch = Cesium.Math.clamp(
+      const pitch = Cesium.Math.clamp(
         m.hpr.pitch + error,
         -Cesium.Math.PI_OVER_TWO,
-        0,
+        cap,
       );
+      if (pitch === m.hpr.pitch) break;
+      m.hpr.pitch = pitch;
     }
+    from = Math.min(from, pivotCameraPitch(m.target, m.hpr, m.hpr.pitch));
   }
   const limit =
     m.hpr && !tiltClearanceBinds(m.hpr.range)

From 58adbb11c7f3cfa33cefe85cc17952f4c923fef5 Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Thu, 5 Nov 2026 21:21:26 -0800
Subject: [PATCH 67/71] fix(traffic): name an account's traffic limit instead
 of a daily budget

A failed flow tile now carries the server's reason. A hosted deployment that limits each account answers USAGE_LIMIT_REACHED or RATE_LIMITED, which the traffic panel labels as the monthly allowance or a rate limit; a 503 with another reason reads as the traffic service being unavailable, not a missing key. The local proxy's no_key and daily budget labels are unchanged.
---
 src/data/traffic.test.mjs          | 22 +++++++++++++++++++++
 src/i18n/locales/ar.json           |  3 +++
 src/i18n/locales/de.json           |  3 +++
 src/i18n/locales/es.json           |  3 +++
 src/i18n/locales/fr.json           |  3 +++
 src/i18n/locales/it.json           |  3 +++
 src/i18n/locales/ja.json           |  3 +++
 src/i18n/locales/pt.json           |  3 +++
 src/i18n/locales/ru.json           |  3 +++
 src/i18n/locales/uk.json           |  3 +++
 src/i18n/locales/zh-CN.json        |  3 +++
 src/i18n/locales/zh-Hant.json      |  3 +++
 src/layers/traffic/flow.js         |  8 ++++++++
 src/layers/traffic/flowSource.js   | 31 +++++++++++++++++++++++++++++-
 src/layers/traffic/source.test.mjs | 26 +++++++++++++++++++++++++
 15 files changed, 119 insertions(+), 1 deletion(-)

diff --git a/src/data/traffic.test.mjs b/src/data/traffic.test.mjs
index 23924448a..0e8ada30a 100644
--- a/src/data/traffic.test.mjs
+++ b/src/data/traffic.test.mjs
@@ -30,6 +30,28 @@ test('a superseded flow fetch is not an outage', () => {
   assert.equal(deriveTrafficFlowError(undefined), null);
 });
 
+test('hosted account limits and service failures name their own reason', () => {
+  const failure = (status, code) =>
+    deriveTrafficFlowError(
+      Object.assign(new Error(`TomTom flow unavailable (HTTP ${status})`), {
+        status,
+        code,
+      }),
+    );
+  assert.equal(
+    failure(429, 'USAGE_LIMIT_REACHED'),
+    'Monthly traffic allowance used',
+  );
+  assert.equal(failure(429, 'RATE_LIMITED'), 'Traffic rate limit reached');
+  assert.equal(failure(429, 'budget'), 'TomTom daily budget reached');
+  assert.equal(failure(503, 'no_key'), 'TomTom key unavailable');
+  assert.equal(failure(503, null), 'TomTom key unavailable');
+  assert.equal(
+    failure(503, 'USAGE_UNAVAILABLE'),
+    'Traffic service unavailable',
+  );
+});
+
 test('flow failures map onto short, specific reasons', () => {
   const reason = (message) => deriveTrafficFlowError(new Error(message));
   assert.equal(reason('flow tile 12/1/1: HTTP 503'), 'TomTom key unavailable');
diff --git a/src/i18n/locales/ar.json b/src/i18n/locales/ar.json
index b491c3c93..8a2b81e20 100644
--- a/src/i18n/locales/ar.json
+++ b/src/i18n/locales/ar.json
@@ -1749,6 +1749,9 @@
   "Hybrid": "هجين",
   "TomTom key unavailable": "مفتاح TomTom غير متاح",
   "TomTom daily budget reached": "بلغت الحصة اليومية لـ TomTom",
+  "Monthly traffic allowance used": "تم استهلاك حصة حركة المرور الشهرية",
+  "Traffic rate limit reached": "تم بلوغ حد طلبات حركة المرور",
+  "Traffic service unavailable": "خدمة حركة المرور غير متاحة",
   "TomTom upstream unreachable": "تعذّر الوصول إلى خادم TomTom",
   "TomTom flow unavailable": "تدفق TomTom غير متاح",
   "SIMULATED — {reason}": "محاكى — {reason}",
diff --git a/src/i18n/locales/de.json b/src/i18n/locales/de.json
index d01ff292f..837a87471 100644
--- a/src/i18n/locales/de.json
+++ b/src/i18n/locales/de.json
@@ -1667,6 +1667,9 @@
   "Hybrid": "Hybrid",
   "TomTom key unavailable": "TomTom-Schlüssel nicht verfügbar",
   "TomTom daily budget reached": "TomTom-Tagesbudget erreicht",
+  "Monthly traffic allowance used": "Monatliches Verkehrskontingent aufgebraucht",
+  "Traffic rate limit reached": "Verkehrs-Anfragelimit erreicht",
+  "Traffic service unavailable": "Verkehrsdienst nicht verfügbar",
   "TomTom upstream unreachable": "TomTom-Upstream nicht erreichbar",
   "TomTom flow unavailable": "TomTom-Verkehrsfluss nicht verfügbar",
   "SIMULATED — {reason}": "SIMULIERT – {reason}",
diff --git a/src/i18n/locales/es.json b/src/i18n/locales/es.json
index aa403f743..57aa09eb7 100644
--- a/src/i18n/locales/es.json
+++ b/src/i18n/locales/es.json
@@ -2274,6 +2274,9 @@
   "SIMULATED — {reason}": "SIMULADO — {reason}",
   "TomTom key unavailable": "Clave de TomTom no disponible",
   "TomTom daily budget reached": "Se alcanzó el límite diario de TomTom",
+  "Monthly traffic allowance used": "Cupo mensual de tráfico agotado",
+  "Traffic rate limit reached": "Límite de solicitudes de tráfico alcanzado",
+  "Traffic service unavailable": "Servicio de tráfico no disponible",
   "TomTom upstream unreachable": "Servidor de TomTom inaccesible",
   "TomTom flow unavailable": "Flujo de TomTom no disponible",
   "API key rejected — check AISSTREAM_API_KEY": "Clave de API rechazada — revisa AISSTREAM_API_KEY",
diff --git a/src/i18n/locales/fr.json b/src/i18n/locales/fr.json
index b3ae72189..bfd2a5975 100644
--- a/src/i18n/locales/fr.json
+++ b/src/i18n/locales/fr.json
@@ -1105,6 +1105,9 @@
   "Hybrid": "Hybride",
   "TomTom key unavailable": "Clé TomTom indisponible",
   "TomTom daily budget reached": "Quota quotidien TomTom atteint",
+  "Monthly traffic allowance used": "Quota mensuel de trafic épuisé",
+  "Traffic rate limit reached": "Limite de requêtes de trafic atteinte",
+  "Traffic service unavailable": "Service de trafic indisponible",
   "TomTom upstream unreachable": "Serveur TomTom injoignable",
   "TomTom flow unavailable": "Flux TomTom indisponible",
   "SIMULATED — {reason}": "SIMULÉ — {reason}",
diff --git a/src/i18n/locales/it.json b/src/i18n/locales/it.json
index 4c69e1d4c..74c0d01aa 100644
--- a/src/i18n/locales/it.json
+++ b/src/i18n/locales/it.json
@@ -1105,6 +1105,9 @@
   "Hybrid": "Ibrido",
   "TomTom key unavailable": "Chiave TomTom non disponibile",
   "TomTom daily budget reached": "Budget giornaliero TomTom esaurito",
+  "Monthly traffic allowance used": "Quota mensile del traffico esaurita",
+  "Traffic rate limit reached": "Limite di richieste del traffico raggiunto",
+  "Traffic service unavailable": "Servizio traffico non disponibile",
   "TomTom upstream unreachable": "Servizio TomTom irraggiungibile",
   "TomTom flow unavailable": "Flusso TomTom non disponibile",
   "SIMULATED — {reason}": "SIMULATO: {reason}",
diff --git a/src/i18n/locales/ja.json b/src/i18n/locales/ja.json
index 9a053f869..932d851e2 100644
--- a/src/i18n/locales/ja.json
+++ b/src/i18n/locales/ja.json
@@ -1073,6 +1073,9 @@
   "Hybrid": "ハイブリッド",
   "TomTom key unavailable": "TomTomキーを利用できません",
   "TomTom daily budget reached": "TomTomの1日の上限に達しました",
+  "Monthly traffic allowance used": "今月の交通情報の上限に達しました",
+  "Traffic rate limit reached": "交通情報のリクエスト上限に達しました",
+  "Traffic service unavailable": "交通情報サービスを利用できません",
   "TomTom upstream unreachable": "TomTomのサービスに接続できません",
   "TomTom flow unavailable": "TomTomの交通流を利用できません",
   "SIMULATED — {reason}": "シミュレーション：{reason}",
diff --git a/src/i18n/locales/pt.json b/src/i18n/locales/pt.json
index 79c507759..e71f144d5 100644
--- a/src/i18n/locales/pt.json
+++ b/src/i18n/locales/pt.json
@@ -1103,6 +1103,9 @@
   "Hybrid": "Híbrido",
   "TomTom key unavailable": "Chave do TomTom indisponível",
   "TomTom daily budget reached": "Limite diário do TomTom atingido",
+  "Monthly traffic allowance used": "Cota mensal de trânsito esgotada",
+  "Traffic rate limit reached": "Limite de solicitações de trânsito atingido",
+  "Traffic service unavailable": "Serviço de trânsito indisponível",
   "TomTom upstream unreachable": "Servidor do TomTom inacessível",
   "TomTom flow unavailable": "Fluxo do TomTom indisponível",
   "SIMULATED — {reason}": "SIMULADO — {reason}",
diff --git a/src/i18n/locales/ru.json b/src/i18n/locales/ru.json
index 11fddb3e9..6573ad11b 100644
--- a/src/i18n/locales/ru.json
+++ b/src/i18n/locales/ru.json
@@ -2313,6 +2313,9 @@
   "SIMULATED — {reason}": "СИМУЛЯЦИЯ — {reason}",
   "TomTom key unavailable": "Ключ TomTom недоступен",
   "TomTom daily budget reached": "Исчерпан дневной лимит TomTom",
+  "Monthly traffic allowance used": "Месячный лимит данных о трафике исчерпан",
+  "Traffic rate limit reached": "Достигнут лимит запросов данных о трафике",
+  "Traffic service unavailable": "Сервис данных о трафике недоступен",
   "TomTom upstream unreachable": "Сервер TomTom не отвечает",
   "TomTom flow unavailable": "Поток TomTom недоступен",
   "API key rejected — check AISSTREAM_API_KEY": "Ключ API отклонён — проверьте AISSTREAM_API_KEY",
diff --git a/src/i18n/locales/uk.json b/src/i18n/locales/uk.json
index c0fab8533..18ea8dc4f 100644
--- a/src/i18n/locales/uk.json
+++ b/src/i18n/locales/uk.json
@@ -1120,6 +1120,9 @@
   "Hybrid": "Гібрид",
   "TomTom key unavailable": "Ключ TomTom недоступний",
   "TomTom daily budget reached": "Вичерпано денний ліміт TomTom",
+  "Monthly traffic allowance used": "Місячний ліміт даних про трафік вичерпано",
+  "Traffic rate limit reached": "Досягнуто ліміту запитів даних про трафік",
+  "Traffic service unavailable": "Сервіс даних про трафік недоступний",
   "TomTom upstream unreachable": "Сервер TomTom не відповідає",
   "TomTom flow unavailable": "Потік TomTom недоступний",
   "SIMULATED — {reason}": "ІМІТАЦІЯ — {reason}",
diff --git a/src/i18n/locales/zh-CN.json b/src/i18n/locales/zh-CN.json
index 8687af790..8d09b74a3 100644
--- a/src/i18n/locales/zh-CN.json
+++ b/src/i18n/locales/zh-CN.json
@@ -1049,6 +1049,9 @@
   "Hybrid": "混合",
   "TomTom key unavailable": "TomTom 密钥不可用",
   "TomTom daily budget reached": "已达 TomTom 每日配额",
+  "Monthly traffic allowance used": "本月交通流量额度已用完",
+  "Traffic rate limit reached": "已达到交通数据请求频率上限",
+  "Traffic service unavailable": "交通服务不可用",
   "TomTom upstream unreachable": "TomTom 上游服务无法连接",
   "TomTom flow unavailable": "TomTom 路况不可用",
   "SIMULATED — {reason}": "模拟——{reason}",
diff --git a/src/i18n/locales/zh-Hant.json b/src/i18n/locales/zh-Hant.json
index a95e71dd5..30801f0f9 100644
--- a/src/i18n/locales/zh-Hant.json
+++ b/src/i18n/locales/zh-Hant.json
@@ -1044,6 +1044,9 @@
   "Hybrid": "混合",
   "TomTom key unavailable": "TomTom 密鑰不可用",
   "TomTom daily budget reached": "已達 TomTom 每日配額",
+  "Monthly traffic allowance used": "本月交通流量額度已用完",
+  "Traffic rate limit reached": "已達交通資料請求頻率上限",
+  "Traffic service unavailable": "交通服務無法使用",
   "TomTom upstream unreachable": "TomTom 上游服務無法連接",
   "TomTom flow unavailable": "TomTom 路況不可用",
   "SIMULATED — {reason}": "模擬——{reason}",
diff --git a/src/layers/traffic/flow.js b/src/layers/traffic/flow.js
index 2064c10ce..caf8aede2 100644
--- a/src/layers/traffic/flow.js
+++ b/src/layers/traffic/flow.js
@@ -38,7 +38,15 @@ export function createFlow({ state: layerState, services, parts, source }) {
     const status = Number.isFinite(error.status)
       ? error.status
       : Number(message.match(/HTTP (\d{3})/)?.[1]);
+    const code = typeof error.code === 'string' ? error.code : null;
     // English in state; trafficFeedPresentation translates it for the panel.
+    // A hosted deployment limits each account (code from the server); the
+    // local proxy has one daily budget (`budget`) and answers `no_key`.
+    if (code === 'USAGE_LIMIT_REACHED')
+      return msg('Monthly traffic allowance used');
+    if (code === 'RATE_LIMITED') return msg('Traffic rate limit reached');
+    if (status === 503 && code && code !== 'no_key')
+      return msg('Traffic service unavailable');
     if (status === 503) return msg('TomTom key unavailable');
     if (status === 429) return msg('TomTom daily budget reached');
     if (status === 502 || status === 504)
diff --git a/src/layers/traffic/flowSource.js b/src/layers/traffic/flowSource.js
index 12e746e43..e5402cf12 100644
--- a/src/layers/traffic/flowSource.js
+++ b/src/layers/traffic/flowSource.js
@@ -11,6 +11,26 @@ const FLOW_TILE_PATH = (z, x, y) => `/api/tomtom/flow/${z}/${x}/${y}.pbf`;
  * (STALE-BUDGET once the daily budget is spent, STALE-ERROR when TomTom
  * fails), and when the proxy fetched it.
  */
+/**
+ * The machine-readable reason a failed tile carries: `code` (hosted usage,
+ * e.g. USAGE_LIMIT_REACHED or RATE_LIMITED) or the local proxy's `error`
+ * (`no_key`, `budget`). Only short identifiers are kept; prose is ignored.
+ */
+async function failureCode(response) {
+  if (!/json/i.test(response.headers?.get?.('content-type') || '')) return null;
+  try {
+    const text = await response.text();
+    if (text.length > 4096) return null;
+    const body = JSON.parse(text);
+    const code = body?.code ?? body?.error;
+    return typeof code === 'string' && /^[A-Za-z_]{1,40}$/.test(code)
+      ? code
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 function tileFreshness(response) {
   const status = response.headers?.get?.('x-tomtom-cache') || '';
   const fetchedAt = Number(response.headers?.get?.('x-tomtom-fetched-at'));
@@ -60,7 +80,16 @@ export function createFlowTileSource({
     },
     fetchImpl: async (url, init) => {
       const response = await fetchImpl(url, init);
-      if (response.ok && !init.signal.aborted) {
+      if (!response.ok) {
+        const code = await failureCode(response);
+        await response.body?.cancel().catch(() => {});
+        throw Object.assign(
+          // Classified for display by deriveTrafficFlowError.
+          new Error(`TomTom flow unavailable (HTTP ${response.status})`),
+          { status: response.status, code },
+        );
+      }
+      if (!init.signal.aborted) {
         const path = String(url);
         const entry = {
           mark: tileFreshness(response),
diff --git a/src/layers/traffic/source.test.mjs b/src/layers/traffic/source.test.mjs
index 779164b7c..e45f5ef0f 100644
--- a/src/layers/traffic/source.test.mjs
+++ b/src/layers/traffic/source.test.mjs
@@ -1050,3 +1050,29 @@ test('cancelling a flow body releases its freshness before a new request', async
   assert.equal(getEventListeners(requestSignal, 'abort').length, 0);
   assert.equal(source.getFlowSessionStats().cacheEntries, 0);
 });
+
+test('a failed flow tile carries the server reason for its label', async () => {
+  for (const [status, body, code] of [
+    [
+      429,
+      { error: 'Monthly usage limit reached', code: 'USAGE_LIMIT_REACHED' },
+      'USAGE_LIMIT_REACHED',
+    ],
+    [
+      429,
+      { error: 'Request rate limit reached', code: 'RATE_LIMITED' },
+      'RATE_LIMITED',
+    ],
+    [503, { error: 'no_key' }, 'no_key'],
+    [503, { error: 'Usage enforcement is temporarily unavailable' }, null],
+  ]) {
+    const source = createFlowTileSource({
+      fetchImpl: async () => Response.json(body, { status }),
+    });
+    await assert.rejects(source.fetchFlowForBounds(bounds), (error) => {
+      assert.equal(error.status, status);
+      assert.equal(error.code, code);
+      return true;
+    });
+  }
+});

From 5d8f2b878f5ef204b5efb4519a7fbbbc3699b59f Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Fri, 6 Nov 2026 15:47:36 +0400
Subject: [PATCH 68/71] chore(datacenters): drop the one-off Norway refresh
 script

The data refresh is committed and its provenance (extract, timestamp, MD5,
filter) stays in the dataset README. The script needed osmium-tool and could
only re-verify while Geofabrik still listed that extract, so it goes with its
test.
---
 changelog.d/953-datacenters-norway-refresh.md |   6 +-
 scripts/build-datacenters-norway.py           | 259 ------------------
 src/data/datacentersNorwayRefresh.test.mjs    |  95 -------
 src/data/local_data/datacenters/README.md     |  12 +-
 4 files changed, 3 insertions(+), 369 deletions(-)
 delete mode 100644 scripts/build-datacenters-norway.py
 delete mode 100644 src/data/datacentersNorwayRefresh.test.mjs

diff --git a/changelog.d/953-datacenters-norway-refresh.md b/changelog.d/953-datacenters-norway-refresh.md
index 48a019605..5db897234 100644
--- a/changelog.d/953-datacenters-norway-refresh.md
+++ b/changelog.d/953-datacenters-norway-refresh.md
@@ -1,6 +1,4 @@
 - Refresh Norway's datacenters from a Geofabrik OpenStreetMap extract
   (2026-10-05). Troll Housing joins the layer (4,352 features) and four
-  Norwegian sites pick up current OSM tags; no site moved or was removed.
-  `scripts/build-datacenters-norway.py` reproduces or `--verify`s the merge,
-  touching only features inside Geofabrik's Norway boundary, and the dataset
-  README records the extract, checksum and filter (trygvehhh, #953).
+  Norwegian sites pick up current OSM tags; no site moved or was removed
+  (trygvehhh, #953).
diff --git a/scripts/build-datacenters-norway.py b/scripts/build-datacenters-norway.py
deleted file mode 100644
index 3c5eb92dd..000000000
--- a/scripts/build-datacenters-norway.py
+++ /dev/null
@@ -1,259 +0,0 @@
-#!/usr/bin/env python3
-"""Maintainer-only Norway refresh of the bundled datacenter extract (osmium-tool).
-
-Downloads a dated Geofabrik Norway extract, verifies its MD5, filters
-telecom=data_center / building=data_center with osmium, and merges the result
-into datacenters.geojsonl: features inside the Geofabrik Norway boundary are
-added, updated or removed once no longer tagged; every other line is kept
-byte-for-byte.
-
-Geofabrik keeps only its newest dated extract, so --extract defaults to the
-current one and a recorded extract can be re-verified only while it is listed.
-"""
-import argparse
-import hashlib
-import json
-import math
-from pathlib import Path
-import shutil
-import subprocess
-import sys
-import urllib.request
-
-ROOT = Path(__file__).resolve().parent.parent
-GEOFABRIK = 'https://download.geofabrik.de/europe/'
-DATASET = ROOT / 'src/data/local_data/datacenters/datacenters.geojsonl'
-CONTACT_TAGS = {'email', 'phone', 'fax', 'mobile', 'whatsapp', 'contact:email', 'contact:phone',
-                'contact:fax', 'contact:mobile', 'contact:whatsapp'}
-SAME_GEOMETRY_METERS = 0.05
-TIMEOUT_SECONDS = 60
-
-
-def latest_extract():
-    """Resolve norway-latest to the dated name Geofabrik redirects it to."""
-    request = urllib.request.Request(GEOFABRIK + 'norway-latest.osm.pbf', method='HEAD')
-    with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
-        name = response.geturl().rsplit('/', 1)[-1]
-    if not name.startswith('norway-') or not name.endswith('.osm.pbf') or name == 'norway-latest.osm.pbf':
-        raise RuntimeError('Unexpected Geofabrik latest target: %s' % name)
-    return name[:-len('.osm.pbf')]
-
-
-def fetch(url, target):
-    if not target.exists():
-        with urllib.request.urlopen(url, timeout=TIMEOUT_SECONDS) as response, \
-                open(str(target) + '.part', 'wb') as out:
-            shutil.copyfileobj(response, out)
-        Path(str(target) + '.part').rename(target)
-    return target
-
-
-def md5(path):
-    digest = hashlib.md5()
-    with open(path, 'rb') as handle:
-        for block in iter(lambda: handle.read(1 << 20), b''):
-            digest.update(block)
-    return digest.hexdigest()
-
-
-def read_poly(path):
-    """Geofabrik .poly -> list of (ring, is_hole)."""
-    rings, ring, hole = [], None, False
-    for raw in path.read_text(encoding='utf-8').splitlines()[1:]:
-        line = raw.strip()
-        if ring is None:
-            if line and line != 'END':
-                ring, hole = [], line.startswith('!')
-        elif line == 'END':
-            rings.append((ring, hole))
-            ring = None
-        elif line:
-            lon, lat = (float(v) for v in line.split())
-            ring.append((lon, lat))
-    return rings
-
-
-def inside(rings, lon, lat):
-    def in_ring(ring):
-        hit = False
-        for (x1, y1), (x2, y2) in zip(ring, ring[1:] + ring[:1]):
-            if (y1 > lat) != (y2 > lat) and lon < x1 + (lat - y1) * (x2 - x1) / (y2 - y1):
-                hit = not hit
-        return hit
-    return any(in_ring(r) for r, h in rings if not h) and not any(in_ring(r) for r, h in rings if h)
-
-
-def points(coordinates):
-    if isinstance(coordinates[0], (int, float)):
-        return [coordinates]
-    return [p for part in coordinates for p in points(part)]
-
-
-def osm_key(feature):
-    osm_id = feature['properties']['osm_id']
-    if osm_id < 0:
-        return 'r%d' % -osm_id
-    return ('n' if feature['geometry']['type'] == 'Point' else 'w') + str(osm_id)
-
-
-def export(osmium, pbf, cache, extract):
-    """Exported features by key, and the keys of every tagged object in the extract."""
-    filtered = cache / (extract + '-datacenters.osm.pbf')
-    listed = cache / (extract + '-datacenters.opl')
-    exported = cache / (extract + '-datacenters.geojsonseq')
-    subprocess.run([osmium, 'tags-filter', '-O', '-o', str(filtered), str(pbf),
-                    'nwr/telecom=data_center', 'nwr/building=data_center'], check=True)
-    subprocess.run([osmium, 'tags-filter', '-O', '-R', '-f', 'opl', '-o', str(listed), str(filtered),
-                    'nwr/telecom=data_center', 'nwr/building=data_center'], check=True)
-    tagged = {line.split(' ', 1)[0] for line in listed.read_text(encoding='utf-8').splitlines() if line}
-    subprocess.run([osmium, 'export', '-O', '-f', 'geojsonseq', '--add-unique-id=type_id',
-                    '-o', str(exported), str(filtered)], check=True)
-    fresh = {}
-    for line in exported.read_text(encoding='utf-8').splitlines():
-        line = line.lstrip('\x1e').strip()
-        if not line:
-            continue
-        feature = json.loads(line)
-        tags = {k: v for k, v in feature['properties'].items() if k not in CONTACT_TAGS}
-        if tags.get('telecom') != 'data_center' and tags.get('building') != 'data_center':
-            continue  # untagged member ways exported only for geometry
-        key = feature['id']
-        geometry = feature['geometry']
-        if key[0] == 'a':  # osmium area id: way * 2 or relation * 2 + 1
-            number = int(key[1:])
-            key = ('w%d' % (number // 2)) if number % 2 == 0 else ('r%d' % (number // 2))
-            if key[0] == 'r':
-                tags = {**tags, 'type': 'multipolygon'}
-            if geometry['type'] == 'MultiPolygon' and len(geometry['coordinates']) == 1:
-                geometry = {'type': 'Polygon', 'coordinates': geometry['coordinates'][0]}
-        elif key in fresh or geometry['type'] == 'LineString':
-            continue  # closed ways are taken from their area export
-        fresh[key] = {'geometry': geometry, 'tags': tags}
-    return fresh, tagged
-
-
-def same_geometry(old, new):
-    """Same type and rings within tolerance; ring start, winding and part or hole order may differ."""
-    if old['type'] != new['type']:
-        return False
-
-    def meters(p, q):
-        dx = (p[0] - q[0]) * 111320 * math.cos(math.radians(p[1]))
-        return math.hypot(dx, (p[1] - q[1]) * 110540)
-
-    def same_line(a, b):
-        return len(a) == len(b) and all(meters(p, q) <= SAME_GEOMETRY_METERS for p, q in zip(a, b))
-
-    def same_ring(a, b):
-        a, b = a[:-1], b[:-1]  # closed rings repeat their first vertex
-        return len(a) == len(b) and \
-            any(same_line(a[i:] + a[:i], c) for c in (b, b[::-1]) for i in range(len(a)))
-
-    def same_parts(a, b, same):
-        rest = list(b)
-        for part in a:
-            match = next((i for i, other in enumerate(rest) if same(part, other)), None)
-            if match is None:
-                return False
-            rest.pop(match)
-        return not rest
-
-    def same_polygon(a, b):
-        return same_ring(a[0], b[0]) and same_parts(a[1:], b[1:], same_ring)
-
-    a, b = old['coordinates'], new['coordinates']
-    if old['type'] == 'Point':
-        return same_line([a], [b])
-    if old['type'] == 'LineString':
-        return same_line(a, b)
-    if old['type'] == 'Polygon':
-        return same_polygon(a, b)
-    if old['type'] == 'MultiPolygon':
-        return same_parts(a, b, same_polygon)
-    return a == b
-
-
-def feature_line(key, sequence, fresh):
-    osm_id = int(key[1:]) * (-1 if key[0] == 'r' else 1)
-    feature = {'id': osm_id, 'type': 'Feature', 'geometry': fresh['geometry'],
-               'properties': {'id': sequence, 'tags': fresh['tags'], 'type': 'data_center',
-                              'osm_id': osm_id}}
-    return json.dumps(feature, separators=(',', ':'), ensure_ascii=False)
-
-
-def merge(lines, fresh, rings, tagged):
-    out, known, sequence = [], set(), 0
-    report = {'kept': 0, 'updated': [], 'removed': [], 'added': [], 'unexported': [], 'skipped': []}
-    for line in lines:
-        feature = json.loads(line)
-        sequence = max(sequence, feature['properties']['id'])
-        key = osm_key(feature)
-        known.add(key)
-        if key in fresh:
-            old_tags = feature['properties']['tags']
-            if old_tags == fresh[key]['tags'] and same_geometry(feature['geometry'], fresh[key]['geometry']):
-                out.append(line)
-                report['kept'] += 1
-            else:
-                out.append(feature_line(key, feature['properties']['id'], fresh[key]))
-                report['updated'].append(key)
-            continue
-        if key in tagged:  # still tagged, but osmium built no usable geometry: keep the old line
-            report['unexported'].append(key)
-            out.append(line)
-            continue
-        lon, lat = points(feature['geometry']['coordinates'])[0][:2]
-        if inside(rings, lon, lat):
-            report['removed'].append(key)
-            continue
-        out.append(line)
-    for key in sorted(set(fresh) - known, key=lambda k: (k[0], int(k[1:]))):
-        sequence += 1
-        out.append(feature_line(key, sequence, fresh[key]))
-        report['added'].append(key)
-    # newly tagged, but osmium built no usable geometry: nothing to add yet
-    report['skipped'] = sorted(set(tagged) - set(fresh) - known, key=lambda k: (k[0], int(k[1:])))
-    if len({osm_key(json.loads(line)) for line in out}) != len(out):
-        raise ValueError('Duplicate OSM identity')
-    return out, report
-
-
-def main():
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('--cache', type=Path, required=True)
-    parser.add_argument('--osmium', default=shutil.which('osmium') or 'osmium')
-    parser.add_argument('--extract', default='latest',
-                        help="dated Geofabrik name such as norway-261005, or 'latest'")
-    parser.add_argument('--verify', action='store_true')
-    args = parser.parse_args()
-    args.cache.mkdir(parents=True, exist_ok=True)
-    extract = latest_extract() if args.extract == 'latest' else args.extract
-    pbf = fetch(GEOFABRIK + extract + '.osm.pbf', args.cache / (extract + '.osm.pbf'))
-    expected = fetch(GEOFABRIK + extract + '.osm.pbf.md5',
-                     args.cache / (extract + '.osm.pbf.md5')).read_text(encoding='utf-8').split()[0]
-    actual = md5(pbf)
-    if actual != expected:
-        raise RuntimeError('MD5 mismatch for %s: %s != %s' % (pbf.name, actual, expected))
-    rings = read_poly(fetch(GEOFABRIK + 'norway.poly', args.cache / 'norway.poly'))
-    fresh, tagged = export(args.osmium, pbf, args.cache, extract)
-    current = [line for line in DATASET.read_text(encoding='utf-8').splitlines() if line.strip()]
-    merged, report = merge(current, fresh, rings, tagged)
-    if report['unexported']:
-        print('warning: kept the old line of tagged features osmium did not export: %s'
-              % ', '.join(report['unexported']), file=sys.stderr)
-    if report['skipped']:
-        print('warning: did not add newly tagged features osmium did not export: %s'
-              % ', '.join(report['skipped']), file=sys.stderr)
-    payload = '\n'.join(merged) + '\n'
-    if args.verify:
-        if payload != DATASET.read_text(encoding='utf-8'):
-            raise SystemExit('datacenters.geojsonl is not the %s merge' % extract)
-    else:
-        with open(DATASET, 'w', encoding='utf-8', newline='\n') as handle:
-            handle.write(payload)
-    print(json.dumps({'extract': extract, 'md5': actual, 'norway': len(fresh),
-                      'features': len(merged), **report}))
-
-
-if __name__ == '__main__':
-    main()
diff --git a/src/data/datacentersNorwayRefresh.test.mjs b/src/data/datacentersNorwayRefresh.test.mjs
deleted file mode 100644
index 99278769e..000000000
--- a/src/data/datacentersNorwayRefresh.test.mjs
+++ /dev/null
@@ -1,95 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-const SCRIPT = fileURLToPath(
-  new URL('../../scripts/build-datacenters-norway.py', import.meta.url),
-);
-
-function python(t, source) {
-  const result = spawnSync('python3', ['-c', source, SCRIPT], {
-    encoding: 'utf8',
-  });
-  if (result.error?.code === 'ENOENT') return t.skip('python3 is not installed');
-  assert.equal(result.status, 0, result.stderr);
-}
-
-test('Norway refresh compares rings, not vertex sets', (t) => {
-  python(
-    t,
-    String.raw`
-import runpy, sys
-same = runpy.run_path(sys.argv[1])['same_geometry']
-poly = lambda *rings: {'type': 'Polygon', 'coordinates': list(rings)}
-multi = lambda *polys: {'type': 'MultiPolygon', 'coordinates': [p['coordinates'] for p in polys]}
-a, b, c, d, e = [0, 0], [4, 0], [4, 4], [0, 4], [2, 1]
-assert not same(poly([a, b, c, d, e, a]), poly([a, b, e, c, d, a])), 'reordered edges'
-assert same(poly([a, b, c, d, e, a]), poly([c, b, a, e, d, c])), 'ring start and winding'
-assert same(poly([a, b, c, d, a]), poly([[0, 1e-7], b, c, d, [0, 1e-7]])), 'tolerance'
-outer = [[0, 0], [9, 0], [9, 9], [0, 9], [0, 0]]
-one, two = [[1, 1], [2, 1], [2, 2], [1, 1]], [[5, 5], [6, 5], [6, 6], [5, 5]]
-assert same(poly(outer, one, two), poly(outer, two, one)), 'hole order'
-assert not same(poly(outer, one), poly(one, outer)), 'outer and inner roles swapped'
-assert same(multi(poly(one), poly(two)), multi(poly(two), poly(one))), 'part order'
-p, q, r, s, u, v = [0, 0], [1, 0], [0, 1], [5, 5], [6, 5], [5, 6]
-assert not same(multi(poly([p, q, r, p]), poly([s, u, v, s])),
-                multi(poly([p, q, s, p]), poly([r, u, v, r]))), 'vertices moved between parts'
-`,
-  );
-});
-
-test('Norway refresh keeps a still-tagged feature osmium did not export', (t) => {
-  python(
-    t,
-    String.raw`
-import json, runpy, sys
-merge = runpy.run_path(sys.argv[1])['merge']
-square = [[[10, 60], [10.01, 60], [10.01, 60.01], [10, 60.01], [10, 60]]]
-def line(osm_id, sequence):
-    return json.dumps({'id': osm_id, 'type': 'Feature', 'geometry': {'type': 'Polygon', 'coordinates': square},
-                       'properties': {'id': sequence, 'tags': {'building': 'data_center'},
-                                      'type': 'data_center', 'osm_id': osm_id}})
-norway = [([(0, 0), (20, 0), (20, 80), (0, 80)], False)]
-lines = [line(7, 1), line(8, 2)]
-fresh = {'w13': {'geometry': {'type': 'Polygon', 'coordinates': square}, 'tags': {'building': 'data_center'}}}
-out, report = merge(lines, fresh, norway, {'w7', 'w12', 'w13'})
-assert out[0] == lines[0] and len(out) == 2, out
-assert report['unexported'] == ['w7'] and report['removed'] == ['w8'], report
-assert report['skipped'] == ['w12'] and report['added'] == ['w13'], report
-`,
-  );
-});
-
-test('Norway refresh lists tagged objects apart from the exported geometry', (t) => {
-  python(
-    t,
-    String.raw`
-import json, runpy, subprocess, sys, tempfile
-from pathlib import Path
-export = runpy.run_path(sys.argv[1])['export']
-tags = {'building': 'data_center'}
-ring = [[10, 60], [10.01, 60], [10.01, 60.01], [10, 60]]
-features = [
-    {'id': 'n1', 'properties': {'telecom': 'data_center'}, 'geometry': {'type': 'Point', 'coordinates': [10, 60]}},
-    {'id': 'w5', 'properties': tags, 'geometry': {'type': 'LineString', 'coordinates': ring}},
-    {'id': 'a10', 'properties': tags, 'geometry': {'type': 'MultiPolygon', 'coordinates': [[ring]]}},
-    {'id': 'w7', 'properties': tags, 'geometry': {'type': 'LineString', 'coordinates': ring[:3]}},
-]
-outputs = {
-    '.opl': 'n1 v1 Ttelecom=data_center x10 y60\nw5 v1 Tbuilding=data_center Nn2,n3,n4,n2\n'
-            'w7 v1 Tbuilding=data_center Nn2,n3,n4\nr9 v1 Ttelecom=data_center Mw8@outer\n',
-    '.geojsonseq': ''.join(chr(30) + json.dumps({'type': 'Feature', **f}) + '\n' for f in features),
-}
-def run(args, check=False):
-    target = Path(args[args.index('-o') + 1])
-    target.write_text(outputs.get(target.suffix, ''), encoding='utf-8')
-subprocess.run = run
-with tempfile.TemporaryDirectory() as cache:
-    fresh, tagged = export('osmium', Path(cache) / 'norway-test.osm.pbf', Path(cache), 'norway-test')
-assert sorted(fresh) == ['n1', 'w5'], fresh
-assert fresh['w5']['geometry'] == {'type': 'Polygon', 'coordinates': [ring]}, fresh['w5']
-assert tagged == {'n1', 'w5', 'w7', 'r9'}, tagged
-`,
-  );
-});
diff --git a/src/data/local_data/datacenters/README.md b/src/data/local_data/datacenters/README.md
index 86f573c61..c360ee527 100644
--- a/src/data/local_data/datacenters/README.md
+++ b/src/data/local_data/datacenters/README.md
@@ -26,14 +26,4 @@ reflects OSM as of the extract below, everything else the original snapshot.
 - Extract: Geofabrik `norway-261005.osm.pbf`, OSM data
   2026-10-05T20:21:35Z, MD5 `1d2cfdeb98980fce11b8891d0f9146c0`
 - Filter: `osmium tags-filter nwr/telecom=data_center nwr/building=data_center`
-- Contact tags are dropped as above; unchanged features keep their original
-  line, so geometry is only rewritten when tags or rings actually changed.
-  A feature is removed only once it is no longer tagged; one still tagged but
-  without an exportable geometry keeps its line and is reported as unexported,
-  and a newly tagged one osmium cannot export is reported as skipped.
-- Refresh: `python3 scripts/build-datacenters-norway.py --cache <dir>` uses
-  Geofabrik's current Norway extract and prints the dated name it used; record
-  that name, its OSM timestamp and MD5 here. Requires `osmium-tool`.
-- Check: add `--extract <dated name> --verify` to compare without writing.
-  Geofabrik keeps only its newest dated extract, so a recorded extract can be
-  re-verified only while it is still listed; the MD5 above identifies it.
+- Contact tags are dropped as above.

From a69d0492d0cda16a1eef15d022629f4949f293b5 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Fri, 6 Nov 2026 15:54:53 +0400
Subject: [PATCH 69/71] docs(datacenters): tighten the Norway refresh notes

---
 changelog.d/953-datacenters-norway-refresh.md | 6 ++----
 docs/INFRASTRUCTURE-LAYERS.md                 | 2 +-
 src/data/local_data/datacenters/README.md     | 6 ++----
 3 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/changelog.d/953-datacenters-norway-refresh.md b/changelog.d/953-datacenters-norway-refresh.md
index 5db897234..d60d4ac00 100644
--- a/changelog.d/953-datacenters-norway-refresh.md
+++ b/changelog.d/953-datacenters-norway-refresh.md
@@ -1,4 +1,2 @@
-- Refresh Norway's datacenters from a Geofabrik OpenStreetMap extract
-  (2026-10-05). Troll Housing joins the layer (4,352 features) and four
-  Norwegian sites pick up current OSM tags; no site moved or was removed
-  (trygvehhh, #953).
+- Add Troll Housing to the Datacenters layer (4,352 features) by refreshing
+  Norway from OpenStreetMap data of 2026-10-05 (trygvehhh, #953).
diff --git a/docs/INFRASTRUCTURE-LAYERS.md b/docs/INFRASTRUCTURE-LAYERS.md
index aa8cd0558..798ff09af 100644
--- a/docs/INFRASTRUCTURE-LAYERS.md
+++ b/docs/INFRASTRUCTURE-LAYERS.md
@@ -59,4 +59,4 @@ globals.
 Dataset files and source/license notices remain under `src/data/local_data/`.
 Their input counts are 4,352 datacenter features and 704 dam features. Cesium may
 expand multipart geometries into multiple entities; entity and stem counts are
-different measurements. This change does not refresh or relicense the datasets.
+different measurements.
diff --git a/src/data/local_data/datacenters/README.md b/src/data/local_data/datacenters/README.md
index c360ee527..a89894fdb 100644
--- a/src/data/local_data/datacenters/README.md
+++ b/src/data/local_data/datacenters/README.md
@@ -19,11 +19,9 @@ snapshot. Future refreshes should record both before replacing the file.
 
 ## Norway refresh
 
-Features inside the Geofabrik Norway boundary (`norway.poly`, which includes
-Svalbard) were refreshed separately, so this file mixes two vintages: Norway
-reflects OSM as of the extract below, everything else the original snapshot.
+Features inside Geofabrik's Norway boundary (`norway.poly`, with Svalbard) come
+from a newer extract than the rest of the file. Contact tags are dropped as above.
 
 - Extract: Geofabrik `norway-261005.osm.pbf`, OSM data
   2026-10-05T20:21:35Z, MD5 `1d2cfdeb98980fce11b8891d0f9146c0`
 - Filter: `osmium tags-filter nwr/telecom=data_center nwr/building=data_center`
-- Contact tags are dropped as above.

From c058ecf21b98f3097adea6cd512b4931cb864723 Mon Sep 17 00:00:00 2001
From: German Khokhlov <ouchlock@gmail.com>
Date: Fri, 6 Nov 2026 15:57:27 +0400
Subject: [PATCH 70/71] docs(infrastructure): keep the dataset scope note

---
 docs/INFRASTRUCTURE-LAYERS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/INFRASTRUCTURE-LAYERS.md b/docs/INFRASTRUCTURE-LAYERS.md
index 798ff09af..aa8cd0558 100644
--- a/docs/INFRASTRUCTURE-LAYERS.md
+++ b/docs/INFRASTRUCTURE-LAYERS.md
@@ -59,4 +59,4 @@ globals.
 Dataset files and source/license notices remain under `src/data/local_data/`.
 Their input counts are 4,352 datacenter features and 704 dam features. Cesium may
 expand multipart geometries into multiple entities; entity and stem counts are
-different measurements.
+different measurements. This change does not refresh or relicense the datasets.

From 141181f83a0cc2fa6379a4c77af04469aee2df92 Mon Sep 17 00:00:00 2001
From: Said Turksever <asturksever@gmail.com>
Date: Fri, 6 Nov 2026 12:02:30 +0000
Subject: [PATCH 71/71] docs(flights): changelog names the one-in-13-ticks
 rotation, about once a second

---
 changelog.d/870-hidden-contact-dr.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/changelog.d/870-hidden-contact-dr.md b/changelog.d/870-hidden-contact-dr.md
index f88084d7a..aab55229e 100644
--- a/changelog.d/870-hidden-contact-dr.md
+++ b/changelog.d/870-hidden-contact-dr.md
@@ -1,4 +1,4 @@
 - Reduce dead-reckoning work for flights already hidden behind the horizon.
-  Hidden contacts update on a staggered one-in-12-ticks rotation while visible
-  contacts and contacts with fleet models retain the full update path
-  (Wilmer Alzate, #870).
+  Hidden contacts update on a staggered one-in-13-ticks rotation (about once a
+  second) while visible contacts and contacts with fleet models retain the full
+  update path (Wilmer Alzate, #870).