@statewalker/fsm 0.36.0 → 0.38.0

package/dist/index.d.ts

@@ -1,335 +1,353 @@
+//#region src/core/fsm-base-class.d.ts
 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.
+ */
 declare class FsmBaseClass {
-    handlers: Record<string, Handler[]>;
-    data: Record<string, unknown>;
-    constructor();
-    setData<T>(key: string, value: T): this;
-    getData<T>(key: string): T | undefined;
-    protected _addHandler<T>(type: string, handler: T, direct?: boolean): () => void;
-    protected _removeHandler<T>(type: string, handler: T): void;
-    _runHandlerParallel(type: string, ...args: unknown[]): Promise<void>;
-    _runHandler(type: string, ...args: unknown[]): Promise<void>;
-    _handleError(error: Error | unknown): Promise<void>;
+  handlers: Record<string, Handler[]>;
+  /**
+   * 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): () => void;
+  protected _removeHandler<T>(type: string, handler: T): void;
+  /** Run every handler of `type` in order, awaiting each; route throws to `_handleError`. */
+  _runHandler(type: string, ...args: unknown[]): Promise<void>;
+  /** Default error sink — logs. `FsmState`/`FsmProcess` override it to fire `onStateError`. */
+  _handleError(error: Error | unknown): Promise<void>;
 }
-
+/**
+ * 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`.
+ */
+declare function bindMethods<T>(obj: T, ...methods: (string | symbol)[]): T;
+//#endregion
+//#region src/core/fsm-state-config.d.ts
+/** Wildcard `from`-state: a transition that applies in *any* state. */
 declare const STATE_ANY = "*";
+/** Empty `from`-state: the *initial* pseudo-state a parent enters into. */
 declare const STATE_INITIAL = "";
+/** Empty `to`-state: the *final* pseudo-state; entering it exits the parent. */
 declare const STATE_FINAL = "";
+/** Wildcard `event`: a transition triggered by *any* event. */
 declare const EVENT_ANY = "*";
+/** Empty event: the eventless/automatic transition (fires with no named event). */
 declare const EVENT_EMPTY = "";
 type FsmStateKey = string;
 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.
+ */
 type FsmStateConfig = {
-    key: FsmStateKey;
-    transitions?: [from: FsmStateKey, event: FsmEventKey, to: FsmStateKey][];
-    states?: FsmStateConfig[];
+  key: FsmStateKey;
+  transitions?: [from: FsmStateKey, event: FsmEventKey, to: FsmStateKey][];
+  states?: FsmStateConfig[];
 } & Record<string, unknown>;
-
+//#endregion
+//#region src/core/fsm-state-descriptor.d.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.
+ */
 declare class FsmStateDescriptor {
-    transitions: Record<string, Record<string, string>>;
-    states: Record<string, FsmStateDescriptor>;
-    static build(config: FsmStateConfig): FsmStateDescriptor;
-    getTargetStateKey(stateKey: string, eventKey: string): string;
+  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): FsmStateDescriptor;
+  /**
+   * 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): string;
 }
-
+//#endregion
+//#region src/core/fsm-state.d.ts
+/** Serialized form of a single state: its `key` plus the `data` bag its `dump` hooks filled. */
 type FsmStateDump = Record<string, unknown> & {
-    key: string;
-    data: Record<string, unknown>;
+  key: string;
+  data: Record<string, unknown>;
 };
+/** An `onEnter` / `onExit` callback; receives the state it fired on. */
 type FsmStateHandler = (state: FsmState, ...args: unknown[]) => void | Promise<void>;
+/** A `dump` / `restore` callback; reads or fills the mutable per-state `data` bag. */
 type FsmStateDumpHandler = (state: FsmState, dump: FsmStateDump) => void | Promise<void>;
+/** An `onStateError` callback; receives the error thrown by another handler on this state. */
 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.
