footprint-explainable-ui 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprint-explainable-ui",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Themeable React components for visualizing FootPrint pipeline execution",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -38,7 +38,9 @@
     "clean": "rm -rf dist",
     "release:patch": "bash scripts/release.sh patch",
     "release:minor": "bash scripts/release.sh minor",
-    "release:major": "bash scripts/release.sh major"
+    "release:major": "bash scripts/release.sh major",
+    "test:coverage": "vitest run --coverage --coverage.reporter=json-summary --coverage.reporter=text-summary --coverage.reportsDirectory=coverage",
+    "coverage:badge": "npm run test:coverage; node scripts/coverage-badge.mjs"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
@@ -52,8 +54,10 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
+    "@types/dagre": "^0.7.54",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitest/coverage-v8": "^4.1.8",
     "@xyflow/react": "^12.10.2",
     "jsdom": "^29.0.1",
     "react": "^19.2.5",
@@ -75,5 +79,8 @@
     "react",
     "time-travel",
     "explainable-ai"
-  ]
+  ],
+  "dependencies": {
+    "dagre": "^0.8.5"
+  }
 }

package/dist/adapters/fromRuntimeSnapshot.d.ts

@@ -1,81 +0,0 @@
-import type { StageSnapshot, NarrativeEntry } from "../types";
-/**
- * Shape of FootPrint's RuntimeSnapshot (from FlowChartExecutor.getSnapshot()).
- * We define it here instead of importing to avoid a hard dependency on footprintjs.
- */
-interface RuntimeStageSnapshot {
-    id: string;
-    name?: string;
-    isDecider?: boolean;
-    isFork?: boolean;
-    /** User-level writes made by this stage (pre-namespace keys → values). */
-    stageWrites?: Record<string, unknown>;
-    logs: Record<string, unknown>;
-    errors: Record<string, unknown>;
-    metrics: Record<string, unknown>;
-    evals: Record<string, unknown>;
-    flowMessages?: unknown[];
-    description?: string;
-    subflowId?: string;
-    next?: RuntimeStageSnapshot;
-    children?: RuntimeStageSnapshot[];
-}
-interface RecorderSnapshot {
-    id: string;
-    name: string;
-    data: unknown;
-}
-interface RuntimeSnapshot {
-    sharedState: Record<string, unknown>;
-    executionTree: RuntimeStageSnapshot;
-    commitLog: unknown[];
-    /** Per-subflow execution results (keyed by subflowId). */
-    subflowResults?: Record<string, unknown>;
-    /** Snapshots from recorders that implement toSnapshot() (e.g. MetricRecorder). */
-    recorders?: RecorderSnapshot[];
-}
-export type { NarrativeEntry } from '../types';
-/**
- * Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
- * suitable for visualization components.
- *
- * The `narrativeEntries` parameter (from `executor.getNarrativeEntries()`)
- * distributes the library's rich combined narrative per-stage.
- * When narrative is not enabled, stages get "Narrative not available" —
- * this adapter reflects what the library produces, nothing more.
- *
- * Usage:
- * ```ts
- * const executor = new FlowChartExecutor(chart);
- * await executor.run();
- * const snapshots = toVisualizationSnapshots(
- *   executor.getSnapshot(),
- *   executor.getNarrativeEntries(),
- * );
- * ```
- */
-export declare function toVisualizationSnapshots(runtime: RuntimeSnapshot, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
-/**
- * Converts a footprintjs SubflowResult (stored on StageSnapshot.subflowResult)
- * into visualization snapshots for drill-down views.
- *
- * SubflowResult shape (from footprintjs):
- *   { subflowId, subflowName, treeContext: { globalContext, stageContexts, history }, parentStageId }
- *
- * Returns empty array if the input is not a valid SubflowResult.
- */
-export declare function subflowResultToSnapshots(subflowResult: unknown, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
-/**
- * Creates StageSnapshots from simple arrays (when you don't have a RuntimeSnapshot).
- * Useful for testing or custom data sources.
- */
-export declare function createSnapshots(stages: Array<{
-    name: string;
-    label?: string;
-    memory?: Record<string, unknown>;
-    narrative?: string;
-    durationMs?: number;
-    description?: string;
-    subflowId?: string;
-}>): StageSnapshot[];
-//# sourceMappingURL=fromRuntimeSnapshot.d.ts.map

package/dist/adapters/fromRuntimeSnapshot.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fromRuntimeSnapshot.d.ts","sourceRoot":"","sources":["../../src/adapters/fromRuntimeSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE9D;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACnC;AAED,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,UAAU,eAAe;IACvB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,EAAE,oBAAoB,CAAC;IACpC,SAAS,EAAE,OAAO,EAAE,CAAC;IACrB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,kFAAkF;IAClF,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAID,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,EACxB,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAClC,aAAa,EAAE,CAWjB;AAgKD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,OAAO,EACtB,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAClC,aAAa,EAAE,CAoCjB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,GACD,aAAa,EAAE,CAkBjB"}

package/dist/adapters/fromRuntimeSnapshot.js

@@ -1,226 +0,0 @@
-/**
- * Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
- * suitable for visualization components.
- *
- * The `narrativeEntries` parameter (from `executor.getNarrativeEntries()`)
- * distributes the library's rich combined narrative per-stage.
- * When narrative is not enabled, stages get "Narrative not available" —
- * this adapter reflects what the library produces, nothing more.
- *
- * Usage:
- * ```ts
- * const executor = new FlowChartExecutor(chart);
- * await executor.run();
- * const snapshots = toVisualizationSnapshots(
- *   executor.getSnapshot(),
- *   executor.getNarrativeEntries(),
- * );
- * ```
- */
-export function toVisualizationSnapshots(runtime, narrativeEntries) {
-    const stageNarrativeMap = narrativeEntries?.length
-        ? buildStageNarrativeMap(narrativeEntries)
-        : new Map();
-    // Extract per-stage timings from MetricRecorder if present in snapshot.recorders.
-    const stageTimings = extractStageTimings(runtime.recorders);
-    const snapshots = [];
-    flattenTree(runtime.executionTree, snapshots, runtime.sharedState, 0, runtime.subflowResults, {}, stageNarrativeMap, stageTimings);
-    return snapshots;
-}
-/**
- * Extracts per-stage duration data from recorder snapshots.
- *
- * Post-KeyedRecorder MetricRecorder serializes as
- *   { name: 'Metrics', data: { steps: { [runtimeStageId]: { stageName, duration, ... } } } }
- *
- * Older versions emitted `data.stages[stageName].totalDuration` directly;
- * we still accept that shape for back-compat when loading old snapshots.
- *
- * Stages that ran multiple times (e.g. CallLLM inside a loop) have one
- * entry per invocation keyed by runtimeStageId — sum their durations by
- * stageName so the GanttTimeline shows cumulative wall time per stage.
- */
-function extractStageTimings(recorders) {
-    const timings = new Map();
-    if (!recorders)
-        return timings;
-    for (const rec of recorders) {
-        if (rec.name !== 'Metrics' || !rec.data || typeof rec.data !== 'object')
-            continue;
-        const data = rec.data;
-        // New shape: data.steps[runtimeStageId] = { stageName, duration, ... }
-        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));
-            }
-        }
-        // Legacy shape: data.stages[stageName].totalDuration
-        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));
-                }
-            }
-        }
-    }
-    return timings;
-}
-/**
- * Groups narrative entries by stage name, preserving non-stage entries
- * (conditions, forks) attached to the preceding stage.
- */
-function buildStageNarrativeMap(entries) {
-    const map = new Map();
-    let currentStageName;
-    for (const entry of entries) {
-        if (entry.stageName) {
-            currentStageName = entry.stageName;
-        }
-        if (currentStageName) {
-            if (!map.has(currentStageName)) {
-                map.set(currentStageName, []);
-            }
-            const indent = '  '.repeat(entry.depth);
-            map.get(currentStageName).push(`${indent}${entry.text}`);
-        }
-    }
-    return map;
-}
-function flattenTree(node, out, sharedState, accumulatedMs = 0, subflowResults, cumulativeMemory = {}, stageNarrativeMap = new Map(), stageTimings = new Map()) {
-    // Prefer MetricRecorder timing (real wall-clock), then scope.$metric('durationMs'), then 0.
-    const stageName = node.name ?? node.id;
-    const durationMs = (stageName ? stageTimings.get(stageName) : undefined) ??
-        (typeof node.metrics?.durationMs === "number" ? node.metrics.durationMs : 0);
-    const startMs = accumulatedMs;
-    // Use id for matching (stable, matches spec node ids).
-    // name may carry display prefixes like "[service-name] STAGE".
-    const stageId = node.id || node.name || 'unknown';
-    const displayName = node.name || node.id || 'unknown';
-    // Narrative comes from the library. When not available (e.g. subflow internals
-    // where the root recorder only captures enter/exit markers), build a basic
-    // narrative from the stage name, description, and data operations.
-    // Try id first, then name — narrative entries use node.name (may be prefixed)
-    // while snapshot uses node.id (stable). Both need to match for subflows.
-    const stageLines = stageNarrativeMap.get(stageId) ?? stageNarrativeMap.get(displayName);
-    let narrative;
-    if (stageLines) {
-        narrative = stageLines.join('\n');
-    }
-    else {
-        const parts = [`${displayName} executed.`];
-        if (node.description)
-            parts.push(node.description);
-        if (node.stageWrites) {
-            const keys = Object.keys(node.stageWrites);
-            if (keys.length > 0)
-                parts.push(`Wrote: ${keys.join(', ')}`);
-        }
-        narrative = parts.join('\n');
-    }
-    // Build cumulative memory from stageWrites (actual setValue/updateValue calls)
-    const memory = { ...cumulativeMemory };
-    if (node.stageWrites) {
-        for (const [key, value] of Object.entries(node.stageWrites)) {
-            if (value === undefined) {
-                delete memory[key];
-            }
-            else {
-                memory[key] = value;
-            }
-        }
-    }
-    const sfResult = subflowResults?.[node.subflowId ?? stageId];
-    out.push({
-        stageName: displayName,
-        stageLabel: stageId,
-        runtimeStageId: node.runtimeStageId ?? undefined,
-        memory,
-        narrative,
-        startMs,
-        durationMs,
-        status: "done",
-        ...(node.description ? { description: node.description } : undefined),
-        ...(node.subflowId ? { subflowId: node.subflowId } : undefined),
-        ...(sfResult ? { subflowResult: sfResult } : undefined),
-    });
-    let nextMs = startMs + durationMs;
-    // Handle parallel children (fork)
-    if (node.children && node.children.length > 0) {
-        let maxChildEnd = nextMs;
-        for (const child of node.children) {
-            const childEnd = flattenTree(child, out, sharedState, nextMs, subflowResults, memory, stageNarrativeMap, stageTimings);
-            maxChildEnd = Math.max(maxChildEnd, childEnd);
-        }
-        nextMs = maxChildEnd;
-    }
-    // Handle linear continuation
-    if (node.next) {
-        nextMs = flattenTree(node.next, out, sharedState, nextMs, subflowResults, memory, stageNarrativeMap, stageTimings);
-    }
-    return nextMs;
-}
-/**
- * Converts a footprintjs SubflowResult (stored on StageSnapshot.subflowResult)
- * into visualization snapshots for drill-down views.
- *
- * SubflowResult shape (from footprintjs):
- *   { subflowId, subflowName, treeContext: { globalContext, stageContexts, history }, parentStageId }
- *
- * Returns empty array if the input is not a valid SubflowResult.
- */
-export function subflowResultToSnapshots(subflowResult, narrativeEntries) {
-    if (!subflowResult || typeof subflowResult !== 'object')
-        return [];
-    const sf = subflowResult;
-    if (!sf.treeContext?.stageContexts)
-        return [];
-    const runtime = {
-        sharedState: sf.treeContext.globalContext ?? {},
-        executionTree: sf.treeContext.stageContexts,
-        commitLog: sf.treeContext.history ?? [],
-    };
-    const snapshots = toVisualizationSnapshots(runtime, narrativeEntries);
-    // Strip subflow prefix from stage names so they match the spec node names.
-    // Runtime names are prefixed (e.g., "analyze/SeedScope") but spec nodes
-    // use unprefixed names (e.g., "SeedScope").
-    const prefix = sf.subflowId ? `${sf.subflowId}/` : '';
-    if (prefix) {
-        for (const snap of snapshots) {
-            if (snap.stageName.startsWith(prefix)) {
-                snap.stageName = snap.stageName.slice(prefix.length);
-            }
-            if (snap.stageLabel.startsWith(prefix)) {
-                snap.stageLabel = snap.stageLabel.slice(prefix.length);
-            }
-        }
-    }
-    return snapshots;
-}
-/**
- * Creates StageSnapshots from simple arrays (when you don't have a RuntimeSnapshot).
- * Useful for testing or custom data sources.
- */
-export function createSnapshots(stages) {
-    let accMs = 0;
-    return stages.map((s) => {
-        const duration = s.durationMs ?? 1;
-        const snap = {
-            stageName: s.name,
-            stageLabel: s.label ?? s.name,
-            memory: s.memory ?? {},
-            narrative: s.narrative ?? `${s.label ?? s.name} completed.`,
-            startMs: accMs,
-            durationMs: duration,
-            status: "done",
-            ...(s.description ? { description: s.description } : undefined),
-            ...(s.subflowId ? { subflowId: s.subflowId } : undefined),
-        };
-        accMs += duration;
-        return snap;
-    });
-}
-//# sourceMappingURL=fromRuntimeSnapshot.js.map

