pi-weave 0.1.8 → 0.1.9

package/src/web/shared/layout.ts

@@ -15,38 +15,64 @@
  * type graph into `tsconfig.web.json` — the identical failure `wire.ts` hit.
  * Fixed here pre-emptively rather than left as a tripwire for P3.
  *
- * ## Why d3-force (§7.2)
+ * ## The recipe — d3's own force-directed tree, not ours
  *
- * The retired simulation collapsed to a vertical line because repulsion and
- * collision derive their direction as `dx / d`: once two nodes share an `x`,
- * the x-component of the push is exactly zero forever, gravity pins x to W/2,
- * and damping freezes it there. d3-force injects `jiggle()` on exactly that
- * zero (`manyBody.js`, `collide.js`, `link.js`), drawn from a **seeded** LCG —
- * so we get symmetry breaking *and* reproducibility, which is what makes §8 a
- * stable CI gate rather than a flaky one.
+ * This module used to carry ~250 lines of derived geometry: a ring-radius
+ * formula per hub fan-out, hash-angled seed rings, a disc-packed root ring,
+ * and seed-anchored gravity. All of it existed to shape a force simulation
+ * into a readable tree. d3's own force-directed-tree example does that in five
+ * lines:
+ *
+ * ```js
+ * const root = d3.hierarchy(data);
+ * const links = root.links();
+ * const nodes = root.descendants();
+ *
+ * const simulation = d3.forceSimulation(nodes)
+ *     .force("link", d3.forceLink(links).id(d => d.id).distance(0).strength(1))
+ *     .force("charge", d3.forceManyBody().strength(-50))
+ *     .force("x", d3.forceX())
+ *     .force("y", d3.forceY());
+ * ```
+ *
+ * The containment tree wants children at their parent with full strength, and
+ * the picture emerges from gentle repulsion and collision. The property that
+ * matters: a tree's radius is set by its **depth**, not by any single node's
+ * fan-out — a 188-child directory shares the angular space with its siblings
+ * instead of defining a ring that the whole graph has to fit inside. That is
+ * why the retired ring-radius family (`ringRadius`, `RING_CAP`,
+ * `seedPositions`, `clusterGap`, `rootRingRadius`, `arcShare`, `rootAngles`
+ * and the seed-anchored gravity) is deleted rather than tuned: it was a wheel
+ * d3 already ships.
  *
- * ## The four failure mechanisms, and what answers each
+ * Two deviations from the example, both stated rather than hidden:
  *
- * | Mechanism                     | Answer here                                 |
- * | ----------------------------- | ------------------------------------------- |
- * | zero-direction repulsion      | d3's `jiggle`, in all three forces           |
- * | children seeded at the parent | {@link seedPositions} — hash-derived ring    |
- * | gravity pinning x to W/2      | `forceX`/`forceY` at 0.03 — positions, never pins |
- * | hub leaves crushed to a line  | ring-sized `contains` distance (below)       |
+ * 1. **`forceCollide`** — the example draws 3.5-pixel dots with no labels; we
+ *    draw 9-unit nodes with zoomed labels, so nodes keep a collision radius
+ *    (`NODE_RADIUS + label room`) and siblings never overlap.
+ * 2. **Relation edges** (`links-to` / `mentions`) are not part of the tree.
+ *    They ride along at a longer distance and a fraction of the strength, so
+ *    they decorate the structure instead of distorting it.
  *
- * ## Ring sizing — the one non-obvious formula
+ * `forceX()`/`forceY()` (d3 defaults: target 0, no accessor) replace the
+ * seed-anchored gravity — they pull every component toward the origin, which
+ * is the no-component-escapes-to-infinity guarantee the anchors existed for,
+ * and they mean a released drag needs no anchor bookkeeping at all.
  *
