@statewalker/fsm 0.37.0 → 0.38.1

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/utils/printer.ts","../src/utils/tracer.ts"],"sourcesContent":["import type { FsmProcess } from \"../core/fsm-process.ts\";\nexport type Printer = (...args: unknown[]) => void;\nexport type PrinterConfig = {\n  prefix?: string;\n  print?: (...args: unknown[]) => void;\n  lineNumbers?: boolean;\n};\n\nconst printerStore = new WeakMap<object, Printer>();\n\nexport function preparePrinter(\n  process: FsmProcess,\n  { prefix = \"\", print = console.log, lineNumbers = false }: PrinterConfig,\n): Printer {\n  let lineCounter = 0;\n  const shift = () => {\n    let prefix = \"\";\n    for (let s = process.state?.parent; s; s = s.parent) {\n      prefix += \"  \";\n    }\n    return prefix;\n  };\n  const getPrefix = lineNumbers ? () => `[${++lineCounter}]${shift()}` : shift;\n  const printer = (...args: unknown[]) => print(prefix, getPrefix(), ...args);\n  return printer;\n}\n\nexport function setProcessPrinter(\n  process: FsmProcess,\n  config: PrinterConfig = {},\n) {\n  const printer = preparePrinter(process, config);\n  printerStore.set(process, printer);\n}\n\nexport function getProcessPrinter(process: FsmProcess): Printer {\n  return printerStore.get(process) || console.log;\n}\n\nexport function getPrinter(state: { process: FsmProcess }): Printer {\n  return printerStore.get(state) || getProcessPrinter(state.process);\n}\n","import type { FsmProcess } from \"../core/fsm-process.ts\";\nimport type { FsmState } from \"../core/fsm-state.ts\";\nimport { getPrinter, type Printer } from \"./printer.ts\";\n\nexport function setProcessTracer(process: FsmProcess, print?: Printer) {\n  return process.onStateCreate((state: FsmState) => {\n    setStateTracer(state, print);\n  });\n}\n\nexport function setStateTracer(state: FsmState, print?: Printer) {\n  state.onEnter(() => {\n    const printLine = print || getPrinter(state);\n    printLine(`<${state?.key} event=\"${state.process.event}\">`);\n  });\n  state.onExit(async () => {\n    await Promise.resolve().then(async () => {\n      const printLine = print || getPrinter(state);\n      printLine(`</${state.key}> <!-- event=\"${state.process.event}\" -->`);\n    });\n  });\n}\n"],"mappings":";;AAQA,MAAM,+BAAe,IAAI,SAA0B;AAEnD,SAAgB,eACd,SACA,EAAE,SAAS,IAAI,QAAQ,QAAQ,KAAK,cAAc,SACzC;CACT,IAAI,cAAc;CAClB,MAAM,cAAc;EAClB,IAAI,SAAS;AACb,OAAK,IAAI,IAAI,QAAQ,OAAO,QAAQ,GAAG,IAAI,EAAE,OAC3C,WAAU;AAEZ,SAAO;;CAET,MAAM,YAAY,oBAAoB,IAAI,EAAE,YAAY,GAAG,OAAO,KAAK;CACvE,MAAM,WAAW,GAAG,SAAoB,MAAM,QAAQ,WAAW,EAAE,GAAG,KAAK;AAC3E,QAAO;;AAGT,SAAgB,kBACd,SACA,SAAwB,EAAE,EAC1B;CACA,MAAM,UAAU,eAAe,SAAS,OAAO;AAC/C,cAAa,IAAI,SAAS,QAAQ;;AAGpC,SAAgB,kBAAkB,SAA8B;AAC9D,QAAO,aAAa,IAAI,QAAQ,IAAI,QAAQ;;AAG9C,SAAgB,WAAW,OAAyC;AAClE,QAAO,aAAa,IAAI,MAAM,IAAI,kBAAkB,MAAM,QAAQ;;;;ACpCpE,SAAgB,iBAAiB,SAAqB,OAAiB;AACrE,QAAO,QAAQ,eAAe,UAAoB;AAChD,iBAAe,OAAO,MAAM;GAC5B;;AAGJ,SAAgB,eAAe,OAAiB,OAAiB;AAC/D,OAAM,cAAc;AAElB,GADkB,SAAS,WAAW,MAAM,EAClC,IAAI,OAAO,IAAI,UAAU,MAAM,QAAQ,MAAM,IAAI;GAC3D;AACF,OAAM,OAAO,YAAY;AACvB,QAAM,QAAQ,SAAS,CAAC,KAAK,YAAY;AAEvC,IADkB,SAAS,WAAW,MAAM,EAClC,KAAK,MAAM,IAAI,gBAAgB,MAAM,QAAQ,MAAM,OAAO;IACpE;GACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/core/fsm-base-class.ts","../src/core/fsm-state.ts","../src/core/fsm-state-config.ts","../src/core/fsm-state-descriptor.ts","../src/core/fsm-process.ts","../src/core/fsm-transitions.ts","../src/start-process.ts","../src/trace/printer.ts","../src/trace/tracer.ts"],"sourcesContent":["type Handler<P extends unknown[] = unknown[], R = unknown> = (...args: P) => R;\n\n/**\n * Shared handler-registry substrate under both `FsmProcess` and `FsmState`.\n *\n * Both the process and every state need the same primitive: keep named lists of\n * callbacks (`onEnter`, `onExit`, `dump`, …) and run them with consistent ordering\n * and error routing. Centralising it here keeps the two subclasses thin and their\n * hook methods one-liners. `handlers` maps a hook name to its ordered callback list;\n * the protected `_addHandler` / `_removeHandler` / `_runHandler` manage and invoke\n * them. Handlers run **sequentially** (awaited in turn); a throwing handler is routed\n * to `_handleError` rather than aborting the batch. Subclasses expose typed sugar\n * (e.g. `state.onEnter(fn)` calls `_addHandler(\"onEnter\", fn)`) and override\n * `_handleError` to forward errors.\n */\nexport class FsmBaseClass {\n  handlers: Record<string, Handler[]> = {};\n\n  // ----------------------------------------------\n  // internal methods\n\n  /**\n   * Register `handler` under `type`; returns a disposer that removes it.\n   * `direct=false` prepends instead of appends — used so `onExit` handlers run in\n   * reverse (inner-to-outer) unwinding order.\n   */\n  protected _addHandler<T>(type: string, handler: T, direct: boolean = true) {\n    let list = this.handlers[type];\n    if (!list) {\n      list = this.handlers[type] = [];\n    }\n    const h = handler as Handler;\n    direct ? list.push(h) : list.unshift(h);\n    return () => this._removeHandler(type, h);\n  }\n\n  protected _removeHandler<T>(type: string, handler: T) {\n    let list = this.handlers[type];\n    if (!list) return;\n    list = list.filter((h) => h !== handler);\n    if (list.length > 0) {\n      this.handlers[type] = list;\n    } else {\n      delete this.handlers[type];\n    }\n  }\n\n  /** Run every handler of `type` in order, awaiting each; route throws to `_handleError`. */\n  async _runHandler(type: string, ...args: unknown[]) {\n    const list = this.handlers[type] || [];\n    for (const handler of list) {\n      try {\n        await handler(...args);\n      } catch (error) {\n        await this._handleError(error);\n      }\n    }\n  }\n\n  /** Default error sink — logs. `FsmState`/`FsmProcess` override it to fire `onStateError`. */\n  async _handleError(error: Error | unknown) {\n    console.error(error);\n  }\n}\n\n/**\n * Bind the named methods of `obj` to `obj` in place, so they can be passed as bare\n * callbacks (e.g. `ctx[KEY_DISPATCH] = process.dispatch`) without losing `this`.\n */\nexport function bindMethods<T>(obj: T, ...methods: (string | symbol)[]) {\n  const o = obj as Record<string | symbol, unknown>;\n  for (const methodName of methods) {\n    const method = o[methodName];\n    if (typeof method !== \"function\") continue;\n    o[methodName] = method.bind(o);\n  }\n  return obj;\n}\n","import { bindMethods, FsmBaseClass } from \"./fsm-base-class.ts\";\nimport type { FsmProcess } from \"./fsm-process.ts\";\nimport type { FsmStateDescriptor } from \"./fsm-state-descriptor.ts\";\n\n/** Serialized form of a single state: its `key` plus the `data` bag its `dump` hooks filled. */\nexport type FsmStateDump = Record<string, unknown> & {\n  key: string;\n  data: Record<string, unknown>;\n};\n/** An `onEnter` / `onExit` callback; receives the state it fired on. */\nexport type FsmStateHandler = (\n  state: FsmState,\n  ...args: unknown[]\n) => void | Promise<void>;\n\n/** A `dump` / `restore` callback; reads or fills the mutable per-state `data` bag. */\nexport type FsmStateDumpHandler = (\n  state: FsmState,\n  dump: FsmStateDump,\n) => void | Promise<void>;\n\n/** An `onStateError` callback; receives the error thrown by another handler on this state. */\nexport type FsmStateErrorHandler = (\n  state: FsmState,\n  error: unknown,\n) => void | Promise<void>;\n\n/**\n * One live node in a running machine's active-state stack.\n *\n * A state needs a place to attach behaviour and record data while it is active.\n * `FsmState` is that handle — created by the engine each time a state is entered,\n * discarded when it exits — so handlers can capture per-activation closures instead\n * of sharing mutable machine-wide state. It offers lifecycle hooks `onEnter` /\n * `onExit` / `onStateError`, serialization hooks `dump` / `restore`, and the tree\n * links `key` / `parent` / `descriptor`; every hook method returns a disposer.\n * Attach hooks from within `FsmProcess.onStateCreate((state) => …)`, or let\n * `startProcess` install them for you from a `load` callback.\n */\nexport class FsmState extends FsmBaseClass {\n  process: FsmProcess;\n  key: string;\n  parent?: FsmState;\n  descriptor?: FsmStateDescriptor;\n\n  constructor(\n    process: FsmProcess,\n    parent: FsmState | undefined,\n    key: string,\n    descriptor?: FsmStateDescriptor,\n  ) {\n    super();\n    this.process = process;\n    this.key = key;\n    this.parent = parent;\n    this.descriptor = descriptor;\n    bindMethods(this, \"onEnter\", \"onExit\", \"dump\", \"restore\", \"onStateError\");\n  }\n\n  /** Run when this state is entered. */\n  onEnter(handler: FsmStateHandler) {\n    return this._addHandler(\"onEnter\", handler, true);\n  }\n  /** Run when this state exits — registered inner-first so unwinding is inner-to-outer. */\n  onExit(handler: FsmStateHandler) {\n    return this._addHandler(\"onExit\", handler, false);\n  }\n  /** Handle an error thrown by another handler on this state (also bubbles to the process). */\n  onStateError(handler: FsmStateErrorHandler) {\n    return this._addHandler(\"onStateError\", handler);\n  }\n  /** Contribute to this state's snapshot: fill `dump.data` when the process is dumped. */\n  dump(handler: FsmStateDumpHandler) {\n    return this._addHandler(\"dump\", handler, true);\n  }\n  /** Rehydrate from this state's snapshot: read `dump.data` when the process is restored. */\n  restore(handler: FsmStateDumpHandler) {\n    return this._addHandler(\"restore\", handler, true);\n  }\n\n  async _handleError(error: Error | unknown) {\n    // Run the state's own error handlers directly — NOT via `_runHandler`, whose\n    // catch re-routes to `_handleError`, which would re-enter `onStateError`\n    // forever. A throw from an error handler terminates at `console.error`.\n    for (const handler of this.handlers.onStateError ?? []) {\n      try {\n        await handler(this, error);\n      } catch (e) {\n        console.error(e);\n      }\n    }\n    await this.process._handleStateError(this, error);\n  }\n}\n","// Sentinel keys used inside `FsmStateConfig.transitions` tuples. The raw `\"\"` and\n// `\"*\"` literals are ambiguous at the call site — `[\"\", \"start\", \"Active\"]` does not\n// visibly say \"from the *initial* state\" — so these named constants document intent\n// while keeping the runtime value (a shared empty string / asterisk) identical, which\n// keeps configs plain-serializable.\n\n/** Wildcard `from`-state: a transition that applies in *any* state. */\nexport const STATE_ANY = \"*\";\n/** Empty `from`-state: the *initial* pseudo-state a parent enters into. */\nexport const STATE_INITIAL = \"\";\n/** Empty `to`-state: the *final* pseudo-state; entering it exits the parent. */\nexport const STATE_FINAL = \"\";\n/** Wildcard `event`: a transition triggered by *any* event. */\nexport const EVENT_ANY = \"*\";\n/** Empty event: the eventless/automatic transition (fires with no named event). */\nexport const EVENT_EMPTY = \"\";\n\nexport type FsmStateKey = string;\nexport type FsmEventKey = string;\n\n/**\n * Declarative definition of a (possibly nested) state machine.\n *\n * One plain-object shape describes an entire HFSM, so machines stay serializable,\n * diffable, and inspectable by tooling — the config is data, not code. A config has:\n * - `key` — the state's name (unique among its siblings);\n * - `transitions` — `[from, event, to]` tuples, where `from`/`to` name sibling\n *   states, `\"\"` is the initial (`from`) or final (`to`) pseudo-state, and `\"*\"` is a\n *   wildcard (see the constants above);\n * - `states` — nested child configs; entering this state descends into its initial\n *   child. The index signature lets consumers attach arbitrary metadata.\n *\n * Pass a config to `new FsmProcess(config)` or `startProcess(ctx, config, …)`; it is\n * compiled once into an `FsmStateDescriptor` for fast lookup at runtime.\n */\nexport type FsmStateConfig = {\n  key: FsmStateKey;\n  transitions?: [from: FsmStateKey, event: FsmEventKey, to: FsmStateKey][];\n  states?: FsmStateConfig[];\n} & Record<string, unknown>;\n","import {\n  EVENT_ANY,\n  type FsmStateConfig,\n  STATE_ANY,\n  STATE_FINAL,\n} from \"./fsm-state-config.ts\";\n\n/**\n * The *compiled* form of an `FsmStateConfig` subtree.\n *\n * Resolving a transition happens on every event, so the flat `[from, event, to]`\n * tuple list is pre-indexed once into nested maps for O(1) lookup, and the\n * wildcard-fallback order is applied here rather than re-derived on each dispatch.\n * The shape is `transitions[from][event] = to` plus a `states` map of child\n * descriptors. `FsmProcess` builds one from your config in its constructor; you\n * rarely construct a descriptor directly.\n */\nexport class FsmStateDescriptor {\n  transitions: Record<string, Record<string, string>> = {};\n  states: Record<string, FsmStateDescriptor> = {};\n\n  /**\n   * Recursively compile a config (and its nested `states`) into descriptors,\n   * turning the tuple list into the indexed `transitions` map.\n   */\n  static build(config: FsmStateConfig) {\n    const descriptor = new FsmStateDescriptor();\n    for (const [from, event, to] of config.transitions || []) {\n      let index = descriptor.transitions[from];\n      if (!index) {\n        index = descriptor.transitions[from] = {};\n      }\n      index[event] = to;\n    }\n    if (config.states) {\n      for (const substateConfig of config.states) {\n        descriptor.states[substateConfig.key] =\n          FsmStateDescriptor.build(substateConfig);\n      }\n    }\n    return descriptor;\n  }\n\n  /**\n   * Resolve the target state for a `(stateKey, eventKey)` pair. Tries the most\n   * specific match first, then falls back through the wildcards —\n   * `(state, event)` → `(*, event)` → `(state, *)` → `(*, *)` — and returns\n   * `STATE_FINAL` if nothing matches, so an unmatched event exits the state rather\n   * than silently doing nothing.\n   */\n  getTargetStateKey(stateKey: string, eventKey: string) {\n    const pairs = [\n      [stateKey, eventKey],\n      [STATE_ANY, eventKey],\n      [stateKey, EVENT_ANY],\n      [STATE_ANY, EVENT_ANY],\n    ];\n    let targetKey: string | undefined;\n    for (\n      let i = 0, len = pairs.length;\n      targetKey === undefined && i < len;\n      i++\n    ) {\n      const [stateKey, eventKey] = pairs[i];\n      const stateTransitions = this.transitions[stateKey];\n      if (!stateTransitions) continue;\n      targetKey = stateTransitions[eventKey];\n    }\n    return targetKey !== undefined ? targetKey : STATE_FINAL;\n  }\n}\n","import { bindMethods, FsmBaseClass } from \"./fsm-base-class.ts\";\nimport {\n  FsmState,\n  type FsmStateDump,\n  type FsmStateHandler,\n} from \"./fsm-state.ts\";\nimport {\n  EVENT_EMPTY,\n  type FsmStateConfig,\n  STATE_FINAL,\n  STATE_INITIAL,\n} from \"./fsm-state-config.ts\";\nimport { FsmStateDescriptor } from \"./fsm-state-descriptor.ts\";\n\n// Status bitmask: where the process is in the enter/exit cycle of `dispatch`.\n// Why a bitmask (rather than an enum): the loop tests *phases* with cheap bitwise\n// masks — `status & STATUS_ENTER`, `status & this.mask` — and composite masks\n// (ENTER / EXIT) are just OR-combinations of the primitive bits.\n/** Not started / no current transition. */\nexport const STATUS_NONE = 0;\n/** Entering: descended into a parent's first (initial) child. */\nexport const STATUS_FIRST = 1;\n/** Entering: advanced to a resolved target (sibling) state. */\nexport const STATUS_NEXT = 2;\n/** Rested on a leaf — dispatch returns control here (the default `mask`). */\nexport const STATUS_LEAF = 4;\n/** Exiting: popped back up to the parent state. */\nexport const STATUS_LAST = 8;\n/** Terminated: the machine has exited its root and cannot advance further. */\nexport const STATUS_FINISHED = 16;\n\n//\n/** Composite: any \"entering\" phase. */\nexport const STATUS_ENTER = STATUS_FIRST | STATUS_NEXT;\n/** Composite: any \"exiting\" phase. */\nexport const STATUS_EXIT = STATUS_LEAF | STATUS_LAST;\n\n/** A process-level handler (`onStateCreate` / `onStateError`). */\nexport type FsmProcessHandler = (\n  process: FsmProcess,\n  ...args: unknown[]\n) => void | Promise<void>;\n\n/** Serialized form of the whole machine: status, last event, and the root→leaf state stack. */\nexport type FsmProcessDump = Record<string, unknown> & {\n  status: number;\n  event?: string;\n  stack: FsmStateDump[];\n};\n\nexport type FsmProcessDumpHandler = (\n  process: FsmProcess,\n  dump: FsmProcessDump,\n) => void | Promise<void>;\n\n/**\n * The running state machine — owner of the active-state stack and the traversal.\n *\n * This is the engine: given a compiled config it drives the enter/exit walk in\n * response to events, so callers reason in terms of states and events, not manual\n * stack bookkeeping. `dispatch(event)` advances the machine to the next resting leaf;\n * `shutdown(event?)` unwinds every active state; `state` is the current leaf;\n * `onStateCreate(handler)` is the primary extension point (fires once per created\n * state — attach that state's hooks there); and `dump()` / `restore(dump)` snapshot\n * and rehydrate the whole stack. Typical use: `new FsmProcess(config)`, register\n * `onStateCreate`, then `dispatch(\"\")` to enter the initial state and\n * `dispatch(event)` for each subsequent event.\n */\nexport class FsmProcess extends FsmBaseClass {\n  state?: FsmState;\n  event?: string;\n  nextEvents: string[] = [];\n  running: boolean = false;\n  mask: number = STATUS_LEAF;\n  status: number = 0;\n  config: FsmStateConfig;\n  rootDescriptor: FsmStateDescriptor;\n\n  constructor(config: FsmStateConfig) {\n    super();\n    this.rootDescriptor = FsmStateDescriptor.build(config);\n    this.config = config;\n    bindMethods(this, \"dispatch\", \"dump\", \"restore\");\n  }\n\n  /** Force-exit the whole stack (root last), running each state's `onExit`; ends the machine. */\n  async shutdown(event?: string) {\n    while (this.state) {\n      this.event = event;\n      this.status = STATUS_FINISHED;\n      await this.state?._runHandler(\"onExit\", this.state);\n      this.state = this.state.parent;\n    }\n  }\n\n  /**\n   * Feed an event to the machine and run the enter/exit cycle until it rests on a\n   * leaf (`status & mask`) or finishes.\n   *\n   * If a dispatch is already running (e.g. an `onEnter` handler dispatches\n   * synchronously), the event is appended to the `nextEvents` FIFO queue and applied\n   * — in order, none dropped — when the current run settles; runs never nest. Returns\n   * `false` once the machine has finished, `true` otherwise.\n   */\n  async dispatch(event: string): Promise<boolean> {\n    // Queue the event. Re-entrant dispatches (from handlers running mid-settle)\n    // append here and are drained in order — so no earlier event is overwritten.\n    this.nextEvents.push(event);\n    if (!this.running && !(this.status & STATUS_FINISHED)) {\n      this.running = true;\n      try {\n        while (this.nextEvents.length > 0) {\n          this.event = this.nextEvents.shift();\n          while (true) {\n            // ---\n            if (this.status & STATUS_EXIT) {\n              await this.state?._runHandler(\"onExit\", this.state);\n            }\n            if (!(await this._update())) break;\n            if (this.status & STATUS_ENTER) {\n              await this.state?._runHandler(\"onEnter\", this.state);\n            }\n            if (this.status & this.mask) break;\n            // ---\n          }\n          if (this.status & STATUS_FINISHED) break;\n        }\n      } finally {\n        this.running = false;\n      }\n    }\n    return !(this.status & STATUS_FINISHED);\n  }\n\n  /**\n   * Snapshot the machine to a plain object: `{ status, event, stack }` where the\n   * stack is root→leaf, each entry carrying whatever its `dump` hooks recorded.\n   */\n  async dump(...args: unknown[]): Promise<FsmProcessDump> {\n    const dumpState = async (state: FsmState) => {\n      const stateDump: FsmStateDump = {\n        key: state.key,\n        data: {},\n      };\n      await state._runHandler(\"dump\", state, stateDump.data, ...args);\n      return stateDump;\n    };\n    const dumpStates = async (\n      state: FsmState | undefined,\n      stack: FsmStateDump[] = [],\n    ) => {\n      if (!state) return stack;\n      state.parent && (await dumpStates(state.parent, stack));\n      stack.push(await dumpState(state));\n      return stack;\n    };\n    const dump: FsmProcessDump = {\n      status: this.status,\n      event: this.event,\n      stack: await dumpStates(this.state),\n    };\n    return dump;\n  }\n\n  /**\n   * Rebuild the machine from a `dump`: recreate each state in the stack (firing\n   * `onStateCreate`) and replay its `restore` hooks, leaving the process resumable\n   * from where it was snapshotted.\n   */\n  async restore(dump: FsmProcessDump, ...args: unknown[]) {\n    this.status = dump.status || 0;\n    this.event = dump.event;\n    this.state = undefined;\n    for (let i = 0; i < dump.stack.length; i++) {\n      const stateDump = dump.stack[i];\n      this.state = this.state\n        ? await this._newSubstate(this.state, stateDump.key)\n        : await this._newState(undefined, stateDump.key, this.rootDescriptor);\n      await this.state._runHandler(\n        \"restore\",\n        this.state,\n        stateDump.data,\n        ...args,\n      );\n    }\n    return this;\n  }\n\n  /** Primary extension point: fires once for every state the machine creates. */\n  onStateCreate(handler: FsmStateHandler) {\n    return this._addHandler(\"onStateCreate\", handler, true);\n  }\n\n  onStateError(\n    handler: (state: FsmState, error: unknown) => void | Promise<void>,\n  ) {\n    return this._addHandler(\"onStateError\", handler);\n  }\n\n  async _handleStateError(state: FsmState, error: Error | unknown) {\n    await this._runHandler(\"onStateError\", state, error);\n    this._handleError(error);\n  }\n\n  async _newState(\n    parent: FsmState | undefined,\n    key: string,\n    descriptor: FsmStateDescriptor | undefined,\n  ) {\n    const state = new FsmState(this, parent, key, descriptor);\n    await this._runHandler(\"onStateCreate\", state);\n    return state;\n  }\n\n  async _getSubstate(\n    parent: FsmState | undefined,\n    prevStateKey: string | undefined,\n  ) {\n    if (!parent) return;\n    const toState =\n      parent.descriptor?.getTargetStateKey(\n        prevStateKey || STATE_INITIAL,\n        this.event || EVENT_EMPTY,\n      ) || STATE_FINAL;\n    if (!toState) return;\n    return this._newSubstate(parent, toState);\n  }\n\n  async _newSubstate(parent: FsmState | undefined, toState: string) {\n    let descriptor: FsmStateDescriptor | undefined;\n    for (\n      let state: FsmState | undefined = parent;\n      !descriptor && state;\n      state = state.parent\n    ) {\n      descriptor = state.descriptor?.states[toState];\n    }\n    return this._newState(parent, toState, descriptor);\n  }\n\n  /**\n   * One step of the traversal: compute the next state and update `status`.\n   *\n   * Either descends to a child / advances to a resolved target (setting an ENTER\n   * status), or — when no target resolves — settles on the current leaf\n   * (`STATUS_LEAF`) or pops to the parent (`STATUS_LAST`), reaching `STATUS_FINISHED`\n   * once the root is exited. Returns `false` when finished.\n   */\n  async _update() {\n    if (this.status & STATUS_FINISHED) return false;\n    const nextState =\n      this.status !== STATUS_NONE\n        ? this.status & STATUS_ENTER\n          ? await this._getSubstate(this.state, STATE_INITIAL)\n          : await this._getSubstate(this.state?.parent, this.state?.key)\n        : await this._newState(undefined, this.config.key, this.rootDescriptor);\n    if (nextState !== undefined) {\n      this.state = nextState;\n      this.status = this.status & STATUS_EXIT ? STATUS_NEXT : STATUS_FIRST;\n    } else {\n      if (this.status & STATUS_EXIT) {\n        this.state = this.state?.parent;\n        this.status = STATUS_LAST;\n      } else {\n        this.status = STATUS_LEAF;\n      }\n      if (!this.state) this.status = STATUS_FINISHED;\n    }\n    return !(this.status & STATUS_FINISHED);\n  }\n}\n","import type { FsmProcess } from \"./fsm-process.ts\";\nimport type { FsmState } from \"./fsm-state.ts\";\nimport { EVENT_ANY } from \"./fsm-state-config.ts\";\nimport type { FsmStateDescriptor } from \"./fsm-state-descriptor.ts\";\n\n// ---------------------------------------------------------------------------\n// Transition introspection — read-only queries over the state/transition graph\n// ---------------------------------------------------------------------------\n\n/**\n * List the transitions currently reachable from `state` — for a UI or viewer that\n * needs to know which events can fire right now (e.g. to render only the enabled\n * buttons). Collects `[from, event, to]` tuples by walking up the parent chain; the\n * nearest state's rule for an event wins, so an outer fallback is masked by an inner\n * override. The returned tuples are ordered outer→inner (root first).\n */\nexport function getStateTransitions(\n  state?: FsmState,\n): [from: string, event: string, to: string][] {\n  const result: [from: string, event: string, to: string][] = [];\n  const index: Record<string, boolean> = {};\n  if (state) {\n    let prevStateKey = state.key;\n    for (let parent = state.parent; parent; parent = parent.parent) {\n      if (!parent.descriptor) continue;\n      result.push(\n        ...getTransitionsFromDescriptor(parent.descriptor, prevStateKey, index),\n      );\n      prevStateKey = parent.key;\n    }\n  }\n  return result.reverse();\n}\n\nfunction getTransitionsFromDescriptor(\n  descriptor: FsmStateDescriptor,\n  prevStateKey: string,\n  index: Record<string, boolean>,\n): [from: string, event: string, to: string][] {\n  const result: [from: string, event: string, to: string][] = [];\n  const prevStateKeys = [prevStateKey, \"*\"];\n  for (const prevKey of prevStateKeys) {\n    const targets = descriptor.transitions[prevKey];\n    if (targets) {\n      for (const [event, target] of Object.entries(targets)) {\n        if (index[event]) continue;\n        // Mark the event seen regardless of target — an inner exit-to-final\n        // (`to === \"\"`, a falsy target) must still mask an outer rule for the\n        // same event, matching what `dispatch` actually resolves.\n        index[event] = true;\n        result.push([prevStateKey, event, target]);\n      }\n    }\n  }\n  return result;\n}\n\n/**\n * Guard: would `event` trigger any transition in the process's current state? Used\n * to avoid dispatching dead events — the runner calls it before `dispatch`, and\n * consumers use it to enable/disable controls. Returns `true` iff `event` appears\n * among `getStateTransitions(process.state)`.\n */\nexport function isStateTransitionEnabled(\n  process: FsmProcess,\n  event: string,\n): boolean {\n  const transitions = getStateTransitions(process.state);\n  for (const [, ev] of transitions) {\n    // A wildcard-event rule (`ev === EVENT_ANY`) matches any concrete event, just\n    // as the engine's `getTargetStateKey` falls back to `(state, *)` / `(*, *)`.\n    if (ev === event || ev === EVENT_ANY) return true;\n  }\n  return false;\n}\n","import { FsmProcess, type FsmProcessDump } from \"./core/fsm-process.ts\";\nimport type { FsmState } from \"./core/fsm-state.ts\";\nimport type { FsmStateConfig } from \"./core/fsm-state-config.ts\";\nimport { isStateTransitionEnabled } from \"./core/fsm-transitions.ts\";\n\n/**\n * Per-state behaviour contract used by `startProcess`. One function shape expresses\n * what to do while in a state, and its *return value* wires up the rest, so a state's\n * setup and teardown live together. The handler runs on entry with the shared\n * `context` and may return:\n * - nothing — no teardown;\n * - a cleanup `function` — registered as this state's `onExit`;\n * - an async/sync generator — run concurrently, each yielded string dispatched back\n *   into the machine (self-driving/reactive states), auto-`return()`ed on exit.\n */\nexport type StageHandler<C = Record<string, unknown>> = (\n  context: C,\n) =>\n  | void\n  | (() => void | Promise<void>)\n  | Promise<void | (() => void | Promise<void>)>\n  | AsyncGenerator<string, void, unknown>\n  | Generator<string, void, unknown>;\n\n/**\n * The caller's remote control returned by `startProcess`: stop the machine and\n * snapshot/rehydrate it without holding a reference to the underlying `FsmProcess`.\n */\nexport interface ProcessHandle {\n  shutdown(): Promise<void>;\n  dump(...args: unknown[]): Promise<FsmProcessDump>;\n  restore(dump: FsmProcessDump, ...args: unknown[]): Promise<void>;\n}\n\n// Context keys under which `startProcess` binds the machine into the shared context\n// object. Why via context (not closures): handlers reach the running machine\n// uniformly — `(ctx[KEY_DISPATCH])(event)` — regardless of where they are defined.\n/** Context key: `(event) => Promise<void>` that dispatches an event (guarded). */\nexport const KEY_DISPATCH = \"fsm:dispatch\";\n/** Context key: `() => Promise<void>` that shuts the machine down. */\nexport const KEY_TERMINATE = \"fsm:terminate\";\n/** Context key: the current state-key stack (root→leaf), refreshed on every transition. */\nexport const KEY_STATES = \"fsm:states\";\n/** Context key: the last dispatched event. */\nexport const KEY_EVENT = \"fsm:event\";\n\n// ---------------------------------------------------------------------------\n// Generator detection\n// ---------------------------------------------------------------------------\n\nfunction isGenerator(\n  value: unknown,\n): value is\n  | Generator<string, void, unknown>\n  | AsyncGenerator<string, void, unknown> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"next\" in value &&\n    typeof (value as { next: unknown }).next === \"function\"\n  );\n}\n\n// ---------------------------------------------------------------------------\n// startProcess (also exported as startFsmProcess for backward compat)\n// ---------------------------------------------------------------------------\n\n/**\n * Ergonomic runner: build a machine, attach behaviour via one `load` callback, and\n * bind the machine into `context`.\n *\n * Doing this by hand (`new FsmProcess` + `onStateCreate` + `onEnter` + a loader +\n * context wiring) is boilerplate every consumer repeats, so `startProcess` does it\n * once — most callers use this instead of the raw engine. It creates the process; on\n * each state entry calls `load(stateKey, event)` and installs the returned\n * `StageHandler`s (their return values become `onExit` cleanups or event-yielding\n * generators — see `StageHandler`); binds `KEY_DISPATCH` / `KEY_TERMINATE` /\n * `KEY_STATES` / `KEY_EVENT` into `context`; dispatches `startEvent` to enter the\n * initial state; and returns a `ProcessHandle`.\n *\n * @param context shared object handlers read/write and the machine is bound into\n * @param config the declarative machine definition\n * @param load returns the handler(s) to run for a given `(stateKey, event)`\n * @param startEvent initial event (default `\"\"`, the eventless start)\n */\nexport async function startProcess<C = unknown>(\n  context: C,\n  config: FsmStateConfig,\n  load: (\n    state: string,\n    event: string | undefined,\n  ) => StageHandler<C>[] | Promise<StageHandler<C>[]>,\n  startEvent = \"\",\n): Promise<ProcessHandle> {\n  let terminated = false;\n  const ctx = context as Record<string, unknown>;\n  const process = new FsmProcess(config);\n  const statesStack: string[] = [];\n\n  process.onStateCreate((state: FsmState) => {\n    state.onEnter(async () => {\n      statesStack.push(state.key);\n      ctx[KEY_STATES] = [...statesStack];\n      ctx[KEY_EVENT] = process.event;\n\n      const modules = (await load(state.key, process.event)) ?? [];\n      for (const module of Array.isArray(modules) ? modules : [modules]) {\n        const result = await module?.(context);\n        if (isGenerator(result)) {\n          let stateExited = false;\n          state.onExit(() => {\n            stateExited = true;\n            result.return?.(undefined as never);\n          });\n          (async () => {\n            try {\n              for await (const event of result) {\n                if (stateExited || terminated) break;\n                await dispatch(event);\n                if (stateExited || terminated) break;\n              }\n            } catch (error) {\n              // A generator `return()` during state exit / termination throws an\n              // abort we intentionally swallow; a genuine error thrown by the\n              // generator body must surface through the state's error handling\n              // rather than vanish.\n              if (!stateExited && !terminated) await state._handleError(error);\n            }\n          })();\n        } else if (typeof result === \"function\") {\n          state.onExit(result as () => void | Promise<void>);\n        }\n      }\n    });\n    state.onExit(() => {\n      statesStack.pop();\n      ctx[KEY_STATES] = [...statesStack];\n      ctx[KEY_EVENT] = process.event;\n    });\n  });\n\n  async function dispatch(event: string): Promise<void> {\n    if (event !== undefined && isStateTransitionEnabled(process, event)) {\n      await process.dispatch(event);\n    }\n  }\n  async function terminate(): Promise<void> {\n    terminated = true;\n    await process.shutdown();\n  }\n\n  async function dumpProcess(...args: unknown[]): Promise<FsmProcessDump> {\n    return process.dump(...args);\n  }\n\n  async function restoreProcess(\n    dumpData: FsmProcessDump,\n    ...args: unknown[]\n  ): Promise<void> {\n    statesStack.length = 0;\n    terminated = false;\n    await process.restore(dumpData, ...args);\n    for (\n      let state: FsmState | undefined = process.state;\n      state;\n      state = state.parent\n    ) {\n      statesStack.unshift(state.key);\n    }\n    ctx[KEY_STATES] = [...statesStack];\n    ctx[KEY_EVENT] = process.event;\n  }\n\n  ctx[KEY_DISPATCH] = dispatch;\n  ctx[KEY_TERMINATE] = terminate;\n  await process.dispatch(startEvent);\n  return {\n    shutdown: terminate,\n    dump: dumpProcess,\n    restore: restoreProcess,\n  };\n}\n\n/** Permanent equal alias of {@link startProcess} — the name existing consumers import. */\nexport const startFsmProcess = startProcess;\n","import type { FsmProcess } from \"../core/fsm-process.ts\";\n\n/** A sink for trace output — anything shaped like `console.log`. */\nexport type Printer = (...args: unknown[]) => void;\n/**\n * Tuning for a `Printer`.\n * - `prefix` — string prepended to every line (e.g. a process tag).\n * - `print` — the underlying sink (defaults to `console.log`).\n * - `lineNumbers` — prepend an incrementing `[n]` counter.\n */\nexport type PrinterConfig = {\n  prefix?: string;\n  print?: (...args: unknown[]) => void;\n  lineNumbers?: boolean;\n};\n\nconst printerStore = new WeakMap<object, Printer>();\n\n/**\n * Build a `Printer` bound to `process` that indents each line by the current state\n * nesting depth (two spaces per level), so log output visually mirrors the state\n * tree — hierarchical indentation makes enter/exit traces readable at a glance.\n */\nexport function preparePrinter(\n  process: FsmProcess,\n  { prefix = \"\", print = console.log, lineNumbers = false }: PrinterConfig,\n): Printer {\n  let lineCounter = 0;\n  const shift = () => {\n    let prefix = \"\";\n    for (let s = process.state?.parent; s; s = s.parent) {\n      prefix += \"  \";\n    }\n    return prefix;\n  };\n  const getPrefix = lineNumbers ? () => `[${++lineCounter}]${shift()}` : shift;\n  const printer = (...args: unknown[]) => print(prefix, getPrefix(), ...args);\n  return printer;\n}\n\n/**\n * Attach a printer to `process` (stored in a weak map so it is GC'd with the\n * process). Handlers/tracers then reach it via {@link getProcessPrinter} /\n * {@link getPrinter} rather than threading a logger through every call.\n */\nexport function setProcessPrinter(\n  process: FsmProcess,\n  config: PrinterConfig = {},\n) {\n  const printer = preparePrinter(process, config);\n  printerStore.set(process, printer);\n}\n\n/** The printer attached to `process`, or `console.log` if none was set. */\nexport function getProcessPrinter(process: FsmProcess): Printer {\n  return printerStore.get(process) || console.log;\n}\n\n/** The printer for a state — its own if set, else its process's (see {@link getProcessPrinter}). */\nexport function getPrinter(state: { process: FsmProcess }): Printer {\n  return printerStore.get(state) || getProcessPrinter(state.process);\n}\n","import type { FsmProcess } from \"../core/fsm-process.ts\";\nimport type { FsmState } from \"../core/fsm-state.ts\";\nimport { getPrinter, type Printer } from \"./printer.ts\";\n\n/**\n * Trace every state of `process`: as each state is created, attach a state tracer —\n * so you can watch the machine move as a readable stream of enter/exit markers\n * without editing any handler. Hooks `onStateCreate` and delegates to\n * {@link setStateTracer}; pass a `print` sink to override the process printer.\n */\nexport function setProcessTracer(process: FsmProcess, print?: Printer) {\n  return process.onStateCreate((state: FsmState) => {\n    setStateTracer(state, print);\n  });\n}\n\n/**\n * Trace one state's lifecycle: emit `<key event=\"…\">` on enter and `</key>` on exit\n * (XML-like, so nested states read as nested tags). Falls back to the state's\n * printer ({@link getPrinter}) when no `print` sink is given.\n */\nexport function setStateTracer(state: FsmState, print?: Printer) {\n  state.onEnter(() => {\n    const printLine = print || getPrinter(state);\n    printLine(`<${state?.key} event=\"${state.process.event}\">`);\n  });\n  state.onExit(async () => {\n    await Promise.resolve().then(async () => {\n      const printLine = print || getPrinter(state);\n      printLine(`</${state.key}> <!-- event=\"${state.process.event}\" -->`);\n    });\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/fsm",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "description": "HFSM Implementation",
   "keywords": [],
   "homepage": "https://github.com/statewalker/statewalker-fsm",
@@ -10,11 +10,7 @@
   },
   "license": "MIT",
   "type": "module",
