XenolithGraph

An embeddable, drop-in node-graph editor for the web with a polished design system inside the package — typed Blueprint pins, live templates, macros, in-node widgets, a plugin host — and a swappable theme architecture that replaces the renderer's material entirely, not just its palette.

Status: v0.7 BETA. The public API documented in STABLE-API.md is the surface we plan to freeze, but it is NOT frozen yet — breaking changes can land at any point before v1.0. If you adopt now, pin an exact version. Initial touch / mobile support landed (pinch, two-finger pan, long-press menu, drawer chrome) but a few polish items remain. See Roadmap below.

<p align="center"><a href="https://graph.xenolith.studio/playground/" target="_blank" rel="noopener noreferrer"><img alt="Try it live" src="https://img.shields.io/badge/%E2%96%B6%20Try%20it%20live%20%E2%80%94%20open%20the%20playground-FCB400?style=for-the-badge&labelColor=0A0A0A" /></a> <a href="https://graph.xenolith.studio/examples/" target="_blank" rel="noopener noreferrer"><img alt="Examples gallery" src="https://img.shields.io/badge/Examples%20gallery%20%E2%86%92-1d1d1d?style=for-the-badge" /></a></p> <p align="center"> <a href="https://graph.xenolith.studio/playground/?demo=agent" target="_blank" rel="noopener noreferrer"> <img src="docs/screenshots/agent-demo.gif" alt="An agent session builds a 14-node telemetry-anomaly pipeline through the MCP tool surface, runs it with per-node timing, and verifies its own output" width="86%" /> </a> </p>

Agents build. Humans debug. The capture above is a scripted session driving the editor through the exact MCP tool surface Claude Desktop or Cursor gets — list_node_types → add_node ×14 → connect_pins ×17 → auto_layout → set_category_palette — then it executes the graph for real (step-by-step, per-node timing) and verifies its own output (anomalies=2 ✓). Every agent edit rides the same command bus as a human edit, so Ctrl+Z just works. Run it live: playground/?demo=agent.

<p align="center"> <a href="https://graph.xenolith.studio/playground/?demo=agent&mode=propose" target="_blank" rel="noopener noreferrer"> <img src="docs/screenshots/agent-propose.gif" alt="Propose mode: the agent's 33 operations queue as proposals, a human reviews them in the approval panel and approves the batch — the whole agent build lands as ONE undo step" width="86%" /> </a> </p>

Agents propose. Humans approve. Connect with mode: 'propose' and every mutating tool call ENQUEUES instead of applying — a badge surfaces the waiting batch, the review panel lists each operation (tool, args digest, predicted effect, client identity), and Approve all lands the whole batch as ONE atomic, undoable transaction. Reject discards. Provisional node ids let the agent chain operations inside a batch; approval re-resolves everything against the current graph (ADR 0007). Run it live: playground/?demo=agent&mode=propose.

<p><a href="https://graph.xenolith.studio/playground/?theme=xen" target="_blank" rel="noopener noreferrer"><img src="docs/screenshots/xen.png" alt="Xen — default dark/gold theme (click to open the live playground)" width="32%" /></a> <a href="https://graph.xenolith.studio/playground/?theme=daylight" target="_blank" rel="noopener noreferrer"><img src="docs/screenshots/daylight.png" alt="Daylight — original light-mode theme (click to open the live playground)" width="32%" /></a> <a href="https://graph.xenolith.studio/playground/?theme=liquid-glass" target="_blank" rel="noopener noreferrer"><img src="docs/screenshots/liquid-glass.png" alt="Liquid Glass — shader-based frosted theme (click to open the live playground)" width="32%" /></a></p>

What it does

Vanilla / any framework:

import { XenolithEditor } from '@xenolithengine/graph-editor'

const editor = await XenolithEditor.init('#app')
editor.loadJSON(graphDoc)
editor.fitView()

React:

import { XenolithGraph } from '@xenolithengine/graph-react'

<XenolithGraph
  graph={graphDoc}
  fitOnLoad
  onReady={(editor) => editor.registry.register(MyNodeSchema)}
/>

Vue 3:

<script setup lang="ts">
import { XenolithGraph } from '@xenolithengine/graph-vue'
function onReady(editor) { editor.registry.register(MyNodeSchema) }
</script>
<template>
  <XenolithGraph :graph="graphDoc" fit-on-load @ready="onReady" />
</template>

One call (or one component) boots: fonts, PIXI v8 renderer, viewport, grid, pan/zoom, marquee, multi-drag with snap, connect-pins-by-drag, Alt+drag rewire, two reroute kinds, comments, collapsed macros, live templates with dive-in editing, in-node widgets, K2-style Tab palette, properties sidebar, undo/redo, JSON serialize with schema migrations, minimap, drag-and-drop palette sidebar. Headless @xenolithengine/graph-core is zero-dependency.

Highlights

