@particle-academy/fancy-flow 0.65.2 → 0.66.1

package/README.md

@@ -339,9 +339,11 @@ function MyEditor() {
 
 ## Node kinds
 
-27 builtins, grouped by category. Ids are namespaced (`@particle-academy/<name>`)
+31 builtins, grouped by category. Ids are namespaced (`@particle-academy/<name>`)
 and every bare name below is a permanent alias, so graphs saved against either
-keep resolving.
+keep resolving. The count is checked against the registry by a test — a
+hand-maintained mirror that nothing compares is the defect this kit keeps
+finding, so it is compared.
 
 | Category | Kinds |
 |---|---|
@@ -352,7 +354,8 @@ keep resolving.
 | `data` | `variable`, `memory_store`, `data_store` |
 | `io` | `api_request`, `webhook_out` |
 | `output` | `output`, `log` |
-| `layout` / `annotation` | `lane`, `note` — visual only, never executed |
+| `io` (terminal) | `terminal_run`, `terminal_send`, `terminal_await` — inside a terminal lane |
+| `layout` / `annotation` | `lane`, `terminal_lane`, `note` — visual only, never executed |
 
 Don't hand-copy this list into generated graphs — it moves. Enumerate at
 runtime with `getNodeKind()` / the registry, or ask the Fancy MCP's `list_nodes`.
@@ -363,6 +366,100 @@ Custom nodes plug in via xyflow's standard `nodeTypes` prop:
 <FlowCanvas nodeTypes={{ ...defaultNodeTypes, myNode: MyCustomNode }} ... />
 ```
 
+## Terminal lanes
+
+A **terminal lane** owns one running terminal for the length of a workflow run,
+so a graph can drive an interactive process — including an agent TUI like Claude
+Code or Codex — instead of only firing one-shot commands.
+
+Three promises, and all three are about WHEN rather than what:
+
+1. **One terminal per lane**, however many nodes are inside it. Two shells look
+   exactly like one that forgot a `cd`.
+2. **It opens at the first terminal node**, not at run start. A lane drawn
+   around nodes that mostly do other things costs nothing until something uses
+   it.
+3. **It stays open until the run finishes**, including when the run FAILS. A
+   leaked PTY looks like nothing at all until the machine is full of them.
+
+Membership is the canvas's own `parentId`, which already persists into the
+`WorkflowSchema` — so a headless runtime resolves exactly the grouping a person
+drew, with no second association to keep in step.
+
+### The nodes
+
+| Kind | For |
+|---|---|
+| `terminal_run` | Run a shell command and wait for its **exit code**. Shell only. |
+| `terminal_send` | Type at whatever is running, without waiting. |
+| `terminal_await` | Wait until the output matches. Returns capture groups in regex mode. |
+
+`terminal_run` is the shell node and `terminal_send` + `terminal_await` are the
+TUI pair, because a terminal is two different things depending on what is in it.
+A shell answers and returns to a prompt, so the useful unit is "run this, tell me
+what it said and whether it worked". A TUI never finishes — there is no exit code
+to wait for — so there is only text going in and text coming out.
+
+Matching runs against the **accumulated** output with escape sequences already
+stripped, so you match what you SEE and a pattern split across PTY chunks still
+resolves. Output that arrived before an await started is not lost. A wait
+consumes through its match, so the same pattern does not resolve twice on one
+line.
+
+Three outcomes are reported distinctly — matched, timed out, and *the process
+exited*. Collapsing the last two is how a dead shell gets reported as "timed out
+waiting for X", sending whoever debugs it to lengthen a timeout on a process
+that is not running.
+
+### Providing the terminal
+
+Core declares the contract and imports no PTY — `node-pty` is a native addon
+that would break every browser build. Same arrangement as `registerLlmClient`:
+
+```ts
+import { registerTerminalHost } from "@particle-academy/fancy-flow/registry";
+
+registerTerminalHost({
+  open: async ({ command, cwd, env, cols, rows }) => {
+    const pty = spawnYourPty(command ?? defaultShell(), { cwd, env, cols, rows });
+    return {
+      id: pty.pid.toString(),
+      write: (data) => pty.write(data),
+      onData: (listener) => { pty.onData(listener); return () => pty.dispose(); },
+      exited: new Promise((r) => pty.onExit(({ exitCode, signal }) => r({ exitCode, signal }))),
+      close: () => pty.kill(),
+    };
+  },
+});
+```
+
+There is deliberately **no `waitForOutput(pattern)` in the contract**. Matching
+is derivable from `onData`, so putting it in the contract would mean every host
+implements it — two implementations of one agreed rule, which is how matching
+bugs end up differing per host. Core owns matching; the host owns the process.
+
+### The fancy-term-host adapter
+
+If you already run `@particle-academy/fancy-term-host`, the adapter is on its
+own subpath:
+
+```ts
+import { terminalManager } from "@particle-academy/fancy-term-host";
+import { useFancyTermHost } from "@particle-academy/fancy-flow/terminal/fancy-term-host";
+
+useFancyTermHost(terminalManager(), { cwd: "/srv/app" });
+```
+
+It takes the backend as an **argument** rather than importing the package.
+`fancy-term-host` requires `node-pty` as a peer and imports it at module scope,
+so depending on it here — even for types — would put a native build in every
+fancy-flow install, including browser consumers who will never open a terminal.
+Anyone who wants this adapter already holds a backend, so passing it in costs
+them one argument and costs everyone else nothing.
+
+**`fancy-flow-php` does not have this feature and is not going to.** It needs
+desktop execution, which is not what the PHP runtime is for.
+
 ## LLM adapters
 
 `llm_router` (alias `llm_branch`) asks a model to pick one of a node's declared

package/dist/{FlowViewer-BI_AyyvU.d.ts → FlowViewer-BCc_BvuD.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { CSSProperties, ReactNode } from 'react';
-import { F as FlowGraph, a as FlowNode } from './types-JFYjPJAG.js';
+import { F as FlowGraph, a as FlowNode } from './types-B-Syk9-M.js';
 
 /** Outcome of one node in a run, for annotating the graph after the fact. */
 type FlowNodeStatus = "ok" | "running" | "failed" | "skipped" | "pending";

package/dist/{FlowViewer-DABx-6A-.d.cts → FlowViewer-CoAJ3o52.d.cts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { CSSProperties, ReactNode } from 'react';
-import { F as FlowGraph, a as FlowNode } from './types-JFYjPJAG.cjs';
+import { F as FlowGraph, a as FlowNode } from './types-B-Syk9-M.cjs';
 
 /** Outcome of one node in a run, for annotating the graph after the fact. */
 type FlowNodeStatus = "ok" | "running" | "failed" | "skipped" | "pending";

package/dist/{HumanPrompt-Bpp3JiVH.d.cts → HumanPrompt--pXDOyYC.d.cts}

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { F as FlowGraph } from './types-JFYjPJAG.cjs';
-import { C as ConfigField } from './types-D71SKA5A.cjs';
+import { F as FlowGraph } from './types-B-Syk9-M.cjs';
+import { C as ConfigField } from './types-C2ATTmjN.cjs';
 
 /** What a host renderer is handed. */
 type ConfigFieldRenderContext = {

package/dist/{HumanPrompt-BKThiyjB.d.ts → HumanPrompt-DXm_FP9z.d.ts}

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { F as FlowGraph } from './types-JFYjPJAG.js';
-import { C as ConfigField } from './types-Ckhz-YwC.js';
+import { F as FlowGraph } from './types-B-Syk9-M.js';
+import { C as ConfigField } from './types-VunLGqrn.js';
 
 /** What a host renderer is handed. */
 type ConfigFieldRenderContext = {