@rokkit/graph 1.6.0

package/dist/layout/points.d.ts

@@ -0,0 +1,6 @@
+import type { LayoutFn } from './types.js';
+/**
+ * Rect layout for dense graphs. `density` is ignored on purpose — a dot has no rows — and
+ * `arrange` is ignored because placement is fully determined by degree and group.
+ */
+export declare const points: LayoutFn;

package/dist/layout/points.js

@@ -0,0 +1,204 @@
+/* Dense-graph layout: every node is a sized rounded RECT, shelf-packed into its group.
+
+   Cards stop working long before the data does. Measured on a 1000-node call graph fitted
+   into 1440x900, the `cluster` layout produces an 1780x18090 canvas at scale 0.047 — a 248px
+   card renders 11.6px wide and a 12px label lands at 0.56px. The geometry is fine and the
+   maths is fast; the CARD is what fails.
+
+   So this layout drops the card. A node becomes a small rect sized by its degree, packed into
+   its group's box, and groups are laid out in a grid ordered by size. Reading shifts from
+   "what columns does this table have" to "which things are central, and which cluster do they
+   live in" — the question you actually ask of a code index.
+
+   WHY RECTS AND NOT DISCS. The first version spiral-packed circles, and it wasted most of its
+   canvas: measured on the 7-node service graph, a declared 607x595 world held only 362x364 of
+   actual dots — 36% fill. Two compounding causes, both intrinsic to the shape:
+
+     1. One spiral step, derived from the LARGEST dot present, applied to every ring. A group
+        holding one hub (r=26) and two leaves (r=5) stepped all three at 60.7px, giving a
+        238px disc for three dots.
+     2. A circular cluster throws away 1 - pi/4 = 21% of its bounding box before anything is
+        placed in it, and the canvas is made of bounding boxes.
+
+   Fit-to-container then frames all that emptiness, so the diagram opens zoomed further out
+   than its content warrants and still clips. Rects remove both causes: shelf packing has no
+   global step, and a rectangular group box is the area it occupies.
+
+   Deterministic and DOM-free like every other LayoutFn: no physics, no simulation, no random
+   seed. The same model always produces the same picture, so it is unit-testable to exact
+   pixels and a re-render never reshuffles the diagram under the reader. */
+import { buildEdges } from './edges.js';
+/**
+ * Node geometry. AREA — not width — tracks degree, so ten edges reads as ten rather than as
+ * a hundred. Areas are carried over from the disc version (pi*5^2 to pi*26^2) so the ink
+ * weight of a diagram is unchanged; only the shape and the packing are different.
+ */
+const MIN_AREA = Math.PI * 5 * 5;
+const MAX_AREA = Math.PI * 26 * 26;
+/** Width:height. 2:1 reads as a "chip" and shelves well; a square wastes shelf height. */
+const ASPECT = 2;
+const NODE_GAP = 6;
+const CLUSTER_PAD = 20;
+/** Room for the group's own label above its first shelf. */
+const CLUSTER_TITLE = 26;
+const CLUSTER_GAP = 40;
+const CANVAS_PAD = 60;
+/**
+ * How wide a group is allowed to get before it wraps, as a multiple of sqrt(total ink).
+ * Above 1 the group box is wider than tall, which suits a label above it and tiles into a
+ * grid of groups better than a tall column.
+ */
+const SHELF_ASPECT = 1.6;
+function degreeOf(model) {
+    const degree = new Map();
+    for (const node of model.nodes)
+        degree.set(node.id, 0);
+    for (const edge of model.edges) {
+        degree.set(edge.source, (degree.get(edge.source) ?? 0) + 1);
+        if (edge.target !== edge.source) {
+            degree.set(edge.target, (degree.get(edge.target) ?? 0) + 1);
+        }
+    }
+    return degree;
+}
+/** Size by degree. Area is linear in degree, so width grows as its square root. */
+function sizeFor(degree, maxDegree) {
+    const t = maxDegree <= 0 ? 0 : degree / maxDegree;
+    const area = MIN_AREA + (MAX_AREA - MIN_AREA) * t;
+    return { w: Math.sqrt(area * ASPECT), h: Math.sqrt(area / ASPECT) };
+}
+/**
+ * Shelf-pack one group (first-fit decreasing height).
+ *
+ * Tallest first, so each shelf is set by its first member and later rows never have to grow —
+ * that is what keeps the wasted band under each node small. It also puts the hubs top-left,
+ * which is where the eye starts, matching the disc version's "hubs at the centre" intent.
+ *
+ * `dx`/`dy` are the node's CENTRE, the convention `buildDots` and the cluster `pos` share.
+ */
+function packGroup(members) {
+    const ordered = [...members].sort((a, b) => b.h - a.h || b.w - a.w || a.node.id.localeCompare(b.node.id));
+    const ink = ordered.reduce((sum, m) => sum + (m.w + NODE_GAP) * (m.h + NODE_GAP), 0);
+    // At least one node wide, or a single oversized hub would wrap onto its own shelf forever.
+    const limit = Math.max(ordered[0].w, Math.sqrt(ink * SHELF_ASPECT));
+    const nodes = [];
+    let x = 0;
+    let y = 0;
+    let shelfHeight = 0;
+    let widest = 0;
+    for (const member of ordered) {
+        if (x > 0 && x + member.w > limit) {
+            y += shelfHeight + NODE_GAP;
+            x = 0;
+            shelfHeight = 0;
+        }
+        nodes.push({ ...member, dx: x + member.w / 2, dy: y + member.h / 2 });
+        x += member.w + NODE_GAP;
+        shelfHeight = Math.max(shelfHeight, member.h);
+        widest = Math.max(widest, x - NODE_GAP);
+    }
+    return { nodes, w: widest, h: y + shelfHeight };
+}
+function clusterFrom(entry, x, y) {
+    return {
+        name: entry.name,
+        list: entry.pack.nodes.map((n) => n.node),
+        count: entry.pack.nodes.length,
+        groupIndex: 0,
+        x,
+        y,
+        w: entry.pack.w + CLUSTER_PAD * 2,
+        h: entry.pack.h + CLUSTER_PAD * 2 + CLUSTER_TITLE,
+        pos: entry.pack.nodes.map((n) => ({
+            key: n.node.id,
+            dx: CLUSTER_PAD + n.dx,
+            dy: CLUSTER_PAD + CLUSTER_TITLE + n.dy
+        }))
+    };
+}
+/** Lay the packed groups out in a grid, biggest first, wrapping to keep the canvas squarish. */
+function placeGroups(packs) {
+    const ordered = [...packs].sort((a, b) => b.pack.w * b.pack.h - a.pack.w * a.pack.h || a.name.localeCompare(b.name));
+    const columns = Math.max(1, Math.ceil(Math.sqrt(ordered.length)));
+    const clusters = [];
+    const cursor = { x: CANVAS_PAD, top: CANVAS_PAD, rowHeight: 0 };
+    ordered.forEach((entry, i) => {
+        if (i > 0 && i % columns === 0) {
+            cursor.x = CANVAS_PAD;
+            cursor.top += cursor.rowHeight + CLUSTER_GAP;
+            cursor.rowHeight = 0;
+        }
+        const cluster = clusterFrom(entry, cursor.x, cursor.top);
+        clusters.push(cluster);
+        cursor.x += (cluster.w ?? 0) + CLUSTER_GAP;
+        cursor.rowHeight = Math.max(cursor.rowHeight, cluster.h ?? 0);
+    });
+    return clusters;
+}
+/** Nodes bucketed by group, each carrying the size its degree earns it. */
+function sizeByGroup(model) {
+    const degree = degreeOf(model);
+    const maxDegree = Math.max(0, ...degree.values());
+    const byGroup = new Map();
+    for (const node of model.nodes) {
+        const key = node.group ?? '';
+        const list = byGroup.get(key) ?? [];
+        list.push({ node, ...sizeFor(degree.get(node.id) ?? 0, maxDegree) });
+        byGroup.set(key, list);
+    }
+    return byGroup;
+}
+/** One rect card for a placed node. `pos` holds the CENTRE; a card is positioned top-left. */
+function dotFor(node, cluster, p, size) {
+    const w = size?.w ?? 1;
+    const h = size?.h ?? 1;
+    return {
+        node,
+        vis: [],
+        more: node.rows.length,
+        w,
+        h,
+        x: cluster.x + p.dx - w / 2,
+        y: cluster.y + p.dy - h / 2,
+        groupIndex: cluster.groupIndex
+    };
+}
+/** One rect card per placed node. */
+function buildDots(model, clusters, sizeOf) {
+    const cards = {};
+    for (const cluster of clusters) {
+        for (const p of cluster.pos ?? []) {
+            const node = model.byId.get(p.key);
+            cards[p.key] = dotFor(node, cluster, p, sizeOf.get(p.key));
+        }
+    }
+    return cards;
+}
+/**
+ * Rect layout for dense graphs. `density` is ignored on purpose — a dot has no rows — and
+ * `arrange` is ignored because placement is fully determined by degree and group.
+ */
+export const points = (model, _options) => {
+    if (model.nodes.length === 0) {
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    }
+    const byGroup = sizeByGroup(model);
+    const packs = [...byGroup.entries()].map(([name, members]) => ({
+        name,
+        pack: packGroup(members)
+    }));
+    const clusters = placeGroups(packs);
+    // Alphabetical group index so a group keeps its colour regardless of how the grid ordered
+    // it by size — the same stability rule resolveGroupStyles follows.
+    const alphabetical = [...byGroup.keys()].sort();
+    for (const cluster of clusters)
+        cluster.groupIndex = alphabetical.indexOf(cluster.name);
+    const sizeOf = new Map();
+    for (const { pack } of packs)
+        for (const n of pack.nodes)
+            sizeOf.set(n.node.id, n);
+    const cards = buildDots(model, clusters, sizeOf);
+    const width = Math.max(...clusters.map((c) => c.x + (c.w ?? 0))) + CANVAS_PAD;
+    const height = Math.max(...clusters.map((c) => c.y + (c.h ?? 0))) + CANVAS_PAD;
+    return { clusters, cards, edges: buildEdges(model.edges, cards), size: { w: width, h: height } };
+};

