machina 6.0.0 → 6.1.0

package/dist/index.mjs

@@ -1,651 +1,655 @@
-// src/emitter.ts
+//#region src/emitter.ts
+/**
+* Minimal typed event emitter used internally by Fsm and BehavioralFsm.
+*
+* Two listener categories exist at runtime: named listeners (keyed by event
+* name) and wildcard listeners (keyed as `"*"`). The wildcard fires on EVERY
+* emit, regardless of event name, and its callback receives both the event
+* name and the data. Named listeners receive only the data.
+*
+* @typeParam TEventMap - Record mapping event names to their payload types.
+*   Constrains `on()` and `emit()` to matching event/payload pairs.
+*/
 var Emitter = class {
-  listeners = /* @__PURE__ */ new Map();
-  on(event, cb) {
-    let set = this.listeners.get(event);
-    if (!set) {
-      set = /* @__PURE__ */ new Set();
-      this.listeners.set(event, set);
-    }
-    set.add(cb);
-    return {
-      off: () => {
-        set.delete(cb);
-      }
-    };
-  }
-  /**
-   * Emit a named event, notifying wildcard listeners first, then named listeners.
-   *
-   * Wildcard listeners receive `(eventName, data)`; named listeners receive
-   * only `data`. The firing order (wildcards before named) is intentional —
-   * it lets relay listeners (like Fsm's bfsm proxy) observe all events
-   * before specific subscribers react.
-   */
-  emit(event, data) {
-    const wildcards = this.listeners.get("*");
-    if (wildcards) {
-      for (const cb of wildcards) {
-        cb(event, data);
-      }
-    }
-    const named = this.listeners.get(event);
-    if (named) {
-      for (const cb of named) {
-        cb(data);
-      }
-    }
-  }
-  /**
-   * Remove all listeners (named and wildcard).
-   *
-   * Existing `Subscription` objects remain valid — their `off()` closures
-   * hold a reference to the now-empty Set, so calling them is harmless.
-   * Called by `dispose()` to prevent memory retention after an FSM shuts down.
-   */
-  clear() {
-    this.listeners.clear();
-  }
+	listeners = /* @__PURE__ */ new Map();
+	on(event, cb) {
+		let set = this.listeners.get(event);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.listeners.set(event, set);
+		}
+		set.add(cb);
+		return { off: () => {
+			set.delete(cb);
+		} };
+	}
+	/**
+	* Emit a named event, notifying wildcard listeners first, then named listeners.
+	*
+	* Wildcard listeners receive `(eventName, data)`; named listeners receive
+	* only `data`. The firing order (wildcards before named) is intentional —
+	* it lets relay listeners (like Fsm's bfsm proxy) observe all events
+	* before specific subscribers react.
+	*/
+	emit(event, data) {
+		const wildcards = this.listeners.get("*");
+		if (wildcards) for (const cb of wildcards) cb(event, data);
+		const named = this.listeners.get(event);
+		if (named) for (const cb of named) cb(data);
+	}
+	/**
+	* Remove all listeners (named and wildcard).
+	*
+	* Existing `Subscription` objects remain valid — their `off()` closures
+	* hold a reference to the now-empty Set, so calling them is harmless.
+	* Called by `dispose()` to prevent memory retention after an FSM shuts down.
+	*/
+	clear() {
+		this.listeners.clear();
+	}
 };
 
-// src/types.ts
-var MACHINA_TYPE = /* @__PURE__ */ Symbol("machina.type");
+//#endregion
+//#region src/types.ts
+/**
+* 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.
+*/
+const MACHINA_TYPE = Symbol("machina.type");
 
