footprint-explainable-ui 0.13.2 → 0.14.0

package/dist/index.d.cts

@@ -7,6 +7,8 @@ interface StageSnapshot {
     stageName: string;
     /** Human-readable label */
     stageLabel: string;
+    /** Unique per-execution-step identifier. Format: [subflowPath/]stageId#executionIndex. Key for recorder Map lookup. */
+    runtimeStageId?: string;
     /** Accumulated memory state after this stage ran */
     memory: Record<string, unknown>;
     /** Narrative text describing what happened */
@@ -26,15 +28,24 @@ interface StageSnapshot {
 }
 /** Structured narrative entry — preserves type info for semantic rendering. */
 interface NarrativeEntry {
-    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error';
+    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error' | 'pause' | 'resume';
     text: string;
     depth: number;
     stageName?: string;
     /** Stable stage identifier (matches spec node id). Primary key for UI sync. */
     stageId?: string;
+    /** Unique per-execution-step identifier. Format: [subflowPath/]stageId#executionIndex.
+     *  Used for exact time-travel sync (preferred over stageId for progressive reveal). */
+    runtimeStageId?: string;
     /** Subflow ID when this entry was generated inside a subflow. */
     subflowId?: string;
+    /** Direction for subflow entries: 'entry' when entering, 'exit' when leaving. */
+    direction?: 'entry' | 'exit';
     stepNumber?: number;
+    /** Scope key that was read or written. Only present on 'step' entries. */
+    key?: string;
+    /** Raw value from the scope event. Only present on 'step' entries. */
+    rawValue?: unknown;
 }
 /** Component size variants */
 type Size = "compact" | "default" | "detailed";
@@ -373,6 +384,9 @@ interface RecorderView {
     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.
@@ -563,4 +577,63 @@ declare function createSnapshots(stages: Array<{
     subflowId?: string;
 }>): StageSnapshot[];
 
-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, NarrativeLog, type NarrativeLogProps, NarrativePanel, type NarrativePanelProps, NarrativeTrace, type NarrativeTraceProps, type PanelLabels, type RecorderView, ResultPanel, type ResultPanelProps, type RuntimeSnapshotInput, 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 };
+/**
+ * Narrative sync utilities — shared logic for mapping timeline position
+ * to narrative entries. Used by NarrativePanel and available to consumers
+ * building custom visualization shells.
+ */
+
+/**
+ * Range index: runtimeStageId → half-open range [firstIdx, endIdx) in entries array.
+ *
+ * This is the same shape as `SequenceRecorder.getEntryRanges()` in footprintjs.
+ * When you have recorder access, pass `recorder.getEntryRanges()` directly.
+ * When you only have the flat array, use `buildEntryRangeIndex()` to build it.
+ */
+type EntryRangeIndex = ReadonlyMap<string, {
+    readonly firstIdx: number;
+    readonly endIdx: number;
+}>;
+/**
+ * Build a range index from a flat entries array for O(1) per-step lookups.
+ * Equivalent to `SequenceRecorder.getEntryRanges()` but works on detached arrays.
+ *
+ * Call once when narrativeEntries changes, then pass to `computeRevealedEntryCount`.
+ *
+ * @param entries — structured entries (from CombinedNarrativeRecorder.getEntries() or getNarrativeEntries())
+ * @returns range index for fast slider sync
+ */
+declare function buildEntryRangeIndex(entries: Pick<NarrativeEntry, "runtimeStageId">[]): EntryRangeIndex;
+/**
+ * Compute how many narrative entries to reveal at a given slider position.
+ *
+ * **With range index (preferred):** O(selectedIndex) — one Map lookup per snapshot.
+ * **Without index (convenience):** O(entries) forward scan.
+ *
+ * The range index can come from:
+ * - `SequenceRecorder.getEntryRanges()` (when you have recorder access)
+ * - `buildEntryRangeIndex(entries)` (when you only have the flat array)
+ *
+ * @param narrativeEntries — structured entries from CombinedNarrativeRecorder
+ * @param snapshots — execution timeline (from adapter)
+ * @param selectedIndex — current slider position (0-based)
+ * @param rangeIndex — optional precomputed range index for O(1) lookups
+ * @returns number of entries to reveal (0 to narrativeEntries.length)
+ */
+declare function computeRevealedEntryCount(narrativeEntries: NarrativeEntry[], snapshots: Pick<StageSnapshot, "runtimeStageId">[], selectedIndex: number, rangeIndex?: EntryRangeIndex): number;
+/**
+ * Extract narrative entries belonging to a specific subflow.
+ *
+ * Three-tier matching (most reliable first):
+ * 1. `stageName` prefix match (e.g., entries with `stageName` starting with `"sf-pay/"`)
+ * 2. `subflowId` field match
+ * 3. `direction` field on subflow entry/exit markers (renderer-agnostic)
+ *
+ * @param entries — all narrative entries from the execution
+ * @param subflowId — subflow identifier to extract
+ * @param subflowName — optional display name for fallback matching
+ * @returns entries belonging to the subflow
+ */
+declare function extractSubflowNarrative(entries: NarrativeEntry[], subflowId: string, subflowName?: string): NarrativeEntry[];
+
+export { type NarrativeEntry as AdapterNarrativeEntry, type BaseComponentProps, type DarkModeTokensOptions, type DefaultExpanded, type DiffEntry, type EntryRangeIndex, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, MemoryPanel, type MemoryPanelProps, type NarrativeEntry, NarrativeLog, type NarrativeLogProps, NarrativePanel, type NarrativePanelProps, NarrativeTrace, type NarrativeTraceProps, type PanelLabels, type RecorderView, ResultPanel, type ResultPanelProps, type RuntimeSnapshotInput, 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, buildEntryRangeIndex, computeRevealedEntryCount, coolDark, coolLight, createSnapshots, defaultTokens, extractSubflowNarrative, rawDefaults, subflowResultToSnapshots, themePresets, toVisualizationSnapshots, tokensToCSSVars, useDarkModeTokens, useFootprintTheme, warmDark, warmLight };

package/dist/index.d.ts

@@ -7,6 +7,8 @@ interface StageSnapshot {
     stageName: string;
     /** Human-readable label */
     stageLabel: string;
+    /** Unique per-execution-step identifier. Format: [subflowPath/]stageId#executionIndex. Key for recorder Map lookup. */
+    runtimeStageId?: string;
     /** Accumulated memory state after this stage ran */
     memory: Record<string, unknown>;
     /** Narrative text describing what happened */
@@ -26,15 +28,24 @@ interface StageSnapshot {
 }
 /** Structured narrative entry — preserves type info for semantic rendering. */
 interface NarrativeEntry {
-    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error';
+    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error' | 'pause' | 'resume';
     text: string;
     depth: number;
     stageName?: string;
     /** Stable stage identifier (matches spec node id). Primary key for UI sync. */
     stageId?: string;
+    /** Unique per-execution-step identifier. Format: [subflowPath/]stageId#executionIndex.
+     *  Used for exact time-travel sync (preferred over stageId for progressive reveal). */
+    runtimeStageId?: string;
     /** Subflow ID when this entry was generated inside a subflow. */
     subflowId?: string;
+    /** Direction for subflow entries: 'entry' when entering, 'exit' when leaving. */
+    direction?: 'entry' | 'exit';
     stepNumber?: number;
+    /** Scope key that was read or written. Only present on 'step' entries. */
+    key?: string;
+    /** Raw value from the scope event. Only present on 'step' entries. */
+    rawValue?: unknown;
 }
 /** Component size variants */
 type Size = "compact" | "default" | "detailed";
@@ -373,6 +384,9 @@ interface RecorderView {
     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.
@@ -563,4 +577,63 @@ declare function createSnapshots(stages: Array<{
     subflowId?: string;
 }>): StageSnapshot[];
 
-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, NarrativeLog, type NarrativeLogProps, NarrativePanel, type NarrativePanelProps, NarrativeTrace, type NarrativeTraceProps, type PanelLabels, type RecorderView, ResultPanel, type ResultPanelProps, type RuntimeSnapshotInput, 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 };
+/**
+ * Narrative sync utilities — shared logic for mapping timeline position
+ * to narrative entries. Used by NarrativePanel and available to consumers
+ * building custom visualization shells.
+ */
+
+/**
+ * Range index: runtimeStageId → half-open range [firstIdx, endIdx) in entries array.
+ *
+ * This is the same shape as `SequenceRecorder.getEntryRanges()` in footprintjs.
+ * When you have recorder access, pass `recorder.getEntryRanges()` directly.
+ * When you only have the flat array, use `buildEntryRangeIndex()` to build it.
+ */
+type EntryRangeIndex = ReadonlyMap<string, {
+    readonly firstIdx: number;
+    readonly endIdx: number;
+}>;
+/**
+ * Build a range index from a flat entries array for O(1) per-step lookups.
+ * Equivalent to `SequenceRecorder.getEntryRanges()` but works on detached arrays.
+ *
+ * Call once when narrativeEntries changes, then pass to `computeRevealedEntryCount`.
+ *
+ * @param entries — structured entries (from CombinedNarrativeRecorder.getEntries() or getNarrativeEntries())
+ * @returns range index for fast slider sync
+ */
+declare function buildEntryRangeIndex(entries: Pick<NarrativeEntry, "runtimeStageId">[]): EntryRangeIndex;
+/**
+ * Compute how many narrative entries to reveal at a given slider position.
+ *
+ * **With range index (preferred):** O(selectedIndex) — one Map lookup per snapshot.
+ * **Without index (convenience):** O(entries) forward scan.
+ *
+ * The range index can come from:
+ * - `SequenceRecorder.getEntryRanges()` (when you have recorder access)
+ * - `buildEntryRangeIndex(entries)` (when you only have the flat array)
+ *
+ * @param narrativeEntries — structured entries from CombinedNarrativeRecorder
+ * @param snapshots — execution timeline (from adapter)
+ * @param selectedIndex — current slider position (0-based)
+ * @param rangeIndex — optional precomputed range index for O(1) lookups
+ * @returns number of entries to reveal (0 to narrativeEntries.length)
+ */
+declare function computeRevealedEntryCount(narrativeEntries: NarrativeEntry[], snapshots: Pick<StageSnapshot, "runtimeStageId">[], selectedIndex: number, rangeIndex?: EntryRangeIndex): number;
+/**
+ * Extract narrative entries belonging to a specific subflow.
+ *
+ * Three-tier matching (most reliable first):
+ * 1. `stageName` prefix match (e.g., entries with `stageName` starting with `"sf-pay/"`)
+ * 2. `subflowId` field match
+ * 3. `direction` field on subflow entry/exit markers (renderer-agnostic)
+ *
+ * @param entries — all narrative entries from the execution
+ * @param subflowId — subflow identifier to extract
+ * @param subflowName — optional display name for fallback matching
+ * @returns entries belonging to the subflow
+ */
+declare function extractSubflowNarrative(entries: NarrativeEntry[], subflowId: string, subflowName?: string): NarrativeEntry[];
+
+export { type NarrativeEntry as AdapterNarrativeEntry, type BaseComponentProps, type DarkModeTokensOptions, type DefaultExpanded, type DiffEntry, type EntryRangeIndex, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, MemoryPanel, type MemoryPanelProps, type NarrativeEntry, NarrativeLog, type NarrativeLogProps, NarrativePanel, type NarrativePanelProps, NarrativeTrace, type NarrativeTraceProps, type PanelLabels, type RecorderView, ResultPanel, type ResultPanelProps, type RuntimeSnapshotInput, 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, buildEntryRangeIndex, computeRevealedEntryCount, coolDark, coolLight, createSnapshots, defaultTokens, extractSubflowNarrative, rawDefaults, subflowResultToSnapshots, themePresets, toVisualizationSnapshots, tokensToCSSVars, useDarkModeTokens, useFootprintTheme, warmDark, warmLight };

package/dist/index.js

@@ -2203,6 +2203,81 @@ function TimeTravelControls({
 // src/components/ExplainableShell/ExplainableShell.tsx
 import { memo as memo4, useState as useState9, useCallback as useCallback7, useMemo as useMemo11, useRef as useRef7, useEffect as useEffect8 } from "react";
 
+// src/utils/narrativeSync.ts
+function buildEntryRangeIndex(entries) {
+  const ranges = /* @__PURE__ */ new Map();
+  let lastId;
+  for (let i = 0; i < entries.length; i++) {
+    const id = entries[i].runtimeStageId;
+    if (id) {
+      const existing = ranges.get(id);
+      if (!existing) {
+        ranges.set(id, { firstIdx: i, endIdx: i + 1 });
+      } else {
+        existing.endIdx = i + 1;
+      }
+      lastId = id;
+    } else if (lastId) {
+      ranges.get(lastId).endIdx = i + 1;
+    }
+  }
+  return ranges;
+}
+function computeRevealedEntryCount(narrativeEntries, snapshots, selectedIndex, rangeIndex) {
+  if (!narrativeEntries.length || snapshots.length === 0) return 0;
+  if (rangeIndex) {
+    let maxEndIdx = 0;
+    for (let si = 0; si <= selectedIndex && si < snapshots.length; si++) {
+      const targetId = snapshots[si].runtimeStageId;
+      if (!targetId) continue;
+      const range = rangeIndex.get(targetId);
+      if (range && range.endIdx > maxEndIdx) {
+        maxEndIdx = range.endIdx;
+      }
+    }
+    return maxEndIdx;
+  }
+  let entryIdx = 0;
+  for (let si = 0; si <= selectedIndex && si < snapshots.length; si++) {
+    const targetId = snapshots[si].runtimeStageId;
+    if (!targetId) continue;
+    let found = false;
+    for (let j = entryIdx; j < narrativeEntries.length; j++) {
+      if (narrativeEntries[j].runtimeStageId === targetId) {
+        found = true;
+        entryIdx = j;
+        break;
+      }
+    }
+    if (!found) continue;
+    while (entryIdx < narrativeEntries.length) {
+      const eId = narrativeEntries[entryIdx].runtimeStageId;
+      if (eId && eId !== targetId) break;
+      entryIdx++;
+    }
+  }
+  return entryIdx;
+}
+function extractSubflowNarrative(entries, subflowId, subflowName) {
+  const prefix = subflowId + "/";
+  const byPrefix = entries.filter((e) => e.stageName?.startsWith(prefix));
+  if (byPrefix.length > 0) return byPrefix;
+  const byId = entries.filter((e) => e.subflowId === subflowId);
+  if (byId.length > 0) return byId;
+  const result = [];
+  const searchName = subflowName ?? subflowId;
+  let inside = false;
+  for (const entry of entries) {
+    if (entry.type === "subflow" && entry.direction === "entry" && entry.stageName === searchName) {
+      inside = true;
+      continue;
+    }
+    if (inside && entry.type === "subflow" && entry.direction === "exit" && entry.stageName === searchName) break;
+    if (inside) result.push(entry);
+  }
+  return result;
+}
+
 // src/adapters/fromRuntimeSnapshot.ts
 function toVisualizationSnapshots(runtime, narrativeEntries) {
   const stageNarrativeMap = narrativeEntries?.length ? buildStageNarrativeMap(narrativeEntries) : /* @__PURE__ */ new Map();
@@ -2278,6 +2353,7 @@ function flattenTree(node, out, sharedState, accumulatedMs = 0, subflowResults,
   out.push({
     stageName: displayName,
     stageLabel: stageId,
+    runtimeStageId: node.runtimeStageId ?? void 0,
     memory,
     narrative,
     startMs,
@@ -2630,37 +2706,14 @@ function NarrativePanel({
     const endIdx = groupsToShow < stageBoundaries.length ? stageBoundaries[groupsToShow] : narrative.length;
     return Math.max(1, endIdx);
   }, [snapshots.length, selectedIndex, narrative]);
-  const revealedEntryCount = useMemo8(() => {
-    if (!narrativeEntries?.length || snapshots.length === 0) return 0;
-    let entryIdx = 0;
-    for (let si = 0; si <= selectedIndex && si < snapshots.length; si++) {
-      const snap = snapshots[si];
-      const keys = /* @__PURE__ */ new Set();
-      if (snap.stageLabel) keys.add(snap.stageLabel);
-      if (snap.stageName) keys.add(snap.stageName);
-      if (snap.subflowId) keys.add(snap.subflowId);
-      let found = false;
-      for (let j = entryIdx; j < narrativeEntries.length; j++) {
-        const e = narrativeEntries[j];
-        const eKey = e.stageId ?? e.subflowId ?? e.stageName;
-        if (eKey && keys.has(eKey)) {
-          found = true;
-          entryIdx = j;
-          break;
-        }
-        if (!eKey && !found) {
-        }
-      }
-      if (!found) continue;
-      while (entryIdx < narrativeEntries.length) {
-        const e = narrativeEntries[entryIdx];
-        const eKey = e.stageId ?? e.subflowId ?? e.stageName;
-        if (eKey && !keys.has(eKey)) break;
-        entryIdx++;
-      }
-    }
-    return entryIdx;
-  }, [narrativeEntries, snapshots, selectedIndex]);
+  const rangeIndex = useMemo8(
+    () => narrativeEntries?.length ? buildEntryRangeIndex(narrativeEntries) : void 0,
+    [narrativeEntries]
+  );
+  const revealedEntryCount = useMemo8(
+    () => narrativeEntries?.length ? computeRevealedEntryCount(narrativeEntries, snapshots, selectedIndex, rangeIndex) : 0,
+    [narrativeEntries, snapshots, selectedIndex, rangeIndex]
+  );
   const hasStructured = narrativeEntries && narrativeEntries.length > 0;
   const [copied, setCopied] = useState7(false);
   const buildLLMNarrative = useCallback4(() => {
@@ -2676,7 +2729,7 @@ function NarrativePanel({
         root.push(entry);
       } else {
         if (entry.type === "subflow") {
-          const isExit = entry.text.startsWith("Done:") || entry.text.startsWith("Exiting");
+          const isExit = entry.direction === "exit";
           if (!isExit) {
             root.push(entry);
           }
@@ -2696,7 +2749,11 @@ function NarrativePanel({
         if (opts?.inSubflow && e.type === "subflow") continue;
         let text = e.text;
         if (opts?.inSubflow) {
-          text = text.replace(new RegExp(`\\[${opts.inSubflow}/`), "[");
+          const prefix = `[${opts.inSubflow}/`;
+          const idx = text.indexOf(prefix);
+          if (idx !== -1) {
+            text = text.slice(0, idx) + "[" + text.slice(idx + prefix.length);
+          }
         }
         const isHeading = e.type === "stage" || e.type === "subflow" || e.type === "fork" || e.type === "selector";
         if (isHeading) {
@@ -4003,6 +4060,12 @@ var DetailsContent = memo4(function DetailsContent2({
   ];
   const allViews = [...builtInViews, ...extraViews ?? []];
   const [activeViewId, setActiveViewId] = useState9(allViews[0]?.id ?? "memory");
+  const viewIds = allViews.map((v2) => v2.id).join(",");
+  useEffect8(() => {
+    if (!allViews.find((v2) => v2.id === activeViewId)) {
+      setActiveViewId(allViews[0]?.id ?? "memory");
+    }
+  }, [viewIds]);
   const activeView = allViews.find((v2) => v2.id === activeViewId) ?? allViews[0];
   return /* @__PURE__ */ jsxs17("div", { style: { flex: 1, display: "flex", flexDirection: "column", overflow: "hidden" }, children: [
     /* @__PURE__ */ jsx18("div", { style: { display: "flex", borderBottom: `1px solid ${theme.border}`, flexShrink: 0, overflowX: "auto" }, children: allViews.map((view) => {
@@ -4053,25 +4116,6 @@ function resolveSubflowLevel(parentSpec, parentSnapshots, subflowNodeName, narra
     snapshots: sfSnapshots
   };
 }
-function extractSubflowNarrative(entries, subflowId, subflowName) {
-  const prefix = subflowId + "/";
-  const byPrefix = entries.filter((e) => e.stageName?.startsWith(prefix));
-  if (byPrefix.length > 0) return byPrefix;
-  const byId = entries.filter((e) => e.subflowId === subflowId);
-  if (byId.length > 0) return byId;
-  const result = [];
-  const searchName = subflowName ?? subflowId;
-  let inside = false;
-  for (const entry of entries) {
-    if (entry.type === "subflow" && entry.text.includes(searchName) && entry.text.startsWith("Entering")) {
-      inside = true;
-      continue;
-    }
-    if (inside && entry.type === "subflow" && entry.text.includes(searchName) && entry.text.startsWith("Exiting")) break;
-    if (inside) result.push(entry);
-  }
-  return result;
-}
 function findSubflowSpecNode(node, name) {
   if ((node.name === name || node.id === name) && node.isSubflowRoot) return node;
   if (node.children) {
@@ -4160,22 +4204,22 @@ function ExplainableShell({
     const recorders = runtimeSnapshot?.recorders;
     if (!recorders?.length) return [];
     const explicitIds = new Set((recorderViews ?? []).map((v2) => v2.id));
-    return recorders.filter((r) => !explicitIds.has(r.id)).map((r) => ({ id: r.id, name: r.name, data: r.data }));
+    return recorders.filter((r) => !explicitIds.has(r.id)).map((r) => ({ id: r.id, name: r.name, description: r.description, data: r.data }));
   }, [runtimeSnapshot, recorderViews]);
   const hasNarrative = !!(narrative?.length || narrativeEntries?.length);
   const allTabs = useMemo11(() => {
     const tabs2 = [
-      { id: "result", name: "Result" },
-      { id: "memory", name: "Memory" }
+      { id: "result", name: "Result", description: "Final output and console logs" },
+      { id: "memory", name: "Memory", description: "Accumulated shared state at each stage" }
     ];
     if (hasNarrative) {
-      tabs2.push({ id: "narrative", name: "Narrative" });
+      tabs2.push({ id: "narrative", name: "Narrative", description: "What happened, what data flowed, what decisions were made" });
     }
     for (const v2 of recorderViews ?? []) {
-      tabs2.push({ id: v2.id, name: v2.name });
+      tabs2.push({ id: v2.id, name: v2.name, description: v2.description });
     }
     for (const v2 of autoRecorderViews) {
-      tabs2.push({ id: v2.id, name: v2.name });
+      tabs2.push({ id: v2.id, name: v2.name, description: v2.description });
     }
     const hideSet = new Set(hideTabsProp ?? []);
     return hideSet.size > 0 ? tabs2.filter((t) => !hideSet.has(t.id)) : tabs2;
@@ -4337,7 +4381,17 @@ function ExplainableShell({
     }
     const autoView = autoRecorderViews.find((v2) => v2.id === activeTab);
     if (autoView) {
-      return /* @__PURE__ */ jsx18("div", { style: { padding: 12, fontFamily: theme.fontMono, fontSize: 11, whiteSpace: "pre-wrap", overflow: "auto", height: "100%" }, children: typeof autoView.data === "string" ? autoView.data : JSON.stringify(autoView.data, null, 2) });
+      return /* @__PURE__ */ jsxs17("div", { style: { overflow: "auto", height: "100%", display: "flex", flexDirection: "column" }, children: [
+        autoView.description && /* @__PURE__ */ jsx18("div", { style: {
+          padding: "6px 12px",
+          fontSize: 11,
+          color: theme.textMuted,
+          fontStyle: "italic",
+          borderBottom: `1px solid ${theme.border}`,
+          flexShrink: 0
+        }, children: autoView.description }),
+        /* @__PURE__ */ jsx18("div", { style: { padding: 12, fontFamily: theme.fontMono, fontSize: 11, whiteSpace: "pre-wrap", overflow: "auto", flex: 1 }, children: typeof autoView.data === "string" ? autoView.data : JSON.stringify(autoView.data, null, 2) })
+      ] });
     }
     return null;
   }, [activeTab, resultData, logs, hideConsole, size, activeSnapshots, safeIdx, activeNarrativeEntries, activeNarrative, recorderViews, autoRecorderViews]);
@@ -4354,6 +4408,7 @@ function ExplainableShell({
         "button",
         {
           onClick: () => handleTabChange(tab.id),
+          title: tab.description,
           style: {
             padding: "6px 14px",
             fontSize: 11,
@@ -4487,10 +4542,13 @@ export {
   StoryNarrative,
   SubflowTree,
   TimeTravelControls,
+  buildEntryRangeIndex,
+  computeRevealedEntryCount,
   coolDark,
   coolLight,
   createSnapshots,
   defaultTokens,
+  extractSubflowNarrative,
   rawDefaults,
   subflowResultToSnapshots,
   themePresets,