@rokkit/graph 1.8.0 → 1.8.1

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
@@ -130,6 +154,22 @@ export type RoutedEdge = {
     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;
@@ -243,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[];

package/dist/model/entities.js

@@ -0,0 +1,12 @@
+/** One row per node for an entity list: its rows and the structural edges touching it. */
+export function entityRows(model) {
+    return model.nodes.map((node) => ({
+        id: node.id,
+        label: node.label,
+        group: node.group,
+        kind: node.kind,
+        rowCount: node.rows.length,
+        refCount: model.edges.filter((e) => e.source === node.id || e.target === node.id).length,
+        note: node.note
+    }));
+}

package/dist/model/normalize.d.ts

@@ -1,7 +1,3 @@
-import type { GraphFields, GraphModel } from '../types.js';
-/**
- * Resolves a consumer's `nodes`/`edges`/`fields` into the canonical model — ONCE.
- * Everything downstream (layouts, routing, components) sees concrete types, so no
- * field mapping leaks past this function.
- */
+import type { GraphEdge, GraphFields, GraphModel } from '../types.js';
+export declare function buildNeighbors(edges: GraphEdge[]): Map<string, Set<string>>;
 export declare function normalizeGraph(nodes: unknown[], edges: unknown[], fields?: GraphFields): GraphModel;

package/dist/model/normalize.js

@@ -68,7 +68,11 @@ const CLAIMED_NODE_KEYS = [
     'path',
     'measures',
     'rows',
-    'note'
+    'note',
+    'members',
+    'collapsed',
+    'layer',
+    'parent'
 ];
 function buildMeta(source, fields) {
     if (source === null || typeof source !== 'object')
@@ -99,9 +103,27 @@ function buildNode(source, fields) {
         measures: measures(pick(source, fields.measures, 'measures')),
         rows: buildRows(source, fields),
         note: str(pick(source, fields.note, 'note')),
+        ...nodeExtras(source, fields),
         meta: buildMeta(source, fields)
     };
 }
+/**
+ * `members` / `collapsed` (#166) and `layer` (#167), added only when present — like the edge
+ * extras, so every node a consumer already has stays key-for-key identical.
+ */
+function nodeExtras(source, fields) {
+    const extras = {};
+    const layer = num(pick(source, fields.layer, 'layer'));
+    if (layer !== undefined)
+        extras.layer = layer;
+    const members = pick(source, fields.members, 'members');
+    if (Array.isArray(members))
+        extras.members = members.map(String);
+    const collapsed = pick(source, fields.collapsed, 'collapsed');
+    if (typeof collapsed === 'boolean')
+        extras.collapsed = collapsed;
+    return extras;
+}
 function resolveEndpoint(source, spec, byId) {
     const raw = str(pick(source, spec.path, spec.fallbackKey));
     if (raw === undefined)
@@ -210,10 +232,19 @@ function buildEdge(source, fields, byId, seen) {
  * `overlay` and `weight`, added only when present so every edge a v1 consumer already has
  * stays key-for-key identical — `toEqual` on an edge is a contract downstream specs rely on.
  */
+const CONFORMANCE = new Set(['down', 'skip', 'up', 'level']);
 function edgeExtras(source, fields) {
     const extras = {};
+    // Only the vocabulary — an unknown word would be a style hook no theme knows.
+    const conformance = str(pick(source, fields.conformance, 'conformance'));
+    if (conformance && CONFORMANCE.has(conformance))
+        extras.conformance = conformance;
     if (pick(source, fields.overlay, 'overlay'))
         extras.overlay = true;
+    if (pick(source, fields.weakest, 'weakest'))
+        extras.weakest = true;
+    if (pick(source, fields.hidden, 'hidden'))
+        extras.hidden = true;
     const weight = num(pick(source, fields.edgeWeight, 'weight'));
     if (weight !== undefined)
         extras.weight = weight;
@@ -241,7 +272,7 @@ function markForeignKeys(byId, edges) {
         }
     }
 }
-function buildNeighbors(edges) {
+export function buildNeighbors(edges) {
     const neighbors = new Map();
     const link = (a, b) => {
         const set = neighbors.get(a) ?? new Set();
@@ -263,8 +294,39 @@ function buildNeighbors(edges) {
  * Everything downstream (layouts, routing, components) sees concrete types, so no
  * field mapping leaks past this function.
  */
+/** A node's ancestry as ids, root first and itself last — cut where a cycle closes. */
+function chainOf(id, parentOf) {
+    const chain = [id];
+    const seen = new Set(chain);
+    let parent = parentOf.get(id);
+    while (parent !== undefined && !seen.has(parent)) {
+        chain.unshift(parent);
+        seen.add(parent);
+        // A parent that is not a node ends the walk: it is kept as the container it names.
+        parent = parentOf.get(parent);
+    }
+    return chain;
+}
+/**
+ * Containment given as `parent` ids (#168) — the shape many hosts send — becomes a `path`.
+ *
+ * Only for a node with no `path` of its own, and only where the parent relation is in play: a
+ * node that HAS a parent, or that another node names as one (so a root still heads the paths
+ * of its children). Segments are node ids, since labels repeat across branches.
+ */
+function pathsFromParents(built, sources, fields) {
+    const parentOf = new Map();
+    built.forEach((node, i) => parentOf.set(node.id, str(pick(sources[i], fields.parent, 'parent'))));
+    const named = new Set([...parentOf.values()].filter((p) => p !== undefined));
+    for (const node of built) {
+        if (node.path || (parentOf.get(node.id) === undefined && !named.has(node.id)))
+            continue;
+        node.path = chainOf(node.id, parentOf);
+    }
+}
 export function normalizeGraph(nodes, edges, fields = {}) {
     const built = nodes.map((source) => buildNode(source, fields));
+    pathsFromParents(built, nodes, fields);
     const byId = new Map(built.map((node) => [node.id, node]));
     const seen = new Map();
     const resolved = edges

package/dist/model/relationships.d.ts

@@ -0,0 +1,30 @@
+import type { RoutedEdge } from '../layout/types.js';
+import type { GraphEdge, GraphModel } from '../types.js';
+export type Relationship = {
+    direction: 'in' | 'out';
+    id: string;
+    label: string;
+    group?: string;
+    /** The canonical edge — always present. A relationship is a fact about the model. */
+    edge: GraphEdge;
+    /** Routed geometry, present only when the ACTIVE layout placed this edge. */
+    routed?: RoutedEdge;
+};
+/**
+ * The selected node's relationships — every edge touching it, in model order.
+ *
+ * Read from `model.edges`, the canonical unfiltered model, NOT from the layout's edges. A layout
+ * filters: `cluster` drops edges whose endpoints were not laid out, and `neighborhood` lays out
+ * only the focus's neighbourhood. Since `focus` and `value` are independent, reading the
+ * layout's edges lets the state contradict itself: with `focus: 'audit.log'` (no neighbours) and
+ * `value: 'public.orders'`, `relationships` would be `[]` while the entity row's `refCount` for
+ * the same node is 1.
+ *
+ * Routed geometry is attached opportunistically — only for edges the active layout placed. A
+ * relationship is a fact about the model; its geometry is a fact about the current view.
+ *
+ * An UNPLACED far end is reported too, with the raw name as the label — it is not a node, so
+ * there is nothing to look up. Hiding it would be worse: "this references something we have not
+ * indexed" is exactly what a reader of a partial graph needs to see.
+ */
+export declare function relationshipsOf(model: GraphModel, id: string | null, routedEdges: RoutedEdge[]): Relationship[];

package/dist/model/relationships.js

@@ -0,0 +1,51 @@
+/** How `id` sits on an edge: not on it, both ends of it, or one end with a far side. */
+function endpointsFor(edge, id) {
+    const isSource = edge.source === id;
+    const isTarget = edge.target === id;
+    if (!isSource && !isTarget)
+        return null;
+    return {
+        self: isSource && isTarget,
+        other: isSource ? edge.target : edge.source,
+        direction: isSource ? 'out' : 'in'
+    };
+}
+/**
+ * The selected node's relationships — every edge touching it, in model order.
+ *
+ * Read from `model.edges`, the canonical unfiltered model, NOT from the layout's edges. A layout
+ * filters: `cluster` drops edges whose endpoints were not laid out, and `neighborhood` lays out
+ * only the focus's neighbourhood. Since `focus` and `value` are independent, reading the
+ * layout's edges lets the state contradict itself: with `focus: 'audit.log'` (no neighbours) and
+ * `value: 'public.orders'`, `relationships` would be `[]` while the entity row's `refCount` for
+ * the same node is 1.
+ *
+ * Routed geometry is attached opportunistically — only for edges the active layout placed. A
+ * relationship is a fact about the model; its geometry is a fact about the current view.
+ *
+ * An UNPLACED far end is reported too, with the raw name as the label — it is not a node, so
+ * there is nothing to look up. Hiding it would be worse: "this references something we have not
+ * indexed" is exactly what a reader of a partial graph needs to see.
+ */
+export function relationshipsOf(model, id, routedEdges) {
+    if (!id)
+        return [];
+    // A plain Map on purpose: a call-local lookup, discarded when the caller re-derives.
+    const routed = new Map(routedEdges.map((e) => [e.id, e]));
+    const describe = (other, direction, edge) => {
+        // normalizeGraph drops any edge whose endpoints do not resolve, so both ends of every
+        // edge in model.edges are in byId. No `?? other` fallback: an unreachable branch cannot
+        // be tested, and the package's 100% statement bar exists to keep that honest.
+        const node = model.byId.get(other);
+        return { direction, id: other, label: node.label, group: node.group, edge, routed: routed.get(edge.id) };
+    };
+    return model.edges.flatMap((edge) => {
+        const ends = endpointsFor(edge, id);
+        if (!ends)
+            return [];
+        if (ends.self)
+            return [describe(id, 'out', edge)];
+        const { other, direction } = ends;
+        return edge.unplaced ? [{ direction, id: other, label: other, edge }] : [describe(other, direction, edge)];
+    });
+}

package/dist/model/share.d.ts

@@ -0,0 +1,9 @@
+import type { TreeNode } from './tree.js';
+import type { Cluster } from '../layout/types.js';
+/** Every box's share of `measure`, by tree id. A box with none is absent from the map. */
+export declare function shares(root: TreeNode, measure: string): Map<string, number>;
+/**
+ * What a box carries for the shade channel: its share, or — when shading is on and it has
+ * none — a mark that the value is missing, so the theme never paints it as a zero.
+ */
+export declare function shadeFields(all: Map<string, number> | undefined, id: string): Pick<Cluster, 'shade' | 'missing'>;

package/dist/model/share.js

@@ -0,0 +1,43 @@
+const clamp = (value) => Math.min(1, Math.max(0, value));
+/** The box's own share, when its node declares one. */
+const ownShare = (box, measure) => {
+    const value = box.node?.measures?.[measure];
+    return value === undefined ? undefined : clamp(value);
+};
+/** The mean of the children's shares, weighted by their size; a plain mean if none has size. */
+function meanOf(children) {
+    if (children.length === 0)
+        return undefined;
+    const weight = children.reduce((total, child) => total + Math.max(0, child.size), 0);
+    if (weight === 0)
+        return children.reduce((total, child) => total + child.share, 0) / children.length;
+    return children.reduce((total, child) => total + child.share * Math.max(0, child.size), 0) / weight;
+}
+function visit(box, measure, out) {
+    const measured = [];
+    for (const child of box.children) {
+        const share = visit(child, measure, out);
+        if (share !== undefined)
+            measured.push({ share, size: child.value });
+    }
+    const share = ownShare(box, measure) ?? meanOf(measured);
+    if (share !== undefined)
+        out.set(box.id, share);
+    return share;
+}
+/** Every box's share of `measure`, by tree id. A box with none is absent from the map. */
+export function shares(root, measure) {
+    const out = new Map();
+    visit(root, measure, out);
+    return out;
+}
+/**
+ * What a box carries for the shade channel: its share, or — when shading is on and it has
+ * none — a mark that the value is missing, so the theme never paints it as a zero.
+ */
+export function shadeFields(all, id) {
+    if (!all)
+        return {};
+    const share = all.get(id);
+    return share === undefined ? { missing: ['color'] } : { shade: share };
+}