@graph-render/core 1.0.1

package/src/layouts/dag.ts

@@ -0,0 +1,76 @@
+import { EdgeData, LayoutDirection, NodeData, PositionedNode } from '@graph-render/types';
+import {
+  DEFAULT_NODE_GAP,
+  DEFAULT_NODE_SIZE,
+  DEFAULT_PADDING,
+  getMaxNodeDimensions,
+} from '../utils';
+import { assignDagLevels } from './treeTopology';
+
+const groupNodesByLayer = (nodes: NodeData[], levels: Map<string, number>): NodeData[][] => {
+  const buckets = new Map<number, NodeData[]>();
+  nodes.forEach((node) => {
+    const level = levels.get(node.id) ?? 0;
+    const entries = buckets.get(level) ?? [];
+    entries.push(node);
+    buckets.set(level, entries);
+  });
+
+  return Array.from(buckets.entries())
+    .sort((a, b) => a[0] - b[0])
+    .map(([, entries]) => entries);
+};
+
+export const dagLayout = (
+  nodes: NodeData[],
+  edges: EdgeData[],
+  pad: number = DEFAULT_PADDING,
+  gap: number = DEFAULT_NODE_GAP,
+  direction: LayoutDirection = LayoutDirection.LTR,
+  width: number = 960,
+  height: number = 720
+): PositionedNode[] => {
+  if (!nodes.length) {
+    return [];
+  }
+
+  const { levels } = assignDagLevels(nodes, edges);
+  const layers = groupNodesByLayer(nodes, levels);
+  const { maxWidth: maxNodeWidth, maxHeight: maxNodeHeight } = getMaxNodeDimensions(nodes);
+  const columnGap = maxNodeWidth + gap;
+  const rowGap = maxNodeHeight + Math.max(24, gap * 0.7);
+  const contentWidth = Math.max(width - pad * 2, columnGap * Math.max(layers.length - 1, 1));
+  const baseX = direction === LayoutDirection.RTL ? width - pad - maxNodeWidth : pad;
+  const stepX = direction === LayoutDirection.RTL ? -columnGap : columnGap;
+
+  return layers.flatMap((layer, layerIndex) => {
+    const totalHeight = layer.reduce(
+      (sum, node, index) =>
+        sum +
+        (node.size?.height ?? DEFAULT_NODE_SIZE.height) +
+        (index > 0 ? rowGap - maxNodeHeight : 0),
+      0
+    );
+    let y = Math.max(pad, (height - totalHeight) / 2);
+
+    return layer.map((node, nodeIndex) => {
+      const nodeWidth = node.size?.width ?? DEFAULT_NODE_SIZE.width;
+      const x =
+        baseX +
+        layerIndex * stepX +
+        (direction === LayoutDirection.RTL ? maxNodeWidth - nodeWidth : 0);
+      const positioned = {
+        ...node,
+        position: {
+          x: layers.length > 1 ? x : pad + Math.max(0, (contentWidth - nodeWidth) / 2),
+          y,
+        },
+      } as PositionedNode;
+
+      y +=
+        (node.size?.height ?? DEFAULT_NODE_SIZE.height) +
+        (nodeIndex < layer.length - 1 ? rowGap - maxNodeHeight : 0);
+      return positioned;
+    });
+  });
+};

package/src/layouts/forceDirected.ts

