@rokkit/graph 1.8.0 → 1.8.2

package/dist/layout/layers.js

@@ -0,0 +1,180 @@
+/* The layered view (#167): modules ranked into horizontal layers, foundations at the bottom.
+ *
+ * Sugiyama-shaped, but the expensive half — assigning layers — is the HOST's: it knows the
+ * intended architecture, and rokkit computes no depth. What is left is placement and the
+ * one thing the view exists to show: edges should only point DOWN, and the ones that climb are
+ * violations.
+ *
+ *   - one full-width band per layer, layer 0 at the top, drawn as a cluster box so it renders
+ *     through the existing box path with its label;
+ *   - a crowded layer wraps into rows rather than one line a thousand cards long;
+ *   - a layer is ordered by one barycenter pass against the layer above — each node under the
+ *     mean position of its neighbours there — which removes most of the avoidable crossings;
+ *   - edges are vertical S-curves, and carry their conformance for the theme to colour.
+ */
+import { buildCards } from './cards.js';
+import { CARD_W } from './constants.js';
+import { carried, keepsEdge } from './edges.js';
+import { warnUnknownOptions } from './options.js';
+import { say } from '../messages.js';
+/** Cards per row before a layer wraps. */
+const PER_ROW = 8;
+const GAP_X = 28;
+const GAP_ROW = 20;
+/** Space between one band and the next — where the edges run. */
+const GAP_BAND = 56;
+/** Inner padding of a band, and the strip its label sits in. */
+const PAD = 20;
+const TITLE = 22;
+/** The band a node belongs to: its layer, or none (drawn last, as Unassigned). */
+const UNASSIGNED = Number.POSITIVE_INFINITY;
+const layerOf = (node) => node.layer ?? UNASSIGNED;
+/** How an edge sits against the layering, from the two layers the host gave. */
+export function deriveConformance(from, to) {
+    if (from === undefined || to === undefined)
+        return undefined;
+    if (to === from)
+        return 'level';
+    if (to < from)
+        return 'up';
+    return to - from === 1 ? 'down' : 'skip';
+}
+/** Nodes grouped by layer, in band order (Unassigned last). */
+function bandsOf(model) {
+    const bands = new Map();
+    for (const node of model.nodes) {
+        const key = layerOf(node);
+        bands.set(key, [...(bands.get(key) ?? []), node]);
+    }
+    return [...bands.entries()].sort(([a], [b]) => a - b);
+}
+/** Undirected neighbour ids per node — the barycenter reads both directions. */
+function neighbours(model) {
+    const near = new Map();
+    const link = (a, b) => near.set(a, [...(near.get(a) ?? []), b]);
+    for (const e of model.edges) {
+        if (e.source === e.target)
+            continue;
+        link(e.source, e.target);
+        link(e.target, e.source);
+    }
+    return near;
+}
+/**
+ * Order each band: the first alphabetically, every later one by the mean index of its
+ * neighbours in the band above (alphabetical among nodes with none there).
+ */
+function order(bands, near) {
+    const ordered = [];
+    let above = new Map();
+    for (const [, nodes] of bands) {
+        const centre = (n) => {
+            const hits = (near.get(n.id) ?? []).map((id) => above.get(id)).filter((i) => i !== undefined);
+            return hits.length > 0 ? hits.reduce((s, i) => s + i, 0) / hits.length : Number.POSITIVE_INFINITY;
+        };
+        const band = [...nodes].sort((a, b) => centre(a) - centre(b) || a.label.localeCompare(b.label));
+        ordered.push(band);
+        above = new Map(band.map((n, i) => [n.id, i]));
+    }
+    return ordered;
+}
+const chunk = (items, size) => Array.from({ length: Math.ceil(items.length / size) }, (_, i) => items.slice(i * size, (i + 1) * size));
+const rowWidth = (count) => count * CARD_W + Math.max(0, count - 1) * GAP_X;
+/** Place one band's cards, row by row, centred in the shared width. Returns the band height. */
+function placeBand(band, cards, top, width) {
+    let y = top + TITLE + PAD;
+    const rows = chunk(band, PER_ROW);
+    rows.forEach((row, r) => {
+        let x = (width - rowWidth(row.length)) / 2;
+        const tallest = Math.max(...row.map((n) => cards[n.id].h));
+        for (const node of row) {
+            Object.assign(cards[node.id], { x, y });
+            x += CARD_W + GAP_X;
+        }
+        y += tallest + (r < rows.length - 1 ? GAP_ROW : 0);
+    });
+    return y + PAD - top;
+}
+/** The host's name for a layer, else the locale's — "Layer 2", "Unassigned". */
+const labelFor = (layer, labels) => layer === UNASSIGNED ? say('layerUnassigned') : (labels?.[layer] ?? say('layer', { n: layer }));
+/** A vertical S: out of the bottom of a card above, into the top of a card below (or reverse). */
+function route(edge, i, cards, conformance) {
+    const a = cards[edge.source];
+    const b = cards[edge.target];
+    const downward = b.y >= a.y + a.h;
+    const x1 = a.x + a.w / 2;
+    const x2 = b.x + b.w / 2;
+    const y1 = downward ? a.y + a.h : a.y;
+    const y2 = downward ? b.y : b.y + b.h;
+    const mid = (y1 + y2) / 2;
+    return {
+        i,
+        id: edge.id,
+        fromKey: edge.source,
+        toKey: edge.target,
+        kind: edge.kind,
+        relation: edge.relation,
+        ...carried(edge),
+        ...(conformance ? { conformance } : {}),
+        self: false,
+        x1,
+        y1,
+        x2,
+        y2,
+        s1: 1,
+        s2: 1,
+        path: `M ${x1} ${y1} C ${x1} ${mid}, ${x2} ${mid}, ${x2} ${y2}`
+    };
+}
+function edgesFor(model, cards, showEdges) {
+    const routed = [];
+    model.edges.forEach((edge, i) => {
+        if (edge.source === edge.target || !cards[edge.source] || !cards[edge.target])
+            return;
+        const conformance = edge.conformance ??
+            deriveConformance(cards[edge.source].node.layer, cards[edge.target].node.layer);
+        const routedEdge = route(edge, i, cards, conformance);
+        if (keepsEdge(showEdges, routedEdge))
+            routed.push(routedEdge);
+    });
+    return routed;
+}
+/** Stack the bands top to bottom, each a full-width labelled box around its cards. */
+function placeBands(ordered, layerKeys, cards, { width, labels }) {
+    const clusters = [];
+    let top = 0;
+    ordered.forEach((band, i) => {
+        const h = placeBand(band, cards, top, width);
+        clusters.push({
+            name: labelFor(layerKeys[i], labels),
+            caption: String(band.length),
+            list: band,
+            count: band.length,
+            groupIndex: i,
+            depth: 0,
+            x: 0,
+            y: top,
+            w: width,
+            h
+        });
+        top += h + GAP_BAND;
+    });
+    return { clusters, height: top - GAP_BAND };
+}
+/** Host-assigned layers as horizontal bands, layer 0 at the top. */
+export const layers = (model, options) => {
+    warnUnknownOptions(options, 'layers');
+    if (model.nodes.length === 0)
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    const cards = buildCards(model.nodes, options.density ?? 'names', { expanded: options.expanded });
+    const bands = bandsOf(model);
+    const ordered = order(bands, neighbours(model));
+    const width = rowWidth(Math.min(PER_ROW, Math.max(...ordered.map((b) => b.length)))) + PAD * 2;
+    const { clusters, height } = placeBands(ordered, bands.map(([layer]) => layer), cards, { width, labels: options.layerLabels });
+    return {
+        clusters,
+        cards,
+        edges: edgesFor(model, cards, options.showEdges ?? 'all'),
+        size: { w: width, h: height }
+    };
+};

