@rokkit/graph 1.6.0 → 1.8.0

package/dist/layout/hierarchy.d.ts

@@ -0,0 +1,42 @@
+import type { GraphModel } from '../types.js';
+export type Hierarchy = {
+    /** Nodes nothing calls, plus any disconnected node. In model order. */
+    roots: string[];
+    /** Hops from the nearest root. */
+    depthOf: Map<string, number>;
+    /** Tree children, in the order they were reached. */
+    childrenOf: Map<string, string[]>;
+    /** Childless nodes, in walk order — left to right around the rim. */
+    leaves: string[];
+    /** Ids of edges the tree could not use. Real relationships, drawn but not structural. */
+    extra: Set<string>;
+};
+/**
+ * A node's tree children — always an array.
+ *
+ * A childless node has no entry at all, and every caller wants an empty list rather than an
+ * `undefined` to guard. One place to say so beats the same `?? []` at each use site.
+ */
+export declare function childrenIn(h: Pick<Hierarchy, 'childrenOf'>, id: string): string[];
+/**
+ * One parent per node, and the edges that did not fit.
+ *
+ * Every node is placed: a disconnected one becomes its own root rather than disappearing, and
+ * a cycle terminates because a claimed node is never re-claimed.
+ */
+export type HierarchyOptions = {
+    /**
+     * Start the walk here instead of at the natural roots — what drilling into a crate does.
+     * A focus naming no node is ignored rather than blanking the canvas, because a stale drill
+     * target is a normal state after the data changes underneath it.
+     */
+    focus?: string | null;
+    /**
+     * How many levels to keep, counting the root as one. Everything deeper is dropped.
+     *
+     * The control that makes a large tree readable at all: a dendrogram over a whole codebase
+     * puts every leaf on one rim, each a fraction of a degree wide.
+     */
+    levels?: number;
+};
+export declare function hierarchy(model: GraphModel, options?: HierarchyOptions): Hierarchy;

package/dist/layout/hierarchy.js

