feat(graph): organic entrance pop + chrome collision fix

Entrance redesign: nodes pop in with an easeOutBack scale overshoot,
ripple outward from the layout centroid, and converge from a 16px
radial drift while the camera flies in from a deeper 0.85 pullback.
Default enter duration drops 600ms -> 500ms. Unstaggered (3k+ node)
graphs keep the batched global fade.

Chrome collision fix: the chrome overlay reserves the legend's width
(dynamic style.right) and fitBounds gains an insetTop reserve so
titles no longer run under the legend and nodes no longer render
behind chrome text.

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

Author: rileyhilliard

packages/core/schema/vizspec.schema.json

@@ -17133,7 +17133,7 @@
               "type": "boolean"
             }
           ],
-          "description": "Node/edge reveal on first render. Default `{ duration: 600, ease: 'smooth', stagger: true }`."
+          "description": "Node/edge reveal on first render. Default `{ duration: 500, ease: 'smooth', stagger: true }`."
         },
         "update": {
           "anyOf": [

packages/core/src/types/spec.ts

@@ -2137,7 +2137,7 @@ export interface NodeOverride {
  * already exists on load and choreography reduces the chaos.
  */
 export interface GraphAnimationConfig {
-  /** Node/edge reveal on first render. Default `{ duration: 600, ease: 'smooth', stagger: true }`. */
+  /** Node/edge reveal on first render. Default `{ duration: 500, ease: 'smooth', stagger: true }`. */
   enter?: AnimationPhaseConfig | boolean;
   /** Data-update enter-fade for newly added marks. Default `{ duration: 300, ease: 'smooth' }`. */
   update?: AnimationPhaseConfig | boolean;

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

@@ -24,7 +24,7 @@ describe('resolveGraphAnimation', () => {
   it('returns full defaults when omitted (default-ON)', () => {
     const r = resolveGraphAnimation(undefined);
     expect(r).toBeDefined();
-    expect(r?.enter).toEqual({ duration: 600, ease: 'smooth', stagger: true, cameraFit: true });
+    expect(r?.enter).toEqual({ duration: 500, ease: 'smooth', stagger: true, cameraFit: true });
     expect(r?.update).toEqual({ duration: 300, ease: 'smooth' });
     expect(r?.exit).toEqual({ duration: 300, ease: 'smooth' });
     expect(r?.camera).toEqual({ duration: 'auto', ease: 'smooth' });
@@ -36,7 +36,7 @@ describe('resolveGraphAnimation', () => {
   });
 
   it('returns full defaults for true', () => {
-    expect(resolveGraphAnimation(true)?.enter?.duration).toBe(600);
+    expect(resolveGraphAnimation(true)?.enter?.duration).toBe(500);
   });
 
   it('disables just the named phase when set false', () => {
@@ -270,7 +270,7 @@ describe('layout presets + seed + highlight', () => {
 
   it('resolves animation (default-ON) and interaction on the compilation', () => {
     const r = compileGraph(base, compileOptions);
-    expect(r.animation?.enter?.duration).toBe(600);
+    expect(r.animation?.enter?.duration).toBe(500);
     expect(r.interaction.hoverMode).toBe('neighbors');
   });
 

packages/engine/src/graphs/animation.ts

@@ -36,7 +36,7 @@ export interface ResolvedGraphAnimation {
 }
 
 const ENTER_DEFAULT = {
-  duration: 600,
+  duration: 500,
   ease: 'smooth' as AnimationEase,
   stagger: true,
   cameraFit: true,

packages/vanilla/src/graph-mount.ts

@@ -27,7 +27,7 @@ import {
   createCameraFollow,
 } from './graph/camera';
 import { GraphCanvasRenderer } from './graph/canvas-renderer';
-import { ENTRANCE_STAGGER_MAX_NODES } from './graph/entrance';
+import { ENTRANCE_STAGGER_MAX_NODES, entranceOffsets, entranceOrder } from './graph/entrance';
 import {
   composeStandingFocus,
   type FocusSnapshot,
@@ -278,6 +278,10 @@ export function createGraph(
   let entranceProgress = 1;
   let entranceActive = false;
   let entranceStagger = false;
+  // Pop choreography inputs (staggered entrances only): centroid-radial stagger
+  // rank and per-node convergence drift vectors, built once at entrance start.
+  let entranceOrderMap: Map<string, number> | null = null;
+  let entranceOffsetMap: Map<string, { x: number; y: number }> | null = null;
   let entranceFitInFlight = false;
   let entranceReveal: GraphAnimation | null = null;
   // Mount-level opt-out (Phase 9): when set, the FIRST entrance takes the instant
@@ -489,6 +493,7 @@ export function createGraph(
     }
 
     container.appendChild(wrapper);
+    syncChromeInset();
 
     // Canvas uses the full container height; chrome overlays on top
     const canvasHeight = Math.max(height, 200);
@@ -553,6 +558,28 @@ export function createGraph(
   /** Re-render the legend to reflect the current active-category state. */
   function syncLegendActiveState(): void {
     if (legendController) legendController.update(legendViewData());
+    syncChromeInset();
+  }
+
+  /**
+   * Keep the chrome block out of the legend's column: the title/subtitle wrap
+   * before they reach the legend box instead of running underneath it. No-op
+   * when there's no legend (or it has no measurable width, e.g. in happy-dom).
+   */
+  function syncChromeInset(): void {
+    if (!chromeEl) return;
+    const legendW = legendEl?.offsetWidth ?? 0;
+    chromeEl.style.right = legendW > 0 ? `${legendW + 24}px` : '';
+  }
+
+  /**
+   * Height of the chrome overlay band (title + subtitle) the camera fit should
+   * reserve, so nodes never settle underneath the text. 0 when chrome is empty
+   * or unmeasurable (happy-dom).
+   */
+  function chromeInsetTop(): number {
+    if (!chromeEl || chromeEl.style.display === 'none') return 0;
+    return chromeEl.offsetHeight;
   }
 
   // ---------------------------------------------------------------------------
@@ -723,6 +750,7 @@ export function createGraph(
     const warmed = (compilation.simulationConfig.warmupTicks ?? 0) > 0;
     const { transform } = ZoomTransform.fitBounds(positionedNodes, cw, ch, undefined, {
       spread: !warmed,
+      insetTop: chromeInsetTop(),
     });
     return transform;
   }
@@ -753,7 +781,7 @@ export function createGraph(
 
     // 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);
+    const pulledBack = fit.zoomAt(fit.k * 0.85, cw / 2, ch / 2);
     interactionManager.setTransform(pulledBack);
     cameraChangePending = true;
 
@@ -762,6 +790,15 @@ export function createGraph(
     // 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;
+    // Pop choreography inputs, computed once against the warmed (near-final)
+    // positions: centroid-radial stagger order + per-node convergence drift.
+    if (entranceStagger) {
+      entranceOrderMap = entranceOrder(positionedNodes);
+      entranceOffsetMap = entranceOffsets(positionedNodes);
+    } else {
+      entranceOrderMap = null;
+      entranceOffsetMap = null;
+    }
 
     // Optional camera flight from the pulled-back framing to the true fit.
     if (enter.cameraFit) {
@@ -1048,7 +1085,12 @@ export function createGraph(
       dimOpacity: highlightDimOpacity ?? compilation.interaction.dimOpacity,
       entrance:
         entranceActive && entranceProgress < 1
-          ? { t: entranceProgress, stagger: entranceStagger }
+          ? {
+              t: entranceProgress,
+              stagger: entranceStagger,
+              order: entranceOrderMap ?? undefined,
+              offsets: entranceOffsetMap ?? undefined,
+            }
           : undefined,
       enterAlpha: enterAlphaMap ?? undefined,
       exiting: exitingGhosts ?? undefined,
@@ -1372,6 +1414,9 @@ export function createGraph(
       cw,
       ch,
       opts?.padding,
+      {
+        insetTop: chromeInsetTop(),
+      },
     );
     flyCamera(fitTransform, opts);
   }
@@ -1494,6 +1539,9 @@ export function createGraph(
     const { width, height } = getContainerDimensions();
     const canvasHeight = Math.max(height, 200);
     renderer.resize(width, canvasHeight);
+    // A width change can rewrap the title or move the legend; re-derive the
+    // chrome/legend separation before any fit below measures the chrome band.
+    syncChromeInset();
 
     // 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

packages/vanilla/src/graph/__tests__/entrance.test.ts

@@ -4,7 +4,16 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import { ENTRANCE_STAGGER_MAX_NODES, nodeEnterProgress } from '../entrance';
+import {
+  driftFactor,
+  ENTRANCE_DRIFT_PX,
+  ENTRANCE_STAGGER_MAX_NODES,
+  entranceOffsets,
+  entranceOrder,
+  nodeEnterProgress,
+  popAlpha,
+  popScale,
+} from '../entrance';
 
 describe('nodeEnterProgress', () => {
   it('clamps global progress to [0, 1]', () => {
@@ -56,3 +65,91 @@ describe('ENTRANCE_STAGGER_MAX_NODES', () => {
     expect(ENTRANCE_STAGGER_MAX_NODES).toBe(3000);
   });
 });
+
+describe('entranceOrder', () => {
+  it('ranks nodes by distance from the centroid, ascending', () => {
+    // Centroid of these four is (0, 0); 'near' is closest, 'far' farthest.
+    const nodes = [
+      { id: 'far', x: 100, y: 0 },
+      { id: 'near', x: 2, y: 0 },
+      { id: 'mid', x: -30, y: 0 },
+      { id: 'balance', x: -72, y: 0 },
+    ];
+    const order = entranceOrder(nodes);
+    expect(order.get('near')).toBe(0);
+    expect(order.get('mid')).toBe(1);
+    expect(order.get('balance')).toBe(2);
+    expect(order.get('far')).toBe(3);
+  });
+
+  it('returns an empty map for zero nodes', () => {
+    expect(entranceOrder([]).size).toBe(0);
+  });
+});
+
+describe('entranceOffsets', () => {
+  it('points away from the centroid with magnitude ENTRANCE_DRIFT_PX', () => {
+    const nodes = [
+      { id: 'a', x: 10, y: 0 },
+      { id: 'b', x: -10, y: 0 },
+    ];
+    const offsets = entranceOffsets(nodes);
+    expect(offsets.get('a')).toEqual({ x: ENTRANCE_DRIFT_PX, y: 0 });
+    expect(offsets.get('b')).toEqual({ x: -ENTRANCE_DRIFT_PX, y: 0 });
+  });
+
+  it('honors a custom distance', () => {
+    const offsets = entranceOffsets(
+      [
+        { id: 'a', x: 5, y: 0 },
+        { id: 'b', x: -5, y: 0 },
+      ],
+      4,
+    );
+    expect(offsets.get('a')).toEqual({ x: 4, y: 0 });
+  });
+
+  it('falls back to straight-up for a node sitting on the centroid', () => {
+    // A single node IS the centroid — zero-length direction vector.
+    const offsets = entranceOffsets([{ id: 'solo', x: 42, y: 42 }]);
+    expect(offsets.get('solo')).toEqual({ x: 0, y: -ENTRANCE_DRIFT_PX });
+  });
+
+  it('returns an empty map for zero nodes', () => {
+    expect(entranceOffsets([]).size).toBe(0);
+  });
+});
+
+describe('popScale', () => {
+  it('is 0 at t≤0 and 1 at t≥1', () => {
+    expect(popScale(0)).toBe(0);
+    expect(popScale(-1)).toBe(0);
+    expect(popScale(1)).toBe(1);
+    expect(popScale(2)).toBe(1);
+  });
+
+  it('overshoots past 1 mid-curve (the pop)', () => {
+    const peak = Math.max(...Array.from({ length: 99 }, (_, i) => popScale((i + 1) / 100)));
+    expect(peak).toBeGreaterThan(1.05);
+    expect(peak).toBeLessThan(1.15);
+  });
+});
+
+describe('popAlpha', () => {
+  it('reaches full opacity by 60% of the window', () => {
+    expect(popAlpha(0)).toBe(0);
+    expect(popAlpha(0.3)).toBeCloseTo(0.5, 5);
+    expect(popAlpha(0.6)).toBe(1);
+    expect(popAlpha(1)).toBe(1);
+  });
+});
+
+describe('driftFactor', () => {
+  it('eases quadratically from 1 (full offset) to 0 (at rest)', () => {
+    expect(driftFactor(0)).toBe(1);
+    expect(driftFactor(0.5)).toBeCloseTo(0.25, 5);
+    expect(driftFactor(1)).toBe(0);
+    expect(driftFactor(-1)).toBe(1);
+    expect(driftFactor(2)).toBe(0);
+  });
+});

packages/vanilla/src/graph/__tests__/graph-mount.test.ts

@@ -321,14 +321,14 @@ describe('createGraph entrance', () => {
     pumpRaf(0);
 
     const pulledBack = graph.getCamera();
-    // The entrance starts at 0.92× the fit zoom — strictly less than the final.
+    // The entrance starts at 0.85× the fit zoom — strictly less than the final.
     // Drive far past the reveal (duration 600) + the fit flight (+100) to settle.
     for (let t = 50; t <= 1400; t += 50) pumpRaf(t);
     const settled = graph.getCamera();
 
-    // Pulled-back zoom is ~0.92 of the settled fit zoom.
+    // Pulled-back zoom is ~0.85 of the settled fit zoom.
     expect(pulledBack.k).toBeLessThan(settled.k);
-    expect(pulledBack.k).toBeCloseTo(settled.k * 0.92, 5);
+    expect(pulledBack.k).toBeCloseTo(settled.k * 0.85, 5);
 
     graph.destroy();
   });
@@ -350,7 +350,7 @@ describe('createGraph entrance', () => {
     expect(later.x).toBeCloseTo(initial.x, 6);
     expect(later.y).toBeCloseTo(initial.y, 6);
     // The instant fit is a real fit (finite, positive zoom), not the pulled-back
-    // framing — i.e. reduced motion skipped the 0.92 pullback.
+    // framing — i.e. reduced motion skipped the 0.85 pullback.
     expect(initial.k).toBeGreaterThan(0);
 
     graph.destroy();
@@ -445,7 +445,7 @@ describe('createGraph entrance', () => {
     graph.destroy();
   });
 
-  it('suppressEntrance: first camera is the instant fit (no 0.92 pullback, no reveal tween)', async () => {
+  it('suppressEntrance: first camera is the instant fit (no 0.85 pullback, no reveal tween)', async () => {
     container = makeContainer();
     // Same warmed spec that DOES animate an entrance without suppressEntrance —
     // the only difference here is the mount option.
@@ -462,7 +462,7 @@ describe('createGraph entrance', () => {
     expect(later.k).toBeCloseTo(initial.k, 6);
     expect(later.x).toBeCloseTo(initial.x, 6);
     expect(later.y).toBeCloseTo(initial.y, 6);
-    // A real fit (finite, positive zoom), not the pulled-back 0.92 framing.
+    // A real fit (finite, positive zoom), not the pulled-back 0.85 framing.
     expect(initial.k).toBeGreaterThan(0);
 
     graph.destroy();