create-harness-vibe-coding 0.8.19 → 0.9.3

package/src/wf-ui-server/__tests__/graph-layout-agent-tree.test.mjs

@@ -0,0 +1,254 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { agentTreePositions, GRAPH_SLOT_W, GRAPH_SLOT_H } from '../graph-layout.mjs';
+
+// Agent-tree compact layout contract (task-agent-tree-layout W1 pins, RED first).
+// Round-2 user requirements: main agent = core anchor centered; subagents one
+// layer BELOW main arranged as an agent TREE (multi-level); non-agent nodes
+// ("scattered") arranged as a compact MATRIX BAND ABOVE their owner agent;
+// layout NEVER creates or modifies edges (pure positions).
+//
+// Pinned API:
+//   agentTreePositions(nodes, edges, opts)
+//     nodes: Array<{id, width?, height?, agentKind?, parentAgentId?, parentNodeId?}>
+//       agentKind: 'main' | 'subagent'  (any other value or absent = non-agent)
+//       width/height default to GRAPH_SLOT_W/H (280x180)
+//     edges: Array<{from, to, direction?, relation?}>  — used ONLY for
+//       agent-tree parenting (first edge to another agent); direction ignored.
+//     opts: {
+//       origin?: {x, y},   default {260, 220} — origin.x is the CENTER x of
+//                          the main agent; origin.y is the TOP of its band.
+//       gapX?: number,     default 64   (edge-to-edge horizontal spacing)
+//       gapY?: number,     default 48   (edge-to-edge vertical spacing)
+//       dockedPairs?: Array<{aId, bId, offset: {x,y}}>  — glued exactly:
+//                          positions[b] = positions[a] + offset.
+//     }
+//   returns {[nodeId]: {x, y}} — every input node placed exactly once;
+//   deterministic (same input -> deep-equal output).
+//
+// Geometry rules pinned below:
+//   - emitted positions are TOP-LEFT corners (graph-map/UI convention);
+//     opts.origin.x anchors the main agent's CENTER x, origin.y the band top.
+//   - agent children sorted by id asc; subtree width = max(unit width,
+//     sum(child subtree widths) + gapX*(n-1)); parent centered over children.
+//   - asset matrix: cols = clamp(ceil(sqrt(n)), 1, 6), row-major by id asc,
+//     row height = tallest unit + gapY, each row centered on owner center;
+//     band sits ABOVE the owner (bandTop = parentRowBottom + gapY; owner y =
+//     bandTop + bandH + (bandH > 0 ? gapY : 0)).
+//   - clearance floor: no two rects closer than 16px (shared AC contract).
+
+const ORIGIN = { x: 0, y: 0 };
+const NODE = { width: 100, height: 50 };
+const S = (id, extra = {}) => ({ id, ...NODE, ...extra });
+const E = (from, to, direction = 'bidirectional') => ({ from, to, direction });
+const AGENT = { agentKind: 'subagent' };
+
+function minRectGap(positions, nodes) {
+  const rects = nodes.map((node) => {
+    const p = positions[node.id];
+    assert.ok(p, `agentTreePositions must place ${node.id}`);
+    assert.ok(Number.isFinite(Number(p.x)) && Number.isFinite(Number(p.y)), `position for ${node.id} must be numeric`);
+    return {
+      id: node.id,
+      x: Number(p.x),
+      y: Number(p.y),
+      w: Number.isFinite(Number(node.width)) ? Number(node.width) : GRAPH_SLOT_W,
+      h: Number.isFinite(Number(node.height)) ? Number(node.height) : GRAPH_SLOT_H,
+    };
+  });
+  let minGap = Infinity;
+  for (let i = 0; i < rects.length; i++) {
+    for (let j = i + 1; j < rects.length; j++) {
+      const a = rects[i];
+      const b = rects[j];
+      const sepX = Math.max(a.x, b.x) - Math.min(a.x + a.w, b.x + b.w);
+      const sepY = Math.max(a.y, b.y) - Math.min(a.y + a.h, b.y + b.h);
+      minGap = Math.min(minGap, Math.max(sepX, sepY));
+    }
+  }
+  return minGap;
+}
+
+function assertNoOverlap16(positions, nodes) {
+  const gap = minRectGap(positions, nodes);
+  assert.ok(gap >= 16, `all rects must keep >= 16px clearance (min gap was ${gap})`);
+}
+
+test('A1: main centered; subagents one row below, centered under main, sorted by id', () => {
+  const nodes = [
+    S('M', { agentKind: 'main' }),
+    S('S1', AGENT),
+    S('S2', AGENT),
+    S('S3', AGENT),
+  ];
+  const edges = [E('M', 'S1'), E('M', 'S2'), E('M', 'S3')];
+  const positions = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  // Positions are TOP-LEFT; origin.x=0 anchors main's CENTER, so main's left
+  // is -50 (width 100). Row width 3*100 + 2*64 = 428 centered on 0 ->
+  // centers -164, 0, 164 -> lefts -214, -50, 114.
+  assert.deepEqual(positions.M, { x: -50, y: 0 }, 'main center sits on origin.x');
+  assert.ok(
+    positions.S1.y === positions.S2.y && positions.S2.y === positions.S3.y,
+    'subagents share ONE layer below main',
+  );
+  assert.ok(positions.S1.y > positions.M.y, 'subagent layer is BELOW main');
+  assert.equal(positions.S2.x, positions.M.x, 'middle subagent centers under main');
+  assert.equal(positions.S1.x, -214, 'first subagent left of center');
+  assert.equal(positions.S3.x, 114, 'last subagent right of center');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A2: scattered assets form a matrix band ABOVE main, centered, row-major', () => {
+  const nodes = [S('M', { agentKind: 'main' }), S('a1'), S('a2'), S('a3')];
+  const positions = agentTreePositions(nodes, [], { origin: ORIGIN });
+  // cols = clamp(ceil(sqrt(3)), 1, 6) = 2 -> row1: a1,a2; row2: a3.
+  // Band height = 50 + 48 + 50 = 148; M.y = bandTop(0) + 148 + 48 = 196.
+  assert.ok(positions.a1.y < positions.M.y && positions.a2.y < positions.M.y && positions.a3.y < positions.M.y, 'assets ABOVE main');
+  assert.equal(positions.a1.y, 0, 'first matrix row at band top');
+  assert.equal(positions.a2.y, 0, 'second item on first matrix row');
+  assert.equal(positions.a3.y, 98, 'third item wraps to the second matrix row');
+  assert.equal(positions.M.x, -50, 'main center keeps the origin x (top-left -50)');
+  assert.equal(positions.M.y, 196, 'main sits below its own band');
+  // Row1 width = 2*100 + 64 = 264 centered on 0 -> lefts -132, 32.
+  assert.equal(positions.a1.x, -132, 'row1 left item');
+  assert.equal(positions.a2.x, 32, 'row1 right item');
+  assert.equal(positions.a3.x, -50, 'row2 single item centered on main');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A3: multi-level agent tree: nested subagent below its parent, siblings side by side', () => {
+  const nodes = [
+    S('M', { agentKind: 'main' }),
+    S('S1', AGENT),
+    S('S1b', AGENT),
+    S('S2', AGENT),
+  ];
+  const edges = [E('M', 'S1'), E('S1', 'S1b'), E('M', 'S2')];
+  const positions = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  assert.equal(positions.S1.y, 98, 'first agent row below main (50 + 48)');
+  assert.equal(positions.S2.y, 98, 'sibling shares the first agent row');
+  assert.equal(positions.S1b.y, 196, 'nested subagent one row deeper');
+  assert.equal(positions.S1.x, -132, 'left sibling subtree (center -82 -> left -132)');
+  assert.equal(positions.S2.x, 32, 'right sibling subtree (center 82 -> left 32)');
+  assert.equal(positions.S1b.x, positions.S1.x, 'nested subagent centers under its parent');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A4: explicit parentAgentId wins over bridge edges', () => {
+  const nodes = [
+    S('M', { agentKind: 'main' }),
+    S('S1', AGENT),
+    S('S2', { ...AGENT, parentAgentId: 'S1' }),
+  ];
+  const edges = [E('M', 'S1'), E('M', 'S2')];
+  const positions = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  assert.equal(positions.S1.x, positions.M.x, 'S1 (only child) centers under M');
+  assert.ok(positions.S2.y > positions.S1.y, 'S2 sits BELOW S1 despite bridging M');
+  assert.equal(positions.S2.x, positions.S1.x, 'S2 centers under its declared parent');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A5: asset with parentAgentId lands in the band ABOVE its owner subagent', () => {
+  const nodes = [
+    S('M', { agentKind: 'main' }),
+    S('S1', AGENT),
+    S('X', { parentAgentId: 'S1' }),
+  ];
+  const edges = [E('M', 'S1')];
+  const positions = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  assert.ok(positions.X.y < positions.S1.y, 'asset band is ABOVE the owner agent');
+  assert.ok(positions.X.y > positions.M.y, 'subagent band sits below main');
+  assert.equal(positions.X.x, positions.S1.x, 'band centers on the owner');
+  // X at bandTop 98, S1.y = 98 + 50 + 48 = 196.
+  assert.equal(positions.X.y, 98, 'band top = main bottom + gapY');
+  assert.equal(positions.S1.y, 196, 'owner below its own band');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A5b: parentNodeId chain resolves ownership to an agent', () => {
+  const nodes = [
+    S('M', { agentKind: 'main' }),
+    S('S1', AGENT),
+    S('child', { parentNodeId: 'X' }),
+    S('X', { parentNodeId: 'S1' }),
+  ];
+  const edges = [E('M', 'S1')];
+  const positions = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  assert.ok(positions.X.y < positions.S1.y, 'chain tail asset above the owner agent');
+  assert.ok(positions.child.y < positions.S1.y, 'chain head asset above the owner agent');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A6: no main agent -> flat fallback: agents in one root row, assets band above, centered', () => {
+  const nodes = [S('A', AGENT), S('B', AGENT), S('x1'), S('x2')];
+  const edges = [E('A', 'B')];
+  const positions = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  assert.equal(positions.A.y, positions.B.y, 'agents share one root row');
+  assert.ok(positions.x1.y < positions.A.y && positions.x2.y < positions.A.y, 'assets above the agent row');
+  assert.equal(positions.x1.y, 0, 'band top at origin');
+  assert.equal(positions.A.y, 98, 'agent row below the band (50 + 48)');
+  assert.equal(positions.A.x, -132, 'agents centered as a row (center -82 -> left -132)');
+  assert.equal(positions.B.x, 32, 'agents centered as a row (center 82 -> left 32)');
+  assert.equal(positions.x1.x, -132, 'asset matrix centered on the agent row');
+  assert.equal(positions.x2.x, 32, 'asset matrix centered on the agent row');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A7: docked pair glued exactly; child row clears the glued unit extent', () => {
+  const nodes = [
+    S('M', { agentKind: 'main' }),
+    S('S1', AGENT),
+    S('X'),
+  ];
+  const edges = [E('M', 'S1')];
+  const dockedPairs = [{ aId: 'M', bId: 'X', offset: { x: 12, y: 196 } }];
+  const positions = agentTreePositions(nodes, edges, { origin: ORIGIN, dockedPairs });
+  assert.equal(positions.X.x, positions.M.x + 12, 'dock keeps its x offset exactly');
+  assert.equal(positions.X.y, positions.M.y + 196, 'dock keeps its y offset exactly');
+  // X extends M's unit down to y=246; S1 must clear 246 + 16.
+  assert.ok(positions.S1.y >= positions.M.y + 246 + 16, 'child row clears the glued unit');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A8: deterministic: same input -> deep-equal output', () => {
+  const nodes = [
+    S('M', { agentKind: 'main' }),
+    S('S1', AGENT),
+    S('S1b', AGENT),
+    S('S2', AGENT),
+    S('a1', { parentAgentId: 'S1' }),
+    S('a2'),
+  ];
+  const edges = [E('M', 'S1'), E('S1', 'S1b'), E('M', 'S2')];
+  const first = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  const second = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  assert.deepEqual(second, first);
+  assertNoOverlap16(first, nodes);
+});
+
+test('A9: agent parenting cycle is safe: both agents placed on the root row', () => {
+  const nodes = [
+    S('A', { ...AGENT, parentAgentId: 'B' }),
+    S('B', { ...AGENT, parentAgentId: 'A' }),
+  ];
+  const positions = agentTreePositions(nodes, [], { origin: ORIGIN });
+  assert.equal(positions.A.y, positions.B.y, 'cycle members share the root row');
+  assert.ok(positions.A.x !== positions.B.x, 'never stacked on one point');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A10: compact: subagent row sits right below main (no slack gap)', () => {
+  const nodes = [S('M', { agentKind: 'main' }), S('S1', AGENT)];
+  const edges = [E('M', 'S1')];
+  const positions = agentTreePositions(nodes, edges, { origin: ORIGIN });
+  // main bottom 50 + gapY 48 = 98 — exactly one gap, nothing extra.
+  assert.equal(positions.S1.y, 98, 'subagent row advances by main height + gapY only');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('A11: defaults pinned: origin {260,220} centers a lone main agent there', () => {
+  const positions = agentTreePositions([S('M', { agentKind: 'main' })], [], {});
+  // origin.x anchors the CENTER (width 100 -> top-left 210); origin.y is the
+  // band top = the agent's top when no assets exist.
+  assert.deepEqual(positions.M, { x: 210, y: 220 }, 'default origin centers main at {260,220}');
+});

package/src/wf-ui-server/__tests__/graph-layout-tidy.test.mjs

@@ -0,0 +1,260 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { tidyPositions, GRAPH_SLOT_W, GRAPH_SLOT_H } from '../graph-layout.mjs';
+
+// Tidy full-graph layout contract (AC-003): hierarchical re-layout driven by
+// EDGE DIRECTION (not parentNodeId), deterministic, zero overlaps for cyclic /
+// multi-component / isolated graphs, docked pairs glued.
+//
+// Pinned API (W1 synthesis; implementers add tidyPositions to graph-layout.mjs):
+//   tidyPositions(nodes, edges, opts)
+//     nodes: Array<{id, width?, height?}>   size fallback 280x180 (GRAPH_SLOT_W/H)
+//     edges: Array<{from, to, direction?}>  'source-to-target' | 'bidirectional'
+//                                           (default 'source-to-target')
+//     opts: {
+//       origin?: {x, y},        default {x: 260, y: 220}
+//       gapX?: number,          default 420
+//       gapY?: number,          default 140
+//       parentNodeId?: string,  optional root anchor (unused by layer order)
+//       dockedPairs?: Array<{aId, bId, offset: {x, y}}>
+//         // b is docked to a; output must satisfy EXACTLY:
+//         //   positions[b] = { x: positions[a].x + offset.x, y: positions[a].y + offset.y }
+//     }
+//   returns {[nodeId]: {x, y}} — every input node placed exactly once;
+//   deterministic (same input -> deep-equal output).
+//
+// Rects use node width/height when given, else GRAPH_SLOT_W/GRAPH_SLOT_H.
+// AC-003 minimum clearance between any two rects: 16px.
+
+const DEFAULT_ORIGIN = { x: 260, y: 220 };
+const DEFAULT_GAP = { x: 420, y: 140 };
+
+// Minimum pairwise rect gap across all nodes; negative when any pair overlaps.
+function minRectGap(positions, nodes) {
+  const rects = nodes.map(node => {
+    const p = positions[node.id];
+    assert.ok(p, `tidyPositions must place ${node.id}`);
+    assert.ok(Number.isFinite(Number(p.x)) && Number.isFinite(Number(p.y)), `position for ${node.id} must be numeric`);
+    return {
+      id: node.id,
+      x: Number(p.x),
+      y: Number(p.y),
+      w: Number.isFinite(Number(node.width)) ? Number(node.width) : GRAPH_SLOT_W,
+      h: Number.isFinite(Number(node.height)) ? Number(node.height) : GRAPH_SLOT_H,
+    };
+  });
+  let minGap = Infinity;
+  for (let i = 0; i < rects.length; i++) {
+    for (let j = i + 1; j < rects.length; j++) {
+      const a = rects[i];
+      const b = rects[j];
+      const sepX = Math.max(a.x, b.x) - Math.min(a.x + a.w, b.x + b.w);
+      const sepY = Math.max(a.y, b.y) - Math.min(a.y + a.h, b.y + b.h);
+      minGap = Math.min(minGap, Math.max(sepX, sepY));
+    }
+  }
+  return minGap;
+}
+
+function assertNoOverlap16(positions, nodes) {
+  const gap = minRectGap(positions, nodes);
+  assert.ok(
+    gap >= 16,
+    `AC-003: all rects must keep >= 16px clearance (min gap was ${gap})`,
+  );
+}
+
+test('T1 (AC-003) chain A->B->C is layered by edge direction and deterministic', () => {
+  const nodes = [{ id: 'A' }, { id: 'B' }, { id: 'C' }];
+  const edges = [
+    { from: 'A', to: 'B', direction: 'source-to-target' },
+    { from: 'B', to: 'C', direction: 'source-to-target' },
+  ];
+  const first = tidyPositions(nodes, edges, {});
+  const second = tidyPositions(nodes, edges, {});
+  assert.deepEqual(second, first, 'deterministic: same input -> same output');
+
+  const ids = Object.keys(first).sort();
+  assert.deepEqual(ids, ['A', 'B', 'C'], 'every node must be placed exactly once');
+  assert.ok(
+    first.A.y < first.B.y && first.B.y < first.C.y,
+    `layers ordered by edge direction: A.y=${first.A.y} < B.y=${first.B.y} < C.y=${first.C.y}`,
+  );
+  assertNoOverlap16(first, nodes);
+});
+
+test('T2 (AC-003) bidirectional edge keeps both nodes on the same layer', () => {
+  const nodes = [{ id: 'A' }, { id: 'B' }];
+  const edges = [{ from: 'A', to: 'B', direction: 'bidirectional' }];
+  const positions = tidyPositions(nodes, edges, {});
+  assert.equal(
+    positions.A.y,
+    positions.B.y,
+    'a bidirectional edge imposes no layer order, so both nodes share one layer',
+  );
+  assert.notEqual(positions.A.x, positions.B.x, 'same-layer nodes are side by side');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('T3 (AC-003) cyclic graph A->B->C->A: all nodes placed, no overlaps, deterministic', () => {
+  const nodes = [{ id: 'A' }, { id: 'B' }, { id: 'C' }];
+  const edges = [
+    { from: 'A', to: 'B' },
+    { from: 'B', to: 'C' },
+    { from: 'C', to: 'A' },
+  ];
+  const first = tidyPositions(nodes, edges, {});
+  const second = tidyPositions(nodes, edges, {});
+  assert.deepEqual(second, first);
+  assert.deepEqual(Object.keys(first).sort(), ['A', 'B', 'C'], 'cycle back-edges must not drop nodes');
+  assertNoOverlap16(first, nodes);
+});
+
+test('T4 (AC-003) multi-component + isolated graphs: internal chain order kept, no overlaps', () => {
+  const nodes = [{ id: 'A' }, { id: 'B' }, { id: 'C' }, { id: 'D' }, { id: 'E' }];
+  const edges = [
+    { from: 'A', to: 'B' },
+    { from: 'C', to: 'D' },
+  ];
+  const positions = tidyPositions(nodes, edges, {});
+  assert.deepEqual(Object.keys(positions).sort(), ['A', 'B', 'C', 'D', 'E']);
+  assert.ok(positions.A.y < positions.B.y, 'chain A->B keeps its layer order');
+  assert.ok(positions.C.y < positions.D.y, 'chain C->D keeps its layer order');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('T5 (AC-003) size variance: a 560x358 node never overlaps a default-size neighbor', () => {
+  const nodes = [
+    { id: 'A', width: 560, height: 358 },
+    { id: 'B' },
+  ];
+  const edges = [{ from: 'A', to: 'B' }];
+  const positions = tidyPositions(nodes, edges, {});
+  assert.ok(positions.A.y < positions.B.y, 'chain order kept with mixed sizes');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('T6 (AC-003) docked pairs are glued: relative offset preserved exactly', () => {
+  const nodes = [{ id: 'A' }, { id: 'B' }, { id: 'C' }];
+  const edges = [{ from: 'A', to: 'C' }];
+  // y-offset 196 = one node height (180) + 16px clearance, so the glued pair
+  // itself also satisfies the min-gap rule (the no-overlap contract applies
+  // between layout units; a docked pair is one unit).
+  const dockedPairs = [{ aId: 'A', bId: 'B', offset: { x: 12, y: 196 } }];
+  const positions = tidyPositions(nodes, edges, { dockedPairs });
+  // Pinned dockedPairs shape: positions[b] = positions[a] + offset exactly.
+  assert.equal(positions.B.x, positions.A.x + 12, 'docked pair keeps its x offset');
+  assert.equal(positions.B.y, positions.A.y + 196, 'docked pair keeps its y offset');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('T7 (AC-003) defaults: opts optional, plain chain still ordered and clean', () => {
+  const nodes = [{ id: 'X' }, { id: 'Y' }];
+  const edges = [{ from: 'X', to: 'Y' }];
+  const positions = tidyPositions(nodes, edges);
+  assert.ok(positions.X.y < positions.Y.y, 'default origin/gap still order the chain');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('T8 (AC-003) opts.origin and opts.gapY are honored', () => {
+  const nodes = [{ id: 'A' }, { id: 'B' }];
+  const edges = [{ from: 'A', to: 'B' }];
+  const opts = { origin: { x: 0, y: 0 }, gapX: 300, gapY: 400 };
+  const positions = tidyPositions(nodes, edges, opts);
+  assert.deepEqual(
+    positions.A,
+    { x: 0, y: 0 },
+    'first layer starts at opts.origin',
+  );
+  assert.equal(
+    positions.B.y,
+    0 + 400,
+    'layer rows advance by opts.gapY',
+  );
+  assertNoOverlap16(positions, nodes);
+});
+
+test('T9 (AC-003) defaults match the pinned constants', () => {
+  // Locks the documented defaults so server.mjs GRAPH_LAYOUT_DEFAULTS stays in
+  // sync with the unit API.
+  const nodes = [{ id: 'A' }];
+  const positions = tidyPositions(nodes, [], {});
+  assert.deepEqual(positions.A, DEFAULT_ORIGIN, 'origin defaults to {260,220}');
+  assert.ok(DEFAULT_GAP.x >= GRAPH_SLOT_W + 16 && DEFAULT_GAP.y >= 16, 'default gaps keep clearance');
+});
+
+// ── W5 review pins (task-optimize-graph-layout) ──────────────────────────────
+// The four cases below pin W4 review findings MED-3 / MED-4 / LOW-9. All are
+// RED against the current engine and must go GREEN with the W5 fix wave:
+//   T10 (MED-3): a top-docked capsule (negative y offset) extends ABOVE its
+//     anchor; the anchor row must advance enough that the glued pair's union
+//     clears the row above.
+//   T11 (MED-4a): chained docks (B is A's slave AND C's anchor) must be laid
+//     out as one glued chain — every node placed, glue exact, no overlaps.
+//   T12 (MED-4b): an A<->B dock cycle must place both nodes, never overlap,
+//     and stay deterministic.
+//   T13 (LOW-9): opts.gapX below the 16px minimum clearance must be clamped.
+
+test('T10 (AC-003/MED-3) top-docked capsule (negative offset) never overlaps the row above', () => {
+  // TALL (600 tall) on the row above; A anchors a capsule docked 600px UP
+  // (offset y:-600). The pair's union bbox reaches from A.y-600 to A.y+180,
+  // so the anchor row must advance for that upward extent: B must clear TALL
+  // by >= 16px.
+  const nodes = [
+    { id: 'TALL', width: 280, height: 600 },
+    { id: 'A' },
+    { id: 'B' },
+  ];
+  const edges = [{ from: 'TALL', to: 'A', direction: 'source-to-target' }];
+  const dockedPairs = [{ aId: 'A', bId: 'B', offset: { x: 0, y: -600 } }];
+  const positions = tidyPositions(nodes, edges, { dockedPairs });
+  assert.deepEqual(Object.keys(positions).sort(), ['A', 'B', 'TALL'], 'every node placed exactly once');
+  assert.equal(positions.B.x, positions.A.x, 'docked pair keeps its x offset');
+  assert.equal(positions.B.y, positions.A.y - 600, 'docked pair keeps its y offset');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('T11 (AC-003/MED-4a) chained docks (slave-as-anchor) place all nodes with no overlaps', () => {
+  // Chain A -> B -> C: B is A's dock slave AND the anchor of C's pair.
+  // The chain must behave as ONE glued unit (extent 196+196+180 tall), so a
+  // node on the row below the anchor (X via edge A->X) never collides with C.
+  const nodes = [{ id: 'A' }, { id: 'B' }, { id: 'C' }, { id: 'X' }];
+  const edges = [{ from: 'A', to: 'X', direction: 'source-to-target' }];
+  const dockedPairs = [
+    { aId: 'A', bId: 'B', offset: { x: 0, y: 196 } },
+    { aId: 'B', bId: 'C', offset: { x: 0, y: 196 } },
+  ];
+  const positions = tidyPositions(nodes, edges, { dockedPairs });
+  assert.deepEqual(Object.keys(positions).sort(), ['A', 'B', 'C', 'X'], 'every node placed exactly once');
+  // Glue relations stay exact wherever the chain is resolvable.
+  assert.equal(positions.B.x, positions.A.x, 'chain link 1 keeps its x offset');
+  assert.equal(positions.B.y, positions.A.y + 196, 'chain link 1 keeps its y offset');
+  assert.equal(positions.C.x, positions.B.x, 'chain link 2 keeps its x offset');
+  assert.equal(positions.C.y, positions.B.y + 196, 'chain link 2 keeps its y offset');
+  assertNoOverlap16(positions, nodes);
+});
+
+test('T12 (AC-003/MED-4b) dock cycle A<->B: both placed, no overlap, deterministic', () => {
+  // Two dock links that agree on the same geometry (B = A + (300,0) and
+  // A = B + (-300,0)) must resolve deterministically instead of collapsing
+  // both nodes onto one spot.
+  const nodes = [{ id: 'A' }, { id: 'B' }];
+  const dockedPairs = [
+    { aId: 'A', bId: 'B', offset: { x: 300, y: 0 } },
+    { aId: 'B', bId: 'A', offset: { x: -300, y: 0 } },
+  ];
+  const first = tidyPositions(nodes, [], { dockedPairs });
+  const second = tidyPositions(nodes, [], { dockedPairs });
+  assert.deepEqual(second, first, 'deterministic: same input -> same output');
+  assert.deepEqual(Object.keys(first).sort(), ['A', 'B'], 'both nodes placed exactly once');
+  assertNoOverlap16(first, nodes);
+});
+
+test('T13 (AC-003/LOW-9) gapX below the 16px minimum clearance is clamped', () => {
+  // opts.gapX = 4 would let two same-row units sit only 4px apart; the engine
+  // must clamp the effective clearance so minRectGap never drops below 16.
+  const nodes = [{ id: 'A' }, { id: 'B' }];
+  const edges = [{ from: 'A', to: 'B', direction: 'bidirectional' }];
+  const positions = tidyPositions(nodes, edges, { gapX: 4 });
+  assertNoOverlap16(positions, nodes);
+});

package/src/wf-ui-server/__tests__/graph-layout.test.mjs

@@ -0,0 +1,84 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  autoPlaceNode,
+  layeredTreePositions,
+  GRAPH_SLOT_W,
+  GRAPH_SLOT_H,
+  GRAPH_ORIGIN,
+} from '../graph-layout.mjs';
+
+// Occupancy-aware auto-layout contract: new auto-placed nodes never overlap
+// any existing node (auto or dragged); children sit below their parents; the
+// full-graph relayout is a deterministic layered tree.
+
+test('G1 sequential auto-placement never overlaps (20 nodes)', () => {
+  const positions = {};
+  const placed = [];
+  for (let i = 0; i < 20; i++) {
+    const pos = autoPlaceNode(positions, {});
+    placed.push(pos);
+    positions[`n-${i}`] = pos;
+  }
+  const seen = new Set();
+  for (const { x, y } of placed) {
+    const key = `${x},${y}`;
+    assert.ok(!seen.has(key), `duplicate slot ${key}`);
+    seen.add(key);
+  }
+});
+
+test('G2 children land on the row below the parent, near the parent column', () => {
+  const parent = { x: GRAPH_ORIGIN.x + 2 * GRAPH_SLOT_W, y: GRAPH_ORIGIN.y };
+  const child1 = autoPlaceNode({ parent }, { parent });
+  assert.equal(child1.y, GRAPH_ORIGIN.y + GRAPH_SLOT_H);
+  assert.equal(child1.x, parent.x, 'first child takes the parent column');
+  const child2 = autoPlaceNode({ parent, child1 }, { parent });
+  assert.equal(child2.y, child1.y);
+  assert.equal(Math.abs(child2.x - parent.x), GRAPH_SLOT_W, 'second child takes the adjacent column');
+});
+
+test('G3 a dragged node occupying a cell is avoided', () => {
+  const dragged = { x: GRAPH_ORIGIN.x, y: GRAPH_ORIGIN.y };
+  const pos = autoPlaceNode({ dragged }, {});
+  assert.notDeepEqual(pos, dragged);
+  // The first free root slot with col 0 taken is the next column.
+  assert.equal(pos.x, GRAPH_ORIGIN.x + GRAPH_SLOT_W);
+  assert.equal(pos.y, GRAPH_ORIGIN.y);
+});
+
+test('G4 layered tree: roots side by side, children below, no collisions', () => {
+  const nodes = [
+    { nodeId: 'root-a' },
+    { nodeId: 'child-a1', parentNodeId: 'root-a' },
+    { nodeId: 'child-a2', parentNodeId: 'root-a' },
+    { nodeId: 'grand-a1', parentNodeId: 'child-a1' },
+    { nodeId: 'root-b' },
+    { nodeId: 'child-b1', parentNodeId: 'root-b' },
+  ];
+  const positions = layeredTreePositions(nodes, {});
+  const seen = new Set();
+  for (const [id, { x, y }] of Object.entries(positions)) {
+    assert.ok(!seen.has(`${x},${y}`), `collision at ${x},${y} for ${id}`);
+    seen.add(`${x},${y}`);
+  }
+  assert.equal(positions['root-a'].y, positions['root-b'].y, 'roots share row 0');
+  assert.ok(positions['root-b'].x > positions['root-a'].x, 'roots side by side');
+  assert.equal(positions['child-a1'].y, positions['root-a'].y + GRAPH_SLOT_H, 'children one row below');
+  assert.equal(positions['child-a2'].y, positions['root-a'].y + GRAPH_SLOT_H);
+  assert.equal(positions['grand-a1'].y, positions['root-a'].y + 2 * GRAPH_SLOT_H, 'grandchildren two rows below');
+  // The two children are centered under the root's x.
+  const midX = (positions['child-a1'].x + positions['child-a2'].x) / 2;
+  assert.equal(midX, positions['root-a'].x, 'children block centered under parent');
+});
+
+test('G5 layered tree is deterministic', () => {
+  const nodes = [
+    { nodeId: 'd1' },
+    { nodeId: 'd2', parentNodeId: 'd1' },
+    { nodeId: 'd3', parentNodeId: 'd1' },
+  ];
+  const first = layeredTreePositions(nodes, {});
+  const second = layeredTreePositions(nodes, {});
+  assert.deepEqual(first, second);
+});