@rokkit/graph 1.6.0 → 1.8.0

package/dist/layout/options.js

@@ -0,0 +1,106 @@
+/**
+ * Every key `LayoutOptions` defines. Kept beside the type on purpose — a key added there and
+ * missed here would warn about a legitimate option, which is worse than the silence this
+ * exists to fix. `spec/options.spec.ts` compares the two.
+ */
+export const LAYOUT_OPTION_KEYS = [
+    'density',
+    'arrange',
+    'edgeStyle',
+    'focus',
+    'expanded',
+    'groupBy',
+    'nestBy',
+    'sizeBy',
+    'sizeScale',
+    'depth',
+    'focusPath',
+    'levels',
+    'radialMode',
+    'root',
+    'bundleTension'
+];
+/**
+ * Which options have an EFFECT under each built-in layout.
+ *
+ * A control wired to an option the active layout ignores is worse than a missing one: it looks
+ * like a knob, it moves, and the picture does not change — so the reader concludes the view is
+ * broken rather than that the control does not apply. `names | keys | full` over a treemap is
+ * the plainest case, since a treemap box has no row list to thin.
+ *
+ * Exported because it is a fact about the layout, not about any one consumer's control panel.
+ * A hand-maintained copy in a UI drifts the first time a layout gains or drops an option.
+ *
+ * Two entries are not simply "what the layout function reads", and both are deliberate:
+ *   - `edgeStyle` is applied by `GraphState` when it draws a path, not by the layout. It
+ *     therefore applies wherever a layout produces edges — which `world` does not.
+ *   - `neighborhood` takes no `density`: it builds its cards at `full` unconditionally, because
+ *     a portrait of one node's surroundings that hides the columns the edges land on defeats
+ *     its own purpose.
+ */
+export const LAYOUT_OPTIONS = {
+    cluster: ['density', 'arrange', 'edgeStyle', 'expanded', 'groupBy', 'nestBy'],
+    flow: ['density', 'edgeStyle', 'expanded'],
+    neighborhood: ['edgeStyle', 'expanded', 'focus', 'depth'],
+    points: ['edgeStyle', 'sizeBy', 'sizeScale'],
+    radial: ['edgeStyle', 'sizeBy', 'sizeScale', 'radialMode', 'levels', 'root'],
+    sunburst: ['sizeBy', 'focusPath', 'levels'],
+    structure: ['sizeBy', 'sizeScale', 'focusPath', 'levels', 'bundleTension'],
+    world: ['sizeBy', 'focusPath', 'levels']
+};
+/**
+ * Layouts that draw a node as a DOT rather than a card.
+ *
+ * A card is the wrong unit once a node is 20px across: the head, the kind tag and the
+ * more-row are all still in the DOM, overflowing a box the layout sized for a dot. Published
+ * as a fact about the layout so the theme can key on the SHAPE instead of naming every layout
+ * that happens to have one — `radial` inherited the whole dot treatment by joining this set.
+ */
+const DOT_LAYOUTS = new Set(['points', 'radial', 'structure']);
+/** `dot` or `card` — what shape this layout draws a node as. */
+export function nodeShapeOf(layout) {
+    return DOT_LAYOUTS.has(layout) ? 'dot' : 'card';
+}
+/** Whether a control for `option` should be offered while `layout` is active. */
+export function appliesTo(layout, option) {
+    return LAYOUT_OPTIONS[layout]?.includes(option) ?? true;
+}
+/** Warn once per unknown key, ever. A layout re-runs on every render. */
+const warned = new Set();
+/** Bundlers replace this; `process` is undefined in a browser, hence the guarded read. */
+function isProduction() {
+    return typeof process !== 'undefined' && process.env?.NODE_ENV === 'production';
+}
+/**
+ * Tell a caller when an option was discarded.
+ *
+ * `LayoutOptions` is not a closed check once the object reaches a layout through a variable —
+ * TypeScript's excess-property check only fires on an object literal at the call site. So
+ * `neighborhood(model, opts)` where `opts` carries `depth: 2` type-checks, runs, and returns
+ * a correct-looking diagram that silently ignored the option (#162).
+ *
+ * Silence is the problem, not the unknown key: the caller has no way to tell "this layout
+ * does not support depth" from "depth worked and two hops is what you are looking at".
+ */
+export function warnUnknownOptions(options, layout) {
+    if (isProduction())
+        return;
+    for (const key of Object.keys(options)) {
+        if (LAYOUT_OPTION_KEYS.includes(key))
+            continue;
+        const seen = `${layout}:${key}`;
+        if (warned.has(seen))
+            continue;
+        warned.add(seen);
+        // The one place a console call is the POINT rather than a leftover: a discarded option
+        // has no other channel back to the caller, and throwing would make an unknown key fatal
+        // for a diagram that still renders correctly. Dev-only and deduped above.
+        // eslint-disable-next-line no-console
+        console.warn(`[@rokkit/graph] \`${layout}\` received unknown option \`${key}\` and ignored it. ` +
+            `Known options: ${LAYOUT_OPTION_KEYS.join(', ')}.`);
+    }
+}
+/** Test seam — the dedupe is module state and would leak between cases otherwise. */
+export function resetOptionWarnings() {
+    warned.clear();
+}

