@rokkit/graph 1.7.0 → 1.8.0

package/README.md

@@ -66,7 +66,8 @@ one layout, the controls that mean something for it, an opt-in legend. The same
 ```
 
 `ErDiagram` · `DependencyDiagram` · `CallTree` · `Treemap` · `Sunburst` · `StructureDiagram` ·
-`Neighborhood`.
+`Neighborhood` · `DependencyMatrix` (a dependency structure matrix — cells above the diagonal are
+dependencies against the grain).
 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`,
@@ -111,6 +112,12 @@ import { appliesTo } from '@rokkit/graph'
 appliesTo('world', 'density')  // false — a treemap box has no row list to thin
 ```
 
+## Overlay edges
+
+An edge with `overlay: true` (or `fields.overlay`) is drawn over the picture but never shapes it —
+co-change pairs, a broken layering rule. It never reaches the layout, neighbours or relationships,
+renders with `data-edge-overlay`, and its `weight` thickens the stroke via `--edge-weight`.
+
 ## Two things worth knowing
 
 **An unplaced edge is dimmed, never dropped.** An endpoint the map cannot resolve is a normal

package/dist/Graph.svelte

@@ -189,81 +189,84 @@
 		onpointercancel={endPan}
 		tabindex="-1"
 	>
-	<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)};"
-	>
-		<!-- Column headings. Three columns get away without them — the focus is visibly
+		<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)};"
+		>
+			<!-- 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
-			>
-		{/each}
+			{#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
+				>
+			{/each}
 
-		<!-- A wedge cannot be a positioned <div> — an annulus sector has no box. It is drawn in
+			<!-- 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
+			{#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}
+						{#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
+			{#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.
@@ -272,147 +275,145 @@
 			     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}
+				{#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
+				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)}
+						data-edge-overlay={edge.overlay ? '' : undefined}
+						style:--edge-weight={graph.edgeWeight(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-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)}
+					data-graph-node={key}
+					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()
-						graph.select(cluster.nodeId!)
+						graph.select(key)
 					}}
 				>
-					<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
-			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-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()
-					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
+					<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>
+							<span data-graph-node-kind>{card.node.kind.replace(/_/g, ' ')}</span>
 						{/if}
-						<span data-graph-row-name>{row.name}</span>
-						<span data-graph-row-type>{row.type}</span>
+						<span data-graph-node-count>{card.node.rows.length}</span>
 					</span>
-				{/each}
-				{#if graph.moreLabel(key)}
-					<!-- A real control. "+3 more" that does nothing is a statement dressed as an
+					{#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}
+						<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>
-
 </div>

package/dist/GraphState.svelte.d.ts

@@ -154,7 +154,15 @@ export declare class GraphState {
     get hasWedges(): boolean;
     get clusters(): Cluster[];
     get cards(): Cards;
+    /** Structural edges as the layout routed them, then any overlay edges on top. */
     get routedEdges(): RoutedEdge[];
+    /** Every overlay edge in the model, placed or not. */
+    get overlayEdges(): GraphEdge[];
+    /**
+     * 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.
+     */
+    edgeWeight(edge: RoutedEdge): number | undefined;
     get size(): Size;
     /**
      * The true content extent, as distinct from `size`.

package/dist/GraphState.svelte.js

@@ -1,7 +1,7 @@
 import { SvelteSet } from 'svelte/reactivity';
 import { normalizeGraph } from './model/normalize.js';
 import { layouts } from './layout/index.js';
-import { edgePath } from './layout/edges.js';
+import { buildEdges, edgePath } from './layout/edges.js';
 import { nodeShapeOf } from './layout/options.js';
 import { arcPath } from './layout/arc.js';
 import { defaultGraphPreset, resolveGroupStyles } from './preset.js';
@@ -132,6 +132,17 @@ export class GraphState {
         focus: this.#focus ?? this.#value,
         expanded: this.#expanded
     }));
+    /**
+     * Overlay edges routed over the finished layout. The layout never saw them — that is the
+     * point — so they are routed here, against whatever cards it placed. A layout with no cards
+     * (the treemap, the sunburst) simply has nothing to route them between.
+     */
+    #overlayRouted = $derived(buildEdges(this.#model.overlays, this.#result.cards));
+    #routed = $derived(this.#overlayRouted.length > 0
+        ? [...this.#result.edges, ...this.#overlayRouted]
+        : this.#result.edges);
+    /** Heaviest weight across every edge that carries one — the 1 that `edgeWeight` scales to. */
+    #maxEdgeWeight = $derived(Math.max(0, ...[...this.#model.edges, ...this.#model.overlays].map((e) => e.weight ?? 0)));
     // 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)));
@@ -385,8 +396,22 @@ export class GraphState {
     get cards() {
         return this.#result.cards;
     }
+    /** Structural edges as the layout routed them, then any overlay edges on top. */
     get routedEdges() {
-        return this.#result.edges;
+        return this.#routed;
+    }
+    /** Every overlay edge in the model, placed or not. */
+    get overlayEdges() {
+        return this.#model.overlays;
+    }
+    /**
+     * 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.
+     */
+    edgeWeight(edge) {
+        if (edge.weight === undefined || this.#maxEdgeWeight <= 0)
+            return undefined;
+        return edge.weight / this.#maxEdgeWeight;
     }
     get size() {
         return this.#result.size;

package/dist/diagrams/DependencyMatrix.svelte

@@ -0,0 +1,177 @@
+<script lang="ts">
+	/**
+	 * The dependency structure matrix: every node a row and a column, a cell where the row
+	 * depends on the column.
+	 *
+	 * Providers come first, so a layered codebase is lower-triangular and a mark ABOVE the
+	 * diagonal is a dependency against the grain — a cycle, or a layer reaching up. Groups sit
+	 * on the diagonal as outlined blocks, so a cross-module violation is a mark outside its
+	 * block. It stays readable at sizes where a node-link drawing is a hairball, which is the
+	 * reason to reach for it.
+	 *
+	 * Share a `state` with a `DependencyDiagram` beside it and a row click selects the same
+	 * node in both.
+	 */
+	import { GraphState } from '../GraphState.svelte.js'
+	import { buildMatrix } from '../layout/matrix.js'
+	import type { NodeAxis } from '../layout/types.js'
+	import type { GraphFields } from '../types.js'
+
+	type Props = {
+		/** Share one state with another view. The caller owns it; this component never updates it. */
+		state?: GraphState
+		nodes?: unknown[]
+		edges?: unknown[]
+		fields?: GraphFields
+		/** Keep each group contiguous and outline it on the diagonal. `null` for one flat order. */
+		groupBy?: NodeAxis | null
+		/** Cell size in pixels. */
+		cell?: number
+		value?: string | null
+		label?: string
+		onselect?: (id: string | null) => void
+		class?: string
+	}
+
+	let {
+		state: provided,
+		nodes = [],
+		edges = [],
+		fields = {},
+		groupBy = 'group',
+		cell = 16,
+		value = $bindable(undefined),
+		label = undefined,
+		onselect = undefined,
+		class: className = ''
+	}: Props = $props()
+
+	const config = () => ({
+		nodes,
+		edges,
+		fields,
+		value,
+		onselect: (id: string | null) => {
+			value = id
+			onselect?.(id)
+		}
+	})
+
+	// svelte-ignore state_referenced_locally
+	const graph = provided ?? new GraphState(config())
+
+	$effect(() => {
+		if (!provided) graph.update(config())
+	})
+
+	const matrix = $derived(buildMatrix(graph.model, { groupBy: groupBy ?? undefined }))
+
+	// Labels are measured by length, not by the DOM — deterministic, like every layout here.
+	const labelW = $derived(
+		Math.min(220, Math.max(48, Math.max(0, ...matrix.labels.map((l) => l.length)) * 6.5 + 14))
+	)
+	const n = $derived(matrix.order.length)
+	const width = $derived(labelW + n * cell + 8)
+	const height = $derived(labelW + n * cell + 8)
+	const selected = $derived(graph.value)
+
+	const name = $derived(
+		label ??
+			`Dependency matrix: ${n} nodes, ${matrix.cells.length} dependencies, ${matrix.above} above the diagonal`
+	)
+
+	function toggle(id: string) {
+		if (selected === id) graph.clear()
+		else graph.select(id)
+	}
+
+	function onKey(event: KeyboardEvent, id: string) {
+		if (event.key !== 'Enter' && event.key !== ' ') return
+		event.preventDefault()
+		toggle(id)
+	}
+
+	const cellState = (source: string, target: string) =>
+		selected && (source === selected || target === selected) ? 'highlight' : undefined
+</script>
+
+<div data-graph-matrix class={className} role="group" aria-label={name}>
+	<svg {width} {height} viewBox="0 0 {width} {height}">
+		<!-- Column headings, rotated so a long name costs height rather than width. -->
+		{#each matrix.labels as text, i (matrix.order[i])}
+			<text
+				data-matrix-col={matrix.order[i]}
+				data-matrix-state={selected === matrix.order[i] ? 'selected' : undefined}
+				transform="translate({labelW + i * cell + cell / 2 + 4}, {labelW - 6}) rotate(-90)"
+				>{text}</text
+			>
+		{/each}
+
+		{#each matrix.labels as text, i (matrix.order[i])}
+			{@const id = matrix.order[i]}
+			<g
+				data-matrix-row={id}
+				data-matrix-state={selected === id ? 'selected' : undefined}
+				role="button"
+				tabindex="0"
+				aria-pressed={selected === id}
+				aria-label={text}
+				onclick={() => toggle(id)}
+				onkeydown={(event) => onKey(event, id)}
+			>
+				<rect
+					x="0"
+					y={labelW + i * cell}
+					width={labelW + n * cell}
+					height={cell}
+					data-matrix-band
+				/>
+				<text
+					x={labelW - 6}
+					y={labelW + i * cell + cell / 2}
+					text-anchor="end"
+					dominant-baseline="middle">{text}</text
+				>
+			</g>
+		{/each}
+
+		{#each matrix.order as id, i (id)}
+			<rect
+				data-matrix-diagonal
+				x={labelW + i * cell}
+				y={labelW + i * cell}
+				width={cell}
+				height={cell}
+			/>
+		{/each}
+
+		{#each matrix.cells as c (`${c.row}:${c.col}`)}
+			<g
+				data-matrix-cell
+				data-matrix-from={c.source}
+				data-matrix-to={c.target}
+				data-matrix-above={c.above ? '' : undefined}
+				data-matrix-state={cellState(c.source, c.target)}
+				style:--cell-weight={c.count / matrix.maxCount}
+			>
+				<rect
+					x={labelW + c.col * cell + 1}
+					y={labelW + c.row * cell + 1}
+					width={cell}
+					height={cell}
+				/>
+				<title>{c.source} → {c.target} ({c.count})</title>
+			</g>
+		{/each}
+
+		{#each matrix.blocks as b (b.name + b.start)}
+			<rect
+				data-matrix-block={b.name}
+				x={labelW + b.start * cell}
+				y={labelW + b.start * cell}
+				width={(b.end - b.start + 1) * cell}
+				height={(b.end - b.start + 1) * cell}
+			/>
+		{/each}
+	</svg>
+</div>

package/dist/diagrams/DependencyMatrix.svelte.d.ts

@@ -0,0 +1,34 @@
+/**
+     * The dependency structure matrix: every node a row and a column, a cell where the row
+     * depends on the column.
+     *
+     * Providers come first, so a layered codebase is lower-triangular and a mark ABOVE the
+     * diagonal is a dependency against the grain — a cycle, or a layer reaching up. Groups sit
+     * on the diagonal as outlined blocks, so a cross-module violation is a mark outside its
+     * block. It stays readable at sizes where a node-link drawing is a hairball, which is the
+     * reason to reach for it.
+     *
+     * Share a `state` with a `DependencyDiagram` beside it and a row click selects the same
+     * node in both.
+     */
+import { GraphState } from '../GraphState.svelte.js';
+import type { NodeAxis } from '../layout/types.js';
+import type { GraphFields } from '../types.js';
+type Props = {
+    /** Share one state with another view. The caller owns it; this component never updates it. */
+    state?: GraphState;
+    nodes?: unknown[];
+    edges?: unknown[];
+    fields?: GraphFields;
+    /** Keep each group contiguous and outline it on the diagonal. `null` for one flat order. */
+    groupBy?: NodeAxis | null;
+    /** Cell size in pixels. */
+    cell?: number;
+    value?: string | null;
+    label?: string;
+    onselect?: (id: string | null) => void;
+    class?: string;
+};
+declare const DependencyMatrix: import("svelte").Component<Props, {}, "value">;
+type DependencyMatrix = ReturnType<typeof DependencyMatrix>;
+export default DependencyMatrix;

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { default as Treemap } from './diagrams/Treemap.svelte';
 export { default as Sunburst } from './diagrams/Sunburst.svelte';
 export { default as StructureDiagram } from './diagrams/StructureDiagram.svelte';
 export { default as Neighborhood } from './diagrams/Neighborhood.svelte';
+export { default as DependencyMatrix } from './diagrams/DependencyMatrix.svelte';
 export { default as DensityControl } from './controls/DensityControl.svelte';
 export { default as EdgeStyleControl } from './controls/EdgeStyleControl.svelte';
 export { default as ZoomControl } from './controls/ZoomControl.svelte';
@@ -22,6 +23,8 @@ export { createGraphPreset, defaultGraphPreset, resolveGroupStyles } from './pre
 export { DEFAULT_ICONS } from './icons.js';
 export { cluster, flow, neighborhood, points, radial, structure, sunburst, world, layouts } from './layout/index.js';
 export { LAYOUT_OPTIONS, appliesTo } from './layout/options.js';
+export { buildMatrix } from './layout/matrix.js';
+export type { Matrix, MatrixCell, MatrixBlock, MatrixOptions } from './layout/matrix.js';
 export type { EntityRow, GraphStateConfig, Relationship } from './GraphState.svelte.js';
 export type { GraphChannel, GraphPreset, GraphShades } from './preset.js';
 export type * from './types.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export { default as Treemap } from './diagrams/Treemap.svelte';
 export { default as Sunburst } from './diagrams/Sunburst.svelte';
 export { default as StructureDiagram } from './diagrams/StructureDiagram.svelte';
 export { default as Neighborhood } from './diagrams/Neighborhood.svelte';
+export { default as DependencyMatrix } from './diagrams/DependencyMatrix.svelte';
 // Controls, for composing your own arrangement over the bare canvas.
 export { default as DensityControl } from './controls/DensityControl.svelte';
 export { default as EdgeStyleControl } from './controls/EdgeStyleControl.svelte';
@@ -28,3 +29,4 @@ export { createGraphPreset, defaultGraphPreset, resolveGroupStyles } from './pre
 export { DEFAULT_ICONS } from './icons.js';
 export { cluster, flow, neighborhood, points, radial, structure, sunburst, world, layouts } from './layout/index.js';
 export { LAYOUT_OPTIONS, appliesTo } from './layout/options.js';
+export { buildMatrix } from './layout/matrix.js';

package/dist/layout/edges.js

@@ -26,6 +26,7 @@ function selfLoop(edge, i, card, { y1, y2 }) {
         toKey: edge.target,
         kind: edge.kind,
         relation: edge.relation,
+        ...carried(edge),
         self: true,
         x1: card.x + card.w,
         y1,
@@ -35,6 +36,15 @@ function selfLoop(edge, i, card, { y1, y2 }) {
         s2: 1
     };
 }
+/** Overlay flag and weight, copied only when set so existing routed edges stay key-identical. */
+function carried(edge) {
+    const out = {};
+    if (edge.overlay)
+        out.overlay = true;
+    if (edge.weight !== undefined)
+        out.weight = edge.weight;
+    return out;
+}
 /** Which side of each card the connector leaves from. 1 = right, -1 = left. */
 function sides(a, b) {
     if (a.x + a.w + 50 <= b.x)
@@ -61,6 +71,7 @@ function buildEdge(edge, i, cards) {
         toKey: edge.target,
         kind: edge.kind,
         relation: edge.relation,
+        ...carried(edge),
         self: false,
         x1: s1 === 1 ? a.x + a.w : a.x,
         y1,

package/dist/layout/matrix.d.ts

@@ -0,0 +1,38 @@
+import type { NodeAxis } from './types.js';
+import type { GraphModel } from '../types.js';
+export type MatrixCell = {
+    /** Index into `order` of the dependent (the edge's source). */
+    row: number;
+    /** Index into `order` of the dependency (the edge's target). */
+    col: number;
+    source: string;
+    target: string;
+    /** Edges folded into this cell — two FKs, a read and a write — each counted by its weight. */
+    count: number;
+    /** Against the grain: a cycle or a layer reaching up. */
+    above: boolean;
+};
+export type MatrixBlock = {
+    name: string;
+    start: number;
+    end: number;
+};
+export type Matrix = {
+    /** Node ids, providers first. Row i and column i are the same node. */
+    order: string[];
+    labels: string[];
+    /** Each node's group key on the grouping axis, parallel to `order` ('' when ungrouped). */
+    groups: string[];
+    cells: MatrixCell[];
+    /** Contiguous group runs along the diagonal. Empty when not grouping. */
+    blocks: MatrixBlock[];
+    /** Cells above the diagonal. */
+    above: number;
+    /** The largest `count`, for scaling cell intensity. */
+    maxCount: number;
+};
+export type MatrixOptions = {
+    /** Keep each group contiguous and outline it on the diagonal. Omit for one flat order. */
+    groupBy?: NodeAxis;
+};
+export declare function buildMatrix(model: GraphModel, options?: MatrixOptions): Matrix;

package/dist/layout/matrix.js

@@ -0,0 +1,90 @@
+/* The dependency structure matrix (DSM): every node is both a row and a column, and a cell at
+ * (row, col) says "row depends on col".
+ *
+ * Its strength is the ORDER. Providers come first, so in a layered architecture every
+ * dependency points up-and-left and the whole matrix is lower-triangular. A mark ABOVE the
+ * diagonal is then a dependency against the grain — a cycle, or a layer that reaches up —
+ * and it is visible at a glance at sizes where a node-link drawing is a hairball.
+ *
+ * The order reuses `flow`'s ranking (longest path, DFS cycle breaking), reversed: `rank` puts
+ * a target in a later column than its source, and a DSM wants the target FIRST. Grouping keeps
+ * each group contiguous, ordered by where its first member ranks, so a module's block sits on
+ * the diagonal and a cross-module dependency against the grain lands above it.
+ *
+ * Pure and DOM-free, like every layout.
+ */
+import { rank } from './rank.js';
+const axisOf = (node, axis) => (axis === 'kind' ? node.kind : node.group) ?? '';
+/** Node ids, providers first; with `groupBy`, each group contiguous in first-ranked order. */
+function orderNodes(model, groupBy) {
+    const { ranks } = rank(model);
+    // `rank` places every node, so each lookup hits; carrying the model index alongside the
+    // rank keeps ties in model order without a second map.
+    const byRank = model.nodes
+        .map((node, i) => ({ node, i, r: ranks.get(node.id) }))
+        .sort((a, b) => b.r - a.r || a.i - b.i)
+        .map((entry) => entry.node);
+    if (!groupBy)
+        return byRank;
+    const runs = new Map();
+    for (const node of byRank) {
+        const key = axisOf(node, groupBy);
+        const run = runs.get(key) ?? [];
+        run.push(node);
+        runs.set(key, run);
+    }
+    return [...runs.values()].flat();
+}
+function blocksOf(groups) {
+    const blocks = [];
+    groups.forEach((name, i) => {
+        const last = blocks[blocks.length - 1];
+        if (last && last.name === name)
+            last.end = i;
+        else
+            blocks.push({ name, start: i, end: i });
+    });
+    return blocks;
+}
+/** One cell per (dependent, dependency) pair, parallel edges folded into its count. */
+function collectCells(model, index) {
+    const cells = new Map();
+    for (const edge of model.edges) {
+        const row = index.get(edge.source);
+        const col = index.get(edge.target);
+        if (row === undefined || col === undefined || row === col)
+            continue;
+        const key = `${row}:${col}`;
+        // A weighted edge already IS a count — an import list aggregated to components says
+        // "7 imports" once rather than repeating the edge seven times.
+        const n = edge.weight ?? 1;
+        const cell = cells.get(key);
+        if (cell)
+            cell.count += n;
+        else
+            cells.set(key, {
+                row,
+                col,
+                source: edge.source,
+                target: edge.target,
+                count: n,
+                above: col > row
+            });
+    }
+    return [...cells.values()].sort((a, b) => a.row - b.row || a.col - b.col);
+}
+export function buildMatrix(model, options = {}) {
+    const nodes = orderNodes(model, options.groupBy);
+    const index = new Map(nodes.map((n, i) => [n.id, i]));
+    const cells = collectCells(model, index);
+    const groups = nodes.map((n) => (options.groupBy ? axisOf(n, options.groupBy) : ''));
+    return {
+        order: nodes.map((n) => n.id),
+        labels: nodes.map((n) => n.label),
+        groups,
+        cells,
+        blocks: options.groupBy ? blocksOf(groups) : [],
+        above: cells.filter((c) => c.above).length,
+        maxCount: Math.max(0, ...cells.map((c) => c.count))
+    };
+}

package/dist/layout/types.d.ts

@@ -126,6 +126,10 @@ export type RoutedEdge = {
      * than the reader wondering why one link behaves differently.
      */
     back?: boolean;
+    /** GraphEdge.overlay — routed after the layout ran, over a picture it did not shape. */
+    overlay?: boolean;
+    /** GraphEdge.weight, raw. `GraphState.edgeWeight` normalises it for drawing. */
+    weight?: number;
     x1: number;
     y1: number;
     x2: number;

package/dist/model/normalize.js

@@ -202,9 +202,23 @@ function buildEdge(source, fields, byId, seen) {
         relation,
         cardinality: str(pick(source, fields.cardinality, 'cardinality')),
         action: str(pick(source, fields.action, 'action')),
-        unplaced
+        unplaced,
+        ...edgeExtras(source, fields)
     };
 }
+/**
+ * `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.
+ */
+function edgeExtras(source, fields) {
+    const extras = {};
+    if (pick(source, fields.overlay, 'overlay'))
+        extras.overlay = true;
+    const weight = num(pick(source, fields.edgeWeight, 'weight'));
+    if (weight !== undefined)
+        extras.weight = weight;
+    return extras;
+}
 /**
  * The source row an edge makes a foreign key, if any.
  *
@@ -256,6 +270,8 @@ export function normalizeGraph(nodes, edges, fields = {}) {
     const resolved = edges
         .map((source) => buildEdge(source, fields, byId, seen))
         .filter((edge) => edge !== null);
-    markForeignKeys(byId, resolved);
-    return { nodes: built, edges: resolved, byId, neighbors: buildNeighbors(resolved) };
+    const structural = resolved.filter((edge) => !edge.overlay);
+    const overlays = resolved.filter((edge) => edge.overlay);
+    markForeignKeys(byId, structural);
+    return { nodes: built, edges: structural, overlays, byId, neighbors: buildNeighbors(structural) };
 }

package/dist/types.d.ts

@@ -94,10 +94,26 @@ export type GraphEdge = {
      * edge is kept and marked, and it is the renderer's job to dim it.
      */
     unplaced?: 'source' | 'target' | 'both';