- * A parent with `k` containment children wants those children on a ring. For
- * them to sit `RING_SPACING` apart without the collision force fighting the
- * link force, the ring's circumference must be at least `RING_SPACING * k`, so
- * its radius must be at least `RING_SPACING * k / 2π`. That is
- * {@link ringRadius}, and it is why a 60-child hub gets a ~380 unit link
- * distance while a 3-child node gets the 70 unit floor. Hairballs are a
- * *geometry* problem, not a tuning problem.
+ * ## Why d3-force (§7.2)
+ *
+ * The retired simulation collapsed to a vertical line because repulsion and
+ * collision derive their direction as `dx / d`: once two nodes share an `x`,
+ * the x-component of the push is exactly zero forever, and damping freezes it
+ * there. d3-force injects `jiggle()` on exactly that zero (`manyBody.js`,
+ * `collide.js`, `link.js`), drawn from a **seeded** LCG — so we get symmetry
+ * breaking *and* reproducibility, which is what makes §8 a stable CI gate
+ * rather than a flaky one. d3 also fills nodes without positions on a
+ * deterministic phyllotaxis spiral, so cold starts need no invented seeding.
  */
 
 import { forceCollide, forceLink, forceManyBody, forceSimulation, forceX, forceY } from "d3-force";
-import type { SimulationLinkDatum, SimulationNodeDatum } from "d3-force";
+import type { Simulation, SimulationLinkDatum, SimulationNodeDatum } from "d3-force";
 import type { WireEdgeKind as EdgeKind, WireGraphEdge as GraphEdge, WireGraphModel as GraphModel } from "./graph";
 import type { Point } from "./metrics";
 
@@ -57,17 +83,21 @@ export interface LayoutOptions {
   ticks?: number;
   /** Seeds d3's jiggle LCG. Default 1. */
   seed?: number;
-  /** Viewport width; the layout is centred on it. Default 1280. */
-  width?: number;
-  /** Viewport height; the layout is centred on it. Default 800. */
-  height?: number;
   /**
    * Warm-start positions by node id. The client passes current positions when
    * re-running after a drag or an expand so the graph does not jump; the
    * dynamics gate passes coincident points to prove symmetry breaking. Ids
-   * absent here fall back to {@link seedPositions}.
+   * absent here start on d3's own deterministic phyllotaxis spiral.
    */
   initial?: ReadonlyMap<string, Point>;
+  /**
+   * Hold the warm-started nodes in place while the simulation integrates the
+   * newcomers (d3's `fx`/`fy`). The collapse/expand pattern: an expand must
+   * hand its new children to the layout without shoving everything else out
+   * of the way — the existing arrangement is the user's, and the collide
+   * force packs the newcomers around it. Ignored without `initial`.
+   */
+  pinWarm?: boolean;
 }
 
 /** Visual node radius in layout units. The renderer must not draw larger than this. */
@@ -76,94 +106,40 @@ export const NODE_RADIUS = 9;
 /** Collision radius: the node plus breathing room for the leading edge of its label. */
 export const COLLIDE_RADIUS = NODE_RADIUS + 9;
 
-/** Target arc between two siblings on a parent's ring — a collision diameter plus margin. */
-const RING_SPACING = 2 * COLLIDE_RADIUS + 4;
-
-/** Shortest a `contains` edge ever gets, for parents with one or two children. */
-export const CONTAINS_DISTANCE = 70;
-
-/** `links-to` / `mentions` are associative, not structural: longer and weaker. */
+/** `links-to` / `mentions` are associative, not structural: longer and weak. */
 const RELATION_DISTANCE = 220;
 
-/** Relation edges pull at this fraction of a containment edge's strength. */
-const RELATION_STRENGTH_SCALE = 0.35;
-
-/**
- * Clearance between the outer rings of two adjacent top-level clusters.
- *
- * Derived from Gestalt proximity, not chosen: a boundary only reads as a
- * boundary if it is emptier than anything *inside* a cluster. The largest
- * empty span within any cluster is the annulus between a hub and its own ring,
- * i.e. `max ringRadius(k)` over the roots — so the inter-cluster gap must be
- * at least that. This is why the gap scales with the graph (a 60-child hub
- * pushes its neighbours further away than a 3-child node does) instead of
- * being a pixel constant that would be wrong at either extreme.
- */
-function clusterGap(roots: readonly string[], children: ReadonlyMap<string, string[]>): number {
-  let widest = CONTAINS_DISTANCE;
-  for (const id of roots) {
-    const r = ringRadius(children.get(id)?.length ?? 0);
-    if (r > widest) widest = r;
-  }
-  return widest;
-}
+/** Relation edges pull at a fraction of the containment link's strength — decoration, not structure. */
+const RELATION_STRENGTH = 0.05;
 