package/dist/layout/order.d.ts

@@ -0,0 +1,11 @@
+import type { GraphModel } from '../types.js';
+/**
+ * Crossings between every adjacent pair of layers.
+ *
+ * Two edges cross when their endpoints are in opposite relative order on the two sides. The
+ * naive pair-count is fine here: a layer holds tens of nodes, not thousands, and being
+ * obviously correct matters more than being O(n log n) — this is the score the sweep is
+ * optimising, so an error in it would silently make the heuristic choose the worse layout.
+ */
+export declare function countCrossings(layers: string[][], model: GraphModel, back: Set<string>): number;
+export declare function order(model: GraphModel, ranks: Map<string, number>, back: Set<string>): string[][];

package/dist/layout/order.js

@@ -0,0 +1,153 @@
+/* Ordering within a column — the crossing-reduction half of a layered layout.
+ *
+ * Minimising edge crossings is NP-hard, so this is the standard heuristic: sweep the layers
+ * assigning each node the average position of its neighbours in the adjacent layer, sort by
+ * that, repeat. See docs/design/25-flow-layout.md.
+ *
+ * Two properties are load-bearing and neither is incidental:
+ *
+ *   - It is DETERMINISTIC. A fixed pass count and a stable tie-break, so the same model lays
+ *     out identically every run — which `LayoutFn` promises and every layout spec relies on.
+ *   - It never returns worse than it started. Each candidate is scored and the best kept, so
+ *     a graph the heuristic cannot improve comes back unchanged rather than churned.
+ */
+/** Sweeps of down-then-up. Four is where the standard heuristic stops paying. */
+const PASSES = 4;
+/** An edge that is actually drawn between two adjacent columns. */
+function drawn(edges, back, byId) {
+    return edges.filter((e) => !back.has(e.id) && e.source !== e.target && byId.has(e.source) && byId.has(e.target));
+}
+/**
+ * Crossings between every adjacent pair of layers.
+ *
+ * Two edges cross when their endpoints are in opposite relative order on the two sides. The
+ * naive pair-count is fine here: a layer holds tens of nodes, not thousands, and being
+ * obviously correct matters more than being O(n log n) — this is the score the sweep is
+ * optimising, so an error in it would silently make the heuristic choose the worse layout.
+ */
+export function countCrossings(layers, model, back) {
+    const pos = new Map();
+    layers.forEach((layer) => layer.forEach((id, i) => pos.set(id, i)));
+    const layerOf = new Map();
+    layers.forEach((layer, i) => layer.forEach((id) => layerOf.set(id, i)));
+    let total = 0;
+    const edges = drawn(model.edges, back, model.byId);
+    for (let i = 0; i < edges.length; i++) {
+        for (let j = i + 1; j < edges.length; j++) {
+            const a = edges[i];
+            const b = edges[j];
+            // Only edges spanning the SAME pair of adjacent layers can cross in this model.
+            if (layerOf.get(a.source) !== layerOf.get(b.source))
+                continue;
+            if (layerOf.get(a.target) !== layerOf.get(b.target))
+                continue;
+            const as = pos.get(a.source);
+            const bs = pos.get(b.source);
+            const at = pos.get(a.target);
+            const bt = pos.get(b.target);
+            if ((as - bs) * (at - bt) < 0)
+                total++;
+        }
+    }
+    return total;
+}
+/** Mean position of `ids` in the previous ordering, or nothing when there are none. */
+function barycenter(ids, pos) {
+    const known = ids.map((id) => pos.get(id)).filter((p) => p !== undefined);
+    if (known.length === 0)
+        return undefined;
+    return known.reduce((sum, p) => sum + p, 0) / known.length;
+}
+/**
+ * Re-sort one layer by the average position of each node's neighbours on `side`.
+ *
+ * A node with no neighbour on that side keeps its current index as its key, so it holds
+ * station instead of collapsing to one end — an unconstrained node drifting to position 0 is
+ * how a sweep makes a layout worse than the order it was given.
+ */
+function sweepLayer(layer, neighbors, pos) {
+    const keyed = layer.map((id, i) => ({
+        id,
+        key: barycenter(neighbors.get(id) ?? [], pos) ?? i,
+        i
+    }));
+    // Index breaks ties, so equal barycenters keep their relative order — a stable sort by
+    // hand, because the tie-break IS the determinism guarantee.
+    keyed.sort((a, b) => a.key - b.key || a.i - b.i);
+    return keyed.map((k) => k.id);
+}
+/** Positions within each layer, for the scoring pass and the next sweep. */
+function positions(layers) {
+    const pos = new Map();
+    layers.forEach((layer) => layer.forEach((id, i) => pos.set(id, i)));
+    return pos;
+}
+function adjacency(edges, forward) {
+    const out = new Map();
+    for (const edge of edges) {
+        const [from, to] = forward ? [edge.target, edge.source] : [edge.source, edge.target];
+        const list = out.get(from);
+        if (list)
+            list.push(to);
+        else
+            out.set(from, [to]);
+    }
+    return out;
+}
+/**
+ * Nodes grouped into their columns and ordered to reduce crossings.
+ *
+ * Layers start in model order — which normalisation fixed — so the starting point is stable
+ * and the result is reproducible.
+ */
+/** Nodes bucketed into their columns, in model order — the stable starting arrangement. */
+function layersOf(model, ranks) {
+    const layers = [];
+    for (const node of model.nodes) {
+        const r = ranks.get(node.id) ?? 0;
+        (layers[r] ??= []).push(node.id);
+    }
+    // A rank with no nodes cannot come out of `rank()`, but an array hole would crash the
+    // sweep rather than lay out oddly, and the cost of not assuming is one filter.
+    return layers.filter((layer) => layer !== undefined);
+}
+/**
+ * One sweep across every layer.
+ *
+ * Down means each layer follows the one to its left, up means the one to its right.
+ * Alternating is what lets an improvement propagate in both directions rather than piling up
+ * against whichever end the sweep started from.
+ */
+function sweep(layers, down, predecessors, successors) {
+    const next = layers.map((layer) => [...layer]);
+    const indices = down
+        ? next.map((_, i) => i).slice(1)
+        : next
+            .map((_, i) => i)
+            .slice(0, -1)
+            .reverse();
+    for (const i of indices) {
+        next[i] = sweepLayer(next[i], down ? predecessors : successors, positions(next));
+    }
+    return next;
+}
+export function order(model, ranks, back) {
+    const filled = layersOf(model, ranks);
+    if (filled.length === 0)
+        return [];
+    const edges = drawn(model.edges, back, model.byId);
+    const predecessors = adjacency(edges, true);
+    const successors = adjacency(edges, false);
+    let best = filled;
+    let bestScore = countCrossings(filled, model, back);
+    let current = filled;
+    for (let pass = 0; pass < PASSES; pass++) {
+        current = sweep(current, pass % 2 === 0, predecessors, successors);
+        const score = countCrossings(current, model, back);
+        if (score < bestScore) {
+            bestScore = score;
+            best = current;
+        }
+    }
+    return best;
+}

