footprint-explainable-ui 0.18.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/dist/adapters/fromRuntimeSnapshot.d.ts +33 -4
  2. package/dist/adapters/fromRuntimeSnapshot.d.ts.map +1 -1
  3. package/dist/adapters/fromRuntimeSnapshot.js +162 -33
  4. package/dist/adapters/fromRuntimeSnapshot.js.map +1 -1
  5. package/dist/components/ExplainableShell/ExplainableShell.d.ts +157 -14
  6. package/dist/components/ExplainableShell/ExplainableShell.d.ts.map +1 -1
  7. package/dist/components/ExplainableShell/ExplainableShell.js +676 -68
  8. package/dist/components/ExplainableShell/ExplainableShell.js.map +1 -1
  9. package/dist/components/ExplainableShell/index.d.ts +1 -1
  10. package/dist/components/ExplainableShell/index.d.ts.map +1 -1
  11. package/dist/components/FlowchartView/SubflowTree.d.ts +7 -14
  12. package/dist/components/FlowchartView/SubflowTree.d.ts.map +1 -1
  13. package/dist/components/FlowchartView/SubflowTree.js +56 -46
  14. package/dist/components/FlowchartView/SubflowTree.js.map +1 -1
  15. package/dist/components/FlowchartView/index.d.ts +32 -4
  16. package/dist/components/FlowchartView/index.d.ts.map +1 -1
  17. package/dist/components/FlowchartView/index.js +22 -2
  18. package/dist/components/FlowchartView/index.js.map +1 -1
  19. package/dist/components/FlowchartView/useSubflowNavigation.d.ts +41 -16
  20. package/dist/components/FlowchartView/useSubflowNavigation.d.ts.map +1 -1
  21. package/dist/components/FlowchartView/useSubflowNavigation.js +69 -50
  22. package/dist/components/FlowchartView/useSubflowNavigation.js.map +1 -1
  23. package/dist/components/GanttTimeline/GanttTimeline.d.ts.map +1 -1
  24. package/dist/components/GanttTimeline/GanttTimeline.js +5 -5
  25. package/dist/components/GanttTimeline/GanttTimeline.js.map +1 -1
  26. package/dist/components/MemoryInspector/MemoryInspector.d.ts.map +1 -1
  27. package/dist/components/MemoryInspector/MemoryInspector.js +36 -13
  28. package/dist/components/MemoryInspector/MemoryInspector.js.map +1 -1
  29. package/dist/components/NarrativeTrace/NarrativeTrace.d.ts.map +1 -1
  30. package/dist/components/NarrativeTrace/NarrativeTrace.js +24 -17
  31. package/dist/components/NarrativeTrace/NarrativeTrace.js.map +1 -1
  32. package/dist/components/ScopeDiff/ScopeDiff.js +3 -3
  33. package/dist/components/ScopeDiff/ScopeDiff.js.map +1 -1
  34. package/dist/components/StageNode/StageNode.d.ts +21 -0
  35. package/dist/components/StageNode/StageNode.d.ts.map +1 -1
  36. package/dist/components/StageNode/StageNode.js +189 -9
  37. package/dist/components/StageNode/StageNode.js.map +1 -1
  38. package/dist/components/TimeTravelControls/TimeTravelControls.d.ts.map +1 -1
  39. package/dist/components/TimeTravelControls/TimeTravelControls.js +19 -3
  40. package/dist/components/TimeTravelControls/TimeTravelControls.js.map +1 -1
  41. package/dist/components/TimeTravelDebugger/TimeTravelDebugger.d.ts +19 -8
  42. package/dist/components/TimeTravelDebugger/TimeTravelDebugger.d.ts.map +1 -1
  43. package/dist/components/TimeTravelDebugger/TimeTravelDebugger.js +23 -8
  44. package/dist/components/TimeTravelDebugger/TimeTravelDebugger.js.map +1 -1
  45. package/dist/flowchart.cjs +3485 -1340
  46. package/dist/flowchart.cjs.map +1 -1
  47. package/dist/flowchart.d.cts +1616 -177
  48. package/dist/flowchart.d.ts +1616 -177
  49. package/dist/flowchart.d.ts.map +1 -1
  50. package/dist/flowchart.js +3507 -1384
  51. package/dist/flowchart.js.map +1 -1
  52. package/dist/index.cjs +749 -557
  53. package/dist/index.cjs.map +1 -1
  54. package/dist/index.d.cts +276 -29
  55. package/dist/index.d.ts +276 -29
  56. package/dist/index.d.ts.map +1 -1
  57. package/dist/index.js +742 -547
  58. package/dist/index.js.map +1 -1
  59. package/dist/theme/ThemeProvider.d.ts +14 -0
  60. package/dist/theme/ThemeProvider.d.ts.map +1 -1
  61. package/dist/theme/ThemeProvider.js +15 -1
  62. package/dist/theme/ThemeProvider.js.map +1 -1
  63. package/dist/theme/index.d.ts +4 -2
  64. package/dist/theme/index.d.ts.map +1 -1
  65. package/dist/theme/index.js +3 -2
  66. package/dist/theme/index.js.map +1 -1
  67. package/dist/theme/presets.d.ts +3 -0
  68. package/dist/theme/presets.d.ts.map +1 -1
  69. package/dist/theme/presets.js +22 -0
  70. package/dist/theme/presets.js.map +1 -1
  71. package/dist/theme/tokens.d.ts +22 -1
  72. package/dist/theme/tokens.d.ts.map +1 -1
  73. package/dist/theme/tokens.js +23 -2
  74. package/dist/theme/tokens.js.map +1 -1
  75. package/dist/tsconfig.tsbuildinfo +1 -1
  76. package/dist/types.d.ts +25 -0
  77. package/dist/types.d.ts.map +1 -1
  78. package/package.json +4 -4
  79. package/dist/components/FlowchartView/FlowchartView.d.ts +0 -20
  80. package/dist/components/FlowchartView/FlowchartView.d.ts.map +0 -1
  81. package/dist/components/FlowchartView/FlowchartView.js +0 -80
  82. package/dist/components/FlowchartView/FlowchartView.js.map +0 -1
  83. package/dist/components/FlowchartView/TracedFlowchartView.d.ts +0 -20
  84. package/dist/components/FlowchartView/TracedFlowchartView.d.ts.map +0 -1
  85. package/dist/components/FlowchartView/TracedFlowchartView.js +0 -101
  86. package/dist/components/FlowchartView/TracedFlowchartView.js.map +0 -1
  87. package/dist/components/FlowchartView/specToReactFlow.d.ts +0 -56
  88. package/dist/components/FlowchartView/specToReactFlow.d.ts.map +0 -1
  89. package/dist/components/FlowchartView/specToReactFlow.js +0 -202
  90. package/dist/components/FlowchartView/specToReactFlow.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import { Node, Edge } from '@xyflow/react';
