@opendata-ai/openchart-vanilla 8.0.0-rc.2 → 8.0.0-rc.21

package/src/story/__tests__/tween.test.ts

@@ -1,159 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { clamp01, createTween, easingFns, lerp } from '../tween';
-
-/**
- * Deterministic rAF: we control frame timestamps manually.
- */
-let rafCallbacks: Map<number, FrameRequestCallback>;
-let rafId: number;
-let now: number;
-
-function advanceFrame(dtMs: number) {
-  now += dtMs;
-  const pending = [...rafCallbacks.entries()];
-  rafCallbacks.clear();
-  for (const [, cb] of pending) cb(now);
-}
-
-beforeEach(() => {
-  rafCallbacks = new Map();
-  rafId = 0;
-  now = 1000;
-  vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
-    rafCallbacks.set(++rafId, cb);
-    return rafId;
-  });
-  vi.stubGlobal('cancelAnimationFrame', (id: number) => {
-    rafCallbacks.delete(id);
-  });
-  vi.stubGlobal('performance', { now: () => now });
-});
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-});
-
-describe('easingFns', () => {
-  it.each(Object.entries(easingFns))('%s hits 0 at 0 and 1 at 1', (_, fn) => {
-    expect(fn(0)).toBeCloseTo(0);
-    expect(fn(1)).toBeCloseTo(1);
-  });
-
-  it.each(Object.entries(easingFns))('%s is monotonic on [0,1]', (_, fn) => {
-    let prev = fn(0);
-    for (let t = 0.05; t <= 1.0001; t += 0.05) {
-      const v = fn(t);
-      expect(v).toBeGreaterThanOrEqual(prev - 1e-9);
-      prev = v;
-    }
-  });
-});
-
-describe('lerp / clamp01', () => {
-  it('lerp endpoints and midpoint', () => {
-    expect(lerp(0, 10, 0)).toBe(0);
-    expect(lerp(0, 10, 1)).toBe(10);
-    expect(lerp(0, 10, 0.5)).toBe(5);
-  });
-
-  it('clamp01 clamps', () => {
-    expect(clamp01(-1)).toBe(0);
-    expect(clamp01(2)).toBe(1);
-    expect(clamp01(0.5)).toBe(0.5);
-  });
-});
-
-describe('createTween', () => {
-  it('retargets FROM THE LIVE interpolated value, not the old endpoint', () => {
-    const frames: number[] = [];
-    const tween = createTween<number>({
-      initial: 0,
-      lerp,
-      duration: 100,
-      ease: easingFns.linear,
-      onFrame: (v) => frames.push(v),
-    });
-
-    tween.to(100);
-    advanceFrame(50); // live value ~50
-    const live = frames.at(-1)!;
-    expect(live).toBeCloseTo(50);
-
-    // Fast-scroll interruption: retargeting must restart from the live
-    // mid-flight value, not snap back to the previous target first.
-    tween.to(0);
-    advanceFrame(0); // first frame of the retargeted tween
-    advanceFrame(1);
-    const firstAfterRetarget = frames.at(-1)!;
-    expect(firstAfterRetarget).toBeLessThanOrEqual(live);
-    expect(firstAfterRetarget).toBeGreaterThan(40); // started near 50, not 100
-
-    advanceFrame(200);
-    expect(tween.get()).toBe(0);
-  });
-
-  it('snap applies synchronously with no rAF', () => {
-    const frames: number[] = [];
-    const tween = createTween<number>({
-      initial: 0,
-      lerp,
-      onFrame: (v) => frames.push(v),
-    });
-    tween.to(7, { snap: true });
-    expect(frames).toEqual([7]);
-    expect(tween.get()).toBe(7);
-    expect(rafCallbacks.size).toBe(0);
-  });
-
-  it('works over arbitrary shapes', () => {
-    type State = { a: number; b: number };
-    const lerpState = (x: State, y: State, t: number): State => ({
-      a: lerp(x.a, y.a, t),
-      b: lerp(x.b, y.b, t),
-    });
-    let latest: State = { a: 0, b: 10 };
-    const tween = createTween<State>({
-      initial: latest,
-      lerp: lerpState,
-      duration: 100,
-      ease: easingFns.linear,
-      onFrame: (v) => {
-        latest = v;
-      },
-    });
-    tween.to({ a: 10, b: 0 });
-    advanceFrame(50);
-    expect(latest.a).toBeCloseTo(5);
-    expect(latest.b).toBeCloseTo(5);
-  });
-
-  it('cancel stops emission mid-flight', () => {
-    const frames: number[] = [];
-    const tween = createTween<number>({
-      initial: 0,
-      lerp,
-      duration: 100,
-      ease: easingFns.linear,
-      onFrame: (v) => frames.push(v),
-    });
-    tween.to(100);
-    advanceFrame(30);
-    const count = frames.length;
-    tween.cancel();
-    advanceFrame(30);
-    expect(frames.length).toBe(count);
-  });
-
-  it('zero duration snaps immediately', () => {
-    const frames: number[] = [];
-    const tween = createTween<number>({
-      initial: 0,
-      lerp,
-      duration: 0,
-      onFrame: (v) => frames.push(v),
-    });
-    tween.to(50);
-    expect(frames).toEqual([50]);
-    expect(rafCallbacks.size).toBe(0);
-  });
-});

