feat(@rozie-ui/rete): FlowCanvas — cross-framework node-flow editor (Rete.js v2)

One FlowCanvas.rozie compiles to idiomatic React/Vue/Svelte/Angular/Solid/Lit
node-flow editors, filling a real gap: no single library ships all six (xyflow
is React+Svelte only, Vue Flow is separate, Solid has only an experiment, Lit
nothing). Wraps the framework-agnostic Rete.js v2 engine (NodeEditor owns the
graph; AreaPlugin owns pan/zoom/drag; ConnectionPlugin owns drag-to-connect)
with a single VANILLA render layer — no per-framework render plugin.

Surface: 13 props / two-way `zoom` model / 7 events / 12-verb `$expose` /
reactive multi-instance `node` portal slot. Config-array `:nodes`/`:connections`
reconciled live; sockets announced via `render` type 'socket' signals so the
ConnectionPlugin + getDOMSocketPosition watcher wire up drag-to-connect;
connection paths drawn with classicConnectionPath + the socket-position watcher.

Package: @rozie-ui/rete + 6 pre-compiled leaves (codegen.mjs doc-automation,
handle-manifest, README generation, ENFORCING docs props-table validation).
No emitter/core change → dist-parity zero-drift.

Verified: compile 6/6 zero-error; react/solid/lit leaf strict-tsc clean; 15
surface tests; behavioral VR 6/6 + screenshot VR 6/6 pixel-parity in the pinned
Linux container (shared FlowCanvasScreenshot.png baseline, all 6 ≤2px).

Docs: /guide/rete (showcase), /guide/rete-comparison, /guide/rete-demo (live
@rozie-ui/rete-vue in VitePress) — build clean, 0 broken anchors.

Two cross-target bugs found + fixed in the wrapper source:
- socketWatcher.attach() needs a CHILD Scope of the area (parentScope walks up
  one level); attaching to the area itself throws.
- slot-name == local-binding shadow: a `node` param shadowed Svelte's
  `$slots.node` (→ `const node = $derived(...)`), dropping default node chrome
  on Svelte only; renamed param → reteNode.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: serpentblade

docs/.vitepress/config.ts

@@ -175,6 +175,14 @@ export default defineConfig({
             { text: 'PdfViewer — live demo', link: '/guide/pdf-demo' },
           ],
         },