• Blueprint-first. Typed pins (exec vs data), per-type colour and shape (circle / arrow / diamond), registerable type conversions (editor.types.registerConversion('number', 'text', String)). Exec pins hoist onto the node header line (UE-Blueprint layout). Header glyphs from a Feather icon set or your own SVG.
• Live templates + macros. Reusable subgraphs with one shared definition + many instances; double-click to dive in, a breadcrumb tracks the path (Root › Pipeline › Stage). One-off inline grouping via macros — convert macro ↔ template either direction. unpackTemplateInstance() inlines a copy.
• Comments. Drag a coloured rectangle behind nodes; spatial group-drag moves everything inside it. Tab → "Comment" or context menu.
• In-node widgets. Declarative number / slider / combo / text / toggle / color / button, plus custom canvas-draw or DOM-mount widgets (reactWidget, vueWidget, svelteWidget via registerWidget(name, controller)). Conditional visibility on widget state (displayOptions.show), free-floating widgets (freeFloating: true), live values on display widgets, properties sidebar. Solid and Angular have no widget bridge — use canvas widgets or editor.chrome.
• Named commands + hotkeys. Register actions through editor.commands with typed Commands.Undo/Commands.Redo/… constants; cross-platform hotkey grammar (Mod+Z resolves to Cmd on macOS, Ctrl elsewhere). Built-in shortcuts are overridable.
• Events + history. Listen with editor.on(event, fn) — including cancellable variants (edge:connecting, edge:disconnecting, node:removing, node:clicking with a cancel() closure). Group many mutations into one undo entry via editor.transaction(fn) (or beginGroup({ idleTimeoutMs }) / endGroup() for keystroke coalescing).
• Save · restore · migrate · export. Versioned xenolith.v1 JSON (ID-sorted for clean git diffs) with per-schema migrate(oldNode, fromVersion) hooks — old graphs upgrade automatically. ComfyUI workflow importer. Export the whole graph (not the viewport) to PNG or JPEG at any resolution.
• Auto-layout plugin. @xenolithengine/graph-plugin-autolayout with Dagre and ELK adapters. One call arranges any graph; animated tweens included; bypasses the command bus per-frame and commits the final positions as one undo entry.
• Pluggable edge paths. Per-edge style: bezier (default), smoothstep, step, linear. Labels, arrowheads, animated marching dashes.
• Plugin host. editor.use(plugin) with a PluginContext that exposes schema/types/icons/widgets, an event bus, and runtime-delegation surfaces (onTick, startLoop/stopLoop/step, setNodePins, setWidgetValue({ephemeral}), setNodePositionEphemeral, expandTemplateInstance, graphSnapshot, setEdgeAnimated).
• Three themes shipped. Xen (dark/gold, original design system), Daylight (light-mode, protruding pin halos, Helvetica typography), and Liquid Glass (shader-based refraction + rim lighting via PIXI Mesh+Shader). Swap at runtime with editor.setTheme(theme).
• Live Mode. editor.setLiveMode(true) hides editor chrome (palette, breadcrumb, controls) — perfect for read-only previews and demos.
• Perf for real graphs. Viewport virtualization + 3-tier LOD (full → sprite-baked → flat-batch). Render-on-demand (static graphs idle at 0 fps cost). BitmapText glyph atlas for node/widget text. Shared GPU texture caches.
• Framework adapters. Six packages, each with a Learn page. React and Vue 3 ship panel components (XenolithPanel, Controls, MiniMap, Button, ProposalQueue), a hook/composable set including the controlled triple useNodesState(), and reactWidget / vueWidget. Svelte ships a use:xenolith action and createXenolithStores() (including nodesState()); panel components and svelteWidget live on the @xenolithengine/graph-svelte/components subpath and need Svelte 5, while the package root stays pure TypeScript and runs on Svelte 4. Solid ships a use:xenolith directive and createXenolithStores() / nodesState() — panels and a widget bridge are absent there, use editor.chrome. Angular ships a decorator-free XenolithGraphService (RxJS, including nodesState()); there is no library component, because an AOT consumer cannot compile a raw decorator class. Web Components (<xenolith-graph>) ship the attribute dictionary and all 25 editor events plus ready; reactive stores belong to the host framework, which receives the editor on ready.
• AI-native via MCP. Ships its own Model Context Protocol server (@xenolithengine/graph-mcp-server). Start the CLI, click Connect in the editor, and Claude Desktop / Cursor can build graphs directly — list_node_types → add_node → connect_pins → auto_layout. Twenty-six tools + three resources (graph://current, schema://types, audit://recent). Every mutation flows through the command bus so undo and the live event stream just work. Token-auth + read-only mode supported. Propose mode (connectMCP(url, { mode: 'propose' })) is the trust boundary: agent edits queue for human approval in the built-in review panel and land as one undo step.
• Visual stepping debugger. StepDebugger is part of @xenolithengine/graph-editor — wrap any executor (StepExecutor), and you get pause/step/continue, breakpoints, per-node timing, and a live trace. The Step debugger / Time-travel scrubber / Per-node cost heatmap / Grap