+ */
 declare class FsmState extends FsmBaseClass {
-    process: FsmProcess;
-    key: string;
-    parent?: FsmState;
-    descriptor?: FsmStateDescriptor;
-    constructor(process: FsmProcess, parent: FsmState | undefined, key: string, descriptor?: FsmStateDescriptor);
-    onEnter(handler: FsmStateHandler): () => void;
-    onExit(handler: FsmStateHandler): () => void;
-    onStateError(handler: FsmStateErrorHandler): () => void;
-    dump(handler: FsmStateDumpHandler): () => void;
-    restore(handler: FsmStateDumpHandler): () => void;
-    getData<T>(key: string, recursive?: boolean): T | undefined;
-    useData<T>(key: string): (((recursive?: boolean) => T | undefined) | ((value: T) => this))[];
-    _handleError(error: Error | unknown): Promise<void>;
+  process: FsmProcess;
+  key: string;
+  parent?: FsmState;
+  descriptor?: FsmStateDescriptor;
+  constructor(process: FsmProcess, parent: FsmState | undefined, key: string, descriptor?: FsmStateDescriptor);
+  /** Run when this state is entered. */
+  onEnter(handler: FsmStateHandler): () => void;
+  /** Run when this state exits — registered inner-first so unwinding is inner-to-outer. */
+  onExit(handler: FsmStateHandler): () => void;
+  /** Handle an error thrown by another handler on this state (also bubbles to the process). */
+  onStateError(handler: FsmStateErrorHandler): () => void;
+  /** Contribute to this state's snapshot: fill `dump.data` when the process is dumped. */
+  dump(handler: FsmStateDumpHandler): () => void;
+  /** Rehydrate from this state's snapshot: read `dump.data` when the process is restored. */
+  restore(handler: FsmStateDumpHandler): () => void;
+  _handleError(error: Error | unknown): Promise<void>;
 }
-
+//#endregion
+//#region src/core/fsm-process.d.ts
+/** Not started / no current transition. */
 declare const STATUS_NONE = 0;
+/** Entering: descended into a parent's first (initial) child. */
 declare const STATUS_FIRST = 1;
+/** Entering: advanced to a resolved target (sibling) state. */
 declare const STATUS_NEXT = 2;
+/** Rested on a leaf — dispatch returns control here (the default `mask`). */
 declare const STATUS_LEAF = 4;
+/** Exiting: popped back up to the parent state. */
 declare const STATUS_LAST = 8;
+/** Terminated: the machine has exited its root and cannot advance further. */
 declare const STATUS_FINISHED = 16;
+/** Composite: any "entering" phase. */
 declare const STATUS_ENTER: number;
+/** Composite: any "exiting" phase. */
 declare const STATUS_EXIT: number;
+/** A process-level handler (`onStateCreate` / `onStateError`). */
 type FsmProcessHandler = (process: FsmProcess, ...args: unknown[]) => void | Promise<void>;
+/** Serialized form of the whole machine: status, last event, and the root→leaf state stack. */
 type FsmProcessDump = Record<string, unknown> & {
-    status: number;
-    event?: string;
-    stack: FsmStateDump[];
+  status: number;
+  event?: string;
+  stack: FsmStateDump[];
 };
 type FsmProcessDumpHandler = (process: FsmProcess, dump: FsmProcessDump) => void | Promise<void>;
