@elabs-ai/components-flow 4.0.0

package/src/flow-layout/flow-layout.ts

@@ -0,0 +1,104 @@
+import dagre from "@dagrejs/dagre";
+import { Position } from "@xyflow/react";
+import type { Edge, Node } from "@xyflow/react";
+
+/** Direction dagre lays the graph out in — top-to-bottom, left-to-right, etc. */
+export type FlowLayoutDirection = "TB" | "LR" | "BT" | "RL";
+
+/**
+ * The handle sides an edge should attach to for each layout direction. A
+ * directional layout must move the anchors with it: a left-to-right flow exits
+ * the source's RIGHT and enters the target's LEFT; top-to-bottom uses
+ * bottom/top. `layoutFlow` stamps these onto every node so `FlowNode` renders
+ * its default handles on the correct sides (and `FlowEdge` routes accordingly)
+ * — otherwise every layout is stuck with top/bottom handles.
+ */
+export const HANDLE_BY_DIRECTION: Record<
+  FlowLayoutDirection,
+  { source: Position; target: Position }
+> = {
+  TB: { source: Position.Bottom, target: Position.Top },
+  BT: { source: Position.Top, target: Position.Bottom },
+  LR: { source: Position.Right, target: Position.Left },
+  RL: { source: Position.Left, target: Position.Right },
+};
+
+export interface FlowLayoutOptions {
+  /** Layout direction. @default "TB" */
+  direction?: FlowLayoutDirection;
+  /** Gap between nodes in the same rank (dagre `nodesep`). @default 48 */
+  nodeSpacing?: number;
+  /** Gap between ranks (dagre `ranksep`). @default 72 */
+  rankSpacing?: number;
+}
+
+export interface FlowLayoutResult<NodeType extends Node = Node, EdgeType extends Edge = Edge> {
+  nodes: NodeType[];
+  edges: EdgeType[];
+}
+
+/** Fallback size used when a node hasn't been measured yet (React Flow's own default node width). */
+const DEFAULT_NODE_WIDTH = 172;
+const DEFAULT_NODE_HEIGHT = 40;
+
+function nodeSize(node: Node): { width: number; height: number } {
+  return {
+    width: node.measured?.width ?? node.width ?? DEFAULT_NODE_WIDTH,
+    height: node.measured?.height ?? node.height ?? DEFAULT_NODE_HEIGHT,
+  };
+}
+
+/**
+ * Pure dagre-powered auto layout. Computes new `position`s for `nodes` given
+ * `edges` — no React, no side effects, safe to call anywhere (including
+ * outside a component or in a test).
+ *
+ * Respects each node's **measured** size (`node.measured` — how React Flow
+ * v12 reports actual rendered dimensions), falling back to `node.width`/
+ * `node.height`, then a sensible default. Node identity and `data` are left
+ * untouched — only `position` changes.
+ *
+ * Pair with `useFlowLayout` to apply the result to a live canvas.
+ */
+export function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
+  nodes: NodeType[],
+  edges: EdgeType[],
+  options: FlowLayoutOptions = {},
+): FlowLayoutResult<NodeType, EdgeType> {
+  const { direction = "TB", nodeSpacing = 48, rankSpacing = 72 } = options;
+
+  const graph = new dagre.graphlib.Graph();
+  graph.setDefaultEdgeLabel(() => ({}));
+  graph.setGraph({ rankdir: direction, nodesep: nodeSpacing, ranksep: rankSpacing });
+
+  for (const node of nodes) {
+    const { width, height } = nodeSize(node);
+    graph.setNode(node.id, { width, height });
+  }
+
+  for (const edge of edges) {
+    graph.setEdge(edge.source, edge.target);
+  }
+
+  dagre.layout(graph);
+
+  const handles = HANDLE_BY_DIRECTION[direction];
+  const layoutedNodes = nodes.map((node) => {
+    const dagreNode = graph.node(node.id);
+    const { width, height } = nodeSize(node);
+    // dagre positions nodes by their center; React Flow positions by top-left.
+    return {
+      ...node,
+      // Move the anchors with the layout direction so `FlowNode` puts its
+      // handles on the sides the edges actually leave/enter.
+      sourcePosition: handles.source,
+      targetPosition: handles.target,
+      position: {
+        x: dagreNode.x - width / 2,
+        y: dagreNode.y - height / 2,
+      },
+    };
+  });
+
+  return { nodes: layoutedNodes, edges };
+}