@@ -0,0 +1,175 @@
+/* A spanning tree over a call graph, which is what a radial layout can actually draw.
+ *
+ * A call graph is not a tree and never was: a shared helper has several callers, and recursion
+ * makes cycles. Radial layouts need one parent per node, so this picks one — breadth-first, so
+ * a node sits at its SHORTEST distance from a root — and reports the edges it could not use.
+ *
+ * Those edges are reported rather than discarded. "b also calls this" is exactly the fact a
+ * reader is looking for in a call graph, and a tree that silently drops half its edges looks
+ * like a complete picture while being a quarter of one. The view draws them; they just do not
+ * define position.
+ */
+/**
+ * A node's tree children — always an array.
+ *
+ * A childless node has no entry at all, and every caller wants an empty list rather than an
+ * `undefined` to guard. One place to say so beats the same `?? []` at each use site.
+ */
+export function childrenIn(h, id) {
+    return h.childrenOf.get(id) ?? [];
+}
+/** An edge that can be a parent link: both ends are nodes, and it is not a self-loop. */
+function usable(edge, byId) {
+    return edge.source !== edge.target && byId.has(edge.source) && byId.has(edge.target);
+}
+function outgoing(edges) {
+    const out = new Map();
+    for (const edge of edges) {
+        const list = out.get(edge.source);
+        if (list)
+            list.push(edge);
+        else
+            out.set(edge.source, [edge]);
+    }
+    return out;
+}
+/**
+ * Where the walk starts: nodes nothing calls.
+ *
+ * A graph that is one big cycle has none, and rendering an empty canvas for a graph that
+ * plainly has nodes is the worse answer — so the first node in model order is drafted. Model
+ * order is fixed by normalisation, so the choice is stable.
+ */
+function rootsOf(model, links) {
+    const called = new Set(links.map((e) => e.target));
+    const roots = model.nodes.map((n) => n.id).filter((id) => !called.has(id));
+    if (roots.length > 0)
+        return roots;
+    return model.nodes.length > 0 ? [model.nodes[0].id] : [];
+}
+/** Every not-yet-claimed callee of `id`, claimed at `depth` and recorded as its children. */
+function claimChildren(id, depth, w) {
+    const taken = [];
+    for (const edge of w.out.get(id) ?? []) {
+        if (w.claimed.has(edge.target))
+            continue;
+        w.claimed.set(edge.target, depth);
+        taken.push(edge.target);
+    }
+    if (taken.length > 0)
+        w.childrenOf.set(id, [...(w.childrenOf.get(id) ?? []), ...taken]);
+    return taken;
+}
+/** Breadth-first, claiming each node once at its nearest depth. */
+function walk(roots, w) {
+    let frontier = roots.filter((id) => !w.claimed.has(id));
+    for (const id of frontier)
+        w.claimed.set(id, 0);
+    let depth = 0;
+    while (frontier.length > 0) {
+        depth++;
+        frontier = frontier.flatMap((id) => claimChildren(id, depth, w));
+    }
+}
+/**
+ * The node to re-root on, when there is one.
+ *
+ * A focus makes its subtree the whole picture — that is drilling. One naming no node is
+ * ignored rather than blanking the canvas: a stale drill target is a normal state once the
+ * data changes underneath it.
+ */
+function drillRoot(model, focus) {
+    return focus && model.byId.has(focus) ? focus : undefined;
+}
+/** Edge ids the spanning tree did not use as parent links. */
+function nonTreeEdges(links, childrenOf) {
+    const tree = new Set();
+    for (const [parent, kids] of childrenOf) {
+        for (const kid of kids)
+            tree.add(`${parent}->${kid}`);
+    }
+    return new Set(links.filter((e) => !tree.has(`${e.source}->${e.target}`)).map((e) => e.id));
+}
+/**
+ * Every node the natural roots could not reach, each seeding its own walk.
+ *
+ * A cycle nothing points into is unreachable from any root, and without this its members are
+ * simply absent from the diagram — which reads as missing DATA rather than as a layout choice.
+ */
+function sweepUnreached(model, w) {
+    const stragglers = [];
+    for (const node of model.nodes) {
+        if (w.claimed.has(node.id))
+            continue;
+        stragglers.push(node.id);
+        walk([node.id], w);
+    }
+    return stragglers;
+}
+/** Childless nodes in walk order, so a parent's children stay adjacent on the rim. */
+function leavesOf(roots, childrenOf) {
+    const leaves = [];
+    const visit = (id) => {
+        const kids = childrenIn({ childrenOf }, id);
+        if (kids.length === 0) {
+            leaves.push(id);
+            return;
+        }
+        for (const kid of kids)
+            visit(kid);
+    };
+    for (const root of roots)
+        visit(root);
+    return leaves;
+}
+/** Everything outside `levels` hops of the roots, pruned. */
+function prune(h, levels) {
+    const kept = new Set();
+    for (const [id, depth] of h.depthOf) {
+        if (depth < levels)
+            kept.add(id);
+    }
+    const childrenOf = new Map();
+    for (const [parent, kids] of h.childrenOf) {
+        if (!kept.has(parent))
+            continue;
+        const visible = kids.filter((kid) => kept.has(kid));
+        if (visible.length > 0)
+            childrenOf.set(parent, visible);
+    }
+    const roots = h.roots.filter((id) => kept.has(id));
+    return {
+        roots,
+        depthOf: new Map([...h.depthOf].filter(([id]) => kept.has(id))),
+        childrenOf,
+        leaves: leavesOf(roots, childrenOf),
+        extra: h.extra
+    };
+}
+export function hierarchy(model, options = {}) {
+    const links = model.edges.filter((e) => usable(e, model.byId));
+    const out = outgoing(links);
+    const claimed = new Map();
+    const childrenOf = new Map();
+    const focused = drillRoot(model, options.focus);
+    const roots = focused ? [focused] : rootsOf(model, links);
+    const w = { out, claimed, childrenOf };
+    walk(roots, w);
+    // A node inside a cycle that no root reaches is still a node. Each unclaimed one seeds its
+    // own walk, so the whole model is covered however tangled it is.
+    // Skipped entirely when a focus is set: drilling means "this subtree and nothing else", so
+    // sweeping up everything the focus cannot reach would undo the drill.
+    const stragglers = focused ? [] : sweepUnreached(model, w);
+    const allRoots = [...roots, ...stragglers];
+    const full = {
+        roots: allRoots,
+        depthOf: claimed,
+        childrenOf,
+        leaves: leavesOf(allRoots, childrenOf),
+        // An edge whose endpoints are not a parent/child pair in the tree. It is real and the
+        // view draws it; it simply did not get to decide where anything sits.
+        extra: nonTreeEdges(links, childrenOf)
+    };
+    const levels = options.levels;
+    return levels !== undefined && levels > 0 ? prune(full, levels) : full;
+}

