Merge branch 'main' into feat/bikeshare-norway

src/annotations/annotationEngine.test.mjs

@@ -313,7 +313,9 @@ test('retry: a plain HTTP 500 still exhausts the existing 8s/25s transient ladde
   t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 100_000 });
   globalThis.window = { setTimeout: globalThis.setTimeout, clearTimeout: globalThis.clearTimeout };
   const requestTimes = [];
-  globalThis.fetch = async () => {
+  globalThis.fetch = async (url) => {
+    if (String(url).endsWith('/status'))
+      return Response.json({ configured: true });
     requestTimes.push(Date.now());
     return httpFailure(500);
   };
@@ -402,7 +404,7 @@ test('outline upgrade updates the rendered element in place without remove/add',
   };
   let overpassCall = 0;
   globalThis.fetch = async (url) => {
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       return { json: async () => ({
         status: 'OK',
         results: [{

src/annotations/annotationResolver.test.mjs

@@ -200,7 +200,7 @@ test('ask-side admin bypass: "the Texas Capitol" recovers near-view despite a fa
   const calls = [];
   installGoogleMocks(t, async (url) => {
     calls.push(String(url));
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       return { json: async () => geocodePayload({
         lat: 31.0000,
         lon: -99.0000,
@@ -235,7 +235,7 @@ test('ask-side admin bypass: explicit "state of Texas" skips recovery and proxim
   const calls = [];
   installGoogleMocks(t, async (url) => {
     calls.push(String(url));
-    assert.match(String(url), /^https:\/\/maps\.googleapis\.com\/maps\/api\/geocode/);
+    assert.match(String(url), /^\/api\/google\/geocode\?/);
     return { json: async () => geocodePayload({
       lat: 31.0000,
       lon: -99.0000,
@@ -273,7 +273,7 @@ for (const fixture of [
     const calls = [];
     installGoogleMocks(t, async (url) => {
       calls.push(String(url));
-      if (String(url).startsWith('https://maps.googleapis.com/')) {
+      if (String(url).startsWith('/api/google/geocode')) {
         return { json: async () => geocodePayload({
           lat: fixture.lat,
           lon: fixture.lon,
@@ -299,7 +299,7 @@ test('ask-side admin bypass: bare "Texas" remains on the guarded recovery path',
   const calls = [];
   installGoogleMocks(t, async (url) => {
     calls.push(String(url));
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       return { json: async () => geocodePayload({
         lat: 31.0000,
         lon: -99.0000,
@@ -328,7 +328,7 @@ test('ask-side admin bypass: admin level 2/3 result types never grant a township
   const calls = [];
   installGoogleMocks(t, async (url) => {
     calls.push(String(url));
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       const query = new URL(String(url)).searchParams.get('address');
       return { json: async () => geocodePayload({
         lat: 39.7817,
@@ -380,7 +380,7 @@ function installCapitolMocks(t, elements, components = [
   { long_name: 'Capitol Hill', types: ['neighborhood', 'political'] },
 ]) {
   installGoogleMocks(t, async (url) => {
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       return { json: async () => ({ status: 'OK', results: [{
         formatted_address: 'Washington, DC 20004, USA',
         types: ['establishment', 'landmark', 'point_of_interest', 'tourist_attraction'],
@@ -458,7 +458,7 @@ test('keyless: a key that geocodes to nothing still anchors the annotation', asy
   const requests = [];
   installGoogleMocks(t, async (url) => {
     requests.push(String(url));
-    if (String(url).startsWith('https://maps.googleapis.com/')) return GOOGLE_FOUND_NOTHING;
+    if (String(url).startsWith('/api/google/geocode')) return GOOGLE_FOUND_NOTHING;
     return {
       ok: true,
       json: async () => ({
@@ -495,7 +495,7 @@ test('keyless: a key that geocodes to nothing still anchors the annotation', asy
     high: { latitude: 30.28, longitude: -97.68 },
   });
   // Google is asked first and exactly once; one Photon call answers it.
-  assert.equal(requests.filter((url) => url.includes('maps.googleapis.com')).length, 1);
+  assert.equal(requests.filter((url) => url.includes('/api/google/geocode')).length, 1);
   assert.equal(requests.filter((url) => url.includes('photon.komoot.io')).length, 1);
 });
 
@@ -512,7 +512,7 @@ test('keyless: OSM matching uses the feature\'s canonical name, not the user\'s
 
   installGoogleMocks(t, async (url, init) => {
     const href = String(url);
-    if (href.startsWith('https://maps.googleapis.com/')) return GOOGLE_FOUND_NOTHING;
+    if (href.startsWith('/api/google/geocode')) return GOOGLE_FOUND_NOTHING;
     if (href.startsWith('/api/google/text-search')) return { ok: true, json: async () => ({ places: [] }) };
     if (href.startsWith('https://photon.komoot.io/')) {
       return {
@@ -575,7 +575,7 @@ test('keyless: a Photon outage is not remembered as "no such place"', async (t)
   const requests = [];
   installGoogleMocks(t, async (url) => {
     requests.push(String(url));
-    if (String(url).startsWith('https://maps.googleapis.com/')) return GOOGLE_FOUND_NOTHING;
+    if (String(url).startsWith('/api/google/geocode')) return GOOGLE_FOUND_NOTHING;
     if (!photonReachable) throw new Error('network down');
     return photonUp;
   });

src/annotations/regionRing.test.mjs

@@ -51,9 +51,11 @@ test('region ring: Natural Earth names resolve without a geocoder', async () =>
 test('region ring: a slow admin-boundary lookup returns region-timeout within the budget', async () => {
   let adminSignal;
   let release;
+  let lookupStarted;
   const { resolveRegionRingForQuery } = createAnnotationResolver({
     featureSource: featureSource({
       getAdministrativeAreas(_point, { signal }) {
+        lookupStarted = Date.now();
         adminSignal = signal;
         return new Promise((resolve) => {
           release = resolve;
@@ -61,7 +63,6 @@ test('region ring: a slow admin-boundary lookup returns region-timeout within th
       },
     }),
   });
-  const started = Date.now();
   const region = await resolveRegionRingForQuery(
     'Atlantis',
     undefined,
@@ -73,8 +74,10 @@ test('region ring: a slow admin-boundary lookup returns region-timeout within th
     ring: null,
     error: 'region-timeout',
   });
+  // Timed from the boundary lookup, so the bundled pack scans before it do not
+  // count. Under the 3 s default budget, so an ignored budgetMs still fails.
   assert.ok(
-    Date.now() - started < 1000,
+    Date.now() - lookupStarted < 2_000,
     'returns at the budget, not the lookup',
   );
   // The lookup is left running so it can fill the boundary cache.

src/app/constructCatalog.js

@@ -25,6 +25,7 @@ import { createApplicationAwareness } from './layers/militaryAwareness.js';
 import { createApplicationFirms } from './layers/firms.js';
 import { createApplicationEarthquakes } from './layers/earthquakes.js';
 import { createApplicationFirePerimeters } from './layers/perimeters.js';
+import { createApplicationGnssIntegrity } from './layers/gnss.js';
 import { createApplicationCables } from './layers/submarineCables.js';
 import { createApplicationStreetLevel } from './layers/streetLevel.js';
 import { createInfrastructureLayers } from '../data/infrastructure.js';
@@ -120,6 +121,9 @@ export function createApplicationCatalog({
         createApplicationFirePerimeters({
           source: sources['fire-perimeters'],
         }),
+        createApplicationGnssIntegrity({
+          source: sources['gnss-integrity'],
+        }),
         createApplicationAlpr({ surface, source: sources.alpr }),
         createApplicationStreetLevel({
           surface,

src/app/constructCatalog.test.mjs

@@ -40,7 +40,7 @@ test('catalogs construct distinct layers and classification from their supplied
     signal: b.signal,
     surface: fixtureSurface(b.signal),
   });
-  assert.equal(first.layers.length, 30);
+  assert.equal(first.layers.length, 31);
   assert.ok(first.get('local-adsb'), 'Local ADS-B is registered');
   assert.deepEqual(
     first.metadata.find(({ id }) => id === 'local-adsb'),
@@ -60,6 +60,7 @@ test('catalogs construct distinct layers and classification from their supplied
       '2026-09-21T12:00:00.000Z',
     );
   assert.ok(first.get('fire-perimeters'));
+  assert.ok(first.get('gnss-integrity'));
   assert.ok(first.get('transit'));
   const order = first.layers.map(({ id }) => id);
   assert.deepEqual(
@@ -153,7 +154,7 @@ test('Mapillary can be omitted or replaced without changing catalog membership',
     surface: fixtureSurface(lifetime.signal),
   };
   const catalog = createApplicationCatalog(options);
-  assert.equal(catalog.layers.length, 30);
+  assert.equal(catalog.layers.length, 31);
   assert.deepEqual(catalog.get('street-level').providerIds, []);
   assert.equal(
     catalogControlServices(catalog).streetLevelLayer,

src/app/layers/gnss.js

@@ -0,0 +1,6 @@
+import { createGnssIntegrityLayer } from '../../layers/gnss/index.js';
+
+/** Wire the adsb.lol GNSS navigation-integrity layer into the application catalog. */
+export function createApplicationGnssIntegrity(options) {
+  return createGnssIntegrityLayer(options);
+}

src/app/layers/streetLevel.js

@@ -1,21 +1,38 @@
 import { createStreetLevelLayer } from '../../layers/streetLevel/index.js';
 import { createMapillaryProvider } from '../../layers/streetLevel/providers/mapillary/index.js';
+import { createGoogleProvider } from '../../layers/streetLevel/providers/google/index.js';
+import { createKartaViewProvider } from '../../layers/streetLevel/providers/kartaview/index.js';
 import * as sprites from '../../data/spriteOrder.js';
 import * as picking from '../../data/pickRegistry.js';
 import * as input from '../../data/inputOwnership.js';
+import * as scenePick from '../../data/scenePick.js';
 import * as render from '../../renderGovernor.js';
 
+/** The browser Maps key the scene was started with (src/app/scene.js). */
+const googleApiKey = () => globalThis.window?.__GOOGLE_MAPS_API_KEY__ || null;
+
 /**
- * Inject providers, or use Mapillary only when its source is supplied.
- * An explicit provider list replaces the default; unused sources.mapillary is
- * neither constructed nor validated, including when the list is empty.
+ * Mapillary, Google Street View and KartaView, once the Mapillary source is
+ * supplied; else none.
+ */
+function defaultProviders(sources) {
+  if (sources.mapillary == null) return [];
+  return [
+    createMapillaryProvider({ source: sources.mapillary }),
+    createGoogleProvider({ getApiKey: googleApiKey }),
+    createKartaViewProvider(),
+  ];
+}
+
+/**
+ * Inject providers, or use the defaults. An explicit provider list replaces
+ * them; an unused sources.mapillary is neither constructed nor validated,
+ * including when the list is empty.
  */
 export function createApplicationStreetLevel({
   surface,
   sources = {},
-  providers = sources.mapillary == null
-    ? []
-    : [createMapillaryProvider({ source: sources.mapillary })],
+  providers = defaultProviders(sources),
 }) {
   return createStreetLevelLayer({
     providers,
@@ -23,6 +40,7 @@ export function createApplicationStreetLevel({
       sprites,
       picking,
       input,
+      scenePick,
       render,
       ground: surface?.groundFloor ?? null,
       meshFloor: surface?.meshFloor ?? null,

src/app/layers/streetLevel.test.mjs

@@ -27,3 +27,30 @@ test('explicit providers replace the default source and an empty list removes it
     /array/,
   );
 });
+
+test('the defaults are Mapillary (given its source), Street View and KartaView, which start off and travel as provider switches', async () => {
+  const { createDefaultLayerState } = await import('../../data/layerState.js');
+  const mapillary = {
+    getStatus() {},
+    getTile() {},
+    getSequenceImages() {},
+    nearestImages() {},
+  };
+  const layer = createApplicationStreetLevel({ sources: { mapillary } });
+  assert.deepEqual(layer.providerIds, ['mapillary', 'google', 'kartaview']);
+  // A fresh page and a restored default agree: Street View is billed, so off.
+  layer.setParams(createDefaultLayerState().options['street-level']);
+  assert.equal(layer.getParams().google, false);
+  assert.equal(layer.getParams().mapillary, true);
+  // A link that lit Street View carries it in the shared switch field.
+  layer.setParams({ providerSwitches: 'google-1' });
+  assert.equal(layer.getParams().google, true);
+  assert.equal(layer.getParams().providerSwitches, 'google-1*kartaview-0');
+  // KartaView is keyless and free, but one source shows at a time.
+  layer.setParams({ providerSwitches: 'kartaview-1' });
+  assert.equal(layer.getParams().kartaview, true);
+  assert.equal(layer.getParams().google, false);
+  assert.equal(layer.getParams().mapillary, false);
+  // Without the application's Street Level source there are none.
+  assert.deepEqual(createApplicationStreetLevel({}).providerIds, []);
+});

src/app/sourceComposition.js

@@ -46,6 +46,7 @@ export const CATALOG_SOURCE_CONTRACTS = Object.freeze({
   cyclones: contract(['weather-cyclones'], ['getSnapshot']),
   earthquakes: contract(['earthquakes'], ['getSnapshot']),
   'fire-perimeters': contract(['fire-perimeters'], ['getSnapshot']),
+  'gnss-integrity': contract(['gnss-integrity'], ['getSnapshot']),
   cables: contract(['telegeography-submarine-cables'], ['fetch']),
   transit: contract(['transit'], ['requestSnapshot', 'getHistory']),
 });

src/app/sourceComposition.test.mjs

@@ -37,7 +37,7 @@ test('every acquisition source can be omitted without losing catalog membership'
 
 test('all acquisition sources may be absent, and enable fails before initializing or fetching', async (t) => {
   const actual = catalog({}, t);
-  assert.equal(actual.layers.length, 30);
+  assert.equal(actual.layers.length, 31);
   const manager = new LayerLifecycle(
     {},
     { getSourceAvailability: actual.getSourceAvailability },

src/app/tools.js

@@ -1,6 +1,7 @@
 import { SceneDirector } from '../scenes/director.js';
 import { initAnnotations } from '../annotations/index.js';
 import { initDrawTool } from '../annotations/drawTool.js';
+import { initGeoFileImport } from '../ui/geoFileImport.js';
 import { initImageryBoxTool } from '../ui/imageryBoxTool.js';
 import { createRecentImageryPanel } from '../ui/recentImagery.js';
 import { initGevVoiceCommands } from '../voice/gevRealtime.js';
@@ -56,6 +57,16 @@ export function createApplicationTools({
   // lifetime rather than to whoever last pressed the button.
   const drawTool = initDrawTool({ viewer, annotations });
   defer(() => drawTool?.destroy());
+  // DISPLAY ▸ Import: the person's own GeoJSON/KML/KMZ/GPX files, each its
+  // own data source. They live for the page session, so the application
+  // lifetime removes them and the drop listeners on the viewer container.
+  const geoFileImport = initGeoFileImport({
+    viewer,
+    navigation: styleManager,
+    ground: operations.surface?.groundFloor,
+    subscribeMapSource: (listener) => mapStackController?.subscribe?.(listener),
+  });
+  defer(() => geoFileImport?.destroy());
   // DATA ▸ Recent Imagery: the box tool claims the pointer like Draw and the
   // panel lives on the right rail, so both belong to the application
   // lifetime. The tileset lets the layer drape while the globe is hidden.

src/cockpitMath.js

@@ -83,6 +83,26 @@ export function cockpitAltitudeDisplayFt(altitudeM, onGround) {
   return Number.isFinite(altitudeM) ? altitudeM * 3.28084 : null;
 }
 
+/**
+ * HUD wording for a tracked aircraft's transponder emergency, or null.
+ * States what was broadcast, never a conclusion about the flight: the Mode A
+ * code when it names the status, else the ADS-B field it came from (an
+ * unrelated squawk is dropped).
+ * @param {{label?: string, squawk?: string|null, source?: string,
+ *   severity?: string}|null|undefined} emergency
+ * @returns {string|null}
+ */
+export function formatCockpitEmergency(emergency) {
+  const label = String(emergency?.label || '')
+    .trim()
+    .toUpperCase();
+  if (!label) return null;
+  if (emergency.source === 'squawk' && emergency.squawk)
+    return `SQUAWK ${emergency.squawk} · ${label}`;
+  const field = emergency.severity === 'priority' ? 'PRIORITY' : 'EMERGENCY';
+  return `ADS-B ${field} · ${label}`;
+}
+
 /** Format the cockpit Context scope without overstating installation coverage. */
 export function formatCockpitContextScope(
   subjectLabel,

src/cockpitMath.test.mjs

@@ -13,6 +13,7 @@ import {
   compassDivisions,
   formatAltitudeRulerTick,
   formatCockpitContextScope,
+  formatCockpitEmergency,
   formatCompassDivision,
   formatSpeedRulerTick,
   normalizeHeading,
@@ -364,3 +365,21 @@ test('tracked-identity resolution falls back to layer precedence', () => {
   assert.equal(resolveTrackedAircraftInfo({ trackedId: 'flights:aaa077' }), null);
   assert.equal(resolveTrackedAircraftInfo(), null);
 });
+
+test('cockpit emergency wording states the broadcast code, not a conclusion', () => {
+  assert.equal(
+    formatCockpitEmergency({ label: 'General emergency', squawk: '7700', source: 'squawk', severity: 'emergency' }),
+    'SQUAWK 7700 · GENERAL EMERGENCY',
+  );
+  assert.equal(
+    formatCockpitEmergency({ label: 'Downed aircraft', squawk: '1200', source: 'ads-b', severity: 'emergency' }),
+    'ADS-B EMERGENCY · DOWNED AIRCRAFT',
+    'an unrelated squawk is not quoted beside an ADS-B status',
+  );
+  assert.equal(
+    formatCockpitEmergency({ label: 'Minimum fuel', squawk: null, source: 'ads-b', severity: 'priority' }),
+    'ADS-B PRIORITY · MINIMUM FUEL',
+  );
+  assert.equal(formatCockpitEmergency(null), null);
+  assert.equal(formatCockpitEmergency({ label: '' }), null);
+});

src/codexOauthRealtime.test.mjs

@@ -145,17 +145,20 @@ test('Codex OAuth reader enforces expiry margin and bounds tokens without exp by
 
 test('Codex login resolves an installed executable before PATH and starts browser auth detached', async () => {
   const checked = [];
+  // Built with path.join so the stub matches the resolver on Windows too,
+  // where the separators are backslashes.
+  const installed = path.join('/home/fixture', '.local', 'bin', 'codex');
   assert.equal(
     resolveCodexExecutable({
       environment: {},
       home: '/home/fixture',
       access(candidate) {
         checked.push(candidate);
-        if (candidate.endsWith('/.local/bin/codex')) return;
+        if (candidate === installed) return;
         throw new Error('missing');
       },
     }),
-    path.join('/home/fixture', '.local', 'bin', 'codex'),
+    installed,
   );
   assert.equal(checked.length, 1);
 

src/data/adsbLolFallback.js

@@ -43,11 +43,18 @@ export function normalizeAdsbLolAircraftState(aircraft, nowSeconds) {
     .toLowerCase();
   const latitude = finiteNumber(aircraft?.lat);
   const longitude = finiteNumber(aircraft?.lon);
-  if (!hex || latitude === null || longitude === null) return null;
+  if (
+    !hex ||
+    latitude === null ||
+    longitude === null ||
+    Math.abs(latitude) > 90 ||
+    Math.abs(longitude) > 180
+  )
+    return null;
 
   const seenPosition = Math.max(
     0,
-    finiteNumber(aircraft?.seen_pos) ?? finiteNumber(aircraft?.seen) ?? 0,
+    finiteNumber(aircraft?.seen_pos) ?? finiteNumber(aircraft?.seen) ?? NaN,
   );
   const seen = Math.max(0, finiteNumber(aircraft?.seen) ?? seenPosition);
   const onGround = aircraft?.alt_baro === 'ground';
@@ -62,8 +69,10 @@ export function normalizeAdsbLolAircraftState(aircraft, nowSeconds) {
     hex,
     String(aircraft?.flight || aircraft?.r || '').trim() || null,
     null,
-    Math.max(0, nowSeconds - seenPosition),
-    Math.max(0, nowSeconds - seen),
+    Number.isFinite(seenPosition)
+      ? Math.max(0, nowSeconds - seenPosition)
+      : null,
+    Number.isFinite(seen) ? Math.max(0, nowSeconds - seen) : null,
     longitude,
     latitude,
     barometricFeet === null ? null : barometricFeet * FOOT_TO_M,
@@ -94,8 +103,28 @@ export function normalizeAdsbLolPointResponse(payload) {
       : Math.floor(
           responseNow > 10_000_000_000 ? responseNow / 1000 : responseNow,
         );
-  const states = (Array.isArray(payload?.ac) ? payload.ac : [])
-    .map((aircraft) => normalizeAdsbLolAircraftState(aircraft, nowSeconds))
-    .filter(Boolean);
-  return { time: nowSeconds, states };
+  const aircraft = Array.isArray(payload?.ac) ? payload.ac : [];
+  const states = [];
+  // Keep the OpenSky vectors unchanged. The regional fallback's extra readsb
+  // status travels alongside them, keyed only to admitted aircraft.
+  const admitted = new Set();
+  const statuses = [];
+  for (const row of aircraft) {
+    const state = normalizeAdsbLolAircraftState(row, nowSeconds);
+    if (!state) continue;
+    states.push(state);
+    // The live contract admits the first valid vector for each ICAO. Its
+    // status must come from that same row, never an invalid or later duplicate.
+    const id = state[0];
+    if (admitted.has(id)) continue;
+    admitted.add(id);
+    if (typeof row.emergency === 'string')
+      statuses.push([id, row.emergency.trim().toLowerCase()]);
+  }
+  const emergencyByIcao = Object.fromEntries(statuses);
+  return {
+    time: nowSeconds,
+    states,
+    ...(Object.keys(emergencyByIcao).length ? { emergencyByIcao } : {}),
+  };
 }

src/data/aircraftEmergency.js

@@ -0,0 +1,93 @@
+/**
+ * Transponder emergency status for one aircraft, from the Mode A squawk and
+ * the ADS-B emergency/priority field.
+ *
+ * Emergency squawks are ICAO-standard worldwide: 7500 unlawful interference,
+ * 7600 radio failure, 7700 general emergency. readsb (adsb.lol) also reports
+ * `emergency`, "a superset of the 7x00 squawks": none, general, lifeguard,
+ * minfuel, nordo, unlawful, downed, reserved. OpenSky state vectors carry the
+ * squawk only.
+ *
+ * The status is what the transponder broadcast in THIS poll, never a finding:
+ * crews pass through 7x00 codes while dialling. Highlighting follows the latest
+ * broadcast, which does not confirm an incident or its resolution.
+ */
+
+/** @constant {string} Tint for aircraft broadcasting an emergency (not a priority). */
+export const EMERGENCY_TINT_CSS = '#FF4444';
+
+const SQUAWK_KINDS = { 7500: 'unlawful', 7600: 'nordo', 7700: 'general' };
+
+const KINDS = {
+  general: { label: 'General emergency', severity: 'emergency' },
+  unlawful: { label: 'Unlawful interference', severity: 'emergency' },
+  nordo: { label: 'Radio failure', severity: 'emergency' },
+  downed: { label: 'Downed aircraft', severity: 'emergency' },
+  minfuel: { label: 'Minimum fuel', severity: 'priority' },
+  lifeguard: { label: 'Lifeguard (medical priority)', severity: 'priority' },
+};
+
+/**
+ * A Mode A code as its four octal digits, else null.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function normalizeSquawk(value) {
+  const code = String(value ?? '').trim();
+  return /^[0-7]{4}$/.test(code) ? code : null;
+}
+
+/**
+ * Emergency status from one observation. Higher severity wins; an ADS-B
+ * emergency wins a tie. A
+ * 7x00 squawk counts even when the ADS-B field says `none`.
+ * @param {{squawk?: unknown, emergency?: unknown}} [observation]
+ * @returns {{kind: string, label: string, severity: 'emergency'|'priority',
+ *   squawk: string|null, source: 'ads-b'|'squawk'}|null} `source` is
+ *   'squawk' when the Mode A code itself names the status (so it can be
+ *   quoted), else 'ads-b'.
+ */
+export function aircraftEmergency({ squawk, emergency } = {}) {
+  const code = normalizeSquawk(squawk);
+  const reported = String(emergency ?? '')
+    .trim()
+    .toLowerCase();
+  const fromAdsb = Object.hasOwn(KINDS, reported);
+  const squawkKind = SQUAWK_KINDS[code] ?? null;
+  const kind =
+    fromAdsb && (KINDS[reported].severity === 'emergency' || !squawkKind)
+      ? reported
+      : squawkKind;
+  if (!kind) return null;
+  return {
+    kind,
+    ...KINDS[kind],
+    squawk: code,
+    source: SQUAWK_KINDS[code] === kind ? 'squawk' : 'ads-b',
+  };
+}
+
+/**
+ * How a summary may phrase the status without flattening it into an incident:
+ * quote the code when the Mode A squawk itself names the status, otherwise
+ * attribute it to the ADS-B emergency field.
+ * @param {{kind?: string, squawk?: string|null, source?: string}|null|undefined} status
+ * @returns {string|null} e.g. 'broadcasting squawk 7700 (general emergency)'
+ *   or 'ADS-B reports general emergency'; null when there is no status.
+ */
+export function emergencyBroadcastPhrase(status) {
+  if (!status || !Object.hasOwn(KINDS, status.kind)) return null;
+  const label = KINDS[status.kind].label.toLowerCase();
+  return status.source === 'squawk' && status.squawk
+    ? `broadcasting squawk ${status.squawk} (${label})`
+    : `ADS-B reports ${label}`;
+}
+
+/**
+ * True when the aircraft is broadcasting an emergency (not a priority status).
+ * @param {{severity?: string}|null|undefined} status
+ * @returns {boolean}
+ */
+export function isEmergency(status) {
+  return status?.severity === 'emergency';
+}

src/data/aircraftEmergency.test.mjs

@@ -0,0 +1,95 @@
+// src/data/aircraftEmergency.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  aircraftEmergency,
+  emergencyBroadcastPhrase,
+  isEmergency,
+  normalizeSquawk,
+} from './aircraftEmergency.js';
+
+test('the three ICAO emergency squawks map to their kinds', () => {
+  assert.equal(aircraftEmergency({ squawk: '7500' }).kind, 'unlawful');
+  assert.equal(aircraftEmergency({ squawk: '7600' }).kind, 'nordo');
+  const general = aircraftEmergency({ squawk: ' 7700 ' });
+  assert.deepEqual(general, {
+    kind: 'general',
+    label: 'General emergency',
+    severity: 'emergency',
+    squawk: '7700',
+    source: 'squawk',
+  });
+});
+
+test('ordinary codes, blanks and non-octal values are not emergencies', () => {
+  for (const squawk of ['1200', '7000', '2000', '', null, undefined, '7800'])
+    assert.equal(aircraftEmergency({ squawk }), null, String(squawk));
+  assert.equal(aircraftEmergency(), null);
+  assert.equal(normalizeSquawk('7800'), null);
+  assert.equal(normalizeSquawk(7700), '7700');
+  assert.equal(normalizeSquawk('770'), null);
+});
+
+test('the ADS-B emergency field wins, and `none` defers to the squawk', () => {
+  const minfuel = aircraftEmergency({ squawk: '4521', emergency: 'MinFuel' });
+  assert.equal(minfuel.kind, 'minfuel');
+  assert.equal(minfuel.severity, 'priority');
+  assert.equal(minfuel.source, 'ads-b');
+  assert.equal(minfuel.squawk, '4521');
+  assert.equal(
+    aircraftEmergency({ squawk: '7700', emergency: 'none' }).source,
+    'squawk',
+  );
+  assert.equal(
+    aircraftEmergency({ squawk: '7700', emergency: 'general' }).source,
+    'squawk',
+    'a code that names the status stays quotable',
+  );
+  assert.equal(
+    aircraftEmergency({ squawk: '1200', emergency: 'general' }).source,
+    'ads-b',
+  );
+  assert.equal(aircraftEmergency({ emergency: 'downed' }).kind, 'downed');
+  assert.equal(aircraftEmergency({ emergency: 'none' }), null);
+  assert.equal(aircraftEmergency({ emergency: 'reserved' }), null);
+});
+
+test('priority statuses are reported but are not emergencies', () => {
+  assert.equal(isEmergency(aircraftEmergency({ squawk: '7700' })), true);
+  assert.equal(
+    isEmergency(aircraftEmergency({ emergency: 'lifeguard' })),
+    false,
+  );
+  assert.equal(isEmergency(aircraftEmergency({ emergency: 'minfuel' })), false);
+  assert.equal(isEmergency(null), false);
+});
+
+test('the broadcast phrase quotes a naming code, else attributes ADS-B', () => {
+  assert.equal(
+    emergencyBroadcastPhrase(aircraftEmergency({ squawk: '7700' })),
+    'broadcasting squawk 7700 (general emergency)',
+  );
+  assert.equal(
+    emergencyBroadcastPhrase(
+      aircraftEmergency({ squawk: '1200', emergency: 'general' }),
+    ),
+    'ADS-B reports general emergency',
+  );
+  assert.equal(
+    emergencyBroadcastPhrase(aircraftEmergency({ emergency: 'lifeguard' })),
+    'ADS-B reports lifeguard (medical priority)',
+  );
+  assert.equal(emergencyBroadcastPhrase(null), null);
+  assert.equal(emergencyBroadcastPhrase({ kind: 'reserved' }), null);
+});
+
+test('an emergency squawk outranks an ADS-B priority', () => {
+  assert.equal(
+    aircraftEmergency({ squawk: '7700', emergency: 'lifeguard' }).kind,
+    'general',
+  );
+  assert.equal(
+    aircraftEmergency({ squawk: '7500', emergency: 'minfuel' }).kind,
+    'unlawful',
+  );
+});

src/data/aircraftEmergencyAnalyst.test.mjs

@@ -0,0 +1,524 @@
+import * as Cesium from 'cesium';
+import { TRACKED_ICON_COLOR } from '../layers/military/policy.js';
+import { createRendering as civilRendering } from '../layers/flights/rendering.js';
+import { createRendering as militaryRendering } from '../layers/military/rendering.js';
+import { createMilitarySnapshotRenderer } from '../layers/military/snapshotRenderer.js';
+import { aircraftEmergency } from './aircraftEmergency.js';
+// Source-to-voice provenance, status retention/clearing, contact-time contracts,
+// and civil/military billboard, Cockpit and model tint regressions.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { openSkySnapshot, readsbSnapshot } from '../sources/live/index.js';
+import { FlightRecords } from '../layers/flights/records.js';
+import { MilitaryFlightRecords } from '../layers/military/records.js';
+import { mapAnalystRecord as mapFlight } from './flights.js';
+import { mapAnalystRecord as mapMilitary } from './militaryFlights.js';
+import { createAnalystEngine } from './analystEngine.js';
+import { normalizeAdsbLolPointResponse } from './adsbLolFallback.js';
+import { createGevActionRunner } from '../voice/gevActions.js';
+
+const NOW_MS = 1800000000000;
+
+test('fallback status belongs to the first valid admitted aircraft row', () => {
+  const valid = { hex: 'a1b2c3', lat: 30, lon: -97, squawk: '1200' };
+  for (const status of [undefined, 'general', 'none']) {
+    const payload = normalizeAdsbLolPointResponse({
+      now: NOW_MS,
+      ac: [
+        { ...valid, lat: 100, emergency: 'general' },
+        { ...valid, emergency: status },
+        { ...valid, lat: null, emergency: 'general' },
+        { ...valid, emergency: status === 'general' ? 'none' : 'general' },
+      ],
+    });
+    const snapshot = openSkySnapshot(payload, { now: NOW_MS });
+    assert.equal(snapshot.records.length, 1);
+    assert.equal(snapshot.records[0].emergency, status);
+    assert.equal(snapshot.records[0].latitude, 30);
+  }
+});
+
+function civilStore() {
+  return new FlightRecords({
+    geoidHeight: () => 0,
+    cachedGroundFloor: () => null,
+    floorAltitudeM: (value) => value,
+    approxDistanceKm: () => 0,
+  });
+}
+const receiveContext = {
+  viewerLatDeg: null,
+  viewerLonDeg: null,
+  trackedId: null,
+  floorWarmPoints: [],
+};
+
+test('real civil fallback preserves ADS-B emergency and priority, then clears', () => {
+  const store = civilStore();
+  const aircraft = {
+    hex: 'a1b2c3',
+    flight: 'TEST1',
+    lat: 30,
+    lon: -97,
+    alt_baro: 10000,
+    gs: 150,
+    track: 90,
+    squawk: '1200',
+    seen: 3,
+    seen_pos: 1,
+  };
+  for (const [status, expectedKind, flagged] of [
+    ['general', 'general', true],
+    ['minfuel', 'minfuel', false],
+    ['none', null, false],
+  ]) {
+    const payload = normalizeAdsbLolPointResponse({
+      now: NOW_MS,
+      ac: [{ ...aircraft, emergency: status }],
+    });
+    assert.equal(
+      payload.states[0].length,
+      18,
+      'fallback vectors retain the OpenSky shape',
+    );
+    const [observation] = openSkySnapshot(payload, { now: NOW_MS }).records;
+    const result = mapFlight(
+      aircraft.hex,
+      store.receive(observation, receiveContext).meta,
+    );
+    assert.equal(result.emergency, flagged);
+    assert.equal(result.emergencyKind, expectedKind);
+    assert.equal(result.emergencySource, expectedKind ? 'ads-b' : null);
+    assert.equal(result.lastContactAtMs, NOW_MS - 3000);
+  }
+});
+
+test('changed status without contact time retains general contact, including voice projection', async () => {
+  const store = civilStore();
+  const [observation] = readsbSnapshot(
+    {
+      ac: [
+        {
+          hex: 'a1b2c3',
+          flight: 'TEST1',
+          lat: 30,
+          lon: -97,
+          alt_baro: 10000,
+          gs: 150,
+          track: 90,
+          squawk: '1200',
+          emergency: 'general',
+          seen: 3,
+          seen_pos: 1,
+        },
+      ],
+    },
+    { observedAtMs: NOW_MS, now: NOW_MS },
+  ).records;
+  store.receive(observation, receiveContext);
+  const meta = store.receive(
+    { ...observation, contactTimeMs: null, squawk: '7600', emergency: 'none' },
+    receiveContext,
+  ).meta;
+  const record = mapFlight(observation.id, meta);
+  assert.equal(record.emergencyKind, 'nordo');
+  assert.equal(record.lastContactAtMs, NOW_MS - 3000);
+  assert.equal(Object.hasOwn(record, 'observedAtMs'), false);
+  globalThis.window = globalThis.window || {
+    clearTimeout,
+    setTimeout,
+    requestIdleCallback: null,
+  };
+  const flights = {
+    id: 'flights',
+    source: 'fixture',
+    getStats: () => ({ count: 1 }),
+    getAnalystRecords: () => [record],
+  };
+  const runner = createGevActionRunner({
+    viewer: {
+      clock: { onTick: { addEventListener: () => () => {} } },
+      scene: { canvas: { addEventListener() {}, removeEventListener() {} } },
+      camera: {
+        moveEnd: { addEventListener() {} },
+        positionCartographic: {
+          height: 300000,
+          latitude: 0.52,
+          longitude: -1.71,
+        },
+      },
+    },
+    styleManager: {
+      getContextModeState: () => ({ mode: null, active: false }),
+      getCockpitState: () => ({ active: false }),
+    },
+    dataManager: {
+      layers: new Map([['flights', { module: flights }]]),
+      isEnabled: (id) => id === 'flights',
+      getAll: () => [
+        { id: 'flights', name: 'Flights', enabled: true, stats: { count: 1 } },
+      ],
+    },
+  });
+  try {
+    const result = await runner('analyst_query', {
+      layers: ['flights'],
+      scope: { kind: 'anywhere' },
+      filters: [{ field: 'emergency', op: 'eq', value: true }],
+    });
+    assert.equal(result.ok, true);
+    assert.equal(result.items[0].emergency, true);
+    assert.equal(result.items[0].lastContactAtMs, NOW_MS - 3000);
+    assert.equal(result.items[0].emergencySource, 'squawk');
+    assert.equal(
+      result.items[0].emergencyBroadcast,
+      'broadcasting squawk 7600 (radio failure)',
+    );
+    assert.equal(
+      Object.hasOwn(result.items[0], 'time'),
+      false,
+      'general contact is not a generic incident timestamp',
+    );
+  } finally {
+    runner.dispose?.();
+  }
+});
+
+// OpenSky /states/all: [icao24, callsign, origin_country, time_position,
+// last_contact, lon, lat, baro_alt, on_ground, velocity, true_track,
+// vertical_rate, sensors, geo_alt, squawk, spi, position_source, category].
+const OPENSKY = {
+  time: NOW_MS / 1000,
+  states: [
+    [
+      'a1b2c3',
+      'SWA696  ',
+      'United States',
+      NOW_MS / 1000 - 6,
+      NOW_MS / 1000 - 3,
+      -97.67,
+      30.19,
+      3000,
+      false,
+      150,
+      180,
+      -5,
+      null,
+      3040,
+      '7700',
+      false,
+      0,
+      4,
+    ],
+  ],
+};
+
+// adsb.lol /v2/mil: readsb aircraft with `seen`/`seen_pos` ages in seconds.
+const ADSB_LOL = {
+  ac: [
+    {
+      hex: 'ae01ce',
+      flight: 'RCH123  ',
+      t: 'C17',
+      lat: 31.1,
+      lon: -97.4,
+      alt_baro: 18000,
+      gs: 300,
+      track: 90,
+      squawk: '1200',
+      emergency: 'general',
+      seen: 1.5,
+      seen_pos: 2,
+    },
+  ],
+};
+
+function civilAnalystRecord() {
+  const [row] = openSkySnapshot(OPENSKY, { now: NOW_MS }).records;
+  const store = new FlightRecords({
+    geoidHeight: () => 0,
+    cachedGroundFloor: () => null,
+    floorAltitudeM: (altitude) => altitude,
+    approxDistanceKm: () => 0,
+  });
+  const { meta } = store.receive(row, {
+    viewerLatDeg: null,
+    viewerLonDeg: null,
+    trackedId: null,
+    floorWarmPoints: [],
+  });
+  return mapFlight(row.id, meta);
+}
+
+function militaryAnalystRecord() {
+  const [row] = readsbSnapshot(ADSB_LOL, {
+    observedAtMs: NOW_MS,
+    now: NOW_MS,
+  }).records;
+  const store = new MilitaryFlightRecords({
+    geoidHeight: () => 0,
+    cachedGroundFloor: () => null,
+    floorAltitudeM: (altitude) => altitude,
+  });
+  const { meta } = store.receive(row, {
+    observedAtMs: NOW_MS,
+    floorWarmPoints: [],
+    modelOwnsVisual: false,
+  });
+  return mapMilitary(row.id, meta);
+}
+
+test('OpenSky 7700 and adsb.lol emergency=general differ only in provenance', () => {
+  const civil = civilAnalystRecord();
+  const military = militaryAnalystRecord();
+
+  assert.equal(civil.emergency, true);
+  assert.equal(civil.emergencyKind, 'general');
+  assert.equal(civil.squawk, '7700');
+  assert.equal(civil.emergencySource, 'squawk');
+  assert.equal(
+    civil.emergencyBroadcast,
+    'broadcasting squawk 7700 (general emergency)',
+  );
+  assert.equal(civil.lastContactAtMs, NOW_MS - 3000, 'OpenSky last_contact');
+
+  assert.equal(military.emergency, true);
+  assert.equal(military.emergencyKind, 'general');
+  assert.equal(military.squawk, '1200', 'the code is not an emergency code');
+  assert.equal(military.emergencySource, 'ads-b');
+  assert.equal(military.emergencyBroadcast, 'ADS-B reports general emergency');
+  assert.equal(military.lastContactAtMs, NOW_MS - 1500, 'snapshot time - seen');
+});
+
+test('the analyst can filter emergencies by source', async () => {
+  const records = {
+    flights: [civilAnalystRecord()],
+    military: [militaryAnalystRecord()],
+  };
+  const engine = createAnalystEngine({
+    getRecords: (key) => records[key] || [],
+    resolveRegionRing: async () => null,
+    getViewContext: () => ({ lat: 30.5, lon: -97.5, viewRadiusKm: 500 }),
+  });
+  const query = (value) =>
+    engine.query({
+      layers: ['flights', 'military'],
+      scope: { kind: 'anywhere' },
+      filters: [
+        { field: 'emergency', op: 'eq', value: true },
+        { field: 'emergencySource', op: 'eq', value },
+      ],
+    });
+  const bySquawk = await query('squawk');
+  assert.deepEqual(
+    bySquawk.items.map((item) => [item.icao24, item.emergencyBroadcast]),
+    [['a1b2c3', 'broadcasting squawk 7700 (general emergency)']],
+  );
+  const byAdsb = await query('ads-b');
+  assert.deepEqual(
+    byAdsb.items.map((item) => [item.icao24, item.emergencyBroadcast]),
+    [['ae01ce', 'ADS-B reports general emergency']],
+  );
+});
+
+test('military status changes retain only the latest known general contact', () => {
+  const store = new MilitaryFlightRecords({
+    geoidHeight: () => 0,
+    cachedGroundFloor: () => null,
+    floorAltitudeM: (v) => v,
+  });
+  const [observation] = readsbSnapshot(ADSB_LOL, {
+    observedAtMs: NOW_MS,
+    now: NOW_MS,
+  }).records;
+  const context = {
+    observedAtMs: NOW_MS,
+    floorWarmPoints: [],
+    modelOwnsVisual: false,
+  };
+  const unknown = mapMilitary(
+    observation.id,
+    store.receive({ ...observation, contactTimeMs: null }, context).meta,
+  );
+  assert.equal(unknown.lastContactAtMs, null);
+  store.receive(observation, context);
+  const changed = mapMilitary(
+    observation.id,
+    store.receive(
+      {
+        ...observation,
+        contactTimeMs: null,
+        squawk: '7600',
+        emergency: 'none',
+      },
+      context,
+    ).meta,
+  );
+  assert.equal(changed.emergencyKind, 'nordo');
+  assert.equal(changed.lastContactAtMs, NOW_MS - 1500);
+});
+
+test('fallback missing contact age retains known contact through the real converter', () => {
+  const store = civilStore();
+  const row = {
+    hex: 'a1b2c3',
+    lat: 30,
+    lon: -97,
+    squawk: '1200',
+    emergency: 'general',
+    seen: 3,
+    seen_pos: 1,
+  };
+  const receive = (row) =>
+    store.receive(
+      openSkySnapshot(
+        normalizeAdsbLolPointResponse({ now: NOW_MS, ac: [row] }),
+        { now: NOW_MS },
+      ).records[0],
+      receiveContext,
+    ).meta;
+  const first = receive(row);
+  const second = receive({ ...row, seen: undefined, seen_pos: undefined });
+  assert.equal(second.lastContactEpochMs, first.lastContactEpochMs);
+});
+
+test('one omitted ADS-B status poll is retained; explicit none and changed squawk clear immediately', () => {
+  const store = civilStore();
+  const row = {
+    hex: 'a1b2c3',
+    lat: 30,
+    lon: -97,
+    squawk: '1200',
+    emergency: 'general',
+    seen: 3,
+  };
+  const receive = (row) =>
+    store.receive(
+      openSkySnapshot(
+        normalizeAdsbLolPointResponse({ now: NOW_MS, ac: [row] }),
+        { now: NOW_MS },
+      ).records[0],
+      receiveContext,
+    ).meta;
+  assert.equal(receive(row).emergency.kind, 'general');
+  assert.equal(
+    receive({ ...row, emergency: undefined }).emergency?.kind,
+    'general',
+  );
+  assert.equal(receive({ ...row, emergency: undefined }).emergency, null);
+  receive(row);
+  assert.equal(receive({ ...row, emergency: 'none' }).emergency, null);
+  receive(row);
+  assert.equal(
+    receive({ ...row, emergency: undefined, squawk: '2000' }).emergency,
+    null,
+  );
+});
+
+function renderHarness(factory) {
+  const flightState = { records: { data: new Map() }, _trackedIcao: null };
+  const rendering = factory({
+    flightState,
+    services: {
+      militaryRegistry: { isMilitaryIcao: (id) => id === 'mil' },
+      aircraftPresentation: {},
+      camera: {},
+      focus: {},
+      recession: {},
+    },
+    parts: {},
+  });
+  return { flightState, rendering };
+}
+
+test('tint priorities cover normal, priority, emergency, tracking and Cockpit dots', () => {
+  for (const factory of [civilRendering, militaryRendering]) {
+    const { flightState, rendering } = renderHarness(factory);
+    const normal = rendering._fleetBillboardColor('civil', {});
+    assert.equal(
+      rendering._fleetBillboardColor('civil', {
+        emergency: aircraftEmergency({ emergency: 'minfuel' }),
+      }),
+      normal,
+    );
+    const red = rendering._fleetBillboardColor('civil', {
+      emergency: aircraftEmergency({ squawk: '7700' }),
+    });
+    assert.ok(red.red > 0.9 && red.green < 0.5);
+    flightState.records.data.set('civil', {
+      emergency: aircraftEmergency({ squawk: '7700' }),
+    });
+    assert.equal(rendering._modelColor('civil'), red);
+    if (rendering._cockpitContactColor)
+      assert.equal(rendering._cockpitContactColor('civil'), red);
+    flightState._trackedIcao = 'civil';
+    assert.equal(
+      rendering._modelColor('civil'),
+      factory === civilRendering ? Cesium.Color.CYAN : TRACKED_ICON_COLOR,
+    );
+    flightState._trackedIcao = null;
+    flightState.records.data.set('civil', { emergency: null });
+    assert.equal(rendering._modelColor('civil'), normal);
+  }
+});
+
+test('GERMAN: an existing untracked military billboard repaints each poll without alpha loss', () => {
+  const { flightState, rendering } = renderHarness(militaryRendering);
+  const bb = {
+    color: rendering._fleetBillboardColor('abc123').withAlpha(0.65),
+  };
+  Object.assign(flightState, {
+    _billboards: new Map([['abc123', bb]]),
+    _models: new Map(),
+    _positionHistory: new Map(),
+    _cullPositions: new Map(),
+    _groundSnap: { forget() {} },
+    _cockpitContactMode: false,
+  });
+  const records = new MilitaryFlightRecords({
+    geoidHeight: () => 0,
+    cachedGroundFloor: () => null,
+    floorAltitudeM: (value) => value,
+  });
+  flightState.records = records;
+  const apply = createMilitarySnapshotRenderer({
+    flightState,
+    records,
+    groundFloor: { warmGroundFloor() {}, cachedGroundFloor: () => null },
+    meshFloor: { sampleMeshFloorCells() {} },
+    militaryRegistry: { registerMilitaryIcaos() {} },
+    rendering: {
+      ...rendering,
+      _syncModelToClass() {},
+      _applyFleetBillboardPresentation() {},
+    },
+    motion: {},
+    tracking: {},
+    queries: {},
+  });
+  for (const [emergency, red] of [
+    ['general', true],
+    ['none', false],
+    ['general', true],
+  ]) {
+    const snapshot = readsbSnapshot(
+      {
+        ac: [
+          {
+            hex: 'abc123',
+            lat: 30,
+            lon: -97,
+            alt_baro: 10000,
+            squawk: '1200',
+            emergency,
+            seen_pos: 1,
+          },
+        ],
+      },
+      { observedAtMs: NOW_MS },
+    );
+    apply(snapshot, {});
+    assert.equal(bb.color.green < 0.5, red);
+    assert.equal(bb.color.alpha, 0.65);
+  }
+});

src/data/aircraftRecession.js

@@ -242,7 +242,7 @@ export function applyAircraftBillboardTreatment({
 }
 
 /**
- * Apply the already-composed aircraft alpha to an ambient glTF model without
+ * Apply layer-owned hue and composed aircraft alpha to an ambient glTF model without
  * disturbing Cesium's existing MIX/colorBlendAmount presentation semantics.
  * @param {object} input
  * @param {object} input.model
@@ -261,7 +261,10 @@ export function applyAircraftModelTreatment({
   if (!model || !baseColor || !Number.isFinite(alpha)) return 0;
   if (
     Number.isFinite(model.color?.alpha) &&
-    Math.abs(model.color.alpha - alpha) <= tuning.writeEpsilon
+    Math.abs(model.color.alpha - alpha) <= tuning.writeEpsilon &&
+    model.color.red === baseColor.red &&
+    model.color.green === baseColor.green &&
+    model.color.blue === baseColor.blue
   )
     return 0;
   model.color = baseColor.withAlpha(alpha);

src/data/aircraftRecession.test.mjs

@@ -142,3 +142,15 @@ test('ambient model presentation receives composed alpha without changing blend
   assert.equal(model.colorBlendAmount, 0.9);
   assert.equal(applyAircraftModelTreatment({ model, baseColor: color, alpha: 0.2, params }), 0);
 });
+
+
+test('model hue changes at constant alpha, then clears without redundant writes', () => {
+  const color = (red,green,blue) => ({red,green,blue,withAlpha(alpha){return {red,green,blue,alpha};}});
+  const model = {color:color(1,1,1).withAlpha(0.65)};
+  assert.equal(applyAircraftModelTreatment({model,baseColor:color(1,0.2,0.2),alpha:0.65}),1);
+  assert.equal(model.color.green,0.2);
+  assert.equal(model.color.alpha,0.65);
+  assert.equal(applyAircraftModelTreatment({model,baseColor:color(1,0.2,0.2),alpha:0.65}),0);
+  assert.equal(applyAircraftModelTreatment({model,baseColor:color(1,1,1),alpha:0.65}),1);
+  assert.equal(model.color.green,1);
+});

src/data/ambiguous-camera-direction.test.mjs

@@ -0,0 +1,30 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { directionToHeading } from './directionText.js';
+test('conflicting facing directions cannot manufacture one heading', () => {
+  for (const bare of [false, true]) {
+    for (const value of ['NB / SB', 'EASTBOUND WESTBOUND', 'NE SW'])
+      assert.ok(Number.isNaN(directionToHeading(value, bare)), value);
+    assert.equal(directionToHeading('NB northbound', bare), 0);
+    assert.equal(directionToHeading('IH-35 SOUTHBOUND AT 15TH', bare), 180);
+  }
+  assert.ok(Number.isNaN(directionToHeading('North / East', true)));
+  assert.equal(directionToHeading('West / SR-24', true), 270);
+});
+
+test('travel tokens retain precedence over quadrant streets and bare words', () => {
+  for (const [text, heading] of [
+    ['I-5 NB at NE 45th St', 0],
+    ['SR 520 EB at NE 148th', 90],
+    ['US 13 SB @ SW Front St', 180],
+  ]) {
+    for (const bare of [false, true])
+      assert.equal(directionToHeading(text, bare), heading);
+  }
+  assert.equal(
+    directionToHeading('Hwy 401 east of Keele St - Westbound', true),
+    270,
+  );
+  assert.equal(directionToHeading('NE near West St', true), 45);
+  assert.ok(Number.isNaN(directionToHeading('NB SB near NE St', true)));
+});

src/data/cameraFraming.js

@@ -0,0 +1,15 @@
+import * as Cesium from 'cesium';
+
+/** Camera range with breathing room in both viewport dimensions. */
+export function rangeForBoundingSphere(viewer, radius) {
+  const frustum = viewer.camera?.frustum;
+  const verticalFov = Number(frustum?.fov) || Cesium.Math.toRadians(60);
+  const aspectRatio = Math.max(0.5, Number(frustum?.aspectRatio) || 1);
+  const horizontalFov = 2 * Math.atan(Math.tan(verticalFov / 2) * aspectRatio);
+  const limitingFov = Math.min(verticalFov, horizontalFov);
+  // Target 57% sphere occupancy so perspective still leaves at least 40%
+  // measured roof-to-base breathing room in ordinary oblique building views.
+  const occupiedViewportFraction = 0.57;
+  const desiredAngularRadius = (limitingFov * occupiedViewportFraction) / 2;
+  return (radius / Math.sin(desiredAngularRadius)) * 1.05;
+}

src/data/cctvNyc.test.mjs

@@ -0,0 +1,391 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  loadNycSourcesFromOpenData,
+  nycCameraIsOnline,
+  nycCameraName,
+  nycCameraToSource,
+} from '../../server/providers/cctv/sources.js';
+import {
+  DEFAULT_CCTV_MAX_SOURCES,
+  DEFAULT_NYC_MAX_SOURCES,
+  NYC_CAMERAS_URL,
+  NYC_GROUND_ELEVATION_M,
+  NYC_IMAGE_ORIGIN,
+  NYC_IMAGE_URL,
+  NYC_MAX_CATALOG_BYTES,
+} from '../../server/providers/cctv/constants.js';
+import {
+  CAMERA_CODE_MAX_CHARS,
+  isLikelyNycCoordinate,
+} from '../../server/providers/cctv/normalize.js';
+import { createCctvCatalog } from '../../server/providers/cctv/catalog.js';
+
+/**
+ * A response whose body is a live stream, plus a flag that flips when the
+ * stream is cancelled. A rejection path that returns without cancelling holds
+ * the transport open, so the flag is what the refusal tests actually assert.
+ */
+const streamingResponse = (init = {}) => {
+  const state = { cancelled: false };
+  const body = new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode('['));
+    },
+    cancel() {
+      state.cancelled = true;
+    },
+  });
+  return { response: new Response(body, init), state };
+};
+
+const MIDTOWN_ID = '8a6bc417-4877-4ebe-8052-88c1b261baf1';
+const BROOKLYN_ID = '11111111-2222-3333-4444-555555555555';
+
+/** One TMC camera row, shaped like the live `webcams.nyctmc.org` payload. */
+const row = (overrides = {}) => ({
+  id: MIDTOWN_ID,
+  name: 'Central Park West @ 86 St',
+  latitude: 40.785302,
+  longitude: -73.969353,
+  area: 'Manhattan',
+  isOnline: 'true',
+  imageUrl: NYC_IMAGE_URL(MIDTOWN_ID),
+  ...overrides,
+});
+
+test('a NYC row maps to a source on the pinned HTTPS frame host', () => {
+  const source = nycCameraToSource(row());
+  assert.equal(source.id, `nyc-${MIDTOWN_ID}`);
+  assert.equal(source.name, 'Central Park West @ 86 St');
+  assert.equal(source.city, 'Manhattan');
+  assert.equal(source.cityId, 'nyc');
+  assert.equal(source.provider, 'NYC DOT Traffic Management Center');
+  assert.equal(source.lat, 40.785302);
+  assert.equal(source.lon, -73.969353);
+  assert.equal(source.feedType, 'image');
+  assert.equal(source.sourceKind, 'nyc-dot-tmc');
+  assert.equal(
+    source.license,
+    'Public NYC DOT Traffic Management Center traffic camera',
+  );
+  assert.equal(source.groundElevationM, NYC_GROUND_ELEVATION_M);
+  assert.equal(source.url, NYC_IMAGE_URL(MIDTOWN_ID));
+  assert.equal(source.url, source.snapshotUrl);
+  assert.ok(source.url.startsWith(NYC_IMAGE_ORIGIN));
+  assert.equal(source.headingConfidence, 'low');
+  assert.ok(Number.isFinite(source.headingDeg));
+});
+
+test('frame URLs are synthesized from the UUID; the payload URL is ignored', () => {
+  const source = nycCameraToSource(
+    row({ imageUrl: 'https://evil.example/cameras/x/image' }),
+  );
+  assert.equal(source.url, NYC_IMAGE_URL(MIDTOWN_ID));
+  assert.equal(source.snapshotUrl, source.url);
+});
+
+test('offline cameras, off-city geometry and unusable ids are dropped', () => {
+  assert.equal(nycCameraToSource(row({ isOnline: 'false' })), null);
+  assert.equal(nycCameraToSource(row({ isOnline: false })), null);
+  assert.equal(
+    nycCameraToSource(row({ isOnline: 'TRUE' })).id,
+    `nyc-${MIDTOWN_ID}`,
+  );
+  assert.equal(
+    nycCameraToSource(row({ isOnline: true })).id,
+    `nyc-${MIDTOWN_ID}`,
+  );
+  // Austin: a plausible lat/lon, but not a New York camera.
+  assert.equal(
+    nycCameraToSource(row({ latitude: 30.2672, longitude: -97.7431 })),
+    null,
+  );
+  assert.equal(nycCameraToSource(row({ latitude: 0, longitude: 0 })), null);
+  assert.equal(nycCameraToSource(row({ id: '../etc/passwd' })), null);
+  assert.equal(nycCameraToSource(row({ id: 'not-a-uuid' })), null);
+  assert.equal(nycCameraToSource(row({ id: `${MIDTOWN_ID}/../x` })), null);
+  assert.equal(nycCameraToSource(null), null);
+});
+
+test('ids lower-case the UUID and unknown boroughs fall back to New York', () => {
+  const mixed = nycCameraToSource(
+    row({ id: MIDTOWN_ID.toUpperCase(), area: 'Long Island' }),
+  );
+  assert.equal(mixed.id, `nyc-${MIDTOWN_ID}`);
+  assert.equal(mixed.city, 'New York');
+  assert.equal(
+    mixed.url,
+    NYC_IMAGE_URL(MIDTOWN_ID.toUpperCase()),
+    'the registered frame path keeps the catalog UUID spelling',
+  );
+});
+
+test('a nameless row still gets a label', () => {
+  assert.equal(
+    nycCameraName({ name: '  FDR Drive @ 23 St ' }, 'nyc-x'),
+    'FDR Drive @ 23 St',
+  );
+  assert.equal(nycCameraName({}, `nyc-${MIDTOWN_ID}`), 'NYC Camera 8a6bc417');
+  assert.equal(nycCameraIsOnline('true'), true);
+  assert.equal(nycCameraIsOnline('false'), false);
+});
+
+test('the unselected label is the intersection, trimmed to the code width', () => {
+  assert.equal(nycCameraToSource(row()).code, 'CENTRAL PARK WEST @ 86 ST');
+  const long = nycCameraToSource(
+    row({
+      name: 'Brooklyn Queens Expressway @ Atlantic Avenue / Flatbush Avenue Extension',
+    }),
+  );
+  assert.ok(long.code.length <= CAMERA_CODE_MAX_CHARS);
+  assert.ok(long.code.endsWith('…'));
+  assert.ok(long.code.startsWith('BROOKLYN'));
+});
+
+test('the loader reads the keyless catalog and collapses duplicate ids', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const requested = [];
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    requested.push([String(url), init.redirect]);
+    return Response.json([
+      row({ latitude: 40.758, longitude: -73.9855 }),
+      row({
+        name: 'Central Park West @ 86 St (duplicate)',
+        latitude: 40.758,
+        longitude: -73.9855,
+      }),
+      row({
+        id: BROOKLYN_ID,
+        name: 'Atlantic Ave @ Flatbush Ave',
+        latitude: 40.65,
+        longitude: -73.96,
+        area: 'Brooklyn',
+        imageUrl: NYC_IMAGE_URL(BROOKLYN_ID),
+      }),
+      row({ isOnline: 'false', name: 'Offline camera' }),
+      row({ id: 'https://evil.example/x' }),
+    ]);
+  });
+  const cameras = await loadNycSourcesFromOpenData();
+  assert.deepEqual(requested, [[NYC_CAMERAS_URL, 'manual']]);
+  assert.deepEqual(
+    cameras.map((camera) => camera.id),
+    // Nearest to a borough anchor first: the Times Square camera before Brooklyn.
+    [`nyc-${MIDTOWN_ID}`, `nyc-${BROOKLYN_ID}`],
+  );
+  assert.equal(cameras[0].name, 'Central Park West @ 86 St');
+  assert.equal(cameras[1].city, 'Brooklyn');
+});
+
+test('an upstream failure yields an empty pack and releases the response', async (t) => {
+  t.mock.method(console, 'warn', () => {});
+  const failed = streamingResponse({ status: 503 });
+  t.mock.method(globalThis, 'fetch', async () => failed.response);
+  assert.deepEqual(await loadNycSourcesFromOpenData(), []);
+  assert.equal(failed.state.cancelled, true, 'the failed body is cancelled');
+
+  t.mock.restoreAll();
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async () => {
+    throw new Error('network down');
+  });
+  assert.deepEqual(await loadNycSourcesFromOpenData(), []);
+});
+
+test('the catalog fetch refuses redirects and oversized bodies', async (t) => {
+  t.mock.method(console, 'warn', () => {});
+  const seen = [];
+  const redirected = streamingResponse({
+    status: 302,
+    headers: { location: 'https://evil.example/cameras.json' },
+  });
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    seen.push([String(url), init.redirect]);
+    return redirected.response;
+  });
+  assert.deepEqual(await loadNycSourcesFromOpenData(), []);
+  assert.deepEqual(seen, [[NYC_CAMERAS_URL, 'manual']]);
+  assert.equal(
+    redirected.state.cancelled,
+    true,
+    'the redirect body is cancelled',
+  );
+
+  t.mock.restoreAll();
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async () => {
+    const body = JSON.stringify([row()]);
+    return new Response(body, {
+      headers: {
+        'Content-Type': 'application/json',
+        'content-length': String(NYC_MAX_CATALOG_BYTES + 1),
+      },
+    });
+  });
+  assert.deepEqual(await loadNycSourcesFromOpenData(), []);
+
+  t.mock.restoreAll();
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async () => {
+    const oversized = 'x'.repeat(NYC_MAX_CATALOG_BYTES + 1024);
+    return new Response(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(oversized));
+          controller.close();
+        },
+      }),
+      { headers: { 'Content-Type': 'application/json' } },
+    );
+  });
+  assert.deepEqual(await loadNycSourcesFromOpenData(), []);
+});
+
+test('a reduced pack cap keeps cameras nearest the borough anchors', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const saved = process.env.CCTV_NYC_MAX_SOURCES;
+  t.after(() => {
+    if (saved === undefined) delete process.env.CCTV_NYC_MAX_SOURCES;
+    else process.env.CCTV_NYC_MAX_SOURCES = saved;
+  });
+  process.env.CCTV_NYC_MAX_SOURCES = '8';
+  const rows = [
+    // Far southern Staten Island, listed first so only distance can keep them.
+    ...[40.5, 40.505, 40.51, 40.515, 40.52, 40.525].map((lat, i) =>
+      row({
+        id: `aaaaaaaa-bbbb-cccc-dddd-${String(i).padStart(12, '0')}`,
+        latitude: lat,
+        longitude: -74.24,
+        area: 'Staten Island',
+        name: `SI ${i}`,
+      }),
+    ),
+    ...[40.758, 40.757, 40.756, 40.755, 40.754, 40.753].map((lat, i) =>
+      row({
+        id: `bbbbbbbb-cccc-dddd-eeee-${String(i).padStart(12, '0')}`,
+        latitude: lat,
+        longitude: -73.9855,
+        area: 'Manhattan',
+        name: `Midtown ${i}`,
+      }),
+    ),
+  ];
+  t.mock.method(globalThis, 'fetch', async () => Response.json(rows));
+  const cameras = await loadNycSourcesFromOpenData();
+  assert.equal(cameras.length, 8);
+  assert.deepEqual(
+    cameras.map((camera) => camera.city),
+    [
+      'Manhattan',
+      'Manhattan',
+      'Manhattan',
+      'Manhattan',
+      'Manhattan',
+      'Manhattan',
+      'Staten Island',
+      'Staten Island',
+    ],
+    'Midtown fills first; the Staten Island anchor still keeps a share',
+  );
+});
+
+/**
+ * Serve the NYC catalog to the NYC endpoint and an empty payload to every
+ * other pack, so one catalog refresh exercises the registration without
+ * reaching the network.
+ */
+const runCatalogWithMockedUpstreams = async (t) => {
+  const requested = [];
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    const href = String(url);
+    requested.push(href);
+    if (href === NYC_CAMERAS_URL) {
+      return Response.json([
+        row({ latitude: 40.758, longitude: -73.9855 }),
+        row({
+          id: BROOKLYN_ID,
+          name: 'Atlantic Ave @ Flatbush Ave',
+          latitude: 40.65,
+          longitude: -73.96,
+          area: 'Brooklyn',
+        }),
+      ]);
+    }
+    return Response.json([]);
+  });
+  const sources = await createCctvCatalog({ sourceRoot: '/nonexistent' })();
+  return { requested, sources };
+};
+
+/** Run one catalog refresh with CCTV_NYC_ENABLED set to `flag` (undefined
+ * leaves it unset), restoring the environment afterwards. */
+const runCatalogWithNycFlag = async (t, flag) => {
+  const saved = { ...process.env };
+  try {
+    delete process.env.CCTV_SOURCES_FILE;
+    delete process.env.CCTV_SOURCES_JSON;
+    if (flag === undefined) delete process.env.CCTV_NYC_ENABLED;
+    else process.env.CCTV_NYC_ENABLED = flag;
+    return await runCatalogWithMockedUpstreams(t);
+  } finally {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in saved)) delete process.env[key];
+    }
+    Object.assign(process.env, saved);
+  }
+};
+
+test('CCTV_NYC_ENABLED=1 wires the NYC lane into the catalog', async (t) => {
+  const { requested, sources } = await runCatalogWithNycFlag(t, '1');
+  assert.ok(
+    requested.includes(NYC_CAMERAS_URL),
+    'the catalog refresh invokes the NYC loader',
+  );
+  assert.deepEqual(
+    sources.filter((s) => s.cityId === 'nyc').map((s) => s.id),
+    [`nyc-${MIDTOWN_ID}`, `nyc-${BROOKLYN_ID}`],
+    'NYC cameras reach the served catalog through the registered lane',
+  );
+});
+
+// NYC DOT requires a data-sharing agreement for this feed, so an install that
+// has not opted in must never contact it.
+for (const [label, flag] of [
+  ['an unset CCTV_NYC_ENABLED', undefined],
+  ['an empty CCTV_NYC_ENABLED', ''],
+  ['CCTV_NYC_ENABLED=0', '0'],
+  ['CCTV_NYC_ENABLED=true', 'true'],
+]) {
+  test(`${label} makes no NYC request`, async (t) => {
+    const { requested, sources } = await runCatalogWithNycFlag(t, flag);
+    assert.ok(requested.length > 0, 'the other packs still refreshed');
+    assert.equal(
+      requested.some((href) => href.includes('nyctmc.org')),
+      false,
+      'the lane never reaches its upstream',
+    );
+    assert.deepEqual(
+      sources.filter((s) => s.cityId === 'nyc'),
+      [],
+    );
+  });
+}
+
+test('the shipped catalog ceiling is not raised to make room for this pack', () => {
+  assert.equal(DEFAULT_CCTV_MAX_SOURCES, 4000);
+  assert.equal(DEFAULT_NYC_MAX_SOURCES, 250);
+});
+
+test('isLikelyNycCoordinate spans the five boroughs and rejects the rest', () => {
+  assert.equal(isLikelyNycCoordinate(40.758, -73.9855), true); // Times Square
+  assert.equal(isLikelyNycCoordinate(40.5795, -74.1502), true); // Staten Island
+  assert.equal(isLikelyNycCoordinate(40.8448, -73.8648), true); // Bronx
+  assert.equal(isLikelyNycCoordinate(40.5077, -74.2304), true); // southern SI slack
+  assert.equal(isLikelyNycCoordinate(30.2672, -97.7431), false); // Austin
+  assert.equal(isLikelyNycCoordinate(0, 0), false);
+  assert.equal(isLikelyNycCoordinate(NaN, -73.98), false);
+});

src/data/dataCredits.js

@@ -91,6 +91,13 @@ export function hideOsmCredit(viewer, owner) {
   return true;
 }
 
+/** NYC DOT asks every application that uses its data to carry this
+ * disclaimer verbatim (nyc.gov/html/dot/html/about/datafeeds.shtml). */
+export const NYC_DOT_DISCLAIMER =
+  'This application may contain and/or utilize information which was originally compiled by the New York City Department of Transportation (NYC DOT) for governmental purposes; the information may subsequently been modified by entity/entities other than NYC DOT. ' +
+  'NYC DOT and the City of New York make no representation as to the accuracy or usefulness of the information provided by this application or the information's suitability for any purpose and disclaim any liability for omissions or errors that may be contained therein. ' +
+  'The public is advised to observe posted signage for compliance with applicable laws and regulations.';
+
 export const DATA_CREDITS = [
   // ── Live sources ────────────────────────────────────────────────
   {
@@ -104,7 +111,7 @@ export const DATA_CREDITS = [
   {
     key: 'adsblol',
     html:
-      'Military flights, aircraft traces & bounded regional flight fallback: ' +
+      'Military flights, aircraft traces, bounded regional flight fallback & GNSS navigation integrity: ' +
       '<a href="https://adsb.lol" target="_blank" rel="noopener">adsb.lol</a> ' +
       '(ODbL 1.0)',
   },
@@ -247,6 +254,13 @@ export const DATA_CREDITS = [
       '<a href="https://data.norge.no/nlod/en/2.0" target="_blank" rel="noopener">Norwegian licence for Open Government data (NLOD)</a> ' +
       'distributed by Statens vegvesen',
   },
+  {
+    key: 'nyc-cctv',
+    html:
+      'CCTV cameras &amp; frames (New York City, when enabled): ' +
+      '<a href="https://webcams.nyctmc.org/" target="_blank" rel="noopener">NYC DOT Traffic Management Center</a>. ' +
+      NYC_DOT_DISCLAIMER,
+  },
   {
     key: 'gbfs',
     html: 'Bikeshare availability: GBFS operator feeds (e.g. Austin BCycle)',

src/data/dataCredits.test.mjs

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { DATA_CREDITS } from './dataCredits.js';
+import { DATA_CREDITS, NYC_DOT_DISCLAIMER } from './dataCredits.js';
 
 test('every credit carries a unique key and some markup to render', () => {
   const keys = DATA_CREDITS.map((entry) => entry.key);
@@ -120,3 +120,11 @@ test('tile attribution follows source changes and viewers have independent owner
   assert.equal(a.credits.size, 0);
   assert.equal(b.credits.size, 1);
 });
+
+test('the NYC camera credit carries NYC DOT’s requested disclaimer', () => {
+  const credit = DATA_CREDITS.find((entry) => entry.key === 'nyc-cctv');
+  assert.ok(credit, 'NYC DOT camera frames must be credited');
+  assert.ok(credit.html.includes(NYC_DOT_DISCLAIMER));
+  assert.match(credit.html, /make no representation as to the accuracy/);
+  assert.match(credit.html, /observe posted signage/);
+});

src/data/directionText.js

@@ -28,22 +28,34 @@ export function directionToHeading(value, allowBare = false) {
     .trim()
     .toUpperCase();
   if (!text) return NaN;
-  // Explicit travel/intercardinal forms — safe on free-form text (a street
-  // name almost never contains "NORTHBOUND" or a lone "NB" token).
-  if (/\bNORTHBOUND\b|\bNB\b/.test(text)) return 0;
-  if (/\bSOUTHBOUND\b|\bSB\b/.test(text)) return 180;
-  if (/\bEASTBOUND\b|\bEB\b/.test(text)) return 90;
-  if (/\bWESTBOUND\b|\bWB\b/.test(text)) return 270;
-  if (/\bNORTHEAST\b|\bNE\b/.test(text)) return 45;
-  if (/\bNORTHWEST\b|\bNW\b/.test(text)) return 315;
-  if (/\bSOUTHEAST\b|\bSE\b/.test(text)) return 135;
-  if (/\bSOUTHWEST\b|\bSW\b/.test(text)) return 225;
-  // Bare cardinals — dedicated direction fields only.
-  if (allowBare) {
-    if (/\bNORTH\b/.test(text)) return 0;
-    if (/\bSOUTH\b/.test(text)) return 180;
-    if (/\bEAST\b/.test(text)) return 90;
-    if (/\bWEST\b/.test(text)) return 270;
+  const tiers = [
+    [
+      [/\bNORTHBOUND\b|\bNB\b/, 0],
+      [/\bSOUTHBOUND\b|\bSB\b/, 180],
+      [/\bEASTBOUND\b|\bEB\b/, 90],
+      [/\bWESTBOUND\b|\bWB\b/, 270],
+    ],
+    [
+      [/\bNORTHEAST\b|\bNE\b/, 45],
+      [/\bNORTHWEST\b|\bNW\b/, 315],
+      [/\bSOUTHEAST\b|\bSE\b/, 135],
+      [/\bSOUTHWEST\b|\bSW\b/, 225],
+    ],
+  ];
+  if (allowBare)
+    tiers.push([
+      [/\bNORTH\b/, 0],
+      [/\bSOUTH\b/, 180],
+      [/\bEAST\b/, 90],
+      [/\bWEST\b/, 270],
+    ]);
+  for (const forms of tiers) {
+    const headings = new Set();
+    for (const [pattern, heading] of forms) {
+      if (pattern.test(text)) headings.add(heading);
+    }
+    if (headings.size)
+      return headings.size === 1 ? headings.values().next().value : NaN;
   }
   return NaN;
 }

src/data/firms-calendar-validity.test.mjs

@@ -0,0 +1,23 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { acquisitionMsUtc } from './firmsCsv.js';
+test('FIRMS acquisition dates cannot roll into a different calendar day', () => {
+  for (const [date, time] of [
+    ['2026-02-30', '1200'],
+    ['2026-04-31', '1200'],
+    ['2026-13-01', '1200'],
+    ['2026-07-16junk', '1200'],
+    ['2026-07-16', '2400'],
+    ['2026-07-16', '1260'],
+    ['2026-07-16', null],
+    ['2026-07-16', ''],
+  ]) {
+    assert.ok(Number.isNaN(acquisitionMsUtc(date, time)), `${date}:${time}`);
+  }
+  for (const [date, time, expected] of [
+    ['2024-02-29', '45', Date.UTC(2024, 1, 29, 0, 45)],
+    ['2026-07-16', '0', Date.UTC(2026, 6, 16)],
+  ]) {
+    assert.equal(acquisitionMsUtc(date, time), expected);
+  }
+});

src/data/firms-coordinate-evidence.test.mjs

@@ -0,0 +1,69 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseFirmsCsv } from './firmsCsv.js';
+import { adaptFirmsRecords } from './firmsAdapt.js';
+test('missing positions do not become fire detections at zero coordinates', () => {
+  const csv =
+    'latitude,longitude,acq_date,acq_time,confidence,frp\n,1,2026-07-16,1200,n,1\n1, ,2026-07-16,1200,n,1\n95,1,2026-07-16,1200,n,1\n1,181,2026-07-16,1200,n,1\n0,0,2026-07-16,1200,n,1\n-90,-180,2026-07-16,1200,n,1';
+  assert.deepEqual(
+    parseFirmsCsv(csv).map((r) => [r.lat, r.lon]),
+    [
+      [0, 0],
+      [-90, -180],
+    ],
+  );
+  const records = [
+    { lat: null, lon: 1 },
+    { lat: '', lon: 1 },
+    { lat: false, lon: 1 },
+    { lat: 95, lon: 1 },
+    { lat: 1, lon: 181 },
+    { lat: '0', lon: 0 },
+    { lat: -90, lon: -180 },
+  ];
+  assert.deepEqual(
+    adaptFirmsRecords(records).map((r) => [r.index, r.lat, r.lon]),
+    [
+      [0, 0, 0],
+      [1, -90, -180],
+    ],
+  );
+});
+
+test('both axes keep their exact bounds and drop values just past them', () => {
+  const row = (lat, lon) => `${lat},${lon},2026-07-16,1200,n,1`;
+  const csv = [
+    'latitude,longitude,acq_date,acq_time,confidence,frp',
+    row(90, 180),
+    row(-90, -180),
+    row(90.000001, 0),
+    row(-90.000001, 0),
+    row(0, 180.000001),
+    row(0, -180.000001),
+    row(' ', 5),
+    row(5, '\t'),
+  ].join('\n');
+  assert.deepEqual(
+    parseFirmsCsv(csv).map((r) => [r.lat, r.lon]),
+    [
+      [90, 180],
+      [-90, -180],
+    ],
+  );
+  const kept = adaptFirmsRecords([
+    { lat: 90, lon: 180 },
+    { lat: '-90', lon: '-180' },
+    { lat: -90.000001, lon: 0 },
+    { lat: 0, lon: -180.000001 },
+    { lat: 5, lon: ' ' },
+    { lat: 5, lon: undefined },
+    { lat: [5], lon: 5 },
+  ]);
+  assert.deepEqual(
+    kept.map((r) => [r.lat, r.lon]),
+    [
+      [90, 180],
+      [-90, -180],
+    ],
+  );
+});

src/data/firmsAdapt.js

@@ -7,8 +7,8 @@
  */
 
 /**
- * Map proxy fire records into internal fire records. Records with
- * non-finite coordinates are skipped; `index` is the post-skip position
+ * Map proxy fire records into internal fire records. Records with missing,
+ * non-numeric or out-of-range (WGS84) coordinates are skipped; `index` is the post-skip position
  * (it keys pick ids and context-store ids, so it must stay sequential).
  * `contextEntity`/`position` start null and are lazily filled by the layer.
  * @param {?Array<Object>} records - /api/firms `fires` array.
@@ -21,7 +21,15 @@ export function adaptFirmsRecords(records) {
   for (const record of records) {
     const lat = Number(record?.lat);
     const lon = Number(record?.lon);
-    if (!Number.isFinite(lat) || !Number.isFinite(lon)) continue;
+    if (
+      !hasCoordinateValue(record?.lat) ||
+      !hasCoordinateValue(record?.lon) ||
+      !Number.isFinite(lat) ||
+      !Number.isFinite(lon) ||
+      Math.abs(lat) > 90 ||
+      Math.abs(lon) > 180
+    )
+      continue;
     fires.push({
       index: fires.length,
       lat,
@@ -110,3 +118,11 @@ function finiteNumber(value) {
   const number = Number(value);
   return Number.isFinite(number) ? number : 0;
 }
+
+// Same rule as parseFirmsCsv: a blank or non-numeric value is not a zero.
+function hasCoordinateValue(value) {
+  return (
+    typeof value === 'number' ||
+    (typeof value === 'string' && value.trim() !== '')
+  );
+}

src/data/firmsCsv.js

@@ -105,7 +105,17 @@ export function parseFirmsCsv(text) {
     if (parts.length < header.length) continue; // malformed row — skip
     const lat = Number(parts[iLat]);
     const lon = Number(parts[iLon]);
-    if (!Number.isFinite(lat) || !Number.isFinite(lon)) continue;
+    // Blank or out-of-range positions are dropped, never read as 0 (see
+    // hasCoordinateValue in firmsAdapt.js for the proxy-record side).
+    if (
+      !parts[iLat].trim() ||
+      !parts[iLon].trim() ||
+      !Number.isFinite(lat) ||
+      !Number.isFinite(lon) ||
+      Math.abs(lat) > 90 ||
+      Math.abs(lon) > 180
+    )
+      continue;
 
     records.push({
       lat,
@@ -153,7 +163,13 @@ export function acquisitionMsUtc(acqDate, acqTime) {
     minutes > 59
   )
     return NaN;
-  return Date.UTC(year, month - 1, day, hours, minutes);
+  const ms = Date.UTC(year, month - 1, day, hours, minutes);
+  const parsed = new Date(ms);
+  return parsed.getUTCFullYear() === year &&
+    parsed.getUTCMonth() === month - 1 &&
+    parsed.getUTCDate() === day
+    ? ms
+    : NaN;
 }
 
 /**

src/data/flights.test.mjs

@@ -79,6 +79,12 @@ test('flights analyst record: full record maps every contract field', () => {
     aircraftClass: 'airliner',
     originCountry: 'United States',
     operator: 'Southwest Airlines',
+    squawk: null,
+    emergency: false,
+    emergencyKind: null,
+    emergencySource: null,
+    emergencyBroadcast: null,
+    lastContactAtMs: null,
     routeOrigin: 'AUS',
     routeDestination: 'LAX',
   });

src/data/geoImportImages.js

@@ -0,0 +1,74 @@
+// Inspect encoded headers before allowing the browser to decode local images.
+export const MAX_IMPORT_IMAGE_PIXELS = 16 * 1024 * 1024;
+const MAX_SIDE = 8192;
+
+/** Width and height from a supported raster header; no image is decoded. */
+export function importImageSize(bytes) {
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const ascii = (at, n) => String.fromCharCode(...bytes.subarray(at, at + n));
+  const u24 = (at) => bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+  if (
+    bytes.length >= 24 &&
+    v.getUint32(0) === 0x89504e47 &&
+    ascii(12, 4) === 'IHDR'
+  )
+    return [v.getUint32(16), v.getUint32(20)];
+  if (bytes.length >= 10 && /^GIF8[79]a$/.test(ascii(0, 6)))
+    return [v.getUint16(6, true), v.getUint16(8, true)];
+  if (bytes.length >= 26 && ascii(0, 2) === 'BM') {
+    if (v.getUint32(14, true) === 12)
+      return [v.getUint16(18, true), v.getUint16(20, true)];
+    return [Math.abs(v.getInt32(18, true)), Math.abs(v.getInt32(22, true))];
+  }
+  if (bytes.length >= 30 && ascii(0, 4) === 'RIFF' && ascii(8, 4) === 'WEBP') {
+    const kind = ascii(12, 4);
+    if (kind === 'VP8X') return [1 + u24(24), 1 + u24(27)];
+    if (kind === 'VP8 ' && u24(23) === 0x2a019d)
+      return [v.getUint16(26, true) & 0x3fff, v.getUint16(28, true) & 0x3fff];
+    if (kind === 'VP8L' && bytes[20] === 0x2f) {
+      const bits = v.getUint32(21, true);
+      return [(bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1];
+    }
+  }
+  if (bytes.length >= 4 && v.getUint16(0) === 0xffd8) {
+    for (let at = 2; at + 4 <= bytes.length;) {
+      if (bytes[at++] !== 0xff) break;
+      while (bytes[at] === 0xff) at++;
+      const marker = bytes[at++];
+      if (marker === 0xd9 || marker === 0xda) break;
+      if (marker === 1 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+      const length = v.getUint16(at);
+      if (length < 2 || at + length > bytes.length) break;
+      if (
+        [
+          0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd,
+          0xce, 0xcf,
+        ].includes(marker) &&
+        length >= 8
+      )
+        return [v.getUint16(at + 5), v.getUint16(at + 3)];
+      at += length;
+    }
+  }
+  return null;
+}
+
+/** Charge each distinct encoded image once against the file's decoded budget. */
+export function createImportImageBudget() {
+  const seen = new Set();
+  let pixels = 0;
+  return (key, bytes) => {
+    if (seen.has(key)) return;
+    const size = importImageSize(bytes);
+    if (
+      !size ||
+      size.some((n) => !Number.isInteger(n) || n <= 0 || n > MAX_SIDE) ||
+      pixels + size[0] * size[1] > MAX_IMPORT_IMAGE_PIXELS
+    )
+      throw new Error(
+        'Local images exceed the decoded image limit or have an unreadable header.',
+      );
+    pixels += size[0] * size[1];
+    seen.add(key);
+  };
+}

src/data/geoImportPins.js

@@ -0,0 +1,128 @@
+import * as Cesium from 'cesium';
+
+const STYLE = [
+  'image',
+  'scale',
+  'rotation',
+  'alignedAxis',
+  'horizontalOrigin',
+  'verticalOrigin',
+  'color',
+  'eyeOffset',
+  'pixelOffset',
+  'width',
+  'height',
+  'scaleByDistance',
+  'translucencyByDistance',
+  'pixelOffsetScaleByDistance',
+  'distanceDisplayCondition',
+  'sizeInMeters',
+  'disableDepthTestDistance',
+  'imageSubRegion',
+];
+
+class ImportedBillboards extends Cesium.BillboardCollection {
+  update(frameState) {
+    // Height queries should find the map, never another imported marker.
+    // Ordinary click picks and rendered screenshots still include the pins.
+    if (frameState.passes.pick && frameState.passes.offscreen) return;
+    super.update(frameState);
+  }
+}
+
+/** Own static imported pins without a per-frame Entity visualizer walk. */
+export function createImportedPins(dataSource, viewer) {
+  const all = dataSource.entities.values.slice();
+  const now = Cesium.JulianDate.now();
+  const pins = all.filter((entity) => entity.billboard && entity.position);
+  if (!pins.length) return { mount() {}, sync() {}, destroy() {} };
+  const collection = new ImportedBillboards({ scene: viewer.scene });
+  const billboards = [];
+  try {
+    for (const entity of pins) {
+      const position = entity.position.getValue(now);
+      if (
+        !position ||
+        ![position.x, position.y, position.z].every(Number.isFinite)
+      )
+        throw new Error('Invalid imported point position.');
+      const options = {
+        id: entity,
+        position,
+        show:
+          entity.isShowing && entity.billboard.show?.getValue(now) !== false,
+        heightReference: Cesium.HeightReference.NONE,
+      };
+      for (const key of STYLE) {
+        const value = entity.billboard[key]?.getValue(now);
+        if (value !== undefined) options[key] = value;
+      }
+      billboards.push(collection.add(options));
+    }
+  } catch (error) {
+    collection.destroy();
+    throw error;
+  }
+  // Rebuild once before the source is added to DataSourceDisplay. Removing
+  // one entity at a time would itself make this transition quadratic.
+  dataSource.entities.suspendEvents();
+  try {
+    dataSource.entities.removeAll();
+    for (const entity of all)
+      if (!entity.billboard || !entity.position)
+        dataSource.entities.add(entity);
+  } finally {
+    dataSource.entities.resumeEvents();
+  }
+  Object.defineProperty(dataSource, 'importedEntities', {
+    value: all,
+    configurable: true,
+  });
+  Object.defineProperty(dataSource, 'importedBillboards', {
+    value: collection,
+    configurable: true,
+  });
+  let show = dataSource.show,
+    mounted = false,
+    destroyed = false;
+  Object.defineProperty(dataSource, 'show', {
+    configurable: true,
+    get: () => show,
+    set(value) {
+      show = Boolean(value);
+      dataSource.entities.show = show;
+      collection.show = show;
+    },
+  });
+  collection.show = show;
+  return {
+    mount() {
+      if (destroyed || mounted) return;
+      viewer.scene.primitives?.add(collection);
+      mounted = true;
+    },
+    sync() {
+      if (destroyed) return;
+      for (let i = 0; i < pins.length; i++) {
+        billboards[i].position = pins[i].position.getValue(now);
+        billboards[i].show =
+          pins[i].isShowing && pins[i].billboard.show?.getValue(now) !== false;
+      }
+      viewer.scene.requestRender?.();
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      if (viewer.trackedEntity && pins.includes(viewer.trackedEntity))
+        viewer.trackedEntity = undefined;
+      if (viewer.selectedEntity && pins.includes(viewer.selectedEntity))
+        viewer.selectedEntity = undefined;
+      if (mounted && !viewer.scene.primitives?.isDestroyed?.())
+        viewer.scene.primitives?.remove(collection);
+      if (!collection.isDestroyed()) collection.destroy();
+      all.length = 0;
+      pins.length = 0;
+      billboards.length = 0;
+    },
+  };
+}

src/data/gnssIntegrityProxy.test.mjs

@@ -0,0 +1,429 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  gnssIntegrityAnchor,
+  gnssIntegrityProxy,
+  gnssRetryCooldownMs,
+} from '../../server/providers/gnssIntegrity.js';
+
+const snapshot = {
+  now: 4_000_000_000_000,
+  ac: [
+    {
+      hex: '4ca7b5',
+      type: 'adsb_icao',
+      version: 2,
+      alt_baro: 36000,
+      lat: 50.1,
+      lon: 19.9,
+      nic: 0,
+      nac_p: 0,
+      seen_pos: 1,
+      flight: 'RYR1AB  ',
+      r: 'EI-ABC',
+    },
+    { hex: '000001', type: 'mlat', lat: 50, lon: 20, nic: 0, nac_p: 0 },
+  ],
+};
+
+function install(options = {}, hook = 'configureServer') {
+  let handler;
+  const plugin = gnssIntegrityProxy({ monotonicNow: options.now, ...options });
+  assert.equal(plugin.name, 'gnss-integrity');
+  plugin[hook]({
+    middlewares: {
+      use(path, callback) {
+        assert.equal(path, '/api/gnss-integrity');
+        handler = callback;
+      },
+    },
+  });
+  return async (url = '/?lat=50&lon=20', method = 'GET', peer = 'local') => {
+    const res = {
+      writeHead(status, headers) {
+        this.status = status;
+        this.headers = headers;
+      },
+      end(body) {
+        this.body = JSON.parse(body);
+      },
+    };
+    await handler({ url, method, socket: { remoteAddress: peer } }, res);
+    return res;
+  };
+}
+
+test('anchors snap to whole degrees and reject missing or out-of-range values', () => {
+  assert.deepEqual(gnssIntegrityAnchor('/?lat=50.44&lon=19.51'), {
+    lat: 50,
+    lon: 20,
+  });
+  assert.equal(gnssIntegrityAnchor('/?lat=91&lon=0'), null);
+  assert.equal(gnssIntegrityAnchor('/?lat=0&lon=-181'), null);
+  assert.equal(gnssIntegrityAnchor('/?lat=0'), null);
+  assert.equal(gnssIntegrityAnchor('/?lat=abc&lon=1'), null);
+});
+
+for (const hook of ['configureServer', 'configurePreviewServer']) {
+  test(`${hook}: fetches the fixed adsb.lol origin and returns only integrity facts`, async () => {
+    const calls = [];
+    const request = install(
+      {
+        now: () => 1234,
+        fetchImpl: async (url, options) => {
+          calls.push(url);
+          assert.ok(options.signal instanceof AbortSignal);
+          assert.equal(options.redirect, 'error');
+          return Response.json(snapshot);
+        },
+      },
+      hook,
+    );
+    const res = await request(
+      '/?lat=50.2&lon=19.8&url=https://invalid.example',
+    );
+    assert.equal(res.status, 200);
+    assert.deepEqual(calls, ['https://api.adsb.lol/v2/lat/50/lon/20/dist/250']);
+    assert.deepEqual(res.body, {
+      fetchedAt: 1234,
+      ageMs: 0,
+      anchor: { lat: 50, lon: 20 },
+      radiusNm: 250,
+      classifier: 'gev-nic-nacp-v2',
+      rows: [
+        {
+          hex: '4ca7b5',
+          lat: 50.1,
+          lon: 19.9,
+          nic: 0,
+          nacp: 0,
+          gpsLost: false,
+          degraded: true,
+        },
+      ],
+    });
+    assert.equal(res.headers['Cache-Control'], 'no-store');
+  });
+}
+
+test('snapshots are cached per anchor and concurrent reads share one upstream call', async () => {
+  let clock = 0;
+  let calls = 0;
+  const request = install({
+    now: () => clock,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(snapshot);
+    },
+  });
+  await Promise.all([request(), request('/?lat=50.3&lon=20.2')]);
+  assert.equal(calls, 1);
+  clock = 59_000;
+  const cached = await request();
+  assert.equal(calls, 1);
+  assert.equal(cached.body.fetchedAt, 0);
+  assert.equal(
+    cached.body.ageMs,
+    59_000,
+    'a cached answer reports its age on the server clock',
+  );
+  clock = 61_000;
+  await request();
+  assert.equal(calls, 2);
+  await request('/?lat=10&lon=10');
+  assert.equal(calls, 3);
+});
+
+test('an upstream failure serves the last snapshot as stale, else 502', async () => {
+  let clock = 0;
+  let fail = false;
+  const request = install({
+    now: () => clock,
+    fetchImpl: async () =>
+      fail ? new Response('down', { status: 503 }) : Response.json(snapshot),
+  });
+  await request();
+  fail = true;
+  clock = 120_000;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(
+    stale.body.fetchedAt,
+    0,
+    'a stale answer keeps the time it was observed',
+  );
+  assert.equal(stale.body.ageMs, 120_000);
+  assert.equal(stale.headers['X-Data-Stale'], 'true');
+  const missing = await request('/?lat=-10&lon=-10');
+  assert.equal(missing.status, 502);
+  assert.deepEqual(missing.body, { error: 'gnss_integrity_unavailable' });
+});
+
+test('a stale snapshot older than the layer window is no longer served', async () => {
+  let clock = 0;
+  let fail = false;
+  const request = install({
+    now: () => clock,
+    fetchImpl: async () =>
+      fail ? new Response('down', { status: 503 }) : Response.json(snapshot),
+  });
+  await request();
+  fail = true;
+  clock = 30 * 60_000;
+  assert.equal((await request()).status, 200);
+  clock = 30 * 60_000 + 1;
+  const expired = await request();
+  assert.equal(expired.status, 502);
+  assert.deepEqual(expired.body, { error: 'gnss_integrity_unavailable' });
+});
+
+test('an upstream 429 starts a cooldown with no further upstream calls', async () => {
+  let clock = 0;
+  let calls = 0;
+  const request = install({
+    now: () => clock,
+    fetchImpl: async () => {
+      calls += 1;
+      return new Response('slow down', {
+        status: 429,
+        headers: { 'retry-after': '90' },
+      });
+    },
+  });
+  const first = await request();
+  assert.equal(first.status, 429);
+  assert.equal(first.headers['Retry-After'], '90');
+  clock = 30_500;
+  const cooling = await request('/?lat=1&lon=1');
+  assert.equal(cooling.status, 429);
+  // The browser is told the remaining shared cooldown, rounded up.
+  assert.equal(cooling.headers['Retry-After'], '60');
+  assert.equal(calls, 1);
+  clock = 91_000;
+  await request('/?lat=2&lon=2');
+  assert.equal(calls, 2);
+});
+
+test('Retry-After accepts sane seconds or HTTP dates up to one hour', () => {
+  const nowMs = Date.parse('2026-09-29T12:00:00Z');
+  assert.equal(gnssRetryCooldownMs('30', nowMs), 30_000);
+  assert.equal(gnssRetryCooldownMs('1', nowMs), 5_000);
+  assert.equal(gnssRetryCooldownMs('3600', nowMs), 3_600_000);
+  assert.equal(
+    gnssRetryCooldownMs('Tue, 29 Sep 2026 13:00:00 GMT', nowMs),
+    3_600_000,
+  );
+  assert.equal(gnssRetryCooldownMs('1e309', nowMs), 60_000);
+  assert.equal(
+    gnssRetryCooldownMs('Tue, 29 Sep 2026 12:00:45 GMT', nowMs),
+    45_000,
+  );
+  // Garbage, a past date or no header fall back to the default minute.
+  assert.equal(gnssRetryCooldownMs('soon', nowMs), 60_000);
+  assert.equal(
+    gnssRetryCooldownMs('Tue, 29 Sep 2026 11:00:00 GMT', nowMs),
+    60_000,
+  );
+  assert.equal(gnssRetryCooldownMs(null, nowMs), 60_000);
+});
+
+test('overlapping 429s preserve the longest shared deadline', async () => {
+  let clock = 0,
+    calls = 0;
+  const pending = [];
+  const request = install({
+    now: () => clock,
+    fetchImpl: () => {
+      calls += 1;
+      return new Promise((resolve) => pending.push(resolve));
+    },
+  });
+  const long = request('/?lat=1&lon=0'),
+    short = request('/?lat=2&lon=0');
+  await new Promise((resolve) => setImmediate(resolve));
+  pending[0](
+    new Response('', { status: 429, headers: { 'Retry-After': '3600' } }),
+  );
+  assert.equal((await long).headers['Retry-After'], '3600');
+  clock = 1000;
+  pending[1](
+    new Response('', { status: 429, headers: { 'Retry-After': '5' } }),
+  );
+  assert.equal((await short).headers['Retry-After'], '3599');
+  clock = 7000;
+  assert.equal((await request('/?lat=3&lon=0')).status, 429);
+  assert.equal(calls, 2);
+  clock = 3_600_001;
+  const resumed = request('/?lat=3&lon=0');
+  await new Promise((resolve) => setImmediate(resolve));
+  pending[2](Response.json(snapshot));
+  assert.equal((await resumed).status, 200);
+  assert.equal(calls, 3);
+});
+
+test('a cached anchor keeps serving its last snapshot as stale during a cooldown', async () => {
+  let clock = 0;
+  let limited = false;
+  let calls = 0;
+  const request = install({
+    now: () => clock,
+    fetchImpl: async () => {
+      calls += 1;
+      return limited
+        ? new Response('slow down', { status: 429 })
+        : Response.json(snapshot);
+    },
+  });
+  await request();
+  limited = true;
+  clock = 61_000;
+  // Another anchor trips the shared cooldown…
+  assert.equal((await request('/?lat=5&lon=5')).status, 429);
+  clock = 62_000;
+  // …and the cached anchor is answered from cache without an upstream call.
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.rows.length, 1);
+  assert.equal(calls, 2);
+});
+
+test('an oversized upstream body is refused as 502 without being parsed', async () => {
+  const request = install({
+    fetchImpl: async () =>
+      new Response('{}', {
+        headers: { 'content-length': String(9 * 1024 * 1024) },
+      }),
+  });
+  const res = await request();
+  assert.equal(res.status, 502);
+  assert.deepEqual(res.body, { error: 'gnss_integrity_unavailable' });
+});
+
+test('the route rejects other methods, paths, bad anchors, a malformed feed and floods', async () => {
+  const request = install({
+    fetchImpl: async () => Response.json({ nope: true }),
+  });
+  assert.equal((await request('/', 'POST')).status, 405);
+  assert.equal((await request('/other?lat=1&lon=1')).status, 404);
+  assert.equal((await request('/?lat=1')).status, 400);
+  assert.equal((await request('/?lat=1&lon=1')).status, 502);
+  const flood = install({ fetchImpl: async () => Response.json(snapshot) });
+  let limited = 0;
+  for (let i = 0; i < 40; i += 1)
+    if ((await flood(`/?lat=${i}&lon=1`, 'GET', 'flood')).status === 429)
+      limited += 1;
+  assert.ok(limited > 0);
+});
+
+test('GERMAN: pathological retry deadlines are bounded', () => {
+  const at = Date.parse('2026-10-14T12:00:00Z');
+  assert.ok(gnssRetryCooldownMs('1e305', at) <= 3600000);
+  assert.equal(gnssRetryCooldownMs('9999999999999999999999', at), 3600000);
+  assert.equal(
+    gnssRetryCooldownMs('Wed, 14 Oct 2099 12:00:00 GMT', at),
+    3600000,
+  );
+  assert.equal(gnssRetryCooldownMs('0x10', at), 60000);
+});
+
+test('GERMAN: 5xx, network timeouts and malformed JSON share a short cooldown', async () => {
+  for (const fail of [
+    async () => new Response('', { status: 503 }),
+    async () => {
+      throw new DOMException('timeout', 'TimeoutError');
+    },
+    async () => new Response('bad JSON'),
+  ]) {
+    let clock = 0,
+      calls = 0;
+    const request = install({
+      now: () => clock,
+      fetchImpl: async () => {
+        calls++;
+        return fail();
+      },
+    });
+    assert.equal((await request()).status, 502);
+    clock = 14000;
+    assert.equal((await request('/?lat=1&lon=1')).status, 502);
+    assert.equal(calls, 1);
+    clock = 15001;
+    await request('/?lat=2&lon=2');
+    assert.equal(calls, 2);
+  }
+});
+
+test('GERMAN: source timestamp dates evidence; frozen old snapshots are rejected', async () => {
+  const now = 1800000000000;
+  const request = install({
+    now: () => now,
+    fetchImpl: async () =>
+      Response.json({ ...snapshot, now: (now - 120000) / 1000 }),
+  });
+  const res = await request();
+  assert.equal(res.body.ageMs, 120000);
+  assert.equal(res.body.stale, true);
+  for (const sourceNow of [(now - 1800001) / 1000, undefined, NaN]) {
+    const missing = install({
+      now: () => now,
+      fetchImpl: async () => Response.json({ ...snapshot, now: sourceNow }),
+    });
+    assert.equal((await missing()).status, 502);
+  }
+});
+
+test('GERMAN: cache age and cooldown remain stable across a wall-clock rollback', async () => {
+  let wall = 1800000000000,
+    mono = 0,
+    calls = 0;
+  const request = install({
+    now: () => wall,
+    monotonicNow: () => mono,
+    fetchImpl: async () => {
+      calls++;
+      return calls === 1
+        ? Response.json({ ...snapshot, now: wall / 1000 })
+        : new Response('', { status: 429, headers: { 'Retry-After': '60' } });
+    },
+  });
+  await request();
+  wall -= 3600000;
+  mono = 61000;
+  const stale = await request();
+  assert.equal(stale.body.ageMs, 61000);
+  assert.equal(stale.body.stale, true);
+  mono += 1000;
+  assert.equal((await request('/?lat=1&lon=1')).headers['Retry-After'], '59');
+  assert.equal(calls, 2);
+});
+
+test('GERMAN: cache hits and coalesced reads do not consume upstream admission', async () => {
+  let calls = 0;
+  const request = install({
+    now: () => 1800000000000,
+    fetchImpl: async () => {
+      calls++;
+      return Response.json(snapshot);
+    },
+  });
+  for (let i = 0; i < 100; i++) assert.equal((await request()).status, 200);
+  assert.equal((await request('/?lat=1&lon=1')).status, 200);
+  assert.equal(calls, 2);
+});
+
+test('GERMAN: distinct concurrent upstream reads are bounded', async () => {
+  const pending = [];
+  const request = install({
+    fetchImpl: () => new Promise((resolve) => pending.push(resolve)),
+  });
+  const jobs = Array.from({ length: 30 }, (_, i) =>
+    request(`/?lat=${i}&lon=1`),
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.ok(pending.length <= 8);
+  pending.forEach((resolve) => resolve(Response.json(snapshot)));
+  const results = await Promise.all(jobs);
+  assert.ok(results.some((result) => result.status === 429));
+});

src/data/layerState.js

@@ -607,6 +607,11 @@ export const LAYER_STATE_REGISTRY = Object.freeze([
     disposition: 'enabled+options',
     optionOwner: 'flights',
   }),
+  Object.freeze({
+    id: 'gnss-integrity',
+    token: '3',
+    disposition: 'enabled-only',
+  }),
   Object.freeze({ id: 'local-dams', token: 'q', disposition: 'enabled-only' }),
   Object.freeze({
     id: 'local-datacenters',

src/data/layerState.test.mjs

@@ -202,8 +202,8 @@ function encode(state) {
 
 test('production registry is exact, canonical, and rejects incomplete contracts', async () => {
   assert.equal(validateLayerStateRegistry(), true);
-  assert.equal(REGISTERED_LAYER_IDS.length, 29);
-  assert.equal(new Set(REGISTERED_LAYER_IDS).size, 29);
+  assert.equal(REGISTERED_LAYER_IDS.length, 30);
+  assert.equal(new Set(REGISTERED_LAYER_IDS).size, 30);
   assert.ok(REGISTERED_LAYER_IDS.includes('transit'));
   assert.deepEqual(REGISTERED_LAYER_IDS, [...REGISTERED_LAYER_IDS].sort());
   assert.deepEqual(LEGACY_LAYER_STATE_TOKENS, {
@@ -242,19 +242,19 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
   for (const [id, token] of Object.entries(LEGACY_LAYER_STATE_TOKENS)) {
     assert.equal(LAYER_STATE_TOKEN_RESERVATIONS[id], token);
   }
-  assert.equal(nextLayerStateToken(), '3');
+  assert.equal(nextLayerStateToken(), '4');
   assert.equal(
     nextLayerStateToken({
       ...LAYER_STATE_TOKEN_RESERVATIONS,
-      alpha: '3',
-      bravo: '4',
+      alpha: '4',
+      bravo: '5',
     }),
-    '5',
+    '6',
   );
   const digitsExhausted = {
     ...LAYER_STATE_TOKEN_RESERVATIONS,
     ...Object.fromEntries(
-      [...'3456789'].map((digit) => [`prior-${digit}`, digit]),
+      [...'456789'].map((digit) => [`prior-${digit}`, digit]),
     ),
   };
   assert.equal(nextLayerStateToken(digitsExhausted), '00');
@@ -307,8 +307,8 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
   assert.equal(
     validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
       ...LAYER_STATE_TOKEN_RESERVATIONS,
-      future: '3',
-      next: '4',
+      future: '4',
+      next: '5',
     }),
     true,
   );
@@ -318,7 +318,7 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
         ...LAYER_STATE_TOKEN_RESERVATIONS,
         future: '00',
       }),
-    /next free token 3/,
+    /next free token 4/,
   );
   const beforeLastDigit = { ...digitsExhausted };
   delete beforeLastDigit['prior-9'];
@@ -341,10 +341,10 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
   assert.throws(
     () =>
       validateLayerStateAllocations(
-        { ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '3' },
-        { ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '3', competing: '3' },
+        { ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '4' },
+        { ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '4', competing: '4' },
       ),
-    /next free token 4/,
+    /next free token 5/,
   );
   assert.throws(
     () => validateLayerStateAllocations({ future: '00' }, { future: '01' }),
@@ -2639,6 +2639,23 @@ test('the recent-imagery split is share-link only: never stored locally, and a s
   );
 });
 
+test('GNSS interference uses digit 3 without colliding with other digit tokens', () => {
+  const decoded = decodeLayerStateParams(new URLSearchParams('v=2&l=3.2.1'));
+  assert.deepEqual(decoded.enabledLayerIds, [
+    'fire-perimeters',
+    'gnss-integrity',
+    'recent-imagery',
+  ]);
+  assert.equal(
+    LAYER_STATE_REGISTRY.find(({ id }) => id === 'gnss-integrity').token,
+    '3',
+  );
+  assert.deepEqual(
+    decodeLayerStateParams(new URLSearchParams(encode(decoded))),
+    decoded,
+  );
+});
+
 test('fire perimeters uses digit 2 without colliding with wind or recent imagery', () => {
   const decoded = decodeLayerStateParams(new URLSearchParams('v=2&l=2.k.1'));
   assert.deepEqual(decoded.enabledLayerIds, [
@@ -2703,13 +2720,19 @@ test('Street Level: the link codec accepts exactly the windows the filter keeps'
   assert.equal(streetLevelOptions('0.s.3652').sinceDays, 3652);
 });
 
-test('Street Level: a link without the provider switch keeps Mapillary on', () => {
+test('Street Level: a link without the provider switches keeps Mapillary on and Street View off', () => {
   assert.deepEqual(streetLevelOptions(''), {
     mapillary: true,
     providerSwitches: '',
     pano: 'all',
     sinceDays: 0,
   });
+  // Street View rides the shared provider-switch field, off unless lit.
+  assert.equal(streetLevelOptions('0.r.google-1').providerSwitches, 'google-1');
+  assert.equal(
+    createDefaultLayerState().options['street-level'].providerSwitches,
+    '',
+  );
   assert.equal(streetLevelOptions('0.p.f').mapillary, true);
   assert.equal(streetLevelOptions('0.m.0').mapillary, false);
   assert.equal(

src/data/layerStateTokenLedger.test.mjs

@@ -128,10 +128,14 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
     { ...parseLayerStateTokenReservations(reservationRows) },
     { ...LAYER_STATE_TOKEN_RESERVATIONS },
   );
-  assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 29);
+  assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 30);
   assert.deepEqual(
     { ...LAYER_STATE_TOKEN_RESERVATIONS },
-    { ...LEGACY_LAYER_STATE_TOKENS, 'street-level': '0' },
+    {
+      ...LEGACY_LAYER_STATE_TOKENS,
+      'street-level': '0',
+      'gnss-integrity': '3',
+    },
   );
   assert.throws(
     () => parseLayerStateTokenReservations(reservationRows.slice(1)),
@@ -151,9 +155,9 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
     /Duplicate layer-state token reservation/,
   );
   assert.equal(
-    parseLayerStateTokenReservations([...reservationRows, ['future', '3']])
+    parseLayerStateTokenReservations([...reservationRows, ['future', '4']])
       .future,
-    '3',
+    '4',
   );
   assert.throws(
     () =>
@@ -171,14 +175,14 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
 
 test('published retired digits and competing PRs advance the merge-time allocation', () => {
   withPublishedBase(
-    { rows: [...reservationRows, ['retired-layer', '3']] },
+    { rows: [...reservationRows, ['retired-layer', '4']] },
     (cwd) => {
       const published = readPublishedLayerStateReservations('HEAD', cwd);
-      assert.equal(nextLayerStateToken(published), '4');
+      assert.equal(nextLayerStateToken(published), '5');
       assert.equal(
         validateLayerStateAllocations(published, {
           ...published,
-          newcomer: '4',
+          newcomer: '5',
         }),
         true,
       );
@@ -186,15 +190,15 @@ test('published retired digits and competing PRs advance the merge-time allocati
         () =>
           validateLayerStateAllocations(published, {
             ...published,
-            competing: '3',
+            competing: '4',
           }),
-        /next free token 4/,
+        /next free token 5/,
       );
       assert.throws(
         () =>
           validateLayerStateAllocations(published, {
             ...LAYER_STATE_TOKEN_RESERVATIONS,
-            newcomer: '3',
+            newcomer: '4',
           }),
         /changed or removed: retired-layer/,
       );
@@ -202,8 +206,8 @@ test('published retired digits and competing PRs advance the merge-time allocati
   );
 });
 
-test('PR B manually replaces provisional 3 with 4 after PR A publishes 3', () => {
-  withPublishedBase({ rows: [...reservationRows, ['pr-a', '3']] }, (cwd) => {
+test('PR B manually replaces provisional 4 with 5 after PR A publishes 4', () => {
+  withPublishedBase({ rows: [...reservationRows, ['pr-a', '4']] }, (cwd) => {
     mkdirSync(path.join(cwd, 'scripts'));
     const fixtureChecker = path.join(
       cwd,
@@ -224,8 +228,8 @@ test('PR B manually replaces provisional 3 with 4 after PR A publishes 3', () =>
 
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-b', '3']],
-      [{ id: 'pr-b', token: '3' }],
+      [...reservationRows, ['pr-b', '4']],
+      [{ id: 'pr-b', token: '4' }],
     );
     const beforeRebase = runCheck();
     assert.equal(beforeRebase.status, 1);
@@ -233,10 +237,10 @@ test('PR B manually replaces provisional 3 with 4 after PR A publishes 3', () =>
 
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-a', '3'], ['pr-b', '3']],
+      [...reservationRows, ['pr-a', '4'], ['pr-b', '4']],
       [
-        { id: 'pr-a', token: '3' },
-        { id: 'pr-b', token: '3' },
+        { id: 'pr-a', token: '4' },
+        { id: 'pr-b', token: '4' },
       ],
     );
     const staleRebase = runCheck();
@@ -244,16 +248,16 @@ test('PR B manually replaces provisional 3 with 4 after PR A publishes 3', () =>
     assert.match(staleRebase.stderr, /Duplicate layer-state token reservation/);
 
     const published = readPublishedLayerStateReservations('HEAD', cwd);
-    assert.equal(nextLayerStateToken(published), '4');
-    const validBaselineRows = [...reservationRows, ['pr-a', '3']];
-    writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '3' }]);
+    assert.equal(nextLayerStateToken(published), '5');
+    const validBaselineRows = [...reservationRows, ['pr-a', '4']];
+    writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '4' }]);
     const helper = spawnSync(
       process.execPath,
       [realpathSync(fixtureNext), 'pr-b'],
       { cwd, encoding: 'utf8' },
     );
     assert.equal(helper.status, 0, helper.stderr);
-    assert.match(helper.stdout, /pr-b: 4/);
+    assert.match(helper.stdout, /pr-b: 5/);
     assert.deepEqual(
       JSON.parse(readFileSync(path.join(cwd, LEDGER_PATH), 'utf8')),
       validBaselineRows,
@@ -261,20 +265,20 @@ test('PR B manually replaces provisional 3 with 4 after PR A publishes 3', () =>
     );
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-a', '3'], ['pr-b', '4']],
+      [...reservationRows, ['pr-a', '4'], ['pr-b', '5']],
       [
-        { id: 'pr-a', token: '3' },
-        { id: 'pr-b', token: '4' },
+        { id: 'pr-a', token: '4' },
+        { id: 'pr-b', token: '5' },
       ],
     );
     const corrected = runCheck();
     assert.equal(corrected.status, 0, corrected.stderr);
-    assert.match(corrected.stdout, /30 published, 1 new/);
+    assert.match(corrected.stdout, /31 published, 1 new/);
   });
 });
 
 test('allocation batches cross the last digit and base-36 pair boundaries in order', () => {
-  const digitRows = [...'3456789'].map((digit) => [`retired-${digit}`, digit]);
+  const digitRows = [...'456789'].map((digit) => [`retired-${digit}`, digit]);
   const allDigits = parseLayerStateTokenReservations([
     ...reservationRows,
     ...digitRows,
@@ -326,7 +330,7 @@ test('allocation batches cross the last digit and base-36 pair boundaries in ord
 test('an isolated valid two-character fixture round-trips an l field beyond the old 64-character cap', async () => {
   const cwd = mkdtempSync(path.join(tmpdir(), 'gev-layer-token-width-'));
   try {
-    const priorDigits = [...'3456789'].map((digit) => [
+    const priorDigits = [...'456789'].map((digit) => [
       `qa-prior-digit-${digit}`,
       digit,
     ]);
@@ -363,7 +367,7 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
     const params = new URLSearchParams([['v', '2']]);
     codec.encodeLayerStateParams(params, state);
     assert.ok(params.get('l').length > 64, 'fixture must cross the old cap');
-    assert.equal(params.get('l').length, 69);
+    assert.equal(params.get('l').length, 71);
     const restored = codec.decodeLayerStateParams(params);
     assert.deepEqual(restored?.enabledLayerIds, expectedLayerIds);
     assert.deepEqual(restored?.options, state.options);
@@ -381,7 +385,7 @@ test('checker reads a complete future base ledger and rejects retired-token reus
     },
     (cwd) => {
       const published = readPublishedLayerStateReservations('HEAD', cwd);
-      assert.equal(Object.keys(published).length, 30);
+      assert.equal(Object.keys(published).length, 31);
       assert.equal(published['retired-layer'], '00');
       assert.throws(
         () =>

src/data/layerStateTokenReservations.json

@@ -9,6 +9,7 @@
   ["earthquakes", "e"],
   ["fire-perimeters", "2"],
   ["flights", "f"],
+  ["gnss-integrity", "3"],
   ["local-dams", "q"],
   ["local-datacenters", "d"],
   ["local-firms", "w"],

src/data/manager.test.mjs

@@ -2398,10 +2398,13 @@ test('a newer absolute intent aborts a hung guard-compensation instead of starvi
   removeGuard();
   // The newest intent must be able to abort the hung compensation and run.
   const pendingFinalOn = mgr.setEnabled('flights', true, { origin: 'user' });
+  let giveUpTimer;
   const finalOn = await Promise.race([
     pendingFinalOn,
-    new Promise((resolve) => setTimeout(() => resolve('starved'), 2000)),
-  ]);
+    new Promise((resolve) => {
+      giveUpTimer = setTimeout(() => resolve('starved'), 2000);
+    }),
+  ]).finally(() => clearTimeout(giveUpTimer));
   assert.notEqual(finalOn, 'starved', 'newest intent must not starve behind the compensation');
   assert.equal(compensationAborted, true, 'the hung compensation was aborted');
   assert.equal(await pendingBlockedOn, false, 'the guard-blocked request stays unfulfilled');
@@ -2451,10 +2454,13 @@ test('re-entrant setEnabled from a blocked-adoption listener supersedes the comp
   releaseFirstDisable();
 
   const blockedOn = await pendingBlockedOn;
+  let giveUpTimer;
   const reentrant = await Promise.race([
     (async () => reentrantResult === null ? 'never-fired' : await reentrantResult)(),
-    new Promise((resolve) => setTimeout(() => resolve('starved'), 2000)),
-  ]);
+    new Promise((resolve) => {
+      giveUpTimer = setTimeout(() => resolve('starved'), 2000);
+    }),
+  ]).finally(() => clearTimeout(giveUpTimer));
   await pendingOff;
   await mgr.waitForLayerSettled('flights');
   unsubscribe();

src/data/militaryFlights.test.mjs

@@ -71,6 +71,12 @@ test('military analyst record: full record maps every contract field', () => {
     aircraftClass: 'widebody',
     originCountry: null,
     operator: 'United States Air Force',
+    squawk: null,
+    emergency: false,
+    emergencyKind: null,
+    emergencySource: null,
+    emergencyBroadcast: null,
+    lastContactAtMs: null,
     routeOrigin: null,
     routeDestination: null,
   });

src/data/regional-calendar-evidence.test.mjs

@@ -0,0 +1,43 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { normalizeRegionalArticles } from './regionalModel.js';
+test('compact source dates must denote an actual calendar instant', () => {
+  for (const date of [
+    '20260230T120000Z',
+    '20260431T120000Z',
+    '20261301T120000Z',
+    '20260716T240000Z',
+    '20260716T126000Z',
+    '20260716T120060Z',
+  ]) {
+    const [article] = normalizeRegionalArticles({
+      articles: [
+        {
+          title: 'Fixture',
+          url: 'https://fixture.example/news',
+          seendate: date,
+        },
+      ],
+    });
+    assert.equal(article.publishedAt, null, date);
+    assert.equal(article.title, 'Fixture');
+  }
+  for (const [input, expected] of [
+    ['20240229T004500Z', '2024-02-29T00:45:00Z'],
+    ['20260716T000000Z', '2026-07-16T00:00:00Z'],
+    ['2026-07-16T12:00:00Z', '2026-07-16T12:00:00.000Z'],
+  ]) {
+    assert.equal(
+      normalizeRegionalArticles({
+        articles: [
+          {
+            title: 'Fixture',
+            url: 'https://fixture.example/news',
+            seendate: input,
+          },
+        ],
+      })[0].publishedAt,
+      expected,
+    );
+  }
+});

src/data/regionalModel.js

@@ -67,11 +67,20 @@ export function normalizeRegionalArticles(payload, limit = MAX_ARTICLES) {
     seen.add(signature);
     const rawDate = cleanText(row?.seendate, 32);
     const compactDate = /^(\d{8})T(\d{6})Z$/.exec(rawDate);
-    const publishedAt = compactDate
+    const candidateDate = compactDate
       ? `${compactDate[1].slice(0, 4)}-${compactDate[1].slice(4, 6)}-${compactDate[1].slice(6, 8)}T${compactDate[2].slice(0, 2)}:${compactDate[2].slice(2, 4)}:${compactDate[2].slice(4, 6)}Z`
-      : Number.isNaN(Date.parse(rawDate))
-        ? null
-        : new Date(rawDate).toISOString();
+      : rawDate;
+    const parsedMs = Date.parse(candidateDate);
+    const validDate =
+      Number.isFinite(parsedMs) &&
+      (!compactDate ||
+        new Date(parsedMs).toISOString().slice(0, 19) ===
+          candidateDate.slice(0, 19));
+    const publishedAt = validDate
+      ? compactDate
+        ? candidateDate
+        : new Date(parsedMs).toISOString()
+      : null;
     articles.push({
       title,
       url,
@@ -87,14 +96,22 @@ export function normalizeRegionalArticles(payload, limit = MAX_ARTICLES) {
   return articles;
 }
 
+/** A reported number, or null when the observation is missing or not numeric. */
+function observedNumber(value) {
+  if (
+    value == null ||
+    typeof value === 'boolean' ||
+    (typeof value === 'string' && !value.trim())
+  )
+    return null;
+  return Number.isFinite(Number(value)) ? Number(value) : null;
+}
+
 /** Normalize Open-Meteo current conditions into a small source-stamped record. */
 export function normalizeRegionalWeather(payload) {
   const current = payload?.current;
-  if (!current || !Number.isFinite(Number(current.temperature_2m))) return null;
-  const numberOrNull = (value) => {
-    if (value === null || value === undefined || value === '') return null;
-    return Number.isFinite(Number(value)) ? Number(value) : null;
-  };
+  if (!current || observedNumber(current.temperature_2m) == null) return null;
+  const numberOrNull = observedNumber;
   // Open-Meteo reports zone-naive timestamps ("2026-08-17T00:15") that are UTC,
   // but JS parses zoneless date-times as LOCAL — pin them to UTC explicitly.
   const observedRaw =
@@ -119,8 +136,8 @@ export function normalizeRegionalWeather(payload) {
 
 /** Translate the WMO weather code used by Open-Meteo into concise cockpit copy. */
 export function weatherCodeLabel(code) {
-  const value = Number(code);
-  if (!Number.isFinite(value)) return 'CONDITIONS UNKNOWN';
+  const value = observedNumber(code);
+  if (value == null) return 'CONDITIONS UNKNOWN';
   if (value === 0) return 'CLEAR';
   if ([1, 2].includes(value)) return 'PARTLY CLOUDY';
   if (value === 3) return 'OVERCAST';

src/data/route-cap-truthfulness.test.mjs

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { normalizeOsrmSteps, ROUTE_STEPS_MAX } from './routeSteps.js';
+const step = (type) => ({
+  maneuver: { type, location: [10, 20] },
+  distance: 10,
+  duration: 1,
+});
+test('exact-cap routes remain complete and boundary exits retain their distance', () => {
+  const steps = Array.from({ length: ROUTE_STEPS_MAX }, () => step('turn'));
+  assert.equal(normalizeOsrmSteps({ legs: [{ steps }] }).truncated, false);
+  assert.equal(
+    normalizeOsrmSteps({ legs: [{ steps: [...steps, step('turn')] }] })
+      .truncated,
+    true,
+  );
+  steps[steps.length - 1] = step('roundabout');
+  const result = normalizeOsrmSteps({
+    legs: [{ steps: [...steps, step('exit roundabout')] }],
+  });
+  assert.equal(result.truncated, false);
+  assert.equal(result.steps.length, ROUTE_STEPS_MAX);
+  assert.equal(result.steps.at(-1).distanceM, 20);
+});

src/data/routeSteps.js

@@ -185,9 +185,9 @@ export function normalizeOsrmSteps(route) {
         }
         continue;
       }
+      if (out.length >= ROUTE_STEPS_MAX) return { steps: out, truncated: true };
       step.instruction = instructionFor(step);
       out.push(step);
-      if (out.length >= ROUTE_STEPS_MAX) return { steps: out, truncated: true };
     }
   }
   return { steps: out, truncated: false };

src/data/routeSteps.test.mjs

@@ -206,9 +206,9 @@ test('the step list is capped, and the cap is reported rather than hidden', () =
   // would present a route that simply stops in the middle of a road.
   assert.equal(cut.truncated, true);
   const exact = normalizeOsrmSteps({
-    legs: [{ steps: many.slice(0, ROUTE_STEPS_MAX - 1) }],
+    legs: [{ steps: many.slice(0, ROUTE_STEPS_MAX) }],
   });
-  assert.equal(exact.steps.length, ROUTE_STEPS_MAX - 1);
+  assert.equal(exact.steps.length, ROUTE_STEPS_MAX);
   assert.equal(exact.truncated, false, 'a route that fits is not cut');
 });
 

src/data/scenePick.js

@@ -47,3 +47,52 @@ export function isPickedWorldPosition(position) {
   const magnitude = Math.hypot(x, y, z);
   return magnitude >= MIN_PICK_MAGNITUDE_M && magnitude <= MAX_PICK_MAGNITUDE_M;
 }
+
+/**
+ * The world position under a screen point: the rendered surface where the
+ * depth buffer has it, else the ellipsoid; null over the sky.
+ *
+ * @param {object} viewer A Cesium viewer.
+ * @param {{x: number, y: number}} screenPosition
+ * @returns {{x: number, y: number, z: number}|null} A Cartesian3.
+ */
+export function pickGroundPosition(viewer, screenPosition) {
+  const scene = viewer?.scene;
+  let position = null;
+  if (
+    scene?.pickPositionSupported &&
+    typeof scene.pickPosition === 'function'
+  ) {
+    try {
+      position = scene.pickPosition(screenPosition);
+    } catch {
+      position = null;
+    }
+  }
+  if (
+    !isPickedWorldPosition(position) &&
+    typeof viewer?.camera?.pickEllipsoid === 'function'
+  ) {
+    try {
+      position = viewer.camera.pickEllipsoid(screenPosition);
+    } catch {
+      position = null;
+    }
+  }
+  return isPickedWorldPosition(position) ? position : null;
+}
+
+/**
+ * Whether a `scene.pick()` result is the map itself: nothing, or 3D tile
+ * content (which has no id).
+ *
+ * @param {object|null|undefined} picked
+ * @returns {boolean}
+ */
+export function isSurfacePick(picked) {
+  if (!picked) return true;
+  if (picked.id !== undefined) return false;
+  return (
+    picked.content !== undefined || picked.primitive?.isCesium3DTileset === true
+  );
+}

src/data/scenePick.test.mjs

@@ -3,9 +3,8 @@ import assert from 'node:assert/strict';
 import * as Cesium from 'cesium';
 import { isPickedWorldPosition } from './scenePick.js';
 
-const describe = (position) => (position
-  ? `(${position.x}, ${position.y}, ${position.z})`
-  : String(position));
+const describe = (position) =>
+  position ? `(${position.x}, ${position.y}, ${position.z})` : String(position);
 
 test('a degenerate depth pick is rejected before it reaches Cesium', () => {
   // These are the shapes `scene.pickPosition()` can produce when the depth read
@@ -21,7 +20,11 @@ test('a degenerate depth pick is rejected before it reaches Cesium', () => {
     new Cesium.Cartesian3(0.2, -0.3, 0.1),
   ];
   for (const position of degenerate) {
-    assert.equal(isPickedWorldPosition(position), false, `must reject ${describe(position)}`);
+    assert.equal(
+      isPickedWorldPosition(position),
+      false,
+      `must reject ${describe(position)}`,
+    );
   }
 });
 
@@ -38,11 +41,18 @@ test('the guard is an Earth-sized band, not just a non-zero check', () => {
     new Cesium.Cartesian3(0, 0, 5_999_999),
   ];
   for (const position of belowTheFloor) {
-    assert.equal(isPickedWorldPosition(position), false, `must reject ${describe(position)}`);
+    assert.equal(
+      isPickedWorldPosition(position),
+      false,
+      `must reject ${describe(position)}`,
+    );
     // Each one converts WITHOUT throwing — that is exactly what makes it dangerous.
     const carto = Cesium.Cartographic.fromCartesian(position);
     assert.ok(carto, `Cesium converts ${describe(position)} without complaint`);
-    assert.ok(carto.height < -300_000, 'and puts the "target" hundreds of km underground');
+    assert.ok(
+      carto.height < -300_000,
+      'and puts the "target" hundreds of km underground',
+    );
   }
 
   const aboveTheCeiling = [
@@ -52,7 +62,11 @@ test('the guard is an Earth-sized band, not just a non-zero check', () => {
     new Cesium.Cartesian3(1e155, 0, 0),
   ];
   for (const position of aboveTheCeiling) {
-    assert.equal(isPickedWorldPosition(position), false, `must reject ${describe(position)}`);
+    assert.equal(
+      isPickedWorldPosition(position),
+      false,
+      `must reject ${describe(position)}`,
+    );
   }
   assert.throws(
     () => Cesium.Cartographic.fromCartesian(new Cesium.Cartesian3(1e155, 0, 0)),
@@ -61,8 +75,14 @@ test('the guard is an Earth-sized band, not just a non-zero check', () => {
   );
 
   // Both edges of the band are inclusive, and both are real magnitudes.
-  assert.equal(isPickedWorldPosition(new Cesium.Cartesian3(6_000_000, 0, 0)), true);
-  assert.equal(isPickedWorldPosition(new Cesium.Cartesian3(1_000_000_000, 0, 0)), true);
+  assert.equal(
+    isPickedWorldPosition(new Cesium.Cartesian3(6_000_000, 0, 0)),
+    true,
+  );
+  assert.equal(
+    isPickedWorldPosition(new Cesium.Cartesian3(1_000_000_000, 0, 0)),
+    true,
+  );
 });
 
 test('a real picked position is accepted', () => {
@@ -81,13 +101,22 @@ test('a real picked position is accepted', () => {
     Cesium.Cartesian3.fromDegrees(0, 0, 35_786_000),
   ];
   for (const position of real) {
-    assert.equal(isPickedWorldPosition(position), true, `must accept ${describe(position)}`);
+    assert.equal(
+      isPickedWorldPosition(position),
+      true,
+      `must accept ${describe(position)}`,
+    );
   }
 
   // The floor has real margin under the smallest legitimate magnitude, so no
   // plausible pick sits anywhere near the boundary.
-  const polarSurface = Cesium.Cartesian3.magnitude(Cesium.Cartesian3.fromDegrees(0, 90, -10_935));
-  assert.ok(polarSurface > 6_300_000, `smallest real magnitude was ${polarSurface}`);
+  const polarSurface = Cesium.Cartesian3.magnitude(
+    Cesium.Cartesian3.fromDegrees(0, 90, -10_935),
+  );
+  assert.ok(
+    polarSurface > 6_300_000,
+    `smallest real magnitude was ${polarSurface}`,
+  );
 });
 
 test('the guard rejects each way Cesium mishandles a degenerate pick', () => {
@@ -118,7 +147,10 @@ test('the guard rejects each way Cesium mishandles a degenerate pick', () => {
   //    Earth's core. That is the quietest failure of the three and the reason
   //    the guard needs a magnitude band, not just a finiteness check.
   const nearCenter = new Cesium.Cartesian3(0.2, -0.3, 0.1);
-  assert.ok(Cesium.Cartographic.fromCartesian(nearCenter), 'Cesium converts it without complaint');
+  assert.ok(
+    Cesium.Cartographic.fromCartesian(nearCenter),
+    'Cesium converts it without complaint',
+  );
   assert.equal(isPickedWorldPosition(nearCenter), false);
 
   // …and every position the guard accepts must convert to the right place.
@@ -129,3 +161,26 @@ test('the guard rejects each way Cesium mishandles a degenerate pick', () => {
   assert.ok(Math.abs(Cesium.Math.toDegrees(carto.longitude) + 97.7431) < 1e-6);
   assert.ok(Math.abs(Cesium.Math.toDegrees(carto.latitude) - 30.2672) < 1e-6);
 });
+
+test('the ground under a click: the rendered surface, else the ellipsoid, never the sky', async () => {
+  const { pickGroundPosition } = await import('./scenePick.js');
+  const ground = { x: 6378137, y: 0, z: 0 };
+  const sky = { x: 500, y: 0, z: 0 };
+  const viewer = (picked, ellipsoid) => ({
+    scene: { pickPositionSupported: true, pickPosition: () => picked },
+    camera: { pickEllipsoid: () => ellipsoid },
+  });
+  assert.equal(pickGroundPosition(viewer(ground, null), {}), ground);
+  assert.equal(pickGroundPosition(viewer(sky, ground), {}), ground);
+  assert.equal(pickGroundPosition(viewer(undefined, undefined), {}), null);
+  assert.equal(pickGroundPosition(null, {}), null);
+});
+
+test('a surface pick is nothing, or Google 3D tile content without an id', async () => {
+  const { isSurfacePick } = await import('./scenePick.js');
+  assert.equal(isSurfacePick(undefined), true);
+  assert.equal(isSurfacePick({ content: {} }), true);
+  assert.equal(isSurfacePick({ primitive: { isCesium3DTileset: true } }), true);
+  assert.equal(isSurfacePick({ id: 'flight:1', content: {} }), false);
+  assert.equal(isSurfacePick({ primitive: {} }), false, 'an unnamed primitive');
+});

src/data/terrainHeightsProxy.js

@@ -35,7 +35,13 @@ export function parseTerrainPoints(raw) {
     if (parts.length !== 2) return null;
     const lon = Number(parts[0]);
     const lat = Number(parts[1]);
-    if (!Number.isFinite(lon) || !Number.isFinite(lat)) return null;
+    if (
+      !Number.isFinite(lon) ||
+      !Number.isFinite(lat) ||
+      Math.abs(lon) > 180 ||
+      Math.abs(lat) > 90
+    )
+      return null;
     points.push([lon, lat]);
   }
   return points;

src/data/terrainHeightsProxy.test.mjs

@@ -3,6 +3,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  parseTerrainPoints,
   fetchTerrainChunkWithRetry,
   resolveTerrainHeightRequest,
   terrainPointKey,
@@ -227,3 +228,13 @@ test('malformed height objects remain refresh failures, not absent readings', as
     assert.equal(response.cacheChanged, false);
   }
 });
+
+test('terrain parser rejects out-of-range WGS84 points and accepts inclusive bounds', () => {
+  for (const value of ['181,0', '-181,0', '0,91', '0,-91', '1,2;0,91'])
+    assert.equal(parseTerrainPoints(value), null, value);
+  assert.deepEqual(parseTerrainPoints('-180,-90;180,90;0,0'), [
+    [-180, -90],
+    [180, 90],
+    [0, 0],
+  ]);
+});

src/data/weather-missing-observations.test.mjs

@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { normalizeRegionalWeather, weatherCodeLabel } from './regionalModel.js';
+test('missing weather observations never assert clear conditions', () => {
+  for (const value of [null, undefined, '', ' ', false, true]) {
+    assert.equal(weatherCodeLabel(value), 'CONDITIONS UNKNOWN');
+    assert.equal(
+      normalizeRegionalWeather({ current: { temperature_2m: value } }),
+      null,
+    );
+  }
+  assert.equal(weatherCodeLabel(0), 'CLEAR');
+  assert.equal(weatherCodeLabel('0'), 'CLEAR');
+  const record = normalizeRegionalWeather({
+    current: { temperature_2m: 0, weather_code: null, wind_speed_10m: false },
+  });
+  assert.equal(record.temperatureC, 0);
+  assert.equal(record.weatherCode, null);
+  assert.equal(record.windKph, null);
+});

src/director/camera.js

@@ -28,6 +28,11 @@ export function resolveCameraMove(scene, shot) {
   };
 }
 
+/** Wrap an interpolated camera longitude to WGS84 without changing authored endpoints. */
+export function normalizeCameraLongitude(longitude) {
+  return ((((longitude + 180) % 360) + 360) % 360) - 180;
+}
+
 /** Sample the same authored curve for playback and seeking, taking the short longitude/angle arc. */
 export function sampleCameraMove(move, progress) {
   const t = Math.max(0, Math.min(1, Number(progress) || 0));
@@ -45,7 +50,7 @@ export function sampleCameraMove(move, progress) {
   const { from, to } = move;
   return {
     lat: lerp(from.lat, to.lat),
-    lon: ((((angle(from.lon, to.lon) + 180) % 360) + 360) % 360) - 180,
+    lon: normalizeCameraLongitude(angle(from.lon, to.lon)),
     alt: lerp(from.alt, to.alt),
     heading: angle(from.heading, to.heading),
     pitch: lerp(from.pitch, to.pitch),

src/director/director-dateline-seek.test.mjs

@@ -0,0 +1,53 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { cameraAtProgress } from './timeline.js';
+const camera = (lon) => ({
+  lat: 10,
+  lon,
+  alt: 1000,
+  heading: 0,
+  pitch: -40,
+  roll: 0,
+});
+test('director seek follows the short dateline arc in both directions', () => {
+  for (const [a, b] of [
+    [179, -179],
+    [-179, 179],
+  ]) {
+    assert.equal(
+      Math.abs(cameraAtProgress(camera(a), camera(b), 0.5).lon),
+      180,
+    );
+    assert.equal(cameraAtProgress(camera(a), camera(b), 0).lon, a);
+    assert.equal(cameraAtProgress(camera(a), camera(b), 1).lon, b);
+    assert.ok(Math.abs(cameraAtProgress(camera(a), camera(b), 0.25).lon) > 179);
+  }
+  assert.equal(cameraAtProgress(camera(20), camera(24), 0.5).lon, 22);
+});
+
+test('director seek keeps exact ±180 endpoints and picks the short arc near the antipode', () => {
+  for (const [a, b] of [
+    [180, -180],
+    [-180, 180],
+  ]) {
+    assert.equal(cameraAtProgress(camera(a), camera(b), 0).lon, a);
+    assert.equal(cameraAtProgress(camera(a), camera(b), 1).lon, b);
+    assert.equal(
+      Math.abs(cameraAtProgress(camera(a), camera(b), 0.5).lon),
+      180,
+    );
+  }
+  // 10°E to 169.9°W is 179.9° westward through Greenwich, not 180.1° east.
+  const mid = cameraAtProgress(camera(10), camera(-169.9), 0.5).lon;
+  assert.ok(mid > -81 && mid < -79, `short arc midpoint, got ${mid}`);
+});
+
+test('director seek turns heading and roll the short way for any authored angles', () => {
+  const pose = (heading, roll) => ({ ...camera(0), heading, roll });
+  const mid = cameraAtProgress(pose(350, 350), pose(-350, -350), 0.5);
+  // 350° and -350° are 20° apart through 0°/360°, not 340° through 180°.
+  for (const value of [mid.heading, mid.roll]) {
+    const wrapped = ((value % 360) + 360) % 360;
+    assert.ok(wrapped < 1e-9 || 360 - wrapped < 1e-9, `got ${value}`);
+  }
+});

src/director/packs/asset-stream-cancellation.test.mjs

@@ -0,0 +1,79 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createAssetDirectorySource } from './source.js';
+test('cancellation during the terminating read cannot return a scene asset', async () => {
+  for (const cancel of [true, false]) {
+    const controller = new AbortController();
+    let reads = 0,
+      cancelled = 0,
+      released = 0;
+    const source = createAssetDirectorySource({
+      baseUrl: 'https://fixture.example/assets/',
+      fetchImpl: async () => ({
+        ok: true,
+        headers: new Headers({ 'content-type': 'application/octet-stream' }),
+        body: {
+          getReader() {
+            return {
+              async read() {
+                reads++;
+                if (reads === 1)
+                  return { done: false, value: new Uint8Array([1, 2]) };
+                if (cancel) controller.abort();
+                return { done: true };
+              },
+              async cancel() {
+                cancelled++;
+              },
+              releaseLock() {
+                released++;
+              },
+            };
+          },
+        },
+      }),
+    });
+    const pending = source({ path: 'scene.bin', signal: controller.signal });
+    if (cancel) await assert.rejects(pending, { name: 'AbortError' });
+    else assert.deepEqual([...(await pending).bytes], [1, 2]);
+    assert.equal(cancelled, 1);
+    assert.equal(released, 1);
+  }
+});
+
+test('cancellation during reader cleanup cannot return a scene asset', async () => {
+  const controller = new AbortController();
+  const reason = new DOMException('scene changed', 'AbortError');
+  let released = 0;
+  const source = createAssetDirectorySource({
+    baseUrl: 'https://fixture.example/assets/',
+    fetchImpl: async () => ({
+      ok: true,
+      headers: new Headers(),
+      body: {
+        getReader() {
+          let reads = 0;
+          return {
+            async read() {
+              reads++;
+              return reads === 1
+                ? { done: false, value: new Uint8Array([1]) }
+                : { done: true };
+            },
+            async cancel() {
+              controller.abort(reason);
+            },
+            releaseLock() {
+              released++;
+            },
+          };
+        },
+      },
+    }),
+  });
+  await assert.rejects(
+    source({ path: 'scene.bin', signal: controller.signal }),
+    (error) => error === reason,
+  );
+  assert.equal(released, 1);
+});

src/director/packs/source.js

@@ -41,6 +41,7 @@ export function createAssetDirectorySource({
       for (;;) {
         signal?.throwIfAborted();
         const { done, value } = await reader.read();
+        signal?.throwIfAborted();
         if (done) break;
         length += value.byteLength;
         if (length > maxBytes) throw new Error('Asset exceeds byte limit');
@@ -50,6 +51,8 @@ export function createAssetDirectorySource({
       await reader.cancel().catch(() => {});
       reader.releaseLock();
     }
+    // Cleanup awaits too; a cancel during it must still discard the asset.
+    signal?.throwIfAborted();
     const bytes = new Uint8Array(length);
     let offset = 0;
     for (const chunk of chunks) {

src/director/timeline.js

@@ -2,6 +2,7 @@ import {
   resolveCameraPose,
   resolveCameraMove,
   sampleCameraMove,
+  normalizeCameraLongitude,
 } from './camera.js';
 
 const DEFAULT_SHOT_DURATION_SEC = 4;
@@ -40,12 +41,19 @@ export function cameraAtProgress(fromCamera, toCamera, progress) {
   const lerp = (from, to) => Number(from) + (Number(to) - Number(from)) * eased;
   const lerpAngle = (from, to) => {
     const start = Number(from) || 0;
-    const delta = ((Number(to) - start + 540) % 360) - 180;
+    // Double modulo keeps the delta in [-180, 180) for any authored angles,
+    // as sampleCameraMove does; a single % goes negative below -540.
+    const delta = ((((Number(to) - start + 540) % 360) + 360) % 360) - 180;
     return start + delta * eased;
   };
   return {
     lat: lerp(source.lat, target.lat),
-    lon: lerp(source.lon, target.lon),
+    lon:
+      t === 0
+        ? Number(source.lon)
+        : t === 1
+          ? Number(target.lon)
+          : normalizeCameraLongitude(lerpAngle(source.lon, target.lon)),
     alt: lerp(source.alt, target.alt),
     heading: lerpAngle(source.heading, target.heading),
     pitch: lerp(source.pitch, target.pitch),

src/firstRunExperience.test.mjs

@@ -673,11 +673,11 @@ test('the voice TOOL SCHEMA matches the pinned contract — the mission mapping
   // referent-only track_entity alternative (kept out of the model-facing
   // schema, which may not carry top-level anyOf), and Contacts requested-radius
   // list descriptions; the missions still ride existing tools.
-  // Street Level adds toggle enum values and the generated alias hint.
-  assert.equal(block.length, 29802, 'serialized tool schema length drifted');
+  // Street Level and GNSS extend the manifest; broadcast caveats describe tracked and analyst aircraft.
+  assert.equal(block.length, 30511, 'serialized tool schema length drifted');
   assert.equal(
     crypto.createHash('sha256').update(block).digest('hex'),
-    'b316ca2e67848eb565b6847ac044a19d1465d8ef8252a5dfbd7d947a2a36d5ed',
+    '62d5df9cedf413403e4fd0a7cbe94bb2cd13736c3d8fedc84bcccd63ad253eb6',
     'the first-run missions must ride EXISTING tools: no schema edit, no cache bust',
   );
   const instructions = fs.readFileSync(new URL('../server/providers/openai/instructions.js', import.meta.url), 'utf8');

src/googleGeocodeProxy.test.mjs

@@ -0,0 +1,204 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  googlePlacesContextProxy,
+  validateGeocodeAddress,
+  geocodeBounds,
+} from '../vite.config.js';
+
+const UPSTREAM = 'https://geocode.test/json';
+
+function installRoutes({ apiKey = 'server-secret', fetchImpl } = {}) {
+  const routes = new Map();
+  googlePlacesContextProxy({
+    resolveApiKey: () => apiKey,
+    fetchImpl,
+    endpoints: { geocode: UPSTREAM },
+  }).configureServer({
+    middlewares: { use: (name, handler) => routes.set(name, handler) },
+  });
+  return routes;
+}
+
+function invokeRoute(handler, { method = 'GET', url = '/' } = {}) {
+  return new Promise((resolve, reject) => {
+    const headers = new Map();
+    const res = {
+      statusCode: 200,
+      setHeader(name, value) {
+        headers.set(String(name).toLowerCase(), String(value));
+      },
+      end(body = '') {
+        resolve({
+          statusCode: this.statusCode,
+          headers: Object.fromEntries(headers),
+          body: body ? JSON.parse(String(body)) : null,
+        });
+      },
+    };
+    Promise.resolve(
+      handler(
+        { method, url, headers: {}, socket: { remoteAddress: '127.0.0.1' } },
+        res,
+      ),
+    ).catch(reject);
+  });
+}
+
+test('geocoder query and viewport bias are validated before Google is paid', () => {
+  assert.deepEqual(validateGeocodeAddress(new URLSearchParams()), {
+    ok: false,
+    error: 'address is required',
+  });
+  assert.deepEqual(validateGeocodeAddress(new URLSearchParams({ address: '  ' })), {
+    ok: false,
+    error: 'address is required',
+  });
+  assert.deepEqual(
+    validateGeocodeAddress(new URLSearchParams({ address: 'x'.repeat(201) })),
+    { ok: false, error: 'address is too long' },
+  );
+  assert.deepEqual(
+    validateGeocodeAddress(new URLSearchParams({ address: ' Austin ' })),
+    { ok: true, address: 'Austin' },
+  );
+
+  // A bias only ranks results, so an unusable one is dropped, not refused.
+  const bias = '30.1,-97.9|30.4,-97.6';
+  assert.equal(geocodeBounds(new URLSearchParams({ bounds: bias })), bias);
+  for (const bounds of [
+    '',
+    '30.1,-97.9',
+    '30.1,-97.9|30.4',
+    'north,-97.9|30.4,-97.6',
+    '91,-97.9|30.4,-97.6',
+    '30.1,-181|30.4,-97.6',
+    // A blank component must not read as 0 — that is the equator, not a corner.
+    '30.1,-97.9|30.4,',
+    '30.1,|30.4,-97.6',
+    '30.1,-97.9| ,-97.6',
+  ])
+    assert.equal(geocodeBounds(new URLSearchParams({ bounds })), null);
+});
+
+test('the geocode routes keep the key server-side and answer in Google shape', async () => {
+  const upstream = [];
+  const routes = installRoutes({
+    fetchImpl: async (url) => {
+      upstream.push(new URL(String(url)));
+      return Response.json({ status: 'OK', results: [{ place_id: 'fixture' }] });
+    },
+  });
+  const forward = routes.get('/api/google/geocode');
+  const reverse = routes.get('/api/google/reverse-geocode');
+  assert.equal(typeof forward, 'function');
+  assert.equal(typeof reverse, 'function');
+
+  const forwarded = await invokeRoute(forward, {
+    url: '/?address=Austin&bounds=30.1,-97.9|30.4,-97.6',
+  });
+  assert.equal(forwarded.statusCode, 200);
+  assert.deepEqual(forwarded.body, {
+    status: 'OK',
+    results: [{ place_id: 'fixture' }],
+  });
+  assert.equal(upstream.at(-1).searchParams.get('address'), 'Austin');
+  assert.equal(upstream.at(-1).searchParams.get('bounds'), '30.1,-97.9|30.4,-97.6');
+  assert.equal(upstream.at(-1).searchParams.get('key'), 'server-secret');
+
+  const reversed = await invokeRoute(reverse, { url: '/?lat=30.27&lon=-97.74' });
+  assert.equal(reversed.statusCode, 200);
+  assert.equal(upstream.at(-1).searchParams.get('latlng'), '30.27,-97.74');
+  assert.equal(upstream.at(-1).searchParams.get('key'), 'server-secret');
+
+  // The key travels to Google, never back to the page that asked.
+  assert.ok(!JSON.stringify(forwarded.body).includes('server-secret'));
+  assert.ok(!JSON.stringify(reversed.body).includes('server-secret'));
+
+  // A malformed bias is dropped rather than forwarded.
+  await invokeRoute(forward, { url: '/?address=Austin&bounds=north' });
+  assert.equal(upstream.at(-1).searchParams.has('bounds'), false);
+});
+
+test('a bad or keyless geocode request never reaches Google', async () => {
+  const upstream = [];
+  const fetchImpl = async (url) => {
+    upstream.push(String(url));
+    return Response.json({ status: 'OK', results: [] });
+  };
+
+  const routes = installRoutes({ fetchImpl });
+  for (const [path, url] of [
+    ['/api/google/geocode', '/?address='],
+    ['/api/google/reverse-geocode', '/?lat=91&lon=-97.74'],
+  ]) {
+    const response = await invokeRoute(routes.get(path), { url });
+    assert.equal(response.statusCode, 400);
+    assert.deepEqual(response.body.results, []);
+    assert.equal(response.body.status, 'REQUEST_DENIED');
+  }
+
+  for (const path of ['/api/google/geocode', '/api/google/reverse-geocode']) {
+    const rejected = await invokeRoute(routes.get(path), {
+      method: 'POST',
+      url: '/?address=Austin&lat=30&lon=-97',
+    });
+    assert.equal(rejected.statusCode, 405);
+  }
+
+  // Keyless is an empty capability, not an outage: a 200 the browser adapters
+  // read as "this provider did not answer", so the chain moves on. It resolves
+  // ahead of validation, like the Places routes: with nothing configured there
+  // is no request to validate and no quota to protect.
+  const keyless = installRoutes({ apiKey: '  ', fetchImpl });
+  for (const path of ['/api/google/geocode', '/api/google/reverse-geocode'])
+    for (const url of ['/?address=Austin&lat=30&lon=-97', '/?address=&lat=91']) {
+      const response = await invokeRoute(keyless.get(path), { url });
+      assert.equal(response.statusCode, 200);
+      assert.equal(response.headers['cache-control'], 'no-store');
+      assert.deepEqual(response.body, {
+        configured: false,
+        status: 'REQUEST_DENIED',
+        results: [],
+        error: null,
+      });
+    }
+
+  assert.deepEqual(upstream, []);
+});
+
+test('an upstream failure reaches the browser as fixed public text', async () => {
+  const routes = installRoutes({
+    fetchImpl: async () => {
+      throw new Error('connect ECONNREFUSED 10.0.0.7:443');
+    },
+  });
+  for (const path of ['/api/google/geocode', '/api/google/reverse-geocode']) {
+    const response = await invokeRoute(routes.get(path), {
+      url: '/?address=Austin&lat=30&lon=-97',
+    });
+    assert.equal(response.statusCode, 502);
+    assert.deepEqual(response.body, {
+      status: 'UNKNOWN_ERROR',
+      results: [],
+      error: 'Google Geocoding request failed',
+    });
+  }
+});
+
+test('an oversized upstream body is dropped rather than buffered', async () => {
+  const routes = installRoutes({
+    // Two hundred times the 256 KiB ceiling, declared honestly.
+    fetchImpl: async () =>
+      Response.json({ status: 'OK', results: [{ pad: 'x'.repeat(52_428_800) }] }),
+  });
+  const response = await invokeRoute(routes.get('/api/google/geocode'), {
+    url: '/?address=Austin',
+  });
+  assert.equal(response.statusCode, 502);
+  assert.deepEqual(response.body, {
+    status: 'UNKNOWN_ERROR',
+    results: [],
+    error: 'Google Geocoding request failed',
+  });
+});

src/googleServerKey.test.mjs

@@ -67,11 +67,19 @@ test('the Street View tool resolves per-variable overrides before preferring the
   }
 });
 
-test('both Places routes select the intended key and keep it out of responses', async (t) => {
+test('every Google route selects the intended key and keeps it out of responses', async (t) => {
   const original = { server: process.env.GOOGLE_MAPS_SERVER_API_KEY, browser: process.env.GOOGLE_MAPS_API_KEY, limit: process.env.GEV_RATELIMIT_GOOGLE_PER_MIN };
   const calls = [];
   t.mock.method(globalThis, 'fetch', async (url, options) => {
-    calls.push({ url, key: options.headers['X-Goog-Api-Key'] });
+    // Places sends the key as a header; Geocoding's web service takes it as a
+    // query parameter. Either way it must be the server key, and never the
+    // browser's copy of it.
+    calls.push({
+      url,
+      key:
+        options?.headers?.['X-Goog-Api-Key'] ??
+        new URL(String(url)).searchParams.get('key'),
+    });
     return Response.json({ places: [] });
   });
   try {
@@ -88,12 +96,12 @@ test('both Places routes select the intended key and keep it out of responses',
       for (const install of ['configureServer', 'configurePreviewServer']) {
         const routes = new Map();
         googlePlacesContextProxy()[install]({ middlewares: { use: (name, handler) => routes.set(name, handler) } });
-        assert.equal(routes.size, 2);
+        assert.equal(routes.size, 4);
         for (const handler of routes.values()) {
           const before = calls.length;
           let body;
           const res = { setHeader() {}, end(value) { body = value; } };
-          await handler({ method: 'GET', url: '/?lat=30&lon=-97&q=capitol', headers: {}, socket: { remoteAddress: '127.0.0.1' } }, res);
+          await handler({ method: 'GET', url: '/?lat=30&lon=-97&q=capitol&address=capitol', headers: {}, socket: { remoteAddress: '127.0.0.1' } }, res);
           assert.equal(res.statusCode, 200);
           assert.ok(!body.includes('server-secret'));
           if (expected) {

src/keySetupCore.mjs

@@ -36,7 +36,7 @@ export const KEY_SETUP_KEYS = Object.freeze([
   Object.freeze({
     id: 'google-maps',
     title: 'GOOGLE MAPS',
-    unlocks: 'The photorealistic 3D planet + place search',
+    unlocks: 'The photorealistic 3D planet, place search + Street View',
     getUrl: 'https://developers.google.com/maps/documentation/tile/get-api-key',
     envVars: Object.freeze(['GOOGLE_MAPS_API_KEY']),
     tier: 'metered',
@@ -352,6 +352,28 @@ export function keySetupRequirement(id) {
   return `Needs ${entry.envVars.join(' + ')} — add it in Provider Settings`;
 }
 
+/**
+ * Key guidance that also names switched-off sources whose key is already set.
+ * @param {string} requirement What `keySetupRequirement` said ('' allowed).
+ * @param {Array<{label: string, requiresKeyId?: string|null}>} [alternatives]
+ */
+export function keySetupWithAlternatives(requirement, alternatives = []) {
+  const options = alternatives.map(({ label, requiresKeyId }) => {
+    const entry = KEY_SETUP_KEYS.find(
+      (candidate) => candidate.id === requiresKeyId,
+    );
+    const name = entry
+      ? entry.title
+          .toLowerCase()
+          .replace(/\b\w/g, (letter) => letter.toUpperCase())
+      : null;
+    return name ? `light ${label} to use your ${name} key` : `light ${label}`;
+  });
+  if (!options.length) return requirement;
+  const offer = `or ${options.join(', or ')}`;
+  return requirement ? `${requirement}, ${offer}` : offer.replace(/^or l/, 'L');
+}
+
 /**
  * Decide whether a live provider value belongs to a source outside the store
  * Provider Settings is allowed to edit. `wasExternalAtBoot` carries source

src/keySetupCore.test.mjs

@@ -9,6 +9,7 @@ import {
   isKeySetupExternallyManaged,
   keySetupStatus,
   keySetupRequirement,
+  keySetupWithAlternatives,
   knownKeySetupEnvVars,
   parseWindowsUserSid,
   upsertDotenvValues,
@@ -362,3 +363,16 @@ test('server Google key remains supported without appearing in setup or its miss
   assert.ok(!JSON.stringify(status).includes('GOOGLE_MAPS_SERVER_API_KEY'));
   assert.ok(!JSON.stringify(status).includes(secret));
 });
+
+test('key guidance can offer another source that works with a key already set', () => {
+  const streetView = { label: 'STREET VIEW', requiresKeyId: 'google-maps' };
+  assert.equal(
+    keySetupWithAlternatives(keySetupRequirement('mapillary'), [streetView]),
+    'Needs MAPILLARY_CLIENT_TOKEN — add it in Provider Settings, or light STREET VIEW to use your Google Maps key',
+  );
+  assert.equal(
+    keySetupWithAlternatives('', [streetView]),
+    'Light STREET VIEW to use your Google Maps key',
+  );
+  assert.equal(keySetupWithAlternatives('Needs X', []), 'Needs X');
+});

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/directions/index.js

@@ -617,32 +617,11 @@ export function createDirectionsLayer({ services, source }) {
   }
 
   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 {

src/layers/flights/policy.js

@@ -7,6 +7,7 @@ export {
   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 +15,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

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,
@@ -167,6 +168,10 @@ export function createQueries({
         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 +224,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 +261,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,
     };

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

src/layers/flights/records.test.mjs

@@ -106,3 +106,13 @@ 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('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,
@@ -54,13 +56,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 +152,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 +183,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
@@ -1009,10 +1030,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/gnss/index.js

@@ -0,0 +1,422 @@
+import * as Cesium from 'cesium';
+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: 'Low-accuracy score < 2%',
+  medium: 'Low-accuracy score 2–10%',
+  high: '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 || '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:
+          'Regional sample · 250 nm radius · cells from visited views over 30 min' +
+          (_lastError && _retryAt
+            ? ` · ${_lastError} · Retrying automatically${
+                _retryAt <= 8640000000000000
+                  ? ` at ${new Date(_retryAt).toISOString().slice(11, 19)} UTC`
+                  : ' after provider cooldown'
+              }`
+            : ''),
+        infoTitle:
+          '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: LEVEL_LABELS[level],
+          color: GNSS_LEVEL_COLORS[level],
+          count: _cells.filter((cell) => cell.level === level).length,
+          ...(index === 0
+            ? {
+                blurb: `Low-accuracy score = 100 × max(0, bad − 1) / total: one aircraft is discounted, so this is not the raw share. Cells need ${GNSS_MIN_AIRCRAFT} aircraft over ${provenance.window.minutes} minutes. Navigation-integrity anomalies are not a detection of jamming or spoofing.`,
+              }
+            : {}),
+        })),
+      };
+    },
+
+    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,76 @@
+import { readResponseJsonCapped } from '../../sources/httpBody.js';
+
+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('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(
+            limited
+              ? '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('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('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,
+      };
+    },
+  };
+}

src/layers/gnss/source.test.mjs

@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAdsbGnssSource } from './source.js';
+
+test('the source asks the same-origin proxy for the view anchor', async () => {
+  const calls = [];
+  const source = createAdsbGnssSource({
+    fetchImpl: async (url, options) => {
+      calls.push(url);
+      assert.ok(options.signal instanceof AbortSignal);
+      return Response.json({
+        fetchedAt: 5,
+        ageMs: 0,
+        classifier: 'gev-nic-nacp-v2',
+        rows: [{ hex: 'abc123' }],
+      });
+    },
+  });
+  const snapshot = await source.getSnapshot(
+    { latitude: 50.06143, longitude: 19.93658 },
+    { signal: new AbortController().signal },
+  );
+  assert.deepEqual(calls, ['/api/gnss-integrity?lat=50&lon=20']);
+  assert.deepEqual(snapshot, {
+    rows: [{ hex: 'abc123' }],
+    ageMs: 0,
+    fetchedAt: 5,
+    stale: false,
+    classifier: 'gev-nic-nacp-v2',
+  });
+});
+
+test('the source reports stale proxy data and rejects bad input or responses', async () => {
+  const reply = (body, init) => async () => Response.json(body, init);
+  const stale = await createAdsbGnssSource({
+    fetchImpl: reply({ rows: [], fetchedAt: 7, ageMs: 90_000, stale: true }),
+  }).getSnapshot({ latitude: 1, longitude: 2 });
+  assert.equal(stale.stale, true);
+  assert.equal(stale.ageMs, 90_000, 'a stale reply keeps its observation age');
+  assert.equal(stale.fetchedAt, 7);
+  assert.equal(stale.classifier, null);
+  // Without an observation age the rows could only be dated as new.
+  for (const ageMs of [undefined, null, '7', -1, Number.NaN])
+    await assert.rejects(
+      createAdsbGnssSource({
+        fetchImpl: reply({ rows: [], fetchedAt: 7, ageMs }),
+      }).getSnapshot({ latitude: 1, longitude: 2 }),
+      /no observation time/,
+    );
+
+  await assert.rejects(
+    createAdsbGnssSource({ fetchImpl: reply({}) }).getSnapshot({}),
+    /view anchor/,
+  );
+  await assert.rejects(
+    createAdsbGnssSource({
+      fetchImpl: reply({ error: 'x' }, { status: 502 }),
+    }).getSnapshot({ latitude: 1, longitude: 2 }),
+    /HTTP 502/,
+  );
+  await assert.rejects(
+    createAdsbGnssSource({ fetchImpl: reply({ rows: 'no' }) }).getSnapshot({
+      latitude: 1,
+      longitude: 2,
+    }),
+    /Malformed/,
+  );
+  const controller = new AbortController();
+  controller.abort();
+  await assert.rejects(
+    createAdsbGnssSource({ fetchImpl: reply({ rows: [] }) }).getSnapshot(
+      { latitude: 1, longitude: 2 },
+      { signal: controller.signal },
+    ),
+  );
+});
+
+test('HTTP failures distinguish rate limiting, preserve Retry-After and classify retryability', async () => {
+  const at = Date.UTC(2026, 9, 13, 12);
+  for (const [status, header, delay, retryable] of [
+    [429, '3600', 3600000, true],
+    [429, new Date(at + 3600000).toUTCString(), 3600000, true],
+    [429, null, 60000, true],
+    [429, 'Infinity', 60000, true],
+    [502, '5', 5000, true],
+    [502, null, null, true],
+    [400, null, null, false],
+  ]) {
+    const source = createAdsbGnssSource({
+      now: () => at,
+      fetchImpl: async () =>
+        Response.json(
+          {},
+          { status, headers: header ? { 'Retry-After': header } : {} },
+        ),
+    });
+    await assert.rejects(
+      source.getSnapshot({ latitude: 50, longitude: 20 }),
+      (e) => {
+        assert.equal(e.status, status);
+        assert.equal(e.retryAfterMs, delay);
+        assert.equal(e.retryable, retryable);
+        assert.match(
+          e.message,
+          status === 429 ? /rate limited/ : /feed unavailable/,
+        );
+        return true;
+      },
+    );
+  }
+});

src/layers/military/policy.js

@@ -6,6 +6,7 @@ export {
   ERROR_BACKOFF_INTERVAL,
 } from './recordPolicy.js';
 import * as Cesium from 'cesium';
+import { EMERGENCY_TINT_CSS } from '../../data/aircraftEmergency.js';
 
 /**
  * @module militaryFlights
@@ -40,6 +41,11 @@ export const MIL_ICON_COLOR = Cesium.Color.fromCssColorString('#FFB800');
 
 export const TRACKED_ICON_COLOR = Cesium.Color.fromCssColorString('#FFD166');
 
+/** @constant {Cesium.Color} Red tint for aircraft broadcasting an emergency (mirror of flights) */
+
+export const EMERGENCY_ICON_COLOR =
+  Cesium.Color.fromCssColorString(EMERGENCY_TINT_CSS);
+
 // --- Ground traffic (owner reversal 2026-07-03; mirror of flights.js) ---------------
 // adsb.lol/readsb flags ground traffic with alt_baro === "ground" (no separate
 // boolean). Such aircraft are RENDERED instead of floating at the 3 km altitude

src/layers/military/queries.js

@@ -9,6 +9,7 @@ import {
   CONTACT_MATCH_TIER,
 } from '../../data/contactMatch.js';
 import { LANDED_ALT_MAX_FT, LANDED_SPEED_MAX_MPS } from './policy.js';
+import { emergencyBroadcastPhrase } from '../../data/aircraftEmergency.js';
 
 export function createQueries({
   flightState,
@@ -133,6 +134,10 @@ export function createQueries({
         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),
     };
   }
 
@@ -156,7 +161,9 @@ 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: null,
-   *   operator: string|null, routeOrigin: null, routeDestination: null}}
+   *   operator: string|null, squawk: string|null, emergency: boolean,
+   *   emergencyKind: string|null, emergencySource: 'squawk'|'ads-b'|null,
+   *   emergencyBroadcast: string|null, lastContactAtMs: number|null, routeOrigin: null, routeDestination: null}}
    */
 
   function mapAnalystRecord(icao24, info) {
@@ -187,6 +194,20 @@ export function createQueries({
       aircraftClass: tr3bAircraftClass(icao24, text(info?.klass)),
       originCountry: null,
       operator: text(info?.operator),
+      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: null,
       routeDestination: null,
     };

src/layers/military/records.js

@@ -1,6 +1,7 @@
 import { pickRenderAltitudeM } from '../../data/renderAltitude.js';
 import { stickyText, stickyNumber } from '../../data/aircraftMeta.js';
 import { classifyAircraft } from '../../data/aircraftClass.js';
+import { aircraftEmergency } from '../../data/aircraftEmergency.js';
 import {
   GROUND_FLOOR_WARM_MAX_ALT_M,
   LANDED_MISSING_POLL_LIMIT,
@@ -161,6 +162,9 @@ export class MilitaryFlightRecords {
         null,
       ),
       turnRateDps: prevMeta?.turnRateDps || 0,
+      // Per poll, NOT sticky (mirror of flights): a cleared code clears here.
+      squawk: aircraft.squawk ?? null,
+      emergency: aircraftEmergency(aircraft),
       onGround,
       // Round 7: sticky airborne history (see _likelyLanded).
       wasAirborne: prevMeta?.wasAirborne === true || !onGround,

src/layers/military/records.test.mjs

@@ -98,3 +98,19 @@ test('military records keep bounded partial retention and release metadata only
     'remove',
   );
 });
+
+test('military emergency status follows the latest poll instead of sticking', () => {
+  const records = store();
+  const first = records.receive(
+    observation({ squawk: '1234', emergency: 'minfuel' }),
+    context(),
+  );
+  assert.equal(first.meta.squawk, '1234');
+  assert.equal(first.meta.emergency.kind, 'minfuel');
+  assert.equal(first.meta.emergency.severity, 'priority');
+  const next = records.receive(
+    observation({ squawk: '1234', emergency: 'none' }),
+    context(),
+  );
+  assert.equal(next.meta.emergency, null);
+});

src/layers/military/rendering.js

@@ -18,6 +18,7 @@ import {
   screenProjectedRotation,
 } from '../../data/iconOrientation.js';
 import { limitCourseStep, courseSlewCapDps } from '../../data/motionModel.js';
+import { isEmergency } from '../../data/aircraftEmergency.js';
 import {
   PLANE_MODEL_SCALE,
   PLANE_MODEL_URL,
@@ -33,6 +34,7 @@ import {
   COCKPIT_CONTACT_SIZE_PX,
   MIL_ICON_COLOR,
   TRACKED_ICON_COLOR,
+  EMERGENCY_ICON_COLOR,
   MODEL_ALT_CEIL_M,
   MODEL_MAX_ALL,
   MODEL_MAX,
@@ -159,7 +161,7 @@ export function createRendering({
       bb.height = COCKPIT_CONTACT_SIZE_PX;
       bb.scale = limbScale;
       bb.scaleByDistance = _cockpitBillboardScaleByDistance();
-      bb.color = MIL_ICON_COLOR.withAlpha(freshnessAlpha);
+      bb.color = _fleetBillboardColor(icao24).withAlpha(freshnessAlpha);
       bb.rotation = 0;
       return;
     }
@@ -173,7 +175,9 @@ export function createRendering({
     bb.height = icao24 === flightState._trackedIcao ? 24 : 20;
     bb.scale = _militaryBillboardScale(icao24) * limbScale;
     bb.scaleByDistance = _normalBillboardScaleByDistance();
-    bb.color = MIL_ICON_COLOR.withAlpha(cyberSonarBaseAlpha(bb));
+    bb.color = _fleetBillboardColor(icao24, meta).withAlpha(
+      cyberSonarBaseAlpha(bb),
+    );
   }
 
   /** Sprite kind for one contact's billboard. Identity for every aircraft except
@@ -189,7 +193,17 @@ export function createRendering({
 
   function _modelColor(icao24) {
     if (icao24 === flightState._trackedIcao) return TRACKED_ICON_COLOR;
-    return MIL_ICON_COLOR;
+    return _fleetBillboardColor(icao24);
+  }
+
+  /** Fleet (untracked) tint: red while the latest poll broadcast an emergency,
+   *  amber otherwise. Cockpit far-contact dots use it too. */
+
+  function _fleetBillboardColor(
+    icao24,
+    info = flightState.records.data.get(icao24),
+  ) {
+    return isEmergency(info?.emergency) ? EMERGENCY_ICON_COLOR : MIL_ICON_COLOR;
   }
 
   /** The FLEET's 3D-model regime: models3d enabled AND the camera zoomed in past the altitude
@@ -965,7 +979,7 @@ export function createRendering({
       const isCockpitNear =
         flightState._cockpitContactMode &&
         flightState._cockpitNearContacts.has(icao24);
-      const baseColor = MIL_ICON_COLOR;
+      const baseColor = _fleetBillboardColor(icao24, info);
       const treatment = applyAircraftBillboardTreatment({
         billboard: bb,
         baseScale:
@@ -1082,6 +1096,7 @@ export function createRendering({
     _applyFleetBillboardPresentation,
     _iconKind,
     _modelColor,
+    _fleetBillboardColor,
     _modelRegimeActive,
     _modelCap,
     _modelAddDistM,

src/layers/military/snapshotRenderer.js

@@ -1,4 +1,5 @@
 import * as Cesium from 'cesium';
+import { cyberSonarBaseAlpha } from '../../cyberSonar.js';
 import { CLASS_SCALE_2D } from '../../data/aircraftClass.js';
 import {
   turnRateFromFixHistory,
@@ -7,12 +8,7 @@ import {
 } from '../../data/motionModel.js';
 import { aircraftIcon } from '../../data/aircraftIcons.js';
 import { POSITION_HISTORY_LIMIT } from './recordPolicy.js';
-import {
-  BILLBOARD_SCALE,
-  GROUND_SCALE,
-  TRACKED_ICON_COLOR,
-  MIL_ICON_COLOR,
-} from './policy.js';
+import { BILLBOARD_SCALE, GROUND_SCALE, TRACKED_ICON_COLOR } from './policy.js';
 
 /** Apply military record changes to Cesium resources and existing follow operations. */
 export function createMilitarySnapshotRenderer({
@@ -125,6 +121,11 @@ export function createMilitarySnapshotRenderer({
 
       if (flightState._billboards.has(icao24)) {
         const bb = flightState._billboards.get(icao24);
+        if (!isTracked) {
+          bb.color = rendering
+            ._fleetBillboardColor(icao24, meta)
+            .withAlpha(cyberSonarBaseAlpha(bb));
+        }
         // Position AND rotation are owned by the fleet pass (_fleetTick);
         // course changes land on the next rotation pass (forced below).
         // Ground flips (landing/takeoff) restyle this SAME billboard in
@@ -161,7 +162,9 @@ export function createMilitarySnapshotRenderer({
           // Screen-projected rotation lands on the next fleet tick.
           rotation: 0,
           alignedAxis: Cesium.Cartesian3.ZERO,
-          color: isTracked ? TRACKED_ICON_COLOR : MIL_ICON_COLOR,
+          color: isTracked
+            ? TRACKED_ICON_COLOR
+            : rendering._fleetBillboardColor(icao24, meta),
           sizeInMeters: false,
           scaleByDistance: rendering._normalBillboardScaleByDistance(),
           // Grounded/near-surface planes sit at/below the photoreal tile

src/layers/military/tracking.js

@@ -21,7 +21,6 @@ import {
   TRAIL_COLOR,
   BILLBOARD_SCALE,
   GROUND_SCALE,
-  MIL_ICON_COLOR,
   AMBER_TRANSPARENT,
   TRACKED_ICON_COLOR,
 } from './policy.js';
@@ -780,12 +779,16 @@ export function createTracking({
       bb.width = 20;
       bb.height = 20;
       // Ground-aware restore (a plane untracked while taxiing comes back at
-      // ground scale; tint is full amber on the ground and in the air).
+      // ground scale; the fleet tint is amber, or red while broadcasting an
+      // emergency, on the ground and in the air).
       bb.scale =
         BILLBOARD_SCALE *
         (CLASS_SCALE_2D[meta?.klass] || 1) *
         (meta?.onGround ? GROUND_SCALE : 1);
-      bb.color = MIL_ICON_COLOR;
+      bb.color = parts.rendering._fleetBillboardColor(
+        flightState._trackedIcao,
+        meta,
+      );
       bb.rotation = flightState._lastTrackedRotation;
     }
     flightState._lastCamPoseSig = ''; // force a fleet rotation pass on the next tick

src/layers/recentImagery/catalog.js

@@ -27,7 +27,8 @@ const CMR_SEARCH_AFTER = 'CMR-Search-After';
 /**
  * Read one product's granules across CMR pages, sending back each response's
  * `CMR-Search-After` cursor until a short page, a missing cursor or the
- * record cap ends the walk. `truncated` is measured against CMR's `hits`.
+ * record cap ends the walk. `truncated` means CMR's `hits` exceed the rows
+ * read, or the cap dropped valid granules from the last page read.
  * @param {{ product: string, url: string, fetchImpl: typeof fetch, signal?: AbortSignal, maxRecords?: number }} request
  * @returns {Promise<{ granules: Array<object>, truncated: boolean }>}
  */
@@ -40,6 +41,8 @@ export async function fetchCmrPages({
 }) {
   const granules = [];
   let hits = 0;
+  let readCount = 0;
+  let capped = 0;
   let cursor = null;
   for (;;) {
     const init = { signal };
@@ -47,19 +50,27 @@ export async function fetchCmrPages({
     const response = await fetchImpl(url, init);
     if (!response?.ok)
       throw new Error(`HTTP ${response?.status ?? 'error'} from CMR`);
-    const page = parseCmrUmm(await response.json(), product);
-    granules.push(...page.granules);
+    const json = await response.json();
+    const rawCount = Array.isArray(json?.items) ? json.items.length : 0;
+    const page = parseCmrUmm(json, product);
+    readCount += rawCount;
+    const admitted = page.granules.slice(
+      0,
+      Math.max(0, maxRecords - granules.length),
+    );
+    granules.push(...admitted);
+    capped += page.granules.length - admitted.length;
     hits = Math.max(hits, page.hits);
     cursor = response.headers?.get?.(CMR_SEARCH_AFTER) ?? null;
     if (
       !cursor ||
-      page.granules.length < CMR_PAGE_SIZE ||
-      granules.length >= maxRecords ||
-      granules.length >= hits
+      rawCount < CMR_PAGE_SIZE ||
+      readCount >= maxRecords ||
+      readCount >= hits
     )
       break;
   }
-  return { granules, truncated: hits > granules.length };
+  return { granules, truncated: hits > readCount || capped > 0 };
 }
 
 function finiteOrNull(value) {

src/layers/recentImagery/cmr-raw-page-budget.test.mjs

@@ -0,0 +1,98 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { fetchCmrPages } from './catalog.js';
+const item = (id) => ({
+  meta: { 'concept-id': id },
+  umm: {
+    TemporalExtent: {
+      RangeDateTime: { BeginningDateTime: '2026-09-18T12:00:00Z' },
+    },
+  },
+});
+test('discarded rows do not turn a full CMR page into a final page', async () => {
+  let calls = 0;
+  const result = await fetchCmrPages({
+    product: 'S30',
+    url: 'fixture',
+    fetchImpl: async () => {
+      calls++;
+      const items =
+        calls === 1
+          ? Array.from({ length: 200 }, (_, i) =>
+              i === 0 ? {} : item(String(i)),
+            )
+          : [item('last')];
+      return Response.json(
+        { hits: 201, items },
+        { headers: { 'CMR-Search-After': `cursor-${calls}` } },
+      );
+    },
+  });
+  assert.equal(calls, 2);
+  assert.equal(result.granules.length, 200);
+  assert.equal(result.granules.at(-1).id, 'last');
+  assert.equal(result.truncated, false);
+});
+test('a non-page-multiple limit never returns more admitted records than its budget', async () => {
+  let calls = 0;
+  const result = await fetchCmrPages({
+    product: 'S30',
+    url: 'fixture',
+    maxRecords: 250,
+    fetchImpl: async () => {
+      calls++;
+      return Response.json(
+        {
+          hits: 1000,
+          items: Array.from({ length: 200 }, (_, i) => item(`${calls}:${i}`)),
+        },
+        { headers: { 'CMR-Search-After': `cursor-${calls}` } },
+      );
+    },
+  });
+  assert.equal(calls, 2);
+  assert.equal(result.granules.length, 250);
+  assert.equal(result.truncated, true);
+});
+test('valid records dropped by the cap mark the result truncated even when every hit was read', async () => {
+  let calls = 0;
+  const result = await fetchCmrPages({
+    product: 'S30',
+    url: 'fixture',
+    maxRecords: 250,
+    fetchImpl: async () => {
+      calls++;
+      return Response.json(
+        {
+          hits: 400,
+          items: Array.from({ length: 200 }, (_, i) => item(`${calls}:${i}`)),
+        },
+        { headers: { 'CMR-Search-After': `cursor-${calls}` } },
+      );
+    },
+  });
+  assert.equal(calls, 2);
+  assert.equal(result.granules.length, 250);
+  assert.equal(result.truncated, true);
+});
+test('malformed rows discarded under the cap leave a fully examined result untruncated', async () => {
+  let calls = 0;
+  const result = await fetchCmrPages({
+    product: 'S30',
+    url: 'fixture',
+    maxRecords: 250,
+    fetchImpl: async () => {
+      calls++;
+      const items = Array.from({ length: 200 }, (_, i) =>
+        calls === 2 && i >= 50 ? {} : item(`${calls}:${i}`),
+      );
+      return Response.json(
+        { hits: 400, items },
+        { headers: { 'CMR-Search-After': `cursor-${calls}` } },
+      );
+    },
+  });
+  assert.equal(calls, 2);
+  assert.equal(result.granules.length, 250);
+  assert.equal(result.truncated, false);
+});

src/layers/recentImagery/imagery-box-missing-edge.test.mjs

@@ -0,0 +1,48 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  boxCentre,
+  boxFromRectangle,
+  dequantizeBox,
+  validateBox,
+} from './model.js';
+import { searchHls } from './catalog.js';
+
+test('missing imagery edges do not turn into invented zero coordinates', () => {
+  for (const value of [null, undefined, '', ' ', false, true]) {
+    const box = { west: value, south: 0, east: 1, north: 1 };
+    assert.equal(validateBox(box).ok, false);
+    assert.equal(validateBox(box).reason, 'invalid');
+    assert.equal(boxCentre(box), null);
+  }
+  assert.equal(validateBox({ west: 0, south: 0, east: 1, north: 1 }).ok, true);
+  assert.equal(
+    validateBox({ west: '0', south: '0', east: '1', north: '1' }).ok,
+    true,
+  );
+});
+
+test('every edge and every box entry point refuses a missing edge', async () => {
+  const blanks = [null, undefined, '', ' ', false, [], {}];
+  for (const edge of ['west', 'south', 'east', 'north']) {
+    for (const value of blanks) {
+      const box = { west: 1, south: 1, east: 2, north: 2, [edge]: value };
+      assert.equal(validateBox(box).ok, false, `${edge}=${String(value)}`);
+      // Share-link integers and Cesium radians are converted per edge.
+      assert.equal(dequantizeBox(box), null, `share ${edge}`);
+      assert.equal(boxFromRectangle(box), null, `radians ${edge}`);
+    }
+  }
+  let fetched = false;
+  await assert.rejects(
+    searchHls({
+      box: { west: ' ', south: 1, east: 2, north: 2 },
+      fetchImpl: async () => {
+        fetched = true;
+      },
+    }),
+    TypeError,
+  );
+  assert.equal(fetched, false);
+  assert.ok(dequantizeBox({ west: 0, south: 0, east: 100000, north: 100000 }));
+});

src/layers/recentImagery/model.js

@@ -75,6 +75,14 @@ const pad2 = (value) => String(value).padStart(2, '0');
  * east are not swapped: west > east crosses the dateline and `validateBox`
  * rejects it. Null when any edge is nonfinite.
  */
+/** A box edge as a number, or null when it is missing, blank or not numeric. */
+function edgeNumber(value) {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
 function normalizeBox(box) {
   if (!box || typeof box !== 'object') return null;
   const [west, south, east, north] = [
@@ -82,8 +90,8 @@ function normalizeBox(box) {
     box.south,
     box.east,
     box.north,
-  ].map(Number);
-  if (![west, south, east, north].every(Number.isFinite)) return null;
+  ].map(edgeNumber);
+  if ([west, south, east, north].some((edge) => edge == null)) return null;
   return {
     west,
     south: Math.min(south, north),
@@ -211,11 +219,16 @@ export function boxFromPin(lon, lat, sideKm = PIN_BOX_SIDE_KM) {
 
 function mapBox(box, fn) {
   if (!box || typeof box !== 'object') return null;
+  // Converting first would turn a blank edge into 0 before normalizeBox sees it.
+  const edge = (value) => {
+    const number = edgeNumber(value);
+    return number == null ? null : fn(number);
+  };
   return normalizeBox({
-    west: fn(box.west),
-    south: fn(box.south),
-    east: fn(box.east),
-    north: fn(box.north),
+    west: edge(box.west),
+    south: edge(box.south),
+    east: edge(box.east),
+    north: edge(box.north),
   });
 }
 

src/layers/recentImagery/source.js

@@ -1,7 +1,11 @@
 import { searchHls } from './catalog.js';
 import { gibsTemplate, wvsSnapshotUrl } from './model.js';
 
-/** NASA-compatible imagery acquisition; transport and URL builders are replaceable. */
+/**
+ * NASA-compatible imagery acquisition; transport and URL builders are replaceable.
+ * Thumbnail responses must expose Data-Present: true for image admission, or
+ * false for confirmed empty coverage, including injected getThumbnail sources.
+ */
 export function createRecentImagerySource({
   fetchImpl = (...args) => globalThis.fetch(...args),
   search = searchHls,

src/layers/recentImagery/thumbnail-presence-proof.test.mjs

@@ -0,0 +1,30 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createThumbnailLoader } from './thumbnails.js';
+test('missing or malformed presence evidence cannot prove thumbnail pixels', async () => {
+  for (const header of [null, 'unknown', '', 'true', 'false']) {
+    let decodes = 0;
+    const loader = createThumbnailLoader({
+      requestThumbnail: async () => ({
+        ok: true,
+        headers: { get: (key) => (key === 'Data-Present' ? header : null) },
+        blob: async () => {
+          decodes++;
+          return new Blob(['fixture']);
+        },
+      }),
+      createObjectUrl: () => 'blob:fixture',
+    });
+    loader.request(
+      { key: 'fixture', product: 'S30', day: '2026-09-18' },
+      { west: 0, east: 1, south: 0, north: 1 },
+    );
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(
+      loader.get('fixture').status,
+      header === 'true' ? 'present' : header === 'false' ? 'empty' : 'error',
+    );
+    assert.equal(decodes, header === 'true' ? 1 : 0);
+    loader.destroy();
+  }
+});

src/layers/recentImagery/thumbnails.js

@@ -100,12 +100,12 @@ export function createThumbnailLoader({
         cancelled = true;
       } else if (response?.ok) {
         const present = String(
-          response.headers?.get?.('Data-Present') ?? 'true',
+          response.headers?.get?.('Data-Present') ?? '',
         ).toLowerCase();
         acquisitionTime = response.headers?.get?.('Acquisition-Time') || null;
         if (present === 'false') {
           status = 'empty';
-        } else {
+        } else if (present === 'true') {
           const blob = await response.blob();
           if (controller.signal.aborted) cancelled = true;
           else {

src/layers/streetLevel/glyphs.js

@@ -65,6 +65,15 @@ export function imageConeGlyph({
   });
 }
 
+/** Street View-style marker: a field-of-view cone from a white-ringed dot. */
+export function viewConeMarkerGlyph({ size = 56, color = '#4285f4' } = {}) {
+  return cachedGlyph(`view-cone:${size}:${color}`, size, (ctx, c) => {
+    wedge(ctx, c, size * 0.48, 0.62, color, 0.38);
+    wedge(ctx, c, size * 0.3, 0.62, color, 0.3);
+    dot(ctx, c, size * 0.13, color, '#ffffff', Math.max(2, size * 0.05));
+  });
+}
+
 /** Marker for the image the viewer currently shows. */
 export function positionMarkerGlyph({ size = 44, color = '#ffb300' } = {}) {
   return cachedGlyph(`pos:${size}:${color}`, size, (ctx, c) => {

src/layers/streetLevel/groundClick.js

@@ -0,0 +1,56 @@
+import * as Cesium from 'cesium';
+import { GROUND_CLICK_MAX_HEIGHT_M } from './policy.js';
+import { cameraHeightAboveGround } from './view.js';
+
+/** Whether the camera is low enough for a click on the ground to mean a street. */
+export function groundClickHeightOk(viewer, groundAt) {
+  if (!viewer?.camera?.positionCartographic) return false;
+  return (
+    cameraHeightAboveGround(viewer, { groundAt }) <= GROUND_CLICK_MAX_HEIGHT_M
+  );
+}
+
+/**
+ * A click on the map itself at street zoom opens the nearest image of the
+ * active `groundClick` providers, without moving the camera. The height is
+ * measured at the click, not read from the cached flag.
+ * @param {{state: object, openNearest: Function, isAvailable: (entry: object) => boolean, groundAt?: Function}} options
+ * @returns {(screenPosition: {x: number, y: number}, picked?: object) => Promise<boolean>|false}
+ */
+export function createGroundClick({
+  state,
+  openNearest,
+  isAvailable,
+  groundAt = null,
+}) {
+  return function openAtGround(screenPosition, picked) {
+    const scenePick = state.services.scenePick;
+    if (!state.enabled || !state.viewer || !scenePick?.pickGroundPosition)
+      return false;
+    if (
+      !scenePick.isSurfacePick(picked) ||
+      !groundClickHeightOk(state.viewer, groundAt)
+    )
+      return false;
+    const providerIds = [...state.providers.values()]
+      .filter(
+        (entry) =>
+          entry.on &&
+          entry.def.groundClick &&
+          entry.status?.configured &&
+          isAvailable(entry),
+      )
+      .map((entry) => entry.def.id);
+    if (!providerIds.length) return false;
+    const position = scenePick.pickGroundPosition(state.viewer, screenPosition);
+    const carto = position && Cesium.Cartographic.fromCartesian(position);
+    if (!carto) return false;
+    return openNearest(
+      {
+        lon: Cesium.Math.toDegrees(carto.longitude),
+        lat: Cesium.Math.toDegrees(carto.latitude),
+      },
+      { providerIds, frame: false },
+    );
+  };
+}

src/layers/streetLevel/groundClick.test.mjs

@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { createGroundClick, groundClickHeightOk } from './groundClick.js';
+import * as scenePick from '../../data/scenePick.js';
+
+const GROUND = Cesium.Cartesian3.fromDegrees(-121.4944, 38.5816, 10);
+const TILESET = { isCesium3DTileset: true };
+
+/**
+ * A layer state with providers `{id, on, groundClick, configured, available}`;
+ * `picked` is where the depth buffer lands, `ellipsoid` the fallback hit.
+ */
+function harness({
+  providers = [
+    { id: 'mapillary', groundClick: false },
+    { id: 'google', groundClick: true },
+  ],
+  height = 400,
+  enabled = true,
+  picked = GROUND,
+  ellipsoid = undefined,
+} = {}) {
+  const opened = [];
+  const state = {
+    enabled,
+    services: { scenePick },
+    providers: new Map(
+      providers.map(
+        ({
+          id,
+          on = true,
+          groundClick,
+          configured = true,
+          available = true,
+        }) => [
+          id,
+          { on, def: { id, groundClick }, status: { configured }, available },
+        ],
+      ),
+    ),
+    viewer: {
+      scene: { pickPositionSupported: true, pickPosition: () => picked },
+      camera: {
+        pickEllipsoid: () => ellipsoid,
+        positionCartographic: Cesium.Cartographic.fromDegrees(
+          -121.4944,
+          38.5816,
+          height,
+        ),
+      },
+    },
+  };
+  const openAtGround = createGroundClick({
+    state,
+    openNearest: (point, options) => {
+      opened.push({ point, options });
+      return Promise.resolve(true);
+    },
+    isAvailable: (entry) => entry.available,
+  });
+  return { opened, openAtGround };
+}
+
+const near = (point) =>
+  Math.abs(point.lon - -121.4944) < 1e-9 &&
+  Math.abs(point.lat - 38.5816) < 1e-9;
+
+test('a click on the map opens the click-to-open providers there, without moving the camera', () => {
+  for (const picked of [undefined, { primitive: TILESET }, { content: {} }]) {
+    const { opened, openAtGround } = harness();
+    openAtGround({ x: 10, y: 20 }, picked);
+    assert.equal(opened.length, 1, JSON.stringify(picked));
+    assert.ok(near(opened[0].point));
+    assert.deepEqual(opened[0].options, {
+      providerIds: ['google'],
+      frame: false,
+    });
+  }
+});
+
+test('where the depth buffer names no place, the ellipsoid answers', () => {
+  const { opened, openAtGround } = harness({
+    picked: new Cesium.Cartesian3(500, 0, 0),
+    ellipsoid: GROUND,
+  });
+  openAtGround({ x: 1, y: 1 });
+  assert.ok(near(opened[0].point));
+});
+
+test('nothing opens over another layer’s object, the sky, from high up, off its map stack, or with the provider off', () => {
+  const cases = [
+    { picked: { id: { id: 'flight:1' } }, label: 'an entity' },
+    { picked: { id: 'cctv:7', primitive: TILESET }, label: 'an id on a tile' },
+    { options: { picked: null, ellipsoid: undefined }, label: 'the sky' },
+    { options: { height: 5000 }, label: 'high up' },
+    {
+      options: {
+        providers: [{ id: 'google', groundClick: true, available: false }],
+      },
+      label: 'not Google 3D',
+    },
+    {
+      options: { providers: [{ id: 'google', groundClick: true, on: false }] },
+      label: 'off',
+    },
+    {
+      options: {
+        providers: [{ id: 'google', groundClick: true, configured: false }],
+      },
+      label: 'no key',
+    },
+    { options: { enabled: false }, label: 'layer off' },
+  ];
+  for (const { picked, options = {}, label } of cases) {
+    const { opened, openAtGround } = harness(options);
+    assert.equal(openAtGround({ x: 1, y: 1 }, picked), false, label);
+    assert.equal(opened.length, 0, label);
+  }
+});
+
+test('street zoom is measured above the ground under the camera', () => {
+  const viewer = (height) => ({
+    camera: {
+      positionCartographic: Cesium.Cartographic.fromDegrees(0, 0, height),
+    },
+    scene: { globe: { getHeight: () => 1500 } },
+  });
+  // 1,500 m up a plateau, 2,000 m above it: still a street.
+  assert.equal(groundClickHeightOk(viewer(3500)), true);
+  assert.equal(groundClickHeightOk(viewer(5000)), false);
+  assert.equal(groundClickHeightOk(null), false);
+});

src/layers/streetLevel/index.js

@@ -1,3 +1,4 @@
+import * as Cesium from 'cesium';
 import { createState } from './state.js';
 import { createMarker } from './marker.js';
 import { createCameraFollow } from './cameraFollow.js';
@@ -5,17 +6,23 @@ import { createCredits } from './credits.js';
 import { createPickRouter } from './pickRouter.js';
 import { createSelection } from './selection.js';
 import { createViewerHost } from './viewerHost.js';
-import { requiresKeyIdFor, validateProviders } from './registry.js';
+import { filtersOf, requiresKeyIdFor, validateProviders } from './registry.js';
 import { normalizeFilter, resolveFilter, sameFilter } from './filter.js';
 import { decodeParams, encodeParams } from './params.js';
-import { composeUIState, summarizeCoverage } from './uiState.js';
+import {
+  composeUIState,
+  keyAlternatives,
+  summarizeCoverage,
+} from './uiState.js';
 import { cameraHeightAboveGround, viewCentre, whenIdle } from './view.js';
+import { createGroundClick, groundClickHeightOk } from './groundClick.js';
 import { createGroundCaster, nextSurfaceMode } from './groundCast.js';
 import { createMeshSampler } from './meshSampler.js';
 
 /** Above this camera height the ground under the camera is not worth fetching. */
 const SURFACE_WARM_BELOW_M = 6000;
 import {
+  AIM_AT_GROUND_MESSAGE,
   FOLLOW_MAP_STACK_ID,
   NEAREST_RADIUS_M,
   POSITION_PICK_ID,
@@ -66,6 +73,12 @@ export function createStreetLevelLayer({
       entry.instance.clearSequence?.();
   };
   parts.selection = createSelection(context);
+  parts.openAtGround = createGroundClick({
+    state,
+    openNearest: (point, options) => layer.openNearest(point, options),
+    isAvailable: (entry) => providerAvailable(entry),
+    groundAt: parts.groundCaster?.groundAt ?? null,
+  });
 
   let notifyQueued = false;
   function notify() {
@@ -95,7 +108,15 @@ export function createStreetLevelLayer({
       getSurface: () => state.surface,
       notify,
       actions: {
-        openImage: (imageId) => openImage(entry.def.id, imageId),
+        /** `{frame: false}` opens it without moving the camera. */
+        openImage: (imageId, options) =>
+          openImage(entry.def.id, imageId, options),
+        /** This provider's image nearest a point the user picked on the map. */
+        openNearest: (point) =>
+          layer.openNearest(point, {
+            providerIds: [entry.def.id],
+            frame: false,
+          }),
         /**
          * Show a provider error, or withdraw it (null). A withdrawal clears
          * only this provider's own error, never a newer one from elsewhere.
@@ -115,11 +136,13 @@ export function createStreetLevelLayer({
     });
   }
 
+  // One source at a time: the first provider that defaults on.
+  const startsOn = definitionsFrozen.find((def) => def.defaultOn !== false);
   for (const def of definitionsFrozen) {
     const entry = {
       def,
       instance: null,
-      on: true,
+      on: def === startsOn,
       status: null,
       /** The error this provider last reported, until it withdraws it. */
       reportedError: null,
@@ -140,6 +163,39 @@ export function createStreetLevelLayer({
     notify();
   }
 
+  /** Usable only on its map stack (Google's terms: Street View on Google 3D only). */
+  function providerAvailable(entry) {
+    const required = entry.def.requiresMapStack;
+    return !required || mapStack?.getActiveId?.() === required;
+  }
+
+  /** Leaving a provider's map stack closes its image, viewer and credit. */
+  function syncProviderAvailability() {
+    const owner = state.providers.get(state.street.providerId);
+    if (state.street.open && owner && !providerAvailable(owner))
+      layer.closeViewer();
+    for (const entry of state.providers.values()) {
+      if (!entry.def.requiresMapStack) continue;
+      if (state.enabled && entry.on && providerAvailable(entry))
+        parts.credits.show(state.viewer, entry.def);
+      else {
+        parts.credits.hide(state.viewer, entry.def);
+        parts.viewerHost.unmount(entry.def.id);
+      }
+    }
+    notify();
+  }
+
+  /** Whether a ground click can open an image: the camera is at street zoom. */
+  function syncGroundClickReady() {
+    const ready =
+      state.enabled &&
+      groundClickHeightOk(state.viewer, parts.groundCaster?.groundAt);
+    if (ready === state.groundClickReady) return;
+    state.groundClickReady = ready;
+    notify();
+  }
+
   /**
    * Camera height above bare earth, for the surface mode. A cold grid cell is
    * fetched once and the mode rechecked when it lands.
@@ -162,6 +218,7 @@ export function createStreetLevelLayer({
 
   /** Cast overlays to bare earth on Google 3D at street zoom; drape them elsewhere. */
   function syncSurface() {
+    syncGroundClickReady();
     const available = Boolean(parts.groundCaster) && state.enabled;
     const photoreal = mapStack?.getActiveId?.() === FOLLOW_MAP_STACK_ID;
     const mode = nextSurfaceMode(state.surface, {
@@ -222,9 +279,13 @@ export function createStreetLevelLayer({
   function activate(entry) {
     if (!state.viewer) return;
     entry.instance.activate(state.viewer);
-    parts.credits.show(state.viewer, entry.def);
     if (!entry.status) refreshStatus(entry);
-    whenIdle(() => parts.viewerHost.prewarm([entry]), 1500);
+    if (!providerAvailable(entry)) return;
+    parts.credits.show(state.viewer, entry.def);
+    // The map may have changed by then.
+    whenIdle(() => {
+      if (providerAvailable(entry)) parts.viewerHost.prewarm([entry]);
+    }, 1500);
   }
 
   function deactivate(entry) {
@@ -241,25 +302,101 @@ export function createStreetLevelLayer({
     nearestLookup = null;
   }
 
-  function openImage(providerId, imageId) {
-    abortNearest();
-    return parts.viewerHost.open(providerId, imageId);
+  /** Ground under the screen centre; null for sky, undefined when it cannot aim. */
+  function screenCentreGround() {
+    const canvas = state.viewer?.scene?.canvas;
+    const pick = state.services.scenePick?.pickGroundPosition;
+    if (!pick || !canvas?.clientWidth || !canvas?.clientHeight)
+      return undefined;
+    const position = pick(state.viewer, {
+      x: canvas.clientWidth / 2,
+      y: canvas.clientHeight / 2,
+    });
+    const carto = position && Cesium.Cartographic.fromCartesian(position);
+    return carto
+      ? {
+          lon: Cesium.Math.toDegrees(carto.longitude),
+          lat: Cesium.Math.toDegrees(carto.latitude),
+        }
+      : null;
   }
 
+  /** `frame: false` keeps the camera where it is (the user picked the spot). */
+  function openImage(providerId, imageId, { frame = true } = {}) {
+    abortNearest();
+    const entry = state.providers.get(providerId);
+    if (entry && !providerAvailable(entry)) {
+      state.street.loading = false;
+      state.street.error = unavailableReason(entry);
+      notify();
+      return Promise.resolve(false);
+    }
+    return parts.viewerHost.open(providerId, imageId, { frame });
+  }
+
+  function unavailableReason(entry) {
+    return `${entry.def.name} needs the Google 3D map: choose it under MAP SOURCE`;
+  }
+
+  /** One imagery source at a time: lighting a provider darkens the others. */
   function setProviderEnabled(providerId, on) {
     const entry = state.providers.get(providerId);
     if (!entry) return false;
+    const before = litIds();
     const next = on !== false;
-    if (entry.on === next) return true;
-    entry.on = next;
-    if (state.enabled) {
-      if (next) activate(entry);
-      else deactivate(entry);
-    }
+    if (next)
+      for (const other of state.providers.values())
+        if (other !== entry && other.on) switchProvider(other, false);
+    switchProvider(entry, next);
+    sourceChanged(before);
     notify();
     return true;
   }
 
+  const litIds = () =>
+    [...state.providers]
+      .filter(([, entry]) => entry.on)
+      .map(([id]) => id)
+      .join();
+
+  /**
+   * After a chip, voice or a link changed the lit source: a lookup still
+   * running and its spinner or error were about the source switched away
+   * (an open photo keeps its own state).
+   */
+  function sourceChanged(before) {
+    if (litIds() === before) return;
+    abortNearest();
+    if (state.street.open) return;
+    state.street.error = null;
+    state.street.loading = false;
+  }
+
+  function switchProvider(entry, on) {
+    if (entry.on === on) return;
+    entry.on = on;
+    if (!state.enabled) return;
+    if (on) activate(entry);
+    else deactivate(entry);
+  }
+
+  /**
+   * The one provider params leave lit: of those they switch on, the one
+   * already on (reapplying never flips), else the first; with none, the lit
+   * one unless they switch it off.
+   */
+  function litByParams(switches) {
+    const asked = [...state.providers.keys()].filter(
+      (id) => switches.get(id) === true,
+    );
+    const current = [...state.providers]
+      .filter(([, entry]) => entry.on)
+      .map(([id]) => id);
+    if (asked.length)
+      return asked.find((id) => current.includes(id)) ?? asked[0];
+    return current.find((id) => switches.get(id) !== false) ?? null;
+  }
+
   function setCoverageFilter(next) {
     const filter = normalizeFilter(next, state.filter);
     if (sameFilter(filter, state.filter)) return;
@@ -270,8 +407,19 @@ export function createStreetLevelLayer({
     notify();
   }
 
+  /** The hint a ground-click provider shows, or the provider's own. */
+  function hintFor(entry, stats) {
+    if (entry.def.groundClick && stats.hint && !state.groundClickReady)
+      return `zoom in to a street to open ${entry.def.name}`;
+    return stats.hint || '';
+  }
+
+  /** Providers usable on this map stack; the others are not shown at all. */
+  const listedEntries = () =>
+    [...state.providers.values()].filter((entry) => providerAvailable(entry));
+
   function providerSnapshots() {
-    return [...state.providers.values()].map((entry) => {
+    return listedEntries().map((entry) => {
       const stats = entry.instance.coverageStats();
       return {
         id: entry.def.id,
@@ -285,9 +433,14 @@ export function createStreetLevelLayer({
         requiresKeyId: entry.def.requiresKeyId || null,
         loading: stats.loading === true,
         count: stats.count || 0,
-        hint: stats.hint || '',
+        hint: hintFor(entry, stats),
         error: stats.error || null,
         color: entry.def.colors.coverage,
+        coverageLabel: entry.def.coverageLabel || null,
+        highlightsSequence: entry.def.highlightsSequence !== false,
+        sinceBasis: entry.def.sinceBasis === 'upload' ? 'upload' : 'capture',
+        groundClick: entry.def.groundClick === true,
+        filters: [...filtersOf(entry.def)],
       };
     });
   }
@@ -313,24 +466,43 @@ export function createStreetLevelLayer({
 
   function getUIState() {
     const { host, ...street } = state.street;
-    return composeUIState({
+    const ui = composeUIState({
       enabled: state.enabled,
+      groundClickReady: state.groundClickReady,
       filter: state.filter,
       providers: providerSnapshots(),
       street,
       sequence: sequenceSnapshot(),
       surface: state.surface,
     });
+    // The lit source cannot run on this map: say so, not a blank panel.
+    const stranded = [...state.providers.values()].find(
+      (entry) => entry.on && !providerAvailable(entry),
+    );
+    if (stranded && !ui.providers.some((p) => p.on))
+      ui.coverage.hint = unavailableReason(stranded);
+    return ui;
   }
 
   const layer = {
     id: STREET_LEVEL_LAYER_ID,
     name: 'Street Level',
     icon: '📷',
-    source: definitionsFrozen.map((def) => def.name).join(' · '),
+    /** The sources usable on this map (Street View only on Google 3D). */
+    get source() {
+      return listedEntries()
+        .map((entry) => entry.def.name)
+        .join(' · ');
+    },
     updateInterval: 0,
     statsRefreshInterval: 1000,
-    requiresKeyId: requiresKeyIdFor(definitionsFrozen),
+    /** The key the switched-on providers share (or null), for the layer row. */
+    get requiresKeyId() {
+      const on = [...state.providers.values()].filter((entry) => entry.on);
+      return requiresKeyIdFor(
+        on.length ? on.map((entry) => entry.def) : definitionsFrozen,
+      );
+    },
     /** Registered providers, in chip order. */
     providerIds: definitionsFrozen.map((def) => def.id),
     getSourceAvailability() {
@@ -404,16 +576,19 @@ export function createStreetLevelLayer({
 
     getStats() {
       // The lifecycle polls this every second: summarise, don't snapshot.
-      const coverage = summarizeCoverage(providerSnapshots());
+      const snapshots = providerSnapshots();
+      const coverage = summarizeCoverage(snapshots);
       let loadingLabel = '';
       const keyLabel = coverage.keyRejected ? 'KEY REJECTED' : 'KEY REQUIRED';
       if (coverage.keyRequired) loadingLabel = keyLabel;
       else if (coverage.loading) loadingLabel = 'loading coverage...';
       else if (coverage.hint && state.enabled) loadingLabel = coverage.hint;
       return {
+        source: layer.source,
         count: coverage.count,
         loading: coverage.loading,
         keyRequired: coverage.keyRequired,
+        keyAlternatives: keyAlternatives(snapshots),
         error: coverage.keyRequired
           ? coverage.keyRejected
             ? coverage.error || keyLabel
@@ -441,9 +616,11 @@ export function createStreetLevelLayer({
       unsubscribeMapStack =
         mapStack?.subscribe?.(() => {
           syncFollowAvailability();
+          syncProviderAvailability();
           syncSurface();
         }) || null;
       syncFollowAvailability();
+      syncProviderAvailability();
       syncSurface();
     },
 
@@ -460,7 +637,13 @@ export function createStreetLevelLayer({
         providerIds: state.providers.keys(),
         filter: state.filter,
       });
-      for (const [id, on] of decoded.providers) setProviderEnabled(id, on);
+      const lit = litByParams(decoded.providers);
+      const before = litIds();
+      for (const [id, entry] of state.providers)
+        if (id !== lit) switchProvider(entry, false);
+      if (lit) switchProvider(state.providers.get(lit), true);
+      sourceChanged(before);
+      notify();
       setCoverageFilter(decoded.filter);
       return true;
     },
@@ -476,15 +659,39 @@ export function createStreetLevelLayer({
     attachViewerHost(element) {
       parts.viewerHost.attach(element);
       if (element && state.enabled)
-        whenIdle(() => parts.viewerHost.prewarm(activeEntries()), 1500);
+        whenIdle(
+          () =>
+            parts.viewerHost.prewarm(
+              activeEntries().filter((entry) => providerAvailable(entry)),
+            ),
+          1500,
+        );
     },
     setProviderEnabled,
     /** Imagery filter for coverage, cones and nearest-image lookups. */
     setCoverageFilter,
     openImage,
-    /** Open the nearest image any active provider has around a point. */
-    async openNearest(point) {
-      const view = point || viewCentre(state.viewer);
+    /**
+     * Open the nearest image of the active providers (or `providerIds`) near
+     * a point, else the view centre, or with `aim: 'screen-centre'` the ground
+     * under the screen centre (sky: nothing).
+     */
+    async openNearest(
+      point,
+      { providerIds = null, frame = true, aim = 'view' } = {},
+    ) {
+      let view = point;
+      if (!view && aim === 'screen-centre') {
+        view = screenCentreGround();
+        if (view === null) {
+          abortNearest();
+          state.street.loading = false;
+          state.street.error = AIM_AT_GROUND_MESSAGE;
+          notify();
+          return false;
+        }
+      }
+      view ||= viewCentre(state.viewer);
       if (!Number.isFinite(view?.lat) || !Number.isFinite(view?.lon))
         return false;
       abortNearest();
@@ -495,7 +702,11 @@ export function createStreetLevelLayer({
       state.street.error = null;
       notify();
       let lastError = null;
-      for (const entry of activeEntries()) {
+      const asked = (entry) =>
+        (!providerIds || providerIds.includes(entry.def.id)) &&
+        providerAvailable(entry);
+      const entries = activeEntries().filter(asked);
+      for (const entry of entries) {
         let imageId = null;
         try {
           imageId = await entry.instance.nearestImage(
@@ -511,17 +722,20 @@ export function createStreetLevelLayer({
         }
         if (signal.aborted) return false;
         if (!state.enabled) break;
-        // This provider was switched off while it looked: try the next.
-        if (!imageId || !entry.on) continue;
+        // Switched off, or its map left, while it looked: try the next.
+        if (!imageId || !entry.on || !providerAvailable(entry)) continue;
         nearestLookup = null;
-        return openImage(entry.def.id, imageId);
+        return openImage(entry.def.id, imageId, { frame });
       }
       if (nearestLookup === lookup) nearestLookup = null;
       // Switched off while it looked: nothing to open, nothing to report.
-      if (state.enabled && activeEntries().length)
+      const stillOn = entries.some(
+        (entry) => entry.on && providerAvailable(entry),
+      );
+      if (state.enabled && stillOn)
         state.street.error =
           lastError?.message ||
-          `No street-level imagery within ${NEAREST_RADIUS_M} m of the view centre`;
+          `No street-level imagery within ${NEAREST_RADIUS_M} m of ${point ? 'that point' : 'the view centre'}`;
       state.street.loading = false;
       notify();
       return false;

src/layers/streetLevel/index.test.mjs

@@ -4,6 +4,7 @@ import * as Cesium from 'cesium';
 import { createStreetLevelLayer } from './index.js';
 import { MAPILLARY_CREDIT_HTML } from './providers/mapillary/policy.js';
 import { createMapillaryProvider } from './providers/mapillary/index.js';
+import { createKartaViewProvider } from './providers/kartaview/index.js';
 import { fakeStreetLevelProvider as fakeProvider } from '../../testSupport/streetLevelFakes.mjs';
 
 /**
@@ -92,8 +93,8 @@ function deferred() {
 }
 
 /** A provider whose viewer reports a pose for every image it opens. */
-function posingProvider() {
-  const provider = fakeProvider();
+function posingProvider(options) {
+  const provider = fakeProvider(options);
   const create = provider.create;
   provider.create = (context) => {
     const instance = create(context);
@@ -483,6 +484,328 @@ test('switching a provider on while the layer is off activates nothing (M01)', a
   assert.equal(viewer.credits.length, 1);
 });
 
+/** The real Google provider over the Street View fakes, beside a Mapillary stand-in. */
+async function withStreetView(
+  t,
+  { mapStack = 'photoreal', nearest, mapillaryKeyless = false } = {},
+) {
+  const { createGoogleProvider } = await import('./providers/google/index.js');
+  const { fakeHost, fakeMapsLoader, fakeStreetViewLibrary } =
+    await import('../../testSupport/googleStreetViewFakes.mjs');
+  const fake = fakeStreetViewLibrary({
+    panoramas: {
+      'pano-a': { lat: 38.5816, lng: -121.4944, imageDate: '2024-05' },
+    },
+    nearest: nearest ?? (() => 'pano-a'),
+  });
+  const mapillaryLookups = [];
+  const mapillary = fakeProvider({
+    nearestImage: async (point) => {
+      mapillaryLookups.push(point);
+      return null;
+    },
+  });
+  mapillary.requiresKeyId = 'mapillary';
+  if (mapillaryKeyless) {
+    mapillary.stats.keyRequired = true;
+    const create = mapillary.create;
+    mapillary.create = (context) => ({
+      ...create(context),
+      status: async () => ({ configured: false }),
+    });
+  }
+  const loader = fakeMapsLoader(fake.library);
+  const google = createGoogleProvider({
+    getApiKey: () => 'browser-key',
+    loader,
+  });
+  const { layer, viewer } = await enabledLayer(t, [mapillary, google]);
+  const stack = fakeMapStack(mapStack);
+  layer.attachMapStackController(stack);
+  layer.attachViewerHost(fakeHost());
+  return { layer, viewer, stack, fake, loader, mapillaryLookups };
+}
+
+test('Street View starts off, and the layer row names the key of the providers that are on', async (t) => {
+  const { layer } = await withStreetView(t);
+  const google = () =>
+    layer.getUIState().providers.find((p) => p.id === 'google');
+  assert.equal(google().on, false);
+  assert.equal(layer.requiresKeyId, 'mapillary');
+  layer.setProviderEnabled('google', true);
+  assert.equal(layer.requiresKeyId, 'google-maps', 'Street View alone');
+});
+
+test('the layer starts with one source lit: the first that defaults on', async (t) => {
+  const { layer } = await enabledLayer(t, [
+    fakeProvider(),
+    fakeProvider({ id: 'panoramax', pickPrefix: 'pmx:' }),
+  ]);
+  assert.deepEqual(
+    layer
+      .getUIState()
+      .providers.filter((p) => p.on)
+      .map((p) => p.id),
+    ['mapillary'],
+  );
+});
+
+test('leaving Google 3D during a Street View lookup ends it without an error or a stuck spinner', async (t) => {
+  const { layer, stack, fake } = await withStreetView(t);
+  layer.setProviderEnabled('google', true);
+  let answer;
+  fake.library.StreetViewService.prototype.getPanorama = () =>
+    new Promise((resolve) => {
+      answer = resolve;
+    });
+  const opening = layer.openNearest({ lat: 38.5816, lon: -121.4944 });
+  await settle();
+  assert.equal(layer.getUIState().street.loading, true);
+  stack.switchTo('bing');
+  answer({ data: { location: { pano: 'pano-a' }, imageDate: '2024-05' } });
+  assert.equal(await opening, false);
+  const { street } = layer.getUIState();
+  assert.equal(street.loading, false, 'OPEN STREET VIEW is usable again');
+  assert.equal(street.error, null);
+  assert.equal(street.open, false);
+});
+
+test('a source swap during a lookup reports no false "no imagery"', async (t) => {
+  let answer;
+  const mapillary = fakeProvider({
+    nearestImage: () =>
+      new Promise((resolve) => {
+        answer = resolve;
+      }),
+  });
+  const other = fakeProvider({ id: 'panoramax', pickPrefix: 'pmx:' });
+  const { layer } = await enabledLayer(t, [mapillary, other]);
+  const opening = layer.openNearest({ lat: 1, lon: 2 });
+  layer.setProviderEnabled('panoramax', true);
+  answer('img-1');
+  assert.equal(await opening, false);
+  assert.equal(layer.getUIState().street.error, null);
+  assert.equal(layer.getUIState().street.loading, false);
+});
+
+test('Street View lit off Google 3D says why the panel is empty', async (t) => {
+  const { layer, stack } = await withStreetView(t);
+  layer.setProviderEnabled('google', true);
+  stack.switchTo('esri-imagery');
+  assert.match(
+    layer.getUIState().coverage.hint,
+    /Google Street View needs the Google 3D map/,
+  );
+  layer.setProviderEnabled('mapillary', true);
+  assert.doesNotMatch(layer.getUIState().coverage.hint, /Google 3D/);
+});
+
+test('one imagery source at a time: lighting one darkens the other, either way', async (t) => {
+  const { layer } = await withStreetView(t);
+  const lit = () =>
+    layer
+      .getUIState()
+      .providers.filter((p) => p.on)
+      .map((p) => p.id);
+  assert.deepEqual(lit(), ['mapillary'], 'Mapillary by default: it is free');
+  layer.setProviderEnabled('google', true);
+  assert.deepEqual(lit(), ['google']);
+  assert.equal(layer.getParams().mapillary, false);
+  layer.setProviderEnabled('mapillary', true);
+  assert.deepEqual(lit(), ['mapillary']);
+  assert.equal(layer.getParams().google, false);
+  // Params that light one switch to it; reapplying them changes nothing.
+  layer.setParams({ google: true });
+  assert.deepEqual(lit(), ['google']);
+  layer.setParams({ google: true });
+  assert.deepEqual(lit(), ['google']);
+  // Params lighting both keep the one already on, however often applied.
+  for (let i = 0; i < 2; i++) {
+    layer.setParams({ mapillary: true, providerSwitches: 'google-1' });
+    assert.deepEqual(lit(), ['google']);
+  }
+  layer.setParams({ mapillary: true, google: false });
+  assert.deepEqual(lit(), ['mapillary']);
+  // Filter-only params leave the source alone.
+  layer.setParams({ pano: 'pano' });
+  assert.deepEqual(lit(), ['mapillary']);
+  // Darkening the only lit one leaves none: the panel turns the layer off.
+  layer.setProviderEnabled('mapillary', false);
+  assert.deepEqual(lit(), []);
+});
+
+test('Street View appears only on the Google 3D map: chip, legend, credit, source and images', async (t) => {
+  const { layer, viewer, stack } = await withStreetView(t, {
+    mapStack: 'esri-imagery',
+  });
+  layer.setProviderEnabled('google', true);
+  await settle();
+  const ui = () => layer.getUIState();
+  const listed = () => ui().providers.map((p) => p.id);
+  const credited = () =>
+    viewer.credits.some((credit) => /Street View imagery/.test(credit.html));
+  assert.deepEqual(listed(), ['mapillary'], 'no Street View chip');
+  assert.ok(!ui().legend.some((item) => item.key === 'google'));
+  assert.equal(credited(), false, 'no Google credit on another map');
+  assert.equal(layer.source, 'Mapillary');
+  assert.equal(layer.getStats().source, 'Mapillary');
+  assert.equal(await layer.openImage('google', 'pano-a'), false);
+  assert.match(ui().street.error, /needs the Google 3D map/);
+  assert.equal(layer.getParams().google, true, 'the choice is kept');
+
+  stack.switchTo('photoreal');
+  assert.deepEqual(listed(), ['mapillary', 'google']);
+  assert.equal(credited(), true);
+  assert.equal(layer.source, 'Mapillary · Google Street View');
+  assert.equal(await layer.openImage('google', 'pano-a'), true);
+  assert.equal(ui().street.providerId, 'google');
+
+  stack.switchTo('bing');
+  await settle();
+  assert.equal(ui().street.open, false, 'closed with the map');
+  assert.equal(credited(), false);
+  assert.deepEqual(listed(), ['mapillary']);
+});
+
+test('the UI state says when a click (or the button) can open Street View here', async (t) => {
+  const { layer } = await withStreetView(t);
+  assert.equal(typeof layer.getUIState().groundClickReady, 'boolean');
+});
+
+test('a lookup for the click-to-open providers asks only them and reports "that point"', async (t) => {
+  const { layer, mapillaryLookups } = await withStreetView(t, {
+    nearest: () => null,
+  });
+  layer.setProviderEnabled('google', true);
+  await settle();
+  const opened = await layer.openNearest(
+    { lat: 38.58, lon: -121.49 },
+    { providerIds: ['google'], frame: false },
+  );
+  assert.equal(opened, false);
+  assert.deepEqual(mapillaryLookups, [], 'Mapillary was not asked');
+  assert.equal(
+    layer.getUIState().street.error,
+    'No street-level imagery within 50 m of that point',
+  );
+});
+
+test('an image opened from a ground click leaves the camera where it is', async (t) => {
+  const { layer, viewer } = await withStreetView(t);
+  layer.setProviderEnabled('google', true);
+  await settle();
+  await layer.openNearest(
+    { lat: 38.58, lon: -121.49 },
+    { providerIds: ['google'], frame: false },
+  );
+  assert.equal(layer.getUIState().street.imageId, 'pano-a');
+  assert.equal(viewer.flights.started, 0, 'no framing flight');
+});
+
+test('off Google 3D not even Google\u2019s script is loaded for Street View', async (t) => {
+  const { layer, loader } = await withStreetView(t, {
+    mapStack: 'esri-imagery',
+  });
+  layer.setProviderEnabled('google', true);
+  layer.attachViewerHost({ ownerDocument: { createElement: () => ({}) } });
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  assert.deepEqual(loader.imports, [], 'no prewarm, no lookup');
+});
+
+test('the button’s “centre of the view” is the ground under the middle of the screen', async (t) => {
+  const { createStreetLevelLayer: create } = await import('./index.js');
+  const scenePick = await import('../../data/scenePick.js');
+  const lookups = [];
+  const provider = fakeProvider({
+    nearestImage: async (point) => {
+      lookups.push(point);
+      return null;
+    },
+  });
+  const saved = globalThis.document;
+  const drawing = new Proxy({}, { get: () => () => ({ addColorStop() {} }) });
+  globalThis.document = Object.assign(new EventTarget(), {
+    createElement: () => ({ getContext: () => drawing }),
+  });
+  const viewer = fakeViewer();
+  const centre = Cesium.Cartesian3.fromDegrees(-121.4937, 38.5799, 0);
+  Object.assign(viewer.scene, {
+    pickPositionSupported: true,
+    pickPosition: (at) => (at.x === 500 && at.y === 300 ? centre : undefined),
+  });
+  viewer.scene.canvas.clientWidth = 1000;
+  viewer.scene.canvas.clientHeight = 600;
+  const layer = create({ providers: [provider], services: { scenePick } });
+  layer.init(viewer);
+  layer.enable(viewer);
+  t.after(() => {
+    layer.destroy();
+    globalThis.document = saved;
+  });
+  await layer.openNearest(undefined, { aim: 'screen-centre' });
+  assert.equal(lookups.length, 1);
+  assert.ok(Math.abs(lookups[0].lat - 38.5799) < 1e-9);
+  assert.ok(Math.abs(lookups[0].lon - -121.4937) < 1e-9);
+});
+
+test('the button aimed at the sky opens nothing, and says to aim at a street', async (t) => {
+  const { createStreetLevelLayer: create } = await import('./index.js');
+  const scenePick = await import('../../data/scenePick.js');
+  const lookups = [];
+  const provider = fakeProvider({
+    nearestImage: async (point) => {
+      lookups.push(point);
+      return null;
+    },
+  });
+  const saved = globalThis.document;
+  const drawing = new Proxy({}, { get: () => () => ({ addColorStop() {} }) });
+  globalThis.document = Object.assign(new EventTarget(), {
+    createElement: () => ({ getContext: () => drawing }),
+  });
+  const viewer = fakeViewer();
+  // Every ground pick misses: the middle of the screen is sky.
+  Object.assign(viewer.scene, {
+    pickPositionSupported: true,
+    pickPosition: () => undefined,
+  });
+  viewer.camera.pickEllipsoid = () => undefined;
+  viewer.scene.canvas.clientWidth = 1000;
+  viewer.scene.canvas.clientHeight = 600;
+  const layer = create({ providers: [provider], services: { scenePick } });
+  layer.init(viewer);
+  layer.enable(viewer);
+  t.after(() => {
+    layer.destroy();
+    globalThis.document = saved;
+  });
+  assert.equal(
+    await layer.openNearest(undefined, { aim: 'screen-centre' }),
+    false,
+  );
+  assert.deepEqual(lookups, [], 'no lookup at the view centre instead');
+  const { street } = layer.getUIState();
+  assert.match(street.error, /Aim the middle of the view at a street/);
+  assert.equal(street.loading, false);
+});
+
+test('with no Mapillary token, the layer points at Street View, on Google 3D only', async (t) => {
+  const { layer, stack } = await withStreetView(t, { mapillaryKeyless: true });
+  await settle();
+  const stats = layer.getStats();
+  assert.equal(stats.keyRequired, true);
+  assert.deepEqual(stats.keyAlternatives, [
+    { id: 'google', label: 'GOOGLE STREET VIEW', requiresKeyId: 'google-maps' },
+  ]);
+  assert.deepEqual(layer.getUIState().keyAlternatives, stats.keyAlternatives);
+  stack.switchTo('esri-imagery');
+  assert.deepEqual(layer.getStats().keyAlternatives, [], 'not off Google 3D');
+  // Lit, Street View draws: the layer is no longer key-gated.
+  stack.switchTo('photoreal');
+  layer.setProviderEnabled('google', true);
+  assert.equal(layer.getStats().keyRequired, false);
+});
+
 test('an empty provider composition enables and tears down without acquiring imagery', async (t) => {
   const { layer, viewer } = await enabledLayer(t, []);
   assert.deepEqual(layer.providerIds, []);
@@ -496,3 +819,127 @@ test('an empty provider composition enables and tears down without acquiring ima
   layer.enable(viewer);
   assert.deepEqual(layer.getUIState().providers, []);
 });
+
+test('a failed lookup’s error goes when another source is lit; a provider can open an image without framing', async (t) => {
+  const failing = fakeProvider({
+    nearestImage: async () => {
+      throw new Error('KartaView did not answer in time — try again');
+    },
+  });
+  const other = fakeProvider({ id: 'other', pickPrefix: 'oth:' });
+  const { layer, viewer } = await enabledLayer(t, [failing, other]);
+  layer.attachViewerHost({});
+  await layer.openNearest({ lat: 1, lon: 1 });
+  assert.match(layer.getUIState().street.error, /did not answer/);
+  layer.setProviderEnabled('other', true);
+  await settle();
+  assert.equal(layer.getUIState().street.error, null);
+  // A provider's own open (KartaView's ‹ ›) can leave the camera alone.
+  await other.context().actions.openImage('img-1', { frame: false });
+  assert.deepEqual(other.calls.open, ['img-1']);
+  assert.equal(viewer.flights.started, 0);
+});
+
+test('a provider’s own open can leave the camera where it is; a default open frames', async (t) => {
+  const provider = posingProvider();
+  const { layer, viewer } = await enabledLayer(t, [provider]);
+  layer.attachViewerHost({});
+  await provider.context().actions.openImage('img-1', { frame: false });
+  assert.deepEqual(provider.calls.open, ['img-1']);
+  assert.equal(viewer.flights.started, 0, 'frame: false keeps the camera');
+  await provider.context().actions.openImage('img-2');
+  assert.equal(viewer.flights.started, 1, 'a default open frames the image');
+});
+
+test('a provider’s openNearest (a line click) asks only that provider and leaves the camera', async (t) => {
+  const lit = posingProvider({ nearestImage: async () => 'lit-near' });
+  const other = fakeProvider({
+    id: 'other',
+    pickPrefix: 'oth:',
+    nearestImage: async () => 'other-near',
+  });
+  const { layer, viewer } = await enabledLayer(t, [lit, other]);
+  layer.attachViewerHost({});
+  const point = { lat: 38.58, lon: -121.49 };
+  // The other source is off: its click asks nobody else.
+  await other.context().actions.openNearest(point);
+  await settle();
+  assert.deepEqual(lit.calls.open, [], 'the lit source was not asked');
+  assert.deepEqual(other.calls.open, []);
+  await lit.context().actions.openNearest(point);
+  assert.deepEqual(lit.calls.open, ['lit-near']);
+  assert.equal(viewer.flights.started, 0, 'the user picked the spot');
+});
+
+test('KartaView through the core: its own swatch without Selected, its lines counted as streets', async (t) => {
+  const kartaView = createKartaViewProvider({
+    source: {
+      getTile: async () => ({ lines: [] }),
+      nearestPhotos: async () => [],
+      getPhoto: async () => {
+        throw new Error('KartaView has no such photo');
+      },
+      getSequencePhotos: async () => ({ photos: [], hasMore: false }),
+      probeImage: async () => true,
+    },
+  });
+  const { layer } = await enabledLayer(t, [kartaView]);
+  layer.setProviderEnabled('kartaview', true);
+  await settle();
+  const ui = layer.getUIState();
+  assert.deepEqual(
+    ui.legend.map((entry) => entry.key),
+    ['kartaview'],
+  );
+  assert.equal(ui.coverage.label?.noun, 'streets');
+  assert.equal(
+    ui.providers.find((p) => p.id === 'kartaview').highlightsSequence,
+    false,
+  );
+});
+
+test('switching source by params (the chip path) stops a running lookup and clears its spinner and error', async (t) => {
+  const slow = slowLookups();
+  const looking = fakeProvider({ nearestImage: slow.nearestImage });
+  const other = fakeProvider({ id: 'other', pickPrefix: 'oth:' });
+  const { layer } = await enabledLayer(t, [looking, other]);
+  layer.attachViewerHost({});
+  const opening = layer.openNearest({ lat: 1, lon: 1 });
+  await settle();
+  assert.equal(layer.getUIState().street.loading, true);
+  layer.setParams({ mapillary: false, other: true });
+  assert.equal(slow.lookups[0].signal.aborted, true, 'the lookup is stopped');
+  assert.equal(
+    layer.getUIState().street.loading,
+    false,
+    'no spinner left behind',
+  );
+  // The stopped lookup answers late: nothing opens, nothing is reported.
+  slow.lookups[0].answer.resolve('img1');
+  assert.equal(await opening, false);
+  assert.deepEqual(looking.calls.open, []);
+  assert.equal(layer.getUIState().street.error, null);
+});
+
+test('switching source by params clears a failed lookup’s error; reapplying the same switches does not', async (t) => {
+  const failing = fakeProvider({
+    nearestImage: async () => {
+      throw new Error('KartaView did not answer in time — try again');
+    },
+  });
+  const { layer: second } = await enabledLayer(t, [
+    failing,
+    fakeProvider({ id: 'other', pickPrefix: 'oth:' }),
+  ]);
+  second.attachViewerHost({});
+  await second.openNearest({ lat: 1, lon: 1 });
+  assert.match(second.getUIState().street.error, /did not answer/);
+  second.setParams({ mapillary: false, other: true });
+  assert.equal(second.getUIState().street.error, null);
+  // Reapplying the same switches (a restore) leaves state alone.
+  await second.openNearest({ lat: 1, lon: 1 });
+  const kept = second.getUIState().street.error;
+  assert.match(kept, /No street-level imagery/);
+  second.setParams({ mapillary: false, other: true });
+  assert.equal(second.getUIState().street.error, kept);
+});

src/layers/streetLevel/lineCoverage.js

@@ -0,0 +1,936 @@
+import * as Cesium from 'cesium';
+import { passesImageryFilter } from './filter.js';
+import {
+  createHorizonCull,
+  groundUnderCamera,
+  metresBetween,
+  viewFocus,
+  visibleBbox,
+  whenIdle,
+} from './view.js';
+import { densifyLine, MESH_DENSIFY_DEG } from './groundCast.js';
+import { MESH_SAMPLE_RADIUS_M } from './meshSampler.js';
+import { tileBounds, tilesForBbox } from './tileMath.js';
+
+/** Draped lines stay at most this long while a tile's cast lines build. */
+export const SWAP_MAX_WAIT_MS = 4000;
+/** Tiles touched by new mesh samples are redrawn at most this often. */
+const REMESH_INTERVAL_MS = 1500;
+/** Gap between redrawing one dirty tile and the next. */
+const REMESH_STAGGER_MS = 120;
+/** Old-zoom tiles are kept at most this long after a zoom change. */
+const STALE_TILE_MAX_MS = 6000;
+/** Sequences per primitive: smaller batches build, and show, sooner. */
+const SEQUENCE_PRIMITIVE_BATCH = 120;
+
+/** Separates a multi-part sequence's part index from its id in pick ids. */
+const PART_SEPARATOR = '~';
+
+/** Pick ids for every part of a sequence; the first part is unsuffixed. */
+function partIds(sequence, prefix) {
+  return sequence.parts.map((_, index) =>
+    index
+      ? `${prefix}${sequence.id}${PART_SEPARATOR}${index}`
+      : `${prefix}${sequence.id}`,
+  );
+}
+
+/** Sequence id for any part's pick id (`<prefix><id>[~<part>]`), else null. */
+export function sequenceIdFromPick(pickId, prefix) {
+  if (typeof pickId !== 'string' || !prefix || !pickId.startsWith(prefix))
+    return null;
+  const rest = pickId.slice(prefix.length);
+  const cut = rest.indexOf(PART_SEPARATOR);
+  return cut === -1 ? rest : rest.slice(0, cut);
+}
+
+/**
+ * Whether any point of `box` ({west, south, east, north}) is within the mesh
+ * sampler's range of `centre`, the ground point under the camera.
+ */
+export function meshBoxInRange(box, centre) {
+  // Move the camera's longitude to the box's side of the date line first:
+  // clamping 179.999 into a box at -179.99 would pick its far edge.
+  const lon =
+    centre.lon +
+    360 * Math.round(((box.west + box.east) / 2 - centre.lon) / 360);
+  const nearest = {
+    lon: Math.min(box.east, Math.max(box.west, lon)),
+    lat: Math.min(box.north, Math.max(box.south, centre.lat)),
+  };
+  return metresBetween(centre, nearest) <= MESH_SAMPLE_RADIUS_M;
+}
+
+/**
+ * @typedef {object} LineCoverageTuning
+ * @property {number} maxTiles            Line tiles drawn at once.
+ * @property {number} overviewMaxTiles    Overview tiles drawn at once.
+ * @property {number} maxSequences        Lines drawn at once, over every tile.
+ * @property {number} lineWidthPx
+ * @property {number} overviewPointPx
+ * @property {number} moveDebounceMs      Camera rest before the tile set is recomputed.
+ * @property {number} viewRangeMinM       Street-zoom coverage reaches at least this far…
+ * @property {number} viewRangePerHeight  …or camera height times this.
+ * @property {number} viewNearM           Ground always covered around a tilted camera.
+ */
+
+/**
+ * Camera-driven coverage from any XYZ line-tile source: overview points from
+ * orbit, sequence lines near the ground. In terrain surface mode a tile is
+ * drawn draped first, then swapped for lines cast to the bare earth (draped
+ * lines would land on roofs), so coverage never waits on terrain heights.
+ *
+ * @param {object} options
+ * @param {object} options.state  Provider state: `context`, `services`, `viewer`, `coverage`, `sequence`, key flags.
+ * @param {(tile: {x: number, y: number, z: number}, init: {signal: AbortSignal}) => Promise<{sequences: Array<object>, overview: Array<object>}>} options.fetchTile
+ *   A decoded tile. Sequences are `{id, parts, capturedAt, isPano}`; overview
+ *   points `{lon, lat, capturedAt, isPano}`. A rejection may carry
+ *   `keyRequired`, `keyRejected` or `retryAfterSec`.
+ * @param {(heightM: number|null) => {zoom: number, kind: 'sequence'|'overview'}|null} options.zoomFor
+ *   Tile zoom for a camera height above ground; null draws nothing.
+ * @param {{coverage: string, selected: string}} options.colors
+ * @param {string} options.pickPrefix   Pick-id prefix of the lines.
+ * @param {string} options.renderKey    Render-governor reason.
+ * @param {LineCoverageTuning} options.tuning
+ * @param {{keyRejected?: string, rateLimited: string, tooHigh?: string}} options.messages
+ * @param {(sequence: object, filter: object) => boolean} [options.passes]  Whether the imagery filter keeps a line or point.
+ */
+export function createLineCoverage({
+  state,
+  fetchTile,
+  zoomFor,
+  colors,
+  pickPrefix,
+  renderKey,
+  tuning,
+  messages,
+  passes = passesImageryFilter,
+}) {
+  const { render } = state.services;
+  const perTileSequenceCap = Math.floor(tuning.maxSequences / tuning.maxTiles);
+
+  /** Colour for a line: the provider's, GEV cyan while selected. */
+  function sequenceColor({ selected = false } = {}) {
+    return selected
+      ? Cesium.Color.fromCssColorString(colors.selected)
+      : Cesium.Color.fromCssColorString(colors.coverage).withAlpha(0.92);
+  }
+
+  function requestRender() {
+    render?.governorRequestRender?.(renderKey);
+  }
+
+  function ensureTerrainReady() {
+    return (state.coverage.terrainReady ||=
+      Cesium.GroundPolylinePrimitive.initializeTerrainHeights());
+  }
+
+  function tileKey({ x, y, z }) {
+    return `${z}/${x}/${y}`;
+  }
+
+  /** The imagery filter, resolved now: "since N days" moves with the clock. */
+  function filter() {
+    return state.context.getFilter();
+  }
+
+  function terrainMode() {
+    return (
+      state.context.getSurface?.() === 'terrain' &&
+      Boolean(state.context.groundCaster)
+    );
+  }
+
+  /**
+   * A tile's sequences, filtered then capped: capping first could leave a
+   * dense tile of newer flat captures with no 360° lines at all.
+   */
+  function drawnSequences(entry) {
+    const drawn = [];
+    const current = filter();
+    for (const sequence of entry.sequenceList) {
+      if (drawn.length >= perTileSequenceCap) break;
+      if (passes(sequence, current)) drawn.push(sequence);
+    }
+    return drawn;
+  }
+
+  /**
+   * Batched primitives for a tile's sequence parts: cast polylines where
+   * terrain heights are cached, draped ground lines otherwise. Each batch
+   * records the selection its colours were built with.
+   */
+  function buildSequencePrimitives(sequences) {
+    const ground = terrainMode() ? state.context.groundCaster : null;
+    const meshAt = ground ? state.context.meshSampler?.meshAt : undefined;
+    const selectedId = state.sequence.selectedId ?? null;
+    const draped = [];
+    const cast = [];
+    for (const sequence of sequences) {
+      const color = Cesium.ColorGeometryInstanceAttribute.fromColor(
+        sequenceColor({ selected: sequence.id === selectedId }),
+      );
+      const ids = partIds(sequence, pickPrefix);
+      sequence.parts.forEach((coordinates, index) => {
+        const flat = ground?.castLine(coordinates, { meshAt });
+        let positions;
+        try {
+          positions = flat
+            ? Cesium.Cartesian3.fromDegreesArrayHeights(flat)
+            : Cesium.Cartesian3.fromDegreesArray(coordinates.flat());
+        } catch {
+          return;
+        }
+        if (positions.length < 2) return;
+        const geometry = flat
+          ? new Cesium.PolylineGeometry({
+              positions,
+              width: tuning.lineWidthPx,
+              vertexFormat: Cesium.PolylineColorAppearance.VERTEX_FORMAT,
+              arcType: Cesium.ArcType.NONE,
+            })
+          : new Cesium.GroundPolylineGeometry({
+              positions,
+              width: tuning.lineWidthPx,
+            });
+        (flat ? cast : draped).push(
+          new Cesium.GeometryInstance({
+            geometry,
+            id: ids[index],
+            attributes: { color },
+          }),
+        );
+      });
+    }
+    const primitives = [];
+    for (let i = 0; i < draped.length; i += SEQUENCE_PRIMITIVE_BATCH)
+      primitives.push({
+        onGround: true,
+        selectedId,
+        primitive: new Cesium.GroundPolylinePrimitive({
+          geometryInstances: draped.slice(i, i + SEQUENCE_PRIMITIVE_BATCH),
+          appearance: new Cesium.PolylineColorAppearance(),
+          classificationType: Cesium.ClassificationType.BOTH,
+          asynchronous: true,
+          allowPicking: true,
+        }),
+      });
+    for (let i = 0; i < cast.length; i += SEQUENCE_PRIMITIVE_BATCH)
+      primitives.push({
+        onGround: false,
+        selectedId,
+        primitive: new Cesium.Primitive({
+          geometryInstances: cast.slice(i, i + SEQUENCE_PRIMITIVE_BATCH),
+          appearance: new Cesium.PolylineColorAppearance({ translucent: true }),
+          asynchronous: true,
+          allowPicking: true,
+        }),
+      });
+    return { primitives, draped, cast: cast.length };
+  }
+
+  /**
+   * Fetch the terrain heights a tile's lines need, then redraw it cast.
+   * `castRequested` stops the redraw from casting again at once; a refresh
+   * `retry`s a tile whose lines are still draped (a failed or partial cast),
+   * and it is redrawn only when more of its lines can be cast.
+   */
+  function castTile(entry, { retry = false } = {}) {
+    if ((entry.castRequested && !retry) || entry.castAbort || !terrainMode())
+      return;
+    entry.castRequested = true;
+    entry.castAbort = new AbortController();
+    const { signal } = entry.castAbort;
+    const lines = [...entry.sequences.values()].flatMap(
+      (sequence) => sequence.parts,
+    );
+    const caster = state.context.groundCaster;
+    caster.prepareLines(lines, { signal }).then(() => {
+      if (entry.castAbort?.signal === signal) entry.castAbort = null;
+      const attached = [...state.coverage.tiles.values()].includes(entry);
+      if (signal.aborted || !attached || !terrainMode()) return;
+      // Nothing new to cast: keep what is drawn until the next refresh.
+      // Counted like buildSequencePrimitives: a cast line needs two points.
+      const castable = lines.filter(
+        (coords) => caster.castLine(coords)?.length >= 6,
+      ).length;
+      if (castable <= (entry.castLines || 0)) {
+        entry.castRequested = (entry.castLines || 0) > 0;
+        return;
+      }
+      // A remesh may have cleared the flag while this was in flight.
+      entry.castRequested = true;
+      redrawTile(entry);
+      requestMesh(entry);
+    });
+  }
+
+  /** Rebuild a tile's lines; the old ones stay up until the new are ready. */
+  function redrawTile(entry) {
+    const previous = entry.primitives;
+    entry.primitives = [];
+    attachPrimitive(entry);
+    removeWhenReady(entry, previous);
+  }
+
+  /** Lon/lat under the camera, where mesh range is measured from. */
+  function meshCentre() {
+    const carto = state.viewer?.camera?.positionCartographic;
+    if (!carto) return null;
+    return {
+      lon: Cesium.Math.toDegrees(carto.longitude),
+      lat: Cesium.Math.toDegrees(carto.latitude),
+    };
+  }
+
+  /**
+   * A tile's drawn lines with bounding boxes, built once per filter; mesh
+   * points are densified the first time a line is in range.
+   */
+  function meshParts(entry) {
+    if (entry.meshParts) return entry.meshParts;
+    entry.meshParts = [];
+    for (const sequence of entry.sequences.values())
+      for (const part of sequence.parts) {
+        const box = {
+          west: Infinity,
+          south: Infinity,
+          east: -Infinity,
+          north: -Infinity,
+        };
+        for (const [lon, lat] of part) {
+          if (lon < box.west) box.west = lon;
+          if (lon > box.east) box.east = lon;
+          if (lat < box.south) box.south = lat;
+          if (lat > box.north) box.north = lat;
+        }
+        entry.meshParts.push({ part, box, points: null });
+      }
+    return entry.meshParts;
+  }
+
+  /**
+   * Ask for mesh samples under a cast tile's lines within the sampler's range
+   * of the camera; the rest are asked for when a camera move brings them in.
+   */
+  function requestMesh(entry) {
+    const sampler = state.context.meshSampler;
+    if (!sampler || entry.kind !== 'sequence' || !terrainMode()) return;
+    const centre = meshCentre();
+    if (!centre || !entry.bounds || !meshBoxInRange(entry.bounds, centre))
+      return;
+    const points = [];
+    for (const line of meshParts(entry)) {
+      if (!meshBoxInRange(line.box, centre)) continue;
+      line.points ||= densifyLine(line.part, MESH_DENSIFY_DEG);
+      for (const point of line.points) points.push(point);
+    }
+    if (points.length) sampler.request(points);
+  }
+
+  /** Redraw the tiles new mesh samples fall in, throttled. */
+  function onMeshSampled(batch) {
+    if (!terrainMode() || !state.context.isActive()) return;
+    for (const entry of state.coverage.tiles.values()) {
+      if (entry.kind !== 'sequence' || !entry.bounds) continue;
+      const { west, south, east, north } = entry.bounds;
+      if (
+        batch.some(
+          ([lon, lat]) =>
+            lon >= west && lon <= east && lat >= south && lat <= north,
+        )
+      )
+        state.coverage.remeshDirty.add(entry);
+    }
+    if (!state.coverage.remeshDirty.size || state.coverage.remeshTimer) return;
+    const wait = Math.max(
+      0,
+      REMESH_INTERVAL_MS - (Date.now() - (state.coverage.remeshAt || 0)),
+    );
+    state.coverage.remeshTimer = setTimeout(remesh, wait);
+  }
+
+  /** Redraw one dirty tile per idle slice, so a burst of samples never stalls a frame. */
+  function remesh() {
+    state.coverage.remeshTimer = null;
+    state.coverage.remeshAt = Date.now();
+    if (!terrainMode() || !state.context.isActive()) {
+      state.coverage.remeshDirty.clear();
+      return;
+    }
+    const attached = new Set(state.coverage.tiles.values());
+    const [entry] = state.coverage.remeshDirty;
+    if (!entry) return;
+    state.coverage.remeshDirty.delete(entry);
+    if (attached.has(entry)) {
+      redrawTile(entry);
+      requestRender();
+    }
+    if (state.coverage.remeshDirty.size)
+      state.coverage.remeshTimer = setTimeout(
+        () => whenIdle(remesh, 500),
+        REMESH_STAGGER_MS,
+      );
+  }
+
+  state.coverage.remeshDirty = new Set();
+  state.context.meshSampler?.onSampled(onMeshSampled);
+
+  /**
+   * Remove a tile's previous primitives once all its current ones are ready
+   * (or after a few seconds); detaching the tile removes them at once.
+   */
+  function removeWhenReady(entry, old) {
+    const scene = state.viewer?.scene;
+    finishSwap(entry);
+    if (!scene?.postRender) {
+      removePrimitives(old);
+      return;
+    }
+    const fresh = entry.primitives;
+    const started = Date.now();
+    const stop = scene.postRender.addEventListener(() => {
+      const ready = fresh.every(
+        ({ primitive }) => primitive.ready || primitive.isDestroyed?.(),
+      );
+      if (!ready && Date.now() - started < SWAP_MAX_WAIT_MS) {
+        requestRender();
+        return;
+      }
+      finishSwap(entry);
+      requestRender();
+    });
+    entry.swap = { old, stop };
+    requestRender();
+  }
+
+  function finishSwap(entry) {
+    if (!entry.swap) return;
+    entry.swap.stop();
+    removePrimitives(entry.swap.old);
+    entry.swap = null;
+  }
+
+  function buildOverviewCollection(points) {
+    const collection = new Cesium.PointPrimitiveCollection({
+      blendOption: Cesium.BlendOption.TRANSLUCENT,
+    });
+    const tint = Cesium.Color.fromCssColorString(colors.coverage).withAlpha(
+      0.85,
+    );
+    const drawn = [];
+    const current = filter();
+    for (const point of points) {
+      if (!passes(point, current)) continue;
+      drawn.push(
+        collection.add({
+          position: Cesium.Cartesian3.fromDegrees(point.lon, point.lat),
+          color: tint,
+          pixelSize: tuning.overviewPointPx,
+          // Google 3D terrain and clouds must not hide the near side's dots;
+          // the horizon cull hides the far side's, which this lets through.
+          disableDepthTestDistance: Number.POSITIVE_INFINITY,
+        }),
+      );
+    }
+    return { collection, points: drawn };
+  }
+
+  /** Every overview point on the globe, current zoom and old alike. */
+  function* overviewPoints() {
+    for (const entry of drawnEntries())
+      if (entry.overviewPoints) yield* entry.overviewPoints;
+  }
+
+  // Overview points skip the depth test: hide the far hemisphere's.
+  const horizon = createHorizonCull({
+    getViewer: () => state.viewer,
+    items: overviewPoints,
+    onChange: requestRender,
+  });
+
+  function attachPrimitive(entry) {
+    const scene = state.viewer?.scene;
+    if (!scene) return;
+    if (entry.kind === 'sequence') {
+      // Lookup, picking and counts follow what is drawn, not the whole tile.
+      const sequences = drawnSequences(entry);
+      entry.sequences = new Map(sequences.map((s) => [s.id, s]));
+      const { primitives, draped, cast } = buildSequencePrimitives(sequences);
+      entry.primitives = primitives;
+      entry.count = sequences.length;
+      for (const { primitive, onGround } of primitives)
+        (onGround ? scene.groundPrimitives : scene.primitives).add(primitive);
+      // Fewer lines cast than last time: the caster has dropped heights this
+      // tile used (a full cache), so it must be cast again.
+      if (cast < (entry.castLines || 0)) entry.castRequested = false;
+      entry.castLines = cast;
+      entry.drapedLines = draped.length;
+      if (draped.length) castTile(entry);
+      watchSelection();
+    } else {
+      const { collection, points } = buildOverviewCollection(entry.points);
+      entry.primitive = collection;
+      entry.overviewPoints = points;
+      entry.count = points.length;
+      scene.primitives.add(collection);
+      // Cull the new points now, then all of them whenever the camera moves.
+      horizon.update(points);
+    }
+  }
+
+  function removePrimitives(list) {
+    const scene = state.viewer?.scene;
+    for (const { primitive, onGround } of list || []) {
+      try {
+        (onGround ? scene?.groundPrimitives : scene?.primitives)?.remove(
+          primitive,
+        );
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+
+  function detachPrimitive(entry) {
+    const scene = state.viewer?.scene;
+    finishSwap(entry);
+    removePrimitives(entry.primitives);
+    entry.primitives = [];
+    if (entry.primitive) {
+      try {
+        scene?.primitives?.remove(entry.primitive);
+      } catch {
+        /* already gone */
+      }
+      entry.primitive = null;
+      entry.overviewPoints = null;
+    }
+  }
+
+  /** Stop a tile's pending terrain lookup (tile dropped or retired). */
+  function cancelCast(entry) {
+    entry.castAbort?.abort();
+    entry.castAbort = null;
+  }
+
+  function removeTile(key) {
+    const entry = state.coverage.tiles.get(key);
+    if (!entry) return;
+    cancelCast(entry);
+    detachPrimitive(entry);
+    state.coverage.tiles.delete(key);
+  }
+
+  async function loadTile(tile, kind) {
+    const key = tileKey(tile);
+    if (state.coverage.tiles.has(key) || state.coverage.pending.has(key))
+      return;
+    const controller = new AbortController();
+    state.coverage.pending.set(key, controller);
+    notify();
+    try {
+      // Fetch and the one-time terrain-height table load run side by side,
+      // both handled from the start so an early tile failure is not unhandled.
+      const [decoded] = await Promise.all([
+        fetchTile(tile, { signal: controller.signal }),
+        kind === 'sequence' ? ensureTerrainReady() : null,
+      ]);
+      // Only an abort, a retire, a clear or a newer request for this tile
+      // discards the bytes; a refresh that still wants the tile keeps them.
+      const current = () =>
+        state.coverage.pending.get(key) === controller &&
+        !state.coverage.tiles.has(key);
+      if (
+        controller.signal.aborted ||
+        !current() ||
+        kind !== state.coverage.kind ||
+        tile.z !== state.coverage.zoom
+      )
+        return;
+      const entry = { kind, primitive: null, primitives: [], count: 0 };
+      // Padded: vector tiles carry a small buffer past their edge.
+      const bounds = tileBounds(tile.x, tile.y, tile.z);
+      const pad = (bounds.east - bounds.west) * 0.05;
+      entry.bounds = {
+        west: bounds.west - pad,
+        east: bounds.east + pad,
+        south: bounds.south - pad,
+        north: bounds.north + pad,
+      };
+      if (kind === 'sequence') {
+        // Newest first; the per-tile cap applies to what passes the filter.
+        entry.sequenceList = decoded.sequences.sort(
+          (a, b) => (b.capturedAt || 0) - (a.capturedAt || 0),
+        );
+        entry.sequences = new Map();
+        entry.total = decoded.sequences.length;
+      } else {
+        entry.points = decoded.overview;
+        entry.sequences = new Map();
+        entry.total = decoded.overview.length;
+      }
+      attachPrimitive(entry);
+      state.coverage.tiles.set(key, entry);
+      state.coverage.lastError = null;
+      requestRender();
+    } catch (error) {
+      if (
+        controller.signal.aborted ||
+        state.coverage.pending.get(key) !== controller
+      )
+        return;
+      state.coverage.lastError = error?.message || 'Coverage tile failed';
+      if (error?.keyRequired) state.keyRequired = true;
+      if (error?.keyRejected) {
+        // Every other tile would be refused too: stop asking.
+        state.keyRejected = true;
+        state.coverage.lastError =
+          messages.keyRejected || state.coverage.lastError;
+      }
+      if (error?.retryAfterSec) holdFor(error.retryAfterSec);
+    } finally {
+      // Only the request that still owns the key settles it: a superseded one
+      // must not drop a newer request's entry (which is what counts as loading).
+      if (state.coverage.pending.get(key) === controller) {
+        state.coverage.pending.delete(key);
+        if (!state.coverage.pending.size) purgeStale();
+      }
+      notify();
+    }
+  }
+
+  /**
+   * The source is rate-limiting: keep what is drawn, request nothing until the
+   * wait is over, then refresh once.
+   */
+  function holdFor(seconds) {
+    clearTimeout(state.coverage.holdTimer);
+    state.coverage.holdUntil = Date.now() + seconds * 1000;
+    state.coverage.lastError = messages.rateLimited;
+    state.coverage.holdTimer = setTimeout(() => {
+      state.coverage.holdTimer = null;
+      state.coverage.holdUntil = 0;
+      if (state.coverage.lastError === messages.rateLimited)
+        state.coverage.lastError = null;
+      refresh();
+    }, seconds * 1000);
+  }
+
+  /** Forget refusals when the provider goes off, so the next run asks again. */
+  function resetErrors() {
+    clearTimeout(state.coverage.holdTimer);
+    state.coverage.holdTimer = null;
+    state.coverage.holdUntil = 0;
+    state.coverage.lastError = null;
+    state.keyRejected = false;
+  }
+
+  /** Drop the previous zoom's tiles once the new ones are on screen. */
+  function purgeStale() {
+    clearTimeout(state.coverage.staleTimer);
+    state.coverage.staleTimer = null;
+    if (!state.coverage.stale.size) return;
+    for (const entry of state.coverage.stale.values()) detachPrimitive(entry);
+    state.coverage.stale.clear();
+    requestRender();
+  }
+
+  /** Move tiles to the stale set: the old zoom shows until the new one loads. */
+  function retire() {
+    for (const controller of state.coverage.pending.values())
+      controller.abort();
+    state.coverage.pending.clear();
+    for (const [key, entry] of state.coverage.tiles) {
+      cancelCast(entry);
+      const previous = state.coverage.stale.get(key);
+      if (previous) detachPrimitive(previous);
+      state.coverage.stale.set(key, entry);
+    }
+    state.coverage.tiles.clear();
+    clearTimeout(state.coverage.staleTimer);
+    state.coverage.staleTimer = setTimeout(purgeStale, STALE_TILE_MAX_MS);
+  }
+
+  function notify() {
+    state.context.notify();
+  }
+
+  /**
+   * Whether the screen centre meets the ground further ahead than the camera
+   * is high (a view tilted above 45°), or misses it.
+   */
+  function isTilted({ nadir, ahead }, height) {
+    if (!ahead) return true;
+    return metresBetween(nadir, ahead) > Math.max(1, height);
+  }
+
+  /** Recompute the tile set for the current camera and reconcile primitives. */
+  function refresh() {
+    const viewer = state.viewer;
+    if (!viewer || !state.context.isActive() || state.keyRequired) return;
+    if (state.statusKnown === false) return;
+    if (state.keyRejected || state.coverage.holdUntil > Date.now()) return;
+    const ground = groundUnderCamera(viewer, {
+      groundAt: state.context.groundCaster?.groundAt,
+    });
+    const cameraHeight = viewer.camera?.positionCartographic?.height;
+    const height = Number.isFinite(cameraHeight)
+      ? cameraHeight - (ground ?? 0)
+      : null;
+    const level = zoomFor(height);
+    const zoom = level?.zoom ?? null;
+    const kind = level?.kind ?? null;
+    // At street zooms the rays meet the ground where it really is (1,600 m up
+    // in Denver; Google 3D hides the globe) and stop short of the horizon.
+    const ranged =
+      kind === 'sequence'
+        ? {
+            groundHeight: ground,
+            maxRange: Math.max(
+              tuning.viewRangeMinM,
+              height * tuning.viewRangePerHeight,
+            ),
+          }
+        : {};
+    // Tilted street views rank tiles along the line of sight, from the ground
+    // under the camera to the ground at the centre of the screen.
+    const focus = kind === 'sequence' ? viewFocus(viewer, ranged) : null;
+    let bbox = visibleBbox(viewer, {
+      ...ranged,
+      // A tilted view's screen rows jump from the first metres to the horizon:
+      // keep the ground around the camera too. Looking down needs no help.
+      nearRange: focus && isTilted(focus, height) ? tuning.viewNearM : null,
+    });
+    if (kind === 'overview' && (!bbox || zoom <= 1))
+      bbox = [-180, -85, 180, 85];
+    if (zoom == null || !bbox) {
+      state.coverage.hint =
+        zoom == null && Number.isFinite(height) && messages.tooHigh
+          ? messages.tooHigh
+          : 'Point the camera at the globe for street-level coverage';
+      clear();
+      notify();
+      return;
+    }
+    state.coverage.hint = '';
+    if (zoom !== state.coverage.zoom || kind !== state.coverage.kind) {
+      retire();
+      state.coverage.zoom = zoom;
+      state.coverage.kind = kind;
+    }
+    const { tiles } = tilesForBbox(bbox, zoom, {
+      limit: kind === 'sequence' ? tuning.maxTiles : tuning.overviewMaxTiles,
+      focus: focus && { from: focus.nadir, to: focus.ahead },
+    });
+    const wanted = new Set(tiles.map(tileKey));
+    for (const key of [...state.coverage.tiles.keys()])
+      if (!wanted.has(key)) removeTile(key);
+    for (const [key, controller] of [...state.coverage.pending])
+      if (!wanted.has(key)) {
+        // The aborted request no longer owns its key, so its `finally` will
+        // not settle it: settle it here.
+        controller.abort();
+        state.coverage.pending.delete(key);
+      }
+    for (const tile of tiles) loadTile(tile, kind);
+    if (!state.coverage.pending.size) purgeStale();
+    // The camera moved: cells that were out of the sampler's range may not be,
+    // and lines left draped by a failed, partial or dropped cast get another try.
+    if (terrainMode())
+      for (const entry of state.coverage.tiles.values()) {
+        if (entry.castRequested) requestMesh(entry);
+        if (entry.drapedLines) castTile(entry, { retry: true });
+      }
+    notify();
+  }
+
+  function scheduleRefresh() {
+    clearTimeout(state.coverage.debounceTimer);
+    state.coverage.debounceTimer = setTimeout(refresh, tuning.moveDebounceMs);
+  }
+
+  function attach(viewer) {
+    detach();
+    const remove = viewer.camera.changed.addEventListener(scheduleRefresh);
+    const removeEnd = viewer.camera.moveEnd.addEventListener(scheduleRefresh);
+    state.coverage.removeCameraListener = () => {
+      remove();
+      removeEnd();
+    };
+    refresh();
+  }
+
+  function detach() {
+    clearTimeout(state.coverage.debounceTimer);
+    state.coverage.debounceTimer = null;
+    state.coverage.removeCameraListener?.();
+    state.coverage.removeCameraListener = null;
+  }
+
+  function clear() {
+    for (const controller of state.coverage.pending.values())
+      controller.abort();
+    state.coverage.pending.clear();
+    for (const key of [...state.coverage.tiles.keys()]) removeTile(key);
+    purgeStale();
+    state.coverage.zoom = null;
+    state.coverage.kind = null;
+    clearTimeout(state.coverage.remeshTimer);
+    state.coverage.remeshTimer = null;
+    state.coverage.remeshDirty.clear();
+    stopSelectionWatch();
+    horizon.stop();
+    requestRender();
+  }
+
+  /** Rebuild every loaded tile from its decoded cache (after a filter change). */
+  function rebuild() {
+    purgeStale();
+    for (const entry of state.coverage.tiles.values()) {
+      cancelCast(entry);
+      entry.castRequested = false;
+      entry.meshParts = null;
+      detachPrimitive(entry);
+      attachPrimitive(entry);
+    }
+    requestRender();
+    notify();
+  }
+
+  /**
+   * Load every tile again (a source that filters on its server had its
+   * filter changed); the lines drawn now show until the new ones are in.
+   */
+  function reload() {
+    retire();
+    refresh();
+  }
+
+  /**
+   * Redraw tiles draped or cast for the new surface mode, then re-pick the
+   * zoom, since the ground height under the camera may have changed.
+   */
+  function setSurface() {
+    if (!state.context.isActive()) return;
+    rebuild();
+    refresh();
+  }
+
+  /** Recolour every part of a sequence in one ready primitive. */
+  function recolorInstances(primitive, sequence, selected) {
+    const value = sequenceColor({ selected });
+    for (const instanceId of partIds(sequence, pickPrefix)) {
+      try {
+        const attributes = primitive.getGeometryInstanceAttributes(instanceId);
+        if (attributes)
+          attributes.color = Cesium.ColorGeometryInstanceAttribute.toValue(
+            value,
+            attributes.color,
+          );
+      } catch {
+        /* instance not in this primitive */
+      }
+    }
+  }
+
+  /** Every tile on the globe: the current zoom's and the stale zoom's. */
+  function drawnEntries() {
+    return [...state.coverage.tiles.values(), ...state.coverage.stale.values()];
+  }
+
+  /** A tile's primitives on the globe: its own, and the ones a swap still shows. */
+  function drawnRecords(entry) {
+    const records = entry.primitives || [];
+    return entry.swap ? [...records, ...entry.swap.old] : records;
+  }
+
+  /** Recolour one sequence, every part of it, in place (selection highlight). */
+  function recolorSequence(id, selected) {
+    for (const entry of drawnEntries()) {
+      const sequence = entry.sequences.get(id);
+      if (!sequence) continue;
+      for (const record of drawnRecords(entry)) {
+        // Still building: `syncSelection` catches it up once it is ready.
+        if (!record.primitive.ready) continue;
+        recolorInstances(record.primitive, sequence, selected);
+        if (selected) record.selectedId = id;
+        else if (record.selectedId === id) record.selectedId = null;
+      }
+    }
+    requestRender();
+  }
+
+  /**
+   * Bring a ready primitive's highlight up to the current selection, when
+   * it was built with another one (or none). True when it changed.
+   */
+  function syncSelection(entry, record) {
+    const current = state.sequence.selectedId ?? null;
+    if (record.selectedId === current || !record.primitive.ready) return false;
+    const previous =
+      record.selectedId && entry.sequences.get(record.selectedId);
+    if (previous) recolorInstances(record.primitive, previous, false);
+    const next = current && entry.sequences.get(current);
+    if (next) recolorInstances(record.primitive, next, true);
+    record.selectedId = current;
+    return true;
+  }
+
+  /**
+   * A primitive cannot be recoloured until it is ready, so while any is
+   * building, catch each one up with the selection as it becomes ready.
+   */
+  function watchSelection() {
+    const scene = state.viewer?.scene;
+    if (state.coverage.stopSelectionWatch || !scene?.postRender) return;
+    const stop = scene.postRender.addEventListener(() => {
+      let building = false;
+      let changed = false;
+      for (const entry of drawnEntries()) {
+        for (const record of entry.primitives || []) {
+          if (!record.primitive.ready) building = true;
+          else if (syncSelection(entry, record)) changed = true;
+        }
+        // Lines a swap still shows were ready (or never show): catch up only.
+        for (const record of entry.swap?.old || [])
+          if (syncSelection(entry, record)) changed = true;
+      }
+      if (changed) requestRender();
+      if (!building) stopSelectionWatch();
+    });
+    state.coverage.stopSelectionWatch = stop;
+  }
+
+  function stopSelectionWatch() {
+    state.coverage.stopSelectionWatch?.();
+    state.coverage.stopSelectionWatch = null;
+  }
+
+  /**
+   * Sequences (or overview points) drawn. A sequence that crosses a tile
+   * edge is in both tiles' lists, so sequences count once by id.
+   */
+  function sequenceCount() {
+    const ids = new Set();
+    let points = 0;
+    for (const entry of state.coverage.tiles.values())
+      if (entry.kind === 'sequence')
+        for (const id of entry.sequences.keys()) ids.add(id);
+      else points += entry.count;
+    return ids.size + points;
+  }
+
+  return {
+    attach,
+    detach,
+    refresh,
+    clear,
+    resetErrors,
+    rebuild,
+    reload,
+    setSurface,
+    recolorSequence,
+    sequenceCount,
+  };
+}

src/layers/streetLevel/lineCoverage.test.mjs

@@ -0,0 +1,142 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createLineCoverage } from './lineCoverage.js';
+import {
+  coverageViewer,
+  tileCentre,
+} from '../../testSupport/streetLevelFakes.mjs';
+import { until } from '../../testSupport/kartaViewFakes.mjs';
+
+const TUNING = Object.freeze({
+  maxTiles: 9,
+  overviewMaxTiles: 0,
+  maxSequences: 900,
+  lineWidthPx: 2,
+  overviewPointPx: 2,
+  moveDebounceMs: 10,
+  viewRangeMinM: 2_500,
+  viewRangePerHeight: 10,
+  viewNearM: 1_000,
+});
+
+/**
+ * Line coverage over one tile holding one line, on a viewer looking down from
+ * `height`. `fetchTile` answers with that line unless `fail` says otherwise.
+ */
+function setup(
+  t,
+  { zoomFor, messages = { rateLimited: 'busy' }, passes, fail } = {},
+) {
+  const centre = tileCentre(-121.4944, 38.5816);
+  const viewer = coverageViewer(
+    { lon: centre.lon, lat: centre.lat, height: 900 },
+    t,
+  );
+  const state = {
+    viewer,
+    services: {},
+    keyRequired: false,
+    keyRejected: false,
+    context: {
+      getFilter: () => ({ pano: 'all', sinceMs: null }),
+      isActive: () => true,
+      notify() {},
+      getSurface: () => 'draped',
+      groundCaster: null,
+      meshSampler: null,
+    },
+    coverage: {
+      zoom: null,
+      kind: null,
+      tiles: new Map(),
+      stale: new Map(),
+      staleTimer: null,
+      pending: new Map(),
+      lastError: null,
+      holdUntil: 0,
+      holdTimer: null,
+      debounceTimer: null,
+      removeCameraListener: null,
+      terrainReady: Promise.resolve(),
+      hint: '',
+    },
+    sequence: { selectedId: null },
+  };
+  const asked = [];
+  const coverage = createLineCoverage({
+    state,
+    fetchTile: async (tile) => {
+      asked.push(tile);
+      if (fail) throw fail;
+      return {
+        sequences: [
+          {
+            id: 'line-1',
+            parts: [
+              [
+                [centre.lon - 0.001, centre.lat],
+                [centre.lon + 0.001, centre.lat],
+              ],
+            ],
+            capturedAt: 0,
+            isPano: false,
+          },
+        ],
+        overview: [],
+      };
+    },
+    zoomFor:
+      zoomFor ??
+      ((height) =>
+        Number.isFinite(height) && height <= 6_000
+          ? { zoom: 14, kind: 'sequence' }
+          : null),
+    colors: { coverage: '#635bff', selected: '#00e5ff' },
+    pickPrefix: 'test:line:',
+    renderKey: 'test-coverage',
+    tuning: TUNING,
+    messages,
+    ...(passes ? { passes } : {}),
+  });
+  t.after(() => {
+    coverage.clear();
+    coverage.resetErrors();
+  });
+  return { viewer, state, coverage, asked };
+}
+
+test('above the zoom range the provider’s own “zoom in” hint shows; without one, the generic hint', (t) => {
+  const tooHigh = 'zoom in to see test coverage';
+  const high = setup(t, { messages: { rateLimited: 'busy', tooHigh } });
+  high.viewer.view.height = 7_000;
+  high.coverage.refresh();
+  assert.equal(high.state.coverage.hint, tooHigh);
+  assert.equal(high.state.coverage.zoom, null);
+  assert.equal(high.asked.length, 0, 'nothing is asked from up there');
+  const generic = setup(t);
+  generic.viewer.view.height = 7_000;
+  generic.coverage.refresh();
+  assert.notEqual(generic.state.coverage.hint, tooHigh);
+  assert.match(generic.state.coverage.hint, /Point the camera/);
+});
+
+test('a provider’s passes() decides which lines are drawn and counted', async (t) => {
+  const all = setup(t, { passes: () => true });
+  all.coverage.refresh();
+  assert.ok(await until(() => all.state.coverage.tiles.size === 1));
+  assert.equal(all.coverage.sequenceCount(), 1, 'control: the line is drawn');
+  const none = setup(t, { passes: () => false });
+  none.coverage.refresh();
+  assert.ok(await until(() => none.state.coverage.tiles.size === 1));
+  assert.equal(none.coverage.sequenceCount(), 0, 'filtered out');
+});
+
+test('a refused key without its own message keeps the error it came with', async (t) => {
+  const refused = Object.assign(new Error('the source refused the key'), {
+    keyRejected: true,
+  });
+  const { state, coverage } = setup(t, { fail: refused });
+  coverage.refresh();
+  assert.ok(await until(() => state.keyRejected === true));
+  assert.equal(state.coverage.lastError, 'the source refused the key');
+});

src/layers/streetLevel/marker.js

@@ -1,11 +1,27 @@
 import * as Cesium from 'cesium';
-import { positionMarkerGlyph } from './glyphs.js';
+import { positionMarkerGlyph, viewConeMarkerGlyph } from './glyphs.js';
 import { COLORS, POSITION_PICK_ID } from './policy.js';
 import { refineHeights } from './groundCast.js';
 import { createHorizonCull } from './view.js';
 
 const SPRITE_ID = 'street-level:marker';
 
+function markerLook(style) {
+  if (style?.kind === 'view-cone') {
+    const color = style.color || COLORS.position;
+    return {
+      key: `view-cone:${color}`,
+      image: viewConeMarkerGlyph({ color }),
+      size: 48,
+    };
+  }
+  return {
+    key: 'pin',
+    image: positionMarkerGlyph({ color: COLORS.position }),
+    size: 40,
+  };
+}
+
 /** On-globe marker for the open image; in terrain mode it stands on bare earth. */
 export function createMarker({ state, parts }) {
   const { render, sprites } = state.services;
@@ -42,7 +58,8 @@ export function createMarker({ state, parts }) {
     const dem = ground.groundAt(lon, lat);
     if (dem === null) {
       ground.prepare([[lon, lat]]).then((ready) => {
-        if (ready && last?.position === position) set(position, last.bearing);
+        if (ready && last?.position === position)
+          set(position, last.bearing, last.style);
       });
       return null;
     }
@@ -53,14 +70,15 @@ export function createMarker({ state, parts }) {
 
   // A new mesh sample may move the marker onto (or off) the road surface.
   parts?.meshSampler?.onSampled(() => {
-    if (last && state.surface === 'terrain') set(last.position, last.bearing);
+    if (last && state.surface === 'terrain')
+      set(last.position, last.bearing, last.style);
   });
 
-  /** Move (or create) the marker; a null position removes it. */
-  function set(position, bearing) {
+  /** Move (or create) the marker; null removes it. `style`: the provider's `marker`. */
+  function set(position, bearing, style = null) {
     const collection = state.marker.collection;
     if (!collection) return;
-    last = position ? { position, bearing } : null;
+    last = position ? { position, bearing, style } : null;
     if (!position) {
       collection.removeAll();
       state.marker.billboard = null;
@@ -78,14 +96,20 @@ export function createMarker({ state, parts }) {
       height === null
         ? Cesium.HeightReference.CLAMP_TO_GROUND
         : Cesium.HeightReference.NONE;
+    const look = markerLook(style);
+    if (state.marker.billboard && state.marker.look !== look.key) {
+      collection.remove?.(state.marker.billboard);
+      state.marker.billboard = null;
+    }
     if (!state.marker.billboard) {
+      state.marker.look = look.key;
       state.marker.billboard = collection.add({
         id: POSITION_PICK_ID,
         position: cartesian,
-        image: positionMarkerGlyph({ color: COLORS.position }),
-        imageId: 'sl-position',
-        width: 40,
-        height: 40,
+        image: look.image,
+        imageId: `sl-position:${look.key}`,
+        width: look.size,
+        height: look.size,
         alignedAxis: Cesium.Cartesian3.UNIT_Z,
         heightReference,
         disableDepthTestDistance: Number.POSITIVE_INFINITY,
@@ -117,7 +141,7 @@ export function createMarker({ state, parts }) {
 
   /** Re-place the marker after the surface mode changes. */
   function setSurface() {
-    if (last) set(last.position, last.bearing);
+    if (last) set(last.position, last.bearing, last.style);
   }
 
   return {

src/layers/streetLevel/marker.test.mjs

@@ -40,6 +40,7 @@ function setup({ parts = {}, surface = 'draped' } = {}) {
       collection: {
         show: true,
         add: (options) => ({ ...options }),
+        remove() {},
         removeAll() {},
       },
       billboard: null,
@@ -187,3 +188,28 @@ test('draped mode clamps the marker to the globe whatever the ground says', () =
   );
   assert.equal(ground.prepares.length, 0);
 });
+
+test('a Street View photo gets a blue view cone; a Mapillary photo GEV\u2019s pin', () => {
+  const { state, marker } = setup();
+  const removed = [];
+  state.marker.collection.remove = (billboard) => removed.push(billboard);
+  const streetView = { kind: 'view-cone', color: '#4285f4' };
+  marker.set({ lon: -121.49, lat: 38.58 }, 45, streetView);
+  const cone = state.marker.billboard;
+  assert.equal(cone.imageId, 'sl-position:view-cone:#4285f4');
+  assert.equal(
+    cone.rotation,
+    -Cesium.Math.toRadians(45),
+    'it turns with the view',
+  );
+  // Dragging the panorama keeps the look and the billboard.
+  marker.set({ lon: -121.49, lat: 38.58 }, 90, streetView);
+  assert.equal(state.marker.billboard, cone);
+  // Re-placed for a surface change: still the cone.
+  marker.setSurface();
+  assert.equal(state.marker.billboard, cone);
+  // A Mapillary photo next (its provider has no marker): the pin.
+  marker.set({ lon: -121.49, lat: 38.58 }, 90, undefined);
+  assert.equal(state.marker.billboard.imageId, 'sl-position:pin');
+  assert.deepEqual(removed, [cone]);
+});

src/layers/streetLevel/policy.js

@@ -7,6 +7,8 @@ export const POSITION_PICK_ID = 'sl:pos';
 /** One colour per imagery source: chip, coverage lines, points, cones and legend. */
 export const PROVIDER_COLORS = Object.freeze({
   mapillary: '#05cb63',
+  google: '#4285f4',
+  kartaview: '#635bff',
 });
 
 /** Colours every provider shares: the selection highlight and the marker. */
@@ -35,3 +37,9 @@ export const FOLLOW_MAP_STACK_ID = 'photoreal';
 
 /** Eye height above the sampled ground when the globe camera follows the viewer. */
 export const FOLLOW_EYE_HEIGHT_M = 2.4;
+
+/** Above this, a ground click is a misclick, not a street. */
+export const GROUND_CLICK_MAX_HEIGHT_M = 3_000;
+
+export const AIM_AT_GROUND_MESSAGE =
+  'Aim the middle of the view at a street to look for imagery there';