@1agh/maude 0.19.1 → 0.21.0

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

@@ -0,0 +1,81 @@
+// Unit: Registry inspector-bridge — REST/WS writes to api.comments* must
+// reach the live Y.Array so collab peers see the change without waiting for
+// a cold-open re-seed.
+
+import { describe, expect, test } from 'bun:test';
+
+import * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+import { createRegistry } from '../collab/registry.ts';
+import type { RoomCallbacks } from '../collab/room.ts';
+
+function noopCallbacks(): RoomCallbacks {
+  return {
+    async seed() {},
+    async persistJson() {},
+    async persistBinary() {},
+  };
+}
+
+describe('Registry inspector-bridge', () => {
+  test('peek returns null when no room is live', () => {
+    const r = createRegistry(noopCallbacks());
+    expect(r.peek('absent')).toBeNull();
+  });
+
+  test('peek returns the room without creating one', () => {
+    const r = createRegistry(noopCallbacks());
+    expect(r.size()).toBe(0);
+    expect(r.peek('foo')).toBeNull();
+    expect(r.size()).toBe(0);
+    r.get('foo'); // create
+    expect(r.size()).toBe(1);
+    expect(r.peek('foo')).not.toBeNull();
+  });
+
+  test('syncRoomFromComments populates the live Y.Array', () => {
+    const r = createRegistry(noopCallbacks());
+    const room = r.get('canvas-slug');
+    expect(room.doc.getArray(Y_TYPES.comments).length).toBe(0);
+
+    r.syncRoomFromComments('canvas-slug', [
+      { id: 'c1', text: 'first', status: 'open' },
+      { id: 'c2', text: 'second', status: 'open' },
+    ]);
+
+    const arr = room.doc.getArray(Y_TYPES.comments);
+    expect(arr.length).toBe(2);
+    expect((arr.get(0) as { id: string }).id).toBe('c1');
+    expect((arr.get(1) as { id: string }).id).toBe('c2');
+  });
+
+  test('syncRoomFromComments replaces existing contents (idempotent)', () => {
+    const r = createRegistry(noopCallbacks());
+    const room = r.get('canvas-slug');
+    r.syncRoomFromComments('canvas-slug', [{ id: 'c1' }, { id: 'c2' }]);
+    r.syncRoomFromComments('canvas-slug', [{ id: 'c1' }, { id: 'c2' }, { id: 'c3' }]);
+    expect(room.doc.getArray(Y_TYPES.comments).length).toBe(3);
+    r.syncRoomFromComments('canvas-slug', []);
+    expect(room.doc.getArray(Y_TYPES.comments).length).toBe(0);
+  });
+
+  test('syncRoomFromComments is a no-op for slugs with no room', () => {
+    const r = createRegistry(noopCallbacks());
+    // Must not throw, must not create a room.
+    r.syncRoomFromComments('absent', [{ id: 'x' }]);
+    expect(r.peek('absent')).toBeNull();
+    expect(r.size()).toBe(0);
+  });
+
+  test('inspector-write origin triggers doc.update broadcast', async () => {
+    const r = createRegistry(noopCallbacks());
+    const room = r.get('echo-slug');
+    let lastOrigin: unknown = undefined;
+    room.doc.on('update', (_update, origin) => {
+      lastOrigin = origin;
+    });
+    r.syncRoomFromComments('echo-slug', [{ id: 'c1' }]);
+    expect(lastOrigin).toBe('inspector-write');
+  });
+});

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

