@1agh/maude 0.19.1 → 0.20.0

package/plugins/design/dev-server/test/use-keyboard-discipline.test.ts

@@ -0,0 +1,27 @@
+// use-keyboard-discipline — T29 (Wave 3). Pure nudge-delta fixture.
+
+import { describe, expect, test } from 'bun:test';
+
+import { nudgeDelta } from '../use-keyboard-discipline.tsx';
+
+describe('nudgeDelta', () => {
+  test('non-arrow key → null', () => {
+    expect(nudgeDelta({ key: 'a', shift: false })).toBeNull();
+    expect(nudgeDelta({ key: 'Tab', shift: false })).toBeNull();
+    expect(nudgeDelta({ key: 'Enter', shift: true })).toBeNull();
+  });
+
+  test('arrow without shift → 1 px step', () => {
+    expect(nudgeDelta({ key: 'ArrowLeft', shift: false })).toEqual({ dx: -1, dy: 0 });
+    expect(nudgeDelta({ key: 'ArrowRight', shift: false })).toEqual({ dx: 1, dy: 0 });
+    expect(nudgeDelta({ key: 'ArrowUp', shift: false })).toEqual({ dx: 0, dy: -1 });
+    expect(nudgeDelta({ key: 'ArrowDown', shift: false })).toEqual({ dx: 0, dy: 1 });
+  });
+
+  test('arrow with shift → 10 px step', () => {
+    expect(nudgeDelta({ key: 'ArrowLeft', shift: true })).toEqual({ dx: -10, dy: 0 });
+    expect(nudgeDelta({ key: 'ArrowRight', shift: true })).toEqual({ dx: 10, dy: 0 });
+    expect(nudgeDelta({ key: 'ArrowUp', shift: true })).toEqual({ dx: 0, dy: -10 });
+    expect(nudgeDelta({ key: 'ArrowDown', shift: true })).toEqual({ dx: 0, dy: 10 });
+  });
+});

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/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();
+}

package/plugins/design/dev-server/use-artboard-drag.tsx

@@ -36,14 +36,17 @@ import {
   useState,
 } from 'react';
 
+import { DRAG_THRESHOLD_PX as INPUT_DRAG_THRESHOLD_PX } from './input-router.tsx';
 import type { Selection } from './use-selection-set.tsx';
 import { type Rect, type SnapResult, computeSnap } from './use-snap-guides.tsx';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
 
-/** Screen-pixel distance the cursor must travel before pending → dragging. */
-export const DRAG_THRESHOLD_PX = 4;
+/** Screen-pixel distance the cursor must travel before pending → dragging.
+ *  Re-export from `input-router` so artboard-drag, marquees, and annotation
+ *  drag-vs-tap share the same canonical value (T25). */
+export const DRAG_THRESHOLD_PX = INPUT_DRAG_THRESHOLD_PX;
 
 /** Default grid + tolerance (world units). Documented in DDR-028. */
 export const DEFAULT_GRID_SIZE = 40;
@@ -136,7 +139,7 @@ export function dragReducer(state: DragState, ev: DragEvent): DragState {
       const dxClient = ev.clientX - state.startClientX;
       const dyClient = ev.clientY - state.startClientY;
       if (state.kind === 'pending') {
-        if (Math.abs(dxClient) < DRAG_THRESHOLD_PX && Math.abs(dyClient) < DRAG_THRESHOLD_PX) {
+        if (Math.hypot(dxClient, dyClient) < DRAG_THRESHOLD_PX) {
           return state;
         }
       }