@jagreehal/workflow 1.6.0 → 1.7.0

package/dist/visualize.d.ts

@@ -145,6 +145,8 @@ interface WorkflowIR {
         /** When the IR was last updated */
         lastUpdatedAt: number;
     };
+    /** Hook executions (if any hooks are configured) */
+    hooks?: WorkflowHooks;
 }
 
 /**
@@ -326,6 +328,200 @@ declare function isDecisionNode(node: FlowNode): node is DecisionNode;
  * Check if a node has children.
  */
 declare function hasChildren(node: FlowNode): node is SequenceNode | ParallelNode | RaceNode | DecisionNode;
+/**
+ * Snapshot of an active step's state at a point in time.
+ */
+interface ActiveStepSnapshot {
+    id: string;
+    name?: string;
+    key?: string;
+    startTs: number;
+    retryCount: number;
+    timedOut: boolean;
+    timeoutMs?: number;
+}
+/**
+ * A snapshot of the complete IR state at a specific point in time.
+ * Used for time-travel debugging - each event creates a snapshot.
+ */
+interface IRSnapshot {
+    /** Unique identifier for this snapshot */
+    id: string;
+    /** Index in the event sequence (0-based) */
+    eventIndex: number;
+    /** The event that triggered this snapshot */
+    event: unknown;
+    /** Complete IR state at this moment */
+    ir: WorkflowIR;
+    /** Timestamp when snapshot was taken */
+    timestamp: number;
+    /** Active step states at this moment (for debugging) */
+    activeSteps: Map<string, ActiveStepSnapshot>;
+}
+/**
+ * State of the time-travel controller.
+ */
+interface TimeTravelState {
+    /** All recorded snapshots */
+    snapshots: IRSnapshot[];
+    /** Current snapshot index (for playback position) */
+    currentIndex: number;
+    /** Whether playback is active */
+    isPlaying: boolean;
+    /** Playback speed multiplier (1.0 = realtime, 2.0 = 2x speed) */
+    playbackSpeed: number;
+    /** Whether recording is active */
+    isRecording: boolean;
+}
+/**
+ * Performance metrics for a single node across multiple runs.
+ */
+interface NodePerformance {
+    /** Node identifier (name or step ID) */
+    nodeId: string;
+    /** Average duration across all samples */
+    avgDurationMs: number;
+    /** Minimum duration observed */
+    minDurationMs: number;
+    /** Maximum duration observed */
+    maxDurationMs: number;
+    /** Standard deviation of durations */
+    stdDevMs: number;
+    /** Number of timing samples collected */
+    samples: number;
+    /** Retry frequency (0-1, where 1 = always retries) */
+    retryRate: number;
+    /** Timeout frequency (0-1) */
+    timeoutRate: number;
+    /** Error rate (0-1) */
+    errorRate: number;
+    /** Percentile data for distribution analysis */
+    percentiles: {
+        p50: number;
+        p90: number;
+        p95: number;
+        p99: number;
+    };
+}
+/**
+ * Heatmap data for visualizing performance across nodes.
+ */
+interface HeatmapData {
+    /** Map of node ID to heat level (0-1, where 1 is hottest/slowest) */
+    heat: Map<string, number>;
+    /** The metric used for heat calculation */
+    metric: "duration" | "retryRate" | "errorRate";
+    /** Statistics used to compute heat values */
+    stats: {
+        /** Minimum value in the dataset */
+        min: number;
+        /** Maximum value in the dataset */
+        max: number;
+        /** Mean value */
+        mean: number;
+        /** Threshold above which a node is considered "hot" */
+        threshold: number;
+    };
+}
+/**
+ * Heat level for visual styling.
+ */
+type HeatLevel = "cold" | "cool" | "neutral" | "warm" | "hot" | "critical";
+/**
+ * Theme for the HTML visualizer.
+ */
+type HTMLTheme = "light" | "dark" | "auto";
+/**
+ * Layout direction for the workflow diagram.
+ */
+type LayoutDirection = "TB" | "LR" | "BT" | "RL";
+/**
+ * Options for the HTML renderer.
+ */
+interface HTMLRenderOptions extends RenderOptions {
+    /** Enable interactive features (click to inspect, zoom/pan) */
+    interactive: boolean;
+    /** Include time-travel controls */
+    timeTravel: boolean;
+    /** Include performance heatmap overlay */
+    heatmap: boolean;
+    /** Animation duration for transitions (ms) */
+    animationDuration: number;
+    /** Color theme */
+    theme: HTMLTheme;
+    /** Diagram layout direction */
+    layout: LayoutDirection;
+    /** Heatmap data (if heatmap is enabled) */
+    heatmapData?: HeatmapData;
+    /** WebSocket URL for live updates (if streaming) */
+    wsUrl?: string;
+}
+/**
+ * Message sent from the web visualizer to the dev server.
+ */
+interface WebVisualizerMessage {
+    type: "time_travel_seek" | "time_travel_play" | "time_travel_pause" | "time_travel_step_forward" | "time_travel_step_backward" | "request_snapshots" | "toggle_heatmap" | "set_heatmap_metric";
+    payload?: unknown;
+}
+/**
+ * Message sent from the dev server to the web visualizer.
+ */
+interface ServerMessage {
+    type: "ir_update" | "snapshot" | "snapshots_list" | "performance_data" | "workflow_complete" | "time_travel_state";
+    payload: unknown;
+}
+/**
+ * Extended render options for the enhanced ASCII renderer.
+ */
+interface EnhancedRenderOptions extends RenderOptions {
+    /** Show performance heatmap coloring */
+    showHeatmap?: boolean;
+    /** Heatmap data for coloring nodes */
+    heatmapData?: HeatmapData;
+    /** Show timing sparklines (requires historical data) */
+    showSparklines?: boolean;
+    /** Historical timing data for sparklines: nodeId → array of durations */
+    timingHistory?: Map<string, number[]>;
+}
+/**
+ * State of a hook execution.
+ */
+type HookState = "pending" | "running" | "success" | "error";
+/**
+ * Execution record for a workflow hook.
+ */
+interface HookExecution {
+    /** Hook type identifier */
+    type: "shouldRun" | "onBeforeStart" | "onAfterStep";
+    /** Execution state */
+    state: HookState;
+    /** Timestamp when hook started */
+    ts: number;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Error if hook failed */
+    error?: unknown;
+    /** Additional context (e.g., stepKey for onAfterStep) */
+    context?: {
+        /** Step key for onAfterStep hooks */
+        stepKey?: string;
+        /** Result of shouldRun hook */
+        result?: boolean;
+        /** Whether workflow was skipped due to shouldRun returning false */
+        skipped?: boolean;
+    };
+}
+/**
+ * Hook execution summary for the workflow.
+ */
+interface WorkflowHooks {
+    /** shouldRun hook execution (if configured) */
+    shouldRun?: HookExecution;
+    /** onBeforeStart hook execution (if configured) */
+    onBeforeStart?: HookExecution;
+    /** onAfterStep hook executions (keyed by stepKey) */
+    onAfterStep: Map<string, HookExecution>;
+}
 
 /**
  * Parallel Detection - Heuristic detection of parallel execution from timing.
@@ -394,6 +590,18 @@ interface IRBuilderOptions {
      * Options for parallel detection.
      */
     parallelDetection?: ParallelDetectorOptions;