package/dist/layout/types.d.ts

@@ -0,0 +1,115 @@
+import type { GraphModel, GraphNode, GraphRow } from '../types.js';
+/** How much of each node's row list a card shows. */
+export type Density = 'names' | 'keys' | 'full';
+/** Cluster and in-cluster ordering strategy. */
+export type Arrange = 'untangle' | 'a-z';
+export type EdgeStyle = 'curved' | 'orthogonal';
+/** A positioned node card. */
+export type Card = {
+    node: GraphNode;
+    /** The rows this card shows at the current density. */
+    vis: GraphRow[];
+    /** Count of rows hidden by the density. */
+    more: number;
+    w: number;
+    h: number;
+    x: number;
+    y: number;
+    /**
+     * Position of the card's group in the sorted group list. Replaces dbd's
+     * `hue` — colour now comes from CSS plus the preset, never from a
+     * hardcoded oklch angle baked into the layout.
+     */
+    groupIndex?: number;
+};
+export type Cluster = {
+    name: string;
+    list: GraphNode[];
+    count: number;
+    groupIndex: number;
+    x: number;
+    y: number;
+    w?: number;
+    h?: number;
+    pos?: {
+        key: string;
+        dx: number;
+        dy: number;
+    }[];
+    /**
+     * 0 for an outer box, 1 for one nested inside it. Absent means the same as 0.
+     *
+     * Nesting needs no DOM tree: clusters are absolutely positioned boxes, so a flat list
+     * where the outer ones are larger and emitted FIRST renders correctly by paint order.
+     * Depth is what lets CSS tell the two apart — an inner box is a faint subdivision, not a
+     * second coloured region competing with the one containing it.
+     */
+    depth?: number;
+    /** Name of the enclosing cluster, for a depth-1 box. */
+    parent?: string;
+};
+/**
+ * Which node property a layout groups on. Both already exist on `GraphNode`, so nesting
+ * needs no new model field — only a choice of which is outer.
+ */
+export type NodeAxis = 'group' | 'kind';
+export type RoutedEdge = {
+    i: number;
+    /** GraphEdge.id */
+    id: string;
+    fromKey: string;
+    toKey: string;
+    kind: GraphModel['edges'][number]['kind'];
+    /** GraphEdge.relation — the consumer's own verb, carried through for theming. */
+    relation?: string;
+    self: boolean;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    /** 1 = right side of the card, -1 = left. */
+    s1: number;
+    s2: number;
+};
+export type Cards = Record<string, Card>;
+export type Size = {
+    w: number;
+    h: number;
+};
+export type LayoutOptions = {
+    density?: Density;
+    arrange?: Arrange;
+    edgeStyle?: EdgeStyle;
+    /** `neighborhood` only — the node the view centres on. */
+    focus?: string | null;
+    /**
+     * Node ids shown at FULL detail regardless of `density`, and uncapped.
+     * "+3 more" on a card is otherwise a statement with no corresponding action.
+     */
+    expanded?: ReadonlySet<string>;
+    /**
+     * Outer grouping axis. Defaults to `group`, which is every existing caller's behaviour.
+     *
+     * Schema is the right axis for an ER diagram and a poor one for a dependency graph, where
+     * a single schema holds a table, a trigger and a procedure and the question is usually
+     * "what are the routines and what do they touch".
+     */
+    groupBy?: NodeAxis;
+    /**
+     * Subdivide each outer cluster by this second axis. Unset (the default) means one level,
+     * and the layout runs its original single-level path untouched.
+     */
+    nestBy?: NodeAxis;
+};
+export type LayoutResult = {
+    clusters: Cluster[];
+    cards: Cards;
+    edges: RoutedEdge[];
+    size: Size;
+};
+/**
+ * A layout is a pure function of the model and its options. DOM-free,
+ * synchronous, deterministic: card heights come from row counts, nothing is
+ * measured. That is what makes layouts unit-testable to exact pixels.
+ */
+export type LayoutFn = (model: GraphModel, options: LayoutOptions) => LayoutResult;

