@1agh/maude 0.19.0 → 0.20.0

package/plugins/design/dev-server/test/canvas-lib-motion.test.ts

@@ -0,0 +1,131 @@
+// canvas-lib-motion — Phase 3.7 Task 14 / DDR-049.
+//
+// Pure-logic + AST tests for the canvas-lib motion helpers. The full DOM
+// path (MotionDemo render, useMotionTokens MutationObserver, ReducedMotionToggle
+// click) belongs to the agent-browser smoke step — bun:test runs in a
+// non-DOM environment, so we exercise (a) the role config table shape, (b)
+// easingFromToken's pure mapping, (c) the canvas-lib export surface (the
+// motion helpers must be exported by name so handoff inlining can resolve
+// them), (d) the canvas-lib-inline pass A walk picking up motion helpers
+// transitively.
+
+import { describe, expect, test } from 'bun:test';
+
+import { buildLibMap, inlineUsedExports } from '../canvas-lib-inline.ts';
+import { canvasLibPath } from '../canvas-lib-resolver.ts';
+
+const PROJECT_DESIGN_ROOT = `${process.cwd()}/.design`;
+
+describe('canvas-lib motion exports', () => {
+  test('motion helpers exported by name', async () => {
+    const libPath = canvasLibPath(PROJECT_DESIGN_ROOT);
+    const libSource = await Bun.file(libPath).text();
+    const map = buildLibMap(libPath, libSource);
+    for (const name of [
+      'MotionDemo',
+      'MotionTrack',
+      'TokenPlayback',
+      'ReducedMotionToggle',
+      'useMotionTokens',
+      'easingFromToken',
+    ]) {
+      expect(map.has(name), `expected '${name}' to be a top-level export`).toBe(true);
+    }
+  });
+
+  test('motion helpers are re-exported under canonical names', async () => {
+    // The lib aliases motion/react primitives to _motionImpl / _useReducedMotion /
+    // _MotionAnimatePresence but re-exports them as `motion`, `useReducedMotion`,
+    // `AnimatePresence`. Handoff inlining relies on the canonical names being in
+    // the libMap (so a canvas importing `useReducedMotion` from @maude/canvas-lib
+    // resolves correctly).
+    const libPath = canvasLibPath(PROJECT_DESIGN_ROOT);
+    const libSource = await Bun.file(libPath).text();
+    expect(libSource).toContain("from 'motion/react'");
+    expect(libSource).toMatch(/_motionImpl\s+as\s+motion/);
+    expect(libSource).toMatch(/_useReducedMotion\s+as\s+useReducedMotion/);
+    expect(libSource).toMatch(/_MotionAnimatePresence\s+as\s+AnimatePresence/);
+  });
+});
+
+describe('canvas-lib motion inline (handoff path)', () => {
+  test('inlining MotionDemo carries transitive deps', async () => {
+    const libPath = canvasLibPath(PROJECT_DESIGN_ROOT);
+    const libSource = await Bun.file(libPath).text();
+    const map = buildLibMap(libPath, libSource);
+
+    // Synthetic canvas that imports just MotionDemo from canvas-lib.
+    const canvas = [
+      'import { MotionDemo } from "@maude/canvas-lib";',
+      '',
+      'export default function Probe() {',
+      '  return <MotionDemo role="flip" />;',
+      '}',
+      '',
+    ].join('\n');
+
+    const inlined = inlineUsedExports(canvas, map);
+    expect(inlined.droppedImport).toBe(true);
+
+    const inlinedNames = new Set(inlined.inlined);
+    // MotionDemo's body references useMotionTokens + easingFromToken + the
+    // aliased _motionImpl + _useReducedMotion. Transitive walk should pull
+    // useMotionTokens + easingFromToken (the function symbols), and the
+    // module-level role table constant.
+    expect(inlinedNames.has('MotionDemo')).toBe(true);
+    // The role config table.
+    expect(inlinedNames.has('MOTION_ROLE_DEFAULTS')).toBe(true);
+    // Reads-tokens hook (referenced inside MotionDemo).
+    expect(inlinedNames.has('useMotionTokens')).toBe(true);
+    expect(inlinedNames.has('easingFromToken')).toBe(true);
+  });
+
+  test('inlined motion code references aliased motion/react imports', async () => {
+    const libPath = canvasLibPath(PROJECT_DESIGN_ROOT);
+    const libSource = await Bun.file(libPath).text();
+    const map = buildLibMap(libPath, libSource);
+
+    const canvas = [
+      'import { MotionDemo } from "@maude/canvas-lib";',
+      '',
+      'export default function Probe() {',
+      '  return <MotionDemo role="soft" />;',
+      '}',
+      '',
+    ].join('\n');
+
+    const inlined = inlineUsedExports(canvas, map);
+    // The inlined body must reference the aliased symbols (handoff.ts then
+    // splices a synthetic import re-binding them to motion/react). If this
+    // assertion fails, the handoff path will produce a TSX with undefined
+    // identifiers.
+    expect(inlined.content).toMatch(/_motionImpl\b/);
+    expect(inlined.content).toMatch(/_useReducedMotion\b/);
+  });
+
+  test('role keys are stable (8-role vocabulary fixed per DDR-049)', async () => {
+    const libPath = canvasLibPath(PROJECT_DESIGN_ROOT);
+    const libSource = await Bun.file(libPath).text();
+    // The 8-role vocabulary is part of the DS contract — design-system-keeper
+    // + motion-critic both grep against it. Lock the role list with a
+    // structural assertion against the source.
+    for (const role of ['flip', 'panel', 'route', 'soft', 'spring', 'scroll', 'drag', 'presence']) {
+      expect(libSource).toContain(`  ${role}: {`);
+    }
+  });
+});
+
+describe('motion peer-dep in package.json', () => {
+  test('motion declared in dependencies', async () => {
+    const pkg = await Bun.file('./package.json').json();
+    expect(pkg.dependencies.motion).toBeDefined();
+    expect(typeof pkg.dependencies.motion).toBe('string');
+  });
+
+  test('motion + motion/react in RUNTIME_PACKAGES', async () => {
+    const { RUNTIME_PACKAGES } = await import('../runtime-bundle.ts');
+    const list = [...RUNTIME_PACKAGES];
+    expect(list).toContain('motion');
+    expect(list).toContain('motion/react');
+  });
+});