-  "bin": {
-    "fsm": "./bin/cli.js"
-  },
   "files": [
-    "bin",
     "dist",
     "src"
   ],
@@ -28,19 +24,13 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    },
-    "./*": {
-      "source": "./src/*.ts",
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*.js",
-      "default": "./dist/*.js"
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.0",
-    "tsdown": "^0.12.4",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "@biomejs/biome": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "^6.0.3",
+    "vitest": "catalog:"
   },
   "repository": {
     "type": "git",

package/src/core/fsm-base-class.ts

@@ -1,10 +1,29 @@
 type Handler<P extends unknown[] = unknown[], R = unknown> = (...args: P) => R;
 
+/**
+ * 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.
+ */
 export class FsmBaseClass {
   handlers: Record<string, Handler[]> = {};
 
   // ----------------------------------------------
   // internal methods
+
+  /**
+   * 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.
+   */
   protected _addHandler<T>(type: string, handler: T, direct: boolean = true) {
     let list = this.handlers[type];
     if (!list) {
@@ -26,6 +45,7 @@ export class FsmBaseClass {
     }
   }
 
+  /** Run every handler of `type` in order, awaiting each; route throws to `_handleError`. */
   async _runHandler(type: string, ...args: unknown[]) {
     const list = this.handlers[type] || [];
     for (const handler of list) {
@@ -37,11 +57,16 @@ export class FsmBaseClass {
     }
   }
 
+  /** Default error sink — logs. `FsmState`/`FsmProcess` override it to fire `onStateError`. */
   async _handleError(error: Error | unknown) {
     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`.
+ */
 export function bindMethods<T>(obj: T, ...methods: (string | symbol)[]) {
   const o = obj as Record<string | symbol, unknown>;
   for (const methodName of methods) {

package/src/core/fsm-process.ts

@@ -12,22 +12,36 @@ import {
 } from "./fsm-state-config.ts";
 import { FsmStateDescriptor } from "./fsm-state-descriptor.ts";
 
+// Status bitmask: where the process is in the enter/exit cycle of `dispatch`.
+// Why a bitmask (rather than an enum): the loop tests *phases* with cheap bitwise
+// masks — `status & STATUS_ENTER`, `status & this.mask` — and composite masks
+// (ENTER / EXIT) are just OR-combinations of the primitive bits.
+/** Not started / no current transition. */
 export const STATUS_NONE = 0;
+/** Entering: descended into a parent's first (initial) child. */
 export const STATUS_FIRST = 1;
+/** Entering: advanced to a resolved target (sibling) state. */
 export const STATUS_NEXT = 2;
+/** Rested on a leaf — dispatch returns control here (the default `mask`). */
 export const STATUS_LEAF = 4;
+/** Exiting: popped back up to the parent state. */
 export const STATUS_LAST = 8;
+/** Terminated: the machine has exited its root and cannot advance further. */
 export const STATUS_FINISHED = 16;
 
 //
+/** Composite: any "entering" phase. */
 export const STATUS_ENTER = STATUS_FIRST | STATUS_NEXT;
+/** Composite: any "exiting" phase. */
 export const STATUS_EXIT = STATUS_LEAF | STATUS_LAST;
 
+/** A process-level handler (`onStateCreate` / `onStateError`). */
 export type FsmProcessHandler = (
   process: FsmProcess,
   ...args: unknown[]
 ) => void | Promise<void>;
 
+/** Serialized form of the whole machine: status, last event, and the root→leaf state stack. */
 export type FsmProcessDump = Record<string, unknown> & {
   status: number;
   event?: string;
@@ -39,10 +53,23 @@ export type FsmProcessDumpHandler = (
   dump: FsmProcessDump,
 ) => void | Promise<void>;
 
+/**
+ * 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.
+ */
 export class FsmProcess extends FsmBaseClass {
   state?: FsmState;
   event?: string;
-  nextEvent?: string;
+  nextEvents: string[] = [];
   running: boolean = false;
   mask: number = STATUS_LEAF;
   status: number = 0;
@@ -56,6 +83,7 @@ export class FsmProcess extends FsmBaseClass {
     bindMethods(this, "dispatch", "dump", "restore");
   }
 
+  /** Force-exit the whole stack (root last), running each state's `onExit`; ends the machine. */
   async shutdown(event?: string) {
     while (this.state) {
       this.event = event;
@@ -65,36 +93,49 @@ export class FsmProcess extends FsmBaseClass {
     }
   }
 
+  /**
+   * 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 appended to the `nextEvents` FIFO queue and applied
+   * — in order, none dropped — when the current run settles; runs never nest. Returns
+   * `false` once the machine has finished, `true` otherwise.
+   */
   async dispatch(event: string): Promise<boolean> {
-    this.nextEvent = event;
+    // Queue the event. Re-entrant dispatches (from handlers running mid-settle)
+    // append here and are drained in order — so no earlier event is overwritten.
+    this.nextEvents.push(event);
     if (!this.running && !(this.status & STATUS_FINISHED)) {
       this.running = true;
       try {
-        this.event = this.nextEvent;
-        this.nextEvent = undefined;
-        while (true) {
-          // ---
-          if (this.status & STATUS_EXIT) {
-            await this.state?._runHandler("onExit", this.state);
+        while (this.nextEvents.length > 0) {
+          this.event = this.nextEvents.shift();
+          while (true) {
+            // ---
+            if (this.status & STATUS_EXIT) {
+              await this.state?._runHandler("onExit", this.state);
+            }
+            if (!(await this._update())) break;
+            if (this.status & STATUS_ENTER) {
+              await this.state?._runHandler("onEnter", this.state);
+            }
+            if (this.status & this.mask) break;
+            // ---
           }
-          if (!(await this._update())) break;
-          if (this.status & STATUS_ENTER) {
-            await this.state?._runHandler("onEnter", this.state);
-          }
-          if (this.status & this.mask) break;
-          // ---
+          if (this.status & STATUS_FINISHED) break;
         }
       } finally {
         this.running = false;
       }
-      const nextEvent = this.nextEvent;
-      if (nextEvent !== undefined) {
-        return Promise.resolve().then(() => this.dispatch(nextEvent));
-      }
     }
     return !(this.status & STATUS_FINISHED);
   }
 
+  /**
+   * 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: unknown[]): Promise<FsmProcessDump> {
     const dumpState = async (state: FsmState) => {
       const stateDump: FsmStateDump = {
@@ -121,6 +162,11 @@ export class FsmProcess extends FsmBaseClass {
     return dump;
   }
 
+  /**
+   * 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: FsmProcessDump, ...args: unknown[]) {
     this.status = dump.status || 0;
     this.event = dump.event;
@@ -140,6 +186,7 @@ export class FsmProcess extends FsmBaseClass {
     return this;
   }
 
+  /** Primary extension point: fires once for every state the machine creates. */
   onStateCreate(handler: FsmStateHandler) {
     return this._addHandler("onStateCreate", handler, true);
   }
@@ -191,6 +238,14 @@ export class FsmProcess extends FsmBaseClass {
     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 & STATUS_FINISHED) return false;
     const nextState =

package/src/core/fsm-state-config.ts

@@ -1,11 +1,38 @@
+// Sentinel keys used inside `FsmStateConfig.transitions` tuples. The raw `""` and
+// `"*"` literals are ambiguous at the call site — `["", "start", "Active"]` does not
+// visibly say "from the *initial* state" — so these named constants document intent
+// while keeping the runtime value (a shared empty string / asterisk) identical, which
+// keeps configs plain-serializable.
+
+/** Wildcard `from`-state: a transition that applies in *any* state. */
 export const STATE_ANY = "*";
+/** Empty `from`-state: the *initial* pseudo-state a parent enters into. */
 export const STATE_INITIAL = "";
+/** Empty `to`-state: the *final* pseudo-state; entering it exits the parent. */
 export const STATE_FINAL = "";
+/** Wildcard `event`: a transition triggered by *any* event. */
 export const EVENT_ANY = "*";
+/** Empty event: the eventless/automatic transition (fires with no named event). */
 export const EVENT_EMPTY = "";
 
 export type FsmStateKey = string;
 export type FsmEventKey = string;
+
+/**
+ * Declarative definition of a (possibly nested) state machine.
+ *
+ * One plain-object shape describes an entire HFSM, so machines stay serializable,
+ * diffable, and inspectable by tooling — the config is data, not code. A config has:
+ * - `key` — the state's name (unique among its siblings);
+ * - `transitions` — `[from, event, to]` tuples, where `from`/`to` name sibling
+ *   states, `""` is the initial (`from`) or final (`to`) pseudo-state, and `"*"` is a
+ *   wildcard (see the constants above);
+ * - `states` — nested child configs; entering this state descends into its initial
+ *   child. The index signature lets consumers attach arbitrary metadata.
+ *
+ * Pass a config to `new FsmProcess(config)` or `startProcess(ctx, config, …)`; it is
+ * compiled once into an `FsmStateDescriptor` for fast lookup at runtime.
+ */
 export type FsmStateConfig = {
   key: FsmStateKey;
   transitions?: [from: FsmStateKey, event: FsmEventKey, to: FsmStateKey][];

package/src/core/fsm-state-descriptor.ts

@@ -5,10 +5,24 @@ import {
   STATE_FINAL,
 } from "./fsm-state-config.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.
+ */
 export class FsmStateDescriptor {
   transitions: Record<string, Record<string, string>> = {};
   states: Record<string, FsmStateDescriptor> = {};
 
+  /**
+   * Recursively compile a config (and its nested `states`) into descriptors,
+   * turning the tuple list into the indexed `transitions` map.
+   */
   static build(config: FsmStateConfig) {
     const descriptor = new FsmStateDescriptor();
     for (const [from, event, to] of config.transitions || []) {
@@ -27,6 +41,13 @@ export class FsmStateDescriptor {
     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: string, eventKey: string) {
     const pairs = [
       [stateKey, eventKey],

package/src/core/fsm-state.ts

@@ -2,25 +2,41 @@ import { bindMethods, FsmBaseClass } from "./fsm-base-class.ts";
 import type { FsmProcess } from "./fsm-process.ts";
 import type { FsmStateDescriptor } from "./fsm-state-descriptor.ts";
 
+/** Serialized form of a single state: its `key` plus the `data` bag its `dump` hooks filled. */
 export type FsmStateDump = Record<string, unknown> & {
   key: string;
   data: Record<string, unknown>;
 };
+/** An `onEnter` / `onExit` callback; receives the state it fired on. */
 export type FsmStateHandler = (
   state: FsmState,
   ...args: unknown[]
 ) => void | Promise<void>;
 
+/** A `dump` / `restore` callback; reads or fills the mutable per-state `data` bag. */
 export type FsmStateDumpHandler = (
   state: FsmState,
   dump: FsmStateDump,
 ) => void | Promise<void>;
 
+/** An `onStateError` callback; receives the error thrown by another handler on this state. */
 export type FsmStateErrorHandler = (
   state: FsmState,
   error: unknown,
 ) => void | Promise<void>;
 
+/**
+ * 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.
+ */
 export class FsmState extends FsmBaseClass {
   process: FsmProcess;
   key: string;
@@ -41,24 +57,38 @@ export class FsmState extends FsmBaseClass {
     bindMethods(this, "onEnter", "onExit", "dump", "restore", "onStateError");
   }
 
+  /** Run when this state is entered. */
   onEnter(handler: FsmStateHandler) {
     return this._addHandler("onEnter", handler, true);
   }
+  /** Run when this state exits — registered inner-first so unwinding is inner-to-outer. */
   onExit(handler: FsmStateHandler) {
     return this._addHandler("onExit", handler, false);
   }
+  /** Handle an error thrown by another handler on this state (also bubbles to the process). */
   onStateError(handler: FsmStateErrorHandler) {
     return this._addHandler("onStateError", handler);
   }
+  /** Contribute to this state's snapshot: fill `dump.data` when the process is dumped. */
   dump(handler: FsmStateDumpHandler) {
     return this._addHandler("dump", handler, true);
   }
+  /** Rehydrate from this state's snapshot: read `dump.data` when the process is restored. */
   restore(handler: FsmStateDumpHandler) {
     return this._addHandler("restore", handler, true);
   }
 
   async _handleError(error: Error | unknown) {
-    await this._runHandler("onStateError", this, error);
+    // Run the state's own error handlers directly — NOT via `_runHandler`, whose
+    // catch re-routes to `_handleError`, which would re-enter `onStateError`
+    // forever. A throw from an error handler terminates at `console.error`.
+    for (const handler of this.handlers.onStateError ?? []) {
+      try {
+        await handler(this, error);
+      } catch (e) {
+        console.error(e);
+      }
+    }
     await this.process._handleStateError(this, error);
   }
 }

package/src/core/fsm-transitions.ts

@@ -0,0 +1,75 @@
+import type { FsmProcess } from "./fsm-process.ts";
+import type { FsmState } from "./fsm-state.ts";
+import { EVENT_ANY } from "./fsm-state-config.ts";
+import type { FsmStateDescriptor } from "./fsm-state-descriptor.ts";
+
+// ---------------------------------------------------------------------------
+// Transition introspection — read-only queries over the state/transition graph
+// ---------------------------------------------------------------------------
+
+/**
+ * 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).
+ */
+export function getStateTransitions(
+  state?: FsmState,
+): [from: string, event: string, to: string][] {
+  const result: [from: string, event: string, to: string][] = [];
+  const index: Record<string, boolean> = {};
+  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: FsmStateDescriptor,
+  prevStateKey: string,
+  index: Record<string, boolean>,
+): [from: string, event: string, to: string][] {
+  const result: [from: string, event: string, to: string][] = [];
+  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;
+        // Mark the event seen regardless of target — an inner exit-to-final
+        // (`to === ""`, a falsy target) must still mask an outer rule for the
+        // same event, matching what `dispatch` actually resolves.
+        index[event] = true;
+        result.push([prevStateKey, event, target]);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * 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)`.
+ */
+export function isStateTransitionEnabled(
+  process: FsmProcess,
+  event: string,
+): boolean {
+  const transitions = getStateTransitions(process.state);
+  for (const [, ev] of transitions) {
+    // A wildcard-event rule (`ev === EVENT_ANY`) matches any concrete event, just
+    // as the engine's `getTargetStateKey` falls back to `(state, *)` / `(*, *)`.
+    if (ev === event || ev === EVENT_ANY) return true;
+  }
+  return false;
+}

package/src/core/index.ts

@@ -3,3 +3,4 @@ export * from "./fsm-process.ts";
 export * from "./fsm-state.ts";
 export * from "./fsm-state-config.ts";
 export * from "./fsm-state-descriptor.ts";
+export * from "./fsm-transitions.ts";

package/src/index.ts

@@ -1,3 +1,3 @@
 export * from "./core/index.ts";
-export * from "./orchestrator/index.ts";
-export * from "./utils/index.ts";
+export * from "./start-process.ts";
+export * from "./trace/index.ts";