@1agh/maude 0.19.1 → 0.21.0

package/plugins/design/dev-server/canvas-lib.tsx

@@ -81,10 +81,22 @@ import {
   useState,
 } from 'react';
 
+import {
+  AnimatePresence as _MotionAnimatePresence,
+  motion as _motionImpl,
+  useReducedMotion as _useReducedMotion,
+} from 'motion/react';
+
 import { CanvasShell } from './canvas-shell.tsx';
+import {
+  buildMoveArtboardsRecord,
+  diffLayoutPositions,
+} from './commands/move-artboards-command.ts';
 import { type DragState, useArtboardDrag } from './use-artboard-drag.tsx';
+import { CollabProvider, canvasSlugFromPath } from './use-collab.tsx';
 import { useSelectionSetOptional } from './use-selection-set.tsx';
 import { ToolProvider, useToolModeOptional } from './use-tool-mode.tsx';
+import { UndoStackProvider, useUndoSinks, useUndoStackOptional } from './use-undo-stack.tsx';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Module constants
@@ -216,7 +228,7 @@ button.dc-artboard-label {
   display: block;
   width: 100%;
 }
-button.dc-artboard-label:focus-visible { outline: 2px solid var(--accent, #d63b1f); outline-offset: -2px; }
+button.dc-artboard-label:focus-visible { outline: 2px solid var(--maude-hud-accent, #d63b1f); outline-offset: -2px; }
 /* Active-artboard ring is in canvas-shell HALO_CSS (subtle 1 px tint). */
 /* Phase 4.2 — drag chrome. */
 .dc-canvas[data-active-tool="move"] .dc-artboard-label { cursor: grab; }
@@ -448,6 +460,26 @@ interface PersistedArtboardLayout {
   y: number;
 }
 
+/**
+ * Phase 20 (DDR-050) — last timestamp at which THIS iframe wrote canvas
+ * meta. Read by `use-undo-stack.tsx` to discriminate self-echo fs:json
+ * events from genuine external edits.
+ */
+declare global {
+  interface Window {
+    __maude_last_meta_self_write_at?: number;
+  }
+}
+
+const META_SELF_ECHO_WINDOW_MS = 500;
+
+/** Recent enough to be our own PATCH echoing back through fs-watch. */
+export function isMetaSelfEcho(now: number = Date.now()): boolean {
+  if (typeof window === 'undefined') return false;
+  const last = window.__maude_last_meta_self_write_at ?? 0;
+  return now - last < META_SELF_ECHO_WINDOW_MS;
+}
+
 function patchCanvasMeta(patch: {
   viewport?: ViewportState;
   layout?: { artboards: ArtboardRect[] };
@@ -469,6 +501,10 @@ function patchCanvasMeta(patch: {
       })),
     };
   }
+  // Stamp the self-write timestamp BEFORE the fetch so the round-trip
+  // (PATCH → server write → fs:json broadcast → iframe message) lands
+  // safely inside the echo window even on a fast network.
+  window.__maude_last_meta_self_write_at = Date.now();
   fetch('/_api/canvas-meta', {
     method: 'PATCH',
     headers: { 'content-type': 'application/json' },
@@ -700,9 +736,22 @@ export function useViewportController(opts: ViewportControllerOptions): Viewport
     [applyViewport]
   );
 
+  // Forward-decl ref — fit / reset run animations that need `animateTo`, but
+  // `animateTo` is declared further down (depends on applyViewport). Resolve
+  // the ordering with a ref the animateTo callback writes to on definition.
+  const animateToRef = useRef<((t: ViewportState, d?: number) => void) | null>(null);
+
+  // T33 — programmatic zoom is eased. Direct user-driven gestures
+  // (wheel, pinch, drag-to-pan) still call `applyViewport` directly so
+  // input feel stays 1:1 with the cursor; only fit/reset/zoom-to-rect
+  // ease over 200 ms. `animateTo` honors `prefers-reduced-motion` and
+  // returns instantly under that media query.
+  const PROGRAMMATIC_EASE_MS = 200;
   const fit = useCallback(() => {
     const next = computeFitRef.current();
-    applyViewport(next);
+    const a = animateToRef.current;
+    if (a) a(next, PROGRAMMATIC_EASE_MS);
+    else applyViewport(next);
   }, [applyViewport]);
 
   const reset = useCallback(() => {
@@ -713,8 +762,15 @@ export function useViewportController(opts: ViewportControllerOptions): Viewport
     }
     const cx = host.clientWidth / 2;
     const cy = host.clientHeight / 2;
-    zoomAt(1 / vpRef.current.zoom, cx, cy);
-  }, [hostRef, applyViewport, zoomAt]);
+    const v = vpRef.current;
+    // Target: same world-coord under cursor, zoom = 1.
+    const wx = (cx - v.x) / v.zoom;
+    const wy = (cy - v.y) / v.zoom;
+    const target: ViewportState = { x: cx - wx, y: cy - wy, zoom: 1 };
+    const a = animateToRef.current;
+    if (a) a(target, PROGRAMMATIC_EASE_MS);
+    else applyViewport(target);
+  }, [hostRef, applyViewport]);
 
   const zoomIn = useCallback(() => {
     const host = hostRef.current;
@@ -767,6 +823,10 @@ export function useViewportController(opts: ViewportControllerOptions): Viewport
     [applyViewport]
   );
 
+  // Keep the ref pointed at the latest `animateTo` so the earlier-declared
+  // fit / reset callbacks can call it without circular dependency.
+  animateToRef.current = animateTo;
+
   const jumpTo = useCallback(
     (rect: ArtboardRect) => {
       const host = hostRef.current;
@@ -844,7 +904,13 @@ export function useViewportController(opts: ViewportControllerOptions): Viewport
       // without a physical Ctrl press — so the same branch covers both
       // Ctrl+wheel (mouse) and pinch-zoom (trackpad).
       if (e.ctrlKey || e.metaKey) {
-        const factor = Math.exp(-e.deltaY * WHEEL_ZOOM_K);
+        // T32 — clamp deltaY into [-50, 50] before the exp() to bring
+        // trackpad-pinch (small per-frame delta) and mouse-wheel (one
+        // notch = ±100) onto the same perceived-speed curve. Mouse-wheel
+        // users still get smooth zoom (clamped notches accumulate at the
+        // same exp rate), trackpad-pinch users no longer outpace them.
+        const clamped = Math.max(-50, Math.min(50, e.deltaY));
+        const factor = Math.exp(-clamped * WHEEL_ZOOM_K);
         zoomAt(factor, cx, cy);
         return;
       }
@@ -1052,11 +1118,24 @@ export function useViewportControllerContext(): ViewportControllerHandle | null
 // drag). A single source-of-truth: only one drag can be active at a time, so
 // the bus holds a single DragState. Each DCArtboard's hook writes here when
 // non-idle and resets to idle on release.
+/** Optional metadata accompanying a position commit. */
+export interface CommitPositionsOptions {
+  /**
+   * HUD / undo-stack label override. Default = `"move N artboard(s)"`.
+   * Distribute / align gestures pass their own label so undo HUD reads
+   * `"Undo: equal-space 4 artboards"` instead of `"Undo: move 4 artboards"`.
+   */
+  label?: string;
+}
+
 interface DragStateBus {
   current: DragState;
   setCurrent: (s: DragState) => void;
   /** Commit drag positions — DesignCanvas wires this to patchCanvasMeta. */
-  commitPositions: (moved: { id: string; x: number; y: number }[]) => void;
+  commitPositions: (
+    moved: { id: string; x: number; y: number }[],
+    opts?: CommitPositionsOptions
+  ) => void;
 }
 
 const DragStateContext = createContext<DragStateBus | null>(null);
@@ -1085,11 +1164,29 @@ interface DesignCanvasProps {
  * via `useToolModeOptional` (hand-mode bare-drag pan).
  */
 export function DesignCanvas(props: DesignCanvasProps) {
-  return (
+  // Phase 20 — per-canvas undo/redo stack (DDR-050 rev 2). The provider
+  // wraps both DesignCanvasInner (so artboard commits push records) AND
+  // the CanvasShell tree (so input-router Cmd+Z / Cmd+Shift+Z + the HUD
+  // share the same context). Stack state is keyed by canvas file path in
+  // `window.top.__maude_undo_stacks` so it survives canvas switches —
+  // close Foo.tsx, open Bar.tsx, come back to Foo.tsx → history intact.
+  const canvasFile = readCanvasMetaFile() ?? undefined;
+  // Phase 8 / DDR-051 — open a Yjs collab session for this canvas iff we can
+  // derive a stable slug. The slug must match `api.fileSlug` server-side so
+  // both ends agree on the room key. When the canvas was opened via a URL
+  // that doesn't yield a slug (e.g. preview iframes without `canvas=`),
+  // CollabProvider is omitted; useCollab() falls back gracefully to null.
+  const collabSlug = canvasSlugFromPath(canvasFile);
+  const inner = (
     <ToolProvider>
       <DesignCanvasInner {...props} />
     </ToolProvider>
   );
+  return (
+    <UndoStackProvider canvasFile={canvasFile}>
+      {collabSlug ? <CollabProvider slug={collabSlug}>{inner}</CollabProvider> : inner}
+    </UndoStackProvider>
+  );
 }
 DesignCanvas.displayName = 'DesignCanvas';
 
@@ -1141,6 +1238,22 @@ function DesignCanvasInner({ children, controls }: DesignCanvasProps) {
     setArtboards(initialArtboards());
   }, [initialArtboards]);
 
+  // Phase 8 — foreign canvas-meta change. The shell-level HMR client
+  // re-fetches `<canvas>.meta.json` and dispatches `maude:meta-refreshed`
+  // when *another* tab PATCHed the layout (drag, distribute, align). We
+  // re-apply positions in-place — no full reload — so the user's tool mode,
+  // undo stack, scroll, and selection state survive. Self-writes are
+  // suppressed at the dispatch site via the `__maude_last_meta_self_write_at`
+  // echo timestamp.
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const onRefresh = () => {
+      setArtboards(initialArtboards());
+    };
+    document.addEventListener('maude:meta-refreshed', onRefresh);
+    return () => document.removeEventListener('maude:meta-refreshed', onRefresh);
+  }, [initialArtboards]);
+
   // Stable refs so the controller's callbacks always see the latest values.
   const artboardsRef = useRef(artboards);
   artboardsRef.current = artboards;
@@ -1239,20 +1352,56 @@ function DesignCanvasInner({ children, controls }: DesignCanvasProps) {
   // hook is non-idle; SnapGuideOverlay (in canvas-shell) reads guides.
   const [dragCurrent, setDragCurrent] = useState<DragState>({ kind: 'idle' });
 
-  const commitArtboardPositions = useCallback((moved: { id: string; x: number; y: number }[]) => {
-    const movedById = new Map(moved.map((m) => [m.id, m]));
-    const next = artboardsRef.current.map((r) => {
-      const m = movedById.get(r.id);
-      if (m) return { ...r, x: m.x, y: m.y };
-      return r;
-    });
-    // Optimistic local update — DOM reflects the new position the moment
-    // the drag drops, no iframe reload required. The PATCH below catches
-    // the server up; if it fails we already logged it via `patchCanvasMeta`.
-    setArtboards(next);
-    patchCanvasMeta({ layout: { artboards: next } });
+  const undoStack = useUndoStackOptional();
+  const undoSinks = useUndoSinks();
+  // Stable ref so the commit callback (memoized once, on mount) always reads
+  // the latest stack value without re-creating the callback on every render.
+  const undoStackRef = useRef(undoStack);
+  undoStackRef.current = undoStack;
+
+  /**
+   * Applies a full artboard layout: optimistic local React state update +
+   * server PATCH. Used as the `layoutPatchFn` sink registered with the
+   * undo stack — both the initial commit (do) and every undo/redo replay
+   * route through here, so React state always tracks the server.
+   */
+  const applyArtboardLayout = useCallback((layout: unknown) => {
+    setArtboards(layout as ArtboardRect[]);
+    patchCanvasMeta({ layout: { artboards: layout as ArtboardRect[] } });
   }, []);
 
+  // Register the layout patch sink with the undo provider so the rebuilt
+  // MoveArtboardsCommand (after a canvas switch + return) can apply layouts
+  // through THIS iframe's React state, not the gone iframe's stale closures.
+  useEffect(() => {
+    undoSinks.setSink('layoutPatchFn', applyArtboardLayout);
+    return () => undoSinks.setSink('layoutPatchFn', undefined);
+  }, [undoSinks, applyArtboardLayout]);
+
+  const commitArtboardPositions = useCallback(
+    (moved: { id: string; x: number; y: number }[], opts?: CommitPositionsOptions) => {
+      const movedById = new Map(moved.map((m) => [m.id, m]));
+      const before = artboardsRef.current;
+      const next = before.map((r) => {
+        const m = movedById.get(r.id);
+        if (m) return { ...r, x: m.x, y: m.y };
+        return r;
+      });
+      // Phase 20 — skip pushing no-op drags (click-without-movement). The
+      // user got back what they had, no edit happened, undo would do nothing.
+      if (!diffLayoutPositions(before, next)) return;
+      const record = buildMoveArtboardsRecord({
+        before: before.map((r) => ({ id: r.id, x: r.x, y: r.y, w: r.w, h: r.h })),
+        after: next.map((r) => ({ id: r.id, x: r.x, y: r.y, w: r.w, h: r.h })),
+        ...(opts?.label ? { label: opts.label } : {}),
+      });
+      // push() invokes the rebuilt cmd.do() = applyArtboardLayout(next) BEFORE
+      // updating the stack, so the optimistic local + PATCH flow is preserved.
+      void undoStackRef.current.push(record);
+    },
+    []
+  );
+
   const dragBus = useMemo<DragStateBus>(
     () => ({
       current: dragCurrent,
@@ -1348,7 +1497,7 @@ export function DCArtboard({
   children: ReactNode;
 }) {
   const ctx = useWorldContext();
-  const controller = useViewportControllerContext();
+  const _controller = useViewportControllerContext();
   const toolMode = useToolModeOptional();
   const selSet = useSelectionSetOptional();
   const dragBus = useDragStateContext();
@@ -1394,9 +1543,11 @@ export function DCArtboard({
     );
   }
   const isActive = ctx.activeArtboardId === id;
-  const onFocus = () => {
-    if (controller) controller.jumpTo(rect);
-  };
+  // G2v2 — earlier the label single-click called `controller.jumpTo(rect)`,
+  // auto-zooming on every click. Per post-Wave-3.5 feedback this was
+  // surprising. The label button stays for a11y (focus + screen-reader
+  // label) but no longer mutates the viewport. Cmd+1 + the zoom HUD still
+  // expose the manual zoom path.
 
   // Am I involved in the current drag (as leader or follower)?
   const busDrag = dragBus?.current;
@@ -1431,12 +1582,7 @@ export function DCArtboard({
       style={{ left: liveX, top: liveY, width: rect.w, height: rect.h }}
       {...handleProps}
     >
-      <button
-        type="button"
-        className="dc-artboard-label sku"
-        onClick={onFocus}
-        aria-label={`Focus artboard ${label}`}
-      >
+      <button type="button" className="dc-artboard-label sku" aria-label={`Artboard ${label}`}>
         {label}
       </button>
       <div className="dc-artboard-body">{children}</div>
@@ -1616,8 +1762,8 @@ const OVERLAY_CSS = `
    outline-only. Reads from a glance as "what slice of the world you're on". */
 .dc-mm-vp {
   position: absolute;
-  background: color-mix(in oklab, var(--accent, #d63b1f) 12%, transparent);
-  border: 1.5px solid var(--accent, #d63b1f);
+  background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 12%, transparent);
+  border: 1.5px solid var(--maude-hud-accent, #d63b1f);
   border-radius: 1px;
   pointer-events: none;
 }
@@ -1653,7 +1799,7 @@ const OVERLAY_CSS = `
 }
 .dc-zoom-tb button:last-child { border-right: 0; }
 .dc-zoom-tb button:hover { background: color-mix(in oklab, var(--fg-0, #1c1917) 5%, transparent); }
-.dc-zoom-tb button:focus-visible { outline: 2px solid var(--accent, #d63b1f); outline-offset: -2px; }
+.dc-zoom-tb button:focus-visible { outline: 2px solid var(--maude-hud-accent, #d63b1f); outline-offset: -2px; }
 .dc-zoom-tb-pct { font-variant-numeric: tabular-nums; min-width: 52px; }
 `.trim();
 
@@ -2088,3 +2234,359 @@ export function useArtboardBounds(ref: RefObject<HTMLElement | null>): {
 // Re-export `useRef` so `useArtboardBounds` consumers can keep a single
 // import line from `@maude/canvas-lib`.
 export { useRef };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Motion subsystem (Phase 3.7 / DDR-049 — Motion One is the canonical runtime)
+//
+// These helpers are tree-shakeable. A canvas that does not import any of them
+// pays no bundle cost (motion/react is externalised via RUNTIME_PACKAGES, so
+// even when imported the byte cost lives in a single shared runtime bundle,
+// not per-canvas).
+//
+// Roles map 1:1 to the 8 motion-vocabulary names enforced by motion-critic +
+// design-system-keeper. Each role binds to a DS duration + easing token from
+// colors_and_type.css; useMotionTokens() reads the live CSS custom property
+// values so the binding survives token edits without rebuilding canvas-lib.
+//
+// Bounded-geometry guarantee — every <MotionDemo> root sets `overflow: hidden`
+// in inline style. That defends against sparkle-on-tile overflow regardless of
+// the host class chrome. See SUB-AGENT-PROMPTS.md → ANIMATION SAFETY.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type MotionRole =
+  | 'flip'
+  | 'panel'
+  | 'route'
+  | 'soft'
+  | 'spring'
+  | 'scroll'
+  | 'drag'
+  | 'presence';
+
+export type MotionLoop = 'always' | 'hover' | 'once';
+
+interface RoleConfig {
+  durationToken: string;
+  easingToken: string;
+  keyframes: Record<string, number[]>;
+  fallbackMs: number;
+}
+
+export const MOTION_ROLE_DEFAULTS: Record<MotionRole, RoleConfig> = {
+  flip: {
+    durationToken: '--dur-flip',
+    easingToken: '--ease-out',
+    keyframes: { y: [0, -12, 0] },
+    fallbackMs: 220,
+  },
+  panel: {
+    durationToken: '--dur-panel',
+    easingToken: '--ease-in-out',
+    keyframes: { x: [-80, 0, -80] },
+    fallbackMs: 320,
+  },
+  route: {
+    durationToken: '--dur-route',
+    easingToken: '--ease-out',
+    keyframes: { opacity: [0, 1, 0], scale: [0.92, 1, 0.92] },
+    fallbackMs: 480,
+  },
+  soft: {
+    durationToken: '--dur-soft',
+    easingToken: '--ease-out',
+    keyframes: { opacity: [0, 1, 0] },
+    fallbackMs: 160,
+  },
+  spring: {
+    durationToken: '--dur-panel',
+    easingToken: 'spring',
+    keyframes: { y: [0, -16, 0] },
+    fallbackMs: 320,
+  },
+  scroll: {
+    durationToken: '--dur-route',
+    easingToken: '--ease-in-out',
+    keyframes: { x: [0, 24, 0] },
+    fallbackMs: 480,
+  },
+  drag: {
+    durationToken: '--dur-flip',
+    easingToken: '--ease-out',
+    keyframes: { rotate: [0, 4, 0] },
+    fallbackMs: 220,
+  },
+  presence: {
+    durationToken: '--dur-soft',
+    easingToken: '--ease-out',
+    keyframes: { opacity: [0, 1], scale: [0.9, 1] },
+    fallbackMs: 160,
+  },
+};
+
+/**
+ * Reads --dur-* + --ease-* CSS custom properties from documentElement and
+ * returns a plain map suitable for plugging into motion/react's transition
+ * config. ms values parsed to numbers; easing tokens returned as strings (the
+ * raw token value, e.g. "cubic-bezier(0, 0, 0.2, 1)" — motion/react accepts
+ * the string form).
+ */
+export function useMotionTokens(): {
+  durations: Record<string, number>;
+  easings: Record<string, string>;
+} {
+  const [snap, setSnap] = useState(() => readMotionTokensOnce());
+  useEffect(() => {
+    setSnap(readMotionTokensOnce());
+    if (typeof MutationObserver === 'undefined') return;
+    const obs = new MutationObserver(() => setSnap(readMotionTokensOnce()));
+    obs.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-theme', 'data-reduced-motion'],
+    });
+    return () => obs.disconnect();
+  }, []);
+  return snap;
+}
+
+function readMotionTokensOnce(): {
+  durations: Record<string, number>;
+  easings: Record<string, string>;
+} {
+  if (typeof window === 'undefined' || typeof getComputedStyle === 'undefined') {
+    return { durations: {}, easings: {} };
+  }
+  const cs = getComputedStyle(document.documentElement);
+  const durations: Record<string, number> = {};
+  const easings: Record<string, string> = {};
+  const durKeys = ['--dur-flip', '--dur-panel', '--dur-route', '--dur-soft'];
+  const easeKeys = ['--ease-out', '--ease-in', '--ease-in-out'];
+  for (const k of durKeys) {
+    const raw = cs.getPropertyValue(k).trim();
+    if (!raw) continue;
+    const n = Number.parseFloat(raw);
+    if (Number.isFinite(n)) {
+      durations[k] = raw.endsWith('s') && !raw.endsWith('ms') ? n * 1000 : n;
+    }
+  }
+  for (const k of easeKeys) {
+    const raw = cs.getPropertyValue(k).trim();
+    if (raw) easings[k] = raw;
+  }
+  return { durations, easings };
+}
+
+/**
+ * Maps a DS easing token name to the value motion/react's `transition.ease`
+ * accepts. Returns the live CSS string when readable, otherwise a sane default
+ * matching Material's "standard" curve.
+ */
+export function easingFromToken(
+  token: string,
+  easings: Record<string, string>
+): string | undefined {
+  const live = easings[token];
+  if (live) return live;
+  if (token === '--ease-out') return 'cubic-bezier(0, 0, 0.2, 1)';
+  if (token === '--ease-in') return 'cubic-bezier(0.4, 0, 1, 1)';
+  if (token === '--ease-in-out') return 'cubic-bezier(0.4, 0, 0.2, 1)';
+  return undefined;
+}
+
+interface MotionDemoProps {
+  role: MotionRole;
+  loop?: MotionLoop;
+  children?: ReactNode;
+  small?: boolean;
+  className?: string;
+  label?: string;
+}
+
+/**
+ * The foundational motion building block. Wraps motion/react's animated <div>
+ * with token-bound duration + easing + reduced-motion short-circuit.
+ *
+ * Default loop="always" so initial paint shows motion — the "looks dead at
+ * rest" failure mode is the regression Phase 3.7 exists to prevent.
+ */
+export function MotionDemo({
+  role,
+  loop = 'always',
+  children,
+  small = false,
+  className,
+  label,
+}: MotionDemoProps) {
+  const cfg = MOTION_ROLE_DEFAULTS[role];
+  const tokens = useMotionTokens();
+  const reduced = _useReducedMotion();
+  const durationMs = tokens.durations[cfg.durationToken] ?? cfg.fallbackMs;
+  const isSpring = cfg.easingToken === 'spring';
+  const ease = isSpring ? undefined : easingFromToken(cfg.easingToken, tokens.easings);
+  const repeat = reduced || loop === 'once' ? 0 : Number.POSITIVE_INFINITY;
+  const repeatType: 'reverse' | 'loop' = loop === 'always' ? 'reverse' : 'loop';
+  const animate = reduced ? undefined : cfg.keyframes;
+
+  return (
+    <div
+      className={`motion-demo${className ? ` ${className}` : ''}`}
+      data-role={role}
+      data-small={small ? 'true' : undefined}
+      style={{ overflow: 'hidden', position: 'relative' }}
+    >
+      <_motionImpl.div
+        animate={animate}
+        transition={{
+          duration: durationMs / 1000,
+          ease,
+          type: isSpring ? 'spring' : 'tween',
+          repeat,
+          repeatType,
+        }}
+        className="motion-demo__target"
+        aria-label={label}
+        style={small ? { width: 32, height: 32 } : undefined}
+      >
+        {children ?? <div className="motion-demo__chip" />}
+      </_motionImpl.div>
+    </div>
+  );
+}
+
+interface MotionTrackProps {
+  children: ReactNode;
+  staggerMs?: number;
+  className?: string;
+}
+
+/**
+ * Row container with CSS animation-delay stagger between children.
+ */
+export function MotionTrack({ children, staggerMs = 40, className }: MotionTrackProps) {
+  const items = Array.isArray(children) ? children : [children];
+  return (
+    <div
+      className={`motion-track${className ? ` ${className}` : ''}`}
+      style={{ display: 'flex', gap: 12, alignItems: 'center' }}
+    >
+      {items.map((c, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: stagger row is index-positional by design; no reorder/insertion semantics
+        <div key={i} style={{ animationDelay: `${i * staggerMs}ms` }}>
+          {c}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+interface TokenPlaybackProps {
+  duration: string;
+  easing?: string;
+  label?: string;
+  keyframes?: Record<string, number[]>;
+}
+
+/**
+ * Click-to-fire single-shot replay chip. Used in the motion specimen so
+ * reviewers can probe a single token without hovering a card.
+ */
+export function TokenPlayback({
+  duration,
+  easing = '--ease-out',
+  label,
+  keyframes = { y: [0, -8, 0] },
+}: TokenPlaybackProps) {
+  const tokens = useMotionTokens();
+  const reduced = _useReducedMotion();
+  const durationMs = tokens.durations[duration] ?? 220;
+  const ease = easing === 'spring' ? undefined : easingFromToken(easing, tokens.easings);
+  const [tick, setTick] = useState(0);
+  const fire = useCallback(() => {
+    if (!reduced) setTick((n) => n + 1);
+  }, [reduced]);
+  return (
+    <button
+      type="button"
+      className="token-playback"
+      onClick={fire}
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 8,
+        fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+        fontSize: 12,
+        padding: '6px 10px',
+        border: '1px solid var(--border-1, currentColor)',
+        borderRadius: 4,
+        background: 'transparent',
+        color: 'inherit',
+        cursor: 'pointer',
+      }}
+    >
+      <span style={{ opacity: 0.6 }}>{label ?? duration}</span>
+      <_motionImpl.span
+        key={tick}
+        animate={tick === 0 ? undefined : keyframes}
+        transition={{
+          duration: durationMs / 1000,
+          ease,
+          type: easing === 'spring' ? 'spring' : 'tween',
+        }}
+        style={{
+          display: 'inline-block',
+          width: 8,
+          height: 8,
+          background: 'var(--accent, currentColor)',
+          borderRadius: '50%',
+        }}
+      />
+      <span style={{ fontVariantNumeric: 'tabular-nums' }}>{durationMs}ms</span>
+    </button>
+  );
+}
+
+/**
+ * Chrome toggle for the motion specimen — flips data-reduced-motion="true"
+ * on <html> so reviewers can eyeball both branches without OS settings.
+ * Inspection aid, never a replacement for prefers-reduced-motion.
+ */
+export function ReducedMotionToggle() {
+  const [on, setOn] = useState(false);
+  useEffect(() => {
+    const el = document.documentElement;
+    const initial = el.getAttribute('data-reduced-motion') === 'true';
+    setOn(initial);
+  }, []);
+  const toggle = useCallback(() => {
+    const el = document.documentElement;
+    const next = !on;
+    if (next) el.setAttribute('data-reduced-motion', 'true');
+    else el.removeAttribute('data-reduced-motion');
+    setOn(next);
+  }, [on]);
+  return (
+    <button
+      type="button"
+      className="reduced-motion-toggle"
+      onClick={toggle}
+      aria-pressed={on}
+      style={{
+        fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+        fontSize: 11,
+        padding: '4px 8px',
+        border: '1px solid var(--border-1, currentColor)',
+        borderRadius: 3,
+        background: on ? 'var(--accent, currentColor)' : 'transparent',
+        color: on ? 'var(--bg-0, white)' : 'inherit',
+        cursor: 'pointer',
+      }}
+    >
+      reduced-motion: {on ? 'on' : 'off'}
+    </button>
+  );
+}
+
+export {
+  _motionImpl as motion,
+  _useReducedMotion as useReducedMotion,
+  _MotionAnimatePresence as AnimatePresence,
+};