fix(graph): close plan-review gaps before the RC cut

Review of phases 1-9 against plans/graph-ux-motion-and-api.md surfaced
six deviations; all fixed here.

- warmup now defaults ON (100 ticks / 250ms budget) as the plan and
  migrating-v8 specify; omitted `layout.warmup` previously resolved to 0
  ticks, so the default entrance revealed the explosive first frames and
  the fitBounds spread bypass never engaged
- edgeStyle domains go through resolveCategoricalDomain, so `sort` and
  `scale.domain` order dash styles instead of first-seen data order
- provider-form camera flights (zoomToNode) keep following the tracked
  node after the flight converges, until sim alpha settles below 0.05
- onCameraChange now fires for user pan/zoom and instant fits, not just
  programmatic flights - its stated purpose is camera persistence and
  zoom UIs without polling
- React StrictMode dev remounts play the entrance again: suppression now
  keys on changed mount deps, not a survives-cleanup boolean ref
- update() churn counts edges added between two survivors, and the
  visual-only gate compares edge multisets (duplicate edges)

Claude-Session: https://claude.ai/code/session_016rS7hi2g4bSzRBfnD1p2ji

Author: rileyhilliard

packages/engine/src/graphs/__tests__/encoding.test.ts

@@ -372,6 +372,35 @@ describe('resolveEdgeVisuals', () => {
       expect(fourthEdge.style).toBe('solid');
     });
 
