@particle-academy/fancy-flow 0.37.0 → 0.39.0

package/dist/index.d.cts

@@ -580,4 +580,72 @@ type FlowRunFeedProps = {
  */
 declare function FlowRunFeed({ entries, showHeader, title, running, className, style }: FlowRunFeedProps): react.JSX.Element;
 
-export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorAction, type FlowEditorApi, type FlowEditorBuiltins, type FlowEditorProps, type FlowEditorSlots, FlowGraph, FlowNode, type FlowNodeRenderProps, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, LaneNode, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeRunStatus, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, WorkflowSchema, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };
+/**
+ * The fancy-flow Live Contract — the run / job stream shape.
+ *
+ * Pure data, with `LiveContract` imported as a TYPE, so this adds no dependency.
+ * `FancyFlow\Laravel\LiveContract` declares the identical list and both sides
+ * assert parity.
+ *
+ * ## What makes this shape different
+ *
+ * A run emits far more than it stores. `NodeStatusChanged` and `NodeOutput`
+ * fire per node, many times a second on a wide graph — and a node's log line is
+ * not a cache entry, it is a **stream**. So the contract covers the run's
+ * DURABLE state (does this run exist, has it finished, is it waiting on a
+ * person) and deliberately leaves per-node chatter to `useFancyStream`, the
+ * same split the whiteboard makes between its document and its cursors.
+ *
+ * Get that wrong and a 40-node run invalidates the run list forty times while
+ * it executes, each one a re-fetch that tells the UI nothing it did not already
+ * learn from the stream.
+ *
+ * ## `awaiting` is the one that matters
+ *
+ * A run parking on a human step is the event a host most needs to react to —
+ * it is when a form has to appear in front of somebody. It gets its own event
+ * rather than folding into `updated`, so a host can subscribe to just that.
+ *
+ * ## Broadcast status, stated plainly
+ *
+ * `fancy-flow-php` currently dispatches these as **in-process Laravel events**;
+ * none of them implement `ShouldBroadcast` yet. This contract is therefore the
+ * agreed vocabulary rather than a description of traffic already on the wire: a
+ * host that wants live runs today re-broadcasts these under these names. Making
+ * the PHP events broadcast natively is a separate change, because it turns on
+ * websocket traffic for every consumer.
+ */
+declare const flowLive: {
+    readonly namespace: "flow";
+    readonly events: readonly [{
+        readonly event: "flow.run.created";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+    }, {
+        readonly event: "flow.run.updated";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+    }, {
+        readonly event: "flow.run.completed";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+    }, {
+        readonly event: "flow.run.awaiting";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+        readonly note: "A run parking on a human step — the moment a form has to appear in front of somebody. Its own event so a host can subscribe to just that, rather than filtering every update.";
+    }, {
+        readonly event: "flow.run.failed";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+        readonly note: "Not one of the standard verbs: a failed run is a terminal state a host renders differently from a completed one, so collapsing the two would lose the distinction.";
+    }];
+};
+/**
+ * Per-run keys, for a host showing a single run rather than the list.
+ *
+ * The contract declares prefixes because it is static data and a run id is not
+ * known until runtime. TanStack matches by prefix, so `["flow", "runs"]` still
+ * invalidates `["flow", "runs", runId]`.
+ */
+declare const flowKeys: {
+    readonly runs: () => readonly ["flow", "runs"];
+    readonly run: (runId: string) => readonly ["flow", "runs", string];
+};
+
+export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorAction, type FlowEditorApi, type FlowEditorBuiltins, type FlowEditorProps, type FlowEditorSlots, FlowGraph, FlowNode, type FlowNodeRenderProps, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, LaneNode, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeRunStatus, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, WorkflowSchema, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, flowKeys, flowLive, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };

package/dist/index.d.ts

