@particle-academy/fancy-flow 0.48.0 → 0.49.0

package/dist/screens.d.cts

@@ -1,6 +1,6 @@
-export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-CY3_vHSg.cjs';
+export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-CFSMlCqi.cjs';
 import 'react';
-import './types-Jx1TwehV.cjs';
+import './types-7cXcSQlx.cjs';
 import '@xyflow/react';
 
 /**

package/dist/screens.d.ts

@@ -1,6 +1,6 @@
-export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-DGW6t-80.js';
+export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-DRgjeWJ7.js';
 import 'react';
-import './types-Jx1TwehV.js';
+import './types-7cXcSQlx.js';
 import '@xyflow/react';
 
 /**

package/dist/screens.js

@@ -1,8 +1,8 @@
-import { FlowViewer } from './chunk-UVP43XU2.js';
-export { FlowViewer } from './chunk-UVP43XU2.js';
-import './chunk-DRRZEAYB.js';
+import { FlowViewer } from './chunk-AVRGZFXG.js';
+export { FlowViewer } from './chunk-AVRGZFXG.js';
+import './chunk-6XKR65XM.js';
 import './chunk-UEOE6B52.js';
-import './chunk-MJ3A3TAI.js';
+import './chunk-6FP3F5YR.js';
 import './chunk-F5RPRB7A.js';
 import './chunk-USL4FMFU.js';
 import { registerSchemaComponents } from '@particle-academy/fancy-screens';

package/dist/{types-Jx1TwehV.d.ts → types-7cXcSQlx.d.cts}

@@ -152,6 +152,23 @@ type BaseNodeData = {
     status?: NodeRunStatus;
     /** Optional human-readable status detail (e.g. error message, current step). */
     statusText?: string;
+    /**
+     * Announced to a person just BEFORE this node runs — "Starting the deep
+     * analysis". Authored on the node, so a graph narrates itself without the
+     * host writing any per-node reporting code.
+     *
+     * Optional on purpose. Most nodes in a real graph are plumbing, and a run
+     * that narrates all of them buries the two or three steps anyone follows.
+     */
+    startingMsg?: string;
+    /**
+     * Announced AFTER this node finishes — "Analysis complete".
+     *
+     * Emitted only when the node SUCCEEDS. A completion message printed after a
+     * failure tells a human the opposite of what happened, in the part of the UI
+     * they trust most; failures report through `node-status` and `log`.
+     */
+    stoppingMsg?: string;
     /** Per-node accent override, e.g. for theming a custom subclass. */
     color?: string;
     /** Input ports rendered on the node. Defaults vary by kind. */
@@ -198,6 +215,21 @@ type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
     abort: (reason?: string) => never;
     /** Lets the executor stream status updates and partial outputs. */
     emit: (event: RunEvent) => void;
