footprint-explainable-ui 0.6.0 → 0.7.2

package/dist/index.d.cts

@@ -24,6 +24,14 @@ interface StageSnapshot {
     /** Subflow execution result — present on stages that ran a subflow. */
     subflowResult?: unknown;
 }
+/** Structured narrative entry — preserves type info for semantic rendering. */
+interface NarrativeEntry$1 {
+    type: 'stage' | 'step' | 'condition' | 'fork' | 'subflow' | 'loop' | 'break' | 'error';
+    text: string;
+    depth: number;
+    stageName?: string;
+    stepNumber?: number;
+}
 /** Component size variants */
 type Size = "compact" | "default" | "detailed";
 /** Common props shared by all visualization components */
@@ -61,7 +69,28 @@ interface ThemeTokens {
 }
 /** Maps ThemeTokens to CSS custom property assignments. */
 declare function tokensToCSSVars(tokens: ThemeTokens): Record<string, string>;
-/** Default dark theme values (used as CSS variable fallbacks). */
+/** Raw fallback values — used by tokensToCSSVars() and anywhere a real color is needed. */
+declare const rawDefaults: {
+    readonly colors: {
+        readonly primary: "#6366f1";
+        readonly success: "#22c55e";
+        readonly error: "#ef4444";
+        readonly warning: "#f59e0b";
+        readonly bgPrimary: "#0f172a";
+        readonly bgSecondary: "#1e293b";
+        readonly bgTertiary: "#334155";
+        readonly textPrimary: "#f8fafc";
+        readonly textSecondary: "#94a3b8";
+        readonly textMuted: "#64748b";
+        readonly border: "#334155";
+    };
+    readonly radius: "8px";
+    readonly fontFamily: {
+        readonly sans: "Inter, system-ui, -apple-system, sans-serif";
+        readonly mono: "'JetBrains Mono', 'Fira Code', monospace";
+    };
+};
+/** Default dark theme values with CSS variable references (consumers can override via CSS). */
 declare const defaultTokens: Required<{
     [K in keyof ThemeTokens]-?: Required<ThemeTokens[K]>;
 }>;
@@ -264,45 +293,25 @@ interface TimeTravelControlsProps extends BaseComponentProps {
 }
 declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react_jsx_runtime.JSX.Element;
 
-type ShellTab = "result" | "explainable" | "ai-compatible";
-interface ExplainableShellProps extends BaseComponentProps {
-    /** Stage snapshots for time-travel visualization */
-    snapshots: StageSnapshot[];
-    /** Final pipeline result data */
-    resultData?: Record<string, unknown> | null;
-    /** Console log lines */
-    logs?: string[];
-    /** Combined narrative lines */
-    narrative?: string[];
-    /** Which tabs to show (default: all three) */
-    tabs?: ShellTab[];
-    /** Initially active tab */
-    defaultTab?: ShellTab;
-    /** Hide console in result tab */
-    hideConsole?: boolean;
-    /** Custom content to render in each tab slot */
-    renderFlowchart?: (props: {
-        snapshots: StageSnapshot[];
-        selectedIndex: number;
-        onNodeClick?: (index: number) => void;
-    }) => React.ReactNode;
-}
-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
+ * 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;
@@ -314,7 +323,72 @@ interface SpecNode {
     subflowId?: string;
     subflowName?: string;
     subflowStructure?: SpecNode;
+    /** True when this subflow uses lazy resolution (deferred until execution). */
+    isLazy?: boolean;
+}
+
+type ShellTab = "result" | "explainable" | "ai-compatible";
+interface PanelLabels {
+    /** Left panel pill label (subflow tree). Default: "Topology" */
+    topology?: string;
+    /** Right panel pill label (memory/narrative). Default: "Details" */
+    details?: string;
+    /** Bottom panel pill label (timeline). Default: "Timeline" */
+    timeline?: string;
+}
+/** Which panels start expanded. Default: `{ details: true }` (flowchart + memory). */
+interface DefaultExpanded {
+    topology?: boolean;
+    details?: boolean;
+    timeline?: boolean;
 }