2
3
  import * as react from 'react';
3
4
 
4
5
  /** Snapshot of a single pipeline stage — the core data shape for all components. */
@@ -28,7 +29,7 @@ interface StageSnapshot {
28
29
  }
29
30
  /** Structured narrative entry — preserves type info for semantic rendering. */
30
31
  interface NarrativeEntry {
31
- type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error' | 'pause' | 'resume';
32
+ type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error' | 'pause' | 'resume' | 'emit';
32
33
  text: string;
33
34
  depth: number;
34
35
  stageName?: string;
@@ -118,6 +119,20 @@ interface FootprintThemeProps {
118
119
  /**
119
120
  * Optional theme provider — wraps children with CSS custom properties.
120
121
  * Consumers can also just set --fp-* CSS variables directly.
122
+ *
123
+ * Wrapper div uses `display: contents` so it's invisible to the
124
+ * parent's layout (flex / grid / block). This matters because themed
125
+ * children often need to fill a parent (flex:1 / height:100% /
126
+ * grid cells), and a regular block `<div>` here would break that
127
+ * chain — descendants would resolve to 0 height when the parent is
128
+ * flex-column or a grid cell with minmax(0, 1fr). `display: contents`
129
+ * removes the box from the render tree while keeping the DOM intact,
130
+ * so CSS custom property inheritance (which follows the DOM) still
131
+ * flows to children.
132
+ *
133
+ * Trade-off: `display: contents` elements are removed from the
134
+ * accessibility tree in some older browser versions. Our wrapper has
135
+ * no semantic role, so this is fine.
121
136
  */
122
137
  declare function FootprintTheme({ tokens, children }: FootprintThemeProps): react_jsx_runtime.JSX.Element;
123
138
 
@@ -308,29 +323,223 @@ interface TimeTravelControlsProps extends BaseComponentProps {
308
323
  }
309
324
  declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react_jsx_runtime.JSX.Element;
310
325
 
326
+ /**
327
+ * One entry in the execution timeline. `<TracedFlow>` keys time-travel
328
+ * scrubbing on the index into this array — at index `i`, all entries
329
+ * `0..i-1` are "done", entry `i` is "active".
330
+ */
331
+ interface RuntimeExecutionStep {
332
+ /** `[subflowPath/]stageId#executionIndex` — universal key. */
333
+ readonly runtimeStageId: string;
334
+ /** Base stage id (without `#N`) — matches the `TraceGraph` node id. */
335
+ readonly stageId: string;
336
+ /** Human-readable label (from event.stageName). */
337
+ readonly stageName: string;
338
+ /** When this step recorded, in ms since recorder start. */
339
+ readonly timestampMs: number;
340
+ }
341
+ interface RuntimeOverlay {
342
+ /** Ordered execution history — drives time-travel scrubbing. */
343
+ readonly executionOrder: readonly RuntimeExecutionStep[];
344
+ /** Per-base-stageId error message (most-recent wins). */
345
+ readonly errors: ReadonlyMap<string, string>;
346
+ /** True after `onRunStart` until `onRunEnd` — useful for "still running" indicators. */
347
+ readonly running: boolean;
348
+ }
349
+
350
+ /**
351
+ * Branded types for translator key discipline.
352
+ *
353
+ * The footprintjs/trace contract uses two distinct identity strings:
354
+ *
355
+ * - **StageId**: the stable identifier the user picks at build time
356
+ * (e.g. `'load-order'`, `'check-inventory'`). Identity per chart spec.
357
+ *
358
+ * - **RuntimeStageId**: `[subflowPath/]stageId#executionIndex` — the
359
+ * per-execution identity. A loop visiting the same stage 3 times
360
+ * produces 3 distinct RuntimeStageIds with the same StageId base.
361
+ *
362
+ * Translator outputs index per-stage data by StageId (`Map<StageId, ...>`)
363
+ * AND per-execution data by RuntimeStageId (`Map<RuntimeStageId, ...>`).
364
+ * Both are `string` at runtime — TypeScript can't distinguish them
365
+ * without help. Branded types make `byStageId.get(runtimeStageId)` a
366
+ * **compile-time error** instead of a silent `undefined` at runtime.
367
+ *
368
+ * Why branded types over wrapper classes
369
+ * ──────────────────────────────────────
370
+ * - Zero runtime cost (the brand exists only at the type level)
371
+ * - JSON-serializable as-is (no `toJSON` glue needed)
372
+ * - Interop with consumer code that uses raw `string` is one cast
373
+ * (`stageId as StageId`) when the consumer is sure of the source.
374
+ *
375
+ * Usage pattern
376
+ * ─────────────
377
+ * ```ts
378
+ * import type { StageId, RuntimeStageId } from './_internal/keys';
379
+ *
380
+ * // In a translator, when accepting input from a footprintjs event:
381
+ * const sid = event.stageId as StageId;
382
+ * const rsid = event.traversalContext.runtimeStageId as RuntimeStageId;
383
+ *
384
+ * // In a consumer reading from the index:
385
+ * const node = index.byStageId.get(stageId); // typechecks
386
+ * const node = index.byStageId.get(runtimeStageId); // TS ERROR ✓
387
+ * ```
388
+ *
389
+ * Helper to derive a StageId from a RuntimeStageId — strips `#N` suffix
390
+ * and optional subflow path. **Use only for DISPLAY**, NEVER for matching
391
+ * commitLog stageIds (see invariant I3 in `traceStructureRecorder.ts`).
392
+ */
393
+ /** Stable per-spec identifier (e.g. `'load-order'`). */
394
+ type StageId = string & {
395
+ readonly __brand: "StageId";
396
+ };
397
+
398
+ /**
399
+ * traceStructureRecorder — event-driven xyflow Node[] + Edge[] collector.
400
+ *
401
+ * Implements footprintjs v6.0+ `StructureRecorder` interface. Accumulates
402
+ * an unpositioned graph (xyflow node + edge shape) as the chart is being
403
+ * built — no spec tree walk required.
404
+ *
405
+ * Why event-driven
406
+ * ────────────────
407
+ * The recorder fires SYNCHRONOUSLY at every spec-mutation moment during
408
+ * construction. By the time `.build()` returns, the recorder's
409
+ * `getGraph()` returns the complete graph — zero extra walking
410
+ * (the "collect during traversal, never post-process" rule footprintjs
411
+ * documents in its core principle).
412
+ *
413
+ * Bonus: the same recorder shape can drive incremental UI updates if
414
+ * the builder is constructed asynchronously (e.g., a UI builder where
415
+ * each "add stage" click re-renders the live graph).
416
+ *
417
+ * Layout is a separate concern
418
+ * ────────────────────────────
419
+ * This module produces UNPOSITIONED nodes (no `position` field set;
420
+ * xyflow defaults to `{x: 0, y: 0}`). Apply a layout algorithm
421
+ * downstream — either:
422
+ *
423
+ * - a graph algorithm (dagre / elk / d3-force)
424
+ * - manual positioning via your own walk over `recorder.getGraph()`
425
+ *
426
+ * The `<TraceFlow>` component wires a default BFS layout.
427
+ *
428
+ * @example
429
+ * ```ts
430
+ * import { flowChart } from 'footprintjs';
431
+ * import { createTraceStructureRecorder } from 'footprint-explainable-ui/flowchart';
432
+ *
433
+ * const trace = createTraceStructureRecorder();
434
+ * const chart = flowChart('seed', fn, 'seed', {
435
+ * structureRecorders: [trace.recorder],
436
+ * })
437
+ * .addFunction('a', fnA, 'a')
438
+ * .build();
439
+ *
440
+ * const { nodes, edges } = trace.getGraph();
441
+ * // → nodes: [{ id: 'seed', data: { label: 'seed', ... } }, { id: 'a', ... }]
442
+ * // → edges: [{ id: 'seed->a', source: 'seed', target: 'a', data: { kind: 'next' } }]
443
+ *
444
+ * <ReactFlow nodes={layout(nodes)} edges={edges} />
445
+ * ```
446
+ */
447
+
448
+ type EdgeKind = "next" | "fork-branch" | "decision-branch";
449
+ /**
450
+ * Per-node data attached to the xyflow `Node`. Consumed by the
451
+ * `StageNode` renderer (shape mirrors what the renderer expects).
452
+ */
453
+ interface TraceNodeData extends Record<string, unknown> {
454
+ label: string;
455
+ isDecider: boolean;
456
+ isFork: boolean;
457
+ isSubflow: boolean;
458
+ /** True when the event carried `type: 'streaming'` (the spec was added
459
+ * via `addStreamingFunction`). Renderers that style streaming stages
460
+ * distinctly key on this flag. */
461
+ isStreaming: boolean;
462
+ description?: string;
463
+ icon?: string;
464
+ subflowId?: string;
465
+ isLazy?: boolean;
466
+ isPausable?: boolean;
467
+ /** Set later by `onDeciderComplete` when the decider's branch list is
468
+ * sealed. Useful for renderers that want to render decider with a
469
+ * branch-count badge. */
470
+ branchIds?: readonly string[];
471
+ defaultBranch?: string;
472
+ /**
473
+ * The subflow this node belongs to, OR `undefined` for top-level
474
+ * parent-chart stages. Tracked via a stack-based heuristic during
475
+ * event ingestion:
476
+ *
477
+ * - Push on `onSubflowMounted({subflowId, rootStageId})` →
478
+ * top-of-stack = `{subflowId, mountStageId}`
479
+ * - `onStageAdded` tags new nodes with the top-of-stack `subflowId`
480
+ * (the mount node itself stays UNtagged — it's part of the parent
481
+ * chain)
482
+ * - Pop on `onEdgeAdded` where `from === mount.id` (a mount's
483
+ * outgoing edge to a sibling means the parent chain has resumed);
484
+ * the wrongly-tagged target node is re-tagged to the parent scope
485
+ *
486
+ * Mount nodes (where `isSubflow=true`) have `subflowOf` reflecting
487
+ * their OWN parent context, NOT the subflow they mount. So a parent's
488
+ * mount node has `subflowOf=undefined` (top-level parent), and the
489
+ * subflow's INTERNAL stages have `subflowOf=<mount.subflowId>`.
490
+ *
491
+ * Renderers use this to filter the chart by drill-down level: show
492
+ * only nodes where `subflowOf === currentDrillSubflowId` (undefined
493
+ * for top-level view, mount.subflowId after drilling in).
494
+ */
495
+ subflowOf?: string;
496
+ /**
497
+ * **L8.0 — STRUCTURAL prev/next**: stage ids that lead into / out of
498
+ * this node, derived live from incoming/outgoing edges. Excludes
499
+ * `loop` back-edges (visual only — per invariant I1).
500
+ *
501
+ * Convergence-correct: a fork-join node carries an ENTRY per branch
502
+ * child (e.g., `FinalizeOrder.prevIds = ['CheckInventory', 'RunFraudCheck']`).
503
+ *
504
+ * "Structural" qualifier: this is the chart-SHAPE prev/next, not
505
+ * runtime execution order. For runtime ancestry use `CommitView`
506
+ * fields on `CommitFlowIndex` (L8.2).
507
+ */
508
+ prevIds: StageId[];
509
+ nextIds: StageId[];
510
+ }
511
+ /** Per-edge data attached to the xyflow `Edge`. */
512
+ interface TraceEdgeData extends Record<string, unknown> {
513
+ kind: EdgeKind | "loop";
514
+ label?: string;
515
+ }
516
+ type TraceNode = Node<TraceNodeData>;
517
+ type TraceEdge = Edge<TraceEdgeData>;
518
+ interface TraceGraph {
519
+ nodes: TraceNode[];
520
+ edges: TraceEdge[];
521
+ }
522
+
523
+ /**
524
+ * Minimal subflow-walking spec shape. Used INTERNALLY by drill-down
525
+ * resolution (which navigates `subflowStructure` to find a child chart
526
+ * inside the parent's serialized structure). No longer used for chart
527
+ * rendering — that happens via `traceGraph` + `<TracedFlow>` exclusively.
528
+ *
529
+ * Kept as a local type so the file no longer depends on any legacy
530
+ * spec-walk module.
531
+ */
311
532
  interface SpecNode {
312
533
  name: string;
313
534
  id?: string;
314
- type?: "stage" | "decider" | "selector" | "fork" | "streaming";
315
- /** Semantic icon hint — rendered by StageNode. Common values:
316
- * "llm", "tool", "rag", "search", "parse", "start", "end", "loop",
317
- * "agent", "swarm", "guard", "stream", "memory" */
318
- icon?: string;
319
535
  description?: string;
320
536
  children?: SpecNode[];
321
537
  next?: SpecNode;
322
- branchIds?: string[];
323
- hasDecider?: boolean;
324
- hasSelector?: boolean;
325
- loopTarget?: string;
326
538
  isSubflowRoot?: boolean;
327
539
  subflowId?: string;
328
540
  subflowName?: string;
329
541
  subflowStructure?: SpecNode;
330
- /** True when this subflow uses lazy resolution (deferred until execution). */
331
- isLazy?: boolean;
332
542
  }
333
-
334
543
  /** Tab ID — "result", "memory", "narrative", or any custom recorder view ID. */
335
544
  type ShellTab = string;
336
545
  interface PanelLabels {
@@ -395,17 +604,42 @@ interface ExplainableShellProps extends BaseComponentProps {
395
604
  snapshots?: StageSnapshot[];
396
605
  /**
397
606
  * Raw runtime snapshot from executor.getSnapshot(). The shell converts it
398
- * internally via toVisualizationSnapshots(). When provided, `snapshots`,
399
- * `resultData`, and `narrative` are derived automatically.
607
+ * internally via toVisualizationSnapshots(). When provided, `snapshots`
608
+ * and `resultData` are derived automatically. Pair with
609
+ * `narrativeEntries` for rich per-stage narrative.
400
610
  *
401
- * Usage: `<ExplainableShell runtimeSnapshot={executor.getSnapshot()} spec={spec} />`
611
+ * Usage: `<ExplainableShell runtimeSnapshot={executor.getSnapshot()} narrativeEntries={executor.getNarrativeEntries()} spec={spec} />`
402
612
  */
403
613
  runtimeSnapshot?: RuntimeSnapshotInput | null;
404
614
  spec?: SpecNode | null;
615
+ /**
616
+ * Build-time graph captured live via `createTraceStructureRecorder`.
617
+ * REQUIRED for chart rendering (v6+) — the legacy `spec` →
618
+ * legacy spec-walk post-walk path was removed in favor of this
619
+ * recorder-driven graph.
620
+ *
621
+ * Pair with `runtimeOverlay` for the full time-travel trace UI.
622
+ * When `traceGraph` is set but `runtimeOverlay` is absent, the
623
+ * chart renders without runtime coloring (build-time-only view).
624
+ *
625
+ * The `spec` prop, when also provided, is used INTERNALLY for
626
+ * subflow drill-down resolution (navigating `subflowStructure` to
627
+ * find a child chart inside the parent's serialized structure) —
628
+ * NOT for rendering.
629
+ */
630
+ traceGraph?: TraceGraph | null;
631
+ /**
632
+ * Runtime overlay captured live via `createTraceRuntimeOverlay`.
633
+ * Pair with `traceGraph` to drive `<TracedFlow>` for the full
634
+ * time-travel trace UI.
635
+ */
636
+ runtimeOverlay?: RuntimeOverlay | null;
405
637
  title?: string;
406
638
  resultData?: Record<string, unknown> | null;
407
639
  logs?: string[];
408
- narrative?: string[];
640
+ /** Structured narrative entries from `executor.getNarrativeEntries()`.
641
+ * This is the only narrative input — the flat-string form was
642
+ * removed; call `.map(e => e.text)` if you need it. */
409
643
  narrativeEntries?: NarrativeEntry[];
410
644
  tabs?: ShellTab[];
411
645
  defaultTab?: ShellTab;
@@ -428,17 +662,31 @@ interface ExplainableShellProps extends BaseComponentProps {
428
662
  */
429
663
  recorderViews?: RecorderView[];
430
664
  /**
431
- * Custom flowchart renderer. When omitted and `spec` is provided,
432
- * ExplainableShell renders TracedFlowchartView by default.
665
+ * Custom flowchart renderer. When omitted, ExplainableShell renders
666
+ * via `<TracedFlow graph={traceGraph} overlay={runtimeOverlay} />` —
667
+ * the recorder-driven path. Override to plug a custom chart UI; the
668
+ * `spec` parameter is forwarded only for backward-compatible
669
+ * signatures (it's the same SpecNode used for drill-down) and may
670
+ * be `null` once consumers stop threading it in.
433
671
  */
434
672
  renderFlowchart?: (props: {
435
- spec: SpecNode;
673
+ spec: SpecNode | null;
436
674
  snapshots: StageSnapshot[];
437
675
  selectedIndex: number;
438
676
  onNodeClick?: (indexOrId: number | string) => void;
677
+ showStageId?: boolean;
439
678
  }) => React.ReactNode;
679
+ /**
680
+ * When true, render each node's stable `stageId` as a small monospace
681
+ * caption beneath the label in the default flowchart renderer.
682
+ * Teaching aid: it reveals the key recorders use
683
+ * (`runtimeStageId = [subflowPath/]stageId#executionIndex`) so a
684
+ * consumer can map any recorder's per-stage data back to a node.
685
+ * Default false.
686
+ */
687
+ showStageId?: boolean;
440
688
  }
441
- declare function ExplainableShell({ snapshots: snapshotsProp, runtimeSnapshot, spec, title, resultData: resultDataProp, logs, narrative: narrativeProp, narrativeEntries, tabs, defaultTab, hideConsole, hideTabs: hideTabsProp, panelLabels, defaultExpanded, recorderViews, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
689
+ 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;
442
690
 
443
691
  /**
444
692
  * TraceViewer — drop-in component that renders an `agentfootprint.exportTrace()`
@@ -493,7 +741,6 @@ interface AgentfootprintTrace {
493
741
  readonly redacted?: boolean;
494
742
  readonly snapshot?: unknown;
495
743
  readonly narrativeEntries?: unknown[];
496
- readonly narrative?: string[];
497
744
  readonly spec?: unknown;
498
745
  }
499
746
  /**
@@ -540,10 +787,9 @@ declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, classNa
540
787
  interface NarrativePanelProps extends BaseComponentProps {
541
788
  snapshots: StageSnapshot[];
542
789
  selectedIndex: number;
543
- /** Structured narrative entries (preferred — richer rendering) */
790
+ /** Structured narrative entries (primary source — richer rendering).
791
+ * When absent, falls back to per-stage `snapshot.narrative` lines. */
544
792
  narrativeEntries?: NarrativeEntry[];
545
- /** Plain narrative lines (fallback) */
546
- narrative?: string[];
547
793
  /**
548
794
  * Full runtime snapshot from the runner (executor.getSnapshot() /
549
795
  * agent.getSnapshot()). When present, "Copy for LLM" includes the
@@ -560,7 +806,7 @@ interface NarrativePanelProps extends BaseComponentProps {
560
806
  */
561
807
  spec?: any;
562
808
  }
563
- declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, narrative: narrativeProp, runtimeSnapshot, spec, size, unstyled, className, style, }: NarrativePanelProps): react_jsx_runtime.JSX.Element;
809
+ declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, runtimeSnapshot, spec, size, unstyled, className, style, }: NarrativePanelProps): react_jsx_runtime.JSX.Element;
564
810
 
565
811
  interface StoryNarrativeProps extends BaseComponentProps {
566
812
  /** Structured narrative entries from CombinedNarrativeRecorder */
@@ -579,12 +825,13 @@ interface SubflowTreeEntry {
579
825
  subflowId?: string;
580
826
  /** Whether this node is a subflow root (has nested structure) */
581
827
  isSubflow?: boolean;
582
- /** Nested children (subflow stages) */
828
+ /** Nested children (subflow stages) — always undefined in the
829
+ * current recorder-driven implementation; see file-level TODO. */
583
830
  children?: SubflowTreeEntry[];
584
831
  }
585
832
  interface SubflowTreeProps extends BaseComponentProps {
586
- /** Pipeline spec to derive the tree from */
587
- spec: SpecNode;
833
+ /** Recorder-captured graph from `createTraceStructureRecorder().getGraph()`. */
834
+ graph: TraceGraph;
588
835
  /** Currently active stage name (highlights in tree) */
589
836
  activeStage?: string | null;
590
837
  /** Set of completed stage names */
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,aAAa,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGvE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACtE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,YAAY,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AACrE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAGjG,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}