@iloveagents/foundry-web-graph 0.1.0

package/dist/theme.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Design tokens → concrete colours for the canvas.
+ *
+ * `react-force-graph-2d` paints to a `<canvas>`, and a canvas cannot read CSS
+ * custom properties: `ctx.fillStyle = "var(--foreground)"` silently paints
+ * black. So every colour the renderer uses has to be resolved from the DOM
+ * first, and re-resolved when the theme flips — otherwise a light-mode graph
+ * stays light-on-light after the user switches to dark.
+ *
+ * Tokens come from the host's stylesheet (`@iloveagents/foundry-web-ui/styles.css`
+ * plus this package's `styles.css`), so a themed app gets a themed graph for
+ * free.
+ */
+/** Tokens this package resolves. Values are whatever the host's CSS says. */
+export interface GraphTheme {
+    foreground: string;
+    mutedForeground: string;
+    background: string;
+    border: string;
+    ring: string;
+    /** Categorical node palette, in assignment order. */
+    palette: string[];
+}
+/**
+ * Last-resort palette, used when this package's `styles.css` was not imported.
+ * Plain hex on purpose: it must not itself depend on a token resolving.
+ */
+export declare const FALLBACK_THEME: GraphTheme;
+/**
+ * Resolve the theme against a mounted element.
+ *
+ * Takes an element rather than `document.documentElement` so a graph inside a
+ * scoped theme (the shell's `ThemeScope`, a preview pane) picks up that scope's
+ * tokens instead of the page's.
+ */
+export declare function resolveGraphTheme(element: Element | null): GraphTheme;

package/dist/theme.js

@@ -0,0 +1,83 @@
+/**
+ * Design tokens → concrete colours for the canvas.
+ *
+ * `react-force-graph-2d` paints to a `<canvas>`, and a canvas cannot read CSS
+ * custom properties: `ctx.fillStyle = "var(--foreground)"` silently paints
+ * black. So every colour the renderer uses has to be resolved from the DOM
+ * first, and re-resolved when the theme flips — otherwise a light-mode graph
+ * stays light-on-light after the user switches to dark.
+ *
+ * Tokens come from the host's stylesheet (`@iloveagents/foundry-web-ui/styles.css`
+ * plus this package's `styles.css`), so a themed app gets a themed graph for
+ * free.
+ */
+/**
+ * Preferred palette: this package's own tokens (`styles.css`), which give
+ * eight well-separated hues.
+ */
+const PALETTE_TOKENS = [
+    "--graph-1",
+    "--graph-2",
+    "--graph-3",
+    "--graph-4",
+    "--graph-5",
+    "--graph-6",
+    "--graph-7",
+    "--graph-8",
+];
+/**
+ * Second choice: the chart tokens every Foundry UI app already has from
+ * `@iloveagents/foundry-web-ui/styles.css`. Five hues instead of eight, but a
+ * themed app that forgot to import this package's stylesheet still gets colours
+ * that match its brand rather than the generic fallback below.
+ */
+const CHART_PALETTE_TOKENS = [
+    "--chart-1",
+    "--chart-2",
+    "--chart-3",
+    "--chart-4",
+    "--chart-5",
+];
+/**
+ * Last-resort palette, used when this package's `styles.css` was not imported.
+ * Plain hex on purpose: it must not itself depend on a token resolving.
+ */
+export const FALLBACK_THEME = {
+    foreground: "#18181b",
+    mutedForeground: "#71717a",
+    background: "#ffffff",
+    border: "#e4e4e7",
+    ring: "#8b5cf6",
+    palette: ["#7c3aed", "#0891b2", "#db2777", "#ea580c", "#16a34a", "#2563eb", "#ca8a04", "#9333ea"],
+};
+function readToken(styles, name) {
+    const raw = styles.getPropertyValue(name).trim();
+    return raw.length > 0 ? raw : null;
+}
+/**
+ * Resolve the theme against a mounted element.
+ *
+ * Takes an element rather than `document.documentElement` so a graph inside a
+ * scoped theme (the shell's `ThemeScope`, a preview pane) picks up that scope's
+ * tokens instead of the page's.
+ */
+export function resolveGraphTheme(element) {
+    if (!element || typeof window === "undefined" || !window.getComputedStyle) {
+        return FALLBACK_THEME;
+    }
+    const styles = window.getComputedStyle(element);
+    const readAll = (tokens) => tokens
+        .map((token) => readToken(styles, token))
+        .filter((value) => value !== null);
+    const graphPalette = readAll(PALETTE_TOKENS);
+    const chartPalette = graphPalette.length > 0 ? [] : readAll(CHART_PALETTE_TOKENS);
+    const palette = graphPalette.length > 0 ? graphPalette : chartPalette;
+    return {
+        foreground: readToken(styles, "--foreground") ?? FALLBACK_THEME.foreground,
+        mutedForeground: readToken(styles, "--muted-foreground") ?? FALLBACK_THEME.mutedForeground,
+        background: readToken(styles, "--background") ?? FALLBACK_THEME.background,
+        border: readToken(styles, "--border") ?? FALLBACK_THEME.border,
+        ring: readToken(styles, "--ring") ?? FALLBACK_THEME.ring,
+        palette: palette.length > 0 ? palette : FALLBACK_THEME.palette,
+    };
+}

