awaitly 1.0.0

package/dist/visualize.d.ts

@@ -0,0 +1,1415 @@
+import { k as ScopeType, W as WorkflowEvent } from './core-BuTBsR0x.js';
+
+/**
+ * Workflow Visualization - Intermediate Representation Types
+ *
+ * The IR (Intermediate Representation) is a DSL that represents workflow
+ * execution structure. Events are converted to IR, which can then be
+ * rendered to various output formats (ASCII, Mermaid, JSON, etc.).
+ */
+/**
+ * Execution state of a step with semantic meaning for visualization.
+ *
+ * Color mapping:
+ * - pending  → white/clear (not started)
+ * - running  → yellow (currently executing)
+ * - success  → green (completed successfully)
+ * - error    → red (failed with error)
+ * - aborted  → gray (cancelled, e.g., in race)
+ * - cached   → blue (served from cache)
+ * - skipped  → dim gray (not executed due to conditional logic)
+ */
+type StepState = "pending" | "running" | "success" | "error" | "aborted" | "cached" | "skipped";
+/**
+ * Base properties shared by all IR nodes.
+ */
+interface BaseNode {
+    /** Unique identifier for this node */
+    id: string;
+    /** Human-readable name (from step options or inferred) */
+    name?: string;
+    /** Cache key if this is a keyed step */
+    key?: string;
+    /** Current execution state */
+    state: StepState;
+    /** Timestamp when execution started */
+    startTs?: number;
+    /** Timestamp when execution ended */
+    endTs?: number;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Error value if state is 'error' */
+    error?: unknown;
+    /** Input value that triggered this step (for decision understanding) */
+    input?: unknown;
+    /** Output value from this step (for decision understanding) */
+    output?: unknown;
+    /** Number of retry attempts made (0 = no retries, 1 = one retry, etc.) */
+    retryCount?: number;
+    /** Whether this step experienced a timeout (may have retried after) */
+    timedOut?: boolean;
+    /** Timeout duration in ms (if timed out) */
+    timeoutMs?: number;
+}
+/**
+ * A single step execution node.
+ */
+interface StepNode extends BaseNode {
+    type: "step";
+}
+/**
+ * Sequential execution - steps run one after another.
+ * This is the implicit structure when steps are awaited in sequence.
+ */
+interface SequenceNode extends BaseNode {
+    type: "sequence";
+    children: FlowNode[];
+}
+/**
+ * Parallel execution - all branches run simultaneously.
+ * Created by allAsync() or allSettledAsync().
+ */
+interface ParallelNode extends BaseNode {
+    type: "parallel";
+    children: FlowNode[];
+    /**
+     * Execution mode:
+     * - 'all': Fails on first error (allAsync)
+     * - 'allSettled': Collects all results (allSettledAsync)
+     */
+    mode: "all" | "allSettled";
+}
+/**
+ * Race execution - first to complete wins.
+ * Created by anyAsync().
+ */
+interface RaceNode extends BaseNode {
+    type: "race";
+    children: FlowNode[];
+    /** ID of the winning branch (first to succeed) */
+    winnerId?: string;
+}
+/**
+ * Decision point - conditional branch (if/switch).
+ * Shows which branch was taken and why.
+ */
+interface DecisionNode extends BaseNode {
+    type: "decision";
+    /** Condition that was evaluated (e.g., "user.role === 'admin'") */
+    condition?: string;
+    /** Value that was evaluated (the input to the decision) */
+    decisionValue?: unknown;
+    /** Which branch was taken (true/false, or the matched case) */
+    branchTaken?: string | boolean;
+    /** All possible branches (including skipped ones) */
+    branches: DecisionBranch[];
+}
+/**
+ * A branch in a decision node.
+ */
+interface DecisionBranch {
+    /** Label for this branch (e.g., "if", "else", "case 'admin'") */
+    label: string;
+    /** Condition that would trigger this branch */
+    condition?: string;
+    /** Whether this branch was taken */
+    taken: boolean;
+    /** Steps in this branch */
+    children: FlowNode[];
+}
+/**
+ * Union of all flow node types.
+ */
+type FlowNode = StepNode | SequenceNode | ParallelNode | RaceNode | DecisionNode;
+/**
+ * Root node representing the entire workflow.
+ */
+interface WorkflowNode extends BaseNode {
+    type: "workflow";
+    /** Correlation ID from the workflow execution */
+    workflowId: string;
+    /** Child nodes (steps, parallel blocks, etc.) */
+    children: FlowNode[];
+}
+/**
+ * Complete workflow intermediate representation.
+ * This is the main data structure produced by the IR builder.
+ */
+interface WorkflowIR {
+    /** Root workflow node */
+    root: WorkflowNode;
+    /** Metadata about the IR */
+    metadata: {
+        /** When the IR was first created */
+        createdAt: number;
+        /** When the IR was last updated */
+        lastUpdatedAt: number;
+    };
+    /** Hook executions (if any hooks are configured) */
+    hooks?: WorkflowHooks;
+}
+
+/**
+ * Event emitted when entering a parallel/race scope.
+ * This matches the scope_start event in WorkflowEvent.
+ */
+interface ScopeStartEvent {
+    type: "scope_start";
+    workflowId: string;
+    scopeId: string;
+    scopeType: ScopeType;
+    name?: string;
+    ts: number;
+}
+/**
+ * Event emitted when exiting a parallel/race scope.
+ */
+interface ScopeEndEvent {
+    type: "scope_end";
+    workflowId: string;
+    scopeId: string;
+    ts: number;
+    durationMs: number;
+    /** For race scopes, the ID of the winning branch */
+    winnerId?: string;
+}
+/**
+ * Event emitted when a decision point is encountered.
+ * Use this to track conditional logic (if/switch).
+ */
+interface DecisionStartEvent {
+    type: "decision_start";
+    workflowId: string;
+    decisionId: string;
+    /** Condition being evaluated (e.g., "user.role === 'admin'") */
+    condition?: string;
+    /** Value being evaluated */
+    decisionValue?: unknown;
+    /** Name/label for this decision point */
+    name?: string;
+    ts: number;
+}
+/**
+ * Event emitted when a decision branch is taken.
+ */
+interface DecisionBranchEvent {
+    type: "decision_branch";
+    workflowId: string;
+    decisionId: string;
+    /** Label for this branch (e.g., "if", "else", "case 'admin'") */
+    branchLabel: string;
+    /** Condition for this branch */
+    condition?: string;
+    /** Whether this branch was taken */
+    taken: boolean;
+    ts: number;
+}
+/**
+ * Event emitted when a decision point completes.
+ */
+interface DecisionEndEvent {
+    type: "decision_end";
+    workflowId: string;
+    decisionId: string;
+    /** Which branch was taken */
+    branchTaken?: string | boolean;
+    ts: number;
+    durationMs: number;
+}
+/**
+ * Event emitted when a step is skipped due to conditional logic.
+ */
+interface StepSkippedEvent {
+    type: "step_skipped";
+    workflowId: string;
+    stepKey?: string;
+    name?: string;
+    /** Reason why this step was skipped (e.g., "condition was false") */
+    reason?: string;
+    /** The decision that caused this skip */
+    decisionId?: string;
+    ts: number;
+}
+/**
+ * Union of scope-related events.
+ */
+type ScopeEvent = ScopeStartEvent | ScopeEndEvent;
+/**
+ * Union of decision-related events.
+ */
+type DecisionEvent = DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent;
+/**
+ * Color scheme for rendering step states.
+ */
+interface ColorScheme {
+    pending: string;
+    running: string;
+    success: string;
+    error: string;
+    aborted: string;
+    cached: string;
+    skipped: string;
+}
+/**
+ * Options passed to renderers.
+ */
+interface RenderOptions {
+    /** Show timing information (duration) */
+    showTimings: boolean;
+    /** Show step cache keys */
+    showKeys: boolean;
+    /** Terminal width for ASCII renderer */
+    terminalWidth?: number;
+    /** Color scheme */
+    colors: ColorScheme;
+}
+/**
+ * Extended options for Mermaid renderer.
+ * Controls how edges are displayed for retries, errors, and timeouts.
+ */
+interface MermaidRenderOptions extends RenderOptions {
+    /** Show retry as self-loop edge (default: true) */
+    showRetryEdges?: boolean;
+    /** Show error flow to error node (default: true) */
+    showErrorEdges?: boolean;
+    /** Show timeout as alternative path (default: true) */
+    showTimeoutEdges?: boolean;
+}
+/**
+ * Renderer interface - transforms IR to output format.
+ */
+interface Renderer {
+    /** Unique identifier for this renderer */
+    readonly name: string;
+    /** Render IR to string output */
+    render(ir: WorkflowIR, options: RenderOptions): string;
+    /** Whether this renderer supports live (incremental) updates */
+    supportsLive?: boolean;
+    /** Render incremental update (optional) */
+    renderUpdate?(ir: WorkflowIR, changedNodes: FlowNode[], options: RenderOptions): string;
+}
+/**
+ * Output format for rendering.
+ */
+type OutputFormat = "ascii" | "mermaid" | "json" | "logger" | "flowchart";
+/**
+ * Options for creating a visualizer.
+ */
+interface VisualizerOptions {
+    /** Name for the workflow in visualizations */
+    workflowName?: string;
+    /** Enable parallel detection heuristics (default: true) */
+    detectParallel?: boolean;
+    /** Show timing information (default: true) */
+    showTimings?: boolean;
+    /** Show step keys (default: false) */
+    showKeys?: boolean;
+    /** Custom color scheme */
+    colors?: Partial<ColorScheme>;
+}
+/**
+ * Options for live visualization.
+ */
+interface LiveVisualizerOptions extends VisualizerOptions {
+    /** Output stream (default: process.stdout) */
+    stream?: NodeJS.WriteStream;
+    /** Update interval in ms (default: 100) */
+    updateInterval?: number;
+}
+/**
+ * Check if a node is a StepNode.
+ */
+declare function isStepNode(node: FlowNode): node is StepNode;
+/**
+ * Check if a node is a SequenceNode.
+ */
+declare function isSequenceNode(node: FlowNode): node is SequenceNode;
+/**
+ * Check if a node is a ParallelNode.
+ */
+declare function isParallelNode(node: FlowNode): node is ParallelNode;
+/**
+ * Check if a node is a RaceNode.
+ */
+declare function isRaceNode(node: FlowNode): node is RaceNode;
+/**
+ * Check if a node is a DecisionNode.
+ */
+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[]>;
+}
+/**
+ * Options for the flowchart ASCII renderer.
+ * Renders workflow as a proper flowchart with boxes and arrows.
+ */
+interface FlowchartRenderOptions extends EnhancedRenderOptions {
+    /** Show start and end nodes (default: true) */
+    showStartEnd?: boolean;
+    /** Reduce vertical spacing between nodes (default: false) */
+    compact?: boolean;
+    /** Box border style (default: 'single') */
+    boxStyle?: "single" | "double" | "rounded";
+}
+/**
+ * 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.
+ *
+ * When steps overlap in time (one starts before another ends), they are
+ * likely running in parallel. This module detects such patterns and
+ * groups overlapping steps into ParallelNode structures.
+ */
+
+/**
+ * Options for parallel detection.
+ */
+interface ParallelDetectorOptions {
+    /**
+     * Minimum overlap in milliseconds to consider steps parallel.
+     * Default: 0 (any overlap counts)
+     */
+    minOverlapMs?: number;
+    /**
+     * Maximum gap in milliseconds to still consider steps as part of same parallel group.
+     * Default: 5 (steps starting within 5ms are grouped)
+     */
+    maxGapMs?: number;
+}
+/**
+ * Group overlapping steps into parallel nodes.
+ *
+ * Algorithm:
+ * 1. Sort steps by start time
+ * 2. For each step, check if it overlaps with existing parallel groups
+ * 3. If it overlaps, add to group; otherwise start new sequence
+ * 4. Merge overlapping groups when step bridges them
+ *
+ * Note: If real scope nodes (from scope_start/scope_end) are present,
+ * heuristic detection is skipped to avoid conflicts.
+ */
+declare function detectParallelGroups(nodes: FlowNode[], options?: ParallelDetectorOptions): FlowNode[];
+/**
+ * Create a parallel detector that processes nodes.
+ */
+declare function createParallelDetector(options?: ParallelDetectorOptions): {
+    /**
+     * Process nodes and group overlapping ones into parallel nodes.
+     */
+    detect: (nodes: FlowNode[]) => FlowNode[];
+};
+
+/**
+ * IR Builder - Converts workflow events to Intermediate Representation.
+ *
+ * The builder maintains state as events arrive, constructing a tree
+ * representation of the workflow execution that can be rendered.
+ */
+
+/**
+ * Options for the IR builder.
+ */
+interface IRBuilderOptions {
+    /**
+     * Enable heuristic parallel detection based on timing.
+     * When true, overlapping steps are grouped into ParallelNodes.
+     * Default: true
+     */
+    detectParallel?: boolean;
+    /**
+     * 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.
+ */
+declare function createIRBuilder(options?: IRBuilderOptions): {
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    handleScopeEvent: (event: ScopeStartEvent | ScopeEndEvent) => void;
+    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.
+ */
+
+/**
+ * Default ANSI color scheme for step states.
+ */
+declare const defaultColorScheme: ColorScheme;
+
+/**
+ * ASCII Terminal Renderer
+ *
+ * Renders the workflow IR as ASCII art with box-drawing characters
+ * and ANSI colors for terminal display.
+ */
+
+/**
+ * Create the ASCII terminal renderer.
+ */
+declare function asciiRenderer(): Renderer;
+
+/**
+ * Mermaid Diagram Renderer
+ *
+ * Renders the workflow IR as a Mermaid flowchart diagram.
+ * Supports sequential flows, parallel (subgraph), and race patterns.
+ */
+
+/**
+ * Create the Mermaid diagram renderer.
+ */
+declare function mermaidRenderer(): Renderer;
+
+/**
+ * Logger Renderer - Outputs structured JSON optimized for logging systems.
+ *
+ * Works with any structured logger (Pino, Winston, Bunyan, console).
+ * Includes workflow summary, step details, and optional ASCII diagram.
+ *
+ * @example
+ * ```typescript
+ * const logData = JSON.parse(viz.renderAs('logger'));
+ * logger.info(logData, 'Workflow completed');
+ * ```
+ */
+
+/**
+ * Step log entry with execution details.
+ */
+interface StepLog {
+    id: string;
+    name: string;
+    key?: string;
+    state: string;
+    durationMs?: number;
+    startTs?: number;
+    endTs?: number;
+    retryCount?: number;
+    timedOut?: boolean;
+    timeoutMs?: number;
+    error?: string;
+}
+/**
+ * Hook execution log entry.
+ */
+interface HookLog {
+    shouldRun?: {
+        result?: boolean;
+        durationMs?: number;
+        error?: string;
+    };
+    onBeforeStart?: {
+        durationMs?: number;
+        error?: string;
+    };
+    onAfterStep?: Array<{
+        stepKey: string;
+        durationMs?: number;
+        error?: string;
+    }>;
+}
+/**
+ * Summary statistics for the workflow.
+ */
+interface WorkflowSummary {
+    totalSteps: number;
+    successCount: number;
+    errorCount: number;
+    cacheHits: number;
+    skippedCount: number;
+    totalRetries: number;
+    slowestStep?: {
+        name: string;
+        durationMs: number;
+    };
+}
+/**
+ * Complete logger output structure.
+ */
+interface LoggerOutput {
+    workflow: {
+        id: string;
+        name?: string;
+        state: string;
+        durationMs?: number;
+        startedAt?: number;
+        completedAt?: number;
+    };
+    steps: StepLog[];
+    summary: WorkflowSummary;
+    hooks?: HookLog;
+    diagram?: string;
+}
+/**
+ * Extended render options for logger renderer.
+ */
+interface LoggerRenderOptions extends RenderOptions {
+    /** Include ASCII diagram in output (default: true) */
+    includeDiagram?: boolean;
+    /** Strip ANSI color codes from diagram (default: true) */
+    stripAnsiColors?: boolean;
+    /** Diagram format: 'ascii' (tree-style) or 'flowchart' (boxes/arrows) (default: 'ascii') */
+    diagramFormat?: "ascii" | "flowchart";
+}
+/**
+ * Create a logger renderer that outputs structured JSON.
+ *
+ * @example
+ * ```typescript
+ * const viz = createVisualizer({ workflowName: 'checkout' });
+ * // ... run workflow ...
+ *
+ * const logData = JSON.parse(viz.renderAs('logger'));
+ * logger.info(logData, 'Workflow completed');
+ * ```
+ */
+declare function loggerRenderer(): Renderer;
+
+/**
+ * Flowchart ASCII Renderer
+ *
+ * Renders workflow IR as a proper flowchart with boxes and arrows.
+ * Uses a 2D canvas approach for spatial layout with proper fork/join patterns.
+ */
+
+declare function flowchartRenderer(): 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.
+ *
+ * Uses ANSI escape codes to update the terminal in-place, showing
+ * workflow progress as it happens.
+ */
+
+/**
+ * Live visualizer with real-time terminal updates.
+ */
+interface LiveVisualizer {
+    /** Process a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Process a scope event */
+    handleScopeEvent: (event: ScopeStartEvent | ScopeEndEvent) => void;
+    /** Process a decision event */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get current IR state */
+    getIR: () => WorkflowIR;
+    /** Render current state to string (without terminal output) */
+    render: () => string;
+    /** Start live rendering to terminal */
+    start: () => void;
+    /** Stop live rendering */
+    stop: () => void;
+    /** Force an immediate redraw */
+    refresh: () => void;
+    /** Reset state for a new workflow */
+    reset: () => void;
+}
+/**
+ * Create a live visualizer for real-time terminal updates.
+ *
+ * @example
+ * ```typescript
+ * const live = createLiveVisualizer({ workflowName: 'my-workflow' });
+ * const workflow = createWorkflow(deps, { onEvent: live.handleEvent });
+ *
+ * live.start();
+ * await workflow(async (step) => { ... });
+ * live.stop();
+ * ```
+ */
+declare function createLiveVisualizer(options?: LiveVisualizerOptions): LiveVisualizer;
+
+/**
+ * Decision Tracker - Helper for tracking conditional logic in workflows.
+ *
+ * This module provides utilities to track decision points (if/switch statements)
+ * so they can be visualized in workflow diagrams.
+ *
+ * @example
+ * ```typescript
+ * import { trackDecision } from 'awaitly/visualize';
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: (event) => {
+ *     // Pass events to visualizer
+ *     viz.handleEvent(event);
+ *   }
+ * });
+ *
+ * await workflow(async (step) => {
+ *   const user = await step(fetchUser(id));
+ *
+ *   // Track a decision point
+ *   const decision = trackDecision('user-role-check', {
+ *     condition: 'user.role === "admin"',
+ *     value: user.role
+ *   });
+ *
+ *   if (user.role === 'admin') {
+ *     decision.takeBranch('admin', true);
+ *     await step(processAdminAction(user));
+ *   } else {
+ *     decision.takeBranch('user', false);
+ *     await step(processUserAction(user));
+ *   }
+ *
+ *   decision.end();
+ * });
+ * ```
+ */
+
+/**
+ * Options for creating a decision tracker.
+ */
+interface DecisionTrackerOptions {
+    /** Condition being evaluated (e.g., "user.role === 'admin'") */
+    condition?: string;
+    /** Value being evaluated */
+    value?: unknown;
+    /** Name/label for this decision point */
+    name?: string;
+    /** Workflow ID (auto-generated if not provided) */
+    workflowId?: string;
+    /** Event emitter function */
+    emit?: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+}
+/**
+ * Track a decision point in your workflow.
+ *
+ * Use this to annotate conditional logic (if/switch) so it appears
+ * in workflow visualizations.
+ *
+ * @param decisionId - Unique identifier for this decision
+ * @param options - Decision tracking options
+ * @returns A tracker object with methods to track branches
+ *
+ * @example
+ * ```typescript
+ * const decision = trackDecision('check-role', {
+ *   condition: 'user.role === "admin"',
+ *   value: user.role,
+ *   emit: (event) => viz.handleDecisionEvent(event)
+ * });
+ *
+ * if (user.role === 'admin') {
+ *   decision.takeBranch('admin', true);
+ *   // ... admin logic
+ * } else {
+ *   decision.takeBranch('user', false);
+ *   // ... user logic
+ * }
+ *
+ * decision.end();
+ * ```
+ */
+declare function trackDecision(decisionId: string, options?: DecisionTrackerOptions): DecisionTracker;
+/**
+ * Decision tracker instance.
+ */
+interface DecisionTracker {
+    /**
+     * Mark that a branch was taken or skipped.
+     * @param label - Label for this branch (e.g., "if", "else", "case 'admin'")
+     * @param taken - Whether this branch was executed
+     * @param branchCondition - Optional condition for this specific branch
+     */
+    takeBranch(label: string, taken: boolean, branchCondition?: string): void;
+    /**
+     * End the decision tracking.
+     * Call this after all branches have been evaluated.
+     */
+    end(): void;
+    /**
+     * Get which branch was taken.
+     */
+    getBranchTaken(): string | boolean | undefined;
+    /**
+     * Get all branches (taken and skipped).
+     */
+    getBranches(): Array<{
+        label: string;
+        condition?: string;
+        taken: boolean;
+    }>;
+}
+/**
+ * Track a simple if/else decision.
+ *
+ * @example
+ * ```typescript
+ * const decision = trackIf('check-admin', user.role === 'admin', {
+ *   condition: 'user.role === "admin"',
+ *   value: user.role,
+ *   emit: (e) => viz.handleDecisionEvent(e)
+ * });
+ *
+ * if (decision.condition) {
+ *   decision.then();
+ *   // admin logic
+ * } else {
+ *   decision.else();
+ *   // user logic
+ * }
+ *
+ * decision.end();
+ * ```
+ */
+declare function trackIf(decisionId: string, condition: boolean, options?: Omit<DecisionTrackerOptions, "value"> & {
+    value?: unknown;
+}): IfTracker;
+/**
+ * If tracker with convenience methods.
+ */
+interface IfTracker extends DecisionTracker {
+    /** The condition value */
+    condition: boolean;
+    /** Mark the "if" branch as taken */
+    then(): void;
+    /** Mark the "else" branch as taken */
+    else(): void;
+}
+/**
+ * Track a switch statement decision.
+ *
+ * @example
+ * ```typescript
+ * const decision = trackSwitch('process-type', user.type, {
+ *   emit: (e) => viz.handleDecisionEvent(e)
+ * });
+ *
+ * switch (user.type) {
+ *   case 'admin':
+ *     decision.case('admin', true);
+ *     // admin logic
+ *     break;
+ *   case 'user':
+ *     decision.case('user', true);
+ *     // user logic
+ *     break;
+ *   default:
+ *     decision.default(true);
+ *     // default logic
+ * }
+ *
+ * decision.end();
+ * ```
+ */
+declare function trackSwitch(decisionId: string, value: unknown, options?: Omit<DecisionTrackerOptions, "value">): SwitchTracker;
+/**
+ * Switch tracker with convenience methods.
+ */
+interface SwitchTracker extends DecisionTracker {
+    /** The value being switched on */
+    value: unknown;
+    /** Mark a case branch */
+    case(caseValue: string | number, taken: boolean): void;
+    /** Mark the default branch */
+    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
+ *
+ * Provides tools for visualizing workflow execution with color-coded
+ * step states and support for parallel/race operations.
+ *
+ * @example
+ * ```typescript
+ * import { createVisualizer } from 'awaitly/visualize';
+ *
+ * const viz = createVisualizer({ workflowName: 'checkout' });
+ * const workflow = createWorkflow(deps, { onEvent: viz.handleEvent });
+ *
+ * await workflow(async (step) => {
+ *   await step(() => validateCart(cart), 'Validate cart');
+ *   await step(() => processPayment(payment), 'Process payment');
+ * });
+ *
+ * console.log(viz.render());
+ * ```
+ */
+
+/**
+ * Workflow visualizer that processes events and renders output.
+ */
+interface WorkflowVisualizer {
+    /** Process a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Process a scope event (parallel/race) */
+    handleScopeEvent: (event: ScopeStartEvent | ScopeEndEvent) => void;
+    /** Process a decision event (conditional branches) */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get current IR state */
+    getIR: () => WorkflowIR;
+    /** Render current state using the default renderer */
+    render: () => string;
+    /** Render to a specific format */
+    renderAs: (format: OutputFormat) => string;
+    /** Reset state for a new workflow */
+    reset: () => void;
+    /** Subscribe to IR updates (for live visualization) */
+    onUpdate: (callback: (ir: WorkflowIR) => void) => () => void;
+}
+/**
+ * Create a workflow visualizer.
+ *
+ * @example
+ * ```typescript
+ * const viz = createVisualizer({ workflowName: 'my-workflow' });
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: viz.handleEvent,
+ * });
+ *
+ * await workflow(async (step) => { ... });
+ *
+ * console.log(viz.render());
+ * ```
+ */
+declare function createVisualizer(options?: VisualizerOptions): WorkflowVisualizer;
+/**
+ * Union type for all collectable/visualizable events (workflow + decision).
+ */
+type CollectableEvent = WorkflowEvent<unknown> | DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent;
+/**
+ * Visualize collected events (post-execution).
+ *
+ * Supports both workflow events (from onEvent) and decision events
+ * (from trackDecision/trackIf/trackSwitch).
+ *
+ * @example
+ * ```typescript
+ * const events: CollectableEvent[] = [];
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: (e) => events.push(e),
+ * });
+ *
+ * await workflow(async (step) => {
+ *   const decision = trackIf('check', condition, {
+ *     emit: (e) => events.push(e),
+ *   });
+ *   // ...
+ * });
+ *
+ * console.log(visualizeEvents(events));
+ * ```
+ */
+declare function visualizeEvents(events: CollectableEvent[], options?: VisualizerOptions): string;
+/**
+ * Create an event collector for later visualization.
+ *
+ * Supports both workflow events (from onEvent) and decision events
+ * (from trackDecision/trackIf/trackSwitch).
+ *
+ * @example
+ * ```typescript
+ * const collector = createEventCollector();
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: collector.handleEvent,
+ * });
+ *
+ * await workflow(async (step) => {
+ *   // Decision events can also be collected
+ *   const decision = trackIf('check', condition, {
+ *     emit: collector.handleDecisionEvent,
+ *   });
+ *   // ...
+ * });
+ *
+ * console.log(collector.visualize());
+ * ```
+ */
+declare function createEventCollector(options?: VisualizerOptions): {
+    /** Handle a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Handle a decision event */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get all collected events */
+    getEvents: () => CollectableEvent[];
+    /** Get workflow events only */
+    getWorkflowEvents: () => WorkflowEvent<unknown>[];
+    /** Get decision events only */
+    getDecisionEvents: () => (DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent)[];
+    /** Clear collected events */
+    clear: () => void;
+    /** Visualize collected events */
+    visualize: () => string;
+    /** Visualize in a specific format */
+    visualizeAs: (format: OutputFormat) => string;
+};
+
+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 FlowchartRenderOptions, type HTMLRenderOptions, type HTMLTheme, type HeatLevel, type HeatmapData, type HookExecution, type HookLog, type HookState, type IRBuilderOptions, type IRSnapshot, type IfTracker, type LayoutDirection, type LiveVisualizer, type LiveVisualizerOptions, type LoggerOutput, type LoggerRenderOptions, type MermaidRenderOptions, 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 StepLog, 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 WorkflowSummary, type WorkflowVisualizer, asciiRenderer, createDevServer, createEventCollector, createIRBuilder, createLiveVisualizer, createParallelDetector, createPerformanceAnalyzer, createTimeTravelController, createVisualizer, defaultColorScheme, detectParallelGroups, flowchartRenderer, getHeatLevel, hasChildren, htmlRenderer, isDecisionNode, isParallelNode, isRaceNode, isSequenceNode, isStepNode, loggerRenderer, mermaidRenderer, renderToHTML, trackDecision, trackIf, trackSwitch, visualizeEvents };