package/plugins/design/dev-server/test/context-resolve-tokens.test.ts

@@ -0,0 +1,97 @@
+// Per-DS tokensCssRel auto-resolution — load-bearing for DDR-048. When a
+// config entry doesn't spell out `tokensCssRel`, the dev-server must derive
+// it from `<entry.path>/colors_and_type.css` so the System view can read the
+// scaffolded layout without forcing every config author to repeat the path.
+
+import { describe, expect, test } from 'bun:test';
+import { normalizeDesignSystems } from '../context';
+
+const baseCfg = {
+  name: 'fixture',
+  projectLabel: null,
+  designRoot: '.design',
+  canvasGroups: [],
+  rootClass: 'app',
+  themeDefault: 'dark' as const,
+  tokensCssRel: 'system/colors_and_type.css',
+  teamAccentDefault: null,
+  handoffTargets: [],
+  newCanvasDir: 'ui',
+  newComponentDir: 'ui/components',
+  _source: '.design/config.json' as const,
+};
+
+describe('normalizeDesignSystems', () => {
+  test('no designSystems → passthrough (top-level tokensCssRel is the only source)', () => {
+    const out = normalizeDesignSystems({ ...baseCfg, designSystems: undefined });
+    expect(out.designSystems).toBeUndefined();
+    expect(out.tokensCssRel).toBe('system/colors_and_type.css');
+  });
+
+  test('empty designSystems array → passthrough', () => {
+    const out = normalizeDesignSystems({ ...baseCfg, designSystems: [] });
+    expect(out.designSystems).toEqual([]);
+  });
+
+  test('entry without tokensCssRel → derived from <path>/colors_and_type.css', () => {
+    const out = normalizeDesignSystems({
+      ...baseCfg,
+      designSystems: [{ name: 'studyfi', path: 'system/studyfi' }],
+    });
+    expect(out.designSystems?.[0].tokensCssRel).toBe('system/studyfi/colors_and_type.css');
+  });
+
+  test('entry with explicit tokensCssRel → preserved (leading slash trimmed)', () => {
+    const out = normalizeDesignSystems({
+      ...baseCfg,
+      designSystems: [
+        { name: 'studyfi', path: 'system/studyfi', tokensCssRel: '/system/studyfi/tokens.css' },
+      ],
+    });
+    expect(out.designSystems?.[0].tokensCssRel).toBe('system/studyfi/tokens.css');
+  });
+
+  test('path with leading + trailing slashes → normalized', () => {
+    const out = normalizeDesignSystems({
+      ...baseCfg,
+      designSystems: [{ name: 'alpha', path: '/system/alpha/' }],
+    });
+    expect(out.designSystems?.[0].path).toBe('system/alpha');
+    expect(out.designSystems?.[0].tokensCssRel).toBe('system/alpha/colors_and_type.css');
+  });
+
+  test('multiple entries → each resolved independently', () => {
+    const out = normalizeDesignSystems({
+      ...baseCfg,
+      designSystems: [
+        { name: 'alpha', path: 'system/alpha' },
+        { name: 'beta', path: 'system/beta', tokensCssRel: 'system/beta/custom.css' },
+      ],
+    });
+    expect(out.designSystems?.[0].tokensCssRel).toBe('system/alpha/colors_and_type.css');
+    expect(out.designSystems?.[1].tokensCssRel).toBe('system/beta/custom.css');
+  });
+
+  test('preserves unrelated entry fields (description, rootClass, themes)', () => {
+    const out = normalizeDesignSystems({
+      ...baseCfg,
+      designSystems: [
+        {
+          name: 'studyfi',
+          path: 'system/studyfi',
+          description: 'StudyFi production mirror',
+          rootClass: 'studyfi',
+          themeDefault: 'light',
+          themes: ['light', 'dark'],
+          newCanvasDir: 'ui/studyfi',
+        },
+      ],
+    });
+    const entry = out.designSystems?.[0];
+    expect(entry?.description).toBe('StudyFi production mirror');
+    expect(entry?.rootClass).toBe('studyfi');
+    expect(entry?.themeDefault).toBe('light');
+    expect(entry?.themes).toEqual(['light', 'dark']);
+    expect(entry?.newCanvasDir).toBe('ui/studyfi');
+  });
+});

