tryopendata
diff --git a/‎packages/vanilla/src/graph-mount.ts‎
Lines changed: 127 additions & 10 deletions b/‎packages/vanilla/src/graph-mount.ts‎
Lines changed: 127 additions & 10 deletions
diff --git a/‎packages/vanilla/src/graph/__tests__/canvas-renderer.test.ts‎
Lines changed: 87 additions & 0 deletions b/‎packages/vanilla/src/graph/__tests__/canvas-renderer.test.ts‎
Lines changed: 87 additions & 0 deletions
diff --git a/‎packages/vanilla/src/graph/__tests__/entrance.test.ts‎
Lines changed: 58 additions & 0 deletions b/‎packages/vanilla/src/graph/__tests__/entrance.test.ts‎
Lines changed: 58 additions & 0 deletions
@@ -22,6 +22,7 @@ import type {
 import { buildEdgeTooltip, compileGraph } from '@opendata-ai/openchart-engine';
 import { type CameraFlightOptions, clampK, createCameraFlight } from './graph/camera';
 import { GraphCanvasRenderer } from './graph/canvas-renderer';
+import { ENTRANCE_STAGGER_MAX_NODES } from './graph/entrance';
 import {
   composeStandingFocus,
   type FocusSnapshot,
@@ -34,6 +35,7 @@ import { createGraphLegend, type GraphLegendController } from './graph/legend';
 import { createTween, prefersReducedMotion, resolveEase } from './graph/motion';
 import { AnimationScheduler, type GraphAnimation } from './graph/scheduler';
 import { GraphSearchManager } from './graph/search';
+import { seedNodePositions } from './graph/seed';
 import { SimulationManager } from './graph/simulation';
 import { SpatialIndex } from './graph/spatial-index';
 import type { GraphRenderState, PositionedEdge, PositionedNode } from './graph/types';
@@ -240,6 +242,17 @@ export function createGraph(
   // Hovered-node radius tween (1 → 1.15), null when settled at 1.
   let hoverRadiusTween: { nodeId: string; scale: number } | null = null;
 
+  // Entrance choreography state (Phase 6). `entranceProgress` is a mount-level
+  // 0→1 value read by buildRenderState; < 1 means the reveal is mid-flight.
+  // `entranceActive` gates the render-state `entrance` field. `entranceFitInFlight`
+  // tracks the entrance camera flight so a resize can cancel just it (keeping the
+  // reveal). `entranceReveal` is the scheduler tween driving `entranceProgress`.
+  let entranceProgress = 1;
+  let entranceActive = false;
+  let entranceStagger = false;
+  let entranceFitInFlight = false;
+  let entranceReveal: GraphAnimation | null = null;
+
   // ---------------------------------------------------------------------------
   // Helpers
   // ---------------------------------------------------------------------------
@@ -510,6 +523,11 @@ export function createGraph(
     const simEdges = toSimEdges(compilation.edges);
     const config = compilation.simulationConfig;
 
+    // Seed deterministic initial positions BEFORE the simulation starts, so the
+    // settled layout is reproducible for a given (spec, seed). `seed ?? 0` keeps
+    // the default path seeded too (still deterministic, just a fixed seed).
+    seedNodePositions(simNodes, config.seed ?? 0);
+
     simulation = SimulationManager.create(simNodes, simEdges, {
       chargeStrength: config.chargeStrength,
       linkDistance: config.linkDistance,
@@ -520,6 +538,9 @@ export function createGraph(
       collisionPadding: config.collisionPadding,
       linkStrength: config.linkStrength,
       centerForce: config.centerForce,
+      warmupTicks: config.warmupTicks,
+      warmupBudgetMs: config.warmupBudgetMs,
+      initialAlpha: config.initialAlpha,
     });
 
     let initialSettleDone = false;
@@ -535,9 +556,9 @@ export function createGraph(
       }
 
       // Build positioned nodes
-      positionedNodes = compilation.nodes.map((node) => {
+      positionedNodes = compilation.nodes.map((node, index) => {
         const pos = posMap.get(node.id) ?? { x: 0, y: 0 };
-        return { ...node, x: pos.x, y: pos.y };
+        return { ...node, x: pos.x, y: pos.y, index };
       });
 
       // Build positioned edges
@@ -556,19 +577,17 @@ export function createGraph(
       // Rebuild spatial index
       spatialIndex.rebuild(positionedNodes);
 
-      // Fit the viewport once on the first tick so the graph is visible and
-      // centered immediately. After that, let the user interact freely while
-      // the simulation continues settling in the background.
+      // Fit + entrance choreography on the FIRST post-warmup tick (the sim only
+      // starts streaming ticks once warmup, if any, has completed). After that,
+      // let the user interact freely while the simulation keeps settling.
       if (
         !initialFitDone &&
         positionedNodes.length > 0 &&
         interactionManager &&
         options?.fitOnLoad !== false
       ) {
         initialFitDone = true;
-        const { width: cw, height: ch } = getCanvasDimensions();
-        const { transform: fitTransform } = ZoomTransform.fitBounds(positionedNodes, cw, ch);
-        interactionManager.setTransform(fitTransform);
+        startEntrance();
       } else if (!initialFitDone && options?.fitOnLoad === false) {
         // Skip the fit but mark it done so a saved camera (getCamera/flyTo) sticks.
         initialFitDone = true;
@@ -584,6 +603,76 @@ export function createGraph(
     });
   }
 
+  /**
+   * Compute the initial fit transform. Bypasses fitBounds' spread inflation when
+   * warmup ran (warmed bounds are near-final; inflating them fits too small).
+   */
+  function computeInitialFit(): ZoomTransform {
+    const { width: cw, height: ch } = getCanvasDimensions();
+    const warmed = (compilation.simulationConfig.warmupTicks ?? 0) > 0;
+    const { transform } = ZoomTransform.fitBounds(positionedNodes, cw, ch, undefined, {
+      spread: !warmed,
+    });
+    return transform;
+  }
+
+  /**
+   * Fit + run the entrance reveal on the first post-warmup tick. Under an enabled
+   * `enter` phase and normal motion, the camera starts pulled back to 0.92× the
+   * fit and (optionally) flies in while a mount-level `entranceProgress` tween
+   * ramps node/edge/label reveal. Under reduced motion or `animation: false`,
+   * it's an instant fit (warmup still ran — it reduces motion, it isn't motion).
+   */
+  function startEntrance(): void {
+    if (!interactionManager) return;
+    const fit = computeInitialFit();
+    const enter = compilation.animation?.enter ?? null;
+
+    if (!enter || prefersReducedMotion()) {
+      interactionManager.setTransform(fit);
+      entranceActive = false;
+      entranceProgress = 1;
+      return;
+    }
+
+    // Start pulled back so the reveal has somewhere to fly in from.
+    const { width: cw, height: ch } = getCanvasDimensions();
+    const pulledBack = fit.zoomAt(fit.k * 0.92, cw / 2, ch / 2);
+    interactionManager.setTransform(pulledBack);
+
+    entranceActive = true;
+    entranceProgress = 0;
+    // Stagger only when the spec asks for it AND the graph is small enough that
+    // per-node start times still batch. Above the cap: a single global fade.
+    entranceStagger = enter.stagger && positionedNodes.length <= ENTRANCE_STAGGER_MAX_NODES;
+
+    // Optional camera flight from the pulled-back framing to the true fit.
+    if (enter.cameraFit) {
+      entranceFitInFlight = true;
+      flyCamera(fit, { duration: enter.duration + 100 }, () => {
+        entranceFitInFlight = false;
+      });
+    }
+
+    // Reveal tween drives entranceProgress 0→1; ends the entrance on completion.
+    const ease = resolveEase(enter.ease);
+    entranceReveal = createTween({
+      duration: enter.duration,
+      ease,
+      apply: (t) => {
+        entranceProgress = t;
+        needsRender = true;
+      },
+      onDone: () => {
+        entranceProgress = 1;
+        entranceActive = false;
+        entranceReveal = null;
+        needsRender = true;
+      },
+    });
+    scheduler.add(entranceReveal);
+  }
+
   function getCanvasDimensions(): { width: number; height: number } {
     if (!canvas) return { width: 600, height: 400 };
     const rect = canvas.getBoundingClientRect();
@@ -840,6 +929,10 @@ export function createGraph(
       focus: focus ?? { t: 1, prev: settledNext, next: settledNext },
       hoverRadiusScale,
       dimOpacity: highlightDimOpacity ?? compilation.interaction.dimOpacity,
+      entrance:
+        entranceActive && entranceProgress < 1
+          ? { t: entranceProgress, stagger: entranceStagger }
+          : undefined,
     };
   }
 
@@ -1244,6 +1337,16 @@ export function createGraph(
     const { width, height } = getContainerDimensions();
     const canvasHeight = Math.max(height, 200);
     renderer.resize(width, canvasHeight);
+
+    // Mid-entrance: the in-flight camera fit targets the OLD viewport, so cancel
+    // just that flight and snap to the new-viewport fit. The reveal tween (node
+    // alpha/scale ramp) is orthogonal to the camera and keeps running.
+    if (entranceFitInFlight && interactionManager) {
+      cancelFlight();
+      entranceFitInFlight = false;
+      interactionManager.setTransform(computeInitialFit());
+    }
+
     needsRender = true;
     scheduleRender();
   }
@@ -1252,6 +1355,15 @@ export function createGraph(
     if (destroyed) return;
     currentSpec = newSpec;
 
+    // Finish any in-flight animations (e.g. an entrance reveal) before teardown
+    // so they snap to their final state and fire onDone, rather than being hard
+    // cancelled mid-flight. teardownSubsystems() then cancels whatever remains.
+    scheduler.finishAll();
+    entranceActive = false;
+    entranceProgress = 1;
+    entranceFitInFlight = false;
+    entranceReveal = null;
+
     // Tear down old simulation + interaction
     teardownSubsystems();
 
@@ -1300,9 +1412,9 @@ export function createGraph(
     buildDataMaps();
 
     // Transfer positions to new compiled nodes
-    positionedNodes = compilation.nodes.map((node) => {
+    positionedNodes = compilation.nodes.map((node, index) => {
       const pos = posMap.get(node.id) ?? { x: 0, y: 0 };
-      return { ...node, x: pos.x, y: pos.y };
+      return { ...node, x: pos.x, y: pos.y, index };
     });
 
     // Rebuild positioned edges from existing positions
@@ -1342,6 +1454,11 @@ export function createGraph(
     // writes to removed state.
     scheduler.cancelAll();
     activeFlight = null;
+    // Reset entrance state so a remount (React StrictMode) starts clean.
+    entranceReveal = null;
+    entranceActive = false;
+    entranceProgress = 1;
+    entranceFitInFlight = false;
     if (animFrameId !== null) {
       cancelAnimationFrame(animFrameId);
       animFrameId = null;
 
@@ -128,6 +128,7 @@ function makeNode(overrides: Partial<PositionedNode> & { id: string }): Position
   return {
     x: 0,
     y: 0,
+    index: 0,
     radius: 5,
     fill: '#3b82f6',
     stroke: '#2563eb',
@@ -871,3 +872,89 @@ describe('label halo on transparent background', () => {
     expect(haloColor(false)).toBe('rgba(255, 255, 255, 0.85)');
   });
 });
+
+// ---------------------------------------------------------------------------
+// Entrance reveal ramp
+// ---------------------------------------------------------------------------
+
+describe('GraphCanvasRenderer entrance', () => {
+  it('mid-entrance node fills use a ramped alpha (0.6 + 0.4·t), below 1', () => {
+    const { canvas, calls } = createRecordingCanvas();
+    const renderer = new GraphCanvasRenderer(canvas);
+    renderer.resize(400, 400);
+
+    renderer.render(
+      makeState({
+        nodes: [makeNode({ id: 'a', index: 0 })],
+        // Global fade (no stagger): nodeT = t = 0.5 → alpha 0.6 + 0.4·0.5 = 0.8.
+        entrance: { t: 0.5, stagger: false },
+      }),
+    );
+
+    const fills = calls.filter((c) => c.method === 'fill' && c.alpha !== undefined);
+    expect(fills.length).toBeGreaterThan(0);
+    const nodeFill = fills.find((c) => (c.alpha ?? 1) < 1);
+    expect(nodeFill).toBeDefined();
+    expect(nodeFill!.alpha).toBeCloseTo(0.8, 5);
+  });
+
+  it('settled (t≥1) renders at full alpha — entrance is a no-op', () => {
+    const { canvas, calls } = createRecordingCanvas();
+    const renderer = new GraphCanvasRenderer(canvas);
+    renderer.resize(400, 400);
+
+    renderer.render(
+      makeState({
+        nodes: [makeNode({ id: 'a', index: 0 })],
+        entrance: { t: 1, stagger: false },
+      }),
+    );
+
+    const fills = calls.filter((c) => c.method === 'fill' && c.alpha !== undefined);
+    // No ramped (sub-1) node fill: the entrance path is skipped at t≥1.
+    expect(fills.every((c) => (c.alpha ?? 1) >= 1 - 1e-9)).toBe(true);
+  });
+
+  it('edges lag 30% behind the reveal (edge alpha 0 until t>0.3)', () => {
+    const { canvas, calls } = createRecordingCanvas();
+    const renderer = new GraphCanvasRenderer(canvas);
+    renderer.resize(400, 400);
+
+    renderer.render(
+      makeState({
+        nodes: [makeNode({ id: 'a', index: 0 }), makeNode({ id: 'b', index: 1, x: 100 })],
+        edges: [makeEdge('a', 'b')],
+        // At t=0.2 (< 0.3 lag), the edge alpha scales to 0 → invisible stroke.
+        entrance: { t: 0.2, stagger: false },
+      }),
+    );
+
+    // Edges are stroked before nodes; the edge stroke lands at alpha 0 (fully
+    // lagged), while node strokes ramp to 0.68 (0.6 + 0.4·0.2). So the very
+    // first stroke recorded is the edge, and it must be transparent.
+    const strokes = calls.filter((c) => c.method === 'stroke' && c.alpha !== undefined);
+    expect(strokes.length).toBeGreaterThan(0);
+    expect(strokes[0].alpha).toBe(0);
+    // At least one stroke (the edge) is fully lagged to 0.
+    expect(strokes.some((c) => c.alpha === 0)).toBe(true);
+  });
+
+  it('past the 30% lag, edges fade in (edge alpha > 0)', () => {
+    const { canvas, calls } = createRecordingCanvas();
+    const renderer = new GraphCanvasRenderer(canvas);
+    renderer.resize(400, 400);
+
+    renderer.render(
+      makeState({
+        nodes: [makeNode({ id: 'a', index: 0 }), makeNode({ id: 'b', index: 1, x: 100 })],
+        edges: [makeEdge('a', 'b')],
+        // t=0.65 → edgeAlpha = (0.65-0.3)/0.7 = 0.5, scaling the 0.35 default edge
+        // alpha to 0.175. The first stroke (edge) is now visible.
+        entrance: { t: 0.65, stagger: false },
+      }),
+    );
+
+    const strokes = calls.filter((c) => c.method === 'stroke' && c.alpha !== undefined);
+    expect(strokes[0].alpha).toBeGreaterThan(0);
+  });
+});
@@ -0,0 +1,58 @@
+/**
+ * Entrance stagger math: per-node reveal window, quantization, and the
+ * stagger-vs-global-fade node-count threshold.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { ENTRANCE_STAGGER_MAX_NODES, nodeEnterProgress } from '../entrance';
+
+describe('nodeEnterProgress', () => {
+  it('clamps global progress to [0, 1]', () => {
+    expect(nodeEnterProgress(-0.5, 0, 10)).toBe(0);
+    expect(nodeEnterProgress(2, 0, 10)).toBe(1);
+  });
+
+  it('first node fully revealed by t=0.6, last node by t=1.0', () => {
+    const total = 10;
+    // Node 0 starts at t=0, ramps over 0.6 → fully in at 0.6.
+    expect(nodeEnterProgress(0.6, 0, total)).toBe(1);
+    // Last node starts at (9/10)*0.4 = 0.36, ramps over 0.6 → fully in at 0.96.
+    expect(nodeEnterProgress(1, total - 1, total)).toBe(1);
+    // ...and is not yet fully in mid-timeline.
+    expect(nodeEnterProgress(0.6, total - 1, total)).toBeLessThan(1);
+  });
+
+  it('later nodes start later than earlier nodes', () => {
+    const total = 100;
+    const early = nodeEnterProgress(0.4, 0, total);
+    const late = nodeEnterProgress(0.4, 99, total);
+    expect(early).toBeGreaterThan(late);
+  });
+
+  it('quantizes to at most `buckets` distinct levels', () => {
+    const total = 1000;
+    const values = new Set<number>();
+    for (let i = 0; i < total; i++) {
+      values.add(nodeEnterProgress(0.5, i, total, 8));
+    }
+    // ≤ 9 levels (0, 1/8, ..., 1) preserves fill batching.
+    expect(values.size).toBeLessThanOrEqual(9);
+  });
+
+  it('a smaller bucket count yields fewer levels', () => {
+    const total = 500;
+    const values = new Set<number>();
+    for (let i = 0; i < total; i++) values.add(nodeEnterProgress(0.5, i, total, 4));
+    expect(values.size).toBeLessThanOrEqual(5);
+  });
+
+  it('handles total=0 without dividing by zero', () => {
+    expect(() => nodeEnterProgress(0.5, 0, 0)).not.toThrow();
+  });
+});
+
+describe('ENTRANCE_STAGGER_MAX_NODES', () => {
+  it('is the documented 3000 threshold', () => {
+    expect(ENTRANCE_STAGGER_MAX_NODES).toBe(3000);
+  });
+});