machina 6.0.0 → 6.1.0

package/dist/index.d.cts

@@ -0,0 +1,654 @@
+//#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;
+};
+//#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.
+ */
+type SpecialStateKeys = "_onEnter" | "_onExit" | "_child" | "*";
+/**
+ * Extracts state names as a string literal union from a states config object.
+ *
+ * @example
+ * ```ts
+ * type S = StateNamesOf<{ green: {...}, yellow: {...}, red: {...} }>;
+ * // => "green" | "yellow" | "red"
+ * ```
+ */
+type StateNamesOf<TStates> = keyof TStates & string;
+/**
+ * Extracts input names as a string literal union from a states config object.
+ * Collects all handler keys across ALL states, then strips out lifecycle hooks
+ * and special keys (_onEnter, _onExit, _child, *).
+ *
+ * This is what flows into `handle(inputName)` to provide compile-time
+ * validation of input names.
+ *
+ * @example
+ * ```ts
+ * type I = InputNamesOf<{
+ *   idle:    { start: "running", reset: fn };
+ *   running: { pause: "paused", stop: "idle" };
+ * }>;
+ * // => "start" | "reset" | "pause" | "stop"
+ * ```
+ *
+ * How it works:
+ * 1. `{ [S in keyof TStates]: keyof TStates[S] & string }` — maps each state
+ *    to the union of its handler key names
+ * 2. `[keyof TStates]` — collapses the mapped type into a flat union of ALL
+ *    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>;
+/**
+ * The single combined object passed to every handler.
+ *
+ * Handlers return a state name to transition, or void to stay put.
+ * This replaces imperative `transition()` calls — closer to gen_fsm's
+ * return-based model and symmetrical with string shorthand handlers.
+ *
+ * @typeParam TCtx - The context type. For Fsm this is the config-defined
+ *   context object. For BehavioralFsm this is the client object itself.
+ * @typeParam TStateNames - String literal union of valid state names.
+ *   Defaults to `string` for loose usage; the factory functions narrow this
+ *   to the actual state names inferred from the config.
+ *
+ * @example
+ * ```ts
+ * // Conditional transition — return the target state:
+ * timeout({ ctx }) {
+ *   if (ctx.tickCount >= 3) return "yellow";
+ * }
+ *
+ * // Side effects without transition — return nothing:
+ * tick({ ctx }) {
+ *   ctx.tickCount++;
+ * }
+ *
+ * // In a catch-all — inputName tells you what was received:
+ * "*"({ inputName }) {
+ *   console.log(`unhandled input: ${inputName}`);
+ * }
+ * ```
+ */
+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;
+}
+/**
+ * A function handler for state inputs, lifecycle hooks (_onEnter, _onExit),
+ * and catch-all (*) handlers.
+ *
+ * **Return value determines transition:**
+ * - Return a valid state name → FSM transitions to that state
+ * - Return void/undefined → FSM stays in the current state
+ *
+ * This mirrors gen_fsm's `{next_state, StateName, NewStateData}` return.
+ * Guards are just `if` statements. Actions are just code before the return.
+ *
+ * The `...extra` rest parameter captures additional arguments passed through
+ * `handle(inputName, ...extraArgs)`. These are untyped (`unknown[]`) because
+ * correlating per-input arg types with handle() call sites would require
+ * prohibitively complex mapped types for minimal benefit.
+ *
+ * @example
+ * ```ts
+ * // Side effects only, no transition:
+ * tick({ ctx }) { ctx.tickCount++; }
+ *
+ * // Conditional transition (replaces guard + target):
+ * timeout({ ctx }) {
+ *   if (ctx.tickCount >= 3) return "yellow";
+ * }
+ *
+ * // Unconditional transition with side effect (replaces action + target):
+ * timeout({ ctx }) {
+ *   console.log("transitioning after", ctx.tickCount, "ticks");
+ *   return "yellow";
+ * }
+ *
+ * // Handler with extra args passed via handle("success", responseData):
+ * success({ ctx }, data) { ctx.result = data; }
+ * ```
+ */
+type HandlerFn<TCtx, TStateNames extends string = string> = (args: HandlerArgs<TCtx, TStateNames>, ...extra: unknown[]) => TStateNames | void;
+/**
+ * The union of valid handler definition forms for a state input.
+ *
+ * - `TStateNames` — string shorthand, auto-transitions to that state
+ * - `HandlerFn` — function that returns a state name (transition) or void (stay)
+ *
+ * @example
+ * ```ts
+ * states: {
+ *   green: {
+ *     timeout: "yellow",                    // string shorthand
+ *     tick({ ctx }) { ctx.tickCount++; },   // function, no transition
+ *     emergency({ ctx }) {                  // function, conditional transition
+ *       if (ctx.severity > 5) return "red";
+ *     },
+ *   },
+ * }
+ * ```
+ */
+/**
+ * The union of valid handler definition forms for a state input.
+ *
+ * - `TStateNames` — string shorthand, auto-transitions to that state
+ * - `HandlerFn` — function that returns a state name (transition) or void (stay)
+ * - `MachinaInstance` — included to satisfy TypeScript's structural widening
+ *   when `ValidateStates` falls back to its constraint type. The per-key
+ *   restriction on `_child` is still enforced by `ValidateStates`; this
+ *   union member just prevents the inference engine from rejecting
+ *   `_child: childFsm` before the conditional mapping can evaluate it.
+ *
+ * @example
+ * ```ts
+ * states: {
+ *   green: {
+ *     timeout: "yellow",                    // string shorthand
+ *     tick({ ctx }) { ctx.tickCount++; },   // function, no transition
+ *     emergency({ ctx }) {                  // function, conditional transition
+ *       if (ctx.severity > 5) return "red";
+ *     },
+ *   },
+ * }
+ * ```
+ */
+type HandlerDef<TCtx, TStateNames extends string = string> = TStateNames | HandlerFn<TCtx, TStateNames> | MachinaInstance;
+/**
+ * Validates and constrains the states object at the type level.
+ *
+ * This is a mapped type that walks every state and every property within
+ * each state, assigning the correct expected type based on the property key:
+ *
+ * | Key              | Expected type                           |
+ * |------------------|-----------------------------------------|
+ * | `_onEnter`       | HandlerFn (lifecycle hook)              |
+ * | `_onExit`        | HandlerFn (lifecycle hook)              |
+ * | `_child`         | MachinaInstance (Fsm or BehavioralFsm)  |
+ * | `*`              | HandlerFn (catch-all)                   |
+ * | anything else    | HandlerDef (string or fn)               |
+ *
+ * @typeParam TCtx - Context/client type, flows into handler signatures
+ * @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> } };
+/**
+ * Configuration object for creating an FSM.
+ *
+ * @typeParam TCtx - The context type (Fsm) or client type (BehavioralFsm).
+ *   For Fsm, this is inferred from the `context` property. For BehavioralFsm,
+ *   it's the client object type provided explicitly or as a generic parameter.
+ *
+ * @typeParam TStates - The literal states object type. Captured by the factory
+ *   function's generic parameter (ideally with `const` to preserve string
+ *   literal types). Defaults to a loose record for unconstrained usage.
+ *
+ * @example
+ * ```ts
+ * // TCtx inferred as { tickCount: number }, TStates inferred from states object:
+ * createFsm({
+ *   id: "traffic-light",
+ *   initialState: "green",         // validated against state keys
+ *   context: { tickCount: 0 },     // inference site for TCtx
+ *   states: {
+ *     green:  { timeout: "yellow" }, // "yellow" validated against state keys
+ *     yellow: { timeout: "red" },
+ *     red:    { timeout: "green" },
+ *   },
+ * });
+ * ```
+ */
+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>;
+}
+/**
+ * Symbol used as a property key to identify machina FSM instances at runtime.
+ * Each class stamps itself with a MachinaType value so the ChildLink adapter
+ * can dispatch handle()/canHandle()/reset() correctly without circular imports.
+ */
+declare const MACHINA_TYPE: unique symbol;
+/**
+ * Discriminant values stamped onto FSM instances via `MACHINA_TYPE`.
+ * Used by the `ChildLink` adapter to dispatch calls correctly without
+ * importing either class directly (which would create circular dependencies).
+ */
+type MachinaType = "Fsm" | "BehavioralFsm";
+/** Structural type matching any machina FSM instance (Fsm or BehavioralFsm) */
+type MachinaInstance = {
+  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;
+}
+/**
+ * Built-in event map for Fsm instances.
+ * Payloads do NOT include a client reference (Fsm is its own client).
+ *
+ * @typeParam TStateNames - The state name union, flows into transition
+ *   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;
+  };
+}
+/**
+ * Built-in event map for BehavioralFsm instances.
+ * Every payload is intersected with `{ client: TClient }` so subscribers
+ * can identify which client the event pertains to.
+ *
+ * @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;
+} };
+//#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.
+ *
+ * Prefer `createFsm()` over constructing this directly — the factory infers
+ * all generic parameters from the config object.
+ *
+ * All public methods silently no-op after `dispose()` is called.
+ *
+ * @typeParam TCtx - The context type, inferred from `config.context`.
+ * @typeParam TStateNames - String literal union of valid state names.
+ * @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 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.
+ *
+ * Generic parameters are inferred automatically:
+ * - `TCtx` comes from `config.context` (defaults to `{}` if omitted).
+ * - `TStates` is captured with `const` inference to preserve string literal
+ *   types, enabling compile-time validation of transition targets and `handle()`
+ *   input names.
+ *
+ * State names, input names, and all handler signatures derive from `TStates`.
+ *
+ * @example
+ * ```ts
+ * const light = createFsm({
+ *   id: "traffic-light",
+ *   initialState: "green",
+ *   context: { tickCount: 0 },
+ *   states: {
+ *     green:  { timeout: "yellow" },
+ *     yellow: { timeout: "red" },
+ *     red:    { timeout: "green" },
+ *   },
+ * });
+ *
+ * light.handle("timeout"); // transitions green → yellow
+ * ```
+ */
+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
+ * independent client objects simultaneously — each gets its own state,
+ * deferred queue, and lifecycle.
+ *
+ * Prefer `createBehavioralFsm()` over constructing this directly — the factory
+ * infers all generic parameters from the config object.
+ *
+ * All public methods silently no-op after `dispose()` is called.
+ *
+ * @typeParam TClient - The client object type. Must be an object (non-primitive)
+ *   so it can serve as a WeakMap key.
+ * @typeParam TStateNames - String literal union of valid state names.
+ * @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";
+  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.
+ *
+ * Generic parameters are inferred automatically:
+ * - `TClient` must be provided explicitly as a type parameter (it can't be
+ *   inferred from the config since no `context` property exists at the FSM level).
+ * - `TStates` is captured with `const` inference to preserve string literal
+ *   types, enabling compile-time validation of transition targets and `handle()`
+ *   input names.
+ *
+ * State names, input names, and all handler signatures derive from `TStates`.
+ *
+ * @example
+ * ```ts
+ * interface Connection { url: string; retries: number; }
+ *
+ * const connFsm = createBehavioralFsm<Connection>({
+ *   id: "connectivity",
+ *   initialState: "disconnected",
+ *   states: {
+ *     disconnected: { connect: "connecting" },
+ *     connecting:   { connected: "online", failed: "disconnected" },
+ *     online:       { disconnect: "disconnected" },
+ *   },
+ * });
+ *
+ * const conn = { url: "wss://example.com", retries: 0 };
+ * connFsm.handle(conn, "connect");
+ * ```
+ */
+declare function createBehavioralFsm<TClient extends object, const TStates extends Record<string, Record<string, unknown>>>(config: FsmConfig<TClient, TStates>): BehavioralFsm<TClient, StateNamesOf<TStates>, InputNamesOf<TStates>>;
+//#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.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/emitter.ts","../src/types.ts","../src/fsm.ts","../src/behavioral-fsm.ts"],"mappings":"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"}