@rokkit/graph 1.6.0

package/dist/layout/clusters.js

@@ -0,0 +1,217 @@
+/* ============================================================
+   Cluster building, ordering, packing, flow — the core of the layout
+   algorithm. Groups become clusters, clusters are ordered to minimise edge
+   crossings, and each cluster's nodes are masonry-packed then flowed into
+   wrapping rows.
+
+   Ported from dbd's layout-clusters.ts. The geometry is unchanged; only the
+   model shape moved (LayoutData -> GraphNode[]/GraphEdge[]) and `hue` became
+   `groupIndex`, because colour now comes from CSS and the preset.
+   ============================================================ */
+import { CARD_W, GAP_X, GAP_Y, CL_PAD, CL_TITLE, CL_GAP_X, CL_GAP_Y, MAX_ROW_W } from './constants.js';
+/**
+ * Group nodes by an axis. A node with no value on it files under ''.
+ *
+ * `axis` defaults to `group`, so every existing caller — and the ported characterization
+ * tests — keep their exact behaviour. It exists because the single-axis case is NOT a special
+ * case of nesting: `groupBy: 'kind'` with no `nestBy` has to regroup the flat layout too, and
+ * without it the control moved while the picture did not.
+ */
+export function groupByGroup(nodes, axis = 'group') {
+    const byGroup = {};
+    for (const node of nodes) {
+        const key = (axis === 'kind' ? node.kind : node.group) ?? '';
+        (byGroup[key] = byGroup[key] || []).push(node);
+    }
+    return byGroup;
+}
+/**
+ * Undirected node adjacency (cross-node edges) for barycenter ordering.
+ *
+ * Pushes once PER EDGE, so two edges between the same pair list the neighbour
+ * twice. That is deliberate: `barycenter` divides by the array length, so a
+ * twice-referenced neighbour is weighted 2x and pulls the node twice as hard.
+ * Two FKs to one table is routine (`orders.created_by` and `orders.approved_by`
+ * both -> `users.id`), so collapsing this to a Set would silently relayout every
+ * multi-FK schema.
+ *
+ * `GraphModel.neighbors` is a Set and stays one — it answers "is X related to Y",
+ * where multiplicity is meaningless. This answers "how strongly is X pulled
+ * toward Y", where multiplicity is the whole point. Different questions.
+ */
+export function buildAdjacency(edges) {
+    const nbrs = new Map();
+    const link = (a, b) => {
+        const list = nbrs.get(a) ?? [];
+        list.push(b);
+        nbrs.set(a, list);
+    };
+    for (const edge of edges) {
+        // An unplaced endpoint has no card, and `barycenter` reads a card's y to average
+        // positions — so including one crashes on the lookup. The relationship is real and
+        // still in the model; it simply has no POSITION to contribute.
+        if (edge.unplaced || edge.source === edge.target)
+            continue;
+        link(edge.source, edge.target);
+        link(edge.target, edge.source);
+    }
+    return nbrs;
+}
+/** One cluster per group; groupIndex assigned by alphabetical position (stable across arranges). */
+export function buildClusters(byGroup) {
+    return Object.keys(byGroup)
+        .sort()
+        .map((name, i) => ({
+        name,
+        list: byGroup[name].slice().sort((a, b) => a.label.localeCompare(b.label)),
+        count: byGroup[name].length,
+        groupIndex: i,
+        x: 0,
+        y: 0
+    }));
+}
+/** Index of the shortest column so far (first one wins on a tie). */
+function shortestColumn(colH) {
+    let ci = 0;
+    for (let i = 1; i < colH.length; i++)
+        if (colH[i] < colH[ci])
+            ci = i;
+    return ci;
+}
+/** Masonry-pack one cluster from its current list order (sets c.pos/w/h). */
+export function pack(c, cards) {
+    const n = c.list.length;
+    const ncols = Math.max(1, Math.min(6, Math.round(Math.sqrt(n * 1.15))));
+    const colH = new Array(ncols).fill(0);
+    c.pos = [];
+    for (const node of c.list) {
+        const card = cards[node.id];
+        const ci = shortestColumn(colH);
+        c.pos.push({ key: node.id, dx: ci * (CARD_W + GAP_X), dy: colH[ci] });
+        colH[ci] += card.h + GAP_Y;
+    }
+    c.w = ncols * CARD_W + (ncols - 1) * GAP_X + CL_PAD * 2;
+    c.h = Math.max(...colH) - GAP_Y + CL_PAD * 2 + CL_TITLE;
+}
+const byArea = (a, b) => (b.w ?? 0) * (b.h ?? 0) - (a.w ?? 0) * (a.h ?? 0);
+/**
+ * Count inter-group edge links (symmetric), keyed 'groupA|groupB'.
+ *
+ * Groups come from the model's `byId` rather than from splitting the node id: an
+ * id is opaque once the normalizer has built it, and re-parsing it into parts is
+ * exactly the coupling the canonical model removes.
+ */
+function bumpLink(links, a, b) {
+    links[`${a}|${b}`] = (links[`${a}|${b}`] || 0) + 1;
+}
+function countGroupLinks(model) {
+    const links = {};
+    for (const edge of model.edges) {
+        const from = model.byId.get(edge.source)?.group;
+        const to = model.byId.get(edge.target)?.group;
+        if (from === undefined || to === undefined || from === to)
+            continue;
+        bumpLink(links, from, to);
+        bumpLink(links, to, from);
+    }
+    return links;
+}
+/** Remove + return the `left` cluster most strongly linked to the already-`ordered` ones. */
+function pickNextLinked(left, ordered, links) {
+    const lk = (a, b) => links[`${a.name}|${b.name}`] || 0;
+    let best = 0;
+    let bestScore = -1;
+    for (let i = 0; i < left.length; i++) {
+        let score = 0;
+        for (let j = 0; j < ordered.length; j++)
+            score += lk(left[i], ordered[j]) * (j + 1);
+        if (score > bestScore) {
+            bestScore = score;
+            best = i;
+        }
+    }
+    return left.splice(best, 1)[0];
+}
+/**
+ * Order clusters. 'untangle' greedily chains groups so heavily-linked ones stay
+ * adjacent (seeded by the largest cluster); otherwise sort by area, biggest first.
+ */
+export function orderClusters(clusters, model, arrange) {
+    if (arrange !== 'untangle' || clusters.length <= 1) {
+        return clusters.sort(byArea);
+    }
+    const links = countGroupLinks(model);
+    const left = clusters.slice().sort(byArea);
+    const ordered = [left.shift()];
+    while (left.length)
+        ordered.push(pickNextLinked(left, ordered, links));
+    return ordered;
+}
+/** Start a new row when the cluster would overflow the current one. */
+function wrapIfNeeded(cursor, width) {
+    if (cursor.x === 0 || cursor.x + width <= MAX_ROW_W)
+        return;
+    cursor.x = 0;
+    cursor.y += cursor.rowH + CL_GAP_Y;
+    cursor.rowH = 0;
+}
+/** Place one cluster's origin (wrapping the row first if it would overflow), then its cards. */
+function placeCluster(c, cursor, cards) {
+    const width = c.w ?? 0;
+    wrapIfNeeded(cursor, width);
+    c.x = cursor.x;
+    c.y = cursor.y;
+    cursor.x += width + CL_GAP_X;
+    cursor.rowH = Math.max(cursor.rowH, c.h ?? 0);
+    for (const p of c.pos ?? []) {
+        const card = cards[p.key];
+        card.x = c.x + CL_PAD + p.dx;
+        card.y = c.y + CL_PAD + CL_TITLE + p.dy;
+        card.groupIndex = c.groupIndex;
+    }
+}
+/** Flow clusters into rows (wrapping at MAX_ROW_W), place each card, return canvas size. */
+export function flow(clusters, cards) {
+    // `Math.max(...[])` is -Infinity, which would report a canvas of -Infinity + 60 and render
+    // as an SVG with a negative viewBox. An empty model has no canvas, not a backwards one.
+    if (clusters.length === 0)
+        return { w: 0, h: 0 };
+    const cursor = { x: 0, y: 0, rowH: 0 };
+    for (const c of clusters)
+        placeCluster(c, cursor, cards);
+    return {
+        w: Math.max(...clusters.map((c) => c.x + (c.w ?? 0))) + 60,
+        h: cursor.y + cursor.rowH + 60
+    };
+}
+/** Barycenter mean of a node's neighbors (its own center when it has none). */
+function barycenter(key, nbrs, cards) {
+    const card = cards[key];
+    const ns = nbrs.get(key);
+    if (!ns || !ns.length)
+        return card.y + card.h / 2;
+    let sum = 0;
+    for (const nk of ns) {
+        const nc = cards[nk];
+        sum += nc.y + nc.h / 2;
+    }
+    return sum / ns.length;
+}
+/** Reorder one cluster's nodes toward their neighbors' barycenters, then re-pack it. */
+function reorderTowardNeighbors(c, cards, nbrs) {
+    const score = {};
+    for (const node of c.list)
+        score[node.id] = barycenter(node.id, nbrs, cards);
+    c.list = c.list.slice().sort((a, b) => score[a.id] - score[b.id]);
+    pack(c, cards);
+}
+/** Two barycenter passes: reorder each cluster's nodes toward neighbors, re-pack, re-flow. */
+export function barycenterPasses(clusters, cards, nbrs) {
+    let size = { w: 0, h: 0 };
+    for (let iter = 0; iter < 2; iter++) {
+        for (const c of clusters)
+            reorderTowardNeighbors(c, cards, nbrs);
+        size = flow(clusters, cards);
+    }
+    return size;
+}

