@rokkit/graph 1.8.0 → 1.8.1

package/dist/GraphState.svelte.js

@@ -2,66 +2,21 @@ import { SvelteSet } from 'svelte/reactivity';
 import { normalizeGraph } from './model/normalize.js';
 import { layouts } from './layout/index.js';
 import { buildEdges, edgePath } from './layout/edges.js';
-import { nodeShapeOf } from './layout/options.js';
+import { appliesTo, nodeShapeOf } from './layout/options.js';
 import { arcPath } from './layout/arc.js';
-import { defaultGraphPreset, resolveGroupStyles } from './preset.js';
-const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
-/** 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'
-    };
-}
-/**
- * One edge's contribution to the selected node's relationship list.
- *
- * An UNPLACED edge is reported too, with the raw name as the label — the far end 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.
- */
-function describeEdge(edge, id, describe) {
-    const ends = endpointsFor(edge, id);
-    if (!ends)
-        return [];
-    if (ends.self)
-        return [describe(id, 'out', edge)];
-    const { other, direction } = ends;
-    // An unplaced far end is not a node, so there is nothing to look up: the raw name IS
-    // the label. Reported rather than hidden — "references something not indexed" is what a
-    // reader of a partial graph most needs to see.
-    return edge.unplaced
-        ? [{ direction, id: other, label: other, edge }]
-        : [describe(other, direction, edge)];
-}
-/** Bottom-right extent of a set of boxes, or {0,0} when there are none. */
-function extentOf(boxes) {
-    let w = 0;
-    let h = 0;
-    for (const box of boxes) {
-        w = Math.max(w, box.x + box.w);
-        h = Math.max(h, box.y + box.h);
-    }
-    return { w, h };
-}
-/**
- * The store. Turns raw `nodes`/`edges`/`fields` into the reactive shape the visuals
- * render, and owns every transition.
- *
- * Components read from this and call its methods — they never compute. That is what
- * lets the geometry, badge derivation and selection logic be covered exhaustively
- * with no DOM, and lets the component specs assert only attributes.
- *
- * `update()` is re-callable and FULLY re-applies config rather than merging deltas,
- * matching `SparkState.update` — so a prop reverting to undefined actually reverts.
- * Deliberately NOT `PlotState.update`, which guards each field with
- * `if (config.X !== undefined)` and therefore merges.
- */
+import { resolveGroupStyles, resolveShade } from './preset.js';
+import { entityRows } from './model/entities.js';
+import { contentExtent } from './layout/extent.js';
+import { GraphConfig } from './state/GraphConfig.svelte.js';
+import { GraphSelection } from './state/GraphSelection.svelte.js';
+import { GraphDrill } from './state/GraphDrill.svelte.js';
+import { GraphGroups } from './state/GraphGroups.svelte.js';
+import { condense } from './model/condense.js';
+import { channelRows, diagramLabel, drillErrorText, moreRowsLabel, sideNames } from './state/text.js';
+import { INTENTS, isIntent } from './state/intents.js';
+import { say } from './messages.js';
+/** A presence attribute: `''` when on, absent when off. */
+const flag = (on) => (on ? '' : undefined);
 /**
  * Sorted unique strings, dropping empties.
  *
@@ -69,68 +24,73 @@ function extentOf(boxes) {
  * sorted anyway, so the Set would be an extra structure for nothing — and a plain Set inside a
  * reactive class is exactly what `svelte/prefer-svelte-reactivity` is right to flag.
  */
-/**
- * A level cap, or nothing.
- *
- * Left UNDEFINED when the caller said nothing: a state-level default of 2 is indistinguishable
- * from an explicit 2, and `radial` needs "no cap" to mean the whole tree — inventing a number
- * here silently pruned a codebase dendrogram to two rings.
- */
-function floorLevels(levels) {
-    return levels === undefined ? undefined : Math.max(1, Math.floor(levels));
-}
 function unique(values) {
     return values
         .filter((v) => Boolean(v))
         .sort()
         .filter((v, i, all) => i === 0 || v !== all[i - 1]);
 }
