@iloveagents/foundry-web-graph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iLoveAgents, a brand of Leitwolf GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @iloveagents/foundry-web-graph
+
+Interactive graph visualization for [Foundry UI](https://github.com/iLoveAgents/foundry-ui).
+
+A force-directed graph view with the interactions people expect from a graph
+explorer — colour and caption by type, a filtering legend, hover, select,
+expand, search, pin, zoom-to-fit — plus an optional assistant-ui tool card and
+side-panel renderer so an agent can put a graph in front of the user.
+
+**Source-neutral by construction.** The root export takes a plain payload and
+knows nothing about where the data came from. Neo4j is one adapter, in its own
+entry point; the chat integration is in another. Import only what you use.
+
+```bash
+pnpm add @iloveagents/foundry-web-graph
+```
+
+### Tailwind v4 hosts: point Tailwind at this package
+
+`styles.css` carries the `--graph-1..8` palette and the rules Tailwind cannot
+express — it is **not** the component styling. `GraphView` is built from
+utility classes, and Tailwind v4 does not scan `node_modules`, so without a
+`@source` directive the graph renders with no spacing, borders or typography:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@iloveagents/foundry-web-graph/dist";
+
+@import "@iloveagents/foundry-web-graph/styles.css";
+```
+
+(Adjust the relative path to your stylesheet\'s location. Apps scaffolded by
+`create-foundry-ui-app --preset neo4j` already have this.)
+
+## Drawing a graph
+
+```tsx
+import { GraphView } from "@iloveagents/foundry-web-graph";
+import "@iloveagents/foundry-web-graph/styles.css";
+
+const data = {
+  kind: "foundry.graph",
+  version: 1,
+  nodes: [
+    { id: "1", labels: ["Person"], properties: { name: "Ada" } },
+    { id: "2", labels: ["Project"], properties: { name: "Analytical Engine" } },
+  ],
+  edges: [{ id: "e1", source: "1", target: "2", type: "WORKED_ON" }],
+} as const;
+
+<GraphView data={data} height={480} onExpandNode={(node) => loadNeighbours(node.id)} />;
+```
+
+`onExpandNode` is a callback: the view never issues a query of its own. Feed a
+larger payload back through `data` and the layout keeps the positions of nodes
+that were already there.
+
+Colours come from your app's design tokens, so light and dark mode work without
+configuration. The stylesheet is optional — without it the graph falls back to
+the host's `--chart-*` tokens, and then to a built-in palette.
+
+## In a chat
+
+```tsx
+import { defineChatModule } from "@iloveagents/foundry-web-shell";
+import {
+  makeGraphToolUI,
+  registerGraphPanelRenderer,
+} from "@iloveagents/foundry-web-graph/assistant-ui";
+
+const CypherToolUI = makeGraphToolUI({ toolName: "graph_read_cypher" });
+
+export const graphModule = defineChatModule({
+  name: "graph",
+  useInit: registerGraphPanelRenderer,
+  toolUIs: <CypherToolUI />,
+});
+```
+
+`makeGraphToolUI` is a factory because assistant-ui binds a literal tool name at
+construction — so the card works for any tool that returns the payload, whatever
+it is called. A result that is not graph-shaped degrades to an ordinary tool
+card rather than throwing.
+
+`registerGraphPanelRenderer()` teaches the tool panel to render
+`type: "graph"` content, which is what the card's **Open in panel** action
+produces. It is idempotent.
+
+## Letting the agent work in the graph
+
+The panel can be a workspace the agent and the user share rather than a picture
+the agent hands over. `registerGraphClientTools()` adds four browser-executed
+tools:
+
+| Tool                | What the agent can do                                                                                          |
+| ------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `graph_get_view`    | Read what is on screen: counts, types, the selected node, the active search                                    |
+| `graph_show`        | Put a new graph in the panel — positions of nodes already there are kept, so a refined query reads as a change |
+| `graph_select_node` | Select and centre a node, by id or by caption                                                                  |
+| `graph_search`      | Highlight matches and dim the rest                                                                             |
+
+```tsx
+import {
+  registerGraphClientTools,
+  registerGraphPanelRenderer,
+} from "@iloveagents/foundry-web-graph/assistant-ui";
+
+export const graphModule = defineChatModule({
+  name: "graph",
+  useInit: () => {
+    registerGraphPanelRenderer();
+    registerGraphClientTools();
+  },
+  toolUIs: <CypherToolUI />,
+});
+```
+
+The user's own clicks land in the same state, so "tell me about this node"
+works without either side restating which node. Read `graphWorkspaceStore`
+directly if you want to build your own UI on top of it.
+
+## From Neo4j
+
+```ts
+import { graphFromNeo4j } from "@iloveagents/foundry-web-graph/adapters/neo4j";
+
+const payload = graphFromNeo4j(records);
+```
+
+Structurally typed — it does not import `neo4j-driver`, so a visualization
+package never drags a database client into your bundle. It walks arbitrary
+result rows and collects anything node- or relationship-shaped, so `RETURN *`
+works as well as a careful projection.
+
+Most apps will not need this: a backend that emits the payload directly is the
+better arrangement. See the `neo4j` starter — `npm create foundry-ui-app my-app -- --preset neo4j`.
+
+## The payload
+
+```ts
+interface GraphPayload {
+  kind: "foundry.graph";
+  version: 1;
+  nodes: {
+    id: string;
+    labels?: string[];
+    caption?: string;
+    properties?: Record<string, unknown>;
+  }[];
+  edges: {
+    id: string;
+    source: string;
+    target: string;
+    type?: string;
+    properties?: Record<string, unknown>;
+  }[];
+  truncated?: boolean;
+  stats?: { nodeCount?: number; edgeCount?: number };
+  legend?: Record<string, { color?: string; captionKey?: string }>;
+}
+```
+
+`kind` and `version` are what let a tool card look at an arbitrary result and
+decide whether to render it. `isGraphPayload` checks both strictly;
+`coerceGraphPayload` is the tolerant version that also accepts a JSON string or
+a `{ graph: … }` envelope.
+
+A payload must never carry a top-level `error` key — the AG-UI runner treats
+that as a failed tool call. Report partial results with `truncated`. The type
+declares `error?: never` so this fails at compile time rather than in a demo.
+
+## Large graphs
+
+`GraphView` caps what it draws (1,500 nodes / 3,000 relationships by default,
+via `limits`). When a payload overflows it keeps the **connected core** — seeded
+at the best-connected node and expanded through its neighbours — rather than an
+arbitrary prefix, and reports what was withheld. Taking the first N instead
+produces a screen of unconnected dots, which reads as "there is nothing here"
+rather than "there is too much here".
+
+The canvas is not readable by assistive technology, so the same graph is always
+available as a table (`GraphTable`, or `forceTable` on `GraphView`).
+
+## Peer dependencies
+
+`react`, `react-dom` and `lucide-react` are required. `@assistant-ui/react` is
+optional and only needed for the `/assistant-ui` entry point.
+
+## License
+
+MIT

package/dist/adapters/index.d.ts

@@ -0,0 +1 @@
+export { graphFromNeo4j, isNeo4jNode, isNeo4jRelationship, toGraphEdge, toGraphNode, type Neo4jNodeLike, type Neo4jRelationshipLike, } from "./neo4j.js";

package/dist/adapters/index.js

@@ -0,0 +1 @@
+export { graphFromNeo4j, isNeo4jNode, isNeo4jRelationship, toGraphEdge, toGraphNode, } from "./neo4j.js";

package/dist/adapters/neo4j.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Neo4j → {@link GraphPayload}.
+ *
+ * The ONLY module in this package that knows Neo4j exists. Everything under
+ * `src/` outside `adapters/` stays store-agnostic; `src/__tests__/no-store-leak.test.ts`
+ * enforces that, so the visualizer keeps working for callers who have never
+ * heard of Cypher.
+ *
+ * This mirrors the server-side mapping the `neo4j-aura` starter preset does in
+ * `agent/app/graph_payload.py`. Most apps will not need it — their backend
+ * already emits the payload. It exists for the ones that query Neo4j straight
+ * from the browser (an HTTP Query API call, a fixture, a test).
+ */
+import { type GraphEdge, type GraphNode, type GraphPayload } from "../model.js";
+/**
+ * Structural shape of a driver node. Deliberately NOT the driver's own type —
+ * importing `neo4j-driver` for a type would put a store client in the
+ * dependency tree of a visualization package. Anything with these fields
+ * works, including the plain JSON the HTTP Query API returns.
+ */
+export interface Neo4jNodeLike {
+    elementId?: string;
+    identity?: unknown;
+    labels?: string[];
+    properties?: Record<string, unknown>;
+}
+export interface Neo4jRelationshipLike {
+    elementId?: string;
+    identity?: unknown;
+    type?: string;
+    start?: unknown;
+    end?: unknown;
+    startNodeElementId?: string;
+    endNodeElementId?: string;
+    properties?: Record<string, unknown>;
+}
+export declare const isNeo4jNode: (value: unknown) => value is Neo4jNodeLike;
+export declare const isNeo4jRelationship: (value: unknown) => value is Neo4jRelationshipLike;
+export declare function toGraphNode(node: Neo4jNodeLike): GraphNode | null;
+export declare function toGraphEdge(rel: Neo4jRelationshipLike): GraphEdge | null;
+/**
+ * Walk arbitrary Cypher result rows and collect every node and relationship,
+ * however deeply nested.
+ *
+ * A row is whatever the query returned: bare entities, a path object, a list
+ * from `collect()`, a map from a projection. Rather than enumerate those
+ * shapes, this recurses and picks out anything that looks like an entity —
+ * which is what makes `RETURN *` work as well as a careful projection.
+ *
+ * Duplicates collapse by id: the same node returned on ten rows is one node.
+ */
+export declare function graphFromNeo4j(rows: unknown): GraphPayload;

package/dist/adapters/neo4j.js

@@ -0,0 +1,149 @@
+/**
+ * Neo4j → {@link GraphPayload}.
+ *
+ * The ONLY module in this package that knows Neo4j exists. Everything under
+ * `src/` outside `adapters/` stays store-agnostic; `src/__tests__/no-store-leak.test.ts`
+ * enforces that, so the visualizer keeps working for callers who have never
+ * heard of Cypher.
+ *
+ * This mirrors the server-side mapping the `neo4j-aura` starter preset does in
+ * `agent/app/graph_payload.py`. Most apps will not need it — their backend
+ * already emits the payload. It exists for the ones that query Neo4j straight
+ * from the browser (an HTTP Query API call, a fixture, a test).
+ */
+import { GRAPH_PAYLOAD_KIND, GRAPH_PAYLOAD_VERSION, } from "../model.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Normalize an id. The driver hands back `elementId` (a string) on modern
+ * versions and `identity` (an Integer object, or a bigint) on older ones;
+ * JSON round-trips turn the latter into `{low, high}`. All of them have to
+ * collapse to the same string, or edges stop matching their nodes.
+ */
+function toId(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (typeof value === "bigint")
+        return String(value);
+    // A `number` only when it can still BE the id. Past 2**53-1 a double has
+    // already lost the low bits — by the time this runs the rounding has
+    // happened, so `String(value)` faithfully stringifies the wrong number and
+    // two distinct ids collapse to one key. Same consequence as the `low`-only
+    // bug below: it does not fail, it points edges at the wrong nodes. A caller
+    // holding larger ids has exact forms available — a string, a bigint, an
+    // `elementId`, or `{low, high}`.
+    if (typeof value === "number")
+        return Number.isSafeInteger(value) ? String(value) : null;
+    if (isRecord(value)) {
+        // An elementId is exact; prefer it whenever the record carries one.
+        if (typeof value.elementId === "string" && value.elementId.length > 0) {
+            return value.elementId;
+        }
+        if (typeof value.low === "number") {
+            // A Neo4j Integer is a 64-bit value split across two 32-bit words, and
+            // `low` alone is only the bottom half. Dropping `high` makes every id
+            // past 2^32 collide with one below it — and a collision here does not
+            // fail, it silently points edges at the wrong nodes. BigInt, because
+            // the whole point is values a double cannot hold exactly.
+            const low = BigInt(value.low >>> 0);
+            const high = typeof value.high === "number" ? BigInt(value.high) : 0n;
+            return String((high << 32n) + low);
+        }
+    }
+    return null;
+}
+export const isNeo4jNode = (value) => isRecord(value) &&
+    Array.isArray(value.labels) &&
+    toId(value.elementId ?? value.identity) !== null;
+export const isNeo4jRelationship = (value) => isRecord(value) &&
+    typeof value.type === "string" &&
+    toId(value.elementId ?? value.identity) !== null &&
+    toId(value.startNodeElementId ?? value.start) !== null &&
+    toId(value.endNodeElementId ?? value.end) !== null;
+export function toGraphNode(node) {
+    const id = toId(node.elementId ?? node.identity);
+    if (id === null)
+        return null;
+    return {
+        id,
+        labels: node.labels ?? [],
+        properties: node.properties ?? {},
+    };
+}
+export function toGraphEdge(rel) {
+    const id = toId(rel.elementId ?? rel.identity);
+    const source = toId(rel.startNodeElementId ?? rel.start);
+    const target = toId(rel.endNodeElementId ?? rel.end);
+    if (id === null || source === null || target === null)
+        return null;
+    return {
+        id,
+        source,
+        target,
+        type: rel.type,
+        properties: rel.properties ?? {},
+    };
+}
+/**
+ * Walk arbitrary Cypher result rows and collect every node and relationship,
+ * however deeply nested.
+ *
+ * A row is whatever the query returned: bare entities, a path object, a list
+ * from `collect()`, a map from a projection. Rather than enumerate those
+ * shapes, this recurses and picks out anything that looks like an entity —
+ * which is what makes `RETURN *` work as well as a careful projection.
+ *
+ * Duplicates collapse by id: the same node returned on ten rows is one node.
+ */
+export function graphFromNeo4j(rows) {
+    const nodes = new Map();
+    const edges = new Map();
+    const seen = new Set();
+    const visit = (value, depth) => {
+        if (value === null || value === undefined || depth > 12)
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, depth + 1);
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        // Cycle guard: paths reference their own segments' nodes.
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        if (isNeo4jNode(value)) {
+            const node = toGraphNode(value);
+            if (node)
+                nodes.set(node.id, node);
+            return;
+        }
+        if (isNeo4jRelationship(value)) {
+            const edge = toGraphEdge(value);
+            if (edge) {
+                edges.set(edge.id, edge);
+                // `MATCH ()-[r]->() RETURN r` is an ordinary query, and the driver
+                // gives back relationships with no node objects at all. Without a
+                // placeholder for each end, every edge dangles, `pruneDanglingEdges`
+                // drops the lot, and a perfectly good result renders as an empty
+                // graph. `setdefault` semantics: a real node visited later — in the
+                // same result or a merge — overwrites the stub and brings its labels
+                // and properties with it.
+                if (!nodes.has(edge.source))
+                    nodes.set(edge.source, { id: edge.source });
+                if (!nodes.has(edge.target))
+                    nodes.set(edge.target, { id: edge.target });
+            }
+            return;
+        }
+        for (const nested of Object.values(value))
+            visit(nested, depth + 1);
+    };
+    visit(rows, 0);
+    return {
+        kind: GRAPH_PAYLOAD_KIND,
+        version: GRAPH_PAYLOAD_VERSION,
+        nodes: [...nodes.values()],
+        edges: [...edges.values()],
+    };
+}

package/dist/assistant-ui/graph-client-tools.d.ts

@@ -0,0 +1,11 @@
+import { type ClientToolEntry } from "@iloveagents/foundry-agent";
+export declare const GRAPH_CLIENT_TOOLS: ClientToolEntry[];
+/**
+ * Register the graph client tools globally.
+ *
+ * Global rather than page-scoped: the panel is available from every route, so
+ * scoping them to one page would make the agent's ability to drive the graph
+ * depend on where the user happens to be standing. Re-registering by the same
+ * name replaces the entry, so this is safe to call from a `useInit`.
+ */
+export declare function registerGraphClientTools(): void;