-// src/behavioral-fsm.ts
-var MAX_TRANSITION_DEPTH = 20;
+//#endregion
+//#region src/behavioral-fsm.ts
+const MAX_TRANSITION_DEPTH = 20;
+/**
+* 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.
+*/
 var BehavioralFsm = class {
-  id;
-  initialState;
-  // Type discriminant — lets ChildLink adapter identify this at runtime
-  [MACHINA_TYPE] = "BehavioralFsm";
-  states;
-  emitter = new Emitter();
-  clients = /* @__PURE__ */ new WeakMap();
-  // Tracks all initialized clients so the Fsm-child nohandler listener can
-  // find which clients need bubbling (Fsm events have no client in payload).
-  // WeakRef prevents retention; clients clean themselves up naturally.
-  knownClients = /* @__PURE__ */ new Set();
-  // Subscriptions to child FSM wildcard events, keyed by state name.
-  // Set up once during construction, torn down in dispose().
-  childSubscriptions = [];
-  disposed = false;
-  transitionDepth = 0;
-  constructor(config) {
-    this.id = config.id;
-    this.initialState = config.initialState;
-    this.states = config.states;
-    this.wrapChildLinks();
-    this.setupChildSubscriptions();
-  }
-  // -------------------------------------------------------------------------
-  // Public API
-  // -------------------------------------------------------------------------
-  /**
-   * 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, inputName, ...args) {
-    if (this.disposed) {
-      return;
-    }
-    const meta = this.getOrCreateClientMeta(client);
-    meta.currentActionArgs = args;
-    const stateObj = this.states[meta.state];
-    const childLink = stateObj?._child;
-    if (childLink) {
-      if (childLink.canHandle(client, inputName)) {
-        try {
-          childLink.handle(client, inputName, ...args);
-        } finally {
-          meta.currentActionArgs = void 0;
-        }
-        return;
-      }
-    }
-    this.handleLocally(client, inputName, args, meta);
-  }
-  /**
-   * 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, inputName) {
-    if (this.disposed) {
-      return false;
-    }
-    const state = this.clients.get(client)?.state ?? this.initialState;
-    const stateObj = this.states[state];
-    return !!(stateObj?.[inputName] ?? stateObj?.["*"]);
-  }
-  /**
-   * Transition the client back to `initialState`, firing `_onEnter` and
-   * lifecycle events as if entering it fresh. No-ops when disposed.
-   */
-  reset(client) {
-    if (this.disposed) {
-      return;
-    }
-    this.transition(client, this.initialState);
-  }
-  /**
-   * 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) {
-    return this.clients.get(client)?.state;
-  }
-  /**
-   * 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, toState) {
-    if (this.disposed) {
-      return;
-    }
-    const meta = this.getOrCreateClientMeta(client);
-    const fromState = meta.state;
-    if (toState === fromState) {
-      return;
-    }
-    if (!(toState in this.states)) {
-      this.emitter.emit("invalidstate", { stateName: toState, client });
-      return;
-    }
-    this.transitionDepth++;
-    if (this.transitionDepth > MAX_TRANSITION_DEPTH) {
-      this.transitionDepth = 0;
-      throw new Error(
-        `Max transition depth (${MAX_TRANSITION_DEPTH}) exceeded in FSM "${this.id}". Likely an infinite _onEnter \u2192 transition loop.`
-      );
-    }
-    try {
-      const curStateObj = this.states[fromState];
-      const newStateObj = this.states[toState];
-      if (curStateObj?._onExit && typeof curStateObj._onExit === "function") {
-        const exitArgs = this.buildHandlerArgs(client, "", meta);
-        curStateObj._onExit(exitArgs);
-      }
-      meta.state = toState;
-      const payload = { fromState, toState, client };
-      this.emitter.emit("transitioning", payload);
-      let bounceTarget = void 0;
-      if (newStateObj?._onEnter && typeof newStateObj._onEnter === "function") {
-        const enterArgs = this.buildHandlerArgs(client, "", meta);
-        bounceTarget = newStateObj._onEnter(enterArgs);
-      }
-      this.emitter.emit("transitioned", payload);
-      const childLink = newStateObj?._child;
-      if (childLink) {
-        childLink.reset(client);
-      }
-      this.processQueue(client, meta);
-      if (typeof bounceTarget === "string" && meta.state === toState) {
-        this.transition(client, bounceTarget);
-      }
-    } finally {
-      this.transitionDepth--;
-    }
-  }
-  /**
-   * 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) {
-    const meta = this.clients.get(client);
-    if (!meta) {
-      return "";
-    }
-    const stateObj = this.states[meta.state];
-    const childLink = stateObj?._child;
-    if (childLink) {
-      const childComposite = childLink.compositeState(client);
-      if (childComposite) {
-        return `${meta.state}.${childComposite}`;
-      }
-    }
-    return meta.state;
-  }
-  on(eventName, callback) {
-    if (this.disposed) {
-      return { off() {
-      } };
-    }
-    return this.emitter.on(eventName, callback);
-  }
-  /**
-   * 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, data) {
-    if (this.disposed) {
-      return;
-    }
-    this.emitter.emit(eventName, data);
-  }
-  /**
-   * 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) {
-    this.disposed = true;
-    for (const sub of this.childSubscriptions) {
-      sub.off();
-    }
-    if (!options?.preserveChildren) {
-      const seen = /* @__PURE__ */ new Set();
-      for (const stateName of Object.keys(this.states)) {
-        const childLink = this.states[stateName]?._child;
-        if (childLink && !seen.has(childLink)) {
-          seen.add(childLink);
-          childLink.dispose();
-        }
-      }
-    }
-    this.emitter.clear();
-  }
-  // -------------------------------------------------------------------------
-  // Internal
-  // -------------------------------------------------------------------------
-  /**
-   * 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.
-   */
-  wrapChildLinks() {
-    for (const stateName of Object.keys(this.states)) {
-      const stateObj = this.states[stateName];
-      const rawChild = stateObj?._child;
-      if (!rawChild) {
-        continue;
-      }
-      if (typeof rawChild !== "object") {
-        throw new Error(
-          `State "${stateName}"._child: expected an Fsm or BehavioralFsm instance, got ${String(rawChild)}`
-        );
-      }
-      if (!(MACHINA_TYPE in rawChild)) {
-        throw new Error(
-          `State "${stateName}"._child: expected an Fsm or BehavioralFsm instance, got a plain object`
-        );
-      }
-      stateObj._child = createChildLink(rawChild);
-    }
-  }
-  /**
-   * 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.
-   */
-  setupChildSubscriptions() {
-    const seenChildren = /* @__PURE__ */ new Set();
-    for (const stateName of Object.keys(this.states)) {
-      const stateObj = this.states[stateName];
-      const childLink = stateObj?._child;
-      if (!childLink || seenChildren.has(childLink)) {
-        continue;
-      }
-      seenChildren.add(childLink);
-      const sub = childLink.onAny((eventName, data) => {
-        if (eventName === "nohandler") {
-          const payload2 = data;
-          if (payload2.client !== void 0) {
-            this.bubbleNohandler(
-              payload2.client,
-              childLink,
-              payload2.inputName,
-              payload2.args ?? []
-            );
-          } else {
-            for (const ref of this.knownClients) {
-              const client = ref.deref();
-              if (client === void 0) {
-                this.knownClients.delete(ref);
-                continue;
-              }
-              this.bubbleNohandler(
-                client,
-                childLink,
-                payload2.inputName,
-                payload2.args ?? []
-              );
-            }
-          }
-          return;
-        }
-        const payload = data;
-        if (payload && typeof payload === "object" && "client" in payload) {
-          if (this.isChildActiveForClient(payload.client, childLink)) {
-            this.emitter.emit(eventName, data);
-          }
-        } else {
-          for (const ref of this.knownClients) {
-            const client = ref.deref();
-            if (!client) {
-              this.knownClients.delete(ref);
-              continue;
-            }
-            if (this.isChildActiveForClient(client, childLink)) {
-              this.emitter.emit(eventName, data);
-              break;
-            }
-          }
-        }
-      });
-      this.childSubscriptions.push(sub);
-    }
-  }
-  /**
-   * 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.
-   */
-  bubbleNohandler(client, childLink, inputName, args) {
-    if (!this.isChildActiveForClient(client, childLink)) {
-      return;
-    }
-    const meta = this.clients.get(client);
-    meta.currentActionArgs = args;
-    this.handleLocally(client, inputName, args, meta);
-  }
-  /**
-   * 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.
-   */
-  isChildActiveForClient(client, childLink) {
-    const meta = this.clients.get(client);
-    if (!meta) {
-      return false;
-    }
-    const parentStateObj = this.states[meta.state];
-    return parentStateObj?._child === childLink;
-  }
-  /**
-   * 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.
-   */
-  handleLocally(client, inputName, args, meta) {
-    const stateObj = this.states[meta.state];
-    const handler = stateObj?.[inputName] ?? stateObj?.["*"];
-    if (!handler) {
-      this.emitter.emit("nohandler", { inputName, args, client });
-      meta.currentActionArgs = void 0;
-      return;
-    }
-    try {
-      this.emitter.emit("handling", { inputName, client });
-      const handlerArgs = this.buildHandlerArgs(client, inputName, meta);
-      let targetState = void 0;
-      if (typeof handler === "string") {
-        targetState = handler;
-      } else if (typeof handler === "function") {
-        targetState = handler(handlerArgs, ...args);
-      }
-      this.emitter.emit("handled", { inputName, client });
-      if (typeof targetState === "string") {
-        this.transition(client, targetState);
-      }
-    } finally {
-      meta.currentActionArgs = void 0;
-    }
-  }
-  getOrCreateClientMeta(client) {
-    let meta = this.clients.get(client);
-    if (meta) {
-      return meta;
-    }
-    meta = {
-      state: void 0,
-      deferredQueue: []
-    };
-    this.clients.set(client, meta);
-    this.knownClients.add(new WeakRef(client));
-    this.transition(client, this.initialState);
-    return meta;
-  }
-  buildHandlerArgs(client, inputName, meta) {
-    return {
-      ctx: client,
-      inputName,
-      defer: (opts) => {
-        if (!meta.currentActionArgs) {
-          return;
-        }
-        const deferred = {
-          inputName,
-          args: [...meta.currentActionArgs],
-          untilState: opts?.until
-        };
-        meta.deferredQueue.push(deferred);
-        this.emitter.emit("deferred", { inputName, client });
-      },
-      emit: (evtName, evtData) => {
-        this.emitter.emit(evtName, evtData);
-      }
-    };
-  }
-  processQueue(client, meta) {
-    const toReplay = [];
-    const remaining = [];
-    for (const item of meta.deferredQueue) {
-      if (item.untilState === void 0 || item.untilState === meta.state) {
-        toReplay.push(item);
-      } else {
-        remaining.push(item);
-      }
-    }
-    meta.deferredQueue = remaining;
-    for (const item of toReplay) {
-      this.handle(client, item.inputName, ...item.args);
-    }
-  }
+	id;
+	initialState;
+	[MACHINA_TYPE] = "BehavioralFsm";
+	states;
+	emitter = new Emitter();
+	clients = /* @__PURE__ */ new WeakMap();
+	knownClients = /* @__PURE__ */ new Set();
+	childSubscriptions = [];
+	disposed = false;
+	transitionDepth = 0;
+	constructor(config) {
+		this.id = config.id;
+		this.initialState = config.initialState;
+		this.states = config.states;
+		this.wrapChildLinks();
+		this.setupChildSubscriptions();
+	}
+	/**
+	* 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, inputName, ...args) {
+		if (this.disposed) return;
+		const meta = this.getOrCreateClientMeta(client);
+		meta.currentActionArgs = args;
+		const childLink = this.states[meta.state]?._child;
+		if (childLink) {
+			if (childLink.canHandle(client, inputName)) {
+				try {
+					childLink.handle(client, inputName, ...args);
+				} finally {
+					meta.currentActionArgs = void 0;
+				}
+				return;
+			}
+		}
+		this.handleLocally(client, inputName, args, meta);
+	}
+	/**
+	* 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, inputName) {
+		if (this.disposed) return false;
+		const state = this.clients.get(client)?.state ?? this.initialState;
+		const stateObj = this.states[state];
+		return !!(stateObj?.[inputName] ?? stateObj?.["*"]);
+	}
+	/**
+	* Transition the client back to `initialState`, firing `_onEnter` and
+	* lifecycle events as if entering it fresh. No-ops when disposed.
+	*/
+	reset(client) {
+		if (this.disposed) return;
+		this.transition(client, this.initialState);
+	}
+	/**
+	* 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) {
+		return this.clients.get(client)?.state;
+	}
+	/**
+	* 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, toState) {
+		if (this.disposed) return;
+		const meta = this.getOrCreateClientMeta(client);
+		const fromState = meta.state;
+		if (toState === fromState) return;
+		if (!(toState in this.states)) {
+			this.emitter.emit("invalidstate", {
+				stateName: toState,
+				client
+			});
+			return;
+		}
+		this.transitionDepth++;
+		if (this.transitionDepth > MAX_TRANSITION_DEPTH) {
+			this.transitionDepth = 0;
+			throw new Error(`Max transition depth (${MAX_TRANSITION_DEPTH}) exceeded in FSM "${this.id}". Likely an infinite _onEnter → transition loop.`);
+		}
+		try {
+			const curStateObj = this.states[fromState];
+			const newStateObj = this.states[toState];
+			if (curStateObj?._onExit && typeof curStateObj._onExit === "function") {
+				const exitArgs = this.buildHandlerArgs(client, "", meta);
+				curStateObj._onExit(exitArgs);
+			}
+			meta.state = toState;
+			const payload = {
+				fromState,
+				toState,
+				client
+			};
+			this.emitter.emit("transitioning", payload);
+			let bounceTarget = void 0;
+			if (newStateObj?._onEnter && typeof newStateObj._onEnter === "function") {
+				const enterArgs = this.buildHandlerArgs(client, "", meta);
+				bounceTarget = newStateObj._onEnter(enterArgs);
+			}
+			this.emitter.emit("transitioned", payload);
+			const childLink = newStateObj?._child;
+			if (childLink) childLink.reset(client);
+			this.processQueue(client, meta);
+			if (typeof bounceTarget === "string" && meta.state === toState) this.transition(client, bounceTarget);
+		} finally {
+			this.transitionDepth--;
+		}
+	}
+	/**
+	* 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) {
+		const meta = this.clients.get(client);
+		if (!meta) return "";
+		const childLink = this.states[meta.state]?._child;
+		if (childLink) {
+			const childComposite = childLink.compositeState(client);
+			if (childComposite) return `${meta.state}.${childComposite}`;
+		}
+		return meta.state;
+	}
+	on(eventName, callback) {
+		if (this.disposed) return { off() {} };
+		return this.emitter.on(eventName, callback);
+	}
+	/**
+	* 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, data) {
+		if (this.disposed) return;
+		this.emitter.emit(eventName, data);
+	}
+	/**
+	* 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) {
+		this.disposed = true;
+		for (const sub of this.childSubscriptions) sub.off();
+		if (!options?.preserveChildren) {
+			const seen = /* @__PURE__ */ new Set();
+			for (const stateName of Object.keys(this.states)) {
+				const childLink = this.states[stateName]?._child;
+				if (childLink && !seen.has(childLink)) {
+					seen.add(childLink);
+					childLink.dispose();
+				}
+			}
+		}
+		this.emitter.clear();
+	}
+	/**
+	* 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.
+	*/
+	wrapChildLinks() {
+		for (const stateName of Object.keys(this.states)) {
+			const stateObj = this.states[stateName];
+			const rawChild = stateObj?._child;
+			if (!rawChild) continue;
+			if (typeof rawChild !== "object") throw new Error(`State "${stateName}"._child: expected an Fsm or BehavioralFsm instance, got ${String(rawChild)}`);
+			if (!(MACHINA_TYPE in rawChild)) throw new Error(`State "${stateName}"._child: expected an Fsm or BehavioralFsm instance, got a plain object`);
+			stateObj._child = createChildLink(rawChild);
+		}
+	}
+	/**
+	* 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.
+	*/
+	setupChildSubscriptions() {
+		const seenChildren = /* @__PURE__ */ new Set();
+		for (const stateName of Object.keys(this.states)) {
+			const childLink = this.states[stateName]?._child;
+			if (!childLink || seenChildren.has(childLink)) continue;
+			seenChildren.add(childLink);
+			const sub = childLink.onAny((eventName, data) => {
+				if (eventName === "nohandler") {
+					const payload = data;
+					if (payload.client !== void 0) this.bubbleNohandler(payload.client, childLink, payload.inputName, payload.args ?? []);
+					else for (const ref of this.knownClients) {
+						const client = ref.deref();
+						if (client === void 0) {
+							this.knownClients.delete(ref);
+							continue;
+						}
+						this.bubbleNohandler(client, childLink, payload.inputName, payload.args ?? []);
+					}
+					return;
+				}
+				const payload = data;
+				if (payload && typeof payload === "object" && "client" in payload) {
+					if (this.isChildActiveForClient(payload.client, childLink)) this.emitter.emit(eventName, data);
+				} else for (const ref of this.knownClients) {
+					const client = ref.deref();
+					if (!client) {
+						this.knownClients.delete(ref);
+						continue;
+					}
+					if (this.isChildActiveForClient(client, childLink)) {
+						this.emitter.emit(eventName, data);
+						break;
+					}
+				}
+			});
+			this.childSubscriptions.push(sub);
+		}
+	}
+	/**
+	* 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.
+	*/
+	bubbleNohandler(client, childLink, inputName, args) {
+		if (!this.isChildActiveForClient(client, childLink)) return;
+		const meta = this.clients.get(client);
+		meta.currentActionArgs = args;
+		this.handleLocally(client, inputName, args, meta);
+	}
+	/**
+	* 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.
+	*/
+	isChildActiveForClient(client, childLink) {
+		const meta = this.clients.get(client);
+		if (!meta) return false;
+		return this.states[meta.state]?._child === childLink;
+	}
+	/**
+	* 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.
+	*/
+	handleLocally(client, inputName, args, meta) {
+		const stateObj = this.states[meta.state];
+		const handler = stateObj?.[inputName] ?? stateObj?.["*"];
+		if (!handler) {
+			this.emitter.emit("nohandler", {
+				inputName,
+				args,
+				client
+			});
+			meta.currentActionArgs = void 0;
+			return;
+		}
+		try {
+			this.emitter.emit("handling", {
+				inputName,
+				client
+			});
+			const handlerArgs = this.buildHandlerArgs(client, inputName, meta);
+			let targetState = void 0;
+			if (typeof handler === "string") targetState = handler;
+			else if (typeof handler === "function") targetState = handler(handlerArgs, ...args);
+			this.emitter.emit("handled", {
+				inputName,
+				client
+			});
+			if (typeof targetState === "string") this.transition(client, targetState);
+		} finally {
+			meta.currentActionArgs = void 0;
+		}
+	}
+	getOrCreateClientMeta(client) {
+		let meta = this.clients.get(client);
+		if (meta) return meta;
+		meta = {
+			state: void 0,
+			deferredQueue: []
+		};
+		this.clients.set(client, meta);
+		this.knownClients.add(new WeakRef(client));
+		this.transition(client, this.initialState);
+		return meta;
+	}
+	buildHandlerArgs(client, inputName, meta) {
+		return {
+			ctx: client,
+			inputName,
+			defer: (opts) => {
+				if (!meta.currentActionArgs) return;
+				const deferred = {
+					inputName,
+					args: [...meta.currentActionArgs],
+					untilState: opts?.until
+				};
+				meta.deferredQueue.push(deferred);
+				this.emitter.emit("deferred", {
+					inputName,
+					client
+				});
+			},
+			emit: (evtName, evtData) => {
+				this.emitter.emit(evtName, evtData);
+			}
+		};
+	}
+	processQueue(client, meta) {
+		const toReplay = [];
+		const remaining = [];
+		for (const item of meta.deferredQueue) if (item.untilState === void 0 || item.untilState === meta.state) toReplay.push(item);
+		else remaining.push(item);
+		meta.deferredQueue = remaining;
+		for (const item of toReplay) this.handle(client, item.inputName, ...item.args);
+	}
 };