+/**
+ * The store. Turns raw `nodes`/`edges`/`fields` into the reactive shape the visuals
+ * render, and owns every transition.
+ *
+ * Components read from this and call its methods — they never compute. That is what
+ * lets the geometry, badge derivation and selection logic be covered exhaustively
+ * with no DOM, and lets the component specs assert only attributes.
+ *
+ * A composition: `config` (every input, `state/GraphConfig`) feeds the layout pipeline
+ * derived here; the selection and the view queries read both. `update()` FULLY re-applies
+ * config rather than merging deltas — so a prop reverting to undefined actually reverts;
+ * `apply()` merges.
+ */
 export class GraphState {
-    #nodes = $state([]);
-    #edges = $state([]);
-    #fields = $state({});
-    #layout = $state('flow');
-    #groupTint = $state(false);
-    #radialMode = $state('tree');
-    #root = $state(null);
-    #bundleTension = $state(undefined);
-    /** The last FULL config, so `apply` can merge over it rather than reset around it. */
-    #last = {};
-    #density = $state('keys');
-    #arrange = $state('untangle');
-    #groupBy = $state('group');
-    #nestBy = $state(null);
-    #sizeBy = $state('degree');
-    #sizeScale = $state('linear');
-    #depth = $state(1);
-    #focusPath = $state([]);
-    #levels = $state(undefined);
-    #edgeStyle = $state('curved');
-    #focus = $state(null);
-    #value = $state(null);
-    #expanded = new SvelteSet();
-    #preset = $state(defaultGraphPreset);
-    #mode = $state('light');
-    #label = $state(undefined);
-    #onselect = $state(undefined);
-    #model = $derived(normalizeGraph(this.#nodes, this.#edges, this.#fields));
-    #layoutFn = $derived(typeof this.#layout === 'function' ? this.#layout : (layouts[this.#layout] ?? layouts.cluster));
+    /** Every input — see `CONFIG_FIELDS` for what each omitted key falls back to. */
+    config = new GraphConfig();
+    /** Which subtree is the canvas, and the host events for moving it (#165). */
+    drill = new GraphDrill({
+        config: this.config,
+        model: () => this.#model,
+        layoutName: () => this.layoutName
+    });
+    /** What the reader picked and opened. */
+    selection = new GraphSelection({
+        model: () => this.#model,
+        routedEdges: () => this.#result.edges,
+        onselect: () => this.config.onselect
+    });
+    /** The model as normalised — every group AND every member. */
+    #canonical = $derived(normalizeGraph(this.config.nodes, this.config.edges, this.config.fields));
+    /** Which groups are collapsed (#166). */
+    groups = new GraphGroups({
+        model: () => this.#canonical,
+        config: this.config
+    });
+    /** What is drawn: the canonical model with each collapsed group standing in for its members. */
+    #model = $derived(condense(this.#canonical, this.groups.collapsed));
+    #layoutFn = $derived(typeof this.config.layout === 'function' ? this.config.layout : (layouts[this.config.layout] ?? layouts.cluster));
     #result = $derived(this.#layoutFn(this.#model, {
-        density: this.#density,
-        arrange: this.#arrange,
-        groupBy: this.#groupBy,
-        nestBy: this.#nestBy ?? undefined,
-        sizeBy: this.#sizeBy,
-        sizeScale: this.#sizeScale,
-        depth: this.#depth,
-        focusPath: this.#focusPath,
-        levels: this.#levels,
-        radialMode: this.#radialMode,
-        root: this.#root,
-        bundleTension: this.#bundleTension,
-        edgeStyle: this.#edgeStyle,
-        focus: this.#focus ?? this.#value,
-        expanded: this.#expanded
+        density: this.config.density,
+        arrange: this.config.arrange,
+        groupBy: this.config.groupBy,
+        nestBy: this.config.nestBy ?? undefined,
+        sizeBy: this.config.sizeBy,
+        sizeScale: this.config.sizeScale,
+        depth: this.config.depth,
+        focusPath: this.config.focusPath,
+        levels: this.config.levels,
+        radialMode: this.config.radialMode,
+        root: this.config.root,
+        bundleTension: this.config.bundleTension,
+        showEdges: this.config.showEdges,
+        layerLabels: this.config.layerLabels,
+        widthBy: this.config.widthBy,
+        heightBy: this.config.heightBy,
+        colorBy: this.config.colorBy,
+        above: this.config.above,
+        shadeBy: this.config.shadeBy,
+        edgeStyle: this.config.edgeStyle,
+        focus: this.config.focus ?? this.selection.value,
+        expanded: this.selection.expanded
     }));
     /**
      * Overlay edges routed over the finished layout. The layout never saw them — that is the
@@ -146,60 +106,8 @@ export class GraphState {
     // Duplicates are left in on purpose: `resolveGroupStyles` de-duplicates and sorts, because
     // that is where ramp assignment lives. A Set here would be a second, redundant de-dup.
     #groups = $derived(this.#model.nodes.map((n) => n.group).filter((g) => Boolean(g)));
-    #groupStyles = $derived(resolveGroupStyles(this.#groups, this.#mode, this.#preset));
-    #related = $derived(this.#value
-        ? new SvelteSet(this.#model.neighbors.get(this.#value) ?? [])
-        : new SvelteSet());
-    #entities = $derived(this.#model.nodes.map((node) => ({
-        id: node.id,
-        label: node.label,
-        group: node.group,
-        kind: node.kind,
-        rowCount: node.rows.length,
-        refCount: this.#model.edges.filter((e) => e.source === node.id || e.target === node.id)
-            .length,
-        note: node.note
-    })));
-    #entity = $derived(this.#value ? (this.#model.byId.get(this.#value) ?? null) : null);
-    /**
-     * Derived from `#model.edges` — the canonical, unfiltered model — NOT from `#result.edges`.
-     *
-     * A layout filters: `cluster` drops edges whose endpoints were not laid out, and
-     * `neighborhood` lays out only the focus node's 1-hop neighbourhood. Since `focus` and
-     * `value` are independent config fields, reading the layout's edges lets the state
-     * contradict itself: with `focus: 'audit.log'` (no neighbours) and `value: 'public.orders'`,
-     * `relationships` would be `[]` while `entities`' `refCount` for the same node is 1.
-     *
-     * Routed geometry is attached opportunistically — it exists only for edges the active layout
-     * actually placed, so `routed` is optional on `Relationship`. A relationship is a fact about
-     * the model; its geometry is a fact about the current view.
-     */
-    #relationships = $derived.by(() => {
-        const id = this.#value;
-        if (!id)
-            return [];
-        // A plain Map on purpose: a call-local lookup built once from an already-derived array
-        // and discarded when this derivation re-runs. Nothing outside can observe it, so
-        // SvelteMap would add proxying for no reactivity.
-        // eslint-disable-next-line svelte/prefer-svelte-reactivity
-        const routed = new Map(this.#result.edges.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 here: an
-            // unreachable branch cannot be tested, and the package's 100% statement bar
-            // exists to keep that honest.
-            const node = this.#model.byId.get(other);
-            return {
-                direction,
-                id: other,
-                label: node.label,
-                group: node.group,
-                edge,
-                routed: routed.get(edge.id)
-            };
-        };
-        return this.#model.edges.flatMap((edge) => describeEdge(edge, id, describe));
-    });
+    #groupStyles = $derived(resolveGroupStyles(this.#groups, this.config.mode, this.config.preset));
+    #entities = $derived(entityRows(this.#model));
     constructor(config = {}) {
         this.update(config);
     }
