@1agh/maude 0.19.0 → 0.20.0

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

@@ -66,6 +66,7 @@
 
 import {
   type CSSProperties,
+  Fragment,
   type ReactNode,
   type PointerEvent as ReactPointerEvent,
   type RefObject,
@@ -80,10 +81,21 @@ 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 { 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
@@ -108,12 +120,63 @@ const ENGINE_CSS = `
   inset: 0;
   overflow: hidden;
   outline: none;
+  /* DDR-046 — snap-layer magenta is distinct from --accent so the snap chrome
+     never visually melts into the selection halo during a drag-snap gesture.
+     OKLCH default approximates FigJam magenta in the project's color space. */
+  --guide-magenta: oklch(62% 0.28 350);
   background-color: var(--bg-1, #f4f1ea);
   background-image:
     linear-gradient(var(--border-subtle, rgba(0,0,0,0.08)) 1px, transparent 1px),
     linear-gradient(90deg, var(--border-subtle, rgba(0,0,0,0.08)) 1px, transparent 1px);
   background-size: 24px 24px;
 }
+/* DDR-046 — Snap guides. Sibling kind = confident magenta + glow + distance
+   pill. Grid kind = lighter gray fallback, no pill. Width 2 px (up from 1 px)
+   so the line stays readable at zoom < 0.8. */
+.dc-snap-guide {
+  position: fixed;
+  pointer-events: none;
+  z-index: 6;
+  animation: dc-snap-spawn 80ms cubic-bezier(0.2, 0.8, 0.2, 1);
+  transform-origin: center;
+}
+.dc-snap-guide--sibling {
+  background: var(--guide-magenta, oklch(62% 0.28 350));
+  box-shadow: 0 0 4px color-mix(in oklab, var(--guide-magenta, oklch(62% 0.28 350)) 35%, transparent);
+}
+.dc-snap-guide--grid {
+  background: color-mix(in oklab, var(--fg-3, var(--fg-1, #4a3f30)) 40%, transparent);
+}
+.dc-snap-pill {
+  position: fixed;
+  pointer-events: none;
+  z-index: 7;
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 1;
+  color: #fff;
+  background: var(--guide-magenta, oklch(62% 0.28 350));
+  padding: 3px 6px;
+  border-radius: 3px;
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+  animation: dc-snap-pill-spawn 80ms cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+@keyframes dc-snap-spawn {
+  from { opacity: 0; transform: scaleY(0.92); }
+  to   { opacity: 1; transform: scaleY(1); }
+}
+@keyframes dc-snap-pill-spawn {
+  from { opacity: 0; transform: translate(-50%, -50%) scale(0.88); }
+  to   { opacity: 1; transform: translate(-50%, -50%) scale(1); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-snap-guide,
+  .dc-snap-pill {
+    animation: none !important;
+  }
+}
 .dc-canvas:focus { outline: none; }
 .dc-world {
   position: absolute;
@@ -129,8 +192,11 @@ const ENGINE_CSS = `
 .dc-canvas .dc-artboard {
   background: var(--bg-0, #ffffff);
   color: var(--fg-0, #2a2520);
-  border: 1px solid var(--fg-0, #2a2520);
-  box-shadow: 6px 6px 0 var(--fg-0, #2a2520);
+  /* Quiet frame chrome — FigJam Section / Figma Frame canonical. The Memphis
+     hard-shadow is the Maude brand on USER CONTENT inside artboards; the frame
+     itself stays calm so user content reads as loud. */
+  border: 1px solid color-mix(in oklab, var(--fg-0, #2a2520) 22%, transparent);
+  border-radius: 2px;
   display: flex;
   flex-direction: column;
   overflow: hidden;
@@ -166,25 +232,15 @@ button.dc-artboard-label:focus-visible { outline: 2px solid var(--accent, #d63b1
 /* Phase 4.2 — drag chrome. */
 .dc-canvas[data-active-tool="move"] .dc-artboard-label { cursor: grab; }
 .dc-canvas[data-active-tool="move"] .dc-artboard-label:active { cursor: grabbing; }
-.dc-canvas .dc-artboard.dc-dragging { opacity: 0.3; }
-.dc-canvas .dc-artboard-ghost {
-  position: absolute;
-  pointer-events: none;
-  opacity: 0.5;
-  background: var(--bg-0, #ffffff);
-  border: 1px solid var(--fg-0, #2a2520);
-  box-shadow: 6px 6px 0 var(--fg-0, #2a2520);
-  z-index: 4;
-}
-.dc-canvas .dc-artboard-ghost-label {
-  background: var(--bg-2, #e8e3d8);
-  border-bottom: 1px solid var(--fg-0, #2a2520);
-  padding: 6px 14px;
-  font-size: 10px;
-  letter-spacing: 0.06em;
-  text-transform: uppercase;
-  color: var(--fg-1, #4a3f30);
-  font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+/* Post-Wave-2 — direct artboard drag. The article itself updates its
+   inline left/top during drag (no ghost placeholder, no opacity fade on
+   the original). Compositor handles the pixel movement; halo + group
+   bbox naturally follow via getBoundingClientRect on the article. */
+.dc-canvas .dc-artboard.dc-dragging {
+  z-index: 5;
+  /* Keep the cursor consistent with the label's grabbing affordance even
+     when the pointer drifts off the label strip during the drag. */
+  cursor: grabbing;
 }
 `.trim();
 
@@ -237,6 +293,12 @@ function useWorldContext(): WorldContextValue | null {
   return useContext(WorldContext);
 }
 
+/** Read-only access to the artboard list + viewport state. Used by overlays
+ *  that need to operate on artboards directly (distribute, marquee, etc.). */
+export function useArtboardsContext(): WorldContextValue | null {
+  return useContext(WorldContext);
+}
+
 // Phase 5.1: annotations-layer needs the world `<div>` to portal a stroke SVG
 // inside it (so CSS zoom + translate apply natively, no per-frame projection
 // math). Expose only the ref — the rest of WorldContextValue stays internal.
@@ -397,6 +459,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[] };
@@ -418,6 +500,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' },
@@ -649,9 +735,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(() => {
@@ -662,8 +761,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;
@@ -716,6 +822,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;
@@ -793,7 +903,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;
       }
@@ -1001,11 +1117,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);
@@ -1034,10 +1163,19 @@ interface DesignCanvasProps {
  * via `useToolModeOptional` (hand-mode bare-drag pan).
  */
 export function DesignCanvas(props: DesignCanvasProps) {
+  // 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;
   return (
-    <ToolProvider>
-      <DesignCanvasInner {...props} />
-    </ToolProvider>
+    <UndoStackProvider canvasFile={canvasFile}>
+      <ToolProvider>
+        <DesignCanvasInner {...props} />
+      </ToolProvider>
+    </UndoStackProvider>
   );
 }
 DesignCanvas.displayName = 'DesignCanvas';
@@ -1188,20 +1326,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,
@@ -1297,7 +1471,7 @@ export function DCArtboard({
   children: ReactNode;
 }) {
   const ctx = useWorldContext();
-  const controller = useViewportControllerContext();
+  const _controller = useViewportControllerContext();
   const toolMode = useToolModeOptional();
   const selSet = useSelectionSetOptional();
   const dragBus = useDragStateContext();
@@ -1343,9 +1517,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;
@@ -1355,50 +1531,36 @@ export function DCArtboard({
   const isFollower = !!followerOffset;
   const isInDrag = isLeader || isFollower;
 
-  // Ghost position (world coords).
-  let ghostX = 0;
-  let ghostY = 0;
+  // Live drag position (world coords). The article's own `left/top` updates
+  // each frame while the drag is in flight — no ghost placeholder, no faded
+  // original. commitFromState then persists the final position on settle.
+  let liveX = rect.x;
+  let liveY = rect.y;
   if (busDrag?.kind === 'dragging') {
     if (isLeader) {
-      ghostX = busDrag.leaderRect.x;
-      ghostY = busDrag.leaderRect.y;
+      liveX = busDrag.leaderRect.x;
+      liveY = busDrag.leaderRect.y;
     } else if (isFollower && followerOffset) {
-      ghostX = busDrag.leaderRect.x + followerOffset.offsetX;
-      ghostY = busDrag.leaderRect.y + followerOffset.offsetY;
+      liveX = busDrag.leaderRect.x + followerOffset.offsetX;
+      liveY = busDrag.leaderRect.y + followerOffset.offsetY;
     }
   }
 
   const handleProps = dragHook.bindHandle();
 
   return (
-    <>
-      <article
-        className={`dc-artboard dc-positioned${isInDrag ? ' dc-dragging' : ''}`}
-        data-dc-screen={id}
-        aria-current={isActive ? 'true' : undefined}
-        style={{ left: rect.x, top: rect.y, width: rect.w, height: rect.h }}
-        {...handleProps}
-      >
-        <button
-          type="button"
-          className="dc-artboard-label sku"
-          onClick={onFocus}
-          aria-label={`Focus artboard ${label}`}
-        >
-          {label}
-        </button>
-        <div className="dc-artboard-body">{children}</div>
-      </article>
-      {isInDrag ? (
-        <div
-          className="dc-artboard-ghost"
-          aria-hidden="true"
-          style={{ left: ghostX, top: ghostY, width: rect.w, height: rect.h }}
-        >
-          <div className="dc-artboard-ghost-label">{label}</div>
-        </div>
-      ) : null}
-    </>
+    <article
+      className={`dc-artboard dc-positioned${isInDrag ? ' dc-dragging' : ''}`}
+      data-dc-screen={id}
+      aria-current={isActive ? 'true' : undefined}
+      style={{ left: liveX, top: liveY, width: rect.w, height: rect.h }}
+      {...handleProps}
+    >
+      <button type="button" className="dc-artboard-label sku" aria-label={`Artboard ${label}`}>
+        {label}
+      </button>
+      <div className="dc-artboard-body">{children}</div>
+    </article>
   );
 }
 DCArtboard.displayName = 'DCArtboard';
@@ -1410,6 +1572,15 @@ DCArtboard.displayName = 'DCArtboard';
 // come from `dragBus.current.snap.guides`; world→screen projection uses the
 // live viewport (`v.x + worldCoord * v.zoom` — same convention as `writeTransform`).
 
+// DDR-046 — render kind-aware snap guides + distance pills. `kind === 'sibling'`
+// gets the confident magenta + glow; `kind === 'grid'` gets a lighter gray (the
+// grid is fallback when no sibling fires). Pre-DDR-046 guides emit no `kind`
+// field — treat as sibling for back-compat. The `Δ{Math.round(delta)}` pill
+// renders mid-span when |delta| > 0 and screen-span exceeds 60 px (smaller
+// spans hide the pill so it never overlaps the line itself).
+const MIN_PILL_SPAN_PX = 60;
+const GUIDE_THICKNESS_PX = 2;
+
 export function SnapGuideOverlay() {
   const dragBus = useDragStateContext();
   const world = useWorldContext();
@@ -1421,49 +1592,78 @@ export function SnapGuideOverlay() {
   return (
     <>
       {s.snap.guides.map((g, i) => {
+        const kindClass = g.kind === 'grid' ? 'dc-snap-guide--grid' : 'dc-snap-guide--sibling';
+        const delta = g.delta ?? 0;
+        const showPill = g.kind !== 'grid' && Math.abs(delta) > 0;
         if (g.axis === 'x') {
           const sx = vp.x + g.pos * vp.zoom;
           const sFrom = vp.y + g.from * vp.zoom;
           const sTo = vp.y + g.to * vp.zoom;
+          const screenSpan = sTo - sFrom;
           return (
-            <div
+            <Fragment
               // biome-ignore lint/suspicious/noArrayIndexKey: guides are positional
               key={`x-${i}`}
-              className="dc-snap-guide"
-              style={{
-                position: 'fixed',
-                pointerEvents: 'none',
-                background: 'var(--accent, #d63b1f)',
-                left: sx,
-                top: sFrom,
-                width: 1,
-                height: Math.max(1, sTo - sFrom),
-                zIndex: 6,
-              }}
-              aria-hidden="true"
-            />
+            >
+              <div
+                className={`dc-snap-guide ${kindClass}`}
+                style={{
+                  left: sx - GUIDE_THICKNESS_PX / 2,
+                  top: sFrom,
+                  width: GUIDE_THICKNESS_PX,
+                  height: Math.max(GUIDE_THICKNESS_PX, screenSpan),
+                }}
+                aria-hidden="true"
+              />
+              {showPill && screenSpan >= MIN_PILL_SPAN_PX && (
+                <div
+                  className="dc-snap-pill"
+                  style={{
+                    left: sx,
+                    top: sFrom + screenSpan / 2,
+                    transform: 'translate(-50%, -50%)',
+                  }}
+                  aria-hidden="true"
+                >
+                  Δ{Math.round(Math.abs(delta))}
+                </div>
+              )}
+            </Fragment>
           );
         }
         const sy = vp.y + g.pos * vp.zoom;
         const sFrom = vp.x + g.from * vp.zoom;
         const sTo = vp.x + g.to * vp.zoom;
+        const screenSpan = sTo - sFrom;
         return (
-          <div
+          <Fragment
             // biome-ignore lint/suspicious/noArrayIndexKey: guides are positional
             key={`y-${i}`}
-            className="dc-snap-guide"
-            style={{
-              position: 'fixed',
-              pointerEvents: 'none',
-              background: 'var(--accent, #d63b1f)',
-              left: sFrom,
-              top: sy,
-              width: Math.max(1, sTo - sFrom),
-              height: 1,
-              zIndex: 6,
-            }}
-            aria-hidden="true"
-          />
+          >
+            <div
+              className={`dc-snap-guide ${kindClass}`}
+              style={{
+                left: sFrom,
+                top: sy - GUIDE_THICKNESS_PX / 2,
+                width: Math.max(GUIDE_THICKNESS_PX, screenSpan),
+                height: GUIDE_THICKNESS_PX,
+              }}
+              aria-hidden="true"
+            />
+            {showPill && screenSpan >= MIN_PILL_SPAN_PX && (
+              <div
+                className="dc-snap-pill"
+                style={{
+                  left: sFrom + screenSpan / 2,
+                  top: sy,
+                  transform: 'translate(-50%, -50%)',
+                }}
+                aria-hidden="true"
+              >
+                Δ{Math.round(Math.abs(delta))}
+              </div>
+            )}
+          </Fragment>
         );
       })}
     </>
@@ -1484,6 +1684,14 @@ export function DCPostIt({ children }: { children: ReactNode }) {
 // same vocabulary; if a DS wants to restyle, it can target `.dc-mm` /
 // `.dc-zoom-tb` directly.
 
+// DDR-046 — Floating chrome (mini-map, zoom HUD, tool palette, popovers, comment
+// composer, export dialog) drops the brutalist 4 × 4 × 0 hard offset shadow in
+// favor of a soft ambient. The hard offset stays on app-shell chrome only
+// (menubar, header, tab strip) — that's the project's intentional brutalist
+// identity. Floating layer = soft. App frame = hard.
+const FLOATING_SHADOW = '0 6px 24px color-mix(in oklab, var(--fg-0, #1c1917) 10%, transparent)';
+const FLOATING_RADIUS = '8px';
+
 const OVERLAY_CSS = `
 .dc-mm {
   position: absolute;
@@ -1491,15 +1699,15 @@ const OVERLAY_CSS = `
   bottom: 16px;
   width: 196px;
   height: 132px;
-  background: var(--bg-2, var(--bg-1, rgba(255,255,255,0.98)));
+  background: var(--bg-0, #ffffff);
   border: 1px solid var(--fg-0, #1c1917);
-  border-radius: 0;
+  border-radius: ${FLOATING_RADIUS};
   font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 10px;
   color: var(--fg-1, rgba(40,30,20,0.7));
   z-index: 6;
   user-select: none;
-  box-shadow: 4px 4px 0 var(--fg-0, #1c1917);
+  box-shadow: ${FLOATING_SHADOW};
   overflow: hidden;
 }
 .dc-mm-hd {
@@ -1508,6 +1716,7 @@ const OVERLAY_CSS = `
   letter-spacing: 0.05em;
   text-transform: uppercase;
   font-size: 9px;
+  background: var(--bg-1, #f4f1ea);
 }
 .dc-mm-body {
   position: relative;
@@ -1515,15 +1724,21 @@ const OVERLAY_CSS = `
   height: calc(100% - 22px);
   overflow: hidden;
   cursor: pointer;
+  background: var(--bg-1, #f4f1ea);
 }
 .dc-mm-rect {
   position: absolute;
-  background: rgba(0,0,0,0.06);
-  border: 1px solid rgba(0,0,0,0.18);
+  background: color-mix(in oklab, var(--fg-0, #1c1917) 14%, transparent);
+  border: 1px solid color-mix(in oklab, var(--fg-0, #1c1917) 28%, transparent);
+  border-radius: 1px;
 }
+/* Filled viewport indicator — FigJam / Figma both ship a tinted fill, not
+   outline-only. Reads from a glance as "what slice of the world you're on". */
 .dc-mm-vp {
   position: absolute;
-  border: 2px solid #d63b1f;
+  background: color-mix(in oklab, var(--accent, #d63b1f) 12%, transparent);
+  border: 1.5px solid var(--accent, #d63b1f);
+  border-radius: 1px;
   pointer-events: none;
 }
 .dc-zoom-tb {
@@ -1533,15 +1748,15 @@ const OVERLAY_CSS = `
   transform: translateX(-50%);
   display: flex;
   align-items: stretch;
-  background: var(--bg-2, rgba(255,255,255,0.94));
+  background: var(--bg-0, #ffffff);
   border: 1px solid var(--fg-0, #1c1917);
-  border-radius: 0;
+  border-radius: ${FLOATING_RADIUS};
   overflow: hidden;
   font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
   color: var(--fg-1, rgba(40,30,20,0.85));
   z-index: 6;
-  box-shadow: 4px 4px 0 var(--fg-0, #1c1917);
+  box-shadow: ${FLOATING_SHADOW};
 }
 .dc-zoom-tb button {
   appearance: none;
@@ -1554,10 +1769,11 @@ const OVERLAY_CSS = `
   cursor: pointer;
   min-width: 36px;
   text-align: center;
+  transition: background 80ms linear;
 }
 .dc-zoom-tb button:last-child { border-right: 0; }
-.dc-zoom-tb button:hover { background: rgba(0,0,0,0.04); }
-.dc-zoom-tb button:focus-visible { outline: 2px solid #d63b1f; outline-offset: -2px; }
+.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-pct { font-variant-numeric: tabular-nums; min-width: 52px; }
 `.trim();
 
@@ -1992,3 +2208,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,
+};