package/plugins/design/dev-server/test/equal-spacing-detector.test.ts

@@ -0,0 +1,93 @@
+// equal-spacing-detector — T27 (Wave 3). Pure detector fixtures.
+
+import { describe, expect, test } from 'bun:test';
+
+import { detectEqualSpacing } from '../equal-spacing-detector.ts';
+import type { Rect } from '../use-snap-guides.tsx';
+
+const r = (x: number, y: number, w = 100, h = 60): Rect => ({ x, y, w, h });
+
+describe('detectEqualSpacing / preconditions', () => {
+  test('fewer than 3 rects → null', () => {
+    expect(detectEqualSpacing([], 'x')).toBeNull();
+    expect(detectEqualSpacing([r(0, 0)], 'x')).toBeNull();
+    expect(detectEqualSpacing([r(0, 0), r(200, 0)], 'x')).toBeNull();
+  });
+
+  test('overlapping rects → null (gap < 0)', () => {
+    // r1 spans 0..100, r2 starts at 90 (overlap by 10)
+    expect(detectEqualSpacing([r(0, 0), r(90, 0), r(220, 0)], 'x')).toBeNull();
+  });
+});
+
+describe('detectEqualSpacing / horizontal axis', () => {
+  test('3 rects, equal gap 20 → detects with gap=20 + 2 midpoints', () => {
+    // 0..100, 120..220, 240..340 — gap = 20
+    const out = detectEqualSpacing([r(0, 0), r(120, 0), r(240, 0)], 'x');
+    expect(out).not.toBeNull();
+    expect(out?.axis).toBe('x');
+    expect(out?.gapPx).toBe(20);
+    expect(out?.midpoints).toHaveLength(2);
+    expect(out?.midpoints[0]).toEqual({ x: 110, y: 30 });
+    expect(out?.midpoints[1]).toEqual({ x: 230, y: 30 });
+  });
+
+  test('uneven gaps outside tolerance → null', () => {
+    // gaps: 20, 30
+    const out = detectEqualSpacing([r(0, 0), r(120, 0), r(250, 0)], 'x');
+    expect(out).toBeNull();
+  });
+
+  test('within 1 px tolerance is accepted', () => {
+    // gaps: 20, 21 — within default tolerance of 1
+    const out = detectEqualSpacing([r(0, 0), r(120, 0), r(241, 0)], 'x');
+    expect(out).not.toBeNull();
+    expect(out?.gapPx).toBeGreaterThanOrEqual(20);
+    expect(out?.gapPx).toBeLessThanOrEqual(21);
+  });
+
+  test('explicit tolerance allows wider band', () => {
+    // gaps: 20, 25
+    const tightFail = detectEqualSpacing([r(0, 0), r(120, 0), r(245, 0)], 'x');
+    expect(tightFail).toBeNull();
+    const loosePass = detectEqualSpacing([r(0, 0), r(120, 0), r(245, 0)], 'x', {
+      tolerancePx: 5,
+    });
+    expect(loosePass).not.toBeNull();
+  });
+
+  test('rects passed in random order → sorted internally', () => {
+    const out = detectEqualSpacing([r(240, 0), r(0, 0), r(120, 0)], 'x');
+    expect(out).not.toBeNull();
+    expect(out?.gapPx).toBe(20);
+  });
+});
+
+describe('detectEqualSpacing / vertical axis', () => {
+  test('3 rects stacked, equal gap 30 → detects', () => {
+    // y: 0..60, 90..150, 180..240 — gap 30
+    const out = detectEqualSpacing([r(0, 0), r(0, 90), r(0, 180)], 'y');
+    expect(out).not.toBeNull();
+    expect(out?.axis).toBe('y');
+    expect(out?.gapPx).toBe(30);
+    expect(out?.midpoints).toHaveLength(2);
+    expect(out?.midpoints[0]?.y).toBe(75); // 60 + 30/2
+    expect(out?.midpoints[1]?.y).toBe(165);
+  });
+});
+
+describe('detectEqualSpacing / 4+ rects', () => {
+  test('4 rects equally distributed → 3 midpoints', () => {
+    // gaps 20, 20, 20
+    const out = detectEqualSpacing([r(0, 0), r(120, 0), r(240, 0), r(360, 0)], 'x');
+    expect(out).not.toBeNull();
+    expect(out?.midpoints).toHaveLength(3);
+    expect(out?.gapPx).toBe(20);
+  });
+
+  test('one bad gap in a 4-rect set → null', () => {
+    // gaps 20, 50, 20
+    const out = detectEqualSpacing([r(0, 0), r(120, 0), r(270, 0), r(390, 0)], 'x');
+    expect(out).toBeNull();
+  });
+});