-declare class FsmProcess extends FsmBaseClass {
-    state?: FsmState;
-    event?: string;
-    nextEvent?: string;
-    running: boolean;
-    mask: number;
-    status: number;
-    config: FsmStateConfig;
-    rootDescriptor: FsmStateDescriptor;
-    constructor(config: FsmStateConfig);
-    shutdown(event?: string): Promise<void>;
-    dispatch(event: string): Promise<boolean>;
-    dump(...args: unknown[]): Promise<FsmProcessDump>;
-    restore(dump: FsmProcessDump, ...args: unknown[]): Promise<this>;
-    onStateCreate(handler: FsmStateHandler): () => void;
-    onStateError(handler: (state: FsmState, error: unknown) => void | Promise<void>): () => void;
-    _handleStateError(state: FsmState, error: Error | unknown): Promise<void>;
-    _newState(parent: FsmState | undefined, key: string, descriptor: FsmStateDescriptor | undefined): FsmState;
-    _getSubstate(parent: FsmState | undefined, prevStateKey: string | undefined): FsmState | undefined;
-    _newSubstate(parent: FsmState | undefined, toState: string): FsmState;
-    _update(): boolean;
-}
-
-type Module<C = unknown> = (context: C) => void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)> | Generator<string> | AsyncGenerator<string>;
-declare function newFsmProcess<C>(context: C, config: FsmStateConfig, load: (state: string, event: undefined | string) => undefined | Module<C> | Module<C>[] | Promise<undefined | Module<C> | Module<C>[]>): [
-    dispatch: (event: string) => Promise<boolean>,
-    shutdown: () => Promise<void>
-];
-
-/**
- * Key used to bind the dispatch function to the process context.
- * The dispatch function allows triggering state transitions by dispatching events.
- *
- * Example usage:
- * ```typescript
- * const context: Record<string, unknown> = {};
- * // Initialize the FSM process using `startFsmProcess`
- * const dispatch = context["fsm:dispatch"] as (event: string) => Promise<void>;
- * await dispatch("someEvent");
- */
-declare const KEY_DISPATCH: "fsm:dispatch";
-/**
- * Key used to bind the terminate function to the process context.
- * The terminate function is used to gracefully shut down the FSM process.
- * It returns a Promise that resolves when the process has been fully terminated.
- * Example usage:
- * ```typescript
- * const context: Record<string, unknown> = {};
- * // Initialize the FSM process using `startFsmProcess`
- * const terminate = context["fsm:terminate"] as () => Promise<void>;
- * await terminate();
- * ```
- */
-declare const KEY_TERMINATE: "fsm:terminate";
 /**
- * Key used to bind the current stack of active states to the process context.
- * This provides a snapshot of the states the FSM process has entered.
- * It is represented as an array of strings -- state keys.
+ * The running state machine — owner of the active-state stack and the traversal.
  *
- * Example usage:
- * ```typescript
- * const context: Record<string, unknown> = {};
- * // Initialize the FSM process using `startFsmProcess`
- * const states = context["fsm:states"] as string[];
- * console.log("Current active states:", states);
- * ```
+ * 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.
  */
-declare const KEY_STATES: "fsm:states";
+declare class FsmProcess extends FsmBaseClass {
+  state?: FsmState;
+  event?: string;
+  nextEvent?: string;
+  running: boolean;
+  mask: number;
+  status: number;
+  config: FsmStateConfig;
+  rootDescriptor: FsmStateDescriptor;
+  constructor(config: FsmStateConfig);
+  /** Force-exit the whole stack (root last), running each state's `onExit`; ends the machine. */
+  shutdown(event?: string): Promise<void>;
+  /**
+   * 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.
+   */
+  dispatch(event: string): Promise<boolean>;
+  /**
+   * Snapshot the machine to a plain object: `{ status, event, stack }` where the
+   * stack is root→leaf, each entry carrying whatever its `dump` hooks recorded.
+   */
+  dump(...args: unknown[]): Promise<FsmProcessDump>;
+  /**
+   * 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.
+   */
+  restore(dump: FsmProcessDump, ...args: unknown[]): Promise<this>;
+  /** Primary extension point: fires once for every state the machine creates. */
+  onStateCreate(handler: FsmStateHandler): () => void;
+  onStateError(handler: (state: FsmState, error: unknown) => void | Promise<void>): () => void;
+  _handleStateError(state: FsmState, error: Error | unknown): Promise<void>;
+  _newState(parent: FsmState | undefined, key: string, descriptor: FsmStateDescriptor | undefined): Promise<FsmState>;
+  _getSubstate(parent: FsmState | undefined, prevStateKey: string | undefined): Promise<FsmState | undefined>;
+  _newSubstate(parent: FsmState | undefined, toState: string): Promise<FsmState>;
+  /**
+   * 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.
+   */
+  _update(): Promise<boolean>;
+}
+//#endregion
+//#region src/core/fsm-transitions.d.ts
 /**
- * Key used to bind the current event being processed to the process context.
- * This represents the event that triggered the current state transition.
- * It is represented as a string.
- * Example usage:
- * ```typescript
- * const context: Record<string, unknown> = {};
- * // Initialize the FSM process using `startFsmProcess`
- * const event = context["fsm:event"] as string;
- * console.log("Current event:", event);
- * ```
+ * 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).
  */
