Engine unification: d3-force replaces forceAtlas2 everywhere

One engine owns the equilibrium: the merge settle and (next commit)
the live drag both run createGraphSimulation — d3-force link springs,
1/d charge, weak centroid gravity — so a drag's rest state IS the
server's rest state. The FA2-era anchor mechanism survives as a
post-tick POSITION-SPACE re-blend (retention 0.85): d3's forceLink is
a Hooke spring (strength*(d-L)*alpha), which overpowers any force-space
anchor at long range — the re-blend is alpha-independent and always
wins as the sim anneals (the 675-unit drift bug). Gravity retuned for
d3's 1/d many-body falloff (bootstrap 0.2 / incremental 0.12: cluster
spacing lands ~400 world units, the FA2-era density). Rim orphans seed
(and anchor) at 1.7x the CONNECTED core's mean radius — a max-span-based
rim fed back on itself and ran the layout away to 6000 units. Replay:
338 positions in 1.6s, old-node shift within a batch 4.8 (FA2: 23).

package-lock.json

@@ -24,6 +24,7 @@
 				"class-variance-authority": "^0.7.1",
 				"clsx": "^2.1.1",
 				"cmdk": "^1.1.1",
+				"d3-force": "^3.0.0",
 				"d3-selection": "^3.0.0",
 				"d3-zoom": "^3.0.0",
 				"embla-carousel-react": "^8.6.0",

package.json

@@ -29,6 +29,7 @@
 		"class-variance-authority": "^0.7.1",
 		"clsx": "^2.1.1",
 		"cmdk": "^1.1.1",
+		"d3-force": "^3.0.0",
 		"d3-selection": "^3.0.0",
 		"d3-zoom": "^3.0.0",
 		"embla-carousel-react": "^8.6.0",

scripts/replay-layout.ts

