fix(osm): stop using public Overpass by default (#648) (#742)

Traffic roads come from OpenFreeMap vector tiles, or TomTom flow tiles with a
key (Hybrid by default). Military areas use OpenFreeMap polygons with a bundled
worldwide name index; wide views show named points. ALPR reads an hourly
OpenStreetMap extract. Cockpit place context and country, state and US county
outlines use bundled Natural Earth and US Census data. Overpass is used only
when an operator configures their own endpoint.

Also: camera arrivals no longer land below ground, keyless terrain retries on
429, bounded relation geometry for configured Overpass, one shared
OpenStreetMap credit, and separate tile and API transports for embedders.

Co-authored-by: theGaryLarson <[email protected]>
Co-authored-by: Milan Khanal <[email protected]>

src/layers/alpr/floors.js

@@ -0,0 +1,82 @@
+/** One cancellable consumer of the shared terrain service, coalesced by floor cell. */
+export function createAlprFloorResolver(ground) {
+  const pending = new Map();
+  const queued = new Map();
+  let owner = null;
+  let running = false;
+
+  async function pump(controller) {
+    try {
+      while (queued.size && !controller.signal.aborted) {
+        const batch = [...queued.values()].slice(0, 64);
+        for (const cell of batch) queued.delete(cell.key);
+        try {
+          await ground.resolveGroundFloorCells(
+            batch.map(({ lat, lon }) => ({ lat, lon })),
+            { signal: controller.signal },
+          );
+        } catch {
+          // Missing floors remain clamped; cancellation must not publish later.
+        }
+        for (const cell of batch) {
+          if (pending.get(cell.key) === cell) pending.delete(cell.key);
+          cell.finish();
+        }
+      }
+    } finally {
+      if (owner === controller) running = false;
+    }
+  }
+
+  function resolve(points) {
+    if (typeof ground.resolveGroundFloorCells !== 'function')
+      return Promise.resolve();
+    owner ??= new AbortController();
+    const waits = [];
+    for (const point of points) {
+      const lat = Number(point.lat.toFixed(3));
+      const lon = Number(point.lon.toFixed(3));
+      const key = `${lat},${lon}`;
+      let cell = pending.get(key);
+      if (!cell) {
+        let finish;
+        const promise = new Promise((done) => {
+          finish = done;
+        });
+        cell = { key, lat, lon, promise, finish };
+        pending.set(key, cell);
+        queued.set(key, cell);
+      }
+      waits.push(cell.promise);
+    }
+    if (!running && queued.size) {
+      running = true;
+      void pump(owner);
+    }
+    return Promise.all(waits);
+  }
+
+  async function prepare(points) {
+    let timer;
+    try {
+      await Promise.race([
+        resolve(points),
+        new Promise((done) => {
+          timer = setTimeout(done, ground.FLOOR_RESOLVE_DEADLINE_MS ?? 1200);
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  function cancel() {
+    owner?.abort();
+    owner = null;
+    running = false;
+    for (const cell of pending.values()) cell.finish();
+    pending.clear();
+    queued.clear();
+  }
+  return { resolve, prepare, cancel };
+}

src/layers/alpr/index.js

@@ -1,3 +1,4 @@
+import { isUnavailableCapability } from '../../sources/capability.js';
 import * as Cesium from 'cesium';
 import {
   LAYER_ID,
@@ -21,7 +22,9 @@ import { createAlprPresentation } from './presentation.js';
 /**
  * Own one layer's requests, records, display and viewer subscriptions.
  * A source fetches a bounded box with an AbortSignal and resolves
- * { records, stale, saturated }. Records use stable string ids and latitude /
+ * { records, stale, saturated }, optionally with `coverage` (the bounds its
+ * records fully cover, reused for later views inside it) and `zoom` (their
+ * tile precision; `source.detailZoom(box)` names the zoom a view needs). Records use stable string ids and latitude /
  * longitude in degrees; optional directionDeg is a compass bearing [0, 360).
  * Manufacturer, operator and cameraType are optional display fields.
  * Source label and attribution { name, description, text, href } identify the
@@ -67,6 +70,12 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     debounceTimer: null,
     /** Snapped box of the last successful query; a view still inside it reuses its records. */
     lastQueryBox: null,
+    /** Extract zoom of the accepted records (null for sources without tiles). */
+    lastQueryZoom: null,
+    /** Increments whenever the displayed camera set changes (QA stability probe). */
+    renderRevision: 0,
+    /** Cameras in view beyond the render cap. */
+    renderSaturated: false,
   };
   const {
     initOverlay,
@@ -81,6 +90,7 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     clearSelection,
     updateSelectedAnchor,
     installInteraction,
+    prepareFloors,
   } = createAlprPresentation({ state, services, source });
 
   function setAlprStatus(status, error = null) {
@@ -109,10 +119,34 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     if (resetBackoff) state.retryDelayMs = 0;
   }
 
+  /** Whether accepted records already answer `box` without a request. */
+  function canReuse(box) {
+    const detailZoom = source.detailZoom?.(box) ?? null;
+    return Boolean(
+      state.lastQueryBox &&
+      boxContains(state.lastQueryBox, box) &&
+      (state.lastQueryZoom == null ||
+        detailZoom == null ||
+        state.lastQueryZoom >= detailZoom - 1) &&
+      state.lastUpdate &&
+      Date.now() - state.lastUpdate < QUERY_REUSE_MS &&
+      !state.stale &&
+      state.status !== 'unavailable',
+    );
+  }
+
   function scheduleLoad() {
     if (!state.enabled) return;
     clearUnavailableRetry({ resetBackoff: false });
     clearTimeout(state.debounceTimer);
+    // A view the accepted tiles already cover is a local filter: show it now.
+    // Only a view that needs a request waits out the debounce.
+    const box = viewportBox(state.viewer);
+    if (box && canReuse(box)) {
+      state.debounceTimer = null;
+      loadCameras();
+      return;
+    }
     state.debounceTimer = setTimeout(() => {
       state.debounceTimer = null;
       loadCameras();
@@ -142,14 +176,9 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     // request still in flight was for a viewport the user has since left, so it
     // is aborted rather than allowed to replace the records that already cover
     // this view. Failed queries never replace the last successful box.
-    if (
-      state.lastQueryBox &&
-      boxContains(state.lastQueryBox, box) &&
-      state.lastUpdate &&
-      Date.now() - state.lastUpdate < QUERY_REUSE_MS &&
-      !state.stale &&
-      state.status !== 'unavailable'
-    ) {
+    // Reuse also needs the accepted records to be precise enough for this view:
+    // one zoom coarser than the view would pick is a few metres, never more.
+    if (canReuse(box)) {
       if (state.abort) {
         state.abort.abort();
         state.abort = null;
@@ -165,7 +194,8 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     }
     // A move inside an in-flight query must not abort and restart that query.
     if (state.abort && boxContains(state.pendingQueryBox, box)) {
-      renderRecords();
+      // The accepted records may cover only part of the new view. Re-filtering
+      // them during floor preparation creates an intermediate marker set.
       return;
     }
     const queryBox = snapAlprBox(box);
@@ -176,7 +206,8 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     state.loading = true;
     state.retrying = state.status === 'unavailable' || state.retryDelayMs > 0;
     setAlprStatus('loading');
-    renderRecords();
+    // Keep the current markers until the new view's records land, so a still
+    // camera sees one update instead of old records re-filtered, then new ones.
     try {
       const snapshot = await source.fetch(queryBox, requestAbort.signal);
       if (
@@ -185,16 +216,43 @@ export function createAlprCamerasLayer({ source, services } = {}) {
         !state.enabled
       )
         return;
+      if (snapshot.zoomIn) {
+        state.records = [];
+        state.recordById.clear();
+        state.noCoverage = false;
+        state.lastQueryBox = null;
+        state.lastQueryZoom = null;
+        clearUnavailableRetry();
+        renderRecords();
+        setAlprStatus('zoom-in');
+        return;
+      }
       const { records, stale, saturated } = validateAlprSnapshot(snapshot);
+      // Resolve marker floors (bounded wait, warm cells answer at once) so new
+      // markers are placed on the floor instead of clamped then moved.
+      await prepareFloors(records);
+      if (
+        requestAbort.signal.aborted ||
+        state.abort !== requestAbort ||
+        !state.enabled
+      )
+        return;
+      state.noCoverage = snapshot.noCoverage === true;
       state.records = records;
       state.recordById = new Map(records.map((r) => [r.id, r]));
       state.lastUpdate = Date.now();
       state.stale = stale;
-      // Saturated when the QUERY truncated OR the render cap would hide cameras:
-      // either way the view holds more than the screen shows, and the user must
-      // be told rather than left with a count that disagrees with the map.
-      state.saturated = saturated || records.length > MAX_RENDERED;
-      state.lastQueryBox = queryBox;
+      // Saturated when the QUERY truncated; the render cap is judged against
+      // the cameras in view (renderSaturated). Either way the row says so.
+      state.saturated = saturated;
+      // The fetched tiles cover more than the view: pans inside them are free.
+      state.lastQueryBox =
+        snapshot.coverage && boxContains(snapshot.coverage, queryBox)
+          ? snapshot.coverage
+          : queryBox;
+      state.lastQueryZoom = Number.isInteger(snapshot.zoom)
+        ? snapshot.zoom
+        : null;
       clearUnavailableRetry();
       // Stale and saturated are independent facts; a cached response that also
       // hit the cap must still warn about coverage, not just about freshness.
@@ -219,7 +277,7 @@ export function createAlprCamerasLayer({ source, services } = {}) {
         'unavailable',
         error?.message || 'Camera source temporarily unavailable',
       );
-      scheduleUnavailableRetry();
+      if (!isUnavailableCapability(error)) scheduleUnavailableRetry();
     } finally {
       if (state.abort === requestAbort) {
         state.abort = null;
@@ -282,6 +340,7 @@ export function createAlprCamerasLayer({ source, services } = {}) {
       return loadCameras();
     },
     destroy(viewer = state.viewer) {
+      source.destroy?.();
       this.disable();
       destroyOverlay();
       state.moveEndRemove?.();
@@ -299,6 +358,7 @@ export function createAlprCamerasLayer({ source, services } = {}) {
       state.records = [];
       state.recordById = new Map();
       state.lastQueryBox = null;
+      state.lastQueryZoom = null;
       state.lastUpdate = null;
       state.error = null;
       state.status = 'idle';
@@ -335,12 +395,21 @@ export function createAlprCamerasLayer({ source, services } = {}) {
     getStats() {
       return {
         count: state.dataSource?.entities.values.length || 0,
-        countLabel: state.enabled
-          ? `${state.dataSource?.entities.values.length || 0} nearby`
-          : '',
+        countLabel:
+          state.enabled && !state.noCoverage && state.status !== 'zoom-in'
+            ? `${state.dataSource?.entities.values.length || 0} nearby${
+                Number.isInteger(state.onScreen)
+                  ? ` · ${state.onScreen} on screen`
+                  : ''
+              }`
+            : '',
+        noCoverage: Boolean(state.noCoverage),
         lastUpdate: state.lastUpdate,
         stale: state.stale,
-        saturated: state.saturated,
+        saturated: state.saturated || state.renderSaturated,
+        renderRevision: state.renderRevision,
+        onScreen: state.onScreen ?? null,
+        shown: state.dataSource?.entities.values.length || 0,
         error: state.error,
         status: state.status,
         loading: state.loading,
@@ -353,17 +422,22 @@ export function createAlprCamerasLayer({ source, services } = {}) {
           ? state.retrying
             ? 'retrying mapped ALPR cameras'
             : 'loading mapped ALPR cameras'
-          : state.status === 'zoom-in'
-            ? 'Zoom in to load mapped cameras'
-            : [
-                state.stale ? 'Showing cached locations' : '',
-                state.saturated ? 'Coverage limited — zoom in' : '',
-                state.status === 'empty'
-                  ? 'No mapped cameras returned — coverage is incomplete'
-                  : '',
-              ]
-                .filter(Boolean)
-                .join(' · '),
+          : state.noCoverage
+            ? 'No ALPR data for this area — US and Canada only'
+            : state.status === 'zoom-in'
+              ? 'Zoom in to load mapped cameras'
+              : [
+                  state.stale ? 'Showing cached locations' : '',
+                  state.saturated || state.renderSaturated
+                    ? 'Coverage limited — zoom in'
+                    : '',
+                  state.status === 'empty' ? 'No ALPR data for this area' : '',
+                  state.status === 'ready' && state.onScreen === 0
+                    ? 'None on screen — nearby cameras are outside the view'
+                    : '',
+                ]
+                  .filter(Boolean)
+                  .join(' · '),
       };
     },
   };
@@ -384,4 +458,4 @@ export {
   QUERY_SNAP_DEGREES,
   QUERY_REUSE_MS,
 } from './policy.js';
-export { createOverpassAlprSource } from './source.js';
+export { createOverpassAlprSource, createAlprTileSource } from './source.js';

src/layers/alpr/overlay.js

@@ -3,18 +3,28 @@ import {
   MAX_CANVAS_FRUSTUMS,
   MARKER_ICON_SIZE,
   SELECTED_MARKER_ICON_SIZE,
+  MARKER_FLOOR_LIFT_M,
+  ANCHOR_SAMPLES_PER_PAINT,
+  SURFACE_BELOW_FLOOR_M,
+  SURFACE_ABOVE_FLOOR_M,
+  SURFACE_SAMPLES_PER_PAINT,
 } from './policy.js';
 import {
   MARKER_IMAGE,
   SELECTED_IMAGE,
   BRACKETS_IMAGE,
   directionWedgePositions,
+  markerScale,
   paintDirectionWedge,
   validAlprGroundHeight,
 } from './visuals.js';
 
 /** Per-layer presentation on a caller-owned overlay; Cesium remains the fallback. */
-export function createAlprOverlay({ state, services }) {
+export function createAlprOverlay({
+  state,
+  services,
+  onSurfaceChange = () => {},
+}) {
   let lane,
     removeMapListener,
     retryTimer,
@@ -22,14 +32,21 @@ export function createAlprOverlay({ state, services }) {
   let records = [],
     hits = [],
     images = [],
-    destroyed = false;
-  let surfaceRegime;
+    destroyed = false,
+    lastCamera = null;
   const requestPaint = () => {
     if (!destroyed && state.enabled) lane?.requestPaint();
   };
 
   function nativeVisible(entity, visible) {
     if (!entity) return;
+    canvasOwned(entity, !visible);
+    setShown(entity, visible);
+  }
+
+  /** Swap a marker between its native look and a faint canvas pick target. */
+  function canvasOwned(entity, owned) {
+    const visible = !owned;
     const billboard = entity.billboard;
     // Keep a faint native pick target under the canvas badge so sibling layer
     // handlers recognize ALPR ownership instead of treating the click as empty.
@@ -55,7 +72,15 @@ export function createAlprOverlay({ state, services }) {
       entity.gevAlprNativeAppearance = null;
       entity.gevAlprPickPosition = null;
     }
-    billboard.show = visible;
+  }
+
+  // Assign only on change: each Entity property write mints a new property
+  // and raises definitionChanged, which paint used to do for every overlay
+  // camera on every frame.
+  function setShown(entity, visible) {
+    if (entity.gevAlprShown === visible) return;
+    entity.gevAlprShown = visible;
+    entity.billboard.show = visible;
     if (entity.polyline) entity.polyline.show = visible;
     if (entity.polygon) entity.polygon.show = visible;
   }
@@ -72,15 +97,25 @@ export function createAlprOverlay({ state, services }) {
     requestPaint();
   }
 
-  function anchorFor(record, entity) {
+  function anchorFor(record, entity, budget) {
     if (entity.gevAlprCanvasPosition) return entity.gevAlprCanvasPosition;
     const scene = state.viewer.scene;
     const location = Cesium.Cartographic.fromDegrees(
       record.longitude,
       record.latitude,
     );
+    // A floor-placed marker anchors where its native badge sits; only a
+    // marker still waiting for its floor samples the rendered surface, and
+    // each paint samples a few at most (each sample is a depth render).
     let height;
-    if (scene.sampleHeightSupported) {
+    const floor = services.groundFloor.cachedGroundFloor(
+      record.latitude,
+      record.longitude,
+    );
+    if (validAlprGroundHeight(floor)) height = floor + MARKER_FLOOR_LIFT_M;
+    else if (scene.sampleHeightSupported) {
+      if (budget.samples <= 0) return null;
+      budget.samples -= 1;
       try {
         height = scene.sampleHeight(location, [entity]);
       } catch {
@@ -89,19 +124,107 @@ export function createAlprOverlay({ state, services }) {
     }
     if (!validAlprGroundHeight(height) && scene.globe.show)
       height = scene.globe.getHeight?.(location);
-    if (!validAlprGroundHeight(height))
-      height = services.groundFloor.cachedGroundFloor(
-        record.latitude,
-        record.longitude,
-      );
     if (!validAlprGroundHeight(height)) return null;
+    setAnchor(record, entity, height);
+    return entity.gevAlprCanvasPosition;
+  }
+
+  function floorHeightAt(latitude, longitude) {
+    const floor = services.groundFloor.cachedGroundFloor(latitude, longitude);
+    return validAlprGroundHeight(floor) ? floor + MARKER_FLOOR_LIFT_M : null;
+  }
+
+  function setAnchor(record, entity, height) {
     entity.gevAlprCanvasPosition = Cesium.Cartesian3.fromDegrees(
       record.longitude,
       record.latitude,
       height,
     );
-    entity.gevAlprWedge = directionWedgePositions(record, height);
-    return entity.gevAlprCanvasPosition;
+    entity.gevAlprWedge = directionWedgePositions(
+      record,
+      height,
+      floorHeightAt,
+    );
+  }
+
+  /** Whether the visible photoreal tiles (or globe) have finished streaming. */
+  function surfaceSettled(scene) {
+    if (scene.globe?.show) return scene.globe.tilesLoaded !== false;
+    for (let i = 0; i < (scene.primitives?.length || 0); i++) {
+      const primitive = scene.primitives.get(i);
+      if (primitive?.show && primitive.tilesLoaded === false) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Replace floor anchors with the rendered surface under each overlay camera.
+   * Floors come from ~111 m cells, so on a slope a badge could float or sink
+   * by tens of metres. Runs only while the camera is still and tiles have
+   * settled, a few depth samples per paint, and each anchor at most once;
+   * samples far outside the floor prior (a roof or a streaming tile) are
+   * rejected. Returns whether anchors remain to check.
+   */
+  function refineAnchors(budget) {
+    const camera = state.viewer.camera;
+    const scene = state.viewer.scene;
+    const still =
+      lastCamera &&
+      camera.positionWC &&
+      Cesium.Cartesian3.equalsEpsilon(
+        camera.positionWC,
+        lastCamera.position,
+        0,
+        0.05,
+      ) &&
+      Cesium.Cartesian3.equalsEpsilon(
+        camera.directionWC,
+        lastCamera.direction,
+        0,
+        1e-6,
+      );
+    if (camera.positionWC && camera.directionWC)
+      lastCamera = {
+        position: Cesium.Cartesian3.clone(camera.positionWC),
+        direction: Cesium.Cartesian3.clone(camera.directionWC),
+      };
+    if (!scene.sampleHeightSupported) return false;
+    let pending = false;
+    for (const record of records) {
+      const entity = state.dataSource.entities.getById(record.id);
+      const anchor = entity?.gevAlprCanvasPosition;
+      if (!anchor || entity.gevAlprSurfaceCheckedFor === anchor) continue;
+      if (!still || !surfaceSettled(scene) || budget.samples <= 0) {
+        pending = true;
+        continue;
+      }
+      budget.samples -= 1;
+      let sample;
+      try {
+        sample = scene.sampleHeight(
+          Cesium.Cartographic.fromDegrees(record.longitude, record.latitude),
+          [entity],
+        );
+      } catch {
+        /* streaming tiles */
+      }
+      const current = Cesium.Cartographic.fromCartesian(anchor).height;
+      const floor = services.groundFloor.cachedGroundFloor(
+        record.latitude,
+        record.longitude,
+      );
+      const accepted =
+        validAlprGroundHeight(sample) &&
+        (!validAlprGroundHeight(floor) ||
+          (sample >= floor - SURFACE_BELOW_FLOOR_M &&
+            sample <= floor + SURFACE_ABOVE_FLOOR_M));
+      if (accepted && Math.abs(sample + MARKER_FLOOR_LIFT_M - current) > 1)
+        setAnchor(record, entity, sample + MARKER_FLOOR_LIFT_M);
+      entity.gevAlprSurfaceCheckedFor = entity.gevAlprCanvasPosition;
+      if (entity.id === state.selectedId)
+        entity.gevAlprDisplayPosition = entity.gevAlprCanvasPosition;
+    }
+    return pending;
   }
 
   function paint({ ctx, width, height, keyhole, occluder }) {
@@ -109,6 +232,7 @@ export function createAlprOverlay({ state, services }) {
     if (!state.enabled || destroyed) return;
     let unresolved = false;
     const painted = [];
+    const budget = { samples: ANCHOR_SAMPLES_PER_PAINT };
     for (const record of records) {
       const entity = state.dataSource.entities.getById(record.id);
       if (!entity) continue;
@@ -122,23 +246,32 @@ export function createAlprOverlay({ state, services }) {
         nativeVisible(entity, true);
         continue;
       }
-      const anchor = anchorFor(record, entity);
+      const anchor = anchorFor(record, entity, budget);
       if (!anchor) {
         nativeVisible(entity, true);
         unresolved = true;
         continue;
       }
-      nativeVisible(entity, false);
-      if (occluder && !occluder.isPointVisible(anchor)) continue;
+      canvasOwned(entity, true);
+      if (occluder && !occluder.isPointVisible(anchor)) {
+        setShown(entity, false);
+        continue;
+      }
       const scene = state.viewer.scene;
       const origin = Cesium.SceneTransforms.worldToWindowCoordinates(
         scene,
         anchor,
       );
-      if (!origin) continue;
+      if (!origin) {
+        setShown(entity, false);
+        continue;
+      }
       const alpha =
         services.overlays.keyholeAlpha?.(origin.x, origin.y, keyhole) ?? 1;
-      if (!(alpha > 0)) continue;
+      if (!(alpha > 0)) {
+        setShown(entity, false);
+        continue;
+      }
       const wedge = entity.gevAlprWedge;
       if (wedge) {
         const left = Cesium.SceneTransforms.worldToWindowCoordinates(
@@ -161,15 +294,27 @@ export function createAlprOverlay({ state, services }) {
         origin.x > width + 60 ||
         origin.y < -60 ||
         origin.y > height + 60
-      )
+      ) {
+        setShown(entity, false);
         continue;
-      entity.billboard.show = true;
-      painted.push({ record, origin, selected, image, alpha });
+      }
+      setShown(entity, true);
+      painted.push({
+        record,
+        origin,
+        selected,
+        image,
+        alpha,
+        scale: markerScale(
+          Cesium.Cartesian3.distance(state.viewer.camera.positionWC, anchor),
+        ),
+      });
       if (selected) entity.gevAlprDisplayPosition = anchor;
     }
     // Paint all glyphs after the wedges so one camera's cone cannot wash out another.
-    for (const { record, origin, selected, image, alpha } of painted) {
-      const size = selected ? SELECTED_MARKER_ICON_SIZE : MARKER_ICON_SIZE;
+    for (const { record, origin, selected, image, alpha, scale } of painted) {
+      const size =
+        (selected ? SELECTED_MARKER_ICON_SIZE : MARKER_ICON_SIZE) * scale;
       ctx.save();
       ctx.globalAlpha *= alpha;
       ctx.drawImage(
@@ -190,7 +335,10 @@ export function createAlprOverlay({ state, services }) {
       ctx.restore();
       hits.push({ id: record.id, x: origin.x, y: origin.y, radius: size / 2 });
     }
-    if (unresolved && !retryTimer && Date.now() < retryUntil) {
+    const refining = refineAnchors({
+      samples: Math.min(budget.samples, SURFACE_SAMPLES_PER_PAINT),
+    });
+    if ((unresolved || refining) && !retryTimer && Date.now() < retryUntil) {
       retryTimer = setTimeout(() => {
         retryTimer = null;
         requestPaint();
@@ -201,6 +349,12 @@ export function createAlprOverlay({ state, services }) {
   return {
     init() {
       destroyed = false;
+      removeMapListener = services.overlays?.subscribeMapStack?.((event) => {
+        if (event.detail?.status !== 'ready' || !state.enabled) return;
+        // Same-regime provider changes also invalidate absolute placements.
+        onSurfaceChange();
+        resetAnchors();
+      });
       if (!services.overlays?.registerPaintLane || typeof Image === 'undefined')
         return;
       lane = services.overlays.registerPaintLane('selected', paint, {
@@ -214,14 +368,6 @@ export function createAlprOverlay({ state, services }) {
         image.src = src;
         return image;
       });
-      surfaceRegime = state.viewer.scene.globe.show;
-      removeMapListener = services.overlays.subscribeMapStack?.((event) => {
-        if (event.detail?.status !== 'ready') return;
-        const next = state.viewer.scene.globe.show;
-        if (next === surfaceRegime) return;
-        surfaceRegime = next;
-        resetAnchors();
-      });
     },
     sync(visible) {
       if (!lane) return;

src/layers/alpr/overlay.test.mjs

@@ -2,9 +2,13 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import * as Cesium from 'cesium';
 import { createAlprOverlay } from './overlay.js';
-import { directionWedgePositions, alprLabelDetails } from './visuals.js';
+import {
+  directionWedgePositions,
+  alprLabelDetails,
+  markerScale,
+} from './visuals.js';
 
-function harness(t, count = 2) {
+function harness(t, count = 2, { floor = null } = {}) {
   const previousImage = globalThis.Image;
   const project = Cesium.SceneTransforms.worldToWindowCoordinates;
   globalThis.Image = class {
@@ -43,7 +47,7 @@ function harness(t, count = 2) {
   const overlay = createAlprOverlay({
     state,
     services: {
-      groundFloor: { cachedGroundFloor: () => null },
+      groundFloor: { cachedGroundFloor: () => floor },
       overlays: {
         registerPaintLane(_lane, painter) {
           paint = painter;
@@ -190,6 +194,20 @@ test('an unresolved surface preserves the native marker; the horizon removes ove
   assert.equal(h.draw.length, 0);
 });
 
+test('repeated paints of a still view never rewrite marker properties', (t) => {
+  // Each Entity write raises definitionChanged; paint used to hide then show
+  // every overlay camera's native marker on every frame.
+  const h = harness(t, 3);
+  h.overlay.sync(h.records);
+  h.paint();
+  let changes = 0;
+  for (const entity of h.entities.values)
+    entity.definitionChanged.addEventListener(() => changes++);
+  for (let i = 0; i < 5; i++) h.paint();
+  assert.equal(changes, 0);
+  assert.equal(h.entities.getById('camera:0').billboard.show.getValue(), true);
+});
+
 test('adapter labels never claim a custom source is public OSM data', () => {
   assert.deepEqual(
     alprLabelDetails(
@@ -199,3 +217,49 @@ test('adapter labels never claim a custom source is public OSM data', () => {
     ['Source: Custom directory', 'VENDOR'],
   );
 });
+
+test('overlay glyphs and native badges shrink alike with distance', () => {
+  assert.equal(markerScale(100), 1.15);
+  assert.equal(markerScale(40_000), 0.45);
+  assert.equal(markerScale(90_000), 0.45);
+  assert.ok(Math.abs(markerScale(20_250) - 0.8) < 1e-9);
+});
+
+test('a still view replaces floor anchors with the rendered surface, within the floor window', (t) => {
+  // Floors come from ~111 m cells; on a slope a badge floated above the mesh.
+  const h = harness(t, 2, { floor: 150 });
+  const scene = h.state.viewer.scene;
+  const camera = h.state.viewer.camera;
+  camera.directionWC = Cesium.Cartesian3.UNIT_X;
+  scene.sampleHeightSupported = true;
+  scene.primitives = { length: 0, get: () => null };
+  let samples = 0;
+  scene.sampleHeight = (carto) => {
+    samples++;
+    return Cesium.Math.toDegrees(carto.latitude) > 30.00005 ? 400 : 172;
+  };
+  h.overlay.sync(h.records);
+  h.paint();
+  const height = (id) =>
+    Cesium.Cartographic.fromCartesian(
+      h.entities.getById(id).gevAlprCanvasPosition,
+    ).height;
+  assert.equal(
+    samples,
+    0,
+    'no depth samples while the camera may still be moving',
+  );
+  assert.ok(Math.abs(height('camera:0') - 151.5) < 0.01, 'floor anchor first');
+  h.paint();
+  assert.ok(
+    Math.abs(height('camera:0') - 173.5) < 0.01,
+    'rendered surface once still',
+  );
+  assert.ok(
+    Math.abs(height('camera:1') - 151.5) < 0.01,
+    'a rooftop-height sample is rejected',
+  );
+  const taken = samples;
+  h.paint();
+  assert.equal(samples, taken, 'each anchor is checked once');
+});

src/layers/alpr/policy.js

@@ -1,33 +1,37 @@
 /**
- * @file Community-mapped automatic license plate reader (ALPR) camera layer.
- *
- * Data source: OpenStreetMap contributors, including the DeFlock community
- * (`man_made=surveillance` + `surveillance:type=ALPR`) — see
- * https://wiki.openstreetmap.org/wiki/Tag:surveillance:type=ALPR and
- * https://deflock.org. OSM data remains ODbL 1.0, separate from the MIT code.
- * Fetched viewport-bounded through the existing generic
- * `/api/overpass` proxy (same one `traffic.js` and `militaryInstallations.js`
- * use) — no new server route needed for a single narrow tag pair.
- *
- * This is mapped surveillance infrastructure, not a live camera feed: no
- * plate records, no vendor accounts, nothing beyond what a contributor chose
- * to publish to OSM. Coverage and tag accuracy are not guaranteed.
- *
- * @module data/alprCameras
+ * Community-mapped OpenStreetMap ALPR locations, via hourly US/Canada detail
+ * tiles. OSM data remains ODbL, separate from the application code. These are
+ * mapped locations, not footage, plate records or evidence of current activity.
  */
 
 export const LAYER_ID = 'alpr-cameras';
 
 export const OVERPASS_URL = '/api/overpass';
 
-export const REQUEST_DEBOUNCE_MS = 500;
+export const REQUEST_DEBOUNCE_MS = 300;
 
-/** Keep public Overpass queries city-scale, never globe-wide. */
+/** Keep camera acquisition city-scale, never globe-wide. */
 export const MAX_VIEWPORT_DEGREES = 3;
 
-/** Overpass `out body N;` cap — also detects possibly truncated coverage. */
+/** Camera record cap; reaching it reports limited coverage. */
 export const QUERY_LIMIT = 1500;
 
+/**
+ * The extract carries full camera attributes from z9 (z0-8 are geometry-only
+ * heat tiles). Each view uses the finest zoom from z12 down to z9 that fits
+ * DETAIL_MAX_TILES, so a whole city loads from a few z9/z10 tiles and a
+ * neighbourhood from z12 (about 2 m position precision).
+ */
+export const DETAIL_MIN_ZOOM = 9;
+export const DETAIL_MAX_ZOOM = 12;
+export const DETAIL_MAX_TILES = 16;
+
+/** Decoded records kept per accepted tile coverage (memory bound, not a render cap). */
+export const SOURCE_RECORD_LIMIT = 6000;
+
+/** Best-precision coordinates remembered per camera across zoom changes. */
+export const PRECISION_CACHE_LIMIT = 20000;
+
 /** Render cap. Kept at or above QUERY_LIMIT on purpose: if it ever sat below
  * it, cameras between the two would be silently dropped while `saturated`
  * stayed false and `count` still reported them — a lie about coverage. */
@@ -40,20 +44,37 @@ export const DIRECTION_CONE_HALF_ANGLE_DEG = 20;
 export const EARTH_MEAN_RADIUS_M = 6371008.8;
 
 /** Query boxes are snapped outward to this grid so nearby camera moves reuse
- * one Overpass request body (the shared proxy keys its cache and in-flight
- * dedupe by the exact body) instead of each becoming a distinct upstream fetch. */
+ * one accepted viewport snapshot rather than rebuilding records on every pan. */
 export const QUERY_SNAP_DEGREES = 0.05;
 
 /** A view still fully inside the last snapped query box reuses those records
- * for this long before asking Overpass again. */
+ * for this long before selecting tiles again. */
 export const QUERY_REUSE_MS = 10 * 60 * 1000;
 
 /** Vendor-neutral camera badge palette, with coral selection. */
 export const ALPR_COLOR = '#52d4ff';
 export const ALPR_SELECTED_COLOR = '#ff6474';
 export const MARKER_ICON_SIZE = 38;
+/** Badge scale by camera distance (near m, scale, far m, scale), shared by
+ * native badges and overlay glyphs so both shrink alike in city-wide views. */
+export const MARKER_SCALE_BY_DISTANCE = Object.freeze([
+  500, 1.15, 40_000, 0.45,
+]);
 export const SELECTED_MARKER_ICON_SIZE = 60;
 export const MAX_CANVAS_FRUSTUMS = 64;
 
+/** Metres a floor-placed marker sits above its resolved ground cell. */
+export const MARKER_FLOOR_LIFT_M = 1.5;
+
+/** Rendered-surface samples one overlay paint may take (each is a depth render). */
+export const ANCHOR_SAMPLES_PER_PAINT = 4;
+
+/** Accepted rendered-surface window around a floor cell (a cut or an embankment
+ * sits within it; a rooftop or an unstreamed tile usually does not). */
+export const SURFACE_BELOW_FLOOR_M = 30;
+/** Rendered-surface refinements per paint while the camera is still. */
+export const SURFACE_SAMPLES_PER_PAINT = 2;
+export const SURFACE_ABOVE_FLOOR_M = 40;
+
 /** OSM attribution may collapse after five seconds; full credit stays in Data attribution. */
 export const CREDIT_DISPLAY_MS = 5000;

src/layers/alpr/presentation.js

@@ -9,15 +9,17 @@ import {
   MARKER_ICON_SIZE,
   SELECTED_MARKER_ICON_SIZE,
   CREDIT_DISPLAY_MS,
+  MARKER_FLOOR_LIFT_M,
+  MARKER_SCALE_BY_DISTANCE,
 } from './policy.js';
 import { boxContains } from './model.js';
+import { createAlprFloorResolver } from './floors.js';
 import { createAlprOverlay } from './overlay.js';
 import {
   MARKER_IMAGE,
   SELECTED_IMAGE,
   alprDisplayId,
   alprLabelDetails,
-  directionWedgePositions,
   validAlprGroundHeight,
 } from './visuals.js';
 
@@ -32,9 +34,198 @@ export function createAlprPresentation({ state, services, source }) {
   } = services.context;
 
   const { cachedGroundFloor } = services.groundFloor;
-  const overlay = createAlprOverlay({ state, services });
+  const overlay = createAlprOverlay({
+    state,
+    services,
+    onSurfaceChange: refreshMarkerPlacements,
+  });
   let visibleRecords = [];
   let selectionStartedAt = 0;
+  /** Markers still clamped while their floor cell resolves (id -> entity). */
+  const clampedMarkers = new Map();
+  let floorResolve = null;
+  const floors = createAlprFloorResolver(services.groundFloor);
+
+  /**
+   * Marker placement from the cached ground floor (validated mesh or DEM, the
+   * ellipsoidal datum every layer shares). Ground clamping on photoreal tiles
+   * re-samples every clamped marker whenever a tile streams in, which made a
+   * whole-city view stutter while zooming, so it is only the placeholder for
+   * a cell that has not resolved yet.
+   * @param {{latitude:number, longitude:number}} record Camera.
+   * @returns {{position: Cesium.Cartesian3, clamped: boolean}} Placement.
+   */
+  function markerPlacement(record) {
+    const floor = cachedGroundFloor(record.latitude, record.longitude);
+    const clamped = !validAlprGroundHeight(floor);
+    return {
+      clamped,
+      position: Cesium.Cartesian3.fromDegrees(
+        record.longitude,
+        record.latitude,
+        clamped ? 0 : floor + MARKER_FLOOR_LIFT_M,
+      ),
+    };
+  }
+
+  /** Records the current view would display (viewport box, nearest first when capped). */
+  function viewRecords(records) {
+    const box = viewportBox(state.viewer);
+    if (!box) return { box, visible: [], capped: false };
+    let visible = records.filter((record) =>
+      boxContains(box, {
+        south: record.latitude,
+        north: record.latitude,
+        west: record.longitude,
+        east: record.longitude,
+      }),
+    );
+    const capped = visible.length > MAX_RENDERED;
+    if (capped) {
+      const lat = (box.south + box.north) / 2;
+      const lon = (box.west + box.east) / 2;
+      const scale = Math.cos((lat * Math.PI) / 180);
+      const distance = (record) =>
+        (record.latitude - lat) ** 2 + ((record.longitude - lon) * scale) ** 2;
+      visible = visible
+        .map((record) => ({ record, d: distance(record) }))
+        .sort((a, b) => a.d - b.d)
+        .slice(0, MAX_RENDERED)
+        .map((item) => item.record);
+    }
+    return { box, visible, capped };
+  }
+
+  /**
+   * Resolve the floor cells of the records this view will display, waiting at
+   * most the ground service's bounded deadline. Never throws.
+   * @param {Array<object>} records Candidate records.
+   * @returns {Promise<void>}
+   */
+  async function prepareFloors(records) {
+    const resolve = services.groundFloor.resolveGroundFloorCells;
+    if (typeof resolve !== 'function') return;
+    const cold = viewRecords(records)
+      .visible.filter(
+        (record) =>
+          !validAlprGroundHeight(
+            cachedGroundFloor(record.latitude, record.longitude),
+          ),
+      )
+      .map((record) => ({ lat: record.latitude, lon: record.longitude }));
+    if (!cold.length) return;
+    try {
+      await floors.prepare(cold);
+    } catch {
+      /* markers fall back to clamping until their floors resolve */
+    }
+  }
+
+  /**
+   * Loaded cameras that project inside the canvas and in front of the globe.
+   * "Nearby" spans twice the camera-to-ground range, so a view can hold
+   * cameras while none is on screen; the row then says so rather than
+   * leaving the user to wait for markers. Runs once per render pass.
+   * @returns {number|null} Count, or null without a scene to project into.
+   */
+  function countOnScreen() {
+    const scene = state.viewer?.scene;
+    const canvas = scene?.canvas;
+    const width = canvas?.clientWidth || canvas?.width;
+    const height = canvas?.clientHeight || canvas?.height;
+    const camera = state.viewer?.camera;
+    if (!scene || !width || !height || !camera?.positionWC) return null;
+    const occluder = new Cesium.EllipsoidalOccluder(
+      Cesium.Ellipsoid.WGS84,
+      camera.positionWC,
+    );
+    let count = 0;
+    try {
+      for (const entity of state.dataSource.entities.values) {
+        const position = entity.position?.getValue?.(Cesium.JulianDate.now());
+        if (!position || !occluder.isPointVisible(position)) continue;
+        const point = Cesium.SceneTransforms.worldToWindowCoordinates(
+          scene,
+          position,
+        );
+        if (
+          point &&
+          point.x >= 0 &&
+          point.x <= width &&
+          point.y >= 0 &&
+          point.y <= height
+        )
+          count += 1;
+      }
+    } catch {
+      // A scene without a usable frame (startup, teardown) cannot answer.
+      return null;
+    }
+    return count;
+  }
+
+  /** Write a marker position, respecting the overlay's pick-target swap. */
+  function setMarkerPosition(entity, position, clamped) {
+    const heightReference = clamped
+      ? Cesium.HeightReference.CLAMP_TO_GROUND
+      : Cesium.HeightReference.NONE;
+    const saved = entity.gevAlprNativeAppearance;
+    if (saved) {
+      saved.position = position;
+      saved.heightReference = heightReference;
+    } else {
+      entity.position = position;
+      entity.billboard.heightReference = heightReference;
+    }
+    entity.gevAlprClamped = clamped;
+  }
+
+  /** Refresh all native placements, including the appearances held by the canvas. */
+  function refreshMarkerPlacements() {
+    if (!state.enabled || !state.dataSource) return;
+    clampedMarkers.clear();
+    for (const entity of state.dataSource.entities.values) {
+      const { position, clamped } = markerPlacement(entity.gevAlprRecord);
+      setMarkerPosition(entity, position, clamped);
+      if (clamped) clampedMarkers.set(entity.id, entity);
+    }
+    resolveClampedFloors();
+    governorRequestRender('alpr-surface');
+  }
+
+  /** Resolve floors for clamped markers once, then place them in place. */
+  function resolveClampedFloors() {
+    const resolve = services.groundFloor.resolveGroundFloorCells;
+    if (floorResolve || !clampedMarkers.size || typeof resolve !== 'function')
+      return;
+    const batch = [...clampedMarkers.values()];
+    const request = Promise.resolve(
+      floors.resolve(
+        batch.map((entity) => ({
+          lat: entity.gevAlprRecord.latitude,
+          lon: entity.gevAlprRecord.longitude,
+        })),
+      ),
+    )
+      .catch(() => {})
+      .then(() => {
+        if (floorResolve !== request) return;
+        floorResolve = null;
+        if (!state.enabled || !state.dataSource) return;
+        let moved = false;
+        for (const entity of batch) {
+          if (clampedMarkers.get(entity.id) !== entity) continue;
+          clampedMarkers.delete(entity.id);
+          const { position, clamped } = markerPlacement(entity.gevAlprRecord);
+          if (clamped) continue;
+          setMarkerPosition(entity, position, false);
+          moved = true;
+        }
+        if (moved) governorRequestRender('alpr-floor');
+        // Cells that never resolved stay clamped; later renders retry them.
+      });
+    floorResolve = request;
+  }
 
   function updateAppearance(entity, selected) {
     const color = Cesium.Color.fromCssColorString(
@@ -44,12 +235,6 @@ export function createAlprPresentation({ state, services, source }) {
     entity.billboard.width = entity.billboard.height = selected
       ? SELECTED_MARKER_ICON_SIZE
       : MARKER_ICON_SIZE;
-    if (entity.polyline) {
-      entity.polyline.width = selected ? 3 : 1.75;
-      entity.polyline.material = color.withAlpha(selected ? 0.98 : 0.82);
-    }
-    if (entity.polygon)
-      entity.polygon.material = color.withAlpha(selected ? 0.8 : 0.2);
     if (entity.gevLabelModel) {
       entity.gevLabelModel.accent = color.toCssColorString();
       entity.gevLabelModel.leaderAnimationStartedAt = selected
@@ -118,13 +303,18 @@ export function createAlprPresentation({ state, services, source }) {
   }
 
   function clearRendered() {
+    hideOnMapCredit();
+    floors.cancel();
+    floorResolve = null;
     overlay.clear();
     visibleRecords = [];
+    clampedMarkers.clear();
     if (state.dataSource?.entities) state.dataSource.entities.removeAll();
     removeEntityContextsForLayer(LAYER_ID);
   }
 
   function hideOnMapCredit() {
+    services.credits?.hideOsmCredit?.(state.viewer, LAYER_ID);
     clearTimeout(state.creditTimer);
     state.creditTimer = null;
     if (state.credit)
@@ -133,6 +323,14 @@ export function createAlprPresentation({ state, services, source }) {
   }
 
   function presentOnMapCredit() {
+    if (
+      state.enabled &&
+      source.attribution?.name === 'OpenStreetMap' &&
+      services.credits?.showOsmCredit
+    ) {
+      services.credits.showOsmCredit(state.viewer, LAYER_ID);
+      return;
+    }
     if (!state.enabled || state.creditPresented || !state.credit) return;
     state.creditPresented = true;
     state.viewer.creditDisplay?.addStaticCredit(state.credit);
@@ -142,19 +340,10 @@ export function createAlprPresentation({ state, services, source }) {
 
   function renderRecords() {
     const selectedContext = getSelectedEntityContext();
-    const box = viewportBox(state.viewer);
-    const visible = box
-      ? state.records
-          .filter((record) =>
-            boxContains(box, {
-              south: record.latitude,
-              north: record.latitude,
-              west: record.longitude,
-              east: record.longitude,
-            }),
-          )
-          .slice(0, MAX_RENDERED)
-      : [];
+    // Over the render cap, keep the cameras nearest the view centre and say
+    // coverage is limited rather than dropping an arbitrary subset.
+    const { visible, capped } = viewRecords(state.records);
+    state.renderSaturated = capped;
     visibleRecords = visible;
     // A refresh may retain its own selection, never reclaim one cleared or
     // replaced by an aircraft, another layer, or a voice action.
@@ -168,8 +357,14 @@ export function createAlprPresentation({ state, services, source }) {
     }
     governorRequestRender('alpr-render');
     const visibleIds = new Set(visible.map((record) => record.id));
+    let changed = false;
+    state.dataSource.entities.suspendEvents();
     for (const entity of [...state.dataSource.entities.values]) {
-      if (!visibleIds.has(entity.id)) state.dataSource.entities.remove(entity);
+      if (!visibleIds.has(entity.id)) {
+        state.dataSource.entities.remove(entity);
+        clampedMarkers.delete(entity.id);
+        changed = true;
+      }
     }
     removeEntityContextsForLayer(LAYER_ID, { retainIds: visibleIds });
     for (const record of visible) {
@@ -180,10 +375,11 @@ export function createAlprPresentation({ state, services, source }) {
       }
       const color = markerColor();
       const selected = record.id === state.selectedId;
-      const position = Cesium.Cartesian3.fromDegrees(
-        record.longitude,
-        record.latitude,
-      );
+      const { position, clamped } = markerPlacement(record);
+      // Direction wedges are painted by the overlay for the nearest cameras.
+      // Native ground-clamped wedges (a ground polyline plus a classification
+      // polygon per camera) cost ~40 ms per frame for 200 downtown cameras on
+      // photoreal tiles, so markers stay billboards only.
       const entityDef = {
         id: record.id,
         position,
@@ -191,38 +387,30 @@ export function createAlprPresentation({ state, services, source }) {
           image: selected ? SELECTED_IMAGE : MARKER_IMAGE,
           width: selected ? SELECTED_MARKER_ICON_SIZE : MARKER_ICON_SIZE,
           height: selected ? SELECTED_MARKER_ICON_SIZE : MARKER_ICON_SIZE,
-          heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
+          heightReference: clamped
+            ? Cesium.HeightReference.CLAMP_TO_GROUND
+            : Cesium.HeightReference.NONE,
           disableDepthTestDistance: Number.POSITIVE_INFINITY,
-          scaleByDistance: new Cesium.NearFarScalar(350, 1.15, 4_000_000, 0.48),
+          // City-wide views hold hundreds of badges; let them shrink.
+          scaleByDistance: new Cesium.NearFarScalar(
+            ...MARKER_SCALE_BY_DISTANCE,
+          ),
         },
       };
-      const wedge = directionWedgePositions(record);
-      if (wedge) {
-        entityDef.polyline = {
-          positions: [wedge[1], position, wedge[2]],
-          width: selected ? 3 : 1.75,
-          material: color.withAlpha(0.82),
-          clampToGround: true,
-        };
-        entityDef.polygon = {
-          hierarchy: wedge,
-          material: color.withAlpha(0.2),
-          height: 0,
-          heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
-          classificationType: Cesium.ClassificationType.BOTH,
-        };
-      }
       let entity = existing;
       // Keep the Cesium entity and its ground-clamping subscription while its
       // geometry is unchanged. Updating metadata must not rebuild the marker.
       const previous = entity?.gevAlprRecord;
-      if (!entity) entity = state.dataSource.entities.add(entityDef);
-      else {
+      if (!entity) {
+        entity = state.dataSource.entities.add(entityDef);
+        entity.gevAlprClamped = clamped;
+        changed = true;
+      } else {
         if (
           previous.latitude !== record.latitude ||
           previous.longitude !== record.longitude
         ) {
-          entity.position = position;
+          setMarkerPosition(entity, position, clamped);
           entity.gevAlprCanvasPosition = null;
           entity.gevAlprDisplayPosition = null;
         }
@@ -231,8 +419,6 @@ export function createAlprPresentation({ state, services, source }) {
           previous.longitude !== record.longitude ||
           previous.directionDeg !== record.directionDeg
         ) {
-          entity.polyline = entityDef.polyline;
-          entity.polygon = entityDef.polygon;
           entity.gevAlprCanvasPosition = null;
           entity.gevAlprWedge = null;
         }
@@ -281,6 +467,12 @@ export function createAlprPresentation({ state, services, source }) {
         },
       });
     }
+    state.dataSource.entities.resumeEvents();
+    if (changed) state.renderRevision += 1;
+    state.onScreen = countOnScreen();
+    for (const entity of state.dataSource.entities.values)
+      if (entity.gevAlprClamped) clampedMarkers.set(entity.id, entity);
+    resolveClampedFloors();
     const selectedEntity = state.selectedId
       ? state.dataSource.entities.getById(state.selectedId)
       : null;
@@ -288,9 +480,9 @@ export function createAlprPresentation({ state, services, source }) {
     updateSelectedAnchor();
     overlay.sync(visible);
     if (selectedEntity) services.overlays?.refreshReadout?.(selectedEntity);
-    // Start only when mapped data is actually displayed, not while an upstream
-    // request or a zoom-in prompt could consume the five-second introduction.
+    // Keep the on-map credit tied to displayed data, not loading or zoom prompts.
     if (visible.length) presentOnMapCredit();
+    else hideOnMapCredit();
   }
 
   function focusNearest() {
@@ -458,5 +650,6 @@ export function createAlprPresentation({ state, services, source }) {
     clearSelection,
     updateSelectedAnchor,
     installInteraction,
+    prepareFloors,
   };
 }

src/layers/alpr/source.js

@@ -1,10 +1,199 @@
+import { tilesForBounds, tileToBBox } from '../../data/tomtomTiles.js';
 import {
   OVERPASS_URL,
+  QUERY_LIMIT,
   MAX_VIEWPORT_DEGREES,
   QUERY_SNAP_DEGREES,
-  QUERY_LIMIT,
+  DETAIL_MIN_ZOOM,
+  DETAIL_MAX_ZOOM,
+  DETAIL_MAX_TILES,
+  SOURCE_RECORD_LIMIT,
+  PRECISION_CACHE_LIMIT,
 } from './policy.js';
+import {
+  createVectorTileSource,
+  validTileBounds,
+} from '../../sources/vectorTiles.js';
 import { buildOverpassQuery, normalizeAlprNode } from './records.js';
+import { decodeAlprTile } from './tileRecords.js';
+
+/**
+ * Finest attributed extract zoom whose tiles for `box` fit the per-view cap,
+ * or null when even z9 would not (the layer asks the user to zoom in).
+ * @param {{south:number, west:number, north:number, east:number}} box View box.
+ * @returns {number|null} Tile zoom.
+ */
+export function alprDetailZoom(box) {
+  for (let zoom = DETAIL_MAX_ZOOM; zoom >= DETAIL_MIN_ZOOM; zoom--)
+    if (
+      tilesForBounds(box, zoom, { maxTiles: DETAIL_MAX_TILES + 1 }).length <=
+      DETAIL_MAX_TILES
+    )
+      return zoom;
+  return null;
+}
+
+/**
+ * Tile coordinates are quantized per zoom (about 19 m at z9, 2 m at z12).
+ * Remember each camera's finest position so zooming out never nudges a marker
+ * that a closer view already placed precisely. Bounded, oldest first.
+ * @param {number} [limit] Cameras remembered.
+ * @returns {{apply: (record: object, zoom: number) => object, clear: () => void,
+ *   size: () => number}} Cache.
+ */
+export function createAlprPrecisionCache(limit = PRECISION_CACHE_LIMIT) {
+  const known = new Map();
+  return {
+    apply(record, zoom) {
+      const finer = known.get(record.id);
+      if (finer && finer.zoom > zoom)
+        return finer.latitude === record.latitude &&
+          finer.longitude === record.longitude
+          ? record
+          : { ...record, latitude: finer.latitude, longitude: finer.longitude };
+      known.delete(record.id);
+      known.set(record.id, {
+        zoom,
+        latitude: record.latitude,
+        longitude: record.longitude,
+      });
+      while (known.size > limit) known.delete(known.keys().next().value);
+      return record;
+    },
+    clear: () => known.clear(),
+    size: () => known.size,
+  };
+}
+
+/** Construct the viewport-bounded OpenStreetMap hourly extract adapter. */
+export function createAlprTileSource({
+  tileFetchImpl = (...args) => globalThis.fetch(...args),
+} = {}) {
+  const sources = ['us', 'ca'].map((country) =>
+    createVectorTileSource({
+      tileJsonUrl: `https://tiles.dontgetflocked.com/cameras-${country}-hourly.json`,
+      allowedOrigin: 'https://tiles.dontgetflocked.com',
+      decode: decodeAlprTile,
+      fetchImpl: tileFetchImpl,
+      maxTiles: DETAIL_MAX_TILES,
+      ttlMs: 60 * 60 * 1000,
+    }),
+  );
+  const precision = createAlprPrecisionCache();
+  const precise = precision.apply;
+  return {
+    /**
+     * Read the camera records for every extract tile covering `box`.
+     * @param {{south:number, west:number, north:number, east:number}} box View box.
+     * @param {AbortSignal} [signal] Cancellation.
+     * @returns {Promise<{records: Array<object>, stale: boolean, saturated: boolean,
+     *   noCoverage?: boolean, zoomIn?: boolean, coverage?: object, zoom?: number}>}
+     *   Records inside the fetched tiles; `coverage` is those tiles' bounds.
+     */
+    async fetch(box, signal) {
+      if (
+        !validTileBounds(box) ||
+        box.north - box.south >
+          MAX_VIEWPORT_DEGREES + 2 * QUERY_SNAP_DEGREES + 1e-9 ||
+        box.east - box.west >
+          MAX_VIEWPORT_DEGREES + 2 * QUERY_SNAP_DEGREES + 1e-9
+      )
+        throw new TypeError('ALPR requires a bounded city viewport');
+      signal?.throwIfAborted();
+      // Fast geographic rejection; the exact extract extents below refine coverage.
+      if (box.east < -180 || box.west > -50 || box.north < 17 || box.south > 84)
+        return {
+          records: [],
+          stale: false,
+          saturated: false,
+          noCoverage: true,
+        };
+      const zoom = alprDetailZoom(box);
+      if (zoom === null)
+        return { records: [], stale: false, saturated: false, zoomIn: true };
+      const tiles = tilesForBounds(box, zoom, {
+        maxTiles: DETAIL_MAX_TILES + 1,
+      });
+      const tileBounds = tiles.map((tile) => tileToBBox(zoom, tile.x, tile.y));
+      const coverage = {
+        south: Math.min(...tileBounds.map((b) => b.south)),
+        west: Math.min(...tileBounds.map((b) => b.west)),
+        north: Math.max(...tileBounds.map((b) => b.north)),
+        east: Math.max(...tileBounds.map((b) => b.east)),
+      };
+      const records = new Map();
+      let covered = false,
+        partial = false;
+      for (const [index, source] of sources.entries()) {
+        if (
+          index === 1 &&
+          (box.north < 41 ||
+            box.south > 84 ||
+            box.east < -142 ||
+            box.west > -52)
+        )
+          continue;
+        const metadata = await source.getMetadata(signal);
+        const [west, south, east, north] = metadata.bounds || [];
+        if (![west, south, east, north].every(Number.isFinite))
+          throw new Error('Camera coverage unavailable');
+        if (
+          box.east < west ||
+          box.west > east ||
+          box.north < south ||
+          box.south > north
+        )
+          continue;
+        covered = true;
+        const result = await source.fetchBounds(box, { zoom, signal });
+        partial ||= result.partial;
+        for (const record of result.tiles.flat())
+          records.set(record.id, precise(record, zoom));
+      }
+      signal?.throwIfAborted();
+      let list = [...records.values()];
+      const truncated = list.length > SOURCE_RECORD_LIMIT;
+      if (truncated) {
+        // Keep the cameras nearest the view centre when a dense metro overflows.
+        const lat = (box.south + box.north) / 2;
+        const lon = (box.west + box.east) / 2;
+        const scale = Math.cos((lat * Math.PI) / 180);
+        list = list
+          .map((record) => ({
+            record,
+            d:
+              (record.latitude - lat) ** 2 +
+              ((record.longitude - lon) * scale) ** 2,
+          }))
+          .sort((a, b) => a.d - b.d)
+          .slice(0, SOURCE_RECORD_LIMIT)
+          .map((item) => item.record);
+      }
+      return {
+        records: list,
+        stale: false,
+        saturated: partial || truncated,
+        noCoverage: !covered,
+        // A partial or truncated read does not cover its tiles; reuse only the box.
+        coverage: partial || truncated ? { ...box } : coverage,
+        zoom,
+      };
+    },
+    detailZoom: alprDetailZoom,
+    destroy() {
+      for (const source of sources) source.clear();
+      precision.clear();
+    },
+    label: 'OpenStreetMap · community mapped',
+    attribution: {
+      name: 'OpenStreetMap',
+      description: '© OpenStreetMap contributors, ODbL',
+      text: '© OpenStreetMap contributors, ODbL',
+      href: 'https://www.openstreetmap.org/copyright',
+    },
+  };
+}
+
 /** Construct the bounded OSM request adapter without starting a request. */
 export function createOverpassAlprSource({
   fetchImpl = (...args) => globalThis.fetch(...args),
@@ -75,7 +264,7 @@ export function createOverpassAlprSource({
     attribution: {
       name: 'OpenStreetMap',
       description: 'OpenStreetMap contributors (ODbL 1.0; community mapped)',
-      text: '© OpenStreetMap',
+      text: '© OpenStreetMap contributors',
       href: 'https://www.openstreetmap.org/copyright',
     },
   };

src/layers/alpr/source.test.mjs

@@ -1,12 +1,19 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { createOverpassAlprSource } from './source.js';
+import { readFileSync } from 'node:fs';
+import {
+  alprDetailZoom,
+  createAlprPrecisionCache,
+  createAlprTileSource,
+  createOverpassAlprSource,
+  buildOverpassQuery,
+} from './source.js';
 import { validateAlprSnapshot, alprCreditMarkup } from './model.js';
 const box = { south: 30, west: -98, north: 30.1, east: -97.9 };
 test('the source rejects invalid and unbounded queries before fetching', async () => {
   let calls = 0;
-  const source = createOverpassAlprSource({
-    fetchImpl() {
+  const source = createAlprTileSource({
+    tileFetchImpl() {
       calls++;
     },
   });
@@ -21,55 +28,77 @@ test('the source rejects invalid and unbounded queries before fetching', async (
   }
   assert.equal(calls, 0);
 });
-test('cancellation during body parsing rejects even when the transport ignores it', async () => {
+const fixture = readFileSync(
+  new URL(
+    '../../data/fixtures/osm-alpr-austin-11-467-843.pbf',
+    import.meta.url,
+  ),
+);
+const metadata = (country) => ({
+  tiles: [
+    `https://tiles.dontgetflocked.com/cameras-${country}-hourly/{z}/{x}/{y}.mvt`,
+  ],
+  bounds: country === 'ca' ? [-124, 42, -63, 54] : [-160, 17, -64, 59],
+});
+const austin = { south: 30.2, north: 30.35, west: -97.85, east: -97.65 };
+
+test('cancellation while reading TileJSON is preserved even if fetch ignores it', async () => {
   const abort = new AbortController();
-  const source = createOverpassAlprSource({
-    fetchImpl: async () => ({
+  const source = createAlprTileSource({
+    tileFetchImpl: async () => ({
       ok: true,
       headers: new Headers(),
-      json: async () => {
+      async text() {
         abort.abort();
-        return { elements: [] };
+        return JSON.stringify(metadata('us'));
       },
     }),
   });
-  await assert.rejects(source.fetch(box, abort.signal), { name: 'AbortError' });
+  await assert.rejects(source.fetch(austin, abort.signal), {
+    name: 'AbortError',
+  });
 });
 
-test('Overpass normalization returns camera records and preserves limited/stale coverage', async () => {
-  const source = createOverpassAlprSource({
-    fetchImpl: async () => ({
-      ok: true,
-      headers: new Headers({ 'x-overpass-cache': 'STALE' }),
-      json: async () => ({
-        elements: [
-          {
-            type: 'node',
-            id: 12,
-            lat: 30,
-            lon: -98,
-            tags: {
-              'surveillance:type': 'camera;ALPR',
-              'camera:direction': '90',
-            },
-          },
-        ],
-      }),
-    }),
+test('extract detail tiles map OSM records and repeated pans reuse decoded tiles', async () => {
+  const calls = [];
+  const source = createAlprTileSource({
+    tileFetchImpl: async (url) => {
+      calls.push(url);
+      return url.endsWith('.json')
+        ? Response.json(metadata(url.includes('-ca-') ? 'ca' : 'us'))
+        : new Response(fixture);
+    },
   });
-  const snapshot = await source.fetch(box);
-  assert.equal(snapshot.records[0].id, 'alpr:12');
-  assert.equal(snapshot.records[0].latitude, 30);
-  assert.equal(snapshot.records[0].directionDeg, 90);
-  assert.equal(snapshot.stale, true);
-  assert.equal(snapshot.saturated, false);
+  const snapshot = await source.fetch(austin);
+  assert.ok(snapshot.records.length > 0);
+  const record = snapshot.records[0];
+  assert.match(record.id, /^alpr:/);
+  assert.equal(record.manufacturer, 'Flock Safety');
+  assert.equal(record.lastVerified, null);
+  assert.ok(record.osmTimestamp);
+  assert.equal(snapshot.stale, false);
   assert.equal('elements' in snapshot, false);
+  const fetched = calls.length;
+  await source.fetch(austin);
+  assert.equal(calls.length, fetched);
+  assert.ok(calls.every((url) => !url.includes('overpass')));
+  assert.doesNotMatch(JSON.stringify(source.attribution), /flock/i);
+});
+
+test('outside extract coverage is an explicit no-data state without Overpass', async () => {
+  const source = createAlprTileSource({
+    tileFetchImpl: () => assert.fail('no network expected in Europe'),
+  });
+  assert.deepEqual(
+    await source.fetch({ south: 51, north: 51.1, west: 0, east: 0.1 }),
+    { records: [], stale: false, saturated: false, noCoverage: true },
+  );
 });
 
 test('an unsuccessful source response releases its body before reporting an error', async () => {
   let cancelled = 0;
-  const source = createOverpassAlprSource({
-    fetchImpl: async () => ({
+  const source = createAlprTileSource({
+    tileFetchImpl: async () => ({
       ok: false,
       status: 429,
       body: {
@@ -79,7 +108,7 @@ test('an unsuccessful source response releases its body before reporting an erro
       },
     }),
   });
-  await assert.rejects(source.fetch(box), /rate-limited/);
+  await assert.rejects(source.fetch(box), /unavailable/);
   assert.equal(cancelled, 1);
 });
 
@@ -115,3 +144,147 @@ test('provider attribution escapes markup and rejects executable links', () => {
   assert.ok(html.includes('?a=1&b=2'));
   assert.ok(!html.includes('<img'));
 });
+
+test('wide detail view returns zoom guidance before any fetch and can retry a smaller view', async () => {
+  let calls = 0;
+  const source = createAlprTileSource({
+    tileFetchImpl: async () => {
+      calls++;
+      return Response.json({
+        tiles: ['https://tiles.dontgetflocked.com/{z}/{x}/{y}.pbf'],
+        bounds: [-180, 17, -50, 84],
+      });
+    },
+  });
+  const wide = await source.fetch({
+    south: 29,
+    north: 32,
+    west: -99,
+    east: -96,
+  });
+  assert.equal(wide.zoomIn, true);
+  assert.equal(calls, 0);
+  await source
+    .fetch({ south: 30.267, north: 30.268, west: -97.744, east: -97.743 })
+    .catch(() => {});
+  assert.ok(calls > 0);
+});
+
+test('each view reads the finest attributed extract zoom that fits 16 tiles', () => {
+  // Field report: a z11-only read refused whole-city views. Attributed detail
+  // exists from z9, so a city reads a few z9/z10 tiles and a street z12.
+  assert.equal(
+    alprDetailZoom({ south: 30.29, north: 30.31, west: -97.78, east: -97.75 }),
+    12,
+  );
+  assert.equal(
+    alprDetailZoom({ south: 30.17, north: 30.36, west: -97.85, east: -97.63 }),
+    12,
+  );
+  assert.equal(
+    alprDetailZoom({ south: 29.7, north: 30.7, west: -98.25, east: -97.25 }),
+    10,
+  );
+  assert.equal(
+    alprDetailZoom({ south: 29.2, north: 31.2, west: -98.75, east: -96.75 }),
+    9,
+  );
+  assert.equal(
+    alprDetailZoom({ south: 29, north: 32, west: -99, east: -96 }),
+    null,
+  );
+});
+
+test('a whole-city view loads cameras and reports the tiles it covers', async () => {
+  const urls = [];
+  const source = createAlprTileSource({
+    tileFetchImpl: async (url) => {
+      urls.push(url);
+      return url.endsWith('.json')
+        ? Response.json(metadata(url.includes('-ca-') ? 'ca' : 'us'))
+        : new Response(fixture);
+    },
+  });
+  const city = { south: 29.95, north: 30.55, west: -98.05, east: -97.45 };
+  const snapshot = await source.fetch(city);
+  assert.equal(snapshot.zoomIn, undefined);
+  assert.equal(snapshot.zoom, 10);
+  assert.ok(snapshot.records.length > 0);
+  assert.ok(urls.some((url) => url.includes('/10/')));
+  for (const key of ['south', 'west'])
+    assert.ok(snapshot.coverage[key] <= city[key]);
+  for (const key of ['north', 'east'])
+    assert.ok(snapshot.coverage[key] >= city[key]);
+});
+
+test('coarser tiles never move a camera a finer tile already placed', () => {
+  const cache = createAlprPrecisionCache(2);
+  const fine = {
+    id: 'alpr:1',
+    latitude: 30.30001,
+    longitude: -97.76001,
+    operator: 'A',
+  };
+  assert.equal(cache.apply(fine, 12), fine);
+  const coarse = {
+    ...fine,
+    latitude: 30.3001,
+    longitude: -97.7602,
+    operator: 'B',
+  };
+  const kept = cache.apply(coarse, 9);
+  assert.equal(kept.latitude, fine.latitude);
+  assert.equal(kept.longitude, fine.longitude);
+  assert.equal(kept.operator, 'B', 'attributes still refresh');
+  const finer = { ...fine, latitude: 30.300012 };
+  assert.equal(cache.apply(finer, 13), finer);
+  cache.apply({ id: 'alpr:2', latitude: 1, longitude: 1 }, 12);
+  cache.apply({ id: 'alpr:3', latitude: 1, longitude: 1 }, 12);
+  assert.equal(cache.size(), 2, 'bounded');
+});
+
+test('the explicit Overpass factory posts the unchanged query to its API transport', async () => {
+  const calls = [];
+  const source = createOverpassAlprSource({
+    fetchImpl: async (url, options) => {
+      calls.push({ url, options });
+      return Response.json({
+        elements: [
+          {
+            type: 'node',
+            id: 42,
+            lat: 30.05,
+            lon: -97.95,
+            tags: { 'surveillance:type': 'ALPR', operator: 'Test' },
+          },
+        ],
+      });
+    },
+  });
+  const result = await source.fetch(box);
+  assert.equal(result.records.length, 1);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].url, '/api/overpass');
+  assert.equal(calls[0].options.method, 'POST');
+  assert.equal(
+    new URLSearchParams(calls[0].options.body).get('data'),
+    buildOverpassQuery(box.south, box.west, box.north, box.east),
+  );
+});
+
+test('the tile adapter never passes public URLs through an injected API transport', async (t) => {
+  const urls = [];
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    urls.push(url);
+    return url.endsWith('.json')
+      ? Response.json(metadata('us'))
+      : new Response(fixture);
+  });
+  const source = createAlprTileSource({
+    fetchImpl: () => assert.fail('API transport must not receive tile URLs'),
+  });
+  const result = await source.fetch(austin);
+  assert.ok(result.records.length);
+  assert.ok(urls.length > 1);
+  assert.ok(urls.every((url) => url.startsWith('https://tiles.')));
+});

src/layers/alpr/tileRecords.js

@@ -0,0 +1,43 @@
+import { PbfReader } from 'pbf';
+import { VectorTile } from '@mapbox/vector-tile';
+import { normalizeAlprNode } from './records.js';
+
+/** Map extract attributes without treating an OSM edit date as a field verification. */
+export function normalizeAlprTileFeature(feature) {
+  const p = feature?.properties || {};
+  if (feature?.geometry?.type !== 'Point' || p.osmType !== 'node') return null;
+  const [lon, lat] = feature.geometry.coordinates;
+  const record = normalizeAlprNode({
+    type: 'node',
+    id: Number(p.osmId),
+    lat,
+    lon,
+    tags: {
+      'surveillance:type': 'ALPR',
+      operator: p.operator,
+      manufacturer: p.brand,
+      'camera:type': p.cameraType,
+      'camera:direction': p.direction,
+      'surveillance:zone': p.surveillanceZone,
+      ref: p.ref,
+      check_date: p.check_date,
+    },
+  });
+  return record ? { ...record, osmTimestamp: p.osmTimestamp || null } : null;
+}
+
+/** Decode detail-level camera points; geometry-only heatmap tiles are not records. */
+export function decodeAlprTile(bytes, z, x, y) {
+  const layer = new VectorTile(new PbfReader(bytes)).layers.cameras;
+  if (!layer) return [];
+  if (layer.length > 40_000)
+    throw new Error('Camera tile feature limit exceeded');
+  const records = [];
+  for (let i = 0; i < layer.length; i++) {
+    const record = normalizeAlprTileFeature(
+      layer.feature(i).toGeoJSON(x, y, z),
+    );
+    if (record) records.push(record);
+  }
+  return records;
+}

src/layers/alpr/visuals.js

@@ -1,6 +1,25 @@
 import * as Cesium from 'cesium';
 import { destinationPointDeg } from './model.js';
-import { DIRECTION_CONE_M, DIRECTION_CONE_HALF_ANGLE_DEG } from './policy.js';
+import {
+  DIRECTION_CONE_M,
+  DIRECTION_CONE_HALF_ANGLE_DEG,
+  MARKER_SCALE_BY_DISTANCE,
+} from './policy.js';
+
+/**
+ * Badge scale at a camera distance, matching Cesium's NearFarScalar for the
+ * native badges (linear between near and far, clamped outside).
+ * @param {number} distanceM Camera-to-marker distance.
+ * @returns {number} Scale factor.
+ */
+export function markerScale(distanceM) {
+  const [near, nearScale, far, farScale] = MARKER_SCALE_BY_DISTANCE;
+  if (!Number.isFinite(distanceM) || distanceM <= near) return nearScale;
+  if (distanceM >= far) return farScale;
+  return (
+    nearScale + ((distanceM - near) / (far - near)) * (farScale - nearScale)
+  );
+}
 
 // Camera artwork and visual treatment contributed by Manjunath (@manjunath22466).
 // Module-relative assets also resolve when the layer is consumed by another app.
@@ -48,8 +67,16 @@ export function alprLabelDetails(record, source) {
   return details;
 }
 
-/** Illustrative bearing wedge, not measured field of view or operating range. */
-export function directionWedgePositions(record, heightM = 0) {
+/**
+ * Illustrative bearing wedge, not measured field of view or operating range.
+ * @param {object} record Camera record.
+ * @param {number} [heightM] Apex height.
+ * @param {function(number, number): (number|null)} [heightAt] Optional height
+ *   for the two far corners (degrees lat, lon), so the wedge follows a slope
+ *   instead of floating level from the apex; falls back to the apex height.
+ * @returns {Array<Cesium.Cartesian3>|null} Apex, left and right corners.
+ */
+export function directionWedgePositions(record, heightM = 0, heightAt = null) {
   if (!Number.isFinite(record.directionDeg)) return null;
   const left = destinationPointDeg(
     record.latitude,
@@ -63,10 +90,18 @@ export function directionWedgePositions(record, heightM = 0) {
     record.directionDeg + DIRECTION_CONE_HALF_ANGLE_DEG,
     DIRECTION_CONE_M,
   );
+  const corner = (point) => {
+    const height = heightAt?.(point.latitude, point.longitude);
+    return Number.isFinite(height) ? height : heightM;
+  };
   return [
     Cesium.Cartesian3.fromDegrees(record.longitude, record.latitude, heightM),
-    Cesium.Cartesian3.fromDegrees(left.longitude, left.latitude, heightM),
-    Cesium.Cartesian3.fromDegrees(right.longitude, right.latitude, heightM),
+    Cesium.Cartesian3.fromDegrees(left.longitude, left.latitude, corner(left)),
+    Cesium.Cartesian3.fromDegrees(
+      right.longitude,
+      right.latitude,
+      corner(right),
+    ),
   ];
 }
 

src/layers/awareness/anchor.test.mjs

@@ -0,0 +1,61 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { createControls } from './controls.js';
+import { createSubject } from './subject.js';
+
+test('passive Contacts releases its installation anchor and subject refresh cannot reclaim it', (t) => {
+  const prior = globalThis.document;
+  globalThis.document = { body: { classList: { contains: () => false } } };
+  t.after(() => {
+    globalThis.document = prior;
+  });
+  const anchors = [];
+  const position = Cesium.Cartesian3.fromDegrees(-117.14, 32.87);
+  const state = {
+    enabled: true,
+    passive: false,
+    subject: {
+      id: 'site',
+      layerId: 'military-installations',
+      label: 'Site',
+      position,
+    },
+    sourceRevision: 'current',
+    lastEvaluatedPosition: position,
+    results: {},
+  };
+  const services = {
+    installations: { setContextAnchor: (value) => anchors.push(value) },
+  };
+  let activations = 0;
+  const parts = {
+    dependencies: { activateOperationalContext: () => activations++ },
+    queries: {
+      collectSourceStates: () => ({}),
+      sourceRevision: () => 'current',
+    },
+    navigation: { isFlightLayer: () => false },
+    model: { awarenessRefreshRequired: () => false },
+    rendering: { renderVisual() {}, scheduleDirectionOverlayUpdate() {} },
+  };
+  const controls = createControls({ state, services, parts }).methods;
+  const subject = createSubject({ state, services, parts });
+  subject.refreshSelectedSubject();
+  assert.equal(anchors.length, 1);
+  assert.ok(anchors[0] instanceof Cesium.Cartesian3);
+  controls.setParams({ passive: true });
+  assert.equal(anchors.at(-1), null);
+  const released = anchors.length;
+  subject.refreshSelectedSubject();
+  subject.refreshSelectedSubject();
+  assert.equal(
+    anchors.length,
+    released,
+    'passive refresh must not reclaim the viewport',
+  );
+  controls.setParams({ passive: false });
+  assert.equal(activations, 1);
+  subject.refreshSelectedSubject();
+  assert.ok(anchors.at(-1) instanceof Cesium.Cartesian3);
+});

src/layers/awareness/controls.js

@@ -29,6 +29,7 @@ export function createControls({ state: layerState, services, parts, source }) {
       if (typeof params.passive !== 'boolean') return;
       const wasPassive = layerState.passive;
       layerState.passive = params.passive;
+      if (layerState.passive) services.installations?.setContextAnchor?.(null);
       if (layerState.enabled && wasPassive && !layerState.passive)
         parts.dependencies.activateOperationalContext();
     },

src/layers/awareness/lifecycle.js

@@ -206,6 +206,7 @@ export function createLifecycle({
       layerState.autoFocusAttempted = false;
       layerState.autoFocusRetryPending = false;
       layerState.subject = null;
+      services.installations?.setContextAnchor?.(null);
       layerState.results = null;
       layerState.lastSubjectRefreshMs = 0;
       layerState.lastEvaluatedPosition = null;

src/layers/awareness/panel.js

@@ -72,7 +72,7 @@ export function createPanel({ state: layerState, services, parts, source }) {
           return `<li><span class="military-awareness-target unavailable" aria-label="Unavailable">${escapeHtml(label)} <span>${formatAwarenessDistance(item.distanceM)}</span></span></li>`;
         }
         const accessibleLabel = label === '—' ? 'Unavailable' : label;
-        return `<li><button type="button" class="military-awareness-target" data-awareness-layer="${escapeHtml(cohort.id)}" data-awareness-id="${escapeHtml(targetId)}" aria-label="Focus ${escapeHtml(accessibleLabel)}">${escapeHtml(label)} <span>${formatAwarenessDistance(item.distanceM)}</span></button></li>`;
+        return `<li><button type="button" class="military-awareness-target" data-awareness-layer="${escapeHtml(cohort.id)}" data-awareness-id="${escapeHtml(targetId)}" aria-label="Focus ${escapeHtml(accessibleLabel)}">${escapeHtml(label)} <span>${formatAwarenessDistance(item.distanceM)}</span></button>${namedAreasHtml(item.memberNames)}</li>`;
       })
       .join('');
     const pageCount = Math.max(
@@ -164,11 +164,18 @@ export function createPanel({ state: layerState, services, parts, source }) {
     );
   }
 
+  function namedAreasHtml(names) {
+    return names?.length
+      ? `<details class="military-awareness-names"><summary>Named areas (${names.length})</summary><div>${names.map((name) => escapeHtml(name)).join('<br>')}</div></details>`
+      : '';
+  }
+
   function renderResults() {
     if (!layerState.enabled || !layerState.results) return hidePanel();
     const panel = ensurePanel();
     const { subject, cohorts } = layerState.results;
     const markup = `<div class="military-awareness-subject">${escapeHtml(subject.label)} · ${formatAwarenessDistance(AWARENESS_RADIUS_M)} FLIGHT / VESSEL WINDOW</div>
+    ${namedAreasHtml(subject.memberNames)}
     ${navigationControlsHtml()}
     ${cohorts.map(rowHtml).join('')}
     <p class="military-awareness-note" tabindex="-1" data-awareness-focus-continuation>Open-source mapped/observed context. Missing broadcasts, unloaded map areas, or unmapped sites are not evidence of absence.</p>`;

src/layers/awareness/queries.js

@@ -94,14 +94,33 @@ export function createQueries({ state: layerState, services, parts, source }) {
    */
 
   function summarizeInstallationViewport(items, source) {
+    const coverage = source.stats?.coverage;
+    // getNearby measures these distances from the current subject, independent
+    // of the retained square used to fetch installation tiles.
+    const withinRadius =
+      coverage?.kind === 'subject' && Number.isFinite(coverage.radiusM)
+        ? items.filter(
+            (item) => (item.distanceM ?? item.distance) <= coverage.radiusM,
+          )
+        : items;
     const summary = parts.navigation.summarizeAwarenessCohortForNavigation(
-      items,
+      withinRadius,
       source,
     );
     if (summary.count === null)
       return source.stats?.statusMessage
         ? { ...summary, reason: source.stats.statusMessage }
         : summary;
+    // A subject window is its own bounded area: name it instead of the viewport.
+    if (coverage?.kind === 'subject' && Number.isFinite(coverage.radiusM)) {
+      const km = Math.round(coverage.radiusM / 1000);
+      return {
+        ...summary,
+        reason: summary.count
+          ? `mapped matches within ${km} km of the subject`
+          : `none mapped within ${km} km; not a complete 250 km survey`,
+      };
+    }
     return {
       ...summary,
       reason: summary.count

src/layers/awareness/queries.test.mjs

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { createQueries } from './queries.js';
+import { createSubject } from './subject.js';
+import { createControls } from '../installations/controls.js';
+import { createModel } from '../installations/model.js';
+import { summarizeAwarenessCohort } from '../../data/militaryAwarenessEngine.js';
+
+test('Contacts excludes square corners and measures from the current moving subject', () => {
+  const records = [
+    { id: 'corner', kind: 'installation', latitude: 90 / 111.195, longitude: 90 / 111.195 },
+    { id: 'east', kind: 'installation', latitude: 0, longitude: 90 / 111.195 },
+    { id: 'west', kind: 'installation', latitude: 0, longitude: -90 / 111.195 },
+  ];
+  const installationState = { records, contextAnchor: { latitude: 0, longitude: 0 },
+    lastUpdate: 1, status: 'ready', coverage: { kind: 'subject', radiusM: 100000 },
+    distanceEndpointScratch: new Cesium.Cartographic(),
+    distanceGeodesicScratch: new Cesium.EllipsoidGeodesic(),
+  };
+  const installationParts = { rendering: { installationSurfaceHeightM: () => 0 } };
+  installationParts.model = createModel({ state: installationState, parts: installationParts });
+  const installations = createControls({ state: installationState, parts: installationParts }).methods;
+  const services = { installations, flights: { getNearby: () => [] },
+    military: { getNearby: () => [] }, vessels: { getNearby: () => [] } };
+  const parts = { navigation: { summarizeAwarenessCohortForNavigation: (items, source) =>
+    summarizeAwarenessCohort(items, source) } };
+  parts.queries = createQueries({ state: {}, services, parts });
+  const subjectOwner = createSubject({ state: {}, services, parts });
+  const states = Object.fromEntries(['flights', 'military', 'ais-live-vessels', 'military-installations']
+    .map((id) => [id, { available: true, stats: {} }]));
+  states['military-installations'].stats.coverage = { kind: 'subject', radiusM: 100000 };
+  const evaluate = (lon) => subjectOwner.evaluateSubject({
+    id: 'moving', layerId: 'flights', position: Cesium.Cartesian3.fromDegrees(lon, 0, 10000),
+  }, states).cohorts[3].summary;
+  installations.setContextAnchor({ latitude: 0, longitude: 0 });
+  const first = evaluate(0);
+  assert.equal(first.count, 2);
+  assert.ok(!first.nearest.some((item) => item.id === 'corner'), '90 km N + 90 km E is outside the disk');
+  assert.equal(installations.getStats().count, 2);
+  assert.equal(installations.getStats().statusMessage, '2 mapped sites within 100 km of the contact');
+  installations.setContextAnchor({ latitude: 0, longitude: 19 / 111.195 });
+  const moved = evaluate(19 / 111.195);
+  assert.equal(installations.getStats().count, 1);
+  assert.equal(installations.getStats().statusMessage, '1 mapped site within 100 km of the contact');
+  assert.equal(moved.count, 1, 'west site leaves the radius before the fetch anchor refreshes');
+  assert.equal(moved.nearest[0].id, 'east');
+  assert.equal(moved.reason, 'mapped matches within 100 km of the subject');
+  assert.deepEqual(installationState.contextAnchor, { latitude: 0, longitude: 0 });
+});

src/layers/awareness/subject.js

@@ -48,8 +48,13 @@ export function createSubject({ state: layerState, services, parts, source }) {
         (item) =>
           !parts.queries.isSame(subject, item, 'ais-live-vessels', 'mmsi'),
       );
+    const coverage = installationsState.stats?.coverage;
+    const installationRadius =
+      coverage?.kind === 'subject' && Number.isFinite(coverage.radiusM)
+        ? coverage.radiusM
+        : AWARENESS_RADIUS_M;
     const installations = militaryInstallationsLayer
-      .getNearby(position, AWARENESS_RADIUS_M, AWARENESS_QUERY_LIMIT)
+      .getNearby(position, installationRadius, AWARENESS_QUERY_LIMIT)
       .filter(
         (item) =>
           !parts.queries.isSame(subject, item, 'military-installations', 'id'),
@@ -92,7 +97,8 @@ export function createSubject({ state: layerState, services, parts, source }) {
           source:
             installationsState.stats.source ||
             SOURCE_LABEL['military-installations'],
-          coverage: 'CURRENT VIEWPORT ONLY',
+          coverage:
+            installationsState.stats.coverageLabel || 'CURRENT VIEWPORT ONLY',
           summary: parts.queries.summarizeInstallationViewport(
             installations,
             installationsState,
@@ -326,6 +332,11 @@ export function createSubject({ state: layerState, services, parts, source }) {
     });
     if (!resolved) return;
     const { position, presence } = resolved;
+    // Mapped installations load around the subject, not the (follow/Cockpit)
+    // camera view. The installation layer moves its window only after the
+    // subject travels far enough, so this per-refresh call is cheap.
+    if (!layerState.passive)
+      militaryInstallationsLayer.setContextAnchor?.(position);
     // UNCHECKED leaves the verdict alone: this tick simply did not look.
     if (presence === SUBJECT_PRESENCE.LIVE) layerState.subjectMissing = false;
     else if (presence === SUBJECT_PRESENCE.MISSING)
@@ -392,6 +403,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
       layerId: record.layerId,
       id: record.properties?.mmsi || record.id,
       label: record.label || record.id,
+      memberNames: record.properties?.memberNames || [],
       position: Cesium.Cartesian3.fromDegrees(longitude, latitude, 0),
     };
   }
@@ -411,6 +423,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
   }
 
   function clearAwarenessSubject() {
+    militaryInstallationsLayer.setContextAnchor?.(null);
     layerState.autoFocusRetryPending = false;
     layerState.subject = null;
     layerState.subjectMissing = false;

src/layers/cctv/lifecycle.js

@@ -339,6 +339,12 @@ export function createLifecycle({
      */
     enable() {
       layerState._enabled = true;
+      if (
+        layerState._records.some(
+          (record) => record.camera.cityId === 'warendorf',
+        )
+      )
+        services.credits?.showOsmCredit?.(layerState._viewer, 'cctv');
       layerState._lastUpdate = Date.now();
       // Pick-ownership (H2): camera billboards use the camera id directly;
       // coverage polyline entities use `cctv-<cameraId>-<role>` entity ids.
@@ -385,6 +391,7 @@ export function createLifecycle({
 
     /** Disables the layer: hides entities, stops the projection loop and load queue. */
     disable() {
+      services.credits?.hideOsmCredit?.(layerState._viewer, 'cctv');
       layerState._enabled = false;
       unregisterPickOwner('cctv');
       // ADJUST mode does not survive a layer toggle — predictable re-entry.
@@ -408,6 +415,7 @@ export function createLifecycle({
      * @param {Cesium.Viewer} [viewer] - Viewer instance (falls back to stored ref).
      */
     destroy(viewer) {
+      services.credits?.hideOsmCredit?.(layerState._viewer, 'cctv');
       layerState._sourceAbort?.abort();
       if (typeof document !== 'undefined')
         document.removeEventListener(

src/layers/directions/index.js

@@ -695,6 +695,7 @@ export function createDirectionsLayer({ services }) {
   }
 
   function clearRouteGraphics() {
+    services.credits?.hideOsmCredit?.(_viewer, 'directions');
     _clearStepSelection();
     stopStepAnchoring();
     removeEntity(_routeEntity);
@@ -800,6 +801,7 @@ export function createDirectionsLayer({ services }) {
         disableDepthTestDistance: Number.POSITIVE_INFINITY,
       });
     }
+    services.credits?.showOsmCredit?.(_viewer, 'directions');
     services.ground.warmGroundFloor(cells);
     _anchorAttempts = 0;
     _anchorStartedAt = Date.now();

src/layers/installations/controls.js

@@ -1,6 +1,10 @@
 import * as Cesium from 'cesium';
 import { installationFeedback } from '../../data/installationFeedback.js';
-import { LAYER_ID, DISTANCE_PREFILTER_MARGIN_M } from './policy.js';
+import {
+  LAYER_ID,
+  DISTANCE_PREFILTER_MARGIN_M,
+  ANCHOR_REFRESH_M,
+} from './policy.js';
 
 export function createControls({ state: layerState, services, parts, source }) {
   const methods = {
@@ -16,12 +20,71 @@ export function createControls({ state: layerState, services, parts, source }) {
 
     statsRefreshInterval: 1000,
 
+    visitNamedMarkers(visitor) {
+      parts.namedMarkers.visit(visitor);
+    },
+
     /** Request a one-shot Google Maps Places search around the current map view. */
     searchNearby() {
       layerState.googleSearchRequested = true;
       return parts.ingestion.loadInstallations();
     },
 
+    /**
+     * Load sites around a Contacts subject instead of the camera viewport.
+     *
+     * A follow or Cockpit camera moves every frame, so `moveEnd` never fires and
+     * its view rectangle often reaches the horizon; a subject window is the
+     * only area that answers "what is near this contact". The window moves
+     * only after the subject travels ANCHOR_REFRESH_M, and cached tiles make
+     * that cheap. Passing null returns the layer to viewport loading.
+     * @param {Cesium.Cartesian3|{latitude:number, longitude:number}|null} position
+     *   Subject position.
+     * @returns {boolean} Whether a new load was scheduled.
+     */
+    setContextAnchor(position) {
+      let next = null;
+      if (position) {
+        if (
+          Number.isFinite(position.latitude) &&
+          Number.isFinite(position.longitude)
+        )
+          next = { latitude: position.latitude, longitude: position.longitude };
+        else {
+          const carto = Cesium.Cartographic.fromCartesian(position);
+          if (carto)
+            next = {
+              latitude: Cesium.Math.toDegrees(carto.latitude),
+              longitude: Cesium.Math.toDegrees(carto.longitude),
+            };
+        }
+      }
+      // Keep the live centre even when the coarse fetch anchor has not moved.
+      layerState.contextPosition = next
+        ? Cesium.Cartesian3.fromDegrees(next.longitude, next.latitude)
+        : null;
+      const previous = layerState.contextAnchor;
+      if (!next) {
+        if (!previous) return false;
+        layerState.contextAnchor = null;
+        parts.viewport.scheduleLoad();
+        return true;
+      }
+      if (
+        previous &&
+        parts.model.approximateSurfaceDistanceM(
+          Cesium.Math.toRadians(previous.latitude),
+          Cesium.Math.toRadians(previous.longitude),
+          next.latitude,
+          next.longitude,
+        ) < ANCHOR_REFRESH_M
+      )
+        return false;
+      layerState.contextAnchor = next;
+      parts.viewport.scheduleLoad();
+      return true;
+    },
+
     getNearby(center, rangeM, maxCount = 50) {
       if (!center) return [];
       const range = Number.isFinite(rangeM) ? rangeM : Infinity;
@@ -100,8 +163,30 @@ export function createControls({ state: layerState, services, parts, source }) {
     },
 
     getStats() {
+      const namedMarkers = parts.namedMarkers?.stats();
+      const subjectWindow =
+        layerState.coverage?.kind === 'subject' &&
+        layerState.contextPosition &&
+        Number.isFinite(layerState.coverage.radiusM);
+      const mappedCount = subjectWindow
+        ? methods.getNearby(
+            layerState.contextPosition,
+            layerState.coverage.radiusM,
+            layerState.records.length || 1,
+          ).length
+        : layerState.wide && namedMarkers
+          ? namedMarkers.pointsOnScreen
+          : layerState.records.filter(
+              (record) => record.kind === 'installation',
+            ).length;
       return {
-        count: layerState.records.length,
+        count:
+          subjectWindow || layerState.wide
+            ? mappedCount
+            : layerState.records.length,
+        namedInView: layerState.namedInView || 0,
+        wide: Boolean(layerState.wide),
+        ...namedMarkers,
         lastUpdate: layerState.lastUpdate,
         stale: layerState.stale,
         saturated: layerState.saturated,
@@ -113,11 +198,17 @@ export function createControls({ state: layerState, services, parts, source }) {
         failureReason: layerState.failureReason,
         statusMessage: installationFeedback({
           ...layerState,
+          count: layerState.lastUpdate ? mappedCount : undefined,
           retrying: layerState.loading && Boolean(layerState.failureReason),
         }),
         loadingLabel: layerState.loading
           ? 'loading mapped installation context'
           : '',
+        coverage: layerState.coverage,
+        coverageLabel:
+          layerState.coverage?.kind === 'subject'
+            ? `WITHIN ${Math.round(layerState.coverage.radiusM / 1000)} KM`
+            : 'CURRENT VIEWPORT ONLY',
       };
     },
   };

src/layers/installations/index.js

@@ -1,3 +1,4 @@
+import { createNamedMarkers } from './namedMarkers.js';
 import { createModel } from './model.js';
 import { createRendering } from './rendering.js';
 import { createIngestion } from './ingestion.js';
@@ -8,7 +9,7 @@ import { createLifecycle } from './lifecycle.js';
 import { createState } from './state.js';
 
 /** Construct one layer with its own scene state and supplied application services. */
-export function createInstallationsLayer({ services, source }) {
+export function createInstallationsLayer({ services, source, overlayHost }) {
   if (
     typeof source?.getMappedSites !== 'function' ||
     typeof source?.searchNearby !== 'function'
@@ -16,9 +17,10 @@ export function createInstallationsLayer({ services, source }) {
     throw new TypeError('An installation source is required');
   const state = createState({ services });
   const parts = {};
-  const context = { state, services, parts, source };
+  const context = { state, services, parts, source, overlayHost };
   parts.model = createModel(context);
   parts.rendering = createRendering(context);
+  parts.namedMarkers = createNamedMarkers(context);
   parts.ingestion = createIngestion(context);
   parts.viewport = createViewport(context);
   parts.selection = createSelection(context);

src/layers/installations/ingestion.js

@@ -1,3 +1,50 @@
+import { militaryOsmKey } from '../../data/militaryNames.js';
+import { isUnavailableCapability } from '../../sources/capability.js';
+/** Keep named point coverage until its matching polygon takes over. */
+export function retainNamedHandoff(previous, records, box) {
+  const named = new Map(
+    previous.filter((r) => r.namedArea).map((r) => [r.id, r]),
+  );
+  const represented = new Set();
+  const next = records.map((record) => {
+    represented.add(record.id);
+    for (const id of record.aliasIds || []) represented.add(id);
+    for (const member of record.namedMembers || []) represented.add(member.id);
+    for (const source of record.sources || []) {
+      const key = militaryOsmKey(source.id);
+      if (key) represented.add(`osm:military:${key}`);
+    }
+    const prior =
+      named.get(record.id) ||
+      (record.aliasIds || [])
+        .map((id) => named.get(id))
+        .filter(Boolean)
+        .sort((a, b) => b.areaM2 - a.areaM2)[0];
+    return !record.namedArea && prior
+      ? {
+          ...record,
+          name: prior.name,
+          namedArea: true,
+          areaM2: prior.areaM2,
+          class: prior.class,
+        }
+      : record;
+  });
+  for (const record of previous) {
+    if (
+      record.pointOnly &&
+      record.namedArea &&
+      !represented.has(record.id) &&
+      record.longitude >= box.west &&
+      record.longitude <= box.east &&
+      record.latitude >= box.south &&
+      record.latitude <= box.north
+    )
+      next.push(record);
+  }
+  return next;
+}
+
 export function createIngestion({
   state: layerState,
   services,
@@ -26,7 +73,7 @@ export function createIngestion({
 
   async function loadInstallations() {
     if (!layerState.enabled || !layerState.viewer) return;
-    const box = parts.viewport.viewportBox(layerState.viewer);
+    const { box, coverage } = parts.viewport.loadArea(layerState.viewer);
     // Guidance, not a fault: the layer chose not to query because the view is
     // unbounded (a global view, or Cockpit looking at the horizon). Keep it out
     // of `error` — the manager derives refresh failures and the global status
@@ -43,6 +90,7 @@ export function createIngestion({
     }
     layerState.abort?.abort();
     const requestAbort = new AbortController();
+    const keyOwner = (layerState.cameraLoadOwner ??= {});
     layerState.abort = requestAbort;
     layerState.loading = true;
     parts.viewport.clearUnavailableRetry({ resetBackoff: false });
@@ -53,19 +101,34 @@ export function createIngestion({
         source.getMappedSites(box, { exact, signal: requestAbort.signal });
 
       let payload = await fetchInstallations(false);
+      // Map tiles carry military areas only at z9 and finer: a view too wide
+      // for that is guidance, exactly like an unbounded view, never an empty
+      // all-clear. Previously loaded sites stay on the map.
+      if (payload.zoomIn) {
+        if (
+          requestAbort.signal.aborted ||
+          layerState.abort !== requestAbort ||
+          !layerState.enabled
+        )
+          return;
+        parts.viewport.clearUnavailableRetry();
+        setInstallationStatus('zoom-in');
+        return;
+      }
       // A SATURATED snapped tile was truncated upstream, so features from the
       // snap's extra ring may have crowded out sites actually on screen. Re-ask
       // for the exact viewport (separately keyed and cached) before rendering.
       let saturated = payload.saturated === true;
-      if (saturated) {
+      if (saturated && !payload.tileSource) {
         payload = await fetchInstallations(true);
         saturated = payload.saturated === true;
       }
       // The proxy answers a bbox at least as large as the viewport; keep only what
       // was actually asked for so nothing off-screen reaches the map or the
       // "current viewport only" context claim.
-      const records = payload.records.filter((record) =>
-        parts.model.installationWithinViewport(record, box),
+      const records = payload.records.filter(
+        (record) =>
+          payload.wide || parts.model.installationWithinViewport(record, box),
       );
       let placesError = null;
       if (layerState.googleSearchRequested) {
@@ -139,43 +202,84 @@ export function createIngestion({
             'Google Places search unavailable; showing mapped sites';
         }
       }
-      await resolveGroundFloorCellsBounded(
-        records.map((record) => ({
-          lat: record.latitude,
-          lon: record.longitude,
-        })),
-      );
+      let floorTimer;
+      await Promise.race([
+        resolveGroundFloorCellsBounded(
+          records
+            .filter((record) => !record.pointOnly)
+            .map((record) => ({
+              lat: record.latitude,
+              lon: record.longitude,
+            })),
+        ),
+        new Promise((resolve) => {
+          floorTimer = setTimeout(resolve, 120);
+        }),
+      ]).finally(() => clearTimeout(floorTimer));
       if (
         requestAbort.signal.aborted ||
         layerState.abort !== requestAbort ||
         !layerState.enabled
       )
         return;
-      layerState.records = records;
-      layerState.recordById = new Map(
-        layerState.records.map((record) => [record.id, record]),
-      );
-      layerState.lastUpdate = Date.now();
-      layerState.stale = payload.status === 'stale';
-      // Even the exact-viewport retry can saturate in a dense area. Say so rather
-      // than implying the view is completely surveyed.
-      layerState.saturated = saturated;
-      layerState.failureReason = null;
-      parts.viewport.clearUnavailableRetry();
-      setInstallationStatus(
-        layerState.records.length
-          ? layerState.stale
-            ? 'stale'
-            : 'ready'
-          : 'empty',
-        payload.status === 'stale'
-          ? 'Serving cached mapped context'
-          : saturated
-            ? 'Too many mapped sites in view to list them all'
-            : placesError,
-      );
-      parts.rendering.renderRecords();
-      parts.rendering.warmInstallationFloors(layerState.records);
+      const publish = (payload, records) => {
+        if (
+          requestAbort.signal.aborted ||
+          layerState.abort !== requestAbort ||
+          !layerState.enabled
+        )
+          return;
+        if (!payload.wide)
+          records = retainNamedHandoff(layerState.records, records, box);
+        layerState.namedInView =
+          payload.namedInView ?? records.filter((r) => r.namedArea).length;
+        layerState.wide = Boolean(payload.wide);
+        layerState.records = records;
+        layerState.recordById = new Map(
+          layerState.records.map((record) => [record.id, record]),
+        );
+        layerState.lastUpdate = Date.now();
+        layerState.coverage = coverage;
+        layerState.stale = payload.status === 'stale';
+        // Even the exact-viewport retry can saturate in a dense area. Say so rather
+        // than implying the view is completely surveyed.
+        layerState.saturated = saturated;
+        layerState.failureReason = null;
+        parts.viewport.clearUnavailableRetry();
+        setInstallationStatus(
+          layerState.records.length
+            ? layerState.stale
+              ? 'stale'
+              : 'ready'
+            : 'empty',
+          payload.status === 'stale'
+            ? `Serving cached mapped context · ${payload.records[0]?.retrievedAt || 'date unknown'}`
+            : saturated
+              ? 'Too many mapped sites in view to list them all'
+              : placesError,
+        );
+        parts.rendering.renderRecords();
+        parts.rendering.warmInstallationFloors(
+          layerState.records.filter((r) => !r.pointOnly),
+        );
+      };
+      publish(payload, records);
+      payload.enrichment?.then((enriched) => {
+        if (
+          !enriched ||
+          requestAbort.signal.aborted ||
+          layerState.abort !== requestAbort ||
+          !layerState.enabled
+        )
+          return;
+        const named = enriched.records.filter((record) =>
+          parts.model.installationWithinViewport(record, box),
+        );
+        publish(enriched, [
+          ...named,
+          ...records.filter((record) => record.id.startsWith('google:')),
+        ]);
+      });
     } catch (error) {
       if (
         requestAbort.signal.aborted ||
@@ -189,11 +293,17 @@ export function createIngestion({
         'unavailable',
         error?.message || 'Installation context unavailable',
       );
-      parts.viewport.scheduleUnavailableRetry();
+      if (!isUnavailableCapability(error))
+        parts.viewport.scheduleUnavailableRetry(error?.retryAfterMs);
     } finally {
       // An older aborted request must not clear a newer request's busy state.
       if (layerState.abort === requestAbort) {
-        layerState.abort = null;
+        if (
+          requestAbort.signal.aborted &&
+          layerState.cameraLoadOwner === keyOwner
+        )
+          layerState.cameraLoadKey = null;
+        // Keep ownership until superseded so late names cannot enrich an old view.
         layerState.loading = false;
       }
     }

src/layers/installations/lifecycle.js

@@ -1,5 +1,9 @@
 import * as Cesium from 'cesium';
 import { LAYER_ID } from './policy.js';
+import {
+  claimCameraSensitivity,
+  releaseCameraSensitivity,
+} from '../../data/cameraSensitivity.js';
 
 export function createLifecycle({
   state: layerState,
@@ -17,14 +21,37 @@ export function createLifecycle({
         'military-installations',
       );
       viewer.dataSources.add(layerState.dataSource);
-      layerState.moveEndRemove = viewer.camera.moveEnd.addEventListener(
-        parts.viewport.scheduleLoad,
-      );
+      const cameraChanged = () => {
+        if (!layerState.contextAnchor) parts.viewport.scheduleLoad();
+      };
+      layerState.moveEndRemove =
+        viewer.camera.moveEnd.addEventListener(cameraChanged);
+      layerState.changedRemove =
+        viewer.camera.changed?.addEventListener(cameraChanged);
       parts.selection.installInteraction(viewer);
     },
 
     enable() {
       layerState.enabled = true;
+      layerState.surfaceChangedRemove ||= services.maps?.subscribeMapStack(
+        parts.rendering.syncSelectionFill,
+      );
+      // Cached markers and geometry become visible before the next fetch.
+      if (
+        layerState.records?.some((r) =>
+          r.sources?.some((s) => s.name === 'OpenStreetMap'),
+        )
+      )
+        services.credits?.showOsmCredit?.(layerState.viewer, LAYER_ID, {
+          openMapTiles: layerState.records.some((r) =>
+            r.sources?.some(
+              (s) => s.name === 'OpenStreetMap' && s.id?.startsWith('tile:'),
+            ),
+          ),
+        });
+      parts.namedMarkers?.enable();
+      parts.namedMarkers?.sync(layerState.records || []);
+      claimCameraSensitivity(layerState.viewer.camera, LAYER_ID, 0.01);
       registerPickOwner(LAYER_ID, (id) => layerState.recordById.has(id));
       layerState.dataSource.show = true;
       // DataLayerManager invokes update() immediately after enable(), which owns
@@ -33,6 +60,14 @@ export function createLifecycle({
 
     disable() {
       layerState.enabled = false;
+      services.credits?.hideOsmCredit?.(layerState.viewer, LAYER_ID);
+      parts.namedMarkers?.hide();
+      releaseCameraSensitivity(layerState.viewer?.camera, LAYER_ID);
+      layerState.contextAnchor = null;
+      layerState.contextPosition = null;
+      layerState.coverage = { kind: 'viewport' };
+      layerState.cameraLoadKey = null;
+      layerState.cameraLoadOwner = null;
       unregisterPickOwner(LAYER_ID);
       parts.viewport.clearUnavailableRetry();
       clearTimeout(layerState.timer);
@@ -42,15 +77,25 @@ export function createLifecycle({
       if (layerState.dataSource) layerState.dataSource.show = false;
       clearSelectedEntityContextForLayer(LAYER_ID);
       layerState.selectedId = null;
+      parts.rendering.clearSelectionFill?.();
+      layerState.surfaceChangedRemove?.();
+      layerState.surfaceChangedRemove = null;
       layerState.failureReason = null;
       parts.ingestion.setInstallationStatus('idle');
     },
 
     destroy(viewer) {
+      source.destroy?.();
       this.disable();
+      layerState.contextAnchor = null;
+      layerState.contextPosition = null;
+      layerState.coverage = { kind: 'viewport' };
       layerState.moveEndRemove?.();
+      layerState.changedRemove?.();
+      parts.selection.destroy?.();
       layerState.clickHandler?.destroy();
       layerState.clickHandler = null;
+      parts.namedMarkers?.destroy();
       parts.rendering.clearRendered();
       if (layerState.dataSource && viewer)
         viewer.dataSources.remove(layerState.dataSource, true);

src/layers/installations/lifecycle.test.mjs

@@ -0,0 +1,82 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as credits from '../../data/dataCredits.js';
+import { createLifecycle } from './lifecycle.js';
+import { LAYER_ID } from './policy.js';
+
+for (const source of [
+  { name: 'OpenStreetMap', id: 'tile:base' },
+  { name: 'OpenStreetMap', id: 'way:123' },
+  { name: 'Google Places', id: 'place:base' },
+  null,
+]) {
+  test(`enable restores cached installation credits before a refresh: ${source?.id || 'empty'}`, () => {
+    const visibleCredits = new Set();
+    const noop = () => {};
+    const viewer = {
+      camera: {},
+      creditDisplay: {
+        addStaticCredit: (credit) => visibleCredits.add(credit),
+        removeStaticCredit: (credit) => visibleCredits.delete(credit),
+      },
+    };
+    const state = {
+      viewer,
+      records: source ? [{ id: 'base', sources: [source] }] : [],
+      recordById: new Map(),
+      dataSource: { show: false },
+    };
+    let markersVisible = false;
+    const parts = {
+      namedMarkers: {
+        enable: () => {
+          markersVisible = true;
+        },
+        sync: noop,
+        hide: () => {
+          markersVisible = false;
+        },
+      },
+      rendering: {},
+      viewport: { clearUnavailableRetry: noop },
+      ingestion: { setInstallationStatus: noop },
+    };
+    const lifecycle = createLifecycle({
+      state,
+      services: {
+        credits,
+        picking: { registerPickOwner: noop, unregisterPickOwner: noop },
+        context: { clearSelectedEntityContextForLayer: noop },
+      },
+      parts,
+      source: {},
+    }).methods;
+    const expected =
+      source?.name === 'OpenStreetMap'
+        ? source.id.startsWith('tile:')
+          ? 2
+          : 1
+        : 0;
+    try {
+      for (let cycle = 0; cycle < 2; cycle++) {
+        lifecycle.enable();
+        assert.equal(state.dataSource.show, true);
+        assert.equal(markersVisible, true);
+        // No renderRecords or successful fetch occurs between toggles.
+        assert.equal(visibleCredits.size, expected);
+        lifecycle.disable();
+        assert.equal(state.dataSource.show, false);
+        assert.equal(markersVisible, false);
+        assert.equal(visibleCredits.size, 0);
+      }
+      credits.showOsmCredit(viewer, 'another-layer');
+      lifecycle.enable();
+      lifecycle.disable();
+      assert.equal(visibleCredits.size, 1, 'another owner retains its credit');
+      assert.equal(credits.hideOsmCredit(viewer, LAYER_ID), false);
+    } finally {
+      lifecycle.disable();
+      credits.hideOsmCredit(viewer, 'another-layer');
+    }
+  });
+}

src/layers/installations/model.js

@@ -116,24 +116,28 @@ export function createModel({ state: layerState, services, parts, source }) {
       longitude >= box.west &&
       longitude <= box.east;
     if (centreInside) return true;
-    if (Array.isArray(footprint) && footprint.length) {
-      let minLat = Infinity;
-      let maxLat = -Infinity;
-      let minLon = Infinity;
-      let maxLon = -Infinity;
-      for (const [lon, lat] of footprint) {
-        if (lat < minLat) minLat = lat;
-        if (lat > maxLat) maxLat = lat;
-        if (lon < minLon) minLon = lon;
-        if (lon > maxLon) maxLon = lon;
-      }
-      return (
-        maxLat >= box.south &&
-        minLat <= box.north &&
-        maxLon >= box.west &&
-        minLon <= box.east
-      );
-    }
+    const footprints =
+      record.footprints?.map((rings) => rings[0]) ||
+      (footprint?.length ? [footprint] : []);
+    if (footprints.length)
+      return footprints.some((footprint) => {
+        let minLat = Infinity;
+        let maxLat = -Infinity;
+        let minLon = Infinity;
+        let maxLon = -Infinity;
+        for (const [lon, lat] of footprint) {
+          if (lat < minLat) minLat = lat;
+          if (lat > maxLat) maxLat = lat;
+          if (lon < minLon) minLon = lon;
+          if (lon > maxLon) maxLon = lon;
+        }
+        return (
+          maxLat >= box.south &&
+          minLat <= box.north &&
+          maxLon >= box.west &&
+          minLon <= box.east
+        );
+      });
     // Unknown extent: inclusive. Only a point feature may be excluded on centre.
     return record.osmType !== 'node';
   }

src/layers/installations/namedMarkers.js

@@ -0,0 +1,224 @@
+import * as Cesium from 'cesium';
+import {
+  MILITARY_LABEL_CAP,
+  MILITARY_POINT_CAP,
+} from '../../data/militaryNames.js';
+import { LAYER_ID, COLOR_BY_CLASS } from './policy.js';
+import { createInfrastructureOverlayEntry } from '../../data/infrastructureOverlayEntry.js';
+
+/** Bounded point markers; the shared overlay owns text projection and decluttering. */
+export function createNamedMarkers({ state, services, parts, overlayHost }) {
+  let points = null;
+  let entries = [];
+  const markers = new Map();
+  const screen = new Cesium.Cartesian2();
+  const occluder = new Cesium.EllipsoidalOccluder(Cesium.Ellipsoid.WGS84);
+  let shownPoints = 0;
+  let ordered = [];
+  const viewMatrix = new Cesium.Matrix4();
+  let width = 0,
+    height = 0;
+  let removeChanged = null,
+    removeEnd = null,
+    removeFrame = null;
+
+  function refresh() {
+    const viewer = state.viewer;
+    if (!state.enabled || !points) return;
+    width = viewer.scene.canvas.clientWidth;
+    height = viewer.scene.canvas.clientHeight;
+    if (viewer.camera.viewMatrix)
+      Cesium.Matrix4.clone(viewer.camera.viewMatrix, viewMatrix);
+    occluder.cameraPosition = viewer.camera.positionWC;
+    shownPoints = 0;
+    for (let index = 0; index < ordered.length; index++) {
+      const marker = ordered[index];
+      const point = marker.point;
+      point.show = marker.named && occluder.isPointVisible(point.position);
+      if (!point.show) continue;
+      const projected = Cesium.SceneTransforms.worldToWindowCoordinates(
+        viewer.scene,
+        point.position,
+        screen,
+      );
+      if (
+        projected &&
+        screen.x >= 0 &&
+        screen.y >= 0 &&
+        screen.x < width &&
+        screen.y < height
+      )
+        shownPoints++;
+    }
+  }
+
+  function publishLabels() {
+    overlayHost.setEntries(LAYER_ID, entries, {
+      // Keep the bounded point cohort available while Contacts owns the window.
+      // The arbiter spends at most 24 slots on currently visible, separated titles.
+      cohortLimit: MILITARY_POINT_CAP,
+      collisionCapacity: MILITARY_LABEL_CAP,
+      maxVisible: MILITARY_LABEL_CAP - (state.selectedId ? 1 : 0),
+      moving: false,
+      visible: state.enabled,
+    });
+  }
+
+  function cameraChanged() {
+    refresh();
+    services.render.governorRequestRender('installation-names');
+  }
+  function frame() {
+    const viewer = state.viewer;
+    if (
+      viewer?.camera.viewMatrix &&
+      (!Cesium.Matrix4.equals(viewMatrix, viewer.camera.viewMatrix) ||
+        width !== viewer.scene.canvas.clientWidth ||
+        height !== viewer.scene.canvas.clientHeight)
+    )
+      refresh();
+  }
+  function enable() {
+    const viewer = state.viewer;
+    if (!viewer || removeChanged || removeEnd || removeFrame) return;
+    removeChanged = viewer.camera.changed?.addEventListener(cameraChanged);
+    removeEnd = viewer.camera.moveEnd?.addEventListener(cameraChanged);
+    removeFrame = viewer.scene.preRender?.addEventListener(frame);
+    if (points) points.show = true;
+    publishLabels();
+    overlayHost.setVisible(LAYER_ID, true);
+    cameraChanged();
+  }
+  function hide() {
+    removeChanged?.();
+    removeEnd?.();
+    removeFrame?.();
+    removeChanged = removeEnd = removeFrame = null;
+    if (points) points.show = false;
+    overlayHost.clearSource(LAYER_ID);
+    overlayHost.setVisible(LAYER_ID, false);
+    shownPoints = 0;
+  }
+
+  function sync(records) {
+    const viewer = state.viewer;
+    if (!viewer?.scene?.primitives) return;
+    if (!points) {
+      points = viewer.scene.primitives.add(
+        new Cesium.PointPrimitiveCollection(),
+      );
+    }
+    points.show = state.enabled;
+    const named = records
+      .filter((r) => r.namedArea || r.id === state.selectedId)
+      .sort(
+        (a, b) =>
+          Number(b.id === state.selectedId) -
+            Number(a.id === state.selectedId) || b.areaM2 - a.areaM2,
+      )
+      .slice(0, MILITARY_POINT_CAP);
+    const keep = new Set(named.map((r) => r.id));
+    for (const record of named) {
+      if (markers.has(record.id)) continue;
+      const alias = record.aliasIds?.find(
+        (id) => !keep.has(id) && markers.has(id),
+      );
+      if (!alias) continue;
+      const marker = markers.get(alias);
+      markers.delete(alias);
+      marker.point.id = { installationId: record.id };
+      marker.entry.id = record.id;
+      markers.set(record.id, marker);
+    }
+    for (const [id, marker] of markers)
+      if (!keep.has(id)) {
+        points.remove(marker.point);
+        markers.delete(id);
+      }
+    ordered = [];
+    entries = [];
+    for (const record of named) {
+      const position = Cesium.Cartesian3.fromDegrees(
+        record.longitude,
+        record.latitude,
+        record.pointOnly
+          ? 0
+          : parts.rendering.installationSurfaceHeightM(record),
+      );
+      let marker = markers.get(record.id);
+      if (!marker) {
+        const id = { installationId: record.id };
+        marker = {
+          point: points.add({
+            id,
+            position,
+            pixelSize: 7,
+            color: parts.model.colorFor(record),
+            outlineColor: Cesium.Color.BLACK,
+            outlineWidth: 1,
+            disableDepthTestDistance: Infinity,
+          }),
+          entry: createInfrastructureOverlayEntry({
+            id: record.id,
+            source: LAYER_ID,
+            position,
+            title: record.name,
+            priority: record.areaM2 || 0,
+            accent: COLOR_BY_CLASS[record.class] || '#9ca6b0',
+          }),
+        };
+        markers.set(record.id, marker);
+      } else {
+        marker.point.position = position;
+      }
+      marker.named = record.namedArea;
+      marker.entry.variant =
+        record.id === state.selectedId ? 'selected' : 'card';
+      marker.entry.selected = record.id === state.selectedId;
+      marker.entry.details = marker.entry.selected
+        ? [
+            String(record.class || 'installation')
+              .replaceAll('_', ' ')
+              .toUpperCase(),
+            ...(record.memberNames || []).slice(0, 3),
+          ]
+        : [];
+      marker.entry.position = position;
+      marker.entry.title = record.name;
+      marker.entry.priority = record.areaM2 || 0;
+      entries.push(marker.entry);
+      ordered.push(marker);
+    }
+    if (state.enabled) publishLabels();
+    refresh();
+    services.render.governorRequestRender('installation-names');
+  }
+  return {
+    sync,
+    visit(visitor) {
+      for (let i = 0; i < ordered.length; i++) {
+        const marker = ordered[i];
+        visitor(marker.point.id.installationId, marker.point);
+      }
+    },
+    refresh,
+    enable,
+    hide,
+    stats: () => ({
+      namedMarkers: markers.size,
+      pointsOnScreen: shownPoints,
+      labelsOnScreen: state.enabled
+        ? overlayHost.getDiagnostics?.().paintedBySource[LAYER_ID] || 0
+        : 0,
+      labelCap: MILITARY_LABEL_CAP,
+    }),
+    destroy() {
+      hide();
+      ordered = [];
+      if (points) state.viewer?.scene.primitives.remove(points);
+      points = null;
+      entries = [];
+      markers.clear();
+    },
+  };
+}

src/layers/installations/namedMarkers.test.mjs

@@ -0,0 +1,185 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as C from 'cesium';
+import { createNamedMarkers } from './namedMarkers.js';
+import { createLifecycle } from './lifecycle.js';
+import { createLocalInfrastructureOverlayEntry } from '../../data/localGeojsonCore.js';
+
+function setup(t) {
+  let labels = [], options, publications = 0, visible = false;
+  const overlayHost = {
+    setEntries(id, entries, policy) {
+      assert.equal(id, 'military-installations');
+      labels = entries; options = policy; publications++;
+    },
+    clearSource() { labels = []; },
+    setVisible(_id, value) { visible = value; },
+  };
+  let x = -100;
+  const projections = new Set();
+  t.mock.method(C.SceneTransforms, 'worldToWindowCoordinates', (_scene, _point, scratch) => { projections.add(scratch); scratch.x = x; scratch.y = 300; return scratch; });
+  const camera = { changed: new C.Event(), moveEnd: new C.Event(), positionWC: C.Cartesian3.fromDegrees(0, 0, 1e6), viewMatrix: C.Matrix4.clone(C.Matrix4.IDENTITY) };
+  const state = { viewer: { camera, dataSources: { add() {}, remove() {} }, scene: { canvas: { clientWidth: 1280, clientHeight: 800 }, preRender: new C.Event(), primitives: { add: (p) => p, remove() {} } } }, enabled: true, contextAnchor: { latitude: 0, longitude: 0 } };
+  const services = { render: { governorRequestRender() {} }, picking: { registerPickOwner() {}, unregisterPickOwner() {} }, context: { clearSelectedEntityContextForLayer() {} } };
+  let loads = 0;
+  const parts = { model: { colorFor: () => C.Color.ORANGE }, rendering: { installationSurfaceHeightM: () => 0, clearRendered() {} }, viewport: { scheduleLoad: () => loads++, clearUnavailableRetry() {} }, selection: { installInteraction() {} }, ingestion: { setInstallationStatus() {} } };
+  const ctx = { state, services, parts, source: {}, overlayHost };
+  parts.namedMarkers = createNamedMarkers(ctx);
+  const lifecycle = createLifecycle(ctx).methods;
+  lifecycle.init(state.viewer); lifecycle.enable();
+  const records = [1, 2].map((n) => ({ id: `osm:military:w${n}`, name: `Site ${n}`, namedArea: true, areaM2: 100 / n, latitude: 0, longitude: 0, pointOnly: true }));
+  return { state, camera, get labels() { return labels; }, get options() { return options; }, get visible() { return visible; }, projections, records, markers: parts.namedMarkers, lifecycle, setX: (value) => { x = value; }, publications: () => publications, loads: () => loads };
+}
+
+test('Contacts camera motion reprojects and declutters existing labels without source loads or primitive replacement', (t) => {
+  const h = setup(t);
+  h.markers.sync(h.records);
+  assert.equal(h.markers.stats().pointsOnScreen, 0);
+  h.setX(600); h.camera.changed.raiseEvent(); h.camera.moveEnd.raiseEvent();
+  assert.equal(h.markers.stats().pointsOnScreen, 2);
+  assert.equal(h.labels.length, 2);
+  assert.equal(h.options.collisionCapacity, 24);
+  assert.equal(h.options.cohortLimit, 512);
+  assert.equal(h.visible, true);
+  assert.equal(h.loads(), 0);
+  assert.equal(h.publications(), 3);
+  assert.equal(h.projections.size, 1);
+  h.setX(1400); h.camera.viewMatrix[12] = 1; h.state.viewer.scene.preRender.raiseEvent();
+  assert.equal(h.markers.stats().pointsOnScreen, 0, 'small pose changes refresh before render');
+  h.lifecycle.disable();
+  assert.equal(h.camera.changed.numberOfListeners, 1, 'only the viewport listener remains');
+  assert.equal(h.state.viewer.scene.preRender.numberOfListeners, 0);
+  assert.equal(h.labels.length, 0);
+  assert.equal(h.visible, false);
+  h.state.records = h.records;
+  h.setX(600); h.lifecycle.enable();
+  assert.equal(h.labels.length, 2);
+  assert.equal(h.publications(), 5);
+  h.lifecycle.destroy(h.state.viewer);
+  assert.equal(h.camera.changed.numberOfListeners, 0);
+  assert.equal(h.camera.moveEnd.numberOfListeners, 0);
+  assert.equal(h.state.viewer.scene.preRender.numberOfListeners, 0);
+});
+
+test('wide named markers retain primitives until close polygons publish with the same identity', async (t) => {
+  const { retainNamedHandoff } = await import('./ingestion.js');
+  const h = setup(t);
+  h.setX(600); h.markers.sync(h.records);
+  const first = h.labels[0];
+  const box = { west: -1, east: 1, south: -1, north: 1 };
+  h.markers.sync(retainNamedHandoff(h.records, [], box));
+  assert.equal(h.labels[0], first);
+  assert.equal(first.title, 'Site 1');
+  const polygon = { ...h.records[0], namedArea: false, name: 'Military area', pointOnly: false, footprint: [[0, 0], [0.1, 0], [0, 0.1], [0, 0]] };
+  const handed = retainNamedHandoff(h.records, [polygon], box);
+  assert.equal(handed.length, 2);
+  assert.equal(handed[0].name, 'Site 1');
+  assert.equal(handed[0].pointOnly, false);
+  h.markers.sync(handed);
+  assert.equal(h.labels[0], first);
+  assert.equal(first.title, 'Site 1');
+  assert.equal(h.labels.length, 2, 'no duplicate title at handoff');
+  assert.equal(retainNamedHandoff(h.records, [], { west: 1, east: 2, south: 1, north: 2 }).length, 0);
+  h.lifecycle.destroy(h.state.viewer);
+});
+
+test('canonical aliases transfer named marker ownership without replacing primitives', (t) => {
+  const h = setup(t);
+  h.setX(600);
+  const parent = h.records[1];
+  h.markers.sync([parent]);
+  let originalPoint;
+  h.markers.visit((_id, point) => { originalPoint = point; });
+  const label = h.labels[0];
+  for (const record of [
+    { ...parent, id: h.records[0].id, aliasIds: [parent.id], pointOnly: false },
+    { ...parent, aliasIds: [h.records[0].id], pointOnly: false },
+    parent,
+  ]) {
+    h.markers.sync([record]);
+    h.markers.visit((id, point) => {
+      const currentLabel = h.labels[0];
+      assert.equal(id, record.id);
+      assert.equal(point, originalPoint);
+      assert.equal(currentLabel, label);
+      assert.equal(point.id.installationId, record.id);
+      assert.equal(currentLabel.id, record.id);
+    });
+  }
+  assert.equal(h.labels.length, 1);
+  h.lifecycle.destroy(h.state.viewer);
+});
+
+
+test('the bounded host cohort ranks wide points and polygon titles by area', (t) => {
+  const h = setup(t);
+  h.markers.sync(Array.from({ length: 600 }, (_, n) => ({
+    ...h.records[0], id: `site:${n}`, name: `Site ${n}`, areaM2: n,
+    pointOnly: n % 2 === 0,
+  })));
+  assert.equal(h.labels.length, 512);
+  assert.equal(h.labels[0].id, 'site:599');
+  assert.equal(h.labels.at(-1).id, 'site:88');
+  assert.ok(h.labels.every((entry) => !entry.stateless && entry.horizonCull && entry.collisionGroup === 'ambient-card'));
+  const first = h.labels[0];
+  const publications = h.publications();
+  for (let i = 0; i < 100; i++) {
+    h.camera.viewMatrix[12] += 0.01;
+    h.state.viewer.scene.preRender.raiseEvent();
+  }
+  assert.equal(h.labels[0], first);
+  assert.equal(h.publications(), publications, 'camera frames never rebuild host entries');
+  assert.equal(h.projections.size, 1, 'point projection reuses scratch storage');
+  h.lifecycle.destroy(h.state.viewer);
+  assert.equal(h.labels.length, 0);
+});
+
+
+test('wide and polygon titles use the Data Centers entry contract and persistent shared domain', (t) => {
+  const h = setup(t);
+  h.markers.sync([h.records[0], { ...h.records[1], pointOnly: false }]);
+  assert.equal(h.options.moving, false);
+  assert.equal(h.options.solveIntervalMs, undefined);
+  assert.equal(h.options.maxVisible, 24);
+  for (const entry of h.labels) {
+    const reference = createLocalInfrastructureOverlayEntry({ id: entry.id, layerId: 'military-installations', position: entry.position, properties: { name: entry.title }, priority: entry.priority, accent: entry.accent });
+    assert.deepEqual(entry, { ...reference, selected: false });
+  }
+  h.lifecycle.destroy(h.state.viewer);
+});
+
+
+test('selection promotes exactly one entry and deselection restores that same label', (t) => {
+  const h = setup(t);
+  h.markers.sync(h.records);
+  const original = h.labels[0];
+  h.state.selectedId = h.records[0].id;
+  h.markers.sync(h.records);
+  assert.equal(h.labels.length, 2);
+  assert.equal(h.labels[0], original);
+  assert.equal(original.variant, 'selected');
+  assert.equal(h.labels.filter(e => e.selected).length, 1);
+  assert.equal(h.options.maxVisible, 23);
+  h.state.selectedId = null;
+  h.markers.sync(h.records);
+  assert.equal(h.labels[0], original);
+  assert.equal(original.variant, 'card');
+  assert.equal(original.selected, false);
+  assert.deepEqual(original.details, []);
+  h.lifecycle.destroy(h.state.viewer);
+});
+
+test('Contacts can select a point outside the normal title cap or an unnamed polygon', (t) => {
+  const h = setup(t);
+  const records = Array.from({ length: 520 }, (_, i) => ({ ...h.records[0], id: `site:${i}`, areaM2: 1000 - i }));
+  records.push({ ...h.records[0], id: 'unnamed', name: 'Military area', namedArea: false, pointOnly: false });
+  for (const id of ['site:519', 'unnamed']) {
+    h.state.selectedId = id;
+    h.markers.sync(records);
+    assert.equal(h.labels[0].id, id);
+    assert.equal(h.labels[0].variant, 'selected');
+    assert.equal(h.labels.filter(e => e.selected).length, 1);
+    assert.equal(h.labels.length, 512);
+  }
+  h.lifecycle.destroy(h.state.viewer);
+});

src/layers/installations/namesLoading.test.mjs

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

src/layers/installations/navigation.test.mjs

@@ -0,0 +1,191 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { createViewport } from './viewport.js';
+import { createLifecycle } from './lifecycle.js';
+
+test('camera changes debounce, deduplicate moveEnd, cancel superseded loads and recover from wide views', (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let rectangle = Cesium.Rectangle.fromDegrees(-117.2, 32.7, -117.1, 32.8);
+  const camera = {
+    changed: new Cesium.Event(),
+    moveEnd: new Cesium.Event(),
+    percentageChanged: 0.5,
+    computeViewRectangle: () => rectangle,
+  };
+  const viewer = {
+    camera,
+    scene: { globe: { ellipsoid: Cesium.Ellipsoid.WGS84 } },
+    dataSources: { add() {}, remove() {} },
+  };
+  const state = { enabled: false, renderedKeys: new Map() };
+  const loads = [];
+  const parts = {
+    selection: { installInteraction() {} },
+    rendering: { clearRendered() {} },
+    ingestion: {
+      loadInstallations() {
+        state.abort = new AbortController();
+        loads.push({
+          ...parts.viewport.loadArea(viewer),
+          signal: state.abort.signal,
+        });
+      },
+      setInstallationStatus() {},
+    },
+  };
+  const services = {
+    picking: { registerPickOwner() {}, unregisterPickOwner() {} },
+    context: { clearSelectedEntityContextForLayer() {} },
+  };
+  const ctx = { state, parts, services, source: {} };
+  parts.viewport = createViewport(ctx);
+  const life = createLifecycle(ctx).methods;
+  life.init(viewer);
+  life.enable();
+  for (let i = 0; i < 8; i++) {
+    camera.changed.raiseEvent();
+    t.mock.timers.tick(15);
+  }
+  t.mock.timers.tick(200);
+  assert.equal(
+    loads.length,
+    1,
+    'changed alone must load, even without moveEnd',
+  );
+  camera.moveEnd.raiseEvent();
+  t.mock.timers.tick(200);
+  assert.equal(loads.length, 1);
+  assert.equal(
+    loads[0].signal.aborted,
+    false,
+    'duplicate settle must not abort its own load',
+  );
+  rectangle = Cesium.Rectangle.fromDegrees(-117.5, 33.2, -117.3, 33.4);
+  camera.changed.raiseEvent();
+  assert.equal(loads[0].signal.aborted, true);
+  t.mock.timers.tick(200);
+  assert.equal(loads.length, 2);
+  rectangle = Cesium.Rectangle.fromDegrees(-150, 10, -80, 60);
+  camera.moveEnd.raiseEvent();
+  t.mock.timers.tick(200);
+  assert.equal(
+    loads.at(-1).box.west,
+    -150,
+    'wide views reach the named-point source',
+  );
+  rectangle = Cesium.Rectangle.fromDegrees(-117.2, 32.7, -117.1, 32.8);
+  camera.changed.raiseEvent();
+  t.mock.timers.tick(200);
+  assert.ok(loads.at(-1).box);
+  state.contextAnchor = { latitude: 32.8, longitude: -117.1 };
+  const count = loads.length;
+  camera.moveEnd.raiseEvent();
+  t.mock.timers.tick(200);
+  assert.equal(loads.length, count, 'Contacts owns the anchor while active');
+  life.disable();
+  assert.equal(state.contextAnchor, null);
+  life.enable();
+  rectangle = Cesium.Rectangle.fromDegrees(-117.5, 33.2, -117.3, 33.4);
+  camera.changed.raiseEvent();
+  t.mock.timers.tick(200);
+  assert.equal(loads.at(-1).coverage.kind, 'viewport');
+  life.destroy(viewer);
+  assert.equal(camera.changed.numberOfListeners, 0);
+  assert.equal(camera.moveEnd.numberOfListeners, 0);
+  assert.equal(camera.percentageChanged, 0.5);
+});
+
+test('an aborting real ingestion cannot clear the next scheduled view key', async (t) => {
+  const { createIngestion } = await import('./ingestion.js');
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let rectangle = Cesium.Rectangle.fromDegrees(-117.2, 32.7, -117.1, 32.8);
+  const viewer = {
+    camera: { computeViewRectangle: () => rectangle },
+    scene: { globe: { ellipsoid: Cesium.Ellipsoid.WGS84 } },
+  };
+  const state = { enabled: true, viewer };
+  const pending = [];
+  const parts = {
+    rendering: { renderRecords() {}, warmInstallationFloors() {} },
+    model: { installationWithinViewport: () => true },
+  };
+  const ctx = {
+    state,
+    parts,
+    services: {
+      render: { governorRequestRender() {} },
+      ground: { resolveGroundFloorCellsBounded: async () => {} },
+    },
+    source: {
+      getMappedSites(box, { signal }) {
+        return new Promise((resolve, reject) => {
+          signal.addEventListener('abort', () => reject(signal.reason), {
+            once: true,
+          });
+          pending.push({ box, signal, resolve });
+        });
+      },
+    },
+  };
+  parts.viewport = createViewport(ctx);
+  parts.ingestion = createIngestion(ctx);
+  const flush = async () => {
+    for (let i = 0; i < 20; i++) await Promise.resolve();
+  };
+  parts.viewport.scheduleLoad();
+  t.mock.timers.tick(200);
+  assert.equal(pending.length, 1);
+  rectangle = Cesium.Rectangle.fromDegrees(-117.5, 33.2, -117.3, 33.4);
+  parts.viewport.scheduleLoad();
+  const nextKey = state.cameraLoadKey;
+  assert.equal(pending[0].signal.aborted, true);
+  await flush();
+  assert.equal(
+    state.cameraLoadKey,
+    nextKey,
+    'A finally must not clear B schedule ownership',
+  );
+  t.mock.timers.tick(200);
+  assert.equal(pending.length, 2);
+  parts.viewport.scheduleLoad();
+  t.mock.timers.tick(600);
+  assert.equal(pending.length, 2);
+  assert.equal(pending[1].signal.aborted, false);
+  pending[1].resolve({ records: [], status: 'ready' });
+  await flush();
+  assert.equal(state.loading, false);
+  assert.equal(state.cameraLoadKey, nextKey);
+});
+
+test('wide views refresh screen decluttering when the globe rectangle stays unchanged', (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const camera = {
+    positionWC: new Cesium.Cartesian3(10000000, 0, 0),
+    directionWC: new Cesium.Cartesian3(-1, 0, 0),
+    computeViewRectangle: () => Cesium.Rectangle.MAX_VALUE,
+  };
+  const state = {
+    enabled: true,
+    viewer: { camera, scene: { globe: { ellipsoid: Cesium.Ellipsoid.WGS84 } } },
+  };
+  let loads = 0;
+  const parts = {
+    ingestion: {
+      loadInstallations() {
+        loads++;
+      },
+    },
+  };
+  const viewport = createViewport({ state, parts, services: {}, source: {} });
+  viewport.scheduleLoad();
+  t.mock.timers.tick(200);
+  viewport.scheduleLoad();
+  t.mock.timers.tick(200);
+  assert.equal(loads, 1, 'the same settled camera remains deduplicated');
+  camera.positionWC = new Cesium.Cartesian3(0, 10000000, 0);
+  camera.directionWC = new Cesium.Cartesian3(0, -1, 0);
+  viewport.scheduleLoad();
+  t.mock.timers.tick(200);
+  assert.equal(loads, 2, 'a different continent needs fresh projected labels');
+});

src/layers/installations/policy.js

@@ -1,6 +1,6 @@
 export const LAYER_ID = 'military-installations';
 
-export const REQUEST_DEBOUNCE_MS = 500;
+export const REQUEST_DEBOUNCE_MS = 180;
 
 export const MAX_VIEWPORT_DEGREES = 10;
 
@@ -19,3 +19,6 @@ export const COLOR_BY_CLASS = {
 export const EARTH_MEAN_RADIUS_M = 6371008.8;
 
 export const DISTANCE_PREFILTER_MARGIN_M = 5000;
+
+/** A Contacts subject must move this far before its installation window moves. */
+export const ANCHOR_REFRESH_M = 20_000;

src/layers/installations/rendering.js

@@ -32,12 +32,104 @@ export function createRendering({
     );
   }
 
+  let selectedFillKey = null;
+  const selectedFillIds = [];
+
+  function clearSelectionFill() {
+    for (const id of selectedFillIds)
+      layerState.dataSource?.entities.removeById(id);
+    selectedFillIds.length = 0;
+    selectedFillKey = null;
+  }
+
+  /** Ground geometry classifies the active surface; no height/extrusion plane. */
+  function syncSelectionFill() {
+    const record =
+      layerState.enabled && layerState.recordById.get(layerState.selectedId);
+    if (!record) {
+      clearSelectionFill();
+      return;
+    }
+    const classificationType =
+      layerState.viewer.scene.globe?.show === false
+        ? Cesium.ClassificationType.CESIUM_3D_TILE
+        : Cesium.ClassificationType.BOTH;
+    const key = `${record.id}|${renderKey(record)}|${classificationType}`;
+    if (key === selectedFillKey) return;
+    clearSelectionFill();
+    selectedFillKey = key;
+    const footprints =
+      record.footprints || (record.footprint ? [[record.footprint]] : []);
+    const material = new Cesium.ColorMaterialProperty(
+      parts.model.colorFor(record).withAlpha(0.22),
+    );
+    for (let i = 0; i < footprints.length; i++) {
+      const rings = footprints[i];
+      const positions = (ring) =>
+        ring.map(([lon, lat]) => Cesium.Cartesian3.fromDegrees(lon, lat));
+      const fill = layerState.dataSource.entities.add({
+        id: `${record.id}:selected-fill:${i}`,
+        polygon: {
+          hierarchy: new Cesium.PolygonHierarchy(
+            positions(rings[0]),
+            rings
+              .slice(1)
+              .map((ring) => new Cesium.PolygonHierarchy(positions(ring))),
+          ),
+          material,
+          classificationType,
+        },
+      });
+      fill.installationId = record.id;
+      selectedFillIds.push(fill.id);
+    }
+    governorRequestRender('installation-selection-fill');
+  }
+
   function clearRendered() {
+    clearSelectionFill();
     if (layerState.dataSource?.entities)
       layerState.dataSource.entities.removeAll();
+    layerState.renderedKeys.clear();
     removeEntityContextsForLayer(LAYER_ID);
   }
 
+  /**
+   * Geometry identity of one rendered record. Records whose key is unchanged
+   * keep their Cesium entities across refreshes: ground-clamped outlines and
+   * classification fills rebuild asynchronously, so recreating them on every
+   * reload made unchanged sites blink.
+   * @param {object} record Installation record.
+   * @returns {string} Stable key for the record's drawn geometry.
+   */
+  function renderKey(record) {
+    const footprints =
+      record.footprints || (record.footprint ? [[record.footprint]] : []);
+    const outlines =
+      record.outlineLines || (record.footprint ? [record.footprint] : []);
+    let points = 0;
+    for (const rings of footprints)
+      for (const ring of rings) points += ring.length;
+    for (const line of outlines) points += line.length;
+    return [
+      record.latitude.toFixed(6),
+      record.longitude.toFixed(6),
+      record.class,
+      record.kind,
+      record.name,
+      footprints.length,
+      outlines.length,
+      points,
+    ].join('|');
+  }
+
+  function removeRecordEntities(id) {
+    const entities = layerState.dataSource.entities;
+    for (const entityId of layerState.renderedKeys.get(id)?.entityIds || [])
+      entities.removeById(entityId);
+    layerState.renderedKeys.delete(id);
+  }
+
   /**
    * The records that get entities this paint: the nearest `MAX_RENDERED`, plus
    * the selected one when it falls outside that window.
@@ -52,7 +144,9 @@ export function createRendering({
    */
 
   function renderableRecords() {
-    const rendered = layerState.records.slice(0, MAX_RENDERED);
+    const rendered = layerState.records
+      .filter((r) => !r.pointOnly)
+      .slice(0, MAX_RENDERED);
     if (!layerState.selectedId) return rendered;
     if (rendered.some((record) => record.id === layerState.selectedId))
       return rendered;
@@ -67,16 +161,48 @@ export function createRendering({
     if (
       !claimSelection &&
       layerState.selectedId &&
-      selectedContext &&
-      selectedContext.id !== layerState.selectedId
+      (!selectedContext || selectedContext.id !== layerState.selectedId)
     ) {
       layerState.selectedId = null;
     }
+    let migratedSelection = false;
+    if (
+      layerState.selectedId &&
+      !layerState.recordById.has(layerState.selectedId)
+    ) {
+      const replacement = layerState.records.find((record) =>
+        record.aliasIds?.includes(layerState.selectedId),
+      );
+      if (replacement) {
+        layerState.selectedId = replacement.id;
+        migratedSelection = true;
+      }
+    }
     // Post-moveEnd debounced fetches commit after the camera settles; the
     // rebuilt entities need one frame in idle mode. (perf wave 2 fix)
     governorRequestRender('installations-render');
-    clearRendered();
-    for (const record of renderableRecords()) {
+    if (
+      layerState.records.some((r) =>
+        r.sources?.some((s) => s.name === 'OpenStreetMap'),
+      )
+    )
+      services.credits?.showOsmCredit?.(layerState.viewer, LAYER_ID, {
+        openMapTiles: layerState.records.some((r) =>
+          r.sources?.some(
+            (s) => s.name === 'OpenStreetMap' && s.id?.startsWith('tile:'),
+          ),
+        ),
+      });
+    else services.credits?.hideOsmCredit?.(layerState.viewer, LAYER_ID);
+    const records = renderableRecords();
+    const keys = new Map(
+      records.map((record) => [record.id, renderKey(record)]),
+    );
+    const entities = layerState.dataSource.entities;
+    entities.suspendEvents();
+    for (const [id, rendered] of [...layerState.renderedKeys])
+      if (keys.get(id) !== rendered.key) removeRecordEntities(id);
+    for (const record of records) {
       const color = parts.model.colorFor(record);
       const surfaceHeightM = installationSurfaceHeightM(record);
       const displayPosition = Cesium.Cartesian3.fromDegrees(
@@ -84,31 +210,63 @@ export function createRendering({
         record.latitude,
         surfaceHeightM,
       );
+      const selectedRecord = record.id === layerState.selectedId;
+      const retained = layerState.renderedKeys.has(record.id)
+        ? entities.getById(record.id)
+        : null;
+      if (retained) {
+        // Same geometry: update the marker in place (selection, floor height).
+        if (retained.gevInstallationHeightM !== surfaceHeightM) {
+          retained.gevInstallationHeightM = surfaceHeightM;
+          retained.position = displayPosition;
+          retained.gevDisplayPosition = () => displayPosition;
+        }
+        if (retained.gevInstallationSelected !== selectedRecord) {
+          retained.gevInstallationSelected = selectedRecord;
+          retained.point.pixelSize = selectedRecord ? 13 : 9;
+          retained.point.color = selectedRecord ? Cesium.Color.WHITE : color;
+        }
+        continue;
+      }
+      const entityIds = [record.id];
+      layerState.renderedKeys.set(record.id, {
+        key: keys.get(record.id),
+        entityIds,
+      });
       const entity = layerState.dataSource.entities.add({
         id: record.id,
         position: displayPosition,
         point: {
+          show: !record.namedArea,
           pixelSize: record.id === layerState.selectedId ? 13 : 9,
+          heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
           color:
             record.id === layerState.selectedId ? Cesium.Color.WHITE : color,
           outlineColor: Cesium.Color.BLACK.withAlpha(0.8),
           outlineWidth: 1,
           disableDepthTestDistance: Number.POSITIVE_INFINITY,
         },
-        polygon: record.footprint
-          ? {
-              hierarchy: new Cesium.PolygonHierarchy(
-                record.footprint.map(([longitude, latitude]) =>
-                  Cesium.Cartesian3.fromDegrees(longitude, latitude),
-                ),
-              ),
-              material: color.withAlpha(0.12),
-              outline: true,
-              outlineColor: color.withAlpha(0.65),
-              height: surfaceHeightM,
-            }
-          : undefined,
       });
+      const outlines =
+        record.outlineLines || (record.footprint ? [record.footprint] : []);
+      for (let i = 0; i < outlines.length; i++) {
+        const outline = layerState.dataSource.entities.add({
+          id: `${record.id}:outline:${i}`,
+          polyline: {
+            positions: outlines[i].map(([lon, lat]) =>
+              Cesium.Cartesian3.fromDegrees(lon, lat),
+            ),
+            width: 2,
+            material: color.withAlpha(0.85),
+            clampToGround: true,
+            classificationType: Cesium.ClassificationType.BOTH,
+          },
+        });
+        outline.installationId = record.id;
+        entityIds.push(outline.id);
+      }
+      entity.gevInstallationHeightM = surfaceHeightM;
+      entity.gevInstallationSelected = selectedRecord;
       entity.gevTrackedId = `installations:${record.id}`;
       entity.gevDisplayPosition = () => displayPosition;
       entity.gevLabelModel = {
@@ -117,6 +275,7 @@ export function createRendering({
           String(record.class || 'installation')
             .replaceAll('_', ' ')
             .toUpperCase(),
+          ...(record.memberNames || []).slice(0, 3),
         ],
         accent: COLOR_BY_CLASS[record.class] || '#9ca6b0',
       };
@@ -133,6 +292,7 @@ export function createRendering({
         longitude: record.longitude,
         properties: {
           class: record.class,
+          memberNames: record.memberNames || [],
           primaryType: record.primaryType || null,
           placeTypes: Array.isArray(record.placeTypes) ? record.placeTypes : [],
           validation: record.validation,
@@ -140,11 +300,17 @@ export function createRendering({
         },
       });
     }
+    entities.resumeEvents();
     const selectedEntity = layerState.selectedId
       ? layerState.dataSource.entities.getById(layerState.selectedId)
       : null;
-    if (selectedEntity) selectEntityContext(selectedEntity);
-    else layerState.selectedId = null;
+    if (selectedEntity && (claimSelection || migratedSelection))
+      selectEntityContext(selectedEntity);
+    else if (!selectedEntity) layerState.selectedId = null;
+    // Re-register rebuilt geometry and migrate aliases before pruning old context.
+    removeEntityContextsForLayer(LAYER_ID, { retainIds: new Set(keys.keys()) });
+    parts.namedMarkers?.sync(layerState.records);
+    syncSelectionFill();
   }
 
   /**
@@ -187,6 +353,8 @@ export function createRendering({
   }
   return {
     installationSurfaceHeightM,
+    clearSelectionFill,
+    syncSelectionFill,
     clearRendered,
     renderableRecords,
     renderRecords,

src/layers/installations/selection.js

@@ -10,6 +10,24 @@ export function createSelection({
 }) {
   const { clearSelectedEntityContextForLayer } = services.context;
 
+  let removeContextListeners = null;
+
+  function syncContextSelection(event) {
+    if (!layerState.enabled) return;
+    // Tracking layers publish this event before replacing the shared context.
+    const selected =
+      event?.type === 'gev:awareness-subject-selected'
+        ? event.detail
+        : services.context.getSelectedEntityContext();
+    const next =
+      selected?.layerId === LAYER_ID && layerState.recordById.has(selected.id)
+        ? selected.id
+        : null;
+    if (next === layerState.selectedId) return;
+    layerState.selectedId = next;
+    parts.rendering.renderRecords();
+  }
+
   function selectRecord(id) {
     const record = layerState.recordById.get(id);
     if (!record || !layerState.dataSource) return false;
@@ -21,6 +39,17 @@ export function createSelection({
 
   function installInteraction(viewer) {
     if (layerState.clickHandler) return;
+    const events = [
+      'gev:entity-selected',
+      'gev:entity-selection-cleared',
+      'gev:awareness-subject-selected',
+    ];
+    for (const event of events)
+      globalThis.window?.addEventListener?.(event, syncContextSelection);
+    removeContextListeners = () => {
+      for (const event of events)
+        globalThis.window?.removeEventListener?.(event, syncContextSelection);
+    };
     layerState.clickHandler = new Cesium.ScreenSpaceEventHandler(
       viewer.scene.canvas,
     );
@@ -29,7 +58,9 @@ export function createSelection({
       if (!isPointerFree()) return;
       if (!layerState.enabled) return;
       const picked = viewer.scene.pick(click.position);
-      const id = typeof picked?.id?.id === 'string' ? picked.id.id : null;
+      const id =
+        picked?.id?.installationId ||
+        (typeof picked?.id?.id === 'string' ? picked.id.id : null);
       if (id && layerState.recordById.has(id) && id !== layerState.selectedId) {
         selectRecord(id);
       } else if (layerState.selectedId) {
@@ -42,5 +73,12 @@ export function createSelection({
       }
     }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
   }
-  return { selectRecord, installInteraction };
+  return {
+    selectRecord,
+    installInteraction,
+    destroy() {
+      removeContextListeners?.();
+      removeContextListeners = null;
+    },
+  };
 }

src/layers/installations/selection.test.mjs

@@ -0,0 +1,155 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import * as context from '../../data/contextStore.js';
+import { createSelection } from './selection.js';
+import { createRendering } from './rendering.js';
+import { createNamedMarkers } from './namedMarkers.js';
+
+function harness(t) {
+  const previousWindow = globalThis.window;
+  const previousDocument = globalThis.document;
+  globalThis.window = new EventTarget();
+  globalThis.document = new EventTarget();
+  const record = {
+    id: 'base',
+    name: 'Base',
+    class: 'base',
+    namedArea: true,
+    latitude: 0,
+    longitude: 0,
+    footprints: [
+      [
+        [
+          [0, 0],
+          [0.01, 0],
+          [0.01, 0.01],
+          [0, 0],
+        ],
+      ],
+    ],
+  };
+  const state = {
+    enabled: true,
+    selectedId: null,
+    records: [record],
+    recordById: new Map([[record.id, record]]),
+    renderedKeys: new Map(),
+    dataSource: new Cesium.CustomDataSource(),
+    viewer: {
+      camera: { positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 1e6) },
+      scene: {
+        globe: { show: false },
+        canvas: Object.assign(new EventTarget(), {
+          clientWidth: 1280,
+          clientHeight: 800,
+        }),
+        primitives: { add: (p) => p, remove() {} },
+      },
+    },
+  };
+  t.mock.method(
+    Cesium.SceneTransforms,
+    'worldToWindowCoordinates',
+    (_scene, _point, scratch) => {
+      scratch.x = 640;
+      scratch.y = 400;
+      return scratch;
+    },
+  );
+  let labels = [];
+  const services = {
+    context,
+    anchors: {},
+    ground: { floorAltitudeM: () => 0, cachedGroundFloor: () => 0 },
+    render: { governorRequestRender() {} },
+  };
+  const parts = {
+    model: {
+      colorFor: () => Cesium.Color.ORANGE,
+      installationSourceLabel: () => 'OpenStreetMap',
+    },
+  };
+  const ctx = {
+    state,
+    services,
+    parts,
+    overlayHost: {
+      setEntries(_id, entries) {
+        labels = entries;
+      },
+      clearSource() {},
+      setVisible() {},
+    },
+  };
+  parts.rendering = createRendering(ctx);
+  parts.namedMarkers = createNamedMarkers(ctx);
+  const selection = createSelection(ctx);
+  selection.installInteraction(state.viewer);
+  t.after(() => {
+    selection.destroy();
+    state.clickHandler.destroy();
+    parts.namedMarkers.destroy();
+    parts.rendering.clearRendered();
+    if (previousWindow === undefined) delete globalThis.window;
+    else globalThis.window = previousWindow;
+    if (previousDocument === undefined) delete globalThis.document;
+    else globalThis.document = previousDocument;
+  });
+  const assertSelected = (selected) => {
+    assert.equal(state.selectedId, selected ? record.id : null);
+    assert.equal(labels[0].selected, selected);
+    assert.equal(labels[0].variant, selected ? 'selected' : 'card');
+    assert.equal(
+      state.dataSource.entities.values.filter((e) => e.polygon).length,
+      selected ? 1 : 0,
+    );
+  };
+  assert.equal(selection.selectRecord(record.id), true);
+  assertSelected(true);
+  return { state, selection, assertSelected };
+}
+
+for (const layerId of ['flights', 'military', 'satellites']) {
+  for (const publishBeforeEvent of [false, true]) {
+    test(`${layerId} programmatic selection clears the installation card and fill (context first: ${publishBeforeEvent})`, (t) => {
+      const h = harness(t);
+      const subject = { id: 'other', layerId, origin: 'programmatic' };
+      if (publishBeforeEvent) context.selectTrackedSubjectContext(subject);
+      window.dispatchEvent(
+        new CustomEvent('gev:awareness-subject-selected', { detail: subject }),
+      );
+      h.assertSelected(false);
+      if (!publishBeforeEvent) context.selectTrackedSubjectContext(subject);
+      assert.equal(context.getSelectedEntityContext().id, 'other');
+      assert.equal(context.getSelectedEntityContext().layerId, layerId);
+    });
+  }
+}
+
+test('entity selection and clear still release the installation card and fill', (t) => {
+  const h = harness(t);
+  const other = {};
+  context.registerEntityContext(other, { id: 'other', layerId: 'vessels' });
+  context.selectEntityContext(other);
+  h.assertSelected(false);
+  h.selection.selectRecord('base');
+  context.clearSelectedEntityContextForLayer('military-installations');
+  h.assertSelected(false);
+});
+
+test('destroy removes all installation context listeners', (t) => {
+  const h = harness(t);
+  h.selection.destroy();
+  context.selectTrackedSubjectContext({ id: 'other', layerId: 'flights' });
+  for (const type of [
+    'gev:entity-selected',
+    'gev:entity-selection-cleared',
+    'gev:awareness-subject-selected',
+  ]) {
+    window.dispatchEvent(
+      new CustomEvent(type, { detail: { id: 'other', layerId: 'flights' } }),
+    );
+    h.assertSelected(true);
+  }
+});

src/layers/installations/selectionFill.test.mjs

@@ -0,0 +1,80 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as C from 'cesium';
+import { createRendering } from './rendering.js';
+import { createLifecycle } from './lifecycle.js';
+
+function harness() {
+  const ring = [[-97, 30], [-96.99, 30], [-96.99, 30.01], [-97, 30]];
+  const record = { id: 'base', latitude: 30, longitude: -97, name: 'Base', class: 'base', footprints: [[ring, ring.map(([x,y]) => [x+0.001,y+0.001])], [ring]] };
+  const state = { enabled: true, selectedId: 'base', records: [record], recordById: new Map([['base', record]]), renderedKeys: new Map(), dataSource: new C.CustomDataSource(), viewer: { scene: { globe: { show: false } }, camera: {} } };
+  let listener, removed = 0;
+  const noop = () => {};
+  const services = { ground: { floorAltitudeM: () => 0, cachedGroundFloor: () => 0 }, anchors: {}, render: { governorRequestRender: noop }, context: { removeEntityContextsForLayer: noop, clearSelectedEntityContextForLayer: noop }, picking: { registerPickOwner: noop, unregisterPickOwner: noop }, maps: { subscribeMapStack(cb) { listener = cb; return () => { listener = null; removed++; }; } } };
+  const parts = { model: { colorFor: () => C.Color.ORANGE, installationSourceLabel: () => 'OpenStreetMap' }, viewport: { clearUnavailableRetry: noop }, ingestion: { setInstallationStatus: noop } };
+  parts.rendering = createRendering({ state, services, parts });
+  const lifecycle = createLifecycle({ state, services, parts, source: {} }).methods;
+  return { state, record, parts, lifecycle, changeSurface: () => listener(), removed: () => removed };
+}
+
+test('selected multipart footprints classify Google tiles with one constant translucent material and holes', () => {
+  const h = harness(), render = h.parts.rendering;
+  render.syncSelectionFill();
+  const fills = h.state.dataSource.entities.values.slice();
+  assert.equal(fills.length, 2);
+  for (const fill of fills) {
+    assert.equal(fill.installationId, 'base');
+    assert.equal(fill.polygon.classificationType.getValue(), C.ClassificationType.CESIUM_3D_TILE);
+    assert.equal(fill.polygon.height, undefined);
+    assert.equal(fill.polygon.extrudedHeight, undefined);
+    assert.equal(fill.polygon.material.isConstant, true);
+    assert.equal(fill.polygon.material.color.getValue().alpha, 0.22);
+  }
+  assert.equal(fills[0].polygon.hierarchy.getValue().holes.length, 1);
+  assert.equal(fills[0].polygon.material, fills[1].polygon.material);
+  for (let i = 0; i < 100; i++) render.syncSelectionFill();
+  assert.deepEqual(h.state.dataSource.entities.values, fills, 'repaints retain ground geometry');
+  h.state.selectedId = null; render.syncSelectionFill();
+  assert.equal(h.state.dataSource.entities.values.length, 0);
+});
+
+test('surface changes reclassify selected geometry and disable tears down fills and subscription', () => {
+  const h = harness();
+  h.lifecycle.enable(); h.parts.rendering.syncSelectionFill();
+  h.state.viewer.scene.globe.show = true; h.changeSurface();
+  assert.ok(h.state.dataSource.entities.values.every(e => e.polygon.classificationType.getValue() === C.ClassificationType.BOTH));
+  h.lifecycle.disable();
+  assert.equal(h.state.dataSource.entities.values.length, 0);
+  assert.equal(h.removed(), 1);
+  h.lifecycle.enable(); h.parts.rendering.syncSelectionFill();
+  assert.equal(h.state.dataSource.entities.values.length, 0, 'reenabling cannot revive a stale selection');
+  h.lifecycle.disable();
+});
+
+
+test('geometry rebuild and canonical alias migration preserve shared selection before pruning', async () => {
+  const context = await import('../../data/contextStore.js');
+  const previousWindow = globalThis.window;
+  globalThis.window = new EventTarget();
+  try {
+    const h = harness();
+    const services = { context, render: { governorRequestRender() {} }, ground: { floorAltitudeM: () => 0, cachedGroundFloor: () => 0 }, anchors: {} };
+    const rendering = createRendering({ state: h.state, services, parts: h.parts });
+    const cleared = [];
+    window.addEventListener('gev:entity-selection-cleared', e => { cleared.push(e.detail); h.state.selectedId = null; });
+    rendering.renderRecords({ claimSelection: true });
+    const oldEntity = context.getSelectedEntityContext().entity;
+    h.record.latitude += 0.001;
+    rendering.renderRecords();
+    assert.equal(h.state.selectedId, 'base');
+    assert.equal(context.getSelectedEntityContext().id, 'base');
+    assert.notEqual(context.getSelectedEntityContext().entity, oldEntity);
+    const replacement = { ...h.record, id: 'canonical', aliasIds: ['base'] };
+    h.state.records = [replacement]; h.state.recordById = new Map([['canonical', replacement]]);
+    rendering.renderRecords();
+    assert.equal(h.state.selectedId, 'canonical');
+    assert.equal(context.getSelectedEntityContext().id, 'canonical');
+    assert.deepEqual(cleared, [], 'no transient eviction can tear down the selected card or fill');
+    rendering.clearRendered();
+  } finally { if (previousWindow === undefined) delete globalThis.window; else globalThis.window = previousWindow; }
+});

src/layers/installations/source.js

@@ -1,3 +1,22 @@
+import { waitForSignal } from '../../sources/requestDeadline.js';
+import {
+  loadMilitaryNames,
+  militaryNamesInView,
+  nameMilitaryFragment,
+} from '../../data/militaryNames.js';
+import {
+  createOpenFreeMapSource,
+  decodeOpenFreeMapMilitaryTile,
+} from '../../sources/openFreeMap.js';
+import {
+  mergeMilitaryFragments,
+  militaryNameInView,
+} from '../../sources/militaryTileGeometry.js';
+import { tilesForBounds } from '../../data/tomtomTiles.js';
+import {
+  isUnavailableCapability,
+  sourceResponseError,
+} from '../../sources/capability.js';
 import { normalizeMilitaryInstallations } from '../../data/militaryInstallationData.js';
 
 /** Preserve legacy cache admission even when the explicit saturation flag is absent. */
@@ -8,11 +27,160 @@ export function installationResponseSaturated(payload) {
   return Array.isArray(payload?.elements) && payload.elements.length >= cap;
 }
 
+/**
+ * OpenMapTiles carries `landuse=military` only from z9; coarser tiles omit it,
+ * so a view that needs them would read as an empty (falsely all-clear) area.
+ */
+export const MILITARY_TILE_MIN_ZOOM = 9;
+
+/** Per-view tile cap for installation tiles. */
+export const MILITARY_TILE_MAX = 16;
+
+/**
+ * Pick the finest installation tile zoom that fits the view, or null when even
+ * z9 would exceed the tile cap (the caller uses bundled named points).
+ * @param {{south:number, west:number, north:number, east:number}} box View box.
+ * @returns {number|null} Tile zoom.
+ */
+export function installationTileZoom(box) {
+  let zoom =
+    Math.max(box.north - box.south, box.east - box.west) > 0.2 ? 10 : 12;
+  const fits = (z) =>
+    tilesForBounds(box, z, { maxTiles: MILITARY_TILE_MAX + 1 }).length <=
+    MILITARY_TILE_MAX;
+  while (zoom > MILITARY_TILE_MIN_ZOOM && !fits(zoom)) zoom -= 1;
+  return fits(zoom) ? zoom : null;
+}
+
+/**
+ * Square window around a context subject that fits the installation tile cap
+ * at the military minimum zoom: 100 km half-width at mid latitudes, shrinking
+ * toward the poles where z9 tiles are shorter.
+ * @param {{latitude:number, longitude:number}} anchor Subject position.
+ * @returns {{south:number, west:number, north:number, east:number,
+ *   radiusM:number}|null} Bounded box, or null for an invalid anchor.
+ */
+export function installationAnchorBox(anchor) {
+  const { latitude, longitude } = anchor || {};
+  if (
+    !Number.isFinite(latitude) ||
+    !Number.isFinite(longitude) ||
+    Math.abs(latitude) > 85 ||
+    Math.abs(longitude) > 180
+  )
+    return null;
+  for (let radiusM = 100_000; radiusM >= 10_000; radiusM *= 0.8) {
+    const latSpan = radiusM / 111_320;
+    const lonSpan =
+      latSpan / Math.max(0.05, Math.cos((latitude * Math.PI) / 180));
+    const box = {
+      south: Math.max(-85, latitude - latSpan),
+      north: Math.min(85, latitude + latSpan),
+      west: Math.max(-180, longitude - lonSpan),
+      east: Math.min(180, longitude + lonSpan),
+    };
+    if (
+      tilesForBounds(box, MILITARY_TILE_MIN_ZOOM, {
+        maxTiles: MILITARY_TILE_MAX + 1,
+      }).length <= MILITARY_TILE_MAX
+    )
+      return { ...box, radiusM: Math.round(radiusM) };
+  }
+  return null;
+}
+
 /** Read mapped installations and explicit nearby-place searches through fixed endpoints. */
 export function createInstallationSource({
   fetchImpl = (...args) => globalThis.fetch(...args),
+  tileFetchImpl = (...args) => globalThis.fetch(...args),
+  loadNames = loadMilitaryNames,
+  mapTiles = createOpenFreeMapSource({
+    fetchImpl: tileFetchImpl,
+    decode: decodeOpenFreeMapMilitaryTile,
+  }),
 } = {}) {
+  let overpassUnavailable = false;
+  const installationIds = new Map();
+  async function getNamedSites(box, signal) {
+    const names = await waitForSignal(loadNames(), signal).catch((cause) => {
+      signal?.throwIfAborted();
+      throw Object.assign(
+        new Error('Mapped names temporarily unavailable', { cause }),
+        {
+          failureReason: 'names_unavailable',
+        },
+      );
+    });
+    signal?.throwIfAborted();
+    const { records, count } = militaryNamesInView(names, box);
+    return {
+      records,
+      namedInView: count,
+      wide: true,
+      status: 'ready',
+      tileSource: true,
+      saturated: false,
+      droppedCount: 0,
+      source: 'OpenStreetMap',
+    };
+  }
+  async function getTileSites(box, signal) {
+    const zoom = installationTileZoom(box);
+    if (zoom === null) return getNamedSites(box, signal);
+    let names = null;
+    const namesJob = waitForSignal(loadNames(), signal)
+      .then((loaded) => {
+        names = loaded;
+        return loaded;
+      })
+      .catch(() => null);
+    let result;
+    try {
+      result = await mapTiles.fetchBounds(box, { zoom, signal });
+    } catch (error) {
+      if (error?.name === 'AbortError' || signal?.aborted) throw error;
+      // Name the tile source: an Overpass reason here would be untrue.
+      throw Object.assign(
+        error instanceof Error ? error : new Error(String(error)),
+        {
+          failureReason: 'tiles_unavailable',
+        },
+      );
+    }
+    signal?.throwIfAborted();
+    const snapshot = (names) => {
+      const fragments = result.tiles
+        .flatMap((tile) => tile.military)
+        .map((record) => nameMilitaryFragment(record, names));
+      const retrievedAt = new Date().toISOString();
+      return {
+        records: mergeMilitaryFragments(
+          fragments.slice(0, 2048),
+          installationIds,
+        ).map((record) => ({
+          ...militaryNameInView(record, box),
+          retrievedAt,
+          sources: record.sources.map((source) => ({ ...source, retrievedAt })),
+        })),
+        status: 'ready',
+        droppedCount: 0,
+        saturated: result.partial || fragments.length > 2048,
+        source: 'OpenStreetMap tiles',
+        tileSource: true,
+      };
+    };
+    const payload = snapshot(names);
+    if (!names)
+      payload.enrichment = namesJob.then((loaded) =>
+        loaded && !signal?.aborted ? snapshot(loaded) : null,
+      );
+    return payload;
+  }
   return {
+    destroy() {
+      mapTiles.clear();
+      installationIds.clear();
+    },
     async getMappedSites(box, { exact = false, signal } = {}) {
       const { south, west, north, east } = box || {};
       if (
@@ -20,14 +188,17 @@ export function createInstallationSource({
         south < -90 ||
         north > 90 ||
         west < -180 ||
+        west > 180 ||
+        east < -180 ||
         east > 180 ||
         north <= south ||
-        east <= west ||
-        north - south > 10 ||
-        east - west > 10
+        east === west
       )
         throw new TypeError('A bounded installation viewport is required');
       signal?.throwIfAborted();
+      if (east < west || north - south > 10 || east - west > 10)
+        return getNamedSites(box, signal);
+      if (overpassUnavailable) return getTileSites(box, signal);
       const query = new URLSearchParams(
         Object.entries({ south, west, north, east }).map(([key, value]) => [
           key,
@@ -40,9 +211,17 @@ export function createInstallationSource({
       });
       const body = await response.json();
       signal?.throwIfAborted();
+      if (isUnavailableCapability(body)) {
+        overpassUnavailable = true;
+        return getTileSites(box, signal);
+      }
       if (!response.ok)
         throw Object.assign(
-          new Error(body?.error || `Installation feed HTTP ${response.status}`),
+          sourceResponseError(
+            body,
+            response,
+            'Installation context unavailable',
+          ),
           {
             failureReason: ['rate_limited', 'timeout', 'query_failed'].includes(
               body?.reason,

src/layers/installations/source.test.mjs

@@ -1,8 +1,43 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { createInstallationSource } from './source.js';
+import { readFileSync } from 'node:fs';
+import { tilesForBounds } from '../../data/tomtomTiles.js';
+import { installationFeedback } from '../../data/installationFeedback.js';
+import {
+  createInstallationSource,
+  installationAnchorBox,
+  installationTileZoom,
+  MILITARY_TILE_MAX,
+  MILITARY_TILE_MIN_ZOOM,
+} from './source.js';
+import {
+  decodeOpenFreeMapMilitaryTile,
+  decodeOpenFreeMapTile,
+} from '../../sources/openFreeMap.js';
 
 const box = { south: 30.1, west: -97.9, north: 30.3, east: -97.6 };
+test('a wide-view pack failure names the unavailable data without an API fallback', async () => {
+  const source = createInstallationSource({
+    fetchImpl: async () => assert.fail('no API request for bundled names'),
+    loadNames: async () => {
+      throw new Error('asset unavailable');
+    },
+  });
+  await assert.rejects(
+    source.getMappedSites({ south: 20, west: -130, north: 60, east: -60 }),
+    (error) => {
+      assert.equal(error.failureReason, 'names_unavailable');
+      assert.equal(
+        installationFeedback({
+          status: 'unavailable',
+          failureReason: error.failureReason,
+        }),
+        'Mapped names temporarily unavailable',
+      );
+      return true;
+    },
+  );
+});
 test('mapped-site sources validate viewport bounds and preserve the exact retry key', async () => {
   const calls = [];
   const source = createInstallationSource({
@@ -14,7 +49,7 @@ test('mapped-site sources validate viewport bounds and preserve the exact retry
   for (const invalid of [
     null,
     { ...box, east: Infinity },
-    { ...box, north: 90 },
+    { ...box, north: 91 },
     { ...box, south: 31 },
   ])
     await assert.rejects(
@@ -84,3 +119,146 @@ test('mapped-site sources normalize records and derive saturation from legacy ca
   assert.equal(payload.status, 'stale');
   assert.equal('elements' in payload, false);
 });
+
+test('installation tiles never drop below z9, where military areas exist', () => {
+  // OpenMapTiles omits landuse=military below z9; a z6-z8 view used to read as
+  // an empty, "Mapped sites loaded" area in Cockpit and wide follow views.
+  assert.equal(
+    installationTileZoom({
+      south: 30.3,
+      west: -97.8,
+      north: 30.33,
+      east: -97.74,
+    }),
+    12,
+  );
+  assert.equal(
+    installationTileZoom({ south: 30, west: -98, north: 31, east: -97 }),
+    10,
+  );
+  assert.equal(
+    installationTileZoom({ south: 30, west: -98.2, north: 31.4, east: -96.8 }),
+    9,
+  );
+  assert.equal(
+    installationTileZoom({ south: 28, west: -100, north: 32, east: -96 }),
+    null,
+  );
+});
+
+test('a Contacts window fits the tile cap at z9 from the tropics to the Arctic', () => {
+  for (const latitude of [0, 30.3125, 51.5, 60, 70]) {
+    const box = installationAnchorBox({ latitude, longitude: -97.765 });
+    assert.ok(box, `window at ${latitude}`);
+    assert.ok(
+      tilesForBounds(box, MILITARY_TILE_MIN_ZOOM, { maxTiles: 64 }).length <=
+        MILITARY_TILE_MAX,
+    );
+    assert.ok(box.south < latitude && box.north > latitude);
+  }
+  assert.equal(
+    installationAnchorBox({ latitude: 30.3125, longitude: -97.765 }).radiusM,
+    100_000,
+  );
+  assert.ok(
+    installationAnchorBox({ latitude: 60, longitude: 10 }).radiusM < 100_000,
+  );
+  assert.equal(
+    installationAnchorBox({ latitude: Number.NaN, longitude: 0 }),
+    null,
+  );
+});
+
+test('too-wide tile views use bundled named points without requesting tiles', async () => {
+  const fetched = [];
+  const source = createInstallationSource({
+    fetchImpl: async () =>
+      Response.json({ code: 'OVERPASS_NOT_CONFIGURED', retryable: false }),
+    mapTiles: {
+      clear() {},
+      async fetchBounds(box, { zoom }) {
+        fetched.push(zoom);
+        return { tiles: [], partial: false };
+      },
+    },
+  });
+  const wide = await source.getMappedSites({
+    south: 28,
+    west: -100,
+    north: 32,
+    east: -96,
+  });
+  assert.equal(wide.wide, true);
+  assert.equal(wide.status, 'ready');
+  assert.ok(wide.records.some((r) => r.name === 'Fort Hood'));
+  assert.ok(wide.records.every((r) => r.namedArea));
+  assert.deepEqual(
+    fetched,
+    [],
+    'no tile request for a view the tiles cannot answer',
+  );
+  await source.getMappedSites({
+    south: 30,
+    west: -98.2,
+    north: 31.4,
+    east: -96.8,
+  });
+  assert.deepEqual(fetched, [9]);
+});
+
+test('the military-only decoder keeps Camp Mabry and skips road geometry', () => {
+  const bytes = readFileSync(
+    new URL(
+      '../../data/fixtures/ofm-camp-mabry-12-935-1685.pbf',
+      import.meta.url,
+    ),
+  );
+  const full = decodeOpenFreeMapTile(bytes, 12, 935, 1685);
+  const military = decodeOpenFreeMapMilitaryTile(bytes, 12, 935, 1685);
+  assert.ok(full.roads.length > 0);
+  assert.equal(military.roads.length, 0);
+  assert.deepEqual(
+    military.military.map((record) => record.id),
+    full.military.map((record) => record.id),
+  );
+});
+
+test('installation API transports never receive vector-tile URLs', async (t) => {
+  const calls = [];
+  const tileFetch = async (url) => {
+    calls.push(url);
+    return url.endsWith('/planet')
+      ? Response.json({
+          tiles: ['https://tiles.openfreemap.org/test/{z}/{x}/{y}.pbf'],
+        })
+      : new Response(
+          readFileSync(
+            new URL(
+              '../../data/fixtures/ofm-camp-mabry-12-935-1685.pbf',
+              import.meta.url,
+            ),
+          ),
+        );
+  };
+  t.mock.method(globalThis, 'fetch', tileFetch);
+  for (const tileFetchImpl of [undefined, tileFetch]) {
+    const source = createInstallationSource({
+      tileFetchImpl,
+      fetchImpl: async (url) => {
+        assert.ok(url.startsWith('/api/'));
+        return Response.json({
+          code: 'OVERPASS_NOT_CONFIGURED',
+          retryable: false,
+        });
+      },
+    });
+    const data = await source.getMappedSites({
+      south: 30.3,
+      west: -97.77,
+      north: 30.32,
+      east: -97.75,
+    });
+    assert.ok(data.records.length);
+  }
+  assert.ok(calls.length >= 4);
+});

src/layers/installations/state.js

@@ -32,6 +32,14 @@ export function createState({ services }) {
     clickHandler: null,
     timer: null,
     googleSearchRequested: false,
+    /** Contacts subject position; when set, it replaces the camera viewport. */
+    contextAnchor: null,
+    /** Latest subject centre, independent of the retained tile-fetch anchor. */
+    contextPosition: null,
+    /** Coverage of the last successful load: viewport, or radius around a subject. */
+    coverage: { kind: 'viewport' },
+    /** Per-record geometry keys of the rendered entities, for in-place updates. */
+    renderedKeys: new Map(),
   });
   return state;
 }

src/layers/installations/viewport.js

@@ -1,7 +1,27 @@
 import * as Cesium from 'cesium';
-import { MAX_VIEWPORT_DEGREES, REQUEST_DEBOUNCE_MS } from './policy.js';
+import { REQUEST_DEBOUNCE_MS } from './policy.js';
+import { installationAnchorBox } from './source.js';
 
 export function createViewport({ state: layerState, services, parts, source }) {
+  /**
+   * The area this load describes: the window around a Contacts subject while
+   * one is set (a follow or Cockpit camera never settles and often looks at the
+   * horizon), otherwise the settled camera viewport.
+   * @param {object} viewer Cesium viewer.
+   * @returns {{box: object|null, coverage: object}} Query box and its coverage.
+   */
+  function loadArea(viewer) {
+    const anchor = layerState.contextAnchor;
+    if (anchor) {
+      const box = installationAnchorBox(anchor);
+      if (box) {
+        const { radiusM, ...bounds } = box;
+        return { box: bounds, coverage: { kind: 'subject', radiusM } };
+      }
+    }
+    return { box: viewportBox(viewer), coverage: { kind: 'viewport' } };
+  }
+
   function viewportBox(viewer) {
     const rectangle = viewer?.camera?.computeViewRectangle(
       viewer.scene.globe.ellipsoid,
@@ -11,12 +31,11 @@ export function createViewport({ state: layerState, services, parts, source }) {
     const north = Cesium.Math.toDegrees(rectangle.north);
     const west = Cesium.Math.toDegrees(rectangle.west);
     const east = Cesium.Math.toDegrees(rectangle.east);
-    // Cross-dateline/global views require a zoom before a bounded request.
+    // Wide and dateline views use the bundled point index.
     if (
       !Number.isFinite(south + north + west + east) ||
-      east <= west ||
-      north - south > MAX_VIEWPORT_DEGREES ||
-      east - west > MAX_VIEWPORT_DEGREES
+      east === west ||
+      north <= south
     )
       return null;
     return { south, west, north, east };
@@ -44,10 +63,13 @@ export function createViewport({ state: layerState, services, parts, source }) {
    * zoom-out, or disable cancels it.
    */
 
-  function scheduleUnavailableRetry() {
+  function scheduleUnavailableRetry(retryAfterMs = 0) {
     if (!layerState.enabled) return;
     clearTimeout(layerState.retryTimer);
-    layerState.retryDelayMs = installationRetryDelayMs(layerState.retryDelayMs);
+    layerState.retryDelayMs = Math.max(
+      retryAfterMs,
+      installationRetryDelayMs(layerState.retryDelayMs),
+    );
     layerState.retryAt = Date.now() + layerState.retryDelayMs;
     layerState.retryTimer = setTimeout(() => {
       layerState.retryTimer = null;
@@ -66,15 +88,36 @@ export function createViewport({ state: layerState, services, parts, source }) {
 
   function scheduleLoad() {
     if (!layerState.enabled) return;
+    const { box, coverage } = loadArea(layerState.viewer);
+    const camera = layerState.viewer.camera;
+    const widePose =
+      coverage.kind === 'viewport' &&
+      box &&
+      (box.east < box.west ||
+        box.east - box.west > 10 ||
+        box.north - box.south > 10)
+        ? [camera.positionWC, camera.directionWC]
+            .map((v) =>
+              v ? [v.x, v.y, v.z].map((n) => n.toFixed(4)).join(',') : '',
+            )
+            .join(':')
+        : '';
+    const key = `${coverage.kind}:${box ? [box.south, box.west, box.north, box.east].map((v) => v.toFixed(6)).join(',') : 'wide'}:${widePose}`;
+    if (layerState.cameraLoadKey === key && !layerState.error) return;
+    layerState.cameraLoadKey = key;
+    layerState.cameraLoadOwner = {};
+    layerState.abort?.abort();
     // A user-driven load supersedes any pending retry; the load reschedules on
     // failure, so the backoff step is kept rather than reset.
     clearUnavailableRetry({ resetBackoff: false });
     clearTimeout(layerState.timer);
     layerState.timer = setTimeout(() => {
+      layerState.timer = null;
       parts.ingestion.loadInstallations();
     }, REQUEST_DEBOUNCE_MS);
   }
   return {
+    loadArea,
     viewportBox,
     installationRetryDelayMs,
     scheduleUnavailableRetry,

src/layers/traffic/animation.js

@@ -1,3 +1,4 @@
+import { DOT_FADE_MS } from './retention.js';
 import { flowBucket, flowSpeedScale } from '../../data/trafficFlowStyle.js';
 import { presetDotOutline } from '../../data/trafficPresetStyle.js';
 import * as Cesium from 'cesium';
@@ -6,7 +7,6 @@ import {
   SPEED_MPS,
   MAX_DOTS,
   JAM_DOT_FAR_SCALE,
-  JAM_DOT_DEPTH_PUNCH,
   CREEP_MOVE_MS,
   CREEP_STOP_MS,
   CREEP_BURST,
@@ -129,11 +129,10 @@ export function createAnimation({
         layerState._scratchLerp,
       );
 
-      // Jam-viz density prototype: jam dots stay visible at city scale — a
-      // longer depth-test punch-through (single-sample road heights sit under
-      // the mesh at oblique views) and a higher far-scale floor. Sim dots and
-      // other buckets keep the shipped values.
+      // Grounded traffic respects building/terrain occlusion. The former
+      // depth override made distant roads look like vehicles crossing roofs.
       const jamProminent = bucket === 'jam' && parts.style.jamDensityOn();
+      const id = layerState._nextDotId++;
       const point = layerState._pointCollection.add({
         position: Cesium.Cartesian3.clone(layerState._scratchLerp),
         pixelSize,
@@ -151,8 +150,8 @@ export function createAnimation({
           layerState._fadeTransFar,
           0.0,
         ),
-        // visible through tiles only when very close (jam: city-scale punch)
-        disableDepthTestDistance: jamProminent ? JAM_DOT_DEPTH_PUNCH : 2000,
+        // Respect the sampled mesh at every viewing distance.
+        disableDepthTestDistance: 0,
         // Preset dark halo (spread only when present — the keyless/normal
         // path passes the exact shipped option set).
         ...(outlineSpec
@@ -161,7 +160,14 @@ export function createAnimation({
       });
       layerState._bucketCounts[bucket || 'sim'] += 1;
 
+      layerState._motion.added++;
       layerState._dots.push({
+        id,
+        index: layerState._dots.length,
+        born: now,
+        retiring: 0,
+        nominalSize: pixelSize,
+        recycle: false,
         point,
         road,
         bucket, // flow bucket at spawn (null = sim) — drives preset restyle/pulse
@@ -188,11 +194,11 @@ export function createAnimation({
    * Per-frame animation callback registered on `scene.preRender`.
    *
    * For every active dot:
-   *  1. Skip if currently paused by a simulated stop-light.
+   *  1. Ease heights and fade arrivals/departures, including paused dots.
    *  2. Convert speed (m/s) to a parametric t-delta relative to the current
    *     segment's Cartesian distance.
    *  3. Advance t in the dot's travel direction, handling segment boundary
-   *     crossings and end-of-road reversals.
+   *     crossings and faded end-of-road departures.
    *  4. Linearly interpolate between the two bounding waypoints and update the
    *     point primitive's position.
    *
@@ -207,55 +213,76 @@ export function createAnimation({
       : 0.016;
     layerState._lastAnimTime = now;
 
+    parts.retention.easeHeights(dt);
     for (let i = 0; i < layerState._dots.length; i++) {
       const dot = layerState._dots[i];
-
-      // Simulated stop-light pause — skip movement while timer is active
-      if (now < dot.stoppedUntil) continue;
+      if (dot.recycle) {
+        // A road-end departure is a new simulated vehicle at the entry, never
+        // a teleport attributed to the departed vehicle's stable identity.
+        dot.id = layerState._nextDotId++;
+        dot.segIdx = dot.direction > 0 ? 0 : dot.numSegments - 1;
+        dot.t = dot.direction > 0 ? 0 : 1;
+        dot.born = now;
+        dot.recycle = false;
+        layerState._motion.recycled++;
+      }
+      const remaining =
+        dot.direction > 0
+          ? dot.segIdx === dot.numSegments - 1
+            ? (1 - dot.t) * dot.segmentDist[dot.segIdx]
+            : Infinity
+          : dot.segIdx === 0
+            ? dot.t * dot.segmentDist[0]
+            : Infinity;
+      const endpointFade = Math.min(1, remaining / Math.max(1, dot.mps * 0.25));
+      dot.point.pixelSize =
+        dot.nominalSize *
+        Math.max(
+          0,
+          Math.min(
+            1,
+            (now - dot.born) / DOT_FADE_MS,
+            dot.retiring ? 1 - (now - dot.retiring) / DOT_FADE_MS : 1,
+            endpointFade,
+          ),
+        );
 
       // Stop-and-go creep (jam-viz density prototype, live jam dots only):
       // alternate short forward bursts with stops. The burst multiplier keeps
       // the long-run average near the honest TomTom crawl speed.
-      let burst = 1;
+      let burst = now < dot.stoppedUntil ? 0 : 1;
       if (dot.creep) {
         if (now >= dot.creep.until) {
           dot.creep.moving = !dot.creep.moving;
           const [lo, hi] = dot.creep.moving ? CREEP_MOVE_MS : CREEP_STOP_MS;
           dot.creep.until = now + lo + Math.random() * (hi - lo);
         }
-        if (!dot.creep.moving) continue;
-        burst = CREEP_BURST;
+        if (!dot.creep.moving) burst = 0;
+        else burst *= CREEP_BURST;
       }
 
-      // Convert m/s speed to parametric t-delta for the current segment length
-      const segLen = dot.segmentDist[dot.segIdx] || 1;
-      const tDelta = (dot.mps * burst * dt) / segLen;
-
-      // Advance parametric position along the road in the current direction
-      dot.t += tDelta * dot.direction;
-
-      // Handle forward segment boundary crossing (t >= 1.0)
-      if (dot.t >= 1.0) {
-        dot.t -= 1.0;
-        dot.segIdx++;
-        if (dot.segIdx >= dot.numSegments) {
-          // End of road: recycle to the road's entry with a small stagger —
-          // cars don't reverse at the end of a street (field-test round 1).
-          // Direction is preserved, so one-way flow stays legal.
-          dot.segIdx = 0;
-          dot.t = Math.random() * 0.3;
+      // Carry metres across bends, not a t fraction from a differently sized
+      // segment. Short segments cannot turn a slow car into a large jump.
+      let travel = dot.mps * burst * dt;
+      while (travel > 0) {
+        const length = Math.max(0.001, dot.segmentDist[dot.segIdx]);
+        const available = (dot.direction > 0 ? 1 - dot.t : dot.t) * length;
+        if (travel < available) {
+          dot.t += (travel / length) * dot.direction;
+          break;
         }
-        maybeStopLight(dot, now);
-      } else if (dot.t <= 0.0) {
-        // Handle backward segment boundary crossing (t <= 0.0)
-        dot.t += 1.0;
-        dot.segIdx--;
-        if (dot.segIdx < 0) {
-          // Start of road (traveling backward): recycle to the far end.
-          dot.segIdx = dot.numSegments - 1;
-          dot.t = 1.0 - Math.random() * 0.3;
+        travel -= available;
+        const next = dot.segIdx + dot.direction;
+        if (next < 0 || next >= dot.numSegments) {
+          dot.t = dot.direction > 0 ? 1 : 0;
+          dot.point.pixelSize = 0;
+          dot.recycle = true;
+          break;
         }
+        dot.segIdx = next;
+        dot.t = dot.direction > 0 ? 0 : 1;
         maybeStopLight(dot, now);
+        if (now < dot.stoppedUntil) break;
       }
 
       // Lerp between pre-computed Cartesian3 waypoints (no trig needed).
@@ -302,6 +329,9 @@ export function createAnimation({
   /** Remove all point primitives and reset dot/road arrays and counters. */
 
   function clearDots() {
+    services.credits?.hideOsmCredit?.(layerState._viewer, 'traffic');
+    parts.retention.clear();
+    if (layerState._dots.length) layerState._motion.rebuilds++;
     if (layerState._pointCollection) layerState._pointCollection.removeAll();
     parts.rendering.removeHeatLines();
     layerState._dots = [];

src/layers/traffic/controls.js

@@ -1,3 +1,8 @@
+import {
+  normalizeRoadMode,
+  resolveRoadMode,
+  TRAFFIC_ROAD_MODES,
+} from './roadModes.js';
 import {
   trafficBucketTier,
   trafficStyleProfile,
@@ -5,6 +10,33 @@ import {
 import { TRAFFIC_TIMING_ENABLED } from './policy.js';
 
 export function createControls({ state: layerState, services, parts, source }) {
+  /** One status line: feed, drawn road source, then degraded-coverage notes. */
+  function roadStatusLabel(feed) {
+    const source = layerState._roadSource;
+    if (layerState._roadError)
+      return `UNAVAILABLE · ${source} · Roads unavailable`;
+    const notes = [feed.loadingLabel];
+    if (!layerState._liveMode || feed.error) notes.push(`Roads: ${source}`);
+    // An explicit TomTom or Hybrid choice without a key draws OpenStreetMap.
+    if (
+      !layerState._liveMode &&
+      ['tomtom', 'hybrid'].includes(layerState._roadMode)
+    )
+      notes.push(
+        layerState._flowStatusUnavailable
+          ? `${layerState._roadMode === 'tomtom' ? 'TomTom roads' : 'Hybrid'} unavailable while the traffic service is unreachable`
+          : layerState._roadMode === 'tomtom'
+            ? 'TomTom roads need a TomTom key'
+            : 'Hybrid needs a TomTom key',
+      );
+    if (layerState._surfacePending) notes.push('Local surface still loading');
+    if (layerState._roadWarning) notes.push(layerState._roadWarning);
+    else if (layerState._roadPartial) notes.push('Partial coverage');
+    if (layerState._detailError) notes.push('Detailed roads unavailable');
+    else if (layerState._detailLimited) notes.push('Reduced detail coverage');
+    return notes.join(' · ');
+  }
+
   const { getFlowSessionStats } = source;
 
   const methods = {
@@ -14,19 +46,48 @@ export function createControls({ state: layerState, services, parts, source }) {
 
     icon: '🚗',
 
-    source: 'OpenStreetMap',
+    source: 'OpenStreetMap / TomTom',
 
     /** @type {number} Zero — layer is self-managed via camera listener + preRender */
     updateInterval: 0,
 
     /**
-     * Update user-adjustable parameters (density and speed scaling).
+     * Update user-adjustable parameters (road source, density and speed scaling).
      *
      * @param {Object}  [params]
+     * @param {'tomtom'|'osm'|'hybrid'|null} [params.roadMode] - Road source; null = default.
      * @param {number}  [params.densityScale] - Dot density multiplier (clamped 0.2–2.5).
      * @param {number}  [params.speedScale]   - Dot speed multiplier (clamped 0.3–3.0).
+     * @param {{origin?:string}} [options] - Intent origin; restores never beat `?trafficRoads=`.
      */
-    setParams(params = {}) {
+    setParams(params = {}, { origin } = {}) {
+      const previousDensity = layerState._densityScale;
+      const previousSpeed = layerState._speedScale;
+      if (
+        Object.hasOwn(params, 'roadMode') &&
+        (params.roadMode === null || normalizeRoadMode(params.roadMode))
+      ) {
+        const explicit = ['user', 'voice', 'tool'].includes(origin);
+        const mode =
+          !explicit && layerState._roadModeUrlOverride
+            ? layerState._roadModeUrlOverride
+            : params.roadMode;
+        if (explicit) layerState._roadModeUrlOverride = null;
+        if (mode !== layerState._roadMode) {
+          layerState._roadMode = mode;
+          // Redraw from scratch: a different source means different roads.
+          parts.ingestion.cancelActiveFetch();
+          clearTimeout(layerState._retryTimer);
+          layerState._retryTimer = null;
+          layerState._loadGeneration++;
+          layerState._fetching = false;
+          layerState._lastBounds = null;
+          layerState._lastViewCenter = null;
+          parts.animation.clearDots();
+          if (layerState._enabled)
+            parts.viewport.onCameraChanged({ immediate: true });
+        }
+      }
       if (typeof params.densityScale === 'number') {
         layerState._densityScale = Math.max(
           0.2,
@@ -39,6 +100,23 @@ export function createControls({ state: layerState, services, parts, source }) {
           Math.min(3.0, params.speedScale),
         );
       }
+      if (layerState._speedScale !== previousSpeed) {
+        const ratio = layerState._speedScale / previousSpeed;
+        for (const dot of layerState._dots) {
+          dot.baseMps *= ratio;
+          dot.mps *= ratio;
+        }
+      }
+      if (
+        layerState._densityScale !== previousDensity &&
+        layerState._enabled &&
+        layerState._roads.length
+      )
+        parts.rendering.renderRoadsForAltitude(
+          layerState._roads,
+          layerState._lastRenderAltitude,
+          'Density',
+        );
       // Live-mode treatment of roads TomTom has no flow data for:
       // 'sim' (default) keeps them as today's white ambient dots — colored =
       // real data, white = simulation; 'hide' spawns nothing on them (strict
@@ -70,6 +148,7 @@ export function createControls({ state: layerState, services, parts, source }) {
      */
     getParams() {
       return {
+        roadMode: layerState._roadMode,
         densityScale: layerState._densityScale,
         speedScale: layerState._speedScale,
         uncoveredRoads: layerState._uncoveredMode,
@@ -78,6 +157,28 @@ export function createControls({ state: layerState, services, parts, source }) {
       };
     },
 
+    /** Road-source chips on the Street Traffic row (TomTom / OSM / Hybrid). */
+    getRowControls() {
+      const selected =
+        layerState._roadMode || resolveRoadMode(null, layerState._liveMode);
+      const needsKey = layerState._liveMode ? '' : ' (needs a TomTom key)';
+      const titles = {
+        tomtom: `TomTom roads only, each with its live flow${needsKey}`,
+        osm: 'OpenStreetMap roads, with TomTom flow matched when available',
+        hybrid: `TomTom roads first; OpenStreetMap fills the rest, simulated${needsKey}`,
+      };
+      const labels = { tomtom: 'TomTom', osm: 'OSM', hybrid: 'Hybrid' };
+      return {
+        chips: TRAFFIC_ROAD_MODES.map((mode) => ({
+          id: `roads-${mode}`,
+          label: labels[mode],
+          title: titles[mode],
+          active: mode === selected,
+          params: { roadMode: mode },
+        })),
+      };
+    },
+
     /**
      * Return a sub-sampled list of active dot positions for detection overlays
      * (e.g. CCTV bounding-box rendering).
@@ -106,7 +207,7 @@ export function createControls({ state: layerState, services, parts, source }) {
         if (!pos) continue;
         const entry = {
           position: pos,
-          id: `VEH-${String(i).padStart(4, '0')}`,
+          id: `VEH-${String(layerState._dots[i].id).padStart(4, '0')}`,
           type: 'VEH',
         };
         // Live mode: the detection bracket carries the congestion signal —
@@ -124,38 +225,94 @@ export function createControls({ state: layerState, services, parts, source }) {
       return result;
     },
 
+    /** Visit stable dot identities and their owning geometry without allocating snapshots. */
+    visitMotionDots(visitor) {
+      for (let i = 0; i < layerState._dots.length; i++) {
+        const dot = layerState._dots[i];
+        visitor(dot.id, dot.road.key, dot.point, dot.road);
+      }
+    },
+
     /**
      * Return current layer statistics for UI status chips.
      * `mode` is the CONFIGURED source — 'live' (a TomTom key is present) or
      * 'sim' (keyless simulation, which the manager renders as a FALLBACK chip);
      * `error` carries this instant's health, so a live-configured layer whose
      * flow feed went down reads DEGRADED with the reason instead of a stale
-     * LIVE coverage number. `flowCoveragePct` is matched roads / roads with any
-     * flow candidates (0–100 int); `tilesFetched` counts flow-tile requests
+     * LIVE coverage number. `flowCoveragePct` is shown dots on matched roads /
+     * all shown dots (0–100 int), excluding closures; `tilesFetched` counts flow-tile requests
      * issued to the proxy this session (decode-cache hits excluded).
      * @returns {{count:number, lastUpdate:number|null, loading:boolean,
      *   mode:'live'|'sim', error:string|null, flowCoveragePct:number,
      *   tilesFetched:number}}
      */
+    getLoadingDiagnostics() {
+      let movingWaypoints = 0,
+        maxResidualM = 0;
+      for (const road of layerState._roads) {
+        if (!road.heightMoving) continue;
+        for (let i = 0; i < road.waypoints.length; i++) {
+          const a = road.waypoints[i],
+            b = road.targetWaypoints[i];
+          const residual = Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+          if (residual >= 0.01) movingWaypoints++;
+          maxResidualM = Math.max(maxResidualM, residual);
+        }
+      }
+      return {
+        fetching: Boolean(layerState._fetching),
+        flowPending: layerState._flowPending,
+        surfaceRefining: Boolean(layerState._surfaceRefining),
+        populationPending: Boolean(layerState._populationPending),
+        heightPending: Boolean(layerState._heightPending),
+        generation: layerState._loadGeneration,
+        surfaceRevision: layerState._surfaceRevision,
+        lastPaintStage: layerState._lastPaintStage || null,
+        movingWaypoints,
+        maxResidualM,
+      };
+    },
+
     getStats() {
       // Outstanding flow work counts as loading: the paint race can leave a
       // TomTom request in flight after the roads have settled, and the shared
       // loading batch has to stay open long enough to announce its failure.
-      const loading = layerState._fetching || layerState._flowPending > 0;
+      const loading =
+        layerState._fetching ||
+        layerState._flowPending > 0 ||
+        Boolean(layerState._surfaceRefining) ||
+        Boolean(layerState._populationPending) ||
+        Boolean(layerState._heightPending);
+      const { free, slow, jam, sim } = layerState._bucketCounts;
+      const matched = free + slow + jam;
+      const flowCoveragePct =
+        matched + sim > 0 ? Math.round((100 * matched) / (matched + sim)) : 0;
       const feed = parts.model.trafficFeedPresentation({
         liveMode: layerState._liveMode,
         fetching: loading,
         flowError: layerState._flowError,
-        coveragePct: layerState._flowCoveragePct,
+        coveragePct: flowCoveragePct,
         statusUnavailable: layerState._flowStatusUnavailable,
+        roadSource: layerState._roadSource,
       });
       return {
         count: layerState._count,
+        motion: { ...layerState._motion },
+        surfaceBudgetOmitted: layerState._surfaceBudgetOmitted || 0,
         lastUpdate: layerState._lastUpdate,
         loading,
         mode: feed.mode,
-        error: layerState._roadError || feed.error,
-        flowCoveragePct: layerState._flowCoveragePct,
+        error:
+          layerState._roadError ||
+          layerState._roadWarning ||
+          layerState._detailError ||
+          feed.error,
+        roadBounds: layerState._lastBounds,
+        surfacePending: layerState._surfacePending || 0,
+        roadWarning: layerState._roadWarning || null,
+        detailError: layerState._detailError || null,
+        detailLimited: Boolean(layerState._detailLimited),
+        flowCoveragePct,
         tilesFetched: getFlowSessionStats().tilesFetched,
         ...(TRAFFIC_TIMING_ENABLED
           ? { trafficTiming: parts.timing.getTrafficTimingDiagnostics() }
@@ -180,7 +337,11 @@ export function createControls({ state: layerState, services, parts, source }) {
         // in one had better be the honest one. This is also where LIVE vs
         // SIMULATED mode is surfaced, and it must never imply a live feed the
         // layer does not have.
-        loadingLabel: feed.loadingLabel,
+        roadMode: resolveRoadMode(layerState._roadMode, layerState._liveMode),
+        roadModeRequested: layerState._roadMode,
+        roadSource: layerState._roadSource,
+        source: layerState._roadSource,
+        loadingLabel: roadStatusLabel(feed),
       };
     },
   };

src/layers/traffic/deadline.test.mjs

@@ -0,0 +1,210 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as C from 'cesium';
+import { createIngestion } from './ingestion.js';
+import { createFlow } from './flow.js';
+import { createRetention } from './retention.js';
+import { createControls } from './controls.js';
+import { createState } from './state.js';
+
+const bounds = { west: 0, east: 0.01, south: 0, north: 0.01 };
+const flush = async () => { for (let i = 0; i < 30; i++) await Promise.resolve(); };
+function setup(source) {
+  const state = { _enabled: true, _roadMode: 'osm', _loadGeneration: 0,
+    _tileCache: new Map(), _parseRoads: (data) => data.roads };
+  const paints = [];
+  const ingestion = createIngestion({ state, source, services: {}, parts: {
+    viewport: { clampBounds: (b) => b, getBoundsCenter: () => ({ lat: 0, lon: 0 }), onCameraChanged() {} },
+    flow: { warmFlow: async () => [], applyFlowThenRender: async (roads) => { paints.push(roads); return true; } },
+  } });
+  return { state, ingestion, paints };
+}
+for (const stage of ['request', 'body']) test(`road ${stage} deadline releases an uncooperative transport and ignores late callbacks`, async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let options, resolveLate;
+  const stalled = new Promise((resolve) => { resolveLate = resolve; });
+  const h = setup({ requestRoads: (_bounds, opts) => {
+    options = opts;
+    return stage === 'request' ? stalled : Promise.resolve({ ok: true, json: () => stalled });
+  } });
+  const request = h.ingestion.loadRoadsForBounds(bounds, 450);
+  await flush();
+  t.mock.timers.tick(12001);
+  await request;
+  assert.equal(options.signal.aborted, true);
+  assert.equal(h.state._fetching, false);
+  assert.equal(h.state._retryAttempts, 1);
+  assert.ok(h.state._retryTimer);
+  const source = h.state._roadSource;
+  h.state._loadGeneration++;
+  h.state._fetching = true;
+  options.onTile({ roads: [{ coords: [] }], roadSource: 'late' });
+  resolveLate(stage === 'request' ? { ok: true, json: async () => ({ roads: [], roadSource: 'late' }) } : { roads: [], roadSource: 'late' });
+  await flush();
+  assert.equal(h.state._roadSource, source);
+  assert.equal(h.state._fetching, true, 'old completion cannot clear a new generation');
+  assert.equal(h.paints.length, 0);
+  h.ingestion.cancelActiveFetch();
+});
+
+test('detail deadline retains painted coarse roads and schedules bounded retry', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const coarse = [{ coords: [[0, 0], [0.01, 0.01]] }];
+  const h = setup({ requestRoads: async (_b, options) => options.majorOnly
+    ? { ok: true, json: async () => ({ roads: coarse }) } : new Promise(() => {}) });
+  const request = h.ingestion.loadRoadsForBounds(bounds, 450);
+  await flush();
+  t.mock.timers.tick(20001);
+  await request;
+  assert.deepEqual(h.paints.at(-1), coarse);
+  assert.equal(h.state._fetching, false);
+  assert.equal(h.state._roadPartial, true);
+  assert.equal(h.state._retryAttempts, 1);
+  h.ingestion.cancelActiveFetch();
+});
+
+test('superseding a stalled pass aborts promptly without clearing newer loading', async () => {
+  const h = setup({ requestRoads: () => new Promise(() => {}) });
+  const old = h.ingestion.loadRoadsForBounds(bounds, 450);
+  const next = h.ingestion.loadRoadsForBounds(bounds, 450);
+  await old;
+  assert.equal(h.state._fetching, true);
+  h.state._enabled = false;
+  h.ingestion.cancelActiveFetch();
+  await next;
+  clearTimeout(h.state._retryTimer);
+});
+
+for (const y of [-175, -200, -300]) test(`off-screen camera-plane height correction settles without holding public loading (${y})`, () => {
+  const angle = 35 * Math.PI / 180;
+  const scene = {
+    canvas: { clientWidth: 1280, clientHeight: 800 },
+    frameState: { mode: C.SceneMode.SCENE3D },
+    camera: { viewMatrix: C.Matrix4.computeView(new C.Cartesian3(0, 0, 450),
+      new C.Cartesian3(0, Math.cos(angle), -Math.sin(angle)),
+      new C.Cartesian3(0, Math.sin(angle), Math.cos(angle)), C.Cartesian3.UNIT_X, new C.Matrix4()),
+    frustum: new C.PerspectiveFrustum({ fov: Math.PI / 3, aspectRatio: 1.6, near: 1, far: 1e7 }) },
+  };
+  const point = new C.Cartesian3(0, y, 100), target = new C.Cartesian3(0, y, 197);
+  const state = createState({ services: {} });
+  Object.assign(state, { _viewer: { scene }, _roads: [{ heightMoving: true, waypoints: [point], targetWaypoints: [target], segmentDist: [] }] });
+  const retention = createRetention({ state, parts: {} });
+  retention.easeHeights(1 / 60);
+  const controls = createControls({ state, services: {}, source: { getFlowSessionStats: () => ({}) }, parts: { model: { trafficFeedPresentation: () => ({}) } } });
+  assert.equal(controls.methods.getStats().loading, false);
+  for (let frame = 0; frame < 180; frame++) retention.easeHeights(1 / 60);
+  assert.equal(state._heightPending, false);
+  assert.equal(state._roads[0].heightMoving, false);
+  assert.ok(C.Cartesian3.distance(point, target) < 0.01);
+  assert.equal(controls.methods.getLoadingDiagnostics().movingWaypoints, 0);
+});
+
+
+test('visible corrections use the pixel limit without the off-screen world-speed cap', () => {
+  const angle = 35 * Math.PI / 180;
+  const scene = {
+    canvas: { clientWidth: 1280, clientHeight: 800 },
+    frameState: { mode: C.SceneMode.SCENE3D },
+    camera: { viewMatrix: C.Matrix4.computeView(new C.Cartesian3(0, 0, 450),
+      new C.Cartesian3(0, Math.cos(angle), -Math.sin(angle)),
+      new C.Cartesian3(0, Math.sin(angle), Math.cos(angle)), C.Cartesian3.UNIT_X, new C.Matrix4()),
+    frustum: new C.PerspectiveFrustum({ fov: Math.PI / 3, aspectRatio: 1.6, near: 1, far: 1e7 }) },
+  };
+  const point = new C.Cartesian3(0, 1000, 0), target = new C.Cartesian3(0, 1000, 300);
+  const state = { _viewer: { scene }, _roads: [{ heightMoving: true, waypoints: [point], targetWaypoints: [target], segmentDist: [] }] };
+  const retention = createRetention({ state, parts: {} });
+  let loadingFrames = 0, maxPixels = 0;
+  for (let frame = 0; frame < 180; frame++) {
+    const before = C.SceneTransforms.worldToWindowCoordinates(scene, point);
+    retention.easeHeights(1 / 60);
+    const after = C.SceneTransforms.worldToWindowCoordinates(scene, point);
+    if (before.y >= 0 && after.y >= 0) maxPixels = Math.max(maxPixels, C.Cartesian2.distance(before, after));
+    if (state._heightPending) loadingFrames++;
+  }
+  assert.ok(maxPixels <= 12.01, `visible correction: ${maxPixels} px`);
+  assert.ok(loadingFrames <= 66, `visible loading: ${loadingFrames / 60} s`);
+  assert.equal(state._roads[0].heightMoving, false);
+});
+
+for (const targetHeight of [200, 2000]) test(`visible height steps stay pixel-limited outside the margin or across the near plane (${targetHeight})`, () => {
+  const angle = 35 * Math.PI / 180;
+  const scene = {
+    canvas: { clientWidth: 1280, clientHeight: 800 },
+    frameState: { mode: C.SceneMode.SCENE3D },
+    camera: { viewMatrix: C.Matrix4.computeView(new C.Cartesian3(0, 0, 450),
+      new C.Cartesian3(0, Math.cos(angle), -Math.sin(angle)),
+      new C.Cartesian3(0, Math.sin(angle), Math.cos(angle)), C.Cartesian3.UNIT_X, new C.Matrix4()),
+    frustum: new C.PerspectiveFrustum({ fov: Math.PI / 3, aspectRatio: 1.6, near: 1, far: 1e7 }) },
+  };
+  const point = new C.Cartesian3(0, 50, 400), target = new C.Cartesian3(0, 50, targetHeight);
+  const state = { _viewer: { scene }, _roads: [{ heightMoving: true, waypoints: [point], targetWaypoints: [target], segmentDist: [] }] };
+  const before = C.SceneTransforms.worldToWindowCoordinates(scene, point);
+  assert.ok(before.y > 0 && before.y < 800);
+  const trial = C.Cartesian3.lerp(point, target, 0.2, new C.Cartesian3());
+  const trialEye = C.Matrix4.multiplyByPoint(scene.camera.viewMatrix, trial, new C.Cartesian3());
+  if (targetHeight === 200) {
+    assert.ok(trialEye.z < -1);
+    assert.ok(C.SceneTransforms.worldToWindowCoordinates(scene, trial).y > 900);
+  } else assert.ok(trialEye.z >= -1);
+  createRetention({ state, parts: {} }).easeHeights(1 / 60);
+  const after = C.SceneTransforms.worldToWindowCoordinates(scene, point);
+  const pixels = C.Cartesian2.distance(before, after);
+  assert.ok(pixels > 0 && pixels <= 12, `visible correction: ${pixels} px`);
+  assert.ok(C.Matrix4.multiplyByPoint(scene.camera.viewMatrix, point, new C.Cartesian3()).z < -1);
+  assert.equal(state._heightPending, true);
+});
+
+for (const outcome of ['timeout', 'abort']) test(`a road pass ${outcome} invalidates queued tiles and terrain publication without a newer generation`, async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const held = [];
+  const setTimer = globalThis.setTimeout;
+  t.mock.method(globalThis, 'setTimeout', (fn, delay, ...args) => delay === 0
+    ? (held.push(fn), held.length) : setTimer(fn, delay, ...args));
+  let clock = 0;
+  t.mock.method(performance, 'now', () => clock += 13);
+  const state = createState({ services: {} });
+  let options, samples = 0;
+  const road = { type: 'primary', oneway: 1, coords: [[0, 0], [0.001, 0]],
+    waypoints: [C.Cartesian3.fromDegrees(0, 0), C.Cartesian3.fromDegrees(0.001, 0)], segmentDist: [111] };
+  const source = { getStatus: async () => ({ hasKey: false }), requestRoads: (_b, opts) => {
+    options = opts;
+    opts.onTile({ roads: [road] });
+    return new Promise(() => {});
+  } };
+  const paints = [];
+  Object.assign(state, { _enabled: true, _roadMode: 'osm', _parseRoads: (data) => data.roads,
+    _viewer: { scene: { globe: { show: true, getHeight: () => { samples++; return 100; } } } } });
+  const parts = {
+    viewport: { clampBounds: (b) => b, getBoundsCenter: () => ({ lat: 0, lon: 0 }), onCameraChanged() {} },
+    rendering: { visibleRoadsForAltitude: (roads) => roads, renderRoadsForAltitude: (...args) => paints.push(args) },
+    model: { allocateRoadDotBudgets: (roads) => roads.map(() => 1), recolorDotsInPlace() {} },
+  };
+  const ctx = { state, source, services: { credits: {} }, parts };
+  parts.flow = createFlow(ctx);
+  const ingestion = createIngestion(ctx);
+  const request = ingestion.loadRoadsForBounds(bounds, 450);
+  await flush();
+  assert.equal(held.length, 1);
+  held.shift()(); await flush();
+  assert.equal(held.length, 1, 'held at the final station before the real terrain onReady callback');
+  options.onTile({ roads: [road] });
+  const generation = state._loadGeneration;
+  const revision = state._surfaceRevision;
+  const samplesBefore = samples;
+  if (outcome === 'timeout') t.mock.timers.tick(12001);
+  else ingestion.cancelActiveFetch();
+  await request;
+  assert.equal(options.signal.aborted, true);
+  assert.equal(state._loadGeneration, generation);
+  assert.equal(state._fetching, false);
+  if (outcome === 'timeout') {
+    assert.equal(state._activeFetchAbort.signal.aborted, false);
+    assert.match(state._roadError, /timed out/);
+    assert.equal(state._retryAttempts, 1);
+  }
+  held.shift()(); await flush();
+  assert.equal(paints.length, 0, 'expired terrain cannot publish');
+  assert.equal(samples, samplesBefore, 'queued tiles cannot start surface preparation');
+  assert.equal(state._surfaceRevision, revision, 'queued tiles cannot invalidate another surface pass');
+  ingestion.cancelActiveFetch();
+});

src/layers/traffic/flow.js

@@ -1,5 +1,16 @@
+import { roadIdentity } from './retention.js';
+import * as Cesium from 'cesium';
+import {
+  prepareRoadSurfaces,
+  roadHeightStations,
+  trafficSurfaceReady,
+} from './surface.js';
 import { matchFlowToRoads } from '../../data/flowMatch.js';
-import { TRAFFIC_TIMING_ENABLED, FLOW_RENDER_RACE_MS } from './policy.js';
+import {
+  DOT_HEIGHT_OFFSET,
+  FAST_FETCH_ALTITUDE,
+  roadDotBudget,
+} from './policy.js';
 
 export function createFlow({ state: layerState, services, parts, source }) {
   const { registerDynamicCredit, TOMTOM_CREDIT } = services.credits;
@@ -22,7 +33,9 @@ export function createFlow({ state: layerState, services, parts, source }) {
   function deriveTrafficFlowError(error) {
     if (!error || error.name === 'AbortError') return null;
     const message = String(error.message || error);
-    const status = Number(message.match(/HTTP (\d{3})/)?.[1]);
+    const status = Number.isFinite(error.status)
+      ? error.status
+      : Number(message.match(/HTTP (\d{3})/)?.[1]);
     if (status === 503) return 'TomTom key unavailable';
     if (status === 429) return 'TomTom daily budget reached';
     if (status === 502 || status === 504) return 'TomTom upstream unreachable';
@@ -39,23 +52,33 @@ export function createFlow({ state: layerState, services, parts, source }) {
    * @returns {Promise<void>} Resolves when `_liveMode` is settled.
    */
 
-  function ensureFlowStatus() {
+  function ensureFlowStatus(signal) {
+    if (layerState._flowStatusSignal?.aborted)
+      layerState._flowStatusPromise = null;
     if (!layerState._flowStatusPromise) {
+      layerState._flowStatusSignal = signal;
       layerState._flowStatusPromise = source
-        .getStatus()
+        .getStatus({ signal })
         .then((status) => {
+          if (layerState._flowStatusSignal === signal)
+            layerState._flowStatusSignal = null;
           layerState._liveMode = Boolean(status?.hasKey);
           layerState._flowStatusUnavailable = false;
+          layerState._flowStatusKnown = true;
           if (layerState._liveMode) {
             console.log('[Data:Traffic] TomTom key present — live flow mode');
             registerDynamicCredit(layerState._viewer, TOMTOM_CREDIT);
           }
         })
         .catch((e) => {
+          if (e?.name === 'AbortError') throw e;
+          if (layerState._flowStatusSignal === signal)
+            layerState._flowStatusSignal = null;
           // Simulating because we could not ask, which is NOT the same as
           // "server says no key" — getStats() distinguishes the two.
           layerState._liveMode = false;
           layerState._flowStatusUnavailable = true;
+          layerState._flowStatusKnown = true;
           console.warn(
             '[Data:Traffic] TomTom status unreachable — simulated traffic:',
             e?.message || e,
@@ -82,49 +105,67 @@ export function createFlow({ state: layerState, services, parts, source }) {
    * @returns {Promise<void>}
    */
 
-  async function applyFlowToRoads(roads, clamped, generation) {
+  async function applyFlowToRoads(roads, clamped, generation, signal) {
     // Claim the work synchronously, before the first await, so `stats.loading`
     // covers this request from the same tick the caller started it — the
     // loading batch must not be able to close underneath an in-flight fetch.
     layerState._flowPending += 1;
+    layerState._flowRoads = roads;
+    // Geometry survives in the session cache; congestion does not. Never paint
+    // an old match as current while a refresh is pending or has failed.
+    for (const road of roads) {
+      road.key ||= roadIdentity(road);
+      if (!road.directFlow) road.flow = null;
+    }
     try {
       if (!layerState._flowStatusPromise) return; // status check not started — sim mode
       await layerState._flowStatusPromise;
       if (!layerState._liveMode || !layerState._enabled) return;
-      if (generation !== layerState._loadGeneration) return;
+      if (generation !== layerState._loadGeneration || signal?.aborted) return;
       if (!Array.isArray(roads) || roads.length === 0) return;
       try {
         // Cached paths reach here without a live controller; the fetch paths
         // reuse theirs so one cancel covers both roads and flow.
         if (!layerState._activeFetchAbort)
           layerState._activeFetchAbort = new AbortController();
-        const segments = await fetchFlowForBounds(clamped, {
-          signal: layerState._activeFetchAbort.signal,
-        });
-        if (generation !== layerState._loadGeneration) return;
-        const { matches, matchedCount, candidateCount } = matchFlowToRoads(
-          roads,
-          segments,
-        );
-        for (let i = 0; i < roads.length; i++) {
-          roads[i].flow = matches[i];
+        const segments = await warmFlow(clamped, generation);
+        if (
+          generation !== layerState._loadGeneration ||
+          !layerState._enabled ||
+          signal?.aborted
+        )
+          return;
+        if (layerState._matchedFlowGeneration !== generation) {
+          layerState._matchedFlowGeneration = generation;
+          layerState._matchedFlow = new Map();
         }
-        layerState._flowCoveragePct =
-          candidateCount > 0
-            ? Math.round((matchedCount / candidateCount) * 100)
-            : 0;
-        layerState._flowError = null;
+        const memo = layerState._matchedFlow;
+        const matchable = roads.filter(
+          (road) =>
+            !road.directFlow && !road.simulatedOnly && !memo.has(road.key),
+        );
+        const { matches } = matchFlowToRoads(matchable, segments);
+        for (let i = 0; i < matchable.length; i++)
+          memo.set(matchable[i].key, matches[i]);
+        for (const road of roads)
+          if (!road.directFlow && !road.simulatedOnly)
+            road.flow = memo.get(road.key) || null;
+        if (layerState._flowRoads === roads) layerState._flowError = null;
       } catch (e) {
         if (e?.name === 'AbortError') return;
         // Same guard the success path gets: a superseded request rejecting late
         // (or after disable() cleared the state) must not restore a stale
         // outage over newer good data.
-        if (generation !== layerState._loadGeneration || !layerState._enabled)
+        if (
+          generation !== layerState._loadGeneration ||
+          !layerState._enabled ||
+          signal?.aborted
+        )
           return;
         // Every covering tile failed: there is no live flow on screen. Drop the
         // now-false coverage number and surface the reason through getStats().
-        layerState._flowError = deriveTrafficFlowError(e);
-        layerState._flowCoveragePct = 0;
+        if (layerState._flowRoads === roads)
+          layerState._flowError = deriveTrafficFlowError(e);
         console.warn(
           '[Data:Traffic] Flow fetch failed (sim colors remain):',
           e?.message || e,
@@ -136,18 +177,22 @@ export function createFlow({ state: layerState, services, parts, source }) {
     }
   }
 
-  /**
-   * Race flow application against the paint deadline, render, and schedule an
-   * in-place recolor if flow lost the race.
-   * @param {Array} roads - Parsed road objects.
-   * @param {{south:number,west:number,north:number,east:number}} clamped - Fetch bounds.
-   * @param {number} generation - `_loadGeneration` at call time.
-   * @param {number} altitude - Camera altitude in meters.
-   * @param {string} label - Render log label.
-   * @param {Object|null} [trace=null] - Development-only correlated load trace.
-   * @returns {Promise<boolean>} True if this generation rendered.
-   */
+  // One flow acquisition per generation, started alongside road acquisition.
+  function warmFlow(clamped, generation) {
+    if (layerState._warmFlowGeneration === generation)
+      return layerState._warmFlow;
+    layerState._warmFlowGeneration = generation;
+    const signal = layerState._activeFetchAbort?.signal;
+    layerState._warmFlow = ensureFlowStatus(signal).then(() => {
+      if (!layerState._liveMode || generation !== layerState._loadGeneration)
+        return [];
+      return fetchFlowForBounds(clamped, { signal });
+    });
+    layerState._warmFlow.catch(() => {});
+    return layerState._warmFlow;
+  }
 
+  /** Paint locally resolved roads incrementally; flow never delays surface work. */
   async function applyFlowThenRender(
     roads,
     clamped,
@@ -155,61 +200,360 @@ export function createFlow({ state: layerState, services, parts, source }) {
     altitude,
     label,
     trace = null,
+    majorPreview = false,
+    signal = layerState._activeFetchAbort?.signal,
   ) {
-    const state =
-      TRAFFIC_TIMING_ENABLED && trace
-        ? parts.timing.trafficTimingRenderState(trace, label)
-        : null;
-    const flowRaceStart = state
-      ? parts.timing.trafficTimingMark(state, 'flow-render-race-start', {
-          deadlineMs: FLOW_RENDER_RACE_MS,
-        })
-      : null;
-    const flowJob = applyFlowToRoads(roads, clamped, generation);
-    const outcome = await Promise.race([
-      flowJob.then(() => 'flow'),
-      new Promise((resolve) =>
-        setTimeout(() => resolve('timeout'), FLOW_RENDER_RACE_MS),
-      ),
-    ]);
-    if (state) {
-      const flowRaceEnd = parts.timing.trafficTimingMark(
-        state,
-        'flow-render-race-end',
-        {
-          deadlineMs: FLOW_RENDER_RACE_MS,
-          outcome,
-        },
-      );
-      parts.timing.trafficTimingMeasure(
-        'flow-render-race',
-        state,
-        flowRaceStart,
-        flowRaceEnd,
-        {
-          deadlineMs: FLOW_RENDER_RACE_MS,
-          outcome,
-        },
-      );
+    if (generation !== layerState._loadGeneration || signal?.aborted)
+      return false;
+    const revision = (layerState._surfaceRevision || 0) + 1;
+    layerState._surfaceRevision = revision;
+    const current = () =>
+      generation === layerState._loadGeneration &&
+      revision === layerState._surfaceRevision &&
+      !signal?.aborted;
+    if (!current()) return false;
+    // Once traffic exists, retain it while the concurrently acquired detail
+    // snapshot finishes. Repeated coarse/tile previews sample roads that are
+    // immediately replaced, delaying the final population after every move.
+    if (
+      altitude <= FAST_FETCH_ALTITUDE &&
+      layerState._roadSource !== 'TomTom' &&
+      (layerState._dots.length ||
+        (layerState._detailRoadsReady && layerState._motion?.added > 0)) &&
+      (majorPreview || label === 'Loaded tile' || label === 'Loaded major')
+    ) {
+      layerState._retainedPreview = true;
+      return true;
     }
-    if (generation !== layerState._loadGeneration) return false;
-    parts.rendering.renderRoadsForAltitude(roads, altitude, label, trace);
-    if (outcome === 'timeout') {
-      flowJob
-        .then(() => {
-          if (generation !== layerState._loadGeneration) return;
-          parts.model.recolorDotsInPlace(label);
-        })
-        .catch(() => {
-          /* applyFlowToRoads settles its own failures */
-        });
+    const preparedRoads =
+      layerState._preparedRoads || (layerState._preparedRoads = new Map());
+    const refining = label.includes('refined');
+    if (!refining) {
+      layerState._surfaceRefining = false;
+      layerState._surfaceRefineRemove?.();
+      layerState._surfaceRefineRemove = null;
     }
-    return true;
+    if (!roads.length) {
+      // A streamed tile with no roads changes nothing on screen. A completed
+      // pass with none (TomTom roads only, where TomTom has no flow) is valid
+      // empty coverage: clear the old view and do not retry.
+      if (label === 'Loaded tile') return false;
+      parts.rendering.renderRoadsForAltitude([], altitude, label, trace);
+      return true;
+    }
+    const scene = layerState._viewer.scene;
+    // The enable-time estimate can predate the first local mesh (especially
+    // after an intercontinental jump). Once previews have measured roads, use
+    // that local evidence to select the detail view at its real elevation.
+    const localHeights = [];
+    for (const prepared of preparedRoads.values()) {
+      const height =
+        Cesium.Cartographic.fromCartesian(prepared.waypoints[0]).height -
+        DOT_HEIGHT_OFFSET;
+      if (Number.isFinite(height) && Math.abs(height) <= 9000)
+        localHeights.push(height);
+      if (localHeights.length === 9) break;
+    }
+    if (localHeights.length) {
+      localHeights.sort((a, b) => a - b);
+      layerState._viewHeightEstimate =
+        localHeights[Math.floor(localHeights.length / 2)];
+    }
+    // A rendered center-depth pick follows the current city's elevation even
+    // while older coarse samples are being replaced. It is selection-only.
+    let depthHeight;
+    if (scene.pickPositionSupported && scene.canvas?.clientWidth) {
+      const probe = new Cesium.Cartesian2(
+        scene.canvas.clientWidth / 2,
+        scene.canvas.clientHeight * 0.6,
+      );
+      try {
+        const hit = scene.pickPosition(probe);
+        const height = hit && Cesium.Cartographic.fromCartesian(hit).height;
+        if (Number.isFinite(height) && Math.abs(height) <= 9000)
+          depthHeight = height;
+      } catch {
+        /* no rendered depth yet */
+      }
+    }
+    if (depthHeight !== undefined) layerState._viewHeightEstimate = depthHeight;
+    for (const road of roads) {
+      road.key ||= roadIdentity(road);
+      const prepared = !refining && preparedRoads.get(road.key);
+      if (prepared) {
+        for (let i = 0; i < road.waypoints.length; i++)
+          Cesium.Cartesian3.clone(prepared.waypoints[i], road.waypoints[i]);
+      } else if (
+        (!road.surfaceReady || refining) &&
+        (localHeights.length || depthHeight !== undefined)
+      ) {
+        road.surfaceReady = false;
+        // Opposite source directions may share waypoint arrays. Provisional
+        // selection must not overwrite an already measured sibling.
+        road.waypoints = road.waypoints.map((point) =>
+          Cesium.Cartesian3.clone(point),
+        );
+        for (let i = 0; i < road.coords.length; i++) {
+          const [lon, lat] = road.coords[i];
+          const floor = services.ground?.cachedGroundFloor?.(lat, lon);
+          const height =
+            Number.isFinite(floor) && Math.abs(floor) <= 9000
+              ? Math.max(floor, layerState._viewHeightEstimate)
+              : layerState._viewHeightEstimate;
+          Cesium.Cartesian3.fromDegrees(
+            lon,
+            lat,
+            height + DOT_HEIGHT_OFFSET,
+            undefined,
+            road.waypoints[i],
+          );
+        }
+      }
+    }
+    const selected = parts.rendering
+      .visibleRoadsForAltitude(roads, altitude)
+      .filter((road) => {
+        const camera = layerState._viewer.camera?.positionWC;
+        const localHeight = Math.max(
+          0,
+          altitude - (layerState._viewHeightEstimate || 0),
+        );
+        const radius = clamped.coverage
+          ? clamped.coverage.rangeKm * 1000 + 1500
+          : Math.max(1200, localHeight * 2);
+        if (
+          camera &&
+          road.waypoints.every(
+            (point) =>
+              Cesium.Cartesian3.distanceSquared(camera, point) >
+              radius * radius,
+          )
+        )
+          return false;
+        // Spend surface work on roads crossing the canvas, with a small pan margin.
+        if (!scene.canvas?.clientWidth) return true;
+        let minX = Infinity,
+          minY = Infinity,
+          maxX = -Infinity,
+          maxY = -Infinity;
+        for (const point of road.waypoints) {
+          const screen = Cesium.SceneTransforms.worldToWindowCoordinates(
+            scene,
+            point,
+          );
+          if (!screen) continue;
+          minX = Math.min(minX, screen.x);
+          maxX = Math.max(maxX, screen.x);
+          minY = Math.min(minY, screen.y);
+          maxY = Math.max(maxY, screen.y);
+        }
+        road.coverageBand = maxY < scene.canvas.clientHeight / 2 ? 1 : 0;
+        if (clamped.coverage && camera) {
+          road.baseDensityWeight ??= road.densityWeight || 1;
+          road.densityWeight =
+            road.baseDensityWeight /
+            Math.max(
+              1,
+              Cesium.Cartesian3.distance(camera, road.waypoints[0]) / 1500,
+            );
+        }
+        return (
+          maxX >= -100 &&
+          minX <= scene.canvas.clientWidth + 100 &&
+          maxY >= -100 &&
+          minY <= scene.canvas.clientHeight + 100
+        );
+      });
+    const budgets = parts.model.allocateRoadDotBudgets(
+      selected,
+      altitude,
+      roadDotBudget(altitude),
+    );
+    const admitted = selected.filter((r, i) => budgets[i] > 0);
+    const camera = layerState._viewer.camera?.positionWC;
+    if (camera)
+      admitted.sort(
+        (a, b) =>
+          Cesium.Cartesian3.distanceSquared(camera, a.waypoints[0]) -
+          Cesium.Cartesian3.distanceSquared(camera, b.waypoints[0]),
+      );
+    // The wide pass is a fast preview when detailed tiles follow. Preparing
+    // the entire coarse graph only to replace it doubles surface work.
+    const preview =
+      label.includes('tile') ||
+      (altitude <= FAST_FETCH_ALTITUDE &&
+        layerState._roadSource !== 'TomTom' &&
+        (majorPreview || label.includes('major')));
+    if (preview) admitted.length = Math.min(admitted.length, 32);
+    // Mesh picks are synchronous GPU work. Bound the unique height stations
+    // as well as the dot count: a one-dot long road can otherwise cost dozens
+    // of picks. Nearest roads win, and the fixed coordinate budget gives cold
+    // and warm views the same deterministic coverage.
+    const stations = new Set();
+    const bounded = [];
+    const upper = clamped.coverage
+      ? admitted.filter((r) => r.coverageBand === 1)
+      : [];
+    const lower = clamped.coverage
+      ? admitted.filter((r) => r.coverageBand !== 1)
+      : admitted;
+    const ordered = [];
+    for (let i = 0; i < Math.max(upper.length, lower.length); i++) {
+      if (lower[i]) ordered.push(lower[i]);
+      if (upper[i]) ordered.push(upper[i]);
+    }
+    for (const road of ordered) {
+      const keys = roadHeightStations(road.coords).indices.map(
+        (i) =>
+          `${road.coords[i][0].toFixed(6)},${road.coords[i][1].toFixed(6)}`,
+      );
+      const fresh = [...new Set(keys)].filter((key) => !stations.has(key));
+      if (stations.size + fresh.length > 1000) continue;
+      for (const key of fresh) stations.add(key);
+      bounded.push(road);
+    }
+    layerState._surfaceBudgetOmitted = admitted.length - bounded.length;
+    admitted.length = 0;
+    admitted.push(...bounded);
+    const ready = [];
+    const unresolved = [];
+    for (const road of admitted) {
+      road.key ||= roadIdentity(road);
+      const prepared = !refining && preparedRoads.get(road.key);
+      if (prepared) {
+        for (let i = 0; i < road.waypoints.length; i++)
+          Cesium.Cartesian3.clone(prepared.waypoints[i], road.waypoints[i]);
+        for (let i = 0; i < road.segmentDist.length; i++)
+          road.segmentDist[i] = prepared.segmentDist[i];
+        road.surfaceReady = true;
+        road.surfaceSettled = prepared.surfaceSettled;
+        ready.push(road);
+      } else unresolved.push(road);
+    }
+    let lastPaint = 0;
+    let painted = 0;
+    const paint = (complete = false) => {
+      if (!current() || !ready.length) return;
+      if (!complete && painted === ready.length) return;
+      parts.rendering.renderRoadsForAltitude(
+        complete ? ready : ready.slice(painted),
+        altitude,
+        label,
+        trace,
+        complete && !preview,
+      );
+      painted = ready.length;
+      lastPaint = performance.now();
+    };
+    paint();
+    const flowJob = applyFlowToRoads(admitted, clamped, generation, signal);
+    flowJob
+      .then(() => {
+        if (current()) parts.model.recolorDotsInPlace(label);
+      })
+      .catch(() => {});
+    const options = {
+      // A tileset can briefly report loaded before finer destination tiles
+      // start streaming. The one completed-mesh pass must replace those early
+      // cache entries even when camera distance stayed in the same band.
+      revalidate: refining,
+      onReady: (road) => {
+        if (!current()) return;
+        ready.push(road);
+        preparedRoads.set(road.key, road);
+        if (!lastPaint || performance.now() - lastPaint >= 120) paint();
+      },
+    };
+    let prepared = await prepareRoadSurfaces(
+      unresolved,
+      layerState._viewer.scene,
+      services.ground,
+      [layerState._pointCollection],
+      signal,
+      options,
+    );
+    paint();
+    // Missing mesh is a surface state, never an OpenFreeMap provider failure.
+    // Only completed snapshots retry locally. A provisional tile/major pass
+    // must never hold the detail fetch behind unresolved preview stations.
+    const deadline = performance.now() + 1500;
+    while (
+      !preview &&
+      !ready.length &&
+      prepared.pending.length &&
+      current() &&
+      performance.now() < deadline
+    ) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      if (!current()) return false;
+      prepared = await prepareRoadSurfaces(
+        prepared.pending,
+        layerState._viewer.scene,
+        services.ground,
+        [layerState._pointCollection],
+        signal,
+        options,
+      );
+      paint();
+    }
+    paint(true);
+    if (current()) layerState._surfacePending = prepared.pending.length;
+    if (
+      current() &&
+      !preview &&
+      !label.includes('refined') &&
+      scene.postRender &&
+      (!trafficSurfaceReady(scene) ||
+        prepared.pending.length ||
+        ready.some((road) => road.surfaceSettled === false))
+    ) {
+      layerState._surfaceRefineRemove?.();
+      const stop = () => {
+        remove();
+        clearTimeout(timer);
+        if (layerState._surfaceRefineRemove === stop)
+          layerState._surfaceRefineRemove = null;
+      };
+      const remove = scene.postRender.addEventListener(() => {
+        if (!current()) {
+          stop();
+          return;
+        }
+        if (!trafficSurfaceReady(scene)) return;
+        stop();
+        // Revalidate only local samples taken at a coarser rendered LOD. This
+        // background upgrade never holds road acquisition or first paint.
+        layerState._surfaceRefining = true;
+        applyFlowThenRender(
+          roads,
+          clamped,
+          generation,
+          altitude,
+          `${label} refined`,
+          trace,
+          false,
+          signal,
+        )
+          .catch(() => {})
+          .finally(() => {
+            if (
+              generation === layerState._loadGeneration &&
+              layerState._surfaceRevision === revision + 1
+            )
+              layerState._surfaceRefining = false;
+          });
+      });
+      const timer = setTimeout(stop, 10000);
+      layerState._surfaceRefineRemove = stop;
+    }
+    return current() && ready.length > 0;
   }
+
   return {
     deriveTrafficFlowError,
     ensureFlowStatus,
     applyFlowToRoads,
+    warmFlow,
     applyFlowThenRender,
   };
 }

src/layers/traffic/flowDecode.js

@@ -8,7 +8,7 @@ import { VectorTile } from '@mapbox/vector-tile';
  * (the TomTom key never reaches the browser) and decodes the Mapbox Vector
  * Tile layer "Traffic flow" into plain lon/lat polylines with congestion
  * attributes. Consumed by the traffic layer's live mode
- * (`src/data/traffic.js` → `src/data/flowMatch.js`).
+ * for matching congestion onto OpenStreetMap roads.
  *
  * Segment shape: `{coords: [[lon,lat],…], trafficLevel: 0..1, roadType: string,
  * closure: boolean}` — `trafficLevel` is TomTom's current/free-flow speed
@@ -23,13 +23,15 @@ import { VectorTile } from '@mapbox/vector-tile';
  */
 
 const FLOW_LAYER_NAME = 'Traffic flow';
-export function decodeFlowTile(data, z, x, y) {
+/** Decode flow geometry; strict mode distinguishes damaged tiles from valid empty coverage. */
+export function decodeFlowTile(data, z, x, y, { strict = false } = {}) {
   let layer;
   try {
     const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
     const tile = new VectorTile(new PbfReader(bytes));
     layer = tile.layers[FLOW_LAYER_NAME];
   } catch {
+    if (strict) throw new Error('Malformed TomTom flow tile');
     return [];
   }
   if (!layer) return [];
@@ -63,7 +65,18 @@ export function decodeFlowTile(data, z, x, y) {
           : [];
     for (const coords of lines) {
       if (!Array.isArray(coords) || coords.length < 2) continue;
-      segments.push({ coords, trafficLevel, roadType, closure });
+      segments.push({
+        coords,
+        trafficLevel,
+        roadType,
+        roadCategory: props.road_category ?? null,
+        roadSubcategory: props.road_subcategory ?? null,
+        closure,
+        coverage: props.traffic_road_coverage ?? null,
+        leftHandTraffic:
+          props.left_hand_traffic === true ||
+          props.left_hand_traffic === 'true',
+      });
     }
   }
   return segments;

src/layers/traffic/flowSource.js

@@ -1,97 +1,47 @@
-import { tilesForBounds } from '../../data/tomtomTiles.js';
+import { isDrivableFlowSegment } from './roadModes.js';
+import { createVectorTileSource } from '../../sources/vectorTiles.js';
+import { clipTileLine } from '../../sources/openFreeMap.js';
+import { tileToBBox } from '../../data/tomtomTiles.js';
 import { decodeFlowTile } from './flowDecode.js';
-/** Own one decoded flow cache and its session counters. */
+
+/** Own one bounded decoded flow cache; every request still passes the server tile budget. */
 export function createFlowTileSource({
   fetchImpl = (...args) => globalThis.fetch(...args),
 } = {}) {
-  const DECODE_CACHE_TTL_MS = 120_000;
-  /** @const {number} Max decoded tiles kept in memory before oldest-entry eviction. */
-  const DECODE_CACHE_MAX_ENTRIES = 64;
-
-  /**
-   * Decoded-tile cache keyed by "z/x/y".
-   * @type {Map<string, {at:number, segments:Array}>}
-   */
-  const _decodeCache = new Map();
-  /** @type {number} Session count of tile requests issued to the proxy (decode-cache misses). */
-  let _tilesFetched = 0;
-
-  /** Insert into the decode cache with oldest-entry eviction. */
-  function cacheSet(key, entry) {
-    if (
-      !_decodeCache.has(key) &&
-      _decodeCache.size >= DECODE_CACHE_MAX_ENTRIES
-    ) {
-      const oldest = _decodeCache.keys().next().value;
-      _decodeCache.delete(oldest);
-    }
-    _decodeCache.set(key, entry);
-  }
-
-  /**
-   * Fetch + decode all flow tiles covering the given bounds.
-   *
-   * Tiles are fetched from the local proxy in parallel; each decoded tile is
-   * cached in memory for 120 s (keyed z/x/y), so repeat calls for the same
-   * viewport are free. Partial tile failures return the segments that DID
-   * decode (last-good philosophy); the promise rejects only when every tile
-   * failed (e.g. keyless 503, aborted signal, proxy down).
-   *
-   * @param {{south:number, west:number, north:number, east:number}} bounds - Degrees.
-   * @param {Object} [opts]
-   * @param {AbortSignal} [opts.signal] - Abort signal (camera moved / layer disabled).
-   * @param {number} [opts.zoom=12] - Flow tile zoom level.
-   * @returns {Promise<Array<{coords:number[][], trafficLevel:number, roadType:string, closure:boolean}>>}
-   *   Flat array of flow segments across all covering tiles.
-   */
-  async function fetchFlowForBounds(bounds, { signal, zoom = 12 } = {}) {
-    signal?.throwIfAborted();
-    const tiles = tilesForBounds(bounds, zoom);
-    if (tiles.length === 0) return [];
-    const now = Date.now();
-
-    const results = await Promise.allSettled(
-      tiles.map(async ({ z, x, y }) => {
-        const key = `${z}/${x}/${y}`;
-        const cached = _decodeCache.get(key);
-        if (cached && now - cached.at < DECODE_CACHE_TTL_MS)
-          return cached.segments;
-
-        _tilesFetched += 1;
-        const res = await fetchImpl(`/api/tomtom/flow/${z}/${x}/${y}.pbf`, {
-          signal,
-        });
-        if (!res.ok) throw new Error(`flow tile ${key}: HTTP ${res.status}`);
-        const segments = decodeFlowTile(await res.arrayBuffer(), z, x, y);
-        signal?.throwIfAborted();
-        cacheSet(key, { at: Date.now(), segments });
-        return segments;
-      }),
-    );
-
-    signal?.throwIfAborted();
-    const fulfilled = results.filter((r) => r.status === 'fulfilled');
-    if (fulfilled.length === 0) {
-      throw results[0].reason instanceof Error
-        ? results[0].reason
-        : new Error('flow fetch failed');
-    }
-    return fulfilled.flatMap((r) => r.value);
-  }
-
-  /**
-   * Session diagnostics for `getStats()` surfaces.
-   * @returns {{tilesFetched:number}} Count of tile requests issued to the proxy
-   *   this session (decode-cache hits excluded).
-   */
-  function getFlowSessionStats() {
-    return { tilesFetched: _tilesFetched };
-  }
-
-  /** Clear the decode cache (tests + layer teardown). Session stats persist. */
-  function resetFlowTileCache() {
-    _decodeCache.clear();
-  }
-
-  return { fetchFlowForBounds, getFlowSessionStats, resetFlowTileCache };
+  const tiles = createVectorTileSource({
+    template: '/api/tomtom/flow/{z}/{x}/{y}.pbf',
+    allowedOrigin: 'http://localhost',
+    decode: (bytes, z, x, y) =>
+      decodeFlowTile(bytes, z, x, y, { strict: true })
+        .filter(isDrivableFlowSegment)
+        .flatMap((segment) =>
+          clipTileLine(segment.coords, tileToBBox(z, x, y)).map((coords) => ({
+            ...segment,
+            coords,
+          })),
+        ),
+    fetchImpl,
+    ttlMs: 120_000,
+    maxTiles: 16,
+  });
+  let partial = false;
+  return {
+    async fetchFlowForBounds(bounds, { signal, zoom = 12 } = {}) {
+      const result = await tiles.fetchBounds(bounds, {
+        zoom,
+        signal,
+        tiles: bounds.coverage?.coarse,
+      });
+      partial = result.partial;
+      if (bounds.coverage) return result.tiles.flat();
+      return result.tiles.flat().flatMap((segment) =>
+        clipTileLine(segment.coords, bounds).map((coords) => ({
+          ...segment,
+          coords,
+        })),
+      );
+    },
+    getFlowSessionStats: () => ({ ...tiles.getStats(), partial }),
+    resetFlowTileCache: () => tiles.clear(),
+  };
 }

src/layers/traffic/footprint.js

@@ -0,0 +1,166 @@
+import * as Cesium from 'cesium';
+import { tilesForBounds, tileToBBox } from '../../data/tomtomTiles.js';
+
+export const RETICLE_RANGE_KM = 10;
+export const RETICLE_TILE_CAP = 16;
+export const tileKey = (tile) => `${tile.z}/${tile.x}/${tile.y}`;
+const cross = (a, b, c) =>
+  (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+
+/** Convex ground envelope of the sampled screen square. */
+export function convexFootprint(points) {
+  const sorted = points.slice().sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const half = (list) => {
+    const out = [];
+    for (const p of list) {
+      while (out.length > 1 && cross(out.at(-2), out.at(-1), p) <= 0) out.pop();
+      out.push(p);
+    }
+    return out;
+  };
+  return [...half(sorted).slice(0, -1), ...half(sorted.reverse()).slice(0, -1)];
+}
+
+/** Select only tiles intersecting the convex footprint, ordered from the camera nadir. */
+export function footprintTiles(polygon, zoom, near) {
+  if (polygon.length < 3) return [];
+  const bounds = {
+    west: Math.min(...polygon.map((p) => p[0])),
+    east: Math.max(...polygon.map((p) => p[0])),
+    south: Math.min(...polygon.map((p) => p[1])),
+    north: Math.max(...polygon.map((p) => p[1])),
+  };
+  const cos = Math.cos((near.lat * Math.PI) / 180);
+  return tilesForBounds(bounds, zoom, { maxTiles: 4096 })
+    .filter((t) => {
+      const b = tileToBBox(t.z, t.x, t.y);
+      const corners = [
+        [b.west, b.south],
+        [b.east, b.south],
+        [b.east, b.north],
+        [b.west, b.north],
+      ];
+      for (let i = 0; i < polygon.length; i++)
+        if (
+          corners.every(
+            (p) =>
+              cross(polygon[i], polygon[(i + 1) % polygon.length], p) < -1e-12,
+          )
+        )
+          return false;
+      return true;
+    })
+    .sort((a, b) => {
+      const distance = (t) => {
+        const box = tileToBBox(t.z, t.x, t.y);
+        return (
+          ((box.west + box.east) / 2 - near.lon) ** 2 * cos * cos +
+          ((box.south + box.north) / 2 - near.lat) ** 2
+        );
+      };
+      return distance(a) - distance(b) || a.y - b.y || a.x - b.x;
+    });
+}
+
+/** Reusable camera scratch; sampled only on camera events, never in the animation loop. */
+export function createReticleFootprint() {
+  const pixels = Array.from({ length: 25 }, () => new Cesium.Cartesian2());
+  const hits = Array.from({ length: 25 }, () => new Cesium.Cartesian3());
+  const carto = new Cesium.Cartographic();
+  const ray = new Cesium.Ray();
+  return (viewer, altitude) => {
+    const { camera, scene } = viewer;
+    if (!camera.getPickRay) return null;
+    const nadir = camera.positionCartographic;
+    const near = {
+      lat: Cesium.Math.toDegrees(nadir.latitude),
+      lon: Cesium.Math.toDegrees(nadir.longitude),
+    };
+    const width = scene.canvas.clientWidth || scene.canvas.width,
+      height = scene.canvas.clientHeight || scene.canvas.height;
+    const side = Math.min(width, height),
+      left = (width - side) / 2,
+      top = (height - side) / 2;
+    const points = [];
+    for (let row = 0; row < 5; row++)
+      for (let col = 0; col < 5; col++) {
+        const i = row * 5 + col,
+          p = pixels[i];
+        p.x = left + (side * col) / 4;
+        p.y = top + (side * row) / 4;
+        const hit = camera.pickEllipsoid(p, Cesium.Ellipsoid.WGS84, hits[i]);
+        let dx, dy;
+        if (hit) {
+          Cesium.Cartographic.fromCartesian(hit, Cesium.Ellipsoid.WGS84, carto);
+          dy = (Cesium.Math.toDegrees(carto.latitude) - near.lat) * 111.195;
+          let dlon = Cesium.Math.toDegrees(carto.longitude) - near.lon;
+          dlon -= 360 * Math.round(dlon / 360);
+          dx = dlon * 111.195 * Math.cos(nadir.latitude);
+        } else {
+          camera.getPickRay(p, ray);
+          const d = ray.direction;
+          dx =
+            -Math.sin(nadir.longitude) * d.x + Math.cos(nadir.longitude) * d.y;
+          dy =
+            -Math.sin(nadir.latitude) * Math.cos(nadir.longitude) * d.x -
+            Math.sin(nadir.latitude) * Math.sin(nadir.longitude) * d.y +
+            Math.cos(nadir.latitude) * d.z;
+          const length = Math.hypot(dx, dy) || 1;
+          dx = (dx / length) * RETICLE_RANGE_KM;
+          dy = (dy / length) * RETICLE_RANGE_KM;
+        }
+        points.push([dx, dy]);
+      }
+    let range = RETICLE_RANGE_KM,
+      polygon,
+      coarse;
+    do {
+      polygon = convexFootprint(
+        points.map(([dx, dy]) => {
+          const scale = Math.min(1, range / Math.max(1e-9, Math.hypot(dx, dy)));
+          return [
+            near.lon +
+              (dx * scale) /
+                (111.195 * Math.max(0.05, Math.cos(nadir.latitude))),
+            near.lat + (dy * scale) / 111.195,
+          ];
+        }),
+      );
+      if (polygon.some((p) => Math.abs(p[0]) > 180 || Math.abs(p[1]) > 85))
+        return null;
+      coarse = footprintTiles(polygon, 12, near);
+      if (coarse.length <= RETICLE_TILE_CAP) break;
+      range *= 0.8;
+    } while (range > 0.5);
+    const detail =
+      altitude <= 4500
+        ? footprintTiles(polygon, 14, near).slice(0, RETICLE_TILE_CAP)
+        : [];
+    const bounds = {
+      west: Math.min(...polygon.map((p) => p[0])),
+      east: Math.max(...polygon.map((p) => p[0])),
+      south: Math.min(...polygon.map((p) => p[1])),
+      north: Math.max(...polygon.map((p) => p[1])),
+    };
+    return {
+      ...bounds,
+      coverage: {
+        polygon,
+        near,
+        rangeKm: range,
+        coarse,
+        detail,
+        viewKey: [
+          nadir.latitude,
+          nadir.longitude,
+          nadir.height / 10000,
+          camera.heading,
+          camera.pitch,
+        ]
+          .map((v) => Number(v || 0).toFixed(7))
+          .join(','),
+        key: [...coarse, ...detail].map(tileKey).sort().join('|'),
+      },
+    };
+  };
+}

src/layers/traffic/footprint.test.mjs

@@ -0,0 +1,92 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import {
+  convexFootprint,
+  footprintTiles,
+  createReticleFootprint,
+} from './footprint.js';
+import { tileToBBox, tilesForBounds } from '../../data/tomtomTiles.js';
+import { outsideDetailTiles } from './source.js';
+
+test('footprint selection excludes bbox corners and orders tiles nearest first', () => {
+  const polygon = convexFootprint([
+    [0, 0],
+    [0.15, 0],
+    [0, 0.15],
+    [0.01, 0.01],
+  ]);
+  const tiles = footprintTiles(polygon, 12, { lat: 0, lon: 0 });
+  const bbox = tilesForBounds(
+    { west: 0, east: 0.15, south: 0, north: 0.15 },
+    12,
+  );
+  assert.ok(tiles.length < bbox.length);
+  const b = tileToBBox(tiles[0].z, tiles[0].x, tiles[0].y);
+  assert.ok(b.west <= 0 && b.east >= 0 && b.south <= 0 && b.north >= 0);
+});
+
+test('oblique horizon bearings are bounded and tile caps hold at city latitudes', () => {
+  for (const [lat, lon] of [
+    [24.964, 55.037],
+    [30.2672, -97.7431],
+    [51.507, -0.128],
+    [70, 10],
+  ]) {
+    const camera = {
+      positionCartographic: Cesium.Cartographic.fromDegrees(lon, lat, 300),
+      heading: 0,
+      pitch: -Math.PI / 12,
+      pickEllipsoid(p, e, result) {
+        if (p.y < 300) return undefined;
+        return Cesium.Cartesian3.fromDegrees(
+          lon + (p.x - 640) / 100000,
+          lat + (800 - p.y) / 50000,
+          0,
+          e,
+          result,
+        );
+      },
+      getPickRay(p, ray) {
+        ray.direction.x =
+          -Math.sin((lat * Math.PI) / 180) * Math.cos((lon * Math.PI) / 180);
+        ray.direction.y =
+          -Math.sin((lat * Math.PI) / 180) * Math.sin((lon * Math.PI) / 180);
+        ray.direction.z = Math.cos((lat * Math.PI) / 180);
+        return ray;
+      },
+    };
+    const result = createReticleFootprint()(
+      { camera, scene: { canvas: { width: 1280, height: 800 } } },
+      300,
+    );
+    assert.ok(result.coverage.coarse.length <= 16);
+    assert.ok(result.coverage.detail.length <= 16);
+    assert.ok(
+      result.north > lat + 0.04,
+      'upper footprint extends past old fixed box',
+    );
+    assert.ok(result.coverage.rangeKm <= 10);
+  }
+});
+
+test('coarse roads retain far segments but never duplicate a detailed tile core', () => {
+  const tile = { z: 14, x: 8192, y: 8192 },
+    b = tileToBBox(tile.z, tile.x, tile.y);
+  const y = (b.south + b.north) / 2;
+  const roads = outsideDetailTiles(
+    [
+      {
+        coordinates: [
+          [b.west - 0.01, y],
+          [b.east + 0.01, y],
+        ],
+        type: 'primary',
+      },
+    ],
+    [tile],
+  );
+  assert.equal(roads.length, 2);
+  assert.equal(roads[0].coordinates.at(-1)[0], b.west);
+  assert.equal(roads[1].coordinates[0][0], b.east);
+});

src/layers/traffic/index.js

@@ -9,6 +9,7 @@ import { createFlow } from './flow.js';
 import { createRendering } from './rendering.js';
 import { createControls } from './controls.js';
 import { createLifecycle } from './lifecycle.js';
+import { createRetention } from './retention.js';
 import { createState } from './state.js';
 
 /** Construct one layer with its own scene state and supplied application services. */
@@ -33,6 +34,7 @@ export function createTrafficLayer({ services, source }) {
   parts.animation = createAnimation(context);
   parts.viewport = createViewport(context);
   parts.flow = createFlow(context);
+  parts.retention = createRetention(context);
   parts.rendering = createRendering(context);
   parts.controls = createControls(context);
   parts.lifecycle = createLifecycle(context);

src/layers/traffic/ingestion.js

@@ -1,10 +1,47 @@
+import * as Cesium from 'cesium';
+import { requestWithDeadline } from '../../sources/requestDeadline.js';
+import { resolveRoadMode, ROAD_SOURCE_LABELS } from './roadModes.js';
+import { phaseTiming } from '../../sources/phaseTiming.js';
+import { RoadRequestError, roadRequestError } from './source.js';
+import {
+  isUnavailableCapability,
+  sourceResponseError,
+} from '../../sources/capability.js';
 import {
   TRAFFIC_TIMING_ENABLED,
-  OVERPASS_URL,
   TILE_CACHE_MAX_ENTRIES,
   FAST_FETCH_ALTITUDE,
 } from './policy.js';
-import { RoadRequestError, roadRequestError } from './source.js';
+
+/** Retain complete parsed snapshots under both an LRU entry cap and a byte budget. */
+export function cacheRoadSnapshot(
+  entries,
+  key,
+  entry,
+  { retain = true, maxBytes = 24 * 1024 * 1024 } = {},
+) {
+  entries.delete(key);
+  if (!retain) return;
+  entry.cacheBytes = [entry.major, entry.full].reduce(
+    (sum, roads) =>
+      sum +
+      (roads || []).reduce(
+        (n, road) =>
+          n + 192 + (road.coords || road.coordinates || []).length * 96,
+        0,
+      ),
+    0,
+  );
+  if (entry.cacheBytes > maxBytes) return;
+  entries.set(key, entry);
+  let bytes = 0;
+  for (const value of entries.values()) bytes += value.cacheBytes || 0;
+  while (entries.size > TILE_CACHE_MAX_ENTRIES || bytes > maxBytes) {
+    const oldest = entries.keys().next().value;
+    bytes -= entries.get(oldest).cacheBytes || 0;
+    entries.delete(oldest);
+  }
+}
 
 export function createIngestion({
   state: layerState,
@@ -12,13 +49,10 @@ export function createIngestion({
   parts,
   source,
 }) {
-  const { fetchFlowForBounds } = source;
-
   /**
-   * Fetch road geometries from the Overpass API via the local proxy.
+   * Fetch road geometries from the selected vector tile source.
    *
-   * Sends a POST with the query as form-encoded `data`. Supports
-   * AbortController signals so in-flight requests can be cancelled
+   * Supports AbortController signals so in-flight requests can be cancelled
    * when the camera moves before the response arrives.
    *
    * @param {number} south - Southern latitude bound (degrees).
@@ -27,19 +61,55 @@ export function createIngestion({
    * @param {number} east  - Eastern longitude bound (degrees).
    * @param {Object}  [opts]
    * @param {boolean} [opts.majorOnly=false]  - Restrict to major highway classes.
-   * @param {number}  [opts.timeoutSec=25]    - Server-side Overpass timeout.
+   * @param {number}  [opts.timeoutSec=25]    - Compatibility deadline for injected sources.
    * @param {AbortSignal} [opts.signal]       - Abort signal for cancellation.
    * @param {Object|null} [trace=null] - Development-only correlated load trace.
-   * @returns {Promise<Object>} Parsed JSON response from Overpass.
+   * @returns {Promise<Object>} Parsed JSON response from vector tiles.
    * @throws {Error} If the HTTP response status is not OK.
    */
 
-  async function fetchRoads(
+  function fetchRoads(south, west, north, east, options = {}, trace = null) {
+    const generation = layerState._loadGeneration;
+    return requestWithDeadline(
+      async (signal) => {
+        const invalidate = () => options.passAbort?.abort(signal.reason);
+        signal.addEventListener('abort', invalidate, { once: true });
+        try {
+          return await readRoads(
+            south,
+            west,
+            north,
+            east,
+            {
+              ...options,
+              signal,
+              onTile: (data) => {
+                if (
+                  !signal.aborted &&
+                  generation === layerState._loadGeneration
+                )
+                  options.onTile?.(data);
+              },
+            },
+            trace,
+          );
+        } catch (error) {
+          options.passAbort?.abort(error);
+          throw error;
+        } finally {
+          signal.removeEventListener('abort', invalidate);
+        }
+      },
+      { signal: options.signal, timeoutMs: (options.timeoutSec ?? 25) * 1000 },
+    );
+  }
+
+  async function readRoads(
     south,
     west,
     north,
     east,
-    { majorOnly = false, timeoutSec = 25, signal } = {},
+    { majorOnly = false, timeoutSec = 25, signal, onTile } = {},
     trace = null,
   ) {
     const state =
@@ -64,11 +134,27 @@ export function createIngestion({
     }
     const response = await source.requestRoads(
       { south, west, north, east },
-      { majorOnly, timeoutSec, signal },
+      {
+        coverage: layerState._lastBounds?.coverage,
+        majorOnly,
+        timeoutSec,
+        signal,
+        onTile,
+        roadMode: layerState._roadMode,
+        flowSnapshot: layerState._roadFlowSnapshot,
+        liveModeHint: () => layerState._liveMode,
+      },
     );
 
     if (!response.ok) {
-      throw roadRequestError(response.status);
+      throw Object.assign(
+        roadRequestError(response.status),
+        sourceResponseError(
+          (await response.json?.().catch(() => ({}))) ?? {},
+          response,
+          roadRequestError(response.status).message,
+        ),
+      );
     }
 
     if (!state) {
@@ -76,6 +162,9 @@ export function createIngestion({
       signal?.throwIfAborted();
       if (!Array.isArray(data?.roads))
         throw new Error('Malformed road snapshot');
+      layerState._roadSource = data.roadSource || 'OpenStreetMap';
+      layerState._roadWarning = data.roadWarning || null;
+      layerState._roadPartial = Boolean(data.partial);
       return data;
     }
 
@@ -120,12 +209,22 @@ export function createIngestion({
         },
       );
     }
+    layerState._roadSource = data.roadSource || 'OpenStreetMap';
+    layerState._roadWarning = data.roadWarning || null;
+    layerState._roadPartial = Boolean(data.partial);
     return data;
   }
 
-  /** Abort any in-flight Overpass fetch and clear the controller reference. */
+  /** Abort any in-flight road fetch and clear the controller reference. */
 
   function cancelActiveFetch() {
+    layerState._preparedRoads?.clear();
+    layerState._preparedRoads = null;
+    layerState._matchedFlow?.clear();
+    layerState._matchedFlowGeneration = null;
+    layerState._surfaceRefineRemove?.();
+    layerState._surfaceRefineRemove = null;
+    layerState._surfaceRefining = false;
     if (layerState._activeFetchAbort) {
       layerState._activeFetchAbort.abort();
       layerState._activeFetchAbort = null;
@@ -140,7 +239,7 @@ export function createIngestion({
    *  1. Check the tile cache (keyed by clamped bounding-box coordinates).
    *     - If a full road set is cached, render immediately and return.
    *     - If only major roads are cached, render those first.
-   *  2. Fetch major roads from Overpass (fast, small payload). Render.
+   *  2. Fetch major roads from vector tiles (fast, small payload). Render.
    *  3. If altitude is low enough (< FAST_FETCH_ALTITUDE), fetch the full
    *     road graph (includes tertiary/residential). Render again to upgrade.
    *
@@ -158,39 +257,69 @@ export function createIngestion({
     // Increment generation to invalidate any in-flight responses from prior calls
     const generation = ++layerState._loadGeneration;
     cancelActiveFetch();
+    layerState._preparedRoads = new Map();
     clearTimeout(layerState._retryTimer);
     layerState._retryTimer = null;
     layerState._flowPending = 0;
     layerState._activeFetchAbort = new AbortController();
     const requestSignal = layerState._activeFetchAbort.signal;
     const clamped = parts.viewport.clampBounds(bounds);
+    // This single local estimate is only for visibility selection. Every road
+    // still needs measured height stations before any dots can be admitted.
+    // Zero-height provisional roads misproject badly in elevated cities.
+    layerState._viewHeightEstimate = 0;
+    const centerLat = (clamped.south + clamped.north) / 2;
+    const centerLon = (clamped.west + clamped.east) / 2;
+    const scene = layerState._viewer?.scene;
+    const location = Cesium.Cartographic.fromDegrees(centerLon, centerLat);
+    let estimated = services.ground?.cachedGroundFloor?.(centerLat, centerLon);
+    if (!Number.isFinite(estimated)) {
+      try {
+        estimated = scene?.globe?.show
+          ? scene.globe.getHeight?.(location)
+          : scene?.sampleHeightSupported
+            ? scene.sampleHeight(location, [layerState._pointCollection])
+            : undefined;
+      } catch {
+        /* the local mesh can still be loading */
+      }
+    }
+    if (Number.isFinite(estimated) && Math.abs(estimated) <= 9000)
+      layerState._viewHeightEstimate = estimated;
 
+    // Only plain OpenStreetMap snapshots are cached here: TomTom and Hybrid
+    // roads carry flow, which expires, and recompose from the tile caches.
+    // Reads need the mode that will actually be drawn. It is known up front
+    // for an explicit OSM choice, or once the TomTom status probe has
+    // settled; before that (a session's first load) the cache is skipped
+    // rather than waiting on the probe. Writes are decided by the snapshot.
+    const cacheMode =
+      layerState._roadMode === 'osm'
+        ? 'osm'
+        : layerState._flowStatusKnown
+          ? resolveRoadMode(layerState._roadMode, layerState._liveMode)
+          : null;
     // Cache key: fixed-precision bounding-box string for deterministic lookups
-    const cacheKey = `${clamped.south.toFixed(4)},${clamped.west.toFixed(4)},${clamped.north.toFixed(4)},${clamped.east.toFixed(4)}`;
+    const cacheKey =
+      clamped.coverage?.key ||
+      `${clamped.south.toFixed(4)},${clamped.west.toFixed(4)},${clamped.north.toFixed(4)},${clamped.east.toFixed(4)}`;
+    const retryKey = `${layerState._roadMode || 'auto'}:${cacheKey}`;
+    const retainSnapshot = (data, roads) =>
+      data?.roadMode === 'osm' &&
+      !layerState._roadPartial &&
+      roads.every((road) => !road.simulatedOnly && !road.directFlow);
 
-    if (cacheKey !== layerState._retryBoundsKey) {
-      layerState._retryBoundsKey = cacheKey;
+    if (retryKey !== layerState._retryBoundsKey) {
+      layerState._retryBoundsKey = retryKey;
       layerState._retryDelayMs = 1500;
+      layerState._retryAttempts = 0;
+      layerState._roadRetryStopped = false;
     }
     layerState._roadError = null;
-
-    // Live mode: warm the flow-tile cache CONCURRENTLY with the Overpass road
-    // fetch — sequential fetches doubled first-paint latency (field-test
-    // round 1). Failures are irrelevant; applyFlowToRoads settles the truth.
-    parts.flow.ensureFlowStatus().then(() => {
-      if (
-        layerState._liveMode &&
-        layerState._enabled &&
-        generation === layerState._loadGeneration
-      ) {
-        fetchFlowForBounds(clamped, { signal: requestSignal }).catch(() => {
-          /* warm-up only */
-        });
-      }
-    });
+    layerState._roadWarning = null;
 
     layerState._fetching = true;
-    // Only COMMIT these on success. Committing up-front means a failed Overpass
+    // Only COMMIT these on success. Committing up-front means a failed road
     // fetch (rate-limited / feed down) still trips the overlap gate in
     // onCameraChanged, so a stationary user never retries (H3/H5). Stage the
     // prospective values and roll back if nothing rendered.
@@ -199,24 +328,106 @@ export function createIngestion({
     layerState._lastBounds = clamped;
     layerState._lastViewCenter = parts.viewport.getBoundsCenter(clamped);
     let renderedSomething = false;
+    layerState._detailError = null;
+    layerState._detailLimited = false;
 
+    let retryable = true;
+    let tilePaint = Promise.resolve();
+    let streamed = [];
+    let majorPass = true;
+    let majorFallback = null;
+    layerState._retainedPreview = false;
+    layerState._detailRoadsReady = false;
+    let paintRevision = 0;
+    const onTile = (data, passSignal, preview) => {
+      if (generation !== layerState._loadGeneration || passSignal.aborted)
+        return;
+      const start = performance.now();
+      const parsed = layerState._parseRoads(data, trace);
+      phaseTiming('parse', start, { roads: parsed.length, incremental: true });
+      if (data.replace) streamed = parsed;
+      else streamed.push(...parsed);
+      const revision = ++paintRevision;
+      layerState._roadSource = data.roadSource || 'OpenStreetMap';
+      const snapshot = streamed.slice();
+      tilePaint = tilePaint.then(async () => {
+        if (
+          generation !== layerState._loadGeneration ||
+          revision !== paintRevision ||
+          passSignal.aborted
+        )
+          return;
+        renderedSomething =
+          (await parts.flow.applyFlowThenRender(
+            snapshot,
+            clamped,
+            generation,
+            altitude,
+            'Loaded tile',
+            trace,
+            preview,
+            passSignal,
+          )) || renderedSomething;
+      });
+      tilePaint.catch(() => {});
+    };
     try {
-      let cache = layerState._tileCache.get(cacheKey);
-      if (!cache) {
-        // LRU eviction: drop the oldest entry when cache exceeds the cap
-        if (layerState._tileCache.size >= TILE_CACHE_MAX_ENTRIES) {
-          const oldest = layerState._tileCache.keys().next().value;
-          layerState._tileCache.delete(oldest);
-        }
-        cache = { major: null, full: null };
-        layerState._tileCache.set(cacheKey, cache);
+      layerState._roadFlowSnapshot = parts.flow
+        .warmFlow(clamped, generation)
+        .then(
+          (segments) => ({
+            segments,
+            hasKey: layerState._liveMode,
+            partial: source.getFlowSessionStats?.().partial,
+          }),
+          (error) => {
+            if (error?.name === 'AbortError') throw error;
+            const reason = parts.flow.deriveTrafficFlowError(error);
+            if (generation === layerState._loadGeneration)
+              layerState._flowError = reason;
+            return {
+              segments: [],
+              hasKey: layerState._liveMode,
+              error: reason,
+            };
+          },
+        );
+      layerState._roadFlowSnapshot.catch(() => {});
+      // Warm the exact detail footprint while the major preview is painted.
+      // This uses the same shared XYZ cache and cap, with no extra ring.
+      if (
+        altitude <= FAST_FETCH_ALTITUDE &&
+        layerState._roadMode !== 'tomtom'
+      ) {
+        source
+          .requestOsmRoads?.(clamped, {
+            signal: requestSignal,
+            coverage: clamped.coverage,
+          })
+          .then(() => {
+            if (generation === layerState._loadGeneration)
+              layerState._detailRoadsReady = true;
+          })
+          .catch(() => {});
       }
+      requestSignal.throwIfAborted();
+      // Until the probe settles only OpenStreetMap roads can be drawn.
+      layerState._roadSource = ROAD_SOURCE_LABELS[cacheMode || 'osm'];
+      let cache =
+        cacheMode === 'osm' ? layerState._tileCache.get(cacheKey) : null;
+      if (cache) {
+        // LRU touch; cacheRoadSnapshot() inserts and evicts on write.
+        layerState._tileCache.delete(cacheKey);
+        layerState._tileCache.set(cacheKey, cache);
+      } else cache = { major: null, full: null };
 
       // Fast path: full road set already cached — render and return.
       // Flow is (re)applied even on cache hits: roads cache for the session,
-      // but congestion data has a 120s shelf life. The race renders within
-      // FLOW_RENDER_RACE_MS either way; late flow recolors in place.
+      // but congestion data has a 120s shelf life. Locally grounded roads
+      // paint independently; late flow recolors in place.
       if (cache.full) {
+        layerState._roadPartial = false;
+        layerState._detailLimited = Boolean(cache.detailLimited);
         renderedSomething = await parts.flow.applyFlowThenRender(
           cache.full,
           clamped,
@@ -230,21 +441,24 @@ export function createIngestion({
 
       // Intermediate path: render cached major roads while fetching the rest
       if (cache.major) {
-        if (
-          !(await parts.flow.applyFlowThenRender(
+        layerState._roadPartial = false;
+        renderedSomething =
+          (await parts.flow.applyFlowThenRender(
             cache.major,
             clamped,
             generation,
             altitude,
             'Cache major',
             trace,
-          ))
-        )
+          )) || renderedSomething;
+        // An unresolved major preview must not starve locally usable detail.
+        if (generation !== layerState._loadGeneration || requestSignal.aborted)
           return;
-        renderedSomething = true;
       } else {
         // Fetch major roads first (smaller payload, faster response)
         console.log(`[Data:Traffic] Fast fetch major roads [${cacheKey}]`);
+        const passAbort = new AbortController();
+        const passSignal = AbortSignal.any([requestSignal, passAbort.signal]);
         const majorData = await fetchRoads(
           clamped.south,
           clamped.west,
@@ -252,33 +466,52 @@ export function createIngestion({
           clamped.east,
           {
             majorOnly: true,
+            onTile: (data) => onTile(data, passSignal, true),
             timeoutSec: 12,
-            signal: requestSignal,
+            signal: passSignal,
+            passAbort,
           },
           trace,
         );
         // Discard stale response if a newer load was triggered while waiting
         if (generation !== layerState._loadGeneration) return;
-        cache.major = layerState._parseRoads(majorData, trace);
-        if (
-          !(await parts.flow.applyFlowThenRender(
+        await tilePaint;
+        const parseStart = performance.now();
+        cache.major = streamed.length
+          ? streamed
+          : layerState._parseRoads(majorData, trace);
+        phaseTiming('parse', parseStart, { roads: cache.major.length });
+        cacheRoadSnapshot(layerState._tileCache, cacheKey, cache, {
+          retain: retainSnapshot(majorData, cache.major),
+        });
+        renderedSomething =
+          (await parts.flow.applyFlowThenRender(
             cache.major,
             clamped,
             generation,
             altitude,
             'Loaded major',
             trace,
-          ))
-        )
+            false,
+            passSignal,
+          )) || renderedSomething;
+        // An unresolved major preview must not starve locally usable detail.
+        if (generation !== layerState._loadGeneration || requestSignal.aborted)
           return;
-        renderedSomething = true;
       }
 
+      majorFallback = cache.major;
+      // TomTom roads come only from the z12 flow tiles already drawn.
+      if (layerState._roadSource === ROAD_SOURCE_LABELS.tomtom) return;
       // At higher altitude, major roads provide sufficient motion density
       if (altitude > FAST_FETCH_ALTITUDE) return;
 
+      streamed = [];
+      majorPass = false;
       // Detailed pass: fetch the full road graph (tertiary, residential, etc.)
       console.log(`[Data:Traffic] Full fetch local roads [${cacheKey}]`);
+      const passAbort = new AbortController();
+      const passSignal = AbortSignal.any([requestSignal, passAbort.signal]);
       const fullData = await fetchRoads(
         clamped.south,
         clamped.west,
@@ -286,14 +519,26 @@ export function createIngestion({
         clamped.east,
         {
           majorOnly: false,
+          onTile: (data) => onTile(data, passSignal, false),
           timeoutSec: 20,
-          signal: requestSignal,
+          signal: passSignal,
+          passAbort,
         },
         trace,
       );
       if (generation !== layerState._loadGeneration) return;
 
-      cache.full = layerState._parseRoads(fullData, trace);
+      layerState._detailLimited = Boolean(fullData.detailLimited);
+      cache.detailLimited = layerState._detailLimited;
+      await tilePaint;
+      const parseStart = performance.now();
+      cache.full = streamed.length
+        ? streamed
+        : layerState._parseRoads(fullData, trace);
+      phaseTiming('parse', parseStart, { roads: cache.full.length });
+      cacheRoadSnapshot(layerState._tileCache, cacheKey, cache, {
+        retain: retainSnapshot(fullData, cache.full),
+      });
       if (
         !(await parts.flow.applyFlowThenRender(
           cache.full,
@@ -302,34 +547,72 @@ export function createIngestion({
           altitude,
           'Loaded full',
           trace,
+          false,
+          passSignal,
         ))
       )
         return;
       renderedSomething = true;
     } catch (e) {
       if (e?.name === 'AbortError') return;
-      if (generation === layerState._loadGeneration && !renderedSomething) {
-        // A refusal we classified carries its own line; anything else — a
-        // dropped connection, a malformed snapshot — keeps the general one,
-        // because `e.message` from the platform is not a sentence anyone
-        // should have to read off a panel.
+      // Retained dots let successful detail loads skip coarse surface work.
+      // If detail fails, ground the current destination's major roads now;
+      // never leave an old city's population masquerading as the fallback.
+      if (
+        !majorPass &&
+        layerState._retainedPreview &&
+        majorFallback &&
+        generation === layerState._loadGeneration
+      ) {
+        try {
+          renderedSomething =
+            (await parts.flow.applyFlowThenRender(
+              majorFallback,
+              clamped,
+              generation,
+              altitude,
+              'Detail fallback',
+              trace,
+            )) || renderedSomething;
+        } catch (surfaceError) {
+          if (surfaceError?.name === 'AbortError') return;
+        }
+      }
+      if (generation === layerState._loadGeneration && !renderedSomething)
+        layerState._roadSource =
+          ROAD_SOURCE_LABELS[
+            resolveRoadMode(layerState._roadMode, layerState._liveMode)
+          ];
+      retryable = !isUnavailableCapability(e);
+      layerState._roadRetryStopped = !retryable;
+      if (generation === layerState._loadGeneration && !renderedSomething)
         layerState._roadError =
           e instanceof RoadRequestError
             ? e.message
-            : 'Road data temporarily unavailable';
+            : roadRequestError(null, e).message;
+      if (generation === layerState._loadGeneration && renderedSomething) {
+        layerState._detailError = `Detailed roads unavailable — ${e instanceof RoadRequestError ? e.message : roadRequestError(null, e).message}`;
+        layerState._roadPartial = true;
       }
       console.warn('[Data:Traffic] Fetch error:', e);
     } finally {
       if (generation === layerState._loadGeneration) {
         layerState._fetching = false;
         // Roll back the bounds commit if this load rendered nothing (e.g. the
-        // Overpass fetch failed). Leaving them committed would make the overlap
+        // road fetch failed). Leaving them committed would make the overlap
         // gate skip the retry while the user sits still. Guarded on generation so
         // a superseding load's commit is not clobbered.
         if (!renderedSomething) {
           layerState._lastBounds = prevBounds;
           layerState._lastViewCenter = prevViewCenter;
-          if (layerState._enabled) {
+        }
+        if (!renderedSomething || layerState._roadPartial) {
+          if (
+            layerState._enabled &&
+            retryable &&
+            layerState._retryAttempts < 3
+          ) {
+            layerState._retryAttempts += 1;
             layerState._retryTimer = setTimeout(() => {
               layerState._retryTimer = null;
               parts.viewport.onCameraChanged();
@@ -341,6 +624,7 @@ export function createIngestion({
           }
         } else {
           layerState._retryDelayMs = 1500;
+          layerState._retryAttempts = 0;
         }
       }
       // Keep this generation's controller until superseded or disabled: flow

src/layers/traffic/lifecycle.js

@@ -1,3 +1,4 @@
+import { observeTrafficSurface } from './surface.js';
 import * as Cesium from 'cesium';
 import { TRAFFIC_TIMING_ENABLED } from './policy.js';
 import {
@@ -40,7 +41,7 @@ export function createLifecycle({
       layerState._densityScale = 1.0;
       layerState._speedScale = 1.0;
       layerState._lastViewCenter = null;
-      layerState._flowCoveragePct = 0;
+      layerState._flowRoads = null;
       layerState._flowError = null;
       if (TRAFFIC_TIMING_ENABLED) {
         layerState._trafficTimingCurrentAnchor = null;
@@ -76,14 +77,14 @@ export function createLifecycle({
      * @param {Cesium.Viewer} viewer - The Cesium viewer instance.
      */
     enable(viewer) {
+      if (layerState._enabled) return;
       layerState._enabled = true;
+      layerState._surfaceFrameRemover = observeTrafficSurface(viewer.scene);
+      if (layerState._roadMode !== 'tomtom') source.prefetch?.();
       holdContinuousRender('traffic'); // per-frame animator (perf wave 2)
       layerState._lastAnimTime = 0;
       layerState._pointCollection.show = true;
 
-      // One status check per session decides sim vs live-TomTom mode.
-      parts.flow.ensureFlowStatus();
-
       layerState._preRenderRemover = viewer.scene.preRender.addEventListener(
         parts.animation.animate,
       );
@@ -101,13 +102,13 @@ export function createLifecycle({
       viewer.camera.changed.addEventListener(parts.viewport.onCameraChanged);
       // Always inspect the final view, even when the last flight step is below
       // camera.changed's movement threshold.
-      layerState._arrivalRemover = viewer.camera.moveEnd.addEventListener(
-        parts.viewport.onCameraChanged,
+      layerState._arrivalRemover = viewer.camera.moveEnd.addEventListener(() =>
+        parts.viewport.onCameraChanged({ immediate: true }),
       );
       claimCameraSensitivity(viewer.camera, 'traffic', 0.05);
 
-      // Kick off initial viewport check
-      parts.viewport.onCameraChanged();
+      // Enabling is explicit intent, not a camera gesture that needs settling.
+      parts.viewport.onCameraChanged({ immediate: true });
 
       // Boot-order guard (field-test round 1: layer sat empty until the user
       // moved): when the persisted layer state re-enables traffic during the
@@ -117,7 +118,12 @@ export function createLifecycle({
       // failed first fetch left the viewport unloaded while parked.
       clearInterval(layerState._enableKickTimer);
       layerState._enableKickTimer = setInterval(() => {
-        if (!layerState._enabled || layerState._lastUpdate) {
+        if (
+          !layerState._enabled ||
+          layerState._lastUpdate ||
+          layerState._roadRetryStopped ||
+          layerState._retryAttempts >= 3
+        ) {
           clearInterval(layerState._enableKickTimer);
           layerState._enableKickTimer = null;
           return;
@@ -135,6 +141,7 @@ export function createLifecycle({
      */
     disable(viewer) {
       layerState._enabled = false;
+      services.credits?.hideOsmCredit?.(layerState._viewer, 'traffic');
       releaseContinuousRender('traffic');
       clearTimeout(layerState._fetchTimeout);
       clearInterval(layerState._enableKickTimer);
@@ -148,11 +155,14 @@ export function createLifecycle({
       layerState._flowPending = 0;
       layerState._roadError = null;
       parts.animation.clearDots();
+      layerState._lastBounds = null;
       layerState._lastViewCenter = null;
       // A stale outage from the last session would misreport a fresh enable —
       // the next load re-derives feed health from real evidence.
       layerState._flowError = null;
 
+      layerState._surfaceFrameRemover?.();
+      layerState._surfaceFrameRemover = null;
       if (layerState._preRenderRemover) {
         layerState._preRenderRemover();
         layerState._preRenderRemover = null;

src/layers/traffic/model.js

@@ -1,15 +1,14 @@
 import * as Cesium from 'cesium';
+import { roadSurfaceChunks } from './surface.js';
 import {
   flowDensityMult,
   flowBucket,
   flowSpeedScale,
 } from '../../data/trafficFlowStyle.js';
 import {
-  MAX_WAYPOINTS_PER_ROAD,
   DOT_HEIGHT_OFFSET,
   DENSITY_MULT,
   JAM_DOT_FAR_SCALE,
-  JAM_DOT_DEPTH_PUNCH,
 } from './policy.js';
 
 export function createModel({ state: layerState, services, parts, source }) {
@@ -23,57 +22,43 @@ export function createModel({ state: layerState, services, parts, source }) {
     for (const road of roadData.roads) {
       if (!road.coordinates || road.coordinates.length < 2) continue;
 
-      const rawCoords = road.coordinates;
+      for (const coords of roadSurfaceChunks(road.coordinates)) {
+        const type = road.type;
+        const oneway = road.oneway;
+        // Pre-compute Cartesian3 waypoints (lon, lat, height) for fast lerp animation
+        const waypoints = coords.map(([lng, lat]) => {
+          const floor = services.ground?.cachedGroundFloor?.(lat, lng);
+          const h =
+            (Number.isFinite(floor) && Math.abs(floor) <= 9000
+              ? floor
+              : layerState._viewHeightEstimate || 0) + DOT_HEIGHT_OFFSET;
+          return Cesium.Cartesian3.fromDegrees(lng, lat, h);
+        });
 
-      // Sub-sample long polylines: keep every Nth vertex to stay within budget
-      const simplifyStep =
-        rawCoords.length > MAX_WAYPOINTS_PER_ROAD
-          ? Math.ceil(rawCoords.length / MAX_WAYPOINTS_PER_ROAD)
-          : 1;
-      const coords = [];
-      for (let i = 0; i < rawCoords.length; i += simplifyStep) {
-        coords.push(rawCoords[i]);
+        // Pre-compute segment distances in meters for speed-to-t conversion
+        const segmentDist = [];
+        for (let i = 0; i < waypoints.length - 1; i++) {
+          segmentDist.push(
+            Cesium.Cartesian3.distance(waypoints[i], waypoints[i + 1]),
+          );
+        }
+
+        for (const direction of oneway ? [oneway] : [1, -1])
+          roads.push({
+            densityWeight: road.densityWeight ?? (oneway ? 1 : 0.5),
+            drivable: road.drivable,
+            roadClass: road.roadClass,
+            roadProperties: road.roadProperties,
+            directFlow: road.directFlow,
+            simulatedOnly: road.simulatedOnly,
+            coords,
+            type,
+            oneway: direction,
+            waypoints,
+            segmentDist,
+            flow: road.flow || null,
+          });
       }
-
-      // Ensure the original endpoint is always preserved
-      const last = rawCoords[rawCoords.length - 1];
-      const tail = coords[coords.length - 1];
-      if (!tail || tail[0] !== last[0] || tail[1] !== last[1]) {
-        coords.push(last);
-      }
-
-      if (coords.length < 2) continue;
-
-      const type = road.type;
-      const oneway = road.oneway;
-
-      // Sample terrain height once at the road start to avoid per-vertex cost
-      let baseHeight = 0;
-      const firstCoord = coords[0];
-      if (layerState._viewer?.scene?.sampleHeightSupported && firstCoord) {
-        const carto = Cesium.Cartographic.fromDegrees(
-          firstCoord[0],
-          firstCoord[1],
-        );
-        const sampled = layerState._viewer.scene.sampleHeight(carto);
-        if (Number.isFinite(sampled)) baseHeight = sampled;
-      }
-
-      // Pre-compute Cartesian3 waypoints (lon, lat, height) for fast lerp animation
-      const waypoints = coords.map(([lng, lat]) => {
-        const h = baseHeight + DOT_HEIGHT_OFFSET;
-        return Cesium.Cartesian3.fromDegrees(lng, lat, h);
-      });
-
-      // Pre-compute segment distances in meters for speed-to-t conversion
-      const segmentDist = [];
-      for (let i = 0; i < waypoints.length - 1; i++) {
-        segmentDist.push(
-          Cesium.Cartesian3.distance(waypoints[i], waypoints[i + 1]),
-        );
-      }
-
-      roads.push({ coords, type, oneway, waypoints, segmentDist });
     }
 
     return roads;
@@ -130,10 +115,14 @@ export function createModel({ state: layerState, services, parts, source }) {
     const lengthM = estimateRoadLengthDeg(road.coords);
 
     // Altitude-adaptive spacing: closer camera = denser dots
+    const clearance = Math.max(
+      0,
+      altitude - (layerState._viewHeightEstimate || 0),
+    );
     let spacing;
-    if (altitude < 1000) spacing = 30;
-    else if (altitude < 3000) spacing = 80;
-    else if (altitude < 5000) spacing = 150;
+    if (clearance < 1000) spacing = 30;
+    else if (clearance < 3000) spacing = 80;
+    else if (clearance < 5000) spacing = 150;
     else spacing = 250;
 
     const mult =
@@ -142,7 +131,10 @@ export function createModel({ state: layerState, services, parts, source }) {
       (flow
         ? flowDensityMult(flow.level, { jamBoost: parts.style.jamDensityOn() })
         : 1);
-    return Math.max(1, Math.floor((lengthM / spacing) * mult));
+    return Math.max(
+      1,
+      Math.floor((lengthM / spacing) * mult * (road.densityWeight || 1)),
+    );
   }
 
   /**
@@ -236,8 +228,9 @@ export function createModel({ state: layerState, services, parts, source }) {
    * @param {boolean} [input.liveMode] - `/api/tomtom/status` reported a key.
    * @param {boolean} [input.fetching] - A viewport load is in flight.
    * @param {string|null} [input.flowError] - `deriveTrafficFlowError` result, if any.
-   * @param {number} [input.coveragePct] - Matched-road coverage, 0–100.
+   * @param {number} [input.coveragePct] - Share of shown dots on matched roads, 0–100.
    * @param {boolean} [input.statusUnavailable] - The status probe itself failed.
+   * @param {string} [input.roadSource] - Name of the geometry being drawn.
    * @returns {{mode:'live'|'sim', error:string|null, loadingLabel:string}}
    */
 
@@ -247,6 +240,7 @@ export function createModel({ state: layerState, services, parts, source }) {
     flowError = null,
     coveragePct = 0,
     statusUnavailable = false,
+    roadSource = 'OpenStreetMap',
   } = {}) {
     // `mode` is the CONFIGURED source (live key present vs keyless), not this
     // instant's health — health rides on `error`. The qa-traffic harness pins
@@ -260,13 +254,36 @@ export function createModel({ state: layerState, services, parts, source }) {
       const degraded = `SIMULATED — ${flowError}`;
       return { mode, error: degraded, loadingLabel: degraded };
     }
+    // TomTom and Hybrid name their geometry; OpenStreetMap keeps its match copy.
+    if (liveMode && roadSource === 'TomTom') {
+      return {
+        mode,
+        error: null,
+        loadingLabel: fetching
+          ? 'Syncing flow · Roads: TomTom'
+          : coveragePct > 0
+            ? 'LIVE · Roads: TomTom · Roads without flow hidden'
+            : 'LIVE · Roads: TomTom · No flow roads in view',
+      };
+    }
+    if (liveMode && roadSource === 'TomTom + OpenStreetMap') {
+      return {
+        mode,
+        error: null,
+        loadingLabel: fetching
+          ? `Syncing flow · Roads: ${roadSource}`
+          : `${coveragePct > 0 ? 'LIVE' : 'SIMULATED'} · Roads: ${roadSource} · Flow ${coveragePct}%`,
+      };
+    }
     if (liveMode) {
       return {
         mode,
         error: null,
         loadingLabel: fetching
-          ? 'syncing LIVE traffic flow'
-          : `LIVE · TomTom flow · ${coveragePct}% cov`,
+          ? 'Syncing flow · Roads: OpenStreetMap · Flow: TomTom · Unmatched: simulated'
+          : coveragePct > 0
+            ? `LIVE · Roads: OpenStreetMap · Flow: TomTom · ${coveragePct}% cov${coveragePct < 100 ? ' · Unmatched: simulated' : ''}`
+            : 'SIMULATED · Roads: OpenStreetMap · Flow: TomTom (no matches)',
       };
     }
     // Keyless simulation — one terse line that names the mode and the remedy
@@ -295,29 +312,24 @@ export function createModel({ state: layerState, services, parts, source }) {
     let closedDots = 0;
     const now = Date.now();
     for (const dot of layerState._dots) {
-      const flow = dot.road ? dot.road.flow : null;
-      if (flow?.closure) {
+      const flow = dot.road?.source ? dot.road.source.flow : dot.road?.flow;
+      dot.road.flow = flow;
+      if (flow?.closure || (!flow && layerState._uncoveredMode === 'hide')) {
         dot.point.show = false;
+        dot.mps = 0;
         closedDots += 1;
         continue;
       }
+      dot.point.show = true;
       const bucket = flow ? flowBucket(flow.level) : null;
       dot.bucket = bucket;
       dot.point.color = bucket
         ? layerState._activeBucketColors[bucket]
         : Cesium.Color.WHITE.withAlpha(0.85);
-      if (bucket === 'jam') {
-        dot.point.pixelSize =
-          parts.style.baseDotSize(dot.road?.type, bucket) +
-          1 +
-          parts.style.activeSizeDelta('jam');
-      } else if (bucket && parts.style.presetProfileActive()) {
-        // Preset profiles size-floor every bucket; the shipped normal path
-        // keeps its jam-only size touch (byte-identical behavior).
-        dot.point.pixelSize =
-          parts.style.baseDotSize(dot.road?.type, bucket) +
-          parts.style.activeSizeDelta(bucket);
-      }
+      dot.nominalSize =
+        parts.style.baseDotSize(dot.road?.type, bucket) +
+        (bucket === 'jam' ? 1 : 0) +
+        parts.style.activeSizeDelta(bucket);
       // Late flow can move a dot between buckets — keep the preset halo in
       // step (no-op writes under the normal profile, whose dots have none).
       if (parts.style.presetProfileActive())
@@ -338,12 +350,12 @@ export function createModel({ state: layerState, services, parts, source }) {
           layerState._fadeScaleFar,
           JAM_DOT_FAR_SCALE,
         );
-        dot.point.disableDepthTestDistance = JAM_DOT_DEPTH_PUNCH;
       } else {
         dot.creep = null;
       }
       layerState._bucketCounts[bucket || 'sim'] += 1;
     }
+    layerState._count = layerState._dots.length - closedDots;
     layerState._closedRoads = layerState._roads.reduce(
       (n, r) => n + (r.flow?.closure ? 1 : 0),
       0,

src/layers/traffic/motion.test.mjs

@@ -0,0 +1,635 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as C from 'cesium';
+import { createState } from './state.js';
+import { createStyle } from './style.js';
+import { createModel } from './model.js';
+import { createAnimation } from './animation.js';
+import {
+  createRetention,
+  DOT_CHANGE_BUDGET,
+  roadIdentity,
+} from './retention.js';
+
+function setup(t) {
+  const frames = [];
+  let now = 10000;
+  t.mock.method(Date, 'now', () => now);
+  const beforeRAF = globalThis.requestAnimationFrame;
+  const beforeCancel = globalThis.cancelAnimationFrame;
+  globalThis.requestAnimationFrame = (fn) => (frames.push(fn), frames.length);
+  globalThis.cancelAnimationFrame = () => {
+    frames.length = 0;
+  };
+  t.after(() => {
+    globalThis.requestAnimationFrame = beforeRAF;
+    globalThis.cancelAnimationFrame = beforeCancel;
+  });
+  const state = createState({ services: {} });
+  state._enabled = true;
+  state._liveMode = true;
+  state._pointCollection = new C.PointPrimitiveCollection();
+  state._viewer = { scene: {} };
+  const parts = {
+    rendering: {
+      removeHeatLines() {},
+      rebuildHeatLines() {},
+      visibleRoadsForAltitude: (roads) => roads,
+    },
+  };
+  const ctx = { state, services: {}, parts, source: {} };
+  parts.style = createStyle(ctx);
+  parts.model = createModel(ctx);
+  parts.animation = createAnimation(ctx);
+  parts.retention = createRetention(ctx);
+  const roads = (offset = 0, height = 100) =>
+    parts.model
+      .parseRoads({
+        roads: [
+          {
+            type: 'primary',
+            oneway: 1,
+            coordinates: [
+              [offset, 0],
+              [offset + 0.003, 0],
+              [offset + 0.004, 0.001],
+            ],
+          },
+        ],
+      })
+      .map((road) => {
+        road.waypoints = road.coords.map(([lon, lat]) =>
+          C.Cartesian3.fromDegrees(lon, lat, height),
+        );
+        road.segmentDist = road.waypoints
+          .slice(1)
+          .map((p, i) => C.Cartesian3.distance(road.waypoints[i], p));
+        return road;
+      });
+  const frame = (ms = 16) => {
+    now += ms;
+    const fn = frames.shift();
+    fn?.();
+    parts.animation.animate();
+  };
+  const settle = () => {
+    for (let i = 0; i < 100 && frames.length; i++) frame();
+  };
+  t.after(() => {
+    parts.animation.clearDots();
+    state._pointCollection.destroy();
+  });
+  return { state, parts, roads, frame, settle, frames };
+}
+
+test('incremental tiles, reordered snapshots and flow changes retain existing dot identities and progress', (t) => {
+  const h = setup(t),
+    a = h.roads(),
+    b = h.roads(0.01);
+  h.parts.retention.reconcile(a, 450, true);
+  h.settle();
+  const before = h.state._dots.map((d) => ({
+    dot: d,
+    id: d.id,
+    point: d.point,
+    t: d.t,
+    segIdx: d.segIdx,
+    road: d.road,
+  }));
+  h.parts.retention.reconcile([...b, ...h.roads()], 450, true);
+  for (const p of before) {
+    assert.equal(p.dot.id, p.id);
+    assert.equal(p.dot.point, p.point);
+    assert.equal(p.dot.t, p.t);
+    assert.equal(p.dot.segIdx, p.segIdx);
+    assert.equal(p.dot.road, p.road);
+  }
+  const target = h.state._dots[0];
+  const oldSpeed = target.mps;
+  target.road.source.flow = { level: 0.2, closure: false };
+  h.parts.model.recolorDotsInPlace('late flow');
+  assert.equal(target.id, before[0].id);
+  assert.ok(target.mps < oldSpeed);
+  target.road.source.flow = { level: 0, closure: true };
+  h.parts.model.recolorDotsInPlace('closure');
+  assert.equal(target.mps, 0);
+  assert.equal(target.point.show, false);
+  target.road.source.flow = { level: 1, closure: false };
+  h.parts.model.recolorDotsInPlace('reopened');
+  assert.equal(target.point.show, true);
+  assert.equal(target.id, before[0].id);
+  assert.equal(h.state._motion.rebuilds, 0);
+});
+
+test('height refinement eases retained waypoints vertically without changing road or dot progress', (t) => {
+  const h = setup(t);
+  h.parts.retention.reconcile(h.roads(), 450, true);
+  h.settle();
+  const d = h.state._dots[0],
+    p = d.waypoints[0];
+  const start = C.Cartographic.fromCartesian(p);
+  const id = d.id,
+    progress = d.t;
+  h.parts.retention.reconcile(h.roads(0, 120), 450, true);
+  assert.equal(Math.round(C.Cartographic.fromCartesian(p).height), 100);
+  h.parts.retention.easeHeights(0.016);
+  const mid = C.Cartographic.fromCartesian(p);
+  assert.ok(mid.height > 100 && mid.height < 120);
+  assert.ok(Math.abs(mid.latitude - start.latitude) < 1e-12);
+  assert.ok(Math.abs(mid.longitude - start.longitude) < 1e-12);
+  assert.equal(d.id, id);
+  assert.equal(d.t, progress);
+  for (let i = 0; i < 100; i++) h.parts.retention.easeHeights(0.016);
+  assert.ok(Math.abs(C.Cartographic.fromCartesian(p).height - 120) < 0.01);
+});
+
+test('density and replacement changes are bounded; removed roads fade out and teardown cancels pending work', (t) => {
+  const h = setup(t);
+  h.parts.model.allocateRoadDotBudgets = (roads) => roads.map(() => 3000);
+  h.parts.retention.reconcile(h.roads(), 450, true);
+  assert.equal(h.state._dots.length, DOT_CHANGE_BUDGET);
+  let previous = h.state._dots.length;
+  for (let i = 0; i < 6; i++) {
+    h.frame();
+    assert.ok(h.state._dots.length - previous <= DOT_CHANGE_BUDGET);
+    previous = h.state._dots.length;
+  }
+  assert.equal(h.state._dots.length, 3000);
+  const oldIds = new Set(h.state._dots.map((d) => d.id));
+  h.parts.retention.reconcile(h.roads(0.01), 450, true);
+  h.frame();
+  assert.ok(h.state._dots.some((d) => d.retiring));
+  h.settle();
+  assert.equal(h.state._dots.length, 3000);
+  assert.ok(h.state._dots.every((d) => !oldIds.has(d.id)));
+  assert.equal(new Set(h.state._dots.map((d) => d.id)).size, 3000);
+  h.parts.animation.clearDots();
+  h.frame();
+  assert.equal(h.state._pointCollection.length, 0);
+  assert.equal(h.state._dots.length, 0);
+  assert.equal(h.frames.length, 0);
+});
+
+test('identity distinguishes sources and opposing directions but ignores flow and height', () => {
+  const road = {
+    type: 'primary',
+    oneway: 1,
+    coords: [
+      [1, 2],
+      [1.001, 2.001],
+    ],
+  };
+  assert.equal(
+    roadIdentity(road),
+    roadIdentity({ ...road, flow: { level: 0 }, waypoints: [1] }),
+  );
+  assert.notEqual(roadIdentity(road), roadIdentity({ ...road, oneway: -1 }));
+  assert.notEqual(
+    roadIdentity(road),
+    roadIdentity({ ...road, directFlow: true }),
+  );
+});
+
+test('one-way departures fade before a new identity enters; segment crossings preserve metre speed', (t) => {
+  const h = setup(t);
+  h.parts.retention.reconcile(h.roads(), 450, true);
+  h.settle();
+  const d = h.state._dots[0];
+  d.mps = 10;
+  d.stoppedUntil = 0;
+  d.creep = null;
+  d.segIdx = d.numSegments - 1;
+  d.t = 0.99999;
+  const old = d.id;
+  h.frame(100);
+  assert.equal(d.id, old);
+  assert.equal(d.point.pixelSize, 0);
+  assert.equal(d.recycle, true);
+  h.frame(16);
+  assert.notEqual(d.id, old);
+  assert.equal(d.direction, 1);
+  assert.equal(d.segIdx, 0);
+  assert.equal(d.point.pixelSize, 0);
+});
+
+test('stopped vehicles still follow smooth height refinement without moving along the road', (t) => {
+  const h = setup(t);
+  h.parts.retention.reconcile(h.roads(), 450, true);
+  h.settle();
+  const d = h.state._dots[0];
+  d.stoppedUntil = Date.now() + 100000;
+  const before = C.Cartographic.fromCartesian(d.point.position).height;
+  const progress = d.t;
+  h.parts.retention.reconcile(h.roads(0, 120), 450, true);
+  h.frame();
+  assert.equal(d.t, progress);
+  const after = C.Cartographic.fromCartesian(d.point.position).height;
+  assert.ok(after > before && after - before <= 2.01);
+});
+
+test('flow closing a queued road cannot leave a population reconciliation loop', (t) => {
+  const h = setup(t);
+  h.parts.model.allocateRoadDotBudgets = (roads) => roads.map(() => 3000);
+  h.parts.retention.reconcile(h.roads(), 450, true);
+  h.state._roads[0].source.flow = { level: 0, closure: true };
+  h.settle();
+  assert.equal(h.state._dots.length, 0);
+  assert.equal(h.frames.length, 0);
+  assert.equal(h.state._populationPending, false);
+});
+
+test('street and city budgets are bounded and zoom changes do not increase the city population', async () => {
+  const { roadDotBudget } = await import('./policy.js');
+  assert.equal(roadDotBudget(450), 6000);
+  assert.equal(roadDotBudget(1000), 6000);
+  assert.equal(roadDotBudget(3000), 667);
+  assert.ok(roadDotBudget(1500) > roadDotBudget(3000));
+  assert.ok(roadDotBudget(8000) >= 400);
+});
+
+test('small previews merge without evicting other retained roads until a completed snapshot', (t) => {
+  const h = setup(t);
+  const a = h.roads(),
+    b = h.roads(0.01);
+  h.parts.retention.reconcile(a, 450, true);
+  h.settle();
+  const first = h.state._dots[0];
+  h.parts.retention.reconcile(b, 450, false);
+  h.settle();
+  assert.ok(h.state._dots.includes(first));
+  assert.equal(first.retiring, 0);
+  h.parts.retention.reconcile(b, 450, true);
+  h.settle();
+  assert.ok(!h.state._dots.includes(first));
+  assert.equal(h.state._motion.rebuilds, 0);
+});
+
+test('major previews merge and never retry missing mesh ahead of the detail pass', async () => {
+  const { createFlow } = await import('./flow.js');
+  for (const measured of [true, false]) {
+    let samples = 0;
+    const paints = [];
+    const scene = {
+      globe: {
+        show: true,
+        tilesLoaded: true,
+        getHeight: () => {
+          samples++;
+          return measured ? 100 : undefined;
+        },
+      },
+    };
+    const coords = [
+      [0, 0],
+      [0.001, 0],
+    ];
+    const road = {
+      type: 'primary',
+      oneway: 1,
+      coords,
+      waypoints: coords.map(([lon, lat]) => C.Cartesian3.fromDegrees(lon, lat)),
+      segmentDist: [111],
+    };
+    const state = {
+      _dots: [],
+      _detailRoadsReady: true,
+      _motion: { added: 0 },
+      _viewer: { scene },
+      _enabled: true,
+      _loadGeneration: 1,
+      _roadSource: 'OpenStreetMap',
+      _flowPending: 0,
+      _activeFetchAbort: new AbortController(),
+    };
+    const flow = createFlow({
+      state,
+      services: { credits: { registerDynamicCredit() {} } },
+      source: {},
+      parts: {
+        model: {
+          allocateRoadDotBudgets: (roads) => roads.map(() => 1),
+          recolorDotsInPlace() {},
+        },
+        rendering: {
+          visibleRoadsForAltitude: (roads) => roads,
+          renderRoadsForAltitude: (...args) => paints.push(args),
+        },
+      },
+    });
+    await flow.applyFlowThenRender([road], {}, 1, 450, 'Loaded major');
+    assert.equal(
+      samples,
+      2,
+      'preview tries each station once, then lets detailed roads proceed',
+    );
+    assert.ok(
+      paints.every((args) => args[4] === false),
+      'provisional roads cannot retire a surviving road',
+    );
+    assert.equal(paints.length > 0, measured);
+    assert.equal(state._flowPending, 0);
+    state._dots = [{}];
+    const before = paints.length;
+    await flow.applyFlowThenRender([road], {}, 1, 450, 'Loaded major');
+    await flow.applyFlowThenRender([road], {}, 1, 450, 'Loaded tile');
+    assert.equal(
+      samples,
+      2,
+      'retained traffic skips redundant preview sampling',
+    );
+    assert.equal(
+      paints.length,
+      before,
+      'previews leave the retained population intact',
+    );
+    state._dots = [];
+    state._detailRoadsReady = true;
+    state._motion.added = 1;
+    await flow.applyFlowThenRender([road], {}, 1, 450, 'Loaded major');
+    assert.equal(
+      samples,
+      2,
+      'decoded detail can supersede a cold coarse preview',
+    );
+    assert.equal(paints.length, before);
+  }
+});
+
+test('unresolved major roads cannot prevent the detailed request', async () => {
+  const { createIngestion } = await import('./ingestion.js');
+  const requests = [],
+    paints = [];
+  const state = {
+    _enabled: true,
+    _roadMode: 'osm',
+    _loadGeneration: 0,
+    _tileCache: new Map(),
+    _parseRoads: (data) => data.roads,
+  };
+  const ingestion = createIngestion({
+    state,
+    services: {},
+    parts: {
+      viewport: {
+        clampBounds: (b) => b,
+        getBoundsCenter: () => ({ lat: 0, lon: 0 }),
+      },
+      flow: {
+        warmFlow: async () => [],
+        applyFlowThenRender: async (
+          _roads,
+          _bounds,
+          _generation,
+          _altitude,
+          label,
+        ) => {
+          paints.push(label);
+          return label === 'Loaded full';
+        },
+      },
+    },
+    source: {
+      requestRoads: async (_bounds, options) => {
+        requests.push(options.majorOnly);
+        return {
+          ok: true,
+          json: async () => ({ roads: [], roadSource: 'OpenStreetMap' }),
+        };
+      },
+    },
+  });
+  await ingestion.loadRoadsForBounds(
+    { west: 0, east: 0.01, south: 0, north: 0.01 },
+    450,
+  );
+  assert.deepEqual(requests, [true, false]);
+  assert.deepEqual(paints, ['Loaded major', 'Loaded full']);
+  assert.equal(state._fetching, false);
+  assert.equal(state._roadError, null);
+});
+
+test('measured preview heights select elevated detail roads before surface admission', async () => {
+  const { createFlow } = await import('./flow.js');
+  const selections = [];
+  const road = (lon) => ({
+    type: 'primary',
+    oneway: 1,
+    coords: [
+      [lon, 0],
+      [lon + 0.001, 0],
+    ],
+    waypoints: [
+      C.Cartesian3.fromDegrees(lon, 0),
+      C.Cartesian3.fromDegrees(lon + 0.001, 0),
+    ],
+    segmentDist: [111],
+  });
+  const scene = {
+    globe: { show: true, tilesLoaded: true, getHeight: () => 750 },
+  };
+  const state = {
+    _dots: [],
+    _viewer: { scene },
+    _enabled: true,
+    _loadGeneration: 1,
+    _roadSource: 'OpenStreetMap',
+    _flowPending: 0,
+    _viewHeightEstimate: 0,
+    _activeFetchAbort: new AbortController(),
+  };
+  const flow = createFlow({
+    state,
+    services: {
+      credits: { registerDynamicCredit() {} },
+      ground: { cachedGroundFloor: () => 50 },
+    },
+    source: {},
+    parts: {
+      model: {
+        allocateRoadDotBudgets: (roads) => roads.map(() => 1),
+        recolorDotsInPlace() {},
+      },
+      rendering: {
+        visibleRoadsForAltitude: (roads) => {
+          selections.push(
+            roads.map(
+              (r) => C.Cartographic.fromCartesian(r.waypoints[0]).height,
+            ),
+          );
+          return roads;
+        },
+        renderRoadsForAltitude() {},
+      },
+    },
+  });
+  await flow.applyFlowThenRender([road(0)], {}, 1, 1250, 'Loaded major');
+  await flow.applyFlowThenRender(
+    [road(0), road(0.002)],
+    {},
+    1,
+    1250,
+    'Loaded full',
+  );
+  assert.ok(Math.abs(state._viewHeightEstimate - 750) < 0.01);
+  assert.ok(
+    selections.at(-1).every((height) => Math.abs(height - 753) < 0.01),
+    'both retained and new roads project at the measured local elevation',
+  );
+});
+
+test('street spacing follows clearance above local ground in elevated cities', (t) => {
+  const h = setup(t);
+  const road = h.roads()[0];
+  const high = h.parts.model.computeDotCount(road, 1250);
+  h.state._viewHeightEstimate = 750;
+  const street = h.parts.model.computeDotCount(road, 1250);
+  assert.equal(street, h.parts.model.computeDotCount(road, 500));
+  assert.ok(street > high);
+});
+
+test('provisional opposite-direction heights cannot overwrite a measured sibling during selection', async () => {
+  const { createFlow } = await import('./flow.js');
+  const road = () => ({
+    type: 'primary',
+    oneway: 1,
+    coords: [
+      [0, 0],
+      [0.001, 0],
+    ],
+    waypoints: [
+      C.Cartesian3.fromDegrees(0, 0),
+      C.Cartesian3.fromDegrees(0.001, 0),
+    ],
+    segmentDist: [111],
+  });
+  const selections = [];
+  const scene = {
+    globe: {
+      show: true,
+      tilesLoaded: true,
+      getHeight: (c) => 750 + C.Math.toDegrees(c.longitude) * 10000,
+    },
+  };
+  const state = {
+    _dots: [],
+    _viewer: { scene },
+    _enabled: true,
+    _loadGeneration: 1,
+    _roadSource: 'OpenStreetMap',
+    _flowPending: 0,
+    _activeFetchAbort: new AbortController(),
+  };
+  const flow = createFlow({
+    state,
+    services: { credits: { registerDynamicCredit() {} } },
+    source: {},
+    parts: {
+      model: {
+        allocateRoadDotBudgets: (roads) => roads.map(() => 1),
+        recolorDotsInPlace() {},
+      },
+      rendering: {
+        visibleRoadsForAltitude: (roads) => {
+          selections.push(
+            roads.map((r) =>
+              r.waypoints.map((p) => C.Cartographic.fromCartesian(p).height),
+            ),
+          );
+          return roads;
+        },
+        renderRoadsForAltitude() {},
+      },
+    },
+  });
+  await flow.applyFlowThenRender([road()], {}, 1, 1250, 'Loaded major');
+  const forward = road(),
+    reverse = { ...forward, oneway: -1 };
+  await flow.applyFlowThenRender(
+    [forward, reverse],
+    {},
+    1,
+    1250,
+    'Loaded full',
+  );
+  assert.ok(
+    Math.abs(selections.at(-1)[0][1] - 763) < 0.01,
+    'measured slope survives provisional sibling selection',
+  );
+  assert.notEqual(forward.waypoints, reverse.waypoints);
+});
+
+test('large height corrections obey a screen-pixel bound and reuse projection scratch objects', (t) => {
+  const h = setup(t);
+  h.state._viewer.scene = {
+    canvas: { clientWidth: 1280, clientHeight: 2000 },
+    camera: {},
+    frameState: {},
+  };
+  const scratch = new Set();
+  t.mock.method(
+    C.SceneTransforms,
+    'worldToWindowCoordinates',
+    (_scene, point, result) => {
+      scratch.add(result);
+      result.x = 0;
+      result.y = C.Cartographic.fromCartesian(point).height * 10;
+      return result;
+    },
+  );
+  h.parts.retention.reconcile(h.roads(), 450, true);
+  h.settle();
+  const dot = h.state._dots[0],
+    id = dot.id;
+  h.parts.retention.reconcile(h.roads(0, 160), 450, true);
+  for (let i = 0; i < 150; i++) {
+    const before = C.Cartographic.fromCartesian(dot.waypoints[0]).height;
+    h.parts.retention.easeHeights(1 / 60);
+    const after = C.Cartographic.fromCartesian(dot.waypoints[0]).height;
+    assert.ok((after - before) * 10 <= 12.01);
+  }
+  assert.ok(
+    Math.abs(C.Cartographic.fromCartesian(dot.waypoints[0]).height - 160) <
+      0.01,
+  );
+  assert.equal(dot.id, id);
+  assert.equal(h.state._heightPending, false);
+  assert.equal(scratch.size, 2);
+});
+
+test('grounded vehicles respect mesh occlusion even after live congestion changes', (t) => {
+  const h = setup(t);
+  const roads = h.roads();
+  h.parts.retention.reconcile(roads, 450, true);
+  h.settle();
+  assert.ok(h.state._dots.length > 0);
+  assert.ok(h.state._dots.every((d) => d.point.disableDepthTestDistance === 0));
+  for (const road of roads) road.flow = { level: 0.01, closure: false };
+  h.parts.model.recolorDotsInPlace('late jam');
+  assert.ok(h.state._dots.every((d) => d.point.disableDepthTestDistance === 0));
+});
+
+test('retained road density follows the settled view without requiring a toggle', (t) => {
+  const h = setup(t),
+    initial = h.roads();
+  initial[0].densityWeight = 0.2;
+  h.parts.retention.reconcile(initial, 450, true);
+  h.settle();
+  const ids = new Set(h.state._dots.map((d) => d.id)),
+    before = h.state._dots.length;
+  const settled = h.roads();
+  settled[0].densityWeight = 1;
+  h.parts.retention.reconcile(settled, 450, true);
+  h.settle();
+  assert.ok(h.state._dots.length > before);
+  assert.equal(h.state._roads[0].densityWeight, 1);
+  assert.ok([...ids].every((id) => h.state._dots.some((d) => d.id === id)));
+  const count = h.state._dots.length;
+  h.parts.animation.clearDots();
+  h.parts.retention.reconcile(h.roads(), 450, true);
+  h.settle();
+  assert.equal(
+    h.state._dots.length,
+    count,
+    'fresh toggle and retained view have the same budget',
+  );
+});

src/layers/traffic/navigation.test.mjs

@@ -11,7 +11,7 @@ function deferred() {
   return { promise, resolve };
 }
 
-function setup(t, requestRoads) {
+function setup(t, requestRoads, getStatus = async () => ({ hasKey: false })) {
   t.mock.timers.enable({ apis: ['setTimeout', 'setInterval'] });
   const camera = {
     positionCartographic: Cesium.Cartographic.fromDegrees(
@@ -44,6 +44,7 @@ function setup(t, requestRoads) {
     camera,
     scene: {
       canvas: { width: 100, height: 100 },
+      globe: { show: true, tilesLoaded: true, getHeight: () => 0 },
       preRender: new Cesium.Event(),
       primitives: { add: (value) => value, remove: () => true },
     },
@@ -55,7 +56,7 @@ function setup(t, requestRoads) {
     },
     source: {
       requestRoads,
-      getStatus: async () => ({ hasKey: false }),
+      getStatus,
       fetchFlowForBounds: async () => [],
       getFlowSessionStats: () => ({ tilesFetched: 0 }),
       resetFlowTileCache() {},
@@ -204,7 +205,7 @@ test('parked failures back off and disabling cancels the scheduled retry', async
   await tick(400);
   assert.equal(calls, 1);
   assert.equal(layer.getStats().loading, false);
-  assert.equal(layer.getStats().error, 'Road data temporarily unavailable');
+  assert.equal(layer.getStats().error, 'OpenFreeMap tiles unavailable');
   await tick(1500);
   await tick(400);
   assert.equal(calls, 2);
@@ -217,38 +218,211 @@ test('parked failures back off and disabling cancels the scheduled retry', async
   assert.equal(layer.getStats().error, null);
 });
 
+test('not-configured roads stop both parked retries and the enable-time kick', async (t) => {
+  let requests = 0;
+  const h = setup(t, async () => {
+    requests++;
+    return {
+      ok: false,
+      status: 503,
+      headers: new Headers(),
+      json: async () => ({ code: 'OVERPASS_NOT_CONFIGURED', retryable: false }),
+    };
+  });
+  h.layer.enable(h.viewer);
+  await h.tick(400);
+  await h.tick(60_000);
+  assert.equal(requests, 1);
+  assert.equal(h.layer.getStats().loading, false);
+  assert.match(h.layer.getStats().loadingLabel, /UNAVAILABLE/);
+});
+
 test('a declined road request reaches the row as the reason, not as a shrug', async (t) => {
-  // Issue #661: with every public Overpass mirror refusing a network, the row
-  // read "Road data temporarily unavailable" while the console already held
-  // "Overpass API returned 406". The reporter went looking for a bad TomTom
-  // key — the other half of this layer, and never the problem. The status the
-  // code already has must survive the trip to the panel.
   let status = 406;
   const { layer, viewer, tick } = setup(t, async () => ({ ok: false, status }));
   layer.enable(viewer);
   await tick(400);
   assert.equal(
     layer.getStats().error,
-    'Overpass refused the road query (HTTP 406)',
+    'OpenFreeMap tiles unavailable (HTTP 406)',
   );
 
   status = 429;
   for (let i = 0; i < 20; i++) await tick(1500);
   assert.equal(
     layer.getStats().error,
-    'Overpass rate-limited',
+    'OpenFreeMap tiles rate-limited',
     'a rate limit is a different instruction to the reader than a refusal',
   );
 });
 
 test('an unclassified road failure keeps the general line', async (t) => {
-  // The complement of the test above, and the reason this is not just
-  // `e.message`: a dropped socket throws whatever the platform felt like
-  // saying, and "Failed to fetch" on a panel row helps nobody.
   const { layer, viewer, tick } = setup(t, async () => {
     throw new Error('socket hang up');
   });
   layer.enable(viewer);
   await tick(400);
-  assert.equal(layer.getStats().error, 'Road data temporarily unavailable');
+  assert.equal(layer.getStats().error, 'OpenFreeMap tiles unavailable');
+});
+
+test('a stalled TomTom status never blocks road acquisition or first simulated dots', async (t) => {
+  let calls = 0;
+  const { layer, viewer, tick } = setup(
+    t,
+    async (box) => {
+      calls++;
+      return roads(box);
+    },
+    () => new Promise(() => {}),
+  );
+  // The source contract is exercised independently of status by the production
+  // load path; the real source status cancellation case is in source.test.
+  layer.enable(viewer);
+  await tick(400);
+  await tick(2000);
+  assert.ok(calls > 0);
+  assert.ok(layer.getStats().count > 0);
+});
+
+test('explicit enable starts roads without the camera debounce', async (t) => {
+  let calls = 0;
+  const { layer, viewer, tick } = setup(t, async (box) => {
+    calls++;
+    return roads(box);
+  });
+  layer.enable(viewer);
+  await tick(0);
+  assert.ok(calls > 0, 'the first load starts before 320 ms');
+});
+
+test('moveEnd starts the destination request without another gesture debounce', async (t) => {
+  let calls = 0;
+  const { layer, viewer, move, tick } = setup(t, async (bounds) => {
+    calls++;
+    return roads(bounds);
+  });
+  layer.enable(viewer);
+  await tick(400);
+  const before = calls;
+  move(-0.1276, 51.5072);
+  await tick(0);
+  assert.ok(calls > before, 'arrival loads in the next task, before 320 ms');
+});
+
+test('traffic surface observers belong to enable and leave no listener after disable or destroy', async (t) => {
+  const { layer, viewer, tick } = setup(t, async (bounds) => roads(bounds));
+  viewer.camera.viewMatrix = Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY);
+  viewer.camera.frustum = {
+    projectionMatrix: Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY),
+  };
+  viewer.scene.camera = viewer.camera;
+  viewer.scene.postRender = new Cesium.Event();
+  assert.equal(viewer.scene.postRender.numberOfListeners, 0);
+  for (let i = 0; i < 3; i++) {
+    layer.enable(viewer);
+    layer.enable(viewer);
+    assert.equal(viewer.scene.postRender.numberOfListeners, 1);
+    viewer.scene.postRender.raiseEvent();
+    await tick(1);
+    layer.disable(viewer);
+    assert.equal(viewer.scene.postRender.numberOfListeners, 0);
+    await tick(5000);
+    assert.equal(
+      viewer.scene.postRender.numberOfListeners,
+      0,
+      'late work cannot resubscribe',
+    );
+  }
+  layer.enable(viewer);
+  assert.equal(viewer.scene.postRender.numberOfListeners, 1);
+  layer.destroy(viewer);
+  assert.equal(viewer.scene.postRender.numberOfListeners, 0);
+  assert.equal(viewer.scene.preRender.numberOfListeners, 0);
+});
+
+test('coverage changes at the same center reload and disabling invalidates coverage without dropping source caches', async (t) => {
+  const calls = [];
+  const { layer, viewer, tick } = setup(t, async (bounds) => {
+    calls.push(bounds);
+    return roads(bounds);
+  });
+  layer.enable(viewer);
+  await tick(1000);
+  await tick(2000);
+  assert.ok(layer.getStats().count > 0);
+  const before = calls.length;
+  layer.disable(viewer);
+  layer.enable(viewer);
+  await tick(1000);
+  await tick(2000);
+  assert.ok(layer.getStats().count > 0, 'enable must repaint the same view');
+  assert.ok(calls.length >= before);
+});
+
+test('a settled footprint loads new tiles even when the camera centre stays put', async (t) => {
+  const seen = [];
+  const { layer, viewer, tick } = setup(
+    t,
+    async (bounds, { majorOnly, coverage }) => {
+      if (!majorOnly) seen.push({ ...bounds, coverage });
+      return roads(bounds);
+    },
+  );
+  layer.setParams({ roadMode: 'osm' });
+  let reach = 0.005;
+  const camera = viewer.camera;
+  camera.getPickRay = () => null;
+  camera.heading = 0;
+  camera.pitch = -Math.PI / 2;
+  camera.pickEllipsoid = (pixel, ellipsoid, result) =>
+    Cesium.Cartesian3.fromDegrees(
+      -97.744 + (pixel.x - 50) / 10000,
+      30.267 + (pixel.y / 100) * reach,
+      0,
+      ellipsoid,
+      result,
+    );
+  layer.enable(viewer);
+  await tick(400);
+  assert.equal(seen.length, 1);
+  const firstKey = seen[0].coverage.key;
+  camera.changed.raiseEvent();
+  // The final flight step occurs below the changed-event threshold.
+  reach = 0.08;
+  camera.pitch = -Math.PI / 12;
+  await tick(400);
+  assert.equal(seen.length, 2);
+  assert.notEqual(seen[1].coverage.key, firstKey);
+  assert.ok(
+    seen[1].north > 30.33,
+    'sample the final view when the debounce fires',
+  );
+  camera.moveEnd.raiseEvent();
+  await tick(400);
+  assert.equal(
+    seen.length,
+    2,
+    'an identical settled footprint does not reload',
+  );
+});
+
+test('partial coverage retries while coarse roads render, then stops after three retries', async (t) => {
+  let calls = 0;
+  const { layer, viewer, tick } = setup(t, async (bounds) => {
+    calls++;
+    const response = roads(bounds);
+    const data = await response.json();
+    return { ok: true, json: async () => ({ ...data, partial: true }) };
+  });
+  layer.enable(viewer);
+  await tick(400);
+  await tick(0);
+  assert.ok(layer.getStats().count > 0);
+  const initial = calls;
+  for (let i = 0; i < 12; i++) {
+    await tick(30000);
+    await tick(400);
+  }
+  assert.equal(calls, initial * 4, 'initial load plus three bounded retries');
+  assert.ok(layer.getStats().count > 0);
 });

src/layers/traffic/policy.js

@@ -1,36 +1,11 @@
 import * as Cesium from 'cesium';
 
 /**
- * @file Street Traffic — animated dots along OSM road polylines, colored by
- * live TomTom congestion when a key is configured.
- *
- * Road geometry: OSM Overpass API (free, no auth). Fetches road polylines for
- * the camera viewport, spawns PointPrimitives that lerp along pre-computed
- * Cartesian3 waypoints. Camera-gated: only active below ~8 km altitude.
- *
- * Two modes (decided once per session via `/api/tomtom/status`):
- *  - `sim` (keyless default): white dots at hardcoded per-road-class speeds —
- *    the original simulation, byte-identical behavior.
- *  - `live`: TomTom flow tiles (`flowTiles.js`) are matched onto the same
- *    Overpass roads (`flowMatch.js`); matched roads color/slow/densify their
- *    dots by real congestion (`trafficFlowStyle.js`), closed roads spawn no
- *    dots, and unmatched roads keep the simulated white.
- *
- * Architecture overview:
- *  - Camera-change listener triggers debounced road fetching per viewport tile.
- *  - Fetch bounds center on the camera's look-at point (`trafficBounds.js`, C4).
- *  - Roads are fetched in two passes: major-only (fast) then full graph (detailed).
- *  - Fetched tiles are cached by clamped bounding-box key to avoid re-fetching.
- *  - Dot budget allocation distributes a hard cap fairly across visible roads.
- *  - Each dot lerps along pre-computed Cartesian3 waypoints every preRender frame.
- *
- * @module data/traffic
+ * @file Street Traffic selects TomTom, OpenMapTiles or Hybrid motor roads,
+ * with directional TomTom congestion in live mode. Tile acquisition is
+ * bounded and camera-driven; animation lerps precomputed Cartesian waypoints.
  */
 
-/** @const {string} Proxy endpoint for Overpass API queries */
-
-export const OVERPASS_URL = '/api/overpass';
-
 /** @const {number} Meters — hide all traffic dots above this camera altitude */
 
 export const ACTIVATION_ALTITUDE = 8000;
@@ -55,6 +30,14 @@ export const OVERLAP_THRESHOLD = 0.6;
 
 export const MAX_DOTS = 6000;
 
+/** Keep a dense street view while bounding both dot and surface work at city scale. */
+export function roadDotBudget(altitude) {
+  return Math.max(
+    400,
+    Math.round(MAX_DOTS * Math.pow(1000 / Math.max(1000, altitude), 2)),
+  );
+}
+
 /** @const {number} Polylines longer than this are simplified by sub-sampling */
 
 export const MAX_WAYPOINTS_PER_ROAD = 80;
@@ -164,17 +147,6 @@ export const HEAT_JAM_COLOR = Cesium.Color.fromCssColorString('#e05252');
 export const HEAT_SLOW_COLOR =
   Cesium.Color.fromCssColorString('#f0b23e').withAlpha(0.2);
 
-/**
- * @const {number} Meters — jam dots depth-test-punch through the 3D tiles out
- * to this camera distance so queues stay visible at city scale. The single
- * start-of-road terrain sample puts much of a road below the rendered mesh
- * at oblique city views (first A/B capture: 396 jam dots, zero visible), so
- * the shipped 2 km window hides exactly the congestion this prototype is
- * meant to surface. Live jam dots only; sim dots keep the shipped 2 km.
- */
-
-export const JAM_DOT_DEPTH_PUNCH = 15000;
-
 /** @const {number} Far-distance scale floor for jam dots (shipped: 0.3). */
 
 export const JAM_DOT_FAR_SCALE = 0.55;

src/layers/traffic/rendering.js

@@ -9,7 +9,6 @@ import {
   HEAT_JAM_BASE_ALPHA,
   HEAT_LINE_SLOW_WIDTH,
   TRAFFIC_TIMING_ENABLED,
-  MAX_DOTS,
 } from './policy.js';
 
 export function createRendering({
@@ -161,7 +160,7 @@ export function createRendering({
   }
 
   /**
-   * Clear existing dots and re-spawn them for the given road set and altitude.
+   * Reconcile road populations without respawning retained dots.
    *
    * When zoomed out (>5 km), only major road types are rendered to reduce clutter.
    * Dot budgets are allocated fairly across visible roads via `allocateRoadDotBudgets`.
@@ -172,14 +171,20 @@ export function createRendering({
    * @param {Object|null} [trace=null] - Development-only correlated load trace.
    */
 
-  function renderRoadsForAltitude(roads, altitude, label, trace = null) {
+  function renderRoadsForAltitude(
+    roads,
+    altitude,
+    label,
+    trace = null,
+    replace = true,
+  ) {
     const state =
       TRAFFIC_TIMING_ENABLED && trace
         ? parts.timing.trafficTimingRenderState(trace, label)
         : null;
     const renderId = state ? ++trace.renderSequence : null;
-    parts.animation.clearDots();
-    layerState._roads = roads;
+
+    layerState._lastPaintStage = label;
     layerState._lastRenderAltitude = altitude;
 
     // At high altitude, drop minor roads to reduce visual noise
@@ -224,18 +229,13 @@ export function createRendering({
           visibleRoadCount: filteredRoads.length,
         })
       : null;
-    const roadBudgets = parts.model.allocateRoadDotBudgets(
-      filteredRoads,
-      altitude,
-      MAX_DOTS,
-    );
-    for (let i = 0; i < filteredRoads.length; i++) {
-      const road = filteredRoads[i];
-      const budget = roadBudgets[i] || 0;
-      if (budget <= 0) continue;
-      parts.animation.spawnDotsForRoad(road, altitude, budget);
-      if (layerState._dots.length >= MAX_DOTS) break;
-    }
+    parts.retention.reconcile(filteredRoads, altitude, replace);
+    if (layerState._dots.length && filteredRoads.some((r) => !r.directFlow))
+      services.credits?.showOsmCredit?.(layerState._viewer, 'traffic', {
+        openMapTiles: true,
+      });
+    else services.credits?.hideOsmCredit?.(layerState._viewer, 'traffic');
+    parts.model.recolorDotsInPlace(label);
 
     const renderMetrics = state
       ? {
@@ -268,7 +268,7 @@ export function createRendering({
           renderMetrics,
         )
       : null;
-    rebuildHeatLines(filteredRoads);
+    if (!label.includes('tile')) rebuildHeatLines(filteredRoads);
     if (state) {
       const heatEnd = parts.timing.trafficTimingMark(
         state,
@@ -290,7 +290,7 @@ export function createRendering({
       );
     }
 
-    layerState._count = layerState._dots.length;
+    parts.retention.refreshCounts();
     layerState._lastUpdate = Date.now();
     console.log(
       `[Data:Traffic] ${label}: ${layerState._count} dots (roads=${roads.length}, alt=${Math.round(altitude)}m)`,

src/layers/traffic/retention.js

@@ -0,0 +1,256 @@
+import * as Cesium from 'cesium';
+import { MAX_DOTS, roadDotBudget } from './policy.js';
+
+export const DOT_CHANGE_BUDGET = 768;
+export const DOT_FADE_MS = 180;
+
+/** Geometry identity excludes heights, flow and snapshot/collection ordering. */
+export function roadIdentity(road) {
+  return `${road.directFlow ? 'tomtom' : 'osm'}:${road.type}:${road.oneway}:${road.coords.map(([lon, lat]) => `${lon.toFixed(7)},${lat.toFixed(7)}`).join(';')}`;
+}
+
+/** Retain one road and its dot population across tile and surface publications. */
+export function createRetention({ state, parts }) {
+  const records = new Map();
+  const heightStep = new Cesium.Cartesian3();
+  const screenFrom = new Cesium.Cartesian2();
+  const screenTo = new Cesium.Cartesian2();
+  const eye = new Cesium.Cartesian3();
+  function projectSafely(scene, point, screen) {
+    if (scene.camera.viewMatrix) {
+      Cesium.Matrix4.multiplyByPoint(scene.camera.viewMatrix, point, eye);
+      if (eye.z >= -(scene.camera.frustum?.near || 0)) return false;
+    }
+    return (
+      Boolean(
+        Cesium.SceneTransforms.worldToWindowCoordinates(scene, point, screen),
+      ) &&
+      Number.isFinite(screen.x) &&
+      Number.isFinite(screen.y)
+    );
+  }
+  function nearCanvas(scene, point, screen) {
+    return (
+      projectSafely(scene, point, screen) &&
+      screen.x >= -100 &&
+      screen.x <= scene.canvas.clientWidth + 100 &&
+      screen.y >= -100 &&
+      screen.y <= scene.canvas.clientHeight + 100
+    );
+  }
+  let timer = null;
+  let altitude = 0;
+  const schedule = () => {
+    if (timer !== null) return;
+    state._populationPending = true;
+    timer =
+      typeof requestAnimationFrame === 'function'
+        ? requestAnimationFrame(pump)
+        : setTimeout(pump, 16);
+  };
+  function pump() {
+    timer = null;
+    if (!state._enabled) return;
+    let budget = DOT_CHANGE_BUDGET;
+    let pending = false;
+    const now = Date.now();
+    // Removing a road or reducing density fades only surplus dots. A retained
+    // dot never changes road, direction, segment or progress.
+    for (const record of records.values()) {
+      record.road.flow = record.road.source.flow;
+      if (
+        record.road.flow?.closure ||
+        (state._liveMode &&
+          !record.road.flow &&
+          state._uncoveredMode === 'hide')
+      )
+        record.target = 0;
+      for (let i = record.dots.length - 1; i >= 0 && budget > 0; i--) {
+        const dot = record.dots[i];
+        if (!dot.retiring || now - dot.retiring < DOT_FADE_MS) continue;
+        state._pointCollection.remove(dot.point);
+        const last = state._dots.pop();
+        if (last !== dot) {
+          state._dots[dot.index] = last;
+          last.index = dot.index;
+        }
+        record.dots.splice(i, 1);
+        budget--;
+        state._motion.removed++;
+      }
+      let active = 0;
+      for (const dot of record.dots) if (!dot.retiring) active++;
+      for (
+        let i = record.dots.length - 1;
+        active > record.target && i >= 0 && budget > 0;
+        i--
+      ) {
+        const dot = record.dots[i];
+        if (dot.retiring) continue;
+        dot.retiring = now;
+        active--;
+        budget--;
+      }
+      if (active < record.target && budget > 0) {
+        const count = Math.min(
+          record.target - active,
+          budget,
+          MAX_DOTS - state._dots.length,
+        );
+        if (count > 0) {
+          const before = state._dots.length;
+          parts.animation.spawnDotsForRoad(record.road, altitude, count);
+          for (let i = before; i < state._dots.length; i++)
+            record.dots.push(state._dots[i]);
+          budget -= state._dots.length - before;
+          active += state._dots.length - before;
+        }
+      }
+      if (active !== record.target || record.dots.length !== active)
+        pending = true;
+      if (!record.target && !record.dots.length)
+        records.delete(record.road.key);
+    }
+    refreshCounts();
+    state._populationPending = pending;
+    if (pending) schedule();
+  }
+  function refreshCounts() {
+    const counts = state._bucketCounts;
+    counts.free = counts.slow = counts.jam = counts.sim = 0;
+    let count = 0;
+    for (const dot of state._dots) {
+      if (!dot.point.show) continue;
+      counts[dot.bucket || 'sim']++;
+      count++;
+    }
+    state._count = count;
+  }
+  function reconcile(roads, height, replace) {
+    altitude = height;
+    if (replace) for (const record of records.values()) record.wanted = false;
+    for (const candidate of roads) {
+      const key = candidate.key || roadIdentity(candidate);
+      candidate.key = key;
+      let record = records.get(key);
+      if (!record) {
+        // Surface sampling owns the incoming arrays. Animation owns copies,
+        // so an asynchronous height pass cannot move half a road in one frame.
+        const road = {
+          ...candidate,
+          waypoints: candidate.waypoints.map((p) => Cesium.Cartesian3.clone(p)),
+          segmentDist: candidate.segmentDist.slice(),
+          source: candidate,
+          targetWaypoints: candidate.waypoints.map((p) =>
+            Cesium.Cartesian3.clone(p),
+          ),
+          heightMoving: false,
+        };
+        record = { road, dots: [], target: 0, wanted: true };
+        records.set(key, record);
+      } else if (candidate !== record.road) {
+        record.road.source = candidate;
+        record.road.flow = candidate.flow;
+        record.road.densityWeight = candidate.densityWeight;
+        for (let i = 0; i < candidate.waypoints.length; i++) {
+          if (
+            !Cesium.Cartesian3.equalsEpsilon(
+              record.road.targetWaypoints[i],
+              candidate.waypoints[i],
+              0,
+              0.01,
+            )
+          )
+            record.road.heightMoving = state._heightPending = true;
+          Cesium.Cartesian3.clone(
+            candidate.waypoints[i],
+            record.road.targetWaypoints[i],
+          );
+        }
+      }
+      record.wanted = true;
+    }
+    const wanted = [];
+    for (const record of records.values()) {
+      if (record.wanted) wanted.push(record.road);
+      else record.target = 0;
+    }
+    const budgets = parts.model.allocateRoadDotBudgets(
+      wanted,
+      altitude,
+      roadDotBudget(altitude),
+    );
+    for (let i = 0; i < wanted.length; i++)
+      records.get(wanted[i].key).target = budgets[i];
+    state._roads = wanted;
+    state._motion.publishes++;
+    // First paint gets one bounded batch without an additional frame wait.
+    if (!state._dots.length && timer === null) pump();
+    else schedule();
+  }
+  function easeHeights(dt) {
+    const blend = Math.min(1, dt * 12);
+    const scene = state._viewer?.scene;
+    const canProject =
+      scene?.canvas?.clientHeight && scene.camera && scene.frameState;
+    state._heightPending = false;
+    for (let r = 0; r < state._roads.length; r++) {
+      const road = state._roads[r];
+      if (!road.heightMoving) continue;
+      let moving = false;
+      for (let i = 0; i < road.waypoints.length; i++) {
+        const point = road.waypoints[i],
+          target = road.targetWaypoints[i];
+        if (Cesium.Cartesian3.distanceSquared(point, target) < 0.0001)
+          Cesium.Cartesian3.clone(target, point);
+        else {
+          const visible = canProject && nearCanvas(scene, point, screenFrom);
+          let step = visible
+            ? blend
+            : Math.min(
+                blend,
+                (120 * dt) / Cesium.Cartesian3.distance(point, target),
+              );
+          if (visible) {
+            let safe = false;
+            for (let attempt = 0; attempt < 16; attempt++) {
+              Cesium.Cartesian3.lerp(point, target, step, heightStep);
+              if (!projectSafely(scene, heightStep, screenTo)) {
+                step *= 0.5;
+                continue;
+              }
+              const pixels = Cesium.Cartesian2.distance(screenFrom, screenTo);
+              if (pixels <= 12) {
+                safe = true;
+                break;
+              }
+              step *= 11.5 / pixels;
+            }
+            if (!safe) step = 0;
+          }
+          state._heightPending ||= !canProject || visible;
+          Cesium.Cartesian3.lerp(point, target, step, point);
+          moving = true;
+        }
+      }
+      for (let i = 0; i < road.segmentDist.length; i++)
+        road.segmentDist[i] = Cesium.Cartesian3.distance(
+          road.waypoints[i],
+          road.waypoints[i + 1],
+        );
+      road.heightMoving = moving;
+    }
+  }
+  function clear() {
+    if (timer !== null) {
+      if (typeof cancelAnimationFrame === 'function')
+        cancelAnimationFrame(timer);
+      else clearTimeout(timer);
+      timer = null;
+    }
+    records.clear();
+    state._populationPending = false;
+    state._heightPending = false;
+  }
+  return { reconcile, easeHeights, clear, refreshCounts };
+}

src/layers/traffic/roadModes.js

@@ -0,0 +1,247 @@
+import { createFlowSegmentIndex } from '../../data/flowMatch.js';
+
+/**
+ * @file Street Traffic road-source modes: which geometry the dots run on.
+ *
+ * - `tomtom`: TomTom flow-tile lines only, each coloured by its own flow.
+ * - `osm`: OpenFreeMap (OpenStreetMap) lines, TomTom flow matched onto them.
+ * - `hybrid`: TomTom lines where TomTom has a road, OpenFreeMap lines only
+ *   where it does not (simulated).
+ *
+ * Pure and Cesium-free so selection and dedupe are unit-testable.
+ *
+ * @module layers/traffic/roadModes
+ */
+
+export const TRAFFIC_ROAD_MODES = Object.freeze(['tomtom', 'osm', 'hybrid']);
+
+/** Status-line names for the geometry each mode draws. */
+export const ROAD_SOURCE_LABELS = Object.freeze({
+  tomtom: 'TomTom',
+  osm: 'OpenStreetMap',
+  hybrid: 'TomTom + OpenStreetMap',
+});
+
+/** Sample spacing along OpenFreeMap roads when testing TomTom overlap. */
+const DEDUPE_STEP_M = 10;
+/** A partly duplicated road keeps only uncovered stretches at least this long. */
+const MIN_FILL_M = 40;
+/**
+ * Overlap radius when exactly one side is a controlled-access road
+ * (motorway/trunk mainline) and the other is not. The same road drawn by
+ * both sources agrees within a few metres (z12 flow tiles quantize to about
+ * 2.4 m), while frontage and service roads beside a freeway run 20-40 m
+ * from its line; 15 m keeps the first a duplicate and the second a road.
+ * Same-class overlap keeps the full 35 m matcher radius.
+ */
+const CLASS_MISMATCH_RADIUS_M = 15;
+const CONTROLLED_ACCESS_FLOW = new Set(['Motorway', 'International road']);
+const CONTROLLED_ACCESS_OSM = new Set(['motorway', 'trunk']);
+
+/**
+ * Validate an explicit choice.
+ * @param {*} value - Candidate mode.
+ * @returns {'tomtom'|'osm'|'hybrid'|null} Null means "use the default".
+ */
+export function normalizeRoadMode(value) {
+  return TRAFFIC_ROAD_MODES.includes(value) ? value : null;
+}
+
+/**
+ * Resolve the mode actually drawn. Without a TomTom key every choice draws
+ * OpenStreetMap roads; with one, an explicit choice wins over Hybrid.
+ * @param {*} value - Requested mode (null for the default).
+ * @param {boolean} hasKey - The server reported a TomTom key.
+ * @returns {'tomtom'|'osm'|'hybrid'}
+ */
+export function resolveRoadMode(value, hasKey) {
+  return hasKey ? normalizeRoadMode(value) || 'hybrid' : 'osm';
+}
+
+const FLOW_ROAD_TYPES = Object.freeze({
+  Motorway: 'motorway',
+  'International road': 'trunk',
+  'Major road': 'primary',
+  'Secondary road': 'secondary',
+  'Connecting road': 'tertiary',
+  'Major local road': 'tertiary',
+  'Local road': 'residential',
+  'Minor local road': 'residential',
+});
+
+/** Unknown/private/parking/walking categories never become vehicles or suppress OSM fill. */
+export function isDrivableFlowSegment(segment) {
+  return (
+    Object.hasOwn(FLOW_ROAD_TYPES, segment?.roadType) &&
+    (!segment.roadCategory ||
+      [
+        'motorway',
+        'trunk',
+        'primary',
+        'secondary',
+        'tertiary',
+        'street',
+      ].includes(segment.roadCategory))
+  );
+}
+
+/**
+ * Convert decoded TomTom flow lines into road records that carry their own
+ * flow. A line with `coverage: 'full'` describes both travel directions;
+ * `one_side` lines describe the direction they are drawn in.
+ * @param {Array<{coords:number[][], trafficLevel:number, roadType:string, closure:boolean, coverage?:string}>} segments
+ * @returns {Array<object>} Road records (`directFlow: true`).
+ */
+export function flowSegmentsToRoads(segments) {
+  return (segments || [])
+    .filter(
+      (segment) =>
+        segment?.coords?.length >= 2 && isDrivableFlowSegment(segment),
+    )
+    .map((segment) => ({
+      coordinates: segment.coords,
+      type: FLOW_ROAD_TYPES[segment.roadType],
+      drivable: true,
+      roadClass: segment.roadType,
+      roadProperties: {
+        roadType: segment.roadType,
+        roadCategory: segment.roadCategory,
+      },
+      oneway: segment.coverage === 'full' ? 0 : 1,
+      flow: { level: segment.trafficLevel, closure: segment.closure === true },
+      directFlow: true,
+    }));
+}
+
+/** Cut a projected polyline to the arc-length interval [from, to]. */
+function slicePolyline(coords, cum, from, to) {
+  const out = [];
+  const at = (i, distance) => {
+    const span = cum[i + 1] - cum[i] || 1;
+    const t = (distance - cum[i]) / span;
+    return [
+      coords[i][0] + (coords[i + 1][0] - coords[i][0]) * t,
+      coords[i][1] + (coords[i + 1][1] - coords[i][1]) * t,
+    ];
+  };
+  for (let i = 0; i < coords.length - 1; i++) {
+    if (cum[i + 1] < from || cum[i] > to) continue;
+    if (!out.length) out.push(cum[i] >= from ? coords[i] : at(i, from));
+    if (cum[i + 1] <= to) out.push(coords[i + 1]);
+    else {
+      out.push(at(i, to));
+      break;
+    }
+  }
+  return out.length >= 2 ? out : null;
+}
+
+/**
+ * Stretches of one travel direction of an OpenFreeMap road that no TomTom
+ * line covers. A sample is covered when a TomTom line lies within the flow
+ * matcher's 35 m radius (15 m across a controlled-access class mismatch)
+ * and agrees with its travel bearing (30 degrees).
+ * Flow values are ignored: any geometric overlap counts, so an uncertain
+ * duplicate is dropped from OpenFreeMap, never from TomTom.
+ * @returns {number[][][]|'all'} Uncovered polylines, or 'all' when untouched.
+ */
+function uncoveredStretches(coords, direction, index, radiusFor) {
+  const xs = [],
+    ys = [],
+    cum = [0];
+  for (let i = 0; i < coords.length; i++) {
+    const [x, y] = index.project(coords[i][0], coords[i][1]);
+    xs.push(x);
+    ys.push(y);
+    if (i) cum.push(cum[i - 1] + Math.hypot(x - xs[i - 1], y - ys[i - 1]));
+  }
+  const length = cum[cum.length - 1];
+  if (!(length > 0)) return [];
+  const count = Math.max(2, Math.ceil(length / DEDUPE_STEP_M));
+  const step = length / count;
+  const runs = [];
+  let runStart = null;
+  let cursor = 1;
+  for (let s = 0; s < count; s++) {
+    const target = (s + 0.5) * step;
+    while (cursor < coords.length - 1 && cum[cursor] < target) cursor++;
+    const t = (target - cum[cursor - 1]) / (cum[cursor] - cum[cursor - 1] || 1);
+    const dx = xs[cursor] - xs[cursor - 1];
+    const dy = ys[cursor] - ys[cursor - 1];
+    const bearing =
+      (Math.atan2(dx, dy) * 180) / Math.PI + (direction === -1 ? 180 : 0);
+    const covered = Boolean(
+      index.nearest(
+        xs[cursor - 1] + dx * t,
+        ys[cursor - 1] + dy * t,
+        bearing,
+        radiusFor,
+      ).best,
+    );
+    if (!covered && runStart === null) runStart = s;
+    if (covered && runStart !== null) {
+      runs.push([runStart * step, s * step]);
+      runStart = null;
+    }
+  }
+  if (runStart === 0) return 'all';
+  if (runStart !== null) runs.push([runStart * step, length]);
+  return runs
+    .filter(([from, to]) => to - from >= MIN_FILL_M)
+    .map(([from, to]) => slicePolyline(coords, cum, from, to))
+    .filter(Boolean);
+}
+
+/**
+ * Build the Hybrid OpenFreeMap fill for a set of TomTom flow lines: every
+ * OpenFreeMap road or travel direction that TomTom does not already draw,
+ * marked simulated. Returns a function so callers can memoize per road.
+ * @param {Array<object>} segments - Decoded TomTom flow lines.
+ * @returns {(road:object) => Array<object>} Fill records for one OSM road.
+ */
+export function createHybridFill(segments) {
+  const index = createFlowSegmentIndex(
+    (segments || []).filter(isDrivableFlowSegment),
+  );
+  return (road) => {
+    const coords = road?.coordinates;
+    if (!Array.isArray(coords) || coords.length < 2) return [];
+    const fill = { ...road, simulatedOnly: true };
+    if (!index) return [fill];
+    // Ramps leave the mainline, so they compare as ordinary roads.
+    const controlled = CONTROLLED_ACCESS_OSM.has(road.type) && !road.ramp;
+    const radiusFor = (segment) =>
+      CONTROLLED_ACCESS_FLOW.has(segment.roadType) === controlled
+        ? Infinity
+        : CLASS_MISMATCH_RADIUS_M;
+    const directions = road.oneway ? [road.oneway] : [1, -1];
+    const stretches = directions.map((direction) =>
+      uncoveredStretches(coords, direction, index, radiusFor),
+    );
+    if (stretches.every((result) => result === 'all')) return [fill];
+    return directions.flatMap((direction, i) =>
+      (stretches[i] === 'all' ? [coords] : stretches[i]).map((piece) => ({
+        ...fill,
+        coordinates: piece,
+        oneway: direction,
+        // A two-way road's single direction keeps its half share of dots.
+        densityWeight: road.oneway ? 1 : 0.5,
+      })),
+    );
+  };
+}
+
+/**
+ * Select the roads a mode draws from already-fetched inputs.
+ * @param {Array<object>} osmRoads - OpenFreeMap road records.
+ * @param {Array<object>} segments - Decoded TomTom flow lines.
+ * @param {'tomtom'|'osm'|'hybrid'} mode - Resolved mode.
+ * @returns {Array<object>} Road records for `parseRoads`.
+ */
+export function selectTrafficRoads(osmRoads, segments, mode) {
+  if (mode === 'osm') return osmRoads;
+  const tomtom = flowSegmentsToRoads(segments);
+  if (mode === 'tomtom') return tomtom;
+  const fill = createHybridFill(segments);
+  return [...tomtom, ...osmRoads.flatMap(fill)];
+}

src/layers/traffic/roadModes.test.mjs

@@ -0,0 +1,554 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  flowSegmentsToRoads,
+  resolveRoadMode,
+  selectTrafficRoads,
+} from './roadModes.js';
+import { createTrafficSource } from './source.js';
+import { createTrafficLayer } from './index.js';
+import {
+  createDefaultLayerState,
+  encodeLayerStateParams,
+  decodeLayerStateParams,
+  serializeStoredLayerState,
+  parseStoredLayerState,
+} from '../../data/layerState.js';
+
+const coordinates = [
+  [-97.744, 30.267],
+  [-97.742, 30.267],
+];
+const main = { coordinates, type: 'primary', oneway: 1 };
+const side = {
+  coordinates: [
+    [-97.743, 30.267],
+    [-97.743, 30.269],
+  ],
+  type: 'residential',
+  oneway: 1,
+};
+const flow = {
+  coords: coordinates,
+  trafficLevel: 0.3,
+  closure: false,
+  roadType: 'Major road',
+};
+const box = { west: -97.75, east: -97.74, south: 30.26, north: 30.27 };
+
+test('road modes have key-aware defaults, explicit overrides and keyless fallback', () => {
+  assert.equal(resolveRoadMode(null, true), 'hybrid');
+  assert.equal(resolveRoadMode(null, false), 'osm');
+  assert.equal(resolveRoadMode('invalid', true), 'hybrid');
+  for (const mode of ['tomtom', 'osm', 'hybrid']) {
+    assert.equal(resolveRoadMode(mode, true), mode);
+    assert.equal(resolveRoadMode(mode, false), 'osm');
+  }
+});
+test('Hybrid keeps TomTom and the unmatched OSM side street, with simulated fill', () => {
+  const roads = selectTrafficRoads([main, side], [flow], 'hybrid');
+  assert.equal(roads.length, 2);
+  assert.equal(roads[0].directFlow, true);
+  assert.equal(roads[0].flow.level, 0.3);
+  assert.equal(roads[1].simulatedOnly, true);
+  assert.deepEqual(roads[1].coordinates, side.coordinates);
+  assert.equal(selectTrafficRoads([main, side], [flow], 'tomtom').length, 1);
+  assert.deepEqual(selectTrafficRoads([main, side], [flow], 'osm'), [
+    main,
+    side,
+  ]);
+});
+test('opposite-direction carriageways and the reverse half of two-way roads survive', () => {
+  for (const reverse of [
+    { ...main, oneway: -1 },
+    { ...main, coordinates: [...coordinates].reverse() },
+  ]) {
+    assert.equal(selectTrafficRoads([reverse], [flow], 'hybrid').length, 2);
+  }
+  const twoWay = selectTrafficRoads([{ ...main, oneway: 0 }], [flow], 'hybrid');
+  assert.equal(twoWay.length, 2);
+  assert.equal(twoWay[1].oneway, -1);
+  assert.equal(twoWay[1].densityWeight, 0.5);
+});
+test('uncertain flow values still dedupe OSM; every TomTom road and closure survives', () => {
+  const closed = { ...flow, trafficLevel: 0, closure: true };
+  const roads = selectTrafficRoads([main], [flow, closed], 'hybrid');
+  assert.equal(roads.length, 2);
+  assert.ok(roads.every((road) => road.directFlow));
+  assert.equal(roads[1].flow.closure, true);
+});
+test('a partly covered OSM road keeps only its uncovered stretch', () => {
+  // 0.004° of longitude at 30.267° N is about 385 m; TomTom covers the west half.
+  const long = {
+    coordinates: [
+      [-97.744, 30.267],
+      [-97.74, 30.267],
+    ],
+    type: 'primary',
+    oneway: 1,
+  };
+  const roads = selectTrafficRoads([long], [flow], 'hybrid');
+  assert.equal(roads.length, 2);
+  const [piece] = roads.slice(1);
+  assert.equal(piece.simulatedOnly, true);
+  // The kept stretch starts within one 35 m match radius of the TomTom end.
+  assert.ok(piece.coordinates[0][0] > -97.742);
+  assert.ok(piece.coordinates[0][0] < -97.741);
+  assert.deepEqual(piece.coordinates.at(-1), [-97.74, 30.267]);
+});
+test('an uncovered sliver shorter than 40 m is dropped with its duplicate', () => {
+  // About 67 m past the TomTom end: the last ~32 m is beyond the 35 m radius.
+  const sliver = {
+    coordinates: [
+      [-97.744, 30.267],
+      [-97.7413, 30.267],
+    ],
+    type: 'primary',
+    oneway: 1,
+  };
+  assert.equal(selectTrafficRoads([sliver], [flow], 'hybrid').length, 1);
+});
+test('a full-coverage TomTom line is two-way and covers both OSM directions', () => {
+  const both = { ...flow, coverage: 'full' };
+  assert.equal(flowSegmentsToRoads([both])[0].oneway, 0);
+  assert.equal(flowSegmentsToRoads([flow])[0].oneway, 1);
+  const roads = selectTrafficRoads([{ ...main, oneway: 0 }], [both], 'hybrid');
+  assert.equal(roads.length, 1);
+  assert.equal(roads[0].directFlow, true);
+});
+test('bearing and distance reject nearby crossing and separate OSM roads', () => {
+  const parallel = {
+    ...main,
+    coordinates: coordinates.map(([lon, lat]) => [lon, lat + 0.001]),
+  };
+  assert.equal(
+    selectTrafficRoads([side, parallel], [flow], 'hybrid').length,
+    3,
+  );
+});
+function sourceFixture() {
+  let requests = 0;
+  const source = createTrafficSource({
+    mapTiles: {
+      async fetchBounds(bounds, { onTile }) {
+        requests++;
+        const tile = { roads: [main, side] };
+        onTile?.(tile);
+        return { tiles: [tile], partial: false };
+      },
+      clear() {},
+    },
+  });
+  return { source, requests: () => requests };
+}
+test('TomTom-only skips OSM requests; keyless selection requests OSM and labels fallback', async () => {
+  for (const hasKey of [true, false]) {
+    const f = sourceFixture();
+    const data = await (
+      await f.source.requestRoads(box, {
+        roadMode: 'tomtom',
+        flowSnapshot: Promise.resolve({
+          hasKey,
+          segments: hasKey ? [flow] : [],
+        }),
+      })
+    ).json();
+    assert.equal(data.roadSource, hasKey ? 'TomTom' : 'OpenStreetMap');
+    assert.equal(f.requests(), hasKey ? 0 : 1);
+    assert.equal(data.roads.length, hasKey ? 1 : 2);
+  }
+});
+test('Hybrid streams OSM before flow settles then replaces duplicates with TomTom', async () => {
+  const f = sourceFixture();
+  let resolve;
+  const snapshots = [];
+  const pending = f.source.requestRoads(box, {
+    roadMode: 'hybrid',
+    flowSnapshot: new Promise((done) => {
+      resolve = done;
+    }),
+    onTile: (data) => snapshots.push(data),
+  });
+  await Promise.resolve();
+  assert.equal(snapshots[0].roadSource, 'OpenStreetMap');
+  assert.equal(snapshots[0].roads.length, 2);
+  resolve({ hasKey: true, segments: [flow] });
+  const final = await (await pending).json();
+  assert.equal(final.roadSource, 'TomTom + OpenStreetMap');
+  assert.equal(final.roads.length, 2);
+  assert.ok(snapshots.at(-1).replace);
+});
+test('road-source params persist in existing layer-state lo field and local storage', () => {
+  for (const mode of ['tomtom', 'osm', 'hybrid']) {
+    const state = createDefaultLayerState();
+    state.enabledLayerIds = ['traffic'];
+    state.options.traffic.roadMode = mode;
+    const params = new URLSearchParams('v=2');
+    encodeLayerStateParams(params, state);
+    assert.deepEqual([...params.keys()].sort(), ['l', 'lo', 'v']);
+    assert.equal(decodeLayerStateParams(params).options.traffic.roadMode, mode);
+    assert.equal(
+      parseStoredLayerState(serializeStoredLayerState(state)).options.traffic
+        .roadMode,
+      mode,
+    );
+  }
+});
+test('row chips use real params; query overrides passive restore and user can change it', () => {
+  const oldLocation = globalThis.location;
+  globalThis.location = { search: '?trafficRoads=tomtom' };
+  try {
+    const layer = createTrafficLayer({
+      services: { credits: {}, render: {} },
+      source: {
+        requestRoads() {},
+        getStatus() {},
+        fetchFlowForBounds() {},
+        getFlowSessionStats: () => ({}),
+        resetFlowTileCache() {},
+      },
+    });
+    layer.setParams({ roadMode: 'osm' }, { origin: 'local-restore' });
+    assert.equal(layer.getParams().roadMode, 'tomtom');
+    const chips = layer.getRowControls().chips;
+    assert.equal(chips.length, 3);
+    assert.equal(chips[0].active, true);
+    layer.setParams(chips[2].params, { origin: 'user' });
+    assert.equal(layer.getParams().roadMode, 'hybrid');
+    assert.match(layer.getStats().loadingLabel, /Hybrid needs a TomTom key/);
+    assert.equal(layer.getStats().roadMode, 'osm');
+  } finally {
+    if (oldLocation === undefined) delete globalThis.location;
+    else globalThis.location = oldLocation;
+  }
+});
+
+test('Hybrid retains TomTom on OSM outage with a named warning; TomTom failure never invents roads', async () => {
+  const source = createTrafficSource({
+    mapTiles: {
+      fetchBounds: async () => {
+        throw Object.assign(new Error('refused'), { status: 429 });
+      },
+    },
+  });
+  const data = await (
+    await source.requestRoads(box, {
+      roadMode: 'hybrid',
+      flowSnapshot: Promise.resolve({ hasKey: true, segments: [flow] }),
+    })
+  ).json();
+  assert.equal(data.roads.length, 1);
+  assert.equal(data.roads[0].directFlow, true);
+  assert.equal(data.partial, true);
+  assert.equal(data.roadWarning, 'OpenFreeMap tiles rate-limited');
+  await assert.rejects(
+    source.requestRoads(box, {
+      roadMode: 'tomtom',
+      flowSnapshot: Promise.resolve({
+        hasKey: true,
+        segments: [],
+        error: 'TomTom daily budget reached',
+      }),
+    }),
+    /TomTom daily budget reached/,
+  );
+});
+
+test('flow application preserves direct values and leaves Hybrid fill simulated', async () => {
+  const { createFlow } = await import('./flow.js');
+  const direct = {
+    coords: coordinates,
+    directFlow: true,
+    flow: { level: 0.15, closure: true },
+  };
+  const fill = { coords: coordinates, simulatedOnly: true };
+  const osm = { coords: coordinates };
+  const state = {
+    _enabled: true,
+    _liveMode: true,
+    _loadGeneration: 1,
+    _flowPending: 0,
+    _flowStatusPromise: Promise.resolve(),
+  };
+  const controller = createFlow({
+    state,
+    services: { credits: {} },
+    parts: {},
+    source: { fetchFlowForBounds: async () => [flow] },
+  });
+  await controller.applyFlowToRoads([direct, fill, osm], box, 1);
+  assert.deepEqual(direct.flow, { level: 0.15, closure: true });
+  assert.equal(fill.flow, null);
+  assert.deepEqual(osm.flow, { level: 0.3, closure: false });
+  assert.equal(state._flowPending, 0);
+});
+
+test('status names the drawn road source for each mode', async () => {
+  const { createModel } = await import('./model.js');
+  const { trafficFeedPresentation: present } = createModel({
+    state: {},
+    services: {},
+    parts: {},
+    source: {},
+  });
+  assert.equal(
+    present({ liveMode: true, coveragePct: 100, roadSource: 'TomTom' })
+      .loadingLabel,
+    'LIVE · Roads: TomTom · Roads without flow hidden',
+  );
+  assert.equal(
+    present({ liveMode: true, coveragePct: 0, roadSource: 'TomTom' })
+      .loadingLabel,
+    'LIVE · Roads: TomTom · No flow roads in view',
+  );
+  assert.equal(
+    present({
+      liveMode: true,
+      coveragePct: 81,
+      roadSource: 'TomTom + OpenStreetMap',
+    }).loadingLabel,
+    'LIVE · Roads: TomTom + OpenStreetMap · Flow 81%',
+  );
+  assert.match(
+    present({ liveMode: true, coveragePct: 74 }).loadingLabel,
+    /^LIVE · Roads: OpenStreetMap · Flow: TomTom · 74% cov/,
+  );
+});
+
+test('only explicit origins clear the query override; restores keep it', () => {
+  const oldLocation = globalThis.location;
+  globalThis.location = { search: '?trafficRoads=osm' };
+  try {
+    const layer = createTrafficLayer({
+      services: { credits: {}, render: {} },
+      source: {
+        requestRoads() {},
+        getStatus() {},
+        fetchFlowForBounds() {},
+        getFlowSessionStats: () => ({}),
+        resetFlowTileCache() {},
+      },
+    });
+    for (const origin of ['share-restore', 'local-restore', 'programmatic']) {
+      layer.setParams({ roadMode: 'tomtom' }, { origin });
+      assert.equal(layer.getParams().roadMode, 'osm', origin);
+    }
+    layer.setParams({ roadMode: 'tomtom' }, { origin: 'voice' });
+    assert.equal(layer.getParams().roadMode, 'tomtom');
+    layer.setParams({ roadMode: null }, { origin: 'local-restore' });
+    assert.equal(layer.getParams().roadMode, null);
+  } finally {
+    if (oldLocation === undefined) delete globalThis.location;
+    else globalThis.location = oldLocation;
+  }
+});
+
+test('TomTom and Hybrid loads skip the OSM snapshot cache; TomTom skips the detail pass', async () => {
+  const { createIngestion } = await import('./ingestion.js');
+  for (const [roadMode, roadSource, perLoad] of [
+    [null, 'TomTom + OpenStreetMap', [true, false]],
+    ['tomtom', 'TomTom', [true]],
+  ]) {
+    const state = {
+      _loadGeneration: 0,
+      _tileCache: new Map(),
+      _enabled: true,
+      _liveMode: true,
+      _roadMode: roadMode,
+      _parseRoads: (data) => data.roads,
+    };
+    const passes = [];
+    const ingestion = createIngestion({
+      state,
+      services: {},
+      parts: {
+        viewport: {
+          clampBounds: (b) => b,
+          getBoundsCenter: () => ({ lat: 30.267, lon: -97.744 }),
+        },
+        flow: {
+          warmFlow: async () => [flow],
+          applyFlowThenRender: async () => true,
+        },
+      },
+      source: {
+        requestRoads: async (_, options) => {
+          passes.push(options.majorOnly);
+          assert.equal(options.roadMode, roadMode);
+          assert.equal((await options.flowSnapshot).hasKey, true);
+          return {
+            ok: true,
+            json: async () => ({ roads: [main], roadSource }),
+          };
+        },
+      },
+    });
+    await ingestion.loadRoadsForBounds(box, 350);
+    await ingestion.loadRoadsForBounds(box, 350);
+    assert.deepEqual(passes, [...perLoad, ...perLoad], roadSource);
+    assert.equal(state._tileCache.size, 0);
+    assert.equal(state._roadSource, roadSource);
+  }
+});
+
+test('a first keyed load whose flow fails never caches simulated fill as OSM roads', async () => {
+  const { createIngestion } = await import('./ingestion.js');
+  // Status unknown at the start of the first load; the probe then reports a
+  // key but flow fails, so Hybrid draws only simulated OpenStreetMap fill,
+  // labelled OpenStreetMap.
+  const state = {
+    _loadGeneration: 0,
+    _tileCache: new Map(),
+    _enabled: true,
+    _liveMode: false,
+    _roadMode: null,
+    _parseRoads: (data) => data.roads,
+  };
+  const requests = [];
+  const ingestion = createIngestion({
+    state,
+    services: {},
+    parts: {
+      viewport: {
+        clampBounds: (b) => b,
+        getBoundsCenter: () => ({ lat: 30.267, lon: -97.744 }),
+      },
+      flow: {
+        warmFlow: async () => {
+          state._liveMode = true;
+          state._flowStatusKnown = true;
+          throw Object.assign(new Error('flow'), { status: 502 });
+        },
+        deriveTrafficFlowError: () => 'TomTom upstream unreachable',
+        applyFlowThenRender: async () => true,
+      },
+    },
+    source: {
+      requestRoads: async (_, options) => {
+        const live = await options.flowSnapshot;
+        const mode = resolveRoadMode(options.roadMode, live.hasKey);
+        requests.push(mode);
+        const roads =
+          mode === 'osm' ? [main] : [{ ...main, simulatedOnly: true }];
+        return {
+          ok: true,
+          json: async () => ({
+            roads,
+            roadSource: 'OpenStreetMap',
+            roadMode: mode,
+          }),
+        };
+      },
+    },
+  });
+  await ingestion.loadRoadsForBounds(box, 350);
+  assert.deepEqual(requests, ['hybrid', 'hybrid']);
+  assert.equal(state._tileCache.size, 0, 'Hybrid fill is never cached');
+  // The user switches to OSM: fresh OpenStreetMap roads, not the fill.
+  state._roadMode = 'osm';
+  await ingestion.loadRoadsForBounds(box, 350);
+  assert.deepEqual(requests.slice(2), ['osm', 'osm']);
+  const [entry] = state._tileCache.values();
+  assert.ok(entry.full.every((road) => !road.simulatedOnly));
+  // ...and those plain OSM roads are what a revisit reuses.
+  await ingestion.loadRoadsForBounds(box, 350);
+  assert.equal(requests.length, 4);
+});
+
+test('a flow snapshot that misses the pass deadline cannot hold roads', async () => {
+  const never = new Promise(() => {});
+  const request = (roadMode, hasKey) =>
+    sourceFixture().source.requestRoads(box, {
+      roadMode,
+      flowSnapshot: never,
+      liveModeHint: () => hasKey,
+      timeoutSec: 0.02,
+    });
+  const keyless = await (await request(null, false)).json();
+  assert.equal(keyless.roadMode, 'osm');
+  assert.equal(keyless.roads.length, 2);
+  const hybrid = await (await request(null, true)).json();
+  assert.equal(hybrid.roadMode, 'hybrid');
+  assert.equal(hybrid.roadSource, 'OpenStreetMap');
+  assert.ok(hybrid.roads.every((road) => road.simulatedOnly));
+  await assert.rejects(request('tomtom', true), /TomTom flow timed out/);
+});
+
+test('frontage roads beside a TomTom motorway survive; same-class duplicates do not', () => {
+  const offset = (road, metres, extra = {}) => ({
+    ...road,
+    ...extra,
+    coordinates: road.coordinates.map(([lon, lat]) => [
+      lon,
+      lat + metres / 111320,
+    ]),
+  });
+  const motorwayLine = { ...flow, roadType: 'Motorway' };
+  const osmMotorway = { ...main, type: 'motorway' };
+  const roads = selectTrafficRoads(
+    [
+      offset(osmMotorway, 4), // the same motorway: dropped
+      offset(main, 25, { type: 'residential' }), // frontage, north side
+      offset(main, -25, { type: 'tertiary' }), // frontage, south side
+    ],
+    [motorwayLine],
+    'hybrid',
+  );
+  assert.equal(roads.length, 3);
+  assert.equal(roads[0].directFlow, true);
+  assert.deepEqual(
+    roads.slice(1).map((road) => road.type),
+    ['residential', 'tertiary'],
+  );
+  // A ramp beside the mainline compares as an ordinary road.
+  assert.equal(
+    selectTrafficRoads(
+      [offset(osmMotorway, 25, { ramp: true })],
+      [motorwayLine],
+      'hybrid',
+    ).length,
+    2,
+  );
+  // Across a class mismatch a true duplicate (within 15 m) is still dropped.
+  assert.equal(
+    selectTrafficRoads(
+      [offset(main, 6, { type: 'residential' })],
+      [motorwayLine],
+      'hybrid',
+    ).length,
+    1,
+  );
+  // Same class, uncertain 25 m overlap: the OpenStreetMap copy goes.
+  assert.equal(
+    selectTrafficRoads(
+      [offset(main, 25, { type: 'residential' })],
+      [{ ...flow, roadType: 'Local road' }],
+      'hybrid',
+    ).length,
+    1,
+  );
+});
+
+test('private, parking, walking and unknown flow never animate or suppress a public OSM road', () => {
+  for (const roadType of [
+    'Non public road',
+    'Parking road',
+    'Walkway road',
+    '',
+    'Other road',
+  ]) {
+    const rejected = { ...flow, roadType };
+    assert.deepEqual(flowSegmentsToRoads([rejected]), []);
+    const roads = selectTrafficRoads([main], [rejected], 'hybrid');
+    assert.equal(roads.length, 1);
+    assert.equal(roads[0].simulatedOnly, true);
+    assert.deepEqual(roads[0].coordinates, main.coordinates);
+  }
+  assert.deepEqual(
+    flowSegmentsToRoads([{ ...flow, roadCategory: 'walkway' }]),
+    [],
+  );
+  const road = flowSegmentsToRoads([flow])[0];
+  assert.equal(road.drivable, true);
+  assert.equal(road.roadClass, 'Major road');
+});

src/layers/traffic/source.js

@@ -1,142 +1,374 @@
-import { normalizeOverpassRoads } from '../../sources/overpassRoads.js';
-export { normalizeOverpassRoads } from '../../sources/overpassRoads.js';
+import {
+  createHybridFill,
+  flowSegmentsToRoads,
+  resolveRoadMode,
+  ROAD_SOURCE_LABELS,
+} from './roadModes.js';
+import { phaseTiming } from '../../sources/phaseTiming.js';
 import { createFlowTileSource } from './flowSource.js';
-function buildOverpassQuery(
-  south,
-  west,
-  north,
-  east,
-  { majorOnly = false, timeoutSec = 25 } = {},
-) {
-  // Regex matches the OSM `highway` tag value against allowed road types
-  const regex = majorOnly
-    ? '^(motorway|trunk|primary|secondary)$'
-    : '^(motorway|trunk|primary|secondary|tertiary|residential|unclassified)$';
-  return `[out:json][timeout:${timeoutSec}];(way["highway"~"${regex}"](${south},${west},${north},${east}););out geom qt;`;
+import { tileToBBox, tilesForBounds } from '../../data/tomtomTiles.js';
+import { clipTileLine } from '../../sources/openFreeMap.js';
+import { createOpenFreeMapSource } from '../../sources/openFreeMap.js';
+import { validTileBounds } from '../../sources/vectorTiles.js';
+export { normalizeOverpassRoads } from '../../sources/overpassRoads.js';
+
+/** Shrink only the detail footprint, centered on the look-at fetch box, to fit 16 tiles. */
+export function trafficDetailBounds(box) {
+  const center = {
+    lat: (box.north + box.south) / 2,
+    lon: (box.east + box.west) / 2,
+  };
+  let detail = { ...box };
+  while (tilesForBounds(detail, 14, { maxTiles: 17 }).length > 16) {
+    detail = {
+      south: center.lat + (detail.south - center.lat) * 0.9,
+      north: center.lat + (detail.north - center.lat) * 0.9,
+      west: center.lon + (detail.west - center.lon) * 0.9,
+      east: center.lon + (detail.east - center.lon) * 0.9,
+    };
+  }
+  return detail;
 }
 
-/**
- * A road request upstream declined, carrying a line fit to show an operator.
- *
- * The status travels beside the message instead of only inside it, so a caller
- * can branch on the code without parsing English — the same shape
- * `LiveSourceError` uses in `src/sources/live/contract.js`.
- */
+/** Keep coarse roads only outside the detailed tile cores. */
+export function outsideDetailTiles(roads, tiles) {
+  return roads.flatMap((road) => {
+    let lines = [road.coordinates];
+    for (const tile of tiles) {
+      const box = tileToBBox(tile.z, tile.x, tile.y);
+      const regions = [
+        { west: -180, east: box.west, south: -85, north: 85 },
+        { west: box.east, east: 180, south: -85, north: 85 },
+        { west: box.west, east: box.east, south: -85, north: box.south },
+        { west: box.west, east: box.east, south: box.north, north: 85 },
+      ];
+      lines = lines.flatMap((line) =>
+        regions.flatMap((region) => clipTileLine(line, region)),
+      );
+    }
+    return lines.map((coordinates) => ({ ...road, coordinates }));
+  });
+}
+
+/** A classified road failure with a display-safe reason and machine-readable status. */
 export class RoadRequestError extends Error {
-  constructor(message, { status = null } = {}) {
-    super(message);
+  constructor(message, { status = null, cause } = {}) {
+    super(message, { cause });
     this.name = 'RoadRequestError';
     this.status = status;
   }
 }
 
-/**
- * Name an Overpass refusal in the words the traffic row will print.
- *
- * This layer has two upstreams — OpenStreetMap for road geometry and TomTom
- * for flow — and only one of them can be down at a time. A row that says
- * nothing more than "road data unavailable" sends the reader to check their
- * TomTom key, which is the wrong half of the layer and costs them the
- * afternoon. So the status upstream actually returned is reported: 406 from a
- * public mirror is not a configuration problem the reader can fix, and saying
- * so is the difference between a dead end and a next step.
- *
- * The first two lines match `alpr`'s Overpass source word for word; this is
- * the same vocabulary, not a new one. What the status adds is *which* upstream
- * and *how* it declined — the part a single-source layer never needs to say.
- *
- * Only what the browser can see is claimed. The proxy rotates mirrors behind
- * `/api/overpass`, so a refusal arriving here means the proxy had nothing
- * better to offer; how many mirrors it tried is not something this side knows,
- * and the message does not pretend otherwise.
- * @param {number} status - HTTP status the proxy returned; a code that is
- *   not a finite number is treated as absent rather than printed.
- * @returns {RoadRequestError}
- */
-export function roadRequestError(status) {
+/** Name the road upstream without exposing raw transport errors or missing codes. */
+export function roadRequestError(status, cause) {
   const code = Number.isFinite(status) ? status : null;
   const message =
     code === 429
-      ? 'Overpass rate-limited'
-      : code === 504
-        ? 'Overpass timed out'
-        : // Our own proxy answers these, not a mirror: 502 when every mirror
-          // failed at the network level, 503 from its local concurrency
-          // limiter before any mirror was asked. Neither is a refusal.
-          code === 502
-          ? 'Overpass mirrors unreachable'
-          : code === 503
-            ? 'Overpass temporarily unavailable'
-            : // A source is injected, so a caller's adapter may hand back a
-              // refusal with no status on it. "HTTP undefined" on a panel row is
-              // worse than not naming a number, so an unreadable code falls back
-              // to what `alpr` says when it cannot be more specific either.
-              code === null
-              ? 'Overpass temporarily unavailable'
-              : `Overpass refused the road query (HTTP ${code})`;
-  return new RoadRequestError(message, { status: code });
+      ? 'OpenFreeMap tiles rate-limited'
+      : code === 504 || cause?.name === 'TimeoutError'
+        ? 'OpenFreeMap tiles timed out'
+        : code === null
+          ? 'OpenFreeMap tiles unavailable'
+          : `OpenFreeMap tiles unavailable (HTTP ${code})`;
+  return Object.assign(new RoadRequestError(message, { status: code, cause }), {
+    retryable: cause?.retryable !== false,
+    code: cause?.code,
+  });
 }
 
-/** Supply road responses, flow availability and one decoded flow cache. */
+/** Supply tile-derived road geometry and flow availability without Overpass queries. */
 export function createTrafficSource({
   fetchImpl = (...args) => globalThis.fetch(...args),
+  tileFetchImpl = (...args) => globalThis.fetch(...args),
+  mapTiles = createOpenFreeMapSource({ fetchImpl: tileFetchImpl }),
 } = {}) {
   const flow = createFlowTileSource({ fetchImpl });
-  return {
+  const api = {
     ...flow,
-    async requestRoads(
-      { south, west, north, east },
-      { majorOnly = false, timeoutSec = 25, signal } = {},
+    prefetch: () => mapTiles.getMetadata().catch(() => {}),
+    resetFlowTileCache() {
+      flow.resetFlowTileCache();
+      mapTiles.clear();
+    },
+    async requestOsmRoads(
+      box,
+      { majorOnly = false, signal, onTile, coverage = box.coverage } = {},
     ) {
       if (
-        ![south, west, north, east].every(Number.isFinite) ||
-        south < -90 ||
-        north > 90 ||
-        west < -180 ||
-        east > 180 ||
-        north <= south ||
-        east <= west ||
-        north - south > 10 ||
-        east - west > 10 ||
-        !Number.isInteger(timeoutSec) ||
-        timeoutSec < 1 ||
-        timeoutSec > 30
+        !validTileBounds(box) ||
+        box.north - box.south > 10 ||
+        box.east - box.west > 10
       )
-        throw new TypeError('A bounded road viewport and timeout are required');
-      signal?.throwIfAborted();
-      const query = buildOverpassQuery(south, west, north, east, {
-        majorOnly,
-        timeoutSec,
-      });
-      const response = await fetchImpl('/api/overpass', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: 'data=' + encodeURIComponent(query),
-        signal,
+        throw new TypeError('A bounded road viewport is required');
+      if (coverage) {
+        try {
+          const tileSnapshot = (tile) =>
+            onTile?.({
+              roads: tile.roads,
+              roadSource: 'OpenStreetMap',
+              roadMode: 'osm',
+            });
+          // Start nearest detail tiles before the coarse pass consumes workers.
+          const detailJob =
+            !majorOnly && coverage.detail.length
+              ? mapTiles
+                  .fetchBounds(box, {
+                    zoom: 14,
+                    tiles: coverage.detail,
+                    signal,
+                    onTile: onTile ? tileSnapshot : undefined,
+                  })
+                  .catch((error) => {
+                    signal?.throwIfAborted();
+                    if (
+                      error?.name === 'AbortError' ||
+                      error?.retryable === false
+                    )
+                      throw error;
+                    return { tiles: [], loadedTiles: [], partial: true };
+                  })
+              : null;
+          const coarseJob = mapTiles.fetchBounds(box, {
+            zoom: 12,
+            tiles: coverage.coarse,
+            signal,
+            onTile: majorOnly && onTile ? tileSnapshot : undefined,
+          });
+          const [detail, coarse] = await Promise.all([detailJob, coarseJob]);
+          signal?.throwIfAborted();
+          let roads = coarse.tiles.flatMap((tile) => tile.roads),
+            partial = coarse.partial;
+          if (detail) {
+            roads = [
+              ...detail.tiles.flatMap((tile) => tile.roads),
+              ...outsideDetailTiles(
+                roads,
+                detail.loadedTiles || (detail.partial ? [] : coverage.detail),
+              ),
+            ];
+            partial ||= detail.partial;
+          }
+          const data = {
+            roads,
+            roadSource: 'OpenStreetMap',
+            roadMode: 'osm',
+            partial,
+            detailLimited: false,
+            replace: true,
+          };
+          if (!majorOnly) onTile?.(data);
+          return {
+            ok: true,
+            status: 200,
+            headers: new Headers(),
+            json: async () => data,
+          };
+        } catch (error) {
+          signal?.throwIfAborted();
+          if (error?.name === 'AbortError') throw error;
+          throw roadRequestError(error?.status, error);
+        }
+      }
+      const area = majorOnly ? box : trafficDetailBounds(box);
+      const snapshot = (tiles, partial = false) => ({
+        roads: tiles
+          .flatMap((tile) => tile.roads)
+          .flatMap((road) =>
+            clipTileLine(road.coordinates, area).map((coordinates) => ({
+              ...road,
+              coordinates,
+            })),
+          ),
+        roadSource: 'OpenStreetMap',
+        roadMode: 'osm',
+        partial,
+        detailLimited:
+          !majorOnly && (area.north !== box.north || area.east !== box.east),
+        detailBounds: majorOnly ? null : area,
       });
+      let result;
+      try {
+        result = await mapTiles.fetchBounds(area, {
+          zoom: majorOnly ? 12 : 14,
+          signal,
+          onTile: onTile ? (tile) => onTile(snapshot([tile])) : undefined,
+        });
+      } catch (error) {
+        signal?.throwIfAborted();
+        if (error?.name === 'AbortError') throw error;
+        throw roadRequestError(error?.status, error);
+      }
+      const data = snapshot(result.tiles, result.partial);
       signal?.throwIfAborted();
       return {
-        ok: response.ok,
-        status: response.status,
-        headers: response.headers,
+        ok: true,
+        status: 200,
+        headers: new Headers(),
         async json() {
-          const body = await response.json();
-          signal?.throwIfAborted();
-          if (!Array.isArray(body?.elements))
-            throw new Error('Malformed road snapshot');
-          return { roads: normalizeOverpassRoads(body) };
+          return data;
         },
       };
     },
     async getStatus({ signal } = {}) {
-      signal?.throwIfAborted();
-      const response = await fetchImpl('/api/tomtom/status', { signal });
-      if (!response.ok) throw new Error('HTTP ' + response.status);
+      const start = performance.now();
+      const timeout = AbortSignal.timeout(8000);
+      const response = await fetchImpl('/api/tomtom/status', {
+        signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+      });
+      if (!response.ok)
+        throw Object.assign(new Error('TomTom status unavailable'), {
+          status: Number.isFinite(response.status) ? response.status : null,
+        });
       const status = await response.json();
       signal?.throwIfAborted();
       if (typeof status?.hasKey !== 'boolean')
         throw new Error('Malformed traffic status');
+      phaseTiming('status', start);
       return status;
     },
   };
+  /**
+   * Request roads for the selected road source.
+   *
+   * `osm` streams OpenFreeMap tiles exactly as before. `tomtom` and `hybrid`
+   * wait for the flow snapshot the layer started alongside road acquisition;
+   * OpenFreeMap tiles stream meanwhile (Hybrid) and are drawn unfiltered until
+   * flow arrives, then one replacing snapshot swaps in TomTom lines and drops
+   * the duplicated OpenFreeMap stretches. Later tiles publish only their own
+   * fill, so parsing stays incremental. TomTom never requests OpenFreeMap
+   * unless the missing key forces the OpenStreetMap fallback.
+   *
+   * @param {{south:number, west:number, north:number, east:number}} box
+   * @param {Object} [options]
+   * @param {'tomtom'|'osm'|'hybrid'|null} [options.roadMode] - Requested mode (null = default).
+   * @param {Promise<{segments:Array, hasKey:boolean, error?:string, partial?:boolean}>} [options.flowSnapshot]
+   * @param {() => boolean} [options.liveModeHint] - Key state if the snapshot misses the pass deadline.
+   * @param {number} [options.timeoutSec=20] - Pass deadline, also bounding the snapshot wait.
+   * @param {(data:Object) => void} [options.onTile] - Incremental snapshots; `replace` resets.
+   */
+  api.requestRoads = async (
+    box,
+    {
+      roadMode = null,
+      flowSnapshot,
+      liveModeHint = () => false,
+      onTile,
+      ...options
+    } = {},
+  ) => {
+    if (
+      !validTileBounds(box) ||
+      box.north - box.south > 10 ||
+      box.east - box.west > 10
+    )
+      throw new TypeError('A bounded road viewport is required');
+    if (roadMode === 'osm' || !flowSnapshot)
+      return api.requestOsmRoads(box, { ...options, onTile });
+    const signal = options.signal;
+    const osm = [];
+    let live = null,
+      mode = null,
+      metadata = {},
+      osmError = null,
+      tomtom = [],
+      fillFor = null;
+    const fillMemo = new Map();
+    const fill = (roads) =>
+      mode === 'hybrid'
+        ? roads.flatMap((road) => {
+            if (!fillMemo.has(road)) fillMemo.set(road, fillFor(road));
+            return fillMemo.get(road);
+          })
+        : roads;
+    // Hybrid without any TomTom line (flow failed, or none here) draws only
+    // OpenStreetMap roads, and says so.
+    const source = () =>
+      !mode || (mode === 'hybrid' && !tomtom.length)
+        ? ROAD_SOURCE_LABELS.osm
+        : ROAD_SOURCE_LABELS[mode];
+    const snapshot = (roads, replace) => ({
+      ...metadata,
+      roads,
+      roadSource: source(),
+      roadMode: mode,
+      replace,
+      partial: Boolean(metadata.partial || osmError || live?.partial),
+      roadWarning: osmError && mode !== 'osm' ? osmError.message : null,
+    });
+    const publish = (roads, replace = false) => {
+      if (!signal?.aborted) onTile?.(snapshot(roads, replace));
+    };
+    const composed = () =>
+      mode === 'tomtom' ? tomtom : [...tomtom, ...fill(osm)];
+    const loadOsm = async () => {
+      try {
+        const response = await api.requestOsmRoads(box, {
+          ...options,
+          onTile: (data) => {
+            if (data.replace) osm.splice(0, osm.length, ...data.roads);
+            else osm.push(...data.roads);
+            metadata = { ...data, roads: undefined };
+            // Before flow settles the tile is drawn as plain OpenStreetMap.
+            publish(
+              data.replace ? composed() : fill(data.roads),
+              Boolean(data.replace),
+            );
+          },
+        });
+        const data = await response.json();
+        metadata = { ...data, roads: undefined };
+        // Every tile streams through onTile; adopt the final list if not.
+        if (osm.length !== data.roads.length)
+          osm.splice(0, osm.length, ...data.roads);
+      } catch (error) {
+        if (error?.name === 'AbortError' || signal?.aborted) throw error;
+        osmError = error;
+      }
+    };
+    const osmJob = roadMode === 'tomtom' ? null : loadOsm();
+    osmJob?.catch(() => {});
+    // The snapshot waits on the status probe and flow tiles; never let it
+    // hold the road pass past its own deadline. A late snapshot counts as a
+    // flow failure: TomTom mode reports it, Hybrid falls back to OSM roads.
+    let deadline;
+    live = await Promise.race([
+      flowSnapshot,
+      new Promise((resolve) => {
+        deadline = setTimeout(
+          () =>
+            resolve({
+              segments: [],
+              hasKey: Boolean(liveModeHint()),
+              error: 'TomTom flow timed out',
+            }),
+          (options.timeoutSec ?? 20) * 1000,
+        );
+      }),
+    ]).finally(() => clearTimeout(deadline));
+    signal?.throwIfAborted();
+    if (!live)
+      throw new TypeError(
+        'Road selection requires a flow availability snapshot',
+      );
+    mode = resolveRoadMode(roadMode, live.hasKey);
+    if (mode === 'tomtom' && live.error) throw new RoadRequestError(live.error);
+    if (mode !== 'osm') {
+      tomtom = flowSegmentsToRoads(live.segments);
+      fillFor = createHybridFill(live.segments);
+      publish(composed(), true);
+    }
+    if (osmJob) await osmJob;
+    else if (mode === 'osm') await loadOsm();
+    signal?.throwIfAborted();
+    if (osmError && (mode === 'osm' || !tomtom.length)) throw osmError;
+    const data = snapshot(composed(), true);
+    publish(data.roads, true);
+    return {
+      ok: true,
+      status: 200,
+      headers: new Headers(),
+      json: async () => data,
+    };
+  };
+  return api;
 }

src/layers/traffic/source.test.mjs

@@ -1,10 +1,14 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { readFileSync } from 'node:fs';
+import { tilesForBounds, tileToBBox } from '../../data/tomtomTiles.js';
+import { decodeFlowTile } from './flowDecode.js';
+import { decodeOpenFreeMapTile } from '../../sources/openFreeMap.js';
 import {
   RoadRequestError,
-  createTrafficSource,
   roadRequestError,
+  trafficDetailBounds,
+  createTrafficSource,
 } from './source.js';
 import { clampBoundsAroundCenter } from '../../data/trafficBounds.js';
 const bounds = { south: 30.267, west: -97.744, north: 30.268, east: -97.743 };
@@ -46,6 +50,7 @@ test('a cancelled flow body cannot refill its source cache', async () => {
   const source = createTrafficSource({
     fetchImpl: async () => ({
       ok: true,
+      headers: new Headers(),
       arrayBuffer: async () => {
         calls++;
         if (calls === 1) controller.abort();
@@ -64,55 +69,36 @@ test('a cancelled flow body cannot refill its source cache', async () => {
     'cancelled bytes were not admitted to the decode cache',
   );
 });
-test('road requests have finite bounds and retain the two-pass query', async () => {
+test('road requests validate bounds and select z12/z14 immutable tile passes', async () => {
   const calls = [];
   const source = createTrafficSource({
-    fetchImpl: async (...args) => {
-      calls.push(args);
-      return new Response('{"elements":[]}');
+    mapTiles: {
+      async fetchBounds(box, options) {
+        calls.push({ box, ...options });
+        return { tiles: [{ roads: [] }], partial: false };
+      },
+      clear() {},
     },
   });
   await assert.rejects(
     source.requestRoads({ ...bounds, north: Infinity }),
     /bounded road viewport/,
   );
-  await assert.rejects(
-    source.requestRoads(bounds, { timeoutSec: '25];out;' }),
-    /bounded road viewport/,
-  );
   assert.equal(calls.length, 0);
-  await source.requestRoads(bounds, { majorOnly: true, timeoutSec: 8 });
-  assert.equal(calls[0][0], '/api/overpass');
-  const query = new URLSearchParams(calls[0][1].body).get('data');
-  assert.match(query, /\[timeout:8\]/);
-  assert.doesNotMatch(query, /residential/);
+  await source.requestRoads(bounds, { majorOnly: true });
   await source.requestRoads(bounds);
-  assert.match(
-    new URLSearchParams(calls[1][1].body).get('data'),
-    /residential/,
+  assert.deepEqual(
+    calls.map((c) => c.zoom),
+    [12, 14],
   );
-});
-test('antimeridian clamps produce road bounds accepted on either side', async () => {
-  const calls = [];
-  const source = createTrafficSource({
-    fetchImpl: async (...args) => {
-      calls.push(args);
-      return new Response('{"elements":[]}');
-    },
-  });
   for (const centerLon of [179.99, -179.99]) {
     const clamped = clampBoundsAroundCenter(
-      {
-        south: -0.02,
-        north: 0.02,
-        west: 179.98,
-        east: -179.98,
-      },
+      { south: -0.02, north: 0.02, west: 179.98, east: -179.98 },
       { lat: 0, lon: centerLon },
     );
     await source.requestRoads(clamped);
   }
-  assert.equal(calls.length, 2);
+  assert.equal(calls.length, 4);
 });
 test('malformed availability is an unavailable source rather than a keyless response', async () => {
   const source = createTrafficSource({
@@ -136,91 +122,516 @@ test('traffic construction is inert and parameters belong to each layer', async
   assert.equal(b.getParams().uncoveredRoads, 'sim');
 });
 
-test('road body parsing retains the source request cancellation signal', async () => {
-  const controller = new AbortController();
+test('road tile replies respect cancellation even when the tile source ignores it', async () => {
+  const abort = new AbortController();
   const source = createTrafficSource({
-    fetchImpl: async () => ({
-      ok: true,
-      status: 200,
-      headers: new Headers(),
-      json: async () => {
-        controller.abort();
-        return { elements: [] };
+    mapTiles: {
+      async fetchBounds() {
+        abort.abort();
+        return { tiles: [{ roads: [] }], partial: false };
       },
-    }),
+    },
   });
-  const response = await source.requestRoads(bounds, {
-    signal: controller.signal,
+  await assert.rejects(source.requestRoads(bounds, { signal: abort.signal }), {
+    name: 'AbortError',
   });
-  await assert.rejects(response.json(), { name: 'AbortError' });
 });
 
-test('road sources decode direction and coordinates before scene construction', async () => {
-  const geometry = [
-    { lat: 30, lon: -97 },
-    { lat: 30.001, lon: -97.001 },
-  ];
+test('keyed and keyless geometry is identical OpenFreeMap data, independent of TomTom failures', async () => {
+  const tile = decodeOpenFreeMapTile(
+    readFileSync(
+      new URL(
+        '../../data/fixtures/ofm-austin-14-3743-6745.pbf',
+        import.meta.url,
+      ),
+    ),
+    14,
+    3743,
+    6745,
+  );
+  const box = tileToBBox(14, 3743, 6745);
+  const calls = [];
   const source = createTrafficSource({
-    fetchImpl: async () =>
-      Response.json({
-        elements: [
-          { type: 'node', id: 1 },
-          { type: 'way', geometry, tags: { highway: 'primary', oneway: '-1' } },
-          { type: 'way', geometry, tags: { junction: 'roundabout' } },
-          { type: 'way', geometry: [geometry[0]] },
-        ],
-      }),
+    fetchImpl: async () => {
+      throw new Error('HTTP 429');
+    },
+    mapTiles: {
+      fetchBounds: async (_, options) => {
+        calls.push(options.zoom);
+        return { tiles: [tile], partial: false };
+      },
+    },
   });
-  assert.deepEqual(await (await source.requestRoads(bounds)).json(), {
+  const keyed = await (await source.requestRoads(box, { live: true })).json();
+  const keyless = await (
+    await source.requestRoads(box, { live: false })
+  ).json();
+  assert.deepEqual(keyed, keyless);
+  assert.equal(keyed.roadSource, 'OpenStreetMap');
+  assert.ok(keyed.roads.length > 0);
+  assert.ok(keyed.roads.every((road) => !road.flow));
+  assert.deepEqual(calls, [14, 14]);
+  await assert.rejects(source.fetchFlowForBounds(bounds), /HTTP 429/);
+  assert.deepEqual(await (await source.requestRoads(box)).json(), keyless);
+});
+
+test('traffic status is session-cached after settlement, but cancelled discovery can restart', async () => {
+  const { createFlow } = await import('./flow.js');
+  let calls = 0;
+  const state = {};
+  const flow = createFlow({
+    state,
+    services: { credits: { registerDynamicCredit() {} } },
+    parts: {},
+    source: {
+      async getStatus({ signal }) {
+        calls++;
+        signal?.throwIfAborted();
+        return { hasKey: false };
+      },
+    },
+  });
+  const first = new AbortController();
+  await flow.ensureFlowStatus(first.signal);
+  first.abort();
+  await flow.ensureFlowStatus(new AbortController().signal);
+  assert.equal(calls, 1);
+  const retryState = {};
+  const retryFlow = createFlow({
+    state: retryState,
+    services: { credits: {} },
+    parts: {},
+    source: {
+      async getStatus({ signal }) {
+        calls++;
+        signal.throwIfAborted();
+        return { hasKey: false };
+      },
+    },
+  });
+  await assert.rejects(retryFlow.ensureFlowStatus(first.signal), {
+    name: 'AbortError',
+  });
+  await retryFlow.ensureFlowStatus(new AbortController().signal);
+  assert.equal(calls, 3);
+});
+
+test('road parsing defers surface reads to the cancellable preparation pass', async () => {
+  const { createModel } = await import('./model.js');
+  let lookups = 0;
+  const model = createModel({
+    state: {
+      _viewer: {
+        scene: {
+          sampleHeightSupported: true,
+          sampleHeight() {
+            assert.fail('offscreen 3D height probe on keyless globe');
+          },
+          globe: {
+            show: true,
+            getHeight() {
+              lookups++;
+              return 0;
+            },
+          },
+        },
+      },
+    },
+    services: {},
+    parts: {},
+    source: {},
+  });
+  const roads = model.parseRoads({
     roads: [
       {
         coordinates: [
-          [-97, 30],
-          [-97.001, 30.001],
+          [-97.74, 30.27],
+          [-97.741, 30.271],
         ],
-        type: 'primary',
-        oneway: -1,
-      },
-      {
-        coordinates: [
-          [-97, 30],
-          [-97.001, 30.001],
-        ],
-        type: 'unclassified',
-        oneway: 1,
+        type: 'residential',
+        oneway: 0,
       },
     ],
   });
+  assert.equal(roads.length, 2);
+  assert.deepEqual(
+    roads.map((r) => r.oneway),
+    [1, -1],
+  );
+  assert.equal(roads[0].waypoints.length, 2);
+  assert.equal(lookups, 0);
 });
 
-test('an Overpass refusal is named by status, and keeps the status beside the words', () => {
-  // The panel prints this string verbatim, so the mapping is part of the
-  // layer's contract with the reader, not an implementation detail.
-  assert.equal(roadRequestError(429).message, 'Overpass rate-limited');
-  assert.equal(roadRequestError(504).message, 'Overpass timed out');
+test('parsed road cache evicts old views by byte budget and never retains partial snapshots', async () => {
+  const { cacheRoadSnapshot } = await import('./ingestion.js');
+  const entries = new Map();
+  const entry = () => ({
+    major: [
+      {
+        coords: [
+          [1, 2],
+          [3, 4],
+        ],
+      },
+    ],
+    full: null,
+  });
+  const first = entry();
+  cacheRoadSnapshot(entries, 'old', first);
+  cacheRoadSnapshot(entries, 'new', entry(), {
+    maxBytes: first.cacheBytes + 1,
+  });
+  assert.deepEqual([...entries.keys()], ['new']);
+  cacheRoadSnapshot(entries, 'new', entry(), { retain: false });
+  assert.equal(entries.size, 0);
+  cacheRoadSnapshot(entries, 'oversized', entry(), { maxBytes: 1 });
+  assert.equal(entries.size, 0);
+});
+
+for (const lat of [51.5, 60])
+  test(`z14 detail at ${lat} stays centered within the sixteen-tile cap`, async () => {
+    const box = {
+      south: lat - 0.025,
+      north: lat + 0.025,
+      west: -0.155,
+      east: -0.105,
+    };
+    assert.ok(tilesForBounds(box, 14).length > 16);
+    const detail = trafficDetailBounds(box);
+    assert.ok(tilesForBounds(detail, 14).length <= 16);
+    assert.ok(Math.abs((detail.south + detail.north) / 2 - lat) < 1e-10);
+    const source = createTrafficSource({
+      mapTiles: { fetchBounds: async () => ({ tiles: [], partial: false }) },
+    });
+    const data = await (await source.requestRoads(box)).json();
+    assert.equal(data.detailLimited, true);
+    assert.deepEqual(data.detailBounds, detail);
+  });
+test('TomTom buffers are clipped before caching and preserve direction and flow attributes', async () => {
+  const core = tileToBBox(12, 935, 1686);
+  const source = createTrafficSource({
+    fetchImpl: async () => new Response(fixture),
+  });
+  const result = await source.fetchFlowForBounds({
+    ...core,
+    east: core.east - 1e-9,
+    south: core.south + 1e-9,
+  });
+  const decoded = decodeFlowTile(fixture, 12, 935, 1686);
+  assert.ok(
+    decoded.some((r) =>
+      r.coords.some(
+        ([x, y]) =>
+          x < core.west || x > core.east || y < core.south || y > core.north,
+      ),
+    ),
+  );
+  assert.ok(
+    result.every((r) =>
+      r.coords.every(
+        ([x, y]) =>
+          x >= core.west - 1e-10 &&
+          x <= core.east + 1e-10 &&
+          y >= core.south - 1e-10 &&
+          y <= core.north + 1e-10,
+      ),
+    ),
+  );
+  assert.ok(result.some((r) => r.closure));
+});
+
+test('a failed detail pass keeps major roads and exposes separate degraded status', async () => {
+  const { createIngestion } = await import('./ingestion.js');
+  for (const retained of [false, true]) {
+    const state = {
+      _loadGeneration: 0,
+      _tileCache: new Map(),
+      _enabled: true,
+      _parseRoads: (data) => data.roads,
+    };
+    let paints = 0;
+    const ingestion = createIngestion({
+      state,
+      services: {},
+      parts: {
+        viewport: {
+          clampBounds: (b) => b,
+          getBoundsCenter: (b) => ({
+            lat: (b.north + b.south) / 2,
+            lon: (b.east + b.west) / 2,
+          }),
+        },
+        flow: {
+          warmFlow: async () => {},
+          applyFlowThenRender: async () => {
+            paints++;
+            if (paints === 1) state._retainedPreview = retained;
+            return true;
+          },
+        },
+      },
+      source: {
+        requestRoads: async (_, opts) => {
+          if (!opts.majorOnly) throw new Error('tile request failed');
+          return {
+            ok: true,
+            json: async () => ({
+              roads: [],
+              roadSource: 'OpenStreetMap tiles',
+              partial: false,
+            }),
+          };
+        },
+      },
+    });
+    await ingestion.loadRoadsForBounds(bounds, 350);
+    assert.equal(
+      paints,
+      retained ? 2 : 1,
+      'only an unpainted retained preview needs fallback work',
+    );
+    assert.equal(state._roadError, null);
+    assert.equal(
+      state._detailError,
+      'Detailed roads unavailable — OpenFreeMap tiles unavailable',
+    );
+    assert.equal(state._roadPartial, true);
+    assert.equal(state._fetching, false);
+    clearTimeout(state._retryTimer);
+  }
+});
+
+const ofmDetail = decodeOpenFreeMapTile(
+  readFileSync(
+    new URL('../../data/fixtures/ofm-austin-14-3743-6745.pbf', import.meta.url),
+  ),
+  14,
+  3743,
+  6745,
+);
+
+async function matchingContext(fetchFlowForBounds) {
+  const { createState } = await import('./state.js');
+  const { createModel } = await import('./model.js');
+  const { createFlow } = await import('./flow.js');
+  const { createControls } = await import('./controls.js');
+  const state = createState({ services: {} });
+  Object.assign(state, {
+    _liveMode: true,
+    _enabled: true,
+    _flowStatusPromise: Promise.resolve(),
+  });
+  const source = {
+    fetchFlowForBounds,
+    getFlowSessionStats: () => ({ tilesFetched: 1 }),
+  };
+  const parts = {
+    style: {
+      presetProfileActive: () => false,
+      jamDensityOn: () => false,
+      baseDotSize: () => 2,
+      activeSizeDelta: () => 0,
+    },
+    rendering: {
+      rebuildHeatLines() {},
+      visibleRoadsForAltitude: (roads) => roads,
+    },
+  };
+  const context = { state, source, parts, services: { credits: {} } };
+  parts.model = createModel(context);
+  return {
+    state,
+    model: parts.model,
+    flow: createFlow(context),
+    controls: createControls(context).methods,
+  };
+}
+
+test('Austin TomTom fixture matches congestion onto OFM detail roads without changing geometry', async () => {
+  const source = createTrafficSource({
+    fetchImpl: async () => new Response(fixture),
+  });
+  const context = await matchingContext(source.fetchFlowForBounds);
+  const roads = context.model.parseRoads({ roads: ofmDetail.roads });
+  const coordinates = structuredClone(roads.map((r) => r.coords));
+  await context.flow.applyFlowToRoads(roads, tileToBBox(14, 3743, 6745), 0);
+  const matched = roads.filter((r) => r.flow);
+  assert.ok(matched.length > 0);
+  assert.ok(roads.length >= 94);
+  assert.ok(roads.every((r) => [1, -1].includes(r.oneway)));
+  assert.ok(matched.some((r) => r.flow.level < 0.8 && r.flow.level > 0));
+  assert.deepEqual(
+    roads.map((r) => r.coords),
+    coordinates,
+    'flow never substitutes its own polylines',
+  );
+  assert.equal(context.state._flowPending, 0);
+
+  // Inject closure attributes on the same checked-in TomTom geometry: the
+  // Austin detail snapshot has no real closures on its matched roads.
+  const segments = await source.fetchFlowForBounds(tileToBBox(14, 3743, 6745));
+  const closed = await matchingContext(async () =>
+    segments.map((s) => ({ ...s, closure: true })),
+  );
+  await closed.flow.applyFlowToRoads(roads, bounds, 0);
+  assert.equal(roads.filter((r) => r.flow?.closure).length, matched.length);
+  assert.ok(
+    roads
+      .filter((r) => r.flow)
+      .every((r) => closed.model.computeDotCount(r, 350) === 0),
+  );
+});
+
+test('late closures hide and stop dots; coverage counts shown matched dots, and reopening restores them', async () => {
+  const C = await import('cesium');
+  const { state, model, controls } = await matchingContext(async () => []);
+  const matched = { flow: { level: 1, closure: false }, type: 'primary' };
+  const sim = { flow: null, type: 'residential' };
+  const closed = { flow: { level: 0, closure: true }, type: 'primary' };
+  state._roads = [matched, sim, closed];
+  state._dots = [matched, matched, matched, sim, closed].map((road) => ({
+    road,
+    baseMps: 10,
+    mps: 10,
+    point: { show: true, color: C.Color.WHITE },
+  }));
+  model.recolorDotsInPlace('fixture');
+  assert.equal(state._dots[4].point.show, false);
+  assert.equal(state._dots[4].mps, 0);
+  assert.equal(controls.getStats().count, 4);
+  assert.equal(controls.getStats().flowCoveragePct, 75);
+  assert.equal(
+    state._dots[3].mps,
+    10,
+    'unmatched roads retain simulated speed',
+  );
+  assert.equal(state._dots[3].bucket, null);
+  closed.flow = { level: 1, closure: false };
+  model.recolorDotsInPlace('reopened');
+  assert.equal(state._dots[4].point.show, true);
+  assert.equal(state._dots[4].mps, 10);
+  assert.equal(controls.getStats().count, 5);
+  assert.equal(controls.getStats().flowCoveragePct, 80);
+});
+
+test('refresh failure removes cached matches and reports simulated flow', async () => {
+  const { flow, state, model, controls } = await matchingContext(async () => {
+    throw new Error('HTTP 429');
+  });
+  const roads = model.parseRoads({ roads: ofmDetail.roads });
+  roads[0].flow = { level: 0.1, closure: true };
+  await flow.applyFlowToRoads(roads, bounds, 0);
+  assert.ok(roads.every((r) => r.flow === null));
+  assert.equal(controls.getStats().flowCoveragePct, 0);
+  assert.match(
+    controls.getStats().loadingLabel,
+    /SIMULATED — TomTom daily budget reached/,
+  );
+  assert.equal(state._flowPending, 0);
+});
+
+test('superseded flow cannot apply matches after a camera move or disable', async () => {
+  let finish;
+  const { flow, state, model } = await matchingContext(
+    () =>
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+  );
+  const roads = model.parseRoads({ roads: ofmDetail.roads });
+  const pending = flow.applyFlowToRoads(roads, bounds, 0);
+  while (!finish) await new Promise((resolve) => setTimeout(resolve, 0));
+  state._loadGeneration++;
+  state._flowPending = 0;
+  state._enabled = false;
+  finish(decodeFlowTile(fixture, 12, 935, 1686));
+  await pending;
+  assert.ok(roads.every((r) => r.flow === null));
+  assert.equal(state._flowPending, 0);
+});
+
+test('OSM keyed loads run z12 then z14 and reuse road snapshots while refreshing flow', async () => {
+  const { createIngestion } = await import('./ingestion.js');
+  const state = {
+    _loadGeneration: 0,
+    _tileCache: new Map(),
+    _enabled: true,
+    _liveMode: true,
+    _roadMode: 'osm',
+    _parseRoads: (data) => data.roads,
+  };
+  const passes = [],
+    paints = [];
+  const ingestion = createIngestion({
+    state,
+    services: {},
+    parts: {
+      viewport: {
+        clampBounds: (b) => b,
+        getBoundsCenter: () => ({ lat: 30.267, lon: -97.744 }),
+      },
+      flow: {
+        warmFlow: async () => {},
+        applyFlowThenRender: async (roads) => {
+          paints.push(roads);
+          return true;
+        },
+      },
+    },
+    source: {
+      requestRoads: async (_, options) => {
+        passes.push(options.majorOnly);
+        return {
+          ok: true,
+          json: async () => ({
+            roads: ofmDetail.roads,
+            roadSource: 'OpenStreetMap',
+            roadMode: 'osm',
+          }),
+        };
+      },
+    },
+  });
+  await ingestion.loadRoadsForBounds(bounds, 350);
+  assert.deepEqual(passes, [true, false]);
+  await ingestion.loadRoadsForBounds(bounds, 350);
+  assert.deepEqual(
+    passes,
+    [true, false],
+    'repeat view does not fetch road geometry',
+  );
+  assert.equal(
+    paints.length,
+    3,
+    'cached roads still pass through flow refresh',
+  );
+});
+
+test('an OpenFreeMap refusal is named by status, and keeps the status beside the words', () => {
+  assert.equal(roadRequestError(429).message, 'OpenFreeMap tiles rate-limited');
+  assert.equal(roadRequestError(504).message, 'OpenFreeMap tiles timed out');
   assert.equal(
     roadRequestError(406).message,
-    'Overpass refused the road query (HTTP 406)',
+    'OpenFreeMap tiles unavailable (HTTP 406)',
   );
   assert.equal(
     roadRequestError(500).message,
-    'Overpass refused the road query (HTTP 500)',
+    'OpenFreeMap tiles unavailable (HTTP 500)',
   );
 
-  // 502 and 503 come from the local proxy (mirrors unreachable, local
-  // limiter busy), so they must not read as a mirror refusing the query.
-  assert.equal(roadRequestError(502).message, 'Overpass mirrors unreachable');
+  assert.equal(
+    roadRequestError(502).message,
+    'OpenFreeMap tiles unavailable (HTTP 502)',
+  );
   assert.equal(
     roadRequestError(503).message,
-    'Overpass temporarily unavailable',
+    'OpenFreeMap tiles unavailable (HTTP 503)',
   );
   assert.equal(roadRequestError(503).status, 503);
 
-  // An injected source may refuse without a readable code; a row must never
-  // print "HTTP undefined" at a reader.
   for (const missing of [undefined, null, NaN, 'four-oh-six']) {
     const vague = roadRequestError(missing);
-    assert.equal(vague.message, 'Overpass temporarily unavailable');
+    assert.equal(vague.message, 'OpenFreeMap tiles unavailable');
     assert.equal(vague.status, null, 'an unreadable code is absent, not zero');
   }
 
@@ -234,3 +645,225 @@ test('an Overpass refusal is named by status, and keeps the status beside the wo
     'a caller must be able to branch on the code without parsing English',
   );
 });
+
+for (const phase of ['metadata', 'tile']) {
+  for (const failure of [406, 429, 503, 504, 'network', 'timeout']) {
+    test(`OpenFreeMap ${phase} ${failure} retains its reason through the road source`, async () => {
+      const source = createTrafficSource({
+        tileFetchImpl: async (url) => {
+          if (phase === 'tile' && url.endsWith('/planet'))
+            return Response.json({
+              tiles: ['https://tiles.openfreemap.org/test/{z}/{x}/{y}.pbf'],
+            });
+          if (failure === 'network') throw new TypeError('Failed to fetch');
+          if (failure === 'timeout')
+            throw new DOMException('deadline', 'TimeoutError');
+          return new Response('', { status: failure });
+        },
+      });
+      await assert.rejects(source.requestRoads(bounds), (error) => {
+        assert.ok(error instanceof RoadRequestError);
+        assert.equal(
+          error.status,
+          typeof failure === 'number' ? failure : null,
+        );
+        assert.equal(
+          error.message,
+          roadRequestError(
+            error.status,
+            failure === 'timeout' ? { name: 'TimeoutError' } : undefined,
+          ).message,
+        );
+        assert.equal(error.retryable, true);
+        return true;
+      });
+    });
+  }
+}
+
+test('permanent metadata failures remain non-retryable through the road error wrapper', async () => {
+  const source = createTrafficSource({
+    tileFetchImpl: async () => Response.json({}),
+  });
+  await assert.rejects(source.requestRoads(bounds), (error) => {
+    assert.ok(error instanceof RoadRequestError);
+    assert.equal(error.retryable, false);
+    assert.equal(error.status, null);
+    return true;
+  });
+});
+
+test('reticle road requests pass exact bounded tiles and retain distant coarse roads', async () => {
+  const requests = [];
+  const source = createTrafficSource({
+    mapTiles: {
+      clear() {},
+      getMetadata: async () => ({}),
+      async fetchBounds(box, options) {
+        requests.push(options);
+        return { tiles: [{ roads: [] }], partial: false };
+      },
+    },
+  });
+  const box = { south: 30.2, west: -97.8, north: 30.4, east: -97.6 };
+  const coverage = {
+    coarse: [{ z: 12, x: 935, y: 1685 }],
+    detail: [{ z: 14, x: 3743, y: 6745 }],
+  };
+  const result = await source.requestOsmRoads(box, { coverage });
+  assert.deepEqual(
+    requests.map((r) => r.tiles),
+    [coverage.detail, coverage.coarse],
+  );
+  assert.equal((await result.json()).partial, false);
+});
+
+test('footprint requests preserve HTTP failures and cancellation semantics', async () => {
+  const coverage = { coarse: [{ z: 12, x: 935, y: 1686 }], detail: [] };
+  const source = createTrafficSource({
+    mapTiles: {
+      clear() {},
+      fetchBounds: async () => {
+        throw Object.assign(new Error('limited'), { status: 429 });
+      },
+    },
+  });
+  await assert.rejects(
+    source.requestOsmRoads(bounds, { coverage }),
+    (error) => error instanceof RoadRequestError && error.status === 429,
+  );
+  const controller = new AbortController();
+  controller.abort();
+  await assert.rejects(
+    source.requestOsmRoads(bounds, { coverage, signal: controller.signal }),
+    { name: 'AbortError' },
+  );
+});
+
+test('near detail starts and streams while distant coarse tiles are still pending', async () => {
+  let releaseCoarse;
+  const coarse = new Promise((resolve) => {
+    releaseCoarse = resolve;
+  });
+  const order = [],
+    painted = [];
+  const source = createTrafficSource({
+    mapTiles: {
+      clear() {},
+      fetchBounds: async (box, options) => {
+        order.push(options.zoom);
+        if (options.zoom === 12) return coarse;
+        const tile = {
+          roads: [
+            {
+              coordinates: [
+                [-97.744, 30.267],
+                [-97.743, 30.268],
+              ],
+              type: 'primary',
+            },
+          ],
+        };
+        options.onTile?.(tile);
+        return { tiles: [tile], partial: false };
+      },
+    },
+  });
+  const pending = source.requestOsmRoads(bounds, {
+    coverage: {
+      detail: [{ z: 14, x: 3743, y: 6745 }],
+      coarse: [{ z: 12, x: 935, y: 1686 }],
+    },
+    onTile: (tile) => painted.push(tile),
+  });
+  await Promise.resolve();
+  assert.deepEqual(order, [14, 12]);
+  assert.equal(painted.length, 1);
+  assert.equal(painted[0].roads.length, 1);
+  releaseCoarse({ tiles: [], partial: false });
+  await pending;
+});
+
+test('failed detail cores retain real coarse roads while successful cores replace them', async () => {
+  const detail = [
+    { z: 14, x: 3743, y: 6745 },
+    { z: 14, x: 3744, y: 6745 },
+  ];
+  const roads = detail.map((tile, i) => {
+    const b = tileToBBox(tile.z, tile.x, tile.y);
+    return {
+      type: 'primary',
+      id: i,
+      coordinates: [
+        [b.west + 0.002, b.south + 0.002],
+        [b.east - 0.002, b.north - 0.002],
+      ],
+    };
+  });
+  for (const allFailed of [false, true]) {
+    const source = createTrafficSource({
+      mapTiles: {
+        async fetchBounds(box, { zoom }) {
+          if (zoom === 12) return { tiles: [{ roads }], partial: false };
+          if (allFailed) throw new Error('temporary tile failure');
+          return {
+            tiles: [{ roads: [] }],
+            loadedTiles: [detail[0]],
+            partial: true,
+          };
+        },
+      },
+    });
+    const snapshots = [];
+    const data = await (
+      await source.requestOsmRoads(bounds, {
+        coverage: { detail, coarse: [{ z: 12, x: 935, y: 1686 }] },
+        onTile: (value) => snapshots.push(value),
+      })
+    ).json();
+    assert.equal(data.partial, true);
+    assert.equal(data.replace, true);
+    assert.deepEqual(data.roads, allFailed ? roads : [roads[1]]);
+    assert.deepEqual(snapshots.at(-1).roads, data.roads);
+  }
+});
+
+test('traffic separates API and public tile transports, including the default tile fetch', async (t) => {
+  const publicUrls = [],
+    apiUrls = [];
+  const publicFetch = async (url) => {
+    publicUrls.push(url);
+    return url.endsWith('/planet')
+      ? Response.json({
+          tiles: ['https://tiles.openfreemap.org/test/{z}/{x}/{y}.pbf'],
+        })
+      : new Response(
+          readFileSync(
+            new URL(
+              '../../data/fixtures/ofm-austin-14-3743-6745.pbf',
+              import.meta.url,
+            ),
+          ),
+        );
+  };
+  t.mock.method(globalThis, 'fetch', publicFetch);
+  for (const tileFetchImpl of [undefined, publicFetch]) {
+    const source = createTrafficSource({
+      tileFetchImpl,
+      fetchImpl: async (url) => {
+        assert.ok(url.startsWith('/api/'));
+        apiUrls.push(url);
+        return url.endsWith('/status')
+          ? Response.json({ hasKey: true })
+          : new Response(fixture);
+      },
+    });
+    await source.getStatus();
+    await source.fetchFlowForBounds(bounds);
+    assert.ok(
+      (await (await source.requestOsmRoads(bounds)).json()).roads.length,
+    );
+  }
+  assert.ok(publicUrls.length >= 4);
+  assert.ok(apiUrls.length >= 4);
+});

src/layers/traffic/state.js

@@ -1,8 +1,17 @@
+import { normalizeRoadMode } from './roadModes.js';
 import * as Cesium from 'cesium';
 import { FLOW_BUCKET_COLORS, TRAFFIC_TIMING_ENABLED } from './policy.js';
 
 export function createState({ services }) {
   const layerState = {};
+  layerState._roadMode =
+    typeof location === 'undefined'
+      ? null
+      : normalizeRoadMode(
+          new URLSearchParams(location.search).get('trafficRoads'),
+        );
+  // The query override is consumed at construction and shields passive restoration.
+  layerState._roadModeUrlOverride = layerState._roadMode;
 
   // ─── Module State ──────────────────────────────────────────
   /** @type {Cesium.Viewer|null} */
@@ -16,6 +25,14 @@ export function createState({ services }) {
   /** @type {Array<{point:Cesium.PointPrimitive, waypoints:Cesium.Cartesian3[], segmentDist:number[], numSegments:number, segIdx:number, t:number, mps:number, direction:number, stoppedUntil:number}>} Active animated dots */
 
   layerState._dots = [];
+  layerState._nextDotId = 1;
+  layerState._motion = {
+    publishes: 0,
+    rebuilds: 0,
+    added: 0,
+    removed: 0,
+    recycled: 0,
+  };
 
   /** @type {Array<{coords:number[][], type:string, waypoints:Cesium.Cartesian3[], segmentDist:number[]}>} Parsed roads with pre-computed Cartesian3 waypoints */
 
@@ -42,7 +59,7 @@ export function createState({ services }) {
 
   layerState._lastBounds = null;
 
-  /** @type {boolean} True while an Overpass fetch is in flight */
+  /** @type {boolean} True while a road fetch is in flight */
 
   layerState._fetching = false;
 
@@ -142,9 +159,7 @@ export function createState({ services }) {
 
   /**
    * Congestion heat-lines are GroundPolylinePrimitive batches draped onto the
-   * rendered 3D tiles (ClassificationType.CESIUM_3D_TILE) — polylines at the
-   * dots' single-sample heights depth-fail under the mesh across an oblique
-   * city view (first A/B capture: 198 lines rendered, zero visible). One
+   * rendered 3D tiles (ClassificationType.CESIUM_3D_TILE). One
    * primitive per bucket so the jam batch can pulse via a single shared
    * material uniform.
    * @type {Cesium.GroundPolylinePrimitive|null}
@@ -212,6 +227,7 @@ export function createState({ services }) {
   /** @type {Promise<void>|null} Session-cached status check (one fetch per session) */
 
   layerState._flowStatusPromise = null;
+  layerState._flowStatusSignal = null;
 
   /** @type {ReturnType<typeof setInterval>|null} Enable-time retry until the first load commits. */
 
@@ -221,10 +237,13 @@ export function createState({ services }) {
   layerState._retryDelayMs = 1500;
   layerState._retryBoundsKey = null;
   layerState._roadError = null;
+  layerState._roadSource = 'OpenStreetMap';
+  layerState._roadPartial = false;
+  layerState._roadRetryStopped = false;
+  layerState._retryAttempts = 0;
 
-  /** @type {number} 0–100 int — matched roads / roads with any flow candidates */
-
-  layerState._flowCoveragePct = 0;
+  /** Parsed road set whose current flow request owns the feed status. */
+  layerState._flowRoads = null;
 
   /** @type {Function|null} Development-only camera moveEnd timing disposer. */
 

src/layers/traffic/streaming.test.mjs

@@ -0,0 +1,138 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createTrafficSource } from './source.js';
+import { createIngestion } from './ingestion.js';
+import { tileToBBox } from '../../data/tomtomTiles.js';
+
+for (const hasKey of [false, true])
+  for (const flowFirst of [false, true]) {
+    test(`${hasKey ? 'Hybrid' : 'keyless default'} source and ingestion replace snapshots with flow ${flowFirst ? 'before' : 'after'} tiles`, async () => {
+      const detail = { z: 14, x: 3743, y: 6745 };
+      const core = tileToBBox(detail.z, detail.x, detail.y);
+      const local = {
+        type: 'residential',
+        oneway: 1,
+        coordinates: [
+          [core.west + 0.002, core.south + 0.002],
+          [core.west + 0.004, core.south + 0.004],
+        ],
+      };
+      const distant = {
+        type: 'primary',
+        oneway: 1,
+        coordinates: [
+          [core.east + 0.01, core.south],
+          [core.east + 0.02, core.south],
+        ],
+      };
+      const flow = [
+        {
+          roadType: 'Major road',
+          trafficLevel: 0.5,
+          coords: [
+            [core.east + 0.01, core.north],
+            [core.east + 0.02, core.north],
+          ],
+        },
+      ];
+      const bounds = {
+        ...core,
+        east: core.east + 0.03,
+        coverage: {
+          detail: [detail],
+          coarse: [{ z: 12, x: 935, y: 1686 }],
+          key: 'test',
+        },
+      };
+      const source = createTrafficSource({
+        mapTiles: {
+          async fetchBounds(box, { zoom, onTile }) {
+            const tile = { roads: zoom === 14 ? [local] : [distant] };
+            onTile?.(tile);
+            return {
+              tiles: [tile],
+              loadedTiles: zoom === 14 ? [detail] : bounds.coverage.coarse,
+              partial: false,
+            };
+          },
+        },
+      });
+      const returned = [],
+        streams = [];
+      const requestRoads = source.requestRoads;
+      source.requestRoads = async (box, options) => {
+        let streamed = [];
+        const response = await requestRoads(box, {
+          ...options,
+          onTile(data) {
+            if (data.replace) streamed = data.roads.slice();
+            else streamed.push(...data.roads);
+            options.onTile(data);
+          },
+        });
+        const data = await response.json();
+        returned.push(data.roads);
+        streams.push(streamed);
+        return response;
+      };
+      const painted = [];
+      const state = {
+        _enabled: true,
+        _loadGeneration: 0,
+        _tileCache: new Map(),
+        _roadMode: hasKey ? 'hybrid' : null,
+        _liveMode: hasKey,
+        _parseRoads: (data) => data.roads,
+      };
+      const ingestion = createIngestion({
+        state,
+        source,
+        services: {},
+        parts: {
+          viewport: {
+            clampBounds: (b) => b,
+            getBoundsCenter: () => ({ lat: 30.26, lon: -97.74 }),
+          },
+          flow: {
+            warmFlow: () =>
+              flowFirst
+                ? Promise.resolve(hasKey ? flow : [])
+                : new Promise((resolve) =>
+                    setImmediate(() => resolve(hasKey ? flow : [])),
+                  ),
+            applyFlowThenRender: async (
+              roads,
+              box,
+              generation,
+              altitude,
+              label,
+            ) => {
+              if (label === 'Loaded full') painted.push(roads);
+              return true;
+            },
+          },
+        },
+      });
+      await ingestion.loadRoadsForBounds(bounds, 350);
+      assert.equal(returned.length, 2);
+      assert.deepEqual(
+        streams,
+        returned,
+        'each completed stream equals its authoritative graph',
+      );
+      assert.deepEqual(
+        painted.at(-1),
+        returned.at(-1),
+        'ingestion paints that exact graph',
+      );
+      const ids = painted
+        .at(-1)
+        .map((r) =>
+          JSON.stringify([r.coordinates, r.oneway, Boolean(r.directFlow)]),
+        );
+      assert.equal(ids.length, hasKey ? 3 : 2);
+      assert.equal(new Set(ids).size, ids.length);
+      ingestion.cancelActiveFetch();
+      clearTimeout(state._retryTimer);
+    });
+  }

src/layers/traffic/style.js

@@ -104,7 +104,7 @@ export function createStyle({ state: layerState, services, parts, source }) {
       const bucket = dot.bucket;
       if (!bucket) continue; // sim/uncovered dots stay byte-identical
       dot.point.color = layerState._activeBucketColors[bucket];
-      dot.point.pixelSize =
+      dot.nominalSize = dot.point.pixelSize =
         baseDotSize(dot.road?.type, bucket) +
         (bucket === 'jam' ? 1 : 0) +
         activeSizeDelta(bucket);

src/layers/traffic/surface.js

@@ -0,0 +1,435 @@
+import { phaseTiming } from '../../sources/phaseTiming.js';
+import * as Cesium from 'cesium';
+import { DOT_HEIGHT_OFFSET, MAX_WAYPOINTS_PER_ROAD } from './policy.js';
+
+function surfaceTilesReady(scene) {
+  if (scene.globe?.show) return scene.globe.tilesLoaded !== false;
+  let found = false;
+  for (let i = 0; i < (scene.primitives?.length || 0); i++) {
+    const primitive = scene.primitives.get(i);
+    if (!primitive.show || typeof primitive.tilesLoaded !== 'boolean') continue;
+    found = true;
+    if (!primitive.tilesLoaded) return false;
+  }
+  return found;
+}
+
+const renderedFrames = new WeakMap();
+/** Observe completed frames only while an enabled traffic consumer owns them. */
+export function observeTrafficSurface(scene) {
+  if (!scene.postRender?.addEventListener || !scene.camera?.viewMatrix)
+    return () => {};
+  let frame = renderedFrames.get(scene);
+  if (!frame) {
+    frame = {
+      view: new Cesium.Matrix4(),
+      projection: new Cesium.Matrix4(),
+      owners: 0,
+    };
+    renderedFrames.set(scene, frame);
+    frame.remove = scene.postRender.addEventListener(() => {
+      Cesium.Matrix4.clone(scene.camera.viewMatrix, frame.view);
+      Cesium.Matrix4.clone(
+        scene.camera.frustum.projectionMatrix,
+        frame.projection,
+      );
+      frame.surface = trafficSurfaceKey(scene);
+      frame.ready = surfaceTilesReady(scene);
+    });
+  }
+  frame.owners++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--frame.owners === 0) {
+      frame.remove();
+      renderedFrames.delete(scene);
+    }
+  };
+}
+
+function currentRenderedFrame(scene) {
+  if (!scene.postRender?.addEventListener || !scene.camera?.viewMatrix)
+    return { ready: surfaceTilesReady(scene) };
+  const frame = renderedFrames.get(scene);
+  return frame &&
+    frame.surface === trafficSurfaceKey(scene) &&
+    Cesium.Matrix4.equals(frame.view, scene.camera.viewMatrix) &&
+    Cesium.Matrix4.equals(
+      frame.projection,
+      scene.camera.frustum.projectionMatrix,
+    )
+    ? frame
+    : null;
+}
+
+/** Only a completed render of this camera can certify cached surface heights. */
+export function trafficSurfaceReady(scene) {
+  return currentRenderedFrame(scene)?.ready === true;
+}
+
+/** Preserve bends and insert height samples at most 150 m apart, splitting long roads. */
+export function roadSurfaceChunks(coordinates) {
+  const chunks = [];
+  let chunk = [coordinates[0]];
+  let chunkMetres = 0;
+  for (let i = 1; i < coordinates.length; i++) {
+    const a = coordinates[i - 1],
+      b = coordinates[i];
+    const metres =
+      Math.hypot(
+        (b[0] - a[0]) * Math.cos((a[1] * Math.PI) / 180),
+        b[1] - a[1],
+      ) * 111320;
+    const steps = Math.max(1, Math.ceil(metres / 150));
+    for (let j = 1; j <= steps; j++) {
+      const point =
+        j === steps
+          ? b
+          : [
+              a[0] + ((b[0] - a[0]) * j) / steps,
+              a[1] + ((b[1] - a[1]) * j) / steps,
+            ];
+      const stepMetres = metres / steps;
+      if (chunk.length > 1 && chunkMetres + stepMetres > 600) {
+        chunks.push(chunk);
+        chunk = [chunk.at(-1)];
+        chunkMetres = 0;
+      }
+      chunk.push(point);
+      chunkMetres += stepMetres;
+      if (chunk.length === MAX_WAYPOINTS_PER_ROAD) {
+        chunks.push(chunk);
+        chunk = [point];
+        chunkMetres = 0;
+      }
+    }
+  }
+  if (chunk.length > 1) chunks.push(chunk);
+  return chunks;
+}
+
+/** Height stations remain at most 150 m apart without sampling every short bend. */
+export function roadHeightStations(coords) {
+  const distances = [0];
+  const indices = [0];
+  let anchor = 0;
+  for (let i = 1; i < coords.length; i++) {
+    const a = coords[i - 1],
+      b = coords[i];
+    const metres =
+      Math.hypot(
+        (b[0] - a[0]) * Math.cos((a[1] * Math.PI) / 180),
+        b[1] - a[1],
+      ) * 111320;
+    distances.push(distances[i - 1] + metres);
+    if (distances[i] - distances[anchor] > 150.001 && i - 1 > anchor) {
+      anchor = i - 1;
+      indices.push(anchor);
+    }
+  }
+  if (indices.at(-1) !== coords.length - 1) indices.push(coords.length - 1);
+  return { indices, distances };
+}
+
+const validHeight = (height) =>
+  Number.isFinite(height) && Math.abs(height) <= 9000;
+
+/**
+ * Reuse the rendered depth buffer instead of drawing a new pick frustum per
+ * station. Iteration corrects the projection's height estimate. A depth hit
+ * is accepted only at this road coordinate (2 m), never on a foreground roof
+ * or hillside projected onto a different geographic point. Translucent traffic
+ * is absent from Cesium's default pickPosition depth pass.
+ */
+export function renderedRoadHeight(scene, lon, lat, estimate) {
+  if (
+    !scene.pickPositionSupported ||
+    scene.pickTranslucentDepth ||
+    !currentRenderedFrame(scene) ||
+    !scene.canvas?.clientWidth ||
+    !scene.frameState
+  )
+    return undefined;
+  let height = validHeight(estimate) ? estimate : 0;
+  const point = new Cesium.Cartesian3();
+  const screen = new Cesium.Cartesian2();
+  for (let attempt = 0; attempt < 4; attempt++) {
+    Cesium.Cartesian3.fromDegrees(lon, lat, height, undefined, point);
+    if (
+      !Cesium.SceneTransforms.worldToWindowCoordinates(scene, point, screen) ||
+      screen.x < 0 ||
+      screen.y < 0 ||
+      screen.x >= scene.canvas.clientWidth ||
+      screen.y >= scene.canvas.clientHeight
+    )
+      return undefined;
+    let hit;
+    try {
+      hit = scene.pickPosition(screen);
+    } catch {
+      return undefined;
+    }
+    if (!hit) return undefined;
+    const location = Cesium.Cartographic.fromCartesian(hit);
+    if (!location || !validHeight(location.height)) return undefined;
+    const dx =
+      (Cesium.Math.toDegrees(location.longitude) - lon) *
+      Math.cos((lat * Math.PI) / 180) *
+      111320;
+    const dy = (Cesium.Math.toDegrees(location.latitude) - lat) * 111320;
+    if (Math.hypot(dx, dy) <= 2) return location.height;
+    height = location.height;
+  }
+  return undefined;
+}
+
+// Per-scene, coordinate-keyed LRU. Never writes raw samples into shared ground floors.
+const sceneCaches = new WeakMap();
+
+// Stable ids for the objects heights are sampled from (tilesets, terrain).
+const surfaceIds = new WeakMap();
+let nextSurfaceId = 1;
+const surfaceId = (object) => {
+  if (!object || typeof object !== 'object') return 0;
+  if (!surfaceIds.has(object)) surfaceIds.set(object, nextSurfaceId++);
+  return surfaceIds.get(object);
+};
+
+/**
+ * Name what heights are sampled against: the terrain provider when the globe
+ * is shown, otherwise the set of visible 3D tilesets. A map-provider switch
+ * changes it and invalidates every cached height.
+ */
+const surfaceKeys = new WeakMap();
+export function trafficSurfaceKey(scene) {
+  let state = surfaceKeys.get(scene);
+  if (!state) {
+    state = { globe: null, terrain: null, tiles: [], key: '' };
+    surfaceKeys.set(scene, state);
+  }
+  const globe = Boolean(scene.globe?.show);
+  const terrain = globe ? scene.globe.terrainProvider : null;
+  let changed = state.globe !== globe || state.terrain !== terrain;
+  let count = 0;
+  if (!globe) {
+    for (let i = 0; i < (scene.primitives?.length || 0); i++) {
+      const primitive = scene.primitives.get(i);
+      if (!primitive?.show || typeof primitive.tilesLoaded !== 'boolean')
+        continue;
+      if (state.tiles[count] !== primitive) {
+        state.tiles[count] = primitive;
+        changed = true;
+      }
+      count++;
+    }
+  }
+  if (count !== state.tiles.length) {
+    state.tiles.length = count;
+    changed = true;
+  }
+  if (changed) {
+    state.globe = globe;
+    state.terrain = terrain;
+    // Allocate only when the actual map surface changes, never per frame.
+    state.key = globe
+      ? `globe:${surfaceId(terrain)}`
+      : `tiles:${state.tiles.map(surfaceId).join(',')}`;
+  }
+  return state.key;
+}
+
+/**
+ * Level-of-detail band for a point seen from the camera: log2 of the
+ * camera-to-point distance in 100 m steps. Streamed meshes refine roughly
+ * one level per halving of distance, so a sample taken from a higher band
+ * came from coarser geometry than the view now shows.
+ */
+export function detailBand(cameraLon, cameraLat, cameraHeight, lon, lat) {
+  if (!Number.isFinite(cameraHeight)) return 0;
+  const dx = (lon - cameraLon) * Math.cos((lat * Math.PI) / 180) * 111320;
+  const dy = (lat - cameraLat) * 111320;
+  const distance = Math.sqrt(dx * dx + dy * dy + cameraHeight * cameraHeight);
+  return Math.max(0, Math.floor(Math.log2(distance / 100)));
+}
+// Yield to rendering/input between bounded work slices without reserving
+// every slice for a separate vsync (which idles the remaining frame budget).
+const nextSlice = (hasSurface) =>
+  hasSurface && globalThis.scheduler?.yield
+    ? globalThis.scheduler.yield()
+    : new Promise((resolve) => setTimeout(resolve, 0));
+
+/** Prepare only admitted roads in bounded slices; locally missing surfaces defer that road. */
+export async function prepareRoadSurfaces(
+  roads,
+  scene,
+  ground,
+  excluded,
+  signal,
+  { onReady, onMetrics, frameBudgetMs = 12, revalidate = false } = {},
+) {
+  // Cached heights are only as good as the surface and detail they came
+  // from: a provider switch drops them all, and a point now seen from a
+  // closer band than its sample is re-sampled against the finer mesh.
+  const surface = trafficSurfaceKey(scene);
+  let cache = sceneCaches.get(scene);
+  if (!cache || cache.surface !== surface) {
+    cache = { surface, heights: new Map() };
+    sceneCaches.set(scene, cache);
+  }
+  const cameraCarto = scene.camera?.positionCartographic;
+  const cameraLon = cameraCarto
+    ? Cesium.Math.toDegrees(cameraCarto.longitude)
+    : 0;
+  const cameraLat = cameraCarto
+    ? Cesium.Math.toDegrees(cameraCarto.latitude)
+    : 0;
+  const cameraHeight = cameraCarto ? cameraCarto.height : NaN;
+  const start = performance.now();
+  const metrics = {
+    sampleCount: 0,
+    sampleMs: 0,
+    cacheHits: 0,
+    depthHits: 0,
+    roads: roads.length,
+    pending: 0,
+    maxSliceMs: 0,
+  };
+  let sliceStart = performance.now();
+  const carto = new Cesium.Cartographic();
+  const ready = [],
+    pending = [];
+  for (const road of roads) {
+    let resolved = true;
+    let settledRoad = true;
+    const { indices, distances } = roadHeightStations(road.coords);
+    const heights = new Array(road.coords.length);
+    for (const i of indices) {
+      signal?.throwIfAborted();
+      const [lon, lat] = road.coords[i];
+      const key = `${lon.toFixed(6)},${lat.toFixed(6)}`;
+      const cached = cache.heights.get(key);
+      const settled = trafficSurfaceReady(scene);
+      const band = detailBand(cameraLon, cameraLat, cameraHeight, lon, lat);
+      let height =
+        cached &&
+        (!revalidate || cached.refined) &&
+        (cached.settled || !settled) &&
+        band >= cached.band
+          ? cached.height
+          : undefined;
+      if (height !== undefined) {
+        if (!cached.settled) settledRoad = false;
+        metrics.cacheHits++;
+        cache.heights.delete(key);
+        cache.heights.set(key, cached);
+      } else {
+        if (!settled) settledRoad = false;
+        carto.longitude = Cesium.Math.toRadians(lon);
+        carto.latitude = Cesium.Math.toRadians(lat);
+        carto.height = 0;
+        const floor = ground?.cachedGroundFloor?.(lat, lon);
+        let sampled;
+        // sampleHeight reads the locally rendered mesh, not unresolved/offscreen
+        // tiles. Global tilesLoaded can stay false while this street is usable.
+        if (scene.globe?.show) sampled = scene.globe.getHeight?.(carto);
+        else {
+          const estimate = Cesium.Cartographic.fromCartesian(
+            road.waypoints[i],
+          )?.height;
+          sampled = renderedRoadHeight(scene, lon, lat, estimate);
+          if (validHeight(sampled)) metrics.depthHits++;
+        }
+        if (
+          !scene.globe?.show &&
+          !validHeight(sampled) &&
+          scene.sampleHeightSupported
+        ) {
+          const sampleStart = performance.now();
+          metrics.sampleCount++;
+          const shown = (excluded || []).filter((p) => p?.show);
+          for (const primitive of shown) primitive.show = false;
+          try {
+            sampled = scene.sampleHeight(carto, excluded);
+          } catch {
+            /* local mesh missing */
+          } finally {
+            for (const primitive of shown) primitive.show = true;
+          }
+          metrics.sampleMs += performance.now() - sampleStart;
+        }
+        // A shared floor is a safe provisional waypoint, but not permission to
+        // display a photoreal road: only local measured mesh heights admit it.
+        if (!validHeight(sampled)) {
+          // A coarser measured height still beats an unresolved road; the
+          // finer sample is retried on the next pass.
+          if (cached) height = cached.height;
+          else {
+            resolved = false;
+            height = validHeight(floor) ? floor : 0;
+          }
+        } else {
+          height = validHeight(floor) ? Math.max(sampled, floor) : sampled;
+          cache.heights.delete(key);
+          cache.heights.set(key, {
+            height,
+            settled,
+            band,
+            refined: revalidate,
+          });
+          while (cache.heights.size > 40000)
+            cache.heights.delete(cache.heights.keys().next().value);
+        }
+      }
+      heights[i] = height;
+      const elapsed = performance.now() - sliceStart;
+      if (elapsed >= frameBudgetMs) {
+        metrics.maxSliceMs = Math.max(metrics.maxSliceMs, elapsed);
+        // Before the first local mesh exists, give its tile/worker tasks the
+        // normal queue priority instead of repeatedly probing an empty scene.
+        await nextSlice(metrics.cacheHits + metrics.depthHits > 0);
+        sliceStart = performance.now();
+      }
+    }
+    let station = 1;
+    for (let i = 0; i < road.coords.length; i++) {
+      while (station < indices.length - 1 && i > indices[station]) station++;
+      const a = indices[station - 1],
+        b = indices[station];
+      const span = distances[b] - distances[a];
+      const t = span > 0 ? (distances[i] - distances[a]) / span : 0;
+      const height = heights[a] + (heights[b] - heights[a]) * t;
+      const [lon, lat] = road.coords[i];
+      const floor = ground?.cachedGroundFloor?.(lat, lon);
+      Cesium.Cartesian3.fromDegrees(
+        lon,
+        lat,
+        (validHeight(floor) ? Math.max(height, floor) : height) +
+          DOT_HEIGHT_OFFSET,
+        undefined,
+        road.waypoints[i],
+      );
+    }
+    for (let i = 0; i < road.segmentDist.length; i++)
+      road.segmentDist[i] = Cesium.Cartesian3.distance(
+        road.waypoints[i],
+        road.waypoints[i + 1],
+      );
+    road.surfaceReady = resolved;
+    road.surfaceSettled = settledRoad;
+    if (resolved) {
+      ready.push(road);
+      onReady?.(road);
+    } else pending.push(road);
+  }
+  metrics.pending = pending.length;
+  metrics.maxSliceMs = Math.max(
+    metrics.maxSliceMs,
+    performance.now() - sliceStart,
+  );
+  phaseTiming('surface', start, metrics);
+  onMetrics?.(metrics);
+  signal?.throwIfAborted();
+  return { ready, pending, metrics };
+}

src/layers/traffic/surface.test.mjs

@@ -0,0 +1,405 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as C from 'cesium';
+import {
+  detailBand,
+  renderedRoadHeight,
+  prepareRoadSurfaces,
+  roadSurfaceChunks,
+  roadHeightStations,
+  trafficSurfaceReady,
+  trafficSurfaceKey,
+  observeTrafficSurface,
+} from './surface.js';
+const road = (coords) => ({
+  coords,
+  waypoints: coords.map(() => new C.Cartesian3()),
+  segmentDist: coords.slice(1).map(() => 0),
+});
+test('surface points preserve bends, bound spacing, and split rather than decimate long roads', () => {
+  const chunks = roadSurfaceChunks([
+    [0, 0],
+    [0.2, 0],
+    [0.2, 0.1],
+  ]);
+  assert.ok(chunks.length > 1);
+  assert.ok(chunks.every((c) => c.length <= 80));
+  for (const chunk of chunks) {
+    let length = 0;
+    for (let i = 1; i < chunk.length; i++)
+      length +=
+        Math.hypot(
+          (chunk[i][0] - chunk[i - 1][0]) *
+            Math.cos((chunk[i - 1][1] * Math.PI) / 180),
+          chunk[i][1] - chunk[i - 1][1],
+        ) * 111320;
+    assert.ok(
+      length <= 600.01,
+      'short chunks keep the population budget near the visible road',
+    );
+  }
+  assert.ok(chunks.flat().some((p) => p[0] === 0.2 && p[1] === 0));
+  for (const c of chunks)
+    for (let i = 1; i < c.length; i++)
+      assert.ok(
+        Math.hypot(c[i][0] - c[i - 1][0], c[i][1] - c[i - 1][1]) * 111320 <=
+          150.01,
+      );
+});
+test('per-vertex mesh heights follow terrain, reject invalid samples, and leave shared cache unmodified', async () => {
+  const heights = [100, 200, NaN, 9001, -9001];
+  let samples = 0;
+  const r = road([
+    [0, 0],
+    [0.001, 0],
+    [0.002, 0],
+    [0.003, 0],
+    [0.004, 0],
+  ]);
+  const tileset = { show: true, tilesLoaded: true };
+  const scene = {
+    globe: { show: false },
+    primitives: { length: 1, get: () => tileset },
+    sampleHeightSupported: true,
+    sampleHeight: () => heights[samples++],
+  };
+  const ground = {
+    cachedGroundFloor: () => 50,
+    reportMeshFloorCell: () => assert.fail('raw sample poisoned shared floor'),
+  };
+  let metrics;
+  const prepared = await prepareRoadSurfaces([r], scene, ground, [], null, {
+    onMetrics: (value) => (metrics = value),
+  });
+  assert.equal(metrics.sampleCount, 5);
+  assert.equal(prepared.pending.length, 1);
+  assert.equal(samples, 5);
+  const actual = r.waypoints.map((p) =>
+    Math.round(C.Cartographic.fromCartesian(p).height),
+  );
+  assert.deepEqual(actual, [103, 203, 53, 53, 53]);
+  tileset.tilesLoaded = false;
+  assert.equal(trafficSurfaceReady(scene), false);
+  scene.sampleHeight = () => 75;
+  const resumed = await prepareRoadSurfaces([r], scene, ground, []);
+  assert.equal(
+    resumed.ready.length,
+    1,
+    'other loading tiles do not block a local mesh',
+  );
+  let picks = 0;
+  scene.sampleHeight = () => {
+    picks++;
+    return 75;
+  };
+  await prepareRoadSurfaces([r], scene, ground, []);
+  assert.equal(picks, 0, 'validated coordinate heights survive cache hits');
+  const abort = new AbortController();
+  abort.abort();
+  await assert.rejects(
+    prepareRoadSurfaces([r], scene, ground, [], abort.signal),
+    { name: 'AbortError' },
+  );
+});
+test('visible-globe roads floor each vertex without mesh picks', async () => {
+  const r = road([
+    [0, 0],
+    [0.001, 0],
+  ]);
+  let calls = 0;
+  await prepareRoadSurfaces(
+    [r],
+    {
+      globe: { show: true, tilesLoaded: true, getHeight: () => ++calls * 100 },
+      sampleHeight: () => assert.fail('mesh sampled'),
+    },
+    { cachedGroundFloor: () => 20 },
+    [],
+  );
+  assert.equal(calls, 2);
+  assert.deepEqual(
+    r.waypoints.map((p) => Math.round(C.Cartographic.fromCartesian(p).height)),
+    [103, 203],
+  );
+});
+
+test('cached heights follow detail and provider; same-detail revisits sample nothing', async () => {
+  const r = road([
+    [0, 0],
+    [0.001, 0],
+  ]);
+  const tileset = { show: true, tilesLoaded: true };
+  let mesh = 40,
+    samples = 0;
+  const camera = (height) => ({
+    positionCartographic: { longitude: 0, latitude: 0, height },
+  });
+  const scene = {
+    globe: { show: false },
+    primitives: { length: 1, get: () => tileset },
+    sampleHeightSupported: true,
+    sampleHeight: () => (samples++, mesh),
+    camera: camera(3000),
+  };
+  const heightAt = () =>
+    Math.round(C.Cartographic.fromCartesian(r.waypoints[0]).height);
+  // Settled but coarse: sampled from 3 km.
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 2);
+  assert.equal(heightAt(), 43);
+  // Same detail band on a revisit: zero samples.
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 2);
+  // Zooming out never re-samples a finer height either.
+  scene.camera = camera(6000);
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 2);
+  // Closer view, finer mesh: re-sampled and the waypoint follows it.
+  mesh = 47;
+  scene.camera = camera(250);
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 4);
+  assert.equal(heightAt(), 50);
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 4, 'the finer sample is now the cached one');
+  // A different photoreal tileset (map provider switch) invalidates all,
+  // even from a coarser view that would otherwise reuse the finer sample.
+  const other = { show: true, tilesLoaded: true };
+  scene.primitives.get = () => other;
+  scene.camera = camera(3000);
+  mesh = 30;
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 6);
+  assert.equal(heightAt(), 33);
+  // A finer sample that fails keeps the coarser measured height.
+  scene.camera = camera(250);
+  mesh = NaN;
+  const kept = await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 8);
+  assert.equal(kept.ready.length, 1);
+  assert.equal(heightAt(), 33);
+});
+
+test('detail bands double with distance and ignore a missing camera', () => {
+  assert.equal(detailBand(0, 0, NaN, 0, 0), 0);
+  assert.equal(detailBand(0, 0, 150, 0, 0), 0);
+  assert.equal(detailBand(0, 0, 250, 0, 0), 1);
+  assert.equal(detailBand(0, 0, 3000, 0, 0), 4);
+  assert.ok(detailBand(0, 0, 250, 0.02, 0) > detailBand(0, 0, 250, 0, 0));
+});
+
+test('a camera jump cannot certify old rendered depth or cache coarse heights as settled', async () => {
+  const tileset = { show: true, tilesLoaded: true };
+  let height = 20,
+    samples = 0;
+  const scene = {
+    postRender: new C.Event(),
+    camera: {
+      viewMatrix: C.Matrix4.clone(C.Matrix4.IDENTITY),
+      frustum: { projectionMatrix: C.Matrix4.clone(C.Matrix4.IDENTITY) },
+    },
+    globe: { show: false },
+    primitives: { length: 1, get: () => tileset },
+    sampleHeightSupported: true,
+    sampleHeight: () => (samples++, height),
+  };
+  assert.equal(trafficSurfaceReady(scene), false);
+  const removeSurfaceObserver = observeTrafficSurface(scene);
+  scene.postRender.raiseEvent();
+  assert.equal(trafficSurfaceReady(scene), true);
+  scene.camera.viewMatrix[12] = 100;
+  assert.equal(
+    trafficSurfaceReady(scene),
+    false,
+    'old camera readiness is stale',
+  );
+  const r = road([
+    [0, 0],
+    [0.001, 0],
+  ]);
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(r.surfaceSettled, false);
+  height = 80;
+  scene.postRender.raiseEvent();
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 4, 'the first fresh render revalidates coarse heights');
+  assert.equal(r.surfaceSettled, true);
+  assert.ok(
+    Math.abs(C.Cartographic.fromCartesian(r.waypoints[0]).height - 83) < 0.01,
+  );
+  height = 100;
+  await prepareRoadSurfaces([r, r], scene, null, [], null, {
+    revalidate: true,
+  });
+  assert.equal(
+    samples,
+    6,
+    'the bounded refinement replaces initially settled coarse samples too',
+  );
+  removeSurfaceObserver();
+  assert.ok(
+    Math.abs(C.Cartographic.fromCartesian(r.waypoints[0]).height - 103) < 0.01,
+  );
+  await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(samples, 6, 'ordinary same-band revisits still reuse the cache');
+  await prepareRoadSurfaces([r], scene, null, [], null, { revalidate: true });
+  assert.equal(
+    samples,
+    6,
+    'already refined same-band coordinates are not sampled twice',
+  );
+});
+
+test('height stations preserve bends while bounding sample spacing along the road', async () => {
+  const coords = Array.from({ length: 31 }, (_, i) => [
+    i * 0.0001,
+    (i % 2) * 0.00001,
+  ]);
+  const { indices, distances } = roadHeightStations(coords);
+  assert.ok(indices.length <= 4);
+  for (let i = 1; i < indices.length; i++)
+    assert.ok(distances[indices[i]] - distances[indices[i - 1]] <= 150.001);
+  const r = road(coords);
+  let picks = 0;
+  await prepareRoadSurfaces(
+    [r],
+    {
+      globe: {
+        show: true,
+        tilesLoaded: true,
+        getHeight: (c) => {
+          picks++;
+          return C.Math.toDegrees(c.longitude) * 1000;
+        },
+      },
+    },
+    null,
+    [],
+  );
+  assert.equal(picks, indices.length);
+  for (let i = 0; i < coords.length; i++) {
+    const c = C.Cartographic.fromCartesian(r.waypoints[i]);
+    assert.ok(Math.abs(C.Math.toDegrees(c.longitude) - coords[i][0]) < 1e-9);
+    assert.ok(Math.abs(C.Math.toDegrees(c.latitude) - coords[i][1]) < 1e-9);
+    assert.ok(Math.abs(c.height - (coords[i][0] * 1000 + 3)) < 0.01);
+  }
+});
+
+test('rendered road depth is geographically checked, bounded, and avoids mesh redraws', async (t) => {
+  t.mock.method(
+    C.SceneTransforms,
+    'worldToWindowCoordinates',
+    (scene, point, out) => {
+      out.x = 100;
+      out.y = 100;
+      return out;
+    },
+  );
+  const scene = {
+    globe: { show: false },
+    frameState: {},
+    canvas: { clientWidth: 800, clientHeight: 600 },
+    pickPositionSupported: true,
+    sampleHeightSupported: true,
+    pickPosition: () => C.Cartesian3.fromDegrees(-97, 30, 100),
+    sampleHeight: () =>
+      assert.fail('valid depth must not draw another pick frustum'),
+  };
+  assert.ok(Math.abs(renderedRoadHeight(scene, -97, 30, 0) - 100) < 0.001);
+  const r = road([
+    [-97, 30],
+    [-97, 30.000005],
+  ]);
+  r.waypoints = r.coords.map(([lon, lat]) =>
+    C.Cartesian3.fromDegrees(lon, lat, 50),
+  );
+  const result = await prepareRoadSurfaces([r], scene, null, []);
+  assert.equal(result.metrics.depthHits, 2);
+  assert.equal(result.metrics.sampleCount, 0);
+  let calls = 0;
+  scene.pickPosition = () => {
+    calls++;
+    return C.Cartesian3.fromDegrees(-97.001, 30, 150);
+  };
+  assert.equal(
+    renderedRoadHeight(scene, -97, 30, 0),
+    undefined,
+    'foreground roof is not the road coordinate',
+  );
+  assert.equal(calls, 4);
+  scene.pickPosition = () => C.Cartesian3.fromDegrees(-97, 30, 10000);
+  assert.equal(renderedRoadHeight(scene, -97, 30, 0), undefined);
+  scene.pickPosition = () => {
+    throw new Error('depth unavailable');
+  };
+  assert.equal(renderedRoadHeight(scene, -97, 30, 0), undefined);
+  scene.pickTranslucentDepth = true;
+  assert.equal(renderedRoadHeight(scene, -97, 30, 0), undefined);
+});
+
+test('surface keys reuse identity without building arrays or strings on unchanged frames', (t) => {
+  const tiles = [
+    { show: true, tilesLoaded: true },
+    { show: true, tilesLoaded: false },
+  ];
+  const scene = {
+    globe: { show: false, terrainProvider: {} },
+    primitives: {
+      get: (i) => tiles[i],
+      get length() {
+        return tiles.length;
+      },
+    },
+    camera: {
+      viewMatrix: C.Matrix4.clone(C.Matrix4.IDENTITY),
+      frustum: { projectionMatrix: C.Matrix4.clone(C.Matrix4.IDENTITY) },
+    },
+    postRender: new C.Event(),
+  };
+  const first = trafficSurfaceKey(scene);
+  const remove = observeTrafficSurface(scene);
+  const originalMap = Array.prototype.map;
+  const originalJoin = Array.prototype.join;
+  let maps = 0,
+    joins = 0;
+  Array.prototype.map = function (...args) {
+    maps++;
+    return originalMap.apply(this, args);
+  };
+  Array.prototype.join = function (...args) {
+    joins++;
+    return originalJoin.apply(this, args);
+  };
+  try {
+    for (let i = 0; i < 1000; i++) {
+      scene.postRender.raiseEvent();
+      assert.equal(trafficSurfaceKey(scene), first);
+    }
+  } finally {
+    Array.prototype.map = originalMap;
+    Array.prototype.join = originalJoin;
+  }
+  assert.equal(maps, 0);
+  assert.equal(joins, 0);
+  tiles[1].show = false;
+  const hidden = trafficSurfaceKey(scene);
+  assert.notEqual(hidden, first);
+  tiles[1] = { show: true, tilesLoaded: true };
+  assert.notEqual(
+    trafficSurfaceKey(scene),
+    first,
+    'same-count tileset replacement is a new surface',
+  );
+  scene.globe.show = true;
+  const terrain = trafficSurfaceKey(scene);
+  scene.globe.terrainProvider = {};
+  assert.notEqual(trafficSurfaceKey(scene), terrain);
+  remove();
+  remove();
+  assert.equal(scene.postRender.numberOfListeners, 0);
+  assert.equal(
+    trafficSurfaceReady(scene),
+    false,
+    'readiness cannot recreate a subscription',
+  );
+});

src/layers/traffic/timing.js

@@ -1,9 +1,6 @@
 import * as Cesium from 'cesium';
-import {
-  TRAFFIC_TIMING_ENABLED,
-  MAX_WAYPOINTS_PER_ROAD,
-  DOT_HEIGHT_OFFSET,
-} from './policy.js';
+import { roadSurfaceChunks } from './surface.js';
+import { TRAFFIC_TIMING_ENABLED, DOT_HEIGHT_OFFSET } from './policy.js';
 
 export function createTiming({ state: layerState, services, parts, source }) {
   /**
@@ -221,18 +218,7 @@ export function createTiming({ state: layerState, services, parts, source }) {
         _trafficTimingParseEnd,
         { roadCount: 0 },
       );
-      trafficTimingAggregate(
-        'sample-height-total',
-        _trafficTimingState,
-        _trafficTimingParseStartTime,
-        0,
-        {
-          sampleHeightCalls: 0,
-          sampleHeightMeanMs: 0,
-          distinctCells: 0,
-          roadCount: 0,
-        },
-      );
+
       trafficTimingAggregate(
         'waypoint-materialization',
         _trafficTimingState,
@@ -246,95 +232,59 @@ export function createTiming({ state: layerState, services, parts, source }) {
 
     const roads = [];
     /* TRACE_ONLY_BEGIN */
-    const _trafficTimingSampledCells = new Set();
-    let _trafficTimingSampleHeightCalls = 0;
-    let _trafficTimingSampleHeightMs = 0;
     let _trafficTimingWaypointMaterializationMs = 0;
     /* TRACE_ONLY_END */
     for (const road of roadData.roads) {
       if (!road.coordinates || road.coordinates.length < 2) continue;
 
-      const rawCoords = road.coordinates;
-      const simplifyStep =
-        rawCoords.length > MAX_WAYPOINTS_PER_ROAD
-          ? Math.ceil(rawCoords.length / MAX_WAYPOINTS_PER_ROAD)
-          : 1;
-      const coords = [];
-      for (let i = 0; i < rawCoords.length; i += simplifyStep) {
-        coords.push(rawCoords[i]);
-      }
+      for (const coords of roadSurfaceChunks(road.coordinates)) {
+        const type = road.type;
+        const oneway = road.oneway;
 
-      const last = rawCoords[rawCoords.length - 1];
-      const tail = coords[coords.length - 1];
-      if (!tail || tail[0] !== last[0] || tail[1] !== last[1]) {
-        coords.push(last);
-      }
-      if (coords.length < 2) continue;
-
-      const type = road.type;
-      const oneway = road.oneway;
-
-      let baseHeight = 0;
-      const firstCoord = coords[0];
-      if (layerState._viewer?.scene?.sampleHeightSupported && firstCoord) {
         /* TRACE_ONLY_BEGIN */
-        _trafficTimingSampleHeightCalls += 1;
-        _trafficTimingSampledCells.add(
-          `${firstCoord[1].toFixed(3)},${firstCoord[0].toFixed(3)}`,
-        );
+        const _trafficTimingMaterializeStart = performance.now();
         /* TRACE_ONLY_END */
-        const carto = Cesium.Cartographic.fromDegrees(
-          firstCoord[0],
-          firstCoord[1],
-        );
+        const waypoints = coords.map(([lng, lat]) => {
+          const floor = services.ground?.cachedGroundFloor?.(lat, lng);
+          const h =
+            (Number.isFinite(floor) && Math.abs(floor) <= 9000
+              ? floor
+              : layerState._viewHeightEstimate || 0) + DOT_HEIGHT_OFFSET;
+          return Cesium.Cartesian3.fromDegrees(lng, lat, h);
+        });
+        const segmentDist = [];
+        for (let i = 0; i < waypoints.length - 1; i++) {
+          segmentDist.push(
+            Cesium.Cartesian3.distance(waypoints[i], waypoints[i + 1]),
+          );
+        }
         /* TRACE_ONLY_BEGIN */
-        const _trafficTimingSampleStart = performance.now();
+        _trafficTimingWaypointMaterializationMs +=
+          performance.now() - _trafficTimingMaterializeStart;
         /* TRACE_ONLY_END */
-        const sampled = layerState._viewer.scene.sampleHeight(carto);
-        /* TRACE_ONLY_BEGIN */
-        _trafficTimingSampleHeightMs +=
-          performance.now() - _trafficTimingSampleStart;
-        /* TRACE_ONLY_END */
-        if (Number.isFinite(sampled)) baseHeight = sampled;
-      }
 
-      /* TRACE_ONLY_BEGIN */
-      const _trafficTimingMaterializeStart = performance.now();
-      /* TRACE_ONLY_END */
-      const waypoints = coords.map(([lng, lat]) => {
-        const h = baseHeight + DOT_HEIGHT_OFFSET;
-        return Cesium.Cartesian3.fromDegrees(lng, lat, h);
-      });
-      const segmentDist = [];
-      for (let i = 0; i < waypoints.length - 1; i++) {
-        segmentDist.push(
-          Cesium.Cartesian3.distance(waypoints[i], waypoints[i + 1]),
-        );
+        for (const direction of oneway ? [oneway] : [1, -1])
+          roads.push({
+            densityWeight: road.densityWeight ?? (oneway ? 1 : 0.5),
+            drivable: road.drivable,
+            roadClass: road.roadClass,
+            roadProperties: road.roadProperties,
+            directFlow: road.directFlow,
+            simulatedOnly: road.simulatedOnly,
+            coords,
+            type,
+            oneway: direction,
+            waypoints,
+            segmentDist,
+            flow: road.flow || null,
+          });
       }
-      /* TRACE_ONLY_BEGIN */
-      _trafficTimingWaypointMaterializationMs +=
-        performance.now() - _trafficTimingMaterializeStart;
-      /* TRACE_ONLY_END */
-
-      roads.push({ coords, type, oneway, waypoints, segmentDist });
     }
-
     /* TRACE_ONLY_BEGIN */
     const _trafficTimingMetrics = {
       roadCount: roads.length,
-      sampleHeightCalls: _trafficTimingSampleHeightCalls,
-      sampleHeightMeanMs: _trafficTimingSampleHeightCalls
-        ? _trafficTimingSampleHeightMs / _trafficTimingSampleHeightCalls
-        : 0,
-      distinctCells: _trafficTimingSampledCells.size,
     };
-    trafficTimingAggregate(
-      'sample-height-total',
-      _trafficTimingState,
-      _trafficTimingParseStartTime,
-      _trafficTimingSampleHeightMs,
-      _trafficTimingMetrics,
-    );
+
     trafficTimingAggregate(
       'waypoint-materialization',
       _trafficTimingState,

src/layers/traffic/viewport.js

@@ -1,3 +1,4 @@
+import { createReticleFootprint } from './footprint.js';
 import * as Cesium from 'cesium';
 import {
   deriveFetchCenter,
@@ -13,6 +14,7 @@ import {
 } from './policy.js';
 
 export function createViewport({ state: layerState, services, parts, source }) {
+  const reticleFootprint = createReticleFootprint();
   // ─── Camera Monitoring ─────────────────────────────────────
 
   /**
@@ -164,32 +166,16 @@ export function createViewport({ state: layerState, services, parts, source }) {
    */
 
   function clampBounds(bounds) {
-    return clampBoundsAroundCenter(bounds, getBoundsCenter(bounds));
+    return bounds.coverage
+      ? bounds
+      : clampBoundsAroundCenter(bounds, getBoundsCenter(bounds));
   }
 
-  /**
-   * Camera-change handler — the main entry point for viewport-driven road loading.
-   *
-   * Gating logic:
-   *  1. If the camera is above ACTIVATION_ALTITUDE, clear all dots and bail.
-   *  2. Clamp the view bounds and compute the viewport center.
-   *  3. Skip the fetch if the new viewport significantly overlaps the last-fetched
-   *     bounds AND the center has shifted less than MIN_CENTER_SHIFT_KM. This
-   *     prevents redundant fetches during small pans.
-   *  4. Otherwise, debounce and schedule `loadRoadsForBounds`.
-   */
-
-  function onCameraChanged() {
+  /** Debounce camera events and sample the actual settled view, including final flight steps. */
+  function onCameraChanged(options) {
     if (!layerState._enabled) return;
-
-    const alt = getCameraAltitude();
-
-    // Above activation altitude — remove all traffic and stop.
-    // Also null the last-fetch gate: otherwise zooming back down to the SAME
-    // viewport hits the overlap/center-shift skip in step 3 and the dots
-    // (cleared here) never reload (H5). Clearing the gate forces a fresh fetch.
-    if (alt > ACTIVATION_ALTITUDE) {
-      clearTimeout(layerState._fetchTimeout);
+    clearTimeout(layerState._fetchTimeout);
+    if (getCameraAltitude() > ACTIVATION_ALTITUDE) {
       clearTimeout(layerState._retryTimer);
       layerState._retryTimer = null;
       parts.ingestion.cancelActiveFetch();
@@ -202,38 +188,52 @@ export function createViewport({ state: layerState, services, parts, source }) {
       layerState._lastViewCenter = null;
       return;
     }
-
-    const bounds = getViewBounds();
-    if (!bounds) return;
-    // C4 fix: center the fetch box on the camera's look-at ground point (with
-    // nadir fallback + 12 km horizon-gaze pull-back), NOT the view rectangle's
-    // midpoint — at oblique pitch that midpoint drifts toward the horizon.
-    const fetchCenter = getFetchCenter();
-    const clamped = fetchCenter
-      ? clampBoundsAroundCenter(bounds, fetchCenter)
-      : clampBounds(bounds);
-    const center = getBoundsCenter(clamped);
-
-    // Skip re-fetch when viewport overlap is high and center shift is negligible
-    if (
-      layerState._lastBounds &&
-      layerState._lastViewCenter &&
-      boundsOverlap(clamped, layerState._lastBounds, OVERLAP_THRESHOLD) &&
-      distanceKm(center, layerState._lastViewCenter) < MIN_CENTER_SHIFT_KM
-    ) {
-      return;
-    }
-
-    // Debounce: wait for camera to settle before triggering a fetch. In debug
-    // captures the final changed event that arms this exact timeout is its
-    // causal anchor; Cesium's later moveEnd notification is diagnostic only.
     const interactionAnchor = TRAFFIC_TIMING_ENABLED
       ? parts.timing.markTrafficTimingCameraChange()
       : null;
-    clearTimeout(layerState._fetchTimeout);
     layerState._fetchTimeout = setTimeout(
-      () => layerState._loadRoadsForBounds(clamped, alt, interactionAnchor),
-      FETCH_DEBOUNCE,
+      () => {
+        if (!layerState._enabled) return;
+        const alt = getCameraAltitude();
+        if (alt > ACTIVATION_ALTITUDE) return onCameraChanged();
+        const footprint = reticleFootprint(layerState._viewer, alt);
+        const bounds = footprint || getViewBounds();
+        if (!bounds) return;
+        const center = footprint ? null : getFetchCenter();
+        const clamped =
+          footprint ||
+          (center
+            ? clampBoundsAroundCenter(bounds, center)
+            : clampBounds(bounds));
+        const previous = layerState._lastBounds;
+        const sameCoverage = clamped.coverage
+          ? previous?.coverage?.key === clamped.coverage.key &&
+            previous.coverage.viewKey === clamped.coverage.viewKey
+          : previous &&
+            layerState._lastViewCenter &&
+            boundsOverlap(clamped, previous, OVERLAP_THRESHOLD) &&
+            distanceKm(getBoundsCenter(clamped), layerState._lastViewCenter) <
+              MIN_CENTER_SHIFT_KM;
+        if (
+          sameCoverage &&
+          !layerState._roadPartial &&
+          !layerState._detailError &&
+          !layerState._roadError
+        ) {
+          if (
+            Math.abs(alt - layerState._lastRenderAltitude) > 100 &&
+            layerState._roads.length
+          )
+            parts.rendering.renderRoadsForAltitude(
+              layerState._roads,
+              alt,
+              'Cached zoom',
+            );
+          return;
+        }
+        return layerState._loadRoadsForBounds(clamped, alt, interactionAnchor);
+      },
+      options?.immediate === true ? 0 : FETCH_DEBOUNCE,
     );
   }
   return {