-/** Body repulsion. Negative is repulsive; scaled up from d3's -30 for our node sizes. */
-const CHARGE_STRENGTH = -180;
+/** Body repulsion — the force-directed-tree example's own value. */
+const CHARGE_STRENGTH = -50;
 
 /**
- * Gravity is **seed-anchored**, not centre-anchored, and that is a deliberate
- * correction of the third failure mechanism rather than a style preference.
- *
- * `forceX(W/2)` accelerates a node by `(W/2 - x)·s·α`, which grows *linearly*
- * with distance, while repulsion falls off as `1/d`. Past a few hundred units
- * centre-gravity therefore wins by orders of magnitude and drags every cluster
- * back onto the middle — measured here as a five-root separation collapsing
- * from 562 to 269 units between seeding and settling. "Gravity pins x to W/2"
- * is the post-mortem's own wording; a weak constant does not fix it, because
- * the problem is the *shape* of the term, not its coefficient.
+ * The containment tree's spring: rest length and stiffness.
  *
- * Anchoring each node to its own seeded slot keeps the restoring force bounded
- * by how far that node has actually moved, which is small. It still guarantees
- * no component escapes to infinity — the property centre-gravity was there for
- * — and it additionally makes re-runs stable, which the client needs on drag
- * and expand/collapse (§7.3).
- */
-const ANCHOR_ROOT = 0.10;
-
-/**
- * Non-roots are anchored an order of magnitude more weakly than roots: their
- * placement is the simulation's job, and at 0.02 this is 50× weaker than the
- * strength-1 link holding a leaf to its parent, so it bounds drift without
- * competing with the structure.
+ * The example's `distance(0).strength(1)` is rigid — correct for 3.5-pixel
+ * dots with no collide, and violent here: with a collision radius and a
+ * 189-child hub, dragging the hub yanked every child at full strength and the
+ * whole tree thrashed (measured: >9000 units of other-node motion per tick on
+ * this repository's real graph). Springs with real rest length and low
+ * stiffness keep every drag a local ripple while collide still packs the
+ * cluster; the shape stays a tree because every node is *in* the tree, not
+ * because the links are rigid.
  */
-const ANCHOR_CHILD = 0.02;
-
-/** Fraction of velocity retained per tick. Below d3's 0.6 default: we want settling, not motion. */
-const VELOCITY_DECAY = 0.4;
+const CONTAINS_REST = 90;
+const CONTAINS_STRENGTH = 0.02;
 
 const DEFAULT_TICKS = 300;
 const DEFAULT_SEED = 1;
-const DEFAULT_WIDTH = 1280;
-const DEFAULT_HEIGHT = 800;
 
 /** d3-force's own alpha floor (`simulation.js`); mirrored so `alphaDecay` can be derived from `ticks`. */
 const ALPHA_MIN = 0.001;
 
