footprint-explainable-ui 0.25.5 → 0.26.0

package/dist/index.d.cts

@@ -636,10 +636,9 @@ interface ExplainableShellProps extends BaseComponentProps {
      * and `resultData` are derived automatically. Pair with
      * `narrativeEntries` for rich per-stage narrative.
      *
-     * Usage: `<ExplainableShell runtimeSnapshot={executor.getSnapshot()} narrativeEntries={executor.getNarrativeEntries()} spec={spec} />`
+     * Usage: `<ExplainableShell runtimeSnapshot={executor.getSnapshot()} narrativeEntries={executor.getNarrativeEntries()} traceGraph={graph} runtimeOverlay={overlay} />`
      */
     runtimeSnapshot?: RuntimeSnapshotInput | null;
-    spec?: SpecNode | null;
     /**
      * Build-time graph captured live via `createTraceStructureRecorder`.
      * REQUIRED for chart rendering (v6+) — the legacy `spec` →
@@ -714,7 +713,7 @@ interface ExplainableShellProps extends BaseComponentProps {
      */
     showStageId?: boolean;
 }
-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): react.JSX.Element;
+declare function ExplainableShell({ snapshots: snapshotsProp, runtimeSnapshot, title, resultData: resultDataProp, logs, narrativeEntries, tabs, defaultTab, hideConsole, hideTabs: hideTabsProp, panelLabels, defaultExpanded, recorderViews, renderFlowchart, showStageId, traceGraph, runtimeOverlay, size, unstyled, className, style, }: ExplainableShellProps): react.JSX.Element;
 
 /**
  * TraceViewer — drop-in component that renders an `agentfootprint.exportTrace()`

package/dist/index.d.ts

@@ -636,10 +636,9 @@ interface ExplainableShellProps extends BaseComponentProps {
      * and `resultData` are derived automatically. Pair with
      * `narrativeEntries` for rich per-stage narrative.
      *
-     * Usage: `<ExplainableShell runtimeSnapshot={executor.getSnapshot()} narrativeEntries={executor.getNarrativeEntries()} spec={spec} />`
+     * Usage: `<ExplainableShell runtimeSnapshot={executor.getSnapshot()} narrativeEntries={executor.getNarrativeEntries()} traceGraph={graph} runtimeOverlay={overlay} />`
      */
     runtimeSnapshot?: RuntimeSnapshotInput | null;
-    spec?: SpecNode | null;
     /**
      * Build-time graph captured live via `createTraceStructureRecorder`.
      * REQUIRED for chart rendering (v6+) — the legacy `spec` →
@@ -714,7 +713,7 @@ interface ExplainableShellProps extends BaseComponentProps {
      */
     showStageId?: boolean;
 }
