footprint-explainable-ui 0.3.2 → 0.5.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 
 /** Snapshot of a single pipeline stage — the core data shape for all components. */
 interface StageSnapshot {
@@ -16,6 +17,12 @@ interface StageSnapshot {
     durationMs: number;
     /** Execution status */
     status?: "pending" | "active" | "done" | "error";
+    /** Human-readable description of what this stage does */
+    description?: string;
+    /** Subflow identifier (when this stage is inside a subflow) */
+    subflowId?: string;
+    /** Subflow execution result — present on stages that ran a subflow. */
+    subflowResult?: unknown;
 }
 /** Component size variants */
 type Size = "compact" | "default" | "detailed";
@@ -135,12 +142,15 @@ interface GanttTimelineProps extends BaseComponentProps {
     selectedIndex?: number;
     /** Callback when a stage bar is clicked */
     onSelect?: (index: number) => void;
+    /** Max visible rows before collapsing (0 = no collapse). Default: 5 */
+    maxVisibleRows?: number;
 }
 /**
  * Horizontal Gantt-style timeline showing stage durations and overlap.
- * Great for performance analysis of pipeline execution.
+ * Collapses to `maxVisibleRows` with expand/collapse toggle.
+ * Auto-scrolls to keep the active stage visible when collapsed.
  */
-declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, }: GanttTimelineProps): react_jsx_runtime.JSX.Element;
+declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, maxVisibleRows, }: GanttTimelineProps): react_jsx_runtime.JSX.Element;
 
 interface SnapshotPanelProps extends BaseComponentProps {
     /** Stage snapshots from pipeline execution */
@@ -184,6 +194,29 @@ interface ResultPanelProps extends BaseComponentProps {
 }
 declare function ResultPanel({ data, logs, hideConsole, size, unstyled, className, style, }: ResultPanelProps): react_jsx_runtime.JSX.Element;
 
+type StageDetailMode = "simple" | "dev";
+interface MemoryChange {
+    key: string;
+    type: "added" | "updated" | "removed";
+    oldValue?: unknown;
+    newValue?: unknown;
+}
+interface StageDetailPanelProps extends BaseComponentProps {
+    /** Stage snapshots for time-travel */
+    snapshots: StageSnapshot[];
+    /** Current snapshot index */
+    selectedIndex: number;
+    /** Display mode: "simple" (description + narrative) or "dev" (memory story) */
+    mode?: StageDetailMode;
+    /** Show a toggle to switch between simple/dev modes (default: false) */
+    showToggle?: boolean;
+    /** Called when user toggles mode via built-in toggle */
+    onModeChange?: (mode: StageDetailMode) => void;
+    /** Keys to exclude from memory display (default: engine internals). Pass empty set to show all. */
+    excludeKeys?: Set<string>;
+}
+declare function StageDetailPanel({ snapshots, selectedIndex, mode: controlledMode, showToggle, onModeChange, size, unstyled, className, style, }: StageDetailPanelProps): react_jsx_runtime.JSX.Element;
+
 interface TimeTravelControlsProps extends BaseComponentProps {
     /** Stage snapshots */
     snapshots: StageSnapshot[];
@@ -221,6 +254,57 @@ interface ExplainableShellProps extends BaseComponentProps {
 }
 declare function ExplainableShell({ snapshots, resultData, logs, narrative, tabs, defaultTab, hideConsole, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * 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
+ */
+
+interface SpecNode {
+    name: string;
+    id?: string;
+    type?: "stage" | "decider" | "fork" | "streaming";
+    description?: string;
+    children?: SpecNode[];
+    next?: SpecNode;
+    branchIds?: string[];
+    hasDecider?: boolean;
+    hasSelector?: boolean;
+    loopTarget?: string;
+    isSubflowRoot?: boolean;
+    subflowId?: string;
+    subflowName?: string;
+    subflowStructure?: SpecNode;
+}
+
+interface SubflowTreeEntry {
+    /** Node name / identifier */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Subflow ID (when this node represents a subflow) */
+    subflowId?: string;
+    /** Whether this node is a subflow root (has nested structure) */
+    isSubflow?: boolean;
+    /** Nested children (subflow stages) */
+    children?: SubflowTreeEntry[];
+}
+interface SubflowTreeProps extends BaseComponentProps {
+    /** Pipeline spec to derive the tree from */
+    spec: SpecNode;
+    /** Currently active stage name (highlights in tree) */
+    activeStage?: string | null;
+    /** Set of completed stage names */
+    doneStages?: Set<string>;
+    /** Called when a tree node is clicked */
+    onNodeSelect?: (name: string, isSubflow: boolean) => void;
+}
+declare const SubflowTree: react.NamedExoticComponent<SubflowTreeProps>;
+
 /**
  * Shape of FootPrint's RuntimeSnapshot (from FlowChartExecutor.getSnapshot()).
  * We define it here instead of importing to avoid a hard dependency on footprintjs.
@@ -230,11 +314,15 @@ interface RuntimeStageSnapshot {
     name?: string;
     isDecider?: boolean;
     isFork?: boolean;
+    /** User-level writes made by this stage (pre-namespace keys → values). */
+    stageWrites?: Record<string, unknown>;
     logs: Record<string, unknown>;
     errors: Record<string, unknown>;
     metrics: Record<string, unknown>;
     evals: Record<string, unknown>;
     flowMessages?: unknown[];
+    description?: string;
+    subflowId?: string;
     next?: RuntimeStageSnapshot;
     children?: RuntimeStageSnapshot[];
 }
@@ -242,6 +330,8 @@ interface RuntimeSnapshot {
     sharedState: Record<string, unknown>;
     executionTree: RuntimeStageSnapshot;
     commitLog: unknown[];
+    /** Per-subflow execution results (keyed by subflowId). */
+    subflowResults?: Record<string, unknown>;
 }
 /**
  * Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
@@ -265,6 +355,8 @@ declare function createSnapshots(stages: Array<{
     memory?: Record<string, unknown>;
     narrative?: string;
     durationMs?: number;
+    description?: string;
+    subflowId?: string;
 }>): StageSnapshot[];
 
-export { type BaseComponentProps, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, MemoryInspector, type MemoryInspectorProps, NarrativeLog, type NarrativeLogProps, NarrativeTrace, type NarrativeTraceProps, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageSnapshot, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useFootprintTheme, warmDark, warmLight };
+export { type BaseComponentProps, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, NarrativeLog, type NarrativeLogProps, NarrativeTrace, type NarrativeTraceProps, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageDetailMode, StageDetailPanel, type StageDetailPanelProps, type StageSnapshot, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useFootprintTheme, warmDark, warmLight };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 
 /** Snapshot of a single pipeline stage — the core data shape for all components. */
 interface StageSnapshot {
@@ -16,6 +17,12 @@ interface StageSnapshot {
     durationMs: number;
     /** Execution status */
     status?: "pending" | "active" | "done" | "error";
+    /** Human-readable description of what this stage does */
+    description?: string;
+    /** Subflow identifier (when this stage is inside a subflow) */
+    subflowId?: string;
+    /** Subflow execution result — present on stages that ran a subflow. */
+    subflowResult?: unknown;
 }
 /** Component size variants */
 type Size = "compact" | "default" | "detailed";
@@ -135,12 +142,15 @@ interface GanttTimelineProps extends BaseComponentProps {
     selectedIndex?: number;
     /** Callback when a stage bar is clicked */
     onSelect?: (index: number) => void;
+    /** Max visible rows before collapsing (0 = no collapse). Default: 5 */
+    maxVisibleRows?: number;
 }
 /**
  * Horizontal Gantt-style timeline showing stage durations and overlap.
- * Great for performance analysis of pipeline execution.
+ * Collapses to `maxVisibleRows` with expand/collapse toggle.
+ * Auto-scrolls to keep the active stage visible when collapsed.
  */
-declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, }: GanttTimelineProps): react_jsx_runtime.JSX.Element;
+declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, maxVisibleRows, }: GanttTimelineProps): react_jsx_runtime.JSX.Element;
 
 interface SnapshotPanelProps extends BaseComponentProps {
     /** Stage snapshots from pipeline execution */
@@ -184,6 +194,29 @@ interface ResultPanelProps extends BaseComponentProps {
 }
 declare function ResultPanel({ data, logs, hideConsole, size, unstyled, className, style, }: ResultPanelProps): react_jsx_runtime.JSX.Element;
 
+type StageDetailMode = "simple" | "dev";
+interface MemoryChange {
+    key: string;
+    type: "added" | "updated" | "removed";
+    oldValue?: unknown;
+    newValue?: unknown;
+}
+interface StageDetailPanelProps extends BaseComponentProps {
+    /** Stage snapshots for time-travel */
+    snapshots: StageSnapshot[];
+    /** Current snapshot index */
+    selectedIndex: number;
+    /** Display mode: "simple" (description + narrative) or "dev" (memory story) */
+    mode?: StageDetailMode;
+    /** Show a toggle to switch between simple/dev modes (default: false) */
+    showToggle?: boolean;
+    /** Called when user toggles mode via built-in toggle */
+    onModeChange?: (mode: StageDetailMode) => void;
+    /** Keys to exclude from memory display (default: engine internals). Pass empty set to show all. */
+    excludeKeys?: Set<string>;
+}
+declare function StageDetailPanel({ snapshots, selectedIndex, mode: controlledMode, showToggle, onModeChange, size, unstyled, className, style, }: StageDetailPanelProps): react_jsx_runtime.JSX.Element;
+
 interface TimeTravelControlsProps extends BaseComponentProps {
     /** Stage snapshots */
     snapshots: StageSnapshot[];
@@ -221,6 +254,57 @@ interface ExplainableShellProps extends BaseComponentProps {
 }
 declare function ExplainableShell({ snapshots, resultData, logs, narrative, tabs, defaultTab, hideConsole, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * 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
+ */
+
+interface SpecNode {
+    name: string;
+    id?: string;
+    type?: "stage" | "decider" | "fork" | "streaming";
+    description?: string;
+    children?: SpecNode[];
+    next?: SpecNode;
+    branchIds?: string[];
+    hasDecider?: boolean;
+    hasSelector?: boolean;
+    loopTarget?: string;
+    isSubflowRoot?: boolean;
+    subflowId?: string;
+    subflowName?: string;
+    subflowStructure?: SpecNode;
+}
+
+interface SubflowTreeEntry {
+    /** Node name / identifier */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Subflow ID (when this node represents a subflow) */
+    subflowId?: string;
+    /** Whether this node is a subflow root (has nested structure) */
+    isSubflow?: boolean;
+    /** Nested children (subflow stages) */
+    children?: SubflowTreeEntry[];
+}
+interface SubflowTreeProps extends BaseComponentProps {
+    /** Pipeline spec to derive the tree from */
+    spec: SpecNode;
+    /** Currently active stage name (highlights in tree) */
+    activeStage?: string | null;
+    /** Set of completed stage names */
+    doneStages?: Set<string>;
+    /** Called when a tree node is clicked */
+    onNodeSelect?: (name: string, isSubflow: boolean) => void;
+}
+declare const SubflowTree: react.NamedExoticComponent<SubflowTreeProps>;
+
 /**
  * Shape of FootPrint's RuntimeSnapshot (from FlowChartExecutor.getSnapshot()).
  * We define it here instead of importing to avoid a hard dependency on footprintjs.
@@ -230,11 +314,15 @@ interface RuntimeStageSnapshot {
     name?: string;
     isDecider?: boolean;
     isFork?: boolean;
+    /** User-level writes made by this stage (pre-namespace keys → values). */
+    stageWrites?: Record<string, unknown>;
     logs: Record<string, unknown>;
     errors: Record<string, unknown>;
     metrics: Record<string, unknown>;
     evals: Record<string, unknown>;
     flowMessages?: unknown[];
+    description?: string;
+    subflowId?: string;
     next?: RuntimeStageSnapshot;
     children?: RuntimeStageSnapshot[];
 }
@@ -242,6 +330,8 @@ interface RuntimeSnapshot {
     sharedState: Record<string, unknown>;
     executionTree: RuntimeStageSnapshot;
     commitLog: unknown[];
+    /** Per-subflow execution results (keyed by subflowId). */
+    subflowResults?: Record<string, unknown>;
 }
 /**
  * Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
@@ -265,6 +355,8 @@ declare function createSnapshots(stages: Array<{
     memory?: Record<string, unknown>;
     narrative?: string;
     durationMs?: number;
+    description?: string;
+    subflowId?: string;
 }>): StageSnapshot[];
 
-export { type BaseComponentProps, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, MemoryInspector, type MemoryInspectorProps, NarrativeLog, type NarrativeLogProps, NarrativeTrace, type NarrativeTraceProps, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageSnapshot, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useFootprintTheme, warmDark, warmLight };
+export { type BaseComponentProps, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, NarrativeLog, type NarrativeLogProps, NarrativeTrace, type NarrativeTraceProps, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageDetailMode, StageDetailPanel, type StageDetailPanelProps, type StageSnapshot, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useFootprintTheme, warmDark, warmLight };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,aAAa,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGvE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACtE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,YAAY,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AACrE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAGjG,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC"}