@rokkit/graph 1.6.0 → 1.7.0

package/README.md

@@ -47,17 +47,49 @@ vocabulary lives entirely in the optional `./schema` entry point.
 
 | Import | Contains |
 |--------|----------|
-| `@rokkit/graph` | `Graph`, `GraphState`, layouts, presets, `normalizeGraph`, `DEFAULT_ICONS`, types |
+| `@rokkit/graph` | `Graph`, `GraphState`, layouts, presets, `normalizeGraph`, `DEFAULT_ICONS`, `appliesTo`, types |
 | `@rokkit/graph/schema` | `EntityView`, `EntitiesView`, `NoteBlocks`, `fromSchemaModel`, `toGraphInput`, `SCHEMA_FIELDS`, `DEPS_FIELDS` |
+| `@rokkit/graph/icons` | `DEFAULT_ICONS` alone, with no Svelte imports — for your UnoCSS safelist |
+
+## Named diagrams
+
+`Graph` is the canvas and ships no chrome. A named diagram is the composition already made —
+one layout, the controls that mean something for it, an opt-in legend. The same shape
+`@rokkit/chart` uses, where `BarChart` and `LineChart` sit over one `Plot`.
+
+```svelte
+<script>
+  import { ErDiagram, CallTree, Treemap, Sunburst } from '@rokkit/graph'
+</script>
+
+<ErDiagram {nodes} {edges} {fields} controls legend />
+```
+
+`ErDiagram` · `DependencyDiagram` · `CallTree` · `Treemap` · `Sunburst` · `StructureDiagram` ·
+`Neighborhood`.
+Both `controls` and `legend` default to off: the default is the bare picture.
+
+Composing your own is the same parts in a different box — `DensityControl`, `EdgeStyleControl`,
+`DepthControl`, `ZoomControl` and `GraphLegend` are all exported, and none of them stores a
+value. They report what was chosen and you own it.
 
 ## Layouts
 
 A layout is a pure `(model, options) => LayoutResult` — DOM-free, synchronous, deterministic.
 Your own slots in the same way.
 
-- **`cluster`** — cards in group boxes. The default; entity diagrams.
+- **`flow`** — cards in columns by reference direction. **The default.** Every edge leaves
+  right and enters left, so direction reads off the geometry and links stay traceable. Pair it
+  with `groupTint` to keep schema visible without cluster boxes.
+- **`cluster`** — cards in group boxes. Entity diagrams grouped by schema.
 - **`neighborhood`** — one focus node and its 1-hop neighbours.
+- **`radial`** — a tidy tree or dendrogram around a circle. Call graphs: angle separates the
+  subtrees, radius carries the depth.
 - **`points`** — degree-sized rects, shelf-packed. Dense graphs, 1000+ nodes.
+- **`world`** — nested rectangles, area proportional to a measure. Where the mass is.
+- **`sunburst`** — the same containment as nested wedges, with depth on the radius.
+- **`structure`** — a codebase as a radial dendrogram with its calls bundled through the
+  hierarchy. What `radial` cannot be: containment is a real tree where a call graph is not.
 
 Two-level clustering shows both grouping axes at once, which matters for a dependency graph
 where one schema holds a table, a trigger and a procedure:
@@ -66,6 +98,19 @@ where one schema holds a table, a trigger and a procedure:
 <Graph {nodes} {edges} {fields} groupBy="group" nestBy="kind" />
 ```
 
+`world` returns no cards: a treemap nests one shape, so a leaf is a `Cluster` too, carrying
+`nodeId` and `kind` so it stays selectable. Its caption is the measure driving its area, not a
+child count.
+
+Not every option reaches every layout, and a control wired to one that does not is worse than a
+missing one — it moves and nothing happens:
+
+```js
+import { appliesTo } from '@rokkit/graph'
+
+appliesTo('world', 'density')  // false — a treemap box has no row list to thin
+```
+
 ## Two things worth knowing
 
 **An unplaced edge is dimmed, never dropped.** An endpoint the map cannot resolve is a normal
@@ -84,6 +129,18 @@ const er = toGraphInput(model, 'er')             // tables + refs
 const deps = toGraphInput(model, 'dependencies') // tables + entities, deps as edges
 ```
 
