footprint-explainable-ui 0.3.2 → 0.5.0

package/dist/index.js

@@ -644,7 +644,7 @@ function NarrativeTrace({
 }
 
 // src/components/GanttTimeline/GanttTimeline.tsx
-import { useMemo as useMemo4 } from "react";
+import { useState as useState2, useMemo as useMemo4, useRef as useRef2, useEffect as useEffect2 } from "react";
 import { jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
 function GanttTimeline({
   snapshots,
@@ -653,8 +653,12 @@ function GanttTimeline({
   size = "default",
   unstyled = false,
   className,
-  style
+  style,
+  maxVisibleRows = 5
 }) {
+  const [expanded, setExpanded] = useState2(false);
+  const activeRowRef = useRef2(null);
+  const scrollContainerRef = useRef2(null);
   const totalWallTime = useMemo4(
     () => Math.max(...snapshots.map((s) => s.startMs + s.durationMs), 1),
     [snapshots]
@@ -663,6 +667,17 @@ function GanttTimeline({
   const pad = padding[size];
   const labelWidth = size === "compact" ? 50 : size === "detailed" ? 100 : 80;
   const msWidth = size === "compact" ? 28 : 36;
+  const rowHeight = size === "compact" ? 18 : 22;
+  const collapsible = maxVisibleRows > 0 && snapshots.length > maxVisibleRows;
+  const showAll = expanded || !collapsible;
+  useEffect2(() => {
+    if (!showAll && activeRowRef.current && scrollContainerRef.current) {
+      activeRowRef.current.scrollIntoView({
+        block: "nearest",
+        behavior: "smooth"
+      });
+    }
+  }, [selectedIndex, showAll]);
   if (unstyled) {
     return /* @__PURE__ */ jsx5("div", { className, style, "data-fp": "gantt-timeline", children: snapshots.map((snap, idx) => /* @__PURE__ */ jsxs4(
       "div",
@@ -689,27 +704,62 @@ function GanttTimeline({
       style: { padding: pad, fontFamily: theme.fontSans, ...style },
       "data-fp": "gantt-timeline",
       children: [
-        /* @__PURE__ */ jsx5(
-          "span",
+        /* @__PURE__ */ jsxs4(
+          "div",
           {
             style: {
-              fontSize: fs.label,
-              fontWeight: 600,
-              color: theme.textMuted,
-              textTransform: "uppercase",
-              letterSpacing: "0.08em"
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "space-between"
             },
-            children: size === "compact" ? "Timeline" : "Execution Timeline"
+            children: [
+              /* @__PURE__ */ jsx5(
+                "span",
+                {
+                  style: {
+                    fontSize: fs.label,
+                    fontWeight: 600,
+                    color: theme.textMuted,
+                    textTransform: "uppercase",
+                    letterSpacing: "0.08em"
+                  },
+                  children: size === "compact" ? "Timeline" : "Execution Timeline"
+                }
+              ),
+              collapsible && /* @__PURE__ */ jsx5(
+                "button",
+                {
+                  onClick: () => setExpanded((e) => !e),
+                  style: {
+                    background: "none",
+                    border: `1px solid ${theme.border}`,
+                    borderRadius: 4,
+                    color: theme.textSecondary,
+                    fontSize: fs.small,
+                    padding: "2px 8px",
+                    cursor: "pointer",
+                    fontFamily: theme.fontSans
+                  },
+                  children: expanded ? "Collapse" : `${snapshots.length - maxVisibleRows} more...`
+                }
+              )
+            ]
           }
         ),
         /* @__PURE__ */ jsx5(
           "div",
           {
+            ref: scrollContainerRef,
             style: {
               marginTop: 8,
               display: "flex",
               flexDirection: "column",
-              gap: 4
+              gap: 4,
+              ...showAll ? {} : {
+                maxHeight: maxVisibleRows * (rowHeight + 4),
+                overflowY: "auto",
+                scrollbarWidth: "thin"
+              }
             },
             children: snapshots.map((snap, idx) => {
               const leftPct = snap.startMs / totalWallTime * 100;
@@ -719,6 +769,7 @@ function GanttTimeline({
               return /* @__PURE__ */ jsxs4(
                 "div",
                 {
+                  ref: isSelected ? activeRowRef : void 0,
                   onClick: () => onSelect?.(idx),
                   style: {
                     display: "flex",
@@ -726,7 +777,9 @@ function GanttTimeline({
                     gap: size === "compact" ? 4 : 8,
                     cursor: onSelect ? "pointer" : "default",
                     opacity: isVisible ? 1 : 0.3,
-                    transition: "opacity 0.3s ease"
+                    transition: "opacity 0.3s ease",
+                    height: rowHeight,
+                    flexShrink: 0
                   },
                   children: [
                     /* @__PURE__ */ jsx5(
@@ -828,7 +881,7 @@ function GanttTimeline({
 }
 
 // src/components/SnapshotPanel/SnapshotPanel.tsx
-import { useState as useState2 } from "react";
+import { useState as useState3 } from "react";
 import { jsx as jsx6, jsxs as jsxs5 } from "react/jsx-runtime";
 function SnapshotPanel({
   snapshots,
@@ -840,7 +893,7 @@ function SnapshotPanel({
   className,
   style
 }) {
-  const [selectedIndex, setSelectedIndex] = useState2(0);
+  const [selectedIndex, setSelectedIndex] = useState3(0);
   const fs = fontSize[size];
   const pad = padding[size];
   if (snapshots.length === 0) {
@@ -1330,9 +1383,487 @@ function ResultPanel({
   );
 }
 
+// src/components/StageDetailPanel/StageDetailPanel.tsx
+import { useState as useState4, useMemo as useMemo6, useCallback as useCallback2 } from "react";
+import { Fragment as Fragment2, jsx as jsx9, jsxs as jsxs8 } from "react/jsx-runtime";
+function computeChanges(prev, curr) {
+  const changes = [];
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(prev ?? {}), ...Object.keys(curr)]);
+  for (const key of allKeys) {
+    const inPrev = prev != null && key in prev;
+    const inCurr = key in curr;
+    const oldVal = prev?.[key];
+    const newVal = curr[key];
+    if (!inPrev && inCurr) {
+      changes.push({ key, type: "added", newValue: newVal });
+    } else if (inPrev && !inCurr) {
+      changes.push({ key, type: "removed", oldValue: oldVal });
+    } else if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+      changes.push({ key, type: "updated", oldValue: oldVal, newValue: newVal });
+    }
+  }
+  const order = { added: 0, updated: 1, removed: 2 };
+  changes.sort((a, b) => order[a.type] - order[b.type]);
+  return changes;
+}
+function fmt2(v2) {
+  if (typeof v2 === "string") return `"${v2}"`;
+  if (typeof v2 === "object" && v2 !== null) return JSON.stringify(v2, null, 2);
+  return String(v2);
+}
+var changeBadge = {
+  added: { bg: "rgba(34,197,94,0.12)", fg: "#22c55e", label: "ADD" },
+  updated: { bg: "rgba(245,158,11,0.12)", fg: "#f59e0b", label: "UPD" },
+  removed: { bg: "rgba(239,68,68,0.12)", fg: "#ef4444", label: "DEL" }
+};
+function SimpleView({
+  snapshot,
+  fs,
+  pad
+}) {
+  return /* @__PURE__ */ jsxs8("div", { style: { display: "flex", flexDirection: "column", gap: 16 }, children: [
+    /* @__PURE__ */ jsxs8("div", { children: [
+      /* @__PURE__ */ jsx9(
+        "div",
+        {
+          style: {
+            fontSize: fs.label + 2,
+            fontWeight: 700,
+            color: theme.textPrimary
+          },
+          children: snapshot.stageLabel
+        }
+      ),
+      snapshot.description && /* @__PURE__ */ jsx9(
+        "div",
+        {
+          style: {
+            fontSize: fs.body,
+            color: theme.textSecondary,
+            marginTop: 4,
+            lineHeight: 1.5
+          },
+          children: snapshot.description
+        }
+      )
+    ] }),
+    snapshot.status && /* @__PURE__ */ jsxs8("div", { style: { display: "flex", alignItems: "center", gap: 6 }, children: [
+      /* @__PURE__ */ jsx9(
+        "div",
+        {
+          style: {
+            width: 8,
+            height: 8,
+            borderRadius: "50%",
+            background: snapshot.status === "done" ? theme.success : snapshot.status === "active" ? theme.primary : snapshot.status === "error" ? theme.error : theme.textMuted
+          }
+        }
+      ),
+      /* @__PURE__ */ jsx9(
+        "span",
+        {
+          style: {
+            fontSize: fs.small,
+            color: theme.textMuted,
+            textTransform: "uppercase",
+            letterSpacing: "0.05em"
+          },
+          children: snapshot.status
+        }
+      )
+    ] }),
+    snapshot.narrative && /* @__PURE__ */ jsxs8("div", { children: [
+      /* @__PURE__ */ jsx9(
+        "div",
+        {
+          style: {
+            fontSize: fs.label,
+            fontWeight: 600,
+            color: theme.textMuted,
+            textTransform: "uppercase",
+            letterSpacing: "0.08em",
+            marginBottom: 6
+          },
+          children: "What happened"
+        }
+      ),
+      /* @__PURE__ */ jsx9(
+        "div",
+        {
+          style: {
+            fontSize: fs.body,
+            lineHeight: 1.6,
+            color: theme.textPrimary,
+            background: theme.bgSecondary,
+            border: `1px solid ${theme.border}`,
+            borderRadius: theme.radius,
+            padding: pad
+          },
+          children: snapshot.narrative
+        }
+      )
+    ] }),
+    snapshot.durationMs > 0 && /* @__PURE__ */ jsxs8(
+      "div",
+      {
+        style: {
+          fontSize: fs.small,
+          color: theme.textMuted
+        },
+        children: [
+          "Completed in ",
+          snapshot.durationMs < 1 ? "<1" : snapshot.durationMs,
+          "ms"
+        ]
+      }
+    )
+  ] });
+}
+function buildMemoryRows(currMemory, changes) {
+  const changeMap = new Map(changes.map((c) => [c.key, c]));
+  const rows = [];
+  for (const change of changes) {
+    rows.push({ kind: "change", change });
+  }
+  const unchangedKeys = Object.keys(currMemory).filter((k) => !changeMap.has(k)).sort();
+  for (const key of unchangedKeys) {
+    rows.push({ kind: "unchanged", key, value: currMemory[key] });
+  }
+  return rows;
+}
+function DevView({
+  snapshot,
+  changes,
+  currMemory,
+  fs,
+  pad
+}) {
+  const rows = useMemo6(() => buildMemoryRows(currMemory, changes), [currMemory, changes]);
+  const totalKeys = Object.keys(currMemory).length;
+  return /* @__PURE__ */ jsxs8("div", { style: { display: "flex", flexDirection: "column", gap: 12 }, children: [
+    /* @__PURE__ */ jsxs8("div", { style: { display: "flex", alignItems: "center", gap: 8 }, children: [
+      /* @__PURE__ */ jsx9(
+        "span",
+        {
+          style: {
+            fontSize: fs.label + 2,
+            fontWeight: 700,
+            color: theme.textPrimary,
+            fontFamily: theme.fontMono
+          },
+          children: snapshot.stageLabel
+        }
+      ),
+      snapshot.durationMs > 0 && /* @__PURE__ */ jsxs8(
+        "span",
+        {
+          style: {
+            fontSize: fs.small,
+            color: theme.textMuted,
+            fontFamily: theme.fontMono
+          },
+          children: [
+            snapshot.durationMs,
+            "ms"
+          ]
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsxs8(
+      "div",
+      {
+        style: {
+          fontSize: fs.label,
+          fontWeight: 600,
+          color: theme.textMuted,
+          textTransform: "uppercase",
+          letterSpacing: "0.08em"
+        },
+        children: [
+          "Memory",
+          /* @__PURE__ */ jsxs8("span", { style: { fontWeight: 400, marginLeft: 6 }, children: [
+            "(",
+            totalKeys,
+            " key",
+            totalKeys !== 1 ? "s" : "",
+            changes.length > 0 && `, ${changes.length} changed`,
+            ")"
+          ] })
+        ]
+      }
+    ),
+    rows.length === 0 ? /* @__PURE__ */ jsx9(
+      "div",
+      {
+        style: {
+          fontSize: fs.body,
+          color: theme.textMuted,
+          fontStyle: "italic",
+          fontFamily: theme.fontMono,
+          padding: `${pad}px`,
+          background: theme.bgSecondary,
+          borderRadius: theme.radius
+        },
+        children: "Empty memory"
+      }
+    ) : /* @__PURE__ */ jsx9(
+      "div",
+      {
+        style: {
+          fontFamily: theme.fontMono,
+          fontSize: fs.body,
+          background: theme.bgSecondary,
+          border: `1px solid ${theme.border}`,
+          borderRadius: theme.radius,
+          overflow: "hidden"
+        },
+        children: rows.map((row) => {
+          if (row.kind === "change") {
+            const { change } = row;
+            const badge = changeBadge[change.type];
+            return /* @__PURE__ */ jsxs8(
+              "div",
+              {
+                style: {
+                  display: "flex",
+                  alignItems: "flex-start",
+                  gap: 8,
+                  padding: `6px ${pad}px`,
+                  borderBottom: `1px solid ${theme.border}`,
+                  background: badge.bg
+                },
+                "data-fp": "memory-change",
+                "data-type": change.type,
+                children: [
+                  /* @__PURE__ */ jsx9(
+                    "span",
+                    {
+                      style: {
+                        fontSize: fs.small,
+                        fontWeight: 700,
+                        color: badge.fg,
+                        width: 28,
+                        flexShrink: 0,
+                        textAlign: "center",
+                        lineHeight: 1.8
+                      },
+                      children: badge.label
+                    }
+                  ),
+                  /* @__PURE__ */ jsx9(
+                    "span",
+                    {
+                      style: {
+                        color: theme.primary,
+                        fontWeight: 600,
+                        flexShrink: 0,
+                        lineHeight: 1.8
+                      },
+                      children: change.key
+                    }
+                  ),
+                  /* @__PURE__ */ jsx9("div", { style: { flex: 1, minWidth: 0, lineHeight: 1.8 }, children: change.type === "updated" ? /* @__PURE__ */ jsxs8(Fragment2, { children: [
+                    /* @__PURE__ */ jsx9(
+                      "span",
+                      {
+                        style: {
+                          color: theme.error,
+                          textDecoration: "line-through",
+                          opacity: 0.7
+                        },
+                        children: fmt2(change.oldValue)
+                      }
+                    ),
+                    /* @__PURE__ */ jsx9("span", { style: { color: theme.textMuted, margin: "0 4px" }, children: "\u2192" }),
+                    /* @__PURE__ */ jsx9("span", { style: { color: theme.success }, children: fmt2(change.newValue) })
+                  ] }) : change.type === "added" ? /* @__PURE__ */ jsx9("span", { style: { color: theme.success }, children: fmt2(change.newValue) }) : /* @__PURE__ */ jsx9("span", { style: { color: theme.error, textDecoration: "line-through" }, children: fmt2(change.oldValue) }) })
+                ]
+              },
+              change.key
+            );
+          }
+          return /* @__PURE__ */ jsxs8(
+            "div",
+            {
+              style: {
+                display: "flex",
+                alignItems: "flex-start",
+                gap: 8,
+                padding: `6px ${pad}px`,
+                borderBottom: `1px solid ${theme.border}`,
+                opacity: 0.5
+              },
+              "data-fp": "memory-unchanged",
+              children: [
+                /* @__PURE__ */ jsx9(
+                  "span",
+                  {
+                    style: {
+                      width: 28,
+                      flexShrink: 0,
+                      lineHeight: 1.8
+                    }
+                  }
+                ),
+                /* @__PURE__ */ jsx9(
+                  "span",
+                  {
+                    style: {
+                      color: theme.textSecondary,
+                      fontWeight: 500,
+                      flexShrink: 0,
+                      lineHeight: 1.8
+                    },
+                    children: row.key
+                  }
+                ),
+                /* @__PURE__ */ jsx9("div", { style: { flex: 1, minWidth: 0, lineHeight: 1.8, color: theme.textMuted }, children: fmt2(row.value) })
+              ]
+            },
+            row.key
+          );
+        })
+      }
+    )
+  ] });
+}
+function UnstyledSimpleView({ snapshot }) {
+  return /* @__PURE__ */ jsxs8("div", { "data-fp": "stage-detail-simple", children: [
+    /* @__PURE__ */ jsx9("div", { "data-fp": "stage-label", children: snapshot.stageLabel }),
+    snapshot.description && /* @__PURE__ */ jsx9("div", { "data-fp": "stage-description", children: snapshot.description }),
+    snapshot.status && /* @__PURE__ */ jsx9("div", { "data-fp": "stage-status", children: snapshot.status }),
+    snapshot.narrative && /* @__PURE__ */ jsx9("div", { "data-fp": "stage-narrative", children: snapshot.narrative })
+  ] });
+}
+function UnstyledDevView({
+  snapshot,
+  changes,
+  currMemory
+}) {
+  const rows = useMemo6(() => buildMemoryRows(currMemory, changes), [currMemory, changes]);
+  return /* @__PURE__ */ jsxs8("div", { "data-fp": "stage-detail-dev", children: [
+    /* @__PURE__ */ jsx9("div", { "data-fp": "stage-label", children: snapshot.stageLabel }),
+    rows.map((row) => {
+      if (row.kind === "change") {
+        const c = row.change;
+        return /* @__PURE__ */ jsxs8("div", { "data-fp": "memory-change", "data-type": c.type, children: [
+          /* @__PURE__ */ jsx9("span", { "data-fp": "change-key", children: c.key }),
+          c.type === "updated" && /* @__PURE__ */ jsxs8(Fragment2, { children: [
+            /* @__PURE__ */ jsx9("span", { "data-fp": "change-old", children: fmt2(c.oldValue) }),
+            /* @__PURE__ */ jsx9("span", { "data-fp": "change-new", children: fmt2(c.newValue) })
+          ] }),
+          c.type === "added" && /* @__PURE__ */ jsx9("span", { "data-fp": "change-value", children: fmt2(c.newValue) }),
+          c.type === "removed" && /* @__PURE__ */ jsx9("span", { "data-fp": "change-value", children: fmt2(c.oldValue) })
+        ] }, c.key);
+      }
+      return /* @__PURE__ */ jsxs8("div", { "data-fp": "memory-unchanged", children: [
+        /* @__PURE__ */ jsx9("span", { "data-fp": "unchanged-key", children: row.key }),
+        /* @__PURE__ */ jsx9("span", { "data-fp": "unchanged-value", children: fmt2(row.value) })
+      ] }, row.key);
+    })
+  ] });
+}
+function ModeToggle({
+  activeMode,
+  onToggle,
+  fs,
+  unstyled
+}) {
+  if (unstyled) {
+    return /* @__PURE__ */ jsx9("button", { "data-fp": "mode-toggle", "data-mode": activeMode, onClick: onToggle, children: activeMode === "simple" ? "Dev" : "Simple" });
+  }
+  return /* @__PURE__ */ jsx9(
+    "div",
+    {
+      style: {
+        display: "inline-flex",
+        borderRadius: 6,
+        border: `1px solid ${theme.border}`,
+        overflow: "hidden",
+        flexShrink: 0
+      },
+      "data-fp": "mode-toggle",
+      children: ["simple", "dev"].map((m) => /* @__PURE__ */ jsx9(
+        "button",
+        {
+          onClick: m !== activeMode ? onToggle : void 0,
+          style: {
+            padding: "4px 10px",
+            fontSize: fs.small,
+            fontWeight: m === activeMode ? 700 : 400,
+            textTransform: "uppercase",
+            letterSpacing: "0.05em",
+            color: m === activeMode ? theme.textPrimary : theme.textMuted,
+            background: m === activeMode ? theme.bgTertiary : "transparent",
+            border: "none",
+            cursor: m === activeMode ? "default" : "pointer"
+          },
+          children: m === "simple" ? "Simple" : "Dev"
+        },
+        m
+      ))
+    }
+  );
+}
+function StageDetailPanel({
+  snapshots,
+  selectedIndex,
+  mode: controlledMode,
+  showToggle = false,
+  onModeChange,
+  size = "default",
+  unstyled = false,
+  className,
+  style
+}) {
+  const [internalMode, setInternalMode] = useState4(controlledMode ?? "simple");
+  const activeMode = controlledMode ?? internalMode;
+  const handleToggle = useCallback2(() => {
+    const next = activeMode === "simple" ? "dev" : "simple";
+    setInternalMode(next);
+    onModeChange?.(next);
+  }, [activeMode, onModeChange]);
+  const snapshot = snapshots[selectedIndex];
+  const prevMemory = selectedIndex > 0 ? snapshots[selectedIndex - 1]?.memory ?? null : null;
+  const currMemory = snapshot?.memory ?? {};
+  const changes = useMemo6(
+    () => computeChanges(prevMemory, currMemory),
+    [prevMemory, currMemory]
+  );
+  const fs = fontSize[size];
+  const pad = padding[size];
+  if (!snapshot) {
+    return /* @__PURE__ */ jsx9("div", { className, style, "data-fp": "stage-detail-panel", children: /* @__PURE__ */ jsx9("div", { style: unstyled ? {} : { color: theme.textMuted, fontSize: fs.body, fontStyle: "italic", padding: pad }, children: "No stage selected" }) });
+  }
+  if (unstyled) {
+    return /* @__PURE__ */ jsxs8("div", { className, style, "data-fp": "stage-detail-panel", "data-mode": activeMode, children: [
+      showToggle && /* @__PURE__ */ jsx9(ModeToggle, { activeMode, onToggle: handleToggle, fs, unstyled: true }),
+      activeMode === "simple" ? /* @__PURE__ */ jsx9(UnstyledSimpleView, { snapshot }) : /* @__PURE__ */ jsx9(UnstyledDevView, { snapshot, changes, currMemory })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs8(
+    "div",
+    {
+      className,
+      style: {
+        padding: pad,
+        fontFamily: theme.fontSans,
+        overflow: "auto",
+        ...style
+      },
+      "data-fp": "stage-detail-panel",
+      "data-mode": activeMode,
+      children: [
+        showToggle && /* @__PURE__ */ jsx9("div", { style: { display: "flex", justifyContent: "flex-end", marginBottom: 12 }, children: /* @__PURE__ */ jsx9(ModeToggle, { activeMode, onToggle: handleToggle, fs, unstyled: false }) }),
+        activeMode === "simple" ? /* @__PURE__ */ jsx9(SimpleView, { snapshot, fs, pad }) : /* @__PURE__ */ jsx9(DevView, { snapshot, changes, currMemory, fs, pad })
+      ]
+    }
+  );
+}
+
 // src/components/TimeTravelControls/TimeTravelControls.tsx
-import { useState as useState3, useEffect as useEffect2, useRef as useRef2, useCallback as useCallback2 } from "react";
-import { jsx as jsx9, jsxs as jsxs8 } from "react/jsx-runtime";
+import { useState as useState5, useEffect as useEffect3, useRef as useRef3, useCallback as useCallback3 } from "react";
+import { jsx as jsx10, jsxs as jsxs9 } from "react/jsx-runtime";
 function TimeTravelControls({
   snapshots,
   selectedIndex,
@@ -1343,12 +1874,12 @@ function TimeTravelControls({
   className,
   style
 }) {
-  const [playing, setPlaying] = useState3(false);
-  const playRef = useRef2(null);
+  const [playing, setPlaying] = useState5(false);
+  const playRef = useRef3(null);
   const total = snapshots.length;
   const canPrev = selectedIndex > 0;
   const canNext = selectedIndex < total - 1;
-  useEffect2(() => {
+  useEffect3(() => {
     if (!playing || !autoPlayable) return;
     if (selectedIndex >= total - 1) {
       setPlaying(false);
@@ -1366,7 +1897,7 @@ function TimeTravelControls({
       if (playRef.current) clearTimeout(playRef.current);
     };
   }, [playing, selectedIndex, snapshots, total, onIndexChange, autoPlayable]);
-  const togglePlay = useCallback2(() => {
+  const togglePlay = useCallback3(() => {
     if (playing) {
       setPlaying(false);
     } else {
@@ -1376,8 +1907,8 @@ function TimeTravelControls({
   }, [playing, selectedIndex, total, onIndexChange]);
   const fs = fontSize[size];
   if (unstyled) {
-    return /* @__PURE__ */ jsxs8("div", { className, style, "data-fp": "time-travel-controls", children: [
-      /* @__PURE__ */ jsx9(
+    return /* @__PURE__ */ jsxs9("div", { className, style, "data-fp": "time-travel-controls", children: [
+      /* @__PURE__ */ jsx10(
         "button",
         {
           "data-fp": "tt-prev",
@@ -1389,8 +1920,8 @@ function TimeTravelControls({
           children: "Prev"
         }
       ),
-      autoPlayable && /* @__PURE__ */ jsx9("button", { "data-fp": "tt-play", onClick: togglePlay, children: playing ? "Pause" : "Play" }),
-      /* @__PURE__ */ jsx9(
+      autoPlayable && /* @__PURE__ */ jsx10("button", { "data-fp": "tt-play", onClick: togglePlay, children: playing ? "Pause" : "Play" }),
+      /* @__PURE__ */ jsx10(
         "button",
         {
           "data-fp": "tt-next",
@@ -1402,7 +1933,7 @@ function TimeTravelControls({
           children: "Next"
         }
       ),
-      /* @__PURE__ */ jsx9("div", { "data-fp": "tt-ticks", children: snapshots.map((snap, i) => /* @__PURE__ */ jsx9(
+      /* @__PURE__ */ jsx10("div", { "data-fp": "tt-ticks", children: snapshots.map((snap, i) => /* @__PURE__ */ jsx10(
         "button",
         {
           "data-fp": "tt-tick",
@@ -1430,7 +1961,7 @@ function TimeTravelControls({
     opacity: disabled ? 0.5 : 1,
     flexShrink: 0
   });
-  return /* @__PURE__ */ jsxs8(
+  return /* @__PURE__ */ jsxs9(
     "div",
     {
       className,
@@ -1446,7 +1977,7 @@ function TimeTravelControls({
       },
       "data-fp": "time-travel-controls",
       children: [
-        /* @__PURE__ */ jsx9(
+        /* @__PURE__ */ jsx10(
           "button",
           {
             style: btnStyle(!canPrev || playing),
@@ -1458,7 +1989,7 @@ function TimeTravelControls({
             children: "\u25C0"
           }
         ),
-        autoPlayable && /* @__PURE__ */ jsx9(
+        autoPlayable && /* @__PURE__ */ jsx10(
           "button",
           {
             onClick: togglePlay,
@@ -1480,7 +2011,7 @@ function TimeTravelControls({
             children: playing ? "\u23F8" : "\u25B6"
           }
         ),
-        /* @__PURE__ */ jsx9(
+        /* @__PURE__ */ jsx10(
           "button",
           {
             style: btnStyle(!canNext || playing),
@@ -1492,7 +2023,7 @@ function TimeTravelControls({
             children: "\u25B6"
           }
         ),
-        /* @__PURE__ */ jsx9(
+        /* @__PURE__ */ jsx10(
           "div",
           {
             style: {
@@ -1505,7 +2036,7 @@ function TimeTravelControls({
             children: snapshots.map((snap, i) => {
               const isActive = i === selectedIndex;
               const isDone = i < selectedIndex;
-              return /* @__PURE__ */ jsx9(
+              return /* @__PURE__ */ jsx10(
                 "button",
                 {
                   onClick: () => {
@@ -1535,8 +2066,8 @@ function TimeTravelControls({
 }
 
 // src/components/ExplainableShell/ExplainableShell.tsx
-import { useState as useState4, useCallback as useCallback3, useMemo as useMemo6 } from "react";
-import { Fragment as Fragment2, jsx as jsx10, jsxs as jsxs9 } from "react/jsx-runtime";
+import { useState as useState6, useCallback as useCallback4, useMemo as useMemo7 } from "react";
+import { Fragment as Fragment3, jsx as jsx11, jsxs as jsxs10 } from "react/jsx-runtime";
 function ExplainableShell({
   snapshots,
   resultData,
@@ -1551,14 +2082,14 @@ function ExplainableShell({
   className,
   style
 }) {
-  const [activeTab, setActiveTab] = useState4(defaultTab ?? tabs[0]);
-  const [snapshotIdx, setSnapshotIdx] = useState4(0);
+  const [activeTab, setActiveTab] = useState6(defaultTab ?? tabs[0]);
+  const [snapshotIdx, setSnapshotIdx] = useState6(0);
   const fs = fontSize[size];
   const pad = padding[size];
-  const handleSnapshotChange = useCallback3((idx) => {
+  const handleSnapshotChange = useCallback4((idx) => {
     setSnapshotIdx(Math.max(0, Math.min(idx, snapshots.length - 1)));
   }, [snapshots.length]);
-  const revealedCount = useMemo6(() => {
+  const revealedCount = useMemo7(() => {
     if (snapshots.length === 0 || narrative.length === 0) return narrative.length;
     const boundaries = [];
     for (let i = 0; i < narrative.length; i++) {
@@ -1589,8 +2120,8 @@ function ExplainableShell({
     "ai-compatible": "AI-Compatible"
   };
   if (unstyled) {
-    return /* @__PURE__ */ jsxs9("div", { className, style, "data-fp": "explainable-shell", children: [
-      /* @__PURE__ */ jsx10("div", { "data-fp": "shell-tabs", children: tabs.map((tab) => /* @__PURE__ */ jsx10(
+    return /* @__PURE__ */ jsxs10("div", { className, style, "data-fp": "explainable-shell", children: [
+      /* @__PURE__ */ jsx11("div", { "data-fp": "shell-tabs", children: tabs.map((tab) => /* @__PURE__ */ jsx11(
         "button",
         {
           "data-fp": "shell-tab",
@@ -1600,8 +2131,8 @@ function ExplainableShell({
         },
         tab
       )) }),
-      /* @__PURE__ */ jsxs9("div", { "data-fp": "shell-content", "data-tab": activeTab, children: [
-        activeTab === "result" && /* @__PURE__ */ jsx10(
+      /* @__PURE__ */ jsxs10("div", { "data-fp": "shell-content", "data-tab": activeTab, children: [
+        activeTab === "result" && /* @__PURE__ */ jsx11(
           ResultPanel,
           {
             data: resultData ?? null,
@@ -1610,8 +2141,8 @@ function ExplainableShell({
             unstyled: true
           }
         ),
-        activeTab === "explainable" && /* @__PURE__ */ jsxs9(Fragment2, { children: [
-          /* @__PURE__ */ jsx10(
+        activeTab === "explainable" && /* @__PURE__ */ jsxs10(Fragment3, { children: [
+          /* @__PURE__ */ jsx11(
             TimeTravelControls,
             {
               snapshots,
@@ -1621,9 +2152,9 @@ function ExplainableShell({
             }
           ),
           renderFlowchart?.({ snapshots, selectedIndex: snapshotIdx, onNodeClick: handleSnapshotChange }),
-          /* @__PURE__ */ jsx10(MemoryInspector, { snapshots, selectedIndex: snapshotIdx, unstyled: true }),
-          /* @__PURE__ */ jsx10(ScopeDiff, { previous: prevMemory, current: currMemory, unstyled: true }),
-          /* @__PURE__ */ jsx10(
+          /* @__PURE__ */ jsx11(MemoryInspector, { snapshots, selectedIndex: snapshotIdx, unstyled: true }),
+          /* @__PURE__ */ jsx11(ScopeDiff, { previous: prevMemory, current: currMemory, unstyled: true }),
+          /* @__PURE__ */ jsx11(
             GanttTimeline,
             {
               snapshots,
@@ -1633,8 +2164,8 @@ function ExplainableShell({
             }
           )
         ] }),
-        activeTab === "ai-compatible" && /* @__PURE__ */ jsxs9(Fragment2, { children: [
-          /* @__PURE__ */ jsx10(
+        activeTab === "ai-compatible" && /* @__PURE__ */ jsxs10(Fragment3, { children: [
+          /* @__PURE__ */ jsx11(
             TimeTravelControls,
             {
               snapshots,
@@ -1644,7 +2175,7 @@ function ExplainableShell({
             }
           ),
           renderFlowchart?.({ snapshots, selectedIndex: snapshotIdx, onNodeClick: handleSnapshotChange }),
-          /* @__PURE__ */ jsx10(
+          /* @__PURE__ */ jsx11(
             NarrativeTrace,
             {
               narrative,
@@ -1656,7 +2187,7 @@ function ExplainableShell({
       ] })
     ] });
   }
-  return /* @__PURE__ */ jsxs9(
+  return /* @__PURE__ */ jsxs10(
     "div",
     {
       className,
@@ -1672,7 +2203,7 @@ function ExplainableShell({
       },
       "data-fp": "explainable-shell",
       children: [
-        /* @__PURE__ */ jsx10(
+        /* @__PURE__ */ jsx11(
           "div",
           {
             style: {
@@ -1684,7 +2215,7 @@ function ExplainableShell({
             },
             children: tabs.map((tab) => {
               const active = tab === activeTab;
-              return /* @__PURE__ */ jsx10(
+              return /* @__PURE__ */ jsx11(
                 "button",
                 {
                   onClick: () => setActiveTab(tab),
@@ -1708,8 +2239,8 @@ function ExplainableShell({
             })
           }
         ),
-        /* @__PURE__ */ jsxs9("div", { style: { flex: 1, overflow: "hidden", display: "flex", flexDirection: "column" }, children: [
-          activeTab === "result" && /* @__PURE__ */ jsx10(
+        /* @__PURE__ */ jsxs10("div", { style: { flex: 1, overflow: "hidden", display: "flex", flexDirection: "column" }, children: [
+          activeTab === "result" && /* @__PURE__ */ jsx11(
             ResultPanel,
             {
               data: resultData ?? null,
@@ -1718,8 +2249,8 @@ function ExplainableShell({
               size
             }
           ),
-          activeTab === "explainable" && /* @__PURE__ */ jsxs9(Fragment2, { children: [
-            /* @__PURE__ */ jsx10(
+          activeTab === "explainable" && /* @__PURE__ */ jsxs10(Fragment3, { children: [
+            /* @__PURE__ */ jsx11(
               TimeTravelControls,
               {
                 snapshots,
@@ -1728,9 +2259,9 @@ function ExplainableShell({
                 size
               }
             ),
-            /* @__PURE__ */ jsxs9("div", { style: { flex: 1, display: "flex", overflow: "hidden" }, children: [
-              renderFlowchart && /* @__PURE__ */ jsx10("div", { style: { flex: 1, overflow: "hidden", borderRight: `1px solid ${theme.border}` }, children: renderFlowchart({ snapshots, selectedIndex: snapshotIdx, onNodeClick: handleSnapshotChange }) }),
-              /* @__PURE__ */ jsxs9(
+            /* @__PURE__ */ jsxs10("div", { style: { flex: 1, display: "flex", overflow: "hidden" }, children: [
+              renderFlowchart && /* @__PURE__ */ jsx11("div", { style: { flex: 1, overflow: "hidden", borderRight: `1px solid ${theme.border}` }, children: renderFlowchart({ snapshots, selectedIndex: snapshotIdx, onNodeClick: handleSnapshotChange }) }),
+              /* @__PURE__ */ jsxs10(
                 "div",
                 {
                   style: {
@@ -1741,7 +2272,7 @@ function ExplainableShell({
                     flexDirection: "column"
                   },
                   children: [
-                    /* @__PURE__ */ jsx10(
+                    /* @__PURE__ */ jsx11(
                       MemoryInspector,
                       {
                         snapshots,
@@ -1749,7 +2280,7 @@ function ExplainableShell({
                         size
                       }
                     ),
-                    /* @__PURE__ */ jsx10("div", { style: { borderTop: `1px solid ${theme.border}` }, children: /* @__PURE__ */ jsx10(
+                    /* @__PURE__ */ jsx11("div", { style: { borderTop: `1px solid ${theme.border}` }, children: /* @__PURE__ */ jsx11(
                       ScopeDiff,
                       {
                         previous: prevMemory,
@@ -1762,7 +2293,7 @@ function ExplainableShell({
                 }
               )
             ] }),
-            /* @__PURE__ */ jsx10("div", { style: { borderTop: `1px solid ${theme.border}`, flexShrink: 0 }, children: /* @__PURE__ */ jsx10(
+            /* @__PURE__ */ jsx11("div", { style: { borderTop: `1px solid ${theme.border}`, flexShrink: 0 }, children: /* @__PURE__ */ jsx11(
               GanttTimeline,
               {
                 snapshots,
@@ -1772,8 +2303,8 @@ function ExplainableShell({
               }
             ) })
           ] }),
-          activeTab === "ai-compatible" && /* @__PURE__ */ jsxs9(Fragment2, { children: [
-            /* @__PURE__ */ jsx10(
+          activeTab === "ai-compatible" && /* @__PURE__ */ jsxs10(Fragment3, { children: [
+            /* @__PURE__ */ jsx11(
               TimeTravelControls,
               {
                 snapshots,
@@ -1782,9 +2313,9 @@ function ExplainableShell({
                 size
               }
             ),
-            /* @__PURE__ */ jsxs9("div", { style: { flex: 1, display: "flex", overflow: "hidden" }, children: [
-              renderFlowchart && /* @__PURE__ */ jsx10("div", { style: { flex: 1, overflow: "hidden", borderRight: `1px solid ${theme.border}` }, children: renderFlowchart({ snapshots, selectedIndex: snapshotIdx, onNodeClick: handleSnapshotChange }) }),
-              /* @__PURE__ */ jsx10(
+            /* @__PURE__ */ jsxs10("div", { style: { flex: 1, display: "flex", overflow: "hidden" }, children: [
+              renderFlowchart && /* @__PURE__ */ jsx11("div", { style: { flex: 1, overflow: "hidden", borderRight: `1px solid ${theme.border}` }, children: renderFlowchart({ snapshots, selectedIndex: snapshotIdx, onNodeClick: handleSnapshotChange }) }),
+              /* @__PURE__ */ jsx11(
                 NarrativeTrace,
                 {
                   narrative,
@@ -1804,40 +2335,276 @@ function ExplainableShell({
   );
 }
 
+// src/components/FlowchartView/SubflowTree.tsx
+import { memo, useState as useState7, useCallback as useCallback5, useMemo as useMemo8 } from "react";
+import { Fragment as Fragment4, jsx as jsx12, jsxs as jsxs11 } from "react/jsx-runtime";
+function specToTree(node) {
+  const entries = [];
+  const seen = /* @__PURE__ */ new Set();
+  function walk(n) {
+    const id = n.name || n.id || "";
+    if (seen.has(id)) return;
+    seen.add(id);
+    const entry = {
+      name: n.name,
+      description: n.description,
+      subflowId: n.subflowId,
+      isSubflow: !!n.isSubflowRoot
+    };
+    if (n.isSubflowRoot && n.subflowStructure) {
+      entry.children = specToTree(n.subflowStructure);
+    }
+    entries.push(entry);
+    if (n.children) {
+      for (const child of n.children) {
+        walk(child);
+      }
+    }
+    if (n.next) {
+      walk(n.next);
+    }
+  }
+  walk(node);
+  return entries;
+}
+var TreeNode = memo(function TreeNode2({
+  entry,
+  depth,
+  activeStage,
+  doneStages,
+  onNodeSelect
+}) {
+  const [expanded, setExpanded] = useState7(true);
+  const hasChildren = entry.children && entry.children.length > 0;
+  const isActive = activeStage === entry.name;
+  const isDone = doneStages?.has(entry.name);
+  const handleClick = useCallback5(() => {
+    if (hasChildren) {
+      setExpanded((prev) => !prev);
+    }
+    onNodeSelect?.(entry.name, !!entry.isSubflow);
+  }, [hasChildren, onNodeSelect, entry.name, entry.isSubflow]);
+  return /* @__PURE__ */ jsxs11(Fragment4, { children: [
+    /* @__PURE__ */ jsxs11(
+      "button",
+      {
+        onClick: handleClick,
+        "data-fp": "subflow-tree-node",
+        style: {
+          display: "flex",
+          alignItems: "center",
+          gap: 6,
+          width: "100%",
+          border: "none",
+          background: isActive ? `color-mix(in srgb, ${theme.primary} 15%, transparent)` : "transparent",
+          cursor: "pointer",
+          padding: `4px 8px 4px ${8 + depth * 16}px`,
+          fontFamily: theme.fontSans,
+          fontSize: 12,
+          textAlign: "left",
+          borderRadius: 4,
+          transition: "background 0.15s"
+        },
+        onMouseEnter: (e) => {
+          if (!isActive) {
+            e.currentTarget.style.background = `color-mix(in srgb, ${theme.textMuted} 10%, transparent)`;
+          }
+        },
+        onMouseLeave: (e) => {
+          if (!isActive) {
+            e.currentTarget.style.background = "transparent";
+          }
+        },
+        children: [
+          hasChildren ? /* @__PURE__ */ jsx12(
+            "span",
+            {
+              style: {
+                fontSize: 10,
+                color: theme.textMuted,
+                width: 12,
+                textAlign: "center",
+                flexShrink: 0,
+                transition: "transform 0.15s",
+                transform: expanded ? "rotate(90deg)" : "rotate(0deg)",
+                display: "inline-block"
+              },
+              children: "\u25B6"
+            }
+          ) : /* @__PURE__ */ jsx12("span", { style: { width: 12, flexShrink: 0 } }),
+          /* @__PURE__ */ jsx12(
+            "span",
+            {
+              style: {
+                width: 6,
+                height: 6,
+                borderRadius: "50%",
+                flexShrink: 0,
+                background: isActive ? theme.primary : isDone ? theme.success : theme.border
+              }
+            }
+          ),
+          /* @__PURE__ */ jsxs11("span", { style: { display: "flex", flexDirection: "column", minWidth: 0 }, children: [
+            /* @__PURE__ */ jsxs11(
+              "span",
+              {
+                style: {
+                  color: isActive ? theme.primary : isDone ? theme.textPrimary : theme.textSecondary,
+                  fontWeight: isActive ? 600 : entry.isSubflow ? 500 : 400,
+                  whiteSpace: "nowrap",
+                  overflow: "hidden",
+                  textOverflow: "ellipsis"
+                },
+                children: [
+                  entry.name,
+                  entry.isSubflow && /* @__PURE__ */ jsx12("span", { style: { opacity: 0.5, marginLeft: 4, fontSize: 10 }, children: "\u229E" })
+                ]
+              }
+            ),
+            entry.description && /* @__PURE__ */ jsx12(
+              "span",
+              {
+                style: {
+                  color: theme.textMuted,
+                  fontSize: 10,
+                  whiteSpace: "nowrap",
+                  overflow: "hidden",
+                  textOverflow: "ellipsis"
+                },
+                children: entry.description
+              }
+            )
+          ] })
+        ]
+      }
+    ),
+    hasChildren && expanded && /* @__PURE__ */ jsx12("div", { children: entry.children.map((child, i) => /* @__PURE__ */ jsx12(
+      TreeNode2,
+      {
+        entry: child,
+        depth: depth + 1,
+        activeStage,
+        doneStages,
+        onNodeSelect
+      },
+      `${child.name}-${i}`
+    )) })
+  ] });
+});
+var SectionLabel = memo(function SectionLabel2({ children }) {
+  return /* @__PURE__ */ jsx12(
+    "div",
+    {
+      style: {
+        padding: "4px 12px 8px",
+        fontSize: 10,
+        fontWeight: 600,
+        textTransform: "uppercase",
+        letterSpacing: "0.05em",
+        color: theme.textMuted
+      },
+      children
+    }
+  );
+});
+var SubflowTree = memo(function SubflowTree2({
+  spec,
+  activeStage,
+  doneStages,
+  onNodeSelect,
+  unstyled = false,
+  className,
+  style
+}) {
+  const tree = useMemo8(() => specToTree(spec), [spec]);
+  const mainStages = useMemo8(() => tree.filter((e) => !e.isSubflow), [tree]);
+  const subflowStages = useMemo8(() => tree.filter((e) => e.isSubflow), [tree]);
+  const renderEntries = (entries) => entries.map((entry, i) => /* @__PURE__ */ jsx12(
+    TreeNode,
+    {
+      entry,
+      depth: 0,
+      activeStage,
+      doneStages,
+      onNodeSelect
+    },
+    `${entry.name}-${i}`
+  ));
+  return /* @__PURE__ */ jsxs11(
+    "div",
+    {
+      className,
+      "data-fp": "subflow-tree",
+      style: {
+        ...unstyled ? {} : {
+          fontFamily: theme.fontSans,
+          fontSize: 12,
+          background: theme.bgPrimary,
+          borderRight: `1px solid ${theme.border}`,
+          overflowY: "auto",
+          overflowX: "hidden",
+          padding: "8px 0"
+        },
+        ...style
+      },
+      children: [
+        !unstyled && /* @__PURE__ */ jsx12(SectionLabel, { children: "Flowchart" }),
+        renderEntries(mainStages),
+        subflowStages.length > 0 && /* @__PURE__ */ jsxs11(Fragment4, { children: [
+          !unstyled && /* @__PURE__ */ jsx12("div", { style: { height: 1, background: theme.border, margin: "8px 12px" } }),
+          !unstyled && /* @__PURE__ */ jsx12(SectionLabel, { children: "Subflows" }),
+          renderEntries(subflowStages)
+        ] })
+      ]
+    }
+  );
+});
+
 // src/adapters/fromRuntimeSnapshot.ts
 function toVisualizationSnapshots(runtime) {
   const snapshots = [];
-  flattenTree(runtime.executionTree, snapshots, runtime.sharedState);
+  flattenTree(runtime.executionTree, snapshots, runtime.sharedState, 0, runtime.subflowResults, {});
   return snapshots;
 }
-function flattenTree(node, out, sharedState, accumulatedMs = 0) {
+function flattenTree(node, out, sharedState, accumulatedMs = 0, subflowResults, cumulativeMemory = {}) {
   const durationMs = typeof node.metrics?.durationMs === "number" ? node.metrics.durationMs : 1;
   const startMs = accumulatedMs;
   const narrative = buildNarrative(node);
-  const memory = {};
-  if (node.logs) {
-    Object.assign(memory, node.logs);
+  const memory = { ...cumulativeMemory };
+  if (node.stageWrites) {
+    for (const [key, value] of Object.entries(node.stageWrites)) {
+      if (value === void 0) {
+        delete memory[key];
+      } else {
+        memory[key] = value;
+      }
+    }
   }
+  const stageId = node.name || node.id;
+  const sfResult = subflowResults?.[node.subflowId ?? stageId];
   out.push({
-    stageName: node.id,
-    stageLabel: node.name || node.id,
+    stageName: stageId,
+    stageLabel: stageId,
     memory,
     narrative,
     startMs,
     durationMs,
-    status: "done"
+    status: "done",
+    ...node.description ? { description: node.description } : void 0,
+    ...node.subflowId ? { subflowId: node.subflowId } : void 0,
+    ...sfResult ? { subflowResult: sfResult } : void 0
   });
   let nextMs = startMs + durationMs;
   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);
       maxChildEnd = Math.max(maxChildEnd, childEnd);
     }
     nextMs = maxChildEnd;
   }
   if (node.next) {
-    nextMs = flattenTree(node.next, out, sharedState, nextMs);
+    nextMs = flattenTree(node.next, out, sharedState, nextMs, subflowResults, memory);
   }
   return nextMs;
 }
@@ -1846,8 +2613,8 @@ function buildNarrative(node) {
   if (node.name) {
     parts.push(`Stage "${node.name}" executed.`);
   }
-  if (node.logs && Object.keys(node.logs).length > 0) {
-    const keys = Object.keys(node.logs);
+  if (node.stageWrites && Object.keys(node.stageWrites).length > 0) {
+    const keys = Object.keys(node.stageWrites);
     parts.push(`Wrote ${keys.length} key(s): ${keys.join(", ")}.`);
   }
   if (node.errors && Object.keys(node.errors).length > 0) {
@@ -1871,7 +2638,9 @@ function createSnapshots(stages) {
       narrative: s.narrative ?? `${s.label ?? s.name} completed.`,
       startMs: accMs,
       durationMs: duration,
-      status: "done"
+      status: "done",
+      ...s.description ? { description: s.description } : void 0,
+      ...s.subflowId ? { subflowId: s.subflowId } : void 0
     };
     accMs += duration;
     return snap;
@@ -1887,6 +2656,8 @@ export {
   ResultPanel,
   ScopeDiff,
   SnapshotPanel,
+  StageDetailPanel,
+  SubflowTree,
   TimeTravelControls,
   coolDark,
   createSnapshots,