package/dist/layout/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const CARD_W = 248;
+export declare const ROW_H = 24;
+export declare const HEAD_H = 40;
+export declare const MORE_H = 22;
+export declare const PAD_B = 6;
+export declare const GAP_X = 36;
+export declare const GAP_Y = 30;
+export declare const CL_PAD = 26;
+export declare const CL_TITLE = 16;
+export declare const CL_GAP_X = 110;
+export declare const CL_GAP_Y = 110;
+export declare const MAX_ROW_W = 2750;

package/dist/layout/constants.js

@@ -0,0 +1,15 @@
+/* Geometry constants for card and cluster layout. Values are carried over from
+   dbd's layout-types.ts unchanged — the ported characterization specs pin exact
+   pixel output, so changing any of these is a visible behaviour change. */
+export const CARD_W = 248;
+export const ROW_H = 24;
+export const HEAD_H = 40;
+export const MORE_H = 22;
+export const PAD_B = 6;
+export const GAP_X = 36;
+export const GAP_Y = 30;
+export const CL_PAD = 26;
+export const CL_TITLE = 16;
+export const CL_GAP_X = 110;
+export const CL_GAP_Y = 110;
+export const MAX_ROW_W = 2750;

package/dist/layout/edges.d.ts

@@ -0,0 +1,5 @@
+import type { Cards, EdgeStyle, RoutedEdge } from './types.js';
+import type { GraphEdge } from '../types.js';
+/** Build all edge geometry, skipping edges whose endpoints aren't laid out. */
+export declare function buildEdges(edges: GraphEdge[], cards: Cards): RoutedEdge[];
+export declare function edgePath(e: RoutedEdge, style: EdgeStyle): string;