package/src/story/camera-math.ts

@@ -1,125 +0,0 @@
-import { lerp } from './tween';
-
-/**
- * Pure math for the scrollytelling camera. `createChartStory` owns DOM
- * writes; everything here is testable without a browser. Ported from
- * opendata/shared/lib/scrolly/camera-math.ts.
- *
- * The camera is a center + zoom over a fixed viewBox, applied as a
- * `transform` on a dedicated wrapper `<g>` around the marks group (NOT
- * viewBox interpolation -- that scales text and gives labels no way to
- * counter-scale). See .claude/rules/svg-animation.md: CSS transform
- * replaces SVG transform attributes, so the camera transform must compose
- * with, not replace, existing SVG transforms on marks.
- */
-
-export interface Camera {
-  cx: number;
-  cy: number;
-  /** Zoom factor. 1 = full viewBox visible. */
-  k: number;
-}
-
-export interface CameraTarget {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  /** ViewBox units added on all sides before fitting */
-  padding?: number;
-}
-
-export interface ViewBoxSize {
-  width: number;
-  height: number;
-}
-
-export const FULL_VIEW = (vb: ViewBoxSize): CameraTarget => ({
-  x: 0,
-  y: 0,
-  width: vb.width,
-  height: vb.height,
-});
-
-/** Fit a target rect inside the viewBox, preserving aspect ratio. */
-export function fitTarget(target: CameraTarget, vb: ViewBoxSize): Camera {
-  const pad = target.padding ?? 0;
-  const w = target.width + 2 * pad;
-  const h = target.height + 2 * pad;
-  return {
-    cx: target.x + target.width / 2,
-    cy: target.y + target.height / 2,
-    k: Math.min(vb.width / w, vb.height / h),
-  };
-}
-
-/**
- * Pan lerps linearly; zoom lerps in LOG space so the zoom rate reads
- * constant (a 1->4 zoom passes through 2 at the midpoint, not 2.5).
- */
-export function interpolateCamera(a: Camera, b: Camera, t: number): Camera {
-  return {
-    cx: lerp(a.cx, b.cx, t),
-    cy: lerp(a.cy, b.cy, t),
-    k: Math.exp(lerp(Math.log(a.k), Math.log(b.k), t)),
-  };
-}
-
-/** SVG transform string that frames the camera inside the viewBox. */
-export function cameraTransform(c: Camera, vb: ViewBoxSize): string {
-  return `translate(${vb.width / 2} ${vb.height / 2}) scale(${c.k}) translate(${-c.cx} ${-c.cy})`;
-}
-
-/**
- * Frame-rate-independent exponential damping: two 8ms steps land where one
- * 16ms step does. `tauMs` is the time constant (~63% of the gap per tau).
- */
-export function damp(current: number, target: number, tauMs: number, dtMs: number): number {
-  if (tauMs <= 0) return target;
-  return current + (target - current) * (1 - Math.exp(-dtMs / tauMs));
-}
-
-export function dampCamera(current: Camera, target: Camera, tauMs: number, dtMs: number): Camera {
-  return {
-    cx: damp(current.cx, target.cx, tauMs, dtMs),
-    cy: damp(current.cy, target.cy, tauMs, dtMs),
-    // k damped in log space, same rationale as interpolateCamera
-    k: Math.exp(damp(Math.log(current.k), Math.log(target.k), tauMs, dtMs)),
-  };
-}
-
-export function camerasClose(a: Camera, b: Camera, epsilon = 1e-3): boolean {
-  return (
-    Math.abs(a.cx - b.cx) < epsilon &&
-    Math.abs(a.cy - b.cy) < epsilon &&
-    Math.abs(Math.log(a.k) - Math.log(b.k)) < epsilon
-  );
-}
-
-/**
- * Where the scrub camera should point for a given frame.
- *
- * Hold-zone semantics: the camera DWELLS on the active step's target while
- * the reader reads, and only transitions toward the next step's target in
- * the tail of the span (`stepProgress > holdUntil`). Interpolating across
- * the whole span would mean the camera departs the moment a step activates
- * and never rests on what the text is describing.
- */
-export function scrubCamera(
-  step: number,
-  stepProgress: number,
-  fitted: Camera[],
-  holdUntil: number,
-  ease: (t: number) => number,
-): Camera {
-  const n = fitted.length;
-  if (n === 0) return { cx: 0, cy: 0, k: 1 };
-  const clamped = Math.min(Math.max(step, 0), n - 1);
-  const current = fitted[clamped]!;
-  const next = fitted[Math.min(clamped + 1, n - 1)]!;
-  if (step < 0 || clamped >= n - 1 || stepProgress <= holdUntil) {
-    return current;
-  }
-  const t = (stepProgress - holdUntil) / (1 - holdUntil);
-  return interpolateCamera(current, next, ease(t));
-}