+## Icons need a safelist
+
+The component picks a node's icon at runtime from its kind, so the class names never appear in
+your source and UnoCSS purges them — cards render a blank box. Safelist them from the
+Node-safe subpath (a `uno.config.ts` runs in Node and cannot parse `.svelte`):
+
+```js
+import { DEFAULT_ICONS } from '@rokkit/graph/icons'
+
+export default defineConfig({ safelist: Object.values(DEFAULT_ICONS) })
+```
+
 ## Theming
 
 Unstyled by default; `@rokkit/themes` ships `graph.css` for all six styles. Every visual hook

package/dist/Graph.svelte

@@ -4,6 +4,7 @@
 	import type { GraphStateConfig } from './GraphState.svelte.js'
 	import type { GraphProps } from './types.js'
 	import { DEFAULT_ICONS } from './icons.js'
+	import { ZOOM_STEP, clampZoom } from './controls/zoom.js'
 
 	// Aliased: a local binding literally named `state` makes the compiler read the `$state`
 	// rune below as a store subscription on it. The PUBLIC prop name is still `state`.
@@ -12,11 +13,14 @@
 		nodes = [],
 		edges = [],
 		fields = {},
-		layout = 'cluster',
+		layout = 'flow',
 		density = $bindable('keys'),
 		arrange = 'untangle',
 		groupBy = 'group',
+		groupTint = false,
 		nestBy = undefined,
+		sizeBy = 'degree',
+		sizeScale = 'linear',
 		edgeStyle = 'curved',
 		focus = null,
 		value = undefined,
@@ -24,7 +28,6 @@
 		mode = 'light',
 		zoom = $bindable(1),
 		zoomable = true,
-		densityToggle = true,
 		arrows = true,
 		label = undefined,
 		onselect = undefined,
@@ -42,7 +45,10 @@
 		density,
 		arrange,
 		groupBy,
+		groupTint,
 		nestBy,
+		sizeBy,
+		sizeScale,
 		edgeStyle,
 		focus,
 		value,
@@ -82,27 +88,11 @@
 	// `fit` alone shrinks a real schema until its labels are unreadable, which is the whole
 	// reason zoom exists.
 	const PAD = 28
-	const ZOOM_MIN = 0.25
-	const ZOOM_MAX = 4
-	const ZOOM_STEP = 1.25
 
 	let vw = $state(0)
 	let vh = $state(0)
 	let paper = $state<HTMLElement | null>(null)
 
-	const clampZoom = (value: number) => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, value))
-
-	/**
-	 * Writes the STATE, then mirrors into the bindable prop. Both halves matter: the state is
-	 * what renders (and may be caller-supplied, where the prop never reaches it), and the
-	 * prop is what a `bind:density` consumer observes — without the mirror its own effect
-	 * would re-apply the stale value and undo the click.
-	 */
-	function setDensity(next: typeof density) {
-		graph.setDensity(next)
-		density = next
-	}
-
 	function zoomBy(factor: number) {
 		zoom = clampZoom(zoom * factor)
 	}
@@ -154,7 +144,6 @@
 	// padding offset so scrolling reaches the far edge instead of clipping it.
 	const tx = $derived(Math.max(PAD, (vw - graph.contentSize.w * scale) / 2))
 	const ty = $derived(Math.max(PAD, (vh - graph.contentSize.h * scale) / 2))
-	const zoomPercent = $derived(Math.round(zoom * 100))
 
 	/**
 	 * Level of detail, from the EFFECTIVE scale rather than from `zoom` — a diagram fitted to
@@ -185,6 +174,7 @@
 	<div
 		data-graph-paper
 		data-graph-detail={detail}
+		data-graph-group-tint={graph.groupTint ? '' : undefined}
 		data-graph-panning={panning ? '' : undefined}
 		role="presentation"
 		bind:this={paper}
@@ -201,22 +191,117 @@
 	>
 	<div
 		data-graph-world
+		data-graph-node-shape={graph.nodeShape}
 		data-graph-layout={graph.layoutName}
 		style="width: {graph.size.w}px; height: {graph.size.h}px; transform: translate({tx}px, {ty}px) scale({scale}); --graph-label-counter-scale: {(1 / scale).toFixed(3)};"
 	>
-		{#each graph.clusters as cluster (graph.clusterKey(cluster))}
-			<div
-				data-graph-cluster
-				data-cluster-depth={cluster.depth ?? 0}
-				data-node-group={cluster.name}
-				style:left="{cluster.x}px"
-				style:top="{cluster.y}px"
-				style:width="{cluster.w}px"
-				style:height="{cluster.h}px"
-				style={graph.groupStyleAttr(cluster.name)}
+		<!-- Column headings. Three columns get away without them — the focus is visibly
+		     central — but a depth-2 portrait is five columns and ambiguous without one.
+		     Position, width and wording all come from the layout; this only prints them. -->
+		{#each graph.columns as column (column.side + column.depth)}
+			<span
+				data-graph-column
+				data-column-side={column.side}
+				data-column-depth={column.depth}
+				style:left="{column.x}px"
+				style:width="{column.w}px">{column.label}</span
 			>
-				<span data-graph-cluster-label>{cluster.name} · {cluster.count}</span>
-			</div>
+		{/each}
+
+		<!-- A wedge cannot be a positioned <div> — an annulus sector has no box. It is drawn in
+		     its own SVG UNDER the boxes, so a sunburst renders through the same cluster list as
+		     every other containment layout and nothing downstream learns a second vocabulary. -->
+		{#if graph.hasWedges}
+			<svg
+				data-graph-wedges
+				width={graph.size.w}
+				height={graph.size.h}
+				role="img"
+				aria-label={graph.label}
+				style="position: absolute; top: 0; left: 0;"
+			>
+				<title>{graph.label}</title>
+				{#each graph.clusters as cluster (graph.clusterKey(cluster))}
+					{@const shared = graph.boxAttrs(cluster)}
+					{@const caption = `${cluster.name} · ${cluster.caption ?? cluster.count}`}
+					<!-- Two branches so `role` is STATIC. A wedge that is a node is a button and says
+					     so; a region is scenery. Written as one element with a conditional role, the
+					     compiler cannot tell which it is and neither can a screen reader. The shared
+					     attributes come from state, so the branches cannot drift apart. -->
+					{#if cluster.nodeId}
+						<path
+							data-graph-wedge
+							{...shared}
+							style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
+							d={graph.wedgePath(cluster)}
+							role="button"
+							tabindex={0}
+							aria-label={caption}
+							onclick={(event: Event) => {
+								event.stopPropagation()
+								graph.select(cluster.nodeId!)
+							}}
+							onkeydown={(event: KeyboardEvent) => {
+								if (event.key !== 'Enter' && event.key !== ' ') return
+								event.preventDefault()
+								event.stopPropagation()
+								graph.select(cluster.nodeId!)
+							}}><title>{caption}</title></path
+						>
+					{:else}
+						<path
+							data-graph-wedge
+							{...shared}
+							style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
+							d={graph.wedgePath(cluster)}><title>{caption}</title></path
+						>
+					{/if}
+				{/each}
+			</svg>
+		{/if}
+
+		{#each graph.boxes as cluster (graph.clusterKey(cluster))}
+			{@const shared = graph.boxAttrs(cluster)}
+			{@const caption = `${cluster.name} · ${cluster.caption ?? cluster.count}`}
+			<!-- One box shape at every depth. A containment layout nests boxes inside boxes, so a
+			     childless one is still a box — rendering it as a node CARD instead put two
+			     structures in one hierarchy and brought the card's furniture with it, down to a
+			     row count that is `0` for anything without rows.
+
+			     Two branches, not one element with a conditional tag: a leaf is clickable and
+			     focusable, so it is a real <button> and gets Enter/Space, focus order and the right
+			     announcement for free. A region is scenery and is a <div> that says so. The shared
+			     attributes come from state, so the two cannot drift. -->
+			{#if cluster.nodeId}
+				<button
+					type="button"
+					data-graph-cluster
+					{...shared}
+					style:left="{cluster.x}px"
+					style:top="{cluster.y}px"
+					style:width="{cluster.w}px"
+					style:height="{cluster.h}px"
+					style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
+					onclick={(event) => {
+						event.stopPropagation()
+						graph.select(cluster.nodeId!)
+					}}
+				>
+					<span data-graph-cluster-label>{caption}</span>
+				</button>
+			{:else}
+				<div
+					data-graph-cluster
+					{...shared}
+					style:left="{cluster.x}px"
+					style:top="{cluster.y}px"
+					style:width="{cluster.w}px"
+					style:height="{cluster.h}px"
+					style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
+				>
+					<span data-graph-cluster-label>{caption}</span>
+				</div>
+			{/if}
 		{/each}
 
 		<svg
@@ -263,10 +348,15 @@
 				data-node-kind={card.node.kind}
 				data-node-group={card.node.group}
 				data-node-state={graph.nodeState(key)}
+				data-label-side={card.labelSide}
+				style:--label-angle={card.labelAngle === undefined
+					? undefined
+					: `${card.labelAngle}deg`}
 				data-node-headonly={card.vis.length === 0 && card.more <= 0 ? '' : undefined}
 				style:left="{card.x}px"
 				style:top="{card.y}px"
 				style:width="{card.w}px"
+				style:height="{card.h}px"
 				style={graph.groupStyleAttr(card.node.group)}
 				onclick={(event) => {
 					event.stopPropagation()
@@ -325,45 +415,4 @@
 		</div>
 	</div>
 
-	{#if densityToggle}
-		<!-- On the canvas for the same reason zoom is: "+3 more" tells a reader something is
-		     hidden; this is the control that does something about it for every card at once. -->
-		<div data-graph-density-controls role="group" aria-label="Detail level">
-			{#each [['names', 'Names', 'Titles only'], ['keys', 'Keys', 'Key rows only'], ['full', 'All', 'All rows']] as [value, short, title] (value)}
-				<button
-					type="button"
-					data-graph-density={value}
-					data-selected={graph.density === value ? '' : undefined}
-					aria-pressed={graph.density === value}
-					{title}
-					onclick={() => setDensity(value as typeof density)}>{short}</button
-				>
-			{/each}
-		</div>
-	{/if}
-
-	{#if zoomable}
-		<!-- On-canvas, because a zoom control that lives in someone else's settings drawer is
-		     a control a reader never finds. Buttons rather than a slider: each is one tab stop
-		     and one keypress, so this works without a trackpad. -->
-		<div data-graph-zoom-controls>
-			<button
-				type="button"
-				data-graph-zoom="out"
-				aria-label="Zoom out"
-				disabled={zoom <= ZOOM_MIN}
-				onclick={() => zoomBy(1 / ZOOM_STEP)}>−</button
-			>
-			<button type="button" data-graph-zoom="reset" aria-label="Reset zoom to fit" onclick={() => (zoom = 1)}
-				>{zoomPercent}%</button
-			>
-			<button
-				type="button"
-				data-graph-zoom="in"
-				aria-label="Zoom in"
-				disabled={zoom >= ZOOM_MAX}
-				onclick={() => zoomBy(ZOOM_STEP)}>+</button
-			>
-		</div>
-	{/if}
 </div>

package/dist/GraphLegend.svelte

@@ -0,0 +1,112 @@
+<script lang="ts">
+	/**
+	 * What the colours and strokes on the canvas mean.
+	 *
+	 * Graph-native rather than `@rokkit/chart`'s legend: that package carries eight d3 modules
+	 * plus ramda, and `@rokkit/graph` has exactly one dependency — so reusing it would cost a
+	 * consumer ten transitive packages for one component, and there is no package both already
+	 * share (chart does not depend on `@rokkit/ui` either). The vocabularies differ anyway: a
+	 * chart swatch is a symbol path, a graph swatch is a kind ICON or a LINE STYLE. If the
+	 * generic legend is ever promoted somewhere both can reach, this is what it replaces.
+	 *
+	 * Every section is opt-in. A diagram whose nodes are all one kind wants the relations key
+	 * and nothing else, and a legend that lists a constant is noise.
+	 */
+	import type { GraphState } from './GraphState.svelte.js'
+	import { DEFAULT_ICONS } from './icons.js'
+
+	type Section = 'kind' | 'relation' | 'group'
+
+	type Props = {
+		state: GraphState
+		/** Node kinds present, each with its glyph. */
+		kinds?: boolean
+		/** Edge relations present, each drawn as the stroke it uses. */
+		relations?: boolean
+		/** Group names present, each with its ramp colour. */
+		groups?: boolean
+		icons?: Record<string, string>
+		/**
+		 * Fires with the entry a reader activated. Given one, entries become real buttons;
+		 * without one they stay inert text, because a static key is not a control.
+		 */
+		onpick?: (section: Section, value: string) => void
+	}
+
+	let {
+		state: graph,
+		kinds = false,
+		relations = false,
+		groups = false,
+		icons: userIcons,
+		onpick
+	}: Props = $props()
+
+	const icons = $derived<Record<string, string>>({ ...DEFAULT_ICONS, ...userIcons })
+	const shown = $derived(kinds || relations || groups)
+
+	/** Underscores are the WIRE format (dbd sends `materialized_view`), not something to read. */
+	const readable = (value: string) => value.replace(/_/g, ' ')
+
+	/** `data-legend-kind` / `-relation` / `-group`, so CSS and tests can address a section. */
+	const attrs = (section: Section, value: string) => ({ [`data-legend-${section}`]: value })
+</script>
+
+<!-- The swatch IS the mark used on the canvas: a kind's own icon, the group's ramp chip, or
+     an SVG line inheriting the stroke the edge is drawn with. A key that redraws its marks a
+     second way is a key that can disagree with the picture. -->
+{#snippet swatch(section: Section, value: string)}
+	{#if section === 'kind'}
+		<span data-legend-swatch data-node-kind={value} class={icons[value] ?? icons.fallback}></span>
+	{:else if section === 'relation'}
+		<svg data-legend-swatch data-edge-relation={value} aria-hidden="true">
+			<line x1="1" y1="4" x2="21" y2="4" />
+		</svg>
+	{:else}
+		<span data-legend-swatch data-node-group={value} style={graph.groupStyleAttr(value)}></span>
+	{/if}
+{/snippet}
+
+<!-- Two branches so the element and its role are STATIC. Written as one `<svelte:element>`
+     with a conditional tag, the compiler cannot tell whether it is interactive and neither can
+     a screen reader — and a click handler on a `<span>` is unreachable by keyboard. -->
+{#snippet row(section: Section, value: string)}
+	{#if onpick}
+		<button
+			type="button"
+			data-graph-legend-entry
+			{...attrs(section, value)}
+			onclick={() => onpick(section, value)}
+		>
+			{@render swatch(section, value)}
+			<span data-legend-label>{readable(value)}</span>
+		</button>
+	{:else}
+		<span data-graph-legend-entry {...attrs(section, value)}>
+			{@render swatch(section, value)}
+			<span data-legend-label>{readable(value)}</span>
+		</span>
+	{/if}
+{/snippet}
+
+{#if shown}
+	<div data-graph-legend aria-label="Legend">
+		{#if kinds}
+			{#each graph.kindsPresent as kind (kind)}
+				{@render row('kind', kind)}
+			{/each}
+		{/if}
+
+		{#if relations}
+			{#each graph.relationsPresent as relation (relation)}
+				{@render row('relation', relation)}
+			{/each}
+		{/if}
+
+		{#if groups}
+			{#each graph.groupsPresent as group (group)}
+				{@render row('group', group)}
+			{/each}
+		{/if}
+	</div>
+{/if}

package/dist/GraphLegend.svelte.d.ts

@@ -0,0 +1,33 @@
+/**
+     * What the colours and strokes on the canvas mean.
+     *
+     * Graph-native rather than `@rokkit/chart`'s legend: that package carries eight d3 modules
+     * plus ramda, and `@rokkit/graph` has exactly one dependency — so reusing it would cost a
+     * consumer ten transitive packages for one component, and there is no package both already
+     * share (chart does not depend on `@rokkit/ui` either). The vocabularies differ anyway: a
+     * chart swatch is a symbol path, a graph swatch is a kind ICON or a LINE STYLE. If the
+     * generic legend is ever promoted somewhere both can reach, this is what it replaces.
+     *
+     * Every section is opt-in. A diagram whose nodes are all one kind wants the relations key
+     * and nothing else, and a legend that lists a constant is noise.
+     */
+import type { GraphState } from './GraphState.svelte.js';
+type Section = 'kind' | 'relation' | 'group';
+type Props = {
+    state: GraphState;
+    /** Node kinds present, each with its glyph. */
+    kinds?: boolean;
+    /** Edge relations present, each drawn as the stroke it uses. */
+    relations?: boolean;
+    /** Group names present, each with its ramp colour. */
+    groups?: boolean;
+    icons?: Record<string, string>;
+    /**
+     * Fires with the entry a reader activated. Given one, entries become real buttons;
+     * without one they stay inert text, because a static key is not a control.
+     */
+    onpick?: (section: Section, value: string) => void;
+};
+declare const GraphLegend: import("svelte").Component<Props, {}, "">;
+type GraphLegend = ReturnType<typeof GraphLegend>;
+export default GraphLegend;

package/dist/GraphState.svelte.d.ts

@@ -1,6 +1,6 @@
 import { SvelteSet } from 'svelte/reactivity';
 import type { GraphPreset } from './preset.js';
-import type { Arrange, Cards, Cluster, Density, EdgeStyle, LayoutFn, NodeAxis, RoutedEdge, Size } from './layout/types.js';
+import type { Arrange, Cards, Cluster, Column, Density, EdgeStyle, LayoutFn, NodeAxis, RoutedEdge, Size } from './layout/types.js';
 import type { GraphEdge, GraphFields, GraphModel, GraphNode } from './types.js';
 export type EntityRow = {
     id: string;
@@ -32,27 +32,41 @@ export type GraphStateConfig = {
     groupBy?: NodeAxis;
     /** Second axis subdividing each outer cluster. Unset means one level. */
     nestBy?: NodeAxis | null;
+    /**
+     * `points` only — what a node's size encodes. `degree` (default), `weight`, or any key in
+     * `GraphNode.measures`.
+     */
+    sizeBy?: string;
+    /** How the measure maps onto area. Defaults to `linear`. */
+    sizeScale?: 'linear' | 'log';
+    /** `neighborhood` only — hops out from the focus. Defaults to 1. */
+    depth?: number;
+    /** `world` only — the subtree rendered as the whole canvas. `[]` is the root. */
+    focusPath?: string[];
+    /** `world` only — levels below the focus to materialise. Defaults to 2. */
+    levels?: number;
+    /** `radial` only — `tree` ranks by depth, `dendrogram` pins leaves to the rim. */
+    radialMode?: 'tree' | 'dendrogram';
+    /** `radial` only — the node to centre on. Drilling; NOT the selection. */
+    root?: string | null;
+    /** `structure` only — how hard edges are pulled onto the tree, 0..1. */
+    bundleTension?: number;
+    /**
+     * Paint each CARD with its group's ramp, not just the cluster box around it.
+     *
+     * A clusterless layout — `flow`, `neighborhood` — has no box for the ramp to land on,
+     * so schema membership becomes invisible the moment you leave `cluster`. The cards
+     * already carry the custom properties; this is what tells CSS to use them.
+     */
+    groupTint?: boolean;
     edgeStyle?: EdgeStyle;
     focus?: string | null;
     value?: string | null;
     preset?: GraphPreset;
     mode?: 'light' | 'dark';
     label?: string;
-    onselect?: (id: string) => void;
+    onselect?: (id: string | null) => void;
 };
-/**
- * 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.
- */
 export declare class GraphState {
     #private;
     constructor(config?: GraphStateConfig);
@@ -64,7 +78,27 @@ export declare class GraphState {
      * field by field.
      */
     update(config?: GraphStateConfig): void;
+    /**
+     * Merge a partial config, leaving every key it does not name alone.
+     *
+     * `update()` fully RE-APPLIES — an omitted key reverts to its default, which is what makes
+     * it safe to call from a render. That is the wrong verb for a component writing the few
+     * options its own controls drive into a state someone else owns: it would reset the
+     * owner's data on every keystroke. This merges over the last full config instead.
+     */
+    apply(config: Partial<GraphStateConfig>): void;
     select(id: string): void;
+    /**
+     * 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.
+     */
     clear(): void;
     /**
      * Show one node's rows in full, whatever the density says.
@@ -109,6 +143,15 @@ export declare class GraphState {
      */
     groupStyleAttr(group: string | undefined): string;
     get model(): GraphModel;
+    /**
+     * Clusters drawn as rectangles — everything the box renderer handles.
+     *
+     * A wedge has no box, so it is drawn as an SVG arc instead. Split here rather than in the
+     * template so the component keeps computing nothing.
+     */
+    get boxes(): Cluster[];
+    /** Whether any cluster is a wedge, which is what puts the arc layer on the canvas. */
+    get hasWedges(): boolean;
     get clusters(): Cluster[];
     get cards(): Cards;
     get routedEdges(): RoutedEdge[];
@@ -147,9 +190,58 @@ export declare class GraphState {
      * 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.
+     *
+     * Here rather than in the component for the same reason `edgePath` is: it is arithmetic,
+     * and the view's job is to render what state derives, not to compute geometry.
+     */
+    wedgePath(cluster: Cluster): string;
+    /**
+     * The data attributes every containment box carries, wedge or rectangle.
+     *
+     * Built here so the two render branches — interactive and scenery — cannot drift: they
+     * differ only in the element and its role, which is exactly the difference that matters.
+     */
+    boxAttrs(cluster: Cluster): Record<string, string | null | undefined>;
     clusterKey(cluster: Cluster): string;
     get groupBy(): NodeAxis;
+    /**
+     * The node kinds actually present, sorted.
+     *
+     * What a LEGEND needs: naming the whole vocabulary over a diagram that uses three of it is
+     * a key to a different picture, and the reader hunts for a `trigger` that is not there.
+     */
+    get kindsPresent(): string[];
+    /**
+     * The edge relations present, sorted — the producer's verb where it gave one, else the
+     * coarse kind.
+     *
+     * A plain foreign key carries no verb, and listing nothing for it would leave the one
+     * stroke actually on the canvas unexplained.
+     */
+    get relationsPresent(): string[];
+    /** The group names present, sorted. Same reasoning as `kindsPresent`. */
+    get groupsPresent(): string[];
+    /** Whether cards carry the group ramp themselves. See `GraphStateConfig.groupTint`. */
+    /** `dot` or `card` — what the active layout draws a node as. */
+    get nodeShape(): 'dot' | 'card';
+    get groupTint(): boolean;
     get nestBy(): NodeAxis | null;
+    get sizeBy(): string;
+    get sizeScale(): 'linear' | 'log';
+    get depth(): number;
+    get focusPath(): string[];
+    /** The configured cap, or the package default of 2 when none was set. */
+    get levels(): number;
+    /**
+     * Column headings for a multi-column layout, empty for the grid ones.
+     *
+     * Exposed so the view can render headings without knowing which layout is active or what
+     * it means — the layout decides both the position and the wording, and the component
+     * prints them.
+     */
+    get columns(): Column[];
     /**
      * Change the grouping axes from inside the component.
      *