@jagreehal/workflow 1.1.0 → 1.3.0

package/dist/visualize.d.ts

@@ -0,0 +1,805 @@
+import { ScopeType, WorkflowEvent } from './core.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;
+}
+/**
+ * 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;
+    };
+}
+
+/**
+ * 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;
+}
+/**
+ * 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";
+/**
+ * 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;
+
+/**
+ * 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;
+}
+/**
+ * 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;
+    /** Check if there are active (running) steps */
+    readonly hasActiveSteps: boolean;
+    /** Get the current workflow state */
+    readonly state: StepState;
+};
+
+/**
+ * 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;
+
+/**
+ * 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 '@jagreehal/workflow/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;
+}
+
+/**
+ * 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 '@jagreehal/workflow/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 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 };