package/dist/adapters/fromRuntimeSnapshot.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"fromRuntimeSnapshot.js","sourceRoot":"","sources":["../../src/adapters/fromRuntimeSnapshot.ts"],"names":[],"mappings":"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"}

package/dist/components/ExplainableShell/ExplainableShell.d.ts

@@ -1,169 +0,0 @@
-import type { StageSnapshot, BaseComponentProps, NarrativeEntry } from "../../types";
-/**
- * Minimal subflow-walking spec shape. Used INTERNALLY by drill-down
- * resolution (which navigates `subflowStructure` to find a child chart
- * inside the parent's serialized structure). No longer used for chart
- * rendering — that happens via `traceGraph` + `<TracedFlow>` exclusively.
- *
- * Kept as a local type so the file no longer depends on any legacy
- * spec-walk module.
- */
-export interface SpecNode {
-    name: string;
-    id?: string;
-    description?: string;
-    children?: SpecNode[];
-    next?: SpecNode;
-    isSubflowRoot?: boolean;
-    subflowId?: string;
-    subflowName?: string;
-    subflowStructure?: SpecNode;
-}
-/** Tab ID — "result", "memory", "narrative", or any custom recorder view ID. */
-export type ShellTab = string;
-export interface PanelLabels {
-    /** Left panel pill label (subflow tree). Default: "Topology" */
-    topology?: string;
-    /** Right panel pill label (memory/narrative). Default: "Details" */
-    details?: string;
-    /** Bottom panel pill label (timeline). Default: "Timeline" */
-    timeline?: string;
-}
-/** Which panels start expanded. Default: `{ details: true }` (flowchart + memory). */
-export interface DefaultExpanded {
-    topology?: boolean;
-    details?: boolean;
-    timeline?: boolean;
-}
-/**
- * Raw runtime snapshot from FlowChartExecutor.getSnapshot().
- * When provided, ExplainableShell converts it internally — zero boilerplate.
- */
-export interface RuntimeSnapshotInput {
-    sharedState: Record<string, unknown>;
-    executionTree: unknown;
-    commitLog: unknown[];
-    subflowResults?: Record<string, unknown>;
-    /** Recorder snapshots from toSnapshot() — auto-generates detail tabs. */
-    recorders?: Array<{
-        id: string;
-        name: string;
-        description?: string;
-        preferredOperation?: 'translate' | 'accumulate' | 'aggregate';
-        data: unknown;
-    }>;
-}
-/**
- * A recorder view that appears as a tab in the details panel.
- * Each recorder provides its own per-stage rendering.
- * Memory and Narrative are built-in defaults — add more via this prop.
- */
-export interface RecorderView {
-    /** Unique key for this view tab */
-    id: string;
-    /** Display label on the tab */
-    name: string;
-    /** Short description shown as tooltip and header for auto-detected views.
-     *  e.g., "Per-step timing and I/O counts (KeyedRecorder)" */
-    description?: string;
-    /**
-     * Render function — receives the current snapshot index and all snapshots.
-     * Return a React node to display in the details panel.
-     */
-    render: (props: {
-        snapshots: StageSnapshot[];
-        selectedIndex: number;
-    }) => React.ReactNode;
-}
-export interface ExplainableShellProps extends BaseComponentProps {
-    /**
-     * Pre-converted visualization snapshots. Use when you've already called
-     * toVisualizationSnapshots() yourself.
-     */
-    snapshots?: StageSnapshot[];
-    /**
-     * Raw runtime snapshot from executor.getSnapshot(). The shell converts it
-     * internally via toVisualizationSnapshots(). When provided, `snapshots`
-     * and `resultData` are derived automatically. Pair with
-     * `narrativeEntries` for rich per-stage narrative.
-     *
-     * Usage: `<ExplainableShell runtimeSnapshot={executor.getSnapshot()} narrativeEntries={executor.getNarrativeEntries()} spec={spec} />`
-     */
-    runtimeSnapshot?: RuntimeSnapshotInput | null;
-    spec?: SpecNode | null;
-    /**
-     * Build-time graph captured live via `createTraceStructureRecorder`.
-     * REQUIRED for chart rendering (v6+) — the legacy `spec` →
-     * legacy spec-walk post-walk path was removed in favor of this
-     * recorder-driven graph.
-     *
-     * Pair with `runtimeOverlay` for the full time-travel trace UI.
-     * When `traceGraph` is set but `runtimeOverlay` is absent, the
-     * chart renders without runtime coloring (build-time-only view).
-     *
-     * The `spec` prop, when also provided, is used INTERNALLY for
-     * subflow drill-down resolution (navigating `subflowStructure` to
-     * find a child chart inside the parent's serialized structure) —
-     * NOT for rendering.
-     */
-    traceGraph?: import("../FlowchartView/traceStructureRecorder").TraceGraph | null;
-    /**
-     * Runtime overlay captured live via `createTraceRuntimeOverlay`.
-     * Pair with `traceGraph` to drive `<TracedFlow>` for the full
-     * time-travel trace UI.
-     */
-    runtimeOverlay?: import("../FlowchartView/createTraceRuntimeOverlay").RuntimeOverlay | null;
-    title?: string;
-    resultData?: Record<string, unknown> | null;
-    logs?: string[];
-    /** Structured narrative entries from `executor.getNarrativeEntries()`.
-     *  This is the only narrative input — the flat-string form was
-     *  removed; call `.map(e => e.text)` if you need it. */
-    narrativeEntries?: NarrativeEntry[];
-    tabs?: ShellTab[];
-    defaultTab?: ShellTab;
-    hideConsole?: boolean;
-    /** Hide specific detail tabs (e.g., ['result', 'memory']). */
-    hideTabs?: string[];
-    /** Customize the labels on collapsible panel pills */
-    panelLabels?: PanelLabels;
-    /** Which panels start expanded. Default: `{ details: true }` */
-    defaultExpanded?: DefaultExpanded;
-    /**
-     * Recorder views — each becomes a tab in the details panel.
-     * Default: Memory + Narrative. Pass additional recorder views
-     * to show tokens, cost, tools, permissions, or custom data.
-     *
-     * Usage:
-     *   recorderViews={[
-     *     { id: 'tokens', name: 'Tokens', render: ({ selectedIndex }) => <div>...</div> },
-     *   ]}
-     */
-    recorderViews?: RecorderView[];
-    /**
-     * Custom flowchart renderer. When omitted, ExplainableShell renders
-     * via `<TracedFlow graph={traceGraph} overlay={runtimeOverlay} />` —
-     * the recorder-driven path. Override to plug a custom chart UI; the
-     * `spec` parameter is forwarded only for backward-compatible
-     * signatures (it's the same SpecNode used for drill-down) and may
-     * be `null` once consumers stop threading it in.
-     */
-    renderFlowchart?: (props: {
-        spec: SpecNode | null;
-        snapshots: StageSnapshot[];
-        selectedIndex: number;
-        onNodeClick?: (indexOrId: number | string) => void;
-        showStageId?: boolean;
-    }) => React.ReactNode;
-    /**
-     * When true, render each node's stable `stageId` as a small monospace
-     * caption beneath the label in the default flowchart renderer.
-     * Teaching aid: it reveals the key recorders use
-     * (`runtimeStageId = [subflowPath/]stageId#executionIndex`) so a
-     * consumer can map any recorder's per-stage data back to a node.
-     * Default false.
-     */
-    showStageId?: boolean;
-}
-export 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): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=ExplainableShell.d.ts.map

package/dist/components/ExplainableShell/ExplainableShell.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ExplainableShell.d.ts","sourceRoot":"","sources":["../../../src/components/ExplainableShell/ExplainableShell.tsx"],"names":[],"mappings":"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"}