@nodius/layouting 0.1.1 → 0.1.4

package/README.md

@@ -3,36 +3,106 @@
 A **zero-dependency**, high-performance graph layouting library for node-based
 technical diagrams.
 
-Built for real-world use cases: data pipelines, visual programming environments,
-workflow editors, and any system where typed-handle nodes are connected by
-typed edges, with parent/child grouping and side-attached values.
+Built for real-world use cases: data pipelines, visual programming
+environments, workflow editors, and any system where typed-handle nodes are
+connected by typed edges, with parent/child grouping and side-attached values.
+
+> **The killer feature.** Most layout libraries pick one axis (vertical OR
+> horizontal). `@nodius/layouting` mixes both *within the same layout*: the
+> execution rail runs along the chosen axis (e.g. top→bottom), while value
+> nodes — your constants, configs, imports — automatically attach to the
+> **perpendicular** flanks of the node that consumes them. You get a tight,
+> readable 2D layout instead of a long ribbon. See
+> [Mixed orientation](#mixed-orientation-rail--sidecars).
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Performance](#performance)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Concepts](#concepts)
+- [Mixed orientation: rail + sidecars](#mixed-orientation-rail--sidecars)
+- [Typed edges](#typed-edges-control-vs-data)
+- [Value nodes & sidecars](#value-nodes--sidecars)
+- [Compound (nested) layout](#compound-nested-layout)
+- [Component packing](#component-packing)
+- [Handle proposals (`onProposal`)](#handle-proposals-onproposal)
+  - [Rotate vs relocate](#rotate-vs-relocate)
+  - [Strategic per-handle placement (`relocate-handles`)](#strategic-per-handle-placement-relocate-handles)
+- [Cookbook — recipes for common patterns](#cookbook--recipes-for-common-patterns)
+- [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)
+
+---
 
 ## Features
 
-- **Zero runtime dependencies** — pure TypeScript, nothing else
-- **Strict-axis Sugiyama** — the chosen reading direction is honored end to end; compacity comes from packing and sidecars, never from local re-orientation
-- **Typed edges** (`control` / `data`) — `data` edges have light weight and pull their value nodes onto the consumer's layer instead of extending the rail
-- **Compound layout** — nodes can declare `parentId`; children are laid out inside their parent's bounding box recursively
-- **Sidecar value placement** — value nodes (only data edges) are attached to the flanks of their consumer, picked from the consumer's handle side
-- **Component packing** — disjoint components are packed along the order axis for a square-ish aspect ratio
-- **Rotation proposals** — when handle orientation doesn't match the chosen direction (or the value's sidecar slot), the engine asks the application via `onProposal` whether to rotate
-- **Handle-aware** — every node has multiple input/output handles with `top`/`right`/`bottom`/`left` positions and configurable offsets
-- **Orthogonal edge routing** through dummy waypoints
-- **Incremental layout** — keep position stability across edits via `IncrementalLayout`
-- **4 layout directions** — `TB`, `LR`, `BT`, `RL`
-- **Cycle support** — back edges are detected and reversed automatically
-- **Scales** — ~150 ms on 1000 nodes; merge-sort based crossing counting; adaptive iteration cap on large graphs
+- **Zero runtime dependencies** — pure TypeScript, nothing else.
+- **Strict-axis Sugiyama** — the chosen reading direction (`TB`/`LR`/`BT`/`RL`)
+  is honored end to end. Compacity comes from packing and sidecars, never from
+  silent local re-orientation.
+- **Typed edges** — `control` defines the execution rail; `data` is a weak
+  link that pulls value nodes onto the consumer's layer.
+- **Mixed-orientation layout** — main rail along one axis, value sidecars on
+  the perpendicular flanks. See dedicated section below.
+- **Compound layout** — nodes can declare `parentId`; children are laid out
+  inside their parent's bounding box, recursively, at any depth.
+- **Sidecar value placement** — value nodes (only data edges) are attached to
+  the flanks of their dominant consumer; the side is picked from the
+  consumer's handle position.
+- **Component packing** — disjoint components are packed along the order axis
+  for a square-ish aspect ratio.
+- **Handle proposals** — when handle orientation doesn't match the planned
+  placement, the engine asks the application via `onProposal` whether to fix
+  it. Two flavors are emitted:
+  - `rotate` — rotate every handle on the node by 90°/-90°/180°.
+  - `relocate-handles` — strategically move **each handle individually** to
+    the side that points toward its actual neighbor (computed from a real
+    layout preview). The app accepts, modifies, or rejects.
+- **Handle-aware** — every node has multiple input/output handles with
+  `top`/`right`/`bottom`/`left` positions and `offset` along the side.
+- **Orthogonal edge routing** through dummy waypoints.
+- **Incremental layout** — `IncrementalLayout` keeps position stability across
+  edits (existing positions are blended with the new ones).
+- **Cycle support** — back edges are detected and reversed automatically.
+- **Scales** — ~150 ms for 1 000 nodes; merge-sort based crossing counting;
+  adaptive iteration cap on large graphs.
 
 ## Performance
 
-Measured on a standard dev machine (Node 22, vitest run):
+Measured on a standard dev machine (Node 24, single-threaded JS):
 
-| Graph size                       | Time   |
-|----------------------------------|--------|
-| 100 nodes, 737 edges (dense)     | ~70 ms |
-| 200 nodes                        | ~25 ms |
-| 500 nodes                        | ~90 ms |
-| 1000 nodes                       | ~150 ms|
+| Graph size                       | balanced | draft   |
+|----------------------------------|---------:|--------:|
+| 100 nodes                        | ~9 ms    | ~4 ms   |
+| 200 nodes                        | ~17 ms   | ~13 ms  |
+| 500 nodes                        | ~36 ms   | ~24 ms  |
+| 1 000 nodes                      | ~25 ms   | ~18 ms  |
+
+Optimization knobs you can use today:
+
+- **`quality: 'draft' | 'balanced' | 'high'`** — preset. `'draft'` is ~2–3×
+  faster (skips transpose, fewer iterations); `'high'` does more iterations
+  for dense graphs. Default is `'balanced'`.
+- **`skipTranspose: true`** — skip the per-layer transpose pass
+  unconditionally (the largest single cost in balanced mode).
+- **`crossingMinimizationIterations`**, **`coordinateOptimizationIterations`**
+  — explicit overrides that win over the preset.
+- **Web Worker** — `LayoutInput` and `LayoutResult` are plain JSON, so
+  `layout()` runs cleanly off the main thread via `postMessage`.
+
+See [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for full benchmarks, worker
+patterns, and notes on plugging a WASM or WebGPU backend.
 
 ## Installation
 
@@ -40,6 +110,8 @@ Measured on a standard dev machine (Node 22, vitest run):
 npm install @nodius/layouting
 ```
 
+---
+
 ## Quick start
 
 ```ts
@@ -59,8 +131,8 @@ const result = layout({
     ]},
   ],
   edges: [
-    { id: 'e1', from: 'src', to: 'transform', fromHandle: 'out', toHandle: 'in' },
-    { id: 'e2', from: 'transform', to: 'sink', fromHandle: 'out', toHandle: 'in' },
+    { id: 'e1', from: 'src',       to: 'transform', fromHandle: 'out', toHandle: 'in' },
+    { id: 'e2', from: 'transform', to: 'sink',      fromHandle: 'out', toHandle: 'in' },
   ],
 }, { direction: 'TB' });
 
@@ -68,14 +140,73 @@ const result = layout({
 // result.edges  → routed edges with waypoint arrays and `kind`
 ```
 
-## Typed edges and value nodes
+---
+
+## Concepts
+
+A complete mental model lives in five concepts:
+
+| Concept     | What it is                                                            | Where it shows in the API           |
+|-------------|------------------------------------------------------------------------|--------------------------------------|
+| Node        | A box on the canvas with a fixed `width` × `height`.                   | `NodeInput`                          |
+| Handle      | A typed connection point on one side of a node (4 sides, with offset).| `NodeInput.handles[]`                |
+| Edge        | A connection from one node's handle to another's, with a `kind`.       | `EdgeInput`                          |
+| Rail        | The subgraph induced by `control` edges. Drives layer assignment.      | implicit — emerges from edge kinds   |
+| Value       | A node whose every incident edge is `data`. Lands as a sidecar.        | implicit — emerges from edge kinds   |
+| Compound    | A node referenced as `parentId` by other nodes — contains them.        | `NodeInput.parentId`                 |
+
+The output mirrors the input, with absolute coordinates and routed edge
+points; `parentId` is echoed back so you can rebuild the hierarchy in your
+renderer.
+
+---
+
+## Mixed orientation: rail + sidecars
+
+This is the feature that sets `@nodius/layouting` apart, and the one most
+worth understanding deeply. **The chosen direction is the rail direction.
+Values sit on the perpendicular axis** — so a `TB` layout naturally extends
+sideways for values, a `LR` layout naturally extends top/bottom.
+
+### Why it matters
+
+A pure top-to-bottom layout that treats every node identically ends up as a
+long vertical ribbon: configs above the function that uses them, constants
+strewn between two business steps, etc. The graph reads top-to-bottom but
+also "skips" all over. With mixed orientation:
+
+```
+       Start                                Start
+         |                                    |
+         v                                    v
+       fetch                  vs.    [API_KEY] fetch [TIMEOUT]
+        / \                                    |
+   API_KEY  TIMEOUT                         Parse
+        \ /                                    |
+       Parse                                 Done
+         |
+         v
+       Done
+```
+
+The rail (`Start → fetch → Parse → Done`) stays a single, tight vertical
+line. The values (`API_KEY`, `TIMEOUT`) attach **horizontally** to the
+consumer (`fetch`). The graph is now square-ish and easy to read.
+
+### How it works
+
+1. Edges declare a `kind`: `'control'` or `'data'`. Defaults to `'control'`.
+2. Layer assignment runs on the **control rail only**. Values don't extend
+   the rail.
+3. After the rail is fully placed, **value sidecars** are attached to the
+   flanks of their dominant consumer. The side (left vs. right in TB, top vs.
+   bottom in LR) is chosen from the *consumer's handle position*:
+   - consumer handle on `left` → value sits on the left flank
+   - consumer handle on `right` → value sits on the right flank
+4. If multiple values share one consumer, they stack outward, ordered by
+   each value's connecting handle offset.
 
-Edges accept a `kind` of `'control'` (default) or `'data'`. **Control edges**
-define the execution rail and drive layer assignment. **Data edges** are weak
-links — their endpoints are pulled onto the consumer's layer, and a node whose
-every incident edge is a data edge becomes a **value**: it is attached as a
-sidecar to the flank of its dominant consumer rather than living inside the
-rail.
+### Self-contained worked example
 
 ```ts
 import { layout } from '@nodius/layouting';
@@ -87,104 +218,653 @@ const result = layout({
     ]},
     { id: 'fetch', width: 140, height: 70, handles: [
       { id: 'in',  type: 'input',  position: 'top' },
+      // Two value-input handles on the LEFT flank …
       { id: 'key', type: 'input',  position: 'left', offset: 0.3 },
       { id: 'url', type: 'input',  position: 'left', offset: 0.7 },
+      // … and one on the RIGHT flank.
+      { id: 'tm',  type: 'input',  position: 'right' },
       { id: 'out', type: 'output', position: 'bottom' },
     ]},
-    { id: 'API_KEY', width: 100, height: 40, handles: [
+    { id: 'API_KEY',  width: 90, height: 40, handles: [
       { id: 'out', type: 'output', position: 'right' },
     ]},
-    { id: 'BASE_URL', width: 100, height: 40, handles: [
+    { id: 'BASE_URL', width: 90, height: 40, handles: [
       { id: 'out', type: 'output', position: 'right' },
     ]},
+    { id: 'TIMEOUT',  width: 90, height: 40, handles: [
+      { id: 'out', type: 'output', position: 'left' },
+    ]},
     { id: 'Done', width: 100, height: 50, handles: [
       { id: 'in', type: 'input', position: 'top' },
     ]},
   ],
   edges: [
-    { id: 'c1', from: 'Start', to: 'fetch', fromHandle: 'out', toHandle: 'in', kind: 'control' },
-    { id: 'c2', from: 'fetch', to: 'Done',  fromHandle: 'out', toHandle: 'in', kind: 'control' },
+    { id: 'c1', from: 'Start',    to: 'fetch', fromHandle: 'out', toHandle: 'in',  kind: 'control' },
+    { id: 'c2', from: 'fetch',    to: 'Done',  fromHandle: 'out', toHandle: 'in',  kind: 'control' },
     { id: 'd1', from: 'API_KEY',  to: 'fetch', fromHandle: 'out', toHandle: 'key', kind: 'data' },
     { id: 'd2', from: 'BASE_URL', to: 'fetch', fromHandle: 'out', toHandle: 'url', kind: 'data' },
+    { id: 'd3', from: 'TIMEOUT',  to: 'fetch', fromHandle: 'out', toHandle: 'tm',  kind: 'data' },
   ],
+}, { direction: 'TB' });
+```
+
+After layout:
+
+- `Start.center.x ≈ fetch.center.x ≈ Done.center.x` — the rail is one line.
+- `API_KEY.center.y ≈ BASE_URL.center.y ≈ TIMEOUT.center.y ≈ fetch.center.y` —
+  values sit at fetch's vertical band.
+- `API_KEY` and `BASE_URL` end up on the **left** flank (their consumer
+  handles are on `left`); `TIMEOUT` ends up on the **right** flank.
+
+### What if my values have "wrong" handles?
+
+Use `onProposal: p => p.proposed` to let the engine auto-fix them. See
+[Rotation proposals](#rotation-proposals-onproposal) below.
+
+---
+
+## Typed edges: control vs data
+
+```ts
+type EdgeKind = 'control' | 'data';
+```
+
+| Kind      | Weight  | Effect on layout                                                                                  |
+|-----------|---------|----------------------------------------------------------------------------------------------------|
+| `control` | 1       | Drives layer assignment. Dummy nodes are inserted for multi-layer spans. Crossings counted.        |
+| `data`    | 0.25    | Light link. Pulls value nodes onto their consumer's layer. No dummies — routed directly.           |
+
+Default is `'control'`. You can override defaults globally:
+
+```ts
+layout(input, {
+  edgeWeights: { control: 1, data: 0.1 }, // make data even lighter
 });
-// Start, fetch and Done line up vertically. API_KEY and BASE_URL sit on
-// fetch's left flank, at fetch's vertical band — they don't extend the rail.
 ```
 
+Or per-edge:
+
+```ts
+{ id: 'd1', from: 'A', to: 'B', fromHandle: 'o', toHandle: 'i',
+  kind: 'data', weight: 0.5 } // explicit override
+```
+
+**Use `control` for**: execution flow, sequencing, "happens before" relationships, error branches.
+
+**Use `data` for**: configuration, constants, environment imports,
+secondary inputs that don't define order — anything you'd put as a `prop`
+rather than a `step`.
+
+---
+
+## Value nodes & sidecars
+
+A node is automatically classified as a **value** when **every** edge touching
+it is of kind `'data'`. Once classified:
+
+1. It is excluded from the control rail layer assignment.
+2. Its target layer becomes the **median layer of its non-value neighbors**
+   (typically the layer of its consumer).
+3. After the rail is laid out, the value is **attached as a sidecar** to its
+   dominant consumer:
+   - in `TB`/`BT`: on the consumer's left or right flank
+   - in `LR`/`RL`: above or below the consumer
+4. The side is chosen from the consumer's handle position. Multiple values
+   targeting the same consumer stack outward.
+
+### Sidecar side picking — by example
+
+```
+Consumer with the data-input handle on the LEFT (TB direction):
+
+    consumer.handles = [
+      { id: 'in',  type: 'input',  position: 'top' },
+      { id: 'cfg', type: 'input',  position: 'left' },  ← value handle
+    ]
+    edge value → consumer via 'cfg'
+
+  Result:  [ value ]——[ consumer ]
+                          |
+                          v
+```
+
+```
+Three values on the LEFT, one on the RIGHT:
+
+    Layout output (TB direction):
+
+      [ V3 ][ V1 ][  consumer  ][ V4 ]
+            [ V2 ]——┘
+```
+
+Values on the same side are sorted by their handle offset on the consumer, so
+stacking order is predictable and matches the visual order of the consumer's
+handles.
+
+### Multiple consumers per value
+
+If a value points to multiple non-value nodes, the engine picks the one with
+the most edges to that value (or alphabetical id as tie-breaker). The value
+becomes a sidecar of that one. Other edges are routed normally.
+
+### Isolated values (no consumer)
+
+Rare — they go in a corner. If you see one, it usually means an edge points to
+something that was filtered out.
+
+---
+
 ## Compound (nested) layout
 
-Set `parentId` on any node to make it a child of another. Children are laid out
-inside their parent's bounding box; the parent grows to fit them plus an
-optional padding and a header strip for its own label.
+Set `parentId` on any node to make it a child of another. The parent grows to
+fit its children plus padding and a header strip for its own label.
 
 ```ts
 const result = layout({
   nodes: [
     { id: 'Start',       width: 110, height: 50, handles: [...] },
+    // The compound — its width/height in the input are MINIMUMS;
+    // the engine inflates them to fit children.
     { id: 'parallel',    width: 220, height: 140, handles: [
       { id: 'in',  type: 'input',  position: 'top' },
       { id: 'out', type: 'output', position: 'bottom' },
     ]},
     { id: 'fetch users',  parentId: 'parallel', width: 130, height: 50, handles: [...] },
     { id: 'fetch orders', parentId: 'parallel', width: 130, height: 50, handles: [...] },
-    { id: 'End',         width: 100, height: 50, handles: [...] },
+    { id: 'End',          width: 100, height: 50, handles: [...] },
   ],
   edges: [
-    { id: 'c1', from: 'Start', to: 'parallel', fromHandle: 'out', toHandle: 'in', kind: 'control' },
-    { id: 'c2', from: 'parallel', to: 'End',   fromHandle: 'out', toHandle: 'in', kind: 'control' },
+    { id: 'c1', from: 'Start',    to: 'parallel', fromHandle: 'out', toHandle: 'in', kind: 'control' },
+    { id: 'c2', from: 'parallel', to: 'End',      fromHandle: 'out', toHandle: 'in', kind: 'control' },
   ],
 });
+```
+
+After layout:
 
-// Output nodes carry `parentId` so you can reconstruct the hierarchy in your renderer.
+- `fetch users` and `fetch orders` are placed **inside** `parallel`'s
+  bounding box, side by side.
+- `parallel` is positioned in the rail just like any other node — its size is
+  big enough to contain its children.
+- `End` sits below the entire `parallel` block.
+- Each output node has `parentId` echoed (`'parallel'` for the children).
+
+### Nesting
+
+Compounds can be nested arbitrarily — children of a compound can themselves
+be compounds with their own children. The engine processes them deepest-first
+so the size at each level reflects the full subtree below it.
+
+### Edges across the compound boundary
+
+- Edges between the compound itself and its siblings (e.g. `Start → parallel`)
+  are routed at the root level.
+- Edges between children of the same compound (e.g. `transform → enrich`
+  inside a `map` compound) are routed inside the compound.
+- Edges that "escape" a compound (a child connecting to something outside)
+  are not yet a first-class feature — model them with explicit handles on the
+  compound itself.
+
+### Tuning the padding
+
+```ts
+layout(input, { compoundPadding: 24 }); // default 24
 ```
 
-## Rotation proposals (`onProposal`)
+The header strip (28 px) is reserved at the top of every compound for its own
+label. The padding wraps the children on all four sides.
 
-When a node's handles don't match how the engine plans to place it, it emits a
-**rotation proposal**. The application decides what to do:
+---
+
+## Component packing
+
+Disjoint components are packed side-by-side along the order axis (perpendicular
+to the flow direction). This keeps the aspect ratio square-ish instead of
+producing a long ribbon.
+
+```ts
+layout(input, { packComponents: true });   // default
+layout(input, { packComponents: false });  // each component starts from 0
+```
+
+Packing respects compound groups — a compound and all of its children always
+move as one block. Components are sorted largest-first along the rank axis so
+the dominant flow leads the layout.
+
+---
+
+## Handle proposals (`onProposal`)
+
+When a node's handles don't match how the engine plans to place it, the engine
+**emits a proposal** to the application. The application decides what to do
+with it.
+
+### The signature
+
+```ts
+type ProposalCallback = (
+  proposal: LayoutProposal,
+) => NodeInput | null | undefined | void;
+
+type LayoutProposal = RotateProposal | RelocateHandlesProposal;
+
+interface RotateProposal {
+  type: 'rotate';
+  nodeId: string;
+  current: NodeInput;          // the original node
+  proposed: NodeInput;         // every handle rotated by `rotation`
+  rotation: 90 | -90 | 180;    // degrees clockwise
+  reason: string;
+}
+
+interface RelocateHandlesProposal {
+  type: 'relocate-handles';
+  nodeId: string;
+  current: NodeInput;          // the original node
+  proposed: NodeInput;         // each affected handle moved to its optimal side
+  changes: Record<string, { from: HandleSide; to: HandleSide }>;
+  reason: string;              // e.g. "out_a: top→bottom, out_b: top→right"
+}
+```
+
+Return value (same for both types):
+
+| Returned             | Meaning                                                |
+|----------------------|--------------------------------------------------------|
+| `proposal.proposed`  | Accept as-is.                                          |
+| Modified `NodeInput` | Accept with tweaks (keep some handles untouched).      |
+| `null` / nothing     | Reject — use the original node.                        |
+
+### Rotate vs relocate
+
+Both fix mis-placed handles, but at different granularities:
+
+| Proposal           | Granularity | Driven by              | Best for                                  |
+|--------------------|-------------|------------------------|-------------------------------------------|
+| `rotate`           | Whole node  | Direction only         | Symmetric nodes, simple graphs            |
+| `relocate-handles` | Per handle  | Real neighbor geometry | Multi-output nodes, mixed orientations    |
+
+The engine runs **both passes**, in this order:
+
+1. **Rotate pass** — direction-only check (no preview needed). Emits a single
+   rotation if every handle is wrong for the chosen direction.
+2. **Relocate pass** — runs a *preview layout* with current handles to see
+   where every neighbor actually ends up, then proposes, per handle, the side
+   that points to its neighbor's center.
+
+The relocate pass is a strict superset of rotate: it can move two handles in
+opposite directions, leave correctly-placed ones alone, or split a single
+node's outputs across all four sides. It costs **one extra layout pass** but
+only when `onProposal` is provided.
+
+### When does the rotate pass emit a proposal?
+
+#### Rail nodes (any node with at least one control edge)
+
+Expected handle layout for the chosen direction:
+
+| Direction | Inputs on | Outputs on |
+|-----------|-----------|------------|
+| `TB`      | top       | bottom     |
+| `BT`      | bottom    | top        |
+| `LR`      | left      | right      |
+| `RL`      | right     | left       |
+
+If a node has handles facing the wrong axis (e.g. `top`/`bottom` handles in a
+`LR` graph), the engine proposes the rotation that maximizes alignment.
+
+#### Value nodes (every incident edge is data)
+
+Values land **opposite** the consumer's handle. Expected output:
+
+| Direction | Consumer handle on | Value output expected |
+|-----------|--------------------|------------------------|
+| `TB`/`BT` | `left`             | `right`                |
+| `TB`/`BT` | `right`            | `left`                 |
+| `LR`/`RL` | `top`              | `bottom`               |
+| `LR`/`RL` | `bottom`           | `top`                  |
+
+This is what makes the "I defined my value with a `bottom` handle by reflex,
+but it sits horizontally — please fix it" case work transparently.
+
+### Strategic per-handle placement (`relocate-handles`)
+
+This pass is **the killer feature** for graphs where a single node has
+neighbors in multiple directions. Examples that motivate it:
+
+- A central **hub** with control edges flowing top↔bottom AND value sidecars
+  on the flanks. A simple rotation cannot satisfy both axes.
+- A **broker / pub-sub** node where publishers feed it from one side and
+  subscribers from the other.
+- A **bidirectional mesh** of services where each pair has a request/reply
+  exchange across multiple handles.
+- A pipeline whose handles were **defined randomly** and need each handle
+  fixed individually.
+
+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, 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
 
 ```ts
 import { layout } from '@nodius/layouting';
 
+const input = {
+  nodes: [
+    { id: 'Trigger', width: 110, height: 50, handles: [
+      { id: 'go', type: 'output', position: 'bottom', offset: 0.5 },
+    ]},
+    // Hub: every handle defined on 'bottom' on purpose.
+    { id: 'Hub', width: 220, height: 100, handles: [
+      { id: 'in',     type: 'input',  position: 'bottom', offset: 0.5 },
+      { id: 'out',    type: 'output', position: 'bottom', offset: 0.5 },
+      { id: 'lg',     type: 'output', position: 'bottom', offset: 0.2 },
+      { id: 'rg',     type: 'output', position: 'bottom', offset: 0.4 },
+      { id: 'ldata',  type: 'input',  position: 'bottom', offset: 0.6 },
+      { id: 'rdata',  type: 'input',  position: 'bottom', offset: 0.8 },
+    ]},
+    { id: 'Continue', width: 110, height: 50, handles: [
+      { id: 'in', type: 'input', position: 'top', offset: 0.5 },
+    ]},
+    { id: 'LogA', width: 90, height: 40, handles: [{ id: 'in', type: 'input', position: 'right', offset: 0.5 }]},
+    { id: 'LogB', width: 90, height: 40, handles: [{ id: 'in', type: 'input', position: 'left',  offset: 0.5 }]},
+    { id: 'CONF_A', width: 90, height: 40, handles: [{ id: 'out', type: 'output', position: 'right', offset: 0.5 }]},
+    { id: 'CONF_B', width: 90, height: 40, handles: [{ id: 'out', type: 'output', position: 'left',  offset: 0.5 }]},
+  ],
+  edges: [
+    { id: 'c0', from: 'Trigger', to: 'Hub', fromHandle: 'go', toHandle: 'in', kind: 'control' },
+    { id: 'c1', from: 'Hub', to: 'Continue', fromHandle: 'out', toHandle: 'in', kind: 'control' },
+    { id: 'l1', from: 'Hub', to: 'LogA', fromHandle: 'lg', toHandle: 'in', kind: 'data' },
+    { id: 'l2', from: 'Hub', to: 'LogB', fromHandle: 'rg', toHandle: 'in', kind: 'data' },
+    { id: 'd1', from: 'CONF_A', to: 'Hub', fromHandle: 'out', toHandle: 'ldata', kind: 'data' },
+    { id: 'd2', from: 'CONF_B', to: 'Hub', fromHandle: 'out', toHandle: 'rdata', kind: 'data' },
+  ],
+};
+
+const result = layout(input, {
+  direction: 'TB',
+  onProposal: (p) => p.proposed, // accept everything
+});
+```
+
+After auto-fix, the Hub's six handles each land on the correct side:
+
+| Handle    | Neighbor        | Original | Relocated |
+|-----------|-----------------|----------|-----------|
+| `in`      | Trigger (above) | `bottom` | `top`     |
+| `out`     | Continue (below)| `bottom` | `bottom`  |
+| `lg`      | LogA (left)     | `bottom` | `left`    |
+| `rg`      | LogB (right)    | `bottom` | `right`   |
+| `ldata`   | CONF_A (left)   | `bottom` | `left`    |
+| `rdata`   | CONF_B (right)  | `bottom` | `right`   |
+
+A single `rotate` proposal could not have produced this — the six handles
+need to spread across four different sides, which is exactly what
+`relocate-handles` does.
+
+### Three patterns of use
+
+**1. Accept everything (the easy mode):**
+
+```ts
 layout(input, {
   direction: 'LR',
-  // Accept every proposal and use the engine-suggested rotation:
   onProposal: (p) => p.proposed,
+});
+```
 
-  // Or filter: only accept rotations for nodes you own
-  // onProposal: (p) => p.nodeId.startsWith('mine_') ? p.proposed : null,
+**2. Observe without applying — useful for logging/debugging:**
 
-  // Or partial: rotate only some handles
-  // onProposal: (p) => ({
-  //   ...p.current,
-  //   handles: p.current.handles.map(h => h.id === 'main' ? { ...h, position: 'right' } : h),
-  // }),
+```ts
+const log: LayoutProposal[] = [];
+layout(input, {
+  onProposal: (p) => { log.push(p); return null; },
 });
+
+for (const p of log) {
+  if (p.type === 'rotate') {
+    console.log(`[rotate]  ${p.nodeId} by ${p.rotation}°`);
+  } else {
+    const moves = Object.entries(p.changes)
+      .map(([h, c]) => `${h}: ${c.from}→${c.to}`).join(', ');
+    console.log(`[relocate] ${p.nodeId} — ${moves}`);
+  }
+}
 ```
 
-The engine reasons about two roles:
+**3. Partial accept — pick which moves to apply:**
 
-- **Rail nodes** are aligned to the global flow: in `TB`, inputs go on top,
-  outputs on bottom.
-- **Value nodes** are sidecars: their handles must face the consumer. A value
-  attached to a consumer's `left` handle will sit on the consumer's left
-  flank, so its output is expected on `right`.
+```ts
+layout(input, {
+  direction: 'TB',
+  onProposal: (p) => {
+    if (p.type !== 'relocate-handles') return null;
+    // Apply only changes whose target is on the left.
+    return {
+      ...p.current,
+      handles: p.current.handles.map(h => {
+        const change = p.changes[h.id];
+        if (change && change.to === 'left') {
+          return { ...h, position: 'left' };
+        }
+        return h;
+      }),
+    };
+  },
+});
+```
 
-Each proposal includes the original node, the rotated proposal, the rotation
-angle (`90` / `-90` / `180`), and a human-readable reason.
+### Helper: `rotateHandles`
 
-## Component packing
+If you build your own rotation logic, import the same utility the engine uses:
 
-By default disjoint components are packed side-by-side along the order axis.
-Disable with `packComponents: false`. Packing respects compound groups — a
-compound and its children always travel as one block.
+```ts
+import { rotateHandles } from '@nodius/layouting';
+
+const rotated = rotateHandles(node.handles, 90);
+// rotation in {90, -90, 180}, clockwise. Offsets are preserved.
+```
+
+---
+
+## Cookbook — recipes for common patterns
+
+### Linear pipeline with constants
 
 ```ts
-layout(input, { packComponents: true });  // default
-layout(input, { packComponents: false }); // long ribbon
+import { layout } from '@nodius/layouting';
+
+layout({
+  nodes: [
+    { id: 'load',  width: 120, height: 50, handles: [
+      { id: 'in',  type: 'input',  position: 'top' },
+      { id: 'cfg', type: 'input',  position: 'left' },
+      { id: 'out', type: 'output', position: 'bottom' },
+    ]},
+    { id: 'CONFIG', width: 100, height: 40, handles: [
+      { id: 'out', type: 'output', position: 'right' },
+    ]},
+    { id: 'save',  width: 120, height: 50, handles: [
+      { id: 'in', type: 'input', position: 'top' },
+    ]},
+  ],
+  edges: [
+    { id: 'c',  from: 'load',   to: 'save', fromHandle: 'out', toHandle: 'in',  kind: 'control' },
+    { id: 'd',  from: 'CONFIG', to: 'load', fromHandle: 'out', toHandle: 'cfg', kind: 'data' },
+  ],
+}, { direction: 'TB' });
 ```
 
+Result: `load → save` vertically, `CONFIG` to the left of `load`.
+
+### Parallel branches (Promise.all)
+
+```ts
+layout({
+  nodes: [
+    { id: 'Start',    width: 100, height: 50, handles: [
+      { id: 'out', type: 'output', position: 'bottom' },
+    ]},
+    { id: 'parallel', width: 240, height: 130, handles: [
+      { id: 'in',  type: 'input',  position: 'top' },
+      { id: 'out', type: 'output', position: 'bottom' },
+    ]},
+    { id: 'a', parentId: 'parallel', width: 100, height: 50, handles: [
+      { id: 'in',  type: 'input',  position: 'top' },
+      { id: 'out', type: 'output', position: 'bottom' },
+    ]},
+    { id: 'b', parentId: 'parallel', width: 100, height: 50, handles: [
+      { id: 'in',  type: 'input',  position: 'top' },
+      { id: 'out', type: 'output', position: 'bottom' },
+    ]},
+    { id: 'Done', width: 100, height: 50, handles: [
+      { id: 'in', type: 'input', position: 'top' },
+    ]},
+  ],
+  edges: [
+    { id: 'c1', from: 'Start',    to: 'parallel', fromHandle: 'out', toHandle: 'in', kind: 'control' },
+    { id: 'c2', from: 'parallel', to: 'Done',     fromHandle: 'out', toHandle: 'in', kind: 'control' },
+  ],
+});
+```
+
+`a` and `b` are placed side by side inside `parallel`'s box. The rail is
+`Start → parallel → Done`.
+
+### Try / Catch
+
+Model the happy path inside one compound and the error path inside another.
+A single `try` node with two outputs (`ok` and `err`) branches to either path.
+
+```ts
+layout({
+  nodes: [
+    { id: 'try', width: 200, height: 120, handles: [
+      { id: 'in',  type: 'input',  position: 'top' },
+      { id: 'ok',  type: 'output', position: 'bottom', offset: 0.3 },
+      { id: 'err', type: 'output', position: 'right' },
+    ]},
+    // … 'try' children (parentId: 'try') …
+    { id: 'catch', width: 180, height: 100, handles: [
+      { id: 'in',  type: 'input',  position: 'top' },
+      { id: 'out', type: 'output', position: 'bottom' },
+    ]},
+    // … 'catch' children (parentId: 'catch') …
+  ],
+  edges: [
+    { id: 'ok_path',  from: 'try', to: 'End',   fromHandle: 'ok',  toHandle: 'in', kind: 'control' },
+    { id: 'err_path', from: 'try', to: 'catch', fromHandle: 'err', toHandle: 'in', kind: 'control' },
+    // …
+  ],
+});
+```
+
+See the `Try / Catch (compound)` example in the playground for a complete
+version.
+
+### Switch / Case
+
+A single dispatcher with one output per branch. Each branch can be a single
+node or a compound.
+
+```ts
+const dispatcher = {
+  id: 'method?', width: 100, height: 50, handles: [
+    { id: 'in',  type: 'input',  position: 'top' },
+    { id: 'GET',  type: 'output', position: 'bottom', offset: 0.2 },
+    { id: 'POST', type: 'output', position: 'bottom', offset: 0.4 },
+    { id: 'PUT',  type: 'output', position: 'bottom', offset: 0.6 },
+    { id: 'DEL',  type: 'output', position: 'bottom', offset: 0.8 },
+  ],
+};
+```
+
+See the `Switch / Case` example in the playground.
+
+### Map / Reduce pipeline with seeded reducer
+
+Combine a compound (`map`) with a sidecar value (`SEED`) on the reducer.
+
+See the `Map / Reduce pipeline` example in the playground.
+
+### HTTP middleware chain with config values
+
+Every middleware in a vertical rail, each one with a `data`-edge constant on
+the left, plus a side-effect (`audit`) on the right.
+
+See the `HTTP middleware chain` example in the playground.
+
+### Disjoint components
+
+Just emit them and let `packComponents` (default on) place them side by side.
+
+```ts
+layout({
+  nodes: [...nodesA, ...nodesB, ...nodesC],
+  edges: [...edgesA, ...edgesB, ...edgesC], // each (A,B,C) self-contained
+});
+```
+
+The three components sit side by side, largest first.
+
+### Cycles
+
+Cycles are detected during the cycle-breaking phase; the back edges are
+reversed for layout purposes only. The output edge keeps its original `from`
+and `to`; only the routing reflects the reversal.
+
+```ts
+layout({
+  nodes: [...],
+  edges: [
+    { id: 'a', from: 'A', to: 'B', ... },
+    { id: 'b', from: 'B', to: 'A', ... }, // ← back edge, reversed internally
+  ],
+});
+```
+
+### Migrating from a "flat" graph
+
+If you already have a working layout with all edges as control, you can adopt
+typed edges incrementally:
+
+```ts
+const result = layout({
+  nodes,
+  edges: edges.map(e => ({
+    ...e,
+    kind: e.isConfig ? 'data' : 'control', // your own classifier
+  })),
+});
+```
+
+The output stays compatible; values just relocate to sidecars.
+
+---
+
 ## API
 
 ### `layout(input, options?)`
@@ -196,6 +876,8 @@ routed edges.
 function layout(input: LayoutInput, options?: LayoutOptions): LayoutResult;
 ```
 
+Use this for one-shot layouts: full recompute every time.
+
 ### `IncrementalLayout`
 
 Maintains state for incremental updates with position stability:
@@ -204,36 +886,57 @@ Maintains state for incremental updates with position stability:
 import { IncrementalLayout } from '@nodius/layouting';
 
 const inc = new IncrementalLayout({ direction: 'LR' });
+
+// Initial layout
 const r1 = inc.setGraph({ nodes: [...], edges: [...] });
+
+// Add things; existing positions are blended 70/30 (new/old).
 const r2 = inc.addNodes([newNode], [newEdge]);
-const r3 = inc.removeNodes(['stale_id']);
-inc.addEdges([...]);
-inc.removeEdges(['e1']);
-inc.getResult();
+const r3 = inc.removeNodes(['stale_id']); // connected edges removed too
+inc.addEdges([{ id: 'e', from: 'A', to: 'B', fromHandle: 'o', toHandle: 'i' }]);
+inc.removeEdges(['e']);
+
+inc.getResult(); // current cached LayoutResult | null
 ```
 
+Position stability formula (per node, per axis):
+`new_position = 0.7 * fresh_compute + 0.3 * previous_position`.
+
 ### `printLayout(result, options?)`
 
-Render a layout result to a debug-friendly text block: per-Y-band summary,
-node hierarchy, edges, overlaps and an optional ASCII grid. Useful when
-iterating on layout strategies without opening a browser.
+Debug helper that renders a `LayoutResult` to a text block: per-Y-band
+summary, hierarchy, edges, overlaps, and an optional ASCII grid.
 
 ```ts
 import { layout, printLayout } from '@nodius/layouting';
+
 const r = layout(input);
 console.log(printLayout(r));
+// Or skip the ASCII grid:
+console.log(printLayout(r, { grid: false }));
 ```
 
+Useful when iterating on the algorithm without opening a browser, or when
+writing failing tests where you want to inspect coordinates.
+
 ### `rotateHandles(handles, rotation)`
 
 Utility re-exported for applications that build their own handle-rotation
-logic in their `onProposal` callback.
+logic in `onProposal`. Rotates each handle's `position` clockwise; `offset`
+is preserved. `rotation` is `90 | -90 | 180`.
 
 ```ts
 import { rotateHandles } from '@nodius/layouting';
 const rotated = rotateHandles(node.handles, 90);
 ```
 
+### `countAllCrossings(graph, layers)`
+
+Internal helper exposed for testing — counts the number of edge crossings
+across all adjacent layers. Mostly useful in your own regression tests.
+
+---
+
 ## Types
 
 ### Input
@@ -244,7 +947,7 @@ interface NodeInput {
   width: number;
   height: number;
   handles: HandleInput[];
-  parentId?: string; // make this node a child of another
+  parentId?: string; // make this node a child of another (compound layout)
 }
 
 interface HandleInput {
@@ -261,7 +964,7 @@ interface EdgeInput {
   fromHandle: string;
   toHandle: string;
   kind?: 'control' | 'data'; // default: 'control'
-  weight?: number;           // override (default: 1 control, 0.25 data)
+  weight?: number;           // default: 1 (control), 0.25 (data)
 }
 
 interface LayoutInput {
@@ -274,24 +977,30 @@ interface LayoutInput {
 
 ```ts
 interface LayoutOptions {
-  direction?: 'TB' | 'LR' | 'BT' | 'RL';   // Default: 'TB'
-  nodeSpacing?: number;                     // Default: 40
-  layerSpacing?: number;                    // Default: 60
-  crossingMinimizationIterations?: number;  // Default: 24
-  coordinateOptimizationIterations?: number;// Default: 8
-  edgeMargin?: number;                      // Default: 20
-
-  // Typed edges
+  // ─── Direction & spacing ────────────────────────────────────────────
+  direction?: 'TB' | 'LR' | 'BT' | 'RL';      // Default: 'TB'
+  nodeSpacing?: number;                        // Default: 40 (px between siblings)
+  layerSpacing?: number;                       // Default: 60 (px between layers)
+  edgeMargin?: number;                         // Default: 20 (entry/exit margin)
+
+  // ─── Iteration counts ───────────────────────────────────────────────
+  crossingMinimizationIterations?: number;     // Default: 24 (auto-reduced for >200 nodes)
+  coordinateOptimizationIterations?: number;   // Default: 8
+
+  // ─── Typed edges ────────────────────────────────────────────────────
   edgeWeights?: { control?: number; data?: number };
+    // Default: { control: 1, data: 0.25 }
+    // Individual edges can override via EdgeInput.weight.
 
-  // Component packing
-  packComponents?: boolean;                 // Default: true
+  // ─── Component packing ──────────────────────────────────────────────
+  packComponents?: boolean;                    // Default: true
 
-  // Compound layout
-  compoundPadding?: number;                 // Default: 24
+  // ─── Compound layout ────────────────────────────────────────────────
+  compoundPadding?: number;                    // Default: 24 (px around children)
 
-  // Proposals
-  onProposal?: (p: LayoutProposal) => NodeInput | null | undefined | void;
+  // ─── Proposals ──────────────────────────────────────────────────────
+  onProposal?: ProposalCallback;
+    // Called once per node when the engine wants to suggest a rotation.
 }
 ```
 
@@ -310,14 +1019,14 @@ interface NodeOutput {
   width: number;
   height: number;
   handles: HandleOutput[]; // absolute positions
-  parentId?: string;        // echoed from the input
+  parentId?: string;        // echoed from the input — keep your hierarchy
 }
 
 interface HandleOutput {
   id: string;
   type: 'input' | 'output';
   position: 'top' | 'right' | 'bottom' | 'left';
-  x: number;
+  x: number; // absolute, includes node position
   y: number;
 }
 
@@ -327,47 +1036,245 @@ interface EdgeOutput {
   to: string;
   fromHandle: string;
   toHandle: string;
-  points: Point[]; // ordered waypoints
+  points: Point[]; // ordered waypoints from source to target
   kind: 'control' | 'data';
 }
 
+interface Point { x: number; y: number; }
+```
+
+### Proposals
+
+```ts
+type LayoutProposal = RotateProposal | RelocateHandlesProposal;
+
 interface RotateProposal {
   type: 'rotate';
   nodeId: string;
-  current: NodeInput;
-  proposed: NodeInput;
-  rotation: 90 | -90 | 180;
+  current: NodeInput;            // unchanged input node
+  proposed: NodeInput;           // all handles rotated by `rotation`
+  rotation: 90 | -90 | 180;      // clockwise
   reason: string;
 }
 
-type LayoutProposal = RotateProposal;
+interface RelocateHandlesProposal {
+  type: 'relocate-handles';
+  nodeId: string;
+  current: NodeInput;            // unchanged input node
+  proposed: NodeInput;           // each affected handle moved
+  /** Per-handle changes; only handles whose side differs are present. */
+  changes: Record<string, { from: HandleSide; to: HandleSide }>;
+  reason: string;
+}
+
+type ProposalCallback = (
+  proposal: LayoutProposal,
+) => NodeInput | null | undefined | void;
 ```
 
-## Algorithm
+---
+
+## Algorithm internals
 
-The engine uses a modified **Sugiyama algorithm** with these phases:
+The engine is a modified **Sugiyama algorithm** with these phases (in order):
 
-1. **Proposals** — scan input nodes; emit rotation proposals when handle
-   orientation doesn't match the planned placement (rail vs. sidecar).
+1. **Proposals** — two passes when `onProposal` is set:
+   - **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. 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 in the parent level.
-3. **Cycle breaking** — DFS-based back edge detection and reversal.
+   known before it appears at the parent level.
+3. **Cycle breaking** — DFS-based back-edge detection and reversal.
 4. **Two-pass layer assignment**:
-   - control rail via longest-path on control-only edges between non-value nodes
-   - values pulled onto the median layer of their non-value neighbors
-5. **Dummy insertion** for long control edges only — data edges route directly.
+   - **control rail** via longest-path on control-only edges between non-value
+     nodes;
+   - **values** are pulled onto the median layer of their non-value neighbors.
+5. **Dummy node insertion** for long control edges only — data edges route
+   directly (typically span 0 or 1 layers).
 6. **Crossing minimization on the rail** — barycenter heuristic with up/down
-   sweeps and transpose improvement; merge-sort inversion counting.
+   sweeps and transpose improvement; merge-sort inversion counting for O(E log V).
 7. **Coordinate assignment on the rail** — median-based iterative positioning
-   with spacing constraints.
-8. **Sidecar value placement** — values are attached to the flank of their
-   dominant consumer, side chosen from the consumer's handle position.
+   with spacing constraints; values are excluded so the rail stays aligned.
+8. **Sidecar value placement** — values are attached to the flanks of their
+   dominant consumer; side chosen from the consumer's handle position.
 9. **Edge routing** — orthogonal paths through dummy waypoints with
-   handle-aware entry/exit directions; `kind` is preserved.
+   handle-aware entry/exit directions; `kind` is preserved on output.
 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
+width (every value adds a slot), which would shift the rail's center.
+Excluding values during the rail's coordinate assignment is what guarantees
+that, say, `Start → fetch → Parse → Done` stay perfectly aligned in TB even
+when fetch has five values attached to it.
+
+---
+
+## Debugging
+
+### `printLayout(result)`
+
+Best first move. Prints:
+
+- bounding box
+- nodes grouped by Y band (TB-style) — useful to verify layer separation
+- hierarchy (compounds with their children, recursively)
+- every edge: kind, source/target, point count
+- a list of overlapping nodes (should be empty in a healthy layout)
+- an ASCII sketch of the final positions
+
+```ts
+console.log(printLayout(layout(input), { gridWidth: 100 }));
+```
+
+### Inspecting proposals
+
+```ts
+layout(input, {
+  onProposal: (p) => {
+    console.log(`[proposal] ${p.nodeId}: rotate by ${p.rotation}° — ${p.reason}`);
+    return null; // observe only
+  },
+});
+```
+
+### Verifying typed-edge classification
+
+A node is considered a "value" iff every incident edge has `kind: 'data'`. If
+a node you expected to be a value is appearing in the rail, double-check:
+
+- Are any of its edges still `kind: 'control'` (or missing `kind`, which
+  defaults to control)?
+- Did you misspell `kind`? It must be a string `'data'`, not the EdgeKind type
+  imported then mis-used.
+
+### Common gotchas
+
+| Symptom                                                  | Likely cause                                                         |
+|----------------------------------------------------------|----------------------------------------------------------------------|
+| Rail is not vertical/horizontal anymore                  | Some control edges leak between unrelated components — packComponents helps |
+| Value lands in the middle of the rail                    | The value still has a control edge — re-check its edge kinds         |
+| Compound child sticks out of the parent box              | Child has handles wider than expected — check `width`/`height` math  |
+| `End` node sits to the side of the rail                  | Its only inbound edge is `data`, not `control`                       |
+| Sidecar values all stack on one side                     | The consumer's handle for those values is on a single side — split them |
+
+---
+
 ## Playground
 
 ```bash
@@ -376,32 +1283,129 @@ npm install
 npm run dev   # → http://localhost:6501
 ```
 
-The playground ships with examples covering every layout feature:
-
-- Compound · Promise.all
-- Floating Values (auto-rotate demo)
-- Compound + Values
-- Try / Catch (compound)
-- Switch / Case
-- Map / Reduce pipeline
-- HTTP middleware chain
-- Disjoint Components
-- Binary Tree
-- Cycle Example
-- ... and classics (Simple Chain, Diamond, Data Pipeline, Multi-Handle Hub)
-
-Toggle **Pack components** and **Auto-rotate handles** in the toolbar to see
-the corresponding features kick in.
+The playground ships with curated examples covering every layout feature:
+
+| Example                  | What it showcases                                  |
+|--------------------------|----------------------------------------------------|
+| Simple Chain             | Bare-bones linear rail                             |
+| Diamond                  | Branch + join                                      |
+| Data Pipeline            | Realistic multi-handle nodes                       |
+| Multi-Handle Hub         | One source fanning out to many workers            |
+| Binary Tree              | Tree with two outputs per parent                  |
+| Compound · Promise.all   | Parallel children inside a compound               |
+| **Floating Values**      | **Mixed orientation + auto-rotate demo**          |
+| Compound + Values        | A compound that takes a value as a config         |
+| Try / Catch (compound)   | Two side-by-side compounds (happy + error path)   |
+| Switch / Case            | One dispatcher, many branches converging          |
+| Map / Reduce pipeline    | Compound + seeded reducer (sidecar value)         |
+| HTTP middleware chain    | Long vertical rail with three left-side configs   |
+| Disjoint Components      | `packComponents` packing in action                |
+| **Star Hub (relocate)**  | **Single node, 6 handles, 4 different sides — per-handle placement** |
+| **Pub/Sub Broker**       | **Bidirectional broker: publishers ↔ broker ↔ subscribers** |
+| **Bidirectional Mesh**   | **3 services with request/reply edges in both directions** |
+| **Wrong Handles Everywhere** | **Linear pipeline with scrambled handles — auto-fix corrects each one** |
+| Cycle Example            | Back edge handling                                |
+
+Toolbar toggles:
+
+- **Direction** — `TB`, `LR`, `BT`, `RL`.
+- **Node / Layer spacing** — sliders.
+- **Pack components** — turns off packing of disjoint subgraphs.
+- **Auto-rotate handles** — when on, `onProposal` returns `p.proposed` so the
+  engine's suggestions are applied automatically — **both** rotate and
+  relocate proposals. Toggle it off on `Star Hub (relocate)`,
+  `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
 
 ```bash
 npm install
-npm test              # 79 tests cover compound, sidecars, 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
+
+# Playground:
+cd playground
+npm install
+npm run dev           # vite on http://localhost:6501
 ```
 
+### Tests of note
+
+- `tests/compound.test.ts` — the original "Option A améliorée" contract:
+  compound bounding box + value pull on `Test 2`.
+- `tests/value-placement.test.ts` — sidecar contract: rail alignment, sidecar
+  side picking, LR direction, no-overlap.
+- `tests/proposals.test.ts` — `onProposal` lifecycle: emission, rejection,
+  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
 
 MIT