+        {
+          text: '@rozie-ui/rete',
+          items: [
+            { text: 'FlowCanvas — showcase & API', link: '/guide/rete' },
+            { text: 'Node-flow editor comparison', link: '/guide/rete-comparison' },
+            { text: 'FlowCanvas — live demo', link: '/guide/rete-demo' },
+          ],
+        },
       ],
       '/compatibility': [
         {

docs/guide/rete-comparison.md

@@ -0,0 +1,70 @@
+# Node-flow editor libraries comparison
+
+How `@rozie-ui/rete` (`FlowCanvas`) compares to the existing per-framework node-flow / graph editor libraries. A node editor's hard parts — the graph model, viewport pan/zoom, node drag, and drag-to-connect — are inherently framework-agnostic; [Rete.js v2](https://retejs.org/) is the engine that owns all of them and delegates only *rendering* to a swappable layer. The per-framework editors each re-solve those hard parts from scratch, which is why the ecosystem is **siloed**: React and Svelte are well-served, Vue has a separate reimplementation, Angular has a couple of options, and **Solid has only an experiment while Lit has nothing**. Rozie ships one source to all six by wrapping the agnostic engine with a single vanilla render layer.
+
+> Research snapshot: 2026-06-08. Versions and the landscape move; treat them as of that date. The full audit is in [`node-flow-editor-feasibility.md`](https://github.com/One-Learning-Community/rozie.js/blob/main/.planning/research/node-flow-editor-feasibility.md).
+
+## The libraries at a glance
+
+| Library | Package | Frameworks | Rendering | State model | Verdict |
+| --- | --- | --- | --- | --- | --- |
+| **React Flow** | `@xyflow/react` | **React only** | SVG edges + DOM nodes | internal Zustand store | mature, deep — the category leader on React |
+| **Svelte Flow** | `@xyflow/svelte` | **Svelte only** | SVG + DOM | Svelte 5 runes | mature; shares `@xyflow/system` core with React Flow |
+| **Vue Flow** | `@vue-flow/core` | **Vue only** | SVG + DOM | own Vue store | mature, but a **separate** codebase — not xyflow's shared core |
+| **Foblex Flow** | `@foblex/flow` | **Angular only** | DOM + SVG | Angular signals | active; Angular-only |
+| **ngx-graph** | `@swimlane/ngx-graph` | **Angular only** | SVG (D3 + dagre) | RxJS | graph-viz-first, less an interactive editor |
+| **solid-flow** | `solid-flow` | Solid | SVG + DOM | signals | **single-author experiment**, not production-grade |
+| **Lit** | — | — | — | — | **no standalone library exists** |
+| **Rozie** | `@rozie-ui/rete-*` | **all 6** | DOM + SVG (vanilla render layer) | Rete `NodeEditor` (the engine owns it) | one source → React/Vue/Svelte/Angular/Solid/Lit |
+
+The big-framework editors above are **excellent, mature libraries** — for a single-React app, React Flow is the obvious pick, and Rozie does not claim to out-feature it on its home framework. The wedge is breadth: **no single library ships all six**, and two targets are essentially unserved. xyflow — the strongest brand — publishes only `@xyflow/react` and `@xyflow/svelte` (its shared `@xyflow/system` core has **no** Vue/Solid/Angular/Lit wrapper); Vue Flow is a wholly separate project; **Solid** has only a single-author `solid-flow` experiment; and **Lit / web-components has nothing at all**. The one ecosystem that even approaches breadth is **Rete.js**, whose render plugins cover React/Vue/Angular/Svelte/Lit — five divergent codebases, and still no Solid. Rozie replaces those five plugins with **one `.rozie` source and one vanilla render layer**, and adds the missing Solid (and a far thinner Lit) for free.
+
+## Why wrap Rete.js
+
+A Rete render plugin's only job is to (a) fill each engine-created node element with DOM, (b) draw each connection's SVG path, and (c) tell the connection plugin where the sockets are. The official plugins do (a)+(b) with a framework's component tree — that *is* the per-framework coupling. `FlowCanvas` does all three with a **vanilla render pipe** (`area.addPipe`), emitting `render` socket signals the `ConnectionPlugin` + `getDOMSocketPosition` watcher consume, and drawing connection paths with `classicConnectionPath`. The engine (`NodeEditor` + `AreaPlugin` + `ConnectionPlugin`) owns graph state and all pointer interaction; the Rozie component is a thin view over it, so the same source behaves identically on every target.
+
+## Feature matrix
+
+Cell legend: **✅** = documented out-of-the-box · **❌** = not supported / not present · **⚠️** = partial / experimental / consumer-glue-required.
+
+| Capability | React Flow | Vue Flow | Svelte Flow | Foblex (Angular) | solid-flow | Lit (none) | **`@rozie-ui/rete`** |
+| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| Mount canvas | ✅ | ✅ | ✅ | ✅ | ⚠️ | hand-roll | ✅ |
+| Pan / zoom viewport | ✅ | ✅ | ✅ | ✅ | ⚠️ | hand-roll | ✅ (engine-owned) |
+| Node drag | ✅ | ✅ | ✅ | ✅ | ⚠️ | hand-roll | ✅ (engine-owned) |
+| **Drag-to-connect** (sockets) | ✅ | ✅ | ✅ | ✅ | ⚠️ | hand-roll | ✅ (socket render-signal bridge) |
+| **Custom node bodies** (framework component) | ✅ node types | ✅ | ✅ | ✅ | ⚠️ | ❌ | ✅ `node` reactive portal slot (all 6) |
+| Two-way zoom binding | ⚠️ controlled | ⚠️ | ⚠️ | ⚠️ | ⚠️ | hand-roll | ✅ `r-model:zoom` (echo-guarded) |
+| Graph events (moved / connected / picked) | ✅ | ✅ | ✅ | ✅ | ⚠️ | hand-roll | ✅ 7 structured events |
+| Imperative handle | ✅ `useReactFlow` | ✅ `useVueFlow` | ✅ | ✅ service | ⚠️ | hand-roll | ✅ uniform 12-verb `$expose` |
+| Config-array graph (`:nodes` / `:connections`) | ✅ | ✅ | ✅ | ✅ | ⚠️ | ❌ | ✅ reconciled live, no remount |
+| MiniMap / Background / Controls | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | ❌ | ⚠️ deferred (see below) |
+| TypeScript | ✅ | ✅ | ✅ | ✅ | ⚠️ | — | ✅ |
+| One source → all 6 frameworks | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+
+## Where Rozie wins today
+
+- **One definition, six idiomatic packages** — including the two frameworks the ecosystem leaves out entirely: **Solid** (only a single-author experiment) and **Lit** (nothing). Those consumers get a real node editor they otherwise cannot have, from the same source that produces the four big-framework packages.
+- **Framework-native node bodies on all six** — the `node` **reactive multi-instance portal slot** renders a real framework fragment (any component, any reactivity) as a graph node, re-rendered in place as the node's data / selection changes, reconciled off the `nodes` data array.
+- **The engine owns interaction, so behavior is identical by construction** — pan/zoom transform, node drag, edge drawing, and connection-handle hit-testing all live in Rete's `AreaPlugin` + `ConnectionPlugin`. Rozie never re-implements pointer math per target, so there is no cross-framework drift in *how the editor feels*.
+- **A uniform 12-verb imperative handle** (`getEditor` / `getArea` / `addNode` / `removeNode` / `addConnection` / `removeConnection` / `clear` / `zoomToFit` / `zoomTo` / `getNodes` / `getConnections` / `getTransform`) grabbed with each framework's native ref — versus "however this library happens to expose its instance" (a hook, a service, a ref).
+- **`getEditor()` / `getArea()` are always one hop from the raw engine**, so the full Rete API (custom plugins, `rete-engine` dataflow, `rete-auto-arrange-plugin`, …) is reachable on any target when the curated surface doesn't cover something.
+
+## What Rozie defers {#what-rozie-defers}
+
+This page concedes where the standalone libraries are genuinely ahead — that's what keeps the comparison credible, and it doubles as Rozie's roadmap.
+
+- **Declarative `<Node>` / `<Edge>` *children*.** React Flow et al. let you compose a graph as JSX/children with per-type node components registered up front. Rozie v1 takes a different authoring shape: the **`:nodes` / `:connections` config-array props** (reconciled into the live editor), with per-node bodies supplied through the `node` slot. It is the **same `addNode` / `addConnection` runtime** and reaches the same result, but the authoring model is a config array, not nested children. True declarative graph children — deeply-nested `<Node>`/`<Handle>` elements reading shared graph state (selection, viewport, neighbors) without prop-drilling — need a **cross-component context primitive** that Rozie deliberately defers (the same primitive MapLibre's `:sources` / `:layers` deferral is waiting on). The wrap-a-vanilla-engine strategy sidesteps it entirely: the **engine** owns the store, and node bodies reach it through portal scope.
+- **MiniMap / Background variants / NodeToolbar / NodeResizer.** React Flow ships these as first-class components. `FlowCanvas` v1 covers the canvas + nodes + sockets + connections + a dotted background; the second-tier chrome is on the roadmap (config-prop first, the MapLibre stance).
+- **Big-framework depth on the home framework.** React Flow (Zustand store, deep node/edge-type catalogs, helper hooks, layouting integrations) is a mature, multi-year library; on React it exposes more surface than Rozie's curated set. Rozie's value is **not** "more than React Flow on React" — it's the **same idiomatic editor on all six frameworks from one source**, with the unserved **Solid and Lit** finally covered.
+- **`@rozie-ui/rete` is `0.1.0`.** The surface (13 props / 7 events / 12-verb handle / `node` reactive slot) is stable and gate-verified (behavioral parity across all six targets), but it is younger than the incumbents.
+
+## Try it
+
+The [`@rozie-ui/rete` showcase + API reference](/guide/rete) documents the `@rozie-ui/rete-*` packages — one pre-compiled, per-framework install (`npm i @rozie-ui/rete-react rete rete-area-plugin rete-connection-plugin rete-render-utils`, etc.). Rete ships no stylesheet, so there is no engine CSS to import — all node / socket / connection chrome is styled by the component.
+
+## Cross-references
+
+- [FlowCanvas — showcase & API](/guide/rete) — the full `@rozie-ui/rete` surface, quick starts, and the `node` slot recipe.
+- [`FlowCanvas.rozie` source on GitHub](https://github.com/One-Learning-Community/rozie.js/blob/main/packages/ui/rete/src/FlowCanvas.rozie)
+- [The portal-slot primitive](/examples/portal-list) — the mechanism the `node` reactive slot builds on.

docs/guide/rete-demo.md

@@ -0,0 +1,169 @@
+---
+title: FlowCanvas — live demo
+---
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import FlowCanvas from '@rozie-ui/rete-vue';
+
+// A small, fixed graph. `nodes` / `connections` are plain config arrays — the
+// same shape that compiles to all six frameworks. Each node declares its
+// input/output socket keys; connections reference nodes + socket keys by id.
+const INITIAL_NODES = [
+  { id: 'input',  label: 'Input',     x: 20,  y: 40,  data: { kind: 'in' },  outputs: [{ key: 'out', label: 'value' }] },
+  { id: 'filter', label: 'Transform', x: 280, y: 40,  data: { kind: 'op' },  inputs: [{ key: 'in', label: 'in' }], outputs: [{ key: 'out', label: 'out' }] },
+  { id: 'output', label: 'Output',    x: 540, y: 140, data: { kind: 'out' }, inputs: [{ key: 'in', label: 'result' }] },
+];
+const INITIAL_EDGES = [
+  { id: 'e1', source: 'input',  sourceOutput: 'out', target: 'filter', targetInput: 'in' },
+  { id: 'e2', source: 'filter', sourceOutput: 'out', target: 'output', targetInput: 'in' },
+];
+
+const flow = ref();
+const zoom = ref(1);
+const nodes = ref(INITIAL_NODES.map((n) => ({ ...n })));
+const connections = ref(INITIAL_EDGES.map((e) => ({ ...e })));
+let next = 1;
+
+function addNode() {
+  const id = 'n' + next++;
+  nodes.value = [
+    ...nodes.value,
+    { id, label: 'Node ' + id, x: 120 + nodes.value.length * 24, y: 240, data: { kind: 'op' }, inputs: [{ key: 'in' }], outputs: [{ key: 'out' }] },
+  ];
+}
+function reset() {
+  next = 1;
+  nodes.value = INITIAL_NODES.map((n) => ({ ...n }));
+  connections.value = INITIAL_EDGES.map((e) => ({ ...e }));
+  zoom.value = 1;
+}
+</script>
+
+# FlowCanvas — live demo
+
+This is the **real `@rozie-ui/rete-vue` package** running on this page (VitePress is itself a Vue app) — driving an actual [Rete.js v2](https://retejs.org/) node editor. **Drag a node**, **drag from one socket to another to connect them**, scroll to zoom, or use the controls below. Everything is driven by the same `FlowCanvas.rozie` source that compiles to all six frameworks, through a **vanilla render layer** (no framework-specific Rete render plugin). Rete ships no stylesheet — every node, socket, and connection you see is styled by the component itself.
+
+<ClientOnly>
+<div class="flow-live">
+  <div class="flow-live__controls">
+    <button @click="addNode">Add node ＋</button>
+    <button @click="zoom = Math.min(Math.round((zoom + 0.25) * 100) / 100, 4)">Zoom in ＋</button>
+    <button @click="zoom = Math.max(Math.round((zoom - 0.25) * 100) / 100, 0.2)">Zoom out －</button>
+    <button @click="flow?.zoomToFit()">Fit ▣</button>
+    <span class="flow-live__sep" />
+    <button class="flow-live__primary" @click="reset">Reset ▸</button>
+  </div>
+
+  <div class="flow-live__stage">
+    <FlowCanvas
+      ref="flow"
+      :nodes="nodes"
+      :connections="connections"
+      v-model:zoom="zoom"
+      style="width: 100%; height: 380px;"
+    >
+      <template #node="{ node, selected }">
+        <div class="flow-live__node" :class="{ 'is-selected': selected }" :data-kind="node.data?.kind">
+          <strong>{{ node.label }}</strong>
+        </div>
+      </template>
+    </FlowCanvas>
+  </div>
+
+  <div class="flow-live__readout">
+    <code>{{ nodes.length }} nodes · {{ connections.length }} connections · zoom {{ zoom.toFixed(2) }}</code>
+  </div>
+</div>
+</ClientOnly>
+
+The graph is a pair of plain config arrays (`:nodes` / `:connections`); **Add node** pushes onto `nodes` and the wrapper reconciles it into the live editor with no remount. `zoom` is **two-way bound** with `v-model:zoom` — the readout tracks it as you scroll, and **Fit** drives the imperative handle (`zoomToFit()`), which echoes the new zoom back into the binding. Each node body is your own `<template #node>` fragment, rendered per node through the reactive `node` portal slot. See the [full API](/guide/rete) for the complete prop / event / handle surface.
+
+## One source, six outputs
+
+You author the component **once** as a `.rozie` file:
+
+<<< ../../packages/ui/rete/src/FlowCanvas.rozie{html}[FlowCanvas.rozie — the single source]
+
+…and Rozie compiles it to six idiomatic, framework-native components. Switch the tabs to see the **actual generated output** for each target (this is exactly what ships in `@rozie-ui/rete-{react,vue,svelte,angular,solid,lit}`):
+
+::: code-group
+
+<<< ../../packages/ui/rete/packages/react/src/FlowCanvas.tsx[React]
+<<< ../../packages/ui/rete/packages/vue/src/FlowCanvas.vue[Vue]
+<<< ../../packages/ui/rete/packages/svelte/src/FlowCanvas.svelte[Svelte]
+<<< ../../packages/ui/rete/packages/angular/src/FlowCanvas.ts[Angular]
+<<< ../../packages/ui/rete/packages/solid/src/FlowCanvas.tsx[Solid]
+<<< ../../packages/ui/rete/packages/lit/src/FlowCanvas.ts[Lit]
+
+:::
+
+Each is a real, idiomatic component for its framework — React `forwardRef` + hooks, Vue `<script setup>` + `defineModel`, Svelte 5 runes, an Angular standalone component with `model()` signals, a Solid component, and a Lit custom element. Same props, same 7 events, same 12-verb imperative handle, same reactive `node` portal slot, all from the one source above — and the engine (graph model, pan/zoom/drag, drag-to-connect) is Rete.js on every target.
+
+## See also
+
+- [FlowCanvas — showcase & API](/guide/rete) — install, quick starts for all six frameworks, the events, the two-way zoom binding, the imperative handle, and the `node` slot.
+- [Node-flow editor libraries comparison](/guide/rete-comparison) — how `@rozie-ui/rete` stacks up against React Flow / Vue Flow / Svelte Flow / Foblex (and the Solid / Lit gap it closes).
+
+<style scoped>
+.flow-live {
+  margin: 1.5rem 0;
+  padding: 1rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  background: var(--vp-c-bg-soft);
+}
+.flow-live__controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.4rem;
+  margin-bottom: 0.85rem;
+}
+.flow-live__controls button {
+  font: inherit;
+  font-size: 0.82rem;
+  padding: 0.3rem 0.7rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 7px;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  transition: border-color 0.15s, background 0.15s;
+}
+.flow-live__controls button:hover {
+  border-color: var(--vp-c-brand-1);
+  color: var(--vp-c-brand-1);
+}
+.flow-live__controls button.flow-live__primary {
+  background: var(--vp-c-brand-1);
+  border-color: var(--vp-c-brand-1);
+  color: #fff;
+  font-weight: 600;
+}
+.flow-live__sep {
+  width: 1px;
+  align-self: stretch;
+  margin: 0 0.3rem;
+  background: var(--vp-c-divider);
+}
+.flow-live__stage {
+  background: var(--vp-c-bg);
+  border-radius: 8px;
+  overflow: hidden;
+}
+.flow-live__node {
+  padding: 0.5rem 0.75rem;
+  font-size: 0.8125rem;
+  color: var(--vp-c-text-1);
+}
+.flow-live__node[data-kind="in"] strong { color: #047857; }
+.flow-live__node[data-kind="out"] strong { color: #b91c1c; }
+.flow-live__node.is-selected { background: rgba(59, 130, 246, 0.1); }
+.flow-live__readout {
+  min-height: 1.4rem;
+  margin-top: 0.6rem;
+  font-size: 0.82rem;
+  color: var(--vp-c-text-2);
+}
+</style>