@@ -0,0 +1,63 @@
+// Unit: helpers exported by ws.ts that gate the Phase 8 collab endpoint.
+// Pure functions — no Bun.serve / no fixtures needed. The full integration
+// (host-header rejection at the upgrade layer) is covered by the manual
+// curl smoke in the Task 1 validate row.
+
+import { describe, expect, test } from 'bun:test';
+
+import { isLoopbackHost, parseCollabSlug } from '../ws.ts';
+
+describe('parseCollabSlug', () => {
+  test('extracts slug from /_ws/collab/<slug>', () => {
+    expect(parseCollabSlug('/_ws/collab/foo')).toBe('foo');
+    expect(parseCollabSlug('/_ws/collab/ui-home_screen')).toBe('ui-home_screen');
+    expect(parseCollabSlug('/_ws/collab/A1B2c3')).toBe('A1B2c3');
+  });
+
+  test('rejects non-collab paths', () => {
+    expect(parseCollabSlug('/_ws')).toBeNull();
+    expect(parseCollabSlug('/_ws/inspector')).toBeNull();
+    expect(parseCollabSlug('/_ws/collab')).toBeNull();
+    expect(parseCollabSlug('/_ws/collab/')).toBeNull();
+    expect(parseCollabSlug('/api/comments')).toBeNull();
+  });
+
+  test('rejects slugs with disallowed chars (URL-encoded, slashes, dots)', () => {
+    expect(parseCollabSlug('/_ws/collab/foo/bar')).toBeNull();
+    expect(parseCollabSlug('/_ws/collab/foo.bar')).toBeNull();
+    expect(parseCollabSlug('/_ws/collab/foo%20bar')).toBeNull();
+  });
+});
+
+describe('isLoopbackHost', () => {
+  test('accepts loopback aliases with or without port', () => {
+    expect(isLoopbackHost('127.0.0.1:4399')).toBe(true);
+    expect(isLoopbackHost('127.0.0.1')).toBe(true);
+    expect(isLoopbackHost('localhost:4399')).toBe(true);
+    expect(isLoopbackHost('localhost')).toBe(true);
+    expect(isLoopbackHost('[::1]:4399')).toBe(true);
+    expect(isLoopbackHost('[::1]')).toBe(true);
+  });
+
+  test('case-insensitive', () => {
+    expect(isLoopbackHost('LOCALHOST:4399')).toBe(true);
+    expect(isLoopbackHost('LocalHost')).toBe(true);
+  });
+
+  test('rejects non-loopback hosts', () => {
+    expect(isLoopbackHost('example.com')).toBe(false);
+    expect(isLoopbackHost('example.com:4399')).toBe(false);
+    expect(isLoopbackHost('10.0.0.1:4399')).toBe(false);
+    expect(isLoopbackHost('192.168.1.1')).toBe(false);
+    expect(isLoopbackHost('host.docker.internal')).toBe(false);
+    // Common attacker patterns — host header smuggling tries.
+    expect(isLoopbackHost('127.0.0.1.attacker.com')).toBe(false);
+    expect(isLoopbackHost('localhost.attacker.com')).toBe(false);
+  });
+
+  test('handles missing / empty host gracefully', () => {
+    expect(isLoopbackHost(null)).toBe(false);
+    expect(isLoopbackHost('')).toBe(false);
+    expect(isLoopbackHost('   ')).toBe(false);
+  });
+});

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

