@luispm/zflow-graph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis G.
+
+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,287 @@
+# @luispm/zflow-graph
+
+> WASM-powered node-edge graph editor + execution runtime. No framework. 100k nodes at 60 fps. Built-in multiplayer, WebGL, sub-flows.
+
+[![npm version](https://img.shields.io/npm/v/@luispm/zflow-graph.svg)](https://www.npmjs.com/package/@luispm/zflow-graph)
+[![license](https://img.shields.io/npm/l/@luispm/zflow-graph.svg)](LICENSE)
+
+Most graph libraries make you choose:
+
+- React Flow looks polished but can't pass ~5k nodes and depends on React
+- ComfyUI runs flows but isn't a library
+- Drawio is the size of a small OS
+- tldraw is great at sketches but doesn't know what a port is
+
+**@luispm/zflow-graph picks none of those tradeoffs.** It is a single self-contained ES module backed by a Zig→WASM core that ships in ~200 KB and runs in any browser tab, Electron, or Tauri-style desktop shell. It is an editor *and* a runtime.
+
+## Quick start
+
+```bash
+npm install @luispm/zflow-graph
+```
+
+```js
+import { ZFlow } from '@luispm/zflow-graph';
+
+const flow = await ZFlow.create({
+  container: document.getElementById('app'),
+  wasmUrl: '/node_modules/@luispm/zflow-graph/dist/zflow.wasm',
+});
+
+// Register a kind with an executable body.
+flow.registerKind({
+  name: 'double',
+  nin: 1, nout: 1,
+  portIn: ['value'], portOut: ['value'],
+  execute: (ctx, ins) => ({ value: ins.value * 2 }),
+});
+
+const a = flow.addNode({ kind: 'input',  x: -200, y: 0, title: '21' });
+const b = flow.addNode({ kind: 'double', x:    0, y: 0 });
+const c = flow.addNode({ kind: 'output', x:  200, y: 0, title: 'Result' });
+
+flow.addEdge({ from: a, to: b });
+flow.addEdge({ from: b, to: c });
+
+flow.setNodeInput(a, { value: 21 });
+await flow.run();             // → c.value === 42
+console.log(flow.getNodeValue(c));
+```
+
+## Why use it
+
+| Capability                              | @luispm/zflow-graph | React Flow | tldraw | Drawio |
+| --------------------------------------- | :---------: | :--------: | :----: | :----: |
+| WASM core (no framework)                |      ✅      |      ❌      |   ❌    |   ❌    |
+| 100k nodes @ 60 fps                     |      ✅      |      ❌      |   ⚠️   |   ❌    |
+| Built-in graph execution runtime         |      ✅      |      ❌      |   ❌    |   ❌    |
+| Real CRDT multiplayer (Yjs adapter)     |      ✅      |   ❌ (Pro)   |   ✅    |   ❌    |
+| WebGL renderer (instanced, opt-in)      |      ✅      |      ❌      |   ✅    |   ❌    |
+| Touch + pinch + pen                     |      ✅      |      ✅      |   ✅    |   ⚠️   |
+| Sub-flows reusable as kinds             |      ✅      |   ❌ (Pro)   |   ❌    |   ❌    |
+| Streaming async generator nodes         |      ✅      |      ❌      |   ❌    |   ❌    |
+| Inline expressions `{{node_X.value}}`   |      ✅      |      ❌      |   ❌    |   ❌    |
+| Schema type validation on edges         |      ✅      |      ✅      |   ❌    |   ❌    |
+| Plugin lifecycle hooks                  |      ✅      |   ⚠️ React   |   ❌    |   ✅    |
+| Mermaid + DOT import                    |      ✅      |      ❌      |   ❌    |   ✅    |
+| Critical-path / SCC / cycles            |      ✅      |      ❌      |   ❌    |   ❌    |
+| Bundle gz                               |    ~140 KB    |   180 KB   | 320 KB | 1.1 MB |
+| Framework dep                           |    None     |   React    | React  |  none  |
+
+## Architecture in 30 seconds
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Your app                                                │
+│    ├─ import { ZFlow } from '@luispm/zflow-graph'                │
+│    └─ flow.addNode(), flow.run(), flow.on(...)           │
+├─────────────────────────────────────────────────────────┤
+│  zflow.js (~180 KB ES module, no deps)                   │
+│    Canvas2D renderer ◄─ overlay text/UI ─┐               │
+│    WebGL renderer (opt-in, instanced) ◄──┘               │
+│    Runtime: topo, async, retry, memo, streaming, debug   │
+│    Plugin lifecycle · Yjs adapter · expression evaluator │
+├─────────────────────────────────────────────────────────┤
+│  zflow.wasm (~740 KB Zig WASM)                           │
+│    SoA storage · spatial grid · snapshot undo            │
+│    Sugiyama + force layouts · SCC + critical-path        │
+│    Zero-copy Float32/Uint32 views into linear memory     │
+└─────────────────────────────────────────────────────────┘
+```
+
+The JS holds typed-array **views** over WASM linear memory — there is no copy on read. The WASM never grows its memory after init, so views stay valid forever.
+
+## Concepts
+
+### Kinds
+A kind is the type of a node: its color, shape, ports, and optionally its executable body.
+
+```js
+flow.registerKind({
+  name: 'http-request',
+  color: '#5b8def', badge: 'H', w: 180, h: 70,
+  inputs:  [{ name: 'url',     type: 'string' }],
+  outputs: [{ name: 'body',    type: 'string' }],
+  retry:   { n: 3, delay: 500 },
+  execute: async (ctx, ins) => {
+    ctx.setProgress(0.3);
+    const res = await fetch(ins.url, { signal: ctx.signal });
+    return { body: await res.text() };
+  },
+});
+```
+
+### The runtime
+Calling `flow.run()` walks the graph in topological order, calling each node's `execute(ctx, inputs)`. Outputs flow through edges. The runtime supports:
+
+- **Async** — `execute` may return a `Promise`
+- **Streaming** — `execute` may return an `AsyncGenerator` that `yield`s multiple values
+- **Retry** — declarative `retry: { n, delay }`
+- **Memoization** — `flow.setMemoization(true)` skips nodes whose inputs hash matches the previous run
+- **Abort** — `flow.stop()` propagates an `AbortSignal` to every `ctx.signal`
+- **Breakpoints** — `flow.setBreakpoint(id)` pauses before exec; `flow.stepOver()` to advance
+
+### Multiplayer (Yjs)
+Real-time co-editing via [Yjs](https://github.com/yjs/yjs). The adapter is opt-in — `yjs` is **not** a runtime dependency unless you import the adapter.
+
+```js
+import { bindYjs } from '@luispm/zflow-graph/adapters/yjs';
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+
+const ydoc = new Y.Doc();
+const provider = new WebsocketProvider('wss://demos.yjs.dev/ws', 'my-room', ydoc);
+bindYjs(flow, ydoc, {
+  userName: 'Alice',
+  color: '#c062e8',
+  awareness: provider.awareness,
+});
+```
+
+Open two tabs of your app: nodes, edges, drags, and cursors sync at ~30 Hz.
+
+### Performance: opt-in WebGL
+For graphs beyond ~5k nodes, enable the WebGL renderer:
+
+```js
+await flow.enableWebGL();   // auto-enables past options.webglThreshold (default 2000)
+```
+
+The GL path uses `ANGLE_instanced_arrays` to paint every node body in a **single draw call**. Canvas2D continues to handle text, ports, badges, and UI on top. Pan/zoom is uniform-only — zero buffer uploads.
+
+### Sub-flows as kinds
+Wrap a group of nodes inside a frame, then turn that frame into a reusable kind:
+
+```js
+const frameId = flow.addFrame(0, 0, 400, 200, 'auth pipeline').id;
+// ... add nodes inside the frame ...
+const kindName = flow.registerSubflowFromFrame(frameId, { name: 'authPipe' });
+
+// Now you can instantiate the whole sub-flow as a single node anywhere:
+flow.addNode({ kind: 'authPipe', x: 600, y: 100 });
+```
+
+The library auto-detects inputs and outputs of the sub-flow based on which inner nodes lack inside-graph predecessors / successors.
+
+## API at a glance
+
+```js
+// Lifecycle
+const flow = await ZFlow.create({ container, wasmUrl });
+flow.dispose();
+
+// Mutation
+flow.addNode(spec) / addEdge(spec) / deleteSelection() / moveNode(id, x, y)
+flow.addNodesBulk(specs) / addEdgesBulk(specs)   // batch (50k nodes in ~50ms)
+
+// Selection
+flow.setSelected(id, on) / toggleSelected(id) / clearSelection() / selectAll()
+flow.getSelection()
+
+// Rich content
+flow.setNodeTitle / Description / Color / Tags / Status / Progress
+flow.setNodeImage / Checked / Tasks / Icon / Links
+
+// Runtime
+flow.registerKind({ name, execute, retry, inputs, outputs, ... })
+flow.run({ from?, filter?, signal? })
+flow.runFrom(nodeId) / runFrame(frameId)
+flow.stop() / startLoop(ms) / stopLoop()
+flow.setBreakpoint(id) / stepOver() / resume() / isPaused()
+flow.setNodeInput(id, value) / getNodeValue(id)
+flow.setNodeParams(id, params)     // for built-in kinds: const, if
+flow.evalExpression('{{node_3.value}} * 2')
+
+// Algorithms
+flow.shortestPath(from, to) / criticalPath() / findSCCs() / findCycles()
+
+// Serialization
+flow.toJSON() / loadJSON(data) / exportSVG() / exportPNG()
+
+// Imports
+flow.importMermaid(text) / importDot(text)
+
+// Layout
+flow.runAutoLayout() / runForceLayout() / fitView() / zoomTo() / panTo()
+
+// Plugins
+flow.use({ init, onNodeAdd, onBeforeExec, ... })
+
+// Multiplayer (separate import)
+import { bindYjs } from '@luispm/zflow-graph/adapters/yjs'
+
+// Performance
+await flow.enableWebGL() / disableWebGL()
+flow.setMemoization(true)
+```
+
+## Documentation
+
+Full guides in [`docs/`](./docs):
+1. [Getting Started](./docs/01-getting-started.md) — first 15 minutes
+2. [The Runtime](./docs/02-runtime.md) — make your graph actually compute
+3. [Designing Kinds](./docs/03-kinds.md) — schemas, ports, async, streaming
+4. [Performance at Scale](./docs/04-performance.md) — WebGL, bulk, LOD, 100k nodes
+5. [Plugin System](./docs/05-plugins.md) — lifecycle hooks
+6. [Multiplayer (Yjs)](./docs/06-multiplayer.md) — real-time co-editing
+7. [Recipes](./docs/07-recipes.md) — paste-and-run examples
+8. [API Reference](./docs/08-api.md) — every method, every event
+
+See the [examples folder](./examples) for working demos:
+- `basic.html` — 3-node minimum
+- `custom-kinds.html` — Plugin API
+- `showcase.html` — full feature parade
+- `runtime.html` — graph execution live
+- `multiplayer.html` — Yjs CRDT in two tabs
+- `powers.html` — schema validation + touch + WebGL
+- `plugins-and-debug.html` — lifecycle hooks + breakpoints + sub-flows
+- `stress.html` — 50k+ nodes WebGL benchmark
+
+## Loading WASM
+
+By default, `ZFlow.create({ wasmUrl })` fetches the WASM. For inline / offline scenarios, pre-load and pass bytes:
+
+```js
+const wasmBytes = await fetch('./zflow.wasm').then(r => r.arrayBuffer());
+const flow = await ZFlow.create({ container, wasmBytes });
+```
+
+If you bundle, copy `node_modules/@luispm/zflow-graph/dist/zflow.wasm` to your `public/` or static-asset directory and point `wasmUrl` at it.
+
+## Limits
+
+- Hard cap of 100,000 nodes / 200,000 edges per instance (compile-time in the WASM core)
+- Spatial grid covers ±8192 world units; nodes outside this range are still selectable but not in `queryRect` results
+- Snapshot-based undo keeps the last 8 states — large graphs make snapshots costly
+- The WebGL renderer requires `ANGLE_instanced_arrays` (essentially every browser since 2014); falls back to per-node draws otherwise
+- Yjs adapter sync rate is throttled to 30 Hz on position changes
+
+## Building from source
+
+You need Zig 0.16+ and Node 18+.
+
+```bash
+git clone https://github.com/luisg/@luispm/zflow-graph
+cd @luispm/zflow-graph
+npm install
+zig build           # produces dist/zflow.wasm
+npm run build:js    # produces dist/zflow.{esm,umd}{,.min}.js
+npm test            # 47 tests across 6 files
+```
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for the honest threat model. TL;DR:
+
+- All user-controlled strings in DOM overlays are HTML-escaped to prevent XSS.
+- Zero runtime dependencies. Yjs is opt-in.
+- `flow.use(plugin)` and `kind.execute` run with full page privileges — only install plugins you trust.
+- `evalExpression()` uses `new Function` — do not pass expressions from untrusted users.
+- Client-side JavaScript is **always readable**. There is no technical way to hide it. Use a license, or move sensitive logic to a server.
+- Minified bundles ship **without sourcemaps** to avoid leaking the source to CDN deployments.
+
+To report a vulnerability: `luis.padre21@gmail.com` with `[@luispm/zflow-graph security]` in subject.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,67 @@
+# Security model
+
+## What zflow-graph is
+
+A **client-side** ES module + WASM that renders and executes node graphs. It runs entirely in the browser (or any embedded WebView). It has no server component, no network calls of its own, and no privileged APIs.
+
+## What zflow-graph is **not**
+
+- Not a sandbox for untrusted code. Functions passed to `kind.execute` run with **the same privileges as your page**.
+- Not a secret store. Anything you put in `flow.toJSON()`, including `setNodeParams`, is visible in the browser.
+- Not obfuscated. Minified JS is readable in 2026 by any LLM in seconds. We do not pretend otherwise.
+
+## Threat model
+
+| Threat                                                | Mitigated by zflow? | Notes |
+| ----------------------------------------------------- | :-----------------: | ----- |
+| XSS via user-controlled node titles / descriptions    |         ✅          | All user strings rendered inside DOM overlays (preview popover, expression editor, context menu, autocomplete) are escaped with an internal `escapeHtml`. Canvas2D rendering is inherently text-safe (it's pixels). |
+| Code IP theft (someone reads your bundle)             |         ❌          | **Impossible to fully prevent on the web.** Use license (MIT/GPL/proprietary) for legal recourse. Move sensitive logic to a server you control. |
+| Supply-chain attack via `npm install zflow-graph`     |         ✅          | This package has **zero runtime dependencies**. Yjs is opt-in and only loaded if you import the adapter explicitly. Pin versions and audit with `npm audit`. |
+| Untrusted plugin via `flow.use(plugin)`               |         ❌          | Plugins run with full access to the flow and the host page. **Only install plugins you trust.** Treat them like NPM packages. |
+| Untrusted `kind.execute` body                         |         ❌          | Same as above — anything in `execute` runs with page privileges. Don't load executors from user input. |
+| Untrusted Mermaid / DOT / JSON imports                |         ✅          | The parsers are string-based — no `eval` or `new Function`. Worst case is malformed graph data. |
+| Untrusted `evalExpression` input                      |         ⚠️          | `evalExpression` uses `new Function` internally. **Do not pass expressions from untrusted users.** Use it for editor templates, not for user-submitted expressions. |
+| CSP (Content Security Policy) compatibility           |         ⚠️          | `evalExpression` requires `unsafe-eval` because of `new Function`. If your CSP forbids it, disable expression evaluation or fork to use a safe expression parser. |
+| WASM integrity                                        |         ✅          | The WASM is loaded by URL or pre-fetched bytes. If you want SRI-style integrity, hash the file at build time and verify before `WebAssembly.instantiate`. |
+
+## Recommended host-side hardening
+
+If you embed zflow-graph in an app, **the surrounding security work is your responsibility**:
+
+```http
+Content-Security-Policy:
+  default-src 'self';
+  script-src 'self' 'wasm-unsafe-eval';   # WASM needs wasm-unsafe-eval
+  worker-src 'self' blob:;
+  connect-src 'self' wss://your-yjs-relay.example;
+  img-src 'self' data: https:;            # if you setNodeImage with external URLs
+```
+
+Notes:
+- `wasm-unsafe-eval` is required to load `zflow.wasm`.
+- `unsafe-eval` is required if you call `evalExpression()`. If you don't, leave it out.
+- For Subresource Integrity of the WASM:
+  ```js
+  const buf = await fetch('zflow.wasm').then(r => r.arrayBuffer());
+  const hash = await crypto.subtle.digest('SHA-256', buf);
+  if (toHex(hash) !== EXPECTED_HASH) throw new Error('WASM tampered');
+  const flow = await ZFlow.create({ container, wasmBytes: new Uint8Array(buf) });
+  ```
+
+## Sourcemaps
+
+- Sourcemaps are **only emitted for the non-minified bundles** (`*.esm.js`, `*.umd.js`).
+- The minified bundles (`*.min.js`) ship **without sourcemaps** so accidentally deploying `dist/` to a CDN does not expose the full original source.
+- To opt in to maps on minified builds for your own debugging, run `ZFLOW_MAPS=1 npm run build:js`.
+
+## Reporting a vulnerability
+
+Email **luis.padre21@gmail.com** with `[zflow-graph security]` in the subject. Please do not open public issues for security reports.
+
+We aim to acknowledge within 72 hours. Critical issues get a patch within 7 days.
+
+## What we will *not* do
+
+- Add code obfuscation. It is performance overhead with no real security benefit. If you need IP protection, keep that code on a server.
+- Add a "license check" that calls home. zflow-graph is MIT — once you have it, you have it.
+- Promise that your secrets stay secret if you ship them in `flow.toJSON()`. They won't. Use a server.

package/dist/adapters/yjs.esm.js

@@ -0,0 +1,238 @@
+/*! @luispm/zflow-graph v0.1.0 | MIT | (c) 2026 */
+// zflow ↔ Yjs adapter — real multiplayer for the graph.
+//
+// Usage:
+//   import { ZFlow } from '../zflow.js';
+//   import { bindYjs } from '../adapters/yjs.js';
+//   import * as Y from 'yjs';
+//   import { WebsocketProvider } from 'y-websocket';
+//
+//   const flow = await ZFlow.create({ container, wasmUrl });
+//   const ydoc = new Y.Doc();
+//   new WebsocketProvider('wss://demos.yjs.dev', 'my-room', ydoc);
+//   const binding = bindYjs(flow, ydoc, { userId: 'alice', userName: 'Alice', color: '#c062e8' });
+//
+// What it syncs:
+//   • Nodes  (Y.Map keyed by stable client-side uuid → { id, kind, x, y, w, h, title, color, ... })
+//   • Edges  (Y.Map keyed by uuid → { from, to, fp, tp, label })
+//   • Awareness (cursor position, selection, name, color)
+//
+// Conflict policy: last-write-wins per field via Y.Map. Position updates are
+// throttled to ~30 Hz so dragging produces ~smooth remote motion without
+// flooding the wire.
+
+
+function bindYjs(flow, ydoc, opts = {}) {
+  const userId   = opts.userId   || 'user-' + Math.random().toString(36).slice(2, 8);
+  const userName = opts.userName || userId;
+  const userColor = opts.color   || pickColor(userId);
+
+  const ynodes = ydoc.getMap('zflow.nodes');
+  const yedges = ydoc.getMap('zflow.edges');
+  const ymeta  = ydoc.getMap('zflow.meta');
+  const aware  = opts.awareness || null; // y-protocols/awareness.Awareness, if provided
+
+  // Bidirectional mapping between local numeric ids and stable Y uuids.
+  const localToUuid = new Map(); // nodeId -> uuid
+  const uuidToLocal = new Map(); // uuid -> nodeId
+  const edgeLocalToUuid = new Map();
+  const edgeUuidToLocal = new Map();
+
+  let applyingRemote = false;            // re-entrancy guard
+  let pendingPosFlush = null;            // throttle handle
+
+  // ── Local → Remote ─────────────────────────────────────────────────
+  // We intercept the high-level mutators by wrapping the WASM exports so
+  // every change locally also writes to Yjs.
+  const origAddNode = flow.addNode.bind(flow);
+  flow.addNode = (spec = {}) => {
+    const id = origAddNode(spec);
+    if (id < 0 || applyingRemote) return id;
+    const uuid = newUuid();
+    localToUuid.set(id, uuid);
+    uuidToLocal.set(uuid, id);
+    ynodes.set(uuid, captureNode(flow, id, spec));
+    return id;
+  };
+
+  const origAddEdge = flow.addEdge.bind(flow);
+  flow.addEdge = (spec = {}) => {
+    const id = origAddEdge(spec);
+    if (id < 0 || applyingRemote) return id;
+    const uuid = newUuid();
+    edgeLocalToUuid.set(id, uuid);
+    edgeUuidToLocal.set(uuid, id);
+    const fromU = localToUuid.get(typeof spec.from === 'number' ? spec.from : -1);
+    const toU   = localToUuid.get(typeof spec.to   === 'number' ? spec.to   : -1);
+    yedges.set(uuid, { from: fromU, to: toU, fp: spec.fp ?? 0, tp: spec.tp ?? 0, label: spec.label || null });
+    return id;
+  };
+
+  // Intercept deleteSelection so each removed local id pulls its uuid out of Y.
+  const origDelete = flow.deleteSelection.bind(flow);
+  flow.deleteSelection = () => {
+    if (applyingRemote) return origDelete();
+    const toRemove = [];
+    for (let i = 0; i < flow.w.nodeCount_(); i++) if (flow.V.selected[i]) toRemove.push(i);
+    origDelete();
+    // Local ids shift after delete; clear the affected uuid mappings by re-scan.
+    ydoc.transact(() => {
+      for (const localId of toRemove) {
+        const uuid = localToUuid.get(localId);
+        if (uuid) { ynodes.delete(uuid); localToUuid.delete(localId); uuidToLocal.delete(uuid); }
+      }
+    }, 'local-delete');
+  };
+
+  // Throttle dragging updates.
+  flow.on('change', () => {
+    if (applyingRemote) return;
+    if (pendingPosFlush) return;
+    pendingPosFlush = setTimeout(() => {
+      pendingPosFlush = null;
+      ydoc.transact(() => {
+        for (const [localId, uuid] of localToUuid) {
+          if (localId >= flow.w.nodeCount_()) continue;
+          const cur = ynodes.get(uuid);
+          if (!cur) continue;
+          const next = captureNode(flow, localId);
+          if (cur.x !== next.x || cur.y !== next.y || cur.w !== next.w || cur.h !== next.h ||
+              cur.title !== next.title || cur.color !== next.color) {
+            ynodes.set(uuid, { ...cur, ...next });
+          }
+        }
+      }, 'local-pos');
+    }, 33);
+  });
+
+  // ── Remote → Local ─────────────────────────────────────────────────
+  ynodes.observe((event) => {
+    if (event.transaction.origin === 'local-pos') return;
+    applyingRemote = true;
+    try {
+      event.changes.keys.forEach((change, uuid) => {
+        if (change.action === 'add')    { addRemoteNode(uuid, ynodes.get(uuid)); }
+        if (change.action === 'update') { updateRemoteNode(uuid, ynodes.get(uuid)); }
+        if (change.action === 'delete') {
+          const localId = uuidToLocal.get(uuid);
+          if (localId !== undefined) {
+            flow.w.setSelected(localId, 1);
+            const orig = flow.deleteSelection;
+            flow.deleteSelection = origDelete;            // bypass intercept
+            try { flow.deleteSelection(); }
+            finally { flow.deleteSelection = orig; }
+            localToUuid.delete(localId);
+            uuidToLocal.delete(uuid);
+          }
+        }
+      });
+    } finally { applyingRemote = false; }
+  });
+
+  yedges.observe((event) => {
+    applyingRemote = true;
+    try {
+      event.changes.keys.forEach((change, uuid) => {
+        if (change.action === 'add') {
+          const e = yedges.get(uuid);
+          const from = uuidToLocal.get(e.from), to = uuidToLocal.get(e.to);
+          if (from !== undefined && to !== undefined) {
+            const localId = origAddEdge({ from, to, fp: e.fp, tp: e.tp, label: e.label });
+            edgeLocalToUuid.set(localId, uuid);
+            edgeUuidToLocal.set(uuid, localId);
+          }
+        }
+        if (change.action === 'delete') {
+          // Local-side deletion isn't wired through a single API yet; leave as a TODO.
+        }
+      });
+    } finally { applyingRemote = false; }
+  });
+
+  // ── Awareness (cursors + selection) ────────────────────────────────
+  if (aware) {
+    aware.setLocalStateField('user', { name: userName, color: userColor });
+    flow.canvas.addEventListener('mousemove', (e) => {
+      const wp = flow._s2w(e.clientX, e.clientY);
+      aware.setLocalStateField('cursor', { x: wp.x, y: wp.y });
+    });
+    aware.on('change', () => {
+      const states = aware.getStates();
+      flow.clearRemoteCursors();
+      for (const [clientId, state] of states) {
+        if (clientId === aware.clientID) continue;
+        const u = state.user || {}, c = state.cursor;
+        if (c) flow.setRemoteCursor(String(clientId), c.x, c.y, u.name || String(clientId), u.color || '#5be0d0');
+      }
+    });
+  }
+
+  // ── Initial backfill: pull whatever's already in the Y.Doc ─────────
+  applyingRemote = true;
+  try {
+    for (const [uuid, spec] of ynodes.entries()) addRemoteNode(uuid, spec);
+    for (const [uuid, spec] of yedges.entries()) {
+      const from = uuidToLocal.get(spec.from), to = uuidToLocal.get(spec.to);
+      if (from !== undefined && to !== undefined) {
+        const localId = origAddEdge({ from, to, fp: spec.fp, tp: spec.tp, label: spec.label });
+        edgeLocalToUuid.set(localId, uuid);
+        edgeUuidToLocal.set(uuid, localId);
+      }
+    }
+  } finally { applyingRemote = false; }
+
+  // ── Public adapter handle ──────────────────────────────────────────
+  return {
+    ynodes, yedges, ymeta, ydoc,
+    userId, userName, userColor,
+    destroy() {
+      flow.addNode = origAddNode;
+      flow.addEdge = origAddEdge;
+    },
+  };
+
+  // ── helpers ────────────────────────────────────────────────────────
+  function addRemoteNode(uuid, spec) {
+    if (uuidToLocal.has(uuid)) return;
+    const localId = origAddNode({
+      kind: spec.kind, x: spec.x, y: spec.y,
+      w: spec.w, h: spec.h, title: spec.title, color: spec.color,
+    });
+    if (localId < 0) return;
+    localToUuid.set(localId, uuid);
+    uuidToLocal.set(uuid, localId);
+  }
+  function updateRemoteNode(uuid, spec) {
+    const localId = uuidToLocal.get(uuid);
+    if (localId === undefined) return;
+    if (spec.x !== undefined && spec.y !== undefined) {
+      flow.V.posX[localId] = spec.x; flow.V.posY[localId] = spec.y;
+    }
+    if (spec.w !== undefined) flow.V.sizeW[localId] = spec.w;
+    if (spec.h !== undefined) flow.V.sizeH[localId] = spec.h;
+    if (spec.title) flow.titles.set(localId, spec.title);
+    if (spec.color) flow.colors.set(localId, spec.color);
+  }
+}
+
+function captureNode(flow, id, spec = {}) {
+  const cat = flow.kinds[flow.V.kind[id]];
+  return {
+    kind: cat.name,
+    x: flow.V.posX[id], y: flow.V.posY[id],
+    w: flow.V.sizeW[id], h: flow.V.sizeH[id],
+    title: flow.titles.get(id) || spec.title || null,
+    color: flow.colors.get(id) || spec.color || null,
+  };
+}
+function newUuid() {
+  return 'u_' + Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
+}
+const PALETTE = ['#5b8def', '#c062e8', '#5bd17a', '#f0b93a', '#5be0d0', '#fb923c', '#e8462b'];
+function pickColor(seed) {
+  let h = 0; for (const ch of seed) h = (h * 31 + ch.charCodeAt(0)) | 0;
+  return PALETTE[Math.abs(h) % PALETTE.length];
+}
+
+export { bindYjs };
+//# sourceMappingURL=yjs.esm.js.map

package/dist/adapters/yjs.esm.min.js

@@ -0,0 +1,2 @@
+/*! @luispm/zflow-graph v0.1.0 | MIT | (c) 2026 */
+function e(e,s,l={}){const r=l.userId||"user-"+Math.random().toString(36).slice(2,8),c=l.userName||r,i=l.color||function(e){let t=0;for(const o of e)t=31*t+o.charCodeAt(0)|0;return n[Math.abs(t)%n.length]}(r),d=s.getMap("zflow.nodes"),a=s.getMap("zflow.edges"),f=s.getMap("zflow.meta"),u=l.awareness||null,g=new Map,p=new Map,y=new Map,m=new Map;let b=!1,h=null;const w=e.addNode.bind(e);e.addNode=(n={})=>{const s=w(n);if(s<0||b)return s;const l=o();return g.set(s,l),p.set(l,s),d.set(l,t(e,s,n)),s};const v=e.addEdge.bind(e);e.addEdge=(e={})=>{const t=v(e);if(t<0||b)return t;const n=o();y.set(t,n),m.set(n,t);const s=g.get("number"==typeof e.from?e.from:-1),l=g.get("number"==typeof e.to?e.to:-1);return a.set(n,{from:s,to:l,fp:e.fp??0,tp:e.tp??0,label:e.label||null}),t};const S=e.deleteSelection.bind(e);e.deleteSelection=()=>{if(b)return S();const t=[];for(let o=0;o<e.w.nodeCount_();o++)e.V.selected[o]&&t.push(o);S(),s.transact(()=>{for(const e of t){const t=g.get(e);t&&(d.delete(t),g.delete(e),p.delete(t))}},"local-delete")},e.on("change",()=>{b||h||(h=setTimeout(()=>{h=null,s.transact(()=>{for(const[o,n]of g){if(o>=e.w.nodeCount_())continue;const s=d.get(n);if(!s)continue;const l=t(e,o);s.x===l.x&&s.y===l.y&&s.w===l.w&&s.h===l.h&&s.title===l.title&&s.color===l.color||d.set(n,{...s,...l})}},"local-pos")},33))}),d.observe(t=>{if("local-pos"!==t.transaction.origin){b=!0;try{t.changes.keys.forEach((t,o)=>{if("add"===t.action&&x(o,d.get(o)),"update"===t.action&&function(t,o){const n=p.get(t);if(void 0===n)return;void 0!==o.x&&void 0!==o.y&&(e.V.posX[n]=o.x,e.V.posY[n]=o.y);void 0!==o.w&&(e.V.sizeW[n]=o.w);void 0!==o.h&&(e.V.sizeH[n]=o.h);o.title&&e.titles.set(n,o.title);o.color&&e.colors.set(n,o.color)}(o,d.get(o)),"delete"===t.action){const t=p.get(o);if(void 0!==t){e.w.setSelected(t,1);const n=e.deleteSelection;e.deleteSelection=S;try{e.deleteSelection()}finally{e.deleteSelection=n}g.delete(t),p.delete(o)}}})}finally{b=!1}}}),a.observe(e=>{b=!0;try{e.changes.keys.forEach((e,t)=>{if("add"===e.action){const e=a.get(t),o=p.get(e.from),n=p.get(e.to);if(void 0!==o&&void 0!==n){const s=v({from:o,to:n,fp:e.fp,tp:e.tp,label:e.label});y.set(s,t),m.set(t,s)}}e.action})}finally{b=!1}}),u&&(u.setLocalStateField("user",{name:c,color:i}),e.canvas.addEventListener("mousemove",t=>{const o=e._s2w(t.clientX,t.clientY);u.setLocalStateField("cursor",{x:o.x,y:o.y})}),u.on("change",()=>{const t=u.getStates();e.clearRemoteCursors();for(const[o,n]of t){if(o===u.clientID)continue;const t=n.user||{},s=n.cursor;s&&e.setRemoteCursor(String(o),s.x,s.y,t.name||String(o),t.color||"#5be0d0")}})),b=!0;try{for(const[e,t]of d.entries())x(e,t);for(const[e,t]of a.entries()){const o=p.get(t.from),n=p.get(t.to);if(void 0!==o&&void 0!==n){const s=v({from:o,to:n,fp:t.fp,tp:t.tp,label:t.label});y.set(s,e),m.set(e,s)}}}finally{b=!1}return{ynodes:d,yedges:a,ymeta:f,ydoc:s,userId:r,userName:c,userColor:i,destroy(){e.addNode=w,e.addEdge=v}};function x(e,t){if(p.has(e))return;const o=w({kind:t.kind,x:t.x,y:t.y,w:t.w,h:t.h,title:t.title,color:t.color});o<0||(g.set(o,e),p.set(e,o))}}function t(e,t,o={}){return{kind:e.kinds[e.V.kind[t]].name,x:e.V.posX[t],y:e.V.posY[t],w:e.V.sizeW[t],h:e.V.sizeH[t],title:e.titles.get(t)||o.title||null,color:e.colors.get(t)||o.color||null}}function o(){return"u_"+Math.random().toString(36).slice(2,10)+Date.now().toString(36)}const n=["#5b8def","#c062e8","#5bd17a","#f0b93a","#5be0d0","#fb923c","#e8462b"];export{e as bindYjs};