@rytejs/core 0.6.0 → 0.7.0

package/dist/plugin-DHN3Pk52.d.ts

@@ -0,0 +1,339 @@
+import { W as WorkflowConfig, S as StateNames, h as StateData, j as WorkflowOf, i as Workflow, a as WorkflowSnapshot, V as ValidationError, k as WorkflowConfigInput, C as CommandNames, b as CommandPayload, g as EventNames, f as EventData, E as ErrorCodes, e as ErrorData, D as DispatchResult, P as PipelineError } from './snapshot-D5iZubCz.js';
+import { ZodType, z } from 'zod';
+
+/**
+ * The result of {@link defineWorkflow} — holds schemas and creates workflow instances.
+ */
+interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
+    /** The raw Zod schema configuration. */
+    readonly config: TConfig;
+    /** The workflow definition name. */
+    readonly name: string;
+    /**
+     * Creates a new workflow instance in a given initial state.
+     *
+     * @param id - Unique identifier for this workflow instance
+     * @param config - Object containing `initialState` and the corresponding `data`
+     * @returns A {@link WorkflowOf} narrowed to the initial state
+     */
+    createWorkflow<S extends StateNames<TConfig>>(id: string, config: {
+        initialState: S;
+        data: StateData<TConfig, S>;
+    }): WorkflowOf<TConfig, S>;
+    /**
+     * Returns the Zod schema for a given state name.
+     *
+     * @param stateName - The state name to look up
+     * @throws If the state name is not found in the config
+     */
+    getStateSchema(stateName: string): ZodType;
+    /**
+     * Returns the Zod schema for a given command name.
+     *
+     * @param commandName - The command name to look up
+     * @throws If the command name is not found in the config
+     */
+    getCommandSchema(commandName: string): ZodType;
+    /**
+     * Returns the Zod schema for a given event name.
+     *
+     * @param eventName - The event name to look up
+     * @throws If the event name is not found in the config
+     */
+    getEventSchema(eventName: string): ZodType;
+    /**
+     * Returns the Zod schema for a given error code.
+     *
+     * @param errorCode - The error code to look up
+     * @throws If the error code is not found in the config
+     */
+    getErrorSchema(errorCode: string): ZodType;
+    /**
+     * Returns `true` if the given state name exists in the config.
+     *
+     * @param stateName - The state name to check
+     */
+    hasState(stateName: string): boolean;
+    /**
+     * Returns `true` if the given command name exists in the config.
+     */
+    hasCommand(commandName: string): boolean;
+    /**
+     * Returns `true` if the given event name exists in the config.
+     */
+    hasEvent(eventName: string): boolean;
+    /**
+     * Serializes a workflow instance into a plain, JSON-safe snapshot.
+     *
+     * @param workflow - The workflow instance to serialize
+     * @returns A {@link WorkflowSnapshot} representing the current state
+     */
+    serialize(workflow: Workflow<TConfig>): WorkflowSnapshot<TConfig>;
+    /**
+     * Deserializes a workflow instance from a plain snapshot, validating the state data.
+     *
+     * @param snapshot - The snapshot to deserialize from
+     * @returns A result object: `{ ok: true, workflow }` or `{ ok: false, error }`
+     */
+    deserialize(snapshot: WorkflowSnapshot<TConfig>): {
+        ok: true;
+        workflow: Workflow<TConfig>;
+    } | {
+        ok: false;
+        error: ValidationError;
+    };
+}
+/**
+ * Creates a workflow definition from a name and Zod schema configuration.
+ *
+ * @param name - Unique name for this workflow type
+ * @param config - Object with `states`, `commands`, `events`, `errors` — each a record of Zod schemas
+ * @returns A {@link WorkflowDefinition} with methods for creating instances and accessing schemas
+ */
+declare function defineWorkflow<const TConfig extends WorkflowConfigInput>(name: string, config: TConfig): WorkflowDefinition<TConfig & {
+    _resolved: {
+        states: {
+            [K in keyof TConfig["states"]]: z.infer<TConfig["states"][K]>;
+        };
+        commands: {
+            [K in keyof TConfig["commands"]]: z.infer<TConfig["commands"][K]>;
+        };
+        events: {
+            [K in keyof TConfig["events"]]: z.infer<TConfig["events"][K]>;
+        };
+        errors: {
+            [K in keyof TConfig["errors"]]: z.infer<TConfig["errors"][K]>;
+        };
+    };
+}>;
+
+/** A phantom-typed key for type-safe middleware state storage via {@link Context.set} and {@link Context.get}. */
+interface ContextKey<T> {
+    /** @internal Phantom type brand — not used at runtime. */
+    readonly _phantom: T;
+    /** Internal symbol providing uniqueness. */
+    readonly id: symbol;
+}
+/**
+ * Creates a unique typed key for storing and retrieving values in context.
+ *
+ * @param name - Debug label (uniqueness comes from an internal `Symbol`)
+ * @returns A {@link ContextKey} for use with `ctx.set()`, `ctx.get()`, and `ctx.getOrNull()`
+ */
+declare function createKey<T>(name: string): ContextKey<T>;
+
+/** Mutable context flowing through the middleware pipeline during dispatch. */
+interface Context<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> {
+    /** The command being dispatched, with type and validated payload. */
+    readonly command: {
+        readonly type: TCommand;
+        readonly payload: CommandPayload<TConfig, TCommand>;
+    };
+    /** The original workflow before any mutations. */
+    readonly workflow: WorkflowOf<TConfig, TState>;
+    /** Dependencies injected via the router constructor. */
+    readonly deps: TDeps;
+    /** Current state data (reflects mutations from {@link update}). */
+    readonly data: StateData<TConfig, TState>;
+    /**
+     * Merges partial data into the current state. Validates against the state's Zod schema.
+     * @param data - Partial state data to merge
+     */
+    update(data: Partial<StateData<TConfig, TState>>): void;
+    /**
+     * Transitions the workflow to a new state with new data. Validates against the target state's Zod schema.
+     * @param target - Target state name
+     * @param data - Data for the target state
+     */
+    transition<Target extends StateNames<TConfig>>(target: Target, data: StateData<TConfig, Target>): void;
+    /**
+     * Emits a domain event. Validates event data against the event's Zod schema.
+     * @param event - Event with type and data
+     */
+    emit<E extends EventNames<TConfig>>(event: {
+        type: E;
+        data: EventData<TConfig, E>;
+    }): void;
+    /** Accumulated events emitted during this dispatch. */
+    readonly events: ReadonlyArray<{
+        type: EventNames<TConfig>;
+        data: unknown;
+    }>;
+    /**
+     * Signals a domain error. Validates error data and throws internally (caught by the router).
+     * @param err - Error with code and data
+     */
+    error<C extends ErrorCodes<TConfig>>(err: {
+        code: C;
+        data: ErrorData<TConfig, C>;
+    }): never;
+    /**
+     * Stores a value in context-scoped middleware state.
+     * @param key - A {@link ContextKey} created via {@link createKey}
+     * @param value - The value to store
+     */
+    set<T>(key: ContextKey<T>, value: T): void;
+    /**
+     * Retrieves a value from context-scoped middleware state. Throws if not set.
+     * @param key - A {@link ContextKey} created via {@link createKey}
+     */
+    get<T>(key: ContextKey<T>): T;
+    /**
+     * Retrieves a value from context-scoped middleware state, or `undefined` if not set.
+     * @param key - A {@link ContextKey} created via {@link createKey}
+     */
+    getOrNull<T>(key: ContextKey<T>): T | undefined;
+    /** @internal — not part of the handler API */
+    getWorkflowSnapshot(): Workflow<TConfig>;
+}
+
+/**
+ * Read-only subset of Context for hook callbacks.
+ * Includes context-key access (set/get) but excludes dispatch mutation methods.
+ */
+type ReadonlyContext<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> = Omit<Context<TConfig, TDeps, TState, TCommand>, "update" | "transition" | "emit" | "error" | "getWorkflowSnapshot">;
+
+type AnyMiddleware = (ctx: any, next: () => Promise<void>) => Promise<void>;
+type HandlerEntry = {
+    inlineMiddleware: AnyMiddleware[];
+    handler: AnyMiddleware;
+};
+/** Options for the {@link WorkflowRouter} constructor. */
+interface RouterOptions {
+    /** Callback invoked when a lifecycle hook throws. Defaults to `console.error`. */
+    onHookError?: (error: unknown) => void;
+    /** Wrap deps in a Proxy to catch dependency errors. Defaults to `true`. */
+    wrapDeps?: boolean;
+}
+declare class StateBuilder<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig>> {
+    /** @internal */ readonly middleware: AnyMiddleware[];
+    /** @internal */ readonly handlers: Map<string, HandlerEntry>;
+    constructor();
+    on<C extends CommandNames<TConfig>>(command: C, handler: (ctx: Context<TConfig, TDeps, TState, C>) => void | Promise<void>): this;
+    on<C extends CommandNames<TConfig>>(command: C, ...fns: [...AnyMiddleware[], (ctx: Context<TConfig, TDeps, TState, C>) => void | Promise<void>]): this;
+    use(middleware: (ctx: Context<TConfig, TDeps, TState>, next: () => Promise<void>) => Promise<void>): this;
+}
+/**
+ * Routes commands to handlers based on workflow state.
+ *
+ * Supports global middleware, state-scoped middleware, inline middleware,
+ * wildcard handlers, and multi-state handlers.
+ */
+declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
+    readonly definition: WorkflowDefinition<TConfig>;
+    private readonly deps;
+    private globalMiddleware;
+    private singleStateBuilders;
+    private multiStateBuilders;
+    private wildcardHandlers;
+    private hookRegistry;
+    private readonly onHookError;
+    private readonly wrapDeps;
+    /**
+     * @param definition - The workflow definition describing states, commands, events, and errors
+     * @param deps - Dependencies injected into every handler context
+     * @param options - Router configuration options
+     */
+    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps, options?: RouterOptions);
+    /**
+     * Adds global middleware, merges another router, or applies a plugin.
+     * @param arg - A middleware function, another {@link WorkflowRouter} to merge, or a {@link Plugin}
+     */
+    use(arg: ((ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>) | WorkflowRouter<TConfig, TDeps> | Plugin<TConfig, TDeps> | GenericPlugin): this;
+    private merge;
+    private mergeStateBuilders;
+    /**
+     * Registers handlers for one or more states.
+     * @param name - A state name or array of state names to register handlers for
+     * @param setup - Callback that receives a state builder to register commands and middleware
+     */
+    state<P extends StateNames<TConfig> | readonly StateNames<TConfig>[]>(name: P, setup: (state: StateBuilder<TConfig, TDeps, P extends readonly (infer S)[] ? S & StateNames<TConfig> : P & StateNames<TConfig>>) => void): this;
+    /**
+     * Registers a lifecycle hook callback.
+     * @param event - The lifecycle event name
+     * @param callback - The callback to invoke when the event fires
+     */
+    on(event: "dispatch:start", callback: (workflow: Workflow<TConfig>, command: {
+        type: CommandNames<TConfig>;
+        payload: unknown;
+    }) => void | Promise<void>): this;
+    on(event: "dispatch:end", callback: (workflow: Workflow<TConfig>, command: {
+        type: CommandNames<TConfig>;
+        payload: unknown;
+    }, result: DispatchResult<TConfig>) => void | Promise<void>): this;
+    on(event: "pipeline:start", callback: (ctx: ReadonlyContext<TConfig, TDeps>) => void | Promise<void>): this;
+    on(event: "pipeline:end", callback: (ctx: ReadonlyContext<TConfig, TDeps>, result: DispatchResult<TConfig>) => void | Promise<void>): this;
+    on(event: "transition", callback: (from: StateNames<TConfig>, to: StateNames<TConfig>, workflow: Workflow<TConfig>) => void | Promise<void>): this;
+    on(event: "error", callback: (error: PipelineError<TConfig>, ctx: ReadonlyContext<TConfig, TDeps>) => void | Promise<void>): this;
+    on(event: "event", callback: (event: {
+        type: EventNames<TConfig>;
+        data: unknown;
+    }, workflow: Workflow<TConfig>) => void | Promise<void>): this;
+    /**
+     * Registers a wildcard handler that matches any state.
+     * @param state - Must be `"*"` to match all states
+     * @param command - The command name to handle
+     * @param handler - The terminal handler
+     */
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, handler: (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>): this;
+    /**
+     * Registers a wildcard handler that matches any state, with inline middleware.
+     * @param state - Must be `"*"` to match all states
+     * @param command - The command name to handle
+     * @param fns - Inline middleware followed by the terminal handler
+     */
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
+        ...AnyMiddleware[],
+        (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>
+    ]): this;
+    /**
+     * Dispatches a command to the appropriate handler and returns the result.
+     * @param workflow - The current workflow instance to dispatch against
+     * @param command - The command with its type and payload
+     * @returns A {@link DispatchResult} indicating success or failure with the updated workflow and events
+     */
+    dispatch(workflow: Workflow<TConfig>, command: {
+        type: CommandNames<TConfig>;
+        payload: unknown;
+    }): Promise<DispatchResult<TConfig>>;
+    private executePipeline;
+}
+
+declare const PLUGIN_SYMBOL: unique symbol;
+/** A branded plugin function that can be passed to {@link WorkflowRouter.use}. */
+type Plugin<TConfig extends WorkflowConfig, TDeps> = ((router: WorkflowRouter<TConfig, TDeps>) => void) & {
+    readonly [PLUGIN_SYMBOL]: true;
+};
+/**
+ * Brands a function as a Ryte plugin for use with {@link WorkflowRouter.use}.
+ *
+ * @param fn - A function that configures a router (adds handlers, middleware, hooks)
+ * @returns A branded {@link Plugin} function
+ */
+declare function definePlugin<TConfig extends WorkflowConfig, TDeps>(fn: (router: WorkflowRouter<TConfig, TDeps>) => void): Plugin<TConfig, TDeps>;
+/**
+ * Checks whether a value is a branded Ryte plugin.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a {@link Plugin}
+ */
+/** A plugin that works with any router, regardless of config or deps. */
+type GenericPlugin = Plugin<any, any>;
+/**
+ * Creates a plugin that works with any router without requiring explicit type parameters.
+ * Use this for cross-cutting concerns (logging, tracing, delay) that don't reference
+ * specific states, commands, or events.
+ *
+ * @param fn - A function that configures a router (adds hooks, middleware)
+ * @returns A branded {@link GenericPlugin} function
+ */
+declare function defineGenericPlugin(fn: (router: WorkflowRouter<any, any>) => void): GenericPlugin;
+/**
+ * Checks whether a value is a branded Ryte plugin.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a {@link Plugin}
+ */
+declare function isPlugin(value: unknown): value is Plugin<WorkflowConfig, unknown>;
+
+export { type Context as C, type GenericPlugin as G, type Plugin as P, type ReadonlyContext as R, type WorkflowDefinition as W, type ContextKey as a, type RouterOptions as b, WorkflowRouter as c, createKey as d, defineGenericPlugin as e, definePlugin as f, defineWorkflow as g, isPlugin as i };

