footprint-explainable-ui 0.18.1 → 0.19.0

package/dist/adapters/fromRuntimeSnapshot.d.ts

@@ -1,4 +1,4 @@
-import type { StageSnapshot } from "../types";
+import type { StageSnapshot, NarrativeEntry } from "../types";
 /**
  * Shape of FootPrint's RuntimeSnapshot (from FlowChartExecutor.getSnapshot()).
  * We define it here instead of importing to avoid a hard dependency on footprintjs.
@@ -8,6 +8,8 @@ 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>;
@@ -18,23 +20,51 @@ interface RuntimeStageSnapshot {
     next?: RuntimeStageSnapshot;
     children?: RuntimeStageSnapshot[];
 }
+interface RecorderSnapshot {
+    id: string;
+    name: string;
+    data: unknown;
+}
 interface RuntimeSnapshot {
     sharedState: Record<string, unknown>;
     executionTree: RuntimeStageSnapshot;
     commitLog: unknown[];
+    /** Per-subflow execution results (keyed by subflowId). */
+    subflowResults?: Record<string, unknown>;
+    /** Snapshots from recorders that implement toSnapshot() (e.g. MetricRecorder). */
+    recorders?: RecorderSnapshot[];
 }
+export type { NarrativeEntry } from '../types';
 /**
  * Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
  * suitable for visualization components.
  *
+ * The `narrativeEntries` parameter (from `executor.getNarrativeEntries()`)
+ * distributes the library's rich combined narrative per-stage.
+ * When narrative is not enabled, stages get "Narrative not available" —
+ * this adapter reflects what the library produces, nothing more.
+ *
  * Usage:
  * ```ts
  * const executor = new FlowChartExecutor(chart);
  * await executor.run();
- * const snapshots = toVisualizationSnapshots(executor.getSnapshot());
+ * const snapshots = toVisualizationSnapshots(
+ *   executor.getSnapshot(),
+ *   executor.getNarrativeEntries(),
+ * );
  * ```
  */
-export declare function toVisualizationSnapshots(runtime: RuntimeSnapshot): StageSnapshot[];
+export 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.
+ */
+export 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.
@@ -48,5 +78,4 @@ export declare function createSnapshots(stages: Array<{
     description?: string;
     subflowId?: string;
 }>): StageSnapshot[];
-export {};
 //# sourceMappingURL=fromRuntimeSnapshot.d.ts.map