+interface ExplainableShellProps extends BaseComponentProps {
+    snapshots: StageSnapshot[];
+    spec?: SpecNode | null;
+    title?: string;
+    resultData?: Record<string, unknown> | null;
+    logs?: string[];
+    narrative?: string[];
+    narrativeEntries?: NarrativeEntry$1[];
+    tabs?: ShellTab[];
+    defaultTab?: ShellTab;
+    hideConsole?: boolean;
+    /** Customize the labels on collapsible panel pills */
+    panelLabels?: PanelLabels;
+    /** Which panels start expanded. Default: `{ details: true }` */
+    defaultExpanded?: DefaultExpanded;
+    renderFlowchart?: (props: {
+        spec: SpecNode;
+        snapshots: StageSnapshot[];
+        selectedIndex: number;
+        onNodeClick?: (indexOrId: number | string) => void;
+    }) => React.ReactNode;
+}
+declare function ExplainableShell({ snapshots, spec, title, resultData, logs, narrative, narrativeEntries, tabs, defaultTab, hideConsole, panelLabels, defaultExpanded, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
+
+interface MemoryPanelProps extends BaseComponentProps {
+    snapshots: StageSnapshot[];
+    selectedIndex: number;
+}
+declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, className, style, }: MemoryPanelProps): react_jsx_runtime.JSX.Element;
+
+interface NarrativePanelProps extends BaseComponentProps {
+    snapshots: StageSnapshot[];
+    selectedIndex: number;
+    /** Structured narrative entries (preferred — richer rendering) */
+    narrativeEntries?: NarrativeEntry$1[];
+    /** Plain narrative lines (fallback) */
+    narrative?: string[];
+}
+declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, narrative: narrativeProp, size, unstyled, className, style, }: NarrativePanelProps): react_jsx_runtime.JSX.Element;
+
+interface StoryNarrativeProps extends BaseComponentProps {
+    /** Structured narrative entries from CombinedNarrativeRecorder */
+    entries: NarrativeEntry$1[];
+    /** Number of stages to reveal (maps to snapshotIdx + 1) */
+    stageCount: number;
+}
+declare function StoryNarrative({ entries, stageCount, size, unstyled, className, style: outerStyle, }: StoryNarrativeProps): react_jsx_runtime.JSX.Element;
 
 interface SubflowTreeEntry {
     /** Node name / identifier */
@@ -399,6 +473,16 @@ interface NarrativeEntry {
  * ```
  */
 declare function toVisualizationSnapshots(runtime: RuntimeSnapshot, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
+/**
+ * Converts a footprintjs SubflowResult (stored on StageSnapshot.subflowResult)
+ * into visualization snapshots for drill-down views.
+ *
+ * SubflowResult shape (from footprintjs):
+ *   { subflowId, subflowName, treeContext: { globalContext, stageContexts, history }, parentStageId }
+ *
+ * Returns empty array if the input is not a valid SubflowResult.
+ */
+declare function subflowResultToSnapshots(subflowResult: unknown, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
 /**
  * Creates StageSnapshots from simple arrays (when you don't have a RuntimeSnapshot).
  * Useful for testing or custom data sources.
@@ -413,4 +497,4 @@ declare function createSnapshots(stages: Array<{
     subflowId?: string;
 }>): StageSnapshot[];
 
-export { type BaseComponentProps, type DarkModeTokensOptions, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, type NarrativeEntry, 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, coolLight, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useDarkModeTokens, useFootprintTheme, warmDark, warmLight };
+export { type NarrativeEntry as AdapterNarrativeEntry, type BaseComponentProps, type DarkModeTokensOptions, type DefaultExpanded, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, MemoryPanel, type MemoryPanelProps, type NarrativeEntry$1 as NarrativeEntry, NarrativeLog, type NarrativeLogProps, NarrativePanel, type NarrativePanelProps, NarrativeTrace, type NarrativeTraceProps, type PanelLabels, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageDetailMode, StageDetailPanel, type StageDetailPanelProps, type StageSnapshot, StoryNarrative, type StoryNarrativeProps, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, coolLight, createSnapshots, defaultTokens, rawDefaults, subflowResultToSnapshots, themePresets, toVisualizationSnapshots, tokensToCSSVars, useDarkModeTokens, useFootprintTheme, warmDark, warmLight };

package/dist/index.d.ts

@@ -24,6 +24,14 @@ interface StageSnapshot {
     /** Subflow execution result — present on stages that ran a subflow. */
     subflowResult?: unknown;
 }
+/** Structured narrative entry — preserves type info for semantic rendering. */
+interface NarrativeEntry$1 {
+    type: 'stage' | 'step' | 'condition' | 'fork' | 'subflow' | 'loop' | 'break' | 'error';
+    text: string;
+    depth: number;
+    stageName?: string;
+    stepNumber?: number;
+}
 /** Component size variants */
 type Size = "compact" | "default" | "detailed";
 /** Common props shared by all visualization components */
@@ -61,7 +69,28 @@ interface ThemeTokens {
 }
 /** Maps ThemeTokens to CSS custom property assignments. */
 declare function tokensToCSSVars(tokens: ThemeTokens): Record<string, string>;
-/** Default dark theme values (used as CSS variable fallbacks). */
+/** Raw fallback values — used by tokensToCSSVars() and anywhere a real color is needed. */
+declare const rawDefaults: {
+    readonly colors: {
+        readonly primary: "#6366f1";
+        readonly success: "#22c55e";
+        readonly error: "#ef4444";
+        readonly warning: "#f59e0b";
+        readonly bgPrimary: "#0f172a";
+        readonly bgSecondary: "#1e293b";
+        readonly bgTertiary: "#334155";
+        readonly textPrimary: "#f8fafc";
+        readonly textSecondary: "#94a3b8";
+        readonly textMuted: "#64748b";
+        readonly border: "#334155";
+    };
+    readonly radius: "8px";
+    readonly fontFamily: {
+        readonly sans: "Inter, system-ui, -apple-system, sans-serif";
+        readonly mono: "'JetBrains Mono', 'Fira Code', monospace";
+    };
+};
+/** Default dark theme values with CSS variable references (consumers can override via CSS). */
 declare const defaultTokens: Required<{
     [K in keyof ThemeTokens]-?: Required<ThemeTokens[K]>;
 }>;
@@ -264,45 +293,25 @@ interface TimeTravelControlsProps extends BaseComponentProps {
 }
 declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react_jsx_runtime.JSX.Element;
 
-type ShellTab = "result" | "explainable" | "ai-compatible";
-interface ExplainableShellProps extends BaseComponentProps {
-    /** Stage snapshots for time-travel visualization */
-    snapshots: StageSnapshot[];
-    /** Final pipeline result data */
-    resultData?: Record<string, unknown> | null;
-    /** Console log lines */
-    logs?: string[];
-    /** Combined narrative lines */
-    narrative?: string[];
-    /** Which tabs to show (default: all three) */
-    tabs?: ShellTab[];
-    /** Initially active tab */
-    defaultTab?: ShellTab;
-    /** Hide console in result tab */
-    hideConsole?: boolean;
-    /** Custom content to render in each tab slot */
-    renderFlowchart?: (props: {
-        snapshots: StageSnapshot[];
-        selectedIndex: number;
-        onNodeClick?: (index: number) => void;
-    }) => React.ReactNode;
-}
-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
+ * 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;
@@ -314,7 +323,72 @@ interface SpecNode {
     subflowId?: string;
     subflowName?: string;
     subflowStructure?: SpecNode;
+    /** True when this subflow uses lazy resolution (deferred until execution). */
+    isLazy?: boolean;
+}
+
+type ShellTab = "result" | "explainable" | "ai-compatible";
+interface PanelLabels {
+    /** Left panel pill label (subflow tree). Default: "Topology" */
+    topology?: string;
+    /** Right panel pill label (memory/narrative). Default: "Details" */
+    details?: string;
+    /** Bottom panel pill label (timeline). Default: "Timeline" */
+    timeline?: string;
+}
+/** Which panels start expanded. Default: `{ details: true }` (flowchart + memory). */
+interface DefaultExpanded {
+    topology?: boolean;
+    details?: boolean;
+    timeline?: boolean;
 }
+interface ExplainableShellProps extends BaseComponentProps {
+    snapshots: StageSnapshot[];
+    spec?: SpecNode | null;
+    title?: string;
+    resultData?: Record<string, unknown> | null;
+    logs?: string[];
+    narrative?: string[];
+    narrativeEntries?: NarrativeEntry$1[];
+    tabs?: ShellTab[];
+    defaultTab?: ShellTab;
+    hideConsole?: boolean;
+    /** Customize the labels on collapsible panel pills */
+    panelLabels?: PanelLabels;
+    /** Which panels start expanded. Default: `{ details: true }` */
+    defaultExpanded?: DefaultExpanded;
+    renderFlowchart?: (props: {
+        spec: SpecNode;
+        snapshots: StageSnapshot[];
+        selectedIndex: number;
+        onNodeClick?: (indexOrId: number | string) => void;
+    }) => React.ReactNode;
+}
+declare function ExplainableShell({ snapshots, spec, title, resultData, logs, narrative, narrativeEntries, tabs, defaultTab, hideConsole, panelLabels, defaultExpanded, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
+
+interface MemoryPanelProps extends BaseComponentProps {
+    snapshots: StageSnapshot[];
+    selectedIndex: number;
+}
+declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, className, style, }: MemoryPanelProps): react_jsx_runtime.JSX.Element;
+
+interface NarrativePanelProps extends BaseComponentProps {
+    snapshots: StageSnapshot[];
+    selectedIndex: number;
+    /** Structured narrative entries (preferred — richer rendering) */
+    narrativeEntries?: NarrativeEntry$1[];
+    /** Plain narrative lines (fallback) */
+    narrative?: string[];
+}
+declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, narrative: narrativeProp, size, unstyled, className, style, }: NarrativePanelProps): react_jsx_runtime.JSX.Element;
+
+interface StoryNarrativeProps extends BaseComponentProps {
+    /** Structured narrative entries from CombinedNarrativeRecorder */
+    entries: NarrativeEntry$1[];
+    /** Number of stages to reveal (maps to snapshotIdx + 1) */
+    stageCount: number;
+}
+declare function StoryNarrative({ entries, stageCount, size, unstyled, className, style: outerStyle, }: StoryNarrativeProps): react_jsx_runtime.JSX.Element;
 
 interface SubflowTreeEntry {
     /** Node name / identifier */
@@ -399,6 +473,16 @@ interface NarrativeEntry {
  * ```
  */
 declare function toVisualizationSnapshots(runtime: RuntimeSnapshot, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
+/**
+ * Converts a footprintjs SubflowResult (stored on StageSnapshot.subflowResult)
+ * into visualization snapshots for drill-down views.
+ *
+ * SubflowResult shape (from footprintjs):
+ *   { subflowId, subflowName, treeContext: { globalContext, stageContexts, history }, parentStageId }
+ *
+ * Returns empty array if the input is not a valid SubflowResult.
+ */
+declare function subflowResultToSnapshots(subflowResult: unknown, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
 /**
  * Creates StageSnapshots from simple arrays (when you don't have a RuntimeSnapshot).
  * Useful for testing or custom data sources.
@@ -413,4 +497,4 @@ declare function createSnapshots(stages: Array<{
     subflowId?: string;
 }>): StageSnapshot[];
 
-export { type BaseComponentProps, type DarkModeTokensOptions, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, type NarrativeEntry, 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, coolLight, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useDarkModeTokens, useFootprintTheme, warmDark, warmLight };
+export { type NarrativeEntry as AdapterNarrativeEntry, type BaseComponentProps, type DarkModeTokensOptions, type DefaultExpanded, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, MemoryPanel, type MemoryPanelProps, type NarrativeEntry$1 as NarrativeEntry, NarrativeLog, type NarrativeLogProps, NarrativePanel, type NarrativePanelProps, NarrativeTrace, type NarrativeTraceProps, type PanelLabels, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageDetailMode, StageDetailPanel, type StageDetailPanelProps, type StageSnapshot, StoryNarrative, type StoryNarrativeProps, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, coolLight, createSnapshots, defaultTokens, rawDefaults, subflowResultToSnapshots, themePresets, toVisualizationSnapshots, tokensToCSSVars, useDarkModeTokens, useFootprintTheme, warmDark, warmLight };