package/dist/layout/index.d.ts

@@ -1,9 +1,15 @@
 import { cluster } from './cluster.js';
+import { flow } from './flow.js';
 import { neighborhood } from './neighborhood.js';
+import { world } from './world.js';
 import { points } from './points.js';
+import { radial } from './radial.js';
+import { structure } from './structure.js';
+import { sunburst } from './sunburst.js';
 import type { LayoutFn } from './types.js';
 /** Built-in layouts, addressable by name from `Graph`'s `layout` prop. */
 export declare const layouts: Record<string, LayoutFn>;
 export type LayoutName = keyof typeof layouts;
-export { cluster, neighborhood, points };
+export { cluster, flow, neighborhood, points, radial, structure, sunburst, world };
+export { LAYOUT_OPTIONS, appliesTo } from './options.js';
 export * from './types.js';

package/dist/layout/index.js

@@ -1,7 +1,13 @@
 import { cluster } from './cluster.js';
+import { flow } from './flow.js';
 import { neighborhood } from './neighborhood.js';
+import { world } from './world.js';
 import { points } from './points.js';
+import { radial } from './radial.js';
+import { structure } from './structure.js';
+import { sunburst } from './sunburst.js';
 /** Built-in layouts, addressable by name from `Graph`'s `layout` prop. */
-export const layouts = { cluster, neighborhood, points };
-export { cluster, neighborhood, points };
+export const layouts = { cluster, flow, neighborhood, points, radial, structure, sunburst, world };
+export { cluster, flow, neighborhood, points, radial, structure, sunburst, world };
+export { LAYOUT_OPTIONS, appliesTo } from './options.js';
 export * from './types.js';

package/dist/layout/matrix.d.ts

@@ -0,0 +1,38 @@
+import type { NodeAxis } from './types.js';
+import type { GraphModel } from '../types.js';
+export type MatrixCell = {
+    /** Index into `order` of the dependent (the edge's source). */
+    row: number;
+    /** Index into `order` of the dependency (the edge's target). */
+    col: number;
+    source: string;
+    target: string;
+    /** Edges folded into this cell — two FKs, a read and a write — each counted by its weight. */
+    count: number;
+    /** Against the grain: a cycle or a layer reaching up. */
+    above: boolean;
+};
+export type MatrixBlock = {
+    name: string;
+    start: number;
+    end: number;
+};
+export type Matrix = {
+    /** Node ids, providers first. Row i and column i are the same node. */
+    order: string[];
+    labels: string[];
+    /** Each node's group key on the grouping axis, parallel to `order` ('' when ungrouped). */
+    groups: string[];
+    cells: MatrixCell[];
+    /** Contiguous group runs along the diagonal. Empty when not grouping. */
+    blocks: MatrixBlock[];
+    /** Cells above the diagonal. */
+    above: number;
+    /** The largest `count`, for scaling cell intensity. */
+    maxCount: number;
+};
+export type MatrixOptions = {
+    /** Keep each group contiguous and outline it on the diagonal. Omit for one flat order. */
+    groupBy?: NodeAxis;
+};
+export declare function buildMatrix(model: GraphModel, options?: MatrixOptions): Matrix;

package/dist/layout/matrix.js