-const TAU = Math.PI * 2;
-
-/**
- * Rotation applied to the root ring. Without it the accumulator starts at
- * angle 0 and a two-root graph lands at 90° and 270° — a vertical pair in a
- * landscape viewport. A quarter turn back puts the first boundary on the
- * horizontal, so few-root graphs spread along the wide axis.
- */
-const ROOT_RING_PHASE = -Math.PI / 2;
-
 interface SimNode extends SimulationNodeDatum {
   id: string;
-  x: number;
-  y: number;
+  x?: number;
+  y?: number;
 }
 
 interface SimLink extends SimulationLinkDatum<SimNode> {
@@ -173,40 +149,10 @@ interface SimLink extends SimulationLinkDatum<SimNode> {
 }
 
 /** Containment edges define the hierarchy; everything else is an association. */
-function isContainment(kind: EdgeKind): boolean {
+export function isContainment(kind: EdgeKind): boolean {
   return kind === "contains" || kind === "anchored-at";
 }
 
-/**
- * FNV-1a (32-bit) followed by MurmurHash3's `fmix32` avalanche.
- *
- * The finalizer is not optional here, and its absence was a real bug caught by
- * the ring assertion. FNV-1a mixes its *low* bits well but its high bits
- * poorly for short, near-identical inputs — and `hashUnit` divides by 2³², so
- * the high bits become the most significant part of the angle. Raw FNV-1a over
- * `leaf001…leaf199` put 199 siblings into six of twelve compass sectors, three
- * of them holding over a third of the ring each. `fmix32` costs four lines and
- * makes every bit depend on every input bit.
- */
-export function hashId(id: string): number {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < id.length; i++) {
-    h ^= id.charCodeAt(i);
-    h = Math.imul(h, 0x01000193);
-  }
-  h ^= h >>> 16;
-  h = Math.imul(h, 0x85ebca6b);
-  h ^= h >>> 13;
-  h = Math.imul(h, 0xc2b2ae35);
-  h ^= h >>> 16;
-  return h >>> 0;
-}
-
-/** `hashId` folded into [0, 1). `salt` gives an independent stream per id. */
-function hashUnit(id: string, salt: number): number {
-  return hashId(`${salt}\u0000${id}`) / 0x100000000;
-}
-
 /**
  * d3-force's LCG (`lcg.js`: a = 1664525, c = 1013904223, m = 2³²), re-exposed
  * so `seed` actually selects a stream — d3 always builds its own with s = 1,
@@ -217,31 +163,18 @@ export function lcg(seed: number): () => number {
   return () => (s = (1664525 * s + 1013904223) % 4294967296) / 4294967296;
 }
 
-/** Radius that fits `k` siblings `RING_SPACING` apart — see the module header. */
-export function ringRadius(k: number): number {
-  return Math.max(CONTAINS_DISTANCE, (RING_SPACING * k) / TAU);
-}
-
 interface Structure {
   /** Ids in `model.nodes` order, deduped. */
   ids: string[];
-  /** Containment parent of each child (first winning edge, in edge order). */
-  parent: Map<string, string>;
-  /** Containment children, in edge order. */
-  children: Map<string, string[]>;
-  /** Nodes with no containment parent — the cluster anchors. */
-  roots: string[];
   /** Edges with both endpoints present, no self-loops, deduped. */
   edges: GraphEdge[];
-  /** Degree over that filtered edge set, both directions. */
-  degree: Map<string, number>;
 }
 
 /**
  * Normalise the model into something a simulation can consume: drop self-edges
  * and edges pointing at ids that are not nodes (d3's `forceLink` throws on
- * those), dedupe, and derive the containment forest. Malformed input is the
- * caller's bug, but it must not be the layout's crash.
+ * those), and dedupe. Malformed input is the caller's bug, but it must not be
+ * the layout's crash.
  */
 function analyse(model: GraphModel): Structure {
   const ids: string[] = [];
@@ -254,9 +187,6 @@ function analyse(model: GraphModel): Structure {
 
   const edges: GraphEdge[] = [];
   const seen = new Set<string>();
-  const parent = new Map<string, string>();
-  const children = new Map<string, string[]>();
-  const degree = new Map<string, number>();
   for (const e of model.edges) {
     if (e.source === e.target) continue;
     if (!known.has(e.source) || !known.has(e.target)) continue;
@@ -264,139 +194,8 @@ function analyse(model: GraphModel): Structure {
     if (seen.has(key)) continue;
     seen.add(key);
     edges.push(e);
-    degree.set(e.source, (degree.get(e.source) ?? 0) + 1);
-    degree.set(e.target, (degree.get(e.target) ?? 0) + 1);
-    if (!isContainment(e.kind) || parent.has(e.target)) continue;
-    parent.set(e.target, e.source);
-    const kids = children.get(e.source);
-    if (kids) kids.push(e.target);
-    else children.set(e.source, [e.target]);
-  }
-
-  // A containment cycle leaves every member parented, so no id in it is a root
-  // and none is reachable from one. `seedPositions` sweeps up the survivors.
-  const roots = ids.filter((id) => !parent.has(id));
-  return { ids, parent, children, roots, edges, degree };
-}
-
-/**
- * Arc budget for one cluster: its own diameter plus the inter-cluster gap.
- * Proportional allocation matters here — a 60-child hub and a 3-child node
- * must not receive the same slice of the circle.
- */
-function arcShare(id: string, children: ReadonlyMap<string, string[]>, gap: number): number {
-  return 2 * ringRadius(children.get(id)?.length ?? 0) + gap;
-}
-
-/**
- * Radius of the ring the top-level cluster anchors sit on. Disc-packing on a
- * circle, derived — not tuned.
- *
- * Anchors get arc *proportional to their share* (see {@link seedPositions}),
- * so adjacent anchors i and i+1 are `2π·(sᵢ + sᵢ₊₁) / (2·Σs)` apart and the
- * chord between them is `2R·sin` of half that. Requiring the chord to clear
- * both clusters — exactly `(sᵢ + sᵢ₊₁) / 2`, since each share is a diameter
- * plus the gap — gives R for that pair:
- *
- *   2R·sin(π·s / (2·Σs)) ≥ s / 2   ⇒   R ≥ s / (4·sin(π·s / (2·Σs)))   , s = sᵢ + sᵢ₊₁
- *
- * Take the max over adjacent pairs, wrapping. The sine's argument is at most
- * π/2 (attained only at n = 2, where s = Σs), so it never folds back.
- */
-function rootRingRadius(shares: readonly number[], total: number): number {
-  let radius = 0;
-  shares.forEach((share, i) => {
-    const pair = share + (shares[(i + 1) % shares.length] as number);
-    const need = pair / (4 * Math.sin((Math.PI * pair) / (2 * total)));
-    if (need > radius) radius = need;
-  });
-  return radius;
-}
-
-/**
- * Angles for the root ring: each anchor at the centre of its own arc slice,
- * offset by {@link ROOT_RING_PHASE}, and nudged by a hash so two equal-sized
- * clusters never land on an identical angle after rounding.
- */
-function rootAngles(roots: readonly string[], shares: readonly number[], total: number): number[] {
-  let acc = 0;
-  return shares.map((share, i) => {
-    const angle = ROOT_RING_PHASE + TAU * ((acc + share / 2) / total) + (hashUnit(roots[i] as string, 3) - 0.5) * 0.05;
-    acc += share;
-    return angle;
-  });
-}
-
-/**
- * Deterministic initial placement (§7.3).
- *
- * Roots are spread around a ring whose arc is allocated in proportion to each
- * cluster's own footprint, so the 60-child hub is not handed the same slice as
- * a 3-child node. Children go on a ring around their parent at ~70 % of the
- * radius the link force will settle them at — near equilibrium, so 300 ticks
- * is plenty — at an angle taken from a **hash of the child's own id**. Never
- * the parent's exact point: exact co-location was one of the four mechanisms
- * behind the retired viewer's vertical line, and a hash is the cheapest way to
- * guarantee two siblings never start on top of each other.
- */
-export function seedPositions(model: GraphModel, width = DEFAULT_WIDTH, height = DEFAULT_HEIGHT): Map<string, Point> {
-  const { ids, children, roots } = analyse(model);
-  const out = new Map<string, Point>();
-  const cx = width / 2;
-  const cy = height / 2;
-
-  if (roots.length === 1) {
-    out.set(roots[0] as string, { x: cx, y: cy });
-  } else if (roots.length > 1) {
-    const gap = clusterGap(roots, children);
-    const shares = roots.map((id) => arcShare(id, children, gap));
-    let total = 0;
-    for (const s of shares) total += s;
-    const ring = rootRingRadius(shares, total);
-    const angles = rootAngles(roots, shares, total);
-    roots.forEach((id, i) => {
-      const angle = angles[i] as number;
-      out.set(id, { x: cx + ring * Math.cos(angle), y: cy + ring * Math.sin(angle) });
-    });
   }
-
-  // Breadth-first, so a parent always has a point before its children read it.
-  const queue = [...roots];
-  for (let head = 0; head < queue.length; head++) {
-    const id = queue[head]!;
-    const kids = children.get(id);
-    if (kids === undefined) continue;
-    const origin = out.get(id)!;
-    const r = 0.7 * ringRadius(kids.length);
-    for (const kid of kids) {
-      const angle = TAU * hashUnit(kid, 1);
-      // 0.85–1.15 of the ring: two ids that collide in angle still differ here.
-      const jitter = 0.85 + 0.3 * hashUnit(kid, 2);
-      out.set(kid, { x: origin.x + r * jitter * Math.cos(angle), y: origin.y + r * jitter * Math.sin(angle) });
-      queue.push(kid);
-    }
-  }
-
-  // Anything a containment cycle kept out of the BFS still needs a point.
-  for (const id of ids) {
-    if (out.has(id)) continue;
-    const angle = TAU * hashUnit(id, 4);
-    const r = CONTAINS_DISTANCE * (1 + hashUnit(id, 5));
-    out.set(id, { x: cx + r * Math.cos(angle), y: cy + r * Math.sin(angle) });
-  }
-  return out;
-}
-
-/**
- * `forceLink` resolves string endpoints into node objects inside its own
- * `initialize`, which runs before the first tick — so by the time the
- * `distance` and `strength` accessors are called, both endpoints are already
- * `SimNode`s. The declared `string | SimNode` union describes only the
- * *pre-initialize* state, so narrowing it at call time would add a branch that
- * can never be taken.
- */
-function endpointId(endpoint: string | SimNode): string {
-  return (endpoint as SimNode).id;
+  return { ids, edges };
 }
 
 /**
@@ -405,93 +204,111 @@ function endpointId(endpoint: string | SimNode): string {
  *
  * The simulation is stepped **synchronously** — `stop()` then a manual `tick()`
  * loop — so it never touches `requestAnimationFrame` and works headless.
+ * Warm ids keep their positions; ids without one start on d3's deterministic
+ * phyllotaxis spiral, which is why a cold start needs no invented seeding.
  */
 export function computeLayout(model: GraphModel, options: LayoutOptions = {}): Map<string, Point> {
   const ticks = Math.max(0, Math.trunc(options.ticks ?? DEFAULT_TICKS));
   const seed = options.seed ?? DEFAULT_SEED;
-  const width = options.width ?? DEFAULT_WIDTH;
-  const height = options.height ?? DEFAULT_HEIGHT;
 
-  const { ids, children, edges, degree, roots } = analyse(model);
+  const { ids, edges } = analyse(model);
   const out = new Map<string, Point>();
   if (ids.length === 0) return out;
 
-  const seeds = seedPositions(model, width, height);
   const warm = options.initial;
   const nodes: SimNode[] = ids.map((id) => {
-    const fallback = seeds.get(id)!;
-    return { id, ...finiteOr(warm?.get(id), fallback), vx: 0, vy: 0 };
+    const at = warm?.get(id);
+    const node: SimNode = { id, vx: 0, vy: 0 };
+    if (at !== undefined && Number.isFinite(at.x) && Number.isFinite(at.y)) {
+      node.x = at.x;
+      node.y = at.y;
+      if (options.pinWarm === true) {
+        node.fx = at.x;
+        node.fy = at.y;
+      }
+    }
+    return node;
   });
 
   if (nodes.length > 1) {
-    runSimulation(nodes, edges, children, degree, seeds, new Set(roots), { ticks, seed });
+    runSimulation(nodes, edges, { ticks, seed, warm: warm !== undefined });
   }
+  // A pinned run leaves the pins behind; clear them so the returned map is
+  // positions, not a promise to keep standing there forever.
+  if (options.pinWarm === true) for (const n of nodes) { n.fx = null; n.fy = null; }
 
   for (const n of nodes) {
     // Guarded on the way out as well as in: the contract is that no caller
-    // ever receives a NaN, and a seeded fallback is always available.
-    out.set(n.id, finiteOr(n, seeds.get(n.id) as Point));
+    // ever receives a NaN. d3 fills every node during `initialize`, so the
+    // fallback is unreachable in practice — but the contract is the contract.
+    out.set(n.id, { x: Number.isFinite(n.x as number) ? (n.x as number) : 0, y: Number.isFinite(n.y as number) ? (n.y as number) : 0 });
   }
   return out;
 }
 
-/**
- * `candidate` when both its coordinates are finite, else `fallback`. Applied to
- * warm-start input and to simulation output, so a poisoned position can neither
- * enter the simulation nor leave it.
- */
-function finiteOr(candidate: Point | undefined, fallback: Point): Point {
-  if (candidate === undefined) return fallback;
-  return {
-    x: Number.isFinite(candidate.x) ? candidate.x : fallback.x,
-    y: Number.isFinite(candidate.y) ? candidate.y : fallback.y,
-  };
+export interface ForceSimulationOptions<N> {
+  nodes: N[];
+  /** String endpoints are resolved by node id; dangling ids must be filtered out by the caller. */
+  links: Array<{ source: string | N; target: string | N; kind: EdgeKind }>;
+  /**
+   * Per-node `forceX`/`forceY` targets, re-read every tick. Absent (or an id
+   * missing from the map) targets the origin — d3's own default — which is the
+   * no-component-escapes guarantee. A live driver mutates the map on drag
+   * release so a dropped node rests where the user put it.
+   */
+  anchors?: ReadonlyMap<string, Point>;
+  /** Seeds d3's jiggle LCG. Default 1 — deterministic in Node and browser. */
+  seed?: number;
 }
 
-/** Configure and step the d3 simulation in place. Mutates `nodes`. */
-function runSimulation(
-  nodes: SimNode[],
-  edges: readonly GraphEdge[],
-  children: ReadonlyMap<string, string[]>,
-  degree: ReadonlyMap<string, number>,
-  seeds: ReadonlyMap<string, Point>,
-  roots: ReadonlySet<string>,
-  opts: { ticks: number; seed: number },
-): void {
-  const links: SimLink[] = edges.map((e) => ({ source: e.source, target: e.target, kind: e.kind }));
-
-  const childCount = (id: string): number => children.get(id)?.length ?? 0;
-  /** Ring geometry is set by whichever endpoint is the fan-out parent. */
-  const fanOut = (l: SimLink): number => Math.max(childCount(endpointId(l.source)), childCount(endpointId(l.target)));
-  // Every link endpoint is a node with at least this link incident on it, so
-  // `degree` always has it and the floor of 1 is arithmetic, not a fallback.
-  const deg = (endpoint: string | SimNode): number => degree.get(endpointId(endpoint)) as number;
-  const anchor = (n: SimNode): number => (roots.has(n.id) ? ANCHOR_ROOT : ANCHOR_CHILD);
-
-  const link = forceLink<SimNode, SimLink>(links)
+/**
+ * The force configuration, as ONE definition shared by the static layout
+ * ({@link computeLayout}) and the live driver (`dynamics.ts`).
+ *
+ * It is d3's force-directed-tree recipe: the containment tree holds children
+ * at their parent with full strength, and the arrangement emerges from gentle
+ * repulsion and collision; `forceX()`/`forceY()` pull every component toward
+ * the origin at d3's default strength, so nothing drifts to infinity.
+ *
+ * The forces live here once so the static and live equilibria cannot diverge:
+ * whatever the static layout settles to is exactly what the live sim holds.
+ * The simulation is returned stopped; the driver owns the alpha policy — the
+ * static path decays to the alpha floor over its tick budget, the live path
+ * re-heats on interaction and sleeps when the floor is reached. Velocity
+ * decay stays at d3's own default, exactly like the example.
+ */
+export function createForceSimulation<
+  N extends SimulationNodeDatum & { id: string },
+>(opts: ForceSimulationOptions<N>): Simulation<N, undefined> {
+  const link = forceLink<N, { source: string | N; target: string | N; kind: EdgeKind }>(opts.links)
     .id((n) => n.id)
-    .distance((l) => (isContainment(l.kind) ? ringRadius(fanOut(l)) : RELATION_DISTANCE))
-    // d3's default `1 / min(degree)` is what stops a degree-60 hub being
-    // yanked 60 times a tick. Keep that shape; scale relations down from it.
-    .strength((l) => {
-      const base = 1 / Math.min(deg(l.source), deg(l.target));
-      return isContainment(l.kind) ? base : base * RELATION_STRENGTH_SCALE;
-    })
+    .distance((l) => (isContainment(l.kind) ? CONTAINS_REST : RELATION_DISTANCE))
+    .strength((l) => (isContainment(l.kind) ? CONTAINS_STRENGTH : RELATION_STRENGTH))
     .iterations(2);
 
-  const sim = forceSimulation<SimNode>(nodes)
-    .randomSource(lcg(opts.seed))
-    .force("charge", forceManyBody<SimNode>().strength(CHARGE_STRENGTH))
+  return forceSimulation<N>(opts.nodes)
+    .randomSource(lcg(opts.seed ?? DEFAULT_SEED))
+    .force("charge", forceManyBody<N>().strength(CHARGE_STRENGTH))
     .force("link", link)
-    .force("collide", forceCollide<SimNode>(COLLIDE_RADIUS).strength(1).iterations(3))
-    .force("x", forceX<SimNode>((n) => seeds.get(n.id)!.x).strength(anchor))
-    .force("y", forceY<SimNode>((n) => seeds.get(n.id)!.y).strength(anchor))
-    .alpha(1)
+    .force("collide", forceCollide<N>(COLLIDE_RADIUS).strength(1).iterations(3))
+    .force("x", forceX<N>((n) => opts.anchors?.get(n.id)?.x ?? 0))
+    .force("y", forceY<N>((n) => opts.anchors?.get(n.id)?.y ?? 0))
+    .stop();
+}
+
+/** Configure and step the d3 simulation in place. Mutates `nodes`. */
+function runSimulation(nodes: SimNode[], edges: readonly GraphEdge[], opts: { ticks: number; seed: number; warm: boolean }): void {
+  const links: SimLink[] = edges.map((e) => ({ source: e.source, target: e.target, kind: e.kind }));
+  const sim = createForceSimulation({ nodes, links, seed: opts.seed });
+  sim
+    // A cold start assembles from d3's phyllotaxis at full alpha; a warm start
+    // relaxes what is already on screen — d3's own re-heat value — so the
+    // graph does not re-arrange itself under the user on every expand.
+    .alpha(opts.warm ? 0.3 : 1)
     .alphaMin(ALPHA_MIN)
     // Reach the same convergence at whatever tick budget the caller asked for.
-    .alphaDecay(opts.ticks > 0 ? 1 - Math.pow(ALPHA_MIN, 1 / opts.ticks) : 0)
-    .velocityDecay(VELOCITY_DECAY);
+    // Velocity decay stays at d3's own default — the example sets neither.
+    .alphaDecay(opts.ticks > 0 ? 1 - Math.pow(ALPHA_MIN, 1 / opts.ticks) : 0);
 
-  sim.stop();
   for (let i = 0; i < opts.ticks; i++) sim.tick();
-}
+}

package/src/web/shared/logo.ts

@@ -0,0 +1,11 @@
+/**
+ * logo.ts — the pi-weave brand mark as an inline data URI.
+ *
+ * The web viewer is a single committed bundle behind a strict CSP
+ * (img-src 'self' data:), so the brand mark is an inlined 48×48 PNG —
+ * the transparent-background spider derived from docs/pi-weave-logo.png —
+ * rather than a new static route. Same pattern as the TUI's branding.ts.
+ */
+export const LOGO_MARK_MIME = "image/png";
+/** 48×48 transparent PNG, base64 — crisp at 2× for the 18px header mark. */
+export const LOGO_MARK_B64 = "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";