Merge remote-tracking branch 'upstream/main' into feature/catalonia-cctv-cameras

# Conflicts:
#	.env.example
#	DATA_SOURCES.md
#	docs/CURRENT-STATE.md
#	scripts/format-scope.json
#	server/providers/cctv/constants.js
#	server/providers/cctv/sources.js
#	src/data/dataCredits.js

src/data/adminBoundaries.js

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

src/data/aisLiveVessels.analyst.test.mjs

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

src/data/aisLiveVessels.js

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

src/data/aisLiveVessels.test.mjs

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

src/data/aisWatchdog.js

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

src/data/bundledJson.js

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

src/data/bundledJson.test.mjs

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

src/data/cctvCatalogCap.test.mjs

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

src/data/cctvVegvesen.test.mjs

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

src/data/dataCredits.js

@@ -248,6 +248,13 @@ export const DATA_CREDITS = [
       '(Llicència oberta d’ús d’informació - Catalunya); some cameras are supplied by partners ' +
       '(Ajuntament de Barcelona, Ajuntament de Terrassa), each named in the CCTV panel',
   },
+  {
+    key: 'vegvesen-cctv',
+    html:
+      'Road cameras (Norway): contains data under the ' +
+      '<a href="https://data.norge.no/nlod/en/2.0" target="_blank" rel="noopener">Norwegian licence for Open Government data (NLOD)</a> ' +
+      'distributed by Statens vegvesen',
+  },
   {
     key: 'gbfs',
     html: 'Bikeshare availability: GBFS operator feeds (e.g. Austin BCycle)',

src/data/flights.js

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

src/data/flights.test.mjs

@@ -203,7 +203,7 @@ test('flights poll refreshes tracked callsign/FL/kts and marks a missed poll STA
   const nowSec = Math.floor(Date.now() / 1000);
   let openskyPoll = 0;
   globalThis.fetch = async (url) => {
-    if (!String(url).startsWith('/api/opensky')) {
+    if (!String(url).startsWith('/api/flights')) {
       return { ok: true, status: 200, json: async () => ({ ac: [] }) };
     }
     const states = openskyPoll++ === 0

src/data/infrastructure.js

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

src/data/infrastructure.test.mjs

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

src/data/layerState.js

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

src/data/layerState.test.mjs

@@ -11,7 +11,6 @@ import {
   LAYER_STATE_STORAGE_KEY,
   LAYER_STATE_TOKEN_ALPHABET,
   LAYER_STATE_TOKEN_RESERVATIONS,
-  LayerStateCoordinator,
   REGISTERED_LAYER_IDS,
   SHARE_TRACKING_RESTORE_POLICIES,
   createDefaultLayerState,
@@ -24,6 +23,7 @@ import {
   validateLayerStateAllocations,
   validateLayerStateRegistry,
 } from './layerState.js';
+import { LayerStateCoordinator } from './layerStateCoordinator.js';
 import radioLayer from './radio.js';
 import { stampInitialShareGesture } from '../navigationPolicy.js';
 

src/data/layerStateCoordinator.js

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

src/data/localGeojsonCore.js

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

src/data/militaryAwareness.test.mjs

@@ -476,7 +476,7 @@ test('pending mapped installations render as unknown instead of a false zero', a
 // the dependencies reach it by different routes:
 //
 //   - ais-live-vessels is its REACHABLE producer. enable()/update() both resolve
-//     as soon as the first /api/ais-live poll answers, so the manager's
+//     as soon as the first /api/vessels poll answers, so the manager's
 //     lifecycle settles to `enabled` — but until the server-side socket delivers
 //     a position, firstConnectPhase stays 'loading' and the module reports busy,
 //     no lastUpdate, count 0, and an UNDEFINED status, so the status list alone

src/data/militaryFlights.js

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

src/data/militaryFlights.test.mjs

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

src/data/militaryNames.js

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

src/data/militaryNames.test.mjs

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

src/data/militaryRegistry.js

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

src/data/naturalEarthRegions.js

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

src/data/neighborhoodPolygons.js

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

src/data/tr3bRegistry.test.mjs

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