@nodius/layouting 0.1.3 → 0.1.4

package/README.md

@@ -36,8 +36,11 @@ connected by typed edges, with parent/child grouping and side-attached values.
 - [API](#api)
 - [Types](#types)
 - [Algorithm internals](#algorithm-internals)
+  - [The phases in depth](#the-phases-in-depth)
+  - [Which knob affects which phase](#which-knob-affects-which-phase)
 - [Debugging](#debugging)
 - [Playground](#playground)
+  - [⚙ Optimizations panel](#-optimizations-panel)
 - [Development](#development)
 
 ---
@@ -542,12 +545,27 @@ Mechanism:
 
 1. The engine lays out the graph **once** with the input handles to discover
    where every node actually ends up.
-2. For each node with at least one connected handle, it groups handles by id,
-   sums per-handle votes for each side (weighted by `1 / distance` so close
-   neighbors win), and picks the strongest side per handle.
-3. If at least one handle would change side, it bundles all the moves into
-   one `RelocateHandlesProposal` for that node — with a `changes` map you can
-   inspect to see exactly what would move.
+2. For each node with at least one connected handle, each handle is assigned a
+   side using a **flow-aware** rule rather than raw center-to-center direction:
+   - A neighbor in a **different rank band** (a layout predecessor / successor)
+     gets a handle on the **flow axis** — top/bottom in TB, left/right in LR —
+     *even when it is offset sideways*. This is what keeps a hub's children on
+     the bottom edge instead of fanning chaotically onto its flanks.
+   - A neighbor that **overlaps the same rank band** (a true sidecar / sibling)
+     gets a handle on the **perpendicular axis** (the flank facing it).
+   - **Lopsided correction:** when a node's flow neighbors all sit on one side
+     of its order-center (a one-directional fan), the nearest one stays on the
+     flow edge and farther outliers move to the flank — they would otherwise
+     crowd and cross. A *balanced* fan (children on both sides) stays entirely
+     on the flow edge.
+   Handles serving several edges still vote per side, weighted by `1 / distance`
+   so the closest neighbor wins.
+3. When two or more handles end up on the **same side**, their offsets are
+   permuted to match the order of their neighbors along that edge — so the
+   edges leaving a shared side never cross each other.
+4. If any handle would change side or offset, it bundles all the moves into one
+   `RelocateHandlesProposal` for that node — with a `changes` map you can
+   inspect to see exactly which sides would move.
 
 #### Example: a multi-handle hub
 
@@ -1064,9 +1082,12 @@ The engine is a modified **Sugiyama algorithm** with these phases (in order):
    - **Rotate pass**: scan input nodes; emit `RotateProposal` when the whole
      node faces the wrong axis for the chosen direction.
    - **Relocate pass**: run a preview layout, then emit
-     `RelocateHandlesProposal` per node with each handle's optimal side
-     (computed from the preview's actual neighbor positions). The
-     application accepts/rejects each proposal via `onProposal`.
+     `RelocateHandlesProposal` per node with each handle's optimal side. Side
+     selection is **flow-aware** (flow-axis for cross-rank neighbors,
+     perpendicular for same-rank sidecars, with a lopsided-fan correction) and
+     handles sharing a side are **offset-ordered** to match their neighbors so
+     edges don't cross. The application accepts/rejects each proposal via
+     `onProposal`.
 2. **Compound resolution** — group nodes by `parentId`; recursively lay out
    each compound's children bottom-up so the compound's bounding box is
    known before it appears at the parent level.
@@ -1088,6 +1109,112 @@ The engine is a modified **Sugiyama algorithm** with these phases (in order):
 10. **Component packing** — disjoint components packed along the order axis;
     compound groups travel as a single block.
 
+### The phases in depth
+
+Each phase is a small, independently testable module under `src/algorithms/`.
+Understanding what each one does explains *why* the optimization knobs in the
+playground behave the way they do.
+
+#### Cycle breaking (`cycle-breaking.ts`)
+
+A layered layout requires a DAG, but real graphs have feedback loops (retry
+edges, `Check → Process` in the `Cycle Example`). A DFS visits nodes ordered by
+out-degree minus in-degree (sources first), and any edge pointing back at a
+*gray* (in-progress) node is a **back edge** — it gets reversed so the graph
+becomes acyclic. The reversal is remembered (`reversed: true`) so edge routing
+can draw the arrow in its original direction. Cost: `O(V + E)`, negligible.
+
+#### Layer assignment (`layer-assignment.ts`)
+
+Two passes. **Pass A** runs a longest-path on *control* edges only, between
+non-value nodes — this fixes the execution "rail" (`Start` at layer 0, each
+successor one layer deeper). **Pass B** pulls every value onto the **median**
+layer of its non-value neighbors, so a `CONFIG` constant snaps next to the node
+that consumes it instead of extending the rail. Then long control edges get
+**dummy nodes** inserted (one per layer crossed) so the next phases only ever
+reason about adjacent layers. Dummies dominate the internal node count — a
+100-node graph can become ~665 internal nodes, which is why the heavy phases
+scale with *dummies*, not your input size.
+
+#### Crossing minimization (`crossing-minimization.ts`) — the hot phase
+
+This is the **barycenter heuristic**: repeatedly sweep down then up the layers,
+and within each layer reorder nodes by the average position of their neighbors
+in the adjacent layer. After each sweep, a **transpose** pass greedily swaps
+adjacent pairs whenever the swap reduces crossings. Crossings are counted with
+**merge-sort inversion counting** — `O(E log V)` instead of the naive `O(E²)`.
+The loop stops early when it reaches zero crossings or stops improving.
+
+This phase is **40–67 % of total time**, which is exactly why the playground
+exposes:
+
+- `crossingMinimizationIterations` — how many sweeps (more = fewer crossings,
+  diminishing returns);
+- `skipTranspose` — drop the transpose pass entirely (the single biggest cost).
+
+The engine already auto-scales iterations down and disables transpose for very
+large graphs; the knobs let you push further.
+
+#### Coordinate assignment (`coordinate-assignment.ts`) — the other hot phase
+
+Two sub-steps. First, each layer is placed along the **rank axis** (Y for TB,
+X for LR) at a cumulative offset. Then the **order axis** position is optimized
+iteratively: each node is pulled toward the **median** of its connected
+neighbors' centers, then a forward + backward pass enforces minimum spacing so
+nodes never overlap. `coordinateOptimizationIterations` controls how many
+align/repair sweeps run — more iterations = straighter edges, ~20–50 % of total
+time.
+
+#### Sidecar value placement (`value-placement.ts`)
+
+Values were excluded from the rail; here they're re-attached. Each value's
+*dominant consumer* (the non-value neighbor it shares the most edges with) is
+found, values are split onto the consumer's two flanks based on which side the
+connecting handle sits, then stacked outward by handle offset. Cheap: `< 1 %`.
+
+#### Edge routing (`edge-routing.ts`)
+
+Dummy chains are collapsed back into single logical edges, then each edge is
+drawn as an **orthogonal path**: exit the source handle along its facing
+direction, fold through the dummy waypoints at midpoints, enter the target
+handle. Collinear points are cleaned up. `edgeMargin` controls how far the path
+travels straight out of a handle before turning.
+
+#### Component packing (`component-packing.ts`)
+
+A union-find groups nodes into connected components (compound children stay with
+their parent), each component's bounding box is computed, and the boxes are laid
+side-by-side along the order axis largest-first — turning a long ribbon into a
+roughly square canvas. Toggle it off with `packComponents: false` (or the
+playground checkbox) to see each component laid out independently at the origin.
+
+### Which knob affects which phase
+
+Everything you can change in the playground's **⚙ Optimizations** panel (and via
+`LayoutOptions`) maps directly onto one of the phases above:
+
+| Knob / option                          | Phase affected                  | Effect                                              |
+|----------------------------------------|---------------------------------|-----------------------------------------------------|
+| `quality: 'draft' \| 'balanced' \| 'high'` | crossing + coordinate           | Bulk preset: scales both iteration counts and toggles transpose. |
+| `crossingMinimizationIterations`       | crossing minimization           | More sweeps → fewer crossings, more time.           |
+| `skipTranspose`                        | crossing minimization           | Drops the transpose pass → big speedup, a few more crossings. |
+| `coordinateOptimizationIterations`     | coordinate assignment           | More sweeps → straighter edges, more time.          |
+| `nodeSpacing` / `layerSpacing`         | coordinate assignment           | Minimum gaps along order / rank axes.               |
+| `edgeMargin`                           | edge routing                    | Straight run-out length before a path turns.        |
+| `packComponents`                       | component packing               | On/off side-by-side packing of disjoint subgraphs.  |
+| `compoundPadding`                      | compound resolution             | Inner padding of compound bounding boxes.           |
+| `edgeWeights` / `kind`                 | layer assignment                | Control vs data classification (rail vs sidecar).   |
+| `onProposal`                           | proposals (pre-pass)            | Accept/reject rotate + relocate handle suggestions. |
+
+The `quality` preset is just a convenient bundle — the table below shows exactly
+what each preset sets, and any explicit option overrides it:
+
+| preset      | crossing iters | coordinate iters | transpose |
+|-------------|---------------:|-----------------:|-----------|
+| `draft`     | 6              | 2                | skipped   |
+| `balanced`  | 24             | 8                | on        |
+| `high`      | 48             | 16               | on        |
+
 ### Why the rail is laid out without values
 
 Including values in the rail's layer assignment would inflate the layer's
@@ -1190,6 +1317,38 @@ Toolbar toggles:
   `Pub/Sub Broker`, or `Wrong Handles Everywhere` to see how bad the layout
   looks without it; toggle it back on to watch every handle snap into place.
 
+### ⚙ Optimizations panel
+
+Click **⚙ Optimizations** in the toolbar to open the optimization controls.
+These let you exercise each speed/quality knob live and see the effect on both
+the rendered layout and the timing read-out:
+
+| Control                | What it does                                                                 |
+|------------------------|------------------------------------------------------------------------------|
+| **Quality**            | `draft` / `balanced` (default) / `high` preset. Re-layouts on change so you can compare the visual quality and the timing. |
+| **Skip transpose**     | Force-skips the per-layer transpose pass (the single largest cost in balanced mode) independently of the preset. |
+| **Crossing iter**      | Numeric override for crossing-minimization iterations. Empty = use the preset's value. |
+| **Coord iter**         | Numeric override for coordinate-optimization iterations. Empty = use the preset's value. |
+| **⏱ Compare presets**  | Runs `draft`, `balanced`, and `high` on the current input (rep count auto-scaled to graph size) and prints a best/mean timing table with the ratio vs `balanced`. |
+| **active-opts badge**  | A live read-out of the effective options, e.g. `quality=balanced · skipTranspose · xIter=4 · cIter=1`. |
+
+**What to try:**
+
+- Load a small example (`Simple Chain`) → all presets read ~0 ms; the layout
+  is dominated by fixed setup, so the preset barely matters.
+- Build or paste a larger graph (a few hundred nodes) and hit **⏱ Compare
+  presets** → `draft` is typically ~0.7–0.8× the balanced time, `high` ~1.2–1.5×.
+- Switch **Quality** between `draft` and `high` on a dense example and watch the
+  number of edge crossings change while the timing tracks the preset.
+
+Every numeric override wins over the preset, and **Skip transpose** stacks on
+top of any preset — so `quality=draft + skipTranspose` is the fastest possible
+configuration, while `quality=high` with explicit high iteration counts is the
+slowest / highest quality.
+
+See [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for the full benchmark tables and
+Web Worker / WASM / WebGPU notes.
+
 ---
 
 ## Development
@@ -1197,7 +1356,7 @@ Toolbar toggles:
 ```bash
 npm install
 
-npm test              # 93 tests cover compound, sidecars, rotate + relocate proposals, perf, cycles…
+npm test              # 99 tests cover compound, sidecars, rotate + relocate proposals, quality presets, perf, cycles…
 npm run test:watch
 npm run build         # tsup bundle + tsc declaration files
 
@@ -1217,6 +1376,35 @@ npm run dev           # vite on http://localhost:6501
   acceptance, partial accept, value-specific rotation suggestions.
 - `tests/diag-values.test.ts` — `printLayout` smoke test on the Floating
   Values scenario.
+- `tests/quality-presets.test.ts` — `quality` presets: `balanced` equals the
+  default, `draft`/`high` produce valid non-overlapping layouts, explicit
+  iteration counts override the preset, and `draft` is measurably faster.
+
+### Snapshot regression harness
+
+`scripts/snapshot.ts` captures a golden master of `layout()` output for the
+whole example corpus in all four directions plus random DAGs up to 500 nodes,
+in **two modes** — `plain` (no proposals) and `proposal` (auto-rotate accepted,
+`onProposal: p => p.proposed`, like the playground default) — for 182 snapshots
+total. The plain set guards that performance work keeps the **`balanced`**
+output bit-identical; the proposal set guards the rotate + relocate handle
+placement:
+
+```bash
+npx tsx scripts/snapshot.ts capture   # write baseline/ (plain + proposal)
+npx tsx scripts/snapshot.ts verify    # diff current output vs baseline/
+```
+
+Two companion scripts judge handle-placement *quality* (a non-circular metric:
+edge crossings, edges through nodes, handles facing away from their edge):
+
+```bash
+npx tsx scripts/quality-metric.ts            # per-example metric, proposal mode
+npx tsx scripts/quality-compare.ts           # none vs rotate vs relocate
+```
+
+`scripts/profile.ts` breaks down per-phase timing and
+`scripts/benchmark-presets.ts` compares the three presets across graph sizes.
 
 ## License
 

package/dist/index.js

@@ -1503,17 +1503,23 @@ function applyRelocateProposals(input, preview, options) {
   const previewIndex = new Map(preview.nodes.map((n) => [n.id, n]));
   const inputIndex = new Map(input.nodes.map((n) => [n.id, n]));
   const newNodes = input.nodes.map((node) => {
-    const proposal = computeRelocateProposal(node, input.edges, inputIndex, previewIndex);
+    const proposal = computeRelocateProposal(node, input.edges, inputIndex, previewIndex, options.direction);
     if (!proposal) return node;
     const accepted = options.onProposal(proposal);
     return accepted ?? node;
   });
   return { nodes: newNodes, edges: input.edges };
 }
-function computeRelocateProposal(node, edges, inputIndex, previewIndex) {
+function computeRelocateProposal(node, edges, inputIndex, previewIndex, direction) {
   const selfPreview = previewIndex.get(node.id);
   if (!selfPreview) return null;
   if (node.handles.length === 0) return null;
+  const isHorizontal = direction === "LR" || direction === "RL";
+  const rankMin = isHorizontal ? selfPreview.x : selfPreview.y;
+  const rankMax = isHorizontal ? selfPreview.x + selfPreview.width : selfPreview.y + selfPreview.height;
+  const orderMin = isHorizontal ? selfPreview.y : selfPreview.x;
+  const orderMax = isHorizontal ? selfPreview.y + selfPreview.height : selfPreview.x + selfPreview.width;
+  const orderCenter = (orderMin + orderMax) / 2;
   const usedHandleIds = /* @__PURE__ */ new Set();
   for (const e of edges) {
     if (e.from === node.id) usedHandleIds.add(e.fromHandle);
@@ -1521,54 +1527,125 @@ function computeRelocateProposal(node, edges, inputIndex, previewIndex) {
   }
   if (usedHandleIds.size === 0) return null;
   const votesByHandle = /* @__PURE__ */ new Map();
-  const selfCenter = {
-    x: selfPreview.x + selfPreview.width / 2,
-    y: selfPreview.y + selfPreview.height / 2
-  };
   for (const e of edges) {
     const isFrom = e.from === node.id;
     const isTo = e.to === node.id;
     if (!isFrom && !isTo) continue;
     const handleId = isFrom ? e.fromHandle : e.toHandle;
     const neighborId = isFrom ? e.to : e.from;
-    const neighborPreview = previewIndex.get(neighborId);
-    if (!neighborPreview) continue;
-    const neighborCenter = {
-      x: neighborPreview.x + neighborPreview.width / 2,
-      y: neighborPreview.y + neighborPreview.height / 2
-    };
-    const dx = neighborCenter.x - selfCenter.x;
-    const dy = neighborCenter.y - selfCenter.y;
-    const side = Math.abs(dx) >= Math.abs(dy) ? dx >= 0 ? "right" : "left" : dy >= 0 ? "bottom" : "top";
-    const dist = Math.hypot(dx, dy);
+    const np = previewIndex.get(neighborId);
+    if (!np) continue;
+    const nbrRankMin = isHorizontal ? np.x : np.y;
+    const nbrRankMax = isHorizontal ? np.x + np.width : np.y + np.height;
+    const overlap = Math.min(rankMax, nbrRankMax) - Math.max(rankMin, nbrRankMin);
+    const isFlow = overlap <= 0;
+    const nbrOrderC = isHorizontal ? np.y + np.height / 2 : np.x + np.width / 2;
+    const nbrRankC = isHorizontal ? np.x + np.width / 2 : np.y + np.height / 2;
+    const selfRankC = isHorizontal ? selfPreview.x + selfPreview.width / 2 : selfPreview.y + selfPreview.height / 2;
+    const nbrIsBefore = nbrRankMax <= rankMin || overlap <= 0 && nbrRankC < selfRankC;
+    const flowSide = isHorizontal ? nbrIsBefore ? "left" : "right" : nbrIsBefore ? "top" : "bottom";
+    const d = nbrOrderC - orderCenter;
+    const perpSide = isHorizontal ? d >= 0 ? "bottom" : "top" : d >= 0 ? "right" : "left";
+    const beyond = nbrOrderC > orderMax ? 1 : nbrOrderC < orderMin ? -1 : 0;
+    const dist = Math.hypot(nbrRankC - selfRankC, nbrOrderC - orderCenter);
     const weight = dist > 0 ? 1 / dist : 1;
     const arr = votesByHandle.get(handleId) ?? [];
-    arr.push({ side, weight });
+    arr.push({ weight, isFlow, flowSide, perpSide, orderCoord: nbrOrderC, rankCoord: nbrRankC, beyond });
     votesByHandle.set(handleId, arr);
   }
-  const changes = {};
-  const newHandles = node.handles.map((h) => {
-    const votes = votesByHandle.get(h.id);
-    if (!votes || votes.length === 0) return h;
+  const resolved = /* @__PURE__ */ new Map();
+  for (const [handleId, votes] of votesByHandle) {
+    if (votes.length === 0) continue;
     const tallies = { top: 0, right: 0, bottom: 0, left: 0 };
-    for (const v of votes) tallies[v.side] += v.weight;
-    const best = Object.entries(tallies).reduce((acc, cur) => cur[1] > acc[1] ? cur : acc, ["top", -Infinity])[0];
-    if (best !== h.position) {
-      changes[h.id] = { from: h.position, to: best };
-      return { ...h, position: best };
+    let dom = votes[0];
+    for (const v of votes) {
+      tallies[v.isFlow ? v.flowSide : v.perpSide] += v.weight;
+      if (v.weight > dom.weight) dom = v;
+    }
+    const side = Object.entries(tallies).reduce((acc, cur) => cur[1] > acc[1] ? cur : acc, ["top", -Infinity])[0];
+    resolved.set(handleId, {
+      side,
+      isFlow: dom.isFlow,
+      flowSide: dom.flowSide,
+      perpSide: dom.perpSide,
+      orderCoord: dom.orderCoord,
+      rankCoord: dom.rankCoord,
+      beyond: dom.beyond
+    });
+  }
+  for (const flowSide of ["top", "bottom", "left", "right"]) {
+    const group = [...resolved.entries()].filter(([, r]) => r.isFlow && r.side === flowSide);
+    if (group.length < 2) continue;
+    let hasLeft = false, hasRight = false;
+    for (const [, r] of group) {
+      if (r.orderCoord < orderCenter) hasLeft = true;
+      else if (r.orderCoord > orderCenter) hasRight = true;
+    }
+    if (hasLeft && hasRight) continue;
+    const distOf = (oc) => oc > orderMax ? oc - orderMax : orderMin - oc;
+    const distinctCoords = [...new Set(group.filter(([, r]) => r.beyond !== 0).map(([, r]) => r.orderCoord))].sort((a, b) => distOf(a) - distOf(b));
+    if (distinctCoords.length >= 2) {
+      const keep = distinctCoords[0];
+      for (const [, r] of group) {
+        if (r.beyond !== 0 && r.orderCoord !== keep) r.side = r.perpSide;
+      }
+    }
+  }
+  const sideChanges = {};
+  const newSideById = /* @__PURE__ */ new Map();
+  for (const h of node.handles) {
+    const r = resolved.get(h.id);
+    if (!r) continue;
+    newSideById.set(h.id, r.side);
+    if (r.side !== h.position) sideChanges[h.id] = { from: h.position, to: r.side };
+  }
+  const newOffsetById = /* @__PURE__ */ new Map();
+  const bySide = /* @__PURE__ */ new Map();
+  for (const [hid, r] of resolved) {
+    const arr = bySide.get(r.side) ?? [];
+    arr.push(hid);
+    bySide.set(r.side, arr);
+  }
+  for (const [side, handleIds] of bySide) {
+    if (handleIds.length < 2) continue;
+    const offsets = handleIds.map((hid) => node.handles.find((h) => h.id === hid).offset ?? 0.5).sort((a, b) => a - b);
+    const horizontalSide = side === "top" || side === "bottom";
+    const sortKey = (hid) => {
+      const r = resolved.get(hid);
+      if (isHorizontal) {
+        return horizontalSide ? r.rankCoord : r.orderCoord;
+      }
+      return horizontalSide ? r.orderCoord : r.rankCoord;
+    };
+    const sortedHandles = [...handleIds].sort((a, b) => {
+      const ra = sortKey(a), rb = sortKey(b);
+      return ra - rb || (a < b ? -1 : a > b ? 1 : 0);
+    });
+    for (let i = 0; i < sortedHandles.length; i++) {
+      newOffsetById.set(sortedHandles[i], offsets[i]);
+    }
+  }
+  let changed = false;
+  const newHandles = node.handles.map((h) => {
+    const side = newSideById.get(h.id) ?? h.position;
+    const offset = newOffsetById.has(h.id) ? newOffsetById.get(h.id) : h.offset ?? 0.5;
+    if (side !== h.position || offset !== (h.offset ?? 0.5)) {
+      changed = true;
+      return { ...h, position: side, offset };
     }
     return h;
   });
-  if (Object.keys(changes).length === 0) return null;
+  if (!changed) return null;
   const proposed = { ...node, handles: newHandles };
-  const summary = Object.entries(changes).map(([id, c]) => `${id}: ${c.from}\u2192${c.to}`).join(", ");
+  const sideSummary = Object.entries(sideChanges).map(([id, c]) => `${id}: ${c.from}\u2192${c.to}`).join(", ");
+  const reason = sideSummary ? `${Object.keys(sideChanges).length} handle(s) repositioned toward their neighbor (${sideSummary})` : `handles on a shared side reordered to match neighbor order`;
   return {
     type: "relocate-handles",
     nodeId: node.id,
     current: node,
     proposed,
-    changes,
-    reason: `${Object.keys(changes).length} handle(s) point away from their neighbor (${summary})`
+    changes: sideChanges,
+    reason
   };
 }
 function rotateHandles(handles, rot) {