-declare const KEY_EVENT: "fsm:event";
+declare function getStateTransitions(state?: FsmState): [from: string, event: string, to: string][];
 /**
- * Key used to register a new FSM process configuration in the process context.
- * This key is associated with a function that allows adding new FSM configurations.
- * The function takes a process name and its configuration, and returns a cleanup function
- * to remove the registered configuration.
- * Example usage:
- * ```typescript
- * const context: Record<string, unknown> = {};
- * initProcessManager(context); // Initialize the process manager in the context
- * ...
- * type StateConfig = { key: string; transitions?: string[][]; states?: StateConfig[] };
- * const registerConfig = context["fsm:sys:registerConfig"] as (name: string, config: StateConfig) => () => void;
- * const unregister = registerConfig("myProcess", { key: "Main", transitions: [...] });
- * // To unregister the configuration later
- * unregister();
- * ```
+ * 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)`.
  */
-declare const KEY_REGISTER_CONFIG: "fsm:sys:registerConfig";
+declare function isStateTransitionEnabled(process: FsmProcess, event: string): boolean;
+//#endregion
+//#region src/start-process.d.ts
 /**
- * Key used to register state and event handlers for FSM processes in the process context.
- * This key is associated with a function that allows adding handler modules for a specific process.
- * The function takes a process name and a variable number of handler modules, returning a cleanup function
- * to remove the registered handlers.
- * Example usage:
- * ```typescript
- * const context: Record<string, unknown> = {};
- * initProcessManager(context); // Initialize the process manager in the context
- * ...
- * const registerHandlers = context["fsm:sys:registerHandlers"] as (name: string, ...modules: unknown[]) => () => void;
- * const handlerModule1 = {
- *   Main: async (context) => { ... },
- *   SomeState: async (context) => { ... },
- * }
- * // Views layer can be defined in the same or separate modules
- * const handlerModule3 = {
- *  MainView: async (context) => { ... },
- *  SomeStateView: async (context) => { ... },
- * }
- * // A common handler function to call for all states
- * const handlerModule2 = (context) => { ... };
- * const unregister = registerHandlers(
- *  "myProcess",
- *  handlerModule1,
- *  handlerModule2,
- *  handlerModule3
- * );
- * // To unregister the handlers later
- * unregister();
- * ```
+ * 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.
  */
-declare const KEY_REGISTER_HANDLERS: "fsm:sys:registerHandlers";
+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>;
 /**
- * Key used to launch an FSM process in the process context.
- * This key is associated with a function that initiates the FSM process based on its name and context.
- * The function takes the process name and context, returning either nothing, a cleanup function,
- * or a Promise that resolves to either nothing or a cleanup function.
- * Example usage:
- * ```typescript
- * const context: Record<string, unknown> = {};
- * initProcessManager(context); // Initialize the process manager in the context
- * // Register process configurations and handlers as needed
- *
- * const launchProcess = context["fsm:sys:launch"] as (name: string, context: Record<string, unknown>) => () => Promise<void>;
- * const terminate = await launchProcess("myProcess", context);
- * // To terminate the process later
- * terminate?.();
- * ```
+ * The caller's remote control returned by `startProcess`: stop the machine and
+ * snapshot/rehydrate it without holding a reference to the underlying `FsmProcess`.
  */