+    /**
+     * The registry THIS run is executing against.
+     *
+     * Handed down so an executor that starts a NESTED run gives the child the
+     * same executors as the parent. `subflow` previously ran its child against
+     * `config.executors ?? {}` — an empty registry unless the graph happened to
+     * carry one — so a host kind resolved at top level and vanished one level
+     * down, and a host that had REPLACED a builtin got the package's version in
+     * the child. Same graph, different behaviour by nesting depth, reported
+     * against the PHP twin as fancy-flow-php#7.
+     *
+     * Inheriting from the context rather than from a parameter is what makes it
+     * unforgettable: any future nesting executor gets it without opting in.
+     */
+    executors?: ExecutorRegistry;
     /**
      * How deep this run is nested. 0 for a top-level run; `subflow` passes
      * depth + 1 to its child, so runaway recursion can be reported by name
@@ -223,6 +255,24 @@ type RunEvent = {
     nodeId: string;
     status: NodeRunStatus;
     text?: string;
+}
+/**
+ * A human-facing announcement a node makes around its own execution, from
+ * `data.startingMsg` / `data.stoppingMsg`. Opt-in per node: most nodes in a
+ * real graph are plumbing, and narrating all of them buries the few steps a
+ * person cares about.
+ *
+ * Deliberately NOT folded into `node-status.text`, which already carries
+ * "skipped", "resumed", "lane", "annotation" and raw error strings. Those are
+ * diagnostics; these are addressed to a person. A consumer rendering a
+ * progress feed cannot be asked to guess which is which — that is how an
+ * error string ends up shown to a user as a status update.
+ */
+ | {
+    type: "node-message";
+    nodeId: string;
+    phase: "start" | "end";
+    message: string;
 } | {
     type: "node-output";
     nodeId: string;

package/dist/{types-Jx1TwehV.d.cts → types-7cXcSQlx.d.ts}

@@ -152,6 +152,23 @@ type BaseNodeData = {
     status?: NodeRunStatus;
     /** Optional human-readable status detail (e.g. error message, current step). */
     statusText?: string;
+    /**
+     * Announced to a person just BEFORE this node runs — "Starting the deep
+     * analysis". Authored on the node, so a graph narrates itself without the
+     * host writing any per-node reporting code.
+     *
+     * Optional on purpose. Most nodes in a real graph are plumbing, and a run
+     * that narrates all of them buries the two or three steps anyone follows.
+     */
+    startingMsg?: string;
+    /**
+     * Announced AFTER this node finishes — "Analysis complete".
+     *
+     * Emitted only when the node SUCCEEDS. A completion message printed after a
+     * failure tells a human the opposite of what happened, in the part of the UI
+     * they trust most; failures report through `node-status` and `log`.
+     */
+    stoppingMsg?: string;
     /** Per-node accent override, e.g. for theming a custom subclass. */
     color?: string;
     /** Input ports rendered on the node. Defaults vary by kind. */
@@ -198,6 +215,21 @@ type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
     abort: (reason?: string) => never;
     /** Lets the executor stream status updates and partial outputs. */
     emit: (event: RunEvent) => void;
+    /**
+     * The registry THIS run is executing against.
+     *
+     * Handed down so an executor that starts a NESTED run gives the child the
+     * same executors as the parent. `subflow` previously ran its child against
+     * `config.executors ?? {}` — an empty registry unless the graph happened to
+     * carry one — so a host kind resolved at top level and vanished one level
+     * down, and a host that had REPLACED a builtin got the package's version in
+     * the child. Same graph, different behaviour by nesting depth, reported
+     * against the PHP twin as fancy-flow-php#7.
+     *
+     * Inheriting from the context rather than from a parameter is what makes it
+     * unforgettable: any future nesting executor gets it without opting in.
+     */
+    executors?: ExecutorRegistry;
     /**
      * How deep this run is nested. 0 for a top-level run; `subflow` passes
      * depth + 1 to its child, so runaway recursion can be reported by name
@@ -223,6 +255,24 @@ type RunEvent = {
     nodeId: string;
     status: NodeRunStatus;
     text?: string;
+}
+/**
+ * A human-facing announcement a node makes around its own execution, from
+ * `data.startingMsg` / `data.stoppingMsg`. Opt-in per node: most nodes in a
+ * real graph are plumbing, and narrating all of them buries the few steps a
+ * person cares about.
+ *
+ * Deliberately NOT folded into `node-status.text`, which already carries
+ * "skipped", "resumed", "lane", "annotation" and raw error strings. Those are
+ * diagnostics; these are addressed to a person. A consumer rendering a
+ * progress feed cannot be asked to guess which is which — that is how an
+ * error string ends up shown to a user as a status update.
+ */
+ | {
+    type: "node-message";
+    nodeId: string;
+    phase: "start" | "end";
+    message: string;
 } | {
     type: "node-output";
     nodeId: string;

package/dist/{types-BO8TgI2M.d.cts → types-BtMOnb9I.d.cts}

@@ -1,5 +1,5 @@
 import { ReactNode, ComponentType } from 'react';
-import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-Jx1TwehV.cjs';
+import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-7cXcSQlx.cjs';
 import { NodeProps } from '@xyflow/react';
 import { P as PauseAwaiting } from './pause-9iT4tCEV.cjs';
 

package/dist/{types-DJAmfiJC.d.ts → types-CDgIIj4c.d.ts}

@@ -1,5 +1,5 @@
 import { ReactNode, ComponentType } from 'react';
-import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-Jx1TwehV.js';
+import { F as FlowGraph, a as FlowNode, P as PortDescriptor, N as NodeExecutor } from './types-7cXcSQlx.js';
 import { NodeProps } from '@xyflow/react';
 import { P as PauseAwaiting } from './pause-9iT4tCEV.js';
 

package/dist/ux.cjs

@@ -9282,6 +9282,7 @@ async function runFlow(graph, executors, onEvent = () => {
         continue;
       }
       onEvent({ type: "node-status", nodeId: node.id, status: "running" });
+      announce(onEvent, node, "start");
       const inputs = collectInputs(node, incoming, portValues, initialInputs);
       const exec = pickExecutor(executors, node);
       if (!exec) {
@@ -9300,6 +9301,7 @@ async function runFlow(graph, executors, onEvent = () => {
               throw new Error(reason ?? "aborted");
             },
             emit: onEvent,
+            executors,
             depth,
             run
           })
@@ -9312,6 +9314,7 @@ async function runFlow(graph, executors, onEvent = () => {
         }
         completed.add(node.id);
         onEvent({ type: "node-status", nodeId: node.id, status: "done" });
+        announce(onEvent, node, "end");
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         errors.push(msg);
@@ -9370,7 +9373,10 @@ function collectInputs(node, incoming, portValues, initial) {
 function pickExecutor(executors, node) {
   if (executors[node.id]) return executors[node.id];
   if (node.type && executors[node.type]) return executors[node.type];
-  const kind = node.type ? getNodeKind(node.type) : null;
+  const declared = node.data?.kind;
+  const kindName = typeof declared === "string" && declared !== "" ? declared : node.type;
+  if (kindName && kindName !== node.type && executors[kindName]) return executors[kindName];
+  const kind = kindName ? getNodeKind(kindName) : null;
   if (kind) {
     for (const id2 of kindIds(kind)) {
       if (executors[id2]) return executors[id2];
@@ -9392,6 +9398,14 @@ function activatedPorts(node, result) {
   const declared = resolveNodePorts(node, kind).outputs?.map((p) => p.id);
   return { ports: declared?.length ? declared : ["out"], value: result };
 }
+function announce(onEvent, node, phase) {
+  const data = node.data;
+  const raw = phase === "start" ? data?.startingMsg : data?.stoppingMsg;
+  if (typeof raw !== "string") return;
+  const message = raw.trim();
+  if (message === "") return;
+  onEvent({ type: "node-message", nodeId: node.id, phase, message });
+}
 
 // src/registry/subflow.ts
 var DEFAULT_MAX_DEPTH = 8;
@@ -9445,7 +9459,10 @@ var subflowExecutor = async (ctx) => {
   };
   const result = await runFlow(
     child,
-    config.executors ?? {},
+    // Inherit the parent's registry, then let the graph layer its own on top.
+    // The inherited half is the fix; the layered half keeps a graph that
+    // deliberately hands its child extra or different executors working.
+    { ...ctx.executors ?? {}, ...config.executors ?? {} },
     forward,
     {
       initialInputs: config.inputs ?? {