+/**
+* Internal factory called by `wrapChildLinks()` during construction.
+* Wraps a raw Fsm or BehavioralFsm instance in a uniform `ChildLink` adapter
+* so the parent engine doesn't need to know which type it's talking to.
+*
+* Users never call this directly — they assign an FSM instance to `_child`
+* in their state config and `wrapChildLinks()` handles the wrapping.
+*/
 function createChildLink(child) {
-  if (!child || typeof child !== "object") {
-    throw new Error(
-      `createChildLink: expected an Fsm or BehavioralFsm instance, got ${String(child)}`
-    );
-  }
-  const childType = child[MACHINA_TYPE];
-  if (childType === "BehavioralFsm") {
-    return {
-      canHandle(client, inputName) {
-        return child.canHandle(client, inputName);
-      },
-      handle(client, inputName, ...args) {
-        child.handle(client, inputName, ...args);
-      },
-      reset(client) {
-        child.transition(client, child.initialState);
-      },
-      onAny(callback) {
-        return child.on("*", callback);
-      },
-      compositeState(client) {
-        return child.compositeState(client);
-      },
-      dispose() {
-        child.dispose();
-      }
-    };
-  }
-  if (childType === "Fsm") {
-    return {
-      canHandle(_client, inputName) {
-        return child.canHandle(inputName);
-      },
-      handle(_client, inputName, ...args) {
-        child.handle(inputName, ...args);
-      },
-      reset(_client) {
-        child.reset();
-      },
-      onAny(callback) {
-        return child.on("*", callback);
-      },
-      compositeState(_client) {
-        return child.compositeState();
-      },
-      dispose() {
-        child.dispose();
-      }
-    };
-  }
-  throw new Error(
-    `createChildLink: expected an Fsm or BehavioralFsm instance, got [MACHINA_TYPE] = ${String(childType ?? "undefined")}`
-  );
+	if (!child || typeof child !== "object") throw new Error(`createChildLink: expected an Fsm or BehavioralFsm instance, got ${String(child)}`);
+	const childType = child[MACHINA_TYPE];
+	if (childType === "BehavioralFsm") return {
+		instance: child,
+		canHandle(client, inputName) {
+			return child.canHandle(client, inputName);
+		},
+		handle(client, inputName, ...args) {
+			child.handle(client, inputName, ...args);
+		},
+		reset(client) {
+			child.transition(client, child.initialState);
+		},
+		onAny(callback) {
+			return child.on("*", callback);
+		},
+		compositeState(client) {
+			return child.compositeState(client);
+		},
+		dispose() {
+			child.dispose();
+		}
+	};
+	if (childType === "Fsm") return {
+		instance: child,
+		canHandle(_client, inputName) {
+			return child.canHandle(inputName);
+		},
+		handle(_client, inputName, ...args) {
+			child.handle(inputName, ...args);
+		},
+		reset(_client) {
+			child.reset();
+		},
+		onAny(callback) {
+			return child.on("*", callback);
+		},
+		compositeState(_client) {
+			return child.compositeState();
+		},
+		dispose() {
+			child.dispose();
+		}
+	};
+	throw new Error(`createChildLink: expected an Fsm or BehavioralFsm instance, got [MACHINA_TYPE] = ${String(childType ?? "undefined")}`);
 }
