footprint-explainable-ui 0.16.0 → 0.18.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -39,6 +49,7 @@ __export(src_exports, {
   StoryNarrative: () => StoryNarrative,
   SubflowTree: () => SubflowTree,
   TimeTravelControls: () => TimeTravelControls,
+  TraceViewer: () => TraceViewer,
   buildEntryRangeIndex: () => buildEntryRangeIndex,
   computeRevealedEntryCount: () => computeRevealedEntryCount,
   coolDark: () => coolDark,
@@ -2350,13 +2361,20 @@ function extractStageTimings(recorders) {
   const timings = /* @__PURE__ */ new Map();
   if (!recorders) return timings;
   for (const rec of recorders) {
-    if (rec.name === "Metrics" && rec.data && typeof rec.data === "object") {
-      const data = rec.data;
-      if (data.stages) {
-        for (const [stageName, metrics] of Object.entries(data.stages)) {
-          if (typeof metrics.totalDuration === "number" && metrics.totalDuration > 0) {
-            timings.set(stageName, Math.round(metrics.totalDuration));
-          }
+    if (rec.name !== "Metrics" || !rec.data || typeof rec.data !== "object") continue;
+    const data = rec.data;
+    if (data.steps) {
+      for (const step of Object.values(data.steps)) {
+        const name = step?.stageName;
+        const d = step?.duration;
+        if (!name || typeof d !== "number" || d <= 0) continue;
+        timings.set(name, Math.round((timings.get(name) ?? 0) + d));
+      }
+    }
+    if (data.stages) {
+      for (const [stageName, metrics] of Object.entries(data.stages)) {
+        if (typeof metrics.totalDuration === "number" && metrics.totalDuration > 0) {
+          timings.set(stageName, Math.round(metrics.totalDuration));
         }
       }
     }
@@ -2728,11 +2746,37 @@ function StoryNarrative({
 
 // src/components/NarrativePanel/NarrativePanel.tsx
 var import_jsx_runtime13 = require("react/jsx-runtime");
+function safeJsonStringify(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const MAX_CHARS = 5e5;
+  try {
+    let text = JSON.stringify(
+      value,
+      (_key, v2) => {
+        if (typeof v2 === "object" && v2 !== null) {
+          if (seen.has(v2)) return "[Circular]";
+          seen.add(v2);
+        }
+        return v2;
+      },
+      2
+    );
+    if (text && text.length > MAX_CHARS) {
+      text = text.slice(0, MAX_CHARS) + `
+... [truncated at ${MAX_CHARS} chars]`;
+    }
+    return text ?? "undefined";
+  } catch (err) {
+    return `[stringify error: ${err instanceof Error ? err.message : String(err)}]`;
+  }
+}
 function NarrativePanel({
   snapshots,
   selectedIndex,
   narrativeEntries,
   narrative: narrativeProp,
+  runtimeSnapshot,
+  spec,
   size = "default",
   unstyled = false,
   className,
@@ -2841,8 +2885,53 @@ function NarrativePanel({
         sections.push("");
       }
     }
+    if (runtimeSnapshot) {
+      const snap = runtimeSnapshot;
+      if (snap.sharedState !== void 0) {
+        sections.push("\n\n## Final Shared State");
+        sections.push("```json");
+        sections.push(safeJsonStringify(snap.sharedState));
+        sections.push("```");
+      }
+      if (Array.isArray(snap.commitLog) && snap.commitLog.length > 0) {
+        sections.push("\n\n## Commit Log");
+        sections.push(
+          "Each entry = one stage execution's writes to shared state. `rsid` is the runtimeStageId (use it to correlate with narrative + executionTree).\n"
+        );
+        sections.push("```json");
+        sections.push(safeJsonStringify(snap.commitLog));
+        sections.push("```");
+      }
+      if (snap.recorders && typeof snap.recorders === "object") {
+        sections.push("\n\n## Recorder Snapshots");
+        sections.push(
+          "Per-recorder data captured DURING the run (metrics, tokens, instructions, emit events).\n"
+        );
+        sections.push("```json");
+        sections.push(safeJsonStringify(snap.recorders));
+        sections.push("```");
+      }
+      if (snap.subflowResults && typeof snap.subflowResults === "object") {
+        const keys = Object.keys(snap.subflowResults);
+        if (keys.length > 0) {
+          sections.push("\n\n## Subflow Results");
+          sections.push("```json");
+          sections.push(safeJsonStringify(snap.subflowResults));
+          sections.push("```");
+        }
+      }
+    }
+    if (spec) {
+      sections.push("\n\n## Flowchart Spec (topology)");
+      sections.push(
+        "Node + edge metadata for the chart that ran. Useful for 'where in the graph did step N happen?' questions.\n"
+      );
+      sections.push("```json");
+      sections.push(safeJsonStringify(spec));
+      sections.push("```");
+    }
     return sections.join("\n");
-  }, [narrativeEntries, narrative]);
+  }, [narrativeEntries, narrative, runtimeSnapshot, spec]);
   const handleCopy = (0, import_react12.useCallback)(async () => {
     const text = buildLLMNarrative();
     await navigator.clipboard.writeText(text);
@@ -4878,6 +4967,7 @@ var RightPanel = (0, import_react24.memo)(function RightPanel2({
   snapshots,
   selectedIndex,
   runtimeSnapshot,
+  spec,
   activeTab,
   allTabs,
   activeNarrativeEntries,
@@ -4924,7 +5014,7 @@ var RightPanel = (0, import_react24.memo)(function RightPanel2({
           id: tab.id,
           name: insightName(tab.name),
           render: () => {
-            if (tab.id === "narrative") return /* @__PURE__ */ (0, import_jsx_runtime22.jsx)(NarrativePanel, { snapshots, selectedIndex, narrativeEntries: activeNarrativeEntries, narrative: activeNarrative, size, style: { height: "100%" } });
+            if (tab.id === "narrative") return /* @__PURE__ */ (0, import_jsx_runtime22.jsx)(NarrativePanel, { snapshots, selectedIndex, narrativeEntries: activeNarrativeEntries, narrative: activeNarrative, runtimeSnapshot, spec, 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);
@@ -5339,6 +5429,7 @@ function ExplainableShell({
                   snapshots: activeSnapshots,
                   selectedIndex: safeIdx,
                   runtimeSnapshot,
+                  spec,
                   activeTab,
                   allTabs,
                   activeNarrativeEntries,
@@ -5367,6 +5458,108 @@ function ExplainableShell({
     }
   );
 }
+
+// src/components/TraceViewer/TraceViewer.tsx
+var React = __toESM(require("react"), 1);
+var import_react25 = require("react");
+var import_jsx_runtime23 = require("react/jsx-runtime");
+function parseTrace(input) {
+  if (input == null) {
+    return {
+      ok: false,
+      error: { kind: "invalid-json", message: "No trace provided." }
+    };
+  }
+  let candidate = input;
+  if (typeof input === "string") {
+    if (!input.trim()) {
+      return { ok: false, error: { kind: "invalid-json", message: "Empty input." } };
+    }
+    try {
+      candidate = JSON.parse(input);
+    } catch (err) {
+      return {
+        ok: false,
+        error: { kind: "invalid-json", message: err.message }
+      };
+    }
+  }
+  if (!candidate || typeof candidate !== "object") {
+    return {
+      ok: false,
+      error: { kind: "not-object", message: "Trace must be a JSON object." }
+    };
+  }
+  const t = candidate;
+  if (typeof t.schemaVersion !== "number") {
+    return {
+      ok: false,
+      error: {
+        kind: "missing-version",
+        message: "Trace is missing required field `schemaVersion`. Did you pass an exportTrace() output?"
+      }
+    };
+  }
+  if (t.schemaVersion !== 1) {
+    return {
+      ok: false,
+      error: {
+        kind: "unsupported-version",
+        message: `Unsupported schemaVersion ${t.schemaVersion}. This TraceViewer renders schemaVersion 1.`,
+        version: t.schemaVersion
+      }
+    };
+  }
+  return { ok: true, trace: t };
+}
+var DEFAULT_TABS = ["explainable"];
+function TraceViewer({
+  trace,
+  onError,
+  fallback,
+  tabs = DEFAULT_TABS,
+  defaultTab = "narrative",
+  hideTabs,
+  size,
+  panelLabels,
+  recorderViews,
+  renderFlowchart
+}) {
+  const parsed = (0, import_react25.useMemo)(() => parseTrace(trace), [trace]);
+  React.useEffect(() => {
+    if (!parsed.ok && onError) onError(parsed.error);
+  }, [parsed, onError]);
+  const snapshots = (0, import_react25.useMemo)(() => {
+    if (!parsed.ok || !parsed.trace.snapshot) return [];
+    try {
+      return toVisualizationSnapshots(
+        parsed.trace.snapshot,
+        parsed.trace.narrativeEntries ?? void 0
+      );
+    } catch {
+      return [];
+    }
+  }, [parsed]);
+  if (!parsed.ok || snapshots.length === 0) {
+    return fallback ?? null;
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime23.jsx)(
+    ExplainableShell,
+    {
+      snapshots,
+      spec: parsed.trace.spec,
+      narrative: parsed.trace.narrative,
+      narrativeEntries: parsed.trace.narrativeEntries,
+      tabs,
+      defaultTab,
+      hideTabs,
+      size,
+      panelLabels,
+      recorderViews,
+      renderFlowchart
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CompactTimeline,
@@ -5388,6 +5581,7 @@ function ExplainableShell({
   StoryNarrative,
   SubflowTree,
   TimeTravelControls,
+  TraceViewer,
   buildEntryRangeIndex,
   computeRevealedEntryCount,
   coolDark,