package/dist/layout/points.js

@@ -28,16 +28,20 @@
    seed. The same model always produces the same picture, so it is unit-testable to exact
    pixels and a re-render never reshuffles the diagram under the reader. */
 import { buildEdges } from './edges.js';
+import { degreeOf, measureOf, normalise, sizeFor } from './sizing.js';
+import { warnUnknownOptions } from './options.js';
+/* Node geometry — area, aspect and the measure curve now live in `sizing.ts`, shared with
+   `radial`, so the same node is the same size in both views. */
+const NODE_GAP = 6;
 /**
- * Node geometry. AREA — not width — tracks degree, so ten edges reads as ten rather than as
- * a hundred. Areas are carried over from the disc version (pi*5^2 to pi*26^2) so the ink
- * weight of a diagram is unchanged; only the shape and the packing are different.
+ * Vertical allowance under each node for its label.
+ *
+ * The label is drawn BELOW the dot and outside it — at these sizes there is no inside to put
+ * text in — so the shelf has to reserve for it or a 6px dot's 19px label lands in the row
+ * beneath. Reserved unconditionally: at the `minimal` and `dot` tiers the label is hidden and
+ * this is simply air, which costs a little density in exchange for never colliding.
  */
-const MIN_AREA = Math.PI * 5 * 5;
-const MAX_AREA = Math.PI * 26 * 26;
-/** Width:height. 2:1 reads as a "chip" and shelves well; a square wastes shelf height. */
-const ASPECT = 2;
-const NODE_GAP = 6;
+const LABEL_H = 18;
 const CLUSTER_PAD = 20;
 /** Room for the group's own label above its first shelf. */
 const CLUSTER_TITLE = 26;
