feat(outlines): restore voice outlines without public Overpass

use bundled place boundaries and shared OpenFreeMap tiles before a guarded Nominatim fallback

preserve multipart shapes, holes and cancellation,
and keep pending annotations visible while ground sampling finishes across frames

keep non-Latin name distinctions when selecting provider results,
and retain an outline anchor only when it lies in filled geometry

src/layers/airQuality/airQualityLocale.test.mjs

@@ -0,0 +1,107 @@
+// The Air quality layer (AQHI) reads in the UI language: layer name, Weather
+// card (title, coverage, status, legend, risk) and its own failure text.
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { setLocale, t } from '../../i18n/index.js';
+import { layerNameForId, localizeLayerName } from '../../ui/layerNames.js';
+import { LayerPanel } from '../../ui/layerPanel.js';
+import { translateFeedError } from '../../ui/statusText.js';
+import { createAirQualityLayer } from './index.js';
+
+function inLocale(locale, run) {
+  setLocale(locale);
+  try {
+    return run();
+  } finally {
+    setLocale('en');
+  }
+}
+
+function harness(source) {
+  const layer = createAirQualityLayer({
+    source,
+    overlayHost: { setEntries() {}, setVisible() {}, clearSource() {} },
+  });
+  const viewer = { dataSources: { add() {}, remove() {} } };
+  layer.init(viewer);
+  layer.enable(viewer);
+  return layer;
+}
+
+const reading = {
+  id: 'eccc:A',
+  provider: 'eccc',
+  scale: 'AQHI',
+  value: 2,
+  band: 'low',
+  stationId: 'A',
+  name: 'Toronto',
+  zone: 'ont',
+  lat: 43.65,
+  lon: -79.38,
+  observedMs: 1_700_000_000_000,
+  color: '#4cc9f0',
+  label: '2',
+  risk: 'Low health risk',
+  note: null,
+};
+
+for (const locale of ['es', 'ru']) {
+  test(`${locale}: the layer name is translated`, () => {
+    inLocale(locale, () => {
+      assert.notEqual(t('Air quality'), 'Air quality', 'catalog has the entry');
+      assert.equal(layerNameForId('air-quality'), t('Air quality'));
+      assert.equal(localizeLayerName('Air quality'), t('Air quality'));
+    });
+  });
+
+  test(`${locale}: the Weather card of Air quality is translated`, async () => {
+    const layer = harness({ getSnapshot: async () => [reading] });
+    await layer.update();
+    const controls = inLocale(locale, () => layer.getRowControls());
+    const english = [
+      controls.summary.label,
+      controls.summary.coverage,
+      controls.summary.status,
+      ...controls.legend.map((entry) => entry.label),
+      ...controls.list.items.map((item) => item.text),
+    ].filter((text) =>
+      /\b(Air quality|Canada only|stations reporting|Low|Moderate|High|health risk)\b/.test(
+        text,
+      ),
+    );
+    assert.deepEqual(english, [], `English left in the ${locale} card`);
+  });
+
+  test(`${locale}: the Air quality failure text is translated in the row`, () => {
+    const row = inLocale(locale, () =>
+      LayerPanel.prototype._buildMetaText({
+        id: 'air-quality',
+        enabled: true,
+        stats: {
+          count: 0,
+          error: 'Air quality request failed',
+          source: 'ECCC',
+          lastUpdate: null,
+        },
+      }),
+    );
+    assert.ok(!row.includes('Air quality request failed'), row);
+  });
+}
+
+for (const locale of ['en', 'es', 'ru']) {
+  test(`${locale}: the Weather card shows an HTTP failure as the row does`, async () => {
+    const layer = harness({
+      getSnapshot: async () => {
+        throw new Error('ECCC HTTP 503');
+      },
+    });
+    await layer.update();
+    const card = inLocale(locale, () => layer.getRowControls().summary.status);
+    assert.equal(
+      card,
+      inLocale(locale, () => translateFeedError('ECCC HTTP 503')),
+    );
+  });
+}

src/layers/airQuality/index.js

@@ -0,0 +1,295 @@
+import * as Cesium from 'cesium';
+import { msg, t, tn } from '../../i18n/index.js';
+import { translateFeedError } from '../../ui/statusText.js';
+import {
+  AIR_QUALITY_BANDS,
+  AIR_QUALITY_OVERLAY_SOURCE_ID,
+  AIR_QUALITY_OVERLAY_COHORT_LIMIT,
+  AIR_QUALITY_OVERLAY_COLLISION_CAPACITY,
+  AIR_QUALITY_PROVIDERS,
+  createAirQualityOverlayEntry,
+  mapAnalystRecord,
+  newestObservation,
+  readingsAreStale,
+  readingsInView,
+  selectAirQualityOverlayCohort,
+} from './model.js';
+export * from './model.js';
+export { createEcccAirQualitySource } from './source.js';
+
+/** Station markers are a point reading, not an extent. */
+const STATION_MARKER_RADIUS_M = 6_000;
+/** Readings listed in the readout card. */
+const READOUT_LIMIT = 5;
+
+/** Own one air-quality display, its refresh lifecycle, and its readout card. */
+export function createAirQualityLayer({ source, overlayHost } = {}) {
+  if (typeof source?.getSnapshot !== 'function')
+    throw new TypeError('Air quality requires a snapshot source');
+  if (!overlayHost) throw new TypeError('Air quality requires an overlay host');
+  let _viewer = null;
+  let _request = null;
+  let _dataSource = null;
+  let _readings = [];
+  let _count = 0;
+  let _lastUpdate = null;
+  let _lastError = null;
+  let _enabled = false;
+  let rowControlsListener = null;
+
+  const notify = () => rowControlsListener?.();
+
+  /** The camera's lon/lat rectangle in degrees, or null when unresolvable. */
+  const viewRectangle = () => {
+    const rectangle = _viewer?.camera?.computeViewRectangle?.();
+    if (!rectangle) return null;
+    const toDeg = Cesium.Math.toDegrees;
+    return {
+      west: toDeg(rectangle.west),
+      south: toDeg(rectangle.south),
+      east: toDeg(rectangle.east),
+      north: toDeg(rectangle.north),
+    };
+  };
+
+  const layer = {
+    id: 'air-quality',
+    name: 'Air quality',
+    icon: '◍',
+    source: 'ECCC MSC GeoMet',
+    updateInterval: 1_200_000,
+
+    init(viewer) {
+      if (_viewer) throw new Error('Air quality layer is already initialized');
+      _viewer = viewer;
+      _dataSource = new Cesium.CustomDataSource('air-quality');
+      _dataSource.show = false;
+      viewer.dataSources.add(_dataSource);
+      _readings = [];
+      _count = 0;
+      _lastUpdate = null;
+      _lastError = null;
+      _enabled = false;
+      overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, false);
+    },
+
+    enable() {
+      _enabled = true;
+      if (_dataSource) _dataSource.show = true;
+      overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, true);
+      notify();
+    },
+
+    disable() {
+      // Abort in flight: a response arriving after disable must not redraw.
+      _request?.abort();
+      _request = null;
+      _enabled = false;
+      if (_dataSource) _dataSource.show = false;
+      overlayHost.clearSource(AIR_QUALITY_OVERLAY_SOURCE_ID);
+      overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, false);
+      notify();
+    },
+
+    async update() {
+      if (!_enabled || !_dataSource) return false;
+      _request?.abort();
+      const request = new AbortController();
+      _request = request;
+      try {
+        const readings = await source.getSnapshot({ signal: request.signal });
+        // A superseded or aborted request must not touch the scene, and neither
+        // must one that lands after the layer was switched off.
+        if (request.signal.aborted || _request !== request || !_enabled)
+          return false;
+        _readings = readings;
+        this._render();
+        _count = _readings.length;
+        _lastUpdate = Date.now();
+        _lastError = null;
+        notify();
+        return true;
+      } catch (error) {
+        if (request.signal.aborted || _request !== request) return false;
+        _lastError = error?.message || msg('Air quality request failed');
+        console.warn('[Data:AirQuality] Refresh failed:', _lastError);
+        notify();
+        return false;
+      } finally {
+        if (_request === request) _request = null;
+      }
+    },
+
+    /** Rebuild entities and overlay labels from the current readings. */
+    _render() {
+      if (!_dataSource) return;
+      _dataSource.entities.removeAll();
+      const overlayEntries = [];
+      for (const reading of _readings) {
+        const position = Cesium.Cartesian3.fromDegrees(
+          reading.lon,
+          reading.lat,
+        );
+        const color = Cesium.Color.fromCssColorString(reading.color);
+        _dataSource.entities.add(
+          new Cesium.Entity({
+            id: `air-quality:${reading.id}`,
+            position,
+            ellipse: {
+              // Static axes, as in the earthquake layer: a per-frame axis
+              // re-tessellates the clamped ground primitive every frame.
+              semiMajorAxis: STATION_MARKER_RADIUS_M,
+              semiMinorAxis: STATION_MARKER_RADIUS_M,
+              material: new Cesium.ColorMaterialProperty(color.withAlpha(0.35)),
+              outline: true,
+              outlineColor: color.withAlpha(0.9),
+              outlineWidth: 2,
+              heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
+            },
+            properties: {
+              provider: reading.provider,
+              scale: reading.scale,
+              value: reading.value,
+              band: reading.band,
+              name: reading.name,
+              zone: reading.zone,
+              risk: reading.risk,
+              observedMs: reading.observedMs,
+              note: reading.note,
+              lat: reading.lat,
+              lon: reading.lon,
+            },
+          }),
+        );
+        overlayEntries.push(
+          createAirQualityOverlayEntry({
+            id: reading.id,
+            position,
+            title: `${reading.name} ${reading.label}`,
+            accent: reading.color,
+            value: reading.value,
+          }),
+        );
+      }
+      if (_enabled) {
+        overlayHost.setEntries(
+          AIR_QUALITY_OVERLAY_SOURCE_ID,
+          selectAirQualityOverlayCohort(overlayEntries),
+          {
+            cohortLimit: AIR_QUALITY_OVERLAY_COHORT_LIMIT,
+            collisionCapacity: AIR_QUALITY_OVERLAY_COLLISION_CAPACITY,
+            moving: false,
+          },
+        );
+      }
+    },
+
+    destroy(viewer = _viewer) {
+      _request?.abort();
+      _request = null;
+      _enabled = false;
+      overlayHost.clearSource(AIR_QUALITY_OVERLAY_SOURCE_ID);
+      overlayHost.setVisible(AIR_QUALITY_OVERLAY_SOURCE_ID, false);
+      if (_dataSource) {
+        viewer?.dataSources?.remove(_dataSource, true);
+        _dataSource = null;
+      }
+      _viewer = null;
+      _readings = [];
+      _count = 0;
+      _lastUpdate = null;
+      _lastError = null;
+      rowControlsListener = null;
+    },
+
+    /**
+     * Readout descriptor for the Weather panel: the band legend, and the worst
+     * readings currently in view.
+     *
+     * `readout: true` renders the toggle and source line only; the card owns
+     * the rest. Coverage is stated plainly because this layer is not global.
+     */
+    getRowControls() {
+      const provider = AIR_QUALITY_PROVIDERS.eccc;
+      const inView = readingsInView(_readings, viewRectangle(), READOUT_LIMIT);
+      const newest = _readings.reduce(
+        (max, reading) => Math.max(max, reading.observedMs || 0),
+        0,
+      );
+      // Readings and errors stay English data (analyst records, stats); the
+      // card translates them as the Layers panel row does. A provider's own
+      // error text has no catalog entry and shows as it came.
+      return {
+        readout: true,
+        summary: {
+          label: t(provider.label),
+          coverage: t(provider.coverage),
+          validTime: newest ? new Date(newest).toISOString() : undefined,
+          detail: `${provider.network} · ${provider.scale}`,
+          status: _lastError
+            ? translateFeedError(_lastError)
+            : _count === 0
+              ? _lastUpdate === null
+                ? t('No readings available')
+                : t('No current readings')
+              : tn(
+                  _count,
+                  '{count} station reporting',
+                  '{count} stations reporting',
+                ),
+          units: provider.scale,
+        },
+        legend: AIR_QUALITY_BANDS.map((band) => ({
+          color: band.color,
+          label: t(band.label),
+        })),
+        legendCategorical: true,
+        list: {
+          ariaLabel: t('Highest air-quality readings in view'),
+          items: inView.map((reading, index) => ({
+            id: reading.id,
+            ordinal: index + 1,
+            lead: `${reading.scale} ${reading.label}`,
+            text: `${reading.name} · ${t(reading.risk)}`,
+            accent: reading.color,
+          })),
+        },
+      };
+    },
+
+    setRowControlsListener(listener) {
+      rowControlsListener = typeof listener === 'function' ? listener : null;
+    },
+
+    /**
+     * Snapshot readings as JSON-safe records for the analyst query engine.
+     * @param {number} [maxCount=500]
+     * @returns {Array<object>}
+     */
+    getAnalystRecords(maxCount = 500) {
+      if (!_enabled || !_readings.length) return [];
+      const limit = Number.isFinite(maxCount)
+        ? Math.max(1, Math.floor(maxCount))
+        : 500;
+      return _readings
+        .slice(0, limit)
+        .map((reading, index) => mapAnalystRecord(reading, index));
+    },
+
+    getStats() {
+      // `lastUpdate` is when a response was received; `observedAt` is when the
+      // network actually measured. Freshness is judged on the latter, so a feed
+      // that keeps answering with hours-old observations reports STALE rather
+      // than being narrated as live by the HUD and voice provenance envelope.
+      return {
+        count: _count,
+        lastUpdate: _lastUpdate,
+        error: _lastError,
+        observedAt: newestObservation(_readings),
+        // Only a completed refresh can be stale; before one there is no feed.
+        stale: _lastUpdate !== null && readingsAreStale(_readings),
+      };
+    },
+  };
+  return layer;
+}

src/layers/airQuality/model.js

@@ -0,0 +1,399 @@
+/**
+ * @module layers/airQuality/model
+ *
+ * Air-quality readings, normalized across networks. Pure — no Cesium, no
+ * network.
+ *
+ * Air-quality indices are not interchangeable numbers. Canada's AQHI runs 1 to
+ * 10+ on health risk; the US AQI runs 0 to 500 on concentration breakpoints;
+ * Europe's EAQI is a five-step category. A reading is therefore carried as
+ * `{ provider, scale, value, band }` — who measured it, which index it is, the
+ * value on that index's own terms, and the band it falls in — so a second
+ * network can be added without retrofitting a shared numeric meaning that does
+ * not exist.
+ *
+ * Only ECCC's AQHI is implemented here; `AIR_QUALITY_PROVIDERS` is the seam a
+ * later provider registers against.
+ */
+// A portable export (package.json): no i18n here. The labels stay English data;
+// the Weather card (index.js) shows them translated.
+const msg = (text) => text;
+
+/** Band identifiers shared across providers, in ascending severity. */
+export const AIR_QUALITY_BANDS = Object.freeze([
+  Object.freeze({
+    id: 'low',
+    label: msg('Low'),
+    risk: msg('Low health risk'),
+    color: '#4cc9f0',
+  }),
+  Object.freeze({
+    id: 'moderate',
+    label: msg('Moderate'),
+    risk: msg('Moderate health risk'),
+    color: '#ffd43b',
+  }),
+  Object.freeze({
+    id: 'high',
+    label: msg('High'),
+    risk: msg('High health risk'),
+    color: '#ff6b35',
+  }),
+  Object.freeze({
+    id: 'very-high',
+    label: msg('Very High'),
+    risk: msg('Very High health risk'),
+    color: '#c1121f',
+  }),
+]);
+
+const BAND_BY_ID = new Map(AIR_QUALITY_BANDS.map((band) => [band.id, band]));
+
+/** Colour used when a station reports no usable reading. */
+export const AIR_QUALITY_UNKNOWN_COLOR = '#6b7785';
+
+export const AIR_QUALITY_OVERLAY_SOURCE_ID = 'air-quality';
+export const AIR_QUALITY_OVERLAY_COHORT_LIMIT = 48;
+export const AIR_QUALITY_OVERLAY_COLLISION_CAPACITY = 32;
+
+/**
+ * A reading this old is stale enough that displaying it would misinform.
+ * AQHI publishes hourly, so six hours is five missed publications.
+ */
+export const OBSERVATION_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * How old the newest observation may be before the layer reports itself stale.
+ *
+ * This is deliberately separate from the age at which a reading is dropped.
+ * `lastUpdate` records when we last *received* a response, which stays current
+ * even when the network publishes nothing new; freshness has to be judged on
+ * the source's own observation time instead. AQHI publishes hourly, so a newest
+ * reading beyond two hours means at least one publication was missed and the
+ * feed should not be described as live.
+ */
+export const STALE_AFTER_MS = 2 * 60 * 60 * 1000;
+
+/**
+ * The newest observation time across a set of readings, or null when empty.
+ * @param {Array<object>} readings
+ * @returns {number|null} Epoch ms.
+ */
+export function newestObservation(readings) {
+  if (!Array.isArray(readings) || readings.length === 0) return null;
+  let newest = null;
+  for (const reading of readings) {
+    const at = Number(reading?.observedMs);
+    if (Number.isFinite(at) && (newest === null || at > newest)) newest = at;
+  }
+  return newest;
+}
+
+/**
+ * Is a set of readings stale, judged on source observation time? An empty
+ * set is stale: a refresh that kept no current observation has nothing live.
+ * @param {Array<object>} readings
+ * @param {number} [now=Date.now()]
+ * @returns {boolean}
+ */
+export function readingsAreStale(readings, now = Date.now()) {
+  const newest = newestObservation(readings);
+  // No current observation at all — every row was dropped as too old or
+  // unusable — is the stalest a feed can be, not a nominal one.
+  if (newest === null) return true;
+  return now - newest > STALE_AFTER_MS;
+}
+
+/**
+ * Registered provider descriptors. `coverage` is stated plainly because the
+ * layer is not global and the row must say so.
+ */
+export const AIR_QUALITY_PROVIDERS = Object.freeze({
+  eccc: Object.freeze({
+    id: 'eccc',
+    scale: 'AQHI',
+    label: msg('Air quality'),
+    network: 'Environment and Climate Change Canada',
+    coverage: msg('Canada only · ECCC AQHI network'),
+    /** ECCC's published band thresholds, evaluated in order. */
+    bands: Object.freeze([
+      Object.freeze({ id: 'low', max: 3 }),
+      Object.freeze({ id: 'moderate', max: 6 }),
+      Object.freeze({ id: 'high', max: 10 }),
+      Object.freeze({ id: 'very-high', max: Infinity }),
+    ]),
+  }),
+});
+
+/** Band descriptor for an id, or null. */
+export function airQualityBandById(bandId) {
+  return BAND_BY_ID.get(String(bandId ?? '')) || null;
+}
+
+/** Accent colour for a band id, falling back to neutral grey. */
+export function airQualityColor(bandId) {
+  return airQualityBandById(bandId)?.color || AIR_QUALITY_UNKNOWN_COLOR;
+}
+
+/**
+ * The published AQHI value for a raw ECCC reading: an integer from 1 up.
+ *
+ * ECCC reports whole numbers with a floor of 1 — there is no "AQHI 0" and no
+ * "AQHI 1.08". A raw value below 1 is a legitimate low reading, not an error,
+ * and is published as 1.
+ *
+ * @param {number|string|null|undefined} raw - Raw `aqhi` value from the API.
+ * @returns {number|null} Published integer AQHI, or null when unusable.
+ */
+export function aqhiDisplayValue(raw) {
+  // Guard the empty forms BEFORE coercing: Number(null) and Number('') are both
+  // 0, which would otherwise floor to a confident "AQHI 1" for a station that
+  // reported nothing at all.
+  if (raw === null || raw === undefined || raw === '') return null;
+  if (typeof raw !== 'number' && typeof raw !== 'string') return null;
+  if (typeof raw === 'string' && raw.trim() === '') return null;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) return null;
+  return Math.max(1, Math.round(value));
+}
+
+/**
+ * The band id for a value on a provider's scale.
+ * @param {string} providerId
+ * @param {number|null} value - Already in the provider's published form.
+ * @returns {string|null}
+ */
+export function bandForValue(providerId, value) {
+  const provider = AIR_QUALITY_PROVIDERS[String(providerId ?? '')];
+  if (!provider || !Number.isFinite(value)) return null;
+  return provider.bands.find((band) => value <= band.max)?.id ?? null;
+}
+
+/**
+ * Display text for a value on a provider's scale.
+ * AQHI collapses everything above ten into the open-ended "10+".
+ * @param {string} providerId
+ * @param {number|null} value
+ * @returns {string}
+ */
+export function valueLabel(providerId, value) {
+  if (!Number.isFinite(value)) return '--';
+  if (providerId === 'eccc') return value > 10 ? '10+' : String(value);
+  return String(value);
+}
+
+/** Plain-language risk phrase for a band id. */
+export function bandRiskText(bandId) {
+  return airQualityBandById(bandId)?.risk ?? null;
+}
+
+/**
+ * Validate a station FeatureCollection into an id-keyed catalog.
+ *
+ * Atomic: a structurally broken response returns null so the caller keeps its
+ * last good catalog. A station missing coordinates is skipped, since one
+ * unusable station is not evidence the catalog is broken.
+ *
+ * @param {object} geojson - GeoJSON FeatureCollection from `aqhi-stations`.
+ * @returns {Map<string, object>|null} Stations by location_id, or null.
+ */
+export function normalizeAqhiStations(geojson) {
+  if (!Array.isArray(geojson?.features)) return null;
+  const stations = new Map();
+  for (const feature of geojson.features) {
+    const properties = feature?.properties;
+    if (
+      !properties ||
+      typeof properties !== 'object' ||
+      Array.isArray(properties)
+    )
+      return null;
+    const coordinates = feature?.geometry?.coordinates;
+    if (!Array.isArray(coordinates) || coordinates.length < 2) continue;
+    const [lon, lat] = coordinates.map(Number);
+    if (!Number.isFinite(lon) || !Number.isFinite(lat)) continue;
+    if (Math.abs(lat) > 90 || Math.abs(lon) > 180) return null;
+    const id = String(properties.location_id ?? feature.id ?? '').trim();
+    if (!id) continue;
+    stations.set(id, {
+      id,
+      name: String(properties.location_name_en || id).trim(),
+      // ECCC's administrative zone: atl, que, ont, pnr, pyr.
+      zone: String(properties['eccc_administrative-zone'] || '').trim(),
+      lat,
+      lon,
+    });
+  }
+  return stations;
+}
+
+/**
+ * Join latest ECCC observations onto known stations into provider-shaped rows.
+ *
+ * The catalog is the only thing that supplies a reading its coordinates, so an
+ * observation without a matching station cannot be placed and is dropped.
+ * Readings older than OBSERVATION_MAX_AGE_MS are dropped too — a six-hour-old
+ * air-quality number presented as current is worse than no number.
+ *
+ * @param {object} geojson - FeatureCollection from `aqhi-observations-realtime`.
+ * @param {Map<string, object>} stations - Known stations by location_id.
+ * @param {number} [now=Date.now()] - Clock seam for tests.
+ * @returns {Array<object>|null} Normalized readings, or null when malformed.
+ */
+export function normalizeAqhiObservations(geojson, stations, now = Date.now()) {
+  if (!Array.isArray(geojson?.features)) return null;
+  if (!(stations instanceof Map)) return null;
+  const provider = AIR_QUALITY_PROVIDERS.eccc;
+  const newest = new Map();
+  for (const feature of geojson.features) {
+    const properties = feature?.properties;
+    if (
+      !properties ||
+      typeof properties !== 'object' ||
+      Array.isArray(properties)
+    )
+      return null;
+    const stationId = String(properties.location_id ?? '').trim();
+    const station = stations.get(stationId);
+    if (!station) continue;
+
+    const value = aqhiDisplayValue(properties.aqhi);
+    if (value === null) continue;
+    const observedMs = Date.parse(properties.observation_datetime);
+    if (!Number.isFinite(observedMs)) continue;
+    if (now - observedMs > OBSERVATION_MAX_AGE_MS) continue;
+
+    const previous = newest.get(stationId);
+    if (previous && previous.observedMs >= observedMs) continue;
+    const band = bandForValue(provider.id, value);
+    newest.set(stationId, {
+      id: `${provider.id}:${stationId}`,
+      provider: provider.id,
+      scale: provider.scale,
+      value,
+      band,
+      stationId,
+      name: station.name,
+      zone: station.zone,
+      lat: station.lat,
+      lon: station.lon,
+      observedMs,
+      color: airQualityColor(band),
+      label: valueLabel(provider.id, value),
+      risk: bandRiskText(band),
+      note: String(properties.special_notes_en || '').trim() || null,
+    });
+  }
+  return [...newest.values()].sort(
+    (a, b) => b.value - a.value || a.stationId.localeCompare(b.stationId),
+  );
+}
+
+/**
+ * Build the source-owned presentation for one station label.
+ * @param {object} input
+ * @returns {object}
+ */
+export function createAirQualityOverlayEntry({
+  id,
+  position,
+  title,
+  accent,
+  value,
+}) {
+  return {
+    id: String(id),
+    position,
+    variant: 'label',
+    title,
+    accent,
+    // Worse air wins the label budget — the reading people need to see first.
+    priority: Math.round(Number(value) || 0) * 1000,
+    collisionGroup: 'ambient-label',
+    paintLane: 'ambient-label',
+    interactive: false,
+    edgeFade: 'keyhole',
+    horizonCull: true,
+    terrainOcclusion: false,
+    gapPx: 14,
+    verticalOnly: true,
+    placement: 'above',
+  };
+}
+
+/** Keep the worst readings, with stable identity as the tie-break. */
+export function selectAirQualityOverlayCohort(
+  entries,
+  limit = AIR_QUALITY_OVERLAY_COHORT_LIMIT,
+) {
+  const cap = Math.max(
+    0,
+    Math.min(AIR_QUALITY_OVERLAY_COHORT_LIMIT, Math.floor(Number(limit) || 0)),
+  );
+  if (!Array.isArray(entries) || cap === 0) return [];
+  return entries
+    .slice()
+    .sort(
+      (a, b) =>
+        b.priority - a.priority || String(a.id).localeCompare(String(b.id)),
+    )
+    .slice(0, cap);
+}
+
+/**
+ * The worst readings inside a lon/lat rectangle, for the readout card.
+ *
+ * A null rectangle means the camera could not resolve one (a fully oblique or
+ * space-level view); everything is then in scope rather than nothing, so the
+ * card degrades to the worst readings overall instead of going blank.
+ *
+ * @param {Array<object>} readings
+ * @param {?{west:number, south:number, east:number, north:number}} rect - Degrees.
+ * @param {number} [limit=5]
+ * @returns {Array<object>}
+ */
+export function readingsInView(readings, rect, limit = 5) {
+  if (!Array.isArray(readings)) return [];
+  const cap = Math.max(0, Math.floor(Number(limit) || 0));
+  if (cap === 0) return [];
+  const inside = !rect
+    ? readings
+    : readings.filter((reading) => {
+        if (reading.lat < rect.south || reading.lat > rect.north) return false;
+        // A rectangle crossing the antimeridian has west > east.
+        return rect.west <= rect.east
+          ? reading.lon >= rect.west && reading.lon <= rect.east
+          : reading.lon >= rect.west || reading.lon <= rect.east;
+      });
+  return inside
+    .slice()
+    .sort((a, b) => b.value - a.value || a.stationId.localeCompare(b.stationId))
+    .slice(0, cap);
+}
+
+/**
+ * Map one reading to a JSON-safe analyst record. Pure — no Cesium types.
+ * @param {object|null|undefined} raw
+ * @param {number} [index=0]
+ * @returns {object}
+ */
+export function mapAnalystRecord(raw, index = 0) {
+  const num = (v) => (Number.isFinite(v) ? v : null);
+  const text = (v) => {
+    const t = String(v ?? '').trim();
+    return t || null;
+  };
+  return {
+    id: text(raw?.id) || `AIR-${String(index).padStart(4, '0')}`,
+    provider: text(raw?.provider),
+    scale: text(raw?.scale),
+    value: num(raw?.value),
+    band: text(raw?.band),
+    name: text(raw?.name),
+    zone: text(raw?.zone),
+    risk: text(raw?.risk),
+    lat: num(raw?.lat),
+    lon: num(raw?.lon),
+    observedMs: num(raw?.observedMs),
+  };
+}

src/layers/airQuality/model.test.mjs

@@ -0,0 +1,269 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  AIR_QUALITY_BANDS,
+  AIR_QUALITY_PROVIDERS,
+  AIR_QUALITY_UNKNOWN_COLOR,
+  OBSERVATION_MAX_AGE_MS,
+  STALE_AFTER_MS,
+  airQualityColor,
+  aqhiDisplayValue,
+  bandForValue,
+  bandRiskText,
+  mapAnalystRecord,
+  normalizeAqhiObservations,
+  normalizeAqhiStations,
+  readingsAreStale,
+  readingsInView,
+  selectAirQualityOverlayCohort,
+  valueLabel,
+} from './model.js';
+
+const NOW = Date.parse('2026-09-24T18:30:00Z');
+const RECENT = '2026-09-24T18:00:00Z';
+const collection = (features) => ({ type: 'FeatureCollection', features });
+const station = (id, name, zone, lon, lat) => ({
+  type: 'Feature',
+  geometry: { type: 'Point', coordinates: [lon, lat] },
+  properties: {
+    location_id: id,
+    location_name_en: name,
+    'eccc_administrative-zone': zone,
+  },
+});
+const observation = (id, aqhi, when = RECENT) => ({
+  type: 'Feature',
+  properties: { location_id: id, aqhi, observation_datetime: when },
+});
+
+const STATIONS = collection([
+  station('IAKID', 'Calgary', 'pnr', -114.0575, 51.0458),
+  station('OAAAA', 'Toronto', 'ont', -79.3832, 43.6532),
+  station('AAAAA', 'Halifax', 'atl', -63.5752, 44.6488),
+]);
+
+// ── provider-shaped records ────────────────────────────────────────────────
+
+test('readings carry the provider-neutral {provider, scale, value, band} shape', () => {
+  // Indices are not interchangeable numbers: AQHI is 1-10+ on health risk,
+  // US AQI is 0-500 on concentration. The shape names which index a value is on
+  // so a second network can be added without inventing a shared meaning.
+  const stations = normalizeAqhiStations(STATIONS);
+  const [row] = normalizeAqhiObservations(
+    collection([observation('IAKID', 2.32)]),
+    stations,
+    NOW,
+  );
+  assert.equal(row.provider, 'eccc');
+  assert.equal(row.scale, 'AQHI');
+  assert.equal(row.value, 2);
+  assert.equal(row.band, 'low');
+});
+
+test('bands map from a value on a named provider scale', () => {
+  assert.equal(bandForValue('eccc', 1), 'low');
+  assert.equal(bandForValue('eccc', 3), 'low');
+  assert.equal(bandForValue('eccc', 4), 'moderate');
+  assert.equal(bandForValue('eccc', 7), 'high');
+  assert.equal(bandForValue('eccc', 11), 'very-high');
+  // An unregistered provider cannot be banded rather than being guessed at.
+  assert.equal(bandForValue('unknown-network', 5), null);
+  assert.equal(bandForValue('eccc', null), null);
+});
+
+test('the provider states its coverage plainly', () => {
+  assert.match(AIR_QUALITY_PROVIDERS.eccc.coverage, /Canada only/);
+  assert.equal(AIR_QUALITY_PROVIDERS.eccc.scale, 'AQHI');
+});
+
+test("values above ten collapse to the scale's open-ended label", () => {
+  assert.equal(valueLabel('eccc', 10), '10');
+  assert.equal(valueLabel('eccc', 11), '10+');
+  assert.equal(valueLabel('eccc', null), '--');
+});
+
+test('every band has a distinct colour, and an unknown band is neutral', () => {
+  const colors = AIR_QUALITY_BANDS.map((b) => b.color);
+  assert.equal(new Set(colors).size, colors.length);
+  assert.equal(airQualityColor('nonsense'), AIR_QUALITY_UNKNOWN_COLOR);
+  assert.equal(bandRiskText('high'), 'High health risk');
+  assert.equal(bandRiskText(null), null);
+});
+
+// ── published form ─────────────────────────────────────────────────────────
+
+test('AQHI rounds to the published integer form and floors at 1', () => {
+  assert.equal(aqhiDisplayValue(1.08), 1);
+  assert.equal(aqhiDisplayValue(3.5), 4);
+  assert.equal(aqhiDisplayValue(0), 1);
+  assert.equal(aqhiDisplayValue('3'), 3);
+});
+
+test('an absent reading never becomes a confident AQHI 1', () => {
+  // Number(null) and Number('') are both 0, which would floor to 1.
+  for (const empty of [null, undefined, '', '   ', NaN, true, {}, [], -1]) {
+    assert.equal(aqhiDisplayValue(empty), null, `${JSON.stringify(empty)}`);
+  }
+});
+
+// ── snapshot validation ────────────────────────────────────────────────────
+
+test('stations normalize into an id-keyed catalog carrying their zone', () => {
+  const stations = normalizeAqhiStations(STATIONS);
+  assert.equal(stations.size, 3);
+  assert.equal(stations.get('OAAAA').zone, 'ont');
+});
+
+test('malformed payloads are rejected atomically', () => {
+  assert.equal(normalizeAqhiStations(null), null);
+  assert.equal(normalizeAqhiStations(collection([{ properties: null }])), null);
+  const stations = normalizeAqhiStations(STATIONS);
+  assert.equal(normalizeAqhiObservations(null, stations, NOW), null);
+  assert.equal(
+    normalizeAqhiObservations(collection([]), 'not a map', NOW),
+    null,
+  );
+});
+
+test('an observation with no matching station is dropped', () => {
+  const stations = normalizeAqhiStations(STATIONS);
+  const rows = normalizeAqhiObservations(
+    collection([observation('IAKID', 2), observation('ZZZZZ', 9)]),
+    stations,
+    NOW,
+  );
+  assert.equal(rows.length, 1);
+});
+
+test('a stale reading is dropped rather than shown as current', () => {
+  const stations = normalizeAqhiStations(STATIONS);
+  const old = new Date(NOW - OBSERVATION_MAX_AGE_MS - 60_000).toISOString();
+  const rows = normalizeAqhiObservations(
+    collection([observation('IAKID', 3, old), observation('OAAAA', 4)]),
+    stations,
+    NOW,
+  );
+  assert.deepEqual(
+    rows.map((r) => r.stationId),
+    ['OAAAA'],
+  );
+});
+
+test('a snapshot whose every observation was too old is stale, not nominal', () => {
+  const stations = normalizeAqhiStations(STATIONS);
+  const old = new Date(NOW - OBSERVATION_MAX_AGE_MS - 60_000).toISOString();
+  const rows = normalizeAqhiObservations(
+    collection([observation('IAKID', 3, old), observation('OAAAA', 4, old)]),
+    stations,
+    NOW,
+  );
+  assert.deepEqual(rows, []);
+  assert.equal(readingsAreStale(rows, NOW), true);
+  assert.equal(readingsAreStale([{ observedMs: NOW - 60_000 }], NOW), false);
+  assert.equal(
+    readingsAreStale([{ observedMs: NOW - STALE_AFTER_MS - 1 }], NOW),
+    true,
+  );
+});
+
+test('the newest reading per station wins and worst air sorts first', () => {
+  const stations = normalizeAqhiStations(STATIONS);
+  const rows = normalizeAqhiObservations(
+    collection([
+      observation('IAKID', 3, '2026-09-24T16:00:00Z'),
+      observation('IAKID', 7, '2026-09-24T18:00:00Z'),
+      observation('OAAAA', 5),
+    ]),
+    stations,
+    NOW,
+  );
+  assert.deepEqual(
+    rows.map((r) => r.value),
+    [7, 5],
+  );
+});
+
+// ── readout selection ──────────────────────────────────────────────────────
+
+const reading = (id, value, lat, lon) => ({
+  id,
+  stationId: id,
+  value,
+  lat,
+  lon,
+  name: id,
+});
+
+test('the readout lists the worst readings inside the view rectangle', () => {
+  const rows = [
+    reading('west', 9, 51.0, -114.0),
+    reading('east', 4, 43.6, -79.3),
+    reading('mild', 2, 51.1, -114.1),
+  ];
+  const inView = readingsInView(
+    rows,
+    { west: -115, south: 50, east: -113, north: 52 },
+    5,
+  );
+  assert.deepEqual(
+    inView.map((r) => r.id),
+    ['west', 'mild'],
+  );
+});
+
+test('an unresolvable view rectangle degrades to the worst overall, not to blank', () => {
+  // A space-level or fully oblique camera cannot produce a rectangle; the card
+  // should still say something useful.
+  const rows = [reading('a', 3, 0, 0), reading('b', 8, 10, 10)];
+  assert.deepEqual(
+    readingsInView(rows, null, 5).map((r) => r.id),
+    ['b', 'a'],
+  );
+  assert.deepEqual(readingsInView(rows, null, 0), []);
+  assert.deepEqual(readingsInView(null, null, 5), []);
+});
+
+test('a view rectangle crossing the antimeridian still selects correctly', () => {
+  // west > east is how a dateline-crossing rectangle is expressed.
+  const rows = [reading('near', 5, 0, 179), reading('far', 9, 0, 100)];
+  const inView = readingsInView(
+    rows,
+    { west: 170, south: -10, east: -170, north: 10 },
+    5,
+  );
+  assert.deepEqual(
+    inView.map((r) => r.id),
+    ['near'],
+  );
+});
+
+test('the overlay cohort is capped and deterministic', () => {
+  const entries = Array.from({ length: 120 }, (_, i) => ({
+    id: `s${i}`,
+    priority: i % 11,
+  }));
+  const cohort = selectAirQualityOverlayCohort(entries);
+  assert.ok(cohort.length <= 48);
+  assert.deepEqual(
+    cohort.map((e) => e.id),
+    selectAirQualityOverlayCohort(entries).map((e) => e.id),
+  );
+});
+
+test('analyst records are JSON-safe and name the provider and scale', () => {
+  const stations = normalizeAqhiStations(STATIONS);
+  const [row] = normalizeAqhiObservations(
+    collection([observation('IAKID', 2)]),
+    stations,
+    NOW,
+  );
+  const record = mapAnalystRecord(row, 0);
+  assert.deepEqual(JSON.parse(JSON.stringify(record)), record);
+  assert.equal(record.provider, 'eccc');
+  assert.equal(record.scale, 'AQHI');
+  const empty = mapAnalystRecord(undefined, 7);
+  assert.equal(empty.id, 'AIR-0007');
+  for (const [key, value] of Object.entries(empty)) {
+    assert.notEqual(value, undefined, `${key} must not be undefined`);
+  }
+});

src/layers/airQuality/ownership.test.mjs

@@ -0,0 +1,275 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAirQualityLayer } from './index.js';
+import { layerFeedState } from '../../data/feedState.js';
+import { STALE_AFTER_MS } from './model.js';
+
+function harness(source) {
+  const sources = [];
+  const events = [];
+  const viewer = {
+    dataSources: {
+      add(value) {
+        sources.push(value);
+      },
+      remove(value) {
+        sources.splice(sources.indexOf(value), 1);
+      },
+    },
+  };
+  const layer = createAirQualityLayer({
+    source,
+    overlayHost: {
+      setEntries(...args) {
+        events.push(args);
+      },
+      setVisible() {},
+      clearSource() {},
+    },
+  });
+  layer.init(viewer);
+  layer.enable(viewer);
+  return { layer, viewer, sources, events };
+}
+
+const reading = (id, value, overrides = {}) => ({
+  id: `eccc:${id}`,
+  provider: 'eccc',
+  scale: 'AQHI',
+  value,
+  band: 'low',
+  stationId: id,
+  name: id,
+  zone: 'ont',
+  lat: 43.65,
+  lon: -79.38,
+  observedMs: 1_700_000_000_000,
+  color: '#4cc9f0',
+  label: String(value),
+  risk: 'Low health risk',
+  note: null,
+  ...overrides,
+});
+
+const staticSource = (rows) => ({ getSnapshot: async () => rows });
+
+test('a layer requires both a snapshot source and an overlay host', () => {
+  assert.throws(() => createAirQualityLayer(), /snapshot source/);
+  assert.throws(
+    () => createAirQualityLayer({ source: staticSource([]) }),
+    /overlay host/,
+  );
+});
+
+test('initialization is single-use and owns exactly one data source', () => {
+  const { layer, viewer, sources } = harness(staticSource([]));
+  assert.equal(sources.length, 1);
+  assert.throws(() => layer.init(viewer), /already initialized/);
+  layer.destroy(viewer);
+  assert.equal(sources.length, 0);
+});
+
+test('a refresh renders readings and publishes an overlay cohort', async () => {
+  const { layer, events } = harness(
+    staticSource([reading('A', 2), reading('B', 7)]),
+  );
+  assert.equal(await layer.update(), true);
+  assert.equal(layer.getStats().count, 2);
+  assert.equal(layer.getStats().error, null);
+  assert.equal(events.at(-1)[0], 'air-quality');
+});
+
+// ── the abort + enabled guard ──────────────────────────────────────────────
+
+test('a response landing after disable cannot redraw the scene', async () => {
+  // The failure this prevents: disable() clears the overlay, then an in-flight
+  // response resolves and repopulates it behind the user's back.
+  let release;
+  const gate = new Promise((resolve) => {
+    release = resolve;
+  });
+  const { layer, events } = harness({
+    getSnapshot: async ({ signal } = {}) => {
+      await gate;
+      signal?.throwIfAborted();
+      return [reading('A', 5)];
+    },
+  });
+  const pending = layer.update();
+  layer.disable();
+  const publishedBefore = events.length;
+  release();
+  assert.equal(await pending, false, 'a late response must not be applied');
+  assert.equal(
+    events.length,
+    publishedBefore,
+    'no overlay write after disable',
+  );
+  assert.equal(layer.getStats().count, 0);
+});
+
+test('disable aborts the request in flight', async () => {
+  let seenSignal = null;
+  const { layer } = harness({
+    getSnapshot: async ({ signal } = {}) => {
+      seenSignal = signal;
+      await new Promise((resolve) => setTimeout(resolve, 40));
+      signal?.throwIfAborted();
+      return [];
+    },
+  });
+  const pending = layer.update();
+  layer.disable();
+  await pending;
+  assert.ok(seenSignal, 'a signal was passed through to the source');
+  assert.equal(seenSignal.aborted, true);
+});
+
+test('a superseded refresh does not clobber the newer one', async () => {
+  let call = 0;
+  const { layer } = harness({
+    getSnapshot: async ({ signal } = {}) => {
+      call += 1;
+      const mine = call;
+      await new Promise((resolve) => setTimeout(resolve, mine === 1 ? 40 : 1));
+      signal?.throwIfAborted();
+      return [reading(`call-${mine}`, mine)];
+    },
+  });
+  const first = layer.update();
+  const second = layer.update();
+  const [firstResult, secondResult] = await Promise.all([first, second]);
+  assert.equal(firstResult, false, 'the superseded call reports no update');
+  assert.equal(secondResult, true);
+  assert.equal(layer.getAnalystRecords()[0].name, 'call-2');
+});
+
+test('update is a no-op while the layer is disabled', async () => {
+  const { layer } = harness(staticSource([reading('A', 2)]));
+  layer.disable();
+  assert.equal(await layer.update(), false);
+  assert.equal(layer.getStats().count, 0);
+});
+
+// ── readout descriptor ─────────────────────────────────────────────────────
+
+test('the readout descriptor carries the band legend and coverage', async () => {
+  const { layer } = harness(staticSource([reading('A', 2), reading('B', 9)]));
+  await layer.update();
+  const controls = layer.getRowControls();
+  assert.equal(controls.readout, true);
+  assert.match(controls.summary.coverage, /Canada only/);
+  // The Weather panel's legend shape: one {color, label} per band.
+  assert.equal(controls.legendCategorical, true);
+  assert.deepEqual(
+    controls.legend.map((entry) => entry.label),
+    ['Low', 'Moderate', 'High', 'Very High'],
+  );
+  assert.ok(
+    controls.legend.every((entry) => /^#[0-9a-f]{6}$/i.test(entry.color)),
+  );
+  // Worst first, and every item keyed.
+  assert.deepEqual(
+    controls.list.items.map((i) => i.text),
+    ['B · Low health risk', 'A · Low health risk'],
+  );
+  assert.ok(controls.list.items.every((i) => i.id));
+  assert.match(controls.summary.status, /2 stations reporting/);
+});
+
+test('the readout reports an error rather than a silent empty card', async () => {
+  const { layer } = harness({
+    getSnapshot: async () => {
+      throw new Error('ECCC HTTP 503');
+    },
+  });
+  await layer.update();
+  assert.match(layer.getRowControls().summary.status, /503/);
+});
+
+test('row-control listeners are notified on refresh and teardown-safe', async () => {
+  const { layer, viewer } = harness(staticSource([reading('A', 2)]));
+  let calls = 0;
+  layer.setRowControlsListener(() => {
+    calls += 1;
+  });
+  await layer.update();
+  assert.ok(calls >= 1, 'a refresh notifies the card');
+  layer.destroy(viewer);
+  const after = calls;
+  layer.setRowControlsListener(() => {
+    calls += 1;
+  });
+  assert.equal(calls, after);
+});
+
+// ── feed-state honesty ─────────────────────────────────────────────────────
+
+test('freshness is judged on observation time, not on when we last fetched', async () => {
+  // lastUpdate stays current every time the network answers, even when it
+  // answers with nothing new. Judging freshness on it would let the HUD and
+  // voice describe hours-old air quality as live.
+  const aged = Date.now() - STALE_AFTER_MS - 60_000;
+  const { layer } = harness(
+    staticSource([reading('A', 2, { observedMs: aged })]),
+  );
+  await layer.update();
+  const stats = layer.getStats();
+  assert.ok(
+    stats.lastUpdate >= Date.now() - 5_000,
+    'we did just receive a response',
+  );
+  assert.equal(stats.observedAt, aged, 'but the observation itself is old');
+  assert.equal(stats.stale, true);
+  assert.equal(
+    layerFeedState(stats),
+    'stale',
+    'provenance must not read this as nominal',
+  );
+});
+
+test('a current reading reports nominal', async () => {
+  const { layer } = harness(
+    staticSource([reading('A', 2, { observedMs: Date.now() - 10 * 60_000 })]),
+  );
+  await layer.update();
+  const stats = layer.getStats();
+  assert.equal(stats.stale, false);
+  assert.equal(layerFeedState(stats), 'nominal');
+});
+
+test('a refresh that kept no current observation reports stale, not nominal', async () => {
+  // Every observation older than OBSERVATION_MAX_AGE_MS is dropped, so a feed
+  // that only has hours-old rows yields an empty snapshot. That is the
+  // stalest a feed can be; it must not read as a healthy empty layer.
+  const { layer } = harness(staticSource([]));
+  assert.equal(layer.getStats().stale, false, 'no refresh yet, no verdict');
+  await layer.update();
+  const stats = layer.getStats();
+  assert.equal(stats.count, 0);
+  assert.equal(stats.observedAt, null);
+  assert.equal(stats.stale, true);
+  assert.equal(layerFeedState(stats), 'stale');
+  assert.equal(layer.getRowControls().summary.status, 'No current readings');
+});
+
+test('a failed refresh over good readings reports degraded, not nominal', async () => {
+  let fail = false;
+  const { layer } = harness({
+    getSnapshot: async () => {
+      if (fail) throw new Error('ECCC HTTP 503');
+      return [reading('A', 2, { observedMs: Date.now() - 10 * 60_000 })];
+    },
+  });
+  await layer.update();
+  assert.equal(layerFeedState(layer.getStats()), 'nominal');
+  fail = true;
+  await layer.update();
+  const stats = layer.getStats();
+  assert.ok(stats.count > 0, 'the previous readings are still displayed');
+  assert.equal(
+    layerFeedState(stats),
+    'degraded',
+    'showing old data after a failure is degraded',
+  );
+});

src/layers/airQuality/source.js

@@ -0,0 +1,110 @@
+import { readResponseJsonCapped } from '../../sources/httpBody.js';
+import { normalizeAqhiStations, normalizeAqhiObservations } from './model.js';
+
+// A portable export (package.json): no i18n here. Failures stay English data;
+// the Layers panel and the Weather card show them translated.
+const msg = (text) => text;
+
+const COLLECTIONS_ROOT = 'https://api.weather.gc.ca/collections';
+const STATIONS_URL = `${COLLECTIONS_ROOT}/aqhi-stations/items`;
+const OBSERVATIONS_URL = `${COLLECTIONS_ROOT}/aqhi-observations-realtime/items`;
+
+/** Comfortably above Canada's ~134 stations without inviting a huge page. */
+const STATION_LIMIT = 500;
+const OBSERVATION_LIMIT = 500;
+/** Station geometry is near-static — a few changes a year. Refetch twice a day. */
+const STATION_TTL_MS = 12 * 60 * 60 * 1000;
+/** A full 500-row GeoJSON page is a few hundred KB; anything past this is not a page. */
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Request and validate a complete ECCC AQHI snapshot before it can replace
+ * displayed readings. The first registered air-quality provider.
+ *
+ * Two collections are involved. `aqhi-stations` is the catalog — it supplies
+ * every reading its coordinates and is cached for twelve hours because it
+ * barely changes. `aqhi-observations-realtime` is the hourly reading feed,
+ * requested with `latest=true` so the response is current values rather than
+ * the full observation history, which is roughly 2,000 rows nationally.
+ *
+ * The station catalog is only replaced when a refresh actually returns
+ * stations, so a transient empty response cannot blank the layer.
+ *
+ * @param {object} [options]
+ * @param {Function} [options.fetchImpl] - Injected fetch, for tests.
+ * @param {() => number} [options.now] - Clock seam, for tests.
+ * @param {number} [options.timeoutMs=15000] - Deadline for each request.
+ * @returns {{getSnapshot: Function}}
+ */
+export function createEcccAirQualitySource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+  timeoutMs = 15_000,
+} = {}) {
+  /** @type {Map<string, object>} */
+  let stations = new Map();
+  let stationsFetchedAt = 0;
+
+  /** One bounded GeoJSON page: deadline, caller abort, byte cap, row cap. */
+  const getJson = async (url, limit, signal) => {
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal.reason);
+    signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(
+      () => controller.abort(new Error(msg('ECCC request timed out'))),
+      timeoutMs,
+    );
+    try {
+      signal?.throwIfAborted();
+      const response = await fetchImpl(url, {
+        headers: { Accept: 'application/json' },
+        signal: controller.signal,
+      });
+      if (!response.ok) throw new Error(`ECCC HTTP ${response.status}`);
+      const payload = await readResponseJsonCapped(
+        response,
+        MAX_RESPONSE_BYTES,
+        controller.signal,
+      );
+      // The server's `limit` is a request, not a guarantee.
+      if (Array.isArray(payload?.features) && payload.features.length > limit)
+        return { ...payload, features: payload.features.slice(0, limit) };
+      return payload;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+    }
+  };
+
+  return {
+    async getSnapshot({ signal } = {}) {
+      const clock = now();
+      if (stations.size === 0 || clock - stationsFetchedAt > STATION_TTL_MS) {
+        const payload = await getJson(
+          `${STATIONS_URL}?f=json&limit=${STATION_LIMIT}`,
+          STATION_LIMIT,
+          signal,
+        );
+        const next = normalizeAqhiStations(payload);
+        if (!next) throw new Error(msg('Malformed AQHI station response'));
+        // An empty refresh must not wipe a good catalog.
+        if (next.size > 0) {
+          stations = next;
+          stationsFetchedAt = clock;
+        }
+      }
+      if (stations.size === 0)
+        throw new Error(msg('No AQHI stations available'));
+
+      const payload = await getJson(
+        `${OBSERVATIONS_URL}?f=json&latest=true&limit=${OBSERVATION_LIMIT}`,
+        OBSERVATION_LIMIT,
+        signal,
+      );
+      const readings = normalizeAqhiObservations(payload, stations, clock);
+      if (!readings)
+        throw new Error(msg('Malformed AQHI observation response'));
+      return readings;
+    },
+  };
+}

src/layers/airQuality/source.test.mjs

@@ -0,0 +1,197 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createEcccAirQualitySource } from './source.js';
+
+const NOW = Date.parse('2026-09-24T18:30:00Z');
+const HOUR = 60 * 60 * 1000;
+const station = (id) => ({
+  type: 'Feature',
+  geometry: { type: 'Point', coordinates: [-79.38, 43.65] },
+  properties: { location_id: id, location_name_en: id },
+});
+const observation = (id, at = NOW, aqhi = 3) => ({
+  type: 'Feature',
+  properties: {
+    location_id: id,
+    aqhi,
+    observation_datetime: new Date(at - 10 * 60_000).toISOString(),
+  },
+});
+const json = (body, init) =>
+  new Response(JSON.stringify(body), {
+    headers: { 'content-type': 'application/json' },
+    ...init,
+  });
+
+/** A fetch that serves the station catalog and observations from mutable state. */
+function feed() {
+  const state = {
+    clock: NOW,
+    stations: [station('A')],
+    stationIds: null,
+    urls: [],
+  };
+  state.source = createEcccAirQualitySource({
+    now: () => state.clock,
+    fetchImpl: async (url) => {
+      state.urls.push(url);
+      return json({
+        type: 'FeatureCollection',
+        // Every known station reports ten minutes before the current clock.
+        features: url.includes('aqhi-stations')
+          ? state.stations
+          : (state.stationIds || ['A']).map((id) =>
+              observation(id, state.clock),
+            ),
+      });
+    },
+  });
+  state.stationRequests = () =>
+    state.urls.filter((url) => url.includes('aqhi-stations')).length;
+  return state;
+}
+
+test('the station catalog is cached for twelve hours, then refetched', async () => {
+  const state = feed();
+  await state.source.getSnapshot();
+  state.clock = NOW + 12 * HOUR;
+  await state.source.getSnapshot();
+  assert.equal(state.stationRequests(), 1, 'within the TTL the cache serves');
+  state.clock = NOW + 12 * HOUR + 1;
+  await state.source.getSnapshot();
+  assert.equal(
+    state.stationRequests(),
+    2,
+    'past the TTL the catalog refreshes',
+  );
+});
+
+test('an empty catalog refresh keeps the previous catalog', async () => {
+  const state = feed();
+  await state.source.getSnapshot();
+  state.stations = [];
+  state.clock = NOW + 13 * HOUR;
+  const readings = await state.source.getSnapshot();
+  assert.deepEqual(
+    readings.map((reading) => reading.stationId),
+    ['A'],
+  );
+  // The empty refresh did not count as fresh, so the next call retries it.
+  await state.source.getSnapshot();
+  assert.equal(state.stationRequests(), 3);
+});
+
+test('an empty first catalog is an error, not an empty layer', async () => {
+  const state = feed();
+  state.stations = [];
+  await assert.rejects(state.source.getSnapshot(), /No AQHI stations/);
+});
+
+test('requests ask for JSON, the latest observations only, and a bounded page', async () => {
+  const state = feed();
+  await state.source.getSnapshot();
+  const [stations, observations] = state.urls.map((url) => new URL(url));
+  assert.equal(stations.pathname, '/collections/aqhi-stations/items');
+  assert.equal(stations.searchParams.get('f'), 'json');
+  assert.equal(stations.searchParams.get('limit'), '500');
+  assert.equal(
+    observations.pathname,
+    '/collections/aqhi-observations-realtime/items',
+  );
+  // Without latest=true the collection returns the full history (~2,000 rows).
+  assert.equal(observations.searchParams.get('latest'), 'true');
+  assert.equal(observations.searchParams.get('limit'), '500');
+});
+
+test('rows past the requested limit are ignored', async () => {
+  const state = feed();
+  state.stations = Array.from({ length: 600 }, (_, index) =>
+    station(`S${String(index).padStart(3, '0')}`),
+  );
+  state.stationIds = state.stations.map((row) => row.properties.location_id);
+  const readings = await state.source.getSnapshot();
+  assert.equal(readings.length, 500);
+});
+
+test('a malformed catalog and HTTP errors reject', async () => {
+  await assert.rejects(
+    createEcccAirQualitySource({
+      fetchImpl: async () => json({ features: 'no' }),
+    }).getSnapshot(),
+    /Malformed AQHI station/,
+  );
+  await assert.rejects(
+    createEcccAirQualitySource({
+      fetchImpl: async () => json({}, { status: 503 }),
+    }).getSnapshot(),
+    /ECCC HTTP 503/,
+  );
+});
+
+test('an oversized response is refused before it is parsed', async () => {
+  const big = 'x'.repeat(4 * 1024 * 1024 + 1);
+  await assert.rejects(
+    createEcccAirQualitySource({
+      fetchImpl: async () =>
+        new Response(new Blob([big]).stream(), {
+          headers: { 'content-type': 'application/json' },
+        }),
+    }).getSnapshot(),
+    (error) => error.code === 'RESPONSE_TOO_LARGE',
+  );
+  await assert.rejects(
+    createEcccAirQualitySource({
+      fetchImpl: async () =>
+        json({}, { headers: { 'content-length': String(5 * 1024 * 1024) } }),
+    }).getSnapshot(),
+    (error) => error.code === 'RESPONSE_TOO_LARGE',
+  );
+});
+
+test('a caller abort cancels the request and detaches its listener', async () => {
+  const caller = new AbortController();
+  let requestSignal = null;
+  const source = createEcccAirQualitySource({
+    fetchImpl: (_url, { signal }) => {
+      requestSignal = signal;
+      return new Promise((_resolve, reject) =>
+        signal.addEventListener('abort', () => reject(signal.reason), {
+          once: true,
+        }),
+      );
+    },
+  });
+  const pending = source.getSnapshot({ signal: caller.signal });
+  caller.abort(new Error('layer disabled'));
+  await assert.rejects(pending, /layer disabled/);
+  assert.equal(requestSignal.aborted, true);
+  const already = new AbortController();
+  already.abort(new Error('before start'));
+  let calls = 0;
+  await assert.rejects(
+    createEcccAirQualitySource({
+      fetchImpl: async () => {
+        calls += 1;
+        return json({ features: [] });
+      },
+    }).getSnapshot({ signal: already.signal }),
+    /before start/,
+  );
+  assert.equal(calls, 0);
+});
+
+test('a request that outlives its deadline is aborted', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const source = createEcccAirQualitySource({
+    timeoutMs: 1_000,
+    fetchImpl: (_url, { signal }) =>
+      new Promise((_resolve, reject) =>
+        signal.addEventListener('abort', () => reject(signal.reason), {
+          once: true,
+        }),
+      ),
+  });
+  const pending = source.getSnapshot();
+  t.mock.timers.tick(1_000);
+  await assert.rejects(pending, /ECCC request timed out/);
+});

src/layers/alpr/index.js

@@ -3,21 +3,18 @@ import * as Cesium from 'cesium';
 import {
   LAYER_ID,
   REQUEST_DEBOUNCE_MS,
-  QUERY_LIMIT,
-  MAX_RENDERED,
-  QUERY_SNAP_DEGREES,
   QUERY_REUSE_MS,
   ALPR_COLOR,
 } from './policy.js';
 import {
   snapAlprBox,
   boxContains,
-  destinationPointDeg,
   alprRetryDelayMs,
   validateAlprSnapshot,
   alprCreditMarkup,
 } from './model.js';
 import { createAlprPresentation } from './presentation.js';
+import { t, tn, msg } from '../../i18n/index.js';
 
 /**
  * Own one layer's requests, records, display and viewer subscriptions.
@@ -83,9 +80,7 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     viewportBox,
     clearRendered,
     hideOnMapCredit,
-    presentOnMapCredit,
     renderRecords,
-    selectRecord,
     focusNearest,
     clearSelection,
     updateSelectedAnchor,
@@ -275,7 +270,7 @@ export function createAlprCamerasLayer({ source, services } = {}) {
       state.stale = Boolean(state.lastUpdate);
       setAlprStatus(
         'unavailable',
-        error?.message || 'Camera source temporarily unavailable',
+        error?.message || msg('Camera source temporarily unavailable'),
       );
       if (!isUnavailableCapability(error)) scheduleUnavailableRetry();
     } finally {
@@ -293,7 +288,8 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     id: LAYER_ID,
     name: 'ALPR Cameras',
     icon: '📷',
-    source: source.label || 'Mapped camera locations',
+    // English in layer state; the layer row translates it.
+    source: source.label || msg('Mapped camera locations'),
     updateInterval: 0,
     statsRefreshInterval: 1000,
     init(viewer) {
@@ -372,10 +368,12 @@ export function createAlprCamerasLayer({ source, services } = {}) {
         chips: [
           {
             id: 'find-camera',
-            label: 'SHOW NEAREST',
+            label: t('SHOW NEAREST'),
             title: state.viewer?.trackedEntity
-              ? 'Stop following the current object before navigating to a camera'
-              : 'Move to the nearest loaded camera and show its details',
+              ? t(
+                  'Stop following the current object before navigating to a camera',
+                )
+              : t('Move to the nearest loaded camera and show its details'),
             disabled:
               !state.enabled || !count || Boolean(state.viewer?.trackedEntity),
             onClick: focusNearest,
@@ -383,25 +381,64 @@ export function createAlprCamerasLayer({ source, services } = {}) {
         ],
         legend: [
           {
-            label: 'Camera badges',
+            label: t('Camera badges'),
             color: ALPR_COLOR,
             count,
-            blurb:
+            blurb: t(
               'Cyan cameras turn coral when selected. Wedges illustrate mapped direction, not measured coverage. Nearby cameras may be outside the screen.',
+            ),
           },
         ],
       };
     },
+    /**
+     * Snapshot loaded ALPR cameras (the nearby query box) as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, lat, lon, operator, manufacturer, cameraType, directionDeg}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!state.enabled) return [];
+      const result = [];
+      for (const record of state.records || []) {
+        if (result.length >= maxCount) break;
+        if (
+          !Number.isFinite(record.latitude) ||
+          !Number.isFinite(record.longitude)
+        )
+          continue;
+        result.push({
+          id: record.id,
+          lat: record.latitude,
+          lon: record.longitude,
+          operator: record.operator ?? null,
+          manufacturer: record.manufacturer ?? null,
+          cameraType: record.cameraType ?? null,
+          directionDeg: Number.isFinite(record.directionDeg)
+            ? record.directionDeg
+            : null,
+        });
+      }
+      return result;
+    },
     getStats() {
       return {
         count: state.dataSource?.entities.values.length || 0,
         countLabel:
           state.enabled && !state.noCoverage && state.status !== 'zoom-in'
-            ? `${state.dataSource?.entities.values.length || 0} nearby${
-                Number.isInteger(state.onScreen)
-                  ? ` · ${state.onScreen} on screen`
-                  : ''
-              }`
+            ? Number.isInteger(state.onScreen)
+              ? tn(
+                  state.dataSource?.entities.values.length || 0,
+                  '{count} nearby · {onScreen} on screen',
+                  '{count} nearby · {onScreen} on screen',
+                  { onScreen: state.onScreen },
+                )
+              : tn(
+                  state.dataSource?.entities.values.length || 0,
+                  '{count} nearby',
+                  '{count} nearby',
+                )
             : '',
         noCoverage: Boolean(state.noCoverage),
         lastUpdate: state.lastUpdate,
@@ -420,20 +457,22 @@ export function createAlprCamerasLayer({ source, services } = {}) {
           : 0,
         loadingLabel: state.loading
           ? state.retrying
-            ? 'retrying mapped ALPR cameras'
-            : 'loading mapped ALPR cameras'
+            ? t('retrying mapped ALPR cameras')
+            : t('loading mapped ALPR cameras')
           : state.noCoverage
-            ? 'No ALPR data for this area — US and Canada only'
+            ? t('No ALPR data for this area — US and Canada only')
             : state.status === 'zoom-in'
-              ? 'Zoom in to load mapped cameras'
+              ? t('Zoom in to load mapped cameras')
               : [
-                  state.stale ? 'Showing cached locations' : '',
+                  state.stale ? t('Showing cached locations') : '',
                   state.saturated || state.renderSaturated
-                    ? 'Coverage limited — zoom in'
+                    ? t('Coverage limited — zoom in')
+                    : '',
+                  state.status === 'empty'
+                    ? t('No ALPR data for this area')
                     : '',
-                  state.status === 'empty' ? 'No ALPR data for this area' : '',
                   state.status === 'ready' && state.onScreen === 0
-                    ? 'None on screen — nearby cameras are outside the view'
+                    ? t('None on screen — nearby cameras are outside the view')
                     : '',
                 ]
                   .filter(Boolean)

src/layers/alpr/presentation.js

@@ -13,6 +13,7 @@ import {
   MARKER_SCALE_BY_DISTANCE,
 } from './policy.js';
 import { boxContains } from './model.js';
+import { msg } from '../../i18n/index.js';
 import { createAlprFloorResolver } from './floors.js';
 import { createAlprOverlay } from './overlay.js';
 import {
@@ -451,7 +452,7 @@ export function createAlprPresentation({ state, services, source }) {
         layerName: 'ALPR Cameras',
         source:
           source.attribution?.description || source.label || 'Camera source',
-        label: 'ALPR camera',
+        label: msg('ALPR camera'),
         latitude: record.latitude,
         longitude: record.longitude,
         properties: {

src/layers/alpr/records.js

@@ -1,11 +1,11 @@
 import { QUERY_LIMIT, QUERY_SNAP_DEGREES } from './policy.js';
 
-export function textTag(value) {
+function textTag(value) {
   const t = String(value ?? '').trim();
   return t || null;
 }
 
-export function numTag(value) {
+function numTag(value) {
   // `Number('')` and `Number('   ')` are 0, not NaN — a blank or whitespace-only
   // tag value must read as missing, never as a due-north bearing.
   if (value == null) return null;
@@ -102,7 +102,7 @@ export function normalizeAlprNode(el) {
   };
 }
 
-export function normalizeDirection(value) {
+function normalizeDirection(value) {
   const degrees = numTag(value);
   return degrees != null && degrees >= 0 && degrees <= 360
     ? degrees % 360

src/layers/alpr/source.js

@@ -16,6 +16,9 @@ import {
 } from '../../sources/vectorTiles.js';
 import { buildOverpassQuery, normalizeAlprNode } from './records.js';
 import { decodeAlprTile } from './tileRecords.js';
+// Marks text for i18n extraction; the UI translates it with t(). Kept local
+// because AI tool services import this module outside the browser.
+const msg = (text) => text;
 
 /**
  * Finest attributed extract zoom whose tiles for `box` fit the per-view cap,
@@ -136,7 +139,7 @@ export function createAlprTileSource({
         const metadata = await source.getMetadata(signal);
         const [west, south, east, north] = metadata.bounds || [];
         if (![west, south, east, north].every(Number.isFinite))
-          throw new Error('Camera coverage unavailable');
+          throw new Error(msg('Camera coverage unavailable'));
         if (
           box.east < west ||
           box.west > east ||
@@ -184,7 +187,7 @@ export function createAlprTileSource({
       for (const source of sources) source.clear();
       precision.clear();
     },
-    label: 'OpenStreetMap · community mapped',
+    label: msg('OpenStreetMap · community mapped'),
     attribution: {
       name: 'OpenStreetMap',
       description: '© OpenStreetMap contributors, ODbL',
@@ -242,7 +245,7 @@ export function createOverpassAlprSource({
     // The shared proxy already rejects query errors. Validate here too so a
     // malformed or partial response never becomes an authoritative empty map.
     if (!Array.isArray(payload?.elements) || payload.remark) {
-      throw new Error('Overpass returned an incomplete camera response');
+      throw new Error(msg('Overpass returned an incomplete camera response'));
     }
     return {
       records: [
@@ -260,7 +263,7 @@ export function createOverpassAlprSource({
   }
   return {
     fetch: fetchAlprNodes,
-    label: 'OpenStreetMap · community mapped',
+    label: msg('OpenStreetMap · community mapped'),
     attribution: {
       name: 'OpenStreetMap',
       description: 'OpenStreetMap contributors (ODbL 1.0; community mapped)',

src/layers/alpr/tileRecords.js

@@ -3,7 +3,7 @@ import { VectorTile } from '@mapbox/vector-tile';
 import { normalizeAlprNode } from './records.js';
 
 /** Map extract attributes without treating an OSM edit date as a field verification. */
-export function normalizeAlprTileFeature(feature) {
+function normalizeAlprTileFeature(feature) {
   const p = feature?.properties || {};
   if (feature?.geometry?.type !== 'Point' || p.osmType !== 'node') return null;
   const [lon, lat] = feature.geometry.coordinates;

src/layers/awareness/controls.js

@@ -75,6 +75,56 @@ export function createControls({ state: layerState, services, parts, source }) {
       );
     },
 
+    /**
+     * Return the exact retained aircraft cohorts behind the current Contacts
+     * panel snapshot. Voice reads this immutable copy instead of re-scanning
+     * live layers, so panel and spoken counts share one evaluation timestamp.
+     */
+    getAircraftQuerySnapshot() {
+      if (!layerState.enabled || !layerState.subject || !layerState.results)
+        return null;
+      // Build every public count from this exact results object before
+      // returning. A refresh may replace `layerState.results` as soon as the
+      // caller awaits, so consumers must not make a second read later and
+      // accidentally combine two evaluation timestamps.
+      const panelSnapshot = parts.model.buildAwarenessContextSnapshot(
+        layerState.results,
+        parts.model.navigationState(),
+        {
+          subjectPresent: !layerState.subjectMissing,
+        },
+      );
+      const cohorts = {};
+      for (const cohort of layerState.results.cohorts || []) {
+        if (!['flights', 'military'].includes(cohort?.id)) continue;
+        cohorts[cohort.id] = {
+          count: cohort.summary?.count ?? null,
+          complete:
+            Number.isFinite(cohort.summary?.count) &&
+            cohort.summary?.complete !== false,
+          truncated:
+            !Number.isFinite(cohort.summary?.count) ||
+            cohort.summary?.truncated === true,
+          // These records carry structured values such as Cartesian positions.
+          // A shallow spread would let a voice consumer mutate the retained
+          // Contacts cohort through the advertised read-only snapshot.
+          items: structuredClone(cohort.summary?.navigationNearest || []),
+          source: cohort.source || null,
+          provenance: cohort.provenance
+            ? structuredClone(cohort.provenance)
+            : null,
+          reason: cohort.summary?.reason || null,
+        };
+      }
+      return {
+        subject: structuredClone(layerState.results.subject),
+        evaluatedAt: layerState.results.evaluatedAt,
+        radiusM: layerState.results.radiusM,
+        cohorts,
+        contactsWindow: parts.model.contactsWindowFromSnapshot(panelSnapshot),
+      };
+    },
+
     /**
      * Release Contact-owned camera tracking without discarding the selected
      * subject. Reset-to-globe uses this route so the normal Context FOCUS action

src/layers/awareness/model.js

@@ -144,6 +144,9 @@ export function createModel({ state: layerState, services, parts, source }) {
 
   function contactsWindowFromSnapshot(snapshot) {
     if (!snapshot?.subject) return null;
+    const aircraftCohorts = (snapshot.cohorts || []).filter((cohort) =>
+      ['flights', 'military'].includes(cohort?.id),
+    );
     const countFor = (cohortId) => {
       const cohort = Array.isArray(snapshot.cohorts)
         ? snapshot.cohorts.find((item) => item?.id === cohortId)
@@ -164,6 +167,12 @@ export function createModel({ state: layerState, services, parts, source }) {
       flights,
       military,
       vessels: countFor('ais-live-vessels'),
+      complete:
+        aircraftCohorts.length === 2 &&
+        aircraftCohorts.every(
+          (cohort) =>
+            Number.isFinite(cohort.count) && cohort.complete !== false,
+        ),
     };
   }
 
@@ -190,6 +199,8 @@ export function createModel({ state: layerState, services, parts, source }) {
         coverage: cohort.coverage || null,
         relationship: cohort.summary.relationship,
         count: cohort.summary.count,
+        complete: cohort.summary.complete !== false,
+        truncated: cohort.summary.truncated === true,
         reason: cohort.summary.reason,
         nearest: cohort.summary.nearest.slice(),
       })),

src/layers/awareness/navigation.js

@@ -25,6 +25,7 @@ export function createNavigation({
     {
       displayLimit = AWARENESS_MAX_EXAMPLES,
       navigationLimit = AWARENESS_MAX_NAVIGATION_EXAMPLES,
+      complete = true,
     } = {},
   ) {
     const summary = summarizeAwarenessCohort(items, {
@@ -34,6 +35,8 @@ export function createNavigation({
     if (summary.count === null) return summary;
     return {
       ...summary,
+      complete: Boolean(complete),
+      truncated: !complete,
       nearest: summary.nearest.slice(0, displayLimit),
       navigationNearest: summary.nearest,
     };

src/layers/awareness/panel.js

@@ -1,10 +1,48 @@
 import {
   formatAwarenessLabel,
-  formatAwarenessDistance,
   AWARENESS_RADIUS_M,
 } from '../../data/militaryAwarenessEngine.js';
+import { formatNumber, t, translateKnown } from '../../i18n/index.js';
+import { formatQuantity } from '../../ui/unitLabels.js';
 import { AWARENESS_PAGE_SIZE, AWARENESS_PAGE_ROTATE_MS } from './policy.js';
 
+/** Format a cohort total without presenting a retained cap as exact. */
+export function formatAwarenessCount(summary = {}) {
+  if (!Number.isFinite(summary.count)) return '?';
+  const count = summary.count.toLocaleString('en-US');
+  return summary.complete === false || summary.truncated === true
+    ? `At least ${count}`
+    : count;
+}
+
+/** The count as the panel shows it, in the UI language. */
+function presentAwarenessCount(summary = {}) {
+  if (!Number.isFinite(summary.count)) return '?';
+  const count = formatNumber(summary.count);
+  return summary.complete === false || summary.truncated === true
+    ? t('At least {count}', { count })
+    : count;
+}
+
+/** A distance as the panel shows it: 850 m, 4.6 km, 120 km, in the UI language. */
+export function presentAwarenessDistance(meters) {
+  if (!Number.isFinite(meters) || meters < 0) return '—';
+  const wholeMeters = Math.round(meters);
+  if (wholeMeters < 1000) return formatQuantity(wholeMeters, 'm');
+  const digits = meters < 10000 ? 1 : 0;
+  return formatQuantity(meters / 1000, 'km', {
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  });
+}
+
+/** The cohort's reason, kept English in data, shown in the UI language. */
+function presentAwarenessReason(summary = {}) {
+  return summary.reasonTemplate
+    ? t(summary.reasonTemplate, summary.reasonValues)
+    : translateKnown(summary.reason || '');
+}
+
 export function createPanel({ state: layerState, services, parts, source }) {
   function ensurePanel() {
     if (layerState.panel) return layerState.panel;
@@ -47,8 +85,8 @@ export function createPanel({ state: layerState, services, parts, source }) {
   function hidePanel() {
     if (layerState.panel) {
       const markup = `<div class="military-awareness-standby">
-      <strong>${layerState.enabled ? 'CONTEXT READY' : 'GLOBAL CONTEXT OFF'}</strong>
-      <span>${layerState.enabled ? 'SELECT A FLIGHT, VESSEL, OR MAPPED INSTALLATION' : 'ENABLE TO LOAD OBSERVED / MAPPED PROXIMITY'}</span>
+      <strong>${layerState.enabled ? t('CONTEXT READY') : t('GLOBAL CONTEXT OFF')}</strong>
+      <span>${layerState.enabled ? t('SELECT A FLIGHT, VESSEL, OR MAPPED INSTALLATION') : t('ENABLE TO LOAD OBSERVED / MAPPED PROXIMITY')}</span>
     </div>`;
       layerState.panel.hidden = false;
       if (layerState.panelMarkup !== markup) {
@@ -61,7 +99,7 @@ export function createPanel({ state: layerState, services, parts, source }) {
 
   function rowHtml(cohort) {
     const summary = cohort.summary;
-    const count = summary.count === null ? '?' : String(summary.count);
+    const count = presentAwarenessCount(summary);
     const page = layerState.cohortPages.get(cohort.id) || 0;
     const nearest = summary.nearest
       .slice(page, page + AWARENESS_PAGE_SIZE)
@@ -69,10 +107,10 @@ export function createPanel({ state: layerState, services, parts, source }) {
         const label = formatAwarenessLabel(item);
         const targetId = item.icao24 || item.mmsi || item.id;
         if (!targetId) {
-          return `<li><span class="military-awareness-target unavailable" aria-label="Unavailable">${escapeHtml(label)} <span>${formatAwarenessDistance(item.distanceM)}</span></span></li>`;
+          return `<li><span class="military-awareness-target unavailable" aria-label="${t('Unavailable')}">${escapeHtml(label)} <span>${presentAwarenessDistance(item.distanceM)}</span></span></li>`;
         }
-        const accessibleLabel = label === '—' ? 'Unavailable' : label;
-        return `<li><button type="button" class="military-awareness-target" data-awareness-layer="${escapeHtml(cohort.id)}" data-awareness-id="${escapeHtml(targetId)}" aria-label="Focus ${escapeHtml(accessibleLabel)}">${escapeHtml(label)} <span>${formatAwarenessDistance(item.distanceM)}</span></button>${namedAreasHtml(item.memberNames)}</li>`;
+        const accessibleLabel = label === '—' ? t('Unavailable') : label;
+        return `<li><button type="button" class="military-awareness-target" data-awareness-layer="${escapeHtml(cohort.id)}" data-awareness-id="${escapeHtml(targetId)}" aria-label="${escapeHtml(t('Focus {label}', { label: accessibleLabel }))}">${escapeHtml(label)} <span>${presentAwarenessDistance(item.distanceM)}</span></button>${namedAreasHtml(item.memberNames)}</li>`;
       })
       .join('');
     const pageCount = Math.max(
@@ -86,17 +124,17 @@ export function createPanel({ state: layerState, services, parts, source }) {
     const coverage = cohort.coverage ? ` · ${escapeHtml(cohort.coverage)}` : '';
     return `<section class="military-awareness-row ${summary.relationship.toLowerCase()}">
     <div><strong>${escapeHtml(cohort.label)}</strong><b aria-live="polite">${count}${pageLabel}</b></div>
-    <small>${escapeHtml(cohort.source)}${coverage} · ${escapeHtml(summary.reason)}</small>
+    <small>${escapeHtml(cohort.source)}${coverage} · ${escapeHtml(presentAwarenessReason(summary))}</small>
     ${nearest ? `<ul>${nearest}</ul>` : ''}
   </section>`;
   }
 
   function navigationControlsHtml() {
     const canPrevious = layerState.navigationIndex > 0;
-    return `<div class="military-awareness-controls" role="group" aria-label="Global Context navigation">
-    <button type="button" data-awareness-action="previous" title="Previous — prior visited contact in the 250 km window"${canPrevious ? '' : ' disabled'}>PREVIOUS</button>
-    <button type="button" data-awareness-action="focus">FOCUS</button>
-    <button type="button" data-awareness-action="next" title="Next — nearest unvisited contact in the 250 km window"${parts.navigation.canNavigateNext() ? '' : ' disabled'}>NEXT</button>
+    return `<div class="military-awareness-controls" role="group" aria-label="${t('Global Context navigation')}">
+    <button type="button" data-awareness-action="previous" title="${t('Previous — prior visited contact in the 250 km window')}"${canPrevious ? '' : ' disabled'}>${t('PREVIOUS')}</button>
+    <button type="button" data-awareness-action="focus">${t('FOCUS')}</button>
+    <button type="button" data-awareness-action="next" title="${t('Next — nearest unvisited contact in the 250 km window')}"${parts.navigation.canNavigateNext() ? '' : ' disabled'}>${t('NEXT')}</button>
   </div>`;
   }
 
@@ -166,7 +204,7 @@ export function createPanel({ state: layerState, services, parts, source }) {
 
   function namedAreasHtml(names) {
     return names?.length
-      ? `<details class="military-awareness-names"><summary>Named areas (${names.length})</summary><div>${names.map((name) => escapeHtml(name)).join('<br>')}</div></details>`
+      ? `<details class="military-awareness-names"><summary>${escapeHtml(t('Named areas ({n})', { n: formatNumber(names.length) }))}</summary><div>${names.map((name) => escapeHtml(name)).join('<br>')}</div></details>`
       : '';
   }
 
@@ -174,11 +212,11 @@ export function createPanel({ state: layerState, services, parts, source }) {
     if (!layerState.enabled || !layerState.results) return hidePanel();
     const panel = ensurePanel();
     const { subject, cohorts } = layerState.results;
-    const markup = `<div class="military-awareness-subject">${escapeHtml(subject.label)} · ${formatAwarenessDistance(AWARENESS_RADIUS_M)} FLIGHT / VESSEL WINDOW</div>
+    const markup = `<div class="military-awareness-subject">${escapeHtml(subject.label)} · ${escapeHtml(t('{distance} FLIGHT / VESSEL WINDOW', { distance: presentAwarenessDistance(AWARENESS_RADIUS_M) }))}</div>
     ${namedAreasHtml(subject.memberNames)}
     ${navigationControlsHtml()}
     ${cohorts.map(rowHtml).join('')}
-    <p class="military-awareness-note" tabindex="-1" data-awareness-focus-continuation>Open-source mapped/observed context. Missing broadcasts, unloaded map areas, or unmapped sites are not evidence of absence.</p>`;
+    <p class="military-awareness-note" tabindex="-1" data-awareness-focus-continuation>${t('Open-source mapped/observed context. Missing broadcasts, unloaded map areas, or unmapped sites are not evidence of absence.')}</p>`;
     panel.hidden = false;
     if (layerState.panelMarkup !== markup) {
       const focusSnapshot = captureAwarenessPanelFocus(panel);

src/layers/awareness/policy.js

@@ -1,9 +1,6 @@
 export const AIRCRAFT_DEPENDENCIES = ['flights', 'military'];
 
-export const DEFERRED_DEPENDENCIES = [
-  'ais-live-vessels',
-  'military-installations',
-];
+const DEFERRED_DEPENDENCIES = ['ais-live-vessels', 'military-installations'];
 
 export const DEPENDENCIES = [
   ...AIRCRAFT_DEPENDENCIES,
@@ -38,8 +35,8 @@ export const AWARENESS_MAX_EXAMPLES = 10;
 // so these caps sit far above any realistic in-range population rather than at
 // the display limit. They are still FINITE: an unbounded materialization would
 // let a pathological feed sort an eleven-thousand-contact array on every
-// refresh. Truthfulness does not depend on them — `summarizeAwarenessCohort`
-// derives `count` from the full in-range set before any slice.
+// refresh. Callers sample beyond this cap and carry explicit completeness, so
+// a saturated cohort is a lower bound rather than a silently exact count.
 
 export const AWARENESS_QUERY_LIMIT = 20000;
 

src/layers/awareness/presentation.js

@@ -0,0 +1,10 @@
+/**
+ * Format a compass direction for the awareness overlay.
+ * @param {number} degrees
+ * @returns {string}
+ */
+export function formatAwarenessDirection(degrees) {
+  if (!Number.isFinite(degrees)) return '—';
+  const normalized = ((degrees % 360) + 360) % 360;
+  return String(Math.round(normalized) % 360).padStart(3, '0');
+}

src/layers/awareness/presentation.test.mjs

@@ -0,0 +1,11 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { formatAwarenessDirection } from './presentation.js';
+
+test('awareness bearings that round through north read 000, not 360', () => {
+  assert.equal(formatAwarenessDirection(359.4), '359');
+  assert.equal(formatAwarenessDirection(359.6), '000');
+  assert.equal(formatAwarenessDirection(0), '000');
+  assert.equal(formatAwarenessDirection(-0.4), '000');
+  assert.equal(formatAwarenessDirection(Number.NaN), '—');
+});

src/layers/awareness/queries.js

@@ -1,4 +1,16 @@
 import { AWARENESS_RADIUS_M } from '../../data/militaryAwarenessEngine.js';
+
+// The reason stays English for the voice analyst; the Contacts panel shows it
+// in the UI language from `reasonTemplate`.
+const msg = (text) => text;
+const fillTemplate = (template, values = {}) =>
+  template.replace(/\{(\w+)\}/g, (_, name) => String(values[name]));
+const withReason = (summary, template, values) => ({
+  ...summary,
+  reason: fillTemplate(template, values),
+  reasonTemplate: template,
+  reasonValues: values,
+});
 import { DEPENDENCIES, AWARENESS_QUERY_LIMIT } from './policy.js';
 
 export function createQueries({ state: layerState, services, parts, source }) {
@@ -35,7 +47,7 @@ export function createQueries({ state: layerState, services, parts, source }) {
     //     setInstallationStatus is only ever called with
     //     loading/zoom-in/ready/stale/empty/unavailable.
     //   - ais-live-vessels is what the predicate below is FOR. Its enable() and
-    //     update() both resolve as soon as the first /api/ais-live poll answers,
+    //     update() both resolve as soon as the first /api/vessels poll answers,
     //     so the lifecycle settles to `enabled` — but until the server-side socket
     //     delivers a position, firstConnectPhase is 'loading' and getStats()
     //     reports loading: true, lastUpdate: null, count 0, and an UNDEFINED
@@ -53,7 +65,12 @@ export function createQueries({ state: layerState, services, parts, source }) {
       neverAnswered ||
       ['unavailable', 'zoom-in'].includes(stats.status) ||
       Boolean(stats.error && stats.count === 0);
-    return { available: !unavailable, stale: Boolean(stats.stale), stats };
+    return {
+      available: !unavailable,
+      enabled,
+      stale: Boolean(stats.stale),
+      stats,
+    };
   }
 
   function collectSourceStates() {
@@ -114,19 +131,20 @@ export function createQueries({ state: layerState, services, parts, source }) {
     // A subject window is its own bounded area: name it instead of the viewport.
     if (coverage?.kind === 'subject' && Number.isFinite(coverage.radiusM)) {
       const km = Math.round(coverage.radiusM / 1000);
-      return {
-        ...summary,
-        reason: summary.count
-          ? `mapped matches within ${km} km of the subject`
-          : `none mapped within ${km} km; not a complete 250 km survey`,
-      };
+      return withReason(
+        summary,
+        summary.count
+          ? msg('mapped matches within {km} km of the subject')
+          : msg('none mapped within {km} km; not a complete 250 km survey'),
+        { km },
+      );
     }
-    return {
-      ...summary,
-      reason: summary.count
-        ? 'mapped matches from the loaded viewport'
-        : 'viewport feed is not a complete 250 km survey',
-    };
+    return withReason(
+      summary,
+      summary.count
+        ? msg('mapped matches from the loaded viewport')
+        : msg('viewport feed is not a complete 250 km survey'),
+    );
   }
 
   /**
@@ -147,8 +165,10 @@ export function createQueries({ state: layerState, services, parts, source }) {
    * @param {object} [options]
    * @param {number} [options.radiusM=AWARENESS_RADIUS_M] Window radius.
    * @param {object|null} [options.subject=null] Contact at the centre, excluded.
-   * @returns {{flights: Array, military: Array, aircraft: number}|null} Cohorts
-   *   plus the combined aircraft count, or null without a position.
+   * @returns {{flights: Array, military: Array, aircraft: number,
+   *   completeByLayer: {flights: boolean, military: boolean}}|null} Cohorts,
+   *   their lower-bound completeness, and the combined aircraft count, or
+   *   null without a position.
    */
 
   function collectAircraftProximityWindow(
@@ -156,21 +176,35 @@ export function createQueries({ state: layerState, services, parts, source }) {
     { radiusM = AWARENESS_RADIUS_M, subject = null } = {},
   ) {
     if (!position) return null;
-    const flights = flightsLayer
-      .getNearby(position, radiusM, AWARENESS_QUERY_LIMIT, {
+    // Ask for one usable row beyond the retained limit so a capped cohort is
+    // reported as a lower bound instead of an exact count. The selected
+    // subject can consume one slot before exclusion, hence the extra two.
+    const sampleLimit = AWARENESS_QUERY_LIMIT + 2;
+    const flightSample = flightsLayer
+      .getNearby(position, radiusM, sampleLimit, {
         includeHidden: true,
       })
       .filter(
         (item) => !subject || !isSame(subject, item, 'flights', 'icao24'),
       );
-    const military = militaryFlightsLayer
-      .getNearby(position, radiusM, AWARENESS_QUERY_LIMIT, {
+    const militarySample = militaryFlightsLayer
+      .getNearby(position, radiusM, sampleLimit, {
         includeHidden: true,
       })
       .filter(
         (item) => !subject || !isSame(subject, item, 'military', 'icao24'),
       );
-    return { flights, military, aircraft: flights.length + military.length };
+    const flights = flightSample.slice(0, AWARENESS_QUERY_LIMIT);
+    const military = militarySample.slice(0, AWARENESS_QUERY_LIMIT);
+    return {
+      flights,
+      military,
+      aircraft: flights.length + military.length,
+      completeByLayer: {
+        flights: flightSample.length <= AWARENESS_QUERY_LIMIT,
+        military: militarySample.length <= AWARENESS_QUERY_LIMIT,
+      },
+    };
   }
   return {
     sourceState,

src/layers/awareness/queries.test.mjs

@@ -6,6 +6,39 @@ import { createSubject } from './subject.js';
 import { createControls } from '../installations/controls.js';
 import { createModel } from '../installations/model.js';
 import { summarizeAwarenessCohort } from '../../data/militaryAwarenessEngine.js';
+import { AWARENESS_QUERY_LIMIT } from './policy.js';
+
+test('aircraft window marks a capped layer as a lower bound', () => {
+  const rows = Array.from({ length: AWARENESS_QUERY_LIMIT + 1 }, (_, index) => ({
+    icao24: `f${index}`,
+    distance: index,
+  }));
+  let requested = null;
+  const services = {
+    flights: {
+      getNearby: (_position, _radius, limit) => {
+        requested = limit;
+        return rows.slice(0, limit);
+      },
+    },
+    military: { getNearby: () => [] },
+  };
+  const parts = {
+    navigation: {
+      summarizeAwarenessCohortForNavigation: (items, source) =>
+        summarizeAwarenessCohort(items, source),
+    },
+  };
+  const queries = createQueries({ state: {}, services, parts });
+  const window = queries.collectAircraftProximityWindow({ center: true });
+  assert.equal(requested, AWARENESS_QUERY_LIMIT + 2);
+  assert.equal(window.flights.length, AWARENESS_QUERY_LIMIT);
+  assert.equal(window.aircraft, AWARENESS_QUERY_LIMIT);
+  assert.deepEqual(window.completeByLayer, {
+    flights: false,
+    military: true,
+  });
+});
 
 test('Contacts excludes square corners and measures from the current moving subject', () => {
   const records = [

src/layers/awareness/rendering.js

@@ -1,4 +1,5 @@
 import * as Cesium from 'cesium';
+import { t } from '../../i18n/index.js';
 import {
   createCyberSonarSampler,
   isCyberContactSonarActive as isCyberSonarActive,
@@ -10,6 +11,7 @@ import {
 } from '../../data/militaryAwarenessEngine.js';
 import { bearingBetweenCoordinates } from '../../cockpitMath.js';
 import { AWARENESS_PAGE_SIZE, CONTEXT_RIM_HEIGHT_M } from './policy.js';
+import { formatAwarenessDirection } from './presentation.js';
 
 export function createRendering({
   state: layerState,
@@ -137,7 +139,9 @@ export function createRendering({
       '--compass-rotation',
       `${-headingDeg}deg`,
     );
-    layerState.compassHeading.textContent = `HDG ${String(headingDeg).padStart(3, '0')}°`;
+    layerState.compassHeading.textContent = t('HDG {value}°', {
+      value: String(headingDeg).padStart(3, '0'),
+    });
     layerState.compassHeading.style.left = `${geometry.centerX}px`;
     layerState.compassHeading.style.top = `${geometry.centerY - compassRadius + 39}px`;
     for (const label of layerState.compassLabels) {
@@ -221,10 +225,14 @@ export function createRendering({
             )
           : null;
       const bearingText = Number.isFinite(bearing)
-        ? `BRG ${String(Math.round(bearing)).padStart(3, '0')}°`
-        : 'BRG —';
+        ? t('BRG {value}°', {
+            value: formatAwarenessDirection(bearing),
+          })
+        : t('BRG —');
       const courseText = Number.isFinite(item.track)
-        ? ` · CRS ${String(Math.round(item.track)).padStart(3, '0')}°`
+        ? ` · ${t('CRS {value}°', {
+            value: formatAwarenessDirection(item.track),
+          })}`
         : '';
       marker._label.textContent = `${label} · ${formatAwarenessDistance(item.distanceM)}\n${bearingText}${courseText}`;
       marker.hidden = false;

src/layers/awareness/subject.js

@@ -3,6 +3,7 @@ import {
   AWARENESS_RELATIONSHIP,
 } from '../../data/militaryAwarenessEngine.js';
 import * as Cesium from 'cesium';
+import { t } from '../../i18n/index.js';
 import {
   AWARENESS_QUERY_LIMIT,
   SOURCE_LABEL,
@@ -10,6 +11,19 @@ import {
   AWARENESS_PAGE_SIZE,
 } from './policy.js';
 
+// coverageLabel is machine-composed English from installations/controls.js
+// (pinned by src/data/militaryInstallations.test.mjs); translate the known
+// forms here, pass anything else through.
+const WITHIN_KM_RE = /^WITHIN (\d+) KM$/;
+
+function localizeCoverageLabel(label) {
+  if (typeof label !== 'string' || !label) return label;
+  if (label === 'CURRENT VIEWPORT ONLY') return t('CURRENT VIEWPORT ONLY');
+  const within = WITHIN_KM_RE.exec(label);
+  if (within) return t('WITHIN {km} KM', { km: within[1] });
+  return label;
+}
+
 export function createSubject({ state: layerState, services, parts, source }) {
   const aisLiveVesselsLayer = services.vessels;
   const militaryInstallationsLayer = services.installations;
@@ -37,11 +51,23 @@ export function createSubject({ state: layerState, services, parts, source }) {
     const militaryState = sourceStates.military;
     const vesselsState = sourceStates['ais-live-vessels'];
     const installationsState = sourceStates['military-installations'];
+    const evaluatedAt = Date.now();
+    const retainedProvenance = (id, label, sourceState, fallbackSource) => {
+      const retainedSource = sourceState.stats.source || fallbackSource;
+      return {
+        id,
+        name: label,
+        enabled: sourceState.enabled,
+        source: retainedSource,
+        stats: { ...sourceState.stats, source: retainedSource },
+      };
+    };
     // Same engine the voice analyst calls — see collectAircraftProximityWindow.
-    const { flights, military } = parts.queries.collectAircraftProximityWindow(
+    const aircraftWindow = parts.queries.collectAircraftProximityWindow(
       position,
       { subject },
     );
+    const { flights, military, completeByLayer } = aircraftWindow;
     const vessels = aisLiveVesselsLayer
       .getNearby(position, AWARENESS_RADIUS_M, AWARENESS_QUERY_LIMIT)
       .filter(
@@ -61,31 +87,57 @@ export function createSubject({ state: layerState, services, parts, source }) {
       );
     return {
       subject,
-      evaluatedAt: Date.now(),
+      evaluatedAt,
       radiusM: AWARENESS_RADIUS_M,
       cohorts: [
         {
           id: 'flights',
-          label: 'Flights',
+          label: t('Flights'),
           source: flightsState.stats.source || SOURCE_LABEL.flights,
+          provenance: retainedProvenance(
+            'flights',
+            'Flights',
+            flightsState,
+            SOURCE_LABEL.flights,
+          ),
           summary: parts.navigation.summarizeAwarenessCohortForNavigation(
             flights,
             flightsState,
+            {
+              navigationLimit: AWARENESS_QUERY_LIMIT,
+              complete: completeByLayer.flights,
+            },
           ),
         },
         {
           id: 'military',
-          label: 'Military flights',
+          label: t('Military flights'),
           source: militaryState.stats.source || SOURCE_LABEL.military,
+          provenance: retainedProvenance(
+            'military',
+            'Military flights',
+            militaryState,
+            SOURCE_LABEL.military,
+          ),
           summary: parts.navigation.summarizeAwarenessCohortForNavigation(
             military,
             militaryState,
+            {
+              navigationLimit: AWARENESS_QUERY_LIMIT,
+              complete: completeByLayer.military,
+            },
           ),
         },
         {
           id: 'ais-live-vessels',
-          label: 'AIS vessels',
+          label: t('AIS vessels'),
           source: vesselsState.stats.source || SOURCE_LABEL['ais-live-vessels'],
+          provenance: retainedProvenance(
+            'ais-live-vessels',
+            'AIS vessels',
+            vesselsState,
+            SOURCE_LABEL['ais-live-vessels'],
+          ),
           summary: parts.navigation.summarizeAwarenessCohortForNavigation(
             vessels,
             vesselsState,
@@ -93,12 +145,19 @@ export function createSubject({ state: layerState, services, parts, source }) {
         },
         {
           id: 'military-installations',
-          label: 'Mapped installations',
+          label: t('Mapped installations'),
           source:
             installationsState.stats.source ||
             SOURCE_LABEL['military-installations'],
+          provenance: retainedProvenance(
+            'military-installations',
+            'Mapped installations',
+            installationsState,
+            SOURCE_LABEL['military-installations'],
+          ),
           coverage:
-            installationsState.stats.coverageLabel || 'CURRENT VIEWPORT ONLY',
+            localizeCoverageLabel(installationsState.stats.coverageLabel) ||
+            t('CURRENT VIEWPORT ONLY'),
           summary: parts.queries.summarizeInstallationViewport(
             installations,
             installationsState,

src/layers/bikeshare/barcelonaSystems.test.mjs

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CITY_BY_ID } from './registry.js';
+import { createModel } from './model.js';
+import { createViewport } from './viewport.js';
+import { isAllowedGbfsHost, isAllowedGbfsPath } from '../../data/gbfsSource.js';
+
+// Each Barcelona system's host, and the stations farthest from its registered
+// centre in the live feed (checked 2026-10-16). AMBici spans the metropolitan
+// area, so it lists its south-western and north-eastern ends.
+const SYSTEMS = {
+  'barcelona-bicing': {
+    host: 'barcelona.publicbikesystem.net',
+    provider: 'Bicing',
+    stations: [
+      { name: 'AV. RASOS DE PEGUERA, 10', lat: 41.462095, lon: 2.178959 },
+      { name: 'C/ 60, NÚMERO 25', lat: 41.3467746, lon: 2.1436235 },
+    ],
+  },
+  'barcelona-ambici': {
+    host: 'gbfs.nextbike.net',
+    provider: 'AMBici',
+    stations: [
+      { name: 'Poal', lat: 41.268865, lon: 1.943849 },
+      { name: 'Platja del Manresà', lat: 41.460101, lon: 2.267271 },
+      { name: 'Can Ruti', lat: 41.482205, lon: 2.237607 },
+    ],
+  },
+};
+
+// The production range check, with no viewer or fetches behind it.
+const parts = {
+  model: createModel({ state: {}, services: {}, parts: {}, source: null }),
+};
+const { computeInRangeCities } = createViewport({
+  state: {},
+  services: { render: { governorRequestRender() {} } },
+  parts,
+  source: null,
+});
+
+test('Bicing and AMBici are registered and readable through the proxy', () => {
+  for (const [id, expected] of Object.entries(SYSTEMS)) {
+    const system = CITY_BY_ID.get(id);
+    assert.ok(system, `${id} is registered`);
+    assert.equal(system.provider, expected.provider);
+    assert.deepEqual(system.hosts, [expected.host]);
+    for (const feed of [
+      system.stationInformationUrl,
+      system.stationStatusUrl,
+    ]) {
+      const url = new URL(feed);
+      assert.ok(isAllowedGbfsHost(url.hostname), `${id} host ${url.hostname}`);
+      assert.ok(
+        isAllowedGbfsPath(url.pathname, url.hostname),
+        `${id} path ${url.pathname}`,
+      );
+    }
+  }
+});
+
+test('a camera over each outermost station activates its system', () => {
+  for (const [id, expected] of Object.entries(SYSTEMS)) {
+    for (const station of expected.stations) {
+      assert.ok(
+        computeInRangeCities({ lat: station.lat, lon: station.lon }).has(id),
+        `${station.name} activates ${id}`,
+      );
+    }
+  }
+});
+
+test('each load radius reaches its outermost stations', () => {
+  // The range check floors every radius at 100 km, so the test above passes
+  // with any loadRadiusKm; get_bike_share uses the radius as registered.
+  for (const [id, expected] of Object.entries(SYSTEMS)) {
+    const system = CITY_BY_ID.get(id);
+    for (const station of expected.stations) {
+      const distance = parts.model.haversineKm(
+        system.centerLat,
+        system.centerLon,
+        station.lat,
+        station.lon,
+      );
+      assert.ok(
+        distance <= system.loadRadiusKm,
+        `${station.name} is ${distance.toFixed(1)} km from the ${id} centre`,
+      );
+    }
+  }
+});
+
+test('a camera over central Barcelona activates both systems', () => {
+  // Plaça de Catalunya.
+  const active = computeInRangeCities({ lat: 41.387, lon: 2.17 });
+  assert.ok(active.has('barcelona-bicing'));
+  assert.ok(active.has('barcelona-ambici'));
+});
+
+test('the nextbike allowance is that one host, not its domain', () => {
+  assert.equal(isAllowedGbfsHost('gbfs.nextbike.net'), true);
+  assert.equal(isAllowedGbfsHost('api.nextbike.net'), false);
+  assert.equal(isAllowedGbfsHost('gbfs.nextbike.net.example'), false);
+});

src/layers/bikeshare/brPbscCities.test.mjs

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CITY_BY_ID } from './registry.js';
+import { createModel } from './model.js';
+import { createViewport } from './viewport.js';
+import { isAllowedGbfsHost, isAllowedGbfsPath } from '../../data/gbfsSource.js';
+
+// Each Bike Itaú city's PBSC host, and the station farthest from its
+// registered centre in the live feed (checked 2026-10-15).
+const CITIES = {
+  'sao-paulo-bike-itau': {
+    host: 'saopaulo.publicbikesystem.net',
+    stations: [{ name: '260 - P3', lat: -23.568235, lon: -46.740715 }],
+  },
+  'rio-de-janeiro-bike-itau': {
+    host: 'riodejaneiro.publicbikesystem.net',
+    stations: [{ name: '293 - Praia da Macumba', lat: -23.03135, lon: -43.479584 }],
+  },
+  'salvador-bike-itau': {
+    host: 'salvador.publicbikesystem.net',
+    stations: [{ name: '49 - Stella Maris', lat: -12.93645, lon: -38.32701 }],
+  },
+  'recife-bike-itau': {
+    host: 'recife.publicbikesystem.net',
+    stations: [{ name: '69 - Praia de Piedade', lat: -8.186205, lon: -34.918371 }],
+  },
+  'porto-alegre-bike-itau': {
+    host: 'portoalegre.publicbikesystem.net',
+    stations: [{ name: '72 - Avenida Tramandaí', lat: -30.135915, lon: -51.22684 }],
+  },
+  'brasilia-bike-itau': {
+    host: 'brasilia.publicbikesystem.net',
+    stations: [{ name: "60 - Parque Olhos d'Água", lat: -15.7431, lon: -47.88667 }],
+  },
+  'curitiba-bike-itau': {
+    host: 'curitiba.publicbikesystem.net',
+    stations: [{ name: '42 - Terminal Portão', lat: -25.476885, lon: -49.292608 }],
+  },
+};
+
+// The production range check, with no viewer or fetches behind it.
+const parts = { model: createModel({ state: {}, services: {}, parts: {}, source: null }) };
+const { computeInRangeCities } = createViewport({
+  state: {},
+  services: { render: { governorRequestRender() {} } },
+  parts,
+  source: null,
+});
+
+test('the Bike Itaú systems are registered and readable through the proxy', () => {
+  for (const [id, expected] of Object.entries(CITIES)) {
+    const city = CITY_BY_ID.get(id);
+    assert.ok(city, `${id} is registered`);
+    assert.equal(city.provider, 'Bike Itaú');
+    assert.deepEqual(city.hosts, [expected.host]);
+    for (const feed of [city.stationInformationUrl, city.stationStatusUrl]) {
+      const url = new URL(feed);
+      assert.ok(isAllowedGbfsHost(url.hostname), `${id} host ${url.hostname}`);
+      assert.ok(isAllowedGbfsPath(url.pathname), `${id} path ${url.pathname}`);
+    }
+  }
+});
+
+test('a camera over each outermost station activates its system', () => {
+  for (const [id, expected] of Object.entries(CITIES)) {
+    for (const station of expected.stations) {
+      assert.ok(
+        computeInRangeCities({ lat: station.lat, lon: station.lon }).has(id),
+        `${station.name} activates ${id}`,
+      );
+    }
+  }
+});

src/layers/bikeshare/controls.js

@@ -1,3 +1,4 @@
+import { msg, t } from '../../i18n/index.js';
 import { STATUS_POLL_MS } from './policy.js';
 
 export function createControls({ state: layerState, services, parts, source }) {
@@ -21,9 +22,42 @@ export function createControls({ state: layerState, services, parts, source }) {
       return parts.queries.collectDetectableStations(options);
     },
 
+    /**
+     * Snapshot loaded bikeshare stations as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, name, city, lat, lon, bikesAvailable, docksAvailable, capacity, renting}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!layerState._enabled) return [];
+      const num = (v) => (Number.isFinite(v) ? v : null);
+      const result = [];
+      for (const record of layerState._stationRenderMap.values()) {
+        if (result.length >= maxCount) break;
+        const info = layerState._stationInfoCache
+          .get(record.cityId)
+          ?.get(record.stationId);
+        if (!Number.isFinite(info?.lat) || !Number.isFinite(info?.lon))
+          continue;
+        result.push({
+          id: record.stationName || `Dock ${record.stationId}`,
+          name: record.stationName || null,
+          city: record.cityId || null,
+          lat: info.lat,
+          lon: info.lon,
+          bikesAvailable: num(record.bikesAvailable),
+          docksAvailable: num(record.docksAvailable),
+          capacity: num(record.capacity),
+          renting: record.isRenting !== false,
+        });
+      }
+      return result;
+    },
+
     /**
      * Return current layer statistics for the UI status display.
-     * @returns {{ count: number, lastUpdate: number|null, loading: boolean, loadingLabel?: string, error?: string }}
+     * @returns {{ count: number, lastUpdate: number|null, loading: boolean, loadingLabel?: string, error?: string, degraded?: boolean, stale?: boolean }}
      */
     getStats() {
       const stats = {
@@ -34,10 +68,26 @@ export function createControls({ state: layerState, services, parts, source }) {
       if (layerState._loading) {
         stats.loadingLabel =
           layerState._activeCityIds.size > 0
-            ? `syncing ${layerState._activeCityIds.size} city feeds...`
-            : 'scanning nearby systems...';
+            ? t('syncing {count} city feeds...', {
+                count: layerState._activeCityIds.size,
+              })
+            : t('scanning nearby systems...');
+      }
+      // A failed city is only the layer's failure when it left nothing on the
+      // map. While other cities still render, the partial failure reads
+      // DEGRADED; when every in-range city failed and only previously drawn
+      // points remain, they read STALE.
+      if (layerState._failedCityIds.size > 0) {
+        if (layerState._stationRenderMap.size === 0) {
+          stats.error = msg('GBFS fetch error');
+        } else {
+          stats.degraded = true;
+          const allFailed = Array.from(layerState._activeCityIds).every(
+            (cityId) => layerState._failedCityIds.has(cityId),
+          );
+          if (allFailed) stats.stale = true;
+        }
       }
-      if (layerState._error) stats.error = layerState._error;
       return stats;
     },
   };

src/layers/bikeshare/failureReporting.test.mjs

@@ -0,0 +1,376 @@
+// BIKESHARE FAILURE REPORTING — one dead city is not a dead layer.
+//
+// City feeds are fetched independently, but the layer reported failure through
+// a single flag. A city whose operator had retired its feed set that flag on
+// every proximity check, and the only code that cleared it ran on a successful
+// *activation* — which an already-loaded city never repeats. The result was a
+// permanent LOAD FAILED over a map drawing a thousand live stations.
+//
+// These cases pin the rule that replaced it: the layer reports failure only
+// when it has nothing to show, and a city that comes back clears its own
+// failure rather than waiting for a neighbour to succeed.
+//
+// Run with: npm test
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createState } from './state.js';
+import { createControls } from './controls.js';
+
+function makeLayer() {
+  const services = {
+    overlays: {
+      setOverlayEntries() {},
+      setOverlaySourceVisible() {},
+      clearOverlaySource() {},
+    },
+  };
+  const state = createState({ services });
+  const parts = { queries: { collectDetectableStations: () => [] } };
+  const { methods } = createControls({ state, services, parts, source: {} });
+  return { state, methods };
+}
+
+/** Stand in for a rendered station without reaching into the renderer. */
+function renderStations(state, count) {
+  for (let i = 0; i < count; i += 1) state._stationRenderMap.set(`s${i}`, {});
+  state._count = state._stationRenderMap.size;
+}
+
+test('a failed city does not fail a layer that is drawing stations', () => {
+  const { state, methods } = makeLayer();
+  renderStations(state, 1069);
+  state._failedCityIds.add('buffalo-reddy');
+
+  const stats = methods.getStats();
+  assert.equal(stats.count, 1069);
+  assert.equal(
+    stats.error,
+    undefined,
+    'a layer drawing 1069 stations reported LOAD FAILED',
+  );
+});
+
+test('the layer reports failure when a failed city left it with nothing', () => {
+  const { state, methods } = makeLayer();
+  state._failedCityIds.add('buffalo-reddy');
+
+  const stats = methods.getStats();
+  assert.equal(stats.count, 0);
+  assert.equal(stats.error, 'GBFS fetch error');
+});
+
+test('a layer with nothing to draw and nothing failed is not an error', () => {
+  const { methods } = makeLayer();
+
+  // Out of range of every city is empty, not broken.
+  assert.equal(methods.getStats().error, undefined);
+});
+
+test('a recovered city clears its own failure', () => {
+  const { state, methods } = makeLayer();
+  state._failedCityIds.add('buffalo-reddy');
+  assert.equal(methods.getStats().error, 'GBFS fetch error');
+
+  state._failedCityIds.delete('buffalo-reddy');
+  assert.equal(
+    methods.getStats().error,
+    undefined,
+    'the failure outlived the city that caused it',
+  );
+});
+
+// The cases above pin how getStats() reads failure state. The cases below
+// drive the real proximity check, status poll and lifecycle against a fake
+// GBFS source, so the failure state they read is the state the layer builds.
+
+import * as Cesium from 'cesium';
+import { CITY_BY_ID } from './registry.js';
+import { createIngestion } from './ingestion.js';
+import { createModel } from './model.js';
+import { createViewport } from './viewport.js';
+import { createRendering } from './rendering.js';
+import { createLifecycle } from './lifecycle.js';
+
+const TORONTO = 'toronto-bike-share';
+const BUFFALO = 'buffalo-reddy';
+// Within range of both Toronto and Buffalo.
+const BETWEEN = { lat: 43.25, lon: -79.1 };
+// Within range of Toronto only.
+const TORONTO_ONLY = { lat: 43.7, lon: -79.6 };
+// Within range of Buffalo only.
+const BUFFALO_ONLY = { lat: 42.5, lon: -78.0 };
+const LOW_M = 10_000;
+
+// disable() detaches a keydown listener; node has no document.
+globalThis.document ??= {
+  addEventListener() {},
+  removeEventListener() {},
+};
+
+/** A GBFS source whose per-city answers each test can change. */
+function makeSource() {
+  const cityOf = (url) => {
+    for (const [id, city] of CITY_BY_ID) {
+      if (url === city.stationInformationUrl) return { id, kind: 'info' };
+      if (url === city.stationStatusUrl) return { id, kind: 'status' };
+    }
+    throw new Error(`unexpected GBFS url ${url}`);
+  };
+  const source = {
+    dead: new Set(),
+    deadStatus: new Set(),
+    /** Optional per-call override: (cityId, kind) => Promise | undefined. */
+    hook: null,
+    async getStations(url, { signal } = {}) {
+      const { id, kind } = cityOf(url);
+      const hooked = source.hook?.(id, kind);
+      if (hooked) return hooked;
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      signal?.throwIfAborted();
+      if (source.dead.has(id)) throw new Error('GBFS HTTP 404');
+      if (kind === 'status' && source.deadStatus.has(id))
+        throw new Error('GBFS HTTP 503');
+      const city = CITY_BY_ID.get(id);
+      if (kind === 'info') {
+        return {
+          data: {
+            stations: [
+              {
+                station_id: `${id}-1`,
+                name: `${id} dock`,
+                lat: city.centerLat,
+                lon: city.centerLon,
+                capacity: 10,
+              },
+            ],
+          },
+        };
+      }
+      return {
+        data: {
+          stations: [
+            {
+              station_id: `${id}-1`,
+              num_bikes_available: 3,
+              num_docks_available: 7,
+              is_installed: true,
+              is_renting: true,
+              is_returning: true,
+            },
+          ],
+        },
+      };
+    },
+  };
+  return source;
+}
+
+/** Assemble the layer from its real parts around a camera the test moves. */
+function makeLiveLayer() {
+  const source = makeSource();
+  const services = {
+    render: { governorRequestRender() {} },
+    overlays: {
+      setOverlayEntries() {},
+      setOverlaySourceVisible() {},
+      clearOverlaySource() {},
+    },
+    sprites: { registerSpriteCollection() {}, restoreSpriteOrder() {} },
+    picking: { registerPickOwner() {}, unregisterPickOwner() {} },
+  };
+  const state = createState({ services });
+  const parts = {};
+  const context = { state, services, parts, source };
+  parts.ingestion = createIngestion(context);
+  parts.model = createModel(context);
+  parts.viewport = createViewport(context);
+  parts.rendering = createRendering(context);
+  // Selection owns a DOM click handler; nothing here selects a station.
+  parts.selection = {
+    _installClickHandler() {},
+    _clearSelection() {},
+    _onKeyDown() {},
+  };
+  parts.queries = { collectDetectableStations: () => [] };
+  parts.lifecycle = createLifecycle(context);
+  const { methods: controls } = createControls(context);
+
+  const camera = { ...BETWEEN, height: LOW_M };
+  const viewer = {
+    camera: {
+      get positionCartographic() {
+        return Cesium.Cartographic.fromDegrees(
+          camera.lon,
+          camera.lat,
+          camera.height,
+        );
+      },
+      computeViewRectangle: () => undefined,
+      changed: { addEventListener() {}, removeEventListener() {} },
+    },
+    scene: { globe: {}, primitives: { add() {}, remove() {} } },
+  };
+  parts.lifecycle.methods.init(viewer);
+
+  return {
+    state,
+    source,
+    stats: () => controls.getStats(),
+    moveTo(place, height = LOW_M) {
+      Object.assign(camera, place, { height });
+      return parts.viewport.runProximityCheck();
+    },
+    async enable() {
+      parts.lifecycle.methods.enable(viewer);
+      await settle();
+    },
+    disable: () => parts.lifecycle.methods.disable(viewer),
+    poll: () => parts.ingestion.methods.update(),
+  };
+}
+
+/** Let fire-and-forget activation started by enable() finish. */
+async function settle() {
+  for (let i = 0; i < 5; i += 1)
+    await new Promise((resolve) => setTimeout(resolve, 2));
+}
+
+function deferred() {
+  let resolve, reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+test('a city that fails beside one that renders reads DEGRADED, not healthy', async () => {
+  const layer = makeLiveLayer();
+  layer.source.dead.add(BUFFALO);
+  await layer.enable();
+
+  const stats = layer.stats();
+  assert.equal(stats.count, 1, 'Toronto should still draw');
+  assert.equal(stats.error, undefined);
+  assert.equal(stats.degraded, true, 'the Buffalo failure was hidden');
+  assert.equal(stats.stale, undefined);
+});
+
+test('a failed city that comes back clears its own failure', async () => {
+  const layer = makeLiveLayer();
+  layer.source.dead.add(BUFFALO);
+  await layer.enable();
+  assert.equal(layer.stats().degraded, true);
+
+  layer.source.dead.clear();
+  await layer.moveTo(BETWEEN);
+  const stats = layer.stats();
+  assert.equal(stats.count, 2);
+  assert.equal(stats.degraded, undefined);
+  assert.equal(stats.error, undefined);
+});
+
+test('a status poll that recovers clears the failure the last poll set', async () => {
+  const layer = makeLiveLayer();
+  await layer.moveTo(TORONTO_ONLY);
+  await layer.enable();
+  layer.source.deadStatus.add(TORONTO);
+  await layer.poll();
+  assert.equal(layer.stats().degraded, true);
+
+  layer.source.deadStatus.clear();
+  await layer.poll();
+  assert.equal(layer.stats().degraded, undefined);
+  assert.equal(layer.stats().stale, undefined);
+});
+
+test('a failure does not outlive its city leaving range', async () => {
+  const layer = makeLiveLayer();
+  layer.source.dead.add(BUFFALO);
+  await layer.enable();
+  await layer.moveTo(BUFFALO_ONLY);
+  assert.equal(layer.stats().error, 'GBFS fetch error');
+
+  // Low over the open Atlantic: nothing in range is empty, not broken.
+  await layer.moveTo({ lat: 30, lon: -40 });
+  const stats = layer.stats();
+  assert.equal(stats.count, 0);
+  assert.equal(stats.error, undefined, 'LOAD FAILED over empty ocean');
+  assert.equal(stats.degraded, undefined);
+});
+
+test('zooming out above the altitude gate drops a city failure', async () => {
+  const layer = makeLiveLayer();
+  layer.source.dead.add(BUFFALO);
+  await layer.enable();
+  await layer.moveTo(BUFFALO_ONLY);
+  assert.equal(layer.stats().error, 'GBFS fetch error');
+
+  await layer.moveTo(BUFFALO_ONLY, 200_000);
+  const stats = layer.stats();
+  assert.equal(stats.count, 0);
+  assert.equal(stats.error, undefined, 'LOAD FAILED above the gate');
+});
+
+test('a late rejection from before a disable/re-enable is ignored', async () => {
+  const layer = makeLiveLayer();
+  await layer.moveTo(BUFFALO_ONLY);
+  const first = deferred();
+  // The first info request hangs and ignores its abort signal.
+  layer.source.hook = (id, kind) => {
+    if (id !== BUFFALO || kind !== 'info') return undefined;
+    layer.source.hook = null;
+    return first.promise;
+  };
+  await layer.enable();
+  layer.disable();
+  await layer.enable();
+  assert.equal(layer.stats().count, 1, 're-enable should draw Buffalo');
+
+  first.reject(new Error('GBFS HTTP 500'));
+  await settle();
+  const stats = layer.stats();
+  assert.equal(stats.count, 1, 'a stale rejection tore down live points');
+  assert.equal(stats.error, undefined);
+  assert.equal(stats.degraded, undefined);
+});
+
+test('a late status poll rejection from before a disable/re-enable is ignored', async () => {
+  const layer = makeLiveLayer();
+  await layer.moveTo(TORONTO_ONLY);
+  await layer.enable();
+  const first = deferred();
+  layer.source.hook = (id, kind) => {
+    if (id !== TORONTO || kind !== 'status') return undefined;
+    layer.source.hook = null;
+    return first.promise;
+  };
+  const poll = layer.poll();
+  layer.disable();
+  await layer.enable();
+
+  first.reject(new Error('GBFS HTTP 500'));
+  await poll;
+  const stats = layer.stats();
+  assert.equal(stats.count, 1);
+  assert.equal(stats.degraded, undefined);
+  assert.equal(stats.error, undefined);
+});
+
+test('every status poll failing over cached points reads STALE, not fresh', async () => {
+  const layer = makeLiveLayer();
+  await layer.moveTo(TORONTO_ONLY);
+  await layer.enable();
+  const loadedAt = layer.stats().lastUpdate;
+  assert.ok(loadedAt, 'activation should record freshness');
+
+  layer.source.deadStatus.add(TORONTO);
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  await layer.poll();
+  const stats = layer.stats();
+  assert.equal(stats.count, 1, 'the cached points stay drawn');
+  assert.equal(stats.error, undefined);
+  assert.equal(stats.degraded, true);
+  assert.equal(stats.stale, true);
+  assert.equal(stats.lastUpdate, loadedAt, 'a failed poll advanced freshness');
+});

src/layers/bikeshare/ingestion.js

@@ -97,7 +97,10 @@ export function createIngestion({
         const payload = await fetchGbfsJson(city.stationInformationUrl, {
           signal: controller.signal,
         });
-        const stationMap = parts.model.parseStationInformation(payload);
+        const stationMap = parts.model.stationsWithinCity(
+          city,
+          parts.model.parseStationInformation(payload),
+        );
         if (stationMap.size === 0) {
           throw new Error(`No station information for ${city.city}`);
         }
@@ -171,30 +174,34 @@ export function createIngestion({
 
       const generation = layerState._proximityGeneration;
       const cityIds = Array.from(layerState._activeCityIds);
+      const isCurrent = (cityId) =>
+        layerState._enabled &&
+        layerState._activeCityIds.has(cityId) &&
+        generation === layerState._proximityGeneration;
+      let refreshed = false;
       await Promise.all(
         cityIds.map(async (cityId) => {
           try {
             const statusMap = await loadCityStationStatus(cityId, generation);
-            if (
-              !layerState._enabled ||
-              !layerState._activeCityIds.has(cityId) ||
-              generation !== layerState._proximityGeneration
-            )
-              return;
+            if (!isCurrent(cityId)) return;
             parts.rendering.applyStatusToPoints(cityId, statusMap);
+            layerState._failedCityIds.delete(cityId);
+            refreshed = true;
           } catch (error) {
-            if (error?.name === 'AbortError') return;
+            if (error?.name === 'AbortError' || !isCurrent(cityId)) return;
             console.warn(
               `[Data:Bikeshare] ${cityId} status update error:`,
               error,
             );
-            layerState._error = 'GBFS status update failed';
+            layerState._failedCityIds.add(cityId);
           }
         }),
       );
 
       layerState._count = layerState._stationRenderMap.size;
-      if (layerState._count > 0) layerState._lastUpdate = Date.now();
+      // Freshness advances only on a poll that actually refreshed a city.
+      if (refreshed && layerState._count > 0)
+        layerState._lastUpdate = Date.now();
     },
   };
 

src/layers/bikeshare/latamPbscCities.test.mjs

@@ -0,0 +1,174 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CITY_BY_ID } from './registry.js';
+import { createIngestion } from './ingestion.js';
+import { createModel } from './model.js';
+import { createViewport } from './viewport.js';
+import { isAllowedGbfsHost, isAllowedGbfsPath } from '../../data/gbfsSource.js';
+
+// Each system's PBSC host, the station farthest from its registered centre,
+// and the depots its live feed lists on other continents (checked 2026-10-16).
+const CITIES = {
+  'bogota-tembici': {
+    host: 'bogota.publicbikesystem.net',
+    provider: 'Tembici Bogotá',
+    stations: [
+      { name: '067 - KR 7B Bis con CL 152A', lat: 4.727729, lon: -74.026271 },
+    ],
+    depots: [
+      {
+        station_id: '316',
+        name: 'Calle 13 - 316',
+        lat: -23.4008649,
+        lon: -46.3972181,
+      },
+    ],
+  },
+  'santiago-bike-itau': {
+    host: 'santiago.publicbikesystem.net',
+    provider: 'Bike Itaú Santiago',
+    stations: [
+      { name: 'LC077 - Mall Sport', lat: -33.3707813, lon: -70.5073122 },
+    ],
+    depots: [
+      {
+        station_id: '459',
+        name: 'Galpon - 459',
+        lat: 40.4167747,
+        lon: -3.7037899,
+      },
+      {
+        station_id: '440',
+        name: 'Galpon - 440',
+        lat: -23.5690975,
+        lon: -46.697366,
+      },
+    ],
+  },
+};
+
+// The production range check, with no viewer or fetches behind it.
+const parts = {
+  model: createModel({ state: {}, services: {}, parts: {}, source: null }),
+};
+const { computeInRangeCities } = createViewport({
+  state: {},
+  services: { render: { governorRequestRender() {} } },
+  parts,
+  source: null,
+});
+
+test('Bogotá and Santiago are registered and readable through the proxy', () => {
+  for (const [id, expected] of Object.entries(CITIES)) {
+    const city = CITY_BY_ID.get(id);
+    assert.ok(city, `${id} is registered`);
+    assert.equal(city.provider, expected.provider);
+    assert.deepEqual(city.hosts, [expected.host]);
+    for (const feed of [city.stationInformationUrl, city.stationStatusUrl]) {
+      const url = new URL(feed);
+      assert.ok(isAllowedGbfsHost(url.hostname), `${id} host ${url.hostname}`);
+      assert.ok(isAllowedGbfsPath(url.pathname), `${id} path ${url.pathname}`);
+    }
+  }
+});
+
+test('a camera over each outermost station activates its system', () => {
+  for (const [id, expected] of Object.entries(CITIES)) {
+    for (const station of expected.stations) {
+      assert.ok(
+        computeInRangeCities({ lat: station.lat, lon: station.lon }).has(id),
+        `${station.name} activates ${id}`,
+      );
+    }
+  }
+});
+
+test('each load radius reaches its outermost stations', () => {
+  // The range check floors every radius at 100 km; the station filter and
+  // get_bike_share use the radius as registered.
+  for (const [id, expected] of Object.entries(CITIES)) {
+    const city = CITY_BY_ID.get(id);
+    for (const station of expected.stations) {
+      const distance = parts.model.haversineKm(
+        city.centerLat,
+        city.centerLon,
+        station.lat,
+        station.lon,
+      );
+      assert.ok(
+        distance <= city.loadRadiusKm,
+        `${station.name} is ${distance.toFixed(1)} km from the ${id} centre`,
+      );
+    }
+  }
+});
+
+test('stations a feed lists on another continent are not loaded', async () => {
+  for (const [id, expected] of Object.entries(CITIES)) {
+    const city = CITY_BY_ID.get(id);
+    const outermost = expected.stations[0];
+    const payload = {
+      data: {
+        stations: [
+          {
+            station_id: 'local',
+            name: outermost.name,
+            lat: outermost.lat,
+            lon: outermost.lon,
+          },
+          ...expected.depots,
+        ],
+      },
+    };
+    const state = {
+      _stationInfoCache: new Map(),
+      _inFlightInfo: new Map(),
+      _inFlightStatus: new Map(),
+      _loadingOps: 0,
+      _loading: false,
+    };
+    const ingestion = createIngestion({
+      state,
+      services: {},
+      parts,
+      source: {
+        async getStations(url) {
+          assert.equal(url, city.stationInformationUrl);
+          return payload;
+        },
+      },
+    });
+
+    const stations = await ingestion.loadCityStationInfo(id, 1);
+    assert.deepEqual(
+      [...stations.keys()],
+      ['local'],
+      `${id} keeps only local stations`,
+    );
+    assert.equal(state._stationInfoCache.get(id), stations);
+  }
+});
+
+test('a feed with only far-away stations reports no station information', async () => {
+  const city = CITY_BY_ID.get('santiago-bike-itau');
+  const ingestion = createIngestion({
+    state: {
+      _stationInfoCache: new Map(),
+      _inFlightInfo: new Map(),
+      _inFlightStatus: new Map(),
+      _loadingOps: 0,
+      _loading: false,
+    },
+    services: {},
+    parts,
+    source: {
+      async getStations() {
+        return { data: { stations: CITIES['santiago-bike-itau'].depots } };
+      },
+    },
+  });
+  await assert.rejects(
+    ingestion.loadCityStationInfo('santiago-bike-itau', 1),
+    new RegExp(`No station information for ${city.city}`),
+  );
+});

src/layers/bikeshare/lifecycle.js

@@ -51,7 +51,7 @@ export function createLifecycle({
       layerState._lastUpdate = null;
       layerState._loading = false;
       layerState._loadingOps = 0;
-      layerState._error = null;
+      layerState._failedCityIds.clear();
       layerState._limitWarned = false;
 
       layerState._overlayHost.setVisible(
@@ -75,7 +75,7 @@ export function createLifecycle({
      */
     enable(viewer) {
       layerState._enabled = true;
-      layerState._error = null;
+      layerState._failedCityIds.clear();
       layerState._pointCollection.show = true;
       layerState._overlayHost.setVisible(
         BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,

src/layers/bikeshare/model.js

@@ -5,6 +5,7 @@ import {
   parseStationStatus,
   toNonNegativeInteger,
 } from '../../sources/gbfsStations.js';
+import { greatCircleKm } from '../../geoDistance.js';
 
 export function createModel({ state: layerState, services, parts, source }) {
   /**
@@ -28,15 +29,31 @@ export function createModel({ state: layerState, services, parts, source }) {
    */
 
   function haversineKm(aLat, aLon, bLat, bLon) {
-    const toRad = (value) => (value * Math.PI) / 180;
-    const dLat = toRad(bLat - aLat);
-    const dLon = toRad(bLon - aLon);
-    const p1 = toRad(aLat);
-    const p2 = toRad(bLat);
-    const a =
-      Math.sin(dLat / 2) ** 2 +
-      Math.cos(p1) * Math.cos(p2) * Math.sin(dLon / 2) ** 2;
-    return 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return greatCircleKm({ lat: aLat, lon: aLon }, { lat: bLat, lon: bLon });
+  }
+
+  /**
+   * Drop stations outside a city's load radius. Some operators list depots on
+   * other continents as in-service stations in a city's feed (Bogotá's and
+   * Santiago's PBSC feeds carry warehouses in São Paulo and Madrid), which
+   * would otherwise draw as live docks thousands of kilometres away.
+   * @param {{ centerLat: number, centerLon: number, loadRadiusKm: number }} city
+   * @param {Map<string, Object>} stationMap - Parsed station info map.
+   * @returns {Map<string, Object>} Stations within the city's load radius.
+   */
+
+  function stationsWithinCity(city, stationMap) {
+    const kept = new Map();
+    for (const [stationId, station] of stationMap) {
+      const distance = haversineKm(
+        city.centerLat,
+        city.centerLon,
+        station.lat,
+        station.lon,
+      );
+      if (distance <= city.loadRadiusKm) kept.set(stationId, station);
+    }
+    return kept;
   }
 
   return {
@@ -44,6 +61,7 @@ export function createModel({ state: layerState, services, parts, source }) {
     toNonNegativeInteger,
     stationKey,
     haversineKm,
+    stationsWithinCity,
     extractStationsArray,
     parseStationInformation,
     parseStationStatus,

src/layers/bikeshare/policy.js

@@ -11,7 +11,7 @@ export const BIKESHARE_SELECTED_OVERLAY_SOURCE_OPTIONS = Object.freeze({
 // --- Activation / display thresholds ---
 /** Altitude (m) at which bikeshare layer becomes eligible for display. */
 
-export const ACTIVATION_ALTITUDE_M = 50000;
+const ACTIVATION_ALTITUDE_M = 50000;
 
 /** Hysteresis enter threshold — layer activates when camera drops below this. */
 

src/layers/bikeshare/proxyRoute.test.mjs

@@ -10,13 +10,19 @@
 // Run with: npm test
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { rm } from 'node:fs/promises';
 import { gbfsProxy } from '../../../server/providers/gbfs.js';
 import { localProviderPlugins } from '../../../server/providers/local.js';
 import { createBikeshareSource } from './source.js';
 import { createModel } from './model.js';
 import { CITY_BY_ID } from './registry.js';
+import { makeFixtureRoot } from '../../tooling/fixtureRoot.mjs';
+
+const nominatimStorageDir = await makeFixtureRoot('gev-gbfs-composition-');
+test.after(() => rm(nominatimStorageDir, { recursive: true, force: true }));
 
 const AUSTIN = CITY_BY_ID.get('austin-capmetro');
+const OSLO = CITY_BY_ID.get('oslo-bysykkel');
 
 const STATION_INFORMATION = {
   data: {
@@ -204,6 +210,101 @@ test('the proxy relays its cache policy and upstream host through the mounted ro
   );
 });
 
+test('the Norwegian city-bike systems are served through the mounted route', async () => {
+  for (const [id, systemId] of [
+    ['oslo-bysykkel', 'oslobysykkel.no'],
+    ['bergen-bysykkel', 'bergenbysykkel.no'],
+    ['trondheim-bysykkel', 'trondheimbysykkel.no'],
+  ]) {
+    const system = CITY_BY_ID.get(id);
+    assert.ok(system, `${id} is registered`);
+    assert.deepEqual(system.hosts, ['gbfs.urbansharing.com']);
+    assert.equal(
+      system.stationStatusUrl,
+      `https://gbfs.urbansharing.com/${systemId}/station_status.json`,
+    );
+  }
+
+  await withUpstream(
+    {
+      [OSLO.stationInformationUrl]: STATION_INFORMATION,
+      [OSLO.stationStatusUrl]: STATION_STATUS,
+    },
+    async (requested) => {
+      const source = createBikeshareSource({ fetchImpl: mountGbfsProxy() });
+      const info = await source.getStations(OSLO.stationInformationUrl);
+      const status = await source.getStations(OSLO.stationStatusUrl);
+      assert.deepEqual(requested, [
+        OSLO.stationInformationUrl,
+        OSLO.stationStatusUrl,
+      ]);
+      assert.equal(info.data.stations.length, 1);
+      assert.equal(status.data.stations.length, 1);
+
+      const response = await mountGbfsProxy()(
+        '/api/gbfs/' + encodeURIComponent(OSLO.stationStatusUrl),
+      );
+      assert.equal(response.status, 200);
+      assert.equal(
+        response.headers.get('x-gbfs-upstream'),
+        'gbfs.urbansharing.com',
+      );
+    },
+  );
+});
+
+test('every Norwegian city-bike system is registered and reachable through the mounted route', async () => {
+  const expected = {
+    'stavanger-kolumbus':
+      'https://api.entur.io/mobility/v2/gbfs/v2/kolumbusbysykkel/station_status',
+    'skien-farte':
+      'https://api.entur.io/mobility/v2/gbfs/v2/fartebysykkel/station_status',
+    'lillestrom-bysykkel':
+      'https://api.cyclocity.fr/contracts/lillestrom/gbfs/station_status.json',
+  };
+  const upstream = {};
+  for (const [id, statusUrl] of Object.entries(expected)) {
+    const system = CITY_BY_ID.get(id);
+    assert.ok(system, `${id} is registered`);
+    assert.equal(system.stationStatusUrl, statusUrl);
+    upstream[system.stationInformationUrl] = STATION_INFORMATION;
+    upstream[system.stationStatusUrl] = STATION_STATUS;
+  }
+
+  await withUpstream(upstream, async (requested) => {
+    const source = createBikeshareSource({ fetchImpl: mountGbfsProxy() });
+    for (const id of Object.keys(expected)) {
+      const system = CITY_BY_ID.get(id);
+      const info = await source.getStations(system.stationInformationUrl);
+      const status = await source.getStations(system.stationStatusUrl);
+      assert.equal(info.data.stations.length, 1, `${id} information`);
+      assert.equal(status.data.stations.length, 1, `${id} status`);
+    }
+    assert.equal(requested.length, 6);
+
+    // Entur's extensionless station_information keeps its 5-minute cache.
+    const kolumbus = CITY_BY_ID.get('stavanger-kolumbus');
+    const response = await mountGbfsProxy()(
+      '/api/gbfs/' + encodeURIComponent(kolumbus.stationInformationUrl),
+    );
+    assert.equal(response.headers.get('cache-control'), 'public, max-age=300');
+  });
+});
+
+test('the mounted route keeps multi-API hosts to their GBFS tree', async () => {
+  await withUpstream({}, async (requested) => {
+    const mounted = mountGbfsProxy();
+    for (const target of [
+      'https://api.entur.io/journey-planner/v3/station_status',
+      'https://api.cyclocity.fr/other/station_status.json',
+    ]) {
+      const response = await mounted('/api/gbfs/' + encodeURIComponent(target));
+      assert.equal(response.status, 400, target);
+    }
+    assert.deepEqual(requested, []);
+  });
+});
+
 test('the query-string shape the client used to send is refused by the mounted route', async () => {
   await withUpstream(
     { [AUSTIN.stationStatusUrl]: STATION_STATUS },
@@ -243,7 +344,7 @@ test('the mounted route still refuses a host outside the allowlist', async () =>
  * or from the preview half of it — fails here rather than in a browser.
  */
 function composedGbfsPlugin() {
-  const plugin = localProviderPlugins().find(
+  const plugin = localProviderPlugins({ nominatimStorageDir }).find(
     (entry) => entry.name === 'gbfs-proxy',
   );
   assert.ok(plugin, 'the application must compose a GBFS provider');
@@ -298,3 +399,55 @@ for (const hook of ['configureServer', 'configurePreviewServer']) {
     );
   });
 }
+
+test('unknown GBFS counts stay unknown through the source, model and station color', async () => {
+  const { createRendering } = await import('./rendering.js');
+  const { COLOR_NEUTRAL, COLOR_RED } = await import('./policy.js');
+  for (const missing of [null, '']) {
+    const source = createBikeshareSource({
+      fetchImpl: async () =>
+        Response.json({
+          data: {
+            stations: [
+              {
+                station_id: '2537',
+                num_bikes_available: missing,
+                num_docks_available: 4,
+                is_installed: true,
+                is_renting: true,
+                is_returning: true,
+              },
+            ],
+          },
+        }),
+    });
+    const model = createModel({});
+    const status = model
+      .parseStationStatus(await source.getStations(AUSTIN.stationStatusUrl))
+      .get('2537');
+    const rendering = createRendering({
+      state: {},
+      services: { render: {} },
+      parts: { model },
+    });
+    assert.equal(status.bikesAvailable, null);
+    assert.equal(
+      model.toNonNegativeInteger(status.bikesAvailable),
+      null,
+      'render-map normalization preserves unknown',
+    );
+    assert.equal(rendering.statusToColor(status, 12), COLOR_NEUTRAL);
+    assert.equal(rendering.resolveCapacity(missing, status), 4);
+    assert.equal(
+      rendering.statusToColor({ ...status, bikesAvailable: 0 }, 12),
+      COLOR_RED,
+      'reported zero is still empty',
+    );
+    assert.equal(
+      model.toNonNegativeInteger(missing, 7),
+      7,
+      'caller fallback is preserved',
+    );
+    assert.equal(model.toNonNegativeInteger('3'), 3);
+  }
+});

src/layers/bikeshare/registry.js

@@ -23,6 +23,47 @@ function bcycleEntry({
     ...buildBcycleUrls(systemId),
   };
 }
+function urbanSharingEntry({
+  id,
+  city,
+  centerLat,
+  centerLon,
+  systemId,
+  provider,
+  loadRadiusKm = 100,
+}) {
+  return {
+    id,
+    city,
+    centerLat,
+    centerLon,
+    loadRadiusKm,
+    provider,
+    stationInformationUrl: `https://gbfs.urbansharing.com/${systemId}/station_information.json`,
+    stationStatusUrl: `https://gbfs.urbansharing.com/${systemId}/station_status.json`,
+  };
+}
+function enturEntry({
+  id,
+  city,
+  centerLat,
+  centerLon,
+  systemId,
+  provider,
+  loadRadiusKm = 100,
+}) {
+  const base = `https://api.entur.io/mobility/v2/gbfs/v2/${systemId}`;
+  return {
+    id,
+    city,
+    centerLat,
+    centerLon,
+    loadRadiusKm,
+    provider,
+    stationInformationUrl: `${base}/station_information`,
+    stationStatusUrl: `${base}/station_status`,
+  };
+}
 const RAW_GBFS_CITY_REGISTRY = [
   {
     id: 'nyc-citibike',
@@ -48,6 +89,56 @@ const RAW_GBFS_CITY_REGISTRY = [
       'https://gbfs.lyft.com/gbfs/2.3/chi/en/station_status.json',
     provider: 'Divvy',
   },
+  {
+    id: 'detroit-mogo',
+    city: 'Detroit, MI',
+    centerLat: 42.3314,
+    centerLon: -83.0458,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://detroit.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://detroit.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'MoGo',
+  },
+  {
+    id: 'pittsburgh-pogoh',
+    city: 'Pittsburgh, PA',
+    centerLat: 40.4406,
+    centerLon: -79.9959,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://pittsburgh.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://pittsburgh.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'POGOH',
+  },
+  {
+    id: 'aspen-we-cycle',
+    city: 'Aspen, CO',
+    centerLat: 39.1911,
+    centerLon: -106.8175,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://aspen.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://aspen.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'WE-cycle',
+  },
+  // HIBike serves both Kailua-Kona and Hilo, about 95 km apart; the centre sits
+  // between them so a camera over either town loads the whole system.
+  {
+    id: 'hawaii-island-hibike',
+    city: 'Kona & Hilo, HI',
+    centerLat: 19.68,
+    centerLon: -155.54,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://kona.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://kona.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'HIBike',
+  },
   {
     id: 'dc-capital-bikeshare',
     city: 'Washington, DC',
@@ -143,18 +234,6 @@ const RAW_GBFS_CITY_REGISTRY = [
       'https://hon.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
     provider: 'Biki',
   },
-  {
-    id: 'columbus-cogo',
-    city: 'Columbus, OH',
-    centerLat: 39.9612,
-    centerLon: -82.9988,
-    loadRadiusKm: 90,
-    stationInformationUrl:
-      'https://gbfs.cogobikeshare.com/gbfs/2.3/en/station_information.json',
-    stationStatusUrl:
-      'https://gbfs.cogobikeshare.com/gbfs/2.3/en/station_status.json',
-    provider: 'CoGo',
-  },
   {
     id: 'chattanooga-bikechatt',
     city: 'Chattanooga, TN',
@@ -167,6 +246,126 @@ const RAW_GBFS_CITY_REGISTRY = [
       'https://chat.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
     provider: 'Bike Chattanooga',
   },
+  {
+    id: 'sao-paulo-bike-itau',
+    city: 'São Paulo, SP',
+    centerLat: -23.5505,
+    centerLon: -46.6333,
+    loadRadiusKm: 100,
+    stationInformationUrl:
+      'https://saopaulo.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://saopaulo.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Itaú',
+  },
+  {
+    id: 'rio-de-janeiro-bike-itau',
+    city: 'Rio de Janeiro, RJ',
+    centerLat: -22.9068,
+    centerLon: -43.1729,
+    loadRadiusKm: 100,
+    stationInformationUrl:
+      'https://riodejaneiro.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://riodejaneiro.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Itaú',
+  },
+  {
+    id: 'salvador-bike-itau',
+    city: 'Salvador, BA',
+    centerLat: -12.9777,
+    centerLon: -38.5016,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://salvador.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://salvador.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Itaú',
+  },
+  {
+    id: 'recife-bike-itau',
+    city: 'Recife, PE',
+    centerLat: -8.0476,
+    centerLon: -34.877,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://recife.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://recife.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Itaú',
+  },
+  {
+    id: 'porto-alegre-bike-itau',
+    city: 'Porto Alegre, RS',
+    centerLat: -30.0346,
+    centerLon: -51.2177,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://portoalegre.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://portoalegre.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Itaú',
+  },
+  {
+    id: 'brasilia-bike-itau',
+    city: 'Brasília, DF',
+    centerLat: -15.7939,
+    centerLon: -47.8828,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://brasilia.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://brasilia.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Itaú',
+  },
+  {
+    id: 'curitiba-bike-itau',
+    city: 'Curitiba, PR',
+    centerLat: -25.4284,
+    centerLon: -49.2733,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://curitiba.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://curitiba.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Itaú',
+  },
+  {
+    id: 'bogota-tembici',
+    city: 'Bogotá, Colombia',
+    centerLat: 4.6533,
+    centerLon: -74.0836,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://bogota.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://bogota.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Tembici Bogotá',
+  },
+  {
+    id: 'santiago-bike-itau',
+    city: 'Santiago, Chile',
+    centerLat: -33.4372,
+    centerLon: -70.6506,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://santiago.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://santiago.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Itaú Santiago',
+  },
+  {
+    id: 'toronto-bike-share',
+    city: 'Toronto, ON',
+    centerLat: 43.6532,
+    centerLon: -79.3832,
+    loadRadiusKm: 90,
+    stationInformationUrl:
+      'https://toronto.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://toronto.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bike Share Toronto',
+  },
   bcycleEntry({
     id: 'boulder-bcycle',
     city: 'Boulder, CO',
@@ -234,14 +433,6 @@ const RAW_GBFS_CITY_REGISTRY = [
     systemId: 'bcycle_pacersbikeshare',
     provider: 'Pacers Bikeshare',
   }),
-  bcycleEntry({
-    id: 'fort-lauderdale-broward',
-    city: 'Fort Lauderdale, FL',
-    centerLat: 26.1224,
-    centerLon: -80.1373,
-    systemId: 'bcycle_broward',
-    provider: 'Broward B-cycle',
-  }),
   bcycleEntry({
     id: 'memphis-bcycle',
     city: 'Memphis, TN',
@@ -256,22 +447,32 @@ const RAW_GBFS_CITY_REGISTRY = [
     centerLon: -93.625,
     systemId: 'bcycle_desmoines',
   }),
-  bcycleEntry({
+  {
+    // Tugo moved off BCycle to PBSC; the bcycle_tugo feed is gone (404).
     id: 'tucson-tugo',
     city: 'Tucson, AZ',
     centerLat: 32.2226,
     centerLon: -110.9747,
-    systemId: 'bcycle_tugo',
+    loadRadiusKm: 100,
+    stationInformationUrl:
+      'https://tucson.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://tucson.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
     provider: 'Tugo',
-  }),
-  bcycleEntry({
+  },
+  {
+    // Trinity Metro moved off BCycle to PBSC; the bcycle_fortworth feed is gone.
     id: 'fort-worth-trinity',
     city: 'Fort Worth, TX',
     centerLat: 32.7555,
     centerLon: -97.3308,
-    systemId: 'bcycle_fortworth',
+    loadRadiusKm: 100,
+    stationInformationUrl:
+      'https://fortworth.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://fortworth.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
     provider: 'Trinity Metro',
-  }),
+  },
   bcycleEntry({
     id: 'omaha-heartland',
     city: 'Omaha, NE',
@@ -295,14 +496,20 @@ const RAW_GBFS_CITY_REGISTRY = [
     centerLon: -82.394,
     systemId: 'bcycle_greenville',
   }),
-  bcycleEntry({
+  {
+    // Reddy left BCycle for Social Bicycles; the bcycle_reddy feed is gone
+    // (404). This is the endpoint the MobilityData GBFS registry lists.
     id: 'buffalo-reddy',
     city: 'Buffalo, NY',
     centerLat: 42.8864,
     centerLon: -78.8784,
-    systemId: 'bcycle_reddy',
+    loadRadiusKm: 100,
+    stationInformationUrl:
+      'https://reddybikeshare.socialbicycles.com/opendata/station_information.json',
+    stationStatusUrl:
+      'https://reddybikeshare.socialbicycles.com/opendata/station_status.json',
     provider: 'Reddy Bikeshare',
-  }),
+  },
   bcycleEntry({
     id: 'las-vegas-rtc-bike-share',
     city: 'Las Vegas, NV',
@@ -318,6 +525,193 @@ const RAW_GBFS_CITY_REGISTRY = [
     centerLon: -119.6982,
     systemId: 'bcycle_santabarbara',
   }),
+  urbanSharingEntry({
+    id: 'oslo-bysykkel',
+    city: 'Oslo, Norway',
+    centerLat: 59.9139,
+    centerLon: 10.7522,
+    systemId: 'oslobysykkel.no',
+    provider: 'Oslo Bysykkel',
+  }),
+  urbanSharingEntry({
+    id: 'bergen-bysykkel',
+    city: 'Bergen, Norway',
+    centerLat: 60.3913,
+    centerLon: 5.3221,
+    systemId: 'bergenbysykkel.no',
+    provider: 'Bergen Bysykkel',
+  }),
+  urbanSharingEntry({
+    id: 'trondheim-bysykkel',
+    city: 'Trondheim, Norway',
+    centerLat: 63.4305,
+    centerLon: 10.3951,
+    systemId: 'trondheimbysykkel.no',
+    provider: 'Trondheim Bysykkel',
+  }),
+  enturEntry({
+    id: 'stavanger-kolumbus',
+    city: 'Stavanger, Norway',
+    centerLat: 58.9,
+    centerLon: 5.72,
+    systemId: 'kolumbusbysykkel',
+    provider: 'Kolumbus Bysykkel',
+  }),
+  enturEntry({
+    id: 'skien-farte',
+    city: 'Skien/Porsgrunn, Norway',
+    centerLat: 59.16,
+    centerLon: 9.64,
+    systemId: 'fartebysykkel',
+    provider: 'Farte Bysykkel',
+    loadRadiusKm: 40,
+  }),
+  {
+    id: 'lillestrom-bysykkel',
+    city: 'Lillestrøm, Norway',
+    centerLat: 59.9556,
+    centerLon: 11.0492,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://api.cyclocity.fr/contracts/lillestrom/gbfs/station_information.json',
+    stationStatusUrl:
+      'https://api.cyclocity.fr/contracts/lillestrom/gbfs/station_status.json',
+    provider: 'Bysykkel Lillestrøm',
+  },
+  {
+    id: 'barcelona-bicing',
+    city: 'Barcelona, Spain',
+    centerLat: 41.3926,
+    centerLon: 2.164,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://barcelona.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://barcelona.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bicing',
+  },
+  // AMBici covers the metropolitan municipalities around Barcelona, from
+  // Castelldefels to Badalona, and overlaps Bicing only at the city edge.
+  {
+    id: 'barcelona-ambici',
+    city: 'Barcelona metropolitan area, Spain',
+    centerLat: 41.37,
+    centerLon: 2.07,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://gbfs.nextbike.net/maps/gbfs/v2/nextbike_bs/en/station_information.json',
+    stationStatusUrl:
+      'https://gbfs.nextbike.net/maps/gbfs/v2/nextbike_bs/en/station_status.json',
+    provider: 'AMBici',
+  },
+  {
+    id: 'madrid-bicimad',
+    city: 'Madrid, Spain',
+    centerLat: 40.4241,
+    centerLon: -3.6825,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://madrid.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://madrid.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'BiciMAD',
+  },
+  {
+    id: 'valencia-valenbisi',
+    city: 'Valencia, Spain',
+    centerLat: 39.4706,
+    centerLon: -0.3749,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://api.cyclocity.fr/contracts/valence/gbfs/station_information.json',
+    stationStatusUrl:
+      'https://api.cyclocity.fr/contracts/valence/gbfs/station_status.json',
+    provider: 'Valenbisi',
+  },
+  {
+    id: 'zaragoza-bizi',
+    city: 'Zaragoza, Spain',
+    centerLat: 41.6481,
+    centerLon: -0.8927,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://zaragoza.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://zaragoza.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bizi Zaragoza',
+  },
+  {
+    id: 'sevilla-sevici',
+    city: 'Seville, Spain',
+    centerLat: 37.3726,
+    centerLon: -5.9607,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://api.cyclocity.fr/contracts/seville/gbfs/station_information.json',
+    stationStatusUrl:
+      'https://api.cyclocity.fr/contracts/seville/gbfs/station_status.json',
+    provider: 'Sevici',
+  },
+  {
+    id: 'valladolid-biki',
+    city: 'Valladolid, Spain',
+    centerLat: 41.6233,
+    centerLon: -4.7382,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://valladolid.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://valladolid.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'BIKI',
+  },
+  {
+    id: 'a-coruna-bicicoruna',
+    city: 'A Coruña, Spain',
+    centerLat: 43.3534,
+    centerLon: -8.4156,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://acoruna.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://acoruna.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'BiciCoruña',
+  },
+  {
+    id: 'donostia-dbizi',
+    city: 'Donostia-San Sebastián, Spain',
+    centerLat: 43.3075,
+    centerLon: -1.9696,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://sansebastian.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://sansebastian.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Dbizi',
+  },
+  {
+    id: 'bilbao-bilbaobizi',
+    city: 'Bilbao, Spain',
+    centerLat: 43.2624,
+    centerLon: -2.9367,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://bilbao.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://bilbao.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'Bilbao Bizi',
+  },
+  {
+    id: 'rivas-bicinrivas',
+    city: 'Rivas-Vaciamadrid, Spain',
+    centerLat: 40.3535,
+    centerLon: -3.5319,
+    loadRadiusKm: 40,
+    stationInformationUrl:
+      'https://rivas.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+    stationStatusUrl:
+      'https://rivas.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+    provider: 'BicinRivas',
+  },
 ];
 function normalizeRegistryEntry(entry) {
   const id = String(entry?.id || '')
@@ -346,11 +740,13 @@ function normalizeRegistryEntry(entry) {
   ) {
     throw new Error(`GBFS entry "${id}" must use https URLs`);
   }
-  // Validate that URLs end with expected GBFS endpoint filenames
-  if (!/\/station_information\.json$/i.test(stationInformationUrl.pathname)) {
+  // Validate that URLs end with expected GBFS endpoint names (Entur omits .json)
+  if (
+    !/\/station_information(\.json)?$/i.test(stationInformationUrl.pathname)
+  ) {
     throw new Error(`GBFS entry "${id}" station_information URL is invalid`);
   }
-  if (!/\/station_status\.json$/i.test(stationStatusUrl.pathname)) {
+  if (!/\/station_status(\.json)?$/i.test(stationStatusUrl.pathname)) {
     throw new Error(`GBFS entry "${id}" station_status URL is invalid`);
   }
 

src/layers/bikeshare/registry.test.mjs

@@ -0,0 +1,58 @@
+// BIKESHARE REGISTRY — a city entry is only useful if the proxy will serve it.
+//
+// A registry entry and the GBFS proxy allowlist are edited in different files,
+// so a city can look correctly registered while every one of its requests is
+// rejected at the proxy. These cases hold the two together: each entry is
+// checked against the same host and path predicates the proxy enforces, so a
+// new city that the proxy would refuse fails here rather than silently
+// rendering an empty layer.
+//
+// Run with: npm test
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { GBFS_CITY_REGISTRY, CITY_BY_ID } from './registry.js';
+import { isAllowedGbfsHost, isAllowedGbfsPath } from '../../data/gbfsSource.js';
+
+test('every registered city is reachable through the GBFS proxy allowlist', () => {
+  for (const city of GBFS_CITY_REGISTRY) {
+    for (const raw of [city.stationInformationUrl, city.stationStatusUrl]) {
+      const url = new URL(raw);
+      assert.equal(
+        isAllowedGbfsHost(url.hostname),
+        true,
+        `${city.id}: host ${url.hostname} is not allowlisted`,
+      );
+      assert.equal(
+        isAllowedGbfsPath(url.pathname, url.hostname),
+        true,
+        `${city.id}: path ${url.pathname} is not allowlisted`,
+      );
+    }
+  }
+});
+
+test('Bike Share Toronto is registered against the PBSC v2 feeds', () => {
+  const toronto = CITY_BY_ID.get('toronto-bike-share');
+  assert.ok(toronto, 'toronto-bike-share is missing from the registry');
+  assert.equal(toronto.city, 'Toronto, ON');
+  assert.equal(toronto.provider, 'Bike Share Toronto');
+  assert.equal(
+    toronto.stationInformationUrl,
+    'https://toronto.publicbikesystem.net/customer/gbfs/v2/en/station_information.json',
+  );
+  assert.equal(
+    toronto.stationStatusUrl,
+    'https://toronto.publicbikesystem.net/customer/gbfs/v2/en/station_status.json',
+  );
+});
+
+test('the Toronto center sits inside the system service area', () => {
+  const toronto = CITY_BY_ID.get('toronto-bike-share');
+  // Bounding box of the 1,069 live stations, sampled from the published
+  // station_information feed: 43.588..43.813 N, -79.603..-79.123 W.
+  assert.ok(toronto.centerLat > 43.588 && toronto.centerLat < 43.813);
+  assert.ok(toronto.centerLon > -79.603 && toronto.centerLon < -79.123);
+  // The system spans roughly 37 km east-west, so the load radius has to clear
+  // half that from the center or downtown pans lose the outer stations.
+  assert.ok(toronto.loadRadiusKm >= 25);
+});

src/layers/bikeshare/selection.js

@@ -1,4 +1,5 @@
 import * as Cesium from 'cesium';
+import { t } from '../../i18n/index.js';
 import { isPointerFree } from '../../data/inputOwnership.js';
 import {
   BIKESHARE_SELECTED_OVERLAY_SOURCE_ID,
@@ -22,7 +23,9 @@ export function createSelection({
     const stationName = String(record?.stationName || '').trim();
     const stationLabel =
       stationName ||
-      (record?.stationId ? `Station ${record.stationId}` : 'Station');
+      (record?.stationId
+        ? t('Station {id}', { id: record.stationId })
+        : t('Station'));
     const bikes = Number.isFinite(record?.bikesAvailable)
       ? record.bikesAvailable
       : '?';
@@ -33,14 +36,18 @@ export function createSelection({
 
     const lines = [
       stationLabel,
-      `🚲 ${bikes} avail · ${docks} docks · ${capacity} cap`,
+      t('🚲 {bikes} avail · {docks} docks · {capacity} cap', {
+        bikes,
+        docks,
+        capacity,
+      }),
     ];
 
     // Append warnings for stations that are offline or partially non-operational
     const abnormal = [];
-    if (record?.isInstalled === false) abnormal.push('⚠️ Not installed');
-    if (record?.isRenting === false) abnormal.push('⚠️ Not renting');
-    if (record?.isReturning === false) abnormal.push('⚠️ Not returning');
+    if (record?.isInstalled === false) abnormal.push(t('⚠️ Not installed'));
+    if (record?.isRenting === false) abnormal.push(t('⚠️ Not renting'));
+    if (record?.isReturning === false) abnormal.push(t('⚠️ Not returning'));
     if (abnormal.length > 0) {
       lines.push(abnormal.join(' · '));
     }

src/layers/bikeshare/spainCitiesSystems.test.mjs

@@ -0,0 +1,256 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CITY_BY_ID } from './registry.js';
+import { createIngestion } from './ingestion.js';
+import { createModel } from './model.js';
+import { createViewport } from './viewport.js';
+import { isAllowedGbfsHost, isAllowedGbfsPath } from '../../data/gbfsSource.js';
+
+// Each system's host, its stations farthest from the registered centre in
+// opposite directions, and the stations its live feed lists away from the
+// city: a workshop at (0,0), a lab in Madrid, planned sites with no position
+// yet (checked 2026-10-17). JCDecaux names keep their feed spelling here.
+const SYSTEMS = {
+  'madrid-bicimad': {
+    host: 'madrid.publicbikesystem.net',
+    provider: 'BiciMAD',
+    stations: [
+      {
+        name: '627 - Alcalde Andrés Madrid Dávila, 92',
+        lat: 40.398303,
+        lon: -3.548534,
+      },
+      {
+        name: '672 - Estación de tren de El Barrial-Pozuelo',
+        lat: 40.464908,
+        lon: -3.807764,
+      },
+    ],
+  },
+  'valencia-valenbisi': {
+    host: 'api.cyclocity.fr',
+    provider: 'Valenbisi',
+    stations: [
+      { name: '_CAMPAMENTO_81', lat: 39.499875, lon: -0.426354 },
+      { name: '_EDIFICIO_VELES_E_VENTS', lat: 39.461943, lon: -0.323856 },
+    ],
+  },
+  'zaragoza-bizi': {
+    host: 'zaragoza.publicbikesystem.net',
+    provider: 'Bizi Zaragoza',
+    stations: [
+      { name: '231- Heroínas Sitios: Gómara', lat: 41.627549, lon: -0.962297 },
+      { name: '263- Avda. Real Zaragoza', lat: 41.666994, lon: -0.823078 },
+    ],
+  },
+  'sevilla-sevici': {
+    host: 'api.cyclocity.fr',
+    provider: 'Sevici',
+    stations: [
+      { name: '_ESTADIO OLIMPICO', lat: 37.415898, lon: -6.005849 },
+      { name: '_HOSPITAL VALME', lat: 37.320325, lon: -5.969204 },
+    ],
+    strays: [
+      {
+        station_id: '298',
+        name: '_LAB MADRID',
+        lat: 40.448779,
+        lon: -3.584983,
+      },
+      { station_id: '300', name: '_TALLER SEVILLA', lat: 0, lon: 0 },
+    ],
+  },
+  'valladolid-biki': {
+    host: 'valladolid.publicbikesystem.net',
+    provider: 'BIKI',
+    stations: [
+      { name: '1002 Puente Duero', lat: 41.55413, lon: -4.79122 },
+      { name: '1005 Santovenia Centro Civico', lat: 41.692504, lon: -4.688387 },
+    ],
+  },
+  'a-coruna-bicicoruna': {
+    host: 'acoruna.publicbikesystem.net',
+    provider: 'BiciCoruña',
+    stations: [
+      { name: 'Novo Mesoiro III', lat: 43.323367, lon: -8.443926 },
+      { name: 'Adormideras', lat: 43.3833748, lon: -8.3956482 },
+    ],
+    strays: [
+      { station_id: '24', name: 'Playa de Oza', lat: 0, lon: 0 },
+      { station_id: '37', name: 'Campus Elviña 2', lat: 0, lon: 0 },
+      { station_id: '38', name: 'Campus Zapateira', lat: 0, lon: 0 },
+    ],
+  },
+  'donostia-dbizi': {
+    host: 'sansebastian.publicbikesystem.net',
+    provider: 'Dbizi',
+    stations: [
+      { name: '59 - BUENAVISTA', lat: 43.321211, lon: -1.922239 },
+      { name: '54 - BERIO 42', lat: 43.305158, lon: -2.016997 },
+    ],
+  },
+  'bilbao-bilbaobizi': {
+    host: 'bilbao.publicbikesystem.net',
+    provider: 'Bilbao Bizi',
+    stations: [
+      { name: 'ZORROTZAKO KIROLDEGIA', lat: 43.2778696, lon: -2.9735575 },
+      { name: 'OTXARKOAGA', lat: 43.258515, lon: -2.899282 },
+    ],
+  },
+  'rivas-bicinrivas': {
+    host: 'rivas.publicbikesystem.net',
+    provider: 'BicinRivas',
+    stations: [
+      {
+        name: 'Polideportivo Parque Sureste',
+        lat: 40.3236695,
+        lon: -3.5127191,
+      },
+      { name: 'OCÉANO ÁRTICO', lat: 40.383292, lon: -3.5343627 },
+    ],
+  },
+};
+
+// The production range check, with no viewer or fetches behind it.
+const parts = {
+  model: createModel({ state: {}, services: {}, parts: {}, source: null }),
+};
+const { computeInRangeCities } = createViewport({
+  state: {},
+  services: { render: { governorRequestRender() {} } },
+  parts,
+  source: null,
+});
+
+/** Station information for `id` through the real ingestion path. */
+async function loadThroughIngestion(id, stations) {
+  const city = CITY_BY_ID.get(id);
+  const state = {
+    _stationInfoCache: new Map(),
+    _inFlightInfo: new Map(),
+    _inFlightStatus: new Map(),
+    _loadingOps: 0,
+    _loading: false,
+  };
+  const ingestion = createIngestion({
+    state,
+    services: {},
+    parts,
+    source: {
+      async getStations(url) {
+        assert.equal(url, city.stationInformationUrl);
+        return { data: { stations } };
+      },
+    },
+  });
+  return ingestion.loadCityStationInfo(id, 1);
+}
+
+test('the Spanish city systems are registered and readable through the proxy', () => {
+  for (const [id, expected] of Object.entries(SYSTEMS)) {
+    const system = CITY_BY_ID.get(id);
+    assert.ok(system, `${id} is registered`);
+    assert.equal(system.provider, expected.provider);
+    assert.deepEqual(system.hosts, [expected.host]);
+    for (const feed of [
+      system.stationInformationUrl,
+      system.stationStatusUrl,
+    ]) {
+      const url = new URL(feed);
+      assert.ok(isAllowedGbfsHost(url.hostname), `${id} host ${url.hostname}`);
+      assert.ok(
+        isAllowedGbfsPath(url.pathname, url.hostname),
+        `${id} path ${url.pathname}`,
+      );
+    }
+  }
+});
+
+test('a camera over each outermost station activates its system', () => {
+  for (const [id, expected] of Object.entries(SYSTEMS)) {
+    for (const station of expected.stations) {
+      assert.ok(
+        computeInRangeCities({ lat: station.lat, lon: station.lon }).has(id),
+        `${station.name} activates ${id}`,
+      );
+    }
+  }
+});
+
+test('each load radius reaches its outermost stations', () => {
+  // The range check floors every radius at 100 km, but station information is
+  // trimmed to the radius as registered, so it has to reach every station.
+  for (const [id, expected] of Object.entries(SYSTEMS)) {
+    const system = CITY_BY_ID.get(id);
+    for (const station of expected.stations) {
+      const distance = parts.model.haversineKm(
+        system.centerLat,
+        system.centerLon,
+        station.lat,
+        station.lon,
+      );
+      assert.ok(
+        distance <= system.loadRadiusKm,
+        `${station.name} is ${distance.toFixed(1)} km from the ${id} centre`,
+      );
+    }
+  }
+});
+
+test('a camera over central Madrid activates BiciMAD and BicinRivas', () => {
+  // Puerta del Sol.
+  const active = computeInRangeCities({ lat: 40.4169, lon: -3.7035 });
+  assert.ok(active.has('madrid-bicimad'));
+  assert.ok(active.has('rivas-bicinrivas'));
+});
+
+test('stations a feed lists away from its city are not loaded', async () => {
+  for (const [id, expected] of Object.entries(SYSTEMS)) {
+    if (!expected.strays) continue;
+    const local = expected.stations.map((station, index) => ({
+      station_id: `local-${index}`,
+      ...station,
+    }));
+    const stations = await loadThroughIngestion(id, [
+      ...local,
+      ...expected.strays,
+    ]);
+    assert.deepEqual(
+      [...stations.keys()],
+      local.map((station) => station.station_id),
+      `${id} keeps only its local stations`,
+    );
+  }
+});
+
+test('JCDecaux station names reach the layer without underscores', async () => {
+  for (const id of ['valencia-valenbisi', 'sevilla-sevici']) {
+    const stations = await loadThroughIngestion(
+      id,
+      SYSTEMS[id].stations.map((station, index) => ({
+        station_id: String(index),
+        ...station,
+      })),
+    );
+    for (const station of stations.values())
+      assert.doesNotMatch(station.name, /_/, `${id}: ${station.name}`);
+  }
+  const valenbisi = await loadThroughIngestion('valencia-valenbisi', [
+    { station_id: '81', ...SYSTEMS['valencia-valenbisi'].stations[0] },
+  ]);
+  assert.equal(valenbisi.get('81').name, 'CAMPAMENTO 81');
+});
+
+test('PBSC station capacity reaches the layer as docks, without the geofenced area', async () => {
+  // Bilbao Bizi's ARAGOI and a BiciMAD station as published on 2026-10-17.
+  const [bilbao] = SYSTEMS['bilbao-bilbaobizi'].stations;
+  const bilbaoStations = await loadThroughIngestion('bilbao-bilbaobizi', [
+    { station_id: '1', ...bilbao, capacity: 839, geofenced_capacity: 800 },
+  ]);
+  assert.equal(bilbaoStations.get('1').capacity, 39);
+  const [madrid] = SYSTEMS['madrid-bicimad'].stations;
+  const madridStations = await loadThroughIngestion('madrid-bicimad', [
+    { station_id: '627', ...madrid, capacity: 47, geofenced_capacity: 20 },
+  ]);
+  assert.equal(madridStations.get('627').capacity, 27);
+});

src/layers/bikeshare/state.js

@@ -99,9 +99,17 @@ export function createState({ services }) {
 
   layerState._loadingOps = 0;
 
-  /** Most recent error message string, or null. */
+  /**
+   * @type {Set<string>} City ids whose most recent fetch failed.
+   *
+   * Per city rather than one layer-wide flag: feeds are fetched independently,
+   * so a retired operator must not mark a layer that other cities are still
+   * populating as failed. Entries are dropped when their city leaves range.
+   * The layer reports failure only when these cost it everything it had to
+   * draw, and degraded otherwise — see `getStats()` in controls.js.
+   */
 
-  layerState._error = null;
+  layerState._failedCityIds = new Set();
 
   /** Whether the MAX_TOTAL_POINTS cap warning has already been logged. */
 

src/layers/bikeshare/usPbscCities.test.mjs

@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CITY_BY_ID } from './registry.js';
+import { createModel } from './model.js';
+import { createViewport } from './viewport.js';
+import { isAllowedGbfsHost, isAllowedGbfsPath } from '../../data/gbfsSource.js';
+
+// Each city's PBSC host, and the stations farthest from its registered centre
+// in the live feed (checked 2026-10-13). HIBike's centre sits between its two
+// towns, so it lists the outermost station in each.
+const CITIES = {
+  'detroit-mogo': {
+    host: 'detroit.publicbikesystem.net',
+    provider: 'MoGo',
+    stations: [{ name: 'Robina Ave & W Twelve Mile Rd', lat: 42.50288, lon: -83.18921 }],
+  },
+  'pittsburgh-pogoh': {
+    host: 'pittsburgh.publicbikesystem.net',
+    provider: 'POGOH',
+    stations: [{ name: 'Wilkinsburg Park & Ride', lat: 40.446951, lon: -79.888593 }],
+  },
+  'aspen-we-cycle': {
+    host: 'aspen.publicbikesystem.net',
+    provider: 'WE-cycle',
+    stations: [{ name: 'Cowen Dr | Hwy 133', lat: 39.413115, lon: -107.220634 }],
+  },
+  'hawaii-island-hibike': {
+    host: 'kona.publicbikesystem.net',
+    provider: 'HIBike',
+    stations: [
+      { name: 'Kona Community Center', lat: 19.642932, lon: -156.004962 },
+      { name: 'Kealoha Beach Park, Hilo', lat: 19.733317, lon: -155.029202 },
+    ],
+  },
+};
+
+// The production range check, with no viewer or fetches behind it.
+const parts = { model: createModel({ state: {}, services: {}, parts: {}, source: null }) };
+const { computeInRangeCities } = createViewport({
+  state: {},
+  services: { render: { governorRequestRender() {} } },
+  parts,
+  source: null,
+});
+
+test('the added US PBSC systems are registered and readable through the proxy', () => {
+  for (const [id, expected] of Object.entries(CITIES)) {
+    const city = CITY_BY_ID.get(id);
+    assert.ok(city, `${id} is registered`);
+    assert.equal(city.provider, expected.provider);
+    assert.deepEqual(city.hosts, [expected.host]);
+    for (const feed of [city.stationInformationUrl, city.stationStatusUrl]) {
+      const url = new URL(feed);
+      assert.ok(isAllowedGbfsHost(url.hostname), `${id} host ${url.hostname}`);
+      assert.ok(isAllowedGbfsPath(url.pathname), `${id} path ${url.pathname}`);
+    }
+  }
+});
+
+test('a camera over each outermost station activates its system', () => {
+  for (const [id, expected] of Object.entries(CITIES)) {
+    for (const station of expected.stations) {
+      assert.ok(
+        computeInRangeCities({ lat: station.lat, lon: station.lon }).has(id),
+        `${station.name} activates ${id}`,
+      );
+    }
+  }
+});
+
+test('HIBike stays inactive away from Hawaii Island', () => {
+  // Honolulu is about 270 km from the HIBike centre.
+  assert.equal(
+    computeInRangeCities({ lat: 21.3069, lon: -157.8583 }).has('hawaii-island-hibike'),
+    false,
+  );
+});

src/layers/bikeshare/viewport.js

@@ -122,6 +122,9 @@ export function createViewport({ state: layerState, services, parts, source }) {
     const cityIds = Array.from(layerState._activeCityIds);
     for (const cityId of cityIds) deactivateCity(cityId);
     layerState._activeCityIds.clear();
+    // A failure belongs to a city in range; none are once everything is off.
+    layerState._failedCityIds.clear();
+    layerState._count = 0;
   }
 
   /**
@@ -168,11 +171,19 @@ export function createViewport({ state: layerState, services, parts, source }) {
         return;
       parts.rendering.applyStatusToPoints(cityId, statusMap);
       layerState._lastUpdate = Date.now();
-      layerState._error = null;
+      layerState._failedCityIds.delete(cityId);
     } catch (error) {
       if (error?.name === 'AbortError') return;
+      // A rejection from superseded work must not mark (or tear down) a city
+      // that a newer proximity check or re-enable now owns.
+      if (
+        !layerState._enabled ||
+        !layerState._activeCityIds.has(cityId) ||
+        generation !== layerState._proximityGeneration
+      )
+        return;
       console.warn(`[Data:Bikeshare] ${cityId} activate error:`, error);
-      layerState._error = 'GBFS fetch error';
+      layerState._failedCityIds.add(cityId);
       deactivateCity(cityId);
       layerState._activeCityIds.delete(cityId);
     } finally {
@@ -208,6 +219,10 @@ export function createViewport({ state: layerState, services, parts, source }) {
         deactivateCity(cityId);
       }
     }
+    // A failure never outlives its city's range.
+    for (const cityId of layerState._failedCityIds) {
+      if (!nextActive.has(cityId)) layerState._failedCityIds.delete(cityId);
+    }
 
     layerState._activeCityIds = nextActive;
     if (layerState._activeCityIds.size === 0) {

src/layers/cctv/catalog.js

@@ -1,4 +1,41 @@
-import { CAMERA_SEEDS, SOURCE_ENDPOINT } from './policy.js';
+import { CAMERA_SEEDS } from './policy.js';
+import {
+  lookupModelSpec,
+  horizontalFovRangeDeg,
+  fixedHorizontalFovDeg,
+} from './modelSpecs.js';
+
+/**
+ * Applies datasheet enrichment to a camera in place: when it names a known
+ * hardware `model` (and, when published, a matching `manufacturer`), the spec
+ * record is attached for the HUD and the datasheet's horizontal FOV range
+ * rides along as `specFovMinDeg`/`specFovMaxDeg`. Only fixed-lens hardware
+ * fills the FOV, and only when none was given: an explicit source/seed
+ * `fovDeg` or a curated pose is never overwritten. A PTZ/varifocal range says
+ * what the lens CAN do, not where it is zoomed now.
+ * Unknown models — the common case — change nothing.
+ * @param {Object} camera - Camera being built (mutated).
+ * @param {{model?:string, manufacturer?:string, explicitFov?:boolean}} hardware
+ *   - Hardware model/manufacturer from a source or seed, and whether that
+ *   source or seed stated its own `fovDeg`.
+ * @param {(v:number,min:number,max:number)=>number} clamp - Pose clamp helper.
+ */
+function applyModelEnrichment(camera, hardware, clamp) {
+  const { model, manufacturer, explicitFov } = hardware;
+  const spec = model ? lookupModelSpec(model, manufacturer) : null;
+  if (!spec) return;
+  const range = horizontalFovRangeDeg(spec);
+  if (range) {
+    camera.specFovMinDeg = range.minDeg;
+    camera.specFovMaxDeg = range.maxDeg;
+  }
+  const fixedFov = fixedHorizontalFovDeg(spec);
+  if (fixedFov && !explicitFov && camera.poseSource !== 'curated') {
+    camera.fovDeg = clamp(fixedFov, 20, 125);
+    camera.fovSource = 'datasheet';
+  }
+  camera.spec = spec;
+}
 
 export function createCatalog({ state: layerState, services, parts, source }) {
   const { CITY_POIS } = services.locations;
@@ -45,6 +82,11 @@ export function createCatalog({ state: layerState, services, parts, source }) {
           parts.model.clamp(seed.elevationM ?? 22, 8, 80),
         pitchDeg: parts.model.clamp(seed.pitchDeg ?? -17, -40, -4),
       };
+      applyModelEnrichment(
+        camera,
+        { model: seed.model, explicitFov: seed.fovDeg != null },
+        parts.model.clamp,
+      );
       parts.model.ensureCameraPose(camera);
       catalog.push(camera);
     }
@@ -204,7 +246,22 @@ export function createCatalog({ state: layerState, services, parts, source }) {
             ? source.groundHeights
             : null,
         poseSource,
+        model: String(source.model || ''),
+        manufacturer: String(source.manufacturer || ''),
       };
+      applyModelEnrichment(
+        camera,
+        {
+          model: source.model || seed?.model,
+          manufacturer: source.model ? source.manufacturer : '',
+          explicitFov:
+            (source.fovDeg != null && Number.isFinite(Number(source.fovDeg))) ||
+            CAMERA_SEEDS.some(
+              (entry) => entry.id === id && entry.fovDeg != null,
+            ),
+        },
+        parts.model.clamp,
+      );
       parts.model.ensureCameraPose(camera);
       catalog.push(camera);
     }

src/layers/cctv/frames.js

@@ -3,15 +3,44 @@ import {
   FRAME_SIGNATURE_H,
   PROJECTION_CANVAS_WIDTH,
   PROJECTION_CANVAS_HEIGHT,
+  PROJECTION_MATTE_COLOR,
   PROJECTION_TEXTURE_SWAP_MS,
-  ACTIVE_FRAME_REFRESH_MS,
-  FRAME_ENDPOINT,
-  MEDIA_ENDPOINT,
   PROJECTION_ACTIVE_REFRESH_MS,
   PROJECTION_IDLE_REFRESH_MS,
   PLACEHOLDER_REPAINT_MS,
 } from './policy.js';
 
+/**
+ * Contain-fits a source frame into the projection canvas: scaled to the
+ * largest size that fits, centered, with the margins left for the matte fill.
+ * Falls back to the full canvas when either dimension is missing or zero.
+ *
+ * @param {number} sourceW - Source width in pixels.
+ * @param {number} sourceH - Source height in pixels.
+ * @returns {{x:number,y:number,w:number,h:number}} Draw rectangle in canvas pixels.
+ */
+export function fitToProjection(sourceW, sourceH) {
+  if (!sourceW || !sourceH)
+    return {
+      x: 0,
+      y: 0,
+      w: PROJECTION_CANVAS_WIDTH,
+      h: PROJECTION_CANVAS_HEIGHT,
+    };
+  const scale = Math.min(
+    PROJECTION_CANVAS_WIDTH / sourceW,
+    PROJECTION_CANVAS_HEIGHT / sourceH,
+  );
+  const w = Math.round(sourceW * scale);
+  const h = Math.round(sourceH * scale);
+  return {
+    x: Math.round((PROJECTION_CANVAS_WIDTH - w) / 2),
+    y: Math.round((PROJECTION_CANVAS_HEIGHT - h) / 2),
+    w,
+    h,
+  };
+}
+
 export function createFrames({ state: layerState, services, parts, source }) {
   /**
    * FNV-1a over the RGB channels of a downsampled frame. Pure (takes the raw
@@ -182,7 +211,7 @@ export function createFrames({ state: layerState, services, parts, source }) {
     ctx.clearRect(0, 0, w, h);
     const g = ctx.createLinearGradient(0, 0, w, h);
     g.addColorStop(0, '#05111a');
-    g.addColorStop(1, '#01070c');
+    g.addColorStop(1, PROJECTION_MATTE_COLOR);
     ctx.fillStyle = g;
     ctx.fillRect(0, 0, w, h);
 
@@ -320,7 +349,14 @@ export function createFrames({ state: layerState, services, parts, source }) {
         // base color (planeMaterial color = WHITE, alpha .95) for the frame or
         // two Cesium needs to rebind, which IS the periodic white flash from the
         // owner field tests (2026-07-04 and 2026-07-30).
-        const signature = projectionFrameSignature(runtime);
+        const fit = fitToProjection(
+          runtime.image.naturalWidth,
+          runtime.image.naturalHeight,
+        );
+        // Pixels are hashed at a fixed size, so the fit carries the aspect.
+        const pixels = projectionFrameSignature(runtime);
+        const signature =
+          pixels === null ? null : `${pixels}:${fit.w}x${fit.h}`;
         runtime.drawnImageStamp = runtime.imageStamp;
         if (signature !== null && signature === runtime.lastFrameSignature) {
           // Identical pixels — leave the canvas, and therefore the bound
@@ -328,19 +364,14 @@ export function createFrames({ state: layerState, services, parts, source }) {
           return;
         }
         runtime.lastFrameSignature = signature;
-        runtime.ctx.clearRect(
-          0,
-          0,
-          PROJECTION_CANVAS_WIDTH,
-          PROJECTION_CANVAS_HEIGHT,
-        );
-        runtime.ctx.drawImage(
-          runtime.image,
+        runtime.ctx.fillStyle = PROJECTION_MATTE_COLOR;
+        runtime.ctx.fillRect(
           0,
           0,
           PROJECTION_CANVAS_WIDTH,
           PROJECTION_CANVAS_HEIGHT,
         );
+        runtime.ctx.drawImage(runtime.image, fit.x, fit.y, fit.w, fit.h);
         runtime.canvasStamp = (runtime.canvasStamp || 0) + 1;
         runtime.lastPlaceholderPaintAt = 0;
       }

src/layers/cctv/frames.test.mjs

@@ -0,0 +1,141 @@
+// src/layers/cctv/frames.test.mjs
+// Still-frame fit (#1201): stills draw at their source aspect, centered on the
+// 1920x1080 projection canvas, instead of being stretched to fill it.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createFrames, fitToProjection } from './frames.js';
+import {
+  FRAME_SIGNATURE_W,
+  FRAME_SIGNATURE_H,
+  PROJECTION_CANVAS_WIDTH,
+  PROJECTION_CANVAS_HEIGHT,
+  PROJECTION_MATTE_COLOR,
+} from './policy.js';
+
+// The expected rectangles below are written for a 1920x1080 canvas.
+assert.equal(PROJECTION_CANVAS_WIDTH, 1920);
+assert.equal(PROJECTION_CANVAS_HEIGHT, 1080);
+
+const FULL_CANVAS = {
+  x: 0,
+  y: 0,
+  w: PROJECTION_CANVAS_WIDTH,
+  h: PROJECTION_CANVAS_HEIGHT,
+};
+
+test('a 4:3 still is pillarboxed at full height', () => {
+  assert.deepEqual(fitToProjection(640, 480), {
+    x: 240,
+    y: 0,
+    w: 1440,
+    h: 1080,
+  });
+});
+
+test('a source wider than 16:9 is letterboxed at full width', () => {
+  assert.deepEqual(fitToProjection(3840, 1080), {
+    x: 0,
+    y: 270,
+    w: 1920,
+    h: 540,
+  });
+});
+
+test('a 16:9 still fills the canvas', () => {
+  assert.deepEqual(fitToProjection(1920, 1080), FULL_CANVAS);
+});
+
+test('a missing or zero dimension falls back to the full canvas', () => {
+  assert.deepEqual(fitToProjection(0, 480), FULL_CANVAS);
+  assert.deepEqual(fitToProjection(640, 0), FULL_CANVAS);
+  assert.deepEqual(fitToProjection(640, undefined), FULL_CANVAS);
+  assert.deepEqual(fitToProjection(undefined, undefined), FULL_CANVAS);
+});
+
+// Draw path: the fit reaches drawImage, and the unchanged-frame skip keys on the
+// fitted size as well as the pixels (the 64x36 hash alone drops aspect).
+function stillHarness() {
+  const calls = [];
+  const ctx = {
+    fillStyle: null,
+    fillRect: (...rect) => calls.push(['fillRect', ctx.fillStyle, ...rect]),
+    clearRect: () => {},
+    drawImage: (_image, ...rect) => calls.push(['drawImage', ...rect]),
+  };
+  // Every frame downsamples to the same pixels, so only the size differs.
+  const pixels = new Uint8ClampedArray(
+    FRAME_SIGNATURE_W * FRAME_SIGNATURE_H * 4,
+  ).fill(7);
+  const runtime = {
+    mode: 'image',
+    ctx,
+    image: { naturalWidth: 0, naturalHeight: 0 },
+    imageReady: true,
+    // In flight, so refreshProjectionImage returns before touching image.src.
+    imageLoading: true,
+    imageStamp: 0,
+    drawnImageStamp: -1,
+    lastFrameSignature: null,
+    canvasStamp: 0,
+    signatureCtx: {
+      clearRect: () => {},
+      drawImage: () => {},
+      getImageData: () => ({ data: pixels }),
+    },
+  };
+  const record = { camera: { id: 'still' }, projection: runtime };
+  const { drawProjectionFrame } = createFrames({
+    state: { _healthById: new Map(), _activeCameraId: null },
+    services: {},
+    parts: {},
+    source: {},
+  });
+  const load = (width, height) => {
+    runtime.image = { naturalWidth: width, naturalHeight: height };
+    runtime.imageStamp += 1;
+    calls.length = 0;
+    drawProjectionFrame(record);
+    return calls.slice();
+  };
+  return { runtime, load };
+}
+
+test('a still is drawn into its fitted rectangle over a full matte', () => {
+  const { runtime, load } = stillHarness();
+  assert.deepEqual(load(640, 480), [
+    [
+      'fillRect',
+      PROJECTION_MATTE_COLOR,
+      0,
+      0,
+      PROJECTION_CANVAS_WIDTH,
+      PROJECTION_CANVAS_HEIGHT,
+    ],
+    ['drawImage', 240, 0, 1440, 1080],
+  ]);
+  assert.equal(runtime.canvasStamp, 1);
+});
+
+test('same pixels at the same size skip the redraw', () => {
+  const { runtime, load } = stillHarness();
+  load(640, 480);
+  assert.deepEqual(load(640, 480), []);
+  assert.equal(runtime.canvasStamp, 1);
+});
+
+test('same pixels at a new aspect redraw at the new fit', () => {
+  const { runtime, load } = stillHarness();
+  load(640, 480);
+  assert.deepEqual(load(1920, 1080), [
+    [
+      'fillRect',
+      PROJECTION_MATTE_COLOR,
+      0,
+      0,
+      PROJECTION_CANVAS_WIDTH,
+      PROJECTION_CANVAS_HEIGHT,
+    ],
+    ['drawImage', 0, 0, 1920, 1080],
+  ]);
+  assert.equal(runtime.canvasStamp, 2);
+});

src/layers/cctv/geometry.js

@@ -1,7 +1,6 @@
 import * as Cesium from 'cesium';
 import { createFrustumVolumePrimitive } from '../../data/cctvViewshed.js';
 import {
-  PROJECTION_VERT_ASPECT,
   FRUSTUM_GROUND_CLEARANCE_M,
   PROBE_MIN_RANGE_M,
   PROBE_CLEARANCE_M,

src/layers/cctv/headingConfidence.js

@@ -1,3 +1,5 @@
+import { t } from '../../i18n/index.js';
+
 /**
  * @module headingConfidence
  *
@@ -43,5 +45,7 @@ export function isHeadingEstimated(camera) {
  */
 export function headingHudToken(camera) {
   const hdg = Math.round(Number(camera?.headingDeg) || 0);
-  return `HDG ${hdg}°${isHeadingEstimated(camera) ? ' (ESTIMATED)' : ''}`;
+  return isHeadingEstimated(camera)
+    ? t('HDG {value}° (ESTIMATED)', { value: hdg })
+    : t('HDG {value}°', { value: hdg });
 }

src/layers/cctv/health.js

@@ -1,4 +1,4 @@
-import { HEALTH_SYNC_INTERVAL_MS, HEALTH_ENDPOINT } from './policy.js';
+import { HEALTH_SYNC_INTERVAL_MS } from './policy.js';
 
 export function createHealth({ state: layerState, services, parts, source }) {
   /**

src/layers/cctv/model.js

@@ -1,4 +1,5 @@
 import * as Cesium from 'cesium';
+import { greatCircleKm } from '../../geoDistance.js';
 import { staticFrameRefreshMs } from '../../data/cctvLod.js';
 import { frameFetchDue, cardFetchPolicy } from '../../data/cctvCards.js';
 import { DEFAULT_CAMERA_CALIBRATION } from './policy.js';
@@ -97,12 +98,23 @@ export function createModel({ state: layerState, services, parts, source }) {
 
   /**
    * Coerces a value to a finite number or returns the fallback.
+   *
+   * Absent, blank and boolean values return the fallback as well. The source
+   * list serializes an unknown number (NaN) as JSON null, and `Number(null)`
+   * is 0, so without this an unknown pose field arrived as zero and was
+   * clamped to the field's floor instead of taking its default.
    * @param {*} value
    * @param {number} [fallback=NaN]
    * @returns {number}
    */
 
   function safeNumber(value, fallback = NaN) {
+    if (
+      value == null ||
+      typeof value === 'boolean' ||
+      (typeof value === 'string' && !value.trim())
+    )
+      return fallback;
     const n = Number(value);
     return Number.isFinite(n) ? n : fallback;
   }
@@ -298,12 +310,7 @@ export function createModel({ state: layerState, services, parts, source }) {
    */
 
   function haversineKm(lat1, lon1, lat2, lon2) {
-    const dLat = toRad(lat2 - lat1);
-    const dLon = toRad(lon2 - lon1);
-    const a =
-      Math.sin(dLat / 2) ** 2 +
-      Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
-    return 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return greatCircleKm({ lat: lat1, lon: lon1 }, { lat: lat2, lon: lon2 });
   }
 
   /**

src/layers/cctv/modelSpecs.js

@@ -0,0 +1,550 @@
+/**
+ * @module cctvModelSpecs
+ *
+ * Hardware-model spec enrichment for the CCTV layer.
+ *
+ * When a catalog camera names its hardware model (source packs may set
+ * `model`; hand-authored seeds may too), the model resolves to a datasheet
+ * record and the HUD meta line gains the model's real specs. A fixed-lens
+ * model's horizontal FOV replaces the frustum's estimate; a PTZ/varifocal or
+ * multi-sensor range is carried as capability metadata beside the estimate,
+ * because the lens's current zoom is unknown.
+ * Cameras without an identified model are untouched — unknown never implies
+ * anything.
+ *
+ * Spec records are vendored verbatim from the CCTV Camera Database
+ * (https://github.com/ch-bas/cctv-camera-database, CC0-1.0) — an open dataset
+ * of 28,000+ camera models transcribed from manufacturer datasheets (84% with
+ * FOV, as of v2.26.0). This module vendors the records that the currently integrated public
+ * catalogs publish hardware for — King County WA (Cohu, Bosch AUTODOME, Axis
+ * Q6135-LE), plus the Bosch AUTODOME and Axis PTZ/multisensor models that
+ * appear in Sarasota County FL and Sioux Falls SD open data; packs that
+ * publish other hardware models can grow it, or vendor the full extract.
+ *
+ * Scope guardrail: records describe camera PRODUCTS (optics, resolution,
+ * night vision) — never endpoints, stream paths, or access/config data.
+ */
+
+/** Verbatim records from the dataset's model-enrichment extract (v2.26.0). */
+const RECORDS = [
+  {
+    id: 'axis-q6135-le',
+    brand: 'Axis',
+    model: 'Q6135-LE',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/axis-q6135-le/',
+    aliases: ['01959-004'],
+    fov_deg: '58.3-2.4 horizontal',
+    resolution: { mp: 2, w: 1920, h: 1080, label: '1080p' },
+    ptz: true,
+    autotracking: true,
+    varifocal: true,
+    night_vision: { type: 'ir', range_m: 250 },
+    environment: ['outdoor'],
+    ndaa_compliant: true,
+  },
+  {
+    id: 'hanwha-xnp-6400rw',
+    brand: 'Hanwha',
+    model: 'XNP-6400RW',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/hanwha-xnp-6400rw/',
+    aliases: ['Wisenet PTZ Plus 2MP 40x IR PTZ'],
+    fov_deg: '65.66-1.88 horizontal / 39.4-1.09 vertical',
+    resolution: { mp: 2, w: 1920, h: 1080, label: '1080p' },
+    ptz: true,
+    autotracking: true,
+    varifocal: true,
+    night_vision: { type: 'ir', range_m: 200 },
+    environment: ['outdoor'],
+    ndaa_compliant: true,
+  },
+  {
+    id: 'hikvision-ds-2cd2087g3-li2uy',
+    brand: 'Hikvision',
+    model: 'DS-2CD2087G3-LI2UY',
+    type: 'bullet',
+    url: 'https://www.cctv-database.com/camera/hikvision-ds-2cd2087g3-li2uy/',
+    fov_deg: '108.8 horizontal (2.8mm) / 93.3 horizontal (4mm)',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 8, w: 3840, h: 2160, label: '8MP (4K)' },
+    night_vision: { type: 'color', range_m: 40 },
+    environment: ['outdoor'],
+    ndaa_compliant: false,
+  },
+  {
+    id: 'axis-f4105-lre',
+    brand: 'Axis',
+    model: 'F4105-LRE',
+    type: 'dome',
+    url: 'https://www.cctv-database.com/camera/axis-f4105-lre/',
+    fov_deg: '110 horizontal, 60 vertical',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 2, w: 1920, h: 1080, label: '1080p HD' },
+    night_vision: { type: 'ir', range_m: 10 },
+    environment: ['outdoor'],
+    ndaa_compliant: true,
+  },
+  {
+    id: 'axis-p3707-pe',
+    brand: 'Axis',
+    model: 'P3707-PE',
+    type: 'panoramic',
+    url: 'https://www.cctv-database.com/camera/axis-p3707-pe/',
+    aliases: ['AXIS P3707-PE', 'P3707-PE'],
+    fov_deg: '108-54 horizontal per sensor (4x 1080p)',
+    resolution: {
+      mp: 8,
+      w: 1920,
+      h: 1080,
+      // i18n-ignore: datasheet label
+      label: '4x 2MP (8MP total; 4x 1080p)',
+    },
+    lens_count: 4,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'axis-q6000-e-mk-ii',
+    brand: 'Axis',
+    model: 'Q6000-E Mk II',
+    type: 'panoramic',
+    url: 'https://www.cctv-database.com/camera/axis-q6000-e-mk-ii/',
+    aliases: [
+      'AXIS Q6000-E Mk II',
+      'Q6000-E Mk II 50 Hz',
+      'Q6000-E Mk II 60 Hz',
+    ],
+    fov_deg: 'up to 360 combined; 113-152 horizontal per sensor',
+    resolution: {
+      mp: 8,
+      w: 1920,
+      h: 1080,
+      // i18n-ignore: datasheet label
+      label: '4x 2MP (8MP total; 4x 1080p)',
+    },
+    lens_count: 4,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'axis-q6054-e',
+    brand: 'Axis',
+    model: 'Q6054-E',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/axis-q6054-e/',
+    aliases: ['AXIS Q6054-E', 'Q6054-E 50 Hz', 'Q6054-E 60 Hz'],
+    fov_deg: '62.9-2.2 horizontal',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 1, w: 1280, h: 720, label: '720p HD' },
+    ptz: true,
+    autotracking: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'axis-q6155-e',
+    brand: 'Axis',
+    model: 'Q6155-E',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/axis-q6155-e/',
+    aliases: ['AXIS Q6155-E', 'Q6155-E 50 Hz', 'Q6155-E 60 Hz'],
+    fov_deg: '66.7-2.36 horizontal',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 2, w: 1920, h: 1080, label: '1080p HD' },
+    ptz: true,
+    autotracking: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'bosch-autodome-500i',
+    brand: 'Bosch',
+    model: 'AutoDome 500i Series (VG4)',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/bosch-autodome-500i/',
+    aliases: [
+      'VG4 AUTODOME',
+      'VG4 AUTODOME H.264',
+      'AutoDome 500i',
+      'AutoDome 500i Series',
+      'VG4-500i',
+      'VG4-500',
+    ],
+    fov_deg: '57.8-1.7 horizontal',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 0.4, label: '540 TVL (NTSC/PAL)' },
+    ptz: true,
+    autotracking: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'bosch-autodome-ip-dynamic-7000-hd',
+    brand: 'Bosch',
+    model: 'AUTODOME IP dynamic 7000 HD',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/bosch-autodome-ip-dynamic-7000-hd/',
+    aliases: ['AUTODOME IP dynamic 7000 HD', 'AUTODOME 7000 dynamic HD'],
+    fov_deg: '65-2.3 horizontal',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 2, w: 1920, h: 1080, label: '1080p HD (2MP)' },
+    ptz: true,
+    autotracking: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'bosch-autodome-ip-starlight-7000-hd',
+    brand: 'Bosch',
+    model: 'AUTODOME IP starlight 7000 HD',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/bosch-autodome-ip-starlight-7000-hd/',
+    aliases: [
+      'AUTODOME IP starlight 7000 HD',
+      'Starlight 7000HD',
+      'VG5-7130-CPT4',
+      'VG5-7130',
+    ],
+    fov_deg: '59-2.1 horizontal',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 1, w: 1280, h: 720, label: '720p HD (1.3MP sensor)' },
+    ptz: true,
+    autotracking: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'bosch-ndp-5502-30',
+    brand: 'Bosch',
+    model: 'AUTODOME IP 5000i (NDP-5502-Z30)',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/bosch-ndp-5502-30/',
+    aliases: [
+      'AUTODOME IP 5000i',
+      'NDP-5502-Z30',
+      'NDP-5502-Z30C',
+      'NDP-5502-30',
+    ],
+    fov_deg: '60.9-2.4 horizontal',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 2, w: 1920, h: 1080, label: '1080p HD (2MP)' },
+    ptz: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'bosch-ndp-7512-z30',
+    brand: 'Bosch',
+    model: 'AUTODOME IP starlight 7000i (NDP-7512-Z30)',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/bosch-ndp-7512-z30/',
+    aliases: [
+      'AUTODOME IP starlight 7000i',
+      'NDP-7512-Z30',
+      'NDP-7512-Z30C',
+      'NDP-7512-Z30K',
+    ],
+    fov_deg: '64.7-2.3 horizontal',
+    // i18n-ignore: datasheet label
+    resolution: { mp: 2, w: 1920, h: 1080, label: '1080p HD (2MP)' },
+    ptz: true,
+    autotracking: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'bosch-vg5-836-ecev',
+    brand: 'Bosch',
+    model: 'AUTODOME 800 Series HD PTZ (VG5-836-ECEV)',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/bosch-vg5-836-ecev/',
+    aliases: ['VG5-836-ECEV', 'VG5-836', 'AUTODOME 800 Series'],
+    resolution: { mp: 2, label: '1080p' },
+    ptz: true,
+    autotracking: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'cohu-3920-idome',
+    brand: 'Cohu',
+    model: '3920 iDome',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/cohu-3920-idome/',
+    aliases: [
+      '3920',
+      '3920 Series',
+      '3923',
+      '3925',
+      '3925 Dome',
+      'iDome 3925',
+      'Cohu iDome 3920 Series',
+    ],
+    // i18n-ignore: datasheet label
+    resolution: { mp: 0.4, label: 'NTSC / 470 TVL' },
+    ptz: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'cohu-3950-iview',
+    brand: 'Cohu',
+    model: '3950 iVIEW',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/cohu-3950-iview/',
+    aliases: ['3950', '3950 Series', 'Cohu 3950 Series iVIEW'],
+    // i18n-ignore: datasheet label
+    resolution: { mp: 0.4, label: 'NTSC / 470 TVL' },
+    ptz: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+  {
+    id: 'cohu-3960',
+    brand: 'Cohu',
+    model: '3960',
+    type: 'ptz',
+    url: 'https://www.cctv-database.com/camera/cohu-3960/',
+    aliases: ['3960 Series', '3964', '3965', 'Cohu 3960 iView'],
+    // i18n-ignore: datasheet label
+    resolution: { mp: 0.4, label: 'NTSC/PAL / 470 TVL' },
+    ptz: true,
+    varifocal: true,
+    environment: ['outdoor'],
+  },
+];
+
+/** Lowercase + collapse whitespace, the shared normal form for matching. */
+function normalize(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, ' ');
+}
+
+/**
+ * Whitespace words of a name, lowercased, with surrounding punctuation trimmed
+ * so "(NDP-7512-Z30)" reads as "ndp-7512-z30". Inner hyphens and dots stay:
+ * "f4105-lre-unknown" is one word, never "f4105-lre" plus noise.
+ * @param {string} value
+ * @returns {string[]}
+ */
+function words(value) {
+  return normalize(value)
+    .split(' ')
+    .map((raw) => raw.replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, ''))
+    .filter(Boolean);
+}
+
+/**
+ * Descriptor words that never identify hardware: product-type nouns, codec
+ * and resolution/zoom/frequency tokens ("h.264", "2mp", "40x", "1080p").
+ */
+const GENERIC_WORDS = new Set([
+  'network',
+  'camera',
+  'cam',
+  'ip',
+  'ptz',
+  'dome',
+  'bullet',
+  'box',
+  'hd',
+  'ir',
+  'outdoor',
+  'indoor',
+  'series',
+]);
+
+function isGeneric(word) {
+  return (
+    GENERIC_WORDS.has(word) ||
+    /^h\.?\d+$/.test(word) ||
+    /^\d+(?:\.\d+)?(?:mp|p|k|x|mm|hz|tvl)$/.test(word)
+  );
+}
+
+/** A model code: letters AND digits, and not a generic descriptor. */
+function isModelCode(word) {
+  return /[a-z]/.test(word) && /\d/.test(word) && !isGeneric(word);
+}
+
+/** Hyphenated variant suffixes that do not change the hardware. */
+const VARIANT_SUFFIXES = new Set(['50hz', '60hz', 'ntsc', 'pal']);
+
+/** "q6155-e-60hz" → "q6155-e"; "f4105-lre-unknown" is left as is. */
+function stripVariantSuffix(word) {
+  let out = word;
+  for (;;) {
+    const cut = out.lastIndexOf('-');
+    if (cut <= 0 || !VARIANT_SUFFIXES.has(out.slice(cut + 1))) return out;
+    out = out.slice(0, cut);
+  }
+}
+
+/** Manufacturer names (lowercased words) accepted for each record brand. */
+const BRAND_ALIASES = {
+  Hanwha: ['wisenet', 'samsung'],
+  Hikvision: ['hiwatch'],
+};
+
+function brandWords(record) {
+  return new Set([
+    ...words(record.brand),
+    ...(BRAND_ALIASES[record.brand] || []),
+  ]);
+}
+
+/**
+ * One entry per record name (model + aliases). `required` is every
+ * non-generic word of the name — all must appear in a query, so a generation
+ * or suffix ("Mk II", "7000i" vs "7000") is never dropped. `hasCode` marks
+ * names carrying a letter+digit model code; names without one ("3950",
+ * "01959-004", "AUTODOME 800 Series") match only when the brand does.
+ */
+const NAME_INDEX = RECORDS.flatMap((record) => {
+  const brand = brandWords(record);
+  return [record.model, ...(record.aliases || [])].map((name) => {
+    const nameWords = words(name);
+    return {
+      record,
+      brand,
+      allowed: new Set(nameWords),
+      required: nameWords.filter((word) => !isGeneric(word)),
+      hasCode: nameWords.some(isModelCode),
+    };
+  });
+});
+
+/**
+ * Looks up a spec record for a hardware-model string.
+ *
+ * A record name matches when every non-generic word of that name appears in
+ * the query (case-insensitive, punctuation-trimmed) and every other query word
+ * is generic or the record's brand. That lets a VERBOSE registry string
+ * resolve — "AXIS Q6155-E PTZ Dome Network Camera" finds the Q6155-E — while
+ * an unrelated code ("Q1615"), a generation suffix ("Mk II") or a longer part
+ * number ("F4105-LRE-UNKNOWN") rejects the match. Codec, resolution and
+ * product-type words never identify hardware on their own. A name with no
+ * letter+digit model code ("3950") needs the brand, from `manufacturer` or the
+ * query itself. A `manufacturer` that is not the record's brand always
+ * rejects. Matches on two different records are ambiguous → null (never
+ * guesses).
+ * @param {string} model - Hardware model as named by a source pack or seed.
+ * @param {string} [manufacturer] - The source's manufacturer, when published.
+ * @returns {Object|null} The verbatim spec record, or null when unknown.
+ */
+export function lookupModelSpec(model, manufacturer) {
+  const query = words(model).map(stripVariantSuffix);
+  if (!query.length) return null;
+  const maker = words(manufacturer);
+  const found = new Set();
+  for (const entry of NAME_INDEX) {
+    const makerMatches = maker.some((word) => entry.brand.has(word));
+    if (maker.length && !makerMatches) continue;
+    if (
+      !entry.hasCode &&
+      !makerMatches &&
+      !query.some((word) => entry.brand.has(word))
+    )
+      continue;
+    if (!entry.required.length) continue;
+    if (!entry.required.every((word) => query.includes(word))) continue;
+    if (
+      !query.every(
+        (word) =>
+          entry.allowed.has(word) || entry.brand.has(word) || isGeneric(word),
+      )
+    )
+      continue;
+    found.add(entry.record);
+  }
+  return found.size === 1 ? [...found][0] : null;
+}
+
+/**
+ * Datasheet horizontal FOV as the range the hardware can cover. Only
+ * segments stating a horizontal figure count — vertical and "combined"
+ * panoramic figures never do — and parenthesized lens/sensor notes are
+ * ignored. A zoom ('58.3-2.4 horizontal') and a lens-option list
+ * ('108.8 horizontal (2.8mm) / 93.3 horizontal (4mm)') both yield a range.
+ * @param {Object} spec - A record from this module.
+ * @returns {{minDeg:number, maxDeg:number}|null} Null when unstated.
+ */
+export function horizontalFovRangeDeg(spec) {
+  const values = [];
+  for (const segment of String(spec?.fov_deg || '').split(/[/;,]/)) {
+    if (!/horizontal/i.test(segment)) continue;
+    const figures = segment.replace(/\([^)]*\)/g, '').split(/horizontal/i)[0];
+    for (const match of figures.matchAll(/\d+(?:\.\d+)?/g)) {
+      const value = Number(match[0]);
+      if (Number.isFinite(value) && value > 0) values.push(value);
+    }
+  }
+  if (!values.length) return null;
+  return { minDeg: Math.min(...values), maxDeg: Math.max(...values) };
+}
+
+/**
+ * The datasheet horizontal FOV as the camera's CURRENT optical state, which
+ * holds only for fixed single-lens hardware stating one figure. PTZ,
+ * varifocal and multi-sensor models publish a capability range whose in-use
+ * value is unknown — known hardware capability is not known pose state — so
+ * they return null and keep their estimated FOV.
+ * @param {Object} spec - A record from this module.
+ * @returns {number|null} Fixed horizontal FOV in degrees, or null.
+ */
+export function fixedHorizontalFovDeg(spec) {
+  if (!spec || spec.ptz || spec.varifocal || (spec.lens_count || 1) > 1)
+    return null;
+  const range = horizontalFovRangeDeg(spec);
+  return range && range.minDeg === range.maxDeg ? range.minDeg : null;
+}
+
+/**
+ * True when the camera's CURRENT FOV is the datasheet figure: it was filled
+ * from a fixed-lens datasheet and no manual calibration offset has moved it.
+ * @param {Object} camera - Catalog camera (see applyModelEnrichment).
+ * @returns {boolean}
+ */
+export function isDatasheetFov(camera) {
+  return camera?.fovSource === 'datasheet' && !camera.calibration?.fovDeg;
+}
+
+/**
+ * HUD token for a datasheet FOV that describes capability rather than the
+ * camera's current state, e.g. 'SPEC FOV 2.4–58° (CAPABILITY)'.
+ * @param {Object} camera - Catalog camera (see applyModelEnrichment).
+ * @param {(span: string) => string} [format] Builds the token from the
+ *   degree span; the HUD passes a translated one.
+ * @returns {string|null} Null when the datasheet FOV already IS the camera's
+ *   FOV (fixed lens) or no datasheet range is known.
+ */
+export function specFovCapabilityToken(
+  camera,
+  format = (span) => `SPEC FOV ${span}° (CAPABILITY)`,
+) {
+  if (!camera || camera.fovSource === 'datasheet') return null;
+  const { specFovMinDeg: min, specFovMaxDeg: max } = camera;
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return null;
+  const fmt = (deg) => (deg < 10 ? deg.toFixed(1) : String(Math.round(deg)));
+  const span = min === max ? fmt(max) : `${fmt(min)}–${fmt(max)}`;
+  return format(span);
+}
+
+/**
+ * One-line spec summary for HUD meta text.
+ * @param {Object} spec - A record from this module.
+ * @returns {string} e.g. 'Axis Q6135-LE · 1080p · IR 250m · PTZ' ('' for null).
+ */
+export function specSummary(spec) {
+  if (!spec) return '';
+  const parts = [`${spec.brand} ${spec.model}`];
+  if (spec.resolution?.label) parts.push(spec.resolution.label);
+  if (spec.night_vision) {
+    parts.push(
+      `${spec.night_vision.type.toUpperCase()}${spec.night_vision.range_m ? ` ${spec.night_vision.range_m}m` : ''}`,
+    );
+  }
+  if (spec.ptz) parts.push('PTZ');
+  return parts.join(' · ');
+}

src/layers/cctv/modelSpecs.test.mjs

@@ -0,0 +1,301 @@
+// src/layers/cctv/modelSpecs.test.mjs
+// Hardware-model spec enrichment: lookup semantics (case-insensitive, alias
+// matching, unknown → null — never a guess), datasheet-FOV parsing across the
+// real fov_deg string shapes, and the HUD spec-summary line.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  lookupModelSpec,
+  horizontalFovRangeDeg,
+  fixedHorizontalFovDeg,
+  specFovCapabilityToken,
+  isDatasheetFov,
+  specSummary,
+} from './modelSpecs.js';
+import { createCatalog } from './catalog.js';
+
+test('lookupModelSpec matches case-insensitively and trims', () => {
+  const spec = lookupModelSpec('  q6135-le ');
+  assert.ok(spec);
+  assert.equal(spec.brand, 'Axis');
+  assert.equal(lookupModelSpec('Q6135-LE'), spec);
+});
+
+test('lookupModelSpec matches aliases', () => {
+  // A part number without letters needs the brand.
+  const byAlias = lookupModelSpec('01959-004', 'Axis');
+  assert.ok(byAlias);
+  assert.equal(byAlias.model, 'Q6135-LE');
+});
+
+test('vendored table covers the integrated catalogs published hardware', () => {
+  // Models the live packs publish: King County (Cohu, AUTODOME IP 5000i),
+  // Sarasota (Bosch AUTODOME 7000/VG4), Sioux Falls (Axis).
+  // King County publishes "3950" with Manufacturer "Cohu".
+  const cohu = lookupModelSpec('3950', 'Cohu');
+  assert.equal(cohu?.brand, 'Cohu');
+  const autodome = lookupModelSpec('AUTODOME IP 5000i');
+  assert.ok(autodome && horizontalFovRangeDeg(autodome).maxDeg > 0);
+  const vg4 = lookupModelSpec('VG4 AUTODOME H.264'); // Sarasota's string
+  assert.ok(vg4);
+  const axis = lookupModelSpec('Q6155-E'); // Sioux Falls
+  assert.deepEqual(horizontalFovRangeDeg(axis), { minDeg: 2.36, maxDeg: 66.7 });
+});
+
+test('verbose registry strings resolve via distinctive-token fallback', () => {
+  // Sioux Falls publishes the full product title, not the bare model.
+  assert.equal(
+    lookupModelSpec('AXIS Q6155-E PTZ Dome Network Camera')?.model,
+    'Q6155-E',
+  );
+  assert.equal(lookupModelSpec('AXIS Q6000-E Mk II')?.model, 'Q6000-E Mk II');
+  assert.equal(
+    lookupModelSpec('AUTODOME IP starlight 7000i camera')?.id,
+    'bosch-ndp-7512-z30',
+  );
+  // Punctuation around the model token doesn't defeat the match.
+  assert.equal(
+    lookupModelSpec('camera (P3707-PE), outdoor')?.model,
+    'P3707-PE',
+  );
+});
+
+test('token fallback never matches on generic words or wrong models', () => {
+  // Only generic descriptors — no distinctive hardware token — stays null.
+  assert.equal(lookupModelSpec('PTZ Dome Camera'), null);
+  assert.equal(lookupModelSpec('HD Network Camera'), null);
+  assert.equal(lookupModelSpec('Outdoor Dome Camera'), null);
+  // A real-looking but unknown model resolves to nothing, not a near neighbour.
+  assert.equal(lookupModelSpec('AXIS FooBar-9 Network Camera'), null);
+  // A generation token alone must not collide with a similar one: "7000"
+  // belongs to two records (dynamic / starlight 7000 HD), so a bare
+  // "AUTODOME 7000" is ambiguous → null rather than an arbitrary pick.
+  assert.equal(lookupModelSpec('AUTODOME 7000'), null);
+});
+
+test('exact match still wins over the token fallback', () => {
+  // "3965" is an alias of the 3960, not the 3950.
+  assert.equal(lookupModelSpec('3965', 'Cohu')?.id, 'cohu-3960');
+  assert.equal(lookupModelSpec('AUTODOME IP 5000i')?.id, 'bosch-ndp-5502-30');
+});
+
+test('lookupModelSpec returns null for unknown or empty input — never guesses', () => {
+  assert.equal(lookupModelSpec('NOT-A-REAL-MODEL'), null);
+  assert.equal(lookupModelSpec(''), null);
+  assert.equal(lookupModelSpec(null), null);
+  assert.equal(lookupModelSpec(undefined), null);
+});
+
+test('horizontalFovRangeDeg reads the full range across real fov_deg shapes', () => {
+  const range = (model) => horizontalFovRangeDeg(lookupModelSpec(model));
+  // PTZ zoom: both ends, not just the wide one.
+  assert.deepEqual(range('Q6135-LE'), { minDeg: 2.4, maxDeg: 58.3 });
+  // Vertical figures never count.
+  assert.deepEqual(range('XNP-6400RW'), { minDeg: 1.88, maxDeg: 65.66 });
+  // Lens options: parenthesized focal lengths are not FOV figures.
+  assert.deepEqual(range('DS-2CD2087G3-LI2UY'), {
+    minDeg: 93.3,
+    maxDeg: 108.8,
+  });
+  assert.deepEqual(range('F4105-LRE'), { minDeg: 110, maxDeg: 110 });
+  // The "360 combined" panoramic figure is not a horizontal lens FOV.
+  assert.deepEqual(range('Q6000-E Mk II'), { minDeg: 113, maxDeg: 152 });
+  assert.deepEqual(range('P3707-PE'), { minDeg: 54, maxDeg: 108 });
+});
+
+test('horizontalFovRangeDeg returns null when no numeric FOV is stated', () => {
+  assert.equal(horizontalFovRangeDeg({ fov_deg: '' }), null);
+  assert.equal(horizontalFovRangeDeg({ fov_deg: 'wide dynamic range' }), null);
+  assert.equal(horizontalFovRangeDeg({ fov_deg: '60 vertical' }), null);
+  assert.equal(horizontalFovRangeDeg({}), null);
+  assert.equal(horizontalFovRangeDeg(null), null);
+});
+
+test('fixedHorizontalFovDeg is the current FOV only for fixed single-lens hardware', () => {
+  // Fixed dome, one horizontal figure: the datasheet IS the optical state.
+  assert.equal(fixedHorizontalFovDeg(lookupModelSpec('F4105-LRE')), 110);
+  // Known hardware capability != known pose state: PTZ, multi-sensor, and a
+  // model sold in several lens options all stay estimated.
+  for (const model of [
+    'Q6135-LE',
+    'XNP-6400RW',
+    'AUTODOME IP 5000i',
+    'P3707-PE',
+    'Q6000-E Mk II',
+    'DS-2CD2087G3-LI2UY',
+  ]) {
+    assert.equal(fixedHorizontalFovDeg(lookupModelSpec(model)), null, model);
+  }
+  assert.equal(fixedHorizontalFovDeg(null), null);
+});
+
+test('specFovCapabilityToken labels a datasheet range as capability, never as current FOV', () => {
+  assert.equal(
+    specFovCapabilityToken({ specFovMinDeg: 2.4, specFovMaxDeg: 58.3 }),
+    'SPEC FOV 2.4–58° (CAPABILITY)',
+  );
+  assert.equal(
+    specFovCapabilityToken({ specFovMinDeg: 113, specFovMaxDeg: 113 }),
+    'SPEC FOV 113° (CAPABILITY)',
+  );
+  // Already the camera's FOV (fixed lens) or nothing known: no token.
+  assert.equal(
+    specFovCapabilityToken({
+      fovSource: 'datasheet',
+      specFovMinDeg: 110,
+      specFovMaxDeg: 110,
+    }),
+    null,
+  );
+  assert.equal(specFovCapabilityToken({}), null);
+  assert.equal(specFovCapabilityToken(null), null);
+});
+
+/** Browser catalog with the pose math stubbed: only enrichment is under test. */
+function browserCatalog() {
+  const model = {
+    safeNumber: (value, fallback = NaN) =>
+      Number.isFinite(Number(value)) ? Number(value) : fallback,
+    normalizeHeading: (deg) => ((deg % 360) + 360) % 360,
+    clamp: (value, lo, hi) => Math.min(hi, Math.max(lo, value)),
+    headingFromId: () => 0,
+    normalizeFeedType: (type) => type,
+    ensureCameraPose: () => {},
+  };
+  return createCatalog({
+    state: {},
+    services: { locations: { CITY_POIS: {} } },
+    parts: { model },
+    source: {},
+  });
+}
+
+test('catalog keeps the estimated FOV for PTZ hardware and fills only fixed-lens datasheets', () => {
+  const [ptz, fixed, unknown] = browserCatalog().buildCatalogFromSources([
+    { id: 'ptz', lat: 47.7, lon: -122, fovDeg: 44, model: 'Q6135-LE' },
+    { id: 'fixed', lat: 47.7, lon: -122, model: 'F4105-LRE' },
+    { id: 'unknown', lat: 47.7, lon: -122, fovDeg: 44, model: 'NOPE-1' },
+  ]);
+
+  // PTZ: the frustum keeps its estimate; the datasheet range is metadata.
+  assert.equal(ptz.fovDeg, 44);
+  assert.equal(ptz.fovSource, undefined);
+  assert.equal(ptz.specFovMinDeg, 2.4);
+  assert.equal(ptz.specFovMaxDeg, 58.3);
+  assert.equal(ptz.spec.model, 'Q6135-LE');
+
+  // Fixed lens: the datasheet figure is the optical state.
+  assert.equal(fixed.fovDeg, 110);
+  assert.equal(fixed.fovSource, 'datasheet');
+
+  // Unknown hardware changes nothing.
+  assert.equal(unknown.fovDeg, 44);
+  assert.equal(unknown.spec, undefined);
+  assert.equal(unknown.specFovMaxDeg, undefined);
+});
+
+test('codec, format and product words never identify hardware', () => {
+  // "h.264" is in the VG4 AUTODOME alias; it is a codec, not a model code.
+  assert.equal(lookupModelSpec('Axis Q1615 H.264 Network Camera'), null);
+  assert.equal(lookupModelSpec('H.264 Network Camera'), null);
+  assert.equal(lookupModelSpec('H.265 IP Camera'), null);
+});
+
+test('generation and suffix distinctions are preserved', () => {
+  // A Mk II is not the vendored (Mk I) Q6135-LE.
+  assert.equal(lookupModelSpec('AXIS Q6135-LE Mk II'), null);
+  // A longer part number is a different product...
+  assert.equal(lookupModelSpec('F4105-LRE-UNKNOWN'), null);
+  // ...unless the rest is a mains-frequency variant suffix.
+  assert.equal(lookupModelSpec('Q6155-E-60Hz')?.id, 'axis-q6155-e');
+});
+
+test('manufacturer must agree with the record brand', () => {
+  // Purely numeric models need a brand match.
+  assert.equal(lookupModelSpec('3950'), null);
+  assert.equal(lookupModelSpec('Pelco 3950'), null);
+  assert.equal(lookupModelSpec('3950', 'Pelco'), null);
+  // A model code under the wrong manufacturer is not that record either.
+  assert.equal(lookupModelSpec('Q6135-LE', 'Hikvision'), null);
+  // Case-insensitive, with company suffixes and aliases.
+  assert.equal(lookupModelSpec('3950', 'COHU')?.id, 'cohu-3950-iview');
+  assert.equal(
+    lookupModelSpec('Q6135-LE', 'Axis Communications AB')?.id,
+    'axis-q6135-le',
+  );
+  assert.equal(
+    lookupModelSpec('XNP-6400RW', 'Hanwha Vision')?.id,
+    'hanwha-xnp-6400rw',
+  );
+  assert.equal(
+    lookupModelSpec('XNP-6400RW', 'Wisenet')?.id,
+    'hanwha-xnp-6400rw',
+  );
+});
+
+test('King County snapshot model strings still resolve', () => {
+  // Model/Manufacturer pairs as published in the King County feed.
+  assert.equal(lookupModelSpec('3950', 'Cohu')?.id, 'cohu-3950-iview');
+  assert.equal(lookupModelSpec('3965', 'Cohu')?.id, 'cohu-3960');
+  assert.equal(lookupModelSpec('3925 Dome', 'Cohu')?.id, 'cohu-3920-idome');
+  assert.equal(lookupModelSpec('Q6135-LE', 'Axis')?.id, 'axis-q6135-le');
+  assert.equal(
+    lookupModelSpec('AUTODOME IP 5000i', 'BOSCH')?.id,
+    'bosch-ndp-5502-30',
+  );
+});
+
+test('catalog never overwrites an explicit FOV or a curated pose', () => {
+  const [explicit, curated, cohu, pelco] =
+    browserCatalog().buildCatalogFromSources([
+      { id: 'explicit', lat: 47.7, lon: -122, fovDeg: 44, model: 'F4105-LRE' },
+      {
+        id: 'curated',
+        lat: 47.7,
+        lon: -122,
+        model: 'F4105-LRE',
+        poseSource: 'curated',
+      },
+      { id: 'cohu', lat: 47.7, lon: -122, model: '3950', manufacturer: 'Cohu' },
+      {
+        id: 'pelco',
+        lat: 47.7,
+        lon: -122,
+        model: '3950',
+        manufacturer: 'Pelco',
+      },
+    ]);
+  assert.equal(explicit.fovDeg, 44);
+  assert.equal(explicit.fovSource, undefined);
+  assert.equal(explicit.spec.model, 'F4105-LRE');
+  assert.equal(curated.fovDeg, 74);
+  assert.equal(curated.fovSource, undefined);
+  // The source's manufacturer reaches the lookup.
+  assert.equal(cohu.spec?.id, 'cohu-3950-iview');
+  assert.equal(pelco.spec, undefined);
+});
+
+test('the DATASHEET label drops once calibration moves the FOV', () => {
+  const camera = { fovSource: 'datasheet', fovDeg: 110 };
+  assert.equal(isDatasheetFov(camera), true);
+  assert.equal(isDatasheetFov({ ...camera, calibration: { fovDeg: 0 } }), true);
+  assert.equal(
+    isDatasheetFov({ ...camera, calibration: { fovDeg: 6 } }),
+    false,
+  );
+  assert.equal(isDatasheetFov({ fovDeg: 74 }), false);
+  assert.equal(isDatasheetFov(null), false);
+});
+
+test('specSummary renders the HUD line and degrades by omission', () => {
+  assert.equal(
+    specSummary(lookupModelSpec('Q6135-LE')),
+    'Axis Q6135-LE · 1080p · IR 250m · PTZ',
+  );
+  // No night vision / no PTZ → those segments are simply absent.
+  assert.equal(
+    specSummary({ brand: 'Axis', model: 'X', resolution: { label: '4K' } }),
+    'Axis X · 4K',
+  );
+  assert.equal(specSummary(null), '');
+});

src/layers/cctv/policy.js

@@ -1,10 +1,4 @@
-export {
-  FRAME_ENDPOINT,
-  SOURCE_ENDPOINT,
-  HEALTH_ENDPOINT,
-  MEDIA_ENDPOINT,
-  ACTIVE_FRAME_REFRESH_MS,
-} from './sourcePolicy.js';
+export { ACTIVE_FRAME_REFRESH_MS } from './sourcePolicy.js';
 import * as Cesium from 'cesium';
 import { CCTV_CARD_FETCH_BURST_SPACING_MS } from '../../data/cctvCards.js';
 import { CCTV_AMBIENT_CARD_MAX } from '../../data/cctvLod.js';
@@ -35,6 +29,9 @@ export const PROJECTION_CANVAS_WIDTH = 1920;
 
 export const PROJECTION_CANVAS_HEIGHT = 1080;
 
+/** Matte behind fitted stills; the placeholder gradient's dark end. */
+export const PROJECTION_MATTE_COLOR = '#01070c';
+
 // Downsample grid for the unchanged-frame signature (drawProjectionFrame).
 // 64x36 keeps the 16:9 aspect and reads ~9 KB per check versus the 8.3 MB a
 // full-resolution compare would touch.
@@ -87,9 +84,6 @@ export const CCTV_CALIBRATION_STORAGE_KEY_V2 =
 
 export const PROJECTION_TEXTURE_SWAP_MS = 1000;
 
-export const PROJECTION_VERT_ASPECT =
-  PROJECTION_CANVAS_WIDTH / PROJECTION_CANVAS_HEIGHT;
-
 // V2 frustum geometry (design §2a/§6): the far-cap center + corners never sink
 // below groundAlt + this clearance, so a fabricated pitch (-24°) cannot bury
 // the monitor plane in the 3D tiles. Exported for the unit suite.
@@ -179,7 +173,7 @@ export const CAMERA_SEEDS = [
     id: 'nyc-midtown-w',
     cityId: 'nyc',
     poiIndex: 1,
-    label: 'Midtown West @ 34th',
+    label: 'Midtown West @ 34th', // i18n-ignore: camera name
     offsetNorthM: 120,
     offsetEastM: -70,
     headingDeg: 206,
@@ -191,7 +185,7 @@ export const CAMERA_SEEDS = [
     id: 'nyc-wtc-n',
     cityId: 'nyc',
     poiIndex: 2,
-    label: 'WTC North Plaza',
+    label: 'WTC North Plaza', // i18n-ignore: camera name
     offsetNorthM: 95,
     offsetEastM: 34,
     headingDeg: 164,
@@ -203,7 +197,7 @@ export const CAMERA_SEEDS = [
     id: 'nyc-times-square-ne',
     cityId: 'nyc',
     poiIndex: 1,
-    label: 'Times Sq Northeast',
+    label: 'Times Sq Northeast', // i18n-ignore: camera name
     offsetNorthM: 230,
     offsetEastM: 120,
     headingDeg: 218,
@@ -216,7 +210,7 @@ export const CAMERA_SEEDS = [
     id: 'sf-market-5th',
     cityId: 'sf',
     poiIndex: 2,
-    label: 'Market & 5th',
+    label: 'Market & 5th', // i18n-ignore: camera name
     offsetNorthM: -160,
     offsetEastM: 80,
     headingDeg: 320,
@@ -228,7 +222,7 @@ export const CAMERA_SEEDS = [
     id: 'sf-financial-district',
     cityId: 'sf',
     poiIndex: 1,
-    label: 'SF Financial Core',
+    label: 'SF Financial Core', // i18n-ignore: camera name
     offsetNorthM: 110,
     offsetEastM: 52,
     headingDeg: 205,
@@ -241,7 +235,7 @@ export const CAMERA_SEEDS = [
     id: 'tokyo-shibuya-scramble',
     cityId: 'tokyo',
     poiIndex: 4,
-    label: 'Shibuya Crossing',
+    label: 'Shibuya Crossing', // i18n-ignore: camera name
     offsetNorthM: 180,
     offsetEastM: 46,
     headingDeg: 18,
@@ -253,7 +247,7 @@ export const CAMERA_SEEDS = [
     id: 'tokyo-ginza-core',
     cityId: 'tokyo',
     poiIndex: 0,
-    label: 'Ginza Core',
+    label: 'Ginza Core', // i18n-ignore: camera name
     offsetNorthM: -180,
     offsetEastM: 150,
     headingDeg: 245,
@@ -265,7 +259,7 @@ export const CAMERA_SEEDS = [
     id: 'tokyo-asakusa-n',
     cityId: 'tokyo',
     poiIndex: 3,
-    label: 'Asakusa North Gate',
+    label: 'Asakusa North Gate', // i18n-ignore: camera name
     offsetNorthM: 110,
     offsetEastM: -65,
     headingDeg: 192,
@@ -278,7 +272,7 @@ export const CAMERA_SEEDS = [
     id: 'london-city-a1',
     cityId: 'london',
     poiIndex: 4,
-    label: 'City Cluster A1',
+    label: 'City Cluster A1', // i18n-ignore: camera name
     offsetNorthM: 80,
     offsetEastM: 65,
     headingDeg: 220,
@@ -290,7 +284,7 @@ export const CAMERA_SEEDS = [
     id: 'london-soho-core',
     cityId: 'london',
     poiIndex: 2,
-    label: 'Soho Core',
+    label: 'Soho Core', // i18n-ignore: camera name
     offsetNorthM: 210,
     offsetEastM: 120,
     headingDeg: 206,
@@ -303,7 +297,7 @@ export const CAMERA_SEEDS = [
     id: 'paris-rivoli',
     cityId: 'paris',
     poiIndex: 4,
-    label: 'Rue de Rivoli',
+    label: 'Rue de Rivoli', // i18n-ignore: camera name
     offsetNorthM: 55,
     offsetEastM: 85,
     headingDeg: 248,
@@ -315,7 +309,7 @@ export const CAMERA_SEEDS = [
     id: 'paris-champs-n',
     cityId: 'paris',
     poiIndex: 1,
-    label: 'Champs-Élysées North',
+    label: 'Champs-Élysées North', // i18n-ignore: camera name
     offsetNorthM: 130,
     offsetEastM: -38,
     headingDeg: 175,
@@ -328,7 +322,7 @@ export const CAMERA_SEEDS = [
     id: 'dc-mall-center',
     cityId: 'dc',
     poiIndex: 1,
-    label: 'National Mall Center',
+    label: 'National Mall Center', // i18n-ignore: camera name
     offsetNorthM: 120,
     offsetEastM: 20,
     headingDeg: 258,
@@ -340,7 +334,7 @@ export const CAMERA_SEEDS = [
     id: 'dc-pentagon-s',
     cityId: 'dc',
     poiIndex: 3,
-    label: 'Pentagon South',
+    label: 'Pentagon South', // i18n-ignore: camera name
     offsetNorthM: -100,
     offsetEastM: 92,
     headingDeg: 14,
@@ -353,7 +347,7 @@ export const CAMERA_SEEDS = [
     id: 'dubai-difc-loop',
     cityId: 'dubai',
     poiIndex: 4,
-    label: 'DIFC Loop',
+    label: 'DIFC Loop', // i18n-ignore: camera name
     offsetNorthM: 92,
     offsetEastM: -45,
     headingDeg: 196,
@@ -365,7 +359,7 @@ export const CAMERA_SEEDS = [
     id: 'dubai-downtown-east',
     cityId: 'dubai',
     poiIndex: 0,
-    label: 'Downtown East',
+    label: 'Downtown East', // i18n-ignore: camera name
     offsetNorthM: -130,
     offsetEastM: 190,
     headingDeg: 322,
@@ -378,7 +372,7 @@ export const CAMERA_SEEDS = [
     id: 'austin-congress-s',
     cityId: 'austin',
     poiIndex: 0,
-    label: 'Congress Southbound',
+    label: 'Congress Southbound', // i18n-ignore: camera name
     offsetNorthM: -165,
     offsetEastM: 40,
     headingDeg: 12,
@@ -390,7 +384,7 @@ export const CAMERA_SEEDS = [
     id: 'austin-downtown-west',
     cityId: 'austin',
     poiIndex: 1,
-    label: 'Downtown West',
+    label: 'Downtown West', // i18n-ignore: camera name
     offsetNorthM: -120,
     offsetEastM: -160,
     headingDeg: 120,
@@ -410,6 +404,9 @@ export const IDLE_CAMERA_COLOR =
 export const ACTIVE_CAMERA_COLOR =
   Cesium.Color.fromCssColorString('#ffd97a').withAlpha(0.95);
 
+export const LIVE_CAMERA_COLOR =
+  Cesium.Color.fromCssColorString('#b48cff').withAlpha(0.88);
+
 export const IDLE_COVERAGE_COLOR =
   Cesium.Color.fromCssColorString('#2fe0ff').withAlpha(0.24);
 

src/layers/cctv/presentation.js

@@ -1,6 +1,12 @@
 import { CCTV_AMBIENT_CARD_MAX } from '../../data/cctvLod.js';
+import { t } from '../../i18n/index.js';
 import { ACTIVE_FRAME_REFRESH_MS, IDLE_FRAME_REFRESH_MS } from './policy.js';
 import { headingHudToken, isHeadingEstimated } from './headingConfidence.js';
+import {
+  specSummary,
+  specFovCapabilityToken,
+  isDatasheetFov,
+} from './modelSpecs.js';
 
 export function createPresentation({
   state: layerState,
@@ -19,8 +25,13 @@ export function createPresentation({
     const active = parts.selection.getActiveRecord();
     if (!active) {
       return layerState._records.length
-        ? `${layerState._records.length} CAMERAS STANDING BY · NO CAMERA SELECTED · CLICK A CAMERA TO ACTIVATE`
-        : 'No cameras available in catalog.';
+        ? t(
+            '{count} CAMERAS STANDING BY · NO CAMERA SELECTED · CLICK A CAMERA TO ACTIVATE',
+            {
+              count: layerState._records.length,
+            },
+          )
+        : t('No cameras available in catalog.');
     }
 
     const area = parts.model.sectorAreaKm2(
@@ -34,21 +45,50 @@ export function createPresentation({
     const calBadge = parts.calibration.deriveCalBadge(active.camera);
 
     return [
-      `${active.camera.city.toUpperCase()} CCTV`,
+      t('{city} CCTV', {
+        city: active.camera.city.toUpperCase(),
+      }),
       `${active.camera.name.toUpperCase()}`,
       // A synthetic bearing (headingConfidence 'low', no human calibration)
       // is tagged so a hashed guess never reads as a surveyed facing (#639).
       headingHudToken(active.camera),
-      `FOV ${Math.round(active.camera.fovDeg)}°`,
-      `COVERAGE ${area.toFixed(2)}km²`,
-      overlapCount > 0 ? `OVERLAP ${overlapCount} cams` : 'ISOLATED VIEW',
-      `PROJ ${layerState._showProjection ? 'MONITOR' : 'OFF'}`,
-      layerState._coverageMode === 'viewshed' ? 'VIEWSHED' : null,
-      `CAL ${calBadge.replace('-', ' ').toUpperCase()}`,
+      // Identified hardware labels its FOV as datasheet-sourced (catalog.js)
+      // only while no manual calibration offset has moved it.
+      isDatasheetFov(active.camera)
+        ? t('FOV {value}° (DATASHEET)', {
+            value: Math.round(active.camera.fovDeg),
+          })
+        : t('FOV {value}°', {
+            value: Math.round(active.camera.fovDeg),
+          }),
+      // A PTZ/varifocal datasheet range is what the lens can do, not its
+      // current zoom, so it is shown beside the estimate, never as it.
+      specFovCapabilityToken(active.camera, (span) =>
+        t('SPEC FOV {span}° (CAPABILITY)', { span }),
+      ),
+      t('COVERAGE {value}km²', { value: area.toFixed(2) }),
+      overlapCount > 0
+        ? t('OVERLAP {count} cams', { count: overlapCount })
+        : t('ISOLATED VIEW'),
+      layerState._showProjection ? t('PROJ MONITOR') : t('PROJ OFF'),
+      layerState._coverageMode === 'viewshed' ? t('VIEWSHED') : null,
+      t('CAL {value}', {
+        value: calBadge.replace('-', ' ').toUpperCase(),
+      }),
       health?.sourceKind
-        ? `SRC ${String(health.sourceKind).toUpperCase()}`
-        : `SRC ${String(active.camera.feedType || 'image').toUpperCase()}`,
-      `${viewBand.toUpperCase()} CONTEXT`,
+        ? t('SRC {value}', {
+            value: String(health.sourceKind).toUpperCase(),
+          })
+        : t('SRC {value}', {
+            value: String(active.camera.feedType || 'image').toUpperCase(),
+          }),
+      t('{value} CONTEXT', { value: viewBand.toUpperCase() }),
+      // Identified hardware: append the model's datasheet specs + attribution.
+      active.camera.spec
+        ? t('{spec} · SPECS: CCTV-DATABASE.COM', {
+            spec: specSummary(active.camera.spec).toUpperCase(),
+          })
+        : null,
     ]
       .filter(Boolean)
       .join(' · ');
@@ -86,6 +126,15 @@ export function createPresentation({
       headingEstimated: isHeadingEstimated(camera),
       pitchDeg: camera.pitchDeg,
       fovDeg: camera.fovDeg,
+      // Identified-hardware enrichment passthrough (catalog.js / modelSpecs.js).
+      fovSource: isDatasheetFov(camera)
+        ? 'datasheet'
+        : camera.fovSource === 'datasheet'
+          ? 'calibrated'
+          : camera.fovSource || 'estimated',
+      specFovMinDeg: camera.specFovMinDeg ?? null,
+      specFovMaxDeg: camera.specFovMaxDeg ?? null,
+      spec: camera.spec || null,
       rangeM: camera.rangeM,
       elevationM: camera.absoluteHeightM,
       mountHeightM: camera.mountHeightM,

src/layers/cctv/rendering.js

@@ -4,6 +4,7 @@ import { isHeadingEstimated } from './headingConfidence.js';
 import {
   ACTIVE_CAMERA_COLOR,
   IDLE_CAMERA_COLOR,
+  LIVE_CAMERA_COLOR,
   ACTIVE_COVERAGE_CENTER,
   IDLE_COVERAGE_CENTER_MUTED,
   ACTIVE_COVERAGE_CENTER_DEPTHFAIL,
@@ -18,6 +19,15 @@ export function createRendering({
   parts,
   source,
 }) {
+  /** Icon color: active wins, then live-capable video feeds, then idle stills. */
+  function cameraColorFor(record) {
+    if (record.camera.id === layerState._activeCameraId)
+      return ACTIVE_CAMERA_COLOR;
+    if (parts.model.isVideoFeedType(record.camera.feedType))
+      return LIVE_CAMERA_COLOR;
+    return IDLE_CAMERA_COLOR;
+  }
+
   const {
     focusNowMs,
     getFocusTarget,
@@ -58,10 +68,7 @@ export function createRendering({
         ),
       cameraDistanceFor: (position) =>
         Cesium.Cartesian3.distance(camera.positionWC, position),
-      baseColorFor: (record) =>
-        record.camera.id === layerState._activeCameraId
-          ? ACTIVE_CAMERA_COLOR
-          : IDLE_CAMERA_COLOR,
+      baseColorFor: cameraColorFor,
     });
     layerState._activeFocusStyleCount = result.activeCount;
   }
@@ -208,9 +215,7 @@ export function createRendering({
     for (const record of layerState._records) {
       const isActive = record.camera.id === activeId;
       if (record.billboard) {
-        record.billboard.color = isActive
-          ? ACTIVE_CAMERA_COLOR
-          : IDLE_CAMERA_COLOR;
+        record.billboard.color = cameraColorFor(record);
         record.billboard.scale = isActive ? 1.25 : 1.0;
         // disableDepthTestDistance stays POSITIVE_INFINITY for every billboard
         // (set at creation) — see the field-test far-zoom submerge fix there.

src/layers/cctv/rendering.test.mjs

@@ -0,0 +1,73 @@
+// src/layers/cctv/rendering.test.mjs
+// Icon colors under focus de-emphasis (#1200): the focus pass fades each icon
+// from the same base color the coverage refresh assigns, so a video-feed camera
+// stays violet while it dims instead of falling back to the idle cyan.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRendering } from './rendering.js';
+import {
+  ACTIVE_CAMERA_COLOR,
+  IDLE_CAMERA_COLOR,
+  LIVE_CAMERA_COLOR,
+} from './policy.js';
+import { isVideoFeedType } from '../../sources/cctvTypes.js';
+
+const FOCUS_FACTOR = 0.5;
+
+function assertFadedFrom(actual, base, label) {
+  assert.ok(actual, `${label}: color written`);
+  assert.deepEqual(
+    [actual.red, actual.green, actual.blue],
+    [base.red, base.green, base.blue],
+    `${label}: hue`,
+  );
+  assert.equal(actual.alpha, base.alpha * FOCUS_FACTOR, `${label}: alpha`);
+}
+
+test('focus de-emphasis fades each icon from its own color', () => {
+  const record = (id, feedType) => ({
+    camera: { id, feedType },
+    // No position, so the pass skips screen projection; the focus stub below
+    // decides the factor on its own.
+    billboard: { show: true },
+  });
+  const idleVideo = record('idle-hls', 'hls');
+  const idleStill = record('idle-image', 'image');
+  const activeVideo = record('active-hls', 'hls');
+  const state = {
+    _enabled: true,
+    _viewer: { scene: {}, camera: {} },
+    _records: [idleVideo, idleStill, activeVideo],
+    _activeCameraId: activeVideo.camera.id,
+    _activeFocusStyleCount: 0,
+    _lastFocusStyleAt: -Infinity,
+  };
+  const focus = {
+    focusNowMs: (nowMs) => nowMs,
+    getFocusTarget: () => ({}),
+    focusPassIsNeeded: () => true,
+    advanceSpriteFocus: () => ({
+      factor: FOCUS_FACTOR,
+      active: true,
+      transitioning: false,
+    }),
+    focusAlphaNeedsWrite: () => true,
+  };
+  const { refreshCctvFocusStyles } = createRendering({
+    state,
+    services: { focus },
+    parts: { model: { isVideoFeedType } },
+    source: {},
+  });
+
+  refreshCctvFocusStyles(1000);
+
+  assertFadedFrom(idleVideo.billboard.color, LIVE_CAMERA_COLOR, 'idle video');
+  assertFadedFrom(idleStill.billboard.color, IDLE_CAMERA_COLOR, 'idle still');
+  assertFadedFrom(
+    activeVideo.billboard.color,
+    ACTIVE_CAMERA_COLOR,
+    'active video',
+  );
+  assert.equal(state._activeFocusStyleCount, 3);
+});

src/layers/cctv/source.js

@@ -3,6 +3,12 @@ import {
   FRAME_ENDPOINT,
   MEDIA_ENDPOINT,
 } from './sourcePolicy.js';
+const FRAME_SOURCE_KINDS = new Set([
+  'upstream-image',
+  'hls-pull',
+  'streetview',
+  'synthetic',
+]);
 function safeNumber(value, fallback = NaN) {
   const n = Number(value);
   return Number.isFinite(n) ? n : fallback;
@@ -51,7 +57,7 @@ export function createCctvSource({
     },
     getFrameUrl: frameUrlFor,
     getMediaUrl: mediaUrlFor,
-    /** Read one current frame through the registered frame endpoint. */
+    /** Read a registered frame and its provenance, including fallback frames. */
     async getFrame(camera, { signal } = {}) {
       signal?.throwIfAborted();
       const response = await fetchImpl(frameUrlFor(camera), {
@@ -62,7 +68,12 @@ export function createCctvSource({
       const bytes = new Uint8Array(await response.arrayBuffer());
       signal?.throwIfAborted();
       const type = response.headers.get('content-type') || '';
-      return { contentType: type.split(';')[0].trim().toLowerCase(), bytes };
+      const sourceKind = response.headers.get('x-cctv-source');
+      return {
+        contentType: type.split(';')[0].trim().toLowerCase(),
+        bytes,
+        sourceKind: FRAME_SOURCE_KINDS.has(sourceKind) ? sourceKind : null,
+      };
     },
   };
 }

src/layers/cctv/source.test.mjs

@@ -173,3 +173,26 @@ test('frames are read through the registered frame endpoint', async () => {
   });
   await assert.rejects(failing.getFrame(camera), /Camera frame HTTP 502/);
 });
+
+test('frame provenance admits the proxy kinds and leaves missing or unknown headers unknown', async () => {
+  for (const kind of [
+    'upstream-image',
+    'hls-pull',
+    'streetview',
+    'synthetic',
+    'other',
+    null,
+  ]) {
+    const source = createCctvSource({
+      fetchImpl: async () =>
+        new Response(new Uint8Array([1]), {
+          headers: {
+            'Content-Type': 'image/png',
+            ...(kind ? { 'X-CCTV-Source': kind } : {}),
+          },
+        }),
+    });
+    const frame = await source.getFrame(camera);
+    assert.equal(frame.sourceKind, kind === 'other' ? null : kind);
+  }
+});

src/layers/cctv/sourcePolicy.js

@@ -1,9 +1,5 @@
 export const FRAME_ENDPOINT = '/api/cctv/frame';
 
-export const SOURCE_ENDPOINT = '/api/cctv/sources';
-
-export const HEALTH_ENDPOINT = '/api/cctv/health';
-
 export const MEDIA_ENDPOINT = '/api/cctv/media';
 
 export const ACTIVE_FRAME_REFRESH_MS = 10000;

src/layers/cctv/videoPlayback.js

@@ -1,3 +1,28 @@
+/**
+ * A v4 UUID for the client lease. `crypto.randomUUID` only exists in secure
+ * contexts, so a page opened over plain HTTP from another machine (the
+ * HOST=0.0.0.0 LAN opt-in) has none; `getRandomValues` exists in every context
+ * and yields the same shape the server's lease check accepts.
+ */
+export function createLeaseId(cryptoImpl = globalThis.crypto) {
+  if (typeof cryptoImpl.randomUUID === 'function') {
+    return cryptoImpl.randomUUID();
+  }
+  const bytes = cryptoImpl.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0'));
+  return [
+    hex.slice(0, 4),
+    hex.slice(4, 6),
+    hex.slice(6, 8),
+    hex.slice(8, 10),
+    hex.slice(10),
+  ]
+    .map((group) => group.join(''))
+    .join('-');
+}
+
 /** One decoder per active camera; both surfaces consume this video element. */
 export function attachCctvVideo(
   video,
@@ -7,13 +32,14 @@ export function attachCctvVideo(
     loadHls = () => import('hls.js'),
     onFailure = () => {},
     fetchImpl = globalThis.fetch,
+    cryptoImpl = globalThis.crypto,
   } = {},
 ) {
   // Preserve replay for existing finite video feeds; live HLS must not loop.
   video.loop = feedType !== 'hls';
   let disposed = false;
   let hls = null;
-  const leaseId = feedType === 'hls' ? globalThis.crypto.randomUUID() : null;
+  const leaseId = feedType === 'hls' ? createLeaseId(cryptoImpl) : null;
   const mediaUrl =
     feedType === 'hls'
       ? `${url}${url.includes('?') ? '&' : '?'}lease=${leaseId}`

src/layers/cctv/videoPlayback.test.mjs

@@ -1,6 +1,15 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { attachCctvVideo } from './videoPlayback.js';
+import { webcrypto } from 'node:crypto';
+import { attachCctvVideo, createLeaseId } from './videoPlayback.js';
+
+const LEASE_V4 =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/** What an insecure context exposes: getRandomValues but no randomUUID. */
+const insecureCrypto = {
+  getRandomValues: (array) => webcrypto.getRandomValues(array),
+};
 function video() {
   const v = new EventTarget();
   Object.assign(v, {
@@ -69,6 +78,34 @@ test('native HLS releases its client lease without response-header access', asyn
   assert.equal(releases[0].init.method, 'DELETE');
 });
 
+test('lease ids are v4 UUIDs with or without crypto.randomUUID', () => {
+  assert.match(createLeaseId(), LEASE_V4);
+  const ids = new Set();
+  for (let i = 0; i < 64; i++) ids.add(createLeaseId(insecureCrypto));
+  assert.equal(ids.size, 64);
+  for (const id of ids) assert.match(id, LEASE_V4);
+});
+
+test('HLS starts on a plain-HTTP LAN page without crypto.randomUUID', async () => {
+  const source = video();
+  source.canPlayType = () => 'probably';
+  const playback = attachCctvVideo(source, '/api/cctv/media/a', 'hls', {
+    loadHls: async () => ({ default: { isSupported: () => false } }),
+    fetchImpl: async () => {},
+    cryptoImpl: insecureCrypto,
+  });
+  try {
+    await playback.ready;
+    const lease = new URL(
+      source.src,
+      'http://192.168.1.10:4173/',
+    ).searchParams.get('lease');
+    assert.match(lease, LEASE_V4);
+  } finally {
+    playback.dispose();
+  }
+});
+
 test('finite video feeds retain looping while live HLS does not loop', async () => {
   for (const feedType of ['mp4', 'webm', 'hls']) {
     const source = video();

src/layers/cyclones/coverage.test.mjs

@@ -0,0 +1,134 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createCyclonesLayer } from './index.js';
+import { setLocale, t } from '../../i18n/index.js';
+
+// The exact string the server sends (COVERAGE in server/providers/cyclones.js).
+const SERVER_COVERAGE =
+  'Atlantic and eastern/central North Pacific; not worldwide cyclone coverage.';
+const time = '2026-09-16T03:00:00.000Z';
+const storm = {
+  id: 'ep152026',
+  name: 'Fifteen-E',
+  classification: 'PTC',
+  basin: 'EP',
+  position: { longitude: -125.8, latitude: 15.5 },
+  positionAt: time,
+  issuedAt: time,
+  advisoryNumber: '10',
+  windKt: 25,
+  pressureHpa: 1006,
+  geometryStatus: 'pending',
+  geometryAdvisoryNumber: null,
+  forecastPoints: [],
+  track: null,
+  cone: null,
+  advisoryUrl: 'https://www.nhc.noaa.gov/text/MIATCMEP5.shtml',
+};
+const snapshot = (storms, extra = {}) => ({
+  schemaVersion: 1,
+  storms,
+  unavailable: false,
+  stale: false,
+  fetchedAt: Date.parse(time),
+  coverage: SERVER_COVERAGE,
+  reason: null,
+  ...extra,
+});
+function harness(feed) {
+  const rendering = {
+    async setSnapshot() {
+      return true;
+    },
+    setSelection() {},
+    getFocusSphere: () => ({ radius: 500000 }),
+    clear() {},
+    destroy() {},
+    getDiagnostics: () => ({ entities: 0, timerActive: false }),
+  };
+  const layer = createCyclonesLayer({
+    feed,
+    createRendering: () => rendering,
+    matchMedia: () => ({ matches: false }),
+    openLink: () => {},
+  });
+  layer.init({ camera: { flyToBoundingSphere() {} } });
+  layer.attachShellServices({ runNavigation: (fn) => fn() });
+  return layer;
+}
+
+const translated = () => t(SERVER_COVERAGE);
+
+test('es: server snapshot without storms -> coverage line in Spanish', async () => {
+  setLocale('es');
+  try {
+    assert.notEqual(translated(), SERVER_COVERAGE, 'es.json has a translation');
+    const layer = harness({ getSnapshot: async () => snapshot([]) });
+    layer.enable();
+    await layer.update();
+    const info = layer.getRowControls().info;
+    assert.ok(
+      info.endsWith(translated()),
+      `expected Spanish coverage, got:\n${info}`,
+    );
+    layer.destroy();
+  } finally {
+    setLocale('en');
+  }
+});
+
+test('es: server snapshot with a storm -> coverage line in Spanish', async () => {
+  setLocale('es');
+  try {
+    const layer = harness({ getSnapshot: async () => snapshot([storm]) });
+    layer.enable();
+    await layer.update();
+    const info = layer.getRowControls().info;
+    assert.ok(
+      info.endsWith(translated()),
+      `expected Spanish coverage, got:\n${info}`,
+    );
+    layer.destroy();
+  } finally {
+    setLocale('en');
+  }
+});
+
+test('es: unavailable without reason -> fallback status not the English literal', async () => {
+  setLocale('es');
+  try {
+    const layer = harness({
+      getSnapshot: async () =>
+        snapshot([], { unavailable: true, reason: null }),
+    });
+    layer.enable();
+    await layer.update();
+    const status = layer.getRowControls().summary.status;
+    assert.notEqual(
+      status,
+      'Cyclone advisories unavailable',
+      `fallback shown in English: ${status}`,
+    );
+    layer.destroy();
+  } finally {
+    setLocale('en');
+  }
+});
+
+test('en: coverage and fallback status read as before', async () => {
+  const layer = harness({ getSnapshot: async () => snapshot([]) });
+  layer.enable();
+  await layer.update();
+  assert.ok(layer.getRowControls().info.endsWith(SERVER_COVERAGE));
+  layer.destroy();
+  const down = harness({
+    getSnapshot: async () => snapshot([], { unavailable: true, reason: null }),
+  });
+  down.enable();
+  await down.update();
+  assert.equal(
+    down.getRowControls().summary.status,
+    'Cyclone advisories unavailable',
+  );
+  down.destroy();
+});

src/layers/cyclones/index.js

@@ -14,23 +14,50 @@ import {
   CYCLONE_OVERLAY_SOURCE_ID,
   cycloneStormIdFromEntryId,
 } from './labels.js';
+import {
+  formatUtcDayMonth,
+  t,
+  tn,
+  msg,
+  translateKnown,
+} from '../../i18n/index.js';
+import { formatQuantity } from '../../ui/unitLabels.js';
 
+// "10-12 15:00 UTC" never breaks across lines: no-break spaces, and a word
+// joiner after the hyphen (JetBrains Mono has no U+2011 non-breaking hyphen).
 const utc = (value) =>
-  value ? `${value.slice(5, 16).replace('T', ' ')} UTC` : 'Unavailable';
-const COVERAGE =
-  'Atlantic and eastern/central North Pacific; not worldwide cyclone coverage.';
+  value
+    ? `${formatUtcDayMonth(value).replace('-', '-\u2060')}\u00a0${value.slice(11, 16)}\u00a0UTC`
+    : t('Unavailable');
+const COVERAGE = msg(
+  'Atlantic and eastern/central North Pacific; not worldwide cyclone coverage.',
+);
+// The server sends the same English coverage (server/providers/cyclones.js);
+// data stays English and is translated here, where it is shown.
+const coverageText = (coverage) =>
+  !coverage || coverage === COVERAGE ? t(COVERAGE) : translateKnown(coverage);
+const ADVISORIES_UNAVAILABLE = msg('Cyclone advisories unavailable');
+// Reason the server gives with an unavailable snapshot, translated when shown.
+const SERVER_REASONS = new Set([msg('Cyclone data unavailable')]);
+const errorText = (error) =>
+  error && (SERVER_REASONS.has(error) ? t(error) : translateKnown(error));
+// NHC's Tropical Cyclone Status JSON reference: PTC is post-tropical, PC is a
+// potential tropical cyclone, and subtropical systems are STS and STD.
 const CLASSIFICATION_NAMES = Object.freeze({
-  PTC: 'Potential tropical cyclone',
-  HU: 'Hurricane',
-  TS: 'Tropical storm',
-  TD: 'Tropical depression',
-  SS: 'Subtropical storm',
-  SD: 'Subtropical depression',
+  PC: msg('Potential tropical cyclone'),
+  PTC: msg('Post-tropical cyclone'),
+  HU: msg('Hurricane'),
+  TS: msg('Tropical storm'),
+  TD: msg('Tropical depression'),
+  STS: msg('Subtropical storm'),
+  STD: msg('Subtropical depression'),
 });
 const classificationName = (code) =>
-  Object.hasOwn(CLASSIFICATION_NAMES, code) ? CLASSIFICATION_NAMES[code] : code;
+  Object.hasOwn(CLASSIFICATION_NAMES, code)
+    ? t(CLASSIFICATION_NAMES[code])
+    : code;
 const number = (value, unit) =>
-  value === null ? 'Unavailable' : `${value} ${unit}`;
+  value === null ? t('Unavailable') : formatQuantity(value, unit);
 
 /** Advisory status and coherent forecast geometry; selected through the shared row list. */
 export function createCyclonesLayer({
@@ -229,7 +256,7 @@ export function createCyclonesLayer({
           snapshot = next;
           selectedId = null;
           ++navigationGeneration;
-          error = next.reason || 'Cyclone advisories unavailable';
+          error = next.reason || ADVISORIES_UNAVAILABLE;
           return true;
         }
         const applied = await rendering.setSnapshot(next, {
@@ -254,7 +281,7 @@ export function createCyclonesLayer({
         return true;
       } catch (cause) {
         if (controller.signal.aborted || request !== controller) return false;
-        error = cause?.message || 'Cyclone advisories unavailable';
+        error = cause?.message || ADVISORIES_UNAVAILABLE;
         // Failed acquisition has no bounded last-good age guarantee at this layer.
         rendering?.clear();
         snapshot = null;
@@ -316,41 +343,68 @@ export function createCyclonesLayer({
       const geometry =
         storm &&
         (coherentCycloneGeometry(storm)
-          ? 'Track and cone match this advisory'
+          ? t('Track and cone match this advisory')
           : storm.geometryStatus === 'pending'
-            ? `Track/cone awaiting advisory ${storm.advisoryNumber}`
-            : 'Track/cone unavailable');
+            ? t('Track/cone awaiting advisory {number}', {
+                number: storm.advisoryNumber,
+              })
+            : t('Track/cone unavailable'));
       const status =
-        error ||
+        errorText(error) ||
         (snapshot?.stale
-          ? 'Cached advisory · stale source'
+          ? t('Cached advisory · stale source')
           : loading
-            ? 'Loading advisories…'
+            ? t('Loading advisories…')
             : storm && !coherentCycloneGeometry(storm)
               ? geometry
               : null);
+      const stormCount = snapshot?.storms.length || 0;
+      const activeStorms = tn(
+        stormCount,
+        '{count} active storm',
+        '{count} active storms',
+      );
+      const position = storm
+        ? t('Position as of {time}', { time: utc(storm.positionAt) })
+        : '';
+      const intensity = storm
+        ? t('Maximum sustained wind: {wind} · Pressure: {pressure}', {
+            wind: number(storm.windKt, 'kt'),
+            pressure: number(storm.pressureHpa, 'hPa'),
+          })
+        : '';
       const detail = storm
-        ? `${storm.name} · ${classificationName(storm.classification)} · Advisory ${storm.advisoryNumber} · issued ${utc(storm.issuedAt)}`
+        ? t('{name} · {classification} · Advisory {number} · issued {time}', {
+            name: storm.name,
+            classification: classificationName(storm.classification),
+            number: storm.advisoryNumber,
+            time: utc(storm.issuedAt),
+          })
         : empty
-          ? 'No active NHC/CPHC systems'
-          : snapshot?.storms.length
-            ? `${snapshot.storms.length} active storm${snapshot.storms.length === 1 ? '' : 's'}`
+          ? t('No active NHC/CPHC systems')
+          : stormCount
+            ? activeStorms
             : loading
-              ? 'Loading advisories…'
-              : 'Advisories unavailable';
+              ? t('Loading advisories…')
+              : t('Advisories unavailable');
       const controls = {
         readout: true,
         summary: {
-          label: 'Cyclones · NHC / CPHC',
-          coverage: 'Atlantic · E/C Pacific',
-          compact: snapshot?.storms.length
-            ? `${snapshot.storms.length} active storm${snapshot.storms.length === 1 ? '' : 's'}${storm ? ` · ${storm.name} selected` : ''}`
+          label: t('Cyclones · NHC / CPHC'),
+          coverage: t('Atlantic · E/C Pacific'),
+          compact: stormCount
+            ? storm
+              ? t('{storms} · {name} selected', {
+                  storms: activeStorms,
+                  name: storm.name,
+                })
+              : activeStorms
             : detail,
           actions: storm?.advisoryUrl
             ? [
                 {
                   id: 'advisory',
-                  label: 'Official advisory ↗',
+                  label: t('Official advisory ↗'),
                   href: storm.advisoryUrl,
                 },
               ]
@@ -360,12 +414,12 @@ export function createCyclonesLayer({
             ? [
                 {
                   id: 'position',
-                  text: `Position as of ${utc(storm.positionAt)}`,
+                  text: position,
                   muted: true,
                 },
                 {
                   id: 'intensity',
-                  text: `Maximum sustained wind: ${number(storm.windKt, 'kt')} · Pressure: ${number(storm.pressureHpa, 'hPa')}`,
+                  text: intensity,
                 },
                 { id: 'geometry', text: geometry, muted: true },
               ]
@@ -375,34 +429,71 @@ export function createCyclonesLayer({
           units: 'kt',
         },
         list: {
-          ariaLabel: 'Active NHC and CPHC cyclone advisories',
+          ariaLabel: t('Active NHC and CPHC cyclone advisories'),
           items: (snapshot?.storms || []).map((item, index) => ({
             id: item.id,
             ordinal: index + 1,
             lead: item.basin,
-            text: `${item.name} · ${classificationName(item.classification)} · ${item.windKt === null ? 'Wind unavailable' : `${item.windKt} kt`}`,
+            text: `${item.name} · ${classificationName(item.classification)} · ${item.windKt === null ? t('Wind unavailable') : formatQuantity(item.windKt, 'kt')}`,
             active: item.id === selectedId,
             params: { stormId: item.id, focus: true },
           })),
         },
         chips: [],
+        legendCategorical: true,
         legend: storm
           ? [
-              { label: 'Advisory center / forecast track', color: '#7fe6ed' },
-              { label: 'Center-track uncertainty cone', color: '#7fe6ed44' },
+              {
+                label: t('Advisory center / forecast track'),
+                color: '#7fe6ed',
+              },
+              {
+                label: t('Center-track uncertainty cone'),
+                color: '#7fe6ed44',
+              },
             ]
           : [],
         info: storm
-          ? `${detail}\nPosition as of ${utc(storm.positionAt)}\nMaximum sustained wind: ${number(storm.windKt, 'kt')} · Pressure: ${number(storm.pressureHpa, 'hPa')}\n${geometry}${status && status !== geometry ? '\n' + status : ''}\n${snapshot.coverage}`
-          : `${detail}${status ? '\n' + status : ''}\n${snapshot?.coverage || COVERAGE}`,
-        infoTitle:
+          ? `${detail}\n${position}\n${intensity}\n${geometry}${status && status !== geometry ? '\n' + status : ''}\n${coverageText(snapshot.coverage)}`
+          : `${detail}${status ? '\n' + status : ''}\n${coverageText(snapshot?.coverage)}`,
+        infoTitle: t(
           'Select a storm on the map, or choose a storm in the list to select it and move the camera. Click empty map space to clear the selection. NOAA NHC/CPHC advisory context. The cone describes forecast center-track uncertainty, not storm size or the full hazard area. Forecast point labels are source lead hours, not times computed from advisory issuance. Geometry follows the surface; height is not weather altitude. Consult the official advisory.',
+        ),
       };
       return controls;
     },
     setRowControlsListener(value) {
       listener = typeof value === 'function' ? value : null;
     },
+    /**
+     * Snapshot loaded active storms as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, name, classification, basin, lat, lon, windKt, pressureHpa}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!enabled || destroyed) return [];
+      const num = (v) => (Number.isFinite(v) ? v : null);
+      const result = [];
+      for (const storm of snapshot?.storms || []) {
+        if (result.length >= maxCount) break;
+        const lat = storm.position?.latitude;
+        const lon = storm.position?.longitude;
+        if (!Number.isFinite(lat) || !Number.isFinite(lon)) continue;
+        result.push({
+          id: storm.name || storm.id,
+          name: storm.name || null,
+          classification: storm.classification || null,
+          basin: storm.basin || null,
+          lat,
+          lon,
+          windKt: num(storm.windKt),
+          pressureHpa: num(storm.pressureHpa),
+        });
+      }
+      return result;
+    },
     getStats() {
       const storm = selected();
       return {

src/layers/cyclones/index.test.mjs

@@ -513,12 +513,13 @@ test('only the latest queued focus runs and an unchanged selection survives refr
 });
 test('classification display expands known codes without altering the source or guessing unknown meanings', async () => {
   for (const [code, label] of [
-    ['PTC', 'Potential tropical cyclone'],
+    ['PC', 'Potential tropical cyclone'],
+    ['PTC', 'Post-tropical cyclone'],
     ['HU', 'Hurricane'],
     ['TS', 'Tropical storm'],
     ['TD', 'Tropical depression'],
-    ['SS', 'Subtropical storm'],
-    ['SD', 'Subtropical depression'],
+    ['STS', 'Subtropical storm'],
+    ['STD', 'Subtropical depression'],
     ['EX', 'EX'],
     ['UNKNOWN', 'UNKNOWN'],
   ]) {
@@ -565,7 +566,9 @@ test('advisory selection uses accessible row descriptors and shared camera hando
     1,
   );
   assert.equal(controls.summary.status, 'Track/cone awaiting advisory 10');
-  assert.match(controls.info, /09-16 03:00 UTC/);
+  // No line break inside the date: a word joiner holds the hyphen.
+  assert.match(controls.info, /issued 09-\u206016\u00a003:00\u00a0UTC/);
+  assert.match(controls.info, /: 25\u00a0kt · .*: 1006\u00a0hPa/);
   assert.match(controls.infoTitle, /not storm size/);
   assert.match(controls.infoTitle, /follows the surface/);
   assert.equal(controls.list.items[1].params.focus, true);

src/layers/cyclones/labels.js

@@ -64,7 +64,7 @@ const SHARED_CARD = Object.freeze({
  * @param {boolean} selected
  * @returns {object}
  */
-export function cycloneStormEntry(storm, selected) {
+function cycloneStormEntry(storm, selected) {
   return {
     ...SHARED_CARD,
     ...markerClearance(
@@ -92,7 +92,7 @@ export function cycloneStormEntry(storm, selected) {
  * @param {{tauHours:number,position:object}} point
  * @returns {object}
  */
-export function cycloneLeadEntry(stormId, point) {
+function cycloneLeadEntry(stormId, point) {
   return {
     ...SHARED_CARD,
     ...markerClearance(CYCLONE_MARKER_PX.forecast),

src/layers/directions/index.js

@@ -17,10 +17,10 @@
  */
 
 import * as Cesium from 'cesium';
-import {
-  formatRouteDistance,
-  formatRouteDuration,
-} from '../../data/routeSteps.js';
+import { roadLabel } from '../../data/routeSteps.js';
+import { t, msg, formatNumber, translateKnown } from '../../i18n/index.js';
+import { pointerOwnerName } from '../../data/pointerOwnerNames.js';
+import { formatQuantity } from '../../ui/unitLabels.js';
 
 export const DIRECTIONS_STEP_OVERLAY_SOURCE_ID = 'directions-step';
 export const DIRECTIONS_STEP_OVERLAY_SOURCE_OPTIONS = Object.freeze({
@@ -31,12 +31,42 @@ export const DIRECTIONS_STEP_OVERLAY_SOURCE_OPTIONS = Object.freeze({
 
 /** Travel modes, keyed by the `/api/route` profile name. */
 export const DIRECTIONS_MODES = Object.freeze({
-  car: Object.freeze({ chip: 'DRIVE', word: 'Drive', icon: '🚗' }),
-  foot: Object.freeze({ chip: 'WALK', word: 'Walk', icon: '🚶' }),
-  bike: Object.freeze({ chip: 'BIKE', word: 'Bike', icon: '🚲' }),
+  car: Object.freeze({ chip: msg('DRIVE'), word: msg('Drive'), icon: '🚗' }),
+  foot: Object.freeze({ chip: msg('WALK'), word: msg('Walk'), icon: '🚶' }),
+  bike: Object.freeze({ chip: msg('BIKE'), word: msg('Bike'), icon: '🚲' }),
 });
 export const DEFAULT_DIRECTIONS_MODE = 'car';
 
+/**
+ * The route proxy's refusal texts (server/providers/places/routes.js). They
+ * stay English on the wire and in the AI tools; the row shows them translated.
+ */
+const ROUTING_REFUSALS = new Set([
+  msg('rate limited'),
+  msg('routing service is rate limited'),
+  msg('route leg too long'),
+  msg('route too long'),
+]);
+
+/** A refusal text from the route proxy in the language; unknown ones as given. */
+export function presentRoutingRefusal(text) {
+  return ROUTING_REFUSALS.has(text) ? t(text) : text;
+}
+
+/** The row text for a failed route request (createDirectionsSource errors). */
+export function presentRoutingFailure(error) {
+  if (error?.status === 429) {
+    return error.refusal
+      ? t('{error} — try again in a moment', {
+          error: presentRoutingRefusal(error.refusal),
+        })
+      : t('Routing is rate limited — try again in a moment');
+  }
+  if (Number.isFinite(error?.status) && error.status > 0)
+    return t('Routing unavailable (HTTP {status})', { status: error.status });
+  return error?.message || t('Routing unavailable');
+}
+
 /** Route colour — the annotation palette's cyan, so voice routes and Directions match. */
 export const DIRECTIONS_ROUTE_COLOR = '#39d0ff';
 const MARKER_A_COLOR = Cesium.Color.fromCssColorString('#5dff9f');
@@ -68,6 +98,285 @@ export const STEP_ANCHOR_FAST_ATTEMPTS = 5;
 /** How often the row repaints the highlighted step while FLY is running (ms). */
 export const FLIGHT_PROGRESS_MS = 250;
 
+// ---------------------------------------------------------------------------
+// Display text in the page's language. The proxy's English `instruction` stays
+// the machine value; steps are phrased from their OSRM type/modifier/road.
+// ---------------------------------------------------------------------------
+
+/**
+ * Localized "850 m", "1.2 km", "21 km" (the rounding of `formatRouteDistance`
+ * in src/data/routeSteps.js); number and unit never break apart.
+ * @param {number} meters
+ * @returns {string}
+ */
+export function routeDistanceText(meters) {
+  if (!Number.isFinite(meters) || meters < 0) return '';
+  if (meters < 100) return formatQuantity(Math.round(meters), 'm');
+  const tens = Math.round(meters / 10) * 10;
+  if (tens < 1000) return formatQuantity(tens, 'm');
+  const km = meters / 1000;
+  return km < 10
+    ? formatQuantity(km, 'km', {
+        minimumFractionDigits: 1,
+        maximumFractionDigits: 1,
+      })
+    : formatQuantity(Math.round(km), 'km');
+}
+
+/**
+ * Localized "40 s", "12 min", "1 h 5 min" (the rounding of
+ * `formatRouteDuration` in src/data/routeSteps.js); never broken apart.
+ * @param {number} seconds
+ * @returns {string}
+ */
+export function routeDurationText(seconds) {
+  if (!Number.isFinite(seconds) || seconds < 0) return '';
+  const wholeSeconds = Math.round(seconds);
+  if (wholeSeconds < 60) return formatQuantity(wholeSeconds, 's');
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return formatQuantity(minutes, 'min');
+  const hours = formatQuantity(Math.floor(minutes / 60), 'h');
+  const rest = minutes % 60;
+  return rest ? `${hours}\u00a0${formatQuantity(rest, 'min')}` : hours;
+}
+
+/** "left", "slightly right", … as it reads inside a maneuver sentence. */
+function directionWord(modifier) {
+  switch (modifier) {
+    case 'left':
+      return t('left', { context: 'direction' });
+    case 'right':
+      return t('right', { context: 'direction' });
+    case 'slight left':
+      return t('slightly left', { context: 'direction' });
+    case 'slight right':
+      return t('slightly right', { context: 'direction' });
+    case 'sharp left':
+      return t('sharply left', { context: 'direction' });
+    case 'sharp right':
+      return t('sharply right', { context: 'direction' });
+    case 'straight':
+      return t('straight', { context: 'direction' });
+    case 'uturn':
+      return t('around', { context: 'direction' });
+    default:
+      return modifier;
+  }
+}
+
+/**
+ * The side to keep at a fork. English reuses the turn words; a language may
+ * need another form here ("держитесь левее", not "держитесь налево").
+ */
+function forkWord(modifier) {
+  switch (modifier) {
+    case 'left':
+      return t('left', { context: 'fork direction' });
+    case 'right':
+      return t('right', { context: 'fork direction' });
+    case 'slight left':
+      return t('slightly left', { context: 'fork direction' });
+    case 'slight right':
+      return t('slightly right', { context: 'fork direction' });
+    case 'sharp left':
+      return t('sharply left', { context: 'fork direction' });
+    case 'sharp right':
+      return t('sharply right', { context: 'fork direction' });
+    case 'straight':
+      return t('straight', { context: 'fork direction' });
+    default:
+      return directionWord(modifier);
+  }
+}
+
+/** The lane to use, as an adjective where a language needs one ("левую полосу"). */
+function laneWord(modifier) {
+  switch (modifier) {
+    case 'left':
+      return t('left', { context: 'lane direction' });
+    case 'right':
+      return t('right', { context: 'lane direction' });
+    case 'slight left':
+      return t('slightly left', { context: 'lane direction' });
+    case 'slight right':
+      return t('slightly right', { context: 'lane direction' });
+    case 'sharp left':
+      return t('sharply left', { context: 'lane direction' });
+    case 'sharp right':
+      return t('sharply right', { context: 'lane direction' });
+    case 'straight':
+      return t('straight', { context: 'lane direction' });
+    default:
+      return directionWord(modifier);
+  }
+}
+
+/** "1st", "2nd", … for a roundabout exit. */
+function exitOrdinal(exit) {
+  const number = formatNumber(exit);
+  switch (new Intl.PluralRules('en', { type: 'ordinal' }).select(exit)) {
+    case 'one':
+      return t('{number}st', { context: 'ordinal', number });
+    case 'two':
+      return t('{number}nd', { context: 'ordinal', number });
+    case 'few':
+      return t('{number}rd', { context: 'ordinal', number });
+    default:
+      return t('{number}th', { context: 'ordinal', number });
+  }
+}
+
+/**
+ * One maneuver in the page's language, from the step's OSRM type, modifier,
+ * exit and road. English matches `instructionFor` in src/data/routeSteps.js
+ * word for word. A step without a type (an older payload) keeps the proxy's
+ * English instruction.
+ * @param {{type?:string, modifier?:string|null, exit?:number|null, name?:string, ref?:string|null, instruction?:string}} step
+ * @returns {string}
+ */
+export function directionsInstruction(step) {
+  const type =
+    typeof step?.type === 'string' ? step.type.trim().toLowerCase() : '';
+  if (!type)
+    return typeof step?.instruction === 'string' ? step.instruction : '';
+  const modifier =
+    typeof step.modifier === 'string' ? step.modifier.trim().toLowerCase() : '';
+  const road = roadLabel(step);
+  const direction = directionWord(modifier);
+  const values = { road, direction };
+  switch (type) {
+    case 'depart':
+      return road ? t('Head out on {road}', values) : t('Head out');
+    case 'arrive':
+      if (modifier === 'left')
+        return t('Arrive at your destination, on the left');
+      if (modifier === 'right')
+        return t('Arrive at your destination, on the right');
+      return t('Arrive at your destination');
+    case 'turn':
+      if (modifier === 'uturn')
+        return road
+          ? t('Make a U-turn onto {road}', values)
+          : t('Make a U-turn');
+      if (modifier === 'straight')
+        return road
+          ? t('Continue straight onto {road}', values)
+          : t('Continue straight');
+      if (direction)
+        return road
+          ? t('Turn {direction} onto {road}', values)
+          : t('Turn {direction}', values);
+      return road
+        ? t('Turn onto {road}', values)
+        : t('Turn', { context: 'maneuver' });
+    case 'continue':
+      if (modifier === 'uturn')
+        return road
+          ? t('Make a U-turn onto {road}', values)
+          : t('Make a U-turn');
+      if (direction && modifier !== 'straight')
+        return road
+          ? t('Continue {direction} onto {road}', values)
+          : t('Continue {direction}', values);
+      return road
+        ? t('Continue straight onto {road}', values)
+        : t('Continue straight');
+    case 'end of road':
+      if (direction)
+        return road
+          ? t('At the end of the road, turn {direction} onto {road}', values)
+          : t('At the end of the road, turn {direction}', values);
+      return road
+        ? t('At the end of the road, continue onto {road}', values)
+        : t('At the end of the road, continue');
+    case 'fork':
+      if (direction) {
+        const fork = { road, direction: forkWord(modifier) };
+        return road
+          ? t('Keep {direction} at the fork onto {road}', fork)
+          : t('Keep {direction} at the fork', fork);
+      }
+      return road
+        ? t('Continue at the fork onto {road}', values)
+        : t('Continue at the fork');
+    case 'merge':
+      if (direction)
+        return road
+          ? t('Merge {direction} onto {road}', values)
+          : t('Merge {direction}', values);
+      return road
+        ? t('Merge onto {road}', values)
+        : t('Merge', { context: 'maneuver' });
+    case 'on ramp':
+      if (modifier === 'left' || modifier === 'right')
+        return road
+          ? t('Take the ramp on the {direction} onto {road}', values)
+          : t('Take the ramp on the {direction}', values);
+      if (direction && modifier !== 'straight')
+        return road
+          ? t('Take the ramp {direction} onto {road}', values)
+          : t('Take the ramp {direction}', values);
+      return road ? t('Take the ramp onto {road}', values) : t('Take the ramp');
+    case 'off ramp':
+      if (modifier === 'left' || modifier === 'right')
+        return road
+          ? t('Take the exit on the {direction} onto {road}', values)
+          : t('Take the exit on the {direction}', values);
+      if (direction && modifier !== 'straight')
+        return road
+          ? t('Take the exit {direction} onto {road}', values)
+          : t('Take the exit {direction}', values);
+      return road ? t('Take the exit onto {road}', values) : t('Take the exit');
+    case 'roundabout':
+    case 'rotary':
+      if (Number.isInteger(step.exit) && step.exit >= 1) {
+        const exit = exitOrdinal(step.exit);
+        return road
+          ? t('At the roundabout, take the {exit} exit onto {road}', {
+              exit,
+              road,
+            })
+          : t('At the roundabout, take the {exit} exit', { exit });
+      }
+      return road
+        ? t('Enter the roundabout onto {road}', values)
+        : t('Enter the roundabout');
+    case 'roundabout turn':
+      if (direction)
+        return road
+          ? t('At the roundabout, turn {direction} onto {road}', values)
+          : t('At the roundabout, turn {direction}', values);
+      return road
+        ? t('At the roundabout, continue onto {road}', values)
+        : t('At the roundabout, continue');
+    case 'exit roundabout':
+    case 'exit rotary':
+      return road
+        ? t('Exit the roundabout onto {road}', values)
+        : t('Exit the roundabout');
+    case 'use lane': {
+      const side = modifier.includes('left')
+        ? 'left'
+        : modifier.includes('right')
+          ? 'right'
+          : '';
+      if (side) {
+        const lane = { road, direction: laneWord(side) };
+        return road
+          ? t('Use the {direction} lane onto {road}', lane)
+          : t('Use the {direction} lane', lane);
+      }
+      return road
+        ? t('Continue onto {road}', values)
+        : t('Continue', { context: 'maneuver' });
+    }
+    default:
+      return road
+        ? t('Continue onto {road}', values)
+        : t('Continue', { context: 'maneuver' });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for tests)
 // ---------------------------------------------------------------------------
@@ -107,32 +416,35 @@ export function directionsRowControls(state) {
   const routing = status === 'routing';
   const chips = Object.entries(DIRECTIONS_MODES).map(([id, spec]) => ({
     id: `mode-${id}`,
-    label: spec.chip,
+    label: t(spec.chip),
     active: mode === id,
     state: mode === id ? 'active' : 'idle',
-    title: `${spec.word} — reroute for ${spec.word.toLowerCase()}`,
+    title: t('{mode} — reroute for {modeLower}', {
+      mode: t(spec.word),
+      modeLower: t(spec.word).toLowerCase(),
+    }),
     params: { mode: id },
   }));
   chips.push({
     id: 'set-a',
-    label: armed === 'a' ? 'CLICK MAP' : a ? 'A ✓' : 'SET A',
+    label: armed === 'a' ? t('CLICK MAP') : a ? 'A ✓' : t('SET A'),
     active: armed === 'a',
     state: armed === 'a' ? 'active' : 'idle',
     title:
       armed === 'a'
-        ? 'Click a spot on the globe to place A (click again to cancel)'
-        : 'Then click the globe to place the start',
+        ? t('Click a spot on the globe to place A (click again to cancel)')
+        : t('Then click the globe to place the start'),
     params: { arm: armed === 'a' ? null : 'a' },
   });
   chips.push({
     id: 'set-b',
-    label: armed === 'b' ? 'CLICK MAP' : b ? 'B ✓' : 'SET B',
+    label: armed === 'b' ? t('CLICK MAP') : b ? 'B ✓' : t('SET B'),
     active: armed === 'b',
     state: armed === 'b' ? 'active' : 'idle',
     title:
       armed === 'b'
-        ? 'Click a spot on the globe to place B (click again to cancel)'
-        : 'Then click the globe to place the destination',
+        ? t('Click a spot on the globe to place B (click again to cancel)')
+        : t('Then click the globe to place the destination'),
     params: { arm: armed === 'b' ? null : 'b' },
   });
   chips.push({
@@ -140,26 +452,28 @@ export function directionsRowControls(state) {
     label: '⇄',
     disabled: !(a && b) || routing,
     state: 'idle',
-    title: 'Swap A and B',
+    title: t('Swap A and B'),
     params: { swap: true },
   });
   const flying = Number.isInteger(flightStep);
   chips.push({
     id: 'fly',
-    label: routing ? 'FLY ···' : flying ? 'FLYING' : 'FLY',
+    label: routing ? t('FLY ···') : flying ? t('FLYING') : t('FLY'),
     disabled: !route || routing,
     busy: routing || flying,
     active: flying,
     state: routing || flying ? 'loading' : 'idle',
-    title: route ? 'Fly the camera along the route' : 'Place A and B first',
+    title: route
+      ? t('Fly the camera along the route')
+      : t('Place A and B first'),
     params: { fly: true },
   });
   chips.push({
     id: 'clear',
-    label: 'CLEAR',
+    label: t('CLEAR', { context: 'action' }),
     disabled: !a && !b && !route,
     state: 'idle',
-    title: 'Remove the route and both markers',
+    title: t('Remove the route and both markers'),
     params: { clear: true },
   });
   return {
@@ -179,8 +493,8 @@ export function directionsRowControls(state) {
  */
 export const POINTER_TOOL_EXITS = Object.freeze({
   draw: Object.freeze({
-    name: 'Draw',
-    leave: 'press Escape twice to leave Draw',
+    name: msg('Draw'),
+    leave: msg('press Escape twice to leave Draw'),
   }),
 });
 
@@ -201,9 +515,16 @@ export function pointerBlockedMessage(owner, which) {
   if (!id || id === DIRECTIONS_POINTER_OWNER) return null;
   const endpoint = which === 'b' ? 'B' : 'A';
   const known = POINTER_TOOL_EXITS[id];
-  const name = known?.name || id;
-  const leave = known?.leave || `turn ${name} off`;
-  return `${name} is active — ${leave}, then set ${endpoint}`;
+  if (!known)
+    return t('{name} is active — turn {name} off, then set {endpoint}', {
+      name: translateKnown(pointerOwnerName(id)),
+      endpoint,
+    });
+  return t('{name} is active — {leave}, then set {endpoint}', {
+    name: t(known.name),
+    leave: t(known.leave),
+    endpoint,
+  });
 }
 
 /**
@@ -272,8 +593,8 @@ export function directionsStepList({
   const items = steps.map((step, index) => ({
     id: `step-${index}`,
     ordinal: index + 1,
-    lead: formatRouteDistance(step.distanceM) || '—',
-    text: step.instruction,
+    lead: routeDistanceText(step.distanceM) || '—',
+    text: directionsInstruction(step),
     active: index === active,
     current: Number.isInteger(flightStep) && index === flightStep,
     params: { step: index },
@@ -285,13 +606,15 @@ export function directionsStepList({
       id: 'step-truncated',
       ordinal: items.length + 1,
       lead: '',
-      text: `Only the first ${steps.length} turns of this route are shown`,
+      text: t('Only the first {count} turns of this route are shown', {
+        count: steps.length,
+      }),
       active: false,
       current: false,
       disabled: true,
     });
   }
-  return { ariaLabel: 'Turn-by-turn directions', items };
+  return { ariaLabel: t('Turn-by-turn directions'), items };
 }
 
 /**
@@ -331,12 +654,12 @@ export function directionsStats(state) {
     armed,
     pointerBlocked,
   } = state;
-  const source = 'OSM routing';
+  const source = 'OSM routing'; // English in layer state; the layer row translates it
   if (pointerBlocked) {
     return {
       count: route?.steps.length || 0,
       lastUpdate,
-      error: 'Another map tool is using clicks — close it, then SET A again',
+      error: t('Another map tool is using clicks — close it, then SET A again'),
       status: 'empty',
       source,
     };
@@ -347,7 +670,7 @@ export function directionsStats(state) {
       lastUpdate,
       error: null,
       loading: true,
-      loadingLabel: 'Routing…',
+      loadingLabel: t('Routing…'),
       source,
     };
   }
@@ -355,7 +678,7 @@ export function directionsStats(state) {
     return {
       count: 0,
       lastUpdate,
-      error: error || 'No route found',
+      error: error || t('No route found'),
       status: 'empty',
       source,
     };
@@ -364,10 +687,17 @@ export function directionsStats(state) {
   // set (not only while loading), so the route summary and the placement
   // guidance ride on it; `coverage` carries the same text for stats readers.
   if (route) {
-    const word = DIRECTIONS_MODES[mode]?.word || mode;
-    const summary =
-      `${formatRouteDistance(route.distanceM)} · ${formatRouteDuration(route.durationS)} · ${word}` +
-      (route.stepsTruncated ? ` · first ${route.steps.length} turns` : '');
+    const spec = DIRECTIONS_MODES[mode];
+    const word = spec ? t(spec.word) : mode;
+    const values = {
+      distance: routeDistanceText(route.distanceM),
+      duration: routeDurationText(route.durationS),
+      mode: word,
+      count: route.steps.length,
+    };
+    const summary = route.stepsTruncated
+      ? t('{distance} · {duration} · {mode} · first {count} turns', values)
+      : t('{distance} · {duration} · {mode}', values);
     return {
       count: route.steps.length,
       lastUpdate,
@@ -378,10 +708,13 @@ export function directionsStats(state) {
     };
   }
   let coverage;
-  if (armed) coverage = `Click the globe to place ${armed.toUpperCase()}`;
-  else if (a && !b) coverage = 'SET B, then click the globe';
-  else if (!a && b) coverage = 'SET A, then click the globe';
-  else coverage = 'SET A, then click the globe';
+  if (armed)
+    coverage = t('Click the globe to place {endpoint}', {
+      endpoint: armed.toUpperCase(),
+    });
+  else if (a && !b) coverage = t('SET B, then click the globe');
+  else if (!a && b) coverage = t('SET A, then click the globe');
+  else coverage = t('SET A, then click the globe');
   return {
     count: 0,
     lastUpdate,
@@ -403,14 +736,23 @@ export function directionsStepCopy(steps, index) {
   const step = steps[index];
   const details = [];
   const leg = [];
-  if (step.distanceM > 0) leg.push(formatRouteDistance(step.distanceM));
-  if (step.durationS > 0) leg.push(formatRouteDuration(step.durationS));
+  if (step.distanceM > 0) leg.push(routeDistanceText(step.distanceM));
+  if (step.durationS > 0) leg.push(routeDurationText(step.durationS));
+  const position = { step: index + 1, total: steps.length };
   details.push(
-    `Step ${index + 1} of ${steps.length}${leg.length ? ` · then ${leg.join(' · ')}` : ''}`,
+    leg.length
+      ? t('Step {step} of {total} · then {leg}', {
+          ...position,
+          leg: leg.join(' · '),
+        })
+      : t('Step {step} of {total}', position),
   );
   const next = steps[index + 1];
-  if (next) details.push(`Then: ${next.instruction}`);
-  return { title: step.instruction, details };
+  if (next)
+    details.push(
+      t('Then: {instruction}', { instruction: directionsInstruction(next) }),
+    );
+  return { title: directionsInstruction(step), details };
 }
 
 /**
@@ -452,10 +794,7 @@ export function createDirectionsStepOverlayEntry(index, position, copy) {
  * @param {{lat:number, lon:number}} b
  * @returns {string}
  */
-export function directionsRequestUrl(mode, a, b) {
-  const coords = `${a.lon.toFixed(6)},${a.lat.toFixed(6)};${b.lon.toFixed(6)},${b.lat.toFixed(6)}`;
-  return `/api/route?profile=${encodeURIComponent(mode)}&coords=${encodeURIComponent(coords)}&steps=1`;
-}
+export { directionsRequestUrl } from './source.js';
 
 /**
  * Validate a proxy payload into the route record the layer keeps, or null.
@@ -509,10 +848,12 @@ export function normalizeRoutePayload(payload, mode) {
  * route, the markers, the pointer claim or the flight this layer owns. The
  * shared services are injected, which is what keeps this module's own imports
  * down to Cesium and the pure step formatter.
- * @param {{services: object}} options
+ * @param {{services: object, source: {getRoute: Function}}} options
  * @returns {object} The layer module the data manager registers.
  */
-export function createDirectionsLayer({ services }) {
+export function createDirectionsLayer({ services, source }) {
+  if (typeof source?.getRoute !== 'function')
+    throw new TypeError('Directions require a route source');
   /**
    * Where the maneuver card is drawn. Defaults to the shared world-overlay host;
    * tests swap it. Resolved on use, not at import, because the services arrive
@@ -618,32 +959,11 @@ export function createDirectionsLayer({ services }) {
   }
 
   function pickGround(screenPosition) {
-    const scene = _viewer?.scene;
-    let cartesian = null;
-    if (
-      scene?.pickPositionSupported &&
-      typeof scene.pickPosition === 'function'
-    ) {
-      try {
-        cartesian = scene.pickPosition(screenPosition);
-      } catch {
-        cartesian = null;
-      }
-    }
-    if (
-      !services.scenePick.isPickedWorldPosition(cartesian) &&
-      typeof _viewer?.camera?.pickEllipsoid === 'function'
-    ) {
-      try {
-        cartesian = _viewer.camera.pickEllipsoid(
-          screenPosition,
-          Cesium.Ellipsoid.WGS84,
-        );
-      } catch {
-        cartesian = null;
-      }
-    }
-    if (!services.scenePick.isPickedWorldPosition(cartesian)) return null;
+    const cartesian = services.scenePick.pickGroundPosition(
+      _viewer,
+      screenPosition,
+    );
+    if (!cartesian) return null;
     const carto = Cesium.Cartographic.fromCartesian(cartesian);
     if (!carto) return null;
     return {
@@ -827,18 +1147,12 @@ export function createDirectionsLayer({ services }) {
     _error = null;
     notifyRow();
     try {
-      const response = await fetch(directionsRequestUrl(mode, _a, _b), {
-        signal: controller.signal,
-        headers: { Accept: 'application/json' },
-      });
-      const payload = await response.json();
-      if (response.status === 429) {
-        throw new Error(
-          typeof payload?.error === 'string' && payload.error
-            ? `${payload.error} — try again in a moment`
-            : 'Routing is rate limited — try again in a moment',
-        );
-      }
+      const payload = await source.getRoute(
+        { mode, a: _a, b: _b },
+        {
+          signal: controller.signal,
+        },
+      );
       if (seq !== _routeSeq || !_enabled) return;
       const route = normalizeRoutePayload(payload, mode);
       if (!route) {
@@ -847,10 +1161,12 @@ export function createDirectionsLayer({ services }) {
         _status = 'error';
         _error =
           payload?.error === 'no route found'
-            ? 'No route found between A and B'
+            ? t('No route found between A and B')
             : payload?.error
-              ? `Routing failed: ${payload.error}`
-              : 'No route found between A and B';
+              ? t('Routing failed: {error}', {
+                  error: presentRoutingRefusal(payload.error),
+                })
+              : t('No route found between A and B');
         return;
       }
       _route = route;
@@ -867,10 +1183,10 @@ export function createDirectionsLayer({ services }) {
       // happened instead.
       _error =
         error?.name === 'AbortError'
-          ? 'Routing timed out'
+          ? t('Routing timed out')
           : error?.name === 'TypeError'
-            ? 'Routing unavailable — no response from the routing service'
-            : error?.message || 'Routing unavailable';
+            ? t('Routing unavailable — no response from the routing service')
+            : presentRoutingFailure(error);
     } finally {
       clearTimeout(timer);
       if (_routeAbort === controller) _routeAbort = null;
@@ -1065,7 +1381,7 @@ export function createDirectionsLayer({ services }) {
       [
         {
           type: 'route',
-          label: 'Directions',
+          label: t('Directions'),
           path: _route.geometry.map(([lon, lat]) => ({ lon, lat, height: 0 })),
         },
       ],

src/layers/directions/source.js

@@ -0,0 +1,50 @@
+// A source module (no browser globals, see check:boundaries), so no i18n
+// import: failures stay English here and the layer translates them on show.
+const msg = (text) => text;
+
+/** Build the existing route-proxy query from geographic endpoints. */
+export function directionsRequestUrl(mode, a, b) {
+  const coords = `${a.lon.toFixed(6)},${a.lat.toFixed(6)};${b.lon.toFixed(6)},${b.lat.toFixed(6)}`;
+  return `/api/route?profile=${encodeURIComponent(mode)}&coords=${encodeURIComponent(coords)}&steps=1`;
+}
+
+/** Acquire route records using caller-owned transport and an optional endpoint. */
+export function createDirectionsSource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  endpoint = '/api/route',
+} = {}) {
+  return {
+    async getRoute({ mode, a, b }, { signal } = {}) {
+      signal?.throwIfAborted();
+      const query = directionsRequestUrl(mode, a, b).split('?')[1];
+      const response = await fetchImpl(`${endpoint}?${query}`, {
+        signal,
+        headers: { Accept: 'application/json' },
+      });
+      const payload = await response.json();
+      signal?.throwIfAborted();
+      // Failures keep their English message and carry the HTTP status and the
+      // server's refusal text, so the layer can show them in the language.
+      if (response.status === 429) {
+        const refusal =
+          typeof payload?.error === 'string' && payload.error
+            ? payload.error
+            : null;
+        throw Object.assign(
+          new Error(
+            refusal
+              ? `${refusal} — try again in a moment`
+              : msg('Routing is rate limited — try again in a moment'),
+          ),
+          { status: 429, refusal },
+        );
+      }
+      if (!response.ok && !payload?.error)
+        throw Object.assign(
+          new Error(`Routing unavailable (HTTP ${response.status})`),
+          { status: response.status },
+        );
+      return payload;
+    },
+  };
+}

src/layers/directions/source.test.mjs

@@ -0,0 +1,43 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createDirectionsSource } from './source.js';
+
+const query = { mode: 'foot', a: { lon: 1, lat: 2 }, b: { lon: 3, lat: 4 } };
+
+test('route acquisition uses only the supplied transport and endpoint', async () => {
+  const controller = new AbortController();
+  const payload = { ok: true, geometry: [[1, 2], [3, 4]] };
+  const calls = [];
+  const source = createDirectionsSource({
+    endpoint: 'https://routes.example/route',
+    fetchImpl: async (...args) => { calls.push(args); return Response.json(payload); },
+  });
+  assert.deepEqual(await source.getRoute(query, { signal: controller.signal }), payload);
+  assert.equal(calls.length, 1);
+  const [url, init] = calls[0];
+  assert.equal(new URL(url).origin, 'https://routes.example');
+  assert.equal(new URL(url).searchParams.get('coords'), '1.000000,2.000000;3.000000,4.000000');
+  assert.equal(new URL(url).searchParams.get('profile'), 'foot');
+  assert.equal(init.signal, controller.signal);
+  assert.equal(init.headers.Accept, 'application/json');
+});
+
+test('aborting during route parsing discards the result', async () => {
+  const controller = new AbortController();
+  const source = createDirectionsSource({ fetchImpl: async () => ({
+    ok: true, json: async () => { controller.abort(); return { ok: true }; },
+  }) });
+  await assert.rejects(source.getRoute(query, { signal: controller.signal }), { name: 'AbortError' });
+});
+
+test('route failures are surfaced without fallback requests', async () => {
+  for (const status of [429, 503]) {
+    let calls = 0;
+    const source = createDirectionsSource({ fetchImpl: async () => {
+      calls++;
+      return Response.json({}, { status });
+    } });
+    await assert.rejects(source.getRoute(query), status === 429 ? /rate limited/ : /HTTP 503/);
+    assert.equal(calls, 1);
+  }
+});

src/layers/earthquakes/index.js

@@ -11,6 +11,10 @@ import {
 export * from './model.js';
 export { createUsgsEarthquakeSource } from './source.js';
 
+// A portable package (no i18n): the error stays English data and the layer
+// panel shows it translated.
+const msg = (text) => text;
+
 /** Own one earthquake display and its refresh lifecycle. */
 export function createEarthquakesLayer({ source, overlayHost } = {}) {
   if (typeof source?.getSnapshot !== 'function')
@@ -154,7 +158,7 @@ export function createEarthquakesLayer({ source, overlayHost } = {}) {
         if (request.signal.aborted || _request !== request || !_enabled)
           return false;
         console.warn('[Data:Earthquakes] Fetch error:', e);
-        _lastError = e?.message || 'Earthquake source unavailable';
+        _lastError = e?.message || msg('Earthquake source unavailable');
         return false;
       } finally {
         if (_request === request) _request = null;

src/layers/earthquakes/records.test.mjs

@@ -0,0 +1,261 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { normalizeEarthquakeSnapshot } from './records.js';
+
+test('normalizeEarthquakeSnapshot parses valid GeoJSON earthquake features', () => {
+  const geojson = {
+    type: 'FeatureCollection',
+    features: [
+      {
+        id: 'us7000m123',
+        type: 'Feature',
+        geometry: {
+          type: 'Point',
+          coordinates: [-122.4194, 37.7749, 10.5],
+        },
+        properties: {
+          mag: 4.2,
+          place: 'San Francisco Bay Area, CA',
+          time: 1711929600000,
+        },
+      },
+    ],
+  };
+
+  const rows = normalizeEarthquakeSnapshot(geojson);
+  assert.equal(Array.isArray(rows), true);
+  assert.equal(rows.length, 1);
+  assert.deepEqual(rows[0], {
+    stableId: 'us7000m123',
+    usgsId: 'us7000m123',
+    lon: -122.4194,
+    lat: 37.7749,
+    depthKm: 10.5,
+    mag: 4.2,
+    place: 'San Francisco Bay Area, CA',
+    time: 1711929600000,
+  });
+});
+
+test('normalizeEarthquakeSnapshot generates index-based stable IDs when id is missing or blank', () => {
+  const geojson = {
+    features: [
+      {
+        id: null,
+        geometry: { type: 'Point', coordinates: [139.6917, 35.6895, 25.0] },
+        properties: { mag: 3.5, place: 'Tokyo, Japan', time: 1711930000000 },
+      },
+      {
+        id: '',
+        geometry: { type: 'Point', coordinates: [-70.6693, -33.4489, 45.2] },
+        properties: { mag: 5.1, place: 'Santiago, Chile', time: 1711931000000 },
+      },
+    ],
+  };
+
+  const rows = normalizeEarthquakeSnapshot(geojson);
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].stableId, 'event-1');
+  assert.equal(rows[0].usgsId, null);
+  assert.equal(rows[1].stableId, 'event-2');
+  assert.equal(rows[1].usgsId, '');
+});
+
+test('normalizeEarthquakeSnapshot filters events below M2.5 without dropping the feed', () => {
+  const geojson = {
+    features: [
+      {
+        id: 'ev-sub',
+        geometry: { type: 'Point', coordinates: [10, 20, 5] },
+        properties: { mag: 2.49, place: 'Minor tremor' },
+      },
+      {
+        id: 'ev-null-mag',
+        geometry: { type: 'Point', coordinates: [11, 21, 5] },
+        properties: { mag: null, place: 'Uncalculated' },
+      },
+      {
+        id: 'ev-threshold',
+        geometry: { type: 'Point', coordinates: [12, 22, 5] },
+        properties: { mag: 2.5, place: 'Threshold event' },
+      },
+      {
+        id: 'ev-strong',
+        geometry: { type: 'Point', coordinates: [13, 23, 5] },
+        properties: { mag: 6.8, place: 'Major event' },
+      },
+    ],
+  };
+
+  const rows = normalizeEarthquakeSnapshot(geojson);
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].stableId, 'ev-threshold');
+  assert.equal(rows[0].mag, 2.5);
+  assert.equal(rows[1].stableId, 'ev-strong');
+  assert.equal(rows[1].mag, 6.8);
+});
+
+test('normalizeEarthquakeSnapshot normalizes optional fields to null when omitted or invalid', () => {
+  const geojson = {
+    features: [
+      {
+        id: 'ev-sparse',
+        geometry: { coordinates: [-100, 40] }, // depth omitted
+        properties: { mag: 3.0, place: 12345, time: 'invalid' }, // place not string, time not number
+      },
+    ],
+  };
+
+  const rows = normalizeEarthquakeSnapshot(geojson);
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].depthKm, null);
+  assert.equal(rows[0].place, null);
+  assert.equal(rows[0].time, null);
+});
+
+test('normalizeEarthquakeSnapshot returns null for malformed structures or non-array features', () => {
+  assert.equal(normalizeEarthquakeSnapshot(null), null);
+  assert.equal(normalizeEarthquakeSnapshot(undefined), null);
+  assert.equal(normalizeEarthquakeSnapshot({}), null);
+  assert.equal(normalizeEarthquakeSnapshot({ features: 'not-an-array' }), null);
+  assert.equal(normalizeEarthquakeSnapshot({ features: null }), null);
+});
+
+test('normalizeEarthquakeSnapshot returns null for invalid geometries or out-of-range coordinates', () => {
+  const baseFeature = {
+    id: 'test',
+    geometry: { type: 'Point', coordinates: [0, 0, 0] },
+    properties: { mag: 3.0 },
+  };
+
+  // Non-Point geometry
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [
+        {
+          ...baseFeature,
+          geometry: {
+            type: 'LineString',
+            coordinates: [
+              [0, 0],
+              [1, 1],
+            ],
+          },
+        },
+      ],
+    }),
+    null,
+  );
+
+  // Missing or short coordinates
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [
+        { ...baseFeature, geometry: { type: 'Point', coordinates: [0] } },
+      ],
+    }),
+    null,
+  );
+
+  // Longitude out of range [-180, 180]
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [
+        {
+          ...baseFeature,
+          geometry: { type: 'Point', coordinates: [180.1, 0, 0] },
+        },
+      ],
+    }),
+    null,
+  );
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [
+        {
+          ...baseFeature,
+          geometry: { type: 'Point', coordinates: [-180.1, 0, 0] },
+        },
+      ],
+    }),
+    null,
+  );
+
+  // Latitude out of range [-90, 90]
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [
+        {
+          ...baseFeature,
+          geometry: { type: 'Point', coordinates: [0, 90.1, 0] },
+        },
+      ],
+    }),
+    null,
+  );
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [
+        {
+          ...baseFeature,
+          geometry: { type: 'Point', coordinates: [0, -90.1, 0] },
+        },
+      ],
+    }),
+    null,
+  );
+
+  // Non-finite depth
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [
+        {
+          ...baseFeature,
+          geometry: { type: 'Point', coordinates: [0, 0, NaN] },
+        },
+      ],
+    }),
+    null,
+  );
+
+  // Magnitude > 10
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [{ ...baseFeature, properties: { mag: 10.1 } }],
+    }),
+    null,
+  );
+
+  // Non-object or array properties
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [{ ...baseFeature, properties: 'invalid' }],
+    }),
+    null,
+  );
+  assert.equal(
+    normalizeEarthquakeSnapshot({
+      features: [{ ...baseFeature, properties: [] }],
+    }),
+    null,
+  );
+});
+
+test('normalizeEarthquakeSnapshot returns null when feed contains duplicate IDs', () => {
+  const geojson = {
+    features: [
+      {
+        id: 'duplicate-id',
+        geometry: { type: 'Point', coordinates: [0, 0, 0] },
+        properties: { mag: 3.0 },
+      },
+      {
+        id: 'duplicate-id',
+        geometry: { type: 'Point', coordinates: [1, 1, 1] },
+        properties: { mag: 4.0 },
+      },
+    ],
+  };
+
+  assert.equal(normalizeEarthquakeSnapshot(geojson), null);
+});

src/layers/feedDegradationI18n.test.mjs

@@ -0,0 +1,84 @@
+// The AIS degradation chip and the traffic "SIMULATED — <reason>" text read in
+// the UI language; English keeps its wording.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { setLocale, translateKnown } from '../i18n/index.js';
+import { deriveAisFeedError } from '../data/aisLiveVessels.js';
+import { createModel } from './traffic/model.js';
+
+test('AIS degraded-feed reasons are localized in es', () => {
+  setLocale('es');
+  try {
+    const cases = [
+      [
+        { status: 'down', reconnectAttempt: 3 },
+        'feed down — retrying slowly (attempt 3)',
+      ],
+      [{ status: 'missing-key' }, 'AISSTREAM_API_KEY not set'],
+      [
+        { status: 'stale', silentForMs: 90000 },
+        'feed silent 90s — no AIS data',
+      ],
+      [{ status: 'auth-failed' }, 'API key rejected — check AISSTREAM_API_KEY'],
+      [{ status: 'connecting' }, 'connecting to feed…'],
+      [{ status: 'closed' }, 'feed disconnected'],
+    ];
+    for (const [payload, english] of cases) {
+      // The layer panel runs stats.error through translateKnown(); emulate it.
+      const shown = translateKnown(deriveAisFeedError(payload, 0));
+      assert.notEqual(shown, english, `status ${payload.status} still English`);
+    }
+  } finally {
+    setLocale('en');
+  }
+});
+
+test('traffic "SIMULATED — <reason>" is localized in es', () => {
+  setLocale('es');
+  try {
+    const { trafficFeedPresentation } = createModel({
+      state: {},
+      services: {},
+      parts: {},
+      source: {},
+    });
+    const degraded = trafficFeedPresentation({
+      liveMode: true,
+      flowError: 'TomTom daily budget reached',
+    });
+    const shown = translateKnown(degraded.error);
+    assert.notEqual(shown, 'SIMULATED — TomTom daily budget reached');
+    assert.ok(!shown.startsWith('SIMULATED'), `still English: ${shown}`);
+  } finally {
+    setLocale('en');
+  }
+});
+
+test('English degraded-feed wording is unchanged', () => {
+  setLocale('en');
+  assert.equal(
+    deriveAisFeedError({ status: 'down', reconnectAttempt: 3 }, 0),
+    'feed down — retrying slowly (attempt 3)',
+  );
+  assert.equal(
+    deriveAisFeedError({ status: 'reconnecting' }, 0),
+    'reconnecting to feed…',
+  );
+  assert.equal(
+    deriveAisFeedError({ status: 'missing-key' }, 0),
+    'AISSTREAM_API_KEY not set',
+  );
+  const { trafficFeedPresentation } = createModel({
+    state: {},
+    services: {},
+    parts: {},
+    source: {},
+  });
+  assert.equal(
+    trafficFeedPresentation({
+      liveMode: true,
+      flowError: 'TomTom daily budget reached',
+    }).error,
+    'SIMULATED — TomTom daily budget reached',
+  );
+});

src/layers/firms/cards.js

@@ -1,4 +1,5 @@
 import * as Cesium from 'cesium';
+import { t } from '../../i18n/index.js';
 import {
   FIRMS_OVERLAY_SOURCE_ID,
   FIRMS_AMBIENT_COHORT_LIMIT,
@@ -115,7 +116,10 @@ export function createCards({
         if (!card.interactive) return card;
         return {
           ...card,
-          accessibilityLabel: `Focus fire detection ${card.title}, ${card.details.join(', ')}`,
+          accessibilityLabel: t('Focus fire detection {title}, {details}', {
+            title: card.title,
+            details: card.details.join(', '),
+          }),
           activate: () => {
             const fire = layerState._fireByCardId.get(card.id);
             if (!fire) return false;

src/layers/firms/ingestion.js

@@ -1,5 +1,6 @@
 import { adaptFirmsRecords } from '../../data/firmsAdapt.js';
 import { fireDetectionKey } from '../../data/firmsLabels.js';
+import { msg } from '../../i18n/index.js';
 
 export function createIngestion({
   layerState,
@@ -72,7 +73,8 @@ export function createIngestion({
       )
         return;
       console.warn(`[Data:${id}] FIRMS live load failed:`, error);
-      layerState._error = 'live feed unavailable';
+      // English data (stats reach the voice tools); the panel translates it.
+      layerState._error = msg('live feed unavailable');
     } finally {
       if (layerState.request === request) {
         layerState.request = null;

src/layers/firms/model.js

@@ -1,8 +1,10 @@
 import * as Cesium from 'cesium';
+import { formatNumber, t } from '../../i18n/index.js';
 import {
   satelliteShortName,
   fireDetectionKey,
   accentForSeverity,
+  formatFrpMw,
 } from '../../data/firmsLabels.js';
 import {
   VIEW_PADDING,
@@ -29,7 +31,8 @@ export function createModel({
    * context-store ids, so the two stay consistent).
    * @param {Object|null|undefined} fire - Internal fire record.
    * @returns {{id: string, lat: number|null, lon: number|null, frp: number|null,
-   *   confidence: number|null, satellite: string|null, acqTime: number|null}}
+   *   confidence: number|null, satellite: string|null, sensor: string|null,
+   *   acqTime: number|null}}
    */
 
   function mapAnalystRecord(fire) {
@@ -45,6 +48,7 @@ export function createModel({
       frp: num(fire?.frp),
       confidence: num(fire?.confidence), // normalized 0..1 (firmsAdapt.normalizeConfidence)
       satellite: text(fire?.satellite) || text(fire?.sensor),
+      sensor: text(fire?.sensor), // VIIRS or MODIS
       acqTime:
         Number.isFinite(fire?.acqMs) && fire.acqMs > 0 ? fire.acqMs : null, // epoch ms; 0 = unparseable → null
     };
@@ -327,14 +331,18 @@ export function createModel({
    */
 
   function buildSelectedFireCard(fire, nowMs) {
-    const meta = [`${confidenceBucket(fire.confidence)} conf`];
+    const meta = [
+      t('{value} conf', {
+        value: confidenceLabel(confidenceBucket(fire.confidence)),
+      }),
+    ];
     if (fire.acqMs > 0) {
-      const age = formatAge(nowMs - fire.acqMs);
-      if (age) meta.push(`${age} ago`);
+      const age = formatAgeLabel(nowMs - fire.acqMs);
+      if (age) meta.push(t('{value} ago', { value: age }));
     }
     const sat = satelliteShortName(fire.satellite);
     meta.push(
-      sat ? `${fire.sensor || 'VIIRS'} ${sat}` : fire.sensor || 'sensor n/a',
+      sat ? `${fire.sensor || 'VIIRS'} ${sat}` : fire.sensor || t('sensor n/a'),
     );
     return {
       id: `selected-fire:${fireDetectionKey(fire)}`,
@@ -344,10 +352,11 @@ export function createModel({
       cullPosition: fireCullPosition(fire),
       gapPx: frpPixelSize(fire.frp),
       accent: accentForSeverity(detectionColorStop(fire).name),
-      title: `FIRE · ${formatFrp(fire.frp)} MW`,
+      title: t('FIRE · {frp} MW', { frp: formatFrpLabel(fire.frp) }),
       details: [
         meta.join(' · '),
-        formatLatLon(fire.lat, fire.lon) + (fire.night ? ' · NIGHT' : ''),
+        formatLatLonLabel(fire.lat, fire.lon) +
+          (fire.night ? ` · ${t('NIGHT')}` : ''),
       ],
       selected: true,
       priority: Number.MAX_SAFE_INTEGER,
@@ -366,9 +375,9 @@ export function createModel({
 
   function buildFireCard(candidate, nowMs) {
     const fire = candidate.fire;
-    const meta = [confidenceBucket(fire.confidence)];
+    const meta = [confidenceLabel(confidenceBucket(fire.confidence))];
     if (fire.acqMs > 0) {
-      const age = formatAge(nowMs - fire.acqMs);
+      const age = formatAgeLabel(nowMs - fire.acqMs);
       if (age) meta.push(age);
     }
     const sat = satelliteShortName(fire.satellite) || fire.sensor;
@@ -380,7 +389,7 @@ export function createModel({
       cullPosition: candidate.cullPosition || candidate.position,
       gapPx: frpPixelSize(fire.frp),
       accent: accentForSeverity(detectionColorStop(fire).name),
-      title: `▲ ${formatFrp(fire.frp)} MW`,
+      title: t('▲ {frp} MW', { frp: formatFrpLabel(fire.frp) }),
       details: [meta.join(' · ')],
       selected: false,
       priority: Number(fire.frp) || 0,
@@ -398,11 +407,11 @@ export function createModel({
 
   function buildCellCard(candidate, nowMs) {
     const cell = candidate.cell;
-    const noun = cell.count === 1 ? 'FIRE' : 'FIRES';
-    const parts = [`max ${formatFrp(cell.maxFrp)} MW`];
+    const noun = cell.count === 1 ? t('FIRE') : t('FIRES');
+    const parts = [t('max {value} MW', { value: formatFrpLabel(cell.maxFrp) })];
     if (cell.newestAcqMs > 0) {
-      const age = formatAge(nowMs - cell.newestAcqMs);
-      if (age) parts.push(`new ${age}`);
+      const age = formatAgeLabel(nowMs - cell.newestAcqMs);
+      if (age) parts.push(t('new {value}', { value: age }));
     }
     return {
       id: `cell:${cell.latCell ?? 'x'}:${cell.lonCell ?? 'x'}`,
@@ -472,7 +481,39 @@ export function createModel({
   }
 
   function formatFrp(frp) {
-    return frp >= 10 ? frp.toFixed(0) : frp.toFixed(1);
+    return formatFrpMw(frp);
+  }
+
+  /** formatFrp for a card, with the locale's decimal separator ("4,9"). */
+
+  function formatFrpLabel(frp) {
+    const text = formatFrpMw(frp);
+    const digits = text.includes('.') ? 1 : 0;
+    return formatNumber(Number(text), {
+      minimumFractionDigits: digits,
+      maximumFractionDigits: digits,
+      useGrouping: false,
+    });
+  }
+
+  /** formatLatLon for a card: "8,389° ю. ш. 44,162° з. д." in Russian. */
+
+  function formatLatLonLabel(lat, lon) {
+    const amount = (value) =>
+      formatNumber(Math.abs(value), {
+        minimumFractionDigits: 3,
+        maximumFractionDigits: 3,
+        useGrouping: false,
+      });
+    const latPart =
+      lat >= 0
+        ? t('{value}°N', { value: amount(lat) })
+        : t('{value}°S', { value: amount(lat) });
+    const lonPart =
+      lon >= 0
+        ? t('{value}°E', { value: amount(lon) })
+        : t('{value}°W', { value: amount(lon) });
+    return `${latPart} ${lonPart}`;
   }
 
   /** Millisecond delta → "<1h" / "Xh" / "Xd", or '' for invalid input. */
@@ -488,11 +529,37 @@ export function createModel({
   /** Millisecond delta → "<1m ago" / "Xm ago" / "Xh ago" (fresh-feed readout). */
 
   function formatAgoMinutes(deltaMs) {
-    if (!Number.isFinite(deltaMs) || deltaMs < 0) return 'just now';
+    if (!Number.isFinite(deltaMs) || deltaMs < 0) return t('just now');
     const minutes = Math.floor(deltaMs / 60000);
-    if (minutes < 1) return '<1m ago';
-    if (minutes < 90) return `${minutes}m ago`;
-    return `${Math.round(minutes / 60)}h ago`;
+    if (minutes < 1) return t('<1m ago');
+    if (minutes < 90) return t('{count}m ago', { count: minutes });
+    return t('{count}h ago', { count: Math.round(minutes / 60) });
+  }
+
+  /** A confidence bucket as a card shows it, in the UI language. */
+
+  function confidenceLabel(bucket) {
+    switch (bucket) {
+      case 'high':
+        return t('high', { context: 'fire confidence' });
+      case 'nominal':
+        return t('nominal', { context: 'fire confidence' });
+      case 'low':
+        return t('low', { context: 'fire confidence' });
+      default:
+        return bucket;
+    }
+  }
+
+  /** formatAge for a card: "<1h", "24h", "3d" in the UI language ("24 ч"). */
+
+  function formatAgeLabel(deltaMs) {
+    if (!Number.isFinite(deltaMs) || deltaMs < 0) return '';
+    const hours = deltaMs / 3600000;
+    if (hours < 1) return t('<1h', { context: 'age' });
+    if (hours < 48)
+      return t('{count}h', { context: 'age', count: Math.round(hours) });
+    return t('{count}d', { context: 'age', count: Math.round(hours / 24) });
   }
 
   /** Normalized 0..1 confidence → low/nominal/high display bucket. */
@@ -526,6 +593,7 @@ export function createModel({
     formatLatLon,
     formatFrp,
     formatAge,
+    formatAgeLabel,
     formatAgoMinutes,
     confidenceBucket,
   };

src/layers/firms/queries.js

@@ -1,4 +1,5 @@
 import { fireDetectionKey } from '../../data/firmsLabels.js';
+import { t } from '../../i18n/index.js';
 import { REFRESH_INTERVAL_MS } from './policy.js';
 
 export function createQueries({
@@ -17,6 +18,7 @@ export function createQueries({
       if (!fire) return null;
       return {
         id: fireDetectionKey(fire),
+        // i18n-ignore: English entity label; the voice card translates it (shownEntityLabel)
         label: `Fire · FRP ${components.model.formatFrp(fire.frp)} MW`,
         latitude: fire.lat,
         longitude: fire.lon,
@@ -59,21 +61,27 @@ export function createQueries({
     getStats() {
       const now = Date.now();
       const staleText = layerState._lastUpdate
-        ? `STALE · cached ${components.model.formatAge(now - layerState._lastUpdate) || '<1h'}`
-        : 'STALE';
+        ? t('STALE · cached {age}', {
+            age:
+              components.model.formatAgeLabel(now - layerState._lastUpdate) ||
+              t('<1h', { context: 'age' }),
+          })
+        : t('STALE');
       let loadingLabel = '';
       if (layerState._loading) {
         loadingLabel = layerState._fires.length
-          ? 'refreshing...'
-          : 'loading...';
+          ? t('refreshing...')
+          : t('loading...');
       } else if (layerState._keyRequired) {
-        loadingLabel = 'KEY REQUIRED';
+        loadingLabel = t('KEY REQUIRED');
       } else if (layerState._stale) {
         loadingLabel = staleText;
       } else if (layerState._error) {
         loadingLabel = layerState._error;
       } else if (layerState._lastUpdate) {
-        loadingLabel = `LIVE · updated ${components.model.formatAgoMinutes(now - layerState._lastUpdate)}`;
+        loadingLabel = t('LIVE · updated {age}', {
+          age: components.model.formatAgoMinutes(now - layerState._lastUpdate),
+        });
       }
       return {
         count: layerState._count,
@@ -87,7 +95,7 @@ export function createQueries({
         // the operator can take.
         keyRequired: layerState._keyRequired,
         error: layerState._keyRequired
-          ? 'KEY REQUIRED'
+          ? t('KEY REQUIRED')
           : layerState._stale
             ? staleText
             : layerState._error,
@@ -109,6 +117,7 @@ export function createQueries({
         latitude: strongest.lat,
         longitude: strongest.lon,
         frp: strongest.frp,
+        // i18n-ignore: English entity label; the voice card translates it (shownEntityLabel)
         label: `Fire · FRP ${components.model.formatFrp(strongest.frp)} MW`,
       };
     },

src/layers/firms/selection.js

@@ -5,6 +5,7 @@ import {
 import * as Cesium from 'cesium';
 import { isPointerFree } from '../../data/inputOwnership.js';
 import { CONTEXT_TOP_N } from './policy.js';
+import { t } from '../../i18n/index.js';
 
 export function createSelection({
   layerState,
@@ -80,7 +81,7 @@ export function createSelection({
     requestWorldFocus({
       kind: 'fire',
       id: fireDetectionKey(fire),
-      label: 'FIRE',
+      label: t('FIRE'),
       position: components.model.firePosition(fire),
     });
   }
@@ -192,6 +193,7 @@ export function createSelection({
       layerName: name,
       source: 'NASA FIRMS',
       dataSource: layerState._dataSource,
+      // i18n-ignore: English entity label; the voice card translates it (shownEntityLabel)
       label: `Fire · FRP ${components.model.formatFrp(fire.frp)} MW`,
       latitude: fire.lat,
       longitude: fire.lon,

src/layers/flights/ingestion.js

@@ -1,5 +1,9 @@
 import { ERROR_BACKOFF_INTERVAL } from './recordPolicy.js';
 
+// Marks English the Layers panel translates when it shows the error. Kept
+// local: this module stays free of browser globals (package boundaries).
+const msg = (text) => text;
+
 /** Own acquisition, cancellation, freshness and backoff independently of rendering. */
 export function createIngestion({
   feed,
@@ -41,9 +45,10 @@ export function createIngestion({
         const sourceStale = snapshot.stale || snapshot.freshness === 'unknown';
         feed._backoff = sourceStale;
         feed._retryAt = 0;
+        // i18n-ignore: English data; the panel shows it through FEED_ERROR_PATTERNS (ui/statusText.js)
         feed._lastError = sourceStale
           ? sourceAgeMs == null
-            ? 'Source snapshot time unavailable'
+            ? msg('Source snapshot time unavailable')
             : `Source snapshot ${Math.max(2, Math.round(sourceAgeMs / 60_000))} min old`
           : null;
         feed._lastSource = snapshot.source;
@@ -77,7 +82,9 @@ export function createIngestion({
           setSourceLabel(feed._lastSource);
         }
         feed._lastError =
-          e?.name === 'LiveSourceError' ? e.message : 'Live data unavailable';
+          e?.name === 'LiveSourceError'
+            ? e.message
+            : msg('Live data unavailable');
       } finally {
         feed._activeUpdateControllers.delete(resourceController);
       }

src/layers/flights/motion.js

@@ -60,6 +60,10 @@ export function createMotion({
     publishFocusTargetFromCachedPosition,
   } = services.focus;
 
+  // Fixes leave the cache with their history; corrected positions invalidate
+  // the local frame even when the existing Cartesian is mutated in place.
+  const fixFrames = new WeakMap();
+
   // Round 5: the old `_warmGroundedAircraftSurfaceCache` (global exact-5-decimal
   // warm for every grounded contact on Earth) is GONE. Parked-aircraft GPS
   // jitter minted fresh keys every poll → thousands of upstream points per
@@ -124,7 +128,7 @@ export function createMotion({
    * @returns {Cesium.Cartesian3|null} Estimated ECEF position, or null if no history exists.
    */
 
-  function _deadReckon(icao24, result) {
+  function _deadReckon(icao24, result, sampledRenderTime) {
     const info = flightState.records.data.get(icao24);
     if (FOCUS_EVIDENCE_DEV && flightState._focusEvidenceIds.has(icao24)) {
       const position = flightState._billboards.get(icao24)?.position;
@@ -149,11 +153,13 @@ export function createMotion({
     const out = result || new Cesium.Cartesian3();
     // Render one poll interval behind real time so we interpolate between
     // two KNOWN fixes whenever possible (see RENDER_DELAY_SEC rationale).
-    const renderTime = Cesium.JulianDate.addSeconds(
-      Cesium.JulianDate.now(),
-      -RENDER_DELAY_SEC,
-      flightState._scratchRenderTime,
-    );
+    const renderTime =
+      sampledRenderTime ??
+      Cesium.JulianDate.addSeconds(
+        Cesium.JulianDate.now(flightState._scratchRenderTime),
+        -RENDER_DELAY_SEC,
+        flightState._scratchRenderTime,
+      );
 
     // Bracketing pair: interpolate — no extrapolation error, no snap-back.
     for (let i = history.length - 1; i >= 1; i--) {
@@ -286,12 +292,31 @@ export function createMotion({
       0,
       flightState._scratchOffset,
     );
-    const enu = Cesium.Transforms.eastNorthUpToFixedFrame(
-      fix.position,
-      Cesium.Ellipsoid.WGS84,
-      flightState._scratchEnu,
+    let frame = fixFrames.get(fix);
+    if (!frame) {
+      frame = {
+        position: new Cesium.Cartesian3(),
+        matrix: new Cesium.Matrix4(),
+      };
+      fixFrames.set(fix, frame);
+    }
+    if (
+      !frame.valid ||
+      !Cesium.Cartesian3.equals(frame.position, fix.position)
+    ) {
+      Cesium.Transforms.eastNorthUpToFixedFrame(
+        fix.position,
+        Cesium.Ellipsoid.WGS84,
+        frame.matrix,
+      );
+      Cesium.Cartesian3.clone(fix.position, frame.position);
+      frame.valid = true;
+    }
+    return Cesium.Matrix4.multiplyByPoint(
+      frame.matrix,
+      flightState._scratchOffset,
+      out,
     );
-    return Cesium.Matrix4.multiplyByPoint(enu, flightState._scratchOffset, out);
   }
 
   /**

src/layers/flights/motion.test.mjs

@@ -0,0 +1,184 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { createMotion } from './motion.js';
+import { arcOffsetEnu } from '../../data/motionModel.js';
+
+function fixture() {
+  const flightState = {
+    records: { data: new Map() },
+    _positionHistory: new Map(),
+    _focusEvidenceIds: new Set(),
+    _scratchArc: {},
+    _scratchOffset: new Cesium.Cartesian3(),
+    _scratchRenderTime: new Cesium.JulianDate(),
+  };
+  const motion = createMotion({
+    flightState,
+    services: { groundFloor: {}, camera: {}, focus: {} },
+    parts: {},
+  });
+  return { flightState, motion };
+}
+
+function expectedPosition(fix, dt, turnRate, transform) {
+  const arc = {};
+  arcOffsetEnu(fix.velocity, fix.track, turnRate, dt, arc);
+  return Cesium.Matrix4.multiplyByPoint(
+    transform(fix.position, Cesium.Ellipsoid.WGS84, new Cesium.Matrix4()),
+    new Cesium.Cartesian3(arc.east, arc.north, 0),
+    new Cesium.Cartesian3(),
+  );
+}
+
+function close(actual, expected) {
+  assert.ok(Cesium.Cartesian3.distance(actual, expected) < 1e-8);
+}
+
+test('extrapolation reuses fixed frames and invalidates corrected coordinates', (t) => {
+  const { motion } = fixture();
+  const transform = Cesium.Transforms.eastNorthUpToFixedFrame;
+  const spy = t.mock.method(
+    Cesium.Transforms,
+    'eastNorthUpToFixedFrame',
+    transform,
+  );
+  const fix = {
+    position: Cesium.Cartesian3.fromDegrees(-97, 30, 200),
+    velocity: 90,
+    track: 70,
+  };
+  const out = new Cesium.Cartesian3();
+  for (const dt of [-30, 5, 30, 60]) {
+    motion._extrapolateFix(fix, {}, dt, out, 1.5);
+    close(out, expectedPosition(fix, dt, 1.5, transform));
+  }
+  assert.equal(spy.mock.callCount(), 1);
+
+  // Ground reflooring mutates an existing fix's Cartesian in place.
+  Cesium.Cartesian3.fromDegrees(-97, 30, 350, undefined, fix.position);
+  motion._extrapolateFix(fix, {}, 30, out, 1.5);
+  close(out, expectedPosition(fix, 30, 1.5, transform));
+  assert.equal(spy.mock.callCount(), 2);
+
+  fix.position = Cesium.Cartesian3.fromDegrees(140, 80, 1000);
+  motion._extrapolateFix(fix, {}, 30, out, -2);
+  close(out, expectedPosition(fix, 30, -2, transform));
+  assert.equal(spy.mock.callCount(), 3);
+
+  fix.velocity = 210;
+  fix.track = 359;
+  motion._extrapolateFix(fix, {}, 15, out, -1);
+  close(out, expectedPosition(fix, 15, -1, transform));
+  assert.equal(spy.mock.callCount(), 3);
+
+  const replacement = { ...fix };
+  motion._extrapolateFix(replacement, {}, 15, out, -1);
+  close(out, expectedPosition(replacement, 15, -1, transform));
+  assert.equal(spy.mock.callCount(), 4);
+});
+
+test('stationary fixes do not build a frame until motion needs it', (t) => {
+  const { motion } = fixture();
+  const spy = t.mock.method(Cesium.Transforms, 'eastNorthUpToFixedFrame');
+  const fix = {
+    position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
+    velocity: 0,
+    track: 90,
+  };
+  const out = new Cesium.Cartesian3();
+  close(motion._extrapolateFix(fix, {}, 30, out), fix.position);
+  fix.velocity = 10;
+  close(motion._extrapolateFix(fix, {}, 0, out), fix.position);
+  assert.equal(spy.mock.callCount(), 0);
+  motion._extrapolateFix(fix, {}, 30, out);
+  assert.equal(spy.mock.callCount(), 1);
+});
+
+test('fleet render time is shared without resampling or mutating the supplied instant', (t) => {
+  const { flightState, motion } = fixture();
+  const start = Cesium.JulianDate.fromIso8601('2026-10-24T12:00:00Z');
+  const end = Cesium.JulianDate.addSeconds(start, 60, new Cesium.JulianDate());
+  const renderTime = Cesium.JulianDate.addSeconds(
+    start,
+    30,
+    new Cesium.JulianDate(),
+  );
+  const savedTime = Cesium.JulianDate.clone(renderTime);
+  const history = [
+    {
+      time: start,
+      position: Cesium.Cartesian3.fromDegrees(-97, 30, 1000),
+      track: 90,
+    },
+    {
+      time: end,
+      position: Cesium.Cartesian3.fromDegrees(-96.99, 30, 1000),
+      track: 90,
+    },
+  ];
+  for (const id of ['one', 'two']) {
+    flightState.records.data.set(id, { velocity: 100, true_track: 90 });
+    flightState._positionHistory.set(id, history);
+  }
+  t.mock.method(Cesium.JulianDate, 'now', () => {
+    throw new Error('unexpected per-contact clock read');
+  });
+  const expected = Cesium.Cartesian3.lerp(
+    history[0].position,
+    history[1].position,
+    0.5,
+    new Cesium.Cartesian3(),
+  );
+  for (const id of ['one', 'two'])
+    close(
+      motion._deadReckon(id, new Cesium.Cartesian3(), renderTime),
+      expected,
+    );
+  assert.ok(Cesium.JulianDate.equals(renderTime, savedTime));
+});
+
+test('tracked callers still sample a fresh delayed time without a fleet epoch', (t) => {
+  const { flightState, motion } = fixture();
+  const start = Cesium.JulianDate.fromIso8601('2026-10-24T12:00:00Z');
+  const history = [
+    {
+      time: start,
+      position: Cesium.Cartesian3.fromDegrees(-97, 30, 1000),
+      track: 90,
+    },
+    {
+      time: Cesium.JulianDate.addSeconds(start, 60, new Cesium.JulianDate()),
+      position: Cesium.Cartesian3.fromDegrees(-96.99, 30, 1000),
+      track: 90,
+    },
+  ];
+  flightState.records.data.set('tracked', { velocity: 100, true_track: 90 });
+  flightState._positionHistory.set('tracked', history);
+  let elapsed = 60;
+  const spy = t.mock.method(Cesium.JulianDate, 'now', (result) => {
+    assert.equal(result, flightState._scratchRenderTime);
+    return Cesium.JulianDate.addSeconds(start, elapsed, result);
+  });
+  const out = new Cesium.Cartesian3();
+  close(
+    motion._deadReckon('tracked', out),
+    Cesium.Cartesian3.lerp(
+      history[0].position,
+      history[1].position,
+      0.5,
+      new Cesium.Cartesian3(),
+    ),
+  );
+  elapsed = 75;
+  close(
+    motion._deadReckon('tracked', out),
+    Cesium.Cartesian3.lerp(
+      history[0].position,
+      history[1].position,
+      0.75,
+      new Cesium.Cartesian3(),
+    ),
+  );
+  assert.equal(spy.mock.callCount(), 2);
+});

src/layers/flights/policy.js

@@ -1,12 +1,5 @@
-export {
-  GROUND_FLOOR_CLAMP_RADIUS_KM,
-  GROUND_FLOOR_WARM_MAX_ALT_M,
-  POSITION_HISTORY_LIMIT,
-  LANDED_MISSING_POLL_LIMIT,
-  MISSING_POLL_LIMIT,
-  ERROR_BACKOFF_INTERVAL,
-} from './recordPolicy.js';
 import * as Cesium from 'cesium';
+import { EMERGENCY_TINT_CSS } from '../../data/aircraftEmergency.js';
 
 export const FOCUS_EVIDENCE_DEV = import.meta.env?.DEV === true;
 
@@ -14,6 +7,11 @@ export const FOCUS_EVIDENCE_DEV = import.meta.env?.DEV === true;
 
 export const MIL_TINT = Cesium.Color.fromCssColorString('#FFB800');
 
+/** Red tint for aircraft broadcasting an emergency (7500/7600/7700 or ADS-B status). */
+
+export const EMERGENCY_TINT =
+  Cesium.Color.fromCssColorString(EMERGENCY_TINT_CSS);
+
 // --- Ground traffic (owner reversal 2026-07-03: "absolutely we should see planes
 // taxiing and landing") -----------------------------------------------------------
 // Present-but-grounded planes are RENDERED instead of being skipped: same class
@@ -213,8 +211,8 @@ export const COURSE_SLEW_DT_MAX_SEC = 0.25;
 // adsbdb enrichment (best-effort, fail-silent). Bounded fan-out: max 4
 // concurrent requests, dispatches dripped ≥ENRICH_DISPATCH_GAP_MS apart
 // (≤5/s — adsbdb is a free community API; the dev-server proxy additionally
-// caches per-key on disk forever, negative results included, so repeat
-// sessions never re-hit adsbdb). Each key is requested at most once per
+// caches successful and 404 responses per key for 24 hours, so later sessions
+// may refresh them). Each key is requested at most once per
 // session. Priority jobs (tracked plane, model-eligible planes) jump the
 // queue; the ambient fleet sweep (below) fills the back at poll cadence.
 // ---------------------------------------------------------------------------
@@ -237,7 +235,7 @@ export const ENRICH_DISPATCH_GAP_MS = 200;
 //     of drip, so the backlog can't outgrow a poll and re-sorts fresh), and
 //   - a ROLLING token-bucket budget (below) bounding the sustained ambient
 //     request rate (repeat sessions resolve instantly from the proxy's
-//     permanent disk cache).
+//     24-hour disk cache).
 // Fail-silent by contract: the sweep never throws into the poll loop, never
 // blocks rendering, and never touches tracking state. When a type answer
 // lands, _requestTypeEnrichment's callback swaps the billboard glyph + scale
@@ -251,7 +249,7 @@ export const ENRICH_DISPATCH_GAP_MS = 200;
 // ENRICH_AMBIENT_REFILL_TOKENS every ENRICH_AMBIENT_REFILL_WINDOW_MS, clamped
 // at the ceiling (no banking beyond one bucket). Numbers: 150 / 5 min sustains
 // 0.5 req/s worst case — an order of magnitude under the 5/s drip that (with
-// the 4-concurrent limit + the proxy's permanent disk cache) is the REAL
+// the 4-concurrent limit + the proxy's 24-hour disk cache) is the REAL
 // politeness bound on adsbdb; the 300 ceiling preserves the old first-look
 // burst so a fresh region still classifies quickly.
 /** Bucket ceiling: max ambient tokens held at once (= the initial burst). */

src/layers/flights/queries.js

@@ -15,6 +15,7 @@ import {
   FOCUS_EVIDENCE_DEV,
   FLEET_DR_INTERVAL_MS,
 } from './policy.js';
+import { emergencyBroadcastPhrase } from '../../data/aircraftEmergency.js';
 
 export function createQueries({
   flightState,
@@ -113,7 +114,7 @@ export function createQueries({
    * Build a public descriptor for one aircraft using its best current position
    * (dead-reckoned when history exists, billboard position otherwise).
    * @param {string} icao24 - ICAO 24-bit transponder address.
-   * @returns {{icao24: string, callsign: string|null, position: Cesium.Cartesian3, latitude: number, longitude: number, altitudeM: number, velocityMps: number|null, track: number|null}|null}
+   * @returns {{icao24: string, callsign: string|null, position: Cesium.Cartesian3, latitude: number, longitude: number, altitudeM: number, velocityMps: number|null, track: number|null, verticalRateMps: number|null}|null}
    *   Descriptor with a cloned position, or null if the aircraft is unknown.
    */
 
@@ -163,10 +164,23 @@ export function createQueries({
       onGround: info?.onGround === true,
       velocityMps: displayed.speedMps,
       track: displayed.trackDeg,
+      // Climb/descent rate, the one kinematic field `mapAnalystRecord` already
+      // published (as `verticalRateMps`) but this descriptor did not, so a
+      // consumer reading the tracked seam had to reach back into `_flightData`
+      // for it. Reported, never derived: `stickyNumber` in records.js keeps the
+      // last value across a blank poll, and an absent rate stays null rather
+      // than becoming a level-flight 0 the aircraft never transmitted.
+      verticalRateMps: Number.isFinite(info?.verticalRate)
+        ? info.verticalRate
+        : null,
       stale: Boolean(
         flightState.records.missingPolls.get(icao24) ||
         flightState.feed._backoff,
       ),
+      // This poll's transponder broadcast (not sticky; see records.js).
+      squawk: info?.squawk ?? null,
+      emergency: info?.emergency ? { ...info.emergency } : null,
+      emergencyBroadcast: emergencyBroadcastPhrase(info?.emergency),
       airline: info?.airline ?? null,
       // CLASS label follows the TR-3B conversion so every downstream card
       // (cockpit, Contacts, analyst) agrees with the triangle on screen.
@@ -219,7 +233,10 @@ export function createQueries({
    *   lon: number|null, altitudeM: number|null, speedMps: number|null,
    *   heading: number|null, verticalRateMps: number|null, onGround: boolean,
    *   military: boolean, aircraftClass: string|null, originCountry: string|null,
-   *   operator: string|null, routeOrigin: string|null, routeDestination: string|null}}
+   *   operator: string|null, squawk: string|null, emergency: boolean,
+   *   emergencyKind: string|null, emergencySource: 'squawk'|'ads-b'|null,
+   *   emergencyBroadcast: string|null, lastContactAtMs: number|null, routeOrigin: string|null,
+   *   routeDestination: string|null}}
    */
 
   function mapAnalystRecord(
@@ -253,6 +270,20 @@ export function createQueries({
       aircraftClass: tr3bAircraftClass(icao24, text(info?.klass)),
       originCountry: text(info?.originCountry),
       operator: text(info?.airline),
+      squawk: text(info?.squawk),
+      // True while this poll broadcast an emergency (7500/7600/7700 or the
+      // ADS-B status); priority statuses (lifeguard, minfuel) report the kind
+      // without the flag.
+      emergency: info?.emergency?.severity === 'emergency',
+      emergencyKind: text(info?.emergency?.kind),
+      // Provenance, so a summary can say "broadcasting squawk 7700" rather
+      // than "ADS-B reports general emergency" (or flatten both): 'squawk'
+      // when the Mode A code names the status, 'ads-b' for the readsb field.
+      emergencySource: text(info?.emergency?.source),
+      emergencyBroadcast: emergencyBroadcastPhrase(info?.emergency),
+      // Latest known general aircraft-message contact, retained if a poll
+      // has no time. This is not the receipt time of the current status.
+      lastContactAtMs: num(info?.lastContactEpochMs),
       routeOrigin: routeOk ? text(info?.route?.origin?.code) : null,
       routeDestination: routeOk ? text(info?.route?.destination?.code) : null,
     };
@@ -421,8 +452,8 @@ export function createQueries({
         const isTracked = icao24 === flightState._trackedIcao;
         // Keep planes rendered as a 3D model (billboard hidden) so the detection box
         // doesn't vanish on the 2D→3D handoff; bb.position stays current while hidden.
-        const model = flightState._models.get(icao24);
-        const modelOwnsVisual = parts.rendering._modelOwnsVisual(icao24);
+        const model = flightState._models.get(icao24) ?? null;
+        const modelOwnsVisual = parts.rendering._modelOwnsVisual(icao24, model);
         if (!isTracked && !bb.show && !modelOwnsVisual) continue;
         const info = flightState.records.data.get(icao24);
         let object = flightState._detectionObjects.get(icao24);
@@ -460,8 +491,19 @@ export function createQueries({
         object.position = pos;
         object.skipLabel = isTracked;
         // Card text only — declutter/cohort identity is `object.sourceId` (icao24).
-        const id = _contactLabel(icao24, info);
-        if (object.id !== id) object.id = id;
+        const callsign = info?.callsign;
+        const registration = info?.registration;
+        // Records and enrichment may change in place. Cache by field values,
+        // while keeping the live visual anchor above independent of text.
+        if (
+          object.id === undefined ||
+          object._labelCallsign !== callsign ||
+          object._labelRegistration !== registration
+        ) {
+          object.id = _contactLabel(icao24, info);
+          object._labelCallsign = callsign;
+          object._labelRegistration = registration;
+        }
         const altitude = info?.altitude;
         if (object._altitude !== altitude) {
           object._altitude = altitude;
@@ -549,7 +591,6 @@ export function createQueries({
       const maxRange =
         Number.isFinite(range) && range > 0 ? range : Number.POSITIVE_INFINITY;
 
-      const now = Cesium.JulianDate.now();
       const nearby = [];
 
       for (const [icao24, bb] of flightState._billboards) {
@@ -834,7 +875,7 @@ export function createQueries({
 
     /**
      * Describe the currently tracked aircraft at its dead-reckoned position.
-     * @returns {{icao24: string, callsign: string|null, latitude: number, longitude: number, altitudeM: number, velocityMps: number|null, track: number|null}|null}
+     * @returns {{icao24: string, callsign: string|null, latitude: number, longitude: number, altitudeM: number, velocityMps: number|null, track: number|null, verticalRateMps: number|null}|null}
      *   Tracked aircraft info, or null when nothing is tracked.
      */
     getTrackedInfo() {

src/layers/flights/queries.test.mjs

@@ -0,0 +1,149 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { createQueries } from './queries.js';
+import { createRendering } from './rendering.js';
+
+function fixture() {
+  const info = {
+    callsign: ' TEST123 ',
+    registration: ' N123 ',
+    altitude: 1000,
+  };
+  const bb = { show: true, position: new Cesium.Cartesian3(1, 2, 3) };
+  const flightState = {
+    feed: {},
+    _billboardCollection: { show: true },
+    _billboards: new Map([['abc123', bb]]),
+    _models: new Map(),
+    _detectionObjects: new Map(),
+    records: { data: new Map([['abc123', info]]) },
+  };
+  let formats = 0;
+  const services = {
+    aircraftPresentation: {},
+    militaryRegistry: {},
+    camera: {},
+    focus: {},
+    recession: {},
+    labels: {
+      formatFlightLevel: (altitude) => {
+        formats++;
+        return String(altitude);
+      },
+    },
+  };
+  const parts = {
+    testing: {},
+    tracking: { _trackedModelRegimeActive: () => true },
+    motion: { _trackedVisualCached: () => null },
+  };
+  parts.rendering = createRendering({ flightState, services, parts });
+  const queries = createQueries({ flightState, services, parts }).methods;
+  return { flightState, info, bb, parts, queries, formats: () => formats };
+}
+
+test('candidate text follows in-place enrichment without freezing identity or positions', () => {
+  const f = fixture();
+  const [first] = f.queries.getDetectableObjects();
+  assert.equal(first.id, 'TEST123');
+  assert.equal(first.sourceId, 'abc123');
+  f.bb.position = new Cesium.Cartesian3(4, 5, 6);
+  assert.equal(f.queries.getDetectableObjects()[0], first);
+  assert.equal(first.position, f.bb.position);
+  assert.equal(f.formats(), 1);
+  f.info.callsign = ' NEW456 ';
+  assert.equal(f.queries.getDetectableObjects()[0].id, 'NEW456');
+  f.info.callsign = '   ';
+  assert.equal(f.queries.getDetectableObjects()[0].id, 'N123');
+  f.info.registration = ' N456 ';
+  f.info.altitude = 2000;
+  assert.equal(f.queries.getDetectableObjects()[0].id, 'N456');
+  assert.equal(first.metric, '2000');
+  assert.equal(f.formats(), 2);
+  f.flightState.records.data.set('abc123', { ...f.info });
+  assert.equal(f.queries.getDetectableObjects()[0], first);
+  f.flightState.records.data.delete('abc123');
+  assert.equal(f.queries.getDetectableObjects()[0].id, 'abc123');
+  assert.equal(first.sourceId, 'abc123');
+});
+
+test('unchanged candidate text is normalized once across paints', (t) => {
+  const f = fixture();
+  const trim = String.prototype.trim;
+  let calls = 0;
+  t.mock.method(String.prototype, 'trim', function () {
+    if (String(this) === ' TEST123 ') calls++;
+    return trim.call(this);
+  });
+  for (let i = 0; i < 20; i++) f.queries.getDetectableObjects();
+  assert.equal(calls, 1);
+});
+
+test('candidate collection resolves models once and keeps handoffs live', (t) => {
+  const f = fixture();
+  const get = t.mock.method(f.flightState._models, 'get');
+  const [candidate] = f.queries.getDetectableObjects();
+  assert.equal(get.mock.callCount(), 1);
+  const model = {
+    ready: false,
+    show: true,
+    modelMatrix: Cesium.Matrix4.fromTranslation(
+      new Cesium.Cartesian3(10, 20, 30),
+    ),
+  };
+  f.parts.rendering._modelSpec = () => ({
+    visualCenterNative: Cesium.Cartesian3.ZERO,
+    scale: 1,
+  });
+  f.flightState._models.set('abc123', model);
+  f.bb.show = false;
+  assert.deepEqual(f.queries.getDetectableObjects(), []);
+  model.ready = true;
+  assert.equal(f.queries.getDetectableObjects()[0], candidate);
+  assert.deepEqual(candidate.position, new Cesium.Cartesian3(10, 20, 30));
+  Cesium.Matrix4.setTranslation(
+    model.modelMatrix,
+    new Cesium.Cartesian3(40, 50, 60),
+    model.modelMatrix,
+  );
+  f.queries.getDetectableObjects();
+  assert.deepEqual(candidate.position, new Cesium.Cartesian3(40, 50, 60));
+  model.show = false;
+  assert.deepEqual(f.queries.getDetectableObjects(), []);
+  f.bb.show = true;
+  assert.equal(f.queries.getDetectableObjects()[0].position, f.bb.position);
+  assert.equal(get.mock.callCount(), 6);
+  model.show = true;
+  assert.equal(f.parts.rendering._modelOwnsVisual('abc123'), true);
+  assert.equal(get.mock.callCount(), 7);
+});
+
+test('tracked ownership and live anchors remain independent of fleet models', () => {
+  const f = fixture();
+  f.flightState._trackedIcao = 'abc123';
+  f.flightState._trackedModel = { ready: true, show: true };
+  f.parts.rendering._modelSpec = () => ({});
+  let anchor = new Cesium.Cartesian3(10, 20, 30);
+  f.parts.motion._trackedVisualCached = () => anchor;
+  const [candidate] = f.queries.getDetectableObjects();
+  assert.equal(candidate.position, anchor);
+  assert.equal(candidate.skipLabel, true);
+  assert.equal(f.parts.rendering._modelOwnsVisual('abc123', null), true);
+  anchor = new Cesium.Cartesian3(40, 50, 60);
+  assert.equal(f.queries.getDetectableObjects()[0].position, anchor);
+  for (const tracked of [
+    null,
+    { ready: false, show: true },
+    { ready: true, show: false },
+  ]) {
+    f.flightState._trackedModel = tracked;
+    assert.equal(
+      f.parts.rendering._modelOwnsVisual('abc123', { ready: true, show: true }),
+      false,
+    );
+  }
+  f.flightState._trackedModel = { ready: true, show: true };
+  f.parts.tracking._trackedModelRegimeActive = () => false;
+  assert.equal(f.parts.rendering._modelOwnsVisual('abc123', null), false);
+});

src/layers/flights/recordPolicy.js

@@ -13,9 +13,4 @@ export const MISSING_POLL_LIMIT = 3;
 export const ERROR_BACKOFF_INTERVAL = 20000;
 
 /** Local equirectangular distance used for viewer-proximate floor sampling. */
-export function approxDistanceKm(lat1, lon1, lat2, lon2) {
-  const dLat = (lat2 - lat1) * 111.32;
-  const dLon =
-    (lon2 - lon1) * 111.32 * Math.cos((((lat1 + lat2) / 2) * Math.PI) / 180);
-  return Math.hypot(dLat, dLon);
-}
+export { approxDistanceKm } from '../../data/approxDistance.js';

src/layers/flights/recordPolicy.test.mjs

@@ -0,0 +1,18 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  approxDistanceKm,
+  GROUND_FLOOR_CLAMP_RADIUS_KM,
+} from './recordPolicy.js';
+
+test('approximate distance takes the short way across the antimeridian', () => {
+  // 0.2° of longitude at Taveuni, Fiji (16.8° S) is about 21 km.
+  for (const [lon1, lon2] of [
+    [179.9, -179.9],
+    [-179.9, 179.9],
+  ]) {
+    const km = approxDistanceKm(-16.8, lon1, -16.8, lon2);
+    assert.ok(Math.abs(km - 21.31) < 0.01, `${lon1} → ${lon2}: ${km} km`);
+    assert.ok(km <= GROUND_FLOOR_CLAMP_RADIUS_KM);
+  }
+});

src/layers/flights/records.js

@@ -4,6 +4,7 @@ import {
   pickRenderAltitudeM,
 } from '../../data/renderAltitude.js';
 import { classifyAircraft } from '../../data/aircraftClass.js';
+import { aircraftEmergency } from '../../data/aircraftEmergency.js';
 import {
   approxDistanceKm,
   GROUND_FLOOR_CLAMP_RADIUS_KM,
@@ -226,6 +227,22 @@ export class FlightRecords {
       // like callsign so a transient blank row doesn't blank the field.
       originCountry:
         stickyText(origin_country, prevMeta?.originCountry) || null,
+      // Per poll, NOT sticky: an emergency code clears when the crew resets
+      // it, so a blank squawk must not hold a stale 7700 on screen.
+      squawk: observation.squawk ?? null,
+      // One source-switch omission may retain an ADS-B status, while an
+      // explicit clear or changed squawk always takes effect immediately.
+      emergency:
+        observation.emergency === undefined &&
+        observation.squawk === prevMeta?.squawk &&
+        prevMeta?.emergency?.source === 'ads-b' &&
+        (prevMeta?.missingEmergencyPolls ?? 0) < 1
+          ? prevMeta.emergency
+          : aircraftEmergency(observation),
+      missingEmergencyPolls:
+        observation.emergency === undefined
+          ? (prevMeta?.missingEmergencyPolls ?? 0) + 1
+          : 0,
       // OpenSky distinguishes the last position epoch from the last
       // transponder message. The fleet coast horizon uses this actual
       // contact time so a temporarily old position does not hard-freeze
@@ -258,10 +275,12 @@ export class FlightRecords {
     return { icao24, prevMeta, meta, groundFlipped, fixEpochMs };
   }
 
-  absence(id, { complete, likelyLanded }) {
-    // Partial admissions do not prove absence, but retention remains bounded.
+  absence(id, { complete, retainIds, likelyLanded }) {
+    // Partial admissions and position-less rows do not prove absence, but
+    // retention remains bounded; a likely-landed position-less contact
+    // still takes the landed limit.
     if (
-      !complete &&
+      (!complete || (retainIds?.has(id) && !likelyLanded)) &&
       Date.now() - (this.data.get(id)?.observedReceiptMs ?? 0) < 300000
     )
       return 'retain';

src/layers/flights/records.test.mjs

@@ -106,3 +106,37 @@ test('ground transitions preserve last render height while a surface cell is col
   assert.equal(next.meta.renderAltitudeM, 1040);
   assert.equal(next.meta.wasAirborne, true);
 });
+
+test('complete snapshots age out vanished aircraft and retain position-less ones unless landed', () => {
+  const store = records();
+  for (const id of ['abc123', 'def456', 'ghi789'])
+    store.receive(observation({ id, reference: id }), view());
+  // abc123 and ghi789 are still listed without a position; def456 vanished.
+  const absent = (id, likelyLanded = false) =>
+    store.absence(id, {
+      complete: true,
+      retainIds: new Set(['abc123', 'ghi789']),
+      likelyLanded,
+    });
+  assert.deepEqual(
+    [absent('def456'), absent('def456'), absent('def456')],
+    ['stale', 'stale', 'remove'],
+  );
+  assert.equal(absent('abc123'), 'retain');
+  assert.equal(store.missingPolls.has('abc123'), false);
+  // A landed contact that lost its position takes the landed fast-cull.
+  assert.equal(absent('ghi789', true), 'remove');
+  // Position-less retention stays bounded like partial admission.
+  store.data.get('abc123').observedReceiptMs = Date.now() - 300001;
+  assert.equal(absent('abc123'), 'stale');
+});
+
+test('civil emergency status follows the latest poll instead of sticking', () => {
+  const store = records();
+  const first = store.receive(observation({ squawk: '7700' }), view());
+  assert.equal(first.meta.squawk, '7700');
+  assert.equal(first.meta.emergency.kind, 'general');
+  const next = store.receive(observation({ squawk: '2000' }), view());
+  assert.equal(next.meta.squawk, '2000');
+  assert.equal(next.meta.emergency, null);
+});

src/layers/flights/rendering.js

@@ -3,6 +3,7 @@ import { cyberSonarBaseAlpha } from '../../cyberSonar.js';
 import { selectModelEligible } from '../../data/modelEligibility.js';
 import { civilAircraftModelSpec } from './modelSpec.js';
 import { CLASS_SCALE_2D } from '../../data/aircraftClass.js';
+import { isEmergency } from '../../data/aircraftEmergency.js';
 import { cockpitContactDotImage } from '../../data/cockpitContactDot.js';
 import { aircraftIcon, TRACKED_ICON_PX } from '../../data/aircraftIcons.js';
 import {
@@ -13,6 +14,7 @@ import {
 import { limitCourseStep, courseSlewCapDps } from '../../data/motionModel.js';
 import {
   MIL_TINT,
+  EMERGENCY_TINT,
   GROUND_SCALE,
   COCKPIT_CONTACT_SIZE_PX,
   COCKPIT_CIVILIAN_COLOR,
@@ -30,10 +32,12 @@ import {
   TRACKED_MODEL_MIN_PX,
   TRACKED_MODEL_MAX_PX,
   FLEET_DR_INTERVAL_MS,
+  RENDER_DELAY_SEC,
   COURSE_SLEW_DT_MAX_SEC,
   ROTATION_REFRESH_MS,
   COURSE_MAX_DPS,
 } from './policy.js';
+import { AIRCRAFT_ENVIRONMENT_MAP_OPTIONS } from '../../data/aircraftModelLighting.js';
 
 export function createRendering({
   flightState,
@@ -54,13 +58,34 @@ export function createRendering({
   const { applyAircraftBillboardTreatment, applyAircraftModelTreatment } =
     services.recession;
 
-  /** Fleet (untracked) billboard tint: amber for known-military, white otherwise.
+  /** True while this contact's latest poll broadcast an emergency code. */
+
+  function _isEmergency(icao24, info = flightState.records.data.get(icao24)) {
+    return isEmergency(info?.emergency);
+  }
+
+  /** Fleet (untracked) billboard tint: red while broadcasting an emergency,
+   *  amber for known-military, white otherwise.
    *  Ground traffic gets NO special tint (owner verdict 2026-07-03 field test). */
 
-  function _fleetBillboardColor(icao24) {
+  function _fleetBillboardColor(
+    icao24,
+    info = flightState.records.data.get(icao24),
+  ) {
+    if (_isEmergency(icao24, info)) return EMERGENCY_TINT;
     return isMilitaryIcao(icao24) ? MIL_TINT : Cesium.Color.WHITE;
   }
 
+  /** Cockpit far-contact dot tint: the emergency red outranks the category tint. */
+
+  function _cockpitContactColor(
+    icao24,
+    info = flightState.records.data.get(icao24),
+  ) {
+    if (_isEmergency(icao24, info)) return EMERGENCY_TINT;
+    return isMilitaryIcao(icao24) ? MIL_TINT : COCKPIT_CIVILIAN_COLOR;
+  }
+
   /** Fleet billboard scale: per-class scale, ×GROUND_SCALE while grounded. */
 
   function _fleetBillboardScale(icao24, klass) {
@@ -129,9 +154,7 @@ export function createRendering({
       bb.height = COCKPIT_CONTACT_SIZE_PX;
       bb.scale = limbScale;
       bb.scaleByDistance = _cockpitBillboardScaleByDistance();
-      bb.color = (
-        isMilitaryIcao(icao24) ? MIL_TINT : COCKPIT_CIVILIAN_COLOR
-      ).withAlpha(freshnessAlpha);
+      bb.color = _cockpitContactColor(icao24).withAlpha(freshnessAlpha);
       bb.rotation = 0;
       return;
     }
@@ -162,7 +185,7 @@ export function createRendering({
 
   function _modelColor(icao24) {
     if (icao24 === flightState._trackedIcao) return Cesium.Color.CYAN;
-    return isMilitaryIcao(icao24) ? MIL_TINT : Cesium.Color.WHITE;
+    return _fleetBillboardColor(icao24);
   }
 
   /** The FLEET's 3D-model regime: models3d enabled AND the camera zoomed in past the altitude
@@ -361,17 +384,20 @@ export function createRendering({
    *    null or still-loading tracked model from claiming a visual it is not
    *    drawing yet.
    * @param {string} icao24
+   * @param {Cesium.Model|null} [model] Resolved fleet model; null means absent.
    * @returns {boolean}
    */
 
-  function _modelOwnsVisual(icao24) {
+  function _modelOwnsVisual(icao24, model) {
     if (icao24 === flightState._trackedIcao) {
       return (
         parts.tracking._trackedModelRegimeActive() &&
         _modelIsRendering(flightState._trackedModel)
       );
     }
-    return _modelIsRendering(flightState._models.get(icao24));
+    return _modelIsRendering(
+      model === undefined ? flightState._models.get(icao24) : model,
+    );
   }
 
   /** A model is the visual only once it actually draws — loaded AND shown.
@@ -482,6 +508,7 @@ export function createRendering({
       model = await Cesium.Model.fromGltfAsync({
         url: resolveAsset(spec.url),
         asynchronous: false,
+        environmentMapOptions: AIRCRAFT_ENVIRONMENT_MAP_OPTIONS,
         minimumPixelSize: MODEL_MIN_PX,
         scale: spec.scale,
         color: flightState._irBoost ? Cesium.Color.WHITE : _modelColor(icao24),
@@ -688,6 +715,7 @@ export function createRendering({
       Cesium.Model.fromGltfAsync({
         url: resolveAsset(trackedSpec.url),
         asynchronous: false,
+        environmentMapOptions: AIRCRAFT_ENVIRONMENT_MAP_OPTIONS,
         minimumPixelSize: TRACKED_MODEL_MIN_PX,
         scale: trackedSpec.scale,
         color: flightState._irBoost ? Cesium.Color.WHITE : Cesium.Color.CYAN,
@@ -833,6 +861,12 @@ export function createRendering({
         )
       : 0.08;
     flightState._lastFleetTickMs = nowMs;
+    // Every contact in this pass shares the same delayed display instant.
+    const renderTime = Cesium.JulianDate.addSeconds(
+      Cesium.JulianDate.now(flightState._scratchFleetRenderTime),
+      -RENDER_DELAY_SEC,
+      flightState._scratchFleetRenderTime,
+    );
 
     _drainIrReloadQueue(); // bounded per-tick slice of any pending boost-flip reload
     if (flightState._cockpitContactMode)
@@ -936,7 +970,11 @@ export function createRendering({
 
       const info = flightState.records.data.get(icao24);
 
-      const dr = parts.motion._deadReckon(icao24, flightState._scratchFleetPos);
+      const dr = parts.motion._deadReckon(
+        icao24,
+        flightState._scratchFleetPos,
+        renderTime,
+      );
       // The dead-reckoned point drifts away from the fix whose cell supplied the
       // height, so a grounded contact's sprite ends up under the mesh it taxied
       // (or coasted) over. Re-floor at the DISPLAYED coordinate — read-only, and
@@ -1009,10 +1047,8 @@ export function createRendering({
         flightState._cockpitNearContacts.has(icao24);
       const layerBaseColor =
         flightState._cockpitContactMode && !isCockpitNear
-          ? isMilitaryIcao(icao24)
-            ? MIL_TINT
-            : COCKPIT_CIVILIAN_COLOR
-          : _fleetBillboardColor(icao24);
+          ? _cockpitContactColor(icao24, info)
+          : _fleetBillboardColor(icao24, info);
       const baseColor = layerBaseColor;
       const treatment = applyAircraftBillboardTreatment({
         billboard: bb,

src/layers/flights/snapshotRenderer.js

@@ -179,8 +179,24 @@ export function createFlightSnapshotRenderer({
         // as the enrichment path — the class's GLB/scale may have changed.
         if (prevMeta?.klass !== meta.klass) rendering._syncModelToClass(icao24);
       } else {
+        // Start where the fleet pass will draw it: the fleet renders behind
+        // real time, so a fresh contact's displayed position is its fix
+        // projected back to that delayed time, and a grounded contact is then
+        // lifted onto the floor under that delayed position. Creating it at
+        // the raw fix drew it ahead until the next fleet tick snapped it back;
+        // skipping the floor started a taxiing contact low and then raised it.
+        const delayed = motion._deadReckon(icao24, new Cesium.Cartesian3());
+        const displayed =
+          (delayed &&
+            motion._floorGroundedDisplayPosition(
+              icao24,
+              flightState.records.data.get(icao24) || meta,
+              delayed,
+              rendering._modelOwnsVisual(icao24),
+            )) ||
+          position;
         const bb = flightState._billboardCollection.add({
-          position,
+          position: displayed,
           image: aircraftIcon(rendering._iconKind(icao24, meta.klass)),
           width: isTracked ? 24 : 20,
           height: isTracked ? 24 : 20,
@@ -227,6 +243,7 @@ export function createFlightSnapshotRenderer({
       if (currentIcaos.has(icao24)) continue;
       const absence = records.absence(icao24, {
         complete: snapshot.complete,
+        retainIds: snapshot.retainIds,
         likelyLanded: queries._likelyLanded(icao24),
       });
       if (absence === 'retain') continue;

src/layers/flights/state.js

@@ -242,12 +242,12 @@ export function createFlightState({ source, services }) {
 
   flightState._scratchCarto = new Cesium.Cartographic();
 
-  flightState._scratchEnu = new Cesium.Matrix4();
-
   flightState._scratchArc = { east: 0, north: 0, endCourseDeg: 0 };
 
   flightState._scratchRenderTime = new Cesium.JulianDate();
 
+  flightState._scratchFleetRenderTime = new Cesium.JulianDate();
+
   flightState._scratchFleetPos = new Cesium.Cartesian3();
 
   flightState._scratchSonarScreen = new Cesium.Cartesian2();

src/layers/flights/tracking.js

@@ -1,4 +1,6 @@
 import * as Cesium from 'cesium';
+import { formatNumber, t } from '../../i18n/index.js';
+import { unitLabel } from '../../ui/unitLabels.js';
 import { nextCockpitNearContacts } from '../../data/cockpitAirLod.js';
 import { trackedModelZoomActive } from '../../data/trackedModelRegime.js';
 import {
@@ -45,7 +47,7 @@ export function createTracking({
   const { isMilitaryLayerActive, isMilitaryIcao } = services.militaryRegistry;
   const { trackedLabelModelFromText, refreshTrackedReadout } = services.readout;
   const { applyTrackedCameraFrame } = services.camera;
-  const { resolvePickId, isOwnedByOtherLayer } = services.picking;
+  const { resolvePickId, isOwnedByOtherLayer, pickContact } = services.picking;
   const flightsLayer = layer;
 
   function _emitAwarenessEvent(type, detail) {
@@ -130,6 +132,7 @@ export function createTracking({
         icao24,
         // Honesty cue: the contact is coasting on dead reckoning, so the
         // narrated position/velocity are last-known rather than live.
+        // i18n-ignore: voice-context data, English for the model
         status: described.stale ? 'stale (missed polls)' : 'live',
       },
     };
@@ -751,11 +754,18 @@ export function createTracking({
     // the tail number rather than raw hex.
     const cs = parts.queries._contactLabel(icao24, info);
     const altFt = Math.round((info.altitude || 0) * 3.28084);
-    const fl = altFt >= 18000 ? `FL${Math.round(altFt / 100)}` : `${altFt} ft`;
-    const spd = info.velocity ? `${Math.round(info.velocity * 1.944)} kts` : '';
+    // Flight levels are an aviation code; feet and knots read in the active
+    // language ("0 фт · 1 уз").
+    const quantity = (value, unit) =>
+      `${formatNumber(value, { useGrouping: false })} ${unitLabel(unit)}`;
+    const fl =
+      altFt >= 18000 ? `FL${Math.round(altFt / 100)}` : quantity(altFt, 'ft');
+    const spd = info.velocity
+      ? quantity(Math.round(info.velocity * 1.944), 'kts')
+      : '';
     const stale =
       flightState.records.missingPolls.get(icao24) || flightState.feed._backoff
-        ? 'STALE'
+        ? t('STALE')
         : '';
     const lines = [[cs, fl, spd, stale].filter(Boolean).join(' · ')];
     // Converted contacts report their class as TR-3B and nothing else — the
@@ -1164,7 +1174,9 @@ export function createTracking({
       // first-person reference. A globe click must not fall through to the
       // normal empty-space deselection path; cockpit has explicit exit controls.
       if (document.body.classList.contains('cockpit-mode')) return;
-      const picked = viewer.scene.pick(click.position);
+      const picked = pickContact
+        ? pickContact(viewer.scene, click.position)
+        : viewer.scene.pick(click.position);
 
       if (picked) {
         // Clicking the tracked entity itself — ignore (don't deselect)

src/layers/ghostMaps/catalog.js

@@ -0,0 +1,245 @@
+// S2 Underground GhostMaps catalog: which KMZ in the public repository is the
+// current edition of each product. Pure and portable (the server builds the
+// catalog, tests pin the rules); no i18n, no DOM, no Cesium.
+
+export const GHOSTMAPS_REPO = Object.freeze({
+  owner: 's2underground',
+  name: 'GhostMaps',
+  branch: 'main',
+  url: 'https://github.com/s2underground/GhostMaps',
+});
+
+/** Largest KMZ the proxy downloads; matches the browser's import ceiling. */
+export const GHOSTMAPS_MAX_FILE_BYTES = 50 * 1024 * 1024;
+
+const ARCGIS = 'ArcGIS Data for ATAK (KMZs)/';
+const INCIDENTS = 'Incident Response Products for ATAK (KMZs and Documents)/';
+
+/**
+ * Curated products, in panel order. Each names a series of dated uploads; the
+ * newest edition wins. Patterns match whole repository paths, so a renamed
+ * folder fails closed (the product drops out) instead of matching elsewhere.
+ */
+export const GHOSTMAPS_PRODUCTS = Object.freeze([
+  Object.freeze({
+    id: 'cip',
+    // i18n-ignore: catalog data; the panel shows its own translated label
+    title: 'Common Intelligence Picture',
+    defaultOn: true,
+    pattern: new RegExp(
+      `^${escape(ARCGIS)}Common Intelligence Picture/Master Database/[^/]+\\.kmz$`,
+      'i',
+    ),
+  }),
+  Object.freeze({
+    id: 'kinetic-30d',
+    // i18n-ignore: catalog data; the panel shows its own translated label
+    title: 'Kinetic Activity (30 days)',
+    defaultOn: true,
+    pattern: new RegExp(
+      `^${escape(ARCGIS)}Common Intelligence Picture/30-Day Pulls/Kinetic[^/]*\\.kmz$`,
+      'i',
+    ),
+  }),
+  Object.freeze({
+    id: 'border-crisis',
+    // i18n-ignore: catalog data; the panel shows its own translated label
+    title: 'Border Crisis Map',
+    defaultOn: false,
+    pattern: new RegExp(
+      `^${escape(ARCGIS)}Border Crisis Map/S2Underground_Border_Crisis_Map[^/]*\\.kmz$`,
+      'i',
+    ),
+  }),
+  Object.freeze({
+    id: 'iran-cip',
+    // i18n-ignore: catalog data; the panel shows its own translated label
+    title: 'Iran Common Intelligence Picture',
+    defaultOn: false,
+    pattern: new RegExp(
+      `^${escape(INCIDENTS)}Iran[^/]*/Iran Common Intelligence Picture/[^/]+\\.kmz$`,
+      'i',
+    ),
+  }),
+  Object.freeze({
+    id: 'iran-kinetic',
+    // i18n-ignore: catalog data; the panel shows its own translated label
+    title: 'Iran Kinetic Events',
+    defaultOn: false,
+    pattern: new RegExp(
+      `^${escape(INCIDENTS)}Iran[^/]*/Iran Kinetic Events/[^/]+\\.kmz$`,
+      'i',
+    ),
+  }),
+  Object.freeze({
+    id: 'yemen-flot',
+    // i18n-ignore: catalog data; the panel shows its own translated label
+    title: 'Yemen FLOT',
+    defaultOn: false,
+    pattern: new RegExp(
+      `^${escape(INCIDENTS)}Yemen[^/]*/Yemen FLOT[^/]*\\.kmz$`,
+      'i',
+    ),
+  }),
+]);
+
+/** The newest incident product outside the curated series and the archive. */
+export const GHOSTMAPS_LATEST_DROP = Object.freeze({
+  id: 'latest-drop',
+  // i18n-ignore: catalog data; the panel shows its own translated label
+  title: 'Latest incident drop',
+  defaultOn: false,
+});
+
+const LATEST_DROP_EXCLUDED =
+  /\/(?:0_Archive|Basedata|Reference Material)(?:\/|$)/i;
+
+function escape(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const MONTHS = [
+  'jan',
+  'feb',
+  'mar',
+  'apr',
+  'may',
+  'jun',
+  'jul',
+  'aug',
+  'sep',
+  'oct',
+  'nov',
+  'dec',
+];
+const DATE_IN_NAME =
+  /(january|february|march|april|may|june|july|august|september|sept|october|november|december|jan|feb|mar|apr|jun|jul|aug|sep|oct|nov|dec)[ _-]?(\d{1,2})(?:st|nd|rd|th)?[ ,_-]+(20\d\d)/i;
+const EDITION_IN_NAME = /(?:[ _-]export)?[ _-]v?(\d{1,3})$/i;
+
+/**
+ * The date and edition written into an S2 file name, e.g.
+ * `..._October_16_2026_Export_1.kmz` → 2026-10-16, edition 1. Undated names
+ * report `dateMs: null` and sort below every dated edition.
+ * @param {string} fileName
+ * @returns {{dateMs: ?number, edition: number}}
+ */
+export function parseGhostMapsEdition(fileName) {
+  const stem = String(fileName || '').replace(/\.km[lz]$/i, '');
+  const match = DATE_IN_NAME.exec(stem);
+  let dateMs = null;
+  if (match) {
+    const month = MONTHS.indexOf(match[1].slice(0, 3).toLowerCase());
+    const day = Number(match[2]);
+    const year = Number(match[3]);
+    const at = Date.UTC(year, month, day);
+    // Date.UTC rolls 31 Sep into 1 Oct; only an exact calendar date counts.
+    if (month >= 0 && new Date(at).getUTCDate() === day) dateMs = at;
+  }
+  const tail = match ? stem.slice(match.index + match[0].length) : stem;
+  const edition = Number(EDITION_IN_NAME.exec(tail)?.[1] ?? 0);
+  return { dateMs, edition };
+}
+
+function newer(a, b) {
+  if (!b) return true;
+  const ad = a.dateMs ?? -Infinity;
+  const bd = b.dateMs ?? -Infinity;
+  if (ad !== bd) return ad > bd;
+  if (a.edition !== b.edition) return a.edition > b.edition;
+  return a.path > b.path;
+}
+
+/** `S2Underground_Border_Crisis_Map_June_02_2026_v1.kmz` → readable words. */
+export function ghostMapsFileTitle(fileName) {
+  return String(fileName || '')
+    .replace(/\.km[lz]$/i, '')
+    .replace(/^S2Underground_/i, '')
+    .replace(/_/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Build the product catalog from a recursive git tree listing.
+ * @param {Array<{path: string, type: string, sha: string, size?: number}>} tree
+ * @returns {Array<{id: string, title: string, defaultOn: boolean,
+ *   path: string, fileName: string, fileTitle: string, version: string,
+ *   size: number, dateMs: ?number, edition: number}>}
+ */
+export function buildGhostMapsCatalog(tree) {
+  const best = new Map();
+  let drop = null;
+  for (const entry of Array.isArray(tree) ? tree : []) {
+    if (entry?.type !== 'blob' || typeof entry.path !== 'string') continue;
+    if (!/\.kmz$/i.test(entry.path)) continue;
+    if (!/^[0-9a-f]{40}$/.test(entry.sha || '')) continue;
+    const size = Number(entry.size);
+    if (!Number.isFinite(size) || size <= 0 || size > GHOSTMAPS_MAX_FILE_BYTES)
+      continue;
+    const fileName = entry.path.slice(entry.path.lastIndexOf('/') + 1);
+    const candidate = {
+      path: entry.path,
+      fileName,
+      version: entry.sha,
+      size,
+      ...parseGhostMapsEdition(fileName),
+    };
+    const product = GHOSTMAPS_PRODUCTS.find(({ pattern }) =>
+      pattern.test(entry.path),
+    );
+    if (product) {
+      if (newer(candidate, best.get(product.id)))
+        best.set(product.id, candidate);
+    } else if (
+      entry.path.startsWith(INCIDENTS) &&
+      !LATEST_DROP_EXCLUDED.test(`/${entry.path}`) &&
+      candidate.dateMs != null &&
+      newer(candidate, drop)
+    ) {
+      drop = candidate;
+    }
+  }
+  const rows = [];
+  for (const product of [...GHOSTMAPS_PRODUCTS, GHOSTMAPS_LATEST_DROP]) {
+    const file =
+      product === GHOSTMAPS_LATEST_DROP ? drop : best.get(product.id);
+    if (!file) continue;
+    rows.push({
+      id: product.id,
+      title: product.title,
+      defaultOn: product.defaultOn,
+      ...file,
+      fileTitle: ghostMapsFileTitle(file.fileName),
+    });
+  }
+  return rows;
+}
+
+/**
+ * Raw download URL pinned to a commit, so a CDN can never hand back an older
+ * edition for a newer catalog.
+ * @param {string} commit 40-hex commit sha.
+ * @param {string} path Repository path.
+ */
+export function ghostMapsRawUrl(commit, path) {
+  const encoded = path.split('/').map(encodeURIComponent).join('/');
+  return `https://raw.githubusercontent.com/${GHOSTMAPS_REPO.owner}/${GHOSTMAPS_REPO.name}/${commit}/${encoded}`;
+}
+
+/**
+ * The branch head from a git smart-HTTP ref advertisement
+ * (`/info/refs?service=git-upload-pack`), or null.
+ * @param {string} text
+ * @param {string} [branch]
+ * @returns {?string}
+ */
+export function parseGitRefAdvertisement(text, branch = GHOSTMAPS_REPO.branch) {
+  const ref = `refs/heads/${branch}`;
+  for (const line of String(text || '').split('\n')) {
+    // pkt-line: 4 hex length digits, then "<sha> <ref>" (the first ref line
+    // also carries a NUL and the capability list).
+    const match = /^[0-9a-f]{4}([0-9a-f]{40}) ([^\0\s]+)/.exec(line);
+    if (match && match[2] === ref) return match[1];
+  }
+  return null;
+}

src/layers/ghostMaps/catalog.test.mjs

@@ -0,0 +1,165 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  buildGhostMapsCatalog,
+  ghostMapsFileTitle,
+  ghostMapsRawUrl,
+  parseGhostMapsEdition,
+  parseGitRefAdvertisement,
+} from './catalog.js';
+
+const ARCGIS = 'ArcGIS Data for ATAK (KMZs)/';
+const INCIDENTS = 'Incident Response Products for ATAK (KMZs and Documents)/';
+let n = 0;
+const blob = (path, size = 1000) => ({
+  path,
+  type: 'blob',
+  size,
+  sha: (++n).toString(16).padStart(40, '0'),
+});
+
+test('editions read the date and export/version number written in the name', () => {
+  assert.deepEqual(
+    parseGhostMapsEdition(
+      'S2Underground_Common_Intelligence_Picture_October_16_2026_Export_1.kmz',
+    ),
+    { dateMs: Date.UTC(2026, 9, 16), edition: 1 },
+  );
+  assert.deepEqual(
+    parseGhostMapsEdition(
+      'S2Underground_Border_Crisis_Map_September_21_2026_Export_v2.kmz',
+    ),
+    { dateMs: Date.UTC(2026, 8, 21), edition: 2 },
+  );
+  assert.deepEqual(
+    parseGhostMapsEdition('Reno Wildfires August 24, 2026.kmz'),
+    {
+      dateMs: Date.UTC(2026, 7, 24),
+      edition: 0,
+    },
+  );
+  assert.deepEqual(
+    parseGhostMapsEdition('Venezuelan_Crisis_Sep_5_2025_v2.kmz'),
+    {
+      dateMs: Date.UTC(2025, 8, 5),
+      edition: 2,
+    },
+  );
+  assert.deepEqual(
+    parseGhostMapsEdition('Kinetic_Activities_Last_30_Days.kmz'),
+    {
+      dateMs: null,
+      edition: 0,
+    },
+  );
+  // An impossible date is not a date.
+  assert.equal(parseGhostMapsEdition('X_September_31_2026.kmz').dateMs, null);
+});
+
+test('each product keeps its newest edition by date, then edition number', () => {
+  const master = `${ARCGIS}Common Intelligence Picture/Master Database/`;
+  const tree = [
+    blob(
+      `${master}S2Underground_Common_Intelligence_Picture_October_9_2026_Export_1.kmz`,
+    ),
+    blob(
+      `${master}S2Underground_Common_Intelligence_Picture_October_16_2026_Export_1.kmz`,
+    ),
+    blob(
+      `${master}S2Underground_Common_Intelligence_Picture_October_1_2026_Export_1.kmz`,
+    ),
+    blob(
+      `${master}S2Underground_Common_Intelligence_Picture_September_30_2026_Export_2.kmz`,
+    ),
+    blob(
+      `${ARCGIS}Common Intelligence Picture/30-Day Pulls/Kinetic_Activities_Last_30_Days.kmz`,
+    ),
+    blob(
+      `${ARCGIS}Border Crisis Map/S2Underground_Border_Crisis_Map_September_21_2026_Export_v1.kmz`,
+    ),
+    blob(
+      `${ARCGIS}Border Crisis Map/S2Underground_Border_Crisis_Map_September_21_2026_Export_v2.kmz`,
+    ),
+    // A European-only subset in a subfolder is not the border map.
+    blob(
+      `${ARCGIS}Border Crisis Map/European Layers Only/Europe_Migration_Crisis_June_02_2026_v1.kmz`,
+    ),
+    blob(`${INCIDENTS}Yemen 2026/Yemen FLOT.kmz`),
+    blob(`${INCIDENTS}Yemen 2026/Yemen FLOT_October_10_2026.kmz`),
+    { path: `${INCIDENTS}Yemen 2026`, type: 'tree', sha: 'f'.repeat(40) },
+  ];
+  const rows = buildGhostMapsCatalog(tree);
+  const byId = Object.fromEntries(rows.map((row) => [row.id, row]));
+  assert.deepEqual(
+    rows.map(({ id }) => id),
+    ['cip', 'kinetic-30d', 'border-crisis', 'yemen-flot'],
+  );
+  assert.match(byId.cip.fileName, /October_16_2026/);
+  assert.equal(byId.cip.defaultOn, true);
+  assert.equal(byId['kinetic-30d'].defaultOn, true);
+  assert.match(byId['border-crisis'].fileName, /Export_v2/);
+  assert.equal(byId['yemen-flot'].fileName, 'Yemen FLOT_October_10_2026.kmz');
+  assert.equal(byId.cip.version, tree[1].sha);
+  assert.equal(
+    byId.cip.fileTitle,
+    'Common Intelligence Picture October 16 2026 Export 1',
+  );
+});
+
+test('latest drop is the newest dated incident file outside curated, archived and base data', () => {
+  const rows = buildGhostMapsCatalog([
+    blob(`${INCIDENTS}Reno Wildfires August 24, 2026.kmz`),
+    blob(
+      `${INCIDENTS}Spokane Fire Disaster - August, 2026/SpokaneDisasterAid_August_8_2026.kmz`,
+    ),
+    blob(
+      `${INCIDENTS}0_Archive/Texas Floods/TexasFloods_December_1_2026_v1.kmz`,
+    ),
+    blob(`${INCIDENTS}Iran 2026/Basedata/Pipelines_December_1_2026.kmz`),
+    blob(
+      `${INCIDENTS}Iran 2026/Iran Kinetic Events/Iran_Kinetic_Events_December_2_2026_v1.kmz`,
+    ),
+    blob(`${INCIDENTS}Undated Product.kmz`),
+  ]);
+  const drop = rows.find(({ id }) => id === 'latest-drop');
+  assert.equal(drop.fileName, 'Reno Wildfires August 24, 2026.kmz');
+  assert.ok(rows.some(({ id }) => id === 'iran-kinetic'));
+});
+
+test('oversized, empty, non-KMZ and malformed entries are skipped', () => {
+  const path = `${ARCGIS}Common Intelligence Picture/Master Database/S2Underground_Common_Intelligence_Picture_October_16_2026_Export_1.kmz`;
+  assert.deepEqual(
+    buildGhostMapsCatalog([
+      { ...blob(path), size: 51 * 1024 * 1024 },
+      { ...blob(path), size: 0 },
+      { ...blob(path), sha: 'not-a-sha' },
+      blob(path.replace(/\.kmz$/, '.zip')),
+      null,
+    ]),
+    [],
+  );
+  assert.deepEqual(buildGhostMapsCatalog(undefined), []);
+});
+
+test('raw URLs are pinned to the commit and encode every path segment', () => {
+  assert.equal(
+    ghostMapsRawUrl('a'.repeat(40), 'Folder (KMZs)/Yemen FLOT.kmz'),
+    `https://raw.githubusercontent.com/s2underground/GhostMaps/${'a'.repeat(40)}/Folder%20(KMZs)/Yemen%20FLOT.kmz`,
+  );
+  assert.equal(ghostMapsFileTitle('S2Underground_A__B.kmz'), 'A B');
+});
+
+test('the branch head comes from the smart-HTTP ref advertisement', () => {
+  const head = '142d7630bc8f1f2c4b96e16ee865ca50d1ab578d';
+  const other = 'b'.repeat(40);
+  const text = [
+    '001e# service=git-upload-pack',
+    `0159${head} HEAD\0multi_ack symref=HEAD:refs/heads/main`,
+    `003f${other} refs/heads/main-old`,
+    `003d${head} refs/heads/main`,
+    '0000',
+  ].join('\n');
+  assert.equal(parseGitRefAdvertisement(text), head);
+  assert.equal(parseGitRefAdvertisement(text, 'dev'), null);
+  assert.equal(parseGitRefAdvertisement(''), null);
+});

src/layers/ghostMaps/index.js

@@ -0,0 +1,711 @@
+import * as Cesium from 'cesium';
+import {
+  decodeXml,
+  kmzImageResolver,
+  kmzMainDocument,
+  parseXml,
+  readZipEntries,
+  resolveKmzPath,
+} from '../../data/geoFileImport.js';
+import {
+  formatNumber,
+  formatUtcDayMonth,
+  msg,
+  t,
+  tn,
+} from '../../i18n/index.js';
+import { createHorizonCull } from '../streetLevel/view.js';
+import { readGhostMapsKml } from './kml.js';
+import { fieldLabel, parseDescriptionFields, wrapCardText } from './records.js';
+export * from './catalog.js';
+export * from './records.js';
+export { readGhostMapsKml } from './kml.js';
+export { createGhostMapsSource } from './source.js';
+
+export const GHOSTMAPS_LAYER_ID = 's2-ghostmaps';
+export const GHOSTMAPS_OVERLAY_SOURCE_ID = 's2-ghostmaps';
+const PICK_PREFIX = 'ghostmaps:';
+const STORAGE_KEY = 'gev.ghostmaps.products';
+const ACCENT = '#c8ff00';
+const MAX_ICON_BYTES = 512 * 1024;
+const CARD_HOST_OPTIONS = Object.freeze({
+  cohortLimit: 1,
+  collisionCapacity: 1,
+  moving: false,
+});
+const MAX_CARD_LINES = 12;
+
+/** Panel names for the catalog's product ids (the catalog sends English). */
+const PRODUCT_LABELS = Object.freeze({
+  cip: msg('Intel Picture'),
+  'kinetic-30d': msg('Kinetic 30d'),
+  'border-crisis': msg('Border Crisis'),
+  'iran-cip': msg('Iran Picture'),
+  'iran-kinetic': msg('Iran Kinetic'),
+  'yemen-flot': msg('Yemen FLOT'),
+  'latest-drop': msg('Latest Drop'),
+});
+
+/** One distinct fallback marker color per product. */
+const PRODUCT_COLORS = Object.freeze({
+  cip: '#c8ff00',
+  'kinetic-30d': '#ff5a36',
+  'border-crisis': '#ffb547',
+  'iran-cip': '#39d0ff',
+  'iran-kinetic': '#ff3b8d',
+  'yemen-flot': '#5dff9f',
+  'latest-drop': '#b48cff',
+});
+
+function defaultStorage() {
+  try {
+    return globalThis.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function readStoredSelection(storage) {
+  try {
+    const value = JSON.parse(storage?.getItem(STORAGE_KEY) ?? 'null');
+    return Array.isArray(value) ? new Set(value.map(String)) : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeStoredSelection(storage, selected) {
+  try {
+    storage?.setItem(STORAGE_KEY, JSON.stringify([...selected]));
+  } catch {
+    /* private window or blocked storage: the selection lasts this session */
+  }
+}
+
+/** A round marker for placemarks whose icon is missing or remote. */
+const markerCache = new Map();
+function markerImage(color) {
+  if (markerCache.has(color)) return markerCache.get(color);
+  let url = null;
+  try {
+    const canvas = document.createElement('canvas');
+    canvas.width = canvas.height = 20;
+    const ctx = canvas.getContext('2d');
+    ctx.beginPath();
+    ctx.arc(10, 10, 7, 0, Math.PI * 2);
+    ctx.fillStyle = color;
+    ctx.fill();
+    ctx.lineWidth = 2;
+    ctx.strokeStyle = 'rgba(0,0,0,0.85)';
+    ctx.stroke();
+    url = canvas.toDataURL();
+  } catch {
+    url = null;
+  }
+  markerCache.set(color, url);
+  return url;
+}
+
+const cesiumColor = (rgba, fallback, alpha) =>
+  rgba
+    ? new Cesium.Color(rgba[0], rgba[1], rgba[2], alpha ?? rgba[3])
+    : Cesium.Color.fromCssColorString(fallback).withAlpha(alpha ?? 1);
+
+function anchorOf(geometry) {
+  if (geometry.type === 'point') return geometry.position;
+  const ring =
+    geometry.type === 'polygon' ? geometry.outer : geometry.positions;
+  let lon = 0;
+  let lat = 0;
+  for (const [x, y] of ring) {
+    lon += x;
+    lat += y;
+  }
+  return [lon / ring.length, lat / ring.length];
+}
+
+/**
+ * S2 Underground GhostMaps: the current editions of S2's public KMZ intel
+ * products, kept in step with the GitHub repository. The proxy watches the
+ * branch head and pushes each new commit; only changed products reload.
+ */
+export function createGhostMapsLayer({
+  source,
+  overlayHost = null,
+  screenSpaceEventHandlerFactory = null,
+  picking = null,
+  pointer = null,
+  openExternal = null,
+  storage = defaultStorage(),
+} = {}) {
+  if (typeof source?.getCatalog !== 'function')
+    throw new TypeError('GhostMaps layer requires a catalog source');
+  let _viewer = null;
+  let _enabled = false;
+  let _catalog = null;
+  let _lastError = null;
+  let _unsubscribe = null;
+  let _stream = 'closed';
+  let _queue = Promise.resolve();
+  let _clickHandler = null;
+  let _rowListener = null;
+  let _selectedKey = null;
+  let _selectedCardId = null;
+  let _selectedLink = null;
+  let _lifetime = new AbortController();
+  let _selection = readStoredSelection(storage);
+  /** productId → {version, dataSource, urls, count, features} */
+  const _loaded = new Map();
+  /** productId → in-flight version */
+  const _loading = new Map();
+  /** productId → error text */
+  const _failed = new Map();
+
+  const notifyRow = () => _rowListener?.();
+  const render = () => _viewer?.scene?.requestRender?.();
+  // Pins skip the depth test, and with Google 3D tiles the globe is hidden,
+  // so nothing else stops far-side pins drawing through the planet.
+  const _horizon = createHorizonCull({
+    getViewer: () => _viewer,
+    items: function* () {
+      for (const item of _loaded.values()) yield* item.pins;
+    },
+    onChange: render,
+  });
+  const canSelect = () =>
+    overlayHost && screenSpaceEventHandlerFactory && picking;
+
+  function wanted(product) {
+    return _selection ? _selection.has(product.id) : product.defaultOn;
+  }
+
+  function selectedIds() {
+    return (_catalog?.products || []).filter(wanted).map(({ id }) => id);
+  }
+
+  function unload(id) {
+    const item = _loaded.get(id);
+    if (!item) return;
+    _loaded.delete(id);
+    _viewer?.dataSources?.remove(item.dataSource, true);
+    item.urls.forEach((url) => URL.revokeObjectURL(url));
+    if (_selectedKey?.startsWith(`${id}:`)) clearSelection();
+  }
+
+  /** Build one product's data source off-scene, then swap it in. */
+  async function load(product, signal) {
+    const bytes = await source.getFile(product.id, product.version, { signal });
+    signal.throwIfAborted();
+    const entries = await readZipEntries(bytes);
+    signal.throwIfAborted();
+    const main = kmzMainDocument(entries);
+    if (!main) throw new Error(msg('That KMZ holds no KML document.'));
+    const urls = [];
+    const resolvePacked = kmzImageResolver(entries, main, (url) =>
+      urls.push(url),
+    );
+    // Icons only: ArcGIS exports also pack multi-megabyte photo attachments,
+    // which fall back to the product marker instead of being decoded.
+    const resolveImage = (href) => {
+      const path = resolveKmzPath(href, main, entries);
+      return path && entries.get(path).length <= MAX_ICON_BYTES
+        ? resolvePacked(href)
+        : null;
+    };
+    try {
+      const parsed = readGhostMapsKml(
+        parseXml(decodeXml(entries.get(main)), 'KML'),
+        resolveImage,
+      );
+      entries.clear();
+      signal.throwIfAborted();
+      const color = PRODUCT_COLORS[product.id] || ACCENT;
+      const dataSource = new Cesium.CustomDataSource(
+        `${GHOSTMAPS_LAYER_ID}:${product.id}`,
+      );
+      const features = [];
+      const pins = [];
+      dataSource.entities.suspendEvents();
+      parsed.features.forEach((feature, index) => {
+        const key = `${product.id}:${index}`;
+        const { style } = feature;
+        feature.geometries.forEach((geometry, part) => {
+          const id = `${PICK_PREFIX}${key}:${part}`;
+          if (geometry.type === 'point') {
+            const position = Cesium.Cartesian3.fromDegrees(
+              ...geometry.position,
+            );
+            const entity = dataSource.entities.add({
+              id,
+              position,
+              billboard: {
+                image: style.icon || markerImage(color),
+                scale: Math.min(
+                  1.5,
+                  Math.max(0.35, (style.iconScale ?? 1) * 0.7),
+                ),
+                color:
+                  style.icon && style.iconColor
+                    ? cesiumColor(style.iconColor)
+                    : undefined,
+                heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
+                verticalOrigin: Cesium.VerticalOrigin.CENTER,
+                // Ground-clamped icons would sink into terrain and 3D tiles; the
+                // horizon cull hides the far side instead (see `_horizon`).
+                disableDepthTestDistance: Number.POSITIVE_INFINITY,
+              },
+            });
+            pins.push({
+              position,
+              get show() {
+                return entity.show;
+              },
+              set show(value) {
+                entity.show = value;
+              },
+            });
+          } else if (geometry.type === 'line') {
+            dataSource.entities.add({
+              id,
+              polyline: {
+                positions: Cesium.Cartesian3.fromDegreesArray(
+                  geometry.positions.flat(),
+                ),
+                width: Math.min(8, Math.max(1.5, style.lineWidth ?? 2)),
+                material: cesiumColor(style.lineColor, color),
+                clampToGround: true,
+              },
+            });
+          } else {
+            const ring = (points) =>
+              Cesium.Cartesian3.fromDegreesArray(points.flat());
+            dataSource.entities.add({
+              id,
+              polygon: {
+                hierarchy: new Cesium.PolygonHierarchy(
+                  ring(geometry.outer),
+                  geometry.holes.map(
+                    (hole) => new Cesium.PolygonHierarchy(ring(hole)),
+                  ),
+                ),
+                material:
+                  style.fill === false
+                    ? Cesium.Color.TRANSPARENT
+                    : cesiumColor(
+                        style.polyColor,
+                        color,
+                        style.polyColor ? undefined : 0.25,
+                      ),
+                classificationType: Cesium.ClassificationType.BOTH,
+              },
+            });
+            if (style.outline !== false)
+              dataSource.entities.add({
+                id: `${id}:outline`,
+                polyline: {
+                  positions: ring([...geometry.outer, geometry.outer[0]]),
+                  width: Math.min(6, Math.max(1.5, style.lineWidth ?? 2)),
+                  material: cesiumColor(style.lineColor, color),
+                  clampToGround: true,
+                },
+              });
+          }
+        });
+        features.push({
+          name: feature.name,
+          folder: feature.folder,
+          description: feature.description,
+          anchor: anchorOf(feature.geometries[0]),
+        });
+      });
+      dataSource.entities.resumeEvents();
+      return { version: product.version, dataSource, urls, features, pins };
+    } catch (error) {
+      urls.forEach((url) => URL.revokeObjectURL(url));
+      throw error;
+    }
+  }
+
+  /** Bring the globe in line with the catalog and the chip selection. */
+  function sync() {
+    const run = _queue.then(async () => {
+      if (!_enabled || !_viewer || !_catalog) return;
+      const signal = _lifetime.signal;
+      const products = new Map(_catalog.products.map((p) => [p.id, p]));
+      for (const id of [..._loaded.keys()]) {
+        const product = products.get(id);
+        if (!product || !wanted(product)) unload(id);
+      }
+      for (const product of _catalog.products) {
+        if (!wanted(product) || signal.aborted) continue;
+        if (_loaded.get(product.id)?.version === product.version) continue;
+        _loading.set(product.id, product.version);
+        _failed.delete(product.id);
+        notifyRow();
+        try {
+          const next = await load(product, signal);
+          if (signal.aborted || !_enabled) {
+            next.urls.forEach((url) => URL.revokeObjectURL(url));
+            return;
+          }
+          // Cull before the first frame so far-side pins never flash.
+          _horizon.update(next.pins);
+          await _viewer.dataSources.add(next.dataSource);
+          // The new edition is on the globe before the old one leaves.
+          unload(product.id);
+          _loaded.set(product.id, next);
+        } catch (error) {
+          if (signal.aborted) return;
+          console.warn(`[Data:GhostMaps] ${product.id}:`, error);
+          _failed.set(
+            product.id,
+            error?.template ||
+              error?.message ||
+              msg('GhostMaps file could not be read'),
+          );
+        } finally {
+          _loading.delete(product.id);
+          notifyRow();
+          render();
+        }
+      }
+    });
+    _queue = run.catch(() => {});
+    return run;
+  }
+
+  function applyCatalog(catalog) {
+    _catalog = catalog;
+    _lastError = catalog.error || null;
+    notifyRow();
+    return sync();
+  }
+
+  function toggleProduct(id) {
+    // The first change pins the whole current selection, defaults included.
+    if (!_selection) _selection = new Set(selectedIds());
+    if (_selection.has(id)) _selection.delete(id);
+    else _selection.add(id);
+    writeStoredSelection(storage, _selection);
+    notifyRow();
+    void sync();
+  }
+
+  // ---- selection card ----------------------------------------------------
+  function featureFor(key) {
+    const [productId, index] = key.split(':');
+    return {
+      product: _catalog?.products.find((p) => p.id === productId) || null,
+      feature: _loaded.get(productId)?.features[Number(index)] || null,
+    };
+  }
+
+  function publishCard() {
+    if (!canSelect()) return;
+    const { product, feature } = _selectedKey ? featureFor(_selectedKey) : {};
+    if (!feature) {
+      _selectedKey = null;
+      _selectedCardId = null;
+      _selectedLink = null;
+      overlayHost.setEntries(
+        GHOSTMAPS_OVERLAY_SOURCE_ID,
+        [],
+        CARD_HOST_OPTIONS,
+      );
+      return;
+    }
+    const { fields, links } = parseDescriptionFields(feature.description);
+    _selectedLink = links[0] || null;
+    const heading = [t(PRODUCT_LABELS[product?.id] || product?.title || '')];
+    if (feature.folder) heading.push(fieldLabel(feature.folder));
+    if (product?.dateMs) heading.push(formatUtcDayMonth(product.dateMs));
+    const details = [heading.filter(Boolean).join(' · ')];
+    for (const { label, value } of fields) {
+      if (details.length >= MAX_CARD_LINES) break;
+      // ArcGIS repeats the feature type as the first row; the title has it.
+      if (value === feature.name) continue;
+      const line = label ? `${fieldLabel(label)}: ${value}` : value;
+      details.push(
+        ...wrapCardText(line, 60, Math.min(4, MAX_CARD_LINES - details.length)),
+      );
+    }
+    if (_selectedLink && openExternal)
+      details.push(
+        tn(
+          links.length,
+          '{count} source link ↗ · click card to open',
+          '{count} source links ↗ · click card to open the first',
+          { count: formatNumber(links.length) },
+        ),
+      );
+    const title = t('S2 · {name}', {
+      name: fieldLabel(feature.name || feature.folder) || t('Report'),
+    });
+    const card = {
+      id: `ghostmaps-card:${_selectedKey}`,
+      selected: true,
+      interactive: Boolean(_selectedLink && openExternal),
+      title,
+      details,
+      accent: PRODUCT_COLORS[product?.id] || ACCENT,
+      priority: Number.MAX_SAFE_INTEGER,
+      gapPx: 15,
+      verticalOnly: true,
+      placement: 'above',
+      // A click card comes and goes with the click, as CCTV cards do, rather
+      // than holding the label arbiter's 2.5 s minimum lifetime; and it hides
+      // when its marker turns behind the planet.
+      stateless: true,
+      horizonCull: true,
+      position: Cesium.Cartesian3.fromDegrees(...feature.anchor),
+    };
+    if (card.interactive) {
+      const link = _selectedLink;
+      card.accessibilityLabel = t('Open the source for {title}', { title });
+      card.activate = () => {
+        openExternal(link);
+        return true;
+      };
+    }
+    _selectedCardId = card.id;
+    overlayHost.setEntries(
+      GHOSTMAPS_OVERLAY_SOURCE_ID,
+      [card],
+      CARD_HOST_OPTIONS,
+    );
+    overlayHost.setVisible?.(GHOSTMAPS_OVERLAY_SOURCE_ID, true);
+  }
+
+  function clearSelection() {
+    _selectedKey = null;
+    _selectedCardId = null;
+    _selectedLink = null;
+    // An empty publish, as the perimeter cards deselect: it releases the
+    // selected card's paint lane, which clearing the source alone left drawn.
+    overlayHost?.setEntries(GHOSTMAPS_OVERLAY_SOURCE_ID, [], CARD_HOST_OPTIONS);
+  }
+
+  function pickedKey(picked) {
+    const pickId = picking.resolvePickId(picked);
+    if (typeof pickId !== 'string' || !pickId.startsWith(PICK_PREFIX))
+      return null;
+    const [productId, index] = pickId.slice(PICK_PREFIX.length).split(':');
+    return _loaded.get(productId)?.features[Number(index)]
+      ? `${productId}:${index}`
+      : null;
+  }
+
+  function installClickHandler() {
+    if (!canSelect() || _clickHandler || !_viewer) return;
+    picking.registerPickOwner?.(
+      GHOSTMAPS_LAYER_ID,
+      (pickedId) =>
+        typeof pickedId === 'string' && pickedId.startsWith(PICK_PREFIX),
+    );
+    _clickHandler = screenSpaceEventHandlerFactory(_viewer);
+    _clickHandler.setInputAction((click) => {
+      if (pointer && !pointer.isPointerFree()) return;
+      const cardHit = overlayHost.hitTest?.(
+        click.position?.x,
+        click.position?.y,
+        { sourceId: GHOSTMAPS_OVERLAY_SOURCE_ID },
+      );
+      if (cardHit && cardHit.entryId === _selectedCardId) {
+        if (_selectedLink && openExternal) openExternal(_selectedLink);
+        return;
+      }
+      const picked = _viewer.scene.pick(click.position);
+      const key = picked ? pickedKey(picked) : null;
+      if (key) {
+        _selectedKey = key;
+        publishCard();
+        render();
+        return;
+      }
+      if (picked) {
+        const pickId = picking.resolvePickId(picked);
+        if (pickId && picking.isOwnedByOtherLayer(GHOSTMAPS_LAYER_ID, pickId))
+          return;
+      }
+      if (_selectedKey) {
+        clearSelection();
+        render();
+      }
+    }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+  }
+
+  function removeClickHandler() {
+    _clickHandler?.destroy();
+    _clickHandler = null;
+    picking?.unregisterPickOwner?.(GHOSTMAPS_LAYER_ID);
+  }
+
+  function featureCount() {
+    let count = 0;
+    for (const item of _loaded.values()) count += item.features.length;
+    return count;
+  }
+
+  const layer = {
+    id: GHOSTMAPS_LAYER_ID,
+    name: 'S2 GhostMaps',
+    icon: '👻',
+    source: 'S2 Underground',
+    // Pushes arrive within seconds over the event stream; this interval is
+    // the backstop if the stream is down.
+    updateInterval: 300000,
+
+    init(viewer) {
+      if (_viewer) throw new Error('GhostMaps layer is already initialized');
+      _viewer = viewer;
+    },
+
+    enable() {
+      _enabled = true;
+      _lifetime = new AbortController();
+      for (const item of _loaded.values()) item.dataSource.show = true;
+      installClickHandler();
+      if (!_unsubscribe && typeof source.subscribe === 'function')
+        _unsubscribe = source.subscribe(
+          (catalog) => {
+            if (_enabled) void applyCatalog(catalog);
+          },
+          (state) => {
+            if (_stream === state) return;
+            _stream = state;
+            notifyRow();
+          },
+        );
+    },
+
+    disable() {
+      _enabled = false;
+      _lifetime.abort();
+      _unsubscribe?.();
+      _unsubscribe = null;
+      _stream = 'closed';
+      removeClickHandler();
+      clearSelection();
+      _horizon.stop();
+      for (const id of [..._loaded.keys()]) unload(id);
+      render();
+    },
+
+    async update(_viewerArg, { signal } = {}) {
+      if (!_enabled || signal?.aborted) return false;
+      try {
+        const catalog = await source.getCatalog({ signal });
+        if (!_enabled) return false;
+        await applyCatalog(catalog);
+        return true;
+      } catch (error) {
+        if (signal?.aborted || !_enabled) return false;
+        console.warn('[Data:GhostMaps] catalog error:', error);
+        _lastError = error?.message || msg('GhostMaps catalog unavailable');
+        notifyRow();
+        // Keep the layer on; the event stream or the next interval recovers.
+        return true;
+      }
+    },
+
+    destroy() {
+      layer.disable();
+      _viewer = null;
+      _catalog = null;
+      _rowListener = null;
+    },
+
+    setRowControlsListener(listener) {
+      _rowListener = listener;
+    },
+
+    getRowControls() {
+      const products = _catalog?.products || [];
+      const commit = _catalog?.commit;
+      const info = commit
+        ? _stream === 'open'
+          ? t('LIVE · GitHub {commit} · {message} · checked every {seconds}s', {
+              commit: commit.slice(0, 7),
+              message: _catalog.message || '—',
+              seconds: formatNumber(
+                Math.round((_catalog.pollMs || 15000) / 1000),
+              ),
+            })
+          : t('GitHub {commit} · {message} · reconnecting for live updates', {
+              commit: commit.slice(0, 7),
+              message: _catalog.message || '—',
+            })
+        : t('Connecting to the S2 GhostMaps repository…');
+      return {
+        chips: products.map((product) => {
+          const loaded = _loaded.get(product.id);
+          const failed = _failed.get(product.id);
+          return {
+            id: product.id,
+            label: t(PRODUCT_LABELS[product.id] || product.title),
+            active: wanted(product),
+            busy: _loading.has(product.id),
+            state: failed ? 'error' : undefined,
+            color: PRODUCT_COLORS[product.id],
+            title: [
+              product.fileTitle,
+              loaded
+                ? tn(
+                    loaded.features.length,
+                    '{count} placemark',
+                    '{count} placemarks',
+                    {
+                      count: formatNumber(loaded.features.length),
+                    },
+                  )
+                : null,
+              failed ? t(failed) : null,
+            ]
+              .filter(Boolean)
+              .join(' · '),
+            onClick: () => toggleProduct(product.id),
+          };
+        }),
+        legend: [],
+        info,
+        infoTitle: t(
+          'S2 Underground publishes these KMZ products to GitHub. New uploads are detected within seconds and replace the previous edition automatically. Click a marker for its report.',
+        ),
+      };
+    },
+
+    getStats() {
+      return {
+        count: featureCount(),
+        products: [..._loaded.keys()],
+        commit: _catalog?.commit || null,
+        lastUpdate: _catalog?.committedAt || _catalog?.changedAt || null,
+        checkedAt: _catalog?.checkedAt || null,
+        stream: _stream,
+        loading: _loading.size > 0,
+        error: _lastError || [..._failed.values()][0] || null,
+        fallback: false,
+      };
+    },
+
+    /** Loaded placemarks as plain records, for tools and QA. */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!_enabled) return [];
+      const out = [];
+      for (const [productId, item] of _loaded) {
+        for (const feature of item.features) {
+          if (out.length >= maxCount) return out;
+          out.push({
+            product: productId,
+            name: feature.name,
+            folder: feature.folder,
+            lon: feature.anchor[0],
+            lat: feature.anchor[1],
+          });
+        }
+      }
+      return out;
+    },
+  };
+  return layer;
+}

src/layers/ghostMaps/kml.js

@@ -0,0 +1,198 @@
+// Read the drawable content of a parsed GhostMaps KML document: placemarks
+// with their folder, geometry, resolved style and raw description. Network
+// links, overlays, models and remote icons are never followed; an icon is
+// either an image packed in the same KMZ or the layer's own marker.
+import { kmlColor } from './records.js';
+
+export const MAX_GHOSTMAPS_FEATURES = 20_000;
+export const MAX_GHOSTMAPS_POSITIONS = 250_000;
+
+const childrenNamed = (el, name) =>
+  [...(el?.children || [])].filter((child) => child.localName === name);
+const firstChild = (el, name) =>
+  [...(el?.children || [])].find((child) => child.localName === name) || null;
+const descendants = (el, name) =>
+  [...(el?.getElementsByTagName?.('*') || [])].filter(
+    (child) => child.localName === name,
+  );
+const text = (el) => (el?.textContent ?? '').trim();
+
+function number(el, fallback) {
+  const value = Number(text(el));
+  return el && Number.isFinite(value) ? value : fallback;
+}
+
+/** `lon,lat[,alt] lon,lat ...` → [[lon, lat], ...]; invalid tuples are dropped. */
+export function parseKmlCoordinates(value) {
+  const out = [];
+  for (const tuple of String(value ?? '')
+    .trim()
+    .split(/\s+/)) {
+    const [lon, lat] = tuple.split(',').map(Number);
+    if (
+      Number.isFinite(lon) &&
+      Number.isFinite(lat) &&
+      Math.abs(lat) <= 90 &&
+      Math.abs(lon) <= 180
+    )
+      out.push([lon, lat]);
+  }
+  return out;
+}
+
+function readStyle(styleEl, resolveImage) {
+  const style = {};
+  const icon = firstChild(styleEl, 'IconStyle');
+  if (icon) {
+    const href = text(firstChild(firstChild(icon, 'Icon'), 'href'));
+    style.icon = href ? resolveImage(href) : null;
+    style.iconScale = number(firstChild(icon, 'scale'), 1);
+    style.iconColor = kmlColor(text(firstChild(icon, 'color')));
+  }
+  const line = firstChild(styleEl, 'LineStyle');
+  if (line) {
+    style.lineColor = kmlColor(text(firstChild(line, 'color')));
+    style.lineWidth = number(firstChild(line, 'width'), 1);
+  }
+  const poly = firstChild(styleEl, 'PolyStyle');
+  if (poly) {
+    style.polyColor = kmlColor(text(firstChild(poly, 'color')));
+    style.fill = text(firstChild(poly, 'fill')) !== '0';
+    style.outline = text(firstChild(poly, 'outline')) !== '0';
+  }
+  return style;
+}
+
+/** Shared styles by id; a StyleMap resolves to its `normal` pair. */
+function collectStyles(doc, resolveImage) {
+  const styles = new Map();
+  for (const el of descendants(doc, 'Style')) {
+    const id = el.getAttribute('id');
+    if (id) styles.set(id, readStyle(el, resolveImage));
+  }
+  const maps = new Map();
+  for (const el of descendants(doc, 'StyleMap')) {
+    const id = el.getAttribute('id');
+    if (!id) continue;
+    const normal = childrenNamed(el, 'Pair').find(
+      (pair) => text(firstChild(pair, 'key')) === 'normal',
+    );
+    if (!normal) continue;
+    const inline = firstChild(normal, 'Style');
+    maps.set(
+      id,
+      inline
+        ? readStyle(inline, resolveImage)
+        : text(firstChild(normal, 'styleUrl')),
+    );
+  }
+  const resolve = (url, depth = 0) => {
+    const id = String(url || '').replace(/^#/, '');
+    if (!id || url.includes('/') || depth > 2) return {};
+    if (styles.has(id)) return styles.get(id);
+    const mapped = maps.get(id);
+    if (typeof mapped === 'string') return resolve(mapped, depth + 1);
+    return mapped || {};
+  };
+  return resolve;
+}
+
+function readGeometry(el, out, budget) {
+  switch (el.localName) {
+    case 'Point': {
+      const [position] = parseKmlCoordinates(
+        text(firstChild(el, 'coordinates')),
+      );
+      if (position) {
+        budget.positions += 1;
+        out.push({ type: 'point', position });
+      }
+      break;
+    }
+    case 'LineString':
+    case 'LinearRing': {
+      const positions = parseKmlCoordinates(
+        text(firstChild(el, 'coordinates')),
+      );
+      if (positions.length >= 2) {
+        budget.positions += positions.length;
+        out.push({ type: 'line', positions });
+      }
+      break;
+    }
+    case 'Polygon': {
+      const ring = (boundary) =>
+        parseKmlCoordinates(
+          text(firstChild(firstChild(boundary, 'LinearRing'), 'coordinates')),
+        );
+      const outer = ring(firstChild(el, 'outerBoundaryIs'));
+      if (outer.length >= 3) {
+        const holes = childrenNamed(el, 'innerBoundaryIs')
+          .map(ring)
+          .filter((hole) => hole.length >= 3);
+        budget.positions +=
+          outer.length + holes.reduce((n, hole) => n + hole.length, 0);
+        out.push({ type: 'polygon', outer, holes });
+      }
+      break;
+    }
+    case 'MultiGeometry':
+      for (const child of el.children) readGeometry(child, out, budget);
+      break;
+    default:
+      // Models, tracks and anything newer are not drawn.
+      break;
+  }
+}
+
+/** Name of the nearest enclosing Folder (or Document), for grouping. */
+function folderName(el) {
+  for (let node = el.parentElement; node; node = node.parentElement) {
+    if (node.localName === 'Folder' || node.localName === 'Document') {
+      const name = text(firstChild(node, 'name'));
+      if (name) return name;
+    }
+  }
+  return '';
+}
+
+/**
+ * @param {Document} doc Parsed KML.
+ * @param {(href: string) => ?string} resolveImage URL for a KMZ-packed image.
+ * @returns {{features: Array<{name: string, folder: string,
+ *   description: string, style: object, geometries: Array<object>}>,
+ *   positions: number, over: boolean}}
+ */
+export function readGhostMapsKml(doc, resolveImage = () => null) {
+  const styleFor = collectStyles(doc, resolveImage);
+  const features = [];
+  const budget = { positions: 0 };
+  let over = false;
+  for (const placemark of descendants(doc, 'Placemark')) {
+    // A hidden placemark (visibility 0) is drawn hidden by Google Earth too.
+    if (text(firstChild(placemark, 'visibility')) === '0') continue;
+    const geometries = [];
+    for (const child of placemark.children)
+      readGeometry(child, geometries, budget);
+    if (!geometries.length) continue;
+    if (
+      features.length >= MAX_GHOSTMAPS_FEATURES ||
+      budget.positions > MAX_GHOSTMAPS_POSITIONS
+    ) {
+      over = true;
+      break;
+    }
+    const inline = firstChild(placemark, 'Style');
+    features.push({
+      name: text(firstChild(placemark, 'name')).slice(0, 200),
+      folder: folderName(placemark).slice(0, 120),
+      description: text(firstChild(placemark, 'description')),
+      style: {
+        ...styleFor(text(firstChild(placemark, 'styleUrl'))),
+        ...(inline ? readStyle(inline, resolveImage) : {}),
+      },
+      geometries,
+    });
+  }
+  return { features, positions: budget.positions, over };
+}

src/layers/ghostMaps/lifecycle.test.mjs

@@ -0,0 +1,180 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { createGhostMapsLayer } from './index.js';
+
+function element(localName, children = [], value = '', attributes = {}) {
+  const node = {
+    localName,
+    children,
+    get textContent() {
+      return value + children.map((child) => child.textContent).join('');
+    },
+    getAttribute: (key) => attributes[key] ?? null,
+    getElementsByTagName(name) {
+      return children.flatMap((child) => [
+        ...(name === '*' || name === child.localName ? [child] : []),
+        ...child.getElementsByTagName(name),
+      ]);
+    },
+  };
+  for (const child of children) child.parentElement = node;
+  return node;
+}
+
+function documentFixture() {
+  return element('document', [
+    element('kml', [
+      element('Document', [
+        element(
+          'Style',
+          [
+            element('IconStyle', [
+              element('Icon', [element('href', [], 'icon.png')]),
+            ]),
+          ],
+          '',
+          { id: 'pin' },
+        ),
+        element('Placemark', [
+          element('name', [], 'Test report'),
+          element('styleUrl', [], '#pin'),
+          element('Point', [element('coordinates', [], '12,34')]),
+        ]),
+      ]),
+    ]),
+  ]);
+}
+
+// A stored KMZ with a local icon; the XML DOM double supplies its one point.
+function fixtureKmz() {
+  const files = [
+    ['doc.kml', '<kml/>'],
+    ['icon.png', 'packed icon'],
+  ];
+  const local = [];
+  const central = [];
+  let offset = 0;
+  for (const [name, value] of files) {
+    const key = Buffer.from(name);
+    const bytes = Buffer.from(value);
+    const header = Buffer.alloc(30);
+    header.writeUInt32LE(0x04034b50);
+    header.writeUInt32LE(bytes.length, 18);
+    header.writeUInt32LE(bytes.length, 22);
+    header.writeUInt16LE(key.length, 26);
+    const directory = Buffer.alloc(46);
+    directory.writeUInt32LE(0x02014b50);
+    directory.writeUInt32LE(bytes.length, 20);
+    directory.writeUInt32LE(bytes.length, 24);
+    directory.writeUInt16LE(key.length, 28);
+    directory.writeUInt32LE(offset, 42);
+    local.push(header, key, bytes);
+    central.push(directory, key);
+    offset += header.length + key.length + bytes.length;
+  }
+  const directory = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50);
+  end.writeUInt16LE(files.length, 8);
+  end.writeUInt16LE(files.length, 10);
+  end.writeUInt32LE(directory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return new Uint8Array(Buffer.concat([...local, directory, end]));
+}
+
+function fixture(t, { beforeFileReturns, onCreateUrl } = {}) {
+  const previous = Object.getOwnPropertyDescriptor(globalThis, 'DOMParser');
+  globalThis.DOMParser = class {
+    parseFromString() {
+      return documentFixture();
+    }
+  };
+  t.after(() => {
+    if (previous) Object.defineProperty(globalThis, 'DOMParser', previous);
+    else delete globalThis.DOMParser;
+  });
+  const created = [];
+  const revoked = [];
+  t.mock.method(URL, 'createObjectURL', () => {
+    const url = `blob:local-${created.length}`;
+    created.push(url);
+    onCreateUrl?.(layer);
+    return url;
+  });
+  t.mock.method(URL, 'revokeObjectURL', (url) => revoked.push(url));
+  t.mock.method(console, 'warn', () => {});
+  const mounted = new Set();
+  const viewer = {
+    scene: { requestRender() {} },
+    dataSources: {
+      async add(dataSource) {
+        mounted.add(dataSource);
+        return dataSource;
+      },
+      remove(dataSource) {
+        return mounted.delete(dataSource);
+      },
+    },
+  };
+  const layer = createGhostMapsLayer({
+    storage: null,
+    source: {
+      getCatalog: async () => ({
+        products: [{ id: 'cip', version: 'a'.repeat(40), defaultOn: true }],
+      }),
+      getFile: async () => {
+        beforeFileReturns?.(layer);
+        return fixtureKmz();
+      },
+    },
+  });
+  layer.init(viewer);
+  layer.enable();
+  t.after(() => layer.destroy());
+  return { layer, viewer, mounted, created, revoked };
+}
+
+test('cancelling a file read does not allocate packed-image URLs', async (t) => {
+  const { layer, viewer, mounted, created, revoked } = fixture(t, {
+    beforeFileReturns: (layer) => queueMicrotask(() => layer.disable()),
+  });
+  await layer.update(viewer);
+  assert.equal(created.length, 0);
+  assert.equal(revoked.length, 0);
+  assert.equal(mounted.size, 0);
+});
+
+test('cancellation during parsing releases every packed-image URL', async (t) => {
+  const { layer, viewer, mounted, created, revoked } = fixture(t, {
+    onCreateUrl: (layer) => layer.disable(),
+  });
+  await layer.update(viewer);
+  assert.equal(created.length, 1);
+  assert.deepEqual(revoked, created);
+  assert.equal(mounted.size, 0);
+});
+
+test('entity construction failure releases parsed image URLs', async (t) => {
+  const { layer, viewer, mounted, created, revoked } = fixture(t);
+  t.mock.method(Cesium.EntityCollection.prototype, 'add', () => {
+    throw new Error('fixture entity failure');
+  });
+  await layer.update(viewer);
+  assert.equal(created.length, 1);
+  assert.deepEqual(revoked, created);
+  assert.equal(mounted.size, 0);
+  assert.equal(layer.getStats().error, 'fixture entity failure');
+});
+
+test('successful load keeps icons until the product is disabled', async (t) => {
+  const { layer, viewer, mounted, created, revoked } = fixture(t);
+  await layer.update(viewer);
+  assert.equal(created.length, 1);
+  assert.equal(revoked.length, 0);
+  assert.equal(mounted.size, 1);
+  assert.equal(layer.getStats().count, 1);
+  layer.disable();
+  assert.deepEqual(revoked, created);
+  assert.equal(mounted.size, 0);
+});

src/layers/ghostMaps/records.js

@@ -0,0 +1,165 @@
+// Pure helpers for GhostMaps placemarks: description tables to plain fields,
+// KML colors, and card text wrapping. Strings in, data out — description
+// markup is only ever read as text, never inserted into the page.
+
+const ENTITIES = Object.freeze({
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+});
+
+/** Decode the HTML character references ArcGIS and Google Earth emit. */
+export function decodeHtmlEntities(text) {
+  return String(text ?? '').replace(
+    /&(#x[0-9a-f]{1,6}|#\d{1,7}|[a-z]{2,8});/gi,
+    (whole, ref) => {
+      if (ref[0] === '#') {
+        const code =
+          ref[1] === 'x' || ref[1] === 'X'
+            ? parseInt(ref.slice(2), 16)
+            : parseInt(ref.slice(1), 10);
+        return code > 0 &&
+          code <= 0x10ffff &&
+          !(code >= 0xd800 && code <= 0xdfff)
+          ? String.fromCodePoint(code)
+          : '';
+      }
+      return ENTITIES[ref.toLowerCase()] ?? whole;
+    },
+  );
+}
+
+/** Markup to one line of plain text. */
+export function htmlToText(html) {
+  return decodeHtmlEntities(
+    String(html ?? '')
+      .replace(/<(script|style|head)\b[\s\S]*?<\/\1\s*>/gi, ' ')
+      .replace(/<br\s*\/?>/gi, ' ')
+      .replace(/<[^>]*>/g, ' '),
+  )
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+const EMPTY_VALUES = new Set(['', '<null>', 'null', 'n/a', '-', '<blank>']);
+// ArcGIS writes geometry type and internal ids into every popup table.
+const SKIPPED_LABELS = new Set(['shape', 'objectid', 'fid', 'globalid']);
+const MAX_FIELDS = 24;
+const MAX_VALUE = 600;
+const MAX_LINKS = 6;
+
+/**
+ * Fields and links from a placemark description. ArcGIS "popup" exports are a
+ * two-column table (label, value); anything else becomes one unlabelled field.
+ * @param {string} html Description as written in the KML (CDATA text).
+ * @returns {{fields: Array<{label: string, value: string}>, links: string[]}}
+ */
+export function parseDescriptionFields(html) {
+  const source = String(html ?? '').replace(
+    /<(script|style|head)\b[\s\S]*?<\/\1\s*>/gi,
+    ' ',
+  );
+  const fields = [];
+  const links = [];
+  const addLinks = (markup) => {
+    for (const match of markup.matchAll(/href\s*=\s*["']([^"']+)["']/gi)) {
+      const url = decodeHtmlEntities(match[1]).trim();
+      if (/^https?:\/\/[^\s]+$/i.test(url) && !links.includes(url))
+        links.push(url);
+    }
+  };
+  // Innermost rows only: ArcGIS nests the field table inside an outer row,
+  // and only leaf rows with exactly two cells are label/value pairs.
+  for (const row of source.matchAll(
+    /<tr\b[^>]*>((?:(?!<tr\b)[\s\S])*?)<\/tr\s*>/gi,
+  )) {
+    const cells = [
+      ...row[1].matchAll(/<t[dh]\b[^>]*>([\s\S]*?)<\/t[dh]\s*>/gi),
+    ].map((cell) => cell[1]);
+    if (cells.length !== 2) continue;
+    const label = htmlToText(cells[0]);
+    const value = htmlToText(cells[1]);
+    if (!label || SKIPPED_LABELS.has(label.toLowerCase())) continue;
+    if (EMPTY_VALUES.has(value.toLowerCase())) continue;
+    addLinks(cells[1]);
+    // A bare research link is carried by `links`; the card does not need
+    // the URL twice.
+    if (/^https?:\/\/\S+$/i.test(value)) continue;
+    if (fields.length < MAX_FIELDS)
+      fields.push({ label, value: value.slice(0, MAX_VALUE) });
+  }
+  if (!fields.length && !links.length) {
+    const text = htmlToText(source);
+    if (text) fields.push({ label: '', value: text.slice(0, MAX_VALUE) });
+    addLinks(source);
+  }
+  return { fields, links: links.slice(0, MAX_LINKS) };
+}
+
+/**
+ * KML `aabbggrr` to `[r, g, b, a]` in 0..1, or null.
+ * @param {string} text
+ * @returns {?number[]}
+ */
+export function kmlColor(text) {
+  const hex = String(text ?? '')
+    .trim()
+    .replace(/^#/, '');
+  if (!/^[0-9a-f]{8}$/i.test(hex)) return null;
+  const byte = (at) => parseInt(hex.slice(at, at + 2), 16) / 255;
+  return [byte(6), byte(4), byte(2), byte(0)];
+}
+
+/**
+ * Greedy word wrap for canvas card lines; overlong words are cut.
+ * @param {string} text
+ * @param {number} width Characters per line.
+ * @param {number} maxLines Lines kept; the last ends with an ellipsis when cut.
+ * @returns {string[]}
+ */
+export function wrapCardText(text, width = 56, maxLines = 4) {
+  const lines = [];
+  let line = '';
+  let cut = false;
+  for (let word of String(text ?? '')
+    .split(/\s+/)
+    .filter(Boolean)) {
+    while (word.length > width) {
+      if (line) {
+        lines.push(line);
+        line = '';
+      }
+      lines.push(word.slice(0, width));
+      word = word.slice(width);
+    }
+    if (!line) line = word;
+    else if (line.length + 1 + word.length <= width) line += ` ${word}`;
+    else {
+      lines.push(line);
+      line = word;
+    }
+    if (lines.length >= maxLines) {
+      cut = true;
+      break;
+    }
+  }
+  if (line && lines.length < maxLines) lines.push(line);
+  else if (line) cut = true;
+  const kept = lines.slice(0, maxLines);
+  if (cut && kept.length) {
+    const last = kept[kept.length - 1];
+    kept[kept.length - 1] = `${last.slice(0, width - 1)}…`;
+  }
+  return kept;
+}
+
+/** Field labels ArcGIS writes CamelCase; show them as words. */
+export function fieldLabel(label) {
+  return String(label ?? '')
+    .replace(/([a-z])([A-Z0-9])/g, '$1 $2')
+    .replace(/_/g, ' ')
+    .trim();
+}

src/layers/ghostMaps/records.test.mjs

@@ -0,0 +1,106 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  decodeHtmlEntities,
+  fieldLabel,
+  htmlToText,
+  kmlColor,
+  parseDescriptionFields,
+  wrapCardText,
+} from './records.js';
+
+// The shape ArcGIS Pro writes into every S2 placemark description.
+const ARCGIS = `<html xmlns:fo="http://www.w3.org/1999/XSL/Format"><head>
+<META http-equiv="Content-Type" content="text/html"></head>
+<body style="margin:0px"><table style="font-family:Arial">
+<tr style="text-align:center;font-weight:bold;background:#9CBCE2"><td>HistoricProtestSite</td></tr>
+<tr><td><table style="font-family:Arial">
+<tr><td>SHAPE</td><td>Point</td></tr>
+<tr bgcolor="#D4E4F3"><td>InstallationType</td><td>HistoricProtestSite</td></tr>
+<tr><td>OperationalStatus</td><td>ACTIVE</td></tr>
+<tr bgcolor="#D4E4F3"><td>Affiliation</td><td>&lt;Null&gt;</td></tr>
+<tr><td>Description</td><td>Locals gather here &amp; protest &#8212; weekly.</td></tr>
+<tr><td>Research1</td><td><a target="_blank" href="https://x.com/a/status/1">https://x.com/a/status/1</a></td></tr>
+<tr><td>Research2</td><td><a href="javascript:alert(1)">bad</a></td></tr>
+<tr><td>Research3</td><td>&lt;Null&gt;</td></tr>
+</table></td></tr></table></body><script type="text/javascript">
+function changeImage(a, b) { document.getElementById('x').innerHTML = b; }
+</script></html>`;
+
+test('ArcGIS popup tables become plain label/value fields and http links', () => {
+  const { fields, links } = parseDescriptionFields(ARCGIS);
+  assert.deepEqual(fields, [
+    { label: 'InstallationType', value: 'HistoricProtestSite' },
+    { label: 'OperationalStatus', value: 'ACTIVE' },
+    { label: 'Description', value: 'Locals gather here & protest — weekly.' },
+    { label: 'Research2', value: 'bad' },
+  ]);
+  // javascript: and other schemes never become links.
+  assert.deepEqual(links, ['https://x.com/a/status/1']);
+});
+
+test('free-form descriptions become one unlabelled field; scripts are dropped', () => {
+  assert.deepEqual(
+    parseDescriptionFields(
+      '<p>Front line<br>as of 10 Oct</p><script>steal()</script><a href="https://s2.example/x">more</a>',
+    ),
+    {
+      fields: [{ label: '', value: 'Front line as of 10 Oct more' }],
+      links: ['https://s2.example/x'],
+    },
+  );
+  assert.deepEqual(parseDescriptionFields(''), { fields: [], links: [] });
+  assert.deepEqual(parseDescriptionFields(undefined), {
+    fields: [],
+    links: [],
+  });
+});
+
+test('field values and counts are bounded', () => {
+  const rows = Array.from(
+    { length: 40 },
+    (_, i) => `<tr><td>K${i}</td><td>${'x'.repeat(900)}</td></tr>`,
+  ).join('');
+  const { fields } = parseDescriptionFields(`<table>${rows}</table>`);
+  assert.equal(fields.length, 24);
+  assert.equal(fields[0].value.length, 600);
+});
+
+test('entities and tags decode to text', () => {
+  assert.equal(
+    decodeHtmlEntities('&lt;b&gt; &#x41;&#66; &nbsp;&bogus;'),
+    '<b> AB  &bogus;',
+  );
+  assert.equal(decodeHtmlEntities('&#xD800;&#0;'), '');
+  assert.equal(htmlToText('<style>a{}</style><b>One</b>\n two'), 'One two');
+});
+
+test('KML aabbggrr colors convert to rgba', () => {
+  assert.deepEqual(kmlColor('ff0000ff'), [1, 0, 0, 1]);
+  assert.deepEqual(kmlColor('8000ff00'), [0, 1, 0, 128 / 255]);
+  assert.equal(kmlColor('red'), null);
+  assert.equal(kmlColor(''), null);
+});
+
+test('card text wraps on words, cuts long words and marks truncation', () => {
+  assert.deepEqual(wrapCardText('one two three four', 9, 4), [
+    'one two',
+    'three',
+    'four',
+  ]);
+  assert.deepEqual(wrapCardText('abcdefghijkl', 5, 4), [
+    'abcde',
+    'fghij',
+    'kl',
+  ]);
+  assert.deepEqual(wrapCardText('aa bb cc dd ee', 5, 2), ['aa bb', 'cc d…']);
+  assert.deepEqual(wrapCardText('', 5, 2), []);
+  for (const line of wrapCardText('word '.repeat(200), 20, 3))
+    assert.ok(line.length <= 20);
+});
+
+test('CamelCase field labels read as words', () => {
+  assert.equal(fieldLabel('OperationalStatus'), 'Operational Status');
+  assert.equal(fieldLabel('Research1'), 'Research 1');
+  assert.equal(fieldLabel('Kinetic_Activity'), 'Kinetic Activity');
+});

src/layers/ghostMaps/source.js

@@ -0,0 +1,81 @@
+import {
+  readResponseBytesCapped,
+  readResponseJsonCapped,
+} from '../../sources/httpBody.js';
+import { GHOSTMAPS_MAX_FILE_BYTES } from './catalog.js';
+
+// A portable export (package.json): no i18n here. Failures stay English data;
+// the Layers panel shows them translated.
+const msg = (text) => text;
+
+/**
+ * Same-origin GhostMaps source: the catalog, one product's KMZ bytes, and a
+ * push subscription that fires whenever the watcher sees a new commit.
+ */
+export function createGhostMapsSource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  EventSourceImpl = globalThis.EventSource,
+} = {}) {
+  return {
+    async getCatalog({ signal } = {}) {
+      const response = await fetchImpl('/api/ghostmaps/catalog', { signal });
+      if (!response.ok)
+        throw new Error(
+          `GhostMaps catalog unavailable (HTTP ${response.status})`,
+        );
+      const catalog = await readResponseJsonCapped(
+        response,
+        1024 * 1024,
+        signal,
+      );
+      if (!Array.isArray(catalog?.products))
+        throw new Error(msg('Malformed GhostMaps catalog'));
+      return catalog;
+    },
+
+    async getFile(id, version, { signal } = {}) {
+      const response = await fetchImpl(
+        `/api/ghostmaps/file/${encodeURIComponent(id)}?v=${encodeURIComponent(version)}`,
+        { signal },
+      );
+      if (!response.ok)
+        throw new Error(`GhostMaps file unavailable (HTTP ${response.status})`);
+      return readResponseBytesCapped(
+        response,
+        GHOSTMAPS_MAX_FILE_BYTES,
+        signal,
+      );
+    },
+
+    /**
+     * Call `onCatalog(catalog)` for every catalog the server pushes, and
+     * `onState('open' | 'connecting' | 'closed')` as the stream changes. The
+     * browser's EventSource reconnects by itself. Returns an unsubscribe.
+     */
+    subscribe(onCatalog, onState = () => {}) {
+      if (typeof EventSourceImpl !== 'function') {
+        onState('closed');
+        return () => {};
+      }
+      const events = new EventSourceImpl('/api/ghostmaps/events');
+      const states = ['connecting', 'open', 'closed'];
+      const report = () => onState(states[events.readyState] ?? 'connecting');
+      events.onopen = report;
+      events.onerror = report;
+      const listener = (event) => {
+        try {
+          const catalog = JSON.parse(event.data);
+          if (Array.isArray(catalog?.products)) onCatalog(catalog);
+        } catch {
+          /* ignore a malformed frame; the next one replaces it */
+        }
+      };
+      events.addEventListener('catalog', listener);
+      report();
+      return () => {
+        events.removeEventListener('catalog', listener);
+        events.close();
+      };
+    },
+  };
+}

src/layers/gnss/index.js

@@ -0,0 +1,435 @@
+import * as Cesium from 'cesium';
+import { formatNumber, msg, t } from '../../i18n/index.js';
+import { translateFeedError } from '../../ui/statusText.js';
+import {
+  GNSS_LEVEL_COLORS,
+  GNSS_MIN_AIRCRAFT,
+  GNSS_WINDOW_MS,
+  accumulateGnssObservations,
+  binGnssCells,
+  gnssProvenance,
+  pruneGnssObservations,
+} from './records.js';
+export * from './records.js';
+export { createAdsbGnssSource } from './source.js';
+
+/**
+ * GroundPrimitive allowPicking:false suppresses ids but still submits stencil
+ * commands in Cesium's pick pass, erasing picks of overlapping ground geometry.
+ * This fill participates only in rendering, so sibling polygons remain pickable.
+ */
+class GnssGroundFill extends Cesium.GroundPrimitive {
+  update(frameState) {
+    if (!frameState.passes.pick) super.update(frameState);
+  }
+}
+
+/** Low stays visible over land so coverage reads apart from no data. */
+const FILL_ALPHA = Object.freeze({ low: 0.3, medium: 0.42, high: 0.55 });
+const LEVEL_LABELS = Object.freeze({
+  low: msg('Low-accuracy score < 2%'),
+  medium: msg('Low-accuracy score 2–10%'),
+  high: msg('Low-accuracy score > 10%'),
+});
+
+/** Degrees at the centre of the current view, or null before the camera settles. */
+export function defaultGnssViewAnchor(viewer) {
+  const canvas = viewer?.scene?.canvas;
+  const ellipsoid = viewer?.scene?.globe?.ellipsoid;
+  // At globe scale the visible rectangle can be the whole world, whose
+  // midpoint is unrelated to the place under the screen centre.
+  const centre =
+    canvas?.clientWidth > 0 &&
+    canvas.clientHeight > 0 &&
+    viewer.camera?.pickEllipsoid?.(
+      new Cesium.Cartesian2(canvas.clientWidth / 2, canvas.clientHeight / 2),
+      ellipsoid,
+    );
+  const rectangle =
+    !centre && viewer?.camera?.computeViewRectangle?.(ellipsoid);
+  const carto = centre
+    ? (ellipsoid || Cesium.Ellipsoid.WGS84).cartesianToCartographic(centre)
+    : rectangle
+      ? Cesium.Rectangle.center(rectangle)
+      : viewer?.camera?.positionCartographic;
+  if (!carto) return null;
+  const latitude = Cesium.Math.toDegrees(carto.latitude);
+  const longitude = Cesium.Math.toDegrees(carto.longitude);
+  return Number.isFinite(latitude) && Number.isFinite(longitude)
+    ? { latitude, longitude }
+    : null;
+}
+
+/**
+ * Own one GNSS navigation-integrity display: rolling integrity observations
+ * around the views the user visits, binned into cells coloured by the
+ * gpsjam low-accuracy score. Share links retain token 3.
+ */
+export function createGnssIntegrityLayer({
+  source,
+  viewAnchor = defaultGnssViewAnchor,
+  now = () => Date.now(),
+  monotonicNow = () => performance.now(),
+  windowMs = GNSS_WINDOW_MS,
+} = {}) {
+  if (typeof source?.getSnapshot !== 'function')
+    throw new TypeError('GNSS integrity layer requires a snapshot source');
+  let _viewer = null;
+  let _primitives = null;
+  let _request = null;
+  let _enabled = false;
+  let _cells = [];
+  let _signature = null;
+  let _lastUpdate = null;
+  let _lastError = null;
+  let _stale = false;
+  let _manager = null;
+  let _cameraTimer = null;
+  let _backgroundRefresh = null;
+  let _lastQueryKey = null;
+  let _lastRequestAt = -Infinity;
+  let _removeCameraEnd = null;
+  let _removeCameraChanged = null;
+  let _coverage = null;
+  let _retryTimer = null;
+  let _retryAt = 0;
+  let _failureCount = 0;
+  const _observations = new Map();
+  const provenance = gnssProvenance({ windowMs });
+
+  const queryKey = (anchor) =>
+    anchor
+      ? `${Math.round(anchor.latitude)},${Math.round(anchor.longitude)}`
+      : null;
+
+  function scheduleCameraRefresh() {
+    if (!_enabled || !_primitives) return;
+    if (now() < _retryAt) return;
+    const key = queryKey(viewAnchor(_viewer));
+    if (!key || key === _lastQueryKey) return;
+    clearTimeout(_cameraTimer);
+    // Debounce drags and bound moving/follow cameras to at most 24 requests
+    // per minute. Nearby views share the proxy's whole-degree cache key.
+    _cameraTimer = setTimeout(
+      async () => {
+        _cameraTimer = null;
+        if (!_enabled || _backgroundRefresh || _request) return;
+        const key = queryKey(viewAnchor(_viewer));
+        if (!key || key === _lastQueryKey) return;
+        await refreshInBackground();
+      },
+      Math.max(600, 2500 - (monotonicNow() - _lastRequestAt)),
+    );
+  }
+
+  async function refreshInBackground() {
+    if (!_enabled || _backgroundRefresh) return;
+    const controller = new AbortController();
+    _backgroundRefresh = controller;
+    try {
+      if (_manager)
+        await _manager.refreshLayer(layer.id, { signal: controller.signal });
+      else await layer.update(undefined, { signal: controller.signal });
+    } finally {
+      if (_backgroundRefresh === controller) {
+        _backgroundRefresh = null;
+        scheduleCameraRefresh();
+        scheduleRetry();
+      }
+    }
+  }
+
+  function scheduleRetry() {
+    clearTimeout(_retryTimer);
+    _retryTimer = null;
+    if (!_enabled || !_retryAt) return;
+    // Long provider cooldowns keep their full deadline. Browser timers cannot
+    // exceed ~24 days, so wake in bounded chunks without fetching early.
+    _retryTimer = setTimeout(
+      () => {
+        _retryTimer = null;
+        void refreshInBackground();
+      },
+      Math.min(2147483647, Math.max(0, _retryAt - now())),
+    );
+    _retryTimer?.unref?.();
+  }
+
+  /** Age the store without new evidence, so expired cells leave the globe. */
+  function expire() {
+    pruneGnssObservations(_observations, now(), { windowMs });
+    _cells = binGnssCells(_observations);
+    render();
+  }
+
+  function render() {
+    // Only the id and band change what is drawn; counts alone do not.
+    const signature = JSON.stringify(
+      _cells.map(({ id, level }) => [id, level]),
+    );
+    if (signature === _signature) return;
+    _signature = signature;
+    _primitives.removeAll();
+    if (_cells.length) {
+      _primitives.add(
+        new GnssGroundFill({
+          geometryInstances: _cells.map(
+            (cell) =>
+              new Cesium.GeometryInstance({
+                id: `${layer.id}:${cell.id}`,
+                geometry: new Cesium.RectangleGeometry({
+                  rectangle: Cesium.Rectangle.fromDegrees(
+                    cell.west,
+                    cell.south,
+                    cell.east,
+                    cell.north,
+                  ),
+                  vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT,
+                }),
+                attributes: {
+                  color: Cesium.ColorGeometryInstanceAttribute.fromColor(
+                    Cesium.Color.fromCssColorString(
+                      GNSS_LEVEL_COLORS[cell.level],
+                    ).withAlpha(FILL_ALPHA[cell.level]),
+                  ),
+                },
+              }),
+          ),
+          appearance: new Cesium.PerInstanceColorAppearance({
+            flat: true,
+            translucent: true,
+          }),
+          classificationType: Cesium.ClassificationType.BOTH,
+          allowPicking: false,
+          // Retain the compact rectangle descriptors for inspection, not Entity visualizers.
+          releaseGeometryInstances: false,
+        }),
+      );
+    }
+    _viewer?.scene?.requestRender?.();
+  }
+
+  const layer = {
+    id: 'gnss-integrity',
+    name: 'GNSS Integrity',
+    icon: '📡',
+    source: 'adsb.lol',
+    /** Where each part of the method comes from; see records.js. */
+    provenance,
+    updateInterval: 60000,
+
+    attachDataManager(manager) {
+      _manager = manager;
+    },
+
+    init(viewer) {
+      if (_viewer)
+        throw new Error('GNSS integrity layer is already initialized');
+      _viewer = viewer;
+      _primitives = new Cesium.PrimitiveCollection();
+      _primitives.id = layer.id;
+      _primitives.show = false;
+      viewer.scene.groundPrimitives.add(_primitives);
+      _removeCameraEnd = viewer.camera?.moveEnd?.addEventListener(
+        scheduleCameraRefresh,
+      );
+      _removeCameraChanged = viewer.camera?.changed?.addEventListener(
+        scheduleCameraRefresh,
+      );
+    },
+
+    enable() {
+      _enabled = true;
+      // Cells left from before a long disable must not reappear past the window.
+      if (_primitives) {
+        expire();
+        _primitives.show = true;
+      }
+    },
+
+    disable() {
+      clearTimeout(_cameraTimer);
+      _cameraTimer = null;
+      clearTimeout(_retryTimer);
+      _retryTimer = null;
+      _backgroundRefresh?.abort();
+      _backgroundRefresh = null;
+      _request?.abort();
+      _request = null;
+      _enabled = false;
+      if (_primitives) _primitives.show = false;
+    },
+
+    async update(_viewerArg, { signal } = {}) {
+      if (!_enabled || !_primitives || signal?.aborted) return false;
+      if (now() < _retryAt) {
+        expire();
+        scheduleRetry();
+        return true;
+      }
+      _retryAt = 0;
+      clearTimeout(_retryTimer);
+      _retryTimer = null;
+      const anchor = viewAnchor(_viewer);
+      // No anchor yet (camera still settling) is not a failure: returning
+      // false would make the manager reject the enable. The next interval
+      // retries; cells already drawn still age out of the window.
+      if (!anchor) {
+        expire();
+        return true;
+      }
+      _request?.abort();
+      const request = new AbortController();
+      _request = request;
+      const onAbort = () => request.abort(signal.reason);
+      signal?.addEventListener('abort', onAbort, { once: true });
+      _lastQueryKey = queryKey(anchor);
+      _lastRequestAt = monotonicNow();
+      _coverage = {
+        kind: 'regional',
+        latitude: Math.round(anchor.latitude),
+        longitude: Math.round(anchor.longitude),
+        radiusNm: 250,
+      };
+      let received = false;
+      try {
+        const snapshot = await source.getSnapshot(anchor, {
+          signal: request.signal,
+        });
+        if (request.signal.aborted || _request !== request || !_enabled)
+          return false;
+        received = true;
+        // Date the rows by when the proxy observed them: a cached or stale
+        // replay keeps its original age instead of restarting the window.
+        // The proxy reports that age, so client and server clocks never mix.
+        const at = now();
+        accumulateGnssObservations(_observations, snapshot.rows, at, {
+          windowMs,
+          observedAt: at - snapshot.ageMs,
+        });
+        _cells = binGnssCells(_observations);
+        render();
+        _stale = snapshot.stale === true;
+        _lastUpdate = at - snapshot.ageMs;
+        _lastError = null;
+        _retryAt = 0;
+        _failureCount = 0;
+        return true;
+      } catch (e) {
+        if (request.signal.aborted || _request !== request || !_enabled)
+          return false;
+        // A renderer/programming failure remains a real lifecycle failure.
+        // Only acquisition failures are kept enabled for recovery.
+        if (received) throw e;
+        console.warn('[Data:GNSS] Fetch error:', e);
+        _lastError = e?.message || msg('GNSS integrity source unavailable');
+        // Keep the last cells only while their evidence is inside the window.
+        expire();
+        if (e?.retryable === false) return false;
+        _failureCount = Math.min(3, _failureCount + 1);
+        const delay =
+          Number.isFinite(e?.retryAfterMs) && e.retryAfterMs > 0
+            ? e.retryAfterMs
+            : Math.min(120000, 30000 * 2 ** (_failureCount - 1));
+        _retryAt = Math.max(
+          _retryAt,
+          Math.min(Number.MAX_VALUE, now() + delay),
+        );
+        // Enabling the display succeeded. Stats still report an unavailable
+        // or degraded feed; the manager keeps its normal refresh failure lane.
+        return true;
+      } finally {
+        signal?.removeEventListener('abort', onAbort);
+        if (_request === request) _request = null;
+        scheduleCameraRefresh();
+        scheduleRetry();
+      }
+    },
+
+    destroy(viewer = _viewer) {
+      layer.disable();
+      _removeCameraEnd?.();
+      _removeCameraChanged?.();
+      _removeCameraEnd = null;
+      _removeCameraChanged = null;
+      _observations.clear();
+      _cells = [];
+      _signature = null;
+      if (_primitives) {
+        viewer.scene.groundPrimitives.remove(_primitives);
+        _primitives = null;
+      }
+      _viewer = null;
+      _lastUpdate = null;
+      _lastError = null;
+      _stale = false;
+      _coverage = null;
+      _retryAt = 0;
+      _failureCount = 0;
+      _lastQueryKey = null;
+      _manager = null;
+    },
+
+    getRowControls() {
+      return {
+        chips: [],
+        info:
+          t(
+            'Regional sample · 250 nm radius · cells from visited views over 30 min',
+          ) +
+          (_lastError && _retryAt
+            ? ` · ${translateFeedError(_lastError)} · ${
+                _retryAt <= 8640000000000000
+                  ? t('Retrying automatically at {time} UTC', {
+                      time: new Date(_retryAt).toISOString().slice(11, 19),
+                    })
+                  : t('Retrying automatically after provider cooldown')
+              }`
+            : ''),
+        infoTitle: t(
+          'Updates automatically after pan or zoom and once a minute. The public feed covers a 250-nautical-mile circle around the view centre; zooming out does not make it a worldwide snapshot. Blank cells are outside sampled coverage or have insufficient observations.',
+        ),
+        legend: ['high', 'medium', 'low'].map((level, index) => ({
+          label: t(LEVEL_LABELS[level]),
+          color: GNSS_LEVEL_COLORS[level],
+          count: _cells.filter((cell) => cell.level === level).length,
+          ...(index === 0
+            ? {
+                blurb: t(
+                  'Low-accuracy score = 100 × max(0, bad − 1) / total: one aircraft is discounted, so this is not the raw share. Cells need {aircraft} aircraft over {minutes} minutes. Navigation-integrity anomalies are not a detection of jamming or spoofing.',
+                  {
+                    aircraft: formatNumber(GNSS_MIN_AIRCRAFT),
+                    minutes: formatNumber(provenance.window.minutes),
+                  },
+                ),
+              }
+            : {}),
+        })),
+      };
+    },
+
+    getStats() {
+      return {
+        count: _cells.length,
+        levels: Object.fromEntries(
+          ['low', 'medium', 'high'].map((level) => [
+            level,
+            _cells.filter((cell) => cell.level === level).length,
+          ]),
+        ),
+        lastUpdate: _lastUpdate,
+        error: _lastError,
+        retryInSec: _retryAt
+          ? Math.max(0, Math.ceil((_retryAt - now()) / 1000))
+          : null,
+        stale: _stale,
+        provenance,
+        coverage: _coverage,
+        // Load-bearing: without an explicit boolean, layerFeedState reads the
+        // adsb.lol source name as a flights fallback (src/data/feedState.js).
+        fallback: false,
+      };
+    },
+  };
+  return layer;
+}

src/layers/gnss/ownership.test.mjs

@@ -0,0 +1,700 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { createGnssIntegrityLayer, defaultGnssViewAnchor } from './index.js';
+import { LayerLifecycle } from '../../data/lifecycle.js';
+import { layerFeedState } from '../../data/feedState.js';
+
+const row = (hex, lat, degraded) => ({
+  hex,
+  lat,
+  lon: 30.2,
+  nic: degraded ? 0 : 8,
+  nacp: degraded ? 0 : 10,
+  gpsLost: false,
+  degraded,
+});
+
+function harness(
+  getSnapshot,
+  {
+    anchor: initialAnchor = { latitude: 50, longitude: 30 },
+    initialize = true,
+  } = {},
+) {
+  let anchor = initialAnchor;
+  const sources = [];
+  const viewer = {
+    camera: { moveEnd: new Cesium.Event(), changed: new Cesium.Event() },
+    scene: {
+      globe: { show: true },
+      groundPrimitives: {
+        add(value) {
+          sources.push(value);
+        },
+        remove(value) {
+          sources.splice(sources.indexOf(value), 1);
+          value.destroy();
+        },
+      },
+    },
+  };
+  let clock = 1_000;
+  const anchors = [];
+  const layer = createGnssIntegrityLayer({
+    // The real source refuses an undated snapshot; stubs default to a fresh one.
+    source: {
+      async getSnapshot(...args) {
+        const snapshot = await getSnapshot(...args);
+        return { ageMs: 0, ...snapshot };
+      },
+    },
+    viewAnchor: () => {
+      anchors.push(anchor);
+      return anchor;
+    },
+    now: () => clock,
+    monotonicNow: () => clock,
+  });
+  if (initialize) layer.init(viewer);
+  return {
+    layer,
+    sources,
+    anchors,
+    viewer,
+    advance(ms) {
+      clock += ms;
+    },
+    now: () => clock,
+    setAnchor(value) {
+      anchor = value;
+    },
+  };
+}
+
+const MIN = 60_000;
+const threeHealthy = () => [
+  row('a1', 1.1, false),
+  row('a2', 1.2, false),
+  row('a3', 1.3, false),
+];
+
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+test('a globe-wide rectangle uses the visible screen centre as the query anchor', () => {
+  const anchor = defaultGnssViewAnchor({
+    scene: {
+      canvas: { clientWidth: 1000, clientHeight: 800 },
+      globe: { ellipsoid: Cesium.Ellipsoid.WGS84 },
+    },
+    camera: {
+      pickEllipsoid(pixel) {
+        assert.deepEqual(pixel, new Cesium.Cartesian2(500, 400));
+        return Cesium.Cartesian3.fromDegrees(-97, 30);
+      },
+      computeViewRectangle: () => {
+        throw new Error('centre hit must not compute a rectangle');
+      },
+    },
+  });
+  assert.ok(Math.abs(anchor.latitude - 30) < 1e-8);
+  assert.ok(Math.abs(anchor.longitude + 97) < 1e-8);
+});
+
+test('pan and zoom refresh through the manager without toggling; nearby changes are coalesced', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout', 'setInterval'] });
+  let calls = 0;
+  const h = harness(
+    async () => {
+      calls++;
+      return { rows: threeHealthy() };
+    },
+    { initialize: false },
+  );
+  const manager = new LayerLifecycle(h.viewer);
+  manager.register(h.layer);
+  h.layer.attachDataManager(manager);
+  const changes = [];
+  manager.subscribe((change) => changes.push(change.type));
+  await manager.setEnabled(h.layer.id, true);
+  h.setAnchor({ latitude: 54, longitude: 19 });
+  h.viewer.camera.changed.raiseEvent();
+  h.setAnchor({ latitude: 55, longitude: 20 });
+  h.viewer.camera.moveEnd.raiseEvent();
+  h.advance(2500);
+  t.mock.timers.tick(2500);
+  await flush();
+  assert.equal(calls, 2, 'one initial read and one read for the latest view');
+  assert.deepEqual(h.anchors.at(-1), { latitude: 55, longitude: 20 });
+  assert.ok(changes.includes('refresh-transition'));
+  assert.ok(changes.includes('refresh'));
+  assert.equal(manager.isEnabled(h.layer.id), true);
+  assert.deepEqual(h.layer.getStats().coverage, {
+    kind: 'regional',
+    latitude: 55,
+    longitude: 20,
+    radiusNm: 250,
+  });
+  assert.match(h.layer.getRowControls().info, /Regional sample.*250 nm radius/);
+  h.setAnchor({ latitude: 55.1, longitude: 20.1 });
+  h.viewer.camera.changed.raiseEvent();
+  h.advance(5000);
+  t.mock.timers.tick(5000);
+  await flush();
+  assert.equal(calls, 2, 'nearby views reuse the same query region');
+  await manager.destroyAll();
+  assert.equal(h.viewer.camera.moveEnd.numberOfListeners, 0);
+  assert.equal(h.viewer.camera.changed.numberOfListeners, 0);
+});
+
+test('movement during a pending refresh follows up at the newest view; disable cancels queued work', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const calls = [];
+  let resolvePending;
+  const h = harness((anchor) => {
+    calls.push(anchor);
+    if (calls.length === 2)
+      return new Promise((resolve) => {
+        resolvePending = resolve;
+      });
+    return { rows: threeHealthy() };
+  });
+  h.layer.enable();
+  await h.layer.update();
+  h.setAnchor({ latitude: 54, longitude: 19 });
+  h.viewer.camera.moveEnd.raiseEvent();
+  h.advance(2500);
+  t.mock.timers.tick(2500);
+  await flush();
+  h.setAnchor({ latitude: 35, longitude: 140 });
+  h.viewer.camera.changed.raiseEvent();
+  h.advance(2500);
+  t.mock.timers.tick(2500);
+  await flush();
+  assert.equal(calls.length, 2, 'only one camera request in flight');
+  resolvePending({ rows: threeHealthy() });
+  await flush();
+  h.advance(600);
+  t.mock.timers.tick(600);
+  await flush();
+  assert.equal(calls.length, 3);
+  assert.deepEqual(calls.at(-1), { latitude: 35, longitude: 140 });
+  h.setAnchor({ latitude: 10, longitude: 10 });
+  h.viewer.camera.moveEnd.raiseEvent();
+  h.layer.disable();
+  h.advance(5000);
+  t.mock.timers.tick(5000);
+  await flush();
+  assert.equal(calls.length, 3, 'disable drains the camera timer');
+  h.layer.destroy();
+});
+
+test('the layer requires a snapshot source and cannot be initialized twice', () => {
+  assert.throws(() => createGnssIntegrityLayer({}), TypeError);
+  const { layer } = harness(async () => ({ rows: [] }));
+  assert.throws(() => layer.init({ dataSources: { add() {} } }), /already/);
+});
+
+test('an enabled refresh bins the snapshot into coloured ground cells', async () => {
+  const { layer, sources, anchors } = harness(async (anchor, { signal }) => {
+    assert.deepEqual(anchor, { latitude: 50, longitude: 30 });
+    assert.ok(signal instanceof AbortSignal);
+    return {
+      rows: [
+        row('a1', 50.1, true),
+        row('a2', 50.1, true),
+        row('a3', 50.2, false),
+        row('a4', 50.3, false),
+        row('b1', 55.1, false),
+      ],
+      stale: false,
+    };
+  });
+  assert.equal(await layer.update(), false, 'disabled layers do not fetch');
+  assert.equal(anchors.length, 0);
+  layer.enable();
+  assert.equal(sources[0].show, true);
+  assert.equal(await layer.update(), true);
+  const entities = sources[0].get(0).geometryInstances;
+  assert.equal(entities.length, 1, 'the one-aircraft cell is withheld');
+  assert.equal(entities[0].id, 'gnss-integrity:280:420');
+  assert.ok(entities[0].geometry instanceof Cesium.RectangleGeometry);
+  assert.equal(sources[0].get(0).allowPicking, false);
+  const stats = layer.getStats();
+  assert.equal(stats.count, 1);
+  assert.equal(stats.error, null);
+  assert.equal(stats.fallback, false);
+  const { legend } = layer.getRowControls();
+  assert.deepEqual(
+    legend.map(({ count }) => count),
+    [1, 0, 0],
+  );
+  assert.match(legend[0].blurb, /not a detection/);
+  assert.match(legend[0].blurb, /need 3 aircraft/);
+});
+
+test('the visible layer leads with low navigation accuracy and exposes its provenance', async () => {
+  const { layer } = harness(async () => ({ rows: [], stale: false }));
+  assert.equal(
+    layer.id,
+    'gnss-integrity',
+    'the unpublished id describes the measured state',
+  );
+  assert.equal(layer.name, 'GNSS Integrity');
+  assert.doesNotMatch(layer.name, /interference|jamming/i);
+  const { legend } = layer.getRowControls();
+  assert.deepEqual(
+    legend.map(({ label }) => label),
+    [
+      'Low-accuracy score > 10%',
+      'Low-accuracy score 2–10%',
+      'Low-accuracy score < 2%',
+    ],
+  );
+  const { blurb } = legend[0];
+  assert.match(blurb, /one aircraft is discounted/);
+  assert.match(blurb, /not the raw share/);
+  assert.match(blurb, /not a detection/);
+  assert.equal(layer.provenance.classifier.id, 'gev-nic-nacp-v2');
+  assert.equal(layer.provenance.classifier.definedBy, 'GEV');
+  assert.equal(layer.provenance.classifier.validated, false);
+  assert.equal(layer.provenance.aggregation.source, 'https://gpsjam.org/faq');
+  assert.deepEqual(layer.provenance.window, {
+    minutes: 30,
+    scope: 'visited-view',
+    cellDeg: 0.5,
+    minAircraft: 3,
+    definedBy: 'GEV',
+  });
+  assert.equal(layer.provenance.interpretation.validated, false);
+  assert.equal(layer.getStats().provenance, layer.provenance);
+});
+
+test('a failed refresh keeps the last cells and reports the error', async () => {
+  let fail = false;
+  const { layer, sources } = harness(async () => {
+    if (fail) throw new Error('adsb.lol HTTP 502');
+    return {
+      rows: [
+        row('a1', 1.1, false),
+        row('a2', 1.2, false),
+        row('a3', 1.3, false),
+      ],
+      stale: true,
+    };
+  });
+  layer.enable();
+  await layer.update();
+  assert.equal(layer.getStats().stale, true);
+  fail = true;
+  assert.equal(await layer.update(), true);
+  assert.equal(sources[0].get(0)?.geometryInstances.length ?? 0, 1);
+  assert.equal(layer.getStats().error, 'adsb.lol HTTP 502');
+  assert.equal(layer.getStats().count, 1);
+});
+
+test('observations expire with the window, and disable aborts the request in flight', async () => {
+  let pending;
+  const { layer, sources, advance } = harness(
+    (anchor, { signal }) =>
+      new Promise((resolve, reject) => {
+        pending = { resolve };
+        signal.addEventListener('abort', () => reject(signal.reason));
+      }),
+  );
+  layer.enable();
+  let result = layer.update();
+  pending.resolve({
+    rows: [row('a1', 1.1, false), row('a2', 1.2, false), row('a3', 1.3, false)],
+  });
+  assert.equal(await result, true);
+  assert.equal(layer.getStats().count, 1);
+
+  advance(31 * 60_000);
+  result = layer.update();
+  pending.resolve({ rows: [] });
+  assert.equal(await result, true);
+  assert.equal(layer.getStats().count, 0);
+  assert.equal(sources[0].get(0)?.geometryInstances.length ?? 0, 0);
+
+  result = layer.update();
+  layer.disable();
+  assert.equal(await result, false);
+  assert.equal(sources[0].show, false);
+});
+
+test('no view anchor means no request, and destroy releases the data source', async () => {
+  let calls = 0;
+  const { layer, sources } = harness(
+    async () => {
+      calls += 1;
+      return { rows: [] };
+    },
+    { anchor: null },
+  );
+  layer.enable();
+  assert.equal(
+    await layer.update(),
+    true,
+    'a settling camera is not a failure',
+  );
+  assert.equal(calls, 0);
+  assert.equal(layer.getStats().error, null);
+  layer.destroy();
+  assert.equal(sources.length, 0);
+  assert.equal(layer.getStats().count, 0);
+});
+
+test('a replayed stale snapshot keeps its observation age and expires on time', async () => {
+  // The proxy keeps answering with the snapshot it observed at t=1000.
+  const { layer, sources, advance, now } = harness(async () => ({
+    rows: threeHealthy(),
+    ageMs: now() - 1_000,
+    stale: true,
+  }));
+  layer.enable();
+  assert.equal(await layer.update(), true);
+  assert.equal(layer.getStats().count, 1);
+  advance(29 * MIN);
+  assert.equal(await layer.update(), true);
+  assert.equal(layer.getStats().count, 1);
+  advance(2 * MIN);
+  assert.equal(
+    await layer.update(),
+    true,
+    'the replay is not an error, only no evidence',
+  );
+  assert.equal(
+    layer.getStats().count,
+    0,
+    'the replay did not restart the window',
+  );
+  assert.equal(sources[0].get(0)?.geometryInstances.length ?? 0, 0);
+});
+
+test('cells expire during prolonged fetch failures', async () => {
+  let fail = false;
+  const { layer, sources, advance } = harness(async () => {
+    if (fail) throw new Error('adsb.lol HTTP 502');
+    return { rows: threeHealthy() };
+  });
+  layer.enable();
+  await layer.update();
+  fail = true;
+  advance(20 * MIN);
+  assert.equal(await layer.update(), true);
+  assert.equal(layer.getStats().count, 1, 'still inside the window');
+  advance(11 * MIN);
+  assert.equal(await layer.update(), true);
+  assert.equal(layer.getStats().count, 0);
+  assert.equal(sources[0].get(0)?.geometryInstances.length ?? 0, 0);
+  assert.equal(layer.getStats().error, 'adsb.lol HTTP 502');
+});
+
+test('cells expire while no view anchor is available', async () => {
+  let calls = 0;
+  const { layer, sources, advance, setAnchor } = harness(async () => {
+    calls += 1;
+    return { rows: threeHealthy() };
+  });
+  layer.enable();
+  await layer.update();
+  setAnchor(null);
+  advance(20 * MIN);
+  assert.equal(await layer.update(), true);
+  assert.equal(layer.getStats().count, 1);
+  advance(11 * MIN);
+  assert.equal(await layer.update(), true);
+  assert.equal(calls, 1, 'no anchor means no request');
+  assert.equal(layer.getStats().count, 0);
+  assert.equal(sources[0].get(0)?.geometryInstances.length ?? 0, 0);
+  assert.equal(layer.getStats().error, null);
+});
+
+test('re-enabling after a long disable does not show cells past the window', async () => {
+  const { layer, sources, advance } = harness(async () => ({
+    rows: threeHealthy(),
+  }));
+  layer.enable();
+  await layer.update();
+  assert.equal(sources[0].get(0)?.geometryInstances.length ?? 0, 1);
+  layer.disable();
+  advance(31 * MIN);
+  layer.enable();
+  assert.equal(layer.getStats().count, 0);
+  assert.equal(sources[0].get(0)?.geometryInstances.length ?? 0, 0);
+});
+
+const threeCells = () => ({
+  rows: [row('a1', 50.1, true), row('a2', 50.1, true), row('a3', 50.2, false)],
+});
+
+test('an identical snapshot leaves the drawn entities untouched', async () => {
+  const { layer, sources } = harness(async () => threeCells());
+  layer.enable();
+  await layer.update();
+  const first = sources[0].get(0);
+  await layer.update();
+  assert.equal(sources[0].get(0)?.geometryInstances.length ?? 0, 1);
+  assert.equal(sources[0].get(0), first);
+});
+
+test('an initial feed failure stays enabled, reports unavailable, and recovers automatically', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout', 'setInterval'] });
+  let calls = 0;
+  const h = harness(
+    async () => {
+      calls++;
+      if (calls === 1) throw new Error('adsb.lol HTTP 502');
+      return { rows: threeHealthy() };
+    },
+    { initialize: false },
+  );
+  const manager = new LayerLifecycle(h.viewer);
+  manager.register(h.layer);
+  h.layer.attachDataManager(manager);
+  const changes = [];
+  manager.subscribe((c) => changes.push(c.type));
+  assert.equal(await manager.setEnabled(h.layer.id, true), true);
+  assert.equal(manager.isEnabled(h.layer.id), true);
+  assert.equal(layerFeedState(h.layer.getStats()), 'unavailable');
+  assert.equal(h.layer.getStats().retryInSec, 30);
+  assert.match(
+    h.layer.getRowControls().info,
+    /HTTP 502.*Retrying automatically at/,
+  );
+  assert.equal(changes.includes('visibility-failed'), false);
+  assert.equal(
+    await manager.refreshLayer(h.layer.id),
+    false,
+    'feed remains honestly unhealthy during cooldown',
+  );
+  assert.equal(calls, 1, 'a manual refresh cannot bypass cooldown');
+  h.advance(30000);
+  t.mock.timers.tick(30000);
+  await flush();
+  assert.equal(calls, 2);
+  assert.equal(manager.isEnabled(h.layer.id), true);
+  assert.equal(layerFeedState(h.layer.getStats()), 'nominal');
+  assert.equal(h.layer.getStats().count, 1);
+  assert.equal(h.layer.getStats().retryInSec, null);
+  assert.doesNotMatch(h.layer.getRowControls().info, /Retrying/);
+  await manager.destroyAll();
+});
+
+test('provider cooldown is preserved across movement and toggling; disable cancels retry work', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let calls = 0;
+  const h = harness(async () => {
+    calls++;
+    if (calls === 1)
+      throw Object.assign(new Error('Rate limited (HTTP 429)'), {
+        retryAfterMs: 3600000,
+      });
+    return { rows: threeHealthy() };
+  });
+  h.layer.enable();
+  await h.layer.update();
+  h.setAnchor({ latitude: 10, longitude: 20 });
+  h.viewer.camera.moveEnd.raiseEvent();
+  h.advance(30000);
+  t.mock.timers.tick(30000);
+  await flush();
+  await h.layer.update();
+  assert.equal(calls, 1);
+  assert.equal(h.layer.getStats().retryInSec, 3570);
+  h.layer.disable();
+  h.advance(30000);
+  t.mock.timers.tick(30000);
+  await flush();
+  h.layer.enable();
+  await h.layer.update();
+  assert.equal(calls, 1, 'reenabling does not erase a provider deadline');
+  h.advance(3540000);
+  t.mock.timers.tick(3540000);
+  await flush();
+  assert.equal(calls, 2);
+  assert.deepEqual(h.anchors.at(-1), { latitude: 10, longitude: 20 });
+  h.layer.destroy();
+
+  const stopped = harness(async () => {
+    throw new Error('network unavailable');
+  });
+  stopped.layer.enable();
+  await stopped.layer.update();
+  stopped.layer.disable();
+  stopped.advance(30000);
+  t.mock.timers.tick(30000);
+  await flush();
+  assert.equal(stopped.anchors.length, 1, 'disabled layers do not retry');
+  stopped.layer.destroy();
+});
+
+test('repeated acquisition failures back off, while genuine non-retryable failures reject startup', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let calls = 0;
+  const h = harness(async () => {
+    calls++;
+    throw new Error('network unavailable');
+  });
+  h.layer.enable();
+  await h.layer.update();
+  assert.equal(h.layer.getStats().retryInSec, 30);
+  h.advance(30000);
+  t.mock.timers.tick(30000);
+  await flush();
+  assert.equal(h.layer.getStats().retryInSec, 60);
+  h.advance(60000);
+  t.mock.timers.tick(60000);
+  await flush();
+  assert.equal(h.layer.getStats().retryInSec, 120);
+  assert.equal(calls, 3);
+  h.layer.destroy();
+  const fatal = harness(async () => {
+    throw Object.assign(new Error('invalid request (HTTP 400)'), {
+      retryable: false,
+    });
+  });
+  fatal.layer.enable();
+  assert.equal(await fatal.layer.update(), false);
+  assert.equal(fatal.layer.getStats().retryInSec, null);
+  fatal.layer.destroy();
+});
+
+test('GERMAN: stale snapshot keeps the source observation age in row stats', async () => {
+  const h = harness(async () => ({
+    rows: threeHealthy(),
+    ageMs: 120000,
+    stale: true,
+  }));
+  h.layer.enable();
+  await h.layer.update();
+  assert.equal(h.layer.getStats().lastUpdate, h.now() - 120000);
+  h.layer.destroy();
+});
+
+test('GERMAN: camera debounce and minimum request gap are pinned', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let calls = 0;
+  const h = harness(async () => {
+    calls++;
+    return { rows: [] };
+  });
+  h.layer.enable();
+  await h.layer.update();
+  h.setAnchor({ latitude: 51, longitude: 31 });
+  h.viewer.camera.changed.raiseEvent();
+  h.advance(2499);
+  t.mock.timers.tick(2499);
+  await flush();
+  assert.equal(calls, 1);
+  h.advance(1);
+  t.mock.timers.tick(1);
+  await flush();
+  assert.equal(calls, 2);
+  h.advance(3000);
+  h.setAnchor({ latitude: 52, longitude: 32 });
+  h.viewer.camera.changed.raiseEvent();
+  h.advance(599);
+  t.mock.timers.tick(599);
+  await flush();
+  assert.equal(calls, 2);
+  h.advance(1);
+  t.mock.timers.tick(1);
+  await flush();
+  assert.equal(calls, 3);
+  h.layer.destroy();
+});
+
+test('camera movement during initial activation waits for acquisition before following up', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const calls = [];
+  let resolve;
+  const h = harness((anchor) => {
+    calls.push(anchor);
+    return calls.length === 1
+      ? new Promise((r) => (resolve = r))
+      : Promise.resolve({ rows: threeHealthy() });
+  });
+  h.layer.enable();
+  const initial = h.layer.update();
+  h.setAnchor({ latitude: 51, longitude: 31 });
+  h.viewer.camera.changed.raiseEvent();
+  h.advance(2500);
+  t.mock.timers.tick(2500);
+  await flush();
+  assert.equal(calls.length, 1);
+  resolve({ rows: threeHealthy() });
+  assert.equal(await initial, true);
+  h.advance(600);
+  t.mock.timers.tick(600);
+  await flush();
+  assert.equal(calls.length, 2);
+  h.layer.destroy();
+});
+
+test('monotonic camera scheduling is unaffected by wall-clock rollback', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const h = harness(async () => ({ rows: [] }));
+  h.layer.destroy();
+  let wall = 1800000000000,
+    mono = 0,
+    anchor = { latitude: 50, longitude: 30 },
+    calls = 0;
+  const layer = createGnssIntegrityLayer({
+    source: {
+      getSnapshot: async () => {
+        calls++;
+        return { rows: [], ageMs: 0 };
+      },
+    },
+    viewAnchor: () => anchor,
+    now: () => wall,
+    monotonicNow: () => mono,
+  });
+  layer.init(h.viewer);
+  layer.enable();
+  await layer.update();
+  wall -= 3600000;
+  mono = 3000;
+  anchor = { latitude: 51, longitude: 31 };
+  h.viewer.camera.changed.raiseEvent();
+  mono += 600;
+  t.mock.timers.tick(600);
+  await flush();
+  assert.equal(calls, 2);
+  layer.destroy();
+});
+
+test('GNSS fill emits no pick-pass commands but keeps normal rendering', async (t) => {
+  const h = harness(async () => ({ rows: threeHealthy() }));
+  h.layer.enable();
+  await h.layer.update();
+  const fill = h.sources[0].get(0);
+  let updates = 0;
+  t.mock.method(Cesium.GroundPrimitive.prototype, 'update', () => updates++);
+  fill.update({ passes: { pick: true } });
+  assert.equal(updates, 0);
+  fill.update({ passes: { render: true, pick: false } });
+  assert.equal(updates, 1);
+  h.layer.destroy();
+  assert.equal(fill.isDestroyed(), true);
+});
+
+test('view anchor falls back to rectangle, then nadir, then no camera', () => {
+  assert.equal(defaultGnssViewAnchor({}), null);
+  const viewer = {
+    camera: {
+      computeViewRectangle: () => Cesium.Rectangle.fromDegrees(20, 40, 22, 42),
+    },
+  };
+  const rectangleAnchor = defaultGnssViewAnchor(viewer);
+  assert.ok(Math.abs(rectangleAnchor.latitude - 41) < 1e-10);
+  assert.ok(Math.abs(rectangleAnchor.longitude - 21) < 1e-10);
+  viewer.camera = {
+    positionCartographic: Cesium.Cartographic.fromDegrees(21, 41),
+  };
+  const nadirAnchor = defaultGnssViewAnchor(viewer);
+  assert.ok(Math.abs(nadirAnchor.latitude - 41) < 1e-10);
+  assert.ok(Math.abs(nadirAnchor.longitude - 21) < 1e-10);
+});

src/layers/gnss/records.js

@@ -0,0 +1,318 @@
+/**
+ * Low navigation accuracy reported by ADS-B aircraft, binned into cells.
+ *
+ * Aircraft broadcasting DO-260 version 1/2 ADS-B report how much they trust
+ * their own position: NIC (integrity containment radius) and NACp (position
+ * accuracy). A cluster of aircraft reporting low values in one area is a
+ * navigation-integrity anomaly. Jamming or spoofing is one common cause, so
+ * such clusters are a well-known public proxy for GNSS interference, but
+ * avionics faults and old transponders also report low values: suspected
+ * interference is a second, unvalidated interpretation, never the primary
+ * state.
+ *
+ * Three separately sourced parts make up the method (see `gnssProvenance`):
+ * - Per-aircraft classifier, defined by GEV: aircraft-reported NIC < 7
+ *   (except unknown NIC 0 with NACp >= 10) or NACp < 8 (borrowed
+ *   from the US 14 CFR 91.227(c) ADS-B Out performance minima, which are not
+ *   a published interference classifier) or the readsb/tar1090 `gpsOkBefore`
+ *   flag. gpsjam.org does not publish its per-aircraft threshold.
+ * - Cell aggregation: gpsjam.org's published formula and 2% / 10% bands.
+ * - Window: a GEV-defined rolling 30 minutes over the views the user visits.
+ */
+
+/** Position source can switch to MLAT after GPS loss; quality must remain aircraft-reported. */
+const QUALIFYING_TYPES = new Set(['adsb_icao', 'mlat']);
+/** Restrict to decoded DO-260A/B quality fields; readsb does not decode v3 quality as v3. */
+const QUALIFYING_VERSIONS = new Set([1, 2]);
+/** NIC below 7: containment radius of 0.2 NM or more (below the US 91.227 ADS-B Out minimum). GEV threshold. */
+export const GNSS_NIC_THRESHOLD = 7;
+/** NACp below 8: position uncertainty of 93 m or more (below the US 91.227 minimum). GEV threshold. */
+export const GNSS_NACP_THRESHOLD = 8;
+/** Positions older than this are not current evidence of the local sky. */
+const MAX_POSITION_AGE_S = 60;
+/** Cell edge in degrees: roughly 55 km north-south, similar in area to an H3 res-4 cell. */
+export const GNSS_CELL_DEG = 0.5;
+/** Hide sparse one- and two-aircraft cells; the aggregation separately discounts one bad report. */
+export const GNSS_MIN_AIRCRAFT = 3;
+/** Rolling window over which aircraft seen in a cell are counted. */
+export const GNSS_WINDOW_MS = 30 * 60_000;
+/** gpsjam.org band edges, in percent of aircraft (after discounting one). */
+export const GNSS_MEDIUM_PERCENT = 2;
+export const GNSS_HIGH_PERCENT = 10;
+
+/** Primary cell state: what the data shows (low navigation accuracy). */
+export const GNSS_ANOMALY_STATE = 'navigation-integrity-anomaly';
+export const GNSS_NOMINAL_STATE = 'nominal';
+/** Secondary, unvalidated reading of an anomaly cell. */
+export const GNSS_INTERPRETATION = 'suspected-gnss-interference';
+
+/** The per-aircraft rule; GEV-defined and not validated against known events. */
+export const GNSS_CLASSIFIER = Object.freeze({
+  id: 'gev-nic-nacp-v2',
+  rule: `gpsOkBefore set || aircraft-reported NACp < ${GNSS_NACP_THRESHOLD} || (aircraft-reported NIC < ${GNSS_NIC_THRESHOLD} && !(NIC === 0 && NACp >= 10))`,
+  basis: '14 CFR 91.227(c) ADS-B Out performance minima (US regulation)',
+  definedBy: 'GEV',
+  validated: false,
+});
+
+/**
+ * Machine-readable provenance of the cell output: which part of the method
+ * comes from where, and which parts are unvalidated.
+ *
+ * @param {{windowMs?: number}} [options] The window the layer actually uses.
+ */
+export function gnssProvenance({ windowMs = GNSS_WINDOW_MS } = {}) {
+  return Object.freeze({
+    classifier: GNSS_CLASSIFIER,
+    aggregation: Object.freeze({
+      id: 'gpsjam-cell-bands',
+      formula: '100 * max(0, bad - 1) / total',
+      bands: Object.freeze([GNSS_MEDIUM_PERCENT, GNSS_HIGH_PERCENT]),
+      source: 'https://gpsjam.org/faq',
+      definedBy: 'gpsjam.org',
+    }),
+    window: Object.freeze({
+      minutes: windowMs / 60_000,
+      scope: 'visited-view',
+      cellDeg: GNSS_CELL_DEG,
+      minAircraft: GNSS_MIN_AIRCRAFT,
+      definedBy: 'GEV',
+    }),
+    state: Object.freeze({
+      id: GNSS_ANOMALY_STATE,
+      meaning: 'low navigation accuracy reported by ADS-B aircraft',
+    }),
+    interpretation: Object.freeze({
+      id: GNSS_INTERPRETATION,
+      validated: false,
+      note: 'one possible cause of an anomaly cell; avionics faults also report low values',
+    }),
+  });
+}
+
+/** Provenance at the default window. */
+export const GNSS_PROVENANCE = gnssProvenance();
+
+const HEX_PATTERN = /^~?[0-9a-f]{6}$/;
+
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+
+/**
+ * Reduce one adsb.lol / readsb `aircraft.json`-style payload to the integrity
+ * facts the layer needs. Returns null when the payload has no aircraft array.
+ *
+ * @param {{ac?: object[], now?: number}} payload - readsb-style snapshot.
+ * @returns {{hex: string, lat: number, lon: number, nic: number|null, nacp: number|null, gpsLost: boolean, degraded: boolean}[]|null}
+ */
+export function normalizeGnssAircraft(payload) {
+  if (!Array.isArray(payload?.ac)) return null;
+  const rows = [];
+  const seen = new Set();
+  for (const aircraft of payload.ac) {
+    if (!aircraft || typeof aircraft !== 'object') continue;
+    const hex = typeof aircraft.hex === 'string' ? aircraft.hex : '';
+    if (!HEX_PATTERN.test(hex) || seen.has(hex)) continue;
+    if (!QUALIFYING_TYPES.has(aircraft.type)) continue;
+    if (!QUALIFYING_VERSIONS.has(aircraft.version)) continue;
+    if (aircraft.alt_baro === 'ground' || !finite(aircraft.alt_baro)) continue;
+    let { lat, lon } = aircraft;
+    const derived = (field) =>
+      aircraft.tisb?.includes(field) || aircraft.mlat?.includes(field);
+    const nic = finite(aircraft.nic) && !derived('nic') ? aircraft.nic : null;
+    const nacp =
+      finite(aircraft.nac_p) && !derived('nac_p') ? aircraft.nac_p : null;
+    if (!finite(lat) || Math.abs(lat) > 90) continue;
+    if (!finite(lon) || Math.abs(lon) > 180) continue;
+    // Only a position confirmed within the last minute is current evidence; a
+    // missing, invalid or negative age confirms nothing.
+    const age = aircraft.seen_pos;
+    if (!finite(age) || age < 0 || age > MAX_POSITION_AGE_S) continue;
+    // readsb exposes the flag while GPS is lost (15 s–15 min after the
+    // last good position), and removes it on recovery. Locate that evidence
+    // at the last good GNSS position, rather than a later MLAT estimate.
+    const gpsLost = finite(aircraft.gpsOkBefore) && aircraft.gpsOkBefore > 0;
+    if (nic === null && nacp === null && !gpsLost) continue;
+    if (
+      gpsLost &&
+      finite(aircraft.gpsOkLat) &&
+      Math.abs(aircraft.gpsOkLat) <= 90 &&
+      finite(aircraft.gpsOkLon) &&
+      Math.abs(aircraft.gpsOkLon) <= 180
+    ) {
+      lat = aircraft.gpsOkLat;
+      lon = aircraft.gpsOkLon;
+    }
+    seen.add(hex);
+    rows.push({
+      hex,
+      lat,
+      lon,
+      nic,
+      nacp,
+      gpsLost,
+      degraded:
+        gpsLost ||
+        (nacp !== null && nacp < GNSS_NACP_THRESHOLD) ||
+        (nic !== null &&
+          nic < GNSS_NIC_THRESHOLD &&
+          !(nic === 0 && nacp !== null && nacp >= 10)),
+    });
+  }
+  return rows;
+}
+
+/** Stable key of the cell containing a position. */
+export function gnssCellKey(lat, lon, cellDeg = GNSS_CELL_DEG) {
+  const row = Math.floor((Math.min(lat, 89.999999) + 90) / cellDeg);
+  const col = Math.floor((Math.min(lon, 179.999999) + 180) / cellDeg);
+  return `${row}:${col}`;
+}
+
+/**
+ * Fold one snapshot into a rolling observation store. Each aircraft counts
+ * once per cell per window. Presence and degraded evidence age separately: a
+ * degraded report keeps the aircraft degraded in that cell for one window
+ * after the report itself, however many healthy reports follow, so an
+ * aircraft that loses GNSS mid-cell is not averaged away and a recovered one
+ * is not held degraded forever.
+ *
+ * Every row is dated by when the snapshot was observed, not when it arrived:
+ * replaying a cached or stale snapshot never makes its evidence younger, and
+ * a snapshot older than the window adds nothing.
+ *
+ * @param {Map<string, {cell: string, seenAt: number, degradedAt: number|null}>} store
+ * @param {ReturnType<typeof normalizeGnssAircraft>} rows
+ * @param {number} nowMs
+ * @param {{windowMs?: number, cellDeg?: number, observedAt?: number}} [options]
+ *   `observedAt` is the snapshot's observation time (defaults to `nowMs`;
+ *   a future time is clamped to `nowMs`, a non-finite one adds nothing).
+ * @returns {Map} The same store, pruned to the window.
+ */
+export function accumulateGnssObservations(
+  store,
+  rows,
+  nowMs,
+  {
+    windowMs = GNSS_WINDOW_MS,
+    cellDeg = GNSS_CELL_DEG,
+    observedAt = nowMs,
+  } = {},
+) {
+  const at = Number.isFinite(observedAt) ? Math.min(observedAt, nowMs) : NaN;
+  if (Number.isFinite(at) && nowMs - at <= windowMs) {
+    for (const row of rows || []) {
+      if (!Number.isFinite(row?.lat) || !Number.isFinite(row?.lon)) continue;
+      const cell = gnssCellKey(row.lat, row.lon, cellDeg);
+      const key = `${row.hex}|${cell}`;
+      const previous = store.get(key);
+      const previousDegradedAt = previous?.degradedAt ?? null;
+      store.set(key, {
+        cell,
+        seenAt: Math.max(previous?.seenAt ?? at, at),
+        degradedAt: row.degraded
+          ? Math.max(previousDegradedAt ?? at, at)
+          : previousDegradedAt,
+      });
+    }
+  }
+  return pruneGnssObservations(store, nowMs, { windowMs });
+}
+
+/**
+ * Drop observations older than the window and degraded evidence older than
+ * the window, without adding anything. Used when no fresh snapshot arrives.
+ *
+ * @param {Map<string, {cell: string, seenAt: number, degradedAt: number|null}>} store
+ * @param {number} nowMs
+ * @param {{windowMs?: number}} [options]
+ * @returns {Map} The same store.
+ */
+export function pruneGnssObservations(
+  store,
+  nowMs,
+  { windowMs = GNSS_WINDOW_MS } = {},
+) {
+  for (const [key, entry] of store) {
+    if (nowMs - entry.seenAt > windowMs) store.delete(key);
+    else if (entry.degradedAt != null && nowMs - entry.degradedAt > windowMs)
+      store.set(key, { ...entry, degradedAt: null });
+  }
+  return store;
+}
+
+/**
+ * Navigation-integrity level of a cell, using gpsjam.org's published cell
+ * formula and bands: the first degraded aircraft is discounted to limit false
+ * positives, then under 2% is low, 2–10% medium and over 10% high. Medium and
+ * high cells are navigation-integrity anomalies.
+ */
+export function gnssIntegrityLevel(total, degraded) {
+  const percent = total > 0 ? (100 * Math.max(0, degraded - 1)) / total : 0;
+  const level =
+    percent > GNSS_HIGH_PERCENT
+      ? 'high'
+      : percent >= GNSS_MEDIUM_PERCENT
+        ? 'medium'
+        : 'low';
+  const anomaly = level !== 'low';
+  return {
+    percent,
+    level,
+    state: anomaly ? GNSS_ANOMALY_STATE : GNSS_NOMINAL_STATE,
+    interpretation: anomaly ? GNSS_INTERPRETATION : null,
+  };
+}
+
+/**
+ * Aggregate the observation store into displayable cells. Expects a store
+ * already pruned to the window by `accumulateGnssObservations` or
+ * `pruneGnssObservations`.
+ *
+ * @returns {{id: string, south: number, west: number, north: number, east: number, lat: number, lon: number, aircraft: number, degraded: number, percentDegraded: number, level: 'low'|'medium'|'high', state: string, interpretation: string|null}[]}
+ */
+export function binGnssCells(
+  store,
+  { cellDeg = GNSS_CELL_DEG, minAircraft = GNSS_MIN_AIRCRAFT } = {},
+) {
+  const tallies = new Map();
+  for (const { cell, degradedAt } of store.values()) {
+    const tally = tallies.get(cell) || { aircraft: 0, degraded: 0 };
+    tally.aircraft += 1;
+    if (degradedAt != null) tally.degraded += 1;
+    tallies.set(cell, tally);
+  }
+  const cells = [];
+  for (const [id, { aircraft, degraded }] of tallies) {
+    if (aircraft < minAircraft) continue;
+    const [row, col] = id.split(':').map(Number);
+    const south = row * cellDeg - 90;
+    const west = col * cellDeg - 180;
+    const { percent, level, state, interpretation } = gnssIntegrityLevel(
+      aircraft,
+      degraded,
+    );
+    cells.push({
+      id,
+      south,
+      west,
+      north: south + cellDeg,
+      east: west + cellDeg,
+      lat: south + cellDeg / 2,
+      lon: west + cellDeg / 2,
+      aircraft,
+      degraded,
+      percentDegraded: Math.round(percent * 10) / 10,
+      level,
+      state,
+      interpretation,
+    });
+  }
+  return cells.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** Legend colors: gpsjam's green / amber / red convention. */
+export const GNSS_LEVEL_COLORS = Object.freeze({
+  low: '#3fb950',
+  medium: '#e3b341',
+  high: '#f85149',
+});

src/layers/gnss/records.test.mjs

@@ -0,0 +1,491 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  accumulateGnssObservations,
+  binGnssCells,
+  GNSS_CLASSIFIER,
+  GNSS_PROVENANCE,
+  GNSS_WINDOW_MS,
+  gnssCellKey,
+  gnssIntegrityLevel,
+  gnssProvenance,
+  normalizeGnssAircraft,
+  pruneGnssObservations,
+} from './records.js';
+
+const aircraft = (overrides = {}) => ({
+  hex: '4ca7b5',
+  type: 'adsb_icao',
+  version: 2,
+  alt_baro: 36000,
+  lat: 50.1,
+  lon: 19.9,
+  nic: 8,
+  nac_p: 10,
+  seen_pos: 1.2,
+  ...overrides,
+});
+
+test('normalization keeps airborne decoded ADS-B v1/v2 quality with current positions', () => {
+  const rows = normalizeGnssAircraft({
+    ac: [
+      aircraft(),
+      aircraft({
+        hex: '000001',
+        type: 'mlat',
+        nic: undefined,
+        nac_p: undefined,
+      }),
+      aircraft({ hex: '000002', type: 'tisb_icao' }),
+      aircraft({ hex: '000003', version: 0 }),
+      aircraft({ hex: '000004', alt_baro: 'ground' }),
+      aircraft({ hex: '000005', seen_pos: 120 }),
+      aircraft({ hex: '000006', nic: undefined, nac_p: undefined }),
+      aircraft({ hex: '000007', lat: 95 }),
+      aircraft({ hex: '000008', version: undefined }),
+      // Only DO-260A/B (versions 1 and 2) define NIC and NACp.
+      aircraft({ hex: '000009', version: 3 }),
+      aircraft({ hex: '00000a', version: '2' }),
+      aircraft({ hex: '00000b', version: 1.5 }),
+      // A position is current only when its age is known, finite and 0..60 s.
+      aircraft({ hex: '00000c', seen_pos: undefined }),
+      aircraft({ hex: '00000d', seen_pos: null }),
+      aircraft({ hex: '00000e', seen_pos: -0.5 }),
+      aircraft({ hex: '00000f', seen_pos: '1.2' }),
+      aircraft({ hex: '000010', seen_pos: Number.NaN }),
+      aircraft({ hex: '000011', seen_pos: 60.1 }),
+      aircraft({ hex: 'not-hex' }),
+      aircraft(),
+      // A non-ICAO (`~`) address still self-reports over 1090ES ADS-B.
+      aircraft({ hex: '~a1b2c3' }),
+      // Version 1, and both ends of the position-age range, qualify.
+      aircraft({ hex: 'b00001', version: 1, seen_pos: 0 }),
+      aircraft({ hex: 'b00002', seen_pos: 60 }),
+      null,
+    ],
+  });
+  assert.deepEqual(rows, [
+    {
+      hex: '4ca7b5',
+      lat: 50.1,
+      lon: 19.9,
+      nic: 8,
+      nacp: 10,
+      gpsLost: false,
+      degraded: false,
+    },
+    {
+      hex: '~a1b2c3',
+      lat: 50.1,
+      lon: 19.9,
+      nic: 8,
+      nacp: 10,
+      gpsLost: false,
+      degraded: false,
+    },
+    ...['b00001', 'b00002'].map((hex) => ({
+      hex,
+      lat: 50.1,
+      lon: 19.9,
+      nic: 8,
+      nacp: 10,
+      gpsLost: false,
+      degraded: false,
+    })),
+  ]);
+  assert.equal(normalizeGnssAircraft({}), null);
+  assert.equal(normalizeGnssAircraft(null), null);
+});
+
+test('low NIC, low NACp or a readsb GPS-loss flag each mark an aircraft degraded', () => {
+  const rows = normalizeGnssAircraft({
+    ac: [
+      aircraft({ hex: 'a00001', nic: 6 }),
+      aircraft({ hex: 'a00002', nac_p: 7 }),
+      aircraft({ hex: 'a00003', gpsOkBefore: 1790690000.1 }),
+      aircraft({ hex: 'a00004', nic: 7, nac_p: 8 }),
+    ],
+  });
+  assert.deepEqual(
+    rows.map(({ hex, degraded, gpsLost }) => [hex, degraded, gpsLost]),
+    [
+      ['a00001', true, false],
+      ['a00002', true, false],
+      ['a00003', true, true],
+      ['a00004', false, false],
+    ],
+  );
+});
+
+test('cell keys are stable half-degree bins, clamped at the poles and antimeridian', () => {
+  assert.equal(gnssCellKey(50.1, 19.9), gnssCellKey(50.4, 19.6));
+  assert.notEqual(gnssCellKey(50.1, 19.9), gnssCellKey(50.6, 19.9));
+  assert.equal(gnssCellKey(90, 180), gnssCellKey(89.9, 179.9));
+  assert.equal(gnssCellKey(-90, -180), '0:0');
+  // Just south-west of the origin falls in the last cell before 0°, not cell 0.
+  assert.equal(gnssCellKey(-0.1, -0.1), '179:359');
+});
+
+test('integrity level follows the gpsjam.org published cell formula and bands', () => {
+  const nominal = {
+    percent: 0,
+    level: 'low',
+    state: 'nominal',
+    interpretation: null,
+  };
+  assert.deepEqual(gnssIntegrityLevel(10, 0), nominal);
+  // One degraded aircraft is always discounted.
+  assert.deepEqual(gnssIntegrityLevel(10, 1), nominal);
+  assert.equal(gnssIntegrityLevel(50, 2).level, 'medium');
+  assert.equal(gnssIntegrityLevel(10, 2).level, 'medium');
+  assert.equal(gnssIntegrityLevel(10, 3).level, 'high');
+  assert.equal(gnssIntegrityLevel(0, 0).level, 'low');
+});
+
+test('the primary state is a navigation-integrity anomaly; interference is only the secondary reading', () => {
+  for (const [total, bad] of [
+    [50, 2],
+    [10, 3],
+  ]) {
+    const { state, interpretation } = gnssIntegrityLevel(total, bad);
+    assert.equal(state, 'navigation-integrity-anomaly');
+    assert.equal(interpretation, 'suspected-gnss-interference');
+  }
+  const store = new Map();
+  accumulateGnssObservations(
+    store,
+    [
+      { hex: 'h1', lat: 10.1, lon: 10.1, degraded: true },
+      { hex: 'h2', lat: 10.2, lon: 10.2, degraded: true },
+      { hex: 'h3', lat: 10.3, lon: 10.3, degraded: false },
+    ],
+    0,
+  );
+  const [cell] = binGnssCells(store);
+  assert.equal(cell.level, 'high');
+  assert.equal(cell.state, 'navigation-integrity-anomaly');
+  assert.equal(cell.interpretation, 'suspected-gnss-interference');
+  for (const key of Object.keys(cell))
+    assert.doesNotMatch(key, /interference|jamming|spoof/i);
+});
+
+test('provenance separates the GEV classifier from the gpsjam aggregation and the GEV window', () => {
+  assert.deepEqual(GNSS_PROVENANCE.classifier, {
+    id: 'gev-nic-nacp-v2',
+    rule: 'gpsOkBefore set || aircraft-reported NACp < 8 || (aircraft-reported NIC < 7 && !(NIC === 0 && NACp >= 10))',
+    basis: '14 CFR 91.227(c) ADS-B Out performance minima (US regulation)',
+    definedBy: 'GEV',
+    validated: false,
+  });
+  assert.equal(GNSS_PROVENANCE.classifier, GNSS_CLASSIFIER);
+  assert.deepEqual(GNSS_PROVENANCE.aggregation, {
+    id: 'gpsjam-cell-bands',
+    formula: '100 * max(0, bad - 1) / total',
+    bands: [2, 10],
+    source: 'https://gpsjam.org/faq',
+    definedBy: 'gpsjam.org',
+  });
+  assert.deepEqual(GNSS_PROVENANCE.window, {
+    minutes: 30,
+    scope: 'visited-view',
+    cellDeg: 0.5,
+    minAircraft: 3,
+    definedBy: 'GEV',
+  });
+  assert.equal(GNSS_PROVENANCE.state.id, 'navigation-integrity-anomaly');
+  assert.equal(
+    GNSS_PROVENANCE.interpretation.id,
+    'suspected-gnss-interference',
+  );
+  assert.equal(GNSS_PROVENANCE.interpretation.validated, false);
+  assert.ok(Object.isFrozen(GNSS_PROVENANCE));
+  assert.ok(Object.isFrozen(GNSS_PROVENANCE.aggregation.bands));
+  // The bands in provenance are the ones the level function applies.
+  const [medium, high] = GNSS_PROVENANCE.aggregation.bands;
+  assert.equal(gnssIntegrityLevel(100, 1 + medium).level, 'medium');
+  assert.equal(gnssIntegrityLevel(100, 1 + high).level, 'medium');
+  assert.equal(gnssIntegrityLevel(100, 2 + high).level, 'high');
+  assert.equal(gnssProvenance({ windowMs: 10 * 60_000 }).window.minutes, 10);
+});
+
+test('observations count each aircraft once per cell and expire after the window', () => {
+  const store = new Map();
+  const at = (lat, hex, degraded) => ({ hex, lat, lon: 20.1, degraded });
+  accumulateGnssObservations(
+    store,
+    [at(50.1, 'a1', true), at(50.2, 'a2', false), at(50.3, 'a3', false)],
+    0,
+    { windowMs: 1000 },
+  );
+  // a1 recovers inside the same cell: it stays degraded for the window.
+  accumulateGnssObservations(store, [at(50.2, 'a1', false)], 500, {
+    windowMs: 1000,
+  });
+  let [cell] = binGnssCells(store);
+  assert.equal(cell.aircraft, 3);
+  assert.equal(cell.degraded, 1);
+  assert.equal(cell.level, 'low');
+  assert.deepEqual(
+    [cell.south, cell.west, cell.north, cell.east],
+    [50, 20, 50.5, 20.5],
+  );
+
+  accumulateGnssObservations(store, [], 1200, { windowMs: 1000 });
+  assert.equal(store.size, 1);
+  assert.deepEqual(binGnssCells(store), []);
+});
+
+const MIN = 60_000;
+const report = (hex, degraded, lat = 50.1) => ({
+  hex,
+  lat,
+  lon: 20.1,
+  degraded,
+});
+const entry = (store, hex) =>
+  [...store].find(([key]) => key.startsWith(`${hex}|`))?.[1];
+
+test('degraded evidence expires one window after the degraded report, despite continuing healthy reports', () => {
+  const store = new Map();
+  accumulateGnssObservations(store, [report('a1', true)], 0);
+  // a1 keeps reporting healthy every minute in the same cell.
+  for (let minute = 1; minute <= 30; minute += 1)
+    accumulateGnssObservations(store, [report('a1', false)], minute * MIN);
+  assert.equal(entry(store, 'a1').seenAt, 30 * MIN);
+  assert.equal(
+    entry(store, 'a1').degradedAt,
+    0,
+    'healthy reports do not refresh the degraded evidence',
+  );
+  accumulateGnssObservations(store, [report('a1', false)], 31 * MIN);
+  assert.deepEqual(entry(store, 'a1'), {
+    cell: gnssCellKey(50.1, 20.1),
+    seenAt: 31 * MIN,
+    degradedAt: null,
+  });
+  // A new degraded report starts its own window.
+  accumulateGnssObservations(store, [report('a1', true)], 32 * MIN);
+  assert.equal(entry(store, 'a1').degradedAt, 32 * MIN);
+  accumulateGnssObservations(store, [report('a1', false)], 40 * MIN);
+  assert.equal(entry(store, 'a1').degradedAt, 32 * MIN);
+});
+
+test('a degraded cell turns healthy once its degraded evidence is older than the window', () => {
+  const store = new Map();
+  const healthy = [report('a2', false), report('a3', false)];
+  accumulateGnssObservations(
+    store,
+    [report('a1', true), report('b1', true), ...healthy],
+    0,
+  );
+  assert.equal(binGnssCells(store)[0].level, 'high');
+  for (let minute = 10; minute <= 30; minute += 10)
+    accumulateGnssObservations(
+      store,
+      [report('a1', false), report('b1', false), ...healthy],
+      minute * MIN,
+    );
+  assert.equal(binGnssCells(store)[0].degraded, 2);
+  accumulateGnssObservations(
+    store,
+    [report('a1', false), report('b1', false), ...healthy],
+    31 * MIN,
+  );
+  const [cell] = binGnssCells(store);
+  assert.equal(cell.aircraft, 4);
+  assert.equal(cell.degraded, 0);
+  assert.equal(cell.level, 'low');
+});
+
+test('an aircraft returning after the window starts fresh', () => {
+  const store = new Map();
+  accumulateGnssObservations(store, [report('a1', true)], 0);
+  // a1 leaves; nothing is heard from it for longer than the window.
+  accumulateGnssObservations(store, [], 31 * MIN);
+  assert.equal(store.size, 0);
+  accumulateGnssObservations(store, [report('a1', false)], 32 * MIN);
+  assert.deepEqual(entry(store, 'a1'), {
+    cell: gnssCellKey(50.1, 20.1),
+    seenAt: 32 * MIN,
+    degradedAt: null,
+  });
+  // Returning degraded dates the evidence from the new report.
+  const again = new Map();
+  accumulateGnssObservations(again, [report('a9', true)], 0);
+  accumulateGnssObservations(again, [], 31 * MIN);
+  accumulateGnssObservations(again, [report('a9', true)], 33 * MIN);
+  assert.equal(entry(again, 'a9').degradedAt, 33 * MIN);
+});
+
+test('an aircraft heard healthy right after the window drops its stale degraded evidence', () => {
+  // No prune runs in between: the old entry is still in the store when the
+  // healthy report arrives, so the new report alone must not carry it over.
+  const store = new Map();
+  accumulateGnssObservations(store, [report('a1', true)], 0);
+  accumulateGnssObservations(store, [report('a1', false)], 31 * MIN);
+  assert.deepEqual(entry(store, 'a1'), {
+    cell: gnssCellKey(50.1, 20.1),
+    seenAt: 31 * MIN,
+    degradedAt: null,
+  });
+  // Exactly one window after the degraded report it still counts.
+  const edge = new Map();
+  accumulateGnssObservations(edge, [report('a1', true)], 0);
+  accumulateGnssObservations(edge, [report('a1', false)], 30 * MIN);
+  assert.equal(entry(edge, 'a1').degradedAt, 0);
+});
+
+test('rows are dated by the snapshot observation time, so a replay never restarts the window', () => {
+  const store = new Map();
+  const snapshot = [report('a1', true), report('a2', false)];
+  accumulateGnssObservations(store, snapshot, 0, { observedAt: 0 });
+  // The same snapshot replayed (cached or stale) 29 minutes later.
+  accumulateGnssObservations(store, snapshot, 29 * MIN, { observedAt: 0 });
+  assert.equal(entry(store, 'a1').seenAt, 0);
+  assert.equal(entry(store, 'a1').degradedAt, 0);
+  accumulateGnssObservations(store, snapshot, 31 * MIN, { observedAt: 0 });
+  assert.equal(store.size, 0, 'a replay older than the window adds nothing');
+
+  // An older replay never moves an entry's age backwards either.
+  accumulateGnssObservations(store, snapshot, 40 * MIN);
+  accumulateGnssObservations(store, [report('a2', true)], 41 * MIN, {
+    observedAt: 35 * MIN,
+  });
+  assert.equal(entry(store, 'a2').seenAt, 40 * MIN);
+  assert.equal(entry(store, 'a2').degradedAt, 35 * MIN);
+
+  // A future time is clamped to now; an undated snapshot adds nothing.
+  accumulateGnssObservations(store, [report('f1', true)], 50 * MIN, {
+    observedAt: 99 * MIN,
+  });
+  assert.equal(entry(store, 'f1').seenAt, 50 * MIN);
+  for (const observedAt of [null, Number.NaN])
+    accumulateGnssObservations(store, [report('u1', true)], 50 * MIN, {
+      observedAt,
+    });
+  assert.equal(entry(store, 'u1'), undefined);
+});
+
+test('pruning without new rows drops expired observations and expired degraded evidence', () => {
+  const store = new Map();
+  accumulateGnssObservations(store, [report('a1', true)], 0);
+  accumulateGnssObservations(store, [report('a1', false)], 20 * MIN);
+  accumulateGnssObservations(store, [report('a2', false)], 0);
+  assert.equal(pruneGnssObservations(store, 31 * MIN), store);
+  assert.deepEqual(
+    [...store.keys()].map((key) => key.split('|')[0]),
+    ['a1'],
+  );
+  assert.equal(entry(store, 'a1').degradedAt, null);
+  pruneGnssObservations(store, 51 * MIN);
+  assert.equal(store.size, 0);
+  assert.equal(GNSS_WINDOW_MS, 30 * MIN);
+});
+
+test('rows without finite coordinates never key a cell', () => {
+  const store = new Map();
+  accumulateGnssObservations(
+    store,
+    [
+      { hex: 'n1', lat: Number.NaN, lon: 10.1, degraded: true },
+      { hex: 'n2', lat: 10.1, lon: '10.1', degraded: true },
+      null,
+    ],
+    0,
+  );
+  assert.equal(store.size, 0);
+});
+
+test('cells below the minimum aircraft count are withheld', () => {
+  const store = new Map();
+  accumulateGnssObservations(
+    store,
+    [
+      { hex: 'b1', lat: 10.1, lon: 10.1, degraded: true },
+      { hex: 'b2', lat: 10.2, lon: 10.2, degraded: true },
+    ],
+    0,
+  );
+  assert.deepEqual(binGnssCells(store), []);
+  const [cell] = binGnssCells(store, { minAircraft: 2 });
+  assert.equal(cell.level, 'high');
+  assert.equal(cell.percentDegraded, 50);
+});
+
+test('MLAT GPS-loss evidence uses the last good GNSS location and ignores MLAT NIC', () => {
+  const [row] = normalizeGnssAircraft({
+    ac: [
+      aircraft({
+        type: 'mlat',
+        nac_p: 0,
+        nic: 0,
+        mlat: ['lat', 'lon', 'nic'],
+        gpsOkBefore: 1800000000,
+        gpsOkLat: 54.2,
+        gpsOkLon: 19.3,
+      }),
+    ],
+  });
+  assert.ok(row);
+  assert.equal(row.lat, 54.2);
+  assert.equal(row.lon, 19.3);
+  assert.equal(row.nic, null);
+  assert.equal(row.degraded, true);
+  const [healthy] = normalizeGnssAircraft({
+    ac: [aircraft({ type: 'mlat', nic: 0, mlat: ['nic'] })],
+  });
+  assert.equal(healthy.degraded, false);
+});
+
+test('TIS-B accuracy fields and unknown containment do not manufacture anomalies', () => {
+  const rows = normalizeGnssAircraft({
+    ac: [
+      aircraft({ hex: 'a00001', nac_p: 0, tisb: ['nac_p'] }),
+      aircraft({ hex: 'a00002', nic: 0, tisb: ['nic'] }),
+      aircraft({ hex: 'a00003', nic: 0, nac_p: 10 }),
+      aircraft({ hex: 'a00004', nic: 0, nac_p: 8 }),
+      aircraft({ hex: 'a00005', nic: 6, nac_p: 10 }),
+    ],
+  });
+  assert.deepEqual(
+    rows.map((r) => r.degraded),
+    [false, false, false, true, true],
+  );
+});
+
+// Quality-field subsets captured from public adsb.lol US point responses on
+// 2026-10-14 (34,-118 and 41,-73, radius 250 nm), ODbL 1.0 / adsb.lol contributors.
+// Only field provenance is reused; the airborne ADS-B envelopes are synthetic.
+test('public US quality-field fixtures do not turn rebroadcast accuracy into own accuracy', () => {
+  const tisbQuality = {
+    nic: 0,
+    nac_p: 0,
+    tisb: [
+      'altitude',
+      'alt_baro',
+      'gs',
+      'track',
+      'geom_rate',
+      'lat',
+      'lon',
+      'nic',
+      'rc',
+      'nac_p',
+      'nac_v',
+      'sil',
+      'sil_type',
+    ],
+    mlat: [],
+  };
+  assert.deepEqual(normalizeGnssAircraft({ ac: [aircraft(tisbQuality)] }), []);
+  const unknownContainment = {
+    nic: 0,
+    nac_p: 10,
+    tisb: ['callsign'],
+    mlat: [],
+  };
+  assert.equal(
+    normalizeGnssAircraft({ ac: [aircraft(unknownContainment)] })[0].degraded,
+    false,
+  );
+});

src/layers/gnss/source.js

@@ -0,0 +1,81 @@
+import { readResponseJsonCapped } from '../../sources/httpBody.js';
+
+// A portable export (package.json): no i18n here. Failures stay English data;
+// the Layers panel shows them translated.
+const msg = (text) => text;
+
+function retryDelay(raw, nowMs) {
+  if (!raw) return null;
+  const seconds = Number(raw);
+  const ms = seconds * 1000;
+  if (Number.isFinite(ms) && seconds > 0)
+    return Math.min(3600000, Math.max(5000, ms));
+  const at = Date.parse(raw);
+  return Number.isFinite(at) && at > nowMs
+    ? Math.min(3600000, Math.max(5000, at - nowMs))
+    : null;
+}
+
+/** Request integrity facts around a view anchor through the same-origin adsb.lol proxy. */
+export function createAdsbGnssSource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+} = {}) {
+  return {
+    async getSnapshot({ latitude, longitude } = {}, { signal } = {}) {
+      signal?.throwIfAborted();
+      if (!Number.isFinite(latitude) || !Number.isFinite(longitude))
+        throw new Error(msg('GNSS snapshot needs a view anchor'));
+      const params = new URLSearchParams({
+        lat: String(Math.round(latitude)),
+        lon: String(Math.round(longitude)),
+      });
+      const response = await fetchImpl(`/api/gnss-integrity?${params}`, {
+        signal,
+      });
+      if (!response.ok) {
+        const limited = response.status === 429;
+        const retryAfterMs = retryDelay(
+          response.headers.get('retry-after'),
+          now(),
+        );
+        throw Object.assign(
+          new Error(
+            // HTTP errors are matched by FEED_ERROR_PATTERNS in ui/statusText.js.
+            limited
+              ? msg('GNSS feed rate limited (HTTP 429)')
+              : `GNSS feed unavailable (HTTP ${response.status})`,
+          ),
+          {
+            status: response.status,
+            retryable: limited || response.status >= 500,
+            retryAfterMs: retryAfterMs ?? (limited ? 60000 : null),
+          },
+        );
+      }
+      const payload = await readResponseJsonCapped(
+        response,
+        4 * 1024 * 1024,
+        signal,
+      );
+      signal?.throwIfAborted();
+      if (!Array.isArray(payload?.rows))
+        throw new Error(msg('Malformed GNSS integrity snapshot'));
+      // The snapshot's age (measured on the proxy's clock) dates every row in
+      // the rolling window; an undated snapshot could only be treated as new,
+      // so it is refused.
+      if (!Number.isFinite(payload.ageMs) || payload.ageMs < 0)
+        throw new Error(msg('GNSS integrity snapshot has no observation time'));
+      return {
+        rows: payload.rows,
+        ageMs: payload.ageMs,
+        fetchedAt: Number.isFinite(payload.fetchedAt)
+          ? payload.fetchedAt
+          : null,
+        stale: payload.stale === true,
+        classifier:
+          typeof payload.classifier === 'string' ? payload.classifier : null,
+      };
+    },
+  };
+}