package/src/story/create-chart-story.ts

@@ -1,353 +0,0 @@
-/**
- * `createChartStory`: a base spec plus an ordered list of deep-partial
- * patch steps, driven by scroll (built-in `ScrollDriver`) or directly via
- * `goTo(n)`.
- *
- * Animation-clock ownership (decision baked 2026-07-11, see
- * plans/design-evolution/11-scrollytelling.md): the data-update-transitions
- * driver in `../transition.ts` owns mark morphing; the ported tween in
- * `./tween.ts` owns camera and any scalar story-level animation. They never
- * animate the same property. `goTo` calls `ChartInstance.update()`, which
- * internally decides morph-vs-instant-swap via `canTransition`; this module
- * predicts that decision ahead of time (`canTransitionSpecShape`) only to
- * decide whether to arm the crossfade fallback, and separately drives the
- * camera tween. It does not bridge the two clocks.
- */
-
-import type { DataRow, MapSpec } from '@opendata-ai/openchart-core';
-import { deepMergeSpec, isMapSpec } from '@opendata-ai/openchart-core';
-import { createMap, type MapInstance, type MapMountOptions } from '../map-mount';
-import { type ChartInstance, createChart, type MountOptions } from '../mount';
-import { canTransitionSpecShape } from '../transition';
-import {
-  type Camera,
-  camerasClose,
-  dampCamera,
-  FULL_VIEW,
-  fitTarget,
-  interpolateCamera,
-  scrubCamera,
-  type ViewBoxSize,
-} from './camera-math';
-import { crossfadeUpdate } from './crossfade';
-import { isDataCameraTarget, resolveCameraTarget } from './resolve-camera-target';
-import { createScrollDriver } from './scroll-driver';
-import { applyStoryCamera, readViewBox } from './story-camera';
-import { createTween, easingFns, storyMotion } from './tween';
-import type {
-  ChartStoryInstance,
-  ChartStoryOptions,
-  StorySpec,
-  StorySpecPatch,
-  StoryStep,
-} from './types';
-
-function prefersReducedMotion(): boolean {
-  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false;
-  try {
-    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-  } catch {
-    return false;
-  }
-}
-
-/** Merge a step's `highlight` sugar into its `spec` patch as `encoding.color.highlight`. */
-function stepToPatch(step: StoryStep): StorySpecPatch {
-  let patch = step.spec ?? {};
-  if ('highlight' in step) {
-    // `highlight: null` clears a highlight set by an earlier step. It must map
-    // to `[]` (not `undefined`): deep-merge skips `undefined`, so `?? undefined`
-    // would leave the prior step's highlight in place. An empty array is a real
-    // value that replaces it, and the engine reads `highlight.length > 0` as
-    // active, so `[]` reads as "no highlight."
-    const highlight = step.highlight === null ? [] : (step.highlight ?? undefined);
-    patch = deepMergeSpec(patch, {
-      encoding: { color: { highlight } },
-    });
-  }
-  return patch;
-}
-
-/** Apply patches 0..index (inclusive) onto the base spec, cumulatively. */
-function resolveSpecAtStep(base: StorySpec, steps: StoryStep[], index: number): StorySpec {
-  let spec: StorySpec = base;
-  for (let i = 0; i <= index && i < steps.length; i++) {
-    spec = deepMergeSpec(spec, stepToPatch(steps[i]!));
-  }
-  return spec;
-}
-
-/**
- * Create a scrollytelling story bound to a container. Mounts a chart with
- * the base spec, then drives it through cumulative patch steps as the
- * reader scrolls (or via `goTo`).
- *
- * `editMode` (any of `onEdit`/`onSelect`/`onDeselect`/`onTextEdit` on
- * `mountOptions`) and an active story are mutually exclusive in v1: passing
- * both warns once and disables the story's own drive loop, matching the
- * seriesSearch/edit-mode precedent in `mount.ts`.
- */
-export function createChartStory<TData extends DataRow = DataRow>(
-  container: HTMLElement,
-  options: ChartStoryOptions<TData>,
-  mountOptions?: MountOptions,
-): ChartStoryInstance {
-  const { spec, steps, triggerPosition = 0.4, cameraMode = 'step' } = options;
-  // The story machinery is spec-shape agnostic (it only deep-merges patches
-  // and hands specs to `update()`, which accepts the non-generic union).
-  // Widen once here so the internal helpers don't have to thread `TData`
-  // through a discriminated union that TS can't narrow across variants.
-  const baseSpec = spec as StorySpec;
-  const isMap = isMapSpec(baseSpec as unknown as Record<string, unknown>);
-
-  if (isMap && cameraMode === 'scrub') {
-    console.warn(
-      '[openchart] cameraMode: "scrub" is not supported for map stories; falling back to "step" mode. Map camera is driven via geo.focus patches in the spec.',
-    );
-  }
-
-  if (isMap && steps.some((s) => s.camera)) {
-    console.warn(
-      '[openchart] step.camera is ignored for map stories. Drive the map camera via geo.focus patches in the spec instead.',
-    );
-  }
-
-  const editModeRequested = !!(
-    mountOptions?.onEdit ||
-    mountOptions?.onSelect ||
-    mountOptions?.onDeselect ||
-    mountOptions?.onTextEdit
-  );
-  if (editModeRequested) {
-    console.warn(
-      '[openchart] a chart story and edit mode are mutually exclusive; the story will not drive updates while editing callbacks are active.',
-    );
-  }
-
-  let currentStep = -1;
-  let destroyed = false;
-
-  const initialSpec = resolveSpecAtStep(baseSpec, steps, 0);
-
-  // Branch: map vs chart mount
-  let instance: ChartInstance | MapInstance;
-  if (isMap) {
-    // Not a spread: MapMountOptions callback signatures differ from MountOptions.
-    // When adding fields to MapMountOptions, check if they should transfer here.
-    const mapOpts: MapMountOptions = {
-      theme: mountOptions?.theme,
-      darkMode: mountOptions?.darkMode,
-      watermark: mountOptions?.watermark,
-      responsive: mountOptions?.responsive,
-    };
-    instance = createMap(container, initialSpec as MapSpec, mapOpts);
-  } else {
-    instance = createChart(container, initialSpec as Exclude<StorySpec, MapSpec>, mountOptions);
-  }
-
-  // Chart camera infra (not used for maps)
-  const cameraTween = isMap
-    ? null
-    : createTween<Camera>({
-        initial: { cx: 0, cy: 0, k: 1 },
-        lerp: interpolateCamera,
-        duration: storyMotion.camera,
-        ease: easingFns.easeInOutCubic,
-        onFrame: (camera) => {
-          const vb = readViewBox(container);
-          if (vb) applyStoryCamera(container, camera, vb);
-        },
-      });
-
-  /** Fit a step's camera (data-coordinate or raw target, or full view) into the viewBox. */
-  function fittedCameraForStep(step: StoryStep | undefined, vb: ViewBoxSize): Camera {
-    if (!step?.camera) return fitTarget(FULL_VIEW(vb), vb);
-    const target = isDataCameraTarget(step.camera)
-      ? resolveCameraTarget((instance as ChartInstance).layout, step.camera)
-      : step.camera;
-    return fitTarget(target, vb);
-  }
-
-  // ---- Scrub-mode camera: self-stopping damping loop toward a live target ---
-  // Step mode eases discretely on step change (the tween above). Scrub mode
-  // reads continuous `stepProgress` and dwells on the active target through a
-  // hold zone, transitioning in the tail of the span. The two modes never run
-  // at once; the settle loop and the step tween are mutually exclusive drivers.
-  let scrubCurrent: Camera | null = null;
-  let scrubTarget: Camera | null = null;
-  let settleRaf = 0;
-  let settling = false;
-
-  // Memoized per-step fitted cameras for scrub mode. The fit depends only on
-  // the current layout (rebuilt on instance.update) and the viewBox size, so
-  // recomputing it on every scroll frame is wasted work. Cache keyed on the
-  // layout reference plus the viewBox dimensions; invalidate when either moves.
-  let fittedCache: Camera[] | null = null;
-  let fittedCacheLayout: unknown = null;
-  let fittedCacheVb: ViewBoxSize | null = null;
-
-  function fittedCamerasForScrub(vb: ViewBoxSize): Camera[] {
-    if (
-      fittedCache &&
-      fittedCacheLayout === (instance as ChartInstance).layout &&
-      fittedCacheVb &&
-      fittedCacheVb.width === vb.width &&
-      fittedCacheVb.height === vb.height
-    ) {
-      return fittedCache;
-    }
-    fittedCache = steps.map((step) => fittedCameraForStep(step, vb));
-    fittedCacheLayout = (instance as ChartInstance).layout;
-    fittedCacheVb = vb;
-    return fittedCache;
-  }
-
-  function stopSettle(): void {
-    if (settling) {
-      cancelAnimationFrame(settleRaf);
-      settling = false;
-    }
-  }
-
-  function startSettle(): void {
-    if (settling) return;
-    settling = true;
-    let last = performance.now();
-    const tick = (now: number): void => {
-      const target = scrubTarget;
-      const current = scrubCurrent;
-      const vb = readViewBox(container);
-      if (!target || !current || !vb) {
-        settling = false;
-        return;
-      }
-      const dt = Math.min(now - last, 64);
-      last = now;
-      const next = dampCamera(current, target, storyMotion.cameraTau, dt);
-      scrubCurrent = next;
-      applyStoryCamera(container, next, vb);
-      if (camerasClose(next, target)) {
-        scrubCurrent = target;
-        applyStoryCamera(container, target, vb);
-        settling = false;
-        return;
-      }
-      settleRaf = requestAnimationFrame(tick);
-    };
-    settleRaf = requestAnimationFrame(tick);
-  }
-
-  /** Step-mode camera: retargetable eased tween on step change. */
-  function applyCameraForStep(step: StoryStep | undefined, snap: boolean): void {
-    if (!cameraTween) return;
-    const vb = readViewBox(container);
-    if (!vb) return;
-    cameraTween.to(fittedCameraForStep(step, vb), { snap: snap || prefersReducedMotion() });
-  }
-
-  /** Scrub-mode camera: continuous, driven by the scroll frame's stepProgress. */
-  function applyScrubCamera(frame: { step: number; stepProgress: number }): void {
-    const vb = readViewBox(container);
-    if (!vb) return;
-    const fitted = fittedCamerasForScrub(vb);
-    if (fitted.length === 0) return;
-
-    if (prefersReducedMotion()) {
-      const clamped = Math.min(Math.max(frame.step, 0), fitted.length - 1);
-      stopSettle();
-      scrubCurrent = fitted[clamped]!;
-      applyStoryCamera(container, scrubCurrent, vb);
-      return;
-    }
-
-    scrubTarget = scrubCamera(
-      frame.step,
-      frame.stepProgress,
-      fitted,
-      0.65,
-      easingFns.easeInOutCubic,
-    );
-    if (scrubCurrent === null) scrubCurrent = scrubTarget;
-    startSettle();
-  }
-
-  function goTo(index: number): void {
-    if (destroyed) return;
-    const clamped = Math.max(0, Math.min(index, steps.length - 1));
-    if (clamped === currentStep) return;
-
-    const isFirst = currentStep === -1;
-    currentStep = clamped;
-
-    const nextSpec = resolveSpecAtStep(baseSpec, steps, clamped);
-
-    if (isMap) {
-      // Maps always apply directly: update handles fill + camera via geo.focus
-      (instance as MapInstance).update(nextSpec as MapSpec);
-      return;
-    }
-
-    const prevSpec = isFirst ? null : resolveSpecAtStep(baseSpec, steps, clamped - 1);
-
-    const willLikelyMorph =
-      !isFirst &&
-      !editModeRequested &&
-      prevSpec !== null &&
-      canTransitionSpecShape(prevSpec, nextSpec);
-
-    const applyUpdate = () =>
-      (instance as ChartInstance).update(nextSpec as Exclude<StorySpec, MapSpec>);
-
-    if (isFirst || willLikelyMorph || editModeRequested) {
-      applyUpdate();
-    } else {
-      // Outside the morph gate (re-encode, type change, etc.): no step may
-      // visibly snap, so crossfade the whole chart instead.
-      crossfadeUpdate(container, applyUpdate, { reducedMotion: prefersReducedMotion() });
-    }
-
-    // Step mode drives the camera on each discrete step change. Scrub mode
-    // drives it continuously from the scroll frame instead (see the scroll
-    // subscription below), so it skips the discrete step tween here.
-    if (cameraMode === 'step') applyCameraForStep(steps[clamped], isFirst);
-  }
-
-  const scrollDriver = editModeRequested ? null : createScrollDriver({ triggerPosition });
-  let unsubscribeScroll: (() => void) | null = null;
-  if (scrollDriver) {
-    unsubscribeScroll = scrollDriver.progress.subscribe((frame) => {
-      if (frame.step < 0) return;
-      // Discrete spec steps always advance at step boundaries; the v1 non-goal
-      // is continuous DATA morph scrubbing, not camera scrub. In scrub mode the
-      // camera additionally follows the continuous frame.
-      goTo(frame.step);
-      if (!isMap && cameraMode === 'scrub') applyScrubCamera(frame);
-    });
-  }
-
-  return {
-    goTo,
-    registerStep(index, el) {
-      scrollDriver?.registerStep(index, el);
-      return (nextEl: HTMLElement | null) => scrollDriver?.registerStep(index, nextEl);
-    },
-    setContainer(el) {
-      scrollDriver?.setContainer(el);
-    },
-    get currentStep() {
-      return currentStep;
-    },
-    get totalSteps() {
-      return steps.length;
-    },
-    destroy() {
-      if (destroyed) return;
-      destroyed = true;
-      unsubscribeScroll?.();
-      scrollDriver?.destroy();
-      cameraTween?.cancel();
-      stopSettle();
-      instance.destroy();
-    },
-  };
-}

