footprint-explainable-ui 0.25.5 → 0.26.1

package/README.md

@@ -10,6 +10,8 @@
 
 Themeable React components for visualizing [footprintjs](https://github.com/footprintjs/footPrint) pipeline execution — time-travel debugging, flowchart overlays, subflow drill-down, and collapsible detail panels.
 
+> Part of the **[footprintjs ecosystem](https://footprintjs.github.io/)** — the self-explaining stack.
+
 ## Install
 
 ```bash
@@ -52,25 +54,16 @@ const snapshots = toVisualizationSnapshots(
 
 ```tsx
 import { ExplainableShell } from "footprint-explainable-ui";
-import { TracedFlowchartView } from "footprint-explainable-ui/flowchart";
 
-function DebugView({ snapshots, spec, narrative, narrativeEntries }) {
+function DebugView({ snapshots, narrativeEntries, traceGraph, runtimeOverlay }) {
   return (
     <ExplainableShell
       snapshots={snapshots}
-      spec={spec}
-      narrative={narrative}
       narrativeEntries={narrativeEntries}
+      traceGraph={traceGraph}
+      runtimeOverlay={runtimeOverlay}
       title="My Pipeline"
       panelLabels={{ topology: "What Ran", details: "What Happened", timeline: "How Long" }}
-      renderFlowchart={({ spec, snapshots, selectedIndex, onNodeClick }) => (
-        <TracedFlowchartView
-          spec={spec}
-          snapshots={snapshots}
-          snapshotIndex={selectedIndex}
-          onNodeClick={onNodeClick}
-        />
-      )}
     />
   );
 }
@@ -132,7 +125,8 @@ The all-in-one orchestrator. Handles time-travel, subflow drill-down, memory/nar
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `snapshots` | `StageSnapshot[]` | required | Visualization snapshots |
-| `spec` | `SpecNode \| null` | — | Pipeline spec (enables flowchart + subflow tree) |
+| `traceGraph` | `TraceGraph \| null` | — | Build-time graph — drives the flowchart + subflow drill-down |
+| `runtimeOverlay` | `RuntimeOverlay` | — | Per-step execution overlay — lights the executed path |
 | `title` | `string` | `"Flowchart"` | Breadcrumb root label |
 | `narrative` | `string[]` | — | Flat narrative lines |
 | `narrativeEntries` | `NarrativeEntry[]` | — | Structured narrative (rich rendering) |
@@ -164,7 +158,7 @@ Control which panels start open. Desktop default: details panel open (flowchart
 
 ```tsx
 // Desktop (default) — memory panel open
-<ExplainableShell snapshots={...} spec={...} />
+<ExplainableShell snapshots={...} traceGraph={...} runtimeOverlay={...} />
 
 // Mobile — all collapsed, flowchart fills screen
 <ExplainableShell
@@ -378,6 +372,20 @@ pipeline and snapshot-asserts the outputs in `test/golden/__snapshots__/`.
 `footprintjs` is a devDependency used ONLY by the generator — the published
 library still has zero footprintjs dependency (it consumes plain JSON shapes).
 
+## The footprintjs ecosystem
+
+The self-explaining stack — from backend pipelines to AI agents. → **[overview](https://footprintjs.github.io/)**
+
+| Project | Role |
+|---|---|
+| [footprintjs](https://footprintjs.github.io/footPrint/) | the flowchart pattern (core engine) |
+| [agentfootprint](https://footprintjs.github.io/agentfootprint/) | build self-explaining AI agents |
+| **Explainable UI** ← you are here | visualize a footprintjs run |
+| [Lens](https://github.com/footprintjs/agentfootprint-lens) | debug an agentfootprint run |
+| [Thinking UI](https://footprintjs.github.io/agentThinkingUI/) | replay an agent run for non-devs |
+
+---
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -5994,42 +5994,19 @@ var DetailsContent = (0, import_react31.memo)(function DetailsContent2({
     /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("div", { style: { flex: 1, overflow: "auto" }, children: activeView?.render({ snapshots, selectedIndex }) })
   ] });
 });
-function resolveSubflowLevel(parentSpec, parentSnapshots, subflowNodeName, narrativeEntries) {
-  const specNode = findSubflowSpecNode(parentSpec, subflowNodeName);
-  if (!specNode?.subflowStructure) return null;
-  const parentSnap = parentSnapshots.find(
-    (s) => s.stageName === subflowNodeName || s.stageLabel === subflowNodeName
-  );
+function resolveSubflowFromRuntime(parentSnapshots, subflowId, narrativeEntries) {
+  const localId = subflowId.split("/").pop() ?? subflowId;
+  const parentSnap = parentSnapshots.find((s) => {
+    if (!s.subflowResult) return false;
+    const sfStageId = s.runtimeStageId?.split("#")[0]?.split("/").pop();
+    return s.subflowId === subflowId || s.subflowId === localId || s.stageName === subflowId || s.stageLabel === subflowId || sfStageId === subflowId || sfStageId === localId;
+  });
   if (!parentSnap?.subflowResult) return null;
-  const sfId = specNode.subflowId ?? subflowNodeName;
-  const sfDisplayName = specNode.subflowName ?? specNode.name;
-  const sfNarrative = narrativeEntries ? extractSubflowNarrative(narrativeEntries, sfId, sfDisplayName) : void 0;
+  const label = parentSnap.stageLabel ?? parentSnap.stageName ?? localId;
+  const sfNarrative = narrativeEntries ? extractSubflowNarrative(narrativeEntries, subflowId, label) : void 0;
   const sfSnapshots = subflowResultToSnapshots(parentSnap.subflowResult, sfNarrative);
   if (sfSnapshots.length === 0) return null;
-  return {
-    subflowId: specNode.subflowId ?? subflowNodeName,
-    label: specNode.subflowName ?? specNode.name,
-    spec: specNode.subflowStructure,
-    snapshots: sfSnapshots
-  };
-}
-function findSubflowSpecNode(node, name) {
-  if ((node.name === name || node.id === name) && node.isSubflowRoot) return node;
-  if (node.children) {
-    for (const child of node.children) {
-      const f = findSubflowSpecNode(child, name);
-      if (f) return f;
-    }
-  }
-  if (node.next) return findSubflowSpecNode(node.next, name);
-  return null;
-}
-function hasSubflowNodes(node) {
-  if (!node) return false;
-  if (node.isSubflowRoot) return true;
-  if (node.children?.some((c) => c && hasSubflowNodes(c))) return true;
-  if (node.next && hasSubflowNodes(node.next)) return true;
-  return false;
+  return { subflowId, label, spec: null, snapshots: sfSnapshots, narrative: sfNarrative };
 }
 function buildDataTrace(commitLog, targetRuntimeStageId, maxDepth = 10) {
   const log = commitLog;
@@ -6071,7 +6048,6 @@ var RightPanel = (0, import_react31.memo)(function RightPanel2({
   snapshots,
   selectedIndex,
   runtimeSnapshot,
-  spec,
   activeTab,
   allTabs,
   activeNarrativeEntries,
@@ -6117,7 +6093,7 @@ var RightPanel = (0, import_react31.memo)(function RightPanel2({
           id: tab.id,
           name: insightName(tab.name),
           render: () => {
-            if (tab.id === "narrative") return /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(NarrativePanel, { snapshots, selectedIndex, narrativeEntries: activeNarrativeEntries, runtimeSnapshot, spec, size, style: { height: "100%" } });
+            if (tab.id === "narrative") return /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(NarrativePanel, { snapshots, selectedIndex, narrativeEntries: activeNarrativeEntries, runtimeSnapshot, size, style: { height: "100%" } });
             const customView = recorderViews?.find((v2) => v2.id === tab.id);
             if (customView?.render) return customView.render({ snapshots, selectedIndex });
             const autoView = autoRecorderViews.find((v2) => v2.id === tab.id);
@@ -6151,7 +6127,6 @@ function insightName(name) {
 function ExplainableShell({
   snapshots: snapshotsProp,
   runtimeSnapshot,
-  spec,
   title,
   resultData: resultDataProp,
   logs = [],
@@ -6167,6 +6142,7 @@ function ExplainableShell({
   showStageId = false,
   traceGraph,
   runtimeOverlay,
+  traceTheme,
   size = "default",
   unstyled = false,
   className,
@@ -6189,16 +6165,27 @@ function ExplainableShell({
       const activeRsid = snapshots2[selectedIndex]?.runtimeStageId;
       let overlayIdx = selectedIndex;
       if (activeRsid && runtimeOverlay) {
-        const i = runtimeOverlay.executionOrder.findIndex(
+        let i = runtimeOverlay.executionOrder.findIndex(
           (s) => s.runtimeStageId === activeRsid
         );
+        if (i < 0) {
+          i = runtimeOverlay.executionOrder.findIndex(
+            (s) => s.runtimeStageId?.endsWith("/" + activeRsid)
+          );
+        }
         if (i >= 0) overlayIdx = i;
       }
+      const traceColors = traceTheme && {
+        ...traceTheme.visited !== void 0 && { done: traceTheme.visited },
+        ...traceTheme.current !== void 0 && { active: traceTheme.current },
+        ...traceTheme.mode !== void 0 && { default: traceTheme.mode === "dark" ? "#94a3b8" : "#64748b" }
+      };
       return /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(
         TracedFlow,
         {
           graph: traceGraph,
           overlay: runtimeOverlay ?? void 0,
+          colors: traceColors || void 0,
           scrubIndex: overlayIdx,
           onNodeClick: (stageId) => onNodeClick?.(stageId),
           onSubflowChange: (mountId) => {
@@ -6207,7 +6194,7 @@ function ExplainableShell({
         }
       );
     };
-  }, [traceGraph, runtimeOverlay]);
+  }, [traceGraph, runtimeOverlay, traceTheme]);
   const effectiveRenderFlowchart = renderFlowchart ?? tracedFlowRenderer;
   const leftLabel = panelLabels?.topology ?? "Topology";
   const rightLabel = panelLabels?.details ?? "Details";
@@ -6287,24 +6274,23 @@ function ExplainableShell({
   const currentLevel = (0, import_react31.useMemo)(() => {
     if (drillDownStack.length > 0) {
       const top = drillDownStack[drillDownStack.length - 1];
-      return { spec: top.spec, snapshots: top.snapshots };
+      return { spec: top.spec, snapshots: top.snapshots, narrative: top.narrative };
     }
-    return { spec: spec ?? null, snapshots };
-  }, [drillDownStack, spec, snapshots]);
+    return { spec: null, snapshots, narrative: void 0 };
+  }, [drillDownStack, snapshots]);
   const activeSnapshots = currentLevel.snapshots;
-  const activeSpec = currentLevel.spec;
   const safeIdx = activeSnapshots.length > 0 ? Math.max(0, Math.min(snapshotIdx, activeSnapshots.length - 1)) : 0;
-  const activeNarrativeEntries = isInSubflow ? void 0 : narrativeEntries;
+  const activeNarrativeEntries = isInSubflow ? currentLevel.narrative : narrativeEntries;
   const breadcrumbs = (0, import_react31.useMemo)(() => {
-    const root = { label: title || "Flowchart", spec, description: spec?.description };
+    const root = { label: title || "Flowchart", spec: null, description: void 0 };
     return [root, ...drillDownStack.map((e) => ({ label: e.label, spec: e.spec, description: void 0 }))];
-  }, [spec, title, drillDownStack]);
+  }, [title, drillDownStack]);
   const showTreeSidebar = (0, import_react31.useMemo)(() => {
     if (traceGraph?.nodes?.length) {
       return traceGraph.nodes.some((n) => n.data?.isSubflow === true);
     }
-    return !!spec && hasSubflowNodes(spec);
-  }, [traceGraph, spec]);
+    return false;
+  }, [traceGraph]);
   const rootOverlay = (0, import_react31.useMemo)(() => {
     if (isInSubflow || !snapshots.length) return { activeStage: void 0, doneStages: void 0 };
     const doneStages = new Set(snapshots.slice(0, safeIdx).map((s) => s.stageLabel));
@@ -6320,14 +6306,13 @@ function ExplainableShell({
   }, []);
   const handleDrillDown = (0, import_react31.useCallback)(
     (nodeName) => {
-      if (!activeSpec) return;
-      const entry = resolveSubflowLevel(activeSpec, activeSnapshots, nodeName, narrativeEntries);
+      const entry = resolveSubflowFromRuntime(activeSnapshots, nodeName, narrativeEntries);
       if (entry) {
         setDrillDownStack((prev) => [...prev, { ...entry, parentSnapshotIdx: snapshotIdx }]);
         setSnapshotIdx(0);
       }
     },
-    [activeSpec, activeSnapshots, narrativeEntries, snapshotIdx]
+    [activeSnapshots, narrativeEntries, snapshotIdx]
   );
   const handleBreadcrumbNavigate = (0, import_react31.useCallback)((level) => {
     setDrillDownStack((prev) => {
@@ -6342,23 +6327,21 @@ function ExplainableShell({
         setSnapshotIdx(indexOrId);
         return;
       }
-      if (activeSpec) {
-        const sfNode = findSubflowSpecNode(activeSpec, indexOrId);
-        if (sfNode?.subflowStructure) {
-          handleDrillDown(indexOrId);
-          return;
-        }
+      const drillable = resolveSubflowFromRuntime(activeSnapshots, indexOrId, narrativeEntries);
+      if (drillable) {
+        handleDrillDown(indexOrId);
+        return;
       }
       const idx = activeSnapshots.findIndex((s) => s.stageLabel === indexOrId);
       if (idx >= 0) setSnapshotIdx(idx);
     },
-    [activeSpec, activeSnapshots, handleDrillDown]
+    [activeSnapshots, narrativeEntries, handleDrillDown]
   );
   const handleTreeNodeSelect = (0, import_react31.useCallback)(
     (name, isSubflow) => {
-      if (isSubflow && spec) {
+      if (isSubflow) {
         setDrillDownStack([]);
-        const entry = resolveSubflowLevel(spec, snapshots, name, narrativeEntries);
+        const entry = resolveSubflowFromRuntime(snapshots, name, narrativeEntries);
         if (entry) {
           setDrillDownStack([{ ...entry, parentSnapshotIdx: snapshotIdx }]);
           setSnapshotIdx(0);
@@ -6369,7 +6352,7 @@ function ExplainableShell({
         if (idx >= 0) setSnapshotIdx(idx);
       }
     },
-    [spec, snapshots, narrativeEntries, snapshotIdx]
+    [snapshots, narrativeEntries, snapshotIdx]
   );
   const tabLabels = new Map(allTabs.map((t) => [t.id, t.name]));
   if (unstyled) {
@@ -6380,7 +6363,7 @@ function ExplainableShell({
         (activeTab === "explainable" || activeTab === "ai-compatible") && /* @__PURE__ */ (0, import_jsx_runtime26.jsxs)(import_jsx_runtime26.Fragment, { children: [
           /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(TimeTravelControls, { snapshots: activeSnapshots, selectedIndex: safeIdx, onIndexChange: handleSnapshotChange, unstyled: true }),
           isInSubflow && /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(SubflowBreadcrumb, { breadcrumbs, onNavigate: handleBreadcrumbNavigate }),
-          activeSpec && effectiveRenderFlowchart?.({ spec: activeSpec, snapshots: activeSnapshots, selectedIndex: safeIdx, onNodeClick: handleNodeClick, showStageId }),
+          traceGraph && effectiveRenderFlowchart?.({ spec: null, snapshots: activeSnapshots, selectedIndex: safeIdx, onNodeClick: handleNodeClick, showStageId }),
           /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(MemoryPanel, { snapshots: activeSnapshots, selectedIndex: safeIdx, unstyled: true }),
           /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(NarrativePanel, { snapshots: activeSnapshots, selectedIndex: safeIdx, narrativeEntries: activeNarrativeEntries, unstyled: true }),
           /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(GanttTimeline, { snapshots: activeSnapshots, selectedIndex: safeIdx, onSelect: handleSnapshotChange, unstyled: true })
@@ -6388,7 +6371,7 @@ function ExplainableShell({
       ] })
     ] });
   }
-  const showTopology = !!effectiveRenderFlowchart && !!activeSpec;
+  const showTopology = !!effectiveRenderFlowchart && !!traceGraph;
   const detailsContent = (0, import_react31.useMemo)(() => {
     if (activeTab === "result") {
       return /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(ResultPanel, { data: resultData ?? null, logs, hideConsole, size });
@@ -6485,7 +6468,7 @@ function ExplainableShell({
           /* ── Mobile: stacked vertical ── */
           /* @__PURE__ */ (0, import_jsx_runtime26.jsxs)(import_jsx_runtime26.Fragment, { children: [
             showTopology && /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("div", { style: { height: 350, flexShrink: 0, overflow: "hidden" }, children: effectiveRenderFlowchart({
-              spec: activeSpec,
+              spec: null,
               snapshots: activeSnapshots,
               selectedIndex: safeIdx,
               onNodeClick: handleNodeClick,
@@ -6525,7 +6508,7 @@ function ExplainableShell({
                 /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(VLinePill, { label: "Topology", expanded: true, side: "left", onClick: () => toggleLeft(false) })
               ] }) : /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(VLinePill, { label: "Topology", expanded: false, side: "left", onClick: () => toggleLeft(true) })),
               showTopology ? /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("div", { style: { flex: 1, overflow: "hidden", minWidth: 0 }, children: effectiveRenderFlowchart({
-                spec: activeSpec,
+                spec: null,
                 snapshots: activeSnapshots,
                 selectedIndex: safeIdx,
                 onNodeClick: handleNodeClick,
@@ -6540,7 +6523,6 @@ function ExplainableShell({
                   snapshots: activeSnapshots,
                   selectedIndex: safeIdx,
                   runtimeSnapshot,
-                  spec,
                   activeTab,
                   allTabs,
                   activeNarrativeEntries,
@@ -6657,7 +6639,6 @@ function TraceViewer({
     ExplainableShell,
     {
       snapshots,
-      spec: parsed.trace.spec,
       narrativeEntries: parsed.trace.narrativeEntries,
       tabs,
       defaultTab,