@@ -49,24 +53,6 @@ const CANVAS_PAD = 60;
  * grid of groups better than a tall column.
  */
 const SHELF_ASPECT = 1.6;
-function degreeOf(model) {
-    const degree = new Map();
-    for (const node of model.nodes)
-        degree.set(node.id, 0);
-    for (const edge of model.edges) {
-        degree.set(edge.source, (degree.get(edge.source) ?? 0) + 1);
-        if (edge.target !== edge.source) {
-            degree.set(edge.target, (degree.get(edge.target) ?? 0) + 1);
-        }
-    }
-    return degree;
-}
-/** Size by degree. Area is linear in degree, so width grows as its square root. */
-function sizeFor(degree, maxDegree) {
-    const t = maxDegree <= 0 ? 0 : degree / maxDegree;
-    const area = MIN_AREA + (MAX_AREA - MIN_AREA) * t;
-    return { w: Math.sqrt(area * ASPECT), h: Math.sqrt(area / ASPECT) };
-}
 /**
  * Shelf-pack one group (first-fit decreasing height).
  *
@@ -78,7 +64,7 @@ function sizeFor(degree, maxDegree) {
  */
 function packGroup(members) {
     const ordered = [...members].sort((a, b) => b.h - a.h || b.w - a.w || a.node.id.localeCompare(b.node.id));
-    const ink = ordered.reduce((sum, m) => sum + (m.w + NODE_GAP) * (m.h + NODE_GAP), 0);
+    const ink = ordered.reduce((sum, m) => sum + (m.w + NODE_GAP) * (m.h + LABEL_H + NODE_GAP), 0);
     // At least one node wide, or a single oversized hub would wrap onto its own shelf forever.
     const limit = Math.max(ordered[0].w, Math.sqrt(ink * SHELF_ASPECT));
     const nodes = [];
@@ -94,7 +80,8 @@ function packGroup(members) {
         }
         nodes.push({ ...member, dx: x + member.w / 2, dy: y + member.h / 2 });
         x += member.w + NODE_GAP;
-        shelfHeight = Math.max(shelfHeight, member.h);
+        // The SHELF is as tall as the node plus its label; the node itself is not.
+        shelfHeight = Math.max(shelfHeight, member.h + LABEL_H);
         widest = Math.max(widest, x - NODE_GAP);
     }
     return { nodes, w: widest, h: y + shelfHeight };