+    /**
+     * Enable snapshot recording for time-travel debugging.
+     * When true, the builder captures IR state after each event.
+     * Default: false
+     */
+    enableSnapshots?: boolean;
+    /**
+     * Maximum number of snapshots to keep (ring buffer behavior).
+     * When exceeded, oldest snapshots are discarded.
+     * Default: 1000
+     */
+    maxSnapshots?: number;
 }
 /**
  * Creates an IR builder that processes workflow events.
@@ -404,11 +612,23 @@ declare function createIRBuilder(options?: IRBuilderOptions): {
     handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
     getIR: () => WorkflowIR;
     reset: () => void;
+    getSnapshots: () => IRSnapshot[];
+    getSnapshotAt: (index: number) => IRSnapshot | undefined;
+    getIRAt: (index: number) => WorkflowIR | undefined;
+    clearSnapshots: () => void;
     /** Check if there are active (running) steps */
     readonly hasActiveSteps: boolean;
     /** Get the current workflow state */
     readonly state: StepState;
+    /** Get the number of recorded snapshots */
+    readonly snapshotCount: number;
+    /** Check if snapshot recording is enabled */
+    readonly snapshotsEnabled: boolean;
 };
+/**
+ * Type for the IR builder instance.
+ */
+type IRBuilder = ReturnType<typeof createIRBuilder>;
 
 /**
  * ANSI color utilities for terminal output.
@@ -443,6 +663,26 @@ declare function asciiRenderer(): Renderer;
  */
 declare function mermaidRenderer(): Renderer;
 
