footprint-explainable-ui 0.25.0 → 0.25.2

package/dist/index.d.cts

@@ -1,6 +1,5 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Node, Edge } from '@xyflow/react';
 import * as react from 'react';
+import { Node, Edge } from '@xyflow/react';
 
 /** Snapshot of a single pipeline stage — the core data shape for all components. */
 interface StageSnapshot {
@@ -134,7 +133,7 @@ interface FootprintThemeProps {
  * accessibility tree in some older browser versions. Our wrapper has
  * no semantic role, so this is fine.
  */
-declare function FootprintTheme({ tokens, children }: FootprintThemeProps): react_jsx_runtime.JSX.Element;
+declare function FootprintTheme({ tokens, children }: FootprintThemeProps): react.JSX.Element;
 
 /** Cool dark theme (the library default) */
 declare const coolDark: ThemeTokens;
@@ -201,7 +200,7 @@ interface MemoryInspectorProps extends BaseComponentProps {
  * Displays pipeline memory state as formatted JSON.
  * Supports both static (data prop) and time-travel (snapshots + selectedIndex) modes.
  */
-declare function MemoryInspector({ data, snapshots, selectedIndex, showTypes, highlightNew, size, unstyled, className, style, }: MemoryInspectorProps): react_jsx_runtime.JSX.Element;
+declare function MemoryInspector({ data, snapshots, selectedIndex, showTypes, highlightNew, size, unstyled, className, style, }: MemoryInspectorProps): react.JSX.Element;
 
 interface NarrativeLogProps extends BaseComponentProps {
     /** Snapshots to display narratives from */
@@ -215,7 +214,7 @@ interface NarrativeLogProps extends BaseComponentProps {
  * Timeline-style execution log showing what happened at each stage.
  * Supports both full snapshots mode and single-narrative mode.
  */
-declare function NarrativeLog({ snapshots, selectedIndex, narrative, size, unstyled, className, style, }: NarrativeLogProps): react_jsx_runtime.JSX.Element;
+declare function NarrativeLog({ snapshots, selectedIndex, narrative, size, unstyled, className, style, }: NarrativeLogProps): react.JSX.Element;
 
 interface NarrativeTraceProps extends BaseComponentProps {
     /** All narrative lines (full trace) */
@@ -227,7 +226,7 @@ interface NarrativeTraceProps extends BaseComponentProps {
     /** Called when user clicks a stage header */
     onStageClick?: (headerIndex: number) => void;
 }
-declare function NarrativeTrace({ narrative, revealedCount, defaultCollapsed, onStageClick, size, unstyled, className, style, }: NarrativeTraceProps): react_jsx_runtime.JSX.Element;
+declare function NarrativeTrace({ narrative, revealedCount, defaultCollapsed, onStageClick, size, unstyled, className, style, }: NarrativeTraceProps): react.JSX.Element;
 
 interface GanttTimelineProps extends BaseComponentProps {
     /** Stage snapshots with timing info */
@@ -244,7 +243,7 @@ interface GanttTimelineProps extends BaseComponentProps {
  * Collapses to `maxVisibleRows` with expand/collapse toggle.
  * Auto-scrolls to keep the active stage visible when collapsed.
  */
-declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, maxVisibleRows, }: GanttTimelineProps): react_jsx_runtime.JSX.Element;
+declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, maxVisibleRows, }: GanttTimelineProps): react.JSX.Element;
 
 interface SnapshotPanelProps extends BaseComponentProps {
     /** Stage snapshots from pipeline execution */
@@ -260,7 +259,7 @@ interface SnapshotPanelProps extends BaseComponentProps {
  * All-in-one panel: time-travel scrubber + memory inspector + narrative log + gantt.
  * Drop this into any page to make a pipeline run inspectable.
  */
-declare function SnapshotPanel({ snapshots, showGantt, showScrubber, title, size, unstyled, className, style, }: SnapshotPanelProps): react_jsx_runtime.JSX.Element;
+declare function SnapshotPanel({ snapshots, showGantt, showScrubber, title, size, unstyled, className, style, }: SnapshotPanelProps): react.JSX.Element;
 
 interface DiffEntry {
     key: string;
@@ -276,7 +275,7 @@ interface ScopeDiffProps extends BaseComponentProps {
     /** Hide unchanged keys (default: false) */
     hideUnchanged?: boolean;
 }
-declare function ScopeDiff({ previous, current, hideUnchanged, size, unstyled, className, style, }: ScopeDiffProps): react_jsx_runtime.JSX.Element;
+declare function ScopeDiff({ previous, current, hideUnchanged, size, unstyled, className, style, }: ScopeDiffProps): react.JSX.Element;
 
 interface ResultPanelProps extends BaseComponentProps {
     /** Final pipeline output / shared state */
@@ -286,7 +285,7 @@ interface ResultPanelProps extends BaseComponentProps {
     /** Hide console section (default: false) */
     hideConsole?: boolean;
 }
-declare function ResultPanel({ data, logs, hideConsole, size, unstyled, className, style, }: ResultPanelProps): react_jsx_runtime.JSX.Element;
+declare function ResultPanel({ data, logs, hideConsole, size, unstyled, className, style, }: ResultPanelProps): react.JSX.Element;
 
 type StageDetailMode = "simple" | "dev";
 interface MemoryChange {
@@ -309,7 +308,7 @@ interface StageDetailPanelProps extends BaseComponentProps {
     /** Keys to exclude from memory display (default: engine internals). Pass empty set to show all. */
     excludeKeys?: Set<string>;
 }
-declare function StageDetailPanel({ snapshots, selectedIndex, mode: controlledMode, showToggle, onModeChange, size, unstyled, className, style, }: StageDetailPanelProps): react_jsx_runtime.JSX.Element;
+declare function StageDetailPanel({ snapshots, selectedIndex, mode: controlledMode, showToggle, onModeChange, size, unstyled, className, style, }: StageDetailPanelProps): react.JSX.Element;
 
 interface TimeTravelControlsProps extends BaseComponentProps {
     /** Stage snapshots */
@@ -321,7 +320,7 @@ interface TimeTravelControlsProps extends BaseComponentProps {
     /** Enable auto-play with Gantt-proportional timing */
     autoPlayable?: boolean;
 }
-declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react_jsx_runtime.JSX.Element;
+declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react.JSX.Element;
 
 /**
  * One entry in the execution timeline. `<TracedFlow>` keys time-travel
@@ -707,7 +706,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_runtime.JSX.Element;
+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;
 
 /**
  * TraceViewer — drop-in component that renders an `agentfootprint.exportTrace()`
@@ -803,7 +802,7 @@ interface MemoryPanelProps extends BaseComponentProps {
     snapshots: StageSnapshot[];
     selectedIndex: number;
 }
-declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, className, style, }: MemoryPanelProps): react_jsx_runtime.JSX.Element;
+declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, className, style, }: MemoryPanelProps): react.JSX.Element;
 
 interface NarrativePanelProps extends BaseComponentProps {
     snapshots: StageSnapshot[];
@@ -827,7 +826,7 @@ interface NarrativePanelProps extends BaseComponentProps {
      */
     spec?: any;
 }
-declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, runtimeSnapshot, spec, size, unstyled, className, style, }: NarrativePanelProps): react_jsx_runtime.JSX.Element;
+declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, runtimeSnapshot, spec, size, unstyled, className, style, }: NarrativePanelProps): react.JSX.Element;
 
 interface StoryNarrativeProps extends BaseComponentProps {
     /** Structured narrative entries from CombinedNarrativeRecorder */
@@ -835,7 +834,7 @@ interface StoryNarrativeProps extends BaseComponentProps {
     /** Number of entries to reveal (position-based sync from NarrativePanel) */
     revealedEntryCount: number;
 }
-declare function StoryNarrative({ entries, revealedEntryCount, size, unstyled, className, style: outerStyle, }: StoryNarrativeProps): react_jsx_runtime.JSX.Element;
+declare function StoryNarrative({ entries, revealedEntryCount, size, unstyled, className, style: outerStyle, }: StoryNarrativeProps): react.JSX.Element;
 
 interface SubflowTreeEntry {
     /** Node name / identifier */

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Node, Edge } from '@xyflow/react';
 import * as react from 'react';
+import { Node, Edge } from '@xyflow/react';
 
 /** Snapshot of a single pipeline stage — the core data shape for all components. */
 interface StageSnapshot {
@@ -134,7 +133,7 @@ interface FootprintThemeProps {
  * accessibility tree in some older browser versions. Our wrapper has
  * no semantic role, so this is fine.
  */
-declare function FootprintTheme({ tokens, children }: FootprintThemeProps): react_jsx_runtime.JSX.Element;
+declare function FootprintTheme({ tokens, children }: FootprintThemeProps): react.JSX.Element;
 
 /** Cool dark theme (the library default) */
 declare const coolDark: ThemeTokens;
@@ -201,7 +200,7 @@ interface MemoryInspectorProps extends BaseComponentProps {
  * Displays pipeline memory state as formatted JSON.
  * Supports both static (data prop) and time-travel (snapshots + selectedIndex) modes.
  */
-declare function MemoryInspector({ data, snapshots, selectedIndex, showTypes, highlightNew, size, unstyled, className, style, }: MemoryInspectorProps): react_jsx_runtime.JSX.Element;
+declare function MemoryInspector({ data, snapshots, selectedIndex, showTypes, highlightNew, size, unstyled, className, style, }: MemoryInspectorProps): react.JSX.Element;
 
 interface NarrativeLogProps extends BaseComponentProps {
     /** Snapshots to display narratives from */
@@ -215,7 +214,7 @@ interface NarrativeLogProps extends BaseComponentProps {
  * Timeline-style execution log showing what happened at each stage.
  * Supports both full snapshots mode and single-narrative mode.
  */
-declare function NarrativeLog({ snapshots, selectedIndex, narrative, size, unstyled, className, style, }: NarrativeLogProps): react_jsx_runtime.JSX.Element;
+declare function NarrativeLog({ snapshots, selectedIndex, narrative, size, unstyled, className, style, }: NarrativeLogProps): react.JSX.Element;
 
 interface NarrativeTraceProps extends BaseComponentProps {
     /** All narrative lines (full trace) */
@@ -227,7 +226,7 @@ interface NarrativeTraceProps extends BaseComponentProps {
     /** Called when user clicks a stage header */
     onStageClick?: (headerIndex: number) => void;
 }
-declare function NarrativeTrace({ narrative, revealedCount, defaultCollapsed, onStageClick, size, unstyled, className, style, }: NarrativeTraceProps): react_jsx_runtime.JSX.Element;
+declare function NarrativeTrace({ narrative, revealedCount, defaultCollapsed, onStageClick, size, unstyled, className, style, }: NarrativeTraceProps): react.JSX.Element;
 
 interface GanttTimelineProps extends BaseComponentProps {
     /** Stage snapshots with timing info */
@@ -244,7 +243,7 @@ interface GanttTimelineProps extends BaseComponentProps {
  * Collapses to `maxVisibleRows` with expand/collapse toggle.
  * Auto-scrolls to keep the active stage visible when collapsed.
  */
-declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, maxVisibleRows, }: GanttTimelineProps): react_jsx_runtime.JSX.Element;
+declare function GanttTimeline({ snapshots, selectedIndex, onSelect, size, unstyled, className, style, maxVisibleRows, }: GanttTimelineProps): react.JSX.Element;
 
 interface SnapshotPanelProps extends BaseComponentProps {
     /** Stage snapshots from pipeline execution */
@@ -260,7 +259,7 @@ interface SnapshotPanelProps extends BaseComponentProps {
  * All-in-one panel: time-travel scrubber + memory inspector + narrative log + gantt.
  * Drop this into any page to make a pipeline run inspectable.
  */
-declare function SnapshotPanel({ snapshots, showGantt, showScrubber, title, size, unstyled, className, style, }: SnapshotPanelProps): react_jsx_runtime.JSX.Element;
+declare function SnapshotPanel({ snapshots, showGantt, showScrubber, title, size, unstyled, className, style, }: SnapshotPanelProps): react.JSX.Element;
 
 interface DiffEntry {
     key: string;
@@ -276,7 +275,7 @@ interface ScopeDiffProps extends BaseComponentProps {
     /** Hide unchanged keys (default: false) */
     hideUnchanged?: boolean;
 }
-declare function ScopeDiff({ previous, current, hideUnchanged, size, unstyled, className, style, }: ScopeDiffProps): react_jsx_runtime.JSX.Element;
+declare function ScopeDiff({ previous, current, hideUnchanged, size, unstyled, className, style, }: ScopeDiffProps): react.JSX.Element;
 
 interface ResultPanelProps extends BaseComponentProps {
     /** Final pipeline output / shared state */
@@ -286,7 +285,7 @@ interface ResultPanelProps extends BaseComponentProps {
     /** Hide console section (default: false) */
     hideConsole?: boolean;
 }
-declare function ResultPanel({ data, logs, hideConsole, size, unstyled, className, style, }: ResultPanelProps): react_jsx_runtime.JSX.Element;
+declare function ResultPanel({ data, logs, hideConsole, size, unstyled, className, style, }: ResultPanelProps): react.JSX.Element;
 
 type StageDetailMode = "simple" | "dev";
 interface MemoryChange {
@@ -309,7 +308,7 @@ interface StageDetailPanelProps extends BaseComponentProps {
     /** Keys to exclude from memory display (default: engine internals). Pass empty set to show all. */
     excludeKeys?: Set<string>;
 }
-declare function StageDetailPanel({ snapshots, selectedIndex, mode: controlledMode, showToggle, onModeChange, size, unstyled, className, style, }: StageDetailPanelProps): react_jsx_runtime.JSX.Element;
+declare function StageDetailPanel({ snapshots, selectedIndex, mode: controlledMode, showToggle, onModeChange, size, unstyled, className, style, }: StageDetailPanelProps): react.JSX.Element;
 
 interface TimeTravelControlsProps extends BaseComponentProps {
     /** Stage snapshots */
@@ -321,7 +320,7 @@ interface TimeTravelControlsProps extends BaseComponentProps {
     /** Enable auto-play with Gantt-proportional timing */
     autoPlayable?: boolean;
 }
-declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react_jsx_runtime.JSX.Element;
+declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react.JSX.Element;
 
 /**
  * One entry in the execution timeline. `<TracedFlow>` keys time-travel
@@ -707,7 +706,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_runtime.JSX.Element;
+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;
 
 /**
  * TraceViewer — drop-in component that renders an `agentfootprint.exportTrace()`
@@ -803,7 +802,7 @@ interface MemoryPanelProps extends BaseComponentProps {
     snapshots: StageSnapshot[];
     selectedIndex: number;
 }
-declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, className, style, }: MemoryPanelProps): react_jsx_runtime.JSX.Element;
+declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, className, style, }: MemoryPanelProps): react.JSX.Element;
 
 interface NarrativePanelProps extends BaseComponentProps {
     snapshots: StageSnapshot[];
@@ -827,7 +826,7 @@ interface NarrativePanelProps extends BaseComponentProps {
      */
     spec?: any;
 }
-declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, runtimeSnapshot, spec, size, unstyled, className, style, }: NarrativePanelProps): react_jsx_runtime.JSX.Element;
+declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, runtimeSnapshot, spec, size, unstyled, className, style, }: NarrativePanelProps): react.JSX.Element;
 
 interface StoryNarrativeProps extends BaseComponentProps {
     /** Structured narrative entries from CombinedNarrativeRecorder */
@@ -835,7 +834,7 @@ interface StoryNarrativeProps extends BaseComponentProps {
     /** Number of entries to reveal (position-based sync from NarrativePanel) */
     revealedEntryCount: number;
 }
-declare function StoryNarrative({ entries, revealedEntryCount, size, unstyled, className, style: outerStyle, }: StoryNarrativeProps): react_jsx_runtime.JSX.Element;
+declare function StoryNarrative({ entries, revealedEntryCount, size, unstyled, className, style: outerStyle, }: StoryNarrativeProps): react.JSX.Element;
 
 interface SubflowTreeEntry {
     /** Node name / identifier */

package/dist/index.js

@@ -2208,7 +2208,7 @@ function TimeTravelControls({
 }
 
 // src/components/ExplainableShell/ExplainableShell.tsx
-import { memo as memo8, useState as useState14, useCallback as useCallback8, useMemo as useMemo12, useRef as useRef9, useEffect as useEffect9 } from "react";
+import { memo as memo8, useState as useState14, useCallback as useCallback8, useMemo as useMemo12, useRef as useRef9, useEffect as useEffect11 } from "react";
 
 // src/utils/narrativeSync.ts
 function buildEntryRangeIndex(entries) {
@@ -3331,7 +3331,7 @@ var SubflowBreadcrumb = memo2(function SubflowBreadcrumb2({
 });
 
 // src/components/FlowchartView/TracedFlow.tsx
-import { useCallback as useCallback7, useMemo as useMemo10, useRef as useRef8, useState as useState10 } from "react";
+import { useCallback as useCallback7, useEffect as useEffect10, useMemo as useMemo10, useRef as useRef8, useState as useState10 } from "react";
 import {
   ReactFlow,
   Background,
@@ -3449,6 +3449,163 @@ function dagreTraceLayout(graph, options = {}) {
   });
   return { nodes: positioned, edges: graph.edges };
 }
+function createDagreTraceLayout(options = {}) {
+  return (graph) => dagreTraceLayout(graph, options);
+}
+
+// src/components/FlowchartView/_internal/devWarn.ts
+function isDevModeEnv() {
+  const proc = globalThis.process;
+  return proc?.env?.NODE_ENV !== "production";
+}
+function devWarn(messageFn, ...extras) {
+  if (!isDevModeEnv()) return;
+  console.warn(messageFn(), ...extras);
+}
+
+// src/components/FlowchartView/_internal/snapLinearSuccessors.ts
+function snapLinearSuccessors(graph, options = {}) {
+  if (graph.nodes.length === 0) return graph;
+  const fallbackW = options.nodeWidth ?? DEFAULT_NODE_W;
+  const fallbackH = options.nodeHeight ?? DEFAULT_NODE_H;
+  const byId = /* @__PURE__ */ new Map();
+  const width = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) {
+    byId.set(n.id, n);
+    width.set(n.id, sizeOf(n, fallbackW, fallbackH, options.nodeSize).width);
+  }
+  const preds = /* @__PURE__ */ new Map();
+  const outDegree = /* @__PURE__ */ new Map();
+  const seenEdge = /* @__PURE__ */ new Set();
+  for (const e of graph.edges) {
+    if (e.data?.kind === "loop") continue;
+    if (!byId.has(e.source) || !byId.has(e.target)) continue;
+    const key = `${e.source}\0${e.target}`;
+    if (seenEdge.has(key)) continue;
+    seenEdge.add(key);
+    const list = preds.get(e.target);
+    if (list) list.push(e.source);
+    else preds.set(e.target, [e.source]);
+    outDegree.set(e.source, (outDegree.get(e.source) ?? 0) + 1);
+  }
+  const workingX = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) workingX.set(n.id, n.position.x);
+  const centerX = (id) => workingX.get(id) + width.get(id) / 2;
+  const order = [...graph.nodes].sort(
+    (a, b) => a.position.y - b.position.y || a.position.x - b.position.x || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+  );
+  for (const n of order) {
+    const p = preds.get(n.id);
+    if (!p || p.length !== 1) continue;
+    const pid = p[0];
+    if ((outDegree.get(pid) ?? 0) !== 1) continue;
+    const P = byId.get(pid);
+    if ((n.parentId ?? void 0) !== (P.parentId ?? void 0)) continue;
+    workingX.set(n.id, centerX(pid) - width.get(n.id) / 2);
+  }
+  const nodes = graph.nodes.map((n) => {
+    const nx = workingX.get(n.id);
+    return nx === n.position.x ? n : { ...n, position: { x: nx, y: n.position.y } };
+  });
+  return { nodes, edges: graph.edges };
+}
+function createSnappedDagreLayout(base, options = {}) {
+  return (graph) => snapLinearSuccessors(base(graph), options);
+}
+
+// src/components/FlowchartView/_internal/centerForkParents.ts
+function centerForkParents(graph, options = {}) {
+  if (graph.nodes.length === 0) return graph;
+  const fallbackW = options.nodeWidth ?? DEFAULT_NODE_W;
+  const fallbackH = options.nodeHeight ?? DEFAULT_NODE_H;
+  const byId = /* @__PURE__ */ new Map();
+  const width = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) {
+    byId.set(n.id, n);
+    width.set(n.id, sizeOf(n, fallbackW, fallbackH, options.nodeSize).width);
+  }
+  const childrenOf = /* @__PURE__ */ new Map();
+  const predsOf = /* @__PURE__ */ new Map();
+  const outDegree = /* @__PURE__ */ new Map();
+  const inDegree = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  for (const e of graph.edges) {
+    if (e.data?.kind === "loop") continue;
+    if (!byId.has(e.source) || !byId.has(e.target)) continue;
+    const key = `${e.source} ${e.target}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const cl = childrenOf.get(e.source);
+    if (cl) cl.push(e.target);
+    else childrenOf.set(e.source, [e.target]);
+    const pl = predsOf.get(e.target);
+    if (pl) pl.push(e.source);
+    else predsOf.set(e.target, [e.source]);
+    outDegree.set(e.source, (outDegree.get(e.source) ?? 0) + 1);
+    inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
+  }
+  const workingX = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) workingX.set(n.id, n.position.x);
+  const centerX = (id) => workingX.get(id) + width.get(id) / 2;
+  const nodeSep = options.nodeSep ?? 60;
+  const clampX = (id, desiredX) => {
+    const w = width.get(id);
+    const x0 = workingX.get(id);
+    const self = byId.get(id);
+    let minX = -Infinity;
+    let maxX = Infinity;
+    for (const m of graph.nodes) {
+      if (m.id === id || m.parentId !== self.parentId) continue;
+      if (Math.abs(m.position.y - self.position.y) > 1) continue;
+      const mLeft = workingX.get(m.id);
+      const mRight = mLeft + width.get(m.id);
+      if (mRight <= x0) minX = Math.max(minX, mRight + nodeSep);
+      else if (mLeft >= x0 + w) maxX = Math.min(maxX, mLeft - nodeSep - w);
+    }
+    return minX <= maxX ? Math.max(minX, Math.min(maxX, desiredX)) : x0;
+  };
+  const order = [...graph.nodes].sort(
+    (a, b) => b.position.y - a.position.y || a.position.x - b.position.x || a.id.localeCompare(b.id)
+  );
+  for (const n of order) {
+    const outD = outDegree.get(n.id) ?? 0;
+    const inD = inDegree.get(n.id) ?? 0;
+    const isFork = outD >= 2 && inD <= 1;
+    const isMerge = inD >= 2 && outD <= 1;
+    if (!isFork && !isMerge) continue;
+    const kin = ((isFork ? childrenOf.get(n.id) : predsOf.get(n.id)) ?? []).filter(
+      (k) => byId.get(k)?.parentId === n.parentId
+      // same compound only
+    );
+    if (kin.length < 2) continue;
+    const centers = kin.map(centerX);
+    const wN = width.get(n.id);
+    const span = (Math.min(...centers) + Math.max(...centers)) / 2;
+    workingX.set(n.id, clampX(n.id, span - wN / 2));
+    const stepOf = isFork ? predsOf : childrenOf;
+    let curId = n.id;
+    const walked = /* @__PURE__ */ new Set([curId]);
+    for (; ; ) {
+      const nexts = stepOf.get(curId);
+      if (!nexts || nexts.length !== 1) break;
+      const m = nexts[0];
+      if (walked.has(m)) break;
+      if ((outDegree.get(m) ?? 0) > 1) break;
+      if ((inDegree.get(m) ?? 0) > 1) break;
+      if (byId.get(m)?.parentId !== byId.get(curId)?.parentId) break;
+      workingX.set(m, clampX(m, centerX(curId) - width.get(m) / 2));
+      walked.add(m);
+      curId = m;
+    }
+  }
+  const nodes = graph.nodes.map(
+    (n) => workingX.get(n.id) === n.position.x ? n : { ...n, position: { x: workingX.get(n.id), y: n.position.y } }
+  );
+  return { nodes, edges: graph.edges };
+}
+function withForkCentering(base, options = {}) {
+  return (graph) => centerForkParents(base(graph), options);
+}
 
 // src/components/FlowchartView/createTraceRuntimeOverlay.ts
 function sliceOverlay(overlay, index) {
@@ -3888,7 +4045,7 @@ var StageNode = memo3(function StageNode2({
                   background: bg,
                   border: `${isHero ? "2.5px" : isMuted ? "1px" : "2px"} ${isLazyUnresolved ? "dashed" : "solid"} ${borderColor}`,
                   borderRadius: theme.radius,
-                  padding: description ? `${Math.round(8 * sizeScale)}px ${Math.round(16 * sizeScale)}px` : `${Math.round(10 * sizeScale)}px ${Math.round(20 * sizeScale)}px`,
+                  padding: description ? `${Math.round(6 * sizeScale)}px ${Math.round(12 * sizeScale)}px` : `${Math.round(7 * sizeScale)}px ${Math.round(14 * sizeScale)}px`,
                   display: "flex",
                   flexDirection: "column",
                   alignItems: "center",
@@ -4509,6 +4666,14 @@ function staggeredBendY(sourceBottom, targetTop, others, minGapFromTarget = 8) {
   if (lowestSkippedBottom === -Infinity) return null;
   return Math.min((lowestSkippedBottom + targetTop) / 2, targetTop - minGapFromTarget);
 }
+function forkFanBendY(sourceBottom, childTops, minGapFromTarget = 8) {
+  if (childTops.length < 2) return null;
+  const nearestTop = Math.min(...childTops);
+  return Math.min((sourceBottom + nearestTop) / 2, nearestTop - minGapFromTarget);
+}
+function resolveStepBendY(forkBend, staggeredBend) {
+  return staggeredBend ?? forkBend;
+}
 
 // src/components/SmartStepEdge/SmartStepEdge.tsx
 import { jsx as jsx20 } from "react/jsx-runtime";
@@ -4531,6 +4696,16 @@ function SmartStepEdge({
     if (!src || !tgt) return null;
     const sourceBottom = src.internals.positionAbsolute.y + (src.measured.height ?? 0);
     const targetTop = tgt.internals.positionAbsolute.y;
+    const childTops = [];
+    for (const e of s.edges) {
+      if (e.source !== source) continue;
+      if (e.data?.kind === "loop") continue;
+      const c = s.nodeLookup.get(e.target);
+      if (c && c.type !== GROUP_CONTAINER_NODE_TYPE) {
+        childTops.push(c.internals.positionAbsolute.y);
+      }
+    }
+    const fan = forkFanBendY(sourceBottom, childTops);
     const others = [];
     for (const n of s.nodeLookup.values()) {
       if (n.id === source || n.id === target) continue;
@@ -4538,7 +4713,8 @@ function SmartStepEdge({
       const top = n.internals.positionAbsolute.y;
       others.push({ top, bottom: top + (n.measured.height ?? 0) });
     }
-    return staggeredBendY(sourceBottom, targetTop, others);
+    const staggered = staggeredBendY(sourceBottom, targetTop, others);
+    return resolveStepBendY(fan, staggered);
   });
   const [path] = getSmoothStepPath({
     sourceX,
@@ -4554,6 +4730,49 @@ function SmartStepEdge({
   return /* @__PURE__ */ jsx20(BaseEdge2, { id, path, markerEnd, style });
 }
 
+// src/components/FlowchartView/_internal/MeasuredNodeSizes.tsx
+import { useEffect as useEffect9 } from "react";
+import { useNodesInitialized, useStore as useStore3 } from "@xyflow/react";
+
+// src/components/FlowchartView/_internal/measuredFootprints.ts
+function extractMeasuredFootprints(entries) {
+  const sizes = /* @__PURE__ */ new Map();
+  for (const [id, node] of entries) {
+    const width = node.measured?.width;
+    const height = node.measured?.height;
+    if (typeof width === "number" && typeof height === "number" && width > 0 && height > 0) {
+      sizes.set(id, { width: Math.round(width), height: Math.round(height) });
+    }
+  }
+  return sizes;
+}
+function sameFootprints(a, b) {
+  if (a === b) return true;
+  if (a.size !== b.size) return false;
+  for (const [id, s] of a) {
+    const t = b.get(id);
+    if (!t || t.width !== s.width || t.height !== s.height) return false;
+  }
+  return true;
+}
+
+// src/components/FlowchartView/_internal/MeasuredNodeSizes.tsx
+function MeasuredNodeSizes({
+  onSizes,
+  includeHiddenNodes = false
+}) {
+  const initialized = useNodesInitialized({ includeHiddenNodes });
+  const sizes = useStore3(
+    (s) => extractMeasuredFootprints(s.nodeLookup),
+    sameFootprints
+  );
+  useEffect9(() => {
+    if (!initialized || sizes.size === 0) return;
+    onSizes(sizes);
+  }, [initialized, sizes, onSizes]);
+  return null;
+}
+
 // src/components/FlowchartView/TracedFlow.tsx
 import { jsx as jsx21, jsxs as jsxs18 } from "react/jsx-runtime";
 var DEFAULT_COLORS = {
@@ -4693,6 +4912,13 @@ function TracedFlow({
   style
 }) {
   const layout = layoutProp ?? dagreTraceLayout;
+  useEffect10(() => {
+    if (layoutProp === dagreTraceLayout) {
+      devWarn(
+        () => "[footprint-explainable-ui] <TracedFlow layout={dagreTraceLayout}> bypasses the built-in measure-then-layout pipeline (content-exact sizing, fork/merge centering, straight spines). OMIT the `layout` prop to use it \u2014 passing the raw dagreTraceLayout silently forfeits every layout improvement eui ships."
+      );
+    }
+  }, [layoutProp]);
   const colors = useMemo10(
     () => ({ ...DEFAULT_COLORS, ...colorOverrides ?? {} }),
     [colorOverrides]
@@ -4726,8 +4952,19 @@ function TracedFlow({
     () => buildSubflowBreadcrumb(graph, drill.currentSubflowId),
     [graph, drill.currentSubflowId]
   );
+  const [measuredSizes, setMeasuredSizes] = useState10(null);
   const positioned = useMemo10(() => {
-    const realBase = layout === "passthrough" ? (g) => g : layout;
+    const nodeSize = measuredSizes ? (n) => measuredSizes.get(n.id) : void 0;
+    const sizeOpts = nodeSize ? { nodeSize } : {};
+    const dagreBase = withForkCentering(
+      createSnappedDagreLayout(
+        createDagreTraceLayout({ ...sizeOpts, rankSep: 52, nodeSep: 36 }),
+        sizeOpts
+      ),
+      { ...sizeOpts, nodeSep: 36 }
+      // same nodeSep → clamp preserves dagre's reserved gap
+    );
+    const realBase = layout === "passthrough" ? (g) => g : layoutProp === void 0 ? dagreBase : layout;
     if (groupedSet.size > 0) {
       const grouped = applyGroupLayout(filteredGraph, {
         groupedSubflowIds: [...groupedSet],
@@ -4738,8 +4975,8 @@ function TracedFlow({
     if (mainChartBox) {
       return wrapInMainChartBox(filteredGraph, { baseLayout: realBase, ...mainChartBox });
     }
-    return layout === "passthrough" ? filteredGraph : layout(filteredGraph);
-  }, [filteredGraph, layout, groupedSet, mainChartBox]);
+    return realBase(filteredGraph);
+  }, [filteredGraph, layout, layoutProp, groupedSet, mainChartBox, measuredSizes]);
   const slice = useMemo10(() => {
     const empty = {
       doneStageIds: /* @__PURE__ */ new Set(),
@@ -4783,7 +5020,11 @@ function TracedFlow({
   );
   const wrapperRef = useRef8(null);
   const [rfInstance, setRfInstance] = useState10(null);
-  useChartAutoRefit(wrapperRef, rfInstance, { refitKey: drill.currentSubflowId });
+  useChartAutoRefit(wrapperRef, rfInstance, {
+    // Re-fit on drill AND after the measured-size re-layout settles.
+    refitKey: `${drill.currentSubflowId ?? ""}:${measuredSizes ? "measured" : "estimated"}`,
+    padding: 0.18
+  });
   return /* @__PURE__ */ jsxs18(
     "div",
     {
@@ -4815,8 +5056,11 @@ function TracedFlow({
             onNodeClick: handleNodeClick,
             onInit: setRfInstance,
             fitView: true,
+            fitViewOptions: { padding: 0.18 },
+            minZoom: 0.1,
             proOptions: { hideAttribution: true },
             children: [
+              /* @__PURE__ */ jsx21(MeasuredNodeSizes, { onSizes: setMeasuredSizes }),
               /* @__PURE__ */ jsx21(Background, { variant: BackgroundVariant.Dots, gap: 20, size: 1 }),
               children
             ]
@@ -5590,7 +5834,7 @@ var DetailsContent = memo8(function DetailsContent2({
   const allViews = [...builtInViews, ...extraViews ?? []];
   const [activeViewId, setActiveViewId] = useState14(allViews[0]?.id ?? "memory");
   const viewIds = allViews.map((v2) => v2.id).join(",");
-  useEffect9(() => {
+  useEffect11(() => {
     if (!allViews.find((v2) => v2.id === activeViewId)) {
       setActiveViewId(allViews[0]?.id ?? "memory");
     }
@@ -5847,7 +6091,7 @@ function ExplainableShell({
   const shellRef = useRef9(null);
   const [isNarrow, setIsNarrow] = useState14(false);
   const [isMedium, setIsMedium] = useState14(false);
-  useEffect9(() => {
+  useEffect11(() => {
     const el = shellRef.current;
     if (!el) return;
     const ro = new ResizeObserver(([entry]) => {
@@ -5892,7 +6136,7 @@ function ExplainableShell({
   const [rightPanelMode, setRightPanelMode] = useState14("insights");
   const [leftExpanded, setLeftExpanded] = useState14(defaultExpanded?.topology ?? false);
   const [timelineExpanded, setTimelineExpanded] = useState14(defaultExpanded?.timeline ?? false);
-  useEffect9(() => {
+  useEffect11(() => {
     if (isNarrow) {
       setLeftExpanded(false);
       setRightExpanded(false);