+    /**
+     * Drawn over the picture but never allowed to shape it — a co-change pair, a layering
+     * rule broken, a suggested dependency.
+     *
+     * Such an edge is exactly what the reader wants to see and exactly what must not re-rank a
+     * layered layout or pull a cluster ordering: files that change together with no import
+     * between them would otherwise be drawn next to each other, hiding the very coupling the
+     * overlay exists to expose. So they never enter `GraphModel.edges`; they live in
+     * `GraphModel.overlays` and are routed after the layout has run.
+     */
+    overlay?: boolean;
+    /** A strength this edge carries — co-change count, call frequency. Drives stroke width. */
+    weight?: number;
 };
 export type GraphModel = {
     nodes: GraphNode[];
+    /** Structural edges — the ones layouts, neighbours and relationships see. */
     edges: GraphEdge[];
+    /** Overlay edges (`GraphEdge.overlay`) — routed after layout, never shaping it. */
+    overlays: GraphEdge[];
     byId: Map<string, GraphNode>;
     /** Undirected adjacency, self-edges excluded. */
     neighbors: Map<string, Set<string>>;
@@ -207,6 +223,10 @@ export type GraphFields = {
     defaultEdgeKind?: EdgeKind;
     /** Path to the consumer's own relationship word — see `GraphEdge.relation`. */
     relation?: string;
+    /** Path to a truthy flag marking an overlay edge — see `GraphEdge.overlay`. */
+    overlay?: string;
+    /** Path to an edge's strength — see `GraphEdge.weight`. */
+    edgeWeight?: string;
     cardinality?: string;
     action?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/graph",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Node-link diagram components — pluggable layouts, ER/schema views",
   "repository": {
     "type": "git",
@@ -46,10 +46,10 @@
     "check:types": "tsc --noEmit"
   },
   "dependencies": {
-    "@rokkit/core": "1.7.0"
+    "@rokkit/core": "1.8.0"
   },
   "peerDependencies": {
-    "@rokkit/ui": "1.7.0",
+    "@rokkit/ui": "1.8.0",
     "svelte": "^5.0.0"
   },
   "peerDependenciesMeta": {
@@ -58,7 +58,7 @@
     }
   },
   "devDependencies": {
-    "@rokkit/ui": "1.7.0",
+    "@rokkit/ui": "1.8.0",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "svelte": "^5.55.7",