+/**
+ * HTML Renderer
+ *
+ * Renders the workflow IR as an interactive HTML page with:
+ * - SVG-based workflow diagram
+ * - Zoom and pan
+ * - Node inspection
+ * - Time-travel controls
+ * - Performance heatmap overlay
+ */
+
+/**
+ * Create the HTML renderer.
+ */
+declare function htmlRenderer(): Renderer;
+/**
+ * Render workflow IR to HTML with custom options.
+ */
+declare function renderToHTML(ir: WorkflowIR, options?: Partial<HTMLRenderOptions>): string;
+
 /**
  * Live Visualizer - Real-time terminal updates during workflow execution.
  *
@@ -676,6 +916,232 @@ interface SwitchTracker extends DecisionTracker {
     default(taken: boolean): void;
 }
 
+/**
+ * Time Travel Debugger
+ *
+ * Records IR snapshots at each event, enabling:
+ * - Step-by-step forward/backward navigation
+ * - Seeking to any point in execution
+ * - Playback at various speeds
+ * - State inspection at any moment
+ */
+
+/**
+ * Options for the time-travel controller.
+ */
+interface TimeTravelOptions {
+    /** Maximum snapshots to store (ring buffer) */
+    maxSnapshots?: number;
+    /** Automatically record snapshots on each event */
+    autoRecord?: boolean;
+    /** IR builder options (passed through) */
+    builderOptions?: Omit<IRBuilderOptions, "enableSnapshots" | "maxSnapshots">;
+}
+/**
+ * Time-travel controller interface.
+ */
+interface TimeTravelController {
+    /** Handle a workflow event (records snapshot if recording) */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Navigate to specific snapshot index */
+    seek: (index: number) => WorkflowIR | undefined;
+    /** Move one step forward */
+    stepForward: () => WorkflowIR | undefined;
+    /** Move one step backward */
+    stepBackward: () => WorkflowIR | undefined;
+    /** Start playback at given speed (1.0 = realtime) */
+    play: (speed?: number) => void;
+    /** Pause playback */
+    pause: () => void;
+    /** Get current IR state */
+    getCurrentIR: () => WorkflowIR;
+    /** Get IR at specific snapshot index */
+    getIRAt: (index: number) => WorkflowIR | undefined;
+    /** Get all snapshots */
+    getSnapshots: () => IRSnapshot[];
+    /** Get snapshot at specific index */
+    getSnapshotAt: (index: number) => IRSnapshot | undefined;
+    /** Get current time-travel state */
+    getState: () => TimeTravelState;
+    /** Subscribe to state changes */
+    onStateChange: (callback: (state: TimeTravelState) => void) => () => void;
+    /** Start/resume recording */
+    startRecording: () => void;
+    /** Stop recording */
+    stopRecording: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+    /** Get the underlying IR builder */
+    getBuilder: () => IRBuilder;
+}
+/**
+ * Create a time-travel controller for workflow debugging.
+ *
+ * @example
+ * ```typescript
+ * const controller = createTimeTravelController();
+ *
+ * // Feed events from workflow execution
+ * workflow.onEvent(event => controller.handleEvent(event));
+ *
+ * // After execution, explore the timeline
+ * controller.seek(0);  // Go to start
+ * controller.stepForward();  // Step through
+ * controller.play(2);  // Playback at 2x speed
+ * ```
+ */
+declare function createTimeTravelController(options?: TimeTravelOptions): TimeTravelController;
+
+/**
+ * Performance Analyzer
+ *
+ * Analyzes workflow execution data to identify:
+ * - Slow steps (bottlenecks)
+ * - Retry patterns
+ * - Error-prone steps
+ * - Timing anomalies
+ *
+ * Aggregates metrics across multiple workflow runs to provide
+ * statistical insights and heatmap visualization data.
+ */
+
+/**
+ * A recorded workflow run for analysis.
+ */
+interface WorkflowRun {
+    /** Unique identifier for this run */
+    id: string;
+    /** Workflow start timestamp */
+    startTime: number;
+    /** All events from the workflow execution */
+    events: WorkflowEvent<unknown>[];
+}
+/**
+ * Performance analyzer interface.
+ */
+interface PerformanceAnalyzer {
+    /** Add a completed workflow run for analysis */
+    addRun: (run: WorkflowRun) => void;
+    /** Add events incrementally (alternative to addRun) */
+    addEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Finalize current run (when using addEvent) */
+    finalizeRun: (runId: string) => void;
+    /** Get performance stats for a specific node */
+    getNodePerformance: (nodeId: string) => NodePerformance | undefined;
+    /** Get heatmap data for an IR */
+    getHeatmap: (ir: WorkflowIR, metric?: "duration" | "retryRate" | "errorRate") => HeatmapData;
+    /** Get slowest nodes */
+    getSlowestNodes: (limit?: number) => NodePerformance[];
+    /** Get error-prone nodes */
+    getErrorProneNodes: (limit?: number) => NodePerformance[];
+    /** Get retry-prone nodes */
+    getRetryProneNodes: (limit?: number) => NodePerformance[];
+    /** Get all performance data */
+    getAllPerformance: () => Map<string, NodePerformance>;
+    /** Export performance data as JSON */
+    exportData: () => string;
+    /** Import performance data from JSON */
+    importData: (json: string) => void;
+    /** Clear all collected data */
+    clear: () => void;
+}
+/**
+ * Get heat level from normalized value (0-1).
+ */
+declare function getHeatLevel(heat: number): HeatLevel;
+/**
+ * Create a performance analyzer for workflow metrics.
+ *
+ * @example
+ * ```typescript
+ * const analyzer = createPerformanceAnalyzer();
+ *
+ * // Add completed runs
+ * analyzer.addRun({ id: 'run-1', startTime: Date.now(), events });
+ *
+ * // Get insights
+ * const slowest = analyzer.getSlowestNodes(5);
+ * const heatmap = analyzer.getHeatmap(ir, 'duration');
+ * ```
+ */
+declare function createPerformanceAnalyzer(): PerformanceAnalyzer;
+
+/**
+ * Development Server
+ *
+ * Provides a local HTTP server with WebSocket support for:
+ * - Serving the HTML visualizer
+ * - Live streaming workflow events
+ * - Time-travel control from the browser
+ * - Performance data broadcasting
+ *
+ * The `ws` package is an optional peer dependency.
+ * Install it with: npm install ws
+ */
+
+/**
+ * Options for the dev server.
+ */
+interface DevServerOptions {
+    /** Port to listen on (default: 3377) */
+    port?: number;
+    /** Hostname to bind to (default: localhost) */
+    host?: string;
+    /** Auto-open browser when starting (default: true) */
+    autoOpen?: boolean;
+    /** Workflow name for the visualizer title */
+    workflowName?: string;
+    /** Enable time-travel debugging (default: true) */
+    timeTravel?: boolean;
+    /** Enable performance heatmap (default: true) */
+    heatmap?: boolean;
+    /** Max snapshots for time-travel (default: 1000) */
+    maxSnapshots?: number;
+}
+/**
+ * Dev server interface.
+ */
+interface DevServer {
+    /** Start the server */
+    start(): Promise<{
+        port: number;
+        url: string;
+    }>;
+    /** Stop the server */
+    stop(): Promise<void>;
+    /** Handle a workflow event (forwards to time-travel and broadcasts) */
+    handleEvent(event: WorkflowEvent<unknown>): void;
+    /** Push an IR update to all clients */
+    pushUpdate(ir: WorkflowIR): void;
+    /** Push heatmap data to all clients */
+    pushHeatmap(data: HeatmapData): void;
+    /** Mark workflow as complete */
+    complete(): void;
+    /** Get the time-travel controller */
+    getTimeTravel(): TimeTravelController;
+    /** Get the performance analyzer */
+    getAnalyzer(): PerformanceAnalyzer;
+    /** Get current IR */
+    getCurrentIR(): WorkflowIR;
+}
+/**
+ * Create a development server for the workflow visualizer.
+ *
+ * @example
+ * ```typescript
+ * const server = createDevServer({ port: 3377 });
+ * await server.start();
+ *
+ * // Forward events from workflow execution
+ * workflow.onEvent(event => server.handleEvent(event));
+ *
+ * // When done
+ * server.complete();
+ * await server.stop();
+ * ```
+ */
+declare function createDevServer(options?: DevServerOptions): Promise<DevServer>;
+
 /**
  * Workflow Visualization Module
  *
@@ -808,4 +1274,4 @@ declare function createEventCollector(options?: VisualizerOptions): {
     visualizeAs: (format: OutputFormat) => string;
 };
 
-export { type BaseNode, type CollectableEvent, type ColorScheme, type DecisionBranch, type DecisionBranchEvent, type DecisionEndEvent, type DecisionEvent, type DecisionNode, type DecisionStartEvent, type DecisionTracker, type FlowNode, type IRBuilderOptions, type IfTracker, type LiveVisualizer, type LiveVisualizerOptions, type OutputFormat, type ParallelDetectorOptions, type ParallelNode, type RaceNode, type RenderOptions, type Renderer, type ScopeEndEvent, type ScopeEvent, type ScopeStartEvent, ScopeType, type SequenceNode, type StepNode, type StepSkippedEvent, type StepState, type SwitchTracker, type VisualizerOptions, type WorkflowIR, type WorkflowNode, type WorkflowVisualizer, asciiRenderer, createEventCollector, createIRBuilder, createLiveVisualizer, createParallelDetector, createVisualizer, defaultColorScheme, detectParallelGroups, hasChildren, isDecisionNode, isParallelNode, isRaceNode, isSequenceNode, isStepNode, mermaidRenderer, trackDecision, trackIf, trackSwitch, visualizeEvents };
+export { type ActiveStepSnapshot, type BaseNode, type CollectableEvent, type ColorScheme, type DecisionBranch, type DecisionBranchEvent, type DecisionEndEvent, type DecisionEvent, type DecisionNode, type DecisionStartEvent, type DecisionTracker, type DevServer, type DevServerOptions, type EnhancedRenderOptions, type FlowNode, type HTMLRenderOptions, type HTMLTheme, type HeatLevel, type HeatmapData, type HookExecution, type HookState, type IRBuilderOptions, type IRSnapshot, type IfTracker, type LayoutDirection, type LiveVisualizer, type LiveVisualizerOptions, type NodePerformance, type OutputFormat, type ParallelDetectorOptions, type ParallelNode, type PerformanceAnalyzer, type RaceNode, type RenderOptions, type Renderer, type ScopeEndEvent, type ScopeEvent, type ScopeStartEvent, ScopeType, type SequenceNode, type ServerMessage, type StepNode, type StepSkippedEvent, type StepState, type SwitchTracker, type TimeTravelController, type TimeTravelOptions, type TimeTravelState, type VisualizerOptions, type WebVisualizerMessage, type WorkflowHooks, type WorkflowIR, type WorkflowNode, type WorkflowRun, type WorkflowVisualizer, asciiRenderer, createDevServer, createEventCollector, createIRBuilder, createLiveVisualizer, createParallelDetector, createPerformanceAnalyzer, createTimeTravelController, createVisualizer, defaultColorScheme, detectParallelGroups, getHeatLevel, hasChildren, htmlRenderer, isDecisionNode, isParallelNode, isRaceNode, isSequenceNode, isStepNode, mermaidRenderer, renderToHTML, trackDecision, trackIf, trackSwitch, visualizeEvents };