@@ -0,0 +1,90 @@
+/* The dependency structure matrix (DSM): every node is both a row and a column, and a cell at
+ * (row, col) says "row depends on col".
+ *
+ * Its strength is the ORDER. Providers come first, so in a layered architecture every
+ * dependency points up-and-left and the whole matrix is lower-triangular. A mark ABOVE the
+ * diagonal is then a dependency against the grain — a cycle, or a layer that reaches up —
+ * and it is visible at a glance at sizes where a node-link drawing is a hairball.
+ *
+ * The order reuses `flow`'s ranking (longest path, DFS cycle breaking), reversed: `rank` puts
+ * a target in a later column than its source, and a DSM wants the target FIRST. Grouping keeps
+ * each group contiguous, ordered by where its first member ranks, so a module's block sits on
+ * the diagonal and a cross-module dependency against the grain lands above it.
+ *
+ * Pure and DOM-free, like every layout.
+ */
+import { rank } from './rank.js';
+const axisOf = (node, axis) => (axis === 'kind' ? node.kind : node.group) ?? '';
+/** Node ids, providers first; with `groupBy`, each group contiguous in first-ranked order. */
+function orderNodes(model, groupBy) {
+    const { ranks } = rank(model);
+    // `rank` places every node, so each lookup hits; carrying the model index alongside the
+    // rank keeps ties in model order without a second map.
+    const byRank = model.nodes
+        .map((node, i) => ({ node, i, r: ranks.get(node.id) }))
+        .sort((a, b) => b.r - a.r || a.i - b.i)
+        .map((entry) => entry.node);
+    if (!groupBy)
+        return byRank;
+    const runs = new Map();
+    for (const node of byRank) {
+        const key = axisOf(node, groupBy);
+        const run = runs.get(key) ?? [];
+        run.push(node);
+        runs.set(key, run);
+    }
+    return [...runs.values()].flat();
+}
+function blocksOf(groups) {
+    const blocks = [];
+    groups.forEach((name, i) => {
+        const last = blocks[blocks.length - 1];
+        if (last && last.name === name)
+            last.end = i;
+        else
+            blocks.push({ name, start: i, end: i });
+    });
+    return blocks;
+}
+/** One cell per (dependent, dependency) pair, parallel edges folded into its count. */
+function collectCells(model, index) {
+    const cells = new Map();
+    for (const edge of model.edges) {
+        const row = index.get(edge.source);
+        const col = index.get(edge.target);
+        if (row === undefined || col === undefined || row === col)
+            continue;
+        const key = `${row}:${col}`;
+        // A weighted edge already IS a count — an import list aggregated to components says
+        // "7 imports" once rather than repeating the edge seven times.
+        const n = edge.weight ?? 1;
+        const cell = cells.get(key);
+        if (cell)
+            cell.count += n;
+        else
+            cells.set(key, {
+                row,
+                col,
+                source: edge.source,
+                target: edge.target,
+                count: n,
+                above: col > row
+            });
+    }
+    return [...cells.values()].sort((a, b) => a.row - b.row || a.col - b.col);
+}
+export function buildMatrix(model, options = {}) {
+    const nodes = orderNodes(model, options.groupBy);
+    const index = new Map(nodes.map((n, i) => [n.id, i]));
+    const cells = collectCells(model, index);
+    const groups = nodes.map((n) => (options.groupBy ? axisOf(n, options.groupBy) : ''));
+    return {
+        order: nodes.map((n) => n.id),
+        labels: nodes.map((n) => n.label),
+        groups,
+        cells,
+        blocks: options.groupBy ? blocksOf(groups) : [],
+        above: cells.filter((c) => c.above).length,
+        maxCount: Math.max(0, ...cells.map((c) => c.count))
+    };
+}

package/dist/layout/neighborhood.js