package/src/flow-layout/index.ts

@@ -0,0 +1,14 @@
+export {
+  layoutFlow,
+  type FlowLayoutDirection,
+  type FlowLayoutOptions,
+  type FlowLayoutResult,
+} from "./flow-layout";
+export { useFlowLayout, type UseFlowLayoutResult } from "./use-flow-layout";
+export {
+  layoutGraph,
+  type LayoutAlgorithm,
+  type LayoutOptions,
+  type LayoutSpacing,
+} from "./layout-graph";
+export { useAutoLayout } from "./use-auto-layout";

package/src/flow-layout/layout-graph.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, it } from "vitest";
+import type { Edge, Node } from "@xyflow/react";
+import { layoutGraph } from "./layout-graph";
+
+function node(id: string): Node {
+  return { id, type: "brand", position: { x: 0, y: 0 }, data: { title: id } };
+}
+
+function edge(source: string, target: string): Edge {
+  return { id: `e-${source}-${target}`, source, target };
+}
+
+/** 1 center + 6 neighbors, all one hop away. */
+function starGraph(): { nodes: Node[]; edges: Edge[] } {
+  const nodes = ["center", "n1", "n2", "n3", "n4", "n5", "n6"].map(node);
+  const edges = ["n1", "n2", "n3", "n4", "n5", "n6"].map((id) => edge("center", id));
+  return { nodes, edges };
+}
+
+/** A straight 3-node chain: a (center) -> b (hop 1) -> c (hop 2). */
+function chainGraph(): { nodes: Node[]; edges: Edge[] } {
+  return {
+    nodes: ["a", "b", "c"].map(node),
+    edges: [edge("a", "b"), edge("b", "c")],
+  };
+}
+
+function positionOf(nodes: Node[], id: string) {
+  return nodes.find((n) => n.id === id)!.position;
+}
+
+function distance(p: { x: number; y: number }, q: { x: number; y: number } = { x: 0, y: 0 }) {
+  return Math.hypot(p.x - q.x, p.y - q.y);
+}
+
+describe("layoutGraph", () => {
+  describe("empty / disconnected input", () => {
+    it("returns [] for an empty graph, for every algorithm", () => {
+      for (const algorithm of ["concentric", "force", "layered-lr", "grid"] as const) {
+        expect(layoutGraph([], [], { algorithm })).toEqual([]);
+      }
+    });
+
+    it("never produces NaN positions for a disconnected graph", () => {
+      const nodes = ["a", "b", "c", "isolated1", "isolated2"].map(node);
+      const edges = [edge("a", "b"), edge("b", "c")];
+
+      for (const algorithm of ["concentric", "force", "layered-lr", "grid"] as const) {
+        const laidOut = layoutGraph(nodes, edges, { algorithm, iterations: 20 });
+        for (const n of laidOut) {
+          expect(Number.isFinite(n.position.x)).toBe(true);
+          expect(Number.isFinite(n.position.y)).toBe(true);
+        }
+      }
+    });
+
+    it("places fully-isolated (edgeless) nodes without NaN under concentric", () => {
+      const nodes = ["a", "b", "c"].map(node);
+      const laidOut = layoutGraph(nodes, [], { algorithm: "concentric", centerId: "a" });
+      for (const n of laidOut) {
+        expect(Number.isFinite(n.position.x)).toBe(true);
+        expect(Number.isFinite(n.position.y)).toBe(true);
+      }
+      // b and c are disconnected from the center — they still land on ring 1.
+      expect(distance(positionOf(laidOut, "b"))).toBeCloseTo(180, 5);
+      expect(distance(positionOf(laidOut, "c"))).toBeCloseTo(180, 5);
+    });
+  });
+
+  describe("concentric", () => {
+    it("preserves node identity and data — only position changes", () => {
+      const { nodes, edges } = starGraph();
+      const laidOut = layoutGraph(nodes, edges, { algorithm: "concentric" });
+      laidOut.forEach((n, i) => {
+        expect(n.id).toBe(nodes[i]!.id);
+        expect(n.data).toBe(nodes[i]!.data);
+      });
+    });
+
+    it("puts a star graph's 6 neighbors on ring 1 at unique angles, distance ringRadius", () => {
+      const { nodes, edges } = starGraph();
+      const ringRadius = 180;
+      const laidOut = layoutGraph(nodes, edges, {
+        algorithm: "concentric",
+        centerId: "center",
+        ringRadius,
+      });
+
+      const center = positionOf(laidOut, "center");
+      expect(center).toEqual({ x: 0, y: 0 });
+
+      const neighborIds = ["n1", "n2", "n3", "n4", "n5", "n6"];
+      const angles = neighborIds.map((id) => {
+        const p = positionOf(laidOut, id);
+        expect(distance(p)).toBeCloseTo(ringRadius, 5);
+        return Math.atan2(p.y, p.x);
+      });
+
+      // All six angles are distinct (rounded to guard float noise).
+      const rounded = angles.map((a) => Math.round(a * 1e6));
+      expect(new Set(rounded).size).toBe(6);
+    });
+
+    it("defaults centerId to the highest-degree node when omitted", () => {
+      const { nodes, edges } = starGraph();
+      const laidOut = layoutGraph(nodes, edges, { algorithm: "concentric" });
+      // "center" has degree 6 — every other node has degree 1 — so it must be
+      // the one left at the origin.
+      expect(positionOf(laidOut, "center")).toEqual({ x: 0, y: 0 });
+    });
+
+    it("puts the second hop of a chain at 2 × ringRadius from the center", () => {
+      const { nodes, edges } = chainGraph();
+      const ringRadius = 180;
+      const laidOut = layoutGraph(nodes, edges, {
+        algorithm: "concentric",
+        centerId: "a",
+        ringRadius,
+      });
+
+      expect(distance(positionOf(laidOut, "a"))).toBe(0);
+      expect(distance(positionOf(laidOut, "b"))).toBeCloseTo(ringRadius, 5);
+      expect(distance(positionOf(laidOut, "c"))).toBeCloseTo(2 * ringRadius, 5);
+    });
+
+    it("is deterministic — two runs on the same input produce identical positions", () => {
+      const { nodes, edges } = starGraph();
+      const first = layoutGraph(nodes, edges, { algorithm: "concentric", centerId: "center" });
+      const second = layoutGraph(nodes, edges, { algorithm: "concentric", centerId: "center" });
+      expect(first.map((n) => n.position)).toEqual(second.map((n) => n.position));
+    });
+  });
+
+  describe("force", () => {
+    it("separates two initially-coincident nodes", () => {
+      const nodes: Node[] = [
+        { id: "a", type: "brand", position: { x: 0, y: 0 }, data: {} },
+        { id: "b", type: "brand", position: { x: 0, y: 0 }, data: {} },
+      ];
+      const laidOut = layoutGraph(nodes, [], { algorithm: "force", iterations: 50 });
+      const a = positionOf(laidOut, "a");
+      const b = positionOf(laidOut, "b");
+      expect(distance(a, b)).toBeGreaterThan(0);
+    });
+
+    it("terminates in bounded time for a fixed iteration count", () => {
+      const { nodes, edges } = starGraph();
+      const start = Date.now();
+      const laidOut = layoutGraph(nodes, edges, { algorithm: "force", iterations: 300 });
+      expect(Date.now() - start).toBeLessThan(5000);
+      expect(laidOut).toHaveLength(nodes.length);
+    });
+
+    it("never produces NaN positions", () => {
+      const { nodes, edges } = starGraph();
+      const laidOut = layoutGraph(nodes, edges, { algorithm: "force", iterations: 50 });
+      for (const n of laidOut) {
+        expect(Number.isFinite(n.position.x)).toBe(true);
+        expect(Number.isFinite(n.position.y)).toBe(true);
+      }
+    });
+
+    it("is deterministic — two runs on the same input produce byte-identical positions", () => {
+      const { nodes, edges } = starGraph();
+      const first = layoutGraph(nodes, edges, { algorithm: "force", iterations: 100 });
+      const second = layoutGraph(nodes, edges, { algorithm: "force", iterations: 100 });
+      expect(first.map((n) => n.position)).toEqual(second.map((n) => n.position));
+    });
+
+    it("preserves node identity and data — only position changes", () => {
+      const { nodes, edges } = starGraph();
+      const laidOut = layoutGraph(nodes, edges, { algorithm: "force", iterations: 30 });
+      laidOut.forEach((n, i) => {
+        expect(n.id).toBe(nodes[i]!.id);
+        expect(n.data).toBe(nodes[i]!.data);
+      });
+    });
+  });
+
+  describe("layered-lr", () => {
+    it("delegates to layoutFlow direction=LR, ordering a chain left-to-right", () => {
+      const { nodes, edges } = chainGraph();
+      const laidOut = layoutGraph(nodes, edges, { algorithm: "layered-lr" });
+      const [a, b, c] = laidOut as [Node, Node, Node];
+      expect(a.position.x).toBeLessThan(b.position.x);
+      expect(b.position.x).toBeLessThan(c.position.x);
+    });
+
+    it("stamps right-out / left-in handle sides (not just position)", () => {
+      const { nodes, edges } = chainGraph();
+      const [a] = layoutGraph(nodes, edges, { algorithm: "layered-lr" }) as [Node];
+      expect(a.sourcePosition).toBe("right");
+      expect(a.targetPosition).toBe("left");
+    });
+
+    it("maps spacing.x/y onto rank/node spacing", () => {
+      const { nodes, edges } = chainGraph();
+      const tight = layoutGraph(nodes, edges, {
+        algorithm: "layered-lr",
+        spacing: { x: 10, y: 10 },
+      });
+      const wide = layoutGraph(nodes, edges, {
+        algorithm: "layered-lr",
+        spacing: { x: 500, y: 10 },
+      });
+      const tightGap = (tight[1]!.position.x as number) - (tight[0]!.position.x as number);
+      const wideGap = (wide[1]!.position.x as number) - (wide[0]!.position.x as number);
+      expect(wideGap).toBeGreaterThan(tightGap);
+    });
+
+    it("respects a custom nodeSize", () => {
+      const nodes: Node[] = [
+        { id: "a", type: "brand", position: { x: 0, y: 0 }, data: {} },
+        { id: "b", type: "brand", position: { x: 0, y: 0 }, data: {} },
+      ];
+      const edges: Edge[] = [edge("a", "b")];
+      const laidOut = layoutGraph(nodes, edges, {
+        algorithm: "layered-lr",
+        nodeSize: () => ({ width: 400, height: 200 }),
+      });
+      const gap = (laidOut[1]!.position.x as number) - (laidOut[0]!.position.x as number);
+      expect(gap).toBeGreaterThanOrEqual(400 + 72 - 1);
+      // The returned nodes are not permanently resized — only `position` changed.
+      expect(laidOut[0]).not.toHaveProperty("measured");
+    });
+  });
+
+  describe("grid", () => {
+    it("lays nodes out row-major using spacing", () => {
+      const nodes = ["a", "b", "c", "d"].map(node);
+      const laidOut = layoutGraph(nodes, [], {
+        algorithm: "grid",
+        spacing: { x: 200, y: 120 },
+      });
+      // ceil(sqrt(4)) = 2 columns.
+      expect(positionOf(laidOut, "a")).toEqual({ x: 0, y: 0 });
+      expect(positionOf(laidOut, "b")).toEqual({ x: 200, y: 0 });
+      expect(positionOf(laidOut, "c")).toEqual({ x: 0, y: 120 });
+      expect(positionOf(laidOut, "d")).toEqual({ x: 200, y: 120 });
+    });
+
+    it("stamps bottom-out / top-in handle sides", () => {
+      const [a] = layoutGraph(["a", "b"].map(node), [edge("a", "b")], {
+        algorithm: "grid",
+      }) as [Node];
+      expect(a.sourcePosition).toBe("bottom");
+      expect(a.targetPosition).toBe("top");
+    });
+
+    it("is deterministic", () => {
+      const nodes = ["a", "b", "c"].map(node);
+      const first = layoutGraph(nodes, [], { algorithm: "grid" });
+      const second = layoutGraph(nodes, [], { algorithm: "grid" });
+      expect(first.map((n) => n.position)).toEqual(second.map((n) => n.position));
+    });
+  });
+});

