@theclearsky/react-blender-nodes 0.0.11 → 0.0.13

package/README.md

@@ -7,12 +7,67 @@
   a flexible and customizable node-based graph editor for web applications.
 </p>
 
+> **Note**: This project is not affiliated with Blender Foundation. If you find
+> Blender useful, consider
+> [donating to support their work](https://fund.blender.org/).
+
 <p align="center">
   <a href="https://bundlejs.com/?q=%40theclearsky%2Freact-blender-nodes"><img src="https://deno.bundlejs.com/?q=%40theclearsky%2Freact-blender-nodes&badge=detailed&badge-style=for-the-badge" alt="spring-easing's badge" /></a>
 </p>
 
 ![React Blender Nodes Banner](./docs/screenshots/banner.png)
 
+## How these projects fit together
+
+This library is the engine at the centre of a small family: two plugins extend
+it, and one application proves it in anger.
+
+```text
+                react-blender-nodes  ·  MIT  ·  published
+                            T H E   E N G I N E
+     ┌────────────────────────────────────────────────────────────┐
+     │  ◀── this package                                          │
+     │  A Blender-style node-graph editor for React.              │
+     │  Typed handles · validate → plan → apply state · node      │
+     │  groups · loops & switches · graph compiler + runner ·     │
+     │  import / export                                           │
+     └──────┬──────────────────────┬────────────────────────┬─────┘
+            │                      │                        │
+            │ peerDependency       │ peerDependency         │ file:
+            │ >=0.0.13 <1          │ >=0.0.13 <1            │ dependency
+            │                      │ (via /contract —       │
+            ▼                      ▼  React-free)           │
+  ┌──────────────────────┐  ┌──────────────────────┐        │
+  │ …-timeline           │  │ …-codegen            │        │
+  │ AGPL-3.0 · published │  │ AGPL-3.0 · published │        │
+  ├──────────────────────┤  ├──────────────────────┤        │
+  │ Keyframed CURVES and │  │ Compiles a graph into│        │
+  │ a transport. A curve │  │ a standalone,        │        │
+  │ becomes a live signal│  │ dependency-free      │        │
+  │ the running graph    │  │ runGraph module.     │        │
+  │ can read.            │  │ No React at runtime. │        │
+  └──────────┬───────────┘  └──────────────────────┘        │
+             │                                              │
+             │ file: dependency                             │
+             └───────────────────┬──────────────────────────┘
+                                 ▼
+     ┌────────────────────────────────────────────────────────────┐
+     │  react-blender-nodes-sound  ·  AGPL-3.0  ·  private app    │
+     │                  T H E   A P P L I C A T I O N             │
+     ├────────────────────────────────────────────────────────────┤
+     │  Here the nodes ARE the audio graph (Tone.js / Web Audio): │
+     │  draw a waveform and hear it · gate-driven envelopes ·     │
+     │  16-key polyphony · timeline curves automating any         │
+     │  parameter while it plays · a spectrally-modelled          │
+     │  instrument library                                        │
+     └────────────────────────────────────────────────────────────┘
+```
+
+An arrow points from a package **to the package that depends on it**. This
+library stays MIT so anyone can build on it; the plugins and the app are
+AGPL-3.0-only. The two plugins never import each other — the app is the only
+place they meet.
+
 ## Quick Links
 
 - [![Storybook](https://img.shields.io/badge/Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white)](https://theclearsky.github.io/react-blender-nodes/?path=/story/organisms-fullgraph--with-runner) -
@@ -34,6 +89,15 @@ system with automatic inference, complex data validation, and comprehensive
 connection validation to ensure your node graphs are always type-safe and
 error-free.
 
+Beyond editing, the library can **execute** your graphs with a built-in runner
+and timeline debugger — or hand them to pluggable **run targets**, including a
+separate AGPL-3.0-only codegen plugin that compiles them to standalone
+JavaScript/TypeScript — compose reusable **node groups**, build control flow
+with first-class **loops** and **switches** (rendered as visual zones), edit
+those structures and node types through in-canvas **drawers**, and step backward
+and forward through every change with full **undo/redo** history. Graph state
+and execution recordings can be exported to and imported from JSON.
+
 ## Quick Start
 
 ### Installation
@@ -51,8 +115,8 @@ import {
   makeStateWithAutoInfer,
   makeTypeOfNodeWithAutoInfer,
   makeDataTypeWithAutoInfer,
-} from 'react-blender-nodes';
-import 'react-blender-nodes/style.css';
+} from '@theclearsky/react-blender-nodes';
+import '@theclearsky/react-blender-nodes/style.css';
 
 function MyNodeEditor() {
   // Define data types with auto-infer for type safety
@@ -229,82 +293,220 @@ your graph into an execution plan and runs it — with full debugging support.
 
 ![Loop Execution Timeline](./docs/screenshots/execution-timeline-loop-iterations.png)
 
-### Usage
+### ⚡ Codegen & Pluggable Run Targets — Export Your Graph as Code
+
+![Codegen — generate a standalone runGraph() live from the graph](./docs/screenshots/codegen-export.png)
+
+The in-process runner is just the default **run target**. The Run button is a
+split control: register your own named targets, use the built-in
+`jsonIrRunTarget` to export the execution plan as a JSON intermediate
+representation, or install the **separate codegen plugin** to compile a graph
+into a **standalone, dependency-free function** — `runGraph(...)` — in
+JavaScript or typed TypeScript.
+
+- **Export as code (plugin)**: `codegenJsRunTarget` / `codegenTsRunTarget` from
+  [`@theclearsky/react-blender-nodes-codegen`](https://github.com/TheClearSky/react-blender-nodes-codegen)
+  (AGPL-3.0-only, published separately) emit a self-contained `runGraph()` (TS
+  adds typed parameters, a return type, and value casts). Built into this
+  package: `jsonIrRunTarget` exports the execution plan as JSON, and the default
+  `inProcessRunTarget` runs the graph live and feeds the timeline.
+- **Clean signature from Graph I/O**: declare root **Graph Input** / **Graph
+  Output** nodes and their handle names become the function's parameters and
+  returned-object keys — an all-inlined graph compiles to a tidy
+  `function runGraph(a, b) { … return { out, flag }; }` with no plumbing
+  arguments.
+- **Opt-in optimization passes**: by default the codegen targets emit a
+  faithful, threaded `runGraph`. Enable the codegen-v2 passes per target to get
+  the clean output — `assumePureImplementations` runs dead-code elimination
+  (drops branches no output depends on); unconnected inputs always inline their
+  current value; and `analyzeImplementations` makes value-API nodes whose
+  implementation reads inputs through the exported `readInput` intrinsic
+  **auto-emit inline as expressions** instead of threading through an
+  implementations argument.
+- **Pluggable contract**: a `RunTarget` is either an `execute` target (produces
+  an `ExecutionRecord`, drives the timeline, and may support stepping) or an
+  `artifact` target (produces a string/download). Register them via the
+  `runTargets` prop and pick the default with `defaultRunTargetId`.
 
 ```tsx
-import { FullGraph, useFullGraph } from 'react-blender-nodes';
-import { makeFunctionImplementationsWithAutoInfer } from 'react-blender-nodes';
-
-// Define what each node type does when executed
-const functionImplementations = makeFunctionImplementationsWithAutoInfer({
-  myNodeType: async ({ inputs }) => {
-    // Process inputs and return outputs
-    return { outputHandle: inputs.inputHandle * 2 };
-  },
-});
+import { FullGraph, jsonIrRunTarget } from '@theclearsky/react-blender-nodes';
+// Code generation is a separate, AGPL-3.0-only plugin:
+import {
+  codegenJsRunTarget,
+  codegenTsRunTarget,
+} from '@theclearsky/react-blender-nodes-codegen';
 
-// Pass implementations to FullGraph to enable the runner
+// The Run button becomes a split control listing every registered target.
 <FullGraph
   state={state}
   dispatch={dispatch}
   functionImplementations={functionImplementations}
+  runTargets={[codegenJsRunTarget, codegenTsRunTarget, jsonIrRunTarget]}
 />;
 ```
 
-### useNodeRunner Hook
+### 🔁 Loops, 🔀 Switches & Zones
+
+Build control flow directly on the canvas. Loops and switches are first-class
+structures backed by dedicated standard nodes, and each renders as a labelled
+**zone** — a frame polygon drawn around the nodes it contains.
+
+- **Loops**: Drop a loop-start / loop-stop / loop-end node triplet to define an
+  iterative body. The runner compiles the body into a `LoopExecutionBlock` and
+  records every iteration, with a configurable max-iteration safety limit.
+- **Switches**: A switch-start / switch-end pair routes execution down a `true`
+  or `false` branch based on a condition handle. The compiler resolves the taken
+  branch and skips the other, surfacing skipped nodes on the canvas.
+- **Zones**: System zones are created and re-discovered automatically as you add
+  structures or change connections. Each zone tracks the body nodes inside it
+  and can enforce connection boundaries (blocking edges that cross in or out).
+  Zones are scope-local, so structures inside a node group get their own zones.
+- **Nesting**: Loops, switches, and groups can be nested inside one another;
+  zone discovery and the compiler resolve nested structures recursively.
+
+### 🪟 In-Canvas Editors
+
+Structures and node types are edited through slide-out drawers, dispatched via
+the graph state and tracked on `state.activeDrawer`:
+
+- **Node Type editor** (`editNodeType`): rename a node type, change its header
+  color, and add, remove, or reorder its inputs and outputs.
+- **Loop editor** (`editLoop`): configure the handles carried through the loop
+  triplet, organized into levels.
+- **Switch editor** (`editSwitch`): configure the handles carried through the
+  switch pair across its true/false branches.
+- **Graph I/O editor** (`editGraphInput` / `editGraphOutput`): rename, reorder,
+  add, or delete the handles of a root **Graph Input / Output** node — the
+  graph's I/O boundary, whose handle names define the `runGraph(...)` signature
+  used by codegen.
+
+![Graph I/O editor — rename, reorder, and add graph input/output handles](./docs/screenshots/graph-io-editor.png)
+
+The Node Type / Node Group editor (`editNodeType`) edits a type's name, header
+color, and its full input/output list — including grouping handles into
+collapsible **panels** and drag-reordering them:
+
+![Node type editor — name, header color, panelled inputs (Transform, Color Settings), outputs, drag-reorder](./docs/screenshots/editor-nodetype.png)
+
+Deleting a handle or channel that carries connections opens a **deletion
+review** — it previews exactly which connections would break (with an expandable
+mini-map highlighting them) and lets you include or exclude each deletion before
+committing:
+
+![Deletion review — preview of the connections each handle deletion will break](./docs/screenshots/editor-deletion-review.png)
+
+### ↩️ Undo / Redo History
+
+Every structural edit is recorded in an Immer-patch-based undo/redo history, so
+users can freely step backward and forward.
+
+- **Patch-based**: history stores forward and inverse Immer patches per entry —
+  compact and exact, with a configurable `maxSize`.
+- **Smart undoability**: viewport changes, navigation, drawer open/close, and
+  selection-only ReactFlow updates are intentionally _not_ recorded.
+- **Batching**: `BEGIN_BATCH` / `END_BATCH` collapse a sequence of related edits
+  (e.g. a multi-node drag) into a single undo step.
+- **Keyboard shortcuts**: `<FullGraph>` listens for `Ctrl+Z` / `Ctrl+Shift+Z` /
+  `Ctrl+Y` by default (toggle with `enableUndoRedoShortcuts`).
+- **Serializable**: history can be exported and re-imported alongside graph
+  state (non-serializable patch values such as Zod schemas are stripped).
+
+### 📡 Graph Event Stream
+
+For tests, dev tooling, and telemetry, subscribe to a single unified
+observability stream via `onGraphEvent`. Reducer-layer events (`action:applied`
+/ `action:rejected` / `state:committed`) carry typed payloads (e.g. an
+`action:rejected` event carries the original `ValidationError` so you can switch
+on `.code`), and UI-layer events (`ui:drag:ended` / `ui:delete:attempted` /
+`ui:state:imported` / `ui:recording:imported`) cover moments that bypass the
+reducer. Pass the _same_ handler to both
+`useFullGraph(initialState, { onGraphEvent })` and
+`<FullGraph onGraphEvent={...} />` to receive every event.
 
-For advanced control over graph execution, use the `useNodeRunner` hook directly
-instead of relying on the built-in runner UI:
+### Usage
 
 ```tsx
-import { FullGraph, useFullGraph, useNodeRunner } from 'react-blender-nodes';
+import {
+  FullGraph,
+  useFullGraph,
+  makeFunctionImplementationsWithAutoInfer,
+} from '@theclearsky/react-blender-nodes';
+
+// Define what each node type does when executed.
+// An implementation receives positional args: (inputs, outputs, context).
+// `inputs` is a ReadonlyMap keyed by handle *name*; read a connected value
+// via inputs.get('Name')?.connections[0]?.value. Return a Map of output
+// handle *names* to computed values (sync Map or Promise<Map>).
+const functionImplementations = makeFunctionImplementationsWithAutoInfer({
+  myNodeType: async (inputs) => {
+    const value = Number(inputs.get('Input')?.connections[0]?.value ?? 0);
+    return new Map([['Output', value * 2]]);
+  },
+});
 
 function MyExecutableGraph() {
   const { state, dispatch } = useFullGraph(initialState);
 
-  const {
-    // State
-    runnerState, // 'idle' | 'compiling' | 'running' | 'paused' | 'completed' | 'errored'
-    nodeVisualStates, // Map<nodeId, 'idle' | 'running' | 'completed' | 'errored' | 'skipped'>
-    executionRecord, // Full execution recording with per-step timing and I/O snapshots
-    currentStepIndex, // Index of the currently active/viewed step
-
-    // Actions
-    run, // Start execution (mode-aware: instant or step-by-step)
-    pause, // Pause during step-by-step execution
-    resume, // Resume paused step-by-step execution
-    step, // Advance one step (starts a new run if idle)
-    stop, // Abort the current execution
-    reset, // Clear all execution state back to idle
-    replayTo, // Seek to a specific step index in a completed recording
-    loadRecord, // Load an imported ExecutionRecord (validates against current graph)
-
-    // Settings
-    mode, // Current execution mode: 'instant' | 'stepByStep'
-    setMode, // Switch execution mode
-    maxLoopIterations, // Max iterations before a loop is force-stopped
-    setMaxLoopIterations,
-  } = useNodeRunner({
-    state,
-    functionImplementations,
-    options: { maxLoopIterations: 100 },
-  });
+  // Pass implementations to FullGraph to enable the runner
+  return (
+    <FullGraph
+      state={state}
+      dispatch={dispatch}
+      functionImplementations={functionImplementations}
+    />
+  );
+}
+```
+
+### Controlling execution
+
+Execution is driven through `FullGraph`'s runner props — the runner hook itself
+(`useNodeRunner`) is internal to `FullGraph` and is not exported. Register run
+targets, pick the default, seed the root Graph Input, and observe or control the
+execution record:
+
+```tsx
+import { useState } from 'react';
+import {
+  FullGraph,
+  useFullGraph,
+  jsonIrRunTarget,
+  type ExecutionRecord,
+} from '@theclearsky/react-blender-nodes';
+
+function MyExecutableGraph() {
+  const { state, dispatch } = useFullGraph(initialState);
+  const [record, setRecord] = useState<ExecutionRecord | undefined>();
 
   return (
-    <div>
-      <button onClick={run}>Run</button>
-      <button onClick={step}>Step</button>
-      <button onClick={pause}>Pause</button>
-      <button onClick={resume}>Resume</button>
-      <button onClick={stop}>Stop</button>
-      <button onClick={reset}>Reset</button>
-      <p>Status: {runnerState}</p>
-      <FullGraph state={state} dispatch={dispatch} />
-    </div>
+    <FullGraph
+      state={state}
+      dispatch={dispatch}
+      functionImplementations={functionImplementations}
+      runTargets={[jsonIrRunTarget]} // the Run button becomes a split control
+      rootInputs={{ a: 2, b: 3 }} // seeds the root Graph Input by handle name (or id)
+      executionRecord={record} // controlled record — you own its lifecycle
+      onExecutionRecordChange={setRecord}
+    />
   );
 }
 ```
 
+For headless use — CI checks, tooling, or inspecting what the runner will do —
+compile a graph directly and serialize the plan:
+
+```ts
+import {
+  compile,
+  serializeExecutionPlan,
+} from '@theclearsky/react-blender-nodes';
+
+const plan = compile(state, functionImplementations, {
+  maxLoopIterations: 100,
+});
+console.log(JSON.stringify(serializeExecutionPlan(plan), null, 2));
+```
+
 ### Import/Export & Automatic Repair
 
 Graph state and execution recordings can be exported to JSON and re-imported
@@ -316,7 +518,7 @@ repair common issues via opt-in repair strategies.
 Pass a `repair` object to `importGraphState` to enable automatic fixes:
 
 ```tsx
-import { importGraphState } from 'react-blender-nodes';
+import { importGraphState } from '@theclearsky/react-blender-nodes';
 
 const result = importGraphState(json, {
   dataTypes: myDataTypes,
@@ -326,7 +528,8 @@ const result = importGraphState(json, {
     removeDuplicateNodeIds: true, // Deduplicate nodes with the same ID (keep first)
     removeDuplicateEdgeIds: true, // Deduplicate edges with the same ID (keep first)
     fillMissingDefaults: true, // Fill missing optional fields (viewport, etc.) with defaults
-    rehydrateDataTypeObjects: true, // Rebuild handle dataType objects from provided dataTypes
+    rehydrateDataTypeObjects: true, // Effectively always-on — the importer always rebuilds handle dataType objects from provided dataTypes (this flag is not read)
+    normalizeConnectionOrder: true, // Repack imported fan-in connection orders to contiguous 0..n-1
   },
 });
 
@@ -343,12 +546,12 @@ if (result.success) {
 Pass a `repair` object to `importExecutionRecord` for recording-specific fixes:
 
 ```tsx
-import { importExecutionRecord } from 'react-blender-nodes';
+import { importExecutionRecord } from '@theclearsky/react-blender-nodes';
 
 const result = importExecutionRecord(json, {
   repair: {
-    sanitizeNonSerializableValues: true, // Replace non-serializable values with "[non-serializable]"
-    removeOrphanSteps: true, // Remove steps referencing nodes not present in the record
+    sanitizeNonSerializableValues: true, // No-op — values parsed from JSON are already serializable; kept for API symmetry
+    removeOrphanSteps: true, // Remove malformed steps missing nodeId, nodeTypeId, or stepIndex
   },
 });
 ```
@@ -498,24 +701,52 @@ const handleShapes = [
 // Clicking a node type adds it at the cursor position
 ```
 
-## 🎨 Styling
+## 🎨 Styling & Theming
+
+The whole graph — canvas, nodes, handles, menus, runner panel, timeline, and the
+in-canvas editor drawers — is retheme-able from a single typed theme object.
+Below: the same graph under the built-in path plus two custom presets (a
+cyberpunk "Neon Heist" and a comic "Halftone Pop") — nodes, edges, run button,
+background grid, and accents all follow the active theme.
+
+![Neon Heist theme — cyberpunk magenta/cyan, glowing nodes and run button](./docs/screenshots/theme-neonheist.png)
 
-The library uses Tailwind CSS for styling and provides a dark theme that matches
-Blender's aesthetic:
+![Halftone Pop theme — comic pop-art, yellow halftone background and red accents](./docs/screenshots/theme-halftonepop.png)
+
+Import the stylesheet once; the graph ships with the default Blender-style dark
+look:
 
 ```css
-/* Import the default styles */
-@import 'react-blender-nodes/style.css';
-
-/* Customize colors using CSS variables */
-:root {
-  --primary-black: #181818;
-  --primary-dark-gray: #272727;
-  --primary-gray: #3f3f3f;
-  --primary-white: #ffffff;
-}
+@import '@theclearsky/react-blender-nodes/style.css';
+```
+
+To retheme the graph, wrap it in the optional `GraphThemeProvider` — a theme is
+a typed map of per-component/per-slot Tailwind className overrides plus a
+`reactFlow` section, deep-merged over a named preset (`'blenderDark'` |
+`'light'`):
+
+```tsx
+import {
+  FullGraph,
+  GraphThemeProvider,
+} from '@theclearsky/react-blender-nodes';
+
+<GraphThemeProvider preset='light' theme={{ node: { header: 'rounded-none' } }}>
+  <FullGraph state={state} dispatch={dispatch} />
+</GraphThemeProvider>;
 ```
 
+Without a provider the graph keeps its default look — theming is purely
+additive. The built-in presets work out of the box (their classes ship in
+`style.css`); classes you write yourself need your own Tailwind v4 build
+scanning the files that contain them. Var-driven surfaces (scrollbars, glows,
+timeline accents) are recolored through CSS variables on the `root` slot, e.g.
+`theme={{ root: '[--color-graph-menu-bg:#f5f5f5]' }}` — re-declaring the
+`@theme inline` tokens from your own CSS does NOT restyle the pre-built
+stylesheet (those utilities inline their values at build time). See
+[docs/ui/themingDoc.md](docs/ui/themingDoc.md) for the full slot map, the three
+theming mechanisms, and the portal caveats.
+
 ## 📚 Documentation
 
 ### Interactive Documentation
@@ -549,8 +780,8 @@ includes an ASCII architecture diagram, cross-feature dependency maps, and a
 | Modifying graph editor UI    | `fullGraphDoc`, `configurableNodeDoc`, `contextMenuDoc`                     |
 | Working with state/reducer   | `stateManagementDoc`, `immerDoc`, `edgesDoc`                                |
 
-See the [full index](./docs/index.md) for all 32 feature docs with relative
-links organized by tier.
+See the [full index](./docs/index.md) for all 39 documentation files with
+relative links organized by tier.
 
 ### Component API
 
@@ -576,6 +807,12 @@ interface FullGraphProps {
   executionRecord?: ExecutionRecord | null;
   /** Called whenever the execution record changes (run completes, reset, load, etc.). */
   onExecutionRecordChange?: (record: ExecutionRecord | null) => void;
+  /** Unified observability stream for UI lifecycle events (drag end, delete-attempt verdict, import outcomes). Pair with the same handler on useFullGraph for reducer-layer events. */
+  onGraphEvent?: (event: GraphEvent) => void;
+  /** Registry of custom input components keyed by DataTypeUniqueId, for data types whose underlyingType resolves to 'unsupportedDirectly'. */
+  inputComponents?: InputComponentRegistry;
+  /** Whether to listen for Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y undo/redo keyboard shortcuts. Defaults to true. */
+  enableUndoRedoShortcuts?: boolean;
 }
 ```
 
@@ -601,8 +838,6 @@ interface ConfigurableNodeProps {
   nodeResizerProps?: NodeResizerWithMoreControlsProps;
   /** Node type unique id */
   nodeTypeUniqueId?: string;
-  /** Whether to show the node open button (used by node groups) */
-  showNodeOpenButton?: boolean;
   /** Runner visual state for this node (undefined = no runner overlay) */
   runnerVisualState?: NodeVisualState;
   /** Errors from the runner for this node */