@rytejs/core 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { ZodType, z } from 'zod';
 
 interface WorkflowConfig {
+    modelVersion?: number;
     states: Record<string, ZodType>;
     commands: Record<string, ZodType>;
     events: Record<string, ZodType>;
@@ -29,7 +30,7 @@ type Workflow<TConfig extends WorkflowConfig = WorkflowConfig> = {
 }[StateNames<TConfig>];
 type PipelineError<TConfig extends WorkflowConfig = WorkflowConfig> = {
     category: "validation";
-    source: "command" | "state" | "event" | "transition";
+    source: "command" | "state" | "event" | "transition" | "restore";
     issues: z.core.$ZodIssue[];
     message: string;
 } | {
@@ -54,9 +55,9 @@ type DispatchResult<TConfig extends WorkflowConfig = WorkflowConfig> = {
 };
 /** Thrown internally when Zod validation fails during dispatch. */
 declare class ValidationError extends Error {
-    readonly source: "command" | "state" | "event" | "transition";
+    readonly source: "command" | "state" | "event" | "transition" | "restore";
     readonly issues: z.core.$ZodIssue[];
-    constructor(source: "command" | "state" | "event" | "transition", issues: z.core.$ZodIssue[]);
+    constructor(source: "command" | "state" | "event" | "transition" | "restore", issues: z.core.$ZodIssue[]);
 }
 /** Thrown internally when a handler calls ctx.error(). Caught by the router. */
 declare class DomainErrorSignal extends Error {
@@ -65,6 +66,17 @@ declare class DomainErrorSignal extends Error {
     constructor(code: string, data: unknown);
 }
 
+/** A plain, JSON-safe representation of a workflow's state. */
+interface WorkflowSnapshot<TConfig extends WorkflowConfig = WorkflowConfig> {
+    readonly id: string;
+    readonly definitionName: string;
+    readonly state: StateNames<TConfig>;
+    readonly data: unknown;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly modelVersion: number;
+}
+
 /** The result of defineWorkflow() — holds schemas and creates workflow instances. */
 interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
     readonly config: TConfig;
@@ -78,6 +90,14 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
     getEventSchema(eventName: string): ZodType;
     getErrorSchema(errorCode: string): ZodType;
     hasState(stateName: string): boolean;
+    snapshot(workflow: Workflow<TConfig>): WorkflowSnapshot<TConfig>;
+    restore(snapshot: WorkflowSnapshot<TConfig>): {
+        ok: true;
+        workflow: Workflow<TConfig>;
+    } | {
+        ok: false;
+        error: ValidationError;
+    };
 }
 /**
  * Creates a workflow definition from a name and Zod schema configuration.
@@ -125,6 +145,9 @@ interface Context<TConfig extends WorkflowConfig, TDeps, TState extends StateNam
 /** Terminal handler function — receives fully typed context with state and command narrowing. */
 type Handler<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig>, TCommand extends CommandNames<TConfig>> = (ctx: Context<TConfig, TDeps, TState, TCommand>) => void | Promise<void>;
 
+/** The lifecycle hook event names. */
+type HookEvent = "dispatch:start" | "dispatch:end" | "transition" | "error" | "event";
+
 /**
  * Koa-style middleware function with full context narrowing via defaults.
  *
@@ -134,11 +157,20 @@ type Handler<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TC
  */
 type Middleware<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> = (ctx: Context<TConfig, TDeps, TState, TCommand>, next: () => Promise<void>) => Promise<void>;
 
+/**
+ * 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;
 };
+interface RouterOptions {
+    onHookError?: (error: unknown) => void;
+}
 declare class StateBuilder<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig>> {
     /** @internal */ readonly middleware: AnyMiddleware[];
     /** @internal */ readonly handlers: Map<string, HandlerEntry>;
@@ -158,13 +190,26 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     private singleStateBuilders;
     private multiStateBuilders;
     private wildcardHandlers;
-    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps);
-    /** Adds global middleware that wraps all dispatches. */
-    use(middleware: (ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>): this;
+    private hookRegistry;
+    private readonly onHookError;
+    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps, options?: RouterOptions);
+    /** Adds global middleware, merges another router, or applies a plugin. */
+    use(arg: ((ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>) | WorkflowRouter<TConfig, TDeps> | Plugin<TConfig, TDeps>): this;
+    private merge;
+    private mergeStateBuilders;
     /** Registers handlers for one or more states. */
     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. */
+    on(event: "dispatch:start", callback: (ctx: ReadonlyContext<TConfig, TDeps>) => void | Promise<void>): this;
+    on(event: "dispatch: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. */
-    on<C extends CommandNames<TConfig>>(_state: "*", command: C, ...fns: [
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
         ...AnyMiddleware[],
         (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>
     ]): this;
@@ -175,4 +220,14 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     }): Promise<DispatchResult<TConfig>>;
 }
 
-export { type CommandNames, type CommandPayload, type Context, type ContextKey, type DispatchResult, DomainErrorSignal, type ErrorCodes, type ErrorData, type EventData, type EventNames, type Handler, type Middleware, type PipelineError, type StateData, type StateNames, ValidationError, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowOf, WorkflowRouter, createKey, defineWorkflow };
+declare const PLUGIN_SYMBOL: unique symbol;
+/** A branded plugin function that can be passed to router.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 router.use(). */
+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. */
+declare function isPlugin(value: unknown): value is Plugin<WorkflowConfig, unknown>;
+
+export { type CommandNames, type CommandPayload, type Context, type ContextKey, type DispatchResult, DomainErrorSignal, type ErrorCodes, type ErrorData, type EventData, type EventNames, type Handler, type HookEvent, type Middleware, type PipelineError, type Plugin, type ReadonlyContext, type RouterOptions, type StateData, type StateNames, ValidationError, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowOf, WorkflowRouter, type WorkflowSnapshot, createKey, definePlugin, defineWorkflow, isPlugin };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ZodType, z } from 'zod';
 
 interface WorkflowConfig {
+    modelVersion?: number;
     states: Record<string, ZodType>;
     commands: Record<string, ZodType>;
     events: Record<string, ZodType>;
@@ -29,7 +30,7 @@ type Workflow<TConfig extends WorkflowConfig = WorkflowConfig> = {
 }[StateNames<TConfig>];
 type PipelineError<TConfig extends WorkflowConfig = WorkflowConfig> = {
     category: "validation";
-    source: "command" | "state" | "event" | "transition";
+    source: "command" | "state" | "event" | "transition" | "restore";
     issues: z.core.$ZodIssue[];
     message: string;
 } | {
@@ -54,9 +55,9 @@ type DispatchResult<TConfig extends WorkflowConfig = WorkflowConfig> = {
 };
 /** Thrown internally when Zod validation fails during dispatch. */
 declare class ValidationError extends Error {
-    readonly source: "command" | "state" | "event" | "transition";
+    readonly source: "command" | "state" | "event" | "transition" | "restore";
     readonly issues: z.core.$ZodIssue[];
-    constructor(source: "command" | "state" | "event" | "transition", issues: z.core.$ZodIssue[]);
+    constructor(source: "command" | "state" | "event" | "transition" | "restore", issues: z.core.$ZodIssue[]);
 }
 /** Thrown internally when a handler calls ctx.error(). Caught by the router. */
 declare class DomainErrorSignal extends Error {
@@ -65,6 +66,17 @@ declare class DomainErrorSignal extends Error {
     constructor(code: string, data: unknown);
 }
 
+/** A plain, JSON-safe representation of a workflow's state. */
+interface WorkflowSnapshot<TConfig extends WorkflowConfig = WorkflowConfig> {
+    readonly id: string;
+    readonly definitionName: string;
+    readonly state: StateNames<TConfig>;
+    readonly data: unknown;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly modelVersion: number;
+}
+
 /** The result of defineWorkflow() — holds schemas and creates workflow instances. */
 interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
     readonly config: TConfig;
@@ -78,6 +90,14 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
     getEventSchema(eventName: string): ZodType;
     getErrorSchema(errorCode: string): ZodType;
     hasState(stateName: string): boolean;
+    snapshot(workflow: Workflow<TConfig>): WorkflowSnapshot<TConfig>;
+    restore(snapshot: WorkflowSnapshot<TConfig>): {
+        ok: true;
+        workflow: Workflow<TConfig>;
+    } | {
+        ok: false;
+        error: ValidationError;
+    };
 }
 /**
  * Creates a workflow definition from a name and Zod schema configuration.
@@ -125,6 +145,9 @@ interface Context<TConfig extends WorkflowConfig, TDeps, TState extends StateNam
 /** Terminal handler function — receives fully typed context with state and command narrowing. */
 type Handler<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig>, TCommand extends CommandNames<TConfig>> = (ctx: Context<TConfig, TDeps, TState, TCommand>) => void | Promise<void>;
 
+/** The lifecycle hook event names. */
+type HookEvent = "dispatch:start" | "dispatch:end" | "transition" | "error" | "event";
+
 /**
  * Koa-style middleware function with full context narrowing via defaults.
  *
@@ -134,11 +157,20 @@ type Handler<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TC
  */
 type Middleware<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> = (ctx: Context<TConfig, TDeps, TState, TCommand>, next: () => Promise<void>) => Promise<void>;
 
+/**
+ * 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;
 };
+interface RouterOptions {
+    onHookError?: (error: unknown) => void;
+}
 declare class StateBuilder<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig>> {
     /** @internal */ readonly middleware: AnyMiddleware[];
     /** @internal */ readonly handlers: Map<string, HandlerEntry>;
@@ -158,13 +190,26 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     private singleStateBuilders;
     private multiStateBuilders;
     private wildcardHandlers;
-    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps);
-    /** Adds global middleware that wraps all dispatches. */
-    use(middleware: (ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>): this;
+    private hookRegistry;
+    private readonly onHookError;
+    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps, options?: RouterOptions);
+    /** Adds global middleware, merges another router, or applies a plugin. */
+    use(arg: ((ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>) | WorkflowRouter<TConfig, TDeps> | Plugin<TConfig, TDeps>): this;
+    private merge;
+    private mergeStateBuilders;
     /** Registers handlers for one or more states. */
     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. */
+    on(event: "dispatch:start", callback: (ctx: ReadonlyContext<TConfig, TDeps>) => void | Promise<void>): this;
+    on(event: "dispatch: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. */
-    on<C extends CommandNames<TConfig>>(_state: "*", command: C, ...fns: [
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
         ...AnyMiddleware[],
         (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>
     ]): this;
@@ -175,4 +220,14 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     }): Promise<DispatchResult<TConfig>>;
 }
 
-export { type CommandNames, type CommandPayload, type Context, type ContextKey, type DispatchResult, DomainErrorSignal, type ErrorCodes, type ErrorData, type EventData, type EventNames, type Handler, type Middleware, type PipelineError, type StateData, type StateNames, ValidationError, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowOf, WorkflowRouter, createKey, defineWorkflow };
+declare const PLUGIN_SYMBOL: unique symbol;
+/** A branded plugin function that can be passed to router.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 router.use(). */
+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. */
+declare function isPlugin(value: unknown): value is Plugin<WorkflowConfig, unknown>;
+
+export { type CommandNames, type CommandPayload, type Context, type ContextKey, type DispatchResult, DomainErrorSignal, type ErrorCodes, type ErrorData, type EventData, type EventNames, type Handler, type HookEvent, type Middleware, type PipelineError, type Plugin, type ReadonlyContext, type RouterOptions, type StateData, type StateNames, ValidationError, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowOf, WorkflowRouter, type WorkflowSnapshot, createKey, definePlugin, defineWorkflow, isPlugin };

package/dist/index.js

@@ -1,3 +1,21 @@
+// src/types.ts
+var ValidationError = class extends Error {
+  constructor(source, issues) {
+    super(`Validation failed (${source}): ${issues.map((i) => i.message).join(", ")}`);
+    this.source = source;
+    this.issues = issues;
+    this.name = "ValidationError";
+  }
+};
+var DomainErrorSignal = class extends Error {
+  constructor(code, data) {
+    super(`Domain error: ${code}`);
+    this.code = code;
+    this.data = data;
+    this.name = "DomainErrorSignal";
+  }
+};
+
 // src/definition.ts
 function defineWorkflow(name, config) {
   return {
@@ -44,6 +62,51 @@ function defineWorkflow(name, config) {
     },
     hasState(stateName) {
       return stateName in config.states;
+    },
+    snapshot(workflow) {
+      return {
+        id: workflow.id,
+        definitionName: name,
+        state: workflow.state,
+        data: workflow.data,
+        createdAt: workflow.createdAt.toISOString(),
+        updatedAt: workflow.updatedAt.toISOString(),
+        modelVersion: config.modelVersion ?? 1
+      };
+    },
+    restore(snap) {
+      const stateSchema = config.states[snap.state];
+      if (!stateSchema) {
+        return {
+          ok: false,
+          error: new ValidationError("restore", [
+            {
+              code: "custom",
+              message: `Unknown state: ${snap.state}`,
+              input: snap.state,
+              path: ["state"]
+            }
+          ])
+        };
+      }
+      const result = stateSchema.safeParse(snap.data);
+      if (!result.success) {
+        return {
+          ok: false,
+          error: new ValidationError("restore", result.error.issues)
+        };
+      }
+      return {
+        ok: true,
+        workflow: {
+          id: snap.id,
+          definitionName: snap.definitionName,
+          state: snap.state,
+          data: result.data,
+          createdAt: new Date(snap.createdAt),
+          updatedAt: new Date(snap.updatedAt)
+        }
+      };
     }
   };
 }
@@ -53,6 +116,17 @@ function createKey(name) {
   return { id: Symbol(name) };
 }
 
+// src/plugin.ts
+var PLUGIN_SYMBOL = /* @__PURE__ */ Symbol.for("ryte:plugin");
+function definePlugin(fn) {
+  const plugin = fn;
+  Object.defineProperty(plugin, PLUGIN_SYMBOL, { value: true, writable: false });
+  return plugin;
+}
+function isPlugin(value) {
+  return typeof value === "function" && PLUGIN_SYMBOL in value;
+}
+
 // src/compose.ts
 function compose(middleware) {
   return async (ctx) => {
@@ -68,24 +142,6 @@ function compose(middleware) {
   };
 }
 
-// src/types.ts
-var ValidationError = class extends Error {
-  constructor(source, issues) {
-    super(`Validation failed (${source}): ${issues.map((i) => i.message).join(", ")}`);
-    this.source = source;
-    this.issues = issues;
-    this.name = "ValidationError";
-  }
-};
-var DomainErrorSignal = class extends Error {
-  constructor(code, data) {
-    super(`Domain error: ${code}`);
-    this.code = code;
-    this.data = data;
-    this.name = "DomainErrorSignal";
-  }
-};
-
 // src/context.ts
 function createContext(definition, originalWorkflow, command, deps) {
   let mutableState = originalWorkflow.state;
@@ -169,6 +225,46 @@ function createContext(definition, originalWorkflow, command, deps) {
   return ctx;
 }
 
+// src/hooks.ts
+var HOOK_EVENTS = /* @__PURE__ */ new Set([
+  "dispatch:start",
+  "dispatch:end",
+  "transition",
+  "error",
+  "event"
+]);
+var HookRegistry = class {
+  // biome-ignore lint/complexity/noBannedTypes: callbacks have varying signatures per hook event
+  hooks = /* @__PURE__ */ new Map();
+  /** Register a callback for a hook event. */
+  // biome-ignore lint/complexity/noBannedTypes: callbacks have varying signatures per hook event
+  add(event, callback) {
+    const existing = this.hooks.get(event) ?? [];
+    existing.push(callback);
+    this.hooks.set(event, existing);
+  }
+  /** Emit a hook event, calling all registered callbacks. Errors are caught and forwarded. */
+  async emit(event, onError, ...args) {
+    const callbacks = this.hooks.get(event);
+    if (!callbacks) return;
+    for (const cb of callbacks) {
+      try {
+        await cb(...args);
+      } catch (err) {
+        onError(err);
+      }
+    }
+  }
+  /** Merge another registry's hooks into this one (used by composable routers). */
+  merge(other) {
+    for (const [event, callbacks] of other.hooks) {
+      const existing = this.hooks.get(event) ?? [];
+      existing.push(...callbacks);
+      this.hooks.set(event, existing);
+    }
+  }
+};
+
 // src/router.ts
 var StateBuilder = class {
   /** @internal */
@@ -190,20 +286,68 @@ var StateBuilder = class {
     return this;
   }
 };
-var WorkflowRouter = class {
-  constructor(definition, deps = {}) {
+var WorkflowRouter = class _WorkflowRouter {
+  constructor(definition, deps = {}, options = {}) {
     this.definition = definition;
     this.deps = deps;
+    this.onHookError = options.onHookError ?? console.error;
   }
   globalMiddleware = [];
+  // biome-ignore lint/suspicious/noExplicitAny: type erasure — builders store handlers for different state types
   singleStateBuilders = /* @__PURE__ */ new Map();
+  // biome-ignore lint/suspicious/noExplicitAny: type erasure — builders store handlers for different state types
   multiStateBuilders = /* @__PURE__ */ new Map();
   wildcardHandlers = /* @__PURE__ */ new Map();
-  /** Adds global middleware that wraps all dispatches. */
-  use(middleware) {
-    this.globalMiddleware.push(middleware);
+  hookRegistry = new HookRegistry();
+  onHookError;
+  /** Adds global middleware, merges another router, or applies a plugin. */
+  use(arg) {
+    if (arg instanceof _WorkflowRouter) {
+      this.merge(arg);
+    } else if (isPlugin(arg)) {
+      arg(this);
+    } else {
+      this.globalMiddleware.push(arg);
+    }
     return this;
   }
+  merge(child) {
+    if (child.definition !== this.definition) {
+      throw new Error(
+        `Cannot merge router for '${child.definition.name}' into router for '${this.definition.name}': definition mismatch`
+      );
+    }
+    this.globalMiddleware.push(...child.globalMiddleware);
+    this.mergeStateBuilders(this.singleStateBuilders, child.singleStateBuilders);
+    this.mergeStateBuilders(this.multiStateBuilders, child.multiStateBuilders);
+    for (const [command, entry] of child.wildcardHandlers) {
+      if (!this.wildcardHandlers.has(command)) {
+        this.wildcardHandlers.set(command, {
+          inlineMiddleware: [...entry.inlineMiddleware],
+          handler: entry.handler
+        });
+      }
+    }
+    this.hookRegistry.merge(child.hookRegistry);
+  }
+  mergeStateBuilders(target, source) {
+    for (const [stateName, childBuilder] of source) {
+      let parentBuilder = target.get(stateName);
+      if (!parentBuilder) {
+        parentBuilder = new StateBuilder();
+        target.set(stateName, parentBuilder);
+      }
+      for (const [command, entry] of childBuilder.handlers) {
+        if (!parentBuilder.handlers.has(command)) {
+          parentBuilder.handlers.set(command, {
+            inlineMiddleware: [...entry.inlineMiddleware],
+            handler: entry.handler
+          });
+        }
+      }
+      parentBuilder.middleware.push(...childBuilder.middleware);
+    }
+  }
   /** Registers handlers for one or more states. */
   state(name, setup) {
     const names = Array.isArray(name) ? name : [name];
@@ -219,19 +363,29 @@ var WorkflowRouter = class {
     }
     return this;
   }
-  /** Registers a wildcard handler that matches any state. */
-  on(_state, command, ...fns) {
-    if (fns.length === 0) throw new Error("on() requires at least a handler");
-    const handler = fns.pop();
-    const inlineMiddleware = fns;
-    const wrappedHandler = async (ctx, _next) => {
-      await handler(ctx);
-    };
-    this.wildcardHandlers.set(command, {
-      inlineMiddleware,
-      handler: wrappedHandler
-    });
-    return this;
+  // biome-ignore lint/suspicious/noExplicitAny: implementation signature must be loose to handle all overloads
+  on(...args) {
+    const first = args[0];
+    if (HOOK_EVENTS.has(first)) {
+      this.hookRegistry.add(first, args[1]);
+      return this;
+    }
+    if (first === "*") {
+      const command = args[1];
+      const fns = args.slice(2);
+      if (fns.length === 0) throw new Error("on() requires at least a handler");
+      const handler = fns.pop();
+      const inlineMiddleware = fns;
+      const wrappedHandler = async (ctx, _next) => {
+        await handler(ctx);
+      };
+      this.wildcardHandlers.set(command, {
+        inlineMiddleware,
+        handler: wrappedHandler
+      });
+      return this;
+    }
+    throw new Error(`Unknown event or state: ${first}`);
   }
   /** Dispatches a command to the appropriate handler and returns the result. */
   async dispatch(workflow, command) {
@@ -305,17 +459,35 @@ var WorkflowRouter = class {
       validatedCommand,
       this.deps
     );
+    await this.hookRegistry.emit("dispatch:start", this.onHookError, ctx);
     try {
       const composed = compose(chain);
       await composed(ctx);
-      return {
+      const result = {
         ok: true,
         workflow: ctx.getWorkflowSnapshot(),
         events: [...ctx.events]
       };
+      if (result.ok && result.workflow.state !== workflow.state) {
+        await this.hookRegistry.emit(
+          "transition",
+          this.onHookError,
+          workflow.state,
+          result.workflow.state,
+          result.workflow
+        );
+      }
+      if (result.ok) {
+        for (const event of result.events) {
+          await this.hookRegistry.emit("event", this.onHookError, event, result.workflow);
+        }
+      }
+      await this.hookRegistry.emit("dispatch:end", this.onHookError, ctx, result);
+      return result;
     } catch (err) {
+      let result;
       if (err instanceof DomainErrorSignal) {
-        return {
+        result = {
           ok: false,
           error: {
             category: "domain",
@@ -323,9 +495,8 @@ var WorkflowRouter = class {
             data: err.data
           }
         };
-      }
-      if (err instanceof ValidationError) {
-        return {
+      } else if (err instanceof ValidationError) {
+        result = {
           ok: false,
           error: {
             category: "validation",
@@ -334,8 +505,12 @@ var WorkflowRouter = class {
             message: err.message
           }
         };
+      } else {
+        throw err;
       }
-      throw err;
+      await this.hookRegistry.emit("error", this.onHookError, result.error, ctx);
+      await this.hookRegistry.emit("dispatch:end", this.onHookError, ctx, result);
+      return result;
     }
   }
 };
@@ -344,6 +519,8 @@ export {
   ValidationError,
   WorkflowRouter,
   createKey,
-  defineWorkflow
+  definePlugin,
+  defineWorkflow,
+  isPlugin
 };
 //# sourceMappingURL=index.js.map