@rokkit/graph 1.7.0 → 1.8.1

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 } };

package/dist/layout/sunburst.js

@@ -14,6 +14,7 @@
  * exact radians.
  */
 import { buildTree, findNode } from '../model/tree.js';
+import { shadeFields, shares } from '../model/share.js';
 import { warnUnknownOptions } from './options.js';
 /** Outer radius of the deepest materialised ring. The canvas is derived from it. */
 const RADIUS = 380;
@@ -70,7 +71,7 @@ function split(node, span, ctx) {
         a += slice;
     });
 }
-function wedgeOf(entry, groupIndex, ring) {
+function wedgeOf(entry, groupIndex, ring, shaded) {
     const leaf = entry.tree.children.length === 0 ? entry.tree.node : undefined;
     return {
         name: entry.tree.label,
@@ -80,6 +81,9 @@ function wedgeOf(entry, groupIndex, ring) {
         ramp: entry.ramp,
         nodeId: leaf?.id,
         kind: leaf?.kind,
+        path: entry.tree.address,
+        leaf: entry.tree.children.length === 0,
+        declared: entry.tree.node?.id,
         list: entry.tree.children.map((c) => c.node).filter((n) => n !== undefined),
         count: entry.tree.children.length,
         groupIndex,
@@ -94,7 +98,8 @@ function wedgeOf(entry, groupIndex, ring) {
         x: RADIUS + PAD + Math.cos((entry.a0 + entry.a1) / 2) * ((entry.depth + 0.5) * ring),
         y: RADIUS + PAD + Math.sin((entry.a0 + entry.a1) / 2) * ((entry.depth + 0.5) * ring),
         w: 0,
-        h: 0
+        h: 0,
+        ...shadeFields(shaded, entry.tree.id)
     };
 }
 /**
@@ -105,18 +110,20 @@ function wedgeOf(entry, groupIndex, ring) {
  */
 export const sunburst = (model, options) => {
     warnUnknownOptions(options, 'sunburst');
-    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 } };
     }
     const levels = options.levels ?? 2;
+    // #164: as in `world` — a share per wedge when a measure is named for it.
+    const shaded = options.shadeBy ? shares(root, options.shadeBy) : undefined;
     const placed = [];
     split(root, { a0: 0, a1: Math.PI * 2 }, { levels, out: placed, origin: root.path.length });
     const ring = RADIUS / Math.max(1, levels);
     const extent = (RADIUS + PAD) * 2;
     return {
-        clusters: placed.map((entry, i) => wedgeOf(entry, i, ring)),
+        clusters: placed.map((entry, i) => wedgeOf(entry, i, ring, shaded)),
         cards: {},
         // Edges are absent for the same reason as the treemap: containment IS the relationship,
         // and an adjacency graph cannot be drawn at this scale.

package/dist/layout/types.d.ts

@@ -103,6 +103,30 @@ export type Cluster = {
         a0: number;
         a1: number;
     };
+    /**
+     * A containment box's full path from the tree root, outermost first — its ADDRESS.
+     *
+     * The name repeats across branches (a `table` box under `public` and under `billing`); the
+     * path cannot. Drilling into a box sets `focusPath` to exactly this, and it stays absolute
+     * when the canvas is itself scoped by `focusPath`. Set by the containment layouts only.
+     */
+    path?: string[];
+    /** Whether nothing lies below this box in the data — so only a host loader can go deeper. */
+    leaf?: boolean;
+    /** `polymetric` (#168) — the colour measure as 0..1 of its cap; absent when not bound or missing. */
+    shade?: number;
+    /** `polymetric` — the channels whose measure this box lacks, drawn at the minimum and marked. */
+    missing?: PolymetricChannel[];
+    /** `polymetric` — the channels whose value exceeded the cap and was clamped to the maximum. */
+    clamped?: PolymetricChannel[];
+    /**
+     * The id of the node this box IS, when one is declared — a leaf OR a container.
+     *
+     * `nodeId` is set only on leaves, because only a leaf is selectable; a container that is
+     * also a real node (a module that holds files) needs its identity for drilling, which is
+     * not selection. Undefined on a container nothing declared.
+     */
+    declared?: string;
 };
 /**
  * Which node property a layout groups on. Both already exist on `GraphNode`, so nesting
@@ -126,6 +150,26 @@ export type RoutedEdge = {
      * than the reader wondering why one link behaves differently.
      */
     back?: boolean;
+    /** GraphEdge.overlay — routed after the layout ran, over a picture it did not shape. */
+    overlay?: boolean;
+    /** GraphEdge.weight, raw. `GraphState.edgeWeight` normalises it for drawing. */
+    weight?: number;
+    /** GraphEdge.weakest — the cheapest link to cut in a cycle (#166). */
+    weakest?: boolean;
+    /** GraphEdge.hidden — coupling no import explains (#169). */
+    hidden?: boolean;
+    /** `arcs` — which side of the axis the arc is drawn on (#169). */
+    side?: 'above' | 'below';
+    /**
+     * 0..1 against its OWN set's 95th-percentile weight, clamped past it, when a layout normalises
+     * per set (`arcs`, #169): imports and shared commits are different units, and one outlying
+     * pair should not flatten the rest. Preferred over the global weight scale.
+     */
+    strength?: number;
+    /** GraphEdge.count — how many model edges a condensed edge stands for. */
+    count?: number;
+    /** How the edge sits against the layering (#167) — given by the host or derived by `layers`. */
+    conformance?: import('../types.js').Conformance;
     x1: number;
     y1: number;
     x2: number;
@@ -239,8 +283,47 @@ export type LayoutOptions = {
      * highlight it would silently re-root the diagram.
      */
     root?: string | null;
+    /**
+     * Which edges to draw. `layers`: `violations` keeps just the edges that climb (#167).
+     * `arcs`: `hidden` keeps just the hidden coupling (#169). On a real codebase the ordinary
+     * edges are the vast majority and drown the signal.
+     */
+    showEdges?: ShowEdges;
+    /** `layers` only — band names by layer index. Unnamed layers read "Layer N". */
+    layerLabels?: string[];
+    /** `polymetric` only — the measure box WIDTH encodes. A `measures` key, `weight` or `degree`. */
+    widthBy?: string;
+    /** `polymetric` only — the measure box HEIGHT encodes. */
+    heightBy?: string;
+    /** `polymetric` only — the measure box SHADE encodes. Omit for no colour channel. */
+    colorBy?: string;
+    /**
+     * `arcs` only — the relation drawn on the right of the axis (#169). Omitted, overlays go
+     * right and structural edges left: what the history reveals against what the code declares.
+     */
+    above?: string;
+    /**
+     * `world` / `sunburst` — the measure each box is SHADED by, a share in 0..1 (#164). A
+     * container takes the size-weighted mean of what it holds unless it declares its own.
+     */
+    shadeBy?: string;
+};
+/** Every edge, or only the ones a view is about. */
+export type ShowEdges = 'all' | 'violations' | 'hidden';
+/** The three encodings of the polymetric view (#168). */
+export type PolymetricChannel = 'width' | 'height' | 'color';
+/** Which measure a channel carries, and the value its full extent stands for. */
+export type ChannelScale = {
+    measure: string;
+    cap: number;
 };
 export type LayoutResult = {
+    /** `polymetric` — what each channel encodes, for the legend. */
+    channels?: {
+        width: ChannelScale;
+        height: ChannelScale;
+        color?: ChannelScale;
+    };
     clusters: Cluster[];
     cards: Cards;
     edges: RoutedEdge[];

package/dist/layout/world.js

@@ -17,6 +17,7 @@
  * have to be able to read what you are about to click.
  */
 import { buildTree, findNode } from '../model/tree.js';
+import { shadeFields, shares } from '../model/share.js';
 import { squarify } from './squarify.js';
 import { warnUnknownOptions } from './options.js';
 /** Canvas the layout lays out into. Fit-to-container scales it; the ratios are what matter. */
@@ -89,7 +90,7 @@ function compact(value) {
  * A childless box keeps its node's id and kind, so uniform structure costs no identity: the
  * box is still selectable and still colours by what it is.
  */
-function clusterOf(entry, groupIndex) {
+function clusterOf(entry, groupIndex, shaded) {
     const leaf = entry.tree.children.length === 0 ? entry.tree.node : undefined;
     return {
         name: entry.tree.label,
@@ -101,13 +102,17 @@ function clusterOf(entry, groupIndex) {
         ramp: entry.ramp,
         nodeId: leaf?.id,
         kind: leaf?.kind,
+        path: entry.tree.address,
+        leaf: entry.tree.children.length === 0,
+        declared: entry.tree.node?.id,
         list: entry.tree.children.map((c) => c.node).filter((n) => n !== undefined),
         count: entry.tree.children.length,
         groupIndex,
         x: entry.rect.x,
         y: entry.rect.y,
         w: entry.rect.w,
-        h: entry.rect.h
+        h: entry.rect.h,
+        ...shadeFields(shaded, entry.tree.id)
     };
 }
 /**
@@ -119,11 +124,13 @@ function clusterOf(entry, groupIndex) {
  */
 export const world = (model, options) => {
     warnUnknownOptions(options, 'world');
-    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 } };
     }
+    // #164: a share per box when a measure is named for it; the layout's geometry is unchanged.
+    const shaded = options.shadeBy ? shares(root, options.shadeBy) : undefined;
     const placed = [];
     place(root, { x: 0, y: 0, w: CANVAS.w, h: CANVAS.h }, {
         levels: options.levels ?? 2,
@@ -136,7 +143,7 @@ export const world = (model, options) => {
     // `cards` is empty by construction rather than by filtering — there is no box in this
     // layout that a card could represent.
     return {
-        clusters: placed.map(clusterOf),
+        clusters: placed.map((entry, i) => clusterOf(entry, i, shaded)),
         cards: {},
         edges: [],
         size: CANVAS

package/dist/messages.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Graph's words live in `messages.graph` (`@rokkit/states`), so a locale can replace any of
+ * them. Templates name their values in braces — `Open {name}` — and `fill` puts them in.
+ */
+import { messages } from '@rokkit/states';
+/** The graph namespace of the active locale. Reactive: read it where the text is shown. */
+export type GraphMessages = typeof messages.graph;
+export type GraphMessageKey = keyof GraphMessages;
+/** `template` with each `{token}` replaced; a token with no value stays as written. */
+export declare function fill(template: string, values: Record<string, string | number>): string;
+/** `{n} node` or `{n} nodes`, from the active locale. */
+export declare function counted(n: number, one: GraphMessageKey, many: GraphMessageKey): string;
+/** One graph string, filled. */
+export declare function say(key: GraphMessageKey, values?: Record<string, string | number>): string;

package/dist/messages.js

@@ -0,0 +1,17 @@
+/**
+ * Graph's words live in `messages.graph` (`@rokkit/states`), so a locale can replace any of
+ * them. Templates name their values in braces — `Open {name}` — and `fill` puts them in.
+ */
+import { messages } from '@rokkit/states';
+/** `template` with each `{token}` replaced; a token with no value stays as written. */
+export function fill(template, values) {
+    return template.replace(/\{(\w+)\}/g, (whole, token) => token in values ? String(values[token]) : whole);
+}
+/** `{n} node` or `{n} nodes`, from the active locale. */
+export function counted(n, one, many) {
+    return fill(messages.graph[n === 1 ? one : many], { n });
+}
+/** One graph string, filled. */
+export function say(key, values = {}) {
+    return fill(messages.graph[key], values);
+}

package/dist/model/condense.d.ts

@@ -0,0 +1,8 @@
+import type { GraphModel } from '../types.js';
+/** Every group node, mapped to its members that exist in the model, in the order listed. */
+export declare function groupsOf(model: GraphModel): Map<string, string[]>;
+/**
+ * The model with each group in `collapsed` standing in for its members, and every other group
+ * expanded into them. The model itself when it has no groups.
+ */
+export declare function condense(model: GraphModel, collapsed: Set<string>): GraphModel;

package/dist/model/condense.js

@@ -0,0 +1,114 @@
+import { buildNeighbors } from './normalize.js';
+/** Every group node, mapped to its members that exist in the model, in the order listed. */
+export function groupsOf(model) {
+    const groups = new Map();
+    for (const node of model.nodes) {
+        if (!node.members || node.members.length === 0)
+            continue;
+        groups.set(node.id, node.members.filter((id) => model.byId.has(id)));
+    }
+    return groups;
+}
+/** A collapsed group takes its members' place. */
+function collapseInto(group, members, { into, hidden }) {
+    for (const member of members) {
+        // A member listed in two groups belongs to the first; nesting is not modelled.
+        if (!into.has(member))
+            into.set(member, group);
+        hidden.add(member);
+    }
+}
+function routingFor(groups, collapsed) {
+    const routing = { into: new Map(), hidden: new Set() };
+    for (const [group, members] of groups) {
+        if (collapsed.has(group))
+            collapseInto(group, members, routing);
+        // Expanded, and its members are here: the group gives way to them. With no member in
+        // the model yet it stays — there is nothing to show in its place.
+        else if (members.length > 0)
+            routing.hidden.add(group);
+    }
+    return routing;
+}
+/**
+ * An edge as the condensed view draws it, or null when it has no place there: inside a
+ * collapsed group, or touching something hidden (a pre-aggregated edge to a group that is now
+ * expanded into its members).
+ */
+/** Where an endpoint is drawn: its collapsed group, or itself. */
+const shownAs = (id, into) => into.get(id) ?? id;
+function reroute(edge, { into, hidden }) {
+    const source = shownAs(edge.source, into);
+    const target = shownAs(edge.target, into);
+    if (hidden.has(source) || hidden.has(target))
+        return null;
+    const moved = source !== edge.source || target !== edge.target;
+    if (!moved)
+        return edge;
+    if (source === target)
+        return null;
+    // Row anchors named a member's rows; the group card has none.
+    const { sourceRow: _s, targetRow: _t, ...rest } = edge;
+    return { ...rest, source, target };
+}
+const keyOf = (e) => `${e.source}>${e.target}>${e.kind}>${e.relation ?? ''}`;
+/** Summed weight, or undefined when neither side carries one. */
+const sumWeights = (a, b) => a === undefined && b === undefined ? undefined : (a ?? 0) + (b ?? 0);
+/** Two parallel edges as one: it stands for both, and is no single edge — so not the weakest. */
+function merge(seen, edge, key) {
+    const { weakest: _w, ...rest } = seen;
+    const merged = { ...rest, id: `condensed:${key}`, count: (seen.count ?? 1) + 1 };
+    const weight = sumWeights(seen.weight, edge.weight);
+    if (weight !== undefined)
+        merged.weight = weight;
+    return merged;
+}
+/**
+ * Parallel edges that rerouting created, folded into one: weights summed (when any carries
+ * one), `count` = how many model edges it stands for. A folded edge is no longer any single
+ * edge, so it is not the weakest one either.
+ */
+function fold(edges, original) {
+    const byKey = new Map();
+    edges.forEach((edge, i) => {
+        const key = keyOf(edge);
+        const seen = byKey.get(key);
+        if (seen)
+            byKey.set(key, merge(seen, edge, key));
+        // A rerouted edge is no longer the model edge it came from, so it takes a new id.
+        else
+            byKey.set(key, edge === original[i] ? edge : { ...edge, id: `condensed:${key}` });
+    });
+    return [...byKey.values()];
+}
+function condenseEdges(edges, routing) {
+    const kept = [];
+    const originals = [];
+    for (const edge of edges) {
+        const routed = reroute(edge, routing);
+        if (!routed)
+            continue;
+        kept.push(routed);
+        originals.push(edge);
+    }
+    return fold(kept, originals);
+}
+/**
+ * The model with each group in `collapsed` standing in for its members, and every other group
+ * expanded into them. The model itself when it has no groups.
+ */
+export function condense(model, collapsed) {
+    const groups = groupsOf(model);
+    if (groups.size === 0)
+        return model;
+    const routing = routingFor(groups, collapsed);
+    const nodes = model.nodes.filter((node) => !routing.hidden.has(node.id));
+    const edges = condenseEdges(model.edges, routing);
+    return {
+        nodes,
+        edges,
+        overlays: condenseEdges(model.overlays, routing),
+        byId: new Map(nodes.map((node) => [node.id, node])),
+        neighbors: buildNeighbors(edges)
+    };
+}

package/dist/model/entities.d.ts

@@ -0,0 +1,12 @@
+import type { GraphModel } from '../types.js';
+export type EntityRow = {
+    id: string;
+    label: string;
+    group?: string;
+    kind?: string;
+    rowCount: number;
+    refCount: number;
+    note?: string;
+};
+/** One row per node for an entity list: its rows and the structural edges touching it. */
+export declare function entityRows(model: GraphModel): EntityRow[];