package/dist/layout/matrix.d.ts

@@ -36,3 +36,15 @@ export type MatrixOptions = {
     groupBy?: NodeAxis;
 };
 export declare function buildMatrix(model: GraphModel, options?: MatrixOptions): Matrix;
+/** The matrix's frame: a label gutter sized by the longest name (by length, not the DOM —
+ *  deterministic, like every layout here), and the canvas around `n` cells of `cell` px. */
+export declare function matrixFrame(matrix: Pick<Matrix, 'labels' | 'order'>, cell: number): {
+    labelW: number;
+    n: number;
+    width: number;
+    height: number;
+};
+/** A cell on the selected node's row or column is highlighted; nothing is without a selection. */
+export declare const cellState: (selected: string | null, source: string, target: string) => "highlight" | undefined;
+/** The matrix's accessible name: what it holds, from the locale. */
+export declare function matrixLabel(nodes: number, dependencies: number, above: number): string;

package/dist/layout/matrix.js

@@ -13,6 +13,7 @@
  *
  * Pure and DOM-free, like every layout.
  */
+import { counted, say } from '../messages.js';
 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. */
@@ -88,3 +89,22 @@ export function buildMatrix(model, options = {}) {
         maxCount: Math.max(0, ...cells.map((c) => c.count))
     };
 }