package/dist/plugin-DHS8yUmS.d.cts

@@ -0,0 +1,339 @@
+import { W as WorkflowConfig, S as StateNames, h as StateData, j as WorkflowOf, i as Workflow, a as WorkflowSnapshot, V as ValidationError, k as WorkflowConfigInput, C as CommandNames, b as CommandPayload, g as EventNames, f as EventData, E as ErrorCodes, e as ErrorData, D as DispatchResult, P as PipelineError } from './snapshot-D5iZubCz.cjs';
+import { ZodType, z } from 'zod';
+
+/**
+ * The result of {@link defineWorkflow} — holds schemas and creates workflow instances.
+ */
+interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
+    /** The raw Zod schema configuration. */
+    readonly config: TConfig;
+    /** The workflow definition name. */
+    readonly name: string;
+    /**
+     * Creates a new workflow instance in a given initial state.
+     *
+     * @param id - Unique identifier for this workflow instance
+     * @param config - Object containing `initialState` and the corresponding `data`
+     * @returns A {@link WorkflowOf} narrowed to the initial state
+     */
+    createWorkflow<S extends StateNames<TConfig>>(id: string, config: {
+        initialState: S;
+        data: StateData<TConfig, S>;
+    }): WorkflowOf<TConfig, S>;
+    /**
+     * Returns the Zod schema for a given state name.
+     *
+     * @param stateName - The state name to look up
+     * @throws If the state name is not found in the config
+     */
+    getStateSchema(stateName: string): ZodType;
+    /**
+     * Returns the Zod schema for a given command name.
+     *
+     * @param commandName - The command name to look up
+     * @throws If the command name is not found in the config
+     */
+    getCommandSchema(commandName: string): ZodType;
+    /**
+     * Returns the Zod schema for a given event name.
+     *
+     * @param eventName - The event name to look up
+     * @throws If the event name is not found in the config
+     */
+    getEventSchema(eventName: string): ZodType;
+    /**
+     * Returns the Zod schema for a given error code.
+     *
+     * @param errorCode - The error code to look up
+     * @throws If the error code is not found in the config
+     */
+    getErrorSchema(errorCode: string): ZodType;
+    /**
+     * Returns `true` if the given state name exists in the config.
+     *
+     * @param stateName - The state name to check
+     */
+    hasState(stateName: string): boolean;
+    /**
+     * Returns `true` if the given command name exists in the config.
+     */
+    hasCommand(commandName: string): boolean;
+    /**
+     * Returns `true` if the given event name exists in the config.
+     */
+    hasEvent(eventName: string): boolean;
+    /**
+     * Serializes a workflow instance into a plain, JSON-safe snapshot.
+     *
+     * @param workflow - The workflow instance to serialize
+     * @returns A {@link WorkflowSnapshot} representing the current state
+     */
+    serialize(workflow: Workflow<TConfig>): WorkflowSnapshot<TConfig>;
+    /**
+     * Deserializes a workflow instance from a plain snapshot, validating the state data.
+     *
+     * @param snapshot - The snapshot to deserialize from
+     * @returns A result object: `{ ok: true, workflow }` or `{ ok: false, error }`
+     */
+    deserialize(snapshot: WorkflowSnapshot<TConfig>): {
+        ok: true;
+        workflow: Workflow<TConfig>;
+    } | {
+        ok: false;
+        error: ValidationError;
+    };
+}
+/**
+ * Creates a workflow definition from a name and Zod schema configuration.
+ *
+ * @param name - Unique name for this workflow type
+ * @param config - Object with `states`, `commands`, `events`, `errors` — each a record of Zod schemas
+ * @returns A {@link WorkflowDefinition} with methods for creating instances and accessing schemas
+ */
+declare function defineWorkflow<const TConfig extends WorkflowConfigInput>(name: string, config: TConfig): WorkflowDefinition<TConfig & {
+    _resolved: {
+        states: {
+            [K in keyof TConfig["states"]]: z.infer<TConfig["states"][K]>;
+        };
+        commands: {
+            [K in keyof TConfig["commands"]]: z.infer<TConfig["commands"][K]>;
+        };
+        events: {
+            [K in keyof TConfig["events"]]: z.infer<TConfig["events"][K]>;
+        };
+        errors: {
+            [K in keyof TConfig["errors"]]: z.infer<TConfig["errors"][K]>;
+        };
+    };
+}>;
+
+/** A phantom-typed key for type-safe middleware state storage via {@link Context.set} and {@link Context.get}. */
+interface ContextKey<T> {
+    /** @internal Phantom type brand — not used at runtime. */
+    readonly _phantom: T;
+    /** Internal symbol providing uniqueness. */
+    readonly id: symbol;
+}
+/**
+ * Creates a unique typed key for storing and retrieving values in context.
+ *
+ * @param name - Debug label (uniqueness comes from an internal `Symbol`)
+ * @returns A {@link ContextKey} for use with `ctx.set()`, `ctx.get()`, and `ctx.getOrNull()`
+ */
+declare function createKey<T>(name: string): ContextKey<T>;
+
+/** Mutable context flowing through the middleware pipeline during dispatch. */
+interface Context<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> {
+    /** The command being dispatched, with type and validated payload. */
+    readonly command: {
+        readonly type: TCommand;
+        readonly payload: CommandPayload<TConfig, TCommand>;
+    };
+    /** The original workflow before any mutations. */
+    readonly workflow: WorkflowOf<TConfig, TState>;
+    /** Dependencies injected via the router constructor. */
+    readonly deps: TDeps;
+    /** Current state data (reflects mutations from {@link update}). */
+    readonly data: StateData<TConfig, TState>;
+    /**
+     * Merges partial data into the current state. Validates against the state's Zod schema.
+     * @param data - Partial state data to merge
+     */
+    update(data: Partial<StateData<TConfig, TState>>): void;
+    /**
+     * Transitions the workflow to a new state with new data. Validates against the target state's Zod schema.
+     * @param target - Target state name
+     * @param data - Data for the target state
+     */
+    transition<Target extends StateNames<TConfig>>(target: Target, data: StateData<TConfig, Target>): void;
+    /**
+     * Emits a domain event. Validates event data against the event's Zod schema.
+     * @param event - Event with type and data
+     */
+    emit<E extends EventNames<TConfig>>(event: {
+        type: E;
+        data: EventData<TConfig, E>;
+    }): void;
+    /** Accumulated events emitted during this dispatch. */
+    readonly events: ReadonlyArray<{
+        type: EventNames<TConfig>;
+        data: unknown;
+    }>;
+    /**
+     * Signals a domain error. Validates error data and throws internally (caught by the router).
+     * @param err - Error with code and data
+     */
+    error<C extends ErrorCodes<TConfig>>(err: {
+        code: C;
+        data: ErrorData<TConfig, C>;
+    }): never;
+    /**
+     * Stores a value in context-scoped middleware state.
+     * @param key - A {@link ContextKey} created via {@link createKey}
+     * @param value - The value to store
+     */
+    set<T>(key: ContextKey<T>, value: T): void;
+    /**
+     * Retrieves a value from context-scoped middleware state. Throws if not set.
+     * @param key - A {@link ContextKey} created via {@link createKey}
+     */
+    get<T>(key: ContextKey<T>): T;
+    /**
+     * Retrieves a value from context-scoped middleware state, or `undefined` if not set.
+     * @param key - A {@link ContextKey} created via {@link createKey}
+     */
+    getOrNull<T>(key: ContextKey<T>): T | undefined;
+    /** @internal — not part of the handler API */
+    getWorkflowSnapshot(): Workflow<TConfig>;
+}
+
+/**
+ * Read-only subset of Context for hook callbacks.
+ * Includes context-key access (set/get) but excludes dispatch mutation methods.
+ */
+type ReadonlyContext<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> = Omit<Context<TConfig, TDeps, TState, TCommand>, "update" | "transition" | "emit" | "error" | "getWorkflowSnapshot">;
+
+type AnyMiddleware = (ctx: any, next: () => Promise<void>) => Promise<void>;
+type HandlerEntry = {
+    inlineMiddleware: AnyMiddleware[];
+    handler: AnyMiddleware;
+};
+/** Options for the {@link WorkflowRouter} constructor. */
+interface RouterOptions {
+    /** Callback invoked when a lifecycle hook throws. Defaults to `console.error`. */
+    onHookError?: (error: unknown) => void;
+    /** Wrap deps in a Proxy to catch dependency errors. Defaults to `true`. */
+    wrapDeps?: boolean;
+}
+declare class StateBuilder<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig>> {
+    /** @internal */ readonly middleware: AnyMiddleware[];
+    /** @internal */ readonly handlers: Map<string, HandlerEntry>;
+    constructor();
+    on<C extends CommandNames<TConfig>>(command: C, handler: (ctx: Context<TConfig, TDeps, TState, C>) => void | Promise<void>): this;
+    on<C extends CommandNames<TConfig>>(command: C, ...fns: [...AnyMiddleware[], (ctx: Context<TConfig, TDeps, TState, C>) => void | Promise<void>]): this;
+    use(middleware: (ctx: Context<TConfig, TDeps, TState>, next: () => Promise<void>) => Promise<void>): this;
+}
+/**
+ * Routes commands to handlers based on workflow state.
+ *
+ * Supports global middleware, state-scoped middleware, inline middleware,
+ * wildcard handlers, and multi-state handlers.
+ */
+declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
+    readonly definition: WorkflowDefinition<TConfig>;
+    private readonly deps;
+    private globalMiddleware;
+    private singleStateBuilders;
+    private multiStateBuilders;
+    private wildcardHandlers;
+    private hookRegistry;
+    private readonly onHookError;
+    private readonly wrapDeps;
+    /**
+     * @param definition - The workflow definition describing states, commands, events, and errors
+     * @param deps - Dependencies injected into every handler context
+     * @param options - Router configuration options
+     */
+    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps, options?: RouterOptions);
+    /**
+     * Adds global middleware, merges another router, or applies a plugin.
+     * @param arg - A middleware function, another {@link WorkflowRouter} to merge, or a {@link Plugin}
+     */
+    use(arg: ((ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>) | WorkflowRouter<TConfig, TDeps> | Plugin<TConfig, TDeps> | GenericPlugin): this;
+    private merge;
+    private mergeStateBuilders;
+    /**
+     * Registers handlers for one or more states.
+     * @param name - A state name or array of state names to register handlers for
+     * @param setup - Callback that receives a state builder to register commands and middleware
+     */
+    state<P extends StateNames<TConfig> | readonly StateNames<TConfig>[]>(name: P, setup: (state: StateBuilder<TConfig, TDeps, P extends readonly (infer S)[] ? S & StateNames<TConfig> : P & StateNames<TConfig>>) => void): this;
+    /**
+     * Registers a lifecycle hook callback.
+     * @param event - The lifecycle event name
+     * @param callback - The callback to invoke when the event fires
+     */
+    on(event: "dispatch:start", callback: (workflow: Workflow<TConfig>, command: {
+        type: CommandNames<TConfig>;
+        payload: unknown;
+    }) => void | Promise<void>): this;
+    on(event: "dispatch:end", callback: (workflow: Workflow<TConfig>, command: {
+        type: CommandNames<TConfig>;
+        payload: unknown;
+    }, result: DispatchResult<TConfig>) => void | Promise<void>): this;
+    on(event: "pipeline:start", callback: (ctx: ReadonlyContext<TConfig, TDeps>) => void | Promise<void>): this;
+    on(event: "pipeline:end", callback: (ctx: ReadonlyContext<TConfig, TDeps>, result: DispatchResult<TConfig>) => void | Promise<void>): this;
+    on(event: "transition", callback: (from: StateNames<TConfig>, to: StateNames<TConfig>, workflow: Workflow<TConfig>) => void | Promise<void>): this;
+    on(event: "error", callback: (error: PipelineError<TConfig>, ctx: ReadonlyContext<TConfig, TDeps>) => void | Promise<void>): this;
+    on(event: "event", callback: (event: {
+        type: EventNames<TConfig>;
+        data: unknown;
+    }, workflow: Workflow<TConfig>) => void | Promise<void>): this;
+    /**
+     * Registers a wildcard handler that matches any state.
+     * @param state - Must be `"*"` to match all states
+     * @param command - The command name to handle
+     * @param handler - The terminal handler
+     */
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, handler: (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>): this;
+    /**
+     * Registers a wildcard handler that matches any state, with inline middleware.
+     * @param state - Must be `"*"` to match all states
+     * @param command - The command name to handle
+     * @param fns - Inline middleware followed by the terminal handler
+     */
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
+        ...AnyMiddleware[],
+        (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>
+    ]): this;
+    /**
+     * Dispatches a command to the appropriate handler and returns the result.
+     * @param workflow - The current workflow instance to dispatch against
+     * @param command - The command with its type and payload
+     * @returns A {@link DispatchResult} indicating success or failure with the updated workflow and events
+     */
+    dispatch(workflow: Workflow<TConfig>, command: {
+        type: CommandNames<TConfig>;
+        payload: unknown;
+    }): Promise<DispatchResult<TConfig>>;
+    private executePipeline;
+}
+
+declare const PLUGIN_SYMBOL: unique symbol;
+/** A branded plugin function that can be passed to {@link WorkflowRouter.use}. */
+type Plugin<TConfig extends WorkflowConfig, TDeps> = ((router: WorkflowRouter<TConfig, TDeps>) => void) & {
+    readonly [PLUGIN_SYMBOL]: true;
+};
+/**
+ * Brands a function as a Ryte plugin for use with {@link WorkflowRouter.use}.
+ *
+ * @param fn - A function that configures a router (adds handlers, middleware, hooks)
+ * @returns A branded {@link Plugin} function
+ */
+declare function definePlugin<TConfig extends WorkflowConfig, TDeps>(fn: (router: WorkflowRouter<TConfig, TDeps>) => void): Plugin<TConfig, TDeps>;
+/**
+ * Checks whether a value is a branded Ryte plugin.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a {@link Plugin}
+ */
+/** A plugin that works with any router, regardless of config or deps. */
+type GenericPlugin = Plugin<any, any>;
+/**
+ * Creates a plugin that works with any router without requiring explicit type parameters.
+ * Use this for cross-cutting concerns (logging, tracing, delay) that don't reference
+ * specific states, commands, or events.
+ *
+ * @param fn - A function that configures a router (adds hooks, middleware)
+ * @returns A branded {@link GenericPlugin} function
+ */
+declare function defineGenericPlugin(fn: (router: WorkflowRouter<any, any>) => void): GenericPlugin;
+/**
+ * Checks whether a value is a branded Ryte plugin.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a {@link Plugin}
+ */
+declare function isPlugin(value: unknown): value is Plugin<WorkflowConfig, unknown>;
+
+export { type Context as C, type GenericPlugin as G, type Plugin as P, type ReadonlyContext as R, type WorkflowDefinition as W, type ContextKey as a, type RouterOptions as b, WorkflowRouter as c, createKey as d, defineGenericPlugin as e, definePlugin as f, defineWorkflow as g, isPlugin as i };