@rokkit/graph 1.6.0 → 1.8.0

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

@@ -0,0 +1,32 @@
+import { GraphState } from '../GraphState.svelte.js';
+import type { GraphFields } from '../types.js';
+import type { GraphPreset } from '../preset.js';
+type Props = {
+    /**
+     * Share one state across this diagram and, say, an entity table beside it. Given one,
+     * the caller owns it: this component reads it and never calls `update`, exactly as
+     * `Graph` does — two owners writing one state fight on every render.
+     */
+    state?: GraphState;
+    nodes?: unknown[];
+    edges?: unknown[];
+    fields?: GraphFields;
+    /** What area encodes. A `measures` key, or `weight`, or `degree`. */
+    sizeBy?: string;
+    /** How many levels below the focus to materialise. */
+    levels?: number;
+    /** The subtree to render as the whole canvas. `[]` is the root. Drilling, not zooming. */
+    focusPath?: string[];
+    controls?: boolean;
+    maxLevels?: number;
+    legend?: boolean;
+    value?: string | null;
+    preset?: GraphPreset;
+    mode?: 'light' | 'dark';
+    label?: string;
+    onselect?: (id: string | null) => void;
+    class?: string;
+};
+declare const Sunburst: import("svelte").Component<Props, {}, "value" | "focusPath" | "levels">;
+type Sunburst = ReturnType<typeof Sunburst>;
+export default Sunburst;