@@ -211,13 +119,16 @@ export class GraphState {
      * field by field.
      */
     update(config = {}) {
-        this.#last = config;
-        this.#applyData(config);
-        this.#applyView(config);
-        // `value` is input AND output, so it is only adopted when the caller supplies
-        // one — otherwise a re-render would wipe a selection the user just made.
+        this.config.update(config);
+        this.#adoptValue(config);
+    }
+    /**
+     * `value` is input AND output, so it is only adopted when the caller supplies one —
+     * otherwise a re-render would wipe a selection the user just made.
+     */
+    #adoptValue(config) {
         if (config.value !== undefined)
-            this.#value = config.value;
+            this.selection.adopt(config.value);
     }
     /**
      * Merge a partial config, leaving every key it does not name alone.
@@ -228,85 +139,102 @@ export class GraphState {
      * owner's data on every keystroke. This merges over the last full config instead.
      */
     apply(config) {
-        this.update({ ...this.#last, ...config });
-    }
-    #applyData(config) {
-        this.#nodes = config.nodes ?? [];
-        this.#edges = config.edges ?? [];
-        this.#fields = config.fields ?? {};
-        this.#layout = config.layout ?? 'flow';
-        this.#focus = config.focus ?? null;
-    }
-    /** How the boxes are organised — one axis, or one subdivided by a second. */
-    #applyGrouping(config) {
-        const outer = config.groupBy ?? 'group';
-        this.#groupBy = outer;
-        // Rejected rather than rendered: a box subdivided by its OWN axis yields exactly one
-        // child containing everything, which reads as a rendering fault, not a no-op.
-        this.#nestBy = config.nestBy === outer ? null : (config.nestBy ?? null);
-        this.#groupTint = config.groupTint ?? false;
-    }
-    /** What a node's size encodes, and how far a neighbourhood reaches. */
-    #applyMeasure(config) {
-        this.#sizeBy = config.sizeBy ?? 'degree';
-        this.#sizeScale = config.sizeScale ?? 'linear';
-        // Floored at 1: a depth of 0 or -1 is a request for nothing, and returning an empty
-        // canvas for it looks identical to a broken focus.
-        this.#depth = Math.max(1, Math.floor(config.depth ?? 1));
-        this.#focusPath = config.focusPath ?? [];
-        this.#levels = floorLevels(config.levels);
-        this.#root = config.root ?? null;
-        this.#bundleTension = config.bundleTension;
-        this.#radialMode = config.radialMode ?? 'tree';
-    }
-    #applyView(config) {
-        this.#density = config.density ?? 'keys';
-        this.#arrange = config.arrange ?? 'untangle';
-        this.#applyGrouping(config);
-        this.#applyMeasure(config);
-        this.#edgeStyle = config.edgeStyle ?? 'curved';
-        this.#preset = config.preset ?? defaultGraphPreset;
-        this.#mode = config.mode ?? 'light';
-        this.#label = config.label;
-        this.#onselect = config.onselect;
+        this.#adoptValue(this.config.apply(config));
     }
     // ─── transitions ───────────────────────────────────────────────────────────
     select(id) {
-        this.#value = id;
-        this.#onselect?.(id);
+        this.selection.select(id);
+    }
+    /** Drop the selection and report `null` — see `GraphSelection.clear`. */
+    clear() {
+        this.selection.clear();
+    }
+    /** Show one node's rows in full, whatever the density says — see `GraphSelection`. */
+    toggleExpanded(id) {
+        this.selection.toggleExpanded(id);
+    }
+    isExpanded(id) {
+        return this.selection.isExpanded(id);
+    }
+    // ─── groups (#166) — see GraphGroups ────────────────────────────────────────
+    isGroup(id) {
+        return this.groups.isGroup(id);
+    }
+    isCollapsed(id) {
+        return this.groups.isCollapsed(id);
+    }
+    memberCount(id) {
+        return this.groups.memberCount(id);
+    }
+    groupOf(id) {
+        return this.groups.groupOf(id);
     }
     /**
-     * Drop the selection, and SAY SO.
-     *
-     * Found by dbd consuming the package: it owns `selected` in its route and branches on it
-     * to show the entity panel, so a silent clear left that panel open over nothing. A
-     * controlled consumer cannot observe an internal `#value` — the callback is the only
-     * channel, which is why it carries `null` rather than being skipped.
-     *
-     * Guarded on an actual change, or a background click on an already-empty canvas
-     * round-trips through the consumer's setter on every stray click.
+     * Expand or collapse a group. Collapsing one whose member is selected moves the selection to
+     * the group: the thing being looked at is now inside it, and a selection naming a hidden node
+     * would leave the entity panel empty for no visible reason.
      */
