machina 6.0.0 → 6.1.0

package/dist/index.d.mts

@@ -1,12 +1,14 @@
+//#region src/emitter.d.ts
 /**
  * Returned by `on()`. Call `off()` to remove the subscription.
  * Safe to call multiple times — subsequent calls are no-ops because
  * the underlying Set deduplicates membership.
  */
 type Subscription = {
-    off(): void;
+  off(): void;
 };
-
+//#endregion
+//#region src/types.d.ts
 /**
  * Keys on a state object that have special meaning and are NOT input names.
  * Used by InputNamesOf to filter these out when collecting input names.
@@ -46,9 +48,7 @@ type StateNamesOf<TStates> = keyof TStates & string;
  *    handler keys across every state
  * 3. `Exclude<..., SpecialStateKeys>` — strips lifecycle/special keys
  */
-type InputNamesOf<TStates> = Exclude<{
-    [S in keyof TStates]: keyof TStates[S] & string;
-}[keyof TStates], SpecialStateKeys>;
+type InputNamesOf<TStates> = Exclude<{ [S in keyof TStates]: keyof TStates[S] & string }[keyof TStates], SpecialStateKeys>;
 /**
  * The single combined object passed to every handler.
  *
@@ -81,40 +81,40 @@ type InputNamesOf<TStates> = Exclude<{
  * ```
  */
 interface HandlerArgs<TCtx, TStateNames extends string = string> {
-    /** The context (Fsm) or client object (BehavioralFsm) */
-    ctx: TCtx;
-    /**
-     * The name of the input currently being handled.
-     *
-     * Typed as `string` rather than the inferred input union because:
-     * 1. Inside a named handler you already know the input name
-     * 2. In a catch-all (*) handler it could be anything
-     * 3. Narrowing to the literal per-handler would require complex
-     *    mapped types for zero practical benefit
-     */
-    inputName: string;
-    /**
-     * Defer the current input for replay after a future transition.
-     * Erlang's selective receive, in JS form.
-     *
-     * @example
-     * ```ts
-     * // Replay on the next transition to any state
-     * defer();
-     *
-     * // Replay only when entering "yellow"
-     * defer({ until: "yellow" });
-     * ```
-     */
-    defer(opts?: {
-        until: TStateNames;
-    }): void;
-    /**
-     * Emit a custom event through the FSM's emitter.
-     * Built-in events (transitioning, transitioned, etc.) are emitted
-     * automatically by the FSM engine — this is for user-defined events.
-     */
-    emit(eventName: string, data?: unknown): void;
+  /** The context (Fsm) or client object (BehavioralFsm) */
+  ctx: TCtx;
+  /**
+   * The name of the input currently being handled.
+   *
+   * Typed as `string` rather than the inferred input union because:
+   * 1. Inside a named handler you already know the input name
+   * 2. In a catch-all (*) handler it could be anything
+   * 3. Narrowing to the literal per-handler would require complex
+   *    mapped types for zero practical benefit
+   */
+  inputName: string;
+  /**
+   * Defer the current input for replay after a future transition.
+   * Erlang's selective receive, in JS form.
+   *
+   * @example
+   * ```ts
+   * // Replay on the next transition to any state
+   * defer();
+   *
+   * // Replay only when entering "yellow"
+   * defer({ until: "yellow" });
+   * ```
+   */
+  defer(opts?: {
+    until: TStateNames;
+  }): void;
+  /**
+   * Emit a custom event through the FSM's emitter.
+   * Built-in events (transitioning, transitioned, etc.) are emitted
+   * automatically by the FSM engine — this is for user-defined events.
+   */
+  emit(eventName: string, data?: unknown): void;
 }
 /**
  * A function handler for state inputs, lifecycle hooks (_onEnter, _onExit),
@@ -215,11 +215,7 @@ type HandlerDef<TCtx, TStateNames extends string = string> = TStateNames | Handl
  * @typeParam TStates - The literal states object type captured by the
  *   factory function's generic parameter
  */