@@ -580,4 +580,72 @@ type FlowRunFeedProps = {
  */
 declare function FlowRunFeed({ entries, showHeader, title, running, className, style }: FlowRunFeedProps): react.JSX.Element;
 
-export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorAction, type FlowEditorApi, type FlowEditorBuiltins, type FlowEditorProps, type FlowEditorSlots, FlowGraph, FlowNode, type FlowNodeRenderProps, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, LaneNode, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeRunStatus, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, WorkflowSchema, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };
+/**
+ * The fancy-flow Live Contract — the run / job stream shape.
+ *
+ * Pure data, with `LiveContract` imported as a TYPE, so this adds no dependency.
+ * `FancyFlow\Laravel\LiveContract` declares the identical list and both sides
+ * assert parity.
+ *
+ * ## What makes this shape different
+ *
+ * A run emits far more than it stores. `NodeStatusChanged` and `NodeOutput`
+ * fire per node, many times a second on a wide graph — and a node's log line is
+ * not a cache entry, it is a **stream**. So the contract covers the run's
+ * DURABLE state (does this run exist, has it finished, is it waiting on a
+ * person) and deliberately leaves per-node chatter to `useFancyStream`, the
+ * same split the whiteboard makes between its document and its cursors.
+ *
+ * Get that wrong and a 40-node run invalidates the run list forty times while
+ * it executes, each one a re-fetch that tells the UI nothing it did not already
+ * learn from the stream.
+ *
+ * ## `awaiting` is the one that matters
+ *
+ * A run parking on a human step is the event a host most needs to react to —
+ * it is when a form has to appear in front of somebody. It gets its own event
+ * rather than folding into `updated`, so a host can subscribe to just that.
+ *
+ * ## Broadcast status, stated plainly
+ *
+ * `fancy-flow-php` currently dispatches these as **in-process Laravel events**;
+ * none of them implement `ShouldBroadcast` yet. This contract is therefore the
+ * agreed vocabulary rather than a description of traffic already on the wire: a
+ * host that wants live runs today re-broadcasts these under these names. Making
+ * the PHP events broadcast natively is a separate change, because it turns on
+ * websocket traffic for every consumer.
+ */
+declare const flowLive: {
+    readonly namespace: "flow";
+    readonly events: readonly [{
+        readonly event: "flow.run.created";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+    }, {
+        readonly event: "flow.run.updated";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+    }, {
+        readonly event: "flow.run.completed";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+    }, {
+        readonly event: "flow.run.awaiting";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+        readonly note: "A run parking on a human step — the moment a form has to appear in front of somebody. Its own event so a host can subscribe to just that, rather than filtering every update.";
+    }, {
+        readonly event: "flow.run.failed";
+        readonly keys: readonly [readonly ["flow", "runs"]];
+        readonly note: "Not one of the standard verbs: a failed run is a terminal state a host renders differently from a completed one, so collapsing the two would lose the distinction.";
+    }];
+};
+/**
+ * Per-run keys, for a host showing a single run rather than the list.
+ *
+ * The contract declares prefixes because it is static data and a run id is not
+ * known until runtime. TanStack matches by prefix, so `["flow", "runs"]` still
+ * invalidates `["flow", "runs", runId]`.
+ */
+declare const flowKeys: {
+    readonly runs: () => readonly ["flow", "runs"];
+    readonly run: (runId: string) => readonly ["flow", "runs", string];
+};
+
+export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorAction, type FlowEditorApi, type FlowEditorBuiltins, type FlowEditorProps, type FlowEditorSlots, FlowGraph, FlowNode, type FlowNodeRenderProps, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, LaneNode, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeRunStatus, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, WorkflowSchema, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, flowKeys, flowLive, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };

package/dist/index.js

@@ -1506,9 +1506,33 @@ function NodePort({ side, type, id, style, title, className }) {
   );
 }
 
+// src/live.ts
+var flowLive = {
+  namespace: "flow",
+  events: [
+    { event: "flow.run.created", keys: [["flow", "runs"]] },
+    { event: "flow.run.updated", keys: [["flow", "runs"]] },
+    { event: "flow.run.completed", keys: [["flow", "runs"]] },
+    {
+      event: "flow.run.awaiting",
+      keys: [["flow", "runs"]],
+      note: "A run parking on a human step \u2014 the moment a form has to appear in front of somebody. Its own event so a host can subscribe to just that, rather than filtering every update."
+    },
+    {
+      event: "flow.run.failed",
+      keys: [["flow", "runs"]],
+      note: "Not one of the standard verbs: a failed run is a terminal state a host renders differently from a completed one, so collapsing the two would lose the distinction."
+    }
+  ]
+};
+var flowKeys = {
+  runs: () => ["flow", "runs"],
+  run: (runId) => ["flow", "runs", runId]
+};
+
 // src/index.ts
 registerBuiltinKinds();
 
-export { ConfigFieldRenderer, FlowEditor, FlowRunControls, FlowRunFeed, NodeConfigPanel, NodePalette, NodePort, defineNode, paletteDropHandlers };
+export { ConfigFieldRenderer, FlowEditor, FlowRunControls, FlowRunFeed, NodeConfigPanel, NodePalette, NodePort, defineNode, flowKeys, flowLive, paletteDropHandlers };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map