# XenolithGraph

> Open-source embeddable node-graph editor for the web. WebGL (PIXI v8) rendering, opinionated design system (Xen + Liquid Glass), typed pins, in-node widgets, custom widget controllers, framework adapters (React / Vue / Svelte / Solid / Angular / vanilla web-component), and an MCP server so AI agents can build graphs over a localhost bridge.

It is NOT a generic flowchart library — Blueprint-style semantics (typed pins, exec vs data, type-color system, K2-style search palette) are first-class. Targets: AI/LLM workflow builders, audio/DSP editors, shader graphs, gameplay logic, anyone who wants a node UI that looks like a tool.

## Guides
- [Install](https://xenolithengine.github.io/xenolith-graph/guides/install.md)
- [Initialize an editor](https://xenolithengine.github.io/xenolith-graph/guides/init.md)
- [Public API reference](https://xenolithengine.github.io/xenolith-graph/guides/api.md)
- [React adapter (@xenolithengine/graph-react — hooks, panels, custom widgets)](https://xenolithengine.github.io/xenolith-graph/guides/react.md)
- [Vue 3 adapter (@xenolithengine/graph-vue — composables, panels, custom widgets)](https://xenolithengine.github.io/xenolith-graph/guides/vue.md)
- [In-node widgets](https://xenolithengine.github.io/xenolith-graph/guides/widgets.md)
- [Macros & templates (grouping)](https://xenolithengine.github.io/xenolith-graph/guides/macros-templates.md)
- [Theming (Xen + Liquid Glass + tokens)](https://xenolithengine.github.io/xenolith-graph/guides/theme.md)
- [Save & export (JSON / PNG / JPG)](https://xenolithengine.github.io/xenolith-graph/guides/save-export.md)
- [Events & commands](https://xenolithengine.github.io/xenolith-graph/guides/events-commands.md)
- [Header icons (Feather set + register your own)](https://xenolithengine.github.io/xenolith-graph/guides/icons.md)
- [Plugins](https://xenolithengine.github.io/xenolith-graph/guides/plugins.md)

## Framework integrations
- [AI agents (MCP, OpenAPI, LangChain) — start here for the AI story](https://xenolithengine.github.io/xenolith-graph/integrations/ai-agents/)
- [Next.js (App Router + Pages)](https://xenolithengine.github.io/xenolith-graph/integrations/nextjs/)
- [SvelteKit](https://xenolithengine.github.io/xenolith-graph/integrations/sveltekit/)
- [Remix](https://xenolithengine.github.io/xenolith-graph/integrations/remix/)

## AI integration (MCP)
- [MCP server README — connect Claude Desktop / Cursor to a live editor](https://github.com/XenolithEngine/xenolith-graph/blob/main/packages/mcp-server/README.md)
- [MCP tool catalogue (JSON Schema)](https://xenolithengine.github.io/xenolith-graph/api/mcp-tools.json)
- [Live demo: "AI builds the graph"](https://xenolithengine.github.io/xenolith-graph/examples/mcp-live/)

## Examples
### Showcases
- [MCP live (AI builds the graph)](https://xenolithengine.github.io/xenolith-graph/examples/mcp-live/) — Start @xenolithengine/graph-mcp-server locally, click Connect, then ask Claude Desktop / Cursor to build a graph. The AI calls list_node_types → add_node → connect_pins → auto_layout. "I describe it, the editor builds it."
- [Visual stepping debugger](https://xenolithengine.github.io/xenolith-graph/examples/step-debugger/) — Run a graph one node at a time. Yellow ring = paused; green = executed; red = breakpoint. The inspector shows live inputs/outputs and per-node timing. Debug your AI workflow on the canvas — like Chrome DevTools, but for nodes.
- [Time-travel scrubber](https://xenolithengine.github.io/xenolith-graph/examples/time-travel/) — Rewind a graph run. Drag the timeline through every step and watch the highlights replay — green = done, yellow = the step under inspection. The inspector shows that step’s inputs and outputs.
- [Graph diff (PR review)](https://xenolithengine.github.io/xenolith-graph/examples/graph-diff/) — Two versions of a graph side by side, with structural diff highlights — green = added, red = removed, yellow = modified. Drop-in PR-review for node graphs.
- [Per-node cost heatmap](https://xenolithengine.github.io/xenolith-graph/examples/heatmap/) — A RAG pipeline with per-node latency badges — cool blue → hot red. Press Pulse to see metrics breathe. Drop-in observability overlay; no OSS competitor ships it.
- [LLM workflow builder](https://xenolithengine.github.io/xenolith-graph/examples/llm-builder/) — Input → Prompt → Model → Output. Press Run; the chain walks in topological order, the active node glows, the completion streams into the Output. A prettier LangFlow, on Xenolith.
- [Audio synth (Web Audio)](https://xenolithengine.github.io/xenolith-graph/examples/audio-synth/) — A real synth built on the graph — Oscillator → Filter → Gain → Output. Knobs are node widgets; Play wires live AudioNodes and lights the active chain. It makes sound.
- [Save & restore](https://xenolithengine.github.io/xenolith-graph/examples/save-restore/) — The whole graph is JSON. Download / upload a .json file, and autosave to localStorage on every edit (driven by useGraphJSON). Reload the page — it comes back.
- [Image pipeline (WebGL)](https://xenolithengine.github.io/xenolith-graph/examples/image-pipeline/) — A real image-filter pipeline — Source → Exposure → Saturation → Hue → Blur → Vignette → Result. Each node is a live GLSL fragment pass. Drag a slider and the result re-renders; drop your own image; download the PNG.
- [Diagram edges](https://xenolithengine.github.io/xenolith-graph/examples/diagram/) — Edges as a diagramming primitive — text nodes wired with directional arrowhead markers, edge labels (pass / fail / retry), and an animated flowing dash on the main path. Toggle the flow.
- [Stress test (1000s of nodes)](https://xenolithengine.github.io/xenolith-graph/examples/stress-test/) — Generate hundreds → thousands of WebGL nodes wired into a chain. Live FPS + node-count overlay top-right; the panel counter is driven by the reactive `useNodes()` hook. Zoom floor dropped to 5% so 10k+ nodes fit on one screen.

### Nodes
- [Mount an editor](https://xenolithengine.github.io/xenolith-graph/examples/mount/) — The honest minimum: register a node type, add one, frame it. Xen is the default theme — no setup.
- [Load a graph](https://xenolithengine.github.io/xenolith-graph/examples/load/) — Load a real saved xenolith.v1 graph and reframe it. Built-in controls + a reload panel.

### Widgets
- [Built-in widgets](https://xenolithengine.github.io/xenolith-graph/examples/builtin-widgets/) — Every built-in widget — slider, number, toggle, combo, color, text — on one node, in WebGL.
- [Custom canvas widget](https://xenolithengine.github.io/xenolith-graph/examples/canvas-widget/) — The simplest custom widget: a click/drag level bar, drawn in WebGL — no DOM. The value flows back to your app via the standard widget callback.
- [Bring your own UI](https://xenolithengine.github.io/xenolith-graph/examples/custom-widgets/) — Four widgets that are real framework components (async-select, file drop, CodeMirror, sparkline), themed via --xeno-*.
- [Conditional widgets](https://xenolithengine.github.io/xenolith-graph/examples/conditional-widgets/) — Declarative `displayOptions.show(state)` — n8n-style. One HTTP Request node hides `body` until the method needs one, and `token` until auth is `bearer`. Pure schema: no `setNodeWidgets` plumbing in the host. The node re-layouts and edges stay attached as widgets appear and disappear.
- [Per-node canvas drawing](https://xenolithengine.github.io/xenolith-graph/examples/preview-nodes/) — Sparkline + ColorPreview nodes — each paints its own body via a CanvasWidgetController (the equivalent of LiteGraph onDrawForeground). The sparkline rolls a live plot of the upstream slider; the swatch fills from `node.state.tint`. Anything you can draw on a `<canvas>` can be a node body.

### Interaction
- [Events → your state](https://xenolithengine.github.io/xenolith-graph/examples/events/) — Typed event callbacks wired to app state: a live log, selection inspector, widget values.
- [Mobile / tablet (touch demo)](https://xenolithengine.github.io/xenolith-graph/examples/mobile-touch/) — Touch-first demo for testing pinch, two-finger pan, long-press context menu, and the drawer-mode palette on narrow viewports. Includes a fullscreen toggle. Open this URL on an iOS device or in the iOS Simulator — see docs/TESTING-ON-IOS-SIMULATOR.md.
- [Properties sidebar](https://xenolithengine.github.io/xenolith-graph/examples/properties-sidebar/) — A "fat" node with 8 widgets opts into the docked properties panel via the per-widget `showInSidebar: true` flag. Edit live — the same widget renders inline AND in the panel; no separate sidebar component to author. Themed via --xeno-*. Open programmatically: `editor.openSidebar(nodeId)`.
- [Two-way data binding](https://xenolithengine.github.io/xenolith-graph/examples/two-way/) — Both binding levels in one: `useSelection()` edits the selected node’s widgets; `useGraphJSON()` binds the whole graph ⇄ JSON. No manual event wiring.
- [Type conversions](https://xenolithengine.github.io/xenolith-graph/examples/type-conversions/) — Typed pins of different types refuse to connect — unless you register a conversion. NumberSource (out: number) won’t wire into TextSink (in: text) until `types.registerConversion("number", "text", String)` is called. Toggle the cast live; the existing edge drops when it disappears.
- [Subgraph breadcrumb](https://xenolithengine.github.io/xenolith-graph/examples/breadcrumb-dive/) — Nested template instances (Pipeline → Stage → primitives). Dive in by double-click OR programmatically; the breadcrumb in the top-left tracks the path (Root › Pipeline › Stage) and pops any segment. Auto-themed via --xeno-*. Opt-out with `editor.setBreadcrumbVisible(false)`.
- [Palette sidebar (drag to spawn)](https://xenolithengine.github.io/xenolith-graph/examples/palette-sidebar/) — 16 schemas across 5 categories (data / math / transform / logic / io) listed in a docked palette on the left. Drag any tile onto the canvas — the editor inserts the node at the drop point via its built-in `node:drop` handler. Configure with `editor.setPaletteSidebar({ side, filter })`.
- [Connection validation](https://xenolithengine.github.io/xenolith-graph/examples/connection-validation/) — Typed Blueprint pins refuse mismatched wires automatically (a string won’t plug into a number). A custom guard adds cycle prevention on top. Every attempt is logged live.
- [Export to image](https://xenolithengine.github.io/xenolith-graph/examples/export-image/) — Export the whole graph — not just the viewport — to a Blob at any scale. Download PNG, retina 2×, or JPG straight from a panel.

### Styling
- [Edge path styles](https://xenolithengine.github.io/xenolith-graph/examples/edge-paths/) — Per-edge `pathStyle`: bezier (default Xen S-curve), smoothstep (rounded orthogonal), step (90° elbows), linear (straight). Set on construction or live via `editor.setEdgeOptions(id, { pathStyle })`. Same wire colour / animated dash / arrowhead contract regardless of shape.
- [Theming](https://xenolithengine.github.io/xenolith-graph/examples/theming/) — Theme is a reactive prop — flip Xen ⇄ Liquid Glass at runtime; panels/widgets restyle via --xeno-*.

### Viewport
- [Viewport & minimap](https://xenolithengine.github.io/xenolith-graph/examples/viewport/) — Built-in controls (zoom/fit/reset/undo/redo/save/lock), toggleable minimap, live useNodes/useViewport readout.

### Layout
- [Nested auto-layout (ELK)](https://xenolithengine.github.io/xenolith-graph/examples/nested-layout/) — Three levels of nested macros — Encoder/Decoder containing Attention/FFN containing leaf ops. ELK respects the hierarchy (children stay inside their parent frame); dagre ignores parent and pancakes everything. Toggle to see the difference.
- [Auto-layout (dagre)](https://xenolithengine.github.io/xenolith-graph/examples/auto-layout/) — A messy 14-node DAG snaps into a clean layered layout. Toggle LR/TB; Cmd+Z restores the mess in a single undo step.

## Full content
- [llms-full.txt — every guide concatenated, plain text](https://xenolithengine.github.io/xenolith-graph/llms-full.txt)
- [agents.md — manifesto for AI agents (when to pick this library, conventions to respect)](https://xenolithengine.github.io/xenolith-graph/agents.md)

## Machine catalogs
- [api/mcp-tools.json — MCP tool catalog (24 tools, the full definition)](https://xenolithengine.github.io/xenolith-graph/api/mcp-tools.json)
- [api/openapi.json — same tools as OpenAPI 3.1 (LangChain / LlamaIndex / function-calling agents)](https://xenolithengine.github.io/xenolith-graph/api/openapi.json)
- [api/graphs.jsonl — every example as JSON Lines (one-shot gallery index)](https://xenolithengine.github.io/xenolith-graph/api/graphs.jsonl)
- [api/mcp-tools/<name>.md — per-tool deep card (one tool at a time, ~1 KB each)](https://xenolithengine.github.io/xenolith-graph/api/mcp-tools/list_node_types.md)
- [examples/<id>/llms.md — plain-text mirror of any example page](https://xenolithengine.github.io/xenolith-graph/examples/diagram/llms.md)
- [.well-known/ai.txt — AI usage policy](https://xenolithengine.github.io/xenolith-graph/.well-known/ai.txt)

## Repository
- [Source on GitHub](https://github.com/XenolithEngine/xenolith-graph)