perf(cables): draw with batched primitives instead of entities

The layer loaded two GeoJsonDataSources and a CustomDataSource: 6,459
entities. Every enable rebuilt them (a 100-250 ms task or three and
about 1 GB of heap that stayed until the next collection), every disable
removed them in a 130-150 ms task, and each horizon sweep that showed a
landing marker made Cesium create its billboard again and read the
terrain height under it once more.

The layer now makes the primitives Cesium built from those entities
itself: one GroundPolylinePrimitive for every line, one
BillboardCollection for the point markers, one PointPrimitiveCollection
for the reference tips and one static polyline Primitive for the stems
in view, rebuilt in a worker when a sweep moves a tip. A disable hides
them and an enable shows them again, so only the first enable builds
anything. A marker is clamped to the ground once, 48 per frame as
before; after that Cesium follows the terrain within its own time budget
and hiding or showing the marker reads nothing. A map-stack change
re-classifies the lines in place.

Lines keep the distance-display attribute the entity display gave them:
with a float attribute present Cesium keeps the 2.5 px width, and
without one it is stored as a byte and drawn 2 px.

Co-Authored-By: Claude Fable 5.2 <[email protected]>

src/layers/submarineCables/surface.js

@@ -1,8 +1,5 @@
 import * as Cesium from 'cesium';
-import {
-  CABLE_GLOBE_STACK_IDS,
-  MARKER_COLLECTION_EXPECTATIONS,
-} from './policy.js';
+import { CABLE_GLOBE_STACK_IDS } from './policy.js';
 
 /**
  * Ground-line classification for one map stack. The photoreal stack renders
@@ -10,7 +7,7 @@ import {
  * 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
+ * Classifying against just the active surface halves the
  * 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.
@@ -40,87 +37,3 @@ export function cableClassificationTypeForScene(scene) {
     ? 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);
-}