+    it('assigns styles in ascending label order regardless of data order', () => {
+      const styledEdges: GraphEdge[] = [
+        { source: 'a', target: 'b', kind: 'zeta' },
+        { source: 'b', target: 'c', kind: 'alpha' },
+        { source: 'a', target: 'c', kind: 'mid' },
+      ];
+      const edges = resolveEdgeVisuals(styledEdges, { edgeStyle: { field: 'kind' } }, theme);
+
+      // Sorted domain [alpha, mid, zeta] → solid, dashed, dotted.
+      expect(edges.find((e) => e.data.kind === 'alpha')!.style).toBe('solid');
+      expect(edges.find((e) => e.data.kind === 'mid')!.style).toBe('dashed');
+      expect(edges.find((e) => e.data.kind === 'zeta')!.style).toBe('dotted');
+    });
+
+    it('sort: null keeps first-seen data order for style assignment', () => {
+      const styledEdges: GraphEdge[] = [
+        { source: 'a', target: 'b', kind: 'zeta' },
+        { source: 'b', target: 'c', kind: 'alpha' },
+      ];
+      const edges = resolveEdgeVisuals(
+        styledEdges,
+        { edgeStyle: { field: 'kind', sort: null } },
+        theme,
+      );
+
+      expect(edges.find((e) => e.data.kind === 'zeta')!.style).toBe('solid');
+      expect(edges.find((e) => e.data.kind === 'alpha')!.style).toBe('dashed');
+    });
+
     it('defaults to solid when no edgeStyle encoding', () => {
       const edges = resolveEdgeVisuals(basicEdges, {}, theme);
 

packages/engine/src/graphs/__tests__/graph-resolvers.test.ts

@@ -248,6 +248,17 @@ describe('layout presets + seed + highlight', () => {
     expect(r.simulationConfig.warmupBudgetMs).toBe(250);
   });
 
+  it('warmup defaults ON when omitted (100 ticks)', () => {
+    const r = compileGraph(base, compileOptions);
+    expect(r.simulationConfig.warmupTicks).toBe(100);
+    expect(r.simulationConfig.warmupBudgetMs).toBe(250);
+  });
+
+  it('warmup: false disables warmup', () => {
+    const r = compileGraph({ ...base, layout: { type: 'force', warmup: false } }, compileOptions);
+    expect(r.simulationConfig.warmupTicks).toBe(0);
+  });
+
   it('captures nodeColor.highlight into initialHighlight against the resolved domain', () => {
     const r = compileGraph(
       { ...base, encoding: { nodeColor: { field: 'g', type: 'nominal', highlight: ['X'] } } },

packages/engine/src/graphs/compile-graph.ts

@@ -417,8 +417,7 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
   };
 
   // 10. Build simulation config. Energy/settle presets provide defaults; raw
-  // layout fields (chargeStrength, and the non-spec alphaDecay/velocityDecay)
-  // always win over a preset.
+  // layout fields (chargeStrength) always win over a preset.
   const collisionPadding = graphSpec.layout.collisionPadding ?? 2;
   const maxRadius =
     compiledNodes.length > 0
@@ -432,14 +431,16 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
     ? SETTLE_PRESETS[graphSpec.layout.settle]
     : SETTLE_PRESETS.balanced;
 
-  // Warmup: true → defaults, number → explicit tick count, false/undefined → 0.
+  // Warmup defaults ON: undefined/true → default ticks, number → explicit tick
+  // count, false → 0. It lives in layout (not animation) so `animation: false`
+  // still gets the off-screen settle instead of the explosive first frames.
   const warmupRaw = graphSpec.layout.warmup;
   const warmupTicks =
-    warmupRaw === true
-      ? DEFAULT_WARMUP_TICKS
+    warmupRaw === false
+      ? 0
       : typeof warmupRaw === 'number'
         ? Math.max(0, Math.floor(warmupRaw))
-        : 0;
+        : DEFAULT_WARMUP_TICKS;
 
   const simulationConfig: SimulationConfig = {
     chargeStrength: graphSpec.layout.chargeStrength ?? energyPreset.chargeStrength,

packages/engine/src/graphs/encoding.ts

@@ -410,10 +410,14 @@ export function resolveEdgeVisuals(
   let styleFn: ((edge: GraphEdge) => 'solid' | 'dashed' | 'dotted') | undefined;
   if (encoding.edgeStyle?.field) {
     const field = encoding.edgeStyle.field;
-    const uniqueValues = [...new Set(edges.map((e) => String(e[field] ?? '')))];
+    const domain = resolveCategoricalDomain(
+      edges.map((e) => String(e[field] ?? '')),
+      encoding.edgeStyle.sort,
+      encoding.edgeStyle.scale?.domain,
+    );
     const styleMap = new Map<string, 'solid' | 'dashed' | 'dotted'>();
-    for (let i = 0; i < uniqueValues.length; i++) {
-      styleMap.set(uniqueValues[i], EDGE_STYLES[i % EDGE_STYLES.length]);
+    for (let i = 0; i < domain.length; i++) {
+      styleMap.set(domain[i], EDGE_STYLES[i % EDGE_STYLES.length]);
     }
     styleFn = (edge: GraphEdge) => styleMap.get(String(edge[field] ?? '')) ?? 'solid';
   }

packages/react/src/Graph.tsx

@@ -131,9 +131,13 @@ export const Graph = forwardRef<GraphHandle, GraphProps>(function Graph(
   const containerRef = useRef<HTMLDivElement>(null);
   const graphRef = useRef<GraphInstance | null>(null);
   const specRef = useRef<string>('');
-  // First run of the mount effect plays the entrance; subsequent runs (theme/
-  // darkMode/structural-tooltip/legend change — all spec-unchanged) suppress it.
-  const mountedOnceRef = useRef(false);
+  // Deps of the previous mount-effect run. A recreation with CHANGED deps
+  // (theme/darkMode/structural-tooltip/legend — all spec-unchanged) suppresses
+  // the entrance; identical deps mean a StrictMode dev replay of the same
+  // mount, which must still play the entrance. A survives-cleanup boolean ref
+  // can't tell those apart — it would suppress the entrance in every
+  // StrictMode app.
+  const prevMountDepsRef = useRef<unknown[] | null>(null);
 
   // Store event handlers AND function-valued options in refs so they don't
   // trigger graph recreation. Inline functions create new references every
@@ -287,6 +291,14 @@ export const Graph = forwardRef<GraphHandle, GraphProps>(function Graph(
       ? { formatter: stableTooltipFormatter }
       : false;
 
+    // Suppress the entrance only when a PREVIOUS mount existed and a dep
+    // actually changed (theme/darkMode/structural option — spec unchanged).
+    // Identical deps = StrictMode's dev remount of the same graph: play it.
+    const mountDeps: unknown[] = [theme, resolvedDarkMode, tooltipOn, legendKey, fitOnLoad];
+    const prevDeps = prevMountDepsRef.current;
+    const suppressEntrance =
+      prevDeps !== null && mountDeps.some((d, i) => !Object.is(d, prevDeps[i]));
+
     const options: GraphMountOptions = {
       theme,
       darkMode: resolvedDarkMode,
@@ -303,14 +315,12 @@ export const Graph = forwardRef<GraphHandle, GraphProps>(function Graph(
       onHighlightChange: stableOnHighlightChange,
       onCameraChange: stableOnCameraChange,
       responsive: true,
-      // First mount plays the entrance; theme/darkMode-only recreations suppress
-      // it so the reveal doesn't replay on an unchanged spec.
-      suppressEntrance: mountedOnceRef.current,
+      suppressEntrance,
     };
 
     graphRef.current = createGraph(container, spec, options);
     specRef.current = JSON.stringify(spec);
-    mountedOnceRef.current = true;
+    prevMountDepsRef.current = mountDeps;
 
     return () => {
       graphRef.current?.destroy();

packages/react/src/__tests__/Graph.suppress-entrance.test.tsx

@@ -9,7 +9,7 @@
 
 import type { GraphSpec } from '@opendata-ai/openchart-core';
 import { cleanup, render, waitFor } from '@testing-library/react';
-import { createRef } from 'react';
+import { createRef, StrictMode } from 'react';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 // A stub GraphInstance whose methods we can assert against.
@@ -75,6 +75,19 @@ describe('<Graph /> suppressEntrance', () => {
     expect(secondOpts.suppressEntrance).toBe(true);
   });
 
+  it('StrictMode dev remount still plays the entrance (identical deps, no suppression)', async () => {
+    render(
+      <StrictMode>
+        <Graph spec={spec} />
+      </StrictMode>,
+    );
+    // StrictMode runs mount → cleanup → mount; the REAL (second) mount must not
+    // be mistaken for a theme-style recreation.
+    await waitFor(() => expect(createGraphMock).toHaveBeenCalledTimes(2));
+    const lastOpts = createGraphMock.mock.calls.at(-1)?.[2] as { suppressEntrance?: boolean };
+    expect(lastOpts.suppressEntrance).toBe(false);
+  });
+
   it('tooltip formatter change does NOT recreate the graph (rides the trampoline)', async () => {
     const { rerender } = render(<Graph spec={spec} tooltip={{ formatter: () => 'one' }} />);
     await waitFor(() => expect(createGraphMock).toHaveBeenCalledTimes(1));

packages/vanilla/src/graph-mount.ts

@@ -20,7 +20,12 @@ import type {
   GraphCompilation,
 } from '@opendata-ai/openchart-engine';
 import { buildEdgeTooltip, compileGraph } from '@opendata-ai/openchart-engine';
-import { type CameraFlightOptions, clampK, createCameraFlight } from './graph/camera';
+import {
+  type CameraFlightOptions,
+  clampK,
+  createCameraFlight,
+  createCameraFollow,
+} from './graph/camera';
 import { GraphCanvasRenderer } from './graph/canvas-renderer';
 import { ENTRANCE_STAGGER_MAX_NODES } from './graph/entrance';
 import {
@@ -180,6 +185,9 @@ const CURSOR_FORCE_MAX_NODES = 2000;
 /** Cursor pointer-feed throttle (~30Hz) so we don't post on every mousemove. */
 const CURSOR_POINTER_THROTTLE_MS = 33;
 
+/** Post-flight camera follow stops once the sim alpha settles below this. */
+const FOLLOW_SETTLE_ALPHA = 0.05;
+
 // ---------------------------------------------------------------------------
 // Main API
 // ---------------------------------------------------------------------------
@@ -240,6 +248,10 @@ export function createGraph(
   let lastPointerFeedTime = 0;
   // Camera flight state.
   let activeFlight: GraphAnimation | null = null;
+  // Post-flight follow for provider-form flights (tracks a still-settling node).
+  let activeFollow: GraphAnimation | null = null;
+  // Latest simulation alpha, fed by onTick; the follow stops below the threshold.
+  let lastAlpha = 1;
   let cameraChangePending = false;
 
   // Focus / highlight state (Phase 5). One highlight slot with two writers:
@@ -635,13 +647,18 @@ export function createGraph(
       cursorRepulsion: cursorForceEnabled() ? compilation.interaction.cursorRepulsion : null,
     });
 
+    // A fresh sim starts hot; don't let a settled previous sim's alpha linger
+    // (it would end a post-flight camera follow before the first tick lands).
+    lastAlpha = opts?.initialAlpha ?? 1;
+
     let initialSettleDone = false;
     // Update sims keep the current camera and don't run the entrance reveal, so
     // pre-mark the fit as done — the first update tick just streams positions.
     let initialFitDone = opts?.skipEntrance ?? false;
 
-    simulation.onTick((positions, _alpha) => {
+    simulation.onTick((positions, alpha) => {
       if (destroyed) return;
+      lastAlpha = alpha;
 
       // Build position lookup
       const posMap = new Map<string, { x: number; y: number }>();
@@ -728,6 +745,7 @@ export function createGraph(
 
     if (suppressed || !enter || prefersReducedMotion()) {
       interactionManager.setTransform(fit);
+      cameraChangePending = true;
       entranceActive = false;
       entranceProgress = 1;
       return;
@@ -737,6 +755,7 @@ export function createGraph(
     const { width: cw, height: ch } = getCanvasDimensions();
     const pulledBack = fit.zoomAt(fit.k * 0.92, cw / 2, ch / 2);
     interactionManager.setTransform(pulledBack);
+    cameraChangePending = true;
 
     entranceActive = true;
     entranceProgress = 0;
@@ -1072,11 +1091,8 @@ export function createGraph(
   ): void {
     if (destroyed || !interactionManager) return;
 
-    // Cancel any in-flight camera animation.
-    if (activeFlight) {
-      scheduler.remove(activeFlight);
-      activeFlight = null;
-    }
+    // Cancel any in-flight camera animation (and a lingering post-flight follow).
+    cancelFlight();
 
     const cameraCfg = compilation.animation?.camera ?? null;
     const resolveTarget = () => (typeof to === 'function' ? to() : to);
@@ -1111,6 +1127,9 @@ export function createGraph(
         activeFlight = null;
         isGesturing = false;
         needsRender = true;
+        // Provider-form flights converge at t=1 while the tracked node may
+        // still be settling — keep following it until the sim quiets down.
+        if (typeof to === 'function') startFollow(to);
         scheduleRender();
         onDone?.();
       },
@@ -1120,13 +1139,32 @@ export function createGraph(
     scheduler.add(flight);
   }
 
-  /** Cancel any active camera flight (called by user-initiated pan/zoom). */
+  /** Snap the camera to a provider each frame until the sim settles. */
+  function startFollow(target: () => ZoomTransform): void {
+    const follow = createCameraFollow({
+      target,
+      apply: (t) => {
+        interactionManager!.setTransform(t);
+        cameraChangePending = true;
+        needsRender = true;
+      },
+      isActive: () => !destroyed && lastAlpha >= FOLLOW_SETTLE_ALPHA,
+    });
+    activeFollow = follow;
+    scheduler.add(follow);
+  }
+
+  /** Cancel any active camera flight/follow (called by user-initiated pan/zoom). */
   function cancelFlight(): void {
     if (activeFlight) {
       scheduler.remove(activeFlight);
       activeFlight = null;
       isGesturing = false;
     }
+    if (activeFollow) {
+      scheduler.remove(activeFollow);
+      activeFollow = null;
+    }
   }
 
   // ---------------------------------------------------------------------------
@@ -1147,6 +1185,9 @@ export function createGraph(
         // node-drag correctly doesn't reach here either.
         cancelFlight();
         markGesture();
+        // User pan/zoom is a camera change too — zoom UIs and camera
+        // persistence rely on the coalesced onCameraChange, not polling.
+        cameraChangePending = true;
         needsRender = true;
         scheduleRender();
       },
@@ -1461,6 +1502,7 @@ export function createGraph(
       cancelFlight();
       entranceFitInFlight = false;
       interactionManager.setTransform(computeInitialFit());
+      cameraChangePending = true;
     }
 
     needsRender = true;
@@ -1594,10 +1636,10 @@ export function createGraph(
       Math.max(prevNodeCount, nextNodeCount),
     );
     const prevEdgeCount =
-      compilation.edges.length - enteringEdgeCount(diff) + diff.exitingEdges.length;
+      compilation.edges.length - diff.enteringEdgeCount + diff.exitingEdges.length;
     const nextEdgeCount = compilation.edges.length;
     const edgeRatio = ratio(
-      enteringEdgeCount(diff) + diff.exitingEdges.length,
+      diff.enteringEdgeCount + diff.exitingEdges.length,
       Math.max(prevEdgeCount, nextEdgeCount),
     );
     const changeRatio = Math.max(nodeRatio, edgeRatio);
@@ -1639,17 +1681,6 @@ export function createGraph(
     scheduleRender();
   }
 
-  /** Count of edges in the new compilation touching an entering node. */
-  function enteringEdgeCount(diff: ReturnType<typeof diffGraphUpdate>): number {
-    if (diff.enteringIds.length === 0) return 0;
-    const entering = new Set(diff.enteringIds);
-    let count = 0;
-    for (const e of compilation.edges) {
-      if (entering.has(e.source) || entering.has(e.target)) count++;
-    }
-    return count;
-  }
-
   /** Safe ratio (0 when the denominator is 0). */
   function ratio(numerator: number, denominator: number): number {
     return denominator > 0 ? numerator / denominator : 0;
@@ -1776,6 +1807,7 @@ export function createGraph(
     // writes to removed state.
     scheduler.cancelAll();
     activeFlight = null;
+    activeFollow = null;
     // Reset entrance state so a remount (React StrictMode) starts clean.
     entranceReveal = null;
     entranceActive = false;