package/dist/layout/edges.js

@@ -0,0 +1,110 @@
+/* Edge routing — anchor points, connector geometry, SVG paths.
+
+   Ported from dbd's layout-edges.ts. All geometry is unchanged: the 50px side-gap
+   threshold, the +14 same-anchor nudge, the 46px self-loop bow, the 64px same-side
+   bow, the [46, 170] control-point clamp and the +52 orthogonal sweep. */
+import { HEAD_H, ROW_H } from './constants.js';
+/**
+ * Vertical anchor for a row's edge endpoint on a card.
+ *
+ * `rowName` is optional because a canonical edge need not name one — a dependency
+ * edge (a view reading a table) has no column anchors at all. An unset name takes
+ * the same head-centre fallback a non-matching name already took.
+ */
+function anchorY(card, rowName) {
+    const idx = card.vis.findIndex((r) => r.name === rowName);
+    if (idx >= 0)
+        return card.y + HEAD_H + idx * ROW_H + ROW_H / 2;
+    return card.y + HEAD_H / 2;
+}
+/** A self-reference: loop on the right edge of the card. */
+function selfLoop(edge, i, card, { y1, y2 }) {
+    return {
+        i,
+        id: edge.id,
+        fromKey: edge.source,
+        toKey: edge.target,
+        kind: edge.kind,
+        relation: edge.relation,
+        self: true,
+        x1: card.x + card.w,
+        y1,
+        x2: card.x + card.w,
+        y2: y2 === y1 ? y1 + 14 : y2,
+        s1: 1,
+        s2: 1
+    };
+}
+/** Which side of each card the connector leaves from. 1 = right, -1 = left. */
+function sides(a, b) {
+    if (a.x + a.w + 50 <= b.x)
+        return { s1: 1, s2: -1 };
+    if (b.x + b.w + 50 <= a.x)
+        return { s1: -1, s2: 1 };
+    return { s1: 1, s2: 1 }; // stacked: route around the right
+}
+/** Geometry for a single edge: a self-loop on the right edge, or a side-routed connector. */
+function buildEdge(edge, i, cards) {
+    const a = cards[edge.source];
+    const b = cards[edge.target];
+    if (!a || !b)
+        return null;
+    const y1 = anchorY(a, edge.sourceRow);
+    const y2 = anchorY(b, edge.targetRow);
+    if (a === b)
+        return selfLoop(edge, i, a, { y1, y2 });
+    const { s1, s2 } = sides(a, b);
+    return {
+        i,
+        id: edge.id,
+        fromKey: edge.source,
+        toKey: edge.target,
+        kind: edge.kind,
+        relation: edge.relation,
+        self: false,
+        x1: s1 === 1 ? a.x + a.w : a.x,
+        y1,
+        x2: s2 === 1 ? b.x + b.w : b.x,
+        y2,
+        s1,
+        s2
+    };
+}
+/** Build all edge geometry, skipping edges whose endpoints aren't laid out. */
+export function buildEdges(edges, cards) {
+    const routed = [];
+    edges.forEach((edge, i) => {
+        const e = buildEdge(edge, i, cards);
+        if (e)
+            routed.push(e);
+    });
+    return routed;
+}
+/** Right-angle route: opposite sides join at the x-midpoint, same-side (stacked) sweeps around the right. */
+function orthogonalPath(e) {
+    const { x1, y1, x2, y2, s1, s2 } = e;
+    if (s1 !== s2) {
+        const mid = (x1 + x2) / 2;
+        return `M ${x1} ${y1} H ${mid} V ${y2} H ${x2}`;
+    }
+    const out = Math.max(x1, x2) + 52;
+    return `M ${x1} ${y1} H ${out} V ${y2} H ${x2}`;
+}
+/** Bezier route: same-side bows outward by a fixed amount, opposite-side bows by half the x distance (clamped). */
+function curvedPath(e) {
+    const { x1, y1, x2, y2, s1, s2 } = e;
+    if (s1 === s2) {
+        const bow = 64;
+        return `M ${x1} ${y1} C ${x1 + bow * s1} ${y1}, ${x2 + bow * s2} ${y2}, ${x2} ${y2}`;
+    }
+    const dx = Math.max(46, Math.min(170, Math.abs(x2 - x1) / 2));
+    return `M ${x1} ${y1} C ${x1 + dx * s1} ${y1}, ${x2 + dx * s2} ${y2}, ${x2} ${y2}`;
+}
+export function edgePath(e, style) {
+    if (e.self) {
+        const { x1, y1, x2, y2 } = e;
+        const bow = 46;
+        return `M ${x1} ${y1} C ${x1 + bow} ${y1}, ${x2 + bow} ${y2}, ${x2} ${y2}`;
+    }
+    return style === 'orthogonal' ? orthogonalPath(e) : curvedPath(e);
+}