@@ -0,0 +1,224 @@
+import { EdgeData, NodeData, Point, PositionedNode } from '@graph-render/types';
+import { DEFAULT_NODE_GAP, DEFAULT_NODE_SIZE, DEFAULT_PADDING } from '../utils';
+import { gridLayout } from './grid';
+
+const FORCE_LAYOUT_CACHE_LIMIT = 24;
+const MAX_SYNC_FORCE_NODES = 250;
+// NOTE: this cache is intentionally module-level so warm hits persist across
+// sequential renders of the same graph (common during viewport-only updates).
+// Trade-off: all <Graph> instances in the same JS bundle share the same 24-slot
+// LRU.  Keys include the full node/edge topology, so stale hits are extremely
+// unlikely.  If you mount many independent graphs with similar-but-distinct
+// topologies and see layout lag, increase FORCE_LAYOUT_CACHE_LIMIT.
+const forceLayoutCache = new Map<string, PositionedNode[]>();
+
+const buildForceLayoutCacheKey = (
+  nodes: NodeData[],
+  edges: EdgeData[],
+  pad: number,
+  width: number,
+  height: number,
+  gap: number
+): string | null => {
+  try {
+    return JSON.stringify({
+      pad,
+      width,
+      height,
+      gap,
+      nodes: nodes.map((node) => ({
+        id: node.id,
+        size: node.size,
+        label: node.label,
+      })),
+      edges: edges.map((edge) => ({
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        type: edge.type,
+      })),
+    });
+  } catch {
+    return null;
+  }
+};
+
+const getCachedForceLayout = (cacheKey: string | null): PositionedNode[] | undefined => {
+  if (!cacheKey) {
+    return undefined;
+  }
+
+  const cached = forceLayoutCache.get(cacheKey);
+  if (!cached) {
+    return undefined;
+  }
+
+  forceLayoutCache.delete(cacheKey);
+  forceLayoutCache.set(cacheKey, cached);
+  return cached.map((node) => ({
+    ...node,
+    position: { ...node.position },
+    size: node.size ? { ...node.size } : undefined,
+  }));
+};
+
+const setCachedForceLayout = (cacheKey: string | null, nodes: PositionedNode[]): void => {
+  if (!cacheKey) {
+    return;
+  }
+
+  if (forceLayoutCache.size >= FORCE_LAYOUT_CACHE_LIMIT) {
+    const oldestKey = forceLayoutCache.keys().next().value;
+    if (oldestKey) {
+      forceLayoutCache.delete(oldestKey);
+    }
+  }
+
+  forceLayoutCache.set(
+    cacheKey,
+    nodes.map((node) => ({
+      ...node,
+      position: { ...node.position },
+      size: node.size ? { ...node.size } : undefined,
+    }))
+  );
+};
+
+const clampPoint = (
+  point: Point,
+  width: number,
+  height: number,
+  pad: number,
+  node: NodeData
+): Point => {
+  const nodeWidth = node.size?.width ?? DEFAULT_NODE_SIZE.width;
+  const nodeHeight = node.size?.height ?? DEFAULT_NODE_SIZE.height;
+
+  return {
+    x: Math.min(Math.max(point.x, pad), width - pad - nodeWidth),
+    y: Math.min(Math.max(point.y, pad), height - pad - nodeHeight),
+  };
+};
+
+const getRequiredPoint = (points: Map<string, Point>, nodeId: string): Point => {
+  const point = points.get(nodeId);
+
+  if (!point) {
+    throw new Error(`Force-directed layout could not resolve point data for node "${nodeId}".`);
+  }
+
+  return point;
+};
+
+export const forceDirectedLayout = (
+  nodes: NodeData[],
+  edges: EdgeData[],
+  pad: number = DEFAULT_PADDING,
+  width: number = 960,
+  height: number = 720,
+  gap: number = DEFAULT_NODE_GAP
+): PositionedNode[] => {
+  if (!nodes.length) {
+    return [];
+  }
+
+  if (nodes.length > MAX_SYNC_FORCE_NODES) {
+    return gridLayout(nodes, pad, gap);
+  }
+
+  const cacheKey = buildForceLayoutCacheKey(nodes, edges, pad, width, height, gap);
+  const cached = getCachedForceLayout(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const area = Math.max((width - pad * 2) * (height - pad * 2), 1);
+  const k = Math.sqrt(area / Math.max(nodes.length, 1));
+  const positions = new Map<string, Point>();
+  // FIX: removed the `adjacency` Map that was built here but never read by the
+  // algorithm.  Repulsion iterates node pairs directly; attraction iterates the
+  // `edges` array directly.  Building the map was O(e) wasted work per layout call.
+
+  nodes.forEach((node, index) => {
+    const angle = (2 * Math.PI * index) / Math.max(nodes.length, 1);
+    const radius = Math.min(width, height) * 0.25;
+    positions.set(node.id, {
+      x: width / 2 + radius * Math.cos(angle),
+      y: height / 2 + radius * Math.sin(angle),
+    });
+  });
+
+  // FIX: removed the edges.forEach that populated `adjacency` (now deleted).
+  // The attraction-force loop below already iterates `edges` directly.
+  for (let iteration = 0; iteration < 80; iteration += 1) {
+    const displacement = new Map<string, Point>();
+    nodes.forEach((node) => displacement.set(node.id, { x: 0, y: 0 }));
+
+    for (let i = 0; i < nodes.length; i += 1) {
+      for (let j = i + 1; j < nodes.length; j += 1) {
+        const source = nodes[i];
+        const target = nodes[j];
+        const sourcePos = getRequiredPoint(positions, source.id);
+        const targetPos = getRequiredPoint(positions, target.id);
+        const dx = sourcePos.x - targetPos.x;
+        const dy = sourcePos.y - targetPos.y;
+        const distance = Math.max(1, Math.hypot(dx, dy));
+        const force = (k * k) / distance;
+        const offsetX = (dx / distance) * force;
+        const offsetY = (dy / distance) * force;
+        const sourceDisp = getRequiredPoint(displacement, source.id);
+        const targetDisp = getRequiredPoint(displacement, target.id);
+        sourceDisp.x += offsetX;
+        sourceDisp.y += offsetY;
+        targetDisp.x -= offsetX;
+        targetDisp.y -= offsetY;
+      }
+    }
+
+    edges.forEach((edge) => {
+      const sourcePos = getRequiredPoint(positions, edge.source);
+      const targetPos = getRequiredPoint(positions, edge.target);
+      const dx = sourcePos.x - targetPos.x;
+      const dy = sourcePos.y - targetPos.y;
+      const distance = Math.max(1, Math.hypot(dx, dy));
+      const force = (distance * distance) / k;
+      const offsetX = (dx / distance) * force;
+      const offsetY = (dy / distance) * force;
+      const sourceDisp = getRequiredPoint(displacement, edge.source);
+      const targetDisp = getRequiredPoint(displacement, edge.target);
+      sourceDisp.x -= offsetX;
+      sourceDisp.y -= offsetY;
+      targetDisp.x += offsetX;
+      targetDisp.y += offsetY;
+    });
+
+    const temperature = Math.max(2, gap * (1 - iteration / 80));
+    nodes.forEach((node) => {
+      const point = getRequiredPoint(positions, node.id);
+      const disp = getRequiredPoint(displacement, node.id);
+      const magnitude = Math.max(1, Math.hypot(disp.x, disp.y));
+      const nextPoint = {
+        x: point.x + (disp.x / magnitude) * Math.min(magnitude, temperature),
+        y: point.y + (disp.y / magnitude) * Math.min(magnitude, temperature),
+      };
+      positions.set(node.id, clampPoint(nextPoint, width, height, pad, node));
+    });
+  }
+
+  const positionedNodes = nodes.map((node) => {
+    const point = getRequiredPoint(positions, node.id);
+    const size = node.size ?? DEFAULT_NODE_SIZE;
+
+    return {
+      ...node,
+      position: {
+        x: point.x - size.width / 2,
+        y: point.y - size.height / 2,
+      },
+    } as PositionedNode;
+  });
+
+  setCachedForceLayout(cacheKey, positionedNodes);
+
+  return positionedNodes;
+};

package/src/layouts/grid.ts

@@ -0,0 +1,50 @@
+import { NodeData, PositionedNode, Point } from '@graph-render/types';
+import { DEFAULT_NODE_SIZE, DEFAULT_PADDING, DEFAULT_NODE_GAP } from '../utils';
+
+/**
+ * Calculate grid dimensions based on node count
+ */
+const calculateGridColumns = (nodeCount: number): number => {
+  return Math.ceil(Math.sqrt(nodeCount));
+};
+
+/**
+ * Calculate grid position for a node at a given index
+ */
+const calculateGridPosition = (
+  index: number,
+  columns: number,
+  nodeWidth: number,
+  nodeHeight: number,
+  padding: number,
+  gap: number
+): Point => {
+  const col = index % columns;
+  const row = Math.floor(index / columns);
+  return {
+    x: padding + col * (nodeWidth + gap),
+    y: padding + row * (nodeHeight + gap),
+  };
+};
+
+/**
+ * Layout nodes in a grid pattern
+ */
+export const gridLayout = (
+  nodes: NodeData[],
+  pad: number = DEFAULT_PADDING,
+  gap: number = DEFAULT_NODE_GAP
+): PositionedNode[] => {
+  const count = nodes.length;
+  const cols = calculateGridColumns(count);
+
+  return nodes.map((node, idx) => {
+    if (node.position) return node as PositionedNode;
+
+    const nodeWidth = node.size?.width ?? DEFAULT_NODE_SIZE.width;
+    const nodeHeight = node.size?.height ?? DEFAULT_NODE_SIZE.height;
+    const position = calculateGridPosition(idx, cols, nodeWidth, nodeHeight, pad, gap);
+
+    return { ...node, position } as PositionedNode;
+  });
+};

package/src/layouts/index.ts

@@ -0,0 +1,148 @@
+import {
+  NodeData,
+  PositionedNode,
+  LayoutOptions,
+  LayoutType,
+  LayoutDirection,
+} from '@graph-render/types';
+import { DEFAULT_NODE_GAP, DEFAULT_PADDING, applyNodeSizing } from '../utils';
+import { gridLayout } from './grid';
+import { centeredLayout } from './centered';
+import { radialTreeLayout } from './radialTree';
+import { treeLayout } from './tree';
+import { dagLayout } from './dag';
+import { forceDirectedLayout } from './forceDirected';
+import { compactBracketLayout } from './compactBracket';
+import { orthogonalFlowLayout } from './orthogonalFlow';
+
+const runSelectedLayout = (options: LayoutOptions, sizedNodes: NodeData[]): PositionedNode[] => {
+  const { edges, padding, theme, layout, width, height, layoutDirection } = options;
+  const gap = theme?.nodeGap ?? DEFAULT_NODE_GAP;
+  const pad = padding ?? DEFAULT_PADDING;
+  const resolvedLayout = layout ?? LayoutType.Grid;
+
+  const assertUnreachable = (value: never): never => {
+    throw new Error(`Unsupported layout type: ${String(value)}`);
+  };
+
+  switch (resolvedLayout) {
+    case LayoutType.Tree:
+      return treeLayout(sizedNodes, edges, pad, gap, layoutDirection ?? LayoutDirection.LTR, height);
+    case LayoutType.Radial:
+      return radialTreeLayout(sizedNodes, edges, pad, width, height, gap);
+    case LayoutType.Centered:
+      return centeredLayout(sizedNodes, pad, width, height);
+    case LayoutType.Dag:
+      return dagLayout(
+        sizedNodes,
+        edges,
+        pad,
+        gap,
+        layoutDirection ?? LayoutDirection.LTR,
+        width,
+        height
+      );
+    case LayoutType.ForceDirected:
+      return forceDirectedLayout(sizedNodes, edges, pad, width, height, gap);
+    case LayoutType.CompactBracket:
+      return compactBracketLayout(
+        sizedNodes,
+        edges,
+        pad,
+        gap,
+        layoutDirection ?? LayoutDirection.LTR,
+        height
+      );
+    case LayoutType.OrthogonalFlow:
+      return orthogonalFlowLayout(
+        sizedNodes,
+        edges,
+        pad,
+        gap,
+        layoutDirection ?? LayoutDirection.LTR,
+        width,
+        height
+      );
+    case LayoutType.Grid:
+      return gridLayout(sizedNodes, pad, gap);
+    default:
+      return assertUnreachable(resolvedLayout);
+  }
+};
+
+const getAnchoredLayoutOffset = (
+  autoLayout: PositionedNode[],
+  fixedNodes: PositionedNode[]
+): { x: number; y: number } => {
+  if (!fixedNodes.length) {
+    return { x: 0, y: 0 };
+  }
+
+  const positionedFixed = fixedNodes
+    .map((fixedNode) => {
+      const laidOut = autoLayout.find((node) => node.id === fixedNode.id);
+      return laidOut ? { fixedNode, laidOut } : null;
+    })
+    .filter(
+      (entry): entry is { fixedNode: PositionedNode; laidOut: PositionedNode } => entry !== null
+    );
+
+  if (!positionedFixed.length) {
+    return { x: 0, y: 0 };
+  }
+
+  const totals = positionedFixed.reduce(
+    (acc, entry) => ({
+      x: acc.x + (entry.fixedNode.position.x - entry.laidOut.position.x),
+      y: acc.y + (entry.fixedNode.position.y - entry.laidOut.position.y),
+    }),
+    { x: 0, y: 0 }
+  );
+
+  return {
+    x: totals.x / positionedFixed.length,
+    y: totals.y / positionedFixed.length,
+  };
+};
+
+export const layoutNodes = (options: LayoutOptions): PositionedNode[] => {
+  const sizedNodes = applyNodeSizing(options.nodes, options);
+
+  const missingPositions = sizedNodes.some((node) => !node.position);
+
+  if (!missingPositions) {
+    return sizedNodes as PositionedNode[];
+  }
+
+  const fixedNodes = sizedNodes.filter((node): node is PositionedNode => Boolean(node.position));
+  const autoLayoutInput = sizedNodes.map((node) => ({ ...node, position: undefined }));
+  const autoLayout = runSelectedLayout(options, autoLayoutInput);
+  const offset = getAnchoredLayoutOffset(autoLayout, fixedNodes);
+  const fixedNodeMap = new Map(fixedNodes.map((node) => [node.id, node]));
+
+  return autoLayout.map((node) => {
+    const fixedNode = fixedNodeMap.get(node.id);
+    if (fixedNode) {
+      return fixedNode;
+    }
+
+    return {
+      ...node,
+      position: {
+        x: node.position.x + offset.x,
+        y: node.position.y + offset.y,
+      },
+    };
+  });
+};
+
+export {
+  gridLayout,
+  centeredLayout,
+  radialTreeLayout,
+  treeLayout,
+  dagLayout,
+  forceDirectedLayout,
+  compactBracketLayout,
+  orthogonalFlowLayout,
+};

package/src/layouts/orthogonalFlow.ts

@@ -0,0 +1,112 @@
+import { EdgeData, LayoutDirection, NodeData, PositionedNode } from '@graph-render/types';
+import { DEFAULT_NODE_GAP, DEFAULT_NODE_SIZE, DEFAULT_PADDING } from '../utils';
+import { assignDagLevels } from './treeTopology';
+
+const VERTICAL_GAP_RATIO = 0.45;
+const VERTICAL_GAP_MIN = 20;
+const VERTICAL_GAP_HEIGHT_RATIO = 0.3;
+const DEFAULT_WIDTH = 960;
+const DEFAULT_HEIGHT = 720;
+
+export const orthogonalFlowLayout = (
+  nodes: NodeData[],
+  edges: EdgeData[],
+  pad: number = DEFAULT_PADDING,
+  gap: number = DEFAULT_NODE_GAP,
+  direction: LayoutDirection = LayoutDirection.LTR,
+  width: number = DEFAULT_WIDTH,
+  height: number = DEFAULT_HEIGHT
+): PositionedNode[] => {
+  if (!nodes.length) {
+    return [];
+  }
+
+  const safePad = Number.isFinite(pad) && pad >= 0 ? pad : DEFAULT_PADDING;
+  const safeGap = Number.isFinite(gap) && gap >= 0 ? gap : DEFAULT_NODE_GAP;
+  const safeWidth = Number.isFinite(width) && width > 0 ? width : DEFAULT_WIDTH;
+  const safeHeight = Number.isFinite(height) && height > 0 ? height : DEFAULT_HEIGHT;
+
+  const { levels } = assignDagLevels(nodes, edges);
+  const buckets = new Map<number, NodeData[]>();
+  nodes.forEach((node) => {
+    const level = levels.get(node.id);
+    if (level == null) {
+      throw new Error(`DAG layout could not assign a level to node "${node.id}".`);
+    }
+    const bucket = buckets.get(level) ?? [];
+    bucket.push(node);
+    buckets.set(level, bucket);
+  });
+
+  const isRTL = direction === LayoutDirection.RTL;
+
+  // Sort columns by level once so per-column x accumulation is deterministic.
+  const sortedColumns = Array.from(buckets.entries()).sort((a, b) => a[0] - b[0]);
+
+  // Per-column max node width drives column pitch; avoids a single wide node in
+  // one column inflating the spacing of every other column.
+  const colMaxWidths = new Map<number, number>(
+    sortedColumns.map(([level, levelNodes]) => [
+      level,
+      levelNodes.reduce(
+        (max, node) => Math.max(max, node.size?.width ?? DEFAULT_NODE_SIZE.width),
+        0
+      ),
+    ])
+  );
+
+  // Accumulate column x start positions so each column occupies exactly its own
+  // content width rather than the global max width.
+  const colX = new Map<number, number>();
+  if (isRTL) {
+    let xCursor = safeWidth - safePad;
+    for (const [level] of sortedColumns) {
+      xCursor -= colMaxWidths.get(level)!;
+      colX.set(level, xCursor);
+      xCursor -= safeGap;
+    }
+  } else {
+    let xCursor = safePad;
+    for (const [level] of sortedColumns) {
+      colX.set(level, xCursor);
+      xCursor += colMaxWidths.get(level)! + safeGap;
+    }
+  }
+
+  return sortedColumns.flatMap(([level, levelNodes]) => {
+    const colMaxWidth = colMaxWidths.get(level)!;
+    const colStartX = colX.get(level)!;
+    const colMaxNodeHeight = levelNodes.reduce(
+      (max, node) => Math.max(max, node.size?.height ?? DEFAULT_NODE_SIZE.height),
+      0
+    );
+    // Gap is proportional to both the user-supplied spacing parameter and each
+    // column's tallest node so that visually dense columns stay readable.
+    const verticalGap = Math.max(
+      VERTICAL_GAP_MIN,
+      safeGap * VERTICAL_GAP_RATIO,
+      colMaxNodeHeight * VERTICAL_GAP_HEIGHT_RATIO
+    );
+    const contentHeight = levelNodes.reduce(
+      (sum, node) => sum + (node.size?.height ?? DEFAULT_NODE_SIZE.height),
+      0
+    );
+    const totalGap = verticalGap * Math.max(levelNodes.length - 1, 0);
+    const centeredY = (safeHeight - contentHeight - totalGap) / 2;
+    // When content + gaps exceed the available height, centeredY goes negative
+    // and the column is top-anchored at safePad instead of disappearing off-canvas.
+    const maxY = safeHeight - safePad;
+    let y = Math.max(safePad, centeredY);
+
+    return levelNodes.map((node) => {
+      const nodeHeight = node.size?.height ?? DEFAULT_NODE_SIZE.height;
+      const nodeWidth = node.size?.width ?? DEFAULT_NODE_SIZE.width;
+      const position = {
+        x: colStartX + (isRTL ? colMaxWidth - nodeWidth : 0),
+        y: Math.min(y, maxY - nodeHeight),
+      };
+      y += nodeHeight + verticalGap;
+      return { ...node, position } as PositionedNode;
+    });
+  });
+};

package/src/layouts/radialTree.ts

@@ -0,0 +1,77 @@
+import { EdgeData, NodeData, PositionedNode } from '@graph-render/types';
+import { DEFAULT_NODE_GAP, DEFAULT_NODE_SIZE, DEFAULT_PADDING } from '../utils';
+import {
+  assertHierarchicalGraph,
+  assignNodesToLevels,
+  buildGraphTopology,
+  findRootNodes,
+  groupNodesByLevel,
+} from './treeTopology';
+import { centeredLayout } from './centered';
+
+export const radialTreeLayout = (
+  nodes: NodeData[],
+  edges: EdgeData[],
+  pad: number = DEFAULT_PADDING,
+  width: number = 960,
+  height: number = 720,
+  gap: number = DEFAULT_NODE_GAP
+): PositionedNode[] => {
+  if (!nodes.length) {
+    return [];
+  }
+
+  if (!edges.length) {
+    return centeredLayout(nodes, pad, width, height);
+  }
+
+  assertHierarchicalGraph(nodes, edges);
+
+  const { incoming, outgoing } = buildGraphTopology(edges);
+  const rootIds = findRootNodes(nodes, incoming);
+  const levelsMap = assignNodesToLevels(nodes, rootIds, outgoing);
+  const levels = groupNodesByLevel(nodes, levelsMap);
+  const centerX = width / 2;
+  const centerY = height / 2;
+  // FIX: use reduce instead of spread+Math.max to avoid a RangeError when the
+  // node array exceeds the JS engine's argument-count limit (~125 k in V8).
+  const maxNodeSize = nodes.reduce(
+    (max, node) =>
+      Math.max(
+        max,
+        node.size?.width ?? DEFAULT_NODE_SIZE.width,
+        node.size?.height ?? DEFAULT_NODE_SIZE.height
+      ),
+    0
+  );
+  const maxRadius = Math.max(0, Math.min(width, height) / 2 - pad - maxNodeSize / 2);
+  const radiusStep = levels.length > 1 ? maxRadius / (levels.length - 1) : 0;
+
+  // FIX: pre-build an id→node map to avoid an O(n) Array.find inside the
+  // levels.flatMap loop, which was O(n²) overall.
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+
+  return levels.flatMap((level, levelIndex) => {
+    const radius =
+      levelIndex === 0 ? 0 : Math.max(radiusStep * levelIndex, maxNodeSize + gap * 0.4);
+
+    return level.map((nodeId, nodeIndex) => {
+      const node = nodeById.get(nodeId) as NodeData;
+      const size = node.size ?? DEFAULT_NODE_SIZE;
+      const angle =
+        level.length === 1 ? -Math.PI / 2 : (2 * Math.PI * nodeIndex) / level.length - Math.PI / 2;
+      const position =
+        levelIndex === 0
+          ? { x: centerX - size.width / 2, y: centerY - size.height / 2 }
+          : {
+              x: centerX + radius * Math.cos(angle) - size.width / 2,
+              y: centerY + radius * Math.sin(angle) - size.height / 2,
+            };
+
+      return {
+        ...node,
+        position,
+      } as PositionedNode;
+    });
+  });
+};