footprint-explainable-ui 0.5.0 → 0.7.2
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/README.md +158 -401
- package/dist/flowchart.cjs +764 -531
- package/dist/flowchart.cjs.map +1 -1
- package/dist/flowchart.d.cts +68 -15
- package/dist/flowchart.d.ts +68 -15
- package/dist/flowchart.js +734 -502
- package/dist/flowchart.js.map +1 -1
- package/dist/index.cjs +1248 -485
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +171 -33
- package/dist/index.d.ts +171 -33
- package/dist/index.js +1225 -469
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -24,6 +24,14 @@ interface StageSnapshot {
|
|
|
24
24
|
/** Subflow execution result — present on stages that ran a subflow. */
|
|
25
25
|
subflowResult?: unknown;
|
|
26
26
|
}
|
|
27
|
+
/** Structured narrative entry — preserves type info for semantic rendering. */
|
|
28
|
+
interface NarrativeEntry$1 {
|
|
29
|
+
type: 'stage' | 'step' | 'condition' | 'fork' | 'subflow' | 'loop' | 'break' | 'error';
|
|
30
|
+
text: string;
|
|
31
|
+
depth: number;
|
|
32
|
+
stageName?: string;
|
|
33
|
+
stepNumber?: number;
|
|
34
|
+
}
|
|
27
35
|
/** Component size variants */
|
|
28
36
|
type Size = "compact" | "default" | "detailed";
|
|
29
37
|
/** Common props shared by all visualization components */
|
|
@@ -61,7 +69,28 @@ interface ThemeTokens {
|
|
|
61
69
|
}
|
|
62
70
|
/** Maps ThemeTokens to CSS custom property assignments. */
|
|
63
71
|
declare function tokensToCSSVars(tokens: ThemeTokens): Record<string, string>;
|
|
64
|
-
/**
|
|
72
|
+
/** Raw fallback values — used by tokensToCSSVars() and anywhere a real color is needed. */
|
|
73
|
+
declare const rawDefaults: {
|
|
74
|
+
readonly colors: {
|
|
75
|
+
readonly primary: "#6366f1";
|
|
76
|
+
readonly success: "#22c55e";
|
|
77
|
+
readonly error: "#ef4444";
|
|
78
|
+
readonly warning: "#f59e0b";
|
|
79
|
+
readonly bgPrimary: "#0f172a";
|
|
80
|
+
readonly bgSecondary: "#1e293b";
|
|
81
|
+
readonly bgTertiary: "#334155";
|
|
82
|
+
readonly textPrimary: "#f8fafc";
|
|
83
|
+
readonly textSecondary: "#94a3b8";
|
|
84
|
+
readonly textMuted: "#64748b";
|
|
85
|
+
readonly border: "#334155";
|
|
86
|
+
};
|
|
87
|
+
readonly radius: "8px";
|
|
88
|
+
readonly fontFamily: {
|
|
89
|
+
readonly sans: "Inter, system-ui, -apple-system, sans-serif";
|
|
90
|
+
readonly mono: "'JetBrains Mono', 'Fira Code', monospace";
|
|
91
|
+
};
|
|
92
|
+
};
|
|
93
|
+
/** Default dark theme values with CSS variable references (consumers can override via CSS). */
|
|
65
94
|
declare const defaultTokens: Required<{
|
|
66
95
|
[K in keyof ThemeTokens]-?: Required<ThemeTokens[K]>;
|
|
67
96
|
}>;
|
|
@@ -83,14 +112,49 @@ declare const coolDark: ThemeTokens;
|
|
|
83
112
|
declare const warmDark: ThemeTokens;
|
|
84
113
|
/** Warm light theme — cream/peach palette */
|
|
85
114
|
declare const warmLight: ThemeTokens;
|
|
115
|
+
/** Cool light theme — neutral grays, matches Tailwind zinc palette */
|
|
116
|
+
declare const coolLight: ThemeTokens;
|
|
86
117
|
/** All built-in theme presets */
|
|
87
118
|
declare const themePresets: {
|
|
88
119
|
readonly coolDark: ThemeTokens;
|
|
120
|
+
readonly coolLight: ThemeTokens;
|
|
89
121
|
readonly warmDark: ThemeTokens;
|
|
90
122
|
readonly warmLight: ThemeTokens;
|
|
91
123
|
};
|
|
92
124
|
type ThemePresetName = keyof typeof themePresets;
|
|
93
125
|
|
|
126
|
+
/**
|
|
127
|
+
* useDarkModeTokens — Auto-bridge between CSS class-based dark mode and FootprintTheme.
|
|
128
|
+
*
|
|
129
|
+
* Watches for a `.dark` class on <html> (Tailwind convention) and returns
|
|
130
|
+
* the appropriate ThemeTokens preset. Pairs with FootprintTheme:
|
|
131
|
+
*
|
|
132
|
+
* import { FootprintTheme, useDarkModeTokens } from 'footprint-explainable-ui';
|
|
133
|
+
*
|
|
134
|
+
* function MyApp() {
|
|
135
|
+
* const tokens = useDarkModeTokens();
|
|
136
|
+
* return (
|
|
137
|
+
* <FootprintTheme tokens={tokens}>
|
|
138
|
+
* <NarrativeTrace ... />
|
|
139
|
+
* </FootprintTheme>
|
|
140
|
+
* );
|
|
141
|
+
* }
|
|
142
|
+
*
|
|
143
|
+
* Consumers can override the light/dark presets:
|
|
144
|
+
*
|
|
145
|
+
* const tokens = useDarkModeTokens({ light: warmLight, dark: warmDark });
|
|
146
|
+
*/
|
|
147
|
+
|
|
148
|
+
interface DarkModeTokensOptions {
|
|
149
|
+
/** Tokens to use in light mode. Defaults to coolLight. */
|
|
150
|
+
light?: ThemeTokens;
|
|
151
|
+
/** Tokens to use in dark mode. Defaults to coolDark. */
|
|
152
|
+
dark?: ThemeTokens;
|
|
153
|
+
/** CSS selector to watch for dark mode. Defaults to checking .dark on documentElement. */
|
|
154
|
+
selector?: string;
|
|
155
|
+
}
|
|
156
|
+
declare function useDarkModeTokens(options?: DarkModeTokensOptions): ThemeTokens;
|
|
157
|
+
|
|
94
158
|
interface MemoryInspectorProps extends BaseComponentProps {
|
|
95
159
|
/** Single memory object or snapshots (will accumulate up to selectedIndex) */
|
|
96
160
|
data?: Record<string, unknown>;
|
|
@@ -229,45 +293,25 @@ interface TimeTravelControlsProps extends BaseComponentProps {
|
|
|
229
293
|
}
|
|
230
294
|
declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react_jsx_runtime.JSX.Element;
|
|
231
295
|
|
|
232
|
-
type ShellTab = "result" | "explainable" | "ai-compatible";
|
|
233
|
-
interface ExplainableShellProps extends BaseComponentProps {
|
|
234
|
-
/** Stage snapshots for time-travel visualization */
|
|
235
|
-
snapshots: StageSnapshot[];
|
|
236
|
-
/** Final pipeline result data */
|
|
237
|
-
resultData?: Record<string, unknown> | null;
|
|
238
|
-
/** Console log lines */
|
|
239
|
-
logs?: string[];
|
|
240
|
-
/** Combined narrative lines */
|
|
241
|
-
narrative?: string[];
|
|
242
|
-
/** Which tabs to show (default: all three) */
|
|
243
|
-
tabs?: ShellTab[];
|
|
244
|
-
/** Initially active tab */
|
|
245
|
-
defaultTab?: ShellTab;
|
|
246
|
-
/** Hide console in result tab */
|
|
247
|
-
hideConsole?: boolean;
|
|
248
|
-
/** Custom content to render in each tab slot */
|
|
249
|
-
renderFlowchart?: (props: {
|
|
250
|
-
snapshots: StageSnapshot[];
|
|
251
|
-
selectedIndex: number;
|
|
252
|
-
onNodeClick?: (index: number) => void;
|
|
253
|
-
}) => React.ReactNode;
|
|
254
|
-
}
|
|
255
|
-
declare function ExplainableShell({ snapshots, resultData, logs, narrative, tabs, defaultTab, hideConsole, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
|
|
256
|
-
|
|
257
296
|
/**
|
|
258
297
|
* Converts a SerializedPipelineStructure (from builder.toSpec()) into
|
|
259
298
|
* ReactFlow nodes and edges with auto-layout.
|
|
260
299
|
*
|
|
261
|
-
*
|
|
262
|
-
* 1.
|
|
263
|
-
* 2.
|
|
264
|
-
*
|
|
300
|
+
* Two-phase approach for performance:
|
|
301
|
+
* 1. `specToLayout(spec)` — tree walk + positioning (expensive, cached on spec)
|
|
302
|
+
* 2. `applyOverlay(layout, overlay)` — color nodes/edges (cheap, runs per slider tick)
|
|
303
|
+
*
|
|
304
|
+
* `specToReactFlow(spec, overlay)` combines both for convenience.
|
|
265
305
|
*/
|
|
266
306
|
|
|
267
307
|
interface SpecNode {
|
|
268
308
|
name: string;
|
|
269
309
|
id?: string;
|
|
270
310
|
type?: "stage" | "decider" | "fork" | "streaming";
|
|
311
|
+
/** Semantic icon hint — rendered by StageNode. Common values:
|
|
312
|
+
* "llm", "tool", "rag", "search", "parse", "start", "end", "loop",
|
|
313
|
+
* "agent", "swarm", "guard", "stream", "memory" */
|
|
314
|
+
icon?: string;
|
|
271
315
|
description?: string;
|
|
272
316
|
children?: SpecNode[];
|
|
273
317
|
next?: SpecNode;
|
|
@@ -279,8 +323,73 @@ interface SpecNode {
|
|
|
279
323
|
subflowId?: string;
|
|
280
324
|
subflowName?: string;
|
|
281
325
|
subflowStructure?: SpecNode;
|
|
326
|
+
/** True when this subflow uses lazy resolution (deferred until execution). */
|
|
327
|
+
isLazy?: boolean;
|
|
282
328
|
}
|
|
283
329
|
|
|
330
|
+
type ShellTab = "result" | "explainable" | "ai-compatible";
|
|
331
|
+
interface PanelLabels {
|
|
332
|
+
/** Left panel pill label (subflow tree). Default: "Topology" */
|
|
333
|
+
topology?: string;
|
|
334
|
+
/** Right panel pill label (memory/narrative). Default: "Details" */
|
|
335
|
+
details?: string;
|
|
336
|
+
/** Bottom panel pill label (timeline). Default: "Timeline" */
|
|
337
|
+
timeline?: string;
|
|
338
|
+
}
|
|
339
|
+
/** Which panels start expanded. Default: `{ details: true }` (flowchart + memory). */
|
|
340
|
+
interface DefaultExpanded {
|
|
341
|
+
topology?: boolean;
|
|
342
|
+
details?: boolean;
|
|
343
|
+
timeline?: boolean;
|
|
344
|
+
}
|
|
345
|
+
interface ExplainableShellProps extends BaseComponentProps {
|
|
346
|
+
snapshots: StageSnapshot[];
|
|
347
|
+
spec?: SpecNode | null;
|
|
348
|
+
title?: string;
|
|
349
|
+
resultData?: Record<string, unknown> | null;
|
|
350
|
+
logs?: string[];
|
|
351
|
+
narrative?: string[];
|
|
352
|
+
narrativeEntries?: NarrativeEntry$1[];
|
|
353
|
+
tabs?: ShellTab[];
|
|
354
|
+
defaultTab?: ShellTab;
|
|
355
|
+
hideConsole?: boolean;
|
|
356
|
+
/** Customize the labels on collapsible panel pills */
|
|
357
|
+
panelLabels?: PanelLabels;
|
|
358
|
+
/** Which panels start expanded. Default: `{ details: true }` */
|
|
359
|
+
defaultExpanded?: DefaultExpanded;
|
|
360
|
+
renderFlowchart?: (props: {
|
|
361
|
+
spec: SpecNode;
|
|
362
|
+
snapshots: StageSnapshot[];
|
|
363
|
+
selectedIndex: number;
|
|
364
|
+
onNodeClick?: (indexOrId: number | string) => void;
|
|
365
|
+
}) => React.ReactNode;
|
|
366
|
+
}
|
|
367
|
+
declare function ExplainableShell({ snapshots, spec, title, resultData, logs, narrative, narrativeEntries, tabs, defaultTab, hideConsole, panelLabels, defaultExpanded, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
|
|
368
|
+
|
|
369
|
+
interface MemoryPanelProps extends BaseComponentProps {
|
|
370
|
+
snapshots: StageSnapshot[];
|
|
371
|
+
selectedIndex: number;
|
|
372
|
+
}
|
|
373
|
+
declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, className, style, }: MemoryPanelProps): react_jsx_runtime.JSX.Element;
|
|
374
|
+
|
|
375
|
+
interface NarrativePanelProps extends BaseComponentProps {
|
|
376
|
+
snapshots: StageSnapshot[];
|
|
377
|
+
selectedIndex: number;
|
|
378
|
+
/** Structured narrative entries (preferred — richer rendering) */
|
|
379
|
+
narrativeEntries?: NarrativeEntry$1[];
|
|
380
|
+
/** Plain narrative lines (fallback) */
|
|
381
|
+
narrative?: string[];
|
|
382
|
+
}
|
|
383
|
+
declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, narrative: narrativeProp, size, unstyled, className, style, }: NarrativePanelProps): react_jsx_runtime.JSX.Element;
|
|
384
|
+
|
|
385
|
+
interface StoryNarrativeProps extends BaseComponentProps {
|
|
386
|
+
/** Structured narrative entries from CombinedNarrativeRecorder */
|
|
387
|
+
entries: NarrativeEntry$1[];
|
|
388
|
+
/** Number of stages to reveal (maps to snapshotIdx + 1) */
|
|
389
|
+
stageCount: number;
|
|
390
|
+
}
|
|
391
|
+
declare function StoryNarrative({ entries, stageCount, size, unstyled, className, style: outerStyle, }: StoryNarrativeProps): react_jsx_runtime.JSX.Element;
|
|
392
|
+
|
|
284
393
|
interface SubflowTreeEntry {
|
|
285
394
|
/** Node name / identifier */
|
|
286
395
|
name: string;
|
|
@@ -333,18 +442,47 @@ interface RuntimeSnapshot {
|
|
|
333
442
|
/** Per-subflow execution results (keyed by subflowId). */
|
|
334
443
|
subflowResults?: Record<string, unknown>;
|
|
335
444
|
}
|
|
445
|
+
/**
|
|
446
|
+
* Matches CombinedNarrativeEntry from footprintjs (defined here to avoid hard dep).
|
|
447
|
+
* Pass from FlowChartExecutor.getNarrativeEntries().
|
|
448
|
+
*/
|
|
449
|
+
interface NarrativeEntry {
|
|
450
|
+
type: 'stage' | 'step' | 'condition' | 'fork' | 'subflow' | 'loop' | 'break' | 'error';
|
|
451
|
+
text: string;
|
|
452
|
+
depth: number;
|
|
453
|
+
stageName?: string;
|
|
454
|
+
stepNumber?: number;
|
|
455
|
+
}
|
|
336
456
|
/**
|
|
337
457
|
* Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
|
|
338
458
|
* suitable for visualization components.
|
|
339
459
|
*
|
|
460
|
+
* The `narrativeEntries` parameter (from `executor.getNarrativeEntries()`)
|
|
461
|
+
* distributes the library's rich combined narrative per-stage.
|
|
462
|
+
* When narrative is not enabled, stages get "Narrative not available" —
|
|
463
|
+
* this adapter reflects what the library produces, nothing more.
|
|
464
|
+
*
|
|
340
465
|
* Usage:
|
|
341
466
|
* ```ts
|
|
342
467
|
* const executor = new FlowChartExecutor(chart);
|
|
343
468
|
* await executor.run();
|
|
344
|
-
* const snapshots = toVisualizationSnapshots(
|
|
469
|
+
* const snapshots = toVisualizationSnapshots(
|
|
470
|
+
* executor.getSnapshot(),
|
|
471
|
+
* executor.getNarrativeEntries(),
|
|
472
|
+
* );
|
|
345
473
|
* ```
|
|
346
474
|
*/
|
|
347
|
-
declare function toVisualizationSnapshots(runtime: RuntimeSnapshot): StageSnapshot[];
|
|
475
|
+
declare function toVisualizationSnapshots(runtime: RuntimeSnapshot, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
|
|
476
|
+
/**
|
|
477
|
+
* Converts a footprintjs SubflowResult (stored on StageSnapshot.subflowResult)
|
|
478
|
+
* into visualization snapshots for drill-down views.
|
|
479
|
+
*
|
|
480
|
+
* SubflowResult shape (from footprintjs):
|
|
481
|
+
* { subflowId, subflowName, treeContext: { globalContext, stageContexts, history }, parentStageId }
|
|
482
|
+
*
|
|
483
|
+
* Returns empty array if the input is not a valid SubflowResult.
|
|
484
|
+
*/
|
|
485
|
+
declare function subflowResultToSnapshots(subflowResult: unknown, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
|
|
348
486
|
/**
|
|
349
487
|
* Creates StageSnapshots from simple arrays (when you don't have a RuntimeSnapshot).
|
|
350
488
|
* Useful for testing or custom data sources.
|
|
@@ -359,4 +497,4 @@ declare function createSnapshots(stages: Array<{
|
|
|
359
497
|
subflowId?: string;
|
|
360
498
|
}>): StageSnapshot[];
|
|
361
499
|
|
|
362
|
-
export { type BaseComponentProps, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, NarrativeLog, type NarrativeLogProps, NarrativeTrace, type NarrativeTraceProps, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageDetailMode, StageDetailPanel, type StageDetailPanelProps, type StageSnapshot, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useFootprintTheme, warmDark, warmLight };
|
|
500
|
+
export { type NarrativeEntry as AdapterNarrativeEntry, type BaseComponentProps, type DarkModeTokensOptions, type DefaultExpanded, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, MemoryPanel, type MemoryPanelProps, type NarrativeEntry$1 as NarrativeEntry, NarrativeLog, type NarrativeLogProps, NarrativePanel, type NarrativePanelProps, NarrativeTrace, type NarrativeTraceProps, type PanelLabels, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageDetailMode, StageDetailPanel, type StageDetailPanelProps, type StageSnapshot, StoryNarrative, type StoryNarrativeProps, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, coolLight, createSnapshots, defaultTokens, rawDefaults, subflowResultToSnapshots, themePresets, toVisualizationSnapshots, tokensToCSSVars, useDarkModeTokens, useFootprintTheme, warmDark, warmLight };
|
package/dist/index.d.ts
CHANGED
|
@@ -24,6 +24,14 @@ interface StageSnapshot {
|
|
|
24
24
|
/** Subflow execution result — present on stages that ran a subflow. */
|
|
25
25
|
subflowResult?: unknown;
|
|
26
26
|
}
|
|
27
|
+
/** Structured narrative entry — preserves type info for semantic rendering. */
|
|
28
|
+
interface NarrativeEntry$1 {
|
|
29
|
+
type: 'stage' | 'step' | 'condition' | 'fork' | 'subflow' | 'loop' | 'break' | 'error';
|
|
30
|
+
text: string;
|
|
31
|
+
depth: number;
|
|
32
|
+
stageName?: string;
|
|
33
|
+
stepNumber?: number;
|
|
34
|
+
}
|
|
27
35
|
/** Component size variants */
|
|
28
36
|
type Size = "compact" | "default" | "detailed";
|
|
29
37
|
/** Common props shared by all visualization components */
|
|
@@ -61,7 +69,28 @@ interface ThemeTokens {
|
|
|
61
69
|
}
|
|
62
70
|
/** Maps ThemeTokens to CSS custom property assignments. */
|
|
63
71
|
declare function tokensToCSSVars(tokens: ThemeTokens): Record<string, string>;
|
|
64
|
-
/**
|
|
72
|
+
/** Raw fallback values — used by tokensToCSSVars() and anywhere a real color is needed. */
|
|
73
|
+
declare const rawDefaults: {
|
|
74
|
+
readonly colors: {
|
|
75
|
+
readonly primary: "#6366f1";
|
|
76
|
+
readonly success: "#22c55e";
|
|
77
|
+
readonly error: "#ef4444";
|
|
78
|
+
readonly warning: "#f59e0b";
|
|
79
|
+
readonly bgPrimary: "#0f172a";
|
|
80
|
+
readonly bgSecondary: "#1e293b";
|
|
81
|
+
readonly bgTertiary: "#334155";
|
|
82
|
+
readonly textPrimary: "#f8fafc";
|
|
83
|
+
readonly textSecondary: "#94a3b8";
|
|
84
|
+
readonly textMuted: "#64748b";
|
|
85
|
+
readonly border: "#334155";
|
|
86
|
+
};
|
|
87
|
+
readonly radius: "8px";
|
|
88
|
+
readonly fontFamily: {
|
|
89
|
+
readonly sans: "Inter, system-ui, -apple-system, sans-serif";
|
|
90
|
+
readonly mono: "'JetBrains Mono', 'Fira Code', monospace";
|
|
91
|
+
};
|
|
92
|
+
};
|
|
93
|
+
/** Default dark theme values with CSS variable references (consumers can override via CSS). */
|
|
65
94
|
declare const defaultTokens: Required<{
|
|
66
95
|
[K in keyof ThemeTokens]-?: Required<ThemeTokens[K]>;
|
|
67
96
|
}>;
|
|
@@ -83,14 +112,49 @@ declare const coolDark: ThemeTokens;
|
|
|
83
112
|
declare const warmDark: ThemeTokens;
|
|
84
113
|
/** Warm light theme — cream/peach palette */
|
|
85
114
|
declare const warmLight: ThemeTokens;
|
|
115
|
+
/** Cool light theme — neutral grays, matches Tailwind zinc palette */
|
|
116
|
+
declare const coolLight: ThemeTokens;
|
|
86
117
|
/** All built-in theme presets */
|
|
87
118
|
declare const themePresets: {
|
|
88
119
|
readonly coolDark: ThemeTokens;
|
|
120
|
+
readonly coolLight: ThemeTokens;
|
|
89
121
|
readonly warmDark: ThemeTokens;
|
|
90
122
|
readonly warmLight: ThemeTokens;
|
|
91
123
|
};
|
|
92
124
|
type ThemePresetName = keyof typeof themePresets;
|
|
93
125
|
|
|
126
|
+
/**
|
|
127
|
+
* useDarkModeTokens — Auto-bridge between CSS class-based dark mode and FootprintTheme.
|
|
128
|
+
*
|
|
129
|
+
* Watches for a `.dark` class on <html> (Tailwind convention) and returns
|
|
130
|
+
* the appropriate ThemeTokens preset. Pairs with FootprintTheme:
|
|
131
|
+
*
|
|
132
|
+
* import { FootprintTheme, useDarkModeTokens } from 'footprint-explainable-ui';
|
|
133
|
+
*
|
|
134
|
+
* function MyApp() {
|
|
135
|
+
* const tokens = useDarkModeTokens();
|
|
136
|
+
* return (
|
|
137
|
+
* <FootprintTheme tokens={tokens}>
|
|
138
|
+
* <NarrativeTrace ... />
|
|
139
|
+
* </FootprintTheme>
|
|
140
|
+
* );
|
|
141
|
+
* }
|
|
142
|
+
*
|
|
143
|
+
* Consumers can override the light/dark presets:
|
|
144
|
+
*
|
|
145
|
+
* const tokens = useDarkModeTokens({ light: warmLight, dark: warmDark });
|
|
146
|
+
*/
|
|
147
|
+
|
|
148
|
+
interface DarkModeTokensOptions {
|
|
149
|
+
/** Tokens to use in light mode. Defaults to coolLight. */
|
|
150
|
+
light?: ThemeTokens;
|
|
151
|
+
/** Tokens to use in dark mode. Defaults to coolDark. */
|
|
152
|
+
dark?: ThemeTokens;
|
|
153
|
+
/** CSS selector to watch for dark mode. Defaults to checking .dark on documentElement. */
|
|
154
|
+
selector?: string;
|
|
155
|
+
}
|
|
156
|
+
declare function useDarkModeTokens(options?: DarkModeTokensOptions): ThemeTokens;
|
|
157
|
+
|
|
94
158
|
interface MemoryInspectorProps extends BaseComponentProps {
|
|
95
159
|
/** Single memory object or snapshots (will accumulate up to selectedIndex) */
|
|
96
160
|
data?: Record<string, unknown>;
|
|
@@ -229,45 +293,25 @@ interface TimeTravelControlsProps extends BaseComponentProps {
|
|
|
229
293
|
}
|
|
230
294
|
declare function TimeTravelControls({ snapshots, selectedIndex, onIndexChange, autoPlayable, size, unstyled, className, style, }: TimeTravelControlsProps): react_jsx_runtime.JSX.Element;
|
|
231
295
|
|
|
232
|
-
type ShellTab = "result" | "explainable" | "ai-compatible";
|
|
233
|
-
interface ExplainableShellProps extends BaseComponentProps {
|
|
234
|
-
/** Stage snapshots for time-travel visualization */
|
|
235
|
-
snapshots: StageSnapshot[];
|
|
236
|
-
/** Final pipeline result data */
|
|
237
|
-
resultData?: Record<string, unknown> | null;
|
|
238
|
-
/** Console log lines */
|
|
239
|
-
logs?: string[];
|
|
240
|
-
/** Combined narrative lines */
|
|
241
|
-
narrative?: string[];
|
|
242
|
-
/** Which tabs to show (default: all three) */
|
|
243
|
-
tabs?: ShellTab[];
|
|
244
|
-
/** Initially active tab */
|
|
245
|
-
defaultTab?: ShellTab;
|
|
246
|
-
/** Hide console in result tab */
|
|
247
|
-
hideConsole?: boolean;
|
|
248
|
-
/** Custom content to render in each tab slot */
|
|
249
|
-
renderFlowchart?: (props: {
|
|
250
|
-
snapshots: StageSnapshot[];
|
|
251
|
-
selectedIndex: number;
|
|
252
|
-
onNodeClick?: (index: number) => void;
|
|
253
|
-
}) => React.ReactNode;
|
|
254
|
-
}
|
|
255
|
-
declare function ExplainableShell({ snapshots, resultData, logs, narrative, tabs, defaultTab, hideConsole, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
|
|
256
|
-
|
|
257
296
|
/**
|
|
258
297
|
* Converts a SerializedPipelineStructure (from builder.toSpec()) into
|
|
259
298
|
* ReactFlow nodes and edges with auto-layout.
|
|
260
299
|
*
|
|
261
|
-
*
|
|
262
|
-
* 1.
|
|
263
|
-
* 2.
|
|
264
|
-
*
|
|
300
|
+
* Two-phase approach for performance:
|
|
301
|
+
* 1. `specToLayout(spec)` — tree walk + positioning (expensive, cached on spec)
|
|
302
|
+
* 2. `applyOverlay(layout, overlay)` — color nodes/edges (cheap, runs per slider tick)
|
|
303
|
+
*
|
|
304
|
+
* `specToReactFlow(spec, overlay)` combines both for convenience.
|
|
265
305
|
*/
|
|
266
306
|
|
|
267
307
|
interface SpecNode {
|
|
268
308
|
name: string;
|
|
269
309
|
id?: string;
|
|
270
310
|
type?: "stage" | "decider" | "fork" | "streaming";
|
|
311
|
+
/** Semantic icon hint — rendered by StageNode. Common values:
|
|
312
|
+
* "llm", "tool", "rag", "search", "parse", "start", "end", "loop",
|
|
313
|
+
* "agent", "swarm", "guard", "stream", "memory" */
|
|
314
|
+
icon?: string;
|
|
271
315
|
description?: string;
|
|
272
316
|
children?: SpecNode[];
|
|
273
317
|
next?: SpecNode;
|
|
@@ -279,8 +323,73 @@ interface SpecNode {
|
|
|
279
323
|
subflowId?: string;
|
|
280
324
|
subflowName?: string;
|
|
281
325
|
subflowStructure?: SpecNode;
|
|
326
|
+
/** True when this subflow uses lazy resolution (deferred until execution). */
|
|
327
|
+
isLazy?: boolean;
|
|
282
328
|
}
|
|
283
329
|
|
|
330
|
+
type ShellTab = "result" | "explainable" | "ai-compatible";
|
|
331
|
+
interface PanelLabels {
|
|
332
|
+
/** Left panel pill label (subflow tree). Default: "Topology" */
|
|
333
|
+
topology?: string;
|
|
334
|
+
/** Right panel pill label (memory/narrative). Default: "Details" */
|
|
335
|
+
details?: string;
|
|
336
|
+
/** Bottom panel pill label (timeline). Default: "Timeline" */
|
|
337
|
+
timeline?: string;
|
|
338
|
+
}
|
|
339
|
+
/** Which panels start expanded. Default: `{ details: true }` (flowchart + memory). */
|
|
340
|
+
interface DefaultExpanded {
|
|
341
|
+
topology?: boolean;
|
|
342
|
+
details?: boolean;
|
|
343
|
+
timeline?: boolean;
|
|
344
|
+
}
|
|
345
|
+
interface ExplainableShellProps extends BaseComponentProps {
|
|
346
|
+
snapshots: StageSnapshot[];
|
|
347
|
+
spec?: SpecNode | null;
|
|
348
|
+
title?: string;
|
|
349
|
+
resultData?: Record<string, unknown> | null;
|
|
350
|
+
logs?: string[];
|
|
351
|
+
narrative?: string[];
|
|
352
|
+
narrativeEntries?: NarrativeEntry$1[];
|
|
353
|
+
tabs?: ShellTab[];
|
|
354
|
+
defaultTab?: ShellTab;
|
|
355
|
+
hideConsole?: boolean;
|
|
356
|
+
/** Customize the labels on collapsible panel pills */
|
|
357
|
+
panelLabels?: PanelLabels;
|
|
358
|
+
/** Which panels start expanded. Default: `{ details: true }` */
|
|
359
|
+
defaultExpanded?: DefaultExpanded;
|
|
360
|
+
renderFlowchart?: (props: {
|
|
361
|
+
spec: SpecNode;
|
|
362
|
+
snapshots: StageSnapshot[];
|
|
363
|
+
selectedIndex: number;
|
|
364
|
+
onNodeClick?: (indexOrId: number | string) => void;
|
|
365
|
+
}) => React.ReactNode;
|
|
366
|
+
}
|
|
367
|
+
declare function ExplainableShell({ snapshots, spec, title, resultData, logs, narrative, narrativeEntries, tabs, defaultTab, hideConsole, panelLabels, defaultExpanded, renderFlowchart, size, unstyled, className, style, }: ExplainableShellProps): react_jsx_runtime.JSX.Element;
|
|
368
|
+
|
|
369
|
+
interface MemoryPanelProps extends BaseComponentProps {
|
|
370
|
+
snapshots: StageSnapshot[];
|
|
371
|
+
selectedIndex: number;
|
|
372
|
+
}
|
|
373
|
+
declare function MemoryPanel({ snapshots, selectedIndex, size, unstyled, className, style, }: MemoryPanelProps): react_jsx_runtime.JSX.Element;
|
|
374
|
+
|
|
375
|
+
interface NarrativePanelProps extends BaseComponentProps {
|
|
376
|
+
snapshots: StageSnapshot[];
|
|
377
|
+
selectedIndex: number;
|
|
378
|
+
/** Structured narrative entries (preferred — richer rendering) */
|
|
379
|
+
narrativeEntries?: NarrativeEntry$1[];
|
|
380
|
+
/** Plain narrative lines (fallback) */
|
|
381
|
+
narrative?: string[];
|
|
382
|
+
}
|
|
383
|
+
declare function NarrativePanel({ snapshots, selectedIndex, narrativeEntries, narrative: narrativeProp, size, unstyled, className, style, }: NarrativePanelProps): react_jsx_runtime.JSX.Element;
|
|
384
|
+
|
|
385
|
+
interface StoryNarrativeProps extends BaseComponentProps {
|
|
386
|
+
/** Structured narrative entries from CombinedNarrativeRecorder */
|
|
387
|
+
entries: NarrativeEntry$1[];
|
|
388
|
+
/** Number of stages to reveal (maps to snapshotIdx + 1) */
|
|
389
|
+
stageCount: number;
|
|
390
|
+
}
|
|
391
|
+
declare function StoryNarrative({ entries, stageCount, size, unstyled, className, style: outerStyle, }: StoryNarrativeProps): react_jsx_runtime.JSX.Element;
|
|
392
|
+
|
|
284
393
|
interface SubflowTreeEntry {
|
|
285
394
|
/** Node name / identifier */
|
|
286
395
|
name: string;
|
|
@@ -333,18 +442,47 @@ interface RuntimeSnapshot {
|
|
|
333
442
|
/** Per-subflow execution results (keyed by subflowId). */
|
|
334
443
|
subflowResults?: Record<string, unknown>;
|
|
335
444
|
}
|
|
445
|
+
/**
|
|
446
|
+
* Matches CombinedNarrativeEntry from footprintjs (defined here to avoid hard dep).
|
|
447
|
+
* Pass from FlowChartExecutor.getNarrativeEntries().
|
|
448
|
+
*/
|
|
449
|
+
interface NarrativeEntry {
|
|
450
|
+
type: 'stage' | 'step' | 'condition' | 'fork' | 'subflow' | 'loop' | 'break' | 'error';
|
|
451
|
+
text: string;
|
|
452
|
+
depth: number;
|
|
453
|
+
stageName?: string;
|
|
454
|
+
stepNumber?: number;
|
|
455
|
+
}
|
|
336
456
|
/**
|
|
337
457
|
* Converts a FootPrint RuntimeSnapshot into a flat array of StageSnapshots
|
|
338
458
|
* suitable for visualization components.
|
|
339
459
|
*
|
|
460
|
+
* The `narrativeEntries` parameter (from `executor.getNarrativeEntries()`)
|
|
461
|
+
* distributes the library's rich combined narrative per-stage.
|
|
462
|
+
* When narrative is not enabled, stages get "Narrative not available" —
|
|
463
|
+
* this adapter reflects what the library produces, nothing more.
|
|
464
|
+
*
|
|
340
465
|
* Usage:
|
|
341
466
|
* ```ts
|
|
342
467
|
* const executor = new FlowChartExecutor(chart);
|
|
343
468
|
* await executor.run();
|
|
344
|
-
* const snapshots = toVisualizationSnapshots(
|
|
469
|
+
* const snapshots = toVisualizationSnapshots(
|
|
470
|
+
* executor.getSnapshot(),
|
|
471
|
+
* executor.getNarrativeEntries(),
|
|
472
|
+
* );
|
|
345
473
|
* ```
|
|
346
474
|
*/
|
|
347
|
-
declare function toVisualizationSnapshots(runtime: RuntimeSnapshot): StageSnapshot[];
|
|
475
|
+
declare function toVisualizationSnapshots(runtime: RuntimeSnapshot, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
|
|
476
|
+
/**
|
|
477
|
+
* Converts a footprintjs SubflowResult (stored on StageSnapshot.subflowResult)
|
|
478
|
+
* into visualization snapshots for drill-down views.
|
|
479
|
+
*
|
|
480
|
+
* SubflowResult shape (from footprintjs):
|
|
481
|
+
* { subflowId, subflowName, treeContext: { globalContext, stageContexts, history }, parentStageId }
|
|
482
|
+
*
|
|
483
|
+
* Returns empty array if the input is not a valid SubflowResult.
|
|
484
|
+
*/
|
|
485
|
+
declare function subflowResultToSnapshots(subflowResult: unknown, narrativeEntries?: NarrativeEntry[]): StageSnapshot[];
|
|
348
486
|
/**
|
|
349
487
|
* Creates StageSnapshots from simple arrays (when you don't have a RuntimeSnapshot).
|
|
350
488
|
* Useful for testing or custom data sources.
|
|
@@ -359,4 +497,4 @@ declare function createSnapshots(stages: Array<{
|
|
|
359
497
|
subflowId?: string;
|
|
360
498
|
}>): StageSnapshot[];
|
|
361
499
|
|
|
362
|
-
export { type BaseComponentProps, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, NarrativeLog, type NarrativeLogProps, NarrativeTrace, type NarrativeTraceProps, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageDetailMode, StageDetailPanel, type StageDetailPanelProps, type StageSnapshot, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, createSnapshots, defaultTokens, themePresets, toVisualizationSnapshots, tokensToCSSVars, useFootprintTheme, warmDark, warmLight };
|
|
500
|
+
export { type NarrativeEntry as AdapterNarrativeEntry, type BaseComponentProps, type DarkModeTokensOptions, type DefaultExpanded, type DiffEntry, ExplainableShell, type ExplainableShellProps, FootprintTheme, GanttTimeline, type GanttTimelineProps, type MemoryChange, MemoryInspector, type MemoryInspectorProps, MemoryPanel, type MemoryPanelProps, type NarrativeEntry$1 as NarrativeEntry, NarrativeLog, type NarrativeLogProps, NarrativePanel, type NarrativePanelProps, NarrativeTrace, type NarrativeTraceProps, type PanelLabels, ResultPanel, type ResultPanelProps, ScopeDiff, type ScopeDiffProps, type ShellTab, type Size, SnapshotPanel, type SnapshotPanelProps, type StageDetailMode, StageDetailPanel, type StageDetailPanelProps, type StageSnapshot, StoryNarrative, type StoryNarrativeProps, SubflowTree, type SubflowTreeEntry, type SubflowTreeProps, type ThemePresetName, type ThemeTokens, TimeTravelControls, type TimeTravelControlsProps, coolDark, coolLight, createSnapshots, defaultTokens, rawDefaults, subflowResultToSnapshots, themePresets, toVisualizationSnapshots, tokensToCSSVars, useDarkModeTokens, useFootprintTheme, warmDark, warmLight };
|