@rokkit/graph 1.6.0

package/dist/GraphState.svelte.js

@@ -0,0 +1,398 @@
+import { SvelteSet } from 'svelte/reactivity';
+import { normalizeGraph } from './model/normalize.js';
+import { layouts } from './layout/index.js';
+import { edgePath } from './layout/edges.js';
+import { defaultGraphPreset, resolveGroupStyles } from './preset.js';
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+/** How `id` sits on an edge: not on it, both ends of it, or one end with a far side. */
+function endpointsFor(edge, id) {
+    const isSource = edge.source === id;
+    const isTarget = edge.target === id;
+    if (!isSource && !isTarget)
+        return null;
+    return {
+        self: isSource && isTarget,
+        other: isSource ? edge.target : edge.source,
+        direction: isSource ? 'out' : 'in'
+    };
+}
+/**
+ * One edge's contribution to the selected node's relationship list.
+ *
+ * An UNPLACED edge is reported too, with the raw name as the label — the far end is not a
+ * node, so there is nothing to look up. Hiding it would be worse: "this references something
+ * we have not indexed" is exactly what a reader of a partial graph needs to see.
+ */
+function describeEdge(edge, id, describe) {
+    const ends = endpointsFor(edge, id);
+    if (!ends)
+        return [];
+    if (ends.self)
+        return [describe(id, 'out', edge)];
+    const { other, direction } = ends;
+    // An unplaced far end is not a node, so there is nothing to look up: the raw name IS
+    // the label. Reported rather than hidden — "references something not indexed" is what a
+    // reader of a partial graph most needs to see.
+    return edge.unplaced
+        ? [{ direction, id: other, label: other, edge }]
+        : [describe(other, direction, edge)];
+}
+/** Bottom-right extent of a set of boxes, or {0,0} when there are none. */
+function extentOf(boxes) {
+    let w = 0;
+    let h = 0;
+    for (const box of boxes) {
+        w = Math.max(w, box.x + box.w);
+        h = Math.max(h, box.y + box.h);
+    }
+    return { w, h };
+}
+/**
+ * The store. Turns raw `nodes`/`edges`/`fields` into the reactive shape the visuals
+ * render, and owns every transition.
+ *
+ * Components read from this and call its methods — they never compute. That is what
+ * lets the geometry, badge derivation and selection logic be covered exhaustively
+ * with no DOM, and lets the component specs assert only attributes.
+ *
+ * `update()` is re-callable and FULLY re-applies config rather than merging deltas,
+ * matching `SparkState.update` — so a prop reverting to undefined actually reverts.
+ * Deliberately NOT `PlotState.update`, which guards each field with
+ * `if (config.X !== undefined)` and therefore merges.
+ */
+export class GraphState {
+    #nodes = $state([]);
+    #edges = $state([]);
+    #fields = $state({});
+    #layout = $state('cluster');
+    #density = $state('keys');
+    #arrange = $state('untangle');
+    #groupBy = $state('group');
+    #nestBy = $state(null);
+    #edgeStyle = $state('curved');
+    #focus = $state(null);
+    #value = $state(null);
+    #expanded = new SvelteSet();
+    #preset = $state(defaultGraphPreset);
+    #mode = $state('light');
+    #label = $state(undefined);
+    #onselect = $state(undefined);
+    #model = $derived(normalizeGraph(this.#nodes, this.#edges, this.#fields));
+    #layoutFn = $derived(typeof this.#layout === 'function' ? this.#layout : (layouts[this.#layout] ?? layouts.cluster));
+    #result = $derived(this.#layoutFn(this.#model, {
+        density: this.#density,
+        arrange: this.#arrange,
+        groupBy: this.#groupBy,
+        nestBy: this.#nestBy ?? undefined,
+        edgeStyle: this.#edgeStyle,
+        focus: this.#focus ?? this.#value,
+        expanded: this.#expanded
+    }));
+    // Duplicates are left in on purpose: `resolveGroupStyles` de-duplicates and sorts, because
+    // that is where ramp assignment lives. A Set here would be a second, redundant de-dup.
+    #groups = $derived(this.#model.nodes.map((n) => n.group).filter((g) => Boolean(g)));
+    #groupStyles = $derived(resolveGroupStyles(this.#groups, this.#mode, this.#preset));
+    #related = $derived(this.#value
+        ? new SvelteSet(this.#model.neighbors.get(this.#value) ?? [])
+        : new SvelteSet());
+    #entities = $derived(this.#model.nodes.map((node) => ({
+        id: node.id,
+        label: node.label,
+        group: node.group,
+        kind: node.kind,
+        rowCount: node.rows.length,
+        refCount: this.#model.edges.filter((e) => e.source === node.id || e.target === node.id)
+            .length,
+        note: node.note
+    })));
+    #entity = $derived(this.#value ? (this.#model.byId.get(this.#value) ?? null) : null);
+    /**
+     * Derived from `#model.edges` — the canonical, unfiltered model — NOT from `#result.edges`.
+     *
+     * A layout filters: `cluster` drops edges whose endpoints were not laid out, and
+     * `neighborhood` lays out only the focus node's 1-hop neighbourhood. Since `focus` and
+     * `value` are independent config fields, reading the layout's edges lets the state
+     * contradict itself: with `focus: 'audit.log'` (no neighbours) and `value: 'public.orders'`,
+     * `relationships` would be `[]` while `entities`' `refCount` for the same node is 1.
+     *
+     * Routed geometry is attached opportunistically — it exists only for edges the active layout
+     * actually placed, so `routed` is optional on `Relationship`. A relationship is a fact about
+     * the model; its geometry is a fact about the current view.
+     */
+    #relationships = $derived.by(() => {
+        const id = this.#value;
+        if (!id)
+            return [];
+        // A plain Map on purpose: a call-local lookup built once from an already-derived array
+        // and discarded when this derivation re-runs. Nothing outside can observe it, so
+        // SvelteMap would add proxying for no reactivity.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const routed = new Map(this.#result.edges.map((e) => [e.id, e]));
+        const describe = (other, direction, edge) => {
+            // normalizeGraph drops any edge whose endpoints do not resolve, so both ends of
+            // every edge in #model.edges are in byId. No `?? other` fallback here: an
+            // unreachable branch cannot be tested, and the package's 100% statement bar
+            // exists to keep that honest.
+            const node = this.#model.byId.get(other);
+            return {
+                direction,
+                id: other,
+                label: node.label,
+                group: node.group,
+                edge,
+                routed: routed.get(edge.id)
+            };
+        };
+        return this.#model.edges.flatMap((edge) => describeEdge(edge, id, describe));
+    });
+    constructor(config = {}) {
+        this.update(config);
+    }
+    /**
+     * 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 = {}) {
+        this.#applyData(config);
+        this.#applyView(config);
+        // `value` is input AND output, so it is only adopted when the caller supplies
+        // one — otherwise a re-render would wipe a selection the user just made.
+        if (config.value !== undefined)
+            this.#value = config.value;
+    }
+    #applyData(config) {
+        this.#nodes = config.nodes ?? [];
+        this.#edges = config.edges ?? [];
+        this.#fields = config.fields ?? {};
+        this.#layout = config.layout ?? 'cluster';
+        this.#focus = config.focus ?? null;
+    }
+    /** How the boxes are organised — one axis, or one subdivided by a second. */
+    #applyGrouping(config) {
+        const outer = config.groupBy ?? 'group';
+        this.#groupBy = outer;
+        // Rejected rather than rendered: a box subdivided by its OWN axis yields exactly one
+        // child containing everything, which reads as a rendering fault, not a no-op.
+        this.#nestBy = config.nestBy === outer ? null : (config.nestBy ?? null);
+    }
+    #applyView(config) {
+        this.#density = config.density ?? 'keys';
+        this.#arrange = config.arrange ?? 'untangle';
+        this.#applyGrouping(config);
+        this.#edgeStyle = config.edgeStyle ?? 'curved';
+        this.#preset = config.preset ?? defaultGraphPreset;
+        this.#mode = config.mode ?? 'light';
+        this.#label = config.label;
+        this.#onselect = config.onselect;
+    }
+    // ─── transitions ───────────────────────────────────────────────────────────
+    select(id) {
+        this.#value = id;
+        this.#onselect?.(id);
+    }
+    clear() {
+        this.#value = null;
+    }
+    /**
+     * 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) {
+        if (this.#expanded.has(id))
+            this.#expanded.delete(id);
+        else
+            this.#expanded.add(id);
+    }
+    isExpanded(id) {
+        return this.#expanded.has(id);
+    }
+    /**
+     * 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) {
+        if (this.#expanded.has(id))
+            return 'show less';
+        const card = this.cards[id];
+        if (!card || card.more <= 0)
+            return null;
+        if (this.#density !== 'keys' || card.vis.length > 0)
+            return `+ ${card.more} more`;
+        return `no keys · ${card.more} ${card.more === 1 ? 'row' : 'rows'}`;
+    }
+    /**
+     * 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) {
+        this.#density = density;
+    }
+    // ─── per-item lookups the templates need ───────────────────────────────────
+    nodeState(id) {
+        if (!this.#value)
+            return null;
+        if (id === this.#value)
+            return 'selected';
+        return this.#related.has(id) ? 'related' : 'dim';
+    }
+    edgeState(edge) {
+        if (!this.#value)
+            return null;
+        return edge.fromKey === this.#value || edge.toKey === this.#value ? 'highlight' : 'dim';
+    }
+    edgePath(edge) {
+        return edgePath(edge, this.#edgeStyle);
+    }
+    groupStyle(group) {
+        return (group && this.#groupStyles.get(group)) || {};
+    }
+    /**
+     * 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) {
+        return Object.entries(this.groupStyle(group))
+            .map(([property, value]) => `${property}:${value}`)
+            .join(';');
+    }
+    // ─── reads ─────────────────────────────────────────────────────────────────
+    get model() {
+        return this.#model;
+    }
+    get clusters() {
+        return this.#result.clusters;
+    }
+    get cards() {
+        return this.#result.cards;
+    }
+    get routedEdges() {
+        return this.#result.edges;
+    }
+    get size() {
+        return this.#result.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() {
+        const clusters = this.#result.clusters.map((c) => ({
+            x: c.x,
+            y: c.y,
+            w: c.w ?? 0,
+            h: c.h ?? 0
+        }));
+        let { w, h } = extentOf(clusters);
+        // An ungrouped layout (neighborhood) reports no clusters, so fall back to the cards.
+        if (!w || !h) {
+            const cards = extentOf(Object.values(this.#result.cards));
+            w = Math.max(w, cards.w);
+            h = Math.max(h, cards.h);
+        }
+        return { w: w || this.#result.size.w, h: h || this.#result.size.h };
+    }
+    get related() {
+        return this.#related;
+    }
+    get entities() {
+        return this.#entities;
+    }
+    get entity() {
+        return this.#entity;
+    }
+    get relationships() {
+        return this.#relationships;
+    }
+    /**
+     * 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() {
+        return this.#model.edges.filter((e) => e.unplaced !== undefined);
+    }
+    get density() {
+        return this.#density;
+    }
+    get arrange() {
+        return this.#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) {
+        return `${cluster.depth ?? 0}:${cluster.parent ?? ''}:${cluster.name}`;
+    }
+    get groupBy() {
+        return this.#groupBy;
+    }
+    get nestBy() {
+        return this.#nestBy;
+    }
+    /**
+     * 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, inner = null) {
+        this.#groupBy = outer;
+        this.#nestBy = inner === outer ? null : inner;
+    }
+    get edgeStyle() {
+        return this.#edgeStyle;
+    }
+    get mode() {
+        return this.#mode;
+    }
+    /** The layout's registry key, or 'custom' when a LayoutFn was passed directly. */
+    get layoutName() {
+        return typeof this.#layout === 'string' ? this.#layout : 'custom';
+    }
+    get value() {
+        return this.#value;
+    }
+    get label() {
+        return (this.#label ??
+            `Diagram of ${plural(this.#model.nodes.length, 'node')} and ${plural(this.#model.edges.length, 'relationship')}`);
+    }
+}

