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.
- package/dist/adapters/fromRuntimeSnapshot.d.ts +33 -4
- package/dist/adapters/fromRuntimeSnapshot.d.ts.map +1 -1
- package/dist/adapters/fromRuntimeSnapshot.js +162 -33
- package/dist/adapters/fromRuntimeSnapshot.js.map +1 -1
- package/dist/components/ExplainableShell/ExplainableShell.d.ts +157 -14
- package/dist/components/ExplainableShell/ExplainableShell.d.ts.map +1 -1
- package/dist/components/ExplainableShell/ExplainableShell.js +676 -68
- package/dist/components/ExplainableShell/ExplainableShell.js.map +1 -1
- package/dist/components/ExplainableShell/index.d.ts +1 -1
- package/dist/components/ExplainableShell/index.d.ts.map +1 -1
- package/dist/components/FlowchartView/SubflowTree.d.ts +7 -14
- package/dist/components/FlowchartView/SubflowTree.d.ts.map +1 -1
- package/dist/components/FlowchartView/SubflowTree.js +56 -46
- package/dist/components/FlowchartView/SubflowTree.js.map +1 -1
- package/dist/components/FlowchartView/index.d.ts +32 -4
- package/dist/components/FlowchartView/index.d.ts.map +1 -1
- package/dist/components/FlowchartView/index.js +22 -2
- package/dist/components/FlowchartView/index.js.map +1 -1
- package/dist/components/FlowchartView/useSubflowNavigation.d.ts +41 -16
- package/dist/components/FlowchartView/useSubflowNavigation.d.ts.map +1 -1
- package/dist/components/FlowchartView/useSubflowNavigation.js +69 -50
- package/dist/components/FlowchartView/useSubflowNavigation.js.map +1 -1
- package/dist/components/GanttTimeline/GanttTimeline.d.ts.map +1 -1
- package/dist/components/GanttTimeline/GanttTimeline.js +5 -5
- package/dist/components/GanttTimeline/GanttTimeline.js.map +1 -1
- package/dist/components/MemoryInspector/MemoryInspector.d.ts.map +1 -1
- package/dist/components/MemoryInspector/MemoryInspector.js +36 -13
- package/dist/components/MemoryInspector/MemoryInspector.js.map +1 -1
- package/dist/components/NarrativeTrace/NarrativeTrace.d.ts.map +1 -1
- package/dist/components/NarrativeTrace/NarrativeTrace.js +24 -17
- package/dist/components/NarrativeTrace/NarrativeTrace.js.map +1 -1
- package/dist/components/ScopeDiff/ScopeDiff.js +3 -3
- package/dist/components/ScopeDiff/ScopeDiff.js.map +1 -1
- package/dist/components/StageNode/StageNode.d.ts +21 -0
- package/dist/components/StageNode/StageNode.d.ts.map +1 -1
- package/dist/components/StageNode/StageNode.js +189 -9
- package/dist/components/StageNode/StageNode.js.map +1 -1
- package/dist/components/TimeTravelControls/TimeTravelControls.d.ts.map +1 -1
- package/dist/components/TimeTravelControls/TimeTravelControls.js +19 -3
- package/dist/components/TimeTravelControls/TimeTravelControls.js.map +1 -1
- package/dist/components/TimeTravelDebugger/TimeTravelDebugger.d.ts +19 -8
- package/dist/components/TimeTravelDebugger/TimeTravelDebugger.d.ts.map +1 -1
- package/dist/components/TimeTravelDebugger/TimeTravelDebugger.js +23 -8
- package/dist/components/TimeTravelDebugger/TimeTravelDebugger.js.map +1 -1
- package/dist/flowchart.cjs +3485 -1340
- package/dist/flowchart.cjs.map +1 -1
- package/dist/flowchart.d.cts +1616 -177
- package/dist/flowchart.d.ts +1616 -177
- package/dist/flowchart.d.ts.map +1 -1
- package/dist/flowchart.js +3507 -1384
- package/dist/flowchart.js.map +1 -1
- package/dist/index.cjs +749 -557
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +276 -29
- package/dist/index.d.ts +276 -29
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +742 -547
- package/dist/index.js.map +1 -1
- package/dist/theme/ThemeProvider.d.ts +14 -0
- package/dist/theme/ThemeProvider.d.ts.map +1 -1
- package/dist/theme/ThemeProvider.js +15 -1
- package/dist/theme/ThemeProvider.js.map +1 -1
- package/dist/theme/index.d.ts +4 -2
- package/dist/theme/index.d.ts.map +1 -1
- package/dist/theme/index.js +3 -2
- package/dist/theme/index.js.map +1 -1
- package/dist/theme/presets.d.ts +3 -0
- package/dist/theme/presets.d.ts.map +1 -1
- package/dist/theme/presets.js +22 -0
- package/dist/theme/presets.js.map +1 -1
- package/dist/theme/tokens.d.ts +22 -1
- package/dist/theme/tokens.d.ts.map +1 -1
- package/dist/theme/tokens.js +23 -2
- package/dist/theme/tokens.js.map +1 -1
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/dist/types.d.ts +25 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +4 -4
- package/dist/components/FlowchartView/FlowchartView.d.ts +0 -20
- package/dist/components/FlowchartView/FlowchartView.d.ts.map +0 -1
- package/dist/components/FlowchartView/FlowchartView.js +0 -80
- package/dist/components/FlowchartView/FlowchartView.js.map +0 -1
- package/dist/components/FlowchartView/TracedFlowchartView.d.ts +0 -20
- package/dist/components/FlowchartView/TracedFlowchartView.d.ts.map +0 -1
- package/dist/components/FlowchartView/TracedFlowchartView.js +0 -101
- package/dist/components/FlowchartView/TracedFlowchartView.js.map +0 -1
- package/dist/components/FlowchartView/specToReactFlow.d.ts +0 -56
- package/dist/components/FlowchartView/specToReactFlow.d.ts.map +0 -1
- package/dist/components/FlowchartView/specToReactFlow.js +0 -202
- 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
|
-
*
|
|
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
|
|
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
|
|
432
|
-
*
|
|
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,
|
|
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 (
|
|
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,
|
|
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
|
-
/**
|
|
587
|
-
|
|
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 */
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|