@@ -135,17 +122,21 @@ function placeGroups(packs) {
     });
     return clusters;
 }
-/** Nodes bucketed by group, each carrying the size its degree earns it. */
-function sizeByGroup(model) {
+/** Nodes bucketed by group, each carrying the size its measure earns it. */
+function sizeByGroup(model, sizeBy, scale) {
     const degree = degreeOf(model);
-    const maxDegree = Math.max(0, ...degree.values());
+    const measures = model.nodes.map((n) => measureOf(n, degree, sizeBy));
+    // Normalised against the range PRESENT, not against zero: a graph whose smallest module
+    // holds 400 declarations should still show its internal spread, not one flat block.
+    const min = Math.min(0, ...measures);
+    const max = Math.max(0, ...measures);
     const byGroup = new Map();
-    for (const node of model.nodes) {
+    model.nodes.forEach((node, i) => {
         const key = node.group ?? '';
         const list = byGroup.get(key) ?? [];
-        list.push({ node, ...sizeFor(degree.get(node.id) ?? 0, maxDegree) });
+        list.push({ node, ...sizeFor(normalise(measures[i], min, max, scale)) });
         byGroup.set(key, list);
-    }
+    });
     return byGroup;
 }
 /** One rect card for a placed node. `pos` holds the CENTRE; a card is positioned top-left. */
@@ -179,10 +170,11 @@ function buildDots(model, clusters, sizeOf) {
  * `arrange` is ignored because placement is fully determined by degree and group.
  */
 export const points = (model, _options) => {
+    warnUnknownOptions(_options, 'points');
     if (model.nodes.length === 0) {
         return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
     }
-    const byGroup = sizeByGroup(model);
+    const byGroup = sizeByGroup(model, _options.sizeBy ?? 'degree', _options.sizeScale ?? 'linear');
     const packs = [...byGroup.entries()].map(([name, members]) => ({
         name,
         pack: packGroup(members)

package/dist/layout/radial.d.ts

@@ -0,0 +1,16 @@
+import type { LayoutFn } from './types.js';
+/**
+ * A map read with a floor.
+ *
+ * Every pass below keys on the same node set, so a miss should not happen — but a node
+ * rendered at NaN coordinates disappears silently, and one rendered at the centre is at least
+ * visible and clickable. One helper rather than a `??` at each of three use sites.
+ */
+export declare function read<T>(map: Map<string, T>, id: string, fallback: T): T;
+/**
+ * A call graph around a circle.
+ *
+ * No clusters: the rings already carry structure, and a group box drawn over a radial
+ * arrangement cuts across every one of them.
+ */
+export declare const radial: LayoutFn;

package/dist/layout/radial.js

@@ -0,0 +1,214 @@
+/* The radial layout: a call graph as a tidy tree, or a dendrogram, around a circle.
+ *
+ * `points` shelf-packs a call graph into group boxes, and at seven services it already reads
+ * as a stack — tiny rects with each label colliding with the row beneath. Packing answers
+ * "how much is there"; a call graph's question is "who calls whom, and how deep does it go",
+ * and that is a SHAPE. Angle separates the subtrees, radius carries the depth.
+ *
+ * Two modes, because they answer different questions:
+ *   - `tree` (default) puts radius = depth, so the rings ARE the call depth.
+ *   - `dendrogram` puts every leaf on the rim, so leaves are compared against each other and
+ *     the internal structure stretches to reach them.
+ *
+ * A call graph is not a tree — see `hierarchy.ts`. The spanning tree decides position; the
+ * edges it could not use are still drawn, marked `back`, because "b also calls this" is
+ * exactly what a reader is looking for.
+ */
+import { childrenIn, hierarchy } from './hierarchy.js';
+import { nodeSizes } from './sizing.js';
+import { warnUnknownOptions } from './options.js';
+/** Gap between rings. Wide enough that a node plus its label clears the ring inside it. */
+const RING = 130;
+/** Arc length reserved per leaf. The outer ring's circumference is derived from this. */
+const LEAF_ARC = 92;
+/**
+ * Margin outside the widest ring.
+ *
+ * Just over half the largest node (sqrt(MAX_AREA * ASPECT) / 2 is ~33px), so a node on the rim
+ * clears the canvas edge with a little air for its label — and no more. Every pixel here is
+ * dead space that the fit-to-container scale then divides the whole diagram by.
+ */
+const PAD = 48;
+/**
+ * A map read with a floor.
+ *
+ * Every pass below keys on the same node set, so a miss should not happen — but a node
+ * rendered at NaN coordinates disappears silently, and one rendered at the centre is at least
+ * visible and clickable. One helper rather than a `??` at each of three use sites.
+ */
+export function read(map, id, fallback) {
+    return map.get(id) ?? fallback;
+}
+/**
+ * One angular slot per leaf, then every parent centred on its children.
+ *
+ * Centring is the "tidy" part: without it a parent sits at a fixed slot and its links cross
+ * the neighbouring subtrees to reach their own children. Computed bottom-up, so a parent sees
+ * children that are already placed.
+ */
+function angles(h, step) {
+    const angle = new Map();
+    h.leaves.forEach((id, i) => angle.set(id, i * step));
+    const place = (id) => {
+        const cached = angle.get(id);
+        if (cached !== undefined)
+            return cached;
+        const kids = childrenIn(h, id);
+        const mean = kids.reduce((sum, kid) => sum + place(kid), 0) / kids.length;
+        angle.set(id, mean);
+        return mean;
+    };
+    for (const root of h.roots)
+        place(root);
+    return angle;
+}
+/**
+ * How far out each node sits.
+ *
+ * `tree` reads radius as depth. `dendrogram` pins leaves to the outermost ring and lifts an
+ * internal node to just inside its deepest descendant, which is what makes leaves comparable.
+ */
+function radii(h, mode, maxDepth) {
+    const radius = new Map();
+    if (mode === 'tree') {
+        for (const [id, depth] of h.depthOf)
+            radius.set(id, depth * RING);
+        return radius;
+    }
+    // Deepest descendant, bottom-up: a leaf is its own, and a parent sits one ring inside its
+    // deepest child so the tree still reads outward.
+    const deepest = (id) => {
+        const kids = childrenIn(h, id);
+        if (kids.length === 0)
+            return maxDepth;
+        return Math.min(...kids.map((kid) => deepest(kid))) - 1;
+    };
+    for (const id of h.depthOf.keys())
+        radius.set(id, Math.max(0, deepest(id)) * RING);
+    return radius;
+}
+/**
+ * The circle the tree has to fit in.
+ *
+ * The rim's circumference has to hold every leaf plus its label, so it follows from the LEAF
+ * COUNT rather than dividing a fixed circle into ever-thinner slices — which is how a radial
+ * layout turns into the same unreadable stack it was meant to replace.
+ */
+function geometry(h) {
+    const leafCount = Math.max(1, h.leaves.length);
+    const maxDepth = Math.max(0, ...h.depthOf.values());
+    const outer = Math.max(RING, (LEAF_ARC * leafCount) / (Math.PI * 2));
+    return {
+        step: (Math.PI * 2) / leafCount,
+        maxDepth,
+        outer,
+        // Rings spaced to reach the rim the leaf count demands, so a wide tree spreads rather
+        // than piling every level on top of the last.
+        spacing: maxDepth > 0 ? outer / maxDepth : 0,
+        extent: outer + PAD
+    };
+}
+/** Centre-out placement, converted to top-left card coordinates. */
+function place(h, sizeOf, mode, model) {
+    const { step, maxDepth, spacing, extent } = geometry(h);
+    const angle = angles(h, step);
+    const radius = radii(h, mode, maxDepth);
+    const cards = {};
+    for (const node of model.nodes) {
+        // Only what the hierarchy materialised. A pruned node has no angle and no radius, and
+        // placing it anyway would stack every dropped node on the centre point.
+        if (!h.depthOf.has(node.id))
+            continue;
+        const size = read(sizeOf, node.id, { w: 1, h: 1 });
+        const r = (read(radius, node.id, 0) / RING) * spacing;
+        const a = read(angle, node.id, 0);
+        cards[node.id] = {
+            node,
+            vis: [],
+            more: node.rows.length,
+            w: size.w,
+            h: size.h,
+            x: extent + Math.cos(a) * r - size.w / 2,
+            y: extent + Math.sin(a) * r - size.h / 2,
+            groupIndex: 0
+        };
+    }
+    return { cards, size: { w: extent * 2, h: extent * 2 } };
+}
+/** Identity half of a routed edge — everything that is not geometry. */
+function identity(edge, i) {
+    return {
+        i,
+        id: edge.id,
+        fromKey: edge.source,
+        toKey: edge.target,
+        kind: edge.kind,
+        relation: edge.relation
+    };
+}
+/**
+ * Centre-to-centre links.
+ *
+ * `s1`/`s2` are derived from which way the link actually points rather than fixed: on a circle
+ * "the right side" is meaningless, and a curve control point pushed the wrong way loops back
+ * through the node it came from.
+ */
+function route(edge, i, cards, extra) {
+    const a = cards[edge.source];
+    const b = cards[edge.target];
+    if (!a || !b)
+        return null;
+    const [ax, ay] = [a.x + a.w / 2, a.y + a.h / 2];
+    const [bx, by] = [b.x + b.w / 2, b.y + b.h / 2];
+    if (a === b) {
+        return {
+            ...identity(edge, i),
+            self: true,
+            x1: a.x + a.w,
+            y1: ay,
+            x2: a.x + a.w,
+            y2: ay + 14,
+            s1: 1,
+            s2: 1
+        };
+    }
+    return {
+        ...identity(edge, i),
+        // Not a broken cycle here but the same idea: a relationship the tree could not express,
+        // still drawn. A theme distinguishes it rather than the reader wondering why one link
+        // ignores the rings.
+        back: extra.has(edge.id) || undefined,
+        self: false,
+        x1: ax,
+        y1: ay,
+        x2: bx,
+        y2: by,
+        s1: bx >= ax ? 1 : -1,
+        s2: bx >= ax ? -1 : 1
+    };
+}
+function routeAll(model, cards, extra) {
+    const routed = [];
+    model.edges.forEach((edge, i) => {
+        const e = route(edge, i, cards, extra);
+        if (e)
+            routed.push(e);
+    });
+    return routed;
+}
+/**
+ * A call graph around a circle.
+ *
+ * No clusters: the rings already carry structure, and a group box drawn over a radial
+ * arrangement cuts across every one of them.
+ */
+export const radial = (model, options) => {
+    warnUnknownOptions(options, 'radial');
+    if (model.nodes.length === 0) {
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    }
+    const h = hierarchy(model, { focus: options.root, levels: options.levels });
+    const sizeOf = nodeSizes(model, options.sizeBy ?? 'degree', options.sizeScale ?? 'linear');
+    const { cards, size } = place(h, sizeOf, options.radialMode ?? 'tree', model);
+    return { clusters: [], cards, edges: routeAll(model, cards, h.extra), size };
+};

package/dist/layout/rank.d.ts

@@ -0,0 +1,15 @@
+import type { GraphModel } from '../types.js';
+export type Ranking = {
+    /** Node id → column index, 0-based. Every node in the model is present. */
+    ranks: Map<string, number>;
+    /** Ids of the edges reversed to make the graph acyclic. */
+    back: Set<string>;
+};
+/**
+ * Columns for every node, and the edges broken to get them.
+ *
+ * A node constrained by nothing — disconnected, or reached only by a broken edge — ranks 0 and
+ * still gets a box. Dropping it would hide a table from the diagram because of how it happens
+ * to be referenced.
+ */
+export declare function rank(model: GraphModel): Ranking;