package/src/flow-layout/layout-graph.ts

@@ -0,0 +1,302 @@
+import {
+  forceCenter,
+  forceCollide,
+  forceLink,
+  forceManyBody,
+  forceSimulation,
+  type SimulationLinkDatum,
+  type SimulationNodeDatum,
+} from "d3-force";
+import type { Edge, Node } from "@xyflow/react";
+import { HANDLE_BY_DIRECTION, layoutFlow } from "./flow-layout";
+
+/** Which generic graph-geometry algorithm `layoutGraph` should run. */
+export type LayoutAlgorithm = "concentric" | "force" | "layered-lr" | "grid";
+
+/** Horizontal/vertical gap used by the `"grid"` and `"layered-lr"` algorithms. */
+export interface LayoutSpacing {
+  x: number;
+  y: number;
+}
+
+export interface LayoutOptions {
+  /** Which layout algorithm to run. */
+  algorithm: LayoutAlgorithm;
+  /**
+   * `"concentric"` only — the focal node placed at the origin. Defaults to the
+   * highest-degree node when omitted (or when the id doesn't match a node).
+   */
+  centerId?: string;
+  /** `"concentric"` only — radius of ring 1; ring N sits at `N × ringRadius`. @default 180 */
+  ringRadius?: number;
+  /** `"force"` only — number of synchronous simulation ticks to run. @default 300 */
+  iterations?: number;
+  /** `"grid"` / `"layered-lr"` — gap between nodes. @default {x:200,y:120} for grid. */
+  spacing?: LayoutSpacing;
+  /** Resolve a node's size by id. Falls back to `measured`/`width`/`height`/a sensible default. */
+  nodeSize?: (id: string) => { width: number; height: number };
+}
+
+const DEFAULT_NODE_WIDTH = 172;
+const DEFAULT_NODE_HEIGHT = 40;
+const DEFAULT_RING_RADIUS = 180;
+const DEFAULT_FORCE_ITERATIONS = 300;
+const DEFAULT_GRID_SPACING: LayoutSpacing = { x: 200, y: 120 };
+/** Base charge/link/collide tuning — chosen to read well at brand-ui's default node size. */
+const FORCE_CHARGE_STRENGTH = -300;
+const FORCE_LINK_DISTANCE = 150;
+
+function resolveNodeSize(
+  node: Node,
+  nodeSize?: (id: string) => { width: number; height: number },
+): { width: number; height: number } {
+  if (nodeSize) return nodeSize(node.id);
+  return {
+    width: node.measured?.width ?? node.width ?? DEFAULT_NODE_WIDTH,
+    height: node.measured?.height ?? node.height ?? DEFAULT_NODE_HEIGHT,
+  };
+}
+
+/**
+ * Pure graph-geometry auto layout. Computes new `position`s for `nodes` given
+ * `edges` and a `LayoutAlgorithm` — no React, no DOM, no side effects, safe to
+ * call anywhere (including outside a component or in a test). Deterministic:
+ * identical `nodes`/`edges`/`options` always produce identical positions.
+ *
+ * Node identity and `data` are left untouched — only `position` changes.
+ * Pair with `useAutoLayout` for a memoized hook form.
+ *
+ * - `"layered-lr"` delegates to the dagre-powered `layoutFlow` (direction `"LR"`).
+ * - `"concentric"` places `centerId` (or the highest-degree node) at the
+ *   origin, with BFS shells at `ring × ringRadius`; disconnected nodes land in
+ *   one extra outer ring so positions are never `NaN`.
+ * - `"force"` runs `d3-force` synchronously for a fixed number of `iterations`,
+ *   seeded on a circle by index (no randomness) so runs are reproducible.
+ * - `"grid"` lays nodes out row-major using `spacing`.
+ */
+export function layoutGraph<NodeType extends Node = Node, EdgeType extends Edge = Edge>(
+  nodes: NodeType[],
+  edges: EdgeType[],
+  options: LayoutOptions,
+): NodeType[] {
+  if (nodes.length === 0) return [];
+
+  switch (options.algorithm) {
+    case "layered-lr":
+      return layoutLayeredLr(nodes, edges, options);
+    case "concentric":
+      return layoutConcentric(nodes, edges, options);
+    case "force":
+      return layoutForce(nodes, edges, options);
+    case "grid":
+      return layoutGrid(nodes, options);
+    default: {
+      const exhaustiveCheck: never = options.algorithm;
+      throw new Error(`layoutGraph: unknown algorithm "${String(exhaustiveCheck)}"`);
+    }
+  }
+}
+
+function layoutLayeredLr<NodeType extends Node, EdgeType extends Edge>(
+  nodes: NodeType[],
+  edges: EdgeType[],
+  options: LayoutOptions,
+): NodeType[] {
+  const { spacing, nodeSize } = options;
+
+  // dagre (via layoutFlow) reads sizes off `measured`/`width`/`height` — feed it
+  // resolved sizes on a throwaway copy so a caller-supplied `nodeSize` is honored
+  // without mutating (or permanently resizing) the nodes we return.
+  const sizedNodes = nodeSize
+    ? nodes.map((node) => {
+        const { width, height } = nodeSize(node.id);
+        return { ...node, width, height, measured: { width, height } };
+      })
+    : nodes;
+
+  const { nodes: laidOut } = layoutFlow(sizedNodes, edges, {
+    direction: "LR",
+    // For an LR flow, ranks progress horizontally (x) and nodes within a rank
+    // stack vertically (y) — map spacing accordingly onto dagre's rank/node sep.
+    nodeSpacing: spacing?.y,
+    rankSpacing: spacing?.x,
+  });
+
+  // Carry the LR handle sides (right-out / left-in) that layoutFlow stamped on,
+  // not just the position — otherwise the layout flips positions but leaves the
+  // anchors on top/bottom.
+  return nodes.map((node, i) => ({
+    ...node,
+    sourcePosition: laidOut[i]!.sourcePosition,
+    targetPosition: laidOut[i]!.targetPosition,
+    position: laidOut[i]!.position,
+  }));
+}
+
+function resolveCenterId(
+  centerId: string | undefined,
+  nodeIds: string[],
+  adjacency: Map<string, Set<string>>,
+): string {
+  if (centerId && nodeIds.includes(centerId)) return centerId;
+
+  let best = nodeIds[0]!;
+  let bestDegree = -1;
+  for (const id of nodeIds) {
+    const degree = adjacency.get(id)?.size ?? 0;
+    if (degree > bestDegree) {
+      bestDegree = degree;
+      best = id;
+    }
+  }
+  return best;
+}
+
+function layoutConcentric<NodeType extends Node, EdgeType extends Edge>(
+  nodes: NodeType[],
+  edges: EdgeType[],
+  options: LayoutOptions,
+): NodeType[] {
+  const ringRadius = options.ringRadius ?? DEFAULT_RING_RADIUS;
+  const nodeIds = nodes.map((node) => node.id);
+  const idSet = new Set(nodeIds);
+
+  const adjacency = new Map<string, Set<string>>();
+  for (const id of nodeIds) adjacency.set(id, new Set());
+  for (const edge of edges) {
+    if (!idSet.has(edge.source) || !idSet.has(edge.target)) continue;
+    adjacency.get(edge.source)!.add(edge.target);
+    adjacency.get(edge.target)!.add(edge.source);
+  }
+
+  const centerId = resolveCenterId(options.centerId, nodeIds, adjacency);
+
+  // BFS shells from the center — hop distance doubles as the ring index.
+  const hopOf = new Map<string, number>();
+  hopOf.set(centerId, 0);
+  const queue: string[] = [centerId];
+  let maxHop = 0;
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    const currentHop = hopOf.get(current)!;
+    for (const neighbor of adjacency.get(current) ?? []) {
+      if (hopOf.has(neighbor)) continue;
+      const hop = currentHop + 1;
+      hopOf.set(neighbor, hop);
+      maxHop = Math.max(maxHop, hop);
+      queue.push(neighbor);
+    }
+  }
+
+  // Disconnected nodes (unreachable from the center) get one extra ring beyond
+  // the farthest reached hop — never left with a NaN/undefined position.
+  const leftoverHop = maxHop + 1;
+  for (const id of nodeIds) {
+    if (!hopOf.has(id)) hopOf.set(id, leftoverHop);
+  }
+
+  const rings = new Map<number, string[]>();
+  for (const id of nodeIds) {
+    const hop = hopOf.get(id)!;
+    if (hop === 0) continue;
+    if (!rings.has(hop)) rings.set(hop, []);
+    rings.get(hop)!.push(id);
+  }
+
+  const positionById = new Map<string, { x: number; y: number }>();
+  positionById.set(centerId, { x: 0, y: 0 });
+
+  for (const [hop, ids] of rings) {
+    const count = ids.length;
+    const angleStep = (2 * Math.PI) / count;
+    // Stagger successive rings by a growing half-step so radial edges don't
+    // trivially line up with the ring behind/ahead of them.
+    const ringOffset = (hop - 1) * (angleStep / 2);
+    const radius = hop * ringRadius;
+    ids.forEach((id, i) => {
+      const angle = ringOffset + i * angleStep;
+      positionById.set(id, { x: radius * Math.cos(angle), y: radius * Math.sin(angle) });
+    });
+  }
+
+  return nodes.map((node) => ({
+    ...node,
+    position: positionById.get(node.id) ?? { x: 0, y: 0 },
+  }));
+}
+
+interface ForceSimNode extends SimulationNodeDatum {
+  id: string;
+}
+
+function layoutForce<NodeType extends Node, EdgeType extends Edge>(
+  nodes: NodeType[],
+  edges: EdgeType[],
+  options: LayoutOptions,
+): NodeType[] {
+  const iterations = options.iterations ?? DEFAULT_FORCE_ITERATIONS;
+  const nodeIds = new Set(nodes.map((node) => node.id));
+
+  // Seed initial positions deterministically on a circle by index — never
+  // `Math.random()` — so two runs with the same input converge identically.
+  const seedRadius = Math.max(nodes.length * 20, 100);
+  const simNodes: ForceSimNode[] = nodes.map((node, i) => {
+    const angle = (2 * Math.PI * i) / Math.max(nodes.length, 1);
+    return { id: node.id, x: seedRadius * Math.cos(angle), y: seedRadius * Math.sin(angle) };
+  });
+
+  const simLinks: SimulationLinkDatum<ForceSimNode>[] = edges
+    .filter((edge) => nodeIds.has(edge.source) && nodeIds.has(edge.target))
+    .map((edge) => ({ source: edge.source, target: edge.target }));
+
+  const collisionById = new Map(
+    nodes.map((node) => {
+      const { width, height } = resolveNodeSize(node, options.nodeSize);
+      return [node.id, Math.max(width, height) / 2];
+    }),
+  );
+
+  const simulation = forceSimulation(simNodes)
+    .force("charge", forceManyBody().strength(FORCE_CHARGE_STRENGTH))
+    .force(
+      "link",
+      forceLink<ForceSimNode, SimulationLinkDatum<ForceSimNode>>(simLinks)
+        .id((d) => d.id)
+        .distance(FORCE_LINK_DISTANCE),
+    )
+    .force("center", forceCenter(0, 0))
+    .force(
+      "collide",
+      forceCollide<ForceSimNode>((d) => collisionById.get(d.id) ?? DEFAULT_NODE_WIDTH / 2),
+    )
+    .stop();
+
+  for (let i = 0; i < iterations; i++) {
+    simulation.tick();
+  }
+
+  const positionById = new Map(simNodes.map((n) => [n.id, { x: n.x ?? 0, y: n.y ?? 0 }]));
+
+  return nodes.map((node) => ({
+    ...node,
+    position: positionById.get(node.id) ?? { x: 0, y: 0 },
+  }));
+}
+
+function layoutGrid<NodeType extends Node>(nodes: NodeType[], options: LayoutOptions): NodeType[] {
+  const spacing = options.spacing ?? DEFAULT_GRID_SPACING;
+  const cols = Math.max(1, Math.ceil(Math.sqrt(nodes.length)));
+  // A grid reads top-to-bottom; anchor edges bottom-out / top-in to match.
+  const handles = HANDLE_BY_DIRECTION.TB;
+
+  return nodes.map((node, i) => {
+    const row = Math.floor(i / cols);
+    const col = i % cols;
+    return {
+      ...node,
+      sourcePosition: handles.source,
+      targetPosition: handles.target,
+      position: { x: col * spacing.x, y: row * spacing.y },
+    };
+  });
+}