package/plugins/design/dev-server/test/input-router.test.ts

@@ -2,7 +2,14 @@
 
 import { describe, expect, test } from 'bun:test';
 
-import { type ClassifyInput, type Tool, classify, isEditableTarget } from '../input-router.tsx';
+import {
+  type ClassifyInput,
+  DRAG_THRESHOLD_PX,
+  type Tool,
+  classify,
+  crossedDragThreshold,
+  isEditableTarget,
+} from '../input-router.tsx';
 
 const base = (over: Partial<ClassifyInput>): ClassifyInput => ({
   type: 'pointermove',
@@ -314,3 +321,82 @@ describe('input-router / isEditableTarget', () => {
     expect(isEditableTarget(el)).toBe(true);
   });
 });
+
+// T25 — Drag-vs-click threshold. Centralized here so every drag-class gesture
+// (artboard drag, artboard marquee, element marquee, annotation pen/rect/etc.)
+// reads the same value. Microsoft Win32 SM_CXDRAG default + d3-drag convention.
+describe('input-router / crossedDragThreshold', () => {
+  test('constant is 4', () => {
+    expect(DRAG_THRESHOLD_PX).toBe(4);
+  });
+
+  test('no movement → false', () => {
+    expect(crossedDragThreshold(100, 200, 100, 200)).toBe(false);
+  });
+
+  test('3 px move (sub-threshold) → false', () => {
+    expect(crossedDragThreshold(0, 0, 3, 0)).toBe(false);
+    expect(crossedDragThreshold(0, 0, 2, 2)).toBe(false); // hypot ≈ 2.83
+  });
+
+  test('exactly 4 px → true (boundary inclusive)', () => {
+    expect(crossedDragThreshold(0, 0, 4, 0)).toBe(true);
+    expect(crossedDragThreshold(0, 0, 0, 4)).toBe(true);
+  });
+
+  test('5 px diagonal → true', () => {
+    // 3-4-5 right triangle: hypot = 5
+    expect(crossedDragThreshold(10, 20, 13, 24)).toBe(true);
+  });
+
+  test('negative deltas — hypot is direction-agnostic', () => {
+    expect(crossedDragThreshold(50, 50, 47, 46)).toBe(true); // hypot = 5
+    expect(crossedDragThreshold(50, 50, 48, 49)).toBe(false); // hypot ≈ 2.24
+  });
+});
+
+describe('input-router / keydown — undo + redo (Phase 20)', () => {
+  test('Cmd+Z → undo', () => {
+    expect(classify(base({ type: 'keydown', key: 'z', metaKey: true })).kind).toBe('undo');
+  });
+
+  test('Cmd+Shift+Z → redo', () => {
+    expect(classify(base({ type: 'keydown', key: 'z', metaKey: true, shiftKey: true })).kind).toBe(
+      'redo'
+    );
+  });
+
+  test('Ctrl+Z → undo (Windows / Linux mac-less)', () => {
+    expect(classify(base({ type: 'keydown', key: 'z', ctrlKey: true })).kind).toBe('undo');
+  });
+
+  test('Ctrl+Y → redo (Windows convention)', () => {
+    expect(classify(base({ type: 'keydown', key: 'y', ctrlKey: true })).kind).toBe('redo');
+  });
+
+  test('Cmd+Y → redo (mac users with Windows muscle-memory)', () => {
+    expect(classify(base({ type: 'keydown', key: 'y', metaKey: true })).kind).toBe('redo');
+  });
+
+  test('Cmd+Z inside editable → no-op (browser native text undo wins)', () => {
+    expect(
+      classify(base({ type: 'keydown', key: 'z', metaKey: true, isEditable: true })).kind
+    ).toBe('no-op');
+  });
+
+  test('Cmd+Opt+Z → no-op (Alt is reserved for browser text gestures)', () => {
+    expect(classify(base({ type: 'keydown', key: 'z', metaKey: true, altKey: true })).kind).toBe(
+      'no-op'
+    );
+  });
+
+  test('bare Z → no-op (Z is not a tool letter; needs Cmd)', () => {
+    expect(classify(base({ type: 'keydown', key: 'z' })).kind).toBe('no-op');
+  });
+
+  test('Cmd+Shift+Y → no-op (only Cmd+Y; we do not over-claim)', () => {
+    expect(classify(base({ type: 'keydown', key: 'y', metaKey: true, shiftKey: true })).kind).toBe(
+      'no-op'
+    );
+  });
+});