-type ValidateStates<TCtx, TStates extends Record<string, Record<string, unknown>>> = {
-    [S in keyof TStates]: {
-        [K in keyof TStates[S]]: K extends "_onEnter" | "_onExit" ? HandlerFn<TCtx, keyof TStates & string> : K extends "_child" ? MachinaInstance : K extends "*" ? HandlerFn<TCtx, keyof TStates & string> : HandlerDef<TCtx, keyof TStates & string>;
-    };
-};
+type ValidateStates<TCtx, TStates extends Record<string, Record<string, unknown>>> = { [S in keyof TStates]: { [K in keyof TStates[S]]: K extends "_onEnter" | "_onExit" ? HandlerFn<TCtx, keyof TStates & string> : K extends "_child" ? MachinaInstance : K extends "*" ? HandlerFn<TCtx, keyof TStates & string> : HandlerDef<TCtx, keyof TStates & string> } };
 /**
  * Configuration object for creating an FSM.
  *
@@ -247,27 +243,27 @@ type ValidateStates<TCtx, TStates extends Record<string, Record<string, unknown>
  * ```
  */
 interface FsmConfig<TCtx, TStates extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> {
-    /** Unique identifier for this FSM */
-    id: string;
-    /**
-     * The state to start in. Must be a key of `states`.
-     *
-     * Wrapped in NoInfer to prevent TypeScript from using this value as an
-     * inference site for TStates. Without it, `initialState: "green"` could
-     * narrow TStates to only have a "green" key. We want inference to come
-     * exclusively from the `states` property.
-     */
-    initialState: NoInfer<keyof TStates & string>;
-    /**
-     * Initial context data. The type is inferred from this value and flows
-     * into every handler's `ctx` parameter.
-     *
-     * For BehavioralFsm, this property is optional and serves only as a
-     * type constraint — the client object IS the context.
-     */
-    context?: TCtx;
-    /** State definitions. Keys become the state name union. */
-    states: ValidateStates<TCtx, TStates>;
+  /** Unique identifier for this FSM */
+  id: string;
+  /**
+   * The state to start in. Must be a key of `states`.
+   *
+   * Wrapped in NoInfer to prevent TypeScript from using this value as an
+   * inference site for TStates. Without it, `initialState: "green"` could
+   * narrow TStates to only have a "green" key. We want inference to come
+   * exclusively from the `states` property.
+   */
+  initialState: NoInfer<keyof TStates & string>;
+  /**
+   * Initial context data. The type is inferred from this value and flows
+   * into every handler's `ctx` parameter.
+   *
+   * For BehavioralFsm, this property is optional and serves only as a
+   * type constraint — the client object IS the context.
+   */
+  context?: TCtx;
+  /** State definitions. Keys become the state name union. */
+  states: ValidateStates<TCtx, TStates>;
 }
 /**
  * Symbol used as a property key to identify machina FSM instances at runtime.
@@ -283,17 +279,44 @@ declare const MACHINA_TYPE: unique symbol;
 type MachinaType = "Fsm" | "BehavioralFsm";
 /** Structural type matching any machina FSM instance (Fsm or BehavioralFsm) */
 type MachinaInstance = {
-    readonly [MACHINA_TYPE]: MachinaType;
+  readonly [MACHINA_TYPE]: MachinaType;
 };
