@1agh/maude 0.15.0

package/plugins/design/dev-server/test/use-artboard-drag.test.ts

@@ -0,0 +1,325 @@
+// use-artboard-drag — Phase 4.2 Task 2. Pure reducer + helpers.
+//
+// The hook itself attaches DOM listeners; we verify the state-machine reducer
+// (`dragReducer`) and the follower/others computations are correct without
+// spinning up a DOM. The integration smoke (T3 ghost render, T5 commit
+// round-trip) is covered by the scenario in `.ai/scenarios/canvas-artboard-drag.md`.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  DEFAULT_GRID_SIZE,
+  DEFAULT_SNAP_TOLERANCE,
+  DRAG_THRESHOLD_PX,
+  type DragEvent,
+  type DragState,
+  commitFromState,
+  computeFollowers,
+  computeOthers,
+  dragReducer,
+  selectionsToArtboardIds,
+} from '../use-artboard-drag.tsx';
+import type { Selection } from '../use-selection-set.tsx';
+import type { Rect } from '../use-snap-guides.tsx';
+
+const rect = (id: string, x: number, y: number, w = 100, h = 80): Rect => ({
+  id,
+  x,
+  y,
+  w,
+  h,
+});
+
+const move = (over: Partial<Extract<DragEvent, { type: 'move' }>>): DragEvent => ({
+  type: 'move',
+  clientX: 0,
+  clientY: 0,
+  alt: false,
+  zoom: 1,
+  gridSize: DEFAULT_GRID_SIZE,
+  tolerance: DEFAULT_SNAP_TOLERANCE,
+  ...over,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// computeFollowers + computeOthers
+
+describe('computeFollowers', () => {
+  test('returns [] when leader is not in selection', () => {
+    const all = [rect('a', 0, 0), rect('b', 200, 0), rect('c', 400, 0)];
+    const followers = computeFollowers('a', all[0] as Rect, new Set(['b', 'c']), all);
+    expect(followers).toEqual([]);
+  });
+
+  test('returns siblings selected alongside leader, with relative offsets', () => {
+    const all = [rect('a', 100, 50), rect('b', 300, 200), rect('c', 600, 400)];
+    const followers = computeFollowers('a', all[0] as Rect, new Set(['a', 'b', 'c']), all);
+    expect(followers).toHaveLength(2);
+    expect(followers[0]).toMatchObject({ id: 'b', offsetX: 200, offsetY: 150 });
+    expect(followers[1]).toMatchObject({ id: 'c', offsetX: 500, offsetY: 350 });
+  });
+
+  test('excludes the leader from its own followers', () => {
+    const all = [rect('a', 0, 0), rect('b', 200, 0)];
+    const followers = computeFollowers('a', all[0] as Rect, new Set(['a', 'b']), all);
+    expect(followers.map((f) => f.id)).toEqual(['b']);
+  });
+});
+
+describe('computeOthers', () => {
+  test('excludes leader + followers from the snap candidate set', () => {
+    const all = [rect('a', 0, 0), rect('b', 200, 0), rect('c', 400, 0), rect('d', 600, 0)];
+    const others = computeOthers('a', new Set(['b']), all);
+    expect(others.map((r) => r.id)).toEqual(['c', 'd']);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// dragReducer — state machine
+
+function downAt(clientX: number, clientY: number, leaderStart: Rect): DragEvent {
+  return {
+    type: 'down',
+    clientX,
+    clientY,
+    leaderId: leaderStart.id ?? '',
+    leaderStart,
+    followers: [],
+    others: [],
+  };
+}
+
+describe('dragReducer / idle → pending', () => {
+  test('down event transitions to pending', () => {
+    const leader = rect('a', 0, 0);
+    const next = dragReducer({ kind: 'idle' }, downAt(50, 60, leader));
+    expect(next.kind).toBe('pending');
+    if (next.kind !== 'pending') throw new Error();
+    expect(next.startClientX).toBe(50);
+    expect(next.startClientY).toBe(60);
+    expect(next.leaderId).toBe('a');
+  });
+});
+
+describe('dragReducer / pending → idle when below threshold', () => {
+  test('move below 4 px stays in pending', () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const next = dragReducer(pending, move({ clientX: 102, clientY: 101 }));
+    expect(next.kind).toBe('pending');
+  });
+
+  test(`move past ${DRAG_THRESHOLD_PX} px transitions to dragging`, () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const next = dragReducer(pending, move({ clientX: 100 + DRAG_THRESHOLD_PX, clientY: 100 }));
+    expect(next.kind).toBe('dragging');
+  });
+});
+
+describe('dragReducer / dragging math', () => {
+  test('world delta scales by zoom (zoom 1.0)', () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const dragging = dragReducer(pending, move({ clientX: 200, clientY: 100, zoom: 1 }));
+    if (dragging.kind !== 'dragging') throw new Error();
+    expect(dragging.leaderRect.x).toBe(100);
+    expect(dragging.leaderRect.y).toBe(0);
+  });
+
+  test('world delta scales by zoom (zoom 0.5 — every screen px = 2 world px)', () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const dragging = dragReducer(pending, move({ clientX: 200, clientY: 100, zoom: 0.5 }));
+    if (dragging.kind !== 'dragging') throw new Error();
+    expect(dragging.leaderRect.x).toBe(200);
+  });
+
+  test('world delta scales by zoom (zoom 2.0 — every screen px = 0.5 world px)', () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const dragging = dragReducer(pending, move({ clientX: 200, clientY: 100, zoom: 2 }));
+    if (dragging.kind !== 'dragging') throw new Error();
+    expect(dragging.leaderRect.x).toBe(50);
+  });
+
+  test('snap applies during drag (proposed near grid line)', () => {
+    // Move leader from (0,0) by (+37 client px) at zoom 1 → proposed.x = 37.
+    // Grid line at 40 within tolerance 8 → snaps to 40.
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const dragging = dragReducer(pending, move({ clientX: 137, clientY: 100 }));
+    if (dragging.kind !== 'dragging') throw new Error();
+    expect(dragging.leaderRect.x).toBe(40);
+    expect(dragging.snap.guides.find((g) => g.axis === 'x')?.pos).toBe(40);
+  });
+
+  test('alt=true disables snap mid-drag', () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const dragging = dragReducer(pending, move({ clientX: 137, clientY: 100, alt: true }));
+    if (dragging.kind !== 'dragging') throw new Error();
+    expect(dragging.leaderRect.x).toBe(37);
+    expect(dragging.snap.guides).toEqual([]);
+  });
+});
+
+describe('dragReducer / cancel + up', () => {
+  test('cancel returns to idle from pending', () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const next = dragReducer(pending, { type: 'cancel' });
+    expect(next.kind).toBe('idle');
+  });
+
+  test('cancel returns to idle from dragging (no commit emitted by reducer)', () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const dragging = dragReducer(pending, move({ clientX: 200, clientY: 100 }));
+    const next = dragReducer(dragging, { type: 'cancel' });
+    expect(next.kind).toBe('idle');
+  });
+
+  test('up returns to idle', () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const dragging = dragReducer(pending, move({ clientX: 200, clientY: 100 }));
+    const next = dragReducer(dragging, { type: 'up' });
+    expect(next.kind).toBe('idle');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// commitFromState
+
+describe('commitFromState', () => {
+  test('returns null for idle/pending', () => {
+    expect(commitFromState({ kind: 'idle' })).toBeNull();
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    expect(commitFromState(pending)).toBeNull();
+  });
+
+  test("returns leader's snapped position when no followers", () => {
+    const leader = rect('a', 0, 0);
+    const pending = dragReducer({ kind: 'idle' }, downAt(100, 100, leader));
+    const dragging = dragReducer(pending, move({ clientX: 200, clientY: 100 }));
+    const commit = commitFromState(dragging);
+    expect(commit).toEqual([{ id: 'a', x: 100, y: 0 }]);
+  });
+
+  test('multi-drag preserves relative offsets', () => {
+    // Leader 'a' starts at (0, 0). Follower 'b' starts at (200, 150) — offset
+    // (200, 150) from leader. Drag leader by (50, 25) world — alt=true to
+    // disable snap so we can predict the result exactly.
+    const leader = rect('a', 0, 0);
+    const follower = rect('b', 200, 150);
+    const all = [leader, follower];
+    const followers = computeFollowers('a', leader, new Set(['a', 'b']), all);
+    const others = computeOthers('a', new Set(['b']), all);
+
+    const down: DragEvent = {
+      type: 'down',
+      clientX: 100,
+      clientY: 100,
+      leaderId: 'a',
+      leaderStart: leader,
+      followers,
+      others,
+    };
+    const pending = dragReducer({ kind: 'idle' }, down);
+    const dragging = dragReducer(pending, move({ clientX: 150, clientY: 125, alt: true }));
+    const commit = commitFromState(dragging);
+    expect(commit).toEqual([
+      { id: 'a', x: 50, y: 25 },
+      { id: 'b', x: 250, y: 175 },
+    ]);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Integration — snap also applies in dragging with siblings present
+
+describe('dragReducer / snap with siblings', () => {
+  test("leader snaps to sibling's left edge during drag", () => {
+    const leader = rect('a', 0, 0, 100, 80);
+    const sibling = rect('b', 200, 0, 100, 80);
+    const others = computeOthers('a', new Set(), [leader, sibling]);
+
+    const down: DragEvent = {
+      type: 'down',
+      clientX: 100,
+      clientY: 100,
+      leaderId: 'a',
+      leaderStart: leader,
+      followers: [],
+      others,
+    };
+    const pending = dragReducer({ kind: 'idle' }, down);
+    // Drag leader by (+197 client px) at zoom 1 → proposed.x = 197.
+    // Sibling.left = 200, delta = 3 → snap to 200.
+    const dragging = dragReducer(pending, move({ clientX: 297, clientY: 100 }));
+    if (dragging.kind !== 'dragging') throw new Error();
+    expect(dragging.leaderRect.x).toBe(200);
+    expect(dragging.snap.guides.find((g) => g.axis === 'x')?.pos).toBe(200);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Move event from idle is a no-op (defensive)
+
+describe('dragReducer / move from idle is a no-op', () => {
+  test('move dispatched without a prior down stays idle', () => {
+    const next = dragReducer({ kind: 'idle' }, move({ clientX: 100 }));
+    expect(next.kind).toBe('idle');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// selectionsToArtboardIds — Phase 4.2 multi-drag identity gate (C1 regression).
+//
+// Selection.id is a child element's data-cd-id; Selection.artboardId is the
+// host artboard. Multi-drag identity MUST key on artboardId only — falling
+// back to id would pollute the set with child cd-ids and silently disable
+// multi-drag.
+
+describe('selectionsToArtboardIds', () => {
+  const sel = (over: Partial<Selection>): Selection => ({
+    selector: '[data-cd-id="x"]',
+    ...over,
+  });
+
+  test('ignores Selection.id (child cd-id) and keys on artboardId only', () => {
+    const list: Selection[] = [
+      sel({ id: 'button_cd_xyz', artboardId: 'A' }),
+      sel({ id: 'span_cd_abc', artboardId: 'B' }),
+    ];
+    const ids = selectionsToArtboardIds(list);
+    expect([...ids].sort()).toEqual(['A', 'B']);
+    expect(ids.has('button_cd_xyz')).toBe(false);
+  });
+
+  test('skips selections that have no artboardId (orphan / world-level)', () => {
+    const list: Selection[] = [
+      sel({ id: 'orphan_cd', artboardId: null }),
+      sel({ artboardId: 'A' }),
+    ];
+    const ids = selectionsToArtboardIds(list);
+    expect([...ids]).toEqual(['A']);
+  });
+
+  test('dedupes when two selections share the same artboardId', () => {
+    const list: Selection[] = [
+      sel({ id: 'a1', artboardId: 'A' }),
+      sel({ id: 'a2', artboardId: 'A' }),
+    ];
+    const ids = selectionsToArtboardIds(list);
+    expect(ids.size).toBe(1);
+    expect(ids.has('A')).toBe(true);
+  });
+
+  test('empty list → empty set', () => {
+    const ids = selectionsToArtboardIds([]);
+    expect(ids.size).toBe(0);
+  });
+});

package/plugins/design/dev-server/test/use-selection-set.test.tsx

@@ -0,0 +1,166 @@
+// use-selection-set — Phase 4.1 Task 3. Set semantics + wire-shape helpers.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  type Selection,
+  denormalizeSelectedWrite,
+  normalizeSelectedRead,
+} from '../use-selection-set.tsx';
+
+const mkSel = (over: Partial<Selection> = {}): Selection => ({
+  selector: 'section:nth-child(1) > div',
+  ...over,
+});
+
+describe('use-selection-set / normalizeSelectedRead', () => {
+  test('null → []', () => {
+    expect(normalizeSelectedRead(null)).toEqual([]);
+    expect(normalizeSelectedRead(undefined)).toEqual([]);
+  });
+
+  test('single object → length-1 array', () => {
+    const s = mkSel({ id: 'cd-a' });
+    expect(normalizeSelectedRead(s)).toEqual([s]);
+  });
+
+  test('array passes through', () => {
+    const a = mkSel({ id: 'cd-a' });
+    const b = mkSel({ id: 'cd-b' });
+    expect(normalizeSelectedRead([a, b])).toEqual([a, b]);
+  });
+
+  test('array dedupe by data-cd-id', () => {
+    const a = mkSel({ id: 'cd-a' });
+    const aDup = mkSel({ id: 'cd-a', text: 'should be dropped' });
+    expect(normalizeSelectedRead([a, aDup])).toEqual([a]);
+  });
+
+  test('array dedupe by selector when no id', () => {
+    const a = mkSel({ selector: '.card:nth-child(1)' });
+    const b = mkSel({ selector: '.card:nth-child(1)' });
+    expect(normalizeSelectedRead([a, b])).toEqual([a]);
+  });
+
+  test("mixed id / selector keys don't collide", () => {
+    const byId = mkSel({ id: 'cd-a', selector: '.x' });
+    const bySel = mkSel({ selector: 'cd-a' }); // no id, selector happens to be 'cd-a'
+    expect(normalizeSelectedRead([byId, bySel])).toEqual([byId, bySel]);
+  });
+});
+
+describe('use-selection-set / denormalizeSelectedWrite', () => {
+  test('empty → null', () => {
+    expect(denormalizeSelectedWrite([])).toBeNull();
+  });
+
+  test('length-1 → bare object (back-compat with legacy single-element shape)', () => {
+    const s = mkSel({ id: 'cd-a' });
+    expect(denormalizeSelectedWrite([s])).toBe(s);
+  });
+
+  test('length>1 → array', () => {
+    const a = mkSel({ id: 'cd-a' });
+    const b = mkSel({ id: 'cd-b' });
+    expect(denormalizeSelectedWrite([a, b])).toEqual([a, b]);
+  });
+});
+
+describe('use-selection-set / round trip read-write', () => {
+  test('legacy single-element shape → array of 1 → back to single-element', () => {
+    const legacy = mkSel({ id: 'cd-a' });
+    const arr = normalizeSelectedRead(legacy);
+    expect(arr).toEqual([legacy]);
+    expect(denormalizeSelectedWrite(arr)).toBe(legacy);
+  });
+
+  test('null round-trips as null', () => {
+    expect(denormalizeSelectedWrite(normalizeSelectedRead(null))).toBeNull();
+  });
+});
+
+describe('use-selection-set / inspect.ts setSelected widening (integration)', () => {
+  test('inspect.setSelected accepts array and collapses single-entry to object', async () => {
+    // Spin up createInspect with a real on-disk active file in a tmp dir.
+    const { createInspect } = await import('../inspect.ts');
+    const { createBus } = await import('../context.ts');
+    const tmp = `/tmp/use-selection-set-${Date.now()}`;
+    await Bun.write(`${tmp}/.design/.keep`, '');
+    const ctx: Parameters<typeof createInspect>[0] = {
+      cfg: {} as never,
+      projectLabel: '',
+      paths: {
+        designRoot: `${tmp}/.design`,
+        designRel: '.design',
+        activeFile: `${tmp}/.design/_active.json`,
+        serverFile: `${tmp}/.design/_server.json`,
+        historyRoot: `${tmp}/.design/_history`,
+        commentsRoot: `${tmp}/.design/_comments`,
+        cwd: tmp,
+      } as never,
+      bus: createBus(),
+    };
+    const insp = createInspect(ctx, async () => []);
+
+    insp.setSelected({
+      file: '.design/ui/Foo.tsx',
+      selector: '.x',
+      tag: 'div',
+      classes: '',
+      text: '',
+      dom_path: [],
+      bounds: null,
+      html: '',
+      id: 'cd-a',
+    });
+    expect(Array.isArray(insp.state.selected)).toBe(false);
+    expect((insp.state.selected as { id?: string } | null)?.id).toBe('cd-a');
+
+    insp.setSelected([
+      {
+        file: '.design/ui/Foo.tsx',
+        selector: '.a',
+        tag: 'div',
+        classes: '',
+        text: '',
+        dom_path: [],
+        bounds: null,
+        html: '',
+        id: 'cd-a',
+      },
+      {
+        file: '.design/ui/Foo.tsx',
+        selector: '.b',
+        tag: 'div',
+        classes: '',
+        text: '',
+        dom_path: [],
+        bounds: null,
+        html: '',
+        id: 'cd-b',
+      },
+    ]);
+    expect(Array.isArray(insp.state.selected)).toBe(true);
+    expect((insp.state.selected as unknown[]).length).toBe(2);
+
+    // Single-entry array → object collapse
+    insp.setSelected([
+      {
+        file: '.design/ui/Foo.tsx',
+        selector: '.only',
+        tag: 'div',
+        classes: '',
+        text: '',
+        dom_path: [],
+        bounds: null,
+        html: '',
+        id: 'cd-only',
+      },
+    ]);
+    expect(Array.isArray(insp.state.selected)).toBe(false);
+    expect((insp.state.selected as { id?: string } | null)?.id).toBe('cd-only');
+
+    insp.setSelected(null);
+    expect(insp.state.selected).toBeNull();
+  });
+});

package/plugins/design/dev-server/test/use-snap-guides.test.ts

@@ -0,0 +1,190 @@
+// use-snap-guides — Phase 4.2 Task 1. Pure snap-math table tests.
+
+import { describe, expect, test } from 'bun:test';
+
+import { type Rect, type SnapOptions, computeSnap } from '../use-snap-guides.tsx';
+
+const DEFAULTS: SnapOptions = { gridSize: 40, tolerance: 8, disabled: false };
+
+const rect = (x: number, y: number, w = 100, h = 80): Rect => ({ x, y, w, h });
+
+describe('computeSnap / disabled (Alt-held)', () => {
+  test('returns proposed unchanged + zero guides', () => {
+    const r = computeSnap(rect(37, 78), [rect(100, 100)], { ...DEFAULTS, disabled: true });
+    expect(r.x).toBe(37);
+    expect(r.y).toBe(78);
+    expect(r.guides).toEqual([]);
+  });
+});
+
+describe('computeSnap / grid', () => {
+  test('snaps left edge to nearest grid line within tolerance', () => {
+    const r = computeSnap(rect(37, 200), [], DEFAULTS);
+    expect(r.x).toBe(40);
+    expect(r.guides.find((g) => g.axis === 'x')).toMatchObject({ pos: 40 });
+  });
+
+  test('does NOT snap when outside tolerance', () => {
+    const r = computeSnap(rect(27, 200), [], DEFAULTS);
+    expect(r.x).toBe(27);
+    expect(r.guides.find((g) => g.axis === 'x')).toBeUndefined();
+  });
+
+  test('snaps top edge independently of left edge', () => {
+    const r = computeSnap(rect(200, 37), [], DEFAULTS);
+    expect(r.y).toBe(40);
+    expect(r.guides.find((g) => g.axis === 'y')).toMatchObject({ pos: 40 });
+    expect(r.x).toBe(200);
+  });
+
+  test('exact grid boundary (delta = 0) snaps to itself + emits guide', () => {
+    const r = computeSnap(rect(40, 80), [], DEFAULTS);
+    expect(r.x).toBe(40);
+    expect(r.y).toBe(80);
+    expect(r.guides.find((g) => g.axis === 'x')).toMatchObject({ pos: 40 });
+    expect(r.guides.find((g) => g.axis === 'y')).toMatchObject({ pos: 80 });
+  });
+
+  test("guide line spans proposed's perpendicular extent (no sibling)", () => {
+    const r = computeSnap(rect(37, 200, 100, 80), [], DEFAULTS);
+    const xg = r.guides.find((g) => g.axis === 'x');
+    expect(xg).toMatchObject({ from: 200, to: 280 });
+  });
+});
+
+describe('computeSnap / sibling edges (X-axis)', () => {
+  test('left↔left snap', () => {
+    const proposed = rect(503, 200);
+    const sibling = rect(500, 50);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.x).toBe(500);
+    expect(r.guides.find((g) => g.axis === 'x')).toMatchObject({ pos: 500 });
+  });
+
+  test('right↔right snap (proposed.right snaps to sibling.right)', () => {
+    // proposed right = 503 + 100 = 603; sibling right = 500 + 100 = 600.
+    // delta = 600 - 603 = -3 → snap x by -3.
+    const proposed = rect(503, 300, 100, 80);
+    const sibling = rect(500, 100, 100, 80);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.x).toBe(500);
+  });
+
+  test('left↔right (proposed.left snaps to sibling.right — abutment)', () => {
+    // proposed.left = 597; sibling.right = 600. delta = +3.
+    const proposed = rect(597, 300, 100, 80);
+    const sibling = rect(500, 100, 100, 80);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.x).toBe(600);
+  });
+
+  test('centerX↔centerX snap', () => {
+    // proposed center = 553 + 50 = 603; sibling center = 550 + 50 = 600.
+    const proposed = rect(553, 300, 100, 80);
+    const sibling = rect(550, 100, 100, 80);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.x).toBe(550);
+  });
+
+  test('does NOT snap when delta exceeds tolerance', () => {
+    // proposed.x = 530 sits between grid lines 520 (Δ-10) and 560 (Δ+30) — both
+    // outside tolerance=8. Sibling at 500 is also -30 away. Nothing snaps.
+    const proposed = rect(530, 305);
+    const sibling = rect(500, 105);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.x).toBe(530);
+    expect(r.guides.find((g) => g.axis === 'x')).toBeUndefined();
+  });
+
+  test("guide line spans union of both rects' Y range", () => {
+    const proposed = rect(503, 50, 100, 80); // y range [50, 130]
+    const sibling = rect(500, 300, 100, 80); // y range [300, 380]
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    const xg = r.guides.find((g) => g.axis === 'x');
+    expect(xg).toMatchObject({ from: 50, to: 380 });
+  });
+});
+
+describe('computeSnap / sibling edges (Y-axis)', () => {
+  test('top↔top snap', () => {
+    const proposed = rect(300, 103, 100, 80);
+    const sibling = rect(50, 100, 100, 80);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.y).toBe(100);
+  });
+
+  test('bottom↔top snap (proposed below sibling, abutting)', () => {
+    // proposed.bottom = 177; sibling.top = 180. delta = +3 → shift y by +3.
+    const proposed = rect(300, 97, 100, 80);
+    const sibling = rect(50, 180, 100, 80);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.y).toBe(100);
+    expect(proposed.y + 100 - 97).toBe(100);
+    const yg = r.guides.find((g) => g.axis === 'y');
+    expect(yg).toMatchObject({ pos: 180 });
+  });
+
+  test('centerY↔centerY snap', () => {
+    const proposed = rect(300, 103, 100, 80); // centerY = 143
+    const sibling = rect(50, 100, 100, 80); // centerY = 140
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.y).toBe(100);
+  });
+});
+
+describe('computeSnap / closest wins', () => {
+  test('when sibling and grid both within tolerance, closer wins', () => {
+    // proposed.x = 37; grid candidate at 40 (delta 3); sibling.left at 38 (delta 1).
+    const proposed = rect(37, 300);
+    const sibling = rect(38, 100);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.x).toBe(38);
+  });
+
+  test('when grid is closer, grid wins', () => {
+    // proposed.x = 39; grid candidate at 40 (delta 1); sibling at 35 (delta -4).
+    const proposed = rect(39, 300);
+    const sibling = rect(35, 100);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.x).toBe(40);
+  });
+});
+
+describe('computeSnap / X and Y axes are independent', () => {
+  test('snaps X to sibling AND Y to grid simultaneously', () => {
+    // proposed at (503, 37): X snaps to sibling.left=500; Y snaps to grid 40.
+    const proposed = rect(503, 37);
+    const sibling = rect(500, 300);
+    const r = computeSnap(proposed, [sibling], DEFAULTS);
+    expect(r.x).toBe(500);
+    expect(r.y).toBe(40);
+    expect(r.guides.length).toBe(2);
+    expect(r.guides.find((g) => g.axis === 'x')).toMatchObject({ pos: 500 });
+    expect(r.guides.find((g) => g.axis === 'y')).toMatchObject({ pos: 40 });
+  });
+});
+
+describe('computeSnap / multiple siblings at same pos merge into one guide', () => {
+  test('two siblings with the same left edge produce a single merged guide', () => {
+    const proposed = rect(503, 300, 100, 80);
+    const sibA = rect(500, 100, 100, 80); // y range [100, 180]
+    const sibB = rect(500, 500, 100, 80); // y range [500, 580]
+    const r = computeSnap(proposed, [sibA, sibB], DEFAULTS);
+    const xGuides = r.guides.filter((g) => g.axis === 'x');
+    expect(xGuides.length).toBe(1);
+    expect(xGuides[0]).toMatchObject({
+      pos: 500,
+      from: 100,
+      to: 580,
+    });
+  });
+});
+
+describe('computeSnap / no candidates', () => {
+  test('empty others + outside grid tolerance → identity, no guides', () => {
+    const r = computeSnap(rect(27, 27), [], DEFAULTS);
+    expect(r.x).toBe(27);
+    expect(r.y).toBe(27);
+    expect(r.guides).toEqual([]);
+  });
+});