package/plugins/design/dev-server/test/marquee-overlay.test.ts

@@ -0,0 +1,94 @@
+// marquee-overlay — T26 (Wave 3). Aseprite-vocabulary modifier semantics
+// table tests + applyMarqueeMode set-algebra tests. Pure functions, no DOM.
+
+import { describe, expect, test } from 'bun:test';
+
+import { applyMarqueeMode, modeOf } from '../marquee-overlay.tsx';
+import type { Selection } from '../use-selection-set.tsx';
+
+describe('marquee-overlay / modeOf', () => {
+  test('no modifiers → replace', () => {
+    expect(modeOf({ shiftKey: false, altKey: false })).toBe('replace');
+  });
+  test('shift → add', () => {
+    expect(modeOf({ shiftKey: true, altKey: false })).toBe('add');
+  });
+  test('alt → subtract', () => {
+    expect(modeOf({ shiftKey: false, altKey: true })).toBe('subtract');
+  });
+  test('shift+alt → intersect', () => {
+    expect(modeOf({ shiftKey: true, altKey: true })).toBe('intersect');
+  });
+});
+
+describe('marquee-overlay / applyMarqueeMode', () => {
+  // Stub `selSet` that records the last call so the test can assert outcome.
+  type Recorded = { method: 'replace' | 'add'; payload: Selection[] };
+  const makeStub = () => {
+    const log: Recorded[] = [];
+    const stub = {
+      replace: (s: Selection | Selection[]) => {
+        log.push({ method: 'replace', payload: Array.isArray(s) ? s : [s] });
+      },
+      add: (s: Selection | Selection[]) => {
+        log.push({ method: 'add', payload: Array.isArray(s) ? s : [s] });
+      },
+    };
+    return { stub, log };
+  };
+
+  const sel = (id: string): Selection => ({ id, selector: `[data-cd-id="${id}"]` });
+
+  test('replace with empty hits → no-op (selection preserved)', () => {
+    const { stub, log } = makeStub();
+    applyMarqueeMode(stub, 'replace', [sel('a')], []);
+    expect(log).toHaveLength(0);
+  });
+
+  test('replace with hits → swaps to hits', () => {
+    const { stub, log } = makeStub();
+    applyMarqueeMode(stub, 'replace', [sel('a')], [sel('b'), sel('c')]);
+    expect(log).toEqual([{ method: 'replace', payload: [sel('b'), sel('c')] }]);
+  });
+
+  test('add with empty hits → no-op', () => {
+    const { stub, log } = makeStub();
+    applyMarqueeMode(stub, 'add', [sel('a')], []);
+    expect(log).toHaveLength(0);
+  });
+
+  test('add with hits → adds to existing', () => {
+    const { stub, log } = makeStub();
+    applyMarqueeMode(stub, 'add', [sel('a')], [sel('b')]);
+    expect(log).toEqual([{ method: 'add', payload: [sel('b')] }]);
+  });
+
+  test('subtract removes the hit ids from startSet', () => {
+    const { stub, log } = makeStub();
+    applyMarqueeMode(stub, 'subtract', [sel('a'), sel('b'), sel('c')], [sel('b')]);
+    expect(log).toEqual([{ method: 'replace', payload: [sel('a'), sel('c')] }]);
+  });
+
+  test('subtract with no overlap → identity (replace with startSet)', () => {
+    const { stub, log } = makeStub();
+    applyMarqueeMode(stub, 'subtract', [sel('a'), sel('b')], [sel('z')]);
+    expect(log).toEqual([{ method: 'replace', payload: [sel('a'), sel('b')] }]);
+  });
+
+  test('intersect keeps only ids present in both sets', () => {
+    const { stub, log } = makeStub();
+    applyMarqueeMode(
+      stub,
+      'intersect',
+      [sel('a'), sel('b'), sel('c')],
+      [sel('b'), sel('c'), sel('d')]
+    );
+    expect(log).toEqual([{ method: 'replace', payload: [sel('b'), sel('c')] }]);
+  });
+
+  test('intersect with empty hits → clears (empty replace)', () => {
+    const { stub, log } = makeStub();
+    applyMarqueeMode(stub, 'intersect', [sel('a'), sel('b')], []);
+    expect(log).toEqual([{ method: 'replace', payload: [] }]);
+  });
+});

