footprint-explainable-ui 0.26.2 → 0.28.0

package/dist/index.cjs

@@ -2300,6 +2300,67 @@ function TimeTravelControls({
 // src/components/ExplainableShell/ExplainableShell.tsx
 var import_react31 = require("react");
 
+// src/components/ExplainableShell/_internal/dataTrace.ts
+function readsByStep(tree) {
+  const byStep = /* @__PURE__ */ new Map();
+  if (!tree) return byStep;
+  const visited = /* @__PURE__ */ new Set();
+  const stack = [tree];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (visited.has(node)) continue;
+    visited.add(node);
+    if (node.runtimeStageId && node.stageReads) {
+      const keys = Object.keys(node.stageReads);
+      if (keys.length > 0) byStep.set(node.runtimeStageId, keys);
+    }
+    if (node.next) stack.push(node.next);
+    if (node.children) for (const c of node.children) stack.push(c);
+  }
+  return byStep;
+}
+function buildDataTrace(commitLog, executionTree, targetRuntimeStageId, maxDepth = 10, maxFrames = 50) {
+  const log = commitLog ?? [];
+  const reads = readsByStep(executionTree);
+  const readsAvailable = reads.size > 0;
+  if (!log.length) return { frames: [], readsAvailable };
+  const idxOf = /* @__PURE__ */ new Map();
+  for (let i = 0; i < log.length; i++) idxOf.set(log[i].runtimeStageId, i);
+  const startIdx = idxOf.get(targetRuntimeStageId);
+  if (startIdx === void 0) return { frames: [], readsAvailable };
+  const findLastWriter = (key, beforeIdx) => {
+    for (let i = beforeIdx - 1; i >= 0; i--) {
+      if (log[i].trace.some((t) => t.path === key)) return i;
+    }
+    return -1;
+  };
+  const frames = [];
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [[startIdx, 0, ""]];
+  while (queue.length > 0 && frames.length < maxFrames) {
+    const [idx, depth, linkedBy] = queue.shift();
+    const commit = log[idx];
+    if (visited.has(commit.runtimeStageId)) continue;
+    visited.add(commit.runtimeStageId);
+    frames.push({
+      runtimeStageId: commit.runtimeStageId,
+      stageId: commit.stageId,
+      stageName: commit.stage,
+      keysWritten: commit.trace.map((t) => t.path),
+      linkedBy,
+      depth
+    });
+    if (depth >= maxDepth) continue;
+    for (const key of reads.get(commit.runtimeStageId) ?? []) {
+      const writerIdx = findLastWriter(key, idx);
+      if (writerIdx >= 0 && !visited.has(log[writerIdx].runtimeStageId)) {
+        queue.push([writerIdx, depth + 1, key]);
+      }
+    }
+  }
+  return { frames, readsAvailable };
+}
+
 // src/utils/narrativeSync.ts
 function buildEntryRangeIndex(entries) {
   const ranges = /* @__PURE__ */ new Map();
@@ -5031,6 +5092,7 @@ function TracedFlow({
   nodeTypes: userNodeTypes,
   edgeTypes: userEdgeTypes,
   coActiveStageIds,
+  sliceCone,
   children,
   className,
   style
@@ -5132,6 +5194,38 @@ function TracedFlow({
     ),
     [positioned.edges, slice, colors]
   );
+  const [coneRevealed, setConeRevealed] = (0, import_react25.useState)(false);
+  (0, import_react25.useEffect)(() => {
+    if (!sliceCone) return;
+    setConeRevealed(false);
+    const raf = requestAnimationFrame(() => setConeRevealed(true));
+    return () => cancelAnimationFrame(raf);
+  }, [sliceCone]);
+  const conedNodes = (0, import_react25.useMemo)(() => {
+    if (!sliceCone || sliceCone.size === 0) return reactFlowNodes;
+    return reactFlowNodes.map((n) => {
+      const depth = sliceCone.get(n.id);
+      if (depth === void 0) {
+        return { ...n, style: { ...n.style, opacity: 0.22, transition: "opacity 260ms ease" } };
+      }
+      return {
+        ...n,
+        style: {
+          ...n.style,
+          opacity: coneRevealed ? 1 : 0.22,
+          transition: "opacity 320ms ease",
+          transitionDelay: `${depth * 90}ms`
+        }
+      };
+    });
+  }, [reactFlowNodes, sliceCone, coneRevealed]);
+  const conedEdges = (0, import_react25.useMemo)(() => {
+    if (!sliceCone || sliceCone.size === 0) return reactFlowEdges;
+    return reactFlowEdges.map((e) => {
+      const inCone = sliceCone.has(e.source) && sliceCone.has(e.target);
+      return inCone ? e : { ...e, style: { ...e.style, opacity: 0.12, transition: "opacity 260ms ease" } };
+    });
+  }, [reactFlowEdges, sliceCone]);
   const handleNodeClick = (0, import_react25.useCallback)(
     (_, node) => {
       const data = node.data ?? {};
@@ -5173,8 +5267,8 @@ function TracedFlow({
         /* @__PURE__ */ (0, import_jsx_runtime21.jsx)("div", { style: { flex: 1, minHeight: 0 }, children: /* @__PURE__ */ (0, import_jsx_runtime21.jsxs)(
           import_react26.ReactFlow,
           {
-            nodes: reactFlowNodes,
-            edges: reactFlowEdges,
+            nodes: conedNodes,
+            edges: conedEdges,
             nodeTypes: mergedNodeTypes,
             edgeTypes: mergedEdgeTypes,
             onNodeClick: handleNodeClick,
@@ -5205,8 +5299,10 @@ var DataTracePanel = (0, import_react27.memo)(function DataTracePanel2({
   frames,
   selectedStageId,
   onFrameClick,
-  fromStageName
+  fromStageName,
+  note
 }) {
+  const noteLine = note ? /* @__PURE__ */ (0, import_jsx_runtime22.jsx)("div", { style: { color: theme.textMuted, fontSize: 11, fontStyle: "italic", marginBottom: 8 }, children: note }) : null;
   if (frames.length === 0) {
     return /* @__PURE__ */ (0, import_jsx_runtime22.jsxs)("div", { style: { padding: "14px 14px 12px", fontSize: 13, lineHeight: 1.55 }, children: [
       /* @__PURE__ */ (0, import_jsx_runtime22.jsx)(
@@ -5224,10 +5320,12 @@ var DataTracePanel = (0, import_react27.memo)(function DataTracePanel2({
         }
       ),
       /* @__PURE__ */ (0, import_jsx_runtime22.jsx)("div", { style: { color: theme.textSecondary, marginBottom: 10 }, children: "Trace any value back to the stage that created it \u2014 and everything upstream that influenced it." }),
+      noteLine,
       /* @__PURE__ */ (0, import_jsx_runtime22.jsx)("div", { style: { color: theme.textMuted, fontSize: 12 }, children: "Select a stage above to see its dependency chain." })
     ] });
   }
   return /* @__PURE__ */ (0, import_jsx_runtime22.jsxs)("div", { style: { padding: "8px 0", fontSize: 13 }, children: [
+    note && /* @__PURE__ */ (0, import_jsx_runtime22.jsx)("div", { style: { padding: "4px 12px 0", fontSize: 11, color: theme.textMuted, fontStyle: "italic" }, children: note }),
     fromStageName && /* @__PURE__ */ (0, import_jsx_runtime22.jsxs)("div", { style: { padding: "4px 12px 8px" }, children: [
       /* @__PURE__ */ (0, import_jsx_runtime22.jsxs)(
         "div",
@@ -5361,10 +5459,16 @@ var InspectorPanel = (0, import_react28.memo)(function InspectorPanel2({
   snapshots,
   selectedIndex,
   dataTraceFrames,
+  dataTraceNote,
   selectedStageId,
-  onNavigateToStage
+  onNavigateToStage,
+  onTabChange
 }) {
-  const [tab, setTab] = (0, import_react28.useState)("state");
+  const [tab, setTabState] = (0, import_react28.useState)("state");
+  const setTab = (t) => {
+    setTabState(t);
+    onTabChange?.(t);
+  };
   const currentSnapshot = snapshots[selectedIndex];
   return /* @__PURE__ */ (0, import_jsx_runtime23.jsxs)(
     "div",
@@ -5417,6 +5521,7 @@ var InspectorPanel = (0, import_react28.memo)(function InspectorPanel2({
             DataTracePanel,
             {
               frames: dataTraceFrames,
+              note: dataTraceNote,
               selectedStageId,
               onFrameClick: onNavigateToStage,
               fromStageName: currentSnapshot?.stageName
@@ -6008,40 +6113,6 @@ function resolveSubflowFromRuntime(parentSnapshots, subflowId, narrativeEntries)
   if (sfSnapshots.length === 0) return null;
   return { subflowId, label, spec: null, snapshots: sfSnapshots, narrative: sfNarrative };
 }
-function buildDataTrace(commitLog, targetRuntimeStageId, maxDepth = 10) {
-  const log = commitLog;
-  if (!log?.length) return [];
-  const idxMap = /* @__PURE__ */ new Map();
-  for (let i = 0; i < log.length; i++) idxMap.set(log[i].runtimeStageId, i);
-  const startIdx = idxMap.get(targetRuntimeStageId);
-  if (startIdx === void 0) return [];
-  const startCommit = log[startIdx];
-  const frames = [];
-  const visited = /* @__PURE__ */ new Set();
-  let current = startCommit;
-  let currentIdx = startIdx;
-  let depth = 0;
-  while (current && depth <= maxDepth) {
-    if (visited.has(current.runtimeStageId)) break;
-    visited.add(current.runtimeStageId);
-    frames.push({
-      runtimeStageId: current.runtimeStageId,
-      stageId: current.stageId,
-      stageName: current.stage,
-      keysWritten: current.trace.map((t) => t.path),
-      linkedBy: depth === 0 ? "" : current.trace[0]?.path ?? "",
-      depth
-    });
-    if (currentIdx > 0) {
-      currentIdx--;
-      current = log[currentIdx];
-      depth++;
-    } else {
-      break;
-    }
-  }
-  return frames;
-}
 var RightPanel = (0, import_react31.memo)(function RightPanel2({
   mode,
   onModeChange,
@@ -6054,7 +6125,9 @@ var RightPanel = (0, import_react31.memo)(function RightPanel2({
   recorderViews,
   autoRecorderViews,
   size,
-  onNavigateToStage
+  onNavigateToStage,
+  dataTrace,
+  onInspectorTabChange
 }) {
   return /* @__PURE__ */ (0, import_jsx_runtime26.jsxs)(import_jsx_runtime26.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("div", { style: {
@@ -6107,7 +6180,9 @@ var RightPanel = (0, import_react31.memo)(function RightPanel2({
       {
         snapshots,
         selectedIndex,
-        dataTraceFrames: runtimeSnapshot?.commitLog ? buildDataTrace(runtimeSnapshot.commitLog, snapshots[selectedIndex]?.runtimeStageId ?? "") : [],
+        dataTraceFrames: dataTrace.frames,
+        dataTraceNote: dataTrace.readsAvailable ? void 0 : "\u26A0 reads were not recorded (readTracking off) \u2014 dependencies are unknowable, not absent.",
+        onTabChange: onInspectorTabChange,
         selectedStageId: snapshots[selectedIndex]?.runtimeStageId,
         onNavigateToStage
       }
@@ -6161,7 +6236,7 @@ function ExplainableShell({
   const resultData = resultDataProp ?? derivedFromRuntime?.resultData ?? null;
   const tracedFlowRenderer = (0, import_react31.useMemo)(() => {
     if (!traceGraph) return void 0;
-    return ({ selectedIndex, snapshots: snapshots2, onNodeClick }) => {
+    return ({ selectedIndex, snapshots: snapshots2, onNodeClick, sliceCone: sliceCone2 }) => {
       const activeRsid = snapshots2[selectedIndex]?.runtimeStageId;
       let overlayIdx = selectedIndex;
       if (activeRsid && runtimeOverlay) {
@@ -6185,6 +6260,7 @@ function ExplainableShell({
         {
           graph: traceGraph,
           overlay: runtimeOverlay ?? void 0,
+          sliceCone: sliceCone2 ?? void 0,
           colors: traceColors || void 0,
           scrubIndex: overlayIdx,
           onNodeClick: (stageId) => onNodeClick?.(stageId),
@@ -6245,6 +6321,7 @@ function ExplainableShell({
   const [drillDownStack, setDrillDownStack] = (0, import_react31.useState)([]);
   const [rightExpanded, setRightExpanded] = (0, import_react31.useState)(defaultExpanded?.details ?? true);
   const [rightPanelMode, setRightPanelMode] = (0, import_react31.useState)("insights");
+  const [inspectorTab, setInspectorTab] = (0, import_react31.useState)("state");
   const [leftExpanded, setLeftExpanded] = (0, import_react31.useState)(defaultExpanded?.topology ?? false);
   const [timelineExpanded, setTimelineExpanded] = (0, import_react31.useState)(defaultExpanded?.timeline ?? false);
   (0, import_react31.useEffect)(() => {
@@ -6280,6 +6357,21 @@ function ExplainableShell({
   }, [drillDownStack, snapshots]);
   const activeSnapshots = currentLevel.snapshots;
   const safeIdx = activeSnapshots.length > 0 ? Math.max(0, Math.min(snapshotIdx, activeSnapshots.length - 1)) : 0;
+  const shellDataTrace = (0, import_react31.useMemo)(
+    () => runtimeSnapshot?.commitLog ? buildDataTrace(runtimeSnapshot.commitLog, runtimeSnapshot.executionTree, activeSnapshots[safeIdx]?.runtimeStageId ?? "") : { frames: [], readsAvailable: true },
+    [runtimeSnapshot, activeSnapshots, safeIdx]
+  );
+  const sliceCone = (0, import_react31.useMemo)(() => {
+    if (rightPanelMode !== "what" || inspectorTab !== "trace") return void 0;
+    if (shellDataTrace.frames.length < 2) return void 0;
+    const cone = /* @__PURE__ */ new Map();
+    for (const f of shellDataTrace.frames) {
+      const stagePart = f.runtimeStageId.split("#")[0];
+      const prev = cone.get(stagePart);
+      if (prev === void 0 || f.depth < prev) cone.set(stagePart, f.depth);
+    }
+    return cone;
+  }, [rightPanelMode, inspectorTab, shellDataTrace]);
   const activeNarrativeEntries = isInSubflow ? currentLevel.narrative : narrativeEntries;
   const breadcrumbs = (0, import_react31.useMemo)(() => {
     const root = { label: title || "Flowchart", spec: null, description: void 0 };
@@ -6363,7 +6455,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 }),
-          traceGraph && effectiveRenderFlowchart?.({ spec: null, snapshots: activeSnapshots, selectedIndex: safeIdx, onNodeClick: handleNodeClick, showStageId }),
+          traceGraph && effectiveRenderFlowchart?.({ spec: null, snapshots: activeSnapshots, selectedIndex: safeIdx, onNodeClick: handleNodeClick, showStageId, ...sliceCone && { sliceCone } }),
           /* @__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 })
@@ -6436,12 +6528,22 @@ function ExplainableShell({
     }) }),
     /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("div", { style: { flex: 1, overflow: "auto" }, children: detailsContent })
   ] });
+  const shellThemeVars = (0, import_react31.useMemo)(() => {
+    if (!traceTheme) return {};
+    const base = traceTheme.mode ? tokensToCSSVars(traceTheme.mode === "light" ? coolLight : coolDark) : {};
+    return {
+      ...base,
+      ...traceTheme.visited !== void 0 && { ["--fp-node-visited"]: traceTheme.visited },
+      ...traceTheme.current !== void 0 && { ["--fp-node-cursor"]: traceTheme.current }
+    };
+  }, [traceTheme]);
   return /* @__PURE__ */ (0, import_jsx_runtime26.jsxs)(
     "div",
     {
       ref: shellRef,
       className,
       style: {
+        ...shellThemeVars,
         height: "100%",
         display: "flex",
         flexDirection: "column",
@@ -6472,7 +6574,8 @@ function ExplainableShell({
               snapshots: activeSnapshots,
               selectedIndex: safeIdx,
               onNodeClick: handleNodeClick,
-              showStageId
+              showStageId,
+              ...sliceCone && { sliceCone }
             }) }),
             showTreeSidebar && /* @__PURE__ */ (0, import_jsx_runtime26.jsxs)(import_jsx_runtime26.Fragment, { children: [
               /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(HLinePill, { label: leftLabel, expanded: leftExpanded, onClick: () => toggleLeft(!leftExpanded) }),
@@ -6512,7 +6615,8 @@ function ExplainableShell({
                 snapshots: activeSnapshots,
                 selectedIndex: safeIdx,
                 onNodeClick: handleNodeClick,
-                showStageId
+                showStageId,
+                ...sliceCone && { sliceCone }
               }) }) : /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("div", { style: { flex: 1 } }),
               /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(VLinePill, { label: "Details", expanded: rightExpanded, onClick: () => toggleRight(!rightExpanded) }),
               rightExpanded && /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("div", { style: { width: "42%", minWidth: 320, maxWidth: 550, display: "flex", flexDirection: "column", overflow: "hidden" }, children: /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(
@@ -6520,6 +6624,8 @@ function ExplainableShell({
                 {
                   mode: rightPanelMode,
                   onModeChange: setRightPanelMode,
+                  dataTrace: shellDataTrace,
+                  onInspectorTabChange: setInspectorTab,
                   snapshots: activeSnapshots,
                   selectedIndex: safeIdx,
                   runtimeSnapshot,