feat(traffic): Lines and Dots toggles; hosts choose which road modes they offer

createTrafficSource({ roadModes }) lets a host offer a subset of the TomTom,
OSM and Hybrid road modes (all three by default). Without OSM the layer never
draws simulated roads, and a single mode shows no road chip.

While flow is live the Street Traffic row offers Lines (every road with flow
as a steady green/amber/red line, from the heat-line renderer) and Dots (the
moving dots), saved in layer state and share links. Defaults: Lines off,
Dots on.

src/layers/traffic/rendering.js

@@ -2,6 +2,10 @@ import * as Cesium from 'cesium';
 import { flowBucket } from '../../data/trafficFlowStyle.js';
 import { trafficStyleProfile } from '../../data/trafficPresetStyle.js';
 import {
+  FLOW_BUCKET_COLORS,
+  FLOW_LINE_ALPHA,
+  FLOW_LINE_CAP,
+  FLOW_LINE_WIDTH,
   HEAT_LINE_CAP,
   HEAT_JAM_COLOR,
   HEAT_SLOW_COLOR,
@@ -34,45 +38,81 @@ export function createRendering({
       : roads;
   }
 
-  /** Remove both heat-line ground primitives from the scene. */
+  const LINE_KEYS = ['_heatJamPrim', '_heatSlowPrim', '_heatFreePrim'];
 
-  function removeHeatLines() {
-    if (layerState._heatJamPrim) {
-      layerState._viewer?.scene.groundPrimitives.remove(
-        layerState._heatJamPrim,
-      );
-      layerState._heatJamPrim = null;
-    }
-    if (layerState._heatSlowPrim) {
-      layerState._viewer?.scene.groundPrimitives.remove(
-        layerState._heatSlowPrim,
-      );
-      layerState._heatSlowPrim = null;
+  /** Detach the current line primitives, leaving them in the scene. */
+  function takeHeatLines() {
+    const taken = [];
+    for (const key of LINE_KEYS) {
+      if (layerState[key]) taken.push(layerState[key]);
+      layerState[key] = null;
     }
     layerState._heatLineCount = 0;
+    return taken;
+  }
+
+  function removePrimitives(primitives) {
+    for (const primitive of primitives)
+      layerState._viewer?.scene.groundPrimitives.remove(primitive);
+  }
+
+  /** Remove the heat-line / flow-line ground primitives from the scene. */
+
+  function removeHeatLines() {
+    removePrimitives(takeHeatLines());
+    removePrimitives(layerState._heatRetired || []);
+    layerState._heatRetired = [];
     parts.animation.syncRenderDemand?.();
   }
 
   /**
-   * Rebuild the congestion heat-line underlay (jam-viz heatline prototype):
-   * slow/jam roads drape a corridor line onto the rendered 3D tiles — glowing
-   * pulsing red for jam, faint flat amber for slow — with the dots animating
-   * on top. Two batched GroundPolylinePrimitives (one per bucket) so the jam
-   * batch pulses through one shared material. Capped at HEAT_LINE_CAP (jam
-   * first, longest first); overflow is logged. No-op in sim mode, when the
-   * heatline mode is off, or without ground-primitive support.
+   * Replaced lines stay drawn until their successors finish building
+   * (GroundPolylinePrimitive geometry is asynchronous), so a rebuild never
+   * blinks. Called every held frame.
+   */
+
+  function retireHeatLines() {
+    if (!layerState._heatRetired?.length) return;
+    if (LINE_KEYS.some((key) => layerState[key] && !layerState[key].ready))
+      return;
+    removePrimitives(layerState._heatRetired);
+    layerState._heatRetired = [];
+  }
+
+  /**
+   * Rebuild the road-line underlay drawn from live flow, in one of two looks:
+   *
+   * - Flow lines (the `lines` row toggle): every road with flow drapes a
+   *   steady line in its bucket color — green free-flow, amber slow, red jam.
+   *   Capped at FLOW_LINE_CAP.
+   * - Heat-lines (jam-viz `heatline` prototype): only slow/jam roads, a
+   *   glowing pulsing red for jam and a faint flat amber for slow. Capped at
+   *   HEAT_LINE_CAP.
+   *
+   * One batched GroundPolylinePrimitive per bucket, so the heat-line jam batch
+   * pulses through one shared material. Kept roads are jam first, then slow,
+   * then free, longest first; overflow is logged. Lines drape on 3D tiles when
+   * the globe is hidden (photoreal) and on terrain or tiles otherwise. No-op in
+   * sim mode, when both looks are off, or without ground-primitive support.
    *
    * @param {Array} roads - Road objects visible in the current render.
    */
 
   function rebuildHeatLines(roads) {
-    removeHeatLines();
+    const previous = takeHeatLines();
+    const finish = () => {
+      // Nothing new to wait for: the old lines go now.
+      if (LINE_KEYS.some((key) => layerState[key]))
+        (layerState._heatRetired ||= []).push(...previous);
+      else removePrimitives(previous);
+      parts.animation.syncRenderDemand?.();
+    };
     if (
       !layerState._viewer ||
       !layerState._liveMode ||
       !parts.style.heatlineOn()
     )
-      return;
+      return finish();
     if (layerState._heatSupported === null) {
       layerState._heatSupported = Cesium.GroundPolylinePrimitive.isSupported(
         layerState._viewer.scene,
@@ -82,22 +122,25 @@ export function createRendering({
           '[Data:Traffic] GroundPolylinePrimitive unsupported — heat-lines disabled',
         );
     }
-    if (!layerState._heatSupported) return;
+    if (!layerState._heatSupported) return finish();
 
+    const flowLines = layerState._showLines;
+    const cap = flowLines ? FLOW_LINE_CAP : HEAT_LINE_CAP;
+    const rank = { jam: 0, slow: 1, free: 2 };
     const candidates = [];
     for (const road of roads) {
       const flow = road.flow;
       if (!flow || flow.closure) continue;
       const bucket = flowBucket(flow.level);
-      if (bucket === 'free') continue;
+      if (bucket === 'free' && !flowLines) continue;
       let len = 0;
       for (const d of road.segmentDist) len += d;
       candidates.push({ road, bucket, len });
     }
     candidates.sort((a, b) =>
-      a.bucket === b.bucket ? b.len - a.len : a.bucket === 'jam' ? -1 : 1,
+      a.bucket === b.bucket ? b.len - a.len : rank[a.bucket] - rank[b.bucket],
     );
-    const kept = candidates.slice(0, HEAT_LINE_CAP);
+    const kept = candidates.slice(0, cap);
 
     const instancesFor = (bucket, width) =>
       kept
@@ -112,51 +155,72 @@ export function createRendering({
             }),
         );
 
-    // Mono presets (NVG/FLIR/noir) discard hue — heat-lines re-encode in
-    // luminance like the dots: jam = white glow, slow = faint gray.
-    const monoHeat =
+    // Mono presets (NVG/FLIR/noir) discard hue — lines re-encode in
+    // luminance like the dots: jam = white, slow = gray, free = dim gray.
+    const mono =
       layerState._presetDots === 'on' &&
       trafficStyleProfile(layerState._stylePreset) === 'mono';
-    const jamLineColor = monoHeat ? Cesium.Color.WHITE : HEAT_JAM_COLOR;
-    const slowLineColor = monoHeat
-      ? new Cesium.Color(0.7, 0.7, 0.7, HEAT_SLOW_COLOR.alpha)
-      : HEAT_SLOW_COLOR;
-
-    const jamInstances = instancesFor('jam', HEAT_LINE_JAM_WIDTH);
-    if (jamInstances.length) {
-      layerState._heatJamPrim = layerState._viewer.scene.groundPrimitives.add(
-        new Cesium.GroundPolylinePrimitive({
-          geometryInstances: jamInstances,
-          classificationType: Cesium.ClassificationType.CESIUM_3D_TILE,
-          appearance: new Cesium.PolylineMaterialAppearance({
-            material: Cesium.Material.fromType('PolylineGlow', {
-              color: jamLineColor.withAlpha(HEAT_JAM_BASE_ALPHA),
-              glowPower: 0.25,
+    const gray = (level, alpha) => new Cesium.Color(level, level, level, alpha);
+    const classificationType =
+      layerState._viewer.scene.globe?.show === false
+        ? Cesium.ClassificationType.CESIUM_3D_TILE
+        : flowLines
+          ? Cesium.ClassificationType.BOTH
+          : Cesium.ClassificationType.CESIUM_3D_TILE;
+    const add = (instances, material) =>
+      instances.length
+        ? layerState._viewer.scene.groundPrimitives.add(
+            new Cesium.GroundPolylinePrimitive({
+              geometryInstances: instances,
+              classificationType,
+              appearance: new Cesium.PolylineMaterialAppearance({ material }),
             }),
+          )
+        : null;
+
+    // Lines take the dots' active (preset-aware) colors.
+    const dotColor = (bucket) =>
+      layerState._activeBucketColors?.[bucket] || FLOW_BUCKET_COLORS[bucket];
+    if (flowLines) {
+      const lineColor = {
+        jam: mono ? gray(1, FLOW_LINE_ALPHA) : dotColor('jam'),
+        slow: mono ? gray(0.7, FLOW_LINE_ALPHA) : dotColor('slow'),
+        free: mono ? gray(0.45, FLOW_LINE_ALPHA) : dotColor('free'),
+      };
+      for (const [bucket, key] of [
+        ['free', '_heatFreePrim'],
+        ['slow', '_heatSlowPrim'],
+        ['jam', '_heatJamPrim'],
+      ])
+        layerState[key] = add(
+          instancesFor(bucket, FLOW_LINE_WIDTH),
+          Cesium.Material.fromType('Color', {
+            color: lineColor[bucket].withAlpha(FLOW_LINE_ALPHA),
           }),
+        );
+    } else {
+      const jamLineColor = mono ? Cesium.Color.WHITE : HEAT_JAM_COLOR;
+      const slowLineColor = mono
+        ? gray(0.7, HEAT_SLOW_COLOR.alpha)
+        : HEAT_SLOW_COLOR;
+      layerState._heatJamPrim = add(
+        instancesFor('jam', HEAT_LINE_JAM_WIDTH),
+        Cesium.Material.fromType('PolylineGlow', {
+          color: jamLineColor.withAlpha(HEAT_JAM_BASE_ALPHA),
+          glowPower: 0.25,
         }),
       );
-    }
-    const slowInstances = instancesFor('slow', HEAT_LINE_SLOW_WIDTH);
-    if (slowInstances.length) {
-      layerState._heatSlowPrim = layerState._viewer.scene.groundPrimitives.add(
-        new Cesium.GroundPolylinePrimitive({
-          geometryInstances: slowInstances,
-          classificationType: Cesium.ClassificationType.CESIUM_3D_TILE,
-          appearance: new Cesium.PolylineMaterialAppearance({
-            material: Cesium.Material.fromType('Color', {
-              color: slowLineColor,
-            }),
-          }),
-        }),
+      layerState._heatSlowPrim = add(
+        instancesFor('slow', HEAT_LINE_SLOW_WIDTH),
+        Cesium.Material.fromType('Color', { color: slowLineColor }),
       );
     }
 
     layerState._heatLineCount = kept.length;
-    parts.animation.syncRenderDemand?.();
+    finish();
     if (candidates.length > kept.length) {
       console.log(
-        `[Data:Traffic] Heat-lines capped at ${HEAT_LINE_CAP} (${candidates.length} congested roads in view)`,
+        `[Data:Traffic] ${flowLines ? 'Flow lines' : 'Heat-lines'} capped at ${cap} (${candidates.length} roads in view)`,
       );
     }
   }
@@ -270,7 +334,13 @@ export function createRendering({
           renderMetrics,
         )
       : null;
-    if (!label.includes('tile')) rebuildHeatLines(filteredRoads);
+    // The flow recolor above already rebuilt the lines from every retained
+    // road; without dots to recolor, rebuild them here.
+    if (
+      !label.includes('tile') &&
+      !(layerState._liveMode && layerState._dots.length)
+    )
+      rebuildHeatLines(visibleRoadsForAltitude(layerState._roads, altitude));
     if (state) {
       const heatEnd = parts.timing.trafficTimingMark(
         state,
@@ -314,6 +384,7 @@ export function createRendering({
   return {
     visibleRoadsForAltitude,
     removeHeatLines,
+    retireHeatLines,
     rebuildHeatLines,
     renderRoadsForAltitude,
   };