@@ -0,0 +1,146 @@
+// Unit: y-websocket binary protocol round-trips. Validates the frames the
+// dev-server emits actually decode against a vanilla yjs/y-protocols peer.
+
+import { describe, expect, test } from 'bun:test';
+
+import * as decoding from 'lib0/decoding';
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+
+import {
+  MESSAGE_AWARENESS,
+  MESSAGE_SYNC,
+  encodeAwarenessFrame,
+  encodeHandshake,
+  encodeSyncUpdate,
+  handleMessage,
+} from '../collab/protocol.ts';
+
+function readType(frame: Uint8Array): number {
+  return decoding.readVarUint(decoding.createDecoder(frame));
+}
+
+describe('encodeHandshake', () => {
+  test('always emits sync step 1 frame', () => {
+    const doc = new Y.Doc();
+    const aw = new Awareness(doc);
+    const frames = encodeHandshake(doc, aw);
+    expect(frames.length).toBeGreaterThanOrEqual(1);
+    // biome-ignore lint/style/noNonNullAssertion: length asserted above
+    expect(readType(frames[0]!)).toBe(MESSAGE_SYNC);
+  });
+
+  test('appends awareness frame when awareness has state', () => {
+    const doc = new Y.Doc();
+    const aw = new Awareness(doc);
+    aw.setLocalState({ name: 'Alice', __connId: 'a' });
+    const frames = encodeHandshake(doc, aw);
+    expect(frames.length).toBe(2);
+    // biome-ignore lint/style/noNonNullAssertion: length asserted above
+    expect(readType(frames[0]!)).toBe(MESSAGE_SYNC);
+    // biome-ignore lint/style/noNonNullAssertion: length asserted above
+    expect(readType(frames[1]!)).toBe(MESSAGE_AWARENESS);
+  });
+
+  test('omits awareness frame when awareness is empty', () => {
+    const doc = new Y.Doc();
+    const aw = new Awareness(doc);
+    aw.setLocalState(null); // clear default
+    const frames = encodeHandshake(doc, aw);
+    expect(frames.length).toBe(1);
+  });
+});
+
+describe('encodeSyncUpdate', () => {
+  test('wraps a Y.Doc update bytes in a sync frame', () => {
+    const doc = new Y.Doc();
+    doc.getArray('comments').push([{ id: 'c1', text: 'hi' }]);
+    const update = Y.encodeStateAsUpdate(doc);
+    const frame = encodeSyncUpdate(update);
+    expect(readType(frame)).toBe(MESSAGE_SYNC);
+    // The wrapped update applied to a fresh doc should reproduce the state.
+    const replay = new Y.Doc();
+    // Strip the message-type byte and the sync-step opcode by re-running
+    // through handleMessage — that's the contract clients use too.
+    const aw = new Awareness(replay);
+    handleMessage(frame, replay, aw, { send() {} });
+    expect((replay.getArray('comments').get(0) as { text: string }).text).toBe('hi');
+  });
+});
+
+describe('encodeAwarenessFrame', () => {
+  test('emits awareness type byte + payload that applies to another Awareness', () => {
+    const docA = new Y.Doc();
+    const awA = new Awareness(docA);
+    awA.setLocalState({ name: 'Alice', __connId: 'a' });
+    const frame = encodeAwarenessFrame(awA, [awA.clientID]);
+    expect(readType(frame)).toBe(MESSAGE_AWARENESS);
+
+    const docB = new Y.Doc();
+    const awB = new Awareness(docB);
+    // Drop B's default local state so we can assert exactly one foreign peer
+    // landed in B's awareness registry.
+    awB.setLocalState(null);
+    handleMessage(frame, docB, awB, { send() {} });
+    const alice = awB.getStates().get(awA.clientID) as
+      | { name: string; __connId: string }
+      | undefined;
+    expect(alice?.name).toBe('Alice');
+    expect(alice?.__connId).toBe('a');
+  });
+});
+
+describe('handleMessage', () => {
+  test('full bidirectional handshake converges two peers', () => {
+    // Peer A: has comments
+    const docA = new Y.Doc();
+    docA.getArray('comments').push([{ id: 'c1', text: 'A wrote this' }]);
+    const awA = new Awareness(docA);
+
+    // Peer B: empty
+    const docB = new Y.Doc();
+    const awB = new Awareness(docB);
+
+    // Full handshake = each peer sends its own sync step 1, the other responds
+    // with sync step 2 (the diff). y-websocket's reference impl does the same.
+    const aFrames = encodeHandshake(docA, awA);
+    const bFrames = encodeHandshake(docB, awB);
+
+    // Cross-feed.
+    for (const frame of bFrames) {
+      const reply = handleMessage(frame, docA, awA, { send() {} });
+      if (reply) handleMessage(reply, docB, awB, { send() {} });
+    }
+    for (const frame of aFrames) {
+      const reply = handleMessage(frame, docB, awB, { send() {} });
+      if (reply) handleMessage(reply, docA, awA, { send() {} });
+    }
+
+    // After exchange B has A's comment.
+    expect(docB.getArray('comments').length).toBe(1);
+    const c = docB.getArray('comments').get(0) as { text: string };
+    expect(c.text).toBe('A wrote this');
+  });
+
+  test('post-handshake encodeSyncUpdate propagates a single edit', () => {
+    const docA = new Y.Doc();
+    const docB = new Y.Doc();
+    // A makes an edit and emits the diff via encodeSyncUpdate.
+    docA.getArray('comments').push([{ id: 'c2', text: 'later edit' }]);
+    const frame = encodeSyncUpdate(Y.encodeStateAsUpdate(docA));
+
+    const awB = new Awareness(docB);
+    handleMessage(frame, docB, awB, { send() {} });
+    expect(docB.getArray('comments').length).toBe(1);
+    expect((docB.getArray('comments').get(0) as { text: string }).text).toBe('later edit');
+  });
+
+  test('unknown message type is a noop (forward-compat)', () => {
+    const doc = new Y.Doc();
+    const aw = new Awareness(doc);
+    // Frame with message type 99 (unknown).
+    const frame = new Uint8Array([99]);
+    const reply = handleMessage(frame, doc, aw, { send() {} });
+    expect(reply).toBeNull();
+  });
+});

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

