refactor(geography): separate cable sources and bundled lookup modules

CHANGELOG.md

@@ -61,6 +61,8 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md
 
 - Separate radio directory loading, station selection, globe presentation and playback into composed components with an explicit metadata source.
 
+- Separate submarine cable sources and rendering components, and export bundled geography lookup modules.
+
 ### Fixed
 
 - Traffic now retries a failed destination after city navigation without a layer

docs/CURRENT-STATE.md

@@ -3303,3 +3303,18 @@ explicitly. Each constructed layer owns its catalog, audio and lifecycle state.
 Existing catalog validation, category filters, tuning and voice playback behavior
 remain unchanged. Audio connects directly to the broadcaster after an explicit
 play action; the source does not relay or record streams.
+
+## Bundled geography and submarine cable components
+
+Submarine cables use separate source, geometry, rendering, interaction and
+lifecycle modules. The layer factory accepts cable and landing-point GeoJSON
+collections from a source with `fetch(signal)` and a display label. The default
+source loads the same bundled TeleGeography files. Disabling still removes all
+three Cesium data sources; enabling rebuilds from the accepted parsed cache,
+and destroying clears it. Load ownership prevents cancelled work from adding
+entities after teardown.
+
+Natural Earth regions and neighborhood polygon lookup are package exports.
+Their existing lazy loaders, retry behavior, bundled datasets and attribution
+are unchanged. The cable dataset remains CC BY-NC-SA 3.0 and is not covered by
+the project's MIT license; see `DATA_SOURCES.md`.

package.json

@@ -156,6 +156,10 @@
     "./layers/traffic": "./src/layers/traffic/index.js",
     "./layers/bikeshare": "./src/layers/bikeshare/index.js",
     "./layers/cctv": "./src/layers/cctv/index.js",
-    "./layers/radio": "./src/layers/radio/index.js"
+    "./layers/radio": "./src/layers/radio/index.js",
+    "./layers/submarine-cables": "./src/layers/submarineCables/index.js",
+    "./sources/bundled-cables": "./src/layers/submarineCables/bundledSource.js",
+    "./geography/natural-earth": "./src/data/naturalEarthRegions.js",
+    "./geography/neighborhoods": "./src/data/neighborhoodPolygons.js"
   }
 }

scripts/format-scope.json

@@ -479,5 +479,21 @@
   "src/layers/radio/tuningNoise.js",
   "src/layers/radio/volume.js",
   "src/data/radio.js",
-  "src/layers/radio/source.test.mjs"
+  "src/layers/radio/source.test.mjs",
+  "src/layers/submarineCables/bundledSource.js",
+  "src/layers/submarineCables/geometry.js",
+  "src/layers/submarineCables/index.js",
+  "src/layers/submarineCables/ingestion.js",
+  "src/layers/submarineCables/interaction.js",
+  "src/layers/submarineCables/lifecycle.js",
+  "src/layers/submarineCables/overlay.js",
+  "src/layers/submarineCables/policy.js",
+  "src/layers/submarineCables/rendering.js",
+  "src/layers/submarineCables/state.js",
+  "src/layers/submarineCables/surface.js",
+  "src/data/telegeographySubmarineCables.js",
+  "src/data/telegeographySubmarineCables.test.mjs",
+  "src/data/naturalEarthRegions.js",
+  "src/data/neighborhoodPolygons.js",
+  "src/layers/submarineCables/bundledSource.test.mjs"
 ]

scripts/package-boundaries.json

@@ -925,5 +925,42 @@
       "src/ui/radioTunerModel.js"
     ],
     "external": ["cesium"]
+  },
+  "submarine-cables": {
+    "exports": ["./layers/submarine-cables"],
+    "modules": [
+      "src/layers/submarineCables/geometry.js",
+      "src/layers/submarineCables/index.js",
+      "src/layers/submarineCables/ingestion.js",
+      "src/layers/submarineCables/interaction.js",
+      "src/layers/submarineCables/lifecycle.js",
+      "src/layers/submarineCables/overlay.js",
+      "src/layers/submarineCables/policy.js",
+      "src/layers/submarineCables/rendering.js",
+      "src/layers/submarineCables/state.js",
+      "src/layers/submarineCables/surface.js"
+    ],
+    "external": ["cesium"]
+  },
+  "bundled-cables": {
+    "exports": ["./sources/bundled-cables"],
+    "modules": [
+      "src/layers/submarineCables/bundledSource.js",
+      "src/data/local_data/telegeography_submarine_cables/cable-geo.json",
+      "src/data/local_data/telegeography_submarine_cables/landing-point-geo.json"
+    ],
+    "external": []
+  },
+  "geography": {
+    "exports": ["./geography/natural-earth", "./geography/neighborhoods"],
+    "modules": [
+      "src/data/naturalEarthRegions.js",
+      "src/data/neighborhoodPolygons.js",
+      "src/data/retryableLoad.js",
+      "src/data/local_data/neighborhoods/san-francisco.json",
+      "src/data/local_data/natural_earth/regions.json",
+      "src/data/local_data/natural_earth/marine.json"
+    ],
+    "external": []
   }
 }

src/data/naturalEarthRegions.js

@@ -29,7 +29,8 @@ function ringAreaKm2(ring) {
   for (let i = 0; i < n; i++) {
     const [lon1, lat1] = ring[i];
     const [lon2, lat2] = ring[(i + 1) % n];
-    sum += toRad(lon2 - lon1) * (2 + Math.sin(toRad(lat1)) + Math.sin(toRad(lat2)));
+    sum +=
+      toRad(lon2 - lon1) * (2 + Math.sin(toRad(lat1)) + Math.sin(toRad(lat2)));
   }
   return Math.abs((sum * EARTH_RADIUS_KM * EARTH_RADIUS_KM) / 2);
 }
@@ -37,8 +38,9 @@ function ringAreaKm2(ring) {
 function haversineKm(lon1, lat1, lon2, lat2) {
   const dLat = toRad(lat2 - lat1);
   const dLon = toRad(lon2 - lon1);
-  const h = Math.sin(dLat / 2) ** 2
-    + Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
   return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(h)));
 }
 
