@statewalker/fsm 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/fsm",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "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,6 +53,19 @@ 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;
@@ -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,6 +93,15 @@ 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 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: string): Promise<boolean> {
     this.nextEvent = event;
     if (!this.running && !(this.status & STATUS_FINISHED)) {
@@ -95,6 +132,10 @@ export class FsmProcess extends FsmBaseClass {
     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,18 +57,23 @@ 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);
   }

package/src/core/fsm-transitions.ts

@@ -0,0 +1,72 @@
+import type { FsmProcess } from "./fsm-process.ts";
+import type { FsmState } from "./fsm-state.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) {
+    if (ev === event) 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";

package/src/{orchestrator/start-process.ts → start-process.ts}

@@ -1,74 +1,49 @@
-import { FsmProcess, type FsmProcessDump } from "../core/fsm-process.ts";
-import type { FsmState } from "../core/fsm-state.ts";
-import type { FsmStateConfig } from "../core/fsm-state-config.ts";
-import type { FsmStateDescriptor } from "../core/fsm-state-descriptor.ts";
-import type { StageHandler } from "./handler-registry.ts";
-
+import { FsmProcess, type FsmProcessDump } from "./core/fsm-process.ts";
+import type { FsmState } from "./core/fsm-state.ts";
+import type { FsmStateConfig } from "./core/fsm-state-config.ts";
+import { isStateTransitionEnabled } from "./core/fsm-transitions.ts";
+
+/**
+ * Per-state behaviour contract used by `startProcess`. One function shape expresses
+ * what to do while in a state, and its *return value* wires up the rest, so a state's
+ * setup and teardown live together. The handler runs on entry with the shared
+ * `context` and may return:
+ * - nothing — no teardown;
+ * - a cleanup `function` — registered as this state's `onExit`;
+ * - an async/sync generator — run concurrently, each yielded string dispatched back
+ *   into the machine (self-driving/reactive states), auto-`return()`ed on exit.
+ */
+export type StageHandler<C = Record<string, unknown>> = (
+  context: C,
+) =>
+  | void
+  | (() => void | Promise<void>)
+  | Promise<void | (() => void | Promise<void>)>
+  | AsyncGenerator<string, void, unknown>
+  | Generator<string, void, unknown>;
+
+/**
+ * The caller's remote control returned by `startProcess`: stop the machine and
+ * snapshot/rehydrate it without holding a reference to the underlying `FsmProcess`.
+ */
 export interface ProcessHandle {
   shutdown(): Promise<void>;
   dump(...args: unknown[]): Promise<FsmProcessDump>;
   restore(dump: FsmProcessDump, ...args: unknown[]): Promise<void>;
 }
 
-// Context keys for binding FSM functions into the shared context object.
+// Context keys under which `startProcess` binds the machine into the shared context
+// object. Why via context (not closures): handlers reach the running machine
+// uniformly — `(ctx[KEY_DISPATCH])(event)` — regardless of where they are defined.
+/** Context key: `(event) => Promise<void>` that dispatches an event (guarded). */
 export const KEY_DISPATCH = "fsm:dispatch";
+/** Context key: `() => Promise<void>` that shuts the machine down. */
 export const KEY_TERMINATE = "fsm:terminate";
+/** Context key: the current state-key stack (root→leaf), refreshed on every transition. */
 export const KEY_STATES = "fsm:states";
+/** Context key: the last dispatched event. */
 export const KEY_EVENT = "fsm:event";
 
-// ---------------------------------------------------------------------------
-// Transition introspection
-// ---------------------------------------------------------------------------
-
-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;
-        if (target) index[event] = true;
-        result.push([prevStateKey, event, target]);
-      }
-    }
-  }
-  return result;
-}
-
-export function isStateTransitionEnabled(
-  process: FsmProcess,
-  event: string,
-): boolean {
-  const transitions = getStateTransitions(process.state);
-  for (const [, ev] of transitions) {
-    if (ev === event) return true;
-  }
-  return false;
-}
-
 // ---------------------------------------------------------------------------
 // Generator detection
 // ---------------------------------------------------------------------------
@@ -90,6 +65,24 @@ function isGenerator(
 // startProcess (also exported as startFsmProcess for backward compat)
 // ---------------------------------------------------------------------------
 
+/**
+ * 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)
+ */
 export async function startProcess<C = unknown>(
   context: C,
   config: FsmStateConfig,
@@ -126,8 +119,12 @@ export async function startProcess<C = unknown>(
                 await dispatch(event);
                 if (stateExited || terminated) break;
               }
-            } catch {
-              // Swallow generator errors after return()
+            } catch (error) {
+              // A generator `return()` during state exit / termination throws an
+              // abort we intentionally swallow; a genuine error thrown by the
+              // generator body must surface through the state's error handling
+              // rather than vanish.
+              if (!stateExited && !terminated) await state._handleError(error);
             }
           })();
         } else if (typeof result === "function") {
@@ -184,5 +181,5 @@ export async function startProcess<C = unknown>(
   };
 }
 
-/** @deprecated Use `startProcess` instead */
+/** Permanent equal alias of {@link startProcess} — the name existing consumers import. */
 export const startFsmProcess = startProcess;

package/src/{utils → trace}/printer.ts

@@ -1,5 +1,13 @@
 import type { FsmProcess } from "../core/fsm-process.ts";
+
+/** A sink for trace output — anything shaped like `console.log`. */
 export type Printer = (...args: unknown[]) => void;
+/**
+ * Tuning for a `Printer`.
+ * - `prefix` — string prepended to every line (e.g. a process tag).
+ * - `print` — the underlying sink (defaults to `console.log`).
+ * - `lineNumbers` — prepend an incrementing `[n]` counter.
+ */
 export type PrinterConfig = {
   prefix?: string;
   print?: (...args: unknown[]) => void;
@@ -8,6 +16,11 @@ export type PrinterConfig = {
 
 const printerStore = new WeakMap<object, Printer>();
 
+/**
+ * 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.
+ */
 export function preparePrinter(
   process: FsmProcess,
   { prefix = "", print = console.log, lineNumbers = false }: PrinterConfig,
@@ -25,6 +38,11 @@ export function preparePrinter(
   return 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.
+ */
 export function setProcessPrinter(
   process: FsmProcess,
   config: PrinterConfig = {},
@@ -33,10 +51,12 @@ export function setProcessPrinter(
   printerStore.set(process, printer);
 }
 
+/** The printer attached to `process`, or `console.log` if none was set. */
 export function getProcessPrinter(process: FsmProcess): Printer {
   return printerStore.get(process) || console.log;
 }
 
+/** The printer for a state — its own if set, else its process's (see {@link getProcessPrinter}). */
 export function getPrinter(state: { process: FsmProcess }): Printer {
   return printerStore.get(state) || getProcessPrinter(state.process);
 }