@@ -49,6 +49,7 @@ function main() {
 
 	console.log(`[replay] ${nodes.length} unique nodes, ${edges.length} edge lines, ${sources.length} sources`);
 	let maxOldShift = 0;
+	let shiftReport = "";
 	for (const source of sources) {
 		const batch = nodes.filter((n) => batchOf.get(n.id) === source.id);
 		const isLast = source.id === sources[sources.length - 1]!.id;
@@ -76,7 +77,10 @@ function main() {
 		for (const [id, prev] of before) {
 			const now = positions.get(id)!;
 			const shift = Math.hypot(prev.x - now.x, prev.y - now.y);
-			if (shift > maxOldShift) maxOldShift = shift;
+			if (shift > maxOldShift) {
+				maxOldShift = shift;
+				shiftReport = `${id} ${prev.x.toFixed(0)},${prev.y.toFixed(0)} -> ${now.x.toFixed(0)},${now.y.toFixed(0)} (batch ${batch.length} new, ${activeEdges.length} edges)`;
+			}
 		}
 		const label = source.filePath.split("/").pop() ?? source.id;
 		console.log(
@@ -87,7 +91,7 @@ function main() {
 	graphStore.writePositions(Object.fromEntries(positions));
 	console.log(
 		`[replay] done: ${positions.size} positions written in ${((Date.now() - t0) / 1000).toFixed(1)}s` +
-			` (max old-node shift within a batch: ${maxOldShift.toFixed(1)})`,
+			` (max old-node shift within a batch: ${maxOldShift.toFixed(1)}: ${shiftReport})`,
 	);
 }
 

src/core/index.ts

@@ -21,6 +21,7 @@ export * from "./render-settings.ts";
 
 export * from "./question-core.ts";
 export * from "./clusters.ts";
+export * from "./layout.ts";
 export * from "./plan-tree.ts";
 export * from "./phases.ts";
 export * from "./pending.ts";

src/core/layout.ts

@@ -1,53 +1,134 @@
 /**
- * Option A — incremental anchored force layout (DECIDED 2026-09-13).
+ * The layout engine — d3-force, everywhere (DECIDED 2026-09-13).
  *
- * The layout EVOLVES instead of reshuffling: each settle warm-starts
+ * One engine owns the equilibrium: the merge-time incremental settle AND
- * forceAtlas2 from the positions ledger, ties every previously-positioned
+ * the live drag physics run the SAME force set (links as springs, charge
- * node back toward its anchor (a per-iteration re-blend), and seeds new
+ * repulsion, weak gravity), so the positions ledger and the transient
- * nodes near their positioned neighbors — so old placements stay
+ * simulation agree on what "resting" means. (FA2 was replaced after a
- * recognizable while the graph grows, exactly the way a mind map accretes
+ * research round: it has no annealing/pinning/settle model and mixing it
- * around what came before.
+ * with a different live engine visibly re-flows the graph on every drag.)
  *
- * Design constraints (kept deliberately, for future live physics):
+ * Layout EVOLVES instead of reshuffling (Option A): each settle warm-starts
- *  - PURE: no fs, no server types — the same function is the merge-time
+ * from the positions ledger and spring-ties every previously-positioned
- *    server settler AND the future client-side live simulator (a pinned
+ * node toward its anchor (a per-node anchor force). New nodes seed near
- *    node is just an anchor with full retention).
+ * their positioned neighbors; orphans seed on the rim OUTSIDE the core and
- *  - DETERMINISTIC: seeded by node id, so the same graph + ledger state
+ * are anchored there, so they read as "not yet connected knowledge".
- *    always settles identically.
  *
- * Orphans (degree-0 nodes) seed on the rim — outside the anchored core's
+ * Design constraints (kept deliberately, for live physics):
- * bounding box — so they read as "not yet connected knowledge", the organic
+ *  - PURE: no fs, no server types — this module runs server-side (the
- * outer ring the user asked for.
+ *    merge settle) and in the browser (the live simulation, via the core
+ *    barrel). A pinned node is just fx/fy; an anchored node is a spring.
+ *  - DETERMINISTIC: seeds derive from node id; d3-force ticks are
+ *    deterministic — same inputs, same layout.
  */
 
-import Graph from "graphology";
+import {
-import forceAtlas2 from "graphology-layout-forceatlas2";
+	forceSimulation,
-import type { GraphNode, GraphEdge, Position } from "./contracts.ts";
+	forceLink,
+	forceManyBody,
+	forceX,
+	forceY,
+	type Simulation,
+	type SimulationLinkDatum,
+	type SimulationNodeDatum,
+} from "d3-force";
+import type { GraphEdge, GraphNode, Position } from "./contracts.ts";
 import { seededRandom } from "./question-core.ts";
 
-export interface IncrementalLayoutOptions {
+/** A node the d3 simulation mutates (x/y/vx/vy; fx/fy = pinned). */
-	/** FA2 iterations per settle (default 100 — same depth as the classic
+export interface LayoutNode extends SimulationNodeDatum {
-	 *  one-shot pass, so a fresh graph settles exactly like the old code). */
+	id: string;
-	iterations?: number;
-	/** Per-iteration anchor retention: how much of a previously-positioned
-	 *  node's displacement from its anchor SURVIVES each iteration.
-	 *  1 = fully pinned (never moves), 0.85 = gentle drift where forces
-	 *  are strong (near new nodes), stillness where they are not. */
-	anchorRetention?: number;
 }
 
-/** Layout adjacency input: edges are undirected for layout purposes. */
+/** A link as d3 sees it (id strings resolve to node refs on init). */
+type SimLink = SimulationLinkDatum<LayoutNode>;
+
+export interface SimOptions {
+	/** Link spring rest length (world units). */
+	linkDistance?: number;
+	/** Many-body repulsion strength (negative). */
+	chargeStrength?: number;
+	/** Center-of-mass gravity: pulls loose components inward. Weak —
+	 *  anchors, not gravity, hold the evolved layout's frame. */
+	gravity?: { x: number; y: number; strength: number };
+	/** Alpha decay per tick — higher = snappier settle. The merge settle
+	 *  uses d3's default 0.0228 (~300 ticks); the live sim passes ~0.05. */
+	alphaDecay?: number;
+}
+
+/** Link input: edges are undirected for layout purposes. */
 export interface LayoutEdge {
 	from: string;
 	to: string;
 }
 
+const LINK_DISTANCE = 40;
+const CHARGE_STRENGTH = -120;
+/** Per-tick anchor re-blend: fraction of an anchored node's displacement
+ *  from its previous position that SURVIVES each tick. 0.85 = gentle
+ *  evolution where forces are strong, stillness where they are not —
+ *  the exact FA2-era constant. Position-space (alpha-independent), so it
+ *  cannot be overpowered by d3's long-range link springs the way a force-
+ *  space anchor can (forceLink is a Hooke spring: strength*(d-L)*alpha). */
+const ANCHOR_RETENTION = 0.85;
+/** Gravity strengths. d3 manyBody repulsion falls off as 1/d, so two
+ *  20-node blobs at distance d push with ~n1*n2*|charge|/d; cluster
+ *  spacing settles where that equals g*d*n/2 — g=0.03 lands clusters
+ *  ~400 world units apart (the FA2-era density), and the anchor re-blend
+ *  (position-space, alpha-independent) keeps gravity's transient sag
+ *  from ever moving an anchored node at rest. */
+const BOOTSTRAP_GRAVITY = 0.2;
+/** Exported: the live sim reuses this so its rest state matches the
+ *  server settle's equilibrium (one engine, one rest). */
+export const INCREMENTAL_GRAVITY = 0.12;
+
+/**
+ * The one force set. Returns a STOPPED simulation — callers drive it
+ * manually (tick-per-frame live, or a bounded tick loop when settling).
+ * Deterministic; mutates `nodes` in place (d3 semantics: impure by design,
+ * zero per-tick allocation).
+ */
+export function createGraphSimulation(
+	nodes: LayoutNode[],
+	edges: ReadonlyArray<LayoutEdge>,
+	options: SimOptions = {},
+): Simulation<LayoutNode, SimLink> {
+	const sim = forceSimulation<LayoutNode, SimLink>(nodes)
+		.force(
+			"link",
+			forceLink<LayoutNode, SimLink>(
+				edges.map((e) => ({ source: e.from, target: e.to })),
+			)
+				.id((d) => d.id)
+				.distance(options.linkDistance ?? LINK_DISTANCE),
+		)
+		.force("charge", forceManyBody<LayoutNode>().strength(options.chargeStrength ?? CHARGE_STRENGTH))
+		.alphaDecay(options.alphaDecay ?? 0.0228)
+		.stop();
+
+	const g = options.gravity;
+	if (g) {
+		sim.force("x", forceX<LayoutNode>(g.x).strength(g.strength));
+		sim.force("y", forceY<LayoutNode>(g.y).strength(g.strength));
+	}
+	return sim;
+}
+
+export interface IncrementalLayoutOptions {
+	/** Manual ticks for the settle (default 300 — d3's anneal to alphaMin). */
+	ticks?: number;
+	/** Per-tick anchor re-blend (default 0.85; 1 = fully pinned). */
+	anchorRetention?: number;
+	/** Center-of-mass gravity strength override (tuning/A-B experiments;
+	 *  defaults to the internal bootstrap/incremental constants). */
+	gravityStrength?: number;
+}
+
 /**
  * One incremental settle. `nodes`/`edges` describe the CURRENT graph;
  * `previous` is the positions ledger (empty on the very first settle —
- * then this degrades to the classic seeded-scatter + 100-iteration FA2
+ * then this degrades to a seeded-scatter bootstrap). Returns positions
- * pass, i.e. what the browser used to do from scratch every time).
+ * for EVERY node in `nodes`.
- * Returns positions for EVERY node in `nodes`.
  */
 export function incrementalLayout(
 	nodes: ReadonlyArray<Pick<GraphNode, "id">>,
@@ -55,8 +136,8 @@ export function incrementalLayout(
 	previous: ReadonlyMap<string, Position>,
 	options: IncrementalLayoutOptions = {},
 ): Map<string, Position> {
-	const iterations = options.iterations ?? 100;
+	const ticks = options.ticks ?? 300;
-	const retention = options.anchorRetention ?? 0.85;
+	const retention = options.anchorRetention ?? ANCHOR_RETENTION;
 
 	// Anchors: the warm-start set (the previous rest state).
 	const anchors = new Map<string, Position>();
@@ -85,20 +166,39 @@ export function incrementalLayout(
 		cx /= anchors.size;
 		cy /= anchors.size;
 	}
-	const coreRadius = hasCore
+	const coreRadius = hasCore ? Math.max(maxX - minX, maxY - minY) / 2 : 1;
-		? Math.max(maxX - minX, maxY - minY) / 2
-		: 1;
 
 	// Adjacency for neighbor seeding (undirected: edges include assertions).
 	const adjacency = new Map<string, string[]>();
+	const linkTo = (a: string, b: string): void => {
+		if (a === b) return;
+		let list = adjacency.get(a);
+		if (!list) adjacency.set(a, (list = []));
+		list.push(b);
+	};
 	for (const e of edges) {
-		if (e.from === e.to) continue;
+		linkTo(e.from, e.to);
-		(adjacency.get(e.from) ?? adjacency.set(e.from, []).get(e.from)!).push(e.to);
+		linkTo(e.to, e.from);
-		(adjacency.get(e.to) ?? adjacency.set(e.to, []).get(e.to)!).push(e.from);
 	}
 
-	const graph = new Graph();
+	// The rim radius derives from the CONNECTED core's mean radius — orphans
-	for (const node of nodes) {
+	// never inflate it (a max-span-based radius feeds back: each batch's
+	// rim pushes the next batch's rim farther out, and the layout runs
+	// away). 1.7x matches the density the FA2-era settle produced
+	// (orphan mean r ~338 vs connected ~194).
+	let rimRadius = 0;
+	let connectedAnchored = 0;
+	for (const [id, a] of anchors) {
+		if ((adjacency.get(id)?.length ?? 0) === 0) continue;
+		connectedAnchored++;
+		rimRadius += Math.hypot(a.x - cx, a.y - cy);
+	}
+	if (connectedAnchored > 0) rimRadius = (rimRadius / connectedAnchored) * 1.7;
+	else if (hasCore) rimRadius = coreRadius * 1.15; // no connected anchors yet: bbox fallback
+	rimRadius += 4;
+
+	// Seed every node.
+	const simNodes: LayoutNode[] = nodes.map((node) => {
 		const rand = seededRandom(node.id);
 		const anchor = anchors.get(node.id);
 		let x: number;
@@ -126,57 +226,63 @@ export function incrementalLayout(
 				y = sy / found + (rand() - 0.5) * 8;
 			} else if (hasCore) {
 				const angle = rand() * Math.PI * 2;
-				const radius = coreRadius * 1.15 + 4 + rand() * 8;
+				const radius = rimRadius + rand() * 8;
 				x = cx + Math.cos(angle) * radius;
 				y = cy + Math.sin(angle) * radius;
+				// An orphan's intended rest spot IS the rim seed: anchor it
+				// there so gravity cannot sink it into the core. (A later
+				// batch linking it to the graph pulls it in naturally —
+				// but then it also has a previous position, and its anchor
+				// becomes that previous position, exactly like any node.)
+				anchors.set(node.id, { x, y });
 			} else {
-				// Bootstrap: the classic seeded scatter (FA2 requires
+				// Bootstrap: the classic seeded scatter.
-				// non-zero coordinates; (rand()-0.5)*100 hits both axes).
 				x = (rand() - 0.5) * 100;
 				y = (rand() - 0.5) * 100;
 			}
 		}
-		// FA2 divides by distances — a coincident (0,0) seed is degenerate.
+		// d3 is fine with coincident seeds (no division), but nudge exact
+		// overlaps of a brand-new node onto its only neighbor anyway.
 		if (x === 0 && y === 0) x = 0.5;
-		graph.addNode(node.id, { x, y });
+		return { id: node.id, x, y };
-	}
+	});
-	for (const e of edges) {
-		if (graph.hasNode(e.from) && graph.hasNode(e.to) && !graph.hasEdge(e.from, e.to)) {
-			graph.addEdge(e.from, e.to);
-		}
-	}
 
-	// Same escalation as the browser path: Barnes-Hut above ~500 nodes.
+	const sim = createGraphSimulation(simNodes, edges, {
-	const settings = {
+		gravity: {
-		...forceAtlas2.inferSettings(graph),
+			x: cx,
-		...(graph.order > 500 ? { barnesHutOptimize: true } : {}),
+			y: cy,
-	};
+			strength: options.gravityStrength ?? (hasCore ? INCREMENTAL_GRAVITY : BOOTSTRAP_GRAVITY),
-	for (let i = 0; i < iterations; i++) {
+		},
-		forceAtlas2.assign(graph, { iterations: 1, settings });
+	});
-		// Anchor re-blend: previously-positioned nodes are pulled back
+	const byId = new Map(simNodes.map((n) => [n.id, n]));
-		// toward their rest positions, so the layout evolves locally
+	for (let i = 0; i < ticks; i++) {
-		// instead of globally reshuffling. displacement * retention —
+		sim.tick();
-		// strong forces still win out (equilibrium ≈ force/(1-retention)),
+		// Anchor re-blend (position space, alpha-independent — see the
-		// weak ones fade to stillness.
+		// ANCHOR_RETENTION note). Pinned nodes (fx/fy) are left to d3.
 		if (hasCore && retention < 1) {
 			for (const [id, a] of anchors) {
-				const attrs = graph.getNodeAttributes(id);
+				const n = byId.get(id);
-				graph.setNodeAttribute(id, "x", a.x + (attrs.x - a.x) * retention);
+				if (!n || n.fx != null || n.fy != null) continue;
-				graph.setNodeAttribute(id, "y", a.y + (attrs.y - a.y) * retention);
+				const x = n.x ?? 0;
+				const y = n.y ?? 0;
+				n.x = a.x + (x - a.x) * retention;
+				n.y = a.y + (y - a.y) * retention;
 			}
 		}
 	}
 
 	const out = new Map<string, Position>();
-	graph.forEachNode((id, attrs) => out.set(id, { x: attrs.x, y: attrs.y }));
+	for (const n of simNodes) out.set(n.id, { x: n.x ?? 0, y: n.y ?? 0 });
 	return out;
 }
 
 /**
  * The merge-time settle: recompute the resting layout from the CURRENT
  * graph + the positions ledger, and replace the ledger. Called by the
- * extraction pipeline after every merge (the sole writer). Synchronous —
+ * extraction pipeline after every merge (the sole writer) and by the
- * it must finish before the next /api/graph fetch reflects the merge.
+ * positions-commit endpoint when the graph grew under a live-physics
+ * commit (client positions become the anchor set). Synchronous — it must
+ * finish before the next /api/graph fetch reflects the change.
  */
 export function settleGraphLayout(graphStore: {
 	readNodes(): GraphNode[];