Merge remote-tracking branch 'upstream/main' into core-rb2

# Conflicts:
#	CHANGELOG.md
#	build/vite.js
#	scripts/package-boundaries.json
#	server/standalone/vite.config.js
#	src/app/scene.js
#	src/layers/vessels/queries.js
#	src/standalone/application.js
#	src/tooling/viteBuild.test.mjs
#	src/ui/cockpitInstruments.js
#	src/ui/layerPanel.js
#	src/ui/panelPositionControls.js

src/app/catalog.js

@@ -4,6 +4,7 @@ const CONTROL_LAYER_IDS = Object.freeze({
   militaryFlightsLayer: 'military',
   satellitesLayer: 'satellites',
   cctvLayer: 'cctv',
+  streetLevelLayer: 'street-level',
   radioLayer: 'radio',
   bikeshareLayer: 'bikeshare',
   transitLayer: 'transit',

src/app/catalog.test.mjs

@@ -65,13 +65,28 @@ test('data setup seals the caller catalog before controls can restore and drains
         },
       },
     },
-    catalog: createLayerCatalog(layers, metadata(layers)),
+    catalog: {
+      ...createLayerCatalog(layers, metadata(layers)),
+      getSourceAvailability: (id) =>
+        id === 'one'
+          ? {
+              available: false,
+              reason: 'One: data source not configured',
+            }
+          : undefined,
+    },
     defer: (release) => releases.push(release),
     onData: (manager) => {
       observed = manager;
     },
   });
   assert.equal(observed, dataManager);
+  assert.equal(await dataManager.setEnabled('one', true), false);
+  assert.equal(dataManager.layers.get('one').initialized, false);
+  assert.equal(
+    dataManager.getAll().find(({ id }) => id === 'one').stats.error,
+    'One: data source not configured',
+  );
   assert.deepEqual(attached, [['one', 'two']]);
   assert.deepEqual([...dataManager.layers.keys()], ['one', 'two']);
   assert.throws(() => dataManager.register({ id: 'late' }), /finalized/);
@@ -93,6 +108,7 @@ test('controls bind catalog instances rather than similarly named defaults', ()
     'military-awareness',
     'military-installations',
     'rocket-launches',
+    'street-level',
     'local-adsb',
   ];
   const layers = ids.map((id) => ({ id }));
@@ -101,7 +117,7 @@ test('controls bind catalog instances rather than similarly named defaults', ()
   assert.equal(services.flightsLayer, layers[1]);
   assert.equal(services.transitLayer, layers[7]);
   assert.equal(services.aisLiveVesselsLayer, layers[8]);
-  assert.equal(services.localAdsbLayer, layers[12]);
+  assert.equal(services.localAdsbLayer, layers[13]);
   assert.equal(new Set(Object.values(services)).size, layers.length);
   assert.throws(
     () => catalogControlServices(createLayerCatalog([], [])),

src/app/constructCatalog.js

@@ -1,3 +1,4 @@
+import { resolveCatalogSources } from './sourceComposition.js';
 import { createWeatherClock } from '../layers/weather/clock.js';
 import { createWeatherLayer } from '../layers/weather/index.js';
 import { createCyclonesLayer } from '../layers/cyclones/index.js';
@@ -25,38 +26,12 @@ import { createApplicationFirms } from './layers/firms.js';
 import { createApplicationEarthquakes } from './layers/earthquakes.js';
 import { createApplicationFirePerimeters } from './layers/perimeters.js';
 import { createApplicationCables } from './layers/submarineCables.js';
+import { createApplicationStreetLevel } from './layers/streetLevel.js';
 import { createInfrastructureLayers } from '../data/infrastructure.js';
 import { localGeoJsonServices } from './localGeojsonServices.js';
 import { createBhoteKoshiEventLayer } from '../data/bhoteKoshiEvent.js';
 import { createBhoteKoshiLocatorLayer } from '../data/bhoteKoshiLocator.js';
 
-const SOURCE_METHODS = Object.freeze({
-  flights: ['getSnapshot'],
-  military: ['getSnapshot'],
-  vessels: ['getSnapshot'],
-  cctv: ['getCatalog', 'getHealth', 'getFrameUrl', 'getMediaUrl'],
-  radio: ['getDirectory', 'recordClick'],
-  traffic: [
-    'requestRoads',
-    'getStatus',
-    'fetchFlowForBounds',
-    'getFlowSessionStats',
-    'resetFlowTileCache',
-  ],
-  bikeshare: ['getStations'],
-  installations: ['getMappedSites', 'searchNearby'],
-  satellites: ['readGroup'],
-  launches: ['getLaunches', 'getActiveTle'],
-  alpr: ['fetch'],
-  firms: ['getSnapshot'],
-  wind: ['getSnapshot'],
-  weather: ['getSnapshot'],
-  cyclones: ['getSnapshot'],
-  earthquakes: ['getSnapshot'],
-  'fire-perimeters': ['getSnapshot'],
-  cables: ['fetch'],
-});
-
 /**
  * Hardware-local layers are registered like any other but never enter share
  * links or stored layer state: another browser cannot have this receiver.
@@ -83,6 +58,7 @@ export function createApplicationCatalog({
   vesselOptions,
   resolveAsset,
   nepalBoundaryResolver,
+  streetLevelProviders,
 }) {
   if (!signal?.addEventListener)
     throw new TypeError('An application lifetime signal is required');
@@ -90,12 +66,8 @@ export function createApplicationCatalog({
   if (!surface?.groundFloor || !surface?.terrain)
     throw new TypeError('Application surface services are required');
 
-  for (const [name, methods] of Object.entries(SOURCE_METHODS)) {
-    if (
-      methods.some((method) => typeof sources?.[name]?.[method] !== 'function')
-    )
-      throw new TypeError(`Invalid catalog source: ${name}`);
-  }
+  const sourceComposition = resolveCatalogSources(sources);
+  sources = sourceComposition.sources;
   const militaryRegistry = createMilitaryRegistry();
   const weatherClock = createWeatherClock();
   const dispose = () => {
@@ -105,7 +77,8 @@ export function createApplicationCatalog({
   };
   signal.addEventListener('abort', dispose, { once: true });
   try {
-    militaryRegistry.configureSource(sources.military, { signal });
+    if (sourceComposition.isConfigured('military'))
+      militaryRegistry.configureSource(sources.military, { signal });
     const flights = createApplicationFlights({
       surface,
       source: sources.flights,
@@ -148,6 +121,11 @@ export function createApplicationCatalog({
           source: sources['fire-perimeters'],
         }),
         createApplicationAlpr({ surface, source: sources.alpr }),
+        createApplicationStreetLevel({
+          surface,
+          sources: { mapillary: sources.mapillary },
+          providers: streetLevelProviders,
+        }),
         satellites,
         createApplicationLaunches({ source: sources.launches, satellites }),
         createApplicationTraffic({ source: sources.traffic, surface }),
@@ -155,8 +133,8 @@ export function createApplicationCatalog({
         createApplicationRadio({ surface, source: sources.radio }),
         createApplicationTransit({ surface, source: sources.transit }),
         createApplicationBikeshare({ source: sources.bikeshare }),
-        createApplicationDirections(),
-        createApplicationRecentImagery(),
+        createApplicationDirections({ source: sources.directions }),
+        createApplicationRecentImagery({ source: sources['recent-imagery'] }),
         vessels,
         installations,
         createApplicationAwareness({
@@ -197,6 +175,9 @@ export function createApplicationCatalog({
     );
     return Object.freeze({
       ...catalog,
+      getSourceAvailability: sourceComposition.createAvailabilityLookup(
+        catalog.layers,
+      ),
       militaryRegistry,
       surface,
       weatherClock,

src/app/constructCatalog.test.mjs

@@ -5,6 +5,7 @@ import { createApplicationCatalog } from './constructCatalog.js';
 import { createStandaloneLayerSources } from '../standalone/layerSources.js';
 import { catalogControlServices } from './catalog.js';
 import { LayerLifecycle } from '../data/lifecycle.js';
+import { fakeStreetLevelProvider } from '../testSupport/streetLevelFakes.mjs';
 
 function fixtureSources(ids, calls) {
   const sources = createStandaloneLayerSources();
@@ -39,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, 29);
+  assert.equal(first.layers.length, 30);
   assert.ok(first.get('local-adsb'), 'Local ADS-B is registered');
   assert.deepEqual(
     first.metadata.find(({ id }) => id === 'local-adsb'),
@@ -116,7 +117,7 @@ test('invalid or already cancelled construction fails before classification can
   assert.throws(
     () =>
       createApplicationCatalog({
-        sources: {},
+        sources: { flights: {} },
         signal: lifetime.signal,
         surface: fixtureSurface(lifetime.signal),
       }),
@@ -140,3 +141,53 @@ function fixtureSurface(signal) {
     eventTarget: null,
   });
 }
+
+test('Mapillary can be omitted or replaced without changing catalog membership', (t) => {
+  const lifetime = new AbortController();
+  t.after(() => lifetime.abort());
+  const sources = fixtureSources([], []);
+  delete sources.mapillary;
+  const options = {
+    sources,
+    signal: lifetime.signal,
+    surface: fixtureSurface(lifetime.signal),
+  };
+  const catalog = createApplicationCatalog(options);
+  assert.equal(catalog.layers.length, 30);
+  assert.deepEqual(catalog.get('street-level').providerIds, []);
+  assert.equal(
+    catalogControlServices(catalog).streetLevelLayer,
+    catalog.get('street-level'),
+  );
+  assert.match(
+    catalog.get('street-level').getUIState().coverage.hint,
+    /No street-level imagery providers/,
+  );
+  const provider = fakeStreetLevelProvider({
+    id: 'example',
+    pickPrefix: 'example:',
+  });
+  const replacement = createApplicationCatalog({
+    ...options,
+    streetLevelProviders: [provider],
+  });
+  assert.deepEqual(replacement.get('street-level').providerIds, ['example']);
+  assert.deepEqual(replacement.metadata, catalog.metadata);
+  assert.equal(provider.calls.activate, 0, 'construction must not acquire');
+  assert.deepEqual(
+    createApplicationCatalog({
+      ...options,
+      sources: fixtureSources([], []),
+      streetLevelProviders: [],
+    }).get('street-level').providerIds,
+    [],
+  );
+  assert.throws(
+    () =>
+      createApplicationCatalog({
+        ...options,
+        sources: { ...sources, mapillary: {} },
+      }),
+    /Mapillary source/,
+  );
+});

src/app/data.js

@@ -13,6 +13,7 @@ export function createApplicationData({
   // Initialize data layer manager
   const dataManager = new LayerLifecycle(viewer, {
     allowQaRegistration,
+    getSourceAvailability: catalog?.getSourceAvailability,
   });
   defer(async () => {
     await dataManager.destroyAll();

src/app/embed.js

@@ -0,0 +1,305 @@
+/**
+ * Embed mode and views in the running app.
+ *
+ * With `?embed=1` the app shows only the globe: clean view, with the HUD,
+ * welcome and setup prompts hidden. A page that frames it changes what it
+ * shows by posting `{ type: 'gev:view', id, view }`; the app applies the view
+ * through its own actions and answers `{ type: 'gev:view-applied', id, ok,
+ * steps }`. It announces `{ type: 'gev:ready' }` once it can take views.
+ *
+ * Annotations in a share link are drawn once the link has been restored,
+ * embedded or not.
+ */
+
+import * as Cesium from 'cesium';
+import { announceNavigationAuthority } from '../navigationPolicy.js';
+import { annotationsFromParams, createView } from '../view/index.js';
+
+export const EMBED_VIEW_MESSAGE = 'gev:view';
+export const EMBED_APPLIED_MESSAGE = 'gev:view-applied';
+export const EMBED_READY_MESSAGE = 'gev:ready';
+
+const FOLLOW_LAYERS = {
+  aircraft: 'flights',
+  military_aircraft: 'military',
+  satellite: 'satellites',
+};
+const FOLLOW_ATTEMPTS = 20;
+const FOLLOW_RETRY_MS = 1000;
+const FLIGHT_SECONDS = 2;
+
+/**
+ * Whether this page shows the app embedded: `?embed=1` when another page
+ * frames it, or inline when a panel page loads the app into itself and sets
+ * `globalThis.GEV_EMBED_INLINE` first.
+ */
+export function isEmbedded(location = globalThis.location) {
+  return (
+    isEmbeddedInline() ||
+    new URLSearchParams(location?.search || '').get('embed') === '1'
+  );
+}
+
+/** Whether a panel page loaded the app into itself. */
+export function isEmbeddedInline() {
+  return globalThis.GEV_EMBED_INLINE === true;
+}
+
+// A panel keeps drawing at about this rate when its host stops animation
+// frames; see keepPanelRendering.
+const PANEL_FRAME_MS = 33;
+const MISSED_FRAMES_MS = 250;
+
+/** A render error's details, including the plain objects workers report. */
+function describeError(error) {
+  if (error instanceof Error)
+    return `${error.name}: ${error.message}\n${error.stack}`;
+  try {
+    return JSON.stringify(error, Object.getOwnPropertyNames(error ?? {}));
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * Keep the globe drawing in an inline panel. Some hosts report a panel on
+ * screen as hidden, which stops the browser's animation frames and with them
+ * Cesium's render loop; while frames stop arriving, draw from a timer.
+ * Returns a function that stops it.
+ */
+export function keepPanelRendering(
+  viewer,
+  { windowRef = globalThis.window, now = () => performance.now() } = {},
+) {
+  let lastFrame = now();
+  let frameRequest = null;
+  const onFrame = () => {
+    lastFrame = now();
+    frameRequest = windowRef.requestAnimationFrame(onFrame);
+  };
+  frameRequest = windowRef.requestAnimationFrame(onFrame);
+  // Cesium stops drawing after a render error, and so does the timer.
+  // Report the error in full: workers report plain objects, which Cesium
+  // prints as [object Object].
+  let failed = false;
+  const removeErrorListener = viewer.scene?.renderError?.addEventListener(
+    (_scene, error) => {
+      failed = true;
+      console.error(
+        "[God's Eye View panel] render error:",
+        describeError(error),
+      );
+    },
+  );
+  const timer = windowRef.setInterval(() => {
+    if (
+      failed ||
+      now() - lastFrame < MISSED_FRAMES_MS ||
+      viewer.isDestroyed?.()
+    )
+      return;
+    viewer.resize();
+    viewer.render();
+  }, PANEL_FRAME_MS);
+  return () => {
+    windowRef.clearInterval(timer);
+    windowRef.cancelAnimationFrame(frameRequest);
+    removeErrorListener?.();
+  };
+}
+
+const delay = (ms, signal) =>
+  new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+
+/** Fly the camera to a view's camera and resolve when the flight ends. */
+function flyTo(viewer, camera) {
+  announceNavigationAuthority('embed-view');
+  return new Promise((resolve) => {
+    viewer.camera.flyTo({
+      destination: Cesium.Cartesian3.fromDegrees(
+        camera.lon,
+        camera.lat,
+        camera.altitude_m,
+      ),
+      orientation: {
+        heading: Cesium.Math.toRadians(camera.heading_deg),
+        pitch: Cesium.Math.toRadians(camera.pitch_deg),
+        roll: 0,
+      },
+      duration: FLIGHT_SECONDS,
+      complete: () => resolve(true),
+      cancel: () => resolve(false),
+    });
+  });
+}
+
+/**
+ * Make the app show a view: style and map, exactly the view's layers,
+ * annotations, the camera, and the followed entity. Each step runs through the
+ * app's own actions (`run(name, args)`); a failed step is reported and the
+ * rest still run. Resolves to the steps and whether each succeeded.
+ */
+export async function applyView(
+  view,
+  { viewer, dataManager, run, signal, retryMs = FOLLOW_RETRY_MS },
+) {
+  const steps = [];
+  const act = async (name, args) => {
+    let result = null;
+    try {
+      result = await run(name, args);
+    } catch (error) {
+      result = { ok: false, error: error?.message || String(error) };
+    }
+    steps.push({
+      step: name,
+      ok: result?.ok !== false,
+      ...(result?.error ? { error: result.error } : {}),
+    });
+    return result;
+  };
+  if (view.style) await act('set_visual_style', { style: view.style });
+  if (view.map) await act('set_map_stack', { stack: view.map });
+  const wanted = new Set(view.layers);
+  for (const layer of dataManager.getAll()) {
+    if (layer.enabled && !wanted.has(layer.id))
+      await act('set_layer_visibility', { layerId: layer.id, enabled: false });
+  }
+  for (const layerId of view.layers) {
+    if (!dataManager.isEnabled(layerId))
+      await act('set_layer_visibility', { layerId, enabled: true });
+  }
+  if (!view.follow) await act('stop_tracking', {});
+  // Annotations go first: drawing them may frame the marks, and the view's
+  // own camera should have the last word.
+  await act('clear_annotations', {});
+  if (view.annotations.length)
+    await act('annotate_map', { annotations: [...view.annotations] });
+  if (!view.follow) {
+    steps.push({ step: 'camera', ok: await flyTo(viewer, view.camera) });
+    return steps;
+  }
+  // A followed entity owns the camera, and a camera flight would end the
+  // follow, so fly to the view only while the entity is not there yet. It
+  // appears once its layer has data; retry until then.
+  const layerId = FOLLOW_LAYERS[view.follow.kind];
+  const follow = async () => {
+    try {
+      return (
+        (await run('track_entity', { query: view.follow.id, layerId }))?.ok ===
+        true
+      );
+    } catch {
+      return false;
+    }
+  };
+  let followed = await follow();
+  if (!followed) {
+    steps.push({ step: 'camera', ok: await flyTo(viewer, view.camera) });
+    for (let attempt = 1; attempt < FOLLOW_ATTEMPTS && !followed; attempt++) {
+      if (signal?.aborted) break;
+      await delay(retryMs, signal);
+      followed = await follow();
+    }
+  }
+  steps.push({ step: 'follow', ok: followed });
+  if (followed && view.follow.cockpit)
+    await act('control_cockpit', { action: 'enter', targetLayer: layerId });
+  return steps;
+}
+
+/**
+ * Install embed mode when the page asks for it, and draw any annotations the
+ * opening link carries. Returns a function that removes the message handler.
+ */
+export function installViews({
+  shell,
+  viewer,
+  dataManager,
+  run,
+  signal,
+  location = globalThis.location,
+  windowRef = globalThis.window,
+}) {
+  const ready = Promise.resolve(shell.initialRestorePromise).catch(() => {});
+  const linked = annotationsFromParams(
+    new URLSearchParams(String(location?.hash || '').replace(/^#/, '')),
+  );
+  if (linked.length)
+    void ready.then(() => {
+      if (!signal?.aborted) void run('annotate_map', { annotations: linked });
+    });
+  if (!isEmbedded(location)) return () => {};
+
+  windowRef.document.body.classList.add('ui-embed');
+  shell.setCleanView?.(true);
+  const stopRendering = isEmbeddedInline()
+    ? keepPanelRendering(viewer, { windowRef })
+    : () => {};
+  // A framing page talks to the app across frames; an inline panel shares
+  // the page with it and talks through the page's own window.
+  const peer = isEmbeddedInline() ? windowRef : windowRef.parent;
+  // Answers go back only to the origin that asked. An inline panel posts to
+  // its own window, and a sandboxed framing page has no origin to name.
+  const post = (message, origin = '*') => {
+    if (peer && (peer !== windowRef || isEmbeddedInline()))
+      peer.postMessage(message, origin);
+  };
+  // Views apply one at a time, in the order they arrive.
+  let queue = ready;
+  const onMessage = (event) => {
+    if (event.source !== peer || event.data?.type !== EMBED_VIEW_MESSAGE)
+      return;
+    const { id = null } = event.data;
+    const replyOrigin =
+      isEmbeddedInline() || !event.origin || event.origin === 'null'
+        ? '*'
+        : event.origin;
+    let view;
+    try {
+      view = createView(event.data.view);
+    } catch (error) {
+      post(
+        {
+          type: EMBED_APPLIED_MESSAGE,
+          id,
+          ok: false,
+          error: error.message,
+        },
+        replyOrigin,
+      );
+      return;
+    }
+    queue = queue.then(async () => {
+      if (signal?.aborted) return;
+      const steps = await applyView(view, { viewer, dataManager, run, signal });
+      post(
+        {
+          type: EMBED_APPLIED_MESSAGE,
+          id,
+          ok: steps.every((step) => step.ok),
+          steps,
+        },
+        replyOrigin,
+      );
+    });
+  };
+  windowRef.addEventListener('message', onMessage);
+  void ready.then(() => {
+    if (!signal?.aborted) post({ type: EMBED_READY_MESSAGE });
+  });
+  return () => {
+    stopRendering();
+    windowRef.removeEventListener('message', onMessage);
+  };
+}

src/app/embed.test.mjs

@@ -0,0 +1,325 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  applyView,
+  installViews,
+  isEmbedded,
+  keepPanelRendering,
+} from './embed.js';
+import { createView } from '../view/index.js';
+
+const fakeViewer = () => {
+  const flights = [];
+  return {
+    flights,
+    camera: {
+      flyTo(options) {
+        flights.push(options);
+        options.complete();
+      },
+    },
+  };
+};
+const fakeLayers = (enabled) => ({
+  getAll: () =>
+    ['flights', 'earthquakes', 'ais-live-vessels'].map((id) => ({
+      id,
+      enabled: enabled.has(id),
+    })),
+  isEnabled: (id) => enabled.has(id),
+});
+const recorder = (answers = {}) => {
+  const calls = [];
+  const run = async (name, args) => {
+    calls.push([name, args]);
+    const answer = answers[name];
+    return typeof answer === 'function'
+      ? answer(calls)
+      : (answer ?? { ok: true });
+  };
+  return { calls, run };
+};
+
+test('embed mode is opt-in by query parameter', () => {
+  assert.equal(isEmbedded({ search: '?embed=1' }), true);
+  assert.equal(isEmbedded({ search: '?welcome=0' }), false);
+});
+
+test('a view is applied through the app actions in order', async () => {
+  const viewer = fakeViewer();
+  const { calls, run } = recorder();
+  const view = createView({
+    camera: { lat: 25, lon: 121, altitude_m: 300000, pitch_deg: -40 },
+    layers: ['ais-live-vessels'],
+    style: 'thermal',
+    map: 'osm',
+    annotations: [{ type: 'pin', target: 'Taipei 101' }],
+  });
+  const steps = await applyView(view, {
+    viewer,
+    dataManager: fakeLayers(new Set(['earthquakes'])),
+    run,
+  });
+  assert.deepEqual(
+    calls.map(([name, args]) => [
+      name,
+      args.layerId ?? args.style ?? args.stack ?? null,
+      args.enabled ?? null,
+    ]),
+    [
+      ['set_visual_style', 'thermal', null],
+      ['set_map_stack', 'osm', null],
+      ['set_layer_visibility', 'earthquakes', false],
+      ['set_layer_visibility', 'ais-live-vessels', true],
+      ['stop_tracking', null, null],
+      ['clear_annotations', null, null],
+      ['annotate_map', null, null],
+    ],
+  );
+  assert.equal(viewer.flights.length, 1);
+  assert.ok(steps.every((step) => step.ok));
+  assert.ok(steps.some((step) => step.step === 'camera'));
+});
+
+test('a followed entity is retried until its layer has it', async () => {
+  let tries = 0;
+  const { run } = recorder({
+    track_entity: () => ({ ok: ++tries >= 3 }),
+  });
+  const view = createView({
+    camera: { lat: 0, lon: 0 },
+    follow: { kind: 'aircraft', id: 'abc123' },
+  });
+  const steps = await applyView(view, {
+    viewer: fakeViewer(),
+    dataManager: fakeLayers(new Set()),
+    run,
+    retryMs: 1,
+  });
+  assert.equal(tries, 3);
+  assert.deepEqual(steps.at(-1), { step: 'follow', ok: true });
+});
+
+test('an embedded page takes views only from its parent and answers it', async () => {
+  const posted = [];
+  const targets = [];
+  const parent = {
+    postMessage: (message, target) => {
+      posted.push(message);
+      targets.push(target);
+    },
+  };
+  const windowRef = new EventTarget();
+  windowRef.parent = parent;
+  windowRef.document = { body: { classList: new Set() } };
+  windowRef.document.body.classList.add = Set.prototype.add;
+  const shell = {
+    initialRestorePromise: Promise.resolve(),
+    clean: null,
+    setCleanView(value) {
+      this.clean = value;
+    },
+  };
+  const { calls, run } = recorder();
+  const remove = installViews({
+    shell,
+    viewer: fakeViewer(),
+    dataManager: fakeLayers(new Set()),
+    run,
+    location: { search: '?embed=1', hash: '' },
+    windowRef,
+  });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(shell.clean, true);
+  assert.deepEqual(posted, [{ type: 'gev:ready' }]);
+  const send = (source, data, origin = 'https://host.example') => {
+    const event = new Event('message');
+    Object.assign(event, { source, data, origin });
+    windowRef.dispatchEvent(event);
+  };
+  send({}, { type: 'gev:view', id: 1, view: { camera: { lat: 1, lon: 2 } } });
+  send(parent, { type: 'gev:view', id: 2, view: { camera: {} } });
+  send(parent, {
+    type: 'gev:view',
+    id: 3,
+    view: { camera: { lat: 1, lon: 2 }, layers: ['flights'] },
+  });
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  assert.deepEqual(posted[1], {
+    type: 'gev:view-applied',
+    id: 2,
+    ok: false,
+    error: 'A view needs a camera lat and lon',
+  });
+  assert.equal(posted[2].id, 3);
+  assert.equal(posted[2].ok, true);
+  assert.ok(
+    calls.some(
+      ([name, args]) =>
+        name === 'set_layer_visibility' && args.layerId === 'flights',
+    ),
+  );
+  assert.equal(posted.filter((message) => message.id === 1).length, 0);
+  // Ready names no data and goes to any parent; answers go only to the
+  // origin that asked.
+  assert.deepEqual(targets, [
+    '*',
+    'https://host.example',
+    'https://host.example',
+  ]);
+  remove();
+});
+
+test('an app loaded inline into a panel page talks through its own window', async () => {
+  const posted = [];
+  const windowRef = new EventTarget();
+  windowRef.parent = windowRef;
+  windowRef.postMessage = (message) => posted.push(message);
+  windowRef.document = { body: { classList: new Set() } };
+  windowRef.document.body.classList.add = Set.prototype.add;
+  Object.assign(windowRef, {
+    requestAnimationFrame: () => 1,
+    cancelAnimationFrame() {},
+    setInterval: () => 1,
+    clearInterval() {},
+  });
+  globalThis.GEV_EMBED_INLINE = true;
+  try {
+    assert.equal(isEmbedded({ search: '' }), true);
+    const remove = installViews({
+      shell: { initialRestorePromise: Promise.resolve() },
+      viewer: fakeViewer(),
+      dataManager: fakeLayers(new Set()),
+      run: recorder().run,
+      location: { search: '', hash: '' },
+      windowRef,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.deepEqual(posted, [{ type: 'gev:ready' }]);
+    const event = new Event('message');
+    Object.assign(event, {
+      source: windowRef,
+      data: { type: 'gev:view', id: 7, view: { camera: { lat: 1, lon: 2 } } },
+    });
+    windowRef.dispatchEvent(event);
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.equal(posted[1].id, 7);
+    assert.equal(posted[1].ok, true);
+    remove();
+  } finally {
+    delete globalThis.GEV_EMBED_INLINE;
+  }
+});
+
+test('annotations in a link are drawn after it restores, embedded or not', async () => {
+  const { calls, run } = recorder();
+  const an = encodeURIComponent(
+    JSON.stringify([{ type: 'pin', target: 'Austin' }]),
+  );
+  installViews({
+    shell: { initialRestorePromise: Promise.resolve() },
+    viewer: fakeViewer(),
+    dataManager: fakeLayers(new Set()),
+    run,
+    location: { search: '', hash: `#v=2&lat=1&lon=2&an=${an}` },
+    windowRef: new EventTarget(),
+  });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(calls, [
+    ['annotate_map', { annotations: [{ type: 'pin', target: 'Austin' }] }],
+  ]);
+});
+
+test('a panel keeps drawing from a timer while animation frames stop', () => {
+  let clock = 0;
+  let tick = null;
+  let frame = null;
+  const windowRef = {
+    requestAnimationFrame: (fn) => ((frame = fn), 1),
+    cancelAnimationFrame: () => (frame = null),
+    setInterval: (fn) => ((tick = fn), 1),
+    clearInterval: () => (tick = null),
+  };
+  const drawn = [];
+  const viewer = {
+    resize: () => drawn.push('resize'),
+    render: () => drawn.push('render'),
+  };
+  const stop = keepPanelRendering(viewer, { windowRef, now: () => clock });
+  // Frames arrive: the render loop draws, so the timer does nothing.
+  clock = 100;
+  frame();
+  tick();
+  assert.deepEqual(drawn, []);
+  // Frames stop, as in a panel its host reports hidden: the timer draws.
+  clock = 400;
+  tick();
+  assert.deepEqual(drawn, ['resize', 'render']);
+  stop();
+  assert.equal(tick, null);
+  assert.equal(frame, null);
+});
+
+test('a panel reports a render error in full and stops drawing', () => {
+  let listener = null;
+  let tick = null;
+  const windowRef = {
+    requestAnimationFrame: () => 1,
+    cancelAnimationFrame() {},
+    setInterval: (fn) => ((tick = fn), 1),
+    clearInterval() {},
+  };
+  const drawn = [];
+  const viewer = {
+    resize() {},
+    render: () => drawn.push('render'),
+    scene: {
+      renderError: {
+        addEventListener: (fn) => ((listener = fn), () => (listener = null)),
+      },
+    },
+  };
+  const logged = [];
+  const original = console.error;
+  console.error = (...args) => logged.push(args.join(' '));
+  try {
+    let clock = 0;
+    const stop = keepPanelRendering(viewer, { windowRef, now: () => clock });
+    listener(viewer.scene, { name: 'RuntimeError', message: 'worker failed' });
+    assert.match(logged[0], /render error: .*"message":"worker failed"/);
+    clock = 1000;
+    tick();
+    assert.deepEqual(drawn, []);
+    stop();
+    assert.equal(listener, null);
+  } finally {
+    console.error = original;
+  }
+});
+
+test('a followed aircraft owns the camera, and cockpit view is entered after it', async () => {
+  const viewer = fakeViewer();
+  const { calls, run } = recorder();
+  const steps = await applyView(
+    createView({
+      camera: { lat: 32.7, lon: -117.2 },
+      follow: { kind: 'military_aircraft', id: 'AE1234', cockpit: true },
+    }),
+    { viewer, dataManager: fakeLayers(new Set()), run, retryMs: 0 },
+  );
+  // Following worked at once, so no camera flight ended it.
+  assert.equal(viewer.flights.length, 0);
+  assert.deepEqual(calls.slice(-2), [
+    ['track_entity', { query: 'ae1234', layerId: 'military' }],
+    ['control_cockpit', { action: 'enter', targetLayer: 'military' }],
+  ]);
+  assert.ok(steps.every((step) => step.ok));
+  assert.throws(
+    () =>
+      createView({
+        camera: { lat: 0, lon: 0 },
+        follow: { kind: 'satellite', id: '25544', cockpit: true },
+      }),
+    /no cockpit view/,
+  );
+});

src/app/globePanelRuntime.js

@@ -0,0 +1,662 @@
+/**
+ * The God's Eye View panel's script, run inside the panel page a host shows.
+ * It is sent as source text (see src/tools/globePanel.js), so it must not use
+ * imports or anything outside the function.
+ *
+ * The page lives on the host's site, and hosts may refuse other addresses,
+ * such as a server on the user's machine. So the panel never requests the
+ * app's server itself: every request for the app's own paths goes to the
+ * panel's MCP server as a call to `config.toolName`, which requests the path
+ * from the app's server. The app's built page, scripts, styles, images and
+ * data all arrive that way; map imagery from providers loads directly.
+ */
+export function panelRuntime(config) {
+  const status = document.getElementById('status');
+  const open = document.getElementById('open');
+  const expand = document.getElementById('expand');
+  const say = (text) => {
+    if (status.isConnected) status.textContent = text;
+  };
+  let blocked = null;
+  document.addEventListener('securitypolicyviolation', (event) => {
+    blocked = `${event.effectiveDirective} blocked ${event.blockedURI || 'a resource'}`;
+  });
+
+  // JSON-RPC with the host.
+  let nextId = 1;
+  const pending = new Map();
+  const send = (message) =>
+    window.parent.postMessage({ jsonrpc: '2.0', ...message }, '*');
+  const request = (method, params) =>
+    new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, { resolve, reject });
+      send({ id, method, params });
+    });
+  const notify = (method, params) => send({ method, params });
+
+  // Requests to the app's server, through the MCP server.
+  const MAX_CALLS = 6;
+  let calls = 0;
+  const waiting = [];
+  async function callTool(args) {
+    if (calls >= MAX_CALLS) await new Promise((go) => waiting.push(go));
+    calls += 1;
+    try {
+      const result = await request('tools/call', {
+        name: config.toolName,
+        // The server refuses the panel's requests without its key.
+        arguments: { ...args, key: config.panelKey },
+      });
+      if (result?.isError || !result?.structuredContent)
+        throw new Error(result?.content?.[0]?.text || 'The request failed');
+      return result.structuredContent;
+    } finally {
+      calls -= 1;
+      waiting.shift()?.();
+    }
+  }
+  const toBase64 = (bytes) => {
+    let binary = '';
+    for (let start = 0; start < bytes.length; start += 0x8000)
+      binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
+    return btoa(binary);
+  };
+  const fromBase64 = (text) =>
+    Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+  async function bodyBytes(body) {
+    if (body == null) return null;
+    if (typeof body === 'string') return new TextEncoder().encode(body);
+    if (body instanceof ArrayBuffer) return new Uint8Array(body);
+    if (ArrayBuffer.isView(body))
+      return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    return new Uint8Array(await new Response(body).arrayBuffer());
+  }
+  const NULL_BODY = new Set([101, 204, 205, 304]);
+  const held = new Map();
+
+  /** Request a path on the app's server; resolves to a Response. */
+  function appFetch(path, init = {}) {
+    const method = (init.method || 'GET').toUpperCase();
+    // Built files never change while the panel runs, so each loads once.
+    const shared = method === 'GET' && path.startsWith(config.panelBase);
+    if (shared && held.has(path)) return held.get(path).then(respond);
+    const loading = (async () => {
+      const headers = {};
+      new Headers(init.headers || {}).forEach((value, name) => {
+        headers[name] = value;
+      });
+      const bytes = await bodyBytes(init.body);
+      let part = await callTool({
+        path,
+        method,
+        headers,
+        ...(bytes ? { body: toBase64(bytes) } : {}),
+      });
+      const parts = [fromBase64(part.body)];
+      while (part.nextOffset !== undefined) {
+        if (init.signal?.aborted) break;
+        part = await callTool({ id: part.id, offset: part.nextOffset });
+        parts.push(fromBase64(part.body));
+      }
+      let body = new Blob(parts);
+      if (part.encoding === 'gzip')
+        body = await new Response(
+          body.stream().pipeThrough(new DecompressionStream('gzip')),
+        ).blob();
+      return {
+        body: await body.arrayBuffer(),
+        status: part.status,
+        statusText: part.statusText,
+        headers: part.headers,
+      };
+    })();
+    if (shared) {
+      held.set(path, loading);
+      loading.catch(() => held.delete(path));
+    }
+    const result = loading.then(respond);
+    if (!init.signal) return result;
+    return Promise.race([
+      result,
+      new Promise((_, reject) => {
+        const abort = () =>
+          reject(new DOMException('The request was aborted', 'AbortError'));
+        if (init.signal.aborted) abort();
+        init.signal.addEventListener('abort', abort, { once: true });
+      }),
+    ]);
+  }
+  function respond({ body, status, statusText, headers }) {
+    return new Response(NULL_BODY.has(status) ? null : body.slice(0), {
+      status,
+      statusText,
+      headers,
+    });
+  }
+
+  // The app's own paths: relative ones, absolute ones on this page's site
+  // (matched by scheme and host, since a host may use its own scheme), and
+  // ones under the app's address in the page, an https address for code
+  // that needs one (`config.appBaseUrl`).
+  const page = new URL(document.baseURI);
+  const appOrigin = new URL(config.appBaseUrl).origin;
+  function appPath(value) {
+    let url;
+    try {
+      url = new URL(String(value), document.baseURI);
+    } catch {
+      return null;
+    }
+    const own =
+      url.origin === appOrigin ||
+      (url.protocol === page.protocol && url.host === page.host);
+    return own ? url.pathname + url.search : null;
+  }
+  const fileUrls = new Map();
+  /**
+   * A data: URL holding an app file, for elements that load by URL. Hosts
+   * allow data: images where some refuse blob: ones. Files of the panel
+   * build never change and are kept; others, such as live camera frames
+   * that change address on every refresh, are not.
+   */
+  function appFileUrl(path) {
+    if (fileUrls.has(path)) return fileUrls.get(path);
+    const loading = appFetch(path)
+      .then((response) => response.blob())
+      .then(
+        (blob) =>
+          new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onload = () => resolve(reader.result);
+            reader.onerror = () => reject(reader.error);
+            reader.readAsDataURL(blob);
+          }),
+      );
+    if (path.startsWith(config.panelBase)) {
+      fileUrls.set(path, loading);
+      loading.catch(() => fileUrls.delete(path));
+    }
+    return loading;
+  }
+
+  function installRequests() {
+    const nativeFetch = window.fetch.bind(window);
+    window.fetch = async (input, init = {}) => {
+      const isRequest = input instanceof Request;
+      const path = appPath(isRequest ? input.url : input);
+      if (path === null) return nativeFetch(input, init);
+      if (!isRequest) return appFetch(path, init);
+      return appFetch(path, {
+        method: init.method || input.method,
+        headers: init.headers || input.headers,
+        body:
+          init.body ??
+          (['GET', 'HEAD'].includes(input.method)
+            ? undefined
+            : await input.arrayBuffer()),
+        signal: init.signal || input.signal,
+      });
+    };
+
+    // XMLHttpRequest for app paths: answered from appFetch, with the
+    // instance's state replaced, and the usual events dispatched.
+    const xhr = XMLHttpRequest.prototype;
+    const nativeOpen = xhr.open;
+    const nativeSend = xhr.send;
+    const nativeHeader = xhr.setRequestHeader;
+    const nativeAbort = xhr.abort;
+    xhr.open = function (method, url, ...rest) {
+      const path = appPath(url);
+      if (path === null) {
+        this.__gev = null;
+        return nativeOpen.call(this, method, url, ...rest);
+      }
+      this.__gev = { method, path, headers: {}, controller: null };
+      setState(this, { readyState: 1 });
+      this.dispatchEvent(new Event('readystatechange'));
+    };
+    xhr.setRequestHeader = function (name, value) {
+      if (!this.__gev) return nativeHeader.call(this, name, value);
+      this.__gev.headers[name] = value;
+    };
+    xhr.abort = function () {
+      if (!this.__gev) return nativeAbort.call(this);
+      this.__gev.controller?.abort();
+    };
+    xhr.send = function (body) {
+      const state = this.__gev;
+      if (!state) return nativeSend.call(this, body);
+      state.controller = new AbortController();
+      appFetch(state.path, {
+        method: state.method,
+        headers: state.headers,
+        body,
+        signal: state.controller.signal,
+      })
+        .then(async (response) => {
+          const type = this.responseType;
+          const value =
+            type === 'arraybuffer'
+              ? await response.arrayBuffer()
+              : type === 'blob'
+                ? await response.blob()
+                : await response.text();
+          const text = typeof value === 'string' ? value : null;
+          let parsed = value;
+          if (type === 'json') {
+            try {
+              parsed = JSON.parse(text);
+            } catch {
+              parsed = null;
+            }
+          } else if (type === 'document')
+            parsed = new DOMParser().parseFromString(text, 'text/html');
+          const headers = [...response.headers]
+            .map(([name, val]) => `${name}: ${val}`)
+            .join('\r\n');
+          setState(this, {
+            readyState: 4,
+            status: response.status,
+            statusText: response.statusText,
+            response: parsed,
+            responseText: type === '' || type === 'text' ? text : '',
+            responseURL: new URL(state.path, document.baseURI).href,
+            getAllResponseHeaders: () => headers,
+            getResponseHeader: (name) => response.headers.get(name),
+          });
+          for (const name of ['readystatechange', 'load', 'loadend'])
+            this.dispatchEvent(
+              name === 'readystatechange'
+                ? new Event(name)
+                : new ProgressEvent(name),
+            );
+        })
+        .catch((error) => {
+          setState(this, { readyState: 4, status: 0 });
+          const name = error?.name === 'AbortError' ? 'abort' : 'error';
+          for (const event of ['readystatechange', name, 'loadend'])
+            this.dispatchEvent(
+              event === 'readystatechange'
+                ? new Event(event)
+                : new ProgressEvent(event),
+            );
+        });
+    };
+    function setState(target, values) {
+      for (const [name, value] of Object.entries(values))
+        Object.defineProperty(target, name, {
+          configurable: true,
+          ...(typeof value === 'function' ? { value } : { get: () => value }),
+        });
+    }
+
+    const nativeBeacon = navigator.sendBeacon?.bind(navigator);
+    if (nativeBeacon)
+      navigator.sendBeacon = (url, data) => {
+        const path = appPath(url);
+        if (path === null) return nativeBeacon(url, data);
+        appFetch(path, { method: 'POST', body: data }).catch(() => {});
+        return true;
+      };
+
+    // Images name app files by URL; give them the file as a data: URL.
+    const image = Object.getOwnPropertyDescriptor(
+      HTMLImageElement.prototype,
+      'src',
+    );
+    Object.defineProperty(HTMLImageElement.prototype, 'src', {
+      ...image,
+      set(value) {
+        const path = appPath(value);
+        if (path === null) return image.set.call(this, value);
+        appFileUrl(path).then(
+          (url) => image.set.call(this, url),
+          () => this.dispatchEvent(new Event('error')),
+        );
+      },
+    });
+
+    // Workers on the app's server start from a small worker here that is
+    // handed the script once it has loaded; messages wait until then.
+    const NativeWorker = window.Worker;
+    const BOOT =
+      'const early=[];let ready=false;' +
+      "addEventListener('message',e=>{if(e.data&&e.data.__gevScript){" +
+      'const go=()=>{ready=true;for(const d of early)dispatchEvent(new MessageEvent("message",{data:d}))};' +
+      'if(e.data.module)import(e.data.__gevScript).then(go);else{importScripts(e.data.__gevScript);go()}' +
+      'e.stopImmediatePropagation();return}' +
+      'if(!ready){early.push(e.data);e.stopImmediatePropagation()}});';
+    window.Worker = function Worker(url, options) {
+      const path = appPath(url);
+      if (path === null || String(url).startsWith('blob:'))
+        return new NativeWorker(url, options);
+      const worker = new NativeWorker(
+        URL.createObjectURL(new Blob([BOOT], { type: 'text/javascript' })),
+        options,
+      );
+      appFetch(path)
+        .then((response) => response.blob())
+        .then((blob) => URL.createObjectURL(blob))
+        .then((script) =>
+          worker.postMessage({
+            __gevScript: script,
+            module: options?.type === 'module',
+          }),
+        );
+      return worker;
+    };
+    window.Worker.prototype = NativeWorker.prototype;
+
+    // Some hosts drop the GPU contents of a panel's 2D canvases while they
+    // consider the panel off screen, and the overlays then cover the globe
+    // in black. Keep 2D canvases in memory instead, which hosts do not drop.
+    const getContext = HTMLCanvasElement.prototype.getContext;
+    HTMLCanvasElement.prototype.getContext = function (type, options) {
+      return type === '2d'
+        ? getContext.call(this, type, { ...options, willReadFrequently: true })
+        : getContext.call(this, type, options);
+    };
+
+    // Markup the app adds as HTML text would request its images from this
+    // page's site at once; hold their addresses until the files are here.
+    const htmlWithHeldImages = (html) =>
+      String(html).replace(
+        /(<(?:img|source)\b[^>]*?\s)src=(["'])([^"']*)\2/gi,
+        (tag, before, quote, value) =>
+          appPath(value) === null
+            ? tag
+            : `${before}data-gev-src=${quote}${value}${quote}`,
+      );
+    const fillHeldImages = (root) => {
+      for (const element of root?.querySelectorAll?.('[data-gev-src]') ?? []) {
+        const path = appPath(element.getAttribute('data-gev-src'));
+        element.removeAttribute('data-gev-src');
+        appFileUrl(path).then((url) => element.setAttribute('src', url));
+      }
+    };
+    const innerHtml = Object.getOwnPropertyDescriptor(
+      Element.prototype,
+      'innerHTML',
+    );
+    Object.defineProperty(Element.prototype, 'innerHTML', {
+      ...innerHtml,
+      set(value) {
+        innerHtml.set.call(this, htmlWithHeldImages(value));
+        fillHeldImages(this);
+      },
+    });
+    const insertHtml = Element.prototype.insertAdjacentHTML;
+    Element.prototype.insertAdjacentHTML = function (position, html) {
+      insertHtml.call(this, position, htmlWithHeldImages(html));
+      fillHeldImages(this.parentNode ?? this);
+    };
+
+    // Markup and styles the app adds later name app files too.
+    new MutationObserver((records) => {
+      for (const record of records)
+        for (const node of record.addedNodes) {
+          if (node.nodeType !== 1) continue;
+          if (node.nodeName === 'STYLE') void inlineStyleUrls(node);
+          for (const element of [node, ...node.querySelectorAll('img[src]')]) {
+            if (element.nodeName !== 'IMG') continue;
+            const path = appPath(element.getAttribute('src'));
+            if (path !== null)
+              appFileUrl(path).then((url) => element.setAttribute('src', url));
+          }
+        }
+    }).observe(document.documentElement, { childList: true, subtree: true });
+  }
+
+  /** Replace url() references to app files in CSS with data: URLs. */
+  async function cssWithFiles(text, baseUrl) {
+    const found = new Map();
+    for (const match of text.matchAll(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g)) {
+      const reference = match[2];
+      if (/^(data|blob):/.test(reference)) continue;
+      const path = appPath(new URL(reference, baseUrl).href);
+      if (path !== null && !found.has(reference))
+        found.set(
+          reference,
+          appFileUrl(path).catch(() => null),
+        );
+    }
+    let result = text;
+    for (const [reference, loading] of found) {
+      const url = await loading;
+      if (url) result = result.split(reference).join(url);
+    }
+    return result;
+  }
+  async function inlineStyleUrls(style) {
+    if (!/url\(/.test(style.textContent)) return;
+    style.textContent = await cssWithFiles(style.textContent, document.baseURI);
+  }
+
+  async function addStylesheet(href) {
+    const path = appPath(href);
+    const style = document.createElement('style');
+    document.head.appendChild(style);
+    if (path === null) {
+      const link = document.createElement('link');
+      link.rel = 'stylesheet';
+      link.href = href;
+      style.replaceWith(link);
+      return;
+    }
+    const text = await (await appFetch(path)).text();
+    style.textContent = await cssWithFiles(
+      text,
+      new URL(path, document.baseURI).href,
+    );
+  }
+
+  function runScript(text, type) {
+    const script = document.createElement('script');
+    if (type) script.type = type;
+    script.textContent = text;
+    document.body.appendChild(script);
+  }
+
+  /**
+   * Load God's Eye View into this page from the app's panel build, in
+   * inline embed mode, starting at the first view as its link would.
+   */
+  async function startApp(url, view) {
+    window.GEV_EMBED_INLINE = true;
+    window.GEV_APP_BASE_URL = config.appBaseUrl;
+    try {
+      history.replaceState(
+        null,
+        '',
+        location.href.split('#')[0] + new URL(url).hash,
+      );
+      // The app restores this view from its link, following included, so
+      // it needs applying again only for what links cannot carry: cockpit.
+      if (queued === view && !view.follow?.cockpit) queued = null;
+    } catch {
+      // The view still arrives once the app is ready.
+    }
+    installRequests();
+    const response = await appFetch(config.panelBase);
+    if (!response.ok)
+      throw new Error(
+        response.status === 404
+          ? 'the app has no panel build (npm run build:panel)'
+          : `the app answered ${response.status}`,
+      );
+    const built = new DOMParser().parseFromString(
+      await response.text(),
+      'text/html',
+    );
+    window.CESIUM_BASE_URL = `${config.panelBase}cesium/`;
+    const [prelude] = await Promise.all([
+      appFetch(config.panelBase + config.workerPreludePath).then((r) =>
+        r.text(),
+      ),
+      ...[...built.head.querySelectorAll('link[rel="stylesheet"]')].map(
+        (link) => addStylesheet(link.getAttribute('href')),
+      ),
+    ]);
+    // Cesium's script sets CESIUM_WORKERS, its workers as one script it
+    // starts from memory. Workers request files themselves, which this page
+    // cannot answer, so the prelude, holding those files, runs ahead of it.
+    let workers;
+    Object.defineProperty(window, 'CESIUM_WORKERS', {
+      configurable: true,
+      get: () => workers,
+      set: (script) => {
+        workers = prelude + script;
+      },
+    });
+    // Images in the markup load their files once added; give them the
+    // files instead of letting them request this page's site.
+    const images = [];
+    for (const image of built.body.querySelectorAll('img[src]')) {
+      const path = appPath(image.getAttribute('src'));
+      if (path === null) continue;
+      image.removeAttribute('src');
+      images.push([image, path]);
+    }
+    for (const node of [...built.body.childNodes]) {
+      if (node.nodeName !== 'SCRIPT')
+        document.body.insertBefore(document.adoptNode(node), status);
+    }
+    for (const [image, path] of images)
+      appFileUrl(path).then((url) => image.setAttribute('src', url));
+    const scripts = await Promise.all(
+      [...built.querySelectorAll('script')].map(async (script) => ({
+        type: script.type,
+        text: script.getAttribute('src')
+          ? await (await appFetch(appPath(script.getAttribute('src')))).text()
+          : script.textContent,
+      })),
+    );
+    for (const { type, text } of scripts) runScript(text, type);
+    // Browsers cap live 3D contexts across pages and take one back when
+    // there are too many; say so rather than show no map.
+    document.addEventListener(
+      'webglcontextlost',
+      () => {
+        const notice = document.createElement('div');
+        notice.id = 'status';
+        notice.textContent =
+          "This panel lost its 3D graphics, likely because other God's Eye " +
+          "View panels in this conversation hold them. Use Open in God's " +
+          'Eye View above, or show it in a new conversation.';
+        document.body.appendChild(notice);
+      },
+      { capture: true, once: true },
+    );
+  }
+
+  // Tool results: the first view starts the app, later ones move it.
+  let started = false;
+  let ready = false;
+  let queued = null;
+  let currentUrl = null;
+  const postView = (view) =>
+    window.postMessage({ type: 'gev:view', id: nextId++, view }, '*');
+  function show(result) {
+    const data = result?.structuredContent;
+    const view = data?.view;
+    const url = data?.url || view?.url;
+    if (!view || !url) return;
+    currentUrl = url;
+    open.hidden = false;
+    if (ready) return postView(view);
+    queued = view;
+    if (started) return;
+    started = true;
+    say("Loading God's Eye View…");
+    startApp(url, view).catch((error) =>
+      say(`God's Eye View could not load here: ${error?.message || error}.`),
+    );
+    setTimeout(() => {
+      if (!ready)
+        say(
+          "God's Eye View did not load here" +
+            (blocked ? ` (${blocked})` : '') +
+            ". Use Open in God's Eye View above.",
+        );
+    }, config.loadTimeoutMs);
+  }
+
+  window.addEventListener('message', (event) => {
+    const message = event.data;
+    if (event.source === window) {
+      if (message?.type === 'gev:ready') {
+        ready = true;
+        status.remove();
+        if (queued) postView(queued);
+        queued = null;
+      }
+      return;
+    }
+    if (event.source !== window.parent || message?.jsonrpc !== '2.0') return;
+    if (
+      message.id !== undefined &&
+      pending.has(message.id) &&
+      !message.method
+    ) {
+      const { resolve, reject } = pending.get(message.id);
+      pending.delete(message.id);
+      if (message.error) reject(message.error);
+      else resolve(message.result);
+      return;
+    }
+    if (message.method === 'ui/notifications/tool-result') show(message.params);
+    if (message.method === 'ui/notifications/host-context-changed')
+      showDisplayMode(message.params);
+  });
+
+  // Fullscreen, where the host offers it, gives the globe the room.
+  let displayMode = 'inline';
+  const showDisplayMode = (context) => {
+    if (context?.displayMode) displayMode = context.displayMode;
+    if (context?.availableDisplayModes)
+      expand.hidden = !context.availableDisplayModes.includes('fullscreen');
+    expand.textContent = displayMode === 'fullscreen' ? 'Collapse' : 'Expand';
+  };
+  expand.addEventListener('click', () => {
+    request('ui/request-display-mode', {
+      mode: displayMode === 'fullscreen' ? 'inline' : 'fullscreen',
+    }).then(
+      (result) => showDisplayMode({ displayMode: result?.mode }),
+      () => {},
+    );
+  });
+
+  open.addEventListener('click', () => {
+    if (!currentUrl) return;
+    request('ui/open-link', { url: currentUrl }).catch(() =>
+      window.open(currentUrl, '_blank', 'noopener'),
+    );
+  });
+
+  // The handshake the MCP Apps SDK's App.connect performs: hosts validate
+  // these parameters, and keep a view hidden until it is initialized.
+  request('ui/initialize', {
+    appCapabilities: { availableDisplayModes: ['inline', 'fullscreen'] },
+    appInfo: {
+      name: 'gods-eye-view',
+      title: "God's Eye View",
+      version: '1.0.0',
+    },
+    protocolVersion: config.protocolVersion,
+  }).then(
+    (result) => {
+      showDisplayMode(result?.hostContext);
+      send({ method: 'ui/notifications/initialized' });
+      notify('ui/notifications/size-changed', {
+        width: document.body.clientWidth,
+        height: config.panelHeight,
+      });
+    },
+    (error) =>
+      say(
+        "This client did not accept the God's Eye View panel" +
+          (error?.message ? `: ${error.message}` : '.'),
+      ),
+  );
+}

src/app/layers/directions.js

@@ -1,12 +1,6 @@
 import { createApplicationDirectionsLayer } from '../../data/directions.js';
 
-/**
- * Construct one Directions layer using the application scene owners.
- *
- * It takes no data source: a route is fetched from `/api/route` when the
- * operator places both endpoints, so there is nothing to supply up front.
- * @returns {object} A fresh layer instance for this catalog.
- */
-export function createApplicationDirections() {
-  return createApplicationDirectionsLayer();
+/** Construct Directions with application scene owners and an explicit route source. */
+export function createApplicationDirections({ source }) {
+  return createApplicationDirectionsLayer({ source });
 }

src/app/layers/recentImagery.js

@@ -3,17 +3,17 @@ import { createRecentImageryRenderer } from '../../layers/recentImagery/renderin
 import { createThumbnailLoader } from '../../layers/recentImagery/thumbnails.js';
 import { governorRequestRender } from '../../renderGovernor.js';
 
-/**
- * Construct the Recent Imagery layer with the real GIBS renderer and the
- * browser thumbnail loader. It takes no data source: the catalog is NASA
- * CMR and the tiles are GIBS, both browser-direct and keyless.
- * @returns {object} A fresh layer instance for this catalog.
- */
-export function createApplicationRecentImagery() {
+/** Construct imagery presentation over one explicitly supplied acquisition source. */
+export function createApplicationRecentImagery({ source }) {
   return createRecentImageryLayer({
+    catalog: { searchHls: (...args) => source.searchHls(...args) },
     renderer: createRecentImageryRenderer({
       requestRender: governorRequestRender,
+      tileTemplate: (...args) => source.getTileTemplate(...args),
+      credit: source.credit || source.label || 'Imagery',
+    }),
+    thumbnails: createThumbnailLoader({
+      requestThumbnail: (...args) => source.getThumbnail(...args),
     }),
-    thumbnails: createThumbnailLoader(),
   });
 }

src/app/layers/streetLevel.js

@@ -0,0 +1,32 @@
+import { createStreetLevelLayer } from '../../layers/streetLevel/index.js';
+import { createMapillaryProvider } from '../../layers/streetLevel/providers/mapillary/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 render from '../../renderGovernor.js';
+
+/**
+ * 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.
+ */
+export function createApplicationStreetLevel({
+  surface,
+  sources = {},
+  providers = sources.mapillary == null
+    ? []
+    : [createMapillaryProvider({ source: sources.mapillary })],
+}) {
+  return createStreetLevelLayer({
+    providers,
+    services: {
+      sprites,
+      picking,
+      input,
+      render,
+      ground: surface?.groundFloor ?? null,
+      meshFloor: surface?.meshFloor ?? null,
+      terrain: surface?.terrain ?? null,
+    },
+  });
+}

src/app/layers/streetLevel.test.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createApplicationStreetLevel } from './streetLevel.js';
+import { fakeStreetLevelProvider } from '../../testSupport/streetLevelFakes.mjs';
+
+test('explicit providers replace the default source and an empty list removes it', () => {
+  const sources = { mapillary: {} };
+  const provider = fakeStreetLevelProvider({
+    id: 'example',
+    pickPrefix: 'example:',
+  });
+  const layer = createApplicationStreetLevel({
+    sources,
+    providers: [provider],
+  });
+  assert.deepEqual(layer.providerIds, ['example']);
+  assert.deepEqual(
+    createApplicationStreetLevel({ sources, providers: [] }).providerIds,
+    [],
+  );
+  assert.throws(
+    () => createApplicationStreetLevel({ sources }),
+    /Mapillary source/,
+  );
+  assert.throws(
+    () => createApplicationStreetLevel({ providers: null }),
+    /array/,
+  );
+});

src/app/scene.js

@@ -20,6 +20,7 @@ import { t } from '../i18n/index.js';
 export async function createApplicationScene({
   requestServices,
   googleApiKey,
+  googleTokens = null,
   cesiumToken,
   credits,
   MapController = MapStackController,
@@ -60,11 +61,12 @@ export async function createApplicationScene({
   registerDataCredits(viewer, credits);
   configureCreditKeyboardAccess(document);
   loaderStatus.textContent =
-    googleApiKey || cesiumToken
+    googleApiKey || googleTokens || cesiumToken
       ? t('shell.loading.status.tilesGoogle')
       : t('shell.loading.status.tilesKeyless');
   const photoreal = await loadPhotorealisticTileset(Cesium, {
     googleApiKey,
+    googleTokens,
     cesiumToken,
   });
   const tileset = photoreal.tileset;

src/app/sourceComposition.js

@@ -0,0 +1,113 @@
+const contract = (layers, methods) =>
+  Object.freeze({
+    layers: Object.freeze(layers),
+    methods: Object.freeze(methods),
+  });
+
+/** Acquisition contracts and their consumers; records remain family-specific. */
+export const CATALOG_SOURCE_CONTRACTS = Object.freeze({
+  directions: contract(['directions'], ['getRoute']),
+  'recent-imagery': contract(
+    ['recent-imagery'],
+    ['searchHls', 'getThumbnail', 'getTileTemplate'],
+  ),
+  flights: contract(['flights'], ['getSnapshot']),
+  military: contract(['military'], ['getSnapshot']),
+  vessels: contract(['ais-live-vessels'], ['getSnapshot']),
+  cctv: contract(
+    ['cctv'],
+    ['getCatalog', 'getHealth', 'getFrameUrl', 'getMediaUrl'],
+  ),
+  radio: contract(['radio'], ['getDirectory', 'recordClick']),
+  traffic: contract(
+    ['traffic'],
+    [
+      'requestRoads',
+      'getStatus',
+      'fetchFlowForBounds',
+      'getFlowSessionStats',
+      'resetFlowTileCache',
+    ],
+  ),
+  bikeshare: contract(['bikeshare'], ['getStations']),
+  installations: contract(
+    ['military-installations'],
+    ['getMappedSites', 'searchNearby'],
+  ),
+  satellites: contract(['satellites'], ['readGroup']),
+  launches: contract(['rocket-launches'], ['getLaunches', 'getActiveTle']),
+  alpr: contract(['alpr-cameras'], ['fetch']),
+  firms: contract(['local-firms'], ['getSnapshot']),
+  wind: contract(['wind'], ['getSnapshot']),
+  weather: contract(
+    ['weather-radar', 'weather-satellite', 'weather-lightning'],
+    ['getSnapshot'],
+  ),
+  cyclones: contract(['weather-cyclones'], ['getSnapshot']),
+  earthquakes: contract(['earthquakes'], ['getSnapshot']),
+  'fire-perimeters': contract(['fire-perimeters'], ['getSnapshot']),
+  cables: contract(['telegeography-submarine-cables'], ['fetch']),
+  transit: contract(['transit'], ['requestSnapshot', 'getHistory']),
+});
+
+/** An omitted provider is unavailable, never an authoritative empty dataset. */
+export class SourceUnavailableError extends Error {
+  constructor(name) {
+    super(`Data source not configured: ${name}`);
+    this.name = 'SourceUnavailableError';
+    this.code = 'unavailable';
+    this.unavailable = true;
+    this.retryable = false;
+  }
+}
+
+/** Validate supplied contracts and keep omitted sources inert during construction. */
+export function resolveCatalogSources(supplied = {}) {
+  if (!supplied || typeof supplied !== 'object' || Array.isArray(supplied))
+    throw new TypeError('Catalog sources must be an object');
+  const sources = { ...supplied };
+  const missing = new Set();
+  for (const [name, { methods }] of Object.entries(CATALOG_SOURCE_CONTRACTS)) {
+    const source = sources[name];
+    if (source == null) {
+      missing.add(name);
+      const unavailable = () => {
+        throw new SourceUnavailableError(name);
+      };
+      sources[name] = Object.freeze({
+        label: name,
+        ...Object.fromEntries(methods.map((method) => [method, unavailable])),
+      });
+    } else if (methods.some((method) => typeof source[method] !== 'function')) {
+      throw new TypeError(`Invalid catalog source: ${name}`);
+    }
+  }
+  return {
+    sources,
+    isConfigured: (name) => !missing.has(name),
+    createAvailabilityLookup(layers) {
+      const byId = new Map(layers.map((layer) => [layer.id, layer]));
+      const availability = new Map();
+      for (const [name, { layers: ids }] of Object.entries(
+        CATALOG_SOURCE_CONTRACTS,
+      )) {
+        for (const id of ids) {
+          const layer = byId.get(id);
+          if (!layer) throw new Error(`Missing source consumer: ${id}`);
+          availability.set(
+            id,
+            Object.freeze({
+              available: !missing.has(name),
+              source: name,
+              reason: missing.has(name)
+                ? `${layer.name || id}: data source not configured`
+                : null,
+            }),
+          );
+        }
+      }
+      return (id) =>
+        availability.get(id) ?? byId.get(id)?.getSourceAvailability?.();
+    },
+  };
+}

src/app/sourceComposition.test.mjs

@@ -0,0 +1,156 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  resolveCatalogSources,
+  CATALOG_SOURCE_CONTRACTS,
+} from './sourceComposition.js';
+import { createApplicationCatalog } from './constructCatalog.js';
+import { createSurfaceServices } from './surfaceServices.js';
+import { createStandaloneLayerSources } from '../standalone/layerSources.js';
+import { LayerLifecycle } from '../data/lifecycle.js';
+
+function catalog(sources, t) {
+  const lifetime = new AbortController();
+  t.after(() => lifetime.abort());
+  return createApplicationCatalog({
+    sources,
+    signal: lifetime.signal,
+    surface: createSurfaceServices({
+      terrainSource: { getHeights: async () => [] },
+      signal: lifetime.signal,
+      eventTarget: null,
+    }),
+  });
+}
+
+test('every acquisition source can be omitted without losing catalog membership', (t) => {
+  const baseline = catalog(createStandaloneLayerSources(), t);
+  for (const name of Object.keys(CATALOG_SOURCE_CONTRACTS)) {
+    const sources = createStandaloneLayerSources({ [name]: null });
+    const actual = catalog(sources, t);
+    assert.deepEqual(actual.metadata, baseline.metadata, name);
+    for (const id of CATALOG_SOURCE_CONTRACTS[name].layers) {
+      assert.equal(actual.getSourceAvailability(id).available, false, id);
+    }
+  }
+});
+
+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);
+  const manager = new LayerLifecycle(
+    {},
+    { getSourceAvailability: actual.getSourceAvailability },
+  );
+  for (const layer of actual.layers) manager.register(layer);
+  for (const { layers: ids } of Object.values(CATALOG_SOURCE_CONTRACTS)) {
+    for (const id of ids) {
+      assert.equal(await manager.setEnabled(id, true), false, id);
+      assert.equal(manager.layers.get(id).initialized, false, id);
+      const row = manager.getAll().find((entry) => entry.id === id);
+      assert.equal(row.enabled, false);
+      assert.equal(row.stats.status, 'unavailable');
+      assert.match(row.stats.error, /data source not configured/);
+    }
+  }
+});
+
+test('configured sources retain identity; invalid implementations never become unavailable silently', () => {
+  const source = { getSnapshot: async () => [] };
+  assert.equal(
+    resolveCatalogSources({ earthquakes: source }).sources.earthquakes,
+    source,
+  );
+  for (const name of Object.keys(CATALOG_SOURCE_CONTRACTS)) {
+    assert.throws(
+      () => resolveCatalogSources({ [name]: {} }),
+      /Invalid catalog source/,
+    );
+  }
+  const missing = resolveCatalogSources({}).sources.earthquakes;
+  assert.throws(() => missing.getSnapshot(), { code: 'unavailable' });
+});
+
+test('standalone defaults allow exact replacements and explicit removal, and reject typos', () => {
+  const source = { getSnapshot: async () => [] };
+  const sources = createStandaloneLayerSources({
+    flights: source,
+    military: null,
+  });
+  assert.equal(sources.flights, source);
+  assert.equal(sources.military, null);
+  assert.equal(typeof sources.cctv.getCatalog, 'function');
+  assert.throws(
+    () => createStandaloneLayerSources({ fligts: source }),
+    /Unknown source/,
+  );
+});
+
+test('empty Street Level uses the shared unavailable lifecycle without initialization', async (t) => {
+  const actual = catalog({}, t);
+  const manager = new LayerLifecycle(
+    {},
+    { getSourceAvailability: actual.getSourceAvailability },
+  );
+  manager.register(actual.get('street-level'));
+  assert.equal(await manager.setEnabled('street-level', true), false);
+  assert.equal(manager.layers.get('street-level').initialized, false);
+  const row = manager.getAll()[0];
+  assert.equal(row.stats.status, 'unavailable');
+  assert.equal(row.stats.error, 'No street-level imagery providers configured');
+  assert.equal(await manager.setEnabled('street-level', false), true);
+  const configured = catalog(createStandaloneLayerSources(), t);
+  assert.equal(
+    configured.get('street-level').getSourceAvailability().available,
+    true,
+  );
+});
+
+test('availability lookup accepts frozen layers and uses their display names', () => {
+  const composition = resolveCatalogSources({});
+  const layers = Object.values(CATALOG_SOURCE_CONTRACTS)
+    .flatMap(({ layers }) => layers)
+    .map((id) =>
+      Object.freeze({
+        id,
+        name: id === 'fire-perimeters' ? 'Fire perimeters' : id,
+      }),
+    );
+  const lookup = composition.createAvailabilityLookup(layers);
+  assert.equal(
+    lookup('fire-perimeters').reason,
+    'Fire perimeters: data source not configured',
+  );
+  assert.equal(Object.hasOwn(layers[0], 'getSourceAvailability'), false);
+  const manager = new LayerLifecycle({}, { getSourceAvailability: lookup });
+  manager.register(layers.find(({ id }) => id === 'fire-perimeters'));
+  assert.equal(
+    manager.getAll()[0].stats.error,
+    'Fire perimeters: data source not configured',
+  );
+});
+
+test('absent military acquisition does not poll, suppress flights, or erase supplied classification', async (t) => {
+  let fetches = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    fetches++;
+    throw new Error('Unexpected fallback acquisition');
+  });
+  const actual = catalog(createStandaloneLayerSources({ military: null }), t);
+  const registry = actual.militaryRegistry;
+  assert.equal(actual.getSourceAvailability('flights').available, true);
+  assert.equal(registry.isMilitaryLayerActive(), false);
+  assert.equal(registry.isMilitaryIcao('abc123'), false);
+  registry.registerMilitaryIcaos([' ABC123 ']);
+  await registry.refreshMilitaryRegistryIfStale();
+  assert.equal(registry.isMilitaryIcao('abc123'), true);
+  assert.equal(registry.isMilitaryIcao('def456'), false);
+  const manager = new LayerLifecycle(
+    {},
+    { getSourceAvailability: actual.getSourceAvailability },
+  );
+  manager.register(actual.get('military'));
+  assert.equal(await manager.setEnabled('military', true), false);
+  assert.equal(registry.isMilitaryLayerActive(), false);
+  assert.equal(fetches, 0);
+});

src/app/tools.js

@@ -4,6 +4,7 @@ import { initDrawTool } from '../annotations/drawTool.js';
 import { initImageryBoxTool } from '../ui/imageryBoxTool.js';
 import { createRecentImageryPanel } from '../ui/recentImagery.js';
 import { initGevVoiceCommands } from '../voice/gevRealtime.js';
+import { installViews, isEmbeddedInline } from './embed.js';
 import { installScopeMask, destroyScopeMask } from '../scopeMask.js';
 import {
   installRenderGovernor,
@@ -118,7 +119,9 @@ export function createApplicationTools({
   // GPU. Holder/data state is untouched, so return is seamless: restore
   // the loop, refresh the one DOM surface we gated, render a frame.
   const syncVisibilitySuspension = () => {
-    const hidden = document.hidden;
+    // A panel's host may report it hidden while it is on screen; the panel
+    // keeps drawing itself (see keepPanelRendering in embed.js).
+    const hidden = document.hidden && !isEmbeddedInline();
     viewer.useDefaultRenderLoop = !hidden;
     cockpitCloudEffects?.setSuspended?.(hidden);
     if (!hidden) {
@@ -176,5 +179,14 @@ export function createApplicationTools({
       delete window.__gevVoiceCommands;
   });
   debug.voiceCommands = voiceCommands;
+  defer(
+    installViews({
+      shell: styleManager,
+      viewer,
+      dataManager,
+      run: (name, args) => voiceCommands.runner(name, args, { signal }),
+      signal,
+    }),
+  );
   return { sceneDirector, annotations, voiceCommands };
 }

src/cockpitMarkup.test.mjs

@@ -86,23 +86,47 @@ test('Cockpit heading tape leaves the bottom exit row unobstructed', () => {
   assert.doesNotMatch(css, /cockpit-compass-label/);
 });
 
-test('Cockpit vision cycle exposes exactly five real visual styles without NONE', () => {
-  assert.match(cycleVisionMode.toString(), /const modes = COCKPIT_VISION_MODES;/);
-  assert.match(setVisionMode.toString(), /const labels = \{\s*optical: inherited,\s*crt: 'CRT',\s*nvg: 'NVG',\s*thermal: 'FLIR',\s*noir: 'NOIR',?\s*\};/);
+test('Cockpit vision cycle exposes every map preset exactly once', () => {
+  assert.match(
+    cycleVisionMode.toString(),
+    /const modes = COCKPIT_VISION_MODES;/,
+  );
+  assert.match(
+    setVisionMode.toString(),
+    /const labels = \{\s*optical: 'NORMAL',\s*crt: 'CRT',\s*nvg: 'NVG',\s*thermal: 'FLIR',\s*anime: 'ANIME',\s*noir: 'NOIR',\s*snow: 'SNOW',?\s*\};/,
+  );
   assert.doesNotMatch(setVisionMode.toString(), /none: 'NONE'/);
-  assert.match(ui, /getInheritedVisionLabel: \(\) =>\s*\(?[\s\S]*?STYLE_STATUS_LABELS\[this\.activeStyle\]/);
+  assert.doesNotMatch(ui, /getInheritedVisionLabel/);
   assert.match(html, /id="cockpit-vision-current-label"[^>]*>NORMAL<\/strong>/);
-  assert.match(ui, /const target = applyCockpitVisionStageIntensities\(\s*this\.stages,\s*next,\s*this\._cockpitVisionRestore,?\s*\);/);
-  assert.match(ui, /this\._cockpitVisionRestore = captureCockpitVisionBaseline\(\s*this\.stages,\s*this\.transitions,?\s*\);/);
+  assert.match(
+    cockpitEnter.toString(),
+    /this\.setVisionMode\(this\.getInitialVisionMode\(\)\)/,
+    'Cockpit must enter on the mode matching the active map preset',
+  );
+  assert.match(
+    readRadioSource(
+      new URL('./ui/cockpitCoordinator.js', import.meta.url),
+      'utf8',
+    ),
+    /getInitialVisionMode:\s*\(\)\s*=>\s*cockpitVisionModeForStyle\(this\.activeStyle\)/,
+  );
   assert.match(
     ui,
-    /if \(next === 'optical'\) \{[\s\S]*?applyCockpitVisionStageIntensities\(\s*this\.stages,\s*next,\s*this\._cockpitVisionRestore,?\s*\);[\s\S]*?return;[\s\S]*?const target = applyCockpitVisionStageIntensities/,
-    'the inherited entry must restore the map shader while CRT, NVG, FLIR, and NOIR remain temporary Cockpit overrides',
+    /const target = applyCockpitVisionStageIntensities\(\s*this\.stages,\s*next,?\s*\);/,
+  );
+  assert.match(
+    ui,
+    /this\._cockpitVisionRestore = captureCockpitVisionBaseline\(\s*this\.stages,\s*this\.transitions,?\s*\);/,
+  );
+  assert.match(
+    ui,
+    /if \(next === 'optical'\) \{[\s\S]*?applyCockpitVisionStageIntensities\(\s*this\.stages,\s*next,?\s*\);[\s\S]*?this\._updateSliderPanel\(null,[\s\S]*?return;[\s\S]*?const target = applyCockpitVisionStageIntensities/,
+    'Normal must clear the inherited map shader while the other map presets remain temporary Cockpit overrides',
   );
   assert.match(
     ui,
     /_syncCockpitInheritedStyle\(\)[\s\S]*?name === this\.activeStyle \? 1 : 0[\s\S]*?this\.transitions\.delete\(name\)[\s\S]*?setVisionMode\(this\.cockpitView\.visionMode\)/,
-    'changing the map preset in Cockpit must refresh both the inherited label and restore baseline',
+    'changing the map preset in Cockpit must refresh the exit restore baseline without replacing Normal',
   );
   assert.match(ui, /setStyle\([\s\S]*?this\._syncCockpitInheritedStyle\(\);/);
 });

src/cockpitVisionPolicy.js

@@ -3,21 +3,40 @@ export const COCKPIT_VISION_MODES = Object.freeze([
   'crt',
   'nvg',
   'thermal',
+  'anime',
   'noir',
+  'snow',
 ]);
 
 const TARGET_STYLE_BY_MODE = Object.freeze({
   crt: 'retro',
   nvg: 'surveillance',
   thermal: 'thermal',
+  anime: 'anime',
   noir: 'noir',
+  snow: 'snow',
 });
 
-/** Normalize a requested Cockpit vision mode to the inherited preset entry. */
+const COCKPIT_MODE_BY_STYLE = Object.freeze({
+  normal: 'optical',
+  retro: 'crt',
+  surveillance: 'nvg',
+  thermal: 'thermal',
+  anime: 'anime',
+  noir: 'noir',
+  snow: 'snow',
+});
+
+/** Normalize a requested Cockpit vision mode to the unfiltered Normal entry. */
 export function normalizeCockpitVisionMode(mode) {
   return COCKPIT_VISION_MODES.includes(mode) ? mode : 'optical';
 }
 
+/** Start Cockpit on the equivalent supported map preset. */
+export function cockpitVisionModeForStyle(style) {
+  return COCKPIT_MODE_BY_STYLE[String(style || '').toLowerCase()] || 'optical';
+}
+
 /** Settle pending map-style crossfades and return their intended final intensities. */
 export function captureCockpitVisionBaseline(stages, transitions) {
   const baseline = {};
@@ -34,12 +53,10 @@ export function captureCockpitVisionBaseline(stages, transitions) {
  * Apply Cockpit-only stage intensities without changing any shader parameters.
  * Returns the temporary style whose parameters should be shown, or null.
  */
-export function applyCockpitVisionStageIntensities(stages, mode, restore = {}) {
+export function applyCockpitVisionStageIntensities(stages, mode) {
   const next = normalizeCockpitVisionMode(mode);
   if (next === 'optical') {
-    for (const [name, intensity] of Object.entries(restore)) {
-      if (stages[name]) stages[name].uniforms.intensity = intensity;
-    }
+    for (const stage of Object.values(stages)) stage.uniforms.intensity = 0;
     return null;
   }
 

src/cockpitVisionPolicy.test.mjs

@@ -3,6 +3,7 @@ import test from 'node:test';
 import {
   applyCockpitVisionStageIntensities,
   captureCockpitVisionBaseline,
+  cockpitVisionModeForStyle,
   COCKPIT_VISION_MODES,
   normalizeCockpitVisionMode,
 } from './cockpitVisionPolicy.js';
@@ -14,12 +15,31 @@ const createStages = () => ({
   thermal: { uniforms: { intensity: 0, heat: 0.8 } },
 });
 
-test('Cockpit vision order exposes inherited, CRT, NVG, FLIR, and NOIR modes', () => {
-  assert.deepEqual(COCKPIT_VISION_MODES, ['optical', 'crt', 'nvg', 'thermal', 'noir']);
+test('Cockpit vision order mirrors the unique map preset order', () => {
+  assert.deepEqual(COCKPIT_VISION_MODES, [
+    'optical',
+    'crt',
+    'nvg',
+    'thermal',
+    'anime',
+    'noir',
+    'snow',
+  ]);
   assert.equal(normalizeCockpitVisionMode('none'), 'optical');
   assert.equal(normalizeCockpitVisionMode('unknown'), 'optical');
 });
 
+test('Cockpit entry selects the vision mode equivalent to the active map style', () => {
+  assert.equal(cockpitVisionModeForStyle('normal'), 'optical');
+  assert.equal(cockpitVisionModeForStyle('retro'), 'crt');
+  assert.equal(cockpitVisionModeForStyle('surveillance'), 'nvg');
+  assert.equal(cockpitVisionModeForStyle('thermal'), 'thermal');
+  assert.equal(cockpitVisionModeForStyle('anime'), 'anime');
+  assert.equal(cockpitVisionModeForStyle('noir'), 'noir');
+  assert.equal(cockpitVisionModeForStyle('snow'), 'snow');
+  assert.equal(cockpitVisionModeForStyle('unsupported'), 'optical');
+});
+
 test('Cockpit settles pending map crossfades before a temporary preset takes ownership', () => {
   const stages = createStages();
   const transitions = new Map([
@@ -29,49 +49,81 @@ test('Cockpit settles pending map crossfades before a temporary preset takes own
   const restore = captureCockpitVisionBaseline(stages, transitions);
   assert.deepEqual(restore, { noir: 1, retro: 0, surveillance: 0, thermal: 0 });
   assert.equal(transitions.size, 0);
-  applyCockpitVisionStageIntensities(stages, 'nvg', restore);
+  applyCockpitVisionStageIntensities(stages, 'nvg');
   assert.equal(stages.surveillance.uniforms.intensity, 1);
-  applyCockpitVisionStageIntensities(stages, 'optical', restore);
-  assert.equal(stages.noir.uniforms.intensity, 1);
+  applyCockpitVisionStageIntensities(stages, 'optical');
+  assert.equal(stages.noir.uniforms.intensity, 0);
   assert.equal(stages.retro.uniforms.intensity, 0);
 });
 
-test('returning from a temporary preset restores the exact inherited intensities', () => {
+test('Normal clears every temporary and inherited visual stage', () => {
   const stages = createStages();
   const restore = Object.fromEntries(
-    Object.entries(stages).map(([name, stage]) => [name, stage.uniforms.intensity]),
+    Object.entries(stages).map(([name, stage]) => [
+      name,
+      stage.uniforms.intensity,
+    ]),
   );
-  applyCockpitVisionStageIntensities(stages, 'thermal', restore);
-  applyCockpitVisionStageIntensities(stages, 'optical', restore);
+  applyCockpitVisionStageIntensities(stages, 'thermal');
+  applyCockpitVisionStageIntensities(stages, 'optical');
   assert.deepEqual(
-    Object.fromEntries(Object.entries(stages).map(([name, stage]) => [name, stage.uniforms.intensity])),
-    restore,
+    Object.fromEntries(
+      Object.entries(stages).map(([name, stage]) => [
+        name,
+        stage.uniforms.intensity,
+      ]),
+    ),
+    { noir: 0, retro: 0, surveillance: 0, thermal: 0 },
   );
+  assert.deepEqual(restore, {
+    noir: 0.72,
+    retro: 0.18,
+    surveillance: 0,
+    thermal: 0,
+  });
 });
 
 test('temporary styles replace each other without changing the inherited restore snapshot', () => {
   const stages = createStages();
   const restore = Object.fromEntries(
-    Object.entries(stages).map(([name, stage]) => [name, stage.uniforms.intensity]),
+    Object.entries(stages).map(([name, stage]) => [
+      name,
+      stage.uniforms.intensity,
+    ]),
   );
-  applyCockpitVisionStageIntensities(stages, 'thermal', restore);
-  assert.equal(applyCockpitVisionStageIntensities(stages, 'crt', restore), 'retro');
+  applyCockpitVisionStageIntensities(stages, 'thermal');
+  assert.equal(applyCockpitVisionStageIntensities(stages, 'crt'), 'retro');
   assert.equal(stages.retro.uniforms.intensity, 1);
   assert.equal(stages.noir.uniforms.intensity, 0);
-  applyCockpitVisionStageIntensities(stages, 'optical', restore);
-  assert.equal(stages.noir.uniforms.intensity, 0.72);
-  assert.equal(stages.retro.uniforms.intensity, 0.18);
+  applyCockpitVisionStageIntensities(stages, 'optical');
+  assert.equal(stages.noir.uniforms.intensity, 0);
+  assert.equal(stages.retro.uniforms.intensity, 0);
+  assert.deepEqual(restore, {
+    noir: 0.72,
+    retro: 0.18,
+    surveillance: 0,
+    thermal: 0,
+  });
 });
 
-test('NOIR is a temporary Cockpit override and inherited restores the captured map style', () => {
+test('NOIR is a temporary Cockpit override and Normal clears it', () => {
   const stages = createStages();
   const restore = Object.fromEntries(
-    Object.entries(stages).map(([name, stage]) => [name, stage.uniforms.intensity]),
+    Object.entries(stages).map(([name, stage]) => [
+      name,
+      stage.uniforms.intensity,
+    ]),
   );
-  assert.equal(applyCockpitVisionStageIntensities(stages, 'noir', restore), 'noir');
+  assert.equal(applyCockpitVisionStageIntensities(stages, 'noir'), 'noir');
   assert.equal(stages.noir.uniforms.intensity, 1);
   assert.equal(stages.retro.uniforms.intensity, 0);
-  applyCockpitVisionStageIntensities(stages, 'optical', restore);
-  assert.equal(stages.noir.uniforms.intensity, 0.72);
-  assert.equal(stages.retro.uniforms.intensity, 0.18);
+  applyCockpitVisionStageIntensities(stages, 'optical');
+  assert.equal(stages.noir.uniforms.intensity, 0);
+  assert.equal(stages.retro.uniforms.intensity, 0);
+  assert.deepEqual(restore, {
+    noir: 0.72,
+    retro: 0.18,
+    surveillance: 0,
+    thermal: 0,
+  });
 });

src/codexOauthRealtime.test.mjs

@@ -0,0 +1,273 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import test from 'node:test';
+import path from 'node:path';
+import {
+  codexAuthPath,
+  preferCodexOAuth,
+  readCodexOAuthAccessToken,
+  resolveCodexExecutable,
+  startCodexChatGptLogin,
+} from '../server/providers/openai/codex-auth.js';
+
+const nowMs = Date.UTC(2026, 8, 27);
+const jwt = (payload) =>
+  `${Buffer.from('{}').toString('base64url')}.${Buffer.from(JSON.stringify(payload)).toString('base64url')}.signature`;
+const auth = (token, extras = {}) =>
+  JSON.stringify({
+    auth_mode: 'chatgpt',
+    tokens: { access_token: token, refresh_token: 'refresh-fixture' },
+    ...extras,
+  });
+
+test('optional Codex OAuth pin fails closed on ambiguous values', () => {
+  assert.equal(preferCodexOAuth({}), false);
+  assert.equal(preferCodexOAuth({ GEV_PREFER_CODEX_OAUTH: 'true' }), true);
+  assert.equal(preferCodexOAuth({ GEV_PREFER_CODEX_OAUTH: 'off' }), false);
+  assert.throws(
+    () => preferCodexOAuth({ GEV_PREFER_CODEX_OAUTH: 'maybe' }),
+    /must be true or false/,
+  );
+});
+
+test('Codex auth path follows explicit auth file, CODEX_HOME, then home directory', () => {
+  assert.equal(
+    codexAuthPath({
+      environment: { CODEX_AUTH_JSON: '/tmp/custom-auth.json' },
+      home: '/home/fixture',
+    }),
+    path.resolve('/tmp/custom-auth.json'),
+  );
+  assert.equal(
+    codexAuthPath({
+      environment: { CODEX_HOME: '/tmp/codex-home' },
+      home: '/home/fixture',
+    }),
+    path.join(path.resolve('/tmp/codex-home'), 'auth.json'),
+  );
+  assert.equal(
+    codexAuthPath({ environment: {}, home: '/home/fixture' }),
+    path.join('/home/fixture', '.codex', 'auth.json'),
+  );
+});
+
+test('Codex OAuth reader accepts a current ChatGPT token and rejects unusable credentials', () => {
+  const current = jwt({ exp: nowMs / 1000 + 3600 });
+  assert.equal(
+    readCodexOAuthAccessToken({
+      authPath: '/unused',
+      nowMs,
+      readFile: () => auth(current),
+    }),
+    current,
+  );
+  assert.equal(
+    readCodexOAuthAccessToken({
+      authPath: '/unused',
+      nowMs,
+      readFile: () =>
+        JSON.stringify({
+          auth_mode: 'chatgpt',
+          tokens: { access_token: current },
+        }),
+    }),
+    current,
+    'GEV does not require or consume the vendor refresh token',
+  );
+  for (const readFile of [
+    () => '{bad json',
+    () => JSON.stringify({ tokens: {} }),
+    () => auth(current, { auth_mode: 'apikey' }),
+    () =>
+      JSON.stringify({
+        OPENAI_API_KEY: 'sk-fixture',
+        tokens: { access_token: current, refresh_token: 'refresh-fixture' },
+      }),
+    () => auth('opaque-token'),
+    () => auth('header.not-json.signature'),
+    () => auth(jwt({ exp: 'tomorrow' })),
+    () => {
+      throw new Error('missing');
+    },
+  ]) {
+    assert.throws(
+      () => readCodexOAuthAccessToken({ authPath: '/unused', readFile, nowMs }),
+      /ChatGPT sign-in is unavailable/,
+    );
+  }
+});
+
+test('Codex OAuth reader enforces expiry margin and bounds tokens without exp by file age', () => {
+  for (const exp of [nowMs / 1000 - 1, nowMs / 1000 + 59]) {
+    assert.throws(
+      () => {
+        readCodexOAuthAccessToken({
+          authPath: '/unused',
+          nowMs,
+          readFile: () => auth(jwt({ exp })),
+        });
+      },
+      (error) => {
+        assert.match(error.message, /sign-in has expired/);
+        assert.equal(error.code, 'CODEX_OAUTH_REAUTH_REQUIRED');
+        return true;
+      },
+    );
+  }
+  const noExp = jwt({ sub: 'fixture' });
+  const base = { authPath: '/unused', nowMs, readFile: () => auth(noExp) };
+  assert.equal(
+    readCodexOAuthAccessToken({
+      ...base,
+      statFile: () => ({ mtimeMs: nowMs }),
+    }),
+    noExp,
+  );
+  assert.throws(
+    () =>
+      readCodexOAuthAccessToken({
+        ...base,
+        statFile: () => ({ mtimeMs: nowMs - 3600_000 }),
+      }),
+    /sign-in has expired/,
+  );
+  assert.throws(
+    () =>
+      readCodexOAuthAccessToken({
+        ...base,
+        statFile: () => {
+          throw new Error('missing');
+        },
+      }),
+    /sign-in is unavailable/,
+  );
+});
+
+test('Codex login resolves an installed executable before PATH and starts browser auth detached', async () => {
+  const checked = [];
+  assert.equal(
+    resolveCodexExecutable({
+      environment: {},
+      home: '/home/fixture',
+      access(candidate) {
+        checked.push(candidate);
+        if (candidate.endsWith('/.local/bin/codex')) return;
+        throw new Error('missing');
+      },
+    }),
+    path.join('/home/fixture', '.local', 'bin', 'codex'),
+  );
+  assert.equal(checked.length, 1);
+
+  const child = new EventEmitter();
+  let unref = 0;
+  child.unref = () => {
+    unref += 1;
+  };
+  const calls = [];
+  const pending = startCodexChatGptLogin({
+    executable: '/fixture/codex',
+    home: '/home/fixture',
+    environment: {
+      PATH: '/fixture',
+      https_proxy: 'http://proxy.fixture:8080',
+      OPENAI_API_KEY: 'fixture-api-key',
+      GOOGLE_MAPS_SERVER_API_KEY: 'fixture-google-key',
+      OPENSKY_CLIENT_SECRET: 'fixture-opensky-secret',
+    },
+    spawnImpl(command, args, options) {
+      calls.push({ command, args, options });
+      queueMicrotask(() => child.emit('spawn'));
+      return child;
+    },
+  });
+  const login = await pending;
+  assert.equal(unref, 1);
+  assert.equal(calls[0].command, '/fixture/codex');
+  assert.deepEqual(calls[0].args, ['login']);
+  assert.equal(calls[0].options.detached, true);
+  assert.equal(calls[0].options.stdio, 'ignore');
+  assert.deepEqual(
+    calls[0].options.env,
+    {
+      PATH: '/fixture',
+      https_proxy: 'http://proxy.fixture:8080',
+      CODEX_HOME: path.join('/home/fixture', '.codex'),
+    },
+    'provider secrets stay out of the login process',
+  );
+  child.emit('exit', 1);
+  assert.deepEqual(await login.completion, { exitCode: 1 });
+});
+
+test('Codex login refuses a read/write storage mismatch before spawning', async () => {
+  await assert.rejects(
+    startCodexChatGptLogin({
+      environment: { CODEX_AUTH_JSON: '/tmp/another-auth.json' },
+      home: '/home/fixture',
+      executable: 'codex',
+      spawnImpl: () => assert.fail('mismatched storage must not launch login'),
+    }),
+    { code: 'CODEX_OAUTH_STORAGE_MISMATCH' },
+  );
+});
+
+test('Codex login resolves relative CODEX_HOME before changing the child directory', async () => {
+  const child = new EventEmitter();
+  const environment = { CODEX_HOME: './fixture-codex' };
+  const login = await startCodexChatGptLogin({
+    environment,
+    executable: 'codex',
+    spawnImpl(_command, _args, options) {
+      assert.equal(
+        options.env.CODEX_HOME,
+        path.resolve(environment.CODEX_HOME),
+      );
+      queueMicrotask(() => child.emit('spawn'));
+      return child;
+    },
+  });
+  assert.equal(
+    environment.CODEX_HOME,
+    './fixture-codex',
+    'caller environment is unchanged',
+  );
+  child.emit('exit', 0);
+  assert.deepEqual(await login.completion, { exitCode: 0 });
+});
+
+test('Codex login hides spawn errors and can cancel only its owned child', async () => {
+  const child = new EventEmitter();
+  await assert.rejects(
+    startCodexChatGptLogin({
+      executable: 'codex',
+      spawnImpl() {
+        queueMicrotask(() =>
+          child.emit('error', new Error('private-token-fixture')),
+        );
+        return child;
+      },
+    }),
+    (error) =>
+      error.code === 'CODEX_OAUTH_LOGIN_FAILED' &&
+      !error.message.includes('private-token-fixture'),
+  );
+
+  const running = new EventEmitter();
+  let cancelled = 0;
+  running.kill = (signal) => {
+    assert.equal(signal, 'SIGTERM');
+    cancelled += 1;
+    running.emit('exit', null);
+  };
+  const login = await startCodexChatGptLogin({
+    executable: 'codex',
+    spawnImpl() {
+      queueMicrotask(() => running.emit('spawn'));
+      return running;
+    },
+  });
+  login.cancel();
+  assert.equal(cancelled, 1);
+  assert.deepEqual(await login.completion, { exitCode: null });
+});

src/costEndpointThrottle.test.mjs

@@ -0,0 +1,281 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Readable } from 'node:stream';
+import { readPinokioEnvironment } from '../scripts/pinokio-environment.mjs';
+import { openAiRealtimeProxy } from 'gods-eye-view/server/providers/openai';
+import {
+  makeCostRateLimiter,
+  resolvePerMinuteCap,
+} from '../server/providers/common/rate-limit.js';
+import { OPENAI_DEFAULT_PER_MIN } from '../server/providers/openai/rate-limit.js';
+import { handleHudSummary } from '../server/providers/openai/hud-summary.js';
+import {
+  googlePlacesContextProxy,
+  GOOGLE_DEFAULT_PER_MIN,
+} from '../server/providers/places/google.js';
+
+// Both limiters are cached at module scope on first use, so the env value that
+// matters is the one in place when a route is first exercised — restoring the
+// variable afterwards does not rebuild the limiter. Each route is therefore
+// driven by exactly one test here; a second test wanting a different cap would
+// need its own process, not just a different env value.
+
+/** Set an env var for one test and put the old value back afterwards. */
+function env(t, name, value) {
+  const old = process.env[name];
+  if (value === undefined) delete process.env[name];
+  else process.env[name] = value;
+  t.after(() => {
+    if (old === undefined) delete process.env[name];
+    else process.env[name] = old;
+  });
+}
+
+function install(plugin) {
+  const routes = new Map();
+  plugin.configureServer({
+    middlewares: { use: (route, handler) => routes.set(route, handler) },
+    restart: async () => {},
+  });
+  return routes;
+}
+
+function request(
+  handler,
+  { url = '/', method = 'POST', remoteAddress = '127.0.0.1' } = {},
+) {
+  return new Promise((resolve, reject) => {
+    const req = Readable.from([]);
+    Object.assign(req, {
+      method,
+      url,
+      headers: { host: 'localhost:4173', 'content-type': 'application/json' },
+      socket: { remoteAddress },
+    });
+    const headers = {};
+    const res = {
+      statusCode: 200,
+      setHeader(name, value) {
+        headers[name.toLowerCase()] = value;
+      },
+      end(body = '') {
+        resolve({ status: this.statusCode, headers, body: String(body) });
+      },
+    };
+    Promise.resolve(handler(req, res)).catch(reject);
+  });
+}
+
+test('an unset throttle resolves to the documented default, not to unlimited', () => {
+  // The defect #16 reports: the cap was opt-in, so an unconfigured server let
+  // anyone who could reach it mint tokens on the operator's key without bound.
+  assert.equal(resolvePerMinuteCap(undefined, 30), 30);
+  assert.equal(resolvePerMinuteCap('', 30), 30);
+  assert.equal(resolvePerMinuteCap('   ', 30), 30);
+  assert.ok(
+    typeof makeCostRateLimiter(undefined, 30) === 'function',
+    'an unconfigured cost endpoint must still be throttled',
+  );
+});
+
+test('an explicit 0 is the documented way to run unthrottled', () => {
+  assert.equal(resolvePerMinuteCap('0', 30), 0);
+  assert.equal(
+    makeCostRateLimiter('0', 30),
+    null,
+    'operators who mean "no throttle" must still be able to say so',
+  );
+});
+
+test('a configured value wins, and a fractional one floors', () => {
+  assert.equal(resolvePerMinuteCap('45', 30), 45);
+  assert.equal(resolvePerMinuteCap(45, 30), 45);
+  assert.equal(resolvePerMinuteCap('30.7', 30), 30);
+});
+
+test('a positive fraction keeps the guard rather than flooring to unlimited', () => {
+  for (const fraction of ['0.5', '0.99', 0.01, '1e-9']) {
+    assert.equal(resolvePerMinuteCap(fraction, 30), 1, String(fraction));
+    assert.equal(
+      typeof makeCostRateLimiter(fraction, 30),
+      'function',
+      `${fraction} must still throttle`,
+    );
+  }
+  // Only an explicit zero turns the limiter off.
+  assert.equal(makeCostRateLimiter('0', 30), null);
+  assert.equal(makeCostRateLimiter('0.0', 30), null);
+});
+
+test('an unreadable value keeps the guard instead of removing it', () => {
+  // `3O` (letter O) and `60/min` are the shapes a hand-edited .env produces.
+  // Reading either as "unlimited" would disarm the spend guard on a typo —
+  // the opposite of what the operator was reaching for when they typed it.
+  for (const typo of ['3O', '60/min', 'thirty', '-5', 'NaN']) {
+    assert.equal(
+      resolvePerMinuteCap(typo, 30),
+      30,
+      `${typo} must fall back to the default, not to unlimited`,
+    );
+  }
+});
+
+test('the default cap clears the app’s own demand with room to spare', () => {
+  // src/hud.js HUD_SUMMARY_INTERVAL_MS = 15000 -> 4 summaries/min per open
+  // tab, plus one token mint per voice session. The cap has to sit well above
+  // that or it would throttle the app rather than an abuser.
+  const hudRequestsPerMinutePerTab = 60_000 / 15_000;
+  assert.ok(
+    OPENAI_DEFAULT_PER_MIN >= hudRequestsPerMinutePerTab * 4,
+    `default ${OPENAI_DEFAULT_PER_MIN}/min leaves too little headroom over ${hudRequestsPerMinutePerTab}/min of ordinary use`,
+  );
+});
+
+test('the realtime token route throttles by default, and says so in a 429', async (t) => {
+  env(t, 'GEV_RATELIMIT_OPENAI_PER_MIN', undefined);
+  env(t, 'OPENAI_API_KEY', 'fixture-upstream-secret');
+  let upstreamCalls = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    upstreamCalls += 1;
+    return Response.json({ value: 'fixture-ephemeral' });
+  });
+
+  const handler = install(openAiRealtimeProxy({})).get('/api/realtime/token');
+  const statuses = [];
+  for (let i = 0; i < OPENAI_DEFAULT_PER_MIN + 1; i += 1) {
+    statuses.push((await request(handler)).status);
+  }
+
+  assert.deepEqual(
+    statuses.slice(0, OPENAI_DEFAULT_PER_MIN),
+    Array(OPENAI_DEFAULT_PER_MIN).fill(200),
+    'the default must not throttle ordinary use',
+  );
+  const overLimit = await request(handler);
+  assert.equal(overLimit.status, 429);
+  assert.equal(overLimit.headers['retry-after'], '5');
+  assert.equal(JSON.parse(overLimit.body).error, 'Rate limit exceeded');
+  assert.equal(
+    overLimit.body.includes('fixture-upstream-secret'),
+    false,
+    'a throttled reply must not leak the server-held key',
+  );
+  assert.ok(
+    upstreamCalls <= OPENAI_DEFAULT_PER_MIN,
+    'a throttled request must be refused before it reaches OpenAI, or it still costs money',
+  );
+});
+
+test('the HUD summary route throttles the paid path, never the free one', async (t) => {
+  env(t, 'OPENAI_API_KEY', 'fixture-upstream-secret');
+  let upstreamCalls = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    upstreamCalls += 1;
+    return Response.json({ output_text: 'five word hud summary here' });
+  });
+
+  // Its own client address: the limiter is cached at module scope and shared
+  // across the OpenAI routes, so the realtime case above has already spent
+  // 127.0.0.1's budget inside this process.
+  const from = '10.9.9.9';
+  const statuses = [];
+  for (let i = 0; i < OPENAI_DEFAULT_PER_MIN; i += 1)
+    statuses.push(
+      (await request(handleHudSummary, { remoteAddress: from })).status,
+    );
+  assert.deepEqual(
+    statuses,
+    Array(OPENAI_DEFAULT_PER_MIN).fill(200),
+    'the default must not throttle ordinary HUD use',
+  );
+
+  const overLimit = await request(handleHudSummary, { remoteAddress: from });
+  assert.equal(overLimit.status, 429);
+  assert.equal(overLimit.headers['retry-after'], '5');
+  assert.equal(JSON.parse(overLimit.body).error, 'Rate limit exceeded');
+  assert.equal(
+    overLimit.body.includes('fixture-upstream-secret'),
+    false,
+    'a throttled reply must not leak the server-held key',
+  );
+  assert.ok(
+    upstreamCalls <= OPENAI_DEFAULT_PER_MIN,
+    'a throttled request must be refused before it reaches OpenAI, or it still costs money',
+  );
+
+  // The keyless HUD answer is deliberately NOT throttled: it is composed
+  // locally, spends nothing upstream, and capping it would only take the free
+  // HUD away from an unconfigured install. Same exhausted client, no key.
+  delete process.env.OPENAI_API_KEY;
+  const free = await request(handleHudSummary, { remoteAddress: from });
+  assert.equal(free.status, 200, 'the free path answers past a spent budget');
+  assert.equal(JSON.parse(free.body).configured, false);
+  assert.equal(
+    upstreamCalls <= OPENAI_DEFAULT_PER_MIN,
+    true,
+    'the free path reaches no provider',
+  );
+});
+
+test('the Google places route throttles by default and keeps its places[] contract', async (t) => {
+  env(t, 'GEV_RATELIMIT_GOOGLE_PER_MIN', undefined);
+  let upstreamCalls = 0;
+  const handler = install(
+    googlePlacesContextProxy({
+      resolveApiKey: () => 'fixture-google-server-key',
+      fetchImpl: async () => {
+        upstreamCalls += 1;
+        return Response.json({ places: [] });
+      },
+    }),
+  ).get('/api/google/nearby-places');
+
+  const url = '/?lat=37.77493&lon=-122.41942';
+  const statuses = [];
+  for (let i = 0; i < GOOGLE_DEFAULT_PER_MIN; i += 1) {
+    statuses.push((await request(handler, { url, method: 'GET' })).status);
+  }
+  assert.ok(
+    statuses.every((s) => s === 200),
+    'the default must not throttle ordinary use',
+  );
+
+  const overLimit = await request(handler, { url, method: 'GET' });
+  assert.equal(overLimit.status, 429);
+  assert.equal(overLimit.headers['retry-after'], '5');
+  // Every error response on this route carries places[]; the client reads it
+  // unconditionally, so a throttled reply must not be the one shape that omits it.
+  assert.deepEqual(JSON.parse(overLimit.body).places, []);
+  assert.equal(
+    upstreamCalls,
+    GOOGLE_DEFAULT_PER_MIN,
+    'a throttled request must be refused before it reaches Google, or it still costs money',
+  );
+});
+
+test('the code defaults match the caps the Pinokio build ships', () => {
+  // These two numbers used to live only in pinokio/_ENVIRONMENT, and the value
+  // this repo suggested elsewhere had already drifted away from them. Now that
+  // they are the server's defaults, the packaged app and an unconfigured
+  // checkout must agree, or a Pinokio user's throttle silently stops matching
+  // the one everybody else gets. If you deliberately want them to differ, this
+  // assertion is the place to say so.
+  const shipped = readPinokioEnvironment(
+    path.join(
+      path.dirname(fileURLToPath(import.meta.url)),
+      '..',
+      'pinokio',
+      '_ENVIRONMENT',
+    ),
+  );
+  assert.equal(
+    Number(shipped.GEV_RATELIMIT_OPENAI_PER_MIN),
+    OPENAI_DEFAULT_PER_MIN,
+  );
+  assert.equal(
+    Number(shipped.GEV_RATELIMIT_GOOGLE_PER_MIN),
+    GOOGLE_DEFAULT_PER_MIN,
+  );
+});

src/data/adminBoundaries.js

@@ -58,30 +58,18 @@ export function normalizeAdminName(value) {
 const PACKS = {
   countries: {
     url: new URL('./local_data/natural_earth/countries.json', import.meta.url),
-    importJson: () =>
-      import('./local_data/natural_earth/countries.json', {
-        with: { type: 'json' },
-      }),
   },
   admin1: {
     url: new URL(
       './local_data/natural_earth/states_provinces.json',
       import.meta.url,
     ),
-    importJson: () =>
-      import('./local_data/natural_earth/states_provinces.json', {
-        with: { type: 'json' },
-      }),
   },
   counties: {
     url: new URL(
       './local_data/us_census_counties/counties.json',
       import.meta.url,
     ),
-    importJson: () =>
-      import('./local_data/us_census_counties/counties.json', {
-        with: { type: 'json' },
-      }),
   },
 };
 
@@ -297,7 +285,7 @@ function addKey(index, key, entry, tier) {
 
 const loadAdmin1 = createRetryableLoader(async () => {
   packLoads.admin1 += 1;
-  const pack = await loadBundledJson(PACKS.admin1.url, PACKS.admin1.importJson);
+  const pack = await loadBundledJson(PACKS.admin1.url);
   const decimals = pack.meta?.decimals ?? 3;
   const index = new Map();
   for (const feature of pack.features || []) {
@@ -323,10 +311,7 @@ const loadAdmin1 = createRetryableLoader(async () => {
 
 const loadCounties = createRetryableLoader(async () => {
   packLoads.counties += 1;
-  const pack = await loadBundledJson(
-    PACKS.counties.url,
-    PACKS.counties.importJson,
-  );
+  const pack = await loadBundledJson(PACKS.counties.url);
   const decimals = pack.meta?.decimals ?? 4;
   const byFull = new Map();
   const byName = new Map();
@@ -348,10 +333,7 @@ const loadCounties = createRetryableLoader(async () => {
 
 const loadCountries = createRetryableLoader(async () => {
   packLoads.countries += 1;
-  const pack = await loadBundledJson(
-    PACKS.countries.url,
-    PACKS.countries.importJson,
-  );
+  const pack = await loadBundledJson(PACKS.countries.url);
   const index = new Map();
   for (const feature of pack.features || []) {
     const entry = {

src/data/aisLiveVessels.analyst.test.mjs

@@ -28,7 +28,7 @@ test('ais analyst record: full record maps every contract field', () => {
     courseDeg: 214.0,
     shipType: 'Cargo',
     destination: 'OAKLAND',
-    navStatus: null, // /api/ais-live does not surface NavigationalStatus
+    navStatus: null, // /api/vessels does not surface NavigationalStatus
   });
 });
 

src/data/aisLiveVessels.js

@@ -1,10 +1,13 @@
 import { createApplicationVessels } from '../app/layers/aisLiveVessels.js';
 
-import { createAisStreamSource } from '../sources/live/standalone.js';
+import { createVesselSource } from '../sources/live/standalone.js';
 
 const aisLiveVesselsLayer = createApplicationVessels({
-  source: createAisStreamSource({
-    apiUrl: import.meta.env?.VITE_AIS_LIVE_API_URL || '/api/ais-live',
+  source: createVesselSource({
+    apiUrl: import.meta.env?.VITE_AIS_LIVE_API_URL || '/api/vessels',
+    // Resolved against the document's address, which a panel host may serve
+    // from its own scheme.
+    origin: () => globalThis.document?.baseURI ?? 'http://localhost',
   }),
   options: {
     maxRows: import.meta.env?.VITE_AIS_LIVE_MAX_ROWS,

src/data/aisLiveVessels.test.mjs

@@ -1668,7 +1668,7 @@ test('a vessel analyst record carries the MMSI the tracker keys on', () => {
 });
 
 test('vessel selection passes the opaque source reference to optional history', async () => {
-  const { createAisStreamSource } = await import('../sources/live/standalone.js');
+  const { createVesselSource } = await import('../sources/live/standalone.js');
   _setVesselStateForTest({ enabled: false });
   const requests = [];
   aisLiveVesselsLayer.setSource({
@@ -1688,6 +1688,6 @@ test('vessel selection passes the opaque source reference to optional history',
   } finally {
     harness.cleanup();
     _setVesselStateForTest({ enabled: false });
-    aisLiveVesselsLayer.setSource(createAisStreamSource());
+    aisLiveVesselsLayer.setSource(createVesselSource());
   }
 });

src/data/aisWatchdog.js

@@ -450,7 +450,7 @@ export function createAisWatchdog(options = {}) {
     return generation;
   }
 
-  /** Status metadata for /api/ais-live. */
+  /** Status metadata for /api/vessels. */
   function snapshot() {
     const monoNow = clock.mono();
     const wallNow = clock.wall();

src/data/analystEngine.test.mjs

@@ -174,11 +174,95 @@ test('analyst: nearest sorting attaches distanceKm ascending', async () => {
 
 test('analyst: follow-up re-filters the remembered set without re-snapshot', async () => {
   const eng = makeEngine();
-  await eng.query({ layers: ['flights'], scope: { kind: 'region', name: 'Texland' } });
-  const r = await eng.query({ followUp: true, filters: [{ field: 'onGround', op: 'eq', value: true }] });
+  const first = await eng.query({
+    layers: ['flights'],
+    scope: { kind: 'region', name: 'Texland' },
+  });
+  const r = await eng.query({
+    followUp: true,
+    filters: [{ field: 'onGround', op: 'eq', value: true }],
+  });
   assert.equal(r.count, 1);
   assert.equal(r.items[0].id, 'GND1');
   assert.equal(r.coverage.followUp, true);
+  assert.equal(r.scopeLabel, first.scopeLabel);
+  assert.equal(r.display.scope, first.display.scope);
+  assert.equal(r.coverage.scope, first.coverage.scope);
+});
+
+test('analyst: follow-ups preserve partial and unanswered coverage', async () => {
+  const eng = createAnalystEngine({
+    getRecords: (key) => (key === 'flights' ? FLIGHTS : []),
+    getLayerSnapshot: (key) => ({
+      enabled: key === 'flights',
+      feedState: key === 'flights' ? 'nominal' : 'off',
+    }),
+    getViewContext: () => ({ lat: 30.27, lon: -97.74, viewRadiusKm: 150 }),
+  });
+  const first = await eng.query({
+    layers: ['flights', 'military'],
+    scope: { kind: 'anywhere' },
+  });
+  assert.equal(first.partial, true);
+  assert.deepEqual(first.unanswered, ['military']);
+
+  const followUp = await eng.query({ followUp: true, limit: 1 });
+  assert.equal(followUp.partial, true);
+  assert.deepEqual(followUp.unanswered, ['military']);
+  assert.deepEqual(
+    followUp.coverage.layersQueried.map(({ layerKey, status }) => [
+      layerKey,
+      status,
+    ]),
+    first.coverage.layersQueried.map(({ layerKey, status }) => [
+      layerKey,
+      status,
+    ]),
+  );
+});
+
+test('analyst: cancelled pre-commit work cannot replace follow-up memory', async () => {
+  const eng = makeEngine();
+  await eng.query({
+    layers: ['flights'],
+    scope: { kind: 'anywhere' },
+    filters: [{ field: 'id', op: 'eq', value: 'SWA1' }],
+  });
+  let current = true;
+  const stale = await eng.query(
+    { layers: ['local-firms'], scope: { kind: 'anywhere' } },
+    {
+      isCurrent: () => current,
+      beforeCommit: async () => {
+        current = false;
+      },
+    },
+  );
+  assert.equal(stale.code, 'CANCELLED');
+  const followUp = await eng.query({ followUp: true });
+  assert.deepEqual(followUp.items.map((item) => item.id), ['SWA1']);
+});
+
+test('analyst: failed pre-commit work cannot replace follow-up memory', async () => {
+  const eng = makeEngine();
+  await eng.query({
+    layers: ['flights'],
+    scope: { kind: 'anywhere' },
+    filters: [{ field: 'id', op: 'eq', value: 'SWA1' }],
+  });
+  await assert.rejects(
+    eng.query(
+      { layers: ['local-firms'], scope: { kind: 'anywhere' } },
+      {
+        beforeCommit: async () => {
+          throw new Error('projection failed');
+        },
+      },
+    ),
+    /projection failed/,
+  );
+  const followUp = await eng.query({ followUp: true });
+  assert.deepEqual(followUp.items.map((item) => item.id), ['SWA1']);
 });
 
 test('analyst: unresolved region is an honest failure, not empty success', async () => {
@@ -200,6 +284,39 @@ test('analyst: a region lookup timeout is reported as region-timeout', async ()
   assert.equal(r.coverage.scope, 'region:Texas:timeout');
 });
 
+test('analyst: region lookup receives and obeys the owning action signal', async () => {
+  const controller = new AbortController();
+  let receivedSignal = null;
+  const eng = createAnalystEngine({
+    getRecords: () => FLIGHTS,
+    resolveRegionRing: async (_name, signal) => {
+      receivedSignal = signal;
+      await new Promise((resolve) =>
+        signal.addEventListener('abort', resolve, { once: true }),
+      );
+      return null;
+    },
+    getViewContext: () => ({
+      lat: 30.27,
+      lon: -97.74,
+      viewRadiusKm: 150,
+    }),
+  });
+  const pending = eng.query(
+    { layers: ['flights'], scope: { kind: 'region', name: 'Texas' } },
+    {
+      signal: controller.signal,
+      isCurrent: () => !controller.signal.aborted,
+    },
+  );
+  await Promise.resolve();
+  controller.abort();
+  const result = await pending;
+  assert.equal(receivedSignal, controller.signal);
+  assert.equal(result.code, 'CANCELLED');
+  assert.equal(result.cancelled, true);
+});
+
 test('analyst: route fields queryable from cached enrichment only', async () => {
   const r = await makeEngine().query({
     layers: ['flights'], scope: { kind: 'anywhere' },
@@ -262,20 +379,132 @@ test('helpers: haversine sanity + scope radius', () => {
   assert.deepEqual(scoped.map((f) => f.id).sort(), ['GND1', 'SWA1']);
 });
 
-test('bounded loaded cohorts disclose truncation before filtering and retain it on follow-up', async () => {
+test('capped cohorts report returned/total/truncated and keep it on follow-up', async () => {
   const engine = createAnalystEngine({
     getRecords: () => [{ id: 'sample dam', lat: 0, lon: 0, name: 'sample' }],
-    getRecordCoverage: () => ({ basis: 'bounded-loaded-records', recordsExamined: 1, loadedCount: 3000, sourceTruncated: true }),
+    getRecordCoverage: () => ({ total: 3000, truncated: true }),
     getViewContext: () => ({ lat: 0, lon: 0, viewRadiusKm: 25 }),
   });
   const result = await engine.query({ layers: ['local-dams'], scope: { kind: 'anywhere' }, sortBy: 'distance' });
   assert.equal(result.count, 1);
-  assert.equal(result.coverage.layersQueried[0].sourceTruncated, true);
-  assert.match(result.coverage.note, /omitted records may change the nearest item or count/);
+  const layer = result.coverage.layersQueried[0];
+  assert.deepEqual({ returned: layer.returned, total: layer.total, truncated: layer.truncated }, { returned: 1, total: 3000, truncated: true });
+  assert.deepEqual(result.coverage.records, { returned: 1, total: 3000, truncated: true });
+  assert.match(result.display.caveat, /counted 1 of 3,000 loaded records/);
   const followUp = await engine.query({ followUp: true });
-  assert.equal(followUp.coverage.layersQueried[0].loadedCount, 3000);
+  assert.equal(followUp.coverage.layersQueried[0].total, 3000);
 });
 
+test('an uncapped cohort is complete and carries no caveat', async () => {
+  const result = await makeEngine().query({ layers: ['flights'], scope: { kind: 'anywhere' } });
+  assert.deepEqual(result.coverage.records, { returned: 4, total: 4, truncated: false });
+  assert.equal(result.display.caveat, undefined);
+  assert.equal(result.display.scope, 'anywhere in the loaded data');
+});
+
+test('unknown fields, operators, scopes and wrong-typed values are refused with the allowed values', async () => {
+  const engine = makeEngine();
+  const field = await engine.query({ layers: ['flights'], filters: [{ field: 'time', op: 'gte', value: 5 }] });
+  assert.equal(field.ok, false);
+  assert.equal(field.code, 'UNKNOWN_FIELD');
+  assert.ok(field.allowed.includes('altitudeM'));
+  const op = await engine.query({ layers: ['flights'], filters: [{ field: 'altitudeM', op: 'wat', value: 5 }] });
+  assert.equal(op.code, 'BAD_OPERATOR');
+  assert.deepEqual(op.allowed, ['gt', 'gte', 'lt', 'lte', 'eq', 'neq']);
+  const flag = await engine.query({ layers: ['flights'], filters: [{ field: 'military', op: 'eq', value: 'false' }] });
+  assert.equal(flag.code, 'BAD_VALUE', 'the string "false" must not match the TRUE record');
+  const num = await engine.query({ layers: ['flights'], filters: [{ field: 'altitudeM', op: 'gt', value: 'high' }] });
+  assert.equal(num.code, 'BAD_VALUE');
+  const scope = await engine.query({ layers: ['flights'], scope: { kind: 'polygon' } });
+  assert.equal(scope.code, 'UNKNOWN_SCOPE');
+  assert.deepEqual(scope.allowed, ['view', 'region', 'radius', 'anywhere']);
+  const sort = await engine.query({ layers: ['flights'], sortBy: 'loudness' });
+  assert.equal(sort.code, 'UNKNOWN_FIELD');
+  assert.equal(engine.hasMemory(), false, 'refusals never become follow-up memory');
+});
+
+test('a typed boolean filter still matches exactly', async () => {
+  const r = await makeEngine().query({ layers: ['flights'], scope: { kind: 'anywhere' }, filters: [{ field: 'military', op: 'eq', value: false }] });
+  assert.deepEqual(r.items.map((i) => i.id).sort(), ['GND1', 'N123', 'SWA1']);
+});
+
+test('distance honours sortDir: desc is farthest first', async () => {
+  const far = await makeEngine().query({ layers: ['flights'], scope: { kind: 'anywhere' }, sortBy: 'distance', sortDir: 'desc', limit: 1 });
+  assert.equal(far.items[0].id, 'N123');
+  const near = await makeEngine().query({ layers: ['flights'], scope: { kind: 'anywhere' }, sortBy: 'distance', limit: 1 });
+  assert.equal(near.items[0].id, 'SWA1');
+});
+
+test('a follow-up without a previous answer is refused, not a fresh flights query', async () => {
+  const r = await makeEngine().query({ followUp: true, filters: [] });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'NO_RESULT_CONTEXT');
+});
+
+test('follow-ups never rewrite the remembered rows', async () => {
+  const engine = makeEngine();
+  await engine.query({ layers: ['flights'], scope: { kind: 'anywhere' } });
+  await engine.query({ followUp: true, sortBy: 'distance' });
+  const again = await engine.query({ followUp: true });
+  assert.equal(again.count, 4, 'a follow-up keeps the remembered set, not the view');
+  assert.ok(again.items.every((item) => item.distanceKm === undefined));
+});
+
+test('a superseded slow region query cannot overwrite the newer follow-up memory', async () => {
+  let releaseSlow;
+  const engine = createAnalystEngine({
+    getRecords: (key) => ({ flights: FLIGHTS, 'ais-live-vessels': SHIPS }[key] || []),
+    resolveRegionRing: () => new Promise((resolve) => { releaseSlow = () => resolve(TEXLAND); }),
+    getViewContext: () => ({ lat: 30.27, lon: -97.74, viewRadiusKm: 150 }),
+  });
+  let generation = 0;
+  const slowGeneration = ++generation;
+  const slow = engine.query({ layers: ['flights'], scope: { kind: 'region', name: 'Texland' } }, { isCurrent: () => generation === slowGeneration });
+  const newGeneration = ++generation;
+  const fresh = await engine.query({ layers: ['ais-live-vessels'], scope: { kind: 'anywhere' } }, { isCurrent: () => generation === newGeneration });
+  assert.equal(fresh.ok, true);
+  releaseSlow();
+  const stale = await slow;
+  assert.equal(stale.code, 'CANCELLED');
+  const followUp = await engine.query({ followUp: true });
+  assert.deepEqual(followUp.items.map((i) => i.layerKey), ['ais-live-vessels', 'ais-live-vessels']);
+});
+
+test('off, loading and unavailable layers are refused distinctly; a real zero stays ok', async () => {
+  const engineFor = (snapshot, rows = [], warming = false) => createAnalystEngine({
+    getRecords: () => rows,
+    getLayerSnapshot: () => snapshot,
+    isWarming: () => warming,
+    getViewContext: () => ({ lat: 0, lon: 0, viewRadiusKm: 25 }),
+  });
+  assert.equal((await engineFor({ enabled: false, feedState: 'off' }).query({ layers: ['earthquakes'] })).code, 'LAYER_OFF');
+  assert.equal((await engineFor({ enabled: true, feedState: 'loading' }).query({ layers: ['earthquakes'] })).code, 'NOT_READY');
+  assert.equal((await engineFor({ enabled: true, feedState: 'nominal' }, [], true).query({ layers: ['earthquakes'] })).code, 'NOT_READY');
+  assert.equal((await engineFor({ enabled: true, feedState: 'unavailable' }).query({ layers: ['earthquakes'] })).code, 'FEED_UNAVAILABLE');
+  const zero = await engineFor({ enabled: true, feedState: 'nominal' }, [{ id: 'q', lat: 50, lon: 50, magnitude: 2 }]).query({ layers: ['earthquakes'], filters: [{ field: 'magnitude', op: 'gte', value: 5 }] });
+  assert.equal(zero.ok, true);
+  assert.equal(zero.count, 0);
+  assert.equal(zero.coverage.layersQueried[0].status, 'ok');
+});
+
+test('time fields filter by ISO and derive ageHours; the feed window is exposed', async () => {
+  const now = Date.parse('2026-09-23T12:00:00Z');
+  const engine = createAnalystEngine({
+    now: () => now,
+    getRecords: () => [
+      { id: 'recent', lat: 0, lon: 0, magnitude: 4, timeMs: now - 2 * 3_600_000 },
+      { id: 'older', lat: 0, lon: 0, magnitude: 5, timeMs: now - 20 * 3_600_000 },
+    ],
+    getViewContext: () => ({ lat: 0, lon: 0, viewRadiusKm: 25 }),
+  });
+  const iso = await engine.query({ layers: ['earthquakes'], scope: { kind: 'anywhere' }, filters: [{ field: 'timeMs', op: 'gte', value: '2026-09-23T06:00:00Z' }] });
+  assert.deepEqual(iso.items.map((i) => i.id), ['recent']);
+  const age = await engine.query({ layers: ['earthquakes'], scope: { kind: 'anywhere' }, filters: [{ field: 'ageHours', op: 'lte', value: 6 }] });
+  assert.deepEqual(age.items.map((i) => i.id), ['recent']);
+  assert.equal(age.items[0].ageHours, 2);
+  assert.equal(age.display.window, 'last 24 h');
+  assert.equal(age.coverage.layersQueried[0].window, 'last 24 h');
+});
 
 test('follow-up provenance stays attached to old rows after a feed recovers', async () => {
   let state = 'stale';
@@ -293,3 +522,141 @@ test('follow-up provenance stays attached to old rows after a feed recovers', as
   assert.equal(engine.hasMemory(), false);
   assert.equal((await engine.query()).coverage.feedProvenance.overall, 'nominal');
 });
+
+test('a large loaded set sorts and summarizes without overflowing the stack', async () => {
+  const rows = Array.from({ length: 200_000 }, (_, i) => ({ id: `FIRE-${i}`, lat: 0, lon: 0, frp: i }));
+  const engine = createAnalystEngine({
+    getRecords: () => rows,
+    getViewContext: () => ({ lat: 0, lon: 0, viewRadiusKm: 25 }),
+  });
+  const result = await engine.query({ layers: ['local-firms'], scope: { kind: 'anywhere' }, sortBy: 'frp', limit: 1 });
+  assert.equal(result.count, 200_000);
+  assert.equal(result.items[0].frp, 199_999);
+  assert.equal(result.summary.frpMin, 0);
+});
+
+test('an enabled but empty layer says why on screen', async () => {
+  const engine = createAnalystEngine({
+    getRecords: () => [],
+    getLayerSnapshot: () => ({ enabled: true, feedState: 'nominal' }),
+    getEmptyNote: () => 'Fly below 400 km to a covered region',
+    getViewContext: () => ({ lat: 0, lon: 0, viewRadiusKm: 25 }),
+  });
+  const result = await engine.query({ layers: ['transit'] });
+  assert.equal(result.ok, true);
+  assert.equal(result.count, 0);
+  assert.equal(result.coverage.layersQueried[0].status, 'empty');
+  assert.match(result.display.caveat, /transit: Fly below 400 km/);
+});
+
+test('a radius around a named place without a centre is refused, not measured around the camera', async () => {
+  const r = await makeEngine().query({ layers: ['ais-live-vessels'], scope: { kind: 'radius', name: 'Singapore', km: 200 } });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'BAD_SCOPE');
+  const ok = await makeEngine().query({ layers: ['ais-live-vessels'], scope: { kind: 'radius', name: 'Houston', km: 200, center: { lat: 29.6, lon: -95.0 } } });
+  assert.equal(ok.ok, true);
+});
+
+test('a field copied with its hinted unit still resolves', async () => {
+  const r = await makeEngine().query({ layers: ['local-firms'], scope: { kind: 'anywhere' }, sortBy: 'frp(MW)', filters: [{ field: 'frp (MW)', op: 'gt', value: 100 }] });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.items.map((i) => i.id), ['FIRE-3', 'FIRE-1']);
+});
+
+test('a written unit converts to the field unit or is refused', async () => {
+  const engine = makeEngine();
+  const feet = await engine.query({ layers: ['flights'], scope: { kind: 'anywhere' }, filters: [{ field: 'altitudeM(ft)', op: 'gt', value: 40000 }] });
+  assert.equal(feet.ok, true);
+  assert.deepEqual(feet.items.map((i) => i.id), ['RCH01'], '40,000 ft is 12,192 m, not 40,000 m');
+  const same = await engine.query({ layers: ['flights'], scope: { kind: 'anywhere' }, filters: [{ field: 'altitudeM (m)', op: 'gt', value: 12192 }] });
+  assert.deepEqual(same.items.map((i) => i.id), ['RCH01']);
+  const knots = await engine.query({ layers: ['flights'], scope: { kind: 'anywhere' }, filters: [{ field: 'speedMps(kts)', op: 'gt', value: 470 }] });
+  assert.deepEqual(knots.items.map((i) => i.id), ['RCH01'], '470 kn is ~242 m/s');
+  const wrong = await engine.query({ layers: ['flights'], filters: [{ field: 'altitudeM(kts)', op: 'gt', value: 1 }] });
+  assert.equal(wrong.code, 'BAD_UNIT');
+  const unitless = await engine.query({ layers: ['flights'], filters: [{ field: 'callsign(ft)', op: 'eq', value: 'X' }] });
+  assert.equal(unitless.code, 'BAD_UNIT');
+  const hinted = await engine.query({ layers: ['local-firms'], scope: { kind: 'anywhere' }, sortBy: 'frp(MW)' });
+  assert.equal(hinted.ok, true);
+});
+
+test('unambiguous numeric strings are numbers; blanks, booleans and words are not', async () => {
+  const engine = makeEngine();
+  const text = await engine.query({ layers: ['flights'], scope: { kind: 'anywhere' }, filters: [{ field: 'altitudeM', op: 'gt', value: '12192' }] });
+  assert.equal(text.ok, true);
+  assert.deepEqual(text.items.map((i) => i.id), ['RCH01']);
+  for (const value of ['', '  ', true, 'high', '12k'])
+    assert.equal((await engine.query({ layers: ['flights'], filters: [{ field: 'altitudeM', op: 'gt', value }] })).code, 'BAD_VALUE', JSON.stringify(value));
+});
+
+test('any supplied centre must be a real coordinate', async () => {
+  const engine = makeEngine();
+  for (const center of [{ lat: 0 }, { lat: 999, lon: 0 }, { lat: 10, lon: 200 }, { lat: '10', lon: 20 }])
+    assert.equal((await engine.query({ layers: ['flights'], scope: { kind: 'radius', km: 100, center } })).code, 'BAD_SCOPE', JSON.stringify(center));
+  assert.equal((await engine.query({ layers: ['flights'], scope: { kind: 'radius', km: 100, center: { lat: 30.2, lon: -97.7 } } })).ok, true);
+});
+
+test('mixed off/loading/unavailable layers refuse; a partly answerable query says so', async () => {
+  const snapshots = { earthquakes: { enabled: true, feedState: 'unavailable' }, 'local-firms': { enabled: true, feedState: 'loading' }, flights: { enabled: false, feedState: 'off' } };
+  const engine = createAnalystEngine({
+    getRecords: (key) => (key === 'ais-live-vessels' ? SHIPS : []),
+    getLayerSnapshot: (key) => snapshots[key] || { enabled: true, feedState: 'nominal' },
+    getViewContext: () => ({ lat: 0, lon: 0, viewRadiusKm: 25 }),
+  });
+  const none = await engine.query({ layers: ['earthquakes', 'local-firms', 'flights'] });
+  assert.equal(none.ok, false);
+  assert.equal(none.code, 'NOT_READY');
+  assert.deepEqual(none.layerStatus.map((l) => l.status), ['error', 'loading', 'off']);
+  assert.equal(engine.hasMemory(), false, 'a refusal never becomes follow-up memory');
+  const down = await engine.query({ layers: ['earthquakes', 'flights'] });
+  assert.equal(down.code, 'FEED_UNAVAILABLE');
+  const partial = await engine.query({ layers: ['ais-live-vessels', 'earthquakes'], scope: { kind: 'anywhere' } });
+  assert.equal(partial.ok, true);
+  assert.equal(partial.partial, true);
+  assert.deepEqual(partial.unanswered, ['earthquakes']);
+  assert.match(partial.display.caveat, /earthquakes error/);
+});
+
+test('returned items are copies: mutating them cannot change the remembered answer', async () => {
+  const engine = makeEngine();
+  const first = await engine.query({ layers: ['flights'], scope: { kind: 'anywhere' }, sortBy: 'altitudeM' });
+  for (const item of first.items) {
+    item.altitudeM = -1;
+    item.id = 'MUTATED';
+  }
+  const again = await engine.query({ followUp: true, sortBy: 'altitudeM' });
+  assert.deepEqual(again.items.map((i) => i.id), ['RCH01', 'SWA1', 'N123', 'GND1']);
+  assert.equal(FLIGHTS[1].altitudeM, 13500, 'the provider rows are untouched');
+});
+
+test('ranking 250k rows stays within a budget and yields to the page', async () => {
+  const rows = Array.from({ length: 250_000 }, (_, i) => ({ id: `F${i}`, lat: (i % 170) - 85, lon: (i % 350) - 175, frp: (i * 7919) % 100_003 }));
+  const engine = createAnalystEngine({ getRecords: () => rows, getViewContext: () => ({ lat: 0, lon: 0, viewRadiusKm: 25 }) });
+  let ticks = 0;
+  const timer = setInterval(() => ticks++, 0);
+  const started = performance.now();
+  const result = await engine.query({ layers: ['local-firms'], scope: { kind: 'anywhere' }, sortBy: 'frp', limit: 1 });
+  const elapsed = performance.now() - started;
+  clearInterval(timer);
+  assert.equal(result.count, 250_000);
+  assert.equal(result.items[0].frp, 100_002);
+  assert.ok(elapsed < 400, `took ${Math.round(elapsed)} ms`);
+  assert.ok(ticks > 0, 'the scan yielded between slices');
+  let current = true;
+  const pending = engine.query({ layers: ['local-firms'], scope: { kind: 'anywhere' }, sortBy: 'distance' }, { isCurrent: () => current });
+  current = false;
+  assert.equal((await pending).code, 'CANCELLED', 'a superseded scan stops at the next slice');
+});
+
+test('analyst: a follow-up naming other layers than the last answer is refused', async () => {
+  const engine = createAnalystEngine({
+    getRecords: (key) => ({ flights: FLIGHTS, 'local-firms': FIRES }[key] || []),
+    resolveRegionRing: async () => null,
+    getViewContext: () => ({ lat: 30.27, lon: -97.74, viewRadiusKm: 150 }),
+  });
+  await engine.query({ layers: ['flights'], scope: { kind: 'anywhere' } });
+  const r = await engine.query({ layers: ['local-firms'], followUp: true });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'FOLLOW_UP_MISMATCH');
+  assert.equal(engine.hasMemory(), true, 'the earlier answer is still the last answer');
+});

src/data/bundledJson.js

@@ -4,24 +4,38 @@
  * The browser fetches the file from `url` — a `new URL('./….json',
  * import.meta.url)` written in the calling module, which Vite serves as-is in
  * dev and emits as an asset in the production build. Under Node (node:test)
- * that URL is a `file:` URL, which `fetch` cannot read, so the caller's
- * JSON-attributed import runs instead.
+ * that URL is a `file:` URL, which `fetch` cannot read, so the file is read
+ * from disk instead.
  *
- * The attributed import cannot serve the browser: the Vite dev server answers
- * it with a JavaScript module, which the browser rejects for a JSON import.
+ * Nothing here imports the JSON as a module. A JSON-attributed import cannot
+ * serve the browser (the Vite dev server answers it with a JavaScript module,
+ * which the browser rejects), and a literal `import('./….json')` makes the
+ * production build emit a JavaScript copy of every pack that the browser
+ * never loads.
  *
  * @module data/bundledJson
  */
 
 /**
  * @param {URL} url - Resolved against the calling module's `import.meta.url`.
- * @param {() => Promise<{default: any}>} importJson - The caller's literal
- *   `import('./….json', { with: { type: 'json' } })`, used only under Node.
+ * @param {{signal?: AbortSignal}} [options]
  * @returns {Promise<any>} The parsed JSON.
  */
-export async function loadBundledJson(url, importJson, { signal } = {}) {
-  if (url.protocol === 'file:') return (await importJson()).default;
+export async function loadBundledJson(url, { signal } = {}) {
   signal?.throwIfAborted();
+  if (url.protocol === 'file:') {
+    // Node's built-in, reached without an import, so the browser build never
+    // bundles or rewrites it; only Node, reading `file:` URLs, gets here. The
+    // read is synchronous so the result settles as promptly as the cached
+    // module import it replaces; callers already memoize each pack.
+    const getBuiltinModule = globalThis.process?.getBuiltinModule;
+    if (typeof getBuiltinModule !== 'function')
+      throw new Error(
+        `God's Eye View needs Node 24.14 or newer to read ${url.pathname.split('/').pop()} (running ${globalThis.process?.version ?? 'an unknown runtime'})`,
+      );
+    const { readFileSync } = getBuiltinModule('node:fs');
+    return JSON.parse(readFileSync(url, 'utf8'));
+  }
   const response = await fetch(url, { signal });
   if (!response.ok) {
     throw new Error(`HTTP ${response.status} for ${url.pathname}`);

src/data/bundledJson.test.mjs

@@ -2,13 +2,14 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { loadBundledJson } from './bundledJson.js';
 
-const MARINE = new URL('./local_data/natural_earth/marine.json', import.meta.url);
-const importMarine = () =>
-  import('./local_data/natural_earth/marine.json', { with: { type: 'json' } });
+const MARINE = new URL(
+  './local_data/natural_earth/marine.json',
+  import.meta.url,
+);
 
-test('bundled JSON: a file URL uses the JSON import under Node', async (t) => {
+test('bundled JSON: a file URL is read from disk under Node', async (t) => {
   const fetchMock = t.mock.method(globalThis, 'fetch');
-  const pack = await loadBundledJson(MARINE, importMarine);
+  const pack = await loadBundledJson(MARINE);
   assert.ok(pack.features.some((ft) => ft.name === 'Gulf of Mexico'));
   assert.equal(fetchMock.mock.callCount(), 0);
 });
@@ -21,16 +22,62 @@ test('bundled JSON: a served URL is fetched as plain JSON', async (t) => {
       headers: { 'content-type': 'application/json' },
     });
   });
-  const url = new URL('http://localhost/src/data/local_data/natural_earth/marine.json');
-  const importJson = () => assert.fail('the browser path must not import JSON');
-  assert.deepEqual(await loadBundledJson(url, importJson), { features: [] });
+  const url = new URL(
+    'http://localhost/src/data/local_data/natural_earth/marine.json',
+  );
+  assert.deepEqual(await loadBundledJson(url), { features: [] });
   assert.deepEqual(requests, [url.href]);
 });
 
 test('bundled JSON: an HTTP error rejects so the retryable loader can retry', async (t) => {
-  t.mock.method(globalThis, 'fetch', async () => new Response('', { status: 404 }));
+  t.mock.method(
+    globalThis,
+    'fetch',
+    async () => new Response('', { status: 404 }),
+  );
   await assert.rejects(
-    loadBundledJson(new URL('http://localhost/missing.json'), importMarine),
+    loadBundledJson(new URL('http://localhost/missing.json')),
     /HTTP 404/,
   );
 });
+
+test('bundled JSON: an aborted load rejects before reading', async () => {
+  const controller = new AbortController();
+  controller.abort();
+  await assert.rejects(loadBundledJson(MARINE, { signal: controller.signal }), {
+    name: 'AbortError',
+  });
+});
+
+test('bundled JSON: no data pack is imported as a module', async () => {
+  // A literal JSON import in app code makes the production build emit a
+  // JavaScript copy of the pack beside the fetched JSON, which the browser
+  // never loads. Tests are not bundled, so they may still import JSON.
+  const { spawnSync } = await import('node:child_process');
+  const result = spawnSync(
+    'git',
+    [
+      'grep',
+      '-nE',
+      String.raw`import\(\s*['"][^'"]*local_data/[^'"]*\.json`,
+      '--',
+      'src',
+      ':!*.test.mjs',
+    ],
+    { cwd: new URL('../../', import.meta.url), encoding: 'utf8' },
+  );
+  // git grep exits 1 when nothing matches.
+  assert.equal(result.status, 1, result.stdout);
+});
+
+test('bundled JSON: an older Node says which version is needed', async (t) => {
+  // Node before 20.16 / 22.3 has no process.getBuiltinModule.
+  const original = process.getBuiltinModule;
+  t.after(() => {
+    process.getBuiltinModule = original;
+  });
+  process.getBuiltinModule = undefined;
+  await assert.rejects(loadBundledJson(MARINE), {
+    message: /needs Node 24\.14 or newer to read marine\.json/,
+  });
+});

src/data/cctvCatalogCap.test.mjs

@@ -128,6 +128,14 @@ test('the catalog applies the fair cap to configured packs end to end', async ()
       sources.slice(0, 3).map((s) => s.id),
       ['env-0', 'env-1', 'env-2'],
     );
+    assert.equal(sources[0].pack, 'env');
+    const [trimmed] = getSources.trimmedPacks();
+    assert.deepEqual(
+      { ...trimmed, region: undefined },
+      { pack: 'env', available: 12, served: 9, region: undefined },
+    );
+    assert.equal(trimmed.region.south, 30);
+    assert.ok(Math.abs(trimmed.region.north - 30.11) < 1e-9);
   } finally {
     for (const key of Object.keys(process.env)) {
       if (!(key in saved)) delete process.env[key];
@@ -135,3 +143,20 @@ test('the catalog applies the fair cap to configured packs end to end', async ()
     Object.assign(process.env, saved);
   }
 });
+
+test('a pack trimmed to its nearest cameras reports how many it offered', async () => {
+  const { prioritizeSources } =
+    await import('../../server/providers/cctv/normalize.js');
+  const cameras = Array.from({ length: 5 }, (_, i) => ({
+    id: `c${i}`,
+    lat: i,
+    lon: 0,
+  }));
+  const kept = prioritizeSources(cameras, 2, [{ lat: 0, lon: 0 }]);
+  assert.deepEqual(
+    kept.map((camera) => camera.id),
+    ['c0', 'c1'],
+  );
+  assert.equal(kept.available, 5);
+  assert.deepEqual(kept.region, { west: 0, south: 0, east: 0, north: 4 });
+});

src/data/cctvVegvesen.test.mjs

@@ -0,0 +1,202 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  loadVegvesenSourcesFromOpenData,
+  vegvesenCameraToSource,
+} from '../../server/providers/cctv/sources.js';
+import {
+  DEFAULT_VEGVESEN_CCTV_URL,
+  VEGVESEN_IMAGE_ORIGIN,
+} from '../../server/providers/cctv/constants.js';
+import { createCctvCatalog } from '../../server/providers/cctv/catalog.js';
+
+/** One `datex_3_1:CctvSimple` feature, shaped like the live OGC payload. */
+const feature = (props = {}, coordinates = [5.459189, 61.832706]) => ({
+  type: 'Feature',
+  geometry: { type: 'Point', coordinates },
+  properties: {
+    stillImageUrl: 'https://kamera.atlas.vegvesen.no/api/images/3000063_1',
+    cameraId: '3000063_1',
+    roadNumber: 'F614',
+    'status.stillImageAvailability': 'videoOrImagesAvailable',
+    orientationDescription: 'Svelgen',
+    description: 'Langesi',
+    ...props,
+  },
+});
+
+test('a Vegvesen feature maps to a source on the pinned frame host', () => {
+  const source = vegvesenCameraToSource(feature());
+  assert.equal(source.id, 'no-vegvesen-3000063_1');
+  assert.equal(source.name, 'F614 Langesi → Svelgen');
+  assert.equal(source.city, 'Norway');
+  assert.equal(source.cityId, 'norway');
+  assert.equal(source.provider, 'Statens vegvesen');
+  assert.equal(source.lat, 61.832706);
+  assert.equal(source.lon, 5.459189);
+  assert.equal(source.headingConfidence, 'low');
+  assert.equal(source.sourceKind, 'vegvesen-datex');
+  assert.equal(source.code, 'LANGESI');
+  assert.ok(source.url.startsWith(VEGVESEN_IMAGE_ORIGIN));
+  assert.equal(source.snapshotUrl, source.url);
+});
+
+test('cameras that publish HLS get live video with the still as fallback', (t) => {
+  const video = {
+    videoServiceLevel: 1,
+    videoEncodingStandard: 'hls',
+    videoUrl: 'https://kamera.vegvesen.no/public/3000063_1/manifest.m3u8',
+  };
+  const source = vegvesenCameraToSource(feature(video));
+  assert.equal(source.feedType, 'hls');
+  assert.equal(source.url, video.videoUrl);
+  assert.equal(
+    source.snapshotUrl,
+    'https://kamera.atlas.vegvesen.no/api/images/3000063_1',
+  );
+  // A manifest anywhere but the camera's own path stays a still.
+  const offPath = vegvesenCameraToSource(
+    feature({ ...video, videoUrl: 'https://evil.test/x/manifest.m3u8' }),
+  );
+  assert.equal(offPath.feedType, 'image');
+  assert.equal(offPath.url, offPath.snapshotUrl);
+  // The kill switch keeps every camera on stills.
+  const saved = process.env.CCTV_VEGVESEN_VIDEO;
+  t.after(() => {
+    if (saved === undefined) delete process.env.CCTV_VEGVESEN_VIDEO;
+    else process.env.CCTV_VEGVESEN_VIDEO = saved;
+  });
+  process.env.CCTV_VEGVESEN_VIDEO = '0';
+  assert.equal(vegvesenCameraToSource(feature(video)).feedType, 'image');
+});
+
+test('faulty cameras, off-host frames and bad geometry are dropped', () => {
+  assert.equal(
+    vegvesenCameraToSource(
+      feature({
+        'status.stillImageAvailability':
+          'videoOrImagesUnavailableDueToCameraFault',
+      }),
+    ),
+    null,
+  );
+  assert.equal(
+    vegvesenCameraToSource(
+      feature({ stillImageUrl: 'https://evil.test/api/images/3000063_1' }),
+    ),
+    null,
+  );
+  // The frame URL must be exactly the camera's own image path.
+  assert.equal(
+    vegvesenCameraToSource(
+      feature({
+        stillImageUrl: 'https://kamera.atlas.vegvesen.no/api/images/999_1',
+      }),
+    ),
+    null,
+  );
+  assert.equal(vegvesenCameraToSource(feature({ cameraId: '../x' })), null);
+  // Copenhagen: a plausible coordinate, but outside the Norway box.
+  assert.equal(vegvesenCameraToSource(feature({}, [12.57, 55.68])), null);
+  assert.equal(vegvesenCameraToSource(feature({}, [5.4])), null);
+  assert.equal(vegvesenCameraToSource(null), null);
+});
+
+test('the loader dedupes, and failures degrade to an empty pack', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  const requested = [];
+  const fetchMock = t.mock.method(globalThis, 'fetch', async (url) => {
+    requested.push(String(url));
+    return Response.json({
+      type: 'FeatureCollection',
+      features: [
+        feature(),
+        feature(),
+        feature(
+          {
+            cameraId: '0629001_1',
+            stillImageUrl:
+              'https://kamera.atlas.vegvesen.no/api/images/0629001_1',
+            description: 'Oslo S',
+          },
+          [10.752, 59.911],
+        ),
+      ],
+    });
+  });
+  const cameras = await loadVegvesenSourcesFromOpenData();
+  assert.deepEqual(requested, [DEFAULT_VEGVESEN_CCTV_URL]);
+  // Nearest-to-anchor first: Oslo leads.
+  assert.deepEqual(
+    cameras.map((c) => c.id),
+    ['no-vegvesen-0629001_1', 'no-vegvesen-3000063_1'],
+  );
+
+  fetchMock.mock.mockImplementation(
+    async () => new Response('nope', { status: 503 }),
+  );
+  assert.deepEqual(await loadVegvesenSourcesFromOpenData(), []);
+  fetchMock.mock.mockImplementation(async () => {
+    throw new Error('offline');
+  });
+  assert.deepEqual(await loadVegvesenSourcesFromOpenData(), []);
+});
+
+const runCatalog = 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 === DEFAULT_VEGVESEN_CCTV_URL) {
+      return Response.json({
+        type: 'FeatureCollection',
+        features: [feature()],
+      });
+    }
+    return Response.json([]);
+  });
+  const sources = await createCctvCatalog({ sourceRoot: '/nonexistent' })();
+  return { requested, sources };
+};
+
+const withEnv = async (patch, fn) => {
+  const saved = { ...process.env };
+  try {
+    delete process.env.CCTV_SOURCES_FILE;
+    delete process.env.CCTV_SOURCES_JSON;
+    delete process.env.CCTV_VEGVESEN_ENABLED;
+    Object.assign(process.env, patch);
+    await fn();
+  } finally {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in saved)) delete process.env[key];
+    }
+    Object.assign(process.env, saved);
+  }
+};
+
+test('the Vegvesen lane is wired into the catalog', async (t) => {
+  await withEnv({}, async () => {
+    const { requested, sources } = await runCatalog(t);
+    assert.ok(requested.includes(DEFAULT_VEGVESEN_CCTV_URL));
+    assert.deepEqual(
+      sources.filter((s) => s.cityId === 'norway').map((s) => s.id),
+      ['no-vegvesen-3000063_1'],
+    );
+  });
+});
+
+test('CCTV_VEGVESEN_ENABLED=0 keeps the lane from being loaded', async (t) => {
+  await withEnv({ CCTV_VEGVESEN_ENABLED: '0' }, async () => {
+    const { requested, sources } = await runCatalog(t);
+    assert.equal(requested.includes(DEFAULT_VEGVESEN_CCTV_URL), false);
+    assert.deepEqual(
+      sources.filter((s) => s.cityId === 'norway'),
+      [],
+    );
+  });
+});

src/data/dataCredits.js

@@ -240,6 +240,13 @@ export const DATA_CREDITS = [
       'Traffic cameras (Calgary): contains information licensed under the ' +
       '<a href="https://data.calgary.ca/stories/s/Open-Calgary-Terms-of-Use/u45n-7awa" target="_blank" rel="noopener">Open Government Licence – City of Calgary</a>',
   },
+  {
+    key: 'vegvesen-cctv',
+    html:
+      'Road cameras (Norway): contains data under the ' +
+      '<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: 'gbfs',
     html: 'Bikeshare availability: GBFS operator feeds (e.g. Austin BCycle)',

src/data/directions.js

@@ -1,3 +1,4 @@
+import { createDirectionsSource } from '../layers/directions/source.js';
 /**
  * @module directions
  * @description Service bundle for the Directions layer.
@@ -37,8 +38,10 @@ export const directionsServices = Object.freeze({
 });
 
 /** Construct one Directions layer over the application scene owners. */
-export function createApplicationDirectionsLayer() {
-  return createDirectionsLayer({ services: directionsServices });
+export function createApplicationDirectionsLayer({
+  source = createDirectionsSource(),
+} = {}) {
+  return createDirectionsLayer({ services: directionsServices, source });
 }
 
 export {

src/data/firmsHeatmap.test.mjs

@@ -25,6 +25,7 @@ test('firms analyst record: full record maps every contract field', () => {
     frp: 1520.4,
     confidence: 0.9,
     satellite: 'N21',
+    sensor: 'VIIRS',
     acqTime: 1_753_600_000_000,
   });
 });

src/data/flights.js

@@ -1,12 +1,12 @@
 import { defaultSurface } from './surfaceServices.js';
 import { createApplicationFlights } from '../app/layers/flights.js';
 
-import { createOpenSkySource } from '../sources/live/standalone.js';
+import { createFlightSource } from '../sources/live/standalone.js';
 import * as militaryRegistry from './militaryRegistry.js';
 
 const flightsLayer = createApplicationFlights({
   surface: defaultSurface,
-  source: createOpenSkySource(),
+  source: createFlightSource(),
   militaryRegistry,
 });
 export { TRACKED_MODEL_MAX_PX } from '../layers/flights/policy.js';

src/data/idSwitches.js

@@ -0,0 +1,63 @@
+const MAX_SWITCHES_LENGTH = 256;
+const ENTRY = /^([a-z][a-z0-9-]*)-([01])$/;
+
+/** Canonical, bounded boolean switches keyed by stable slugs. */
+export function normalizeIdSwitches(value, reservedIds = []) {
+  if (typeof value !== 'string' || value.length > MAX_SWITCHES_LENGTH)
+    return null;
+  if (!value) return '';
+  const entries = new Map();
+  for (const field of value.split('*')) {
+    const match = ENTRY.exec(field);
+    if (!match || reservedIds.includes(match[1]) || entries.has(match[1]))
+      return null;
+    entries.set(match[1], match[2] === '1');
+  }
+  return [...entries]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([id, on]) => `${id}-${on ? '1' : '0'}`)
+    .join('*');
+}
+
+/** Encode by stable IDs rather than registration order or generated tokens. */
+export function encodeIdSwitches(switches) {
+  const value = [...switches]
+    .map(([id, on]) => `${id}-${on === true ? '1' : '0'}`)
+    .join('*');
+  if (value.length > MAX_SWITCHES_LENGTH)
+    throw new RangeError(
+      `Switch IDs exceed the ${MAX_SWITCHES_LENGTH}-character share-link limit`,
+    );
+  const normalized = normalizeIdSwitches(value);
+  if (normalized === null) throw new TypeError('Invalid boolean switch IDs');
+  return normalized;
+}
+
+/** A Map keeps switch IDs separate from object prototype properties. */
+export function decodeIdSwitches(value) {
+  const normalized = normalizeIdSwitches(value);
+  return new Map(
+    normalized
+      ? normalized.split('*').map((entry) => {
+          const [, id, on] = ENTRY.exec(entry);
+          return [id, on === '1'];
+        })
+      : [],
+  );
+}
+
+/** Persist only explicitly requested switch IDs, not unrelated live changes. */
+export function patchRequestedIdSwitches(previous, applied, requested) {
+  const current = decodeIdSwitches(applied);
+  const next = new Map(
+    [...decodeIdSwitches(previous)].filter(([id]) => current.has(id)),
+  );
+  let changed = false;
+  for (const [id, on] of current) {
+    if (Object.hasOwn(requested, id) && typeof requested[id] === 'boolean') {
+      next.set(id, on);
+      changed = true;
+    }
+  }
+  return changed ? encodeIdSwitches(next) : undefined;
+}

src/data/infrastructure.js

@@ -1,12 +1,5 @@
 import { createLocalGeoJsonLayer } from './localGeojsonCore.js';
-
-// Resolved by Vite in builds and relative to this module in other consumers.
-const datacentersUrl = new URL(
-  './local_data/datacenters/datacenters.geojsonl',
-  import.meta.url,
-).href;
-const damsUrl = new URL('./local_data/dams/dams.geojsonl', import.meta.url)
-  .href;
+import { INFRASTRUCTURE_DATA_URLS } from '../sources/infrastructureData.js';
 
 /**
  * Create fresh datacenter and dam layers without starting or loading them.
@@ -14,6 +7,8 @@ const damsUrl = new URL('./local_data/dams/dams.geojsonl', import.meta.url)
  * @returns {object[]} Datacenters then dams, with stable standalone identities.
  */
 export function createInfrastructureLayers(services) {
+  const datacentersUrl = INFRASTRUCTURE_DATA_URLS['local-datacenters'];
+  const damsUrl = INFRASTRUCTURE_DATA_URLS['local-dams'];
   const datacenters = createLocalGeoJsonLayer(
     {
       id: 'local-datacenters',

src/data/infrastructure.test.mjs

@@ -192,6 +192,7 @@ test('consumer build includes only infrastructure code and resolves assets under
   const sources = Object.keys(entry.modules).filter((id) => id.endsWith('.js'));
   assert.deepEqual(sources.map((id) => id.split('/').at(-1)).sort(), [
     'infrastructure.js',
+    'infrastructureData.js',
     'infrastructureOverlayEntry.js',
     'localGeojsonCore.js',
     'localGeojsonLod.js',

src/data/layerState.js

@@ -1,3 +1,4 @@
+import { normalizeIdSwitches, patchRequestedIdSwitches } from './idSwitches.js';
 import reservationRows from './layerStateTokenReservations.json' with { type: 'json' };
 
 const VALID_DISPOSITIONS = new Set([
@@ -11,8 +12,6 @@ export const LAYER_STATE_TOKEN_ALPHABET =
   '0123456789abcdefghijklmnopqrstuvwxyz';
 const LAYER_STATE_TOKEN_PATTERN = /^[a-z0-9]{1,2}$/;
 const NEW_SINGLE_CHARACTER_TOKEN_PATTERN = /^[0-9]$/;
-/** Re-check cadence while a shared subject waits for its feed row to arrive. */
-const PENDING_TRACKING_POLL_MS = 1_000;
 /**
  * A tracking ID is a transponder address, not free text: 6 hex digits for an
  * ICAO24, with slack for TIS-B (`~abc123`) and similar prefixed forms. Bounding
@@ -412,6 +411,27 @@ const OPTION_GROUPS = Object.freeze({
     ),
     booleanOption('viirs', 'v', false),
   ]),
+  'street-level': Object.freeze([
+    // Preserve the published Mapillary token; custom switches use stable IDs.
+    booleanOption('mapillary', 'm', true),
+    Object.freeze({
+      key: 'providerSwitches',
+      patchRequested: patchRequestedIdSwitches,
+      token: 'r',
+      defaultValue: '',
+      normalize: (value) => normalizeIdSwitches(value, ['mapillary']),
+      encode: normalizeIdSwitches,
+      decode: (value) => normalizeIdSwitches(value, ['mapillary']),
+    }),
+    enumOption('pano', 'p', 'all', ['all', 'pano', 'flat'], {
+      all: 'a',
+      pano: 'p',
+      flat: 'f',
+    }),
+    // Relative days, so a link means the same next year. The max matches
+    // MAX_SINCE_DAYS in streetLevel/policy.js (pinned by layerState.test).
+    boundedIntegerOption('sinceDays', 's', 0, { min: 0, max: 36500 }),
+  ]),
   radio: Object.freeze([
     Object.freeze({
       key: 'filter',
@@ -433,12 +453,6 @@ const OPTION_GROUPS = Object.freeze({
   ]),
 });
 
-const TRACKING_OPTION_KEY_BY_LAYER = Object.freeze({
-  flights: 'selectedFlightsTrackingId',
-  military: 'selectedMilitaryTrackingId',
-  satellites: 'selectedSatTrackingId',
-});
-
 export const SHARE_TRACKING_RESTORE_POLICIES = Object.freeze({
   flights: Object.freeze({
     optionOwner: 'flights',
@@ -639,6 +653,12 @@ export const LAYER_STATE_REGISTRY = Object.freeze([
     disposition: 'enabled+options',
     optionOwner: 'satellites',
   }),
+  Object.freeze({
+    id: 'street-level',
+    token: '0',
+    disposition: 'enabled+options',
+    optionOwner: 'street-level',
+  }),
   Object.freeze({
     id: 'telegeography-submarine-cables',
     token: 'u',
@@ -740,7 +760,7 @@ export function validateLayerStateAllocations(
   return true;
 }
 
-const REGISTRY_BY_ID = new Map(
+export const REGISTRY_BY_ID = new Map(
   LAYER_STATE_REGISTRY.map((entry) => [entry.id, entry]),
 );
 const REGISTRY_BY_TOKEN = new Map(
@@ -752,7 +772,7 @@ const OPTION_OWNER_IDS = Object.freeze([
   ),
 ]);
 
-function optionSpecs(ownerId) {
+export function optionSpecs(ownerId) {
   return OPTION_GROUPS[ownerId] || [];
 }
 
@@ -1055,716 +1075,3 @@ export function layerOptionsForRestore(state, layerId) {
   if (!entry?.optionOwner) return null;
   return { ...normalizeLayerState(state).options[entry.optionOwner] };
 }
-
-function safeStorage() {
-  try {
-    return globalThis.localStorage || null;
-  } catch {
-    return null;
-  }
-}
-
-function currentLayerOutcome(dataManager, layerId) {
-  const state = dataManager.getLayerLifecycleState?.(layerId);
-  return {
-    settledEnabled: Boolean(state?.enabled),
-    lifecycleState: state?.lifecycleState || 'missing',
-    lifecycleUncertain: Boolean(state?.uncertain),
-  };
-}
-
-/**
- * Owns durable user layer preferences independently from transient runtime
- * choreography, and coordinates passive post-registration restoration.
- */
-export class LayerStateCoordinator {
-  constructor(
-    dataManager,
-    shareLinkManager,
-    {
-      storage = safeStorage(),
-      restoreGate = null,
-      onDurableStateChange = null,
-      onTrackingRestoreStatus = null,
-      now = () => Date.now(),
-      // Injectable so the pending-window behavior is deterministically testable
-      // without sleeping out a 90 s expiry.
-      setTimer = (fn, ms) => setTimeout(fn, ms),
-      clearTimer = (handle) => clearTimeout(handle),
-    } = {},
-  ) {
-    if (!dataManager?.registrationsFinalized) {
-      throw new Error(
-        'Layer state requires finalized data-layer registrations',
-      );
-    }
-    this.dataManager = dataManager;
-    this.shareLinkManager = shareLinkManager || null;
-    this.storage = storage;
-    this.restoreGate = restoreGate;
-    this.onDurableStateChange = onDurableStateChange;
-    this.onTrackingRestoreStatus = onTrackingRestoreStatus;
-    this.now = now;
-    this.setTimer = setTimer;
-    this.clearTimer = clearTimer;
-    this._durableState = createDefaultLayerState();
-    this._source = 'defaults';
-    this._destroyed = false;
-    this._restoreControllers = new Map();
-    this._shareCreatedAtMs = null;
-    this._trackingRestoreController = null;
-    this._trackingRestoreGeneration = 0;
-    this._pendingTrackingTimer = null;
-    this._pendingTrackingContext = null;
-    this._unsubscribe = this.dataManager.subscribe((change) =>
-      this._handleManagerChange(change),
-    );
-    this._unsubscribeVisibilityRequests =
-      this.dataManager.subscribeVisibilityRequests((change) =>
-        this._handleVisibilityRequest(change),
-      );
-    this.restorePromise = Promise.resolve([]);
-    this.lastRestoreResults = [];
-  }
-
-  start({
-    shareLayerState = null,
-    allowLocalState = true,
-    shareCreatedAtMs = null,
-  } = {}) {
-    if (this._destroyed)
-      throw new Error('Layer-state coordinator is destroyed');
-    let selected = shareLayerState
-      ? normalizeLayerState(shareLayerState)
-      : null;
-    if (selected) {
-      this._source = 'share';
-      this._shareCreatedAtMs = Number.isFinite(shareCreatedAtMs)
-        ? shareCreatedAtMs
-        : null;
-    } else if (allowLocalState) {
-      let stored = null;
-      try {
-        stored = parseStoredLayerState(
-          this.storage?.getItem?.(LAYER_STATE_STORAGE_KEY),
-        );
-      } catch {
-        /* best effort */
-      }
-      if (stored) {
-        selected = stored;
-        this._source = 'local';
-      }
-    } else {
-      // A valid historical camera/style share with no v2 layer payload keeps
-      // the exact legacy default-layer behavior. It must not inherit an
-      // unrelated recipient's saved local layer preferences.
-      this._source = 'legacy-share';
-    }
-    this._durableState = selected || createDefaultLayerState();
-    this.shareLinkManager?.setLayerStateProvider?.(() =>
-      this.getDurableState(),
-    );
-    this.shareLinkManager?.onLayerStateChange?.();
-    this._notifyDurableState();
-    if (!selected) return this.restorePromise;
-    this.restorePromise = this._restoreSelectedState(
-      this._source === 'share'
-        ? LAYER_RESTORE_ORIGINS.share
-        : LAYER_RESTORE_ORIGINS.local,
-    );
-    return this.restorePromise;
-  }
-
-  get source() {
-    return this._source;
-  }
-
-  getDurableState() {
-    return cloneLayerState(this._durableState);
-  }
-
-  _notifyDurableState() {
-    try {
-      this.onDurableStateChange?.(this.getDurableState());
-    } catch {
-      /* UI sync is best effort */
-    }
-  }
-
-  _handleVisibilityRequest(change) {
-    if (!isExplicitLayerStateOrigin(change?.origin)) return;
-    this._restoreControllers
-      .get(change.layerId)
-      ?.abort('superseded-by-explicit-visibility');
-    if (SHARE_TRACKING_RESTORE_POLICIES[change.layerId]) {
-      this._revokePendingTrackingWatch('superseded-by-explicit-visibility');
-    }
-  }
-
-  /** Revoke every passive restore before explicit navigation can be reclaimed. */
-  cancelPendingRestores(reason = 'superseded-by-explicit-navigation') {
-    for (const controller of this._restoreControllers.values())
-      controller.abort(reason);
-    this._revokePendingTrackingWatch(reason);
-  }
-
-  /**
-   * Revoke a pending shared Follow. Physical navigation may also clear only
-   * the exact passive selection, without writing recipient preferences.
-   */
-  cancelPendingShareTracking(
-    reason = 'superseded-by-explicit-navigation',
-    { clearSelection = false } = {},
-  ) {
-    this._revokePendingTrackingWatch(reason);
-    if (!clearSelection) return false;
-    const selected = this._selectedShareTrackingTarget();
-    return selected ? this._passivelyClearTrackingSelection(selected) : false;
-  }
-
-  _handleManagerChange(change) {
-    if (!change || this._destroyed) return;
-    // Parameter and visibility ownership are independent. A newer explicit
-    // option request may replace passive share options, but it must not abort
-    // the same layer's visibility lifecycle.
-    if (change.type === 'params-requested') {
-      if (
-        isExplicitLayerStateOrigin(change.origin) &&
-        SHARE_TRACKING_RESTORE_POLICIES[change.layerId]
-      ) {
-        this._revokePendingTrackingWatch('superseded-by-explicit-params');
-      }
-      return;
-    }
-    // A layer that goes away takes its latch with it, at ANY origin — a
-    // programmatic disable or teardown never reaches the explicit-intent path
-    // below, so revoke here before that early return.
-    if (
-      change.type === 'visibility' &&
-      change.enabled === false &&
-      SHARE_TRACKING_RESTORE_POLICIES[change.layerId]
-    ) {
-      this._revokePendingTrackingWatch('owner-layer-disabled');
-    }
-    if (!isExplicitLayerStateOrigin(change.origin)) return;
-    if (change.type === 'visibility') {
-      this._restoreControllers
-        .get(change.layerId)
-        ?.abort('superseded-by-explicit-visibility');
-      if (SHARE_TRACKING_RESTORE_POLICIES[change.layerId]) {
-        this._revokePendingTrackingWatch('superseded-by-explicit-visibility');
-      }
-      const enabled = new Set(this._durableState.enabledLayerIds);
-      if (change.enabled) enabled.add(change.layerId);
-      else enabled.delete(change.layerId);
-      this._commitExplicit({
-        ...this._durableState,
-        enabledLayerIds: [...enabled],
-      });
-      return;
-    }
-    if (change.type !== 'params') return;
-    const entry = REGISTRY_BY_ID.get(change.layerId);
-    if (!entry?.optionOwner) return;
-    const ownerId = entry.optionOwner;
-    const nextOwnerOptions = { ...this._durableState.options[ownerId] };
-    const requestedParams = change.requestedParams || {};
-    const trackingOptionKey =
-      TRACKING_OPTION_KEY_BY_LAYER[change.layerId] || null;
-    let changed = false;
-    for (const spec of optionSpecs(ownerId)) {
-      // Only persist keys present in this explicit request. getLayerParams()
-      // can return a wider live snapshot containing transient or passively
-      // changed values that this user action did not own. Tracking is the one
-      // exception: an unrelated explicit option cancels a pending restoration
-      // in that family, so its wider live value (active ID or null) must replace
-      // the formerly durable pending ID instead of allowing reload resurrection.
-      const explicitlyRequested = Object.hasOwn(requestedParams, spec.key);
-      const implicitTrackingSync =
-        !explicitlyRequested && spec.key === trackingOptionKey;
-      if (!explicitlyRequested && !implicitTrackingSync) continue;
-      const value = spec.normalize(change.params[spec.key]);
-      if (value === null) {
-        if (implicitTrackingSync) {
-          nextOwnerOptions[spec.key] = null;
-          changed = true;
-          continue;
-        }
-        if (spec.defaultValue !== null || change.params[spec.key] !== null)
-          continue;
-      }
-      nextOwnerOptions[spec.key] = value;
-      changed = true;
-    }
-    if (!changed) return;
-    this._commitExplicit({
-      ...this._durableState,
-      options: { ...this._durableState.options, [ownerId]: nextOwnerOptions },
-    });
-  }
-
-  _commitExplicit(candidate) {
-    this._durableState = normalizeLayerState(candidate);
-    const serialized = serializeStoredLayerState(this._durableState);
-    try {
-      if (this.storage?.getItem?.(LAYER_STATE_STORAGE_KEY) !== serialized) {
-        this.storage?.setItem?.(LAYER_STATE_STORAGE_KEY, serialized);
-      }
-    } catch {
-      /* storage can be unavailable or quota-limited */
-    }
-    this.shareLinkManager?.onLayerStateChange?.();
-    this._notifyDurableState();
-  }
-
-  async _waitForRestoreGate() {
-    if (!this.restoreGate) return;
-    await (typeof this.restoreGate === 'function'
-      ? this.restoreGate()
-      : this.restoreGate);
-  }
-
-  async _restoreSelectedState(origin) {
-    for (const entry of LAYER_STATE_REGISTRY) {
-      this._restoreControllers.set(entry.id, new AbortController());
-    }
-    try {
-      await this._waitForRestoreGate();
-      const enabled = new Set(this._durableState.enabledLayerIds);
-      const settled = await Promise.allSettled(
-        LAYER_STATE_REGISTRY.map(async (entry) => {
-          const controller = this._restoreControllers.get(entry.id);
-          const targetEnabled = enabled.has(entry.id);
-          const options = layerOptionsForRestore(this._durableState, entry.id);
-          if (origin === LAYER_RESTORE_ORIGINS.share && options) {
-            for (const trackingKey of Object.values(
-              TRACKING_OPTION_KEY_BY_LAYER,
-            )) {
-              delete options[trackingKey];
-            }
-          }
-          if (this._destroyed || controller?.signal.aborted) {
-            return {
-              layerId: entry.id,
-              targetEnabled,
-              origin,
-              phase: 'reserved',
-              ...currentLayerOutcome(this.dataManager, entry.id),
-              appliedOptions: {},
-              cancellationReason: this._destroyed ? 'destroyed' : 'superseded',
-              errorClass: 'cancelled',
-              persistenceWrite: false,
-              succeeded: false,
-            };
-          }
-          // Reserve passive option state before any asynchronous lifecycle work.
-          // A later explicit params intent then wins on its own lane without
-          // cancelling or being overwritten by the visibility restore.
-          const paramsSucceeded =
-            !options ||
-            Object.keys(options).length === 0 ||
-            this.dataManager.setLayerParams(entry.id, options, { origin });
-          return this.dataManager
-            .restoreLayerState(
-              entry.id,
-              {
-                enabled: targetEnabled,
-                params: null,
-              },
-              { origin, signal: controller.signal },
-            )
-            .then((result) => ({
-              ...result,
-              appliedOptions: paramsSucceeded && options ? options : {},
-              errorClass: paramsSucceeded
-                ? result.errorClass
-                : 'ParamsRejected',
-              succeeded: paramsSucceeded && result.succeeded,
-            }));
-        }),
-      );
-      this.lastRestoreResults = settled.map((result, index) => {
-        if (result.status === 'fulfilled') return result.value;
-        const entry = LAYER_STATE_REGISTRY[index];
-        return {
-          layerId: entry.id,
-          targetEnabled: enabled.has(entry.id),
-          origin,
-          phase: 'coordinator',
-          ...currentLayerOutcome(this.dataManager, entry.id),
-          appliedOptions: {},
-          cancellationReason: null,
-          errorClass: result.reason?.name || 'Error',
-          error: String(result.reason?.message || result.reason),
-          persistenceWrite: false,
-          succeeded: false,
-        };
-      });
-      return this.lastRestoreResults.map((result) => ({ ...result }));
-    } finally {
-      this._restoreControllers.clear();
-      this._notifyDurableState();
-    }
-  }
-
-  _selectedShareTrackingTarget() {
-    if (this._source !== 'share') return null;
-    for (const [layerId, policy] of Object.entries(
-      SHARE_TRACKING_RESTORE_POLICIES,
-    )) {
-      const targetId =
-        this._durableState.options?.[policy.optionOwner]?.[policy.optionKey];
-      if (targetId !== null && targetId !== undefined && targetId !== '') {
-        return { layerId, targetId, ...policy };
-      }
-    }
-    return null;
-  }
-
-  _passivelyClearTrackingSelection(selected) {
-    const current =
-      this._durableState.options?.[selected.optionOwner]?.[selected.optionKey];
-    if (String(current) !== String(selected.targetId)) return false;
-    const ownerOptions = {
-      ...this._durableState.options[selected.optionOwner],
-      [selected.optionKey]: null,
-    };
-    this._durableState = normalizeLayerState({
-      ...this._durableState,
-      options: {
-        ...this._durableState.options,
-        [selected.optionOwner]: ownerOptions,
-      },
-    });
-    this.dataManager.setLayerParams?.(
-      selected.layerId,
-      { [selected.optionKey]: null },
-      { origin: LAYER_RESTORE_ORIGINS.share },
-    );
-    this.shareLinkManager?.onLayerStateChange?.();
-    this._notifyDurableState();
-    return true;
-  }
-
-  /**
-   * `atMs` is the moment the subject was first found ABSENT, not the moment the
-   * verdict is delivered. Waiting out the pending window must not by itself
-   * push a fresh link into the "expired" wording — that word describes the
-   * SHARE's age, not how long this client watched for the subject.
-   */
-  _classifyMissingTrackingTarget(selected, atMs = this.now()) {
-    const copiedAt = this._shareCreatedAtMs;
-    if (!Number.isFinite(copiedAt)) return 'unavailable';
-    const ageMs = atMs - copiedAt;
-    return ageMs > selected.expiryWindowMs ? 'expired' : 'unavailable';
-  }
-
-  /** Whether the owning layer currently follows the shared subject. */
-  _trackingTargetLatched(selected) {
-    const params = this.dataManager.getLayerParams?.(selected.layerId);
-    const active = params?.[selected.optionKey];
-    return (
-      active !== null &&
-      active !== undefined &&
-      String(active) === String(selected.targetId)
-    );
-  }
-
-  /** Stop watching a pending shared subject without deciding its fate. */
-  _cancelPendingTrackingWatch() {
-    if (this._pendingTrackingTimer !== null)
-      this.clearTimer(this._pendingTrackingTimer);
-    this._pendingTrackingTimer = null;
-    const pending = this._pendingTrackingContext;
-    if (pending?.signal && pending.abortHandler) {
-      pending.signal.removeEventListener('abort', pending.abortHandler);
-      pending.abortHandler = null;
-    }
-  }
-
-  /** Publish a share-follow lifecycle update without allowing UI errors to own state. */
-  _publishTrackingRestoreStatus(status) {
-    try {
-      this.onTrackingRestoreStatus?.(status);
-    } catch {
-      /* status UI is best effort */
-    }
-  }
-
-  /**
-   * Revoke a pending shared Follow wholesale.
-   *
-   * The watch and the LAYER's own deferred-restore latch are two halves of one
-   * mechanism, so they must die together. Aborting only the restore controller
-   * left the timer alive: the controller has already settled by the time the
-   * watch exists, so the abort was a no-op and the orphaned timer went on to
-   * announce "Shared … unavailable" for a subject whose latch had been
-   * cancelled — a notice about work no longer being attempted.
-   */
-  _revokePendingTrackingWatch(reason) {
-    this._trackingRestoreController?.abort(reason);
-    this._trackingRestoreGeneration += 1;
-    this._cancelPendingTrackingWatch();
-    const pending = this._pendingTrackingContext;
-    this._pendingTrackingContext = null;
-    if (pending) {
-      this.dataManager.cancelPendingLayerRestore?.(pending.selected.layerId, {
-        origin: LAYER_RESTORE_ORIGINS.share,
-        reason: String(reason || 'cancelled'),
-      });
-      this._publishTrackingRestoreStatus({
-        ...pending.probe,
-        ...pending.selected,
-        status: 'cancelled',
-        classification: 'cancelled',
-        reason: String(reason || 'cancelled'),
-        cleared: false,
-      });
-    }
-  }
-
-  /**
-   * Hold a not-yet-arrived shared subject PENDING instead of declaring it gone.
-   *
-   * A recipient's first authoritative refresh routinely lands without a given
-   * contact — the feed is polled, coverage is partial, and rendering trails the
-   * snapshot by a poll. Reload-from-local already survives this: its restore
-   * arms the layer's own deferred-restore latch, which re-attempts on every
-   * later poll. The shared path used to decide on that single refresh, clear
-   * the subject from durable state AND from the URL, then post a failure notice
-   * seconds into startup — so the same link healed on reload but never on the
-   * share.
-   *
-   * Arm the SAME latch, then watch it in the background: the caller is never
-   * blocked (startup must not wait out a 90 s window before it may write the
-   * URL again), and the terminal verdict is deferred until the source-specific
-   * window has genuinely expired. The existing wordings are unchanged.
-   */
-  async _beginPendingTrackingRestore(selected, probe, signal = null) {
-    const generation = this._trackingRestoreGeneration;
-    const absentAtMs = this.now();
-    // Arm the layer's deferred-restore latch under the passive share origin, so
-    // it re-attempts each poll and never rewrites recipient preferences.
-    let armed = false;
-    let armError = null;
-    try {
-      armed =
-        (await this.dataManager.setLayerParams?.(
-          selected.layerId,
-          { [selected.optionKey]: selected.targetId },
-          { origin: LAYER_RESTORE_ORIGINS.share },
-        )) === true;
-    } catch (error) {
-      armError = error;
-    }
-    if (
-      this._destroyed ||
-      generation !== this._trackingRestoreGeneration ||
-      signal?.aborted
-    ) {
-      if (armed) {
-        this.dataManager.cancelPendingLayerRestore?.(selected.layerId, {
-          origin: LAYER_RESTORE_ORIGINS.share,
-          reason: String(signal?.reason || 'superseded'),
-        });
-      }
-      return {
-        ...probe,
-        ...selected,
-        status: 'cancelled',
-        classification: 'cancelled',
-        reason: String(signal?.reason || 'superseded'),
-        cleared: false,
-      };
-    }
-    if (!armed) {
-      const terminal = {
-        ...probe,
-        ...selected,
-        status: 'source-unavailable',
-        classification: 'source-unavailable',
-        reason: String(
-          armError?.message || armError || 'tracking restore latch rejected',
-        ),
-        cleared: this._passivelyClearTrackingSelection(selected),
-      };
-      this._publishTrackingRestoreStatus(terminal);
-      return terminal;
-    }
-    const deadline = this.now() + selected.expiryWindowMs;
-    const settle = (terminal) => {
-      if (this._pendingTrackingContext?.generation !== generation) return;
-      this._cancelPendingTrackingWatch();
-      this._pendingTrackingContext = null;
-      this._publishTrackingRestoreStatus(terminal);
-    };
-    const poll = () => {
-      this._pendingTrackingTimer = null;
-      if (this._destroyed || generation !== this._trackingRestoreGeneration)
-        return;
-      // The layer that owns the latch may have gone away since the last tick
-      // (disable, teardown, replacement). There is nothing left attempting this
-      // restore, so abandon it silently rather than announcing a verdict.
-      if (this.dataManager.isEffectivelyEnabled?.(selected.layerId) === false) {
-        this._revokePendingTrackingWatch('owner-layer-disabled');
-        return;
-      }
-      if (this._trackingTargetLatched(selected)) {
-        settle({
-          ...probe,
-          ...selected,
-          status: 'found',
-          classification: 'followed',
-          cleared: false,
-        });
-        return;
-      }
-      if (this.now() >= deadline) {
-        // The window really has elapsed — only now does the verdict apply.
-        const classification =
-          probe.status === 'missing'
-            ? this._classifyMissingTrackingTarget(selected, absentAtMs)
-            : 'source-unavailable';
-        const cleared = this._passivelyClearTrackingSelection(selected);
-        settle({ ...probe, ...selected, classification, cleared });
-        return;
-      }
-      this._pendingTrackingTimer = this.setTimer(
-        poll,
-        PENDING_TRACKING_POLL_MS,
-      );
-      this._pendingTrackingTimer?.unref?.();
-    };
-    this._cancelPendingTrackingWatch();
-    const pending = {
-      ...probe,
-      ...selected,
-      status: 'pending',
-      classification: 'pending',
-      cleared: false,
-    };
-    const pendingContext = {
-      generation,
-      selected,
-      probe,
-      signal,
-      abortHandler: null,
-    };
-    if (signal) {
-      pendingContext.abortHandler = () => {
-        if (this._pendingTrackingContext?.generation !== generation) return;
-        this._revokePendingTrackingWatch(signal.reason || 'aborted');
-      };
-      signal.addEventListener('abort', pendingContext.abortHandler, {
-        once: true,
-      });
-    }
-    this._pendingTrackingContext = pendingContext;
-    this._publishTrackingRestoreStatus(pending);
-    this._pendingTrackingTimer = this.setTimer(poll, PENDING_TRACKING_POLL_MS);
-    this._pendingTrackingTimer?.unref?.();
-    return pending;
-  }
-
-  /**
-   * Refresh and restore the one shareable tracked target after destination
-   * camera and ordinary layer restoration have settled.
-   */
-  async restoreShareTrackingSelection({ signal = null } = {}) {
-    const selected = this._selectedShareTrackingTarget();
-    if (!selected || this._destroyed)
-      return { status: 'skipped', reason: 'no-shared-target' };
-    this._revokePendingTrackingWatch('superseded-by-newer-restore');
-    const controller = new AbortController();
-    const combinedSignal = signal
-      ? AbortSignal.any([signal, controller.signal])
-      : controller.signal;
-    this._trackingRestoreController = controller;
-    const generation = ++this._trackingRestoreGeneration;
-    let result;
-    try {
-      result = await this.dataManager.resolveLayerTrackingTarget(
-        selected.layerId,
-        selected.targetId,
-        { signal: combinedSignal, origin: LAYER_RESTORE_ORIGINS.share },
-      );
-    } catch (error) {
-      result = combinedSignal.aborted
-        ? {
-            status: 'cancelled',
-            reason: String(combinedSignal.reason || 'aborted'),
-          }
-        : {
-            status: 'source-unavailable',
-            reason: String(error?.message || error),
-          };
-    }
-    if (
-      generation !== this._trackingRestoreGeneration ||
-      this._destroyed ||
-      combinedSignal.aborted
-    ) {
-      if (this._trackingRestoreController === controller)
-        this._trackingRestoreController = null;
-      return {
-        ...result,
-        status: 'cancelled',
-        reason: String(combinedSignal.reason || 'superseded'),
-      };
-    }
-    if (this._trackingRestoreController === controller)
-      this._trackingRestoreController = null;
-
-    if (result.status === 'found') {
-      const terminal = {
-        ...result,
-        ...selected,
-        classification: 'followed',
-        cleared: false,
-      };
-      this._publishTrackingRestoreStatus(terminal);
-      return terminal;
-    }
-    if (['cancelled', 'superseded', 'destroyed'].includes(result.status))
-      return result;
-
-    // A subject that is simply not here YET is not a subject that is gone. Hold
-    // it on the layer's own deferred-restore latch for its source-specific
-    // window before any verdict is reached or shown. `unsupported` layers have
-    // no latch to arm, so they still decide immediately.
-    if (result.status === 'missing' || result.status === 'source-unavailable') {
-      return this._beginPendingTrackingRestore(
-        selected,
-        result,
-        combinedSignal,
-      );
-    }
-
-    const classification =
-      result.status === 'missing'
-        ? this._classifyMissingTrackingTarget(selected)
-        : 'source-unavailable';
-    const cleared = this._passivelyClearTrackingSelection(selected);
-    const terminal = { ...result, ...selected, classification, cleared };
-    this._publishTrackingRestoreStatus(terminal);
-    return terminal;
-  }
-
-  destroy() {
-    if (this._destroyed) return;
-    this._destroyed = true;
-    for (const controller of this._restoreControllers.values())
-      controller.abort('coordinator-destroyed');
-    this._restoreControllers.clear();
-    this._revokePendingTrackingWatch('coordinator-destroyed');
-    this._trackingRestoreController = null;
-    this._unsubscribe?.();
-    this._unsubscribe = null;
-    this._unsubscribeVisibilityRequests?.();
-    this._unsubscribeVisibilityRequests = null;
-    this.shareLinkManager?.setLayerStateProvider?.(null);
-    this.onDurableStateChange = null;
-    this.onTrackingRestoreStatus = null;
-  }
-}

src/data/layerState.test.mjs

@@ -1,3 +1,4 @@
+import { encodeParams, decodeParams } from '../layers/streetLevel/params.js';
 import { readShellSource } from '../testSupport/readShellSource.mjs';
 import { expandApplicationHtml } from '../../build/application-html.js';
 import { readLayerSource } from '../testSupport/readLayerSource.mjs';
@@ -11,7 +12,6 @@ import {
   LAYER_STATE_STORAGE_KEY,
   LAYER_STATE_TOKEN_ALPHABET,
   LAYER_STATE_TOKEN_RESERVATIONS,
-  LayerStateCoordinator,
   REGISTERED_LAYER_IDS,
   SHARE_TRACKING_RESTORE_POLICIES,
   createDefaultLayerState,
@@ -24,8 +24,11 @@ import {
   validateLayerStateAllocations,
   validateLayerStateRegistry,
 } from './layerState.js';
+import { LayerStateCoordinator } from './layerStateCoordinator.js';
 import radioLayer from './radio.js';
 import { stampInitialShareGesture } from '../navigationPolicy.js';
+import { MAX_SINCE_DAYS } from '../layers/streetLevel/policy.js';
+import { SINCE_STOPS } from '../ui/streetLevelPresentation.js';
 
 function deferred() {
   let resolve;
@@ -199,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, 28);
-  assert.equal(new Set(REGISTERED_LAYER_IDS).size, 28);
+  assert.equal(REGISTERED_LAYER_IDS.length, 29);
+  assert.equal(new Set(REGISTERED_LAYER_IDS).size, 29);
   assert.ok(REGISTERED_LAYER_IDS.includes('transit'));
   assert.deepEqual(REGISTERED_LAYER_IDS, [...REGISTERED_LAYER_IDS].sort());
   assert.deepEqual(LEGACY_LAYER_STATE_TOKENS, {
@@ -239,15 +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(), '0');
+  assert.equal(nextLayerStateToken(), '3');
   assert.equal(
-    nextLayerStateToken({ ...LAYER_STATE_TOKEN_RESERVATIONS, alpha: '0', bravo: '3' }),
-    '4',
+    nextLayerStateToken({
+      ...LAYER_STATE_TOKEN_RESERVATIONS,
+      alpha: '3',
+      bravo: '4',
+    }),
+    '5',
   );
   const digitsExhausted = {
     ...LAYER_STATE_TOKEN_RESERVATIONS,
     ...Object.fromEntries(
-      [...'03456789'].map((digit) => [`prior-${digit}`, digit]),
+      [...'3456789'].map((digit) => [`prior-${digit}`, digit]),
     ),
   };
   assert.equal(nextLayerStateToken(digitsExhausted), '00');
@@ -274,7 +281,9 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
           [
             ...'0123456789',
             ...[...LAYER_STATE_TOKEN_ALPHABET].flatMap((first) =>
-              [...LAYER_STATE_TOKEN_ALPHABET].map((second) => `${first}${second}`),
+              [...LAYER_STATE_TOKEN_ALPHABET].map(
+                (second) => `${first}${second}`,
+              ),
             ),
           ].map((token, index) => [`occupied-${index}`, token]),
         ),
@@ -296,42 +305,46 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
     true,
   );
   assert.equal(
-    validateLayerStateAllocations(
-      LAYER_STATE_TOKEN_RESERVATIONS,
-      { ...LAYER_STATE_TOKEN_RESERVATIONS, future: '0', next: '3' },
-    ),
+    validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
+      ...LAYER_STATE_TOKEN_RESERVATIONS,
+      future: '3',
+      next: '4',
+    }),
     true,
   );
   assert.throws(
-    () => validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
-      ...LAYER_STATE_TOKEN_RESERVATIONS,
-      future: '00',
-    }),
-    /next free token 0/,
+    () =>
+      validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
+        ...LAYER_STATE_TOKEN_RESERVATIONS,
+        future: '00',
+      }),
+    /next free token 3/,
   );
   const beforeLastDigit = { ...digitsExhausted };
   delete beforeLastDigit['prior-9'];
   assert.equal(
-    validateLayerStateAllocations(
-      beforeLastDigit,
-      { ...beforeLastDigit, futurePair: '00', futureDigit: '9' },
-    ),
+    validateLayerStateAllocations(beforeLastDigit, {
+      ...beforeLastDigit,
+      futurePair: '00',
+      futureDigit: '9',
+    }),
     true,
   );
   assert.equal(
-    validateLayerStateAllocations(
-      digitsExhausted,
-      { ...digitsExhausted, pairB: '01', pairA: '00' },
-    ),
+    validateLayerStateAllocations(digitsExhausted, {
+      ...digitsExhausted,
+      pairB: '01',
+      pairA: '00',
+    }),
     true,
   );
   assert.throws(
     () =>
       validateLayerStateAllocations(
-        { ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '0' },
-        { ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '0', competing: '0' },
+        { ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '3' },
+        { ...LAYER_STATE_TOKEN_RESERVATIONS, merged: '3', competing: '3' },
       ),
-    /next free token 3/,
+    /next free token 4/,
   );
   assert.throws(
     () => validateLayerStateAllocations({ future: '00' }, { future: '01' }),
@@ -2642,3 +2655,135 @@ test('fire perimeters uses digit 2 without colliding with wind or recent imagery
     decoded,
   );
 });
+
+/** Street Level options decoded from a v2 link with these `lo` assignments. */
+function streetLevelOptions(lo) {
+  const params = new URLSearchParams([
+    ['v', '2'],
+    ['l', '0'],
+  ]);
+  if (lo) params.set('lo', lo);
+  return decodeLayerStateParams(params).options['street-level'];
+}
+
+test('Street Level: every option round-trips through a share link and stored state', () => {
+  const state = createDefaultLayerState();
+  state.enabledLayerIds = ['street-level'];
+  state.options['street-level'] = {
+    mapillary: false,
+    providerSwitches: '',
+    pano: 'flat',
+    sinceDays: MAX_SINCE_DAYS,
+  };
+  const decoded = decodeLayerStateParams(new URLSearchParams(encode(state)));
+  assert.deepEqual(decoded.options['street-level'], {
+    mapillary: false,
+    providerSwitches: '',
+    pano: 'flat',
+    sinceDays: MAX_SINCE_DAYS,
+  });
+  assert.deepEqual(
+    parseStoredLayerState(serializeStoredLayerState(state)).options[
+      'street-level'
+    ],
+    state.options['street-level'],
+  );
+});
+
+test('Street Level: the link codec accepts exactly the windows the filter keeps', () => {
+  // A window past MAX_SINCE_DAYS reads as "any date".
+  assert.equal(
+    streetLevelOptions(`0.s.${MAX_SINCE_DAYS}`).sinceDays,
+    MAX_SINCE_DAYS,
+  );
+  assert.equal(streetLevelOptions(`0.s.${MAX_SINCE_DAYS + 1}`).sinceDays, 0);
+  // Every SINCE slider stop survives, the LAST 10 YEARS one included.
+  for (const { days } of SINCE_STOPS)
+    assert.equal(streetLevelOptions(`0.s.${days}`).sinceDays, days);
+  assert.equal(streetLevelOptions('0.s.3652').sinceDays, 3652);
+});
+
+test('Street Level: a link without the provider switch keeps Mapillary on', () => {
+  assert.deepEqual(streetLevelOptions(''), {
+    mapillary: true,
+    providerSwitches: '',
+    pano: 'all',
+    sinceDays: 0,
+  });
+  assert.equal(streetLevelOptions('0.p.f').mapillary, true);
+  assert.equal(streetLevelOptions('0.m.0').mapillary, false);
+  assert.equal(
+    createDefaultLayerState().options['street-level'].mapillary,
+    true,
+  );
+});
+
+test('explicit provider switches reach durable state without adopting unrelated live switches', () => {
+  const manager = new DataLayerManager({});
+  const providers = new Map([
+    ['mapillary', true],
+    ['alpha', true],
+    ['beta', true],
+  ]);
+  const filter = { pano: 'all', sinceDays: 0 };
+  for (const id of REGISTERED_LAYER_IDS) {
+    manager.register(
+      id === 'street-level'
+        ? {
+            ...fakeLayer(id),
+            getParams: () => encodeParams({ providers, filter }),
+            setParams(params) {
+              const decoded = decodeParams(params, {
+                providerIds: providers.keys(),
+                filter,
+              });
+              for (const [id, on] of decoded.providers) providers.set(id, on);
+              return true;
+            },
+          }
+        : fakeLayer(id),
+    );
+  }
+  manager.finalizeRegistrations(LAYER_STATE_REGISTRY);
+  const storage = memoryStorage();
+  const coordinator = new LayerStateCoordinator(manager, shareSink(), {
+    storage,
+  });
+  try {
+    providers.set('beta', false); // Passive state does not belong to the next action.
+    assert.equal(
+      manager.setLayerParams(
+        'street-level',
+        { alpha: false },
+        { origin: 'user' },
+      ),
+      true,
+    );
+    let saved = parseStoredLayerState(storage.getItem(LAYER_STATE_STORAGE_KEY));
+    assert.equal(saved.options['street-level'].providerSwitches, 'alpha-0');
+    const shared = decodeLayerStateParams(new URLSearchParams(encode(saved)));
+    const restored = decodeParams(shared.options['street-level'], {
+      providerIds: ['beta', 'alpha'],
+      filter,
+    });
+    assert.deepEqual([...restored.providers], [['alpha', false]]);
+    manager.setLayerParams('street-level', { beta: true }, { origin: 'user' });
+    saved = parseStoredLayerState(storage.getItem(LAYER_STATE_STORAGE_KEY));
+    assert.equal(
+      saved.options['street-level'].providerSwitches,
+      'alpha-0*beta-1',
+    );
+    manager.setLayerParams(
+      'street-level',
+      { alpha: true },
+      { origin: 'local-restore' },
+    );
+    saved = parseStoredLayerState(storage.getItem(LAYER_STATE_STORAGE_KEY));
+    assert.equal(
+      saved.options['street-level'].providerSwitches,
+      'alpha-0*beta-1',
+    );
+  } finally {
+    coordinator.destroy();
+  }
+});

src/data/layerStateCoordinator.js

@@ -0,0 +1,756 @@
+/**
+ * Applies layer state to the running application: restores shared and stored
+ * layer choices and persists changes to browser storage.
+ */
+
+import {
+  LAYER_RESTORE_ORIGINS,
+  LAYER_STATE_REGISTRY,
+  LAYER_STATE_STORAGE_KEY,
+  REGISTRY_BY_ID,
+  SHARE_TRACKING_RESTORE_POLICIES,
+  cloneLayerState,
+  createDefaultLayerState,
+  isExplicitLayerStateOrigin,
+  layerOptionsForRestore,
+  normalizeLayerState,
+  optionSpecs,
+  parseStoredLayerState,
+  serializeStoredLayerState,
+} from './layerState.js';
+
+/** Re-check cadence while a shared subject waits for its feed row to arrive. */
+const PENDING_TRACKING_POLL_MS = 1_000;
+
+const TRACKING_OPTION_KEY_BY_LAYER = Object.freeze({
+  flights: 'selectedFlightsTrackingId',
+  military: 'selectedMilitaryTrackingId',
+  satellites: 'selectedSatTrackingId',
+});
+
+function safeStorage() {
+  try {
+    return globalThis.localStorage || null;
+  } catch {
+    return null;
+  }
+}
+
+function currentLayerOutcome(dataManager, layerId) {
+  const state = dataManager.getLayerLifecycleState?.(layerId);
+  return {
+    settledEnabled: Boolean(state?.enabled),
+    lifecycleState: state?.lifecycleState || 'missing',
+    lifecycleUncertain: Boolean(state?.uncertain),
+  };
+}
+
+/**
+ * Owns durable user layer preferences independently from transient runtime
+ * choreography, and coordinates passive post-registration restoration.
+ */
+export class LayerStateCoordinator {
+  constructor(
+    dataManager,
+    shareLinkManager,
+    {
+      storage = safeStorage(),
+      restoreGate = null,
+      onDurableStateChange = null,
+      onTrackingRestoreStatus = null,
+      now = () => Date.now(),
+      // Injectable so the pending-window behavior is deterministically testable
+      // without sleeping out a 90 s expiry.
+      setTimer = (fn, ms) => setTimeout(fn, ms),
+      clearTimer = (handle) => clearTimeout(handle),
+    } = {},
+  ) {
+    if (!dataManager?.registrationsFinalized) {
+      throw new Error(
+        'Layer state requires finalized data-layer registrations',
+      );
+    }
+    this.dataManager = dataManager;
+    this.shareLinkManager = shareLinkManager || null;
+    this.storage = storage;
+    this.restoreGate = restoreGate;
+    this.onDurableStateChange = onDurableStateChange;
+    this.onTrackingRestoreStatus = onTrackingRestoreStatus;
+    this.now = now;
+    this.setTimer = setTimer;
+    this.clearTimer = clearTimer;
+    this._durableState = createDefaultLayerState();
+    this._source = 'defaults';
+    this._destroyed = false;
+    this._restoreControllers = new Map();
+    this._shareCreatedAtMs = null;
+    this._trackingRestoreController = null;
+    this._trackingRestoreGeneration = 0;
+    this._pendingTrackingTimer = null;
+    this._pendingTrackingContext = null;
+    this._unsubscribe = this.dataManager.subscribe((change) =>
+      this._handleManagerChange(change),
+    );
+    this._unsubscribeVisibilityRequests =
+      this.dataManager.subscribeVisibilityRequests((change) =>
+        this._handleVisibilityRequest(change),
+      );
+    this.restorePromise = Promise.resolve([]);
+    this.lastRestoreResults = [];
+  }
+
+  start({
+    shareLayerState = null,
+    allowLocalState = true,
+    shareCreatedAtMs = null,
+  } = {}) {
+    if (this._destroyed)
+      throw new Error('Layer-state coordinator is destroyed');
+    let selected = shareLayerState
+      ? normalizeLayerState(shareLayerState)
+      : null;
+    if (selected) {
+      this._source = 'share';
+      this._shareCreatedAtMs = Number.isFinite(shareCreatedAtMs)
+        ? shareCreatedAtMs
+        : null;
+    } else if (allowLocalState) {
+      let stored = null;
+      try {
+        stored = parseStoredLayerState(
+          this.storage?.getItem?.(LAYER_STATE_STORAGE_KEY),
+        );
+      } catch {
+        /* best effort */
+      }
+      if (stored) {
+        selected = stored;
+        this._source = 'local';
+      }
+    } else {
+      // A valid historical camera/style share with no v2 layer payload keeps
+      // the exact legacy default-layer behavior. It must not inherit an
+      // unrelated recipient's saved local layer preferences.
+      this._source = 'legacy-share';
+    }
+    this._durableState = selected || createDefaultLayerState();
+    this.shareLinkManager?.setLayerStateProvider?.(() =>
+      this.getDurableState(),
+    );
+    this.shareLinkManager?.onLayerStateChange?.();
+    this._notifyDurableState();
+    if (!selected) return this.restorePromise;
+    this.restorePromise = this._restoreSelectedState(
+      this._source === 'share'
+        ? LAYER_RESTORE_ORIGINS.share
+        : LAYER_RESTORE_ORIGINS.local,
+    );
+    return this.restorePromise;
+  }
+
+  get source() {
+    return this._source;
+  }
+
+  getDurableState() {
+    return cloneLayerState(this._durableState);
+  }
+
+  _notifyDurableState() {
+    try {
+      this.onDurableStateChange?.(this.getDurableState());
+    } catch {
+      /* UI sync is best effort */
+    }
+  }
+
+  _handleVisibilityRequest(change) {
+    if (!isExplicitLayerStateOrigin(change?.origin)) return;
+    this._restoreControllers
+      .get(change.layerId)
+      ?.abort('superseded-by-explicit-visibility');
+    if (SHARE_TRACKING_RESTORE_POLICIES[change.layerId]) {
+      this._revokePendingTrackingWatch('superseded-by-explicit-visibility');
+    }
+  }
+
+  /** Revoke every passive restore before explicit navigation can be reclaimed. */
+  cancelPendingRestores(reason = 'superseded-by-explicit-navigation') {
+    for (const controller of this._restoreControllers.values())
+      controller.abort(reason);
+    this._revokePendingTrackingWatch(reason);
+  }
+
+  /**
+   * Revoke a pending shared Follow. Physical navigation may also clear only
+   * the exact passive selection, without writing recipient preferences.
+   */
+  cancelPendingShareTracking(
+    reason = 'superseded-by-explicit-navigation',
+    { clearSelection = false } = {},
+  ) {
+    this._revokePendingTrackingWatch(reason);
+    if (!clearSelection) return false;
+    const selected = this._selectedShareTrackingTarget();
+    return selected ? this._passivelyClearTrackingSelection(selected) : false;
+  }
+
+  _handleManagerChange(change) {
+    if (!change || this._destroyed) return;
+    // Parameter and visibility ownership are independent. A newer explicit
+    // option request may replace passive share options, but it must not abort
+    // the same layer's visibility lifecycle.
+    if (change.type === 'params-requested') {
+      if (
+        isExplicitLayerStateOrigin(change.origin) &&
+        SHARE_TRACKING_RESTORE_POLICIES[change.layerId]
+      ) {
+        this._revokePendingTrackingWatch('superseded-by-explicit-params');
+      }
+      return;
+    }
+    // A layer that goes away takes its latch with it, at ANY origin — a
+    // programmatic disable or teardown never reaches the explicit-intent path
+    // below, so revoke here before that early return.
+    if (
+      change.type === 'visibility' &&
+      change.enabled === false &&
+      SHARE_TRACKING_RESTORE_POLICIES[change.layerId]
+    ) {
+      this._revokePendingTrackingWatch('owner-layer-disabled');
+    }
+    if (!isExplicitLayerStateOrigin(change.origin)) return;
+    if (change.type === 'visibility') {
+      this._restoreControllers
+        .get(change.layerId)
+        ?.abort('superseded-by-explicit-visibility');
+      if (SHARE_TRACKING_RESTORE_POLICIES[change.layerId]) {
+        this._revokePendingTrackingWatch('superseded-by-explicit-visibility');
+      }
+      const enabled = new Set(this._durableState.enabledLayerIds);
+      if (change.enabled) enabled.add(change.layerId);
+      else enabled.delete(change.layerId);
+      this._commitExplicit({
+        ...this._durableState,
+        enabledLayerIds: [...enabled],
+      });
+      return;
+    }
+    if (change.type !== 'params') return;
+    const entry = REGISTRY_BY_ID.get(change.layerId);
+    if (!entry?.optionOwner) return;
+    const ownerId = entry.optionOwner;
+    const nextOwnerOptions = { ...this._durableState.options[ownerId] };
+    const requestedParams = change.requestedParams || {};
+    const trackingOptionKey =
+      TRACKING_OPTION_KEY_BY_LAYER[change.layerId] || null;
+    let changed = false;
+    for (const spec of optionSpecs(ownerId)) {
+      // Only persist keys present in this explicit request. getLayerParams()
+      // can return a wider live snapshot containing transient or passively
+      // changed values that this user action did not own. Tracking is the one
+      // exception: an unrelated explicit option cancels a pending restoration
+      // in that family, so its wider live value (active ID or null) must replace
+      // the formerly durable pending ID instead of allowing reload resurrection.
+      const explicitlyRequested = Object.hasOwn(requestedParams, spec.key);
+      const implicitTrackingSync =
+        !explicitlyRequested && spec.key === trackingOptionKey;
+      // Packed options can persist only the subkeys owned by this request.
+      const requestedValue =
+        explicitlyRequested || implicitTrackingSync
+          ? change.params[spec.key]
+          : spec.patchRequested?.(
+              nextOwnerOptions[spec.key],
+              change.params[spec.key],
+              requestedParams,
+            );
+      if (
+        !explicitlyRequested &&
+        !implicitTrackingSync &&
+        requestedValue === undefined
+      )
+        continue;
+      const value = spec.normalize(requestedValue);
+      if (value === null) {
+        if (implicitTrackingSync) {
+          nextOwnerOptions[spec.key] = null;
+          changed = true;
+          continue;
+        }
+        if (spec.defaultValue !== null || change.params[spec.key] !== null)
+          continue;
+      }
+      nextOwnerOptions[spec.key] = value;
+      changed = true;
+    }
+    if (!changed) return;
+    this._commitExplicit({
+      ...this._durableState,
+      options: { ...this._durableState.options, [ownerId]: nextOwnerOptions },
+    });
+  }
+
+  _commitExplicit(candidate) {
+    this._durableState = normalizeLayerState(candidate);
+    const serialized = serializeStoredLayerState(this._durableState);
+    try {
+      if (this.storage?.getItem?.(LAYER_STATE_STORAGE_KEY) !== serialized) {
+        this.storage?.setItem?.(LAYER_STATE_STORAGE_KEY, serialized);
+      }
+    } catch {
+      /* storage can be unavailable or quota-limited */
+    }
+    this.shareLinkManager?.onLayerStateChange?.();
+    this._notifyDurableState();
+  }
+
+  async _waitForRestoreGate() {
+    if (!this.restoreGate) return;
+    await (typeof this.restoreGate === 'function'
+      ? this.restoreGate()
+      : this.restoreGate);
+  }
+
+  async _restoreSelectedState(origin) {
+    for (const entry of LAYER_STATE_REGISTRY) {
+      this._restoreControllers.set(entry.id, new AbortController());
+    }
+    try {
+      await this._waitForRestoreGate();
+      const enabled = new Set(this._durableState.enabledLayerIds);
+      const settled = await Promise.allSettled(
+        LAYER_STATE_REGISTRY.map(async (entry) => {
+          const controller = this._restoreControllers.get(entry.id);
+          const targetEnabled = enabled.has(entry.id);
+          const options = layerOptionsForRestore(this._durableState, entry.id);
+          if (origin === LAYER_RESTORE_ORIGINS.share && options) {
+            for (const trackingKey of Object.values(
+              TRACKING_OPTION_KEY_BY_LAYER,
+            )) {
+              delete options[trackingKey];
+            }
+          }
+          if (this._destroyed || controller?.signal.aborted) {
+            return {
+              layerId: entry.id,
+              targetEnabled,
+              origin,
+              phase: 'reserved',
+              ...currentLayerOutcome(this.dataManager, entry.id),
+              appliedOptions: {},
+              cancellationReason: this._destroyed ? 'destroyed' : 'superseded',
+              errorClass: 'cancelled',
+              persistenceWrite: false,
+              succeeded: false,
+            };
+          }
+          // Reserve passive option state before any asynchronous lifecycle work.
+          // A later explicit params intent then wins on its own lane without
+          // cancelling or being overwritten by the visibility restore.
+          const paramsSucceeded =
+            !options ||
+            Object.keys(options).length === 0 ||
+            this.dataManager.setLayerParams(entry.id, options, { origin });
+          return this.dataManager
+            .restoreLayerState(
+              entry.id,
+              {
+                enabled: targetEnabled,
+                params: null,
+              },
+              { origin, signal: controller.signal },
+            )
+            .then((result) => ({
+              ...result,
+              appliedOptions: paramsSucceeded && options ? options : {},
+              errorClass: paramsSucceeded
+                ? result.errorClass
+                : 'ParamsRejected',
+              succeeded: paramsSucceeded && result.succeeded,
+            }));
+        }),
+      );
+      this.lastRestoreResults = settled.map((result, index) => {
+        if (result.status === 'fulfilled') return result.value;
+        const entry = LAYER_STATE_REGISTRY[index];
+        return {
+          layerId: entry.id,
+          targetEnabled: enabled.has(entry.id),
+          origin,
+          phase: 'coordinator',
+          ...currentLayerOutcome(this.dataManager, entry.id),
+          appliedOptions: {},
+          cancellationReason: null,
+          errorClass: result.reason?.name || 'Error',
+          error: String(result.reason?.message || result.reason),
+          persistenceWrite: false,
+          succeeded: false,
+        };
+      });
+      return this.lastRestoreResults.map((result) => ({ ...result }));
+    } finally {
+      this._restoreControllers.clear();
+      this._notifyDurableState();
+    }
+  }
+
+  _selectedShareTrackingTarget() {
+    if (this._source !== 'share') return null;
+    for (const [layerId, policy] of Object.entries(
+      SHARE_TRACKING_RESTORE_POLICIES,
+    )) {
+      const targetId =
+        this._durableState.options?.[policy.optionOwner]?.[policy.optionKey];
+      if (targetId !== null && targetId !== undefined && targetId !== '') {
+        return { layerId, targetId, ...policy };
+      }
+    }
+    return null;
+  }
+
+  _passivelyClearTrackingSelection(selected) {
+    const current =
+      this._durableState.options?.[selected.optionOwner]?.[selected.optionKey];
+    if (String(current) !== String(selected.targetId)) return false;
+    const ownerOptions = {
+      ...this._durableState.options[selected.optionOwner],
+      [selected.optionKey]: null,
+    };
+    this._durableState = normalizeLayerState({
+      ...this._durableState,
+      options: {
+        ...this._durableState.options,
+        [selected.optionOwner]: ownerOptions,
+      },
+    });
+    this.dataManager.setLayerParams?.(
+      selected.layerId,
+      { [selected.optionKey]: null },
+      { origin: LAYER_RESTORE_ORIGINS.share },
+    );
+    this.shareLinkManager?.onLayerStateChange?.();
+    this._notifyDurableState();
+    return true;
+  }
+
+  /**
+   * `atMs` is the moment the subject was first found ABSENT, not the moment the
+   * verdict is delivered. Waiting out the pending window must not by itself
+   * push a fresh link into the "expired" wording — that word describes the
+   * SHARE's age, not how long this client watched for the subject.
+   */
+  _classifyMissingTrackingTarget(selected, atMs = this.now()) {
+    const copiedAt = this._shareCreatedAtMs;
+    if (!Number.isFinite(copiedAt)) return 'unavailable';
+    const ageMs = atMs - copiedAt;
+    return ageMs > selected.expiryWindowMs ? 'expired' : 'unavailable';
+  }
+
+  /** Whether the owning layer currently follows the shared subject. */
+  _trackingTargetLatched(selected) {
+    const params = this.dataManager.getLayerParams?.(selected.layerId);
+    const active = params?.[selected.optionKey];
+    return (
+      active !== null &&
+      active !== undefined &&
+      String(active) === String(selected.targetId)
+    );
+  }
+
+  /** Stop watching a pending shared subject without deciding its fate. */
+  _cancelPendingTrackingWatch() {
+    if (this._pendingTrackingTimer !== null)
+      this.clearTimer(this._pendingTrackingTimer);
+    this._pendingTrackingTimer = null;
+    const pending = this._pendingTrackingContext;
+    if (pending?.signal && pending.abortHandler) {
+      pending.signal.removeEventListener('abort', pending.abortHandler);
+      pending.abortHandler = null;
+    }
+  }
+
+  /** Publish a share-follow lifecycle update without allowing UI errors to own state. */
+  _publishTrackingRestoreStatus(status) {
+    try {
+      this.onTrackingRestoreStatus?.(status);
+    } catch {
+      /* status UI is best effort */
+    }
+  }
+
+  /**
+   * Revoke a pending shared Follow wholesale.
+   *
+   * The watch and the LAYER's own deferred-restore latch are two halves of one
+   * mechanism, so they must die together. Aborting only the restore controller
+   * left the timer alive: the controller has already settled by the time the
+   * watch exists, so the abort was a no-op and the orphaned timer went on to
+   * announce "Shared … unavailable" for a subject whose latch had been
+   * cancelled — a notice about work no longer being attempted.
+   */
+  _revokePendingTrackingWatch(reason) {
+    this._trackingRestoreController?.abort(reason);
+    this._trackingRestoreGeneration += 1;
+    this._cancelPendingTrackingWatch();
+    const pending = this._pendingTrackingContext;
+    this._pendingTrackingContext = null;
+    if (pending) {
+      this.dataManager.cancelPendingLayerRestore?.(pending.selected.layerId, {
+        origin: LAYER_RESTORE_ORIGINS.share,
+        reason: String(reason || 'cancelled'),
+      });
+      this._publishTrackingRestoreStatus({
+        ...pending.probe,
+        ...pending.selected,
+        status: 'cancelled',
+        classification: 'cancelled',
+        reason: String(reason || 'cancelled'),
+        cleared: false,
+      });
+    }
+  }
+
+  /**
+   * Hold a not-yet-arrived shared subject PENDING instead of declaring it gone.
+   *
+   * A recipient's first authoritative refresh routinely lands without a given
+   * contact — the feed is polled, coverage is partial, and rendering trails the
+   * snapshot by a poll. Reload-from-local already survives this: its restore
+   * arms the layer's own deferred-restore latch, which re-attempts on every
+   * later poll. The shared path used to decide on that single refresh, clear
+   * the subject from durable state AND from the URL, then post a failure notice
+   * seconds into startup — so the same link healed on reload but never on the
+   * share.
+   *
+   * Arm the SAME latch, then watch it in the background: the caller is never
+   * blocked (startup must not wait out a 90 s window before it may write the
+   * URL again), and the terminal verdict is deferred until the source-specific
+   * window has genuinely expired. The existing wordings are unchanged.
+   */
+  async _beginPendingTrackingRestore(selected, probe, signal = null) {
+    const generation = this._trackingRestoreGeneration;
+    const absentAtMs = this.now();
+    // Arm the layer's deferred-restore latch under the passive share origin, so
+    // it re-attempts each poll and never rewrites recipient preferences.
+    let armed = false;
+    let armError = null;
+    try {
+      armed =
+        (await this.dataManager.setLayerParams?.(
+          selected.layerId,
+          { [selected.optionKey]: selected.targetId },
+          { origin: LAYER_RESTORE_ORIGINS.share },
+        )) === true;
+    } catch (error) {
+      armError = error;
+    }
+    if (
+      this._destroyed ||
+      generation !== this._trackingRestoreGeneration ||
+      signal?.aborted
+    ) {
+      if (armed) {
+        this.dataManager.cancelPendingLayerRestore?.(selected.layerId, {
+          origin: LAYER_RESTORE_ORIGINS.share,
+          reason: String(signal?.reason || 'superseded'),
+        });
+      }
+      return {
+        ...probe,
+        ...selected,
+        status: 'cancelled',
+        classification: 'cancelled',
+        reason: String(signal?.reason || 'superseded'),
+        cleared: false,
+      };
+    }
+    if (!armed) {
+      const terminal = {
+        ...probe,
+        ...selected,
+        status: 'source-unavailable',
+        classification: 'source-unavailable',
+        reason: String(
+          armError?.message || armError || 'tracking restore latch rejected',
+        ),
+        cleared: this._passivelyClearTrackingSelection(selected),
+      };
+      this._publishTrackingRestoreStatus(terminal);
+      return terminal;
+    }
+    const deadline = this.now() + selected.expiryWindowMs;
+    const settle = (terminal) => {
+      if (this._pendingTrackingContext?.generation !== generation) return;
+      this._cancelPendingTrackingWatch();
+      this._pendingTrackingContext = null;
+      this._publishTrackingRestoreStatus(terminal);
+    };
+    const poll = () => {
+      this._pendingTrackingTimer = null;
+      if (this._destroyed || generation !== this._trackingRestoreGeneration)
+        return;
+      // The layer that owns the latch may have gone away since the last tick
+      // (disable, teardown, replacement). There is nothing left attempting this
+      // restore, so abandon it silently rather than announcing a verdict.
+      if (this.dataManager.isEffectivelyEnabled?.(selected.layerId) === false) {
+        this._revokePendingTrackingWatch('owner-layer-disabled');
+        return;
+      }
+      if (this._trackingTargetLatched(selected)) {
+        settle({
+          ...probe,
+          ...selected,
+          status: 'found',
+          classification: 'followed',
+          cleared: false,
+        });
+        return;
+      }
+      if (this.now() >= deadline) {
+        // The window really has elapsed — only now does the verdict apply.
+        const classification =
+          probe.status === 'missing'
+            ? this._classifyMissingTrackingTarget(selected, absentAtMs)
+            : 'source-unavailable';
+        const cleared = this._passivelyClearTrackingSelection(selected);
+        settle({ ...probe, ...selected, classification, cleared });
+        return;
+      }
+      this._pendingTrackingTimer = this.setTimer(
+        poll,
+        PENDING_TRACKING_POLL_MS,
+      );
+      this._pendingTrackingTimer?.unref?.();
+    };
+    this._cancelPendingTrackingWatch();
+    const pending = {
+      ...probe,
+      ...selected,
+      status: 'pending',
+      classification: 'pending',
+      cleared: false,
+    };
+    const pendingContext = {
+      generation,
+      selected,
+      probe,
+      signal,
+      abortHandler: null,
+    };
+    if (signal) {
+      pendingContext.abortHandler = () => {
+        if (this._pendingTrackingContext?.generation !== generation) return;
+        this._revokePendingTrackingWatch(signal.reason || 'aborted');
+      };
+      signal.addEventListener('abort', pendingContext.abortHandler, {
+        once: true,
+      });
+    }
+    this._pendingTrackingContext = pendingContext;
+    this._publishTrackingRestoreStatus(pending);
+    this._pendingTrackingTimer = this.setTimer(poll, PENDING_TRACKING_POLL_MS);
+    this._pendingTrackingTimer?.unref?.();
+    return pending;
+  }
+
+  /**
+   * Refresh and restore the one shareable tracked target after destination
+   * camera and ordinary layer restoration have settled.
+   */
+  async restoreShareTrackingSelection({ signal = null } = {}) {
+    const selected = this._selectedShareTrackingTarget();
+    if (!selected || this._destroyed)
+      return { status: 'skipped', reason: 'no-shared-target' };
+    this._revokePendingTrackingWatch('superseded-by-newer-restore');
+    const controller = new AbortController();
+    const combinedSignal = signal
+      ? AbortSignal.any([signal, controller.signal])
+      : controller.signal;
+    this._trackingRestoreController = controller;
+    const generation = ++this._trackingRestoreGeneration;
+    let result;
+    try {
+      result = await this.dataManager.resolveLayerTrackingTarget(
+        selected.layerId,
+        selected.targetId,
+        { signal: combinedSignal, origin: LAYER_RESTORE_ORIGINS.share },
+      );
+    } catch (error) {
+      result = combinedSignal.aborted
+        ? {
+            status: 'cancelled',
+            reason: String(combinedSignal.reason || 'aborted'),
+          }
+        : {
+            status: 'source-unavailable',
+            reason: String(error?.message || error),
+          };
+    }
+    if (
+      generation !== this._trackingRestoreGeneration ||
+      this._destroyed ||
+      combinedSignal.aborted
+    ) {
+      if (this._trackingRestoreController === controller)
+        this._trackingRestoreController = null;
+      return {
+        ...result,
+        status: 'cancelled',
+        reason: String(combinedSignal.reason || 'superseded'),
+      };
+    }
+    if (this._trackingRestoreController === controller)
+      this._trackingRestoreController = null;
+
+    if (result.status === 'found') {
+      const terminal = {
+        ...result,
+        ...selected,
+        classification: 'followed',
+        cleared: false,
+      };
+      this._publishTrackingRestoreStatus(terminal);
+      return terminal;
+    }
+    if (['cancelled', 'superseded', 'destroyed'].includes(result.status))
+      return result;
+
+    // A subject that is simply not here YET is not a subject that is gone. Hold
+    // it on the layer's own deferred-restore latch for its source-specific
+    // window before any verdict is reached or shown. `unsupported` layers have
+    // no latch to arm, so they still decide immediately.
+    if (result.status === 'missing' || result.status === 'source-unavailable') {
+      return this._beginPendingTrackingRestore(
+        selected,
+        result,
+        combinedSignal,
+      );
+    }
+
+    const classification =
+      result.status === 'missing'
+        ? this._classifyMissingTrackingTarget(selected)
+        : 'source-unavailable';
+    const cleared = this._passivelyClearTrackingSelection(selected);
+    const terminal = { ...result, ...selected, classification, cleared };
+    this._publishTrackingRestoreStatus(terminal);
+    return terminal;
+  }
+
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    for (const controller of this._restoreControllers.values())
+      controller.abort('coordinator-destroyed');
+    this._restoreControllers.clear();
+    this._revokePendingTrackingWatch('coordinator-destroyed');
+    this._trackingRestoreController = null;
+    this._unsubscribe?.();
+    this._unsubscribe = null;
+    this._unsubscribeVisibilityRequests?.();
+    this._unsubscribeVisibilityRequests = null;
+    this.shareLinkManager?.setLayerStateProvider?.(null);
+    this.onDurableStateChange = null;
+    this.onTrackingRestoreStatus = null;
+  }
+}

src/data/layerStateTokenLedger.test.mjs

@@ -98,6 +98,12 @@ function withPublishedBase(
 }
 
 function writeCodecFixture(cwd, rows, entries) {
+  const providerCodec = path.join(cwd, 'src/data/idSwitches.js');
+  mkdirSync(path.dirname(providerCodec), { recursive: true });
+  writeFileSync(
+    providerCodec,
+    readFileSync(new URL('./idSwitches.js', import.meta.url)),
+  );
   const source = readFileSync(CODEC_SOURCE_PATH, 'utf8');
   const registryEnd = ']);\n\nexport const REGISTERED_LAYER_IDS';
   assert.equal(source.split(registryEnd).length, 2);
@@ -122,10 +128,10 @@ 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, 28);
+  assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 29);
   assert.deepEqual(
     { ...LAYER_STATE_TOKEN_RESERVATIONS },
-    { ...LEGACY_LAYER_STATE_TOKENS },
+    { ...LEGACY_LAYER_STATE_TOKENS, 'street-level': '0' },
   );
   assert.throws(
     () => parseLayerStateTokenReservations(reservationRows.slice(1)),
@@ -145,9 +151,9 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
     /Duplicate layer-state token reservation/,
   );
   assert.equal(
-    parseLayerStateTokenReservations([...reservationRows, ['future', '0']])
+    parseLayerStateTokenReservations([...reservationRows, ['future', '3']])
       .future,
-    '0',
+    '3',
   );
   assert.throws(
     () =>
@@ -165,14 +171,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', '0']] },
+    { rows: [...reservationRows, ['retired-layer', '3']] },
     (cwd) => {
       const published = readPublishedLayerStateReservations('HEAD', cwd);
-      assert.equal(nextLayerStateToken(published), '3');
+      assert.equal(nextLayerStateToken(published), '4');
       assert.equal(
         validateLayerStateAllocations(published, {
           ...published,
-          newcomer: '3',
+          newcomer: '4',
         }),
         true,
       );
@@ -180,15 +186,15 @@ test('published retired digits and competing PRs advance the merge-time allocati
         () =>
           validateLayerStateAllocations(published, {
             ...published,
-            competing: '0',
+            competing: '3',
           }),
-        /next free token 3/,
+        /next free token 4/,
       );
       assert.throws(
         () =>
           validateLayerStateAllocations(published, {
             ...LAYER_STATE_TOKEN_RESERVATIONS,
-            newcomer: '0',
+            newcomer: '3',
           }),
         /changed or removed: retired-layer/,
       );
@@ -196,8 +202,8 @@ test('published retired digits and competing PRs advance the merge-time allocati
   );
 });
 
-test('PR B manually replaces provisional 0 with 3 after PR A publishes 0', () => {
-  withPublishedBase({ rows: [...reservationRows, ['pr-a', '0']] }, (cwd) => {
+test('PR B manually replaces provisional 3 with 4 after PR A publishes 3', () => {
+  withPublishedBase({ rows: [...reservationRows, ['pr-a', '3']] }, (cwd) => {
     mkdirSync(path.join(cwd, 'scripts'));
     const fixtureChecker = path.join(
       cwd,
@@ -218,8 +224,8 @@ test('PR B manually replaces provisional 0 with 3 after PR A publishes 0', () =>
 
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-b', '0']],
-      [{ id: 'pr-b', token: '0' }],
+      [...reservationRows, ['pr-b', '3']],
+      [{ id: 'pr-b', token: '3' }],
     );
     const beforeRebase = runCheck();
     assert.equal(beforeRebase.status, 1);
@@ -227,10 +233,10 @@ test('PR B manually replaces provisional 0 with 3 after PR A publishes 0', () =>
 
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-a', '0'], ['pr-b', '0']],
+      [...reservationRows, ['pr-a', '3'], ['pr-b', '3']],
       [
-        { id: 'pr-a', token: '0' },
-        { id: 'pr-b', token: '0' },
+        { id: 'pr-a', token: '3' },
+        { id: 'pr-b', token: '3' },
       ],
     );
     const staleRebase = runCheck();
@@ -238,16 +244,16 @@ test('PR B manually replaces provisional 0 with 3 after PR A publishes 0', () =>
     assert.match(staleRebase.stderr, /Duplicate layer-state token reservation/);
 
     const published = readPublishedLayerStateReservations('HEAD', cwd);
-    assert.equal(nextLayerStateToken(published), '3');
-    const validBaselineRows = [...reservationRows, ['pr-a', '0']];
-    writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '0' }]);
+    assert.equal(nextLayerStateToken(published), '4');
+    const validBaselineRows = [...reservationRows, ['pr-a', '3']];
+    writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '3' }]);
     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: 3/);
+    assert.match(helper.stdout, /pr-b: 4/);
     assert.deepEqual(
       JSON.parse(readFileSync(path.join(cwd, LEDGER_PATH), 'utf8')),
       validBaselineRows,
@@ -255,20 +261,20 @@ test('PR B manually replaces provisional 0 with 3 after PR A publishes 0', () =>
     );
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-a', '0'], ['pr-b', '3']],
+      [...reservationRows, ['pr-a', '3'], ['pr-b', '4']],
       [
-        { id: 'pr-a', token: '0' },
-        { id: 'pr-b', token: '3' },
+        { id: 'pr-a', token: '3' },
+        { id: 'pr-b', token: '4' },
       ],
     );
     const corrected = runCheck();
     assert.equal(corrected.status, 0, corrected.stderr);
-    assert.match(corrected.stdout, /29 published, 1 new/);
+    assert.match(corrected.stdout, /30 published, 1 new/);
   });
 });
 
 test('allocation batches cross the last digit and base-36 pair boundaries in order', () => {
-  const digitRows = [...'03456789'].map((digit) => [`retired-${digit}`, digit]);
+  const digitRows = [...'3456789'].map((digit) => [`retired-${digit}`, digit]);
   const allDigits = parseLayerStateTokenReservations([
     ...reservationRows,
     ...digitRows,
@@ -320,7 +326,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 = [...'03456789'].map((digit) => [
+    const priorDigits = [...'3456789'].map((digit) => [
       `qa-prior-digit-${digit}`,
       digit,
     ]);
@@ -357,7 +363,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, 67);
+    assert.equal(params.get('l').length, 69);
     const restored = codec.decodeLayerStateParams(params);
     assert.deepEqual(restored?.enabledLayerIds, expectedLayerIds);
     assert.deepEqual(restored?.options, state.options);
@@ -375,7 +381,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, 29);
+      assert.equal(Object.keys(published).length, 30);
       assert.equal(published['retired-layer'], '00');
       assert.throws(
         () =>

src/data/layerStateTokenReservations.json

@@ -19,6 +19,7 @@
   ["recent-imagery", "1"],
   ["rocket-launches", "x"],
   ["satellites", "s"],
+  ["street-level", "0"],
   ["telegeography-submarine-cables", "u"],
   ["traffic", "t"],
   ["transit", "j"],

src/data/lifecycle.js

@@ -74,7 +74,11 @@ function refreshFailureFromStats(stats, label) {
  * for real-time data overlays on the CesiumJS globe.
  */
 export class LayerLifecycle {
-  constructor(viewer, { allowQaRegistration = false } = {}) {
+  constructor(
+    viewer,
+    { allowQaRegistration = false, getSourceAvailability } = {},
+  ) {
+    this._catalogSourceAvailability = getSourceAvailability;
     this.viewer = viewer;
     this._activityListeners = new Set();
     this.layers = new Map(); // id → { module, enabled, initialized, intervalId, lifecycleState, lifecycleUncertain }
@@ -228,6 +232,7 @@ export class LayerLifecycle {
 
   _normalizedStats(entry) {
     const moduleStats = this._moduleStats(entry);
+    const availability = this._sourceAvailability(entry.module.id);
     const lifecycleLoading =
       entry.lifecycleState === 'enabling' ||
       entry.lifecycleState === 'disabling';
@@ -235,6 +240,13 @@ export class LayerLifecycle {
       count: 0,
       lastUpdate: null,
       ...moduleStats,
+      ...(availability?.available === false
+        ? {
+            status: 'unavailable',
+            sourceUnavailable: true,
+            error: availability.reason,
+          }
+        : {}),
       loading: lifecycleLoading || moduleStats.loading === true,
       refreshing: entry.refreshing || moduleStats.refreshing === true,
       managerRefreshError: entry.managerRefreshError,
@@ -2282,7 +2294,17 @@ export class LayerLifecycle {
     }
   }
 
+  _sourceAvailability(layerId) {
+    return (
+      this._catalogSourceAvailability?.(layerId) ??
+      this.layers.get(layerId)?.module.getSourceAvailability?.()
+    );
+  }
+
   async _visibilityBlockReason(change) {
+    const availability = this._sourceAvailability(change.layerId);
+    if (change.enabled && availability?.available === false)
+      return availability.reason || 'Data source unavailable';
     for (const callback of this._visibilityGuards) {
       try {
         const result = await callback(change);

src/data/localGeojsonCore.js

@@ -1,4 +1,9 @@
 import * as Cesium from 'cesium';
+import {
+  layerTitle,
+  mapAnalystRecord,
+  parseGeojsonLines,
+} from '../sources/infrastructureData.js';
 import { createInfrastructureOverlayEntry } from './infrastructureOverlayEntry.js';
 import { isPointerFree } from './inputOwnership.js';
 import {
@@ -86,78 +91,6 @@ export function localInfrastructureOverlayCopy(properties, layerId) {
   return { title, details };
 }
 
-/**
- * Map one local infrastructure feature to a JSON-safe analyst record
- * (analyst query engine seam). Pure — no Cesium types. Missing/unknown
- * fields are null, never NaN/undefined. Layer-specific fields that do not
- * apply (river/output on datacenters, capacity on dams) stay null so a
- * shared compact payload can copy them without inventing values.
- * Names are unclamped — overlay cards shorten for paint; queries need the
- * full source string ("Usina Hidrelétrica de Itaipu").
- * @param {Object|null|undefined} raw - {id, lat, lon, properties}.
- * @param {string} [layerId] Local layer id (`local-datacenters` / `local-dams`).
- * @returns {{id: string, name: string|null, lat: number|null, lon: number|null,
- *   operator: string|null, capacity: string|null, river: string|null,
- *   output: string|null}}
- */
-export function mapAnalystRecord(raw, layerId = '') {
-  const num = (v) => (Number.isFinite(v) ? v : null);
-  const text = (v) => {
-    const t = String(v ?? '').trim();
-    return t && t !== 'undefined' && t !== 'null' ? t : null;
-  };
-  const props =
-    raw?.properties &&
-    typeof raw.properties === 'object' &&
-    !Array.isArray(raw.properties)
-      ? raw.properties
-      : {};
-  const tags =
-    props.tags && typeof props.tags === 'object' && !Array.isArray(props.tags)
-      ? props.tags
-      : {};
-  const name =
-    text(props.name) ||
-    text(tags.name) ||
-    text(tags['name:en']) ||
-    text(tags.official_name) ||
-    null;
-  const operator =
-    text(tags.operator) ||
-    text(props.operator) ||
-    text(tags['operator:short']) ||
-    null;
-  const capacity =
-    layerId === 'local-datacenters'
-      ? text(tags['capacity:it_load']) ||
-        text(tags.it_load) ||
-        text(tags.capacity) ||
-        text(props.capacity)
-      : null;
-  const river =
-    layerId === 'local-dams'
-      ? text(tags.associated_river) ||
-        text(props.associated_river) ||
-        text(tags.river) ||
-        text(props.river) ||
-        text(tags['river:name'])
-      : null;
-  const output =
-    layerId === 'local-dams'
-      ? text(props.output) || text(tags['plant:output:electricity'])
-      : null;
-  return {
-    id: name || text(raw?.id) || layerTitle(layerId),
-    name,
-    lat: num(raw?.lat),
-    lon: num(raw?.lon),
-    operator,
-    capacity,
-    river,
-    output,
-  };
-}
-
 /**
  * Produce one normalized-contract input owned by a local infrastructure layer.
  * The host revalidates the authoritative `source` value while normalizing it.
@@ -664,11 +597,7 @@ export function createLocalGeoJsonLayer(
                 }
                 const text = await response.text();
                 if (_destroyed) return;
-                const lines = text
-                  .split('\n')
-                  .filter((l) => l.trim().length > 0);
-
-                features = lines.map((line) => JSON.parse(line));
+                features = parseGeojsonLines(text);
                 _cachedFeatures = features;
               }
 
@@ -1360,8 +1289,4 @@ function clampCardLine(value) {
   return text.length > 48 ? `${text.slice(0, 45)}...` : text;
 }
 
-function layerTitle(layerId) {
-  if (layerId === 'local-datacenters') return 'Datacenter';
-  if (layerId === 'local-dams') return 'Dam';
-  return 'Feature';
-}
+export { mapAnalystRecord };

src/data/militaryAwareness.test.mjs

@@ -41,6 +41,7 @@ import {
   formatAwarenessLabel,
   getAwarenessNavigationTargets,
 } from './militaryAwarenessEngine.js';
+import { formatAwarenessCount } from '../layers/awareness/panel.js';
 import { NAVIGATION_AUTHORITY_EVENT } from '../navigationPolicy.js';
 
 const militaryAwarenessSource = readLayerSource(
@@ -55,6 +56,18 @@ const AWARENESS_DEPENDENCIES = [
   'military-installations',
 ];
 
+test('Contacts labels a capped cohort as a lower bound', () => {
+  assert.equal(
+    formatAwarenessCount({ count: 20_000, complete: false, truncated: true }),
+    'At least 20,000',
+  );
+  assert.equal(
+    formatAwarenessCount({ count: 19_999, complete: true, truncated: false }),
+    '19,999',
+  );
+  assert.equal(formatAwarenessCount({ count: null }), '?');
+});
+
 function installAwarenessRuntime({
   isEnabled = () => true,
   isEffectivelyEnabled = isEnabled,
@@ -476,7 +489,7 @@ test('pending mapped installations render as unknown instead of a false zero', a
 // the dependencies reach it by different routes:
 //
 //   - ais-live-vessels is its REACHABLE producer. enable()/update() both resolve
-//     as soon as the first /api/ais-live poll answers, so the manager's
+//     as soon as the first /api/vessels poll answers, so the manager's
 //     lifecycle settles to `enabled` — but until the server-side socket delivers
 //     a position, firstConnectPhase stays 'loading' and the module reports busy,
 //     no lastUpdate, count 0, and an UNDEFINED status, so the status list alone
@@ -2554,6 +2567,7 @@ test('the contacts window reports exactly the counts the panel renders', () => {
   assert.equal(window.flights, 42);
   assert.equal(window.military, 13);
   assert.equal(window.aircraft, 55);
+  assert.equal(window.complete, true);
   assert.equal(window.centeredOn, 'ASA635');
   assert.equal(window.radiusKm, Math.round(AWARENESS_RADIUS_M / 1000));
   // A feed that cannot answer says so rather than reporting a confident zero.
@@ -2561,6 +2575,57 @@ test('the contacts window reports exactly the counts the panel renders', () => {
   assert.equal(window.vessels, 'unknown');
 });
 
+test('the voice query snapshot is a detached copy of the rendered aircraft cohort', async () => {
+  const subjectPosition = Cesium.Cartesian3.fromDegrees(-97.74, 30.27, 1_000);
+  const nearbyPosition = Cesium.Cartesian3.fromDegrees(-97.7, 30.3, 1_500);
+  const restoreCollections = stubAwarenessCollections({
+    flights: [
+      {
+        icao24: 'subject',
+        id: 'SUBJECT',
+        position: subjectPosition,
+        distance: 0,
+      },
+      {
+        icao24: 'nearby',
+        id: 'NEARBY',
+        position: nearbyPosition,
+        distance: 5_000,
+      },
+    ],
+  });
+  const runtime = installAwarenessRuntime();
+  try {
+    runtime.dispatch(
+      'gev:awareness-subject-selected',
+      awarenessSubject('flights', 'subject', subjectPosition),
+    );
+    await nextTurn();
+    const first = militaryAwarenessLayer.getAircraftQuerySnapshot();
+    assert.equal(first.cohorts.flights.count, 1);
+    assert.equal(first.cohorts.flights.complete, true);
+    assert.equal(first.cohorts.flights.provenance.id, 'flights');
+    assert.equal(first.cohorts.flights.provenance.enabled, true);
+    assert.equal(first.cohorts.flights.items[0].icao24, 'nearby');
+    first.cohorts.flights.items[0].icao24 = 'mutated';
+    first.cohorts.flights.items[0].position.x = 99;
+    first.cohorts.flights.provenance.source = 'mutated';
+    first.cohorts.flights.provenance.stats.coverage = { radiusM: 1 };
+    first.subject.position.x = 77;
+    const second = militaryAwarenessLayer.getAircraftQuerySnapshot();
+    assert.equal(second.cohorts.flights.items[0].icao24, 'nearby');
+    assert.equal(second.cohorts.flights.items[0].position.x, nearbyPosition.x);
+    assert.notEqual(second.cohorts.flights.provenance.source, 'mutated');
+    assert.notDeepEqual(second.cohorts.flights.provenance.stats.coverage, {
+      radiusM: 1,
+    });
+    assert.equal(second.subject.position.x, subjectPosition.x);
+  } finally {
+    runtime.restore();
+    restoreCollections();
+  }
+});
+
 test('there is no contacts window without a subject', () => {
   assert.equal(contactsWindowFromSnapshot(null), null);
   assert.equal(contactsWindowFromSnapshot({ cohorts: [] }), null);

src/data/militaryFlights.js

@@ -1,12 +1,12 @@
 import { defaultSurface } from './surfaceServices.js';
 import { createApplicationMilitary } from '../app/layers/militaryFlights.js';
 
-import { createAdsbLolSource } from '../sources/live/standalone.js';
+import { createMilitarySource } from '../sources/live/standalone.js';
 import * as militaryRegistry from './militaryRegistry.js';
 
 const militaryFlightsLayer = createApplicationMilitary({
   surface: defaultSurface,
-  source: createAdsbLolSource(),
+  source: createMilitarySource(),
   militaryRegistry,
 });
 export { TRACKED_MODEL_MAX_PX } from '../layers/military/policy.js';

src/data/militaryFlights.test.mjs

@@ -24,8 +24,12 @@ test('share-Follow absence requires an accepted adsb.lol snapshot', async () =>
     (await militaryFlightsLayer.resolveTrackingRestoreTarget('ae1234')).status,
     'source-unavailable',
   );
-  _setMilitaryTrackingRefreshOutcomeForTest({ status: 'accepted', ids: ['different'] });
-  const missing = await militaryFlightsLayer.resolveTrackingRestoreTarget('ae1234');
+  _setMilitaryTrackingRefreshOutcomeForTest({
+    status: 'accepted',
+    ids: ['different'],
+  });
+  const missing =
+    await militaryFlightsLayer.resolveTrackingRestoreTarget('ae1234');
   assert.equal(missing.status, 'missing');
   assert.equal(missing.reason, 'target-absent-from-snapshot');
 });
@@ -44,9 +48,9 @@ const FULL_INFO = {
   operator: 'United States Air Force',
 };
 
-test('military stats identify adsb.lol as the primary feed, not a fallback', () => {
+test('military stats name the feed until the server names its provider, not a fallback', () => {
   const stats = militaryFlightsLayer.getStats();
-  assert.equal(stats.source, 'adsb.lol');
+  assert.equal(stats.source, 'Military aircraft');
   assert.equal(stats.fallback, false);
 });
 
@@ -81,8 +85,14 @@ test('military analyst record: military is ALWAYS true, routes/country always nu
 });
 
 test('military analyst record: no callsign falls back to registration, then icao24', () => {
-  assert.equal(mapAnalystRecord('ae01ce', { ...FULL_INFO, callsign: '' }).id, '05-8152');
-  assert.equal(mapAnalystRecord('ae01ce', { callsign: '', registration: ' ' }).id, 'ae01ce');
+  assert.equal(
+    mapAnalystRecord('ae01ce', { ...FULL_INFO, callsign: '' }).id,
+    '05-8152',
+  );
+  assert.equal(
+    mapAnalystRecord('ae01ce', { callsign: '', registration: ' ' }).id,
+    'ae01ce',
+  );
 });
 
 test('military analyst record: empty info yields nulls, never NaN/undefined', () => {
@@ -91,7 +101,8 @@ test('military analyst record: empty info yields nulls, never NaN/undefined', ()
   assert.equal(r.onGround, false);
   for (const [key, value] of Object.entries(r)) {
     assert.notEqual(value, undefined, `${key} must not be undefined`);
-    if (typeof value === 'number') assert.ok(Number.isFinite(value), `${key} must not be NaN`);
+    if (typeof value === 'number')
+      assert.ok(Number.isFinite(value), `${key} must not be NaN`);
   }
 });
 
@@ -103,12 +114,17 @@ test('military analyst record: output is JSON-safe (no Cesium types)', () => {
 test('military first update forwards caller cancellation into the feed request', async () => {
   const realFetch = globalThis.fetch;
   let observedSignal = null;
-  globalThis.fetch = (_url, options = {}) => new Promise((_resolve, reject) => {
-    observedSignal = options.signal;
-    options.signal?.addEventListener('abort', () => {
-      reject(new DOMException('aborted', 'AbortError'));
-    }, { once: true });
-  });
+  globalThis.fetch = (_url, options = {}) =>
+    new Promise((_resolve, reject) => {
+      observedSignal = options.signal;
+      options.signal?.addEventListener(
+        'abort',
+        () => {
+          reject(new DOMException('aborted', 'AbortError'));
+        },
+        { once: true },
+      );
+    });
   try {
     const controller = new AbortController();
     const work = militaryFlightsLayer.update({}, { signal: controller.signal });
@@ -138,11 +154,22 @@ test('nonempty adsb.lol payload with zero usable rows cannot prove share target
     json: async () => ({ ac: [null, {}, { hex: 'ae1234' }] }),
   });
   try {
-    await militaryFlightsLayer.update({ camera: { positionCartographic: null }, scene: {} });
-    const resolution = await militaryFlightsLayer.resolveTrackingRestoreTarget('ae1234');
+    await militaryFlightsLayer.update({
+      camera: { positionCartographic: null },
+      scene: {},
+    });
+    const resolution =
+      await militaryFlightsLayer.resolveTrackingRestoreTarget('ae1234');
     assert.equal(resolution.status, 'source-unavailable');
-    assert.match(militaryFlightsLayer.getStats().error, /Malformed adsb\.lol aircraft rows/);
-    assert.equal(militaryFlightsLayer.getAnalystRecords().length, 1, 'warm aircraft data is preserved');
+    assert.match(
+      militaryFlightsLayer.getStats().error,
+      /Malformed adsb\.lol aircraft rows/,
+    );
+    assert.equal(
+      militaryFlightsLayer.getAnalystRecords().length,
+      1,
+      'warm aircraft data is preserved',
+    );
   } finally {
     globalThis.fetch = realFetch;
   }
@@ -188,21 +215,26 @@ test('military poll refreshes tracked callsign/altitude/kts and marks a missed p
     ok: true,
     status: 200,
     json: async () => ({
-      ac: poll++ === 0 ? [{
-        hex: icao24,
-        lon: -96.9,
-        lat: 31.1,
-        alt_baro: 28_000,
-        alt_geom: 28_100,
-        track: 95,
-        gs: 400,
-        seen: 0,
-        seen_pos: 0,
-        flight: 'RCH451 ',
-        t: 'C17',
-        r: '05-8152',
-        ownOp: 'United States Air Force',
-      }] : [],
+      ac:
+        poll++ === 0
+          ? [
+              {
+                hex: icao24,
+                lon: -96.9,
+                lat: 31.1,
+                alt_baro: 28_000,
+                alt_geom: 28_100,
+                track: 95,
+                gs: 400,
+                seen: 0,
+                seen_pos: 0,
+                flight: 'RCH451 ',
+                t: 'C17',
+                r: '05-8152',
+                ownOp: 'United States Air Force',
+              },
+            ]
+          : [],
     }),
   });
 
@@ -227,7 +259,10 @@ test('cached military snapshots retain their observation time and expose stale f
   _setTrackedMilitaryRefreshStateForTest({
     icao24: 'ae01ce',
     entity: { gevLabelModel: { title: 'RCH451', details: [] } },
-    billboard: { position: Cesium.Cartesian3.fromDegrees(-97, 31, 8000), show: false },
+    billboard: {
+      position: Cesium.Cartesian3.fromDegrees(-97, 31, 8000),
+      show: false,
+    },
     billboardCollection: { show: false, remove() {} },
     viewer,
     history,
@@ -235,21 +270,48 @@ test('cached military snapshots retain their observation time and expose stale f
   });
   let cache = 'MISS';
   t.mock.method(Date, 'now', () => now);
-  t.mock.method(globalThis, 'fetch', async () => Response.json({
-    ac: [{ hex: 'ae01ce', lon: -97, lat: 31, alt_baro: 28000,
-      track: 95, gs: 400, seen: 1, seen_pos: 2, flight: 'RCH451' }],
-  }, { headers: {
-    'X-ADS-B-Cache': cache,
-    ...(cache === 'MISS' ? {} : { 'X-ADS-B-Cache-Age-Ms': String(now - receivedAt) }),
-  } }));
+  t.mock.method(globalThis, 'fetch', async () =>
+    Response.json(
+      {
+        ac: [
+          {
+            hex: 'ae01ce',
+            lon: -97,
+            lat: 31,
+            alt_baro: 28000,
+            track: 95,
+            gs: 400,
+            seen: 1,
+            seen_pos: 2,
+            flight: 'RCH451',
+          },
+        ],
+      },
+      {
+        headers: {
+          'X-Feed-Cache': cache,
+          ...(cache === 'MISS'
+            ? {}
+            : { 'X-Feed-Age-Ms': String(now - receivedAt) }),
+        },
+      },
+    ),
+  );
   await militaryFlightsLayer.update(viewer);
   assert.equal(history.length, 1);
   assert.equal(history[0].epochMs, receivedAt - 2000);
-  for (const [status, age] of [['HIT', 5000], ['STALE', 45000]]) {
+  for (const [status, age] of [
+    ['HIT', 5000],
+    ['STALE', 45000],
+  ]) {
     cache = status;
     now = receivedAt + age;
     await militaryFlightsLayer.update(viewer);
-    assert.equal(history.length, 1, 'replayed positions cannot create a new fix');
+    assert.equal(
+      history.length,
+      1,
+      'replayed positions cannot create a new fix',
+    );
     assert.equal(militaryFlightsLayer.getStats().lastUpdate, receivedAt);
     assert.equal(militaryFlightsLayer.getStats().stale, status === 'STALE');
     assert.equal(militaryFlightsLayer.getStats().error, null);
@@ -276,14 +338,18 @@ test('real military track path creates no native label and publishes every cache
     trackedEntityChanged,
     clock: { currentTime: now },
     camera: {
-      cancelFlight() { cancelledFlights += 1; },
+      cancelFlight() {
+        cancelledFlights += 1;
+      },
       position: new Cesium.Cartesian3(0, -10_000, 7_000),
       positionWC: new Cesium.Cartesian3(0, -10_000, 7_000),
       direction: Cesium.Cartesian3.UNIT_Y,
       transform: Cesium.Matrix4.IDENTITY,
       viewMatrix: Cesium.Matrix4.IDENTITY,
       frustum: { projectionMatrix: Cesium.Matrix4.IDENTITY },
-      lookAtTransform() { appliedFrames += 1; },
+      lookAtTransform() {
+        appliedFrames += 1;
+      },
     },
     scene: {
       canvas: { clientWidth: 1600, clientHeight: 900 },
@@ -322,9 +388,12 @@ test('real military track path creates no native label and publishes every cache
   const realFetch = globalThis.fetch;
   globalThis.window = new EventTarget();
   const selectionEvents = [];
-  globalThis.window.addEventListener('gev:awareness-subject-selected', (event) => {
-    selectionEvents.push(event.detail);
-  });
+  globalThis.window.addEventListener(
+    'gev:awareness-subject-selected',
+    (event) => {
+      selectionEvents.push(event.detail);
+    },
+  );
   globalThis.fetch = async () => ({ ok: false });
   _setTrackedOverlayHostForTest(host);
   try {
@@ -336,13 +405,15 @@ test('real military track path creates no native label and publishes every cache
       billboardCollection: { show: true, remove() {} },
       viewer,
       tracked: false,
-      history: [{
-        time: now,
-        epochMs: Date.now(),
-        position,
-        velocity: 231.5,
-        track: 92.1,
-      }],
+      history: [
+        {
+          time: now,
+          epochMs: Date.now(),
+          position,
+          velocity: 231.5,
+          track: 92.1,
+        },
+      ],
       meta: {
         ...FULL_INFO,
         type: 'C17',
@@ -352,34 +423,72 @@ test('real military track path creates no native label and publishes every cache
       },
     });
 
-    assert.equal(militaryFlightsLayer.trackById(icao24, { origin: 'programmatic' }), true);
+    assert.equal(
+      militaryFlightsLayer.trackById(icao24, { origin: 'programmatic' }),
+      true,
+    );
     const entity = viewer.trackedEntity;
-    assert.ok(entity instanceof Cesium.Entity, 'trackById must create the real Cesium entity');
+    assert.ok(
+      entity instanceof Cesium.Entity,
+      'trackById must create the real Cesium entity',
+    );
     assert.equal(entity.label, undefined);
-    assert.ok(entities.values.every((candidate) => candidate.label === undefined));
+    assert.ok(
+      entities.values.every((candidate) => candidate.label === undefined),
+    );
     assert.deepEqual(entity.gevLabelModel, {
       title: 'RCH451',
-      details: [
-        'C17 · 05-8152',
-        'United States Air Force · 28000 ft · 450 kt',
-      ],
+      details: ['C17 · 05-8152', 'United States Air Force · 28000 ft · 450 kt'],
       accent: '#ffd166',
     });
     viewer.scene.preUpdate.raiseEvent();
     const initialAppliedFrames = appliedFrames;
     const initialCancelledFlights = cancelledFlights;
-    assert.equal(militaryFlightsLayer.trackById(icao24, { origin: 'user' }), true);
-    assert.equal(cancelledFlights, initialCancelledFlights, 'ordinary repeated tracking stays camera-idempotent');
-    assert.equal(selectionEvents.at(-1)?.origin, 'user', 'same-target selection upgrades durable authority');
+    assert.equal(
+      militaryFlightsLayer.trackById(icao24, { origin: 'user' }),
+      true,
+    );
+    assert.equal(
+      cancelledFlights,
+      initialCancelledFlights,
+      'ordinary repeated tracking stays camera-idempotent',
+    );
+    assert.equal(
+      selectionEvents.at(-1)?.origin,
+      'user',
+      'same-target selection upgrades durable authority',
+    );
     assert.equal(entity.gevSelectionOrigin, 'user');
-    assert.equal(militaryFlightsLayer.refocusTrackedById('different-flight'), false);
-    assert.equal(militaryFlightsLayer.refocusTrackedById(icao24, { origin: 'voice' }), true);
-    assert.equal(selectionEvents.at(-1)?.origin, 'voice', 'same-target refocus forwards explicit authority');
+    assert.equal(
+      militaryFlightsLayer.refocusTrackedById('different-flight'),
+      false,
+    );
+    assert.equal(
+      militaryFlightsLayer.refocusTrackedById(icao24, { origin: 'voice' }),
+      true,
+    );
+    assert.equal(
+      selectionEvents.at(-1)?.origin,
+      'voice',
+      'same-target refocus forwards explicit authority',
+    );
     assert.equal(militaryFlightsLayer.refocusTrackedById(icao24), true);
     viewer.scene.preUpdate.raiseEvent();
-    assert.equal(viewer.trackedEntity, entity, 'refocus must retain the exact tracked entity');
-    assert.equal(appliedFrames, initialAppliedFrames + 1, 'repeated refocus keeps one camera-frame owner');
-    assert.equal(cancelledFlights, initialCancelledFlights + 2, 'only explicit refocus requests cancel camera flights');
+    assert.equal(
+      viewer.trackedEntity,
+      entity,
+      'refocus must retain the exact tracked entity',
+    );
+    assert.equal(
+      appliedFrames,
+      initialAppliedFrames + 1,
+      'repeated refocus keeps one camera-frame owner',
+    );
+    assert.equal(
+      cancelledFlights,
+      initialCancelledFlights + 2,
+      'only explicit refocus requests cancel camera flights',
+    );
     const publication = publications.at(-1);
     assert.equal(publication.sourceId, 'tracked');
     const entry = publication.entries[0];
@@ -390,23 +499,40 @@ test('real military track path creates no native label and publishes every cache
 
     const display = entity.position.getValue(now);
     assert.ok(display, 'tracked position callback must seed its frame cache');
-    assert.equal(entry.position(), display, 'host must reuse the exact cached display Cartesian');
+    assert.equal(
+      entry.position(),
+      display,
+      'host must reuse the exact cached display Cartesian',
+    );
 
     militaryFlightsLayer.setParams(
       { selectedMilitaryTrackingId: 'late001' },
       { origin: 'share-restore' },
     );
     assert.equal(_pendingMilitaryTrackingRestoreForTest(), 'late001');
-    assert.equal(militaryFlightsLayer.trackById(icao24, { origin: 'user' }), true);
-    assert.equal(_pendingMilitaryTrackingRestoreForTest(), null, 'new user selection cancels stale restore');
+    assert.equal(
+      militaryFlightsLayer.trackById(icao24, { origin: 'user' }),
+      true,
+    );
+    assert.equal(
+      _pendingMilitaryTrackingRestoreForTest(),
+      null,
+      'new user selection cancels stale restore',
+    );
     _addMilitaryTrackingCandidateForTest({
       icao24: 'late001',
-      billboard: { ...billboard, position: Cesium.Cartesian3.fromDegrees(-96.9, 31.1, 8_000) },
+      billboard: {
+        ...billboard,
+        position: Cesium.Cartesian3.fromDegrees(-96.9, 31.1, 8_000),
+      },
       meta: { ...FULL_INFO, callsign: 'LATE1', rawLat: 31.1, rawLon: -96.9 },
       history: [],
     });
     _applyPendingMilitaryTrackingRestoreForTest();
-    assert.equal(militaryFlightsLayer.getParams().selectedMilitaryTrackingId, icao24);
+    assert.equal(
+      militaryFlightsLayer.getParams().selectedMilitaryTrackingId,
+      icao24,
+    );
 
     militaryFlightsLayer.stopTracking();
     militaryFlightsLayer.setParams(
@@ -415,15 +541,25 @@ test('real military track path creates no native label and publishes every cache
     );
     assert.equal(_pendingMilitaryTrackingRestoreForTest(), 'late002');
     militaryFlightsLayer.stopTracking({ origin: 'user' });
-    assert.equal(_pendingMilitaryTrackingRestoreForTest(), null, 'explicit clear cancels stale restore');
+    assert.equal(
+      _pendingMilitaryTrackingRestoreForTest(),
+      null,
+      'explicit clear cancels stale restore',
+    );
     _addMilitaryTrackingCandidateForTest({
       icao24: 'late002',
-      billboard: { ...billboard, position: Cesium.Cartesian3.fromDegrees(-96.8, 31.2, 7_000) },
+      billboard: {
+        ...billboard,
+        position: Cesium.Cartesian3.fromDegrees(-96.8, 31.2, 7_000),
+      },
       meta: { ...FULL_INFO, callsign: 'LATE2', rawLat: 31.2, rawLon: -96.8 },
       history: [],
     });
     _applyPendingMilitaryTrackingRestoreForTest();
-    assert.equal(militaryFlightsLayer.getParams().selectedMilitaryTrackingId, null);
+    assert.equal(
+      militaryFlightsLayer.getParams().selectedMilitaryTrackingId,
+      null,
+    );
 
     militaryFlightsLayer.setParams(
       { selectedMilitaryTrackingId: 'late003' },
@@ -438,12 +574,18 @@ test('real military track path creates no native label and publishes every cache
     );
     _addMilitaryTrackingCandidateForTest({
       icao24: 'late003',
-      billboard: { ...billboard, position: Cesium.Cartesian3.fromDegrees(-97.3, 30.6, 7_000) },
+      billboard: {
+        ...billboard,
+        position: Cesium.Cartesian3.fromDegrees(-97.3, 30.6, 7_000),
+      },
       meta: { ...FULL_INFO, callsign: 'LATE3', rawLat: 30.6, rawLon: -97.3 },
       history: [],
     });
     _applyPendingMilitaryTrackingRestoreForTest();
-    assert.equal(militaryFlightsLayer.getParams().selectedMilitaryTrackingId, null);
+    assert.equal(
+      militaryFlightsLayer.getParams().selectedMilitaryTrackingId,
+      null,
+    );
 
     militaryFlightsLayer.setParams(
       { selectedMilitaryTrackingId: 'late004' },
@@ -452,18 +594,27 @@ test('real military track path creates no native label and publishes every cache
     assert.equal(_pendingMilitaryTrackingRestoreForTest(), 'late004');
     _addMilitaryTrackingCandidateForTest({
       icao24: 'late004',
-      billboard: { ...billboard, position: Cesium.Cartesian3.fromDegrees(-97.2, 30.7, 6_000) },
+      billboard: {
+        ...billboard,
+        position: Cesium.Cartesian3.fromDegrees(-97.2, 30.7, 6_000),
+      },
       meta: { ...FULL_INFO, callsign: 'LATE4', rawLat: 30.7, rawLon: -97.2 },
       history: [],
     });
     assert.equal(_applyPendingMilitaryTrackingRestoreForTest(), true);
-    assert.equal(militaryFlightsLayer.getParams().selectedMilitaryTrackingId, 'late004');
+    assert.equal(
+      militaryFlightsLayer.getParams().selectedMilitaryTrackingId,
+      'late004',
+    );
 
     militaryFlightsLayer.setParams(
       { selectedMilitaryTrackingId: 'late005' },
       { origin: 'local-restore' },
     );
-    assert.equal(militaryFlightsLayer.trackById(icao24, { origin: 'programmatic' }), true);
+    assert.equal(
+      militaryFlightsLayer.trackById(icao24, { origin: 'programmatic' }),
+      true,
+    );
     assert.equal(
       _pendingMilitaryTrackingRestoreForTest(),
       'late005',
@@ -471,12 +622,18 @@ test('real military track path creates no native label and publishes every cache
     );
     _addMilitaryTrackingCandidateForTest({
       icao24: 'late005',
-      billboard: { ...billboard, position: Cesium.Cartesian3.fromDegrees(-96.6, 31.4, 5_000) },
+      billboard: {
+        ...billboard,
+        position: Cesium.Cartesian3.fromDegrees(-96.6, 31.4, 5_000),
+      },
       meta: { ...FULL_INFO, callsign: 'LATE5', rawLat: 31.4, rawLon: -96.6 },
       history: [],
     });
     assert.equal(_applyPendingMilitaryTrackingRestoreForTest(), true);
-    assert.equal(militaryFlightsLayer.getParams().selectedMilitaryTrackingId, 'late005');
+    assert.equal(
+      militaryFlightsLayer.getParams().selectedMilitaryTrackingId,
+      'late005',
+    );
   } finally {
     militaryFlightsLayer.stopTracking();
     viewer.scene.preUpdate.raiseEvent();
@@ -521,21 +678,47 @@ test('a callsign-less contact is findable by the tail number the app displays',
 
   // The identity analyst_query hands back for this contact.
   const analystId = mapAnalystRecord(icao24, {
-    callsign: null, registration: '6606', rawLat: 40.71, rawLon: -74.01,
+    callsign: null,
+    registration: '6606',
+    rawLat: 40.71,
+    rawLon: -74.01,
   }).id;
-  assert.equal(analystId, '6606', 'the analyst names a callsign-less contact by its tail');
+  assert.equal(
+    analystId,
+    '6606',
+    'the analyst names a callsign-less contact by its tail',
+  );
 
   const found = militaryFlightsLayer.findByQuery(analystId);
-  assert.equal(found?.icao24, icao24, 'and the tracker must resolve that same identity');
-  assert.equal(militaryFlightsLayer.findByQuery('660')?.icao24, icao24, 'prefix match too');
-  assert.equal(militaryFlightsLayer.findByQuery(icao24)?.icao24, icao24, 'hex still wins outright');
+  assert.equal(
+    found?.icao24,
+    icao24,
+    'and the tracker must resolve that same identity',
+  );
+  assert.equal(
+    militaryFlightsLayer.findByQuery('660')?.icao24,
+    icao24,
+    'prefix match too',
+  );
+  assert.equal(
+    militaryFlightsLayer.findByQuery(icao24)?.icao24,
+    icao24,
+    'hex still wins outright',
+  );
 });
 
 test('the analyst record carries the hex key the tracker keys on', () => {
   const record = mapAnalystRecord('ae7f01', {
-    callsign: null, registration: '6606', rawLat: 40.71, rawLon: -74.01,
+    callsign: null,
+    registration: '6606',
+    rawLat: 40.71,
+    rawLon: -74.01,
   });
-  assert.equal(record.icao24, 'ae7f01', 'a resolvable key must ride along with the display label');
+  assert.equal(
+    record.icao24,
+    'ae7f01',
+    'a resolvable key must ride along with the display label',
+  );
 });
 
 test('a registration never outranks another contact’s exact callsign', () => {
@@ -548,18 +731,35 @@ test('a registration never outranks another contact’s exact callsign', () => {
     show: true,
   });
   const base = {
-    type: 'C17', operator: 'USAF', altitudeFt: 25000, speedMps: 180,
-    track: 90, klass: 'widebody', onGround: false,
+    type: 'C17',
+    operator: 'USAF',
+    altitudeFt: 25000,
+    speedMps: 180,
+    track: 90,
+    klass: 'widebody',
+    onGround: false,
   };
   // Registered FIRST, so insertion order favours it.
   _addMilitaryTrackingCandidateForTest({
     icao24: 'ae0aa1',
-    meta: { ...base, callsign: null, registration: 'ZULU777', rawLat: 31.0, rawLon: -97.0 },
+    meta: {
+      ...base,
+      callsign: null,
+      registration: 'ZULU777',
+      rawLat: 31.0,
+      rawLon: -97.0,
+    },
     billboard: billboardAt(-97.0, 31.0),
   });
   _addMilitaryTrackingCandidateForTest({
     icao24: 'ae0bb2',
-    meta: { ...base, callsign: 'ZULU777', registration: '05-9999', rawLat: 31.2, rawLon: -97.2 },
+    meta: {
+      ...base,
+      callsign: 'ZULU777',
+      registration: '05-9999',
+      rawLat: 31.2,
+      rawLon: -97.2,
+    },
     billboard: billboardAt(-97.2, 31.2),
   });
 
@@ -582,24 +782,49 @@ test('two contacts matching at the same strength resolve deterministically', ()
     show: true,
   });
   const base = {
-    type: 'C130', operator: 'USAF', altitudeFt: 21000, speedMps: 150,
-    track: 45, klass: 'turboprop', onGround: false,
+    type: 'C130',
+    operator: 'USAF',
+    altitudeFt: 21000,
+    speedMps: 150,
+    track: 45,
+    klass: 'turboprop',
+    onGround: false,
   };
   // Both registrations begin with QQ7 — a same-tier prefix tie. Registered
   // highest-hex first so insertion order would pick the wrong one.
   _addMilitaryTrackingCandidateForTest({
     icao24: 'aef002',
-    meta: { ...base, callsign: null, registration: 'QQ7-222', rawLat: 32.0, rawLon: -98.0 },
+    meta: {
+      ...base,
+      callsign: null,
+      registration: 'QQ7-222',
+      rawLat: 32.0,
+      rawLon: -98.0,
+    },
     billboard: billboardAt(-98.0, 32.0),
   });
   _addMilitaryTrackingCandidateForTest({
     icao24: 'aef001',
-    meta: { ...base, callsign: null, registration: 'QQ7-111', rawLat: 32.1, rawLon: -98.1 },
+    meta: {
+      ...base,
+      callsign: null,
+      registration: 'QQ7-111',
+      rawLat: 32.1,
+      rawLon: -98.1,
+    },
     billboard: billboardAt(-98.1, 32.1),
   });
 
   const first = militaryFlightsLayer.findByQuery('QQ7')?.icao24;
   const second = militaryFlightsLayer.findByQuery('qq7')?.icao24;
-  assert.equal(first, 'aef001', 'the stable key (lowest hex) wins, not the feed order');
-  assert.equal(second, first, 'and the same query resolves the same way every time');
+  assert.equal(
+    first,
+    'aef001',
+    'the stable key (lowest hex) wins, not the feed order',
+  );
+  assert.equal(
+    second,
+    first,
+    'and the same query resolves the same way every time',
+  );
 });

src/data/militaryNames.js

@@ -14,10 +14,6 @@ export function createMilitaryNamesLoader({
   loadPack = (signal) =>
     loadBundledJson(
       new URL('./local_data/osm_military_names/names.json', import.meta.url),
-      () =>
-        import('./local_data/osm_military_names/names.json', {
-          with: { type: 'json' },
-        }),
       { signal },
     ),
   timeoutMs = MILITARY_NAMES_TIMEOUT_MS,
@@ -93,8 +89,16 @@ export function nameMilitaryFragment(fragment, names) {
   };
 }
 
-/** Area-ranked spatial thinning of visible label points, including dateline views. */
-export function militaryNamesInView(names, box, cap = MILITARY_POINT_CAP) {
+/**
+ * Area-ranked spatial thinning of visible label points, including dateline
+ * views. With `thinned` false every point in the box is kept, up to `cap`.
+ */
+export function militaryNamesInView(
+  names,
+  box,
+  cap = MILITARY_POINT_CAP,
+  thinned = true,
+) {
   const width =
     box.east >= box.west ? box.east - box.west : 360 + box.east - box.west;
   const height = box.north - box.south;
@@ -107,7 +111,7 @@ export function militaryNamesInView(names, box, cap = MILITARY_POINT_CAP) {
       continue;
     count++;
     const cell = `${Math.min(31, Math.floor((x / width) * 32))}:${Math.min(15, Math.floor(((record.latitude - box.south) / height) * 16))}`;
-    if (cells.has(cell) || records.length >= cap) continue;
+    if ((thinned && cells.has(cell)) || records.length >= cap) continue;
     cells.add(cell);
     records.push(record);
   }

src/data/militaryNames.test.mjs

@@ -217,3 +217,13 @@ test('a close view keeps the parent name inside its polygon when the usual label
     hole,
   );
 });
+
+test('queries can take every named site in a box instead of one per display cell', async () => {
+  const names = await loadMilitaryNames();
+  const box = { west: -2, south: 50, east: 2, north: 54 };
+  const thinned = militaryNamesInView(names, box);
+  const all = militaryNamesInView(names, box, Infinity, false);
+  assert.equal(all.count, thinned.count);
+  assert.equal(all.records.length, all.count);
+  assert.ok(all.records.length > thinned.records.length);
+});

src/data/militaryRegistry.js

@@ -1,7 +1,7 @@
 import { createMilitaryRegistry } from '../layers/aircraft/classification.js';
-import { createAdsbLolSource } from '../sources/live/standalone.js';
+import { createMilitarySource } from '../sources/live/standalone.js';
 
-const registry = createMilitaryRegistry({ source: createAdsbLolSource() });
+const registry = createMilitaryRegistry({ source: createMilitarySource() });
 export const isMilitaryLayerActive = registry.isMilitaryLayerActive;
 export const setMilitaryLayerActive = registry.setMilitaryLayerActive;
 export const onMilitaryLayerActiveChange = registry.onMilitaryLayerActiveChange;

src/data/naturalEarthRegions.js

@@ -124,17 +124,9 @@ let _entries = null;
 const PACKS = {
   regions: {
     url: new URL('./local_data/natural_earth/regions.json', import.meta.url),
-    importJson: () =>
-      import('./local_data/natural_earth/regions.json', {
-        with: { type: 'json' },
-      }),
   },
   marine: {
     url: new URL('./local_data/natural_earth/marine.json', import.meta.url),
-    importJson: () =>
-      import('./local_data/natural_earth/marine.json', {
-        with: { type: 'json' },
-      }),
   },
 };
 
@@ -178,8 +170,8 @@ function buildEntries(pack, kind) {
  */
 const loadIndex = createRetryableLoader(async () => {
   const [regions, marine] = await Promise.all([
-    loadBundledJson(PACKS.regions.url, PACKS.regions.importJson),
-    loadBundledJson(PACKS.marine.url, PACKS.marine.importJson),
+    loadBundledJson(PACKS.regions.url),
+    loadBundledJson(PACKS.marine.url),
   ]);
   _entries = [
     ...buildEntries(regions, 'natural'),

src/data/neighborhoodPolygons.js

@@ -22,10 +22,6 @@ const CITY_FILES = [
       './local_data/neighborhoods/san-francisco.json',
       import.meta.url,
     ),
-    importJson: () =>
-      import('./local_data/neighborhoods/san-francisco.json', {
-        with: { type: 'json' },
-      }),
   },
 ];
 
@@ -112,7 +108,7 @@ function cityLoader(city) {
   let loader = _cityLoaders.get(city.id);
   if (!loader) {
     loader = createRetryableLoader(async () => {
-      const fc = await loadBundledJson(city.url, city.importJson);
+      const fc = await loadBundledJson(city.url);
       return Array.isArray(fc.features) ? fc.features : [];
     });
     _cityLoaders.set(city.id, loader);

src/data/pickRegistry.js

@@ -65,6 +65,23 @@ export function unregisterPickOwner(layerId) {
   _owners.delete(layerId);
 }
 
+/**
+ * The registered layer that owns a picked id, or null.
+ * @param {string} pickedId - Canonical pick id from {@link resolvePickId}.
+ * @returns {string|null} Owning layer id.
+ */
+export function findPickOwner(pickedId) {
+  if (!pickedId) return null;
+  for (const [ownerId, predicate] of _owners) {
+    try {
+      if (predicate(pickedId)) return ownerId;
+    } catch {
+      // a broken predicate must never break picking
+    }
+  }
+  return null;
+}
+
 /**
  * True when some OTHER registered layer owns the picked id.
  * @param {string} layerId - The asking layer's id (excluded from the scan).

src/data/pickedContext.js

@@ -0,0 +1,128 @@
+import { getContextStore, isContextRecordActive } from './contextStore.js';
+import { findPickOwner, resolvePickId } from './pickRegistry.js';
+
+/**
+ * Resolve a `scene.pick()` result to the identity a person would name: which
+ * layer, which record, and its display label.
+ *
+ * Two lanes, in order:
+ *  1. Context-store carriers. Entity-backed layers (infrastructure GeoJSON,
+ *     selected vessels, fires, installations) stamp `__gevContextId` on the
+ *     picked object, and the store record already carries the label and
+ *     position voice uses everywhere else.
+ *  2. Pick owners. Primitive-backed layers (aircraft, satellites, vessels)
+ *     register an ownership predicate in `pickRegistry`; the owning layer's
+ *     `findByQuery` turns the pick id into a live descriptor.
+ *
+ * Trails claim their pick ids only to make clicks inert, so they never
+ * resolve. Disabled layers never resolve: what the user cannot see is not
+ * what they are pointing at.
+ */
+
+const KIND_BY_LAYER = Object.freeze({
+  flights: 'aircraft',
+  military: 'aircraft',
+  'local-adsb': 'aircraft',
+  'ais-live-vessels': 'vessel',
+  satellites: 'satellite',
+  'local-firms': 'fire',
+});
+
+const IGNORED_OWNERS = new Set(['trails']);
+
+function text(value) {
+  return String(value ?? '').trim();
+}
+
+function finite(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+/** Kind of thing a layer holds, for deixis ("this aircraft", "this place"). */
+export function pickedKindForLayer(layerId) {
+  return KIND_BY_LAYER[layerId] || 'feature';
+}
+
+function contextCarrierRecord(picked, dataManager) {
+  const store = getContextStore();
+  for (const carrier of [
+    picked?.id,
+    picked?.primitive?.id,
+    picked?.primitive,
+  ]) {
+    const contextId =
+      carrier && typeof carrier === 'object' ? carrier.__gevContextId : null;
+    if (!contextId) continue;
+    const record = store.entities.get(contextId);
+    if (record && isContextRecordActive(record, dataManager)) return record;
+  }
+  return null;
+}
+
+function fromRecord(record) {
+  const layerId = record.layerId || null;
+  const id =
+    layerId === 'ais-live-vessels' && record.properties?.mmsi
+      ? String(record.properties.mmsi)
+      : String(record.id);
+  return {
+    layerId,
+    id,
+    label:
+      text(record.label) ||
+      text(record.properties?.name) ||
+      text(record.layerName) ||
+      id,
+    kind: pickedKindForLayer(layerId),
+    lat: finite(record.latitude),
+    lon: finite(record.longitude),
+  };
+}
+
+function descriptorLabel(found, fallback) {
+  return (
+    text(found?.callsign) ||
+    text(found?.registration) ||
+    text(found?.name) ||
+    text(found?.icao24) ||
+    text(found?.mmsi) ||
+    text(found?.noradId) ||
+    fallback
+  );
+}
+
+/**
+ * @param {object|null} picked Result of `scene.pick()`.
+ * @param {object} [options]
+ * @param {object} [options.dataManager] Layer lifecycle (enabled state, modules).
+ * @returns {{layerId: string, id: string, label: string, kind: string, lat: number|null, lon: number|null, altitudeM?: number|null}|null}
+ */
+export function resolvePickedContext(picked, { dataManager = null } = {}) {
+  if (!picked) return null;
+  const record = contextCarrierRecord(picked, dataManager);
+  if (record) return fromRecord(record);
+
+  const pickId = resolvePickId(picked);
+  if (!pickId) return null;
+  const layerId = findPickOwner(pickId);
+  if (!layerId || IGNORED_OWNERS.has(layerId)) return null;
+  if (dataManager?.isEnabled && !dataManager.isEnabled(layerId)) return null;
+  const layer = dataManager?.layers?.get?.(layerId);
+  let found = null;
+  try {
+    found = layer?.module?.findByQuery?.(pickId) || null;
+  } catch {
+    found = null;
+  }
+  return {
+    layerId,
+    id: pickId,
+    label: descriptorLabel(found, text(layer?.name) || pickId),
+    kind: pickedKindForLayer(layerId),
+    lat: finite(found?.latitude),
+    lon: finite(found?.longitude),
+    altitudeM: finite(found?.altitudeM),
+  };
+}

src/data/pickedContext.test.mjs

@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+globalThis.window ||= globalThis;
+globalThis.CustomEvent ||= class CustomEvent {
+  constructor(type, init) {
+    this.type = type;
+    this.detail = init?.detail;
+  }
+};
+globalThis.dispatchEvent ||= () => true;
+
+const { registerEntityContext } = await import('./contextStore.js');
+const { registerPickOwner, unregisterPickOwner, findPickOwner } = await import('./pickRegistry.js');
+const { resolvePickedContext, pickedKindForLayer } = await import('./pickedContext.js');
+
+function manager({ enabled = new Set(['flights', 'local-datacenters']), modules = {} } = {}) {
+  return {
+    isEnabled: (id) => enabled.has(id),
+    layers: new Map(Object.entries(modules).map(([id, module]) => [id, { name: id, module }])),
+  };
+}
+
+test('an aircraft billboard resolves through its pick owner to a live label', () => {
+  registerPickOwner('flights', (id) => id === 'a1b2c3');
+  const dataManager = manager({
+    modules: {
+      flights: {
+        findByQuery: (q) => (q === 'a1b2c3' ? { icao24: 'a1b2c3', callsign: 'UPS793', latitude: 30.2, longitude: -97.7, altitudeM: 9000 } : null),
+      },
+    },
+  });
+  const picked = { id: 'a1b2c3', primitive: {} };
+  assert.equal(findPickOwner('a1b2c3'), 'flights');
+  assert.deepEqual(resolvePickedContext(picked, { dataManager }), {
+    layerId: 'flights',
+    id: 'a1b2c3',
+    label: 'UPS793',
+    kind: 'aircraft',
+    lat: 30.2,
+    lon: -97.7,
+    altitudeM: 9000,
+  });
+  unregisterPickOwner('flights');
+});
+
+test('an entity-backed feature resolves through the context store', () => {
+  const entity = { show: true };
+  registerEntityContext(entity, {
+    id: 'local-datacenters:7',
+    layerId: 'local-datacenters',
+    label: 'Data Center 7',
+    latitude: 30.1,
+    longitude: -97.6,
+  });
+  const out = resolvePickedContext({ id: entity }, { dataManager: manager() });
+  assert.deepEqual(out, {
+    layerId: 'local-datacenters',
+    id: 'local-datacenters:7',
+    label: 'Data Center 7',
+    kind: 'feature',
+    lat: 30.1,
+    lon: -97.6,
+  });
+});
+
+test('disabled layers, trails and empty picks never resolve', () => {
+  registerPickOwner('military', (id) => id === 'm1');
+  assert.equal(resolvePickedContext({ id: 'm1' }, { dataManager: manager() }), null, 'military is disabled');
+  unregisterPickOwner('military');
+  assert.equal(resolvePickedContext({ id: 'gev-trail:1' }, { dataManager: manager() }), null);
+  assert.equal(resolvePickedContext(null), null);
+  assert.equal(resolvePickedContext({ id: 'unknown' }, { dataManager: manager() }), null);
+  assert.equal(pickedKindForLayer('ais-live-vessels'), 'vessel');
+});

src/data/sharedOsmDisplays.test.mjs

@@ -7,6 +7,7 @@ import { createBhoteKoshiLocatorLayer } from './bhoteKoshiLocator.js';
 import { createWorldAnnotationRenderer } from '../annotations/worldAnnotationRenderer.js';
 import * as annotations from '../annotations/worldAnnotationRenderer.js';
 import { createDirectionsLayer } from '../layers/directions/index.js';
+import { createDirectionsSource } from '../layers/directions/source.js';
 import { createLifecycle as createCctvLifecycle } from '../layers/cctv/lifecycle.js';
 import * as input from './inputOwnership.js';
 import { createOverpassAlprSource } from '../layers/alpr/source.js';
@@ -64,7 +65,7 @@ test('voice route geometry introduces the shared OSM credit', (t) => {
 test('Directions introduces the shared OSM credit when the requested route draws', async (t) => {
   const v = viewer(t);
   t.mock.method(globalThis, 'fetch', async () => Response.json({ ok: true, geometry: [[0, 0], [0.01, 0.01]], steps: [] }));
-  const layer = createDirectionsLayer({ services: {
+  const layer = createDirectionsLayer({ source: createDirectionsSource(), services: {
     credits: { showOsmCredit, hideOsmCredit }, annotations, input, scenePick: {}, camera: {},
     overlays: { setOverlayEntries: noop, setOverlaySourceVisible: noop, clearOverlaySource: noop },
     render: { governorRequestRender: noop, holdContinuousRender: noop, releaseContinuousRender: noop },

src/data/tr3bRegistry.test.mjs

@@ -189,7 +189,7 @@ test('a conversion survives a poll refresh, in both the billboard and the tracke
   const realFetch = globalThis.fetch;
   const nowSec = Math.floor(Date.now() / 1000);
   globalThis.fetch = async (url) => {
-    if (!String(url).startsWith('/api/opensky')) {
+    if (!String(url).startsWith('/api/flights')) {
       return { ok: true, status: 200, json: async () => ({ ac: [] }) };
     }
     return {
@@ -309,7 +309,7 @@ test('conversions are session-scoped and no lifecycle path clears them', async (
     meta: { callsign: 'OLD1', altitude: 9_000, klass: 'airliner', rawLat: 30.2, rawLon: -97.7 },
   });
   const realFetch = globalThis.fetch;
-  globalThis.fetch = async (url) => (String(url).startsWith('/api/opensky')
+  globalThis.fetch = async (url) => (String(url).startsWith('/api/flights')
     ? { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ time: 0, states: [] }) }
     : { ok: true, status: 200, json: async () => ({ ac: [] }) });
   try {

src/firstRunExperience.js

@@ -217,6 +217,9 @@ export function shouldShowFirstRun({
   if (hasShareState) return false;
   const params = new URLSearchParams(location?.search || '');
   if (params.get('welcome') === '0') return false;
+  // An embedded globe never shows the welcome launcher.
+  if (params.get('embed') === '1' || globalThis.GEV_EMBED_INLINE === true)
+    return false;
   // The demo/support escape hatch outranks both suppressions on purpose.
   if (params.get('welcome') === '1') return true;
   if (readStored('local', storage, FIRST_RUN_STORAGE_KEY) === 'suppressed')

src/firstRunExperience.test.mjs

@@ -656,7 +656,7 @@ test('the DISPLAY rail starts collapsed on a first run, and a stored choice wins
 
 // ── Voice: instruction-only, tool schema unchanged ─────────────────────
 
-test('the voice TOOL SCHEMA matches the pinned release — the mission mapping is instructions only', () => {
+test('the voice TOOL SCHEMA matches the pinned contract — the mission mapping is instructions only', () => {
   // Analyst layers and the separate satellite-pass tool deliberately extend the schema.
   // Canonical serialization pins every tool name, description, property and
   // ordering while allowing source formatting. Derived from the unchanged
@@ -667,12 +667,17 @@ test('the voice TOOL SCHEMA matches the pinned release — the mission mapping i
   // Cyber deliberately adds one layout; first-run missions still change no tools.
   hudLayout.enum = hudLayout.enum.filter((layout) => layout !== 'cyber');
   const block = JSON.stringify(legacyTools);
-  // Re-derived for the additive `local-adsb` set_layer_visibility value and
-  // its common-name mapping; the missions still ride existing tools.
-  assert.equal(block.length, 27432, 'serialized tool schema length drifted');
+  // Re-derived for the voice layer manifest (generated layer enums, alias and
+  // field hints), point-and-ask's pointer/referent arguments and the prompt
+  // consolidation (shorter analyst, annotate_map and ISS wording), plus the
+  // 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');
   assert.equal(
     crypto.createHash('sha256').update(block).digest('hex'),
-    'a2a4a787f4528f75b01f3f42caec636f29c37452c0d45b11f4f986171d6be57d',
+    'b316ca2e67848eb565b6847ac044a19d1465d8ef8252a5dfbd7d947a2a36d5ed',
     '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/i18n/locales/en/cockpit.js

@@ -311,7 +311,9 @@ export default {
   // NORMAL default) into {style} templates.
   'vision.styleNameNightVision': 'Night vision',
   'vision.styleNameThermal': 'Thermal',
+  'vision.styleNameAnime': 'Anime',
   'vision.styleNameNoir': 'Noir',
+  'vision.styleNameSnow': 'Snow',
   'vision.currentAriaTemplate':
     'Current cockpit vision style: {style}. Activate for next style.',
   'vision.currentTitleTemplate': 'Current style: {style} — click for next',

src/i18n/locales/en/layers.js

@@ -142,6 +142,7 @@ export default {
   'meta.minutesAgo': '{count}m ago',
   'meta.hoursAgo': '{count}h ago',
   'meta.never': 'never',
+  'meta.dataSourceUnavailable': 'Data source unavailable',
   'meta.loading': 'loading...',
   'meta.uncertainLifecycle':
     'UNCERTAIN · {source} · lifecycle state requires reconciliation',

src/keySetup.js

@@ -1,4 +1,8 @@
 import { createSurfaceKeyboard } from './ui/surfaceKeyboard.js';
+import {
+  readStoredCloudVoiceAuthMode,
+  writeStoredCloudVoiceAuthMode,
+} from './voice/cloudVoiceAuth.js';
 
 /**
  * The POWER UP surface — paste a key, get a power.
@@ -46,6 +50,52 @@ export function collectKeyUpdates(fields) {
   return updates;
 }
 
+function sleepWithSignal(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason || new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason || new DOMException('Aborted', 'AbortError'));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+export async function waitForChatGptOAuth({
+  fetchImpl,
+  signal,
+  timeoutMs = 120_000,
+  pollMs = 1_000,
+  now = () => Date.now(),
+  sleep = sleepWithSignal,
+} = {}) {
+  const deadline = now() + Math.max(0, timeoutMs);
+  while (!signal?.aborted && now() <= deadline) {
+    const response = await fetchImpl('/api/realtime/oauth-status', {
+      cache: 'no-store',
+      signal,
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (signal?.aborted) return false;
+    if (response.ok && payload.available) return true;
+    if (!response.ok || payload.loginFailed) {
+      throw new Error(
+        payload.error || 'Could not check ChatGPT sign-in. Try again.',
+      );
+    }
+    if (now() >= deadline) break;
+    await sleep(Math.max(0, pollMs), signal);
+  }
+  return false;
+}
+
 /**
  * After the FIRST Google key lands, the restart's reload should boot the
  * photoreal default — not faithfully restore the auto-selected keyless OSM
@@ -69,6 +119,21 @@ export function stripKeylessBasemapFromHash(hash) {
 
 const TIER_DOTS = Object.freeze({ metered: '🔴', free: '🟡' });
 
+function updateCloudVoiceAuthControl(auth, busy = false) {
+  const mode = readStoredCloudVoiceAuthMode();
+  const state = auth.querySelector('.key-setup-cloud-auth-state');
+  const toggle = auth.querySelector('[data-cloud-voice-auth-toggle]');
+  state.textContent =
+    mode === 'oauth' ? 'VOICE AUTH · CHATGPT OAUTH' : 'VOICE AUTH · API KEY';
+  toggle.textContent = mode === 'oauth' ? 'USE API KEY' : 'USE CHATGPT OAUTH';
+  toggle.title =
+    mode === 'oauth'
+      ? 'Use OPENAI_API_KEY for the next cloud voice session'
+      : 'Use the signed-in local ChatGPT/Codex OAuth session for the next cloud voice session';
+  // Keep the control focusable while the delegated handler blocks repeats.
+  toggle.setAttribute('aria-disabled', String(busy));
+}
+
 /** Build one key row. All content is our own registry text, set via textContent. */
 function buildRow(documentRef, key) {
   const row = documentRef.createElement('section');
@@ -155,6 +220,19 @@ function buildRow(documentRef, key) {
     }
     row.append(fields);
   }
+  if (key.id === 'openai') {
+    const auth = documentRef.createElement('div');
+    auth.className = 'key-setup-cloud-auth';
+    const state = documentRef.createElement('span');
+    state.className = 'key-setup-cloud-auth-state';
+    const toggle = documentRef.createElement('button');
+    toggle.type = 'button';
+    toggle.className = 'key-setup-cloud-auth-toggle';
+    toggle.dataset.cloudVoiceAuthToggle = 'true';
+    auth.append(state, toggle);
+    updateCloudVoiceAuthControl(auth);
+    row.append(auth);
+  }
   return row;
 }
 
@@ -235,8 +313,14 @@ export async function initKeySetup({
   const statusLine = root.querySelector('[data-key-setup-status]');
   const defaultStatusText = statusLine?.textContent || '';
   let busy = false;
+  let oauthBusy = false;
   let open = false;
 
+  const syncCloudVoiceAuth = () => {
+    for (const auth of rowsHost.querySelectorAll('.key-setup-cloud-auth'))
+      updateCloudVoiceAuthControl(auth, oauthBusy);
+  };
+
   const render = (nextStatus) => {
     if (disposed) return;
     status = nextStatus;
@@ -250,6 +334,7 @@ export async function initKeySetup({
     rowsHost.textContent = '';
     for (const key of status.keys || [])
       rowsHost.append(buildRow(documentRef, key));
+    syncCloudVoiceAuth();
   };
 
   const visible = () =>
@@ -335,7 +420,11 @@ export async function initKeySetup({
               globalThis.location?.hash?.slice(1) || '',
             );
             if (next !== null)
-              globalThis.history?.replaceState?.(null, '', `#${next}`);
+              globalThis.history?.replaceState?.(
+                null,
+                '',
+                new URL(`#${next}`, globalThis.location.href).href,
+              );
           } catch {
             // Continuity is a nicety, never a blocker.
           }
@@ -382,6 +471,100 @@ export async function initKeySetup({
   applyButton?.addEventListener('click', onApply);
   // Remove buttons are rendered per row; delegate so re-renders stay wired.
   rowsHost?.addEventListener('click', (event) => {
+    const authButton = event.target?.closest?.(
+      '[data-cloud-voice-auth-toggle]',
+    );
+    if (authButton && !disposed) {
+      if (oauthBusy) return;
+      void (async () => {
+        const current = readStoredCloudVoiceAuthMode();
+        if (current === 'oauth') {
+          writeStoredCloudVoiceAuthMode('api-key');
+          syncCloudVoiceAuth();
+          say('Cloud voice will use OPENAI_API_KEY on the next session.');
+          return;
+        }
+        oauthBusy = true;
+        syncCloudVoiceAuth();
+        say('Checking local ChatGPT OAuth sign-in…');
+        try {
+          const response = await doFetch('/api/realtime/oauth-status', {
+            cache: 'no-store',
+            signal: lifetime.signal,
+          });
+          const payload = await response.json().catch(() => ({}));
+          if (lifetime.signal.aborted) return;
+          if (!response.ok)
+            throw new Error(
+              payload.error || 'Could not check ChatGPT sign-in.',
+            );
+          if (payload.available) {
+            writeStoredCloudVoiceAuthMode('oauth');
+            syncCloudVoiceAuth();
+            say(
+              'ChatGPT OAuth selected for cloud voice. Your API key stays saved and available.',
+            );
+            return;
+          }
+
+          say(
+            payload.code === 'CODEX_OAUTH_REAUTH_REQUIRED'
+              ? 'ChatGPT sign-in expired. Opening sign-in again…'
+              : 'Opening ChatGPT sign-in in your browser…',
+          );
+          const loginResponse = await doFetch('/api/realtime/oauth-login', {
+            method: 'POST',
+            cache: 'no-store',
+            signal: lifetime.signal,
+          });
+          const loginPayload = await loginResponse.json().catch(() => ({}));
+          if (lifetime.signal.aborted) return;
+          if (!loginResponse.ok) {
+            say(
+              loginPayload.error ||
+                payload.error ||
+                'Could not start ChatGPT sign-in on this machine.',
+            );
+            return;
+          }
+          if (loginPayload.available) {
+            writeStoredCloudVoiceAuthMode('oauth');
+            syncCloudVoiceAuth();
+            say(
+              'ChatGPT OAuth selected for cloud voice. Your API key stays saved and available.',
+            );
+            return;
+          }
+
+          say(
+            'Finish ChatGPT sign-in in the browser. Waiting for it to complete…',
+          );
+          const available = await waitForChatGptOAuth({
+            fetchImpl: doFetch,
+            signal: lifetime.signal,
+          });
+          if (lifetime.signal.aborted) return;
+          if (!available) {
+            say(
+              'ChatGPT sign-in timed out. Click USE CHATGPT OAUTH to try again.',
+            );
+            return;
+          }
+          writeStoredCloudVoiceAuthMode('oauth');
+          syncCloudVoiceAuth();
+          say(
+            'ChatGPT sign-in complete. OAuth will be used for the next cloud voice session.',
+          );
+        } catch (error) {
+          if (lifetime.signal.aborted) return;
+          say(`OAuth check failed: ${error?.message || error}`);
+        } finally {
+          oauthBusy = false;
+          if (!disposed) syncCloudVoiceAuth();
+        }
+      })();
+      return;
+    }
     const button = event.target?.closest?.('[data-key-setup-remove]');
     if (disposed || !button || busy) return;
     let envVars = [];

src/keySetup.test.mjs

@@ -5,6 +5,7 @@ import {
   keySetupChipLabel,
   stripKeylessBasemapFromHash,
   bindKeySetupPlacement,
+  waitForChatGptOAuth,
 } from './keySetup.js';
 
 test('setup placement moves the same button only in Cyber and disconnects on teardown', () => {
@@ -61,6 +62,64 @@ test('collectKeyUpdates keeps only non-empty trimmed values', () => {
   assert.deepEqual(collectKeyUpdates(null), {});
 });
 
+test('OAuth login polling stops as soon as local ChatGPT auth becomes available', async () => {
+  let checks = 0;
+  let clock = 0;
+  const available = await waitForChatGptOAuth({
+    fetchImpl: async () => {
+      checks += 1;
+      return {
+        ok: true,
+        json: async () => ({ available: checks >= 3 }),
+      };
+    },
+    timeoutMs: 10_000,
+    pollMs: 100,
+    now: () => clock,
+    sleep: async (ms) => {
+      clock += ms;
+    },
+  });
+  assert.equal(available, true);
+  assert.equal(checks, 3);
+});
+
+test('OAuth login polling stops on login or HTTP failure instead of waiting for timeout', async () => {
+  for (const result of [
+    { ok: true, payload: { available: false, loginFailed: true, error: 'Sign-in failed.' } },
+    { ok: false, payload: { error: 'Sign-in is local only.' } },
+  ]) {
+    let checks = 0;
+    await assert.rejects(waitForChatGptOAuth({
+      fetchImpl: async () => { checks += 1; return { ok: result.ok, json: async () => result.payload }; },
+      sleep: () => assert.fail('failed login must stop polling'),
+    }), { message: result.payload.error });
+    assert.equal(checks, 1);
+  }
+});
+
+test('OAuth login polling respects timeout and an aborted setup surface', async () => {
+  let clock = 0;
+  let checks = 0;
+  const poll = { fetchImpl: async () => { checks += 1; return { ok: true, json: async () => ({ available: false, pending: true }) }; } };
+  assert.equal(await waitForChatGptOAuth({ ...poll, timeoutMs: 100, pollMs: 100, now: () => clock, sleep: async (ms) => { clock += ms; } }), false);
+  assert.equal(checks, 2);
+  const controller = new AbortController();
+  controller.abort();
+  assert.equal(await waitForChatGptOAuth({ ...poll, signal: controller.signal }), false);
+  assert.equal(checks, 2, 'aborted polling does not fetch');
+});
+
+test('OAuth polling ignores a ready response received after the surface was aborted', async () => {
+  const controller = new AbortController();
+  const available = await waitForChatGptOAuth({
+    signal: controller.signal,
+    fetchImpl: async () => ({ ok: true, json: async () => { controller.abort(); return { available: true }; } }),
+    sleep: () => assert.fail('aborted polling must not continue'),
+  });
+  assert.equal(available, false);
+});
+
 test('the first Google key strips ONLY the keyless OSM basemap from the share hash', () => {
   const stripped = stripKeylessBasemapFromHash('lat=30.2&lon=-97.7&map=osm&style=normal');
   assert.ok(stripped !== null);

src/keySetupCore.mjs

@@ -1,7 +1,8 @@
 /**
  * Key setup ("POWER UP") — the pure core.
  *
- * One registry, three pure functions, zero dependencies. The dev server's
+ * One registry and pure functions; its only import is the proxy-header check
+ * shared with the other local gates (localRequestGate.mjs). The dev server's
  * /api/setup endpoints (vite.config.js) and the in-app panel (keySetup.js)
  * are both thin shells over this module, so what a key is called, what it
  * unlocks, and how a .env line is written each live in exactly one place.
@@ -11,6 +12,8 @@
  * behavior below unit-testable.
  */
 
+import { hasProxySignals } from './localRequestGate.mjs';
+
 /** Longest accepted key/token value. Real provider keys are all far shorter. */
 export const KEY_SETUP_VALUE_LIMIT = 512;
 
@@ -25,7 +28,7 @@ export const KEY_SETUP_APPEND_HEADER =
  * Provider credentials, in display order — most magic per
  * minute first. `tier` mirrors the README's color legend: 'metered' (🔴) is a
  * billing-enabled account, 'free' (🟡) is a register-and-paste key.
- * `clientExposed` marks the two keys that are injected into the browser
+ * `clientExposed` marks the keys that are injected into the browser
  * bundle by design (restrict them at the provider, per SECURITY.md).
  * `hidden` keeps advanced configuration out of the panel and missing-key count.
  */
@@ -52,7 +55,7 @@ export const KEY_SETUP_KEYS = Object.freeze([
   Object.freeze({
     id: 'openai',
     title: 'OPENAI',
-    unlocks: 'Voice control — talk to the planet',
+    unlocks: 'Voice control — API key or ChatGPT OAuth',
     getUrl: 'https://platform.openai.com/api-keys',
     envVars: Object.freeze(['OPENAI_API_KEY']),
     tier: 'metered',
@@ -77,7 +80,7 @@ export const KEY_SETUP_KEYS = Object.freeze([
     id: 'tomtom',
     title: 'TOMTOM',
     unlocks: 'Real live traffic (keyless runs a simulation)',
-    getUrl: 'https://developer.tomtom.com',
+    getUrl: 'https://my.tomtom.com/keys',
     envVars: Object.freeze(['TOMTOM_API_KEY']),
     tier: 'free',
   }),
@@ -98,6 +101,16 @@ export const KEY_SETUP_KEYS = Object.freeze([
     envVars: Object.freeze(['OPENSKY_CLIENT_ID', 'OPENSKY_CLIENT_SECRET']),
     tier: 'free',
   }),
+  Object.freeze({
+    id: 'mapillary',
+    title: 'MAPILLARY',
+    unlocks:
+      'Street-level imagery and coverage in the Street Level layer. Free: register an app in the Mapillary developer dashboard and paste its Client Token',
+    getUrl: 'https://www.mapillary.com/dashboard/developers',
+    envVars: Object.freeze(['MAPILLARY_CLIENT_TOKEN']),
+    tier: 'free',
+    clientExposed: true,
+  }),
   Object.freeze({
     id: 'launch-library',
     title: 'LAUNCH LIBRARY',
@@ -184,6 +197,24 @@ export function parseWindowsUserSid(stdout) {
     : null;
 }
 
+/**
+ * Whether the launcher has sharing on. Every sharing signal the launcher
+ * recognizes (scripts/pinokio-preflight.mjs) counts, so the two sets cannot
+ * drift apart. One DELIBERATE divergence: preflight is a boot check that
+ * treats an empty PINOKIO_SHARE_VAR as sharing-on (fail closed before Start),
+ * but here an empty/unset value is the NORMAL git-clone and Pinokio state, so
+ * a bare/sentinel value is not sharing; only a real tunnel var is.
+ */
+export function isSharingEnabled(env = {}) {
+  const shareVar = String(env.PINOKIO_SHARE_VAR ?? '').trim();
+  return (
+    ['PINOKIO_SHARE_CLOUDFLARE', 'PINOKIO_SHARE_LOCAL'].some((name) =>
+      /^(1|true)$/i.test(String(env[name] || '').trim()),
+    ) ||
+    (shareVar !== '' && shareVar !== '__gev_sharing_disabled__')
+  );
+}
+
 /**
  * The admission gate for the Provider Settings endpoints — pure, exported so
  * every refusal below is pinned by a unit assertion rather than a review note.
@@ -219,20 +250,7 @@ export function admitKeySetupRequest({
   // on this machine, whatever its socket says. Refuse them outright as defense
   // in depth — the shipped tunnel (Pinokio) is force-closed at boot, so these
   // only appear when someone has deliberately fronted the dev server.
-  const PROXY_SIGNALS = [
-    'forwarded',
-    'via',
-    'x-forwarded-for',
-    'x-forwarded-host',
-    'x-forwarded-port',
-    'x-forwarded-proto',
-    'x-real-ip',
-    'cf-connecting-ip',
-    'cf-ray',
-  ];
-  if (
-    PROXY_SIGNALS.some((name) => String(proxyHeaders[name] || '').trim() !== '')
-  ) {
+  if (hasProxySignals(proxyHeaders)) {
     return {
       ok: false,
       status: 403,
@@ -249,13 +267,7 @@ export function admitKeySetupRequest({
   // tunnel var is. This is defense in depth regardless: the loopback+Host checks
   // below independently refuse LAN/tunnel traffic, and under Pinokio the launcher
   // refuses to boot at all when sharing is genuinely on.
-  const shareVar = String(env.PINOKIO_SHARE_VAR ?? '').trim();
-  const sharingEnabled =
-    ['PINOKIO_SHARE_CLOUDFLARE', 'PINOKIO_SHARE_LOCAL'].some((name) =>
-      /^(1|true)$/i.test(String(env[name] || '').trim()),
-    ) ||
-    (shareVar !== '' && shareVar !== '__gev_sharing_disabled__');
-  if (sharingEnabled) {
+  if (isSharingEnabled(env)) {
     return {
       ok: false,
       status: 403,

src/layers/aircraft/index.js

@@ -9,6 +9,7 @@ export * from '../../data/cockpitContactDot.js';
 export * from '../../data/contactMatch.js';
 export * from '../../data/iconOrientation.js';
 export * from '../../data/layerState.js';
+export * from '../../data/layerStateCoordinator.js';
 export * from '../../data/modelVisualAnchor.js';
 export * from '../../data/motionModel.js';
 export * from '../../data/renderAltitude.js';

src/layers/alpr/index.js

@@ -392,6 +392,37 @@ export function createAlprCamerasLayer({ source, services } = {}) {
         ],
       };
     },
+    /**
+     * Snapshot loaded ALPR cameras (the nearby query box) as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, lat, lon, operator, manufacturer, cameraType, directionDeg}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!state.enabled) return [];
+      const result = [];
+      for (const record of state.records || []) {
+        if (result.length >= maxCount) break;
+        if (
+          !Number.isFinite(record.latitude) ||
+          !Number.isFinite(record.longitude)
+        )
+          continue;
+        result.push({
+          id: record.id,
+          lat: record.latitude,
+          lon: record.longitude,
+          operator: record.operator ?? null,
+          manufacturer: record.manufacturer ?? null,
+          cameraType: record.cameraType ?? null,
+          directionDeg: Number.isFinite(record.directionDeg)
+            ? record.directionDeg
+            : null,
+        });
+      }
+      return result;
+    },
     getStats() {
       return {
         count: state.dataSource?.entities.values.length || 0,

src/layers/awareness/controls.js

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

src/layers/awareness/model.js

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

src/layers/awareness/navigation.js

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

src/layers/awareness/panel.js

@@ -6,6 +6,15 @@ import {
 import { t } from '../../i18n/index.js';
 import { AWARENESS_PAGE_SIZE, AWARENESS_PAGE_ROTATE_MS } from './policy.js';
 
+/** Format a cohort total without presenting a retained cap as exact. */
+export function formatAwarenessCount(summary = {}) {
+  if (!Number.isFinite(summary.count)) return '?';
+  const count = summary.count.toLocaleString('en-US');
+  return summary.complete === false || summary.truncated === true
+    ? `At least ${count}`
+    : count;
+}
+
 export function createPanel({ state: layerState, services, parts, source }) {
   function ensurePanel() {
     if (layerState.panel) return layerState.panel;
@@ -62,7 +71,7 @@ export function createPanel({ state: layerState, services, parts, source }) {
 
   function rowHtml(cohort) {
     const summary = cohort.summary;
-    const count = summary.count === null ? '?' : String(summary.count);
+    const count = formatAwarenessCount(summary);
     const page = layerState.cohortPages.get(cohort.id) || 0;
     const nearest = summary.nearest
       .slice(page, page + AWARENESS_PAGE_SIZE)

src/layers/awareness/policy.js

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

src/layers/awareness/queries.js

@@ -35,7 +35,7 @@ export function createQueries({ state: layerState, services, parts, source }) {
     //     setInstallationStatus is only ever called with
     //     loading/zoom-in/ready/stale/empty/unavailable.
     //   - ais-live-vessels is what the predicate below is FOR. Its enable() and
-    //     update() both resolve as soon as the first /api/ais-live poll answers,
+    //     update() both resolve as soon as the first /api/vessels poll answers,
     //     so the lifecycle settles to `enabled` — but until the server-side socket
     //     delivers a position, firstConnectPhase is 'loading' and getStats()
     //     reports loading: true, lastUpdate: null, count 0, and an UNDEFINED
@@ -53,7 +53,12 @@ export function createQueries({ state: layerState, services, parts, source }) {
       neverAnswered ||
       ['unavailable', 'zoom-in'].includes(stats.status) ||
       Boolean(stats.error && stats.count === 0);
-    return { available: !unavailable, stale: Boolean(stats.stale), stats };
+    return {
+      available: !unavailable,
+      enabled,
+      stale: Boolean(stats.stale),
+      stats,
+    };
   }
 
   function collectSourceStates() {
@@ -147,8 +152,10 @@ export function createQueries({ state: layerState, services, parts, source }) {
    * @param {object} [options]
    * @param {number} [options.radiusM=AWARENESS_RADIUS_M] Window radius.
    * @param {object|null} [options.subject=null] Contact at the centre, excluded.
-   * @returns {{flights: Array, military: Array, aircraft: number}|null} Cohorts
-   *   plus the combined aircraft count, or null without a position.
+   * @returns {{flights: Array, military: Array, aircraft: number,
+   *   completeByLayer: {flights: boolean, military: boolean}}|null} Cohorts,
+   *   their lower-bound completeness, and the combined aircraft count, or
+   *   null without a position.
    */
 
   function collectAircraftProximityWindow(
@@ -156,21 +163,35 @@ export function createQueries({ state: layerState, services, parts, source }) {
     { radiusM = AWARENESS_RADIUS_M, subject = null } = {},
   ) {
     if (!position) return null;
-    const flights = flightsLayer
-      .getNearby(position, radiusM, AWARENESS_QUERY_LIMIT, {
+    // Ask for one usable row beyond the retained limit so a capped cohort is
+    // reported as a lower bound instead of an exact count. The selected
+    // subject can consume one slot before exclusion, hence the extra two.
+    const sampleLimit = AWARENESS_QUERY_LIMIT + 2;
+    const flightSample = flightsLayer
+      .getNearby(position, radiusM, sampleLimit, {
         includeHidden: true,
       })
       .filter(
         (item) => !subject || !isSame(subject, item, 'flights', 'icao24'),
       );
-    const military = militaryFlightsLayer
-      .getNearby(position, radiusM, AWARENESS_QUERY_LIMIT, {
+    const militarySample = militaryFlightsLayer
+      .getNearby(position, radiusM, sampleLimit, {
         includeHidden: true,
       })
       .filter(
         (item) => !subject || !isSame(subject, item, 'military', 'icao24'),
       );
-    return { flights, military, aircraft: flights.length + military.length };
+    const flights = flightSample.slice(0, AWARENESS_QUERY_LIMIT);
+    const military = militarySample.slice(0, AWARENESS_QUERY_LIMIT);
+    return {
+      flights,
+      military,
+      aircraft: flights.length + military.length,
+      completeByLayer: {
+        flights: flightSample.length <= AWARENESS_QUERY_LIMIT,
+        military: militarySample.length <= AWARENESS_QUERY_LIMIT,
+      },
+    };
   }
   return {
     sourceState,

src/layers/awareness/queries.test.mjs

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

src/layers/awareness/subject.js

@@ -53,11 +53,23 @@ export function createSubject({ state: layerState, services, parts, source }) {
     const militaryState = sourceStates.military;
     const vesselsState = sourceStates['ais-live-vessels'];
     const installationsState = sourceStates['military-installations'];
+    const evaluatedAt = Date.now();
+    const retainedProvenance = (id, label, sourceState, fallbackSource) => {
+      const retainedSource = sourceState.stats.source || fallbackSource;
+      return {
+        id,
+        name: label,
+        enabled: sourceState.enabled,
+        source: retainedSource,
+        stats: { ...sourceState.stats, source: retainedSource },
+      };
+    };
     // Same engine the voice analyst calls — see collectAircraftProximityWindow.
-    const { flights, military } = parts.queries.collectAircraftProximityWindow(
+    const aircraftWindow = parts.queries.collectAircraftProximityWindow(
       position,
       { subject },
     );
+    const { flights, military, completeByLayer } = aircraftWindow;
     const vessels = aisLiveVesselsLayer
       .getNearby(position, AWARENESS_RADIUS_M, AWARENESS_QUERY_LIMIT)
       .filter(
@@ -77,31 +89,57 @@ export function createSubject({ state: layerState, services, parts, source }) {
       );
     return {
       subject,
-      evaluatedAt: Date.now(),
+      evaluatedAt,
       radiusM: AWARENESS_RADIUS_M,
       cohorts: [
         {
           id: 'flights',
           label: t('layers.awareness.cohort.flights'),
           source: flightsState.stats.source || SOURCE_LABEL.flights,
+          provenance: retainedProvenance(
+            'flights',
+            'Flights',
+            flightsState,
+            SOURCE_LABEL.flights,
+          ),
           summary: parts.navigation.summarizeAwarenessCohortForNavigation(
             flights,
             flightsState,
+            {
+              navigationLimit: AWARENESS_QUERY_LIMIT,
+              complete: completeByLayer.flights,
+            },
           ),
         },
         {
           id: 'military',
           label: t('layers.awareness.cohort.military'),
           source: militaryState.stats.source || SOURCE_LABEL.military,
+          provenance: retainedProvenance(
+            'military',
+            'Military flights',
+            militaryState,
+            SOURCE_LABEL.military,
+          ),
           summary: parts.navigation.summarizeAwarenessCohortForNavigation(
             military,
             militaryState,
+            {
+              navigationLimit: AWARENESS_QUERY_LIMIT,
+              complete: completeByLayer.military,
+            },
           ),
         },
         {
           id: 'ais-live-vessels',
           label: t('layers.awareness.cohort.vessels'),
           source: vesselsState.stats.source || SOURCE_LABEL['ais-live-vessels'],
+          provenance: retainedProvenance(
+            'ais-live-vessels',
+            'AIS vessels',
+            vesselsState,
+            SOURCE_LABEL['ais-live-vessels'],
+          ),
           summary: parts.navigation.summarizeAwarenessCohortForNavigation(
             vessels,
             vesselsState,
@@ -113,6 +151,12 @@ export function createSubject({ state: layerState, services, parts, source }) {
           source:
             installationsState.stats.source ||
             SOURCE_LABEL['military-installations'],
+          provenance: retainedProvenance(
+            'military-installations',
+            'Mapped installations',
+            installationsState,
+            SOURCE_LABEL['military-installations'],
+          ),
           coverage:
             localizeCoverageLabel(installationsState.stats.coverageLabel) ||
             t('layers.awareness.coverage.viewport'),

src/layers/bikeshare/controls.js

@@ -22,6 +22,39 @@ export function createControls({ state: layerState, services, parts, source }) {
       return parts.queries.collectDetectableStations(options);
     },
 
+    /**
+     * Snapshot loaded bikeshare stations as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, name, city, lat, lon, bikesAvailable, docksAvailable, capacity, renting}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!layerState._enabled) return [];
+      const num = (v) => (Number.isFinite(v) ? v : null);
+      const result = [];
+      for (const record of layerState._stationRenderMap.values()) {
+        if (result.length >= maxCount) break;
+        const info = layerState._stationInfoCache
+          .get(record.cityId)
+          ?.get(record.stationId);
+        if (!Number.isFinite(info?.lat) || !Number.isFinite(info?.lon))
+          continue;
+        result.push({
+          id: record.stationName || `Dock ${record.stationId}`,
+          name: record.stationName || null,
+          city: record.cityId || null,
+          lat: info.lat,
+          lon: info.lon,
+          bikesAvailable: num(record.bikesAvailable),
+          docksAvailable: num(record.docksAvailable),
+          capacity: num(record.capacity),
+          renting: record.isRenting !== false,
+        });
+      }
+      return result;
+    },
+
     /**
      * Return current layer statistics for the UI status display.
      * @returns {{ count: number, lastUpdate: number|null, loading: boolean, loadingLabel?: string, error?: string }}

src/layers/bikeshare/model.js

@@ -1,36 +1,12 @@
+import {
+  extractStationsArray,
+  normalizeGbfsBool,
+  parseStationInformation,
+  parseStationStatus,
+  toNonNegativeInteger,
+} from '../../sources/gbfsStations.js';
+
 export function createModel({ state: layerState, services, parts, source }) {
-  /**
-   * Coerce a GBFS boolean field to a native boolean.
-   * GBFS feeds are inconsistent — some use booleans, others use 0/1 or strings.
-   * @param {*} value - Raw field value from GBFS JSON.
-   * @param {boolean} [fallback=true] - Default when value is null/undefined/unrecognized.
-   * @returns {boolean}
-   */
-
-  function normalizeGbfsBool(value, fallback = true) {
-    if (value == null) return fallback;
-    if (typeof value === 'boolean') return value;
-    const num = Number(value);
-    if (Number.isFinite(num)) return num !== 0;
-    const text = String(value).trim().toLowerCase();
-    if (text === 'true' || text === 'yes') return true;
-    if (text === 'false' || text === 'no') return false;
-    return fallback;
-  }
-
-  /**
-   * Parse a value as a non-negative integer, returning fallback on failure.
-   * @param {*} value - Raw numeric value.
-   * @param {number|null} [fallback=null] - Returned when value is not a valid non-negative number.
-   * @returns {number|null}
-   */
-
-  function toNonNegativeInteger(value, fallback = null) {
-    const n = Number(value);
-    if (!Number.isFinite(n) || n < 0) return fallback;
-    return Math.round(n);
-  }
-
   /**
    * Build a globally unique render key for a station.
    * @param {string} cityId - City identifier.
@@ -63,93 +39,6 @@ export function createModel({ state: layerState, services, parts, source }) {
     return 6371 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
   }
 
-  /**
-   * Extract the stations array from a GBFS JSON payload.
-   * Handles multiple response shapes: { data: { stations: [...] } },
-   * { data: [...] }, and nested objects with a stations sub-key.
-   * @param {Object} payload - Parsed GBFS JSON response.
-   * @returns {Object[]} Array of raw station objects (may be empty).
-   */
-
-  function extractStationsArray(payload) {
-    const data = payload?.data;
-    if (Array.isArray(data?.stations)) return data.stations;
-    if (Array.isArray(data)) return data;
-    // Some feeds nest stations under an additional key (e.g. locale wrappers)
-    if (data && typeof data === 'object') {
-      for (const value of Object.values(data)) {
-        if (Array.isArray(value?.stations)) return value.stations;
-      }
-    }
-    return [];
-  }
-
-  /**
-   * Parse a GBFS station_information payload into a Map of station metadata.
-   * Handles field-name variations across different GBFS providers
-   * (station_id vs id, lat vs latitude, etc.). Stations with missing or
-   * invalid coordinates are silently skipped.
-   * @param {Object} payload - Parsed station_information.json response.
-   * @returns {Map<string, Object>} Map of stationId to station info objects.
-   */
-
-  function parseStationInformation(payload) {
-    const stations = extractStationsArray(payload);
-    const stationMap = new Map();
-
-    for (const raw of stations) {
-      // Accept both GBFS 2.x (station_id) and alternate (id) field names
-      const stationId = String(raw?.station_id ?? raw?.id ?? '').trim();
-      const lat = Number(raw?.lat ?? raw?.latitude);
-      const lon = Number(raw?.lon ?? raw?.longitude);
-      if (!stationId || !Number.isFinite(lat) || !Number.isFinite(lon))
-        continue;
-
-      stationMap.set(stationId, {
-        stationId,
-        name: String(raw?.name || raw?.short_name || '').trim(),
-        lat,
-        lon,
-        capacity: toNonNegativeInteger(raw?.capacity),
-        isInstalled: normalizeGbfsBool(raw?.is_installed, true),
-        isRenting: normalizeGbfsBool(raw?.is_renting, true),
-        isReturning: normalizeGbfsBool(raw?.is_returning, true),
-      });
-    }
-
-    return stationMap;
-  }
-
-  /**
-   * Parse a GBFS station_status payload into a Map of real-time availability.
-   * @param {Object} payload - Parsed station_status.json response.
-   * @returns {Map<string, Object>} Map of stationId to status objects containing
-   *   bikesAvailable, docksAvailable, and operational flags.
-   */
-
-  function parseStationStatus(payload) {
-    const stations = extractStationsArray(payload);
-    const statusMap = new Map();
-
-    for (const raw of stations) {
-      const stationId = String(raw?.station_id ?? raw?.id ?? '').trim();
-      if (!stationId) continue;
-
-      const bikes = toNonNegativeInteger(raw?.num_bikes_available);
-      const docks = toNonNegativeInteger(raw?.num_docks_available);
-      statusMap.set(stationId, {
-        stationId,
-        bikesAvailable: bikes,
-        docksAvailable: docks,
-        isInstalled: normalizeGbfsBool(raw?.is_installed, true),
-        isRenting: normalizeGbfsBool(raw?.is_renting, true),
-        isReturning: normalizeGbfsBool(raw?.is_returning, true),
-        lastReported: toNonNegativeInteger(raw?.last_reported),
-      });
-    }
-
-    return statusMap;
-  }
   return {
     normalizeGbfsBool,
     toNonNegativeInteger,

src/layers/cctv/source.js

@@ -51,5 +51,18 @@ export function createCctvSource({
     },
     getFrameUrl: frameUrlFor,
     getMediaUrl: mediaUrlFor,
+    /** Read one current frame through the registered frame endpoint. */
+    async getFrame(camera, { signal } = {}) {
+      signal?.throwIfAborted();
+      const response = await fetchImpl(frameUrlFor(camera), {
+        cache: 'no-store',
+        signal,
+      });
+      if (!response.ok) throw new Error('Camera frame HTTP ' + response.status);
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      signal?.throwIfAborted();
+      const type = response.headers.get('content-type') || '';
+      return { contentType: type.split(';')[0].trim().toLowerCase(), bytes };
+    },
   };
 }

src/layers/cctv/source.test.mjs

@@ -148,3 +148,28 @@ test('camera construction is inert and destruction cancels a pending catalog and
   assert.equal(a.getStats().count, 0);
   assert.equal(b.getStats().count, 0);
 });
+
+test('frames are read through the registered frame endpoint', async () => {
+  const png = Uint8Array.from([0x89, 0x50, 0x4e, 0x47]);
+  const requested = [];
+  const source = createCctvSource({
+    fetchImpl: async (url, init) => {
+      requested.push({ url, cache: init.cache });
+      return new Response(png, {
+        headers: { 'Content-Type': 'Image/PNG; charset=binary' },
+      });
+    },
+  });
+  const frame = await source.getFrame(camera);
+  assert.equal(frame.contentType, 'image/png');
+  assert.deepEqual([...frame.bytes], [...png]);
+  assert.equal(
+    requested[0].url.split('?')[0],
+    '/api/cctv/frame/pack%2Fcamera%20%3Fx',
+  );
+  assert.equal(requested[0].cache, 'no-store');
+  const failing = createCctvSource({
+    fetchImpl: async () => new Response(null, { status: 502 }),
+  });
+  await assert.rejects(failing.getFrame(camera), /Camera frame HTTP 502/);
+});

src/layers/cyclones/index.js

@@ -403,6 +403,35 @@ export function createCyclonesLayer({
     setRowControlsListener(value) {
       listener = typeof value === 'function' ? value : null;
     },
+    /**
+     * Snapshot loaded active storms as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, name, classification, basin, lat, lon, windKt, pressureHpa}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!enabled || destroyed) return [];
+      const num = (v) => (Number.isFinite(v) ? v : null);
+      const result = [];
+      for (const storm of snapshot?.storms || []) {
+        if (result.length >= maxCount) break;
+        const lat = storm.position?.latitude;
+        const lon = storm.position?.longitude;
+        if (!Number.isFinite(lat) || !Number.isFinite(lon)) continue;
+        result.push({
+          id: storm.name || storm.id,
+          name: storm.name || null,
+          classification: storm.classification || null,
+          basin: storm.basin || null,
+          lat,
+          lon,
+          windKt: num(storm.windKt),
+          pressureHpa: num(storm.pressureHpa),
+        });
+      }
+      return result;
+    },
     getStats() {
       const storm = selected();
       return {

src/layers/directions/index.js

@@ -452,10 +452,7 @@ export function createDirectionsStepOverlayEntry(index, position, copy) {
  * @param {{lat:number, lon:number}} b
  * @returns {string}
  */
-export function directionsRequestUrl(mode, a, b) {
-  const coords = `${a.lon.toFixed(6)},${a.lat.toFixed(6)};${b.lon.toFixed(6)},${b.lat.toFixed(6)}`;
-  return `/api/route?profile=${encodeURIComponent(mode)}&coords=${encodeURIComponent(coords)}&steps=1`;
-}
+export { directionsRequestUrl } from './source.js';
 
 /**
  * Validate a proxy payload into the route record the layer keeps, or null.
@@ -509,10 +506,12 @@ export function normalizeRoutePayload(payload, mode) {
  * route, the markers, the pointer claim or the flight this layer owns. The
  * shared services are injected, which is what keeps this module's own imports
  * down to Cesium and the pure step formatter.
- * @param {{services: object}} options
+ * @param {{services: object, source: {getRoute: Function}}} options
  * @returns {object} The layer module the data manager registers.
  */
-export function createDirectionsLayer({ services }) {
+export function createDirectionsLayer({ services, source }) {
+  if (typeof source?.getRoute !== 'function')
+    throw new TypeError('Directions require a route source');
   /**
    * Where the maneuver card is drawn. Defaults to the shared world-overlay host;
    * tests swap it. Resolved on use, not at import, because the services arrive
@@ -827,18 +826,12 @@ export function createDirectionsLayer({ services }) {
     _error = null;
     notifyRow();
     try {
-      const response = await fetch(directionsRequestUrl(mode, _a, _b), {
-        signal: controller.signal,
-        headers: { Accept: 'application/json' },
-      });
-      const payload = await response.json();
-      if (response.status === 429) {
-        throw new Error(
-          typeof payload?.error === 'string' && payload.error
-            ? `${payload.error} — try again in a moment`
-            : 'Routing is rate limited — try again in a moment',
-        );
-      }
+      const payload = await source.getRoute(
+        { mode, a: _a, b: _b },
+        {
+          signal: controller.signal,
+        },
+      );
       if (seq !== _routeSeq || !_enabled) return;
       const route = normalizeRoutePayload(payload, mode);
       if (!route) {

src/layers/directions/source.js

@@ -0,0 +1,34 @@
+/** Build the existing route-proxy query from geographic endpoints. */
+export function directionsRequestUrl(mode, a, b) {
+  const coords = `${a.lon.toFixed(6)},${a.lat.toFixed(6)};${b.lon.toFixed(6)},${b.lat.toFixed(6)}`;
+  return `/api/route?profile=${encodeURIComponent(mode)}&coords=${encodeURIComponent(coords)}&steps=1`;
+}
+
+/** Acquire route records using caller-owned transport and an optional endpoint. */
+export function createDirectionsSource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  endpoint = '/api/route',
+} = {}) {
+  return {
+    async getRoute({ mode, a, b }, { signal } = {}) {
+      signal?.throwIfAborted();
+      const query = directionsRequestUrl(mode, a, b).split('?')[1];
+      const response = await fetchImpl(`${endpoint}?${query}`, {
+        signal,
+        headers: { Accept: 'application/json' },
+      });
+      const payload = await response.json();
+      signal?.throwIfAborted();
+      if (response.status === 429) {
+        throw new Error(
+          typeof payload?.error === 'string' && payload.error
+            ? `${payload.error} — try again in a moment`
+            : 'Routing is rate limited — try again in a moment',
+        );
+      }
+      if (!response.ok && !payload?.error)
+        throw new Error(`Routing unavailable (HTTP ${response.status})`);
+      return payload;
+    },
+  };
+}

src/layers/directions/source.test.mjs

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

src/layers/firms/model.js

@@ -30,7 +30,8 @@ export function createModel({
    * context-store ids, so the two stay consistent).
    * @param {Object|null|undefined} fire - Internal fire record.
    * @returns {{id: string, lat: number|null, lon: number|null, frp: number|null,
-   *   confidence: number|null, satellite: string|null, acqTime: number|null}}
+   *   confidence: number|null, satellite: string|null, sensor: string|null,
+   *   acqTime: number|null}}
    */
 
   function mapAnalystRecord(fire) {
@@ -46,6 +47,7 @@ export function createModel({
       frp: num(fire?.frp),
       confidence: num(fire?.confidence), // normalized 0..1 (firmsAdapt.normalizeConfidence)
       satellite: text(fire?.satellite) || text(fire?.sensor),
+      sensor: text(fire?.sensor), // VIIRS or MODIS
       acqTime:
         Number.isFinite(fire?.acqMs) && fire.acqMs > 0 ? fire.acqMs : null, // epoch ms; 0 = unparseable → null
     };

src/layers/flights/snapshotRenderer.js

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

src/layers/installations/controls.js

@@ -209,6 +209,35 @@ export function createControls({ state: layerState, services, parts, source }) {
       return true;
     },
 
+    /**
+     * Snapshot loaded mapped installations as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, name, class, kind, lat, lon}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!layerState.enabled) return [];
+      const result = [];
+      for (const record of layerState.records || []) {
+        if (result.length >= maxCount) break;
+        if (
+          !Number.isFinite(record.latitude) ||
+          !Number.isFinite(record.longitude)
+        )
+          continue;
+        result.push({
+          id: record.name || record.id,
+          name: record.name || null,
+          class: record.class || null,
+          kind: record.kind || null,
+          lat: record.latitude,
+          lon: record.longitude,
+        });
+      }
+      return result;
+    },
+
     getStats() {
       const namedMarkers = parts.namedMarkers?.stats();
       const subjectWindow =

src/layers/installations/namesLoading.test.mjs

@@ -4,22 +4,47 @@ import { readFileSync } from 'node:fs';
 import { createInstallationSource } from './source.js';
 import { createIngestion } from './ingestion.js';
 import { decodeOpenFreeMapMilitaryTile } from '../../sources/openFreeMap.js';
-import { createMilitaryNamesLoader, loadMilitaryNames } from '../../data/militaryNames.js';
+import {
+  createMilitaryNamesLoader,
+  loadMilitaryNames,
+} from '../../data/militaryNames.js';
 import { loadBundledJson } from '../../data/bundledJson.js';
 
 const box = { south: 30.3, west: -97.8, north: 30.33, east: -97.74 };
 const wide = { south: 20, west: -130, north: 60, east: -60 };
-const tile = decodeOpenFreeMapMilitaryTile(readFileSync(new URL('../../data/fixtures/ofm-camp-mabry-12-935-1685.pbf', import.meta.url)), 12, 935, 1685);
-const flush = async () => { for (let i = 0; i < 30; i++) await Promise.resolve(); };
-function deferred() { let resolve; const promise = new Promise((r) => { resolve = r; }); return { promise, resolve }; }
-function sourceWith(job) { return createInstallationSource({
-  loadNames: () => job.promise,
-  fetchImpl: async () => Response.json({ unavailable: true }),
-  mapTiles: { fetchBounds: async () => ({ tiles: [tile] }), clear() {} },
-}); }
+const tile = decodeOpenFreeMapMilitaryTile(
+  readFileSync(
+    new URL(
+      '../../data/fixtures/ofm-camp-mabry-12-935-1685.pbf',
+      import.meta.url,
+    ),
+  ),
+  12,
+  935,
+  1685,
+);
+const flush = async () => {
+  for (let i = 0; i < 30; i++) await Promise.resolve();
+};
+function deferred() {
+  let resolve;
+  const promise = new Promise((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+function sourceWith(job) {
+  return createInstallationSource({
+    loadNames: () => job.promise,
+    fetchImpl: async () => Response.json({ unavailable: true }),
+    mapTiles: { fetchBounds: async () => ({ tiles: [tile] }), clear() {} },
+  });
+}
 
 test('close polygons publish immediately while a wide consumer can cancel its independent names wait', async () => {
-  const job = deferred(), source = sourceWith(job), abort = new AbortController();
+  const job = deferred(),
+    source = sourceWith(job),
+    abort = new AbortController();
   const waiting = source.getMappedSites(wide, { signal: abort.signal });
   const rejection = assert.rejects(waiting, { name: 'AbortError' });
   const payload = await source.getMappedSites(box);
@@ -32,48 +57,81 @@ test('close polygons publish immediately while a wide consumer can cancel its in
   assert.ok(enriched.records.some((r) => r.name === 'Camp Mabry'));
 });
 
-for (const stale of [false, true]) test(`late names ${stale ? 'cannot publish to a superseded view' : 'enrich the current published polygons'}`, async () => {
-  const job = deferred(), source = sourceWith(job), publications = [];
-  let currentBox = box;
-  const state = { enabled: true, viewer: {}, records: [], googleSearchRequested: false };
-  const ingestion = createIngestion({ state, source,
-    services: { render: { governorRequestRender() {} }, ground: { resolveGroundFloorCellsBounded: async () => {} } },
-    parts: {
-      viewport: { loadArea: () => ({ box: currentBox, coverage: {} }), clearUnavailableRetry() {}, scheduleUnavailableRetry() {} },
-      model: { installationWithinViewport: () => true },
-      rendering: { renderRecords: () => publications.push(state.records), warmInstallationFloors() {} },
-    },
+for (const stale of [false, true])
+  test(`late names ${stale ? 'cannot publish to a superseded view' : 'enrich the current published polygons'}`, async () => {
+    const job = deferred(),
+      source = sourceWith(job),
+      publications = [];
+    let currentBox = box;
+    const state = {
+      enabled: true,
+      viewer: {},
+      records: [],
+      googleSearchRequested: false,
+    };
+    const ingestion = createIngestion({
+      state,
+      source,
+      services: {
+        render: { governorRequestRender() {} },
+        ground: { resolveGroundFloorCellsBounded: async () => {} },
+      },
+      parts: {
+        viewport: {
+          loadArea: () => ({ box: currentBox, coverage: {} }),
+          clearUnavailableRetry() {},
+          scheduleUnavailableRetry() {},
+        },
+        model: { installationWithinViewport: () => true },
+        rendering: {
+          renderRecords: () => publications.push(state.records),
+          warmInstallationFloors() {},
+        },
+      },
+    });
+    await ingestion.loadInstallations();
+    assert.equal(state.loading, false);
+    assert.ok(publications[0].length);
+    if (stale) {
+      currentBox = wide;
+      state.enabled = false;
+      state.abort.abort();
+    }
+    job.resolve(await loadMilitaryNames());
+    await flush();
+    assert.equal(publications.length, stale ? 1 : 2);
+    if (!stale) assert.ok(state.records.some((r) => r.name === 'Camp Mabry'));
+    state.abort.abort();
   });
-  await ingestion.loadInstallations();
-  assert.equal(state.loading, false);
-  assert.ok(publications[0].length);
-  if (stale) { currentBox = wide; state.enabled = false; state.abort.abort(); }
-  job.resolve(await loadMilitaryNames());
-  await flush();
-  assert.equal(publications.length, stale ? 1 : 2);
-  if (!stale) assert.ok(state.records.some((r) => r.name === 'Camp Mabry'));
-  state.abort.abort();
-});
 
-for (const stage of ['response', 'body']) test(`shared names ${stage} deadline aborts and releases the retryable loader`, async (t) => {
-  t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
-  let calls = 0, signal;
-  t.mock.method(globalThis, 'fetch', async (_url, options) => {
-    calls++; signal = options.signal;
-    if (calls > 1) return Response.json({ records: [], classes: [] });
-    if (stage === 'response') return new Promise(() => {});
-    return { ok: true, json: () => new Promise(() => {}) };
+for (const stage of ['response', 'body'])
+  test(`shared names ${stage} deadline aborts and releases the retryable loader`, async (t) => {
+    t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
+    let calls = 0,
+      signal;
+    t.mock.method(globalThis, 'fetch', async (_url, options) => {
+      calls++;
+      signal = options.signal;
+      if (calls > 1) return Response.json({ records: [], classes: [] });
+      if (stage === 'response') return new Promise(() => {});
+      return { ok: true, json: () => new Promise(() => {}) };
+    });
+    const load = createMilitaryNamesLoader({
+      timeoutMs: 50,
+      cooldownMs: 100,
+      loadPack: (signal) =>
+        loadBundledJson(new URL('https://example.test/names.json'), { signal }),
+    });
+    const first = load();
+    assert.equal(load(), first, 'shared acquisition');
+    const rejected = assert.rejects(first, { name: 'TimeoutError' });
+    await flush();
+    t.mock.timers.tick(51);
+    await rejected;
+    assert.equal(signal.aborted, true);
+    await assert.rejects(load(), { name: 'TimeoutError' });
+    assert.equal(calls, 1);
+    t.mock.timers.tick(101);
+    assert.deepEqual((await load()).records, []);
+    assert.equal(calls, 2);
   });
-  const load = createMilitaryNamesLoader({ timeoutMs: 50, cooldownMs: 100,
-    loadPack: (signal) => loadBundledJson(new URL('https://example.test/names.json'), null, { signal }) });
-  const first = load();
-  assert.equal(load(), first, 'shared acquisition');
-  const rejected = assert.rejects(first, { name: 'TimeoutError' });
-  await flush(); t.mock.timers.tick(51); await rejected;
-  assert.equal(signal.aborted, true);
-  await assert.rejects(load(), { name: 'TimeoutError' });
-  assert.equal(calls, 1);
-  t.mock.timers.tick(101);
-  assert.deepEqual((await load()).records, []);
-  assert.equal(calls, 2);
-});

src/layers/installations/source.js

@@ -101,7 +101,7 @@ export function createInstallationSource({
 } = {}) {
   let overpassUnavailable = false;
   const installationIds = new Map();
-  async function getNamedSites(box, signal) {
+  async function getNamedSites(box, signal, thinned = true) {
     const names = await waitForSignal(loadNames(), signal).catch((cause) => {
       signal?.throwIfAborted();
       throw Object.assign(
@@ -112,7 +112,13 @@ export function createInstallationSource({
       );
     });
     signal?.throwIfAborted();
-    const { records, count } = militaryNamesInView(names, box);
+    // The map keeps one site per display cell; queries can ask for all.
+    const { records, count } = militaryNamesInView(
+      names,
+      box,
+      thinned ? undefined : Infinity,
+      thinned,
+    );
     return {
       records,
       namedInView: count,
@@ -124,9 +130,9 @@ export function createInstallationSource({
       source: 'OpenStreetMap',
     };
   }
-  async function getTileSites(box, signal) {
+  async function getTileSites(box, signal, thinned) {
     const zoom = installationTileZoom(box);
-    if (zoom === null) return getNamedSites(box, signal);
+    if (zoom === null) return getNamedSites(box, signal, thinned);
     let names = null;
     const namesJob = waitForSignal(loadNames(), signal)
       .then((loaded) => {
@@ -181,7 +187,7 @@ export function createInstallationSource({
       mapTiles.clear();
       installationIds.clear();
     },
-    async getMappedSites(box, { exact = false, signal } = {}) {
+    async getMappedSites(box, { exact = false, thinned = true, signal } = {}) {
       const { south, west, north, east } = box || {};
       if (
         ![south, west, north, east].every(Number.isFinite) ||
@@ -197,8 +203,8 @@ export function createInstallationSource({
         throw new TypeError('A bounded installation viewport is required');
       signal?.throwIfAborted();
       if (east < west || north - south > 10 || east - west > 10)
-        return getNamedSites(box, signal);
-      if (overpassUnavailable) return getTileSites(box, signal);
+        return getNamedSites(box, signal, thinned);
+      if (overpassUnavailable) return getTileSites(box, signal, thinned);
       const query = new URLSearchParams(
         Object.entries({ south, west, north, east }).map(([key, value]) => [
           key,
@@ -213,7 +219,7 @@ export function createInstallationSource({
       signal?.throwIfAborted();
       if (isUnavailableCapability(body)) {
         overpassUnavailable = true;
-        return getTileSites(box, signal);
+        return getTileSites(box, signal, thinned);
       }
       if (!response.ok)
         throw Object.assign(

src/layers/launches/controls.js

@@ -17,6 +17,40 @@ export function createControls({ state: layerState, services, parts, source }) {
       parts.selection.stopMissionZoomAnchor();
     },
 
+    /**
+     * Snapshot loaded launches as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, name, provider, status, launchSite, missionName, lat, lon, launchTimeMs, hoursUntil}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!layerState._enabled) return [];
+      const now = Date.now();
+      const text = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+      const result = [];
+      for (const launch of layerState._launches || []) {
+        if (result.length >= maxCount) break;
+        const at = Date.parse(launch.launchTime);
+        result.push({
+          id: launch.id,
+          name: text(launch.name),
+          provider: text(launch.provider),
+          status: text(launch.status),
+          launchSite: text(launch.launchSite),
+          missionName: text(launch.missionName),
+          lat: launch.lat,
+          lon: launch.lon,
+          launchTimeMs: Number.isFinite(at) ? at : null,
+          // Negative for launches already flown.
+          hoursUntil: Number.isFinite(at)
+            ? Math.round(((at - now) / 3_600_000) * 10) / 10
+            : null,
+        });
+      }
+      return result;
+    },
+
     getStats() {
       return {
         count: layerState._count,

src/layers/launches/source.js

@@ -2,16 +2,24 @@
 export function createLaunchSource({
   fetchImpl = (...args) => globalThis.fetch(...args),
 } = {}) {
+  /** The launch payload, and whether the proxy served it from a stale cache. */
+  async function getLaunchSnapshot({ signal } = {}) {
+    signal?.throwIfAborted();
+    const response = await fetchImpl('/api/launches', { signal });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const payload = await response.json();
+    signal?.throwIfAborted();
+    if (!Array.isArray(payload) && !Array.isArray(payload?.results))
+      throw new Error('Malformed launch snapshot');
+    return {
+      payload,
+      stale: response.headers?.get?.('x-gev-cache') === 'STALE-ERROR',
+    };
+  }
   return {
-    async getLaunches({ signal } = {}) {
-      signal?.throwIfAborted();
-      const response = await fetchImpl('/api/launches', { signal });
-      if (!response.ok) throw new Error(`HTTP ${response.status}`);
-      const payload = await response.json();
-      signal?.throwIfAborted();
-      if (!Array.isArray(payload) && !Array.isArray(payload?.results))
-        throw new Error('Malformed launch snapshot');
-      return payload;
+    getLaunchSnapshot,
+    async getLaunches(options) {
+      return (await getLaunchSnapshot(options)).payload;
     },
     async getActiveTle({ signal } = {}) {
       signal?.throwIfAborted();

src/layers/localAdsb/index.js

@@ -828,6 +828,40 @@ export function createLocalAdsbLayer({
       return enabled && selectMarker(`${ENTITY_PREFIX}${icao}`);
     },
 
+    /**
+     * Snapshot loaded locally received aircraft as plain JSON-safe records for the analyst
+     * query engine. On demand only (once per spoken query); [] while the
+     * layer is off.
+     * @param {number} [maxCount=Infinity] Most records to return.
+     * @returns {Array<Object>} {id, icao24, callsign, lat, lon, altitudeM, speedKts, heading, onGround}.
+     */
+    getAnalystRecords(maxCount = Infinity) {
+      if (!enabled) return [];
+      const num = (v) => (Number.isFinite(v) ? v : null);
+      const result = [];
+      for (const marker of markers.values()) {
+        if (result.length >= maxCount) break;
+        const record = marker.record || {};
+        const lat = marker.lat ?? record.lat;
+        const lon = marker.lon ?? record.lon;
+        if (!Number.isFinite(lat) || !Number.isFinite(lon)) continue;
+        result.push({
+          id: record.callsign || record.icao,
+          icao24: record.icao || null,
+          callsign: record.callsign || null,
+          lat,
+          lon,
+          altitudeM: Number.isFinite(record.altitudeFt)
+            ? Math.round(record.altitudeFt * 0.3048)
+            : null,
+          speedKts: num(record.groundSpeedKt),
+          heading: num(record.trackDeg),
+          onGround: record.onGround === true,
+        });
+      }
+      return result;
+    },
+
     getAllPositions(maxCount = 500) {
       return positionRows(maxCount);
     },

src/layers/military/index.js

@@ -33,6 +33,7 @@ export function createMilitaryFlightLayer({
     militaryRegistry: services.militaryRegistry,
     rendering: parts.rendering,
     tracking: parts.tracking,
+    motion: parts.motion,
     queries: parts.queries,
   });
   parts.ingestion = createIngestion({

src/layers/military/ownership.test.mjs

@@ -113,3 +113,101 @@ test('a normalized source can retain its stale reason without changing standalon
   assert.equal(layer.getStats().error, null);
   assert.equal(layer.getStats().stale, true);
 });
+
+test('a newly seen military contact appears at its delayed position, not ahead of it', async () => {
+  // The military fleet renders RENDER_DELAY_SEC behind real time, so a fresh
+  // contact's first displayed position is its fix projected back to that
+  // delayed time. Creating the billboard at the raw fix drew it ahead until
+  // the next fleet tick jumped it back.
+  const Cesium = await import('cesium');
+  const { RENDER_DELAY_SEC } = await import('./policy.js');
+  // The application's own scene services, as src/app/layers/militaryFlights.js
+  // composes them; only the surface samplers and registry are stubbed.
+  const supplied = {
+    picking: await import('../../data/pickRegistry.js'),
+    sprites: await import('../../data/spriteOrder.js'),
+    trails: await import('../../data/trailRenderer.js'),
+    aircraftPresentation: await import('../../data/tr3bRegistry.js'),
+    camera: await import('../../data/trackedCamera.js'),
+    labels: await import('../../data/detectionDraw.js'),
+    geoid: await import('../../data/geoid.js'),
+    focus: await import('../../data/focusDeemphasis.js'),
+    readout: await import('../../data/trackedReadout.js'),
+    context: await import('../../data/contextStore.js'),
+    render: await import('../../renderGovernor.js'),
+    recession: await import('../../data/aircraftRecession.js'),
+    groundFloor: await import('../../data/groundFloor.js'),
+    groundSnap: await import('../../data/groundSnap.js'),
+    meshFloor: { sampleMeshFloorCells: () => {} },
+    militaryRegistry: { registerMilitaryIcaos: () => {} },
+  };
+  const fixLon = -97.6;
+  const fixLat = 30.3;
+  const speedMps = 200;
+  const fixAgeMs = 2_000;
+  const nowMs = Date.now();
+  const layer = createMilitaryFlightLayer({
+    services: supplied,
+    source: {
+      label: 'Fixture aircraft',
+      async getSnapshot() {
+        return {
+          source: 'Fixture aircraft',
+          complete: true,
+          observedAtMs: nowMs,
+          records: [
+            {
+              id: 'ae0001',
+              latitude: fixLat,
+              longitude: fixLon,
+              onGround: false,
+              baroAltitudeM: 9_000,
+              courseDeg: 90,
+              speedMps,
+              positionTimeMs: nowMs - fixAgeMs,
+              contactTimeMs: nowMs - fixAgeMs,
+            },
+          ],
+        };
+      },
+    },
+  });
+  const added = [];
+  layer.testing._setTrackedMilitaryRefreshStateForTest({
+    icao24: 'seed00',
+    entity: null,
+    meta: { rawLat: 0, rawLon: 0, onGround: false },
+    billboard: {
+      show: false,
+      position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
+    },
+    billboardCollection: {
+      show: false,
+      add(options) {
+        const billboard = { ...options };
+        added.push(billboard);
+        return billboard;
+      },
+      remove() {},
+    },
+    viewer: { camera: { positionCartographic: null }, scene: {} },
+    tracked: false,
+  });
+  await layer.update({ camera: { positionCartographic: null }, scene: {} });
+  const billboard = added.find((entry) => entry.id === 'ae0001');
+  assert.ok(billboard, 'the new contact gets a billboard');
+  const shown = Cesium.Cartographic.fromCartesian(billboard.position);
+  const behindM = Cesium.Cartesian3.distance(
+    Cesium.Cartesian3.fromRadians(shown.longitude, shown.latitude, 0),
+    Cesium.Cartesian3.fromDegrees(fixLon, fixLat, 0),
+  );
+  const expectedM = speedMps * (RENDER_DELAY_SEC - fixAgeMs / 1000);
+  assert.ok(
+    Cesium.Math.toDegrees(shown.longitude) < fixLon,
+    'drawn behind the fix',
+  );
+  assert.ok(
+    Math.abs(behindM - expectedM) < speedMps * 3,
+    `expected about ${Math.round(expectedM)} m behind the fix, got ${Math.round(behindM)} m`,
+  );
+});

src/layers/military/snapshotRenderer.js

@@ -23,6 +23,7 @@ export function createMilitarySnapshotRenderer({
   militaryRegistry,
   rendering,
   tracking,
+  motion,
   queries,
 }) {
   const { warmGroundFloor, cachedGroundFloor, GROUND_FLOOR_LIFT_M } =
@@ -142,8 +143,14 @@ export function createMilitarySnapshotRenderer({
         // Round 5: depth policy is uniform (always depth-test-free, see
         // _groundDepthDistance) — nothing to flip on landing/takeoff.
       } else {
+        // Start where the fleet pass will draw it: the fleet renders behind
+        // real time, so a fresh contact's displayed position is its fix
+        // projected back to that delayed time. Creating it at the raw fix drew
+        // it ahead until the next fleet tick snapped it back.
+        const displayed =
+          motion._deadReckon(icao24, new Cesium.Cartesian3()) || position;
         const bb = flightState._billboardCollection.add({
-          position,
+          position: displayed,
           image: aircraftIcon(rendering._iconKind(icao24, meta.klass)),
           width: isTracked ? 24 : 20,
           height: isTracked ? 24 : 20,

src/layers/recentImagery/rendering.js

@@ -70,6 +70,8 @@ function admitTileRequests(provider, admission, requestRender, retry) {
  */
 export function createRecentImageryRenderer({
   cesium = Cesium,
+  tileTemplate = gibsTemplate,
+  credit = 'NASA GIBS',
   maxTileRequests = 6,
   requestRender = () => {},
   setTimeoutImpl = (fn, ms) => globalThis.setTimeout(fn, ms),
@@ -101,7 +103,7 @@ export function createRecentImageryRenderer({
   function createProvider(candidate, box) {
     const spec = PRODUCTS[candidate.product];
     const provider = new cesium.UrlTemplateImageryProvider({
-      url: gibsTemplate(candidate.product, candidate.day),
+      url: tileTemplate(candidate.product, candidate.day),
       subdomains: ['a', 'b', 'c'],
       minimumLevel: 0,
       maximumLevel: spec.maxLevel,
@@ -112,7 +114,7 @@ export function createRecentImageryRenderer({
         box.east,
         box.north,
       ),
-      credit: 'NASA GIBS',
+      credit,
       hasAlphaChannel: spec.format === 'png',
     });
     return admitTileRequests(provider, admission, requestRender, retry);

src/layers/recentImagery/rendering.test.mjs

@@ -53,10 +53,11 @@ const S30 = { key: 'S30:2026-09-18', product: 'S30', day: '2026-09-18' };
 const L30 = { key: 'L30:2026-09-16', product: 'L30', day: '2026-09-16' };
 const VIIRS = { key: 'VIIRS:2026-09-20', product: 'VIIRS', day: '2026-09-20' };
 
-function fixture({ requestImage, maxTileRequests } = {}) {
+function fixture({ requestImage, maxTileRequests, ...options } = {}) {
   const renders = [];
   const timers = manualTimers();
   const renderer = createRecentImageryRenderer({
+    ...options,
     cesium: fakeCesium(requestImage),
     maxTileRequests,
     requestRender: (reason) => renders.push(reason),
@@ -208,3 +209,21 @@ test('against the basemap slot a splits left with no second layer, and leaving t
   assert.equal(layer.splitDirection, 0);
   assert.deepEqual(renders, ['recent-imagery-show', 'recent-imagery-look']);
 });
+
+test('replacement imagery uses source-owned tile URLs and credit and tears down normally', () => {
+  const { renderer, globe } = fixture({
+    tileTemplate: (product, day) =>
+      `https://tiles.example/${product}/${day}/{z}/{x}/{y}`,
+    credit: 'Example imagery',
+  });
+  assert.equal(renderer.showSlot('a', S30, BOX), true);
+  const layer = globe.layers[0];
+  assert.equal(
+    layer.provider.options.url,
+    'https://tiles.example/S30/2026-09-18/{z}/{x}/{y}',
+  );
+  assert.equal(layer.provider.options.credit, 'Example imagery');
+  renderer.destroy();
+  assert.equal(globe.layers.length, 0);
+  assert.equal(layer.destroyed, true);
+});

src/layers/recentImagery/source.js

@@ -0,0 +1,32 @@
+import { searchHls } from './catalog.js';
+import { gibsTemplate, wvsSnapshotUrl } from './model.js';
+
+/** NASA-compatible imagery acquisition; transport and URL builders are replaceable. */
+export function createRecentImagerySource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  search = searchHls,
+  thumbnailUrl = wvsSnapshotUrl,
+  tileTemplate = gibsTemplate,
+  credit = 'NASA GIBS',
+} = {}) {
+  return {
+    credit,
+    searchHls: (query) => search({ ...query, fetchImpl }),
+    async getThumbnail(candidate, box, { size = 256, signal } = {}) {
+      signal?.throwIfAborted();
+      const response = await fetchImpl(
+        thumbnailUrl({
+          product: candidate.product,
+          day: candidate.day,
+          box,
+          width: size,
+          height: size,
+        }),
+        { signal },
+      );
+      signal?.throwIfAborted();
+      return response;
+    },
+    getTileTemplate: (product, day) => tileTemplate(product, day),
+  };
+}

src/layers/recentImagery/source.test.mjs

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createRecentImagerySource } from './source.js';
+
+test('imagery source routes catalog, thumbnails and tiles through supplied adapters', async () => {
+  const controller = new AbortController();
+  const query = { box: { west: 0, east: 1, south: 0, north: 1 }, signal: controller.signal };
+  const candidate = { product: 'S30', day: '2026-10-01' };
+  const calls = [];
+  const fetchImpl = async (...args) => { calls.push(args); return new Response('image'); };
+  const source = createRecentImagerySource({
+    fetchImpl,
+    search: async (request) => {
+      assert.equal(request.fetchImpl, fetchImpl);
+      assert.equal(request.signal, controller.signal);
+      assert.equal(request.box, query.box);
+      return [candidate];
+    },
+    thumbnailUrl: ({ product, day, width }) => `https://imagery.example/${product}/${day}/${width}`,
+    tileTemplate: (product, day) => `https://tiles.example/${product}/${day}/{z}/{x}/{y}`,
+    credit: 'Example imagery',
+  });
+  assert.deepEqual(await source.searchHls(query), [candidate]);
+  assert.equal(await (await source.getThumbnail(candidate, query.box, { signal: controller.signal })).text(), 'image');
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0][0], 'https://imagery.example/S30/2026-10-01/256');
+  assert.equal(calls[0][1].signal, controller.signal);
+  assert.equal(source.getTileTemplate(candidate.product, candidate.day), 'https://tiles.example/S30/2026-10-01/{z}/{x}/{y}');
+  assert.equal(source.credit, 'Example imagery');
+});
+
+test('cancelled thumbnail acquisition does not return stale responses or retry', async () => {
+  const controller = new AbortController();
+  let calls = 0;
+  const source = createRecentImagerySource({
+    thumbnailUrl: () => 'https://imagery.example/thumbnail',
+    fetchImpl: async () => { calls++; controller.abort(); return new Response('image'); },
+  });
+  await assert.rejects(source.getThumbnail({}, {}, { signal: controller.signal }), { name: 'AbortError' });
+  await assert.rejects(source.getThumbnail({}, {}, { signal: controller.signal }), { name: 'AbortError' });
+  assert.equal(calls, 1);
+});