@statewalker/fsm 0.36.0 → 0.38.0

package/dist/index.js

@@ -1,786 +1,568 @@
-// src/core/fsm-base-class.ts
+//#region src/core/fsm-base-class.ts
+/**
+* Shared handler-registry substrate under both `FsmProcess` and `FsmState`.
+*
+* Both the process and every state need the same primitive: keep named lists of
+* callbacks (`onEnter`, `onExit`, `dump`, …) and run them with consistent ordering
+* and error routing. Centralising it here keeps the two subclasses thin and their
+* hook methods one-liners. `handlers` maps a hook name to its ordered callback list;
+* the protected `_addHandler` / `_removeHandler` / `_runHandler` manage and invoke
+* them. Handlers run **sequentially** (awaited in turn); a throwing handler is routed
+* to `_handleError` rather than aborting the batch. Subclasses expose typed sugar
+* (e.g. `state.onEnter(fn)` calls `_addHandler("onEnter", fn)`) and override
+* `_handleError` to forward errors.
+*/
 var FsmBaseClass = class {
-  constructor() {
-    this.handlers = {};
-    this.data = {};
-    bindMethods(this, "setData", "getData");
-  }
-  setData(key, value) {
-    this.data[key] = value;
-    return this;
-  }
-  getData(key) {
-    return this.data[key];
-  }
-  // ----------------------------------------------
-  // internal methods
-  _addHandler(type, handler, direct = true) {
-    let list = this.handlers[type];
-    if (!list) {
-      list = this.handlers[type] = [];
-    }
-    const h = handler;
-    direct ? list.push(h) : list.unshift(h);
-    return () => this._removeHandler(type, h);
-  }
-  _removeHandler(type, handler) {
-    let list = this.handlers[type];
-    if (!list) return;
-    list = list.filter((h) => h !== handler);
-    if (list.length > 0) {
-      this.handlers[type] = list;
-    } else {
-      delete this.handlers[type];
-    }
-  }
-  async _runHandlerParallel(type, ...args) {
-    const list = this.handlers[type] || [];
-    await Promise.all(
-      list.map(async (handler) => {
-        try {
-          await handler(...args);
-        } catch (error) {
-          this._handleError(error);
-        }
-      })
-    );
-  }
-  async _runHandler(type, ...args) {
-    const list = this.handlers[type] || [];
-    for (const handler of list) {
-      try {
-        await handler(...args);
-      } catch (error) {
-        await this._handleError(error);
-      }
-    }
-  }
-  async _handleError(error) {
-    console.error(error);
-  }
+	constructor() {
+		this.handlers = {};
+	}
+	/**
+	* Register `handler` under `type`; returns a disposer that removes it.
+	* `direct=false` prepends instead of appends — used so `onExit` handlers run in
+	* reverse (inner-to-outer) unwinding order.
+	*/
+	_addHandler(type, handler, direct = true) {
+		let list = this.handlers[type];
+		if (!list) list = this.handlers[type] = [];
+		const h = handler;
+		direct ? list.push(h) : list.unshift(h);
+		return () => this._removeHandler(type, h);
+	}
+	_removeHandler(type, handler) {
+		let list = this.handlers[type];
+		if (!list) return;
+		list = list.filter((h) => h !== handler);
+		if (list.length > 0) this.handlers[type] = list;
+		else delete this.handlers[type];
+	}
+	/** Run every handler of `type` in order, awaiting each; route throws to `_handleError`. */
+	async _runHandler(type, ...args) {
+		const list = this.handlers[type] || [];
+		for (const handler of list) try {
+			await handler(...args);
+		} catch (error) {
+			await this._handleError(error);
+		}
+	}
+	/** Default error sink — logs. `FsmState`/`FsmProcess` override it to fire `onStateError`. */
+	async _handleError(error) {
+		console.error(error);
+	}
 };
+/**
+* Bind the named methods of `obj` to `obj` in place, so they can be passed as bare
+* callbacks (e.g. `ctx[KEY_DISPATCH] = process.dispatch`) without losing `this`.
+*/
 function bindMethods(obj, ...methods) {
-  const o = obj;
-  for (const methodName of methods) {
-    const method = o[methodName];
-    if (typeof method !== "function") continue;
-    o[methodName] = method.bind(o);
-  }
-  return obj;
+	const o = obj;
+	for (const methodName of methods) {
+		const method = o[methodName];
+		if (typeof method !== "function") continue;
+		o[methodName] = method.bind(o);
+	}
+	return obj;
 }
-
-// src/core/fsm-state.ts
+//#endregion
+//#region src/core/fsm-state.ts
+/**
+* One live node in a running machine's active-state stack.
+*
+* A state needs a place to attach behaviour and record data while it is active.
+* `FsmState` is that handle — created by the engine each time a state is entered,
+* discarded when it exits — so handlers can capture per-activation closures instead
+* of sharing mutable machine-wide state. It offers lifecycle hooks `onEnter` /
+* `onExit` / `onStateError`, serialization hooks `dump` / `restore`, and the tree
+* links `key` / `parent` / `descriptor`; every hook method returns a disposer.
+* Attach hooks from within `FsmProcess.onStateCreate((state) => …)`, or let
+* `startProcess` install them for you from a `load` callback.
+*/
 var FsmState = class extends FsmBaseClass {
-  constructor(process2, parent, key, descriptor) {
-    super();
-    this.process = process2;
-    this.key = key;
-    this.parent = parent;
-    this.descriptor = descriptor;
-    bindMethods(
-      this,
-      "onEnter",
-      "onExit",
-      "dump",
-      "restore",
-      "useData",
-      "onStateError"
-    );
-  }
-  onEnter(handler) {
-    return this._addHandler("onEnter", handler, true);
-  }
-  onExit(handler) {
-    return this._addHandler("onExit", handler, false);
-  }
-  onStateError(handler) {
-    return this._addHandler("onStateError", handler);
-  }
-  dump(handler) {
-    return this._addHandler("dump", handler, true);
-  }
-  restore(handler) {
-    return this._addHandler("restore", handler, true);
-  }
-  getData(key, recursive = true) {
-    return this.data[key] ?? (recursive ? this.parent?.getData(key, recursive) : void 0);
-  }
-  useData(key) {
-    return [
-      (recursive = true) => this.getData(key, recursive),
-      (value) => this.setData(key, value)
-    ];
-  }
-  async _handleError(error) {
-    await this._runHandler("onStateError", this, error);
-    await this.process._handleStateError(this, error);
-  }
+	constructor(process, parent, key, descriptor) {
+		super();
+		this.process = process;
+		this.key = key;
+		this.parent = parent;
+		this.descriptor = descriptor;
+		bindMethods(this, "onEnter", "onExit", "dump", "restore", "onStateError");
+	}
+	/** Run when this state is entered. */
+	onEnter(handler) {
+		return this._addHandler("onEnter", handler, true);
+	}
+	/** Run when this state exits — registered inner-first so unwinding is inner-to-outer. */
+	onExit(handler) {
+		return this._addHandler("onExit", handler, false);
+	}
+	/** Handle an error thrown by another handler on this state (also bubbles to the process). */
+	onStateError(handler) {
+		return this._addHandler("onStateError", handler);
+	}
+	/** Contribute to this state's snapshot: fill `dump.data` when the process is dumped. */
+	dump(handler) {
+		return this._addHandler("dump", handler, true);
+	}
+	/** Rehydrate from this state's snapshot: read `dump.data` when the process is restored. */
+	restore(handler) {
+		return this._addHandler("restore", handler, true);
+	}
+	async _handleError(error) {
+		await this._runHandler("onStateError", this, error);
+		await this.process._handleStateError(this, error);
+	}
 };