package/src/story/crossfade.ts

@@ -1,70 +0,0 @@
-/**
- * Whole-chart crossfade fallback for story steps whose spec diff falls
- * outside the data-update-transitions morph gate (`canTransition` in
- * `../transition.ts`): re-encodes, type changes, and anything else that
- * would otherwise instant-snap. No step in a story may visibly snap, so
- * this ghosts the current rendered SVG over the container, lets
- * `ChartInstance.update()` perform its normal instant swap underneath,
- * then fades the ghost out to reveal the new state.
- *
- * This is deliberately NOT the mark-morphing transition driver: it never
- * interpolates geometry, only opacity. See the animation-clock ownership
- * note in the scrollytelling plan -- the transitions driver owns mark
- * morphing, this owns the pixel-level fallback when that driver declines.
- */
-
-import { storyMotion } from './tween';
-
-export interface CrossfadeOptions {
-  /** Fade duration in ms. Default `storyMotion.crossfade`. */
-  duration?: number;
-  /** Skip the fade and swap instantly (reduced motion). */
-  reducedMotion?: boolean;
-}
-
-/**
- * Ghost the container's current SVG, run `applyUpdate` (which mutates the
- * container to its next state), then fade the ghost out.
- */
-export function crossfadeUpdate(
-  container: HTMLElement,
-  applyUpdate: () => void,
-  options: CrossfadeOptions = {},
-): void {
-  const duration = options.duration ?? storyMotion.crossfade;
-  const svg = container.querySelector('svg');
-
-  if (options.reducedMotion || !svg || duration <= 0) {
-    applyUpdate();
-    return;
-  }
-
-  const ghost = svg.cloneNode(true) as SVGElement;
-  ghost.setAttribute('aria-hidden', 'true');
-  ghost.style.position = 'absolute';
-  ghost.style.inset = '0';
-  ghost.style.width = '100%';
-  ghost.style.height = '100%';
-  ghost.style.pointerEvents = 'none';
-  ghost.style.transition = `opacity ${duration}ms ease-out`;
-  ghost.style.opacity = '1';
-
-  const priorPosition = container.style.position;
-  container.style.position = priorPosition || 'relative';
-  container.appendChild(ghost);
-
-  applyUpdate();
-
-  // Force layout so the transition starts from opacity: 1 before dropping.
-  void ghost.getBoundingClientRect();
-  ghost.style.opacity = '0';
-
-  const cleanup = () => {
-    ghost.remove();
-    if (!priorPosition) container.style.position = '';
-  };
-  ghost.addEventListener('transitionend', cleanup, { once: true });
-  // Safety net in case transitionend never fires (e.g. element removed by
-  // an intervening render before the transition completes).
-  setTimeout(cleanup, duration + 100);
-}