@iloveagents/foundry-web-graph 0.1.0

package/dist/graph-view.js

@@ -0,0 +1,338 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, lazy, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, } from "react";
+import { cn } from "@iloveagents/foundry-web-primitives";
+import { deepEqual, primaryLabel, } from "./model.js";
+import { GraphLegend } from "./graph-legend.js";
+import { GraphInspector, GRAPH_INSPECTOR_WIDTH } from "./graph-inspector.js";
+import { GraphToolbar } from "./graph-toolbar.js";
+import { GraphEmptyState, GraphLossNotice } from "./graph-notice.js";
+import { GraphTable } from "./graph-table.js";
+import { useElementSize } from "./use-element-size.js";
+import { endpointId, useGraphModel, DEFAULT_LIMITS, } from "./use-graph-model.js";
+import { useGraphStyling } from "./use-graph-styling.js";
+import { useGraphTheme } from "./use-graph-theme.js";
+import { useGraphViewState } from "./use-graph-view-state.js";
+/**
+ * The engine is code-split.
+ *
+ * `react-force-graph-2d` pulls in force-graph and the d3 force/zoom/drag
+ * stack. A chat app that shows one graph card in ten conversations should not
+ * pay for that on first paint, and a host that only wants the payload types
+ * should not pay for it at all.
+ */
+const GraphCanvas = lazy(() => import("./graph-canvas.js"));
+/**
+ * Is there a canvas that can actually be DRAWN on?
+ *
+ * `typeof HTMLCanvasElement === "undefined"` was the wrong question. A stock
+ * jsdom defines the class and then throws "Not implemented" from
+ * `getContext`, so a consumer's test rendering `GraphView` took the engine
+ * path and hit unimplemented APIs instead of the readable table this fallback
+ * exists to give them. Asking for the context answers what the caller meant.
+ *
+ * Probed once: the answer cannot change within a page, and this is read on
+ * every render.
+ */
+let usableCanvas;
+function hasUsableCanvas() {
+    if (usableCanvas !== undefined)
+        return usableCanvas;
+    if (typeof document === "undefined" || typeof HTMLCanvasElement === "undefined") {
+        usableCanvas = false;
+        return usableCanvas;
+    }
+    try {
+        usableCanvas = document.createElement("canvas").getContext("2d") !== null;
+    }
+    catch {
+        usableCanvas = false;
+    }
+    return usableCanvas;
+}
+/**
+ * Run after the frame that opens the details drawer.
+ *
+ * Callers frame a node right after selecting it (`graph_select_node` does
+ * exactly that), and it is the selection that opens the drawer — so on this
+ * tick the width deciding what is visible does not exist yet. Framing now
+ * would put the node underneath the panel about to describe it.
+ */
+function afterDrawer(run) {
+    if (typeof requestAnimationFrame === "function")
+        requestAnimationFrame(run);
+    else
+        run();
+}
+function usePrefersReducedMotion() {
+    const [reduced, setReduced] = useState(false);
+    useEffect(() => {
+        if (typeof window === "undefined" || !window.matchMedia)
+            return;
+        const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+        const sync = () => setReduced(query.matches);
+        sync();
+        query.addEventListener("change", sync);
+        return () => query.removeEventListener("change", sync);
+    }, []);
+    return reduced;
+}
+/**
+ * An interactive, force-directed graph.
+ *
+ * Source-agnostic by construction: it takes a {@link GraphPayload} and knows
+ * nothing about where the nodes came from. Expansion is a callback, so the view
+ * never issues a query of its own.
+ */
+export function GraphView({ data, variant = "full", height = 420, className, styling, limits = DEFAULT_LIMITS, onExpandNode, onSelectionChange, onQueryChange, onFilterChange, inspectorActions, forceTable = false, handleRef, }) {
+    const [container, setContainer] = useState(null);
+    // The canvas is opaque to a screen reader; the table is the same graph as
+    // real DOM. Off by default, one button away.
+    const [tableRequested, setTableRequested] = useState(false);
+    const [canvasHost, setCanvasHost] = useState(null);
+    const canvasRef = useRef(null);
+    const theme = useGraphTheme(container);
+    const reducedMotion = usePrefersReducedMotion();
+    const model = useGraphModel(data, limits);
+    const styleMap = useGraphStyling(data, theme, styling);
+    const captionOf = useCallback((node) => styleMap.styleForNode(node).caption, [styleMap]);
+    const state = useGraphViewState(data, captionOf);
+    const size = useElementSize(canvasHost);
+    // A `Map`, not `{}`. Labels come from the payload and the payload is
+    // source-neutral — nothing stops a graph from having a label called
+    // `constructor` or `toString`, and both the write (`out[label] ?? 0`) and
+    // the legend\'s read would then find an inherited function where a count
+    // belongs, so the chip shows a stringified function or `NaN`.
+    const counts = useMemo(() => {
+        const out = new Map();
+        for (const node of model.nodes) {
+            const label = primaryLabel(node);
+            out.set(label, (out.get(label) ?? 0) + 1);
+        }
+        return out;
+    }, [model.nodes]);
+    const { selection, selectNode } = state;
+    /**
+     * The graph as DRAWN: the capped model, minus anything the legend hides.
+     *
+     * One derivation, so the canvas, the readable table and the agent cannot
+     * disagree about what is on screen. Hiding a label takes its relationships
+     * with it — the canvas already does that through `linkVisibility`, and the
+     * table showed them until this existed.
+     */
+    const visibleModel = useMemo(() => {
+        if (state.hiddenLabels.size === 0)
+            return model;
+        const nodes = model.nodes.filter((node) => !state.hiddenLabels.has(primaryLabel(node)));
+        const ids = new Set(nodes.map((node) => node.id));
+        const links = model.links.filter((link) => {
+            const source = endpointId(link.source);
+            const target = endpointId(link.target);
+            return source !== undefined && target !== undefined && ids.has(source) && ids.has(target);
+        });
+        return { ...model, nodes, links };
+    }, [model, state.hiddenLabels]);
+    /**
+     * Report changes, and ONLY changes.
+     *
+     * A host almost always passes these as inline arrows, so their identity is
+     * new on every render and an effect that lists them as dependencies re-runs
+     * every render — firing "the selection changed" when it did not. That is
+     * fine until a listener writes to a store the host also reads, at which
+     * point the notification causes the render that causes the notification.
+     * (It did: routing the selection into the chat context deadlocked the panel
+     * with "Maximum update depth exceeded" the moment a node was selected.)
+     *
+     * Debouncing or stabilising callbacks host-side would paper over it. The
+     * component's own contract is the right place to hold the line: a change
+     * callback fires when the value changes.
+     */
+    /**
+     * Identity is not enough to say the selection is unchanged.
+     *
+     * `reconcileGraphModel` refreshes a node's `labels`/`caption`/`properties`
+     * IN PLACE, precisely so the simulation keeps its position — so after a
+     * merge that rewrote the selected node, the object is the same object with
+     * different data. The drawer re-rendered and showed the new values; the
+     * listener never fired, and `syncGraphSelectionContext` snapshots
+     * `properties` into the chat context, so the agent went on answering about
+     * "this node" from the values before the write.
+     *
+     * Comparing the VALUE keeps the loop-prevention this guard exists for — it
+     * changes only when the data actually changes — while noticing that case.
+     * Held as a value rather than a serialized signature so nothing stringifies
+     * a node\'s whole property bag on every render, and so a `bigint` property
+     * cannot collide with the string of its own digits.
+     */
+    const selectionValue = selection.node
+        ? [
+            selection.node.id,
+            selection.node.labels ?? [],
+            selection.node.caption ?? null,
+            selection.node.properties ?? {},
+        ]
+        : null;
+    const notifiedSelection = useRef(selectionValue);
+    useEffect(() => {
+        if (deepEqual(notifiedSelection.current, selectionValue))
+            return;
+        notifiedSelection.current = selectionValue;
+        onSelectionChange?.(selection.node);
+        // Deliberately runs on EVERY render, gated by the comparison above rather
+        // than by a dependency list. The case this exists to catch is
+        // `reconcileGraphModel` refreshing the selected node IN PLACE — the object
+        // is identical, so no dependency can see it; only re-reading the value can.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    });
+    /**
+     * How much of the canvas the details drawer covers.
+     *
+     * Framing reads this so a node is centred in what the user can SEE. Zero
+     * whenever the drawer is closed, so an inline card is unaffected.
+     */
+    const showsInspector = variant === "full" && Boolean(selection.node || selection.edge);
+    /**
+     * Matches AMONG THE DRAWN NODES.
+     *
+     * `matchedIds` is computed from the payload, which is what the canvas needs
+     * — it dims by id and only ever paints visible nodes anyway. The toolbar is
+     * different: it states a number to the user. Counting the payload let it
+     * report "1 match" with every node on screen dimmed and nothing found,
+     * whenever the only hit was one the render cap dropped or the legend hid.
+     */
+    const visibleMatchCount = useMemo(() => {
+        if (state.matchedIds.size === 0)
+            return 0;
+        return visibleModel.nodes.reduce((count, node) => (state.matchedIds.has(node.id) ? count + 1 : count), 0);
+    }, [state.matchedIds, visibleModel.nodes]);
+    const inspectorInset = showsInspector ? Math.min(GRAPH_INSPECTOR_WIDTH, size.width * 0.85) : 0;
+    const notifiedQuery = useRef(state.query);
+    useEffect(() => {
+        if (notifiedQuery.current === state.query)
+            return;
+        notifiedQuery.current = state.query;
+        onQueryChange?.(state.query);
+    }, [state.query, onQueryChange]);
+    // Same shape, same reason: hosts pass an inline arrow, so the change has to
+    // be detected from the VALUE. Sorted so a Set rebuilt in a different order
+    // is not reported as a change.
+    const hiddenLabels = useMemo(() => [...state.hiddenLabels].sort().join("\u0000"), [state.hiddenLabels]);
+    const notifiedHidden = useRef(hiddenLabels);
+    useEffect(() => {
+        if (notifiedHidden.current === hiddenLabels)
+            return;
+        notifiedHidden.current = hiddenLabels;
+        onFilterChange?.(hiddenLabels.length === 0 ? [] : hiddenLabels.split("\u0000"));
+    }, [hiddenLabels, onFilterChange]);
+    /**
+     * Everything the handle answers from, refreshed every render.
+     *
+     * The handle itself must be ONE object for the life of the view.
+     * `GraphPanel` stores `handleRef.current` in the workspace when it connects
+     * and reconnects only on a payload, title or visibility change — so a handle
+     * rebuilt whenever the view state changed left the workspace, and every
+     * client tool through it, holding a closure over the view as it was when the
+     * panel opened. `graph_get_view` would answer without the search the user
+     * had since typed; `graph_select_node` would accept a node hidden after
+     * connection. Nothing surfaced it, because a merge changes the payload and
+     * so happens to reconnect.
+     *
+     * `useGraphViewState` returns a fresh object literal every render, which is
+     * what made `state` in a dependency list mean "every render".
+     */
+    const live = useRef({ model, visibleModel, state, selectNode });
+    // Assigned during render on purpose: the handle's methods are only ever
+    // called imperatively — by the host, or by a client tool the agent ran —
+    // never while rendering, so there is nothing here to tear. Deferring it to
+    // an effect would leave the handle a render behind instead.
+    live.current = { model, visibleModel, state, selectNode };
+    useImperativeHandle(handleRef, () => ({
+        zoomToFit: (durationMs) => canvasRef.current?.zoomToFit(durationMs),
+        centerOn: (nodeId, durationMs) => afterDrawer(() => canvasRef.current?.centerOn(nodeId, durationMs)),
+        reveal: (nodeId, durationMs) => afterDrawer(() => canvasRef.current?.reveal(nodeId, durationMs)),
+        search: (term) => live.current.state.setQuery(term),
+        select: (nodeId) => {
+            const { visibleModel: drawn, selectNode: choose } = live.current;
+            if (nodeId === null) {
+                choose(null);
+                return true;
+            }
+            // The DRAWN nodes: a label hidden in the legend is as absent from the
+            // canvas as one the render cap dropped, and reporting success for it
+            // opens a drawer describing something invisible.
+            const node = drawn.nodes.find((n) => n.id === nodeId) ?? null;
+            if (node)
+                choose(node);
+            return node !== null;
+        },
+        unpinAll: () => live.current.state.unpinAll(),
+        getViewState: () => {
+            const { state, visibleModel, model } = live.current;
+            return {
+                selection: state.selection.node,
+                // A legend filter is a view toggle, not a deletion, so hiding a
+                // selected node\'s label does NOT clear the selection — the drawer
+                // stays open and its properties are still on screen, which is what
+                // the user is reading. But `nodes` below excludes it, so reporting
+                // the selection bare made this result contradict itself. Saying
+                // whether it is drawn is what lets the agent be precise: "selected,
+                // though its label is hidden" rather than a node that is somehow both
+                // selected and absent.
+                selectionDrawn: state.selection.node
+                    ? visibleModel.nodes.some((node) => node.id === state.selection.node?.id)
+                    : false,
+                query: state.query,
+                hiddenLabels: [...state.hiddenLabels],
+                nodes: visibleModel.nodes,
+                // Normalised, because force-graph REPLACES a link's `source`/`target`
+                // with the node objects once it has run — so handing these out raw
+                // put whole simulation objects, mutable layout fields and all, where
+                // a caller expects an id.
+                edges: visibleModel.links.map((link) => ({
+                    ...link,
+                    source: endpointId(link.source) ?? "",
+                    target: endpointId(link.target) ?? "",
+                })),
+                selectedEdge: state.selection.edge
+                    ? {
+                        ...state.selection.edge,
+                        source: endpointId(state.selection.edge.source) ?? "",
+                        target: endpointId(state.selection.edge.target) ?? "",
+                    }
+                    : null,
+                lossy: model.lossy,
+            };
+        },
+    }), 
+    // Empty ON PURPOSE — see `live` above. One handle for the life of the
+    // view; everything it answers from is read at call time.
+    []);
+    // `forceTable` is the print path; `tableRequested` is the user asking, from
+    // the toolbar; `noCanvas` is the environment having nothing to draw on.
+    const noCanvas = !hasUsableCanvas();
+    const useTable = forceTable || noCanvas || tableRequested;
+    const isEmpty = model.nodes.length === 0;
+    return (_jsxs("div", { ref: setContainer, className: cn("flex min-h-0 flex-col gap-2", className), style: { height }, children: [_jsx(GraphToolbar, { query: state.query, onQueryChange: state.setQuery, matchCount: visibleMatchCount, 
+                // The DRAWN graph, like every other count on this screen. Reading the
+                // capped-but-unfiltered model meant switching a label off left the
+                // toolbar saying "2 nodes · 1 rels" beside a canvas showing one node
+                // and no relationships.
+                nodeCount: visibleModel.nodes.length, edgeCount: visibleModel.links.length, onZoomToFit: () => canvasRef.current?.zoomToFit(), onReheat: () => canvasRef.current?.reheat(), pinnedCount: state.pinnedIds.size, onUnpinAll: state.unpinAll, showsTable: useTable, 
+                // No control where there is no choice: a host that pinned the table
+                // with `forceTable`, or an environment with no canvas to go back to.
+                onToggleTable: forceTable || noCanvas ? undefined : () => setTableRequested((shown) => !shown), className: "shrink-0" }), _jsx(GraphLegend, { styleMap: styleMap, counts: counts, hiddenLabels: state.hiddenLabels, onToggleLabel: state.toggleLabel, onShowAll: state.showAllLabels, className: "shrink-0" }), (model.lossy || data.truncated) && (_jsx(GraphLossNotice, { loss: model.loss, truncatedByProducer: data.truncated, className: "shrink-0" })), _jsx("div", { className: "flex min-h-0 flex-1", children: _jsxs("div", { ref: setCanvasHost, className: "border-border bg-background relative min-h-0 flex-1 overflow-hidden rounded-lg border", children: [isEmpty ? (_jsx(GraphEmptyState, {})) : useTable ? (_jsx(GraphTable, { model: visibleModel, styleMap: styleMap, onSelectNode: selectNode, onSelectEdge: state.selectEdge, className: "h-full" })) : (
+                        // `role="img"` wraps the CANVAS ONLY. ARIA exposes the descendants
+                        // of an image as presentational, so with this on the box that also
+                        // holds `GraphInspector`, selecting a node deleted the whole
+                        // drawer — its dialog, its property rows, its Pin/Freeze/Expand
+                        // controls — from the accessibility tree, at exactly the moment
+                        // the user asked to inspect something.
+                        //
+                        // The canvas itself genuinely is one opaque element to a screen
+                        // reader: the nodes and relationships are pixels, and no labelling
+                        // changes that. So the region says what it holds and where the
+                        // readable form is; the toolbar's button is what gets you there.
+                        _jsx("div", { role: "img", "aria-label": 
+                            // Same numbers the sighted user is given, for the same reason.
+                            `Graph: ${visibleModel.nodes.length} nodes, ${visibleModel.links.length} relationships. ` +
+                                `Use "Show as a table" for a readable version.`, className: "absolute inset-0", children: _jsx(Suspense, { fallback: _jsx(GraphEmptyState, { message: "Loading graph\u2026" }), children: size.width > 0 && size.height > 0 && (_jsx(GraphCanvas, { model: model, styleMap: styleMap, theme: theme, state: state, width: size.width, height: size.height, onExpandNode: onExpandNode, insetRight: inspectorInset, handleRef: canvasRef, reducedMotion: reducedMotion })) }) })), showsInspector && (_jsx(GraphInspector, { selection: selection, colorForLabel: styleMap.colorForLabel, captionOf: captionOf, onClose: state.clearSelection, onExpandNode: onExpandNode, onToggleFrozen: (node) => state.togglePinned(node.id), isFrozen: (node) => state.pinnedIds.has(node.id), actions: selection.node && inspectorActions ? inspectorActions(selection.node) : null }))] }) })] }));
+}

package/dist/graph-workspace.d.ts

@@ -0,0 +1,55 @@
+import { type GraphNode, type GraphPayload } from "./model.js";
+import type { GraphViewHandle } from "./graph-view.js";
+/**
+ * The live graph the user is looking at.
+ *
+ * This is what turns the panel from a picture into a workspace the agent and
+ * the user share. The agent can ask what is on screen, drive the selection,
+ * and replace the data in place; the user's own clicks land in the same state,
+ * so the next question can be about "this node" without either side having to
+ * restate it.
+ *
+ * Vanilla zustand (not the React entry) so the store itself has no renderer
+ * dependency — the client tools that read it run outside React.
+ */
+export interface GraphWorkspaceState {
+    /** Imperative handle of the mounted panel view, or null when none is open. */
+    handle: GraphViewHandle | null;
+    title: string | null;
+    payload: GraphPayload | null;
+    /** What the user (or the agent) currently has selected. */
+    selection: GraphNode | null;
+    /** The active search term, if any. */
+    query: string;
+    /**
+     * Labels the user has switched OFF in the legend.
+     *
+     * Published because what the agent sees has to be what the user sees: a
+     * hidden label's nodes and relationships are not drawn, and an account of
+     * "the graph" that counts them describes a screen nobody is looking at.
+     */
+    hiddenLabels: readonly string[];
+    connect: (handle: GraphViewHandle, title: string, payload: GraphPayload) => void;
+    disconnect: (handle: GraphViewHandle) => void;
+    setSelection: (node: GraphNode | null) => void;
+    setQuery: (query: string) => void;
+    setHiddenLabels: (labels: readonly string[]) => void;
+}
+/** Test seam: put the workspace back to "nothing is open", every field of it. */
+export declare const _resetGraphWorkspace: () => void;
+export declare const graphWorkspaceStore: import("zustand").StoreApi<GraphWorkspaceState>;
+/** Is a graph panel currently open? */
+export declare const isGraphOpen: () => boolean;
+/**
+ * Find a node by id, or failing that by caption — case-insensitively, exact
+ * before partial.
+ *
+ * The agent refers to nodes the way the user does ("select Metropolis"), not
+ * by the database's element id, which it has usually never seen.
+ */
+/** Several nodes answer to the same text; the caller must disambiguate. */
+export interface AmbiguousMatch {
+    ambiguous: GraphNode[];
+}
+export declare const isAmbiguous: (value: unknown) => value is AmbiguousMatch;
+export declare function findWorkspaceNode(needle: string): GraphNode | AmbiguousMatch | null;

package/dist/graph-workspace.js

@@ -0,0 +1,100 @@
+import { createStore } from "zustand/vanilla";
+import { primaryLabel, resolveCaption } from "./model.js";
+/**
+ * Every field of the workspace at rest, in one place.
+ *
+ * `disconnect` and the tests both need "nothing is open", and writing that out
+ * twice is how a field added later gets left out of one of them — zustand's
+ * `setState` MERGES, so a partial reset silently keeps the old value and the
+ * tests become order-dependent. `hiddenLabels` had already drifted that way.
+ */
+const CLOSED = {
+    handle: null,
+    title: null,
+    payload: null,
+    selection: null,
+    query: "",
+    hiddenLabels: [],
+};
+/** Test seam: put the workspace back to "nothing is open", every field of it. */
+export const _resetGraphWorkspace = () => graphWorkspaceStore.setState({ ...CLOSED });
+export const graphWorkspaceStore = createStore((set, get) => ({
+    ...CLOSED,
+    connect: (handle, title, payload) => set((state) => {
+        // A selection has to belong to the graph it is reported against.
+        //
+        // React mounts a replacement panel BEFORE unmounting the old one, and
+        // `disconnect` deliberately no-ops once a newer panel has claimed the
+        // workspace — so without this the previous graph's selection survives
+        // into the new one, and `graph_get_view` tells the agent a node is
+        // selected that is not on screen.
+        //
+        // Keeping it when it survives matters just as much: a merge changes
+        // `payload` on the SAME panel, and clearing unconditionally would drop
+        // the user's selection every time the agent expanded a node.
+        // Both conditions, and the first is the one that was missing: ids come
+        // from one database, so two panels showing overlapping results share
+        // them, and "the id is in the new payload" was letting panel A's
+        // selection arrive in panel B as something the user never clicked.
+        const samePanel = state.handle === handle;
+        const stillThere = state.selection !== null && payload.nodes.some((node) => node.id === state.selection?.id);
+        return {
+            handle,
+            title,
+            payload,
+            selection: samePanel && stillThere ? state.selection : null,
+            query: samePanel ? state.query : "",
+            hiddenLabels: samePanel ? state.hiddenLabels : [],
+        };
+    }),
+    disconnect: (handle) => {
+        // Guard against a stale unmount clearing a workspace that a NEWER panel
+        // has already claimed — React unmounts the old tree after mounting the
+        // new one, so the order is not the intuitive one.
+        if (get().handle !== handle)
+            return;
+        set({ ...CLOSED });
+    },
+    setSelection: (selection) => set({ selection }),
+    setQuery: (query) => set({ query }),
+    setHiddenLabels: (hiddenLabels) => set({ hiddenLabels }),
+}));
+/** Is a graph panel currently open? */
+export const isGraphOpen = () => graphWorkspaceStore.getState().payload !== null;
+export const isAmbiguous = (value) => typeof value === "object" && value !== null && "ambiguous" in value;
+export function findWorkspaceNode(needle) {
+    const { payload } = graphWorkspaceStore.getState();
+    if (!payload)
+        return null;
+    const byId = payload.nodes.find((node) => node.id === needle);
+    if (byId)
+        return byId;
+    const lower = needle.trim().toLowerCase();
+    // Every caption `.includes("")`, so a blank selector would match the first
+    // node and the tool would report a confident, arbitrary selection. A missing
+    // argument has to fail, not pick.
+    if (lower.length === 0)
+        return null;
+    // The SAME resolver the canvas paints with. A local approximation of it
+    // (caption / name / title) left every other way a node gets its caption —
+    // a producer's `legend.captionKey`, `displayName`, `label`, the first short
+    // string property — visible on screen and unselectable by the text on it.
+    const captionOf = (node) => resolveCaption(node, payload.legend?.[primaryLabel(node)]?.captionKey).toLowerCase();
+    // Duplicate captions are ordinary in a real graph — two people with the
+    // same name, two films with the same title — and `find` answered those with
+    // whichever the producer happened to return first. The tool then reported a
+    // confident selection and the agent described the wrong node, with nothing
+    // on screen to show it had guessed. An exact match on ONE node is an answer;
+    // more than one is a question for the caller, who has the ids.
+    const exact = payload.nodes.filter((node) => captionOf(node) === lower);
+    if (exact.length === 1)
+        return exact[0] ?? null;
+    if (exact.length > 1)
+        return { ambiguous: exact };
+    const partial = payload.nodes.filter((node) => captionOf(node).includes(lower));
+    if (partial.length === 1)
+        return partial[0] ?? null;
+    if (partial.length > 1)
+        return { ambiguous: partial };
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@iloveagents/foundry-web-graph` — the source-agnostic graph visualizer.
+ *
+ * Nothing exported from here knows about Neo4j, assistant-ui, or the chat
+ * shell. The Neo4j mapping is `@iloveagents/foundry-web-graph/adapters/neo4j`;
+ * the chat card and panel renderer are
+ * `@iloveagents/foundry-web-graph/assistant-ui`.
+ */
+export { GRAPH_PAYLOAD_KIND, GRAPH_PAYLOAD_VERSION, DEFAULT_CAPTION_KEYS, coerceGraphPayload, emptyGraphPayload, isGraphPayload, mergeGraphPayloads, primaryLabel, pruneDanglingEdges, resolveCaption, type GraphEdge, type GraphNode, type GraphPayload, } from "./model.js";
+export { GraphView, type GraphViewHandle, type GraphViewProps } from "./graph-view.js";
+export { GraphLegend, type GraphLegendProps } from "./graph-legend.js";
+export { GraphInspector, type GraphInspectorProps } from "./graph-inspector.js";
+export { GraphToolbar, type GraphToolbarProps } from "./graph-toolbar.js";
+export { GraphTable, type GraphTableProps } from "./graph-table.js";
+export { GraphEmptyState, GraphLossNotice } from "./graph-notice.js";
+export { DEFAULT_LIMITS, reconcileGraphModel, selectConnectedCore, useGraphModel, type EngineLink, type EngineNode, type GraphModel, type GraphModelLimits, type GraphModelLoss, } from "./use-graph-model.js";
+export { useGraphStyling, type GraphStyleMap, type GraphStyling, type NodeStyle, } from "./use-graph-styling.js";
+export { useGraphViewState, type GraphSelection, type GraphViewState, } from "./use-graph-view-state.js";
+export { useGraphTheme } from "./use-graph-theme.js";
+export { FALLBACK_THEME, resolveGraphTheme, type GraphTheme } from "./theme.js";
+export { findWorkspaceNode, graphWorkspaceStore, isGraphOpen, type GraphWorkspaceState, } from "./graph-workspace.js";

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@iloveagents/foundry-web-graph` — the source-agnostic graph visualizer.
+ *
+ * Nothing exported from here knows about Neo4j, assistant-ui, or the chat
+ * shell. The Neo4j mapping is `@iloveagents/foundry-web-graph/adapters/neo4j`;
+ * the chat card and panel renderer are
+ * `@iloveagents/foundry-web-graph/assistant-ui`.
+ */
+export { GRAPH_PAYLOAD_KIND, GRAPH_PAYLOAD_VERSION, DEFAULT_CAPTION_KEYS, coerceGraphPayload, emptyGraphPayload, isGraphPayload, mergeGraphPayloads, primaryLabel, pruneDanglingEdges, resolveCaption, } from "./model.js";
+export { GraphView } from "./graph-view.js";
+export { GraphLegend } from "./graph-legend.js";
+export { GraphInspector } from "./graph-inspector.js";
+export { GraphToolbar } from "./graph-toolbar.js";
+export { GraphTable } from "./graph-table.js";
+export { GraphEmptyState, GraphLossNotice } from "./graph-notice.js";
+export { DEFAULT_LIMITS, reconcileGraphModel, selectConnectedCore, useGraphModel, } from "./use-graph-model.js";
+export { useGraphStyling, } from "./use-graph-styling.js";
+export { useGraphViewState, } from "./use-graph-view-state.js";
+export { useGraphTheme } from "./use-graph-theme.js";
+export { FALLBACK_THEME, resolveGraphTheme } from "./theme.js";
+export { findWorkspaceNode, graphWorkspaceStore, isGraphOpen, } from "./graph-workspace.js";