+/**
+ * Internal adapter that wraps either an Fsm or BehavioralFsm child,
+ * presenting a uniform API for parent-initiated delegation.
+ */
+interface ChildLink {
+  /** Check if the child's current state can handle this input */
+  canHandle(client: object, inputName: string): boolean;
+  /** Dispatch the input to the child */
+  handle(client: object, inputName: string, ...args: unknown[]): void;
+  /** Reset the child to its initialState */
+  reset(client: object): void;
+  /** Subscribe to all child events (wildcard). Returns unsubscribe fn. */
+  onAny(callback: (eventName: string, data: unknown) => void): {
+    off(): void;
+  };
+  /** The child FSM's compositeState for the given client */
+  compositeState(client: object): string;
+  /** Dispose the child FSM */
+  dispose(): void;
+  /**
+   * The raw Fsm or BehavioralFsm instance this ChildLink wraps.
+   * Exposed for inspection tooling (machina-inspect) — allows external
+   * tools to introspect child graph structure without reaching through
+   * private fields.
+   */
+  instance: MachinaInstance;
+}
 /**
  * Options for FSM disposal.
  */
 interface DisposeOptions {
-    /**
-     * When true, child FSMs declared via _child are NOT disposed.
-     * Default: false (children ARE disposed along with the parent).
-     */
-    preserveChildren?: boolean;
+  /**
+   * When true, child FSMs declared via _child are NOT disposed.
+   * Default: false (children ARE disposed along with the parent).
+   */
+  preserveChildren?: boolean;
 }
 /**
  * Built-in event map for Fsm instances.
@@ -303,37 +326,37 @@ interface DisposeOptions {
  *   event payloads so fromState/toState are narrowed to actual state names.
  */
 interface FsmEventMap<TStateNames extends string = string> {
-    /** Fired just before a state transition occurs */
-    transitioning: {
-        fromState: TStateNames;
-        toState: TStateNames;
-    };
-    /** Fired just after a state transition completes */
-    transitioned: {
-        fromState: TStateNames;
-        toState: TStateNames;
-    };
-    /** Fired when an input is about to be dispatched to a handler */
-    handling: {
-        inputName: string;
-    };
-    /** Fired after an input has been successfully handled */
-    handled: {
-        inputName: string;
-    };
-    /** Fired when an input has no matching handler in the current state */
-    nohandler: {
-        inputName: string;
-        args: unknown[];
-    };
-    /** Fired when a transition targets a state that doesn't exist */
-    invalidstate: {
-        stateName: string;
-    };
-    /** Fired when an input is deferred for later replay */
-    deferred: {
-        inputName: string;
-    };
+  /** Fired just before a state transition occurs */
+  transitioning: {
+    fromState: TStateNames;
+    toState: TStateNames;
+  };
+  /** Fired just after a state transition completes */
+  transitioned: {
+    fromState: TStateNames;
+    toState: TStateNames;
+  };
+  /** Fired when an input is about to be dispatched to a handler */
+  handling: {
+    inputName: string;
+  };
+  /** Fired after an input has been successfully handled */
+  handled: {
+    inputName: string;
+  };
+  /** Fired when an input has no matching handler in the current state */
+  nohandler: {
+    inputName: string;
+    args: unknown[];
+  };
+  /** Fired when a transition targets a state that doesn't exist */
+  invalidstate: {
+    stateName: string;
+  };
+  /** Fired when an input is deferred for later replay */
+  deferred: {
+    inputName: string;
+  };
 }
 /**
  * Built-in event map for BehavioralFsm instances.
@@ -343,12 +366,11 @@ interface FsmEventMap<TStateNames extends string = string> {
  * @typeParam TClient - The client object type
  * @typeParam TStateNames - The state name union
  */