package/plugins/design/dev-server/test/move-artboards-command.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, mock, test } from 'bun:test';
+
+import {
+  type ArtboardLayoutEntry,
+  createMoveArtboardsCommand,
+  diffLayoutPositions,
+} from '../commands/move-artboards-command.ts';
+
+const A: ArtboardLayoutEntry = { id: 'a', x: 0, y: 0, w: 100, h: 80 };
+const B: ArtboardLayoutEntry = { id: 'b', x: 200, y: 0, w: 100, h: 80 };
+const A2: ArtboardLayoutEntry = { id: 'a', x: 50, y: 25, w: 100, h: 80 };
+const B2: ArtboardLayoutEntry = { id: 'b', x: 260, y: 0, w: 100, h: 80 };
+
+describe('createMoveArtboardsCommand', () => {
+  test('do() patches with the AFTER snapshot', async () => {
+    const patchFn = mock(() => {});
+    const cmd = createMoveArtboardsCommand({ before: [A, B], after: [A2, B], patchFn });
+    await cmd.do();
+    expect(patchFn).toHaveBeenCalledTimes(1);
+    const arg = patchFn.mock.calls[0]?.[0];
+    expect(arg).toEqual([A2, B]);
+  });
+
+  test('undo() patches with the BEFORE snapshot', async () => {
+    const patchFn = mock(() => {});
+    const cmd = createMoveArtboardsCommand({ before: [A, B], after: [A2, B], patchFn });
+    await cmd.undo();
+    expect(patchFn).toHaveBeenCalledTimes(1);
+    const arg = patchFn.mock.calls[0]?.[0];
+    expect(arg).toEqual([A, B]);
+  });
+
+  test('redo idempotence — do() twice yields the same patch payload', async () => {
+    const patchFn = mock(() => {});
+    const cmd = createMoveArtboardsCommand({ before: [A, B], after: [A2, B2], patchFn });
+    await cmd.do();
+    await cmd.do();
+    expect(patchFn).toHaveBeenCalledTimes(2);
+    expect(patchFn.mock.calls[0]?.[0]).toEqual([A2, B2]);
+    expect(patchFn.mock.calls[1]?.[0]).toEqual([A2, B2]);
+  });
+
+  test('snapshots are deep-cloned — mutating the source after construction has no effect', async () => {
+    const before: ArtboardLayoutEntry[] = [{ ...A }, { ...B }];
+    const after: ArtboardLayoutEntry[] = [{ ...A2 }, { ...B }];
+    const patchFn = mock(() => {});
+    const cmd = createMoveArtboardsCommand({ before, after, patchFn });
+    // Poison the source arrays in place.
+    // biome-ignore lint/style/noNonNullAssertion: test invariant — arrays literally constructed two lines above
+    after[0]!.x = 9999;
+    // biome-ignore lint/style/noNonNullAssertion: test invariant — arrays literally constructed two lines above
+    before[1]!.y = -777;
+    await cmd.do();
+    expect(patchFn.mock.calls[0]?.[0]).toEqual([A2, B]);
+    await cmd.undo();
+    expect(patchFn.mock.calls[1]?.[0]).toEqual([A, B]);
+  });
+
+  test('label defaults to "move N artboards" with correct count', () => {
+    const cmd = createMoveArtboardsCommand({
+      before: [A, B],
+      after: [A2, B],
+      patchFn: () => {},
+    });
+    expect(cmd.label).toBe('move 1 artboard');
+
+    const cmd2 = createMoveArtboardsCommand({
+      before: [A, B],
+      after: [A2, B2],
+      patchFn: () => {},
+    });
+    expect(cmd2.label).toBe('move 2 artboards');
+  });
+
+  test('label override (equal-spacing wraps with its own copy)', () => {
+    const cmd = createMoveArtboardsCommand({
+      before: [A, B],
+      after: [A2, B2],
+      patchFn: () => {},
+      label: 'equal-space 2 artboards',
+    });
+    expect(cmd.label).toBe('equal-space 2 artboards');
+  });
+});
+
+describe('diffLayoutPositions', () => {
+  test('identical → null (skip push)', () => {
+    expect(diffLayoutPositions([A, B], [A, B])).toBeNull();
+    expect(diffLayoutPositions([A, B], [{ ...A }, { ...B }])).toBeNull();
+  });
+
+  test('1 moved → { changed: 1 }', () => {
+    expect(diffLayoutPositions([A, B], [A2, B])).toEqual({ changed: 1 });
+  });
+
+  test('both moved → { changed: 2 }', () => {
+    expect(diffLayoutPositions([A, B], [A2, B2])).toEqual({ changed: 2 });
+  });
+
+  test('different array lengths → reports max (defensive — real flows align ids)', () => {
+    expect(diffLayoutPositions([A], [A, B])).toEqual({ changed: 2 });
+  });
+
+  test('size-only diff (no position change) → null', () => {
+    const Aresized: ArtboardLayoutEntry = { id: 'a', x: 0, y: 0, w: 200, h: 160 };
+    expect(diffLayoutPositions([A], [Aresized])).toBeNull();
+  });
+});