@@ -1,6 +1,10 @@
 /* Entity-centric layout: the focus node centred, nodes that reference it stacked on
    the left, nodes it references on the right.
 
+   EXACTLY ONE HOP, always. There is no depth option, and a caller passing one gets a warning
+   rather than silence (#162) — a two-hop view is a different picture with its own problems
+   (a hub explodes, and five columns need headings to be readable at all), not a parameter.
+
    Ported from dbd's EntityDiagram.svelte. That component carried its own geometry
    constants, buildCard, anchorY and path — roughly 100 lines duplicating cards.ts and
    edges.ts with slightly different numbers. Here it reuses both, so the duplication is
@@ -8,6 +12,8 @@
    +14 anchor nudge and 46px bow instead of EntityDiagram's +16 and 52px. */
 import { buildCards } from './cards.js';
 import { buildEdges } from './edges.js';
+import { warnUnknownOptions } from './options.js';
+import { rings } from './rings.js';
 import { CARD_W } from './constants.js';
 /* Local to this layout and deliberately NOT the cluster gaps in constants.ts: this is
    a three-column portrait, not a masonry grid, so it wants a wide horizontal gutter and
@@ -19,7 +25,23 @@ const MIN_H = 120;
 const H_PAD = 20;
 /** Extra width reserved to the right of the focus card for self-loop bows. */
 const LOOP_W = 60;
-const EMPTY = { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+const EMPTY = { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 }, columns: [] };
+/**
+ * Column headings, worded for the KIND of graph rather than configured.
+ *
+ * The same layout draws a call graph and an ER diagram, and "calls" is simply wrong for the
+ * latter. The model already knows which it is, so the wording follows the edges instead of
+ * asking the consumer to supply strings that must then be kept in step.
+ */
+function headings(dependency) {
+    return dependency
+        ? { in: ['called by', 'callers of callers'], out: ['calls', 'which call'] }
+        : { in: ['referenced by', 'their references'], out: ['references', 'which reference'] };
+}
+function headingFor(side, depth, dependency) {
+    const words = headings(dependency)[side];
+    return words[depth - 1] ?? `${words[0]} · ${depth} hops`;
+}
 function partition(model, focusId) {
     const byNeighbour = new Map();
     const selfEdges = [];
@@ -59,11 +81,15 @@ function referencedRows(neighbour) {
             names.add(edge.targetRow);
     return names;
 }
-/** Stack height of a column of cards, gaps between but not after. */
+/**
+ * Stack height of a column of cards — gaps between them, not after the last.
+ *
+ * Seeded at `-STACK_GAP` so the trailing gap cancels without a subtraction, and clamped at 0
+ * so an empty column is 0 rather than a negative height. No early return: the callers filter
+ * empty rings already, so a guard here would be a branch no test could reach.
+ */
 function stackHeight(cards) {
-    if (cards.length === 0)
-        return 0;
-    return cards.reduce((total, card) => total + card.h + STACK_GAP, 0) - STACK_GAP;
+    return Math.max(0, cards.reduce((total, card) => total + card.h + STACK_GAP, -STACK_GAP));
 }
 /** Place a column of cards at `x`, vertically centred within `height`. */
 function placeColumn(cards, x, height) {
@@ -85,6 +111,122 @@ function buildNeighbourCards(model, neighbours, expanded) {
         select: (row, node) => row.badges.includes('pk') || (wanted.get(node.id)?.has(row.name) ?? false)
     });
 }
