Merge branch 'main' into feat/lithuania-cctv

src/data/adminBoundaries.js

@@ -0,0 +1,803 @@
+/**
+ * Bundled administrative boundaries — countries and states/provinces (Natural
+ * Earth admin-0/admin-1) and US counties (US Census Bureau cartographic boundaries),
+ * so "outline Texas", "outline Bavaria" or "outline Travis County" draws the
+ * real boundary without a network lookup.
+ *
+ * Data: `local_data/natural_earth/{countries,states_provinces}.json` and
+ * `local_data/us_census_counties/counties.json`, public domain and built
+ * by `scripts/build-admin-packs.mjs` (provenance in each folder's README).
+ * Rings are delta-encoded integers; see `decodeRing`.
+ *
+ * PURE data module — no Cesium, node-testable. Each pack is fetched through
+ * `loadBundledJson` on the first lookup that needs it (never at app start),
+ * indexed once, and kept; a failed load is retried later rather than cached
+ * (`createRetryableLoader`). The county pack is only loaded for asks that
+ * name a county (or a county-equivalent city) or that a geocoder typed as one.
+ *
+ * Two entry points:
+ *   - `findAdminArea(query, { near })` — name-only. Resolves asks that are
+ *     unambiguous from the words alone ("Texas", "TX", "State of Texas",
+ *     "Bavaria", "Travis County, Texas", "Orleans Parish"); duplicates are
+ *     settled by a state/country qualifier, then by the camera (`near`).
+ *     Country/state homonyms such as Georgia use the qualifier or camera;
+ *     city/state homonyms such as New York still defer to the geocoder.
+ *   - `findAdminAreaAt(names, lat, lon, scope)` — geocoder-confirmed. The
+ *     geocoder already typed the place as a country, state or county; the unit must
+ *     carry one of the names AND contain the geocoded point.
+ */
+
+import { loadBundledJson } from './bundledJson.js';
+import { createRetryableLoader } from './retryableLoad.js';
+
+const FOLD = {
+  ß: 'ss',
+  ø: 'o',
+  æ: 'ae',
+  ł: 'l',
+  đ: 'd',
+  ı: 'i',
+  œ: 'oe',
+  þ: 'th',
+};
+
+/** Fold a name for matching: case, accents, punctuation, "the", "saint". */
+export function normalizeAdminName(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[ßøæłđıœþ]/g, (c) => FOLD[c])
+    .normalize('NFD')
+    .replace(/\p{M}/gu, '')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .replace(/^the /, '')
+    .replace(/\bsaint\b/g, 'st')
+    .replace(/\bsainte\b/g, 'ste');
+}
+
+const PACKS = {
+  countries: {
+    url: new URL('./local_data/natural_earth/countries.json', import.meta.url),
+  },
+  admin1: {
+    url: new URL(
+      './local_data/natural_earth/states_provinces.json',
+      import.meta.url,
+    ),
+  },
+  counties: {
+    url: new URL(
+      './local_data/us_census_counties/counties.json',
+      import.meta.url,
+    ),
+  },
+};
+
+/** Test seam: count pack loads (lazy-loading contract). */
+export const packLoads = { admin1: 0, counties: 0, countries: 0 };
+
+const EARTH_RADIUS_KM = 6371;
+const toRad = (d) => (d * Math.PI) / 180;
+
+/** Spherical ring area (km²) — same formula as naturalEarthRegions.js. */
+function ringAreaKm2(ring) {
+  const n = ring.length;
+  if (n < 3) return 0;
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    const [lon1, lat1] = ring[i];
+    const [lon2, lat2] = ring[(i + 1) % n];
+    sum +=
+      toRad(lon2 - lon1) * (2 + Math.sin(toRad(lat1)) + Math.sin(toRad(lat2)));
+  }
+  return Math.abs((sum * EARTH_RADIUS_KM * EARTH_RADIUS_KM) / 2);
+}
+
+function haversineKm(lat1, lon1, lat2, lon2) {
+  const dLat = toRad(lat2 - lat1);
+  const dLon = toRad(lon2 - lon1);
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+
+/**
+ * Decode one packed ring: integers in units of 10^-decimals degrees, the
+ * first vertex absolute and each later one a delta from the previous.
+ * @param {number[]} encoded
+ * @param {number} decimals
+ * @returns {Array<[number, number]>} open ring of [lon, lat]
+ */
+export function decodeRing(encoded, decimals) {
+  const factor = 10 ** decimals;
+  const ring = [];
+  let x = 0;
+  let y = 0;
+  for (let i = 0; i + 1 < encoded.length; i += 2) {
+    x += encoded[i];
+    y += encoded[i + 1];
+    ring.push([x / factor, y / factor]);
+  }
+  return ring;
+}
+
+/** Even-odd point-in-ring test; ring is [[lon, lat], …], open or closed. */
+export function pointInRing(ring, lat, lon) {
+  if (!Array.isArray(ring) || ring.length < 3) return false;
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i, i += 1) {
+    const [xi, yi] = ring[i];
+    const [xj, yj] = ring[j];
+    if (
+      yi > lat !== yj > lat &&
+      lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi
+    )
+      inside = !inside;
+  }
+  return inside;
+}
+
+/**
+ * Whether polygons ([outer, ...holes][]) contain the point: inside an outer
+ * ring and not inside any of that part's holes.
+ */
+export function polygonsContain(polygons, lat, lon) {
+  for (const [outer, ...holes] of polygons || []) {
+    if (!pointInRing(outer, lat, lon)) continue;
+    if (!holes.some((hole) => pointInRing(hole, lat, lon))) return true;
+  }
+  return false;
+}
+
+/**
+ * A unit's geometry, decoded on first use. Longitudes are unwrapped around
+ * the largest part for the box so units cut at the antimeridian (Alaska,
+ * Chukotka) get a box on the right side of the globe.
+ */
+function geometryOf(entry) {
+  if (entry.geometry) return entry.geometry;
+  const decimals = entry.feature.d ?? entry.decimals;
+  const polygons = entry.feature.polygons.map((poly) =>
+    poly.map((ring) => decodeRing(ring, decimals)),
+  );
+  const ref = polygons[0]?.[0]?.[0]?.[0] ?? 0;
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  let areaKm2 = 0;
+  for (const [outer, ...holes] of polygons) {
+    areaKm2 += ringAreaKm2(outer);
+    for (const hole of holes) areaKm2 -= ringAreaKm2(hole);
+    for (const [lon, lat] of outer) {
+      const x = lon - 360 * Math.round((lon - ref) / 360);
+      if (x < west) west = x;
+      if (x > east) east = x;
+      if (lat < south) south = lat;
+      if (lat > north) north = lat;
+    }
+  }
+  const label = entry.feature.label
+    ? { lon: entry.feature.label[0], lat: entry.feature.label[1] }
+    : ringCentroid(polygons[0][0]);
+  entry.geometry = {
+    polygons,
+    bbox: [west, south, east, north],
+    areaKm2: Math.max(0, areaKm2),
+    label,
+  };
+  return entry.geometry;
+}
+
+/** Area-weighted centroid of an open ring (planar; fine at unit scale). */
+function ringCentroid(ring) {
+  let a = 0;
+  let cx = 0;
+  let cy = 0;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const [x0, y0] = ring[j];
+    const [x1, y1] = ring[i];
+    const f = x0 * y1 - x1 * y0;
+    a += f;
+    cx += (x0 + x1) * f;
+    cy += (y0 + y1) * f;
+  }
+  if (!a) return { lon: ring[0][0], lat: ring[0][1] };
+  return { lon: cx / (3 * a), lat: cy / (3 * a) };
+}
+
+/** Km from a point to a unit's box (0 inside it). */
+function boxDistanceKm(bbox, lat, lon) {
+  const [west, south, east, north] = bbox;
+  const mid = (west + east) / 2;
+  const x = lon - 360 * Math.round((lon - mid) / 360);
+  const clampedLon = Math.min(east, Math.max(west, x));
+  const clampedLat = Math.min(north, Math.max(south, lat));
+  return haversineKm(lat, x, clampedLat, clampedLon);
+}
+
+/**
+ * Natural Earth `min_label` (the zoom at which a unit is labelled) up to which
+ * a unit may be named alone: every US state, Canadian province, Mexican and
+ * German state; not English counties, French départements or small districts.
+ */
+const BARE_NAME_MAX_RANK = 7;
+
+/**
+ * Words that name a unit somewhere (Cameroon's "North", Paraguay's
+ * "Central") but, said alone, name a direction or a feature.
+ */
+const GENERIC_NAMES = new Set([
+  'north',
+  'south',
+  'east',
+  'west',
+  'northern',
+  'southern',
+  'eastern',
+  'western',
+  'north east',
+  'north west',
+  'south east',
+  'south west',
+  'northeast',
+  'northwest',
+  'southeast',
+  'southwest',
+  'far north',
+  'far west',
+  'central',
+  'centre',
+  'center',
+  'capital',
+  'coast',
+  'island',
+  'islands',
+  'lakes',
+  'highland',
+  'highlands',
+  'interior',
+  'upper',
+  'lower',
+  'valley',
+  'plateau',
+  'plateaux',
+  'littoral',
+  'oriental',
+  'occidental',
+]);
+
+/** State codes that, alone, more often mean a city ("LA", "NY"). */
+const CITY_ABBREVIATIONS = new Set(['la', 'ny']);
+
+/** Postal abbreviations accepted alone ("TX", "ON"): US states and Canada. */
+const POSTAL_COUNTRIES = new Set(['US', 'CA']);
+
+function addKey(index, key, entry, tier) {
+  if (!key) return;
+  entry.keys?.add(key);
+  const list = index.get(key);
+  const item = { entry, tier };
+  if (!list) index.set(key, [item]);
+  else if (!list.some((i) => i.entry === entry)) list.push(item);
+}
+
+const loadAdmin1 = createRetryableLoader(async () => {
+  packLoads.admin1 += 1;
+  const pack = await loadBundledJson(PACKS.admin1.url);
+  const decimals = pack.meta?.decimals ?? 3;
+  const index = new Map();
+  for (const feature of pack.features || []) {
+    const entry = {
+      kind: 'state',
+      feature,
+      decimals,
+      amb: new Set(feature.amb || []),
+      ambAbroad: new Set(feature.ambAbroad || []),
+      keys: new Set(),
+      country: normalizeAdminName(feature.country),
+      iso2: String(feature.iso2 || '').toLowerCase(),
+    };
+    addKey(index, normalizeAdminName(feature.name), entry, 0);
+    addKey(index, normalizeAdminName(feature.nameEn), entry, 1);
+    for (const alt of feature.alt || [])
+      addKey(index, normalizeAdminName(alt), entry, 2);
+    if (feature.postal && POSTAL_COUNTRIES.has(feature.iso2))
+      addKey(index, `postal:${feature.postal.toLowerCase()}`, entry, 2);
+  }
+  return { index };
+});
+
+const loadCounties = createRetryableLoader(async () => {
+  packLoads.counties += 1;
+  const pack = await loadBundledJson(PACKS.counties.url);
+  const decimals = pack.meta?.decimals ?? 4;
+  const byFull = new Map();
+  const byName = new Map();
+  const states = new Map();
+  for (const feature of pack.features || []) {
+    const entry = {
+      kind: 'county',
+      feature,
+      decimals,
+      state: normalizeAdminName(feature.state),
+      st: String(feature.st || '').toLowerCase(),
+    };
+    addKey(byFull, normalizeAdminName(feature.full), entry, 0);
+    addKey(byName, normalizeAdminName(feature.name), entry, 1);
+    states.set(entry.state, entry.st);
+  }
+  return { byFull, byName, states };
+});
+
+const loadCountries = createRetryableLoader(async () => {
+  packLoads.countries += 1;
+  const pack = await loadBundledJson(PACKS.countries.url);
+  const index = new Map();
+  for (const feature of pack.features || []) {
+    const entry = {
+      kind: 'country',
+      feature,
+      decimals: pack.meta.decimals,
+      keys: new Set(),
+      country: normalizeAdminName(feature.country),
+      iso2: feature.iso2?.toLowerCase(),
+    };
+    for (const name of [feature.name, ...(feature.alt || [])])
+      addKey(index, normalizeAdminName(name), entry, 0);
+  }
+  return { index };
+});
+
+async function countryCandidates(parsed) {
+  if (!['any', 'country'].includes(parsed.kind)) return [];
+  const { index } = await loadCountries();
+  const key = COUNTRY_TARGET_ALIASES.get(parsed.name) || parsed.name;
+  return (index.get(key) || []).filter(({ entry }) =>
+    parsed.qualifiers.every((q) => qualifierMatches(entry, q)),
+  );
+}
+
+/** Country target aliases never broaden constituent-country requests. */
+const COUNTRY_TARGET_ALIASES = new Map([
+  ['usa', 'united states of america'],
+  ['us', 'united states of america'],
+  ['u s', 'united states of america'],
+  ['u s a', 'united states of america'],
+  ['united states', 'united states of america'],
+  ['america', 'united states of america'],
+  ['uk', 'united kingdom'],
+  ['u k', 'united kingdom'],
+  ['great britain', 'united kingdom'],
+  ['britain', 'united kingdom'],
+  ['russian federation', 'russia'],
+  ['korea', 'south korea'],
+  ['czechia', 'czech republic'],
+  ['tanzania', 'united republic of tanzania'],
+  ['drc', 'democratic republic of the congo'],
+]);
+
+const COUNTRY_ALIASES = new Map([
+  ...COUNTRY_TARGET_ALIASES,
+  ['england', 'united kingdom'],
+  ['scotland', 'united kingdom'],
+  ['wales', 'united kingdom'],
+  ['northern ireland', 'united kingdom'],
+]);
+
+/** County-equivalent words, longest first so "city and borough" wins. */
+const COUNTY_WORDS = [
+  'city and borough',
+  'planning region',
+  'census area',
+  'municipality',
+  'municipio',
+  'borough',
+  'parish',
+  'county',
+];
+const COUNTY_WORD_RE = new RegExp(`\\b(${COUNTY_WORDS.join('|')})\\b`);
+const STATE_PREFIX_RE =
+  /^(?:free state|state|commonwealth|province|territory|prefecture|region|land|canton|department) of (.+)$/;
+const STATE_SUFFIX_RE = /^(.+) (?:state|province|prefecture|territory)$/;
+
+/**
+ * Split an ask into what it names and how.
+ * @param {string} text
+ * @returns {{kind:'country'|'county'|'state'|'any', name:string, qualifiers:string[],
+ *   postal:string|null, countyWord:string|null}|null}
+ */
+export function parseAdminQuery(text) {
+  const raw = String(text || '').trim();
+  if (!raw) return null;
+  const segments = raw.split(',').map(normalizeAdminName).filter(Boolean);
+  if (!segments.length) return null;
+  const head = segments[0];
+  const country =
+    /^(?:country|nation) of (.+)$/.exec(head) ||
+    /^(.+) (?:country|nation)$/.exec(head);
+  if (country)
+    return {
+      kind: 'country',
+      name: country[1],
+      qualifiers: segments.slice(1),
+      postal: null,
+      countyWord: null,
+      full: head,
+    };
+  const qualifiers = segments.slice(1);
+  const postal = /^[A-Za-z]{2}$/.test(raw) ? raw.toLowerCase() : null;
+  // "TX", "DC", "D.C.": written as an abbreviation, not a short word.
+  const abbreviation = /^[A-Z]{2,3}$/.test(raw.replace(/[.\s]/g, ''));
+
+  // "County Cork", "County of Los Angeles"
+  const countyPrefix = /^county (?:of )?(.+)$/.exec(head);
+  if (countyPrefix)
+    return {
+      kind: 'county',
+      name: countyPrefix[1],
+      qualifiers,
+      postal: null,
+      countyWord: 'county',
+      full: head,
+    };
+  // "Travis County", "Travis County Texas", "Orleans Parish, LA"
+  const county = COUNTY_WORD_RE.exec(head);
+  if (county && county.index > 0) {
+    const name = head.slice(0, county.index).trim();
+    const rest = head.slice(county.index + county[1].length).trim();
+    if (rest) qualifiers.unshift(rest);
+    return {
+      kind: 'county',
+      name,
+      qualifiers,
+      postal: null,
+      countyWord: county[1],
+      full: head.slice(0, county.index + county[1].length),
+    };
+  }
+  const prefix = STATE_PREFIX_RE.exec(head);
+  if (prefix)
+    return {
+      kind: 'state',
+      name: prefix[1],
+      qualifiers,
+      postal: null,
+      countyWord: null,
+      full: head,
+      form: 'prefix',
+    };
+  const suffix = STATE_SUFFIX_RE.exec(head);
+  if (suffix)
+    return {
+      kind: 'state',
+      name: suffix[1],
+      qualifiers,
+      postal: null,
+      countyWord: null,
+      full: head,
+      form: 'suffix',
+    };
+  return {
+    kind: 'any',
+    name: head,
+    qualifiers,
+    postal,
+    abbreviation,
+    countyWord: null,
+  };
+}
+
+/** A qualifier names the unit's country ("Bavaria, Germany") or the unit
+ * itself ("Washington, DC"). */
+function qualifierMatches(entry, qualifier) {
+  const q = COUNTRY_ALIASES.get(qualifier) || qualifier;
+  return (
+    entry.country === q ||
+    entry.iso2 === q ||
+    entry.keys.has(qualifier) ||
+    entry.keys.has(`postal:${qualifier}`)
+  );
+}
+
+/**
+ * Rank candidates: a unit containing `near` first, then the match tier,
+ * then distance from `near`, then larger area. Returns the ranked list.
+ */
+function rank(candidates, near) {
+  const hasNear = Number.isFinite(near?.lat) && Number.isFinite(near?.lon);
+  const scored = candidates.map(({ entry, tier }) => {
+    const geometry = geometryOf(entry);
+    const contains = hasNear
+      ? polygonsContain(geometry.polygons, near.lat, near.lon)
+      : false;
+    const distanceKm = hasNear
+      ? contains
+        ? 0
+        : boxDistanceKm(geometry.bbox, near.lat, near.lon)
+      : 0;
+    return { entry, tier, contains, distanceKm, areaKm2: geometry.areaKm2 };
+  });
+  scored.sort(
+    (a, b) =>
+      Number(b.contains) - Number(a.contains) ||
+      a.tier - b.tier ||
+      a.distanceKm - b.distanceKm ||
+      b.areaKm2 - a.areaKm2,
+  );
+  return scored;
+}
+
+function toResult(scored, candidateCount) {
+  const { entry } = scored;
+  const { feature } = entry;
+  const geometry = geometryOf(entry);
+  // Parts are stored largest first, so polygons[0][0] is the main outline.
+  const polygons = geometry.polygons;
+  if (entry.kind === 'county') {
+    return {
+      kind: 'county',
+      name: feature.full,
+      region: feature.state,
+      regionCode: feature.st,
+      country: 'United States of America',
+      id: feature.geoid,
+      source: 'us-census',
+      polygons,
+      ring: polygons[0][0],
+      bbox: geometry.bbox,
+      areaKm2: geometry.areaKm2,
+      label: geometry.label,
+      candidates: candidateCount,
+    };
+  }
+  return {
+    kind: entry.kind,
+    name: feature.nameEn || feature.name,
+    localName: feature.name,
+    type: feature.type,
+    region: null,
+    regionCode: feature.postal || null,
+    country: feature.country,
+    id: feature.iso || null,
+    source: 'natural-earth',
+    polygons,
+    ring: polygons[0][0],
+    bbox: geometry.bbox,
+    areaKm2: geometry.areaKm2,
+    label: geometry.label,
+    candidates: candidateCount,
+  };
+}
+
+async function countyCandidates(parsed) {
+  const { byFull, byName, states } = await loadCounties();
+  // An exact full name ("Orleans Parish") wins outright; without one, the
+  // name with ANY county-equivalent word ("Anchorage Borough" finds
+  // Anchorage Municipality). An independent city is only ever its full name
+  // ("Fairfax city", "Carson City").
+  let list = parsed.countyWord
+    ? [
+        ...(byFull.get(parsed.full || `${parsed.name} ${parsed.countyWord}`) ||
+          byName.get(parsed.name) ||
+          []),
+      ]
+    : [...(byFull.get(parsed.name) || [])];
+  if (!list.length) return [];
+  // Every qualifier must be a state or the US: "Travis County, TX, USA"
+  // qualifies, "Travis County Courthouse, Texas" names something else.
+  const stateByCode = new Map([...states].map(([name, st]) => [st, name]));
+  const stateQualifiers = [];
+  for (const q of parsed.qualifiers) {
+    const state = states.has(q) ? q : stateByCode.get(q);
+    if (state) stateQualifiers.push(state);
+    else if (!isUnitedStates(q)) return [];
+  }
+  if (stateQualifiers.length)
+    list = list.filter((i) => stateQualifiers.includes(i.entry.state));
+  return list;
+}
+
+function isUnitedStates(qualifier) {
+  return (
+    (COUNTRY_ALIASES.get(qualifier) || qualifier) === 'united states of america'
+  );
+}
+
+async function stateCandidates(parsed, { allowAmbiguous = false } = {}) {
+  const { index } = await loadAdmin1();
+  const keys = [];
+  if (parsed.full) keys.push(parsed.full);
+  keys.push(parsed.name);
+  if (parsed.postal) keys.push(`postal:${parsed.postal}`);
+  const seen = new Set();
+  let list = [];
+  for (const key of keys) {
+    for (const item of index.get(key) || []) {
+      if (seen.has(item.entry)) continue;
+      seen.add(item.entry);
+      list.push({ ...item, key, tier: key === parsed.full ? 0 : item.tier });
+    }
+  }
+  // Every qualifier must place the unit: "Bavaria, Germany", "Washington,
+  // DC" — not "Santa Barbara, California" (a city the pack does not hold).
+  if (parsed.qualifiers.length)
+    list = list.filter((i) =>
+      parsed.qualifiers.every((q) => qualifierMatches(i.entry, q)),
+    );
+  if (allowAmbiguous) return list;
+  // A bare name answers alone only for a prominent unit — a US state, a
+  // Canadian province, Bavaria — never a French département, an English
+  // county or a Bahamas district ("Long Island", "Santa Barbara", "Kent" are
+  // likelier the places a geocoder knows). It must not also be a country or
+  // a large city ("Georgia", "New York"), and a short code must be written
+  // as one ("TX", not "tx"). Otherwise a qualifier, admin wording or the
+  // geocoder decides.
+  // A country qualifier places a name without making it a state: "New York,
+  // USA" and "Madrid, Spain" stay the geocoder's; "Washington, DC" names the
+  // unit itself.
+  if (parsed.kind === 'any') {
+    const short = parsed.name.replace(/ /g, '').length <= 3;
+    if (short && (!parsed.abbreviation || CITY_ABBREVIATIONS.has(parsed.name)))
+      return [];
+    const namesUnit = (entry) =>
+      parsed.qualifiers.some(
+        (q) => entry.keys.has(q) || entry.keys.has(`postal:${q}`),
+      );
+    if (!parsed.qualifiers.length) {
+      if (GENERIC_NAMES.has(parsed.name)) return [];
+      return list.filter(
+        (i) =>
+          !i.entry.amb.has(i.key) &&
+          !i.entry.ambAbroad.has(i.key) &&
+          ((i.entry.feature.rank ?? Infinity) <= BARE_NAME_MAX_RANK ||
+            i.entry.feature.cityState),
+      );
+    }
+    // Qualified: a shared name abroad is settled by the country ("Victoria,
+    // Australia"); one shared at home only by the unit's own name.
+    return list.filter((i) => !i.entry.amb.has(i.key) || namesUnit(i.entry));
+  }
+  // "X State" only settles a name that is ambiguous on its own ("New York
+  // State"); otherwise it is as likely a university ("Ohio State") and a
+  // geocoder decides. A unit literally named so ("Free State") matches.
+  if (parsed.form === 'suffix')
+    return list.filter((i) => i.key === parsed.full || i.entry.amb.has(i.key));
+  return list;
+}
+
+/**
+ * Resolve an administrative unit from the ask's words alone.
+ *
+ * @param {string} query e.g. "Texas", "TX", "State of Texas", "Bavaria",
+ *   "Bavaria, Germany", "Travis County", "Travis County, TX", "Orleans Parish"
+ * @param {{near?: {lat:number, lon:number}|null}} [options] the camera's
+ *   view centre — the tie-break between same-named units
+ * @returns {Promise<AdminArea|null>}
+ *
+ * @typedef {{kind:'country'|'state'|'county', name:string, region:string|null,
+ *   regionCode:string|null, country:string, id:string|null,
+ *   source:'natural-earth'|'us-census',
+ *   polygons:Array<Array<Array<[number,number]>>>, ring:Array<[number,number]>,
+ *   bbox:number[], areaKm2:number, label:{lat:number, lon:number},
+ *   candidates:number}} AdminArea
+ */
+export async function findAdminArea(query, { near = null } = {}) {
+  const parsed = parseAdminQuery(query);
+  if (!parsed || !parsed.name) return null;
+  let candidates = [];
+  if (parsed.kind === 'country') {
+    candidates = await countryCandidates(parsed);
+  } else if (parsed.kind === 'county') {
+    // County wording also names admin-1 units abroad. Neither pack gets
+    // first refusal: qualifiers exclude ineligible countries before ranking.
+    const [counties, admin1] = await Promise.all([
+      countyCandidates(parsed),
+      stateCandidates({ ...parsed, kind: 'state' }),
+    ]);
+    candidates = [...counties, ...admin1];
+  } else {
+    candidates = await stateCandidates(parsed);
+    if (!candidates.length || COUNTRY_TARGET_ALIASES.has(parsed.name)) {
+      const countries = await countryCandidates(parsed);
+      if (countries.length) {
+        const states = await stateCandidates(parsed, { allowAmbiguous: true });
+        if (
+          states.length &&
+          !Number.isFinite(near?.lat) &&
+          !parsed.qualifiers.length
+        )
+          return null;
+        candidates = [...countries, ...states];
+      }
+    }
+    // A county-equivalent city: "Baltimore city", "Fairfax city, Virginia".
+    if (!candidates.length && / city$/.test(parsed.name))
+      candidates = await countyCandidates(parsed);
+  }
+  if (!candidates.length) return null;
+  const ranked = rank(candidates, near);
+  return toResult(ranked[0], candidates.length);
+}
+
+/**
+ * Geocoder-confirmed lookup: the geocoder typed a country, state or
+ * county, so the unit must carry one of `names` AND contain the geocoded
+ * point. Ambiguity marks do not apply — the geocoder already chose.
+ *
+ * @param {string[]} names  the ask and the geocoder's own name for it
+ * @param {number} lat
+ * @param {number} lon
+ * @param {'country'|'state'|'county'} scope
+ * @returns {Promise<AdminArea|null>}
+ */
+export async function findAdminAreaAt(names, lat, lon, scope) {
+  if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
+  const parsedList = [...new Set((names || []).filter(Boolean))]
+    .map(parseAdminQuery)
+    .filter((p) => p?.name);
+  if (!parsedList.length) return null;
+  const containing = (items) => {
+    const out = [];
+    for (const item of items)
+      if (
+        !out.some((c) => c.entry === item.entry) &&
+        polygonsContain(geometryOf(item.entry).polygons, lat, lon)
+      )
+        out.push(item);
+    return out;
+  };
+  if (scope === 'country') {
+    const countries = [];
+    for (const parsed of parsedList)
+      countries.push(
+        ...(await countryCandidates({
+          ...parsed,
+          kind: 'country',
+          qualifiers: [],
+        })),
+      );
+    const found = containing(countries);
+    return found.length
+      ? toResult(rank(found, { lat, lon })[0], found.length)
+      : null;
+  }
+  // The geocoder's scope says what kind of unit this is; the ask's wording
+  // may omit it ("Travis" typed as a county). A US county that matches wins
+  // outright — "New York County" is Manhattan, not the state.
+  if (scope === 'county' && inUnitedStatesBox(lat, lon)) {
+    const counties = [];
+    for (const parsed of parsedList)
+      counties.push(
+        ...(await countyCandidates({
+          ...parsed,
+          kind: 'county',
+          countyWord: parsed.countyWord || 'county',
+          qualifiers: [],
+        })),
+      );
+    const found = containing(counties);
+    if (found.length)
+      return toResult(rank(found, { lat, lon })[0], found.length);
+  }
+  const states = [];
+  for (const parsed of parsedList)
+    states.push(
+      ...(await stateCandidates(
+        { ...parsed, qualifiers: [] },
+        { allowAmbiguous: true },
+      )),
+    );
+  const found = containing(states);
+  if (!found.length) return null;
+  return toResult(rank(found, { lat, lon })[0], found.length);
+}
+
+/** Rough box around the US and its territories (skips the county pack elsewhere). */
+function inUnitedStatesBox(lat, lon) {
+  return (
+    (lat >= 13 && lat <= 72 && (lon <= -64 || lon >= 144)) ||
+    (lat >= -15 && lat <= -10 && lon <= -168)
+  );
+}

src/data/adminBoundaries.test.mjs

@@ -0,0 +1,481 @@
+// Bundled state/province and US county boundaries: name matching,
+// disambiguation, multipolygons and holes, and lazy loading.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, statSync } from 'node:fs';
+import {
+  decodeRing,
+  findAdminArea,
+  findAdminAreaAt,
+  normalizeAdminName,
+  packLoads,
+  parseAdminQuery,
+  polygonsContain,
+} from './adminBoundaries.js';
+
+const ADMIN1 = new URL(
+  './local_data/natural_earth/states_provinces.json',
+  import.meta.url,
+);
+const COUNTIES = new URL(
+  './local_data/us_census_counties/counties.json',
+  import.meta.url,
+);
+
+const AUSTIN = { lat: 30.2672, lon: -97.7431 };
+const PORTLAND = { lat: 45.5152, lon: -122.6784 };
+
+// Runs first: nothing loads until a lookup needs it, and a state ask never
+// pulls the county pack.
+test('packs load lazily, once, and only the pack an ask needs', async () => {
+  assert.deepEqual(packLoads, { admin1: 0, counties: 0, countries: 0 });
+  assert.equal(parseAdminQuery('Texas').kind, 'any');
+  assert.deepEqual(
+    packLoads,
+    { admin1: 0, counties: 0, countries: 0 },
+    'parsing is free',
+  );
+  await findAdminArea('Texas');
+  await findAdminArea('Bavaria');
+  assert.deepEqual(packLoads, { admin1: 1, counties: 0, countries: 0 });
+  await findAdminArea('Travis County');
+  await findAdminArea('Orleans Parish');
+  assert.deepEqual(packLoads, { admin1: 1, counties: 1, countries: 0 });
+});
+
+test('Texas, TX and "State of Texas" name the same unit', async () => {
+  for (const query of [
+    'Texas',
+    'texas',
+    'TX',
+    'State of Texas',
+    'the State of Texas',
+    'Texas, USA',
+    'Texas, United States',
+  ]) {
+    const unit = await findAdminArea(query, { near: AUSTIN });
+    assert.equal(unit?.id, 'US-TX', query);
+    assert.equal(unit.name, 'Texas');
+    assert.equal(unit.kind, 'state');
+    assert.equal(unit.source, 'natural-earth');
+  }
+  const texas = await findAdminArea('Texas');
+  assert.ok(
+    texas.areaKm2 > 600_000 && texas.areaKm2 < 750_000,
+    `Texas area ${texas.areaKm2}`,
+  );
+  assert.ok(polygonsContain(texas.polygons, AUSTIN.lat, AUSTIN.lon));
+});
+
+test('provinces and states abroad resolve by English and local names', async () => {
+  for (const query of [
+    'Bavaria',
+    'Bayern',
+    'Bavaria, Germany',
+    'Free State of Bavaria',
+  ]) {
+    const unit = await findAdminArea(query);
+    assert.equal(unit?.id, 'DE-BY', query);
+    assert.equal(unit.name, 'Bavaria');
+    assert.equal(unit.country, 'Germany');
+  }
+  assert.equal((await findAdminArea('Ontario'))?.id, 'CA-ON');
+  assert.equal((await findAdminArea('ON'))?.id, 'CA-ON');
+  assert.equal((await findAdminArea('Province of Ontario'))?.id, 'CA-ON');
+  assert.equal((await findAdminArea('Free State'))?.country, 'South Africa');
+  // Same name in two countries: the qualifier decides.
+  assert.equal((await findAdminArea('Punjab, India'))?.id, 'IN-PB');
+  assert.equal((await findAdminArea('Punjab, Pakistan'))?.id, 'PK-PB');
+  // A qualifier may name the unit itself.
+  assert.equal((await findAdminArea('Washington, DC'))?.id, 'US-DC');
+});
+
+test('"Washington" is the state; "Washington County" is a county near the camera', async () => {
+  const state = await findAdminArea('Washington', { near: AUSTIN });
+  assert.equal(state?.id, 'US-WA');
+  const fromAustin = await findAdminArea('Washington County', { near: AUSTIN });
+  assert.equal(fromAustin.kind, 'county');
+  assert.equal(fromAustin.name, 'Washington County');
+  assert.equal(fromAustin.region, 'Texas');
+  assert.ok(fromAustin.candidates > 20, 'dozens of Washington Counties');
+  const fromPortland = await findAdminArea('Washington County', {
+    near: PORTLAND,
+  });
+  assert.equal(fromPortland.region, 'Oregon');
+  const arkansas = await findAdminArea('Washington County, Arkansas', {
+    near: PORTLAND,
+  });
+  assert.equal(arkansas.region, 'Arkansas');
+  assert.equal(arkansas.candidates, 1);
+  assert.equal(
+    (await findAdminArea('Washington County, AR'))?.region,
+    'Arkansas',
+  );
+});
+
+test('Travis County with and without its state', async () => {
+  for (const query of [
+    'Travis County',
+    'Travis County, Texas',
+    'Travis County, TX',
+    'Travis County Texas',
+    'travis county, texas, usa',
+  ]) {
+    const unit = await findAdminArea(query, { near: PORTLAND });
+    assert.equal(unit?.id, '48453', query);
+    assert.equal(unit.name, 'Travis County');
+    assert.equal(unit.region, 'Texas');
+    assert.equal(unit.source, 'us-census');
+  }
+  assert.equal(await findAdminArea('Travis County, Ohio'), null);
+  assert.equal(await findAdminArea('Travis County Courthouse'), null);
+  // Every qualifier must place the county, not name something in it.
+  assert.equal(await findAdminArea('Travis County Courthouse, Texas'), null);
+  assert.equal(
+    await findAdminArea('Orange County Great Park, California'),
+    null,
+  );
+});
+
+test('county equivalents: parishes, boroughs, independent cities, and non-US counties', async () => {
+  const orleans = await findAdminArea('Orleans Parish', { near: AUSTIN });
+  assert.equal(orleans?.id, '22071');
+  assert.equal(orleans.region, 'Louisiana');
+  assert.equal((await findAdminArea('Orleans Parish, LA'))?.id, '22071');
+  // The wrong county word still finds the only unit with that name.
+  assert.equal(
+    (await findAdminArea('Anchorage Borough'))?.name,
+    'Anchorage Municipality',
+  );
+  // Outside the US a county is an admin-1 unit.
+  assert.equal((await findAdminArea('County Cork'))?.country, 'Ireland');
+  assert.equal(
+    (await findAdminArea('Kent County, England'))?.country,
+    'United Kingdom',
+  );
+  assert.equal(
+    (await findAdminArea('Kent County', { near: AUSTIN }))?.region,
+    'Texas',
+  );
+});
+
+test('a bare name that is also a country or a large city is left to a geocoder', async () => {
+  for (const query of ['New York', 'Georgia', 'Madrid']) {
+    assert.equal(await findAdminArea(query), null, query);
+  }
+  // Admin wording settles it.
+  assert.equal((await findAdminArea('New York State'))?.id, 'US-NY');
+  assert.equal((await findAdminArea('State of New York'))?.id, 'US-NY');
+  assert.equal((await findAdminArea('State of Mexico'))?.country, 'Mexico');
+  // City-states are the city itself.
+  assert.equal((await findAdminArea('Berlin'))?.id, 'DE-BE');
+  assert.equal((await findAdminArea('Vienna'))?.country, 'Austria');
+  // A country qualifier places a name; it does not make a city a state.
+  assert.equal(await findAdminArea('New York, USA'), null);
+  assert.equal(await findAdminArea('Madrid, Spain'), null);
+  // A namesake city abroad: ambiguous alone, settled by naming the country.
+  const santaFe = { lat: 35.687, lon: -105.938 };
+  assert.equal(await findAdminArea('Santa Fe', { near: santaFe }), null);
+  assert.equal(await findAdminArea('Victoria'), null);
+  assert.equal((await findAdminArea('Victoria, Australia'))?.id, 'AU-VIC');
+});
+
+test('bare names: only prominent units, no generic words, codes as codes', async () => {
+  // Places a geocoder knows better than a small admin unit of that name.
+  for (const query of [
+    'Long Island',
+    'Santa Barbara',
+    'Kent',
+    'Hamilton',
+    'Milan',
+  ])
+    assert.equal(await findAdminArea(query, { near: AUSTIN }), null, query);
+  for (const query of ['North', 'Central', 'Capital', 'Lakes'])
+    assert.equal(await findAdminArea(query), null, query);
+  // Two-letter codes must be written as codes, and not the city ones.
+  assert.equal(await findAdminArea('tx'), null);
+  assert.equal(
+    await findAdminArea('LA', { near: { lat: 34.05, lon: -118.24 } }),
+    null,
+  );
+  assert.equal(await findAdminArea('NY'), null);
+  assert.equal((await findAdminArea('OK'))?.id, 'US-OK');
+});
+
+test('non-admin asks never match', async () => {
+  for (const query of [
+    'Texas Capitol',
+    'the Texas State Capitol',
+    'Zilker Park',
+    'Ohio State',
+    'Texas State',
+    'Alps',
+    '',
+    null,
+  ]) {
+    assert.equal(await findAdminArea(query), null, String(query));
+  }
+});
+
+test('geocoder-confirmed lookup: the named unit that contains the point', async () => {
+  // Atlanta — the geocoder said "state", so the US state wins over the country.
+  const georgia = await findAdminAreaAt(['Georgia'], 33.749, -84.388, 'state');
+  assert.equal(georgia?.id, 'US-GA');
+  // Tbilisi — Georgia the country has no admin-1 unit of that name.
+  assert.equal(await findAdminAreaAt(['Georgia'], 41.7, 44.8, 'state'), null);
+  const newYork = await findAdminAreaAt(['New York'], 42.9, -75.5, 'state');
+  assert.equal(newYork?.id, 'US-NY');
+  // A county the geocoder typed, named without the county word.
+  const travis = await findAdminAreaAt(
+    ['Travis', 'Travis County'],
+    30.33,
+    -97.78,
+    'county',
+  );
+  assert.equal(travis?.id, '48453');
+  // A county the geocoder typed stays a county even where a state shares
+  // its name: Manhattan, the Big Island, Arkansas County.
+  assert.equal(
+    (await findAdminAreaAt(['New York County'], 40.783, -73.966, 'county'))?.id,
+    '36061',
+  );
+  assert.equal(
+    (await findAdminAreaAt(['Hawaii County'], 19.6, -155.5, 'county'))?.name,
+    'Hawaii County',
+  );
+  // A geocoded point outside the named unit is not that unit.
+  assert.equal(await findAdminAreaAt(['Texas'], 35.0, -106.6, 'state'), null);
+  // Outside the US a geocoder "county" is an admin-1 unit (Kent).
+  assert.equal(
+    (await findAdminAreaAt(['Kent'], 51.2, 0.7, 'county'))?.country,
+    'United Kingdom',
+  );
+});
+
+test('multipolygons: every island is a part, and containment follows the parts', async () => {
+  const hawaii = await findAdminArea('Hawaii');
+  assert.ok(
+    hawaii.polygons.length >= 7,
+    `Hawaii parts ${hawaii.polygons.length}`,
+  );
+  assert.ok(polygonsContain(hawaii.polygons, 19.6, -155.5), 'Big Island');
+  assert.ok(polygonsContain(hawaii.polygons, 20.8, -156.3), 'Maui');
+  assert.ok(polygonsContain(hawaii.polygons, 21.45, -158.0), 'Oahu');
+  assert.ok(
+    !polygonsContain(hawaii.polygons, 21.0, -157.3),
+    'the channel between',
+  );
+  // The main ring is the largest part (the Big Island).
+  assert.equal(hawaii.ring, hawaii.polygons[0][0]);
+
+  // Alaska is cut at the antimeridian: its box stays on one side of the globe.
+  const alaska = await findAdminArea('Alaska');
+  const [west, , east] = alaska.bbox;
+  assert.ok(east - west < 60, `Alaska box width ${east - west}°`);
+  assert.ok(alaska.polygons.length > 10, 'Aleutians and the southeast islands');
+});
+
+test('holes: Berlin is cut out of Brandenburg', async () => {
+  const brandenburg = await findAdminArea('Brandenburg');
+  assert.ok(
+    brandenburg.polygons.some((part) => part.length > 1),
+    'Brandenburg has a hole',
+  );
+  assert.ok(!polygonsContain(brandenburg.polygons, 52.52, 13.405), 'Berlin');
+  assert.ok(polygonsContain(brandenburg.polygons, 52.39, 13.06), 'Potsdam');
+  const berlin = await findAdminArea('Berlin');
+  assert.ok(polygonsContain(berlin.polygons, 52.52, 13.405));
+});
+
+test('holes: an independent city is cut out of its county', async () => {
+  const fairfax = await findAdminArea('Fairfax County, Virginia');
+  assert.ok(fairfax.polygons[0].length > 1, 'Fairfax County has holes');
+  assert.ok(
+    !polygonsContain(fairfax.polygons, 38.846, -77.306),
+    'Fairfax city',
+  );
+  assert.ok(polygonsContain(fairfax.polygons, 38.9, -77.2), 'Fairfax County');
+  const city = await findAdminArea('Fairfax city, Virginia');
+  assert.ok(polygonsContain(city.polygons, 38.846, -77.306));
+  assert.equal((await findAdminArea('Carson City'))?.region, 'Nevada');
+  for (const query of ['New York City', 'Mexico City', 'Quebec City, Canada'])
+    assert.equal(await findAdminArea(query), null, query);
+});
+
+test('rings decode from deltas and are open', () => {
+  assert.deepEqual(decodeRing([-97743, 30267, 10, -5, -3, 8], 3), [
+    [-97.743, 30.267],
+    [-97.733, 30.262],
+    [-97.736, 30.27],
+  ]);
+});
+
+test('names normalize across accents, punctuation and "Saint"', () => {
+  assert.equal(normalizeAdminName('Québec'), 'quebec');
+  assert.equal(normalizeAdminName('  The State of TEXAS '), 'state of texas');
+  assert.equal(normalizeAdminName('Saint Louis County'), 'st louis county');
+  assert.equal(normalizeAdminName('St. Louis County'), 'st louis county');
+  assert.equal(normalizeAdminName('Schleswig-Holstein'), 'schleswig holstein');
+});
+
+test('packs: public-domain provenance, schema, and size budgets', () => {
+  const admin1 = JSON.parse(readFileSync(ADMIN1, 'utf8'));
+  const counties = JSON.parse(readFileSync(COUNTIES, 'utf8'));
+  for (const pack of [admin1, counties]) {
+    assert.match(pack.meta.license, /public domain/i);
+    assert.match(pack.meta.sha256, /^[0-9a-f]{64}$/);
+    assert.equal(pack.meta.script, 'scripts/build-admin-packs.mjs');
+    for (const feature of pack.features) {
+      assert.ok(feature.name, 'named');
+      assert.ok(feature.polygons.length >= 1, `${feature.name} has a part`);
+      for (const poly of feature.polygons)
+        for (const ring of poly) {
+          assert.equal(ring.length % 2, 0);
+          assert.ok(ring.length >= 8, `${feature.name}: ring has 4+ vertices`);
+        }
+    }
+  }
+  assert.ok(
+    admin1.features.length > 4500,
+    `${admin1.features.length} states/provinces`,
+  );
+  assert.ok(
+    counties.features.length > 3200,
+    `${counties.features.length} counties`,
+  );
+  assert.ok(statSync(ADMIN1).size <= 4 * 1024 * 1024, 'admin-1 pack ≤ 4 MB');
+  assert.ok(statSync(COUNTIES).size <= 2 * 1024 * 1024, 'county pack ≤ 2 MB');
+});
+
+test('county queries compare US and international names before choosing a geography', async () => {
+  const england = { lat: 54.78, lon: -1.58 };
+  const nc = { lat: 36.0, lon: -78.9 };
+  assert.equal(
+    (await findAdminArea('County Durham', { near: england }))?.country,
+    'United Kingdom',
+  );
+  assert.equal(
+    (await findAdminArea('County Durham'))?.country,
+    'United Kingdom',
+    'exact alias survives parsing',
+  );
+  assert.equal(
+    (await findAdminArea('Durham County', { near: nc }))?.region,
+    'North Carolina',
+  );
+  assert.equal(
+    (await findAdminArea('County Durham, England', { near: nc }))?.country,
+    'United Kingdom',
+  );
+  assert.equal(
+    (await findAdminArea('County Durham, USA', { near: england }))?.region,
+    'North Carolina',
+  );
+  assert.equal(
+    (await findAdminArea('Durham County, NC', { near: england }))?.region,
+    'North Carolina',
+  );
+  // Durham is also a city: without county wording leave city geocoding intact.
+  assert.equal(await findAdminArea('Durham, NC', { near: england }), null);
+  assert.equal(
+    (await findAdminAreaAt(['Durham, NC'], nc.lat, nc.lon, 'county'))?.region,
+    'North Carolina',
+  );
+});
+
+test('countries resolve aliases, keep substantial islands and disambiguate Georgia by scope and geography', async () => {
+  for (const names of [
+    ['USA', 'United States', 'America'],
+    ['UK', 'United Kingdom', 'Britain'],
+    ['Iran', 'Islamic Republic of Iran'],
+    ['Czechia', 'Czech Republic'],
+    ['Ivory Coast', "Côte d'Ivoire"],
+    ['South Korea', 'Korea'],
+    ['Russia', 'Russian Federation'],
+    ['Switzerland'],
+    ['France'],
+  ]) {
+    const resolved = await Promise.all(
+      names.map((name) => findAdminArea(name, { near: AUSTIN })),
+    );
+    assert.ok(
+      resolved.every((r) => r?.kind === 'country'),
+      names.join('/'),
+    );
+    assert.equal(new Set(resolved.map((r) => r.id)).size, 1);
+  }
+  assert.equal(
+    (await findAdminArea('Georgia', { near: AUSTIN })).kind,
+    'state',
+  );
+  assert.equal(
+    (await findAdminArea('Georgia', { near: { lat: 41.7, lon: 44.8 } })).kind,
+    'country',
+  );
+  assert.equal(
+    (await findAdminArea('the country of Georgia', { near: AUSTIN })).kind,
+    'country',
+  );
+  assert.equal(await findAdminArea('New York', { near: AUSTIN }), null);
+  assert.equal(
+    (await findAdminAreaAt(['Iran'], 35.69, 51.39, 'country')).kind,
+    'country',
+  );
+  assert.equal(
+    await findAdminAreaAt(['Iran'], 46.9, 7.4, 'country'),
+    null,
+    'name alone cannot override a mismatched geocoded point',
+  );
+  const japan = await findAdminArea('Japan');
+  for (const [lat, lon] of [
+    [35.68, 139.69],
+    [43.06, 141.35],
+    [33.59, 130.4],
+    [33.56, 133.53],
+  ])
+    assert.ok(polygonsContain(japan.polygons, lat, lon));
+  const usa = await findAdminArea('USA');
+  for (const [lat, lon] of [
+    [30.27, -97.74],
+    [61.22, -149.9],
+    [19.7, -155.1],
+  ])
+    assert.ok(
+      polygonsContain(usa.polygons, lat, lon),
+      'USA includes mainland, Alaska and Hawaii',
+    );
+  const bytes = statSync(
+    new URL('./local_data/natural_earth/countries.json', import.meta.url),
+  ).size;
+  assert.ok(bytes < 1_000_000);
+});
+
+test('UK constituent countries retain their own identity and extent from any camera', async () => {
+  const targets = [
+    ['Scotland', 'SCT', [55.95, -3.19], [54.6, 61]],
+    ['England', 'ENG', [51.5, -0.12], [49.8, 55.9]],
+    ['Wales', 'WLS', [51.48, -3.18], [51.3, 53.6]],
+    ['Northern Ireland', 'NIR', [54.6, -5.93], [53.9, 55.4]],
+  ];
+  for (const [name, id, point, extent] of targets) {
+    const unit = await findAdminArea(name, { near: AUSTIN });
+    assert.equal(unit.id, id);
+    assert.equal(unit.name, name);
+    assert.equal(unit.kind, 'country');
+    assert.ok(
+      unit.bbox[1] >= extent[0] && unit.bbox[3] <= extent[1],
+      `${name}: ${unit.bbox}`,
+    );
+    assert.ok(polygonsContain(unit.polygons, ...point));
+    for (const [other, , otherPoint] of targets)
+      if (other !== name)
+        assert.equal(polygonsContain(unit.polygons, ...otherPoint), false);
+    assert.equal((await findAdminAreaAt([name], ...point, 'country')).id, id);
+    assert.equal(await findAdminAreaAt([name], 30.27, -97.74, 'country'), null);
+  }
+  assert.equal((await findAdminArea('UK', { near: AUSTIN })).id, 'GBR');
+  assert.equal(
+    (await findAdminArea('County Durham, England', { near: AUSTIN })).country,
+    'United Kingdom',
+  );
+});

src/data/adsbLolFallback.js

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

src/data/aircraftClass.js

@@ -438,6 +438,20 @@ export function classifyAircraft({ typeCode, category } = {}) {
   return 'airliner';
 }
 
+/** Readable name of each class, for cards and readouts. */
+export const AIRCRAFT_CLASS_LABELS = Object.freeze({
+  light: 'Light aircraft',
+  glider: 'Glider',
+  turboprop: 'Turboprop',
+  airliner: 'Airliner',
+  widebody: 'Widebody',
+  quadjet: 'Four-engine jet',
+  helicopter: 'Helicopter',
+  fastjet: 'Fast jet',
+  bizjet: 'Business jet',
+  uav: 'Drone',
+});
+
 /** Billboard scale multipliers (skylight GLYPH_SCALE, + fastjet). */
 export const CLASS_SCALE_2D = {
   light: 0.62,

src/data/aircraftEmergency.js

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

src/data/aircraftEmergency.test.mjs

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

src/data/aircraftEmergencyAnalyst.test.mjs

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

src/data/aircraftRecession.js

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

src/data/aircraftRecession.test.mjs

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

src/data/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

@@ -1600,6 +1600,31 @@ test('vessel interaction wire: a sibling-owned pick wins without selection mutat
   }
 });
 
+for (const card of ['live', 'stale', 'absent', 'covered']) {
+  test(`vessel interaction wire: ${card} foreground card over registered cyclone`, () => {
+    const id = 'cyclone:fixture:cone:0';
+    registerPickOwner('weather-cyclones', (pickedId) => pickedId === id);
+    const harness = installWireHarness({ id });
+    const requests = [];
+    harness.windowTarget.addEventListener(WORLD_FOCUS_REQUEST_EVENT, (event) => requests.push(event.detail));
+    const host = hostWithCardHit(card === 'live' ? `vessel:${harness.record.mmsi}` : card === 'stale' ? 'vessel:999999999' : null);
+    if (card === 'covered') host.hitTest = (_x, _y, options) => {
+      assert.equal(options?.sourceId, undefined, 'test topmost host hit, not a covered AIS card');
+      return { sourceId: 'cctv', entryId: 'vessel:999999999' };
+    };
+    _setVesselOverlayHostForTest(host);
+    try {
+      harness.handler.click({ position: { x: 10, y: 20 } });
+      assert.equal(aisLiveVesselsLayer.getSelectedInfo()?.mmsi, harness.record.mmsi);
+      assert.equal(requests.length, card === 'live' ? 1 : 0);
+    } finally {
+      _setVesselOverlayHostForTest(null);
+      harness.cleanup();
+      unregisterPickOwner('weather-cyclones');
+    }
+  });
+}
+
 test('vessel card policy: only MMSI-keyed cards publish a hit rect', () => {
   const keyed = applyVesselOverlayPolicy(buildVesselCard(makeRecord()));
   assert.equal(keyed.interactive, true);
@@ -1643,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({
@@ -1663,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/aisStreamSentinels.test.mjs

@@ -0,0 +1,65 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  aisStreamRows,
+  ingestAisStreamEnvelope,
+} from '../../server/providers/vessels/ais-store.js';
+
+// ITU-R M.1371 encodes speed over ground in 0.1-knot units and course over
+// ground in 0.1-degree units, reserving the top code of each field for "not
+// available": SOG 1023 arrives as 102.3 knots and COG 3600 as 360 degrees.
+// Both are finite numbers, so they reach consumers as ordinary readings unless
+// the store rejects them here.
+const positionReport = (mmsi, body) => ({
+  MessageType: 'PositionReport',
+  Message: { PositionReport: { UserID: Number(mmsi), ...body } },
+  MetaData: {
+    MMSI: mmsi,
+    latitude: 53.40879,
+    longitude: 6.19741,
+    time_utc: '2026-09-17 20:00:00.000000000 +0000 UTC',
+  },
+});
+
+const rowFor = (mmsi) => aisStreamRows(50000).find((row) => row.mmsi === mmsi);
+
+test('speed over ground reported as unavailable is unknown, not 102.3 knots', () => {
+  assert.equal(
+    ingestAisStreamEnvelope(positionReport('244060365', { Sog: 102.3 })),
+    true,
+  );
+  assert.equal(rowFor('244060365').speed, null);
+});
+
+test('course over ground reported as unavailable is unknown, not 360 degrees', () => {
+  assert.equal(
+    ingestAisStreamEnvelope(positionReport('245382000', { Cog: 360 })),
+    true,
+  );
+  assert.equal(rowFor('245382000').course, null);
+});
+
+test('genuine speed and course readings survive the unavailable check', () => {
+  ingestAisStreamEnvelope(
+    positionReport('341260000', { Sog: 12.9, Cog: 74.6 }),
+  );
+  const row = rowFor('341260000');
+  assert.equal(row.speed, 12.9);
+  assert.equal(row.course, 74.6);
+});
+
+test('a stopped vessel keeps its zero speed and zero course', () => {
+  ingestAisStreamEnvelope(positionReport('244374235', { Sog: 0, Cog: 0 }));
+  const row = rowFor('244374235');
+  assert.equal(row.speed, 0);
+  assert.equal(row.course, 0);
+});
+
+test('the fastest encodable reading below the unavailable code is kept', () => {
+  ingestAisStreamEnvelope(
+    positionReport('244060366', { Sog: 102.2, Cog: 359.9 }),
+  );
+  const row = rowFor('244060366');
+  assert.equal(row.speed, 102.2);
+  assert.equal(row.course, 359.9);
+});

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/alprCameras.js

@@ -1,12 +1,13 @@
 import { defaultSurface } from './surfaceServices.js';
 import { createApplicationAlpr } from '../app/layers/alprCameras.js';
 import { createSourceSlot } from '../sources/sourceSlot.js';
-import { createOverpassAlprSource } from '../layers/alpr/index.js';
+import { createAlprTileSource } from '../layers/alpr/index.js';
 export * from '../layers/alpr/index.js';
 const slot = createSourceSlot(
-  createOverpassAlprSource(),
+  createAlprTileSource(),
   ['fetch'],
   'ALPR source',
+  { destroy: () => {}, detailZoom: () => null },
 );
 export const configureAlprSource = slot.configure;
 export default createApplicationAlpr({

src/data/alprCameras.test.mjs

@@ -3,7 +3,11 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import * as Cesium from 'cesium';
-import alprCamerasLayer, { createAlprCamerasLayer } from './alprCameras.js';
+import alprCamerasLayer, {
+  createAlprCamerasLayer,
+  configureAlprSource,
+} from './alprCameras.js';
+import { createAlprTileSource } from '../layers/alpr/source.js';
 import { DATA_CREDITS } from './dataCredits.js';
 import {
   clearSelectedEntityContextForLayer,
@@ -262,9 +266,45 @@ function cameraHarness(layer = alprCamerasLayer) {
   let response = async () => cameraResponse();
   const requests = [];
   globalThis.fetch = (...args) => {
+    // Marker floors resolve through the shared terrain service; these tests
+    // count camera requests only.
+    if (String(args[0]).includes('/api/terrain/heights'))
+      return Promise.resolve(Response.json({ results: [] }));
     requests.push(args);
     return response(...args);
   };
+  // Rendering tests use normalized records; tile transport has its own fixture suite.
+  if (layer === alprCamerasLayer)
+    configureAlprSource({
+      ...createAlprTileSource(),
+      async fetch(box, signal) {
+        const response = await globalThis.fetch('/test/cameras', {
+          signal,
+          body: `data=${encodeURIComponent(buildOverpassQuery(box.south, box.west, box.north, box.east))}`,
+        });
+        if (!response.ok)
+          throw new Error('Camera source temporarily unavailable');
+        const body = await response.json();
+        if (!Array.isArray(body.elements) || body.remark)
+          throw new Error('Incomplete fixture snapshot');
+        signal?.throwIfAborted();
+        return {
+          records: [
+            ...new Map(
+              body.elements
+                .slice(0, QUERY_LIMIT)
+                .map(normalizeAlprNode)
+                .filter(Boolean)
+                .map((r) => [r.id, r]),
+            ).values(),
+          ],
+          stale: response.headers.get('x-overpass-cache') === 'STALE',
+          saturated: body.elements.length >= QUERY_LIMIT,
+          noCoverage: body.noCoverage,
+          zoomIn: body.zoomIn,
+        };
+      },
+    });
   let box = { south: 30.26, west: -97.75, north: 30.28, east: -97.73 };
   let source, click, picked;
   const credits = new Set();
@@ -348,88 +388,28 @@ function cameraHarness(layer = alprCamerasLayer) {
   };
 }
 
-test('OSM attribution introduces displayed data for five seconds, then stays discoverable in the overflow', async (t) => {
+test('OSM attribution stays inline while ALPR displays and follows toggles', async (t) => {
   t.mock.timers.enable({ apis: ['setTimeout'] });
   const h = cameraHarness();
   try {
-    assert.equal(
-      h.credits.size,
-      0,
-      'do not use up the introduction while data is still loading',
-    );
+    assert.equal(h.credits.size, 0);
     await alprCamerasLayer.update();
     assert.equal(h.credits.size, 1);
     const [credit] = h.credits;
     assert.equal(credit.showOnScreen, true);
-    assert.match(credit.html, /class="gev-alpr-credit">ALPR:/);
-    assert.match(
-      credit.html,
-      /href="https:\/\/www.openstreetmap.org\/copyright"/,
-    );
-    assert.match(credit.html, /© OpenStreetMap<\/a>/);
-    t.mock.timers.tick(4999);
+    assert.match(credit.html, />© OpenStreetMap</);
+    assert.doesNotMatch(credit.html, /OpenMapTiles|Map and place data/);
+    t.mock.timers.tick(6000);
     assert.equal(h.credits.size, 1);
-    t.mock.timers.tick(1);
-    assert.equal(h.credits.size, 0);
-    const overflow = DATA_CREDITS.find((entry) => entry.key === 'alpr-osm');
-    assert.match(
-      overflow.html,
-      /ALPR camera locations \(automatic license plate readers\)/,
-    );
-    assert.match(
-      overflow.html,
-      /href="https:\/\/www.openstreetmap.org\/copyright"/,
-    );
-    assert.match(overflow.html, /ODbL 1\.0/);
-    await alprCamerasLayer.update();
-    assert.equal(
-      h.credits.size,
-      0,
-      'refresh must not keep reintroducing the credit',
-    );
     alprCamerasLayer.disable();
     assert.equal(h.credits.size, 0);
     alprCamerasLayer.enable();
     await alprCamerasLayer.update();
-    t.mock.timers.tick(4000);
-    alprCamerasLayer.enable();
     assert.equal(h.credits.size, 1);
-    t.mock.timers.tick(1000);
-    assert.equal(
-      h.credits.size,
-      0,
-      'duplicate enable must not restart the timer',
+    assert.match(
+      DATA_CREDITS.find((entry) => entry.key === 'openstreetmap').html,
+      /OpenStreetMap contributors.*ODbL/,
     );
-    alprCamerasLayer.disable();
-    alprCamerasLayer.enable();
-    await alprCamerasLayer.update();
-    assert.equal(h.credits.size, 1);
-  } finally {
-    h.restore();
-  }
-  assert.equal(h.credits.size, 0);
-  t.mock.timers.tick(5000);
-  assert.equal(h.credits.size, 0, 'destroy cancels the presentation timer');
-});
-
-test('disabling midway through the introduction cancels its timer before a new enable', async (t) => {
-  t.mock.timers.enable({ apis: ['setTimeout'] });
-  const h = cameraHarness();
-  try {
-    await alprCamerasLayer.update();
-    t.mock.timers.tick(3000);
-    alprCamerasLayer.disable();
-    assert.equal(h.credits.size, 0);
-    alprCamerasLayer.enable();
-    await alprCamerasLayer.update();
-    t.mock.timers.tick(2000);
-    assert.equal(
-      h.credits.size,
-      1,
-      'old deadline must not hide the new presentation',
-    );
-    t.mock.timers.tick(3000);
-    assert.equal(h.credits.size, 0);
   } finally {
     h.restore();
   }
@@ -765,7 +745,7 @@ test('empty mapped coverage, stale data and a saturated response remain distinct
     assert.equal(alprCamerasLayer.getStats().status, 'empty');
     assert.match(
       alprCamerasLayer.getStats().loadingLabel,
-      /coverage is incomplete/,
+      /No ALPR data for this area/,
     );
     h.expire();
     h.setFetch(async () =>
@@ -928,6 +908,122 @@ test('two factories keep their requests, records and destruction independent', a
   }
 });
 
+test('markers sit on the cached floor; unknown floors clamp only until they resolve', async () => {
+  // Ground clamping re-samples every marker whenever a photoreal tile streams
+  // in; a whole-city view (about 1,000 cameras) stuttered while zooming.
+  const floors = new Map([['30.2672', 150]]);
+  let resolveCalls = 0;
+  let releaseResolve;
+  const services = {
+    render: { governorRequestRender() {} },
+    picking: { registerPickOwner() {}, unregisterPickOwner() {} },
+    groundFloor: {
+      cachedGroundFloor: (lat) => floors.get(lat.toFixed(4)) ?? null,
+      resolveGroundFloorCells: async () => {
+        resolveCalls++;
+        await new Promise((resolve) => {
+          releaseResolve = resolve;
+        });
+        floors.set('30.2682', 160);
+      },
+    },
+    context: {
+      clearSelectedEntityContextForLayer() {},
+      getSelectedEntityContext() {
+        return null;
+      },
+      registerEntityContext() {},
+      removeEntityContextsForLayer() {},
+      selectEntityContext() {},
+    },
+  };
+  const layer = createAlprCamerasLayer({
+    services,
+    source: {
+      fetch: async () => ({
+        records: [
+          { id: 'directory:1', latitude: 30.2672, longitude: -97.7431 },
+          { id: 'directory:2', latitude: 30.2682, longitude: -97.7431 },
+        ],
+        stale: false,
+        saturated: false,
+      }),
+    },
+  });
+  const h = cameraHarness(layer);
+  try {
+    await layer.update();
+    const known = h.source.entities.getById('directory:1');
+    const unknown = h.source.entities.getById('directory:2');
+    assert.equal(
+      known.billboard.heightReference.getValue(),
+      Cesium.HeightReference.NONE,
+    );
+    assert.ok(
+      Math.abs(
+        Cesium.Cartographic.fromCartesian(known.position.getValue()).height -
+          151.5,
+      ) < 0.01,
+    );
+    assert.equal(
+      unknown.billboard.heightReference.getValue(),
+      Cesium.HeightReference.CLAMP_TO_GROUND,
+    );
+    assert.equal(resolveCalls, 1);
+    releaseResolve();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.equal(
+      unknown.billboard.heightReference.getValue(),
+      Cesium.HeightReference.NONE,
+    );
+    assert.ok(
+      Math.abs(
+        Cesium.Cartographic.fromCartesian(unknown.position.getValue()).height -
+          161.5,
+      ) < 0.01,
+    );
+    assert.equal(
+      h.source.entities.getById('directory:2'),
+      unknown,
+      'placed in place, not rebuilt',
+    );
+  } finally {
+    h.restore();
+  }
+});
+
+test('loaded cameras outside the view say so instead of looking unloaded', async () => {
+  // Field review: "nearby" spans twice the camera-to-ground range, so a view
+  // could hold cameras with none on screen and read as a failed load.
+  const h = cameraHarness();
+  const project = Cesium.SceneTransforms.worldToWindowCoordinates;
+  let inView = false;
+  Cesium.SceneTransforms.worldToWindowCoordinates = () =>
+    inView ? new Cesium.Cartesian2(100, 100) : new Cesium.Cartesian2(-500, 100);
+  try {
+    h.viewer.camera.positionWC = Cesium.Cartesian3.fromDegrees(
+      -97.7431,
+      30.2672,
+      2000,
+    );
+    h.viewer.scene.canvas.clientWidth = 800;
+    h.viewer.scene.canvas.clientHeight = 600;
+    await alprCamerasLayer.update();
+    let stats = alprCamerasLayer.getStats();
+    assert.equal(stats.onScreen, 0);
+    assert.match(stats.countLabel, /1 nearby · 0 on screen/);
+    assert.match(stats.loadingLabel, /None on screen/);
+    inView = true;
+    h.viewer.camera.moveEnd.raiseEvent();
+    stats = alprCamerasLayer.getStats();
+    assert.equal(stats.onScreen, 1);
+    assert.doesNotMatch(stats.loadingLabel, /None on screen/);
+  } finally {
+    Cesium.SceneTransforms.worldToWindowCoordinates = project;
+    h.restore();
+  }
+});
+
 test('orbit cache hits and metadata refreshes preserve marker geometry and selection events', async () => {
   const h = cameraHarness();
   try {
@@ -943,6 +1039,10 @@ test('orbit cache hits and metadata refreshes preserve marker geometry and selec
     const entity = h.source.entities.getById('alpr:42');
     const position = entity.position,
       line = entity.polyline;
+    // Ground-clamped native wedges cost ~40 ms per frame for a downtown view;
+    // bearings are painted by the overlay for the nearest cameras instead.
+    assert.equal(line, undefined);
+    assert.equal(entity.polygon, undefined);
     let selections = 0,
       clears = 0,
       collectionChanges = 0;
@@ -1126,3 +1226,270 @@ test('nearby count and discovery control frame a real loaded camera without fetc
     h.restore();
   }
 });
+
+test('a non-retryable capability error does not arm the ALPR retry timer', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const h = cameraHarness();
+  try {
+    h.setFetch(async () => {
+      throw Object.assign(new Error('Unavailable'), {
+        code: 'OVERPASS_NOT_CONFIGURED',
+        retryable: false,
+      });
+    });
+    await alprCamerasLayer.update();
+    assert.equal(alprCamerasLayer.getStats().retryAt, 0);
+    const requests = h.requests.length;
+    t.mock.timers.tick(300_000);
+    await Promise.resolve();
+    assert.equal(h.requests.length, requests);
+  } finally {
+    h.restore();
+  }
+});
+
+test('unsupported ALPR coverage suppresses the nearby count and names the extract region', async () => {
+  const h = cameraHarness();
+  try {
+    h.setFetch(async () => ({
+      ...cameraResponse([]),
+      json: async () => ({ elements: [], noCoverage: true }),
+    }));
+    await alprCamerasLayer.update();
+    const stats = alprCamerasLayer.getStats();
+    assert.equal(stats.noCoverage, true);
+    assert.equal(stats.countLabel, '');
+    assert.equal(
+      stats.loadingLabel,
+      'No ALPR data for this area — US and Canada only',
+    );
+  } finally {
+    h.restore();
+  }
+});
+
+import { createGroundFloor } from '../services/groundFloor.js';
+import { createTerrainHeights } from '../services/terrainHeights.js';
+import { createApplicationRequestServices } from '../services/requests.js';
+
+test('slow ALPR floors share real terrain requests across preparation, render and pans; disable aborts', async () => {
+  const requests = [];
+  const sourceServices = createApplicationRequestServices({
+    fetchImpl: (url, { signal }) =>
+      new Promise((resolve, reject) => {
+        assert.match(url, /^\/api\/terrain\/heights\?/);
+        const points = new URL(url, 'http://localhost').searchParams
+          .get('points')
+          .split(';');
+        requests.push({
+          signal,
+          points,
+          release: () =>
+            resolve(
+              Response.json({
+                results: points.map(() => ({ ellipsoid: 160 })),
+              }),
+            ),
+        });
+        signal.addEventListener('abort', () => reject(signal.reason), {
+          once: true,
+        });
+      }),
+  });
+  const terrain = createTerrainHeights({ source: sourceServices.terrain });
+  const ground = createGroundFloor({ terrain });
+  ground.FLOOR_RESOLVE_DEADLINE_MS = 1;
+  const records = Array.from({ length: 130 }, (_, i) => ({
+    id: `slow:${i}`,
+    latitude: 30.261 + Math.floor(i / 15) * 0.001,
+    longitude: -97.749 + (i % 15) * 0.001,
+  }));
+  const layer = createAlprCamerasLayer({
+    source: {
+      fetch: async () => ({ records, stale: false, saturated: false }),
+    },
+    services: {
+      groundFloor: ground,
+      render: { governorRequestRender() {} },
+      picking: { registerPickOwner() {}, unregisterPickOwner() {} },
+      context: {
+        clearSelectedEntityContextForLayer() {},
+        getSelectedEntityContext() {},
+        registerEntityContext() {},
+        removeEntityContextsForLayer() {},
+        selectEntityContext() {},
+      },
+    },
+  });
+  const h = cameraHarness(layer);
+  try {
+    await layer.update();
+    assert.equal(
+      requests.length,
+      1,
+      'render joins the outstanding preparation batch',
+    );
+    assert.equal(
+      requests[0].points.length,
+      64,
+      'one bounded batch runs at a time',
+    );
+    h.expire();
+    await layer.update();
+    await layer.update();
+    assert.equal(
+      requests.length,
+      1,
+      'further preparation and render reuse cold cell promises',
+    );
+    requests[0].release();
+    await new Promise((done) => setTimeout(done, 0));
+    assert.equal(requests.length, 2);
+    const requested = requests.flatMap((request) => request.points);
+    assert.equal(
+      new Set(requested).size,
+      requested.length,
+      'no duplicate cells over HTTP',
+    );
+    layer.disable();
+    assert.equal(
+      requests[1].signal.aborted,
+      true,
+      'disable cancels the active HTTP request',
+    );
+    requests[1].release();
+    await new Promise((done) => setTimeout(done, 0));
+    assert.equal(requests.length, 2, 'queued final cells are discarded');
+    assert.equal(h.source.entities.values.length, 0);
+    layer.enable();
+    await layer.update();
+    assert.equal(
+      requests.length,
+      3,
+      'a fresh consumer can resume unresolved cells',
+    );
+    layer.destroy();
+    assert.equal(
+      requests[2].signal.aborted,
+      true,
+      'destroy also aborts its consumer',
+    );
+  } finally {
+    h.restore();
+  }
+});
+
+test('map-source changes reposition all ALPR entities and saved native appearances in place', async () => {
+  let floor = 180;
+  let listener;
+  let removed = 0;
+  const records = Array.from({ length: 70 }, (_, i) => ({
+    id: `surface:${i}`,
+    latitude: 30.2672 + i * 0.00001,
+    longitude: -97.7431,
+    directionDeg: i === 0 ? null : 90,
+  }));
+  const layer = createAlprCamerasLayer({
+    source: {
+      fetch: async () => ({ records, stale: false, saturated: false }),
+    },
+    services: {
+      groundFloor: { cachedGroundFloor: () => floor },
+      overlays: {
+        subscribeMapStack(fn) {
+          listener = fn;
+          return () => {
+            removed++;
+          };
+        },
+      },
+      render: { governorRequestRender() {} },
+      picking: { registerPickOwner() {}, unregisterPickOwner() {} },
+      context: {
+        clearSelectedEntityContextForLayer() {},
+        getSelectedEntityContext() {},
+        registerEntityContext() {},
+        removeEntityContextsForLayer() {},
+        selectEntityContext() {},
+      },
+    },
+  });
+  const h = cameraHarness(layer);
+  try {
+    await layer.update();
+    const entities = [...h.source.entities.values];
+    const saved = entities[1];
+    saved.gevAlprNativeAppearance = {
+      position: saved.position,
+      heightReference: saved.billboard.heightReference,
+    };
+    saved.position = Cesium.Cartesian3.fromDegrees(-97.7431, 30.26721, 190);
+    saved.gevAlprPickPosition = saved.position;
+    for (const next of [150, 120, null, 180]) {
+      floor = next;
+      // Includes a provider switch with the same globe.show value.
+      h.viewer.scene.globe.show = next !== 180;
+      listener({ detail: { status: 'ready' } });
+      for (const entity of entities) {
+        assert.equal(h.source.entities.getById(entity.id), entity);
+        assert.ok(
+          Math.abs(
+            Cesium.Cartographic.fromCartesian(entity.position.getValue())
+              .height - (next == null ? 0 : next + 1.5),
+          ) < 0.01,
+          `${entity.id} refreshes at ${next}`,
+        );
+        assert.equal(
+          entity.billboard.heightReference.getValue(),
+          next == null
+            ? Cesium.HeightReference.CLAMP_TO_GROUND
+            : Cesium.HeightReference.NONE,
+        );
+        assert.equal(entity.gevAlprCanvasPosition, null);
+      }
+      assert.equal(
+        saved.gevAlprNativeAppearance,
+        null,
+        'saved appearance restores at the new floor',
+      );
+    }
+  } finally {
+    h.restore();
+  }
+  assert.equal(removed, 1, 'map listener is disposed');
+});
+
+test('a repeated move inside an outstanding query keeps the displayed marker set until commit', async () => {
+  const h = cameraHarness();
+  try {
+    await alprCamerasLayer.update();
+    const previous = h.source.entities.getById('alpr:42');
+    const revision = alprCamerasLayer.getStats().renderRevision;
+    let release;
+    h.setFetch(
+      () =>
+        new Promise((resolve) => {
+          release = resolve;
+        }),
+    );
+    h.setBox({ south: 31, west: -98, north: 31.02, east: -97.98 });
+    const pending = alprCamerasLayer.update();
+    await alprCamerasLayer.update();
+    assert.equal(
+      h.source.entities.getById('alpr:42'),
+      previous,
+      'do not show an intermediate filtered snapshot while the new query prepares',
+    );
+    assert.equal(alprCamerasLayer.getStats().renderRevision, revision);
+    assert.equal(h.requests.length, 2, 'both moves share one new query');
+    release(cameraResponse([cameraNode(43, { lat: 31.01, lon: -97.99 })]));
+    await pending;
+    assert.equal(alprCamerasLayer.getStats().renderRevision, revision + 1);
+    assert.deepEqual(
+      h.source.entities.values.map((e) => e.id),
+      ['alpr:43'],
+    );
+  } finally {
+    h.restore();
+  }
+});

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

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

src/data/analystEngine.test.mjs

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

src/data/bhoteKoshiEmbeddedMedia.js

@@ -595,8 +595,15 @@ export function createBhoteKoshiEmbeddedMedia({
   facebookLoader = loadFacebookSdk,
   youtubeLoader = loadYouTubeApi,
 } = {}) {
-  if (!documentRef?.createElement || !viewer) {
+  // Pinokio externalizes HTTPS iframe navigation, including hidden preloads.
+  // Use the existing source-card/local-clip fallback before allocating provider
+  // resources. Browsers visiting the same Pinokio-launched server keep embeds.
+  const pinokioShell = /(?:^|\s)Pinokio\/[^\s]+/i.test(
+    globalRef.navigator?.userAgent || '',
+  );
+  if (pinokioShell || !documentRef?.createElement || !viewer) {
     return {
+      supportsPlayback: false,
       warm: () => false,
       show: () => false,
       play: () => false,
@@ -1078,6 +1085,7 @@ export function createBhoteKoshiEmbeddedMedia({
   }
 
   return {
+    supportsPlayback: true,
     warm,
     show,
     getPlaybackState: () => record?.youtubeSession?.getState() || null,

src/data/bhoteKoshiEmbeddedMedia.test.mjs

@@ -10,6 +10,57 @@ import {
   resolveEmbeddedMediaSource,
 } from './bhoteKoshiEmbeddedMedia.js';
 
+test('Pinokio fallback never creates provider DOM or loads SDKs', async () => {
+  const unexpected = () => { throw new Error('Provider resource allocated in Pinokio'); };
+  const media = createBhoteKoshiEmbeddedMedia({
+    viewer: {},
+    documentRef: { createElement: unexpected },
+    globalRef: {
+      navigator: { userAgent: 'Mozilla/5.0 Chrome/140.0.0.0 Safari/537.36 Pinokio/8.0.40' },
+      setTimeout: unexpected,
+      requestAnimationFrame: unexpected,
+    },
+    facebookLoader: unexpected,
+    youtubeLoader: unexpected,
+    xLoader: unexpected,
+  });
+  for (const sourceUrl of [
+    'https://www.youtube.com/watch?v=abcdefghijk',
+    'https://www.facebook.com/watch/?v=123456789',
+    'https://x.com/example/status/123456789',
+  ]) {
+    const options = { observation: { media: { sourceUrl } }, autoplay: true };
+    assert.equal(media.warm(options), false, 'no hidden preload');
+    assert.equal(media.show(options), false, 'retain the existing fallback card');
+    assert.equal(media.play(), false);
+    assert.equal(media.pause(), false);
+    media.hide();
+  }
+  media.destroy();
+  media.hide();
+  await Promise.resolve();
+});
+
+test('ordinary browsers retain real preloads on the same launcher URL', () => {
+  for (const userAgent of [
+    'Mozilla/5.0 Chrome/140.0.0.0 Safari/537.36',
+    'Mozilla/5.0 Version/18.0 Safari/605.1.15',
+    'Mozilla/5.0 Electron/38.0.0',
+    '',
+  ]) {
+    const { media, root } = preloadFixture({ globalRef: {
+      navigator: { userAgent }, location: { href: 'http://127.0.0.1:42003/' },
+    } });
+    assert.equal(media.warm({ observation: { media: {
+      sourceUrl: 'https://www.youtube.com/watch?v=abcdefghijk',
+    } } }), true);
+    assert.equal(root.children.length, 1);
+    media.pause();
+    assert.equal(root.children.length, 0);
+    media.destroy();
+  }
+});
+
 function trimmedPlaybackFixture() {
   let now = 0;
   let nextId = 0;

src/data/bhoteKoshiEvent.js

@@ -22,6 +22,8 @@ import {
   createBhoteKoshiEmbeddedMedia,
   resolveEmbeddedMediaSource,
 } from './bhoteKoshiEmbeddedMedia.js';
+import { acquireImageryComparison } from '../maps/imageryComparison.js';
+import { createImagerySplit } from '../ui/imagerySplit.js';
 
 export const BHOTE_KOSHI_LAYER_ID = 'bhote-koshi-2026';
 export const BHOTE_KOSHI_OVERLAY_SOURCE_ID = 'bhote-koshi-witnesses';
@@ -964,10 +966,7 @@ export function createBhoteKoshiEventLayer({
   let _enabled = false;
   let _panel = null;
   let _panelRefs = null;
-  let _splitLine = null;
-  let _splitHandle = null;
-  let _splitDragging = false;
-  let _splitPointerId = null;
+  let _splitControl = null;
   let _beforeLayer = null;
   let _afterLayer = null;
   let _imageryLayerCollection = null;
@@ -1000,6 +999,8 @@ export function createBhoteKoshiEventLayer({
   let _sceneMediaPlaybackBeatId = null;
   let _sceneMediaPlaybackCompletedBeatId = null;
   let _sceneMediaPlaybackTimer = null;
+  let _sceneMediaOwner = null;
+  let _removeSceneMediaAbort = null;
   let _witnessEmbedActive = false;
   let _sceneRevealAnimationFrame = null;
   let _sceneRevealHoldActive = false;
@@ -1020,14 +1021,11 @@ export function createBhoteKoshiEventLayer({
   let _playStartedAt = 0;
   let _playStartProgress = 0;
   let _animationFrame = null;
-  let _previousMapStack = null;
-  let _eventMapGeneration = null;
-  let _previousSplitPosition = null;
+  let _comparisonLease = null;
   let _introTimer = null;
   let _introGeneration = 0;
   let _lastSurgePosition = null;
   let _lastSurgeVisible = null;
-  let _lastSplitCssValue = null;
   let _presentation = 'standalone';
   let _sceneBeatId = null;
   let _sceneBeatReveal = 0.36;
@@ -1261,8 +1259,41 @@ export function createBhoteKoshiEventLayer({
     return true;
   }
 
+  // Playback authority is supplied by the Director, never restored from params.
+  function setSceneMediaPlayback(owner = null) {
+    _removeSceneMediaAbort?.();
+    _removeSceneMediaAbort = null;
+    _sceneMediaOwner = owner;
+    stopSceneMediaPlayback();
+    releaseEvidenceVideo({ restorePoster: false });
+    _embeddedMedia?.hide?.({ immediate: true });
+    _embeddedEvidenceIndex = -1;
+    _sceneMediaPlaybackCompletedBeatId = null;
+    if (owner?.token?.signal) {
+      const signal = owner.token.signal;
+      const cancel = () => setSceneMediaPlayback();
+      if (signal.aborted) cancel();
+      else {
+        signal.addEventListener('abort', cancel, { once: true });
+        _removeSceneMediaAbort = () =>
+          signal.removeEventListener('abort', cancel);
+      }
+    }
+  }
+
+  function sceneMediaPlaybackActive() {
+    return (
+      _sceneMediaOwner != null &&
+      !_sceneMediaOwner.token.cancelled &&
+      !_sceneMediaOwner.token.signal?.aborted &&
+      _sceneMediaOwner.sceneId === _sceneContext?.sceneId &&
+      _sceneMediaOwner.shotId === _sceneContext?.shotId
+    );
+  }
+
   function sceneEvidenceMediaAutoplays() {
     return (
+      sceneMediaPlaybackActive() &&
       _presentation === BHOTE_KOSHI_SCENE_PRESENTATION &&
       _sceneSurface === BHOTE_KOSHI_SCENE_EVIDENCE_BEAT &&
       _sceneControls.evidenceMediaAutoplay === true &&
@@ -1333,7 +1364,7 @@ export function createBhoteKoshiEventLayer({
     stopSceneMediaPlayback({ pauseMedia: false });
     _sceneMediaPlaybackBeatId = beatId;
     _embeddedMedia?.play?.();
-    if (sceneUsesTrimmedMedia(beatId)) {
+    if (sceneUsesTrimmedMedia(beatId) && _embeddedEvidenceIndex === index) {
       const deadline = Date.now() + 18000;
       const check = () => {
         if (
@@ -1415,6 +1446,14 @@ export function createBhoteKoshiEventLayer({
       !sceneUsesTrimmedMedia(beatId)
     )
       return null;
+    const media = _evidenceTimeline.find(
+      (item) => item.observation?.id === beatId,
+    )?.observation?.media;
+    // Deliberate provider suppression is a source card, not a player waiting
+    // to load. Returning no gate selects the Director's authored card dwell.
+    // A local clip still owns playback; a starting supported provider still waits.
+    if (_embeddedMedia?.supportsPlayback === false && !media?.videoPath)
+      return null;
     return {
       pending:
         _sceneMediaPlaybackCompletedBeatId !== beatId ||
@@ -2103,6 +2142,7 @@ export function createBhoteKoshiEventLayer({
       releaseEvidenceVideo();
       _embeddedEvidenceIndex = -1;
       const warmingEvidence =
+        sceneMediaPlaybackActive() &&
         _presentation === BHOTE_KOSHI_SCENE_PRESENTATION &&
         _sceneSurface === BHOTE_KOSHI_SCENE_EVIDENCE_BEAT;
       // Keep the same preload across camera frames; stop/disable still cancels it.
@@ -2512,79 +2552,20 @@ export function createBhoteKoshiEventLayer({
     createFloodDataSource();
   }
 
-  function ensureSplitLine(event) {
-    _splitLine = document.createElement('div');
-    _splitLine.id = 'bhote-koshi-split-line';
-    const beforeLabel = document.createElement('span');
-    const afterLabel = document.createElement('span');
-    const splitHandle = document.createElement('button');
-    beforeLabel.className = 'before';
-    afterLabel.className = 'after';
-    beforeLabel.textContent = 'A';
-    beforeLabel.title = event.imagery.before.label;
-    afterLabel.textContent = 'B';
-    afterLabel.title = event.imagery.after.label;
-    splitHandle.type = 'button';
-    splitHandle.className = 'bhote-koshi-split-handle';
-    splitHandle.setAttribute('role', 'slider');
-    splitHandle.setAttribute(
-      'aria-label',
-      'Historical reference and post-event image divider',
-    );
-    splitHandle.setAttribute('aria-valuemin', '0');
-    splitHandle.setAttribute('aria-valuemax', '100');
-    splitHandle.setAttribute('aria-orientation', 'horizontal');
-    splitHandle.textContent = '↔';
-    splitHandle.addEventListener('pointerdown', handleSplitPointerDown);
-    splitHandle.addEventListener('pointermove', handleSplitPointerMove);
-    splitHandle.addEventListener('pointerup', finishSplitPointerDrag);
-    splitHandle.addEventListener('pointercancel', finishSplitPointerDrag);
-    splitHandle.addEventListener('keydown', handleSplitKeyDown);
-    _splitHandle = splitHandle;
-    _splitLine.append(beforeLabel, splitHandle, afterLabel);
-    document.body.appendChild(_splitLine);
-  }
-
-  function setSplitFromClientX(clientX) {
-    const viewportWidth =
-      Number(document.documentElement?.clientWidth) ||
-      Number(window.innerWidth) ||
-      0;
-    if (viewportWidth <= 0 || !Number.isFinite(Number(clientX))) return;
-    setSplit(Number(clientX) / viewportWidth);
-  }
-
-  function handleSplitPointerDown(event) {
-    if (event.button != null && event.button !== 0) return;
-    event.preventDefault?.();
-    _splitDragging = true;
-    _splitPointerId = event.pointerId ?? null;
-    _splitHandle?.setPointerCapture?.(event.pointerId);
-    setSplitFromClientX(event.clientX);
-  }
-
-  function handleSplitPointerMove(event) {
-    if (!_splitDragging) return;
-    if (_splitPointerId != null && event.pointerId !== _splitPointerId) return;
-    event.preventDefault?.();
-    setSplitFromClientX(event.clientX);
-  }
-
-  function finishSplitPointerDrag(event) {
-    if (!_splitDragging) return;
-    if (_splitPointerId != null && event.pointerId !== _splitPointerId) return;
-    _splitHandle?.releasePointerCapture?.(event.pointerId);
-    _splitDragging = false;
-    _splitPointerId = null;
-  }
-
-  function handleSplitKeyDown(event) {
-    if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return;
-    event.preventDefault?.();
-    const step = event.shiftKey ? 0.05 : 0.01;
-    if (event.key === 'Home') setSplit(0);
-    else if (event.key === 'End') setSplit(1);
-    else setSplit(_split + (event.key === 'ArrowRight' ? step : -step));
+  function createSplitControl(event) {
+    _splitControl = createImagerySplit({
+      scene: _viewer.scene,
+      initialValue: _split,
+      id: 'bhote-koshi-split-line',
+      handleClass: 'bhote-koshi-split-handle',
+      cssProperty: '--bhote-koshi-split',
+      beforeTitle: event.imagery.before.label,
+      afterTitle: event.imagery.after.label,
+      ariaLabel: 'Historical reference and post-event image divider',
+      formatValueText: (beforePercent, afterPercent) =>
+        `A historical reference ${beforePercent} percent, B post-event ${afterPercent} percent`,
+      onChange: setSplit,
+    });
   }
 
   function applyCinematicCamera() {
@@ -3167,7 +3148,7 @@ export function createBhoteKoshiEventLayer({
       _panelRefs.observedStatus.hidden = !imageryAvailable;
     if (_panelRefs?.progressInput)
       _panelRefs.progressInput.hidden = !scrubberAvailable;
-    if (_splitLine) _splitLine.hidden = !imageryAvailable;
+    _splitControl?.setVisible(imageryAvailable);
     if (_beforeLayer) _beforeLayer.show = imageryAvailable;
     if (_afterLayer) _afterLayer.show = imageryAvailable;
     if (_panelRefs?.caveat) {
@@ -3284,24 +3265,7 @@ export function createBhoteKoshiEventLayer({
 
   function setSplit(split) {
     _split = clampUnit(split);
-    if (_viewer && _viewer.scene.splitPosition !== _split)
-      _viewer.scene.splitPosition = _split;
-    const cssValue = `${_split * 100}%`;
-    if (_lastSplitCssValue !== cssValue) {
-      document.documentElement.style.setProperty(
-        '--bhote-koshi-split',
-        cssValue,
-      );
-      _lastSplitCssValue = cssValue;
-    }
-    if (_splitHandle) {
-      const beforePercent = Math.round(_split * 100);
-      _splitHandle.setAttribute('aria-valuenow', String(beforePercent));
-      _splitHandle.setAttribute(
-        'aria-valuetext',
-        `A historical reference ${beforePercent} percent, B post-event ${100 - beforePercent} percent`,
-      );
-    }
+    _splitControl?.setValue(_split);
     syncPanel();
     renderHost.request('bhote-koshi-split');
   }
@@ -3384,7 +3348,6 @@ export function createBhoteKoshiEventLayer({
   async function enable(viewer, { origin = 'local-restore', signal } = {}) {
     _viewer = viewer;
     _enabled = true;
-    _previousSplitPosition = viewer.scene.splitPosition;
     // Public lifecycle passes signal, not intent origin, to enable. Its atomic
     // restore has already applied the scene parameters; those own presentation.
     // A missing origin is passive, never authority to focus or start playback.
@@ -3393,24 +3356,20 @@ export function createBhoteKoshiEventLayer({
       const event = await loadEvent();
       throwIfEnableCancelled(signal, _enabled);
       registerDynamicCredit(viewer, BHOTE_KOSHI_CREDIT);
-      _previousMapStack = _mapStackController?.getActiveId?.() || null;
-      if (
-        !sceneDirected &&
-        _mapStackController &&
-        _previousMapStack !== 'esri-imagery'
-      ) {
-        await _mapStackController.setStack('esri-imagery');
+      if (_mapStackController) {
+        _comparisonLease = acquireImageryComparison(_mapStackController, {
+          owner: BHOTE_KOSHI_LAYER_ID,
+          switchPolicy: sceneDirected ? 'preserve' : 'esri',
+        });
+        await _comparisonLease.ready;
       }
-      _eventMapGeneration = sceneDirected
-        ? null
-        : (_mapStackController?.getSwitchGeneration?.() ?? null);
       throwIfEnableCancelled(signal, _enabled);
       await createImagery(event);
       throwIfEnableCancelled(signal, _enabled);
       await syncTerrainComparison();
       throwIfEnableCancelled(signal, _enabled);
       createFloodDataSource();
-      ensureSplitLine(event);
+      createSplitControl(event);
       const panelView = createPanel(event, {
         close: () =>
           _dataManager?.setEnabled(BHOTE_KOSHI_LAYER_ID, false, {
@@ -3476,6 +3435,7 @@ export function createBhoteKoshiEventLayer({
   }
 
   async function disable() {
+    setSceneMediaPlayback();
     _enabled = false;
     ++_comparisonSurfaceGeneration;
     _mapStackController?.clearTerrainComparison?.();
@@ -3528,17 +3488,8 @@ export function createBhoteKoshiEventLayer({
       ?.classList.remove('bhote-event-active');
     _panel = null;
     _panelRefs = null;
-    _splitDragging = false;
-    _splitPointerId = null;
-    _splitLine?.remove();
-    _splitLine = null;
-    _splitHandle = null;
-    document.documentElement.style.removeProperty('--bhote-koshi-split');
-    _lastSplitCssValue = null;
-    if (_viewer?.scene && _previousSplitPosition != null) {
-      _viewer.scene.splitPosition = _previousSplitPosition;
-    }
-    _previousSplitPosition = null;
+    _splitControl?.destroy();
+    _splitControl = null;
     _progress = 0;
     _split = 0.5;
     _presentation = 'standalone';
@@ -3556,20 +3507,10 @@ export function createBhoteKoshiEventLayer({
       cancel?.(_sceneSeekFrame);
       _sceneSeekFrame = null;
     }
-    const previousMapStack = _previousMapStack;
-    const eventMapGeneration = _eventMapGeneration;
-    _previousMapStack = null;
-    _eventMapGeneration = null;
+    const comparisonLease = _comparisonLease;
+    _comparisonLease = null;
     try {
-      if (
-        _mapStackController &&
-        previousMapStack &&
-        previousMapStack !== 'esri-imagery' &&
-        _mapStackController.getActiveId?.() === 'esri-imagery' &&
-        _mapStackController.getSwitchGeneration?.() === eventMapGeneration
-      ) {
-        await _mapStackController.setStack(previousMapStack);
-      }
+      await comparisonLease?.release();
     } finally {
       renderHost.request('bhote-koshi-disable');
     }
@@ -3770,6 +3711,7 @@ export function createBhoteKoshiEventLayer({
     setParams,
     getParams,
     getSceneShotMediaHold,
+    setSceneMediaPlayback,
     getStats() {
       return {
         count: _enabled ? 1 : 0,

src/data/bhoteKoshiEvent.test.mjs

@@ -30,6 +30,8 @@ import {
 } from './bhoteKoshiEvent.js';
 import { SCENE_RECIPES } from '../scenes/recipes.js';
 import { LayerLifecycle } from './lifecycle.js';
+import { createBhoteKoshiEmbeddedMedia } from './bhoteKoshiEmbeddedMedia.js';
+import { SceneDirector } from '../scenes/director.js';
 
 const eventUrl = new URL('../../public/events/bhote-koshi-2026/event.json', import.meta.url);
 const eventModuleUrl = new URL('./bhoteKoshiEvent.js', import.meta.url);
@@ -277,8 +279,9 @@ test('trimmed scene media holds through provider startup, playback and fade, the
   try {
     const viewer = eventViewer();
     await layer.init(viewer);
+    layer.setSceneMediaPlayback({ sceneId: 'scene', shotId: 'shot', token: { cancelled: false } });
     layer.setParams({ presentation: 'scene-beat', sceneSurface: 'evidence-beat', beatId: 'mailung-bazzar',
-      sceneContext: { holdSec: 7.65 },
+      sceneContext: { sceneId: 'scene', shotId: 'shot', holdSec: 7.65 },
       sceneControls: { evidenceMediaAutoplay: true, cameraSettled: true, mediaExitDurationSec: 0.65 } }, { origin: 'scene' });
     await layer.enable(viewer, { origin: 'scene' });
     assert.equal(layer.getSceneShotMediaHold('mailung-bazzar').pending, true);
@@ -301,6 +304,94 @@ test('trimmed scene media holds through provider startup, playback and fade, the
   }
 });
 
+test('Pinokio source-card fallback selects authored Director dwell, not an impossible player hold', async () => {
+  const previous = { document: globalThis.document, window: globalThis.window };
+  installEventDom();
+  globalThis.window = { setTimeout: () => 1, clearTimeout() {} };
+  const event = JSON.parse(await readFile(eventUrl, 'utf8'));
+  const layer = createBhoteKoshiEventLayer({
+    eventLoader: async () => event,
+    imageryProviderFactory: async url => ({ url }),
+    terrainSampler: async (_viewer, observations) => observations.map(() => ({ height: 800 })),
+    mediaLoader: async () => { throw Object.assign(new Error('No bundled clip'), { name: 'AbortError' }); },
+    overlayHost: { setEntries() {}, setVisible() {}, clearSource() {} },
+    renderHost: { request() {}, hold() {}, release() {} },
+    embeddedMediaFactory: options => createBhoteKoshiEmbeddedMedia({ ...options,
+      globalRef: { navigator: { userAgent: 'Chrome Pinokio/8.0.40' } },
+      documentRef: { createElement() { assert.fail('unsupported host must allocate no provider DOM'); } },
+    }),
+  });
+  const token = { cancelled: false, signal: new AbortController().signal };
+  const params = { presentation: 'scene-beat', sceneSurface: 'evidence-beat', beatId: 'mailung-bazzar',
+    sceneContext: { sceneId: 'scene', shotId: 'shot', holdSec: 7.65 },
+    sceneControls: { evidenceMediaAutoplay: true, mediaPlaybackHoldSec: 7, cameraSettled: true } };
+  try {
+    const viewer = eventViewer();
+    await layer.init(viewer);
+    layer.setSceneMediaPlayback({ sceneId: 'scene', shotId: 'shot', token });
+    layer.setParams(params, { origin: 'scene' });
+    await layer.enable(viewer, { origin: 'scene' });
+    assert.equal(layer.getSceneShotMediaHold('mailung-bazzar'), null);
+    const waits = [];
+    await SceneDirector.prototype._holdShot.call({
+      _layerStatesForShot: () => ({ [layer.id]: { enabled: true, params } }),
+      dataManager: { layers: new Map([[layer.id, { module: layer }]]) },
+      _effectiveShotHoldSec: () => 7.65,
+      _sleep: async ms => waits.push(ms),
+      stopScene: () => assert.fail('a source card must not time out'),
+    }, { id: 'scene' }, { id: 'shot' }, token);
+    assert.deepEqual(waits, [7650], 'use the authored dwell instead of completing instantly or polling 20 seconds');
+    event.evidenceSpine.find(item => item.id === 'mailung-bazzar').media.videoPath = 'fixture-approved.mp4';
+    assert.equal(layer.getSceneShotMediaHold('mailung-bazzar').pending, true,
+      'an approved local clip remains a real playback owner even with the provider suppressed');
+  } finally { await layer.destroy(); Object.assign(globalThis, previous); }
+});
+
+test('saved autoplay controls cannot authorize media; live shot ownership is cancellable and never serialized', async () => {
+  const previous = { document: globalThis.document, window: globalThis.window };
+  installEventDom();
+  const timers = new Map(); let timerId = 0;
+  globalThis.window = { setTimeout: fn => { timers.set(++timerId, fn); return timerId; }, clearTimeout: id => timers.delete(id) };
+  const calls = [];
+  const event = JSON.parse(await readFile(eventUrl, 'utf8'));
+  const layer = createBhoteKoshiEventLayer({
+    eventLoader: async () => event,
+    imageryProviderFactory: async url => ({ url }),
+    terrainSampler: async (_viewer, observations) => observations.map(() => ({ height: 800 })),
+    mediaLoader: async () => { throw Object.assign(new Error('No bundled clip'), { name: 'AbortError' }); },
+    overlayHost: { setEntries() {}, setVisible() {}, clearSource() {} },
+    renderHost: { request() {}, hold() {}, release() {} },
+    embeddedMediaFactory: () => ({ supportsPlayback: true, warm: () => true,
+      show: options => { calls.push(options.autoplay); return true; },
+      getPlaybackState: () => null, play() {}, pause() {}, hide() {}, destroy() {} }),
+  });
+  const params = { presentation: 'scene-beat', sceneSurface: 'evidence-beat', beatId: 'mailung-bazzar',
+    sceneContext: { sceneId: 'scene', shotId: 'shot', holdSec: 7.65 },
+    sceneControls: { evidenceMediaAutoplay: true, cameraSettled: true, mediaPlaybackHoldSec: 7 } };
+  try {
+    const viewer = eventViewer(); await layer.init(viewer);
+    layer.setParams(params, { origin: 'local-restore' }); await layer.enable(viewer);
+    assert.ok(calls.length); assert.ok(calls.every(value => value === false));
+    assert.equal(layer.getSceneShotMediaHold('mailung-bazzar'), null);
+    const saved = layer.getParams();
+    const abort = new AbortController();
+    layer.setSceneMediaPlayback({ sceneId: 'scene', shotId: 'shot', token: { cancelled: false, signal: abort.signal } });
+    layer.setParams(params, { origin: 'scene' });
+    assert.equal(calls.at(-1), true);
+    assert.equal(layer.getSceneShotMediaHold('mailung-bazzar').pending, true,
+      'a temporarily null supported-provider state is still startup, not unsupported');
+    assert.deepEqual(layer.getParams(), saved, 'live playback authority must not enter saved params');
+    const late = [...timers.values()];
+    abort.abort(); late.forEach(fn => fn());
+    assert.equal(layer.getSceneShotMediaHold('mailung-bazzar'), null);
+    layer.setParams(params, { origin: 'local-restore' });
+    assert.equal(calls.at(-1), false, 'late callbacks and restored flags cannot restart revoked playback');
+    layer.setSceneMediaPlayback({ sceneId: 'scene', shotId: 'different-shot', token: { cancelled: false } });
+    layer.setParams(params, { origin: 'scene' });
+    assert.equal(calls.at(-1), false, 'a different shot cannot borrow this playback owner');
+  } finally { await layer.destroy(); Object.assign(globalThis, previous); }
+});
+
 test('Bhote Koshi timeline helpers clamp untrusted UI values', () => {
   assert.equal(clampUnit(-1), 0);
   assert.equal(clampUnit(0.42), 0.42);
@@ -1695,7 +1786,9 @@ test('Upper Valley Collapse autoplays its muted local fallback without starting
       sceneControls: { evidenceMediaAutoplay: true },
       beatId: 'immediate-collapse-viewpoint',
       beatReveal: 0.36,
+      sceneContext: { sceneId: 'scene', shotId: 'shot' },
     }, { origin: 'scene' });
+    layer.setSceneMediaPlayback({ sceneId: 'scene', shotId: 'shot', token: { cancelled: false } });
     await layer.enable(viewer, { origin: 'scene' });
     assert.equal(videos.length, 1);
     const video = videos[0];
@@ -1874,6 +1967,7 @@ test('Nepal evidence shots resume the standalone callout and flood sequence from
     sceneSurface: 'evidence-beat',
     beatId: 'gyirong-border-gate',
     beatReveal: 0.36,
+    sceneContext: { sceneId: 'scene', shotId: 'shot' },
     sceneControls: {
       evidenceSequence: true,
       evidenceSequenceDurationSec: 0.9,
@@ -1886,6 +1980,7 @@ test('Nepal evidence shots resume the standalone callout and flood sequence from
   try {
     await layer.init(viewer);
     layer.setParams(params, { origin: 'scene' });
+    layer.setSceneMediaPlayback({ sceneId: 'scene', shotId: 'shot', token: { cancelled: false } });
     await layer.enable(viewer, { origin: 'scene' });
     const card = entries.find(({ id }) => id === 'evidence-card-gyirong-border-gate');
     const flood = viewer._test.dataSources[0].entities.getById('bhote-koshi-flood-core');

src/data/bhoteKoshiLocator.js

@@ -7,6 +7,8 @@ import { governorRequestRender } from '../renderGovernor.js';
 import {
   BHOTE_KOSHI_LOCATOR_CREDIT,
   registerDynamicCredit,
+  showOsmCredit,
+  hideOsmCredit,
 } from './dataCredits.js';
 import { BHOTE_KOSHI_FLOOD_PATH } from './bhoteKoshiFloodPath.js';
 import { INCIDENT_OVERVIEW_PLACES } from './bhoteKoshiIncidentPlaces.js';
@@ -1035,6 +1037,7 @@ export function createBhoteKoshiLocatorLayer({
     renderPresentation();
     viewer.dataSources.add(dataSource);
     registerDynamicCredit(viewer, BHOTE_KOSHI_LOCATOR_CREDIT);
+    showOsmCredit(viewer, BHOTE_KOSHI_LOCATOR_LAYER_ID);
     requestRender('bhote-koshi-locator-callout');
 
     try {
@@ -1070,6 +1073,7 @@ export function createBhoteKoshiLocatorLayer({
   }
 
   async function disable() {
+    hideOsmCredit(_viewer, BHOTE_KOSHI_LOCATOR_LAYER_ID);
     _enabled = false;
     _boundaryReady = false;
     _boundaryResolved = false;

src/data/bhoteKoshiLocator.test.mjs

@@ -5,6 +5,8 @@ import { INCIDENT_OVERVIEW_HOLD_SEC, INCIDENT_OVERVIEW_PLACES } from './bhoteKos
 import { BHOTE_KOSHI_FLOOD_PATH } from './bhoteKoshiFloodPath.js';
 import * as Cesium from 'cesium';
 import { SceneDirector } from '../scenes/director.js';
+import { createPlaybackClock } from '../director/clock.js';
+import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
 import {
   anchoredCalloutPresentation,
   BHOTE_KOSHI_CITY_CONTEXT_PRESENTATION,
@@ -25,7 +27,7 @@ function viewerFixture() {
   const added = [];
   const removed = [];
   return {
-    creditDisplay: { addStaticCredit() {} },
+    creditDisplay: { addStaticCredit() {}, removeStaticCredit() {} },
     dataSources: {
       add(source) { added.push(source); },
       remove(source) { removed.push(source); },
@@ -503,11 +505,14 @@ for (const phase of ['timer', 'move-end', 'approach', 'orbit']) {
       ...nonRunningAnimation(),
     });
     const director = {
+      _clock: createPlaybackClock({ isRunning: () => false, timingForShot: () => null, onProgress() {} }),
+      _scenePacks: createDefaultScenePacks(),
       dataManager: { layers: new Map([[layer.id, { module: layer }]]) },
       viewer,
       _sceneSeekGeneration: 0,
       _loadGeneration: 0,
       _cancelActiveSceneTravel: SceneDirector.prototype._cancelActiveSceneTravel,
+      _setSceneMediaPlayback: SceneDirector.prototype._setSceneMediaPlayback,
     };
     try {
       layer.setParams({ presentation: BHOTE_KOSHI_TRIGGER_RECORD_PRESENTATION });

src/data/bundledJson.js

@@ -0,0 +1,44 @@
+/**
+ * @file Load a JSON file shipped beside the source modules.
+ *
+ * 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 file is read
+ * from disk instead.
+ *
+ * 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 {{signal?: AbortSignal}} [options]
+ * @returns {Promise<any>} The parsed JSON.
+ */
+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}`);
+  }
+  return response.json();
+}

src/data/bundledJson.test.mjs

@@ -0,0 +1,83 @@
+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,
+);
+
+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);
+  assert.ok(pack.features.some((ft) => ft.name === 'Gulf of Mexico'));
+  assert.equal(fetchMock.mock.callCount(), 0);
+});
+
+test('bundled JSON: a served URL is fetched as plain JSON', async (t) => {
+  const requests = [];
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    requests.push(String(url));
+    return new Response('{"features":[]}', {
+      headers: { 'content-type': 'application/json' },
+    });
+  });
+  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 }),
+  );
+  await assert.rejects(
+    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/cameraArrival.js

@@ -0,0 +1,16 @@
+/** Arrival corrections belong to one viewer and yield to its next camera owner. */
+const arrivals = new WeakMap();
+
+/** Cancel an outstanding arrival correction before navigation or teardown. */
+export function cancelCameraArrival(viewer) {
+  if (viewer) arrivals.get(viewer)?.();
+}
+
+/** Register a correction and return an idempotent ownership release. */
+export function ownCameraArrival(viewer, cancel) {
+  cancelCameraArrival(viewer);
+  arrivals.set(viewer, cancel);
+  return () => {
+    if (arrivals.get(viewer) === cancel) arrivals.delete(viewer);
+  };
+}

src/data/cameraFraming.js

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

src/data/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/cctvHlsStream.test.mjs

@@ -0,0 +1,225 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createHlsPuller,
+  fetchHlsBytes,
+  parseHlsMedia,
+  HLS_LIMITS,
+} from '../../server/providers/cctv/stream.js';
+const playlist =
+  '#EXTM3U\n#EXT-X-MEDIA-SEQUENCE:12\n#EXTINF:2,\na.ts\n#EXTINF:2,\nb.ts\n#EXTINF:2,\nc.ts\n';
+const base = 'https://camera.example/live/list.m3u8';
+
+test('playlist parser uses sequence, refuses escaping and unsupported references', () => {
+  assert.deepEqual(
+    parseHlsMedia(playlist, base).map((s) => s.seq),
+    [12, 13, 14],
+  );
+  for (const bad of [
+    playlist.replace('a.ts', 'https://evil.example/a.ts'),
+    playlist.replace('a.ts', '//evil.example/a.ts'),
+    '#EXTM3U\n#EXT-X-KEY:METHOD=AES-128\n' + playlist,
+    playlist.replace('12', '-1'),
+    playlist.replace('2,', 'Infinity,'),
+  ])
+    assert.throws(() => parseHlsMedia(bad, base));
+});
+
+test('downloads reject redirect responses, oversized declared and chunked bodies', async () => {
+  let init;
+  await assert.rejects(
+    fetchHlsBytes(base, {
+      maxBytes: 5,
+      fetchImpl: async (_url, options) => {
+        init = options;
+        return new Response('', {
+          status: 302,
+          headers: { Location: 'https://evil.example' },
+        });
+      },
+    }),
+  );
+  assert.equal(init.redirect, 'error');
+  await assert.rejects(
+    fetchHlsBytes(base, {
+      maxBytes: 5,
+      fetchImpl: async () => new Response('abcdef'),
+    }),
+  );
+  await assert.rejects(
+    fetchHlsBytes(base, {
+      maxBytes: 5,
+      fetchImpl: async () =>
+        new Response('a', { headers: { 'content-length': '100' } }),
+    }),
+  );
+});
+
+test('one session is reserved before await; disk-free cache and capacity remain bounded', async () => {
+  const manager = createHlsPuller({
+    limits: {
+      ...HLS_LIMITS,
+      sessions: 1,
+      segmentBytes: 4,
+      sessionBytes: 6,
+      segments: 2,
+      pollMs: 100000,
+    },
+    fetchImpl: async (url) =>
+      new Response(url.endsWith('.m3u8') ? playlist : 'abc'),
+  });
+  const [a, b] = await Promise.all([
+    manager.ensure('a', base),
+    manager.ensure('a', base),
+  ]);
+  assert.equal(a, b);
+  await assert.rejects(manager.ensure('b', base));
+  assert.equal(await manager.waitReady(a), true);
+  assert.deepEqual(manager.stats(), { sessions: 1, bytes: 6 });
+  const text = await manager.buildPlaylist(a, 'a');
+  assert.match(text, /seg_0\.ts\?session=/);
+  assert.equal(manager.getSegment('a', 'stale-token', 0), null);
+  assert.equal(manager.getSegment('a', a.token, 0).length, 3);
+  manager.stop('a', 'stale-token');
+  assert.equal(manager.stats().sessions, 1);
+  manager.stop('a', a.token);
+  assert.deepEqual(manager.stats(), { sessions: 0, bytes: 0 });
+  await manager.shutdown();
+});
+
+test('shutdown cancels in-flight downloads and late responses cannot refill cache', async () => {
+  let observed;
+  const manager = createHlsPuller({
+    fetchImpl: async (_url, { signal }) => {
+      observed = signal;
+      return new Promise((resolve, reject) =>
+        signal.addEventListener('abort', () => reject(new Error('cancelled')), {
+          once: true,
+        }),
+      );
+    },
+  });
+  const entry = await manager.ensure('a', base);
+  await manager.shutdown();
+  assert.equal(observed.aborted, true);
+  assert.equal(entry.stopping, true);
+  assert.deepEqual(manager.stats(), { sessions: 0, bytes: 0 });
+  await assert.rejects(manager.ensure('a', base));
+});
+
+test('idle cleanup stops all polling without a background sweep', async () => {
+  let calls = 0;
+  const manager = createHlsPuller({
+    limits: { ...HLS_LIMITS, idleMs: 15, pollMs: 100000 },
+    fetchImpl: async (url) => {
+      calls++;
+      return new Response(url.endsWith('.m3u8') ? playlist : 'abc');
+    },
+  });
+  await manager.ensure('a', base);
+  await new Promise((r) => setTimeout(r, 50));
+  assert.deepEqual(manager.stats(), { sessions: 0, bytes: 0 });
+  const stoppedCalls = calls;
+  await new Promise((r) => setTimeout(r, 30));
+  assert.equal(calls, stoppedCalls);
+  await manager.shutdown();
+});
+
+test('agency sequence rollback creates a monotonic local discontinuity', async () => {
+  let current = playlist;
+  const manager = createHlsPuller({
+    limits: { ...HLS_LIMITS, pollMs: 5 },
+    fetchImpl: async (url) =>
+      new Response(url.endsWith('.m3u8') ? current : 'abc'),
+  });
+  const entry = await manager.ensure('a', base);
+  await manager.waitReady(entry);
+  const before = await manager.buildPlaylist(entry, 'a');
+  assert.match(before, /seg_0\.ts/);
+  current = playlist.replace('SEQUENCE:12', 'SEQUENCE:0');
+  await new Promise((r) => setTimeout(r, 30));
+  const after = await manager.buildPlaylist(entry, 'a');
+  assert.match(
+    after,
+    /#EXT-X-DISCONTINUITY\n#EXTINF:2\.000,\n\/api\/cctv\/media\/a\/seg_3\.ts/,
+  );
+  await manager.shutdown();
+});
+
+test('upstream discontinuity tags survive the media parser', () => {
+  const parsed = parseHlsMedia(
+    playlist.replace('a.ts', 'a.ts\n#EXT-X-DISCONTINUITY'),
+    base,
+  );
+  assert.equal(parsed[0].discontinuity, false);
+  assert.equal(parsed[1].discontinuity, true);
+});
+
+test('a reused agency sequence with changed segment URI cannot remain stale', async () => {
+  let current = playlist;
+  const manager = createHlsPuller({
+    limits: { ...HLS_LIMITS, pollMs: 5 },
+    fetchImpl: async (url) =>
+      new Response(url.endsWith('.m3u8') ? current : 'abc'),
+  });
+  const entry = await manager.ensure('a', base);
+  await manager.waitReady(entry);
+  current = playlist.replaceAll('.ts', '.ts?generation=2');
+  await new Promise((r) => setTimeout(r, 30));
+  assert.match(
+    await manager.buildPlaylist(entry, 'a'),
+    /#EXT-X-DISCONTINUITY\n#EXTINF:2\.000,\n\/api\/cctv\/media\/a\/seg_3\.ts/,
+  );
+  await manager.shutdown();
+});
+
+test('two consumers share downloads but release and abandoned expiry are independent', async () => {
+  let downloads = 0;
+  const manager = createHlsPuller({
+    limits: { ...HLS_LIMITS, pollMs: 100000, leasesPerSession: 2 },
+    fetchImpl: async (url) => {
+      downloads++;
+      return new Response(url.endsWith('.m3u8') ? playlist : 'abc');
+    },
+  });
+  const [a, b] = await Promise.all([
+    manager.ensure('camera', base, 'viewer-a'),
+    manager.ensure('camera', base, 'viewer-b'),
+  ]);
+  assert.equal(a, b);
+  await manager.waitReady(a);
+  assert.equal(downloads, 4); // One manifest and three segments, not per consumer.
+  assert.equal(a.leases.size, 2);
+  await assert.rejects(manager.ensure('camera', base, 'viewer-c'));
+  manager.release('camera', 'viewer-a');
+  assert.equal(manager.stats().sessions, 1);
+  assert.equal(manager.getSegment('camera', a.token, 0, 'viewer-a'), null);
+  assert.equal(manager.getSegment('camera', a.token, 0, 'viewer-b').length, 3);
+  assert.match(
+    await manager.buildPlaylist(b, 'camera', 'viewer-b'),
+    /lease=viewer-b/,
+  );
+  manager.release('camera', 'viewer-a'); // Duplicate/late release cannot stop B.
+  assert.equal(b.controller.signal.aborted, false);
+  manager.release('camera', 'viewer-b');
+  assert.equal(b.controller.signal.aborted, true);
+  assert.deepEqual(manager.stats(), { sessions: 0, bytes: 0 });
+  await manager.shutdown();
+});
+
+test('an abandoned consumer expires while a renewed consumer keeps the session', async () => {
+  const manager = createHlsPuller({
+    limits: { ...HLS_LIMITS, idleMs: 80, pollMs: 100000 },
+    fetchImpl: async (url) =>
+      new Response(url.endsWith('.m3u8') ? playlist : 'abc'),
+  });
+  const entry = await manager.ensure('camera', base, 'abandoned');
+  await manager.ensure('camera', base, 'active');
+  await new Promise((r) => setTimeout(r, 50));
+  await manager.ensure('camera', base, 'active');
+  await new Promise((r) => setTimeout(r, 50));
+  assert.equal(entry.leases.has('abandoned'), false);
+  assert.equal(entry.leases.has('active'), true);
+  assert.equal(entry.controller.signal.aborted, false);
+  await manager.shutdown();
+});

src/data/cctvMediaRange.test.mjs

@@ -8,8 +8,9 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import http from 'node:http';
 import net from 'node:net';
-import { Readable } from 'node:stream';
+import { Readable, Writable } from 'node:stream';
 import { cctvProxy } from '../../server/providers/cctv.js';
+import { proxyMediaResponse } from '../../server/providers/cctv/media.js';
 import { sanitizeCctvRangeHeader } from '../../server/providers/cctv/range.js';
 import { CCTV_MEDIA_MAX_BODY_BYTES as CAP } from '../../server/providers/cctv/constants.js';
 
@@ -586,3 +587,117 @@ test('two sequential seeks are served as two partial responses', async (t) => {
   assert.equal(first.body, 'chunk-0');
   assert.equal(second.body, 'chunk-100');
 });
+
+// ---------------------------------------------------------------------------
+// The body idle deadline. proxyMediaResponse is driven directly here because
+// the deadline is only injectable through its options; the route always passes
+// the production value.
+// ---------------------------------------------------------------------------
+
+/**
+ * A response to pipe into, built on a real Writable so the backpressure the
+ * proxy reads is the stream's own rather than a flag the test sets. With
+ * `drains: false` the bytes are accepted and never flushed, which is what a
+ * viewer on a slow link looks like from the server side.
+ */
+function pipeTarget({ drains = true } = {}) {
+  const res = new Writable({
+    // One byte is enough to leave a target that never empties its buffer
+    // permanently in need of a drain.
+    highWaterMark: drains ? undefined : 1,
+    write(_chunk, _encoding, callback) {
+      if (drains) callback();
+    },
+  });
+  res.writeHead = (status, headers) => {
+    res.statusCode = status;
+    res.headers = headers || {};
+  };
+  return res;
+}
+
+/**
+ * An upstream that answers with headers, sends one chunk, and then either
+ * keeps producing every `everyMs` or goes silent. `released` reports the body's
+ * own cleanup: a cancelled fetch body lands in the web stream's cancel hook.
+ */
+function mediaUpstream({ everyMs = 0 } = {}) {
+  const state = { produced: 0, released: false };
+  let ticker = null;
+  const body = new ReadableStream({
+    start(controller) {
+      const send = () => {
+        state.produced += 1;
+        controller.enqueue(new Uint8Array([0xff, 0xd8, 0xff, 0xe0]));
+      };
+      send();
+      if (everyMs > 0) {
+        ticker = setInterval(send, everyMs);
+        ticker.unref();
+      }
+    },
+    cancel() {
+      state.released = true;
+      if (ticker) clearInterval(ticker);
+    },
+  });
+  state.upstream = {
+    ok: true,
+    status: 200,
+    headers: {
+      get: (name) =>
+        String(name).toLowerCase() === 'content-type' ? 'video/mp4' : null,
+    },
+    body,
+    arrayBuffer: async () => Buffer.alloc(0),
+  };
+  return state;
+}
+
+test('an upstream that goes silent after its headers is released at the idle deadline', async (t) => {
+  const feed = mediaUpstream();
+  const res = pipeTarget();
+  t.after(() => res.destroy());
+  await proxyMediaResponse(res, feed.upstream, { idleTimeoutMs: 40 });
+
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  assert.equal(feed.released, false, 'released before the deadline was due');
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  // Without the deadline this stream is held open against the camera host for
+  // as long as that host will keep the socket, with no bytes ever arriving.
+  assert.equal(feed.released, true, 'the silent upstream was never released');
+  assert.equal(res.writableEnded, true, 'the client was left waiting');
+});
+
+test('a live feed that keeps producing is not cut off by the idle deadline', async (t) => {
+  const feed = mediaUpstream({ everyMs: 10 });
+  const res = pipeTarget();
+  t.after(() => res.destroy());
+  await proxyMediaResponse(res, feed.upstream, { idleTimeoutMs: 40 });
+
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  assert.equal(feed.released, false, 'a healthy feed was torn down');
+  assert.equal(res.writableEnded, false, 'a healthy feed was ended early');
+  assert.ok(
+    feed.produced > 5,
+    `the feed stopped producing (${feed.produced} chunks)`,
+  );
+});
+
+test('a client that cannot keep up is not mistaken for a stalled upstream', async (t) => {
+  // Nothing arrives from upstream while the pipe is paused, which looks exactly
+  // like silence unless the response is asked whether it is still draining.
+  const feed = mediaUpstream({ everyMs: 10 });
+  const res = pipeTarget({ drains: false });
+  t.after(() => res.destroy());
+  await proxyMediaResponse(res, feed.upstream, { idleTimeoutMs: 30 });
+
+  await new Promise((resolve) => setTimeout(resolve, 200));
+  assert.equal(
+    res.writableNeedDrain,
+    true,
+    'the client was not the bottleneck',
+  );
+  assert.equal(feed.released, false, 'a slow viewer tore down a healthy feed');
+  assert.equal(res.writableEnded, false, 'a slow viewer ended the response');
+});

src/data/cctvNyc.test.mjs

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

src/data/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/cyclonesProxy.test.mjs

@@ -0,0 +1,454 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import {
+  cycloneProxy,
+  parseCycloneStatus,
+  attachCycloneGeometry,
+} from '../../server/providers/cyclones.js';
+
+const NOW = Date.UTC(2026, 8, 16, 3, 35);
+const TIME = '2026-09-16T03:00:00.000Z';
+function status(overrides = {}) {
+  return {
+    activeStorms: [
+      {
+        id: 'ep152026',
+        name: 'Fifteen-E',
+        classification: 'PTC',
+        intensity: '25',
+        pressure: '1006',
+        longitudeNumeric: -125.8,
+        latitudeNumeric: 15.5,
+        movementDir: 255,
+        movementSpeed: 12,
+        lastUpdate: TIME,
+        forecastAdvisory: {
+          advNum: '010',
+          issuance: TIME,
+          url: 'https://www.nhc.noaa.gov/text/MIATCMEP5.shtml',
+        },
+        ...overrides,
+      },
+    ],
+  };
+}
+function collections(adv = '10') {
+  const geometry = [
+    { type: 'Point', coordinates: [-125.8, 15.5] },
+    {
+      type: 'LineString',
+      coordinates: [
+        [-125.8, 15.5],
+        [-128, 15],
+      ],
+    },
+    {
+      type: 'Polygon',
+      coordinates: [
+        [
+          [-126, 15],
+          [-128, 15],
+          [-127, 17],
+          [-126, 15],
+        ],
+      ],
+    },
+  ];
+  return geometry.map((shape, index) => ({
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        properties: {
+          idp_source: `ep152026-${adv.padStart(3, '0')}_5day_${['pts', 'lin', 'pgn'][index]}`,
+          advisnum: adv,
+          tau: 0,
+          maxwind: 25,
+          gust: 9999,
+        },
+        geometry: shape,
+      },
+    ],
+  }));
+}
+function install(options = {}, preview = false) {
+  let handler;
+  const plugin = cycloneProxy({ now: () => NOW, ...options });
+  plugin[preview ? 'configurePreviewServer' : 'configureServer']({
+    middlewares: {
+      use(path, callback) {
+        assert.equal(path, '/api/cyclones');
+        handler = callback;
+      },
+    },
+  });
+  const begin = (url = '/', method = 'GET') => {
+    const res = new EventEmitter();
+    res.writeHead = (code, headers) => {
+      res.statusCode = code;
+      res.headers = headers;
+    };
+    res.end = (body) => {
+      res.body = body;
+    };
+    return { res, done: handler({ url, method }, res).then(() => res) };
+  };
+  return { begin, request: (url, method) => begin(url, method).done };
+}
+const body = (res) => JSON.parse(res.body);
+const nextTurn = () => new Promise((resolve) => setImmediate(resolve));
+function fetcher(calls = [], data = status(), parts = collections()) {
+  return async (url, options) => {
+    calls.push({ url: new URL(url), options });
+    return Response.json(
+      url.includes('CurrentStorms')
+        ? data
+        : parts[Number(url.match(/\/(\d)\/query/)[1]) - 5],
+    );
+  };
+}
+
+test('status retains official clocks, knots, source links and finite current position', () => {
+  const storm = parseCycloneStatus(status(), NOW)[0];
+  assert.equal(storm.advisoryNumber, '10');
+  assert.equal(storm.issuedAt, TIME);
+  assert.equal(storm.positionAt, TIME);
+  assert.deepEqual(storm.position, { longitude: -125.8, latitude: 15.5 });
+  assert.deepEqual(storm.movement, { directionDegrees: 255, speedKt: 12 });
+  assert.equal(storm.windKt, 25);
+  assert.equal(storm.pressureHpa, 1006);
+  assert.match(storm.advisoryUrl, /^https:\/\/www\.nhc\.noaa\.gov\/text\//);
+  const missing = parseCycloneStatus(
+    status({ intensity: '9999', pressure: null, movementSpeed: '' }),
+    NOW,
+  )[0];
+  assert.equal(missing.windKt, null);
+  assert.equal(missing.pressureHpa, null);
+  assert.equal(missing.movement.speedKt, null);
+  assert.equal(
+    parseCycloneStatus(
+      status({
+        forecastAdvisory: {
+          advNum: '10',
+          issuance: TIME,
+          url: 'https://www.nhc.noaa.gov.evil/secret',
+        },
+      }),
+      NOW,
+    )[0].advisoryUrl,
+    null,
+  );
+});
+
+test('malformed, duplicate, oversized, future and expired status is rejected rather than reported empty', () => {
+  for (const payload of [
+    {},
+    { activeStorms: null },
+    { activeStorms: Array(33).fill(status().activeStorms[0]) },
+    { activeStorms: [...status().activeStorms, ...status().activeStorms] },
+    status({ id: 'wp012026' }),
+    status({ name: 'a'.repeat(81) }),
+    status({ name: '<script>' }),
+    status({ longitudeNumeric: Infinity }),
+    status({ latitudeNumeric: 91 }),
+    status({ lastUpdate: '2026-09-17T00:00:00.000Z' }),
+    status({ lastUpdate: '2026-02-30T00:00:00.000Z' }),
+    status({
+      forecastAdvisory: { advNum: '10', issuance: '2026-09-15T03:00:00.000Z' },
+    }),
+  ])
+    assert.throws(() => parseCycloneStatus(payload, NOW));
+  assert.deepEqual(parseCycloneStatus({ activeStorms: [] }, NOW), []);
+});
+
+test('coherent geometry is retained with holes/dateline while older advisory geometry is omitted', () => {
+  const storms = parseCycloneStatus(status(), NOW);
+  const parts = collections();
+  parts[1].features[0].geometry.coordinates = [
+    [179, 15],
+    [-179, 16],
+  ];
+  parts[2].features[0].geometry.coordinates.push([
+    [-126.5, 15.5],
+    [-127, 15.5],
+    [-126.8, 16],
+    [-126.5, 15.5],
+  ]);
+  const good = attachCycloneGeometry(storms, parts)[0];
+  assert.equal(good.geometryStatus, 'current');
+  assert.equal(good.geometryAdvisoryNumber, '10');
+  assert.deepEqual(good.track, parts[1].features[0].geometry);
+  assert.equal(good.cone.coordinates.length, 2);
+  assert.equal(good.forecastPoints[0].gustKt, null);
+  assert.equal(good.forecastPoints[0].tauHours, 0);
+  assert.equal(
+    'validAt' in good.forecastPoints[0],
+    false,
+    'do not fabricate point time from advisory + tau',
+  );
+  const old = attachCycloneGeometry(storms, collections('9'))[0];
+  assert.equal(old.geometryStatus, 'pending');
+  assert.equal(old.track, null);
+  assert.equal(old.cone, null);
+  assert.deepEqual(old.forecastPoints, []);
+  assert.deepEqual(old.position, storms[0].position);
+  const mixed = collections();
+  mixed[2] = collections('9')[2];
+  const partial = attachCycloneGeometry(storms, mixed)[0];
+  assert.equal(partial.geometryStatus, 'pending');
+  assert.equal(
+    partial.track,
+    null,
+    'a new track and old cone cannot form one advisory snapshot',
+  );
+});
+
+test('geometry rejects transfer truncation, duplicate tracks, invalid coordinates and structural budgets', () => {
+  const storms = parseCycloneStatus(status(), NOW);
+  const mutations = [
+    (p) => {
+      p[0].exceededTransferLimit = true;
+    },
+    (p) => {
+      p[0].features = Array(501).fill(p[0].features[0]);
+    },
+    (p) => {
+      p[1].features.push(p[1].features[0]);
+    },
+    (p) => {
+      p[0].features.push(p[0].features[0]);
+    },
+    (p) => {
+      p[0].features[0].properties.idp_source = 'ep152026-009_5day_pts';
+    },
+    (p) => {
+      p[1].features[0].geometry.coordinates[1] = [181, 1];
+    },
+    (p) => {
+      p[2].features[0].geometry.coordinates[0].pop();
+    },
+    (p) => {
+      p[1].features[0].geometry.coordinates = Array(10001).fill([0, 0]);
+    },
+    (p) => {
+      p[1].features[0].geometry = {
+        type: 'MultiLineString',
+        coordinates: Array.from({ length: 3 }, () => Array(9000).fill([0, 0])),
+      };
+    },
+    (p) => {
+      p[2].features[0].geometry = {
+        type: 'GeometryCollection',
+        geometries: [],
+      };
+    },
+  ];
+  for (const mutate of mutations) {
+    const parts = collections();
+    mutate(parts);
+    assert.throws(() => attachCycloneGeometry(storms, parts));
+  }
+});
+
+test('dev and preview serve only fixed bounded NOAA queries, caching a complete snapshot', async () => {
+  for (const preview of [false, true]) {
+    const calls = [];
+    const { request } = install({ fetchImpl: fetcher(calls) }, preview);
+    const snapshot = body(await request());
+    assert.equal(snapshot.unavailable, false);
+    assert.equal(snapshot.stale, false);
+    assert.match(snapshot.coverage, /not worldwide/);
+    assert.equal(snapshot.storms[0].geometryStatus, 'current');
+    assert.equal(snapshot.fetchedAt, NOW);
+    assert.equal(calls.length, 4);
+    assert.equal(
+      calls[0].url.href,
+      'https://www.nhc.noaa.gov/CurrentStorms.json',
+    );
+    for (const call of calls) assert.equal(call.options.redirect, 'error');
+    for (const call of calls.slice(1)) {
+      assert.equal(call.url.origin, 'https://mapservices.weather.noaa.gov');
+      assert.equal(call.url.searchParams.get('outSR'), '4326');
+      assert.equal(call.url.searchParams.get('f'), 'geojson');
+      assert.notEqual(call.url.searchParams.get('outFields'), '*');
+    }
+    assert.equal(
+      calls[2].url.searchParams.get('outFields'),
+      'idp_source,advisnum',
+    );
+    assert.deepEqual(body(await request()), snapshot);
+    assert.equal(calls.length, 4);
+  }
+});
+
+test('query/method rejection cannot redirect or widen provider work', async () => {
+  let calls = 0;
+  const { request } = install({
+    fetchImpl: async () => {
+      calls++;
+      throw new Error('unexpected');
+    },
+  });
+  for (const url of [
+    '/?url=https://evil',
+    '/?storm=ep152026',
+    '/other',
+    '/?bbox=0,0,1,1',
+  ])
+    assert.equal((await request(url)).statusCode, 400);
+  assert.equal((await request('/', 'POST')).statusCode, 405);
+  assert.equal(calls, 0);
+});
+
+test('confirmed empty status skips GIS; broken GIS keeps honest current positions', async () => {
+  const calls = [];
+  const empty = install({ fetchImpl: fetcher(calls, { activeStorms: [] }) });
+  assert.deepEqual(body(await empty.request()).storms, []);
+  assert.equal(body(await empty.request()).unavailable, false);
+  assert.equal(calls.length, 1);
+  const broken = install({
+    fetchImpl: async (url) =>
+      url.includes('CurrentStorms')
+        ? Response.json(status())
+        : new Response('secret detail', { status: 503 }),
+  });
+  const snapshot = body(await broken.request());
+  assert.equal(snapshot.unavailable, false);
+  assert.equal(snapshot.storms[0].geometryStatus, 'unavailable');
+  assert.equal(snapshot.storms[0].track, null);
+  assert.doesNotMatch(JSON.stringify(snapshot), /secret/);
+});
+
+test('five-minute TTL, failure cooldown and age-limited last-good retain original advisory/fetch clocks', async () => {
+  let clock = NOW;
+  let fail = false;
+  let calls = 0;
+  const good = fetcher();
+  const { request } = install({
+    now: () => clock,
+    fetchImpl: async (...args) => {
+      calls++;
+      if (fail) throw new Error('private');
+      return good(...args);
+    },
+  });
+  await request();
+  clock += 299_000;
+  await request();
+  assert.equal(calls, 4);
+  fail = true;
+  clock += 2000;
+  const stale = body(await request());
+  assert.equal(stale.stale, true);
+  assert.equal(stale.fetchedAt, NOW);
+  assert.equal(stale.storms[0].issuedAt, TIME);
+  await request();
+  assert.equal(calls, 5);
+  clock += 12 * 3600_000;
+  const expired = body(await request());
+  assert.equal(expired.unavailable, true);
+  assert.deepEqual(expired.storms, []);
+});
+
+test('shared refresh survives one disconnect and aborts when its last consumer leaves', async () => {
+  let release;
+  let signal;
+  const good = fetcher();
+  const { begin } = install({
+    fetchImpl: async (url, options) => {
+      if (url.includes('CurrentStorms')) {
+        signal = options.signal;
+        await new Promise((resolve, reject) => {
+          release = resolve;
+          signal.addEventListener('abort', () => reject(new Error('aborted')), {
+            once: true,
+          });
+        });
+      }
+      return good(url, options);
+    },
+  });
+  const a = begin();
+  const b = begin();
+  await nextTurn();
+  a.res.emit('close');
+  await a.done;
+  assert.equal(signal.aborted, false);
+  assert.equal(a.res.body, undefined);
+  release();
+  assert.equal(body(await b.done).unavailable, false);
+  let calls = 0;
+  const cancel = install({
+    fetchImpl: async (url, options) => {
+      calls++;
+      if (calls > 1) return good(url, options);
+      signal = options.signal;
+      return new Promise((_, reject) =>
+        signal.addEventListener('abort', () => reject(new Error('aborted')), {
+          once: true,
+        }),
+      );
+    },
+  });
+  const c = cancel.begin();
+  await nextTurn();
+  c.res.emit('close');
+  await c.done;
+  assert.equal(signal.aborted, true);
+  assert.equal(
+    body(await cancel.request()).unavailable,
+    false,
+    'cancellation does not impose upstream failure cooldown',
+  );
+});
+
+test('stream caps and whole refresh deadline cancel oversized or stalled response bodies', async () => {
+  for (const stalled of [false, true]) {
+    let cancelled = false;
+    const { request } = install({
+      timeoutMs: 15,
+      fetchImpl: async () =>
+        new Response(
+          new ReadableStream({
+            start(controller) {
+              controller.enqueue(new Uint8Array(stalled ? 4 : 128 * 1024 + 1));
+            },
+            cancel() {
+              cancelled = true;
+            },
+          }),
+        ),
+    });
+    const snapshot = body(await request());
+    assert.equal(snapshot.unavailable, true);
+    assert.equal(cancelled, true);
+  }
+});
+
+test('shared refresh caps waiting consumers and rejects redirects without exposing upstream errors', async () => {
+  let release;
+  const good = fetcher();
+  const { request } = install({
+    fetchImpl: async (url, options) => {
+      if (url.includes('CurrentStorms'))
+        await new Promise((resolve) => {
+          release = resolve;
+        });
+      return good(url, options);
+    },
+  });
+  const waiting = Array.from({ length: 32 }, () => request());
+  await nextTurn();
+  assert.equal((await request()).statusCode, 429);
+  release();
+  assert.ok((await Promise.all(waiting)).every((r) => r.statusCode === 200));
+  const redirected = install({
+    fetchImpl: async () =>
+      new Response('private', {
+        status: 302,
+        headers: { Location: 'http://127.0.0.1/' },
+      }),
+  });
+  assert.equal(body(await redirected.request()).unavailable, true);
+});

src/data/dataCredits.js

@@ -25,6 +25,79 @@ import * as Cesium from 'cesium';
  * follows DATA_SOURCES.md (live sources, then bundled snapshots).
  * @type {{ key: string, html: string }[]}
  */
+export const OSM_CREDIT = {
+  key: 'openstreetmap',
+  html: 'Map and place data <a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> (<a href="https://opendatacommons.org/licenses/odbl/1-0/" target="_blank" rel="noopener">ODbL</a>)',
+};
+export const OPENMAPTILES_CREDIT = {
+  key: 'openfreemap',
+  html: 'Vector tiles: <a href="https://openfreemap.org" target="_blank" rel="noopener">OpenFreeMap</a> © <a href="https://openmaptiles.org" target="_blank" rel="noopener">OpenMapTiles</a>',
+};
+
+const osmDisplays = new WeakMap();
+
+function updateOsmDisplay(viewer, state) {
+  const osm = state.owners.size > 0;
+  let tiles = false;
+  for (const usesTiles of state.owners.values()) tiles ||= usesTiles;
+  for (const [key, visible] of [
+    ['osm', osm],
+    ['tiles', tiles],
+  ]) {
+    if (state[key].visible === visible) continue;
+    state[key].visible = visible;
+    viewer.creditDisplay[visible ? 'addStaticCredit' : 'removeStaticCredit'](
+      state[key].credit,
+    );
+    viewer.scene?.requestRender?.();
+  }
+}
+
+/** Keep one short inline credit while an OSM display owner has visible data. */
+export function showOsmCredit(viewer, owner, { openMapTiles = false } = {}) {
+  if (!viewer?.creditDisplay?.addStaticCredit || !owner) return false;
+  let state = osmDisplays.get(viewer);
+  if (!state) {
+    state = {
+      owners: new Map(),
+      osm: {
+        visible: false,
+        credit: new Cesium.Credit(
+          '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap</a>',
+          true,
+        ),
+      },
+      tiles: {
+        visible: false,
+        credit: new Cesium.Credit(
+          '<a href="https://openmaptiles.org" target="_blank" rel="noopener">© OpenMapTiles</a>',
+          true,
+        ),
+      },
+    };
+    osmDisplays.set(viewer, state);
+  }
+  if (state.owners.get(owner) === openMapTiles) return false;
+  state.owners.set(owner, openMapTiles);
+  updateOsmDisplay(viewer, state);
+  return true;
+}
+
+/** Release only this owner's credit; other displayed OSM sources retain theirs. */
+export function hideOsmCredit(viewer, owner) {
+  const state = osmDisplays.get(viewer);
+  if (!state?.owners.delete(owner)) return false;
+  updateOsmDisplay(viewer, state);
+  return true;
+}
+
+/** NYC DOT asks every application that uses its data to carry this
+ * disclaimer verbatim (nyc.gov/html/dot/html/about/datafeeds.shtml). */
+export const NYC_DOT_DISCLAIMER =
+  'This application may contain and/or utilize information which was originally compiled by the New York City Department of Transportation (NYC DOT) for governmental purposes; the information may subsequently been modified by entity/entities other than NYC DOT. ' +
+  'NYC DOT and the City of New York make no representation as to the accuracy or usefulness of the information provided by this application or the information&#39;s suitability for any purpose and disclaim any liability for omissions or errors that may be contained therein. ' +
+  'The public is advised to observe posted signage for compliance with applicable laws and regulations.';
+
 export const DATA_CREDITS = [
   // ── Live sources ────────────────────────────────────────────────
   {
@@ -38,10 +111,21 @@ export const DATA_CREDITS = [
   {
     key: 'adsblol',
     html:
-      'Military flights, aircraft traces &amp; bounded regional flight fallback: ' +
+      'Military flights, aircraft traces, bounded regional flight fallback &amp; GNSS navigation integrity: ' +
       '<a href="https://adsb.lol" target="_blank" rel="noopener">adsb.lol</a> ' +
       '(ODbL 1.0)',
   },
+  {
+    key: 'adsbdb',
+    html:
+      'Aircraft type, registration &amp; flight routes: ' +
+      '<a href="https://www.adsbdb.com" target="_blank" rel="noopener">adsbdb</a> ' +
+      '· aircraft data from PlaneBase · ICAO-to-N-number conversion by ' +
+      'Guillaume Michel · route data is the work of ' +
+      'David Taylor, Edinburgh, and Jim Mason, Glasgow, and may not be ' +
+      'copied, published, or incorporated into other databases without the ' +
+      'explicit permission of David J Taylor, Edinburgh',
+  },
   {
     key: 'aisstream',
     html:
@@ -67,41 +151,38 @@ export const DATA_CREDITS = [
     html: 'Earthquakes: Data courtesy of the U.S. Geological Survey',
   },
   {
-    key: 'overpass',
+    key: 'nasa-gibs',
     html:
-      'Road geometry (traffic): ' +
-      '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> ' +
-      '(ODbL 1.0)',
+      'Recent imagery: We acknowledge the use of imagery provided by services from ' +
+      "NASA's Global Imagery Browse Services (GIBS), part of NASA's Earth Science " +
+      'Data and Information System (ESDIS). ' +
+      '<a href="https://gibs.earthdata.nasa.gov" target="_blank" rel="noopener">gibs.earthdata.nasa.gov</a> · ' +
+      '<a href="https://lpdaac.usgs.gov/products/hlss30v002/" target="_blank" rel="noopener">HLS product page</a>',
+  },
+  {
+    key: 'wfigs',
+    html:
+      'Wildfire perimeters: ' +
+      '<a href="https://data-nifc.opendata.arcgis.com/" target="_blank" rel="noopener">National Interagency Fire Center (WFIGS)</a>' +
+      ' · Incident information: ' +
+      '<a href="https://inciweb.wildfire.gov/" target="_blank" rel="noopener">InciWeb</a>',
+  },
+  OSM_CREDIT,
+  OPENMAPTILES_CREDIT,
+  {
+    key: 'eccc-aqhi',
+    html:
+      'Air quality (AQHI): Environment and Climate Change Canada — MSC GeoMet ' +
+      '(<a href="https://eccc-msc.github.io/open-data/" target="_blank" rel="noopener">eccc-msc.github.io/open-data</a>) ' +
+      '· <a href="https://eccc-msc.github.io/open-data/licence/readme_en/" target="_blank" rel="noopener">ECCC Data Servers End-use Licence</a>',
+  },
+  {
+    key: 'overture-military-names',
+    html: 'Military area names: <a href="https://overturemaps.org" target="_blank" rel="noopener">Overture Maps Foundation</a> (ODbL)',
   },
   {
     key: 'photon-geocoder',
-    html:
-      'Keyless place search: ' +
-      '<a href="https://photon.komoot.io" target="_blank" rel="noopener">Photon</a> (komoot) over ' +
-      '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> ' +
-      '(ODbL 1.0)',
-  },
-  {
-    key: 'alpr-osm',
-    html:
-      'ALPR camera locations (automatic license plate readers): ' +
-      '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> ' +
-      '(<a href="https://opendatacommons.org/licenses/odbl/1-0/" target="_blank" rel="noopener">ODbL 1.0</a>); ' +
-      'community mapping includes <a href="https://deflock.org" target="_blank" rel="noopener">DeFlock</a>',
-  },
-  {
-    key: 'military-installations-osm',
-    html:
-      'Mapped installation context: ' +
-      '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> ' +
-      '(ODbL 1.0; incomplete mapped context)',
-  },
-  {
-    key: 'cockpit-place-osm',
-    html:
-      'Cockpit place context and last-resort place search: ' +
-      '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> ' +
-      'via Nominatim (ODbL 1.0)',
+    html: 'Keyless place search: <a href="https://photon.komoot.io" target="_blank" rel="noopener">Photon</a> (komoot)',
   },
   {
     key: 'open-meteo',
@@ -136,6 +217,10 @@ export const DATA_CREDITS = [
       'CCTV cameras &amp; frames (Texas): ' +
       '<a href="https://its.txdot.gov/" target="_blank" rel="noopener">Texas Department of Transportation</a> (courtesy)',
   },
+  {
+    key: 'deldot-cctv',
+    html: 'CCTV live video (Delaware): <a href="https://deldot.gov/map/" target="_blank" rel="noopener">DelDOT — Delaware Department of Transportation</a>',
+  },
   {
     key: 'caltrans-cctv',
     html:
@@ -175,9 +260,45 @@ export const DATA_CREDITS = [
       'Traffic cameras (Calgary): contains information licensed under the ' +
       '<a href="https://data.calgary.ca/stories/s/Open-Calgary-Terms-of-Use/u45n-7awa" target="_blank" rel="noopener">Open Government Licence – City of Calgary</a>',
   },
+  {
+    key: 'vegvesen-cctv',
+    html:
+      'Road cameras (Norway): contains data under the ' +
+      '<a href="https://data.norge.no/nlod/en/2.0" target="_blank" rel="noopener">Norwegian licence for Open Government data (NLOD)</a> ' +
+      'distributed by Statens vegvesen',
+  },
+  {
+    key: 'nyc-cctv',
+    html:
+      'CCTV cameras &amp; frames (New York City, when enabled): ' +
+      '<a href="https://webcams.nyctmc.org/" target="_blank" rel="noopener">NYC DOT Traffic Management Center</a>. ' +
+      NYC_DOT_DISCLAIMER,
+  },
   {
     key: 'gbfs',
-    html: 'Bikeshare availability: GBFS operator feeds (e.g. Austin BCycle)',
+    html:
+      'Bikeshare availability: GBFS operator feeds ' +
+      '(e.g. Austin BCycle; Bike Share Toronto, operated by the Toronto Parking Authority)',
+  },
+  {
+    key: 'urbansharing-gbfs',
+    html:
+      'City bikes (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> ' +
+      'made available by Oslo Bysykkel, Bergen Bysykkel and Trondheim Bysykkel',
+  },
+  {
+    key: 'entur-mobility-gbfs',
+    html:
+      'City bikes (Stavanger, Skien/Porsgrunn): 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> ' +
+      'made available by Entur (Kolumbus Bysykkel, Farte Bysykkel)',
+  },
+  {
+    key: 'jcdecaux-gbfs',
+    html:
+      'City bikes (Lillestrøm): Bysykkel Lillestrøm, JCDecaux — ' +
+      '<a href="https://developer.jcdecaux.com/files/Open-Licence-fr.pdf" target="_blank" rel="noopener">Licence Ouverte</a>',
   },
   {
     key: 'osrm-routing',
@@ -186,7 +307,6 @@ export const DATA_CREDITS = [
     html:
       'Routing (voice routes and Directions): OSRM on the FOSSGIS servers — ' +
       '<a href="https://routing.openstreetmap.de/about.html" target="_blank" rel="noopener">routing.openstreetmap.de</a> · ' +
-      '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> (ODbL) · ' +
       '<a href="https://www.openstreetmap.org/fixthemap" target="_blank" rel="noopener">fix the map</a>',
   },
   {
@@ -207,20 +327,38 @@ export const DATA_CREDITS = [
       '<a href="https://terrain.reearth.land" target="_blank" rel="noopener">Re:Earth Terrain</a> / ' +
       'Mapterhorn (CC BY 4.0) / EGM2008 (NGA)',
   },
-  // ── Bundled snapshots ───────────────────────────────────────────
   {
-    key: 'datacenters',
-    html:
-      'Datacenters: ' +
-      '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> ' +
-      '(ODbL 1.0)',
+    key: 'weather-noaa',
+    html: 'Observed weather: <a href="https://nowcoast.noaa.gov/" target="_blank" rel="noopener">NOAA nowCOAST</a> · NWS/OAR MRMS radar; NESDIS GOES and global satellite partners. <a href="https://oceanservice.noaa.gov/disclaimer.html" target="_blank" rel="noopener">Source disclaimer</a>.',
   },
   {
-    key: 'dams',
+    key: 'weather-cyclones',
+    html: 'Cyclone advisories: <a href="https://www.nhc.noaa.gov/" target="_blank" rel="noopener">NOAA/NWS NHC / CPHC</a> · Atlantic and eastern/central North Pacific. Forecast center uncertainty, not storm size.',
+  },
+  {
+    key: 'weather-lightning',
+    html: 'Lightning density: NOAA/NWS nowCOAST · derived from Vaisala NLDN/GLD360. <a href="https://ocean.weather.gov/lightning/lightning_pdd.php" target="_blank" rel="noopener">Public derived density product</a>, not raw detections.',
+  },
+  {
+    key: 'wind-gfs',
     html:
-      'Dams: ' +
-      '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> ' +
-      '(ODbL 1.0) + Open Infrastructure Map',
+      'Wind: resampled NOAA Global Forecast System (GFS) 10 m wind via ' +
+      '<a href="https://registry.opendata.aws/noaa-gfs-bdp-pds/" target="_blank" rel="noopener">NOAA Open Data on AWS</a> ' +
+      '(U.S. public domain; forecast, not observations)',
+  },
+  {
+    key: 'ecmwf-ifs',
+    html:
+      'This service is based on data and products of the European Centre for Medium-Range Weather Forecasts (ECMWF). ' +
+      '<a href="https://www.ecmwf.int/en/forecasts/datasets/open-data" target="_blank" rel="noopener">ECMWF Open Data</a> · ' +
+      '<a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="noopener">CC BY 4.0</a>. ' +
+      'Modified: resampled 10 m IFS forecast vectors and animated display. ' +
+      'ECMWF does not accept any liability whatsoever for any error or omission in the data, their availability, or for any loss or damage arising from their use.',
+  },
+  // ── Bundled snapshots ───────────────────────────────────────────
+  {
+    key: 'dams',
+    html: 'Dams: Open Infrastructure Map',
   },
   {
     key: 'firms',
@@ -253,9 +391,7 @@ export const DATA_CREDITS = [
   },
   {
     key: 'warendorf-cctv',
-    html:
-      'Webcam (Warendorf): <a href="https://www.warendorf.de/" target="_blank" rel="noopener">Stadt Warendorf</a> (courtesy); ' +
-      'camera poses derived from OpenStreetMap geometry, © OpenStreetMap contributors (ODbL)',
+    html: 'Webcam (Warendorf): <a href="https://www.warendorf.de/" target="_blank" rel="noopener">Stadt Warendorf</a> (courtesy)',
   },
   {
     key: 'nsw-cctv',
@@ -288,15 +424,24 @@ export const TOMTOM_CREDIT = {
     '<a href="https://www.tomtom.com" target="_blank" rel="noopener">TomTom</a>',
 };
 
-/** Registered when the first Natural Earth region outline resolves (public
- * domain — no attribution required; credited as a courtesy). */
+/** Registered when the first Natural Earth region or state/province outline
+ * resolves (public domain — no attribution required; credited as a courtesy). */
 export const NATURAL_EARTH_CREDIT = {
   key: 'natural-earth',
   html:
-    'Physical region boundaries from ' +
+    'Country, state/province and physical region boundaries from ' +
     '<a href="https://www.naturalearthdata.com" target="_blank" rel="noopener">Natural Earth</a> (public domain)',
 };
 
+/** Registered when the first bundled US county outline resolves (public
+ * domain — credited as a courtesy). */
+export const US_CENSUS_CREDIT = {
+  key: 'us-census-counties',
+  html:
+    'US county boundaries from the ' +
+    '<a href="https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.html" target="_blank" rel="noopener">U.S. Census Bureau</a> (public domain)',
+};
+
 /**
  * Per-feed transit credit, registered the first time that feed's vehicles
  * render (see `src/data/transitFeeds.js` for the license of each).
@@ -332,10 +477,7 @@ export const BHOTE_KOSHI_CREDIT = {
 export const BHOTE_KOSHI_LOCATOR_CREDIT = {
   key: 'bhote-koshi-locator',
   html:
-    'Nepal administrative boundary and nearby-city locations: ' +
-    '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">© OpenStreetMap contributors</a> ' +
-    '(ODbL 1.0); incident-place anchors use an owner-curated, source-verified geolocation union; ' +
-    'flood corridor derived from the ' +
+    'Flood corridor derived from the ' +
     '<a href="https://github.com/geo-pera/bhotekoshi-2026-reconstruction/blob/main/vectors/river_centerline.geojson" target="_blank" rel="noopener">GeoPera river centerline</a> ' +
     '(CC BY-NC 4.0)',
 };

src/data/dataCredits.test.mjs

@@ -0,0 +1,130 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { DATA_CREDITS, NYC_DOT_DISCLAIMER } from './dataCredits.js';
+
+test('every credit carries a unique key and some markup to render', () => {
+  const keys = DATA_CREDITS.map((entry) => entry.key);
+  assert.equal(
+    new Set(keys).size,
+    keys.length,
+    'a duplicate key would silently shadow one provider’s credit',
+  );
+  for (const entry of DATA_CREDITS) {
+    assert.ok(entry.key, 'a credit without a key cannot be registered');
+    assert.ok(
+      entry.html && entry.html.trim().length > 0,
+      `credit ${entry.key} has nothing to show`,
+    );
+  }
+});
+
+test('adsbdb is credited and carries its published route-data restriction', () => {
+  const credit = DATA_CREDITS.find((entry) => entry.key === 'adsbdb');
+  assert.ok(
+    credit,
+    'adsbdb supplies aircraft type and routes and must be credited',
+  );
+  // adsbdb publishes this restriction for its route data. Pin the provider's
+  // credits and restriction here so a later edit cannot silently remove them.
+  assert.match(credit.html, /David Taylor, Edinburgh/);
+  assert.match(credit.html, /Jim Mason, Glasgow/);
+  assert.match(
+    credit.html,
+    /may not be\s+copied, published, or incorporated into other databases/,
+  );
+  assert.match(credit.html, /explicit permission of David J Taylor, Edinburgh/);
+  assert.match(credit.html, /PlaneBase/);
+  assert.match(credit.html, /Guillaume Michel/);
+  assert.match(credit.html, /href="https:\/\/www\.adsbdb\.com"/);
+});
+
+test('OpenStreetMap has one generic data credit with separate tile and names distributors', () => {
+  const osm = DATA_CREDITS.filter((entry) =>
+    entry.html.includes('openstreetmap.org/copyright'),
+  );
+  assert.equal(osm.length, 1);
+  assert.equal(osm[0].key, 'openstreetmap');
+  assert.match(osm[0].html, /Map and place data/);
+  assert.match(osm[0].html, /© OpenStreetMap contributors/);
+  assert.match(
+    DATA_CREDITS.find((entry) => entry.key === 'openfreemap').html,
+    /Vector tiles:/,
+  );
+  assert.match(
+    DATA_CREDITS.find((entry) => entry.key === 'overture-military-names').html,
+    /Overture Maps Foundation/,
+  );
+});
+
+test('inline OSM attribution persists until its last display owner leaves', async (t) => {
+  const { showOsmCredit, hideOsmCredit } = await import('./dataCredits.js');
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const visible = new Set();
+  const viewer = {
+    creditDisplay: {
+      addStaticCredit: (c) => visible.add(c),
+      removeStaticCredit: (c) => visible.delete(c),
+    },
+    scene: { requestRender() {} },
+  };
+  assert.equal(showOsmCredit(viewer, 'alpr'), true);
+  assert.equal(showOsmCredit(viewer, 'alpr'), false);
+  assert.equal(visible.size, 1);
+  assert.match(
+    [...visible][0].html,
+    /href="https:\/\/www.openstreetmap.org\/copyright"/,
+  );
+  assert.match([...visible][0].html, />© OpenStreetMap</);
+  assert.ok([...visible][0].showOnScreen);
+  t.mock.timers.tick(60000);
+  assert.equal(visible.size, 1);
+  showOsmCredit(viewer, 'traffic', { openMapTiles: true });
+  assert.equal(visible.size, 2);
+  hideOsmCredit(viewer, 'alpr');
+  assert.equal(visible.size, 2, 'traffic still owns both credits');
+  showOsmCredit(viewer, 'datacenters');
+  hideOsmCredit(viewer, 'traffic');
+  assert.equal(
+    visible.size,
+    1,
+    'bundled data does not retain the tile distributor',
+  );
+  hideOsmCredit(viewer, 'datacenters');
+  assert.equal(visible.size, 0);
+  assert.equal(hideOsmCredit(viewer, 'datacenters'), false);
+  showOsmCredit(viewer, 'alpr');
+  assert.equal(visible.size, 1, 'reenabling restores the short credit');
+});
+
+test('tile attribution follows source changes and viewers have independent ownership', async () => {
+  const { showOsmCredit, hideOsmCredit } = await import('./dataCredits.js');
+  const create = () => {
+    const credits = new Set();
+    return {
+      credits,
+      creditDisplay: {
+        addStaticCredit: (c) => credits.add(c),
+        removeStaticCredit: (c) => credits.delete(c),
+      },
+    };
+  };
+  const a = create(),
+    b = create();
+  showOsmCredit(a, 'installations', { openMapTiles: true });
+  showOsmCredit(b, 'installations');
+  assert.equal(a.credits.size, 2);
+  assert.equal(b.credits.size, 1);
+  showOsmCredit(a, 'installations');
+  assert.equal(a.credits.size, 1, 'wide names no longer use tiles');
+  hideOsmCredit(a, 'installations');
+  assert.equal(a.credits.size, 0);
+  assert.equal(b.credits.size, 1);
+});
+
+test('the NYC camera credit carries NYC DOT’s requested disclaimer', () => {
+  const credit = DATA_CREDITS.find((entry) => entry.key === 'nyc-cctv');
+  assert.ok(credit, 'NYC DOT camera frames must be credited');
+  assert.ok(credit.html.includes(NYC_DOT_DISCLAIMER));
+  assert.match(credit.html, /make no representation as to the accuracy/);
+  assert.match(credit.html, /observe posted signage/);
+});

src/data/detection.js

@@ -48,6 +48,12 @@ import {
   viewScaleForAltitude,
 } from './detectionPolicy.js';
 import { detectionBracketOpacity } from './detectionPresentation.js';
+import {
+  createCyberSonarSampler,
+  cyberSonarFrameDelay,
+  isCyberContactSonarActive as isCyberSonarActive,
+  isCyberContactThemeActive as isCyberMapThemeActive,
+} from '../cyberSonar.js';
 
 /**
  * @module detection
@@ -206,6 +212,8 @@ let _lastRenderMs = 0;
 let _lastPaintMs = 0;
 let _lastSolveMs = 0;
 let _throttleSkipCount = 0;
+let _lastCyberSonarPaintAt = Number.NEGATIVE_INFINITY;
+let _cyberSonarRenderTimer = null;
 /** @type {Function|null} External callback invoked when the detection mode changes */
 let _onModeChange = null;
 /** @type {{surface:HTMLCanvasElement|null,setActive:Function,requestPaint:Function,unregister:Function}|null} */
@@ -325,6 +333,7 @@ export function initDetection(viewer, layers, onModeChange) {
 
 /** Release the host lane and all retained detection runtime state. */
 export function destroyDetection() {
+  _clearCyberSonarRenderTimer();
   if (_cockpitModeListener && typeof window !== 'undefined') {
     window.removeEventListener(
       'gev:cockpit-mode-changed',
@@ -362,6 +371,25 @@ export function destroyDetection() {
   _lastPaintMs = 0;
   _lastSolveMs = 0;
   _throttleSkipCount = 0;
+  _lastCyberSonarPaintAt = Number.NEGATIVE_INFINITY;
+}
+
+function _clearCyberSonarRenderTimer() {
+  if (_cyberSonarRenderTimer != null) {
+    globalThis.clearTimeout?.(_cyberSonarRenderTimer);
+    _cyberSonarRenderTimer = null;
+  }
+}
+
+function _scheduleCyberSonarRender(nowMs) {
+  if (_cyberSonarRenderTimer != null || !globalThis.setTimeout) return;
+  const delay = cyberSonarFrameDelay(_lastCyberSonarPaintAt, nowMs);
+  _cyberSonarRenderTimer = globalThis.setTimeout(() => {
+    _cyberSonarRenderTimer = null;
+    if (isCyberSonarActive()) {
+      governorRequestRender('cyber-sonar-cadence');
+    }
+  }, delay);
 }
 
 /**
@@ -682,7 +710,18 @@ function _applyModeState() {
 function _shouldPaintDetectionLane(frame) {
   if (_mode === MODE_OFF || _suspended) return false;
   const layoutChanged = frame.layoutRevision !== _hostLayoutRevision;
+  const nowMs = Number.isFinite(frame.timestamp) ? frame.timestamp : _nowMs();
   _frameCount++;
+  if (isCyberSonarActive()) {
+    const sonarDelay = cyberSonarFrameDelay(_lastCyberSonarPaintAt, nowMs);
+    if (!layoutChanged && sonarDelay > 0) {
+      _scheduleCyberSonarRender(nowMs);
+      return false;
+    }
+  } else {
+    _clearCyberSonarRenderTimer();
+    _lastCyberSonarPaintAt = Number.NEGATIVE_INFINITY;
+  }
   // The skip and the follow-up request come from ONE decision, so the valve
   // cannot drop a frame without handing its request forward — see
   // `detectionPaintSkipDecision`. (Skipping is a deferral, never a cancellation:
@@ -729,6 +768,14 @@ function _paintDetectionLane(frame) {
   _lastRenderMs = performance.now() - start;
   _lastSolveMs = result.solveMs || 0;
   _lastPaintMs = Math.max(0, _lastRenderMs - _lastSolveMs);
+  const nowMs = Number.isFinite(frame.timestamp) ? frame.timestamp : _nowMs();
+  if (isCyberSonarActive() && _lastDiagnostics?.visibleCount > 0) {
+    _lastCyberSonarPaintAt = nowMs;
+    _scheduleCyberSonarRender(nowMs);
+  } else {
+    _clearCyberSonarRenderTimer();
+    _lastCyberSonarPaintAt = Number.NEGATIVE_INFINITY;
+  }
   if (_lastDiagnostics) {
     _lastDiagnostics.frameTotalMs = _lastRenderMs;
     _lastDiagnostics.paintMs = _lastPaintMs;
@@ -748,7 +795,7 @@ function _paintDetectionLane(frame) {
       // The frame's OWN timestamp, not a fresh sample — re-reading the clock here
       // is what dropped the terminal frame of a fade (paint at 219 ms, policy at
       // 220 ms, and the settled alpha never painted).
-      nowMs: Number.isFinite(frame.timestamp) ? frame.timestamp : _nowMs(),
+      nowMs,
       enabledAtMs: _enableTime,
       fadeMs: FADE_MS,
       animatingLabelCount: result.animatingCount || 0,
@@ -996,7 +1043,8 @@ function _stashCallout(entry, acquireFade, keyhole) {
     placement.centerY,
     keyhole,
   );
-  const alpha = acquireFade * temporalAlpha * radialAlpha;
+  const alpha =
+    acquireFade * temporalAlpha * radialAlpha * (candidate.sonarFactor ?? 1);
   if (alpha <= 0.001) return;
 
   let row = _calloutPool[_calloutCount];
@@ -1146,6 +1194,7 @@ function _materializeCandidate(
     keyholeAlpha,
     placements,
     color: obj._candidateColor,
+    sonarFactor: obj._candidateSonarFactor ?? 1,
     // Costed here rather than in the object sweep: the sweep walks every
     // observation in view, while this runs only for callouts that actually
     // placed — a budgeted handful per frame.
@@ -1180,6 +1229,9 @@ function _drawOverlay(frame) {
   // with every arbiter call in this function — so the frame that paints an
   // animation's final state is the same frame that ends its demand.
   const now = Number.isFinite(frame.timestamp) ? frame.timestamp : _nowMs();
+  const sonarActive = isCyberSonarActive();
+  const cyberMapActive = isCyberMapThemeActive();
+  const sonarSampler = createCyberSonarSampler(width, height, now);
   const bracketPresentationOpacity = detectionBracketOpacity(_cockpitActive);
   const shouldSolve =
     _labelSolveDirty || now - _lastLabelSolveAt >= LABEL_SOLVE_INTERVAL_MS;
@@ -1362,11 +1414,16 @@ function _drawOverlay(frame) {
     // The bracket follows the same linear radial keyhole fade as its callout.
     const color = colorFor(resolveTier(obj));
     const keyholeAlpha = keyholeLabelAlphaFromGeometry(sx, sy, keyhole);
-    const bracketAlpha = detectionBracketAlpha(
+    const sonarFactor =
+      sonarActive && !obj.skipLabel ? sonarSampler.at(sx, sy) : 1;
+    const sonarLabelFactor = sonarSampler.label(sonarFactor);
+    const admissionAlpha = detectionBracketAlpha(
       obj.type,
       keyholeAlpha,
       keyholeOutsideOpacity,
+      cyberMapActive,
     );
+    const bracketAlpha = admissionAlpha * sonarFactor;
     if (bracketAlpha > 0) {
       const transit = obj.tier?.startsWith('transit_');
       (transit ? appendTransitBracket : appendCornerBracket)(
@@ -1404,13 +1461,15 @@ function _drawOverlay(frame) {
 
     obj._cohortSourceId = sourceId;
     obj._cohortPriority = _semanticPriority(obj);
-    obj._cohortBand = bracketAlpha >= 0.999 ? 8 : Math.floor(bracketAlpha * 8);
+    obj._cohortBand =
+      admissionAlpha >= 0.999 ? 8 : Math.floor(admissionAlpha * 8);
     obj._cohortHash = stableIdentityHash(layerId, sourceId);
     obj._candidateScreenX = sx;
     obj._candidateScreenY = sy;
     obj._candidateHalfW = halfW;
     obj._candidateHalfH = halfH;
     obj._candidateColor = color;
+    obj._candidateSonarFactor = sonarLabelFactor;
     obj._candidatePrimary = primary;
     obj._candidateMicro = micro;
 

src/data/detectionPolicy.js

@@ -92,14 +92,18 @@ export function aircraftBracketAlphaFloor(outsideOpacity) {
  * @param {number} keyholeAlpha - Radial keyhole alpha for this contact.
  * @param {number} [outsideOpacity] - Live OUTSIDE slider value. Omitted means
  *   the default, so a caller that does not know it reproduces the shipped look.
+ * @param {boolean} [strictKeyholeFade] - When true, do not apply the AIR
+ *   readability floor; the bracket follows the radial keyhole alpha exactly.
  * @returns {number} Paint alpha, 0-1.
  */
 export function detectionBracketAlpha(
   type,
   keyholeAlpha,
   outsideOpacity = AIRCRAFT_BRACKET_FLOOR_ANCHOR,
+  strictKeyholeFade = false,
 ) {
   const alpha = Math.max(0, Math.min(1, Number(keyholeAlpha) || 0));
+  if (strictKeyholeFade) return alpha;
   if (String(type || '').toUpperCase() !== 'AIR' || alpha <= 0) return alpha;
   return Math.max(aircraftBracketAlphaFloor(outsideOpacity), alpha);
 }

src/data/detectionPolicy.test.mjs

@@ -28,6 +28,20 @@ test('side aircraft brackets stay readable without changing zero-opacity intent'
   assert.equal(detectionBracketAlpha('SAT', 0.05), 0.05);
 });
 
+test('strict keyhole fading bypasses the aircraft floor for themed brackets', () => {
+  assert.equal(
+    detectionBracketAlpha(
+      'AIR',
+      0.01,
+      KEYHOLE_OUTSIDE_OPACITY_DEFAULT,
+      true,
+    ),
+    0.01,
+  );
+  assert.equal(detectionBracketAlpha('AIR', 0.42, 1, true), 0.42);
+  assert.equal(detectionBracketAlpha('AIR', 1, 0, true), 1);
+});
+
 test('the bracket floor anchor mirrors the real keyhole default it is calibrated to', () => {
   // detectionPolicy stays Cesium-free, so the anchor is a mirror. If the keyhole
   // default ever moves, this fails rather than silently shifting the shipped

src/data/detectionRenderDemand.test.mjs

@@ -285,7 +285,15 @@ test('detection holds nothing, and asks for its own frames instead', async () =>
   assert.ok(paintLane, 'detection.js still has a paint lane');
   assert.doesNotMatch(paintLane, /nowMs: Date\.now\(\)/,
     'demand must not re-sample the clock — that is the dropped terminal frame');
-  assert.match(paintLane, /nowMs: Number\.isFinite\(frame\.timestamp\) \? frame\.timestamp : _nowMs\(\)/);
+  assert.match(
+    paintLane,
+    /const nowMs = Number\.isFinite\(frame\.timestamp\) \? frame\.timestamp : _nowMs\(\)/,
+  );
+  assert.match(
+    paintLane,
+    /detectionNeedsFollowUpFrame\(\{[\s\S]*?\n\s*nowMs,/,
+    'the sonar cadence and fade demand share the same frame-clock sample',
+  );
   assert.match(paintLane, /animatingLabelCount: result\.animatingCount/,
     'demand counts fades in both directions');
   // …and `animatingCount` must really be the BOTH-directions count. Feeding the

src/data/detectionSonarAdmission.test.mjs

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+import { detectionBracketAlpha } from './detectionPolicy.js';
+
+// Exercise the actual renderer's admission and paint expressions. A sweep is
+// appearance only: it must not reshuffle candidates at the cohort cutoff.
+const source = readFileSync(new URL('./detection.js', import.meta.url), 'utf8');
+const alphaBlock = source.match(
+  /const admissionAlpha = detectionBracketAlpha\([\s\S]*?const bracketAlpha = [^;]+;/,
+)?.[0];
+const bandAssignment = source.match(/obj\._cohortBand\s*=\s*[^;]+;/)?.[0];
+
+test('Sonar changes paint alpha without changing detection cohort admission', () => {
+  assert.ok(alphaBlock, 'renderer separates admission from paint');
+  assert.ok(bandAssignment);
+  for (const cyberMapActive of [false, true]) {
+    for (const type of ['AIR', 'SAT', 'SEA']) {
+      for (const keyholeAlpha of [0, 0.01, 0.125, 0.5, 0.999, 1]) {
+        const alpha = detectionBracketAlpha(
+          type,
+          keyholeAlpha,
+          0.35,
+          cyberMapActive,
+        );
+        const expectedBand = alpha >= 0.999 ? 8 : Math.floor(alpha * 8);
+        for (const sonarFactor of [0.01, 0.12, 0.5, 1]) {
+          const state = {
+            obj: { type },
+            keyholeAlpha,
+            keyholeOutsideOpacity: 0.35,
+            cyberMapActive,
+            sonarFactor,
+            detectionBracketAlpha,
+          };
+          vm.runInNewContext(
+            alphaBlock + bandAssignment + '; result = bracketAlpha;',
+            state,
+          );
+          assert.equal(state.obj._cohortBand, expectedBand);
+          assert.equal(state.result, alpha * sonarFactor);
+        }
+      }
+    }
+  }
+});

src/data/directionText.js

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

src/data/directions.js

@@ -1,3 +1,4 @@
+import { createDirectionsSource } from '../layers/directions/source.js';
 /**
  * @module directions
  * @description Service bundle for the Directions layer.
@@ -10,6 +11,7 @@
  * the layer's pure helpers for the tests and the share-link code.
  */
 
+import * as credits from './dataCredits.js';
 import * as render from '../renderGovernor.js';
 import * as sprites from './spriteOrder.js';
 import * as picking from './pickRegistry.js';
@@ -23,6 +25,7 @@ import { createDirectionsLayer } from '../layers/directions/index.js';
 
 /** The shared scene owners every Directions instance runs on. */
 export const directionsServices = Object.freeze({
+  credits,
   render,
   sprites,
   picking,
@@ -35,8 +38,10 @@ export const directionsServices = Object.freeze({
 });
 
 /** Construct one Directions layer over the application scene owners. */
-export function createApplicationDirectionsLayer() {
-  return createDirectionsLayer({ services: directionsServices });
+export function createApplicationDirectionsLayer({
+  source = createDirectionsSource(),
+} = {}) {
+  return createDirectionsLayer({ services: directionsServices, source });
 }
 
 export {

src/data/feedState.js

@@ -3,7 +3,7 @@ import { GUIDANCE_STATUSES } from '../loadingFeedback.js';
 /**
  * Normalize heterogeneous layer stats into one honest control-chip state.
  * @param {object|null} stats Layer getStats() result.
- * @returns {'nominal'|'loading'|'degraded'|'stale'|'fallback'|'unavailable'} Feed state.
+ * @returns {'nominal'|'loading'|'degraded'|'stale'|'partial'|'fallback'|'unavailable'} Feed state.
  */
 export function layerFeedState(stats = {}) {
   const state = stats || {};
@@ -50,5 +50,6 @@ export function layerFeedState(stats = {}) {
     state.available === false
   )
     return 'degraded';
+  if (state.partial === true) return 'partial';
   return 'nominal';
 }

src/data/firePerimetersProxy.test.mjs

@@ -0,0 +1,410 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { firePerimetersProxy } from '../../server/providers/firePerimeters.js';
+
+const incidentHtml = `<meta property="og:updated_time" content="2026-09-23T11:32:31-04:00" />
+<th>Date of Origin</th>
+<td class="text-tabular text-left"><time datetime="2026-07-15T20:20:00Z">Origin</time></td>`;
+const incidentTimes = {
+  createdMs: Date.parse('2026-07-15T20:20:00Z'),
+  changedMs: Date.parse('2026-09-23T11:32:31-04:00'),
+};
+const incidentRedirect = () =>
+  new Response('redirect', {
+    status: 301,
+    headers: { location: 'http://inciweb.wildfire.gov/test-fire' },
+  });
+
+const feature = (id = 'fire') => ({
+  properties: { attr_UniqueFireIdentifier: id, poly_DateCurrent: 123 },
+  geometry: {
+    type: 'Polygon',
+    coordinates: [
+      [
+        [-108, 35],
+        [-107, 35],
+        [-107, 36],
+        [-108, 35],
+      ],
+    ],
+  },
+});
+function install(options = {}, hook = 'configureServer') {
+  let handler;
+  const plugin = firePerimetersProxy(options);
+  assert.equal(typeof plugin.configureServer, 'function');
+  assert.equal(typeof plugin.configurePreviewServer, 'function');
+  plugin[hook]({
+    middlewares: {
+      use(path, callback) {
+        assert.equal(path, '/api/fire-perimeters');
+        handler = callback;
+      },
+    },
+  });
+  return async (url = '/', method = 'GET', peer = 'local') => {
+    const res = {
+      writeHead(status, headers) {
+        this.status = status;
+        this.headers = headers;
+      },
+      end(body) {
+        this.body = JSON.parse(body);
+      },
+    };
+    await handler({ url, method, socket: { remoteAddress: peer } }, res);
+    return res;
+  };
+}
+
+for (const hook of ['configureServer', 'configurePreviewServer']) {
+  test(`${hook}: paging stops at five pages and normalizes the combined snapshot`, async () => {
+    const calls = [];
+    const request = install(
+      {
+        now: () => 1234,
+        fetchImpl: async (url, options) => {
+          calls.push(new URL(url));
+          assert.ok(options.signal instanceof AbortSignal);
+          assert.equal(options.redirect, 'error');
+          return Response.json({
+            features: [feature(String(calls.length))],
+            exceededTransferLimit: true,
+          });
+        },
+      },
+      hook,
+    );
+    const res = await request('/?url=https://invalid.example&resultOffset=999');
+    assert.equal(res.status, 200);
+    assert.equal(res.body.fetchedAt, 1234);
+    assert.equal(res.body.rows.length, 5);
+    assert.deepEqual(
+      calls.map((url) => url.searchParams.get('resultOffset')),
+      [null, '1', '2', '3', '4'],
+    );
+    assert.ok(calls.every((url) => url.hostname === 'services3.arcgis.com'));
+    assert.equal(calls[0].searchParams.get('maxAllowableOffset'), '0.001');
+  });
+}
+
+test('an explicit transfer-limit false stops paging; a fresh cache does not fetch', async () => {
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls++;
+      return Response.json({
+        features: [feature()],
+        exceededTransferLimit: false,
+      });
+    },
+  });
+  const first = await request();
+  assert.deepEqual((await request()).body, first.body);
+  assert.equal(calls, 1);
+});
+
+test('a failed refresh serves the last good perimeter snapshot as stale', async () => {
+  let clock = 0,
+    calls = 0;
+  const request = install({
+    now: () => clock,
+    fetchImpl: async () => {
+      if (++calls > 1) throw new Error('private upstream details');
+      return Response.json({ features: [feature()] });
+    },
+  });
+  await request();
+  clock = 300_000;
+  const res = await request();
+  assert.equal(res.status, 200);
+  assert.equal(res.body.stale, true);
+  assert.equal(res.body.fetchedAt, 0);
+  assert.equal(res.body.rows[0].stableId, 'fire');
+});
+
+test('oversized streamed and declared bodies produce sanitized 502 responses', async () => {
+  for (const declared of [true, false]) {
+    let cancelled = false;
+    const request = install({
+      fetchImpl: async () =>
+        new Response(
+          new ReadableStream({
+            pull(controller) {
+              controller.enqueue(new Uint8Array(1024 * 1024));
+            },
+            cancel() {
+              cancelled = true;
+            },
+          }),
+          {
+            headers: declared
+              ? { 'Content-Length': String(17 * 1024 * 1024) }
+              : {},
+          },
+        ),
+    });
+    const res = await request();
+    assert.equal(res.status, 502);
+    assert.deepEqual(res.body, { error: 'fire_perimeters_unavailable' });
+    assert.equal(cancelled, true);
+  }
+});
+
+test('malformed WFIGS data does not become a cached empty snapshot', async () => {
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls++;
+      return Response.json({ error: 'upstream detail' });
+    },
+  });
+  assert.equal((await request()).status, 502);
+  assert.equal((await request()).status, 502);
+  assert.equal(calls, 2);
+});
+
+test('concurrent requests share one upstream operation for every route', async () => {
+  for (const [path, payload] of [
+    ['/', { features: [] }],
+    ['/inciweb/index', []],
+    ['/inciweb/publication/42', {}],
+  ]) {
+    let release,
+      calls = 0;
+    const pending = new Promise((resolve) => {
+      release = resolve;
+    });
+    const request = install({
+      fetchImpl: async () => {
+        calls++;
+        await pending;
+        if (path.includes('/publication/'))
+          return calls === 1 ? incidentRedirect() : new Response(incidentHtml);
+        return Response.json(payload);
+      },
+    });
+    const responses = [request(path), request(path)];
+    await new Promise(setImmediate);
+    assert.equal(calls, 1);
+    release();
+    for (const res of await Promise.all(responses))
+      assert.equal(res.status, 200);
+    assert.equal(calls, path.includes('/publication/') ? 2 : 1);
+  }
+});
+
+test('bad publication ids and non-GET requests never fetch upstream', async () => {
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls++;
+      throw new Error('unexpected');
+    },
+  });
+  for (const id of ['', 'abc', '-1', '1234567890', '1/2', '%31', '1.0'])
+    assert.equal((await request(`/inciweb/publication/${id}`)).status, 400);
+  for (const path of ['/', '/inciweb/index', '/inciweb/publication/123']) {
+    for (const method of ['POST', 'HEAD', 'PUT', 'DELETE'])
+      assert.equal((await request(path, method)).status, 405);
+  }
+  assert.equal(calls, 0);
+});
+
+test('InciWeb index preserves the fixed POST, caches for one hour and serves stale arrays', async () => {
+  let clock = 0,
+    calls = 0;
+  const rows = [{ incident_id: '42', incident_title: 'Fire' }];
+  const request = install({
+    now: () => clock,
+    fetchImpl: async (url, options) => {
+      calls++;
+      assert.equal(url, 'https://inciweb.wildfire.gov/api/single-publication/');
+      assert.equal(options.method, 'POST');
+      assert.deepEqual(options.headers, { 'Content-Type': 'application/json' });
+      assert.deepEqual(JSON.parse(options.body), { title: '' });
+      if (calls > 1) throw new Error('offline');
+      return Response.json(rows);
+    },
+  });
+  assert.deepEqual((await request('/inciweb/index')).body, rows);
+  clock = 3_599_999;
+  assert.deepEqual((await request('/inciweb/index')).body, rows);
+  assert.equal(calls, 1);
+  clock++;
+  const stale = await request('/inciweb/index');
+  assert.deepEqual(stale.body, rows);
+  assert.equal(stale.headers['X-Data-Stale'], 'true');
+});
+
+test('publication timestamps, thirty-minute TTL and oldest-entry eviction', async () => {
+  let clock = 0;
+  const calls = [];
+  const request = install({
+    now: () => clock,
+    fetchImpl: async (url) => {
+      calls.push(url);
+      return url.includes('/node/')
+        ? incidentRedirect()
+        : new Response(incidentHtml);
+    },
+  });
+  const get = (id) =>
+    request(`/inciweb/publication/${id}`, 'GET', `peer-${id}`);
+  assert.deepEqual((await get(1)).body, incidentTimes);
+  clock = 1_799_999;
+  await get(1);
+  assert.equal(calls.length, 2);
+  clock++;
+  await get(1);
+  assert.equal(calls.length, 4);
+  for (let id = 2; id <= 257; id++) assert.equal((await get(id)).status, 200);
+  await get(2);
+  assert.equal(calls.length, 516);
+  await get(1);
+  assert.equal(calls.length, 518);
+  assert.equal(calls.at(-2), 'https://inciweb.wildfire.gov/node/1');
+});
+
+test('InciWeb index and publication reads enforce their smaller caps', async () => {
+  for (const [path, cap] of [
+    ['/inciweb/index', 4 * 1024 * 1024],
+    ['/inciweb/publication/1', 2 * 1024 * 1024],
+  ]) {
+    const request = install({
+      fetchImpl: async () =>
+        new Response('{}', { headers: { 'Content-Length': String(cap + 1) } }),
+    });
+    assert.equal((await request(path)).status, 502);
+  }
+});
+
+test('the per-client limit stops a loop while another client can read the cache', async () => {
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls++;
+      return Response.json({ features: [] });
+    },
+  });
+  for (let i = 0; i < 60; i++) assert.equal((await request()).status, 200);
+  assert.equal((await request()).status, 429);
+  assert.equal((await request('/', 'GET', 'another-client')).status, 200);
+  assert.equal(calls, 1);
+});
+
+test('publication redirects share a signal, cancel the redirect body and force HTTPS', async () => {
+  for (const status of [301, 302, 303, 307, 308]) {
+    const calls = [];
+    const redirect = new Response('redirect', {
+      status,
+      headers: {
+        location: 'http://inciweb.wildfire.gov/incident/test-fire#details',
+      },
+    });
+    const request = install({
+      fetchImpl: async (url, options) => {
+        calls.push({ url, options });
+        return calls.length === 1 ? redirect : new Response(incidentHtml);
+      },
+    });
+    assert.deepEqual(
+      (await request('/inciweb/publication/42')).body,
+      incidentTimes,
+    );
+    assert.equal(calls.length, 2);
+    assert.equal(redirect.bodyUsed, true);
+    assert.equal(calls[0].url, 'https://inciweb.wildfire.gov/node/42');
+    assert.equal(calls[0].options.redirect, 'manual');
+    assert.equal(
+      calls[1].url,
+      'https://inciweb.wildfire.gov/incident/test-fire',
+    );
+    assert.equal(calls[1].options.redirect, 'error');
+    assert.ok(calls[0].options.signal instanceof AbortSignal);
+    assert.equal(calls[0].options.signal, calls[1].options.signal);
+  }
+});
+
+test('unsafe publication redirect locations fail before a second fetch', async () => {
+  for (const location of [
+    'https://evil.example/x',
+    '/a/../x',
+    '/x?q=1',
+    '/x?',
+    '/%2e%2e/x',
+    '/a/b/c',
+    '',
+  ]) {
+    let calls = 0;
+    const request = install({
+      fetchImpl: async () => {
+        calls++;
+        return new Response('redirect', { status: 301, headers: { location } });
+      },
+    });
+    assert.equal((await request('/inciweb/publication/42')).status, 502);
+    assert.equal(calls, 1);
+  }
+});
+
+test('incident pages without valid timestamps fail closed and are not cached', async () => {
+  for (const html of [
+    '<html>No markers</html>',
+    incidentHtml.replaceAll(/2026-[^"]+/g, 'invalid'),
+  ]) {
+    let calls = 0;
+    const request = install({
+      fetchImpl: async () => {
+        calls++;
+        return calls % 2 ? incidentRedirect() : new Response(html);
+      },
+    });
+    assert.equal((await request('/inciweb/publication/42')).status, 502);
+    assert.equal((await request('/inciweb/publication/42')).status, 502);
+    assert.equal(calls, 4);
+  }
+});
+
+test('direct 200 incident pages work, including one missing timestamp', async () => {
+  for (const [html, expected] of [
+    [incidentHtml, incidentTimes],
+    [
+      incidentHtml.replace('og:updated_time', 'unrelated'),
+      { ...incidentTimes, changedMs: null },
+    ],
+    [
+      incidentHtml.replace('Date of Origin', 'Unrelated'),
+      { ...incidentTimes, createdMs: null },
+    ],
+  ]) {
+    let calls = 0;
+    const request = install({
+      fetchImpl: async () => {
+        calls++;
+        return new Response(html);
+      },
+    });
+    assert.deepEqual((await request('/inciweb/publication/42')).body, expected);
+    assert.equal(calls, 1);
+  }
+});
+
+test('publication HTML streams are capped at 2 MiB', async () => {
+  let cancelled = false;
+  const request = install({
+    fetchImpl: async () =>
+      new Response(
+        new ReadableStream({
+          pull(controller) {
+            controller.enqueue(new Uint8Array(1024 * 1024));
+          },
+          cancel() {
+            cancelled = true;
+          },
+        }),
+      ),
+  });
+  assert.equal((await request('/inciweb/publication/42')).status, 502);
+  assert.equal(cancelled, true);
+});

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

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

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

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

src/data/firmsAdapt.js

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

src/data/firmsCsv.js

@@ -5,9 +5,15 @@
  * VIIRS header (confirmed live 2026-07-16):
  *   latitude,longitude,bright_ti4,scan,track,acq_date,acq_time,satellite,
  *   instrument,confidence,version,bright_ti5,frp,daynight
+ * MODIS header:
+ *   latitude,longitude,brightness,scan,track,acq_date,acq_time,satellite,
+ *   instrument,confidence,version,bright_t31,frp,daynight
  *
  * Quirks this module owns:
- * - `confidence` is CATEGORICAL for VIIRS (`l`/`n`/`h`) — passed through raw.
+ * - `confidence` is CATEGORICAL for VIIRS (`l`/`n`/`h`) and numeric 0-100 for
+ *   MODIS — passed through raw.
+ * - Brightness maps from `bright_ti4`/`brightness`; the secondary band maps
+ *   from `bright_ti5`/`bright_t31`.
  * - `acq_time` is NOT zero-padded ("45" = 00:45 UTC) — kept as-is in records;
  *   {@link acquisitionMsUtc} does the padding.
  * - Upstream errors come back as HTML or plain text ("Invalid MAP_KEY"),
@@ -99,7 +105,17 @@ export function parseFirmsCsv(text) {
     if (parts.length < header.length) continue; // malformed row — skip
     const lat = Number(parts[iLat]);
     const lon = Number(parts[iLon]);
-    if (!Number.isFinite(lat) || !Number.isFinite(lon)) continue;
+    // Blank or out-of-range positions are dropped, never read as 0 (see
+    // hasCoordinateValue in firmsAdapt.js for the proxy-record side).
+    if (
+      !parts[iLat].trim() ||
+      !parts[iLon].trim() ||
+      !Number.isFinite(lat) ||
+      !Number.isFinite(lon) ||
+      Math.abs(lat) > 90 ||
+      Math.abs(lon) > 180
+    )
+      continue;
 
     records.push({
       lat,
@@ -147,7 +163,13 @@ export function acquisitionMsUtc(acqDate, acqTime) {
     minutes > 59
   )
     return NaN;
-  return Date.UTC(year, month - 1, day, hours, minutes);
+  const ms = Date.UTC(year, month - 1, day, hours, minutes);
+  const parsed = new Date(ms);
+  return parsed.getUTCFullYear() === year &&
+    parsed.getUTCMonth() === month - 1 &&
+    parsed.getUTCDate() === day
+    ? ms
+    : NaN;
 }
 
 /**

src/data/firmsCsv.test.mjs

@@ -48,6 +48,25 @@ test('fixture first row maps every field, categorical confidence preserved raw',
   assert.equal(first.instrument, 'VIIRS');
 });
 
+test('MODIS schema maps fields and preserves numeric confidence raw', () => {
+  const header =
+    'latitude,longitude,brightness,scan,track,acq_date,acq_time,satellite,instrument,confidence,version,bright_t31,frp,daynight';
+  const row =
+    '34.123,-117.456,321.5,1.2,0.8,2026-07-16,1045,Aqua,MODIS,78,6.1NRT,290.25,12.4,D';
+  const [record] = parseFirmsCsv(`${header}\n${row}\n`);
+  assert.equal(record.lat, 34.123);
+  assert.equal(record.lon, -117.456);
+  assert.equal(record.frp, 12.4);
+  assert.equal(record.brightness, 321.5);
+  assert.equal(record.brightnessTi5, 290.25);
+  assert.equal(record.daynight, 'D');
+  assert.equal(record.acqDate, '2026-07-16');
+  assert.equal(record.acqTime, '1045');
+  assert.equal(record.satellite, 'Aqua');
+  assert.equal(record.instrument, 'MODIS');
+  assert.equal(record.confidence, '78');
+});
+
 test('acquisitionMsUtc: "1006" = 10:06 UTC', () => {
   assert.equal(
     acquisitionMsUtc('2026-07-16', '1006'),

src/data/firmsHeatmap.test.mjs

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

src/data/firmsProxy.test.mjs

@@ -9,7 +9,7 @@ assert.notEqual(start, -1, 'FIRMS refresh function exists');
 const end = config.indexOf('\n  }', start);
 assert.notEqual(end, -1, 'FIRMS refresh function closes');
 const refreshSource = config.slice(start, end + 4);
-const SOURCES = ['VIIRS_NOAA20_NRT', 'VIIRS_NOAA21_NRT', 'VIIRS_SNPP_NRT'];
+const SOURCES = ['VIIRS_NOAA20_NRT', 'VIIRS_NOAA21_NRT', 'VIIRS_SNPP_NRT', 'MODIS_NRT'];
 const NOW = Date.UTC(2026, 8, 11, 12);
 const recent = { acqDate: '2026-09-11', acqTime: '1100' };
 
@@ -42,7 +42,7 @@ test('FIRMS retains large sources in order and filters expired rows', async () =
   assert.equal(result.fires[199_999], large.at(-1));
   assert.equal(result.fires.at(-1), last);
   assert.deepEqual(result.sources, SOURCES.map((source, index) => ({
-    source, count: [200_000, 1, 0][index], ok: true,
+    source, count: [200_000, 1, 0, 0][index], ok: true,
   })));
 });
 
@@ -51,7 +51,7 @@ test('FIRMS keeps successful sources when another upstream fails', async () => {
     if (source === SOURCES[1]) throw new Error('upstream unavailable');
     return [recent];
   })('fixture');
-  assert.equal(result.fires.length, 2);
+  assert.equal(result.fires.length, 3);
   assert.deepEqual(result.sources, SOURCES.map((source, index) => ({
     source, count: index === 1 ? 0 : 1, ok: index !== 1,
   })));
@@ -65,7 +65,7 @@ test('FIRMS reports one failure if consuming a source throws before append', asy
       // Fault injection for aggregation; ordinary parsed CSV returns an array.
       return { length: 1, [Symbol.iterator]() { throw new Error('aggregation failed'); } };
     })('fixture');
-  assert.equal(result.fires.length, 2);
+  assert.equal(result.fires.length, 3);
   assert.deepEqual(result.sources, SOURCES.map((source, index) => ({
     source, count: index === 0 ? 0 : 1, ok: index !== 0,
   })));

src/data/fixtures/README.md

@@ -7,3 +7,37 @@
   (22,980 bytes). Used by offline decode/source tests and the explicit `qa-traffic --fixtures`
   browser mode — it is a point-in-time congestion snapshot, not a bundled
   data layer, and is never loaded by ordinary application startup. © TomTom.
+- `adsb-austin-frames.txt` — 112 raw Mode S frames (`*<hex>;`, one per line,
+  in receive order) received over Austin, TX, and
+  `adsb-austin-dump1090-aircraft.json` — dump1090-fa's `aircraft.json` decode
+  of the same frames, trimmed to the fields the tests assert on. Used by the
+  Local ADS-B decoder and record-adapter tests; never loaded at runtime.
+- `adsb-austin-capture-timed.json` — a second ~90 s receive over Austin, TX:
+  846 extended squitters from six aircraft (`frames`: `[ms, hex]`), with
+  dump1090-fa's decoded positions and emitter categories for the same
+  interval (`dump1090`: per ICAO `flight`, `category` and `fixes` as
+  `[ms, lat, lon]`). The capture has no per-frame timestamps; each frame's
+  time is interpolated between the frames whose decoded position equals a
+  dump1090 fix, timed as dump1090's `now − seen_pos`. Used by the decoder's
+  category, speed-check and track-accuracy tests; never loaded at runtime.
+- `ofm-austin-{14-3743-6745,12-935-1686}.pbf` and
+  `ofm-camp-mabry-12-935-1685.pbf` — OpenFreeMap / OpenMapTiles tiles from
+  `https://tiles.openfreemap.org/planet/20260913_164504_pt/{z}/{x}/{y}.pbf`,
+  retrieved 2026-09-23. Trimmed to one transportation feature per class/direction
+  and one military landuse feature, preserving original geometry and dictionaries.
+  OpenFreeMap © OpenMapTiles Data from OpenStreetMap; © OpenStreetMap
+  contributors, ODbL 1.0 (https://www.openstreetmap.org/copyright).
+  These modified data fixtures retain ODbL attribution and database share-alike;
+  commercial use and redistribution are permitted under that license. Test-only.
+- `osm-alpr-austin-11-467-843.pbf` — one OSM camera feature (original geometry
+  and attribute dictionary) from the community-hosted hourly US extract,
+  `https://tiles.dontgetflocked.com/cameras-us-hourly/11/467/843.mvt`,
+  retrieved 2026-09-23. © OpenStreetMap contributors, ODbL 1.0; modified by
+  trimming to one feature, test-only. Same attribution/share-alike terms above.
+
+- `traffic-road-access.json` — representative transportation properties and two
+  original vertices per feature near the Texas Capitol, Camp Mabry greenbelt,
+  and Austin commercial car parks, from OpenFreeMap z14 tiles, retrieved
+  2026-09-25. Each record names its XYZ tile and expected traffic eligibility.
+  Modified, test-only OpenStreetMap data; same ODbL attribution and database
+  share-alike terms as the OpenFreeMap fixtures above.

src/data/fixtures/adsb-austin-capture-timed.json

@@ -0,0 +1 @@
+{"receiver":{"latitude":30.27,"longitude":-97.8},"frames":[[10,"8d0d0c07501d0030aa4c0c2140c6"],[80,"8da5b3a758b99408f8dda679bb00"],[150,"8da0b702e1150d0000000004eb56"],[220,"8d0d0c0722594377e37820b79a0d"],[290,"8d0d0c07990c111d483c0c92e5f3"],[360,"8da0b702590d40253c4af26e47d9"],[430,"8da0b70299105d833818018770a8"],[500,"8d0d0c07501bf7da9cd71ab9e124"],[570,"8da5b3a7ea466864013c085e68e2"],[640,"8da3627d58a580665464f23579f2"],[780,"8d0d0c07990c111d483c0c92e5f3"],[850,"8da0b702590d47cf46d60b223463"],[920,"8da0b70299105d83380c015f9ea8"],[990,"8d0d0c07f8200002004ab89cec0b"],[1060,"8da0b702f8122006005ab8b0ce08"],[1130,"8d0d0c07501bf030d84c0b00e5d5"],[1200,"8da5b3a758b9905ff8528e447e65"],[1275,"8d0d0c07990c111d483c0c92e5f3"],[1350,"8da0b702590d5025384afb963e58"],[1425,"8da0b70299105d83300481465660"],[1500,"8da3627d58a5840ef0ef82e7f39f"],[1600,"8d0d0c07501bf030f64c0af8367b"],[1675,"8da5b3a7990da30b30085d4a3fb6"],[1750,"8d0d0c07990c111d483c0b6d35d7"],[1825,"8da5b3a723041333c31c2045cc84"],[1900,"8da0b702590d4025364affe4f100"],[1963,"8da0b70299105c833008010a006e"],[2088,"8dabe7c59915ad0d380456abc760"],[2150,"8dabe7c558af87ce8ccac01d62c7"],[2213,"8d0d0c07501be031124c090e5e08"],[2275,"8d0d0c07e1058a00000000c4d44e"],[2338,"8da3627de106290000000030ef86"],[2400,"8da5b3a758b994091cdd51bae36d"],[2460,"8d0d0c07990c111d483c0c92e5f3"],[2580,"8da0b702590d47cf40d6170e6567"],[2640,"8da0b70299105c83100c01774a47"],[2700,"8d0d0c07501be031244c08456bbe"],[2800,"8da5b3a7990da30b30085d4a3fb6"],[2900,"8da27e81592147de34ccbfe1e71f"],[3000,"8d0d0c07990c111d683c0b2849fe"],[3100,"8da0b702590d57cf3cd61d759697"],[3133,"8da0b70299105c83101081d8ce87"],[3200,"8da5b3a7ea466864013c085e68e2"],[3233,"8d0d0c07501be7db16d7163df6ea"],[3267,"8da3627d991417bb100854ccc1a2"],[3300,"8da27e81592147de3cccc18db35e"],[3333,"8da27e819910390f18080b8ece70"],[3367,"8d0d0c07990c111d683c0cd799da"],[3400,"8da5b3a758b990601e52360713ad"],[3450,"8da0b702f8122006005ab8b0ce08"],[3500,"8d0d0c07f8200002004ab89cec0b"],[3550,"8da0b702590d50252e4b0d6c0eab"],[3600,"8da0b70299105b83101481e9cced"],[3650,"8da5b3a7f82300060049b8e08700"],[3700,"8d0d0c07501be7db32d715b033d5"],[3700,"8da3627d58a580652c64ebca78d9"],[3860,"8da5b3a7990da30b30085eb5d7a4"],[3940,"8d0d0c07990c111d68380b107ffe"],[4020,"8dabe7c59915ad0d380456abc760"],[4100,"8da0b702590d57cf38d625439697"],[4140,"8da0b70299105b83101801a6902d"],[4180,"8d0d0c07501bd031724c05906709"],[4220,"8dabe7c558af87ceb8ca66b4e8a7"],[4260,"8d0d0c07990c111d68380cefafda"],[4300,"8da5b3a758b9906030520dfe8d1c"],[4417,"8d0d0c07501bd031844c05445a49"],[4533,"8da0b702590d57cf36d62b019958"],[4650,"8da0b70299105b83101881a196ed"],[4767,"8da5b3a7990da30b30085d4a3fb6"],[4883,"8d0d0c07990c111d88380b35ff28"],[5000,"8da0b702590d57cf34d62ee5fde5"],[5000,"8da0b70299105b82f01481e7b168"],[5000,"8da0b702e1150d0000000004eb56"],[5000,"8d0d0c07501bd7db74d71347e30c"],[5150,"8da0b70227c74d5462082004597a"],[5300,"8da5b3a758b990604051e7fb7390"],[5333,"8d0d0c0722594377e37820b79a0d"],[5367,"8d0d0c07990c111d88380cca2f0c"],[5400,"8dabe7c558af8024c23ee7c8e962"],[5460,"8dabe7c5f8230006004ab8db4fc2"],[5520,"8da0b702590d5025264b1f025060"],[5580,"8da0b70299105b82f01401e0b7a8"],[5640,"8da5b3a7ea466864013c085e68e2"],[5700,"8d0d0c07501bd031b44c03dc465d"],[5760,"8da5b3a7990da30b30085eb5d7a4"],[5820,"8da0b702f8122006005ab8b0ce08"],[5880,"8d0d0c07990c111d88380b35ff28"],[5940,"8dabe7c59915ad0d300456c56568"],[6000,"8da0b702590d57cf30d6372dc85c"],[6050,"8da0b70299105b82f01401e0b7a8"],[6100,"8d0d0c07501bc031c64c021a765d"],[6250,"8d0d0c07f8200002004ab89cec0b"],[6400,"8dabe7c558af8024d83eba9c7813"],[6500,"8d0d0c07501bc7dbb4d71117af08"],[6600,"8d0d0c07990c111da83c0b48b501"],[6700,"8da5b3a7990da30b30085d4a3fb6"],[6800,"8dabe7c59915ad0d300456c56568"],[6900,"8d0d0c07501bc7dbc8d710a36866"],[7050,"8d0d0c07990c111da83c0cb76525"],[7200,"8da5b3a758b990606451947414a7"],[7300,"8dabe7c558af87cef8c9e42b1cae"],[7360,"8dabe7c5ea428867215c08fe0874"],[7420,"8d0d0c07e1058a00000000c4d44e"],[7540,"8d0d0c07501bc0320a4c005f6240"],[7600,"8d0d0c07990c111da83c0b48b501"],[7660,"8da0b702590d67cf28d645cd6577"],[7720,"8da0b70299105a82f01081dc8da6"],[7780,"8da5b3a7990da30b30085eb5d7a4"],[7840,"8dabe7c59915ad0d300456c56568"],[7900,"8d0d0c07501bb032264bff008fc5"],[7933,"8d0d0c07990c111da83c0cb76525"],[7967,"8da5b3a7ea466864013c085e68e2"],[8000,"8da0b702590d67cf26d6487082aa"],[8150,"8da0b70299105a82d01481a1c78f"],[8300,"8da5b3a758b9906076516b48fcb5"],[8300,"8dabe7c558af8025003e6a60fadf"],[8364,"8da5b3a7f82300060049b8e08700"],[8427,"8da0b702f8122006005ab8b0ce08"],[8491,"8d0d0c07f8200002004ab89cec0b"],[8555,"8d0d0c07990c111dc83c0b87317a"],[8618,"8d0d0c07501bb032444bfe2b5735"],[8682,"8da5b3a7e10d2800000000aefd57"],[8745,"8da0b702590d67cf24d64d94e617"],[8809,"8da0b70299105a82d01481a1c78f"],[8873,"8dabe7c59915ad0d300456c56568"],[8936,"8d0d0c07990c111dc83c0c78e15e"],[9000,"8d0d0c07501bb032564bfeedbba7"],[9200,"8da0b702590d6025164b3fca5cc9"],[9267,"8da0b70299105a82d010019ef74f"],[9333,"8da5b3a758b9940996dc34d66e25"],[9400,"8dabe7c55Line truncated

src/data/fixtures/adsb-austin-dump1090-aircraft.json

@@ -0,0 +1,53 @@
+{
+  "now": 1790127097.5,
+  "messages": 112,
+  "aircraft": [
+    {
+      "hex": "a15c54",
+      "flight": "SKW3301 ",
+      "alt_baro": 5050,
+      "gs": 287.5,
+      "track": 291.2,
+      "baro_rate": 3072,
+      "seen": 31.5,
+      "messages": 14,
+      "rssi": -28.2
+    },
+    {
+      "hex": "ae5d8a",
+      "flight": "SHINR42 ",
+      "lat": 30.269662,
+      "lon": -97.793262,
+      "alt_baro": 1600,
+      "gs": 129.9,
+      "track": 330.5,
+      "baro_rate": 64,
+      "seen": 30.5,
+      "seen_pos": 34.6,
+      "messages": 74,
+      "rssi": -30.0
+    },
+    {
+      "hex": "a3c775",
+      "lat": 30.360625,
+      "lon": -97.919659,
+      "alt_baro": 34000,
+      "gs": 434.4,
+      "track": 283.7,
+      "baro_rate": 0,
+      "seen": 38.2,
+      "seen_pos": 43.4,
+      "messages": 20,
+      "rssi": -30.5
+    },
+    {
+      "hex": "a46e6a",
+      "gs": 319.8,
+      "track": 351.2,
+      "baro_rate": 2688,
+      "seen": 32.0,
+      "messages": 4,
+      "rssi": -37.1
+    }
+  ]
+}

src/data/fixtures/adsb-austin-frames.txt

@@ -0,0 +1,112 @@
+*8da46e6a99143227b0ac21405d5c;
+*8da46e6aea428858015c080bb810;
+*5da46e6ae86d20;
+*8da3c775990da70d180457361e57;
+*8dae5d8aea00085ee53e004546c3;
+*8dae5d8a580d77d658d63e32c82f;
+*5dae5d8a54a93d;
+*8da3c77558af803cce430dad950f;
+*200015b8f3156e;
+*02e615b82df0c7;
+*02e615b82df0c7;
+*8da3c775990da70d180458c9be1f;
+*8dae5d8a99a4400e70088202ff80;
+*5dae5d8a54a93d;
+*200015b8f3156e;
+*200015b8f3156e;
+*8dae5d8a580d702c844b24b6523e;
+*8dae5d8af80300020049bc1cd8f3;
+*200015b8f3156e;
+*20000197d80069;
+*5dae5d8a54a93d;
+*020001970f9c90;
+*8dae5d8a580d77d688d63170d088;
+*8da3c77558af87e6a0cdf2c8bbf8;
+*8dae5d8aea00085ee53e004546c3;
+*8dae5d8a274c824e4b4ca06f9608;
+*5dae5d8a54a93d;
+*8dae5d8a99a4400e700c823ac980;
+*020001970f9c90;
+*5da15c54111a4b;
+*8dae5d8a580d77d6a0d62aa4760f;
+*5da3c7758f35d4;
+*8dae5d8aea00085ee53e004546c3;
+*8dae5d8a99a4410e500c827cbf67;
+*8da15c54581b8019e24c96ebec6d;
+*8dae5d8a580d77d6ccd61fccec2f;
+*5dae5d8a54a93d;
+*8dae5d8a99a4410e500c827cbf67;
+*8dae5d8a580d77d6d8d61cd91129;
+*8dae5d8a99a4410e500c827cbf67;
+*8dae5d8a580d77d6e2d619cbefa5;
+*8dae5d8af80300020049bc1cd8f3;
+*20000197d80069;
+*80000197580d77d6e8d6172cc0e3;
+*8dae5d8a580d702d044b0189a64f;
+*020001970f9c90;
+*8dae5d8a99a4410e500882448967;
+*8dae5d8a580d77d6fad6128791c3;
+*5dae5d8a54a93d;
+*8dae5d8a99a4410e500882448967;
+*020001970f9c90;
+*8da15c54581bc01a424c2f038351;
+*8dae5d8ae1080800000000e6168f;
+*8da3c77558af87e730ccd3243e2f;
+*8dae5d8a580d87d728d6051c99a8;
+*5dae5d8a54a93d;
+*8dae5d8aea00085ee53e004546c3;
+*8dae5d8a99a4410e500882448967;
+*8dae5d8a580d802d584aea9aed46;
+*5da15c54111a4b;
+*8dae5d8a99a4410e500c827cbf67;
+*2000019827a021;
+*8dae5d8af80300020049bc1cd8f3;
+*8dae5d8a580d87d754d5f94050dd;
+*8dae5d8a99a4410e500c827cbf67;
+*5dae5d8a54a93d;
+*8dae5d8a99a4410e500c827cbf67;
+*02000198f03cd8;
+*8dae5d8a580d87d76ed5f252fa10;
+*8dae5d8aea00085ee53e004546c3;
+*8da15c5499150a0df0ac0d713d8d;
+*200015b8f3156e;
+*8da3c775990da70d100458a71c17;
+*8dae5d8a580d87d778d5ef5c1b0d;
+*8dae5d8a99a4410e500882448967;
+*5dae5d8a54a93d;
+*02818393027eb0;
+*5da3c7758f35d5;
+*5da3c7758f35d5;
+*5da3c7758f35d4;
+*200015b8f3156e;
+*8dae5d8a580d87d782d5ec2e3d53;
+*8da15c54ea178858015e88a53d08;
+*5dae5d8a54a93d;
+*8dae5d8a99a4410e500882448967;
+*02000198f03cd8;
+*8dae5d8ae1080800000000e6168f;
+*200015b8f3156e;
+*8dae5d8a580d802db04ad2d09e9c;
+*02e195b8f5cd24;
+*8da15c5499150b0db0b40d687b11;
+*8dae5d8aea00085ee53e004546c3;
+*8dae5d8a99a4410e500882448967;
+*8dae5d8a580d802dc64accee13e8;
+*2000019827a021;
+*8dae5d8a99a4410e500881bb6175;
+*8dae5d8a580d802ddc4ac5b9d917;
+*8dae5d8af80300020049bc1cd8f3;
+*80000198580d87d7cad5d9283036;
+*02000198f03cd8;
+*5da15c54111a4b;
+*8dae5d8a580d87d7ecd5d0a28b94;
+*8dae5d8a99a4410e500881bb6175;
+*8da15c54234cb5f3cf0c6055934a;
+*5dae5d8a54a93d;
+*8da15c5499150d0d50c40e1a396a;
+*8da15c5499150d0d30c40ed5bd11;
+*5da15c54111a4b;
+*5da46e6ae86d29;
+*8da15c54581f201b484af27089b0;
+*02000198f03cd8;
+*5dae5d8a54a93d;

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/flowMatch.js

@@ -1,7 +1,7 @@
 /**
- * @file Flow→road matching: assign TomTom congestion levels to Overpass roads.
+ * @file Flow→road matching: assign TomTom congestion levels to OpenStreetMap roads.
  *
- * The traffic layer renders dots along OSM road polylines (Overpass), while
+ * In OpenStreetMap road mode the layer renders OpenFreeMap polylines, while
  * TomTom flow tiles carry their own (differently segmented) polylines with
  * `traffic_level`. This module snaps flow onto roads geometrically:
  *
@@ -11,8 +11,10 @@
  *     projected to local meters (degree cell size cos(lat)-adjusted).
  *  2. Each road is sampled at up to 7 evenly-spaced points along its length;
  *     each sample looks for the nearest flow segment within 35 m whose
- *     bearing agrees within 30° (folded mod 180° so two-way roads match
- *     opposite-direction flow lines).
+ *     bearing agrees with the road travel direction within 30°. Two-way
+ *     roads are represented as separate travel directions by the layer. A
+ *     flow line whose `coverage` is `full` describes both directions of its
+ *     road, so either travel bearing may match it.
  *  3. A road matches when at least half its samples (minimum 2) matched; its
  *     level is the MEDIAN of the matched samples' trafficLevels, and closure
  *     is true if ANY matched segment is closed.
@@ -29,7 +31,7 @@ const M_PER_DEG_LAT = 111320;
 const CELL_SIZE_M = 100;
 /** @const {number} Max snap distance from a road sample to a flow segment. */
 const MATCH_RADIUS_M = 35;
-/** @const {number} Max bearing disagreement (degrees, folded mod 180). */
+/** @const {number} Max travel-bearing disagreement (degrees). */
 const BEARING_TOLERANCE_DEG = 30;
 /** @const {number} Evenly-spaced samples per road. */
 const ROAD_SAMPLES = 7;
@@ -56,15 +58,14 @@ function bearingDeg(dx, dy) {
 }
 
 /**
- * Bearing disagreement folded mod 180° — a flow line drawn in the opposite
- * direction of travel still describes the same two-way road.
+ * Travel-bearing disagreement; opposing flow never matches.
  * @param {number} a - Bearing (degrees). @param {number} b - Bearing (degrees).
- * @returns {number} min(|Δ|, 180 − |Δ|) in [0, 90].
+ * @returns {number} Angular difference in [0, 180].
  */
 function bearingDiffDeg(a, b) {
   let d = Math.abs(a - b) % 360;
   if (d > 180) d = 360 - d;
-  return Math.min(d, 180 - d);
+  return d;
 }
 
 /** Squared distance from point (px,py) to segment (ax,ay)-(bx,by), meters². */
@@ -80,61 +81,45 @@ function pointSegDist2(px, py, ax, ay, bx, by) {
 }
 
 /**
- * Match flow segments onto roads.
+ * Index flow polylines for nearest-segment queries in local meters.
  *
- * @param {Array<{coords:number[][], type:string}>} roads
- *   Parsed Overpass road objects ([[lon,lat],…] polylines).
- * @param {Array<{coords:number[][], trafficLevel:number, roadType:string, closure:boolean}>} flowSegments
- *   Decoded flow polylines from `flowTiles.js`.
- * @returns {{
- *   matches: Array<{level:number, closure:boolean}|null>,
- *   matchedCount: number,
- *   candidateCount: number,
- * }}
- *   `matches` is PARALLEL to `roads` (index i describes roads[i]; null = no
- *   flow data for that road, render it exactly as today). `candidateCount` is
- *   the number of roads with at least one flow segment inside the 35 m search
- *   radius regardless of bearing — the denominator for coverage stats.
+ * Shared by congestion matching and the Hybrid road-source dedupe, so both
+ * use one distance, bearing and direction rule.
+ *
+ * @param {Array<{coords:number[][], trafficLevel:number, closure:boolean, coverage?:string}>} flowSegments
+ * @returns {null|{
+ *   project: (lon:number, lat:number) => [number, number],
+ *   nearest: (x:number, y:number, bearing:number, radiusFor?:(segment:object) => number) => {best:object|null, ambiguous:boolean, candidate:boolean},
+ * }} Null when no usable segment exists.
  */
-export function matchFlowToRoads(roads, flowSegments) {
-  const roadCount = Array.isArray(roads) ? roads.length : 0;
-  const matches = new Array(roadCount).fill(null);
-  const empty = { matches, matchedCount: 0, candidateCount: 0 };
-  if (
-    roadCount === 0 ||
-    !Array.isArray(flowSegments) ||
-    flowSegments.length === 0
-  ) {
-    return empty;
-  }
-
+export function createFlowSegmentIndex(flowSegments) {
+  if (!Array.isArray(flowSegments)) return null;
   // Local equirectangular projection anchored at the first flow coordinate —
   // over a ≤0.05° fetch box the distortion is negligible.
   const anchor = flowSegments.find(
     (f) => Array.isArray(f?.coords) && f.coords.length >= 2,
   );
-  if (!anchor) return empty;
+  if (!anchor) return null;
   const [refLon, refLat] = anchor.coords[0];
   const mPerDegLon = M_PER_DEG_LAT * Math.cos((refLat * Math.PI) / 180);
-  const projX = (lon) => (lon - refLon) * mPerDegLon;
-  const projY = (lat) => (lat - refLat) * M_PER_DEG_LAT;
+  const project = (lon, lat) => [
+    (lon - refLon) * mPerDegLon,
+    (lat - refLat) * M_PER_DEG_LAT,
+  ];
 
-  // ── 1. Spatial hash of flow segments (midpoint-keyed 100 m cells) ──
-  /** @type {Map<string, Array<{ax:number,ay:number,bx:number,by:number,bearing:number,level:number,closure:boolean}>>} */
+  // Spatial hash of flow segments (midpoint-keyed 100 m cells).
   const grid = new Map();
-  const cellOf = (x, y) =>
-    `${Math.floor(x / CELL_SIZE_M)},${Math.floor(y / CELL_SIZE_M)}`;
-
+  const cellKey = (cx, cy) => (cx + 0x8000) * 0x10000 + (cy + 0x8000);
   for (const flow of flowSegments) {
     const coords = flow?.coords;
     if (!Array.isArray(coords) || coords.length < 2) continue;
     const level = flow.trafficLevel;
     const closure = flow.closure === true;
+    const bothDirections = flow.coverage === 'full';
+    const roadType = flow.roadType;
     for (let i = 0; i < coords.length - 1; i++) {
-      const ax = projX(coords[i][0]);
-      const ay = projY(coords[i][1]);
-      const bx = projX(coords[i + 1][0]);
-      const by = projY(coords[i + 1][1]);
+      const [ax, ay] = project(coords[i][0], coords[i][1]);
+      const [bx, by] = project(coords[i + 1][0], coords[i + 1][1]);
       const segLen = Math.hypot(bx - ax, by - ay);
       if (!(segLen > 0)) continue;
       const bearing = bearingDeg(bx - ax, by - ay);
@@ -150,10 +135,15 @@ export function matchFlowToRoads(roads, flowSegments) {
           bx: ax + (bx - ax) * t1,
           by: ay + (by - ay) * t1,
           bearing,
+          bothDirections,
+          roadType,
           level,
           closure,
         };
-        const key = cellOf((seg.ax + seg.bx) / 2, (seg.ay + seg.by) / 2);
+        const key = cellKey(
+          Math.floor((seg.ax + seg.bx) / 2 / CELL_SIZE_M),
+          Math.floor((seg.ay + seg.by) / 2 / CELL_SIZE_M),
+        );
         let bucket = grid.get(key);
         if (!bucket) {
           bucket = [];
@@ -163,13 +153,87 @@ export function matchFlowToRoads(roads, flowSegments) {
       }
     }
   }
-  if (grid.size === 0) return empty;
+  if (grid.size === 0) return null;
 
   const radius2 = MATCH_RADIUS_M * MATCH_RADIUS_M;
+  /**
+   * Nearest direction-compatible segment within 35 m of a projected point.
+   * `radiusFor(segment)` may tighten the radius per segment (never widen it).
+   */
+  function nearest(px, py, bearing, radiusFor = null) {
+    const cx = Math.floor(px / CELL_SIZE_M);
+    const cy = Math.floor(py / CELL_SIZE_M);
+    let best = null;
+    let bestDist2 = radius2;
+    let ambiguous = false;
+    let candidate = false;
+    for (let gy = cy - 1; gy <= cy + 1; gy++) {
+      for (let gx = cx - 1; gx <= cx + 1; gx++) {
+        const bucket = grid.get(cellKey(gx, gy));
+        if (!bucket) continue;
+        for (const seg of bucket) {
+          const d2 = pointSegDist2(px, py, seg.ax, seg.ay, seg.bx, seg.by);
+          if (d2 > radius2) continue;
+          candidate = true; // within radius, bearing not yet checked
+          if (radiusFor) {
+            const radius = Math.min(MATCH_RADIUS_M, radiusFor(seg));
+            if (d2 > radius * radius) continue;
+          }
+          const diff = bearingDiffDeg(seg.bearing, bearing);
+          if (
+            diff >= BEARING_TOLERANCE_DEG &&
+            !(seg.bothDirections && 180 - diff < BEARING_TOLERANCE_DEG)
+          )
+            continue;
+          if (d2 < bestDist2 - 1) {
+            bestDist2 = d2;
+            best = seg;
+            ambiguous = false;
+          } else if (Math.abs(d2 - bestDist2) <= 1) {
+            if (
+              best &&
+              (best.level !== seg.level || best.closure !== seg.closure)
+            )
+              ambiguous = true;
+            else if (!best) best = seg;
+          }
+        }
+      }
+    }
+    return { best, ambiguous, candidate };
+  }
+  return { project, nearest };
+}
+
+/**
+ * Match flow segments onto roads.
+ *
+ * @param {Array<{coords:number[][], type:string, oneway?:number}>} roads
+ *   Parsed OpenStreetMap road objects ([[lon,lat],…] polylines).
+ * @param {Array<{coords:number[][], trafficLevel:number, roadType:string, closure:boolean, coverage?:string}>} flowSegments
+ *   Decoded flow polylines from `flowDecode.js`.
+ * @returns {{
+ *   matches: Array<{level:number, closure:boolean}|null>,
+ *   matchedCount: number,
+ *   candidateCount: number,
+ * }}
+ *   `matches` is PARALLEL to `roads` (index i describes roads[i]; null = no
+ *   flow data for that road, render it exactly as today). `candidateCount` is
+ *   the number of roads with at least one flow segment inside the 35 m search
+ *   radius regardless of bearing before bearing rejection.
+ */
+export function matchFlowToRoads(roads, flowSegments) {
+  const roadCount = Array.isArray(roads) ? roads.length : 0;
+  const matches = new Array(roadCount).fill(null);
+  const empty = { matches, matchedCount: 0, candidateCount: 0 };
+  if (roadCount === 0) return empty;
+  const index = createFlowSegmentIndex(flowSegments);
+  if (!index) return empty;
+
   let matchedCount = 0;
   let candidateCount = 0;
 
-  // ── 2+3. Sample each road and vote ──
+  // Sample each road and vote.
   for (let r = 0; r < roadCount; r++) {
     const coords = roads[r]?.coords;
     if (!Array.isArray(coords) || coords.length < 2) continue;
@@ -180,8 +244,7 @@ export function matchFlowToRoads(roads, flowSegments) {
     const cum = new Array(coords.length);
     cum[0] = 0;
     for (let i = 0; i < coords.length; i++) {
-      xs[i] = projX(coords[i][0]);
-      ys[i] = projY(coords[i][1]);
+      [xs[i], ys[i]] = index.project(coords[i][0], coords[i][1]);
       if (i > 0)
         cum[i] = cum[i - 1] + Math.hypot(xs[i] - xs[i - 1], ys[i] - ys[i - 1]);
     }
@@ -202,37 +265,17 @@ export function matchFlowToRoads(roads, flowSegments) {
         (target - cum[cursor - 1]) / (cum[cursor] - cum[cursor - 1] || 1);
       const px = xs[cursor - 1] + (xs[cursor] - xs[cursor - 1]) * segT;
       const py = ys[cursor - 1] + (ys[cursor] - ys[cursor - 1]) * segT;
-      const sampleBearing = bearingDeg(
-        xs[cursor] - xs[cursor - 1],
-        ys[cursor] - ys[cursor - 1],
-      );
+      const sampleBearing =
+        (roads[r].oneway === -1 ? 180 : 0) +
+        bearingDeg(xs[cursor] - xs[cursor - 1], ys[cursor] - ys[cursor - 1]);
 
-      // 3×3 cell probe around the sample.
-      const cx = Math.floor(px / CELL_SIZE_M);
-      const cy = Math.floor(py / CELL_SIZE_M);
-      let best = null;
-      let bestDist2 = radius2;
-      for (let gy = cy - 1; gy <= cy + 1; gy++) {
-        for (let gx = cx - 1; gx <= cx + 1; gx++) {
-          const bucket = grid.get(`${gx},${gy}`);
-          if (!bucket) continue;
-          for (const seg of bucket) {
-            const d2 = pointSegDist2(px, py, seg.ax, seg.ay, seg.bx, seg.by);
-            if (d2 > radius2) continue;
-            hadCandidate = true; // within radius, bearing not yet checked
-            if (
-              bearingDiffDeg(seg.bearing, sampleBearing) >=
-              BEARING_TOLERANCE_DEG
-            )
-              continue;
-            if (d2 <= bestDist2) {
-              bestDist2 = d2;
-              best = seg;
-            }
-          }
-        }
-      }
-      if (best) {
+      const { best, ambiguous, candidate } = index.nearest(
+        px,
+        py,
+        sampleBearing,
+      );
+      if (candidate) hadCandidate = true;
+      if (best && !ambiguous) {
         matchedLevels.push(best.level);
         if (best.closure) matchedClosure = true;
       }

src/data/flowMatch.test.mjs

@@ -44,10 +44,10 @@ test('coincident parallel road matches with the flow level', () => {
   assert.equal(matches[0].closure, false);
 });
 
-test('opposite-direction flow still matches (two-way bearing fold)', () => {
+test('opposite-direction flow matches only the reverse travel direction)', () => {
   // Same line drawn south->north vs road north->south equivalence.
   const reversed = line({ lengthM: 500, bearingDeg: 0, eastM: 4 }).reverse();
-  const { matches } = matchFlowToRoads([ROAD_NS], [flow(reversed, 0.3)]);
+  const { matches } = matchFlowToRoads([{...ROAD_NS, oneway:-1}], [flow(reversed, 0.3)]);
   assert.ok(matches[0], 'reversed flow should still match');
   assert.ok(Math.abs(matches[0].level - 0.3) < 1e-9);
 });
@@ -159,3 +159,28 @@ test('median: single value and empty', () => {
   assert.equal(median([0.7]), 0.7);
   assert.equal(median([]), null);
 });
+
+test('one-way rejects opposite closure and two travel directions retain separate congestion', () => {
+  const coords = [[0,0],[0.002,0]];
+  const forward = {coords, oneway:1};
+  const reverse = {coords, oneway:-1};
+  const east = {coords, trafficLevel:1, closure:false};
+  const west = {coords:[...coords].reverse(), trafficLevel:0, closure:true};
+  assert.equal(matchFlowToRoads([forward],[west]).matches[0], null);
+  for (const flows of [[east,west],[west,east]]) {
+    assert.deepEqual(matchFlowToRoads([forward,reverse],flows).matches,
+      [{level:1,closure:false},{level:0,closure:true}]);
+  }
+  assert.equal(matchFlowToRoads([forward],[east,{...east,trafficLevel:0,closure:true}]).matches[0], null);
+});
+
+test('a full-coverage flow line matches both travel directions; one-side does not', () => {
+  const coords = [[0,0],[0.002,0]];
+  const directions = [{coords, oneway:1}, {coords, oneway:-1}];
+  const full = {coords, trafficLevel:0.4, closure:false, coverage:'full'};
+  assert.deepEqual(matchFlowToRoads(directions, [full]).matches,
+    [{level:0.4,closure:false},{level:0.4,closure:false}]);
+  const oneSide = {...full, coverage:'one_side'};
+  assert.deepEqual(matchFlowToRoads(directions, [oneSide]).matches,
+    [{level:0.4,closure:false}, null]);
+});

src/data/gbfsProxy.test.mjs

@@ -1,6 +1,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  GBFS_CLIENT_IDENTIFIER,
   GBFS_MAX_BODY_BYTES,
   fetchGbfsUpstream,
 } from '../../server/providers/gbfs.js';
@@ -56,6 +57,41 @@ test('GBFS upstream fetch passes a direct 200 through unchanged', async () => {
   });
 });
 
+test('GBFS upstream fetch names the app in the Client-Identifier header', async () => {
+  let observedHeaders = null;
+  await fetchGbfsUpstream(
+    'https://gbfs.urbansharing.com/oslobysykkel.no/station_status.json',
+    {
+      fetchImpl: async (_url, options) => {
+        observedHeaders = options.headers;
+        return new Response(STATION_BODY, { status: 200 });
+      },
+    },
+  );
+  assert.equal(GBFS_CLIENT_IDENTIFIER, 'gods-eye-view');
+  assert.equal(observedHeaders['Client-Identifier'], GBFS_CLIENT_IDENTIFIER);
+});
+
+test('GBFS upstream fetch adds ET-Client-Name for Entur and only for Entur', async () => {
+  const headersFor = async (url) => {
+    let observed = null;
+    await fetchGbfsUpstream(url, {
+      fetchImpl: async (_url, options) => {
+        observed = options.headers;
+        return new Response(STATION_BODY, { status: 200 });
+      },
+    });
+    return observed;
+  };
+  const entur = await headersFor(
+    'https://api.entur.io/mobility/v2/gbfs/v2/kolumbusbysykkel/station_status',
+  );
+  assert.equal(entur['ET-Client-Name'], 'gods-eye-view-bikeshare');
+  assert.equal(entur['Client-Identifier'], GBFS_CLIENT_IDENTIFIER);
+  const lyft = await headersFor(STATION_URL);
+  assert.equal(lyft['ET-Client-Name'], undefined);
+});
+
 test('GBFS upstream fetch forwards a non-redirect error status for the middleware to relay', async () => {
   const result = await fetchGbfsUpstream(STATION_URL, {
     fetchImpl: async () => new Response(null, { status: 404 }),

src/data/gbfsSource.js

@@ -4,10 +4,35 @@ const GBFS_ALLOWED_HOSTS = new Set([
   'gbfs.bluebikes.com',
   'gbfs.bcycle.com',
   'gbfs.biketownpdx.com',
-  'gbfs.cogobikeshare.com',
+  'reddybikeshare.socialbicycles.com',
   'austin.publicbikesystem.net',
   'hon.publicbikesystem.net',
   'chat.publicbikesystem.net',
+  'gbfs.urbansharing.com',
+  'api.entur.io',
+  'api.cyclocity.fr',
+]);
+
+/**
+ * Hosts that serve more than GBFS keep the proxy to their GBFS tree: Entur's
+ * api.entur.io fronts every Entur API, and api.cyclocity.fr every JCDecaux
+ * contract endpoint.
+ */
+const GBFS_HOST_PATH_PREFIXES = new Map([
+  ['api.entur.io', '/mobility/v2/gbfs/'],
+  ['api.cyclocity.fr', '/contracts/'],
+]);
+
+/**
+ * Identifying headers an operator asks every GBFS client to send. Entur rate
+ * limits or blocks consumers that do not send ET-Client-Name, in the form
+ * "company-application".
+ */
+const GBFS_HOST_HEADERS = new Map([
+  [
+    'api.entur.io',
+    Object.freeze({ 'ET-Client-Name': 'gods-eye-view-bikeshare' }),
+  ],
 ]);
 
 /**
@@ -28,13 +53,40 @@ export function isAllowedGbfsHost(hostname) {
 }
 
 /**
- * Only allow station_information.json and station_status.json endpoints.
+ * Only allow station_information and station_status endpoints. The `.json`
+ * suffix is optional because Entur serves its feeds without one. When a
+ * hostname is given and that host serves more than GBFS, the path must also
+ * sit under the host's GBFS prefix.
  *
  * @param {string} pathname
+ * @param {string} [hostname]
  * @returns {boolean}
  */
-export function isAllowedGbfsPath(pathname) {
-  return /\/station_(information|status)\.json$/i.test(String(pathname || ''));
+export function isAllowedGbfsPath(pathname, hostname = '') {
+  const path = String(pathname || '');
+  if (!/\/station_(information|status)(\.json)?$/i.test(path)) return false;
+  const prefix = GBFS_HOST_PATH_PREFIXES.get(
+    String(hostname || '')
+      .trim()
+      .toLowerCase(),
+  );
+  return !prefix || path.startsWith(prefix);
+}
+
+/**
+ * Extra request headers an upstream GBFS host asks clients to send.
+ *
+ * @param {string} hostname
+ * @returns {Record<string, string>}
+ */
+export function gbfsUpstreamHeaders(hostname) {
+  return (
+    GBFS_HOST_HEADERS.get(
+      String(hostname || '')
+        .trim()
+        .toLowerCase(),
+    ) || {}
+  );
 }
 
 /**
@@ -47,7 +99,7 @@ export function isAllowedGbfsPath(pathname) {
  * @returns {string} Cache-Control header value.
  */
 export function gbfsCacheControl(pathname) {
-  if (/\/station_information\.json$/i.test(String(pathname || ''))) {
+  if (/\/station_information(\.json)?$/i.test(String(pathname || ''))) {
     return 'public, max-age=300';
   }
   return 'no-store';

src/data/geoImportImages.js

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

src/data/geoImportPins.js

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

src/data/gnssIntegrityProxy.test.mjs

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

src/data/idSwitches.js

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

src/data/infrastructure.js

@@ -1,12 +1,5 @@
 import { createLocalGeoJsonLayer } from './localGeojsonCore.js';
-
-// Resolved by Vite in builds and relative to this module in other consumers.
-const datacentersUrl = new URL(
-  './local_data/datacenters/datacenters.geojsonl',
-  import.meta.url,
-).href;
-const damsUrl = new URL('./local_data/dams/dams.geojsonl', import.meta.url)
-  .href;
+import { INFRASTRUCTURE_DATA_URLS } from '../sources/infrastructureData.js';
 
 /**
  * Create fresh datacenter and dam layers without starting or loading them.
@@ -14,6 +7,8 @@ const damsUrl = new URL('./local_data/dams/dams.geojsonl', import.meta.url)
  * @returns {object[]} Datacenters then dams, with stable standalone identities.
  */
 export function createInfrastructureLayers(services) {
+  const datacentersUrl = INFRASTRUCTURE_DATA_URLS['local-datacenters'];
+  const damsUrl = INFRASTRUCTURE_DATA_URLS['local-dams'];
   const datacenters = createLocalGeoJsonLayer(
     {
       id: 'local-datacenters',
@@ -22,6 +17,7 @@ export function createInfrastructureLayers(services) {
       color: '#00ffff', // Cyan
       icon: '▣',
       source: 'Local',
+      osmDerived: true,
       labels: true,
       labelMax: 700,
       labelGridPx: 138,
@@ -37,6 +33,7 @@ export function createInfrastructureLayers(services) {
       color: '#0088ff', // Blue
       icon: '▰',
       source: 'USACE',
+      osmDerived: true,
       labels: true,
       labelMax: 900,
       labelGridPx: 132,

src/data/infrastructure.test.mjs

@@ -8,9 +8,12 @@ import { createLocalGeoJsonLayer } from 'gods-eye-view/infrastructure/geojson';
 
 function services() {
   const records = new Map();
+  const credited = [];
   let selection;
   return {
     records,
+    credited,
+    showOsmCredit: (viewer) => credited.push(viewer),
     overlayHost: { setEntries() {}, setVisible() {}, clearSource() {} },
     registerEntityContext(entity, metadata) {
       records.set(metadata.id, { entity, ...metadata });
@@ -121,6 +124,7 @@ test('two viewers use their supplied contexts and dispose independently', async
       {
         id: 'local-dams',
         name: 'Dams',
+        osmDerived: true,
         color: '#0088ff',
         url: '/dams.geojsonl',
         screenSpaceEventHandlerFactory: () => ({
@@ -150,6 +154,10 @@ test('two viewers use their supplied contexts and dispose independently', async
   );
   await Promise.all(instances.map(({ layer, viewer }) => layer.enable(viewer)));
   assert.equal(hosts[0].records.size, 1);
+  assert.deepEqual(
+    hosts.map((host) => host.credited),
+    instances.map(({ viewer }) => [viewer]),
+  );
   assert.equal(hosts[1].records.size, 1);
   instances[0].click();
   assert.ok(hosts[0].selection());
@@ -184,6 +192,8 @@ 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/infrastructureOverlayEntry.js

@@ -0,0 +1,43 @@
+const LOCAL_OVERLAY_MAX_DISTANCE_M = 14000000;
+const LOCAL_OVERLAY_FADE_START_M = 250000;
+const LOCAL_OVERLAY_FADE_START_RATIO =
+  LOCAL_OVERLAY_FADE_START_M / LOCAL_OVERLAY_MAX_DISTANCE_M;
+
+/** Shared ambient infrastructure card contract; the host owns projection and persistence. */
+export function createInfrastructureOverlayEntry({
+  id,
+  source,
+  position,
+  title,
+  details = [],
+  accent,
+  priority,
+}) {
+  return {
+    id: String(id),
+    source: source,
+    position,
+    variant: 'card',
+    title: title,
+    details: details,
+    accent,
+    priority,
+    collisionGroup: 'ambient-card',
+    zIndex: 30,
+    interactive: false,
+    minDistance: 0,
+    maxDistance: LOCAL_OVERLAY_MAX_DISTANCE_M,
+    distanceFadeStartRatio: LOCAL_OVERLAY_FADE_START_RATIO,
+    distanceScale: {
+      near: 250000,
+      nearValue: 1,
+      far: 9000000,
+      farValue: 0.62,
+    },
+    edgeFade: 'keyhole',
+    horizonCull: true,
+    terrainOcclusion: false,
+    gapPx: 15,
+    placement: 'above',
+  };
+}

src/data/installationFeedback.js

@@ -4,6 +4,8 @@ export function installationFeedback(stats = {}, now = Date.now()) {
     rate_limited: 'Overpass rate-limited',
     timeout: 'Overpass timed out',
     query_failed: 'Overpass could not complete the query',
+    tiles_unavailable: 'Map tiles temporarily unavailable',
+    names_unavailable: 'Mapped names temporarily unavailable',
   };
   const reason =
     reasons[stats.failureReason] || 'Overpass temporarily unavailable';
@@ -18,5 +20,16 @@ export function installationFeedback(stats = {}, now = Date.now()) {
     return 'Zoom in to search mapped installations';
   if (stats.stale) return 'Showing cached mapped sites';
   if (stats.status === 'idle') return 'Mapped sites not loaded';
+  // With a count, say what was found and where; an empty area is not "loaded".
+  if (Number.isFinite(stats.count)) {
+    const km =
+      stats.coverage?.kind === 'subject' &&
+      Number.isFinite(stats.coverage.radiusM)
+        ? Math.round(stats.coverage.radiusM / 1000)
+        : null;
+    const where = km ? ` within ${km} km of the contact` : ' in view';
+    if (stats.count === 0) return `No mapped sites${where}`;
+    return `${stats.count} mapped site${stats.count === 1 ? '' : 's'}${where}`;
+  }
   return 'Mapped sites loaded';
 }

src/data/installationFeedback.test.mjs

@@ -19,3 +19,16 @@ test('first fetch, retry, cached data and success have distinct copy', () => {
   assert.equal(installationFeedback({ status: 'ready' }), 'Mapped sites loaded');
   assert.equal(installationFeedback({ stale: true }), 'Showing cached mapped sites');
 });
+test('a counted result names what was found and where', () => {
+  assert.equal(installationFeedback({ status: 'ready', count: 3 }), '3 mapped sites in view');
+  assert.equal(installationFeedback({ status: 'empty', count: 0 }), 'No mapped sites in view');
+  const coverage = { kind: 'subject', radiusM: 100_000 };
+  assert.equal(
+    installationFeedback({ status: 'ready', count: 1, coverage }),
+    '1 mapped site within 100 km of the contact',
+  );
+  assert.equal(
+    installationFeedback({ status: 'unavailable', failureReason: 'tiles_unavailable' }),
+    'Map tiles temporarily unavailable',
+  );
+});

src/data/installationProxy.test.mjs

@@ -26,6 +26,7 @@ import {
   validMilitaryInstallationBox,
   writeMilitaryInstallationDisk,
 } from '../../vite.config.js';
+import { resolveOverpassUpstreamTag } from '../../server/providers/overpass/constants.js';
 
 const DAY_MS = 86_400_000;
 test('installation failure reasons disclose no raw upstream error and do not guess overload', () => {
@@ -274,3 +275,30 @@ test('an unwritable cache directory degrades to a miss instead of throwing', asy
     await fsp.rm(dir, { recursive: true, force: true });
   }
 });
+
+test('an installation entry is not served after OVERPASS_UPSTREAMS is repointed', async (t) => {
+  const prior = process.env.OVERPASS_UPSTREAMS;
+  t.after(() => {
+    if (prior === undefined) delete process.env.OVERPASS_UPSTREAMS;
+    else process.env.OVERPASS_UPSTREAMS = prior;
+  });
+  const dir = tempCacheDir();
+  const key = '30.250,-97.750,30.300,-97.700';
+  try {
+    process.env.OVERPASS_UPSTREAMS = 'https://a.example/api/interpreter,https://b.example/api/interpreter';
+    const tag = resolveOverpassUpstreamTag();
+    await writeMilitaryInstallationDisk(key, { ...entry(Date.now()), upstreams: tag }, dir);
+    assert.ok(await readMilitaryInstallationDisk(key, TTL_MS, dir), 'its own entry is a hit');
+    process.env.OVERPASS_UPSTREAMS = 'https://b.example/api/interpreter,https://a.example/api/interpreter';
+    assert.equal(resolveOverpassUpstreamTag(), tag, 'reordering the same instances keeps the tag');
+    process.env.OVERPASS_UPSTREAMS = 'https://c.example/api/interpreter';
+    assert.equal(await readMilitaryInstallationDisk(key, TTL_MS, dir), null, 'fresh read refused');
+    assert.equal(await readMilitaryInstallationDisk(key, Infinity, dir), null, 'stale read refused');
+    await writeMilitaryInstallationDisk('legacy', entry(Date.now()), dir);
+    assert.equal(await readMilitaryInstallationDisk('legacy', Infinity, dir), null, 'untagged entry refused');
+    delete process.env.OVERPASS_UPSTREAMS;
+    assert.ok(await readMilitaryInstallationDisk(key, Infinity, dir), 'nothing configured accepts any entry');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

src/data/issPass.js

@@ -1,33 +1,26 @@
 // src/data/issPass.js
 /**
- * Next-ISS-pass prediction from a satrec: coarse 30 s scan to find a window
- * where elevation ≥ minElevDeg, refined to ~5 s at the edges, tracking peak
- * elevation. ~2880 SGP4 propagations for a 24 h horizon — tens of ms, fine for
- * an on-demand voice call. Pattern from skylight (MIT) shared/src/celestial.ts
- * nextISSPass, extended with set-time + peak tracking.
+ * Next-ISS-pass prediction. Kept as a thin wrapper over satellitePass.js so the
+ * original findNextIssPass signature and defaults still work.
  */
-import { propagate, gstime, eciToEcf, ecfToLookAngles } from 'satellite.js';
+import { findNextSatellitePass, lookAnglesAt } from './satellitePass.js';
 
-const R2D = 180 / Math.PI;
-const D2R = Math.PI / 180;
-
-/** Observer look angles at an instant, or null when propagation fails. */
-export function lookAnglesAt(satrec, dateMs, latDeg, lonDeg) {
-  const date = new Date(dateMs);
-  const pv = propagate(satrec, date);
-  const pos = pv && pv.position;
-  if (!pos || typeof pos === 'boolean') return null;
-  const ecf = eciToEcf(pos, gstime(date));
-  const look = ecfToLookAngles(
-    { latitude: latDeg * D2R, longitude: lonDeg * D2R, height: 0 },
-    ecf,
-  );
-  return {
-    elevDeg: look.elevation * R2D,
-    azDeg: (((look.azimuth * R2D) % 360) + 360) % 360,
-  };
-}
+export { lookAnglesAt };
 
+/**
+ * Predict the next ISS pass over an observer location.
+ * @param {Object} options
+ * @param {Object} options.satrec SGP4 satellite record
+ * @param {number} options.latDeg Observer latitude in degrees [-90, 90]
+ * @param {number} options.lonDeg Observer longitude in degrees [-180, 180]
+ * @param {number} options.fromMs UTC start time in milliseconds
+ * @param {number} [options.minElevDeg=10] Elevation that defines rise and set, in degrees
+ * @param {number} [options.horizonHours=24] Maximum search window in hours
+ * @param {number} [options.coarseStepSec=30] Coarse search step in seconds
+ * @param {number} [options.fineStepSec=5] Fine transit step in seconds for peak tracking and visibility
+ * @param {boolean} [options.requireVisible=false] Require a naked-eye-visible pass
+ * @returns {{ riseMs: number, setMs: number, maxElevDeg: number, maxElevMs: number, riseAzDeg: number, visible: boolean, sunlit: boolean, observerDark: boolean } | null}
+ */
 export function findNextIssPass({
   satrec,
   latDeg,
@@ -37,49 +30,17 @@ export function findNextIssPass({
   horizonHours = 24,
   coarseStepSec = 30,
   fineStepSec = 5,
+  requireVisible = false,
 }) {
-  const elev = (t) => lookAnglesAt(satrec, t, latDeg, lonDeg)?.elevDeg ?? -90;
-  const horizonMs = fromMs + horizonHours * 3600_000;
-  const coarse = coarseStepSec * 1000;
-  const fine = fineStepSec * 1000;
-
-  // Coarse scan for the first sample above threshold. If we START inside a
-  // pass, that's still "the next pass" for a voice answer — accept it.
-  let hit = null;
-  for (let t = fromMs; t <= horizonMs; t += coarse) {
-    if (elev(t) >= minElevDeg) {
-      hit = t;
-      break;
-    }
-  }
-  if (hit == null) return null;
-
-  // Refine rise: walk back in fine steps to the first sample ≥ threshold.
-  let riseMs = hit;
-  while (riseMs - fine > fromMs && elev(riseMs - fine) >= minElevDeg)
-    riseMs -= fine;
-
-  // Walk forward through the pass tracking the peak until we drop below.
-  let maxElevDeg = -90;
-  let maxElevMs = riseMs;
-  let t = riseMs;
-  while (t <= horizonMs) {
-    const e = elev(t);
-    if (e < minElevDeg && t > riseMs) break;
-    if (e > maxElevDeg) {
-      maxElevDeg = e;
-      maxElevMs = t;
-    }
-    t += fine;
-  }
-  const setMs = t;
-
-  const rise = lookAnglesAt(satrec, riseMs, latDeg, lonDeg);
-  return {
-    riseMs,
-    setMs,
-    maxElevDeg,
-    maxElevMs,
-    riseAzDeg: rise ? rise.azDeg : 0,
-  };
+  return findNextSatellitePass({
+    satrec,
+    latDeg,
+    lonDeg,
+    fromMs,
+    minElevDeg,
+    horizonHours,
+    coarseStepSec,
+    fineStepSec,
+    requireVisible,
+  });
 }

src/data/issPass.test.mjs

@@ -3,6 +3,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { twoline2satrec } from 'satellite.js';
 import { findNextIssPass, lookAnglesAt } from './issPass.js';
+import { findNextSatellitePass } from './satellitePass.js';
 
 // Canonical archived ISS TLE (valid checksums; epoch 2008-09-20 ~12:25 UTC).
 const L1 = '1 25544U 98067A   08264.51782528 -.00002182  00000-0 -11606-4 0  2927';
@@ -27,6 +28,13 @@ test('finds a structurally-consistent ISS pass within 24h of the TLE epoch', ()
   assert.ok(before && before.elevDeg < 10);
 });
 
+test('forwards its original 30 s coarse step and fineStepSec to the pass engine', () => {
+  const satrec = twoline2satrec(L1, L2);
+  const opts = { satrec, ...AUSTIN, fromMs: FROM_MS, minElevDeg: 10, fineStepSec: 30 };
+  assert.deepEqual(findNextIssPass(opts), findNextSatellitePass({ ...opts, coarseStepSec: 30 }));
+  assert.notDeepEqual(findNextIssPass(opts), findNextIssPass({ ...opts, fineStepSec: 5 }));
+});
+
 test('returns null when no pass clears an absurd threshold', () => {
   const satrec = twoline2satrec(L1, L2);
   const pass = findNextIssPass({ satrec, ...AUSTIN, fromMs: FROM_MS, minElevDeg: 89.9, horizonHours: 2 });

src/data/labelArbiter.js

@@ -10,6 +10,9 @@ const FADE_IN_MS = 150;
 const FADE_OUT_MS = 300;
 const MIN_LIFETIME_MS = 2500;
 const COOLDOWN_MS = 1200;
+function zeroCount(_value, key, map) {
+  map.set(key, 0);
+}
 
 function clampInt(value, min, max) {
   return Math.max(min, Math.min(max, Math.floor(Number(value) || 0)));
@@ -757,6 +760,8 @@ export class LabelArbiter {
     this._layerBuckets = new Map();
     this._demand = new Map();
     this._quotas = new Map();
+    this._acceptedByLayer = new Map();
+    this._paintedByLayer = new Map();
     this._weightedQuotaScratch = [];
     this._quotaPriorityScratch = [];
     this._quotaRemainderScratch = [];
@@ -770,6 +775,12 @@ export class LabelArbiter {
     this._queue = new SpatialCandidateQueue();
   }
 
+  /** Release an identity when its source changes between ambient and protected paint. */
+  remove(key) {
+    if (this.states.delete(key)) this._stateListDirty = true;
+    this.selectedKeys.delete(key);
+  }
+
   clear() {
     this.states.clear();
     this.selectedKeys.clear();
@@ -781,6 +792,8 @@ export class LabelArbiter {
     this._candidates.length = 0;
     this._layerBuckets.clear();
     this._quotas.clear();
+    this._acceptedByLayer.clear();
+    this._paintedByLayer.clear();
     this._selectedCandidates.length = 0;
     this._selectedPlacements.length = 0;
     this._droppedKeys.length = 0;
@@ -889,6 +902,12 @@ export class LabelArbiter {
         demand.set(layerId, bucket.count);
     });
 
+    const limits = options.limitsByLayer;
+    demand.forEach((count, layerId) => {
+      demand.set(layerId, Math.min(count, limits?.get(layerId) ?? Infinity));
+    });
+    const acceptedByLayer = this._acceptedByLayer;
+    acceptedByLayer.forEach(zeroCount);
     const activeLayers = this._activeLayersScratch;
     let activeCount = 0;
     let totalDemand = 0;
@@ -937,6 +956,9 @@ export class LabelArbiter {
       )
         return false;
       attemptStamps.set(candidate.key, stamp);
+      const layerCount = acceptedByLayer.get(candidate.layerId) || 0;
+      if (layerCount >= (limits?.get(candidate.layerId) ?? Infinity))
+        return false;
       const previous = this.states.get(candidate.key);
       const stateless = candidate.stateless === true;
       // Stateless candidates ignore the re-entry cooldown (they return on the
@@ -955,6 +977,7 @@ export class LabelArbiter {
       selectedCandidates[selectedCount] = candidate;
       selectedPlacements[selectedCount] = placement;
       selectedCount++;
+      acceptedByLayer.set(candidate.layerId, layerCount + 1);
       return true;
     };
 
@@ -968,7 +991,8 @@ export class LabelArbiter {
       if (preserveIncumbents) {
         for (let i = 0; i < layerCount && accepted < target; i++) {
           const candidate = layerList[i];
-          if (!this.states.get(candidate.key)?.selected) continue;
+          if (candidate.stateless || !this.states.get(candidate.key)?.selected)
+            continue;
           if (attempt(candidate, true)) accepted++;
         }
       }
@@ -1139,7 +1163,7 @@ export class LabelArbiter {
    * Reproject accepted/fading identities from the current frame candidate map.
    * A caller-owned output array enables allocation-free per-frame rendering.
    */
-  renderEntries(currentCandidates, now = Date.now(), out = []) {
+  renderEntries(currentCandidates, now = Date.now(), out = [], limits = null) {
     const current =
       currentCandidates instanceof Map
         ? currentCandidates
@@ -1151,6 +1175,20 @@ export class LabelArbiter {
           );
     const states = this._refreshStateList();
     let outIndex = 0;
+    const painted = this._paintedByLayer;
+    painted.forEach(zeroCount);
+    // Reserve the live winners before spending any remaining slots on exit fades.
+    if (limits)
+      for (let i = 0; i < states.length; i++) {
+        const state = states[i];
+        if (!state.selected) continue;
+        const candidate = current.get(state.key) || state.lastCandidate;
+        if (candidate)
+          painted.set(
+            candidate.layerId,
+            (painted.get(candidate.layerId) || 0) + 1,
+          );
+      }
     for (let i = 0; i < states.length; i++) {
       const state = states[i];
       let temporalAlpha;
@@ -1171,9 +1209,14 @@ export class LabelArbiter {
       if (temporalAlpha <= 0) continue;
       const candidate = current.get(state.key) || state.lastCandidate;
       if (!candidate) continue;
+      if (limits && !state.selected) {
+        const count = painted.get(candidate.layerId) || 0;
+        if (count >= (limits.get(candidate.layerId) ?? Infinity)) continue;
+        painted.set(candidate.layerId, count + 1);
+      }
       const placement = renderPlacement(
         candidate,
-        state.stateless ? undefined : state.corner,
+        state.corner,
         state.lastPlacement,
       );
       if (!placement) continue;

src/data/labelArbiter.test.mjs

@@ -345,6 +345,9 @@ test('a stateless candidate keeps no corner, no cooldown, and no fades', () => {
   arbiter.solve([blocker, mover], { capacity: 2, now: 1000 });
   assert.equal(arbiter.states.get('cctv:mover').corner, 'below',
     'it took the free corner while the preferred one was blocked');
+  const paint = arbiter.renderEntries(new Map([[blocker.key, blocker], [mover.key, mover]]), 1000, []);
+  assert.equal(paint.find((entry) => entry.candidate.key === mover.key).placement.corner, 'below',
+    'painting honors this solve’s collision-free corner even without sticky placement');
 
   // Corner is re-decided from geometry, NOT remembered: with the blocker gone the
   // card returns to its preferred placement immediately.
@@ -504,3 +507,44 @@ test('live identities expose selected and temporal fading membership by layer/so
   ]));
   assert.equal(arbiter.liveIdentities({ includeFading: true, now: 1501 }).size, 0);
 });
+
+
+test('stateless labels yield occupied slots and re-rank by area on each solve', () => {
+  const make = (key, x, priority) => ({ key, layerId: 'installations', sourceId: key,
+    priority, keyholeAlpha: 1, stateless: true, screenX: x, screenY: 100,
+    placements: [{ corner: 'above', rect: { x, y: 100, w: 100, h: 20 } }],
+  });
+  const large = make('large', 100, 100), small = make('small', 300, 10);
+  const arbiter = new LabelArbiter();
+  arbiter.solve([large, small], { capacity: 2, now: 1000 });
+  assert.equal(arbiter.selectedKeys.size, 2);
+  small.placements[0].rect.x = 100;
+  arbiter.solve([large, small], { capacity: 2, now: 1016 });
+  assert.deepEqual([...arbiter.selectedKeys], ['large'], 'incumbency never forces a stateless overlap');
+  const larger = make('larger', 100, 1000);
+  arbiter.solve([large, small, larger], { capacity: 2, now: 1032 });
+  assert.deepEqual([...arbiter.selectedKeys], ['larger'], 'area priority outranks a smaller incumbent');
+});
+
+
+test('a source ceiling bounds shared-domain winners and exit fades without evicting incumbents', () => {
+  const arbiter = new LabelArbiter();
+  const sites = Array.from({ length: 40 }, (_, i) => candidate('installations', i));
+  const centers = Array.from({ length: 30 }, (_, i) => candidate('flights', i));
+  const limits = new Map([['installations', 24]]);
+  const solve = (list, now) => arbiter.solve(list, { capacity: 54, limitsByLayer: limits, now });
+  solve([...sites, ...centers], 0);
+  const first = new Set(arbiter.selectedKeys);
+  assert.equal([...first].filter(key => key.startsWith('installations:')).length, 24);
+  for (let i = 1; i <= 10; i++) {
+    for (const site of sites) site.placements[0].rect.x += 0.25;
+    solve([...sites, ...centers], i * 16);
+    assert.deepEqual(arbiter.selectedKeys, first);
+  }
+  const replacements = sites.map((site, i) => ({ ...site, key: `installations:new${i}` }));
+  const current = [...replacements, ...centers];
+  solve(current, 2000);
+  const rendered = arbiter.renderEntries(new Map(current.map(c => [c.key, c])), 2100, [], limits);
+  assert.equal(rendered.filter(r => r.candidate.layerId === 'installations').length, 24);
+  assert.equal(rendered.filter(r => r.candidate.layerId === 'flights').length, 30);
+});

src/data/layerSnapshot.js

@@ -0,0 +1,253 @@
+import { layerFeedState } from './feedState.js';
+/**
+ * Shared layer snapshot envelope for voice and HUD answers.
+ *
+ * Data Layers chips, `analyst_query`, `get_current_view_state`, and the HUD
+ * summary must all name the same feed-state. This module is the one envelope:
+ * it classifies `getStats()` through `layerFeedState` and stamps the result
+ * so a stale or degraded feed cannot be narrated as live. Cesium-free so the
+ * HUD summary proxy can import it from Node.
+ *
+ * @module data/layerSnapshot
+ */
+
+/** Feed states the Data Layers chips and voice/HUD provenance share. */
+export const LAYER_FEED_STATES = Object.freeze([
+  'nominal',
+  'loading',
+  'degraded',
+  'stale',
+  'fallback',
+  'unavailable',
+]);
+
+/** Chip labels for enabled layers. Disabled layers read OFF, not a feed-state. */
+export const LAYER_FEED_STATE_LABELS = Object.freeze({
+  nominal: 'ON',
+  loading: 'LOADING',
+  degraded: 'DEGRADED',
+  stale: 'STALE',
+  fallback: 'FALLBACK',
+  unavailable: 'UNAVAILABLE',
+});
+
+/** Snapshot feed-state including a disabled layer. */
+export const SNAPSHOT_FEED_STATES = Object.freeze([
+  ...LAYER_FEED_STATES,
+  'off',
+]);
+
+/**
+ * Lower rank is more severe. Voice/HUD `overall` is the worst queried state
+ * so a mixed roster cannot hide an unavailable or stale feed behind a nominal
+ * neighbour.
+ */
+export const FEED_STATE_SEVERITY = Object.freeze({
+  unavailable: 0,
+  loading: 1,
+  degraded: 2,
+  stale: 3,
+  fallback: 4,
+  nominal: 5,
+  off: 6,
+});
+
+export { layerFeedState } from './feedState.js';
+
+function snapshotError(stats) {
+  const err = stats?.error || stats?.lastError || stats?.managerRefreshError;
+  if (err == null || err === '') return null;
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Age of a lastUpdate timestamp in whole seconds.
+ * @param {number|null|undefined} lastUpdate Epoch ms.
+ * @param {number} [now=Date.now()] Clock for tests.
+ * @returns {number|null} Non-negative seconds, or null when unknown.
+ */
+export function snapshotAgeSec(lastUpdate, now = Date.now()) {
+  const stamp = Number(lastUpdate);
+  if (!Number.isFinite(stamp) || stamp <= 0) return null;
+  return Math.max(0, Math.floor((now - stamp) / 1000));
+}
+
+/**
+ * Compact age label matching the Data Layers meta line.
+ * @param {number|null|undefined} lastUpdate Epoch ms.
+ * @param {number} [now=Date.now()] Clock for tests.
+ * @returns {string|null} `just now` / `12s ago` / `4m ago` / `2h ago`.
+ */
+export function snapshotAgeLabel(lastUpdate, now = Date.now()) {
+  const sec = snapshotAgeSec(lastUpdate, now);
+  if (sec === null) return null;
+  if (sec < 5) return 'just now';
+  if (sec < 60) return `${sec}s ago`;
+  if (sec < 3600) return `${Math.floor(sec / 60)}m ago`;
+  return `${Math.floor(sec / 3600)}h ago`;
+}
+
+/**
+ * Pick the most severe feed-state from a list.
+ * @param {Iterable<string|null|undefined>} states Feed-state strings.
+ * @returns {'nominal'|'loading'|'degraded'|'stale'|'fallback'|'unavailable'|'off'|null}
+ */
+export function worstFeedState(states) {
+  let worst = null;
+  let worstRank = Number.POSITIVE_INFINITY;
+  for (const state of states || []) {
+    if (!Object.hasOwn(FEED_STATE_SEVERITY, state)) continue;
+    const rank = FEED_STATE_SEVERITY[state];
+    if (rank < worstRank) {
+      worst = state;
+      worstRank = rank;
+    }
+  }
+  return worst;
+}
+
+/**
+ * One honest layer snapshot for voice/HUD narration.
+ *
+ * Disabled layers report `feedState: 'off'` — the same reading the chips use —
+ * even if leftover stats would otherwise classify as stale. Counts and errors
+ * still travel so a disabled layer with a last-known error is inspectable.
+ *
+ * @param {object} [layer] `DataLayerManager.getAll()` projection, or a layer-like
+ *   object with `id`, `enabled`, `stats`, and optional `source`/`name`.
+ * @param {{ now?: number }} [options]
+ * @returns {{
+ *   id: string|null,
+ *   name: string|null,
+ *   enabled: boolean,
+ *   feedState: string,
+ *   source: string|null,
+ *   count: number,
+ *   lastUpdate: number|null,
+ *   ageSec: number|null,
+ *   ageLabel: string|null,
+ *   error: string|null,
+ * }}
+ */
+export function layerSnapshot(layer = {}, { now = Date.now() } = {}) {
+  const stats = (layer && typeof layer.stats === 'object' && layer.stats) || {};
+  const source = String(stats.source || layer.source || '').trim() || null;
+  const enabled = Boolean(layer.enabled);
+  const countRaw = Number(stats.count);
+  const count = Number.isFinite(countRaw) ? countRaw : 0;
+  const lastUpdate = Number.isFinite(Number(stats.lastUpdate))
+    ? Number(stats.lastUpdate)
+    : null;
+  const feedState = enabled ? layerFeedState({ ...stats, source }) : 'off';
+  return {
+    id: layer.id || layer.layerKey || null,
+    name: layer.name || layer.label || layer.id || layer.layerKey || null,
+    enabled,
+    feedState,
+    source,
+    count,
+    lastUpdate,
+    ageSec: snapshotAgeSec(lastUpdate, now),
+    ageLabel: snapshotAgeLabel(lastUpdate, now),
+    error: snapshotError(stats),
+  };
+}
+
+/**
+ * Snapshot every layer in a roster.
+ * @param {Array<object>} [layers]
+ * @param {{ now?: number }} [options]
+ * @returns {Array<object>}
+ */
+export function layerSnapshots(layers = [], options) {
+  if (!Array.isArray(layers)) return [];
+  return layers.map((layer) => layerSnapshot(layer, options));
+}
+
+function asSnapshot(entry, now) {
+  if (!entry || typeof entry !== 'object') return layerSnapshot({}, { now });
+  if (typeof entry.feedState === 'string') return entry;
+  return layerSnapshot(entry, { now });
+}
+
+/**
+ * Mechanical narration note so the model does not have to infer honesty.
+ * @param {Array<object>} layers Snapshots.
+ * @param {string|null} overall Worst considered feed-state.
+ * @returns {string}
+ */
+export function feedProvenanceNote(layers = [], overall = null) {
+  if (!overall) {
+    return 'No layer snapshot is attached. Do not invent a feed-state or a count.';
+  }
+  if (overall === 'nominal') {
+    return 'Queried enabled layers are nominal. Still name the count scope; do not claim whole-world coverage.';
+  }
+  if (overall === 'off') {
+    const names =
+      layers
+        .map((s) => s.name || s.id)
+        .filter(Boolean)
+        .join(', ') || 'the requested layer';
+    return `${names} is off. Do not invent a count; say the layer is off and offer to enable it.`;
+  }
+  const flagged = layers.filter(
+    (s) => s.feedState && s.feedState !== 'nominal' && s.feedState !== 'off',
+  );
+  const bits = flagged.map((s) => {
+    const extras = [
+      s.source,
+      s.ageLabel || snapshotAgeLabel(s.lastUpdate),
+      s.error,
+    ]
+      .filter(Boolean)
+      .join(', ');
+    return `${s.name || s.id} is ${String(s.feedState).toUpperCase()}${extras ? ` (${extras})` : ''}`;
+  });
+  const body = bits.join('; ') || `${String(overall).toUpperCase()} feed`;
+  return `${body}. Narrate that provenance with any count; do not describe this as live.`;
+}
+
+/**
+ * Shared envelope stamped onto analyst, view-state, and HUD payloads.
+ * @param {Array<object>} [snapshots] Snapshots or raw `getAll()` rows.
+ * @param {{ now?: number }} [options]
+ * @returns {{ overall: string|null, layers: Array<object>, note: string }}
+ */
+export function feedProvenanceEnvelope(
+  snapshots = [],
+  { now = Date.now() } = {},
+) {
+  const layers = (Array.isArray(snapshots) ? snapshots : []).map((entry) =>
+    asSnapshot(entry, now),
+  );
+  const active = layers.filter((s) => s.feedState && s.feedState !== 'off');
+  const overall =
+    worstFeedState(active.map((s) => s.feedState)) ||
+    (layers.length ? 'off' : null);
+  return {
+    overall,
+    layers,
+    note: feedProvenanceNote(layers, overall),
+  };
+}
+
+/**
+ * Compact voice-tool layer row: identity + the fields a model must read.
+ * @param {object} layer Raw `getAll()` row or snapshot.
+ * @param {{ now?: number }} [options]
+ * @returns {object}
+ */
+export function viewStateLayerRow(layer, options) {
+  const snap = layerSnapshot(layer, options);
+  return {
+    id: snap.id,
+    name: snap.name,
+    enabled: snap.enabled,
+    count: snap.count,
+    error: snap.error,
+    feedState: snap.feedState,
+    source: snap.source,
+    lastUpdate: snap.lastUpdate,
+  };
+}

src/data/layerSnapshot.test.mjs

@@ -0,0 +1,260 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import {
+  FEED_STATE_SEVERITY,
+  LAYER_FEED_STATE_LABELS,
+  LAYER_FEED_STATES,
+  SNAPSHOT_FEED_STATES,
+  feedProvenanceEnvelope,
+  feedProvenanceNote,
+  layerFeedState,
+  layerSnapshot,
+  layerSnapshots,
+  snapshotAgeLabel,
+  snapshotAgeSec,
+  viewStateLayerRow,
+  worstFeedState,
+} from './layerSnapshot.js';
+
+const NOW = 1_700_000_000_000;
+
+test('layerSnapshot stays Cesium-free so the HUD proxy can import it', () => {
+  const src = readFileSync(
+    new URL('./layerSnapshot.js', import.meta.url),
+    'utf8',
+  );
+  assert.equal(src.includes("from './manager.js'"), false);
+  assert.doesNotMatch(src, /from ['"]cesium['"]/i);
+});
+
+test('layerFeedState matches the chip classifier for every honesty class', () => {
+  assert.equal(
+    layerFeedState({ error: 'feed down', count: 0, lastUpdate: null }),
+    'unavailable',
+  );
+  assert.equal(
+    layerFeedState({
+      status: 'unavailable',
+      error: 'feed down',
+      count: 50,
+      lastUpdate: 1,
+    }),
+    'unavailable',
+  );
+  assert.equal(
+    layerFeedState({ mode: 'sim', count: 100, lastUpdate: 1 }),
+    'fallback',
+  );
+  assert.equal(
+    layerFeedState({ source: 'adsb.lol', count: 10, lastUpdate: 1 }),
+    'fallback',
+  );
+  assert.equal(
+    layerFeedState({
+      source: 'adsb.lol',
+      fallback: false,
+      count: 10,
+      lastUpdate: 1,
+    }),
+    'nominal',
+  );
+  assert.equal(
+    layerFeedState({ stale: true, count: 0, lastUpdate: 1 }),
+    'stale',
+  );
+  assert.equal(
+    layerFeedState({
+      error: 'partial group failure',
+      count: 50,
+      lastUpdate: 1,
+    }),
+    'degraded',
+  );
+  assert.equal(layerFeedState({ loading: true }), 'loading');
+  assert.equal(layerFeedState({ count: 5, lastUpdate: 1 }), 'nominal');
+  assert.equal(
+    layerFeedState({
+      status: 'zoom-in',
+      error: 'zoom in to search',
+      count: 12,
+    }),
+    'nominal',
+  );
+  assert.equal(
+    layerFeedState({ status: 'zoom-in', stale: true, count: 12 }),
+    'stale',
+  );
+});
+
+test('chip labels and severity cover every feed-state the envelope can emit', () => {
+  assert.deepEqual(
+    [...LAYER_FEED_STATES],
+    ['nominal', 'loading', 'degraded', 'stale', 'fallback', 'unavailable'],
+  );
+  assert.deepEqual([...SNAPSHOT_FEED_STATES], [...LAYER_FEED_STATES, 'off']);
+  for (const state of LAYER_FEED_STATES) {
+    assert.equal(typeof LAYER_FEED_STATE_LABELS[state], 'string');
+    assert.equal(typeof FEED_STATE_SEVERITY[state], 'number');
+  }
+  assert.equal(
+    FEED_STATE_SEVERITY.unavailable < FEED_STATE_SEVERITY.stale,
+    true,
+  );
+  assert.equal(FEED_STATE_SEVERITY.stale < FEED_STATE_SEVERITY.fallback, true);
+  assert.equal(worstFeedState(['nominal', 'stale', 'fallback']), 'stale');
+  assert.equal(worstFeedState(['degraded', 'unavailable']), 'unavailable');
+  assert.equal(worstFeedState([]), null);
+});
+
+test('a disabled layer is off even when leftover stats would read stale', () => {
+  const snap = layerSnapshot(
+    {
+      id: 'flights',
+      name: 'Live Flights',
+      enabled: false,
+      source: 'OpenSky Network',
+      stats: {
+        stale: true,
+        count: 12,
+        lastUpdate: NOW - 240_000,
+        source: 'OpenSky Network',
+      },
+    },
+    { now: NOW },
+  );
+  assert.equal(snap.feedState, 'off');
+  assert.equal(snap.enabled, false);
+  assert.equal(snap.count, 12);
+  assert.equal(snap.ageLabel, '4m ago');
+});
+
+test('an enabled stale layer carries age, source, and a mechanical note', () => {
+  const snap = layerSnapshot(
+    {
+      id: 'flights',
+      name: 'Live Flights',
+      enabled: true,
+      stats: {
+        stale: true,
+        count: 12,
+        lastUpdate: NOW - 240_000,
+        source: 'OpenSky Network',
+      },
+    },
+    { now: NOW },
+  );
+  assert.equal(snap.feedState, 'stale');
+  assert.equal(snap.source, 'OpenSky Network');
+  assert.equal(snap.ageSec, 240);
+  assert.equal(snap.ageLabel, '4m ago');
+  const envelope = feedProvenanceEnvelope([snap], { now: NOW });
+  assert.equal(envelope.overall, 'stale');
+  assert.match(envelope.note, /Live Flights is STALE/);
+  assert.match(envelope.note, /OpenSky Network/);
+  assert.match(envelope.note, /4m ago/);
+  assert.match(envelope.note, /do not describe this as live/i);
+});
+
+test('degraded and unavailable envelopes outrank leftover nominal neighbours', () => {
+  const layers = layerSnapshots(
+    [
+      {
+        id: 'earthquakes',
+        name: 'Earthquakes',
+        enabled: true,
+        stats: { count: 3, lastUpdate: NOW - 10_000 },
+      },
+      {
+        id: 'local-firms',
+        name: 'Active Fires',
+        enabled: true,
+        stats: {
+          error: 'FIRMS key missing',
+          count: 8,
+          lastUpdate: NOW - 30_000,
+        },
+      },
+    ],
+    { now: NOW },
+  );
+  const envelope = feedProvenanceEnvelope(layers, { now: NOW });
+  assert.equal(envelope.overall, 'degraded');
+  assert.match(envelope.note, /Active Fires is DEGRADED/);
+  assert.match(envelope.note, /FIRMS key missing/);
+});
+
+test('an unavailable feed with no prior data does not become a confident zero', () => {
+  const snap = layerSnapshot(
+    {
+      id: 'ais-live-vessels',
+      name: 'Live Vessels',
+      enabled: true,
+      stats: { error: 'AISStream down', count: 0, lastUpdate: null },
+    },
+    { now: NOW },
+  );
+  assert.equal(snap.feedState, 'unavailable');
+  const envelope = feedProvenanceEnvelope([snap]);
+  assert.equal(envelope.overall, 'unavailable');
+  assert.match(envelope.note, /UNAVAILABLE/);
+});
+
+test('fallback provenance names the fallback source instead of calling it live', () => {
+  const snap = layerSnapshot(
+    {
+      id: 'flights',
+      name: 'Live Flights',
+      enabled: true,
+      stats: {
+        source: 'adsb.lol fallback',
+        count: 40,
+        lastUpdate: NOW - 8_000,
+      },
+    },
+    { now: NOW },
+  );
+  assert.equal(snap.feedState, 'fallback');
+  assert.match(feedProvenanceNote([snap], 'fallback'), /adsb\.lol fallback/);
+});
+
+test('view-state rows keep the existing identity fields and add feedState', () => {
+  const row = viewStateLayerRow(
+    {
+      id: 'flights',
+      name: 'Live Flights',
+      enabled: true,
+      stats: {
+        count: 9,
+        lastUpdate: 42,
+        error: null,
+        source: 'OpenSky Network',
+      },
+    },
+    { now: NOW },
+  );
+  assert.deepEqual(row, {
+    id: 'flights',
+    name: 'Live Flights',
+    enabled: true,
+    count: 9,
+    error: null,
+    feedState: 'nominal',
+    source: 'OpenSky Network',
+    lastUpdate: 42,
+  });
+});
+
+test('empty roster envelope does not pretend to be nominal', () => {
+  const envelope = feedProvenanceEnvelope([]);
+  assert.equal(envelope.overall, null);
+  assert.match(envelope.note, /Do not invent/);
+});
+
+test('age labels match the Data Layers meta clock', () => {
+  assert.equal(snapshotAgeSec(null, NOW), null);
+  assert.equal(snapshotAgeLabel(NOW - 3_000, NOW), 'just now');
+  assert.equal(snapshotAgeLabel(NOW - 12_000, NOW), '12s ago');
+  assert.equal(snapshotAgeLabel(NOW - 240_000, NOW), '4m ago');
+  assert.equal(snapshotAgeLabel(NOW - 7_200_000, NOW), '2h ago');
+});

src/data/layerStateCoordinator.js

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

src/data/layerStateTokenLedger.test.mjs

@@ -0,0 +1,435 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import {
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import test from 'node:test';
+import {
+  LEGACY_LAYER_STATE_TOKENS,
+  LAYER_STATE_TOKEN_ALPHABET,
+  LAYER_STATE_TOKEN_RESERVATIONS,
+  nextLayerStateToken,
+  parseLayerStateTokenReservations,
+  validateLayerStateAllocations,
+} from './layerState.js';
+import {
+  PRE_LEDGER_LAYER_STATE_TOKENS,
+  checkLayerStateTokens,
+  readPublishedLayerStateReservations,
+} from '../../scripts/check-layer-state-tokens.mjs';
+
+const LEDGER_PATH = 'src/data/layerStateTokenReservations.json';
+const SOURCE_PATH = 'src/data/layerState.js';
+const CODEC_SOURCE_PATH = fileURLToPath(
+  new URL('./layerState.js', import.meta.url),
+);
+const CHECKER_PATH = fileURLToPath(
+  new URL('../../scripts/check-layer-state-tokens.mjs', import.meta.url),
+);
+const NEXT_PATH = fileURLToPath(
+  new URL('../../scripts/next-layer-state-token.mjs', import.meta.url),
+);
+const reservationRows = JSON.parse(
+  readFileSync(
+    new URL('./layerStateTokenReservations.json', import.meta.url),
+    'utf8',
+  ),
+);
+
+test('pre-ledger published ownership is independent of the candidate mapping', () => {
+  assert.notStrictEqual(
+    PRE_LEDGER_LAYER_STATE_TOKENS,
+    LEGACY_LAYER_STATE_TOKENS,
+  );
+  assert.deepEqual(PRE_LEDGER_LAYER_STATE_TOKENS, LEGACY_LAYER_STATE_TOKENS);
+  assert.equal(Object.keys(PRE_LEDGER_LAYER_STATE_TOKENS).length, 28);
+  assert.equal(PRE_LEDGER_LAYER_STATE_TOKENS['recent-imagery'], '1');
+  assert.equal(PRE_LEDGER_LAYER_STATE_TOKENS['fire-perimeters'], '2');
+  assert.throws(
+    () =>
+      validateLayerStateAllocations(PRE_LEDGER_LAYER_STATE_TOKENS, {
+        ...LAYER_STATE_TOKEN_RESERVATIONS,
+        flights: '00',
+      }),
+    /Published layer-state token changed or removed: flights/,
+  );
+});
+
+function git(cwd, ...args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+}
+
+function withPublishedBase(
+  { rows, source = 'export const changed = true;\n' },
+  check,
+) {
+  const cwd = mkdtempSync(path.join(tmpdir(), 'gev-layer-token-ledger-'));
+  try {
+    git(cwd, 'init', '-q');
+    mkdirSync(path.join(cwd, 'src/data'), { recursive: true });
+    writeFileSync(path.join(cwd, SOURCE_PATH), source);
+    if (rows !== undefined) {
+      writeFileSync(path.join(cwd, LEDGER_PATH), JSON.stringify(rows));
+    }
+    git(cwd, 'add', 'src/data');
+    git(
+      cwd,
+      '-c',
+      'user.name=Layer Token Test',
+      '-c',
+      '[email protected]',
+      'commit',
+      '-q',
+      '-m',
+      'published base',
+    );
+    check(cwd);
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}
+
+function writeCodecFixture(cwd, rows, entries) {
+  const providerCodec = path.join(cwd, 'src/data/idSwitches.js');
+  mkdirSync(path.dirname(providerCodec), { recursive: true });
+  writeFileSync(
+    providerCodec,
+    readFileSync(new URL('./idSwitches.js', import.meta.url)),
+  );
+  const source = readFileSync(CODEC_SOURCE_PATH, 'utf8');
+  const registryEnd = ']);\n\nexport const REGISTERED_LAYER_IDS';
+  assert.equal(source.split(registryEnd).length, 2);
+  const additions = entries
+    .map(
+      ({ id, token }) =>
+        `  Object.freeze({ id: '${id}', token: '${token}', disposition: 'enabled-only' }),`,
+    )
+    .join('\n');
+  mkdirSync(path.join(cwd, 'src/data'), { recursive: true });
+  writeFileSync(path.join(cwd, 'package.json'), '{"type":"module"}');
+  writeFileSync(
+    path.join(cwd, SOURCE_PATH),
+    source.replace(registryEnd, `${additions}\n${registryEnd}`),
+  );
+  writeFileSync(path.join(cwd, LEDGER_PATH), JSON.stringify(rows));
+  return path.join(cwd, SOURCE_PATH);
+}
+
+test('reservation ledger is complete, pinned, and rejects duplicate or malformed rows', () => {
+  assert.deepEqual(
+    { ...parseLayerStateTokenReservations(reservationRows) },
+    { ...LAYER_STATE_TOKEN_RESERVATIONS },
+  );
+  assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 31);
+  assert.deepEqual(
+    { ...LAYER_STATE_TOKEN_RESERVATIONS },
+    {
+      ...LEGACY_LAYER_STATE_TOKENS,
+      'street-level': '0',
+      'gnss-integrity': '3',
+      'air-quality': '4',
+    },
+  );
+  assert.throws(
+    () =>
+      parseLayerStateTokenReservations(
+        // Drop a legacy row by id; the first row sorts as air-quality, which
+        // is not a legacy reservation.
+        reservationRows.filter(([id]) => id !== 'ais-live-vessels'),
+      ),
+    /Missing or changed legacy/,
+  );
+  assert.throws(
+    () =>
+      parseLayerStateTokenReservations([
+        ...reservationRows,
+        reservationRows[0],
+      ]),
+    /Duplicate layer-state token reservation id/,
+  );
+  assert.throws(
+    () =>
+      parseLayerStateTokenReservations([...reservationRows, ['future', 'a']]),
+    /Duplicate layer-state token reservation/,
+  );
+  assert.equal(
+    parseLayerStateTokenReservations([...reservationRows, ['future', '5']])
+      .future,
+    '5',
+  );
+  assert.throws(
+    () =>
+      parseLayerStateTokenReservations([
+        ...reservationRows.filter(([id]) => id !== 'transit'),
+        ['future', 'j'],
+      ]),
+    /Legacy layer-state token is immutable/,
+  );
+  assert.throws(
+    () => parseLayerStateTokenReservations([...reservationRows, ['future']]),
+    /Invalid layer-state token ledger row/,
+  );
+});
+
+test('published retired digits and competing PRs advance the merge-time allocation', () => {
+  withPublishedBase(
+    { rows: [...reservationRows, ['retired-layer', '5']] },
+    (cwd) => {
+      const published = readPublishedLayerStateReservations('HEAD', cwd);
+      assert.equal(nextLayerStateToken(published), '6');
+      assert.equal(
+        validateLayerStateAllocations(published, {
+          ...published,
+          newcomer: '6',
+        }),
+        true,
+      );
+      assert.throws(
+        () =>
+          validateLayerStateAllocations(published, {
+            ...published,
+            competing: '5',
+          }),
+        /next free token 6/,
+      );
+      assert.throws(
+        () =>
+          validateLayerStateAllocations(published, {
+            ...LAYER_STATE_TOKEN_RESERVATIONS,
+            newcomer: '5',
+          }),
+        /changed or removed: retired-layer/,
+      );
+    },
+  );
+});
+
+test('PR B manually replaces provisional 5 with 6 after PR A publishes 5', () => {
+  withPublishedBase({ rows: [...reservationRows, ['pr-a', '5']] }, (cwd) => {
+    mkdirSync(path.join(cwd, 'scripts'));
+    const fixtureChecker = path.join(
+      cwd,
+      'scripts/check-layer-state-tokens.mjs',
+    );
+    writeFileSync(fixtureChecker, readFileSync(CHECKER_PATH, 'utf8'));
+    const fixtureNext = path.join(cwd, 'scripts/next-layer-state-token.mjs');
+    writeFileSync(fixtureNext, readFileSync(NEXT_PATH, 'utf8'));
+    const runCheck = () =>
+      spawnSync(
+        process.execPath,
+        [realpathSync(fixtureChecker), '--base-ref', 'HEAD'],
+        {
+          cwd,
+          encoding: 'utf8',
+        },
+      );
+
+    writeCodecFixture(
+      cwd,
+      [...reservationRows, ['pr-b', '5']],
+      [{ id: 'pr-b', token: '5' }],
+    );
+    const beforeRebase = runCheck();
+    assert.equal(beforeRebase.status, 1);
+    assert.match(beforeRebase.stderr, /changed or removed: pr-a/);
+
+    writeCodecFixture(
+      cwd,
+      [...reservationRows, ['pr-a', '5'], ['pr-b', '5']],
+      [
+        { id: 'pr-a', token: '5' },
+        { id: 'pr-b', token: '5' },
+      ],
+    );
+    const staleRebase = runCheck();
+    assert.equal(staleRebase.status, 1);
+    assert.match(staleRebase.stderr, /Duplicate layer-state token reservation/);
+
+    const published = readPublishedLayerStateReservations('HEAD', cwd);
+    assert.equal(nextLayerStateToken(published), '6');
+    const validBaselineRows = [...reservationRows, ['pr-a', '5']];
+    writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '5' }]);
+    const helper = spawnSync(
+      process.execPath,
+      [realpathSync(fixtureNext), 'pr-b'],
+      { cwd, encoding: 'utf8' },
+    );
+    assert.equal(helper.status, 0, helper.stderr);
+    assert.match(helper.stdout, /pr-b: 6/);
+    assert.deepEqual(
+      JSON.parse(readFileSync(path.join(cwd, LEDGER_PATH), 'utf8')),
+      validBaselineRows,
+      'the helper reports a token without rewriting the ledger',
+    );
+    writeCodecFixture(
+      cwd,
+      [...reservationRows, ['pr-a', '5'], ['pr-b', '6']],
+      [
+        { id: 'pr-a', token: '5' },
+        { id: 'pr-b', token: '6' },
+      ],
+    );
+    const corrected = runCheck();
+    assert.equal(corrected.status, 0, corrected.stderr);
+    assert.match(corrected.stdout, /32 published, 1 new/);
+  });
+});
+
+test('allocation batches cross the last digit and base-36 pair boundaries in order', () => {
+  const digitRows = [...'56789'].map((digit) => [`retired-${digit}`, digit]);
+  const allDigits = parseLayerStateTokenReservations([
+    ...reservationRows,
+    ...digitRows,
+  ]);
+  const beforeNine = { ...allDigits };
+  delete beforeNine['retired-9'];
+  assert.equal(
+    validateLayerStateAllocations(beforeNine, {
+      ...beforeNine,
+      pair: '00',
+      lastDigit: '9',
+    }),
+    true,
+  );
+  const baseBefore0a = {
+    ...allDigits,
+    ...Object.fromEntries(
+      [...'012345678'].map((second) => [`retired-0${second}`, `0${second}`]),
+    ),
+  };
+  assert.equal(nextLayerStateToken(baseBefore0a), '09');
+  assert.equal(
+    validateLayerStateAllocations(baseBefore0a, {
+      ...baseBefore0a,
+      after: '0a',
+      before: '09',
+    }),
+    true,
+  );
+  const baseBefore10 = {
+    ...allDigits,
+    ...Object.fromEntries(
+      [...LAYER_STATE_TOKEN_ALPHABET]
+        .slice(0, -1)
+        .map((second) => [`retired-0${second}`, `0${second}`]),
+    ),
+  };
+  assert.equal(nextLayerStateToken(baseBefore10), '0z');
+  assert.equal(
+    validateLayerStateAllocations(baseBefore10, {
+      ...baseBefore10,
+      after: '10',
+      before: '0z',
+    }),
+    true,
+  );
+});
+
+test('an isolated valid two-character fixture round-trips an l field beyond the old 64-character cap', async () => {
+  const cwd = mkdtempSync(path.join(tmpdir(), 'gev-layer-token-width-'));
+  try {
+    const priorDigits = [...'56789'].map((digit) => [
+      `qa-prior-digit-${digit}`,
+      digit,
+    ]);
+    const fixtureLayers = ['00', '01', '02', '03'].map((token) => ({
+      id: `qa-layer-${token}`,
+      token,
+    }));
+    const fixtureRows = [
+      ...reservationRows,
+      ...priorDigits,
+      ...fixtureLayers.map(({ id, token }) => [id, token]),
+    ];
+    const fixtureModule = writeCodecFixture(cwd, fixtureRows, fixtureLayers);
+    const codec = await import(pathToFileURL(fixtureModule));
+    assert.equal(codec.validateLayerStateRegistry(), true);
+    assert.equal(
+      nextLayerStateToken(
+        parseLayerStateTokenReservations([...reservationRows, ...priorDigits]),
+      ),
+      '00',
+    );
+    assert.equal(
+      validateLayerStateAllocations(
+        LAYER_STATE_TOKEN_RESERVATIONS,
+        codec.LAYER_STATE_TOKEN_RESERVATIONS,
+      ),
+      true,
+    );
+
+    const expectedLayerIds = codec.REGISTERED_LAYER_IDS;
+    const state = codec.normalizeLayerState({
+      enabledLayerIds: expectedLayerIds,
+    });
+    const params = new URLSearchParams([['v', '2']]);
+    codec.encodeLayerStateParams(params, state);
+    assert.ok(params.get('l').length > 64, 'fixture must cross the old cap');
+    assert.equal(params.get('l').length, 73);
+    const restored = codec.decodeLayerStateParams(params);
+    assert.deepEqual(restored?.enabledLayerIds, expectedLayerIds);
+    assert.deepEqual(restored?.options, state.options);
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('checker reads a complete future base ledger and rejects retired-token reuse', () => {
+  withPublishedBase(
+    {
+      rows: [...reservationRows, ['retired-layer', '00']],
+      source:
+        'export const LAYER_STATE_TOKEN_RESERVATIONS = Object.freeze({ ["retired-layer"]: "00" });\n',
+    },
+    (cwd) => {
+      const published = readPublishedLayerStateReservations('HEAD', cwd);
+      assert.equal(Object.keys(published).length, 32);
+      assert.equal(published['retired-layer'], '00');
+      assert.throws(
+        () =>
+          validateLayerStateAllocations(published, {
+            ...LAYER_STATE_TOKEN_RESERVATIONS,
+            newcomer: '00',
+          }),
+        /changed or removed/,
+      );
+      assert.throws(
+        () => checkLayerStateTokens('HEAD', cwd),
+        /changed or removed/,
+      );
+      const cli = spawnSync(
+        process.execPath,
+        [CHECKER_PATH, '--base-ref', 'HEAD'],
+        {
+          cwd,
+          encoding: 'utf8',
+        },
+      );
+      assert.equal(cli.status, 1);
+      assert.match(cli.stderr, /changed or removed/);
+    },
+  );
+});
+
+test('checker fails closed on unknown or malformed published ledgers', () => {
+  withPublishedBase({}, (cwd) => {
+    assert.throws(
+      () => readPublishedLayerStateReservations('HEAD', cwd),
+      /no recognizable layer-state token ledger/,
+    );
+  });
+  withPublishedBase({ rows: [...reservationRows, ['future', 'a']] }, (cwd) => {
+    assert.throws(
+      () => readPublishedLayerStateReservations('HEAD', cwd),
+      /Duplicate layer-state token reservation/,
+    );
+  });
+});

src/data/layerStateTokenReservations.json

@@ -0,0 +1,33 @@
+[
+  ["air-quality", "4"],
+  ["ais-live-vessels", "a"],
+  ["alpr-cameras", "p"],
+  ["bhote-koshi-2026", "h"],
+  ["bhote-koshi-locator", "z"],
+  ["bikeshare", "b"],
+  ["cctv", "c"],
+  ["directions", "n"],
+  ["earthquakes", "e"],
+  ["fire-perimeters", "2"],
+  ["flights", "f"],
+  ["gnss-integrity", "3"],
+  ["local-dams", "q"],
+  ["local-datacenters", "d"],
+  ["local-firms", "w"],
+  ["military", "m"],
+  ["military-awareness", "g"],
+  ["military-installations", "i"],
+  ["radio", "r"],
+  ["recent-imagery", "1"],
+  ["rocket-launches", "x"],
+  ["satellites", "s"],
+  ["street-level", "0"],
+  ["telegeography-submarine-cables", "u"],
+  ["traffic", "t"],
+  ["transit", "j"],
+  ["weather-cyclones", "y"],
+  ["weather-lightning", "l"],
+  ["weather-radar", "v"],
+  ["weather-satellite", "o"],
+  ["wind", "k"]
+]

src/data/lifecycle.js

@@ -1,3 +1,5 @@
+import { cancelCameraArrival } from './cameraArrival.js';
+
 function cloneLayerParams(value) {
   if (Array.isArray(value)) return value.map(cloneLayerParams);
   if (value && typeof value === 'object') {
@@ -16,6 +18,8 @@ const VALID_LAYER_SERIALIZATION_DISPOSITIONS = new Set([
   'enabled-only',
   'enabled+options',
   'enabled+mirrored-options',
+  // Registered but never serialized (for example hardware-local layers).
+  'local-only',
 ]);
 
 function isAbortError(error) {
@@ -70,7 +74,11 @@ function refreshFailureFromStats(stats, label) {
  * for real-time data overlays on the CesiumJS globe.
  */
 export class LayerLifecycle {
-  constructor(viewer, { allowQaRegistration = false } = {}) {
+  constructor(
+    viewer,
+    { allowQaRegistration = false, getSourceAvailability } = {},
+  ) {
+    this._catalogSourceAvailability = getSourceAvailability;
     this.viewer = viewer;
     this._activityListeners = new Set();
     this.layers = new Map(); // id → { module, enabled, initialized, intervalId, lifecycleState, lifecycleUncertain }
@@ -224,6 +232,7 @@ export class LayerLifecycle {
 
   _normalizedStats(entry) {
     const moduleStats = this._moduleStats(entry);
+    const availability = this._sourceAvailability(entry.module.id);
     const lifecycleLoading =
       entry.lifecycleState === 'enabling' ||
       entry.lifecycleState === 'disabling';
@@ -231,6 +240,13 @@ export class LayerLifecycle {
       count: 0,
       lastUpdate: null,
       ...moduleStats,
+      ...(availability?.available === false
+        ? {
+            status: 'unavailable',
+            sourceUnavailable: true,
+            error: availability.reason,
+          }
+        : {}),
       loading: lifecycleLoading || moduleStats.loading === true,
       refreshing: entry.refreshing || moduleStats.refreshing === true,
       managerRefreshError: entry.managerRefreshError,
@@ -1072,6 +1088,7 @@ export class LayerLifecycle {
     const entry = this.layers.get(layerId);
     if (!entry) return { intentEpoch: null, promise: Promise.resolve() };
     const desiredState = Boolean(shouldEnable);
+    if (!desiredState) cancelCameraArrival(this.viewer);
     if (entry.destroying) {
       return {
         intentEpoch: null,
@@ -2093,6 +2110,7 @@ export class LayerLifecycle {
   async destroyLayer(layerId) {
     const entry = this.layers.get(layerId);
     if (!entry || entry.destroying) return false;
+    cancelCameraArrival(this.viewer);
     entry.destroying = true;
     this._invalidateRefresh(layerId, entry, 'layer-destroyed');
     // Teardown becomes authoritative before the first await. Advancing the
@@ -2276,7 +2294,17 @@ export class LayerLifecycle {
     }
   }
 
+  _sourceAvailability(layerId) {
+    return (
+      this._catalogSourceAvailability?.(layerId) ??
+      this.layers.get(layerId)?.module.getSourceAvailability?.()
+    );
+  }
+
   async _visibilityBlockReason(change) {
+    const availability = this._sourceAvailability(change.layerId);
+    if (change.enabled && availability?.available === false)
+      return availability.reason || 'Data source unavailable';
     for (const callback of this._visibilityGuards) {
       try {
         const result = await callback(change);
@@ -2302,6 +2330,14 @@ export class LayerLifecycle {
     return () => this._activityListeners.delete(callback);
   }
 
+  /**
+   * Ask presentation to repaint layer rows now, for data that lands outside
+   * the manager tick (Transit's proximity polls, Directions' route steps).
+   */
+  refreshLayerStats() {
+    this._publishActivity({ type: 'status' });
+  }
+
   _publishActivity(change) {
     for (const callback of this._activityListeners) {
       try {

src/data/localGeojson.analyst.test.mjs

@@ -0,0 +1,222 @@
+// Focused tests for the local-infrastructure analyst-record mapper and snapshot seam.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { createLocalGeoJsonLayer, mapAnalystRecord } from './localGeojson.js';
+
+const DC_RAW = {
+  id: '1176042553',
+  lat: -52.942,
+  lon: -70.85,
+  properties: {
+    tags: {
+      name: 'AWS',
+      operator: 'Amazon Web Services',
+      'operator:short': 'AWS',
+      'capacity:it_load': '27 MW',
+    },
+  },
+};
+
+const DAM_RAW = {
+  id: '-19685440',
+  lat: -25.41,
+  lon: -54.59,
+  properties: {
+    name: 'Usina Hidrelétrica de Itaipu',
+    output: '14000 MW',
+    tags: {
+      name: 'Usina Hidrelétrica de Itaipu',
+      'name:en': 'Itaipu Dam',
+      operator: 'Itaipú Binacional',
+      associated_river: 'Paraná',
+      'plant:output:electricity': '14000 MW',
+    },
+  },
+};
+
+test('infra analyst record: datacenter maps name, operator, capacity', () => {
+  const r = mapAnalystRecord(DC_RAW, 'local-datacenters');
+  assert.deepEqual(r, {
+    id: 'AWS',
+    name: 'AWS',
+    lat: -52.942,
+    lon: -70.85,
+    operator: 'Amazon Web Services',
+    capacity: '27 MW',
+    river: null,
+    output: null,
+  });
+});
+
+test('infra analyst record: dam maps name, operator, river, output; names stay unclamped', () => {
+  const r = mapAnalystRecord(DAM_RAW, 'local-dams');
+  assert.equal(r.id, 'Usina Hidrelétrica de Itaipu');
+  assert.equal(r.name, 'Usina Hidrelétrica de Itaipu');
+  assert.equal(r.operator, 'Itaipú Binacional');
+  assert.equal(r.river, 'Paraná');
+  assert.equal(r.output, '14000 MW');
+  assert.equal(r.capacity, null);
+});
+
+test('infra analyst record: unnamed feature falls back to source id', () => {
+  const r = mapAnalystRecord(
+    {
+      id: 'dc-42',
+      lat: 30.2,
+      lon: -97.7,
+      properties: { tags: { operator: 'Example Cloud' } },
+    },
+    'local-datacenters',
+  );
+  assert.equal(r.id, 'dc-42');
+  assert.equal(r.name, null);
+  assert.equal(r.operator, 'Example Cloud');
+});
+
+test('infra analyst record: empty record yields nulls, never NaN/undefined', () => {
+  const r = mapAnalystRecord(undefined, 'local-dams');
+  assert.equal(r.id, 'Dam');
+  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`);
+  }
+});
+
+test('infra analyst record: output is JSON-safe (no Cesium types leak)', () => {
+  const r = mapAnalystRecord(
+    {
+      ...DAM_RAW,
+      entity: {},
+      position: { x: 1 },
+    },
+    'local-dams',
+  );
+  assert.deepEqual(JSON.parse(JSON.stringify(r)), r);
+  assert.equal('entity' in r, false);
+  assert.equal('position' in r, false);
+});
+
+class MockLayerEvent {
+  constructor() {
+    this.listeners = new Set();
+  }
+
+  addEventListener(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+}
+
+test('infra getAnalystRecords: enabled layer snapshots loaded stems; disable returns []', async () => {
+  const originalFetch = globalThis.fetch;
+  const originalWindow = globalThis.window;
+  globalThis.window = { dispatchEvent() {} };
+  globalThis.fetch = async () => ({
+    ok: true,
+    status: 200,
+    text: async () =>
+      JSON.stringify({
+        type: 'Feature',
+        id: 'runtime-dam',
+        properties: {
+          name: 'Runtime Dam',
+          output: '12 MW',
+          tags: { associated_river: 'Test River', operator: 'Test Hydro' },
+        },
+        geometry: {
+          type: 'Polygon',
+          coordinates: [
+            [
+              [-97.7, 30.2],
+              [-97.69, 30.2],
+              [-97.69, 30.21],
+              [-97.7, 30.2],
+            ],
+          ],
+        },
+      }),
+  });
+  const viewer = {
+    selectedEntity: undefined,
+    dataSources: {
+      add(dataSource) {
+        return dataSource;
+      },
+      remove() {
+        return true;
+      },
+    },
+    camera: {
+      positionWC: Cesium.Cartesian3.fromDegrees(-97.695, 30.205, 100_000),
+      frustum: { fov: Math.PI / 3 },
+      moveEnd: new MockLayerEvent(),
+      flyTo() {},
+    },
+    scene: {
+      canvas: { clientWidth: 800, clientHeight: 600 },
+      preRender: new MockLayerEvent(),
+      sampleHeightSupported: false,
+      sampleHeight() {
+        return undefined;
+      },
+      screenSpaceCameraController: { enableInputs: true },
+      pick() {
+        return null;
+      },
+      requestRender() {},
+    },
+  };
+  const layer = createLocalGeoJsonLayer({
+    id: 'local-dams',
+    url: '/runtime-dam.geojsonl',
+    name: 'Runtime Dams',
+    color: '#0088ff',
+    overlayHost: { setVisible() {}, setEntries() {}, clearSource() {} },
+    projectToWindow: () => ({ x: 400, y: 300 }),
+    screenSpaceEventHandlerFactory: () => ({
+      setInputAction() {},
+      destroy() {},
+    }),
+  });
+  try {
+    assert.deepEqual(
+      layer.getAnalystRecords(),
+      [],
+      'unenabled layer has no analyst records',
+    );
+    await layer.enable(viewer);
+    const rows = layer.getAnalystRecords();
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].id, 'Runtime Dam');
+    assert.equal(rows[0].name, 'Runtime Dam');
+    assert.equal(rows[0].operator, 'Test Hydro');
+    assert.equal(rows[0].river, 'Test River');
+    assert.equal(rows[0].output, '12 MW');
+    assert.ok(Number.isFinite(rows[0].lat) && Number.isFinite(rows[0].lon));
+    assert.deepEqual(JSON.parse(JSON.stringify(rows[0])), rows[0]);
+    assert.equal(
+      layer.getAnalystRecords(0).length,
+      1,
+      'non-finite/zero cap still returns at least one',
+    );
+
+    layer.disable(viewer);
+    assert.deepEqual(
+      layer.getAnalystRecords(),
+      [],
+      'disable keeps stems but analyst snapshot is empty',
+    );
+  } finally {
+    layer.destroy(viewer);
+    assert.deepEqual(
+      layer.getAnalystRecords(),
+      [],
+      'destroy releases analyst records',
+    );
+    globalThis.fetch = originalFetch;
+    if (originalWindow === undefined) delete globalThis.window;
+    else globalThis.window = originalWindow;
+  }
+});

src/data/localGeojsonCore.js

@@ -1,4 +1,10 @@
 import * as Cesium from 'cesium';
+import {
+  layerTitle,
+  mapAnalystRecord,
+  parseGeojsonLines,
+} from '../sources/infrastructureData.js';
+import { createInfrastructureOverlayEntry } from './infrastructureOverlayEntry.js';
 import { isPointerFree } from './inputOwnership.js';
 import {
   selectInfraLod,
@@ -14,10 +20,6 @@ const VISIBILITY_UPDATE_MS = 450;
 export const LOCAL_OVERLAY_COHORT_LIMIT = 160;
 const LOCAL_OVERLAY_COLLISION_CAPACITY = 96;
 const LOCAL_OVERLAY_CELL_SURPLUS = 2;
-const LOCAL_OVERLAY_MAX_DISTANCE_M = 14000000;
-const LOCAL_OVERLAY_FADE_START_M = 250000;
-const LOCAL_OVERLAY_FADE_START_RATIO =
-  LOCAL_OVERLAY_FADE_START_M / LOCAL_OVERLAY_MAX_DISTANCE_M;
 // Stems are anchored at ellipsoid height 0, but high-elevation features
 // (e.g. dams in river canyons) sit hundreds of meters above the ellipsoid,
 // burying the short close-in stem inside the photoreal mesh. Once the
@@ -110,33 +112,15 @@ export function createLocalInfrastructureOverlayEntry({
   accent,
 }) {
   const copy = localInfrastructureOverlayCopy(properties, layerId);
-  return {
-    id: String(id),
+  return createInfrastructureOverlayEntry({
+    id,
     source: layerId,
     position,
-    variant: 'card',
     title: copy.title,
     details: copy.details,
     accent,
     priority,
-    collisionGroup: 'ambient-card',
-    zIndex: 30,
-    interactive: false,
-    minDistance: 0,
-    maxDistance: LOCAL_OVERLAY_MAX_DISTANCE_M,
-    distanceFadeStartRatio: LOCAL_OVERLAY_FADE_START_RATIO,
-    distanceScale: {
-      near: 250000,
-      nearValue: 1,
-      far: 9000000,
-      farValue: 0.62,
-    },
-    edgeFade: 'keyhole',
-    horizonCull: true,
-    terrainOcclusion: false,
-    gapPx: 15,
-    placement: 'above',
-  };
+  });
 }
 
 /**
@@ -310,7 +294,7 @@ export function localDatasetError(error) {
  * standard scene.pick natively clicks them.
  * @param {object} options Dataset URL, identity, appearance and optional Cesium adapters.
  * @param {object} services Caller-owned operations; see docs/INFRASTRUCTURE-LAYERS.md.
- * @returns {object} A fresh layer implementing init/enable/disable/update/destroy/getStats.
+ * @returns {object} A fresh layer implementing init/enable/disable/update/destroy/getStats/getAnalystRecords.
  * One live instance per layer id is allowed in a given viewer/context/overlay host.
  * Destroy the previous instance before replacing it. Importing creates no layers.
  */
@@ -322,6 +306,7 @@ export function createLocalGeoJsonLayer(
     color,
     icon = '📍',
     source = 'Local JSONL',
+    osmDerived = false,
     labels = true,
     labelMax = DEFAULT_LABEL_MAX,
     labelGridPx = DEFAULT_LABEL_GRID_PX,
@@ -337,6 +322,8 @@ export function createLocalGeoJsonLayer(
     clearSelectedEntityContextForLayer,
     removeEntityContextsForLayer,
     governorRequestRender,
+    showOsmCredit,
+    hideOsmCredit,
   },
 ) {
   let _dataSource = null;
@@ -466,6 +453,7 @@ export function createLocalGeoJsonLayer(
   };
 
   const disableLayer = (viewer) => {
+    hideOsmCredit?.(viewer, id);
     _enabled = false;
     clearGroundRetryRender();
     _activeLodIds = new Set();
@@ -530,6 +518,40 @@ export function createLocalGeoJsonLayer(
       computed: _lodComputed,
     }),
 
+    /**
+     * Snapshot in-memory infrastructure features as plain JSON-safe objects
+     * for the analyst query engine. On-demand only (called at most once per
+     * spoken query) — zero per-frame cost, no listeners, no caching. Returns
+     * [] while the layer is disabled or empty. Disable keeps the loaded
+     * stems for reuse; this method still returns [] until the next enable.
+     * @param {number} [maxCount=2000] Maximum records to return (truncation).
+     * @returns {Array<Object>} See mapAnalystRecord for the record shape.
+     */
+    getAnalystRecords(maxCount = 2000) {
+      if (!_enabled || !_stemRecords.length) return [];
+      const limit = Number.isFinite(maxCount)
+        ? Math.max(1, Math.floor(maxCount))
+        : 2000;
+      const result = [];
+      for (let i = 0; i < _stemRecords.length; i++) {
+        if (result.length >= limit) break;
+        const record = _stemRecords[i];
+        const carto = record.carto;
+        result.push(
+          mapAnalystRecord(
+            {
+              id: record.id,
+              lat: carto ? Cesium.Math.toDegrees(carto.latitude) : null,
+              lon: carto ? Cesium.Math.toDegrees(carto.longitude) : null,
+              properties: propertyObject(record.entity),
+            },
+            id,
+          ),
+        );
+      }
+      return result;
+    },
+
     enable: async (viewer) => {
       if (_destroyed) return;
       _enabled = true;
@@ -575,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;
               }
 
@@ -836,6 +854,7 @@ export function createLocalGeoJsonLayer(
       }
 
       if (_destroyed) return;
+      if (_enabled && _count > 0 && osmDerived) showOsmCredit?.(viewer, id);
       // 3. Add an incredibly fast pre-render occluder to hide points behind the globe
       if (_enabled && !_preRenderRemover) {
         _preRenderRemover = viewer.scene.preRender.addEventListener(() => {
@@ -1270,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/localReceiversProxy.test.mjs

@@ -0,0 +1,459 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import {
+  LOCAL_RECEIVERS_ROUTE,
+  createLocalReceiversHandler,
+  localReceiversProxy,
+  parseLocalReceiverFeeds,
+} from '../../server/providers/local-receivers.js';
+import { localProviderPlugins } from '../../server/providers/local.js';
+
+const FIXTURE = readFileSync(
+  new URL('./fixtures/adsb-austin-dump1090-aircraft.json', import.meta.url),
+  'utf8',
+);
+const FIXTURE_NOW_MS = JSON.parse(FIXTURE).now * 1000;
+const FEED_1090 = 'http://localhost:8080/data/aircraft.json';
+const FEED_978 = 'http://127.0.0.1:8978/data/aircraft.json';
+
+function quietLogger() {
+  const lines = [];
+  return {
+    lines,
+    warn: (line) => lines.push(line),
+    info: (line) => lines.push(line),
+  };
+}
+
+function respond(status = 200, body = FIXTURE, headers = {}) {
+  return new Response(body, {
+    status,
+    headers: { 'content-type': 'application/json', ...headers },
+  });
+}
+
+async function call(handler, method = 'GET') {
+  const res = {
+    writeHead(status, headers) {
+      Object.assign(this, { status, headers });
+    },
+    end(body) {
+      this.body = body;
+    },
+  };
+  await handler.handle({ url: '/', method }, res);
+  return { ...res, json: JSON.parse(res.body) };
+}
+
+test('LOCAL_RECEIVER_FEEDS accepts local http(s) aircraft.json feeds per band', () => {
+  const { configured, feeds } = parseLocalReceiverFeeds(
+    ` 1090=${FEED_1090} , 978=http://skyaware.local/skyaware978/data/aircraft.json,1090=https://192.168.1.20:8443/tar1090/data/aircraft.json`,
+  );
+  assert.equal(configured, true);
+  assert.deepEqual(
+    feeds.map(({ band, label, url }) => ({ band, label, url })),
+    [
+      { band: '1090', label: '1090 MHz #1', url: FEED_1090 },
+      {
+        band: '978',
+        label: '978 MHz UAT',
+        url: 'http://skyaware.local:80/skyaware978/data/aircraft.json',
+      },
+      {
+        band: '1090',
+        label: '1090 MHz #2',
+        url: 'https://192.168.1.20:8443/tar1090/data/aircraft.json',
+      },
+    ],
+  );
+  assert.deepEqual(parseLocalReceiverFeeds(undefined), {
+    configured: false,
+    feeds: [],
+  });
+  assert.equal(parseLocalReceiverFeeds(' , ').configured, false);
+});
+
+test('LOCAL_RECEIVER_FEEDS rejects public, link-local and named hosts, bad paths and bands', () => {
+  const cases = {
+    '1090=http://8.8.8.8/data/aircraft.json': 'host must be',
+    '1090=http://169.254.169.254/latest/aircraft.json': 'host must be',
+    '1090=http://example.com/data/aircraft.json': 'host must be',
+    '1090=http://[::1]:8080/data/aircraft.json': 'host must be',
+    '1090=http://localhost:8080/data/receiver.json': 'path must end',
+    '1090=http://localhost:8080/data/aircraft.json.bak': 'path must end',
+    '1090=http://localhost:8080/data/aircraft.json?x=1': 'query',
+    '1090=http://user:pw@localhost:8080/data/aircraft.json': 'credentials',
+    '1090=ftp://localhost/data/aircraft.json': 'scheme',
+    '1090=not a url': 'not a valid URL',
+    '868=http://localhost:8080/data/aircraft.json': 'band must be',
+    'http://localhost:8080/data/aircraft.json': 'expected band=url',
+  };
+  for (const [entry, reason] of Object.entries(cases)) {
+    const [feed] = parseLocalReceiverFeeds(entry).feeds;
+    assert.equal(feed.url, undefined, `${entry} must not be fetchable`);
+    assert.match(feed.reason, new RegExp(reason), entry);
+  }
+  const [badBand] = parseLocalReceiverFeeds(
+    '868=http://localhost/aircraft.json',
+  ).feeds;
+  assert.equal(badBand.band, null);
+  assert.equal(badBand.label, 'entry 1');
+});
+
+test('an unconfigured route answers 200 without fetching anything', async (t) => {
+  t.mock.method(globalThis, 'fetch', () => {
+    throw Error('must not fetch');
+  });
+  const handler = createLocalReceiversHandler({
+    feedsValue: undefined,
+    logger: quietLogger(),
+  });
+  const res = await call(handler);
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.json, { configured: false, feeds: [], records: [] });
+});
+
+test('construction mounts the route once and neither parses nor fetches', (t) => {
+  t.mock.method(globalThis, 'fetch', () => {
+    throw Error('construction must not fetch');
+  });
+  const plugins = localProviderPlugins();
+  assert.equal(
+    plugins.filter((plugin) => plugin.name === 'local-receivers-proxy').length,
+    1,
+  );
+  const routes = [];
+  localReceiversProxy({
+    feedsValue: '',
+    logger: quietLogger(),
+  }).configureServer({ middlewares: { use: (route) => routes.push(route) } });
+  assert.deepEqual(routes, [LOCAL_RECEIVERS_ROUTE]);
+});
+
+test('live feeds are read in parallel and labelled with their band', async () => {
+  const calls = [];
+  const handler = createLocalReceiversHandler({
+    feedsValue: `1090=${FEED_1090},978=${FEED_978}`,
+    now: () => FIXTURE_NOW_MS + 2_000,
+    logger: quietLogger(),
+    fetchImpl: async (url, options) => {
+      calls.push({ url, redirect: options.redirect });
+      return respond();
+    },
+  });
+  const { status, json } = await call(handler);
+  assert.equal(status, 200);
+  assert.deepEqual(
+    calls.sort((a, b) => (a.url < b.url ? 1 : -1)),
+    [
+      { url: FEED_1090, redirect: 'manual' },
+      { url: FEED_978, redirect: 'manual' },
+    ],
+  );
+  assert.equal(json.configured, true);
+  assert.deepEqual(json.feeds, [
+    {
+      band: '1090',
+      label: '1090 MHz',
+      status: 'live',
+      aircraft: 4,
+      ageMs: 2_000,
+    },
+    {
+      band: '978',
+      label: '978 MHz UAT',
+      status: 'live',
+      aircraft: 4,
+      ageMs: 2_000,
+    },
+  ]);
+  assert.equal(json.records.length, 8);
+  const shinr = json.records.filter((record) => record.icao === 'ae5d8a');
+  assert.deepEqual(
+    shinr.map(({ band, source }) => ({ band, source })),
+    [
+      { band: '1090', source: 'feed' },
+      { band: '978', source: 'feed' },
+    ],
+  );
+  // Ages are anchored at the feed's own `now`.
+  assert.equal(shinr[0].lastPositionAt, FIXTURE_NOW_MS - 34_600);
+  assert.equal(shinr[0].lat, 30.269662);
+});
+
+test('a feed whose own now is over 10 s old is stale; failures are unreachable', async () => {
+  const logger = quietLogger();
+  const handler = createLocalReceiversHandler({
+    feedsValue: [
+      `1090=${FEED_1090}`,
+      `978=${FEED_978}`,
+      '1090=http://10.0.0.5/redirect/aircraft.json',
+      '1090=http://10.0.0.6/big/aircraft.json',
+      '1090=http://10.0.0.7/error/aircraft.json',
+      '978=http://10.0.0.8/garbage/aircraft.json',
+      '1090=http://8.8.8.8/aircraft.json',
+    ].join(','),
+    now: () => FIXTURE_NOW_MS + 10_001,
+    logger,
+    maxBytes: 4_096,
+    fetchImpl: async (url) => {
+      if (url === FEED_978) throw new TypeError('connect ECONNREFUSED secret');
+      if (url.includes('/redirect/'))
+        return respond(302, '', { location: 'http://169.254.169.254/' });
+      if (url.includes('/big/'))
+        return respond(200, `{"aircraft":[${' '.repeat(5_000)}]}`);
+      if (url.includes('/error/'))
+        return respond(500, 'upstream internal detail');
+      if (url.includes('/garbage/')) return respond(200, '<html>');
+      if (url.includes('8.8.8.8')) throw Error('invalid feed was fetched');
+      return respond();
+    },
+  });
+  const { json, body } = await call(handler);
+  assert.deepEqual(
+    json.feeds.map(({ band, status }) => `${band} ${status}`),
+    [
+      '1090 stale',
+      '978 unreachable',
+      '1090 unreachable',
+      '1090 unreachable',
+      '1090 unreachable',
+      '978 unreachable',
+      '1090 invalid',
+    ],
+  );
+  assert.equal(json.feeds[0].ageMs, 10_001);
+  assert.equal(json.records.length, 4, 'stale feed records still flow');
+  for (const secret of ['ECONNREFUSED', 'secret', 'internal detail', '169.254'])
+    assert.equal(body.includes(secret), false, `${secret} leaked`);
+  assert.equal(
+    body.includes('10.0.0'),
+    false,
+    'feed addresses stay server-side',
+  );
+  assert.ok(
+    logger.lines.some((line) =>
+      /LOCAL_RECEIVER_FEEDS feed-7 .* rejected: host must be/.test(line),
+    ),
+  );
+  assert.ok(logger.lines.some((line) => /REDIRECT_REFUSED/.test(line)));
+  assert.ok(logger.lines.some((line) => /RESPONSE_TOO_LARGE/.test(line)));
+});
+
+test('a feed that exceeds the timeout is unreachable', async () => {
+  const handler = createLocalReceiversHandler({
+    feedsValue: `1090=${FEED_1090}`,
+    logger: quietLogger(),
+    timeoutMs: 5,
+    fetchImpl: (url, { signal }) =>
+      new Promise((resolve, reject) => {
+        signal.addEventListener('abort', () =>
+          reject(Object.assign(new Error('aborted'), { name: 'AbortError' })),
+        );
+      }),
+  });
+  const { json } = await call(handler);
+  assert.equal(json.feeds[0].status, 'unreachable');
+});
+
+test('requests within a second share one read of every feed', async () => {
+  let clock = FIXTURE_NOW_MS;
+  let fetches = 0;
+  const handler = createLocalReceiversHandler({
+    feedsValue: `1090=${FEED_1090}`,
+    now: () => clock,
+    logger: quietLogger(),
+    fetchImpl: async () => {
+      fetches += 1;
+      return respond();
+    },
+  });
+  await Promise.all([call(handler), call(handler), call(handler)]);
+  assert.equal(fetches, 1, 'concurrent requests are single-flight');
+  clock += 500;
+  await call(handler);
+  assert.equal(fetches, 1, 'cached for about a second');
+  clock += 1_000;
+  await call(handler);
+  assert.equal(fetches, 2);
+  const res = await call(handler, 'POST');
+  assert.equal(res.status, 405);
+});
+
+test('a feed name is resolved, every address checked, and the connection pinned to it', async () => {
+  const lookups = [];
+  const answers = {
+    'good.local': [{ address: '10.0.0.9', family: 4 }],
+    'public.local': [{ address: '93.184.216.34', family: 4 }],
+    'linklocal.local': [{ address: '169.254.169.254', family: 4 }],
+    'mixed.local': [
+      { address: '192.168.1.4', family: 4 },
+      { address: '8.8.8.8', family: 4 },
+    ],
+  };
+  const fetched = [];
+  const logger = quietLogger();
+  const handler = createLocalReceiversHandler({
+    feedsValue: [
+      '1090=http://good.local:8080/data/aircraft.json',
+      '1090=http://public.local:8080/data/aircraft.json',
+      '978=http://linklocal.local/data/aircraft.json',
+      '978=http://mixed.local/data/aircraft.json',
+      `1090=${FEED_978}`,
+    ].join(','),
+    now: () => FIXTURE_NOW_MS,
+    logger,
+    lookupImpl: async (hostname, options) => {
+      lookups.push({ hostname, all: options?.all });
+      return answers[hostname];
+    },
+    fetchImpl: async (url, options) => {
+      fetched.push({ url, lookup: options.lookup });
+      return respond();
+    },
+  });
+  const { json } = await call(handler);
+  assert.deepEqual(
+    json.feeds.map(({ status }) => status),
+    ['live', 'unreachable', 'unreachable', 'unreachable', 'live'],
+  );
+  assert.deepEqual(
+    lookups.map(({ hostname }) => hostname).sort(),
+    ['good.local', 'linklocal.local', 'mixed.local', 'public.local'],
+    'IP literals are not resolved',
+  );
+  assert.ok(
+    lookups.every(({ all }) => all === true),
+    'every address',
+  );
+  assert.deepEqual(
+    fetched.map(({ url }) => url).sort(),
+    [FEED_978, 'http://good.local:8080/data/aircraft.json'],
+    'a name resolving outside loopback/RFC1918 is never contacted',
+  );
+  // The connection resolves only to the validated address, whatever the
+  // resolver would answer later.
+  answers['good.local'] = [{ address: '93.184.216.34', family: 4 }];
+  const pinned = fetched.find(({ url }) => url.includes('good.local')).lookup;
+  assert.equal(typeof pinned, 'function');
+  const one = await new Promise((resolve) =>
+    pinned('good.local', {}, (error, address, family) =>
+      resolve({ error, address, family }),
+    ),
+  );
+  assert.deepEqual(one, { error: null, address: '10.0.0.9', family: 4 });
+  const all = await new Promise((resolve) =>
+    pinned('good.local', { all: true }, (error, addresses) =>
+      resolve(addresses),
+    ),
+  );
+  assert.deepEqual(all, [{ address: '10.0.0.9', family: 4 }]);
+  assert.ok(logger.lines.some((line) => /FORBIDDEN_ADDRESS/.test(line)));
+});
+
+test('the default transport connects to the validated address, not a re-resolution', async (t) => {
+  const { createServer } = await import('node:http');
+  const server = createServer((req, res) => {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ now: FIXTURE_NOW_MS / 1000, aircraft: [] }));
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => server.close());
+  const { port } = server.address();
+  // `receiver-pin-test.local` has no real DNS entry: only the pinned lookup
+  // can reach the loopback server.
+  const handler = createLocalReceiversHandler({
+    feedsValue: `1090=http://receiver-pin-test.local:${port}/data/aircraft.json`,
+    now: () => FIXTURE_NOW_MS,
+    logger: quietLogger(),
+    lookupImpl: async () => [{ address: '127.0.0.1', family: 4 }],
+  });
+  const { json } = await call(handler);
+  assert.equal(json.feeds[0].status, 'live');
+});
+
+test('null-body statuses (204, 205, 304) from a named feed are a clean feed error, never an uncaught exception', async (t) => {
+  const { createServer } = await import('node:http');
+  const server = createServer((req, res) => {
+    const status = Number(req.url.split('/')[1]);
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end();
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => server.close());
+  const { port } = server.address();
+  const uncaught = [];
+  const onUncaught = (error) => uncaught.push(error);
+  process.on('uncaughtException', onUncaught);
+  t.after(() => process.off('uncaughtException', onUncaught));
+  const handler = createLocalReceiversHandler({
+    feedsValue: [204, 205, 304]
+      .map(
+        (status) =>
+          `1090=http://receiver-null-body.local:${port}/${status}/aircraft.json`,
+      )
+      .join(','),
+    now: () => FIXTURE_NOW_MS,
+    logger: quietLogger(),
+    timeoutMs: 300,
+    lookupImpl: async () => [{ address: '127.0.0.1', family: 4 }],
+  });
+  const { status, json } = await call(handler);
+  // Let any exception thrown inside the response callback surface.
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  assert.deepEqual(uncaught, [], 'no uncaught exception');
+  assert.equal(status, 200);
+  assert.deepEqual(
+    json.feeds.map((feed) => feed.status),
+    ['unreachable', 'unreachable', 'unreachable'],
+  );
+});
+
+test('a stalled DNS lookup fails its feed at the deadline without holding other feeds or later polls', async () => {
+  let clock = FIXTURE_NOW_MS;
+  const lookups = [
+    // Never answers.
+    () => new Promise(() => {}),
+    // Answers only after the deadline: the late answer is ignored.
+    () =>
+      new Promise((resolve) =>
+        setTimeout(() => resolve([{ address: '127.0.0.1', family: 4 }]), 80),
+      ),
+  ];
+  const fetched = [];
+  const handler = createLocalReceiversHandler({
+    feedsValue: `1090=http://stalled.local/data/aircraft.json,978=${FEED_978}`,
+    now: () => clock,
+    logger: quietLogger(),
+    timeoutMs: 20,
+    lookupImpl: () => lookups.shift()(),
+    fetchImpl: async (url) => {
+      fetched.push(url);
+      return respond();
+    },
+  });
+  const within = (promise) =>
+    Promise.race([
+      promise,
+      new Promise((resolve) => setTimeout(() => resolve('timed out'), 60)),
+    ]);
+  const first = await within(call(handler));
+  assert.notEqual(first, 'timed out', 'the snapshot is not held by DNS');
+  assert.deepEqual(
+    first.json.feeds.map((feed) => feed.status),
+    ['unreachable', 'live'],
+  );
+  clock += 2_000;
+  const second = await within(call(handler));
+  assert.notEqual(second, 'timed out', 'a later poll is not held either');
+  assert.deepEqual(
+    second.json.feeds.map((feed) => feed.status),
+    ['unreachable', 'live'],
+  );
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  assert.ok(
+    fetched.every((url) => !url.includes('stalled.local')),
+    'a late DNS answer is never fetched',
+  );
+});

src/data/local_data/natural_earth/README.md

@@ -1,4 +1,4 @@
-# Natural Earth physical regions pack
+# Natural Earth packs
 
 Offline named-region polygons for the voice-annotation resolver
 (`src/data/naturalEarthRegions.js`) — "outline the Alps" resolves to the real
@@ -8,6 +8,8 @@ range geometry with no network dependency.
 |------|----------------|----------|
 | `regions.json` | `ne_10m_geography_regions_polys` (ranges, deserts, plateaus, peninsulas, islands, …) | 1,046 named |
 | `marine.json` | `ne_10m_geography_marine_polys` (seas, gulfs, straits, bays, …) | 292 named |
+| `countries.json` | `ne_10m_admin_0_countries` (countries) | 256 |
+| `states_provinces.json` | `ne_10m_admin_1_states_provinces` (states, provinces and other first-level units) | 4,587 named |
 
 **Source:** Natural Earth 10m physical vectors, via the canonical
 [nvkelso/natural-earth-vector](https://github.com/nvkelso/natural-earth-vector)
@@ -34,3 +36,70 @@ See DATA_SOURCES.md.
 
 Duplicate names exist upstream (two "Cordillera Oriental", a sliver + real
 "Canadian Shield", …); the lookup module resolves ties by largest area.
+
+## States and provinces (`states_provinces.json`)
+
+Worldwide first-level administrative units for area annotations ("outline
+Texas", "outline Bavaria"), read by `src/data/adminBoundaries.js`.
+
+**Source:** `geojson/ne_10m_admin_1_states_provinces.geojson` from
+[nvkelso/natural-earth-vector](https://github.com/nvkelso/natural-earth-vector)
+at commit `ca96624a56bd078437bca8184e78163e5039ad19` (SHA-256
+`22d0e3ad85eb3e27f17cabf8ba2d50e554fbc27a87796ff891d958185da62fb5`), fetched
+2026-09-25. `geojson/ne_10m_populated_places_simple.geojson` from the same
+commit (SHA-256
+`fd3fa867a320cbd5c5b6bb5bc550afeec2939fb2cef688e508007282a55ac42f`) is read
+only to mark ambiguous names; none of it is bundled.
+
+**License:** public domain, as above.
+
+**Regenerate:** `node scripts/build-admin-packs.mjs --only admin1` downloads
+the pinned files (to the system temp directory, or `--cache <dir>`), checks
+their SHA-256 and rewrites the pack byte for byte. Parameters are in the
+script's `PARAMS` and in the pack's `meta.curation`.
+
+**Schema:** `meta` (source, URLs, hashes, license, curation) and `features[]`
+with `name`, `nameEn` (when it differs), `alt[]` (Latin-script `name_alt`
+variants and abbreviations), `postal`, `type` (`type_en`), `rank`
+(`min_label`), `country` (`admin`), `iso2`, `iso` (ISO 3166-2), `amb[]`,
+`ambAbroad[]`, `cityState`, `label` ([lon, lat] label point) and
+`polygons`. `polygons` is a list of parts, largest first, each
+`[outer, ...holes]`; every ring is open and stored as integers in units of
+10^-3 degrees (10^-`d` when a feature carries `d`), the first vertex absolute
+and each later one as a `[dLon, dLat]` delta.
+
+**Curation:**
+
+- The 7 unnamed features and 2 degenerate Nauru districts are dropped
+  (4,596 → 4,587).
+- Douglas-Peucker per ring at 0.004 × √(unit area in km²) km, clamped to
+  0.005°–0.02° (Texas ≈ 0.02°, Bavaria ≈ 0.01°); coordinates rounded to
+  3 decimals. The 75 units too small to survive (Maldives atolls, Malta's
+  councils) keep 4 decimals at 0.001° (`d: 4`); 3 smaller still (Vatican
+  City) keep their source rings at 5 decimals (`d: 5`).
+- Parts under 20 km² or under 0.03% of the unit's largest part are dropped;
+  holes under 20 km² are dropped. Outers are counter-clockwise, holes
+  clockwise.
+- `amb` lists names that are also a country (`admin`/`geonunit` of any
+  unit), a populated place of 200,000+ (`pop_max`) inside the unit's box
+  when the unit is larger than 1,000 km², or a populated place of 50,000+
+  elsewhere in the same country; `ambAbroad` lists names shared only with a
+  populated place of 50,000+ in another country. `cityState` marks a unit of
+  at most 1,000 km² that contains its namesake city (Berlin, Vienna, Paris).
+  548 units carry `amb`, 108 `ambAbroad`, 138 `cityState`.
+- Result: 3,648,916 bytes (1,260,545 with gzip -9); 6,492 parts, 80 holes,
+  407,339 vertices.
+
+## Countries (`countries.json`)
+
+Natural Earth 10m admin-0 countries, public domain under the terms above.
+Source: `geojson/ne_10m_admin_0_countries.geojson` at the same pinned commit;
+SHA-256 `239eec57ac17f100a11e2536cffc56752c318b50ae765b0918ff7aab4ce8f255`.
+Regenerate with `node scripts/build-admin-packs.mjs --only countries`.
+Uses the state/province encoding and simplification, retaining parts of at least
+20 km² and 0.003% of the largest part (including Alaska and Hawaii); the largest
+part always stays. Holes under 20 km² are dropped.
+Includes England, Scotland, Wales and Northern Ireland from
+`ne_10m_admin_0_map_units.geojson` at the same commit (SHA-256
+`57da82be755f4afccd8f3b14251bb2752f5df1395f47d2d86f817470c4a48862`).
+Result: 945,843 bytes; 260 features, 2,088 parts, 122,788 vertices.

src/data/local_data/natural_earth/countries.json

@@ -0,0 +1 @@
+{"meta":{"title":"Natural Earth admin-0 countries","mapUnits":{"url":"https://raw.githubusercontent.com/nvkelso/natural-earth-vector/ca96624a56bd078437bca8184e78163e5039ad19/geojson/ne_10m_admin_0_map_units.geojson","sha256":"57da82be755f4afccd8f3b14251bb2752f5df1395f47d2d86f817470c4a48862"},"source":"ne_10m_admin_0_countries","url":"https://raw.githubusercontent.com/nvkelso/natural-earth-vector/ca96624a56bd078437bca8184e78163e5039ad19/geojson/ne_10m_admin_0_countries.geojson","sha256":"239eec57ac17f100a11e2536cffc56752c318b50ae765b0918ff7aab4ce8f255","commit":"ca96624a56bd078437bca8184e78163e5039ad19","license":"Public domain (https://www.naturalearthdata.com/about/terms-of-use/)","decimals":3,"curation":{"toleranceFactor":0.004,"minToleranceDeg":0.005,"maxToleranceDeg":0.02,"decimals":3,"minPartKm2":20,"minPartShare":0.00003,"minHoleKm2":20},"script":"scripts/build-admin-packs.mjs"},"features":[{"name":"Afghanistan","alt":["Islamic State of Afghanistan"],"country":"Afghanistan","iso":"AFG","iso2":"AF","type":"Country","polygons":[[[74383,37127,-15,40,89,10,43,55,123,-1,98,67,73,-84,98,17,-103,100,-129,63,-139,-18,-205,51,-12,-27,-80,3,-36,-65,-479,-121,-112,45,142,76,14,90,-268,53,-189,-16,-164,-81,-64,-69,-277,-95,-133,-191,-398,-62,-423,-268,-184,-12,-100,83,-122,297,63,241,36,453,60,55,8,82,-61,46,-196,-51,-83,33,101,258,-1,67,-407,222,-15,-40,-159,13,-112,-41,20,-18,-85,-40,-17,-72,-36,-12,-77,-142,-216,-148,8,-34,-90,7,-7,-56,82,-71,36,-114,-35,-82,-90,-82,-150,8,-89,68,-117,-35,-293,-3,-131,-142,32,-191,32,-22,-130,-107,-66,-13,-122,65,-139,151,-97,18,28,-59,-80,50,-26,-17,10,-61,-151,27,-42,-72,-223,-54,-12,-47,-104,-2,-10,-93,-92,8,-166,-92,-142,138,-105,46,8,79,-34,40,-114,25,-72,-34,-58,62,-244,-97,-136,97,-26,59,-91,43,-712,-53,-151,54,-63,56,-225,67,-94,70,-22,-49,-80,-19,-38,-80,3,-85,-87,-88,-474,-24,-284,-115,-23,-64,23,-116,-174,-277,-11,-237,-116,-152,-174,-60,-38,-60,-107,8,-102,-55,-12,-106,-155,31,-124,-53,-184,-18,-152,-88,-326,-15,-20,-30,28,-56,102,-71,-137,-74,24,-100,-21,-88,-162,-49,-224,-140,-159,-21,-103,54,-146,-140,-52,153,-227,145,-402,-8,-212,123,-41,74,-82,-10,20,-70,-95,-158,-8,-90,-85,-43,-6,-64,51,-91,-72,-169,-10,-118,-105,-92,-12,-85,-248,-122,190,-197,-246,-12,-151,-168,35,-298,-41,-130,25,-73,144,-78,190,-4,75,-42,-89,-30,-3,-68,-261,-265,-5,-93,267,-809,-15,-161,-40,-61,47,-532,865,-122,55,-52,1,-81,83,-225,-24,-168,-958,-989,1634,-450,1091,89,517,-110,87,97,305,86,558,-30,1160,295,145,122,-122,101,86,187,17,192,-54,164,98,322,184,54,113,106,34,113,246,119,74,-6,18,-73,311,-28,419,126,5,61,-159,16,-42,119,127,-9,147,102,123,15,81,50,92,137,116,-59,243,-41,52,29,-131,29,108,40,149,-48,29,-74,99,-98,236,70,259,265,-48,193,17,170,-35,162,193,192,-50,117,101,85,11,171,60,47,224,40,109,-26,114,38,53,67,77,5,169,120,-8,64,-131,124,19,125,-56,85,-160,36,-111,174,26,90,130,27,325,-87,194,-18,340,26,22,42,56,-6,123,53,45,111,14,192,-130,86,-35,89,109,26,15,115,122,75,86,127,181,75,41,59,-2,63,129,118,-108,111,91,109,-39,83,11,56,-100,61,22,91,-159,232,-185,94,52,98,335,203,-11,44,63,86,173,-61,-10,83,102,19,164,81,20,47,113,27,-19,48,61,24,240,32,176,75,238,-3,324,47,581,15,262,-76,59,15,36,67,106,4,158,92,63,10,80,-42,5,60]]]},{"name":"Akrotiri Sovereign Base Area","alt":["Akrotiri"],"country":"Akrotiri Sovereign Base Area","iso":"WSB","iso2":"-99","type":"Country","polygons":[[[32970,34632,-7,-7,-9,18,12,9,24,-6,-2,27,-33,4,-19,-19,-19,9,-3,-7,-48,19,-6,22,-28,0,-13,-13,-13,-2,-7,-15,-32,5,-7,-7,1,-16,73,18,80,-14,2,-18,29,-45,-4,-25,89,0,-21,28,7,37]]]},{"name":"Aland","alt":["Åland Islands"],"country":"Aland","iso":"ALD","iso2":"AX","type":"Country","polygons":[[[20236,60232,42,47,-76,14,-21,-7,11,26,-14,11,-52,11,-33,21,-21,-5,-48,11,13,-27,-41,22,-68,0,-22,46,-24,4,-44,-6,-61,-45,42,-8,39,-34,31,32,35,-31,10,-32,-28,-10,-13,35,-13,-48,-21,-14,-7,-28,-34,15,5,-24,-9,-17,-22,9,-27,49,32,51,-48,7,22,-21,-62,-17,-21,-31,3,19,-8,7,-36,2,24,-49,11,-5,13,-42,68,-96,26,22,18,4,17,-6,-1,-10,9,-5,13,0,23,7,5,10,14,5,23,0,14,-9,17,-32,-3,-10,10,-2,10,6,-9,30,57,10,39,-7,5,11,-19,17,13,61,-34,-20,-23,17,-43,13,-27,22,-2,10,40,7,-7,-21,68,-20,-1,18,16,15,-37,24,-18,38,27,-12,22,9,9,18,-10,19,37,-3,-4,-17,-33,-38,8,-19,29,-21,-3,-24,7,0,17,32,29,16,77,6,-16,-12,-49,-2,-21,-10,-13,-25,-2,-14,8,-6,42,0,25,-9,13,3,26,29,29,5,-21,21]],[[20025,60042,79,-14,17,-11,-16,-21,18,-7,48,10,13,-6,-9,-22,50,34,-32,61,-30,22,-62,7,-33,-22,-34,-9]],[[19634,60240,-26,17,-40,-2,-31,-23,0,-31,-24,-17,14,-35,38,-19,20,5,18,29,-11,33,55,-41,24,2,0,33,-32,30]],[[20284,59958,23,-4,15,9,3,14,74,4,48,14,-10,10,-98,15,-37,-21,-21,-22]],[[20256,60145,8,-27,-6,-10,-36,42,-24,-46,4,-16,64,-28,12,6,-9,20,29,36,-20,20]],[[20411,60260,-31,10,-21,-4,-12,-13,-2,-15,8,-9,30,12,5,-19,-7,-23,12,-2,48,48,-2,13,-11,8]],[[20583,60059,-38,-3,-44,-43,26,-8,23,14,37,-11,19,15,2,13,-7,3,17,3,-8,3]]]},{"name":"Albania","alt":["Republic of Albania"],"country":"Albania","iso":"ALB","iso2":"AL","type":"Country","polygons":[[[2Line truncated

src/data/local_data/natural_earth/states_provinces.json

@@ -0,0 +1 @@
+{"meta":{"title":"Natural Earth admin-1 states and provinces","source":"ne_10m_admin_1_states_provinces","url":"https://raw.githubusercontent.com/nvkelso/natural-earth-vector/ca96624a56bd078437bca8184e78163e5039ad19/geojson/ne_10m_admin_1_states_provinces.geojson","sha256":"22d0e3ad85eb3e27f17cabf8ba2d50e554fbc27a87796ff891d958185da62fb5","ambiguitySource":"https://raw.githubusercontent.com/nvkelso/natural-earth-vector/ca96624a56bd078437bca8184e78163e5039ad19/geojson/ne_10m_populated_places_simple.geojson","ambiguitySha256":"fd3fa867a320cbd5c5b6bb5bc550afeec2939fb2cef688e508007282a55ac42f","commit":"ca96624a56bd078437bca8184e78163e5039ad19","license":"Public domain (https://www.naturalearthdata.com/about/terms-of-use/)","schema":"features[]: name, nameEn?, alt?[], postal?, type, rank? (min_label: the zoom at which Natural Earth labels the unit; lower is more prominent), country, iso2, iso (ISO 3166-2), amb?[] (normalized names that are also a country or a city — alone or with the country named), ambAbroad?[] (names shared only with a city in another country — ambiguous alone, settled by naming the country), cityState? (the unit is its own city), label? [lon, lat] label point, d? (decimals when not meta.decimals), polygons[][ring] (first ring outer, rest holes; each ring open and encoded as integers in 10^-d degrees, first vertex absolute then [dLon, dLat] deltas)","decimals":3,"curation":{"toleranceFactor":0.004,"minToleranceDeg":0.005,"maxToleranceDeg":0.02,"decimals":3,"minPartKm2":20,"minPartShare":0.0003,"minHoleKm2":20,"ambiguity":{"insideMinPopulation":200000,"elsewhereMinPopulation":50000,"cityStateMaxKm2":1000}},"script":"scripts/build-admin-packs.mjs"},"features":[{"name":"Badakhshan","alt":["Badahšan"],"postal":"BD","type":"Province","rank":6.7,"country":"Afghanistan","iso2":"AF","iso":"AF-BDS","label":[70.804,36.781],"polygons":[[[74892,37231,-29,14,-74,86,-129,63,-29,-13,-110,-5,-66,18,-77,0,-34,27,-23,-7,-5,13,-12,-27,-80,3,-16,-13,-2,-34,-18,-18,-352,-81,-38,-28,-52,2,-37,-14,-29,25,-62,-9,-16,8,-5,21,34,34,59,9,49,33,14,90,-78,3,-190,50,-44,-1,-63,-27,-82,12,-36,-15,-49,-42,-41,0,-38,-24,-64,-69,-72,-6,-94,-55,-111,-34,-133,-191,-149,-18,-34,-14,-69,11,-146,-41,-133,-94,-290,-174,-88,-20,-96,8,-42,18,-58,65,-25,86,-65,92,-3,63,-29,56,19,150,37,50,7,41,-7,101,24,77,-14,81,5,43,20,28,21,82,-13,41,8,18,52,37,8,82,-61,46,-36,2,-160,-53,-83,33,15,72,29,44,57,142,-1,67,-24,30,-116,45,-101,73,-67,10,-52,57,-47,7,-15,-40,-65,20,-28,-13,-66,6,-35,-27,-77,-14,20,-18,-44,-33,-41,-7,-17,-72,-36,-12,-77,-142,-55,-26,-131,-113,-30,-9,-4,-17,12,-17,-47,-10,-43,17,-11,-25,4,-31,31,-50,51,-21,28,-45,8,-69,-35,-82,-32,-6,-17,-38,-41,-38,-29,-9,-125,19,-5,-20,6,-123,37,-21,-24,-28,-14,-83,30,-88,-1,-53,91,-92,-28,-47,-40,-16,-19,-39,-30,-19,-3,-307,33,-100,1,-53,102,-57,84,-78,137,-23,80,0,31,-20,3,-134,-46,-112,33,-67,-161,-91,-28,-30,-19,-45,-23,-135,63,-9,90,37,95,-31,20,-45,56,-55,-19,-69,2,-39,6,-13,33,-4,58,24,16,45,36,26,43,-40,28,-8,106,-5,19,32,-17,84,12,26,82,16,54,57,-45,41,4,35,47,24,42,56,23,87,85,89,-4,15,42,42,15,37,79,38,17,38,84,30,76,70,79,27,-16,28,5,16,33,30,30,56,39,-5,87,-57,47,1,11,11,-19,40,-2,32,102,19,102,64,62,17,16,13,-5,26,9,8,113,27,-22,35,20,22,132,32,152,15,63,43,113,32,238,-3,78,22,45,-10,51,22,150,13,75,-10,65,15,177,-3,131,18,133,-5,92,-19,82,-42,88,-15,59,15,21,59,15,8,106,4,158,92,63,10,64,-46,16,4,10,54,-28,14,-42,53,-94,44,-17,21,2,19,89,10,43,55,90,11,33,-12,28,29,25,4,45,34,16,-2,57,-82]]]},{"name":"Badghis","alt":["Badghes","Badghisat","Badgis"],"postal":"BG","type":"Province","rank":6.7,"country":"Afghanistan","iso2":"AF","iso":"AF-BDG","label":[63.85,35.27],"polygons":[[[63125,35860,-21,-4,-15,-13,-5,-17,28,-56,72,-58,25,-8,5,-12,-34,-26,-77,-20,-26,-21,0,-66,24,-34,-21,-88,-13,-11,-82,-11,-67,-27,-95,-60,-39,-101,-84,-115,-28,-70,-20,-148,16,-51,49,-17,34,-1,69,-50,46,-14,47,-29,82,-6,31,-35,8,-45,77,-11,62,-24,71,34,116,-10,73,-22,99,-52,76,-13,42,10,77,-19,58,-30,227,53,67,45,45,10,26,39,52,24,107,0,57,-15,110,6,20,29,33,11,123,-4,57,-12,78,30,179,40,48,29,21,56,10,100,-46,76,-74,50,-57,58,-22,9,-32,-1,-49,25,-35,46,-116,-14,-102,12,-101,29,-5,17,6,79,13,53,-1,22,-8,7,-118,-20,-47,21,11,27,-15,22,-220,19,-24,15,-2,107,-12,37,-43,46,-51,18,-8,11,28,54,3,44,26,86,3,83,-11,30,-30,14,-16,-2,-124,-53,-184,-18,-71,-57,-81,-31,-87,-15]]]},{"name":"Baghlan","alt":["Baglan","Bughlan"],"postal":"BL","type":"Province","rank":6.7,"country":"Afghanistan","iso2":"AF","iso":"AF-BGL","amb":["baghlan"],"label":[68.983,35.859],"polygons":[[[69956,35887,-32,41,-3,19,-20,20,-32,67,-81,65,-10,115,-12,19,-54,8,-11,61,-20,48,-10,3,-56,-32,-92,-26,-79,-48,-99,-17,-23,9,-21,-11,-33,47,-35,8,-35,41,-117,31,-82,62,-84,16,-53,-20,-20,7,-43,28,-64,64,-12,22,-88,-13,-96,20,-217,7,-82,23,-38,-14,-19,-14,-10,-28,152,-201,46,-50,120,-67,31,-26,9,-18,-64,-80,-129,-85,-14,-26,-12,-108,-156,-177,-4,-35,42,-29,-5,-30,-36,-42,-10,-34,-54,-46,-3,-25,20,-60,-12,-32,7,-36,-40,-99,-31,-16,-20,-28,-5,Line truncated

src/data/local_data/osm_military_names/README.md

@@ -0,0 +1,23 @@
+# Military area names
+
+This database is distributed under [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/), separately from the MIT code.
+© [OpenStreetMap contributors](https://www.openstreetmap.org/copyright).
+Distribution: [Overture Maps Foundation](https://docs.overturemaps.org/attribution/), base/land_use release **2026-09-23.1**.
+OSM snapshots: **2026-09-06**, with two named records from **2026-09-12**.
+
+Selected named military areas; geometry simplified to interior label points,
+bounds and area, coordinates rounded and records re-encoded. Names are unchanged.
+Rows: `[typedOsmId, name, lon, lat, west, south, east, north, classIndex, areaM2]`.
+Labels use five decimal places; bounds use four. Area is measured on the WGS84
+ellipsoid. Class indices refer to `classes`. Output SHA-256: [`names.sha256`](names.sha256).
+
+Rebuild (maintainer tool; requires Python and `duckdb==1.5.5`):
+
+```sh
+python scripts/build-military-names.py --cache /tmp/military-names
+python scripts/build-military-names.py --cache /tmp/military-names --verify
+```
+
+The pinned parquet file list and query are in `scripts/military-names-files.json`
+and `scripts/military-names.sql`. The first build downloads DuckDB extensions and
+scans source columns; subsequent builds reuse the cached selected rows.

src/data/local_data/osm_military_names/names.json

@@ -0,0 +1 @@
+{"release":"2026-09-23.1","snapshots":["2026-09-06","2026-09-12"],"classes":["military_land","airfield","naval_base","range","barracks","base","training_area"],"records":[["r122949","Scott Air Force Base",-89.85277,38.54384,-89.8799,38.5292,-89.8041,38.5588,1,12413875],["r130448","Fort Campbell",-87.61569,36.63134,-87.8047,36.5355,-87.4231,36.7268,0,419957267],["r133445","Fort George G Meade",-76.74626,39.10227,-76.7766,39.0732,-76.7092,39.131,0,18817854],["r133514","Joint Base Andrews",-76.87745,38.80571,-76.9034,38.7823,-76.8491,38.829,5,17812387],["r139794","Whiteman AFB",-93.56134,38.72992,-93.5959,38.7024,-93.5308,38.7575,1,19580209],["r139848","Fort Leonard Wood",-92.16933,37.70114,-92.2496,37.6052,-92.0411,37.798,0,248751778],["r147157","Camp du Valdahon",6.32589,47.18508,6.2731,47.151,6.375,47.2189,0,34786523],["r169792","Offutt Air Force Base",-95.90817,41.1172,-95.9664,41.0986,-95.8781,41.1364,1,11200098],["r170440","McGuire Air Force Base",-74.57822,40.03444,-74.6026,40.0267,-74.5593,40.0586,5,5388371],["r171293","Cannon AFB",-103.31633,34.38639,-103.3371,34.3653,-103.2955,34.4054,1,13976465],["r171528","White Sands",-106.49662,32.38378,-106.5139,32.3657,-106.4793,32.4031,0,8047394],["r175474","West Point",-74.00783,41.35584,-74.1043,41.3163,-73.9467,41.413,0,64474104],["r176921","Pope Field",-79.01404,35.17337,-79.0319,35.1587,-78.9888,35.1886,1,7327036],["r176940","Fort Bragg",-79.15415,35.14031,-79.3814,35.0306,-78.9447,35.2512,5,554150015],["r206824","Fort Belvoir",-77.14369,38.7108,-77.1739,38.6729,-77.1208,38.7486,0,23156083],["r237502","Joint Base Lewis-McChord",-122.50741,47.03083,-122.802,46.9015,-122.3698,47.1595,0,358289411],["r252043","Francis E. Warren Air Force Base",-104.86328,41.16587,-104.8859,41.1317,-104.8394,41.2012,1,23635348],["r253786","Naval Base Point Loma",-117.24939,32.6941,-117.2562,32.6648,-117.2341,32.7131,5,4741248],["r253814","Marine Corps Air Station Miramar",-117.08249,32.87638,-117.1986,32.8331,-116.9871,32.9208,0,87161025],["r308744","Schietveld",5.44866,51.04934,5.4361,51.0439,5.4672,51.0548,0,1200107],["r309689","Ādažu poligons",24.46976,57.15377,24.3461,57.0837,24.563,57.2226,6,133266211],["r309926","Roberts Army Heliport",-120.74307,35.81448,-120.7467,35.8091,-120.7404,35.8197,1,331999],["r317709","Naval Reservation San Clemente Island",-118.51541,32.92142,-118.6206,32.8004,-118.3487,33.0422,0,163093405],["r317710","Naval Air Warfare Center China Lake",-117.62946,35.75329,-117.8897,35.272,-116.9246,36.2318,0,4495435805],["r317712","Marine Corps Base Camp Pendleton",-117.42402,33.35453,-117.5963,33.2056,-117.2554,33.5036,0,507618719],["r317716","Camp Roberts",-120.77817,35.79079,-120.8594,35.6884,-120.6887,35.8934,6,173959948],["r317718","Camp San Luis Obispo",-120.69818,35.33796,-120.7635,35.3048,-120.6642,35.3716,0,23703563],["r379564","US Coast Guard - Base Portsmouth",-76.35878,36.88311,-76.3678,36.8801,-76.3518,36.8859,0,636553],["r383103","Patuxent River NAS (Trapnell Field)",-76.40977,38.28455,-76.4423,38.2641,-76.3817,38.3042,1,9064162],["r389913","Helmut-Schmidt-Universität – Universität der Bundeswehr Hamburg",10.11122,53.56877,10.1059,53.5663,10.1165,53.5709,4,255487],["r392208","Joint Expeditionary Base Little Creek - Fort Story East East",-76.01769,36.92062,-76.0464,36.9092,-75.9918,36.9323,0,6066899],["r392665","Naval Station Norfolk",-76.29734,36.94167,-76.3307,36.9193,-76.2646,36.964,0,13143152],["r416869","Naval Base Kitsap-Bremerton",-122.64202,47.5574,-122.6622,47.5511,-122.6257,47.5649,5,2487880],["r417668","Camp Murray",-122.56814,47.11741,-122.5809,47.111,-122.5577,47.1229,0,1105917],["r420625","Yakima Training Center",-120.18138,46.75205,-120.4667,46.5473,-119.9159,46.9563,0,1322423534],["r437075","Vojenský újezd Libavá",17.54728,49.67197,17.4068,49.5838,17.6984,49.7602,6,235507050],["r438525","Vojenský újezd Boletice",14.07264,48.8478,13.947,48.7872,14.2431,48.9085,6,165484736],["r439469","Vojenský újezd Hradiště",13.13,50.26224,13.0045,50.1629,13.2555,50.3615,6,280845474],["r440731","Vojenský újezd Březina",16.96557,49.40648,16.8378,49.313,17.0541,49.5,6,149643828],["r451539","Naval Magazine Indian Island",-122.72867,48.05303,-122.7481,48.0187,-122.7014,48.0872,0,10831143],["r451698","Naval Radio Station Jim Creek",-121.92018,48.2028,-121.9584,48.167,-121.8873,48.2249,0,19804554],["r454382","National Security Investigative Service",31.31037,30.05187,31.31,30.0508,31.3117,30.0528,0,14562],["r533411","Naval Outlying Landing Field Coupeville",-122.63203,48.18948,-122.6479,48.171,-122.6152,48.2067,1,2626295],["r533644","Eglin Air Force Base",-86.51396,30.5777,-86.9829,30.3814,-86.1073,30.7498,5,1873152593],["r534267","Saufley Field",-87.34183,30.46763,-87.3512,30.4582,-87.3321,30.4773,0,2666728],["r541791","Whidbey Island Naval Air Station Seaplane Base",-122.56089,48.28799,-122.6453,48.2676,-122.5559,48.3083,0,9647535],["r543980","U.S. Coast Guard - Base Seattle",-122.34035,47.58933,-122.343,47.5879,-122.3375,47.5908,Line truncated