package/dist/diagrams/Treemap.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+	/**
+	 * Containment as nested rectangles, area proportional to a measure.
+	 *
+	 * Answers "where is the mass" — a box's area is what it CONTAINS, so the tree sums
+	 * subtrees rather than counting nodes. Every box is the same shape at every depth,
+	 * including a leaf: a treemap nests one thing.
+	 *
+	 * No edges. Containment IS the relationship here, and at this scale an adjacency graph
+	 * cannot be drawn.
+	 */
+	import Graph from '../Graph.svelte'
+	import GraphLegend from '../GraphLegend.svelte'
+	import DiagramFrame from './DiagramFrame.svelte'
+	import DepthControl from '../controls/DepthControl.svelte'
+	import ZoomControl from '../controls/ZoomControl.svelte'
+	import { GraphState } from '../GraphState.svelte.js'
+	import type { GraphFields } from '../types.js'
+	import type { GraphPreset } from '../preset.js'
+
+	type Props = {
+		/**
+		 * Share one state across this diagram and, say, an entity table beside it. Given one,
+		 * the caller owns it: this component reads it and never calls `update`, exactly as
+		 * `Graph` does — two owners writing one state fight on every render.
+		 */
+		state?: GraphState
+		nodes?: unknown[]
+		edges?: unknown[]
+		fields?: GraphFields
+		/** What area encodes. A `measures` key, or `weight`, or `degree`. */
+		sizeBy?: string
+		/** How many levels below the focus to materialise. */
+		levels?: number
+		/** The subtree to render as the whole canvas. `[]` is the root. Drilling, not zooming. */
+		focusPath?: string[]
+		controls?: boolean
+		maxLevels?: number
+		legend?: boolean
+		value?: string | null
+		preset?: GraphPreset
+		mode?: 'light' | 'dark'
+		label?: string
+		onselect?: (id: string | null) => void
+		class?: string
+	}
+
+	let {
+		state: provided,
+		nodes = [],
+		edges = [],
+		fields = {},
+		sizeBy = 'weight',
+		levels = $bindable(2),
+		focusPath = $bindable([]),
+		controls = false,
+		maxLevels = 4,
+		legend = false,
+		value = $bindable(undefined),
+		preset = undefined,
+		mode = 'light',
+		label = undefined,
+		onselect = undefined,
+		class: className = ''
+	}: Props = $props()
+
+	let zoom = $state(1)
+
+	const config = () => ({
+		nodes,
+		edges,
+		fields,
+		layout: 'world',
+		sizeBy,
+		levels,
+		focusPath,
+		value,
+		preset,
+		mode,
+		label,
+		onselect
+	})
+
+	// svelte-ignore state_referenced_locally
+	const graph = provided ?? new GraphState(config())
+
+	$effect(() => {
+		if (!provided) {
+			graph.update(config())
+
+			return
+		}
+
+		// A supplied state is the caller's: their data, preset, mode and selection stay theirs
+		// and are never reset here. What this component DOES own is the options its own
+		// controls drive — the layout above all, since choosing this component is choosing it.
+		// `apply` merges; `update` would revert everything it does not name.
+		const { nodes: _n, edges: _e, fields: _f, preset: _p, mode: _m, value: _v, ...mine } =
+			config()
+		graph.apply(mine)
+	})
+</script>
+
+<!-- Snippets are declared OUTSIDE the frame and passed conditionally: one declared
+     inside is always defined, so the frame would render an empty control bar over
+     every diagram that asked for none. -->
+{#snippet controlBar()}
+	<DepthControl {levels} max={maxLevels} onchange={(v) => (levels = v)} />
+	<ZoomControl {zoom} onchange={(v) => (zoom = v)} />
+{/snippet}
+
+{#snippet legendBar()}
+	<GraphLegend state={graph} groups />
+{/snippet}
+
+<DiagramFrame
+	class={className}
+	overlay={controls ? controlBar : undefined}
+	footer={legend ? legendBar : undefined}
+>
+	{#snippet canvas()}
+		<Graph state={graph} bind:zoom arrows={false} />
+	{/snippet}
+</DiagramFrame>

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

@@ -0,0 +1,32 @@
+import { GraphState } from '../GraphState.svelte.js';
+import type { GraphFields } from '../types.js';
+import type { GraphPreset } from '../preset.js';
+type Props = {
+    /**
+     * Share one state across this diagram and, say, an entity table beside it. Given one,
+     * the caller owns it: this component reads it and never calls `update`, exactly as
+     * `Graph` does — two owners writing one state fight on every render.
+     */
+    state?: GraphState;
+    nodes?: unknown[];
+    edges?: unknown[];
+    fields?: GraphFields;
+    /** What area encodes. A `measures` key, or `weight`, or `degree`. */
+    sizeBy?: string;
+    /** How many levels below the focus to materialise. */
+    levels?: number;
+    /** The subtree to render as the whole canvas. `[]` is the root. Drilling, not zooming. */
+    focusPath?: string[];
+    controls?: boolean;
+    maxLevels?: number;
+    legend?: boolean;
+    value?: string | null;
+    preset?: GraphPreset;
+    mode?: 'light' | 'dark';
+    label?: string;
+    onselect?: (id: string | null) => void;
+    class?: string;
+};
+declare const Treemap: import("svelte").Component<Props, {}, "value" | "focusPath" | "levels">;
+type Treemap = ReturnType<typeof Treemap>;
+export default Treemap;

package/dist/icons.d.ts

@@ -1,6 +1,11 @@
 /**
  * Default glyph per node kind and row badge.
  *
+ * Reachable as `@rokkit/graph/icons` — a subpath with NO Svelte imports, because the one
+ * place a consumer is REQUIRED to use it is a UnoCSS config, which Node loads directly and
+ * which therefore cannot import the main barrel (that re-exports `Graph.svelte`, and Node
+ * cannot parse `.svelte`). Found by dbd wiring its safelist.
+ *
  * `i-glyph:<name>` is the vocabulary this repo actually ships — `packages/icons/lib/glyph.json`,
  * 697 names, safelisted wholesale by the app's UnoCSS config. An earlier version of this map
  * used `i-graph-<kind>`, which is defined nowhere: UnoCSS emitted no rule, so every kind

package/dist/icons.js

@@ -1,6 +1,11 @@
 /**
  * Default glyph per node kind and row badge.
  *
+ * Reachable as `@rokkit/graph/icons` — a subpath with NO Svelte imports, because the one
+ * place a consumer is REQUIRED to use it is a UnoCSS config, which Node loads directly and
+ * which therefore cannot import the main barrel (that re-exports `Graph.svelte`, and Node
+ * cannot parse `.svelte`). Found by dbd wiring its safelist.
+ *
  * `i-glyph:<name>` is the vocabulary this repo actually ships — `packages/icons/lib/glyph.json`,
  * 697 names, safelisted wholesale by the app's UnoCSS config. An earlier version of this map
  * used `i-graph-<kind>`, which is defined nowhere: UnoCSS emitted no rule, so every kind

package/dist/index.d.ts

@@ -1,10 +1,30 @@
 export { default as Graph } from './Graph.svelte';
+export { default as GraphLegend } from './GraphLegend.svelte';
+export { default as ErDiagram } from './diagrams/ErDiagram.svelte';
+export { default as DependencyDiagram } from './diagrams/DependencyDiagram.svelte';
+export { default as CallTree } from './diagrams/CallTree.svelte';
+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';
+export { default as DepthControl } from './controls/DepthControl.svelte';
+export { default as BundleControl } from './controls/BundleControl.svelte';
+export { ZOOM_MIN, ZOOM_MAX, ZOOM_STEP, clampZoom } from './controls/zoom.js';
 export { GraphState } from './GraphState.svelte.js';
 export { normalizeGraph } from './model/normalize.js';
+export { buildTree, findNode } from './model/tree.js';
+export type { TreeNode } from './model/tree.js';
 export { readPath } from './model/path.js';
 export { createGraphPreset, defaultGraphPreset, resolveGroupStyles } from './preset.js';
 export { DEFAULT_ICONS } from './icons.js';
-export { cluster, neighborhood, points, layouts } from './layout/index.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

@@ -1,8 +1,32 @@
 // Public surface for `@rokkit/graph`.
+// The canvas. It draws what a layout hands it and ships no chrome — pair it with the
+// controls below, or reach for a named diagram, which is the composition already made.
 export { default as Graph } from './Graph.svelte';
+export { default as GraphLegend } from './GraphLegend.svelte';
+// Named diagrams: one layout, the controls that mean something for that picture, an opt-in
+// legend. `@rokkit/chart` has `BarChart` and `LineChart` over one `Plot`; these are the same
+// idea over one `Graph`, and each is usable on its own.
+export { default as ErDiagram } from './diagrams/ErDiagram.svelte';
+export { default as DependencyDiagram } from './diagrams/DependencyDiagram.svelte';
+export { default as CallTree } from './diagrams/CallTree.svelte';
+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';
+export { default as ZoomControl } from './controls/ZoomControl.svelte';
+export { default as DepthControl } from './controls/DepthControl.svelte';
+export { default as BundleControl } from './controls/BundleControl.svelte';
+export { ZOOM_MIN, ZOOM_MAX, ZOOM_STEP, clampZoom } from './controls/zoom.js';
 export { GraphState } from './GraphState.svelte.js';
 export { normalizeGraph } from './model/normalize.js';
+export { buildTree, findNode } from './model/tree.js';
 export { readPath } from './model/path.js';
 export { createGraphPreset, defaultGraphPreset, resolveGroupStyles } from './preset.js';
 export { DEFAULT_ICONS } from './icons.js';
-export { cluster, neighborhood, points, layouts } from './layout/index.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/arc.d.ts

@@ -0,0 +1,13 @@
+export type Wedge = {
+    r0: number;
+    r1: number;
+    a0: number;
+    a1: number;
+};
+/**
+ * The wedge as a path, centred on `(cx, cy)`.
+ *
+ * An innermost wedge has `r0 === 0`, where the two inner corners are the same point and an
+ * inner arc is undefined — that one is a pie slice, closing through the centre instead.
+ */
+export declare function arcPath(cx: number, cy: number, wedge: Wedge): string;

package/dist/layout/arc.js

@@ -0,0 +1,58 @@
+/* An annulus sector as an SVG path.
+ *
+ * Kept out of the component because it is arithmetic, not rendering: the layout reports a
+ * wedge as four numbers, and turning those into a path is a pure function that can be tested
+ * to exact coordinates. The same split `edgePath` already makes.
+ */
+const TAU = Math.PI * 2;
+/** Point on a circle of radius `r` at angle `a`, relative to a centre at the origin. */
+function at(cx, cy, r, a) {
+    return [cx + Math.cos(a) * r, cy + Math.sin(a) * r];
+}
+const fmt = (n) => Number(n.toFixed(3));
+/**
+ * A full turn cannot be one arc.
+ *
+ * SVG's `A` command draws the arc BETWEEN two points, and for a complete circle those two
+ * points coincide — so the command is a no-op and the wedge vanishes. A single child covering
+ * its parent's whole span is the common case at the root, not an edge case, so the span is
+ * halved and drawn as two arcs.
+ */
+function isFullTurn(wedge) {
+    return wedge.a1 - wedge.a0 >= TAU - 1e-9;
+}
+/** Ring path for a span that covers the whole circle: two half-arcs, outer then inner. */
+function fullRing(cx, cy, wedge) {
+    const { r0, r1 } = wedge;
+    const ring = (r, sweep) => {
+        const [ax, ay] = at(cx, cy, r, 0);
+        const [bx, by] = at(cx, cy, r, Math.PI);
+        return (`M ${fmt(ax)} ${fmt(ay)} ` +
+            `A ${fmt(r)} ${fmt(r)} 0 0 ${sweep} ${fmt(bx)} ${fmt(by)} ` +
+            `A ${fmt(r)} ${fmt(r)} 0 0 ${sweep} ${fmt(ax)} ${fmt(ay)} Z`);
+    };
+    // The inner circle is drawn the opposite way round, so the even-odd/nonzero fill punches
+    // it out and the result is a ring rather than a disc.
+    return r0 > 0 ? `${ring(r1, 1)} ${ring(r0, 0)}` : ring(r1, 1);
+}
+/**
+ * The wedge as a path, centred on `(cx, cy)`.
+ *
+ * An innermost wedge has `r0 === 0`, where the two inner corners are the same point and an
+ * inner arc is undefined — that one is a pie slice, closing through the centre instead.
+ */
+export function arcPath(cx, cy, wedge) {
+    if (isFullTurn(wedge))
+        return fullRing(cx, cy, wedge);
+    const { r0, r1, a0, a1 } = wedge;
+    const large = a1 - a0 > Math.PI ? 1 : 0;
+    const [ox0, oy0] = at(cx, cy, r1, a0);
+    const [ox1, oy1] = at(cx, cy, r1, a1);
+    const outer = `M ${fmt(ox0)} ${fmt(oy0)} A ${fmt(r1)} ${fmt(r1)} 0 ${large} 1 ${fmt(ox1)} ${fmt(oy1)}`;
+    if (r0 <= 0)
+        return `${outer} L ${fmt(cx)} ${fmt(cy)} Z`;
+    const [ix1, iy1] = at(cx, cy, r0, a1);
+    const [ix0, iy0] = at(cx, cy, r0, a0);
+    return (`${outer} L ${fmt(ix1)} ${fmt(iy1)} ` +
+        `A ${fmt(r0)} ${fmt(r0)} 0 ${large} 0 ${fmt(ix0)} ${fmt(iy0)} Z`);
+}

package/dist/layout/bundle.d.ts

@@ -0,0 +1,30 @@
+export type Point = {
+    x: number;
+    y: number;
+};
+/**
+ * Where two paths stop agreeing.
+ *
+ * The tree's lowest common ancestor, by prefix — `TreeNode.path` is the full chain from the
+ * root, so no parent pointers are needed and nothing has to be walked twice.
+ */
+export declare function commonDepth(a: string[], b: string[]): number;
+/**
+ * Pull each control point toward the straight line between the endpoints.
+ *
+ * `beta` is the tension: 1 keeps the full route through the tree, 0 collapses it onto the
+ * chord. Endpoints are unmoved at any beta — an edge has to start and finish where its nodes
+ * are, whatever the middle does.
+ */
+export declare function relax(points: Point[], beta: number): Point[];
+/**
+ * A uniform cubic B-spline through `points`, as an SVG path.
+ *
+ * B-spline rather than a curve THROUGH the points: a spline that interpolates every control
+ * point reproduces the corner at each tree level, and the whole reason to route through the
+ * tree is to get a smooth flow. The ends are duplicated so the curve actually reaches the
+ * first and last point instead of stopping short of them.
+ */
+export declare function splinePath(points: Point[]): string;
+/** The bundled route between two leaves, relaxed by `beta` and drawn as a spline. */
+export declare function bundlePath(points: Point[], beta: number): string;

package/dist/layout/bundle.js

@@ -0,0 +1,80 @@
+/* Hierarchical edge bundling — Holten (2006).
+ *
+ * A radial dendrogram of a codebase has every module on one rim, and the calls between them
+ * are chords across the middle. Drawn straight, a few hundred of those are a solid disc of
+ * ink. Bundled, edges that travel the same way through the TREE are pulled together, and the
+ * picture turns into visible flows between parts of the structure — which is the thing the
+ * reader came for.
+ *
+ * The bundle is a B-spline through the path each edge takes up to the lowest common ancestor
+ * and back down, relaxed toward the straight line by `beta`. At `beta = 0` it IS the straight
+ * line, which is why that is the "Straight" setting rather than a separate code path.
+ */
+/**
+ * Where two paths stop agreeing.
+ *
+ * The tree's lowest common ancestor, by prefix — `TreeNode.path` is the full chain from the
+ * root, so no parent pointers are needed and nothing has to be walked twice.
+ */
+export function commonDepth(a, b) {
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i])
+        i++;
+    return i;
+}
+/**
+ * Pull each control point toward the straight line between the endpoints.
+ *
+ * `beta` is the tension: 1 keeps the full route through the tree, 0 collapses it onto the
+ * chord. Endpoints are unmoved at any beta — an edge has to start and finish where its nodes
+ * are, whatever the middle does.
+ */
+export function relax(points, beta) {
+    if (points.length < 2)
+        return points;
+    const first = points[0];
+    const last = points[points.length - 1];
+    const span = points.length - 1;
+    return points.map((p, i) => {
+        const t = i / span;
+        const straightX = first.x + (last.x - first.x) * t;
+        const straightY = first.y + (last.y - first.y) * t;
+        return {
+            x: beta * p.x + (1 - beta) * straightX,
+            y: beta * p.y + (1 - beta) * straightY
+        };
+    });
+}
+const fmt = (n) => Number(n.toFixed(2));
+/**
+ * A uniform cubic B-spline through `points`, as an SVG path.
+ *
+ * B-spline rather than a curve THROUGH the points: a spline that interpolates every control
+ * point reproduces the corner at each tree level, and the whole reason to route through the
+ * tree is to get a smooth flow. The ends are duplicated so the curve actually reaches the
+ * first and last point instead of stopping short of them.
+ */
+export function splinePath(points) {
+    if (points.length === 0)
+        return '';
+    if (points.length === 1)
+        return `M ${fmt(points[0].x)} ${fmt(points[0].y)}`;
+    if (points.length === 2) {
+        return `M ${fmt(points[0].x)} ${fmt(points[0].y)} L ${fmt(points[1].x)} ${fmt(points[1].y)}`;
+    }
+    // Clamped: repeating the endpoints pins the curve to them, which a plain B-spline does not do.
+    const p = [points[0], points[0], ...points, points[points.length - 1], points[points.length - 1]];
+    let d = `M ${fmt(p[1].x)} ${fmt(p[1].y)}`;
+    for (let i = 1; i < p.length - 2; i++) {
+        const [a, b, c, e] = [p[i - 1], p[i], p[i + 1], p[i + 2]];
+        // Standard uniform cubic B-spline in Bezier form.
+        const c1 = { x: b.x + (c.x - a.x) / 6, y: b.y + (c.y - a.y) / 6 };
+        const c2 = { x: c.x - (e.x - b.x) / 6, y: c.y - (e.y - b.y) / 6 };
+        d += ` C ${fmt(c1.x)} ${fmt(c1.y)}, ${fmt(c2.x)} ${fmt(c2.y)}, ${fmt(c.x)} ${fmt(c.y)}`;
+    }
+    return d;
+}
+/** The bundled route between two leaves, relaxed by `beta` and drawn as a spline. */
+export function bundlePath(points, beta) {
+    return splinePath(relax(points, beta));
+}

package/dist/layout/cluster.js

@@ -1,6 +1,7 @@
 import { buildCards } from './cards.js';
 import { barycenterPasses, buildAdjacency, buildClusters, flow, groupByGroup, orderClusters, pack } from './clusters.js';
 import { buildEdges } from './edges.js';
+import { warnUnknownOptions } from './options.js';
 import { nestedClusters } from './nested.js';
 /**
  * Deterministic cluster layout: groups become clusters, clusters are ordered to
@@ -12,6 +13,7 @@ import { nestedClusters } from './nested.js';
  * area-descending order with alphabetical lists.
  */
 export const cluster = (model, options) => {
+    warnUnknownOptions(options, 'cluster');
     const density = options.density ?? 'keys';
     const arrange = options.arrange ?? 'untangle';
     const cards = buildCards(model.nodes, density, { expanded: options.expanded });

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/flow.d.ts

@@ -0,0 +1,8 @@
+import type { LayoutFn } from './types.js';
+/**
+ * Columns by reference direction, ordered to reduce crossings, with fixed ports.
+ *
+ * No clusters: ranking and schema grouping compete for the same axis, and a box cannot be both
+ * "in the `public` box" and "in column 3". `cluster` remains the schema view.
+ */
+export declare const flow: LayoutFn;

package/dist/layout/flow.js

@@ -0,0 +1,141 @@
+/* The `flow` layout: columns by reference direction, fixed ports, crossings reduced.
+ *
+ * Raised from the ER diagram — incoming should always enter on the LEFT and outgoing always
+ * leave from the RIGHT, and the boxes should be arranged so links are not buried behind
+ * entities. Those are ONE feature. `edges.ts` picks a connector's side by relative POSITION,
+ * so an edge's exit side tells a reader where the other box happens to sit rather than which
+ * way the reference points; and fixing the ports without ranking makes burial worse, because a
+ * right-exit connector reaching a left-hand table sweeps back across everything between.
+ *
+ * Ranking is what makes x-position mean direction, and only then are fixed ports honest.
+ *
+ * See docs/design/25-flow-layout.md — including what this deliberately does NOT do: a long
+ * edge is still drawn straight over any box between its endpoints, because routing it around
+ * needs dummy nodes on the intervening ranks and that is its own slice.
+ */
+import { buildCards } from './cards.js';
+import { rank } from './rank.js';
+import { order } from './order.js';
+import { warnUnknownOptions } from './options.js';
+import { CARD_W, GAP_Y, HEAD_H, ROW_H } from './constants.js';
+/**
+ * Horizontal gap between columns.
+ *
+ * Wider than `cluster`'s `GAP_X` on purpose: this gap is where every connector between two
+ * columns is drawn, so it is working space rather than breathing room. Too tight and the
+ * curves of a fan-out overlap each other before they reach their targets.
+ */
+const COL_GAP = 120;
+/** Vertical anchor for a row on a card, matching `edges.ts` so the two agree. */
+function anchorY(card, rowName) {
+    const idx = card.vis.findIndex((r) => r.name === rowName);
+    if (idx >= 0)
+        return card.y + HEAD_H + idx * ROW_H + ROW_H / 2;
+    return card.y + HEAD_H / 2;
+}
+/**
+ * Place each column left to right, centring every column on a shared axis.
+ *
+ * Every id in `layers` has a card without checking: both come from `model.nodes`, and
+ * `buildCards` keys one entry per node. A guard here would be a branch no input can reach.
+ */
+function place(layers, cards) {
+    const heights = layers.map((layer) => layer.reduce((total, id) => total + cards[id].h + GAP_Y, -GAP_Y));
+    const tallest = Math.max(0, ...heights);
+    let x = 0;
+    layers.forEach((layer, i) => {
+        // Centred rather than top-aligned: a short column hanging off the top reads as a
+        // hierarchy that is not there, and centring keeps most connectors near-horizontal.
+        let y = (tallest - heights[i]) / 2;
+        for (const id of layer) {
+            const card = cards[id];
+            card.x = x;
+            card.y = y;
+            y += card.h + GAP_Y;
+        }
+        x += CARD_W + COL_GAP;
+    });
+    return { w: Math.max(0, x - COL_GAP), h: tallest };
+}
+/** The identity half of a routed edge — everything that is not geometry. */
+function identity(edge, i) {
+    return {
+        i,
+        id: edge.id,
+        fromKey: edge.source,
+        toKey: edge.target,
+        kind: edge.kind,
+        relation: edge.relation
+    };
+}
+/**
+ * A self-reference bows off the right edge — the same shape `edges.ts` gives it, including the
+ * nudge that stops a single-row loop collapsing to a point.
+ */
+function selfLoop(edge, i, at) {
+    return {
+        ...identity(edge, i),
+        self: true,
+        x1: at.x,
+        y1: at.y1,
+        x2: at.x,
+        y2: at.y2 === at.y1 ? at.y1 + 14 : at.y2,
+        s1: 1,
+        s2: 1
+    };
+}
+/**
+ * One connector, always leaving the right and entering the left.
+ *
+ * That is the whole point of the layout, so there is no side calculation here at all — unlike
+ * `edges.ts`, which derives sides from geometry. A back edge gets the same treatment and pays
+ * a visible sweep for it; that is the minority case ranking exists to isolate.
+ */
+function route(edge, i, cards, back) {
+    const a = cards[edge.source];
+    const b = cards[edge.target];
+    if (!a || !b)
+        return null;
+    const y1 = anchorY(a, edge.sourceRow);
+    const y2 = anchorY(b, edge.targetRow);
+    if (a === b)
+        return selfLoop(edge, i, { x: a.x + a.w, y1, y2 });
+    return {
+        ...identity(edge, i),
+        back: back.has(edge.id) || undefined,
+        self: false,
+        x1: a.x + a.w,
+        y1,
+        x2: b.x,
+        y2,
+        s1: 1,
+        s2: -1
+    };
+}
+function routeAll(model, cards, back) {
+    const routed = [];
+    model.edges.forEach((edge, i) => {
+        const e = route(edge, i, cards, back);
+        if (e)
+            routed.push(e);
+    });
+    return routed;
+}
+/**
+ * Columns by reference direction, ordered to reduce crossings, with fixed ports.
+ *
+ * No clusters: ranking and schema grouping compete for the same axis, and a box cannot be both
+ * "in the `public` box" and "in column 3". `cluster` remains the schema view.
+ */
+export const flow = (model, options) => {
+    warnUnknownOptions(options, 'flow');
+    const cards = buildCards(model.nodes, options.density ?? 'keys', {
+        expanded: options.expanded
+    });
+    if (model.nodes.length === 0) {
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    }
+    const { ranks, back } = rank(model);
+    const size = place(order(model, ranks, back), cards);
+    return { clusters: [], cards, edges: routeAll(model, cards, back), size };
+};