package/dist/icons.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Default glyph per node kind and row badge.
+ *
+ * `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
+ * rendered an identical blank box while the class attribute looked perfectly correct.
+ * `spec/icons.spec.ts` now checks each name against the collection.
+ *
+ * A consumer overrides any entry through `<Graph icons={{ view: 'i-lucide-eye' }}>`, which is
+ * how a project on a different icon collection adopts this without patching the package.
+ */
+export declare const DEFAULT_ICONS: Record<string, string>;

package/dist/icons.js

@@ -0,0 +1,38 @@
+/**
+ * Default glyph per node kind and row badge.
+ *
+ * `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
+ * rendered an identical blank box while the class attribute looked perfectly correct.
+ * `spec/icons.spec.ts` now checks each name against the collection.
+ *
+ * A consumer overrides any entry through `<Graph icons={{ view: 'i-lucide-eye' }}>`, which is
+ * how a project on a different icon collection adopts this without patching the package.
+ */
+export const DEFAULT_ICONS = {
+    // ─── node kinds ───────────────────────────────────────────────────────────
+    table: 'i-glyph:table',
+    /** A view is a lens over other data, not storage of its own. */
+    view: 'i-glyph:eye',
+    /** dbd v2's wire string. Materialized = the query is stored, hence layers. */
+    materialized_view: 'i-glyph:layers',
+    /** Alias: rokkit's themes and demos have said `matview` since slice 1. */
+    matview: 'i-glyph:layers',
+    function: 'i-glyph:code',
+    /** A procedure is invoked for its effects — distinct from a function's value. */
+    procedure: 'i-glyph:play-circle',
+    /** dbd emits this; it fires on an event rather than being called. */
+    trigger: 'i-glyph:bolt',
+    /** A closed set of labels. */
+    enum: 'i-glyph:tag',
+    // ─── row badges ───────────────────────────────────────────────────────────
+    /** Identity constraint. The collection has no key glyph; `lock` is the closest. */
+    pk: 'i-glyph:lock',
+    /** Points at another entity. */
+    fk: 'i-glyph:git-merge',
+    uq: 'i-glyph:star',
+    /** NOT NULL — the value is guaranteed present. */
+    nn: 'i-glyph:shield',
+    fallback: 'i-glyph:box'
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { default as Graph } from './Graph.svelte';
+export { GraphState } from './GraphState.svelte.js';
+export { normalizeGraph } from './model/normalize.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 type { EntityRow, GraphStateConfig, Relationship } from './GraphState.svelte.js';
+export type { GraphChannel, GraphPreset, GraphShades } from './preset.js';
+export type * from './types.js';
+export type * from './layout/types.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+// Public surface for `@rokkit/graph`.
+export { default as Graph } from './Graph.svelte';
+export { GraphState } from './GraphState.svelte.js';
+export { normalizeGraph } from './model/normalize.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';

package/dist/layout/cards.d.ts

@@ -0,0 +1,19 @@
+import type { Cards, Density } from './types.js';
+import type { GraphNode, GraphRow } from '../types.js';
+export type CardOptions = {
+    /** Row cap. Defaults to 14 at density 'full', 8 otherwise. */
+    limit?: number;
+    /**
+     * Extra row filter applied before the cap, in place of the density's own.
+     *
+     * `more` still counts against ALL of the node's rows, which is why this belongs here
+     * rather than at the call site: filtering a node's rows before calling would report
+     * "+0 more" on a card that is in fact hiding most of its rows, and drop the more-row's
+     * height with it.
+     */
+    select?: (row: GraphRow, node: GraphNode) => boolean;
+    /** Nodes rendered at full detail and uncapped, whatever `density` says. */
+    expanded?: ReadonlySet<string>;
+};
+/** Build a card per node. Height is derived from row count — nothing is measured. */
+export declare function buildCards(nodes: GraphNode[], density: Density, options?: CardOptions): Cards;

package/dist/layout/cards.js

@@ -0,0 +1,31 @@
+import { CARD_W, HEAD_H, MORE_H, PAD_B, ROW_H } from './constants.js';
+/** The rows a card shows at the given density (none at 'names'). */
+function visibleRows(node, density, options) {
+    // An expanded node ignores the density AND the cap: the reader asked for this specific
+    // card in full, so truncating it again would answer a different question.
+    if (options.expanded?.has(node.id))
+        return node.rows;
+    if (density === 'names')
+        return [];
+    const rows = selectedRows(node, density, options.select);
+    return rows.slice(0, options.limit ?? (density === 'full' ? 14 : 8));
+}
+function selectedRows(node, density, select) {
+    if (select)
+        return node.rows.filter((r) => select(r, node));
+    if (density === 'keys') {
+        return node.rows.filter((r) => r.badges.includes('pk') || r.badges.includes('fk'));
+    }
+    return node.rows;
+}
+/** Build a card per node. Height is derived from row count — nothing is measured. */
+export function buildCards(nodes, density, options = {}) {
+    const cards = {};
+    for (const node of nodes) {
+        const vis = visibleRows(node, density, options);
+        const more = node.rows.length - vis.length;
+        const h = HEAD_H + vis.length * ROW_H + (more > 0 ? MORE_H : 0) + (vis.length || more > 0 ? PAD_B : 0);
+        cards[node.id] = { node, vis, more, w: CARD_W, h, x: 0, y: 0 };
+    }
+    return cards;
+}

package/dist/layout/cluster.d.ts

@@ -0,0 +1,11 @@
+import type { LayoutFn } from './types.js';
+/**
+ * Deterministic cluster layout: groups become clusters, clusters are ordered to
+ * reduce edge crossings, and each cluster's nodes are masonry-packed then flowed
+ * into wrapping rows.
+ *
+ * `arrange: 'untangle'` (default) chains clusters by inter-group link weight and
+ * reorders nodes inside each cluster with barycenter passes. `'a-z'` is plain
+ * area-descending order with alphabetical lists.
+ */
+export declare const cluster: LayoutFn;

package/dist/layout/cluster.js

@@ -0,0 +1,39 @@
+import { buildCards } from './cards.js';
+import { barycenterPasses, buildAdjacency, buildClusters, flow, groupByGroup, orderClusters, pack } from './clusters.js';
+import { buildEdges } from './edges.js';
+import { nestedClusters } from './nested.js';
+/**
+ * Deterministic cluster layout: groups become clusters, clusters are ordered to
+ * reduce edge crossings, and each cluster's nodes are masonry-packed then flowed
+ * into wrapping rows.
+ *
+ * `arrange: 'untangle'` (default) chains clusters by inter-group link weight and
+ * reorders nodes inside each cluster with barycenter passes. `'a-z'` is plain
+ * area-descending order with alphabetical lists.
+ */
+export const cluster = (model, options) => {
+    const density = options.density ?? 'keys';
+    const arrange = options.arrange ?? 'untangle';
+    const cards = buildCards(model.nodes, density, { expanded: options.expanded });
+    // Two-level clustering takes its own path — and only when asked. `clusters.ts` carries 20
+    // characterization assertions ported from dbd with exact pixel values, so the single-level
+    // pipeline below has to keep running byte-identically for every existing caller.
+    //
+    // Barycenter ordering is deliberately skipped here: it reorders nodes WITHIN one flat
+    // cluster to shorten edges, and a node in a nested layout is already pinned by two axes —
+    // reordering it could only move it out of the subdivision that explains where it is.
+    if (options.nestBy) {
+        const { clusters, size } = nestedClusters(model.nodes, cards, options.groupBy ?? 'group', options.nestBy);
+        return { clusters, cards, edges: buildEdges(model.edges, cards), size };
+    }
+    // NOT model.neighbors. That is a Set; barycenter needs the duplicate-preserving array so a
+    // twice-referenced neighbour weighs twice.
+    const neighbors = buildAdjacency(model.edges);
+    let clusters = buildClusters(groupByGroup(model.nodes, options.groupBy ?? 'group'));
+    clusters.forEach((c) => pack(c, cards));
+    clusters = orderClusters(clusters, model, arrange);
+    let size = flow(clusters, cards);
+    if (arrange === 'untangle')
+        size = barycenterPasses(clusters, cards, neighbors);
+    return { clusters, cards, edges: buildEdges(model.edges, cards), size };
+};

package/dist/layout/clusters.d.ts

@@ -0,0 +1,39 @@
+import type { Cluster, Cards, Size, Arrange, NodeAxis } from './types.js';
+import type { GraphEdge, GraphModel, GraphNode } from '../types.js';
+/**
+ * Group nodes by an axis. A node with no value on it files under ''.
+ *
+ * `axis` defaults to `group`, so every existing caller — and the ported characterization
+ * tests — keep their exact behaviour. It exists because the single-axis case is NOT a special
+ * case of nesting: `groupBy: 'kind'` with no `nestBy` has to regroup the flat layout too, and
+ * without it the control moved while the picture did not.
+ */
+export declare function groupByGroup(nodes: GraphNode[], axis?: NodeAxis): Record<string, GraphNode[]>;
+/**
+ * Undirected node adjacency (cross-node edges) for barycenter ordering.
+ *
+ * Pushes once PER EDGE, so two edges between the same pair list the neighbour
+ * twice. That is deliberate: `barycenter` divides by the array length, so a
+ * twice-referenced neighbour is weighted 2x and pulls the node twice as hard.
+ * Two FKs to one table is routine (`orders.created_by` and `orders.approved_by`
+ * both -> `users.id`), so collapsing this to a Set would silently relayout every
+ * multi-FK schema.
+ *
+ * `GraphModel.neighbors` is a Set and stays one — it answers "is X related to Y",
+ * where multiplicity is meaningless. This answers "how strongly is X pulled
+ * toward Y", where multiplicity is the whole point. Different questions.
+ */
+export declare function buildAdjacency(edges: GraphEdge[]): Map<string, string[]>;
+/** One cluster per group; groupIndex assigned by alphabetical position (stable across arranges). */
+export declare function buildClusters(byGroup: Record<string, GraphNode[]>): Cluster[];
+/** Masonry-pack one cluster from its current list order (sets c.pos/w/h). */
+export declare function pack(c: Cluster, cards: Cards): void;
+/**
+ * Order clusters. 'untangle' greedily chains groups so heavily-linked ones stay
+ * adjacent (seeded by the largest cluster); otherwise sort by area, biggest first.
+ */
+export declare function orderClusters(clusters: Cluster[], model: GraphModel, arrange: Arrange): Cluster[];
+/** Flow clusters into rows (wrapping at MAX_ROW_W), place each card, return canvas size. */
+export declare function flow(clusters: Cluster[], cards: Cards): Size;
+/** Two barycenter passes: reorder each cluster's nodes toward neighbors, re-pack, re-flow. */
+export declare function barycenterPasses(clusters: Cluster[], cards: Cards, nbrs: Map<string, string[]>): Size;