@rokkit/graph 1.6.0 → 1.7.0

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;

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)