-type BehavioralFsmEventMap<TClient, TStateNames extends string = string> = {
-    [K in keyof FsmEventMap<TStateNames>]: FsmEventMap<TStateNames>[K] & {
-        client: TClient;
-    };
-};
-
+type BehavioralFsmEventMap<TClient, TStateNames extends string = string> = { [K in keyof FsmEventMap<TStateNames>]: FsmEventMap<TStateNames>[K] & {
+  client: TClient;
+} };
+//#endregion
+//#region src/fsm.d.ts
 /**
  * Single-client FSM. Wraps a BehavioralFsm and uses the config's `context`
  * object as the implicit client, so callers never pass a client argument.
@@ -363,70 +385,72 @@ type BehavioralFsmEventMap<TClient, TStateNames extends string = string> = {
  * @typeParam TInputNames - String literal union of valid input names.
  */
 declare class Fsm<TCtx extends object, TStateNames extends string, TInputNames extends string> {
-    readonly id: string;
-    readonly [MACHINA_TYPE]: "Fsm";
-    private readonly bfsm;
-    private readonly context;
-    private readonly emitter;
-    private disposed;
-    constructor(config: FsmConfig<TCtx, Record<string, Record<string, unknown>>>);
-    /**
-     * Dispatch an input to the current state's handler.
-     * If a `_child` FSM in the current state can handle it, delegation occurs
-     * there first; unhandled inputs bubble up to the parent.
-     * No-ops silently when disposed.
-     */
-    handle(inputName: TInputNames, ...args: unknown[]): void;
-    /**
-     * Returns true if the current state has a handler for `inputName`
-     * (or a catch-all `"*"` handler). Does not trigger initialization
-     * or any side effects. Returns false when disposed.
-     */
-    canHandle(inputName: string): boolean;
-    /**
-     * Transition back to `initialState`, firing `_onEnter` and lifecycle
-     * events as if entering it fresh. No-ops silently when disposed.
-     */
-    reset(): void;
-    /**
-     * Returns the current state name. Always defined — Fsm eagerly
-     * initializes into `initialState` during construction.
-     */
-    currentState(): TStateNames;
-    /**
-     * Directly transition to `toState`, firing `_onExit`, `_onEnter`, and
-     * lifecycle events. Same-state transitions are silently ignored.
-     * No-ops when disposed.
-     */
-    transition(toState: TStateNames): void;
-    /**
-     * Returns the current state as a dot-delimited path that includes
-     * any active child FSM states (e.g. `"active.connecting.retrying"`).
-     * Returns just the current state name when no child is active.
-     */
-    compositeState(): string;
-    /**
-     * Subscribe to a built-in lifecycle event or the wildcard.
-     *
-     * Named overload: typed payload, no event name in callback.
-     * Wildcard (`"*"`): receives `(eventName, data)` for every event.
-     * Returns a no-op `Subscription` when disposed.
-     */
-    on<K extends keyof FsmEventMap<TStateNames> & string>(eventName: K, callback: (data: FsmEventMap<TStateNames>[K]) => void): Subscription;
-    on(eventName: "*", callback: (eventName: string, data: unknown) => void): Subscription;
-    /**
-     * Emit a custom event through the FSM. Built-in lifecycle events are
-     * emitted automatically — this is for user-defined events from handlers.
-     * Routes through the BehavioralFsm so all relay paths are consistent.
-     * No-ops when disposed.
-     */
-    emit(eventName: string, data?: unknown): void;
-    /**
-     * Permanently shut down this FSM. Irreversible — all subsequent method
-     * calls become silent no-ops. Clears all listeners and cascades disposal
-     * to child FSMs (unless `preserveChildren` is set).
-     */
-    dispose(options?: DisposeOptions): void;
+  readonly id: string;
+  readonly initialState: TStateNames;
+  readonly [MACHINA_TYPE]: "Fsm";
+  readonly states: Record<string, Record<string, unknown>>;
+  private readonly bfsm;
+  private readonly context;
+  private readonly emitter;
+  private disposed;
+  constructor(config: FsmConfig<TCtx, Record<string, Record<string, unknown>>>);
+  /**
+   * Dispatch an input to the current state's handler.
+   * If a `_child` FSM in the current state can handle it, delegation occurs
+   * there first; unhandled inputs bubble up to the parent.
+   * No-ops silently when disposed.
+   */
+  handle(inputName: TInputNames, ...args: unknown[]): void;
+  /**
+   * Returns true if the current state has a handler for `inputName`
+   * (or a catch-all `"*"` handler). Does not trigger initialization
+   * or any side effects. Returns false when disposed.
+   */
+  canHandle(inputName: string): boolean;
+  /**
+   * Transition back to `initialState`, firing `_onEnter` and lifecycle
+   * events as if entering it fresh. No-ops silently when disposed.
+   */
+  reset(): void;
+  /**
+   * Returns the current state name. Always defined — Fsm eagerly
+   * initializes into `initialState` during construction.
+   */
+  currentState(): TStateNames;
+  /**
+   * Directly transition to `toState`, firing `_onExit`, `_onEnter`, and
+   * lifecycle events. Same-state transitions are silently ignored.
+   * No-ops when disposed.
+   */
+  transition(toState: TStateNames): void;
+  /**
+   * Returns the current state as a dot-delimited path that includes
+   * any active child FSM states (e.g. `"active.connecting.retrying"`).
+   * Returns just the current state name when no child is active.
+   */
+  compositeState(): string;
+  /**
+   * Subscribe to a built-in lifecycle event or the wildcard.
+   *
+   * Named overload: typed payload, no event name in callback.
+   * Wildcard (`"*"`): receives `(eventName, data)` for every event.
+   * Returns a no-op `Subscription` when disposed.
+   */
+  on<K extends keyof FsmEventMap<TStateNames> & string>(eventName: K, callback: (data: FsmEventMap<TStateNames>[K]) => void): Subscription;
+  on(eventName: "*", callback: (eventName: string, data: unknown) => void): Subscription;
+  /**
+   * Emit a custom event through the FSM. Built-in lifecycle events are
+   * emitted automatically — this is for user-defined events from handlers.
+   * Routes through the BehavioralFsm so all relay paths are consistent.
+   * No-ops when disposed.
+   */
+  emit(eventName: string, data?: unknown): void;
+  /**
+   * Permanently shut down this FSM. Irreversible — all subsequent method
+   * calls become silent no-ops. Clears all listeners and cascades disposal
+   * to child FSMs (unless `preserveChildren` is set).
+   */
+  dispose(options?: DisposeOptions): void;
 }
 /**
  * Create a single-client FSM from a config object.
@@ -456,7 +480,8 @@ declare class Fsm<TCtx extends object, TStateNames extends string, TInputNames e
  * ```
  */
 declare function createFsm<TCtx extends object = Record<string, never>, const TStates extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>>(config: FsmConfig<TCtx, TStates>): Fsm<TCtx, StateNamesOf<TStates>, InputNamesOf<TStates>>;