-declare const KEY_LAUNCH_PROCESS: "fsm:sys:launch";
-
-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>;
-declare function toStageHandlers<C>(value: unknown, accept: (key: string, value: unknown) => boolean): StageHandler<C>[];
-
-type ProcessConfig = {
-    name: string;
-    config?: FsmStateConfig;
-} & ({
-    handler?: StageHandler;
-} | {
-    handlers?: StageHandler | (StageHandler | {
-        [state: string]: StageHandler | StageHandler[];
-    })[];
-} | {
-    default?: StageHandler | (StageHandler | {
-        [state: string]: StageHandler | StageHandler[];
-    })[];
-});
-declare function launcher(options: unknown): Promise<() => Promise<void>>;
-
-interface IProcessConfigManager {
-    getProcessConfig(processName: string): FsmStateConfig;
-    getHandlersLoader<C = unknown>(processName: string): (state: string, event: undefined | string) => StageHandler<C>[];
-    registerConfig(name: string, config: FsmStateConfig): () => void;
-    registerHandlers(name: string, ...modules: unknown[]): () => void;
-}
-declare class ProcessConfigManager implements IProcessConfigManager {
-    protected configs: Record<string, FsmStateConfig>;
-    protected handlers: Record<string, unknown[]>;
-    getProcessConfig(processName: string): FsmStateConfig;
-    getHandlersLoader<C = unknown>(processName: string): (state: string, event: undefined | string) => StageHandler<C>[];
-    registerConfig(name: string, config: FsmStateConfig): () => void;
-    registerHandlers(name: string, ...modules: unknown[]): () => void;
+interface ProcessHandle {
+  shutdown(): Promise<void>;
+  dump(...args: unknown[]): Promise<FsmProcessDump>;
+  restore(dump: FsmProcessDump, ...args: unknown[]): Promise<void>;
 }
-
+/** Context key: `(event) => Promise<void>` that dispatches an event (guarded). */
+declare const KEY_DISPATCH = "fsm:dispatch";
+/** Context key: `() => Promise<void>` that shuts the machine down. */
+declare const KEY_TERMINATE = "fsm:terminate";
+/** Context key: the current state-key stack (root→leaf), refreshed on every transition. */
+declare const KEY_STATES = "fsm:states";
+/** Context key: the last dispatched event. */
+declare const KEY_EVENT = "fsm:event";
 /**
- * Resolve module paths relative to a base URL.
- * This is useful for converting relative paths to absolute URLs.
+ * 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 baseUrl - The base URL to resolve against.
- * @param refs - An array of module references (relative or absolute).
- * @returns An array of resolved absolute module URLs as strings.
- * @example
- * ```ts
- * const urls = resolveModulesUrls(
- *  'file:///home/user/project/', // base URL
- *  'https://example.com/js/my-module.js', // absolute URL
- *  './module1.js', // relative path
- *  '../module2.js' // relative path
- * );
- * console.log(urls);
- * // Output: [
- * //  'https://example.com/js/my-module.js',
- * //  'file:///home/user/project/module1.js',
- * //  'file:///home/user/module2.js'
- * // ] *
- * ```
+ * @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)
  */
-declare function resolveModulesUrls(baseUrl: URL | string, ...refs: (URL | string)[]): string[];
+declare function startProcess<C = unknown>(context: C, config: FsmStateConfig, load: (state: string, event: string | undefined) => StageHandler<C>[] | Promise<StageHandler<C>[]>, startEvent?: string): Promise<ProcessHandle>;
+/** Permanent equal alias of {@link startProcess} — the name existing consumers import. */
+declare const startFsmProcess: typeof startProcess;
+//#endregion
+//#region src/trace/printer.d.ts
+/** A sink for trace output — anything shaped like `console.log`. */
+type Printer = (...args: unknown[]) => void;
 /**
- * Resolves module paths relative to a base URL.
- * This is useful for converting relative paths to absolute file system paths.
- * @param baseUrl - The base URL to resolve against
- * @param refs - An array of module references (relative or absolute)
- * @returns - An array of resolved absolute module paths as strings
- * @example
- * ```ts
- * const paths = resolveModulesPaths('file:///home/user/project/', './module1.js', '../module2.js');
- * console.log(paths);
- * // Output: [
- * //   '/home/user/project/module1.js',
- * //   '/home/user/module2.js'
- * // ]
- * ```
+ * 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.
  */
-declare function resolveModulesPaths(baseUrl: URL | string, ...refs: (URL | string)[]): string[];
-
-declare function startNodeProcesses(modules?: string[]): Promise<void>;
-
-declare function startFsmProcess<C = unknown>(context: C, config: FsmStateConfig, load: (state: string, event: undefined | string) => StageHandler<C>[] | Promise<StageHandler<C>[]>, startEvent?: string): Promise<() => Promise<void>>;
-
-declare function startProcesses({ onExit, modules, init, }: {
-    onExit?: () => Promise<void> | void;
-    modules: unknown[];
-    init?: (context: Record<string, unknown>) => Promise<Record<string, unknown>> | Record<string, unknown>;
-}): Promise<() => Promise<void>>;
-
-type Printer = (...args: unknown[]) => void;
 type PrinterConfig = {
-    prefix?: string;
-    print?: (...args: unknown[]) => void;
-    lineNumbers?: boolean;
+  prefix?: string;
+  print?: (...args: unknown[]) => void;
+  lineNumbers?: boolean;
 };
-declare const KEY_PRINTER = "printer";
-declare function preparePrinter(process: FsmProcess, { prefix, print, lineNumbers }: PrinterConfig): Printer;
-declare function setPrinter(state: FsmState, config?: PrinterConfig): void;
+/**
+ * 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.
+ */
+declare function preparePrinter(process: FsmProcess, {
+  prefix,
+  print,
+  lineNumbers
+}: PrinterConfig): 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.
+ */
 declare function setProcessPrinter(process: FsmProcess, config?: PrinterConfig): void;
+/** The printer attached to `process`, or `console.log` if none was set. */
 declare function getProcessPrinter(process: FsmProcess): Printer;
-declare function getPrinter(state: FsmState): Printer;
-
-declare function newProcess(config: FsmStateConfig, { prefix, print, lineNumbers, }: {
-    prefix?: string;
-    print?: (...args: any[]) => void;
-    lineNumbers?: boolean;
-}): FsmProcess;
-
+/** The printer for a state — its own if set, else its process's (see {@link getProcessPrinter}). */
+declare function getPrinter(state: {
+  process: FsmProcess;
+}): Printer;
+//#endregion
+//#region src/trace/tracer.d.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.
+ */
 declare function setProcessTracer(process: FsmProcess, print?: Printer): () => void;
+/**
+ * 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.
+ */
 declare function setStateTracer(state: FsmState, print?: Printer): void;
-
-declare function isStateTransitionEnabled(process: FsmProcess, event: string): boolean;
-declare function getStateTransitions(state?: FsmState): [from: string, event: string, to: string][];
-
-export { EVENT_ANY, EVENT_EMPTY, type FsmEventKey, FsmProcess, type FsmProcessDump, type FsmProcessDumpHandler, type FsmProcessHandler, FsmState, type FsmStateConfig, FsmStateDescriptor, type FsmStateDump, type FsmStateDumpHandler, type FsmStateErrorHandler, type FsmStateHandler, type FsmStateKey, type IProcessConfigManager, KEY_DISPATCH, KEY_EVENT, KEY_LAUNCH_PROCESS, KEY_PRINTER, KEY_REGISTER_CONFIG, KEY_REGISTER_HANDLERS, KEY_STATES, KEY_TERMINATE, type Module, type Printer, type PrinterConfig, type ProcessConfig, ProcessConfigManager, STATE_ANY, STATE_FINAL, STATE_INITIAL, STATUS_ENTER, STATUS_EXIT, STATUS_FINISHED, STATUS_FIRST, STATUS_LAST, STATUS_LEAF, STATUS_NEXT, STATUS_NONE, type StageHandler, startNodeProcesses as default, getPrinter, getProcessPrinter, getStateTransitions, isStateTransitionEnabled, launcher, newFsmProcess, newProcess, preparePrinter, resolveModulesPaths, resolveModulesUrls, setPrinter, setProcessPrinter, setProcessTracer, setStateTracer, startFsmProcess, startNodeProcesses, startProcesses, toStageHandlers };
+//#endregion
+export { EVENT_ANY, EVENT_EMPTY, FsmBaseClass, FsmEventKey, FsmProcess, FsmProcessDump, FsmProcessDumpHandler, FsmProcessHandler, FsmState, FsmStateConfig, FsmStateDescriptor, FsmStateDump, FsmStateDumpHandler, FsmStateErrorHandler, FsmStateHandler, FsmStateKey, KEY_DISPATCH, KEY_EVENT, KEY_STATES, KEY_TERMINATE, Printer, PrinterConfig, ProcessHandle, STATE_ANY, STATE_FINAL, STATE_INITIAL, STATUS_ENTER, STATUS_EXIT, STATUS_FINISHED, STATUS_FIRST, STATUS_LAST, STATUS_LEAF, STATUS_NEXT, STATUS_NONE, StageHandler, bindMethods, getPrinter, getProcessPrinter, getStateTransitions, isStateTransitionEnabled, preparePrinter, setProcessPrinter, setProcessTracer, setStateTracer, startFsmProcess, startProcess };
+//# sourceMappingURL=index.d.ts.map