Merge main into prereq-10-osm-overlays and port Open Map Overlays

Main moved on since this PR opened; the overlay layer is ported to the
current contracts:

- Layer-state token 6 (j belongs to transit; new single-character
  tokens are digits) with a reservation-ledger row, and the option owner
  renamed to the layer id so the compact share codec can encode it.
- Constructed per catalog by createOsmOverlaysLayer() in
  constructCatalog.js; src/standalone/data.js no longer registers layers.
- Drapes through maps/imageryHost.js, so the overlays show on Google 3D
  (tileset imagery) as well as the globe stacks, and follow map-stack
  switches. Imagery layers are created on enable and destroyed on
  disable/destroy.
- Translated chip labels and layer name in every locale, LAYER_NAME_KEYS,
  Infrastructure panel group, voice manifest entry.
- Attribution: OpenSeaMap tiles CC BY-SA 2.0, OpenSnowMap credit as
  required, OSM ODbL credit for both; bulk-download note in DATA_SOURCES.
- CURRENT-STATE row, changelog fragment, share-codec absent defaults,
  updated token-ledger fixtures and voice schema pins.

src/agent/worldPacket.js

@@ -0,0 +1,170 @@
+import * as Cesium from 'cesium';
+import {
+  feedProvenanceEnvelope,
+  layerSnapshot,
+  layerSnapshots,
+} from '../data/layerSnapshot.js';
+import { contextModeWord } from '../contextModePolicy.js';
+
+export const TRACKABLE_FAMILIES = Object.freeze([
+  { layerId: 'flights', kind: 'aircraft' },
+  { layerId: 'military', kind: 'aircraft' },
+  { layerId: 'ais-live-vessels', kind: 'vessel' },
+  { layerId: 'satellites', kind: 'satellite' },
+]);
+
+const CONTEXT_MODE_RESULT_FIELDS = Object.freeze([
+  { field: 'mode', emptyAs: 'off' },
+  { field: 'entering', emptyAs: null },
+  { field: 'priorMode', emptyAs: null },
+]);
+
+const NESTED_CONTEXT_RESULT_FIELDS = Object.freeze([
+  'context',
+  'contextRollback',
+]);
+
+/**
+ * Translate context-mode payloads into the public tool vocabulary while
+ * retaining the internal id beside each translated field.
+ */
+export function withContextModeVocabulary(state) {
+  if (!state || typeof state !== 'object') return state;
+  let out = state;
+  const mutable = () => {
+    if (out === state) out = { ...state };
+    return out;
+  };
+  for (const { field, emptyAs } of CONTEXT_MODE_RESULT_FIELDS) {
+    if (!(field in state)) continue;
+    const internal = state[field] ?? null;
+    const target = mutable();
+    target[field] = contextModeWord(internal, { emptyAs });
+    target[`${field}Internal`] = internal;
+  }
+  for (const field of NESTED_CONTEXT_RESULT_FIELDS) {
+    const nested = state[field];
+    if (!nested || typeof nested !== 'object') continue;
+    const translated = withContextModeVocabulary(nested);
+    if (translated !== nested) mutable()[field] = translated;
+  }
+  return out;
+}
+
+/** Read tracked entities from their canonical layer owners. */
+export function collectTrackedEntities(dataManager) {
+  const tracked = [];
+  for (const family of TRACKABLE_FAMILIES) {
+    const module = dataManager?.layers?.get(family.layerId)?.module;
+    if (!module) continue;
+    try {
+      const info =
+        family.kind === 'vessel'
+          ? module.getSelectedInfo?.()
+          : module.getTrackedInfo?.();
+      if (info)
+        tracked.push({
+          kind: family.kind,
+          layerId: family.layerId,
+          ...info,
+        });
+    } catch {
+      // A not-yet-ready layer contributes no tracked observation.
+    }
+  }
+  return tracked;
+}
+
+/** Read the active Contacts window from its owning awareness layer. */
+export function activeContactsWindow(dataManager) {
+  try {
+    const layer = dataManager?.layers?.get('military-awareness')?.module;
+    return (
+      layer?.contactsWindowFromSnapshot?.(layer.getContextSnapshot?.()) ?? null
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the model-free fast World Packet from existing application owners.
+ *
+ * This performs no network requests and intentionally mirrors the historical
+ * get_current_view_state payload so voice can delegate without behavior drift.
+ */
+export function getWorldPacket(options = {}) {
+  const {
+    viewer,
+    styleManager,
+    dataManager,
+    sceneDirector = null,
+    now: requestedNow,
+  } = options ?? {};
+  // A default parameter only covers undefined; null or NaN would age every
+  // feed against the epoch and report stale data as "just now".
+  const now = Number.isFinite(requestedNow) ? requestedNow : Date.now();
+  if (!viewer?.camera?.positionWC)
+    throw new TypeError('World Packet requires a viewer camera');
+  if (!dataManager || typeof dataManager.getAll !== 'function')
+    throw new TypeError('World Packet requires a data manager');
+
+  const cartographic = Cesium.Cartographic.fromCartesian(
+    viewer.camera.positionWC,
+  );
+  // Read the roster once. Voice must not rewalk disabled layers: preserving the
+  // current enabled-only view keeps the model's context budget bounded.
+  const rows = dataManager.getAll();
+  const enabledRows = rows.filter((layer) => layer.enabled);
+  const contactsWindow = activeContactsWindow(dataManager);
+  const contextState =
+    typeof styleManager?.getContextModeState === 'function'
+      ? withContextModeVocabulary(styleManager.getContextModeState())
+      : null;
+
+  return {
+    ok: true,
+    action: 'get_current_view_state',
+    camera: {
+      latitude: Cesium.Math.toDegrees(cartographic.latitude),
+      longitude: Cesium.Math.toDegrees(cartographic.longitude),
+      heightM: cartographic.height,
+    },
+    style: styleManager?.activeStyle || 'normal',
+    context: contextState
+      ? {
+          ...contextState,
+          ...(contactsWindow ? { contactsWindow } : {}),
+        }
+      : null,
+    cockpit:
+      typeof styleManager?.getCockpitState === 'function'
+        ? styleManager.getCockpitState()
+        : null,
+    controls:
+      typeof styleManager?.getControlState === 'function'
+        ? styleManager.getControlState()
+        : null,
+    scenePlayback: sceneDirector?.getPlaybackStatus?.() || null,
+    tracked: collectTrackedEntities(dataManager),
+    disabledLayerCount: rows.length - enabledRows.length,
+    // Preserve get_current_view_state's existing compact enabled-only shape.
+    layers: enabledRows.map((layer) => {
+      const snapshot = layerSnapshot(layer, { now });
+      return {
+        id: layer.id,
+        name: layer.name,
+        enabled: layer.enabled,
+        count: layer.stats?.count || 0,
+        error: layer.stats?.error || null,
+        feedState: snapshot.feedState,
+        source: snapshot.source,
+        lastUpdate: snapshot.lastUpdate,
+      };
+    }),
+    feedProvenance: feedProvenanceEnvelope(
+      layerSnapshots(rows, { now }).filter((layer) => layer.enabled),
+      { now },
+    ),
+  };
+}

src/agent/worldPacket.test.mjs

@@ -0,0 +1,335 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+
+import { getWorldPacket } from './worldPacket.js';
+import { createGevActionRunner } from '../voice/gevActions.js';
+
+function withoutVoicePresentation(result) {
+  const packet = { ...result };
+  delete packet.say;
+  delete packet.display;
+  delete packet.schedule;
+  return packet;
+}
+
+function harness() {
+  const position = Cesium.Cartesian3.fromDegrees(-97.74, 30.26, 500);
+  const viewer = {
+    trackedEntity: undefined,
+    clock: { onTick: { addEventListener: () => () => {} } },
+    scene: {
+      canvas: {
+        clientWidth: 1200,
+        clientHeight: 800,
+        addEventListener() {},
+        removeEventListener() {},
+      },
+      globe: { getHeight: () => 0 },
+      tweens: [],
+    },
+    camera: {
+      positionWC: position,
+      positionCartographic: Cesium.Cartographic.fromCartesian(position),
+      heading: 0,
+      pitch: Cesium.Math.toRadians(-45),
+      moveEnd: { addEventListener: () => () => {} },
+      cancelFlight() {},
+      lookAtTransform() {},
+    },
+  };
+  const rows = [
+    {
+      id: 'traffic',
+      name: 'Traffic',
+      enabled: true,
+      stats: {
+        count: 3,
+        source: 'fixture',
+        lastUpdate: null,
+      },
+    },
+  ];
+  const dataManager = {
+    layers: new Map([['traffic', { module: null }]]),
+    getAll: () => rows,
+  };
+  const styleManager = {
+    activeStyle: 'normal',
+    getContextModeState: () => ({ mode: 'flights' }),
+    getCockpitState: () => null,
+    getControlState: () => ({ hud: { visible: 'auto' } }),
+  };
+  return { viewer, dataManager, styleManager };
+}
+
+test('World Packet preserves get_current_view_state parity', async () => {
+  const { viewer, dataManager, styleManager } = harness();
+  const packet = getWorldPacket({ viewer, dataManager, styleManager });
+  const runner = createGevActionRunner({ viewer, dataManager, styleManager });
+  const voice = await runner('get_current_view_state');
+
+  assert.deepEqual(withoutVoicePresentation(voice), packet);
+  assert.equal(packet.context.mode, 'contacts');
+  assert.equal(packet.context.modeInternal, 'flights');
+  assert.equal(packet.layers[0].feedState, 'nominal');
+  assert.equal(packet.feedProvenance.overall, 'nominal');
+});
+
+test('World Packet keeps stale/unavailable feed semantics distinct from empty', () => {
+  const { viewer, dataManager, styleManager } = harness();
+  dataManager.getAll = () => [
+    {
+      id: 'traffic',
+      name: 'Traffic',
+      enabled: true,
+      stats: {
+        count: 0,
+        source: 'fixture',
+        error: 'fixture unavailable',
+        lastUpdate: null,
+      },
+    },
+  ];
+
+  const packet = getWorldPacket({ viewer, dataManager, styleManager });
+  assert.equal(packet.layers[0].count, 0);
+  assert.notEqual(packet.layers[0].feedState, 'nominal');
+  assert.notEqual(packet.feedProvenance.overall, 'nominal');
+  assert.match(packet.feedProvenance.note, /fixture unavailable/i);
+});
+
+// The 2026-10 main voice contract omits disabled layers from the model payload.
+test('World Packet and voice preserve enabled-only payload and count disabled layers', async () => {
+  const { viewer, dataManager, styleManager } = harness();
+  const rows = dataManager.getAll();
+  rows.push({
+    id: 'earthquakes',
+    name: 'Earthquakes',
+    enabled: false,
+    stats: { count: 99, source: 'fixture', error: 'stale' },
+  });
+  let reads = 0;
+  dataManager.getAll = () => {
+    reads += 1;
+    return rows;
+  };
+  const packet = getWorldPacket({ viewer, dataManager, styleManager });
+  assert.equal(reads, 1, 'collect the roster once rather than repeatedly');
+  assert.equal(packet.disabledLayerCount, 1);
+  assert.deepEqual(
+    packet.layers.map((layer) => layer.id),
+    ['traffic'],
+  );
+  assert.equal(packet.feedProvenance.overall, 'nominal');
+
+  const runner = createGevActionRunner({ viewer, dataManager, styleManager });
+  const voice = await runner('get_current_view_state');
+  assert.deepEqual(withoutVoicePresentation(voice), packet);
+});
+
+const PINNED_NOW = Date.UTC(2026, 9, 17, 12, 0, 0);
+
+// Exercises every packet field: context vocabulary and Contacts window,
+// cockpit, controls, scene playback, tracked families (one not ready),
+// enabled and disabled layers, and an aged and an unavailable feed.
+function pinnedHarness() {
+  const { viewer } = harness();
+  const rows = [
+    {
+      id: 'flights',
+      name: 'Flights',
+      enabled: true,
+      stats: {
+        count: 12,
+        source: 'fixture-adsb',
+        lastUpdate: PINNED_NOW - 90_000,
+      },
+    },
+    {
+      id: 'traffic',
+      name: 'Traffic',
+      enabled: true,
+      stats: {
+        count: 0,
+        source: 'fixture',
+        error: 'fixture unavailable',
+        lastUpdate: null,
+      },
+    },
+    {
+      id: 'earthquakes',
+      name: 'Earthquakes',
+      enabled: false,
+      stats: { count: 99, source: 'fixture', error: 'stale' },
+    },
+  ];
+  const module = (methods) => ({ module: methods });
+  const dataManager = {
+    layers: new Map([
+      [
+        'flights',
+        module({
+          getTrackedInfo: () => ({ icao24: 'abc123', callsign: 'TEST1' }),
+        }),
+      ],
+      [
+        'ais-live-vessels',
+        module({ getSelectedInfo: () => ({ mmsi: '366000001' }) }),
+      ],
+      [
+        'satellites',
+        module({
+          getTrackedInfo: () => {
+            throw new Error('not ready');
+          },
+        }),
+      ],
+      [
+        'military-awareness',
+        module({
+          getContextSnapshot: () => ({ snapshot: true }),
+          contactsWindowFromSnapshot: (snapshot) =>
+            snapshot ? { windowMin: 30, count: 4 } : null,
+        }),
+      ],
+    ]),
+    getAll: () => rows,
+  };
+  const styleManager = {
+    activeStyle: 'night-vision',
+    getContextModeState: () => ({
+      mode: 'flights',
+      entering: null,
+      priorMode: null,
+    }),
+    getCockpitState: () => ({ active: false }),
+    getControlState: () => ({ hud: { visible: 'auto' } }),
+  };
+  const sceneDirector = {
+    getPlaybackStatus: () => ({ playing: false, sceneId: 'fixture' }),
+  };
+  return { viewer, dataManager, styleManager, sceneDirector };
+}
+
+// Captured from main's get_current_view_state before the extraction
+// (bilawalsidhu/gods-eye-view@3d8e1ef0) with Date.now pinned to PINNED_NOW,
+// minus the speech envelope. Key order is part of the contract.
+const PRE_EXTRACTION_PAYLOAD = {
+  ok: true,
+  action: 'get_current_view_state',
+  camera: {
+    latitude: 30.259999999999994,
+    longitude: -97.74,
+    heightM: 499.99999999901877,
+  },
+  style: 'night-vision',
+  context: {
+    mode: 'contacts',
+    entering: null,
+    priorMode: null,
+    modeInternal: 'flights',
+    enteringInternal: null,
+    priorModeInternal: null,
+    contactsWindow: { windowMin: 30, count: 4 },
+  },
+  cockpit: { active: false },
+  controls: { hud: { visible: 'auto' } },
+  scenePlayback: { playing: false, sceneId: 'fixture' },
+  tracked: [
+    {
+      kind: 'aircraft',
+      layerId: 'flights',
+      icao24: 'abc123',
+      callsign: 'TEST1',
+    },
+    { kind: 'vessel', layerId: 'ais-live-vessels', mmsi: '366000001' },
+  ],
+  disabledLayerCount: 1,
+  layers: [
+    {
+      id: 'flights',
+      name: 'Flights',
+      enabled: true,
+      count: 12,
+      error: null,
+      feedState: 'nominal',
+      source: 'fixture-adsb',
+      lastUpdate: 1792238310000,
+    },
+    {
+      id: 'traffic',
+      name: 'Traffic',
+      enabled: true,
+      count: 0,
+      error: 'fixture unavailable',
+      feedState: 'unavailable',
+      source: 'fixture',
+      lastUpdate: 0,
+    },
+  ],
+  feedProvenance: {
+    overall: 'unavailable',
+    layers: [
+      {
+        id: 'flights',
+        name: 'Flights',
+        enabled: true,
+        feedState: 'nominal',
+        source: 'fixture-adsb',
+        count: 12,
+        lastUpdate: 1792238310000,
+        ageSec: 90,
+        ageLabel: '1m ago',
+        error: null,
+      },
+      {
+        id: 'traffic',
+        name: 'Traffic',
+        enabled: true,
+        feedState: 'unavailable',
+        source: 'fixture',
+        count: 0,
+        lastUpdate: 0,
+        ageSec: null,
+        ageLabel: null,
+        error: 'fixture unavailable',
+      },
+    ],
+    note: 'Traffic is UNAVAILABLE (fixture, fixture unavailable). Narrate that provenance with any count; do not describe this as live.',
+  },
+};
+
+function assertPinnedPayload(actual) {
+  assert.deepEqual(actual, PRE_EXTRACTION_PAYLOAD);
+  // deepEqual ignores key order; the serialized form does not.
+  assert.equal(JSON.stringify(actual), JSON.stringify(PRE_EXTRACTION_PAYLOAD));
+}
+
+test('World Packet matches the pre-extraction get_current_view_state payload', () => {
+  const packet = getWorldPacket({ ...pinnedHarness(), now: PINNED_NOW });
+  assertPinnedPayload(packet);
+});
+
+test('voice get_current_view_state still returns the pre-extraction payload', async (t) => {
+  t.mock.method(Date, 'now', () => PINNED_NOW);
+  const runner = createGevActionRunner(pinnedHarness());
+  const voice = await runner('get_current_view_state');
+  assertPinnedPayload(withoutVoicePresentation(voice));
+});
+
+test('World Packet ages feeds against the clock when now is not a finite number', (t) => {
+  t.mock.method(Date, 'now', () => PINNED_NOW);
+  for (const now of [null, Number.NaN, '2026-10-17']) {
+    const packet = getWorldPacket({ ...pinnedHarness(), now });
+    const flights = packet.feedProvenance.layers.find(
+      (layer) => layer.id === 'flights',
+    );
+    assert.equal(flights.ageSec, 90, `now: ${String(now)}`);
+    assert.equal(flights.ageLabel, '1m ago', `now: ${String(now)}`);
+  }
+});
+
+test('World Packet rejects null options with the camera requirement', () => {
+  assert.throws(() => getWorldPacket(null), /requires a viewer camera/);
+});

src/annotations/adminOutline.test.mjs

@@ -0,0 +1,323 @@
+// Area annotations draw bundled state/province/county outlines with no
+// network lookup, and multi-part outlines reach the renderer intact.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { FEATURE_SOURCE_METHODS } from '../sources/featureSource.js';
+import { createAnnotationResolver } from './resolver.js';
+import { createAnnotationEngine } from './annotationEngine.js';
+import { _resetRenderGovernorForTest } from '../renderGovernor.js';
+
+function viewerAt(lat, lon, height = 20_000) {
+  return {
+    camera: {
+      positionCartographic: {
+        latitude: (lat * Math.PI) / 180,
+        longitude: (lon * Math.PI) / 180,
+        height,
+      },
+    },
+  };
+}
+
+/** A resolver whose boundary lookups and geocoder record every call. */
+function harness(place = null) {
+  const lookups = [];
+  const featureSource = {};
+  for (const method of FEATURE_SOURCE_METHODS)
+    featureSource[method] = async () => {
+      lookups.push(method);
+      return null;
+    };
+  const geocodes = [];
+  const placeSearch = {
+    async geocode(query) {
+      geocodes.push(query);
+      return { place };
+    },
+    async textSearch() {
+      geocodes.push('text-search');
+      return [];
+    },
+  };
+  const { resolveAnnotationTarget } = createAnnotationResolver({
+    featureSource,
+  });
+  const resolve = (target, viewer, extra = {}) =>
+    resolveAnnotationTarget({
+      placeSearch,
+      viewer,
+      target,
+      footprint: true,
+      deferFootprint: true,
+      ...extra,
+    });
+  return { resolve, lookups, geocodes };
+}
+
+const AUSTIN = viewerAt(30.2672, -97.7431, 3000);
+
+test('"Texas", "Travis County, Texas" and "Bavaria" outline offline', async () => {
+  const { resolve, lookups, geocodes } = harness();
+  for (const [target, label] of [
+    ['Texas', 'Texas'],
+    ['Travis County, Texas', 'Travis County'],
+    // Far from the camera, but named outright: no proximity gate applies.
+    ['Bavaria', 'Bavaria'],
+  ]) {
+    const resolved = await resolve(target, AUSTIN);
+    assert.ok(resolved, target);
+    assert.equal(resolved.source, 'bundled', target);
+    assert.equal(resolved.label, label);
+    assert.equal(resolved.footprintKind, 'area');
+    assert.equal(resolved.synthesized, false);
+    assert.equal(resolved.resolveOutline, undefined, 'drawn at once');
+    assert.ok(resolved.ring.length >= 9, `${target} ring`);
+    assert.deepEqual(resolved.ring[0], resolved.ring.at(-1), 'ring closed');
+    assert.ok(resolved.polygons.length >= 1, `${target} parts`);
+    assert.equal(resolved.polygons[0][0].length + 1, resolved.ring.length);
+    assert.ok(resolved.viewport?.low && resolved.viewport?.high);
+  }
+  assert.deepEqual(geocodes, [], 'no geocoding');
+  assert.deepEqual(lookups, [], 'no boundary lookups');
+});
+
+test('duplicate county names go to the one near the camera', async () => {
+  const { resolve } = harness();
+  const nearPortland = await resolve(
+    'Washington County',
+    viewerAt(45.52, -122.68),
+  );
+  assert.ok(nearPortland.lat > 45 && nearPortland.lon < -122, 'Oregon');
+  const nearAustin = await resolve('Washington County', AUSTIN);
+  assert.ok(nearAustin.lat > 29.9 && nearAustin.lat < 30.5, 'Texas');
+  assert.ok(nearAustin.lon > -96.8 && nearAustin.lon < -96, 'Texas');
+});
+
+test('multi-part outlines carry every part and hole', async () => {
+  const { resolve } = harness();
+  const hawaii = await resolve('Hawaii', AUSTIN);
+  assert.ok(hawaii.polygons.length >= 7, 'islands');
+  const brandenburg = await resolve('Brandenburg', AUSTIN);
+  assert.ok(
+    brandenburg.polygons.some((part) => part.length === 2),
+    'Berlin hole',
+  );
+});
+
+test('Georgia resolves from camera geography without a geocoder', async () => {
+  const { resolve, lookups, geocodes } = harness();
+  for (const [query, viewer, latitude] of [
+    ['Georgia', viewerAt(33.75, -84.39, 400_000), 32],
+    ['the country of Georgia', AUSTIN, 42],
+    ['Georgia', viewerAt(41.7, 44.8), 42],
+  ]) {
+    const resolved = await resolve(query, viewer);
+    assert.equal(resolved.source, 'bundled');
+    assert.ok(Math.abs(resolved.lat - latitude) < 2);
+    assert.ok(resolved.ring.length > 20);
+  }
+  assert.deepEqual(lookups, []);
+  assert.deepEqual(geocodes, []);
+});
+
+test('Gold Coast in Australia cannot acquire its West African namesake outline', async () => {
+  for (const types of [['locality', 'political'], ['natural_feature']]) {
+    const { resolve, geocodes } = harness({
+      lat: -28.0167,
+      lng: 153.4,
+      label: 'Gold Coast, Australia',
+      name: 'Gold Coast',
+      types,
+    });
+    const resolved = await resolve('Gold Coast', viewerAt(-28.0167, 153.4));
+    assert.equal(resolved?.source, 'geocode');
+    assert.equal(resolved.lat, -28.0167);
+    assert.equal(resolved.lon, 153.4);
+    assert.equal(resolved.naturalRegion, undefined);
+    const outline = await resolved.resolveOutline();
+    assert.equal(outline?.naturalRegion, undefined);
+    assert.deepEqual(geocodes, ['Gold Coast']);
+  }
+});
+
+test('natural annotation outlines require a geocoded anchor', async () => {
+  for (const viewer of [AUSTIN, {}, viewerAt(46.5, 10, 248_000)]) {
+    const miss = harness();
+    assert.equal(await miss.resolve('the Alps', viewer), null);
+    assert.ok(miss.geocodes.includes('the Alps'));
+  }
+  const anchored = harness({
+    lat: 46.5,
+    lng: 10,
+    label: 'Alps',
+    name: 'Alps',
+    types: ['natural_feature'],
+  });
+  const resolved = await anchored.resolve('the Alps', {});
+  assert.equal(resolved.source, 'geocode');
+  const outline = await resolved.resolveOutline();
+  assert.equal(outline.naturalRegion, 'Alps');
+  assert.ok(outline.ring.length >= 8);
+});
+
+test('overlapping natural candidates continue through geocoding without choosing a ring', async () => {
+  const { resolve, geocodes } = harness({
+    lat: 45.6336,
+    lng: -74.86493,
+    label: 'Canadian Shield',
+    name: 'Canadian Shield',
+    types: ['natural_feature'],
+  });
+  const resolved = await resolve(
+    'Canadian Shield',
+    viewerAt(45.6336, -74.86493),
+  );
+  assert.equal(resolved?.source, 'geocode');
+  assert.equal((await resolved.resolveOutline())?.naturalRegion, undefined);
+  assert.deepEqual(geocodes, ['Canadian Shield']);
+});
+
+test('geocoded natural outlines respect district and around intent', async () => {
+  for (const extra of [
+    { entityKind: 'district' },
+    { intent: 'around_the_thing' },
+  ]) {
+    const { resolve, geocodes } = harness({
+      lat: 46.5,
+      lng: 10,
+      label: 'Alps',
+      name: 'Alps',
+      types:
+        extra.entityKind === 'district' ? ['locality'] : ['natural_feature'],
+    });
+    const resolved = await resolve('the Alps', viewerAt(46.5, 10), extra);
+    assert.ok(geocodes.includes('the Alps'));
+    assert.equal((await resolved.resolveOutline())?.naturalRegion, undefined);
+  }
+});
+
+test('cancellation while a bundled admin lookup is pending cannot publish an annotation', async () => {
+  const controller = new AbortController();
+  const { resolve, geocodes } = harness();
+  const pending = resolve('the Alps', viewerAt(46.5, 10), {
+    signal: controller.signal,
+  });
+  controller.abort();
+  await assert.rejects(pending, { name: 'AbortError' });
+  assert.deepEqual(geocodes, []);
+});
+
+test('country asks and geocoded country scopes use the bundled outline', async () => {
+  const direct = harness();
+  for (const name of ['Switzerland', 'Iran', 'France', 'Japan']) {
+    const resolved = await direct.resolve(name, AUSTIN);
+    assert.equal(resolved.source, 'bundled');
+    assert.ok(resolved.polygons.length);
+    if (name === 'Japan') assert.ok(resolved.polygons.length > 3);
+  }
+  assert.deepEqual(direct.lookups, []);
+  assert.deepEqual(direct.geocodes, []);
+  const geocoded = harness({
+    lat: 46.95,
+    lng: 7.45,
+    label: 'Switzerland',
+    name: 'Switzerland',
+    types: ['country', 'political'],
+  });
+  const resolved = await geocoded.resolve(
+    'Swiss country outline',
+    viewerAt(46.95, 7.45),
+  );
+  assert.equal(resolved.source, 'geocode');
+  const outline = await resolved.resolveOutline();
+  assert.ok(outline.polygons.length);
+  assert.deepEqual(geocoded.lookups, []);
+});
+
+test('non-admin asks and entity facts keep the existing path', async () => {
+  const { resolve, geocodes } = harness();
+  await resolve('Texas Capitol', AUSTIN);
+  await resolve('Texas', AUSTIN, { entityKind: 'building' });
+  await resolve('Zilker Park', AUSTIN);
+  assert.equal(
+    geocodes.filter((q) => q !== 'text-search').length,
+    3,
+    'each ask geocoded',
+  );
+  // Points and explicit coordinates never use the pack.
+  const point = await resolve('Texas', AUSTIN, { footprint: false });
+  assert.notEqual(point?.source, 'bundled');
+});
+
+test('the engine keeps every part on the mark, drawn at once or upgraded', async (t) => {
+  globalThis.requestAnimationFrame ??= () => 1;
+  globalThis.cancelAnimationFrame ??= () => {};
+  _resetRenderGovernorForTest();
+  t.after(() => _resetRenderGovernorForTest());
+  const polygons = [
+    [
+      [
+        [0, 0],
+        [2, 0],
+        [2, 2],
+        [0, 2],
+      ],
+      [
+        [0.5, 0.5],
+        [0.5, 1],
+        [1, 1],
+        [1, 0.5],
+      ],
+    ],
+    [
+      [
+        [3, 3],
+        [4, 3],
+        [4, 4],
+      ],
+    ],
+  ];
+  const ring = [...polygons[0][0], polygons[0][0][0]];
+  const seen = [];
+  const renderer = {
+    add: (anno) => seen.push(['add', anno.polygons]),
+    update: (anno) => seen.push(['update', anno.polygons]),
+    remove() {},
+    sync() {},
+    destroy() {},
+  };
+  const engine = createAnnotationEngine({
+    viewer: {},
+    renderer,
+    resolveTarget: async ({ target }) =>
+      target === 'now'
+        ? { lon: 1, lat: 1, height: 0, ring, polygons, footprintKind: 'area' }
+        : {
+            lon: 1,
+            lat: 1,
+            height: 0,
+            ring: null,
+            resolveOutline: async () => ({
+              ring,
+              polygons,
+              footprintKind: 'area',
+              lat: 1,
+              lon: 1,
+              height: 0,
+            }),
+          },
+  });
+  await engine.annotate([{ type: 'area', target: 'now' }]);
+  await engine.annotate([{ type: 'area', target: 'later', label: 'later' }]);
+  for (let i = 0; i < 20; i += 1) await Promise.resolve();
+  const marks = engine.list();
+  assert.equal(marks[0].polygons, polygons);
+  assert.ok(
+    marks.some((m) => m.label === 'later' && m.polygons === polygons),
+    'upgrade carries the parts',
+  );
+  assert.ok(
+    seen.some(([kind, parts]) => kind === 'update' && parts === polygons),
+  );
+  engine.destroy();
+});

src/annotations/annotationEngine.test.mjs

@@ -1,3 +1,4 @@
+import { createStandalonePlaceSearch } from '../standalone/placeSearch.js';
 // Voice-annotation resilience contract tests — pure logic, no network, no browser.
 //
 // Locks the 2026-07-21 field-test fixes:
@@ -253,7 +254,9 @@ test('retry: HTTP 429 Retry-After 5s gets one ladder-spaced retry; a second 429
   t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 10_000 });
   globalThis.window = { setTimeout: globalThis.setTimeout, clearTimeout: globalThis.clearTimeout };
   const requestTimes = [];
-  globalThis.fetch = async () => {
+  globalThis.fetch = async (url) => {
+    // The one-time capability probe is not an outline request.
+    if (String(url).endsWith('/status')) return httpFailure(404);
     requestTimes.push(Date.now());
     return httpFailure(429, '5');
   };
@@ -310,7 +313,9 @@ test('retry: a plain HTTP 500 still exhausts the existing 8s/25s transient ladde
   t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 100_000 });
   globalThis.window = { setTimeout: globalThis.setTimeout, clearTimeout: globalThis.clearTimeout };
   const requestTimes = [];
-  globalThis.fetch = async () => {
+  globalThis.fetch = async (url) => {
+    if (String(url).endsWith('/status'))
+      return Response.json({ configured: true });
     requestTimes.push(Date.now());
     return httpFailure(500);
   };
@@ -385,7 +390,7 @@ test('targetKey: empty / absent targets stay null (coord and pixel specs never p
   assert.equal(normalizeTargetKey(undefined), null);
 });
 
-test('outline upgrade updates the rendered element in place without remove/add', async (t) => {
+test('outline upgrade updates the rendered element in place without remove/add', { timeout: 5000 }, async (t) => {
   const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
   const originalCancelAnimationFrame = globalThis.cancelAnimationFrame;
   const originalWindow = globalThis.window;
@@ -399,7 +404,7 @@ test('outline upgrade updates the rendered element in place without remove/add',
   };
   let overpassCall = 0;
   globalThis.fetch = async (url) => {
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       return { json: async () => ({
         status: 'OK',
         results: [{
@@ -466,7 +471,7 @@ test('outline upgrade updates the rendered element in place without remove/add',
     sync() {},
   };
   const viewer = {};
-  const engine = createAnnotationEngine({ viewer, renderer });
+  const engine = createAnnotationEngine({ viewer, renderer, placeSearch: createStandalonePlaceSearch({ resolveApiKey: () => 'unit-test-key' }) });
   const upgraded = new Promise((resolve) => engine.onOutlineEvent(resolve));
 
   const result = await engine.annotate([{
@@ -709,3 +714,34 @@ test('a late annotation resolver cannot redraw after destruction', async (t) =>
   assert.equal(calls.add, 0);
   assert.equal(engine.count(), 0);
 });
+
+test('only an explicit navigation request permits resolving distant annotation targets', async (t) => {
+  installAnimationFrameStubs(t);
+  _resetRenderGovernorForTest();
+  t.after(() => _resetRenderGovernorForTest());
+  const { renderer } = throwingRendererHarness();
+  renderer.destroy = () => {};
+  const received = [];
+  const engine = createAnnotationEngine({ viewer: {}, renderer,
+    resolveTarget: async (options) => { received.push(options); return null; },
+  });
+  await engine.annotate([{ type: 'point', target: 'Remote landmark' }]);
+  await engine.annotate([{ type: 'point', target: 'Remote landmark' }], { flyTo: true });
+  assert.deepEqual(received.map(options => options.allowDistant), [false, true]);
+  engine.destroy();
+});
+
+test('a drawn line that rounds up to the next unit is labelled in it, not as 1000 m or 10.0 km', async (t) => {
+  installAnimationFrameStubs(t);
+  const labels = [];
+  const renderer = { add(anno) { labels.push(anno.label); }, update() {}, remove() {}, sync() {}, destroy() {} };
+  const engine = createAnnotationEngine({ viewer: {}, renderer });
+  const metresPerDegree = (6371.0088 * 1000 * Math.PI) / 180;
+  for (const metres of [994, 996, 9940, 9960]) {
+    await engine.annotate([
+      { type: 'route', manual: true, path: [[0, 0], [0, metres / metresPerDegree]] },
+    ]);
+  }
+  assert.deepEqual(labels, ['990 m', '1.0 km', '9.9 km', '10 km']);
+  engine.destroy();
+});

src/annotations/annotationGeoJson.js

@@ -1,213 +0,0 @@
-/**
- * @module annotationGeoJson
- * @description Pure conversion between the runtime annotation model and a GeoJSON
- * FeatureCollection — a durable, testable interchange format for saving, exporting,
- * importing, sharing, and fixture-testing annotations. It is NOT a renderer input:
- * the Cesium/SVG renderers keep consuming runtime annotation objects. This module is
- * deliberately Cesium-free and dependency-free so it can run in tests and any context.
- *
- * Mapping (one Feature per mark; project fields namespaced `gev:`):
- *   pin | highlight | label  ->  Point      (anchor)
- *   arrow                     ->  LineString (anchor -> to)
- *   route                     ->  LineString (the routed path)
- *   area (with a ring)        ->  Polygon    (the footprint ring; centroid in `gev:anchor`)
- *   area (no ring)            ->  Point      (degenerate area; renders as a marker)
- *
- * Coordinates are GeoJSON positions `[lon, lat]`, or `[lon, lat, height]` when a height
- * is present (anchor / route / arrow). Area ring vertices are 2D `[lon, lat]` (the runtime
- * ring has no per-vertex height). Conversions are LOSSLESS for the semantic fields; transient
- * render state (alpha/bornAt/createdAt/expiring) is intentionally NOT carried — an importer
- * re-initializes it.
- */
-
-const VALID_TYPES = new Set(['pin', 'highlight', 'label', 'arrow', 'route', 'area']);
-
-/** {lon,lat,height?} -> GeoJSON position, or null if not a finite lon/lat. */
-function toPosition(p) {
-  if (!p || !Number.isFinite(p.lon) || !Number.isFinite(p.lat)) return null;
-  return Number.isFinite(p.height) ? [p.lon, p.lat, p.height] : [p.lon, p.lat];
-}
-
-/** GeoJSON position -> {lon,lat,height?}, or null if malformed. */
-function fromPosition(c) {
-  if (!Array.isArray(c) || !Number.isFinite(c[0]) || !Number.isFinite(c[1])) return null;
-  return Number.isFinite(c[2]) ? { lon: c[0], lat: c[1], height: c[2] } : { lon: c[0], lat: c[1] };
-}
-
-/** Mean of a runtime ring (`[[lon,lat],...]`), used as a fallback area anchor on import. */
-function ringCentroid(ring) {
-  if (!Array.isArray(ring) || ring.length === 0) return null;
-  let sx = 0;
-  let sy = 0;
-  for (const [lon, lat] of ring) { sx += lon; sy += lat; }
-  return { lon: sx / ring.length, lat: sy / ring.length };
-}
-
-/**
- * Convert one runtime annotation object to a GeoJSON Feature.
- * @param {object} anno - A runtime annotation (as produced by the engine).
- * @returns {object|null} A GeoJSON Feature, or null if `anno` can't form a valid geometry.
- */
-export function annotationToFeature(anno) {
-  if (!anno || typeof anno !== 'object' || !VALID_TYPES.has(anno.type)) return null;
-  const type = anno.type;
-  const properties = {
-    'gev:type': type,
-    'gev:id': anno.id ?? null,
-    'gev:label': anno.label ?? null,
-    'gev:color': anno.color ?? null,
-    'gev:ttlMs': anno.ttlMs ?? null,
-  };
-  let geometry = null;
-
-  if (type === 'route') {
-    const coords = (Array.isArray(anno.path) ? anno.path : []).map(toPosition).filter(Boolean);
-    if (coords.length < 2) return null;
-    geometry = { type: 'LineString', coordinates: coords };
-    properties['gev:mode'] = anno.mode ?? null;
-    properties['gev:distanceM'] = anno.distanceM ?? null;
-    properties['gev:durationS'] = anno.durationS ?? null;
-    properties['gev:fallback'] = Boolean(anno.fallback);
-  } else if (type === 'arrow') {
-    const from = toPosition(anno.anchor);
-    const to = toPosition(anno.to);
-    if (!from || !to) return null;
-    geometry = { type: 'LineString', coordinates: [from, to] };
-  } else if (type === 'area' && Array.isArray(anno.ring) && anno.ring.length >= 3) {
-    const ring = [];
-    for (const pair of anno.ring) {
-      if (!Array.isArray(pair) || !Number.isFinite(pair[0]) || !Number.isFinite(pair[1])) return null;
-      ring.push([pair[0], pair[1]]);
-    }
-    // GeoJSON linear rings must be explicitly closed (first === last).
-    const first = ring[0];
-    const last = ring[ring.length - 1];
-    if (first[0] !== last[0] || first[1] !== last[1]) ring.push([first[0], first[1]]);
-    geometry = { type: 'Polygon', coordinates: [ring] };
-    properties['gev:footprintKind'] = anno.footprintKind ?? null;
-    properties['gev:buildingHeight'] = anno.buildingHeight ?? null;
-    properties['gev:synthesized'] = Boolean(anno.synthesized);
-    const anchor = toPosition(anno.anchor);
-    if (anchor) properties['gev:anchor'] = anchor; // preserve the exact centroid, don't recompute
-  } else {
-    // pin / highlight / label, or a degenerate `area` with no ring -> a Point at the anchor.
-    const anchor = toPosition(anno.anchor);
-    if (!anchor) return null;
-    geometry = { type: 'Point', coordinates: anchor };
-    if (type === 'area') {
-      properties['gev:footprintKind'] = anno.footprintKind ?? null;
-      properties['gev:synthesized'] = Boolean(anno.synthesized);
-    }
-  }
-
-  return { type: 'Feature', geometry, properties };
-}
-
-/**
- * Convert a GeoJSON Feature back to a runtime annotation object (semantic fields only —
- * the importer adds render state). Fails CLOSED: returns null for any malformed feature,
- * unknown `gev:type`, or geometry that doesn't match the declared type.
- * @param {object} feature - A GeoJSON Feature produced by {@link annotationToFeature}.
- * @returns {object|null}
- */
-export function featureToAnnotation(feature) {
-  if (!feature || feature.type !== 'Feature' || !feature.geometry || !feature.properties) return null;
-  const g = feature.geometry;
-  const p = feature.properties;
-  const type = p['gev:type'];
-  if (!VALID_TYPES.has(type)) return null;
-
-  const base = {
-    type,
-    id: p['gev:id'] ?? null,
-    label: p['gev:label'] ?? null,
-    color: p['gev:color'] ?? 'primary',
-    ttlMs: p['gev:ttlMs'] ?? null,
-  };
-
-  if (type === 'route') {
-    if (g.type !== 'LineString' || !Array.isArray(g.coordinates) || g.coordinates.length < 2) return null;
-    const path = g.coordinates.map(fromPosition);
-    if (path.some((x) => !x)) return null;
-    return {
-      ...base,
-      anchor: path[0],
-      to: null,
-      ring: null,
-      path,
-      mode: p['gev:mode'] ?? null,
-      distanceM: p['gev:distanceM'] ?? null,
-      durationS: p['gev:durationS'] ?? null,
-      fallback: Boolean(p['gev:fallback']),
-    };
-  }
-
-  if (type === 'arrow') {
-    if (g.type !== 'LineString' || !Array.isArray(g.coordinates) || g.coordinates.length !== 2) return null;
-    const from = fromPosition(g.coordinates[0]);
-    const to = fromPosition(g.coordinates[1]);
-    if (!from || !to) return null;
-    return { ...base, anchor: from, to, ring: null };
-  }
-
-  if (g.type === 'Polygon') {
-    if (type !== 'area' || !Array.isArray(g.coordinates) || !Array.isArray(g.coordinates[0])) return null;
-    const raw = g.coordinates[0];
-    if (raw.length < 4) return null; // a closed triangle is the minimum (4 positions)
-    const ring = [];
-    for (const c of raw) {
-      if (!Array.isArray(c) || !Number.isFinite(c[0]) || !Number.isFinite(c[1])) return null;
-      ring.push([c[0], c[1]]);
-    }
-    // Drop the GeoJSON closing duplicate to match the runtime ring (not explicitly closed).
-    const f = ring[0];
-    const l = ring[ring.length - 1];
-    if (ring.length > 3 && f[0] === l[0] && f[1] === l[1]) ring.pop();
-    const anchor = fromPosition(p['gev:anchor']) || ringCentroid(ring);
-    return {
-      ...base,
-      anchor,
-      to: null,
-      ring,
-      footprintKind: p['gev:footprintKind'] ?? null,
-      buildingHeight: p['gev:buildingHeight'] ?? null,
-      synthesized: Boolean(p['gev:synthesized']),
-    };
-  }
-
-  // Point geometry — pin / highlight / label, or a degenerate area.
-  if (g.type !== 'Point') return null;
-  const anchor = fromPosition(g.coordinates);
-  if (!anchor) return null;
-  const out = { ...base, anchor, to: null, ring: null };
-  if (type === 'area') {
-    out.footprintKind = p['gev:footprintKind'] ?? null;
-    out.buildingHeight = null;
-    out.synthesized = Boolean(p['gev:synthesized']);
-  }
-  return out;
-}
-
-/**
- * Convert an array of runtime annotations to a GeoJSON FeatureCollection.
- * Marks that can't form a valid geometry are dropped (not thrown).
- * @param {Array<object>} annotations
- * @returns {{type:'FeatureCollection', features: object[]}}
- */
-export function annotationsToFeatureCollection(annotations) {
-  const features = (Array.isArray(annotations) ? annotations : [])
-    .map(annotationToFeature)
-    .filter(Boolean);
-  return { type: 'FeatureCollection', features };
-}
-
-/**
- * Convert a GeoJSON FeatureCollection back to runtime annotation objects.
- * Malformed features are skipped (fail-closed per feature), never throwing.
- * @param {object} collection
- * @returns {Array<object>}
- */
-export function featureCollectionToAnnotations(collection) {
-  if (!collection || collection.type !== 'FeatureCollection' || !Array.isArray(collection.features)) return [];
-  return collection.features.map(featureToAnnotation).filter(Boolean);
-}

src/annotations/annotationGeoJson.test.mjs

@@ -1,118 +0,0 @@
-// Pure round-trip + fail-closed tests for the annotation <-> GeoJSON interchange.
-// Run with: npm test   (node --test). No framework, no Cesium, no browser.
-import { test } from 'node:test';
-import assert from 'node:assert/strict';
-import {
-  annotationToFeature,
-  featureToAnnotation,
-  annotationsToFeatureCollection,
-  featureCollectionToAnnotations,
-} from './annotationGeoJson.js';
-
-// A round-trip preserves the semantic fields (transient render state is intentionally not carried).
-const roundTrip = (anno) => featureToAnnotation(annotationToFeature(anno));
-
-test('point (pin/highlight/label) round-trips, height preserved', () => {
-  const pin = { type: 'pin', id: 'anno-1', label: 'ILM', color: 'primary', ttlMs: null,
-    anchor: { lon: -77.9, lat: 34.27, height: 12 }, to: null, ring: null };
-  const f = annotationToFeature(pin);
-  assert.equal(f.geometry.type, 'Point');
-  assert.deepEqual(f.geometry.coordinates, [-77.9, 34.27, 12]);
-  assert.equal(f.properties['gev:type'], 'pin');
-  assert.deepEqual(roundTrip(pin), pin);
-
-  const hl = { type: 'highlight', id: 'anno-2', label: 'spot', color: 'amber', ttlMs: 30000,
-    anchor: { lon: 2.29, lat: 48.85 }, to: null, ring: null };
-  assert.deepEqual(roundTrip(hl), hl); // no height -> 2D position
-});
-
-test('area polygon round-trips: ring closed in GeoJSON, un-closed on import; centroid preserved', () => {
-  const area = { type: 'area', id: 'anno-3', label: 'Marina', color: 'primary', ttlMs: null,
-    anchor: { lon: -122.434, lat: 37.804 }, to: null,
-    ring: [[-122.44, 37.80], [-122.43, 37.81], [-122.42, 37.80], [-122.43, 37.79]],
-    footprintKind: 'area', buildingHeight: null, synthesized: false };
-  const f = annotationToFeature(area);
-  assert.equal(f.geometry.type, 'Polygon');
-  const gjRing = f.geometry.coordinates[0];
-  assert.equal(gjRing.length, 5); // 4 vertices + explicit closing point
-  assert.deepEqual(gjRing[0], gjRing[gjRing.length - 1]); // closed
-  assert.deepEqual(f.properties['gev:anchor'], [-122.434, 37.804]);
-  assert.deepEqual(roundTrip(area), area); // ring back to 4, anchor from gev:anchor
-});
-
-test('synthesized + building props are preserved', () => {
-  const synth = { type: 'area', id: 'anno-4', label: 'around', color: 'primary', ttlMs: null,
-    anchor: { lon: -97.74, lat: 30.27 }, to: null,
-    ring: [[-97.75, 30.27], [-97.74, 30.28], [-97.73, 30.27]],
-    footprintKind: 'area', buildingHeight: null, synthesized: true };
-  const f = annotationToFeature(synth);
-  assert.equal(f.properties['gev:synthesized'], true);
-  assert.equal(roundTrip(synth).synthesized, true);
-
-  const bldg = { type: 'area', id: 'anno-5', label: 'Pentagon', color: 'primary', ttlMs: null,
-    anchor: { lon: -77.056, lat: 38.871 }, to: null,
-    ring: [[-77.057, 38.870], [-77.055, 38.872], [-77.054, 38.870]],
-    footprintKind: 'building', buildingHeight: 24, synthesized: false };
-  assert.equal(roundTrip(bldg).footprintKind, 'building');
-  assert.equal(roundTrip(bldg).buildingHeight, 24);
-});
-
-test('route path round-trips with mode/distance/duration', () => {
-  const path = [{ lon: -122.4, lat: 37.7, height: 5 }, { lon: -122.39, lat: 37.71, height: 6 }, { lon: -122.38, lat: 37.72, height: 7 }];
-  const route = { type: 'route', id: 'anno-6', label: '590 m · 8 min', color: 'primary', ttlMs: null,
-    anchor: { lon: -122.4, lat: 37.7, height: 5 }, to: null, ring: null,
-    path, mode: 'foot', distanceM: 590, durationS: 480, fallback: false };
-  const f = annotationToFeature(route);
-  assert.equal(f.geometry.type, 'LineString');
-  assert.equal(f.geometry.coordinates.length, 3);
-  assert.deepEqual(roundTrip(route), route);
-});
-
-test('arrow round-trips (anchor -> to)', () => {
-  const arrow = { type: 'arrow', id: 'anno-7', label: '2 km', color: 'primary', ttlMs: null,
-    anchor: { lon: -122.43, lat: 37.80, height: 3 }, to: { lon: -122.40, lat: 37.81, height: 4 }, ring: null };
-  const f = annotationToFeature(arrow);
-  assert.equal(f.geometry.type, 'LineString');
-  assert.equal(f.geometry.coordinates.length, 2);
-  assert.deepEqual(roundTrip(arrow), arrow);
-});
-
-test('degenerate area (no ring) -> Point, round-trips', () => {
-  const ptArea = { type: 'area', id: 'anno-8', label: 'X', color: 'primary', ttlMs: null,
-    anchor: { lon: 10, lat: 20 }, to: null, ring: null, footprintKind: null, buildingHeight: null, synthesized: false };
-  const f = annotationToFeature(ptArea);
-  assert.equal(f.geometry.type, 'Point');
-  const back = roundTrip(ptArea);
-  assert.equal(back.type, 'area');
-  assert.equal(back.ring, null);
-  assert.deepEqual(back.anchor, { lon: 10, lat: 20 });
-});
-
-test('FeatureCollection round-trips a mixed set', () => {
-  const annos = [
-    { type: 'pin', id: 'a', label: 'p', color: 'primary', ttlMs: null, anchor: { lon: 1, lat: 2 }, to: null, ring: null },
-    { type: 'area', id: 'b', label: 'q', color: 'amber', ttlMs: null, anchor: { lon: 3, lat: 4 }, to: null,
-      ring: [[3, 4], [4, 5], [5, 4]], footprintKind: 'area', buildingHeight: null, synthesized: false },
-  ];
-  const fc = annotationsToFeatureCollection(annos);
-  assert.equal(fc.type, 'FeatureCollection');
-  assert.equal(fc.features.length, 2);
-  assert.deepEqual(featureCollectionToAnnotations(fc), annos);
-});
-
-test('malformed input fails CLOSED (returns null / skips)', () => {
-  assert.equal(featureToAnnotation(null), null);
-  assert.equal(featureToAnnotation({}), null);
-  assert.equal(featureToAnnotation({ type: 'NotAFeature' }), null);
-  assert.equal(featureToAnnotation({ type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0] }, properties: {} }), null); // no gev:type
-  assert.equal(featureToAnnotation({ type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0] }, properties: { 'gev:type': 'route' } }), null); // route needs LineString
-  assert.equal(featureToAnnotation({ type: 'Feature', geometry: { type: 'LineString', coordinates: [[0, 0], [1, 1], [2, 2]] }, properties: { 'gev:type': 'arrow' } }), null); // arrow needs exactly 2
-  assert.equal(featureToAnnotation({ type: 'Feature', geometry: { type: 'Polygon', coordinates: [[[0, 0], [1, 1]]] }, properties: { 'gev:type': 'area' } }), null); // <4 positions
-  assert.equal(featureToAnnotation({ type: 'Feature', geometry: { type: 'Point', coordinates: ['x', 0] }, properties: { 'gev:type': 'pin' } }), null); // non-finite
-  // unknown type on the annotation side too
-  assert.equal(annotationToFeature({ type: 'blob', anchor: { lon: 0, lat: 0 } }), null);
-  assert.equal(annotationToFeature(null), null);
-  // collection helpers never throw on junk
-  assert.deepEqual(featureCollectionToAnnotations({ type: 'X' }), []);
-  assert.deepEqual(annotationsToFeatureCollection('nope'), { type: 'FeatureCollection', features: [] });
-});

src/annotations/annotationResolver.test.mjs

@@ -1,3 +1,5 @@
+import { createStandalonePlaceSearch } from '../standalone/placeSearch.js';
+import { createPlaceSearch } from '../search/placeSearch.js';
 // Footprint-selection contract tests — pure fixtures, no network, no browser.
 //
 // Locks the field-test-7 monument fix (docs/field-test-rootcause-2026-06-30.md §1):
@@ -12,7 +14,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
-  resolveAnnotationTarget,
+  resolveAnnotationTarget as resolveTarget,
   selectFootprint,
   refineScope,
   isGroundsLikeAsk,
@@ -198,7 +200,7 @@ test('ask-side admin bypass: "the Texas Capitol" recovers near-view despite a fa
   const calls = [];
   installGoogleMocks(t, async (url) => {
     calls.push(String(url));
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       return { json: async () => geocodePayload({
         lat: 31.0000,
         lon: -99.0000,
@@ -233,7 +235,7 @@ test('ask-side admin bypass: explicit "state of Texas" skips recovery and proxim
   const calls = [];
   installGoogleMocks(t, async (url) => {
     calls.push(String(url));
-    assert.match(String(url), /^https:\/\/maps\.googleapis\.com\/maps\/api\/geocode/);
+    assert.match(String(url), /^\/api\/google\/geocode\?/);
     return { json: async () => geocodePayload({
       lat: 31.0000,
       lon: -99.0000,
@@ -271,7 +273,7 @@ for (const fixture of [
     const calls = [];
     installGoogleMocks(t, async (url) => {
       calls.push(String(url));
-      if (String(url).startsWith('https://maps.googleapis.com/')) {
+      if (String(url).startsWith('/api/google/geocode')) {
         return { json: async () => geocodePayload({
           lat: fixture.lat,
           lon: fixture.lon,
@@ -297,7 +299,7 @@ test('ask-side admin bypass: bare "Texas" remains on the guarded recovery path',
   const calls = [];
   installGoogleMocks(t, async (url) => {
     calls.push(String(url));
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       return { json: async () => geocodePayload({
         lat: 31.0000,
         lon: -99.0000,
@@ -326,7 +328,7 @@ test('ask-side admin bypass: admin level 2/3 result types never grant a township
   const calls = [];
   installGoogleMocks(t, async (url) => {
     calls.push(String(url));
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       const query = new URL(String(url)).searchParams.get('address');
       return { json: async () => geocodePayload({
         lat: 39.7817,
@@ -378,7 +380,7 @@ function installCapitolMocks(t, elements, components = [
   { long_name: 'Capitol Hill', types: ['neighborhood', 'political'] },
 ]) {
   installGoogleMocks(t, async (url) => {
-    if (String(url).startsWith('https://maps.googleapis.com/')) {
+    if (String(url).startsWith('/api/google/geocode')) {
       return { json: async () => ({ status: 'OK', results: [{
         formatted_address: 'Washington, DC 20004, USA',
         types: ['establishment', 'landmark', 'point_of_interest', 'tourist_attraction'],
@@ -431,3 +433,192 @@ test('a genuine geocoded feature name still canonicalizes an alternate user name
   const result = await resolveAnnotationTarget({ viewer: capitolViewer(), target: 'Congress meeting building', footprint: true });
   assert.deepEqual(result.ring, capitol.geometry.map(p => [p.lon, p.lat]));
 });
+
+// ── Keyless geocoding ────────────────────────────────────────────────────────
+//
+// `geocodePlace` was Google-only: no key returned null, and so did a key whose
+// Geocoding API is not enabled (Google answers HTTP 200 with REQUEST_DENIED).
+// Either way the annotation silently failed to place. Both now fall through to
+// Photon. These drive the second case, because it reaches the SAME fallback
+// through a running Google branch — the no-key branch cannot be driven from
+// `node --test`, since the key expression reads `import.meta.env`, which only
+// Vite defines.
+
+/** Photon's GeoJSON shape, trimmed to the properties the adapter consumes. */
+function photonFeature({ name, lat, lon, tags = {}, extent = null, ...rest }) {
+  return {
+    geometry: { type: 'Point', coordinates: [lon, lat] },
+    properties: { name, ...tags, ...rest, ...(extent ? { extent } : {}) },
+  };
+}
+
+const GOOGLE_FOUND_NOTHING = { ok: true, json: async () => ({ status: 'ZERO_RESULTS', results: [] }) };
+
+test('keyless: a key that geocodes to nothing still anchors the annotation', async (t) => {
+  const requests = [];
+  installGoogleMocks(t, async (url) => {
+    requests.push(String(url));
+    if (String(url).startsWith('/api/google/geocode')) return GOOGLE_FOUND_NOTHING;
+    return {
+      ok: true,
+      json: async () => ({
+        features: [photonFeature({
+          name: 'Lady Bird Lake',
+          lat: 30.25,
+          lon: -97.73,
+          city: 'Austin',
+          state: 'Texas',
+          country: 'United States',
+          tags: { osm_key: 'natural', osm_value: 'water' },
+          // Photon orders extent [west, north, east, south] — a naive [w,s,e,n]
+          // read would invert the box and still look like a valid viewport.
+          extent: [-97.8, 30.28, -97.68, 30.24],
+        })],
+      }),
+    };
+  });
+
+  const resolved = await resolveAnnotationTarget({
+    viewer: closeViewportViewer(),
+    target: 'Lady Bird Lake',
+  });
+
+  assert.ok(resolved, 'a Google miss must not leave the annotation unplaced');
+  assert.equal(resolved.source, 'geocode');
+  assert.deepEqual([resolved.lat, resolved.lon], [30.25, -97.73]);
+  // The label is shortened the same way a Google `formatted_address` is.
+  assert.equal(resolved.label, 'Lady Bird Lake');
+  // Photon's extent reaches the framing code in the Places `{low,high}` shape,
+  // right way up — this is what sizes a grounds disc and the flyTo box.
+  assert.deepEqual(resolved.viewport, {
+    low: { latitude: 30.24, longitude: -97.8 },
+    high: { latitude: 30.28, longitude: -97.68 },
+  });
+  // Google is asked first and exactly once; one Photon call answers it.
+  assert.equal(requests.filter((url) => url.includes('/api/google/geocode')).length, 1);
+  assert.equal(requests.filter((url) => url.includes('photon.komoot.io')).length, 1);
+});
+
+test('keyless: OSM matching uses the feature\'s canonical name, not the user\'s words', async (t) => {
+  // The reason `primaryName` is carried out of Photon at all. The ask names a
+  // landmark AND its surroundings; the geocoded feature is called just "Tejano
+  // Monument". Score the OSM candidates on the raw utterance and the locality
+  // tokens win — this is the Thompson-Austin bug (field test 7) reached through
+  // the keyless path. Score them on the canonical name and the monument wins.
+  const decoy = squareWay(ANCHOR, -250, -250, 3000, {
+    building: 'yes', tourism: 'hotel', name: 'Texas Capitol Austin Visitor Center',
+  });
+  const monument = squareWay(ANCHOR, 5, 5, 300, { tourism: 'artwork', name: 'Tejano Monument' });
+
+  installGoogleMocks(t, async (url, init) => {
+    const href = String(url);
+    if (href.startsWith('/api/google/geocode')) return GOOGLE_FOUND_NOTHING;
+    if (href.startsWith('/api/google/text-search')) return { ok: true, json: async () => ({ places: [] }) };
+    if (href.startsWith('https://photon.komoot.io/')) {
+      return {
+        ok: true,
+        json: async () => ({
+          features: [photonFeature({
+            name: 'Tejano Monument',
+            lat: ANCHOR.lat,
+            lon: ANCHOR.lon,
+            city: 'Austin',
+            tags: { osm_key: 'historic', osm_value: 'memorial' },
+          })],
+        }),
+      };
+    }
+    assert.equal(href, '/api/overpass');
+    assert.equal(init?.method, 'POST');
+    return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ elements: [decoy, monument] }) };
+  });
+
+  const resolved = await resolveAnnotationTarget({
+    viewer: closeViewportViewer(),
+    target: 'the monument near the Texas Capitol, Austin',
+    footprint: true,
+  });
+
+  assert.ok(resolved.ring, 'the monument polygon is monument-scale and exactly named — it must outline');
+  // The anchor re-centres on the chosen polygon, so its position IS the verdict:
+  // the monument sits on the anchor, the decoy 354 m south-west of it.
+  assert.ok(
+    approximateMetres(resolved.lat, resolved.lon, ANCHOR.lat, ANCHOR.lon) < 50,
+    `outlined a polygon ${Math.round(approximateMetres(resolved.lat, resolved.lon, ANCHOR.lat, ANCHOR.lon))} m from the monument`,
+  );
+});
+
+/** Metres between two coordinates — enough precision for a few hundred metres. */
+function approximateMetres(lat1, lon1, lat2, lon2) {
+  const mLat = 111320;
+  const dy = (lat1 - lat2) * mLat;
+  const dx = (lon1 - lon2) * mLat * Math.cos((lat1 * Math.PI) / 180);
+  return Math.hypot(dx, dy);
+}
+
+test('keyless: a Photon outage is not remembered as "no such place"', async (t) => {
+  // Google answering ZERO_RESULTS is a verdict about GOOGLE. Photon holds
+  // plenty of places Google does not — that asymmetry is why this fallback
+  // exists — so a Google verdict plus a Photon timeout must leave the query
+  // open. Caching it would keep an annotation unplaceable for the rest of the
+  // session, on a network that has since recovered.
+  const photonUp = {
+    ok: true,
+    json: async () => ({
+      features: [photonFeature({
+        name: 'Waller Creek', lat: 30.2665, lon: -97.7385, city: 'Austin',
+        tags: { osm_key: 'waterway', osm_value: 'stream' },
+      })],
+    }),
+  };
+  let photonReachable = false;
+  const requests = [];
+  installGoogleMocks(t, async (url) => {
+    requests.push(String(url));
+    if (String(url).startsWith('/api/google/geocode')) return GOOGLE_FOUND_NOTHING;
+    if (!photonReachable) throw new Error('network down');
+    return photonUp;
+  });
+
+  const target = 'Waller Creek';
+  assert.equal(await resolveAnnotationTarget({ viewer: closeViewportViewer(), target }), null);
+  const duringOutage = requests.length;
+
+  photonReachable = true;
+  const retried = await resolveAnnotationTarget({ viewer: closeViewportViewer(), target });
+
+  assert.ok(retried, 'the same target must resolve once the network is back');
+  assert.deepEqual([retried.lat, retried.lon], [30.2665, -97.7385]);
+  assert.ok(
+    requests.length > duringOutage,
+    'the retry was served from a poisoned cache instead of asking again',
+  );
+});
+
+test('a not-found is remembered only when every source consulted gave a verdict', async () => {
+  // The full truth table, because the no-key row is the one the behavioural
+  // tests above cannot reach: `import.meta.env` only exists under Vite, so
+  // `node --test` can never take the branch that skips Google entirely.
+  const cases = [
+    // no key: Photon is the only source, so Photon alone decides
+    [{ googleConsulted: false, photonAnswered: true }, true],
+    [{ googleConsulted: false, photonAnswered: false }, false],
+    // with a key: Google must have said "no such place", AND Photon must have replied
+    [{ googleConsulted: true, googleSaysNoSuchPlace: true, photonAnswered: true }, true],
+    [{ googleConsulted: true, googleSaysNoSuchPlace: true, photonAnswered: false }, false],
+    // Google declined (REQUEST_DENIED / OVER_QUERY_LIMIT) — never a verdict
+    [{ googleConsulted: true, googleSaysNoSuchPlace: false, photonAnswered: true }, false],
+    [{ googleConsulted: true, googleSaysNoSuchPlace: false, photonAnswered: false }, false],
+  ];
+  for (const [sources, expected] of cases) {
+    const providers = [sources.googleConsulted ? Boolean(sources.googleSaysNoSuchPlace) : true, sources.photonAnswered]
+      .map((answered) => ({ geocode: async () => ({ place: null, answered }) }));
+    assert.equal((await createPlaceSearch({ providers }).geocode('miss')).answered, expected, JSON.stringify(sources));
+  }
+  // An omitted Google verdict defaults to "did not say no such place".
+
+});
+
+function resolveAnnotationTarget(options) {
+  return resolveTarget({ placeSearch: createStandalonePlaceSearch({ resolveApiKey: () => globalThis.window?.__GOOGLE_MAPS_API_KEY__ }), ...options });
+}

src/annotations/drawMode.js

@@ -0,0 +1,307 @@
+import { t, tn } from '../i18n/index.js';
+
+/**
+ * Manual whiteboard drawing: the pure half.
+ *
+ * The voice whiteboard resolves NAMES to geometry. This module is for the other
+ * way in: a person clicks the vertices themselves. It holds a draw session (the
+ * shape being drawn and its vertices), decides when a shape is finishable, and
+ * turns a finished session into the SAME annotation spec the engine already
+ * accepts (`type: area | route | pin`, geometry supplied, `manual: true`), so a
+ * hand-drawn mark renders, persists, de-dups and clears exactly like a spoken
+ * one.
+ *
+ * A vertex is a lon/lat and nothing more. The world renderer drapes every mark
+ * onto the photoreal surface (`clampToGround` + `CESIUM_3D_TILE`), so there is
+ * no such thing as a vertex at a height here: the height under the click is
+ * used for the live preview and is deliberately dropped at finish.
+ *
+ * No Cesium, no DOM — importable under `node --test`. The Cesium/DOM half is
+ * `drawTool.js`.
+ */
+
+import { greatCircleMeters } from '../geoDistance.js';
+import { formatDistanceText } from '../data/distanceFormat.js';
+
+export const DRAW_SHAPES = Object.freeze(['area', 'line', 'pin']);
+export const MIN_VERTICES = Object.freeze({ area: 3, line: 2, pin: 1 });
+/**
+ * Hard ceiling on vertices in one shape. Every vertex is a live preview entity
+ * and a position in the finished geometry, so a stuck mouse button or a script
+ * must not be able to grow one shape without limit.
+ */
+export const MAX_VERTICES = 512;
+/** Two clicks closer than this are one vertex: a double-click to finish must not add a stray point. */
+const MIN_VERTEX_SEPARATION_M = 0.5;
+/** A line shorter than this, or an area thinner than this, is a mis-click rather than a shape. */
+const MIN_PATH_LENGTH_M = 1;
+const MIN_AREA_M2 = 1;
+
+/** @param {string} shape @returns {'area'|'line'|'pin'} */
+export function normalizeShape(shape) {
+  const s = String(shape || '').toLowerCase();
+  if (s === 'line' || s === 'path' || s === 'route') return 'line';
+  if (s === 'pin' || s === 'point' || s === 'marker') return 'pin';
+  return 'area';
+}
+
+/** @param {string} [shape] @returns {{shape: 'area'|'line'|'pin', vertices: Array<{lon:number, lat:number, height?:number}>}} */
+export function createDrawSession(shape = 'area') {
+  return { shape: normalizeShape(shape), vertices: [] };
+}
+
+/** Great-circle distance in metres between two {lon, lat} points. */
+function greatCircleM(a, b) {
+  return greatCircleMeters(a, b);
+}
+
+/**
+ * Add a vertex. A vertex that is not a finite lon/lat is refused; one within
+ * MIN_VERTEX_SEPARATION_M of the previous vertex is treated as the same click
+ * (the second half of a double-click) and refused as a duplicate. A pin holds
+ * exactly one vertex: a later click moves it.
+ * @returns {{added: boolean, reason?: 'invalid'|'duplicate'}}
+ */
+export function addVertex(
+  session,
+  vertex,
+  { minSeparationM = MIN_VERTEX_SEPARATION_M } = {},
+) {
+  if (!session || !isFiniteCoordinate(vertex))
+    return { added: false, reason: 'invalid' };
+  const v = {
+    lon: vertex.lon,
+    lat: vertex.lat,
+    height: Number.isFinite(vertex.height) ? vertex.height : 0,
+  };
+  if (session.shape === 'pin') {
+    session.vertices = [v];
+    return { added: true };
+  }
+  if (session.vertices.length >= MAX_VERTICES)
+    return { added: false, reason: 'full' };
+  const last = session.vertices[session.vertices.length - 1];
+  if (last && greatCircleM(last, v) < minSeparationM)
+    return { added: false, reason: 'duplicate' };
+  session.vertices.push(v);
+  return { added: true };
+}
+
+/** A usable click position: finite, and on the globe rather than past its edges. */
+export function isFiniteCoordinate(vertex) {
+  if (!vertex) return false;
+  const { lon, lat } = vertex;
+  return (
+    Number.isFinite(lon) &&
+    Number.isFinite(lat) &&
+    Math.abs(lon) <= 180 &&
+    Math.abs(lat) <= 90
+  );
+}
+
+/** Remove the last vertex. @returns {boolean} whether one was removed */
+export function removeLastVertex(session) {
+  if (!session?.vertices?.length) return false;
+  session.vertices.pop();
+  return true;
+}
+
+/**
+ * Why a session can or cannot become an annotation.
+ * - `too-few`: not enough vertices yet.
+ * - `degenerate`: enough vertices, but they describe nothing — three collinear
+ *   points enclose no area, and a line that doubles back on itself has no
+ *   length. Drawing one of those and calling it a mark would put an invisible
+ *   entity on the board that the person cannot see, select or explain.
+ * @returns {'ok'|'too-few'|'degenerate'|'invalid'}
+ */
+export function finishReason(session) {
+  if (!session || !Array.isArray(session.vertices)) return 'invalid';
+  if (session.vertices.some((vertex) => !isFiniteCoordinate(vertex)))
+    return 'invalid';
+  if (session.vertices.length < (MIN_VERTICES[session.shape] || 1))
+    return 'too-few';
+  if (
+    session.shape === 'line' &&
+    pathLengthM(session.vertices) < MIN_PATH_LENGTH_M
+  )
+    return 'degenerate';
+  if (session.shape === 'area' && ringAreaM2(session.vertices) < MIN_AREA_M2)
+    return 'degenerate';
+  return 'ok';
+}
+
+/** @returns {boolean} whether the session can become an annotation right now */
+export function canFinish(session) {
+  return finishReason(session) === 'ok';
+}
+
+/** Length of an open path in metres. */
+export function pathLengthM(vertices) {
+  let m = 0;
+  for (let i = 1; i < (vertices?.length || 0); i += 1)
+    m += greatCircleM(vertices[i - 1], vertices[i]);
+  return m;
+}
+
+/**
+ * The same vertices with longitudes made CONTINUOUS relative to the first one,
+ * so planar maths does not tear at the antimeridian. A small shape straddling
+ * 180° has longitudes like [179.999, -179.999]; subtracting those raw gives
+ * 359.998° of width instead of 0.002°, which is how a 25,000 m² rectangle
+ * measured 4,461 km² and reported its centre on the Greenwich meridian.
+ *
+ * Values may leave the [-180, 180] range on purpose — that is what "continuous"
+ * means. Re-wrap with `wrapLongitude` before handing one back as a coordinate.
+ * @param {Array<{lon:number, lat:number}>} vertices
+ */
+export function unwrapLongitudes(vertices) {
+  if (!vertices?.length) return [];
+  const reference = vertices[0].lon;
+  return vertices.map((vertex) => {
+    let lon = vertex.lon;
+    while (lon - reference > 180) lon -= 360;
+    while (lon - reference < -180) lon += 360;
+    return { ...vertex, lon };
+  });
+}
+
+/** A continuous longitude brought back into [-180, 180]. */
+export function wrapLongitude(lon) {
+  if (!Number.isFinite(lon)) return lon;
+  // A value already in range is returned UNCHANGED rather than pushed through
+  // the modulo, which is only exact in binary for some inputs: 0.0005 came back
+  // as 0.0004999999999881766. The seam is the only place the arithmetic is
+  // needed, so it is the only place that pays for it.
+  if (lon >= -180 && lon < 180) return lon;
+  const value = ((((lon + 180) % 360) + 360) % 360) - 180;
+  return Object.is(value, -0) ? 0 : value;
+}
+
+/** Planar shoelace area of a ring in square metres (local metre grid; fine at whiteboard scale). */
+export function ringAreaM2(vertices) {
+  if (!vertices || vertices.length < 3) return 0;
+  const ring = unwrapLongitudes(vertices);
+  const lat0 = ring.reduce((s, v) => s + v.lat, 0) / ring.length;
+  const kx = 111320 * Math.cos((lat0 * Math.PI) / 180);
+  const ky = 111320;
+  let twice = 0;
+  for (let i = 0; i < ring.length; i += 1) {
+    const a = ring[i];
+    const b = ring[(i + 1) % ring.length];
+    twice += a.lon * kx * (b.lat * ky) - b.lon * kx * (a.lat * ky);
+  }
+  return Math.abs(twice) / 2;
+}
+
+/** Vertex-average centroid of a ring, {lon, lat}, safe across the antimeridian. */
+export function ringCentroid(vertices) {
+  if (!vertices?.length) return null;
+  const ring = unwrapLongitudes(vertices);
+  return {
+    lon: wrapLongitude(ring.reduce((s, v) => s + v.lon, 0) / ring.length),
+    lat: ring.reduce((s, v) => s + v.lat, 0) / ring.length,
+  };
+}
+
+/** Distance or area, formatted for a label suffix. */
+export function formatMeasure(session) {
+  if (!session) return '';
+  if (session.shape === 'line') {
+    return formatDistanceText(pathLengthM(session.vertices)) ?? '';
+  }
+  if (session.shape === 'area') {
+    const m2 = ringAreaM2(session.vertices);
+    // Round before each unit cut, as for a line. 9,999.6 m² was "10000 m²".
+    const whole = Math.round(m2);
+    const ha = (m2 / 1e4).toFixed(1);
+    if (whole < 1e4) return `${whole} m²`;
+    if (Number(ha) < 100) return `${ha} ha`;
+    return `${(m2 / 1e6).toFixed(2)} km²`;
+  }
+  return '';
+}
+
+/**
+ * The annotation spec for a finished session, in the shape `annotationEngine.annotate()`
+ * takes. Null when the session cannot finish. Geometry is supplied outright and
+ * `manual: true` tells the engine to skip name resolution.
+ *
+ * The per-vertex height from the click is dropped here, deliberately and in one
+ * place: the world renderer drapes areas and routes onto the photoreal surface,
+ * so a height carried this far would be discarded further downstream instead,
+ * silently. What the person gets is the outline they drew, lying on the
+ * surface under it.
+ * @param {object} session
+ * @param {{label?: string, color?: string}} [opts]
+ */
+export function finishSpec(session, { label = '', color = 'primary' } = {}) {
+  if (!canFinish(session)) return null;
+  const text = String(label || '').trim();
+  const pts = session.vertices.map((v) => [v.lon, v.lat]);
+  if (session.shape === 'area') {
+    // CLOSED explicitly. A polygon fill closes itself, but the outline beside it
+    // is a polyline, and an open ring draws every edge except the one back to
+    // the first vertex — the shape reads as a shape with one side missing.
+    return {
+      type: 'area',
+      manual: true,
+      ring: closeRing(pts),
+      label: text || null,
+      color,
+    };
+  }
+  if (session.shape === 'line') {
+    return {
+      type: 'route',
+      manual: true,
+      path: pts,
+      label: text || null,
+      color,
+    };
+  }
+  const [lon, lat] = pts[0];
+  return {
+    type: 'pin',
+    manual: true,
+    latitude: lat,
+    longitude: lon,
+    label: text || null,
+    color,
+  };
+}
+
+/** A ring whose last position repeats its first, so an outline has no gap. */
+export function closeRing(pairs) {
+  if (!Array.isArray(pairs) || pairs.length < 3) return pairs;
+  const [firstLon, firstLat] = pairs[0];
+  const [lastLon, lastLat] = pairs[pairs.length - 1];
+  if (firstLon === lastLon && firstLat === lastLat) return pairs;
+  return [...pairs, [firstLon, firstLat]];
+}
+
+/** One line of guidance for the person drawing, by state. */
+export function drawHint(session) {
+  if (!session) return t('Pick a shape, then click the map.');
+  const n = session.vertices.length;
+  if (session.shape === 'pin')
+    return n
+      ? t('Enter to place the pin, Esc to cancel.')
+      : t('Click where the pin goes.');
+  const need = MIN_VERTICES[session.shape] - n;
+  if (need > 0)
+    return tn(need, 'Click {count} more point.', 'Click {count} more points.');
+  if (finishReason(session) === 'degenerate') {
+    return session.shape === 'area'
+      ? t('Those points are in a line — move one off it to enclose an area.')
+      : t('That line has no length — click somewhere further away.');
+  }
+  const full =
+    n >= MAX_VERTICES
+      ? t(' · {max}-point limit reached', { max: MAX_VERTICES })
+      : '';
+  return t(
+    '{measure} · double-click or Enter to finish, Backspace undoes, Esc cancels.{full}',
+    { measure: formatMeasure(session), full },
+  );
+}

src/annotations/drawMode.test.mjs

@@ -0,0 +1,395 @@
+// Pure tests for the manual draw session. Run with: npm test (node --test). No Cesium, no DOM.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createDrawSession,
+  addVertex,
+  removeLastVertex,
+  canFinish,
+  finishSpec,
+  normalizeShape,
+  pathLengthM,
+  ringAreaM2,
+  ringCentroid,
+  formatMeasure,
+  drawHint,
+  finishReason,
+  isFiniteCoordinate,
+  closeRing,
+  unwrapLongitudes,
+  wrapLongitude,
+  MAX_VERTICES,
+  MIN_VERTICES,
+} from './drawMode.js';
+
+test('shapes normalize to area, line or pin, and unknown words fall back to area', () => {
+  assert.equal(normalizeShape('route'), 'line');
+  assert.equal(normalizeShape('marker'), 'pin');
+  assert.equal(normalizeShape('polygon'), 'area');
+  assert.equal(normalizeShape(undefined), 'area');
+});
+
+test('an area needs three vertices, a line two, a pin one', () => {
+  const area = createDrawSession('area');
+  addVertex(area, { lon: -97.74, lat: 30.27 });
+  addVertex(area, { lon: -97.73, lat: 30.27 });
+  assert.equal(canFinish(area), false);
+  addVertex(area, { lon: -97.73, lat: 30.28 });
+  assert.equal(canFinish(area), true);
+  assert.equal(MIN_VERTICES.line, 2);
+  assert.equal(MIN_VERTICES.pin, 1);
+});
+
+test('a second click within half a metre is the tail of a double-click, not a vertex', () => {
+  const line = createDrawSession('line');
+  assert.deepEqual(addVertex(line, { lon: 0, lat: 0 }), { added: true });
+  assert.deepEqual(addVertex(line, { lon: 0.000001, lat: 0 }), {
+    added: false,
+    reason: 'duplicate',
+  });
+  assert.deepEqual(addVertex(line, { lon: 'x', lat: 0 }), {
+    added: false,
+    reason: 'invalid',
+  });
+  assert.equal(line.vertices.length, 1);
+});
+
+test('a pin keeps exactly one vertex: a later click moves it', () => {
+  const pin = createDrawSession('pin');
+  addVertex(pin, { lon: 1, lat: 1 });
+  addVertex(pin, { lon: 2, lat: 2 });
+  assert.equal(pin.vertices.length, 1);
+  assert.deepEqual(pin.vertices[0], { lon: 2, lat: 2, height: 0 });
+});
+
+test('backspace removes the last vertex and reports whether it did', () => {
+  const s = createDrawSession('line');
+  assert.equal(removeLastVertex(s), false);
+  addVertex(s, { lon: 0, lat: 0 });
+  assert.equal(removeLastVertex(s), true);
+  assert.equal(s.vertices.length, 0);
+});
+
+test('finishSpec yields the engine spec shapes with manual geometry, or null when unfinished', () => {
+  const area = createDrawSession('area');
+  assert.equal(finishSpec(area), null);
+  [
+    [-97.74, 30.27],
+    [-97.73, 30.27],
+    [-97.73, 30.28],
+  ].forEach(([lon, lat]) => addVertex(area, { lon, lat }));
+  assert.deepEqual(finishSpec(area, { label: ' Zilker ', color: 'amber' }), {
+    type: 'area',
+    manual: true,
+    // CLOSED: the last position repeats the first so the outline polyline
+    // draws all three sides of the triangle, not two.
+    ring: [
+      [-97.74, 30.27],
+      [-97.73, 30.27],
+      [-97.73, 30.28],
+      [-97.74, 30.27],
+    ],
+    label: 'Zilker',
+    color: 'amber',
+  });
+  const line = createDrawSession('line');
+  addVertex(line, { lon: 0, lat: 0 });
+  addVertex(line, { lon: 0.01, lat: 0 });
+  assert.deepEqual(finishSpec(line), {
+    type: 'route',
+    manual: true,
+    path: [
+      [0, 0],
+      [0.01, 0],
+    ],
+    label: null,
+    color: 'primary',
+  });
+  const pin = createDrawSession('pin');
+  addVertex(pin, { lon: 151.2, lat: -33.9 });
+  assert.deepEqual(finishSpec(pin, { label: 'A shed' }), {
+    type: 'pin',
+    manual: true,
+    latitude: -33.9,
+    longitude: 151.2,
+    label: 'A shed',
+    color: 'primary',
+  });
+});
+
+test('length and area come out in metres on a local grid', () => {
+  const km = pathLengthM([
+    { lon: 0, lat: 0 },
+    { lon: 0, lat: 0.009 },
+  ]);
+  assert.ok(km > 990 && km < 1010, `1 km of latitude, got ${km}`);
+  const square = [
+    { lon: 0, lat: 0 },
+    { lon: 0.001, lat: 0 },
+    { lon: 0.001, lat: 0.001 },
+    { lon: 0, lat: 0.001 },
+  ];
+  const m2 = ringAreaM2(square);
+  assert.ok(m2 > 12000 && m2 < 12800, `~111 m square, got ${m2}`);
+  assert.deepEqual(ringCentroid(square), { lon: 0.0005, lat: 0.0005 });
+});
+
+test('the measure and the hint follow the shape and the vertex count', () => {
+  const area = createDrawSession('area');
+  assert.equal(drawHint(area), 'Click 3 more points.');
+  [
+    { lon: 0, lat: 0 },
+    { lon: 0.01, lat: 0 },
+    { lon: 0.01, lat: 0.01 },
+  ].forEach((v) => addVertex(area, v));
+  assert.match(formatMeasure(area), /ha$|km²$|m²$/);
+  assert.match(drawHint(area), /double-click or Enter to finish/);
+  const pin = createDrawSession('pin');
+  assert.equal(drawHint(pin), 'Click where the pin goes.');
+  assert.equal(drawHint(null), 'Pick a shape, then click the map.');
+});
+
+test('a vertex must be a finite coordinate on the globe', () => {
+  assert.equal(isFiniteCoordinate({ lon: 12, lat: -4 }), true);
+  assert.equal(isFiniteCoordinate({ lon: 0, lat: 90 }), true);
+  for (const bad of [
+    null,
+    {},
+    { lon: NaN, lat: 0 },
+    { lon: 0, lat: Infinity },
+    { lon: 181, lat: 0 },
+    { lon: 0, lat: -90.5 },
+    { lon: '10', lat: 10 },
+  ]) {
+    assert.equal(isFiniteCoordinate(bad), false, JSON.stringify(bad));
+  }
+  const line = createDrawSession('line');
+  assert.deepEqual(addVertex(line, { lon: 200, lat: 0 }), {
+    added: false,
+    reason: 'invalid',
+  });
+  assert.equal(line.vertices.length, 0);
+});
+
+test('one shape holds at most MAX_VERTICES points', () => {
+  const line = createDrawSession('line');
+  for (let i = 0; i < MAX_VERTICES + 25; i += 1)
+    addVertex(line, { lon: i * 0.001, lat: 0 });
+  assert.equal(line.vertices.length, MAX_VERTICES);
+  assert.deepEqual(addVertex(line, { lon: 99, lat: 1 }), {
+    added: false,
+    reason: 'full',
+  });
+  assert.match(drawHint(line), /512-point limit reached/);
+
+  // A pin replaces its one vertex forever: the ceiling cannot strand it.
+  const pin = createDrawSession('pin');
+  for (let i = 0; i < MAX_VERTICES + 5; i += 1)
+    assert.equal(addVertex(pin, { lon: i * 0.01, lat: 0 }).added, true);
+  assert.equal(pin.vertices.length, 1);
+});
+
+test('a shape that encloses nothing is refused, with a reason', () => {
+  // Three points on one meridian are not an area.
+  const collinear = createDrawSession('area');
+  for (const lat of [0, 0.001, 0.002]) addVertex(collinear, { lon: 0, lat });
+  assert.equal(collinear.vertices.length, 3);
+  assert.equal(finishReason(collinear), 'degenerate');
+  assert.equal(canFinish(collinear), false);
+  assert.equal(finishSpec(collinear), null);
+  assert.match(drawHint(collinear), /in a line/);
+
+  // Moving one point off that line makes it a shape again.
+  collinear.vertices[2].lon = 0.001;
+  assert.equal(finishReason(collinear), 'ok');
+  assert.ok(finishSpec(collinear));
+
+  // A line whose two ends are a handful of centimetres apart has no length.
+  const stub = createDrawSession('line');
+  addVertex(stub, { lon: 0, lat: 0 });
+  addVertex(stub, { lon: 0.000007, lat: 0 }, { minSeparationM: 0.01 });
+  assert.equal(stub.vertices.length, 2);
+  assert.equal(finishReason(stub), 'degenerate');
+  assert.equal(finishSpec(stub), null);
+  assert.match(drawHint(stub), /no length/);
+
+  // And the states in between are named, not lumped together.
+  assert.equal(finishReason(createDrawSession('area')), 'too-few');
+  assert.equal(finishReason(null), 'invalid');
+});
+
+test('a finished area is a CLOSED ring, so its outline has no missing side', () => {
+  const area = createDrawSession('area');
+  for (const [lon, lat] of [
+    [-97.74, 30.27],
+    [-97.73, 30.27],
+    [-97.73, 30.28],
+  ])
+    addVertex(area, { lon, lat });
+
+  const spec = finishSpec(area);
+  assert.equal(
+    spec.ring.length,
+    4,
+    'three clicked vertices become four ring positions',
+  );
+  assert.deepEqual(
+    spec.ring.at(-1),
+    spec.ring[0],
+    'the last position repeats the first',
+  );
+  // The renderer draws the outline as a polyline over exactly these positions:
+  // an open ring would draw two of the triangle's three sides.
+  assert.equal(spec.ring.length - 1, area.vertices.length);
+
+  // A line is NOT closed — it is a path, and joining its ends would invent a
+  // segment the person never drew.
+  const line = createDrawSession('line');
+  addVertex(line, { lon: 0, lat: 0 });
+  addVertex(line, { lon: 0.01, lat: 0 });
+  assert.equal(finishSpec(line).path.length, 2);
+
+  // closeRing is idempotent: finishing an already-closed ring adds nothing.
+  const closed = closeRing([
+    [0, 0],
+    [1, 0],
+    [1, 1],
+    [0, 0],
+  ]);
+  assert.equal(closed.length, 4);
+});
+
+test('a shape straddling the antimeridian measures what it looks like', () => {
+  // 0.002 degrees square at the equator — about 223 m a side, so ~49,600 m2 —
+  // sitting across 180. Raw longitude arithmetic reads that 0.002-degree width
+  // as 359.998 degrees: the area came out in the thousands of square
+  // kilometres and the centroid landed on the Greenwich meridian, half a world
+  // from the shape it belongs to.
+  const rectangle = [
+    { lon: 179.999, lat: -0.001 },
+    { lon: -179.999, lat: -0.001 },
+    { lon: -179.999, lat: 0.001 },
+    { lon: 179.999, lat: 0.001 },
+  ];
+  const area = ringAreaM2(rectangle);
+  assert.ok(
+    area > 45_000 && area < 55_000,
+    `a ~223 m x ~223 m patch is ~49,600 m2, got ${Math.round(area)} m2`,
+  );
+  assert.ok(area < 1e6, 'and nowhere near a square kilometre');
+
+  const centre = ringCentroid(rectangle);
+  assert.ok(
+    Math.abs(Math.abs(centre.lon) - 180) < 0.01,
+    `the centre belongs on the antimeridian, got lon ${centre.lon}`,
+  );
+  assert.ok(Math.abs(centre.lat) < 0.01, `got lat ${centre.lat}`);
+
+  // Length was already safe — haversine is periodic in the longitude delta —
+  // and this pins that so a "fix" cannot break it.
+  const across = pathLengthM([
+    { lon: 179.999, lat: 0 },
+    { lon: -179.999, lat: 0 },
+  ]);
+  assert.ok(
+    across > 150 && across < 300,
+    `about 222 m, got ${Math.round(across)} m`,
+  );
+
+  // The same shape away from the seam still measures the same.
+  const inland = rectangle.map((v) => ({ lon: v.lon - 179.999, lat: v.lat }));
+  assert.ok(
+    Math.abs(ringAreaM2(inland) - area) < 1,
+    'position must not change size',
+  );
+
+  // And the ordinary case is untouched.
+  const austin = [
+    { lon: -97.75, lat: 30.26 },
+    { lon: -97.74, lat: 30.26 },
+    { lon: -97.74, lat: 30.27 },
+  ];
+  const centroid = ringCentroid(austin);
+  assert.ok(Math.abs(centroid.lon + 97.7433) < 0.001);
+  assert.ok(Math.abs(centroid.lat - 30.2633) < 0.001);
+});
+
+test('longitude unwrapping is continuous and re-wraps to one canonical range', () => {
+  const unwrapped = unwrapLongitudes([
+    { lon: 179.9, lat: 0 },
+    { lon: -179.9, lat: 0 },
+  ]);
+  assert.equal(unwrapped[0].lon, 179.9);
+  assert.ok(
+    Math.abs(unwrapped[1].lon - 180.1) < 1e-9,
+    `continuous neighbour, got ${unwrapped[1].lon}`,
+  );
+  assert.equal(wrapLongitude(180.1).toFixed(4), (-179.9).toFixed(4));
+  assert.equal(wrapLongitude(-190), 170);
+  assert.equal(wrapLongitude(10), 10);
+  assert.equal(wrapLongitude(180), -180);
+  assert.equal(unwrapLongitudes([]).length, 0);
+});
+
+test('a line that rounds up to a kilometre reads 1.0 km, not 1000 m', () => {
+  const metresPerDegree = (6371.0088 * 1000 * Math.PI) / 180;
+  const lat = 999.6 / metresPerDegree;
+  const line = createDrawSession('line');
+  addVertex(line, { lon: 0, lat: 0 });
+  addVertex(line, { lon: 0, lat });
+  const metres = pathLengthM(line.vertices);
+  assert.ok(
+    metres >= 999.5 && metres < 1000,
+    `length should round to 1000 m, got ${metres}`,
+  );
+  assert.equal(formatMeasure(line), '1.0 km');
+  assert.match(drawHint(line), /^1\.0 km · /);
+});
+
+test('a line that rounds to 10.0 km reads in whole kilometres', () => {
+  const metresPerDegree = (6371.0088 * 1000 * Math.PI) / 180;
+  const line = createDrawSession('line');
+  addVertex(line, { lon: 0, lat: 0 });
+  addVertex(line, { lon: 0, lat: 9960 / metresPerDegree });
+  assert.equal(formatMeasure(line), '10 km');
+});
+
+test('an area that rounds up to the next unit reads in that unit', () => {
+  // A square on the equator whose shoelace area is about `m2`.
+  const square = (m2) => {
+    const side = Math.sqrt(m2) / 111320;
+    const area = createDrawSession('area');
+    for (const [lon, lat] of [
+      [0, 0],
+      [side, 0],
+      [side, side],
+      [0, side],
+    ])
+      addVertex(area, { lon, lat });
+    return area;
+  };
+  const almostHectare = square(9999.6);
+  const metres = ringAreaM2(almostHectare.vertices);
+  assert.ok(
+    metres >= 9999.5 && metres < 1e4,
+    `area should round to 10000 m², got ${metres}`,
+  );
+  assert.equal(formatMeasure(almostHectare), '1.0 ha');
+  assert.match(drawHint(almostHectare), /^1\.0 ha · /);
+  assert.equal(formatMeasure(square(9999.4)), '9999 m²');
+  // Pin the shoelace area too, so a geodesy change fails here and not as a unit.
+  const almostKm2 = square(999_960);
+  const nearKm2 = ringAreaM2(almostKm2.vertices);
+  assert.ok(
+    nearKm2 >= 999_500 && nearKm2 < 1e6,
+    `area should round to 100.0 ha, got ${nearKm2}`,
+  );
+  assert.equal(formatMeasure(almostKm2), '1.00 km²');
+  const under = square(999_400);
+  const underM2 = ringAreaM2(under.vertices);
+  assert.ok(
+    underM2 >= 998_500 && underM2 < 999_500,
+    `area should round to 99.9 ha, got ${underM2}`,
+  );
+  assert.equal(formatMeasure(under), '99.9 ha');
+});

src/annotations/drawTool.js

@@ -0,0 +1,561 @@
+/**
+ * Manual whiteboard drawing: the Cesium + DOM half.
+ *
+ * DISPLAY ▸ Draw turns the globe into a whiteboard you draw on by hand: pick a
+ * shape (area, line or pin), click the vertices on the real world, double-click
+ * or press Enter to finish, type a label. Each finished shape goes through the
+ * SAME `annotationEngine.annotate()` the voice agent uses, with its geometry
+ * supplied and `manual: true`, so it renders with the whiteboard look,
+ * persists, de-dups, shows up in `.list()`, and clears with the board.
+ *
+ * Two ownership rules make it safe to share the scene with the layers:
+ *
+ * - While a session is open the tool HOLDS THE POINTER
+ *   (`src/data/inputOwnership.js`), and every ambient selection handler yields,
+ *   so a vertex clicked on top of an aircraft or a camera is a vertex and
+ *   nothing else. It is one claim consulted by all of them, not a list of
+ *   exceptions inside each.
+ * - Cesium's Viewer binds its OWN left click (select the entity under the
+ *   pointer) and double click (track it) on the viewer's handler, outside every
+ *   layer and therefore outside the shared claim. Both are borrowed for the
+ *   session and given back on the way out, and `destroy()` gives back every
+ *   listener, the Cesium handler, the preview data source and the window
+ *   handle, so the tool can be turned off or the shell disposed without leaving
+ *   anything behind.
+ *
+ * A vertex carries the height the click landed on — a roof, a hillside — and
+ * that height is what the live preview hangs on, so the rubber band follows the
+ * surface under the pointer instead of sinking to sea level. The world renderer
+ * drapes finished areas and routes onto the surface, so the height is dropped
+ * at finish, deliberately and in one place — see `finishSpec` in drawMode.js.
+ */
+import * as Cesium from 'cesium';
+import { pickWorldFromScreen } from './annotationResolver.js';
+import {
+  claimPointer,
+  pointerOwner,
+  releasePointer,
+} from '../data/inputOwnership.js';
+import { pointerOwnerName } from '../data/pointerOwnerNames.js';
+import {
+  DRAW_SHAPES,
+  MAX_VERTICES,
+  addVertex,
+  createDrawSession,
+  drawHint,
+  finishReason,
+  finishSpec,
+  normalizeShape,
+  removeLastVertex,
+} from './drawMode.js';
+
+import { onLocaleChange, t, translateKnown } from '../i18n/index.js';
+/** The id this tool claims the pointer under. */
+const DRAW_POINTER_OWNER = 'draw';
+const PREVIEW_DATA_SOURCE_NAME = 'gev-draw-preview';
+
+const COLORS = ['primary', 'amber', 'cyan', 'green', 'red'];
+const PREVIEW = {
+  primary: '#8be9ff',
+  amber: '#ffb547',
+  cyan: '#39d0ff',
+  green: '#5dff9f',
+  red: '#ff6b6b',
+};
+
+/**
+ * Run the Draw control. Returns a handle with a `destroy()` the application
+ * lifetime owns, plus the console/test seam (`window.__gevDrawTool`).
+ * The tool hands what the controls show (`{ active, shape, color, label,
+ * hint }`) to `publish`, which the view renders, and answers the controls
+ * through the actions it gives `connect`, which returns their disconnect.
+ * @param {{viewer: Cesium.Viewer, annotations: {annotate: Function, clear: Function}, publish?: Function, connect?: Function}} deps
+ * @returns {{destroy: Function}|null}
+ */
+export function initDrawTool({
+  viewer,
+  annotations,
+  publish = () => {},
+  connect = () => () => {},
+}) {
+  // A page without the Draw controls (the Display controls view omitted) has
+  // no draw tool.
+  if (!viewer || !annotations || !document.getElementById('draw-toggle'))
+    return null;
+
+  let active = false;
+  let destroyed = false;
+  let session = null;
+  let shape = 'area';
+  let color = 'primary';
+  let label = '';
+  let hint = '';
+  let handler = null;
+  let lease = null;
+  let savedDoubleClick = null;
+  let savedSingleClick = null;
+  let cursor = null; // last mouse position on the canvas, for the rubber band
+  // Bumped by anything that supersedes an in-flight finish: cancelling, clearing
+  // the board, leaving draw mode, teardown. An `annotate()` that resolves after
+  // one of those must not write its outcome over the newer state.
+  let generation = 0;
+  const previewEntities = [];
+  // Every DOM listener this tool adds (the session's keydown), so teardown is
+  // one loop rather than a list that can fall out of step with the bindings.
+  const domListeners = [];
+  const listen = (target, type, listener, options) => {
+    target.addEventListener(type, listener, options);
+    domListeners.push([target, type, listener, options]);
+  };
+
+  const dataSource = new Cesium.CustomDataSource(PREVIEW_DATA_SOURCE_NAME);
+  // `add()` resolves on the NEXT tick, so an init-then-immediate-destroy would
+  // remove a source that had not been attached yet and leave the attachment to
+  // land afterwards — a preview data source nobody owns. Chain the removal onto
+  // the attachment instead of racing it.
+  let attaching = Promise.resolve(viewer.dataSources.add(dataSource)).catch(
+    () => null,
+  );
+
+  const present = () => publish({ active, shape, color, label, hint });
+  // The hint is kept as the call that words it, so a language switch can
+  // word it again.
+  let hintText = () => '';
+  const setHint = (text) => {
+    hintText = text;
+    hint = text();
+    present();
+  };
+  const offLocale = onLocaleChange(() => {
+    if (!destroyed) setHint(hintText);
+  });
+
+  // ---- preview ---------------------------------------------------------
+  const vertexPositions = () =>
+    session.vertices.map((v) =>
+      Cesium.Cartesian3.fromDegrees(v.lon, v.lat, v.height || 0),
+    );
+  const previewLine = dataSource.entities.add({
+    show: false,
+    polyline: {
+      positions: new Cesium.CallbackProperty(() => {
+        if (!session) return [];
+        const pts = vertexPositions();
+        if (cursor && session.shape !== 'pin') pts.push(cursor);
+        if (session.shape === 'area' && pts.length >= 3) pts.push(pts[0]);
+        return pts;
+      }, false),
+      width: 3,
+      material: new Cesium.PolylineDashMaterialProperty({
+        color: Cesium.Color.fromCssColorString(PREVIEW.primary).withAlpha(0.9),
+        dashLength: 16,
+      }),
+      depthFailMaterial: new Cesium.PolylineDashMaterialProperty({
+        color: Cesium.Color.fromCssColorString(PREVIEW.primary).withAlpha(0.35),
+        dashLength: 16,
+      }),
+      clampToGround: false,
+    },
+  });
+  const syncPreview = () => {
+    if (destroyed) return;
+    previewEntities.forEach((e) => dataSource.entities.remove(e));
+    previewEntities.length = 0;
+    if (!session) {
+      previewLine.show = false;
+      setHint(() => drawHint(null));
+      viewer.scene.requestRender();
+      return;
+    }
+    const stroke = Cesium.Color.fromCssColorString(
+      PREVIEW[color] || PREVIEW.primary,
+    );
+    previewLine.polyline.material = new Cesium.PolylineDashMaterialProperty({
+      color: stroke.withAlpha(0.9),
+      dashLength: 16,
+    });
+    previewLine.show = session.shape !== 'pin';
+    for (const v of session.vertices) {
+      previewEntities.push(
+        dataSource.entities.add({
+          position: Cesium.Cartesian3.fromDegrees(v.lon, v.lat, v.height || 0),
+          point: {
+            pixelSize: 8,
+            color: stroke,
+            outlineColor: Cesium.Color.BLACK.withAlpha(0.6),
+            outlineWidth: 2,
+            disableDepthTestDistance: Number.POSITIVE_INFINITY,
+          },
+        }),
+      );
+    }
+    setHint(() => drawHint(session));
+    viewer.scene.requestRender();
+  };
+
+  // ---- vertices from clicks --------------------------------------------
+  const worldAt = (position) => {
+    const canvas = viewer.scene.canvas;
+    const w = canvas.clientWidth || canvas.width || 1;
+    const h = canvas.clientHeight || canvas.height || 1;
+    return pickWorldFromScreen(viewer, position.x / w, position.y / h);
+  };
+  const onClick = (event) => {
+    if (!session || destroyed) return;
+    const p = worldAt(event.position);
+    if (!p) return;
+    const { added, reason } = addVertex(session, p);
+    if (added) {
+      syncPreview();
+      return;
+    }
+    // A click that changed nothing still deserves an answer when the reason is
+    // a limit rather than the harmless tail of a double-click.
+    if (reason === 'full')
+      setHint(() =>
+        t(
+          'That shape already has {count} points — finish it or press Backspace.',
+          { count: MAX_VERTICES },
+        ),
+      );
+    else if (reason === 'invalid')
+      setHint(() => t('That point is off the globe — click on the world.'));
+  };
+  const onMove = (event) => {
+    if (!session || session.shape === 'pin' || destroyed) return;
+    const p = worldAt(event.endPosition);
+    cursor = p
+      ? Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0)
+      : null;
+    viewer.scene.requestRender();
+  };
+
+  // ---- finish / cancel -------------------------------------------------
+  const finish = async () => {
+    if (destroyed || !session) return null;
+    const reason = finishReason(session);
+    if (reason !== 'ok') {
+      // 'too-few' is just "keep clicking" and the hint already says so;
+      // a degenerate or off-globe shape needs to be told why it was refused.
+      if (reason !== 'too-few') setHint(() => drawHint(session));
+      return null;
+    }
+    const spec = finishSpec(session, { label, color });
+    if (!spec) return null;
+    // Start a fresh session BEFORE awaiting, so a second Enter or the second
+    // half of a double-click cannot submit the same shape twice.
+    session = createDrawSession(shape);
+    cursor = null;
+    syncPreview();
+    label = '';
+    present();
+    const attempt = generation;
+    try {
+      const result = await annotations.annotate([spec], {
+        persist: true,
+        flyTo: false,
+      });
+      if (destroyed || attempt !== generation) return result;
+      if (result?.drawn === 0)
+        setHint(() => t('That shape could not be placed.'));
+      return result;
+    } catch (error) {
+      if (destroyed || attempt !== generation) return null;
+      setHint(() =>
+        t('Could not place the shape: {error}', {
+          error: error?.message || error,
+        }),
+      );
+      return null;
+    }
+  };
+  const cancel = () => {
+    if (!session) return;
+    generation += 1;
+    session = createDrawSession(shape);
+    cursor = null;
+    syncPreview();
+  };
+  /** Wipe the board: the shape in progress AND every mark already placed. */
+  const clearAll = () => {
+    generation += 1;
+    cursor = null;
+    if (session) session = createDrawSession(shape);
+    annotations.clear();
+    syncPreview();
+    if (!destroyed && !active) setHint(() => t('Board cleared.'));
+  };
+
+  // ---- keys: only while drawing, never while typing in another field ----
+  // The label field is this tool's own: typing there still drives drawing.
+  const isLabelField = (target) => target?.id === 'draw-label-input';
+  const typingElsewhere = (event) => {
+    const t = event.target;
+    if (!t || isLabelField(t)) return false;
+    return (
+      t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.isContentEditable
+    );
+  };
+  /**
+   * Enter is the finish key, but on a focused control Enter means "press this
+   * control". Keyboard-focusing Clear and pressing Enter must clear the board,
+   * not finish the shape — so the finish key is only taken from the canvas,
+   * the page body, or the label field this tool owns.
+   */
+  const enterBelongsToDrawing = (event) => {
+    const t = event.target;
+    if (!t || isLabelField(t)) return true;
+    if (
+      typeof t.closest === 'function' &&
+      t.closest('button, a, select, [role="button"], [role="radio"]')
+    )
+      return false;
+    return (
+      t === document.body || t === viewer.scene.canvas || t.tagName === 'CANVAS'
+    );
+  };
+  const onKey = (event) => {
+    if (!active || destroyed || typingElsewhere(event)) return;
+    // Enter goes to finish() once a shape has been started; finish() owns the
+    // decision and says WHY it refused. Swallowing the key on a degenerate
+    // shape left the person pressing Enter at a silent panel. A focused button
+    // keeps its own Enter — see enterBelongsToDrawing.
+    if (event.key === 'Enter') {
+      if (session?.vertices?.length && enterBelongsToDrawing(event)) {
+        event.preventDefault();
+        void finish();
+      }
+      return;
+    }
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      if (session?.vertices.length) cancel();
+      else setActive(false);
+      return;
+    }
+    if (event.key === 'Backspace' && !isLabelField(event.target)) {
+      if (removeLastVertex(session)) {
+        event.preventDefault();
+        syncPreview();
+      }
+    }
+  };
+
+  // ---- mode on / off -----------------------------------------------------
+  function setActive(next) {
+    if (destroyed || next === active) return active;
+    if (next) {
+      lease = claimPointer(DRAW_POINTER_OWNER);
+      if (!lease) {
+        // Somebody else is using the pointer — possibly an older instance of
+        // this same tool that has not finished tearing down. Say so instead of
+        // half-starting.
+        setHint(() =>
+          t('{owner} is using the pointer — close it first.', {
+            owner: translateKnown(pointerOwnerName(pointerOwner())),
+          }),
+        );
+        return active;
+      }
+    }
+    active = next;
+    present();
+    document.body.classList.toggle('gev-drawing', active);
+    if (active) {
+      session = createDrawSession(shape);
+      bindSceneHandler();
+      syncPreview();
+    } else {
+      generation += 1;
+      session = null;
+      cursor = null;
+      releaseSceneHandler();
+      releasePointer(lease);
+      lease = null;
+      syncPreview();
+    }
+    return active;
+  }
+
+  function bindSceneHandler() {
+    if (handler) return;
+    handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
+    handler.setInputAction(onClick, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+    handler.setInputAction(onMove, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
+    handler.setInputAction(() => {
+      void finish();
+    }, Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK);
+    // Cesium's Viewer binds BOTH stock click actions on its own handler: the
+    // single click picks an entity into `viewer.selectedEntity`, the double
+    // click tracks it. Neither goes through a layer, so neither can be fixed by
+    // the shared pointer claim — they have to be borrowed outright for the
+    // session and given back on the way out. Borrowing the single click is what
+    // stops a vertex placed on a contact from also selecting it.
+    const stock = viewer.screenSpaceEventHandler;
+    savedSingleClick =
+      stock.getInputAction(Cesium.ScreenSpaceEventType.LEFT_CLICK) || null;
+    savedDoubleClick =
+      stock.getInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK) ||
+      null;
+    stock.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_CLICK);
+    stock.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK);
+    listen(document, 'keydown', onKey, true);
+  }
+
+  function releaseSceneHandler() {
+    if (handler) {
+      handler.destroy();
+      handler = null;
+    }
+    if (savedSingleClick) {
+      viewer.screenSpaceEventHandler.setInputAction(
+        savedSingleClick,
+        Cesium.ScreenSpaceEventType.LEFT_CLICK,
+      );
+      savedSingleClick = null;
+    }
+    if (savedDoubleClick) {
+      viewer.screenSpaceEventHandler.setInputAction(
+        savedDoubleClick,
+        Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK,
+      );
+      savedDoubleClick = null;
+    }
+    // Drop the keydown listener bound alongside this handler.
+    for (let i = domListeners.length - 1; i >= 0; i -= 1) {
+      const [target, type, listener, options] = domListeners[i];
+      if (listener !== onKey) continue;
+      target.removeEventListener(type, listener, options);
+      domListeners.splice(i, 1);
+    }
+  }
+
+  /** Draw `next` from now on; an open shape starts over in it. */
+  function chooseShape(next) {
+    shape = normalizeShape(next);
+    present();
+    if (active) {
+      generation += 1;
+      session = createDrawSession(shape);
+      cursor = null;
+      syncPreview();
+    }
+  }
+  const disconnect = connect({
+    toggleDraw: () => setActive(!active),
+    setDrawShape: chooseShape,
+    setDrawColor: (value) => {
+      color = COLORS.includes(value) ? value : 'primary';
+      present();
+      syncPreview();
+    },
+    setDrawLabel: (text) => {
+      label = String(text ?? '');
+      present();
+    },
+    clearDraw: clearAll,
+  });
+  setHint(() => drawHint(null));
+
+  const api = {
+    get active() {
+      return active;
+    },
+    get shape() {
+      return shape;
+    },
+    get session() {
+      return session;
+    },
+    setActive,
+    setShape: chooseShape,
+    /** Test seam: add a vertex from lon/lat as if it had been clicked. */
+    addVertex(lon, lat, height = 0) {
+      if (!session) return false;
+      const r = addVertex(session, { lon, lat, height });
+      if (r.added) syncPreview();
+      return r.added;
+    },
+    finish,
+    cancel,
+    clearAll,
+    shapes: DRAW_SHAPES,
+    /** What this tool currently holds — for teardown and leak assertions. */
+    diagnostics() {
+      return {
+        active,
+        destroyed,
+        sceneHandler: Boolean(handler),
+        domListeners: domListeners.length,
+        previewDataSources: countPreviewDataSources(viewer),
+        previewEntities: destroyed ? 0 : dataSource.entities.values.length,
+        pointerOwner: pointerOwner(),
+        // The viewer's OWN click actions. While a session is open both are
+        // borrowed (absent here); after it closes both are back. A harness can
+        // compare the restored functions by identity with what it captured
+        // before, which is the only way to prove they were given back rather
+        // than replaced.
+        stockSingleClick: Boolean(
+          viewer.screenSpaceEventHandler?.getInputAction?.(
+            Cesium.ScreenSpaceEventType.LEFT_CLICK,
+          ),
+        ),
+        stockDoubleClick: Boolean(
+          viewer.screenSpaceEventHandler?.getInputAction?.(
+            Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK,
+          ),
+        ),
+      };
+    },
+    /** Resolves once every deferred teardown step has run. */
+    whenSettled() {
+      return attaching;
+    },
+    destroy() {
+      if (destroyed) return attaching;
+      // Supersede any finish still in flight before anything is torn down.
+      generation += 1;
+      if (active) setActive(false);
+      destroyed = true;
+      offLocale();
+      disconnect();
+      releaseSceneHandler();
+      releasePointer(lease);
+      lease = null;
+      for (const [target, type, listener, options] of domListeners.splice(0)) {
+        target.removeEventListener(type, listener, options);
+      }
+      previewEntities.length = 0;
+      dataSource.entities.removeAll();
+      // Wait for the pending add() before removing: a destroy() in the same
+      // tick as init would otherwise remove nothing and let the attachment land
+      // behind it.
+      attaching = attaching.then(() => {
+        try {
+          viewer.dataSources.remove(dataSource, true);
+        } catch {
+          /* viewer already disposed — nothing to detach from */
+        }
+      });
+      document.body.classList.remove('gev-drawing');
+      hint = '';
+      present();
+      if (window.__gevDrawTool === api) delete window.__gevDrawTool;
+      return attaching;
+    },
+  };
+  window.__gevDrawTool = api;
+  return api;
+}
+
+/** How many draw previews are attached — more than one means a leaked tool. */
+function countPreviewDataSources(viewer) {
+  const sources = viewer?.dataSources;
+  if (!sources) return 0;
+  let found = 0;
+  for (let index = 0; index < sources.length; index += 1) {
+    if (sources.get(index)?.name === PREVIEW_DATA_SOURCE_NAME) found += 1;
+  }
+  return found;
+}

src/annotations/drawTool.test.mjs

@@ -0,0 +1,229 @@
+// STRUCTURAL contracts only: where files live, which ids the markup carries,
+// what the docs may claim. Things a running test cannot observe.
+//
+// Everything about the tool's BEHAVIOUR — the pointer lease, borrowing and
+// restoring the viewer's own click actions, teardown, the Enter key, preview
+// heights, Clear — is asserted against the running module in
+// `drawToolBehaviour.test.mjs`, not by reading this file's source.
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+const tool = () => read('src/annotations/drawTool.js');
+
+test('the application composition wires the draw tool and owns its teardown', () => {
+  const tools = read('src/app/tools.js');
+  const engineAt = tools.indexOf('const annotations = initAnnotations({');
+  const drawAt = tools.indexOf(
+    'const drawTool = initDrawTool({\n    viewer,\n    annotations,\n    publish: (view) => displayStore.publishDraw(view),',
+  );
+  assert.ok(engineAt >= 0, 'initAnnotations call missing');
+  assert.ok(
+    drawAt > engineAt,
+    'initDrawTool must follow initAnnotations and receive its engine',
+  );
+  assert.match(
+    tools,
+    /import \{ initDrawTool \} from '\.\.\/annotations\/drawTool\.js';/,
+  );
+  // The tool holds a pointer claim, DOM listeners and a data source, so the
+  // application lifetime disposes it — not whoever last pressed the button.
+  const deferAt = tools.indexOf('defer(() => drawTool?.destroy());');
+  assert.ok(deferAt > drawAt, 'the shell must defer the draw tool teardown');
+});
+
+test('the engine resolves manual geometry before any name resolution', () => {
+  const engine = read('src/annotations/annotationEngine.js');
+  const resolveAt = engine.indexOf(
+    'async function resolveSpec(spec, signal) {',
+  );
+  const manualAt = engine.indexOf(
+    'if (isManualSpec(spec, type)) return resolveManualSpec(spec, type, viewer);',
+    resolveAt,
+  );
+  const routeAt = engine.indexOf("if (type === 'route') {", resolveAt);
+  assert.ok(
+    manualAt > resolveAt && manualAt < routeAt,
+    'manual specs must short-circuit ahead of the route/arrow/area resolvers',
+  );
+  assert.match(
+    engine,
+    /if \(mode === 'manual'\) return baseLabel \? `\$\{baseLabel\} — \$\{dist\}` : dist;/,
+    'a drawn line reports length, never a walk time',
+  );
+});
+
+test('the Draw control markup carries the ids the tool binds to', () => {
+  // The DISPLAY rail is a Vue view now, rendered into index.html's view host —
+  // the markup is not in index.html any more.
+  const html = read('src/ui/views/panels/DisplayPanel.vue');
+  const ids = [
+    'draw-toggle',
+    'draw-mode-row',
+    'draw-label-row',
+    'draw-label-input',
+    'draw-color-select',
+    'draw-clear',
+    'draw-hint',
+  ];
+  for (const id of ids) {
+    assert.match(
+      html,
+      new RegExp(`id="${id}"`),
+      `#${id} missing from index.html`,
+    );
+  }
+  for (const shape of ['area', 'line', 'pin']) {
+    assert.match(
+      html,
+      new RegExp(`'data-shape': '${shape}'`),
+      `shape button ${shape} missing`,
+    );
+  }
+  // The rows and the hint render what the tool publishes; the controls
+  // call the actions the tool connects to the display store.
+  for (const action of [
+    "act('toggleDraw')",
+    "act('setDrawShape', $event)",
+    "act('setDrawLabel', $event.target.value)",
+    "act('setDrawColor', $event)",
+    "act('clearDraw')",
+  ]) {
+    assert.ok(html.includes(action), `DisplayPanel must call ${action}`);
+    const name = /act\('([a-zA-Z]+)'/.exec(action)[1];
+    assert.match(
+      tool(),
+      new RegExp(`\\b${name}: `),
+      `drawTool must answer ${name}`,
+    );
+  }
+});
+
+test('the DISPLAY rail styles live in their current owner, not the shim', () => {
+  // The PR this came from was written against the pre-refactor layout, where
+  // these rules lived in the root style.css. That file is an import shim now,
+  // and putting rules back into it would silently undo the split.
+  const shim = read('style.css');
+  const rules = shim
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .split('\n')
+    .filter((line) => line.trim() && !/^@import '[^']+';$/.test(line.trim()));
+  assert.deepEqual(rules, [], 'style.css is an import shim, not a stylesheet');
+  assert.doesNotMatch(
+    shim,
+    /draw-hint|pp-text-input/,
+    'draw styles belong to a component stylesheet',
+  );
+  const controls = read('src/ui/styles/controls.css');
+  for (const rule of [
+    '#draw-mode-row',
+    '#draw-label-row',
+    '.pp-text-input',
+    '.draw-clear-btn',
+    '.draw-hint',
+    'body.gev-drawing',
+  ]) {
+    assert.ok(
+      controls.includes(rule),
+      `${rule} must live in src/ui/styles/controls.css`,
+    );
+  }
+});
+
+test('nothing promises a GeoJSON export for drawn shapes', () => {
+  for (const file of [
+    'src/annotations/drawTool.js',
+    'src/annotations/drawMode.js',
+  ]) {
+    assert.doesNotMatch(
+      read(file),
+      /GeoJSON/i,
+      `${file} still claims a GeoJSON export`,
+    );
+  }
+  for (const file of ['README.md', 'CHANGELOG.md', 'docs/CURRENT-STATE.md']) {
+    const source = read(file);
+    const at = source.indexOf('DISPLAY ▸ **Draw**');
+    const start = at >= 0 ? at : source.indexOf('DISPLAY ▸ Draw');
+    assert.ok(start >= 0, `${file} should describe the Draw control`);
+    const section = source.slice(start, start + 1200);
+    assert.doesNotMatch(
+      section,
+      /GeoJSON/i,
+      `${file} still claims a GeoJSON export for drawn shapes`,
+    );
+  }
+});
+
+test('the docs do not promise a vertex height the renderer would discard', () => {
+  // Areas and routes are DRAPED, so a per-vertex height is not a placement.
+  // That the finished spec actually drops it is asserted against the running
+  // module in drawToolBehaviour.test.mjs; this only guards the wording.
+  assert.doesNotMatch(tool(), /lands on the roof/);
+  assert.doesNotMatch(
+    read('docs/CURRENT-STATE.md'),
+    /a vertex on a roof lands on the roof/,
+  );
+});
+
+test('draped marks classify onto terrain as well as 3D tiles', () => {
+  // CESIUM_3D_TILE alone rendered nothing on a keyless boot, where Cesium's own
+  // globe carries the imagery and there are no tiles to classify against. The
+  // rendered proof is in scripts/qa-draw-tool.mjs, which counts stroke pixels
+  // against a keyless server; this stops the constant being narrowed again.
+  const renderer = read('src/annotations/worldAnnotationRenderer.js');
+  assert.match(renderer, /const CLASSIFY = Cesium\.ClassificationType\.BOTH;/);
+  assert.doesNotMatch(
+    renderer,
+    /classificationType: Cesium\.ClassificationType\.CESIUM_3D_TILE/,
+  );
+});
+
+test('the draw modules are registered for formatting and boundary checks', () => {
+  const formatScope = JSON.parse(read('scripts/format-scope.json'));
+  for (const file of [
+    'src/annotations/drawMode.js',
+    'src/annotations/drawMode.test.mjs',
+    'src/annotations/drawTool.js',
+    'src/annotations/drawTool.test.mjs',
+    'src/data/inputOwnership.js',
+  ]) {
+    assert.ok(
+      formatScope.includes(file),
+      `${file} must be in the formatting scope`,
+    );
+  }
+  const boundaries = JSON.parse(read('scripts/package-boundaries.json'));
+  const owners = (file) =>
+    Object.entries(boundaries)
+      .filter(([, group]) => group.modules?.includes(file))
+      .map(([name]) => name);
+  for (const file of [
+    'src/annotations/drawMode.js',
+    'src/annotations/drawTool.js',
+    'src/data/inputOwnership.js',
+  ]) {
+    assert.ok(
+      owners(file).length > 0,
+      `${file} must be owned by at least one boundary group`,
+    );
+  }
+  // Every layer that consults the shared claim has to own the module it reads,
+  // or its bundle fails the boundary check.
+  for (const group of ['alpr-cameras', 'vessel-layer', 'satellites-layer']) {
+    assert.ok(
+      boundaries[group]?.modules.includes('src/data/inputOwnership.js'),
+      `${group} consults the pointer claim and must own the module`,
+    );
+  }
+  const exports = JSON.parse(read('package.json')).exports;
+  assert.equal(exports['./annotations'], './src/annotations/index.js');
+});

src/annotations/drawToolBehaviour.test.mjs

@@ -0,0 +1,552 @@
+// Behavioural tests for the draw tool: the module is driven against fake DOM
+// and viewer doubles and its OBSERVABLE effects are asserted — which lease it
+// holds, which viewer input actions it borrowed and gave back, what it leaves
+// behind when destroyed. Nothing here reads the module's source text.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { initDrawTool } from './drawTool.js';
+import {
+  isPointerFree,
+  pointerOwner,
+  claimPointer,
+  releasePointer,
+  resetPointerOwnership,
+} from '../data/inputOwnership.js';
+
+/* ── DOM doubles ───────────────────────────────────────────────────────── */
+
+class FakeClassList {
+  constructor() {
+    this.names = new Set();
+  }
+  add(...names) {
+    for (const n of names) this.names.add(n);
+  }
+  remove(...names) {
+    for (const n of names) this.names.delete(n);
+  }
+  contains(name) {
+    return this.names.has(name);
+  }
+  toggle(name, force) {
+    const on = force === undefined ? !this.names.has(name) : Boolean(force);
+    if (on) this.names.add(name);
+    else this.names.delete(name);
+    return on;
+  }
+}
+
+class FakeElement {
+  constructor(tagName = 'DIV', id = '') {
+    this.tagName = tagName.toUpperCase();
+    this.id = id;
+    this.classList = new FakeClassList();
+    this.dataset = {};
+    this.attributes = new Map();
+    this.textContent = '';
+    this.value = '';
+    this.listeners = [];
+  }
+  setAttribute(name, value) {
+    this.attributes.set(name, String(value));
+  }
+  getAttribute(name) {
+    return this.attributes.get(name) ?? null;
+  }
+  addEventListener(type, listener, options) {
+    this.listeners.push({ type, listener, options });
+  }
+  removeEventListener(type, listener) {
+    const at = this.listeners.findIndex(
+      (entry) => entry.type === type && entry.listener === listener,
+    );
+    if (at >= 0) this.listeners.splice(at, 1);
+  }
+  click() {
+    return this.emit('click');
+  }
+  closest(selector) {
+    // Only what the tool asks: "am I inside an activatable control?"
+    const activatable = ['button', 'a', 'select', '[role="button"]', '[role="radio"]'];
+    if (!activatable.some((part) => selector.includes(part))) return null;
+    return this.tagName === 'BUTTON' || this.tagName === 'A' || this.tagName === 'SELECT'
+      ? this
+      : null;
+  }
+  /** Deliver an event to this element's own listeners. */
+  emit(type, event = {}) {
+    const payload = {
+      type,
+      target: this,
+      preventDefault() {},
+      stopImmediatePropagation() {},
+      ...event,
+    };
+    for (const entry of [...this.listeners])
+      if (entry.type === type) entry.listener(payload);
+    return payload;
+  }
+}
+
+function fakeDom() {
+  const byId = new Map();
+  const make = (id, tagName = 'DIV') => {
+    const element = new FakeElement(tagName, id);
+    byId.set(id, element);
+    return element;
+  };
+  // The control whose presence means the page has Draw, a focused button
+  // whose Enter is its own, and the tool's label field.
+  make('draw-toggle', 'BUTTON');
+  make('draw-clear', 'BUTTON');
+  make('draw-label-input', 'INPUT');
+
+  const body = new FakeElement('BODY');
+  const documentDouble = {
+    body,
+    getElementById: (id) => byId.get(id) ?? null,
+    listeners: [],
+    addEventListener(type, listener, options) {
+      this.listeners.push({ type, listener, options });
+    },
+    removeEventListener(type, listener) {
+      const at = this.listeners.findIndex(
+        (entry) => entry.type === type && entry.listener === listener,
+      );
+      if (at >= 0) this.listeners.splice(at, 1);
+    },
+    emit(type, event = {}) {
+      const payload = {
+        type,
+        target: body,
+        preventDefault() {},
+        stopImmediatePropagation() {},
+        ...event,
+      };
+      for (const entry of [...this.listeners])
+        if (entry.type === type) entry.listener(payload);
+      return payload;
+    },
+  };
+  return { byId, documentDouble };
+}
+
+/* ── viewer double ─────────────────────────────────────────────────────── */
+
+function fakeViewer() {
+  const canvas = new FakeElement('CANVAS');
+  canvas.clientWidth = 800;
+  canvas.clientHeight = 600;
+  const actions = new Map();
+  const stockHandler = {
+    getInputAction: (type) => actions.get(type),
+    setInputAction: (action, type) => actions.set(type, action),
+    removeInputAction: (type) => actions.delete(type),
+  };
+  const attached = [];
+  const pendingAdds = [];
+  const dataSources = {
+    get length() {
+      return attached.length;
+    },
+    get: (index) => attached[index],
+    add(source) {
+      // Cesium resolves this on a later tick — the whole point of finding 7.
+      const promise = Promise.resolve().then(() => {
+        attached.push(source);
+        return source;
+      });
+      pendingAdds.push(promise);
+      return promise;
+    },
+    remove(source) {
+      const at = attached.indexOf(source);
+      if (at >= 0) attached.splice(at, 1);
+      return at >= 0;
+    },
+  };
+  return {
+    scene: { canvas, requestRender() {} },
+    screenSpaceEventHandler: stockHandler,
+    dataSources,
+    _attached: attached,
+    _actions: actions,
+  };
+}
+
+function fakeAnnotations() {
+  const calls = { annotate: [], clear: 0 };
+  return {
+    calls,
+    async annotate(specs, options) {
+      calls.annotate.push({ specs, options });
+      return { drawn: specs.length };
+    },
+    clear() {
+      calls.clear += 1;
+    },
+  };
+}
+
+/** Stand up a tool against fresh doubles, with globals restored afterwards. */
+function harness() {
+  resetPointerOwnership();
+  const { byId, documentDouble } = fakeDom();
+  const viewer = fakeViewer();
+  const annotations = fakeAnnotations();
+  const previousDocument = globalThis.document;
+  const previousWindow = globalThis.window;
+  globalThis.document = documentDouble;
+  globalThis.window = globalThis.window || {};
+  const shown = { view: null };
+  // The controls' actions, as the display store holds them.
+  const controls = { actions: null };
+  const tool = initDrawTool({
+    viewer,
+    annotations,
+    publish: (view) => (shown.view = view),
+    connect: (actions) => {
+      controls.actions = actions;
+      return () => (controls.actions = null);
+    },
+  });
+  return {
+    tool,
+    shown,
+    viewer,
+    annotations,
+    byId,
+    documentDouble,
+    element: (id) => byId.get(id),
+    controls,
+    /** A control's change, as the view sends it. */
+    act: (name, ...args) => controls.actions?.[name]?.(...args),
+    restore() {
+      resetPointerOwnership();
+      if (previousDocument === undefined) delete globalThis.document;
+      else globalThis.document = previousDocument;
+      if (previousWindow === undefined) delete globalThis.window;
+      else globalThis.window = previousWindow;
+    },
+  };
+}
+
+const LEFT_CLICK = Cesium.ScreenSpaceEventType.LEFT_CLICK;
+const LEFT_DOUBLE_CLICK = Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK;
+
+/* ── the tests ─────────────────────────────────────────────────────────── */
+
+test('turning Draw on takes a lease and turning it off gives it back', async () => {
+  const h = harness();
+  try {
+    assert.equal(isPointerFree(), true);
+    h.act('toggleDraw');
+    assert.equal(pointerOwner(), 'draw', 'the session owns the pointer');
+    assert.equal(h.tool.active, true);
+
+    h.act('toggleDraw');
+    assert.equal(isPointerFree(), true, 'leaving draw mode frees the pointer');
+    assert.equal(h.tool.active, false);
+  } finally {
+    h.restore();
+  }
+});
+
+test('Draw refuses to start when something else holds the pointer', async () => {
+  const h = harness();
+  try {
+    const other = claimPointer('directions');
+    h.act('toggleDraw');
+    assert.equal(h.tool.active, false, 'it must not half-start');
+    assert.equal(pointerOwner(), 'directions', 'and must not steal the claim');
+    // Named by its tool, not by the internal owner id.
+    assert.equal(
+      h.shown.view.hint,
+      'Directions is using the pointer — close it first.',
+    );
+    assert.equal(h.tool.diagnostics().sceneHandler, false, 'no handler was bound');
+
+    releasePointer(other);
+    h.act('toggleDraw');
+    assert.equal(h.tool.active, true, 'and it starts once the pointer is free');
+  } finally {
+    h.restore();
+  }
+});
+
+test('a destroyed instance cannot free the pointer its replacement holds', async () => {
+  const first = harness();
+  try {
+    first.act('toggleDraw');
+    assert.equal(pointerOwner(), 'draw');
+    // The replacement takes over before the old one finishes tearing down.
+    first.tool.setActive(false);
+    const second = harness();
+    try {
+      second.act('toggleDraw');
+      assert.equal(pointerOwner(), 'draw');
+      await first.tool.destroy();
+      assert.equal(
+        pointerOwner(),
+        'draw',
+        'the live session still owns the pointer after the old one is destroyed',
+      );
+      assert.equal(second.tool.active, true);
+    } finally {
+      second.restore();
+    }
+  } finally {
+    first.restore();
+  }
+});
+
+test('both stock viewer click actions are borrowed for the session and given back', async () => {
+  const h = harness();
+  try {
+    const stockClick = () => 'viewer picks and selects';
+    const stockDouble = () => 'viewer tracks';
+    h.viewer.screenSpaceEventHandler.setInputAction(stockClick, LEFT_CLICK);
+    h.viewer.screenSpaceEventHandler.setInputAction(stockDouble, LEFT_DOUBLE_CLICK);
+
+    h.act('toggleDraw');
+    assert.equal(
+      h.viewer.screenSpaceEventHandler.getInputAction(LEFT_CLICK),
+      undefined,
+      "the viewer's own selecting click must not run while drawing",
+    );
+    assert.equal(
+      h.viewer.screenSpaceEventHandler.getInputAction(LEFT_DOUBLE_CLICK),
+      undefined,
+    );
+
+    h.act('toggleDraw');
+    assert.equal(
+      h.viewer.screenSpaceEventHandler.getInputAction(LEFT_CLICK),
+      stockClick,
+      'the exact function is restored, not a replacement',
+    );
+    assert.equal(
+      h.viewer.screenSpaceEventHandler.getInputAction(LEFT_DOUBLE_CLICK),
+      stockDouble,
+    );
+  } finally {
+    h.restore();
+  }
+});
+
+test('Enter finishes from the canvas and the label field, never from a focused button', async () => {
+  const h = harness();
+  try {
+    h.act('toggleDraw');
+    h.tool.setShape('area');
+    h.tool.addVertex(-97.75, 30.26);
+    h.tool.addVertex(-97.74, 30.26);
+    h.tool.addVertex(-97.74, 30.27);
+
+    // Enter while the Clear button has keyboard focus means "press Clear".
+    h.documentDouble.emit('keydown', { key: 'Enter', target: h.element('draw-clear') });
+    await Promise.resolve();
+    assert.equal(
+      h.annotations.calls.annotate.length,
+      0,
+      'a focused button keeps its own Enter',
+    );
+    assert.equal(h.tool.session.vertices.length, 3, 'and the shape is untouched');
+
+    // Enter from the page body (the canvas has focus in practice) finishes it.
+    h.documentDouble.emit('keydown', { key: 'Enter', target: h.documentDouble.body });
+    await Promise.resolve();
+    await Promise.resolve();
+    assert.equal(h.annotations.calls.annotate.length, 1, 'Enter on the map finishes');
+    assert.equal(h.annotations.calls.annotate[0].specs[0].type, 'area');
+  } finally {
+    h.restore();
+  }
+});
+
+test('the live preview hangs at the height the click landed on', async () => {
+  const h = harness();
+  try {
+    h.act('toggleDraw');
+    h.tool.setShape('line');
+    h.tool.addVertex(-97.75, 30.26, 187.5);
+    h.tool.addVertex(-97.74, 30.26, 212.25);
+
+    await h.tool.whenSettled();
+    const source = h.viewer._attached[0] ?? null;
+    assert.ok(source, 'the preview data source is attached');
+    const points = source.entities.values.filter((entity) => entity.point);
+    assert.equal(points.length, 2, 'one preview dot per vertex');
+    const heights = points.map((entity) => {
+      const position = entity.position.getValue(Cesium.JulianDate.now());
+      return Cesium.Cartographic.fromCartesian(position).height;
+    });
+    assert.ok(Math.abs(heights[0] - 187.5) < 0.5, `got ${heights[0]}`);
+    assert.ok(Math.abs(heights[1] - 212.25) < 0.5, `got ${heights[1]}`);
+
+    // …and the finished shape is still flattened, deliberately: the renderer
+    // drapes, so a height carried further would be discarded out of sight.
+    h.documentDouble.emit('keydown', { key: 'Enter', target: h.documentDouble.body });
+    await Promise.resolve();
+    await Promise.resolve();
+    const spec = h.annotations.calls.annotate[0].specs[0];
+    assert.deepEqual(spec.path, [
+      [-97.75, 30.26],
+      [-97.74, 30.26],
+    ]);
+  } finally {
+    h.restore();
+  }
+});
+
+test('destroy in the same tick as init still removes the preview data source', async () => {
+  const h = harness();
+  try {
+    // Nothing has been attached yet — dataSources.add() resolves later.
+    assert.equal(h.viewer._attached.length, 0, 'the add is still pending');
+    await h.tool.destroy();
+    await Promise.resolve();
+    assert.equal(
+      h.viewer._attached.length,
+      0,
+      'the preview must not be left attached behind the teardown',
+    );
+  } finally {
+    h.restore();
+  }
+});
+
+test('destroy releases the pointer, the handler, the listeners and the stock actions', async () => {
+  const h = harness();
+  try {
+    const stockClick = () => 'viewer picks and selects';
+    h.viewer.screenSpaceEventHandler.setInputAction(stockClick, LEFT_CLICK);
+    h.act('toggleDraw');
+    h.tool.addVertex(-97.75, 30.26);
+    assert.equal(pointerOwner(), 'draw');
+    assert.ok(h.tool.diagnostics().domListeners > 0);
+
+    await h.tool.destroy();
+    await Promise.resolve();
+
+    assert.equal(isPointerFree(), true, 'the pointer is free');
+    const after = h.tool.diagnostics();
+    assert.equal(after.destroyed, true);
+    assert.equal(after.sceneHandler, false, 'the Cesium handler is gone');
+    assert.equal(after.domListeners, 0, 'every DOM listener came off');
+    assert.equal(h.documentDouble.listeners.length, 0, 'including the keydown');
+    assert.equal(h.controls.actions, null, 'and the controls are disconnected');
+    assert.equal(
+      h.viewer.screenSpaceEventHandler.getInputAction(LEFT_CLICK),
+      stockClick,
+      'the viewer got its selecting click back',
+    );
+    assert.equal(h.viewer._attached.length, 0, 'the preview data source is detached');
+
+    // Idempotent: a second destroy is harmless.
+    await h.tool.destroy();
+  } finally {
+    h.restore();
+  }
+});
+
+test('Clear wipes the board and the shape in progress', async () => {
+  const h = harness();
+  try {
+    h.act('toggleDraw');
+    h.tool.addVertex(-97.75, 30.26);
+    h.tool.addVertex(-97.74, 30.26);
+    assert.equal(h.tool.session.vertices.length, 2);
+
+    h.act('clearDraw');
+    assert.equal(h.annotations.calls.clear, 1, 'placed marks are removed');
+    assert.equal(h.tool.session.vertices.length, 0, 'and so is the shape in progress');
+  } finally {
+    h.restore();
+  }
+});
+
+test('the controls choose the shape, colour and label the next shape is drawn with', async () => {
+  const h = harness();
+  try {
+    h.act('toggleDraw');
+    h.act('setDrawShape', 'line');
+    h.act('setDrawColor', 'amber');
+    h.act('setDrawLabel', 'Route A');
+    assert.deepEqual(
+      { ...h.shown.view, hint: undefined },
+      { active: true, shape: 'line', color: 'amber', label: 'Route A', hint: undefined },
+      'the view shows what the controls chose',
+    );
+    h.act('setDrawColor', 'purple');
+    assert.equal(h.shown.view.color, 'primary', 'an unknown colour falls back');
+    h.act('setDrawColor', 'cyan');
+    h.tool.addVertex(-97.75, 30.26);
+    // Choosing a shape again starts the open one over.
+    h.act('setDrawShape', 'line');
+    assert.equal(h.tool.session.vertices.length, 0);
+    h.tool.addVertex(-97.75, 30.26);
+    h.tool.addVertex(-97.74, 30.26);
+    h.documentDouble.emit('keydown', { key: 'Enter', target: h.documentDouble.body });
+    await Promise.resolve();
+    await Promise.resolve();
+    const spec = h.annotations.calls.annotate[0].specs[0];
+    assert.equal(spec.type, 'route', 'a drawn line is a manual route');
+    assert.equal(spec.color, 'cyan');
+    assert.equal(spec.label, 'Route A');
+    assert.equal(h.shown.view.label, '', 'a finished shape empties the label');
+  } finally {
+    h.restore();
+  }
+});
+
+test('keys typed in the label field: Enter finishes, Backspace edits, Escape cancels', async () => {
+  const h = harness();
+  try {
+    const label = h.element('draw-label-input');
+    const elsewhere = new FakeElement('INPUT', 'location-search');
+    h.act('toggleDraw');
+    h.tool.addVertex(-97.75, 30.26);
+    h.tool.addVertex(-97.74, 30.26);
+    h.documentDouble.emit('keydown', { key: 'Backspace', target: label });
+    assert.equal(h.tool.session.vertices.length, 2, 'Backspace edits the label');
+    h.documentDouble.emit('keydown', { key: 'Enter', target: elsewhere });
+    await Promise.resolve();
+    assert.equal(h.annotations.calls.annotate.length, 0, 'another field keeps its Enter');
+    h.documentDouble.emit('keydown', { key: 'Escape', target: label });
+    assert.equal(h.tool.session.vertices.length, 0, 'Escape drops the open shape');
+    assert.equal(h.tool.active, true, 'and leaves Draw on');
+    h.act('setDrawShape', 'line');
+    h.tool.addVertex(-97.75, 30.26);
+    h.tool.addVertex(-97.74, 30.26);
+    h.documentDouble.emit('keydown', { key: 'Enter', target: label });
+    await Promise.resolve();
+    await Promise.resolve();
+    assert.equal(h.annotations.calls.annotate.length, 1, 'Enter in the label finishes');
+  } finally {
+    h.restore();
+  }
+});
+
+test('a page without the Draw controls gets no draw tool', () => {
+  resetPointerOwnership();
+  const previousDocument = globalThis.document;
+  globalThis.document = { getElementById: () => null };
+  try {
+    let connected = false;
+    const tool = initDrawTool({
+      viewer: fakeViewer(),
+      annotations: fakeAnnotations(),
+      connect: () => {
+        connected = true;
+        return () => {};
+      },
+    });
+    assert.equal(tool, null);
+    assert.equal(connected, false);
+  } finally {
+    if (previousDocument === undefined) delete globalThis.document;
+    else globalThis.document = previousDocument;
+  }
+});

src/annotations/hybridAnnotationRenderer.js

@@ -16,11 +16,15 @@ import { createScreenAnnotationRenderer } from './screenAnnotationRenderer.js';
  * label-less) so every caption shares one consistent style.
  *
  * The hybrid surface honors add/update/remove/sync/destroy; update coordinates the
- * one route change that spans both sub-renderers.
+ * one route change that spans both sub-renderers. `screen` passes options to the
+ * screen renderer (its store, in tests).
  */
-export function createHybridAnnotationRenderer(viewer) {
+export function createHybridAnnotationRenderer(
+  viewer,
+  { screen: screenOptions } = {},
+) {
   const world = createWorldAnnotationRenderer(viewer);
-  const screen = createScreenAnnotationRenderer(viewer);
+  const screen = createScreenAnnotationRenderer(viewer, screenOptions);
   // anno.id -> { worldProxy?, screenProxy? } — proxies own the sub-renderer state.
   const routed = new Map();
 
@@ -42,7 +46,11 @@ export function createHybridAnnotationRenderer(viewer) {
         entry.screenProxy = liveProxy(anno, { type: 'label', ring: null });
         screen.add(entry.screenProxy);
       }
-    } else if (anno.type === 'route' && Array.isArray(anno.path) && anno.path.length >= 2) {
+    } else if (
+      anno.type === 'route' &&
+      Array.isArray(anno.path) &&
+      anno.path.length >= 2
+    ) {
       // Drape the path on the tiles (world), caption it with a screen callout
       // at the path midpoint.
       entry.worldProxy = liveProxy(anno, { label: null });
@@ -73,7 +81,11 @@ export function createHybridAnnotationRenderer(viewer) {
       add(anno);
       return;
     }
-    if (anno.type !== 'area' || !anno.ring || anno.ring.length < 3) return;
+    if (anno.type !== 'area' || !anno.ring || anno.ring.length < 3) {
+      if (anno.outlineUnavailable && entry.screenProxy)
+        screen.update(entry.screenProxy);
+      return;
+    }
 
     if (!entry.worldProxy) {
       entry.worldProxy = liveProxy(anno, { label: null });
@@ -86,7 +98,11 @@ export function createHybridAnnotationRenderer(viewer) {
     } else if (anno.label) {
       screen.add(screenProxy);
     }
-    entry.screenProxy = entry.screenProxy ? screenProxy : (anno.label ? screenProxy : null);
+    entry.screenProxy = entry.screenProxy
+      ? screenProxy
+      : anno.label
+        ? screenProxy
+        : null;
   }
 
   /**

src/annotations/hybridAnnotationRenderer.test.mjs

@@ -1,143 +1,24 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import * as Cesium from 'cesium';
+import { createPinia } from 'pinia';
+import { useScreenAnnotationsStore } from '../ui/stores/screenAnnotations.js';
 import { createHybridAnnotationRenderer } from './hybridAnnotationRenderer.js';
 
-class FakeClassList {
-  constructor(owner) {
-    this.owner = owner;
-    this.names = new Set();
-  }
-
-  reset(value) {
-    this.names = new Set(String(value || '').split(/\s+/).filter(Boolean));
-  }
-
-  add(...names) {
-    for (const name of names) this.names.add(name);
-    this.owner.attributes.set('class', Array.from(this.names).join(' '));
-  }
-
-  remove(...names) {
-    for (const name of names) this.names.delete(name);
-    this.owner.attributes.set('class', Array.from(this.names).join(' '));
-  }
-
-  contains(name) {
-    return this.names.has(name);
-  }
+/** A hybrid renderer whose screen board is presented to its own store. */
+function hybridWithBoard(viewer) {
+  const store = useScreenAnnotationsStore(createPinia());
+  const renderer = createHybridAnnotationRenderer(viewer, { screen: { store } });
+  return { store, renderer };
 }
 
-class FakeElement {
-  constructor(tagName) {
-    this.tagName = tagName;
-    this.attributes = new Map();
-    this.children = [];
-    this.parentNode = null;
-    this.style = {};
-    this.classList = new FakeClassList(this);
-    this.textContent = '';
-  }
-
-  setAttribute(name, value) {
-    this.attributes.set(name, String(value));
-    if (name === 'class') this.classList.reset(value);
-  }
-
-  getAttribute(name) {
-    return this.attributes.get(name) ?? null;
-  }
-
-  set className(value) {
-    this.setAttribute('class', value);
-  }
-
-  get className() {
-    return this.getAttribute('class') || '';
-  }
-
-  set id(value) {
-    this.setAttribute('id', value);
-  }
-
-  get id() {
-    return this.getAttribute('id') || '';
-  }
-
-  appendChild(child) {
-    child.parentNode = this;
-    this.children.push(child);
-    return child;
-  }
-
-  removeChild(child) {
-    const index = this.children.indexOf(child);
-    if (index >= 0) this.children.splice(index, 1);
-    child.parentNode = null;
-    return child;
-  }
-
-  remove() {
-    this.parentNode?.removeChild(this);
-  }
-
-  querySelector(selector) {
-    return this.querySelectorAll(selector)[0] || null;
-  }
-
-  querySelectorAll(selector) {
-    const className = selector.startsWith('.') ? selector.slice(1) : null;
-    const matches = [];
-    const visit = (node) => {
-      for (const child of node.children) {
-        if (className && child.classList.contains(className)) matches.push(child);
-        visit(child);
-      }
-    };
-    visit(this);
-    return matches;
-  }
-
-  addEventListener() {}
-
-  getBBox() {
-    return { x: 0, y: 0, width: 40, height: 16 };
-  }
-
-  set innerHTML(value) {
-    this._innerHTML = value;
-  }
+/** The screen marks the board shows, fading ones included. */
+function annotationGroups(store) {
+  return store.board?.marks ?? [];
 }
 
-function fakeDocument() {
-  const head = new FakeElement('head');
-  const body = new FakeElement('body');
-  const roots = [head, body];
-  return {
-    head,
-    body,
-    createElement: (tag) => new FakeElement(tag),
-    createElementNS: (_namespace, tag) => new FakeElement(tag),
-    getElementById(id) {
-      let found = null;
-      const visit = (node) => {
-        if (node.getAttribute('id') === id) found = node;
-        for (const child of node.children) visit(child);
-      };
-      for (const root of roots) visit(root);
-      return found;
-    },
-  };
-}
-
-function findAnnotationGroup(document) {
-  const layer = document.body.children.find((child) => child.classList.contains('gev-screen-whiteboard'));
-  const svg = layer.children.find((child) => child.classList.contains('gev-screen-whiteboard-svg'));
-  return {
-    svg,
-    group: svg.children.find((child) => child.classList.contains('gev-anno')),
-  };
-}
+const childrenWithClass = (mark, name) =>
+  mark.children.filter((child) => child.attrs?.class?.split(' ').includes(name));
 
 function cameraLookingAt(lon, lat) {
   const target = Cesium.Cartesian3.fromDegrees(lon, lat);
@@ -184,7 +65,6 @@ function cameraLookingAt(lon, lat) {
 
 /** Install the browser globals both renderers touch, restored after the test. */
 function installBrowserGlobals(t) {
-  const originalDocument = globalThis.document;
   const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
   const originalWindow = globalThis.window;
   const originalBrowserConstructors = new Map([
@@ -193,13 +73,10 @@ function installBrowserGlobals(t) {
     ['ImageBitmap', globalThis.ImageBitmap],
     ['OffscreenCanvas', globalThis.OffscreenCanvas],
   ]);
-  globalThis.document = fakeDocument();
   globalThis.requestAnimationFrame = (callback) => { callback(); return 1; };
   globalThis.window = { setTimeout: (fn) => { fn(); return 1; } };
   for (const name of originalBrowserConstructors.keys()) globalThis[name] = class {};
   t.after(() => {
-    if (originalDocument === undefined) delete globalThis.document;
-    else globalThis.document = originalDocument;
     if (originalRequestAnimationFrame === undefined) delete globalThis.requestAnimationFrame;
     else globalThis.requestAnimationFrame = originalRequestAnimationFrame;
     if (originalWindow === undefined) delete globalThis.window;
@@ -244,9 +121,6 @@ function fakeViewer(lon, lat) {
   };
 }
 
-function annotationGroups(svg) {
-  return svg.children.filter((child) => child.classList.contains('gev-anno'));
-}
 
 function naiveRingCentroid(ring) {
   const totals = ring.reduce(
@@ -257,7 +131,6 @@ function naiveRingCentroid(ring) {
 }
 
 test('hybrid outline upgrade preserves the screen group and adds world geometry', (t) => {
-  const originalDocument = globalThis.document;
   const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
   const originalBrowserConstructors = new Map([
     ['HTMLCanvasElement', globalThis.HTMLCanvasElement],
@@ -265,12 +138,9 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry'
     ['ImageBitmap', globalThis.ImageBitmap],
     ['OffscreenCanvas', globalThis.OffscreenCanvas],
   ]);
-  globalThis.document = fakeDocument();
   globalThis.requestAnimationFrame = (callback) => { callback(); return 1; };
   for (const name of originalBrowserConstructors.keys()) globalThis[name] = class {};
   t.after(() => {
-    if (originalDocument === undefined) delete globalThis.document;
-    else globalThis.document = originalDocument;
     if (originalRequestAnimationFrame === undefined) delete globalThis.requestAnimationFrame;
     else globalThis.requestAnimationFrame = originalRequestAnimationFrame;
     for (const [name, original] of originalBrowserConstructors) {
@@ -305,7 +175,7 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry'
       },
     },
   };
-  const renderer = createHybridAnnotationRenderer(viewer);
+  const { store, renderer } = hybridWithBoard(viewer);
   const anno = {
     id: 'anno-hybrid-fb3',
     type: 'area',
@@ -319,10 +189,8 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry'
   };
 
   renderer.add(anno);
-  const before = findAnnotationGroup(globalThis.document);
-  const originalCallout = before.group.querySelector('.gev-anno-callout');
-  const originalDot = before.group.querySelector('.gev-anno-dot');
-  assert.equal(before.group.querySelectorAll('.gev-anno-ring').length, 2);
+  const [before] = annotationGroups(store);
+  assert.equal(childrenWithClass(before, 'gev-anno-ring').length, 2);
   assert.equal(dataSources.length, 1);
   assert.equal(dataSources[0].entities.values.length, 0);
 
@@ -339,18 +207,22 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry'
   anno.footprintKind = 'area';
   renderer.update(anno);
 
-  const after = findAnnotationGroup(globalThis.document);
+  const [after, ...others] = annotationGroups(store);
   const expectedWindow = Cesium.SceneTransforms.worldToWindowCoordinates(
     scene,
     Cesium.Cartesian3.fromDegrees(centroid.lon, centroid.lat, centroid.height),
   );
-  assert.equal(after.group, before.group, 'the real hybrid keeps the existing SVG group');
-  assert.equal(after.svg.children.filter((child) => child.classList.contains('gev-anno')).length, 1);
-  assert.equal(after.group.querySelectorAll('.gev-anno-ring').length, 0, 'screen reticle rings are removed');
-  assert.equal(after.group.querySelector('.gev-anno-callout'), originalCallout, 'the callout node is retained');
-  assert.equal(after.group.querySelector('.gev-anno-dot'), originalDot, 'the anchor dot is retained');
-  assert.equal(originalDot.getAttribute('cx'), expectedWindow.x.toFixed(1));
-  assert.equal(originalDot.getAttribute('cy'), expectedWindow.y.toFixed(1));
+  assert.equal(after.key, before.key, 'the real hybrid keeps the existing screen mark');
+  assert.equal(others.length, 0);
+  assert.equal(childrenWithClass(after, 'gev-anno-ring').length, 0, 'screen reticle rings are removed');
+  assert.deepEqual(
+    after.children.map((child) => child.key),
+    ['dot', 'leader', 'callout'],
+    'the dot, leader and callout are retained',
+  );
+  const dot = after.children.find((child) => child.key === 'dot');
+  assert.equal(dot.attrs.cx, expectedWindow.x.toFixed(1));
+  assert.equal(dot.attrs.cy, expectedWindow.y.toFixed(1));
   assert.deepEqual(centroid, { lon: -100.8, lat: 29.4, height: 0 }, 'closed-ring vertex mean stays pinned');
   assert.equal(dataSources[0].entities.values.length, 2, 'world area adds one fill and one outline');
   assert.equal(dataSources[0].entities.values.filter((entity) => entity.polygon).length, 1);
@@ -370,7 +242,7 @@ test('hybrid outline upgrade preserves the screen group and adds world geometry'
 test('a sub-renderer throw mid-add leaves state the rollback can still remove', (t) => {
   installBrowserGlobals(t);
   const { viewer, dataSources } = fakeViewer(-99, 31);
-  const renderer = createHybridAnnotationRenderer(viewer);
+  const { store, renderer } = hybridWithBoard(viewer);
   const ring = [[-106, 25], [-93, 25], [-93, 36], [-106, 36], [-106, 25]];
   const anno = {
     id: 'anno-partial-add',
@@ -386,20 +258,19 @@ test('a sub-renderer throw mid-add leaves state the rollback can still remove',
 
   // The world drape lands first; the screen caption then fails the way a lost
   // context does, AFTER the world geometry is already on the board.
-  const { svg } = findAnnotationGroup(globalThis.document);
-  const appendChild = svg.appendChild.bind(svg);
+  const publish = store.publish;
   let failNextInsert = true;
-  svg.appendChild = (child) => {
+  store.publish = (board) => {
     if (failNextInsert) {
       failNextInsert = false;
       throw new Error('screen insert failed');
     }
-    return appendChild(child);
+    return publish(board);
   };
 
   assert.throws(() => renderer.add(anno), /screen insert failed/);
   assert.equal(dataSources[0].entities.values.length, 2, 'the world drape is already live');
-  assert.equal(annotationGroups(svg).length, 0, 'the half-built screen group detached itself');
+  assert.equal(annotationGroups(store).length, 0, 'the half-built screen group detached itself');
 
   // The engine's rollback path — it must reach the partial state by id.
   renderer.remove(anno);
@@ -409,7 +280,7 @@ test('a sub-renderer throw mid-add leaves state the rollback can still remove',
   // an orphan nothing owns.
   renderer.add(anno);
   assert.equal(dataSources[0].entities.values.length, 2, 'the retry draws exactly one world drape');
-  assert.equal(annotationGroups(svg).length, 1, 'and exactly one screen caption');
+  assert.equal(annotationGroups(store).length, 1, 'and exactly one screen caption');
   renderer.remove(anno);
   assert.equal(dataSources[0].entities.values.length, 0);
   renderer.destroy();
@@ -418,7 +289,7 @@ test('a sub-renderer throw mid-add leaves state the rollback can still remove',
 test('a release that throws keeps the mark addressable for a retry cleanup', (t) => {
   installBrowserGlobals(t);
   const { viewer, dataSources } = fakeViewer(-99, 31);
-  const renderer = createHybridAnnotationRenderer(viewer);
+  const { store, renderer } = hybridWithBoard(viewer);
   const ring = [[-106, 25], [-93, 25], [-93, 36], [-106, 36], [-106, 25]];
   const anno = {
     id: 'anno-release-throw',
@@ -433,35 +304,34 @@ test('a release that throws keeps the mark addressable for a retry cleanup', (t)
   };
 
   renderer.add(anno);
-  const { svg } = findAnnotationGroup(globalThis.document);
   assert.equal(dataSources[0].entities.values.length, 2);
-  assert.equal(annotationGroups(svg).length, 1);
+  assert.equal(annotationGroups(store).length, 1);
 
   // The world route releases fine, then the screen release fails part-way
-  // (its fade-out timer throws) — so its SVG group is still in the document.
+  // (its fade-out timer throws) — so its mark is still on the board.
   const workingSetTimeout = globalThis.window.setTimeout;
   globalThis.window.setTimeout = () => { throw new Error('teardown scheduling failed'); };
   assert.throws(() => renderer.remove(anno), /teardown scheduling failed/);
   assert.equal(dataSources[0].entities.values.length, 0, 'the world route did release');
-  assert.equal(annotationGroups(svg).length, 1, 'the screen route did NOT — that is the orphan');
+  assert.equal(annotationGroups(store).length, 1, 'the screen route did NOT — that is the orphan');
 
   // Dropping the routing entry here would make that orphan permanently
   // unreachable. It must still be addressable, so a retry finishes the job.
   globalThis.window.setTimeout = workingSetTimeout;
   renderer.remove(anno);
-  assert.equal(annotationGroups(svg).length, 0, 'the retry cleanup must reach the orphan');
+  assert.equal(annotationGroups(store).length, 0, 'the retry cleanup must reach the orphan');
   assert.equal(dataSources[0].entities.values.length, 0, 'without double-releasing the world route');
 
   // Fully released now — a third call is inert.
   renderer.remove(anno);
-  assert.equal(annotationGroups(svg).length, 0);
+  assert.equal(annotationGroups(store).length, 0);
   renderer.destroy();
 });
 
 test('a world add that fails mid-way leaves its landed entities removable', (t) => {
   installBrowserGlobals(t);
   const { viewer, dataSources } = fakeViewer(-99, 31);
-  const renderer = createHybridAnnotationRenderer(viewer);
+  const { store, renderer } = hybridWithBoard(viewer);
   const ring = [[-106, 25], [-93, 25], [-93, 36], [-106, 36], [-106, 25]];
   const anno = {
     id: 'anno-partial-world-add',
@@ -493,9 +363,8 @@ test('a world add that fails mid-way leaves its landed entities removable', (t)
   assert.equal(entities.values.length, 0,
     'the rollback must see the entities that landed before the throw');
 
-  const { svg } = findAnnotationGroup(globalThis.document);
   renderer.add(anno);
   assert.equal(entities.values.length, 2, 'the retry draws a complete mark');
-  assert.equal(annotationGroups(svg).length, 1);
+  assert.equal(annotationGroups(store).length, 1);
   renderer.destroy();
 });

src/annotations/index.js

@@ -10,13 +10,27 @@ import { createHybridAnnotationRenderer } from './hybridAnnotationRenderer.js';
  * footprints + screen-space SVG for callouts/rings/arrows. The engine, resolver,
  * and voice tool wiring are identical to the other two branches.
  */
-export function initAnnotations({ viewer, tileset = null }) {
+export function initAnnotations({
+  viewer,
+  tileset = null,
+  placeSearch,
+  resolver,
+}) {
   // World-space footprint draping; clamped marks can use the photoreal tiles.
   if (tileset) {
-    try { tileset.enableCollision = true; } catch { /* older tileset */ }
+    try {
+      tileset.enableCollision = true;
+    } catch {
+      /* older tileset */
+    }
   }
   const renderer = createHybridAnnotationRenderer(viewer);
-  const engine = createAnnotationEngine({ viewer, renderer });
+  const engine = createAnnotationEngine({
+    viewer,
+    renderer,
+    placeSearch,
+    resolveTarget: resolver?.resolveAnnotationTarget,
+  });
   window.__gevAnnotations = engine;
   return engine;
 }

src/annotations/regionRing.test.mjs

@@ -0,0 +1,262 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { FEATURE_SOURCE_METHODS } from '../sources/featureSource.js';
+import { createAnnotationResolver } from './resolver.js';
+
+function featureSource(overrides = {}) {
+  const source = {};
+  for (const method of FEATURE_SOURCE_METHODS)
+    source[method] = async () => null;
+  return Object.assign(source, overrides);
+}
+
+// A state-typed place outside every bundled boundary, so the admin-boundary
+// feature lookup (not the bundled packs) answers.
+const offPackGeocode = {
+  async geocode() {
+    return {
+      place: {
+        lat: 0.5,
+        lng: -150.5,
+        label: 'Atlantis',
+        name: 'Atlantis',
+        types: ['administrative_area_level_1', 'political'],
+      },
+    };
+  },
+};
+
+function geocoderFor(place) {
+  const calls = [];
+  return {
+    calls,
+    async geocode(query) {
+      calls.push(query);
+      return { place };
+    },
+  };
+}
+
+test('region ring: Natural Earth names resolve without a geocoder', async () => {
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource(),
+  });
+  for (const name of ['Gulf of Mexico', 'the Alps']) {
+    const region = await resolveRegionRingForQuery(name);
+    assert.ok(region?.ring?.length >= 3, `${name} resolves to a ring`);
+    assert.equal(region.source, 'natural-earth');
+    assert.equal(region.error, undefined);
+  }
+});
+
+test('region ring: duplicate natural names need a containing geocoded anchor', async () => {
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource(),
+  });
+  const miss = geocoderFor(null);
+  assert.equal(
+    await resolveRegionRingForQuery('Cordillera Oriental', undefined, miss),
+    null,
+  );
+  assert.deepEqual(miss.calls, ['Cordillera Oriental']);
+
+  const inside = geocoderFor({
+    lat: 5,
+    lng: -73,
+    label: 'Cordillera Oriental',
+    name: 'Cordillera Oriental',
+    types: ['natural_feature'],
+  });
+  const region = await resolveRegionRingForQuery(
+    'Cordillera Oriental',
+    undefined,
+    inside,
+  );
+  assert.equal(region?.source, 'natural-earth');
+  assert.equal(region.name, 'Cordillera Oriental');
+  assert.ok(region.ring.length >= 8);
+  assert.deepEqual(inside.calls, ['Cordillera Oriental']);
+});
+
+test('region ring: outside and overlapping geocoded natural anchors stay unresolved', async () => {
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource(),
+  });
+  for (const [name, lat, lng] of [
+    ['Cordillera Oriental', 30.27, -97.74],
+    ['Canadian Shield', 45.6336, -74.86493],
+  ]) {
+    const geocoder = geocoderFor({
+      lat,
+      lng,
+      label: name,
+      name,
+      types: ['natural_feature'],
+    });
+    assert.equal(
+      await resolveRegionRingForQuery(name, undefined, geocoder),
+      null,
+    );
+    assert.deepEqual(geocoder.calls, [name]);
+  }
+});
+
+test('region ring: geocoded administrative scope wins over duplicate natural geography', async () => {
+  const lookups = [];
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource({
+      getAdministrativeAreas: async (point) => {
+        lookups.push(point);
+        return [];
+      },
+    }),
+  });
+  const geo = geocoderFor({
+    lat: 5,
+    lng: -73,
+    label: 'Cordillera Oriental',
+    name: 'Cordillera Oriental',
+    types: ['locality'],
+  });
+  const resolved = await resolveRegionRingForQuery(
+    'Cordillera Oriental',
+    undefined,
+    geo,
+  );
+  assert.equal(
+    resolved,
+    null,
+    'an unavailable city boundary is not a natural-region outline',
+  );
+  assert.deepEqual(lookups, [{ lat: 5, lon: -73 }]);
+  assert.deepEqual(geo.calls, ['Cordillera Oriental']);
+});
+
+test('region ring: cancellation during bundled lookup and geocode never returns a region', async () => {
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource(),
+  });
+  const controller = new AbortController();
+  const pending = resolveRegionRingForQuery('the Alps', controller.signal);
+  controller.abort();
+  await assert.rejects(pending, { name: 'AbortError' });
+
+  const later = new AbortController();
+  await assert.rejects(
+    resolveRegionRingForQuery('Cordillera Oriental', later.signal, {
+      async geocode() {
+        later.abort();
+        return { place: null };
+      },
+    }),
+    { name: 'AbortError' },
+  );
+});
+
+test('region ring: a slow admin-boundary lookup returns region-timeout within the budget', async () => {
+  let adminSignal;
+  let release;
+  let lookupStarted;
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource({
+      getAdministrativeAreas(_point, { signal }) {
+        lookupStarted = Date.now();
+        adminSignal = signal;
+        return new Promise((resolve) => {
+          release = resolve;
+        });
+      },
+    }),
+  });
+  const region = await resolveRegionRingForQuery(
+    'Atlantis',
+    undefined,
+    offPackGeocode,
+    { budgetMs: 50 },
+  );
+  assert.deepEqual(region, {
+    name: 'Atlantis',
+    ring: null,
+    error: 'region-timeout',
+  });
+  // Timed from the boundary lookup, so the bundled pack scans before it do not
+  // count. Under the 3 s default budget, so an ignored budgetMs still fails.
+  assert.ok(
+    Date.now() - lookupStarted < 2_000,
+    'returns at the budget, not the lookup',
+  );
+  // The lookup is left running so it can fill the boundary cache.
+  assert.equal(adminSignal?.aborted ?? false, false);
+  release(null);
+});
+
+test('region ring: an unbounded budget waits for the lookup', async () => {
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource({
+      getAdministrativeAreas: () =>
+        new Promise((resolve) => setTimeout(() => resolve(null), 30)),
+    }),
+  });
+  const region = await resolveRegionRingForQuery(
+    'Atlantis',
+    undefined,
+    offPackGeocode,
+    { budgetMs: Infinity },
+  );
+  assert.equal(region, null);
+});
+
+test('region ring: bundled states and counties resolve without a geocoder', async () => {
+  const lookups = [];
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource({
+      getAdministrativeAreas: async () => {
+        lookups.push('admin');
+        return null;
+      },
+    }),
+  });
+  const geocoder = geocoderFor(null);
+  for (const [query, name] of [
+    ['Texas', 'Texas'],
+    ['Bavaria', 'Bavaria'],
+    ['Travis County, Texas', 'Travis County'],
+  ]) {
+    const region = await resolveRegionRingForQuery(query, undefined, geocoder);
+    assert.equal(region?.name, name, query);
+    assert.equal(region.source, 'bundled-admin');
+    assert.ok(region.ring.length >= 8, `${query} has a real ring`);
+  }
+  assert.deepEqual(geocoder.calls, [], 'no geocoding');
+  assert.deepEqual(lookups, [], 'no boundary lookups');
+});
+
+test('region ring: a geocoder-typed state resolves from the bundled pack', async () => {
+  const lookups = [];
+  const { resolveRegionRingForQuery } = createAnnotationResolver({
+    featureSource: featureSource({
+      getAdministrativeAreas: async () => {
+        lookups.push('admin');
+        return null;
+      },
+    }),
+  });
+  // "Georgia" alone is also a country, so the words don't settle it; the
+  // geocoder's state type and point inside the US state do.
+  const geocoder = geocoderFor({
+    lat: 32.16,
+    lng: -82.9,
+    label: 'Georgia, USA',
+    name: 'Georgia',
+    types: ['administrative_area_level_1', 'political'],
+  });
+  const region = await resolveRegionRingForQuery(
+    'Georgia',
+    undefined,
+    geocoder,
+  );
+  assert.equal(region?.name, 'Georgia');
+  assert.ok(region.ring.length >= 8);
+  assert.deepEqual(geocoder.calls, ['Georgia']);
+  assert.deepEqual(lookups, [], 'no boundary lookups');
+});

src/annotations/screenAnnotationRenderer.test.mjs

@@ -1,164 +1,177 @@
+import '../testSupport/registerDom.mjs';
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import * as Cesium from 'cesium';
+import { createApp, nextTick } from 'vue';
+import { createPinia } from 'pinia';
+import { useScreenAnnotationsStore } from '../ui/stores/screenAnnotations.js';
+import ScreenAnnotations from '../ui/views/panels/ScreenAnnotations.vue';
 import { createScreenAnnotationRenderer } from './screenAnnotationRenderer.js';
 
-class FakeClassList {
-  constructor(owner) {
-    this.owner = owner;
-    this.names = new Set();
-  }
-
-  reset(value) {
-    this.names = new Set(String(value || '').split(/\s+/).filter(Boolean));
-  }
-
-  add(...names) {
-    for (const name of names) this.names.add(name);
-    this.owner.attributes.set('class', Array.from(this.names).join(' '));
-  }
-
-  remove(...names) {
-    for (const name of names) this.names.delete(name);
-    this.owner.attributes.set('class', Array.from(this.names).join(' '));
-  }
-
-  contains(name) {
-    return this.names.has(name);
-  }
+// happy-dom does not lay out SVG; every element measures as a 40 x 16 box.
+for (const type of [globalThis.SVGElement, globalThis.SVGGraphicsElement]) {
+  if (type) type.prototype.getBBox = () => ({ x: 0, y: 0, width: 40, height: 16 });
 }
 
-class FakeElement {
-  constructor(tagName) {
-    this.tagName = tagName;
-    this.attributes = new Map();
-    this.children = [];
-    this.parentNode = null;
-    this.style = {};
-    this.classList = new FakeClassList(this);
-    this.textContent = '';
-  }
+const settle = async () => {
+  for (let flush = 0; flush < 4; flush += 1) await nextTick();
+};
 
-  setAttribute(name, value) {
-    this.attributes.set(name, String(value));
-    if (name === 'class') this.classList.reset(value);
-  }
-
-  getAttribute(name) {
-    return this.attributes.get(name) ?? null;
-  }
-
-  set className(value) {
-    this.setAttribute('class', value);
-  }
-
-  get className() {
-    return this.getAttribute('class') || '';
-  }
-
-  set id(value) {
-    this.setAttribute('id', value);
-  }
-
-  get id() {
-    return this.getAttribute('id') || '';
-  }
-
-  appendChild(child) {
-    child.parentNode = this;
-    this.children.push(child);
-    return child;
-  }
-
-  removeChild(child) {
-    const index = this.children.indexOf(child);
-    if (index >= 0) this.children.splice(index, 1);
-    child.parentNode = null;
-    return child;
-  }
-
-  remove() {
-    this.parentNode?.removeChild(this);
-  }
-
-  querySelector(selector) {
-    return this.querySelectorAll(selector)[0] || null;
-  }
-
-  querySelectorAll(selector) {
-    const className = selector.startsWith('.') ? selector.slice(1) : null;
-    const matches = [];
-    const visit = (node) => {
-      for (const child of node.children) {
-        if (className && child.classList.contains(className)) matches.push(child);
-        visit(child);
-      }
-    };
-    visit(this);
-    return matches;
-  }
-
-  addEventListener() {}
-
-  getBBox() {
-    return { x: 0, y: 0, width: 40, height: 16 };
-  }
-
-  set innerHTML(value) {
-    this._innerHTML = value;
-  }
-}
-
-function fakeDocument() {
-  const head = new FakeElement('head');
-  const body = new FakeElement('body');
-  const roots = [head, body];
-  return {
-    head,
-    body,
-    createElement: (tag) => new FakeElement(tag),
-    createElementNS: (_namespace, tag) => new FakeElement(tag),
-    getElementById(id) {
-      let found = null;
-      const visit = (node) => {
-        if (node.getAttribute('id') === id) found = node;
-        for (const child of node.children) visit(child);
-      };
-      for (const root of roots) visit(root);
-      return found;
-    },
-  };
-}
-
-function findAnnotationGroup(document) {
-  const layer = document.body.children.find((child) => child.classList.contains('gev-screen-whiteboard'));
-  const svg = layer.children.find((child) => child.classList.contains('gev-screen-whiteboard-svg'));
-  return {
-    svg,
-    group: svg.children.find((child) => child.classList.contains('gev-anno')),
-  };
-}
-
-test('outline upgrade preserves the existing SVG group identity', (t) => {
-  const originalDocument = globalThis.document;
+/** Mount the board's view; animation frames run when `frames()` is called. */
+function board(t) {
+  document.body.replaceChildren();
+  const pinia = createPinia();
+  const store = useScreenAnnotationsStore(pinia);
+  const app = createApp(ScreenAnnotations).use(pinia);
+  app.mount(document.body.appendChild(document.createElement('div')));
+  const queued = [];
   const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
-  globalThis.document = fakeDocument();
-  globalThis.requestAnimationFrame = (callback) => { callback(); return 1; };
+  globalThis.requestAnimationFrame = (callback) => queued.push(callback);
   t.after(() => {
-    if (originalDocument === undefined) delete globalThis.document;
-    else globalThis.document = originalDocument;
-    if (originalRequestAnimationFrame === undefined) delete globalThis.requestAnimationFrame;
-    else globalThis.requestAnimationFrame = originalRequestAnimationFrame;
+    globalThis.requestAnimationFrame = originalRequestAnimationFrame;
+    app.unmount();
   });
+  const frames = () => {
+    for (const callback of queued.splice(0)) callback();
+  };
+  const svg = () => document.querySelector('.gev-screen-whiteboard-svg');
+  const groups = () => [...(svg()?.querySelectorAll('g.gev-anno') ?? [])];
+  return { store, frames, svg, groups };
+}
 
+function cameraOver(lon, lat) {
+  const positionWC = Cesium.Cartesian3.fromDegrees(lon, lat, 1000);
+  const directionWC = Cesium.Cartesian3.normalize(
+    Cesium.Cartesian3.negate(positionWC, new Cesium.Cartesian3()),
+    new Cesium.Cartesian3(),
+  );
+  // Low enough that point marks keep their full size.
+  return { positionWC, directionWC, positionCartographic: { height: 500 } };
+}
+
+function sceneFor(camera, extra = {}) {
+  return {
+    camera,
+    canvas: { clientWidth: 800, clientHeight: 600, width: 800, height: 600 },
+    clampToHeightSupported: false,
+    postRender: { addEventListener() {}, removeEventListener() {} },
+    ...extra,
+  };
+}
+
+/** Project every point to the given window position for the test's length. */
+function projectTo(t, at) {
+  const original = Cesium.SceneTransforms.worldToWindowCoordinates;
+  Cesium.SceneTransforms.worldToWindowCoordinates = typeof at === 'function' ? at : () => at;
+  t.after(() => {
+    Cesium.SceneTransforms.worldToWindowCoordinates = original;
+  });
+}
+
+test('a pin renders its reticle, leader and callout on the page board', async (t) => {
+  const { store, frames, svg, groups } = board(t);
+  projectTo(t, { x: 200, y: 300 });
+  const camera = cameraOver(0, 0);
+  const renderer = createScreenAnnotationRenderer(
+    { scene: sceneFor(camera), camera, trackedEntity: null },
+    { store, activeTrackedReadoutId: () => null },
+  );
+  t.after(() => renderer.destroy());
+  renderer.add({
+    id: 'pin',
+    type: 'pin',
+    color: 'amber',
+    label: 'Capitol',
+    alpha: 1,
+    anchor: { lon: 0, lat: 0, height: 0 },
+  });
+  await settle();
+  const layer = document.body.querySelector(':scope > .gev-screen-whiteboard');
+  assert.ok(layer);
+  assert.equal(svg().getAttribute('preserveAspectRatio'), 'none');
+  assert.equal(svg().getAttribute('viewBox'), '0 0 800 600');
+  assert.ok(svg().querySelector('defs > filter#gev-sketch > feTurbulence'));
+  const [group] = groups();
+  assert.equal(group.getAttribute('class'), 'gev-anno');
+  assert.equal(group.getAttribute('opacity'), '1');
+  assert.deepEqual(
+    [...group.children].map((child) => [child.tagName.toLowerCase(), child.getAttribute('class')]),
+    [
+      ['circle', 'gev-anno-ring gev-pulse'],
+      ['circle', 'gev-anno-ring'],
+      ['circle', 'gev-anno-dot'],
+      ['line', 'gev-anno-leader'],
+      ['g', 'gev-anno-callout'],
+    ],
+  );
+  const [outer, inner, dot, leader, callout] = group.children;
+  assert.equal(outer.getAttribute('stroke'), '#ffb547');
+  assert.equal(outer.getAttribute('cx'), '200.0');
+  assert.equal(outer.getAttribute('r'), '34.0');
+  assert.equal(inner.getAttribute('fill-opacity'), '0.12');
+  assert.equal(inner.getAttribute('filter'), 'url(#gev-sketch)');
+  assert.equal(dot.getAttribute('r'), '5.0');
+  assert.equal(leader.getAttribute('x1'), '200.0');
+  assert.equal(leader.getAttribute('x2'), '218.0');
+  // The card is sized to its measured text, and the leader meets its bottom.
+  const [card, accent, text] = callout.children;
+  assert.equal(text.textContent, 'Capitol');
+  assert.equal(text.getAttribute('x'), '9');
+  assert.equal(card.getAttribute('width'), '58');
+  assert.equal(card.getAttribute('height'), '26');
+  assert.equal(accent.getAttribute('height'), '18');
+  assert.equal(accent.getAttribute('fill'), '#ffb547');
+  assert.equal(callout.getAttribute('transform'), 'translate(218.0, 266.0)');
+  assert.equal(leader.getAttribute('y2'), '292.0');
+  frames();
+  await settle();
+  assert.equal(group.getAttribute('class'), 'gev-anno gev-in');
+});
+
+test('an arrow defines its arrowhead and drops the dash once drawn on', async (t) => {
+  const { store, frames, svg, groups } = board(t);
+  let calls = 0;
+  projectTo(t, () => (calls++ % 2 ? { x: 400, y: 100 } : { x: 100, y: 100 }));
+  const camera = cameraOver(0, 0);
+  const renderer = createScreenAnnotationRenderer(
+    { scene: sceneFor(camera), camera, trackedEntity: null },
+    { store, activeTrackedReadoutId: () => null },
+  );
+  t.after(() => renderer.destroy());
+  renderer.add({
+    id: 'arrow',
+    type: 'arrow',
+    color: 'green',
+    alpha: 1,
+    anchor: { lon: 0, lat: 0 },
+    to: { lon: 0.01, lat: 0 },
+  });
+  await settle();
+  const marker = svg().querySelector('defs > marker#gev-arrow-green');
+  assert.equal(marker.getAttribute('orient'), 'auto-start-reverse');
+  assert.equal(marker.querySelector('path').getAttribute('fill'), '#5dff9f');
+  const path = groups()[0].querySelector('path');
+  assert.equal(path.getAttribute('class'), 'gev-anno-arrow gev-draw');
+  assert.equal(path.getAttribute('marker-end'), 'url(#gev-arrow-green)');
+  assert.match(path.getAttribute('d'), /^M 100\.0 100\.0 Q /);
+  frames();
+  await settle();
+  const ended = new Event('transitionend', { bubbles: true });
+  ended.propertyName = 'stroke-dashoffset';
+  path.dispatchEvent(ended);
+  await settle();
+  assert.equal(path.style.strokeDasharray, 'none');
+});
+
+test('outline upgrade preserves the existing SVG group identity', async (t) => {
+  const { store, svg, groups } = board(t);
   const camera = {
     positionWC: Cesium.Cartesian3.ZERO,
     directionWC: Cesium.Cartesian3.ZERO,
     positionCartographic: { height: 1000 },
   };
   const sampledAnchors = [];
-  const scene = {
-    camera,
+  const scene = sceneFor(camera, {
     canvas: { clientWidth: 1280, clientHeight: 720, width: 1280, height: 720 },
     clampToHeightSupported: true,
     clampToHeight(world) {
@@ -169,9 +182,12 @@ test('outline upgrade preserves the existing SVG group identity', (t) => {
       ]);
       return world;
     },
-    postRender: { addEventListener() {}, removeEventListener() {} },
-  };
-  const renderer = createScreenAnnotationRenderer({ scene, camera, trackedEntity: null });
+  });
+  const renderer = createScreenAnnotationRenderer(
+    { scene, camera, trackedEntity: null },
+    { store, activeTrackedReadoutId: () => null },
+  );
+  t.after(() => renderer.destroy());
   const anno = {
     id: 'anno-fb3',
     type: 'area',
@@ -182,8 +198,11 @@ test('outline upgrade preserves the existing SVG group identity', (t) => {
     ring: null,
   };
   renderer.add(anno);
-  const before = findAnnotationGroup(globalThis.document);
-  assert.ok(before.group.querySelector('.gev-anno-ring'), 'pending area starts as a reticle');
+  await settle();
+  const [before] = groups();
+  assert.ok(before.querySelector('.gev-anno-ring'), 'pending area starts as a reticle');
+  const callout = before.querySelector('.gev-anno-callout');
+  const dot = before.querySelector('.gev-anno-dot');
 
   const labelProxy = Object.assign(Object.create(anno), {
     type: 'label',
@@ -191,47 +210,65 @@ test('outline upgrade preserves the existing SVG group identity', (t) => {
     anchor: { lon: -97.5, lat: 31.2, height: 0 },
   });
   renderer.update(labelProxy);
-  const after = findAnnotationGroup(globalThis.document);
+  await settle();
+  const [after] = groups();
 
-  assert.equal(after.group, before.group, 'the rendered group is mutated, not replaced');
+  assert.ok(after === before, 'the rendered group is mutated, not replaced');
   assert.deepEqual(sampledAnchors.at(-1), [-97.5, 31.2], 'the existing group projects from the re-seated anchor');
-  assert.equal(after.svg.children.filter((child) => child.classList.contains('gev-anno')).length, 1);
-  assert.equal(after.group.querySelector('.gev-anno-ring'), null, 'reticle rings are removed in place');
-  assert.ok(after.group.querySelector('.gev-anno-callout'), 'the original callout remains in the group');
-  renderer.destroy();
+  assert.equal(groups().length, 1);
+  assert.equal(after.querySelector('.gev-anno-ring'), null, 'reticle rings are removed in place');
+  assert.ok(after.querySelector('.gev-anno-callout') === callout, 'the original callout remains in the group');
+  assert.ok(after.querySelector('.gev-anno-dot') === dot, 'the anchor dot remains in the group');
+  assert.ok(svg());
 });
 
-test('annotation fade consumes the actual tracked host paint rectangle after layout', (t) => {
-  const originalDocument = globalThis.document;
-  const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
-  const originalProjection = Cesium.SceneTransforms.worldToWindowCoordinates;
-  globalThis.document = fakeDocument();
-  globalThis.requestAnimationFrame = (callback) => { callback(); return 1; };
-  Cesium.SceneTransforms.worldToWindowCoordinates = () => ({ x: 0, y: 0 });
-  t.after(() => {
-    Cesium.SceneTransforms.worldToWindowCoordinates = originalProjection;
-    if (originalDocument === undefined) delete globalThis.document;
-    else globalThis.document = originalDocument;
-    if (originalRequestAnimationFrame === undefined) delete globalThis.requestAnimationFrame;
-    else globalThis.requestAnimationFrame = originalRequestAnimationFrame;
-  });
-
-  const positionWC = Cesium.Cartesian3.fromDegrees(0, 0, 1000);
-  const directionWC = Cesium.Cartesian3.normalize(
-    Cesium.Cartesian3.negate(positionWC, new Cesium.Cartesian3()),
-    new Cesium.Cartesian3(),
-  );
-  const camera = { positionWC, directionWC, positionCartographic: { height: 1000 } };
-  const scene = {
-    camera,
-    canvas: { clientWidth: 800, clientHeight: 600, width: 800, height: 600 },
-    clampToHeightSupported: false,
-    postRender: { addEventListener() {}, removeEventListener() {} },
+test('a callout whose text changes is sized to the new text', async (t) => {
+  const { store, groups } = board(t);
+  projectTo(t, { x: 100, y: 100 });
+  // Text measures 7px a character; everything else keeps the shared box.
+  const original = globalThis.SVGGraphicsElement.prototype.getBBox;
+  globalThis.SVGGraphicsElement.prototype.getBBox = function () {
+    return this.tagName.toLowerCase() === 'text'
+      ? { x: 0, y: 0, width: this.textContent.length * 7, height: 16 }
+      : original.call(this);
   };
+  t.after(() => {
+    globalThis.SVGGraphicsElement.prototype.getBBox = original;
+  });
+  const camera = cameraOver(0, 0);
+  const renderer = createScreenAnnotationRenderer(
+    { scene: sceneFor(camera), camera, trackedEntity: null },
+    { store, activeTrackedReadoutId: () => null },
+  );
+  t.after(() => renderer.destroy());
+  const anno = {
+    id: 'upgrade',
+    type: 'label',
+    color: 'primary',
+    label: 'Texas',
+    alpha: 1,
+    anchor: { lon: 0, lat: 0 },
+  };
+  renderer.add(anno);
+  await settle();
+  const card = () => groups()[0].querySelector('.gev-anno-card');
+  assert.equal(card().getAttribute('width'), String(5 * 7 + 18));
+  renderer.update({ ...anno, outlineUnavailable: true });
+  await settle();
+  const text = 'Texas · Detailed outline unavailable';
+  assert.equal(groups()[0].querySelector('text').textContent, text);
+  assert.equal(card().getAttribute('width'), String(text.length * 7 + 18));
+});
+
+test('annotation fade consumes the actual tracked host paint rectangle after layout', async (t) => {
+  const { store, groups } = board(t);
+  projectTo(t, { x: 0, y: 0 });
+  const camera = cameraOver(0, 0);
   const paintRectCalls = [];
   const renderer = createScreenAnnotationRenderer(
-    { scene, camera, trackedEntity: null },
+    { scene: sceneFor(camera), camera, trackedEntity: null },
     {
+      store,
       activeTrackedReadoutId: () => 'installations:test',
       overlayPaintRect(sourceId, entryId) {
         paintRectCalls.push({ sourceId, entryId });
@@ -239,6 +276,7 @@ test('annotation fade consumes the actual tracked host paint rectangle after lay
       },
     },
   );
+  t.after(() => renderer.destroy());
   renderer.add({
     id: 'anno-overlap',
     type: 'label',
@@ -247,7 +285,8 @@ test('annotation fade consumes the actual tracked host paint rectangle after lay
     alpha: 1,
     anchor: { lon: 0, lat: 0, height: 0 },
   });
-  const { group } = findAnnotationGroup(globalThis.document);
+  await settle();
+  const [group] = groups();
   assert.deepEqual(paintRectCalls.at(-1), {
     sourceId: 'tracked',
     entryId: 'installations:test',
@@ -256,44 +295,59 @@ test('annotation fade consumes the actual tracked host paint rectangle after lay
     Number(group.getAttribute('opacity')) < 1,
     'final annotation bbox fades against the complete painted card rectangle',
   );
+});
+
+test('a removed mark fades out, then leaves the board', async (t) => {
+  const { store, groups } = board(t);
+  projectTo(t, { x: 100, y: 100 });
+  const camera = cameraOver(0, 0);
+  const renderer = createScreenAnnotationRenderer(
+    { scene: sceneFor(camera), camera, trackedEntity: null },
+    { store, activeTrackedReadoutId: () => null },
+  );
+  t.after(() => renderer.destroy());
+  const anno = {
+    id: 'fading',
+    type: 'label',
+    color: 'primary',
+    label: 'Gone soon',
+    alpha: 1,
+    anchor: { lon: 0, lat: 0 },
+  };
+  renderer.add(anno);
+  await settle();
+  const [group] = groups();
+  renderer.remove(anno);
+  // A new mark for the same place gets its own group beside the fading one.
+  renderer.add(anno);
+  await settle();
+  assert.equal(group.getAttribute('class'), 'gev-anno gev-out');
+  assert.equal(groups().length, 2);
+  assert.ok(groups()[1] !== group);
+  await new Promise((resolve) => setTimeout(resolve, 400));
+  await settle();
+  assert.deepEqual(groups().length, 1);
+  assert.equal(group.isConnected, false);
   renderer.destroy();
+  await settle();
+  assert.equal(document.querySelector('.gev-screen-whiteboard'), null);
 });
 
 // ── Partial-add unwind (review round 2) ───────────────────────────────────────
 //
-// add() inserts the group and records it, then does more live-document work
-// (draw-on wiring, the first projection pass). A throw in that tail used to
-// leave an ORPHANED <g> plus a record nobody owned — the engine's rollback only
-// deletes its own map entry — so re-annotating the same place stacked a second
-// mark over the corpse.
+// add() records the mark, then does more work (presenting it, the first
+// projection pass). A throw in that tail used to leave an ORPHANED mark plus a
+// record nobody owned — the engine's rollback only deletes its own map entry —
+// so re-annotating the same place stacked a second mark over the corpse.
 
-test('an add that throws after inserting its group unwinds instead of orphaning it', (t) => {
-  const originalDocument = globalThis.document;
-  const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
-  const originalProjection = Cesium.SceneTransforms.worldToWindowCoordinates;
-  globalThis.document = fakeDocument();
-  globalThis.requestAnimationFrame = (callback) => { callback(); return 1; };
-  t.after(() => {
-    Cesium.SceneTransforms.worldToWindowCoordinates = originalProjection;
-    if (originalDocument === undefined) delete globalThis.document;
-    else globalThis.document = originalDocument;
-    if (originalRequestAnimationFrame === undefined) delete globalThis.requestAnimationFrame;
-    else globalThis.requestAnimationFrame = originalRequestAnimationFrame;
-  });
-
-  const positionWC = Cesium.Cartesian3.fromDegrees(0, 0, 1000);
-  const directionWC = Cesium.Cartesian3.normalize(
-    Cesium.Cartesian3.negate(positionWC, new Cesium.Cartesian3()),
-    new Cesium.Cartesian3(),
+test('an add that throws after inserting its group unwinds instead of orphaning it', async (t) => {
+  const { store, groups } = board(t);
+  const camera = cameraOver(0, 0);
+  const renderer = createScreenAnnotationRenderer(
+    { scene: sceneFor(camera, { canvas: { clientWidth: 1280, clientHeight: 720, width: 1280, height: 720 } }), camera, trackedEntity: null },
+    { store, activeTrackedReadoutId: () => null },
   );
-  const camera = { positionWC, directionWC, positionCartographic: { height: 1000 } };
-  const scene = {
-    camera,
-    canvas: { clientWidth: 1280, clientHeight: 720, width: 1280, height: 720 },
-    clampToHeightSupported: false,
-    postRender: { addEventListener() {}, removeEventListener() {} },
-  };
-  const renderer = createScreenAnnotationRenderer({ scene, camera, trackedEntity: null });
+  t.after(() => renderer.destroy());
   const anno = {
     id: 'anno-partial-screen',
     type: 'pin',
@@ -303,26 +357,36 @@ test('an add that throws after inserting its group unwinds instead of orphaning
     anchor: { lon: 0, lat: 0, height: 0 },
   };
 
-  // The group is in the document and recorded by the time add() reaches its
-  // first projection pass — so a throw there is real partial state, not a
-  // clean bail-out.
-  Cesium.SceneTransforms.worldToWindowCoordinates = () => { throw new Error('projection failed'); };
+  // The mark is on the board by the time add() reaches its first projection
+  // pass — so a throw there is real partial state, not a clean bail-out.
+  projectTo(t, () => {
+    throw new Error('projection failed');
+  });
   assert.throws(() => renderer.add(anno), /projection failed/);
   Cesium.SceneTransforms.worldToWindowCoordinates = () => ({ x: 0, y: 0 });
-  const { svg } = findAnnotationGroup(globalThis.document);
-  assert.equal(
-    svg.children.filter((child) => child.classList.contains('gev-anno')).length,
-    0,
-    'the half-built group must not stay in the document',
-  );
+  await settle();
+  assert.equal(groups().length, 0, 'the half-built group must not stay in the document');
 
   // The id is free again: a retry draws exactly one mark, and remove() still
   // owns it (a leaked record would leave a second group behind).
   renderer.add(anno);
-  assert.equal(
-    svg.children.filter((child) => child.classList.contains('gev-anno')).length,
-    1,
-    'the retry must draw one mark, not stack over an orphan',
-  );
-  renderer.destroy();
+  await settle();
+  assert.equal(groups().length, 1, 'the retry must draw one mark, not stack over an orphan');
+});
+
+test("an earlier renderer leaves a later renderer's board alone", async (t) => {
+  const { store, groups } = board(t);
+  projectTo(t, { x: 100, y: 100 });
+  const camera = cameraOver(0, 0);
+  const viewer = { scene: sceneFor(camera), camera, trackedEntity: null };
+  const options = { store, activeTrackedReadoutId: () => null };
+  const earlier = createScreenAnnotationRenderer(viewer, options);
+  const later = createScreenAnnotationRenderer(viewer, options);
+  t.after(() => later.destroy());
+  later.add({ id: 'kept', type: 'label', label: 'Kept', alpha: 1, anchor: { lon: 0, lat: 0 } });
+  earlier.add({ id: 'ignored', type: 'label', label: 'Ignored', alpha: 1, anchor: { lon: 0, lat: 0 } });
+  earlier.destroy();
+  await settle();
+  assert.equal(groups().length, 1);
+  assert.equal(groups()[0].querySelector('text').textContent, 'Kept');
 });

src/annotations/worldAnnotationRenderer.js

@@ -1,4 +1,5 @@
 import * as Cesium from 'cesium';
+import { showOsmCredit, hideOsmCredit } from '../data/dataCredits.js';
 
 /**
  * World-space annotation renderer (Direction A).
@@ -10,7 +11,7 @@ import * as Cesium from 'cesium';
  * IMPORTANT — drawing on Google Photorealistic 3D Tiles:
  *   The Cesium globe is hidden, so there is no terrain to clamp to. Ground
  *   geometry (areas, rings, connectors) is draped onto the photoreal tiles with
- *   `classificationType: CESIUM_3D_TILE`; points and labels clamp to the tile
+ *   `classificationType: CESIUM_3D_TILE`; points clamp to the tile
  *   surface with `heightReference: CLAMP_TO_GROUND` (which requires the tileset
  *   to have `enableCollision = true`, set in initAnnotations). This keeps marks
  *   sitting ON the world instead of buried at sea level.
@@ -30,12 +31,26 @@ const PALETTE = {
   red: '#ff6b6b',
 };
 
-const CLASSIFY = Cesium.ClassificationType.CESIUM_3D_TILE;
+/**
+ * What a draped mark is allowed to paint onto.
+ *
+ * This was CESIUM_3D_TILE, which is right with Google's photoreal tiles under
+ * the camera and wrong everywhere else: on a keyless boot (Esri or OSM imagery
+ * on Cesium's own globe) there are no 3D tiles to classify against, so every
+ * area fill, area outline, route and arrow rendered to nothing. The labels
+ * showed and the geometry did not, which reads as a broken feature rather than
+ * an unsupported surface — and it hit spoken annotations exactly as hard as
+ * hand-drawn ones.
+ *
+ * BOTH paints onto terrain AND onto 3D tiles, so one value covers both worlds.
+ */
+const CLASSIFY = Cesium.ClassificationType.BOTH;
 const CLAMP = Cesium.HeightReference.CLAMP_TO_GROUND;
 
 export function createWorldAnnotationRenderer(viewer) {
   const dataSource = new Cesium.CustomDataSource('gev-annotations');
   viewer.dataSources.add(dataSource);
+  const osmAnnotations = new Set();
 
   // Register the GevRouteFlow fabric once so Cesium's Material.fromType() can build the
   // material the route pipeline renders. The animated `time` uniform is read straight
@@ -45,7 +60,9 @@ export function createWorldAnnotationRenderer(viewer) {
   ensureFlowFabricRegistered();
 
   function colorFor(anno) {
-    return Cesium.Color.fromCssColorString(PALETTE[anno.color] || PALETTE.primary);
+    return Cesium.Color.fromCssColorString(
+      PALETTE[anno.color] || PALETTE.primary,
+    );
   }
 
   // Target-ring radius (meters) scaled to camera height so it reads at any
@@ -73,7 +90,11 @@ export function createWorldAnnotationRenderer(viewer) {
     const entities = [];
     anno._entities = entities;
 
-    if (anno.ring && anno.ring.length >= 3 && anno.footprintKind === 'building') {
+    if (
+      anno.ring &&
+      anno.ring.length >= 3 &&
+      anno.footprintKind === 'building'
+    ) {
       // Single building → the PRIMARY highlight is an extruded CLASSIFICATION
       // volume that tints the real photogrammetry mesh (dome, walls, roof —
       // everything inside the column) amber and pulses. A flat footprint
@@ -81,179 +102,224 @@ export function createWorldAnnotationRenderer(viewer) {
       // actual tiles. A faint wireframe cage rides on top as a secondary cue.
       const buffered = bufferRing(anno.ring, 3);
       const positions = Cesium.Cartesian3.fromDegreesArray(buffered.flat());
-      const groundH = sampleGroundOutside(viewer.scene, anno.ring)
-        ?? (Number.isFinite(anno.anchor.height) ? anno.anchor.height - (anno.buildingHeight || 25) : 0);
+      const groundH =
+        sampleGroundOutside(viewer.scene, anno.ring) ??
+        (Number.isFinite(anno.anchor.height)
+          ? anno.anchor.height - (anno.buildingHeight || 25)
+          : 0);
       const baseH = groundH - 3;
       // Tall headroom is free: classification only colors where tiles exist, so
       // empty air above the roof isn't tinted — this just guarantees we cover
       // under-tagged building heights.
       const topH = groundH + Math.max(18, anno.buildingHeight || 25) + 24;
       // 1) Classification volume — tints the mesh amber, pulsing.
-      entities.push(dataSource.entities.add({
-        polygon: {
-          hierarchy: new Cesium.PolygonHierarchy(positions),
-          height: baseH,
-          extrudedHeight: topH,
-          perPositionHeight: false,
-          classificationType: CLASSIFY,
-          material: new Cesium.ColorMaterialProperty(liveColor(anno, base, { alpha: 0.45, pulse: true })),
-        },
-      }));
+      entities.push(
+        dataSource.entities.add({
+          polygon: {
+            hierarchy: new Cesium.PolygonHierarchy(positions),
+            height: baseH,
+            extrudedHeight: topH,
+            perPositionHeight: false,
+            classificationType: CLASSIFY,
+            material: new Cesium.ColorMaterialProperty(
+              liveColor(anno, base, { alpha: 0.45, pulse: true }),
+            ),
+          },
+        }),
+      );
       // 2) Faint, SIMPLIFIED wireframe cage — secondary, lower opacity. Decimate
       // the footprint so the extruded outline draws ~14 clean verticals, not one
       // per (often 100+) ring vertex.
-      const cagePositions = Cesium.Cartesian3.fromDegreesArray(decimateRing(buffered, 14).flat());
-      entities.push(dataSource.entities.add({
-        polygon: {
-          hierarchy: new Cesium.PolygonHierarchy(cagePositions),
-          height: baseH,
-          extrudedHeight: topH,
-          perPositionHeight: false,
-          fill: false,
-          outline: true,
-          outlineColor: liveColor(anno, base, { alpha: 0.32, pulse: true }),
-        },
-      }));
+      const cagePositions = Cesium.Cartesian3.fromDegreesArray(
+        decimateRing(buffered, 14).flat(),
+      );
+      entities.push(
+        dataSource.entities.add({
+          polygon: {
+            hierarchy: new Cesium.PolygonHierarchy(cagePositions),
+            height: baseH,
+            extrudedHeight: topH,
+            perPositionHeight: false,
+            fill: false,
+            outline: true,
+            outlineColor: liveColor(anno, base, { alpha: 0.32, pulse: true }),
+          },
+        }),
+      );
       // 3) Crisp draped base outline so the footprint reads on the ground.
-      entities.push(dataSource.entities.add({
-        polyline: {
-          positions,
-          width: 3,
-          material: new Cesium.PolylineGlowMaterialProperty({ glowPower: 0.25, color: liveColor(anno, base, { alpha: 0.7 }) }),
-          clampToGround: true,
-          classificationType: CLASSIFY,
-        },
-      }));
-      if (anno.label) entities.push(labelMarker(anno, base, { point: false }));
+      entities.push(
+        dataSource.entities.add({
+          polyline: {
+            positions,
+            width: 3,
+            material: new Cesium.PolylineGlowMaterialProperty({
+              glowPower: 0.25,
+              color: liveColor(anno, base, { alpha: 0.7 }),
+            }),
+            clampToGround: true,
+            classificationType: CLASSIFY,
+          },
+        }),
+      );
     } else if (anno.ring && anno.ring.length >= 3) {
-      // Larger area (district / compound / park) → flat fill draped on the tiles
-      // + a glowing outline. Draping is right here: you can't extrude a whole
-      // neighbourhood, and the GIS overlay shows the boundary clearly.
-      const fillPositions = Cesium.Cartesian3.fromDegreesArray(anno.ring.flat());
-      entities.push(dataSource.entities.add({
-        polygon: {
-          hierarchy: new Cesium.PolygonHierarchy(fillPositions),
-          // Synthesized (approximate) areas get a fainter fill so they don't read as solid.
-          material: new Cesium.ColorMaterialProperty(liveColor(anno, base, { alpha: anno.synthesized ? 0.10 : 0.20, pulse: true })),
-          classificationType: CLASSIFY,
-        },
-      }));
-      entities.push(dataSource.entities.add({
-        polyline: {
-          positions: fillPositions,
-          width: 6,
-          // Synthesized → DASHED outline (signals "approximate, not an authoritative
-          // boundary", research §8.4/§8.6); real footprints → solid glow.
-          material: anno.synthesized
-            ? new Cesium.PolylineDashMaterialProperty({ color: liveColor(anno, base, { alpha: 0.95 }), dashLength: 24 })
-            : new Cesium.PolylineGlowMaterialProperty({ glowPower: 0.35, color: liveColor(anno, base, { alpha: 1 }) }),
-          clampToGround: true,
-          classificationType: CLASSIFY,
-        },
-      }));
-      if (anno.label) entities.push(labelMarker(anno, base, { point: false }));
-    } else if (anno.type === 'route' && Array.isArray(anno.path) && anno.path.length >= 2) {
+      // Larger area (district / compound / park / state) → flat fill draped on
+      // the tiles + a glowing outline. Draping is right here: you can't extrude
+      // a whole neighbourhood, and the GIS overlay shows the boundary clearly.
+      // A multi-part outline (`anno.polygons`: Hawaii's islands, Berlin as a
+      // hole in Brandenburg) draws every part with its holes. All parts share
+      // ONE fill and ONE line material, so Cesium batches the whole mark into a
+      // ground primitive per kind instead of one per island.
+      const parts =
+        Array.isArray(anno.polygons) && anno.polygons.length
+          ? anno.polygons
+          : [[anno.ring]];
+      const fillMaterial = new Cesium.ColorMaterialProperty(
+        // Synthesized (approximate) areas get a fainter fill so they don't read as solid.
+        liveColor(anno, base, {
+          alpha: anno.synthesized ? 0.1 : 0.2,
+          pulse: true,
+        }),
+      );
+      // Synthesized → DASHED outline (signals "approximate, not an authoritative
+      // boundary", research §8.4/§8.6); real footprints → solid glow.
+      const lineMaterial = anno.synthesized
+        ? new Cesium.PolylineDashMaterialProperty({
+            color: liveColor(anno, base, { alpha: 0.95 }),
+            dashLength: 24,
+          })
+        : new Cesium.PolylineGlowMaterialProperty({
+            glowPower: 0.35,
+            color: liveColor(anno, base, { alpha: 1 }),
+          });
+      for (const [outer, ...holes] of parts) {
+        if (!Array.isArray(outer) || outer.length < 3) continue;
+        const rings = [outer, ...holes.filter((h) => h?.length >= 3)];
+        entities.push(
+          dataSource.entities.add({
+            polygon: {
+              hierarchy: new Cesium.PolygonHierarchy(
+                Cesium.Cartesian3.fromDegreesArray(outer.flat()),
+                rings
+                  .slice(1)
+                  .map(
+                    (hole) =>
+                      new Cesium.PolygonHierarchy(
+                        Cesium.Cartesian3.fromDegreesArray(hole.flat()),
+                      ),
+                  ),
+              ),
+              material: fillMaterial,
+              classificationType: CLASSIFY,
+            },
+          }),
+        );
+        for (const ring of rings) {
+          entities.push(
+            dataSource.entities.add({
+              polyline: {
+                positions: Cesium.Cartesian3.fromDegreesArray(
+                  closedRing(ring).flat(),
+                ),
+                width: 6,
+                material: lineMaterial,
+                clampToGround: true,
+                classificationType: CLASSIFY,
+              },
+            }),
+          );
+        }
+      }
+    } else if (
+      anno.type === 'route' &&
+      Array.isArray(anno.path) &&
+      anno.path.length >= 2
+    ) {
       // A real path (street-following) draped on the 3D tiles, with dashes that
       // FLOW toward the destination (custom st.s + time material; works on the
       // clamped/classified ground polyline).
       const positions = Cesium.Cartesian3.fromDegreesArray(
         anno.path.flatMap((p) => [p.lon, p.lat]),
       );
-      entities.push(dataSource.entities.add({
-        polyline: {
-          positions,
-          width: 9,
-          material: new FlowMaterialProperty(PALETTE[anno.color] || PALETTE.primary),
-          clampToGround: true,
-          classificationType: CLASSIFY,
-        },
-      }));
-      if (anno.label) entities.push(labelMarker(anno, base, { point: false }));
+      entities.push(
+        dataSource.entities.add({
+          polyline: {
+            positions,
+            width: 9,
+            material: new FlowMaterialProperty(
+              PALETTE[anno.color] || PALETTE.primary,
+            ),
+            clampToGround: true,
+            classificationType: CLASSIFY,
+          },
+        }),
+      );
+      osmAnnotations.add(anno);
+      showOsmCredit(viewer, anno);
     } else if (anno.type === 'arrow' && anno.to) {
       // Connector draped across the ground from origin to destination.
       const positions = [
         Cesium.Cartesian3.fromDegrees(anno.anchor.lon, anno.anchor.lat),
         Cesium.Cartesian3.fromDegrees(anno.to.lon, anno.to.lat),
       ];
-      entities.push(dataSource.entities.add({
-        polyline: {
-          positions,
-          width: 16,
-          material: new Cesium.PolylineArrowMaterialProperty(liveColor(anno, base, { alpha: 0.95 })),
-          clampToGround: true,
-          classificationType: CLASSIFY,
-        },
-      }));
-      if (anno.label) {
-        const mid = {
-          lon: (anno.anchor.lon + anno.to.lon) / 2,
-          lat: (anno.anchor.lat + anno.to.lat) / 2,
-        };
-        entities.push(dataSource.entities.add({
-          position: Cesium.Cartesian3.fromDegrees(mid.lon, mid.lat),
-          label: labelGraphic(anno, base),
-        }));
-      }
+      entities.push(
+        dataSource.entities.add({
+          polyline: {
+            positions,
+            width: 16,
+            material: new Cesium.PolylineArrowMaterialProperty(
+              liveColor(anno, base, { alpha: 0.95 }),
+            ),
+            clampToGround: true,
+            classificationType: CLASSIFY,
+          },
+        }),
+      );
     } else {
       // pin / highlight / label — a camera-proportional target ring + a marker.
       if (anno.type !== 'label') {
         // Radius scales with camera height so the ring reads at any altitude.
         // semiMajor === semiMinor is required AND must hold every frame, so both
         // axes read the SAME ringRadius() (camera height is constant per frame).
-        entities.push(dataSource.entities.add({
-          position: Cesium.Cartesian3.fromDegrees(anno.anchor.lon, anno.anchor.lat),
-          ellipse: {
-            semiMajorAxis: new Cesium.CallbackProperty(ringRadius, false),
-            semiMinorAxis: new Cesium.CallbackProperty(ringRadius, false),
-            material: new Cesium.ColorMaterialProperty(liveColor(anno, base, { alpha: 0.38, pulse: true })),
-            outline: false,
-            classificationType: CLASSIFY,
-          },
-        }));
+        entities.push(
+          dataSource.entities.add({
+            position: Cesium.Cartesian3.fromDegrees(
+              anno.anchor.lon,
+              anno.anchor.lat,
+            ),
+            ellipse: {
+              semiMajorAxis: new Cesium.CallbackProperty(ringRadius, false),
+              semiMinorAxis: new Cesium.CallbackProperty(ringRadius, false),
+              material: new Cesium.ColorMaterialProperty(
+                liveColor(anno, base, { alpha: 0.38, pulse: true }),
+              ),
+              outline: false,
+              classificationType: CLASSIFY,
+            },
+          }),
+        );
       }
-      entities.push(labelMarker(anno, base, { point: true }));
+      entities.push(pointMarker(anno, base));
     }
   }
 
-  // A clamped point + (optional) label that sits on the tile surface.
-  function labelMarker(anno, base, { point }) {
+  // Captions belong to the hybrid renderer's screen-space callouts.
+  function pointMarker(anno, base) {
     return dataSource.entities.add({
       position: Cesium.Cartesian3.fromDegrees(anno.anchor.lon, anno.anchor.lat),
-      point: point ? {
+      point: {
         pixelSize: anno.type === 'label' ? 8 : 14,
         color: liveColor(anno, base, { alpha: 1 }),
         outlineColor: liveColor(anno, Cesium.Color.WHITE, { alpha: 0.95 }),
         outlineWidth: 3,
         heightReference: CLAMP,
         disableDepthTestDistance: Number.POSITIVE_INFINITY,
-      } : undefined,
-      label: anno.label ? labelGraphic(anno, base) : undefined,
+      },
     });
   }
 
-  function labelGraphic(anno, base) {
-    return {
-      text: anno.label,
-      font: '600 14px "Inter", system-ui, sans-serif',
-      fillColor: liveColor(anno, Cesium.Color.WHITE, { alpha: 1 }),
-      outlineColor: liveColor(anno, Cesium.Color.BLACK, { alpha: 0.85 }),
-      outlineWidth: 3,
-      style: Cesium.LabelStyle.FILL_AND_OUTLINE,
-      verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
-      pixelOffset: new Cesium.Cartesian2(0, -16),
-      showBackground: true,
-      backgroundColor: new Cesium.CallbackProperty(
-        () => Cesium.Color.fromCssColorString('#0b1622').withAlpha(0.72 * (anno.alpha ?? 1)),
-        false,
-      ),
-      backgroundPadding: new Cesium.Cartesian2(8, 5),
-      heightReference: CLAMP,
-      disableDepthTestDistance: Number.POSITIVE_INFINITY,
-      scaleByDistance: new Cesium.NearFarScalar(500, 1.05, 14000, 0.55),
-    };
-  }
-
   function remove(anno) {
+    hideOsmCredit(viewer, anno);
+    osmAnnotations.delete(anno);
     if (!anno?._entities) return;
     for (const entity of anno._entities) {
       try {
@@ -270,6 +336,8 @@ export function createWorldAnnotationRenderer(viewer) {
   }
 
   function destroy() {
+    for (const anno of osmAnnotations) hideOsmCredit(viewer, anno);
+    osmAnnotations.clear();
     try {
       viewer.dataSources.remove(dataSource, true);
     } catch {
@@ -323,7 +391,7 @@ let _flowFabricRegistered = false;
 /** Register the GevRouteFlow fabric ONCE so Cesium's `Material.fromType('GevRouteFlow')`
  *  can build the material the render pipeline uses. Constructing one Material with the
  *  fabric caches it under its type name. */
-function ensureFlowFabricRegistered() {
+export function ensureFlowFabricRegistered() {
   if (_flowFabricRegistered) return;
   makeRouteFlowMaterial('#ffffff'); // side effect: registers the 'GevRouteFlow' type
   _flowFabricRegistered = true;
@@ -339,13 +407,21 @@ function ensureFlowFabricRegistered() {
  * returned a standalone Material Cesium never rendered, or treated `result` as a
  * Material — both left the real uniforms untouched, so nothing animated.)
  */
-function FlowMaterialProperty(colorCss) {
+export function FlowMaterialProperty(colorCss) {
   this._color = Cesium.Color.fromCssColorString(colorCss).withAlpha(0.95);
   this._definitionChanged = new Cesium.Event();
 }
 Object.defineProperties(FlowMaterialProperty.prototype, {
-  isConstant: { get() { return false; } }, // re-evaluated each frame → it animates
-  definitionChanged: { get() { return this._definitionChanged; } },
+  isConstant: {
+    get() {
+      return false;
+    },
+  }, // re-evaluated each frame → it animates
+  definitionChanged: {
+    get() {
+      return this._definitionChanged;
+    },
+  },
 });
 FlowMaterialProperty.prototype.getType = function getType() {
   return 'GevRouteFlow';
@@ -366,6 +442,13 @@ FlowMaterialProperty.prototype.equals = function equals(other) {
   return this === other;
 };
 
+/** The ring with its first vertex repeated at the end, so an outline closes. */
+function closedRing(ring) {
+  const first = ring[0];
+  const last = ring[ring.length - 1];
+  return first[0] === last[0] && first[1] === last[1] ? ring : [...ring, first];
+}
+
 /** Evenly down-sample a [[lon,lat],...] ring to at most n points (keeps shape). */
 function decimateRing(ring, n) {
   if (ring.length <= n) return ring;
@@ -381,10 +464,17 @@ function decimateRing(ring, n) {
  * tiles under those points aren't loaded yet.
  */
 function sampleGroundOutside(scene, ring) {
-  if (!scene?.clampToHeightSupported || typeof scene.clampToHeight !== 'function') return null;
+  if (
+    !scene?.clampToHeightSupported ||
+    typeof scene.clampToHeight !== 'function'
+  )
+    return null;
   let clon = 0;
   let clat = 0;
-  for (const [lon, lat] of ring) { clon += lon; clat += lat; }
+  for (const [lon, lat] of ring) {
+    clon += lon;
+    clat += lat;
+  }
   clon /= ring.length;
   clat /= ring.length;
   const latS = 111320;
@@ -394,7 +484,16 @@ function sampleGroundOutside(scene, ring) {
     maxR = Math.max(maxR, Math.hypot((lon - clon) * lonS, (lat - clat) * latS));
   }
   const out = maxR * 1.5 + 12;
-  const dirs = [[1, 0], [-1, 0], [0, 1], [0, -1], [0.7, 0.7], [-0.7, -0.7], [0.7, -0.7], [-0.7, 0.7]];
+  const dirs = [
+    [1, 0],
+    [-1, 0],
+    [0, 1],
+    [0, -1],
+    [0.7, 0.7],
+    [-0.7, -0.7],
+    [0.7, -0.7],
+    [-0.7, 0.7],
+  ];
   const samples = [];
   for (const [dx, dy] of dirs) {
     const lon = clon + (dx * out) / lonS;
@@ -405,7 +504,9 @@ function sampleGroundOutside(scene, ring) {
         const h = Cesium.Cartographic.fromCartesian(c).height;
         if (Number.isFinite(h) && h > -430 && h < 9000) samples.push(h);
       }
-    } catch { /* tile not ready */ }
+    } catch {
+      /* tile not ready */
+    }
   }
   if (!samples.length) return null;
   samples.sort((a, b) => a - b);
@@ -420,7 +521,10 @@ function sampleGroundOutside(scene, ring) {
 function bufferRing(ring, meters) {
   let clon = 0;
   let clat = 0;
-  for (const [lon, lat] of ring) { clon += lon; clat += lat; }
+  for (const [lon, lat] of ring) {
+    clon += lon;
+    clat += lat;
+  }
   clon /= ring.length;
   clat /= ring.length;
   const latScale = 111320;

src/app/application.js

@@ -1,3 +1,4 @@
+import { mountApplicationViews } from '../ui/views/index.js';
 const START_ORDER = ['scene', 'controls', 'data', 'tools'];
 // Controls cancel restoration while the data manager and viewer still exist.
 const STOP_ORDER = ['tools', 'controls', 'data', 'scene'];
@@ -6,7 +7,9 @@ const STOP_ORDER = ['tools', 'controls', 'data', 'scene'];
  * Own application startup and teardown without importing an application entry.
  * Constructors receive earlier components, an AbortSignal and defer(cleanup).
  * Register cleanup immediately after acquiring each resource, before any await.
- * @param {{createScene:Function,createControls:Function,createData:Function,createTools:Function}} constructors
+ * The page's views render first; `omitViews` names the ones this application
+ * leaves out (see mountApplicationViews).
+ * @param {{createScene:Function,createControls:Function,createData:Function,createTools:Function,omitViews?:string[]}} constructors
  * @returns {{start:Function,destroy:Function,subscribe:Function,getState:Function,getComponents:Function}}
  */
 export function createApplication({
@@ -14,7 +17,10 @@ export function createApplication({
   createControls,
   createData,
   createTools,
+  omitViews = [],
 }) {
+  // A host's page needs its views before any phase reads the markup.
+  mountApplicationViews(globalThis.document, { omit: omitViews });
   const factories = {
     scene: createScene,
     controls: createControls,

src/app/application.test.mjs

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { createApplication } from './application.js';
+import { installTrackpadPinchZoom } from './viewer.js';
 
 const phases = ['Scene', 'Controls', 'Data', 'Tools'];
 function fixture(overrides = {}) {
@@ -30,6 +31,8 @@ test('importing and constructing the package is inactive without browser globals
   const result = spawnSync(
     process.execPath,
     [
+      // Views are single-file components; Node needs the loader hosts use.
+      '--import=gods-eye-view/build/register-vue',
       '--input-type=module',
       '-e',
       `
@@ -217,3 +220,126 @@ test('the separate viewer export imports without constructing a browser viewer',
   assert.equal(typeof createApplicationViewer, 'function');
   assert.throws(() => createApplicationViewer({}), /containers are required/);
 });
+
+test('the viewer gets the starry sky as an option, which keeps the Sun and Moon', async () => {
+  const { applicationViewerOptions } = await import('./viewer.js');
+  const { StarrySky } = await import('../sky/starrySky.js');
+  const creditContainer = {};
+  const options = applicationViewerOptions(creditContainer);
+  // CesiumWidget skips scene.sun and scene.moon when skyBox is false.
+  assert.ok(options.skyBox instanceof StarrySky);
+  assert.equal(options.creditContainer, creditContainer);
+  options.skyBox.destroy();
+});
+
+function pinchFixture({ zoomEventTypes } = {}) {
+  const handlers = new Set();
+  const relayed = [];
+  const container = {
+    addEventListener(type, handler, options) {
+      assert.equal(type, 'wheel');
+      assert.deepEqual(options, { capture: true, passive: false });
+      handlers.add(handler);
+    },
+    removeEventListener(type, handler, capture) {
+      assert.equal(type, 'wheel');
+      assert.equal(capture, true);
+      handlers.delete(handler);
+    },
+    emit(event) {
+      for (const handler of handlers) handler(event);
+    },
+  };
+  const canvas = {
+    dispatchEvent(event) {
+      // A real canvas dispatch crosses the container's capture listener again.
+      container.emit(event);
+      relayed.push(event);
+      return true;
+    },
+  };
+  const controller = { zoomEventTypes };
+  const viewer = {
+    container,
+    canvas,
+    scene: { screenSpaceCameraController: controller },
+  };
+  const createEvent = (init = {}) => ({
+    deltaX: 0,
+    deltaY: 0,
+    deltaZ: 0,
+    deltaMode: 0,
+    screenX: 0,
+    screenY: 0,
+    clientX: 0,
+    clientY: 0,
+    ctrlKey: false,
+    defaultPrevented: false,
+    propagationStopped: false,
+    preventDefault() {
+      this.defaultPrevented = true;
+    },
+    stopPropagation() {
+      this.propagationStopped = true;
+    },
+    ...init,
+  });
+  return { viewer, controller, container, handlers, relayed, createEvent };
+}
+
+test('trackpad pinch adds the Ctrl+wheel binding without replacing Cesium inputs', () => {
+  const original = [1, 2, 3];
+  const f = pinchFixture({ zoomEventTypes: original });
+  const dispose = installTrackpadPinchZoom(f.viewer, {
+    createWheelEvent: (_type, init) => f.createEvent(init),
+  });
+  assert.deepEqual(f.controller.zoomEventTypes.slice(0, 3), original);
+  assert.equal(f.controller.zoomEventTypes.length, 4);
+
+  const plain = f.createEvent({ deltaY: 2 });
+  f.container.emit(plain);
+  assert.equal(plain.defaultPrevented, false);
+  const lineMode = f.createEvent({ ctrlKey: true, deltaY: 2, deltaMode: 1 });
+  f.container.emit(lineMode);
+  assert.equal(lineMode.defaultPrevented, false);
+  assert.equal(f.relayed.length, 0);
+
+  dispose();
+  dispose();
+  assert.equal(f.controller.zoomEventTypes, original);
+  assert.equal(f.handlers.size, 0);
+});
+
+test('trackpad pinch relays pixel deltas once with bounded amplification', () => {
+  const f = pinchFixture({ zoomEventTypes: [1, 2, 3] });
+  installTrackpadPinchZoom(f.viewer, {
+    createWheelEvent: (_type, init) => f.createEvent(init),
+  });
+
+  const small = f.createEvent({ ctrlKey: true, deltaY: 2 });
+  f.container.emit(small);
+  assert.equal(small.defaultPrevented, true);
+  assert.equal(small.propagationStopped, true);
+  assert.equal(f.relayed.length, 1);
+  assert.equal(f.relayed[0].deltaY, 16);
+  assert.equal(f.relayed[0].ctrlKey, true);
+
+  const large = f.createEvent({ ctrlKey: true, deltaY: -100 });
+  f.container.emit(large);
+  assert.equal(f.relayed.length, 2);
+  assert.equal(f.relayed[1].deltaY, -120);
+});
+
+test('trackpad pinch falls back to the original event when relay construction fails', () => {
+  const f = pinchFixture({ zoomEventTypes: [1, 2, 3] });
+  installTrackpadPinchZoom(f.viewer, {
+    createWheelEvent() {
+      throw new Error('unsupported');
+    },
+  });
+  const event = f.createEvent({ ctrlKey: true, deltaY: 2 });
+  f.container.emit(event);
+  assert.equal(event.defaultPrevented, false);
+  assert.equal(event.propagationStopped, false);
+  assert.equal(f.relayed.length, 0);
+});

src/app/atmosphereCompat.js

@@ -0,0 +1,189 @@
+/**
+ * Workaround for Apple's Metal/ANGLE shader translator rejecting Cesium's
+ * per-vertex model atmosphere.
+ *
+ * Cesium's `AtmosphereStageVS` calls a function whose `out` parameters are
+ * bound DIRECTLY to varyings:
+ *
+ *   czm_computeGroundAtmosphereScattering(
+ *       v_positionWC, lightDirection,
+ *       v_atmosphereRayleighColor, v_atmosphereMieColor, v_atmosphereOpacity);
+ *
+ * ANGLE's Metal backend wraps each `out` argument in an `ANGLE_out(...)`
+ * helper that takes a `thread T &`. Vertex-output struct members live in
+ * `__metal_generic`, which cannot bind to `thread`, so the program fails to
+ * LINK (not compile) and Cesium tears the render loop down:
+ *
+ *   RuntimeError: Program failed to link. ... MSL compilation error:
+ *   reference to type 'thread float3' could not bind to an lvalue of type
+ *   '__metal_generic float3'
+ *
+ * This is the only shader in Cesium that binds varyings to `out` params --
+ * SkyAtmosphere and the ground-atmosphere fragment path both route through
+ * locals first, so they are unaffected and stay on.
+ *
+ * Cesium attaches that stage in `ModelSceneGraph.configurePipeline` under a
+ * single condition:
+ *
+ *   const fogRenderable = frameState.fog.enabled && frameState.fog.renderable;
+ *   if (fogRenderable) modelPipelineStages.push(AtmospherePipelineStage);
+ *
+ * so clearing `scene.fog.renderable` keeps the broken stage out of the
+ * pipeline entirely -- the program is never built, so it cannot fail to link.
+ *
+ * We clear `renderable` rather than `enabled` deliberately:
+ *   - `Fog.update` still computes fog density when only `renderable` is off,
+ *     preserving the distance-based screen-space-error scaling that governs
+ *     3D Tiles refinement. Clearing `enabled` returns early and forfeits it.
+ *   - `visualSettings.js` saves and restores `scene.fog.enabled` around IR
+ *     boost. Parking our fix on `enabled` would let that restore resurrect
+ *     the broken shader mid-session; `renderable` is orthogonal to it.
+ *
+ * @module app/atmosphereCompat
+ */
+
+/** Minimal vertex shader reproducing the exact out-param-to-varying bind. */
+const PROBE_VERTEX_SHADER = `#version 300 es
+precision highp float;
+in vec3 a_position;
+out vec3 v_probe;
+void writeOut(out vec3 value) { value = vec3(1.0); }
+void main() {
+  writeOut(v_probe);
+  gl_Position = vec4(a_position, 1.0);
+}`;
+
+const PROBE_FRAGMENT_SHADER = `#version 300 es
+precision highp float;
+in vec3 v_probe;
+out vec4 fragColor;
+void main() { fragColor = vec4(v_probe, 1.0); }`;
+
+/**
+ * True when the user agent is iOS or iPadOS.
+ *
+ * iPadOS 13+ defaults to desktop-mode browsing and reports `MacIntel` with no
+ * iPad token, so it is identified by touch points instead -- real Macs report
+ * `maxTouchPoints` of 0, including Apple Silicon ones that also claim
+ * `MacIntel`. Brave/Chrome/Firefox on iOS are all WebKit underneath and share
+ * the same Metal backend, so matching the platform rather than the browser is
+ * what we want.
+ */
+export function isAppleMobilePlatform(navigatorLike = globalThis.navigator) {
+  if (!navigatorLike) return false;
+  const ua = String(navigatorLike.userAgent || '');
+  if (/\b(iPad|iPhone|iPod)\b/.test(ua)) return true;
+  // Desktop-mode iPadOS presents as a Mac. What separates it from a real Mac
+  // is touch: Macs report 0 touch points, including Apple Silicon ones that
+  // also claim `MacIntel`. `navigator.platform` is deprecated and may be
+  // empty, so the UA's Macintosh token is accepted as an equal signal rather
+  // than relying on platform alone.
+  const platform = String(navigatorLike.platform || '');
+  const macLike =
+    platform === 'MacIntel' ||
+    platform === 'MacARM' ||
+    /\bMacintosh\b/.test(ua);
+  const touchPoints = Number(navigatorLike.maxTouchPoints) || 0;
+  return macLike && touchPoints > 1;
+}
+
+/**
+ * Link the probe program and report whether the driver rejects the pattern.
+ *
+ * Returns `false` when WebGL2 is unavailable so that a missing context is
+ * never mistaken for a broken driver -- Cesium has its own handling for that,
+ * and the caller still falls back to platform detection.
+ */
+export function probeOutParamVaryingLinkFailure(gl) {
+  if (!gl) return false;
+  const vs = gl.createShader(gl.VERTEX_SHADER);
+  const fs = gl.createShader(gl.FRAGMENT_SHADER);
+  const program = gl.createProgram();
+  if (!vs || !fs || !program) return false;
+  try {
+    gl.shaderSource(vs, PROBE_VERTEX_SHADER);
+    gl.compileShader(vs);
+    gl.shaderSource(fs, PROBE_FRAGMENT_SHADER);
+    gl.compileShader(fs);
+    // A compile failure here is not the bug we are probing for: the driver
+    // rejects this pattern at LINK time, after both stages compile cleanly.
+    if (
+      !gl.getShaderParameter(vs, gl.COMPILE_STATUS) ||
+      !gl.getShaderParameter(fs, gl.COMPILE_STATUS)
+    )
+      return false;
+    gl.attachShader(program, vs);
+    gl.attachShader(program, fs);
+    gl.linkProgram(program);
+    return !gl.getProgramParameter(program, gl.LINK_STATUS);
+  } catch {
+    return false;
+  } finally {
+    gl.deleteShader(vs);
+    gl.deleteShader(fs);
+    gl.deleteProgram(program);
+  }
+}
+
+/** Build a throwaway WebGL2 context for the probe, or null if unavailable. */
+function defaultProbeContext() {
+  try {
+    const canvas =
+      typeof OffscreenCanvas === 'function'
+        ? new OffscreenCanvas(1, 1)
+        : globalThis.document?.createElement('canvas');
+    return canvas?.getContext('webgl2') ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide whether the per-vertex model atmosphere must be kept out of the
+ * pipeline on this device.
+ *
+ * The probe is authoritative when it fires, so a future driver fix silently
+ * restores the effect without a code change. Platform detection is the
+ * backstop for the case where no context can be created -- on Apple mobile a
+ * link failure is fatal and unrecoverable, so we would rather lose fog than
+ * gamble the whole render loop on the probe having run.
+ */
+export function shouldDisableModelAtmosphere({
+  navigatorLike = globalThis.navigator,
+  createProbeContext = defaultProbeContext,
+} = {}) {
+  const gl = createProbeContext();
+  if (gl) {
+    let linkFails;
+    try {
+      linkFails = probeOutParamVaryingLinkFailure(gl);
+    } finally {
+      // Browsers cap live WebGL contexts (Safari especially); release the
+      // throwaway probe context now rather than waiting for GC.
+      try {
+        gl.getExtension?.('WEBGL_lose_context')?.loseContext();
+      } catch {
+        // A context that cannot be released is left to GC.
+      }
+    }
+    if (linkFails) return true;
+    // Probe ran and the driver accepted the pattern. Apple mobile is still
+    // quarantined: the probe program is far simpler than Cesium's, and a
+    // false negative there costs the entire scene.
+    return isAppleMobilePlatform(navigatorLike);
+  }
+  return isAppleMobilePlatform(navigatorLike);
+}
+
+/**
+ * Keep Cesium's broken model-atmosphere stage out of the pipeline.
+ *
+ * Returns true when the workaround was applied. Safe to call on any scene;
+ * scenes without a fog object are left untouched.
+ */
+export function applyModelAtmosphereWorkaround(scene, options = {}) {
+  if (!scene?.fog) return false;
+  if (!shouldDisableModelAtmosphere(options)) return false;
+  scene.fog.renderable = false;
+  return true;
+}

src/app/atmosphereCompat.test.mjs

@@ -0,0 +1,221 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  isAppleMobilePlatform,
+  probeOutParamVaryingLinkFailure,
+  shouldDisableModelAtmosphere,
+  applyModelAtmosphereWorkaround,
+} from './atmosphereCompat.js';
+
+const IPAD_OS12 = {
+  userAgent:
+    'Mozilla/5.0 (iPad; CPU OS 12_5 like Mac OS X) AppleWebKit/605.1.15',
+  platform: 'iPad',
+  maxTouchPoints: 5,
+};
+// iPadOS 13+ desktop mode: no iPad token, reports as a Mac.
+const IPAD_DESKTOP_MODE = {
+  userAgent:
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15',
+  platform: 'MacIntel',
+  maxTouchPoints: 5,
+};
+const MAC_DESKTOP = {
+  userAgent:
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15',
+  platform: 'MacIntel',
+  maxTouchPoints: 0,
+};
+const LINUX_DESKTOP = {
+  userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/141',
+  platform: 'Linux x86_64',
+  maxTouchPoints: 0,
+};
+
+/** Minimal GL double. `linkOk: false` mimics the Metal translator's refusal. */
+function fakeGl({ linkOk = true, compileOk = true, throwOn = null } = {}) {
+  const deleted = { shaders: 0, programs: 0 };
+  return {
+    deleted,
+    VERTEX_SHADER: 1,
+    FRAGMENT_SHADER: 2,
+    COMPILE_STATUS: 3,
+    LINK_STATUS: 4,
+    createShader: () => ({}),
+    createProgram: () => ({}),
+    shaderSource() {
+      if (throwOn === 'shaderSource') throw new Error('context lost');
+    },
+    compileShader() {},
+    attachShader() {},
+    linkProgram() {},
+    getShaderParameter: () => compileOk,
+    getProgramParameter: () => linkOk,
+    deleteShader: () => (deleted.shaders += 1),
+    deleteProgram: () => (deleted.programs += 1),
+  };
+}
+
+test('identifies iPadOS in both legacy and desktop-mode guises', () => {
+  assert.equal(isAppleMobilePlatform(IPAD_OS12), true);
+  assert.equal(isAppleMobilePlatform(IPAD_DESKTOP_MODE), true);
+});
+
+test('does not mistake a real Mac or a Linux desktop for Apple mobile', () => {
+  // Regression guard: the desktop-mode check keys on touch points, and a Mac
+  // reports the same MacIntel platform string with zero of them.
+  assert.equal(isAppleMobilePlatform(MAC_DESKTOP), false);
+  assert.equal(isAppleMobilePlatform(LINUX_DESKTOP), false);
+});
+
+test('treats a missing navigator as not-Apple rather than throwing', () => {
+  assert.equal(isAppleMobilePlatform(undefined), false);
+  assert.equal(isAppleMobilePlatform(null), false);
+});
+
+test('detects desktop-mode iPadOS without navigator.platform', () => {
+  // `navigator.platform` is deprecated and can be absent or stripped; the UA's
+  // Macintosh token plus touch points has to carry the detection on its own.
+  assert.equal(
+    isAppleMobilePlatform({
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15',
+      maxTouchPoints: 5,
+    }),
+    true,
+  );
+  // Same UA, no touch: a real Mac, which must stay untouched.
+  assert.equal(
+    isAppleMobilePlatform({
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15',
+      maxTouchPoints: 0,
+    }),
+    false,
+  );
+});
+
+test('probe reports failure only when the program fails to link', () => {
+  assert.equal(
+    probeOutParamVaryingLinkFailure(fakeGl({ linkOk: false })),
+    true,
+  );
+  assert.equal(
+    probeOutParamVaryingLinkFailure(fakeGl({ linkOk: true })),
+    false,
+  );
+});
+
+test('a compile failure is not reported as the link bug', () => {
+  // The Metal defect surfaces at link time; both stages compile cleanly.
+  // Treating a compile error as the bug would disable fog for the wrong reason.
+  assert.equal(
+    probeOutParamVaryingLinkFailure(
+      fakeGl({ compileOk: false, linkOk: false }),
+    ),
+    false,
+  );
+});
+
+test('probe releases its GL objects on both paths', () => {
+  const ok = fakeGl({ linkOk: true });
+  probeOutParamVaryingLinkFailure(ok);
+  assert.equal(ok.deleted.shaders, 2);
+  assert.equal(ok.deleted.programs, 1);
+
+  const thrown = fakeGl({ throwOn: 'shaderSource' });
+  probeOutParamVaryingLinkFailure(thrown);
+  assert.equal(thrown.deleted.shaders, 2, 'shaders freed even when GL throws');
+  assert.equal(thrown.deleted.programs, 1);
+});
+
+test('probe treats a null context as healthy, not broken', () => {
+  assert.equal(probeOutParamVaryingLinkFailure(null), false);
+});
+
+test('a failing probe disables the stage on any platform', () => {
+  assert.equal(
+    shouldDisableModelAtmosphere({
+      navigatorLike: LINUX_DESKTOP,
+      createProbeContext: () => fakeGl({ linkOk: false }),
+    }),
+    true,
+  );
+});
+
+test('a passing probe still quarantines Apple mobile but frees desktops', () => {
+  const createProbeContext = () => fakeGl({ linkOk: true });
+  assert.equal(
+    shouldDisableModelAtmosphere({
+      navigatorLike: IPAD_DESKTOP_MODE,
+      createProbeContext,
+    }),
+    true,
+  );
+  assert.equal(
+    shouldDisableModelAtmosphere({
+      navigatorLike: LINUX_DESKTOP,
+      createProbeContext,
+    }),
+    false,
+  );
+});
+
+test('falls back to platform detection when no context can be made', () => {
+  const createProbeContext = () => null;
+  assert.equal(
+    shouldDisableModelAtmosphere({
+      navigatorLike: IPAD_OS12,
+      createProbeContext,
+    }),
+    true,
+  );
+  assert.equal(
+    shouldDisableModelAtmosphere({
+      navigatorLike: MAC_DESKTOP,
+      createProbeContext,
+    }),
+    false,
+  );
+});
+
+test('applies to the scene by clearing renderable, never enabled', () => {
+  // `enabled` must survive: Fog.update short-circuits when it is false, which
+  // forfeits the density used for 3D Tiles screen-space-error scaling, and
+  // visualSettings' IR boost saves/restores that same flag.
+  const scene = { fog: { enabled: true, renderable: true } };
+  const applied = applyModelAtmosphereWorkaround(scene, {
+    navigatorLike: IPAD_DESKTOP_MODE,
+    createProbeContext: () => null,
+  });
+  assert.equal(applied, true);
+  assert.equal(scene.fog.renderable, false);
+  assert.equal(scene.fog.enabled, true);
+});
+
+test('leaves unaffected devices completely untouched', () => {
+  const scene = { fog: { enabled: true, renderable: true } };
+  const applied = applyModelAtmosphereWorkaround(scene, {
+    navigatorLike: LINUX_DESKTOP,
+    createProbeContext: () => fakeGl({ linkOk: true }),
+  });
+  assert.equal(applied, false);
+  assert.equal(scene.fog.renderable, true);
+});
+
+test('tolerates a scene with no fog object', () => {
+  assert.equal(applyModelAtmosphereWorkaround({}, {}), false);
+  assert.equal(applyModelAtmosphereWorkaround(null, {}), false);
+});
+
+test('releases the throwaway probe context after probing', () => {
+  let lost = 0;
+  const gl = fakeGl({ linkOk: true });
+  gl.getExtension = (name) =>
+    name === 'WEBGL_lose_context' ? { loseContext: () => (lost += 1) } : null;
+  shouldDisableModelAtmosphere({
+    navigatorLike: LINUX_DESKTOP,
+    createProbeContext: () => gl,
+  });
+  assert.equal(lost, 1, 'probe context must not linger until GC');
+});

src/app/catalog.js

@@ -0,0 +1,61 @@
+const CONTROL_LAYER_IDS = Object.freeze({
+  trafficLayer: 'traffic',
+  flightsLayer: 'flights',
+  militaryFlightsLayer: 'military',
+  satellitesLayer: 'satellites',
+  cctvLayer: 'cctv',
+  streetLevelLayer: 'street-level',
+  radioLayer: 'radio',
+  bikeshareLayer: 'bikeshare',
+  transitLayer: 'transit',
+  aisLiveVesselsLayer: 'ais-live-vessels',
+  militaryAwarenessLayer: 'military-awareness',
+  militaryInstallationsLayer: 'military-installations',
+  rocketLaunchesLayer: 'rocket-launches',
+  localAdsbLayer: 'local-adsb',
+});
+
+/** Capture the ordered application instances and their serialization metadata. */
+export function createLayerCatalog(layers, metadata) {
+  if (!Array.isArray(layers) || !Array.isArray(metadata))
+    throw new TypeError(
+      'Layer instances and serialization metadata are required',
+    );
+  const byId = new Map();
+  for (const layer of layers) {
+    if (typeof layer?.id !== 'string' || !layer.id || byId.has(layer.id))
+      throw new TypeError(`Invalid or duplicate catalog layer: ${layer?.id}`);
+    byId.set(layer.id, layer);
+  }
+  const ids = new Set();
+  for (const entry of metadata) {
+    if (!byId.has(entry?.id) || ids.has(entry.id))
+      throw new TypeError(
+        `Unmatched or duplicate catalog metadata: ${entry?.id}`,
+      );
+    ids.add(entry.id);
+  }
+  if (ids.size !== byId.size)
+    throw new TypeError('Catalog metadata is incomplete');
+  return Object.freeze({
+    layers: Object.freeze([...layers]),
+    metadata: Object.freeze(
+      metadata.map((entry) => Object.freeze({ ...entry })),
+    ),
+    get: (id) => byId.get(id),
+  });
+}
+
+/** Bind the current control surface to the exact instances registered by the app. */
+export function catalogControlServices(catalog) {
+  if (!catalog?.get)
+    throw new TypeError('An application layer catalog is required');
+  return Object.fromEntries(
+    Object.entries(CONTROL_LAYER_IDS).map(([role, id]) => {
+      const layer = catalog.get(id);
+      if (!layer)
+        throw new TypeError(`Control layer missing from catalog: ${id}`);
+      return [role, layer];
+    }),
+  );
+}

src/app/catalog.test.mjs

@@ -0,0 +1,155 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createLayerCatalog, catalogControlServices } from './catalog.js';
+import { createApplicationData } from './data.js';
+
+const metadata = (layers) =>
+  layers.map(({ id }) => ({ id, disposition: 'enabled-only' }));
+
+test('catalog captures membership and metadata while preserving the supplied instances', () => {
+  const first = { id: 'first' };
+  const layers = [first];
+  const schema = metadata(layers);
+  const catalog = createLayerCatalog(layers, schema);
+  layers.push({ id: 'later' });
+  schema[0].disposition = 'invalid';
+  assert.deepEqual(catalog.layers, [first]);
+  assert.equal(catalog.get('first'), first);
+  assert.equal(catalog.get('later'), undefined);
+  assert.equal(catalog.metadata[0].disposition, 'enabled-only');
+  assert.throws(() => catalog.layers.push({ id: 'later' }), TypeError);
+});
+
+test('duplicate, missing and extra metadata fail before application registration', () => {
+  const layers = [{ id: 'first' }];
+  assert.throws(
+    () => createLayerCatalog([...layers, ...layers], metadata(layers)),
+    /duplicate/,
+  );
+  assert.throws(() => createLayerCatalog(layers, []), /incomplete/);
+  assert.throws(
+    () => createLayerCatalog(layers, metadata([{ id: 'other' }])),
+    /Unmatched/,
+  );
+  assert.throws(
+    () =>
+      createLayerCatalog(layers, [...metadata(layers), ...metadata(layers)]),
+    /duplicate/,
+  );
+});
+
+test('data setup seals the caller catalog before controls can restore and drains its exact instances', async (t) => {
+  const previous = globalThis.document;
+  globalThis.document = { getElementById: () => null };
+  t.after(() => {
+    if (previous === undefined) delete globalThis.document;
+    else globalThis.document = previous;
+  });
+  const attached = [];
+  const layers = [
+    {
+      id: 'one',
+      attachDataManager: (manager) => attached.push([...manager.layers.keys()]),
+    },
+    { id: 'two' },
+  ];
+  const releases = [];
+  let observed;
+  const { dataManager } = createApplicationData({
+    scene: { viewer: {} },
+    controls: {
+      styleManager: {
+        attachDataManager(manager) {
+          assert.equal(manager.registrationsFinalized, true);
+          assert.equal(manager.layers.get('one').module, layers[0]);
+        },
+      },
+    },
+    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/);
+  for (const release of releases.reverse()) await release();
+  assert.equal(dataManager.layers.size, 0);
+});
+
+test('data setup keeps layers polling in an inline panel its host reports hidden', async (t) => {
+  const previous = globalThis.document;
+  globalThis.document = {
+    hidden: true,
+    visibilityState: 'hidden',
+    getElementById: () => null,
+    addEventListener() {},
+    removeEventListener() {},
+  };
+  t.after(() => {
+    delete globalThis.GEV_EMBED_INLINE;
+    if (previous === undefined) delete globalThis.document;
+    else globalThis.document = previous;
+  });
+  const releases = [];
+  const { dataManager } = createApplicationData({
+    scene: { viewer: {} },
+    controls: { styleManager: { attachDataManager() {} } },
+    catalog: createLayerCatalog([], []),
+    defer: (release) => releases.push(release),
+  });
+  const visibility = dataManager._visibilityTarget;
+  assert.equal(visibility.hidden, true, 'a hidden page pauses outside a panel');
+  globalThis.GEV_EMBED_INLINE = true;
+  assert.equal(visibility.hidden, false);
+  assert.equal(visibility.visibilityState, 'visible');
+  for (const release of releases.reverse()) await release();
+});
+
+test('controls bind catalog instances rather than similarly named defaults', () => {
+  const ids = [
+    'traffic',
+    'flights',
+    'military',
+    'satellites',
+    'cctv',
+    'radio',
+    'bikeshare',
+    'transit',
+    'ais-live-vessels',
+    'military-awareness',
+    'military-installations',
+    'rocket-launches',
+    'street-level',
+    'local-adsb',
+  ];
+  const layers = ids.map((id) => ({ id }));
+  const catalog = createLayerCatalog(layers, metadata(layers));
+  const services = catalogControlServices(catalog);
+  assert.equal(services.flightsLayer, layers[1]);
+  assert.equal(services.transitLayer, layers[7]);
+  assert.equal(services.aisLiveVesselsLayer, layers[8]);
+  assert.equal(services.localAdsbLayer, layers[13]);
+  assert.equal(new Set(Object.values(services)).size, layers.length);
+  assert.throws(
+    () => catalogControlServices(createLayerCatalog([], [])),
+    /Control layer missing/,
+  );
+});

src/app/constructCatalog.js

@@ -0,0 +1,200 @@
+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';
+import { createWindLayer } from '../layers/wind/index.js';
+import { createLayerCatalog } from './catalog.js';
+import { LAYER_STATE_REGISTRY } from '../data/layerState.js';
+import { createMilitaryRegistry } from '../layers/aircraft/classification.js';
+import { createApplicationFlights } from './layers/flights.js';
+import { createApplicationMilitary } from './layers/militaryFlights.js';
+import { createApplicationVessels } from './layers/aisLiveVessels.js';
+import { createApplicationCctv } from './layers/cctv.js';
+import { createApplicationRadio } from './layers/radio.js';
+import { createApplicationTraffic } from './layers/traffic.js';
+import { createApplicationBikeshare } from './layers/bikeshare.js';
+import { createApplicationDirections } from './layers/directions.js';
+import { createApplicationRecentImagery } from './layers/recentImagery.js';
+import { createApplicationTransit } from './layers/transit.js';
+import { createApplicationInstallations } from './layers/militaryInstallations.js';
+import { createApplicationSatellites } from './layers/satellites.js';
+import { createApplicationLaunches } from './layers/rocketLaunches.js';
+import { createApplicationAlpr } from './layers/alprCameras.js';
+import { createApplicationLocalAdsb } from './layers/localAdsb.js';
+import { createApplicationAwareness } from './layers/militaryAwareness.js';
+import { createApplicationFirms } from './layers/firms.js';
+import { createApplicationEarthquakes } from './layers/earthquakes.js';
+import { createApplicationAirQuality } from './layers/airQuality.js';
+import { createApplicationFirePerimeters } from './layers/perimeters.js';
+import { createApplicationGnssIntegrity } from './layers/gnss.js';
+import { createApplicationGhostMaps } from './layers/ghostMaps.js';
+import { createApplicationCables } from './layers/submarineCables.js';
+import { createOsmOverlaysLayer } from '../data/osmOverlays.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';
+
+/**
+ * Hardware-local layers are registered like any other but never enter share
+ * links or stored layer state: another browser cannot have this receiver.
+ */
+export const LOCAL_ONLY_LAYER_METADATA = Object.freeze([
+  Object.freeze({ id: 'local-adsb', disposition: 'local-only' }),
+]);
+
+/** Serialization metadata for every layer the application catalog constructs. */
+export const APPLICATION_LAYER_METADATA = Object.freeze([
+  ...LAYER_STATE_REGISTRY,
+  ...LOCAL_ONLY_LAYER_METADATA,
+]);
+
+/** Construct the current catalog without choosing any source provider.
+ * Scene engines remain page-owned; layers and classification have this app's lifetime.
+ * The manager owns layer destruction, while abort releases classification even if startup fails.
+ */
+export function createApplicationCatalog({
+  surface,
+  sources,
+  signal,
+  metadata = APPLICATION_LAYER_METADATA,
+  vesselOptions,
+  resolveAsset,
+  nepalBoundaryResolver,
+  streetLevelProviders,
+}) {
+  if (!signal?.addEventListener)
+    throw new TypeError('An application lifetime signal is required');
+  signal.throwIfAborted();
+  if (!surface?.groundFloor || !surface?.terrain)
+    throw new TypeError('Application surface services are required');
+
+  const sourceComposition = resolveCatalogSources(sources);
+  sources = sourceComposition.sources;
+  const militaryRegistry = createMilitaryRegistry();
+  const weatherClock = createWeatherClock();
+  const dispose = () => {
+    signal.removeEventListener('abort', dispose);
+    militaryRegistry.dispose();
+    weatherClock.destroy();
+  };
+  signal.addEventListener('abort', dispose, { once: true });
+  try {
+    if (sourceComposition.isConfigured('military'))
+      militaryRegistry.configureSource(sources.military, { signal });
+    const flights = createApplicationFlights({
+      surface,
+      source: sources.flights,
+      militaryRegistry,
+      resolveAsset,
+    });
+    const military = createApplicationMilitary({
+      surface,
+      source: sources.military,
+      militaryRegistry,
+      resolveAsset,
+    });
+    const vessels = createApplicationVessels({
+      source: sources.vessels,
+      options: vesselOptions,
+    });
+    const installations = createApplicationInstallations({
+      surface,
+      source: sources.installations,
+    });
+    const satellites = createApplicationSatellites({
+      source: sources.satellites,
+    });
+    const catalog = createLayerCatalog(
+      [
+        createBhoteKoshiEventLayer(),
+        createBhoteKoshiLocatorLayer({
+          boundaryResolver: nepalBoundaryResolver,
+        }),
+        flights,
+        military,
+        createApplicationLocalAdsb({
+          surface,
+          enrichment: sources.flights,
+          displayParams: () => flights.getParams(),
+          ...(resolveAsset ? { resolveAsset } : {}),
+        }),
+        createApplicationEarthquakes({ source: sources.earthquakes }),
+        createApplicationAirQuality({ source: sources['air-quality'] }),
+        createApplicationFirePerimeters({
+          source: sources['fire-perimeters'],
+        }),
+        createApplicationGnssIntegrity({
+          source: sources['gnss-integrity'],
+          windowMs: sources['gnss-integrity'].windowMs,
+        }),
+        createApplicationGhostMaps({ source: sources['s2-ghostmaps'] }),
+        createApplicationAlpr({ surface, source: sources.alpr }),
+        createApplicationStreetLevel({
+          surface,
+          sources: { mapillary: sources.mapillary },
+          providers: streetLevelProviders,
+        }),
+        satellites,
+        createApplicationLaunches({ source: sources.launches, satellites }),
+        createApplicationTraffic({ source: sources.traffic, surface }),
+        createApplicationCctv({ surface, source: sources.cctv }),
+        createApplicationRadio({ surface, source: sources.radio }),
+        createApplicationTransit({ surface, source: sources.transit }),
+        createApplicationBikeshare({ source: sources.bikeshare }),
+        createApplicationDirections({ source: sources.directions }),
+        createApplicationRecentImagery({ source: sources['recent-imagery'] }),
+        vessels,
+        installations,
+        createApplicationAwareness({
+          flights,
+          military,
+          vessels,
+          installations,
+        }),
+        createWindLayer({ feed: sources.wind, clock: weatherClock }),
+        createWeatherLayer({
+          feed: sources.weather,
+          id: 'weather-radar',
+          clock: weatherClock,
+        }),
+        createWeatherLayer({
+          feed: sources.weather,
+          id: 'weather-satellite',
+          clock: weatherClock,
+        }),
+        createWeatherLayer({
+          feed: sources.weather,
+          id: 'weather-lightning',
+          clock: weatherClock,
+        }),
+        createCyclonesLayer({ feed: sources.cyclones }),
+        createOsmOverlaysLayer(),
+        ...createInfrastructureLayers(localGeoJsonServices),
+        createApplicationCables({ source: sources.cables }),
+        createApplicationFirms({
+          surface,
+          id: 'local-firms',
+          name: 'FIRMS Active Fires',
+          icon: '▲',
+          source: 'NASA FIRMS · LIVE',
+          feed: sources.firms,
+        }),
+      ],
+      metadata,
+    );
+    return Object.freeze({
+      ...catalog,
+      getSourceAvailability: sourceComposition.createAvailabilityLookup(
+        catalog.layers,
+      ),
+      militaryRegistry,
+      surface,
+      weatherClock,
+    });
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+}

src/app/constructCatalog.test.mjs

@@ -0,0 +1,234 @@
+import { createSurfaceServices } from './surfaceServices.js';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+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();
+  sources.military = {
+    getSnapshot: async () => {
+      throw new Error('Use identity acquisition');
+    },
+    async getIdentities(_query, { signal }) {
+      calls.push(signal);
+      return ids;
+    },
+  };
+  return sources;
+}
+
+test('catalogs construct distinct layers and classification from their supplied source', async (t) => {
+  const a = new AbortController();
+  const b = new AbortController();
+  t.after(() => {
+    a.abort();
+    b.abort();
+  });
+  const callsA = [];
+  const callsB = [];
+  const first = createApplicationCatalog({
+    sources: fixtureSources(['abc123'], callsA),
+    signal: a.signal,
+    surface: fixtureSurface(a.signal),
+  });
+  const second = createApplicationCatalog({
+    sources: fixtureSources(['def456'], callsB),
+    signal: b.signal,
+    surface: fixtureSurface(b.signal),
+  });
+  assert.equal(first.layers.length, 34);
+  assert.ok(first.get('local-adsb'), 'Local ADS-B is registered');
+  assert.deepEqual(
+    first.metadata.find(({ id }) => id === 'local-adsb'),
+    { id: 'local-adsb', disposition: 'local-only' },
+    'the hardware-local layer is never serialized into links',
+  );
+  assert.notEqual(first.weatherClock, second.weatherClock);
+  await first.weatherClock.setTarget('2026-09-21T12:00:00.000Z');
+  assert.match(
+    first.get('wind').getRowControls().info,
+    /Forecast · does not follow history/,
+  );
+  assert.equal(second.get('wind').getRowControls().summary.status, null);
+  for (const id of ['weather-radar', 'weather-satellite', 'weather-lightning'])
+    assert.equal(
+      first.get(id).getDiagnostics().clock.target,
+      '2026-09-21T12:00:00.000Z',
+    );
+  assert.ok(first.get('fire-perimeters'));
+  assert.ok(first.get('gnss-integrity'));
+  assert.ok(first.get('s2-ghostmaps'));
+  assert.ok(first.get('transit'));
+  const order = first.layers.map(({ id }) => id);
+  assert.deepEqual(
+    order.slice(order.indexOf('traffic'), order.indexOf('directions') + 1),
+    ['traffic', 'cctv', 'radio', 'transit', 'bikeshare', 'directions'],
+  );
+  assert.ok(first.get('bhote-koshi-2026'));
+  assert.ok(first.get('bhote-koshi-locator'));
+  const lifecycle = new LayerLifecycle({});
+  for (const layer of first.layers) lifecycle.register(layer);
+  const rows = lifecycle.getAll();
+  for (const id of ['bhote-koshi-2026', 'bhote-koshi-locator']) {
+    assert.equal(
+      rows.find((row) => row.id === id)?.showInTogglePanel,
+      false,
+      `${id} remains registered for Scenes but is absent from Data Layers`,
+    );
+    assert.equal(typeof first.get(id).enable, 'function');
+    assert.equal(typeof first.get(id).setParams, 'function');
+  }
+  assert.equal(
+    rows.find((row) => row.id === 'flights')?.showInTogglePanel,
+    true,
+    'ordinary data layer entries remain visible',
+  );
+  assert.deepEqual(
+    first.layers.map(({ id }) => id),
+    second.layers.map(({ id }) => id),
+  );
+  for (const layer of first.layers)
+    assert.notEqual(layer, second.get(layer.id));
+  assert.equal(
+    catalogControlServices(first).satellitesLayer,
+    first.get('satellites'),
+  );
+  assert.equal(callsA.length, 0, 'construction must not acquire');
+  await first.militaryRegistry.refreshMilitaryRegistryIfStale();
+  await second.militaryRegistry.refreshMilitaryRegistryIfStale();
+  assert.equal(first.militaryRegistry.isMilitaryIcao('abc123'), true);
+  assert.equal(first.militaryRegistry.isMilitaryIcao('def456'), false);
+  assert.equal(second.militaryRegistry.isMilitaryIcao('def456'), true);
+  a.abort();
+  assert.equal(
+    await first.weatherClock.setTarget('2026-09-21T13:00:00.000Z'),
+    false,
+  );
+  assert.equal(callsA[0].aborted, true);
+  assert.equal(first.militaryRegistry.isMilitaryIcao('abc123'), false);
+  assert.equal(callsB[0].aborted, false);
+  assert.equal(second.militaryRegistry.isMilitaryIcao('def456'), true);
+});
+
+test('invalid or already cancelled construction fails before classification can acquire', () => {
+  const lifetime = new AbortController();
+  assert.throws(
+    () =>
+      createApplicationCatalog({
+        sources: { flights: {} },
+        signal: lifetime.signal,
+        surface: fixtureSurface(lifetime.signal),
+      }),
+    /catalog source/,
+  );
+  lifetime.abort();
+  assert.throws(
+    () =>
+      createApplicationCatalog({
+        sources: createStandaloneLayerSources(),
+        signal: lifetime.signal,
+      }),
+    { name: 'AbortError' },
+  );
+});
+
+function fixtureSurface(signal) {
+  return createSurfaceServices({
+    terrainSource: { getHeights: async () => [] },
+    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, 34);
+  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/,
+  );
+});
+
+test('a GNSS integrity source can set the layer evidence window', (t) => {
+  const lifetime = new AbortController();
+  t.after(() => lifetime.abort());
+  const gnssLayer = (descriptor) => {
+    const sources = fixtureSources([], []);
+    sources['gnss-integrity'] = {
+      getSnapshot: async () => ({}),
+      ...descriptor,
+    };
+    return createApplicationCatalog({
+      sources,
+      signal: lifetime.signal,
+      surface: fixtureSurface(lifetime.signal),
+    }).get('gnss-integrity');
+  };
+  const shows = (layer, minutes) => {
+    assert.equal(layer.provenance.window.minutes, minutes);
+    const { info, legend } = layer.getRowControls();
+    assert.match(info, new RegExp(`visited views over ${minutes} min`));
+    assert.match(legend[0].blurb, new RegExp(`over ${minutes} minutes`));
+  };
+  shows(gnssLayer({ windowMs: 65 * 60_000 }), 65);
+  shows(gnssLayer({}), 30);
+  for (const windowMs of [
+    undefined,
+    null,
+    NaN,
+    Infinity,
+    0,
+    -60_000,
+    '3600000',
+  ])
+    assert.equal(
+      gnssLayer({ windowMs }).provenance.window.minutes,
+      30,
+      `${String(windowMs)} falls back to the default`,
+    );
+});

src/app/controls.js

@@ -0,0 +1,62 @@
+import { catalogControlServices } from './catalog.js';
+import { StyleManager } from '../ui/composition.js';
+import { flyToAustin } from '../camera.js';
+import { initCockpitCloudEffects } from '../cockpitCloudEffects.js';
+import { t } from '../i18n/index.js';
+
+/**
+ * Construct the existing controls and camera presentation. `initialShareCode`
+ * opens a share code (the `<code>` of `/share/<code>`) at start-up, for a host
+ * whose address does not carry one. `localePicker: false` removes the language
+ * picker, for a host that does not initialize Core's locale.
+ */
+export function createApplicationControls({
+  scene: { viewer, mapStackController, operations },
+  loaderStatus,
+  Controls = StyleManager,
+  services,
+  catalog,
+  placeSearch,
+  defer,
+  initialShareCode = null,
+  localePicker = true,
+}) {
+  // Initialize the style manager (post-processing, HUD, locations, share links)
+  const styleManager = new Controls(viewer, {
+    services: {
+      ...services,
+      ...operations.surface.controlServices,
+      searchAndFlyTo: operations.searchAndFlyTo,
+      fetchRegionalBrief: (...args) =>
+        operations.requests.regional.getBrief(...args),
+      ...catalogControlServices(catalog),
+    },
+    requestServices: operations.requests,
+    mapStackController,
+    placeSearch,
+    // A share code to open at start-up instead of the page's address.
+    initialShareCode,
+    localePicker,
+  });
+  defer(() => styleManager.orbitController.stop());
+  defer(() => styleManager.hud.destroy());
+  defer(() => styleManager.dispose());
+  // The previous multi-canvas weather compositor remains disabled. Cockpit
+  // clouds use a separate, capped low-resolution GPU pass that never attaches
+  // Cesium fog or post-process stages and is fully stopped in map mode.
+  const weatherEffects = null;
+  const cockpitCloudEffects = initCockpitCloudEffects(viewer, {
+    weatherService: operations.requests.weather,
+  });
+  defer(() => cockpitCloudEffects?.destroy());
+
+  // If no share link state, do default fly-to Austin
+  if (!styleManager.hasShareState) {
+    loaderStatus.textContent = t('Flying to Austin, TX...');
+    defer(flyToAustin(viewer));
+  } else {
+    loaderStatus.textContent = t('Restoring shared view...');
+  }
+
+  return { styleManager, weatherEffects, cockpitCloudEffects };
+}

src/app/data.js

@@ -0,0 +1,67 @@
+import { LayerLifecycle } from '../data/lifecycle.js';
+import { LayerPresentation } from './layerPresentation.js';
+import { createCyberSonarScene } from '../cyberSonarScene.js';
+import { panelAwareVisibility } from './embed.js';
+/** Register the application layer catalog before allowing state restoration. */
+export function createApplicationData({
+  scene: { viewer, mapStackController },
+  controls: { styleManager },
+  catalog,
+  allowQaRegistration,
+  onData,
+  defer,
+}) {
+  // Initialize data layer manager
+  const dataManager = new LayerLifecycle(viewer, {
+    allowQaRegistration,
+    // A panel's host may report it hidden while it is on screen; its layers
+    // keep polling (see keepPanelRendering in embed.js).
+    visibilityTarget: panelAwareVisibility(document),
+    getSourceAvailability: catalog?.getSourceAvailability,
+  });
+  defer(async () => {
+    await dataManager.destroyAll();
+    if (dataManager.layers.size)
+      throw new Error(
+        `Data layers could not be destroyed: ${[...dataManager.layers.keys()].join(', ')}`,
+      );
+  });
+  const presentation = new LayerPresentation(dataManager, {
+    weatherClock: catalog?.weatherClock,
+  });
+  defer(() => presentation.destroy());
+  onData?.(dataManager);
+  if (!catalog?.layers || !catalog?.metadata)
+    throw new TypeError('An application layer catalog is required');
+  for (const layer of catalog.layers) dataManager.register(layer);
+  for (const layer of catalog.layers) layer.attachDataManager?.(dataManager);
+  for (const layer of catalog.layers)
+    layer.attachMapStackController?.(mapStackController);
+  // Restoration starts only after the caller's complete registry is sealed.
+  dataManager.finalizeRegistrations(catalog.metadata);
+  if (allowQaRegistration) {
+    window.__gevQaRegisterLayer = (targetManager, layerModule) => {
+      if (targetManager !== dataManager)
+        throw new Error('QA layer manager mismatch');
+      return dataManager.registerForQa(layerModule);
+    };
+    window.__gevQaUnregisterLayer = (targetManager, layerId) => {
+      if (targetManager !== dataManager)
+        throw new Error('QA layer manager mismatch');
+      return dataManager.unregisterForQa(layerId);
+    };
+    const register = window.__gevQaRegisterLayer;
+    const unregister = window.__gevQaUnregisterLayer;
+    defer(() => {
+      if (window.__gevQaRegisterLayer === register)
+        delete window.__gevQaRegisterLayer;
+      if (window.__gevQaUnregisterLayer === unregister)
+        delete window.__gevQaUnregisterLayer;
+    });
+  }
+  presentation.mount(document.getElementById('data-toggles'));
+  styleManager.attachDataManager(dataManager);
+  defer(createCyberSonarScene(viewer, dataManager));
+
+  return { dataManager, catalog, presentation };
+}

src/app/embed.js

@@ -0,0 +1,327 @@
+/**
+ * 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';
+
+const EMBED_VIEW_MESSAGE = 'gev:view';
+const EMBED_APPLIED_MESSAGE = 'gev:view-applied';
+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;
+}
+
+/**
+ * `doc`'s visibility for work that pauses in a hidden page. A panel's host
+ * may report it hidden while it is on screen (see keepPanelRendering), so an
+ * inline panel always reads as visible.
+ */
+export function panelAwareVisibility(doc = globalThis.document) {
+  const hidden = () =>
+    (doc.hidden === true || doc.visibilityState === 'hidden') &&
+    !isEmbeddedInline();
+  return {
+    get hidden() {
+      return hidden();
+    },
+    get visibilityState() {
+      return hidden() ? 'hidden' : 'visible';
+    },
+    addEventListener: (type, listener) => doc.addEventListener(type, listener),
+    removeEventListener: (type, listener) =>
+      doc.removeEventListener(type, listener),
+  };
+}
+
+// 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,395 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  applyView,
+  installViews,
+  isEmbedded,
+  keepPanelRendering,
+  panelAwareVisibility,
+} from './embed.js';
+import { LayerLifecycle } from '../data/lifecycle.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'] },
+  });
+  // A view kept from before Snow was retired still applies, on Normal.
+  send(parent, {
+    type: 'gev:view',
+    id: 4,
+    view: { camera: { lat: 1, lon: 2 }, style: 'snow' },
+  });
+  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[3].id, 4);
+  assert.equal(posted[3].ok, true);
+  assert.ok(
+    calls.some(
+      ([name, args]) => name === 'set_visual_style' && args.style === 'normal',
+    ),
+  );
+  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',
+    '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('polled layers keep refreshing in an inline panel its host reports hidden', async (t) => {
+  const listeners = new Set();
+  const doc = {
+    hidden: true,
+    visibilityState: 'hidden',
+    addEventListener: (_type, fn) => listeners.add(fn),
+    removeEventListener: (_type, fn) => listeners.delete(fn),
+  };
+  const settle = async () => {
+    for (let i = 0; i < 3; i++) await Promise.resolve();
+  };
+  t.mock.timers.enable({ apis: ['setInterval', 'Date'], now: 1000 });
+  let updates = 0;
+  const manager = new LayerLifecycle(
+    {},
+    { visibilityTarget: panelAwareVisibility(doc) },
+  );
+  manager.register({
+    id: 'flights',
+    name: 'flights',
+    icon: '',
+    source: 'test',
+    updateInterval: 1000,
+    async init() {},
+    enable() {},
+    disable() {},
+    async update() {
+      updates++;
+      await Promise.resolve();
+    },
+    getStats: () => ({ count: 0, lastUpdate: null }),
+  });
+  globalThis.GEV_EMBED_INLINE = true;
+  try {
+    await manager.setEnabled('flights', true);
+    await settle();
+    const enabled = updates;
+    t.mock.timers.tick(1000);
+    await settle();
+    t.mock.timers.tick(1000);
+    await settle();
+    assert.equal(updates, enabled + 2, 'the panel keeps polling');
+
+    delete globalThis.GEV_EMBED_INLINE;
+    t.mock.timers.tick(1000);
+    await settle();
+    assert.equal(updates, enabled + 2, 'outside a panel a hidden page pauses');
+  } finally {
+    delete globalThis.GEV_EMBED_INLINE;
+    await manager.destroyAll();
+  }
+  assert.equal(listeners.size, 0);
+});
+
+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/errors.js

@@ -0,0 +1,25 @@
+/**
+ * Extract a human-readable error message from any thrown value.
+ * Handles Error objects, strings, and plain objects with message/error fields.
+ * @param {*} error — caught exception value
+ * @returns {string} best-effort error description
+ */
+export function describeError(error) {
+  if (!error) return 'Unknown initialization error';
+  if (error instanceof Error) {
+    if (error.message && error.message.trim()) return error.message.trim();
+    return error.name || 'Initialization error';
+  }
+  if (typeof error === 'string' && error.trim()) return error.trim();
+  if (typeof error === 'object') {
+    const maybeMessage = String(error.message || error.error || '').trim();
+    if (maybeMessage) return maybeMessage;
+    try {
+      const serialized = JSON.stringify(error);
+      if (serialized && serialized !== '{}') return serialized;
+    } catch {
+      // ignore serialization error
+    }
+  }
+  return String(error);
+}

src/app/globePanelRuntime.js

@@ -0,0 +1,669 @@
+/**
+ * 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 =
+          // i18n-ignore: host-panel script, no app catalogs
+          "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;
+    // i18n-ignore: host-panel script, no app catalogs
+    say("Loading God's Eye View…");
+    startApp(url, view).catch((error) =>
+      // i18n-ignore: host-panel script, no app catalogs
+      say(`God's Eye View could not load here: ${error?.message || error}.`),
+    );
+    setTimeout(() => {
+      if (!ready)
+        say(
+          // i18n-ignore: see above
+          "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');
+    // i18n-ignore: host-panel script, no app catalogs
+    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',
+      // i18n-ignore: product name sent to the MCP host
+      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(
+        // i18n-ignore: host-panel script, no app catalogs
+        "This client did not accept the God's Eye View panel" +
+          (error?.message ? `: ${error.message}` : '.'),
+      ),
+  );
+}

src/app/layerPresentation.js

@@ -0,0 +1,94 @@
+import { LayerPanel } from '../ui/layers.js';
+import { governorRequestRender } from '../renderGovernor.js';
+import { markDetectionSourcesChanged } from '../data/detection.js';
+
+/** Own the layer panel and application reactions to lifecycle activity. */
+export class LayerPresentation {
+  constructor(
+    manager,
+    {
+      weatherClock,
+      requestRender = governorRequestRender,
+      invalidateDetection = markDetectionSourcesChanged,
+    } = {},
+  ) {
+    this.manager = manager;
+    this.weatherClock = weatherClock;
+    this._panel = null;
+    this.pendingVisible = false;
+    this._unsubscribe = manager.subscribeActivity((change) => {
+      if (change.type === 'status') this.refresh();
+      else if (change.type === 'destroy-all') this.destroy();
+      else {
+        const reason =
+          change.type === 'data-updated'
+            ? `layer-tick:${change.layerId}`
+            : change.type === 'visibility-settled'
+              ? 'layer-visibility'
+              : change.type === 'params-settled'
+                ? `layer-params:${change.layerId}`
+                : null;
+        if (!reason) return;
+        requestRender(reason);
+        if (change.type !== 'params-settled') invalidateDetection(reason);
+      }
+    });
+  }
+  get panel() {
+    if (!this._panel)
+      this._panel = new LayerPanel({
+        weatherClock: this.weatherClock,
+        getLayers: () => this.manager.getAll(),
+        isEnabled: (id) => this.manager.isEnabled(id),
+        setEnabled: (id, enabled, options) =>
+          this.manager.setEnabled(id, enabled, options),
+        setLayerParams: (id, params, options) =>
+          this.manager.setLayerParams(id, params, options),
+        getRowControls: (id) => {
+          const module = this.manager.layers.get(id)?.module;
+          try {
+            return module?.getRowControls?.() || null;
+          } catch (error) {
+            console.warn(`[Data] ${id} getRowControls error:`, error);
+            return null;
+          }
+        },
+        hasRowControls: (id) =>
+          typeof this.manager.layers.get(id)?.module?.getRowControls ===
+          'function',
+        subscribeRowControls: (id, listener) => {
+          const module = this.manager.layers.get(id)?.module;
+          module?.setRowControlsListener?.(listener);
+          return () => module?.setRowControlsListener?.(null);
+        },
+        onHiddenRefresh: () => {
+          this.pendingVisible = true;
+        },
+      });
+    return this._panel;
+  }
+  mount(container) {
+    this.panel.mount(container);
+  }
+  /** Hand the Recent Imagery readout factory to the panel (see LayerPanel). */
+  attachRecentImagery(factory) {
+    // Detaching never builds a panel that teardown already released.
+    if (factory) this.panel.attachRecentImagery(factory);
+    else this._panel?.attachRecentImagery(null);
+  }
+  refresh() {
+    this._panel?._refreshTogglePanel();
+  }
+  flushVisible() {
+    if (!this.pendingVisible) return;
+    this.pendingVisible = false;
+    this.refresh();
+  }
+  destroy() {
+    this._panel?.destroy();
+    this._panel = null;
+    this.pendingVisible = false;
+    this._unsubscribe?.();
+    this._unsubscribe = null;
+  }
+}

src/app/layers/airQuality.js

@@ -0,0 +1,6 @@
+import { createAirQualityLayer } from '../../layers/airQuality/index.js';
+import { overlayHost } from './overlayHost.js';
+/** Wire air-quality readings to the application overlay host. */
+export function createApplicationAirQuality(options) {
+  return createAirQualityLayer({ overlayHost, ...options });
+}

src/app/layers/aisLiveVessels.js

@@ -0,0 +1,33 @@
+import { createVesselLayer } from '../../layers/vessels/index.js';
+import * as context from '../../data/contextStore.js';
+import * as trails from '../../data/trailRenderer.js';
+import * as labels from '../../data/detectionDraw.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as overlay from '../../overlays/worldOverlay.js';
+import * as geoid from '../../data/geoid.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as focus from '../../data/focusDeemphasis.js';
+import * as worldFocus from '../../worldFocus.js';
+import * as render from '../../renderGovernor.js';
+import * as readouts from '../../hudReadouts.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationVessels({ source, options = {} }) {
+  return createVesselLayer({
+    source,
+    options,
+    services: {
+      context,
+      trails,
+      labels,
+      picking,
+      overlay,
+      geoid,
+      sprites,
+      focus,
+      worldFocus,
+      render,
+      readouts,
+    },
+  });
+}

src/app/layers/alprCameras.js

@@ -0,0 +1,33 @@
+import * as credits from '../../data/dataCredits.js';
+import { createAlprCamerasLayer } from '../../layers/alpr/index.js';
+import * as render from '../../renderGovernor.js';
+import * as context from '../../data/contextStore.js';
+import * as picking from '../../data/pickRegistry.js';
+import { registerWorldOverlayPaintLane } from '../../overlays/worldOverlay.js';
+import { keyholeLabelAlphaFromGeometry } from '../../celestialRing.js';
+import { refreshTrackedReadout } from '../../data/trackedReadout.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationAlpr({ surface, source }) {
+  const { groundFloor } = surface;
+  return createAlprCamerasLayer({
+    source,
+    services: {
+      credits,
+      render,
+      context,
+      picking,
+      groundFloor,
+      overlays: {
+        registerPaintLane: registerWorldOverlayPaintLane,
+        keyholeAlpha: keyholeLabelAlphaFromGeometry,
+        refreshReadout: refreshTrackedReadout,
+        subscribeMapStack(callback) {
+          window.addEventListener('gev:map-stack-changed', callback);
+          return () =>
+            window.removeEventListener('gev:map-stack-changed', callback);
+        },
+      },
+    },
+  });
+}

src/app/layers/bikeshare.js

@@ -0,0 +1,13 @@
+import { createBikeshareLayer } from '../../layers/bikeshare/index.js';
+import * as render from '../../renderGovernor.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationBikeshare({ source }) {
+  return createBikeshareLayer({
+    source,
+    services: { render, sprites, picking, overlays },
+  });
+}

src/app/layers/cctv.js

@@ -0,0 +1,30 @@
+import { createCctvLayer } from '../../layers/cctv/index.js';
+import * as credits from '../../data/dataCredits.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as activation from '../../cctvFocusRequest.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import { CITY_POIS } from '../../cityPois.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as focus from '../../data/focusDeemphasis.js';
+import * as render from '../../renderGovernor.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationCctv({ surface, source }) {
+  const { terrain, groundFloor: ground, meshFloor: mesh } = surface;
+  return createCctvLayer({
+    source,
+    services: {
+      credits,
+      sprites,
+      activation,
+      overlays,
+      locations: { CITY_POIS },
+      picking,
+      terrain,
+      ground,
+      mesh,
+      focus,
+      render,
+    },
+  });
+}

src/app/layers/directions.js

@@ -0,0 +1,6 @@
+import { createApplicationDirectionsLayer } from '../../data/directions.js';
+
+/** Construct Directions with application scene owners and an explicit route source. */
+export function createApplicationDirections({ source }) {
+  return createApplicationDirectionsLayer({ source });
+}

src/app/layers/earthquakes.js

@@ -0,0 +1,6 @@
+import { createEarthquakesLayer } from '../../layers/earthquakes/index.js';
+import { overlayHost } from './overlayHost.js';
+/** Wire earthquake observations to the application overlay host. */
+export function createApplicationEarthquakes(options) {
+  return createEarthquakesLayer({ overlayHost, ...options });
+}

src/app/layers/firms.js

@@ -0,0 +1,36 @@
+import * as Cesium from 'cesium';
+import { createFirmsHeatmapLayer as createLayer } from '../../layers/firms/index.js';
+import * as render from '../../renderGovernor.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as context from '../../data/contextStore.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import * as focus from '../../worldFocus.js';
+export const firmsServices = {
+  render,
+  sprites,
+  context,
+  picking,
+  overlays,
+  focus,
+};
+
+/** Bind a supplied fire feed to the application scene service owners. */
+export function createApplicationFirms({ surface, ...options }) {
+  return createLayer({
+    ...options,
+    icon: options.icon ?? '▲',
+    source: options.source ?? 'NASA FIRMS',
+    feed: options.feed,
+    services: { ...firmsServices, anchors: surface.anchors },
+    overlayHost: options.overlayHost ?? {
+      setEntries: overlays.setOverlayEntries,
+      setVisible: overlays.setOverlaySourceVisible,
+      clearSource: overlays.clearOverlaySource,
+      hitTest: overlays.hitTestWorldOverlay,
+    },
+    screenSpaceEventHandlerFactory:
+      options.screenSpaceEventHandlerFactory ??
+      ((viewer) => new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas)),
+  });
+}

src/app/layers/flights.js

@@ -0,0 +1,46 @@
+import { createCivilFlightLayer } from '../../layers/flights/index.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as trails from '../../data/trailRenderer.js';
+import * as aircraftPresentation from '../../data/tr3bRegistry.js';
+import * as camera from '../../data/trackedCamera.js';
+import * as labels from '../../data/detectionDraw.js';
+import * as geoid from '../../data/geoid.js';
+import * as focus from '../../data/focusDeemphasis.js';
+import * as readout from '../../data/trackedReadout.js';
+import * as context from '../../data/contextStore.js';
+import * as render from '../../renderGovernor.js';
+import * as recession from '../../data/aircraftRecession.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationFlights({
+  surface,
+  source,
+  militaryRegistry,
+  resolveAsset = (url) =>
+    `${import.meta.env?.BASE_URL || '/'}${url.replace(/^\//, '')}`,
+}) {
+  const { groundFloor, meshFloor, groundSnap } = surface;
+  return createCivilFlightLayer({
+    source,
+    resolveAsset,
+    services: {
+      picking,
+      sprites,
+      trails,
+      aircraftPresentation,
+      camera,
+      militaryRegistry,
+      labels,
+      groundFloor,
+      meshFloor,
+      geoid,
+      focus,
+      readout,
+      context,
+      render,
+      groundSnap,
+      recession,
+    },
+  });
+}

src/app/layers/ghostMaps.js

@@ -0,0 +1,23 @@
+import * as Cesium from 'cesium';
+import { createGhostMapsLayer } from '../../layers/ghostMaps/index.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import { isPointerFree } from '../../data/inputOwnership.js';
+
+/** Wire the S2 Underground GhostMaps layer into the application catalog. */
+export function createApplicationGhostMaps(options) {
+  return createGhostMapsLayer({
+    overlayHost: {
+      setEntries: overlays.setOverlayEntries,
+      setVisible: overlays.setOverlaySourceVisible,
+      clearSource: overlays.clearOverlaySource,
+      hitTest: overlays.hitTestWorldOverlay,
+    },
+    openExternal: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+    screenSpaceEventHandlerFactory: (viewer) =>
+      new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas),
+    picking,
+    pointer: { isPointerFree },
+    ...options,
+  });
+}

src/app/layers/gnss.js

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

src/app/layers/localAdsb.js

@@ -0,0 +1,48 @@
+import { createLocalAdsbLayer } from '../../layers/localAdsb/index.js';
+import { createLocalReceiverFeeds } from '../../layers/localAdsb/feeds.js';
+import { SdrController } from '../../sdr/controller.js';
+import * as render from '../../renderGovernor.js';
+import * as context from '../../data/contextStore.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as trails from '../../data/trailRenderer.js';
+import * as geoid from '../../data/geoid.js';
+import { markDetectionSourcesChanged } from '../../data/detection.js';
+import { refreshTrackedReadout } from '../../data/trackedReadout.js';
+
+/**
+ * Construct the Local ADS-B layer, the browser RTL-SDR session it shares with
+ * the Radio panel, and the decoder-feed session. Construction opens no device
+ * and makes no request; the SDR starts only from an explicit Connect and the
+ * feeds are polled only while the layer is enabled.
+ *
+ * `displayParams` reads the public Flights layer's DISPLAY-rail 3D preference
+ * (`{ models3d, models3dMode }`) so local aircraft follow the same toggle;
+ * `enrichment` is the Flights source whose cached adsbdb proxy they share.
+ */
+export function createApplicationLocalAdsb({
+  receiver = new SdrController(),
+  feeds = createLocalReceiverFeeds(),
+  surface = null,
+  enrichment = null,
+  displayParams = null,
+  resolveAsset = (url) =>
+    `${import.meta.env?.BASE_URL || '/'}${url.replace(/^\//, '')}`,
+} = {}) {
+  return createLocalAdsbLayer({
+    receiver,
+    feeds,
+    resolveAsset,
+    services: {
+      render,
+      context,
+      picking,
+      trails,
+      geoid,
+      groundSnap: surface?.groundSnap || null,
+      enrichment,
+      display: displayParams ? { getParams: displayParams } : null,
+      detection: { markSourcesChanged: markDetectionSourcesChanged },
+      overlays: { refreshReadout: refreshTrackedReadout },
+    },
+  });
+}

src/app/layers/militaryAwareness.js

@@ -0,0 +1,23 @@
+import { createAwarenessLayer } from '../../layers/awareness/index.js';
+import * as navigation from '../../navigationPolicy.js';
+import * as geometry from '../../celestialRing.js';
+import * as render from '../../renderGovernor.js';
+/** Bind Contacts to the same catalog instances used for rendering. */
+export function createApplicationAwareness({
+  flights,
+  military,
+  vessels,
+  installations,
+}) {
+  return createAwarenessLayer({
+    services: {
+      flights,
+      military,
+      vessels,
+      installations,
+      navigation,
+      geometry,
+      render,
+    },
+  });
+}

src/app/layers/militaryFlights.js

@@ -0,0 +1,46 @@
+import { createMilitaryFlightLayer } from '../../layers/military/index.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as trails from '../../data/trailRenderer.js';
+import * as aircraftPresentation from '../../data/tr3bRegistry.js';
+import * as camera from '../../data/trackedCamera.js';
+import * as labels from '../../data/detectionDraw.js';
+import * as geoid from '../../data/geoid.js';
+import * as focus from '../../data/focusDeemphasis.js';
+import * as readout from '../../data/trackedReadout.js';
+import * as context from '../../data/contextStore.js';
+import * as render from '../../renderGovernor.js';
+import * as recession from '../../data/aircraftRecession.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationMilitary({
+  surface,
+  source,
+  militaryRegistry,
+  resolveAsset = (url) =>
+    `${import.meta.env?.BASE_URL || '/'}${url.replace(/^\//, '')}`,
+}) {
+  const { groundFloor, meshFloor, groundSnap } = surface;
+  return createMilitaryFlightLayer({
+    source,
+    resolveAsset,
+    services: {
+      picking,
+      sprites,
+      trails,
+      aircraftPresentation,
+      camera,
+      militaryRegistry,
+      labels,
+      groundFloor,
+      meshFloor,
+      geoid,
+      focus,
+      readout,
+      context,
+      render,
+      groundSnap,
+      recession,
+    },
+  });
+}

src/app/layers/militaryInstallations.js

@@ -0,0 +1,36 @@
+import { overlayHost } from './overlayHost.js';
+import * as credits from '../../data/dataCredits.js';
+import { createInstallationsLayer } from '../../layers/installations/index.js';
+import * as render from '../../renderGovernor.js';
+import * as context from '../../data/contextStore.js';
+import * as picking from '../../data/pickRegistry.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationInstallations({ surface, source }) {
+  const { groundFloor: ground, anchors } = surface;
+  return createInstallationsLayer({
+    source,
+    overlayHost,
+    services: {
+      credits,
+      render,
+      context,
+      ground,
+      anchors,
+      picking,
+      maps: {
+        subscribeMapStack(callback) {
+          globalThis.window?.addEventListener?.(
+            'gev:map-stack-changed',
+            callback,
+          );
+          return () =>
+            globalThis.window?.removeEventListener?.(
+              'gev:map-stack-changed',
+              callback,
+            );
+        },
+      },
+    },
+  });
+}

src/app/layers/overlayHost.js

@@ -0,0 +1,12 @@
+import {
+  clearOverlaySource,
+  getWorldOverlayDiagnostics,
+  setOverlayEntries,
+  setOverlaySourceVisible,
+} from '../../overlays/worldOverlay.js';
+export const overlayHost = Object.freeze({
+  clearSource: clearOverlaySource,
+  getDiagnostics: getWorldOverlayDiagnostics,
+  setEntries: setOverlayEntries,
+  setVisible: setOverlaySourceVisible,
+});

src/app/layers/perimeters.js

@@ -0,0 +1,29 @@
+import * as Cesium from 'cesium';
+import {
+  createFirePerimetersLayer,
+  createInciwebIndexSource,
+  createInciwebPublicationSource,
+} from '../../layers/perimeters/index.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import { isPointerFree } from '../../data/inputOwnership.js';
+
+/** Wire WFIGS fire perimeters into the application catalog. */
+export function createApplicationFirePerimeters(options) {
+  return createFirePerimetersLayer({
+    overlayHost: {
+      setEntries: overlays.setOverlayEntries,
+      setVisible: overlays.setOverlaySourceVisible,
+      clearSource: overlays.clearOverlaySource,
+      hitTest: overlays.hitTestWorldOverlay,
+    },
+    inciwebSource: createInciwebIndexSource(),
+    inciwebPublications: createInciwebPublicationSource(),
+    openExternal: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+    screenSpaceEventHandlerFactory: (viewer) =>
+      new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas),
+    picking,
+    pointer: { isPointerFree },
+    ...options,
+  });
+}

src/app/layers/radio.js

@@ -0,0 +1,14 @@
+import { createRadioLayer } from '../../layers/radio/index.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import * as globe from '../../celestialRing.js';
+import * as render from '../../renderGovernor.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationRadio({ surface, source }) {
+  const { groundFloor: ground } = surface;
+  return createRadioLayer({
+    source,
+    services: { ground, picking, overlays, globe, render },
+  });
+}

src/app/layers/recentImagery.js

@@ -0,0 +1,19 @@
+import { createRecentImageryLayer } from '../../layers/recentImagery/index.js';
+import { createRecentImageryRenderer } from '../../layers/recentImagery/rendering.js';
+import { createThumbnailLoader } from '../../layers/recentImagery/thumbnails.js';
+import { governorRequestRender } from '../../renderGovernor.js';
+
+/** 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),
+    }),
+  });
+}

src/app/layers/rocketLaunches.js

@@ -0,0 +1,12 @@
+import { createRocketLaunchesLayer } from '../../layers/launches/index.js';
+import * as geometry from '../../celestialRing.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import * as render from '../../renderGovernor.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationLaunches({ source, satellites }) {
+  return createRocketLaunchesLayer({
+    source,
+    services: { satellites, geometry, overlays, render },
+  });
+}

src/app/layers/satellites.js

@@ -0,0 +1,24 @@
+import { createSatellitesLayer } from '../../layers/satellites/index.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as focus from '../../data/focusDeemphasis.js';
+import * as readout from '../../data/trackedReadout.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import * as context from '../../data/contextStore.js';
+import * as render from '../../renderGovernor.js';
+import * as layerState from '../../data/layerState.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationSatellites({ source }) {
+  return createSatellitesLayer({
+    source,
+    services: {
+      picking,
+      focus,
+      readout,
+      overlays,
+      context,
+      render,
+      layerState,
+    },
+  });
+}

src/app/layers/streetLevel.js

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

src/app/layers/streetLevel.test.mjs

@@ -0,0 +1,88 @@
+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/,
+  );
+});
+
+test('the defaults are Mapillary (given its source), Street View, KartaView and Panoramax, which start off and travel as provider switches', async () => {
+  const { createDefaultLayerState } = await import('../../data/layerState.js');
+  const mapillary = {
+    getStatus() {},
+    getTile() {},
+    getSequenceImages() {},
+    nearestImages() {},
+  };
+  const layer = createApplicationStreetLevel({ sources: { mapillary } });
+  assert.deepEqual(layer.providerIds, [
+    'mapillary',
+    'google',
+    'kartaview',
+    'panoramax',
+  ]);
+  // A fresh page and a restored default agree: Street View is billed, so off.
+  layer.setParams(createDefaultLayerState().options['street-level']);
+  assert.equal(layer.getParams().google, false);
+  assert.equal(layer.getParams().mapillary, true);
+  // A link that lit Street View carries it in the shared switch field.
+  layer.setParams({ providerSwitches: 'google-1' });
+  assert.equal(layer.getParams().google, true);
+  assert.equal(
+    layer.getParams().providerSwitches,
+    'google-1*kartaview-0*panoramax-0',
+  );
+  // KartaView is keyless and free, but one source shows at a time.
+  layer.setParams({ providerSwitches: 'kartaview-1' });
+  assert.equal(layer.getParams().kartaview, true);
+  assert.equal(layer.getParams().google, false);
+  assert.equal(layer.getParams().mapillary, false);
+  // As is Panoramax: lighting it puts KartaView out.
+  layer.setParams({ providerSwitches: 'panoramax-1' });
+  assert.equal(layer.getParams().panoramax, true);
+  assert.equal(layer.getParams().kartaview, false);
+  assert.equal(layer.getParams().mapillary, false);
+  // The form the app writes (the README and CHANGELOG quote it).
+  assert.equal(
+    layer.getParams().providerSwitches,
+    'google-0*kartaview-0*panoramax-1',
+  );
+  // Without the application's Street Level source there are none.
+  assert.deepEqual(createApplicationStreetLevel({}).providerIds, []);
+});
+
+test('every built-in provider is exported, so hosts can choose their own list', async () => {
+  const google = await import('gods-eye-view/layers/street-level/google');
+  const kartaview = await import('gods-eye-view/layers/street-level/kartaview');
+  const panoramax = await import('gods-eye-view/layers/street-level/panoramax');
+  const layer = createApplicationStreetLevel({
+    providers: [
+      google.createGoogleProvider({ getApiKey: () => null }),
+      kartaview.createKartaViewProvider(),
+      panoramax.createPanoramaxProvider(),
+    ],
+  });
+  assert.deepEqual(layer.providerIds, ['google', 'kartaview', 'panoramax']);
+});

src/app/layers/submarineCables.js

@@ -0,0 +1,13 @@
+import * as Cesium from 'cesium';
+import { createSubmarineCableLayer } from '../../layers/submarineCables/index.js';
+import { overlayHost } from './overlayHost.js';
+/** Wire cable source geometry to the application overlay host. */
+export function createApplicationCables(options) {
+  return createSubmarineCableLayer({
+    overlayHost,
+    screenSpaceEventHandlerFactory: (canvas) =>
+      new Cesium.ScreenSpaceEventHandler(canvas),
+    mapStackEventTarget: typeof window !== 'undefined' ? window : null,
+    ...options,
+  });
+}

src/app/layers/traffic.js

@@ -0,0 +1,12 @@
+import { createTrafficLayer } from '../../layers/traffic/index.js';
+import * as credits from '../../data/dataCredits.js';
+import * as ground from '../../data/groundFloor.js';
+import * as render from '../../renderGovernor.js';
+
+/** Construct one layer using the application scene owners and a supplied source. */
+export function createApplicationTraffic({ source, surface }) {
+  return createTrafficLayer({
+    source,
+    services: { credits, render, ground: surface?.groundFloor || ground },
+  });
+}

src/app/layers/transit.js

@@ -0,0 +1,49 @@
+import { createTransitLayer } from '../../layers/transit/index.js';
+import * as render from '../../renderGovernor.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import {
+  registerDynamicCredit,
+  transitFeedCredit,
+} from '../../data/dataCredits.js';
+
+/**
+ * Construct one layer using the application scene owners and the
+ * application's surface services.
+ *
+ * The floor comes from `surface.groundFloor` — the ONE instance aircraft,
+ * trails, fires and camera geometry stand on — and the rendered-mesh sampler
+ * from `surface.meshFloor`, so a mesh floor the application resolves for a
+ * cell is the floor transit draws on, and a transit-only session warms its
+ * own mesh floors. An earlier cut imported the legacy module-level singleton
+ * instead and could not see either.
+ *
+ * @param {{surface: object}} options
+ * @returns {object}
+ */
+export function createApplicationTransit({ surface, source }) {
+  if (!surface?.groundFloor || !surface?.meshFloor)
+    throw new TypeError('Transit needs the application surface services');
+  const { groundFloor, meshFloor } = surface;
+  return createTransitLayer({
+    source,
+    services: {
+      render,
+      sprites,
+      picking,
+      overlays,
+      credits: { registerDynamicCredit, transitFeedCredit },
+      ground: {
+        GROUND_FLOOR_LIFT_M: groundFloor.GROUND_FLOOR_LIFT_M,
+        cachedGroundFloor: groundFloor.cachedGroundFloor,
+        coarseFloorCoord: groundFloor.coarseFloorCoord,
+        neighborFloorM: groundFloor.neighborFloorM,
+        warmGroundFloor: groundFloor.warmGroundFloor,
+        corridorFloorCells: groundFloor.corridorFloorCells,
+        allocateCorridorCells: groundFloor.allocateCorridorCells,
+      },
+      mesh: { sampleMeshFloorCells: meshFloor.sampleMeshFloorCells },
+    },
+  });
+}

src/app/layers/transit.test.mjs

@@ -0,0 +1,93 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createSurfaceServices } from '../surfaceServices.js';
+import { createApplicationTransit } from './transit.js';
+import { createApplicationCatalog } from '../constructCatalog.js';
+import { createStandaloneLayerSources } from '../../standalone/layerSources.js';
+
+/** A terrain source that answers every point with one ellipsoidal height. */
+function fixtureSurface(signal, demM) {
+  return createSurfaceServices({
+    terrainSource: {
+      getHeights: async (chunk) => chunk.map(() => ({ ellipsoid: demM })),
+    },
+    signal,
+    eventTarget: null,
+  });
+}
+
+test('transit reads the mesh floor the application resolved, through the application surface', async (t) => {
+  // The floor transit draws on is the ONE the application constructs — the
+  // instance aircraft and camera geometry stand on — not a module-level copy.
+  // An earlier cut imported the legacy singleton and could not see a mesh
+  // floor the app had already resolved for a cell; it drew on bare earth.
+  const lifetime = new AbortController();
+  t.after(() => lifetime.abort());
+  const surface = fixtureSurface(lifetime.signal, 20);
+  const layer = createApplicationTransit({ surface });
+  const height = layer._transitPartsForTest().height;
+  const lat = 42.3601;
+  const lon = -71.0589;
+
+  // Nothing warm yet: the layer has no floor and no prior to borrow.
+  assert.equal(height.requestHeight(lat, lon).height, null);
+
+  // The application resolves the DEM for that cell...
+  await surface.groundFloor.resolveGroundFloorCells([{ lat, lon }]);
+  const lift = surface.groundFloor.GROUND_FLOOR_LIFT_M;
+  assert.equal(
+    height.requestHeight(lat, lon).height,
+    20 + lift,
+    'the DEM floor, lifted',
+  );
+
+  // ...and then a rendered-mesh sample lands on the same cell, seventeen
+  // metres above bare earth, the way a photogrammetric street sits.
+  assert.equal(
+    surface.groundFloor.reportValidatedMeshFloorCell(lat, lon, 37),
+    true,
+  );
+  assert.equal(
+    surface.groundFloor.cachedGroundFloor(lat, lon),
+    37,
+    'the app now floors on the mesh',
+  );
+  assert.equal(
+    height.requestHeight(lat, lon).height,
+    37 + lift,
+    'and so does transit — the same number',
+  );
+
+  // Leaving the photoreal regime drops back to the DEM for everyone at once.
+  surface.groundFloor.setMeshFloorPreferred(false);
+  assert.equal(height.requestHeight(lat, lon).height, 20 + lift);
+});
+
+test('the catalog hands transit the same surface it hands everything else', async (t) => {
+  const lifetime = new AbortController();
+  t.after(() => lifetime.abort());
+  const surface = fixtureSurface(lifetime.signal, 5);
+  const catalog = createApplicationCatalog({
+    sources: createStandaloneLayerSources(),
+    signal: lifetime.signal,
+    surface,
+  });
+  const transit = catalog.get('transit');
+  assert.ok(transit, 'transit is in the catalog');
+  const lat = 30.2672;
+  const lon = -97.7431;
+  await surface.groundFloor.resolveGroundFloorCells([{ lat, lon }]);
+  surface.groundFloor.reportValidatedMeshFloorCell(lat, lon, 22);
+  assert.equal(
+    transit._transitPartsForTest().height.requestHeight(lat, lon).height,
+    22 + surface.groundFloor.GROUND_FLOOR_LIFT_M,
+  );
+});
+
+test('transit refuses to build without the application surface', () => {
+  assert.throws(() => createApplicationTransit({}), /surface/);
+  assert.throws(
+    () => createApplicationTransit({ surface: { groundFloor: {} } }),
+    /surface/,
+  );
+});

src/app/localGeojsonServices.js

@@ -0,0 +1,28 @@
+import { showOsmCredit, hideOsmCredit } from '../data/dataCredits.js';
+import { governorRequestRender } from '../renderGovernor.js';
+import {
+  clearSelectedEntityContextForLayer,
+  registerEntityContext,
+  removeEntityContextsForLayer,
+  selectEntityContext,
+} from '../data/contextStore.js';
+import {
+  clearOverlaySource,
+  setOverlayEntries,
+  setOverlaySourceVisible,
+} from '../overlays/worldOverlay.js';
+/** Existing standalone application operations, shared by its local layers. */
+export const localGeoJsonServices = Object.freeze({
+  overlayHost: Object.freeze({
+    clearSource: clearOverlaySource,
+    setEntries: setOverlayEntries,
+    setVisible: setOverlaySourceVisible,
+  }),
+  clearSelectedEntityContextForLayer,
+  registerEntityContext,
+  removeEntityContextsForLayer,
+  selectEntityContext,
+  governorRequestRender,
+  showOsmCredit,
+  hideOsmCredit,
+});

src/app/operations.js

@@ -0,0 +1,50 @@
+import { requireFeatureSource } from '../sources/featureSource.js';
+import { createOverpassFeatureSource } from '../sources/overpassFeatures.js';
+import { createSurfaceServices } from './surfaceServices.js';
+import { createAnnotationResolver } from '../annotations/resolver.js';
+import { searchAndFlyTo } from '../locations.js';
+
+/** Assemble application operations from the caller's request services. */
+export function createApplicationOperations({ requests, signal, eventTarget }) {
+  for (const [name, method] of Object.entries({
+    terrain: 'getHeights',
+    regional: 'getBrief',
+    weather: 'getConditions',
+    summary: 'summarize',
+  })) {
+    if (typeof requests?.[name]?.[method] !== 'function')
+      throw new TypeError(`Missing application request service: ${name}`);
+  }
+  const features = requireFeatureSource(
+    requests.features ??
+      createOverpassFeatureSource({
+        boundarySource: requests.boundaries,
+        signal,
+      }),
+  );
+  const surface = createSurfaceServices({
+    terrainSource: requests.terrain,
+    signal,
+    eventTarget,
+  });
+  const annotationResolver = createAnnotationResolver({
+    featureSource: features,
+    signal,
+  });
+  return Object.freeze({
+    requests,
+    surface,
+    annotationResolver,
+    searchAndFlyTo: (viewer, query, options = {}) =>
+      searchAndFlyTo(viewer, query, {
+        ...options,
+        features,
+        ground: surface.groundFloor,
+        signal:
+          signal && options.signal
+            ? AbortSignal.any([signal, options.signal])
+            : signal || options.signal,
+        recoverNearView: annotationResolver.placesNearViewRecovery,
+      }),
+  });
+}

src/app/operations.test.mjs

@@ -0,0 +1,184 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createApplicationOperations } from './operations.js';
+
+function requests(terrain, boundaries = { query: async () => [] }) {
+  return {
+    terrain,
+    boundaries,
+    regional: { getBrief: async () => ({}) },
+    weather: { getConditions: async () => ({}) },
+    summary: { summarize: async () => ({}) },
+  };
+}
+
+test('surface cache and stack listeners belong to the supplied application lifetime', async (t) => {
+  const a = new AbortController();
+  const b = new AbortController();
+  t.after(() => {
+    a.abort();
+    b.abort();
+  });
+  const target = new EventTarget();
+  let calls = 0;
+  const first = createApplicationOperations({
+    signal: a.signal,
+    eventTarget: target,
+    requests: requests({
+      async getHeights(points) {
+        calls++;
+        return points.map(() => ({ ellipsoid: 123 }));
+      },
+    }),
+  });
+  const second = createApplicationOperations({
+    signal: b.signal,
+    eventTarget: target,
+    requests: requests({
+      async getHeights(points) {
+        return points.map(() => ({ ellipsoid: 456 }));
+      },
+    }),
+  });
+  const point = { lat: 30, lon: -97 };
+  await first.surface.terrain.resolveEllipsoidalGround([point]);
+  await first.surface.terrain.resolveEllipsoidalGround([point]);
+  await second.surface.terrain.resolveEllipsoidalGround([point]);
+  assert.equal(calls, 1);
+  assert.equal(first.surface.groundFloor.cachedGroundFloor(30, -97), 123);
+  assert.equal(second.surface.groundFloor.cachedGroundFloor(30, -97), 456);
+  target.dispatchEvent(
+    new CustomEvent('gev:map-stack-changed', {
+      detail: { activeId: 'esri-imagery' },
+    }),
+  );
+  assert.equal(first.surface.groundFloor.meshFloorPreferred(), false);
+  a.abort();
+  assert.equal(first.surface.terrain.cachedEllipsoidalGround(30, -97), null);
+  target.dispatchEvent(
+    new CustomEvent('gev:map-stack-changed', {
+      detail: { activeId: 'photoreal' },
+    }),
+  );
+  assert.equal(
+    first.surface.groundFloor.meshFloorPreferred(),
+    false,
+    'disposed listener cannot update the old owner',
+  );
+  assert.equal(second.surface.groundFloor.meshFloorPreferred(), true);
+});
+
+test('a terrain reply after application abort cannot refill the cache or become a fallback', async () => {
+  const lifetime = new AbortController();
+  let respond;
+  let receivedSignal;
+  const operations = createApplicationOperations({
+    signal: lifetime.signal,
+    eventTarget: null,
+    requests: requests({
+      getHeights(_points, { signal }) {
+        receivedSignal = signal;
+        return new Promise((resolve) => {
+          respond = resolve;
+        });
+      },
+    }),
+  });
+  const pending = operations.surface.terrain.resolveEllipsoidalGround([
+    { lat: 30, lon: -97 },
+  ]);
+  lifetime.abort();
+  respond([{ ellipsoid: 123 }]);
+  await assert.rejects(pending, { name: 'AbortError' });
+  assert.equal(receivedSignal.aborted, true);
+  assert.equal(
+    operations.surface.terrain.cachedEllipsoidalGround(30, -97),
+    null,
+  );
+});
+
+test('annotation lookup and cached outlines use the supplied source independently', async (t) => {
+  const priorWindow = globalThis.window;
+  globalThis.window = { setTimeout, clearTimeout };
+  const a = new AbortController();
+  const b = new AbortController();
+  t.after(() => {
+    a.abort();
+    b.abort();
+    if (priorWindow === undefined) delete globalThis.window;
+    else globalThis.window = priorWindow;
+  });
+  const calls = [0, 0];
+  const make = (signal, index) =>
+    createApplicationOperations({
+      signal,
+      eventTarget: null,
+      requests: requests(
+        { getHeights: async () => [] },
+        {
+          query: async () => {
+            calls[index]++;
+            const delta = index * 0.0001;
+            return [
+              {
+                type: 'way',
+                id: index + 1,
+                tags: { building: 'yes', name: 'Source fixture hall' },
+                geometry: [
+                  { lat: 30 - 0.0001, lon: -97 - 0.0001 + delta },
+                  { lat: 30 - 0.0001, lon: -97 + 0.0001 + delta },
+                  { lat: 30 + 0.0001, lon: -97 + 0.0001 + delta },
+                  { lat: 30 + 0.0001, lon: -97 - 0.0001 + delta },
+                  { lat: 30 - 0.0001, lon: -97 - 0.0001 + delta },
+                ],
+              },
+            ];
+          },
+        },
+      ),
+    });
+  const first = make(a.signal, 0);
+  const second = make(b.signal, 1);
+  const query = {
+    viewer: {},
+    target: 'Source fixture hall',
+    latitude: 30,
+    longitude: -97,
+    footprint: true,
+    entityKind: 'building',
+  };
+  const resultA = await first.annotationResolver.resolveAnnotationTarget(query);
+  const resultB =
+    await second.annotationResolver.resolveAnnotationTarget(query);
+  assert.ok(resultA.ring?.length >= 4);
+  assert.ok(resultB.ring?.length >= 4);
+  assert.notDeepEqual(resultA.ring, resultB.ring);
+  const before = calls[0];
+  const cached = await first.annotationResolver.resolveAnnotationTarget(query);
+  assert.deepEqual(cached.ring, resultA.ring);
+  assert.equal(calls[0], before);
+  a.abort();
+  await assert.rejects(
+    first.annotationResolver.resolveAnnotationTarget(query),
+    { name: 'AbortError' },
+  );
+});
+
+test('invalid feature adapters fail before surface listeners are installed', () => {
+  let installed = 0;
+  assert.throws(
+    () =>
+      createApplicationOperations({
+        signal: new AbortController().signal,
+        requests: { ...requests({ getHeights: async () => [] }), features: {} },
+        eventTarget: {
+          addEventListener() {
+            installed++;
+          },
+          removeEventListener() {},
+        },
+      }),
+    /Missing feature operation/,
+  );
+  assert.equal(installed, 0);
+});

src/app/scene.js

@@ -0,0 +1,132 @@
+import { createApplicationOperations } from './operations.js';
+import * as Cesium from 'cesium';
+import {
+  createApplicationViewer,
+  installTrackpadPinchZoom,
+} from '../app/viewer.js';
+import { registerDataCredits } from '../data/dataCredits.js';
+import { configureCreditKeyboardAccess } from '../creditKeyboard.js';
+import { MapStackController } from '../mapStackController.js';
+import { loadPhotorealisticTileset } from '../mapStartup.js';
+import { initLogoGaze } from '../logoGaze.js';
+import {
+  uninstallRenderGovernor,
+  governorRequestRender,
+} from '../renderGovernor.js';
+import { describeError } from './errors.js';
+import { onLocaleChange, t } from '../i18n/index.js';
+
+/** Construct the application globe using the caller's local configuration. */
+export async function createApplicationScene({
+  requestServices,
+  googleApiKey,
+  googleTokens = null,
+  cesiumToken,
+  credits,
+  MapController = MapStackController,
+  mapOptions = {},
+  loaderStatus,
+  signal,
+  defer,
+}) {
+  const operations = createApplicationOperations({
+    requests: requestServices,
+    signal,
+  });
+  defer(initLogoGaze());
+  const previousKey = window.__GOOGLE_MAPS_API_KEY__;
+  if (googleApiKey) {
+    window.__GOOGLE_MAPS_API_KEY__ = googleApiKey;
+    defer(() => {
+      if (window.__GOOGLE_MAPS_API_KEY__ !== googleApiKey) return;
+      if (previousKey === undefined) delete window.__GOOGLE_MAPS_API_KEY__;
+      else window.__GOOGLE_MAPS_API_KEY__ = previousKey;
+    });
+  }
+  loaderStatus.textContent = t('Configuring viewer...');
+  // Provider attribution stays visible, including clean-view and recording.
+  const creditContainer = document.createElement('div');
+  creditContainer.id = 'cesium-credits';
+  document.body.appendChild(creditContainer);
+  defer(() => creditContainer.remove());
+  const viewer = createApplicationViewer({
+    container: 'cesiumContainer',
+    creditContainer,
+  });
+  defer(() => {
+    uninstallRenderGovernor(viewer);
+    if (!viewer.isDestroyed()) viewer.destroy();
+  });
+  defer(installTrackpadPinchZoom(viewer));
+  registerDataCredits(viewer, credits);
+  configureCreditKeyboardAccess(document);
+  defer(onLocaleChange(() => configureCreditKeyboardAccess(document)));
+  loaderStatus.textContent =
+    googleApiKey || googleTokens || cesiumToken
+      ? t('Loading Google 3D Tiles...')
+      : t('Loading the keyless globe...');
+  const photoreal = await loadPhotorealisticTileset(Cesium, {
+    googleApiKey,
+    googleTokens,
+    cesiumToken,
+  });
+  const tileset = photoreal.tileset;
+  // A provider can finish after cancellation; retain ownership of its result.
+  defer(() => {
+    if (tileset && !tileset.isDestroyed()) {
+      if (!viewer.scene.primitives.remove(tileset)) tileset.destroy();
+    }
+  });
+  signal.throwIfAborted();
+  if (tileset) {
+    viewer.scene.primitives.add(tileset);
+    // NOTE: Cesium World Terrain intentionally disabled — conflicts with Google 3D Tiles at high zoom.
+    // Google Photorealistic 3D Tiles provide their own terrain/elevation.
+    viewer.scene.globe.show = false;
+    console.info(`[Init] Google 3D Tiles loaded via ${photoreal.route}.`);
+  } else {
+    if (photoreal.errors.length) {
+      const tileError = photoreal.errors.at(-1);
+      console.warn(
+        '[Init] Google 3D Tiles unavailable, using the keyless globe:',
+        tileError,
+      );
+      const tileErrorDetail = describeError(tileError);
+      loaderStatus.textContent = t(
+        'Google 3D Tiles unavailable ({detail}). Loading the keyless globe...',
+        {
+          detail: tileErrorDetail,
+        },
+      );
+    }
+    viewer.scene.globe.show = true;
+  }
+
+  loaderStatus.textContent = t('Initializing systems...');
+
+  const mapStackController = new MapController(viewer, {
+    requestRender: governorRequestRender,
+    ...mapOptions,
+    googleTileset: tileset,
+    cesiumToken,
+    initialStack: tileset ? 'photoreal' : 'esri-imagery',
+    // Task 5 (height-datum fix): rebroadcast stack changes as a window
+    // CustomEvent so data layers (CCTV per-regime ground resolution) can
+    // react without coupling MapStackController to layer modules. Fires on
+    // 'switching'/'ready'/'error'; listeners derive the surface regime from
+    // live scene state, so intermediate emissions are harmless.
+    onChange: (state) => {
+      window.dispatchEvent(
+        new CustomEvent('gev:map-stack-changed', { detail: state }),
+      );
+    },
+    onError: (message) => console.warn('[MapStack]', message),
+  });
+  defer(() => mapStackController.destroy());
+  await mapStackController.setStack(tileset ? 'photoreal' : 'esri-imagery', {
+    silent: true,
+  });
+
+  signal.throwIfAborted();
+  return { viewer, tileset, mapStackController, operations };
+}

src/app/sourceComposition.js

@@ -0,0 +1,116 @@
+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']),
+  'air-quality': contract(['air-quality'], ['getSnapshot']),
+  'gnss-integrity': contract(['gnss-integrity'], ['getSnapshot']),
+  's2-ghostmaps': contract(['s2-ghostmaps'], ['getCatalog', 'getFile']),
+  cables: contract(['telegeography-submarine-cables'], ['fetch']),
+  transit: contract(['transit'], ['requestSnapshot', 'getHistory']),
+});
+
+/** An omitted provider is unavailable, never an authoritative empty dataset. */
+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,220 @@
+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, 34);
+  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('GhostMaps obeys source omission, replacement and explicit removal', async (t) => {
+  let fetches = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    fetches++;
+    throw new Error('Unexpected standalone acquisition');
+  });
+  const missing = catalog({}, t);
+  assert.equal(missing.getSourceAvailability('s2-ghostmaps')?.available, false);
+  const manager = new LayerLifecycle(
+    {},
+    { getSourceAvailability: missing.getSourceAvailability },
+  );
+  manager.register(missing.get('s2-ghostmaps'));
+  assert.equal(await manager.setEnabled('s2-ghostmaps', true), false);
+  assert.equal(manager.layers.get('s2-ghostmaps').initialized, false);
+  assert.equal(
+    createStandaloneLayerSources({ 's2-ghostmaps': null })['s2-ghostmaps'],
+    null,
+  );
+
+  let reads = 0;
+  let subscriptions = 0;
+  let unsubscribed = 0;
+  const source = {
+    getCatalog: async () => {
+      reads++;
+      return { commit: 'a'.repeat(40), products: [] };
+    },
+    getFile: async () => {
+      throw new Error('Empty catalog must not read files');
+    },
+    subscribe: () => {
+      subscriptions++;
+      return () => {
+        unsubscribed++;
+      };
+    },
+  };
+  const supplied = createStandaloneLayerSources({ 's2-ghostmaps': source });
+  assert.equal(supplied['s2-ghostmaps'], source);
+  const configured = catalog(supplied, t);
+  assert.equal(
+    configured.getSourceAvailability('s2-ghostmaps').available,
+    true,
+  );
+  const previous = Object.getOwnPropertyDescriptor(globalThis, 'document');
+  globalThis.document = { addEventListener() {}, removeEventListener() {} };
+  t.after(() => {
+    if (previous) Object.defineProperty(globalThis, 'document', previous);
+    else delete globalThis.document;
+  });
+  const layer = configured.get('s2-ghostmaps');
+  t.after(() => layer.destroy());
+  layer.init({ scene: { requestRender() {} } });
+  layer.enable();
+  await layer.update();
+  layer.disable();
+  assert.equal(reads, 1);
+  assert.equal(subscriptions, 1);
+  assert.equal(unsubscribed, 1);
+  assert.equal(layer.getStats().commit, 'a'.repeat(40));
+  assert.equal(fetches, 0);
+});
+
+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/sources.js

@@ -0,0 +1,45 @@
+import flights from '../data/flights.js';
+import military from '../data/militaryFlights.js';
+import vessels from '../data/aisLiveVessels.js';
+import { configureAlprSource } from '../data/alprCameras.js';
+import { configureCctvSource } from '../data/cctv.js';
+import { configureRadioSource } from '../data/radio.js';
+import { configureTrafficSource } from '../data/traffic.js';
+import { configureBikeshareSource } from '../data/bikeshare.js';
+import { configureInstallationSource } from '../data/militaryInstallations.js';
+import { configureSatelliteSource } from '../data/satellites.js';
+import { configureLaunchSource } from '../data/rocketLaunches.js';
+import { configureFirmsSource } from '../data/firmsHeatmap.js';
+import { configureWindSource } from '../data/wind.js';
+import { configureMilitaryRegistrySource } from '../data/militaryRegistry.js';
+const configure = {
+  alpr: configureAlprSource,
+  cctv: configureCctvSource,
+  radio: configureRadioSource,
+  traffic: configureTrafficSource,
+  bikeshare: configureBikeshareSource,
+  installations: configureInstallationSource,
+  satellites: configureSatelliteSource,
+  launches: configureLaunchSource,
+  firms: configureFirmsSource,
+  wind: configureWindSource,
+};
+/** Configure sources before any registration or state restoration starts. */
+export function configureApplicationSources({
+  layers = {},
+  live = {},
+  signal,
+  defer,
+}) {
+  for (const [name, source] of Object.entries(layers)) {
+    if (!configure[name]) throw new TypeError(`Unknown layer source: ${name}`);
+    defer(configure[name](source));
+  }
+  if (live.flights) flights.setSource(live.flights);
+  if (live.military) {
+    military.setSource(live.military);
+    defer(configureMilitaryRegistrySource(live.military, { signal }));
+  }
+  if (live.vessels) vessels.setSource(live.vessels);
+}
+export const liveLayers = Object.freeze({ flights, military, vessels });

src/app/startupChrome.js

@@ -0,0 +1,54 @@
+import { initFirstRunExperience } from '../firstRunExperience.js';
+
+/** Reveal welcome controls only after restoration and the loading transition. */
+export function startApplicationChrome({
+  loadingScreen,
+  styleManager,
+  dataManager,
+  signal,
+  initializeWelcome = initFirstRunExperience,
+  initializeSettings,
+}) {
+  let disposed = false;
+  let firstRun;
+  let revealTimer;
+  let resolveDelay;
+  const minimumDelay = new Promise((resolve) => {
+    resolveDelay = resolve;
+  });
+  const delayTimer = setTimeout(resolveDelay, 1000);
+  const revealFirstRun = () => {
+    if (disposed || signal.aborted || firstRun) return;
+    firstRun = initializeWelcome?.({ styleManager, dataManager });
+    clearTimeout(revealTimer);
+    loadingScreen.removeEventListener('transitionend', revealFirstRun);
+  };
+  void Promise.all([styleManager.initialRestorePromise, minimumDelay])
+    .catch(() => {
+      /* Restoration reports its own outcome through the controls. */
+    })
+    .then(() => {
+      if (disposed || signal.aborted) return;
+      loadingScreen.classList.add('hidden');
+      loadingScreen.addEventListener('transitionend', revealFirstRun, {
+        once: true,
+      });
+      revealTimer = setTimeout(revealFirstRun, 900);
+    });
+  const keySetup = Promise.resolve(
+    signal.aborted ? null : initializeSettings?.({ signal }),
+  );
+  // Own the pending initializer too; it must not reveal a dialog after abort.
+  void keySetup.catch(() =>
+    console.error('Provider settings initialization failed'),
+  );
+  return async () => {
+    disposed = true;
+    clearTimeout(delayTimer);
+    clearTimeout(revealTimer);
+    resolveDelay();
+    loadingScreen.removeEventListener('transitionend', revealFirstRun);
+    firstRun?.destroy();
+    (await keySetup.catch(() => null))?.destroy();
+  };
+}

src/app/stateChannel.js

@@ -0,0 +1,111 @@
+/** Copy plain product data so a subscriber cannot mutate its owner's state. */
+function copyState(value, ancestors = new Set()) {
+  if (value === null) return value;
+  if (typeof value !== 'object') {
+    if (['string', 'number', 'boolean', 'undefined'].includes(typeof value))
+      return value;
+    throw new TypeError('Product state must contain plain data');
+  }
+  if (ancestors.has(value)) throw new TypeError('Circular product state');
+  if (
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) !== Object.prototype &&
+    Object.getPrototypeOf(value) !== null
+  ) {
+    throw new TypeError('Product state must contain plain records');
+  }
+  const next = new Set(ancestors).add(value);
+  const copy = Array.isArray(value)
+    ? value.map((item) => copyState(item, next))
+    : Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [
+          key,
+          copyState(item, next),
+        ]),
+      );
+  return Object.freeze(copy);
+}
+
+/**
+ * Publish immutable snapshots and ordinary action outcomes synchronously.
+ * Reentrant publications retain order. New subscribers start at current state;
+ * removed subscribers and destroyed channels cannot receive queued work.
+ */
+export function createStateChannel(readSnapshot) {
+  const listeners = new Set();
+  const pending = [];
+  let revision = 0;
+  let delivering = false;
+  let destroyed = false;
+  let lastSnapshot = null;
+  const getSnapshot = () => {
+    if (!destroyed) lastSnapshot = copyState(readSnapshot());
+    return lastSnapshot;
+  };
+  const deliver = (entry, notification) => {
+    try {
+      entry.listener(notification);
+    } catch {
+      console.error('Product state listener failed');
+    }
+  };
+  return Object.freeze({
+    getSnapshot,
+    subscribe(listener, { emitCurrent = true } = {}) {
+      if (typeof listener !== 'function')
+        throw new TypeError('Expected a state listener');
+      if (destroyed) return () => {};
+      const state = emitCurrent ? getSnapshot() : null;
+      const entry = { listener, revision };
+      listeners.add(entry);
+      if (emitCurrent)
+        deliver(
+          entry,
+          Object.freeze({
+            state,
+            change: null,
+            revision,
+            initial: true,
+          }),
+        );
+      return () => listeners.delete(entry);
+    },
+    publish(change = null) {
+      if (destroyed) return false;
+      pending.push(
+        Object.freeze({
+          state: getSnapshot(),
+          change: copyState(change),
+          revision: ++revision,
+          initial: false,
+        }),
+      );
+      if (delivering) return true;
+      delivering = true;
+      try {
+        while (!destroyed && pending.length) {
+          const notification = pending.shift();
+          for (const entry of [...listeners]) {
+            if (
+              destroyed ||
+              !listeners.has(entry) ||
+              entry.revision >= notification.revision
+            )
+              continue;
+            entry.revision = notification.revision;
+            deliver(entry, notification);
+          }
+        }
+      } finally {
+        delivering = false;
+      }
+      return true;
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      listeners.clear();
+      pending.length = 0;
+    },
+  });
+}

src/app/stateChannel.test.mjs

@@ -0,0 +1,99 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createStateChannel } from './stateChannel.js';
+
+test('snapshots and action data are immutable copies of live product state', () => {
+  const live = { selected: { id: 'a' }, items: ['a'] };
+  const channel = createStateChannel(() => live);
+  const received = [];
+  channel.subscribe((event) => received.push(event));
+  const change = { type: 'selected', item: { id: 'b' } };
+  live.selected.id = 'b';
+  channel.publish(change);
+  change.item.id = 'mutated';
+  assert.equal(received[0].initial, true);
+  assert.equal(received[0].state.selected.id, 'a');
+  assert.equal(received[1].state.selected.id, 'b');
+  assert.equal(received[1].change.item.id, 'b');
+  assert.throws(() => received[1].state.items.push('c'), TypeError);
+  assert.deepEqual(live.items, ['a']);
+});
+
+test('reentrant updates retain order and a new subscriber never regresses behind its initial snapshot', () => {
+  let count = 0;
+  const channel = createStateChannel(() => ({ count }));
+  const first = [],
+    second = [],
+    joined = [];
+  channel.subscribe(({ state, initial }) => {
+    if (initial) return;
+    first.push(state.count);
+    if (state.count === 1) {
+      count = 2;
+      channel.publish({ type: 'next' });
+      channel.subscribe(({ state }) => joined.push(state.count));
+    }
+  });
+  channel.subscribe(({ state, initial }) => {
+    if (!initial) second.push(state.count);
+  });
+  count = 1;
+  channel.publish();
+  assert.deepEqual(first, [1, 2]);
+  assert.deepEqual(second, [1, 2]);
+  assert.deepEqual(joined, [2]);
+});
+
+test('unsubscribe and destroy during delivery revoke pending callbacks and future reads', () => {
+  let reads = 0;
+  const channel = createStateChannel(() => ({ reads: ++reads }));
+  let late = 0;
+  let remove;
+  channel.subscribe(
+    () => {
+      remove();
+      channel.publish();
+      channel.destroy();
+    },
+    { emitCurrent: false },
+  );
+  remove = channel.subscribe(() => late++, { emitCurrent: false });
+  channel.publish();
+  const stoppedReads = reads;
+  channel.publish();
+  channel.subscribe(() => late++);
+  channel.destroy();
+  remove();
+  assert.equal(late, 0);
+  assert.equal(reads, stoppedReads);
+});
+
+test('a failed subscriber cannot prevent other controls from receiving an update', () => {
+  const channel = createStateChannel(() => ({ selected: 'a' }));
+  const errors = [];
+  const original = console.error;
+  console.error = (message) => errors.push(message);
+  try {
+    channel.subscribe(() => {
+      throw new Error('consumer failure');
+    });
+    let received = 0;
+    channel.subscribe(() => received++);
+    channel.publish();
+    assert.equal(received, 2);
+    assert.equal(errors.length, 2);
+  } finally {
+    console.error = original;
+    channel.destroy();
+  }
+});
+
+test('an invalid initial snapshot cannot retain a subscriber without a cleanup handle', () => {
+  let live = { action() {} };
+  const channel = createStateChannel(() => live);
+  let calls = 0;
+  assert.throws(() => channel.subscribe(() => calls++), /plain data/);
+  live = { selected: 'a' };
+  channel.publish();
+  assert.equal(calls, 0);
+});

src/app/surfaceServices.js

@@ -0,0 +1,37 @@
+import { createTerrainHeights } from '../services/terrainHeights.js';
+import { createGroundFloor } from '../services/groundFloor.js';
+import { createMeshFloorSampler } from '../services/meshFloorSampler.js';
+import { createGroundSnap } from '../services/groundSnap.js';
+import { createFireAnchors } from '../layers/firms/anchors.js';
+
+/** Own the DEM, coarse floors and mesh samples used by one application. */
+export function createSurfaceServices({
+  terrainSource,
+  signal,
+  eventTarget = globalThis.window,
+}) {
+  const terrain = createTerrainHeights({ source: terrainSource, signal });
+  const groundFloor = createGroundFloor({ terrain, signal });
+  const meshFloor = createMeshFloorSampler({
+    groundFloor,
+    signal,
+    eventTarget,
+  });
+  return Object.freeze({
+    terrain,
+    groundFloor,
+    meshFloor,
+    groundSnap: Object.freeze({
+      createGroundSnap: () => createGroundSnap({ groundFloor }),
+    }),
+    anchors: createFireAnchors(groundFloor),
+    controlServices: Object.freeze({
+      cachedGroundFloor: groundFloor.cachedGroundFloor,
+      cachedMeshFloor: groundFloor.cachedMeshFloor,
+      GROUND_FLOOR_LIFT_M: groundFloor.GROUND_FLOOR_LIFT_M,
+      meshFloorPreferred: groundFloor.meshFloorPreferred,
+      warmGroundFloor: groundFloor.warmGroundFloor,
+      sampleMeshFloorCells: meshFloor.sampleMeshFloorCells,
+    }),
+  });
+}

src/app/tools.js

@@ -0,0 +1,229 @@
+import { SceneDirector } from '../scenes/director.js';
+import { initAnnotations } from '../annotations/index.js';
+import { initDrawTool } from '../annotations/drawTool.js';
+import { initGeoFileImport } from '../ui/geoFileImport.js';
+import { useDisplayStore } from '../ui/stores/display.js';
+import { applicationPinia } from '../ui/vueRuntime.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 { installLayerReleaseTrim } from '../sceneCommandRelease.js';
+import {
+  installRenderGovernor,
+  getRenderGovernorDiagnostics,
+  governorRequestRender,
+  holdContinuousRender,
+  releaseContinuousRender,
+} from '../renderGovernor.js';
+
+/** Attach scene tools, rendering listeners and the application debug handle. */
+export function createApplicationTools({
+  scene,
+  controls,
+  data,
+  loadingScreen,
+  placeSearch,
+  voice = {},
+  startChrome,
+  onSceneDirector,
+  sceneDataPacks,
+  signal,
+  defer,
+}) {
+  const { viewer, tileset, mapStackController, operations } = scene;
+  const { styleManager, weatherEffects, cockpitCloudEffects } = controls;
+  const { dataManager } = data;
+  const sceneDirector = new SceneDirector(viewer, styleManager, dataManager, {
+    dataPacks: sceneDataPacks,
+    isMapStackAvailable: (id) =>
+      mapStackController?.isStackAvailable(id) === true,
+  });
+  dataManager.layers
+    .get('bhote-koshi-2026')
+    ?.module.attachSceneController(sceneDirector);
+  defer(() => sceneDirector.destroy());
+  onSceneDirector?.(sceneDirector);
+  const annotations = initAnnotations({
+    viewer,
+    tileset,
+    placeSearch,
+    resolver: operations.annotationResolver,
+  });
+  defer(() => {
+    if (window.__gevAnnotations === annotations) delete window.__gevAnnotations;
+    annotations.destroy();
+  });
+  const displayStore = useDisplayStore(applicationPinia());
+  // The Display panel's controls answer through the store; returns the
+  // disconnect.
+  const connectDisplay = (actions) => {
+    const token = displayStore.connect(actions);
+    return () => displayStore.detach(token);
+  };
+  // DISPLAY ▸ Draw: the same whiteboard, drawn by hand. It claims the pointer
+  // while a session is open, so its teardown belongs to the application
+  // lifetime rather than to whoever last pressed the button.
+  const drawTool = initDrawTool({
+    viewer,
+    annotations,
+    publish: (view) => displayStore.publishDraw(view),
+    connect: connectDisplay,
+  });
+  defer(() => drawTool?.destroy());
+  // DISPLAY ▸ Import: the person's own GeoJSON/KML/KMZ/GPX files, each its
+  // own data source. They live for the page session, so the application
+  // lifetime removes them and the drop listeners on the viewer container.
+  const geoFileImport = initGeoFileImport({
+    viewer,
+    navigation: styleManager,
+    ground: operations.surface?.groundFloor,
+    subscribeMapSource: (listener) => mapStackController?.subscribe?.(listener),
+    publish: (view) => displayStore.publishGeoImport(view),
+    connect: connectDisplay,
+  });
+  defer(() => geoFileImport?.destroy());
+  // DATA ▸ Recent Imagery: the box tool claims the pointer like Draw and the
+  // panel lives on the right rail, so both belong to the application
+  // lifetime. The tileset lets the layer drape while the globe is hidden.
+  const recentImagery = dataManager.layers.get('recent-imagery')?.module;
+  if (recentImagery) {
+    recentImagery.attachTileset(tileset);
+    const imageryBoxTool = initImageryBoxTool({
+      viewer,
+      onBox: (box) => recentImagery.setBox(box),
+      onCancel: (reason, message, box) => {
+        if (message) recentImagery.reportBoxRefusal(message, box);
+      },
+      onActive: (active) => recentImagery.setToolActive(active),
+      // The tool takes Escape in a capture listener, so the panel's order
+      // (clear a preview before cancelling the tool) is applied here.
+      onEscape: () => recentImagery.clearPreview(),
+    });
+    // The readout mounts in its rail body through the layer panel, like the
+    // weather readout.
+    data.presentation.attachRecentImagery((container) =>
+      createRecentImageryPanel({
+        container,
+        viewer,
+        layer: recentImagery,
+        tool: imageryBoxTool,
+      }),
+    );
+    // The live gate's handle (scripts/qa-recent-imagery.mjs).
+    const recentImageryHandle = { layer: recentImagery, tool: imageryBoxTool };
+    window.__gevRecentImagery = recentImageryHandle;
+    defer(() => {
+      if (window.__gevRecentImagery === recentImageryHandle)
+        delete window.__gevRecentImagery;
+      data.presentation.attachRecentImagery(null);
+      imageryBoxTool?.destroy();
+    });
+  }
+  if (startChrome)
+    defer(startChrome({ loadingScreen, styleManager, dataManager, signal }));
+  // Idle render governor: flips the scene into requestRenderMode whenever
+  // nothing animates per frame. Installed AFTER every module above has had
+  // its chance to register pre-install holds. (perf wave 2)
+  installRenderGovernor(viewer);
+  // Cesium keeps a turned-off layer's draw commands (and so all its entities)
+  // alive in reused per-pass arrays; trim them after each disable.
+  defer(
+    installLayerReleaseTrim({
+      scene: viewer.scene,
+      dataManager,
+      requestRender: governorRequestRender,
+    }),
+  );
+
+  // Install the explicit scope mask used by the DISPLAY controls.
+  installScopeMask(viewer);
+  defer(() => destroyScopeMask());
+
+  // The follow camera recomputes the tracked target's dead-reckon position
+  // every frame — tracking anything is a per-frame animation. (perf wave 2)
+  const removeTrackingListener = viewer.trackedEntityChanged.addEventListener(
+    () => {
+      if (viewer.trackedEntity) holdContinuousRender('tracked-entity');
+      else releaseContinuousRender('tracked-entity');
+    },
+  );
+
+  // Hidden-state suspension (perf wave 2): when the window/tab is hidden,
+  // stop the default render loop outright — a hidden canvas repaints for
+  // nobody, and browser rAF throttling still lets throttled frames burn
+  // 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 = () => {
+    // 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) {
+      data.presentation.flushVisible();
+      governorRequestRender('visibility-restore');
+    }
+  };
+  document.addEventListener('visibilitychange', syncVisibilitySuspension);
+  defer(() =>
+    document.removeEventListener('visibilitychange', syncVisibilitySuspension),
+  );
+  defer(() => {
+    removeTrackingListener();
+    releaseContinuousRender('tracked-entity');
+  });
+  // Apply the CURRENT state too — bootstrap can complete while the tab is
+  // already hidden, and waiting for the next transition would leave the
+  // loop burning behind a hidden tab. (perf wave 2 fix)
+  syncVisibilitySuspension();
+
+  window.__godsEyeView = {
+    viewer,
+    styleManager,
+    tileset,
+    dataManager,
+    sceneDirector,
+    mapStackController,
+    annotations,
+    weatherEffects,
+    cockpitCloudEffects,
+    getRenderGovernorDiagnostics,
+    surfaceServices: operations.surface,
+    requestRender: governorRequestRender,
+  };
+  const debug = window.__godsEyeView;
+  defer(() => {
+    if (window.__godsEyeView === debug) delete window.__godsEyeView;
+  });
+  const voiceCommands = initGevVoiceCommands({
+    ...voice,
+    floorServices: operations.surface.groundFloor,
+    annotationResolver: operations.annotationResolver,
+    searchNavigation: operations.searchAndFlyTo,
+    signal,
+    placeSearch,
+    viewer,
+    styleManager,
+    dataManager,
+    sceneDirector,
+    annotations,
+  });
+  defer(() => {
+    voiceCommands.stop({ removeUi: true });
+    if (window.__gevVoiceCommands === voiceCommands)
+      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/app/viewer.js

@@ -1,10 +1,111 @@
 import * as Cesium from 'cesium';
+import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js';
+import { StarrySky } from '../sky/starrySky.js';
 
-/** Create the standard globe viewer in caller-owned, visible containers. */
-export function createApplicationViewer({ container, creditContainer }) {
-  if (!container || !creditContainer)
-    throw new TypeError('Viewer and credit containers are required');
-  const viewer = new Cesium.Viewer(container, {
+const PINCH_ZOOM_MULTIPLIER = 8;
+const MAX_PINCH_PIXEL_DELTA = 120;
+
+function boundedPinchDelta(delta) {
+  if (!Number.isFinite(delta) || delta === 0) return delta;
+  return (
+    Math.sign(delta) *
+    Math.min(Math.abs(delta) * PINCH_ZOOM_MULTIPLIER, MAX_PINCH_PIXEL_DELTA)
+  );
+}
+
+/**
+ * Add browser trackpad pinch to Cesium's zoom inputs and return its disposer.
+ * Browsers expose this gesture as a small pixel-mode Ctrl+wheel event.
+ */
+export function installTrackpadPinchZoom(
+  viewer,
+  { createWheelEvent = (type, init) => new WheelEvent(type, init) } = {},
+) {
+  const controller = viewer?.scene?.screenSpaceCameraController;
+  const container = viewer?.container;
+  const canvas = viewer?.canvas;
+  if (!controller || !container || !canvas)
+    throw new TypeError('A complete Cesium viewer is required');
+
+  const originalZoomEventTypes = controller.zoomEventTypes;
+  const zoomEventTypes = Array.isArray(originalZoomEventTypes)
+    ? originalZoomEventTypes
+    : originalZoomEventTypes === undefined
+      ? []
+      : [originalZoomEventTypes];
+  const alreadyHandlesControlWheel = zoomEventTypes.some(
+    (binding) =>
+      binding?.eventType === Cesium.CameraEventType.WHEEL &&
+      binding?.modifier === Cesium.KeyboardEventModifier.CTRL,
+  );
+  const configuredZoomEventTypes = alreadyHandlesControlWheel
+    ? originalZoomEventTypes
+    : [
+        ...zoomEventTypes,
+        {
+          eventType: Cesium.CameraEventType.WHEEL,
+          modifier: Cesium.KeyboardEventModifier.CTRL,
+        },
+      ];
+  if (!alreadyHandlesControlWheel)
+    controller.zoomEventTypes = configuredZoomEventTypes;
+
+  const relayedEvents = new WeakSet();
+  const relayPinch = (event) => {
+    if (
+      !event.ctrlKey ||
+      relayedEvents.has(event) ||
+      event.deltaMode !== 0 ||
+      !Number.isFinite(event.deltaY) ||
+      event.deltaY === 0
+    )
+      return;
+    let relayed;
+    try {
+      relayed = createWheelEvent('wheel', {
+        deltaX: event.deltaX,
+        deltaY: boundedPinchDelta(event.deltaY),
+        deltaZ: event.deltaZ,
+        deltaMode: event.deltaMode,
+        screenX: event.screenX,
+        screenY: event.screenY,
+        clientX: event.clientX,
+        clientY: event.clientY,
+        ctrlKey: true,
+        bubbles: true,
+        cancelable: true,
+        view: globalThis.window,
+      });
+    } catch {
+      // The registered Ctrl+wheel binding can still consume the original.
+      return;
+    }
+    relayedEvents.add(relayed);
+    event.preventDefault();
+    event.stopPropagation();
+    canvas.dispatchEvent(relayed);
+  };
+  container.addEventListener('wheel', relayPinch, {
+    capture: true,
+    passive: false,
+  });
+
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    container.removeEventListener('wheel', relayPinch, true);
+    if (
+      !alreadyHandlesControlWheel &&
+      controller.zoomEventTypes === configuredZoomEventTypes
+    )
+      controller.zoomEventTypes = originalZoomEventTypes;
+  };
+}
+
+/** Cesium.Viewer options of the standard globe viewer. */
+export function applicationViewerOptions(creditContainer) {
+  return {
     timeline: false,
     animation: false,
     baseLayerPicker: false,
@@ -17,12 +118,34 @@ export function createApplicationViewer({ container, creditContainer }) {
     selectionIndicator: false,
     infoBox: false,
     baseLayer: false,
+    // Replaces the blocky Tycho-2 default. An option, not `skyBox: false`,
+    // which would also stop CesiumWidget from creating the Sun and Moon.
+    skyBox: new StarrySky(),
     creditContainer,
     msaaSamples: 4,
     contextOptions: { webgl: { preserveDrawingBuffer: true } },
-  });
+  };
+}
+
+/** Create the standard globe viewer in caller-owned, visible containers. */
+export function createApplicationViewer({ container, creditContainer }) {
+  if (!container || !creditContainer)
+    throw new TypeError('Viewer and credit containers are required');
+  const viewer = new Cesium.Viewer(
+    container,
+    applicationViewerOptions(creditContainer),
+  );
   try {
     viewer.targetFrameRate = 60;
+    // A phone pinch spans fewer screen pixels than desktop zoom gestures.
+    // Keep Cesium's distance-aware zoom and collision limits, with less travel
+    // required on touch-first screens. Mouse/trackpad sensitivity stays native.
+    if (globalThis.matchMedia?.('(pointer: coarse)').matches)
+      viewer.scene.screenSpaceCameraController.zoomFactor *= 3;
+    // Before any tile builds a draw command: Cesium's per-vertex model
+    // atmosphere fails to LINK on Apple's Metal backend and kills the
+    // render loop. See app/atmosphereCompat.js.
+    applyModelAtmosphereWorkaround(viewer.scene);
     viewer.scene.globe.show = false;
     viewer.scene.skyAtmosphere.show = true;
     viewer.scene.skyAtmosphere.atmosphereLightIntensity = 18;

src/bloom.js

@@ -43,7 +43,11 @@ export function clampBloomIntensity(value) {
  * @returns {number} equivalent v2 intensity
  */
 export function legacyBloomToV2(value) {
-  const legacy = clamp(Math.round(Number(value) || 0), 0, LEGACY_BLOOM_INTENSITY_MAX);
+  const legacy = clamp(
+    Math.round(Number(value) || 0),
+    0,
+    LEGACY_BLOOM_INTENSITY_MAX,
+  );
   return clampBloomIntensity((LEGACY_BLOOM_INTENSITY_MAX - legacy) * 2);
 }
 
@@ -59,7 +63,10 @@ export function decodeBloomIntensity(value, version = 1) {
   if (!Number.isFinite(num)) return BLOOM_INTENSITY_DEFAULT;
 
   const normalizedVersion = Number(version);
-  if (Number.isFinite(normalizedVersion) && normalizedVersion >= BLOOM_SCALE_VERSION) {
+  if (
+    Number.isFinite(normalizedVersion) &&
+    normalizedVersion >= BLOOM_SCALE_VERSION
+  ) {
     return clampBloomIntensity(num);
   }
 

src/browserModuleBoundary.test.mjs

@@ -22,7 +22,7 @@ test('no browser-built module imports a Node core module', () => {
   // import survives the build and turns into a runtime failure the moment the
   // guard around it is wrong. src/data/naturalEarthRegions.js and
   // src/data/neighborhoodPolygons.js both carried one to read their bundled
-  // JSON packs under node:test; an import attribute serves both runtimes.
+  // JSON packs under node:test; src/data/bundledJson.js now serves both runtimes.
   const offenders = [];
   for (const file of browserModules()) {
     const source = readFileSync(file, 'utf8');

src/camera.js

@@ -1,51 +1,5 @@
 import * as Cesium from 'cesium';
 
-/**
- * Camera presets for notable locations.
- * Phase 1 default: fly to Austin, TX on load.
- */
-export const CAMERA_PRESETS = {
-  austin: {
-    destination: Cesium.Cartesian3.fromDegrees(-97.7431, 30.2672, 800),
-    orientation: {
-      heading: Cesium.Math.toRadians(0),
-      pitch: Cesium.Math.toRadians(-35),
-      roll: 0.0,
-    },
-  },
-  sf: {
-    destination: Cesium.Cartesian3.fromDegrees(-122.4194, 37.7749, 1000),
-    orientation: {
-      heading: Cesium.Math.toRadians(30),
-      pitch: Cesium.Math.toRadians(-30),
-      roll: 0.0,
-    },
-  },
-  nyc: {
-    destination: Cesium.Cartesian3.fromDegrees(-73.9857, 40.7484, 1200),
-    orientation: {
-      heading: Cesium.Math.toRadians(-20),
-      pitch: Cesium.Math.toRadians(-30),
-      roll: 0.0,
-    },
-  },
-};
-
-/**
- * Fly the camera to a preset location with a smooth animation.
- */
-export function flyToPreset(viewer, presetName, duration = 3.0) {
-  const preset = CAMERA_PRESETS[presetName];
-  if (!preset) return;
-
-  viewer.camera.flyTo({
-    destination: preset.destination,
-    orientation: preset.orientation,
-    duration,
-    easingFunction: Cesium.EasingFunction.CUBIC_IN_OUT,
-  });
-}
-
 /**
  * Set camera to Austin on load with a cinematic fly-in.
  * @returns {Function} Cancels the pending or active startup flight.

src/cameraGroundGuard.js

@@ -0,0 +1,198 @@
+/**
+ * Camera ground guard: never leave an arrival buried in, or pressed against,
+ * the rendered surface.
+ *
+ * Arrival framing is computed before the destination's tiles exist, so it has
+ * to predict the ground height. `globe.getHeight()` answers nothing while the
+ * globe is hidden under photoreal tiles, curated `groundElevation` presets
+ * cover only a few cities, and the elevation service resolves asynchronously.
+ * A missing prediction used to fall back to sea level, which buried the eye by
+ * roughly the local elevation (Denver ~1,600 m; Austin ~170 m).
+ *
+ * After the flight lands and tiles have streamed in, this module measures the
+ * rendered surface under the framed target and under the camera itself, and
+ * lifts the eye if it sits below a usable clearance. Heading and pitch are
+ * held, so the correction reads as the shot settling.
+ */
+import * as Cesium from 'cesium';
+import { ownCameraArrival } from './data/cameraArrival.js';
+
+/** Minimum eye height above the rendered surface for a usable view. */
+export const MIN_EYE_CLEARANCE_M = 120;
+/** Retries while tiles stream in; sampling fails until the mesh exists. */
+const GUARD_ATTEMPTS = 8;
+const GUARD_INTERVAL_MS = 600;
+/** Ignore sub-metre noise rather than nudging the camera forever. */
+const GUARD_EPSILON_M = 2;
+
+const probeScratch = new Cesium.Cartographic();
+
+/**
+ * Highest rendered surface across a few cells, with how many cells answered.
+ * A cell whose tiles are not streamed yet contributes nothing.
+ * @param {Cesium.Scene} scene Live scene.
+ * @param {Array<{lat: number, lon: number}>} cells Cells to probe.
+ * @returns {{heightM: number, sampled: number}} Reading.
+ */
+function sampleSurfaceM(scene, cells) {
+  let heightM = Number.NaN;
+  let sampled = 0;
+  if (typeof scene?.sampleHeight !== 'function') return { heightM, sampled };
+  for (const cell of cells) {
+    try {
+      const height = scene.sampleHeight(
+        Cesium.Cartographic.fromDegrees(cell.lon, cell.lat, 0, probeScratch),
+      );
+      if (!Number.isFinite(height)) continue;
+      sampled += 1;
+      heightM = Number.isFinite(heightM) ? Math.max(heightM, height) : height;
+    } catch {
+      /* tiles not ready for this cell */
+    }
+  }
+  return { heightM, sampled };
+}
+
+/**
+ * How far the camera must rise to clear the ground, given a measured surface.
+ * Pure so the policy is testable without a scene.
+ * @param {number} cameraHeightM Eye height above the ellipsoid.
+ * @param {number} groundHeightM Measured surface height above the ellipsoid.
+ * @param {number} [clearanceM] Desired eye height above that surface.
+ * @returns {number} Metres to lift; 0 when the view is already clear.
+ */
+export function groundClearanceDeficitM(
+  cameraHeightM,
+  groundHeightM,
+  clearanceM = MIN_EYE_CLEARANCE_M,
+) {
+  if (!Number.isFinite(cameraHeightM) || !Number.isFinite(groundHeightM))
+    return 0;
+  const deficit = groundHeightM + clearanceM - cameraHeightM;
+  return deficit > GUARD_EPSILON_M ? deficit : 0;
+}
+
+/**
+ * Watch an arrival and lift the camera once the real surface can be measured.
+ *
+ * Stops quietly on a clear view, exhausted attempts, the user taking the
+ * controls (pointer or wheel on the canvas), or `isStale()` reporting that a
+ * newer arrival owns the camera.
+ * @param {Cesium.Viewer} viewer Live viewer.
+ * @param {{lat: number, lon: number}} at Destination being framed.
+ * @param {{clearanceM?: number, attempts?: number, intervalMs?: number,
+ *   isStale?: () => boolean, onLift?: (liftM: number) => void}} [options]
+ * @returns {() => void} Cancel function.
+ */
+export function guardCameraAboveGround(viewer, at, options = {}) {
+  const {
+    clearanceM = MIN_EYE_CLEARANCE_M,
+    attempts = GUARD_ATTEMPTS,
+    intervalMs = GUARD_INTERVAL_MS,
+    isStale = () => false,
+    onLift = null,
+  } = options;
+  if (!viewer?.scene || !Number.isFinite(at?.lat) || !Number.isFinite(at?.lon))
+    return () => {};
+
+  let timer = null;
+  let done = false;
+  const canvas = viewer.scene.canvas;
+  const documentRef = canvas?.ownerDocument;
+  const removers = [];
+  let release = () => {};
+  const stop = () => {
+    if (done) return;
+    done = true;
+    clearTimeout(timer);
+    for (const type of ['pointerdown', 'wheel'])
+      canvas?.removeEventListener?.(type, stop);
+    documentRef?.removeEventListener?.('keydown', stop, true);
+    for (const remove of removers) remove();
+    release();
+  };
+  release = ownCameraArrival(viewer, stop);
+  // Direct camera API callers (including duration-zero flights) must yield
+  // before moving the eye. Restore the exact method ownership on completion.
+  for (const name of [
+    'flyTo',
+    'flyToBoundingSphere',
+    'setView',
+    'lookAt',
+    'cancelFlight',
+  ]) {
+    const camera = viewer.camera;
+    const original = camera[name];
+    if (typeof original !== 'function') continue;
+    const descriptor = Object.getOwnPropertyDescriptor(camera, name);
+    const wrapped = function (...args) {
+      stop();
+      return original.apply(this, args);
+    };
+    camera[name] = wrapped;
+    removers.push(() => {
+      if (camera[name] !== wrapped) return;
+      if (descriptor) Object.defineProperty(camera, name, descriptor);
+      else delete camera[name];
+    });
+  }
+  const removeTracking = viewer.trackedEntityChanged?.addEventListener(stop);
+  if (removeTracking) removers.push(removeTracking);
+  documentRef?.addEventListener?.('keydown', stop, true);
+  // A manual gesture ends the guard, as it interrupts camera motion elsewhere.
+  for (const type of ['pointerdown', 'wheel'])
+    canvas?.addEventListener?.(type, stop, { once: true, passive: true });
+
+  let remaining = attempts;
+  const attempt = () => {
+    if (done) return;
+    if (isStale() || viewer.isDestroyed?.()) return stop();
+    remaining -= 1;
+    const camera = viewer.camera;
+    const carto = camera.positionCartographic;
+    // The eye must clear both the framed target and the ground beneath it.
+    const below = {
+      lat: Cesium.Math.toDegrees(carto.latitude),
+      lon: Cesium.Math.toDegrees(carto.longitude),
+    };
+    const { heightM, sampled } = sampleSurfaceM(viewer.scene, [
+      { lat: at.lat, lon: at.lon },
+      below,
+    ]);
+    if (sampled > 0 && Number.isFinite(heightM)) {
+      const deficit = groundClearanceDeficitM(
+        carto.height,
+        heightM,
+        clearanceM,
+      );
+      if (deficit > 0) {
+        stop();
+        camera.flyTo({
+          destination: Cesium.Cartesian3.fromRadians(
+            carto.longitude,
+            carto.latitude,
+            carto.height + deficit,
+          ),
+          orientation: {
+            heading: camera.heading,
+            pitch: camera.pitch,
+            roll: camera.roll,
+          },
+          duration: 0.9,
+          easingFunction: Cesium.EasingFunction.CUBIC_IN_OUT,
+        });
+        try {
+          onLift?.(deficit);
+        } catch {
+          /* observer only */
+        }
+      }
+      // Both samples answered: the surface is measured, nothing left to wait for.
+      if (sampled === 2 || deficit > 0) return stop();
+    }
+    if (remaining <= 0) return stop();
+    timer = setTimeout(attempt, intervalMs);
+  };
+  timer = setTimeout(attempt, intervalMs);
+  return stop;
+}

src/cameraGroundGuard.test.mjs

@@ -0,0 +1,171 @@
+// Camera ground-guard policy tests: pure arithmetic plus a fake scene, no network.
+//
+// Arrival framing is computed before the destination's tiles exist, so it
+// works from a predicted ground height. The guard measures the real surface
+// after arrival and lifts the eye; these tests pin when it acts.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import {
+  MIN_EYE_CLEARANCE_M,
+  groundClearanceDeficitM,
+  guardCameraAboveGround,
+} from './cameraGroundGuard.js';
+
+test('a buried camera is lifted clear of the surface', () => {
+  // Framed near sea level, arriving over ground at ~1,609 m (Denver).
+  const lift = groundClearanceDeficitM(140, 1609);
+  assert.equal(lift, 1609 + MIN_EYE_CLEARANCE_M - 140);
+});
+
+test('a camera resting on the surface is lifted to a usable height', () => {
+  // Camp Mabry field report: eye 1 m above the mesh at 171 m.
+  assert.equal(groundClearanceDeficitM(172, 171), MIN_EYE_CLEARANCE_M - 1);
+});
+
+test('a well-framed arrival is left alone', () => {
+  assert.equal(groundClearanceDeficitM(1755, 1609), 0);
+  assert.equal(groundClearanceDeficitM(2960, 1609), 0);
+});
+
+test('sub-metre noise never triggers a nudge', () => {
+  assert.equal(groundClearanceDeficitM(1609 + MIN_EYE_CLEARANCE_M, 1609), 0);
+  assert.equal(
+    groundClearanceDeficitM(1609 + MIN_EYE_CLEARANCE_M - 1, 1609),
+    0,
+  );
+});
+
+test('an unmeasurable surface is never acted on', () => {
+  assert.equal(groundClearanceDeficitM(1000, Number.NaN), 0);
+  assert.equal(groundClearanceDeficitM(Number.NaN, 1609), 0);
+  assert.equal(groundClearanceDeficitM(1000, undefined), 0);
+});
+
+test('the clearance frames a subject without turning into an overflight', () => {
+  assert.ok(MIN_EYE_CLEARANCE_M >= 60);
+  assert.ok(MIN_EYE_CLEARANCE_M <= 250);
+});
+
+function fakeViewer({ cameraHeightM, surfaceM }) {
+  const flights = [];
+  const position = Cesium.Cartographic.fromDegrees(-97.7603, 30.3141, cameraHeightM);
+  return {
+    flights,
+    scene: {
+      canvas: null,
+      sampleHeight: (carto) =>
+        typeof surfaceM === 'function' ? surfaceM(carto) : surfaceM,
+    },
+    camera: {
+      positionCartographic: position,
+      heading: 0.5,
+      pitch: -0.55,
+      roll: 0,
+      flyTo: (options) => flights.push(options),
+    },
+  };
+}
+
+test('the guard lifts a buried arrival once the surface answers', async () => {
+  const viewer = fakeViewer({ cameraHeightM: 172, surfaceM: 171 });
+  const lifts = [];
+  guardCameraAboveGround(
+    viewer,
+    { lat: 30.3125, lon: -97.765 },
+    { intervalMs: 1, onLift: (m) => lifts.push(m) },
+  );
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  assert.equal(viewer.flights.length, 1);
+  const lifted = Cesium.Cartographic.fromCartesian(
+    viewer.flights[0].destination,
+  );
+  assert.ok(Math.abs(lifted.height - (171 + MIN_EYE_CLEARANCE_M)) < 0.5);
+  assert.equal(viewer.flights[0].orientation.heading, 0.5);
+  assert.equal(lifts.length, 1);
+});
+
+test('the guard waits for streaming tiles and yields to a newer arrival', async () => {
+  let answer = Number.NaN;
+  let stale = false;
+  const viewer = fakeViewer({ cameraHeightM: 172, surfaceM: () => answer });
+  guardCameraAboveGround(
+    viewer,
+    { lat: 30.3125, lon: -97.765 },
+    { intervalMs: 2, attempts: 20, isStale: () => stale },
+  );
+  await new Promise((resolve) => setTimeout(resolve, 12));
+  assert.equal(viewer.flights.length, 0, 'no guess while tiles stream in');
+  stale = true;
+  answer = 171;
+  await new Promise((resolve) => setTimeout(resolve, 12));
+  assert.equal(viewer.flights.length, 0, 'a newer arrival owns the camera');
+});
+
+test('the guard leaves a clear view untouched', async () => {
+  const viewer = fakeViewer({ cameraHeightM: 400, surfaceM: 171 });
+  guardCameraAboveGround(viewer, { lat: 30.3125, lon: -97.765 }, { intervalMs: 1 });
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  assert.equal(viewer.flights.length, 0);
+});
+
+// Handoffs act before the delayed probe, even when the next owner stays low.
+import { NavigationController } from './ui/navigationController.js';
+import { SceneDirector } from './scenes/director.js';
+import { LayerLifecycle } from './data/lifecycle.js';
+
+function handoffFixture(t) {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const viewer = fakeViewer({ cameraHeightM: 172, surfaceM: 171 });
+  viewer.scene.canvas = new EventTarget();
+  viewer.scene.canvas.ownerDocument = new EventTarget();
+  viewer.trackedEntityChanged = new Cesium.Event();
+  viewer.camera.cancelFlight = () => {};
+  viewer.camera.lookAtTransform = () => {};
+  viewer.camera.flyToBoundingSphere = () => {};
+  viewer.camera.setView = () => {};
+  const originalFly = viewer.camera.flyTo;
+  const navigation = new NavigationController({
+    viewer,
+    tracking: Object.fromEntries(['flightsLayer', 'militaryFlightsLayer',
+      'satellitesLayer', 'aisLiveVesselsLayer', 'militaryAwarenessLayer',
+      'rocketLaunchesLayer'].map((key) => [key, {}])),
+    cancelOrientation() {}, clearLocation() {}, cancelShareSelection() {},
+    getDataManager() {}, interruptCameraMotion() {}, stopOrbit() {},
+    isCockpitActive: () => false, showToast() {},
+  });
+  guardCameraAboveGround(viewer, { lat: 30.3, lon: -97.7 });
+  return { viewer, navigation, originalFly };
+}
+
+for (const handoff of ['Director', 'tracking', 'follow', 'keyboard', 'UI',
+  'flyTo', 'flyToBoundingSphere', 'setView', 'layer-disable', 'layer-destroy', 'app-stop']) {
+  test(`arrival guard relinquishes and removes hooks on ${handoff}`, async (t) => {
+    const { viewer, navigation, originalFly } = handoffFixture(t);
+    if (handoff === 'Director') {
+      SceneDirector.prototype._claimCameraOwnership.call({
+        viewer, styleManager: { runImmediateNavigation: (noun, fn) =>
+          navigation._runExplicitNavigation(noun, fn) },
+      });
+    } else if (handoff === 'tracking') {
+      viewer.trackedEntityChanged.raiseEvent({ id: 'contact' });
+    } else if (handoff === 'follow' || handoff === 'UI') {
+      navigation._stampNavigation({ cancelPendingSelection: false });
+    } else if (handoff === 'keyboard') {
+      viewer.scene.canvas.ownerDocument.dispatchEvent(new Event('keydown'));
+    } else if (handoff === 'app-stop') navigation.stop();
+    else if (handoff.startsWith('layer-')) {
+      const lifecycle = new LayerLifecycle(viewer);
+      lifecycle.register({ id: 'test', init() {}, enable() {}, disable() {}, destroy() {} });
+      await lifecycle.setEnabled('test', true);
+      if (handoff === 'layer-disable') await lifecycle.setEnabled('test', false);
+      else await lifecycle.destroyLayer('test');
+    } else viewer.camera[handoff]({});
+    const priorFlights = viewer.flights.length;
+    t.mock.timers.tick(10000);
+    assert.equal(viewer.flights.length, priorFlights, 'the old probe cannot fly');
+    assert.equal(viewer.camera.flyTo, originalFly, 'direct-call hook is removed');
+    assert.equal(viewer.trackedEntityChanged.numberOfListeners, 0);
+    navigation.destroy();
+  });
+}

src/cameraHandoff.test.mjs

@@ -1,3 +1,8 @@
+import { LayerBindings } from './ui/layerBindings.js';
+import { readShellSource, shellMethod } from './testSupport/readShellSource.mjs';
+import { readLayerSource } from './testSupport/readLayerSource.mjs';
+import { enter as cockpitEnter, navigateContext } from './ui/cockpitTrackingController.js';
+import { CockpitViewController } from './ui/cockpitController.js';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -5,14 +10,19 @@ import test from 'node:test';
 import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const ui = fs.readFileSync(path.join(ROOT, 'src', 'ui.js'), 'utf8');
-const firms = fs.readFileSync(path.join(ROOT, 'src', 'data', 'firmsHeatmap.js'), 'utf8');
-const vessels = fs.readFileSync(path.join(ROOT, 'src', 'data', 'aisLiveVessels.js'), 'utf8');
+const ui = readShellSource();
+const firms = readLayerSource(path.join(ROOT, 'src', 'data', 'firmsHeatmap.js'));
+const vessels = readLayerSource(path.join(ROOT, 'src', 'data', 'aisLiveVessels.js'));
 const voice = fs.readFileSync(path.join(ROOT, 'src', 'voice', 'gevActions.js'), 'utf8');
 const cameraVerbs = fs.readFileSync(path.join(ROOT, 'src', 'cameraVerbs.js'), 'utf8');
 const cockpitTracking = fs.readFileSync(path.join(ROOT, 'src', 'cockpitTracking.js'), 'utf8');
 
 function body(source, pattern, label) {
+  const name = pattern.source.match(/^(\w+)/)?.[1];
+  if (source === ui && typeof shellMethod(name) === 'function') {
+    const method = shellMethod(name).toString();
+    return method.slice(method.indexOf(') {') + 3, -1);
+  }
   const match = source.match(pattern);
   assert.ok(match, `${label} is missing`);
   return match[1];
@@ -21,7 +31,8 @@ function body(source, pattern, label) {
 function ordered(source, needles, label) {
   let previous = -1;
   for (const needle of needles) {
-    const index = source.indexOf(needle);
+    const match = needle instanceof RegExp ? needle.exec(source.slice(previous + 1)) : null;
+    const index = needle instanceof RegExp ? (match ? previous + 1 + match.index : -1) : source.indexOf(needle, previous + 1);
     assert.ok(index >= 0, `${label}: missing ${needle}`);
     assert.ok(index > previous, `${label}: ${needle} is out of order`);
     previous = index;
@@ -29,11 +40,7 @@ function ordered(source, needles, label) {
 }
 
 test('Cockpit takeover invalidates deferred work before camera cancellation', () => {
-  const enter = body(
-    ui,
-    /enter\(\) \{([\s\S]*?)\n  \}\n\n  exit\(/,
-    'Cockpit enter',
-  );
+  const enter = cockpitEnter.toString();
   ordered(enter, [
     'if (!info || !entity?.position) return false;',
     'this.onCameraTakeover?.();',
@@ -42,7 +49,7 @@ test('Cockpit takeover invalidates deferred work before camera cancellation', ()
   ], 'Cockpit takeover');
   assert.match(
     ui,
-    /onCameraTakeover: \(\) => this\._stampNavigation\(\{ cancelPendingSelection: false \}\),/,
+    /onCameraTakeover: \(\) =>\s*this\._stampNavigation\(\{\s*cancelPendingSelection: false,?\s*\}\),/,
     'Cockpit retires stale camera work without clearing the aircraft selection it adopts',
   );
 });
@@ -53,14 +60,14 @@ test('one explicit tracking selection clears sibling IDs before publishing its d
     /_persistAwarenessSelection\(event, cleared = false\) \{([\s\S]*?)\n  \}/,
     'tracking persistence',
   );
-  assert.match(persist, /adoptLayerParams\?\.\(layerId,/);
+  assert.match(persist, /adoptLayerParams\?\.\(\s*layerId,/);
   assert.match(persist, /\['flights', 'selectedFlightsTrackingId'\]/);
   assert.match(persist, /\['military', 'selectedMilitaryTrackingId'\]/);
   assert.match(persist, /\['satellites', 'selectedSatTrackingId'\]/);
   assert.match(persist, /if \(otherLayerId === layerId\) continue;/);
   assert.match(
     persist,
-    /for \(const \[otherLayerId, otherKey\][\s\S]*?setLayerParams\(otherLayerId,[\s\S]*?adoptLayerParams\?\.\(layerId,/,
+    /for \(const \[otherLayerId, otherKey\][\s\S]*?setLayerParams\(\s*otherLayerId,[\s\S]*?adoptLayerParams\?\.\(\s*layerId,/,
     'the previous family clears before Flight/Military/Satellite publishes the new durable ID',
   );
 });
@@ -75,9 +82,9 @@ test('navigation clears dormant tracker IDs without aborting unrelated layer res
   assert.match(stamp, /flightsLayer\.cancelPendingTrackingRestore\?\.\(\)/);
   assert.match(stamp, /militaryFlightsLayer\.cancelPendingTrackingRestore\?\.\(\)/);
   assert.match(stamp, /satellitesLayer\.cancelPendingTrackingRestore\?\.\(\)/);
-  assert.match(stamp, /if \(!passivelyClearedShareSelection && !flightsLayer\.getTrackedInfo\?\.\(\)\)[\s\S]*?selectedFlightsTrackingId: null/);
-  assert.match(stamp, /if \(!passivelyClearedShareSelection && !militaryFlightsLayer\.getTrackedInfo\?\.\(\)\)[\s\S]*?selectedMilitaryTrackingId: null/);
-  assert.match(stamp, /if \(!passivelyClearedShareSelection && !satellitesLayer\.getTrackedInfo\?\.\(\)\)[\s\S]*?selectedSatTrackingId: null/);
+  assert.match(stamp, /if \(\s*!passivelyClearedShareSelection\s*&&\s*!flightsLayer\.getTrackedInfo\?\.\(\)\s*\)[\s\S]*?selectedFlightsTrackingId: null/);
+  assert.match(stamp, /if \(\s*!passivelyClearedShareSelection\s*&&\s*!militaryFlightsLayer\.getTrackedInfo\?\.\(\)\s*\)[\s\S]*?selectedMilitaryTrackingId: null/);
+  assert.match(stamp, /if \(\s*!passivelyClearedShareSelection\s*&&\s*!satellitesLayer\.getTrackedInfo\?\.\(\)\s*\)[\s\S]*?selectedSatTrackingId: null/);
 });
 
 test('voice Cockpit entry reaches the camera only through stamping seams', () => {
@@ -98,7 +105,7 @@ test('voice Cockpit entry reaches the camera only through stamping seams', () =>
     'Cockpit entry transaction',
   );
   ordered(transaction, [
-    'if (!selectedLayer.trackById?.(selectedTarget.id, { origin: selectionOrigin })) {',
+    /if \(\s*!selectedLayer\.trackById\?\.\(selectedTarget\.id, \{\s*origin: selectionOrigin,?\s*\}\)\s*\) \{/,
     'if (!entryError) entered = Boolean(cockpitView.enter());',
   ], 'Cockpit entry transaction');
   // No direct camera control: every mutation goes through a layer tracker or
@@ -110,7 +117,7 @@ test('voice Cockpit entry reaches the camera only through stamping seams', () =>
   // Seam 1: any tracker handoff stamps, so the adoption step is covered.
   assert.match(
     ui,
-    /viewer\.trackedEntityChanged\.addEventListener\(\(entity\) => \{\s*if \(entity && !this\._disposed\) this\._stampNavigation\(\{ cancelPendingSelection: false \}\);/,
+    /viewer\.trackedEntityChanged\.addEventListener\(\s*\(entity\) => \{\s*if \(entity && !this\._disposed\)\s*this\._stampNavigation\(\{\s*cancelPendingSelection: false,?\s*\}\);/,
     'tracker handoff must stamp',
   );
   // Seam 2 is pinned by "Cockpit takeover invalidates deferred work" above.
@@ -131,21 +138,18 @@ test('voice Cockpit next/previous shares the manual Context navigation path', ()
   // is what stamps. Divergence here is how a voice-only camera path escapes
   // the arbiter.
   assert.match(
-    ui,
-    /this\._listen\(this\.contextPrevious, 'click', \(\) => this\.navigateContext\(-1, \{ origin: 'user' \}\)\);/,
+    CockpitViewController.toString(),
+    /this\._listen\(this\.contextPrevious, 'click', \(\) =>\s*this\.navigateContext\(-1, \{ origin: 'user' \}\),?\s*\);/,
   );
   assert.match(
-    ui,
-    /this\._listen\(this\.contextNext, 'click', \(\) => this\.navigateContext\(1, \{ origin: 'user' \}\)\);/,
-  );
-  const funnel = body(
-    ui,
-    /navigateContext\(direction, options = \{\}\) \{([\s\S]*?)\n  \}\n\n  \/\*\* Adopt/,
-    'Cockpit Context navigation funnel',
+    CockpitViewController.toString(),
+    /this\._listen\(this\.contextNext, 'click', \(\) =>\s*this\.navigateContext\(1, \{ origin: 'user' \}\),?\s*\);/,
   );
+  const funnel = navigateContext.toString();
+  assert.match(funnel, /const navigationOptions = wasActive\s*\? \{ \.\.\.options, aircraftOnly: true \}\s*: options;/);
   ordered(funnel, [
     "const method = direction < 0 ? 'navigatePrevious' : 'navigateNext';",
-    'const navigationOptions = wasActive ? { ...options, aircraftOnly: true } : options;',
+    'const navigationOptions = wasActive',
     'militaryAwarenessLayer?.[method]?.(navigationOptions)',
     'this._adoptTrackedEntity(performance.now());',
   ], 'Cockpit Context navigation funnel');
@@ -172,7 +176,7 @@ test('accepted navigation releases through PR15-aware ownership before flight',
     'explicit navigation',
   );
   ordered(run, [
-    'cockpitActive: !!this.cockpitView?.active',
+    'cockpitActive: this.isCockpitActive()',
     'stamp: () => this._stampNavigation()',
     'release: () => this._releaseFollowCamera(releaseOptions)',
     'navigate,',
@@ -197,11 +201,11 @@ test('accepted navigation releases through PR15-aware ownership before flight',
 
 test('validated voice camera destinations share the UI navigation authority facade', () => {
   assert.match(ui, /runImmediateNavigation\(noun, navigate, releaseOptions = undefined\) \{\s*return this\._runExplicitNavigation\(noun, navigate, releaseOptions\);/);
-  assert.match(voice, /runManagedVoiceNavigation\(\s*styleManager, 'camera', 'move_camera', navigate, releaseOptions/);
-  assert.match(voice, /runManagedVoiceNavigation\(styleManager, 'route', 'fly_route', navigate/);
-  assert.match(voice, /runManagedVoiceNavigation\(styleManager, 'fire', 'track_entity'/);
-  assert.match(voice, /runManagedVoiceNavigation\(styleManager, family\.kind, 'track_entity'/);
-  assert.match(voice, /runManagedVoiceNavigation\(styleManager, 'frame', 'frame_overhead'/);
+  assert.match(voice, /runManagedVoiceNavigation\(\s*styleManager,\s*'camera',\s*'move_camera',\s*navigate,\s*releaseOptions/);
+  assert.match(voice, /runManagedVoiceNavigation\(\s*styleManager,\s*'route',\s*'fly_route',\s*navigate/);
+  assert.match(voice, /runManagedVoiceNavigation\(\s*styleManager,\s*'fire',\s*'track_entity'/);
+  assert.match(voice, /runManagedVoiceNavigation\(\s*styleManager,\s*family\.kind,\s*'track_entity'/);
+  assert.match(voice, /runManagedVoiceNavigation\(\s*styleManager,\s*'frame',\s*'frame_overhead'/);
   const trackedVoice = voice.slice(
     voice.indexOf('async function trackEntity'),
     voice.indexOf('async function frameOverhead'),
@@ -219,64 +223,64 @@ test('validated voice camera destinations share the UI navigation authority faca
     'move camera',
   );
   ordered(move, [
-    "if (!['orbit', 'pan', 'tilt', 'rotate'].includes(motion))",
+    "if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion))",
     'const start = () => {',
-    "const preserveCameraFlight = motion === 'orbit'",
+    /const preserveCameraFlight =\s*motion === 'orbit'/,
     'runNavigation(start, { preserveCameraFlight })',
   ], 'move validation before handoff');
 
   const route = body(
     cameraVerbs,
-    /export function flyRoute\(annoList, args = \{\}, floorFn = null, runNavigation = null, warmFn = null\) \{([\s\S]*?)\n\}/,
+    /export function flyRoute\(\s*annoList,\s*args = \{\},\s*floorFn = null,\s*runNavigation = null,\s*warmFn = null,?\s*\) \{([\s\S]*?)\n\}/,
     'fly route',
   );
   ordered(route, [
     'if (!routes.length)',
     'const pts = route.path.map',
     'const start = () => {',
-    "return typeof runNavigation === 'function' ? runNavigation(start) : start();",
+    /return typeof runNavigation === 'function'\s*\? runNavigation\(start\)\s*: start\(\);/,
   ], 'route validation before handoff');
   // The corridor warm is injected the same way the floor READ is — the dolly
   // never reaches into the data layer itself, and the voice dispatch is the one
   // place that binds both.
-  assert.match(voice, /\(lat, lon\) => cachedGroundFloor\(lat, lon\),[\s\S]{0,200}?\(cells\) => warmGroundFloor\(cells\),/);
+  assert.match(voice, /\(lat, lon\) => floorServices\.cachedGroundFloor\(lat, lon\),[\s\S]{0,200}?\(cells\) => floorServices\.warmGroundFloor\(cells\),/);
 });
 
 test('deferred search releases only after its final authority check', () => {
-  const handler = body(
-    ui,
-    /this\._locationSearch\.addEventListener\('keydown', async \(e\) => \{([\s\S]*?)\n    \}\);/,
-    'search handler',
-  );
-  ordered(handler, [
-    "this._beginDeferredNavigation('location')",
-    'this._activeLocationSearchGeneration = generation;',
-    'searchAndFlyTo(this.viewer, query',
-    'beforeFly: () => this._reassertNavigationHandoff(generation)',
-    'generation !== this._navigationGeneration',
+  const search = fs.readFileSync(path.join(ROOT, 'src', 'ui', 'locationSearch.js'), 'utf8');
+  ordered(search, [
+    'const authority = this.begin();',
+    'this.onStart?.(authority);',
+    'await this.search(query',
+    'beforeFly: () => current() && this.beforeFly(authority)',
+    'if (!current() || controller.signal.aborted) return;',
     'destination?.cancelled',
     'finally',
-    'this._settleLocationSearchUi(generation)',
-  ], 'deferred search');
-  assert.doesNotMatch(handler.slice(0, handler.indexOf('searchAndFlyTo')), /_releaseFollowCamera/);
+    'this.onSettled?.(authority)',
+  ], 'deferred search component');
+  assert.match(ui, /begin: \(\) => this\._beginDeferredNavigation\('location'\)/);
+  assert.match(ui, /beforeFly: \(generation\) => this\._reassertNavigationHandoff\(generation\)/);
+  assert.match(ui, /isCurrent: \(generation\) =>\s*!this\._disposed && generation === this\._navigationGeneration/);
+  assert.match(ui, /change\.type === 'settled'\)\s*this\._settleLocationSearchUi\(change\.generation, \{\s*keepQuery: state\.status === 'missing' \|\| state\.status === 'failed',?\s*\}\)/);
+  assert.doesNotMatch(search.slice(0, search.indexOf('await this.search')), /_releaseFollowCamera/);
 });
 
 test('a direct globe gesture retires delayed camera and selection restore only', () => {
   assert.match(
     ui,
-    /this\._initialShareGestureHandler = \(\) => \{[\s\S]*?!this\._resolveInitialShareRestore[\s\S]*?stampInitialShareGesture\(\(options\) => this\._stampNavigation\(options\)\);/,
+    /this\._initialShareGestureHandler = \(\) => \{[\s\S]*?!this\._resolveInitialShareRestore[\s\S]*?stampInitialShareGesture\(\(options\) =>\s*this\.navigation\._stampNavigation\(options\),?\s*\);/,
   );
   assert.match(
     ui,
-    /viewer\?\.canvas\?\.addEventListener\('pointerdown', this\._initialShareGestureHandler/,
+    /viewer\?\.canvas\?\.addEventListener\(\s*'pointerdown',\s*this\._initialShareGestureHandler/,
   );
   assert.match(
     ui,
-    /viewer\?\.canvas\?\.addEventListener\('wheel', this\._initialShareGestureHandler/,
+    /viewer\?\.canvas\?\.addEventListener\(\s*'wheel',\s*this\._initialShareGestureHandler/,
   );
   assert.match(
     ui,
-    /removeEventListener\('pointerdown', this\._initialShareGestureHandler\)[\s\S]*?removeEventListener\('wheel', this\._initialShareGestureHandler\)/,
+    /removeEventListener\(\s*'pointerdown',\s*this\._initialShareGestureHandler,?\s*\)[\s\S]*?removeEventListener\(\s*'wheel',\s*this\._initialShareGestureHandler,?\s*\)/,
   );
   const stamp = body(
     ui,
@@ -298,21 +302,26 @@ test('newer navigation, reset, Cockpit, and teardown share one generation', () =
   const dispose = body(ui, /async dispose\(\) \{([\s\S]*?)\n  \}/, 'dispose');
   ordered(dispose, [
     'this._disposed = true;',
-    'this._stampNavigation();',
-    'this._removeWorldRequestFocusListener?.();',
-    'await this._restoreContextSession();',
+    'this._layerBindings.stop();',
+    'this._navigation.destroy();',
+    'await this._contextControls.restoreForDisposal();',
   ], 'dispose invalidation');
+  assert.match(shellMethod('destroy').toString(), /this\._stampNavigation\(\)/);
 });
 
 test('teardown synchronously closes immediate camera entry points', () => {
   const dispose = body(ui, /async dispose\(\) \{([\s\S]*?)\n  \}/, 'dispose');
   ordered(dispose, [
+    'this._disposed = true;',
+    'this._layerBindings.stop();',
+    'await this._contextControls.restoreForDisposal();',
+  ], 'synchronous teardown barrier');
+  ordered(LayerBindings.prototype.stop.toString(), [
     'this._disposed = true;',
     'this._removeCctvRequestFocusListener?.();',
     'this._removeWorldRequestFocusListener?.();',
     'this._navigationOwnerChangedRemover?.();',
-    'await this._restoreContextSession();',
-  ], 'synchronous teardown barrier');
+  ], 'camera bindings close synchronously');
 
   const navigation = body(
     ui,
@@ -337,25 +346,18 @@ test('teardown synchronously closes immediate camera entry points', () => {
 });
 
 test('teardown refuses deferred location work before geocoding begins', () => {
-  const deferred = body(
-    ui,
-    /_beginDeferredNavigation\(noun = 'location', \{ cancelPendingSelection = true \} = \{\}\) \{([\s\S]*?)\n  \}/,
-    'deferred navigation',
-  );
+  const deferred = body(ui, /_beginDeferredNavigation\(noun = 'location', \{ cancelPendingSelection = true \} = \{\}\) \{([\s\S]*?)\n  \}/, 'deferred navigation');
   assert.match(deferred, /disposed: this\._disposed/);
-
-  const handler = body(
-    ui,
-    /this\._locationSearch\.addEventListener\('keydown', async \(e\) => \{([\s\S]*?)\n    \}\);/,
-    'search handler',
-  );
-  ordered(handler, [
-    "const generation = this._beginDeferredNavigation('location');",
-    'if (generation === false)',
-    'this._locationSearch.blur();',
-    'searchAndFlyTo(this.viewer, query',
+  const search = fs.readFileSync(path.join(ROOT, 'src', 'ui', 'locationSearch.js'), 'utf8');
+  ordered(search, [
+    'if (!query || this.destroyed) return;',
+    'const authority = this.begin();',
+    'if (authority === false)',
+    'this.input?.blur();',
+    'this.onStart?.(authority);',
+    'await this.search(query',
   ], 'disposed search refusal');
-  assert.match(handler, /if \(generation === false\) \{[\s\S]*?return;[\s\S]*?\}\s*this\._activeLocationSearchGeneration/);
+  assert.match(search, /if \(authority === false\) \{[\s\S]*?return;[\s\S]*?\}\s*this\.controller/);
 });
 
 test('refused canned destinations commit no location or POI state', () => {
@@ -381,13 +383,13 @@ test('world-focus listener lifecycle is symmetric and idempotent', () => {
 });
 
 test('vessel and fire layers announce valid clicks and never fly cameras', () => {
-  for (const [label, source] of [['vessels', vessels], ['fires', firms]]) {
+  for (const source of [vessels, firms]) {
     assert.match(source, /requestWorldFocus\(\{/);
     assert.doesNotMatch(source, /camera\.flyTo/);
   }
   const vesselClick = body(
     vessels,
-    /handler\.setInputAction\(\(click\) => \{([\s\S]*?)\n  \}, Cesium\.ScreenSpaceEventType\.LEFT_CLICK\);/,
+    /handler\.setInputAction\(\s*\(click\) => \{([\s\S]*?)\n\s*\},\s*Cesium\.ScreenSpaceEventType\.LEFT_CLICK,?\s*\);/,
     'vessel click',
   );
   ordered(vesselClick, [
@@ -397,7 +399,7 @@ test('vessel and fire layers announce valid clicks and never fly cameras', () =>
   ], 'vessel sibling ownership');
   const vesselFocus = body(
     vessels,
-    /function selectAndFocusVessel\(record\) \{([\s\S]*?)\n\}/,
+    /function selectAndFocusVessel\(record\) \{([\s\S]*?)\n  \}/,
     'vessel focus helper',
   );
   assert.match(vesselFocus, /requestWorldFocus\(\{/);

src/cctvFocusPolicy.js

@@ -27,7 +27,7 @@ export function runCctvLayerEnableFocus({
  * @param {Object} [after={}] Ownership immediately after the await.
  * @returns {{ trackedEntity: *, cockpitActive: boolean }} Conservative ownership.
  */
-export function mergeCctvEnableOwnership(before = {}, after = {}) {
+function mergeCctvEnableOwnership(before = {}, after = {}) {
   return {
     trackedEntity: before.trackedEntity || after.trackedEntity || null,
     cockpitActive: !!(before.cockpitActive || after.cockpitActive),

src/cctvFocusPolicy.test.mjs

@@ -1,6 +1,6 @@
+import { readShellSource } from './testSupport/readShellSource.mjs';
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
 import {
   runCctvLayerEnableFocus,
   runCctvLayerEnableTransition,
@@ -73,7 +73,7 @@ test('CCTV enable retains a pre-await tracking snapshot when tracking clears dur
   assert.match(diagnostics[0][0], /before setEnabled await/);
   assert.match(diagnostics[1][0], /after setEnabled await/);
 
-  const uiSource = readFileSync(new URL('./ui.js', import.meta.url), 'utf8');
+  const uiSource = readShellSource();
   assert.match(uiSource, /await runCctvLayerEnableTransition\(\{/);
 });
 
@@ -95,3 +95,25 @@ test('CCTV disable transition does not emit enable-ownership diagnostics', async
   assert.deepEqual(transitions, [false]);
   assert.deepEqual(diagnostics, []);
 });
+
+
+test('a disposed UI cannot activate a camera when enabling finishes late', async () => {
+  let release;
+  let disposed = false;
+  let activations = 0;
+  const pending = runCctvLayerEnableTransition({
+    target: true,
+    setEnabled: () => new Promise((resolve) => { release = resolve; }),
+    readOwnership: () => ({}),
+    shouldFocus: () => !disposed,
+    activate: () => { activations++; return 'camera-a'; },
+    fly: () => assert.fail('disposed UI must not fly'),
+    debug: () => {},
+  });
+  disposed = true;
+  release();
+  await pending;
+  assert.equal(activations, 0);
+  const uiSource = readShellSource();
+  assert.match(uiSource, /shouldFocus: \(\) =>\s*!this\._disposed\s*&&\s*this\._dataManager\.isEnabled\('cctv'\)/);
+});

src/cctvFocusRequest.js

@@ -22,9 +22,11 @@ export function activateCctvCameraFromWorldClick(
 ) {
   if (!cameraId || typeof activate !== 'function') return false;
   if (activate(cameraId) !== CCTV_ACTIVATION_RESULT.ACTIVATED) return false;
-  eventTarget.dispatchEvent(new CustomEvent(CCTV_FOCUS_REQUEST_EVENT, {
-    detail: { cameraId },
-  }));
+  eventTarget.dispatchEvent(
+    new CustomEvent(CCTV_FOCUS_REQUEST_EVENT, {
+      detail: { cameraId },
+    }),
+  );
   return true;
 }
 
@@ -36,8 +38,12 @@ export function activateCctvCameraFromWorldClick(
  * @returns {() => void} Listener disposer.
  */
 export function registerCctvFocusRequestListener(eventTarget, listener) {
-  if (!eventTarget?.addEventListener || !eventTarget?.removeEventListener
-    || typeof listener !== 'function') return () => {};
+  if (
+    !eventTarget?.addEventListener ||
+    !eventTarget?.removeEventListener ||
+    typeof listener !== 'function'
+  )
+    return () => {};
   eventTarget.addEventListener(CCTV_FOCUS_REQUEST_EVENT, listener);
   let disposed = false;
   return () => {
@@ -57,11 +63,16 @@ export function registerCctvFocusRequestListener(eventTarget, listener) {
  */
 export function routeCctvFocusRequest(event, runExplicitFocus, focusCamera) {
   const cameraId = event?.detail?.cameraId;
-  if (typeof cameraId !== 'string' || !cameraId || typeof runExplicitFocus !== 'function') {
+  if (
+    typeof cameraId !== 'string' ||
+    !cameraId ||
+    typeof runExplicitFocus !== 'function'
+  ) {
     return false;
   }
   return runExplicitFocus(
     () => cameraId,
-    (selectedId) => focusCamera(selectedId, CCTV_WORLD_CLICK_FOCUS_DURATION_SEC),
+    (selectedId) =>
+      focusCamera(selectedId, CCTV_WORLD_CLICK_FOCUS_DURATION_SEC),
   );
 }

src/cctvFocusRequest.test.mjs

@@ -1,6 +1,6 @@
+import { readShellSource } from './testSupport/readShellSource.mjs';
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
 import {
   CCTV_WORLD_CLICK_FOCUS_DURATION_SEC,
   CCTV_FOCUS_REQUEST_EVENT,
@@ -57,7 +57,7 @@ test('UI CCTV focus listener registration disposes the exact added callback once
   assert.strictEqual(added[0].callback, listener);
   assert.strictEqual(removed[0].callback, added[0].callback);
 
-  const uiSource = readFileSync(new URL('./ui.js', import.meta.url), 'utf8');
+  const uiSource = readShellSource();
   assert.match(
     uiSource,
     /_removeCctvRequestFocusListener = registerCctvFocusRequestListener\([\s\S]+this\._cctvRequestFocusHandler/,

src/celestialRing.js

@@ -90,16 +90,30 @@ export function getKeyholeGeometry(width, height) {
  * floor through a band derived from the live keyhole radius.
  */
 export function keyholeLabelAlpha(labelX, labelY, width, height) {
-  return keyholeLabelAlphaFromGeometry(labelX, labelY, getKeyholeGeometry(width, height));
+  return keyholeLabelAlphaFromGeometry(
+    labelX,
+    labelY,
+    getKeyholeGeometry(width, height),
+  );
 }
 
 /** Compute keyhole opacity from geometry already cached by a hot render loop. */
 export function keyholeLabelAlphaFromGeometry(labelX, labelY, geometry) {
-  if (!geometry || !(geometry.radius > 0) || !Number.isFinite(labelX) || !Number.isFinite(labelY)) return 0;
+  if (
+    !geometry ||
+    !(geometry.radius > 0) ||
+    !Number.isFinite(labelX) ||
+    !Number.isFinite(labelY)
+  )
+    return 0;
   const feather = geometry.featherPx;
-  const distance = Math.hypot(labelX - geometry.centerX, labelY - geometry.centerY);
+  const distance = Math.hypot(
+    labelX - geometry.centerX,
+    labelY - geometry.centerY,
+  );
   if (distance <= geometry.radius) return 1;
-  if (!(feather > 0) || distance >= geometry.radius + feather) return keyholeOutsideOpacity;
+  if (!(feather > 0) || distance >= geometry.radius + feather)
+    return keyholeOutsideOpacity;
   const progress = clamp((distance - geometry.radius) / feather, 0, 1);
   return 1 - (1 - keyholeOutsideOpacity) * progress;
 }
@@ -131,7 +145,11 @@ export function isCelestialRingStyleSupported(styleName) {
  * @param {number} lastAngle - Previous stable angle in radians.
  * @returns {{angle:number, opacity:number, stable:boolean}}
  */
-export function celestialScreenAngle(rightComponent, upComponent, lastAngle = 0) {
+export function celestialScreenAngle(
+  rightComponent,
+  upComponent,
+  lastAngle = 0,
+) {
   const planeLength = Math.hypot(rightComponent, upComponent);
   if (!Number.isFinite(planeLength) || planeLength < CELESTIAL_PLANE_EPSILON) {
     return {
@@ -170,26 +188,42 @@ export function isFullGlobeInsideKeyhole(geometry, wasVisible = false) {
     keyholeCenterY,
     keyholeRadius,
   } = geometry || {};
-  const values = [earthCenterX, earthCenterY, earthRadius, keyholeCenterX, keyholeCenterY, keyholeRadius];
-  if (!values.every(Number.isFinite) || earthRadius <= 0 || keyholeRadius <= 0) return false;
-  const offset = Math.hypot(earthCenterX - keyholeCenterX, earthCenterY - keyholeCenterY);
+  const values = [
+    earthCenterX,
+    earthCenterY,
+    earthRadius,
+    keyholeCenterX,
+    keyholeCenterY,
+    keyholeRadius,
+  ];
+  if (!values.every(Number.isFinite) || earthRadius <= 0 || keyholeRadius <= 0)
+    return false;
+  const offset = Math.hypot(
+    earthCenterX - keyholeCenterX,
+    earthCenterY - keyholeCenterY,
+  );
   const clearance = keyholeRadius - (offset + earthRadius);
-  return clearance >= (wasVisible ? GLOBE_EXIT_CLEARANCE_PX : GLOBE_ENTER_CLEARANCE_PX);
+  return (
+    clearance >=
+    (wasVisible ? GLOBE_EXIT_CLEARANCE_PX : GLOBE_ENTER_CLEARANCE_PX)
+  );
 }
 
 /** Return the Earth-disc radius in CSS pixels for a perspective camera. */
 export function earthDiscScreenRadius(cameraDistance, viewportHeight, fovy) {
   const earthRadiusM = Cesium.Ellipsoid.WGS84.maximumRadius;
   if (
-    !Number.isFinite(cameraDistance)
-    || cameraDistance <= earthRadiusM
-    || !(viewportHeight > 0)
-    || !Number.isFinite(fovy)
-    || fovy <= 0
-    || fovy >= Math.PI
-  ) return null;
+    !Number.isFinite(cameraDistance) ||
+    cameraDistance <= earthRadiusM ||
+    !(viewportHeight > 0) ||
+    !Number.isFinite(fovy) ||
+    fovy <= 0 ||
+    fovy >= Math.PI
+  )
+    return null;
   const angularRadius = Math.asin(clamp(earthRadiusM / cameraDistance, 0, 1));
-  const radius = (viewportHeight * 0.5) * Math.tan(angularRadius) / Math.tan(fovy * 0.5);
+  const radius =
+    (viewportHeight * 0.5 * Math.tan(angularRadius)) / Math.tan(fovy * 0.5);
   return Number.isFinite(radius) && radius > 0 ? radius : null;
 }
 
@@ -216,7 +250,11 @@ export function projectEarthDiscToViewport(
   if (!camera || !scene || !(width > 0) || !(height > 0)) return null;
 
   const distance = Cesium.Cartesian3.magnitude(camera.positionWC);
-  if (!Number.isFinite(distance) || distance <= Cesium.Ellipsoid.WGS84.maximumRadius) return null;
+  if (
+    !Number.isFinite(distance) ||
+    distance <= Cesium.Ellipsoid.WGS84.maximumRadius
+  )
+    return null;
 
   const toCenter = Cesium.Cartesian3.negate(
     camera.positionWC,
@@ -229,9 +267,14 @@ export function projectEarthDiscToViewport(
     Cesium.Cartesian3.ZERO,
     scratchCenter,
   );
-  if (!center || !Number.isFinite(center.x) || !Number.isFinite(center.y)) return null;
+  if (!center || !Number.isFinite(center.x) || !Number.isFinite(center.y))
+    return null;
 
-  const earthRadius = earthDiscScreenRadius(distance, height, camera.frustum?.fovy);
+  const earthRadius = earthDiscScreenRadius(
+    distance,
+    height,
+    camera.frustum?.fovy,
+  );
   if (!earthRadius) return null;
 
   const keyhole = getKeyholeGeometry(width, height);
@@ -286,7 +329,12 @@ function drawSunRays(ctx, cx, cy, radius, innerRadius, angle) {
   glow.addColorStop(0.58, 'rgba(255, 235, 188, 0.027)');
   glow.addColorStop(1, 'rgba(255, 242, 214, 0)');
   ctx.fillStyle = glow;
-  ctx.fillRect(cx - radius - 4, cy - radius - 4, (radius + 4) * 2, (radius + 4) * 2);
+  ctx.fillRect(
+    cx - radius - 4,
+    cy - radius - 4,
+    (radius + 4) * 2,
+    (radius + 4) * 2,
+  );
 
   ctx.lineCap = 'round';
   ctx.shadowColor = 'rgba(255, 232, 171, 0.11)';
@@ -299,7 +347,10 @@ function drawSunRays(ctx, cx, cy, radius, innerRadius, angle) {
     const ex = sx + Math.cos(rayAngle) * rayLength;
     const ey = sy + Math.sin(rayAngle) * rayLength;
     const lineGradient = ctx.createLinearGradient(sx, sy, ex, ey);
-    lineGradient.addColorStop(0, `rgba(255, 230, 166, ${0.075 - Math.abs(i) * 0.011})`);
+    lineGradient.addColorStop(
+      0,
+      `rgba(255, 230, 166, ${0.075 - Math.abs(i) * 0.011})`,
+    );
     lineGradient.addColorStop(1, 'rgba(255, 226, 156, 0)');
     ctx.strokeStyle = lineGradient;
     ctx.lineWidth = i === 0 ? 1.8 : 0.9;
@@ -328,19 +379,28 @@ function drawMoonHaze(ctx, cx, cy, radius, angle) {
   ctx.restore();
 }
 
+// Keys each ring's overlay, so a new ring never reuses an old one's canvases.
+let rings = 0;
+
 /**
  * Screen-space ring and celestial direction overlay for the full-globe view.
+ * The overlay is presented to the celestial ring store, whose view renders it
+ * inside the viewer's container and hands back the two canvases this paints.
  */
 export class CelestialRing {
   /**
    * @param {Cesium.Viewer} viewer
-   * @param {{enabled?:boolean,onAutoDisable?:Function}} [options]
+   * @param {{enabled?:boolean,onAutoDisable?:Function,store:object}} options
+   *   `store` is the celestial ring store (src/ui/stores/celestialRing.js);
+   *   the keyhole helpers here stay free of Vue for the packages that use
+   *   them.
    */
-  constructor(viewer, { enabled = true, onAutoDisable = null } = {}) {
+  constructor(viewer, { enabled = true, onAutoDisable = null, store }) {
     this.viewer = viewer;
     this.enabled = !!enabled;
     this.visible = false;
-    this._onAutoDisable = typeof onAutoDisable === 'function' ? onAutoDisable : null;
+    this._onAutoDisable =
+      typeof onAutoDisable === 'function' ? onAutoDisable : null;
     this._focusInProgress = false;
     this._ephemerisDirty = true;
     this._ephemerisUpdateCount = 0;
@@ -354,6 +414,10 @@ export class CelestialRing {
     this._sunRenderKey = '';
     this._moonRenderKey = '';
     this._outlineRenderKey = '';
+    this._sunCanvas = null;
+    this._sunCtx = null;
+    this._moonCanvas = null;
+    this._moonCtx = null;
 
     this._sunInertial = new Cesium.Cartesian3();
     this._moonInertial = new Cesium.Cartesian3();
@@ -363,8 +427,10 @@ export class CelestialRing {
     this._screenCenter = new Cesium.Cartesian2();
     this._fixedMatrix = new Cesium.Matrix3();
 
-    this._buildDOM();
-    this._removePostRender = viewer.scene.postRender.addEventListener(() => this._draw());
+    this._initView(store);
+    this._removePostRender = viewer.scene.postRender.addEventListener(() =>
+      this._draw(),
+    );
     // Pre-existing staleness fix (perf wave 2 review): the ephemeris was
     // sampled once per visible-enable from the FROZEN app clock, so the
     // sun/moon markers aged with the app. Resample real wall time each
@@ -382,40 +448,68 @@ export class CelestialRing {
     this.setEnabled(this.enabled);
   }
 
-  /** Construct cached effect layers and Material Symbols celestial markers. */
-  _buildDOM() {
-    this._root = document.createElement('div');
-    this._root.id = 'celestial-ring-overlay';
-    this._root.className = 'celestial-ring-overlay';
-    this._root.setAttribute('aria-hidden', 'true');
+  /** Present the overlay and take the canvases its view hands back. */
+  _initView(store) {
+    const owner = {};
+    this._store = store;
+    this._owner = owner;
+    this._view = {
+      id: ++rings,
+      owner,
+      container: this.viewer.container,
+      enabled: this.enabled,
+      visible: false,
+      globeVisible: null,
+      ephemerisUpdates: null,
+      size: null,
+      outline: null,
+      sun: null,
+      moon: null,
+      sunMarker: null,
+      moonMarker: null,
+    };
+    this._viewKey = '';
+    store.publish(this._view);
+    store.connect({
+      attach: (from, kind, canvas) => {
+        if (from === owner && this._shown()) this._attach(kind, canvas);
+      },
+    });
+  }
 
-    this._ringOutline = document.createElement('div');
-    this._ringOutline.className = 'celestial-ring-outline';
+  /** Whether the store still shows this ring's overlay. */
+  _shown() {
+    return this._store.ring?.owner === this._owner;
+  }
 
-    this._sunCanvas = document.createElement('canvas');
-    this._sunCanvas.className = 'celestial-ring-canvas celestial-sun-canvas';
-    this._sunCtx = this._sunCanvas.getContext('2d', { alpha: true, desynchronized: true });
-
-    this._moonCanvas = document.createElement('canvas');
-    this._moonCanvas.className = 'celestial-ring-canvas celestial-moon-canvas';
-    this._moonCtx = this._moonCanvas.getContext('2d', { alpha: true, desynchronized: true });
-
-    this._sunMarker = document.createElement('span');
-    this._sunMarker.className = 'celestial-marker celestial-sun material-symbols-outlined';
-    this._sunMarker.textContent = 'light_mode';
-
-    this._moonMarker = document.createElement('span');
-    this._moonMarker.className = 'celestial-marker celestial-moon material-symbols-outlined';
-    this._moonMarker.textContent = 'dark_mode';
-
-    this._root.append(
-      this._ringOutline,
-      this._sunCanvas,
-      this._moonCanvas,
-      this._sunMarker,
-      this._moonMarker
+  /** Publish a change to the overlay, skipping one that changes nothing. */
+  _present(patch) {
+    if (!this._shown()) return;
+    const next = { ...this._view, ...patch };
+    const key = JSON.stringify(next, (name, value) =>
+      name === 'owner' || name === 'container' ? undefined : value,
     );
-    this.viewer.container.appendChild(this._root);
+    if (key === this._viewKey) return;
+    this._view = next;
+    this._viewKey = key;
+    this._store.publish(next);
+  }
+
+  /** Take (or, with null, drop) the canvas the view rendered for one layer. */
+  _attach(kind, canvas) {
+    const ctx =
+      canvas?.getContext('2d', { alpha: true, desynchronized: true }) ?? null;
+    // A new canvas starts blank, so the next frame repaints its layer.
+    if (kind === 'sun') {
+      this._sunCanvas = canvas;
+      this._sunCtx = ctx;
+      this._sunRenderKey = '';
+    } else if (kind === 'moon') {
+      this._moonCanvas = canvas;
+      this._moonCtx = ctx;
+      this._moonRenderKey = '';
+    } else return;
+    if (canvas && this.enabled) governorRequestRender('celestial-ring');
   }
 
   /** Enable or disable the user preference for the effect. */
@@ -429,12 +523,14 @@ export class CelestialRing {
     // all. Camera motion covers every later repaint; the 60 s ephemeris
     // timer requests its own. (perf wave 2 fix — owner playtest finding)
     if (this.enabled !== wasEnabled) governorRequestRender('celestial-ring');
-    this._root.classList.toggle('disabled', !this.enabled);
     if (!this.enabled) {
       this.visible = false;
-      this._root.classList.remove('visible');
       this._clear();
     }
+    this._present({
+      enabled: this.enabled,
+      ...(!this.enabled && { visible: false }),
+    });
   }
 
   /** Whether the current camera already frames the complete globe inside the keyhole. */
@@ -458,15 +554,24 @@ export class CelestialRing {
     const height = canvas.clientHeight || canvas.height;
     const cartographic = this.viewer.camera.positionCartographic;
     const fovy = this.viewer.camera.frustum?.fovy;
-    if (!(height > 0) || !cartographic || !Number.isFinite(fovy) || fovy <= 0 || fovy >= Math.PI) {
+    if (
+      !(height > 0) ||
+      !cartographic ||
+      !Number.isFinite(fovy) ||
+      fovy <= 0 ||
+      fovy >= Math.PI
+    ) {
       return false;
     }
 
     const earthRadius = Cesium.Ellipsoid.WGS84.maximumRadius;
-    const keyholeRadius = getKeyholeGeometry(canvas.clientWidth || canvas.width, height).radius;
+    const keyholeRadius = getKeyholeGeometry(
+      canvas.clientWidth || canvas.width,
+      height,
+    ).radius;
     const targetScreenRadius = keyholeRadius * FULL_GLOBE_RADIUS_RATIO;
     const angularRadius = Math.atan(
-      (targetScreenRadius / (height * 0.5)) * Math.tan(fovy * 0.5)
+      (targetScreenRadius / (height * 0.5)) * Math.tan(fovy * 0.5),
     );
     const distance = earthRadius / Math.max(Math.sin(angularRadius), 1e-4);
     const altitude = Math.max(earthRadius * 1.55, distance - earthRadius);
@@ -480,7 +585,7 @@ export class CelestialRing {
       destination: Cesium.Cartesian3.fromRadians(
         cartographic.longitude,
         cartographic.latitude,
-        altitude
+        altitude,
       ),
       orientation: {
         heading: this.viewer.camera.heading,
@@ -500,10 +605,13 @@ export class CelestialRing {
 
   /** Clear the backing canvas. */
   _clear() {
-    for (const [canvas, ctx] of [[this._sunCanvas, this._sunCtx], [this._moonCanvas, this._moonCtx]]) {
+    for (const [canvas, ctx] of [
+      [this._sunCanvas, this._sunCtx],
+      [this._moonCanvas, this._moonCtx],
+    ]) {
       if (canvas && ctx) ctx.clearRect(0, 0, canvas.width, canvas.height);
     }
-    this._ringOutline?.style.setProperty('display', 'none');
+    this._present({ outline: { ...this._view.outline, hidden: true } });
     this._sunRenderKey = '';
     this._moonRenderKey = '';
     this._outlineRenderKey = '';
@@ -512,20 +620,30 @@ export class CelestialRing {
   /** Resize the canvas backing store while drawing in CSS pixels. */
   _resize(width, height) {
     const nativeDpr = Math.max(1, window.devicePixelRatio || 1);
-    const pixelsScale = Math.sqrt(CELESTIAL_MAX_BACKING_PIXELS / (width * height));
-    const dimensionScale = CELESTIAL_MAX_BACKING_DIMENSION / Math.max(width, height);
-    const dpr = Math.min(nativeDpr, CELESTIAL_MAX_DEVICE_PIXEL_RATIO, pixelsScale, dimensionScale);
+    const pixelsScale = Math.sqrt(
+      CELESTIAL_MAX_BACKING_PIXELS / (width * height),
+    );
+    const dimensionScale =
+      CELESTIAL_MAX_BACKING_DIMENSION / Math.max(width, height);
+    const dpr = Math.min(
+      nativeDpr,
+      CELESTIAL_MAX_DEVICE_PIXEL_RATIO,
+      pixelsScale,
+      dimensionScale,
+    );
     const bw = Math.max(1, Math.round(width * dpr));
     const bh = Math.max(1, Math.round(height * dpr));
-    for (const [canvas, ctx] of [[this._sunCanvas, this._sunCtx], [this._moonCanvas, this._moonCtx]]) {
+    for (const [canvas, ctx] of [
+      [this._sunCanvas, this._sunCtx],
+      [this._moonCanvas, this._moonCtx],
+    ]) {
       if (canvas.width !== bw || canvas.height !== bh) {
         canvas.width = bw;
         canvas.height = bh;
       }
-      canvas.style.width = `${width}px`;
-      canvas.style.height = `${height}px`;
       ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
     }
+    this._present({ size: { width, height } });
     this._renderScale = dpr;
   }
 
@@ -536,14 +654,25 @@ export class CelestialRing {
   _updateEphemeris(time) {
     if (!this._ephemerisDirty) return true;
 
-    Cesium.Simon1994PlanetaryPositions.computeSunPositionInEarthInertialFrame(time, this._sunInertial);
-    Cesium.Simon1994PlanetaryPositions.computeMoonPositionInEarthInertialFrame(time, this._moonInertial);
-    const matrix = Cesium.Transforms.computeIcrfToFixedMatrix(time, this._fixedMatrix)
-      || Cesium.Transforms.computeTemeToPseudoFixedMatrix(time, this._fixedMatrix);
+    Cesium.Simon1994PlanetaryPositions.computeSunPositionInEarthInertialFrame(
+      time,
+      this._sunInertial,
+    );
+    Cesium.Simon1994PlanetaryPositions.computeMoonPositionInEarthInertialFrame(
+      time,
+      this._moonInertial,
+    );
+    const matrix =
+      Cesium.Transforms.computeIcrfToFixedMatrix(time, this._fixedMatrix) ||
+      Cesium.Transforms.computeTemeToPseudoFixedMatrix(time, this._fixedMatrix);
     if (!matrix) return false;
 
     Cesium.Matrix3.multiplyByVector(matrix, this._sunInertial, this._sunFixed);
-    Cesium.Matrix3.multiplyByVector(matrix, this._moonInertial, this._moonFixed);
+    Cesium.Matrix3.multiplyByVector(
+      matrix,
+      this._moonInertial,
+      this._moonFixed,
+    );
     Cesium.Cartesian3.normalize(this._sunFixed, this._sunFixed);
     Cesium.Cartesian3.normalize(this._moonFixed, this._moonFixed);
     this._ephemerisDirty = false;
@@ -569,41 +698,63 @@ export class CelestialRing {
     );
   }
 
-  /** Position one icon-library marker along the keyhole circumference. */
-  _positionMarker(marker, cx, cy, radius, angle, opacity) {
+  /** Where one icon-library marker sits along the keyhole circumference. */
+  _markerPosition(cx, cy, radius, angle, opacity) {
     const cos = Math.cos(angle);
     const sin = Math.sin(angle);
     const margin = 14;
-    const maxRadiusX = Math.abs(cos) > 1e-4 ? (cx - margin) / Math.abs(cos) : Number.POSITIVE_INFINITY;
-    const maxRadiusY = Math.abs(sin) > 1e-4 ? (cy - margin) / Math.abs(sin) : Number.POSITIVE_INFINITY;
+    const maxRadiusX =
+      Math.abs(cos) > 1e-4
+        ? (cx - margin) / Math.abs(cos)
+        : Number.POSITIVE_INFINITY;
+    const maxRadiusY =
+      Math.abs(sin) > 1e-4
+        ? (cy - margin) / Math.abs(sin)
+        : Number.POSITIVE_INFINITY;
     const markerRadius = Math.min(radius, maxRadiusX, maxRadiusY);
-    marker.style.left = `${cx + cos * markerRadius}px`;
-    marker.style.top = `${cy + sin * markerRadius}px`;
-    marker.style.opacity = String(opacity);
+    return {
+      left: cx + cos * markerRadius,
+      top: cy + sin * markerRadius,
+      opacity: String(opacity),
+    };
   }
 
   /** Update the cached effect geometry only when camera distance or viewport changes. */
   _renderEffectLayers(cx, cy, radius, rayInnerRadius) {
     const outlineKey = `${cx}:${cy}:${radius}`;
     if (outlineKey !== this._outlineRenderKey) {
-      this._ringOutline.style.display = '';
-      this._ringOutline.style.left = `${cx - radius}px`;
-      this._ringOutline.style.top = `${cy - radius}px`;
-      this._ringOutline.style.width = `${radius * 2}px`;
-      this._ringOutline.style.height = `${radius * 2}px`;
+      this._present({
+        outline: {
+          hidden: false,
+          left: cx - radius,
+          top: cy - radius,
+          width: radius * 2,
+          height: radius * 2,
+        },
+      });
       this._outlineRenderKey = outlineKey;
     }
 
     const sunKey = `${outlineKey}:${Math.round(rayInnerRadius)}`;
     if (sunKey !== this._sunRenderKey) {
-      this._sunCtx.clearRect(0, 0, this._sunCanvas.width, this._sunCanvas.height);
+      this._sunCtx.clearRect(
+        0,
+        0,
+        this._sunCanvas.width,
+        this._sunCanvas.height,
+      );
       drawSunRays(this._sunCtx, cx, cy, radius, rayInnerRadius, 0);
       drawTaperedArc(this._sunCtx, cx, cy, radius, 0, '222, 190, 89', 0.56);
       this._sunRenderKey = sunKey;
     }
 
     if (outlineKey !== this._moonRenderKey) {
-      this._moonCtx.clearRect(0, 0, this._moonCanvas.width, this._moonCanvas.height);
+      this._moonCtx.clearRect(
+        0,
+        0,
+        this._moonCanvas.width,
+        this._moonCanvas.height,
+      );
       drawMoonHaze(this._moonCtx, cx, cy, radius, 0);
       drawTaperedArc(this._moonCtx, cx, cy, radius, 0, '48, 201, 229', 0.42);
       this._moonRenderKey = outlineKey;
@@ -612,7 +763,11 @@ export class CelestialRing {
 
   /** Per-frame camera projection with GPU-composited cached effect layers. */
   _draw() {
-    if (!this.enabled || !this._sunCtx || !this._moonCtx) return;
+    // A ring the store no longer shows has handed its overlay to a later one.
+    if (!this.enabled || !this._shown()) return;
+    // Without its canvases (no view rendered them) the ring still tracks
+    // whether the globe is framed, so it turns itself off as before.
+    const painted = !!(this._sunCtx && this._moonCtx);
     const now = performance.now();
     if (now < this._nextDrawAt) return;
     this._nextDrawAt = now + 1000 / CELESTIAL_MAX_FRAME_RATE;
@@ -620,15 +775,19 @@ export class CelestialRing {
     const width = canvas.clientWidth || canvas.width;
     const height = canvas.clientHeight || canvas.height;
     if (!(width > 0 && height > 0)) return;
-    this._resize(width, height);
+    if (painted) this._resize(width, height);
 
     const disc = this._projectedEarthDisc(width, height);
     const wasVisible = this.visible;
-    const nextVisible = disc ? isFullGlobeInsideKeyhole(disc, wasVisible) : false;
+    const nextVisible = disc
+      ? isFullGlobeInsideKeyhole(disc, wasVisible)
+      : false;
     this.visible = nextVisible;
-    this._root.classList.toggle('visible', nextVisible);
-    this._root.dataset.globeVisible = String(nextVisible);
-    this._root.dataset.ephemerisUpdates = String(this._ephemerisUpdateCount);
+    this._present({
+      visible: nextVisible,
+      globeVisible: String(nextVisible),
+      ephemerisUpdates: String(this._ephemerisUpdateCount),
+    });
     if (!nextVisible || !disc) {
       this._clear();
       this._debug = { enabled: true, visible: false, disc };
@@ -637,20 +796,24 @@ export class CelestialRing {
     }
 
     if (!wasVisible) this._ephemerisDirty = true;
+    if (!painted) {
+      this._debug = { enabled: true, visible: true, disc };
+      return;
+    }
 
     const time = Cesium.JulianDate.now();
     if (!this._updateEphemeris(time)) return;
-    this._root.dataset.ephemerisUpdates = String(this._ephemerisUpdateCount);
+    this._present({ ephemerisUpdates: String(this._ephemerisUpdateCount) });
     const camera = this.viewer.camera;
     const sunProjection = celestialScreenAngle(
       Cesium.Cartesian3.dot(this._sunFixed, camera.rightWC),
       Cesium.Cartesian3.dot(this._sunFixed, camera.upWC),
-      this._sunAngle
+      this._sunAngle,
     );
     const moonProjection = celestialScreenAngle(
       Cesium.Cartesian3.dot(this._moonFixed, camera.rightWC),
       Cesium.Cartesian3.dot(this._moonFixed, camera.upWC),
-      this._moonAngle
+      this._moonAngle,
     );
     if (sunProjection.stable) this._sunAngle = sunProjection.angle;
     if (moonProjection.stable) this._moonAngle = moonProjection.angle;
@@ -660,28 +823,43 @@ export class CelestialRing {
     const cx = width * 0.5;
     const cy = height * 0.5;
     const radius = disc.keyholeRadius - RING_INSET_PX;
-    const rayInnerRadius = Math.min(radius - 12, disc.earthRadius + Math.max(38, radius * 0.065));
+    const rayInnerRadius = Math.min(
+      radius - 12,
+      disc.earthRadius + Math.max(38, radius * 0.065),
+    );
     this._renderEffectLayers(cx, cy, radius, rayInnerRadius);
-    this._sunCanvas.style.transform = `rotate(${this._sunAngle}rad)`;
-    this._sunCanvas.style.opacity = String(this._sunOpacity);
-    this._moonCanvas.style.transform = `rotate(${this._moonAngle}rad)`;
-    this._moonCanvas.style.opacity = String(this._moonOpacity);
 
     // Markers sit inside the illuminated band rather than straddling its outer
     // stroke. Near conjunction (such as a new moon), keep the true bearings but
     // move the moon into a second radial lane so both bodies remain legible.
     const markerRadius = radius - MARKER_INSET_PX;
-    const markersCollide = circularAngleDistance(this._sunAngle, this._moonAngle)
-      < MARKER_COLLISION_ANGLE;
-    this._positionMarker(this._sunMarker, cx, cy, markerRadius, this._sunAngle, this._sunOpacity);
-    this._positionMarker(
-      this._moonMarker,
-      cx,
-      cy,
-      markerRadius - (markersCollide ? COLLIDING_MARKER_EXTRA_INSET_PX : 0),
-      this._moonAngle,
-      this._moonOpacity
-    );
+    const markersCollide =
+      circularAngleDistance(this._sunAngle, this._moonAngle) <
+      MARKER_COLLISION_ANGLE;
+    this._present({
+      sun: {
+        transform: `rotate(${this._sunAngle}rad)`,
+        opacity: String(this._sunOpacity),
+      },
+      moon: {
+        transform: `rotate(${this._moonAngle}rad)`,
+        opacity: String(this._moonOpacity),
+      },
+      sunMarker: this._markerPosition(
+        cx,
+        cy,
+        markerRadius,
+        this._sunAngle,
+        this._sunOpacity,
+      ),
+      moonMarker: this._markerPosition(
+        cx,
+        cy,
+        markerRadius - (markersCollide ? COLLIDING_MARKER_EXTRA_INSET_PX : 0),
+        this._moonAngle,
+        this._moonOpacity,
+      ),
+    });
     this._debug = {
       enabled: true,
       visible: true,
@@ -698,10 +876,15 @@ export class CelestialRing {
 
   /** Read-only geometry snapshot for browser QA. */
   getDebugState() {
-    return this._debug ? { ...this._debug, disc: this._debug.disc ? { ...this._debug.disc } : null } : null;
+    return this._debug
+      ? {
+          ...this._debug,
+          disc: this._debug.disc ? { ...this._debug.disc } : null,
+        }
+      : null;
   }
 
-  /** Detach the render hook and remove all overlay DOM. */
+  /** Detach the render hook and withdraw the overlay. */
   destroy() {
     if (this._ephemerisTimer) {
       clearInterval(this._ephemerisTimer);
@@ -709,6 +892,10 @@ export class CelestialRing {
     }
     if (this._removePostRender) this._removePostRender();
     this._removePostRender = null;
-    this._root?.remove();
+    if (this._shown()) {
+      this._store.connect(null);
+      this._store.publish(null);
+    }
+    this._sunCanvas = this._sunCtx = this._moonCanvas = this._moonCtx = null;
   }
 }

src/celestialRing.test.mjs

@@ -87,7 +87,7 @@ test('circular angle distance remains small across the wrap point', () => {
 
 test('celestial ring is available only in Normal style', () => {
   assert.equal(isCelestialRingStyleSupported('normal'), true);
-  for (const style of ['retro', 'surveillance', 'thermal', 'anime', 'noir', 'snow']) {
+  for (const style of ['retro', 'surveillance', 'thermal', 'anime', 'noir']) {
     assert.equal(isCelestialRingStyleSupported(style), false);
   }
 });

src/celestialRingView.test.mjs

@@ -0,0 +1,251 @@
+// src/celestialRingView.test.mjs — the full-globe ring renders in the
+// viewer's container from what the ring owner presents, and the owner paints
+// the canvases the view hands back.
+import './testSupport/registerDom.mjs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createApp, nextTick } from 'vue';
+import { createPinia } from 'pinia';
+import { useCelestialRingStore } from './ui/stores/celestialRing.js';
+import CelestialRingView from './ui/views/panels/CelestialRing.vue';
+import * as Cesium from 'cesium';
+import { CelestialRing } from './celestialRing.js';
+
+// happy-dom has no 2D context; a stand-in takes every drawing call.
+const context = new Proxy(
+  {},
+  { get: (target, name) => target[name] ?? (() => context), set: () => true },
+);
+globalThis.HTMLCanvasElement.prototype.getContext = () => context;
+
+function fakeViewer(container) {
+  return {
+    container,
+    camera: {
+      rightWC: new Cesium.Cartesian3(1, 0, 0),
+      upWC: new Cesium.Cartesian3(0, 1, 0),
+    },
+    scene: {
+      canvas: { clientWidth: 400, clientHeight: 300, width: 400, height: 300 },
+      postRender: { addEventListener: () => () => {} },
+      requestRender() {},
+    },
+  };
+}
+
+function fixture(t) {
+  document.body.replaceChildren();
+  const container = document.body.appendChild(document.createElement('div'));
+  const pinia = createPinia();
+  const store = useCelestialRingStore(pinia);
+  const app = createApp(CelestialRingView).use(pinia);
+  app.mount(document.body.appendChild(document.createElement('div')));
+  const rings = [];
+  const create = (options = {}) => {
+    const ring = new CelestialRing(fakeViewer(container), {
+      enabled: false,
+      store,
+      ...options,
+    });
+    rings.push(ring);
+    return ring;
+  };
+  t.after(() => {
+    for (const ring of rings) ring.destroy();
+    app.unmount();
+  });
+  const $ = (selector) => container.querySelector(selector);
+  const settle = async () => {
+    for (let flush = 0; flush < 4; flush += 1) await nextTick();
+  };
+  return { container, store, create, $, settle };
+}
+
+test('the ring renders its overlay in the viewer container', async (t) => {
+  const { create, $, settle } = fixture(t);
+  const ring = create();
+  await settle();
+  const root = $('#celestial-ring-overlay');
+  assert.equal(root.className, 'celestial-ring-overlay disabled');
+  assert.equal(root.getAttribute('aria-hidden'), 'true');
+  assert.equal(root.hasAttribute('data-globe-visible'), false);
+  assert.deepEqual(
+    [...root.children].map((child) => [child.tagName, child.className]),
+    [
+      ['DIV', 'celestial-ring-outline'],
+      ['CANVAS', 'celestial-ring-canvas celestial-sun-canvas'],
+      ['CANVAS', 'celestial-ring-canvas celestial-moon-canvas'],
+      ['SPAN', 'celestial-marker celestial-sun material-symbols-outlined'],
+      ['SPAN', 'celestial-marker celestial-moon material-symbols-outlined'],
+    ],
+  );
+  assert.equal(root.children[0].style.display, 'none');
+  assert.equal(root.children[3].textContent, 'light_mode');
+  assert.equal(root.children[4].textContent, 'dark_mode');
+  assert.ok(ring._sunCanvas === root.children[1]);
+  assert.ok(ring._moonCanvas === root.children[2]);
+  ring.setEnabled(true);
+  await settle();
+  assert.equal(root.className, 'celestial-ring-overlay');
+  ring.destroy();
+  await settle();
+  assert.equal($('#celestial-ring-overlay'), null);
+  assert.equal(ring._sunCanvas, null);
+});
+
+test('a drawn frame places the outline, layers and markers', async (t) => {
+  const { create, $, settle } = fixture(t);
+  const ring = create({ enabled: true });
+  await settle();
+  ring._present({ visible: true, globeVisible: 'true', ephemerisUpdates: '1' });
+  ring._resize(400, 300);
+  ring._renderEffectLayers(200, 150, 120, 80);
+  ring._present({
+    sun: { transform: 'rotate(1rad)', opacity: '0.5' },
+    sunMarker: ring._markerPosition(200, 150, 100, 0, 1),
+  });
+  await settle();
+  const root = $('#celestial-ring-overlay');
+  assert.equal(root.className, 'celestial-ring-overlay visible');
+  assert.equal(root.dataset.globeVisible, 'true');
+  assert.equal(root.dataset.ephemerisUpdates, '1');
+  const [outline, sun, moon, sunMarker] = root.children;
+  assert.equal(outline.style.display, '');
+  assert.equal(outline.style.left, '80px');
+  assert.equal(outline.style.width, '240px');
+  assert.equal(sun.style.width, '400px');
+  assert.equal(sun.style.transform, 'rotate(1rad)');
+  assert.equal(sun.style.opacity, '0.5');
+  assert.equal(moon.style.height, '300px');
+  assert.equal(sunMarker.style.left, '300px');
+  assert.equal(sunMarker.style.top, '150px');
+  ring.setEnabled(false);
+  await settle();
+  assert.equal(root.className, 'celestial-ring-overlay disabled');
+  assert.equal(outline.style.display, 'none');
+});
+
+test("an earlier ring leaves a later ring's overlay alone", async (t) => {
+  const { create, store, $, settle } = fixture(t);
+  const earlier = create();
+  await settle();
+  const later = create();
+  await settle();
+  const root = $('#celestial-ring-overlay');
+  assert.ok(later._sunCanvas === root.children[1]);
+  earlier.setEnabled(true);
+  earlier.destroy();
+  await settle();
+  assert.ok(store.ring.owner === later._owner);
+  assert.equal(
+    $('#celestial-ring-overlay').className,
+    'celestial-ring-overlay disabled',
+  );
+  assert.ok(later._sunCanvas === $('.celestial-sun-canvas'));
+});
+
+// A globe framed well inside the keyhole of a 400 x 300 view.
+const FRAMED = {
+  earthCenterX: 200,
+  earthCenterY: 150,
+  earthRadius: 40,
+  keyholeCenterX: 200,
+  keyholeCenterY: 150,
+  keyholeRadius: 140,
+};
+
+/** Run one rendered frame, past the frame-rate throttle. */
+function frame(ring, disc) {
+  ring._projectedEarthDisc = () => disc;
+  // Fixed sun and moon directions; Cesium's own model would fetch its
+  // orientation data.
+  ring._updateEphemeris = () => {
+    if (ring._ephemerisDirty) {
+      Cesium.Cartesian3.clone(new Cesium.Cartesian3(1, 0, 0), ring._sunFixed);
+      Cesium.Cartesian3.clone(new Cesium.Cartesian3(0, 1, 0), ring._moonFixed);
+      ring._ephemerisDirty = false;
+      ring._ephemerisUpdateCount += 1;
+    }
+    return true;
+  };
+  ring._nextDrawAt = 0;
+  ring._draw();
+}
+
+test('a rendered frame publishes the layers and markers it painted', async (t) => {
+  const { create, $, settle } = fixture(t);
+  const ring = create({ enabled: true });
+  await settle();
+  frame(ring, FRAMED);
+  await settle();
+  const root = $('#celestial-ring-overlay');
+  assert.equal(root.className, 'celestial-ring-overlay visible');
+  assert.equal(root.dataset.globeVisible, 'true');
+  assert.equal(root.dataset.ephemerisUpdates, '1');
+  const [outline, sun, moon, sunMarker, moonMarker] = root.children;
+  const debug = ring.getDebugState();
+  assert.equal(debug.visible, true);
+  assert.equal(outline.style.display, '');
+  // The outline is the keyhole circle, a fixed inset inside its radius.
+  const diameter = parseFloat(outline.style.width);
+  assert.ok(diameter > 0 && diameter < 280);
+  assert.equal(outline.style.height, outline.style.width);
+  assert.equal(outline.style.left, `${200 - diameter / 2}px`);
+  assert.equal(outline.style.top, `${150 - diameter / 2}px`);
+  assert.equal(sun.style.width, '400px');
+  assert.equal(moon.style.height, '300px');
+  assert.equal(sun.style.transform, `rotate(${debug.sunAngle}rad)`);
+  assert.equal(moon.style.transform, `rotate(${debug.moonAngle}rad)`);
+  assert.equal(sun.style.opacity, String(debug.sunOpacity));
+  assert.equal(moon.style.opacity, String(debug.moonOpacity));
+  assert.ok(sunMarker.style.left.endsWith('px'));
+  assert.ok(moonMarker.style.top.endsWith('px'));
+  assert.equal(moonMarker.style.opacity, String(debug.moonOpacity));
+});
+
+test('a frame without the globe framed turns the ring off', async (t) => {
+  const { create, $, settle } = fixture(t);
+  let disabled = 0;
+  const ring = create({ enabled: true, onAutoDisable: () => (disabled += 1) });
+  await settle();
+  frame(ring, FRAMED);
+  frame(ring, null);
+  await settle();
+  assert.equal(ring.enabled, false);
+  assert.equal(disabled, 1);
+  assert.equal(
+    $('#celestial-ring-overlay').className,
+    'celestial-ring-overlay disabled',
+  );
+});
+
+test('without a rendered view the ring still tracks the globe and turns off', () => {
+  const pinia = createPinia();
+  let disabled = 0;
+  const ring = new CelestialRing(fakeViewer({}), {
+    enabled: true,
+    store: useCelestialRingStore(pinia),
+    onAutoDisable: () => (disabled += 1),
+  });
+  frame(ring, FRAMED);
+  assert.equal(ring.visible, true);
+  frame(ring, null);
+  assert.equal(ring.enabled, false);
+  assert.equal(disabled, 1);
+  ring.destroy();
+});
+
+test('a ring the store no longer shows stops drawing', async (t) => {
+  const { create, settle } = fixture(t);
+  let disabled = 0;
+  const earlier = create({
+    enabled: true,
+    onAutoDisable: () => (disabled += 1),
+  });
+  await settle();
+  create();
+  await settle();
+  frame(earlier, null);
+  assert.equal(earlier.enabled, true);
+  assert.equal(disabled, 0);
+});

src/cityPois.js

@@ -0,0 +1,514 @@
+/**
+ * @module cityPois
+ * @description The preset cities and their landmarks — plain data with no
+ * Cesium, so modules that only need the names (voice cards) can import it.
+ */
+
+/**
+ * Points of Interest per city.
+ * Each city has 5 POIs; the first is the default fly-to landmark.
+ *
+ * Field reference:
+ *   alt     — RANGE (distance from target in meters), NOT absolute altitude
+ *   heading — optimal camera heading in degrees (0=N, 90=E, 180=S, 270=W)
+ *   pitch   — camera tilt in degrees (negative = looking down)
+ *   buildingHeight — estimated height of landmark center above ground (meters)
+ */
+export const CITY_POIS = {
+  austin: {
+    name: 'Austin',
+    groundElevation: 150, // meters above WGS84 ellipsoid
+    viewBounds: {
+      southwest: { lat: 30.1, lng: -97.95 },
+      northeast: { lat: 30.52, lng: -97.55 },
+    },
+    pois: [
+      {
+        name: 'Texas State Capitol',
+        lat: 30.2747,
+        lon: -97.7403,
+        alt: 550,
+        pitch: -28,
+        heading: 180,
+        buildingHeight: 35,
+      },
+      {
+        name: 'Frost Bank Tower',
+        lat: 30.2674,
+        lon: -97.7434,
+        alt: 550,
+        pitch: -22,
+        heading: 30,
+        buildingHeight: 80,
+      },
+      {
+        name: 'Pennybacker Bridge',
+        lat: 30.3451,
+        lon: -97.7951,
+        alt: 500,
+        pitch: -25,
+        heading: 90,
+        buildingHeight: 40,
+      },
+      {
+        name: 'The Jenga Tower',
+        lat: 30.2642,
+        lon: -97.75,
+        alt: 500,
+        pitch: -18,
+        heading: 45,
+        buildingHeight: 60,
+      },
+      {
+        name: 'UT Tower',
+        lat: 30.2862,
+        lon: -97.7394,
+        alt: 500,
+        pitch: -22,
+        heading: 180,
+        buildingHeight: 50,
+      },
+    ],
+  },
+  sf: {
+    name: 'San Francisco',
+    groundElevation: 15,
+    viewBounds: {
+      southwest: { lat: 37.7, lng: -122.53 },
+      northeast: { lat: 37.84, lng: -122.35 },
+    },
+    pois: [
+      {
+        name: 'Golden Gate Bridge',
+        lat: 37.8199,
+        lon: -122.4783,
+        alt: 1400,
+        pitch: -20,
+        heading: 45,
+        buildingHeight: 100,
+      },
+      {
+        name: 'Transamerica Pyramid',
+        lat: 37.7952,
+        lon: -122.4028,
+        alt: 500,
+        pitch: -25,
+        heading: 30,
+        buildingHeight: 85,
+      },
+      {
+        name: 'Salesforce Tower',
+        lat: 37.7897,
+        lon: -122.3972,
+        alt: 680,
+        pitch: -25,
+        heading: 330,
+        buildingHeight: 100,
+      },
+      {
+        name: 'Alcatraz Island',
+        lat: 37.8267,
+        lon: -122.423,
+        alt: 800,
+        pitch: -30,
+        heading: 0,
+        buildingHeight: 20,
+      },
+      {
+        name: 'Coit Tower',
+        lat: 37.8024,
+        lon: -122.4058,
+        alt: 420,
+        pitch: -30,
+        heading: 45,
+        buildingHeight: 30,
+      },
+    ],
+  },
+  nyc: {
+    name: 'New York',
+    groundElevation: 10,
+    viewBounds: {
+      southwest: { lat: 40.477, lng: -74.259 },
+      northeast: { lat: 40.918, lng: -73.7 },
+    },
+    pois: [
+      {
+        name: 'Statue of Liberty',
+        lat: 40.6892,
+        lon: -74.0445,
+        alt: 450,
+        pitch: -25,
+        heading: 315,
+        buildingHeight: 45,
+      },
+      {
+        name: 'Empire State Building',
+        lat: 40.7484,
+        lon: -73.9857,
+        alt: 850,
+        pitch: -12,
+        heading: 30,
+        buildingHeight: 130,
+        buildingBounds: { height: 443, width: 130, depth: 75 },
+      },
+      {
+        name: 'One World Trade Center',
+        lat: 40.7127,
+        lon: -74.0134,
+        alt: 850,
+        pitch: -25,
+        heading: 0,
+        buildingHeight: 170,
+      },
+      {
+        name: 'Brooklyn Bridge',
+        lat: 40.7061,
+        lon: -73.9969,
+        alt: 850,
+        pitch: -25,
+        heading: 45,
+        buildingHeight: 40,
+      },
+      {
+        name: 'Chrysler Building',
+        lat: 40.7516,
+        lon: -73.9755,
+        alt: 700,
+        pitch: -20,
+        heading: 225,
+        buildingHeight: 100,
+      },
+    ],
+  },
+  tokyo: {
+    name: 'Tokyo',
+    groundElevation: 40,
+    viewBounds: {
+      southwest: { lat: 35.52, lng: 139.55 },
+      northeast: { lat: 35.9, lng: 139.92 },
+    },
+    pois: [
+      {
+        name: 'Tokyo Tower',
+        lat: 35.6586,
+        lon: 139.7454,
+        alt: 850,
+        pitch: -25,
+        heading: 0,
+        buildingHeight: 110,
+      },
+      {
+        name: 'Tokyo Skytree',
+        lat: 35.7101,
+        lon: 139.8107,
+        alt: 900,
+        pitch: -25,
+        heading: 30,
+        buildingHeight: 200,
+      },
+      {
+        name: 'Imperial Palace',
+        lat: 35.6852,
+        lon: 139.7528,
+        alt: 900,
+        pitch: -35,
+        heading: 0,
+        buildingHeight: 20,
+      },
+      {
+        name: 'Senso-ji Temple',
+        lat: 35.7148,
+        lon: 139.7967,
+        alt: 400,
+        pitch: -30,
+        heading: 180,
+        buildingHeight: 25,
+      },
+      {
+        name: 'Mode Gakuen Cocoon Tower',
+        lat: 35.6929,
+        lon: 139.6925,
+        alt: 350,
+        pitch: -20,
+        heading: 30,
+        buildingHeight: 70,
+      },
+    ],
+  },
+  london: {
+    name: 'London',
+    groundElevation: 15,
+    viewBounds: {
+      southwest: { lat: 51.28, lng: -0.51 },
+      northeast: { lat: 51.7, lng: 0.33 },
+    },
+    pois: [
+      {
+        name: 'Tower Bridge',
+        lat: 51.5055,
+        lon: -0.0754,
+        alt: 400,
+        pitch: -25,
+        heading: 270,
+        buildingHeight: 65,
+      },
+      {
+        name: 'The Shard',
+        lat: 51.5045,
+        lon: -0.0865,
+        alt: 850,
+        pitch: -20,
+        heading: 0,
+        buildingHeight: 100,
+      },
+      {
+        name: 'Big Ben / Parliament',
+        lat: 51.5007,
+        lon: -0.1246,
+        alt: 600,
+        pitch: -25,
+        heading: 180,
+        buildingHeight: 50,
+      },
+      {
+        name: "St. Paul's Cathedral",
+        lat: 51.5138,
+        lon: -0.0984,
+        alt: 400,
+        pitch: -30,
+        heading: 270,
+        buildingHeight: 55,
+      },
+      {
+        name: 'The Gherkin',
+        lat: 51.5145,
+        lon: -0.0803,
+        alt: 350,
+        pitch: -20,
+        heading: 30,
+        buildingHeight: 60,
+      },
+    ],
+  },
+  paris: {
+    name: 'Paris',
+    groundElevation: 35,
+    viewBounds: {
+      southwest: { lat: 48.815, lng: 2.224 },
+      northeast: { lat: 48.902, lng: 2.47 },
+    },
+    pois: [
+      {
+        name: 'Eiffel Tower',
+        lat: 48.8584,
+        lon: 2.2945,
+        alt: 750,
+        pitch: -25,
+        heading: 315,
+        buildingHeight: 150,
+      },
+      {
+        name: 'Arc de Triomphe',
+        lat: 48.8738,
+        lon: 2.295,
+        alt: 400,
+        pitch: -28,
+        heading: 45,
+        buildingHeight: 25,
+      },
+      {
+        name: 'Notre-Dame',
+        lat: 48.853,
+        lon: 2.3499,
+        alt: 400,
+        pitch: -25,
+        heading: 225,
+        buildingHeight: 35,
+      },
+      {
+        name: 'Sacré-Cœur',
+        lat: 48.8867,
+        lon: 2.3431,
+        alt: 400,
+        pitch: -30,
+        heading: 180,
+        buildingHeight: 40,
+      },
+      {
+        name: 'Louvre Pyramid',
+        lat: 48.8606,
+        lon: 2.3376,
+        alt: 500,
+        pitch: -35,
+        heading: 0,
+        buildingHeight: 10,
+      },
+    ],
+  },
+  dubai: {
+    name: 'Dubai',
+    groundElevation: 5,
+    viewBounds: {
+      southwest: { lat: 24.95, lng: 54.9 },
+      northeast: { lat: 25.35, lng: 55.55 },
+    },
+    pois: [
+      {
+        name: 'Burj Khalifa',
+        lat: 25.1972,
+        lon: 55.2744,
+        alt: 600,
+        pitch: -20,
+        heading: 200,
+        buildingHeight: 270,
+      },
+      {
+        name: 'Burj Al Arab',
+        lat: 25.1412,
+        lon: 55.1853,
+        alt: 500,
+        pitch: -25,
+        heading: 90,
+        buildingHeight: 100,
+      },
+      {
+        name: 'Palm Jumeirah',
+        lat: 25.1124,
+        lon: 55.139,
+        alt: 1200,
+        pitch: -40,
+        heading: 0,
+        buildingHeight: 20,
+      },
+      {
+        name: 'Dubai Frame',
+        lat: 25.235,
+        lon: 55.3003,
+        alt: 400,
+        pitch: -25,
+        heading: 270,
+        buildingHeight: 75,
+      },
+      {
+        name: 'Museum of the Future',
+        lat: 25.2197,
+        lon: 55.2806,
+        alt: 350,
+        pitch: -20,
+        heading: 30,
+        buildingHeight: 35,
+      },
+    ],
+  },
+  dc: {
+    name: 'Washington DC',
+    groundElevation: 10,
+    viewBounds: {
+      southwest: { lat: 38.79, lng: -77.12 },
+      northeast: { lat: 38.995, lng: -76.91 },
+    },
+    pois: [
+      {
+        name: 'US Capitol',
+        lat: 38.8897,
+        lon: -77.0091,
+        alt: 550,
+        pitch: -25,
+        heading: 270,
+        buildingHeight: 45,
+      },
+      {
+        name: 'Washington Monument',
+        lat: 38.8895,
+        lon: -77.0353,
+        alt: 500,
+        pitch: -30,
+        heading: 0,
+        buildingHeight: 85,
+      },
+      {
+        name: 'Lincoln Memorial',
+        lat: 38.8893,
+        lon: -77.0502,
+        alt: 400,
+        pitch: -25,
+        heading: 90,
+        buildingHeight: 20,
+      },
+      {
+        name: 'Pentagon',
+        lat: 38.8711,
+        lon: -77.0559,
+        alt: 800,
+        pitch: -40,
+        heading: 0,
+        buildingHeight: 20,
+      },
+      {
+        name: 'Jefferson Memorial',
+        lat: 38.8814,
+        lon: -77.0365,
+        alt: 400,
+        pitch: -30,
+        heading: 0,
+        buildingHeight: 25,
+      },
+    ],
+  },
+  tallinn: {
+    name: 'Tallinn',
+    groundElevation: 15,
+    viewBounds: {
+      southwest: { lat: 59.36, lng: 24.6 },
+      northeast: { lat: 59.52, lng: 24.92 },
+    },
+    pois: [
+      {
+        name: 'Viru Square',
+        lat: 59.4366,
+        lon: 24.7527,
+        alt: 450,
+        pitch: -28,
+        heading: 60,
+        buildingHeight: 25,
+      },
+      {
+        name: 'Old Town / Raekoja plats',
+        lat: 59.4372,
+        lon: 24.7452,
+        alt: 400,
+        pitch: -30,
+        heading: 180,
+        buildingHeight: 20,
+      },
+      {
+        name: 'Teatri väljak',
+        lat: 59.4344,
+        lon: 24.7514,
+        alt: 400,
+        pitch: -25,
+        heading: 220,
+        buildingHeight: 25,
+      },
+      {
+        name: 'Port of Tallinn',
+        lat: 59.4445,
+        lon: 24.7675,
+        alt: 700,
+        pitch: -30,
+        heading: 90,
+        buildingHeight: 20,
+      },
+      {
+        name: 'Ülemiste',
+        lat: 59.421,
+        lon: 24.792,
+        alt: 600,
+        pitch: -28,
+        heading: 45,
+        buildingHeight: 30,
+      },
+    ],
+  },
+};

src/cityPresets.test.mjs

@@ -0,0 +1,197 @@
+// CITY PRESETS — the destination table, checked as data.
+//
+// CITY_POIS is written by hand and read directly by the camera, so a malformed
+// row is not a crash: the pill lights up, the camera flies, and it frames the
+// wrong thing. These checks are structural. They say a row is well formed —
+// present keys, finite numbers, coordinates on Earth, a camera angle a camera
+// can hold, a landmark inside the rectangle its own destination opens on — and
+// say nothing about whether a destination is framed well.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { CITY_POIS } from './cityPois.js';
+import { LOCATIONS } from './locations.js';
+
+const DESTINATIONS = Object.entries(CITY_POIS);
+const REQUIRED_POI_KEYS = ['name', 'lat', 'lon', 'alt', 'pitch', 'heading'];
+
+/** `id · POI name`, so a failure names the row instead of an index. */
+const where = (id, poi) => `${id} · ${poi.name}`;
+
+/** Longitude folded into [-180, 180]. */
+const wrapLon = (lon) => ((((lon + 180) % 360) + 360) % 360) - 180;
+
+/**
+ * Whether a longitude lies in the west→east span, the way navigation reads it.
+ *
+ * A span that crosses the antimeridian has a west greater than its east
+ * (179 → -179), and everything outside that pair is what falls between them.
+ */
+export function lonWithin(lon, west, east) {
+  const value = wrapLon(lon);
+  const from = wrapLon(west);
+  const to = wrapLon(east);
+  return from <= to
+    ? value >= from && value <= to
+    : value >= from || value <= to;
+}
+
+test('the table is not empty, and every destination offers at least one place', () => {
+  assert.ok(DESTINATIONS.length > 0);
+  for (const [id, city] of DESTINATIONS) {
+    assert.ok(
+      typeof city.name === 'string' && city.name.trim().length > 0,
+      `${id} has no name`,
+    );
+    assert.ok(
+      Array.isArray(city.pois) && city.pois.length > 0,
+      `${id} has no POIs`,
+    );
+  }
+});
+
+test('every POI carries the keys the camera reads', () => {
+  for (const [id, city] of DESTINATIONS) {
+    for (const poi of city.pois) {
+      for (const key of REQUIRED_POI_KEYS) {
+        assert.notEqual(
+          poi[key],
+          undefined,
+          `${where(id, poi)} is missing ${key}`,
+        );
+      }
+      // A blank name reaches the pill as an unlabelled button.
+      assert.ok(
+        typeof poi.name === 'string' && poi.name.trim().length > 0,
+        `${id} has a place with no name`,
+      );
+    }
+  }
+});
+
+test('every coordinate is a finite point on Earth', () => {
+  for (const [id, city] of DESTINATIONS) {
+    for (const poi of city.pois) {
+      assert.ok(
+        Number.isFinite(poi.lat) && Math.abs(poi.lat) <= 90,
+        `${where(id, poi)} lat ${poi.lat}`,
+      );
+      assert.ok(
+        Number.isFinite(poi.lon) && Math.abs(poi.lon) <= 180,
+        `${where(id, poi)} lon ${poi.lon}`,
+      );
+    }
+  }
+});
+
+test('every camera angle is one a camera can hold', () => {
+  for (const [id, city] of DESTINATIONS) {
+    for (const poi of city.pois) {
+      // Looking down, not up and not along the horizon: these are aerial frames.
+      assert.ok(
+        Number.isFinite(poi.pitch) && poi.pitch < 0 && poi.pitch >= -90,
+        `${where(id, poi)} pitch ${poi.pitch}`,
+      );
+      assert.ok(
+        Number.isFinite(poi.heading) && poi.heading >= 0 && poi.heading < 360,
+        `${where(id, poi)} heading ${poi.heading}`,
+      );
+      // A non-finite altitude is a camera at no distance at all.
+      assert.ok(
+        Number.isFinite(poi.alt) && poi.alt > 0,
+        `${where(id, poi)} alt ${poi.alt}`,
+      );
+    }
+  }
+});
+
+test('every viewBounds is a finite rectangle on Earth', () => {
+  for (const [id, city] of DESTINATIONS) {
+    assert.ok(city.viewBounds, `${id} has no viewBounds`);
+    const { southwest: sw, northeast: ne } = city.viewBounds;
+    for (const [corner, point] of [
+      ['southwest', sw],
+      ['northeast', ne],
+    ]) {
+      assert.ok(
+        Number.isFinite(point?.lat) && Math.abs(point.lat) <= 90,
+        `${id} ${corner} lat ${point?.lat}`,
+      );
+      assert.ok(
+        Number.isFinite(point?.lng) && Math.abs(point.lng) <= 180,
+        `${id} ${corner} lng ${point?.lng}`,
+      );
+    }
+    // Swapped latitudes produce an inverted-but-plausible box: the framing code
+    // still runs, and the camera frames nothing. Longitudes are not ordered,
+    // because a span that crosses the antimeridian runs west > east.
+    assert.ok(sw.lat < ne.lat, `${id} viewBounds latitudes are inverted`);
+    assert.notEqual(
+      wrapLon(sw.lng),
+      wrapLon(ne.lng),
+      `${id} viewBounds has no width`,
+    );
+  }
+});
+
+test('every POI lies inside the frame its own destination opens on', () => {
+  // The failure this exists for: a landmark the destination lists but its
+  // overview never shows.
+  for (const [id, city] of DESTINATIONS) {
+    const { southwest: sw, northeast: ne } = city.viewBounds;
+    for (const poi of city.pois) {
+      assert.ok(
+        poi.lat >= sw.lat &&
+          poi.lat <= ne.lat &&
+          lonWithin(poi.lon, sw.lng, ne.lng),
+        `${where(id, poi)} at ${poi.lat}, ${poi.lon} is outside ${id}'s viewBounds`,
+      );
+    }
+  }
+});
+
+test('every LOCATIONS row matches the destination it names', () => {
+  assert.equal(LOCATIONS.length, DESTINATIONS.length);
+  for (const [index, [id, city]] of DESTINATIONS.entries()) {
+    assert.deepEqual(LOCATIONS[index], {
+      id,
+      name: city.name,
+      lat: city.pois[0].lat,
+      lon: city.pois[0].lon,
+    });
+  }
+});
+
+test('containment follows a span across the antimeridian', () => {
+  // No current destination crosses 180°, so the wrapped case is exercised here
+  // rather than left to whoever adds the first one. southwest (-1, 179) to
+  // northeast (1, -179) is a real 2° box straddling the line.
+  const west = 179;
+  const east = -179;
+  assert.equal(lonWithin(179.5, west, east), true);
+  assert.equal(lonWithin(-179.5, west, east), true);
+  assert.equal(lonWithin(180, west, east), true);
+  assert.equal(lonWithin(0, west, east), false);
+  assert.equal(lonWithin(178.9, west, east), false);
+  assert.equal(lonWithin(-178.9, west, east), false);
+  // An ordinary span is unaffected by the wrapping.
+  assert.equal(lonWithin(-97.7, -97.95, -97.55), true);
+  assert.equal(lonWithin(-98.4, -97.95, -97.55), false);
+  // A whole POI checked against a synthetic destination, the way the table
+  // check reads it.
+  const destination = {
+    viewBounds: {
+      southwest: { lat: -1, lng: west },
+      northeast: { lat: 1, lng: east },
+    },
+    pois: [{ name: 'Dateline overlook', lat: 0, lon: 179.5 }],
+  };
+  const { southwest: sw, northeast: ne } = destination.viewBounds;
+  for (const poi of destination.pois) {
+    assert.ok(
+      poi.lat >= sw.lat &&
+        poi.lat <= ne.lat &&
+        lonWithin(poi.lon, sw.lng, ne.lng),
+      'a landmark inside a wrapped view must read as inside',
+    );
+  }
+});

src/cockpitCloudEffects.js

@@ -1,5 +1,10 @@
+import { applicationServices } from './services/application.js';
 import * as Cesium from 'cesium';
-import { deriveWeatherEffectProfile, weatherAltitudeFactors } from './weatherEffectsMath.js';
+import { greatCircleMeters } from './geoDistance.js';
+import {
+  deriveWeatherEffectProfile,
+  weatherAltitudeFactors,
+} from './weatherEffectsMath.js';
 
 const WEATHER_REFRESH_MS = 5 * 60_000;
 const CLOUD_FRAME_MS = 1000 / 12;
@@ -116,28 +121,33 @@ function compileShader(gl, type, source) {
   gl.shaderSource(shader, source);
   gl.compileShader(shader);
   if (gl.getShaderParameter(shader, gl.COMPILE_STATUS)) return shader;
-  const error = gl.getShaderInfoLog(shader) || 'Unknown shader compilation error';
+  const error =
+    gl.getShaderInfoLog(shader) || 'Unknown shader compilation error';
   gl.deleteShader(shader);
   throw new Error(error);
 }
 
 function greatCircleM(a, b) {
-  if (![a?.latitude, a?.longitude, b?.latitude, b?.longitude].every(Number.isFinite)) return Infinity;
-  const latitudeA = Cesium.Math.toRadians(a.latitude);
-  const latitudeB = Cesium.Math.toRadians(b.latitude);
-  const latitudeDelta = Cesium.Math.toRadians(b.latitude - a.latitude);
-  const longitudeDelta = Cesium.Math.toRadians(b.longitude - a.longitude);
-  const haversine = Math.sin(latitudeDelta / 2) ** 2
-    + Math.cos(latitudeA) * Math.cos(latitudeB) * Math.sin(longitudeDelta / 2) ** 2;
-  return 6371000 * 2 * Math.atan2(Math.sqrt(haversine), Math.sqrt(1 - haversine));
+  return greatCircleMeters(
+    { lat: a?.latitude, lon: a?.longitude },
+    { lat: b?.latitude, lon: b?.longitude },
+  );
 }
 
 /** Return whether cockpit weather must refresh for elapsed time or movement. */
-export function cockpitWeatherRefreshDue({ nowMs, fetchedAt, anchor, point, hasWeather }) {
+export function cockpitWeatherRefreshDue({
+  nowMs,
+  fetchedAt,
+  anchor,
+  point,
+  hasWeather,
+}) {
   if (!hasWeather) return true;
   if (!Number.isFinite(nowMs) || !Number.isFinite(fetchedAt)) return true;
-  return nowMs - fetchedAt >= WEATHER_REFRESH_MS
-    || greatCircleM(anchor, point) >= WEATHER_MOVE_REFRESH_M;
+  return (
+    nowMs - fetchedAt >= WEATHER_REFRESH_MS ||
+    greatCircleM(anchor, point) >= WEATHER_MOVE_REFRESH_M
+  );
 }
 
 /** Returns the capped framebuffer size used by the cockpit cloud pass. */
@@ -164,8 +174,9 @@ export function cockpitWeatherEnabledFromStoredValue(value) {
  * Weather-backed volumetric cloud pass that exists only while cockpit mode is
  * active. It owns no Cesium fog/post-process stages and cannot affect map mode.
  */
-export class CockpitCloudEffectsController {
-  constructor(viewer) {
+class CockpitCloudEffectsController {
+  constructor(viewer, { weatherService = applicationServices.weather } = {}) {
+    this.weatherService = weatherService;
     this.viewer = viewer;
     this.canvas = document.createElement('canvas');
     this.canvas.id = 'cockpit-cloud-effects';
@@ -190,18 +201,24 @@ export class CockpitCloudEffectsController {
     this.pending = null;
     this.abort = null;
     this.destroyed = false;
-    this.reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    this.reducedMotion = window.matchMedia(
+      '(prefers-reduced-motion: reduce)',
+    ).matches;
     this.enabled = this.readEnabledPreference();
 
     this.onResize = () => this.resize();
     this.onCockpitMode = (event) => {
-      const active = event?.detail?.active ?? document.body.classList.contains('cockpit-mode');
+      const active =
+        event?.detail?.active ??
+        document.body.classList.contains('cockpit-mode');
       if (active && this.enabled) this.start();
       else this.stop();
     };
     this.onEnabledChange = (event) => {
       const requested = event?.detail?.enabled;
-      this.setEnabled(typeof requested === 'boolean' ? requested : !this.enabled);
+      this.setEnabled(
+        typeof requested === 'boolean' ? requested : !this.enabled,
+      );
     };
     window.addEventListener('resize', this.onResize);
     window.addEventListener('gev:cockpit-mode-changed', this.onCockpitMode);
@@ -220,9 +237,11 @@ export class CockpitCloudEffectsController {
   }
 
   emitEnabledState() {
-    window.dispatchEvent(new CustomEvent('gev:cockpit-weather-state', {
-      detail: { enabled: this.enabled },
-    }));
+    window.dispatchEvent(
+      new CustomEvent('gev:cockpit-weather-state', {
+        detail: { enabled: this.enabled },
+      }),
+    );
   }
 
   setEnabled(enabled) {
@@ -230,7 +249,9 @@ export class CockpitCloudEffectsController {
     this.enabled = next;
     try {
       localStorage.setItem(WEATHER_ENABLED_STORAGE_KEY, next ? '1' : '0');
-    } catch { /* best effort */ }
+    } catch {
+      /* best effort */
+    }
     if (!next) {
       this.stop();
     } else if (document.body.classList.contains('cockpit-mode')) {
@@ -253,7 +274,11 @@ export class CockpitCloudEffectsController {
       if (!gl) throw new Error('WebGL unavailable');
 
       const vertexShader = compileShader(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
-      const fragmentShader = compileShader(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
+      const fragmentShader = compileShader(
+        gl,
+        gl.FRAGMENT_SHADER,
+        FRAGMENT_SHADER,
+      );
       const program = gl.createProgram();
       gl.attachShader(program, vertexShader);
       gl.attachShader(program, fragmentShader);
@@ -261,15 +286,18 @@ export class CockpitCloudEffectsController {
       gl.deleteShader(vertexShader);
       gl.deleteShader(fragmentShader);
       if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
-        throw new Error(gl.getProgramInfoLog(program) || 'Cloud shader link failed');
+        throw new Error(
+          gl.getProgramInfoLog(program) || 'Cloud shader link failed',
+        );
       }
 
       const buffer = gl.createBuffer();
       gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
-      gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
-        -1, -1, 1, -1, -1, 1,
-        -1, 1, 1, -1, 1, 1,
-      ]), gl.STATIC_DRAW);
+      gl.bufferData(
+        gl.ARRAY_BUFFER,
+        new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
+        gl.STATIC_DRAW,
+      );
       const position = gl.getAttribLocation(program, 'position');
       gl.enableVertexAttribArray(position);
       gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
@@ -291,7 +319,8 @@ export class CockpitCloudEffectsController {
   resize() {
     if (!this.gl) return;
     const size = cockpitCloudRenderSize(window.innerWidth, window.innerHeight);
-    if (this.canvas.width === size.width && this.canvas.height === size.height) return;
+    if (this.canvas.width === size.width && this.canvas.height === size.height)
+      return;
     this.canvas.width = size.width;
     this.canvas.height = size.height;
     this.gl.viewport(0, 0, size.width, size.height);
@@ -311,7 +340,13 @@ export class CockpitCloudEffectsController {
   }
 
   start() {
-    if (this.destroyed || !this.enabled || this.frame !== null || this.suspended) return;
+    if (
+      this.destroyed ||
+      !this.enabled ||
+      this.frame !== null ||
+      this.suspended
+    )
+      return;
     if (!this.gl) {
       this.initializeRenderer();
       this.resize();
@@ -351,16 +386,21 @@ export class CockpitCloudEffectsController {
   }
 
   async refresh() {
-    if (this.destroyed || !this.enabled || this.pending || this.suspended
-      || !document.body.classList.contains('cockpit-mode')) {
+    if (
+      this.destroyed ||
+      !this.enabled ||
+      this.pending ||
+      this.suspended ||
+      !document.body.classList.contains('cockpit-mode')
+    ) {
       return this.pending;
     }
     const point = this.cameraPoint();
     if (!point) return null;
     if (
-      this.weather
-      && Date.now() - this.fetchedAt < WEATHER_REFRESH_MS
-      && greatCircleM(this.anchor, point) < WEATHER_MOVE_REFRESH_M
+      this.weather &&
+      Date.now() - this.fetchedAt < WEATHER_REFRESH_MS &&
+      greatCircleM(this.anchor, point) < WEATHER_MOVE_REFRESH_M
     ) {
       this.applyWeather(this.weather, point.altitudeM);
       return this.weather;
@@ -368,15 +408,17 @@ export class CockpitCloudEffectsController {
 
     this.abort?.abort();
     this.abort = new AbortController();
-    const params = new URLSearchParams({
-      latitude: point.latitude.toFixed(5),
-      longitude: point.longitude.toFixed(5),
-    });
-    this.pending = fetch(`/api/weather-effects?${params}`, { signal: this.abort.signal })
-      .then(async (response) => {
-        if (!response.ok) throw new Error(`Cloud weather unavailable (${response.status})`);
-        const payload = await response.json();
-        if (!payload?.weather) throw new Error('Cloud weather observation unavailable');
+    const pending = this.weatherService.getConditions(
+      point.latitude,
+      point.longitude,
+      { signal: this.abort.signal },
+    );
+    const request = this.abort;
+    this.pending = pending
+      .then(async (payload) => {
+        if (this.abort !== request || request.signal.aborted) return null;
+        if (!payload?.weather)
+          throw new Error('Cloud weather observation unavailable');
         this.weather = payload.weather;
         this.fetchedAt = Date.now();
         this.anchor = point;
@@ -385,6 +427,7 @@ export class CockpitCloudEffectsController {
         return payload.weather;
       })
       .catch((error) => {
+        if (request.signal.aborted || this.abort !== request) return;
         if (error?.name !== 'AbortError') {
           this.targetStrength = 0;
           this.canvas.dataset.sourceStatus = 'unavailable';
@@ -392,8 +435,10 @@ export class CockpitCloudEffectsController {
         return null;
       })
       .finally(() => {
-        this.pending = null;
-        this.abort = null;
+        if (this.abort === request) {
+          this.pending = null;
+          this.abort = null;
+        }
       });
     return this.pending;
   }
@@ -401,12 +446,17 @@ export class CockpitCloudEffectsController {
   applyWeather(weather, altitudeM) {
     const profile = deriveWeatherEffectProfile(weather);
     const altitude = weatherAltitudeFactors(altitudeM);
-    this.targetStrength = profile.available ? profile.cloud * altitude.cloud : 0;
+    this.targetStrength = profile.available
+      ? profile.cloud * altitude.cloud
+      : 0;
     this.windDirectionDeg = profile.windDirectionDeg || 0;
     this.windStrength = profile.wind || 0;
     this.canvas.dataset.cloudStrength = this.targetStrength.toFixed(3);
     this.canvas.dataset.weatherCode = String(weather?.weatherCode ?? 'unknown');
-    if (this.reducedMotion && document.body.classList.contains('cockpit-mode')) {
+    if (
+      this.reducedMotion &&
+      document.body.classList.contains('cockpit-mode')
+    ) {
       this.strength = this.targetStrength;
       const visible = this.strength > 0.035;
       this.canvas.classList.toggle('active', visible);
@@ -416,7 +466,11 @@ export class CockpitCloudEffectsController {
   }
 
   tick(timeMs) {
-    if (this.destroyed || !this.enabled || !document.body.classList.contains('cockpit-mode')) {
+    if (
+      this.destroyed ||
+      !this.enabled ||
+      !document.body.classList.contains('cockpit-mode')
+    ) {
       this.stop();
       return;
     }
@@ -433,20 +487,27 @@ export class CockpitCloudEffectsController {
     if (timeMs - this.lastRefreshCheckMs >= 1000) {
       this.lastRefreshCheckMs = timeMs;
       const point = this.cameraPoint();
-      if (point && cockpitWeatherRefreshDue({
-        nowMs: Date.now(),
-        fetchedAt: this.fetchedAt,
-        anchor: this.anchor,
-        point,
-        hasWeather: Boolean(this.weather),
-      })) void this.refresh();
+      if (
+        point &&
+        cockpitWeatherRefreshDue({
+          nowMs: Date.now(),
+          fetchedAt: this.fetchedAt,
+          anchor: this.anchor,
+          point,
+          hasWeather: Boolean(this.weather),
+        })
+      )
+        void this.refresh();
     }
 
     const blend = this.reducedMotion ? 1 : 0.08;
     this.strength += (this.targetStrength - this.strength) * blend;
     const visible = this.strength > 0.035;
     this.canvas.classList.toggle('active', visible);
-    if (visible && (this.reducedMotion || timeMs - this.lastFrameMs >= CLOUD_FRAME_MS)) {
+    if (
+      visible &&
+      (this.reducedMotion || timeMs - this.lastFrameMs >= CLOUD_FRAME_MS)
+    ) {
       this.lastFrameMs = timeMs;
       this.render(timeMs / 1000);
     } else if (!visible) {
@@ -470,9 +531,16 @@ export class CockpitCloudEffectsController {
     const windRadians = Cesium.Math.toRadians(this.windDirectionDeg);
     const windScale = 0.008 + this.windStrength * 0.022;
     gl.useProgram(this.program);
-    gl.uniform2f(this.locations.resolution, this.canvas.width, this.canvas.height);
+    gl.uniform2f(
+      this.locations.resolution,
+      this.canvas.width,
+      this.canvas.height,
+    );
     gl.uniform1f(this.locations.time, timeSec);
-    gl.uniform1f(this.locations.strength, Math.min(1, Math.max(0, this.strength)));
+    gl.uniform1f(
+      this.locations.strength,
+      Math.min(1, Math.max(0, this.strength)),
+    );
     gl.uniform2f(
       this.locations.wind,
       Math.sin(windRadians) * windScale,
@@ -519,12 +587,15 @@ export class CockpitCloudEffectsController {
     this.stop();
     window.removeEventListener('resize', this.onResize);
     window.removeEventListener('gev:cockpit-mode-changed', this.onCockpitMode);
-    window.removeEventListener('gev:cockpit-weather-toggle', this.onEnabledChange);
+    window.removeEventListener(
+      'gev:cockpit-weather-toggle',
+      this.onEnabledChange,
+    );
     if (this.program && this.gl) this.gl.deleteProgram(this.program);
     this.canvas.remove();
   }
 }
 
-export function initCockpitCloudEffects(viewer) {
-  return new CockpitCloudEffectsController(viewer);
+export function initCockpitCloudEffects(viewer, options) {
+  return new CockpitCloudEffectsController(viewer, options);
 }

src/cockpitMath.js

@@ -1,7 +1,18 @@
-/** Normalize a heading into the [0, 360) range. */
-export function normalizeHeading(value) {
-  if (!Number.isFinite(value)) return 0;
-  return ((value % 360) + 360) % 360;
+import {
+  normalizeHeading,
+  roundHeadingDegrees,
+} from './data/headingDegrees.js';
+
+export { resolveHudRailLayout } from './ui/panelRailGeometry.js';
+export { normalizeHeading };
+
+/**
+ * Three-digit heading readout, 000–359.
+ * Rounding 359.5° and above lands on north (000), not 360.
+ */
+export function formatHeadingReadout(degrees) {
+  if (!Number.isFinite(degrees)) return '---';
+  return String(roundHeadingDegrees(degrees)).padStart(3, '0');
 }
 
 /** Advance a displayed heading along the shortest arc without exceeding a slew rate. */
@@ -23,8 +34,13 @@ export function slewHeading(current, target, maxStepDeg) {
  * becoming a first-person surge or reversal while still removing drift.
  */
 export function cockpitAnchorCorrectionStep(distanceM, speedMps, dtSec) {
-  if (!Number.isFinite(distanceM) || distanceM <= 0
-    || !Number.isFinite(dtSec) || dtSec <= 0) return 0;
+  if (
+    !Number.isFinite(distanceM) ||
+    distanceM <= 0 ||
+    !Number.isFinite(dtSec) ||
+    dtSec <= 0
+  )
+    return 0;
   const dt = Math.min(0.1, dtSec);
   const speed = Number.isFinite(speedMps) ? Math.max(0, speedMps) : 0;
   const eased = distanceM * (1 - Math.exp(-1.25 * dt));
@@ -34,14 +50,21 @@ export function cockpitAnchorCorrectionStep(distanceM, speedMps, dtSec) {
 
 /** Return whether a throttled cockpit presentation update is due. */
 export function cockpitUiUpdateDue(nowMs, lastUpdateMs, intervalMs) {
-  if (!Number.isFinite(nowMs) || !Number.isFinite(intervalMs) || intervalMs < 0) return false;
-  if (!Number.isFinite(lastUpdateMs) || lastUpdateMs <= 0 || nowMs < lastUpdateMs) return true;
+  if (!Number.isFinite(nowMs) || !Number.isFinite(intervalMs) || intervalMs < 0)
+    return false;
+  if (
+    !Number.isFinite(lastUpdateMs) ||
+    lastUpdateMs <= 0 ||
+    nowMs < lastUpdateMs
+  )
+    return true;
   return nowMs - lastUpdateMs >= intervalMs;
 }
 
 /** Return whether the bounded rendered-surface acquisition window has elapsed. */
 export function cockpitSurfaceWaitExpired(nowMs, startedMs, timeoutMs = 5000) {
-  if (![nowMs, startedMs, timeoutMs].every(Number.isFinite) || timeoutMs < 0) return true;
+  if (![nowMs, startedMs, timeoutMs].every(Number.isFinite) || timeoutMs < 0)
+    return true;
   return nowMs - startedMs >= timeoutMs;
 }
 
@@ -49,7 +72,11 @@ export function cockpitSurfaceWaitExpired(nowMs, startedMs, timeoutMs = 5000) {
  * Keep the cockpit camera above the shared rendered-surface floor.
  * Unknown floors preserve the proposed camera height.
  */
-export function cockpitGroundSafeHeight(proposedHeightM, groundHeightM, clearanceM) {
+export function cockpitGroundSafeHeight(
+  proposedHeightM,
+  groundHeightM,
+  clearanceM,
+) {
   if (!Number.isFinite(proposedHeightM)) return proposedHeightM;
   if (!Number.isFinite(groundHeightM)) return proposedHeightM;
   const clearance = Number.isFinite(clearanceM) ? Math.max(0, clearanceM) : 0;
@@ -65,37 +92,106 @@ export function cockpitAltitudeDisplayFt(altitudeM, onGround) {
   return Number.isFinite(altitudeM) ? altitudeM * 3.28084 : null;
 }
 
-/** Format the cockpit Context scope without overstating installation coverage. */
-export function formatCockpitContextScope(subjectLabel, radiusM, installationCoverage = null) {
-  const normalizedLabel = typeof subjectLabel === 'string'
-    ? subjectLabel.trim() || '—'
-    : Number.isFinite(subjectLabel) ? String(subjectLabel) : '—';
-  const radiusKm = Number.isFinite(radiusM) && radiusM >= 0
-    ? String(Math.round(radiusM / 1000))
-    : '—';
-  const coverage = typeof installationCoverage === 'string'
-    ? installationCoverage.trim()
-    : '';
-  const base = `${normalizedLabel} · ${radiusKm} KM AIR/SEA WINDOW`;
-  return coverage
-    ? `${base} · INSTALLATIONS ${coverage}`
-    : base;
+/** The English emergency line; see formatCockpitEmergency. */
+const ENGLISH_EMERGENCY = Object.freeze({
+  squawk: ({ squawk, label }) => `SQUAWK ${squawk} · ${label}`,
+  adsb: ({ priority, label }) =>
+    `ADS-B ${priority ? 'PRIORITY' : 'EMERGENCY'} · ${label}`,
+});
+
+/**
+ * HUD wording for a tracked aircraft's transponder emergency, or null.
+ * States what was broadcast, never a conclusion about the flight: the Mode A
+ * code when it names the status, else the ADS-B field it came from (an
+ * unrelated squawk is dropped).
+ * The cockpit passes its own formatter so the page shows it in the active
+ * language; this module stays i18n-free.
+ * @param {{label?: string, squawk?: string|null,
+ *   source?: string, severity?: string}|null|undefined} emergency
+ * @param {{squawk: Function, adsb: Function}} [format] Builds the line from
+ *   `{ name, label, squawk }` and `{ name, label, priority }`, where
+ *   `label` is the upper-cased `name`.
+ * @returns {string|null}
+ */
+export function formatCockpitEmergency(emergency, format = ENGLISH_EMERGENCY) {
+  const label = String(emergency?.label || '')
+    .trim()
+    .toUpperCase();
+  if (!label) return null;
+  const name = String(emergency.label).trim();
+  if (emergency.source === 'squawk' && emergency.squawk)
+    return format.squawk({ name, label, squawk: emergency.squawk });
+  return format.adsb({
+    name,
+    label,
+    priority: emergency.severity === 'priority',
+  });
+}
+
+/** The English Context scope line; see formatCockpitContextScope. */
+const ENGLISH_CONTEXT_SCOPE = Object.freeze({
+  window: ({ label, radiusKm }) =>
+    `${label} · ${radiusKm ?? '—'} KM AIR/SEA WINDOW`,
+  installations: ({ scope, coverage }) =>
+    `${scope} · INSTALLATIONS ${coverage}`,
+});
+
+/**
+ * Format the cockpit Context scope without overstating installation coverage.
+ * @param {string|number} subjectLabel
+ * @param {number} radiusM
+ * @param {string|null} [installationCoverage]
+ * @param {{window: Function, installations: Function}} [format] Builds the
+ *   line from `{ label, radiusKm }` (radiusKm is null when unknown) and
+ *   `{ scope, coverage }`.
+ * @returns {string}
+ */
+export function formatCockpitContextScope(
+  subjectLabel,
+  radiusM,
+  installationCoverage = null,
+  format = ENGLISH_CONTEXT_SCOPE,
+) {
+  const normalizedLabel =
+    typeof subjectLabel === 'string'
+      ? subjectLabel.trim() || '—'
+      : Number.isFinite(subjectLabel)
+        ? String(subjectLabel)
+        : '—';
+  const radiusKm =
+    Number.isFinite(radiusM) && radiusM >= 0
+      ? Math.round(radiusM / 1000)
+      : null;
+  const coverage =
+    typeof installationCoverage === 'string' ? installationCoverage.trim() : '';
+  const base = format.window({ label: normalizedLabel, radiusKm });
+  return coverage ? format.installations({ scope: base, coverage }) : base;
 }
 
 /** Return seven 30-degree compass divisions centered on a heading. */
 export function compassDivisions(heading) {
   const center = Math.round(normalizeHeading(heading) / 30) * 30;
-  return [-90, -60, -30, 0, 30, 60, 90].map((offset) => normalizeHeading(center + offset));
+  return [-90, -60, -30, 0, 30, 60, 90].map((offset) =>
+    normalizeHeading(center + offset),
+  );
 }
 
 /** Format a compass division as a cardinal/intercardinal label or degrees. */
 export function formatCompassDivision(heading) {
   const normalized = normalizeHeading(heading);
   const labels = new Map([
-    [0, 'N'], [45, 'NE'], [90, 'E'], [135, 'SE'],
-    [180, 'S'], [225, 'SW'], [270, 'W'], [315, 'NW'],
+    [0, 'N'],
+    [45, 'NE'],
+    [90, 'E'],
+    [135, 'SE'],
+    [180, 'S'],
+    [225, 'SW'],
+    [270, 'W'],
+    [315, 'NW'],
   ]);
-  return labels.get(normalized) || String(Math.round(normalized)).padStart(3, '0');
+  return (
+    labels.get(normalized) || String(Math.round(normalized)).padStart(3, '0')
+  );
 }
 
 /** Choose a readable altitude-tape interval for the current flight level. */
@@ -188,20 +284,22 @@ export function formatSpeedRulerTick(valueKt) {
 /** Return the initial great-circle bearing between two latitude/longitude points. */
 export function bearingBetweenCoordinates(fromLat, fromLon, toLat, toLon) {
   if (![fromLat, fromLon, toLat, toLon].every(Number.isFinite)) return null;
-  const φ1 = fromLat * Math.PI / 180;
-  const φ2 = toLat * Math.PI / 180;
-  const Δλ = (toLon - fromLon) * Math.PI / 180;
+  const φ1 = (fromLat * Math.PI) / 180;
+  const φ2 = (toLat * Math.PI) / 180;
+  const Δλ = ((toLon - fromLon) * Math.PI) / 180;
   const y = Math.sin(Δλ) * Math.cos(φ2);
-  const x = Math.cos(φ1) * Math.sin(φ2)
-    - Math.sin(φ1) * Math.cos(φ2) * Math.cos(Δλ);
+  const x =
+    Math.cos(φ1) * Math.sin(φ2) - Math.sin(φ1) * Math.cos(φ2) * Math.cos(Δλ);
   if (Math.abs(x) < 1e-12 && Math.abs(y) < 1e-12) return null;
-  return normalizeHeading(Math.atan2(y, x) * 180 / Math.PI);
+  return normalizeHeading((Math.atan2(y, x) * 180) / Math.PI);
 }
 
 /** Return a target bearing relative to the current heading in the [-180, 180) range. */
 export function relativeBearing(bearing, heading) {
   if (!Number.isFinite(bearing) || !Number.isFinite(heading)) return null;
-  return ((normalizeHeading(bearing) - normalizeHeading(heading) + 540) % 360) - 180;
+  return (
+    ((normalizeHeading(bearing) - normalizeHeading(heading) + 540) % 360) - 180
+  );
 }
 
 /**
@@ -227,10 +325,13 @@ export function resolveTrackedAircraftInfo({
   if (civilian) candidates.push({ ...civilian, layerId: 'flights' });
   if (military) candidates.push({ ...military, layerId: 'military' });
   if (!candidates.length) return null;
-  const trackedKey = String(trackedId || '').trim().toLowerCase();
+  const trackedKey = String(trackedId || '')
+    .trim()
+    .toLowerCase();
   if (trackedKey) {
     const owner = candidates.find(
-      (candidate) => `${candidate.layerId}:${candidate.icao24}`.toLowerCase() === trackedKey,
+      (candidate) =>
+        `${candidate.layerId}:${candidate.icao24}`.toLowerCase() === trackedKey,
     );
     if (owner) return owner;
   }
@@ -251,7 +352,10 @@ export function resolveTrackedAircraftInfo({
  *   aircraftRelative: boolean, contactLost: boolean}}
  *   Panel visibility plus the per-field rendering rules for this frame.
  */
-export function resolveCockpitContextReadout({ snapshot = null, info = null } = {}) {
+export function resolveCockpitContextReadout({
+  snapshot = null,
+  info = null,
+} = {}) {
   if (!snapshot) {
     return {
       visible: false,
@@ -262,14 +366,15 @@ export function resolveCockpitContextReadout({ snapshot = null, info = null } =
     };
   }
   const trackedId = info?.icao24 ?? info?.id;
-  const subjectMatchesTracked = snapshot.subject?.layerId === info?.layerId
-    && String(snapshot.subject?.id) === String(trackedId);
+  const subjectMatchesTracked =
+    snapshot.subject?.layerId === info?.layerId &&
+    String(snapshot.subject?.id) === String(trackedId);
   // `subjectPresent` is absent on snapshots built before the presence signal
   // existed; only an explicit `false` means the subject left its source.
   const contactLost = snapshot.subjectPresent === false;
   return {
     visible: true,
-    mode: contactLost ? 'lost' : (subjectMatchesTracked ? 'tracked' : 'foreign'),
+    mode: contactLost ? 'lost' : subjectMatchesTracked ? 'tracked' : 'foreign',
     subjectMatchesTracked,
     // The nose-relative arrow and BRG readout are measured in the tracked
     // aircraft's own frame; every other value in that row is measured from the
@@ -282,45 +387,3 @@ export function resolveCockpitContextReadout({ snapshot = null, info = null } =
     contactLost,
   };
 }
-
-/**
- * Resolve a vertically centered panel slot inside a HUD rail while respecting
- * live rectangles that intersect that rail above or below the viewport center.
- */
-export function resolveHudRailLayout({
-  viewportHeight,
-  panelHeight,
-  laneLeft,
-  laneRight,
-  obstacles = [],
-  baseTop,
-  baseBottom,
-  gap = 12,
-  align = 'center',
-}) {
-  if (![viewportHeight, panelHeight, laneLeft, laneRight, baseTop, baseBottom]
-    .every(Number.isFinite) || viewportHeight <= 0 || laneRight <= laneLeft) return null;
-  const midpoint = viewportHeight * 0.5;
-  let safeTop = Math.max(0, baseTop);
-  let safeBottom = Math.min(viewportHeight, baseBottom);
-
-  for (const rect of obstacles) {
-    if (![rect?.left, rect?.right, rect?.top, rect?.bottom].every(Number.isFinite)) continue;
-    if (rect.right <= laneLeft || rect.left >= laneRight || rect.bottom <= rect.top) continue;
-    if (rect.bottom <= midpoint) safeTop = Math.max(safeTop, rect.bottom + gap);
-    else if (rect.top >= midpoint) safeBottom = Math.min(safeBottom, rect.top - gap);
-  }
-
-  safeBottom = Math.max(safeTop, safeBottom);
-  const availableHeight = Math.max(0, safeBottom - safeTop);
-  const renderedHeight = Math.min(Math.max(0, panelHeight), availableHeight);
-  return {
-    top: align === 'start'
-      ? safeTop
-      : safeTop + Math.max(0, (availableHeight - renderedHeight) * 0.5),
-    maxHeight: availableHeight,
-    safeTop,
-    safeBottom,
-    constrained: panelHeight > availableHeight,
-  };
-}

src/cockpitMath.test.mjs

@@ -13,7 +13,9 @@ import {
   compassDivisions,
   formatAltitudeRulerTick,
   formatCockpitContextScope,
+  formatCockpitEmergency,
   formatCompassDivision,
+  formatHeadingReadout,
   formatSpeedRulerTick,
   normalizeHeading,
   relativeBearing,
@@ -154,6 +156,15 @@ test('compass labels use cardinals where exact and degrees elsewhere', () => {
   assert.equal(formatCompassDivision(30), '030');
 });
 
+test('a heading that rounds to north reads 000, not 360', () => {
+  assert.equal(formatHeadingReadout(359.6), '000');
+  assert.equal(formatHeadingReadout(359.4), '359');
+  assert.equal(formatHeadingReadout(0), '000');
+  assert.equal(formatHeadingReadout(10.2), '010');
+  assert.equal(formatHeadingReadout(-0.6), '359');
+  assert.equal(formatHeadingReadout(Number.NaN), '---');
+});
+
 test('great-circle bearing resolves cardinal directions', () => {
   assert.ok(Math.abs(bearingBetweenCoordinates(0, 0, 1, 0) - 0) < 0.001);
   assert.ok(Math.abs(bearingBetweenCoordinates(0, 0, 0, 1) - 90) < 0.001);
@@ -364,3 +375,21 @@ test('tracked-identity resolution falls back to layer precedence', () => {
   assert.equal(resolveTrackedAircraftInfo({ trackedId: 'flights:aaa077' }), null);
   assert.equal(resolveTrackedAircraftInfo(), null);
 });
+
+test('cockpit emergency wording states the broadcast code, not a conclusion', () => {
+  assert.equal(
+    formatCockpitEmergency({ label: 'General emergency', squawk: '7700', source: 'squawk', severity: 'emergency' }),
+    'SQUAWK 7700 · GENERAL EMERGENCY',
+  );
+  assert.equal(
+    formatCockpitEmergency({ label: 'Downed aircraft', squawk: '1200', source: 'ads-b', severity: 'emergency' }),
+    'ADS-B EMERGENCY · DOWNED AIRCRAFT',
+    'an unrelated squawk is not quoted beside an ADS-B status',
+  );
+  assert.equal(
+    formatCockpitEmergency({ label: 'Minimum fuel', squawk: null, source: 'ads-b', severity: 'priority' }),
+    'ADS-B PRIORITY · MINIMUM FUEL',
+  );
+  assert.equal(formatCockpitEmergency(null), null);
+  assert.equal(formatCockpitEmergency({ label: '' }), null);
+});

src/cockpitSignalFocus.test.mjs

@@ -1,223 +1,393 @@
+// src/cockpitSignalFocus.test.mjs — the Cockpit signal rows keep keyboard
+// focus while they refresh and reorder, over happy-dom with the real view.
+import './testSupport/registerDom.mjs';
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
+import { createPinia } from 'pinia';
+import { createApp, nextTick } from 'vue';
 import { formatAwarenessLabel } from './data/militaryAwarenessEngine.js';
+import { createBriefState } from './ui/cockpitBriefPages.js';
+import {
+  handleSignalClick,
+  publishCockpitSignals,
+  pushCockpitSignal,
+  updateCockpitSignals,
+} from './ui/cockpitSignals.js';
+import { useCockpitStore } from './ui/stores/cockpit.js';
+import CockpitBriefing from './ui/views/panels/CockpitBriefing.vue';
 
-const source = readFileSync(new URL('./ui.js', import.meta.url), 'utf8');
-const renderStart = source.indexOf('  renderCockpitSignals() {');
-const renderEnd = source.indexOf('  setContextCollapsed(', renderStart);
-assert.ok(renderStart >= 0 && renderEnd > renderStart);
-const clickSource = source.match(/this\._listen\(this\.signalList, 'click', (\(event\) => \{[\s\S]*?\n    \})\);/)?.[1];
-assert.ok(clickSource, 'the installed signal click route exists');
-
-// Model native focus loss on removal AND on ordinary DOM moves. Keeping an
-// object reference alone is insufficient if reconciliation disconnects it.
-function fixture() {
-  const document = { activeElement: null };
-  let focusLosses = 0;
-  let focusCalls = 0;
-  class Node {
-    constructor(tagName) {
-      this.tagName = tagName.toUpperCase();
-      this.children = [];
-      this.parentNode = null;
-      this.dataset = {};
-      this.attributes = new Map();
-      this.className = '';
-      this._text = '';
-      this.classList = {
-        add: (...names) => { this.className = [...new Set([...this.className.split(/\s+/).filter(Boolean), ...names])].join(' '); },
-      };
+/**
+ * A browser blurs an element it removes or moves. happy-dom only models the
+ * removal, so count both: any insert or removal of a node that holds focus
+ * is a loss, and a moved node gives its focus up as a browser's would.
+ */
+function trackFocus(t) {
+  const counts = { losses: 0, focusCalls: 0 };
+  const holdsFocus = (node) =>
+    node.isConnected && node.contains(document.activeElement);
+  const insertBefore = Node.prototype.insertBefore;
+  t.mock.method(Node.prototype, 'insertBefore', function (node, anchor) {
+    const lost = holdsFocus(node);
+    const result = insertBefore.call(this, node, anchor);
+    if (lost) {
+      counts.losses += 1;
+      document.activeElement.blur();
     }
-    get isConnected() { return this === document.body || Boolean(this.parentNode?.isConnected); }
-    get firstElementChild() { return this.children[0] || null; }
-    get nextElementSibling() { return this.parentNode?.children[this.parentNode.children.indexOf(this) + 1] || null; }
-    get textContent() { return this._text + this.children.map((node) => node.textContent).join(''); }
-    set textContent(value) { this.replaceChildren(); this._text = String(value); }
-    setAttribute(name, value) { this.attributes.set(name, String(value)); }
-    getAttribute(name) { return this.attributes.get(name) ?? null; }
-    contains(node) { return this === node || this.children.some((child) => child.contains(node)); }
-    append(...nodes) { for (const node of nodes) this.insertBefore(node, null); }
-    insertBefore(node, anchor) {
-      assert.ok(anchor === null || anchor.parentNode === this, 'insert anchor belongs to its parent');
-      if (node === anchor) return node;
-      node.remove();
-      const index = anchor === null ? this.children.length : this.children.indexOf(anchor);
-      this.children.splice(index, 0, node);
-      node.parentNode = this;
-      return node;
-    }
-    remove() {
-      if (!this.parentNode) return;
-      if (this.contains(document.activeElement)) {
-        document.activeElement = document.body;
-        focusLosses += 1;
-      }
-      this.parentNode.children.splice(this.parentNode.children.indexOf(this), 1);
-      this.parentNode = null;
-    }
-    replaceChildren(...nodes) {
-      for (const child of [...this.children]) child.remove();
-      this._text = '';
-      this.append(...nodes);
-    }
-    matches(selector) {
-      if (selector === 'button[data-signal-layer][data-signal-id]') {
-        return this.tagName === 'BUTTON' && this.dataset.signalLayer != null && this.dataset.signalId != null;
-      }
-      return selector.startsWith('.') ? this.className.split(/\s+/).includes(selector.slice(1))
-        : this.tagName === selector.toUpperCase();
-    }
-    closest(selector) {
-      for (let node = this; node; node = node.parentNode) if (node.matches(selector)) return node;
-      return null;
-    }
-    querySelectorAll(selector) {
-      return this.children.flatMap((child) => [ ...(child.matches(selector) ? [child] : []), ...child.querySelectorAll(selector) ]);
-    }
-    focus() {
-      assert.ok(this.isConnected, 'a focus destination must still be connected');
-      focusCalls += 1;
-      document.activeElement = this;
-    }
-  }
-  document.body = new Node('body');
-  document.createElement = (tag) => new Node(tag);
-  document.activeElement = document.body;
-  const controller = new (new Function('document', 'formatAwarenessLabel',
-    `return class { ${source.slice(renderStart, renderEnd)} };`)(document, formatAwarenessLabel))();
-  controller.signalList = new Node('ol');
-  controller.signalToggle = new Node('button');
-  controller.briefTabs = [new Node('button'), new Node('button'), new Node('button')];
-  controller.briefPageIndex = 0;
-  controller.signalItems = [];
-  controller.signalSignatures = new Map();
-  controller.scheduleContextLayout = () => {};
-  const display = new Node('button');
-  const radio = new Node('button');
-  const outside = new Node('button');
-  document.body.append(controller.signalToggle, controller.signalList, ...controller.briefTabs, display, radio, outside);
-  const selected = [];
-  const click = new Function('militaryAwarenessLayer', `return ${clickSource};`)({
-    focusTarget: (...args) => selected.push(args),
+    return result;
   });
-  const buttons = () => controller.signalList.querySelectorAll('button');
+  const removeChild = Node.prototype.removeChild;
+  t.mock.method(Node.prototype, 'removeChild', function (node) {
+    if (holdsFocus(node)) counts.losses += 1;
+    return removeChild.call(this, node);
+  });
+  const focus = HTMLElement.prototype.focus;
+  t.mock.method(HTMLElement.prototype, 'focus', function (...args) {
+    assert.ok(this.isConnected, 'a focus destination must still be connected');
+    counts.focusCalls += 1;
+    return focus.apply(this, args);
+  });
+  return counts;
+}
+
+function fixture(t) {
+  document.body.replaceChildren();
+  const host = document.body.appendChild(document.createElement('div'));
+  const pinia = createPinia();
+  const app = createApp(CockpitBriefing).use(pinia);
+  app.mount(host);
+  const store = useCockpitStore(pinia);
+  const button = () => {
+    const element = document.createElement('button');
+    element.type = 'button';
+    return document.body.appendChild(element);
+  };
+  const display = button();
+  const radio = button();
+  const outside = button();
+  const counts = trackFocus(t);
+  t.after(() => app.unmount());
+  const selected = [];
+  // The signal presenters need only this much of the controller.
+  const owner = {
+    destroyed: false,
+    brief: createBriefState(),
+    signalItems: [],
+    signalSignatures: new Map(),
+    publishSignals: (rows) => store.publishSignals(rows),
+    publishCockpitSignals,
+    scheduleContextLayout() {},
+    services: {
+      formatAwarenessLabel,
+      militaryAwarenessLayer: {
+        focusTarget: (...args) => selected.push(args),
+      },
+    },
+  };
+  // The controller shows the card on entering Cockpit.
+  document.getElementById('cockpit-signal-stream').hidden = false;
+  const list = document.getElementById('cockpit-signal-list');
+  list.addEventListener('click', (event) =>
+    handleSignalClick.call(owner, event),
+  );
+  const buttons = () => [...list.querySelectorAll('button')];
+  // Tab visits the enabled buttons no hidden ancestor removes from view.
   const tab = () => {
-    const nodes = document.body.querySelectorAll('button');
-    const index = nodes.indexOf(document.activeElement);
-    nodes[(index + 1) % nodes.length].focus();
+    const nodes = [...document.querySelectorAll('button')].filter(
+      (node) => !node.disabled && !node.closest('[hidden]'),
+    );
+    nodes[(nodes.indexOf(document.activeElement) + 1) % nodes.length].focus();
+  };
+  const pageTab = (index) =>
+    document.querySelector(`[data-cockpit-brief-index="${index}"]`);
+  const signalTab = () => pageTab(0);
+  return {
+    owner,
+    list,
+    buttons,
+    display,
+    radio,
+    outside,
+    selected,
+    tab,
+    pageTab,
+    signalTab,
+    store,
+    losses: () => counts.losses,
+    focusCalls: () => counts.focusCalls,
   };
-  return { controller, document, buttons, display, radio, outside, selected, click, tab,
-    losses: () => focusLosses, focusCalls: () => focusCalls };
 }
 
 const item = (id, overrides = {}) => ({
-  key: `flight:flights:${id}`, tone: 'nearby', title: `Flight ${id}`, detail: 'COMMERCIAL FLIGHT · 2 KM',
-  target: { layerId: 'flights', id }, timestamp: 1_700_000_000_000, ...overrides,
+  key: `flight:flights:${id}`,
+  tone: 'nearby',
+  title: `Flight ${id}`,
+  detail: 'COMMERCIAL FLIGHT · 2 KM',
+  target: { layerId: 'flights', id },
+  timestamp: 1_700_000_000_000,
+  ...overrides,
 });
-const render = (f, items) => { f.controller.signalItems = items; f.controller.renderCockpitSignals(); };
+const render = async (f, items) => {
+  f.owner.signalItems = items;
+  publishCockpitSignals.call(f.owner);
+  await nextTick();
+};
+const refresh = async (f, distanceM) => {
+  updateCockpitSignals.call(f.owner, snapshot(distanceM), 0);
+  await nextTick();
+};
 const snapshot = (distanceM = 2000) => ({
   evaluatedAt: 1_700_000_000_000,
   subject: { layerId: 'flights', id: 'current', label: 'CURRENT' },
-  cohorts: [{ id: 'flights', count: 1, nearest: [{ id: 'nearby', label: 'NEARBY', distanceM }] }],
+  cohorts: [
+    {
+      id: 'flights',
+      count: 1,
+      nearest: [{ id: 'nearby', label: 'NEARBY', distanceM }],
+    },
+  ],
 });
 
-test('actual Context refresh retains the focused signal button across unchanged and changed details', () => {
-  const f = fixture();
-  f.controller.updateCockpitSignals(snapshot(), 0);
-  const target = f.buttons()[1]; target.focus();
+test('rows render the signals the controller presents', async (t) => {
+  const f = fixture(t);
+  await render(f, [
+    item('a'),
+    item('status', { tone: 'warning', target: null, title: 'UNKNOWN' }),
+  ]);
+  const [action, status] = f.list.children;
+  assert.equal(action.className, 'nearby actionable');
+  assert.equal(action.querySelector('time').textContent, '22:13:20Z');
+  const button = action.querySelector('button.cockpit-signal-target');
+  assert.equal(button.type, 'button');
+  assert.equal(button.dataset.signalLayer, 'flights');
+  assert.equal(button.dataset.signalId, 'a');
+  assert.equal(button.getAttribute('aria-label'), 'Select flight Flight a');
+  assert.equal(
+    button.querySelector('.cockpit-signal-target-label').textContent,
+    'Flight a',
+  );
+  assert.equal(
+    button.querySelector('.cockpit-signal-target-chevron').textContent,
+    'chevron_right',
+  );
+  assert.equal(
+    action.querySelector('div > span').textContent,
+    'COMMERCIAL FLIGHT · 2 KM',
+  );
+  assert.equal(status.className, 'warning');
+  assert.equal(status.querySelector('div > strong').textContent, 'UNKNOWN');
+  assert.equal(status.querySelector('button'), null);
+});
+
+test('actual Context refresh retains the focused signal button across unchanged and changed details', async (t) => {
+  const f = fixture(t);
+  await refresh(f);
+  const target = f.buttons()[1];
+  target.focus();
   const calls = f.focusCalls();
-  for (let tick = 0; tick < 8; tick += 1) f.controller.updateCockpitSignals(snapshot(2500), 0);
-  assert.equal(f.buttons()[1], target);
-  assert.equal(f.document.activeElement, target);
+  for (let tick = 0; tick < 8; tick += 1) await refresh(f, 2500);
+  assert.equal(f.buttons()[1] === target, true);
+  assert.equal(document.activeElement === target, true);
   assert.equal(f.losses(), 0);
-  assert.equal(f.focusCalls(), calls, 'refresh must preserve focus without repeatedly restoring it');
-  assert.match(f.controller.signalList.textContent, /2\.5 KM/);
+  assert.equal(
+    f.focusCalls(),
+    calls,
+    'refresh must preserve focus without repeatedly restoring it',
+  );
+  assert.match(f.list.textContent, /2\.5\u00a0KM/);
 });
 
-test('signal content and accessible name update without replacing the active target', () => {
-  const f = fixture(); render(f, [item('a')]);
-  const target = f.buttons()[0]; target.focus();
-  render(f, [item('a', { title: 'RENAMED', tone: 'track', detail: 'CURRENT', timestamp: 1_700_000_001_000 })]);
-  assert.equal(f.buttons()[0], target);
+test('signal content and accessible name update without replacing the active target', async (t) => {
+  const f = fixture(t);
+  await render(f, [item('a')]);
+  const target = f.buttons()[0];
+  target.focus();
+  await render(f, [
+    item('a', {
+      title: 'RENAMED',
+      tone: 'track',
+      detail: 'CURRENT',
+      timestamp: 1_700_000_001_000,
+    }),
+  ]);
+  assert.equal(f.buttons()[0] === target, true);
   assert.equal(target.getAttribute('aria-label'), 'Select flight RENAMED');
   assert.match(target.textContent, /RENAMED/);
-  assert.match(f.controller.signalList.textContent, /CURRENT/);
-  assert.equal(f.controller.signalList.children[0].className, 'track actionable');
-  assert.equal(f.document.activeElement, target);
+  assert.match(f.list.textContent, /CURRENT/);
+  assert.equal(f.list.children[0].className, 'track actionable');
+  assert.equal(document.activeElement === target, true);
   assert.equal(f.losses(), 0);
 });
 
-test('signal ranking changes move surrounding rows without disconnecting the focused row', () => {
-  const f = fixture(); render(f, ['a', 'b', 'c', 'd'].map((id) => item(id)));
-  const target = f.buttons()[1]; target.focus();
+test('signal ranking changes move surrounding rows without disconnecting the focused row', async (t) => {
+  const f = fixture(t);
+  await render(
+    f,
+    ['a', 'b', 'c', 'd'].map((id) => item(id)),
+  );
+  const target = f.buttons()[1];
+  target.focus();
   const calls = f.focusCalls();
-  for (const order of [['d', 'c', 'b', 'a'], ['b', 'c', 'd', 'a'], ['a', 'd', 'c', 'b']]) {
-    render(f, order.map((id) => item(id)));
-    assert.deepEqual(f.buttons().map((button) => button.dataset.signalId), order);
-    assert.equal(f.document.activeElement, target);
+  for (const order of [
+    ['d', 'c', 'b', 'a'],
+    ['b', 'c', 'd', 'a'],
+    ['a', 'd', 'c', 'b'],
+    ['c', 'a', 'b', 'd'],
+    ['b', 'a', 'd', 'c'],
+  ]) {
+    await render(
+      f,
+      order.map((id) => item(id)),
+    );
+    assert.deepEqual(
+      f.buttons().map((button) => button.dataset.signalId),
+      order,
+    );
+    assert.equal(document.activeElement === target, true);
     assert.equal(f.losses(), 0);
   }
   assert.equal(f.focusCalls(), calls);
 });
 
-test('a new pushed signal preserves existing focus and delegated selection reads the current target', () => {
-  const f = fixture(); render(f, [item('a'), item('b')]);
-  const target = f.buttons()[1]; target.focus();
-  f.controller.pushCockpitSignal('status', 'warning', 'INPUT UNKNOWN', 'SOURCE UNAVAILABLE');
-  assert.equal(f.document.activeElement, target);
+test('a new pushed signal preserves existing focus and delegated selection reads the current target', async (t) => {
+  const f = fixture(t);
+  await render(f, [item('a'), item('b')]);
+  const target = f.buttons()[1];
+  target.focus();
+  pushCockpitSignal.call(
+    f.owner,
+    'status',
+    'warning',
+    'INPUT UNKNOWN',
+    'SOURCE UNAVAILABLE',
+  );
+  await nextTick();
+  assert.equal(f.list.children.length, 3);
+  assert.equal(document.activeElement === target, true);
   assert.equal(f.losses(), 0);
-  const event = { target: target.children[0], prevented: false, preventDefault() { this.prevented = true; } };
-  f.click(event);
-  assert.equal(event.prevented, true);
+  const click = new MouseEvent('click', { bubbles: true, cancelable: true });
+  target.querySelector('.cockpit-signal-target-label').dispatchEvent(click);
+  assert.equal(click.defaultPrevented, true);
   assert.deepEqual(f.selected, [['flights', 'b', { origin: 'user' }]]);
 });
 
-test('removing the focused identity uses the existing briefing tab once and permits forward traversal', () => {
-  const f = fixture(); render(f, [item('a'), item('b')]);
-  const removed = f.buttons()[1]; removed.focus();
+test('removing the focused identity uses the shown briefing tab once and permits forward traversal', async (t) => {
+  const f = fixture(t);
+  await render(f, [item('a'), item('b')]);
+  const removed = f.buttons()[1];
+  removed.focus();
   const calls = f.focusCalls();
-  render(f, [item('a')]);
+  await render(f, [item('a')]);
   assert.equal(removed.isConnected, false);
-  assert.equal(f.document.activeElement, f.controller.briefTabs[0]);
+  assert.equal(document.activeElement === f.signalTab(), true);
   assert.equal(f.focusCalls(), calls + 1);
-  f.tab(); f.tab(); f.tab();
-  assert.equal(f.document.activeElement, f.display);
-  render(f, [item('a', { detail: 'UPDATED' })]);
-  assert.equal(f.document.activeElement, f.display, 'later refresh must not pull focus back');
+  assert.equal(f.losses(), 0);
+  assert.equal(f.signalTab().closest('[hidden]'), null);
+  // Traversal carries on forward from the footer tab.
   f.tab();
-  assert.equal(f.document.activeElement, f.radio);
+  assert.equal(document.activeElement === f.pageTab(1), true);
+  while (document.activeElement !== f.display) f.tab();
+  await render(f, [item('a', { detail: 'UPDATED' })]);
+  assert.equal(
+    document.activeElement === f.display,
+    true,
+    'later refresh must not pull focus back',
+  );
+  f.tab();
+  assert.equal(document.activeElement === f.radio, true);
 });
 
-test('a changed target cannot reuse a focused action for another flight', () => {
-  const f = fixture(); render(f, [item('a', { key: 'shared-status-key' })]);
-  const removed = f.buttons()[0]; removed.focus();
-  render(f, [item('b', { key: 'shared-status-key', target: { layerId: 'military', id: 'b' } })]);
+test('a changed target cannot reuse a focused action for another flight', async (t) => {
+  const f = fixture(t);
+  await render(f, [item('a', { key: 'shared-status-key' })]);
+  const removed = f.buttons()[0];
+  removed.focus();
+  await render(f, [
+    item('b', {
+      key: 'shared-status-key',
+      target: { layerId: 'military', id: 'b' },
+    }),
+  ]);
   const target = f.buttons()[0];
-  assert.notEqual(target, removed);
+  assert.equal(target === removed, false);
   assert.equal(removed.isConnected, false);
-  assert.equal(f.document.activeElement, f.controller.briefTabs[0]);
-  f.click({ target, preventDefault() {} });
+  assert.equal(document.activeElement === f.signalTab(), true);
+  target.click();
   assert.deepEqual(f.selected, [['military', 'b', { origin: 'user' }]]);
 });
 
-test('empty, informational and duplicate-key rows have no stale or aliased actions', () => {
-  const f = fixture();
-  render(f, [item('a'), item('a')]);
+test('empty, informational and duplicate-key rows have no stale or aliased actions', async (t) => {
+  const f = fixture(t);
+  await render(f, [item('a'), item('a')]);
   const [first, second] = f.buttons();
-  assert.notEqual(first, second);
+  assert.equal(first === second, false);
   second.focus();
-  render(f, [item('a'), item('a')]);
-  assert.deepEqual(f.buttons(), [first, second]);
-  assert.equal(f.document.activeElement, second);
-  render(f, [item('status', { target: null, title: 'UNKNOWN' })]);
+  await render(f, [item('a'), item('a')]);
+  const again = f.buttons();
+  assert.equal(again[0] === first && again[1] === second, true);
+  assert.equal(document.activeElement === second, true);
+  await render(f, [item('status', { target: null, title: 'UNKNOWN' })]);
   assert.equal(f.buttons().length, 0);
-  assert.match(f.controller.signalList.textContent, /UNKNOWN/);
-  assert.equal(f.document.activeElement, f.controller.briefTabs[0]);
+  assert.match(f.list.textContent, /UNKNOWN/);
+  assert.equal(document.activeElement === f.signalTab(), true);
   f.outside.focus();
-  render(f, []);
-  assert.equal(f.controller.signalList.children.length, 0);
-  render(f, [item('a')]);
-  assert.notEqual(f.buttons()[0], first);
-  assert.equal(f.document.activeElement, f.outside);
+  await render(f, []);
+  assert.equal(f.list.children.length, 0);
+  await render(f, [item('a')]);
+  assert.equal(f.buttons()[0] === first, false);
+  assert.equal(document.activeElement === f.outside, true);
+  assert.equal(f.losses(), 0);
+});
+
+test('any reordering of five rows keeps focus wherever it sits', async (t) => {
+  const f = fixture(t);
+  const ids = ['a', 'b', 'c', 'd', 'e'];
+  // A fixed pseudo-random sequence, so a failure reproduces.
+  let seed = 7;
+  const random = () => {
+    seed = (seed * 48271) % 2147483647;
+    return seed / 2147483647;
+  };
+  const shuffle = (list) => {
+    const next = [...list];
+    for (let index = next.length - 1; index > 0; index -= 1) {
+      const swap = Math.floor(random() * (index + 1));
+      [next[index], next[swap]] = [next[swap], next[index]];
+    }
+    return next;
+  };
+  await render(
+    f,
+    ids.map((id) => item(id)),
+  );
+  for (let round = 0; round < 60; round += 1) {
+    const target = f.buttons()[round % ids.length];
+    target.focus();
+    const order = shuffle(ids);
+    await render(
+      f,
+      order.map((id) => item(id)),
+    );
+    assert.deepEqual(
+      f.buttons().map((button) => button.dataset.signalId),
+      order,
+    );
+    assert.equal(document.activeElement === target, true);
+  }
+  assert.equal(f.losses(), 0);
+});
+
+test('the fallback follows the shown page, and the collapse toggle without tabs', async (t) => {
+  const f = fixture(t);
+  f.store.publishBrief({ ...createBriefState(), pageIndex: 2 });
+  await render(f, [item('a'), item('b')]);
+  f.buttons()[1].focus();
+  await render(f, [item('a')]);
+  assert.equal(document.activeElement === f.pageTab(2), true);
+  for (const index of [0, 1, 2]) f.pageTab(index).remove();
+  f.buttons()[0].focus();
+  await render(f, []);
+  assert.equal(
+    document.activeElement === document.getElementById('cockpit-signal-toggle'),
+    true,
+  );
 });

src/cockpitTracking.js

@@ -8,7 +8,11 @@
  */
 
 /** Force the prior aircraft layer to reacquire Cesium and durable tracking ownership. */
-export function restoreAircraftTrackingOwner(layer, id, { origin = 'programmatic' } = {}) {
+export function restoreAircraftTrackingOwner(
+  layer,
+  id,
+  { origin = 'programmatic' } = {},
+) {
   if (!layer?.trackById || !id) return false;
   layer.stopTracking?.({ origin });
   return Boolean(layer.trackById(id, { origin }));
@@ -33,11 +37,13 @@ export function enterCockpitWithTracking({
   rollbackTarget = undefined,
   selectionOrigin = 'programmatic',
 }) {
-  const currentTarget = aircraftTrackingTarget(cockpitView?.readAircraftInfo?.());
-  const restoreTarget = rollbackTarget === undefined ? currentTarget : rollbackTarget;
-  const key = (target) => target?.layerId && target?.id
-    ? `${target.layerId}:${target.id}`
-    : null;
+  const currentTarget = aircraftTrackingTarget(
+    cockpitView?.readAircraftInfo?.(),
+  );
+  const restoreTarget =
+    rollbackTarget === undefined ? currentTarget : rollbackTarget;
+  const key = (target) =>
+    target?.layerId && target?.id ? `${target.layerId}:${target.id}` : null;
   let activeLayer = currentLayer;
   let activeTarget = currentTarget;
   let entryError = null;
@@ -49,8 +55,14 @@ export function enterCockpitWithTracking({
     if (selectingTarget) {
       activeLayer = selectedLayer;
       activeTarget = selectedTarget;
-      if (!selectedLayer.trackById?.(selectedTarget.id, { origin: selectionOrigin })) {
-        entryError = new Error('Selected aircraft could not be tracked for Cockpit entry');
+      if (
+        !selectedLayer.trackById?.(selectedTarget.id, {
+          origin: selectionOrigin,
+        })
+      ) {
+        entryError = new Error(
+          'Selected aircraft could not be tracked for Cockpit entry',
+        );
       }
     }
     if (!entryError) entered = Boolean(cockpitView.enter());
@@ -66,12 +78,15 @@ export function enterCockpitWithTracking({
       // programmatic rollback would fix the camera while leaving the failed
       // target durable in local/share state.
       activeLayer?.stopTracking?.({ origin: selectionOrigin });
-      if (restoreTarget && !restoreAircraftTrackingOwner(
-        rollbackLayer,
-        restoreTarget.id,
-        { origin: selectionOrigin },
-      )) {
-        entryError ||= new Error('Prior aircraft tracking could not be restored');
+      if (
+        restoreTarget &&
+        !restoreAircraftTrackingOwner(rollbackLayer, restoreTarget.id, {
+          origin: selectionOrigin,
+        })
+      ) {
+        entryError ||= new Error(
+          'Prior aircraft tracking could not be restored',
+        );
       }
     } catch (error) {
       entryError ||= error instanceof Error ? error : new Error(String(error));
@@ -87,6 +102,8 @@ export function enterCockpitWithTracking({
 
   return {
     entered,
-    error: entered ? null : entryError?.message || 'Cockpit entry was unavailable',
+    error: entered
+      ? null
+      : entryError?.message || 'Cockpit entry was unavailable',
   };
 }