footprint-explainable-ui 0.6.0 → 0.7.2

package/dist/flowchart.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _xyflow_react from '@xyflow/react';
-import { Node, Edge } from '@xyflow/react';
+import { Node, Edge, NodeTypes } from '@xyflow/react';
 import * as react from 'react';
 
 /** Snapshot of a single pipeline stage — the core data shape for all components. */
@@ -62,16 +62,21 @@ declare function FlowchartView({ nodes: rawNodes, edges: rawEdges, snapshots, se
  * Converts a SerializedPipelineStructure (from builder.toSpec()) into
  * ReactFlow nodes and edges with auto-layout.
  *
- * Supports two modes:
- * 1. Build-time only (no executionState) — all nodes gray
- * 2. With execution overlay — executed nodes colored, active node highlighted,
- *    unvisited nodes stay gray
+ * Two-phase approach for performance:
+ * 1. `specToLayout(spec)` — tree walk + positioning (expensive, cached on spec)
+ * 2. `applyOverlay(layout, overlay)` — color nodes/edges (cheap, runs per slider tick)
+ *
+ * `specToReactFlow(spec, overlay)` combines both for convenience.
  */
 
 interface SpecNode {
     name: string;
     id?: string;
     type?: "stage" | "decider" | "fork" | "streaming";
+    /** Semantic icon hint — rendered by StageNode. Common values:
+     *  "llm", "tool", "rag", "search", "parse", "start", "end", "loop",
+     *  "agent", "swarm", "guard", "stream", "memory" */
+    icon?: string;
     description?: string;
     children?: SpecNode[];
     next?: SpecNode;
@@ -83,6 +88,8 @@ interface SpecNode {
     subflowId?: string;
     subflowName?: string;
     subflowStructure?: SpecNode;
+    /** True when this subflow uses lazy resolution (deferred until execution). */
+    isLazy?: boolean;
 }
 interface ExecutionOverlay {
     /** Names of stages that have completed (before the active one) */
@@ -105,6 +112,48 @@ interface FlowchartColors {
     labelLoop: string;
     pathGlow: string;
 }
+/** A positioned node with all static info, before overlay is applied. */
+interface LayoutNode {
+    id: string;
+    x: number;
+    y: number;
+    label: string;
+    isDecider: boolean;
+    isFork: boolean;
+    description?: string;
+    icon?: string;
+    subflowId?: string;
+    isSubflow: boolean;
+    isLazy?: boolean;
+}
+/** A positioned edge with source/target info. */
+interface LayoutEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: string;
+    isLoop: boolean;
+}
+/** Static layout output — positions + structure, no execution state. */
+interface SpecLayout {
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    /** Maps stage ID → node id for resolving loopTarget references. */
+    idToName: Map<string, string>;
+}
+/**
+ * Phase 1: Compute static layout from spec. Cached on spec reference — only
+ * recomputes when the pipeline structure changes, not on every slider tick.
+ */
+declare function specToLayout(spec: SpecNode): SpecLayout;
+/**
+ * Phase 2: Apply execution overlay to static layout.
+ * Produces ReactFlow nodes/edges with correct colors, step numbers, and glow.
+ */
+declare function applyOverlay(layout: SpecLayout, overlay?: ExecutionOverlay, colors?: Partial<FlowchartColors>): {
+    nodes: Node[];
+    edges: Edge[];
+};
 /**
  * Convert a pipeline spec to ReactFlow graph.
  * Pass `overlay` to color nodes/edges by execution state.
@@ -115,7 +164,7 @@ declare function specToReactFlow(spec: SpecNode, overlay?: ExecutionOverlay, col
 };
 
 interface TracedFlowchartViewProps extends BaseComponentProps {
-    /** Pipeline spec from builder.toSpec() */
+    /** Pipeline spec from builder.toSpec() — for the current level */
     spec: SpecNode;
     /** Visualization snapshots (enables trace overlay when provided) */
     snapshots?: StageSnapshot[];
@@ -123,14 +172,10 @@ interface TracedFlowchartViewProps extends BaseComponentProps {
     snapshotIndex?: number;
     /** Callback when a node is clicked (receives snapshot index, or node id if no snapshots) */
     onNodeClick?: (indexOrId: number | string) => void;
-    /** Callback when subflow navigation changes (true = entered subflow) */
-    onSubflowChange?: (isInSubflow: boolean, subflowNodeName: string | null) => void;
-    /** Show subflow directory sidebar when subflows exist (default: true) */
-    showTree?: boolean;
-    /** Width of the tree sidebar in pixels (default: 200) */
-    treeWidth?: number;
-}
-declare function TracedFlowchartView({ spec, snapshots, snapshotIndex, onNodeClick, onSubflowChange, showTree, treeWidth, unstyled, className, style, }: TracedFlowchartViewProps): react_jsx_runtime.JSX.Element;
+    /** Override default node types */
+    nodeTypes?: NodeTypes;
+}
+declare function TracedFlowchartView({ spec, snapshots, snapshotIndex, onNodeClick, nodeTypes: customNodeTypes, unstyled, className, style, }: TracedFlowchartViewProps): react_jsx_runtime.JSX.Element;
 
 interface BreadcrumbEntry {
     /** Display name for this level */
@@ -205,12 +250,20 @@ interface StageNodeData {
     done?: boolean;
     error?: boolean;
     linked?: boolean;
+    /** Semantic icon hint (e.g., "llm", "tool", "rag", "start", "parse", "agent", "guard") */
+    icon?: string;
     /** Step numbers in execution order (shown as badges — multiple when revisited via loops) */
     stepNumbers?: number[];
     /** Node was not executed (dim it) */
     dimmed?: boolean;
     /** Node is a subflow root (show nested indicator) */
     isSubflow?: boolean;
+    /** Node uses lazy resolution (dashed border + cloud icon when unresolved) */
+    isLazy?: boolean;
+    /** Node is a decider (renders as diamond shape per flowchart convention) */
+    isDecider?: boolean;
+    /** Node is a fork (parallel fan-out) */
+    isFork?: boolean;
     /** Human-readable description of what this stage does */
     description?: string;
     /** Subflow identifier — set when this node belongs to a subflow */
@@ -250,4 +303,4 @@ interface TimeTravelDebuggerProps extends BaseComponentProps {
  */
 declare function TimeTravelDebugger({ snapshots, nodes, edges, showGantt, layout, title, size, unstyled, className, style, }: TimeTravelDebuggerProps): react_jsx_runtime.JSX.Element;
 
-export { type BreadcrumbEntry, type ExecutionOverlay, type FlowchartColors, FlowchartView, type FlowchartViewProps, type SpecNode, StageNode, type StageNodeData, SubflowBreadcrumb, type SubflowBreadcrumbProps, type SubflowNavigation, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, TimeTravelDebugger, type TimeTravelDebuggerProps, TracedFlowchartView, type TracedFlowchartViewProps, specToReactFlow, useSubflowNavigation };
+export { type BreadcrumbEntry, type ExecutionOverlay, type FlowchartColors, FlowchartView, type FlowchartViewProps, type LayoutEdge, type LayoutNode, type SpecLayout, type SpecNode, StageNode, type StageNodeData, SubflowBreadcrumb, type SubflowBreadcrumbProps, type SubflowNavigation, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, TimeTravelDebugger, type TimeTravelDebuggerProps, TracedFlowchartView, type TracedFlowchartViewProps, applyOverlay, specToLayout, specToReactFlow, useSubflowNavigation };

package/dist/flowchart.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _xyflow_react from '@xyflow/react';
-import { Node, Edge } from '@xyflow/react';
+import { Node, Edge, NodeTypes } from '@xyflow/react';
 import * as react from 'react';
 
 /** Snapshot of a single pipeline stage — the core data shape for all components. */
@@ -62,16 +62,21 @@ declare function FlowchartView({ nodes: rawNodes, edges: rawEdges, snapshots, se
  * Converts a SerializedPipelineStructure (from builder.toSpec()) into
  * ReactFlow nodes and edges with auto-layout.
  *
- * Supports two modes:
- * 1. Build-time only (no executionState) — all nodes gray
- * 2. With execution overlay — executed nodes colored, active node highlighted,
- *    unvisited nodes stay gray
+ * Two-phase approach for performance:
+ * 1. `specToLayout(spec)` — tree walk + positioning (expensive, cached on spec)
+ * 2. `applyOverlay(layout, overlay)` — color nodes/edges (cheap, runs per slider tick)
+ *
+ * `specToReactFlow(spec, overlay)` combines both for convenience.
  */
 
 interface SpecNode {
     name: string;
     id?: string;
     type?: "stage" | "decider" | "fork" | "streaming";
+    /** Semantic icon hint — rendered by StageNode. Common values:
+     *  "llm", "tool", "rag", "search", "parse", "start", "end", "loop",
+     *  "agent", "swarm", "guard", "stream", "memory" */
+    icon?: string;
     description?: string;
     children?: SpecNode[];
     next?: SpecNode;
@@ -83,6 +88,8 @@ interface SpecNode {
     subflowId?: string;
     subflowName?: string;
     subflowStructure?: SpecNode;
+    /** True when this subflow uses lazy resolution (deferred until execution). */
+    isLazy?: boolean;
 }
 interface ExecutionOverlay {
     /** Names of stages that have completed (before the active one) */
@@ -105,6 +112,48 @@ interface FlowchartColors {
     labelLoop: string;
     pathGlow: string;
 }
+/** A positioned node with all static info, before overlay is applied. */
+interface LayoutNode {
+    id: string;
+    x: number;
+    y: number;
+    label: string;
+    isDecider: boolean;
+    isFork: boolean;
+    description?: string;
+    icon?: string;
+    subflowId?: string;
+    isSubflow: boolean;
+    isLazy?: boolean;
+}
+/** A positioned edge with source/target info. */
+interface LayoutEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: string;
+    isLoop: boolean;
+}
+/** Static layout output — positions + structure, no execution state. */
+interface SpecLayout {
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    /** Maps stage ID → node id for resolving loopTarget references. */
+    idToName: Map<string, string>;
+}
+/**
+ * Phase 1: Compute static layout from spec. Cached on spec reference — only
+ * recomputes when the pipeline structure changes, not on every slider tick.
+ */
+declare function specToLayout(spec: SpecNode): SpecLayout;
+/**
+ * Phase 2: Apply execution overlay to static layout.
+ * Produces ReactFlow nodes/edges with correct colors, step numbers, and glow.
+ */
+declare function applyOverlay(layout: SpecLayout, overlay?: ExecutionOverlay, colors?: Partial<FlowchartColors>): {
+    nodes: Node[];
+    edges: Edge[];
+};
 /**
  * Convert a pipeline spec to ReactFlow graph.
  * Pass `overlay` to color nodes/edges by execution state.
@@ -115,7 +164,7 @@ declare function specToReactFlow(spec: SpecNode, overlay?: ExecutionOverlay, col
 };
 
 interface TracedFlowchartViewProps extends BaseComponentProps {
-    /** Pipeline spec from builder.toSpec() */
+    /** Pipeline spec from builder.toSpec() — for the current level */
     spec: SpecNode;
     /** Visualization snapshots (enables trace overlay when provided) */
     snapshots?: StageSnapshot[];
@@ -123,14 +172,10 @@ interface TracedFlowchartViewProps extends BaseComponentProps {
     snapshotIndex?: number;
     /** Callback when a node is clicked (receives snapshot index, or node id if no snapshots) */
     onNodeClick?: (indexOrId: number | string) => void;
-    /** Callback when subflow navigation changes (true = entered subflow) */
-    onSubflowChange?: (isInSubflow: boolean, subflowNodeName: string | null) => void;
-    /** Show subflow directory sidebar when subflows exist (default: true) */
-    showTree?: boolean;
-    /** Width of the tree sidebar in pixels (default: 200) */
-    treeWidth?: number;
-}
-declare function TracedFlowchartView({ spec, snapshots, snapshotIndex, onNodeClick, onSubflowChange, showTree, treeWidth, unstyled, className, style, }: TracedFlowchartViewProps): react_jsx_runtime.JSX.Element;
+    /** Override default node types */
+    nodeTypes?: NodeTypes;
+}
+declare function TracedFlowchartView({ spec, snapshots, snapshotIndex, onNodeClick, nodeTypes: customNodeTypes, unstyled, className, style, }: TracedFlowchartViewProps): react_jsx_runtime.JSX.Element;
 
 interface BreadcrumbEntry {
     /** Display name for this level */
@@ -205,12 +250,20 @@ interface StageNodeData {
     done?: boolean;
     error?: boolean;
     linked?: boolean;
+    /** Semantic icon hint (e.g., "llm", "tool", "rag", "start", "parse", "agent", "guard") */
+    icon?: string;
     /** Step numbers in execution order (shown as badges — multiple when revisited via loops) */
     stepNumbers?: number[];
     /** Node was not executed (dim it) */
     dimmed?: boolean;
     /** Node is a subflow root (show nested indicator) */
     isSubflow?: boolean;
+    /** Node uses lazy resolution (dashed border + cloud icon when unresolved) */
+    isLazy?: boolean;
+    /** Node is a decider (renders as diamond shape per flowchart convention) */
+    isDecider?: boolean;
+    /** Node is a fork (parallel fan-out) */
+    isFork?: boolean;
     /** Human-readable description of what this stage does */
     description?: string;
     /** Subflow identifier — set when this node belongs to a subflow */
@@ -250,4 +303,4 @@ interface TimeTravelDebuggerProps extends BaseComponentProps {
  */
 declare function TimeTravelDebugger({ snapshots, nodes, edges, showGantt, layout, title, size, unstyled, className, style, }: TimeTravelDebuggerProps): react_jsx_runtime.JSX.Element;
 
-export { type BreadcrumbEntry, type ExecutionOverlay, type FlowchartColors, FlowchartView, type FlowchartViewProps, type SpecNode, StageNode, type StageNodeData, SubflowBreadcrumb, type SubflowBreadcrumbProps, type SubflowNavigation, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, TimeTravelDebugger, type TimeTravelDebuggerProps, TracedFlowchartView, type TracedFlowchartViewProps, specToReactFlow, useSubflowNavigation };
+export { type BreadcrumbEntry, type ExecutionOverlay, type FlowchartColors, FlowchartView, type FlowchartViewProps, type LayoutEdge, type LayoutNode, type SpecLayout, type SpecNode, StageNode, type StageNodeData, SubflowBreadcrumb, type SubflowBreadcrumbProps, type SubflowNavigation, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, TimeTravelDebugger, type TimeTravelDebuggerProps, TracedFlowchartView, type TracedFlowchartViewProps, applyOverlay, specToLayout, specToReactFlow, useSubflowNavigation };