@doeixd/machine 0.0.13 → 0.0.18

package/src/middleware.ts

@@ -57,12 +57,6 @@ export interface MiddlewareError<C extends object> {
  * All hooks are optional - provide only the ones you need.
  * @template C - The context object type
  */
-/**
- * Strongly typed middleware hooks with precise context and return types.
- * All hooks are optional - provide only the ones you need.
- *
- * @template C - The machine context type for precise type inference
- */
 export interface MiddlewareHooks<C extends object> {
   /**
    * Called before a transition executes.
@@ -70,15 +64,6 @@ export interface MiddlewareHooks<C extends object> {
    *
    * @param ctx - Transition context with machine state and transition details
    * @returns void to continue, CANCEL to abort silently, or Promise for async validation
-   *
-   * @example
-   * ```typescript
-   * before: ({ transitionName, args, context }) => {
-   *   if (transitionName === 'withdraw' && context.balance < args[0]) {
-   *     throw new Error('Insufficient funds');
-   *   }
-   * }
-   * ```
    */
   before?: (ctx: MiddlewareContext<C>) => void | typeof CANCEL | Promise<void | typeof CANCEL>;
 
@@ -88,1112 +73,541 @@ export interface MiddlewareHooks<C extends object> {
    * Cannot prevent the transition (it already happened).
    *
    * @param result - Transition result with before/after contexts and transition details
-   *
-   * @example
-   * ```typescript
-   * after: ({ transitionName, before, after }) => {
-   *   console.log(`${transitionName}: ${before.count} -> ${after.count}`);
-   * }
-   * ```
    */
   after?: (result: MiddlewareResult<C>) => void | Promise<void>;
 
   /**
-   * Called if a transition throws an error.
-   * Can be used for error logging, Sentry reporting, fallback states, etc.
-   *
-   * @param error - Error context with transition details and the thrown error
-   * @returns
-   * - void/undefined/null: Re-throw the original error (default)
-   * - BaseMachine: Use this as fallback state instead of throwing
-   * - throw new Error: Transform the error
-   *
-   * @example
-   * ```typescript
-   * error: ({ transitionName, error, context }) => {
-   *   // Log to error reporting service
-   *   reportError(error, { transitionName, context });
+   * Called when a transition throws an error.
+   * Can be used for error reporting, recovery, etc.
    *
-   *   // Return fallback state for recoverable errors
-   *   if (error.message.includes('network')) {
-   *     return createMachine({ ...context, error: 'offline' }, transitions);
-   *   }
-   * }
-   * ```
+   * @param error - Error context with transition details and error information
    */
-  error?: (error: MiddlewareError<C>) => void | null | BaseMachine<C> | Promise<void | null | BaseMachine<C>>;
+  error?: (error: MiddlewareError<C>) => void | Promise<void>;
 }
 
 /**
- * Options for middleware configuration.
+ * Options for configuring middleware behavior.
  */
 export interface MiddlewareOptions {
-  /**
-   * Execution mode for middleware hooks.
-   * - 'sync': Hooks must be synchronous, throws if hooks return Promise
-   * - 'async': Always await hooks and transition
-   * - 'auto' (default): Adaptive mode - starts synchronously, automatically handles async results if encountered
-   *
-   * Note: 'auto' mode provides the best of both worlds - zero overhead for sync transitions
-   * while seamlessly handling async ones when they occur.
-   * @default 'auto'
-   */
-  mode?: 'sync' | 'async' | 'auto';
-
-  /**
-   * Properties to exclude from middleware interception.
-   * Useful for excluding utility methods or getters.
-   * @default ['context']
-   */
-  exclude?: string[];
+  /** Whether to continue execution if a hook throws an error */
+  continueOnError?: boolean;
+  /** Whether to log errors from hooks */
+  logErrors?: boolean;
+  /** Custom error handler for hook errors */
+  onError?: (error: Error, hookName: string, ctx: any) => void;
 }
 
-// =============================================================================
-// SECTION: CANCELLATION SUPPORT
-// =============================================================================
-
 /**
- * Special symbol that can be returned from before hooks to cancel a transition.
- * When returned, the transition will not execute and the current machine state is preserved.
- *
- * @example
- * createMiddleware(machine, {
- *   before: ({ transitionName, context }) => {
- *     if (shouldCancel(context)) {
- *       return CANCEL; // Abort transition without throwing
- *     }
- *   }
- * });
+ * Symbol used to cancel a transition from a before hook.
  */
 export const CANCEL = Symbol('CANCEL');
 
 // =============================================================================
-// SECTION: UTILITY TYPES FOR AUGMENTED MACHINES
-// =============================================================================
-
-/**
- * Augmented machine type with history tracking capabilities.
- * @template M - The base machine type
- * @template C - The context type
- */
-export type WithHistory<M extends BaseMachine<any>> = M & {
-  /** Array of recorded transition history entries */
-  history: HistoryEntry[];
-  /** Clear all history entries */
-  clearHistory: () => void;
-};
-
-/**
- * Augmented machine type with snapshot tracking capabilities.
- * @template M - The base machine type
- * @template C - The context type
- */
-export type WithSnapshot<M extends BaseMachine<any>, C extends object = Context<M>> = M & {
-  /** Array of recorded context snapshots */
-  snapshots: ContextSnapshot<C>[];
-  /** Clear all snapshots */
-  clearSnapshots: () => void;
-  /** Restore machine to a previous context state */
-  restoreSnapshot: (context: C) => M;
-};
-
-/**
- * Augmented machine type with full time-travel debugging capabilities.
- * Combines both history and snapshot tracking.
- * @template M - The base machine type
- * @template C - The context type
- */
-export type WithTimeTravel<M extends BaseMachine<any>, C extends object = Context<M>> = M & {
-  /** Array of recorded transition history entries */
-  history: HistoryEntry[];
-  /** Array of recorded context snapshots */
-  snapshots: ContextSnapshot<C>[];
-  /** Clear all history and snapshots */
-  clearTimeTravel: () => void;
-  /** Restore machine to a previous context state */
-  restoreSnapshot: (context: C) => M;
-  /** Replay all transitions from a specific snapshot */
-  replayFrom: (snapshotIndex: number) => M;
-};
-
-// =============================================================================
-// SECTION: CORE MIDDLEWARE FUNCTION
+// SECTION: CORE MIDDLEWARE FUNCTIONS
 // =============================================================================
 
 /**
- * Wraps a machine with middleware hooks that intercept all transitions.
- * Uses direct property wrapping for optimal performance (3x faster than Proxy).
- *
- * The middleware preserves:
- * - Full type safety (return type matches input machine)
- * - `this` binding for transitions
- * - Async and sync transitions
- * - Machine immutability
+ * Creates a middleware function that wraps machine transitions with hooks.
  *
  * @template M - The machine type
- * @param machine - The machine to wrap with middleware
- * @param hooks - Middleware hooks (before, after, error)
- * @param options - Configuration options
+ * @param machine - The machine to instrument
+ * @param hooks - Middleware hooks to execute
+ * @param options - Middleware configuration options
  * @returns A new machine with middleware applied
- *
- * @example
- * const instrumented = createMiddleware(counter, {
- *   before: ({ transitionName, context, args }) => {
- *     console.log(`→ ${transitionName}`, args);
- *   },
- *   after: ({ transitionName, prevContext, nextContext }) => {
- *     console.log(`✓ ${transitionName}`, nextContext);
- *   },
- *   error: ({ transitionName, error }) => {
- *     console.error(`✗ ${transitionName}:`, error);
- *   }
- * });
  */
 export function createMiddleware<M extends BaseMachine<any>>(
   machine: M,
   hooks: MiddlewareHooks<Context<M>>,
   options: MiddlewareOptions = {}
 ): M {
-  const { mode = 'auto', exclude = ['context'] } = options;
+  const { continueOnError = false, logErrors = true, onError } = options;
 
-  // Build wrapped machine object with direct property iteration
-  const wrapped: any = {};
+  // Create a wrapped machine that intercepts all transition calls
+  const wrappedMachine: any = { ...machine };
 
-  // Copy all properties and wrap functions
+  // Copy any extra properties from the original machine (for middleware composition)
   for (const prop in machine) {
     if (!Object.prototype.hasOwnProperty.call(machine, prop)) continue;
-
-    const value = machine[prop];
-
-    // Always copy context
-    if (prop === 'context') {
-      wrapped.context = value;
-      continue;
-    }
-
-    // Skip excluded properties
-    if (exclude.includes(prop)) {
-      wrapped[prop] = value;
-      continue;
+    if (prop !== 'context' && typeof machine[prop] !== 'function') {
+      wrappedMachine[prop] = machine[prop];
     }
-
-    // Skip non-functions and private methods
-    if (typeof value !== 'function' || prop.startsWith('_')) {
-      wrapped[prop] = value;
-      continue;
-    }
-
-    // Wrap transition function
-    wrapped[prop] = createTransitionWrapper(
-      prop,
-      value,
-      machine,
-      hooks,
-      mode
-    );
   }
 
-  return wrapped as M;
-}
-
-/**
- * Creates a wrapped transition function with middleware hooks.
- * Extracted as a separate function for clarity and reusability.
- *
- * @internal
- */
-function createTransitionWrapper<M extends BaseMachine<any>>(
-  transitionName: string,
-  originalFn: Function,
-  machine: M,
-  hooks: MiddlewareHooks<Context<M>>,
-  mode: 'sync' | 'async' | 'auto'
-): Function {
-  return function wrappedTransition(this: any, ...args: any[]) {
-    // Get current context (might be different from initial if machine changed)
-    const context = machine.context;
-
-    const middlewareCtx: MiddlewareContext<Context<M>> = {
-      transitionName,
-      context,
-      args
-    };
-
-    // Helper for sync execution
-    const executeSyncTransition = () => {
-      try {
-        // Call before hook (must be sync or throw)
-        if (hooks.before) {
-          const beforeResult = hooks.before(middlewareCtx);
-          // Check for cancellation
-          if (beforeResult === CANCEL) {
-            return machine; // Return current machine unchanged
-          }
-          // If before hook returns a promise in sync mode, throw
-          if (beforeResult instanceof Promise) {
-            throw new Error(
-              `Middleware mode is 'sync' but before hook returned Promise for transition: ${transitionName}`
-            );
-          }
-        }
-
-        // Execute the actual transition
-        const result = originalFn.call(this, ...args);
-
-        // If result is async, switch to async handling
-        if (result instanceof Promise) {
-          return handleAsyncResult(result, context);
-        }
-
-        // Call after hook (must be sync or throw)
-        if (hooks.after) {
-          const middlewareResult: MiddlewareResult<Context<M>> = {
-            transitionName,
-            prevContext: context,
-            nextContext: result.context,
-            args
-          };
-          const afterResult = hooks.after(middlewareResult);
-          if (afterResult instanceof Promise) {
-            throw new Error(
-              `Middleware mode is 'sync' but after hook returned Promise for transition: ${transitionName}`
-            );
-          }
-        }
-
-        return result;
-      } catch (err) {
-        // Call error hook and check for fallback state
-        if (hooks.error) {
-          const middlewareError: MiddlewareError<Context<M>> = {
-            transitionName,
-            context,
-            args,
-            error: err as Error
-          };
-          const errorResult = hooks.error(middlewareError);
-
-          // Handle async error hook in sync mode
-          if (errorResult instanceof Promise) {
-            // Fire-and-forget for async error hooks in sync mode
-            errorResult.catch(() => {});
-            throw err; // Re-throw original error
-          }
-
-          // Check if error hook returned a fallback machine
-          if (errorResult && typeof errorResult === 'object' && 'context' in errorResult) {
-            return errorResult as M; // Return fallback state
+  // Wrap each transition function
+  for (const prop in machine) {
+    if (!Object.prototype.hasOwnProperty.call(machine, prop)) continue;
+    const value = machine[prop];
+    if (typeof value === 'function' && prop !== 'context') {
+      wrappedMachine[prop] = function (this: any, ...args: any[]) {
+        const transitionName = prop;
+        const context = wrappedMachine.context;
+
+        // Helper function to execute the transition and after hooks
+        const executeTransition = () => {
+          // 2. Execute the actual transition
+          let nextMachine: any;
+          try {
+            nextMachine = value.apply(this, args);
+          } catch (error) {
+            // 3. Execute error hooks if transition failed
+            if (hooks.error) {
+              try {
+                // Error hooks are called synchronously for now
+                hooks.error({
+                  transitionName,
+                  context,
+                  args: [...args],
+                  error: error as Error
+                });
+              } catch (hookError) {
+                if (!continueOnError) throw hookError;
+                if (logErrors) console.error(`Middleware error hook error for ${transitionName}:`, hookError);
+                onError?.(hookError as Error, 'error', { transitionName, context, args, error });
+              }
+            }
+            throw error; // Re-throw the original error
           }
-        }
 
-        // Re-throw the error
-        throw err;
-      }
-    };
+          // Check if the transition is async (returns a Promise)
+          if (nextMachine && typeof nextMachine.then === 'function') {
+            // For async transitions, we need to handle the after hooks after the promise resolves
+            const asyncResult = nextMachine.then((resolvedMachine: any) => {
+              // Execute after hooks with the resolved machine
+              if (hooks.after) {
+                try {
+                  const result = hooks.after({
+                    transitionName,
+                    prevContext: context,
+                    nextContext: resolvedMachine.context,
+                    args: [...args]
+                  });
+
+                  // Handle async after hooks
+                  if (result && typeof result.then === 'function') {
+                    return result.then(() => resolvedMachine);
+                  }
+                } catch (error) {
+                  if (!continueOnError) throw error;
+                  if (logErrors) console.error(`Middleware after hook error for ${transitionName}:`, error);
+                  onError?.(error as Error, 'after', {
+                    transitionName,
+                    prevContext: context,
+                    nextContext: resolvedMachine.context,
+                    args
+                  });
+                }
+              }
+              return resolvedMachine;
+            });
 
-    // Helper for handling async transition results
-    const handleAsyncResult = async (resultPromise: Promise<any>, ctx: any) => {
-      try {
-        const result = await resultPromise;
-
-        // Call after hook
-        if (hooks.after) {
-          const middlewareResult: MiddlewareResult<Context<M>> = {
-            transitionName,
-            prevContext: ctx,
-            nextContext: result.context,
-            args
-          };
-          await hooks.after(middlewareResult);
-        }
+            return asyncResult;
+          } else {
+            // Synchronous transition
+            // 4. Execute after hooks
+            if (hooks.after) {
+              try {
+                const result = hooks.after({
+                  transitionName,
+                  prevContext: context,
+                  nextContext: nextMachine.context,
+                  args: [...args]
+                });
+
+                // Handle async after hooks
+                if (result && typeof result === 'object' && result && 'then' in result) {
+                  return result.then(() => nextMachine).catch((error: Error) => {
+                    if (!continueOnError) throw error;
+                    if (logErrors) console.error(`Middleware after hook error for ${transitionName}:`, error);
+                    onError?.(error, 'after', {
+                      transitionName,
+                      prevContext: context,
+                      nextContext: nextMachine.context,
+                      args
+                    });
+                    return nextMachine;
+                  });
+                }
+              } catch (error) {
+                if (!continueOnError) throw error;
+                if (logErrors) console.error(`Middleware after hook error for ${transitionName}:`, error);
+                onError?.(error as Error, 'after', {
+                  transitionName,
+                  prevContext: context,
+                  nextContext: nextMachine.context,
+                  args
+                });
+              }
+            }
 
-        return result;
-      } catch (err) {
-        // Call error hook and check for fallback state
-        if (hooks.error) {
-          const middlewareError: MiddlewareError<Context<M>> = {
-            transitionName,
-            context: ctx,
-            args,
-            error: err as Error
-          };
-          const errorResult = await hooks.error(middlewareError);
-
-          // Check if error hook returned a fallback machine
-          if (errorResult && typeof errorResult === 'object' && 'context' in errorResult) {
-            return errorResult as M; // Return fallback state
+            // 5. Return the next machine state
+            return nextMachine;
           }
-        }
-
-        // Re-throw the error
-        throw err;
-      }
-    };
+        };
 
-    // Helper for fully async execution
-    const executeAsyncTransition = async () => {
-      try {
-        // Call before hook
+        // 1. Execute before hooks synchronously if possible
         if (hooks.before) {
-          const beforeResult = await hooks.before(middlewareCtx);
-          // Check for cancellation
-          if (beforeResult === CANCEL) {
-            return machine; // Return current machine unchanged
-          }
-        }
+          try {
+            const result = hooks.before({
+              transitionName,
+              context,
+              args: [...args]
+            });
 
-        // Execute the actual transition
-        const result = await originalFn.call(this, ...args);
-
-        // Call after hook
-        if (hooks.after) {
-          const middlewareResult: MiddlewareResult<Context<M>> = {
-            transitionName,
-            prevContext: context,
-            nextContext: result.context,
-            args
-          };
-          await hooks.after(middlewareResult);
-        }
+            // Handle async hooks
+            if (result && typeof result === 'object' && result && 'then' in result) {
+              // For async hooks, return a promise that executes the transition after
+              return result.then((hookResult: any) => {
+                if (hookResult === CANCEL) {
+                  return wrappedMachine;
+                }
+                return executeTransition();
+              }).catch((error: Error) => {
+                if (!continueOnError) throw error;
+                if (logErrors) console.error(`Middleware before hook error for ${transitionName}:`, error);
+                onError?.(error, 'before', { transitionName, context, args });
+                return executeTransition();
+              });
+            }
 
-        return result;
-      } catch (err) {
-        // Call error hook and check for fallback state
-        if (hooks.error) {
-          const middlewareError: MiddlewareError<Context<M>> = {
-            transitionName,
-            context,
-            args,
-            error: err as Error
-          };
-          const errorResult = await hooks.error(middlewareError);
-
-          // Check if error hook returned a fallback machine
-          if (errorResult && typeof errorResult === 'object' && 'context' in errorResult) {
-            return errorResult as M; // Return fallback state
+            // Check if transition should be cancelled
+            if (result === CANCEL) {
+              return wrappedMachine; // Return the same machine instance
+            }
+          } catch (error) {
+            if (!continueOnError) throw error;
+            if (logErrors) console.error(`Middleware before hook error for ${transitionName}:`, error);
+            onError?.(error as Error, 'before', { transitionName, context, args });
           }
-        }
-
-        // Re-throw the error
-        throw err;
-      }
-    };
-
-    // Choose execution mode
-    if (mode === 'async') {
-      // Force async execution
-      return executeAsyncTransition();
-    } else if (mode === 'sync') {
-      // Force sync execution
-      return executeSyncTransition();
-    } else {
-      // Auto mode (adaptive): Starts synchronously for zero overhead,
-      // but automatically switches to async if the transition returns a Promise.
-      // This provides optimal performance for sync transitions while
-      // seamlessly handling async ones when they occur.
-      return executeSyncTransition();
+        };
     }
-  };
-}
+  }
 
-// =============================================================================
-// SECTION: COMPOSABLE MIDDLEWARE HELPERS
-// =============================================================================
+  return wrappedMachine;
+}
 
 /**
- * Logging middleware that logs transition calls and results to console.
- * Useful for debugging and development.
+ * Creates a simple logging middleware that logs all transitions.
  *
  * @template M - The machine type
  * @param machine - The machine to add logging to
- * @param options - Optional configuration for logging format
+ * @param options - Logging configuration options
  * @returns A new machine with logging middleware
- *
- * @example
- * const logged = withLogging(counter);
- * logged.increment(); // Console: "→ increment []" then "✓ increment { count: 1 }"
  */
 export function withLogging<M extends BaseMachine<any>>(
   machine: M,
   options: {
-    /** Custom logger function (default: console.log) */
-    logger?: (message: string, ...args: any[]) => void;
-    /** Include context in logs (default: true) */
-    includeContext?: boolean;
-    /** Include arguments in logs (default: true) */
+    logger?: (message: string) => void;
     includeArgs?: boolean;
+    includeContext?: boolean;
   } = {}
 ): M {
-  const {
-    logger = console.log,
-    includeContext = true,
-    includeArgs = true
-  } = options;
+  const { logger = console.log, includeArgs = false, includeContext = true } = options;
 
   return createMiddleware(machine, {
     before: ({ transitionName, args }) => {
-      const argsStr = includeArgs && args.length > 0 ? ` ${JSON.stringify(args)}` : '';
-      logger(`→ ${transitionName}${argsStr}`);
+      const message = includeArgs ? `→ ${transitionName} [${args.join(', ')}]` : `→ ${transitionName}`;
+      logger(message);
     },
-    after: ({ transitionName, nextContext }) => {
-      const contextStr = includeContext ? ` ${JSON.stringify(nextContext)}` : '';
-      logger(`✓ ${transitionName}${contextStr}`);
+     after: ({ transitionName, nextContext }) => {
+       const contextStr = includeContext ? ` ${JSON.stringify(nextContext)}` : '';
+       logger(`✓ ${transitionName}${contextStr}`);
+     },
+    error: ({ transitionName, error }) => {
+      console.error(`[Machine] ${transitionName} failed:`, error);
     }
   });
 }
 
 /**
- * Analytics middleware that tracks state transitions.
- * Compatible with any analytics service (Segment, Mixpanel, GA, etc.).
+ * Creates analytics tracking middleware.
  *
  * @template M - The machine type
  * @param machine - The machine to track
  * @param track - Analytics tracking function
- * @param options - Optional configuration for event naming
- * @returns A new machine with analytics middleware
- *
- * @example
- * const tracked = withAnalytics(machine, (event, props) => {
- *   analytics.track(event, props);
- * });
+ * @param options - Configuration options
+ * @returns A new machine with analytics tracking
  */
 export function withAnalytics<M extends BaseMachine<any>>(
   machine: M,
-  track: (event: string, properties: Record<string, any>) => void | Promise<void>,
+  track: (event: string, data?: any) => void,
   options: {
-    /** Prefix for event names (default: "state_transition") */
     eventPrefix?: string;
-    /** Include previous context in properties (default: false) */
     includePrevContext?: boolean;
-    /** Include arguments in properties (default: true) */
     includeArgs?: boolean;
   } = {}
 ): M {
-  const {
-    eventPrefix = 'state_transition',
-    includePrevContext = false,
-    includeArgs = true
-  } = options;
+  const { eventPrefix = 'state_transition', includePrevContext = false, includeArgs = false } = options;
 
   return createMiddleware(machine, {
-    after: async ({ transitionName, prevContext, nextContext, args }) => {
-      const properties: Record<string, any> = {
-        transition: transitionName,
-        to: nextContext
-      };
-
-      if (includePrevContext) {
-        properties.from = prevContext;
-      }
-
-      if (includeArgs && args.length > 0) {
-        properties.args = args;
-      }
-
-      await track(`${eventPrefix}.${transitionName}`, properties);
+    after: ({ transitionName, prevContext, nextContext, args }) => {
+      const event = `${eventPrefix}.${transitionName}`;
+      const data: any = { transition: transitionName };
+      if (includePrevContext) data.from = prevContext;
+      data.to = nextContext;
+      if (includeArgs) data.args = args;
+      track(event, data);
     }
-  }, { mode: 'async' });
+  });
 }
 
 /**
- * Validation middleware that validates transitions before they execute.
- * Throws an error if validation fails, preventing the transition.
+ * Creates validation middleware that runs before transitions.
  *
  * @template M - The machine type
  * @param machine - The machine to validate
- * @param validate - Validation function that throws or returns false on invalid transitions
- * @returns A new machine with validation middleware
- *
- * @example
- * const validated = withValidation(counter, ({ transitionName, context, args }) => {
- *   if (transitionName === 'decrement' && context.count === 0) {
- *     throw new Error('Cannot decrement below zero');
- *   }
- * });
+ * @param validator - Validation function
+ * @returns A new machine with validation
  */
 export function withValidation<M extends BaseMachine<any>>(
   machine: M,
-  validate: (ctx: MiddlewareContext<Context<M>>) => void | boolean | Promise<void | boolean>,
-  options?: Pick<MiddlewareOptions, 'mode'>
+  validator: (ctx: MiddlewareContext<Context<M>>) => boolean | void
 ): M {
   return createMiddleware(machine, {
     before: (ctx) => {
-      const result = validate(ctx);
-      if (result instanceof Promise) {
-        return result.then(r => {
-          if (r === false) {
-            throw new Error(`Validation failed for transition: ${ctx.transitionName}`);
-          }
-          return undefined;
-        });
-      }
+      const result = validator(ctx);
       if (result === false) {
         throw new Error(`Validation failed for transition: ${ctx.transitionName}`);
       }
-      return undefined;
     }
-  }, { mode: 'auto', ...options });
+  });
 }
 
 /**
- * Permission/authorization middleware that checks if a transition is allowed.
- * Useful for implementing role-based access control (RBAC) in state machines.
+ * Creates permission-checking middleware.
  *
  * @template M - The machine type
  * @param machine - The machine to protect
- * @param canPerform - Function that checks if the transition is allowed
+ * @param checker - Permission checking function
  * @returns A new machine with permission checks
- *
- * @example
- * const protected = withPermissions(machine, (user) => ({ transitionName }) => {
- *   if (transitionName === 'delete' && user.role !== 'admin') {
- *     return false;
- *   }
- *   return true;
- * });
  */
 export function withPermissions<M extends BaseMachine<any>>(
   machine: M,
-  canPerform: (ctx: MiddlewareContext<Context<M>>) => boolean | Promise<boolean>,
-  options?: Pick<MiddlewareOptions, 'mode'>
+  checker: (ctx: MiddlewareContext<Context<M>>) => boolean
 ): M {
   return createMiddleware(machine, {
     before: (ctx) => {
-      const result = canPerform(ctx);
-      if (result instanceof Promise) {
-        return result.then(allowed => {
-          if (!allowed) {
-            throw new Error(`Unauthorized transition: ${ctx.transitionName}`);
-          }
-          return undefined;
-        });
-      }
-      if (!result) {
+      if (!checker(ctx)) {
         throw new Error(`Unauthorized transition: ${ctx.transitionName}`);
       }
-      return undefined;
     }
-  }, { mode: 'auto', ...options });
+  });
 }
 
 /**
- * Error reporting middleware that sends errors to an error tracking service.
- * Compatible with Sentry, Bugsnag, Rollbar, etc.
+ * Creates error reporting middleware.
  *
  * @template M - The machine type
  * @param machine - The machine to monitor
- * @param captureError - Error capture function (e.g., Sentry.captureException)
- * @param options - Optional configuration for error context
+ * @param reporter - Error reporting function
+ * @param options - Configuration options
  * @returns A new machine with error reporting
- *
- * @example
- * const monitored = withErrorReporting(machine, (error, context) => {
- *   Sentry.captureException(error, { extra: context });
- * });
  */
 export function withErrorReporting<M extends BaseMachine<any>>(
   machine: M,
-  captureError: (error: Error, context: Record<string, any>) => void | Promise<void>,
-  options: {
-    /** Include machine context in error report (default: true) */
-    includeContext?: boolean;
-    /** Include arguments in error report (default: true) */
-    includeArgs?: boolean;
-    /** Middleware execution mode */
-    mode?: MiddlewareOptions['mode'];
-  } = {}
+  reporter: (error: Error, ctx: any) => void,
+  options: { includeArgs?: boolean } = {}
 ): M {
-  const { includeContext = true, includeArgs = true, mode } = options;
+  const { includeArgs = false } = options;
 
   return createMiddleware(machine, {
-    error: async ({ transitionName, context, args, error }) => {
-      const errorContext: Record<string, any> = {
-        transition: transitionName
+    error: (errorCtx) => {
+      // Format the context to match test expectations
+      const formattedCtx = {
+        transition: errorCtx.transitionName,
+        context: errorCtx.context,
+        ...(includeArgs && { args: errorCtx.args })
       };
-
-      if (includeContext) {
-        errorContext.context = context;
-      }
-
-      if (includeArgs && args.length > 0) {
-        errorContext.args = args;
-      }
-
-      await Promise.resolve(captureError(error, errorContext));
+      reporter(errorCtx.error, formattedCtx);
     }
-  }, { mode });
+  });
 }
 
 /**
- * Performance monitoring middleware that tracks transition execution time.
- * Useful for identifying slow transitions and performance bottlenecks.
+ * Creates performance monitoring middleware.
  *
  * @template M - The machine type
  * @param machine - The machine to monitor
- * @param onMetric - Callback to receive performance metrics
+ * @param tracker - Performance tracking function
  * @returns A new machine with performance monitoring
- *
- * @example
- * const monitored = withPerformanceMonitoring(machine, ({ transition, duration }) => {
- *   if (duration > 100) {
- *     console.warn(`Slow transition: ${transition} took ${duration}ms`);
- *   }
- * });
  */
 export function withPerformanceMonitoring<M extends BaseMachine<any>>(
   machine: M,
-  onMetric: (metric: {
-    transitionName: string;
-    duration: number;
-    context: Readonly<Context<M>>;
-  }) => void | Promise<void>
+  tracker: (metric: { transitionName: string; duration: number; context: Context<M> }) => void
 ): M {
-  const timings = new Map<string, number>();
+  const startTimes = new Map<string, number>();
 
   return createMiddleware(machine, {
-    before: ({ transitionName }) => {
-      timings.set(transitionName, performance.now());
-      return undefined;
+    before: (ctx) => {
+      startTimes.set(ctx.transitionName, Date.now());
     },
-    after: ({ transitionName, nextContext }) => {
-      const startTime = timings.get(transitionName);
+    after: (result) => {
+      const startTime = startTimes.get(result.transitionName);
       if (startTime) {
-        const duration = performance.now() - startTime;
-        timings.delete(transitionName);
-        const result = onMetric({ transitionName, duration, context: nextContext });
-        if (result instanceof Promise) {
-          return result;
-        }
+        const duration = Date.now() - startTime;
+        startTimes.delete(result.transitionName);
+        // For test compatibility, pass a single object as expected
+        const testResult = {
+          transitionName: result.transitionName,
+          duration,
+          context: result.nextContext || result.prevContext
+        };
+        tracker(testResult);
       }
-      return undefined;
     }
-  }, { mode: 'auto' });
+  });
 }
 
 /**
- * Retry middleware that automatically retries failed transitions.
- * Uses direct property wrapping for optimal performance.
- * Useful for handling transient failures in async operations.
+ * Creates retry middleware for failed transitions.
  *
  * @template M - The machine type
  * @param machine - The machine to add retry logic to
  * @param options - Retry configuration
  * @returns A new machine with retry logic
- *
- * @example
- * const resilient = withRetry(machine, {
- *   maxRetries: 3,
- *   delay: 1000,
- *   shouldRetry: (error) => error.message.includes('network')
- * });
  */
 export function withRetry<M extends BaseMachine<any>>(
   machine: M,
   options: {
-    /** Maximum number of retry attempts (default: 3) */
-    maxRetries?: number;
-    /** Delay between retries in milliseconds (default: 1000) */
-    delay?: number;
-    /** Exponential backoff multiplier (default: 1, no backoff) */
-    backoffMultiplier?: number;
-    /** Function to determine if error should trigger retry (default: always retry) */
-    shouldRetry?: (error: Error) => boolean;
-    /** Callback when retry occurs */
-    onRetry?: (attempt: number, error: Error) => void;
+    maxAttempts?: number;
+    maxRetries?: number; // alias for maxAttempts
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    backoffMs?: number | ((attempt: number) => number);
+    delay?: number | ((attempt: number) => number); // alias for backoffMs
+    backoffMultiplier?: number; // multiplier for exponential backoff
+    onRetry?: (error: Error, attempt: number) => void;
   } = {}
 ): M {
   const {
-    maxRetries = 3,
-    delay = 1000,
-    backoffMultiplier = 1,
+    maxAttempts = options.maxRetries ?? 3,
     shouldRetry = () => true,
+    backoffMs = options.delay ?? 100,
+    backoffMultiplier = 2,
     onRetry
   } = options;
 
-  // Build wrapped machine object with direct property iteration
-  const wrapped: any = {};
+  // Create a wrapped machine that adds retry logic
+  const wrappedMachine: any = { ...machine };
 
+  // Wrap each transition function with retry logic
   for (const prop in machine) {
     if (!Object.prototype.hasOwnProperty.call(machine, prop)) continue;
-
     const value = machine[prop];
-
-    // Skip context and non-functions
-    if (prop === 'context' || typeof value !== 'function') {
-      wrapped[prop] = value;
-      continue;
-    }
-
-    // Wrap with retry logic
-    wrapped[prop] = async function retriableTransition(this: any, ...args: any[]) {
-      let lastError: Error | undefined;
-
-      for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-          return await value.call(this, ...args);
-        } catch (error) {
-          lastError = error as Error;
-
-          // Don't retry if we've exhausted attempts
-          if (attempt === maxRetries) {
-            break;
-          }
-
-          // Don't retry if shouldRetry returns false
-          if (!shouldRetry(lastError)) {
-            break;
+    if (typeof value === 'function' && prop !== 'context') {
+      wrappedMachine[prop] = async function (this: any, ...args: any[]) {
+        let lastError: Error;
+        let attempt = 0;
+
+        while (attempt < maxAttempts) {
+          try {
+            return await value.apply(this, args);
+          } catch (error) {
+            lastError = error as Error;
+            attempt++;
+
+            if (attempt < maxAttempts && shouldRetry(lastError, attempt)) {
+              onRetry?.(lastError, attempt);
+              const baseDelay = typeof backoffMs === 'function' ? backoffMs(attempt) : backoffMs;
+              const delay = baseDelay * Math.pow(backoffMultiplier, attempt - 1);
+              await new Promise(resolve => setTimeout(resolve, delay));
+            } else {
+              throw lastError;
+            }
           }
-
-          // Call onRetry callback
-          onRetry?.(attempt + 1, lastError);
-
-          // Wait before retrying
-          const currentDelay = delay * Math.pow(backoffMultiplier, attempt);
-          await new Promise(resolve => setTimeout(resolve, currentDelay));
         }
-      }
 
-      // All retries exhausted, throw the last error
-      throw lastError;
-    };
-  }
+        throw lastError!;
+        };
 
-  return wrapped as M;
-}
 
-/**
- * Guard configuration for a single transition.
- */
-export interface GuardConfig<C extends object> {
-  /** Guard predicate function that returns true if transition is allowed */
-  guard: (ctx: MiddlewareContext<C>, ...args: any[]) => boolean | Promise<boolean>;
-  /**
-   * Action to take when guard fails.
-   * - 'throw': Throw an error (default)
-   * - 'ignore': Silently cancel the transition
-   *
-   * Note: For custom fallback machines, use the error hook in createMiddleware:
-   * @example
-   * createMiddleware(machine, {
-   *   error: ({ error, context }) => {
-   *     if (error.message.includes('Guard failed')) {
-   *       return createMachine({ ...context, error: 'Unauthorized' }, machine);
-   *     }
-   *   }
-   * });
-   */
-  onFail?: 'throw' | 'ignore';
+     }
+   }
+
+   return wrappedMachine;
 }
 
 /**
- * Guard middleware that prevents transitions based on predicate functions.
- * Implements fundamental FSM guard concept - transitions only occur when guards pass.
+ * Creates custom middleware from hooks.
  *
  * @template M - The machine type
- * @param machine - The machine to protect with guards
- * @param guards - Object mapping transition names to guard configurations
- * @returns A new machine with guard checks
- *
- * @example
- * const guarded = withGuards(counter, {
- *   decrement: {
- *     guard: ({ context }) => context.count > 0,
- *     onFail: 'throw' // or 'ignore'
- *   },
- *   delete: {
- *     guard: ({ context }) => context.user?.isAdmin === true,
- *     onFail: 'throw'
- *   }
- * });
- *
- * guarded.decrement(); // Throws if count === 0
- *
- * // For custom fallback machines, combine with error middleware:
- * const guardedWithFallback = createMiddleware(guarded, {
- *   error: ({ error, context }) => {
- *     if (error.message.includes('Guard failed')) {
- *       return createMachine({ ...context, error: 'Unauthorized' }, machine);
- *     }
- *   }
- * });
+ * @param hooks - Middleware hooks
+ * @param options - Middleware options
+ * @returns A middleware function
  */
-export function withGuards<M extends BaseMachine<any>>(
-  machine: M,
-  guards: Record<string, GuardConfig<Context<M>> | ((ctx: MiddlewareContext<Context<M>>, ...args: any[]) => boolean | Promise<boolean>)>,
-  options?: Pick<MiddlewareOptions, 'mode'>
-): M {
-  return createMiddleware(machine, {
-    before: async (ctx) => {
-      const guardConfig = guards[ctx.transitionName];
-      if (!guardConfig) {
-        return undefined; // No guard for this transition
-      }
+export function createCustomMiddleware<M extends BaseMachine<any>>(
+  hooks: MiddlewareHooks<Context<M>>,
+  options?: MiddlewareOptions
+): (machine: M) => M {
+  return (machine: M) => createMiddleware(machine, hooks, options);
+}
 
-      // Handle shorthand: function directly instead of config object
-      const guard = typeof guardConfig === 'function' ? guardConfig : guardConfig.guard;
-      const onFail = typeof guardConfig === 'object' ? guardConfig.onFail : 'throw';
+// =============================================================================
+// SECTION: HISTORY TRACKING
+// =============================================================================
 
-      // Evaluate guard
-      const allowed = await Promise.resolve(guard(ctx, ...ctx.args));
+/**
+ * A single history entry recording a transition.
+ */
+export interface HistoryEntry {
+  /** Unique ID for this history entry */
+  id: string;
+  /** Name of the transition that was called */
+  transitionName: string;
+  /** Arguments passed to the transition */
+  args: any[];
+  /** Timestamp when the transition occurred */
+  timestamp: number;
+  /** Optional serialized version of args for persistence */
+  serializedArgs?: string;
+}
 
-      if (!allowed) {
-        if (onFail === 'ignore') {
-          return CANCEL; // Silently cancel transition
-        } else {
-          // Default to 'throw'
-          throw new Error(`Guard failed for transition: ${ctx.transitionName}`);
-        }
-      }
-      return undefined;
-    }
-  }, { mode: 'async', ...options });
+/**
+ * Serializer interface for converting context/args to/from strings.
+ */
+export interface Serializer<T = any> {
+  serialize: (value: T) => string;
+  deserialize: (str: string) => T;
 }
 
 /**
- * Creates conditional middleware that only applies to specific transitions.
- * Useful for targeted instrumentation without affecting all transitions.
+ * Creates a machine with history tracking capabilities.
+ * Records all transitions that occur, allowing you to see the sequence of state changes.
  *
  * @template M - The machine type
- * @param machine - The machine to instrument
- * @param config - Configuration specifying which transitions to instrument
- * @returns A new machine with conditional middleware
- *
- * @example
- * const conditional = createConditionalMiddleware(counter, {
- *   only: ['delete', 'update'], // Only these transitions
- *   hooks: {
- *     before: ({ transitionName }) => console.log('Sensitive operation:', transitionName),
- *     after: ({ transitionName }) => auditLog(transitionName)
- *   }
- * });
+ * @param machine - The machine to track
+ * @param options - Configuration options
+ * @returns A new machine with history tracking
  *
  * @example
- * const excluding = createConditionalMiddleware(counter, {
- *   except: ['increment'], // All except these
- *   hooks: {
- *     before: ({ transitionName, args }) => validate(transitionName, args)
- *   }
- * });
- */
-export function createConditionalMiddleware<M extends BaseMachine<any>>(
-  machine: M,
-  config: {
-    /** Only apply to these transitions (mutually exclusive with except) */
-    only?: string[];
-    /** Apply to all except these transitions (mutually exclusive with only) */
-    except?: string[];
-    /** Middleware hooks to apply */
-    hooks: MiddlewareHooks<Context<M>>;
-    /** Middleware options */
-    options?: MiddlewareOptions;
-  }
-): M {
-  const { only, except, hooks, options } = config;
-
-  if (only && except) {
-    throw new Error('Cannot specify both "only" and "except" - choose one');
-  }
-
-  // Create filter function
-  const shouldApply = (transitionName: string): boolean => {
-    if (only) {
-      return only.includes(transitionName);
-    }
-    if (except) {
-      return !except.includes(transitionName);
-    }
-    return true;
-  };
-
-  // Wrap hooks to check filter
-  const conditionalHooks: MiddlewareHooks<Context<M>> = {
-    before: hooks.before
-      ? async (ctx) => {
-          if (shouldApply(ctx.transitionName)) {
-            return await hooks.before!(ctx);
-          }
-        }
-      : undefined,
-    after: hooks.after
-      ? async (result) => {
-          if (shouldApply(result.transitionName)) {
-            return await hooks.after!(result);
-          }
-        }
-      : undefined,
-    error: hooks.error
-      ? async (error) => {
-          if (shouldApply(error.transitionName)) {
-            return await hooks.error!(error);
-          }
-        }
-      : undefined
-  };
-
-  return createMiddleware(machine, conditionalHooks, options);
-}
-
-/**
- * Creates state-dependent middleware that only applies when a predicate is true.
- * Allows middleware behavior to change based on current context/state.
- *
- * @template M - The machine type
- * @param machine - The machine to instrument
- * @param config - Configuration with predicate and hooks
- * @returns A new machine with state-dependent middleware
- *
- * @example
- * const stateful = createStateMiddleware(counter, {
- *   when: (ctx) => ctx.debugMode === true,
- *   hooks: {
- *     before: (ctx) => console.log('Debug:', ctx),
- *     after: (result) => console.log('Debug result:', result)
- *   }
- * });
- *
- * // Logging only happens when context.debugMode === true
- */
-export function createStateMiddleware<M extends BaseMachine<any>>(
-  machine: M,
-  config: {
-    /** Predicate that determines if middleware should apply */
-    when: (ctx: Context<M>) => boolean | Promise<boolean>;
-    /** Middleware hooks to apply when predicate is true */
-    hooks: MiddlewareHooks<Context<M>>;
-    /** Middleware options */
-    options?: MiddlewareOptions;
-  }
-): M {
-  const { when, hooks, options } = config;
-
-  // Wrap hooks to check predicate
-  const conditionalHooks: MiddlewareHooks<Context<M>> = {
-    before: hooks.before
-      ? async (ctx) => {
-          if (await Promise.resolve(when(ctx.context))) {
-            return await hooks.before!(ctx);
-          }
-        }
-      : undefined,
-    after: hooks.after
-      ? async (result) => {
-          if (await Promise.resolve(when(result.prevContext))) {
-            return await hooks.after!(result);
-          }
-        }
-      : undefined,
-    error: hooks.error
-      ? async (error) => {
-          if (await Promise.resolve(when(error.context))) {
-            return await hooks.error!(error);
-          }
-        }
-      : undefined
-  };
-
-  return createMiddleware(machine, conditionalHooks, options);
-}
-
-// =============================================================================
-// SECTION: HISTORY AND SNAPSHOT TRACKING
-// =============================================================================
-
-/**
- * Represents a recorded transition call in the history.
- */
-export interface HistoryEntry {
-  /** Unique ID for this history entry */
-  id: string;
-  /** The transition that was called */
-  transitionName: string;
-  /** Arguments passed to the transition */
-  args: any[];
-  /** Timestamp when the transition was called */
-  timestamp: number;
-  /** Optional serialized version of args (if serializer provided) */
-  serializedArgs?: string;
-}
-
-/**
- * Generic serializer/deserializer interface.
- * Used for serializing history arguments, context snapshots, etc.
- * @template T - The type being serialized
- */
-export interface Serializer<T = any> {
-  /** Serialize data to a string */
-  serialize: (data: T) => string;
-  /** Deserialize string back to data */
-  deserialize: (serialized: string) => T;
-}
-
-/**
- * History tracking middleware that records all transition calls.
- * Useful for debugging, replay, undo/redo, and audit logging.
- *
- * @template M - The machine type
- * @param machine - The machine to track
- * @param options - Configuration options
- * @returns A new machine with history tracking and a history array
- *
- * Note: Arguments are shallow-cloned by default. If you need deep cloning or
- * serialization for persistence, provide a serializer:
- *
- * @example
- * const tracked = withHistory(counter, {
- *   maxSize: 100,
- *   serializer: {
- *     serialize: (args) => JSON.stringify(args),  // For deep clone or persistence
- *     deserialize: (str) => JSON.parse(str)
- *   }
- * });
- *
+ * ```typescript
+ * const tracked = withHistory(counter, { maxSize: 50 });
  * tracked.increment();
- * tracked.add(5);
- * console.log(tracked.history); // [{ transitionName: 'increment', args: [], ... }, ...]
- * tracked.clearHistory(); // Clear history
+ * console.log(tracked.history); // [{ id: "entry-1", transitionName: "increment", ... }]
+ * ```
  */
 export function withHistory<M extends BaseMachine<any>>(
   machine: M,
   options: {
-    /** Maximum number of entries to keep (default: unlimited) */
+    /** Maximum number of history entries to keep (default: unlimited) */
     maxSize?: number;
-    /** Optional serializer for arguments */
+    /** Optional serializer for transition arguments */
     serializer?: Serializer<any[]>;
-    /** Filter function to exclude certain transitions from history */
-    filter?: (transitionName: string, args: any[]) => boolean;
-    /** Callback when new entry is added */
+    /** Callback when a transition occurs */
     onEntry?: (entry: HistoryEntry) => void;
-    /** Internal flag to prevent rewrapping */
-    _isRewrap?: boolean;
   } = {}
-): WithHistory<M> {
-  const {
-    maxSize,
-    serializer,
-    filter,
-    onEntry,
-    _isRewrap = false
-  } = options;
-
+): M & { history: HistoryEntry[]; clearHistory: () => void } {
+  const { maxSize, serializer, onEntry } = options;
   const history: HistoryEntry[] = [];
   let entryId = 0;
 
   const instrumentedMachine = createMiddleware(machine, {
     before: ({ transitionName, args }) => {
-      // Check filter
-      if (filter && !filter(transitionName, args)) {
-        return;
-      }
-
-      // Create entry
       const entry: HistoryEntry = {
         id: `entry-${entryId++}`,
         transitionName,
-        args: [...args], // Shallow clone args (fast, works with any type)
+        args: [...args],
         timestamp: Date.now()
       };
 
-      // Serialize if serializer provided
       if (serializer) {
         try {
           entry.serializedArgs = serializer.serialize(args);
@@ -1202,7 +616,6 @@ export function withHistory<M extends BaseMachine<any>>(
         }
       }
 
-      // Add to history
       history.push(entry);
 
       // Enforce max size
@@ -1210,93 +623,28 @@ export function withHistory<M extends BaseMachine<any>>(
         history.shift();
       }
 
-      // Call callback
       onEntry?.(entry);
     }
-  }, { exclude: ['context', 'history', 'clearHistory'] });
-
-  // Override transitions to propagate history to returned machines
-  if (!_isRewrap) {
-    for (const prop in instrumentedMachine) {
-      if (!Object.prototype.hasOwnProperty.call(instrumentedMachine, prop)) continue;
-      const value = instrumentedMachine[prop];
-      if (typeof value === 'function' && !prop.startsWith('_') && prop !== 'context' && !['history', 'clearHistory'].includes(prop)) {
-        const originalFn = value;
-        (instrumentedMachine as any)[prop] = function(this: any, ...args: any[]) {
-          const result = originalFn.apply(this, args);
-          // If result is a machine, re-wrap it with history tracking using the shared history array
-          if (result && typeof result === 'object' && 'context' in result && !('history' in result)) {
-            // Create a new wrapped machine that shares the same history array
-            const rewrappedResult = createMiddleware(result, {
-              before: ({ transitionName, args: transArgs }) => {
-                // Check filter
-                if (filter && !filter(transitionName, transArgs)) {
-                  return;
-                }
-
-                // Create entry
-                const entry: HistoryEntry = {
-                  id: `entry-${entryId++}`,
-                  transitionName,
-                  args: [...transArgs],
-                  timestamp: Date.now()
-                };
-
-                // Serialize if serializer provided
-                if (serializer) {
-                  try {
-                    entry.serializedArgs = serializer.serialize(transArgs);
-                  } catch (err) {
-                    console.error('Failed to serialize history args:', err);
-                  }
-                }
-
-                // Add to history
-                history.push(entry);
-
-                // Enforce max size
-                if (maxSize && history.length > maxSize) {
-                  history.shift();
-                }
-
-                // Call callback
-                onEntry?.(entry);
-              }
-            }, { exclude: ['context', 'history', 'clearHistory'] });
-
-            // Attach the shared history
-            return Object.assign(rewrappedResult, {
-              history,
-              clearHistory: () => {
-                history.length = 0;
-                entryId = 0;
-              }
-            });
-          }
-          return result;
-        };
-      }
-    }
-  }
+  });
 
-  // Attach history tracking properties to the instrumented machine
+  // Attach history properties to the machine
   return Object.assign(instrumentedMachine, {
     history,
-    clearHistory: () => {
-      history.length = 0;
-      entryId = 0;
-    }
+    clearHistory: () => { history.length = 0; entryId = 0; }
   });
 }
 
+// =============================================================================
+// SECTION: SNAPSHOT TRACKING
+// =============================================================================
+
 /**
- * Represents a snapshot of context at a point in time.
- * @template C - The context type
+ * A snapshot of machine context before and after a transition.
  */
-export interface ContextSnapshot<C extends object = any> {
+export interface ContextSnapshot<C extends object> {
   /** Unique ID for this snapshot */
   id: string;
-  /** The transition that caused this change */
+  /** Name of the transition that caused this snapshot */
   transitionName: string;
   /** Context before the transition */
   before: C;
@@ -1304,7 +652,7 @@ export interface ContextSnapshot<C extends object = any> {
   after: C;
   /** Timestamp of the snapshot */
   timestamp: number;
-  /** Optional serialized version of contexts */
+  /** Optional serialized versions of contexts */
   serializedBefore?: string;
   serializedAfter?: string;
   /** Optional diff information */
@@ -1312,31 +660,27 @@ export interface ContextSnapshot<C extends object = any> {
 }
 
 /**
- * Snapshot middleware that records context before/after each transition.
- * Useful for time-travel debugging, undo/redo, and state inspection.
+ * Creates a machine with snapshot tracking capabilities.
+ * Records context state before and after each transition for debugging and inspection.
  *
  * @template M - The machine type
  * @param machine - The machine to track
  * @param options - Configuration options
- * @returns A new machine with snapshot tracking and snapshots array
+ * @returns A new machine with snapshot tracking
  *
  * @example
+ * ```typescript
  * const tracked = withSnapshot(counter, {
  *   maxSize: 50,
  *   serializer: {
  *     serialize: (ctx) => JSON.stringify(ctx),
  *     deserialize: (str) => JSON.parse(str)
- *   },
- *   captureSnapshot: (before, after) => ({
- *     changed: before.count !== after.count
- *   })
+ *   }
  * });
  *
  * tracked.increment();
  * console.log(tracked.snapshots); // [{ before: { count: 0 }, after: { count: 1 }, ... }]
- *
- * // Time-travel: restore to previous state
- * const previousState = tracked.restoreSnapshot(tracked.snapshots[0].before);
+ * ```
  */
 export function withSnapshot<M extends BaseMachine<any>>(
   machine: M,
@@ -1348,26 +692,18 @@ export function withSnapshot<M extends BaseMachine<any>>(
     /** Custom function to capture additional snapshot data */
     captureSnapshot?: (before: Context<M>, after: Context<M>) => any;
     /** Only capture snapshots where context actually changed */
-    onlyIfChanged?: boolean;
-    /** Filter function to exclude certain transitions from snapshots */
-    filter?: (transitionName: string) => boolean;
-    /** Callback when new snapshot is taken */
-    onSnapshot?: (snapshot: ContextSnapshot<Context<M>>) => void;
-    /** Additional properties to exclude from middleware (for composition) */
-    _extraExclusions?: string[];
-    /** Internal flag to prevent rewrapping */
-    _isRewrap?: boolean;
+    onlyOnChange?: boolean;
   } = {}
-): WithSnapshot<M, Context<M>> {
+): M & {
+  snapshots: ContextSnapshot<Context<M>>[];
+  clearSnapshots: () => void;
+  restoreSnapshot: (snapshot: ContextSnapshot<Context<M>>['before']) => M;
+} {
   const {
     maxSize,
     serializer,
     captureSnapshot,
-    onlyIfChanged = false,
-    filter,
-    onSnapshot,
-    _extraExclusions = [],
-    _isRewrap = false
+    onlyOnChange = false
   } = options;
 
   const snapshots: ContextSnapshot<Context<M>>[] = [];
@@ -1375,33 +711,24 @@ export function withSnapshot<M extends BaseMachine<any>>(
 
   const instrumentedMachine = createMiddleware(machine, {
     after: ({ transitionName, prevContext, nextContext }) => {
-      // Check filter
-      if (filter && !filter(transitionName)) {
+      // Skip if only capturing on change and context didn't change
+      if (onlyOnChange && JSON.stringify(prevContext) === JSON.stringify(nextContext)) {
         return;
       }
 
-      // Check if changed (if required)
-      if (onlyIfChanged) {
-        const changed = JSON.stringify(prevContext) !== JSON.stringify(nextContext);
-        if (!changed) {
-          return;
-        }
-      }
-
-      // Create snapshot
       const snapshot: ContextSnapshot<Context<M>> = {
         id: `snapshot-${snapshotId++}`,
         transitionName,
-        before: { ...prevContext as Context<M> }, // Clone
-        after: { ...nextContext as Context<M> }, // Clone
+        before: { ...prevContext },
+        after: { ...nextContext },
         timestamp: Date.now()
       };
 
-      // Serialize if serializer provided
+      // Serialize contexts if serializer provided
       if (serializer) {
         try {
-          snapshot.serializedBefore = serializer.serialize(prevContext as Context<M>);
-          snapshot.serializedAfter = serializer.serialize(nextContext as Context<M>);
+          snapshot.serializedBefore = serializer.serialize(prevContext);
+          snapshot.serializedAfter = serializer.serialize(nextContext);
         } catch (err) {
           console.error('Failed to serialize snapshot:', err);
         }
@@ -1410,348 +737,273 @@ export function withSnapshot<M extends BaseMachine<any>>(
       // Capture custom snapshot data
       if (captureSnapshot) {
         try {
-          snapshot.diff = captureSnapshot(prevContext as Context<M>, nextContext as Context<M>);
+          snapshot.diff = captureSnapshot(prevContext, nextContext);
         } catch (err) {
           console.error('Failed to capture snapshot:', err);
         }
       }
 
-      // Add to snapshots
       snapshots.push(snapshot);
 
       // Enforce max size
       if (maxSize && snapshots.length > maxSize) {
         snapshots.shift();
       }
-
-      // Call callback
-      onSnapshot?.(snapshot);
     }
-  }, { exclude: ['context', 'snapshots', 'clearSnapshots', 'restoreSnapshot', ..._extraExclusions] });
+  });
 
-  // Helper to restore machine to a previous context
+  // Helper to restore machine to a previous state
   const restoreSnapshot = (context: Context<M>): M => {
-    const { context: _, ...transitions } = machine;
-    return { context, ...transitions } as M;
-  };
-
-  // Override transitions to propagate snapshots and history to returned machines
-  if (!_isRewrap) {
-    for (const prop in instrumentedMachine) {
-      if (!Object.prototype.hasOwnProperty.call(instrumentedMachine, prop)) continue;
-      const value = instrumentedMachine[prop];
-      if (typeof value === 'function' && !prop.startsWith('_') && prop !== 'context' && !['snapshots', 'clearSnapshots', 'restoreSnapshot', 'history', 'clearHistory'].includes(prop)) {
-        const originalWrappedFn = value;
-        (instrumentedMachine as any)[prop] = function(this: any, ...args: any[]) {
-          const result = originalWrappedFn.apply(this, args);
-          // If result is a machine, re-wrap it with snapshot tracking using the shared snapshots array
-          if (result && typeof result === 'object' && 'context' in result && !('snapshots' in result)) {
-            // Manually handle snapshot tracking without calling createMiddleware again
-            // to avoid infinite recursion and complex wrapping issues
-            
-            // Create a proxy that intercepts transition calls to record snapshots
-            
-            // Wrap each transition to record snapshots
-            for (const transProp in result) {
-              if (!Object.prototype.hasOwnProperty.call(result, transProp)) continue;
-              const transValue = result[transProp];
-              if (typeof transValue === 'function' && !transProp.startsWith('_') && transProp !== 'context' && !['snapshots', 'clearSnapshots', 'restoreSnapshot', 'history', 'clearHistory'].includes(transProp)) {
-                const origTransFn = transValue;
-                (result as any)[transProp] = function(this: any, ...transArgs: any[]) {
-                  const prevCtx = result.context;
-                  const transResult = origTransFn.apply(this, transArgs);
-                  
-                  // Record snapshot if we got a machine back
-                  if (transResult && typeof transResult === 'object' && 'context' in transResult) {
-                    const nextCtx = transResult.context;
-                    
-                    // Check filter
-                    if (!(filter && !filter(transProp))) {
-                      // Check if changed (if required)
-                      let shouldRecord = true;
-                      if (onlyIfChanged) {
-                        const changed = JSON.stringify(prevCtx) !== JSON.stringify(nextCtx);
-                        shouldRecord = changed;
-                      }
-                      
-                      if (shouldRecord) {
-                        // Create snapshot
-                        const snapshot: ContextSnapshot<Context<M>> = {
-                          id: `snapshot-${snapshotId++}`,
-                          transitionName: transProp,
-                          before: { ...prevCtx as Context<M> },
-                          after: { ...nextCtx as Context<M> },
-                          timestamp: Date.now()
-                        };
-
-                        // Serialize if serializer provided
-                        if (serializer) {
-                          try {
-                            snapshot.serializedBefore = serializer.serialize(prevCtx as Context<M>);
-                            snapshot.serializedAfter = serializer.serialize(nextCtx as Context<M>);
-                          } catch (err) {
-                            console.error('Failed to serialize snapshot:', err);
-                          }
-                        }
-
-                        // Capture custom snapshot data
-                        if (captureSnapshot) {
-                          try {
-                            snapshot.diff = captureSnapshot(prevCtx as Context<M>, nextCtx as Context<M>);
-                          } catch (err) {
-                            console.error('Failed to capture snapshot:', err);
-                          }
-                        }
-
-                        // Add to snapshots
-                        snapshots.push(snapshot);
-
-                        // Enforce max size
-                        if (maxSize && snapshots.length > maxSize) {
-                          snapshots.shift();
-                        }
-
-                        // Call callback
-                        onSnapshot?.(snapshot);
-                      }
-                    }
-                  }
-                  
-                  return transResult;
-                };
-              }
-            }
-            
-            // Attach the shared snapshots and history
-            const resultWithTracking = Object.assign(result, {
-              snapshots,
-              clearSnapshots: () => {
-                snapshots.length = 0;
-                snapshotId = 0;
-              },
-              restoreSnapshot
-            });
-
-            // Also propagate history if it exists on the input machine
-            if ((machine as any).history) {
-              resultWithTracking.history = (machine as any).history;
-              resultWithTracking.clearHistory = (machine as any).clearHistory;
-            }
+    // Find the machine's transition functions (excluding context and snapshot properties)
+    const transitions = Object.fromEntries(
+      Object.entries(machine).filter(([key]) =>
+        key !== 'context' &&
+        key !== 'snapshots' &&
+        key !== 'clearSnapshots' &&
+        key !== 'restoreSnapshot' &&
+        typeof machine[key as keyof M] === 'function'
+      )
+    );
 
-            return resultWithTracking;
-          }
-          return result;
-        };
-      }
-    }
-  }
+    return Object.assign({ context }, transitions) as M;
+  };
 
-  // Attach snapshot tracking properties to the instrumented machine
+  // Attach snapshot properties to the machine
   return Object.assign(instrumentedMachine, {
     snapshots,
-    clearSnapshots: () => {
-      snapshots.length = 0;
-      snapshotId = 0;
-    },
+    clearSnapshots: () => { snapshots.length = 0; snapshotId = 0; },
     restoreSnapshot
   });
 }
 
+// =============================================================================
+// SECTION: TIME TRAVEL DEBUGGING
+// =============================================================================
+
+/**
+ * A machine enhanced with history tracking capabilities.
+ */
+export type WithHistory<M extends BaseMachine<any>> = M & {
+  /** History of all transitions */
+  history: HistoryEntry[];
+  /** Clear all history */
+  clearHistory: () => void;
+};
+
+/**
+ * A machine enhanced with snapshot tracking capabilities.
+ */
+export type WithSnapshot<M extends BaseMachine<any>> = M & {
+  /** Snapshots of context before/after each transition */
+  snapshots: ContextSnapshot<Context<M>>[];
+  /** Clear all snapshots */
+  clearSnapshots: () => void;
+  /** Restore machine to a previous context state */
+  restoreSnapshot: (context: Context<M>) => M;
+};
+
+/**
+ * A machine enhanced with time travel capabilities.
+ */
+export type WithTimeTravel<M extends BaseMachine<any>> = M & {
+  /** History of all transitions */
+  history: HistoryEntry[];
+  /** Snapshots of context before/after each transition */
+  snapshots: ContextSnapshot<Context<M>>[];
+  /** Clear all history and snapshots */
+  clearTimeTravel: () => void;
+  /** Clear just the history */
+  clearHistory: () => void;
+  /** Clear just the snapshots */
+  clearSnapshots: () => void;
+  /** Restore machine to a previous context state */
+  restoreSnapshot: (context: Context<M>) => M;
+  /** Replay transitions from a specific point in history */
+  replayFrom: (startIndex: number) => M;
+};
+
 /**
- * Combined history and snapshot middleware for full time-travel debugging.
- * Records both transition calls and context changes.
+ * Creates a machine with full time travel debugging capabilities.
+ * Combines history tracking, snapshots, and replay functionality.
  *
  * @template M - The machine type
- * @param machine - The machine to track
+ * @param machine - The machine to enhance
  * @param options - Configuration options
- * @returns Machine with both history and snapshot tracking
+ * @returns A machine with time travel capabilities
  *
  * @example
- * const tracker = withTimeTravel(counter, {
- *   maxSize: 100,
- *   serializer: {
- *     serialize: (data) => JSON.stringify(data),
- *     deserialize: (str) => JSON.parse(str)
- *   }
- * });
- *
- * tracker.increment();
- * tracker.add(5);
- *
- * console.log(tracker.history); // All transitions
- * console.log(tracker.snapshots); // All state changes
+ * ```typescript
+ * const debugMachine = withTimeTravel(counter);
  *
- * // Replay from a specific snapshot
- * const replayed = tracker.replayFrom(0);
+ * // Make some transitions
+ * debugMachine.increment();
+ * debugMachine.increment();
+ * debugMachine.decrement();
  *
- * // Restore to specific snapshot
- * const restored = tracker.restoreSnapshot(tracker.snapshots[0].before);
+ * // Time travel to previous states
+ * const previousState = debugMachine.replayFrom(0); // Replay from start
+ * const undoLast = debugMachine.restoreSnapshot(debugMachine.snapshots[1].before);
  *
- * // Clear all tracking data
- * tracker.clearTimeTravel();
+ * // Inspect history
+ * console.log(debugMachine.history);
+ * console.log(debugMachine.snapshots);
+ * ```
  */
 export function withTimeTravel<M extends BaseMachine<any>>(
   machine: M,
   options: {
-    /** Maximum size for both history and snapshots */
+    /** Maximum number of history entries/snapshots to keep */
     maxSize?: number;
-    /** Serializer for both args and context */
-    serializer?: Serializer<any>;
-    /** Callback for each recorded action */
+    /** Optional serializer for persistence */
+    serializer?: Serializer;
+    /** Callback when history/snapshot events occur */
     onRecord?: (type: 'history' | 'snapshot', data: any) => void;
   } = {}
-): WithTimeTravel<M, Context<M>> {
+): WithTimeTravel<M> {
   const { maxSize, serializer, onRecord } = options;
 
+  // Create separate history and snapshot tracking
   const history: HistoryEntry[] = [];
   const snapshots: ContextSnapshot<Context<M>>[] = [];
-  let entryId = 0;
+  let historyId = 0;
   let snapshotId = 0;
 
-  // Middleware hooks that record to shared arrays
-  const recordHistory = (transitionName: string, args: any[]) => {
-    const entry: HistoryEntry = {
-      id: `entry-${entryId++}`,
-      transitionName,
-      args: [...args],
-      timestamp: Date.now()
-    };
+  // Create middleware that handles both history and snapshots
+  const instrumentedMachine = createMiddleware(machine, {
+    before: ({ transitionName, args }) => {
+      const entry: HistoryEntry = {
+        id: `entry-${historyId++}`,
+        transitionName,
+        args: [...args],
+        timestamp: Date.now()
+      };
 
-    if (serializer) {
-      try {
-        entry.serializedArgs = serializer.serialize(args);
-      } catch (err) {
-        console.error('Failed to serialize history args:', err);
+      if (serializer) {
+        try {
+          entry.serializedArgs = serializer.serialize(args);
+        } catch (err) {
+          console.error('Failed to serialize history args:', err);
+        }
       }
-    }
 
-    history.push(entry);
-    if (maxSize && history.length > maxSize) {
-      history.shift();
-    }
+      history.push(entry);
 
-    onRecord?.('history', entry);
-  };
+      // Enforce max size
+      if (maxSize && history.length > maxSize) {
+        history.shift();
+      }
 
-  const recordSnapshot = (transitionName: string, prevContext: Context<M>, nextContext: Context<M>) => {
-    const snapshot: ContextSnapshot<Context<M>> = {
-      id: `snapshot-${snapshotId++}`,
-      transitionName,
-      before: { ...prevContext },
-      after: { ...nextContext },
-      timestamp: Date.now()
-    };
+      onRecord?.('history', entry);
+    },
+    after: ({ transitionName, prevContext, nextContext }) => {
+      const snapshot: ContextSnapshot<Context<M>> = {
+        id: `snapshot-${snapshotId++}`,
+        transitionName,
+        before: { ...prevContext },
+        after: { ...nextContext },
+        timestamp: Date.now()
+      };
 
-    if (serializer) {
-      try {
-        snapshot.serializedBefore = serializer.serialize(prevContext);
-        snapshot.serializedAfter = serializer.serialize(nextContext);
-      } catch (err) {
-        console.error('Failed to serialize snapshot:', err);
+      // Serialize contexts if serializer provided
+      if (serializer) {
+        try {
+          snapshot.serializedBefore = serializer.serialize(prevContext);
+          snapshot.serializedAfter = serializer.serialize(nextContext);
+        } catch (err) {
+          console.error('Failed to serialize snapshot:', err);
+        }
       }
-    }
-
-    snapshots.push(snapshot);
-    if (maxSize && snapshots.length > maxSize) {
-      snapshots.shift();
-    }
 
-    onRecord?.('snapshot', snapshot);
-  };
+      snapshots.push(snapshot);
 
-  // Helper to restore machine to a previous context
-  const restoreSnapshot = (context: Context<M>): M => {
-    const { context: _, ...transitions } = machine;
-    return Object.assign({ context }, context, transitions) as M;
-  };
+      // Enforce max size
+      if (maxSize && snapshots.length > maxSize) {
+        snapshots.shift();
+      }
 
-  // Implementation of replay functionality
-  const replayFrom = (snapshotIndex: number = 0): M => {
-    if (snapshotIndex < 0 || snapshotIndex >= snapshots.length) {
-      throw new Error(`Invalid snapshot index: ${snapshotIndex}`);
+      onRecord?.('snapshot', snapshot);
     }
+  });
 
-    let current = restoreSnapshot(snapshots[snapshotIndex].before);
-
-    // Find the history index that corresponds to this snapshot
-    const snapshot = snapshots[snapshotIndex];
-    const historyStartIndex = history.findIndex(
-      entry => entry.transitionName === snapshot.transitionName && entry.timestamp === snapshot.timestamp
+  // Helper to restore machine to a previous state
+  const restoreSnapshot = (context: Context<M>): M => {
+    // Find the machine's transition functions (excluding context and snapshot properties)
+    const transitions = Object.fromEntries(
+      Object.entries(machine).filter(([key]) =>
+        key !== 'context' &&
+        key !== 'history' &&
+        key !== 'snapshots' &&
+        key !== 'clearHistory' &&
+        key !== 'clearSnapshots' &&
+        key !== 'restoreSnapshot' &&
+        key !== 'clearTimeTravel' &&
+        key !== 'replayFrom' &&
+        typeof machine[key as keyof M] === 'function'
+      )
     );
 
-    if (historyStartIndex === -1) {
-      throw new Error('Could not find matching history entry for snapshot');
-    }
-
-    // Replay all transitions from that point
-    for (let i = historyStartIndex; i < history.length; i++) {
-      const entry = history[i];
-      const transition = (current as any)[entry.transitionName];
+    return Object.assign({ context }, transitions) as M;
+  };
 
-      if (typeof transition === 'function') {
-        try {
-          current = transition.apply(current.context, entry.args);
-        } catch (err) {
-          console.error(`Replay failed at step ${i}:`, err);
-          throw err;
-        }
-      }
+  // Create replay functionality
+  const replayFrom = (startIndex: number): M => {
+    if (startIndex < 0 || startIndex >= history.length) {
+      throw new Error(`Invalid replay start index: ${startIndex}`);
     }
 
-    return current;
-  };
-
-  // Helper to wrap a machine with tracking properties and wrapped transitions
-  const wrapMachine = (machine: any): any => {
-    const wrapped: any = { ...machine };
-
-    // Wrap transition functions
-    for (const prop in machine) {
-      if (!Object.prototype.hasOwnProperty.call(machine, prop)) continue;
-      const value = machine[prop];
-      if (typeof value === 'function' && !prop.startsWith('_') && prop !== 'context' &&
-          !['history', 'snapshots', 'clearHistory', 'clearSnapshots', 'clearTimeTravel', 'restoreSnapshot', 'replayFrom'].includes(prop)) {
-        wrapped[prop] = function(this: any, ...args: any[]) {
-          // Record history before transition
-          recordHistory(prop, args);
-
-          const prevContext = wrapped.context;
-          const result = value.apply(this, args);
-
-          // Record snapshot after transition
-          if (result && typeof result === 'object' && 'context' in result) {
-            recordSnapshot(prop, prevContext, result.context);
-          }
+    // Start from the context at the specified history index
+    let currentContext = snapshots[startIndex]?.before;
+    if (!currentContext) {
+      throw new Error(`No snapshot available for index ${startIndex}`);
+    }
 
-          // Wrap returned machine
-          if (result && typeof result === 'object' && 'context' in result) {
-            return wrapMachine(result);
-          }
-          return result;
-        };
+    // Get all transitions from start index to end
+    const transitionsToReplay = history.slice(startIndex);
+
+    // Create a fresh machine instance
+    const freshMachine = Object.assign(
+      { context: currentContext },
+      Object.fromEntries(
+        Object.entries(machine).filter(([key]) =>
+          key !== 'context' &&
+          typeof machine[key as keyof M] === 'function'
+        )
+      )
+    ) as M;
+
+    // Replay each transition
+    let replayedMachine = freshMachine;
+    for (const entry of transitionsToReplay) {
+      const transitionFn = replayedMachine[entry.transitionName as keyof M] as Function;
+      if (transitionFn) {
+        replayedMachine = transitionFn.apply(replayedMachine.context, entry.args);
       }
     }
 
-    // Attach tracking properties
-    return Object.assign(wrapped, {
-      history,
-      snapshots,
-      clearHistory: () => { history.length = 0; entryId = 0; },
-      clearSnapshots: () => { snapshots.length = 0; snapshotId = 0; },
-      clearTimeTravel: () => {
-        history.length = 0;
-        snapshots.length = 0;
-        entryId = 0;
-        snapshotId = 0;
-      },
-      restoreSnapshot,
-      replayFrom
-    });
+    return replayedMachine;
   };
 
-  return wrapMachine(machine);
+  // Return machine with all time travel capabilities
+  return Object.assign(instrumentedMachine, {
+    history,
+    snapshots,
+    clearHistory: () => { history.length = 0; historyId = 0; },
+    clearSnapshots: () => { snapshots.length = 0; snapshotId = 0; },
+    clearTimeTravel: () => {
+      history.length = 0;
+      snapshots.length = 0;
+      historyId = 0;
+      snapshotId = 0;
+    },
+    restoreSnapshot,
+    replayFrom
+  }) as WithTimeTravel<M>;
 }
 
+// =============================================================================
+// SECTION: MIDDLEWARE COMPOSITION
+// =============================================================================
+
 /**
  * Compose multiple middleware functions into a single middleware stack.
  * Middleware is applied left-to-right (first middleware wraps outermost).
@@ -1760,15 +1012,6 @@ export function withTimeTravel<M extends BaseMachine<any>>(
  * @param machine - The base machine
  * @param middlewares - Array of middleware functions
  * @returns A new machine with all middleware applied
- *
- * @example
- * const instrumented = compose(
- *   counter,
- *   withLogging,
- *   withAnalytics(analytics.track),
- *   withValidation(validator),
- *   withErrorReporting(Sentry.captureException)
- * );
  */
 export function compose<M extends BaseMachine<any>>(
   machine: M,
@@ -1778,43 +1021,48 @@ export function compose<M extends BaseMachine<any>>(
 }
 
 /**
- * Create a reusable middleware function from hooks.
- * Useful for defining custom middleware that can be applied to multiple machines.
+ * Type-safe middleware composition with perfect inference.
+ * Composes multiple middlewares into a single transformation chain.
  *
- * @template M - The machine type
- * @param hooks - Middleware hooks configuration
- * @param options - Middleware options
- * @returns A middleware function that can be applied to machines
- *
- * @example
- * const myMiddleware = createCustomMiddleware({
- *   before: ({ transitionName }) => console.log('Before:', transitionName),
- *   after: ({ transitionName }) => console.log('After:', transitionName)
- * });
- *
- * const machine1 = myMiddleware(counter1);
- * const machine2 = myMiddleware(counter2);
+ * @template M - The input machine type
+ * @template Ms - Array of middleware functions
+ * @param machine - The machine to enhance
+ * @param middlewares - Middleware functions to apply in order
+ * @returns The machine with all middlewares applied, with precise type inference
  */
-export function createCustomMiddleware<M extends BaseMachine<any>>(
-  hooks: MiddlewareHooks<Context<M>>,
-  options?: MiddlewareOptions
-): (machine: M) => M {
-  return (machine: M) => createMiddleware(machine, hooks, options);
+export function composeTyped<
+  M extends BaseMachine<any>,
+  Ms extends readonly MiddlewareFn<any, any>[]
+>(
+  machine: M,
+  ...middlewares: Ms
+): ComposeResult<M, Ms> {
+  return middlewares.reduce((acc, middleware) => middleware(acc), machine) as ComposeResult<M, Ms>;
 }
 
 // =============================================================================
-// SECTION: TYPESAFE MIDDLEWARE COMPOSITION
+// SECTION: TYPE-LEVEL COMPOSITION
 // =============================================================================
 
 /**
- * A middleware function that transforms a machine.
- * @template M - The input machine type
- * @template R - The output machine type (usually extends M)
+ * Type-level utility for composing middleware return types.
+ * This enables perfect TypeScript inference when chaining middlewares.
  */
+export type ComposeResult<
+  M extends BaseMachine<any>,
+  Ms extends readonly MiddlewareFn<any, any>[]
+> = Ms extends readonly [infer First, ...infer Rest]
+  ? First extends MiddlewareFn<any, infer R>
+    ? Rest extends readonly MiddlewareFn<any, any>[]
+      ? ComposeResult<R, Rest>
+      : R
+    : M
+  : M;
+
 /**
  * A middleware function that transforms a machine.
- * @template M - Input machine type
- * @template R - Output machine type (defaults to same as input if no augmentation)
+ * @template M - The input machine type
+ * @template R - The output machine type (usually extends M)
  */
 export type MiddlewareFn<M extends BaseMachine<any>, R extends BaseMachine<any> = M> = (machine: M) => R;
 
@@ -1848,109 +1096,22 @@ export type NamedMiddleware<M extends BaseMachine<any>> = {
  * Configuration for middleware pipeline execution.
  */
 export interface PipelineConfig {
-  /** Whether to continue executing remaining middlewares if one fails */
+  /** Whether to continue execution if a middleware throws an error */
   continueOnError?: boolean;
-  /** Whether to log errors to console */
+  /** Whether to log errors from middlewares */
   logErrors?: boolean;
   /** Custom error handler */
-  onError?: (error: Error, middlewareName?: string) => void;
+  onError?: (error: Error, middlewareIndex: number, middlewareName?: string) => void;
 }
 
 /**
  * Result of pipeline execution.
  */
-export interface PipelineResult<M extends BaseMachine<any>> {
-  /** The final machine after all middlewares */
-  machine: M;
-  /** Any errors that occurred during execution */
-  errors: Array<{ error: Error; middlewareIndex: number; middlewareName?: string }>;
-  /** Whether the pipeline completed successfully */
-  success: boolean;
-}
-
-/**
- * Compose multiple middlewares with improved type inference.
- * This is a more typesafe version of the basic compose function.
- *
- * @template M - The initial machine type
- * @template Ms - Array of middleware functions
- * @param machine - The initial machine
- * @param middlewares - Array of middleware functions to apply
- * @returns The machine with all middlewares applied
- *
- * @example
- * const enhanced = composeTyped(
- *   counter,
- *   withHistory(),
- *   withSnapshot(),
- *   withTimeTravel()
- * );
- */
-/**
- * Recursively applies middlewares to infer the final machine type.
- * Provides precise type inference for middleware composition chains.
- */
-type ComposeResult<
-  M extends BaseMachine<any>,
-  Ms extends readonly MiddlewareFn<any, any>[]
-> = Ms extends readonly []
-  ? M
-  : Ms extends readonly [infer First, ...infer Rest]
-    ? First extends MiddlewareFn<any, infer Output>
-      ? Rest extends readonly MiddlewareFn<any, any>[]
-        ? ComposeResult<Output, Rest>
-        : Output
-      : M
-    : M;
+export type PipelineResult<M extends BaseMachine<any>> = M;
 
-/**
- * Type-safe middleware composition with perfect inference.
- * Composes multiple middlewares into a single transformation chain.
- *
- * @template M - The input machine type
- * @template Ms - Array of middleware functions
- * @param machine - The machine to enhance
- * @param middlewares - Middleware functions to apply in order
- * @returns The machine with all middlewares applied, with precise type inference
- *
- * @example
- * ```typescript
- * const enhanced = composeTyped(
- *   counter,
- *   withHistory(),
- *   withSnapshot(),
- *   withTimeTravel()
- * );
- * // enhanced: WithTimeTravel<WithSnapshot<WithHistory<Counter>>>
- * // Perfect IntelliSense for all methods and properties
- * ```
- */
-export function composeTyped<
-  M extends BaseMachine<any>,
-  Ms extends readonly MiddlewareFn<any, any>[]
->(
-  machine: M,
-  ...middlewares: Ms
-): ComposeResult<M, Ms> {
-  return middlewares.reduce((acc, middleware) => middleware(acc), machine) as ComposeResult<M, Ms>;
-}
-
-/**
- * Type-safe middleware composition with fluent API.
- * Allows building middleware chains with method chaining.
- *
- * @example
- * ```typescript
- * const enhanced = chain(counter)
- *   .with(withHistory())
- *   .with(withSnapshot())
- *   .with(withTimeTravel())
- *   .build();
- * ```
- */
-export function chain<M extends BaseMachine<any>>(machine: M) {
-  return new MiddlewareChainBuilder(machine);
-}
+// =============================================================================
+// SECTION: FLUENT API
+// =============================================================================
 
 /**
  * Fluent middleware composer for building complex middleware chains.
@@ -1980,121 +1141,97 @@ class MiddlewareChainBuilder<M extends BaseMachine<any>> {
 }
 
 /**
- * Common middleware combination types for better DX.
- * These types help with inference when using popular middleware combinations.
- */
-export type WithDebugging<M extends BaseMachine<any>> = WithTimeTravel<WithSnapshot<WithHistory<M>>>;
-
-/**
- * Convenience function for the most common debugging middleware stack.
- * Combines history, snapshots, and time travel for full debugging capabilities.
+ * Create a fluent middleware chain builder.
  *
  * @example
  * ```typescript
- * const debugMachine = withDebugging(counter);
- * debugMachine.increment();
- * debugMachine.history; // Full transition history
- * debugMachine.snapshots; // Context snapshots
- * debugMachine.replayFrom(0); // Time travel
+ * const enhanced = chain(counter)
+ *   .with(withHistory())
+ *   .with(withSnapshot())
+ *   .with(withTimeTravel())
+ *   .build();
  * ```
  */
-export function withDebugging<M extends BaseMachine<any>>(machine: M): WithDebugging<M> {
-  return withTimeTravel(withSnapshot(withHistory(machine)));
+export function chain<M extends BaseMachine<any>>(machine: M) {
+  return new MiddlewareChainBuilder(machine);
 }
 
+// =============================================================================
+// SECTION: CONDITIONAL MIDDLEWARE
+// =============================================================================
+
 /**
- * Create a middleware pipeline with error handling and conditional execution.
+ * Create a conditional middleware that only applies when a predicate is true.
  *
  * @template M - The machine type
- * @param config - Pipeline configuration
- * @returns A function that executes middlewares in a pipeline
- *
- * @example
- * const pipeline = createPipeline({ continueOnError: true });
- *
- * const result = pipeline(
- *   counter,
- *   withHistory(),
- *   withSnapshot(),
- *   { middleware: withLogging(), when: (m) => m.context.debug }
- * );
+ * @param middleware - The middleware to conditionally apply
+ * @param predicate - Function that determines when to apply the middleware
+ * @returns A conditional middleware that can be called directly or used in pipelines
  */
-export function createPipeline<M extends BaseMachine<any>>(
-  config: PipelineConfig = {}
-): {
-  <Ms extends Array<MiddlewareFn<M> | ConditionalMiddleware<M>>>(
-    machine: M,
-    ...middlewares: Ms
-  ): PipelineResult<M>;
-} {
-  const {
-    continueOnError = false,
-    logErrors = true,
-    onError
-  } = config;
-
-  return (machine: M, ...middlewares: Array<MiddlewareFn<M> | ConditionalMiddleware<M>>): PipelineResult<M> => {
-    let currentMachine = machine;
-    const errors: Array<{ error: Error; middlewareIndex: number; middlewareName?: string }> = [];
-
-    for (let i = 0; i < middlewares.length; i++) {
-      const middleware = middlewares[i];
-
-      try {
-        // Handle conditional middleware
-        if ('middleware' in middleware && 'when' in middleware) {
-          if (!middleware.when(currentMachine)) {
-            continue; // Skip this middleware
-          }
-          currentMachine = middleware.middleware(currentMachine);
-        } else {
-          // Regular middleware
-          currentMachine = (middleware as MiddlewareFn<M>)(currentMachine);
-        }
-      } catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
-        errors.push({ error: err, middlewareIndex: i });
-
-        if (logErrors) {
-          console.error(`Middleware pipeline error at index ${i}:`, err);
-        }
-
-        onError?.(err, `middleware-${i}`);
+export function when<M extends BaseMachine<any>>(
+  middleware: MiddlewareFn<M>,
+  predicate: (machine: M) => boolean
+): ConditionalMiddleware<M> & MiddlewareFn<M> {
+  const conditional: ConditionalMiddleware<M> & MiddlewareFn<M> = function(machine: M) {
+    return predicate(machine) ? middleware(machine) : machine;
+  };
 
-        if (!continueOnError) {
-          break;
-        }
-      }
-    }
+  conditional.middleware = middleware;
+  conditional.when = predicate;
 
-    return {
-      machine: currentMachine,
-      errors,
-      success: errors.length === 0
-    };
-  };
+  return conditional;
 }
 
 /**
- * Create a middleware registry for named middleware composition.
- * Useful for building complex middleware stacks from reusable components.
+ * Create a middleware that only applies in development mode.
  *
  * @template M - The machine type
+ * @param middleware - The middleware to apply in development
+ * @returns A conditional middleware for development mode
+ */
+export function inDevelopment<M extends BaseMachine<any>>(
+  middleware: MiddlewareFn<M>
+): ConditionalMiddleware<M> & MiddlewareFn<M> {
+  return when(middleware, () => {
+    return typeof process !== 'undefined'
+      ? process.env.NODE_ENV === 'development'
+      : typeof window !== 'undefined'
+        ? !window.location.hostname.includes('production')
+        : false;
+  });
+}
+
+/**
+ * Create a middleware that only applies when a context property matches a value.
  *
- * @example
- * const registry = createMiddlewareRegistry<CounterMachine>()
- *   .register('history', withHistory(), 'Track state changes')
- *   .register('snapshot', withSnapshot(), 'Take context snapshots', 10)
- *   .register('timeTravel', withTimeTravel(), 'Enable time travel debugging', 20);
- *
- * const machine = registry.apply(counter, ['history', 'snapshot', 'timeTravel']);
+ * @template M - The machine type
+ * @template K - The context key
+ * @param key - The context property key
+ * @param value - The value to match
+ * @param middleware - The middleware to apply when the condition matches
+ * @returns A conditional middleware
+ */
+export function whenContext<M extends BaseMachine<any>, K extends keyof Context<M>>(
+  key: K,
+  value: Context<M>[K],
+  middleware: MiddlewareFn<M>
+): ConditionalMiddleware<M> & MiddlewareFn<M> {
+  return when(middleware, (machine) => machine.context[key] === value);
+}
+
+// =============================================================================
+// SECTION: MIDDLEWARE REGISTRY
+// =============================================================================
+
+/**
+ * Create a middleware registry for managing reusable middleware configurations.
  */
 export function createMiddlewareRegistry<M extends BaseMachine<any>>() {
   const registry = new Map<string, NamedMiddleware<M>>();
 
   return {
     /**
-     * Register a middleware with a name and optional metadata.
+     * Register a middleware by name.
      */
     register(
       name: string,
@@ -2166,104 +1303,80 @@ export function createMiddlewareRegistry<M extends BaseMachine<any>>() {
   };
 }
 
+// =============================================================================
+// SECTION: PIPELINES
+// =============================================================================
+
 /**
- * Create a conditional middleware that only applies when a predicate is true.
+ * Create a middleware pipeline with error handling and conditional execution.
  *
  * @template M - The machine type
- * @param middleware - The middleware to conditionally apply
- * @param predicate - Function that determines when to apply the middleware
- * @returns A conditional middleware that can be called directly or used in pipelines
- *
- * @example
- * const debugMiddleware = when(
- *   withTimeTravel(),
- *   (machine) => machine.context.debugMode
- * );
- *
- * // Can be called directly
- * const machine = debugMiddleware(baseMachine);
- *
- * // Can also be used in pipelines
- * const pipeline = createPipeline();
- * const result = pipeline(machine, debugMiddleware);
+ * @param config - Pipeline configuration
+ * @returns A function that executes middlewares in a pipeline
  */
-export function when<M extends BaseMachine<any>>(
-  middleware: MiddlewareFn<M>,
-  predicate: (machine: M) => boolean
-): ConditionalMiddleware<M> & MiddlewareFn<M> {
-  const conditional: ConditionalMiddleware<M> & MiddlewareFn<M> = function(machine: M) {
-    return predicate(machine) ? middleware(machine) : machine;
-  };
+export function createPipeline<M extends BaseMachine<any>>(
+  config: PipelineConfig = {}
+): {
+  <Ms extends Array<MiddlewareFn<M> | ConditionalMiddleware<M>>>(
+    machine: M,
+    ...middlewares: Ms
+  ): { machine: M; errors: Array<{ error: Error; middlewareIndex: number; middlewareName?: string }>; success: boolean };
+} {
+  const {
+    continueOnError = false,
+    logErrors = true,
+    onError
+  } = config;
 
-  conditional.middleware = middleware;
-  conditional.when = predicate;
+  return (machine: M, ...middlewares: Array<MiddlewareFn<M> | ConditionalMiddleware<M>>) => {
+    let currentMachine = machine;
+    const errors: Array<{ error: Error; middlewareIndex: number; middlewareName?: string }> = [];
+    let success = true;
 
-  return conditional;
-}
+    for (let i = 0; i < middlewares.length; i++) {
+      const middleware = middlewares[i];
 
-/**
- * Create a middleware that only applies in development mode.
- *
- * @template M - The machine type
- * @param middleware - The middleware to apply in development
- * @returns A conditional middleware for development mode
- *
- * @example
- * const devMachine = composeTyped(
- *   counter,
- *   inDevelopment(withTimeTravel())
- * );
- */
-export function inDevelopment<M extends BaseMachine<any>>(
-  middleware: MiddlewareFn<M>
-): ConditionalMiddleware<M> & MiddlewareFn<M> {
-  return when(middleware, () => {
-    return typeof process !== 'undefined'
-      ? process.env.NODE_ENV === 'development'
-      : typeof window !== 'undefined'
-        ? !window.location.hostname.includes('production')
-        : false;
-  });
-}
+      try {
+        // Handle conditional middleware
+        if ('middleware' in middleware && 'when' in middleware) {
+          if (!middleware.when(currentMachine)) {
+            continue; // Skip this middleware
+          }
+          currentMachine = middleware.middleware(currentMachine);
+        } else {
+          // Regular middleware
+          currentMachine = (middleware as MiddlewareFn<M>)(currentMachine);
+        }
+      } catch (error) {
+        success = false;
+        if (!continueOnError) {
+          throw error;
+        }
 
-/**
- * Create a middleware that only applies when a context property matches a value.
- *
- * @template M - The machine type
- * @template K - The context key
- * @param key - The context property key
- * @param value - The value to match
- * @param middleware - The middleware to apply when the condition matches
- * @returns A conditional middleware
- *
- * @example
- * const adminMachine = composeTyped(
- *   userMachine,
- *   whenContext('role', 'admin', withAdminFeatures())
- * );
- */
-export function whenContext<M extends BaseMachine<any>, K extends keyof Context<M>>(
-  key: K,
-  value: Context<M>[K],
-  middleware: MiddlewareFn<M>
-): ConditionalMiddleware<M> & MiddlewareFn<M> {
-  return when(middleware, (machine) => machine.context[key] === value);
+        errors.push({
+          error: error as Error,
+          middlewareIndex: i,
+          middlewareName: (middleware as any).name
+        });
+
+        if (logErrors) {
+          console.error(`Pipeline middleware error at index ${i}:`, error);
+        }
+
+        onError?.(error as Error, i, (middleware as any).name);
+      }
+    }
+
+    return { machine: currentMachine, errors, success };
+  };
 }
 
+// =============================================================================
+// SECTION: UTILITY FUNCTIONS
+// =============================================================================
+
 /**
  * Combine multiple middlewares with short-circuiting.
- * If any middleware returns a different type, the composition stops.
- *
- * @template M - The machine type
- * @param middlewares - Array of middlewares to combine
- * @returns A combined middleware function
- *
- * @example
- * const combined = combine(
- *   withHistory(),
- *   withSnapshot(),
- *   withValidation()
- * );
  */
 export function combine<M extends BaseMachine<any>>(
   ...middlewares: Array<MiddlewareFn<M>>
@@ -2273,18 +1386,6 @@ export function combine<M extends BaseMachine<any>>(
 
 /**
  * Create a middleware that applies different middlewares based on context.
- *
- * @template M - The machine type
- * @param branches - Array of [predicate, middleware] pairs
- * @param fallback - Optional fallback middleware if no predicates match
- * @returns A branching middleware
- *
- * @example
- * const smartMiddleware = branch(
- *   [(m) => m.context.userType === 'admin', withAdminFeatures()],
- *   [(m) => m.context.debug, withTimeTravel()],
- *   withBasicLogging() // fallback
- * );
  */
 export function branch<M extends BaseMachine<any>>(
   branches: Array<[predicate: (machine: M) => boolean, middleware: MiddlewareFn<M>]>,
@@ -2300,6 +1401,10 @@ export function branch<M extends BaseMachine<any>>(
   };
 }
 
+// =============================================================================
+// SECTION: TYPE GUARDS
+// =============================================================================
+
 /**
  * Type guard to check if a value is a middleware function.
  */
@@ -2323,3 +1428,19 @@ export function isConditionalMiddleware<M extends BaseMachine<any>>(
     typeof value.when === 'function'
   );
 }
+
+// =============================================================================
+// SECTION: COMMON COMBINATIONS
+// =============================================================================
+
+/**
+ * Common middleware combination types for better DX.
+ */
+export type WithDebugging<M extends BaseMachine<any>> = WithTimeTravel<WithSnapshot<WithHistory<M>>>;
+
+/**
+ * Convenience function for the most common debugging middleware stack.
+ */
+export function withDebugging<M extends BaseMachine<any>>(machine: M): WithDebugging<M> {
+  return withTimeTravel(withSnapshot(withHistory(machine)));
+}