-    clear() {
-        if (this.#value === null)
-            return;
-        this.#value = null;
-        this.#onselect?.(null);
+    toggleGroup(id) {
+        const collapsing = this.groups.isGroup(id) && !this.groups.isCollapsed(id);
+        const selected = this.value;
+        const holdsSelection = collapsing && selected !== null && this.groups.groupOf(selected) === id;
+        if (!this.groups.toggle(id))
+            return false;
+        if (holdsSelection)
+            this.select(id);
+        return true;
+    }
+    /** The selection's group action — what a drill bar offers. */
+    get groupAction() {
+        return this.groups.actionFor(this.value);
+    }
+    // ─── drilling (#165) — see GraphDrill ───────────────────────────────────────
+    get drillPath() {
+        return this.drill.path;
+    }
+    get breadcrumbs() {
+        return this.drill.breadcrumbs;
+    }
+    /** A drill's handler returned a promise that has not settled. */
+    get pending() {
+        return this.drill.pending;
+    }
+    get drillError() {
+        return this.drill.error;
+    }
+    canDrill(box) {
+        return this.drill.canDrill(box);
+    }
+    drillInto(box) {
+        return this.drill.drillInto(box);
+    }
+    drillOut(levels = 1) {
+        return this.drill.drillOut(levels);
+    }
+    drillTo(path) {
+        return this.drill.drillTo(path);
     }
     /**
-     * Show one node's rows in full, whatever the density says.
-     *
-     * Per NODE rather than a global density change: a reader who clicks "+3 more" on one
-     * card is asking about that card, and expanding all of them answers a question they did
-     * not ask — on a large diagram it also relayouts everything under them.
+     * The selected box, when it can be opened — what a drill bar's "Open" acts on. The keyboard
+     * route into a leaf: Enter selects it, and this is the next step.
      */
-    toggleExpanded(id) {
-        if (this.#expanded.has(id))
-            this.#expanded.delete(id);
-        else
-            this.#expanded.add(id);
+    /** The failed drill, worded for the reader; null when the last drill did not fail. */
+    get drillErrorText() {
+        return drillErrorText(this.drillError);
     }
-    isExpanded(id) {
-        return this.#expanded.has(id);
+    get drillTarget() {
+        const value = this.value;
+        if (!value)
+            return null;
+        return this.clusters.find((c) => c.nodeId === value && this.canDrill(c)) ?? null;
+    }
+    /** Whether a drill bar has anything to show: a trail, a load, a failure, or a box to open. */
+    get showsDrillBar() {
+        return (this.drillPath.length > 0 ||
+            this.pending ||
+            this.drillError !== null ||
+            this.drillTarget !== null ||
+            this.groupAction !== null);
     }
     /**
      * The more-row's text, or null when the card is hiding nothing and needs no control.
@@ -321,14 +249,7 @@ export class GraphState {
      * answer to what was asked, not a filter that matched nothing.
      */
     moreLabel(id) {
-        if (this.#expanded.has(id))
-            return 'show less';
-        const card = this.cards[id];
-        if (!card || card.more <= 0)
-            return null;
-        if (this.#density !== 'keys' || card.vis.length > 0)
-            return `+ ${card.more} more`;
-        return `no keys · ${card.more} ${card.more === 1 ? 'row' : 'rows'}`;
+        return moreRowsLabel(this.selection.isExpanded(id), this.cards[id], this.config.density);
     }
     /**
      * Change the detail level from inside the component.
@@ -338,25 +259,40 @@ export class GraphState {
      * prop would render, click, and change nothing.
      */
     setDensity(density) {
-        this.#density = density;
+        this.config.setDensity(density);
+    }
+    /** Every edge or only the climbing ones — what `ViolationsControl` drives (#167). */
+    setShowEdges(value) {
+        this.config.setShowEdges(value);
+    }
+    get showEdges() {
+        return this.config.showEdges;
     }
     // ─── per-item lookups the templates need ───────────────────────────────────
+    /**
+     * In `neighborhood`, the selection IS the focus (it defaults to it), and the canvas is built
+     * from adjacency to the focus — so every card is "related" and every edge "highlight" by
+     * construction, and ring 2 is "dim" for being the ring the reader asked for (#172). Those
+     * states would say nothing, so they are withheld; a selected NEIGHBOUR still lights its own.
+     */
+    get #selectingFocus() {
+        const value = this.value;
+        return this.layoutName === 'neighborhood' && value !== null && (this.config.focus ?? value) === value;
+    }
     nodeState(id) {
-        if (!this.#value)
-            return null;
-        if (id === this.#value)
-            return 'selected';
-        return this.#related.has(id) ? 'related' : 'dim';
+        if (this.#selectingFocus)
+            return id === this.value ? 'selected' : null;
+        return this.selection.nodeState(id);
     }
     edgeState(edge) {
-        if (!this.#value)
+        if (this.#selectingFocus)
             return null;
-        return edge.fromKey === this.#value || edge.toKey === this.#value ? 'highlight' : 'dim';
+        return this.selection.edgeState(edge);
     }
     edgePath(edge) {
         // A layout that knows more than the endpoints builds its own — a bundled edge follows
         // the whole chain of ancestors between them, which `edgePath` never sees.
-        return edge.path ?? edgePath(edge, this.#edgeStyle);
+        return edge.path ?? edgePath(edge, this.config.edgeStyle);
     }
     groupStyle(group) {
         return (group && this.#groupStyles.get(group)) || {};
@@ -368,6 +304,35 @@ export class GraphState {
      * Doing that inline put the same map/join in two places in `Graph.svelte` — a derivation
      * living in a component, which is the one thing this layer exists to prevent.
      */
+    /** Whether shading is on: a measure is named, and the active layout reads it (#164). */
+    get #shading() {
+        return Boolean(this.config.shadeBy) && appliesTo(this.layoutName, 'shadeBy');
+    }
+    #shaded(cluster) {
+        return this.#shading && cluster.shade !== undefined;
+    }
+    /**
+     * A box's paint as a style attribute: the shade ramp's step for its share when shading
+     * (#164), else its group's colour. Custom properties, so a theme still has the last word.
+     */
+    boxStyleAttr(cluster) {
+        if (!this.#shaded(cluster))
+            return this.groupStyleAttr(cluster.ramp ?? cluster.name);
+        return Object.entries(resolveShade(cluster.shade, this.config.mode, this.config.preset))
+            .map(([property, value]) => `${property}:${value}`)
+            .join(';');
+    }
+    /** What a legend says about the shade: the measure and the ramp's two ends, or null. */
+    get shadeLegend() {
+        if (!this.#shading)
+            return null;
+        const { mode, preset } = this.config;
+        return {
+            measure: this.config.shadeBy,
+            low: resolveShade(0, mode, preset)['--group-fill'],
+            high: resolveShade(1, mode, preset)['--group-fill']
+        };
+    }
     groupStyleAttr(group) {
         return Object.entries(this.groupStyle(group))
             .map(([property, value]) => `${property}:${value}`)
@@ -406,9 +371,13 @@ export class GraphState {
     }
     /**
      * An edge's weight as 0..1 of the heaviest weighted edge, for stroke width — or undefined
-     * for an edge with no weight, which draws at the theme's normal width.
+     * for an edge with no weight, which draws at the theme's normal width. A layout's own
+     * per-set `strength` wins.
      */
     edgeWeight(edge) {
+        // A layout that scales each set to its own heaviest (`arcs`) has already said.
+        if (edge.strength !== undefined)
+            return edge.strength;
         if (edge.weight === undefined || this.#maxEdgeWeight <= 0)
             return undefined;
         return edge.weight / this.#maxEdgeWeight;
@@ -427,32 +396,19 @@ export class GraphState {
      * stay in the component. Keeping this here is what lets it be tested without a renderer.
      */
     get contentSize() {
-        const clusters = this.#result.clusters.map((c) => ({
-            x: c.x,
-            y: c.y,
-            w: c.w ?? 0,
-            h: c.h ?? 0
-        }));
-        let { w, h } = extentOf(clusters);
-        // An ungrouped layout (neighborhood) reports no clusters, so fall back to the cards.
-        if (!w || !h) {
-            const cards = extentOf(Object.values(this.#result.cards));
-            w = Math.max(w, cards.w);
-            h = Math.max(h, cards.h);
-        }
-        return { w: w || this.#result.size.w, h: h || this.#result.size.h };
+        return contentExtent(this.#result.clusters, this.#result.cards, this.#result.size);
     }
     get related() {
-        return this.#related;
+        return this.selection.related;
     }
     get entities() {
         return this.#entities;
     }
     get entity() {
-        return this.#entity;
+        return this.selection.entity;
     }
     get relationships() {
-        return this.#relationships;
+        return this.selection.relationships;
     }
     /**
      * Edges the field map could not place at one or both ends.
@@ -466,19 +422,11 @@ export class GraphState {
         return this.#model.edges.filter((e) => e.unplaced !== undefined);
     }
     get density() {
-        return this.#density;
+        return this.config.density;
     }
     get arrange() {
-        return this.#arrange;
+        return this.config.arrange;
     }
-    /**
-     * A cluster's unique render key.
-     *
-     * NOT the name: nesting puts a `table` box under `public` AND under `billing`, and keying
-     * an `{#each}` by name alone is a duplicate key — Svelte throws `each_key_duplicate`, the
-     * render aborts, and no inner box appears at all, which reads as nesting silently not
-     * working rather than as an error.
-     */
     /**
      * The SVG path for a wedge-shaped box, centred on the canvas.
      *
@@ -498,18 +446,148 @@ export class GraphState {
      */
     boxAttrs(cluster) {
         return {
+            ...this.#boxIntent(cluster),
+            // #164: painted from the shade ramp rather than its group's colour.
+            'data-graph-shaded': flag(this.#shaded(cluster)),
             'data-cluster-depth': String(cluster.depth ?? 0),
+            // polymetric (#168): the channels a box could not show — missing data, or past the cap.
+            'data-graph-missing': cluster.missing?.join(' '),
+            'data-graph-clamped': cluster.clamped?.join(' '),
             'data-node-group': cluster.name,
             'data-graph-node-id': cluster.nodeId,
             'data-node-kind': cluster.kind,
             'data-node-state': cluster.nodeId ? this.nodeState(cluster.nodeId) : undefined
         };
     }
+    /**
+     * What a press and a double-click on a box mean (see `state/intents`): a leaf selects, and
+     * opens into its level; a container that can be drilled opens on press; a region does
+     * neither. The label says so for assistive tech.
+     */
+    #boxIntent(cluster) {
+        if (cluster.nodeId) {
+            const key = cluster.nodeId;
+            return { 'data-graph-press': 'select', 'data-graph-open': 'drill', 'data-graph-key': key, 'aria-label': this.caption(cluster) };
+        }
+        if (!this.canDrill(cluster))
+            return {};
+        return {
+            'data-graph-drillable': '',
+            'data-graph-press': 'drill',
+            'data-graph-key': this.clusterKey(cluster),
+            'aria-label': say('open', { name: this.caption(cluster) })
+        };
+    }
+    /** Whether a box takes the pointer and the keyboard: it has an intent. */
+    interactive(cluster) {
+        return Boolean(cluster.nodeId) || this.canDrill(cluster);
+    }
+    /** A box's visible caption: its name, and the layout's caption or its count. */
+    caption(cluster) {
+        return `${cluster.name} · ${cluster.caption ?? cluster.count}`;
+    }
+    /**
+     * A node card's hooks and intents: it selects on press, and folds or opens its group on open
+     * (#166). A card with nothing below its head — no rows shown, none to reveal, not a group —
+     * is marked head-only so the theme can drop the empty body.
+     */
+    cardAttrs(key) {
+        return {
+            ...this.#cardNodeAttrs(key),
+            ...this.#cardGroupAttrs(key),
+            'data-graph-press': 'select',
+            'data-graph-open': 'group',
+            'data-graph-key': key
+        };
+    }
+    #cardNodeAttrs(key) {
+        const card = this.cards[key];
+        const headOnly = card !== undefined && card.vis.length === 0 && card.more <= 0 && !this.isGroup(key);
+        return {
+            'data-node-kind': card?.node.kind,
+            'data-node-group': card?.node.group,
+            'data-node-state': this.nodeState(key) ?? undefined,
+            'data-node-headonly': flag(headOnly)
+        };
+    }
+    #cardGroupAttrs(key) {
+        return {
+            'data-graph-group': flag(this.isGroup(key)),
+            'data-graph-collapsed': flag(this.isCollapsed(key)),
+            'data-graph-member-of': this.groupOf(key) ?? undefined
+        };
+    }
+    /** What a card's head counts: a group, the members it stands for; anything else, its rows. */
+    cardCount(key) {
+        return this.isGroup(key) ? this.memberCount(key) : (this.cards[key]?.node.rows.length ?? 0);
+    }
+    /** The "more rows" control's hooks: it expands the card, and says when a filter emptied it. */
+    moreAttrs(key) {
+        const expanded = this.isExpanded(key);
+        return {
+            'data-graph-press': 'expand',
+            'data-graph-key': key,
+            'data-graph-more-empty': flag(this.cards[key]?.vis.length === 0 && !expanded),
+            'data-expanded': flag(expanded)
+        };
+    }
+    /**
+     * The box a `data-graph-key` names, if it is on the canvas: a container by its render key,
+     * a leaf by its node id — the one key a leaf carries for both its press and its open.
+     */
+    boxFor(key) {
+        return this.clusters.find((cluster) => cluster.nodeId === key || this.clusterKey(cluster) === key);
+    }
+    /**
+     * Perform an intent read off the DOM (see `state/intents`). An unknown intent, or a key
+     * that names nothing, does nothing — the DOM is not a trusted source.
+     */
+    act(intent, key) {
+        if (!isIntent(intent))
+            return;
+        INTENTS[intent](this, key ?? '');
+    }
+    /**
+     * A cluster's unique render key.
+     *
+     * NOT the name: nesting puts a `table` box under `public` AND under `billing`, and keying
+     * an `{#each}` by name alone is a duplicate key — Svelte throws `each_key_duplicate`, the
+     * render aborts, and no inner box appears at all, which reads as nesting silently not
+     * working rather than as an error.
+     */
     clusterKey(cluster) {
+        // A containment box's PATH is its address, unique by construction; the parent's label is
+        // not — `lib/marks` under `geoms` and under `src` share depth, parent label and name.
+        // A pathless box (an orphan node at the root, or a group box) keeps the label key.
+        if (cluster.path && cluster.path.length > 0)
+            return `path:${cluster.path.join('/')}`;
         return `${cluster.depth ?? 0}:${cluster.parent ?? ''}:${cluster.name}`;
     }
+    /** `polymetric` — which measure is on which channel, and each one's cap; for the legend. */
+    get channels() {
+        return this.#result.channels;
+    }
+    /** The polymetric legend's rows, labelled from the locale (#168). */
+    get channelRows() {
+        return channelRows(this.#result.channels);
+    }
+    /** What each side of an arc diagram shows, named from the data or the locale (#169). */
+    get sideNames() {
+        return sideNames([...this.#model.edges, ...this.#model.overlays], this.config.above);
+    }
+    /**
+     * Every measure a channel could bind: the keys in the nodes' `measures`, plus `weight` and
+     * `degree`, which every node has an answer for. Sorted, so a picker does not reshuffle.
+     */
+    get measureKeys() {
+        return unique([
+            'degree',
+            'weight',
+            ...this.#canonical.nodes.flatMap((node) => Object.keys(node.measures ?? {}))
+        ]);
+    }
     get groupBy() {
-        return this.#groupBy;
+        return this.config.groupBy;
     }
     /**
      * The node kinds actually present, sorted.
@@ -534,32 +612,32 @@ export class GraphState {
     get groupsPresent() {
         return unique(this.#model.nodes.map((n) => n.group));
     }
-    /** Whether cards carry the group ramp themselves. See `GraphStateConfig.groupTint`. */
     /** `dot` or `card` — what the active layout draws a node as. */
     get nodeShape() {
         return nodeShapeOf(this.layoutName);
     }
+    /** Whether cards carry the group ramp themselves. See `GraphStateConfig.groupTint`. */
     get groupTint() {
-        return this.#groupTint;
+        return this.config.groupTint;
     }
     get nestBy() {
-        return this.#nestBy;
+        return this.config.nestBy;
     }
     get sizeBy() {
-        return this.#sizeBy;
+        return this.config.sizeBy;
     }
     get sizeScale() {
-        return this.#sizeScale;
+        return this.config.sizeScale;
     }
     get depth() {
-        return this.#depth;
+        return this.config.depth;
     }
     get focusPath() {
-        return this.#focusPath;
+        return this.config.focusPath;
     }
     /** The configured cap, or the package default of 2 when none was set. */
     get levels() {
-        return this.#levels ?? 2;
+        return this.config.levels ?? 2;
     }
     /**
      * Column headings for a multi-column layout, empty for the grid ones.
@@ -583,24 +661,22 @@ export class GraphState {
      * a rendering fault rather than a no-op.
      */
     setGrouping(outer, inner = null) {
-        this.#groupBy = outer;
-        this.#nestBy = inner === outer ? null : inner;
+        this.config.setGrouping(outer, inner);
     }
     get edgeStyle() {
-        return this.#edgeStyle;
+        return this.config.edgeStyle;
     }
     get mode() {
-        return this.#mode;
+        return this.config.mode;
     }
     /** The layout's registry key, or 'custom' when a LayoutFn was passed directly. */
     get layoutName() {
-        return typeof this.#layout === 'string' ? this.#layout : 'custom';
+        return typeof this.config.layout === 'string' ? this.config.layout : 'custom';
     }
     get value() {
-        return this.#value;
+        return this.selection.value;
     }
     get label() {
-        return (this.#label ??
-            `Diagram of ${plural(this.#model.nodes.length, 'node')} and ${plural(this.#model.edges.length, 'relationship')}`);
+        return this.config.label ?? diagramLabel(this.#model.nodes.length, this.#model.edges.length);
     }
 }