package/dist/layout/types.js

@@ -0,0 +1 @@
+export {};

package/dist/model/normalize.d.ts

@@ -0,0 +1,7 @@
+import type { GraphFields, GraphModel } from '../types.js';
+/**
+ * Resolves a consumer's `nodes`/`edges`/`fields` into the canonical model — ONCE.
+ * Everything downstream (layouts, routing, components) sees concrete types, so no
+ * field mapping leaks past this function.
+ */
+export declare function normalizeGraph(nodes: unknown[], edges: unknown[], fields?: GraphFields): GraphModel;

package/dist/model/normalize.js

@@ -0,0 +1,215 @@
+import { readPath } from './path.js';
+const BADGE_ORDER = ['pk', 'fk', 'uq', 'nn'];
+function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function pick(row, path, fallbackKey) {
+    return readPath(row, path ?? fallbackKey);
+}
+function buildRows(source, fields) {
+    const raw = pick(source, fields.rows, 'rows');
+    if (!Array.isArray(raw))
+        return [];
+    const badgePaths = fields.rowBadges ?? {};
+    return raw.map((entry) => {
+        const badges = BADGE_ORDER.filter((badge) => {
+            const path = badgePaths[badge];
+            return path ? Boolean(readPath(entry, path)) : false;
+        });
+        return {
+            name: String(pick(entry, fields.rowName, 'name') ?? ''),
+            type: str(pick(entry, fields.rowType, 'type')),
+            badges,
+            note: str(pick(entry, fields.rowNote, 'note'))
+        };
+    });
+}
+// Every node-level field the canonical model reads. A claimed key must NOT also
+// land in `meta`, or the same value sits in two places and the two can drift.
+const CLAIMED_NODE_KEYS = ['id', 'label', 'group', 'kind', 'rows', 'note'];
+function buildMeta(source, fields) {
+    if (source === null || typeof source !== 'object')
+        return {};
+    const claimed = new Set();
+    for (const key of CLAIMED_NODE_KEYS) {
+        // Only the FIRST segment is claimed: a map of `from.t` claims `from`.
+        claimed.add((fields[key] ?? key).split('.')[0]);
+    }
+    const meta = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (!claimed.has(key))
+            meta[key] = value;
+    }
+    return meta;
+}
+function buildNode(source, fields) {
+    const label = String(pick(source, fields.label, 'label') ?? '');
+    const group = str(pick(source, fields.group, 'group'));
+    const explicitId = str(pick(source, fields.id, 'id'));
+    return {
+        id: explicitId ?? (group ? `${group}.${label}` : label),
+        label,
+        group,
+        kind: str(pick(source, fields.kind, 'kind')),
+        rows: buildRows(source, fields),
+        note: str(pick(source, fields.note, 'note')),
+        meta: buildMeta(source, fields)
+    };
+}
+function resolveEndpoint(source, spec, byId) {
+    const raw = str(pick(source, spec.path, spec.fallbackKey));
+    if (raw === undefined)
+        return undefined;
+    if (byId.has(raw))
+        return raw;
+    const group = spec.groupPath ? str(readPath(source, spec.groupPath)) : undefined;
+    if (group && byId.has(`${group}.${raw}`))
+        return `${group}.${raw}`;
+    return undefined;
+}
+/**
+ * Both endpoints, each flagged when the map could not resolve it to a node.
+ *
+ * Deliberately NOT "resolve or drop". Refusing to GUESS is still right — see resolveEndpoint
+ * — but discarding is a different decision, and a wrong one: an endpoint that cannot be
+ * placed is the normal case at scale, and dropping the edge hides that the relationship
+ * exists at all.
+ */
+function resolveEndpoints(source, fields, byId) {
+    const from = resolveEndpoint(source, {
+        path: fields.source,
+        fallbackKey: 'source',
+        groupPath: fields.sourceGroup ?? fields.group
+    }, byId);
+    const to = resolveEndpoint(source, {
+        path: fields.target,
+        fallbackKey: 'target',
+        groupPath: fields.targetGroup ?? fields.group
+    }, byId);
+    // The raw value is kept when it does not resolve, so an unplaced edge still carries the
+    // name written at the use site rather than becoming anonymous.
+    const rawFrom = str(pick(source, fields.source, 'source'));
+    const rawTo = str(pick(source, fields.target, 'target'));
+    if (rawFrom === undefined || rawTo === undefined)
+        return null;
+    return { from: from ?? rawFrom, to: to ?? rawTo, unplaced: whichUnplaced(from, to) };
+}
+/** Which end (if either) the map could not resolve. */
+function whichUnplaced(from, to) {
+    if (from && to)
+        return undefined;
+    if (!from && !to)
+        return 'both';
+    return from ? 'target' : 'source';
+}
+/**
+ * Makes `base` unique within one normalize pass.
+ *
+ * `kind` is already in `base`, and this counter breaks the remaining ties. Endpoints plus row
+ * names are NOT unique on their own: two dependency edges between the same pair (a procedure
+ * calling a function twice, a view reaching a table by two paths) carry no row anchors at all,
+ * so they would both key as `a:->b:`. A duplicate id silently breaks every id-keyed use —
+ * `{#each … as e (e.id)}` first among them.
+ */
+function uniqueEdgeId(base, seen) {
+    const seq = seen.get(base) ?? 0;
+    seen.set(base, seq + 1);
+    return seq === 0 ? base : `${base}#${seq}`;
+}
+/**
+ * The coarse edge kind: what the row declares, else the map's default, else a reference.
+ *
+ * Only the two canonical values are accepted from the data. A row carrying dbd v2's verb
+ * (`reads`) would otherwise fall through to `reference` and draw a view's dependency as a
+ * foreign key — which is why `defaultEdgeKind` exists for a list that is wholly one kind.
+ */
+function edgeKindOf(source, fields) {
+    const declared = str(pick(source, fields.edgeKind, 'kind'));
+    if (declared === 'dependency' || declared === 'reference')
+        return declared;
+    return fields.defaultEdgeKind ?? 'reference';
+}
+function buildEdge(source, fields, byId, seen) {
+    const endpoints = resolveEndpoints(source, fields, byId);
+    if (!endpoints)
+        return null;
+    const { from, to, unplaced } = endpoints;
+    const sourceRow = str(pick(source, fields.sourceRow, 'sourceRow'));
+    const targetRow = str(pick(source, fields.targetRow, 'targetRow'));
+    const kind = edgeKindOf(source, fields);
+    const relation = str(pick(source, fields.relation, 'relation'));
+    // `relation` joins the id because it is what separates otherwise-identical edges: a
+    // procedure that both reads AND writes one table produces two dep edges with the same
+    // endpoints and no row anchors, which would key identically and lose one to `{#each}`.
+    //
+    // Appended only when present, so every edge id a v1 consumer already has stays
+    // byte-identical — these are `{#each}` keys, and churning them relayouts for no reason.
+    const verb = relation ? `${kind}/${relation}` : kind;
+    const base = `${verb}:${from}:${sourceRow ?? ''}->${to}:${targetRow ?? ''}`;
+    return {
+        id: uniqueEdgeId(base, seen),
+        source: from,
+        target: to,
+        sourceRow,
+        targetRow,
+        kind,
+        relation,
+        cardinality: str(pick(source, fields.cardinality, 'cardinality')),
+        action: str(pick(source, fields.action, 'action')),
+        unplaced
+    };
+}
+/**
+ * The source row an edge makes a foreign key, if any.
+ *
+ * An unplaced TARGET still qualifies — the reference is real, only its destination is
+ * unknown. An unplaced SOURCE has no row to mark.
+ */
+function foreignKeyRow(byId, edge) {
+    if (edge.unplaced === 'source' || edge.unplaced === 'both')
+        return undefined;
+    if (edge.kind !== 'reference' || !edge.sourceRow)
+        return undefined;
+    return byId.get(edge.source)?.rows.find((r) => r.name === edge.sourceRow);
+}
+/** Adds the derived `fk` badge to each reference edge's source row. */
+function markForeignKeys(byId, edges) {
+    for (const edge of edges) {
+        const row = foreignKeyRow(byId, edge);
+        if (row && !row.badges.includes('fk')) {
+            row.badges = BADGE_ORDER.filter((b) => b === 'fk' || row.badges.includes(b));
+        }
+    }
+}
+function buildNeighbors(edges) {
+    const neighbors = new Map();
+    const link = (a, b) => {
+        const set = neighbors.get(a) ?? new Set();
+        set.add(b);
+        neighbors.set(a, set);
+    };
+    for (const edge of edges) {
+        // An unplaced endpoint is not a node, so it cannot be a neighbour. `related` and the
+        // dim/highlight states must only ever name things the reader can actually click.
+        if (edge.unplaced || edge.source === edge.target)
+            continue;
+        link(edge.source, edge.target);
+        link(edge.target, edge.source);
+    }
+    return neighbors;
+}
+/**
+ * Resolves a consumer's `nodes`/`edges`/`fields` into the canonical model — ONCE.
+ * Everything downstream (layouts, routing, components) sees concrete types, so no
+ * field mapping leaks past this function.
+ */
+export function normalizeGraph(nodes, edges, fields = {}) {
+    const built = nodes.map((source) => buildNode(source, fields));
+    const byId = new Map(built.map((node) => [node.id, node]));
+    const seen = new Map();
+    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) };
+}