package/dist/layout/index.d.ts

@@ -0,0 +1,9 @@
+import { cluster } from './cluster.js';
+import { neighborhood } from './neighborhood.js';
+import { points } from './points.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 * from './types.js';

package/dist/layout/index.js

@@ -0,0 +1,7 @@
+import { cluster } from './cluster.js';
+import { neighborhood } from './neighborhood.js';
+import { points } from './points.js';
+/** Built-in layouts, addressable by name from `Graph`'s `layout` prop. */
+export const layouts = { cluster, neighborhood, points };
+export { cluster, neighborhood, points };
+export * from './types.js';

package/dist/layout/neighborhood.d.ts

@@ -0,0 +1,9 @@
+import type { LayoutFn } from './types.js';
+/**
+ * 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.
+ *
+ * The focus card shows up to 16 rows unfiltered. Each neighbour shows only its keys and
+ * the rows the focus references, capped at 8 — both caps carried over from dbd.
+ */
+export declare const neighborhood: LayoutFn;

package/dist/layout/neighborhood.js

@@ -0,0 +1,123 @@
+/* Entity-centric layout: the focus node centred, nodes that reference it stacked on
+   the left, nodes it references on the right.
+
+   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
+   gone rather than moved. The one visible consequence: self-loops now use the shared
+   +14 anchor nudge and 46px bow instead of EntityDiagram's +16 and 52px. */
+import { buildCards } from './cards.js';
+import { buildEdges } from './edges.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
+   a tight vertical one. */
+const COL_GAP = 170;
+const STACK_GAP = 26;
+/** Floor and padding on the canvas, so a one-row neighbourhood is not a sliver. */
+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 } };
+function partition(model, focusId) {
+    const byNeighbour = new Map();
+    const selfEdges = [];
+    const entry = (id) => {
+        const found = byNeighbour.get(id) ?? { id, in: [], out: [] };
+        byNeighbour.set(id, found);
+        return found;
+    };
+    for (const edge of model.edges) {
+        // An unplaced endpoint is not a node, so it has no card and cannot be a neighbour.
+        // The relationship is still real and still reported by GraphState.relationships —
+        // it simply has nothing to draw here.
+        if (edge.unplaced)
+            continue;
+        const isFrom = edge.source === focusId;
+        const isTo = edge.target === focusId;
+        if (isFrom && isTo)
+            selfEdges.push(edge);
+        else if (isFrom)
+            entry(edge.target).out.push(edge);
+        else if (isTo)
+            entry(edge.source).in.push(edge);
+    }
+    return { neighbours: [...byNeighbour.values()], selfEdges };
+}
+/**
+ * Rows a neighbour card reveals: its own keys, plus whichever rows the focus actually
+ * references. Everything else stays behind the more-count.
+ */
+function referencedRows(neighbour) {
+    const names = new Set();
+    for (const edge of neighbour.in)
+        if (edge.sourceRow)
+            names.add(edge.sourceRow);
+    for (const edge of neighbour.out)
+        if (edge.targetRow)
+            names.add(edge.targetRow);
+    return names;
+}
+/** Stack height of a column of cards, gaps between but not after. */
+function stackHeight(cards) {
+    if (cards.length === 0)
+        return 0;
+    return cards.reduce((total, card) => total + card.h + STACK_GAP, 0) - STACK_GAP;
+}
+/** Place a column of cards at `x`, vertically centred within `height`. */
+function placeColumn(cards, x, height) {
+    let y = (height - stackHeight(cards)) / 2;
+    for (const card of cards) {
+        card.x = x;
+        card.y = y;
+        y += card.h + STACK_GAP;
+    }
+}
+function buildNeighbourCards(model, neighbours, expanded) {
+    const nodes = neighbours
+        .map((n) => model.byId.get(n.id))
+        .filter((n) => n !== undefined);
+    const wanted = new Map(neighbours.map((n) => [n.id, referencedRows(n)]));
+    return buildCards(nodes, 'full', {
+        limit: 8,
+        expanded,
+        select: (row, node) => row.badges.includes('pk') || (wanted.get(node.id)?.has(row.name) ?? false)
+    });
+}
+/**
+ * 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.
+ *
+ * The focus card shows up to 16 rows unfiltered. Each neighbour shows only its keys and
+ * the rows the focus references, capped at 8 — both caps carried over from dbd.
+ */
+export const neighborhood = (model, options) => {
+    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 } };
+};

