@1agh/maude 0.19.1 → 0.21.0

package/plugins/design/dev-server/test/use-collab.test.ts

@@ -0,0 +1,71 @@
+// Unit: pure helpers from use-collab.tsx (color hash + slug derivation).
+// The provider itself + the WS round-trip live in browser-shaped harnesses.
+
+import { describe, expect, test } from 'bun:test';
+
+import { canvasSlugFromPath, colorForName } from '../use-collab.tsx';
+
+describe('colorForName', () => {
+  test('returns a color from the curated palette', () => {
+    const color = colorForName('Alice');
+    expect(color).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+
+  test('deterministic per input', () => {
+    const a = colorForName('Alice');
+    const b = colorForName('Alice');
+    expect(a).toBe(b);
+  });
+
+  test('different names land on different colors (probabilistically)', () => {
+    // Sample many distinct names; expect at least 8 distinct colors among 30
+    // names. With 12-color palette + uniform-ish djb2, this is comfortable.
+    const names = Array.from({ length: 30 }, (_, i) => `peer-${i}`);
+    const colors = new Set(names.map(colorForName));
+    expect(colors.size).toBeGreaterThanOrEqual(8);
+  });
+
+  test('empty string returns a palette color (not crash)', () => {
+    expect(colorForName('')).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+
+  test('unicode names work', () => {
+    expect(colorForName('Michał Dovrtěl')).toMatch(/^#[0-9a-f]{6}$/i);
+    expect(colorForName('佐藤')).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+});
+
+describe('canvasSlugFromPath', () => {
+  test('normalizes a typical canvas path', () => {
+    expect(canvasSlugFromPath('ui/Foo.tsx')).toBe('ui-foo');
+    expect(canvasSlugFromPath('ui/Canvas Viewport.tsx')).toBe('ui-canvas_viewport');
+    expect(canvasSlugFromPath('system/project/preview/colors-accent.tsx')).toBe(
+      'system-project-preview-colors-accent'
+    );
+  });
+
+  test('strips .tsx + .html extensions case-insensitively', () => {
+    expect(canvasSlugFromPath('ui/Foo.TSX')).toBe('ui-foo');
+    expect(canvasSlugFromPath('ui/Foo.html')).toBe('ui-foo');
+  });
+
+  test('returns null for paths that would yield invalid slug chars', () => {
+    // Dots in name (not extension) survive normalization and fail the gate.
+    expect(canvasSlugFromPath('ui/Foo.Bar.tsx')).toBeNull();
+    // Empty input.
+    expect(canvasSlugFromPath('')).toBeNull();
+    expect(canvasSlugFromPath(null)).toBeNull();
+    expect(canvasSlugFromPath(undefined)).toBeNull();
+  });
+
+  test('round-trips against the slug grammar parseCollabSlug accepts', () => {
+    // parseCollabSlug regex = ^[a-z0-9_-]+$
+    const re = /^[a-z0-9_-]+$/;
+    const samples = ['ui/Foo.tsx', 'system/project/preview/x.tsx', 'a/b c.tsx'];
+    for (const s of samples) {
+      const slug = canvasSlugFromPath(s);
+      expect(slug).not.toBeNull();
+      if (slug !== null) expect(re.test(slug)).toBe(true);
+    }
+  });
+});

package/plugins/design/dev-server/test/use-cursor-modifiers.test.ts

@@ -0,0 +1,59 @@
+// use-cursor-modifiers — T28 (Wave 3). Pure reducer covers the cross-platform
+// Ctrl≡Meta normalization + same-state short-circuit.
+
+import { describe, expect, test } from 'bun:test';
+
+import { type ModifierState, reduceModifiers } from '../use-cursor-modifiers.tsx';
+
+const initial: ModifierState = { alt: false, shift: false, meta: false };
+
+const k = (over: Partial<KeyboardEventInit & { ctrlKey: boolean }> = {}) => ({
+  altKey: false,
+  shiftKey: false,
+  metaKey: false,
+  ctrlKey: false,
+  ...over,
+});
+
+describe('reduceModifiers', () => {
+  test('no change → returns same reference (cheap equality)', () => {
+    const out = reduceModifiers(initial, k());
+    expect(out).toBe(initial);
+  });
+
+  test('alt down → alt:true', () => {
+    const out = reduceModifiers(initial, k({ altKey: true }));
+    expect(out).toEqual({ alt: true, shift: false, meta: false });
+  });
+
+  test('shift down → shift:true', () => {
+    const out = reduceModifiers(initial, k({ shiftKey: true }));
+    expect(out).toEqual({ alt: false, shift: true, meta: false });
+  });
+
+  test('meta down → meta:true', () => {
+    const out = reduceModifiers(initial, k({ metaKey: true }));
+    expect(out).toEqual({ alt: false, shift: false, meta: true });
+  });
+
+  test('ctrl is normalized to meta (cross-platform parity)', () => {
+    const out = reduceModifiers(initial, k({ ctrlKey: true }));
+    expect(out.meta).toBe(true);
+  });
+
+  test('meta + ctrl together → meta:true (not duplicated)', () => {
+    const out = reduceModifiers(initial, k({ metaKey: true, ctrlKey: true }));
+    expect(out).toEqual({ alt: false, shift: false, meta: true });
+  });
+
+  test('alt+shift simultaneously → both true', () => {
+    const out = reduceModifiers(initial, k({ altKey: true, shiftKey: true }));
+    expect(out).toEqual({ alt: true, shift: true, meta: false });
+  });
+
+  test('releasing alt while shift still held → shift only', () => {
+    const both: ModifierState = { alt: true, shift: true, meta: false };
+    const out = reduceModifiers(both, k({ shiftKey: true })); // alt released
+    expect(out).toEqual({ alt: false, shift: true, meta: false });
+  });
+});

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/tool-palette.tsx

@@ -76,19 +76,19 @@ const PALETTE_CSS = `
   transition: background-color 80ms linear, color 80ms linear;
 }
 .dc-tool-palette button:hover {
-  background: color-mix(in oklab, var(--accent, #d63b1f) 8%, transparent);
+  background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 8%, transparent);
   color: var(--fg-0, #1a1a1a);
 }
 .dc-tool-palette button:focus-visible {
-  outline: 2px solid var(--accent, #d63b1f);
+  outline: 2px solid var(--maude-hud-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);
+  background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 14%, transparent);
+  color: var(--maude-hud-accent, #d63b1f);
 }
 .dc-tool-palette button[aria-pressed="true"]::after {
   content: "";
@@ -97,7 +97,7 @@ const PALETTE_CSS = `
   right: 6px;
   bottom: 2px;
   height: 2px;
-  background: var(--accent, #d63b1f);
+  background: var(--maude-hud-accent, #d63b1f);
   border-radius: 1px;
 }
 /* T19 — sticky-tool lock badge. Tiny accent square in the top-right corner
@@ -107,7 +107,7 @@ const PALETTE_CSS = `
 .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);
+  box-shadow: inset 0 0 0 1px var(--maude-hud-accent, #d63b1f);
 }
 .dc-tool-palette button .dc-tp-sticky-badge {
   position: absolute;
@@ -115,7 +115,7 @@ const PALETTE_CSS = `
   right: 3px;
   width: 6px;
   height: 6px;
-  background: var(--accent, #d63b1f);
+  background: var(--maude-hud-accent, #d63b1f);
   border-radius: 1px;
   box-shadow: 0 0 0 1px var(--bg-0, #ffffff);
   opacity: 0;

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';