@1agh/maude 0.19.0 → 0.20.0

package/plugins/design/dev-server/test/use-undo-stack.test.tsx

@@ -0,0 +1,193 @@
+// use-undo-stack — Provider runner contract. SSR-capture pattern + ref-as-
+// store means most of the interesting state lives outside React renders,
+// so we exercise the action closures directly. Pure reducer is covered in
+// undo-stack.test.ts.
+
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import {
+  type CommandRecord,
+  type CommandSinks,
+  _clearBuilderRegistry,
+  _clearStackStore,
+  registerCommand,
+} from '../undo-stack.ts';
+import {
+  UndoStackProvider,
+  useUndoSinks,
+  useUndoStack,
+  useUndoStackOptional,
+} from '../use-undo-stack.tsx';
+
+// Shared spy plumbing for record-builder tests below.
+let doSpy: ReturnType<typeof mock>;
+let undoSpy: ReturnType<typeof mock>;
+
+beforeEach(() => {
+  _clearStackStore();
+  _clearBuilderRegistry();
+  doSpy = mock(() => {});
+  undoSpy = mock(() => {});
+  // A single "test" command kind shared across this file. The builder reads
+  // `sinks.layoutPatchFn` as a generic "trigger" — when present, do() and
+  // undo() fire the spies; when absent, rebuild returns null.
+  registerCommand('test', (record, sinks) => {
+    if (!sinks.layoutPatchFn) return null;
+    return {
+      kind: record.kind,
+      label: record.label,
+      do() {
+        doSpy(record.payload);
+      },
+      undo() {
+        undoSpy(record.payload);
+      },
+    };
+  });
+});
+
+afterEach(() => {
+  _clearStackStore();
+});
+
+function rec(label: string, payload: unknown = null): CommandRecord {
+  return { kind: 'test', label, payload };
+}
+
+function capture<T>(useHook: () => T, tree: (consumer: React.ReactElement) => React.ReactElement) {
+  let captured: T | null = null;
+  function Consumer() {
+    captured = useHook();
+    return null;
+  }
+  renderToStaticMarkup(tree(<Consumer />));
+  if (!captured) throw new Error('hook did not capture a value');
+  return captured;
+}
+
+/**
+ * Render a provider tree and capture both the stack value and the sinks API.
+ * Sinks are bound during the same SSR render via a sibling capture, so the
+ * runner's first push() sees the registered sink.
+ */
+function captureProvider(canvasFile?: string, sinks?: Partial<CommandSinks>) {
+  let stack: ReturnType<typeof useUndoStack> | null = null;
+  function Inner() {
+    stack = useUndoStack();
+    const undoSinks = useUndoSinks();
+    if (sinks) {
+      for (const [k, v] of Object.entries(sinks)) {
+        // biome-ignore lint/suspicious/noExplicitAny: setSink generic indexing
+        undoSinks.setSink(k as never, v as any);
+      }
+    }
+    return null;
+  }
+  renderToStaticMarkup(
+    <UndoStackProvider canvasFile={canvasFile}>
+      <Inner />
+    </UndoStackProvider>
+  );
+  if (!stack) throw new Error('no provider value captured');
+  return stack;
+}
+
+describe('use-undo-stack / contract outside provider', () => {
+  test('useUndoStack() throws outside provider', () => {
+    function Bare() {
+      useUndoStack();
+      return null;
+    }
+    expect(() => renderToStaticMarkup(<Bare />)).toThrow(
+      /useUndoStack must be used inside <UndoStackProvider>/
+    );
+  });
+
+  test('useUndoStackOptional() returns no-op value outside provider', () => {
+    const value = capture(useUndoStackOptional, (child) => <>{child}</>);
+    expect(value.canUndo).toBe(false);
+    expect(value.canRedo).toBe(false);
+    expect(value.lastLabel).toBeNull();
+    expect(() => value.clear()).not.toThrow();
+  });
+
+  test('useUndoSinks() outside provider is a silent no-op', () => {
+    const value = capture(useUndoSinks, (child) => <>{child}</>);
+    expect(() => value.setSink('layoutPatchFn', () => {})).not.toThrow();
+  });
+});
+
+describe('use-undo-stack / runner side-effects', () => {
+  test('push() invokes rebuilt cmd.do() exactly once', async () => {
+    const v = captureProvider(undefined, { layoutPatchFn: () => {} });
+    await v.push(rec('move 1'));
+    expect(doSpy).toHaveBeenCalledTimes(1);
+    expect(undoSpy).toHaveBeenCalledTimes(0);
+  });
+
+  test('undo() invokes cmd.undo() on the most recently pushed record', async () => {
+    const v = captureProvider(undefined, { layoutPatchFn: () => {} });
+    await v.push(rec('a', 'A'));
+    await v.push(rec('b', 'B'));
+    await v.undo();
+    expect(undoSpy).toHaveBeenCalledTimes(1);
+    expect(undoSpy.mock.calls[0]?.[0]).toBe('B');
+  });
+
+  test('redo() re-invokes cmd.do() on the most recently undone record', async () => {
+    const v = captureProvider(undefined, { layoutPatchFn: () => {} });
+    await v.push(rec('a', 'A'));
+    await v.undo();
+    await v.redo();
+    expect(doSpy).toHaveBeenCalledTimes(2);
+    expect(doSpy.mock.calls[1]?.[0]).toBe('A');
+  });
+
+  test('push without a registered sink skips the do() call (rebuild returned null)', async () => {
+    const v = captureProvider(undefined, {}); // no sinks → builder returns null
+    await v.push(rec('lonely'));
+    // doSpy is the only observable signal here — `lastLabel` is React
+    // state that doesn't refresh under SSR-capture.
+    expect(doSpy).toHaveBeenCalledTimes(0);
+    expect(undoSpy).toHaveBeenCalledTimes(0);
+  });
+});
+
+describe('use-undo-stack / cross-canvas persistence', () => {
+  test('history under a canvasFile survives a fresh provider mount with the same canvasFile', async () => {
+    // First mount: push 2 records.
+    {
+      const v = captureProvider('ui/Foo.tsx', { layoutPatchFn: () => {} });
+      await v.push(rec('e1'));
+      await v.push(rec('e2'));
+    }
+    // Second mount (simulates iframe destroy + remount for same canvas).
+    const v2 = captureProvider('ui/Foo.tsx', { layoutPatchFn: () => {} });
+    expect(v2.canUndo).toBe(true);
+    expect(v2.lastLabel).toBeNull(); // labels are per-mount session
+    // Undo the top — should fire spy with rec('e2') payload.
+    await v2.undo();
+    expect(undoSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test('switching canvases keeps each history independent', async () => {
+    {
+      const v = captureProvider('ui/Foo.tsx', { layoutPatchFn: () => {} });
+      await v.push(rec('foo-1'));
+      await v.push(rec('foo-2'));
+    }
+    {
+      const v = captureProvider('ui/Bar.tsx', { layoutPatchFn: () => {} });
+      await v.push(rec('bar-1'));
+    }
+    // Come back to Foo.
+    const v2 = captureProvider('ui/Foo.tsx', { layoutPatchFn: () => {} });
+    expect(v2.canUndo).toBe(true);
+    await v2.undo();
+    // The spy was called for foo-2 last (LIFO).
+    const lastCall = undoSpy.mock.calls[undoSpy.mock.calls.length - 1]?.[0];
+    expect(lastCall).toBeNull(); // payload is null in `rec(label)` default
+  });
+});

package/plugins/design/dev-server/tool-palette.tsx

@@ -24,6 +24,9 @@ import { useToolMode } from './use-tool-mode.tsx';
 // 32 × 32 buttons with iconography. Grouped pill segments separated by 1 px
 // dividers — visual cue that nav / draw / view-controls are distinct kinds.
 
+// DDR-046 — floating chrome ambient shadow + 8 px radius (NOT brutalist).
+// Active-tool state: 14% tint bg + 2px accent underbar + accent fg, replacing
+// the previous full-accent flood (too loud at 32 × 32 in a quiet chrome).
 const PALETTE_CSS = `
 .dc-tool-palette {
   position: absolute;
@@ -32,10 +35,10 @@ const PALETTE_CSS = `
   transform: translateX(-50%);
   display: flex;
   align-items: stretch;
-  background: var(--u-bg-2, var(--bg-1, rgba(255,255,255,0.98)));
+  background: var(--u-bg-0, var(--bg-0, #ffffff));
   border: 1px solid var(--u-fg-0, #1c1917);
-  border-radius: 0;
-  box-shadow: 4px 4px 0 var(--u-fg-0, #1c1917);
+  border-radius: 8px;
+  box-shadow: 0 6px 24px color-mix(in oklab, var(--u-fg-0, #1c1917) 10%, transparent);
   font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 12px;
   color: var(--u-fg-0, var(--fg-0, #1a1a1a));
@@ -43,8 +46,7 @@ const PALETTE_CSS = `
   user-select: none;
   /* Intentionally NO overflow:hidden — the zoom popover (.dc-tp-popover) is
      a position:absolute child anchored above the toolbar; clipping the
-     parent would hide it. Inner buttons have their own border-radius so the
-     rounded outer corners are preserved by content shape, not overflow. */
+     parent would hide it. */
 }
 .dc-tool-palette .dc-tp-group {
   display: flex;
@@ -61,7 +63,7 @@ const PALETTE_CSS = `
   appearance: none;
   background: transparent;
   border: 0;
-  border-radius: 0;
+  border-radius: 6px;
   padding: 0;
   width: 32px;
   height: 32px;
@@ -70,16 +72,61 @@ const PALETTE_CSS = `
   justify-content: center;
   color: var(--fg-1, rgba(40,30,20,0.75));
   cursor: pointer;
+  position: relative;
   transition: background-color 80ms linear, color 80ms linear;
 }
-.dc-tool-palette button:hover { background: rgba(0,0,0,0.04); color: var(--fg-0, #1a1a1a); }
+.dc-tool-palette button:hover {
+  background: color-mix(in oklab, var(--accent, #d63b1f) 8%, transparent);
+  color: var(--fg-0, #1a1a1a);
+}
 .dc-tool-palette button:focus-visible {
   outline: 2px solid var(--accent, #d63b1f);
   outline-offset: -2px;
 }
+/* DDR-046 — Active tool: tinted background + accent underbar + accent text.
+   The underbar is rendered via ::after so the visual stays inside the 6 px
+   radius without leaking past the button edge. */
 .dc-tool-palette button[aria-pressed="true"] {
+  background: color-mix(in oklab, var(--accent, #d63b1f) 14%, transparent);
+  color: var(--accent, #d63b1f);
+}
+.dc-tool-palette button[aria-pressed="true"]::after {
+  content: "";
+  position: absolute;
+  left: 6px;
+  right: 6px;
+  bottom: 2px;
+  height: 2px;
   background: var(--accent, #d63b1f);
-  color: var(--accent-fg, #fff);
+  border-radius: 1px;
+}
+/* T19 — sticky-tool lock badge. Tiny accent square in the top-right corner
+   of the active tool button, fades in 50 ms after a double-click. The badge
+   reads "armed across draws" so the user understands the tool will stay
+   selected after each shape commit. */
+.dc-tool-palette button[data-sticky="true"] {
+  /* Keep the tinted active background; add a hairline ring so the lock state
+     is readable even when the button is also aria-pressed. */
+  box-shadow: inset 0 0 0 1px var(--accent, #d63b1f);
+}
+.dc-tool-palette button .dc-tp-sticky-badge {
+  position: absolute;
+  top: 3px;
+  right: 3px;
+  width: 6px;
+  height: 6px;
+  background: var(--accent, #d63b1f);
+  border-radius: 1px;
+  box-shadow: 0 0 0 1px var(--bg-0, #ffffff);
+  opacity: 0;
+  transition: opacity 50ms linear 50ms;
+  pointer-events: none;
+}
+.dc-tool-palette button[data-sticky="true"] .dc-tp-sticky-badge {
+  opacity: 1;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-tool-palette button .dc-tp-sticky-badge { transition: none; }
 }
 .dc-tool-palette .dc-tp-zoom {
   min-width: 56px;
@@ -88,7 +135,7 @@ const PALETTE_CSS = `
   font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
   letter-spacing: 0.04em;
-  border-radius: 0;
+  border-radius: 6px;
   display: inline-flex;
   align-items: center;
   gap: 4px;
@@ -98,10 +145,10 @@ const PALETTE_CSS = `
   position: absolute;
   right: 4px;
   bottom: 44px;
-  background: var(--u-bg-2, var(--bg-1, rgba(255,255,255,0.98)));
+  background: var(--u-bg-0, var(--bg-0, #ffffff));
   border: 1px solid var(--u-fg-0, #1c1917);
-  border-radius: 0;
-  box-shadow: 4px 4px 0 var(--u-fg-0, #1c1917);
+  border-radius: 8px;
+  box-shadow: 0 6px 24px color-mix(in oklab, var(--u-fg-0, #1c1917) 10%, transparent);
   display: flex;
   flex-direction: column;
   padding: 4px;
@@ -149,7 +196,7 @@ const DRAW_TOOLS = ['pen', 'rect', 'ellipse', 'arrow', 'eraser'] as const;
 
 export function ToolPalette() {
   ensurePaletteStyles();
-  const { tool, setTool, tools } = useToolMode();
+  const { tool, setTool, tools, sticky, toggleSticky } = useToolMode();
   const controller = useViewportControllerContext();
   const visibilityCtx = useAnnotationsVisibility();
   const [mounted, setMounted] = useState(false);
@@ -176,16 +223,25 @@ export function ToolPalette() {
 
   const renderToolButton = (id: string, label: string, shortcut: string) => {
     const Icon = TOOL_ICONS[id];
+    const isDraw = (DRAW_TOOLS as readonly string[]).includes(id);
+    const isSticky = sticky.locked && sticky.tool === (id as never);
+    const stickyHint = isDraw ? ' · double-click to lock' : '';
     return (
       <button
         key={id}
         type="button"
-        aria-label={`${label} (${shortcut})`}
+        aria-label={`${label} (${shortcut})${isSticky ? ' — locked' : stickyHint}`}
         aria-pressed={tool === id}
-        title={`${label} (${shortcut})`}
+        data-sticky={isSticky ? 'true' : undefined}
+        title={`${label} (${shortcut})${stickyHint}`}
         onClick={() => setTool(id as never)}
+        onDoubleClick={() => {
+          if (!isDraw) return;
+          toggleSticky(id as never);
+        }}
       >
         {Icon ? <Icon /> : <span style={{ fontSize: 11 }}>{shortcut}</span>}
+        {isSticky ? <span className="dc-tp-sticky-badge" aria-hidden="true" /> : null}
       </button>
     );
   };

package/plugins/design/dev-server/undo-hud.tsx

@@ -0,0 +1,95 @@
+/**
+ * @file       undo-hud.tsx — top-right toast announcing the last undo edit
+ * @scope      plugins/design/dev-server/undo-hud.tsx
+ * @purpose    Subscribes to `useUndoStack().lastLabel` + `.lastTick` and
+ *             surfaces a 1.2 s aria-live toast so the user (and a screen
+ *             reader) knows which edit just got pushed / undone / redone.
+ *
+ * a11y. The toast renders into `aria-live="polite"` so a screen reader
+ * announces "Undo: move 3 artboards" without interrupting in-flight speech.
+ * Pointer events are disabled — the HUD is informational only and must
+ * never absorb clicks meant for the canvas behind it.
+ */
+
+import { useEffect, useState } from 'react';
+
+import { useUndoStackOptional } from './use-undo-stack.tsx';
+
+const HUD_CSS = `
+.dc-undo-hud {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+  z-index: 7;
+  pointer-events: none;
+  padding: 6px 10px;
+  background: var(--bg-2, rgba(20, 20, 20, 0.85));
+  color: var(--fg-1, rgba(255, 255, 255, 0.85));
+  border: 1px solid var(--border-subtle, rgba(255, 255, 255, 0.08));
+  border-radius: 6px;
+  font: 11px var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  letter-spacing: 0.02em;
+  user-select: none;
+  opacity: 0;
+  transform: translateY(-4px);
+  transition: opacity var(--dur-base, 200ms) linear, transform var(--dur-base, 200ms) ease-out;
+}
+.dc-undo-hud[data-visible="true"] {
+  opacity: 1;
+  transform: translateY(0);
+  transition-duration: var(--dur-fast, 120ms);
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-undo-hud {
+    transition-duration: 1ms !important;
+  }
+}
+`.trim();
+
+function ensureStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-undo-hud-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-undo-hud-css';
+  s.textContent = HUD_CSS;
+  document.head.appendChild(s);
+}
+
+/** Auto-dismiss timeout — matches the post-Wave-3 toast cadence. */
+const DISMISS_MS = 1200;
+
+export function UndoHud() {
+  ensureStyles();
+  const undo = useUndoStackOptional();
+  const [visible, setVisible] = useState(false);
+
+  // Bump visibility every time `lastTick` increments — same tick value means
+  // the underlying state did NOT change (provider's no-op fallback returns
+  // `lastTick: 0` constantly, so the HUD stays hidden when no provider).
+  const tick = undo.lastTick;
+  const label = undo.lastLabel;
+
+  useEffect(() => {
+    if (tick === 0 || !label) {
+      setVisible(false);
+      return;
+    }
+    setVisible(true);
+    const id = window.setTimeout(() => setVisible(false), DISMISS_MS);
+    return () => window.clearTimeout(id);
+  }, [tick, label]);
+
+  return (
+    <div
+      className="dc-undo-hud"
+      // biome-ignore lint/a11y/useSemanticElements: <output> is form-scoped; this HUD is a global status overlay outside any form
+      data-visible={visible ? 'true' : 'false'}
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      {label ?? ''}
+    </div>
+  );
+}
+UndoHud.displayName = 'UndoHud';

package/plugins/design/dev-server/undo-stack.ts

@@ -0,0 +1,240 @@
+/**
+ * @file       undo-stack.ts — per-canvas in-memory command stack
+ * @scope      plugins/design/dev-server/undo-stack.ts
+ * @purpose    Pure state + reducer for canvas Cmd+Z / Cmd+Shift+Z. No React,
+ *             no DOM, no fetch — `EditCommand.do()` / `.undo()` are caller-
+ *             supplied side-effects so this file stays trivially testable
+ *             under `bun:test`.
+ *
+ * Scope (DDR-050 rev 2):
+ *   - **Persistent per-canvas, in-memory, session-scoped.** The stack lives
+ *     in `window.top.__maude_undo_stacks` keyed by canvas file path so it
+ *     survives canvas switches (close Foo.tsx, open Bar.tsx, come back to
+ *     Foo.tsx → history still there). Reload destroys it. The original
+ *     "per-iframe-ephemeral" rule from rev 1 was UX-wrong.
+ *   - Stack stores SERIALIZABLE `CommandRecord`s (kind + label + payload),
+ *     NOT EditCommand closures. Closures captured by patchFn/putFn point
+ *     to the iframe's React state — when that iframe unmounts (canvas
+ *     switch), the closures become invalid. Rebuilding from the record
+ *     using the fresh iframe's sinks side-steps the lifecycle issue.
+ *   - Command-pattern semantics intact: each kind ships its own builder
+ *     that turns a payload + sinks into a runnable EditCommand.
+ *   - Depth cap = 50 per canvas. Future-discarded on push. Viewport +
+ *     selection NOT undoable (Figma convention).
+ *
+ * Async note. `cmd.do()` and `cmd.undo()` may return a Promise (server
+ * PATCH/PUT). The reducer itself is synchronous and never awaits — the
+ * runner inside `use-undo-stack.tsx` awaits the side-effect BEFORE
+ * dispatching the state transition. Reducer-pure keeps reasoning + tests
+ * trivial.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Runtime command shape
+
+/**
+ * A single reversible edit, ready to execute. Built on demand from a
+ * `CommandRecord` + `CommandSinks` via the registry below. Holds closures
+ * bound to the CURRENT iframe's React state — never persist this; persist
+ * the `CommandRecord` instead.
+ */
+export interface EditCommand {
+  readonly kind: string;
+  readonly label: string;
+  do(): Promise<void> | void;
+  undo(): Promise<void> | void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Persistent record shape — what the stack actually stores
+
+/**
+ * Serializable description of a reversible edit. Each `kind` corresponds
+ * to a registered builder (see `registerCommand` below). Payload shape is
+ * the kind's contract — see `commands/*-command.ts` for definitions.
+ */
+export interface CommandRecord<P = unknown> {
+  readonly kind: string;
+  readonly label: string;
+  readonly payload: P;
+}
+
+/**
+ * Per-iframe side-effect surface. Populated by descendants of the
+ * `UndoStackProvider` via `useUndoSinks().setSinks(...)`. Each consumer
+ * provides only the sink it owns; the provider merges. Unbound sinks are
+ * `undefined` — builders fail gracefully (returning `null` makes the
+ * runner skip the entry with a warning rather than crash).
+ */
+export interface CommandSinks {
+  /** Wired by canvas-lib `DesignCanvasInner`. */
+  layoutPatchFn?: unknown;
+  /** Wired by `AnnotationsLayer`. */
+  strokesPutFn?: unknown;
+}
+
+export type CommandBuilder<P = unknown> = (
+  record: CommandRecord<P>,
+  sinks: CommandSinks
+) => EditCommand | null;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Reducer state + actions
+
+export interface UndoStackState {
+  past: readonly CommandRecord[];
+  future: readonly CommandRecord[];
+}
+
+export type UndoAction =
+  | { type: 'push'; record: CommandRecord }
+  | { type: 'undo' }
+  | { type: 'redo' }
+  | { type: 'clear' }
+  | { type: 'hydrate'; state: UndoStackState };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+
+/**
+ * Ring cap per canvas. When `past.length === MAX_DEPTH` and a new record
+ * arrives, the oldest entry is dropped. 50 ≈ 3–5 minutes of intense
+ * iteration before the user can no longer undo to the start.
+ */
+export const MAX_DEPTH = 50;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Builder registry
+
+const BUILDERS = new Map<string, CommandBuilder>();
+
+/** Register a builder for a command kind. Idempotent. */
+export function registerCommand<P>(kind: string, builder: CommandBuilder<P>): void {
+  BUILDERS.set(kind, builder as CommandBuilder);
+}
+
+/**
+ * Rebuild a runnable `EditCommand` from a persisted record + the iframe's
+ * current sinks. Returns `null` when the kind isn't registered or the
+ * required sink isn't bound — the runner treats `null` as "skip this entry,
+ * something's misconfigured" rather than crashing.
+ */
+export function rebuildCommand(record: CommandRecord, sinks: CommandSinks): EditCommand | null {
+  const builder = BUILDERS.get(record.kind);
+  if (!builder) return null;
+  return builder(record, sinks);
+}
+
+/** Test seam — reset the registry between bun:test cases. */
+export function _clearBuilderRegistry(): void {
+  BUILDERS.clear();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory + reducer
+
+export function createUndoStackState(): UndoStackState {
+  return { past: [], future: [] };
+}
+
+export function undoReducer(state: UndoStackState, action: UndoAction): UndoStackState {
+  switch (action.type) {
+    case 'push': {
+      const next = state.past.length >= MAX_DEPTH ? state.past.slice(1) : state.past;
+      return { past: [...next, action.record], future: [] };
+    }
+    case 'undo': {
+      if (state.past.length === 0) return state;
+      const top = state.past[state.past.length - 1];
+      if (!top) return state;
+      return {
+        past: state.past.slice(0, -1),
+        future: [...state.future, top],
+      };
+    }
+    case 'redo': {
+      if (state.future.length === 0) return state;
+      const top = state.future[state.future.length - 1];
+      if (!top) return state;
+      return {
+        past: [...state.past, top],
+        future: state.future.slice(0, -1),
+      };
+    }
+    case 'clear':
+      return createUndoStackState();
+    case 'hydrate':
+      return action.state;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Selectors — keep state-shape inspection out of consumers.
+
+export function canUndo(state: UndoStackState): boolean {
+  return state.past.length > 0;
+}
+
+export function canRedo(state: UndoStackState): boolean {
+  return state.future.length > 0;
+}
+
+/** Top of `past` — the record an `undo` will invert. */
+export function peekUndo(state: UndoStackState): CommandRecord | null {
+  return state.past[state.past.length - 1] ?? null;
+}
+
+/** Top of `future` — the record a `redo` will re-apply. */
+export function peekRedo(state: UndoStackState): CommandRecord | null {
+  return state.future[state.future.length - 1] ?? null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cross-iframe persistent store (DDR-050 rev 2)
+//
+// Lives on the topmost window of the dev-server (same-origin — all canvas
+// iframes are children of /index.html). The map is keyed by canvas file path,
+// so switching from Foo.tsx → Bar.tsx → Foo.tsx replays the original Foo
+// history into the freshly-mounted iframe.
+
+interface StoreHost {
+  __maude_undo_stacks?: Map<string, UndoStackState>;
+}
+
+/**
+ * Prefer `window.top` so all canvas iframes (children of the dev-server
+ * shell) read + write the same Map. Falls back to `window` (when top is
+ * cross-origin — shouldn't happen in our same-origin setup), then to
+ * `globalThis` (Node / Bun test runtime where window is absent).
+ */
+function getStoreHost(): StoreHost {
+  if (typeof window !== 'undefined') {
+    try {
+      return (window.top ?? window) as unknown as StoreHost;
+    } catch {
+      return window as unknown as StoreHost;
+    }
+  }
+  return globalThis as unknown as StoreHost;
+}
+
+function ensureStoreMap(): Map<string, UndoStackState> {
+  const host = getStoreHost();
+  if (!host.__maude_undo_stacks) host.__maude_undo_stacks = new Map();
+  return host.__maude_undo_stacks;
+}
+
+/** Load saved state for a canvas file. Returns empty state on miss. */
+export function loadStackState(canvasFile: string): UndoStackState {
+  return ensureStoreMap().get(canvasFile) ?? createUndoStackState();
+}
+
+/** Persist state for a canvas file. */
+export function saveStackState(canvasFile: string, state: UndoStackState): void {
+  ensureStoreMap().set(canvasFile, state);
+}
+
+/** Test seam — wipe the cross-iframe store between bun:test cases. */
+export function _clearStackStore(): void {
+  getStoreHost().__maude_undo_stacks = new Map();
+}