-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): react.JSX.Element;
+declare function ExplainableShell({ snapshots: snapshotsProp, runtimeSnapshot, title, resultData: resultDataProp, logs, narrativeEntries, tabs, defaultTab, hideConsole, hideTabs: hideTabsProp, panelLabels, defaultExpanded, recorderViews, renderFlowchart, showStageId, traceGraph, runtimeOverlay, size, unstyled, className, style, }: ExplainableShellProps): react.JSX.Element;
 
 /**
  * TraceViewer — drop-in component that renders an `agentfootprint.exportTrace()`

package/dist/index.js

@@ -5927,42 +5927,19 @@ var DetailsContent = memo8(function DetailsContent2({
     /* @__PURE__ */ jsx26("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;
@@ -6004,7 +5981,6 @@ var RightPanel = memo8(function RightPanel2({
   snapshots,
   selectedIndex,
   runtimeSnapshot,
-  spec,
   activeTab,
   allTabs,
   activeNarrativeEntries,
@@ -6050,7 +6026,7 @@ var RightPanel = memo8(function RightPanel2({
           id: tab.id,
           name: insightName(tab.name),
           render: () => {
-            if (tab.id === "narrative") return /* @__PURE__ */ jsx26(NarrativePanel, { snapshots, selectedIndex, narrativeEntries: activeNarrativeEntries, runtimeSnapshot, spec, size, style: { height: "100%" } });
+            if (tab.id === "narrative") return /* @__PURE__ */ jsx26(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);
@@ -6084,7 +6060,6 @@ function insightName(name) {
 function ExplainableShell({
   snapshots: snapshotsProp,
   runtimeSnapshot,
-  spec,
   title,
   resultData: resultDataProp,
   logs = [],
@@ -6122,9 +6097,14 @@ 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;
       }
       return /* @__PURE__ */ jsx26(
@@ -6220,24 +6200,23 @@ function ExplainableShell({
   const currentLevel = useMemo12(() => {
     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 = useMemo12(() => {
-    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 = useMemo12(() => {
     if (traceGraph?.nodes?.length) {
       return traceGraph.nodes.some((n) => n.data?.isSubflow === true);
     }
-    return !!spec && hasSubflowNodes(spec);
-  }, [traceGraph, spec]);
+    return false;
+  }, [traceGraph]);
   const rootOverlay = useMemo12(() => {
     if (isInSubflow || !snapshots.length) return { activeStage: void 0, doneStages: void 0 };
     const doneStages = new Set(snapshots.slice(0, safeIdx).map((s) => s.stageLabel));
@@ -6253,14 +6232,13 @@ function ExplainableShell({
   }, []);
   const handleDrillDown = useCallback8(
     (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 = useCallback8((level) => {
     setDrillDownStack((prev) => {
@@ -6275,23 +6253,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 = useCallback8(
     (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);
@@ -6302,7 +6278,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) {
@@ -6313,7 +6289,7 @@ function ExplainableShell({
         (activeTab === "explainable" || activeTab === "ai-compatible") && /* @__PURE__ */ jsxs23(Fragment6, { children: [
           /* @__PURE__ */ jsx26(TimeTravelControls, { snapshots: activeSnapshots, selectedIndex: safeIdx, onIndexChange: handleSnapshotChange, unstyled: true }),
           isInSubflow && /* @__PURE__ */ jsx26(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__ */ jsx26(MemoryPanel, { snapshots: activeSnapshots, selectedIndex: safeIdx, unstyled: true }),
           /* @__PURE__ */ jsx26(NarrativePanel, { snapshots: activeSnapshots, selectedIndex: safeIdx, narrativeEntries: activeNarrativeEntries, unstyled: true }),
           /* @__PURE__ */ jsx26(GanttTimeline, { snapshots: activeSnapshots, selectedIndex: safeIdx, onSelect: handleSnapshotChange, unstyled: true })
@@ -6321,7 +6297,7 @@ function ExplainableShell({
       ] })
     ] });
   }
-  const showTopology = !!effectiveRenderFlowchart && !!activeSpec;
+  const showTopology = !!effectiveRenderFlowchart && !!traceGraph;
   const detailsContent = useMemo12(() => {
     if (activeTab === "result") {
       return /* @__PURE__ */ jsx26(ResultPanel, { data: resultData ?? null, logs, hideConsole, size });
@@ -6418,7 +6394,7 @@ function ExplainableShell({
           /* ── Mobile: stacked vertical ── */
           /* @__PURE__ */ jsxs23(Fragment6, { children: [
             showTopology && /* @__PURE__ */ jsx26("div", { style: { height: 350, flexShrink: 0, overflow: "hidden" }, children: effectiveRenderFlowchart({
-              spec: activeSpec,
+              spec: null,
               snapshots: activeSnapshots,
               selectedIndex: safeIdx,
               onNodeClick: handleNodeClick,
@@ -6458,7 +6434,7 @@ function ExplainableShell({
                 /* @__PURE__ */ jsx26(VLinePill, { label: "Topology", expanded: true, side: "left", onClick: () => toggleLeft(false) })
               ] }) : /* @__PURE__ */ jsx26(VLinePill, { label: "Topology", expanded: false, side: "left", onClick: () => toggleLeft(true) })),
               showTopology ? /* @__PURE__ */ jsx26("div", { style: { flex: 1, overflow: "hidden", minWidth: 0 }, children: effectiveRenderFlowchart({
-                spec: activeSpec,
+                spec: null,
                 snapshots: activeSnapshots,
                 selectedIndex: safeIdx,
                 onNodeClick: handleNodeClick,
@@ -6473,7 +6449,6 @@ function ExplainableShell({
                   snapshots: activeSnapshots,
                   selectedIndex: safeIdx,
                   runtimeSnapshot,
-                  spec,
                   activeTab,
                   allTabs,
                   activeNarrativeEntries,
@@ -6590,7 +6565,6 @@ function TraceViewer({
     ExplainableShell,
     {
       snapshots,
-      spec: parsed.trace.spec,
       narrativeEntries: parsed.trace.narrativeEntries,
       tabs,
       defaultTab,