@@ -0,0 +1,182 @@
+// Unit: Room behavior — two in-memory peers see each other, debounced flush
+// fires, flush is idempotent, room teardown is clean.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import * as Y from 'yjs';
+
+import { encodeHandshake, encodeSyncUpdate, handleMessage } from '../collab/protocol.ts';
+import { type RoomCallbacks, type RoomConn, createRoom } from '../collab/room.ts';
+
+function makeConn(id: string): RoomConn & { recv: Uint8Array[] } {
+  const recv: Uint8Array[] = [];
+  return {
+    id,
+    send(payload: Uint8Array) {
+      recv.push(payload);
+    },
+    recv,
+  };
+}
+
+function makeCallbacks(): RoomCallbacks & {
+  jsonCalls: number;
+  binaryCalls: number;
+  lastJson: { slug: string; commentsLen: number } | null;
+} {
+  const cb = {
+    jsonCalls: 0,
+    binaryCalls: 0,
+    lastJson: null as { slug: string; commentsLen: number } | null,
+    async seed(_slug: string, _doc: Y.Doc) {
+      /* empty */
+    },
+    async persistJson(slug: string, doc: Y.Doc) {
+      cb.jsonCalls++;
+      cb.lastJson = { slug, commentsLen: doc.getArray('comments').length };
+    },
+    async persistBinary(_slug: string, _state: Uint8Array) {
+      cb.binaryCalls++;
+    },
+  };
+  return cb;
+}
+
+const DEBOUNCE_MS = 800;
+const SETTLE_MS = DEBOUNCE_MS + 100;
+
+describe('Room', () => {
+  test('two peers converge on Y.Doc updates', async () => {
+    const cb = makeCallbacks();
+    const room = createRoom('test-slug', cb);
+    const A = makeConn('a');
+    const B = makeConn('b');
+
+    await room.connect(A);
+    await room.connect(B);
+
+    // Drain handshake frames each peer received.
+    A.recv.length = 0;
+    B.recv.length = 0;
+
+    // Peer A produces an update; route it through the room (as the protocol
+    // would). Easiest path: mutate doc directly through a transaction tagged
+    // with A.
+    room.doc.transact(() => {
+      room.doc.getArray('comments').push([{ id: 'c1', text: 'hello' }]);
+    }, A);
+
+    // Room broadcasts the encoded update to all peers except A.
+    expect(A.recv.length).toBe(0);
+    expect(B.recv.length).toBe(1);
+
+    // B replays the frame against its own doc; the comment lands.
+    const docB = new Y.Doc();
+    const awBStub = (await import('y-protocols/awareness')).Awareness;
+    const awB = new awBStub(docB);
+    // biome-ignore lint/style/noNonNullAssertion: recv.length asserted in the prior expect()
+    handleMessage(B.recv[0]!, docB, awB, { send() {} });
+    expect(docB.getArray('comments').length).toBe(1);
+
+    await room.destroy();
+  });
+
+  test('debounced flush fires after 800ms of quiescence', async () => {
+    const cb = makeCallbacks();
+    const room = createRoom('debounce-slug', cb);
+    const A = makeConn('a');
+    await room.connect(A);
+
+    room.doc.transact(() => {
+      room.doc.getArray('comments').push([{ id: 'c1', text: 'one' }]);
+    }, A);
+    expect(cb.jsonCalls).toBe(0); // not yet — still inside debounce window
+
+    await Bun.sleep(SETTLE_MS);
+    expect(cb.jsonCalls).toBe(1);
+    expect(cb.binaryCalls).toBe(1);
+    expect(cb.lastJson?.commentsLen).toBe(1);
+
+    await room.destroy();
+  });
+
+  test('rapid updates collapse to a single flush at quiescence', async () => {
+    const cb = makeCallbacks();
+    const room = createRoom('coalesce-slug', cb);
+    const A = makeConn('a');
+    await room.connect(A);
+
+    for (let i = 0; i < 5; i++) {
+      room.doc.transact(() => {
+        room.doc.getArray('comments').push([{ id: `c${i}`, text: `n${i}` }]);
+      }, A);
+    }
+    expect(cb.jsonCalls).toBe(0);
+    await Bun.sleep(SETTLE_MS);
+    expect(cb.jsonCalls).toBe(1);
+    expect(cb.lastJson?.commentsLen).toBe(5);
+
+    await room.destroy();
+  });
+
+  test('explicit flush() bypasses the debounce', async () => {
+    const cb = makeCallbacks();
+    const room = createRoom('force-flush-slug', cb);
+    const A = makeConn('a');
+    await room.connect(A);
+
+    room.doc.transact(() => {
+      room.doc.getArray('comments').push([{ id: 'c1', text: 'one' }]);
+    }, A);
+    expect(cb.jsonCalls).toBe(0);
+
+    await room.flush();
+    expect(cb.jsonCalls).toBe(1);
+
+    // Idempotent — second flush with no further mutations doesn't write again.
+    await room.flush();
+    expect(cb.jsonCalls).toBe(1);
+
+    await room.destroy();
+  });
+
+  test('disconnect cleans up awareness states tagged with __connId', async () => {
+    const cb = makeCallbacks();
+    const room = createRoom('aw-cleanup-slug', cb);
+    const A = makeConn('a');
+    await room.connect(A);
+
+    // Simulate Alice publishing her awareness state with the matching __connId.
+    room.awareness.setLocalState({ name: 'Alice', __connId: 'a' });
+    expect(room.awareness.getStates().size).toBe(1);
+
+    room.disconnect(A);
+    expect(room.size()).toBe(0);
+    // Awareness state owned by the disconnected conn is gone.
+    const states = room.awareness.getStates();
+    for (const s of states.values()) {
+      expect((s as { __connId?: string }).__connId).not.toBe('a');
+    }
+
+    await room.destroy();
+  });
+
+  test('seed is called once even with concurrent connects', async () => {
+    let seedCalls = 0;
+    const cb: RoomCallbacks = {
+      async seed(_slug, _doc) {
+        seedCalls++;
+        await Bun.sleep(10);
+      },
+      async persistJson() {},
+      async persistBinary() {},
+    };
+    const room = createRoom('seed-once-slug', cb);
+    const A = makeConn('a');
+    const B = makeConn('b');
+    await Promise.all([room.connect(A), room.connect(B)]);
+    expect(seedCalls).toBe(1);
+
+    await room.destroy();
+  });
+});

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