@@ -62,34 +64,34 @@ function normalizeName(s) {
  * Keys and values are both in normalizeName() form.
  */
 const ALIASES = {
-  'rockies': 'rocky mountains',
-  'himalaya': 'himalayas',
+  rockies: 'rocky mountains',
+  himalaya: 'himalayas',
   'the himalaya': 'himalayas',
   'alps mountains': 'alps',
   'sahara desert': 'sahara',
-  'gobi': 'gobi desert',
-  'kalahari': 'kalahari desert',
-  'atacama': 'desierto de atacama',
+  gobi: 'gobi desert',
+  kalahari: 'kalahari desert',
+  atacama: 'desierto de atacama',
   'atacama desert': 'desierto de atacama',
   'tibetan plateau': 'plateau of tibet',
   'tibet plateau': 'plateau of tibet',
-  'appalachians': 'appalachian mts',
+  appalachians: 'appalachian mts',
   'appalachian mountains': 'appalachian mts',
-  'caucasus': 'caucasus mts',
+  caucasus: 'caucasus mts',
   'caucasus mountains': 'caucasus mts',
-  'balkans': 'balkan pen',
+  balkans: 'balkan pen',
   'balkan peninsula': 'balkan pen',
   'andes mountains': 'andes',
-  'urals': 'ural mountains',
+  urals: 'ural mountains',
   'pyrenees mountains': 'pyrenees',
   'arabian gulf': 'persian gulf',
   'gulf of arabia': 'persian gulf',
-  'mediterranean': 'mediterranean sea',
-  'caribbean': 'caribbean sea',
-  'baja': 'baja california',
-  'yucatan': 'pen de yucatan',
+  mediterranean: 'mediterranean sea',
+  caribbean: 'caribbean sea',
+  baja: 'baja california',
+  yucatan: 'pen de yucatan',
   'yucatan peninsula': 'pen de yucatan',
-  'kamchatka': 'kamchatka peninsula',
+  kamchatka: 'kamchatka peninsula',
   'sierra nevada mountains': 'sierra nevada',
 };
 
@@ -97,8 +99,13 @@ const ALIASES = {
 function suffixVariants(norm) {
   const v = [];
   // "x mountains" ↔ "x mts" (pack uses "Mts."; normalization strips the dot)
-  if (norm.endsWith(' mountains')) v.push(norm.replace(/ mountains$/, ' mts'), norm.replace(/ mountains$/, ''));
-  if (norm.endsWith(' mts')) v.push(norm.replace(/ mts$/, ' mountains'), norm.replace(/ mts$/, ''));
+  if (norm.endsWith(' mountains'))
+    v.push(
+      norm.replace(/ mountains$/, ' mts'),
+      norm.replace(/ mountains$/, ''),
+    );
+  if (norm.endsWith(' mts'))
+    v.push(norm.replace(/ mts$/, ' mountains'), norm.replace(/ mts$/, ''));
   // "x desert" ↔ "x"
   if (norm.endsWith(' desert')) v.push(norm.replace(/ desert$/, ''));
   else v.push(norm + ' desert');
@@ -117,9 +124,14 @@ async function loadPackFile(base) {
   // Vite bundles these JSON files as modules; the import attribute is what Node
   // needs to load the same files under node:test (same pattern as
   // neighborhoodPolygons.js). One path, so no node: import reaches the browser.
-  const mod = base === 'regions'
-    ? await import('./local_data/natural_earth/regions.json', { with: { type: 'json' } })
-    : await import('./local_data/natural_earth/marine.json', { with: { type: 'json' } });
+  const mod =
+    base === 'regions'
+      ? await import('./local_data/natural_earth/regions.json', {
+          with: { type: 'json' },
+        })
+      : await import('./local_data/natural_earth/marine.json', {
+          with: { type: 'json' },
+        });
   return mod.default || mod;
 }
 
@@ -129,7 +141,10 @@ function buildEntries(pack, kind) {
     const polygons = ft.polygons || [];
     if (!polygons.length) continue;
     let areaKm2 = 0;
-    let minLon = Infinity, minLat = Infinity, maxLon = -Infinity, maxLat = -Infinity;
+    let minLon = Infinity,
+      minLat = Infinity,
+      maxLon = -Infinity,
+      maxLat = -Infinity;
     for (const ring of polygons) {
       areaKm2 += ringAreaKm2(ring);
       for (const [lon, lat] of ring) {
@@ -169,10 +184,14 @@ const loadIndex = createRetryableLoader(async () => {
   ];
   const index = new Map();
   for (const entry of _entries) {
-    for (const key of new Set([normalizeName(entry.name), normalizeName(entry.namealt)])) {
+    for (const key of new Set([
+      normalizeName(entry.name),
+      normalizeName(entry.namealt),
+    ])) {
       if (!key) continue;
       const list = index.get(key);
-      if (list) list.push(entry); else index.set(key, [entry]);
+      if (list) list.push(entry);
+      else index.set(key, [entry]);
     }
   }
   // duplicate names exist in Natural Earth (e.g. two "Cordillera Oriental",
@@ -207,7 +226,11 @@ export async function findNaturalRegion(query) {
   const norm = normalizeName(query);
   if (!norm) return null;
   const index = await loadIndex();
-  const candidates = [norm, ALIASES[norm], ...suffixVariants(ALIASES[norm] || norm)];
+  const candidates = [
+    norm,
+    ALIASES[norm],
+    ...suffixVariants(ALIASES[norm] || norm),
+  ];
   for (const key of candidates) {
     if (!key) continue;
     const list = index.get(key);
@@ -248,8 +271,8 @@ export function pointInRing(ring, lat, lon) {
   for (let i = 0, j = ring.length - 1; i < ring.length; j = i, i += 1) {
     const [xi, yi] = ring[i];
     const [xj, yj] = ring[j];
-    const intersects = (yi > lat) !== (yj > lat)
-      && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi;
+    const intersects =
+      yi > lat !== yj > lat && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi;
     if (intersects) inside = !inside;
   }
   return inside;
@@ -274,7 +297,11 @@ export async function lookupNaturalRegionOutline(query, lat, lon) {
   const norm = normalizeName(query);
   if (!norm || !Number.isFinite(lat) || !Number.isFinite(lon)) return null;
   const index = await loadIndex();
-  const candidates = [norm, ALIASES[norm], ...suffixVariants(ALIASES[norm] || norm)];
+  const candidates = [
+    norm,
+    ALIASES[norm],
+    ...suffixVariants(ALIASES[norm] || norm),
+  ];
   const seen = new Set();
   for (const key of candidates) {
     if (!key || seen.has(key)) continue;

src/data/neighborhoodPolygons.js

@@ -14,7 +14,14 @@ import { createRetryableLoader } from './retryableLoad.js';
 
 // bbox = [west, south, east, north]; only load a city file when the point falls in its box.
 const CITY_FILES = [
-  { id: 'san-francisco', bbox: [-122.55, 37.70, -122.35, 37.84], loader: () => import('./local_data/neighborhoods/san-francisco.json', { with: { type: 'json' } }) },
+  {
+    id: 'san-francisco',
+    bbox: [-122.55, 37.7, -122.35, 37.84],
+    loader: () =>
+      import('./local_data/neighborhoods/san-francisco.json', {
+        with: { type: 'json' },
+      }),
+  },
 ];
 
 /**
@@ -27,7 +34,11 @@ const CITY_FILES = [
 const _cityLoaders = new Map();
 
 function normalize(s) {
-  return String(s || '').toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').replace(/\s+/g, ' ').trim();
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
 }
 
 /**
@@ -45,10 +56,12 @@ const NAME_ALIASES = new Map([
 function pointInRing(lon, lat, ring) {
   let inside = false;
   for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
-    const xi = ring[i][0]; const yi = ring[i][1];
-    const xj = ring[j][0]; const yj = ring[j][1];
-    const intersect = ((yi > lat) !== (yj > lat))
-      && (lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi);
+    const xi = ring[i][0];
+    const yi = ring[i][1];
+    const xj = ring[j][0];
+    const yj = ring[j][1];
+    const intersect =
+      yi > lat !== yj > lat && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi;
     if (intersect) inside = !inside;
   }
   return inside;
@@ -70,7 +83,10 @@ function containingOuterRing(feature, lon, lat) {
     if (!pointInRing(lon, lat, outer)) continue;
     let inHole = false;
     for (let h = 1; h < poly.length; h++) {
-      if (pointInRing(lon, lat, poly[h])) { inHole = true; break; }
+      if (pointInRing(lon, lat, poly[h])) {
+        inHole = true;
+        break;
+      }
     }
     if (!inHole) return outer;
   }
@@ -108,7 +124,10 @@ async function loadCity(city) {
   } catch (error) {
     // The caller falls back to the live resolver ladder, which looks exactly
     // like "no bundled coverage" — say so once, out loud, instead.
-    console.warn(`[neighborhoods] ${city.id} pack unavailable:`, error?.message || error);
+    console.warn(
+      `[neighborhoods] ${city.id} pack unavailable:`,
+      error?.message || error,
+    );
     return [];
   }
 }
@@ -122,7 +141,13 @@ async function loadCity(city) {
  *   neighborhood name, or null when the point isn't in a covered city / no match.
  */
 export async function lookupNeighborhoodRing(lat, lon, matchName) {
-  const city = CITY_FILES.find((c) => lon >= c.bbox[0] && lat >= c.bbox[1] && lon <= c.bbox[2] && lat <= c.bbox[3]);
+  const city = CITY_FILES.find(
+    (c) =>
+      lon >= c.bbox[0] &&
+      lat >= c.bbox[1] &&
+      lon <= c.bbox[2] &&
+      lat <= c.bbox[3],
+  );
   if (!city) return null;
   const feats = await loadCity(city);
   if (!feats.length) return null;
@@ -153,11 +178,18 @@ export async function lookupNeighborhoodRing(lat, lon, matchName) {
     const containRing = containingOuterRing(f, lon, lat);
     const ring = containRing || largestOuterRing(f.geometry);
     if (!ring) continue;
-    const cand = { ring, name: f.properties.name, contains: !!containRing, fwordCount: fWords.length };
+    const cand = {
+      ring,
+      name: f.properties.name,
+      contains: !!containRing,
+      fwordCount: fWords.length,
+    };
     // Prefer a feature that CONTAINS the point, then the most specific name (most words).
-    if (!best
-      || (cand.contains && !best.contains)
-      || (cand.contains === best.contains && cand.fwordCount > best.fwordCount)) {
+    if (
+      !best ||
+      (cand.contains && !best.contains) ||
+      (cand.contains === best.contains && cand.fwordCount > best.fwordCount)
+    ) {
       best = cand;
     }
   }

src/layers/submarineCables/bundledSource.js

@@ -0,0 +1,42 @@
+// This dataset is CC BY-NC-SA 3.0, not the project's MIT license.
+// Commercial users must remove it or obtain a TeleGeography license.
+// See DATA_SOURCES.md and the bundled dataset's source.json.
+const cableUrl = new URL(
+  '../../data/local_data/telegeography_submarine_cables/cable-geo.json',
+  import.meta.url,
+).href;
+const landingPointUrl = new URL(
+  '../../data/local_data/telegeography_submarine_cables/landing-point-geo.json',
+  import.meta.url,
+).href;
+
+/** Supply GeoJSON collections without coupling the renderer to asset URLs. */
+export function createBundledCableSource({
+  fetchImpl = (...args) => fetch(...args),
+} = {}) {
+  async function read(url, signal) {
+    signal?.throwIfAborted();
+    const response = await fetchImpl(url, { signal, cache: 'force-cache' });
+    if (!response.ok) {
+      try {
+        await response.body?.cancel();
+      } catch {
+        /* best effort */
+      }
+      throw new Error(`HTTP ${response.status} for ${url}`);
+    }
+    const json = await response.json();
+    signal?.throwIfAborted();
+    return json;
+  }
+  return {
+    label: 'TeleGeography',
+    async fetch(signal) {
+      const [cables, landingPoints] = await Promise.all([
+        read(cableUrl, signal),
+        read(landingPointUrl, signal),
+      ]);
+      return { cables, landingPoints };
+    },
+  };
+}

src/layers/submarineCables/bundledSource.test.mjs

@@ -0,0 +1,34 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createBundledCableSource } from './bundledSource.js';
+
+test('a failed bundled response releases its body', async () => {
+  let released = 0;
+  const source = createBundledCableSource({
+    fetchImpl: async () => ({
+      ok: false,
+      status: 503,
+      body: {
+        cancel: async () => {
+          released++;
+        },
+      },
+    }),
+  });
+  await assert.rejects(source.fetch(), /HTTP 503/);
+  assert.equal(released, 2);
+});
+
+test('cancellation during JSON parsing cannot return a late snapshot', async () => {
+  const controller = new AbortController();
+  const source = createBundledCableSource({
+    fetchImpl: async () => ({
+      ok: true,
+      async json() {
+        controller.abort();
+        return { type: 'FeatureCollection', features: [] };
+      },
+    }),
+  });
+  await assert.rejects(source.fetch(controller.signal), { name: 'AbortError' });
+});

src/layers/submarineCables/geometry.js

@@ -0,0 +1,79 @@
+export function featureReference(feature) {
+  const geometry = feature?.geometry;
+  if (!geometry) return null;
+
+  const props = feature?.properties || {};
+  const propertyCoords = coordsFromProperty(props.coordinates);
+  if (propertyCoords) {
+    return {
+      lon: propertyCoords[0],
+      lat: propertyCoords[1],
+    };
+  }
+
+  if (geometry.type === 'Point') {
+    const coords = coordsFromPoint(geometry.coordinates);
+    if (!coords) return null;
+    return { lon: coords[0], lat: coords[1] };
+  }
+
+  const coords = [];
+  collectLonLat(geometry.coordinates, coords);
+  if (!coords.length) return null;
+
+  let lonSum = 0;
+  let latSum = 0;
+  for (const [lon, lat] of coords) {
+    lonSum += lon;
+    latSum += lat;
+  }
+  return {
+    lon: lonSum / coords.length,
+    lat: latSum / coords.length,
+  };
+}
+
+export function coordsFromProperty(value) {
+  if (!Array.isArray(value) || value.length < 2) return null;
+  const lon = Number(value[0]);
+  const lat = Number(value[1]);
+  if (!Number.isFinite(lon) || !Number.isFinite(lat)) return null;
+  return [lon, lat];
+}
+
+export function coordsFromPoint(value) {
+  if (!Array.isArray(value) || value.length < 2) return null;
+  const lon = Number(value[0]);
+  const lat = Number(value[1]);
+  if (!Number.isFinite(lon) || !Number.isFinite(lat)) return null;
+  return [lon, lat];
+}
+
+export function collectLonLat(value, out) {
+  if (!Array.isArray(value)) return;
+  if (typeof value[0] === 'number' && typeof value[1] === 'number') {
+    const lon = Number(value[0]);
+    const lat = Number(value[1]);
+    if (Number.isFinite(lon) && Number.isFinite(lat)) {
+      out.push([lon, lat]);
+    }
+    return;
+  }
+  for (const child of value) collectLonLat(child, out);
+}
+
+export function featureLabel(feature) {
+  const props = feature?.properties || {};
+  return String(props.name || props.id || feature?.id || '').trim();
+}
+
+export function normalizeFeatures(json, kind) {
+  const features = Array.isArray(json?.features) ? json.features : [];
+  return features.map((feature, index) => {
+    const id = feature?.properties?.id || feature?.id || `${kind}-${index}`;
+    return {
+      ...feature,
+      id: String(id),
+    };
+  });
+}

src/layers/submarineCables/index.js

@@ -0,0 +1,53 @@
+import { createState } from './state.js';
+import { createLifecycle } from './lifecycle.js';
+import { defaultSweepClock } from './policy.js';
+import { createRendering } from './rendering.js';
+import { createIngestion } from './ingestion.js';
+import { createInteraction } from './interaction.js';
+export function createSubmarineCableLayer({
+  source,
+  overlayHost,
+  screenSpaceEventHandlerFactory,
+  mapStackEventTarget = null,
+  sweepClock = defaultSweepClock,
+}) {
+  if (!source?.fetch || !source.label)
+    throw new TypeError(
+      'A cable source with a label and fetch(signal) is required',
+    );
+  const state = createState({ overlayHost, sweepClock });
+  const parts = {};
+  const context = {
+    state,
+    parts,
+    source,
+    screenSpaceEventHandlerFactory,
+    mapStackEventTarget,
+  };
+  parts.rendering = createRendering(context);
+  parts.ingestion = createIngestion(context);
+  parts.interaction = createInteraction(context);
+  return createLifecycle(context);
+}
+export {
+  selectCableReferenceLabelWinners,
+  cableReferencePriority,
+  createCableOverlayEntry,
+  createCableOverlayPublisher,
+  createCableReferenceSweepGate,
+  updateCableReferenceStem,
+} from './overlay.js';
+export {
+  cableClassificationTypeForStack,
+  cableClassificationTypeForScene,
+  applyTranslucentMarkerBlend,
+} from './surface.js';
+export {
+  CABLE_REFERENCE_LABEL_WINNER_CAP,
+  CABLE_OVERLAY_SOURCE_ID,
+  CABLE_OVERLAY_COLLISION_CAPACITY,
+  CABLE_STEM_TIP_EPSILON_M,
+  CABLE_SWEEP_MOTION_PROBE_INTERVAL_MS,
+  CABLE_SWEEP_MOTION_EPSILON_M,
+  CABLE_LABEL_DEPTH_DECISION,
+} from './policy.js';

src/layers/submarineCables/ingestion.js

@@ -0,0 +1,210 @@
+import {
+  featureLabel,
+  featureReference,
+  normalizeFeatures,
+} from './geometry.js';
+import * as Cesium from 'cesium';
+
+export function createIngestion({ state, parts, source }) {
+  async function load(viewer) {
+    if (state._loading || state._loaded) return;
+
+    state._loading = true;
+    state._error = null;
+    state._loadingLabel = 'loading...';
+    // Ownership token (the militaryAwareness activationId pattern): a
+    // disable/abort followed by a fresh enable starts a NEWER load while this
+    // one is still settling. The stale load must bail after every await and
+    // must never touch shared lifecycle state or the viewer it no longer
+    // owns — clearing `_loading`/`_abort` for the successor is how duplicate
+    // or post-destroy data sources got added.
+    const generation = ++state._loadGeneration;
+    const abort = new AbortController();
+    state._abort = abort;
+    const owns = () =>
+      generation === state._loadGeneration && !abort.signal.aborted;
+
+    try {
+      let cableJson = state._cachedCableJson;
+      let landingJson = state._cachedLandingJson;
+      if (!cableJson || !landingJson) {
+        ({ cables: cableJson, landingPoints: landingJson } = await source.fetch(
+          abort.signal,
+        ));
+        if (!owns()) return;
+        if (
+          !Array.isArray(cableJson?.features) ||
+          !Array.isArray(landingJson?.features)
+        ) {
+          throw new TypeError(
+            'A cable source must return cables and landingPoints GeoJSON collections',
+          );
+        }
+        state._cachedCableJson = cableJson;
+        state._cachedLandingJson = landingJson;
+      }
+
+      const cableFeatures = normalizeFeatures(cableJson, 'cable');
+      const landingFeatures = normalizeFeatures(landingJson, 'landing');
+
+      const cableDataSource = await Cesium.GeoJsonDataSource.load(
+        { type: 'FeatureCollection', features: cableFeatures },
+        {
+          clampToGround: true,
+          stroke: state.cableColor.withAlpha(0.95),
+          fill: state.cableColor.withAlpha(0.18),
+          strokeWidth: 2,
+          markerColor: state.cableColor,
+          markerSize: 6,
+        },
+      );
+      if (!owns()) return;
+      const landingDataSource = await Cesium.GeoJsonDataSource.load(
+        { type: 'FeatureCollection', features: landingFeatures },
+        {
+          clampToGround: true,
+          stroke: state.landingColor.withAlpha(0.9),
+          fill: state.landingColor.withAlpha(0.35),
+          strokeWidth: 2,
+          markerColor: state.landingColor,
+          markerSize: 6,
+        },
+      );
+      if (!owns()) return;
+
+      cableDataSource.name = `${source.label} Submarine Cables`;
+      landingDataSource.name = `${source.label} Landing Points`;
+      const referenceDataSource = new Cesium.CustomDataSource(
+        `${source.label} Cable References`,
+      );
+      const addedSources = [
+        cableDataSource,
+        landingDataSource,
+        referenceDataSource,
+      ];
+
+      // dataSources.add() is itself an await point: Cesium mutates the
+      // collection on a DEFERRED tick, so a disable/destroy racing this
+      // window finds nothing to remove and the adds still materialize
+      // afterwards. Await every add to settlement (allSettled so a partial
+      // failure cannot leave an unawaited add materializing later), then
+      // re-check ownership. Pinned teardown mechanism: disable/destroy never
+      // wait for in-flight adds — the stale generation's own post-await
+      // check here guarantees cleanup by removing exactly the sources THIS
+      // generation added.
+      const addResults = await Promise.allSettled([
+        viewer.dataSources.add(cableDataSource),
+        viewer.dataSources.add(landingDataSource),
+        viewer.dataSources.add(referenceDataSource),
+      ]);
+      const rejectedAdd = addResults.find(
+        (result) => result.status === 'rejected',
+      );
+      if (!owns() || rejectedAdd) {
+        // Compensate: every add has settled by now, so removal is effective
+        // (a remove inside the deferred window would have been a no-op).
+        // Remove EVERY generation-local source regardless of settle status:
+        // Cesium's add() pushes into the collection BEFORE raising
+        // dataSourceAdded, so a REJECTED add may still have landed its
+        // mutation. remove() of a never-added source is a harmless no-op.
+        for (const source of addedSources) {
+          try {
+            viewer.dataSources.remove(source, true);
+          } catch {
+            /* collection gone */
+          }
+        }
+        if (owns() && rejectedAdd) throw rejectedAdd.reason;
+        return;
+      }
+
+      // Await-free commit: the viewer accepted all three sources and this
+      // load still owns the lifecycle.
+      state._cableDataSource = cableDataSource;
+      state._landingDataSource = landingDataSource;
+      state._referenceDataSource = referenceDataSource;
+
+      const cableEntities = state._cableDataSource.entities.values;
+      const landingEntities = state._landingDataSource.entities.values;
+      state._pickByEntity = new WeakMap();
+      state._referenceRecords = [];
+      state._surfaceRecords = [];
+
+      cableEntities.forEach((entity, index) => {
+        const feature = cableFeatures[index];
+        const reference = featureReference(feature);
+        if (!reference) return;
+
+        parts.rendering.styleCableEntity(entity, feature);
+        parts.interaction.registerPickEntity(entity, {
+          kind: 'cable',
+          reference,
+          label: featureLabel(feature),
+        });
+        state._surfaceRecords.push({
+          entity,
+          base: Cesium.Cartesian3.fromDegrees(reference.lon, reference.lat, 0),
+        });
+        parts.rendering.addReferenceStem({
+          reference,
+          label: featureLabel(feature),
+          kind: 'cable',
+          color: state.cableColor,
+          feature,
+        });
+      });
+
+      landingEntities.forEach((entity, index) => {
+        const feature = landingFeatures[index];
+        const reference = featureReference(feature);
+        if (!reference) return;
+
+        parts.rendering.styleLandingEntity(entity, feature);
+        parts.interaction.registerPickEntity(entity, {
+          kind: 'landing-point',
+          reference,
+          label: featureLabel(feature),
+        });
+        state._surfaceRecords.push({
+          entity,
+          base: Cesium.Cartesian3.fromDegrees(reference.lon, reference.lat, 0),
+        });
+        parts.rendering.addReferenceStem({
+          reference,
+          label: featureLabel(feature),
+          kind: 'landing-point',
+          color: state.landingColor,
+          feature,
+        });
+      });
+
+      state._count = cableFeatures.length + landingFeatures.length;
+      state._loaded = true;
+      state._lastUpdate = Date.now();
+      state._loadingLabel = '';
+      parts.rendering.updateVisibility();
+      state._referenceSweepGate.markDirty();
+      viewer.scene.requestRender?.();
+    } catch (error) {
+      // A stale or aborted load reports nothing: its failure belongs to a
+      // lifecycle the user already left.
+      if (owns() && error?.name !== 'AbortError') {
+        state._error = error?.message || 'TeleGeography load failed';
+        console.warn(
+          '[Data:telegeography-submarine-cables]',
+          state._error,
+          error,
+        );
+      }
+    } finally {
+      // Only the OWNING load may clear the shared lifecycle. A stale load
+      // clearing `_loading`/`_abort` would hand a later enable/update a
+      // duplicate load while the real one is still in flight.
+      if (generation === state._loadGeneration) {
+        state._loading = false;
+        if (state._abort === abort) state._abort = null;
+      }
+    }
+  }
+  return { load };
+}

src/layers/submarineCables/interaction.js

@@ -0,0 +1,75 @@
+import * as Cesium from 'cesium';
+
+export function createInteraction({ state, screenSpaceEventHandlerFactory }) {
+  function registerPickEntity(entity, info) {
+    entity.__gevTeleGeography = info;
+    state._pickByEntity.set(entity, info);
+  }
+
+  function beginInteraction(viewer) {
+    if (state._clickHandler) return;
+    state._clickHandler = screenSpaceEventHandlerFactory(viewer.scene.canvas);
+    state._clickHandler.setInputAction((click) => {
+      if (!state._enabled) return;
+      const picked = viewer.scene.pick(click.position);
+      const record = resolvePickRecord(picked);
+      if (!record?.reference) return;
+      flyToReference(viewer, record.reference);
+    }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+  }
+
+  function resolvePickRecord(picked) {
+    if (!picked) return null;
+    const primitive = picked.primitive;
+    if (primitive) {
+      const primitiveInfo = state._pickByEntity.get(primitive);
+      if (primitiveInfo) return primitiveInfo;
+      if (primitive.__gevTeleGeography) return primitive.__gevTeleGeography;
+      if (
+        primitive.id &&
+        typeof primitive.id === 'object' &&
+        primitive.id.reference
+      ) {
+        return primitive.id;
+      }
+    }
+
+    const entity = picked.id;
+    if (entity) {
+      const entityInfo = state._pickByEntity.get(entity);
+      if (entityInfo) return entityInfo;
+      if (entity.__gevTeleGeography) return entity.__gevTeleGeography;
+      if (entity.id && typeof entity.id === 'object' && entity.id.reference) {
+        return entity.id;
+      }
+    }
+
+    return null;
+  }
+
+  function flyToReference(viewer, reference) {
+    if (!viewer || !reference) return;
+    const destination = Cesium.Cartesian3.fromDegrees(
+      reference.lon,
+      reference.lat,
+      6500,
+    );
+    viewer.camera.cancelFlight();
+    viewer.camera.flyTo({
+      destination,
+      orientation: {
+        heading: viewer.camera.heading || 0,
+        pitch: Cesium.Math.toRadians(-52),
+        roll: 0,
+      },
+      duration: 1.35,
+      easingFunction: Cesium.EasingFunction.CUBIC_IN_OUT,
+    });
+  }
+  return {
+    registerPickEntity,
+    beginInteraction,
+    resolvePickRecord,
+    flyToReference,
+  };
+}

src/layers/submarineCables/lifecycle.js

@@ -0,0 +1,156 @@
+import {
+  cableClassificationTypeForScene,
+  cableClassificationTypeForStack,
+} from './surface.js';
+
+export function createLifecycle({ state, parts, source, mapStackEventTarget }) {
+  return {
+    id: 'telegeography-submarine-cables',
+    name: 'Submarine Cables',
+    icon: '≋',
+    source: source.label,
+    updateInterval: 0,
+    statsRefreshInterval: 500,
+
+    init(viewer) {
+      state._viewer = viewer;
+      state._classificationType = cableClassificationTypeForScene(
+        viewer?.scene,
+      );
+      if (!state._mapStackListener && mapStackEventTarget?.addEventListener) {
+        state._mapStackListener = (event) => {
+          parts.rendering.applyCableClassification(
+            event?.detail?.activeId
+              ? cableClassificationTypeForStack(event.detail.activeId)
+              : cableClassificationTypeForScene(state._viewer?.scene),
+          );
+        };
+        mapStackEventTarget.addEventListener(
+          'gev:map-stack-changed',
+          state._mapStackListener,
+        );
+      }
+      parts.interaction.beginInteraction(viewer);
+      if (!state._preRenderRemover) {
+        state._preRenderRemover = viewer.scene.preRender.addEventListener(
+          () => {
+            // The camera is handed to the gate so tracked/orbit cameras — which
+            // never emit moveEnd — reach the motion fallback. No render is
+            // requested for a fallback sweep: it only fires while the camera is
+            // already moving, so frames are flowing by construction.
+            if (
+              !state._enabled ||
+              !state._loaded ||
+              !state._referenceSweepGate.shouldRun(viewer.camera)
+            )
+              return;
+            parts.rendering.updateReferenceVisibility();
+          },
+        );
+      }
+      if (!state._moveEndRemover) {
+        state._moveEndRemover = viewer.camera.moveEnd.addEventListener(() => {
+          if (!state._enabled) return;
+          state._referenceSweepGate.markDirty();
+          viewer.scene.requestRender?.();
+        });
+      }
+    },
+
+    enable(viewer) {
+      state._enabled = true;
+      parts.rendering.updateVisibility();
+      state._overlayPublisher.show();
+      // A hide() cleared the host source, so an identical cohort must still
+      // republish on the next sweep.
+      parts.rendering.resetPublishSignature();
+      state._referenceSweepGate.markDirty();
+      // The gate is dirty-only; ask for the frame its sweep needs in case the
+      // camera is parked and nothing else is rendering.
+      (viewer || state._viewer)?.scene?.requestRender?.();
+      void parts.ingestion.load(viewer || state._viewer);
+    },
+
+    disable() {
+      state._enabled = false;
+      state._overlayPublisher.hide();
+      parts.rendering.resetPublishSignature();
+      if (state._loading && state._abort) {
+        state._abort.abort();
+        state._loading = false;
+        state._loadingLabel = '';
+      }
+      // Free the entities rather than hide them; enable() rebuilds from the
+      // cached JSON. An in-flight load's own post-await ownership check
+      // removes whatever that stale generation adds later.
+      parts.rendering.releaseDataSources(state._viewer);
+    },
+
+    update(viewer) {
+      return parts.ingestion.load(viewer || state._viewer);
+    },
+
+    destroy(viewer) {
+      if (state._abort) state._abort.abort();
+      parts.rendering.releaseDataSources(viewer || state._viewer);
+      state._cachedCableJson = null;
+      state._cachedLandingJson = null;
+      // hide() clears every published host entry and goes invisible while
+      // keeping the publisher reusable — the legacy layer supported re-init
+      // after destroy, and hidden publishers already drop late publishes.
+      // Pinned by the direct-destroy host test: removing this line leaves a
+      // visible overlay source with orphan labels.
+      state._overlayPublisher.hide();
+      if (state._clickHandler) {
+        state._clickHandler.destroy();
+        state._clickHandler = null;
+      }
+      if (state._preRenderRemover) {
+        state._preRenderRemover();
+        state._preRenderRemover = null;
+      }
+      if (state._moveEndRemover) {
+        state._moveEndRemover();
+        state._moveEndRemover = null;
+      }
+      if (state._mapStackListener && mapStackEventTarget?.removeEventListener) {
+        mapStackEventTarget.removeEventListener(
+          'gev:map-stack-changed',
+          state._mapStackListener,
+        );
+        state._mapStackListener = null;
+      }
+      state._viewer = null;
+      state._enabled = false;
+      state._loading = false;
+      state._loaded = false;
+      state._count = 0;
+      state._error = null;
+      state._lastUpdate = null;
+      state._loadingLabel = '';
+      state._cableDataSource = null;
+      state._landingDataSource = null;
+      state._referenceDataSource = null;
+      state._referenceRecords = [];
+      state._surfaceRecords = [];
+      state._pickByEntity = new WeakMap();
+      state._referenceLabelCount = 0;
+      state._publishScratch.length = 0;
+      state._markerBlendDone = false;
+      state._markerBlendInvariantWarned = false;
+      parts.rendering.resetPublishSignature();
+      state._referenceSweepGate.reset();
+    },
+
+    getStats() {
+      return {
+        count: state._count,
+        lastUpdate: state._lastUpdate,
+        loading: state._loading,
+        loadingLabel: state._loadingLabel,
+        error: state._error,
+        referenceLabelCount: state._referenceLabelCount,
+      };
+    },
+  };
+}

src/layers/submarineCables/overlay.js

@@ -0,0 +1,309 @@
+import * as Cesium from 'cesium';
+import {
+  CABLE_REFERENCE_LABEL_WINNER_CAP,
+  CABLE_REFERENCE_LABEL_MAX_DISTANCE_M,
+  BASE_CABLE_COLOR,
+  BASE_LANDING_COLOR,
+  CABLE_OVERLAY_SOURCE_ID,
+  CABLE_OVERLAY_COLLISION_CAPACITY,
+  defaultSweepClock,
+  CABLE_SWEEP_MOTION_PROBE_INTERVAL_MS,
+  CABLE_SWEEP_MOTION_EPSILON_M,
+  STEM_TARGET_PX,
+  CABLE_STEM_TIP_EPSILON_SQ,
+} from './policy.js';
+
+/**
+ * Select the nearest visible cable references without exceeding the bounded
+ * cohort cap the shared host is offered.
+ * @param {object[]} records Records annotated with `visible` and `distanceM`.
+ * @param {number} [limit]
+ * @returns {object[]}
+ */
+
+export function selectCableReferenceLabelWinners(
+  records,
+  limit = CABLE_REFERENCE_LABEL_WINNER_CAP,
+) {
+  const cap = Math.max(
+    0,
+    Math.min(CABLE_REFERENCE_LABEL_WINNER_CAP, Math.floor(Number(limit) || 0)),
+  );
+  if (!Array.isArray(records) || cap === 0) return [];
+  return records
+    .filter(
+      (record) =>
+        record?.visible === true &&
+        record.label &&
+        Number.isFinite(record.distanceM) &&
+        record.distanceM <= CABLE_REFERENCE_LABEL_MAX_DISTANCE_M,
+    )
+    .sort(
+      (a, b) =>
+        a.distanceM - b.distanceM ||
+        String(a.entity?.id || '').localeCompare(String(b.entity?.id || '')),
+    )
+    .slice(0, cap);
+}
+
+/**
+ * Distance-derived arbiter priority. Quantized to 50 km buckets so a slowly
+ * moving camera does not reshuffle equal-rank labels on every sweep; nearer
+ * references still win collisions, matching the shipped nearest-first feel.
+ * @param {number} distanceM
+ * @returns {number}
+ */
+
+export function cableReferencePriority(distanceM) {
+  const distance = Number.isFinite(distanceM)
+    ? Math.max(0, distanceM)
+    : CABLE_REFERENCE_LABEL_MAX_DISTANCE_M;
+  return 1000 - Math.round(distance / 50000);
+}
+
+/**
+ * Build one shared-host ambient label for a cable or landing-point reference.
+ * The entry stays attached to the record's mutable stem-tip Cartesian and is
+ * created once per record; only `priority` is refreshed per sweep.
+ * `interactive: false` follows the infrastructure precedent — the depth-tested
+ * native point/stem/line remains the click surface, and a non-interactive
+ * label keeps the host's per-frame accessibility/hit sync allocation-free.
+ * @param {object} record Reference record ({ id, kind, label, tip }).
+ * @returns {object}
+ */
+
+export function createCableOverlayEntry(record) {
+  const kind = record?.kind === 'landing-point' ? 'landing-point' : 'cable';
+  return {
+    id: String(record?.id || ''),
+    position: record?.tip,
+    variant: 'label',
+    title: String(record?.label || ''),
+    accent: kind === 'cable' ? BASE_CABLE_COLOR : BASE_LANDING_COLOR,
+    priority: cableReferencePriority(record?.distanceM),
+    collisionGroup: 'ambient-label',
+    paintLane: 'ambient-label',
+    interactive: false,
+    minDistance: 0,
+    maxDistance: CABLE_REFERENCE_LABEL_MAX_DISTANCE_M,
+    distanceFadeStartRatio: 0.7,
+    // Former native scaleByDistance curve, unchanged: 1.0× at 250 km → 0.62×
+    // at 9,000 km.
+    distanceScale: {
+      near: 250000,
+      nearValue: 1,
+      far: 9000000,
+      farValue: 0.62,
+    },
+    edgeFade: 'keyhole',
+    horizonCull: true,
+    terrainOcclusion: false,
+    gapPx: 14,
+    verticalOnly: true,
+    placement: 'above',
+  };
+}
+
+/**
+ * Bind the cable layer's host visibility and entry lifecycle to the shared
+ * world overlay (same contract as the infrastructure publisher). The layer
+ * supports re-init after destroy (legacy contract), so its teardown path is
+ * hide() — clear the published source and go invisible while staying
+ * reusable. There is deliberately no permanent-destroy method: a hidden
+ * publisher already drops late publishes until the next show().
+ * @param {object} [options]
+ * @param {string} [options.sourceId]
+ * @param {object} [options.host] Test seam for the three host lifecycle calls.
+ * @returns {{show:function():void,publish:function(object[]):void,hide:function():void}}
+ */
+
+export function createCableOverlayPublisher({
+  sourceId = CABLE_OVERLAY_SOURCE_ID,
+  host,
+} = {}) {
+  let visible = false;
+  let published = false;
+  const sourceOptions = {
+    cohortLimit: CABLE_REFERENCE_LABEL_WINNER_CAP,
+    collisionCapacity: CABLE_OVERLAY_COLLISION_CAPACITY,
+    moving: false,
+  };
+
+  return {
+    show() {
+      if (visible) return;
+      visible = true;
+      host.setVisible(sourceId, true);
+    },
+    publish(entries) {
+      if (!visible) return;
+      host.setEntries(sourceId, entries, sourceOptions);
+      published = entries.length > 0;
+    },
+    hide() {
+      if (published) host.clearSource(sourceId);
+      if (visible) host.setVisible(sourceId, false);
+      visible = false;
+      published = false;
+    },
+  };
+}
+
+/**
+ * Dirty gate for the reference sweep. TWO dirty conditions, no timer:
+ *
+ * 1. EVENT (primary): the sweep runs on the first frame after a camera
+ *    `moveEnd`, layer enable, or load completion. The former 500 ms timer
+ *    path re-sized stems while frames were flowing, and every re-size
+ *    rebuilt the 2,629-instance batched translucent stem primitive
+ *    (measured: 12 rebuilds in 6 s with the replacement primitive unready
+ *    for 46/360 frames — the felt hitch). Stem lengths are therefore
+ *    deliberately stale mid-drag/mid-flight and settle on release;
+ *    reference visibility and label winners go stale the same way, and the
+ *    shared host keeps reprojecting the published positions per frame.
+ * 2. MOTION FALLBACK: `moveEnd` covers drags, one-shot `setView`, and voice
+ *    `flyTo`, but a TRACKED-entity follow camera or an orbit never emits it,
+ *    so condition 1 alone starves those sessions forever (frozen horizon
+ *    visibility, frozen stems, stale label winners for as long as tracking
+ *    lasts). While frames render, the gate therefore samples the camera at
+ *    most once per `CABLE_SWEEP_MOTION_PROBE_INTERVAL_MS` and re-arms itself
+ *    only when the camera has actually travelled past
+ *    `CABLE_SWEEP_MOTION_EPSILON_M` since the last sweep.
+ *
+ * A PARKED camera still costs exactly zero sweeps: the probe compares against
+ * the last swept position (never the previous frame), so neither a frozen
+ * camera nor sub-epsilon numeric jitter ever accumulates into a sweep, and
+ * the per-frame cost of the fallback is one clock read plus one subtraction.
+ * Position is the only motion channel because it is the only camera input the
+ * sweep consumes — the horizon occluder, the reference distances, the stem
+ * sizing, and the winner ranks all derive from `positionWC` alone, so a
+ * heading-only rotation cannot change a single sweep output and deliberately
+ * does not spend one.
+ * @param {object} [options]
+ * @param {function():number} [options.now] Monotonic clock (test seam).
+ * @param {number} [options.probeIntervalMs]
+ * @param {number} [options.motionEpsilonM]
+ */
+
+export function createCableReferenceSweepGate({
+  now = defaultSweepClock,
+  probeIntervalMs = CABLE_SWEEP_MOTION_PROBE_INTERVAL_MS,
+  motionEpsilonM = CABLE_SWEEP_MOTION_EPSILON_M,
+} = {}) {
+  const motionEpsilonSq = motionEpsilonM ** 2;
+  // Preallocated: the probe clones into it, so a moving camera allocates
+  // nothing per frame.
+  const lastSweptPosition = new Cesium.Cartesian3();
+  let hasSweptPosition = false;
+  let dirty = true;
+  let lastProbeAt = -Infinity;
+
+  /** Arm the next probe window and adopt the camera position being swept. */
+  function accept(camera, time) {
+    lastProbeAt = time;
+    const position = camera?.positionWC;
+    hasSweptPosition = Boolean(position);
+    if (position) Cesium.Cartesian3.clone(position, lastSweptPosition);
+    return true;
+  }
+
+  return {
+    markDirty() {
+      dirty = true;
+    },
+    /**
+     * @param {Cesium.Camera} [camera] Live camera; omit to disable the motion
+     *   fallback entirely (pure dirty-only gate).
+     * @returns {boolean}
+     */
+    shouldRun(camera) {
+      if (dirty) {
+        dirty = false;
+        return accept(camera, now());
+      }
+      if (!camera) return false;
+      // Cheapest possible per-frame path: a clock read and a subtraction. The
+      // camera getter is only touched once the probe window has actually
+      // opened, and the window re-arms whether or not the probe sweeps.
+      const time = now();
+      if (time - lastProbeAt < probeIntervalMs) return false;
+      lastProbeAt = time;
+      const position = camera.positionWC;
+      if (!position) return false;
+      if (
+        hasSweptPosition &&
+        Cesium.Cartesian3.distanceSquared(position, lastSweptPosition) <=
+          motionEpsilonSq
+      ) {
+        return false;
+      }
+      return accept(camera, time);
+    },
+    reset() {
+      dirty = true;
+      lastProbeAt = -Infinity;
+      hasSweptPosition = false;
+    },
+  };
+}
+
+/**
+ * Recompute one staticized stem on the sweep cadence. Replaces the former
+ * per-frame `CallbackProperty` pair: constant properties are redefined only
+ * when the camera-scaled tip moved beyond the settle epsilon, and the two
+ * preallocated position buffers alternate so each real change raises exactly
+ * one geometry notification (the localGeojson double-buffer pattern).
+ * @param {object} record Reference record with entity/base/tip/nextTip/buffers.
+ * @param {Cesium.Cartesian3} cameraPositionWC
+ * @param {number} canvasHeight CSS-pixel canvas height.
+ * @param {number} fov Camera frustum field of view (radians).
+ * @returns {boolean} True when the stem geometry was redefined.
+ */
+
+export function updateCableReferenceStem(
+  record,
+  cameraPositionWC,
+  canvasHeight,
+  fov,
+) {
+  const distance = Cesium.Cartesian3.distance(cameraPositionWC, record.base);
+  const effectiveDistance = Math.max(distance, 5000);
+  const height = canvasHeight || 1080;
+  const fieldOfView = fov || Math.PI / 3;
+  const metersPerPixelFactor = (2 * Math.tan(fieldOfView / 2)) / height;
+  const tipHeight = Math.max(
+    700,
+    Math.min(85000, effectiveDistance * metersPerPixelFactor * STEM_TARGET_PX),
+  );
+  Cesium.Cartesian3.fromDegrees(
+    record.reference.lon,
+    record.reference.lat,
+    tipHeight,
+    Cesium.Ellipsoid.WGS84,
+    record.nextTip,
+  );
+  if (
+    Cesium.Cartesian3.distanceSquared(record.tip, record.nextTip) <=
+    CABLE_STEM_TIP_EPSILON_SQ
+  ) {
+    return false;
+  }
+  Cesium.Cartesian3.clone(record.nextTip, record.tip);
+  record.stemPositionBufferIndex = 1 - record.stemPositionBufferIndex;
+  const stemPositions =
+    record.stemPositionBuffers[record.stemPositionBufferIndex];
+  stemPositions[0] = record.base;
+  stemPositions[1] = record.tip;
+  record.entity.position.setValue(record.tip);
+  record.entity.polyline.positions.setValue(stemPositions);
+  return true;
+}
+
+export function clampLabel(value, maxLength = 34) {
+  const text = String(value || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!text) return '';
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, Math.max(1, maxLength - 3))}...`;
+}

src/layers/submarineCables/policy.js

@@ -0,0 +1,109 @@
+import * as Cesium from 'cesium';
+
+export const BASE_CABLE_COLOR = '#39d5ff';
+
+export const BASE_LANDING_COLOR = '#8fffd2';
+
+export const STEM_TARGET_PX = 66;
+
+export const CABLE_REFERENCE_LABEL_MAX_DISTANCE_M = 9000000;
+
+/** Bounded nearest-visible cohort the layer offers the shared host. */
+
+export const CABLE_REFERENCE_LABEL_WINNER_CAP = 160;
+
+/** Shared world-overlay source id (matches the layer id). */
+
+export const CABLE_OVERLAY_SOURCE_ID = 'telegeography-submarine-cables';
+
+/** Shared ambient-label paint budget, matching the infrastructure sources. */
+
+export const CABLE_OVERLAY_COLLISION_CAPACITY = 96;
+
+/** Ignore sub-metre camera-derived stem-tip noise at camera settle. */
+
+export const CABLE_STEM_TIP_EPSILON_M = 0.5;
+
+export const CABLE_STEM_TIP_EPSILON_SQ = CABLE_STEM_TIP_EPSILON_M ** 2;
+
+/**
+ * Motion-fallback probe window. Cameras that never emit `moveEnd` (tracked
+ * entities, orbits) would otherwise starve the dirty-only sweep forever, so
+ * the gate samples camera motion at most this often while frames render.
+ */
+
+export const CABLE_SWEEP_MOTION_PROBE_INTERVAL_MS = 2000;
+
+/**
+ * Camera displacement that counts as meaningful motion for that probe. Stem
+ * tip height is ~8.5% of camera distance at the shipped 66 px target, so
+ * 250 m of camera travel moves a tip ~21 m; below that the frozen sweep is
+ * visually indistinguishable and `moveEnd` settles it exactly.
+ */
+
+export const CABLE_SWEEP_MOTION_EPSILON_M = 250;
+
+/**
+ * Phase-5 depth decision, REVISED 2026-08-18: Option 2. Cable reference text
+ * now renders in the shared world-overlay host (horizon-cull + keyhole fade,
+ * no per-label tile depth test), superseding the 2026-08-02 Option-1 native
+ * `LabelGraphics` exception. The native path evaluated 2 `CallbackProperty`
+ * channels per reference entity per frame (5,258 across the 2,629-reference
+ * dataset) and re-batched a 160-label `LabelCollection` on every sweep — the
+ * layer alone cost ~9.5 ms/frame during camera motion. The depth cue this
+ * trades away (photoreal tiles occluding label TEXT at low, city-level
+ * cameras) matches the sibling dams/datacenters sources, which shipped
+ * host-composited under the same ruling; the anchor points/stems remain
+ * Cesium-native and depth-tested. See
+ * the world-overlay consolidation design notes ("Depth-testing
+ * decision") for both dated decisions.
+ */
+
+export const CABLE_LABEL_DEPTH_DECISION = Object.freeze({
+  option: 2,
+  decidedAt: '2026-08-18',
+  supersedes: '2026-08-02',
+  depthTested: false,
+});
+
+/**
+ * `MAP_STACKS` ids that render imagery on the SHOWN Cesium globe (the ion
+ * Bing stacks + OSM). Deliberately an explicit allowlist, not "anything that
+ * is not photoreal": an id this module has never heard of is UNKNOWN, and
+ * unknown must reach the documented BOTH fallback rather than being asserted
+ * onto the terrain surface. A stack added to `MAP_STACKS` without being added
+ * here therefore degrades to the safe pre-optimization behavior (visible on
+ * every surface) instead of vanishing — and the per-stack unit test walks the
+ * real `MAP_STACKS` so the omission is caught loudly.
+ */
+
+export const CABLE_GLOBE_STACK_IDS = Object.freeze(
+  new Set(['bing-aerial', 'bing-labels', 'esri-imagery', 'osm']),
+);
+
+/** EntityCluster's private marker collections and their required types. */
+
+export const MARKER_COLLECTION_EXPECTATIONS = Object.freeze([
+  Object.freeze({
+    key: '_billboardCollection',
+    type: Cesium.BillboardCollection,
+  }),
+  Object.freeze({
+    key: '_pointCollection',
+    type: Cesium.PointPrimitiveCollection,
+  }),
+]);
+
+/**
+ * Monotonic clock for the sweep gate's motion probe. A hoisted declaration:
+ * the module's `export default createTeleGeographySubmarineCableLayer()`
+ * runs before this point in source order.
+ * @returns {number}
+ */
+
+export function defaultSweepClock() {
+  return typeof performance === 'object' &&
+    typeof performance.now === 'function'
+    ? performance.now()
+    : Date.now();
+}

src/layers/submarineCables/rendering.js

@@ -0,0 +1,274 @@
+import * as Cesium from 'cesium';
+import {
+  probeTranslucentMarkerBlend,
+  commitTranslucentMarkerBlend,
+} from './surface.js';
+import {
+  clampLabel,
+  createCableOverlayEntry,
+  updateCableReferenceStem,
+  selectCableReferenceLabelWinners,
+  cableReferencePriority,
+} from './overlay.js';
+
+export function createRendering({ state }) {
+  function resetPublishSignature() {
+    state._lastPublishedIds.length = 0;
+    state._lastPublishedPriorities.length = 0;
+    state._lastPublishedCount = -1;
+  }
+
+  /**
+   * Remove the three data sources from the viewer and forget the built
+   * entities. Hiding them (`show = false`) is NOT enough: Cesium's
+   * DataSourceDisplay still walks every visualizer of a hidden source on
+   * every frame, and the thousands of hidden polylines/billboards keep
+   * costing CPU and GC pressure long after the user toggled the layer off —
+   * that is the "everything gets sluggish after I turn layers off" report.
+   * The fetched JSON stays cached, so the next enable rebuilds without a
+   * network round trip or a re-parse.
+   */
+
+  function releaseDataSources(viewer) {
+    const sources = [
+      state._cableDataSource,
+      state._landingDataSource,
+      state._referenceDataSource,
+    ];
+    state._cableDataSource = null;
+    state._landingDataSource = null;
+    state._referenceDataSource = null;
+    state._referenceRecords = [];
+    state._surfaceRecords = [];
+    state._pickByEntity = new WeakMap();
+    state._referenceLabelCount = 0;
+    state._publishScratch.length = 0;
+    // The blend pass targets the collections being dropped; the rebuilt
+    // sources need their own pass.
+    state._markerBlendDone = false;
+    state._loaded = false;
+    state._referenceSweepGate.reset();
+    for (const source of sources) {
+      if (!source) continue;
+      try {
+        viewer?.dataSources?.remove(source, true);
+      } catch {
+        /* collection gone */
+      }
+    }
+  }
+
+  function updateVisibility() {
+    if (state._cableDataSource) state._cableDataSource.show = state._enabled;
+    if (state._landingDataSource)
+      state._landingDataSource.show = state._enabled;
+    if (state._referenceDataSource)
+      state._referenceDataSource.show = state._enabled;
+  }
+
+  function styleCableEntity(entity, feature) {
+    if (!entity?.polyline) return;
+    const color = feature?.properties?.color
+      ? Cesium.Color.fromCssColorString(String(feature.properties.color))
+      : state.cableColor;
+    entity.polyline.material = color.withAlpha(0.92);
+    entity.polyline.width = 2.5;
+    entity.polyline.clampToGround = true;
+    entity.polyline.classificationType = state._classificationType;
+    entity.show = true;
+  }
+
+  /**
+   * Apply the single translucent blend pass to the landing-billboard and
+   * reference-point collections. Landing entities carry only billboards and
+   * reference entities only points, so completion is one applied collection
+   * per source; a failed shape probe disables the optimization permanently
+   * for this session and says so loudly in dev builds.
+   * Both sources are probed BEFORE either is committed, so the helper's
+   * "defaults untouched on shape drift" fallback holds across the pair too —
+   * a reference-source failure can never leave the landing source already
+   * forced to TRANSLUCENT.
+   */
+
+  function applyMarkerBlendOnce() {
+    const landing = probeTranslucentMarkerBlend(state._landingDataSource);
+    const reference = probeTranslucentMarkerBlend(state._referenceDataSource);
+    if (landing.invariantFailed || reference.invariantFailed) {
+      state._markerBlendDone = true;
+      if (!state._markerBlendInvariantWarned && import.meta.env?.DEV === true) {
+        state._markerBlendInvariantWarned = true;
+        console.error(
+          '[Data:telegeography-submarine-cables] EntityCluster marker-collection ' +
+            'shape changed — single-pass translucent blend skipped; markers fall ' +
+            "back to Cesium's default two-pass blend.",
+        );
+      }
+      return;
+    }
+    const landingBlend = commitTranslucentMarkerBlend(landing);
+    const referenceBlend = commitTranslucentMarkerBlend(reference);
+    if (landingBlend.applied > 0 && referenceBlend.applied > 0)
+      state._markerBlendDone = true;
+  }
+
+  /**
+   * Re-classify every cable ground line for the active surface. One batched
+   * ground-primitive rebuild per stack switch — never per frame.
+   * @param {Cesium.ClassificationType} next
+   */
+
+  function applyCableClassification(next) {
+    if (next === undefined || next === state._classificationType) return;
+    state._classificationType = next;
+    if (!state._cableDataSource) return;
+    const entities = state._cableDataSource.entities.values;
+    for (let i = 0; i < entities.length; i++) {
+      const polyline = entities[i].polyline;
+      if (polyline) polyline.classificationType = next;
+    }
+    state._viewer?.scene?.requestRender?.();
+  }
+
+  function styleLandingEntity(entity, feature) {
+    if (!entity?.point) return;
+    entity.point.color = state.landingColor.withAlpha(0.92);
+    entity.point.pixelSize = feature?.properties?.is_tbd ? 6 : 7;
+    entity.point.outlineColor = state.cableOutline;
+    entity.point.outlineWidth = 1;
+    entity.point.disableDepthTestDistance = 0;
+    entity.show = true;
+  }
+
+  function addReferenceStem({ reference, label, kind, color, feature }) {
+    if (!state._referenceDataSource || !reference) return;
+
+    const base = Cesium.Cartesian3.fromDegrees(reference.lon, reference.lat, 0);
+    const tip = Cesium.Cartesian3.fromDegrees(
+      reference.lon,
+      reference.lat,
+      2500,
+    );
+    const info = {
+      kind,
+      reference,
+      label,
+      featureId: feature?.id || feature?.properties?.id || null,
+    };
+    const pointColor = color.withAlpha(kind === 'cable' ? 0.84 : 0.94);
+    const stemColor = color.withAlpha(kind === 'cable' ? 0.58 : 0.68);
+    // Constant properties on the sweep cadence, never per-frame callbacks:
+    // the sweep redefines them through the alternating buffers below.
+    const stemPositionBuffers = [
+      [base, tip],
+      [base, tip],
+    ];
+
+    const entity = state._referenceDataSource.entities.add({
+      id: `${kind}-reference-${state._referenceRecords.length}-${info.featureId || 'feature'}`,
+      position: tip,
+      polyline: {
+        positions: stemPositionBuffers[0],
+        width: kind === 'cable' ? 2 : 2.4,
+        material: new Cesium.ColorMaterialProperty(stemColor),
+      },
+      point: {
+        pixelSize: kind === 'cable' ? 7 : 8,
+        color: pointColor,
+        outlineColor: Cesium.Color.BLACK.withAlpha(0.65),
+        outlineWidth: 1,
+        disableDepthTestDistance: 0,
+      },
+    });
+
+    entity.__gevTeleGeography = info;
+    state._pickByEntity.set(entity, info);
+    const record = {
+      id: entity.id,
+      entity,
+      base,
+      tip,
+      nextTip: Cesium.Cartesian3.clone(tip),
+      stemPositionBuffers,
+      stemPositionBufferIndex: 0,
+      reference,
+      kind,
+      label: clampLabel(label),
+      visible: false,
+      distanceM: Infinity,
+      entry: null,
+    };
+    record.entry = createCableOverlayEntry(record);
+    state._referenceRecords.push(record);
+  }
+
+  function updateReferenceVisibility() {
+    if (!state._enabled || !state._viewer?.camera) return;
+    const cameraPos = state._viewer.camera.positionWC;
+    if (!cameraPos) return;
+
+    const canvasHeight = state._viewer.scene?.canvas?.clientHeight || 1080;
+    const fov = state._viewer.camera.frustum?.fov || Math.PI / 3;
+    const occluder = new Cesium.EllipsoidalOccluder(
+      Cesium.Ellipsoid.WGS84,
+      cameraPos,
+    );
+    for (const record of state._referenceRecords) {
+      const visible = occluder.isPointVisible(record.base);
+      record.visible = visible;
+      record.distanceM = Cesium.Cartesian3.distance(cameraPos, record.base);
+      if (record.entity.show !== visible) {
+        record.entity.show = visible;
+      }
+      // Hidden stems keep their last geometry; this same sweep refreshes them
+      // in the pass where they turn visible again.
+      if (visible)
+        updateCableReferenceStem(record, cameraPos, canvasHeight, fov);
+    }
+    for (const record of state._surfaceRecords) {
+      const visible = occluder.isPointVisible(record.base);
+      if (record.entity.show !== visible) {
+        record.entity.show = visible;
+      }
+    }
+    const winners = selectCableReferenceLabelWinners(state._referenceRecords);
+    let changed = winners.length !== state._lastPublishedCount;
+    for (let i = 0; i < winners.length; i++) {
+      const record = winners[i];
+      const priority = cableReferencePriority(record.distanceM);
+      record.entry.priority = priority;
+      state._publishScratch[i] = record.entry;
+      if (
+        !changed &&
+        (state._lastPublishedIds[i] !== record.entry.id ||
+          state._lastPublishedPriorities[i] !== priority)
+      ) {
+        changed = true;
+      }
+    }
+    state._publishScratch.length = winners.length;
+    state._referenceLabelCount = winners.length;
+    // The marker collections are created lazily by the visualizers, so the
+    // single-pass blend is applied on the sweep cadence until both landed.
+    if (!state._markerBlendDone) applyMarkerBlendOnce();
+    if (!changed) return;
+    state._overlayPublisher.publish(state._publishScratch);
+    state._lastPublishedCount = winners.length;
+    for (let i = 0; i < winners.length; i++) {
+      state._lastPublishedIds[i] = state._publishScratch[i].id;
+      state._lastPublishedPriorities[i] = state._publishScratch[i].priority;
+    }
+    state._lastPublishedIds.length = winners.length;
+    state._lastPublishedPriorities.length = winners.length;
+  }
+  return {
+    resetPublishSignature,
+    releaseDataSources,
+    updateVisibility,
+    styleCableEntity,
+    applyMarkerBlendOnce,
+    applyCableClassification,
+    styleLandingEntity,
+    addReferenceStem,
+    updateReferenceVisibility,
+  };
+}

src/layers/submarineCables/state.js

@@ -0,0 +1,107 @@
+import * as Cesium from 'cesium';
+import {
+  createCableReferenceSweepGate,
+  createCableOverlayPublisher,
+} from './overlay.js';
+import { BASE_CABLE_COLOR, BASE_LANDING_COLOR } from './policy.js';
+
+export function createState({ sweepClock, overlayHost }) {
+  const state = {};
+
+  state._viewer = null;
+
+  state._enabled = false;
+
+  state._loading = false;
+
+  state._loaded = false;
+
+  state._count = 0;
+
+  state._error = null;
+
+  state._lastUpdate = null;
+
+  state._loadingLabel = '';
+
+  state._abort = null;
+
+  /** Monotonic load-ownership token; every load() start claims a new one. */
+
+  state._loadGeneration = 0;
+
+  state._cableDataSource = null;
+
+  state._landingDataSource = null;
+
+  state._referenceDataSource = null;
+
+  /**
+   * Fetched cable/landing JSON kept across disable/enable. A disable RELEASES
+   * the three data sources (see releaseDataSources) instead of hiding them,
+   * so a re-enable has to rebuild the entities; the network/parse half of
+   * that rebuild is the expensive part users would notice, so it is cached.
+   */
+
+  state._cachedCableJson = null;
+
+  state._cachedLandingJson = null;
+
+  state._referenceRecords = [];
+
+  state._surfaceRecords = [];
+
+  state._clickHandler = null;
+
+  state._preRenderRemover = null;
+
+  state._moveEndRemover = null;
+
+  state._mapStackListener = null;
+
+  /** Active ground-line classification; refined from live scene state at init. */
+
+  state._classificationType = Cesium.ClassificationType.BOTH;
+
+  /** True once both marker collections blend translucent (or the shape probe failed). */
+
+  state._markerBlendDone = false;
+
+  state._markerBlendInvariantWarned = false;
+
+  state._pickByEntity = new WeakMap();
+
+  state._referenceLabelCount = 0;
+
+  state._referenceSweepGate = createCableReferenceSweepGate({
+    now: sweepClock,
+  });
+
+  state._overlayPublisher = createCableOverlayPublisher({ host: overlayHost });
+
+  /** Reused winner→entry scratch so a 2 Hz sweep allocates no arrays. */
+
+  state._publishScratch = [];
+
+  /**
+   * Last published cohort signature (ids + quantized priorities). A parked
+   * camera reproduces the same winners every sweep; skipping the identical
+   * republish keeps the host from requesting a render per publish, so the
+   * layer stays render-governor idle exactly like its native predecessor.
+   * Tip positions need no republish either: the host reprojects the same
+   * mutable Cartesians on every painted frame.
+   */
+
+  state._lastPublishedIds = [];
+
+  state._lastPublishedPriorities = [];
+
+  state._lastPublishedCount = -1;
+
+  state.cableColor = Cesium.Color.fromCssColorString(BASE_CABLE_COLOR);
+
+  state.cableOutline = Cesium.Color.BLACK.withAlpha(0.45);
+
+  state.landingColor = Cesium.Color.fromCssColorString(BASE_LANDING_COLOR);
+  return state;
+}

src/layers/submarineCables/surface.js

@@ -0,0 +1,126 @@
+import * as Cesium from 'cesium';
+import {
+  CABLE_GLOBE_STACK_IDS,
+  MARKER_COLLECTION_EXPECTATIONS,
+} from './policy.js';
+
+/**
+ * Ground-line classification for one map stack. The photoreal stack renders
+ * Google 3D tiles with the Cesium globe HIDDEN, so cable ground lines only
+ * need the 3D-tile classification pass there; every other known stack (the
+ * bing stacks and osm) renders imagery on the shown globe, so only the
+ * terrain pass applies.
+ * Classifying against just the active surface halves the batched
+ * GroundPolylinePrimitive's emitted command sets. BOTH is the safe fallback
+ * for an unknown stack — it renders on every surface, exactly the shipped
+ * pre-optimization behavior.
+ * @param {string|null|undefined} activeId MapStackController stack id.
+ * @returns {Cesium.ClassificationType}
+ */
+
+export function cableClassificationTypeForStack(activeId) {
+  if (activeId === 'photoreal') return Cesium.ClassificationType.CESIUM_3D_TILE;
+  if (CABLE_GLOBE_STACK_IDS.has(activeId))
+    return Cesium.ClassificationType.TERRAIN;
+  return Cesium.ClassificationType.BOTH;
+}
+
+/**
+ * Derive the active surface from live scene state. The boot-time
+ * `setStack(..., { silent: true })` fires no 'gev:map-stack-changed' event,
+ * so the initial classification reads the scene the way the height-datum
+ * listeners do: the photoreal regime is exactly "globe hidden".
+ * @param {Cesium.Scene|null|undefined} scene
+ * @returns {Cesium.ClassificationType}
+ */
+
+export function cableClassificationTypeForScene(scene) {
+  if (!scene?.globe) return Cesium.ClassificationType.BOTH;
+  return scene.globe.show === false
+    ? Cesium.ClassificationType.CESIUM_3D_TILE
+    : Cesium.ClassificationType.TERRAIN;
+}
+
+/**
+ * Validate one data source's marker collections WITHOUT mutating anything.
+ * Splitting validation from mutation is what makes the fallback honest: a
+ * shape failure on the SECOND collection (or the second data source) must
+ * not leave the first one already forced to TRANSLUCENT.
+ * @param {Cesium.DataSource|null|undefined} dataSource
+ * @returns {{ready:object[],pending:number,invariantFailed:boolean}}
+ */
+
+export function probeTranslucentMarkerBlend(dataSource) {
+  const cluster = dataSource?.clustering;
+  if (!cluster) return { ready: [], pending: 0, invariantFailed: true };
+  const ready = [];
+  let pending = 0;
+  let invariantFailed = false;
+  for (const { key, type } of MARKER_COLLECTION_EXPECTATIONS) {
+    if (!(key in cluster)) {
+      invariantFailed = true;
+      continue;
+    }
+    const collection = cluster[key];
+    if (collection === undefined || collection === null) {
+      pending++;
+      continue;
+    }
+    if (!(collection instanceof type) || !('blendOption' in collection)) {
+      invariantFailed = true;
+      continue;
+    }
+    ready.push(collection);
+  }
+  // Any failure discards every collected target: nothing is mutated at all.
+  if (invariantFailed) return { ready: [], pending: 0, invariantFailed: true };
+  return { ready, pending, invariantFailed: false };
+}
+
+/**
+ * Commit a clean probe. Only ever called once every probe in the batch has
+ * passed, so this cannot land a partial application.
+ * @param {{ready:object[],pending:number}} probe
+ * @returns {{applied:number,pending:number,invariantFailed:boolean}}
+ */
+
+export function commitTranslucentMarkerBlend(probe) {
+  for (const collection of probe.ready) {
+    if (collection.blendOption !== Cesium.BlendOption.TRANSLUCENT) {
+      collection.blendOption = Cesium.BlendOption.TRANSLUCENT;
+    }
+  }
+  return {
+    applied: probe.ready.length,
+    pending: probe.pending,
+    invariantFailed: false,
+  };
+}
+
+/**
+ * Force one translucent draw pass for a data source's marker collections.
+ * The default `OPAQUE_AND_TRANSLUCENT` blend emits two draw commands per
+ * collection, and every cable marker is translucent (alpha < 1), so the
+ * opaque pass is pure overhead across 1,917 landing billboards + 2,629
+ * reference points. Cesium has no public accessor for the entity-backed
+ * collections, so this reaches through EntityCluster's private fields under
+ * a SHAPE INVARIANT the caller must honor loudly: the constructor
+ * pre-assigns `_billboardCollection`/`_pointCollection` (= undefined until a
+ * visualizer lazily creates them), so a missing PROPERTY means Cesium's
+ * shape changed — report `invariantFailed` and never touch anything —
+ * while a present-but-undefined value only means "not created yet"
+ * (`pending`). Wrong instance types also fail the invariant. The cables
+ * sources never enable clustering, so created collections persist.
+ * VALIDATE-ALL-THEN-MUTATE-ALL: every field/type check runs before the first
+ * assignment, so a failure anywhere leaves BOTH collections on Cesium's
+ * default blend — the fallback this helper promises.
+ * @param {Cesium.DataSource|null|undefined} dataSource
+ * @returns {{applied:number,pending:number,invariantFailed:boolean}}
+ */
+
+export function applyTranslucentMarkerBlend(dataSource) {
+  const probe = probeTranslucentMarkerBlend(dataSource);
+  if (probe.invariantFailed)
+    return { applied: 0, pending: 0, invariantFailed: true };
+  return commitTranslucentMarkerBlend(probe);
+}