package/dist/model/path.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reads a dotted field path off a source row.
+ *
+ * Field maps name object paths only. Arrays are rejected on purpose: a map like
+ * `rows.0.name` would break the moment the data reorders, so it is better to
+ * return undefined than to make it appear to work.
+ *
+ * Only OWN properties are read. The map is consumer-supplied and the rows are
+ * consumer data, so a path naming `constructor` or `toString` must read as
+ * absent — walking the prototype chain would resolve `constructor.name` to
+ * 'Object' and hand a layout a label no row actually carries.
+ */
+export declare function readPath(row: unknown, path: string): unknown;

package/dist/model/path.js

@@ -0,0 +1,23 @@
+/**
+ * Reads a dotted field path off a source row.
+ *
+ * Field maps name object paths only. Arrays are rejected on purpose: a map like
+ * `rows.0.name` would break the moment the data reorders, so it is better to
+ * return undefined than to make it appear to work.
+ *
+ * Only OWN properties are read. The map is consumer-supplied and the rows are
+ * consumer data, so a path naming `constructor` or `toString` must read as
+ * absent — walking the prototype chain would resolve `constructor.name` to
+ * 'Object' and hand a layout a label no row actually carries.
+ */
+export function readPath(row, path) {
+    let current = row;
+    for (const segment of path.split('.')) {
+        if (current === null || typeof current !== 'object' || Array.isArray(current))
+            return undefined;
+        if (!Object.hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}

package/dist/preset.d.ts

@@ -0,0 +1,47 @@
+/**
+ * How open-ended groups are differentiated.
+ *
+ * `pattern` is the colour-blind- and print-safe path and reuses chart's patterns.js.
+ * A `symbol` channel is deliberately NOT here in slice 1: the preset could emit a name, but
+ * nothing renders a glyph (chart's Shape.svelte stays in chart), so it would be a documented
+ * API that silently does nothing. It returns when it has a renderer.
+ */
+export type GraphChannel = 'color' | 'pattern';
+export type GraphShades = {
+    fill: string;
+    stroke: string;
+    label: string;
+};
+export type GraphPreset = {
+    /** Ordered ramp assigned to open-ended group names, wrapping when exhausted. */
+    groups: string[];
+    shades: {
+        light: GraphShades;
+        dark: GraphShades;
+    };
+    patterns: string[];
+    using: GraphChannel;
+};
+/**
+ * Mirrors `createChartPreset`'s shape on purpose — a consumer who has met one
+ * has met both. Shade picks differ from chart's because a cluster is a large
+ * background area rather than a small mark.
+ *
+ * The `groups` ramp and the `patterns` list are chart's own leading entries, in
+ * chart's order, so a graph and a chart on one page differentiate alike.
+ */
+export declare const defaultGraphPreset: GraphPreset;
+export declare function createGraphPreset(overrides?: Partial<GraphPreset>): GraphPreset;
+/**
+ * Resolves group names to CSS custom properties.
+ *
+ * Returns custom properties rather than concrete fills so a theme or an app can
+ * still override with one attribute rule — the JS decides the DEFAULT, never the
+ * final paint.
+ *
+ * Assignment is by SORTED group name so a group keeps its colour when `arrange`
+ * reorders the layout. Callers pass one name per NODE, so names are de-duplicated
+ * first; otherwise the ramp would advance per node and two nodes in the same group
+ * would disagree.
+ */
+export declare function resolveGroupStyles(groups: string[], mode: 'light' | 'dark', preset?: GraphPreset): Map<string, Record<string, string>>;