@@ -0,0 +1,121 @@
+// Phase 8 Task 8 — multi-tab stress harness.
+//
+// Two in-memory peers attached to one Room, broadcasting cursor-shaped
+// Awareness updates at ~30 Hz for `STRESS_MS` (default 10 s in CI; the plan
+// spec calls for 2 min but a tighter CI default keeps the run under 15 s).
+// Measures:
+//
+//   - RSS growth via process.memoryUsage().rss (before vs after)
+//   - Y.Doc state size growth via Y.encodeStateAsUpdate(doc).byteLength
+//   - Awareness state cleanup — when both peers disconnect, no entries leak
+//
+// Pass thresholds (CI-safe):
+//   - RSS delta < 20 MB (plan spec; conservative because GC is non-deterministic)
+//   - Y.Doc growth < 100 KB (the spec ceiling is 500 KB for a 2-min run; with
+//     awareness ephemeral + no doc.update traffic, growth should be ~0).
+
+import { afterEach, describe, expect, test } from 'bun:test';
+
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+
+import { type RoomConn, createRoom } from '../collab/room.ts';
+
+const STRESS_MS = Number(process.env.MAUDE_STRESS_MS ?? 10_000);
+const RSS_GROWTH_LIMIT_MB = 20;
+const YDOC_GROWTH_LIMIT_BYTES = 100_000;
+
+function makeConn(id: string): RoomConn {
+  return {
+    id,
+    send() {
+      /* drain — we don't care about the network bytes; the memory pressure
+         is on the Awareness map + Y.Doc internals, not the WS buffer */
+    },
+  };
+}
+
+describe('multi-tab stress (Phase 8 Task 8)', () => {
+  let cleanupRoom: (() => Promise<void>) | null = null;
+
+  afterEach(async () => {
+    if (cleanupRoom) {
+      await cleanupRoom();
+      cleanupRoom = null;
+    }
+  });
+
+  test(
+    '30 Hz × STRESS_MS × 2 peers — bounded RSS + Y.Doc growth',
+    async () => {
+      const room = createRoom('stress-slug', {
+        async seed() {},
+        async persistJson() {},
+        async persistBinary() {},
+      });
+      cleanupRoom = () => room.destroy();
+
+      const A = makeConn('peer-a');
+      const B = makeConn('peer-b');
+      await room.connect(A);
+      await room.connect(B);
+
+      // Each peer has its own local Awareness instance to model what real
+      // clients do — they don't share a memory address space with the server's
+      // awareness. We pump updates by setting state on the server-side
+      // awareness directly (the server's room.awareness is what the real WS
+      // peers' setLocalState() would land in via applyAwarenessUpdate).
+      const awA = new Awareness(new Y.Doc());
+      const awB = new Awareness(new Y.Doc());
+      awA.setLocalState({ name: 'Alice', color: '#f00', cursor: { x: 0, y: 0 }, __connId: A.id });
+      awB.setLocalState({ name: 'Bob', color: '#0f0', cursor: { x: 0, y: 0 }, __connId: B.id });
+
+      const rssBefore = process.memoryUsage().rss;
+      const docSizeBefore = Y.encodeStateAsUpdate(room.doc).byteLength;
+
+      const start = Date.now();
+      const tickInterval = 33; // ~30 Hz
+      let aX = 0;
+      let bX = 0;
+      let updates = 0;
+      while (Date.now() - start < STRESS_MS) {
+        aX = (aX + 1) % 1000;
+        bX = (bX + 7) % 1000;
+        awA.setLocalState({
+          name: 'Alice',
+          color: '#f00',
+          cursor: { x: aX, y: aX },
+          __connId: A.id,
+        });
+        awB.setLocalState({
+          name: 'Bob',
+          color: '#0f0',
+          cursor: { x: bX, y: bX },
+          __connId: B.id,
+        });
+        updates += 2;
+        await Bun.sleep(tickInterval);
+      }
+
+      const rssAfter = process.memoryUsage().rss;
+      const docSizeAfter = Y.encodeStateAsUpdate(room.doc).byteLength;
+
+      const rssGrowthMb = (rssAfter - rssBefore) / (1024 * 1024);
+      const docGrowth = docSizeAfter - docSizeBefore;
+
+      console.log(
+        `[stress] ${updates} awareness updates over ${STRESS_MS} ms → ` +
+          `RSS Δ=${rssGrowthMb.toFixed(1)} MB, Y.Doc Δ=${docGrowth} bytes`
+      );
+
+      expect(rssGrowthMb).toBeLessThan(RSS_GROWTH_LIMIT_MB);
+      expect(docGrowth).toBeLessThan(YDOC_GROWTH_LIMIT_BYTES);
+
+      // Disconnect both peers; size should go to 0.
+      room.disconnect(A);
+      room.disconnect(B);
+      expect(room.size()).toBe(0);
+    },
+    STRESS_MS + 5_000
+  );
+});

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