+/**
+ * Place every ring, size the canvas, and name the columns.
+ *
+ * An EMPTY ring costs no width: a depth-2 request on a graph with nothing at depth 2 must not
+ * leave a gap where that column would have been, so the width is measured from the rightmost
+ * column that actually exists rather than from the depth asked for.
+ */
+function arrange(built, cards, ctx) {
+    const occupied = built.filter((r) => r.ids.length > 0);
+    const { focusX, xFor } = geometry(occupied);
+    const focusCard = cards[ctx.focus.id];
+    const height = placeRings(occupied, cards, { focusCard, focusX, xFor });
+    const columns = buildColumns(occupied, {
+        focusX,
+        focusLabel: ctx.focus.label,
+        xFor,
+        dependency: ctx.dependency
+    });
+    const width = xFor('out', furthest(occupied, 'out')) + CARD_W + (ctx.hasLoop ? LOOP_W : 0) + 4;
+    return { columns, size: { w: width, h: height } };
+}
+/**
+ * Which side ring 1 puts each neighbour on.
+ *
+ * The DOMINANT direction, not "has an out edge at all" (#160). A node with edges both ways is
+ * routine in a call graph — mutual recursion, a callback registered with its invoker, a
+ * visitor dispatching back into its walker — and testing `out.length > 0` put every one of
+ * them on the right, drawing its inbound edge right-to-left against the convention this
+ * layout states.
+ *
+ * One card per node is the constraint, so a TIE still draws one edge backwards whichever side
+ * wins. `in` is the deliberate pick: that column reads "things that reach this", which is what
+ * a reader scans for before changing something.
+ */
+function sideOf(neighbours) {
+    const outward = new Set(neighbours.filter((n) => n.out.length > n.in.length).map((n) => n.id));
+    return (id) => (outward.has(id) ? 'out' : 'in');
+}
+/**
+ * Edges with BOTH ends placed, rather than "touches the focus".
+ *
+ * At depth 1 those are the same set — everything on the canvas is a direct neighbour — so the
+ * one-hop picture is unchanged. At depth 2 they differ: an edge from ring 1 to ring 2 touches
+ * no focus, and showing it is exactly what the second ring is for.
+ */
+function drawableIn(model, cards) {
+    return model.edges.filter((e) => cards[e.source] !== undefined && cards[e.target] !== undefined);
+}
+/**
+ * Where each ring sits. Ring d on the `in` side is d steps left of the focus; on the `out`
+ * side, d steps right. The focus is pushed right by however deep the inbound side goes.
+ */
+function geometry(occupied) {
+    const columnStep = CARD_W + COL_GAP;
+    const focusX = furthest(occupied, 'in') * columnStep;
+    return {
+        focusX,
+        xFor: (side, d) => (side === 'in' ? focusX - d * columnStep : focusX + d * columnStep)
+    };
+}
+/**
+ * Cards for everything on the canvas.
+ *
+ * Three populations, three treatments: the focus shows up to 16 rows unfiltered, a direct
+ * neighbour shows its keys plus the rows the focus references, and a node further out shows
+ * keys only — at two hops the reader is tracing reach, not reading columns.
+ */
+function buildRingCards(model, neighbours, ring) {
+    const { placed, focus, expanded } = ring;
+    const direct = new Set(neighbours.map((n) => n.id));
+    return {
+        ...buildNeighbourCards(model, neighbours, expanded),
+        ...buildCards(placed.filter((n) => !direct.has(n.id)), 'keys', { expanded }),
+        ...buildCards([focus], 'full', { limit: 16, expanded })
+    };
+}
+/**
+ * Stack every ring into its column and centre the focus beside them. Returns the canvas
+ * height, which is the tallest stack — every column is vertically centred against it, so a
+ * short ring beside a long one reads as beside rather than above.
+ */
+function placeRings(occupied, cards, ctx) {
+    const stacks = occupied.map((ring) => ({
+        ring,
+        cards: ring.ids.map((id) => cards[id]).filter((c) => c !== undefined)
+    }));
+    const height = Math.max(ctx.focusCard.h, ...stacks.map((s) => stackHeight(s.cards)), MIN_H) + H_PAD;
+    for (const { ring, cards: column } of stacks) {
+        placeColumn(column, ctx.xFor(ring.side, ring.depth), height);
+    }
+    placeColumn([ctx.focusCard], ctx.focusX, height);
+    return height;
+}
+/** Deepest occupied ring on one side, or 0 when that side is empty. */
+function furthest(occupied, side) {
+    const depths = occupied.filter((r) => r.side === side).map((r) => r.depth);
+    return depths.length > 0 ? Math.max(...depths) : 0;
+}
+/** Headings left-to-right: inbound rings, the focus, then outbound rings. */
+function buildColumns(occupied, ctx) {
+    const side = (which) => occupied
+        .filter((r) => r.side === which)
+        .map((r) => ({
+        x: ctx.xFor(which, r.depth),
+        w: CARD_W,
+        depth: r.depth,
+        side: which,
+        label: headingFor(which, r.depth, ctx.dependency)
+    }))
+        .sort((a, b) => a.x - b.x);
+    return [
+        ...side('in'),
+        { x: ctx.focusX, w: CARD_W, depth: 0, side: 'focus', label: ctx.focusLabel },
+        ...side('out')
+    ];
+}
 /**
  * Entity-centric layout. `options.focus` names the node to centre; without it, or with
  * an id the model does not know, the result is empty.
@@ -93,31 +235,25 @@ function buildNeighbourCards(model, neighbours, expanded) {
  * the rows the focus references, capped at 8 — both caps carried over from dbd.
  */
 export const neighborhood = (model, options) => {
+    warnUnknownOptions(options, 'neighborhood');
     const focus = options.focus ? model.byId.get(options.focus) : undefined;
     if (!focus)
         return EMPTY;
     const { neighbours, selfEdges } = partition(model, focus.id);
-    const cards = {
-        ...buildNeighbourCards(model, neighbours, options.expanded),
-        ...buildCards([focus], 'full', { limit: 16, expanded: options.expanded })
-    };
-    const focusCard = cards[focus.id];
-    // A neighbour the focus points at sits right; one that points at the focus sits left.
-    const right = neighbours.filter((n) => n.out.length > 0).map((n) => cards[n.id]);
-    const left = neighbours.filter((n) => n.out.length === 0).map((n) => cards[n.id]);
-    const height = Math.max(focusCard.h, stackHeight(left), stackHeight(right), MIN_H) + H_PAD;
-    const hasRight = right.length > 0 || selfEdges.length > 0;
-    const focusX = left.length > 0 ? CARD_W + COL_GAP : 0;
-    placeColumn(left, 0, height);
-    placeColumn([focusCard], focusX, height);
-    placeColumn(right, focusX + CARD_W + COL_GAP, height);
-    const width = focusX +
-        CARD_W +
-        (hasRight ? COL_GAP + CARD_W : 0) +
-        (selfEdges.length > 0 ? LOOP_W : 0) +
-        4;
-    // Only edges touching the focus. buildEdges would otherwise connect two neighbours
-    // that happen to both be laid out, which this view never shows.
-    const touching = model.edges.filter((e) => e.source === focus.id || e.target === focus.id);
-    return { clusters: [], cards, edges: buildEdges(touching, cards), size: { w: width, h: height } };
+    const built = rings(model, focus.id, Math.max(1, Math.floor(options.depth ?? 1)), sideOf(neighbours));
+    const placedNodes = built
+        .flatMap((r) => r.ids)
+        .map((id) => model.byId.get(id))
+        .filter((n) => n !== undefined);
+    const cards = buildRingCards(model, neighbours, {
+        placed: placedNodes,
+        focus,
+        expanded: options.expanded
+    });
+    const { columns, size } = arrange(built, cards, {
+        focus,
+        hasLoop: selfEdges.length > 0,
+        dependency: model.edges.some((e) => e.kind === 'dependency')
+    });
+    return { clusters: [], cards, edges: buildEdges(drawableIn(model, cards), cards), size, columns };
 };

package/dist/layout/options.d.ts

@@ -0,0 +1,44 @@
+import type { LayoutOptions } from './types.js';
+/**
+ * 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 declare const LAYOUT_OPTION_KEYS: readonly ["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 declare const LAYOUT_OPTIONS: Record<string, readonly (typeof LAYOUT_OPTION_KEYS)[number][]>;
+/** `dot` or `card` — what shape this layout draws a node as. */
+export declare function nodeShapeOf(layout: string): 'dot' | 'card';
+/** Whether a control for `option` should be offered while `layout` is active. */
+export declare function appliesTo(layout: string, option: string): boolean;
+/**
+ * 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 declare function warnUnknownOptions(options: LayoutOptions, layout: string): void;
+/** Test seam — the dedupe is module state and would leak between cases otherwise. */
+export declare function resetOptionWarnings(): void;