package/dist/use-element-size.d.ts

@@ -0,0 +1,13 @@
+export interface ElementSize {
+    width: number;
+    height: number;
+}
+/**
+ * Track an element's box.
+ *
+ * `react-force-graph-2d` takes `width`/`height` as NUMBERS — it sizes the
+ * canvas imperatively and has no CSS-driven mode. Without an observer the
+ * canvas keeps its first measurement forever, so it goes blank when the tool
+ * panel is dragged wider or toggled fullscreen.
+ */
+export declare function useElementSize(element: Element | null): ElementSize;

package/dist/use-element-size.js

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react";
+/**
+ * Track an element's box.
+ *
+ * `react-force-graph-2d` takes `width`/`height` as NUMBERS — it sizes the
+ * canvas imperatively and has no CSS-driven mode. Without an observer the
+ * canvas keeps its first measurement forever, so it goes blank when the tool
+ * panel is dragged wider or toggled fullscreen.
+ */
+export function useElementSize(element) {
+    const [size, setSize] = useState({ width: 0, height: 0 });
+    useEffect(() => {
+        if (!element)
+            return;
+        const measure = () => {
+            const rect = element.getBoundingClientRect();
+            setSize((prev) => 
+            // Sub-pixel jitter from a flex parent would otherwise re-render (and
+            // re-measure) on every frame.
+            Math.abs(prev.width - rect.width) < 1 && Math.abs(prev.height - rect.height) < 1
+                ? prev
+                : { width: rect.width, height: rect.height });
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [element]);
+    return size;
+}

package/dist/use-graph-model.d.ts

@@ -0,0 +1,101 @@
+import { type GraphEdge, type GraphNode, type GraphPayload } from "./model.js";
+/**
+ * A node handed to the force engine. force-graph WRITES to these objects —
+ * `x`, `y`, `vx`, `vy` are the simulation's state, and `fx`/`fy` pin a node.
+ */
+export interface EngineNode extends GraphNode {
+    x?: number;
+    y?: number;
+    vx?: number;
+    vy?: number;
+    fx?: number;
+    fy?: number;
+}
+/** An edge handed to the engine. force-graph replaces the endpoint ids with
+ *  the resolved node objects in place, hence the widened type. */
+export interface EngineLink extends Omit<GraphEdge, "source" | "target"> {
+    source: string | EngineNode;
+    target: string | EngineNode;
+}
+/** Why the rendered graph is smaller than the payload. All zero is the happy path. */
+export interface GraphModelLoss {
+    /** Edges whose source or target was absent from the payload entirely. */
+    danglingEdges: number;
+    /** Nodes dropped by the node cap. */
+    cappedNodes: number;
+    /** Edges dropped — either stranded by the node cap, or over the edge cap. */
+    cappedEdges: number;
+}
+export interface GraphModel {
+    nodes: EngineNode[];
+    links: EngineLink[];
+    loss: GraphModelLoss;
+    /** True when anything at all was withheld from the canvas. */
+    lossy: boolean;
+}
+export interface GraphModelLimits {
+    maxNodes: number;
+    maxEdges: number;
+}
+/**
+ * Caps chosen so an accidental `MATCH (n) RETURN n` degrades to a slow-but-alive
+ * canvas instead of a frozen tab. Hosts with a known-small domain can raise them.
+ */
+export declare const DEFAULT_LIMITS: GraphModelLimits;
+/**
+ * Choose which nodes survive a cap: the connected core around the hubs.
+ *
+ * Which nodes survive decides whether the user sees a graph or confetti.
+ *
+ * Taking the first N in payload order keeps whatever the producer happened to
+ * emit first — for an unbounded query that is close to random, and the
+ * survivors are mostly unrelated, so the edges collapse with them.
+ *
+ * Taking the N highest-degree nodes is better but not enough. In a graph that
+ * is even loosely bipartite — films and people, orders and customers — the hubs
+ * all sit on one side and none of them are adjacent, so a small cap still
+ * yields a set with no edges at all. (Measured: on an 8-film demo graph, top-5
+ * by degree gave five films and zero relationships.)
+ *
+ * So: seed at the biggest hub and expand outwards through its neighbours,
+ * preferring well-connected ones, then start again at the next unvisited hub.
+ * Every node after the first seed is adjacent to one already chosen, so the
+ * result is a handful of connected neighbourhoods rather than scattered dust.
+ *
+ * Mirrors `select_connected_core` in the Neo4j starter's `graph_payload.py`;
+ * both sides cap, and they have to agree on what the important part of a graph
+ * is.
+ */
+export declare function selectConnectedCore(nodes: GraphNode[], edges: GraphEdge[], limit: number): GraphNode[];
+/**
+ * Turn a payload into the mutable objects the force engine wants, REUSING the
+ * object for any node whose id is already in `cache`.
+ *
+ * This is the single most important detail of driving force-graph. The
+ * simulation stores each node's position ON the node object. Build a fresh
+ * array every time — which `payload.nodes.map(...)` does — and every unrelated
+ * re-render (a hover, a search keystroke) throws away all positions, so the
+ * graph visibly explodes and re-settles. Reusing the object for an unchanged
+ * node keeps its identity, and therefore its place.
+ *
+ * Pure, and it returns the next cache rather than mutating the one passed in:
+ * the React binding is a thin wrapper below, and this stays testable — and
+ * usable — without a renderer.
+ *
+ * Nodes absent from the new payload are dropped from the returned cache, so
+ * this does not accumulate across successive queries.
+ */
+export declare function reconcileGraphModel(payload: GraphPayload, cache: ReadonlyMap<string, EngineNode>, limits?: GraphModelLimits): {
+    model: GraphModel;
+    cache: Map<string, EngineNode>;
+};
+/**
+ * A link's endpoint id, whichever form it is in.
+ *
+ * force-graph REPLACES an endpoint id with the node object once the simulation
+ * has run, so anything reading endpoints after a render has to accept both —
+ * comparing against `node.id` alone silently matches nothing.
+ */
+export declare function endpointId(end: unknown): string | undefined;
+/** React binding for {@link reconcileGraphModel}: holds the cache across renders. */
+export declare function useGraphModel(payload: GraphPayload, limits?: GraphModelLimits): GraphModel;

package/dist/use-graph-model.js

@@ -0,0 +1,164 @@
+import { useMemo, useRef } from "react";
+import { pruneDanglingEdges } from "./model.js";
+/**
+ * Caps chosen so an accidental `MATCH (n) RETURN n` degrades to a slow-but-alive
+ * canvas instead of a frozen tab. Hosts with a known-small domain can raise them.
+ */
+export const DEFAULT_LIMITS = { maxNodes: 1500, maxEdges: 3000 };
+/**
+ * Choose which nodes survive a cap: the connected core around the hubs.
+ *
+ * Which nodes survive decides whether the user sees a graph or confetti.
+ *
+ * Taking the first N in payload order keeps whatever the producer happened to
+ * emit first — for an unbounded query that is close to random, and the
+ * survivors are mostly unrelated, so the edges collapse with them.
+ *
+ * Taking the N highest-degree nodes is better but not enough. In a graph that
+ * is even loosely bipartite — films and people, orders and customers — the hubs
+ * all sit on one side and none of them are adjacent, so a small cap still
+ * yields a set with no edges at all. (Measured: on an 8-film demo graph, top-5
+ * by degree gave five films and zero relationships.)
+ *
+ * So: seed at the biggest hub and expand outwards through its neighbours,
+ * preferring well-connected ones, then start again at the next unvisited hub.
+ * Every node after the first seed is adjacent to one already chosen, so the
+ * result is a handful of connected neighbourhoods rather than scattered dust.
+ *
+ * Mirrors `select_connected_core` in the Neo4j starter's `graph_payload.py`;
+ * both sides cap, and they have to agree on what the important part of a graph
+ * is.
+ */
+export function selectConnectedCore(nodes, edges, limit) {
+    if (nodes.length <= limit)
+        return nodes;
+    const degree = new Map();
+    const adjacency = new Map();
+    for (const edge of edges) {
+        degree.set(edge.source, (degree.get(edge.source) ?? 0) + 1);
+        degree.set(edge.target, (degree.get(edge.target) ?? 0) + 1);
+        (adjacency.get(edge.source) ?? adjacency.set(edge.source, []).get(edge.source)).push(edge.target);
+        (adjacency.get(edge.target) ?? adjacency.set(edge.target, []).get(edge.target)).push(edge.source);
+    }
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    // Payload order breaks ties, so identical data caps identically — an
+    // unstable tiebreak makes the retained set flicker between renders.
+    const order = new Map(nodes.map((node, index) => [node.id, index]));
+    const better = (a, b) => (degree.get(b) ?? 0) - (degree.get(a) ?? 0) || (order.get(a) ?? 0) - (order.get(b) ?? 0);
+    const ranked = [...order.keys()].sort(better);
+    const chosen = [];
+    const seen = new Set();
+    for (const seed of ranked) {
+        if (chosen.length >= limit)
+            break;
+        if (seen.has(seed))
+            continue;
+        const queue = [seed];
+        seen.add(seed);
+        while (queue.length > 0 && chosen.length < limit) {
+            const current = queue.shift();
+            const node = byId.get(current);
+            if (node)
+                chosen.push(node);
+            const neighbours = (adjacency.get(current) ?? []).filter((id) => !seen.has(id)).sort(better);
+            for (const neighbour of neighbours) {
+                seen.add(neighbour);
+                queue.push(neighbour);
+            }
+        }
+    }
+    return chosen.slice(0, limit);
+}
+/**
+ * Turn a payload into the mutable objects the force engine wants, REUSING the
+ * object for any node whose id is already in `cache`.
+ *
+ * This is the single most important detail of driving force-graph. The
+ * simulation stores each node's position ON the node object. Build a fresh
+ * array every time — which `payload.nodes.map(...)` does — and every unrelated
+ * re-render (a hover, a search keystroke) throws away all positions, so the
+ * graph visibly explodes and re-settles. Reusing the object for an unchanged
+ * node keeps its identity, and therefore its place.
+ *
+ * Pure, and it returns the next cache rather than mutating the one passed in:
+ * the React binding is a thin wrapper below, and this stays testable — and
+ * usable — without a renderer.
+ *
+ * Nodes absent from the new payload are dropped from the returned cache, so
+ * this does not accumulate across successive queries.
+ */
+export function reconcileGraphModel(payload, cache, limits = DEFAULT_LIMITS) {
+    {
+        const { nodes: allNodes, edges: connectedEdges, dropped: danglingEdges, } = pruneDanglingEdges(payload);
+        const keptNodes = selectConnectedCore(allNodes, connectedEdges, limits.maxNodes);
+        const cappedNodes = allNodes.length - keptNodes.length;
+        // Dropping nodes strands edges that were connected a moment ago, so the
+        // edge set is re-filtered against the surviving nodes rather than reused.
+        const keptIds = new Set(keptNodes.map((node) => node.id));
+        const survivingEdges = connectedEdges.filter((edge) => keptIds.has(edge.source) && keptIds.has(edge.target));
+        const keptEdges = survivingEdges.slice(0, limits.maxEdges);
+        // Every edge that made it past the dangling prune but not onto the canvas,
+        // whichever cap took it.
+        const cappedEdges = connectedEdges.length - keptEdges.length;
+        const next = new Map();
+        const nodes = keptNodes.map((node) => {
+            const existing = cache.get(node.id);
+            if (existing) {
+                // Refresh the data fields in place; leave x/y/vx/vy/fx/fy alone —
+                // those belong to the simulation, not to the payload.
+                existing.labels = node.labels;
+                existing.caption = node.caption;
+                existing.properties = node.properties;
+                next.set(node.id, existing);
+                return existing;
+            }
+            const created = { ...node };
+            next.set(node.id, created);
+            return created;
+        });
+        const loss = { danglingEdges, cappedNodes, cappedEdges };
+        return {
+            model: {
+                nodes,
+                // Links carry no simulation state we need to preserve — force-graph
+                // resolves the endpoint ids to node objects itself on each data set —
+                // so unlike nodes they can be rebuilt freely.
+                links: keptEdges.map((edge) => ({ ...edge })),
+                loss,
+                lossy: danglingEdges > 0 || cappedNodes > 0 || cappedEdges > 0,
+            },
+            cache: next,
+        };
+    }
+}
+/**
+ * A link's endpoint id, whichever form it is in.
+ *
+ * force-graph REPLACES an endpoint id with the node object once the simulation
+ * has run, so anything reading endpoints after a render has to accept both —
+ * comparing against `node.id` alone silently matches nothing.
+ */
+export function endpointId(end) {
+    if (typeof end === "string")
+        return end;
+    if (typeof end === "number")
+        return String(end);
+    if (typeof end === "object" && end !== null && "id" in end) {
+        const id = end.id;
+        if (typeof id === "string" || typeof id === "number")
+            return String(id);
+    }
+    return undefined;
+}
+/** React binding for {@link reconcileGraphModel}: holds the cache across renders. */
+export function useGraphModel(payload, limits = DEFAULT_LIMITS) {
+    const cacheRef = useRef(new Map());
+    return useMemo(() => {
+        const { model, cache } = reconcileGraphModel(payload, cacheRef.current, limits);
+        cacheRef.current = cache;
+        return model;
+        // `limits` is an object literal at most call sites, so depend on its
+        // fields rather than its identity — otherwise every render reconciles.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [payload, limits.maxNodes, limits.maxEdges]);
+}

package/dist/use-graph-styling.d.ts

@@ -0,0 +1,55 @@
+import { type GraphEdge, type GraphNode, type GraphPayload } from "./model.js";
+import type { GraphTheme } from "./theme.js";
+/** Host-supplied styling overrides, all optional. */
+export interface GraphStyling {
+    /** Explicit colour per label. Labels not listed fall back to the palette. */
+    colors?: Record<string, string>;
+    /** Property key to read the caption from, per label. */
+    captionKeys?: Record<string, string>;
+    /** Relative node size per label (1 = default). */
+    sizes?: Record<string, number>;
+}
+/** Everything the canvas needs to draw one node, precomputed once per payload. */
+export interface NodeStyle {
+    color: string;
+    caption: string;
+    radius: number;
+}
+export interface GraphStyleMap {
+    /** Distinct labels in first-seen order — also the legend's order. */
+    labels: string[];
+    colorForLabel: (label: string) => string;
+    styleForNode: (node: GraphNode) => NodeStyle;
+    /** Distinct relationship types, for the legend. */
+    edgeTypes: string[];
+}
+/**
+ * Assign a palette slot per label — by hash, then linear probing.
+ *
+ * Colour has to mean the same thing across queries. Assigning slots in
+ * first-seen order is collision-free but makes `Person` blue in one result and
+ * red in the next, so the legend has to be re-read every time and no mental
+ * model of the graph ever forms. Hashing pins a label to a colour it keeps.
+ *
+ * Probing covers the hash's weakness: two labels that hash to the same slot
+ * would otherwise be indistinguishable in exactly the small graphs where the
+ * legend matters most. With eight colours and a handful of labels a collision
+ * is likelier than not, so dropping it is not an option.
+ *
+ * The cost, stated plainly because it is a real one: a label's colour depends
+ * on which OTHER labels are present. Add a label that hashes to the same slot
+ * and sorts earlier, and the first label moves one slot along — so a label can
+ * change colour between two queries, and can change colour mid-session as a
+ * merge grows the graph. There is no way to have both properties with a fixed
+ * eight-colour palette; distinctness within one graph is the one worth having,
+ * because the swatch is only ever read next to the label's own name.
+ *
+ * Sorted order at least makes the outcome depend on WHICH labels are present
+ * and never on the order the producer happened to return them in.
+ */
+declare function buildLabelColors(labels: string[], palette: string[], overrides: Record<string, string> | undefined): Map<string, string>;
+export declare function useGraphStyling(payload: GraphPayload, theme: GraphTheme, styling?: GraphStyling): GraphStyleMap;
+/** Human-readable one-liner for a hover tooltip. */
+export declare function describeNode(node: GraphNode, caption: string): string;
+export declare function describeEdge(edge: GraphEdge): string;
+export { buildLabelColors as __buildLabelColorsForTest };

package/dist/use-graph-styling.js

@@ -0,0 +1,156 @@
+import { useMemo } from "react";
+import { hasOwn, primaryLabel, resolveCaption, } from "./model.js";
+/** Small, stable string hash (FNV-1a). Deterministic across runs and machines. */
+function hashLabel(label) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < label.length; i += 1) {
+        hash ^= label.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash;
+}
+/**
+ * Assign a palette slot per label — by hash, then linear probing.
+ *
+ * Colour has to mean the same thing across queries. Assigning slots in
+ * first-seen order is collision-free but makes `Person` blue in one result and
+ * red in the next, so the legend has to be re-read every time and no mental
+ * model of the graph ever forms. Hashing pins a label to a colour it keeps.
+ *
+ * Probing covers the hash's weakness: two labels that hash to the same slot
+ * would otherwise be indistinguishable in exactly the small graphs where the
+ * legend matters most. With eight colours and a handful of labels a collision
+ * is likelier than not, so dropping it is not an option.
+ *
+ * The cost, stated plainly because it is a real one: a label's colour depends
+ * on which OTHER labels are present. Add a label that hashes to the same slot
+ * and sorts earlier, and the first label moves one slot along — so a label can
+ * change colour between two queries, and can change colour mid-session as a
+ * merge grows the graph. There is no way to have both properties with a fixed
+ * eight-colour palette; distinctness within one graph is the one worth having,
+ * because the swatch is only ever read next to the label's own name.
+ *
+ * Sorted order at least makes the outcome depend on WHICH labels are present
+ * and never on the order the producer happened to return them in.
+ */
+function buildLabelColors(labels, palette, overrides) {
+    const out = new Map();
+    const taken = new Set();
+    const assignable = [...labels].sort();
+    for (const label of assignable) {
+        // An own-key check because a label is untrusted: `overrides?.["toString"]`
+        // finds a function on the prototype and paints a node with it.
+        const override = overrides && hasOwn(overrides, label) ? overrides[label] : undefined;
+        if (override) {
+            out.set(label, override);
+            continue;
+        }
+        let slot = hashLabel(label) % palette.length;
+        // At most one full pass: with more labels than colours some reuse is
+        // unavoidable, and stopping keeps this O(palette) rather than looping.
+        for (let probe = 0; probe < palette.length && taken.has(slot); probe += 1) {
+            slot = (slot + 1) % palette.length;
+        }
+        taken.add(slot);
+        out.set(label, palette[slot]);
+    }
+    return out;
+}
+/** Radius of a leaf node, in graph units. */
+const BASE_RADIUS = 6;
+/** A hub may grow to this multiple of the base — enough to read at a glance,
+ *  not so much that one supernode swallows the canvas. */
+const MAX_DEGREE_SCALE = 2.4;
+export function useGraphStyling(payload, theme, styling) {
+    return useMemo(() => {
+        const labels = [];
+        const seenLabels = new Set();
+        for (const node of payload.nodes) {
+            const label = primaryLabel(node);
+            if (!seenLabels.has(label)) {
+                seenLabels.add(label);
+                labels.push(label);
+            }
+        }
+        const edgeTypes = [];
+        const seenTypes = new Set();
+        for (const edge of payload.edges) {
+            const type = edge.type ?? "RELATED";
+            if (!seenTypes.has(type)) {
+                seenTypes.add(type);
+                edgeTypes.push(type);
+            }
+        }
+        // Producer-supplied legend colours are an override of last resort — the
+        // host's explicit `styling.colors` still wins.
+        const producerColors = Object.create(null);
+        for (const [label, hint] of Object.entries(payload.legend ?? {})) {
+            if (hint.color)
+                producerColors[label] = hint.color;
+        }
+        const colors = buildLabelColors(labels, theme.palette, {
+            ...producerColors,
+            ...(styling?.colors ?? {}),
+        });
+        // A `Map`, because the keys are LABELS and labels come from the payload.
+        // A graph with a label called `constructor` or `toString` reads an
+        // inherited function out of an object literal, and it would be handed to
+        // `resolveCaption` as the caption key.
+        const captionKeys = new Map();
+        for (const [label, hint] of Object.entries(payload.legend ?? {})) {
+            if (hint.captionKey)
+                captionKeys.set(label, hint.captionKey);
+        }
+        for (const [label, key] of Object.entries(styling?.captionKeys ?? {})) {
+            captionKeys.set(label, key);
+        }
+        const colorForLabel = (label) => colors.get(label) ?? theme.palette[0] ?? theme.foreground;
+        // Size by connectedness. In a force layout every node is a same-sized
+        // dot, so the structure — which nodes hold the graph together — is
+        // invisible until you trace the edges by eye. Scaling by degree makes the
+        // hubs read immediately, and it is the single change that most makes a
+        // force graph look like a graph explorer rather than a hairball.
+        // sqrt, not linear: degree is long-tailed, and a linear scale turns one
+        // supernode into a disc that covers everything else.
+        const degree = new Map();
+        for (const edge of payload.edges) {
+            degree.set(edge.source, (degree.get(edge.source) ?? 0) + 1);
+            degree.set(edge.target, (degree.get(edge.target) ?? 0) + 1);
+        }
+        let maxDegree = 0;
+        for (const value of degree.values())
+            maxDegree = Math.max(maxDegree, value);
+        const degreeScale = (id) => {
+            if (maxDegree <= 1)
+                return 1;
+            const ratio = Math.sqrt((degree.get(id) ?? 0) / maxDegree);
+            return 1 + ratio * (MAX_DEGREE_SCALE - 1);
+        };
+        const styleCache = new Map();
+        const styleForNode = (node) => {
+            const cached = styleCache.get(node.id);
+            if (cached)
+                return cached;
+            const label = primaryLabel(node);
+            const style = {
+                color: colorForLabel(label),
+                caption: resolveCaption(node, captionKeys.get(label)),
+                radius: BASE_RADIUS *
+                    degreeScale(node.id) *
+                    (styling?.sizes && hasOwn(styling.sizes, label) ? (styling.sizes[label] ?? 1) : 1),
+            };
+            styleCache.set(node.id, style);
+            return style;
+        };
+        return { labels, colorForLabel, styleForNode, edgeTypes };
+    }, [payload, theme, styling]);
+}
+/** Human-readable one-liner for a hover tooltip. */
+export function describeNode(node, caption) {
+    const labels = node.labels?.length ? node.labels.join(":") : "Node";
+    return `${labels} — ${caption}`;
+}
+export function describeEdge(edge) {
+    return edge.type ?? "RELATED";
+}
+export { buildLabelColors as __buildLabelColorsForTest };

package/dist/use-graph-theme.d.ts

@@ -0,0 +1,11 @@
+import { type GraphTheme } from "./theme.js";
+/**
+ * Keep {@link GraphTheme} in sync with the DOM.
+ *
+ * Re-resolves when the `class`, `data-theme` or `style` attribute changes
+ * anywhere up the tree — between them that is how every theme switcher in this
+ * stack signals a flip (Tailwind's `.dark` class, an explicit `data-theme`, or
+ * a runtime layer writing variables inline). Watching the element itself is not
+ * enough: the class usually lands on `<html>`, far above.
+ */
+export declare function useGraphTheme(element: Element | null): GraphTheme;