+/** The matrix's frame: a label gutter sized by the longest name (by length, not the DOM —
+ *  deterministic, like every layout here), and the canvas around `n` cells of `cell` px. */
+export function matrixFrame(matrix, cell) {
+    const longest = Math.max(0, ...matrix.labels.map((label) => label.length));
+    const labelW = Math.min(220, Math.max(48, longest * 6.5 + 14));
+    const n = matrix.order.length;
+    const side = labelW + n * cell + 8;
+    return { labelW, n, width: side, height: side };
+}
+/** A cell on the selected node's row or column is highlighted; nothing is without a selection. */
+export const cellState = (selected, source, target) => selected && (source === selected || target === selected) ? 'highlight' : undefined;
+/** The matrix's accessible name: what it holds, from the locale. */
+export function matrixLabel(nodes, dependencies, above) {
+    return say('matrix', {
+        nodes: counted(nodes, 'nodeOne', 'nodeMany'),
+        dependencies: counted(dependencies, 'dependencyOne', 'dependencyMany'),
+        above
+    });
+}

package/dist/layout/neighborhood.js

@@ -115,12 +115,17 @@ function buildNeighbourCards(model, neighbours, expanded) {
  * 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.
+ * leave a gap where that column would have been, so the width is measured from the deepest
+ * column that actually exists rather than from the depth asked for. An empty SIDE is
+ * different (#170): the focus is centred, so the shallower side reserves the deeper side's
+ * columns — otherwise "centred" would only hold for a node with neighbours both ways.
  */
 function arrange(built, cards, ctx) {
     const occupied = built.filter((r) => r.ids.length > 0);
-    const { focusX, xFor } = geometry(occupied);
+    // The same edge room on BOTH sides — a self-loop's bow plus a hairline — so the canvas
+    // stays symmetric about the focus.
+    const edge = (ctx.hasLoop ? LOOP_W : 0) + 2;
+    const { focusX, xFor } = geometry(occupied, edge);
     const focusCard = cards[ctx.focus.id];
     const height = placeRings(occupied, cards, { focusCard, focusX, xFor });
     const columns = buildColumns(occupied, {
@@ -129,7 +134,9 @@ function arrange(built, cards, ctx) {
         xFor,
         dependency: ctx.dependency
     });
-    const width = xFor('out', furthest(occupied, 'out')) + CARD_W + (ctx.hasLoop ? LOOP_W : 0) + 4;
+    // Symmetric about the focus (#170): as much room right of it as left, so the focus card's
+    // centre IS the canvas's centre whichever side is empty or deeper.
+    const width = focusX * 2 + CARD_W;
     return { columns, size: { w: width, h: height } };
 }
 /**
@@ -161,11 +168,13 @@ function drawableIn(model, cards) {
 }
 /**
  * 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.
+ * side, d steps right. The focus sits past `edge` and as many columns as the DEEPER side
+ * needs, so both sides get the same room and the focus is the centre.
  */
-function geometry(occupied) {
+function geometry(occupied, edge) {
     const columnStep = CARD_W + COL_GAP;
-    const focusX = furthest(occupied, 'in') * columnStep;
+    const reach = Math.max(furthest(occupied, 'in'), furthest(occupied, 'out'));
+    const focusX = edge + reach * columnStep;
     return {
         focusX,
         xFor: (side, d) => (side === 'in' ? focusX - d * columnStep : focusX + d * columnStep)

package/dist/layout/options.d.ts

@@ -4,7 +4,7 @@ import type { LayoutOptions } from './types.js';
  * 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"];
+export declare const LAYOUT_OPTION_KEYS: readonly ["density", "arrange", "edgeStyle", "focus", "expanded", "groupBy", "nestBy", "sizeBy", "sizeScale", "depth", "focusPath", "levels", "radialMode", "root", "bundleTension", "showEdges", "layerLabels", "widthBy", "heightBy", "colorBy", "above", "shadeBy"];
 /**
  * Which options have an EFFECT under each built-in layout.
  *

package/dist/layout/options.js

@@ -18,7 +18,14 @@ export const LAYOUT_OPTION_KEYS = [
     'levels',
     'radialMode',
     'root',
-    'bundleTension'
+    'bundleTension',
+    'showEdges',
+    'layerLabels',
+    'widthBy',
+    'heightBy',
+    'colorBy',
+    'above',
+    'shadeBy'
 ];
 /**
  * Which options have an EFFECT under each built-in layout.
@@ -39,14 +46,20 @@ export const LAYOUT_OPTION_KEYS = [
  *     its own purpose.
  */
 export const LAYOUT_OPTIONS = {
+    // No edgeStyle: an arc is the only shape that keeps one axis readable.
+    arcs: ['showEdges', 'above'],
     cluster: ['density', 'arrange', 'edgeStyle', 'expanded', 'groupBy', 'nestBy'],
     flow: ['density', 'edgeStyle', 'expanded'],
+    // No edgeStyle: a layered edge is always a vertical S, built by the layout itself.
+    layers: ['density', 'expanded', 'showEdges', 'layerLabels'],
     neighborhood: ['edgeStyle', 'expanded', 'focus', 'depth'],
     points: ['edgeStyle', 'sizeBy', 'sizeScale'],
+    // No edgeStyle: the tree's links are elbows the layout draws itself.
+    polymetric: ['widthBy', 'heightBy', 'colorBy'],
     radial: ['edgeStyle', 'sizeBy', 'sizeScale', 'radialMode', 'levels', 'root'],
-    sunburst: ['sizeBy', 'focusPath', 'levels'],
+    sunburst: ['sizeBy', 'shadeBy', 'focusPath', 'levels'],
     structure: ['sizeBy', 'sizeScale', 'focusPath', 'levels', 'bundleTension'],
-    world: ['sizeBy', 'focusPath', 'levels']
+    world: ['sizeBy', 'shadeBy', 'focusPath', 'levels']
 };
 /**
  * Layouts that draw a node as a DOT rather than a card.

package/dist/layout/percentile.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The 95th-percentile cap of the present, positive values — 1 when there are none.
+ *
+ * Code metrics are long-tailed: one file with ten times the functions, one import pair with
+ * fifty times the count. Scaling to the maximum shrinks everything else to the minimum, so a
+ * channel scales to this instead and a value past it clamps (#168, #169).
+ */
+export declare function capOf(values: (number | undefined)[]): number;

package/dist/layout/percentile.js

@@ -0,0 +1,13 @@
+/**
+ * The 95th-percentile cap of the present, positive values — 1 when there are none.
+ *
+ * Code metrics are long-tailed: one file with ten times the functions, one import pair with
+ * fifty times the count. Scaling to the maximum shrinks everything else to the minimum, so a
+ * channel scales to this instead and a value past it clamps (#168, #169).
+ */
+export function capOf(values) {
+    const sorted = values.filter((v) => v !== undefined && v > 0).sort((a, b) => a - b);
+    if (sorted.length === 0)
+        return 1;
+    return sorted[Math.min(sorted.length - 1, Math.ceil(0.95 * sorted.length) - 1)];
+}

package/dist/layout/polymetric.d.ts

@@ -0,0 +1,3 @@
+import type { LayoutFn } from './types.js';
+/** The containment tree with each leaf's width, height and shade bound to three measures. */
+export declare const polymetric: LayoutFn;

package/dist/layout/polymetric.js

@@ -0,0 +1,221 @@
+/* The polymetric view (#168): Lanza & Marinescu's System Complexity.
+ *
+ * A containment tree, drawn top-down, where every LEAF is a box whose width, height and shade
+ * carry three independent measures — the three-at-once is the point: narrow-tall-dark reads
+ * differently from wide-short-pale, and neither is expressible as area (that is `world`).
+ *
+ * Degenerate data is the normal case for code metrics, so it is designed for:
+ *   - each channel scales to the 95th percentile of its values, so one file with 10x the
+ *     functions of the rest does not shrink every other box to the minimum; a value past the
+ *     cap is clamped to the maximum and the box says so (`clamped`);
+ *   - a zero is a value and draws at the minimum; a MISSING measure also draws at the minimum
+ *     but is marked (`missing`), never passed off as a zero.
+ * Every box at one depth is topped on one line, so heights compare at a glance.
+ */
+import { buildTree } from '../model/tree.js';
+import { degreeOf } from './sizing.js';
+import { warnUnknownOptions } from './options.js';
+import { capOf } from './percentile.js';
+const MIN = 10;
+const MAX = { width: 140, height: 140, color: 1 };
+/** A container is a label, not a measured thing. */
+const CONTAINER = { w: 132, h: 26 };
+const GAP_X = 18;
+/** Between depth rows — room for the leaf labels under the boxes and the links. */
+const GAP_Y = 46;
+const PAD = 16;
+/** One encoding: the measure it reads, and the value its full extent stands for. */
+class Channel {
+    name;
+    measure;
+    cap;
+    #degree;
+    constructor(name, measure, leaves, degree) {
+        this.name = name;
+        this.measure = measure;
+        this.#degree = degree;
+        this.cap = capOf(leaves.map((l) => this.valueOf(l.node)));
+    }
+    /** The node's value, or undefined when it has none — distinct from zero. */
+    valueOf(node) {
+        if (this.measure === 'degree')
+            return this.#degree.get(node.id) ?? 0;
+        if (this.measure === 'weight')
+            return node.weight;
+        return node.measures?.[this.measure];
+    }
+    /** 0..1 of the cap (undefined when missing), and whether the value passed the cap. */
+    read(node) {
+        const value = this.valueOf(node);
+        if (value === undefined)
+            return { clamped: false };
+        return { t: Math.min(1, Math.max(0, value / this.cap)), clamped: value > this.cap };
+    }
+    get scale() {
+        return { measure: this.measure, cap: this.cap };
+    }
+}
+/** One channel's reading onto the box: a size between MIN and the max, or a shade. */
+function apply(out, name, t) {
+    if (name === 'color') {
+        if (t !== undefined)
+            out.shade = t;
+        return;
+    }
+    out[name === 'width' ? 'w' : 'h'] = MIN + (t ?? 0) * (MAX[name] - MIN);
+}
+/** A leaf's width, height and shade, with what was missing or clamped. */
+function encode(node, channels) {
+    const out = {};
+    const missing = [];
+    const clamped = [];
+    for (const channel of channels) {
+        const { t, clamped: over } = channel.read(node);
+        if (t === undefined)
+            missing.push(channel.name);
+        if (over)
+            clamped.push(channel.name);
+        apply(out, channel.name, t);
+    }
+    if (missing.length)
+        out.missing = missing;
+    if (clamped.length)
+        out.clamped = clamped;
+    return out;
+}
+const rowSpan = (boxes) => boxes.reduce((s, b) => s + b.span, 0) + GAP_X * Math.max(0, boxes.length - 1);
+function boxFor(tree, encoding, kids) {
+    // From the TREE, not from `kids`: a container's kids are attached after it is created.
+    const leaf = tree.children.length === 0;
+    return {
+        name: tree.label,
+        list: [],
+        count: tree.children.length,
+        groupIndex: 0,
+        x: 0,
+        y: 0,
+        depth: tree.depth - 1,
+        path: tree.address,
+        declared: tree.node?.id,
+        ...(leaf ? { nodeId: tree.node?.id, kind: tree.node?.kind } : {}),
+        ...encoding,
+        tree,
+        kids,
+        span: 0
+    };
+}
+/** Every box in the subtree, sized; `span` is the subtree's width for the tidy layout. */
+function size(tree, channels, out) {
+    if (tree.children.length === 0) {
+        // A leaf is always a declared node: a synthesised box exists only because something
+        // lies below it.
+        const leaf = boxFor(tree, encode(tree.node, channels), []);
+        leaf.span = leaf.w;
+        out.push(leaf);
+        return leaf;
+    }
+    const box = boxFor(tree, { ...CONTAINER }, []);
+    out.push(box);
+    box.kids = tree.children.map((child) => size(child, channels, out));
+    box.span = Math.max(CONTAINER.w, rowSpan(box.kids));
+    return box;
+}
+/** Lay the subtree out from `left`: children side by side, the parent centred over them. */
+function place(box, left, rowTop) {
+    box.y = rowTop[box.depth ?? 0];
+    box.x = left + (box.span - box.w) / 2;
+    let x = left + (box.span - rowSpan(box.kids)) / 2;
+    for (const kid of box.kids) {
+        place(kid, x, rowTop);
+        x += kid.span + GAP_X;
+    }
+}
+/** The top of each depth row: every box at a depth is topped on one line. */
+function rowTops(boxes) {
+    const tallest = [];
+    for (const b of boxes)
+        tallest[b.depth ?? 0] = Math.max(tallest[b.depth ?? 0] ?? 0, b.h);
+    const tops = [];
+    let y = PAD;
+    for (const h of tallest) {
+        tops.push(y);
+        y += h + GAP_Y;
+    }
+    return tops;
+}
+const keyOf = (b) => b.declared ?? b.tree.id;
+/** An elbow from the bottom of a container to the top of what it holds. */
+function link(parent, child, i) {
+    const x1 = parent.x + parent.w / 2;
+    const y1 = parent.y + parent.h;
+    const x2 = child.x + child.w / 2;
+    const y2 = child.y;
+    return {
+        i,
+        id: `contains:${keyOf(parent)}>${keyOf(child)}`,
+        fromKey: keyOf(parent),
+        toKey: keyOf(child),
+        kind: 'containment',
+        self: false,
+        x1,
+        y1,
+        x2,
+        y2,
+        s1: 1,
+        s2: 1,
+        path: `M ${x1} ${y1} V ${(y1 + y2) / 2} H ${x2} V ${y2}`
+    };
+}
+function linksOf(roots) {
+    const edges = [];
+    const walk = (b) => {
+        for (const kid of b.kids) {
+            edges.push(link(b, kid, edges.length));
+            walk(kid);
+        }
+    };
+    roots.forEach(walk);
+    return edges;
+}
+/** The channels the options bind; colour only when a measure is named for it. */
+function channelsFor(options, leaves, degree) {
+    const channels = [
+        new Channel('width', options.widthBy ?? 'weight', leaves, degree),
+        new Channel('height', options.heightBy ?? 'weight', leaves, degree)
+    ];
+    if (options.colorBy)
+        channels.push(new Channel('color', options.colorBy, leaves, degree));
+    return channels;
+}
+/** Size and place the forest under the tree root; returns the boxes and the canvas width. */
+function lay(roots, channels) {
+    const boxes = [];
+    const tops = roots.map((root) => size(root, channels, boxes));
+    const rowTop = rowTops(boxes);
+    let left = PAD;
+    for (const top of tops) {
+        place(top, left, rowTop);
+        left += top.span + GAP_X * 2;
+    }
+    return { boxes, tops, width: left - GAP_X * 2 + PAD };
+}
+/** The containment tree with each leaf's width, height and shade bound to three measures. */
+export const polymetric = (model, options) => {
+    warnUnknownOptions(options, 'polymetric');
+    const tree = buildTree(model);
+    if (tree.children.length === 0)
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    const leaves = (function all(n) {
+        return n.children.length === 0 ? [n] : n.children.flatMap(all);
+    })(tree);
+    const channels = channelsFor(options, leaves, degreeOf(model));
+    const { boxes, tops, width } = lay(tree.children, channels);
+    const [w, h, color] = channels;
+    return {
+        clusters: boxes.map(({ tree: _t, span: _s, kids: _k, ...cluster }) => cluster),
+        cards: {},
+        edges: linksOf(tops),
+        size: { w: width, h: Math.max(...boxes.map((b) => b.y + b.h)) + PAD + GAP_Y / 2 },
+        channels: { width: w.scale, height: h.scale, ...(color ? { color: color.scale } : {}) }
+    };
+};

package/dist/layout/radial.js

@@ -14,6 +14,7 @@
  * edges it could not use are still drawn, marked `back`, because "b also calls this" is
  * exactly what a reader is looking for.
  */
+import { carried } from './edges.js';
 import { childrenIn, hierarchy } from './hierarchy.js';
 import { nodeSizes } from './sizing.js';
 import { warnUnknownOptions } from './options.js';
@@ -143,7 +144,8 @@ function identity(edge, i) {
         fromKey: edge.source,
         toKey: edge.target,
         kind: edge.kind,
-        relation: edge.relation
+        relation: edge.relation,
+        ...carried(edge)
     };
 }
 /**

package/dist/layout/structure.js

@@ -20,6 +20,7 @@
  * Modelled on Sensei's Structure board (docs/mockups/Sensei, "Project window · Diagrams ·
  * Structure"), which is d3.cluster + lineRadial + curveBundle over the same hierarchy.
  */
+import { carried } from './edges.js';
 import { buildTree, findNode } from '../model/tree.js';
 import { bundlePath, commonDepth } from './bundle.js';
 import { nodeSizes } from './sizing.js';
@@ -153,6 +154,10 @@ function band(node, ctx, index) {
         // no band appears at all rather than one looking wrong.
         parent: node.path.slice(0, -1).join('/'),
         ramp: node.path[ctx.origin],
+        // A band is a container by construction — its leaves are the node cards on the rim.
+        path: node.address,
+        leaf: false,
+        declared: node.node?.id,
         count: node.children.length,
         list: node.children.map((c) => c.node).filter((n) => n !== undefined),
         groupIndex: index,
@@ -261,6 +266,7 @@ function routeAll(model, root, ctx, tension) {
             toKey: edge.target,
             kind: edge.kind,
             relation: edge.relation ?? reach(a, b),
+            ...carried(edge),
             self: false,
             x1: from.x,
             y1: from.y,
@@ -340,7 +346,7 @@ function dots(leaves, ring, ctx) {
  */
 export const structure = (model, options) => {
     warnUnknownOptions(options, 'structure');
-    const tree = buildTree(model, { measure: options.sizeBy ?? 'weight' });
+    const tree = buildTree(model, { measure: options.sizeBy ?? 'weight', keep: options.focusPath });
     const root = findNode(tree, options.focusPath ?? []);
     if (!root || root.children.length === 0) {
         return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };