@rokkit/graph 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jerry Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @rokkit/graph
+
+Node-link diagram components for Svelte 5. ER diagrams, schema entity tables and dependency /
+call graphs from one component, driven by field-mapped data rather than a fixed schema type.
+
+```bash
+npm install @rokkit/graph
+```
+
+`@rokkit/ui` and `svelte` are peer dependencies. `@rokkit/ui` is optional — only the
+`./schema` views use it.
+
+## Usage
+
+```svelte
+<script>
+  import { Graph } from '@rokkit/graph'
+
+  const services = [
+    { key: 'checkout', team: 'commerce', type: 'procedure' },
+    { key: 'ledger', team: 'finance', type: 'table' }
+  ]
+  const calls = [{ caller: 'checkout', callee: 'ledger' }]
+
+  // Your shape, mapped once. Nothing downstream sees your field names.
+  const fields = {
+    id: 'key',
+    label: 'key',
+    group: 'team',
+    kind: 'type',
+    source: 'caller',
+    target: 'callee'
+  }
+</script>
+
+<div class="relative h-[600px]">
+  <Graph nodes={services} edges={calls} {fields} />
+</div>
+```
+
+The canvas fills its nearest positioned ancestor, so give it a `relative` box with a height.
+
+## What it is
+
+The package knows nodes, edges, groups and kinds — it has no opinion about databases. The dbd
+vocabulary lives entirely in the optional `./schema` entry point.
+
+| Import | Contains |
+|--------|----------|
+| `@rokkit/graph` | `Graph`, `GraphState`, layouts, presets, `normalizeGraph`, `DEFAULT_ICONS`, types |
+| `@rokkit/graph/schema` | `EntityView`, `EntitiesView`, `NoteBlocks`, `fromSchemaModel`, `toGraphInput`, `SCHEMA_FIELDS`, `DEPS_FIELDS` |
+
+## 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.
+- **`neighborhood`** — one focus node and its 1-hop neighbours.
+- **`points`** — degree-sized rects, shelf-packed. Dense graphs, 1000+ nodes.
+
+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:
+
+```svelte
+<Graph {nodes} {edges} {fields} groupBy="group" nestBy="kind" />
+```
+
+## Two things worth knowing
+
+**An unplaced edge is dimmed, never dropped.** An endpoint the map cannot resolve is a normal
+state at scale, not a defect — Sensei's code graph reports 59.6% of 4.08M edges with a null
+target: the call is real, the callee is simply not indexed. Dropping them would make the graph
+look far more complete than it is.
+
+**A schema is two graphs.** dbd's v2 `SchemaModel` separates `tables`/`refs` from
+`entities`/`deps` because an ER diagram is table entities and their foreign keys — a view is a
+derived projection and a routine is behaviour, so neither belongs on that canvas:
+
+```js
+import { toGraphInput } from '@rokkit/graph/schema'
+
+const er = toGraphInput(model, 'er')             // tables + refs
+const deps = toGraphInput(model, 'dependencies') // tables + entities, deps as edges
+```
+
+## Theming
+
+Unstyled by default; `@rokkit/themes` ships `graph.css` for all six styles. Every visual hook
+is a data-attribute — `data-node-kind`, `data-edge-kind`, `data-edge-relation`,
+`data-cluster-depth`, `data-graph-detail` and more.
+
+Node kinds are a closed set, so they are plain CSS. Groups are open-ended, so they get a ramp
+from `createGraphPreset({ using: 'color' | 'pattern' })`.
+
+## Docs
+
+- [Package reference](../../docs/llms/packages/graph.txt) — data contract, layouts, dbd adapter
+- [Component reference](../../docs/llms/components/graph.txt) — props, interaction, attributes
+- [Design](../../docs/design/23-graph.md) — why it is its own package, and what is locked

package/dist/Graph.svelte

@@ -0,0 +1,369 @@
+<script lang="ts">
+	import { setContext, untrack } from 'svelte'
+	import { GraphState } from './GraphState.svelte.js'
+	import type { GraphStateConfig } from './GraphState.svelte.js'
+	import type { GraphProps } from './types.js'
+	import { DEFAULT_ICONS } from './icons.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`.
+	let {
+		state: provided,
+		nodes = [],
+		edges = [],
+		fields = {},
+		layout = 'cluster',
+		density = $bindable('keys'),
+		arrange = 'untangle',
+		groupBy = 'group',
+		nestBy = undefined,
+		edgeStyle = 'curved',
+		focus = null,
+		value = undefined,
+		preset = undefined,
+		mode = 'light',
+		zoom = $bindable(1),
+		zoomable = true,
+		densityToggle = true,
+		arrows = true,
+		label = undefined,
+		onselect = undefined,
+		icons: userIcons = undefined,
+		class: className = ''
+	}: GraphProps = $props()
+
+	// A getter thunk (not a plain object) so every reactive prop it closes over is re-read on
+	// each call — used both by the untracked initial construction and the live $effect below.
+	const config = (): GraphStateConfig => ({
+		nodes,
+		edges,
+		fields,
+		layout,
+		density,
+		arrange,
+		groupBy,
+		nestBy,
+		edgeStyle,
+		focus,
+		value,
+		preset,
+		mode,
+		label,
+		onselect
+	})
+
+	// untrack: the constructor's initial read must not register as a dependency of whatever
+	// scope creates <Graph> — mirrors Spark's `untrack(() => new SparkState(config()))`.
+	const own = untrack(() => new GraphState(config()))
+
+	// Resolved ONCE, not $derived. setContext runs a single time at init and captures the value
+	// it is handed, so publishing a $derived would put whichever object won the branch at that
+	// instant into context forever — a caller later swapping `state` (or going from none to one)
+	// would leave nested EntityView/EntitiesView reading the stale object, silently.
+	//
+	// PlotState and SparkState hold the same discipline: reactivity flows through mutating ONE
+	// object's $state fields, never through replacing which object is in context.
+	// svelte-ignore state_referenced_locally
+	const graph = provided ?? own
+
+	setContext('graph-state', graph)
+
+	// Only sync the state WE own. A caller-supplied state is theirs to drive.
+	$effect(() => {
+		if (!provided) own.update(config())
+	})
+
+	const icons = $derived<Record<string, string>>({ ...DEFAULT_ICONS, ...userIcons })
+
+	// Fit-to-container, multiplied by `zoom`. These stay in the component because they depend
+	// on the rendered viewport, which state cannot know. The content extent they divide by is
+	// `graph.contentSize` — a pure derivation, so it lives in state.
+	//
+	// `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)
+	}
+
+	/**
+	 * Ctrl/meta + wheel is what a trackpad pinch reports as. Without preventDefault the
+	 * browser zooms the whole PAGE instead of the diagram, which is the behaviour a reader
+	 * hits first and reads as the component ignoring them.
+	 *
+	 * A plain wheel is left alone: the canvas scrolls, which is how panning works here.
+	 */
+	function onWheel(event: WheelEvent) {
+		if (!zoomable || !(event.ctrlKey || event.metaKey)) return
+		event.preventDefault()
+		zoomBy(event.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP)
+	}
+
+	// Drag-to-pan on the background. Scrolling already reaches the overflow, so this is the
+	// direct-manipulation path on top of it, not the only way across.
+	let panning = $state(false)
+	let panFrom = { x: 0, y: 0, left: 0, top: 0 }
+
+	function onPointerDown(event: PointerEvent) {
+		// Only the background drags — a press that starts on a card is a selection.
+		if (!paper || (event.target as HTMLElement).closest('[data-graph-node]')) return
+		panning = true
+		panFrom = { x: event.clientX, y: event.clientY, left: paper.scrollLeft, top: paper.scrollTop }
+		paper.setPointerCapture(event.pointerId)
+	}
+
+	function onPointerMove(event: PointerEvent) {
+		if (!panning || !paper) return
+		paper.scrollLeft = panFrom.left - (event.clientX - panFrom.x)
+		paper.scrollTop = panFrom.top - (event.clientY - panFrom.y)
+	}
+
+	function endPan() {
+		panning = false
+	}
+
+	const fit = $derived(
+		Math.max(
+			0.08,
+			Math.min((vw - PAD * 2) / graph.contentSize.w, (vh - PAD * 2) / graph.contentSize.h, 1)
+		) || 0.5
+	)
+	const scale = $derived(fit * zoom)
+	// Centre while the content is smaller than the viewport; once it is larger, pin to a
+	// 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
+	 * 0.05 is unreadable whether or not the reader touched the zoom control.
+	 *
+	 * Measured on a 1000-node call graph fitted into 1440x900: scale 0.047, so a 248px card
+	 * renders 11.6px wide and a 12px label lands at 0.56px. Drawing that text costs layout
+	 * and paint for glyphs nobody can see, so each tier drops what has stopped being legible
+	 * and the card keeps its colour, shape and position — which is what still reads at that
+	 * size. Hovering a node brings its label back at any tier.
+	 */
+	const detail = $derived(
+		scale >= 0.6 ? 'full' : scale >= 0.32 ? 'compact' : scale >= 0.14 ? 'minimal' : 'dot'
+	)
+</script>
+
+<!-- The viewport fills its nearest positioned ancestor. Place it inside a `relative` box
+     with a height.
+
+     The accessible name lives on the <svg> below, NOT here: role="img" makes its whole
+     subtree presentational, so putting it on this root would hide every node button from
+     assistive tech. The svg holds only edge geometry, which is genuinely one graphic.
+
+     role="presentation" is what this is — a positioned surface. Click-the-background-to-
+     dismiss is not the only way out: Escape does the same, and every node is a real
+     <button>, so nothing here is keyboard-inaccessible. -->
+<div data-graph-viewport class={className}>
+	<div
+		data-graph-paper
+		data-graph-detail={detail}
+		data-graph-panning={panning ? '' : undefined}
+		role="presentation"
+		bind:this={paper}
+		bind:clientWidth={vw}
+		bind:clientHeight={vh}
+		onclick={() => graph.clear()}
+		onkeydown={(e) => e.key === 'Escape' && graph.clear()}
+		onwheel={onWheel}
+		onpointerdown={onPointerDown}
+		onpointermove={onPointerMove}
+		onpointerup={endPan}
+		onpointercancel={endPan}
+		tabindex="-1"
+	>
+	<div
+		data-graph-world
+		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)}
+			>
+				<span data-graph-cluster-label>{cluster.name} · {cluster.count}</span>
+			</div>
+		{/each}
+
+		<svg
+			width={graph.size.w}
+			height={graph.size.h}
+			role="img"
+			aria-label={graph.label}
+			style="position: absolute; top: 0; left: 0; pointer-events: none;"
+		>
+			<title>{graph.label}</title>
+			{#each graph.routedEdges as edge (edge.id)}
+				<g
+					data-graph-edge
+					data-edge-kind={edge.kind}
+					data-edge-relation={edge.relation}
+					data-edge-from={edge.fromKey}
+					data-edge-to={edge.toKey}
+					data-edge-state={graph.edgeState(edge)}
+				>
+					<path d={graph.edgePath(edge)} />
+					<circle data-graph-edge-dot="from" cx={edge.x1} cy={edge.y1} r="3.2" />
+					{#if arrows}
+						<!-- An edge HAS a direction — source to target — and two identical dots threw
+						     that away. The tangent of both path shapes is horizontal at the endpoint,
+						     so the heading is just the side the curve arrives from: -s2. No angle
+						     maths, and it stays correct for a self-loop. -->
+						{@const d = -edge.s2}
+						<polygon
+							data-graph-edge-arrow
+							points="{edge.x2},{edge.y2} {edge.x2 - d * 9},{edge.y2 - 4.5} {edge.x2 -
+								d * 9},{edge.y2 + 4.5}"
+						/>
+					{:else}
+						<circle data-graph-edge-dot="to" cx={edge.x2} cy={edge.y2} r="3.2" />
+					{/if}
+				</g>
+			{/each}
+		</svg>
+
+		{#each Object.entries(graph.cards) as [key, card] (key)}
+			<button
+				type="button"
+				data-graph-node={key}
+				data-node-kind={card.node.kind}
+				data-node-group={card.node.group}
+				data-node-state={graph.nodeState(key)}
+				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={graph.groupStyleAttr(card.node.group)}
+				onclick={(event) => {
+					event.stopPropagation()
+					graph.select(key)
+				}}
+			>
+				<span data-graph-node-head>
+					<span data-graph-node-icon class={icons[card.node.kind ?? ''] ?? icons.fallback}></span>
+					<span data-graph-node-title>{card.node.label}</span>
+					{#if card.node.kind}
+						<!-- The glyph alone is a guess: layers vs eye vs bolt does not tell anyone what a
+						     materialized view is. Icon for the glance, tag for the answer. Underscores
+						     are the WIRE format (dbd sends `materialized_view`), not something to
+						     read. -->
+						<span data-graph-node-kind>{card.node.kind.replace(/_/g, ' ')}</span>
+					{/if}
+					<span data-graph-node-count>{card.node.rows.length}</span>
+				</span>
+				{#each card.vis as row (row.name)}
+					<span data-graph-row data-graph-row-key={row.badges.length > 0 ? '' : undefined}>
+						{#if row.badges.length > 0}
+							<span data-row-badge={row.badges[0]} class={icons[row.badges[0]]}></span>
+						{:else}
+							<span data-row-badge-empty></span>
+						{/if}
+						<span data-graph-row-name>{row.name}</span>
+						<span data-graph-row-type>{row.type}</span>
+					</span>
+				{/each}
+				{#if graph.moreLabel(key)}
+					<!-- A real control. "+3 more" that does nothing is a statement dressed as an
+					     affordance; this expands just this card. -->
+					<span
+						role="button"
+						tabindex="0"
+						data-graph-more
+						data-graph-more-empty={card.vis.length === 0 && !graph.isExpanded(key)
+							? ''
+							: undefined}
+						data-expanded={graph.isExpanded(key) ? '' : undefined}
+						onclick={(event) => {
+							event.stopPropagation()
+							graph.toggleExpanded(key)
+						}}
+						onkeydown={(event) => {
+							if (event.key !== 'Enter' && event.key !== ' ') return
+							event.preventDefault()
+							event.stopPropagation()
+							graph.toggleExpanded(key)
+						}}
+					>{graph.moreLabel(key)}</span
+					>
+				{/if}
+			</button>
+		{/each}
+		</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/Graph.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { GraphProps } from './types.js';
+declare const Graph: import("svelte").Component<GraphProps, {}, "density" | "zoom">;
+type Graph = ReturnType<typeof Graph>;
+export default Graph;

package/dist/GraphState.svelte.d.ts

@@ -0,0 +1,171 @@
+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 { GraphEdge, GraphFields, GraphModel, GraphNode } from './types.js';
+export type EntityRow = {
+    id: string;
+    label: string;
+    group?: string;
+    kind?: string;
+    rowCount: number;
+    refCount: number;
+    note?: string;
+};
+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;
+};
+export type GraphStateConfig = {
+    nodes?: unknown[];
+    edges?: unknown[];
+    fields?: GraphFields;
+    layout?: string | LayoutFn;
+    density?: Density;
+    arrange?: Arrange;
+    /** Outer grouping axis. Defaults to `group` (the schema, for dbd data). */
+    groupBy?: NodeAxis;
+    /** Second axis subdividing each outer cluster. Unset means one level. */
+    nestBy?: NodeAxis | null;
+    edgeStyle?: EdgeStyle;
+    focus?: string | null;
+    value?: string | null;
+    preset?: GraphPreset;
+    mode?: 'light' | 'dark';
+    label?: string;
+    onselect?: (id: string) => 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);
+    /**
+     * Fully re-applies config. Safe to call on every prop change.
+     *
+     * Split across two helpers only to stay under the complexity bar — every field is still
+     * assigned unconditionally on every call, which is the contract the specs enforce
+     * field by field.
+     */
+    update(config?: GraphStateConfig): void;
+    select(id: string): void;
+    clear(): void;
+    /**
+     * 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.
+     */
+    toggleExpanded(id: string): void;
+    isExpanded(id: string): boolean;
+    /**
+     * The more-row's text, or null when the card is hiding nothing and needs no control.
+     *
+     * The "no keys" case is the whole reason this is a method rather than a template
+     * expression. A view, a procedure and an enum have no pk and no fk — correctly, they are
+     * not tables — so at 'keys' their cards collapse to a title and "+3 more", which is
+     * indistinguishable from a card the reader collapsed and reads as a rendering failure.
+     * The count alone cannot say WHY the rows are hidden; naming the empty filter can.
+     *
+     * Scoped to 'keys' because 'names' hides every row BY DESIGN — an empty card there is the
+     * answer to what was asked, not a filter that matched nothing.
+     */
+    moreLabel(id: string): string | null;
+    /**
+     * Change the detail level from inside the component.
+     *
+     * Needed because `Graph`'s `density` PROP only ever reaches the state it owns. With a
+     * caller-supplied state — which is how all three views share one — a control that set the
+     * prop would render, click, and change nothing.
+     */
+    setDensity(density: Density): void;
+    nodeState(id: string): 'selected' | 'related' | 'dim' | null;
+    edgeState(edge: RoutedEdge): 'highlight' | 'dim' | null;
+    edgePath(edge: RoutedEdge): string;
+    groupStyle(group: string | undefined): Record<string, string>;
+    /**
+     * The same style as a `style=` attribute string.
+     *
+     * A template cannot spread an object into `style`, so something has to serialise it.
+     * 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.
+     */
+    groupStyleAttr(group: string | undefined): string;
+    get model(): GraphModel;
+    get clusters(): Cluster[];
+    get cards(): Cards;
+    get routedEdges(): RoutedEdge[];
+    get size(): Size;
+    /**
+     * The true content extent, as distinct from `size`.
+     *
+     * `LayoutResult.size` adds a +60 margin on the right and bottom only, so fitting to it hugs
+     * the left/top edge and floats away from the right/bottom. Centring needs the real bounds.
+     *
+     * This lives in state, not in `Graph.svelte`, because it is a pure max over `clusters` — no
+     * viewport involved. Only the `scale`/`tx`/`ty` that consume it need `clientWidth`, and those
+     * stay in the component. Keeping this here is what lets it be tested without a renderer.
+     */
+    get contentSize(): Size;
+    get related(): SvelteSet<string>;
+    get entities(): EntityRow[];
+    get entity(): GraphNode | null;
+    get relationships(): Relationship[];
+    /**
+     * Edges the field map could not place at one or both ends.
+     *
+     * Exposed rather than hidden because at scale this is the MAJORITY: Sensei's code graph
+     * reports 59.6% of 4.08M edges with a null target. A view that silently omitted them
+     * would claim a completeness the data does not have. They are absent from `routedEdges`
+     * because there is no card to draw them between — that is geometry, not a judgement.
+     */
+    get unplacedEdges(): GraphEdge[];
+    get density(): Density;
+    get arrange(): 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.
+     */
+    clusterKey(cluster: Cluster): string;
+    get groupBy(): NodeAxis;
+    get nestBy(): NodeAxis | null;
+    /**
+     * Change the grouping axes from inside the component.
+     *
+     * Same reason `setDensity` exists: a `groupBy` PROP only ever reaches the state `Graph`
+     * owns, so with a caller-supplied state — which is how all three views share one — a
+     * control that set the prop would render, click, and change nothing.
+     *
+     * Passing the same axis for both is rejected rather than silently rendered: a box
+     * subdivided by itself produces exactly one child containing everything, which looks like
+     * a rendering fault rather than a no-op.
+     */
+    setGrouping(outer: NodeAxis, inner?: NodeAxis | null): void;
+    get edgeStyle(): EdgeStyle;
+    get mode(): 'light' | 'dark';
+    /** The layout's registry key, or 'custom' when a LayoutFn was passed directly. */
+    get layoutName(): string;
+    get value(): string | null;
+    get label(): string;
+}