-
-// src/core/fsm-state-config.ts
-var STATE_ANY = "*";
-var STATE_INITIAL = "";
-var STATE_FINAL = "";
-var EVENT_ANY = "*";
-var EVENT_EMPTY = "";
-
-// src/core/fsm-state-descriptor.ts
-var FsmStateDescriptor = class _FsmStateDescriptor {
-  constructor() {
-    this.transitions = {};
-    this.states = {};
-  }
-  static build(config) {
-    const descriptor = new _FsmStateDescriptor();
-    for (const [from, event, to] of config.transitions || []) {
-      let index = descriptor.transitions[from];
-      if (!index) {
-        index = descriptor.transitions[from] = {};
-      }
-      index[event] = to;
-    }
-    if (config.states) {
-      for (const substateConfig of config.states) {
-        descriptor.states[substateConfig.key] = _FsmStateDescriptor.build(substateConfig);
-      }
-    }
-    return descriptor;
-  }
-  getTargetStateKey(stateKey, eventKey) {
-    const pairs = [
-      [stateKey, eventKey],
-      [STATE_ANY, eventKey],
-      [stateKey, EVENT_ANY],
-      [STATE_ANY, EVENT_ANY]
-    ];
-    let targetKey;
-    for (let i = 0, len = pairs.length; targetKey === void 0 && i < len; i++) {
-      const [stateKey2, eventKey2] = pairs[i];
-      const stateTransitions = this.transitions[stateKey2];
-      if (!stateTransitions) continue;
-      targetKey = stateTransitions[eventKey2];
-    }
-    return targetKey !== void 0 ? targetKey : STATE_FINAL;
-  }
+//#endregion
+//#region src/core/fsm-state-config.ts
+/** Wildcard `from`-state: a transition that applies in *any* state. */
+const STATE_ANY = "*";
+/** Empty `from`-state: the *initial* pseudo-state a parent enters into. */
+const STATE_INITIAL = "";
+/** Empty `to`-state: the *final* pseudo-state; entering it exits the parent. */
+const STATE_FINAL = "";
+/** Wildcard `event`: a transition triggered by *any* event. */
+const EVENT_ANY = "*";
+/** Empty event: the eventless/automatic transition (fires with no named event). */
+const EVENT_EMPTY = "";
+//#endregion
+//#region src/core/fsm-state-descriptor.ts
+/**
+* The *compiled* form of an `FsmStateConfig` subtree.
+*
+* Resolving a transition happens on every event, so the flat `[from, event, to]`
+* tuple list is pre-indexed once into nested maps for O(1) lookup, and the
+* wildcard-fallback order is applied here rather than re-derived on each dispatch.
+* The shape is `transitions[from][event] = to` plus a `states` map of child
+* descriptors. `FsmProcess` builds one from your config in its constructor; you
+* rarely construct a descriptor directly.
+*/
+var FsmStateDescriptor = class FsmStateDescriptor {
+	constructor() {
+		this.transitions = {};
+		this.states = {};
+	}
+	/**
+	* Recursively compile a config (and its nested `states`) into descriptors,
+	* turning the tuple list into the indexed `transitions` map.
+	*/
+	static build(config) {
+		const descriptor = new FsmStateDescriptor();
+		for (const [from, event, to] of config.transitions || []) {
+			let index = descriptor.transitions[from];
+			if (!index) index = descriptor.transitions[from] = {};
+			index[event] = to;
+		}
+		if (config.states) for (const substateConfig of config.states) descriptor.states[substateConfig.key] = FsmStateDescriptor.build(substateConfig);
+		return descriptor;
+	}
+	/**
+	* Resolve the target state for a `(stateKey, eventKey)` pair. Tries the most
+	* specific match first, then falls back through the wildcards —
+	* `(state, event)` → `(*, event)` → `(state, *)` → `(*, *)` — and returns
+	* `STATE_FINAL` if nothing matches, so an unmatched event exits the state rather
+	* than silently doing nothing.
+	*/
+	getTargetStateKey(stateKey, eventKey) {
+		const pairs = [
+			[stateKey, eventKey],
+			["*", eventKey],
+			[stateKey, "*"],
+			["*", "*"]
+		];
+		let targetKey;
+		for (let i = 0, len = pairs.length; targetKey === void 0 && i < len; i++) {
+			const [stateKey, eventKey] = pairs[i];
+			const stateTransitions = this.transitions[stateKey];
+			if (!stateTransitions) continue;
+			targetKey = stateTransitions[eventKey];
+		}
+		return targetKey !== void 0 ? targetKey : "";
+	}
 };
-
-// src/core/fsm-process.ts
-var STATUS_NONE = 0;
-var STATUS_FIRST = 1;
-var STATUS_NEXT = 2;
-var STATUS_LEAF = 4;
-var STATUS_LAST = 8;
-var STATUS_FINISHED = 16;
-var STATUS_ENTER = STATUS_FIRST | STATUS_NEXT;
-var STATUS_EXIT = STATUS_LEAF | STATUS_LAST;
+//#endregion
+//#region src/core/fsm-process.ts
+/** Not started / no current transition. */
+const STATUS_NONE = 0;
+/** Entering: descended into a parent's first (initial) child. */
+const STATUS_FIRST = 1;
+/** Entering: advanced to a resolved target (sibling) state. */
+const STATUS_NEXT = 2;
+/** Rested on a leaf — dispatch returns control here (the default `mask`). */
+const STATUS_LEAF = 4;
+/** Exiting: popped back up to the parent state. */
+const STATUS_LAST = 8;
+/** Terminated: the machine has exited its root and cannot advance further. */
+const STATUS_FINISHED = 16;
+/** Composite: any "entering" phase. */
+const STATUS_ENTER = 3;
+/** Composite: any "exiting" phase. */
+const STATUS_EXIT = 12;
+/**
+* The running state machine — owner of the active-state stack and the traversal.
+*
+* This is the engine: given a compiled config it drives the enter/exit walk in
+* response to events, so callers reason in terms of states and events, not manual
+* stack bookkeeping. `dispatch(event)` advances the machine to the next resting leaf;
+* `shutdown(event?)` unwinds every active state; `state` is the current leaf;
+* `onStateCreate(handler)` is the primary extension point (fires once per created
+* state — attach that state's hooks there); and `dump()` / `restore(dump)` snapshot
+* and rehydrate the whole stack. Typical use: `new FsmProcess(config)`, register
+* `onStateCreate`, then `dispatch("")` to enter the initial state and
+* `dispatch(event)` for each subsequent event.
+*/
 var FsmProcess = class extends FsmBaseClass {
-  constructor(config) {
-    super();
-    this.running = false;
-    this.mask = STATUS_LEAF;
-    this.status = 0;
-    this.rootDescriptor = FsmStateDescriptor.build(config);
-    this.config = config;
-    bindMethods(this, "dispatch", "dump", "restore");
-  }
-  async shutdown(event) {
-    while (this.state) {
-      this.event = event;
-      this.status = STATUS_FINISHED;
-      await this.state?._runHandler("onExit", this.state);
-      this.state = this.state.parent;
-    }
-  }
-  async dispatch(event) {
-    this.nextEvent = event;
-    if (!this.running && !(this.status & STATUS_FINISHED)) {
-      this.running = true;
-      try {
-        this.event = this.nextEvent;
-        this.nextEvent = void 0;
-        while (true) {
-          if (this.status & STATUS_EXIT) {
-            await this.state?._runHandler("onExit", this.state);
-          }
-          if (!this._update()) break;
-          if (this.status & STATUS_ENTER) {
-            await this.state?._runHandler("onEnter", this.state);
-          }
-          if (this.status & this.mask) break;
-        }
-      } finally {
-        this.running = false;
-      }
-      const nextEvent = this.nextEvent;
-      if (nextEvent !== void 0) {
-        return Promise.resolve().then(() => this.dispatch(nextEvent));
-      }
-    }
-    return !(this.status & STATUS_FINISHED);
-  }
-  async dump(...args) {
-    const dumpState = async (state) => {
-      const stateDump = {
-        key: state.key,
-        data: {}
-      };
-      await state._runHandler("dump", state, stateDump.data, ...args);
-      return stateDump;
-    };
-    const dumpStates = async (state, stack = []) => {
-      if (!state) return stack;
-      state.parent && await dumpStates(state.parent, stack);
-      stack.push(await dumpState(state));
-      return stack;
-    };
-    const dump = {
-      status: this.status,
-      event: this.event,
-      stack: await dumpStates(this.state)
-    };
-    return dump;
-  }
-  async restore(dump, ...args) {
-    this.status = dump.status || 0;
-    this.event = dump.event;
-    this.state = void 0;
-    for (let i = 0; i < dump.stack.length; i++) {
-      const stateDump = dump.stack[i];
-      this.state = this.state ? this._newSubstate(this.state, stateDump.key) : this._newState(void 0, stateDump.key, this.rootDescriptor);
-      await this.state._runHandler(
-        "restore",
-        this.state,
-        stateDump.data,
-        ...args
-      );
-    }
-    return this;
-  }
-  onStateCreate(handler) {
-    return this._addHandler("onStateCreate", handler, true);
-  }
-  onStateError(handler) {
-    return this._addHandler("onStateError", handler);
-  }
-  async _handleStateError(state, error) {
-    await this._runHandler("onStateError", state, error);
-    this._handleError(error);
-  }
-  _newState(parent, key, descriptor) {
-    const state = new FsmState(this, parent, key, descriptor);
-    this._runHandlerParallel("onStateCreate", state);
-    return state;
-  }
-  _getSubstate(parent, prevStateKey) {
-    if (!parent) return;
-    const toState = parent.descriptor?.getTargetStateKey(
-      prevStateKey || STATE_INITIAL,
-      this.event || EVENT_EMPTY
-    ) || STATE_FINAL;
-    if (!toState) return;
-    return this._newSubstate(parent, toState);
-  }
-  _newSubstate(parent, toState) {
-    let descriptor;
-    for (let state = parent; !descriptor && state; state = state.parent) {
-      descriptor = state.descriptor?.states[toState];
-    }
-    return this._newState(parent, toState, descriptor);
-  }
-  _update() {
-    if (this.status & STATUS_FINISHED) return false;
-    const nextState = this.status !== STATUS_NONE ? this.status & STATUS_ENTER ? this._getSubstate(this.state, STATE_INITIAL) : this._getSubstate(this.state?.parent, this.state?.key) : this._newState(void 0, this.config.key, this.rootDescriptor);
-    if (nextState !== void 0) {
-      this.state = nextState;
-      this.status = this.status & STATUS_EXIT ? STATUS_NEXT : STATUS_FIRST;
-    } else {
-      if (this.status & STATUS_EXIT) {
-        this.state = this.state?.parent;
-        this.status = STATUS_LAST;
-      } else {
-        this.status = STATUS_LEAF;
-      }
-      if (!this.state) this.status = STATUS_FINISHED;
-    }
-    return !(this.status & STATUS_FINISHED);
-  }
+	constructor(config) {
+		super();
+		this.running = false;
+		this.mask = 4;
+		this.status = 0;
+		this.rootDescriptor = FsmStateDescriptor.build(config);
+		this.config = config;
+		bindMethods(this, "dispatch", "dump", "restore");
+	}
+	/** Force-exit the whole stack (root last), running each state's `onExit`; ends the machine. */
+	async shutdown(event) {
+		while (this.state) {
+			this.event = event;
+			this.status = 16;
+			await this.state?._runHandler("onExit", this.state);
+			this.state = this.state.parent;
+		}
+	}
+	/**
+	* Feed an event to the machine and run the enter/exit cycle until it rests on a
+	* leaf (`status & mask`) or finishes.
+	*
+	* If a dispatch is already running (e.g. an `onEnter` handler dispatches
+	* synchronously), the event is queued in `nextEvent` and applied when the current
+	* run settles — runs never nest. Returns `false` once the machine has finished,
+	* `true` otherwise.
+	*/
+	async dispatch(event) {
+		this.nextEvent = event;
+		if (!this.running && !(this.status & 16)) {
+			this.running = true;
+			try {
+				this.event = this.nextEvent;
+				this.nextEvent = void 0;
+				while (true) {
+					if (this.status & 12) await this.state?._runHandler("onExit", this.state);
+					if (!await this._update()) break;
+					if (this.status & 3) await this.state?._runHandler("onEnter", this.state);
+					if (this.status & this.mask) break;
+				}
+			} finally {
+				this.running = false;
+			}
+			const nextEvent = this.nextEvent;
+			if (nextEvent !== void 0) return Promise.resolve().then(() => this.dispatch(nextEvent));
+		}
+		return !(this.status & 16);
+	}
+	/**
+	* Snapshot the machine to a plain object: `{ status, event, stack }` where the
+	* stack is root→leaf, each entry carrying whatever its `dump` hooks recorded.
+	*/
+	async dump(...args) {
+		const dumpState = async (state) => {
+			const stateDump = {
+				key: state.key,
+				data: {}
+			};
+			await state._runHandler("dump", state, stateDump.data, ...args);
+			return stateDump;
+		};
+		const dumpStates = async (state, stack = []) => {
+			if (!state) return stack;
+			state.parent && await dumpStates(state.parent, stack);
+			stack.push(await dumpState(state));
+			return stack;
+		};
+		return {
+			status: this.status,
+			event: this.event,
+			stack: await dumpStates(this.state)
+		};
+	}
+	/**
+	* Rebuild the machine from a `dump`: recreate each state in the stack (firing
+	* `onStateCreate`) and replay its `restore` hooks, leaving the process resumable
+	* from where it was snapshotted.
+	*/
+	async restore(dump, ...args) {
+		this.status = dump.status || 0;
+		this.event = dump.event;
+		this.state = void 0;
+		for (let i = 0; i < dump.stack.length; i++) {
+			const stateDump = dump.stack[i];
+			this.state = this.state ? await this._newSubstate(this.state, stateDump.key) : await this._newState(void 0, stateDump.key, this.rootDescriptor);
+			await this.state._runHandler("restore", this.state, stateDump.data, ...args);
+		}
+		return this;
+	}
+	/** Primary extension point: fires once for every state the machine creates. */
+	onStateCreate(handler) {
+		return this._addHandler("onStateCreate", handler, true);
+	}
+	onStateError(handler) {
+		return this._addHandler("onStateError", handler);
+	}
+	async _handleStateError(state, error) {
+		await this._runHandler("onStateError", state, error);
+		this._handleError(error);
+	}
+	async _newState(parent, key, descriptor) {
+		const state = new FsmState(this, parent, key, descriptor);
+		await this._runHandler("onStateCreate", state);
+		return state;
+	}
+	async _getSubstate(parent, prevStateKey) {
+		if (!parent) return;
+		const toState = parent.descriptor?.getTargetStateKey(prevStateKey || "", this.event || "") || "";
+		if (!toState) return;
+		return this._newSubstate(parent, toState);
+	}
+	async _newSubstate(parent, toState) {
+		let descriptor;
+		for (let state = parent; !descriptor && state; state = state.parent) descriptor = state.descriptor?.states[toState];
+		return this._newState(parent, toState, descriptor);
+	}
+	/**
+	* One step of the traversal: compute the next state and update `status`.
+	*
+	* Either descends to a child / advances to a resolved target (setting an ENTER
+	* status), or — when no target resolves — settles on the current leaf
+	* (`STATUS_LEAF`) or pops to the parent (`STATUS_LAST`), reaching `STATUS_FINISHED`
+	* once the root is exited. Returns `false` when finished.
+	*/
+	async _update() {
+		if (this.status & 16) return false;
+		const nextState = this.status !== 0 ? this.status & 3 ? await this._getSubstate(this.state, "") : await this._getSubstate(this.state?.parent, this.state?.key) : await this._newState(void 0, this.config.key, this.rootDescriptor);
+		if (nextState !== void 0) {
+			this.state = nextState;
+			this.status = this.status & 12 ? 2 : 1;
+		} else {
+			if (this.status & 12) {
+				this.state = this.state?.parent;
+				this.status = 8;
+			} else this.status = 4;
+			if (!this.state) this.status = 16;
+		}
+		return !(this.status & 16);
+	}
 };
-
-// src/utils/transitions.ts
-function isStateTransitionEnabled(process2, event) {
-  const transitions = getStateTransitions(process2.state);
-  let active = false;
-  for (const [from, ev, to] of transitions) {
-    if (ev === event) {
-      active = true;
-      break;
-    }
-  }
-  return active;
-}
+//#endregion
+//#region src/core/fsm-transitions.ts
+/**
+* List the transitions currently reachable from `state` — for a UI or viewer that
+* needs to know which events can fire right now (e.g. to render only the enabled
+* buttons). Collects `[from, event, to]` tuples by walking up the parent chain; the
+* nearest state's rule for an event wins, so an outer fallback is masked by an inner
+* override. The returned tuples are ordered outer→inner (root first).
+*/
 function getStateTransitions(state) {
-  const result = [];
-  const index = {};
-  if (state) {
-    let prevStateKey = state.key;
-    for (let parent = state?.parent; parent; parent = parent.parent) {
-      if (!parent.descriptor) continue;
-      result.push(
-        ...getTransitionsFromDescriptor(parent.descriptor, prevStateKey, index)
-      );
-      prevStateKey = parent.key;
-    }
-  }
-  return result.reverse();
+	const result = [];
+	const index = {};
+	if (state) {
+		let prevStateKey = state.key;
+		for (let parent = state.parent; parent; parent = parent.parent) {
+			if (!parent.descriptor) continue;
+			result.push(...getTransitionsFromDescriptor(parent.descriptor, prevStateKey, index));
+			prevStateKey = parent.key;
+		}
+	}
+	return result.reverse();
 }
-function getTransitionsFromDescriptor(descriptor, prevStateKey, index = {}) {
-  const result = [];
-  const prevStateKeys = [prevStateKey, "*"];
-  for (const prevKey of prevStateKeys) {
-    const targets = descriptor.transitions[prevKey];
-    if (targets) {
-      for (const [event, target] of Object.entries(targets)) {
-        if (index[event]) continue;
-        if (target) {
-          index[event] = true;
-        }
-        result.push([prevStateKey, event, target]);
-      }
-    }
-  }
-  return result;
+function getTransitionsFromDescriptor(descriptor, prevStateKey, index) {
+	const result = [];
+	const prevStateKeys = [prevStateKey, "*"];
+	for (const prevKey of prevStateKeys) {
+		const targets = descriptor.transitions[prevKey];
+		if (targets) for (const [event, target] of Object.entries(targets)) {
+			if (index[event]) continue;
+			index[event] = true;
+			result.push([
+				prevStateKey,
+				event,
+				target
+			]);
+		}
+	}
+	return result;
 }
-
-// src/core/new-fsm-process.ts
-function newFsmProcess(context, config, load) {
-  let started = false;
-  let terminated = false;
-  const process2 = new FsmProcess(config);
-  async function dispatch(event) {
-    return terminated || event !== void 0 && (!started || isStateTransitionEnabled(process2, event)) ? process2.dispatch(event) : false;
-  }
-  process2.onStateCreate((state) => {
-    started = true;
-    state.onEnter(async () => {
-      const modules = await load(state.key, process2.event) ?? [];
-      for (const module of Array.isArray(modules) ? modules : [modules]) {
-        const result = await module?.(context);
-        if (isGenerator2(result)) {
-          state.onExit(() => {
-            result.return?.(void 0);
-          });
-          (async () => {
-            for await (const event of result) {
-              if (terminated) {
-                break;
-              }
-              await dispatch(event);
-              if (terminated) {
-                break;
-              }
-            }
-          })();
-        } else if (typeof result === "function") {
-          state.onExit(result);
-        }
-      }
-    });
-  });
-  async function shutdown() {
-    await process2.shutdown();
-    terminated = true;
-  }
-  return [dispatch, shutdown];
-  function isGenerator2(value) {
-    return typeof value === "object" && value !== null && "next" in value && typeof value.next === "function";
-  }
+/**
+* Guard: would `event` trigger any transition in the process's current state? Used
+* to avoid dispatching dead events — the runner calls it before `dispatch`, and
+* consumers use it to enable/disable controls. Returns `true` iff `event` appears
+* among `getStateTransitions(process.state)`.
+*/
+function isStateTransitionEnabled(process, event) {
+	const transitions = getStateTransitions(process.state);
+	for (const [, ev] of transitions) if (ev === event) return true;
+	return false;
 }
-
-// src/orchestrator/constants.ts
-var KEY_DISPATCH = "fsm:dispatch";
-var KEY_TERMINATE = "fsm:terminate";
-var KEY_STATES = "fsm:states";
-var KEY_EVENT = "fsm:event";
-var KEY_REGISTER_CONFIG = "fsm:sys:registerConfig";
-var KEY_REGISTER_HANDLERS = "fsm:sys:registerHandlers";
-var KEY_LAUNCH_PROCESS = "fsm:sys:launch";
-
-// src/orchestrator/types.ts
-function toStageHandlers(value, accept) {
-  return visit(value);
-  function visit(val) {
-    if (!val) {
-      return [];
-    }
-    if (typeof val === "function") {
-      return [val];
-    }
-    if (typeof val !== "object") {
-      return [];
-    }
-    if (Array.isArray(val)) {
-      return val.flatMap(visit);
-    }
-    const modulesIndex = val;
-    return Object.entries(modulesIndex).flatMap(([key, value2]) => {
-      return accept(key, value2) ? visit(value2) : [];
-    });
-  }
+//#endregion
+//#region src/start-process.ts
+/** Context key: `(event) => Promise<void>` that dispatches an event (guarded). */
+const KEY_DISPATCH = "fsm:dispatch";
+/** Context key: `() => Promise<void>` that shuts the machine down. */
+const KEY_TERMINATE = "fsm:terminate";
+/** Context key: the current state-key stack (root→leaf), refreshed on every transition. */
+const KEY_STATES = "fsm:states";
+/** Context key: the last dispatched event. */
+const KEY_EVENT = "fsm:event";
+function isGenerator(value) {
+	return typeof value === "object" && value !== null && "next" in value && typeof value.next === "function";
 }
-
-// src/orchestrator/process-config-manager.ts
-var ProcessConfigManager = class {
-  constructor() {
-    this.configs = {};
-    this.handlers = {};
-  }
-  getProcessConfig(processName) {
-    return this.configs[processName] ?? { key: "Main" };
-  }
-  getHandlersLoader(processName) {
-    const config = this.getProcessConfig(processName);
-    return (stateKey) => {
-      const modulesKeys = [];
-      if (stateKey === config.key) {
-        modulesKeys.push("default");
-      }
-      modulesKeys.push(
-        stateKey,
-        `${stateKey}Controller`,
-        `${stateKey}StateController`,
-        `${stateKey}View`,
-        `${stateKey}StateView`,
-        `${stateKey}Trigger`,
-        `${stateKey}StateTrigger`,
-        `${stateKey}Test`,
-        `${stateKey}StateTest`
-      );
-      const keysSet = new Set(modulesKeys);
-      const processHandlers = this.handlers[processName] ?? [];
-      const handlers = toStageHandlers(
-        processHandlers,
-        (key) => keysSet.has(key)
-      );
-      return handlers;
-    };
-  }
-  registerConfig(name, config) {
-    this.configs[name] = config;
-    return () => {
-      delete this.configs[name];
-    };
-  }
-  registerHandlers(name, ...modules) {
-    let list = this.handlers[name];
-    if (!list) {
-      list = this.handlers[name] = [];
-    }
-    list.push(modules);
-    return () => {
-      list = list.filter((v) => v !== modules);
-      if (list.length === 0) {
-        delete this.handlers[name];
-      }
-    };
-  }
-};
-
-// src/utils/printer.ts
-var KEY_PRINTER = "printer";
-function preparePrinter(process2, { prefix = "", print = console.log, lineNumbers = false }) {
-  let lineCounter = 0;
-  const shift = () => {
-    let prefix2 = "";
-    for (let s = process2.state?.parent; s; s = s.parent) {
-      prefix2 += "  ";
-    }
-    return prefix2;
-  };
-  const getPrefix = lineNumbers ? () => `[${++lineCounter}]${shift()}` : shift;
-  const printer = (...args) => print(prefix, getPrefix(), ...args);
-  return printer;
+/**
+* Ergonomic runner: build a machine, attach behaviour via one `load` callback, and
+* bind the machine into `context`.
+*
+* Doing this by hand (`new FsmProcess` + `onStateCreate` + `onEnter` + a loader +
+* context wiring) is boilerplate every consumer repeats, so `startProcess` does it
+* once — most callers use this instead of the raw engine. It creates the process; on
+* each state entry calls `load(stateKey, event)` and installs the returned
+* `StageHandler`s (their return values become `onExit` cleanups or event-yielding
+* generators — see `StageHandler`); binds `KEY_DISPATCH` / `KEY_TERMINATE` /
+* `KEY_STATES` / `KEY_EVENT` into `context`; dispatches `startEvent` to enter the
+* initial state; and returns a `ProcessHandle`.
+*
+* @param context shared object handlers read/write and the machine is bound into
+* @param config the declarative machine definition
+* @param load returns the handler(s) to run for a given `(stateKey, event)`
+* @param startEvent initial event (default `""`, the eventless start)
+*/
+async function startProcess(context, config, load, startEvent = "") {
+	let terminated = false;
+	const ctx = context;
+	const process = new FsmProcess(config);
+	const statesStack = [];
+	process.onStateCreate((state) => {
+		state.onEnter(async () => {
+			statesStack.push(state.key);
+			ctx[KEY_STATES] = [...statesStack];
+			ctx[KEY_EVENT] = process.event;
+			const modules = await load(state.key, process.event) ?? [];
+			for (const module of Array.isArray(modules) ? modules : [modules]) {
+				const result = await module?.(context);
+				if (isGenerator(result)) {
+					let stateExited = false;
+					state.onExit(() => {
+						stateExited = true;
+						result.return?.(void 0);
+					});
+					(async () => {
+						try {
+							for await (const event of result) {
+								if (stateExited || terminated) break;
+								await dispatch(event);
+								if (stateExited || terminated) break;
+							}
+						} catch (error) {
+							if (!stateExited && !terminated) await state._handleError(error);
+						}
+					})();
+				} else if (typeof result === "function") state.onExit(result);
+			}
+		});
+		state.onExit(() => {
+			statesStack.pop();
+			ctx[KEY_STATES] = [...statesStack];
+			ctx[KEY_EVENT] = process.event;
+		});
+	});
+	async function dispatch(event) {
+		if (event !== void 0 && isStateTransitionEnabled(process, event)) await process.dispatch(event);
+	}
+	async function terminate() {
+		terminated = true;
+		await process.shutdown();
+	}
+	async function dumpProcess(...args) {
+		return process.dump(...args);
+	}
+	async function restoreProcess(dumpData, ...args) {
+		statesStack.length = 0;
+		terminated = false;
+		await process.restore(dumpData, ...args);
+		for (let state = process.state; state; state = state.parent) statesStack.unshift(state.key);
+		ctx[KEY_STATES] = [...statesStack];
+		ctx[KEY_EVENT] = process.event;
+	}
+	ctx[KEY_DISPATCH] = dispatch;
+	ctx[KEY_TERMINATE] = terminate;
+	await process.dispatch(startEvent);
+	return {
+		shutdown: terminate,
+		dump: dumpProcess,
+		restore: restoreProcess
+	};
 }
-function setPrinter(state, config = {}) {
-  const printer = preparePrinter(state.process, config);
-  state.setData(KEY_PRINTER, printer);
+/** Permanent equal alias of {@link startProcess} — the name existing consumers import. */
+const startFsmProcess = startProcess;
+//#endregion
+//#region src/trace/printer.ts
+const printerStore = /* @__PURE__ */ new WeakMap();
+/**
+* Build a `Printer` bound to `process` that indents each line by the current state
+* nesting depth (two spaces per level), so log output visually mirrors the state
+* tree — hierarchical indentation makes enter/exit traces readable at a glance.
+*/
+function preparePrinter(process, { prefix = "", print = console.log, lineNumbers = false }) {
+	let lineCounter = 0;
+	const shift = () => {
+		let prefix = "";
+		for (let s = process.state?.parent; s; s = s.parent) prefix += "  ";
+		return prefix;
+	};
+	const getPrefix = lineNumbers ? () => `[${++lineCounter}]${shift()}` : shift;
+	const printer = (...args) => print(prefix, getPrefix(), ...args);
+	return printer;
 }
-function setProcessPrinter(process2, config = {}) {
-  const printer = preparePrinter(process2, config);
-  process2.setData(KEY_PRINTER, printer);
+/**
+* Attach a printer to `process` (stored in a weak map so it is GC'd with the
+* process). Handlers/tracers then reach it via {@link getProcessPrinter} /
+* {@link getPrinter} rather than threading a logger through every call.
+*/
+function setProcessPrinter(process, config = {}) {
+	const printer = preparePrinter(process, config);
+	printerStore.set(process, printer);
 }
-function getProcessPrinter(process2) {
-  return process2.getData(KEY_PRINTER) || console.log;
+/** The printer attached to `process`, or `console.log` if none was set. */
+function getProcessPrinter(process) {
+	return printerStore.get(process) || console.log;
 }
+/** The printer for a state — its own if set, else its process's (see {@link getProcessPrinter}). */
 function getPrinter(state) {
-  return state.getData(KEY_PRINTER, true) || getProcessPrinter(state.process);
+	return printerStore.get(state) || getProcessPrinter(state.process);
 }
-
-// src/utils/tracer.ts
-function setProcessTracer(process2, print) {
-  return process2.onStateCreate((state) => {
-    setStateTracer(state, print);
-  });
+//#endregion
+//#region src/trace/tracer.ts
+/**
+* Trace every state of `process`: as each state is created, attach a state tracer —
+* so you can watch the machine move as a readable stream of enter/exit markers
+* without editing any handler. Hooks `onStateCreate` and delegates to
+* {@link setStateTracer}; pass a `print` sink to override the process printer.
+*/
+function setProcessTracer(process, print) {
+	return process.onStateCreate((state) => {
+		setStateTracer(state, print);
+	});
 }
+/**
+* Trace one state's lifecycle: emit `<key event="…">` on enter and `</key>` on exit
+* (XML-like, so nested states read as nested tags). Falls back to the state's
+* printer ({@link getPrinter}) when no `print` sink is given.
+*/
 function setStateTracer(state, print) {
-  state.onEnter(() => {
-    const printLine = print || getPrinter(state);
-    printLine(`<${state?.key} event="${state.process.event}">`);
-  });
-  state.onExit(async () => {
-    await Promise.resolve().then(async () => {
-      const printLine = print || getPrinter(state);
-      printLine(`</${state.key}> <!-- event="${state.process.event}" -->`);
-    });
-  });
-}
-
-// src/utils/process.ts
-function newProcess(config, {
-  prefix,
-  print,
-  lineNumbers = true
-}) {
-  const process2 = new FsmProcess(config);
-  setProcessPrinter(process2, {
-    prefix,
-    print,
-    lineNumbers
-  });
-  setProcessTracer(process2);
-  return process2;
+	state.onEnter(() => {
+		(print || getPrinter(state))(`<${state?.key} event="${state.process.event}">`);
+	});
+	state.onExit(async () => {
+		await Promise.resolve().then(async () => {
+			(print || getPrinter(state))(`</${state.key}> <!-- event="${state.process.event}" -->`);
+		});
+	});
 }
+//#endregion
+export { EVENT_ANY, EVENT_EMPTY, FsmBaseClass, FsmProcess, FsmState, FsmStateDescriptor, KEY_DISPATCH, KEY_EVENT, KEY_STATES, KEY_TERMINATE, STATE_ANY, STATE_FINAL, STATE_INITIAL, STATUS_ENTER, STATUS_EXIT, STATUS_FINISHED, STATUS_FIRST, STATUS_LAST, STATUS_LEAF, STATUS_NEXT, STATUS_NONE, bindMethods, getPrinter, getProcessPrinter, getStateTransitions, isStateTransitionEnabled, preparePrinter, setProcessPrinter, setProcessTracer, setStateTracer, startFsmProcess, startProcess };
 
-// src/orchestrator/is-generator.ts
-function isGenerator(value) {
-  return typeof value === "object" && value !== null && "next" in value && typeof value.next === "function";
-}
-
-// src/orchestrator/start-process.ts
-async function startFsmProcess(context, config, load, startEvent = "") {
-  let terminated = false;
-  const ctx = context;
-  const process2 = new FsmProcess(config);
-  const statesStack = [];
-  process2.onStateCreate((state) => {
-    state.onEnter(async () => {
-      statesStack.push(state.key);
-      ctx[KEY_STATES] = [...statesStack];
-      ctx[KEY_EVENT] = process2.event;
-      const modules = await load(state.key, process2.event) ?? [];
-      for (const module of Array.isArray(modules) ? modules : [modules]) {
-        const result = await module?.(context);
-        if (isGenerator(result)) {
-          let stateExited = false;
-          state.onExit(() => {
-            stateExited = true;
-            result.return?.(void 0);
-          });
-          (async () => {
-            for await (const event of result) {
-              if (stateExited || terminated) {
-                break;
-              }
-              await dispatch(event);
-            }
-          })();
-        } else if (typeof result === "function") {
-          state.onExit(result);
-        }
-      }
-    });
-    state.onExit(() => {
-      statesStack.pop();
-      ctx[KEY_STATES] = [...statesStack];
-      ctx[KEY_EVENT] = process2.event;
-    });
-  });
-  async function terminate() {
-    terminated = true;
-    await process2.shutdown();
-  }
-  async function dispatch(event) {
-    if (event !== void 0 && isStateTransitionEnabled(process2, event)) {
-      await process2.dispatch(event);
-    }
-  }
-  ctx[KEY_DISPATCH] = dispatch;
-  ctx[KEY_TERMINATE] = terminate;
-  await process2.dispatch(startEvent);
-  return terminate;
-}
-
-// src/orchestrator/launcher.ts
-function asArray(value, filter = (v) => v) {
-  if (value === void 0) return [];
-  const array = Array.isArray(value) ? value : [value];
-  return array.filter(Boolean).map(filter).filter(Boolean);
-}
-async function launcher(options) {
-  const configsManager = new ProcessConfigManager();
-  async function launch(processName, context, startEvent = "start") {
-    const config2 = configsManager.getProcessConfig(processName);
-    const load = configsManager.getHandlersLoader(processName);
-    return startFsmProcess(context, config2, load, startEvent);
-  }
-  function registerProcess(configsManager2, process2) {
-    if (!process2 || typeof process2 !== "object") {
-      throw new Error("Invalid process configuration: not an object");
-    }
-    const processName = process2.name;
-    if (!processName || typeof processName !== "string") {
-      throw new Error("Invalid process configuration: missing or invalid name");
-    }
-    const processConfig = process2.config;
-    if (processConfig && typeof processConfig !== "object") {
-      throw new Error(
-        `Invalid process configuration: config is not an object in process ${process2.name}`
-      );
-    }
-    if (processConfig) {
-      configsManager2.registerConfig(processName, processConfig);
-    }
-    const processHandlers = asArray(
-      process2.handlers ?? process2.handler ?? process2.default,
-      (v, idx) => {
-        if (typeof v === "function") return v;
-        if (typeof v === "object" && v !== null) return v;
-        throw new Error(
-          [
-            `Invalid process configuration:`,
-            `a process handler is not object nor function in process ${processName} at index ${idx}`,
-            `Recieved: ${v === null ? "null" : typeof v}`
-          ].join("\n")
-        );
-      }
-    );
-    if (processHandlers.length > 0) {
-      configsManager2.registerHandlers(processName, ...processHandlers);
-    }
-  }
-  const rootContext = { "fsm:launch": launch };
-  const init = typeof options === "function" ? options : async () => options;
-  const config = await init(rootContext);
-  if (typeof config !== "object" || !config) {
-    throw new Error("Invalid launcher configuration");
-  }
-  const processes = asArray(
-    config.processes ?? config.process ?? config.default,
-    (v) => {
-      if (typeof v === "function") {
-        return {
-          name: v.name || "",
-          handler: v
-        };
-      }
-      if (typeof v !== "object") {
-        throw new Error(
-          "Invalid launcher configuration: process is not an object"
-        );
-      }
-      return v;
-    }
-  );
-  const processesToStart = {};
-  for (const process2 of processes) {
-    const processName = process2.name;
-    const start = process2.start;
-    if (start === void 0) {
-      if (!(processName in processesToStart)) {
-        processesToStart[processName] = void 0;
-      }
-    } else {
-      processesToStart[processName] = start;
-    }
-    registerProcess(configsManager, process2);
-  }
-  const shutdowns = [];
-  let initContext = (context) => context;
-  const configContext = config.context ?? config.init;
-  if (configContext) {
-    if (typeof configContext === "function") {
-      initContext = configContext;
-    } else if (typeof configContext === "object") {
-      initContext = () => ({ parent: configContext });
-    } else {
-      throw new Error("Invalid launcher configuration: context");
-    }
-  }
-  for (const [processName, start] of Object.entries(processesToStart)) {
-    if (start === false) continue;
-    let context = {
-      parent: rootContext,
-      "fsm:name": processName
-    };
-    context = initContext(context) ?? context;
-    if (typeof context !== "object") {
-      throw new Error(
-        `Invalid launcher context for process "${processName}". Expected an object, but recieved ${typeof context}.`
-      );
-    }
-    const shutdown = await launch(processName, context);
-    shutdowns.push(shutdown);
-  }
-  return async () => {
-    for (const shutdown of shutdowns) {
-      await shutdown();
-    }
-  };
-}
-
-// src/orchestrator/resolve-module-refs.ts
-function resolveModulesUrls(baseUrl, ...refs) {
-  return refs.map((ref) => new URL(ref, baseUrl).href);
-}
-function resolveModulesPaths(baseUrl, ...refs) {
-  return refs.map((ref) => new URL(ref, baseUrl).pathname);
-}
-
-// src/orchestrator/start-processes.ts
-async function startProcesses({
-  onExit,
-  modules,
-  init
-}) {
-  const modulesList = [];
-  for (const module of modules) {
-    modulesList.push(
-      typeof module === "string" || module instanceof URL ? await import(String(module)) : module
-    );
-  }
-  return await launcher({
-    init,
-    processes: [
-      ...modulesList,
-      // This function is called on exit at the end of the process chain
-      function Exit() {
-        return onExit;
-      }
-    ]
-  });
-}
-
-// src/orchestrator/start-node-processes.ts
-async function startNodeProcesses(modules) {
-  try {
-    if (!modules) {
-      modules = process.argv.slice(2);
-    }
-    const terminate = await startProcesses({
-      modules: resolveModulesPaths(`file://${process.cwd()}/`, ...modules),
-      onExit: () => process.exit(0)
-    });
-    process.on("SIGINT", terminate);
-    process.on("SIGTERM", terminate);
-    process.stdin.resume();
-  } catch (err) {
-    console.error("Fatal error:", err);
-    process.exit(1);
-  }
-}
-
-// src/index.ts
-var index_default = startNodeProcesses;
-
-export { EVENT_ANY, EVENT_EMPTY, FsmProcess, FsmState, FsmStateDescriptor, KEY_DISPATCH, KEY_EVENT, KEY_LAUNCH_PROCESS, KEY_PRINTER, KEY_REGISTER_CONFIG, KEY_REGISTER_HANDLERS, KEY_STATES, KEY_TERMINATE, ProcessConfigManager, STATE_ANY, STATE_FINAL, STATE_INITIAL, STATUS_ENTER, STATUS_EXIT, STATUS_FINISHED, STATUS_FIRST, STATUS_LAST, STATUS_LEAF, STATUS_NEXT, STATUS_NONE, index_default as default, getPrinter, getProcessPrinter, getStateTransitions, isStateTransitionEnabled, launcher, newFsmProcess, newProcess, preparePrinter, resolveModulesPaths, resolveModulesUrls, setPrinter, setProcessPrinter, setProcessTracer, setStateTracer, startFsmProcess, startNodeProcesses, startProcesses, toStageHandlers };
-//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map