package/dist/adapters/fromRuntimeSnapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fromRuntimeSnapshot.d.ts","sourceRoot":"","sources":["../../src/adapters/fromRuntimeSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACnC;AAED,UAAU,eAAe;IACvB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,EAAE,oBAAoB,CAAC;IACpC,SAAS,EAAE,OAAO,EAAE,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,GACvB,aAAa,EAAE,CAIjB;AAkFD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,GACD,aAAa,EAAE,CAkBjB"}
+{"version":3,"file":"fromRuntimeSnapshot.d.ts","sourceRoot":"","sources":["../../src/adapters/fromRuntimeSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE9D;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACnC;AAED,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,UAAU,eAAe;IACvB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,EAAE,oBAAoB,CAAC;IACpC,SAAS,EAAE,OAAO,EAAE,CAAC;IACrB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,kFAAkF;IAClF,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAID,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,EACxB,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAClC,aAAa,EAAE,CAWjB;AAgKD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,OAAO,EACtB,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAClC,aAAa,EAAE,CAoCjB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,GACD,aAAa,EAAE,CAkBjB"}

package/dist/adapters/fromRuntimeSnapshot.js

@@ -2,34 +2,142 @@
  * Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
  * suitable for visualization components.
  *
+ * The `narrativeEntries` parameter (from `executor.getNarrativeEntries()`)
+ * distributes the library's rich combined narrative per-stage.
+ * When narrative is not enabled, stages get "Narrative not available" —
+ * this adapter reflects what the library produces, nothing more.
+ *
  * Usage:
  * ```ts
  * const executor = new FlowChartExecutor(chart);
  * await executor.run();
- * const snapshots = toVisualizationSnapshots(executor.getSnapshot());
+ * const snapshots = toVisualizationSnapshots(
+ *   executor.getSnapshot(),
+ *   executor.getNarrativeEntries(),
+ * );
  * ```
  */
-export function toVisualizationSnapshots(runtime) {
+export function toVisualizationSnapshots(runtime, narrativeEntries) {
+    const stageNarrativeMap = narrativeEntries?.length
+        ? buildStageNarrativeMap(narrativeEntries)
+        : new Map();
+    // Extract per-stage timings from MetricRecorder if present in snapshot.recorders.
+    const stageTimings = extractStageTimings(runtime.recorders);
     const snapshots = [];
-    flattenTree(runtime.executionTree, snapshots, runtime.sharedState);
+    flattenTree(runtime.executionTree, snapshots, runtime.sharedState, 0, runtime.subflowResults, {}, stageNarrativeMap, stageTimings);
     return snapshots;
 }
-function flattenTree(node, out, sharedState, accumulatedMs = 0) {
-    // Estimate duration from metrics if available
-    const durationMs = typeof node.metrics?.durationMs === "number"
-        ? node.metrics.durationMs
-        : 1;
+/**
+ * Extracts per-stage duration data from recorder snapshots.
+ *
+ * Post-KeyedRecorder MetricRecorder serializes as
+ *   { name: 'Metrics', data: { steps: { [runtimeStageId]: { stageName, duration, ... } } } }
+ *
+ * Older versions emitted `data.stages[stageName].totalDuration` directly;
+ * we still accept that shape for back-compat when loading old snapshots.
+ *
+ * Stages that ran multiple times (e.g. CallLLM inside a loop) have one
+ * entry per invocation keyed by runtimeStageId — sum their durations by
+ * stageName so the GanttTimeline shows cumulative wall time per stage.
+ */
+function extractStageTimings(recorders) {
+    const timings = new Map();
+    if (!recorders)
+        return timings;
+    for (const rec of recorders) {
+        if (rec.name !== 'Metrics' || !rec.data || typeof rec.data !== 'object')
+            continue;
+        const data = rec.data;
+        // New shape: data.steps[runtimeStageId] = { stageName, duration, ... }
+        if (data.steps) {
+            for (const step of Object.values(data.steps)) {
+                const name = step?.stageName;
+                const d = step?.duration;
+                if (!name || typeof d !== 'number' || d <= 0)
+                    continue;
+                timings.set(name, Math.round((timings.get(name) ?? 0) + d));
+            }
+        }
+        // Legacy shape: data.stages[stageName].totalDuration
+        if (data.stages) {
+            for (const [stageName, metrics] of Object.entries(data.stages)) {
+                if (typeof metrics.totalDuration === 'number' && metrics.totalDuration > 0) {
+                    timings.set(stageName, Math.round(metrics.totalDuration));
+                }
+            }
+        }
+    }
+    return timings;
+}
+/**
+ * Groups narrative entries by stage name, preserving non-stage entries
+ * (conditions, forks) attached to the preceding stage.
+ */
+function buildStageNarrativeMap(entries) {
+    const map = new Map();
+    let currentStageName;
+    for (const entry of entries) {
+        if (entry.stageName) {
+            currentStageName = entry.stageName;
+        }
+        if (currentStageName) {
+            if (!map.has(currentStageName)) {
+                map.set(currentStageName, []);
+            }
+            const indent = '  '.repeat(entry.depth);
+            map.get(currentStageName).push(`${indent}${entry.text}`);
+        }
+    }
+    return map;
+}
+function flattenTree(node, out, sharedState, accumulatedMs = 0, subflowResults, cumulativeMemory = {}, stageNarrativeMap = new Map(), stageTimings = new Map()) {
+    // Prefer MetricRecorder timing (real wall-clock), then scope.$metric('durationMs'), then 0.
+    const stageName = node.name ?? node.id;
+    const durationMs = (stageName ? stageTimings.get(stageName) : undefined) ??
+        (typeof node.metrics?.durationMs === "number" ? node.metrics.durationMs : 0);
     const startMs = accumulatedMs;
-    // Build narrative from logs
-    const narrative = buildNarrative(node);
-    // Build memory from logs (key-value pairs written during this stage)
-    const memory = {};
-    if (node.logs) {
-        Object.assign(memory, node.logs);
+    // Use id for matching (stable, matches spec node ids).
+    // name may carry display prefixes like "[service-name] STAGE".
+    const stageId = node.id || node.name || 'unknown';
+    const displayName = node.name || node.id || 'unknown';
+    // Narrative comes from the library. When not available (e.g. subflow internals
+    // where the root recorder only captures enter/exit markers), build a basic
+    // narrative from the stage name, description, and data operations.
+    // Try id first, then name — narrative entries use node.name (may be prefixed)
+    // while snapshot uses node.id (stable). Both need to match for subflows.
+    const stageLines = stageNarrativeMap.get(stageId) ?? stageNarrativeMap.get(displayName);
+    let narrative;
+    if (stageLines) {
+        narrative = stageLines.join('\n');
+    }
+    else {
+        const parts = [`${displayName} executed.`];
+        if (node.description)
+            parts.push(node.description);
+        if (node.stageWrites) {
+            const keys = Object.keys(node.stageWrites);
+            if (keys.length > 0)
+                parts.push(`Wrote: ${keys.join(', ')}`);
+        }
+        narrative = parts.join('\n');
     }
+    // Build cumulative memory from stageWrites (actual setValue/updateValue calls)
+    const memory = { ...cumulativeMemory };
+    if (node.stageWrites) {
+        for (const [key, value] of Object.entries(node.stageWrites)) {
+            if (value === undefined) {
+                delete memory[key];
+            }
+            else {
+                memory[key] = value;
+            }
+        }
+    }
+    const sfResult = subflowResults?.[node.subflowId ?? stageId];
     out.push({
-        stageName: node.name || node.id,
-        stageLabel: node.name || node.id,
+        stageName: displayName,
+        stageLabel: stageId,
+        runtimeStageId: node.runtimeStageId ?? undefined,
         memory,
         narrative,
         startMs,
@@ -37,39 +145,60 @@ function flattenTree(node, out, sharedState, accumulatedMs = 0) {
         status: "done",
         ...(node.description ? { description: node.description } : undefined),
         ...(node.subflowId ? { subflowId: node.subflowId } : undefined),
+        ...(sfResult ? { subflowResult: sfResult } : undefined),
     });
     let nextMs = startMs + durationMs;
     // Handle parallel children (fork)
     if (node.children && node.children.length > 0) {
         let maxChildEnd = nextMs;
         for (const child of node.children) {
-            const childEnd = flattenTree(child, out, sharedState, nextMs);
+            const childEnd = flattenTree(child, out, sharedState, nextMs, subflowResults, memory, stageNarrativeMap, stageTimings);
             maxChildEnd = Math.max(maxChildEnd, childEnd);
         }
         nextMs = maxChildEnd;
     }
     // Handle linear continuation
     if (node.next) {
-        nextMs = flattenTree(node.next, out, sharedState, nextMs);
+        nextMs = flattenTree(node.next, out, sharedState, nextMs, subflowResults, memory, stageNarrativeMap, stageTimings);
     }
     return nextMs;
 }
-function buildNarrative(node) {
-    const parts = [];
-    if (node.name) {
-        parts.push(`Stage "${node.name}" executed.`);
-    }
-    if (node.logs && Object.keys(node.logs).length > 0) {
-        const keys = Object.keys(node.logs);
-        parts.push(`Wrote ${keys.length} key(s): ${keys.join(", ")}.`);
-    }
-    if (node.errors && Object.keys(node.errors).length > 0) {
-        parts.push(`Errors: ${JSON.stringify(node.errors)}`);
-    }
-    if (node.isFork) {
-        parts.push(`Forked into ${node.children?.length ?? 0} parallel branch(es).`);
+/**
+ * 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.
+ */
+export function subflowResultToSnapshots(subflowResult, narrativeEntries) {
+    if (!subflowResult || typeof subflowResult !== 'object')
+        return [];
+    const sf = subflowResult;
+    if (!sf.treeContext?.stageContexts)
+        return [];
+    const runtime = {
+        sharedState: sf.treeContext.globalContext ?? {},
+        executionTree: sf.treeContext.stageContexts,
+        commitLog: sf.treeContext.history ?? [],
+    };
+    const snapshots = toVisualizationSnapshots(runtime, narrativeEntries);
+    // Strip subflow prefix from stage names so they match the spec node names.
+    // Runtime names are prefixed (e.g., "analyze/SeedScope") but spec nodes
+    // use unprefixed names (e.g., "SeedScope").
+    const prefix = sf.subflowId ? `${sf.subflowId}/` : '';
+    if (prefix) {
+        for (const snap of snapshots) {
+            if (snap.stageName.startsWith(prefix)) {
+                snap.stageName = snap.stageName.slice(prefix.length);
+            }
+            if (snap.stageLabel.startsWith(prefix)) {
+                snap.stageLabel = snap.stageLabel.slice(prefix.length);
+            }
+        }
     }
-    return parts.join(" ") || `Stage ${node.id} completed.`;
+    return snapshots;
 }
 /**
  * Creates StageSnapshots from simple arrays (when you don't have a RuntimeSnapshot).

package/dist/adapters/fromRuntimeSnapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"fromRuntimeSnapshot.js","sourceRoot":"","sources":["../../src/adapters/fromRuntimeSnapshot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fromRuntimeSnapshot.js","sourceRoot":"","sources":["../../src/adapters/fromRuntimeSnapshot.ts"],"names":[],"mappings":"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"}

package/dist/components/ExplainableShell/ExplainableShell.d.ts

@@ -1,26 +1,169 @@
-import type { StageSnapshot, BaseComponentProps } from "../../types";
-export type ShellTab = "result" | "explainable" | "ai-compatible";
+import type { StageSnapshot, BaseComponentProps, NarrativeEntry } from "../../types";
+/**
+ * Minimal subflow-walking spec shape. Used INTERNALLY by drill-down
+ * resolution (which navigates `subflowStructure` to find a child chart
+ * inside the parent's serialized structure). No longer used for chart
+ * rendering — that happens via `traceGraph` + `<TracedFlow>` exclusively.
+ *
+ * Kept as a local type so the file no longer depends on any legacy
+ * spec-walk module.
+ */
+export interface SpecNode {
+    name: string;
+    id?: string;
+    description?: string;
+    children?: SpecNode[];
+    next?: SpecNode;
+    isSubflowRoot?: boolean;
+    subflowId?: string;
+    subflowName?: string;
+    subflowStructure?: SpecNode;
+}
+/** Tab ID — "result", "memory", "narrative", or any custom recorder view ID. */
+export type ShellTab = string;
+export 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). */
+export interface DefaultExpanded {
+    topology?: boolean;
+    details?: boolean;
+    timeline?: boolean;
+}
+/**
+ * Raw runtime snapshot from FlowChartExecutor.getSnapshot().
+ * When provided, ExplainableShell converts it internally — zero boilerplate.
+ */
+export interface RuntimeSnapshotInput {
+    sharedState: Record<string, unknown>;
+    executionTree: unknown;
+    commitLog: unknown[];
+    subflowResults?: Record<string, unknown>;
+    /** Recorder snapshots from toSnapshot() — auto-generates detail tabs. */
+    recorders?: Array<{
+        id: string;
+        name: string;
+        description?: string;
+        preferredOperation?: 'translate' | 'accumulate' | 'aggregate';
+        data: unknown;
+    }>;
+}
+/**
+ * A recorder view that appears as a tab in the details panel.
+ * Each recorder provides its own per-stage rendering.
+ * Memory and Narrative are built-in defaults — add more via this prop.
+ */
+export interface RecorderView {
+    /** Unique key for this view tab */
+    id: string;
+    /** Display label on the tab */
+    name: string;
+    /** Short description shown as tooltip and header for auto-detected views.
+     *  e.g., "Per-step timing and I/O counts (KeyedRecorder)" */
+    description?: string;
+    /**
+     * Render function — receives the current snapshot index and all snapshots.
+     * Return a React node to display in the details panel.
+     */
+    render: (props: {
+        snapshots: StageSnapshot[];
+        selectedIndex: number;
+    }) => React.ReactNode;
+}
 export interface ExplainableShellProps extends BaseComponentProps {
-    /** Stage snapshots for time-travel visualization */
-    snapshots: StageSnapshot[];
-    /** Final pipeline result data */
+    /**
+     * Pre-converted visualization snapshots. Use when you've already called
+     * toVisualizationSnapshots() yourself.
+     */
+    snapshots?: StageSnapshot[];
+    /**
+     * Raw runtime snapshot from executor.getSnapshot(). The shell converts it
+     * internally via toVisualizationSnapshots(). When provided, `snapshots`
+     * and `resultData` are derived automatically. Pair with
+     * `narrativeEntries` for rich per-stage narrative.
+     *
+     * Usage: `<ExplainableShell runtimeSnapshot={executor.getSnapshot()} narrativeEntries={executor.getNarrativeEntries()} spec={spec} />`
+     */
+    runtimeSnapshot?: RuntimeSnapshotInput | null;
+    spec?: SpecNode | null;
+    /**
+     * Build-time graph captured live via `createTraceStructureRecorder`.
+     * REQUIRED for chart rendering (v6+) — the legacy `spec` →
+     * legacy spec-walk post-walk path was removed in favor of this
+     * recorder-driven graph.
+     *
+     * Pair with `runtimeOverlay` for the full time-travel trace UI.
+     * When `traceGraph` is set but `runtimeOverlay` is absent, the
+     * chart renders without runtime coloring (build-time-only view).
+     *
+     * The `spec` prop, when also provided, is used INTERNALLY for
+     * subflow drill-down resolution (navigating `subflowStructure` to
+     * find a child chart inside the parent's serialized structure) —
+     * NOT for rendering.
+     */
+    traceGraph?: import("../FlowchartView/traceStructureRecorder").TraceGraph | null;
+    /**
+     * Runtime overlay captured live via `createTraceRuntimeOverlay`.
+     * Pair with `traceGraph` to drive `<TracedFlow>` for the full
+     * time-travel trace UI.
+     */
+    runtimeOverlay?: import("../FlowchartView/createTraceRuntimeOverlay").RuntimeOverlay | null;
+    title?: string;
     resultData?: Record<string, unknown> | null;
-    /** Console log lines */
     logs?: string[];
-    /** Combined narrative lines */
-    narrative?: string[];
-    /** Which tabs to show (default: all three) */
+    /** Structured narrative entries from `executor.getNarrativeEntries()`.
+     *  This is the only narrative input — the flat-string form was
+     *  removed; call `.map(e => e.text)` if you need it. */
+    narrativeEntries?: NarrativeEntry[];
     tabs?: ShellTab[];
-    /** Initially active tab */
     defaultTab?: ShellTab;
-    /** Hide console in result tab */
     hideConsole?: boolean;
-    /** Custom content to render in each tab slot */
+    /** Hide specific detail tabs (e.g., ['result', 'memory']). */
+    hideTabs?: string[];
+    /** Customize the labels on collapsible panel pills */
+    panelLabels?: PanelLabels;
+    /** Which panels start expanded. Default: `{ details: true }` */
+    defaultExpanded?: DefaultExpanded;
+    /**
+     * Recorder views — each becomes a tab in the details panel.
+     * Default: Memory + Narrative. Pass additional recorder views
+     * to show tokens, cost, tools, permissions, or custom data.
+     *
+     * Usage:
+     *   recorderViews={[
+     *     { id: 'tokens', name: 'Tokens', render: ({ selectedIndex }) => <div>...</div> },
+     *   ]}
+     */
+    recorderViews?: RecorderView[];
+    /**
+     * Custom flowchart renderer. When omitted, ExplainableShell renders
+     * via `<TracedFlow graph={traceGraph} overlay={runtimeOverlay} />` —
+     * the recorder-driven path. Override to plug a custom chart UI; the
+     * `spec` parameter is forwarded only for backward-compatible
+     * signatures (it's the same SpecNode used for drill-down) and may
+     * be `null` once consumers stop threading it in.
+     */
     renderFlowchart?: (props: {
+        spec: SpecNode | null;
         snapshots: StageSnapshot[];
         selectedIndex: number;
-        onNodeClick?: (index: number) => void;
+        onNodeClick?: (indexOrId: number | string) => void;
+        showStageId?: boolean;
     }) => React.ReactNode;
+    /**
+     * When true, render each node's stable `stageId` as a small monospace
+     * caption beneath the label in the default flowchart renderer.
+     * Teaching aid: it reveals the key recorders use
+     * (`runtimeStageId = [subflowPath/]stageId#executionIndex`) so a
+     * consumer can map any recorder's per-stage data back to a node.
+     * Default false.
+     */
+    showStageId?: boolean;
 }
-export declare function ExplainableShell({ snapshots, resultData, logs, narrative, tabs, defaultTab, hideConsole, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): import("react/jsx-runtime").JSX.Element;
+export declare function ExplainableShell({ snapshots: snapshotsProp, runtimeSnapshot, spec, title, resultData: resultDataProp, logs, narrativeEntries, tabs, defaultTab, hideConsole, hideTabs: hideTabsProp, panelLabels, defaultExpanded, recorderViews, renderFlowchart, showStageId, traceGraph, runtimeOverlay, size, unstyled, className, style, }: ExplainableShellProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ExplainableShell.d.ts.map

package/dist/components/ExplainableShell/ExplainableShell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExplainableShell.d.ts","sourceRoot":"","sources":["../../../src/components/ExplainableShell/ExplainableShell.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAarE,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,eAAe,CAAC;AAElE,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,oDAAoD;IACpD,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC;IAClB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,QAAQ,CAAC;IACtB,iCAAiC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,SAAS,EAAE,aAAa,EAAE,CAAC;QAC3B,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;KACvC,KAAK,KAAK,CAAC,SAAS,CAAC;CACvB;AAMD,wBAAgB,gBAAgB,CAAC,EAC/B,SAAS,EACT,UAAU,EACV,IAAS,EACT,SAAc,EACd,IAAiD,EACjD,UAAU,EACV,WAAmB,EACnB,eAAe,EACf,IAAgB,EAChB,QAAgB,EAChB,SAAS,EACT,KAAK,GACN,EAAE,qBAAqB,2CAoQvB"}
+{"version":3,"file":"ExplainableShell.d.ts","sourceRoot":"","sources":["../../../src/components/ExplainableShell/ExplainableShell.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAarF;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,QAAQ,CAAC;CAC7B;AASD,gFAAgF;AAChF,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAc9B,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,OAAO,EAAE,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,yEAAyE;IACzE,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,WAAW,CAAC;QAC9D,IAAI,EAAE,OAAO,CAAC;KACf,CAAC,CAAC;CACJ;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb;iEAC6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,aAAa,EAAE,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,KAAK,KAAK,CAAC,SAAS,CAAC;CAC3F;AAED,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D;;;OAGG;IACH,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC9C,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAE,OAAO,yCAAyC,EAAE,UAAU,GAAG,IAAI,CAAC;IACjF;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,4CAA4C,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;4DAEwD;IACxD,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;IACpC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,QAAQ,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,sDAAsD;IACtD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,gEAAgE;IAChE,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;QACtB,SAAS,EAAE,aAAa,EAAE,CAAC;QAC3B,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC;QACnD,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,KAAK,KAAK,CAAC,SAAS,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA+nBD,wBAAgB,gBAAgB,CAAC,EAC/B,SAAS,EAAE,aAAa,EACxB,eAAe,EACf,IAAI,EACJ,KAAK,EACL,UAAU,EAAE,cAAc,EAC1B,IAAS,EACT,gBAAgB,EAChB,IAAgC,EAChC,UAAU,EACV,WAAmB,EACnB,QAAQ,EAAE,YAAY,EACtB,WAAW,EACX,eAAe,EACf,aAAa,EACb,eAAe,EACf,WAAmB,EACnB,UAAU,EACV,cAAc,EACd,IAAgB,EAChB,QAAgB,EAChB,SAAS,EACT,KAAK,GACN,EAAE,qBAAqB,2CAshBvB"}