package/dist/layout/nested.d.ts

@@ -0,0 +1,13 @@
+import type { Cards, Cluster, NodeAxis, Size } from './types.js';
+import type { GraphNode } from '../types.js';
+/**
+ * Two-level clusters over already-built cards.
+ *
+ * Returns a FLAT list, every outer box before every inner one — absolutely positioned
+ * siblings paint in document order, so an outer box emitted later would cover the
+ * subdivisions inside it.
+ */
+export declare function nestedClusters(nodes: GraphNode[], cards: Cards, outerAxis: NodeAxis, innerAxis: NodeAxis): {
+    clusters: Cluster[];
+    size: Size;
+};

package/dist/layout/nested.js

@@ -0,0 +1,156 @@
+/* Two-level clustering: an outer box per value of one axis, subdivided by a second.
+
+   Schema is the right grouping for an ER diagram and a poor one for a dependency graph — a
+   single schema holds a table, a trigger and a procedure, while the question there is usually
+   "what are the routines, and what do they touch". Nesting shows both facts at once rather
+   than trading one for the other, and which axis is OUTER is the reader's choice.
+
+   Nesting needs no DOM tree. Clusters are absolutely positioned boxes, so a FLAT list with the
+   outer boxes emitted first renders correctly by paint order; `depth` is what lets CSS draw an
+   inner box as a faint subdivision rather than a second coloured region fighting the one
+   around it.
+
+   This is a separate module, and `nestBy` is strictly opt-in, because `clusters.ts` carries 20
+   characterization tests ported from dbd with exact pixel assertions. Single-level layout must
+   keep running the original code path untouched. */
+import { CL_GAP_X, CL_GAP_Y, CL_PAD, CL_TITLE, MAX_ROW_W } from './constants.js';
+import { pack } from './clusters.js';
+/** Gap between two inner boxes inside one outer box. Tighter than the canvas-level gap. */
+const INNER_GAP = 14;
+/** An inner box gets a shorter label strip than an outer one — it is a subdivision. */
+const INNER_TITLE = 20;
+/** The axis value a node buckets under. '' when it has none, which is a bucket, not a drop. */
+function axisOf(node, axis) {
+    return (axis === 'kind' ? node.kind : node.group) ?? '';
+}
+/** Stable, alphabetical bucketing so a re-render never reshuffles the boxes. */
+function bucket(nodes, axis) {
+    const by = new Map();
+    for (const node of nodes) {
+        const key = axisOf(node, axis);
+        const list = by.get(key) ?? [];
+        list.push(node);
+        by.set(key, list);
+    }
+    return new Map([...by.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * One inner box: its nodes masonry-packed by the SAME `pack` the single-level layout uses, so
+ * card geometry inside a subdivision is identical to card geometry inside a plain cluster.
+ */
+function packInner(name, parent, nodes, cards) {
+    const inner = {
+        name,
+        parent,
+        depth: 1,
+        list: [...nodes].sort((a, b) => a.label.localeCompare(b.label)),
+        count: nodes.length,
+        groupIndex: 0,
+        x: 0,
+        y: 0
+    };
+    pack(inner, cards);
+    // `pack` sizes for a top-level cluster (CL_PAD + CL_TITLE). An inner box carries a shorter
+    // strip, so the height is re-derived rather than inherited.
+    const h = (inner.h ?? 0) - CL_TITLE + INNER_TITLE;
+    return { cluster: { ...inner, h }, w: inner.w ?? 0, h };
+}
+/** Flow inner boxes into wrapping rows inside one outer box. Returns the content extent. */
+function flowInner(inners, limit) {
+    let x = 0;
+    let y = 0;
+    let rowHeight = 0;
+    let widest = 0;
+    for (const item of inners) {
+        if (x > 0 && x + item.w > limit) {
+            y += rowHeight + INNER_GAP;
+            x = 0;
+            rowHeight = 0;
+        }
+        item.cluster.x = x;
+        item.cluster.y = y;
+        x += item.w + INNER_GAP;
+        rowHeight = Math.max(rowHeight, item.h);
+        widest = Math.max(widest, x - INNER_GAP);
+    }
+    return { w: widest, h: y + rowHeight };
+}
+/** Shift an inner box and its cards from outer-relative to canvas coordinates. */
+function translate(item, originX, originY, cards) {
+    const x = originX + item.cluster.x;
+    const y = originY + item.cluster.y;
+    item.cluster.x = x;
+    item.cluster.y = y;
+    for (const p of item.cluster.pos ?? []) {
+        const card = cards[p.key];
+        card.x = x + CL_PAD + p.dx;
+        card.y = y + INNER_TITLE + p.dy;
+    }
+}
+/** Build one outer box: bucket by the inner axis, pack each, flow them, size the container. */
+function buildOuter(name, nodes, inner, cards) {
+    const inners = [...bucket(nodes, inner).entries()].map(([key, list]) => packInner(key, name, list, cards));
+    // Wide enough for the widest subdivision, so an inner box is never forced to overflow.
+    const limit = Math.max(...inners.map((i) => i.w), MAX_ROW_W / 3);
+    const extent = flowInner(inners, limit);
+    return {
+        cluster: {
+            name,
+            depth: 0,
+            list: [...nodes].sort((a, b) => a.label.localeCompare(b.label)),
+            count: nodes.length,
+            groupIndex: 0,
+            x: 0,
+            y: 0,
+            w: extent.w + CL_PAD * 2,
+            h: extent.h + CL_PAD * 2 + CL_TITLE
+        },
+        inners
+    };
+}
+/** Flow outer boxes into wrapping rows, then translate everything they contain. */
+function placeOuters(outers, cards) {
+    let x = 0;
+    let y = 0;
+    let rowHeight = 0;
+    for (const outer of outers) {
+        const w = outer.cluster.w ?? 0;
+        if (x > 0 && x + w > MAX_ROW_W) {
+            y += rowHeight + CL_GAP_Y;
+            x = 0;
+            rowHeight = 0;
+        }
+        outer.cluster.x = x;
+        outer.cluster.y = y;
+        for (const item of outer.inners) {
+            translate(item, x + CL_PAD, y + CL_PAD + CL_TITLE, cards);
+        }
+        x += w + CL_GAP_X;
+        rowHeight = Math.max(rowHeight, outer.cluster.h ?? 0);
+    }
+    return {
+        w: Math.max(...outers.map((o) => o.cluster.x + (o.cluster.w ?? 0))) + 60,
+        h: y + rowHeight + 60
+    };
+}
+/**
+ * Two-level clusters over already-built cards.
+ *
+ * Returns a FLAT list, every outer box before every inner one — absolutely positioned
+ * siblings paint in document order, so an outer box emitted later would cover the
+ * subdivisions inside it.
+ */
+export function nestedClusters(nodes, cards, outerAxis, innerAxis) {
+    if (nodes.length === 0)
+        return { clusters: [], size: { w: 0, h: 0 } };
+    const outers = [...bucket(nodes, outerAxis).entries()].map(([name, list]) => buildOuter(name, list, innerAxis, cards));
+    // Alphabetical index so a box keeps its colour however the rows happened to wrap — the
+    // stability rule `resolveGroupStyles` follows.
+    const names = outers.map((o) => o.cluster.name);
+    outers.forEach((o) => (o.cluster.groupIndex = names.indexOf(o.cluster.name)));
+    const size = placeOuters(outers, cards);
+    return {
+        clusters: [...outers.map((o) => o.cluster), ...outers.flatMap((o) => o.inners.map((i) => i.cluster))],
+        size
+    };
+}