-
+//#endregion
+//#region src/behavioral-fsm.d.ts
 /**
  * Defines FSM behavior (states + transitions) while tracking per-client state
  * in a `WeakMap`. A single `BehavioralFsm` instance can drive any number of
@@ -474,124 +499,124 @@ declare function createFsm<TCtx extends object = Record<string, never>, const TS
  * @typeParam TInputNames - String literal union of valid input names.
  */
 declare class BehavioralFsm<TClient extends object, TStateNames extends string, TInputNames extends string> {
-    readonly id: string;
-    readonly initialState: TStateNames;
-    readonly [MACHINA_TYPE]: "BehavioralFsm";
-    private readonly states;
-    private readonly emitter;
-    private readonly clients;
-    private readonly knownClients;
-    private readonly childSubscriptions;
-    private disposed;
-    private transitionDepth;
-    constructor(config: FsmConfig<TClient, Record<string, Record<string, unknown>>>);
-    /**
-     * Dispatch an input to the given client's current state handler.
-     *
-     * Delegation order: if the current state has a `_child` FSM that can
-     * handle the input, it is dispatched there. If the child emits `nohandler`,
-     * the input bubbles up to this FSM's local handler. If no handler exists
-     * here either, `nohandler` is emitted on this FSM's emitter.
-     *
-     * No-ops silently when disposed.
-     */
-    handle(client: TClient, inputName: TInputNames, ...args: unknown[]): void;
-    /**
-     * Returns true if the client's current state has a handler for `inputName`
-     * (or a catch-all `"*"` handler). Does NOT initialize the client — no
-     * `_onEnter`, no events, no side effects. Unseen clients are treated as
-     * if they were already in `initialState`. Returns false when disposed.
-     */
-    canHandle(client: TClient, inputName: string): boolean;
-    /**
-     * Transition the client back to `initialState`, firing `_onEnter` and
-     * lifecycle events as if entering it fresh. No-ops when disposed.
-     */
-    reset(client: TClient): void;
-    /**
-     * Returns the client's current state, or `undefined` if the client has
-     * never been initialized (i.e. `handle()`, `transition()`, or `reset()`
-     * have never been called for it). Does NOT trigger initialization.
-     */
-    currentState(client: TClient): TStateNames | undefined;
-    /**
-     * Directly transition `client` to `toState`, running the full lifecycle:
-     * `_onExit` for the current state → `transitioning` event → update state →
-     * `_onEnter` for new state → `transitioned` event → child reset → deferred
-     * queue replay → bounce (if `_onEnter` returned a state name).
-     *
-     * Same-state transitions are silently ignored. Transitions to unknown state
-     * names emit `invalidstate` instead of throwing. Throws if the transition
-     * depth exceeds `MAX_TRANSITION_DEPTH` (likely an `_onEnter` → transition loop).
-     *
-     * No-ops when disposed.
-     */
-    transition(client: TClient, toState: TStateNames): void;
-    /**
-     * Returns the client's state as a dot-delimited path including any active
-     * child FSM states (e.g. `"active.connecting.retrying"`). Returns just the
-     * current state name when no child is active. Returns `""` for clients that
-     * have never been initialized (unlike `currentState()` which returns `undefined`).
-     */
-    compositeState(client: TClient): string;
-    /**
-     * Subscribe to a built-in lifecycle event or the wildcard.
-     *
-     * Named overload: typed payload includes `{ client: TClient }` so you can
-     * identify which client the event pertains to. Wildcard (`"*"`) receives
-     * `(eventName, data)` for every event. Returns a no-op `Subscription`
-     * when disposed.
-     */
-    on<K extends keyof BehavioralFsmEventMap<TClient, TStateNames> & string>(eventName: K, callback: (data: BehavioralFsmEventMap<TClient, TStateNames>[K]) => void): Subscription;
-    on(eventName: "*", callback: (eventName: string, data: unknown) => void): Subscription;
-    /**
-     * Emit a custom event through the FSM. Built-in lifecycle events are
-     * emitted automatically — this is for user-defined events from handlers.
-     * No-ops when disposed.
-     */
-    emit(eventName: string, data?: unknown): void;
-    /**
-     * Permanently shut down this FSM. Irreversible — all subsequent method
-     * calls become silent no-ops. Tears down child subscriptions, clears all
-     * listeners, and cascades disposal to child FSMs (unless `preserveChildren`
-     * is set). The same child appearing in multiple states is disposed once.
-     */
-    dispose(options?: DisposeOptions): void;
-    /**
-     * Walks all states at construction time, detects raw FSM instances assigned
-     * to _child, and wraps them into ChildLink adapters via createChildLink().
-     * Must run BEFORE setupChildSubscriptions() so the subscriptions see
-     * ChildLink objects, not raw FSM instances.
-     */
-    private wrapChildLinks;
-    /**
-     * Walks all states at construction time, finds states with _child, and
-     * subscribes once to each unique child's wildcard events. Subscriptions are
-     * stored for cleanup in dispose(). We deduplicate by child reference to
-     * avoid double-subscribing when the same child appears in multiple states.
-     */
-    private setupChildSubscriptions;
-    /**
-     * Bubbles a child nohandler to the parent for the given client.
-     * Only fires if the client is currently in a state that has this childLink.
-     * Extracted from the lambda in setupChildSubscriptions to keep it readable.
-     */
-    private bubbleNohandler;
-    /**
-     * Returns true if the given client is currently in a parent state whose
-     * _child is the specified childLink. Returns false if the client has no
-     * meta (never initialized) or is in a state with a different (or no) child.
-     */
-    private isChildActiveForClient;
-    /**
-     * The inner handler dispatch — no delegation, no initialization side effects
-     * beyond what getOrCreateClientMeta already did. Called by handle() after
-     * the delegation check, and by the nohandler child listener for bubbling.
-     */
-    private handleLocally;
-    private getOrCreateClientMeta;
-    private buildHandlerArgs;
-    private processQueue;
+  readonly id: string;
+  readonly initialState: TStateNames;
+  readonly [MACHINA_TYPE]: "BehavioralFsm";
+  readonly states: Record<string, Record<string, unknown>>;
+  private readonly emitter;
+  private readonly clients;
+  private readonly knownClients;
+  private readonly childSubscriptions;
+  private disposed;
+  private transitionDepth;
+  constructor(config: FsmConfig<TClient, Record<string, Record<string, unknown>>>);
+  /**
+   * Dispatch an input to the given client's current state handler.
+   *
+   * Delegation order: if the current state has a `_child` FSM that can
+   * handle the input, it is dispatched there. If the child emits `nohandler`,
+   * the input bubbles up to this FSM's local handler. If no handler exists
+   * here either, `nohandler` is emitted on this FSM's emitter.
+   *
+   * No-ops silently when disposed.
+   */
+  handle(client: TClient, inputName: TInputNames, ...args: unknown[]): void;
+  /**
+   * Returns true if the client's current state has a handler for `inputName`
+   * (or a catch-all `"*"` handler). Does NOT initialize the client — no
+   * `_onEnter`, no events, no side effects. Unseen clients are treated as
+   * if they were already in `initialState`. Returns false when disposed.
+   */
+  canHandle(client: TClient, inputName: string): boolean;
+  /**
+   * Transition the client back to `initialState`, firing `_onEnter` and
+   * lifecycle events as if entering it fresh. No-ops when disposed.
+   */
+  reset(client: TClient): void;
+  /**
+   * Returns the client's current state, or `undefined` if the client has
+   * never been initialized (i.e. `handle()`, `transition()`, or `reset()`
+   * have never been called for it). Does NOT trigger initialization.
+   */
+  currentState(client: TClient): TStateNames | undefined;
+  /**
+   * Directly transition `client` to `toState`, running the full lifecycle:
+   * `_onExit` for the current state → `transitioning` event → update state →
+   * `_onEnter` for new state → `transitioned` event → child reset → deferred
+   * queue replay → bounce (if `_onEnter` returned a state name).
+   *
+   * Same-state transitions are silently ignored. Transitions to unknown state
+   * names emit `invalidstate` instead of throwing. Throws if the transition
+   * depth exceeds `MAX_TRANSITION_DEPTH` (likely an `_onEnter` → transition loop).
+   *
+   * No-ops when disposed.
+   */
+  transition(client: TClient, toState: TStateNames): void;
+  /**
+   * Returns the client's state as a dot-delimited path including any active
+   * child FSM states (e.g. `"active.connecting.retrying"`). Returns just the
+   * current state name when no child is active. Returns `""` for clients that
+   * have never been initialized (unlike `currentState()` which returns `undefined`).
+   */
+  compositeState(client: TClient): string;
+  /**
+   * Subscribe to a built-in lifecycle event or the wildcard.
+   *
+   * Named overload: typed payload includes `{ client: TClient }` so you can
+   * identify which client the event pertains to. Wildcard (`"*"`) receives
+   * `(eventName, data)` for every event. Returns a no-op `Subscription`
+   * when disposed.
+   */
+  on<K extends keyof BehavioralFsmEventMap<TClient, TStateNames> & string>(eventName: K, callback: (data: BehavioralFsmEventMap<TClient, TStateNames>[K]) => void): Subscription;
+  on(eventName: "*", callback: (eventName: string, data: unknown) => void): Subscription;
+  /**
+   * Emit a custom event through the FSM. Built-in lifecycle events are
+   * emitted automatically — this is for user-defined events from handlers.
+   * No-ops when disposed.
+   */
+  emit(eventName: string, data?: unknown): void;
+  /**
+   * Permanently shut down this FSM. Irreversible — all subsequent method
+   * calls become silent no-ops. Tears down child subscriptions, clears all
+   * listeners, and cascades disposal to child FSMs (unless `preserveChildren`
+   * is set). The same child appearing in multiple states is disposed once.
+   */
+  dispose(options?: DisposeOptions): void;
+  /**
+   * Walks all states at construction time, detects raw FSM instances assigned
+   * to _child, and wraps them into ChildLink adapters via createChildLink().
+   * Must run BEFORE setupChildSubscriptions() so the subscriptions see
+   * ChildLink objects, not raw FSM instances.
+   */
+  private wrapChildLinks;
+  /**
+   * Walks all states at construction time, finds states with _child, and
+   * subscribes once to each unique child's wildcard events. Subscriptions are
+   * stored for cleanup in dispose(). We deduplicate by child reference to
+   * avoid double-subscribing when the same child appears in multiple states.
+   */
+  private setupChildSubscriptions;
+  /**
+   * Bubbles a child nohandler to the parent for the given client.
+   * Only fires if the client is currently in a state that has this childLink.
+   * Extracted from the lambda in setupChildSubscriptions to keep it readable.
+   */
+  private bubbleNohandler;
+  /**
+   * Returns true if the given client is currently in a parent state whose
+   * _child is the specified childLink. Returns false if the client has no
+   * meta (never initialized) or is in a state with a different (or no) child.
+   */
+  private isChildActiveForClient;
+  /**
+   * The inner handler dispatch — no delegation, no initialization side effects
+   * beyond what getOrCreateClientMeta already did. Called by handle() after
+   * the delegation check, and by the nohandler child listener for bubbling.
+   */
+  private handleLocally;
+  private getOrCreateClientMeta;
+  private buildHandlerArgs;
+  private processQueue;
 }
 /**
  * Create a behavioral FSM (one definition, many clients) from a config object.
@@ -624,5 +649,6 @@ declare class BehavioralFsm<TClient extends object, TStateNames extends string,
  * ```
  */
 declare function createBehavioralFsm<TClient extends object, const TStates extends Record<string, Record<string, unknown>>>(config: FsmConfig<TClient, TStates>): BehavioralFsm<TClient, StateNamesOf<TStates>, InputNamesOf<TStates>>;
-
-export { BehavioralFsm, type BehavioralFsmEventMap, type DisposeOptions, Fsm, type FsmConfig, type FsmEventMap, type HandlerArgs, type HandlerDef, type HandlerFn, type InputNamesOf, type MachinaInstance, type StateNamesOf, type Subscription, createBehavioralFsm, createFsm };
+//#endregion
+export { BehavioralFsm, type BehavioralFsmEventMap, type ChildLink, type DisposeOptions, Fsm, type FsmConfig, type FsmEventMap, type HandlerArgs, type HandlerDef, type HandlerFn, type InputNamesOf, MACHINA_TYPE, type MachinaInstance, type StateNamesOf, type Subscription, createBehavioralFsm, createFsm };
+//# sourceMappingURL=index.d.mts.map