@luispm/zflow-graph 0.1.0

package/docs/08-api.md

@@ -0,0 +1,436 @@
+# 8 · API Reference
+
+Every public method, grouped by capability. For event payloads, see [Events](#events).
+
+## Lifecycle
+
+```js
+static async ZFlow.create(opts) → ZFlow
+```
+Async constructor. Returns a ready ZFlow instance.
+
+**Options:**
+- `container: HTMLElement` (required) — host element
+- `wasmUrl: string` OR `wasmBytes: Uint8Array | ArrayBuffer` (one required)
+- `theme: 'dark' | 'light'` (default `'dark'`)
+- `edgeStyle: 'bezier' | 'orthogonal'` (default `'bezier'`)
+- `snapToGrid: boolean` (default `false`)
+- `gridSize: number` (default `20`)
+- `contextMenu: boolean` (default `true`)
+- `keyboard: boolean` (default `true`) — install keyboard shortcuts
+- `minimap: boolean` (default `false`)
+- `animateEdges: boolean` (default `false`)
+- `edgeFlowSpeed: number` (default `60`)
+- `inlineMarkdown: boolean` (default `true`)
+- `hoverPreview: boolean` (default `false`)
+- `webglThreshold: number` (default `2000`) — auto-enable GL above this
+- `stopOnError: boolean` (default `false`)
+- `dblclickEditsTitle: boolean` (default `true`)
+
+```js
+flow.dispose()
+```
+Detach all listeners, remove canvas, release WASM views.
+
+---
+
+## Mutation
+
+```js
+flow.addNode(spec) → number          // returns node id or -1
+flow.addEdge(spec) → number          // returns edge id or -1
+flow.deleteSelection()
+flow.moveNode(id, x, y)
+flow.duplicateSelection(dx = 40, dy = 40)
+flow.addNodesBulk(specs) → number[]  // bulk insert (returns ids in order)
+flow.addEdgesBulk(specs) → number[]
+```
+
+**`addNode` spec fields:**
+- `kind: string | number` — kind name or index
+- `x`, `y` — world coords (default 0, 0)
+- `w`, `h` — size (defaults from kind)
+- `nin`, `nout` — override port counts
+- `title`, `color`, `description`, `tags`, `status`, `progress`
+- `image`, `checked`, `tasks`, `icon`, `links`
+- `portIn`, `portOut` — per-node port label override
+- `animate: false` — skip pop-in animation
+
+**`addEdge` spec fields:**
+- `from: number` — source node id (required)
+- `to: number` — target node id (required)
+- `fp: number` — source port index (default 0)
+- `tp: number` — target port index (default 0)
+- `label: string` — edge label
+
+---
+
+## Selection
+
+```js
+flow.setSelected(id, on)
+flow.toggleSelected(id)
+flow.clearSelection()
+flow.selectAll()
+flow.getSelection() → number[]
+flow.nodeCount() → number
+flow.edgeCount() → number
+```
+
+---
+
+## Rich content
+
+```js
+flow.setNodeTitle(id, title)
+flow.setNodeColor(id, hex)
+flow.setNodeDescription(id, md)     // supports inline markdown
+flow.setNodeTags(id, tags)          // string[]
+flow.setNodeStatus(id, status)      // 'ok' | 'running' | 'error' | 'warn' | 'idle' | ...
+flow.setNodeProgress(id, p)         // 0..1
+flow.setNodeImage(id, url)
+flow.setNodeChecked(id, bool)
+flow.setNodeTasks(id, [{text, done}, ...])
+flow.setNodeIcon(id, glyph)
+flow.setNodeLinks(id, [{url, label}, ...])
+flow.setPortInLabels(id, labels)
+flow.setPortOutLabels(id, labels)
+flow.setEdgeLabel(eid, label)
+```
+
+---
+
+## Visual
+
+```js
+flow.setEdgeStyle('bezier' | 'orthogonal')
+flow.setSnapToGrid(bool)
+flow.setTheme('dark' | 'light')
+flow.toggleTheme()
+flow.setMinimap(bool)
+flow.setHoverPreview(bool)
+flow.setPathHighlight(bool)
+flow.setEdgeAnimated(edgeId, bool)
+flow.setAllEdgesAnimated(bool)
+flow.setEdgeWaypoints(edgeId, points)
+flow.clearEdgeWaypoints(edgeId)
+
+flow.bringToFront(ids?)
+flow.sendToBack(ids?)
+flow.zoomTo(zoom)
+flow.panTo(x, y)
+flow.fitView(padding = 80)
+flow.runAutoLayout()        // Sugiyama hierarchical
+flow.runForceLayout(maxFrames = 220)
+```
+
+---
+
+## Locks & read-only
+
+```js
+flow.lockNode(id, on = true)
+flow.isLocked(id) → boolean
+flow.setReadOnly(on)        // disables mutations
+```
+
+---
+
+## Sticky notes
+
+```js
+flow.addNote(x, y, text = '', opts = {}) → number    // returns note id
+flow.deleteNote(noteId)
+```
+
+---
+
+## Frames (groups)
+
+```js
+flow.addFrame(x, y, w, h, label = 'Group', color = '#5b8def') → { id, ... }
+flow.groupSelection(label = 'Group')
+flow.deleteFrame(frameId)
+flow.toggleFrameCollapse(frameIdx)
+flow.isFrameCollapsed(frameIdx) → boolean
+flow.enterSubflow(frameId)         // dim everything outside
+flow.exitSubflow()
+flow.registerSubflowFromFrame(frameId, opts) → kindName
+```
+
+---
+
+## Bookmarks
+
+```js
+flow.setBookmark(slot, nodeId?)   // slot = 1..9
+flow.jumpBookmark(slot)
+```
+
+---
+
+## Multi-cursor presence
+
+```js
+flow.setRemoteCursor(userId, x, y, name?, color?)
+flow.clearRemoteCursors()
+```
+
+(Wire to your real CRDT via the [Yjs adapter](./06-multiplayer.md) instead of calling these directly.)
+
+---
+
+## Kinds
+
+```js
+flow.registerKind(spec) → number    // returns kind index
+flow.setKindExecutor(kindName, fn) → previousFn
+```
+
+Spec fields: see [Designing Kinds](./03-kinds.md).
+
+---
+
+## Runtime
+
+```js
+flow.run({ from?, filter?, signal? }) → Promise<{ executed, errors, values }>
+flow.runFrom(nodeId) → Promise<result>
+flow.runFrame(frameId) → Promise<result>
+flow.stop()
+flow.startLoop(intervalMs = 500)
+flow.stopLoop()
+flow.isRunning() → boolean
+flow.setRunStepDelay(ms)
+flow.setMemoization(bool)
+flow.clearRuntimeState()
+
+flow.setNodeInput(id, outputs)    // inject a node's output without running it
+flow.setNodeParams(id, params)
+flow.getNodeParams(id) → params
+flow.getNodeValue(id) → output
+
+flow.evalExpression(expr, extraScope?) → result
+```
+
+### Debugging
+
+```js
+flow.setBreakpoint(id, on = true)
+flow.toggleBreakpoint(id)
+flow.clearBreakpoints()
+flow.setStepMode(on)
+flow.stepOver()
+flow.resume()
+flow.isPaused() → boolean
+```
+
+### Streaming metrics
+
+```js
+flow.pushNodeMetric(id, value)
+flow.clearNodeMetric(id)
+```
+
+---
+
+## Validation
+
+```js
+flow.validateConnection(fromN, fp, toN, tp) → string | null   // null = ok
+flow.setConnectionValidator(fn)
+```
+
+---
+
+## Algorithms
+
+```js
+flow.shortestPath(from, to) → edgeIds[]
+flow.criticalPath() → edgeIds[]
+flow.findSCCs() → nodeIds[][]
+flow.findCycles() → edgeIds[]
+flow.colorByDegree()
+flow.clearNodeColors()
+flow.setReachableFrom(nodeId)
+flow.clearReachable()
+```
+
+---
+
+## Serialization
+
+```js
+flow.toJSON() → object
+flow.loadJSON(data)
+flow.exportSVG() → string
+flow.exportPNG() → Promise<Blob>
+```
+
+---
+
+## Imports
+
+```js
+flow.importMermaid(text)
+flow.importDot(text)
+```
+
+---
+
+## Plugins
+
+```js
+flow.use(plugin) → dispose fn
+```
+
+See [Plugin System](./05-plugins.md).
+
+---
+
+## Search
+
+```js
+flow.search(query) → nodeIds[]
+flow.jumpToSearchHit(idx)
+flow.clearSearch()
+flow.openSearch()           // opens the search UI
+```
+
+---
+
+## Command palette
+
+```js
+flow.openCommandPalette()   // toggles
+flow.registerTemplate(name, builder)
+flow.insertTemplate(name, x, y) → id
+flow.listTemplates() → string[]
+```
+
+---
+
+## Undo / redo
+
+```js
+flow.undo()
+flow.redo()
+flow.snapshot()             // manual save point
+```
+
+---
+
+## WebGL
+
+```js
+await flow.enableWebGL(force = false) → bool
+flow.disableWebGL()
+```
+
+---
+
+## Inline editor
+
+```js
+flow.editNodeExpression(nodeId, field = 'title')   // 'title' | 'desc'
+```
+
+Opens a floating editor with autocomplete for `{{node_X.value}}` expressions and live preview.
+
+---
+
+## Drag-from-palette
+
+```js
+flow.makeDraggable(domElement, spec)
+```
+
+Wires a DOM element so dragging it into the canvas creates a node of the given kind.
+
+---
+
+## Events
+
+```js
+flow.on(event, callback)        // returns nothing; pass same fn to remove
+```
+
+| Event                  | Payload                                        |
+| ---------------------- | ---------------------------------------------- |
+| `change`               | (none)                                         |
+| `select`               | nodeIds[]                                      |
+| `node:dblclick`        | nodeId                                         |
+| `edge:dblclick`        | edgeId                                         |
+| `canvas:dblclick`      | { x, y } (world coords)                        |
+| `theme`                | 'dark' | 'light'                               |
+| `renderer`             | 'canvas2d' | 'webgl'                           |
+| `connection:rejected`  | { fromN, fromP, toN, toP, reason }             |
+| `plugin:installed`     | plugin name or object                          |
+| `palette:drop`         | { id, x, y, spec }                             |
+| `run:start`            | { order: nodeIds[] }                           |
+| `run:done`             | { executed, errors, values }                   |
+| `run:paused`           | { nodeId }                                     |
+| `node:exec`            | { id, inputs }                                 |
+| `node:emit`            | { id, outputs } — per emission incl. streaming |
+| `node:done`            | { id, outputs }                                |
+| `node:error`           | { id, error }                                  |
+| `node:retry`           | { id, attempt, error }                         |
+| `node:cached`          | { id }                                         |
+| `node:log`             | { id, args }                                   |
+
+---
+
+## Direct WASM access
+
+For advanced cases you can call WASM exports directly via `flow.w.*`:
+
+```js
+flow.w.hitTestNode(x, y) → nodeId | -1
+flow.w.hitTestPort(x, y, tol) → packed | -1
+flow.w.queryRect(minX, minY, maxX, maxY) → count
+flow.w.nodeCount_() → number
+flow.w.edgeCount_() → number
+flow.w.nodeCap() → number
+flow.w.edgeCap() → number
+flow.w.snapshot()
+flow.w.undo() → 0 | 1
+flow.w.redo() → 0 | 1
+```
+
+`flow.V` exposes the typed-array views:
+
+```js
+flow.V.posX        // Float32Array (length = cap)
+flow.V.posY
+flow.V.sizeW
+flow.V.sizeH
+flow.V.kind        // Uint8Array
+flow.V.nIn
+flow.V.nOut
+flow.V.selected
+flow.V.edgeFromN   // Uint32Array
+flow.V.edgeToN
+flow.V.edgeFromP   // Uint8Array
+flow.V.edgeToP
+flow.V.edgeSel
+flow.V.queryRes    // Uint32Array (results from queryRect)
+```
+
+Reading is always safe (zero-copy). Writing to these arrays bypasses event emission and dirty tracking — use the high-level methods unless you know what you're doing.
+
+---
+
+## Constants
+
+```js
+flow.kinds          // array of kind specs in registration order
+flow.kindByName     // Map: name → index
+flow.cam            // { x, y, zoom } — read-write, but use panTo/zoomTo for animation
+flow.canvas         // the canvas element
+flow.container      // the host element
+flow.options        // mutable options object
+```
+
+---
+
+That's the full surface. ~230 public methods + 16 events. Search by `Ctrl+F` in the docs to find anything.

package/docs/README.md

@@ -0,0 +1,61 @@
+# zflow-graph · Documentation
+
+Guides ordered from "I want to play" to "I want to ship".
+
+## Tutorials (read in order)
+1. [Getting Started](./01-getting-started.md) — install, first graph, first run · **15 min**
+2. [The Runtime](./02-runtime.md) — make your graph actually compute things · **20 min**
+3. [Designing Kinds](./03-kinds.md) — schemas, ports, async, retry, streaming · **20 min**
+4. [Performance at Scale](./04-performance.md) — WebGL, bulk ops, LOD, 100k nodes · **15 min**
+
+## Guides (read as needed)
+5. [Plugin System](./05-plugins.md) — lifecycle hooks, recipes
+6. [Multiplayer (Yjs)](./06-multiplayer.md) — real-time co-editing
+7. [Recipes](./07-recipes.md) — worked examples you can paste
+
+## Reference
+8. [API Reference](./08-api.md) — every public method, every event
+
+---
+
+## What zflow-graph actually is
+
+A graph editor *and* a runtime in one ES module. You can:
+
+- **Build editors** — the user drags nodes, connects ports, edits properties
+- **Run the graph** — each node has an `execute()` function; the runtime walks topology and propagates values through edges
+- **Embed both** — your app is the editor for end-users *and* the runtime that runs their work
+
+This is the same shape as n8n, ComfyUI, Unreal Blueprints, Scratch, Node-RED. The difference: zflow-graph is **a library**, not a product. It runs anywhere you have a DOM and a WASM-capable JS engine.
+
+## When to use it
+
+| You want to build…                          | Use zflow? |
+| ------------------------------------------- | :--------: |
+| A workflow automation tool (n8n / Zapier)   |     ✅     |
+| A visual ML pipeline editor (ComfyUI clone) |     ✅     |
+| A live data dashboard with node graph       |     ✅     |
+| A diagram editor (Drawio replacement)       |     ✅     |
+| A game-engine blueprint editor              |     ✅     |
+| A simple flowchart for docs                 |   ⚠️ overkill   |
+| A whiteboard / sketching tool               |   ❌ (use tldraw) |
+| A code diff visualizer                      |   ❌ (use d3)    |
+
+## When NOT to use it
+
+- You need IE11 support. zflow needs ES2020 and WASM.
+- Your graph is purely static / read-only and < 100 nodes. SVG is fine for that.
+- You need server-side rendering. zflow renders in the browser (or Electron/Tauri/WebView2 — same shape).
+- You want to obfuscate the source against piracy. JavaScript isn't obfuscatable. See [SECURITY.md](../SECURITY.md).
+
+## The mental model in 3 sentences
+
+1. The graph lives in a **WASM core** (Zig). JS holds zero-copy views into it.
+2. Each **node** has a **kind**. Kinds are templates: shape, color, ports, and an optional `execute()` body.
+3. When you call `flow.run()`, the runtime walks nodes in topological order, calls `execute(ctx, inputs)`, and propagates outputs through edges.
+
+Everything else — multiplayer, undo, layouts, sub-flows, animations — is built on those three primitives.
+
+## A note on the docs style
+
+These are **executable docs**. Every code block is a real snippet you can paste into an HTML file with zflow imported. No pseudocode. If a snippet doesn't work as written, that's a bug in the docs or the library — report it.

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@luispm/zflow-graph",
+  "version": "0.1.0",
+  "description": "WASM-powered node-edge graph editor + runtime. No framework. 100k nodes at 60fps. Built-in execution engine, Yjs multiplayer, WebGL renderer.",
+  "type": "module",
+  "main": "./dist/zflow.umd.js",
+  "module": "./dist/zflow.esm.js",
+  "browser": "./dist/zflow.umd.min.js",
+  "unpkg": "./dist/zflow.umd.min.js",
+  "jsdelivr": "./dist/zflow.umd.min.js",
+  "exports": {
+    ".": {
+      "import": "./dist/zflow.esm.js",
+      "require": "./dist/zflow.umd.js",
+      "default": "./dist/zflow.esm.js"
+    },
+    "./webgl": {
+      "import": "./dist/webgl-renderer.esm.js",
+      "require": "./dist/webgl-renderer.umd.js"
+    },
+    "./adapters/yjs": {
+      "import": "./dist/adapters/yjs.esm.js",
+      "require": "./dist/adapters/yjs.umd.js"
+    },
+    "./wasm": "./dist/zflow.wasm",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/zflow.esm.js",
+    "dist/zflow.esm.js.map",
+    "dist/zflow.esm.min.js",
+    "dist/zflow.esm.min.js.map",
+    "dist/zflow.umd.js",
+    "dist/zflow.umd.js.map",
+    "dist/zflow.umd.min.js",
+    "dist/zflow.umd.min.js.map",
+    "dist/zflow.wasm",
+    "dist/webgl-renderer.esm.js",
+    "dist/webgl-renderer.esm.min.js",
+    "dist/webgl-renderer.umd.js",
+    "dist/adapters/yjs.esm.js",
+    "dist/adapters/yjs.esm.min.js",
+    "dist/adapters/yjs.umd.js",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "docs/"
+  ],
+  "scripts": {
+    "build:wasm": "zig build",
+    "build:js": "rollup -c",
+    "build": "npm run build:wasm && npm run build:js",
+    "dev": "rollup -c -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run test && npm run build",
+    "serve": "python -m http.server 8765"
+  },
+  "keywords": [
+    "graph",
+    "editor",
+    "node",
+    "edge",
+    "diagram",
+    "flowchart",
+    "react-flow-alternative",
+    "wasm",
+    "webgl",
+    "visual-programming",
+    "no-code",
+    "workflow",
+    "canvas",
+    "interactive"
+  ],
+  "author": "Luis G. <luis.padre21@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luisg/zflow-graph"
+  },
+  "homepage": "https://github.com/luisg/zflow-graph#readme",
+  "bugs": {
+    "url": "https://github.com/luisg/zflow-graph/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "@vitest/coverage-v8": "^1.6.0",
+    "jsdom": "^24.0.0",
+    "rollup": "^4.18.0",
+    "vitest": "^1.6.0"
+  },
+  "peerDependenciesMeta": {
+    "yjs": { "optional": true }
+  }
+}