+/**
+* 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");
+* ```
+*/
 function createBehavioralFsm(config) {
-  return new BehavioralFsm(config);
+	return new BehavioralFsm(config);
 }
 
-// src/fsm.ts
+//#endregion
+//#region src/fsm.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.
+*/
 var Fsm = class {
-  id;
-  // Type discriminant — lets ChildLink adapter identify this at runtime
-  [MACHINA_TYPE] = "Fsm";
-  bfsm;
-  context;
-  // FsmEventMap is an interface, which lacks the implicit index signature
-  // that Emitter's Record<string, unknown> constraint needs. The mapped type
-  // BehavioralFsmEventMap doesn't have this issue. Intersect with Record to
-  // satisfy the constraint while preserving typed event signatures.
-  emitter = new Emitter();
-  disposed = false;
-  constructor(config) {
-    this.id = config.id;
-    this.context = config.context ?? {};
-    this.bfsm = new BehavioralFsm(config);
-    this.bfsm.on("*", (eventName, data) => {
-      if (data && typeof data === "object" && "client" in data) {
-        const { client: _, ...payload } = data;
-        this.emitter.emit(eventName, payload);
-      } else {
-        this.emitter.emit(eventName, data);
-      }
-    });
-    this.bfsm.transition(this.context, config.initialState);
-  }
-  // -------------------------------------------------------------------------
-  // Public API — same as BehavioralFsm, minus the client parameter
-  // -------------------------------------------------------------------------
-  /**
-   * 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, ...args) {
-    if (this.disposed) {
-      return;
-    }
-    this.bfsm.handle(this.context, inputName, ...args);
-  }
-  /**
-   * 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) {
-    if (this.disposed) {
-      return false;
-    }
-    return this.bfsm.canHandle(this.context, inputName);
-  }
-  /**
-   * Transition back to `initialState`, firing `_onEnter` and lifecycle
-   * events as if entering it fresh. No-ops silently when disposed.
-   */
-  reset() {
-    if (this.disposed) {
-      return;
-    }
-    this.bfsm.reset(this.context);
-  }
-  /**
-   * Returns the current state name. Always defined — Fsm eagerly
-   * initializes into `initialState` during construction.
-   */
-  currentState() {
-    return this.bfsm.currentState(this.context);
-  }
-  /**
-   * Directly transition to `toState`, firing `_onExit`, `_onEnter`, and
-   * lifecycle events. Same-state transitions are silently ignored.
-   * No-ops when disposed.
-   */
-  transition(toState) {
-    if (this.disposed) {
-      return;
-    }
-    this.bfsm.transition(this.context, toState);
-  }
-  /**
-   * 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() {
-    return this.bfsm.compositeState(this.context);
-  }
-  on(eventName, callback) {
-    if (this.disposed) {
-      return { off() {
-      } };
-    }
-    return this.emitter.on(eventName, callback);
-  }
-  /**
-   * 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, data) {
-    if (this.disposed) {
-      return;
-    }
-    this.bfsm.emit(eventName, data);
-  }
-  /**
-   * 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) {
-    this.disposed = true;
-    this.bfsm.dispose(options);
-    this.emitter.clear();
-  }
+	id;
+	initialState;
+	[MACHINA_TYPE] = "Fsm";
+	states;
+	bfsm;
+	context;
+	emitter = new Emitter();
+	disposed = false;
+	constructor(config) {
+		this.id = config.id;
+		this.initialState = config.initialState;
+		this.context = config.context ?? {};
+		this.bfsm = new BehavioralFsm(config);
+		this.states = config.states;
+		this.bfsm.on("*", (eventName, data) => {
+			if (data && typeof data === "object" && "client" in data) {
+				const { client: _, ...payload } = data;
+				this.emitter.emit(eventName, payload);
+			} else this.emitter.emit(eventName, data);
+		});
+		this.bfsm.transition(this.context, config.initialState);
+	}
+	/**
+	* 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, ...args) {
+		if (this.disposed) return;
+		this.bfsm.handle(this.context, inputName, ...args);
+	}
+	/**
+	* 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) {
+		if (this.disposed) return false;
+		return this.bfsm.canHandle(this.context, inputName);
+	}
+	/**
+	* Transition back to `initialState`, firing `_onEnter` and lifecycle
+	* events as if entering it fresh. No-ops silently when disposed.
+	*/
+	reset() {
+		if (this.disposed) return;
+		this.bfsm.reset(this.context);
+	}
+	/**
+	* Returns the current state name. Always defined — Fsm eagerly
+	* initializes into `initialState` during construction.
+	*/
+	currentState() {
+		return this.bfsm.currentState(this.context);
+	}
+	/**
+	* Directly transition to `toState`, firing `_onExit`, `_onEnter`, and
+	* lifecycle events. Same-state transitions are silently ignored.
+	* No-ops when disposed.
+	*/
+	transition(toState) {
+		if (this.disposed) return;
+		this.bfsm.transition(this.context, toState);
+	}
+	/**
+	* 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() {
+		return this.bfsm.compositeState(this.context);
+	}
+	on(eventName, callback) {
+		if (this.disposed) return { off() {} };
+		return this.emitter.on(eventName, callback);
+	}
+	/**
+	* 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, data) {
+		if (this.disposed) return;
+		this.bfsm.emit(eventName, data);
+	}
+	/**
+	* 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) {
+		this.disposed = true;
+		this.bfsm.dispose(options);
+		this.emitter.clear();
+	}
 };
+/**
+* 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
+* ```
+*/
 function createFsm(config) {
-  return new Fsm(config);
+	return new Fsm(config);
 }
 
-export { BehavioralFsm, Fsm, createBehavioralFsm, createFsm };
-//# sourceMappingURL=index.mjs.map
+//#endregion
+export { BehavioralFsm, Fsm, MACHINA_TYPE, createBehavioralFsm, createFsm };
 //# sourceMappingURL=index.mjs.map