jssm 5.104.2 → 5.112.4

package/jssm.es5.d.cts

@@ -1,23 +1,87 @@
 import { circular_buffer } from 'circular_buffer_js';
 
-declare type StateType$1 = string; /** Composite type composing whether or not a result was successful */
+declare type StateType$1 = string;
+/**
+ *  A color value accepted by jssm-viz for state and arrow styling.  Currently
+ *  any string, validated downstream by Graphviz / the named-colors list.
+ *  Intended to be narrowed to `#RRGGBB` / `#RRGGBBAA` and CSS named colors
+ *  in a future release.
+ */
 declare type JssmColor = string;
+/**
+ *  Three-state policy flag: `'required'`, `'disallowed'`, or `'optional'`.
+ *  Used by machine configuration where a default-permissive middle ground
+ *  is meaningful (for example, the `actions` config key).
+ */
 declare type JssmPermittedOpt = 'required' | 'disallowed' | 'optional';
+/**
+ *  The set of ASCII arrow tokens recognized by the FSL grammar.  Each arrow
+ *  encodes a direction (one-way left/right, or two-way) and a "kind" for
+ *  each direction (`-` legal, `=` main path, `~` forced-only).  See the
+ *  Language Reference docs for the full semantic table.
+ */
 declare type JssmArrow = '->' | '<-' | '<->' | '<=->' | '<~->' | '=>' | '<=' | '<=>' | '<-=>' | '<~=>' | '~>' | '<~' | '<~>' | '<-~>' | '<=~>';
 /**
  * A type teaching Typescript the various supported shapes for nodes, mostly inherited from GraphViz
  */
 declare type JssmShape = "box" | "polygon" | "ellipse" | "oval" | "circle" | "point" | "egg" | "triangle" | "plaintext" | "plain" | "diamond" | "trapezium" | "parallelogram" | "house" | "pentagon" | "hexagon" | "septagon" | "octagon" | "doublecircle" | "doubleoctagon" | "tripleoctagon" | "invtriangle" | "invtrapezium" | "invhouse" | "Mdiamond" | "Msquare" | "Mcircle" | "rect" | "rectangle" | "square" | "star" | "none" | "underline" | "cylinder" | "note" | "tab" | "folder" | "box3d" | "component" | "promoter" | "cds" | "terminator" | "utr" | "primersite" | "restrictionsite" | "fivepoverhang" | "threepoverhang" | "noverhang" | "assembly" | "signature" | "insulator" | "ribosite" | "rnastab" | "proteasesite" | "proteinstab" | "rpromoter" | "rarrow" | "larrow" | "lpromoter" | "record";
+/**
+ *  Direction polarity of an arrow: pointing only `'left'`, only `'right'`,
+ *  or `'both'` (a bidirectional arrow).
+ */
 declare type JssmArrowDirection = 'left' | 'right' | 'both';
+/**
+ *  Semantic category of an arrow's transition.  `'legal'` is a normal
+ *  transition, `'main'` is part of the machine's primary path, `'forced'`
+ *  may only be taken via {@link Machine.force_transition}, and `'none'`
+ *  means no transition exists in that direction.
+ */
 declare type JssmArrowKind = 'none' | 'legal' | 'main' | 'forced';
+/**
+ *  Graphviz layout engine selector.  Controls how jssm-viz lays out the
+ *  rendered diagram; `'dot'` is the default and most useful for state
+ *  machines.  See the Graphviz documentation for the differences.
+ */
 declare type JssmLayout = 'dot' | 'circo' | 'twopi' | 'fdp' | 'neato';
 declare type JssmCorner = 'regular' | 'rounded' | 'lined';
 declare type JssmLineStyle = 'solid' | 'dashed' | 'dotted';
+/**
+ *  Tristate flag for whether a property may be overridden at runtime.
+ *  `true` permits overrides, `false` forbids them, and `undefined` defers
+ *  the decision to the surrounding configuration's default.
+ */
 declare type JssmAllowsOverride = true | false | undefined;
+/**
+ *  Runtime-iterable list of valid `flow` directions for FSL diagrams.
+ *  Use this when you need to enumerate directions; for the type itself
+ *  see {@link FslDirection}.
+ */
 declare const FslDirections: readonly ["up", "right", "down", "left"];
+/**
+ *  String literal type of the four supported FSL flow directions.  This is
+ *  the type of the `flow` config key on a machine.
+ */
 declare type FslDirection = typeof FslDirections[number];
+/**
+ *  Runtime-iterable list of the built-in theme names that ship with jssm-viz.
+ *  Use this when you need to enumerate themes; for the type itself see
+ *  {@link FslTheme}.
+ */
 declare const FslThemes: readonly ["default", "ocean", "modern", "plain", "bold"];
+/**
+ *  String literal type of the built-in theme names.  This is the element
+ *  type of the `theme` config key (which accepts an array so that themes
+ *  can be layered).
+ */
 declare type FslTheme = typeof FslThemes[number];
+/**
+ *  Persistable snapshot of a Machine produced by {@link Machine.serialize}
+ *  and consumed by {@link deserialize}.  Carries the current state, the
+ *  associated machine data, the recent history (subject to the configured
+ *  capacity), and metadata to detect version-skew on rehydration.
+ *
+ *  @typeParam DataType - The type of the user-supplied data payload (`mDT`).
+ */
 declare type JssmSerialization<DataType> = {
     jssm_version: string;
     timestamp: number;
@@ -27,6 +91,11 @@ declare type JssmSerialization<DataType> = {
     history_capacity: number;
     data: DataType;
 };
+/**
+ *  Declaration of a named property that a machine's states may carry.
+ *  Set `required: true` to force every state to define the property, or
+ *  provide `default_value` to fall back when the state does not specify it.
+ */
 declare type JssmPropertyDefinition = {
     name: string;
     default_value?: any;
@@ -34,6 +103,17 @@ declare type JssmPropertyDefinition = {
 };
 declare type JssmTransitionPermitter<DataType> = (OldState: StateType$1, NewState: StateType$1, OldData: DataType, NewData: DataType) => boolean;
 declare type JssmTransitionPermitterMaybeArray<DataType> = JssmTransitionPermitter<DataType> | Array<JssmTransitionPermitter<DataType>>;
+/**
+ *  A single directed transition (edge) within a state machine.  Captures
+ *  both the topology (`from` / `to`), the FSL semantics (`kind`,
+ *  `forced_only`, `main_path`), and any optional metadata such as a
+ *  per-edge `name`, an action label, a guard `check`, a transition
+ *  `probability` for stochastic models, and an `after_time` for timed
+ *  transitions.
+ *
+ *  @typeParam StateType - The state-name type (usually `string`).
+ *  @typeParam DataType  - The machine's data payload type (`mDT`).
+ */
 declare type JssmTransition<StateType, DataType> = {
     from: StateType;
     to: StateType;
@@ -47,17 +127,34 @@ declare type JssmTransition<StateType, DataType> = {
     forced_only: boolean;
     main_path: boolean;
 };
+/** A list of {@link JssmTransition}s — the edge set of a machine. */
 declare type JssmTransitions<StateType, DataType> = JssmTransition<StateType, DataType>[];
+/**
+ *  The set of states that can immediately precede or follow a given state.
+ *  Returned by jssm helpers that report a state's connectivity in the graph.
+ */
 declare type JssmTransitionList = {
     entrances: Array<StateType$1>;
     exits: Array<StateType$1>;
 };
+/**
+ *  Topology record for one node in a compiled machine: its name, the set of
+ *  states it can be reached from, the set of states it can transition to,
+ *  and whether reaching it constitutes "completing" the machine.
+ */
 declare type JssmGenericState = {
     from: Array<StateType$1>;
     name: StateType$1;
     to: Array<StateType$1>;
     complete: boolean;
 };
+/**
+ *  The full internal bookkeeping snapshot of a {@link Machine}, exposed for
+ *  advanced introspection.  Contains the current state, the state map, the
+ *  edge map and reverse-action map, and the original edge list.  The
+ *  `internal_state_impl_version` field exists so that consumers can detect
+ *  shape changes if this representation evolves.
+ */
 declare type JssmMachineInternalState<DataType> = {
     internal_state_impl_version: 1;
     state: StateType$1;
@@ -70,11 +167,21 @@ declare type JssmMachineInternalState<DataType> = {
 };
 declare type JssmStatePermitter<DataType> = (OldState: StateType$1, NewState: StateType$1, OldData: DataType, NewData: DataType) => boolean;
 declare type JssmStatePermitterMaybeArray<DataType> = JssmStatePermitter<DataType> | Array<JssmStatePermitter<DataType>>;
+/**
+ *  A single key/value pair from an FSL `state X: { ... };` block, in the
+ *  raw form produced by the parser before being condensed into a
+ *  {@link JssmStateDeclaration}.
+ */
 declare type JssmStateDeclarationRule = {
     key: string;
     value: any;
     name?: string;
 };
+/**
+ *  The fully-condensed declaration for a single state, including its raw
+ *  rule list (`declarations`) and the well-known styling fields jssm-viz
+ *  understands.  Returned by {@link Machine.state_declaration}.
+ */
 declare type JssmStateDeclaration = {
     declarations: Array<JssmStateDeclarationRule>;
     shape?: JssmShape;
@@ -85,12 +192,18 @@ declare type JssmStateDeclaration = {
     textColor?: JssmColor;
     backgroundColor?: JssmColor;
     borderColor?: JssmColor;
+    image?: string;
     state: StateType$1;
     property?: {
         name: string;
         value: unknown;
     };
 };
+/**
+ *  A loosened version of {@link JssmStateDeclaration} where every field is
+ *  optional.  Used as the value type for theme entries and for default
+ *  state configuration where most fields will be inherited or merged.
+ */
 declare type JssmStateConfig = Partial<JssmStateDeclaration>;
 declare type JssmStateStyleShape = {
     key: 'shape';
@@ -124,8 +237,35 @@ declare type JssmStateStyleBorderColor = {
     key: 'border-color';
     value: JssmColor;
 };
-declare type JssmStateStyleKey = JssmStateStyleShape | JssmStateStyleColor | JssmStateStyleTextColor | JssmStateStyleCorners | JssmStateStyleLineStyle | JssmStateStyleBackgroundColor | JssmStateStyleStateLabel | JssmStateStyleBorderColor;
+declare type JssmStateStyleImage = {
+    key: 'image';
+    value: string;
+};
+/**
+ *  Tagged union of all individual style key/value pairs that may appear in
+ *  a state's style configuration.  The `key` discriminator selects which
+ *  member, and the `value` is typed accordingly.
+ */
+declare type JssmStateStyleKey = JssmStateStyleShape | JssmStateStyleColor | JssmStateStyleTextColor | JssmStateStyleCorners | JssmStateStyleLineStyle | JssmStateStyleBackgroundColor | JssmStateStyleStateLabel | JssmStateStyleBorderColor | JssmStateStyleImage;
+/**
+ *  An ordered list of {@link JssmStateStyleKey} entries.  Used by the
+ *  `default_*_state_config` machine config options to provide a fallback
+ *  style stack.
+ */
 declare type JssmStateStyleKeyList = JssmStateStyleKey[];
+/**
+ *  Full configuration object accepted by the {@link Machine} constructor and
+ *  by {@link from}.  Carries the transition list and the optional knobs
+ *  governing layout, theming, history, start/end states, property
+ *  definitions, machine metadata (author, license, version, ...) and the
+ *  runtime hook surfaces (`time_source`, `timeout_source`, ...).
+ *
+ *  Most users never construct one of these directly — the `sm` tagged
+ *  template literal and {@link from} produce one from FSL source.
+ *
+ *  @typeParam StateType - The state-name type (usually `string`).
+ *  @typeParam DataType  - The user-supplied data payload type (`mDT`).
+ */
 declare type JssmGenericConfig<StateType, DataType> = {
     graph_layout?: JssmLayout;
     complete?: Array<StateType>;
@@ -178,6 +318,15 @@ declare type JssmGenericConfig<StateType, DataType> = {
     timeout_source?: (Function: any, number: any) => number;
     clear_timeout_source?: (number: any) => void;
 };
+/**
+ *  Internal compiler intermediate: one link in a chained transition
+ *  expression (an "s-expression" segment).  Carries both directions of an
+ *  arrow with optional per-direction action labels, probabilities, and
+ *  after-times.  The recursive `se` field allows the parser to chain
+ *  arrows of the form `A -> B -> C`.  Not intended for end-user code.
+ *
+ *  @internal
+ */
 declare type JssmCompileSe<StateType, mDT> = {
     to: StateType;
     se?: JssmCompileSe<StateType, mDT>;
@@ -189,6 +338,15 @@ declare type JssmCompileSe<StateType, mDT> = {
     l_after?: number;
     r_after?: number;
 };
+/**
+ *  Internal compiler intermediate: the root of a chained transition
+ *  expression, anchored at a `from` state.  Also doubles as the carrier
+ *  for non-transition rules (state declarations, property definitions,
+ *  machine metadata) via its `key`/`value`/`name`/`state` fields.  Not
+ *  intended for end-user code.
+ *
+ *  @internal
+ */
 declare type JssmCompileSeStart<StateType, DataType> = {
     from: StateType;
     se: JssmCompileSe<StateType, DataType>;
@@ -199,6 +357,13 @@ declare type JssmCompileSeStart<StateType, DataType> = {
     default_value?: any;
     required?: boolean;
 };
+/**
+ *  The output shape of the FSL parser: a flat array of
+ *  {@link JssmCompileSeStart} entries, one per top-level rule in the
+ *  source.  Consumed by the compiler to build a machine configuration.
+ *
+ *  @internal
+ */
 declare type JssmParseTree<StateType, mDT> = Array<JssmCompileSeStart<StateType, mDT>>;
 declare type BasicHookDescription<mDT> = {
     kind: 'hook';
@@ -301,21 +466,116 @@ declare type PostExitHook<mDT> = {
     from: string;
     handler: PostHookHandler<mDT>;
 };
-declare type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT> | AfterHook<mDT> | PostBasicHookDescription<mDT> | PostHookDescriptionWithAction<mDT> | PostGlobalActionHook<mDT> | PostAnyActionHook<mDT> | PostStandardTransitionHook<mDT> | PostMainTransitionHook<mDT> | PostForcedTransitionHook<mDT> | PostAnyTransitionHook<mDT> | PostEntryHook<mDT> | PostExitHook<mDT>;
+declare type PreEverythingHook<mDT> = {
+    kind: 'pre everything';
+    handler: EverythingHookHandler<mDT>;
+};
+declare type EverythingHook<mDT> = {
+    kind: 'everything';
+    handler: EverythingHookHandler<mDT>;
+};
+declare type PrePostEverythingHook<mDT> = {
+    kind: 'pre post everything';
+    handler: PostEverythingHookHandler<mDT>;
+};
+declare type PostEverythingHook<mDT> = {
+    kind: 'post everything';
+    handler: PostEverythingHookHandler<mDT>;
+};
+/**
+ *  Discriminated union of every kind of hook registration jssm understands,
+ *  pre-transition and post-transition.  The `kind` field selects the
+ *  variant; remaining fields describe which transitions / states / actions
+ *  the hook is bound to and supply the {@link HookHandler} or
+ *  {@link PostHookHandler} to invoke.
+ *
+ *  Pre-transition variants (`'hook'`, `'named'`, `'standard transition'`,
+ *  `'main transition'`, `'forced transition'`, `'any transition'`,
+ *  `'global action'`, `'any action'`, `'entry'`, `'exit'`, `'after'`)
+ *  may return a falsy value to veto a transition.  Post-transition
+ *  variants (`'post *'`) cannot veto and are invoked only after a
+ *  successful transition.
+ */
+declare type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT> | AfterHook<mDT> | PostBasicHookDescription<mDT> | PostHookDescriptionWithAction<mDT> | PostGlobalActionHook<mDT> | PostAnyActionHook<mDT> | PostStandardTransitionHook<mDT> | PostMainTransitionHook<mDT> | PostForcedTransitionHook<mDT> | PostAnyTransitionHook<mDT> | PostEntryHook<mDT> | PostExitHook<mDT> | PreEverythingHook<mDT> | EverythingHook<mDT> | PrePostEverythingHook<mDT> | PostEverythingHook<mDT>;
+/**
+ *  Richer hook return value used when a hook needs to do more than just
+ *  accept or veto a transition.  `pass` is the required accept/veto flag
+ *  (kept non-optional so that returning a stray object doesn't accidentally
+ *  veto everything).  The optional `state` overrides the destination state,
+ *  `data` overrides the data observed by other hooks in the same chain,
+ *  and `next_data` overrides the data committed after the transition.
+ */
 declare type HookComplexResult<mDT> = {
     pass: boolean;
     state?: StateType$1;
     data?: mDT;
     next_data?: mDT;
 };
-declare type HookResult<mDT> = true | false | undefined | void | HookComplexResult<mDT>; /** Documents whether a hook succeeded, either with a primitive or a reference to the hook complex object */
+/**
+ *  Return value from a {@link HookHandler}.  May be a plain boolean to
+ *  accept (`true`/`undefined`/`void`) or veto (`false`) the transition, or
+ *  a {@link HookComplexResult} that additionally rewrites the next state
+ *  and/or the next data payload.
+ */
+declare type HookResult<mDT> = true | false | undefined | void | HookComplexResult<mDT>;
+/**
+ *  Context object passed to every {@link HookHandler}.  `data` is the
+ *  data payload as it stands before the transition, and `next_data` is
+ *  the payload that will be committed if the transition is accepted —
+ *  handlers may inspect or mutate the latter via a
+ *  {@link HookComplexResult} return value.
+ */
 declare type HookContext<mDT> = {
     data: mDT;
     next_data: mDT;
 };
+/**
+ *  Context object passed to "everything" hooks ({@link EverythingHookHandler}
+ *  and {@link PostEverythingHookHandler}).  Extends the usual
+ *  {@link HookContext} with `hook_name`, which identifies which specific
+ *  hook fired so a single handler can route on it.
+ */
+declare type EverythingHookContext<mDT> = HookContext<mDT> & {
+    hook_name: string;
+};
+/**
+ *  Signature of a pre-transition hook handler.  Receives the current and
+ *  proposed-next data payloads via a {@link HookContext} and returns a
+ *  {@link HookResult}: a falsy result vetoes the transition, a truthy
+ *  result allows it, and a {@link HookComplexResult} can additionally
+ *  rewrite the next state or next data.
+ */
 declare type HookHandler<mDT> = (hook_context: HookContext<mDT>) => HookResult<mDT>;
+/**
+ *  Signature of a post-transition hook handler.  Invoked after a successful
+ *  transition has been committed; the return value is ignored (the
+ *  transition cannot be undone).
+ */
 declare type PostHookHandler<mDT> = (hook_context: HookContext<mDT>) => void;
+/**
+ *  Signature of an "everything" pre-transition hook handler.  Like
+ *  {@link HookHandler} but receives an {@link EverythingHookContext} so the
+ *  handler can dispatch on `hook_name`.
+ */
+declare type EverythingHookHandler<mDT> = (hook_context: EverythingHookContext<mDT>) => HookResult<mDT>;
+/**
+ *  Signature of an "everything" post-transition hook handler.  Like
+ *  {@link PostHookHandler} but receives an {@link EverythingHookContext}.
+ *  The return value is ignored.
+ */
+declare type PostEverythingHookHandler<mDT> = (hook_context: EverythingHookContext<mDT>) => void;
+/**
+ *  Bounded history of recently-visited states paired with the data payload
+ *  observed in each.  Backed by `circular_buffer_js`, so the oldest entry
+ *  is dropped silently once the configured capacity is exceeded.
+ */
 declare type JssmHistory<mDT> = circular_buffer<[StateType$1, mDT]>;
+/**
+ *  Pluggable random-number-generator function shape.  Must return a value
+ *  in `[0, 1)` exactly as `Math.random` does.  Supplied via the
+ *  `rng_seed`-aware machine configuration so that stochastic models can be
+ *  made reproducible.
+ */
 declare type JssmRng = () => number;
 
 /*********
@@ -493,6 +753,33 @@ declare function compile<StateType, mDT>(tree: JssmParseTree<StateType, mDT>): J
  */
 declare function make<StateType, mDT>(plan: string): JssmGenericConfig<StateType, mDT>;
 
+/*******
+ *
+ *  Selects a single item from a weighted array of objects using cumulative
+ *  probability.  Each object in the array should have a numeric property
+ *  indicating its relative weight (defaults to `'probability'`).  Objects
+ *  missing the property are treated as weight 1.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { value: 'common',  probability: 0.8 },
+ *    { value: 'rare',    probability: 0.2 }
+ *  ];
+ *
+ *  weighted_rand_select(opts);  // most often { value: 'common', ... }
+ *  ```
+ *
+ *  @param options              - Non-empty array of objects to choose from.
+ *  @param probability_property - Name of the numeric weight property on each
+ *                                object.  Defaults to `'probability'`.
+ *  @param rng                  - Optional random number generator `() => number`
+ *                                in `[0, 1)`.  Defaults to `Math.random`.
+ *
+ *  @returns One element from `options`, chosen by weighted random selection.
+ *
+ *  @throws {TypeError} If `options` is not a non-empty array of objects.
+ *
+ */
 declare const weighted_rand_select: Function;
 /*******
  *
@@ -520,8 +807,68 @@ declare function seq(n: number): number[];
  *
  */
 declare const histograph: Function;
+/*******
+ *
+ *  Draws `n` weighted random samples from an array of objects.  Each draw is
+ *  independent (with replacement), delegating to {@link weighted_rand_select}.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { value: 'a', probability: 0.9 },
+ *    { value: 'b', probability: 0.1 }
+ *  ];
+ *
+ *  weighted_sample_select(3, opts, 'probability');
+ *  // e.g. [ { value: 'a', ... }, { value: 'a', ... }, { value: 'b', ... } ]
+ *  ```
+ *
+ *  @param n                    - Number of samples to draw.
+ *  @param options              - Non-empty array of weighted objects.
+ *  @param probability_property - Name of the numeric weight property.
+ *  @param rng                  - Optional random number generator.
+ *
+ *  @returns An array of `n` independently selected items.
+ *
+ */
 declare const weighted_sample_select: Function;
+/*******
+ *
+ *  Draws `n` weighted random samples, extracts a named key from each, and
+ *  returns a histograph (`Map`) of how often each key value appeared.  Useful
+ *  for validating that a probabilistic transition distribution is roughly
+ *  correct over many trials.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { to: 'a', probability: 0.7 },
+ *    { to: 'b', probability: 0.3 }
+ *  ];
+ *
+ *  weighted_histo_key(1000, opts, 'probability', 'to');
+ *  // Map { 'a' => ~700, 'b' => ~300 }
+ *  ```
+ *
+ *  @param n         - Number of samples to draw.
+ *  @param opts      - Non-empty array of weighted objects.
+ *  @param prob_prop - Name of the numeric weight property.
+ *  @param extract   - Name of the property to extract from each sample for
+ *                     histogramming.
+ *  @param rng       - Optional random number generator.
+ *
+ *  @returns A `Map` from extracted key values to their occurrence counts.
+ *
+ */
 declare const weighted_histo_key: Function;
+/*******
+ *
+ *  Creates a SplitMix32 random generator.  Used by the randomness test suite.
+ *
+ *  Sourced from `bryc`: https://github.com/bryc/code/blob/master/jshash/PRNGs.md#splitmix32
+ *
+ *  Replaces the Mulberry generator, which was found to have problems
+ *
+ */
+declare function gen_splitmix32(a?: number | undefined): () => number;
 /*******
  *
  *  Reduces an array to its unique contents.  Compares with `===` and makes no
@@ -538,7 +885,7 @@ declare const weighted_histo_key: Function;
  *  ```
  *
  */
-declare const unique: <T>(arr?: T[]) => T[];
+declare const unique: <T>(arr: T[]) => T[];
 /*******
  *
  *  Lists all repeated items in an array along with their counts.  Subject to
@@ -558,8 +905,33 @@ declare const unique: <T>(arr?: T[]) => T[];
  *
  */
 declare function find_repeated<T>(arr: T[]): [T, number][];
+/*******
+ *
+ *  Returns a `Promise` that resolves after `ms` milliseconds.  Useful for
+ *  inserting delays in async test flows or demos.
+ *
+ *  ```typescript
+ *  await sleep(100);  // pauses execution for 100ms
+ *  ```
+ *
+ *  @param ms - Number of milliseconds to wait before resolving.
+ *
+ *  @returns A `Promise<void>` that resolves after the timeout.
+ *
+ */
 declare function sleep(ms: number): Promise<unknown>;
 
+/*******
+ *
+ *  Convenience aliases for common mathematical and numeric constants from
+ *  `Number` and `Math`.  Re-exported so that FSL data expressions and tests
+ *  can reference them without importing `Math` directly.
+ *
+ *  Includes: `NegInfinity`, `PosInfinity`, `Epsilon`, `Pi`, `E`, `Root2`,
+ *  `RootHalf`, `Ln2`, `Ln10`, `Log2E`, `Log10E`, `MaxSafeInt`, `MinSafeInt`,
+ *  `MaxPosNum`, `MinPosNum`, `Phi` (golden ratio), `EulerC` (Euler–Mascheroni).
+ *
+ */
 declare const NegInfinity: number;
 declare const PosInfinity: number;
 declare const Epsilon: number;
@@ -577,8 +949,29 @@ declare const MaxPosNum: number;
 declare const MinPosNum: number;
 declare const Phi = 1.618033988749895;
 declare const EulerC = 0.5772156649015329;
+/*******
+ *
+ *  Complete list of node shapes supported by Graphviz.  Used by jssm-viz to
+ *  validate and render state shapes in FSL `state ... : { shape: ... }` blocks.
+ *
+ *  `shapes` is an alias for `gviz_shapes`.
+ *
+ */
 declare const gviz_shapes$1: string[];
+/**
+ *  Public alias for {@link gviz_shapes}.  The list of node shapes supported
+ *  by Graphviz that jssm-viz accepts in FSL `state ... : { shape: ... }`
+ *  declarations.
+ */
 declare const shapes$1: string[];
+/*******
+ *
+ *  List of CSS/SVG named colors accepted by jssm-viz for state styling
+ *  properties like `background-color` and `text-color`.  Case-insensitive
+ *  matching is done at parse time; the canonical casing here follows the
+ *  CSS specification.
+ *
+ */
 declare const named_colors$1: string[];
 
 declare const jssm_constants_d_E: typeof E;
@@ -599,7 +992,28 @@ declare const jssm_constants_d_PosInfinity: typeof PosInfinity;
 declare const jssm_constants_d_Root2: typeof Root2;
 declare const jssm_constants_d_RootHalf: typeof RootHalf;
 declare namespace jssm_constants_d {
-  export { jssm_constants_d_E as E, jssm_constants_d_Epsilon as Epsilon, jssm_constants_d_EulerC as EulerC, jssm_constants_d_Ln10 as Ln10, jssm_constants_d_Ln2 as Ln2, jssm_constants_d_Log10E as Log10E, jssm_constants_d_Log2E as Log2E, jssm_constants_d_MaxPosNum as MaxPosNum, jssm_constants_d_MaxSafeInt as MaxSafeInt, jssm_constants_d_MinPosNum as MinPosNum, jssm_constants_d_MinSafeInt as MinSafeInt, jssm_constants_d_NegInfinity as NegInfinity, jssm_constants_d_Phi as Phi, jssm_constants_d_Pi as Pi, jssm_constants_d_PosInfinity as PosInfinity, jssm_constants_d_Root2 as Root2, jssm_constants_d_RootHalf as RootHalf, gviz_shapes$1 as gviz_shapes, named_colors$1 as named_colors, shapes$1 as shapes };
+  export {
+    jssm_constants_d_E as E,
+    jssm_constants_d_Epsilon as Epsilon,
+    jssm_constants_d_EulerC as EulerC,
+    jssm_constants_d_Ln10 as Ln10,
+    jssm_constants_d_Ln2 as Ln2,
+    jssm_constants_d_Log10E as Log10E,
+    jssm_constants_d_Log2E as Log2E,
+    jssm_constants_d_MaxPosNum as MaxPosNum,
+    jssm_constants_d_MaxSafeInt as MaxSafeInt,
+    jssm_constants_d_MinPosNum as MinPosNum,
+    jssm_constants_d_MinSafeInt as MinSafeInt,
+    jssm_constants_d_NegInfinity as NegInfinity,
+    jssm_constants_d_Phi as Phi,
+    jssm_constants_d_Pi as Pi,
+    jssm_constants_d_PosInfinity as PosInfinity,
+    jssm_constants_d_Root2 as Root2,
+    jssm_constants_d_RootHalf as RootHalf,
+    gviz_shapes$1 as gviz_shapes,
+    named_colors$1 as named_colors,
+    shapes$1 as shapes,
+  };
 }
 
 declare const version: string;
@@ -621,7 +1035,69 @@ declare const named_colors: string[];
  *
  */
 declare function transfer_state_properties(state_decl: JssmStateDeclaration): JssmStateDeclaration;
-declare function state_style_condense(jssk: JssmStateStyleKeyList): JssmStateConfig;
+/**
+ *
+ *  Collapse a list of individual state-style key/value pairs into a single
+ *  {@link JssmStateConfig} object, remapping FSL-style kebab-case keys to the
+ *  camelCase field names the runtime uses.
+ *
+ *  The parser emits state styling as a flat array like
+ *  `[{ key: 'color', value: 'red' }, { key: 'line-style', value: 'dashed' }]`
+ *  because that is the most natural shape for the grammar to produce.  This
+ *  helper runs once per style bucket during `Machine` construction to turn
+ *  those arrays into the compact `{ color, lineStyle, ... }` objects the
+ *  graph-rendering code expects.
+ *
+ *  ```typescript
+ *  state_style_condense([
+ *    { key: 'color',      value: 'red' },
+ *    { key: 'shape',      value: 'oval' },
+ *    { key: 'line-style', value: 'dashed' }
+ *  ]);
+ *  // => { color: 'red', shape: 'oval', lineStyle: 'dashed' }
+ *
+ *  state_style_condense(undefined);
+ *  // => {}
+ *  ```
+ *
+ *  @param jssk The list of style keys to condense.  `undefined` is accepted
+ *  and yields an empty config.
+ *
+ *  @param machine Optional `Machine` reference, used only so that any
+ *  {@link JssmError} thrown can point at the offending machine in its
+ *  diagnostic message.
+ *
+ *  @returns A `JssmStateConfig` object containing every key from `jssk`
+ *  remapped into its camelCase field.
+ *
+ *  @throws {JssmError} If `jssk` is neither an array nor `undefined`, if any
+ *  element is not an object, if the same key appears more than once, or if a
+ *  key is not one of the recognized style names.
+ *
+ *  @internal
+ *
+ */
+declare function state_style_condense(jssk: JssmStateStyleKeyList, machine?: any): JssmStateConfig;
+/*******
+ *
+ *  Core finite state machine class.  Holds the full graph of states and
+ *  transitions, the current state, hooks, data, properties, and all runtime
+ *  behavior.  Typically created via the {@link sm} tagged template literal
+ *  rather than constructed directly.
+ *
+ *  ```typescript
+ *  import { sm } from 'jssm';
+ *
+ *  const light = sm`Red 'next' => Green 'next' => Yellow 'next' => Red;`;
+ *  light.state();       // 'Red'
+ *  light.action('next'); // true
+ *  light.state();       // 'Green'
+ *  ```
+ *
+ *  @typeparam mDT The machine data type — the type of the value stored in
+ *  `.data()`.  Defaults to `undefined` when no data is used.
+ *
+ */
 declare class Machine<mDT> {
     _state: StateType;
     _states: Map<StateType, JssmGenericState>;
@@ -694,6 +1170,10 @@ declare class Machine<mDT> {
     _post_main_transition_hook: HookHandler<mDT> | undefined;
     _post_forced_transition_hook: HookHandler<mDT> | undefined;
     _post_any_transition_hook: HookHandler<mDT> | undefined;
+    _pre_everything_hook: EverythingHookHandler<mDT> | undefined;
+    _everything_hook: EverythingHookHandler<mDT> | undefined;
+    _pre_post_everything_hook: PostEverythingHookHandler<mDT> | undefined;
+    _post_everything_hook: PostEverythingHookHandler<mDT> | undefined;
     _property_keys: Set<string>;
     _default_properties: Map<string, any>;
     _state_properties: Map<string, any>;
@@ -741,6 +1221,8 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns The current state name.
+     *
      */
     state(): StateType;
     /*********
@@ -759,6 +1241,10 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @param state The state to get the label for.
+     *
+     *  @returns The label string, or `undefined` if no label is set.
+     *
      */
     label_for(state: StateType): string;
     /*********
@@ -782,6 +1268,10 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @param state The state to get display text for.
+     *
+     *  @returns The label if one exists, otherwise the state's name.
+     *
      */
     display_text(state: StateType): string;
     /*********
@@ -797,45 +1287,60 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns A deep clone of the machine's current data value.
+     *
      */
     data(): mDT;
     /*********
      *
-     *  Get the current value of a given property name.
+     *  Get the current value of a given property name.  Checks the current
+     *  state's properties first, then falls back to the global default.
+     *  Returns `undefined` if neither exists.  For a throwing variant, see
+     *  {@link strict_prop}.
      *
      *  ```typescript
+     *  const m = sm`property color default "grey"; a -> b;
+     *               state b: { property color "blue"; };`;
      *
+     *  m.prop('color');  // 'grey'  (default, because state is 'a')
+     *  m.go('b');
+     *  m.prop('color');  // 'blue'  (state 'b' overrides the default)
+     *  m.prop('size');   // undefined (no such property)
      *  ```
      *
-     *  @param name The relevant property name to look up
+     *  @param name The relevant property name to look up.
      *
-     *  @returns The value behind the prop name.  Because functional props are
-     *  evaluated as getters, this can be anything.
+     *  @returns The value behind the prop name, or `undefined` if not defined.
      *
      */
     prop(name: string): any;
     /*********
      *
      *  Get the current value of a given property name.  If missing on the state
-     *  and without a global default, throw, unlike {@link prop}, which would
-     *  return `undefined` instead.
+     *  and without a global default, throws a {@link JssmError}, unlike
+     *  {@link prop}, which would return `undefined` instead.
      *
      *  ```typescript
+     *  const m = sm`property color default "grey"; a -> b;`;
      *
+     *  m.strict_prop('color');  // 'grey'
+     *  m.strict_prop('size');   // throws JssmError
      *  ```
      *
-     *  @param name The relevant property name to look up
+     *  @param name The relevant property name to look up.
      *
-     *  @returns The value behind the prop name.  Because functional props are
-     *  evaluated as getters, this can be anything.
+     *  @returns The value behind the prop name.
+     *
+     *  @throws {JssmError} If the property is not defined on the current state
+     *  and has no default.
      *
      */
     strict_prop(name: string): any;
     /*********
      *
      *  Get the current value of every prop, as an object.  If no current definition
-     *  exists for a prop - that is, if the prop was defined without a default and
-     *  the current state also doesn't define the prop - then that prop will be listed
+     *  exists for a prop — that is, if the prop was defined without a default and
+     *  the current state also doesn't define the prop — then that prop will be listed
      *  in the returned object with a value of `undefined`.
      *
      *  ```typescript
@@ -866,29 +1371,12 @@ declare class Machine<mDT> {
      *  traffic_light.props();  // { can_go: true,  hesitate: false, stop_first: false; }
      *  ```
      *
-     */
-    props(): object;
-    /*********
-     *
-     *  Get the current value of every prop, as an object.  Compare
-     *  {@link prop_map}, which returns a `Map`.
-     *
-     *  ```typescript
-     *
-     *  ```
-     *
-     */
-    /*********
-     *
-     *  Get the current value of every prop, as an object.  Compare
-     *  {@link prop_map}, which returns a `Map`.  Akin to {@link strict_prop},
-     *  this throws if a required prop is missing.
-     *
-     *  ```typescript
-     *
-     *  ```
+     *  @returns An object mapping every known property name to its current value
+     *  (or `undefined` if the property has no default and the current state
+     *  doesn't define it).
      *
      */
+    props(): object;
     /*********
      *
      *  Check whether a given string is a known property's name.
@@ -911,8 +1399,13 @@ declare class Machine<mDT> {
      *  the properties generally will not be sorted.
      *
      *  ```typescript
+     *  const m = sm`property color default "grey"; property size default 1; a -> b;`;
+     *
+     *  m.known_props();  // ['color', 'size']
      *  ```
      *
+     *  @returns An array of all property name strings defined on this machine.
+     *
      */
     known_props(): string[];
     /********
@@ -1011,22 +1504,78 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @param comment An optional comment string to embed in the serialized
+     *  output for identification or debugging.
+     *
+     *  @returns A {@link JssmSerialization} object containing the machine's
+     *  current state, data, and timestamp.
+     *
      */
     serialize(comment?: string | undefined): JssmSerialization<mDT>;
+    /** Get the graph layout direction (e.g. `'LR'`, `'TB'`).  Set via the
+     *  FSL `graph_layout` directive.
+     *  @returns The layout string, or the default if not set.
+     */
     graph_layout(): string;
+    /** Get the Graphviz DOT preamble string, injected before the graph body
+     *  during visualization.  Set via the FSL `dot_preamble` directive.
+     *  @returns The preamble string.
+     */
     dot_preamble(): string;
+    /** Get the machine's author list.  Set via the FSL `machine_author` directive.
+     *  @returns An array of author name strings.
+     */
     machine_author(): Array<string>;
+    /** Get the machine's comment string.  Set via the FSL `machine_comment` directive.
+     *  @returns The comment string.
+     */
     machine_comment(): string;
+    /** Get the machine's contributor list.  Set via the FSL `machine_contributor` directive.
+     *  @returns An array of contributor name strings.
+     */
     machine_contributor(): Array<string>;
+    /** Get the machine's definition string.  Set via the FSL `machine_definition` directive.
+     *  @returns The definition string.
+     */
     machine_definition(): string;
+    /** Get the machine's language (ISO 639-1).  Set via the FSL `machine_language` directive.
+     *  @returns The language code string.
+     */
     machine_language(): string;
+    /** Get the machine's license string.  Set via the FSL `machine_license` directive.
+     *  @returns The license string.
+     */
     machine_license(): string;
+    /** Get the machine's name.  Set via the FSL `machine_name` directive.
+     *  @returns The machine name string.
+     */
     machine_name(): string;
+    /** Get the machine's version string.  Set via the FSL `machine_version` directive.
+     *  @returns The version string.
+     */
     machine_version(): string;
+    /** Get the raw state declaration objects as parsed from the FSL source.
+     *  @returns An array of raw state declaration objects.
+     */
     raw_state_declarations(): Array<Object>;
+    /** Get the processed state declaration for a specific state.
+     *  @param which - The state to look up.
+     *  @returns The {@link JssmStateDeclaration} for the given state.
+     */
     state_declaration(which: StateType): JssmStateDeclaration;
+    /** Get all processed state declarations as a Map.
+     *  @returns A `Map` from state name to {@link JssmStateDeclaration}.
+     */
     state_declarations(): Map<StateType, JssmStateDeclaration>;
+    /** Get the FSL language version this machine was compiled under.
+     *  @returns The FSL version string.
+     */
     fsl_version(): string;
+    /** Get the complete internal state of the machine as a serializable
+     *  structure.  Includes actions, edges, edge map, named transitions,
+     *  reverse actions, current state, and states map.
+     *  @returns A {@link JssmMachineInternalState} snapshot.
+     */
     machine_state(): JssmMachineInternalState<mDT>;
     /*********
      *
@@ -1042,8 +1591,15 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns An array of all state names in the machine.
+     *
      */
     states(): Array<StateType>;
+    /** Get the internal state descriptor for a given state name.
+     *  @param whichState - The state to look up.
+     *  @returns The {@link JssmGenericState} descriptor.
+     *  @throws {JssmError} If the state does not exist.
+     */
     state_for(whichState: StateType): JssmGenericState;
     /*********
      *
@@ -1060,7 +1616,9 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
-     *  @param whichState The state to be checked for extance
+     *  @param whichState The state to be checked for existence.
+     *
+     *  @returns `true` if the state exists, `false` otherwise.
      *
      */
     has_state(whichState: StateType): boolean;
@@ -1096,35 +1654,82 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns An array of all {@link JssmTransition} edge objects.
+     *
      */
     list_edges(): Array<JssmTransition<StateType, mDT>>;
+    /** Get the map of named transitions (transitions with explicit names).
+     *  @returns A `Map` from transition name to edge index.
+     */
     list_named_transitions(): Map<StateType, number>;
+    /** List all distinct action names defined anywhere in the machine.
+     *  @returns An array of action name strings.
+     */
     list_actions(): Array<StateType>;
+    /** Whether any actions are defined on this machine.
+     *  @returns `true` if the machine has at least one action.
+     */
     get uses_actions(): boolean;
+    /** Whether any forced (`~>`) transitions exist in this machine.
+     *  @returns `true` if at least one forced transition is defined.
+     */
     get uses_forced_transitions(): boolean;
     /*********
      *
      *  Check if the code that built the machine allows overriding state and data.
      *
+     *  @returns The override permission from the FSL source code.
+     *
      */
     get code_allows_override(): JssmAllowsOverride;
     /*********
      *
      *  Check if the machine config allows overriding state and data.
      *
+     *  @returns The override permission from the runtime config.
+     *
      */
     get config_allows_override(): JssmAllowsOverride;
     /*********
      *
-     *  Check if a machine allows overriding state and data.
+     *  Check if a machine allows overriding state and data.  Resolves the
+     *  combined effect of code and config permissions — config may not be
+     *  less strict than code.
+     *
+     *  @returns The effective override permission.
      *
      */
     get allows_override(): JssmAllowsOverride;
+    /** List all available theme names.
+     *  @returns An array of theme name strings.
+     */
     all_themes(): FslTheme[];
+    /** Get the active theme(s) for this machine.  Always stored as an array
+     *  internally; the union return type exists for setter compatibility.
+     *  @returns The current theme or array of themes.
+     */
     get themes(): FslTheme | FslTheme[];
+    /** Set the active theme(s).  Accepts a single theme name or an array.
+     *  @param to - A theme name or array of theme names to apply.
+     */
     set themes(to: FslTheme | FslTheme[]);
+    /** Get the flow direction for graph layout (e.g. `'right'`, `'down'`).
+     *  Set via the FSL `flow` directive.
+     *  @returns The current flow direction.
+     */
     flow(): FslDirection;
+    /** Look up a transition's edge index by source and target state names.
+     *  @param from - Source state name.
+     *  @param to   - Target state name.
+     *  @returns The edge index in the edges array, or `undefined` if no
+     *  such transition exists.
+     */
     get_transition_by_state_names(from: StateType, to: StateType): number;
+    /** Look up the full transition object for a given source→target pair.
+     *  @param from - Source state name.
+     *  @param to   - Target state name.
+     *  @returns The {@link JssmTransition} object, or `undefined` if none exists.
+     */
     lookup_transition_for(from: StateType, to: StateType): JssmTransition<StateType, mDT>;
     /********
      *
@@ -1192,9 +1797,29 @@ declare class Machine<mDT> {
      *
      */
     list_exits(whichState?: StateType): Array<StateType>;
+    /** Get the transitions available from a state, filtered to those with
+     *  probability data.  Used by the probabilistic walk system.
+     *  @param whichState - The state to inspect.
+     *  @returns An array of {@link JssmTransition} edges exiting the state.
+     *  @throws {JssmError} If the state does not exist.
+     */
     probable_exits_for(whichState: StateType): Array<JssmTransition<StateType, mDT>>;
+    /** Take a single random transition from the current state, weighted by
+     *  edge probabilities.
+     *  @returns `true` if a transition was taken, `false` otherwise.
+     */
     probabilistic_transition(): boolean;
+    /** Take `n` consecutive probabilistic transitions and return the sequence
+     *  of states visited (before each transition).
+     *  @param n - Number of steps to walk.
+     *  @returns An array of state names visited during the walk.
+     */
     probabilistic_walk(n: number): Array<StateType>;
+    /** Take `n` probabilistic steps and return a histograph of how many times
+     *  each state was visited.
+     *  @param n - Number of steps to walk.
+     *  @returns A `Map` from state name to visit count.
+     */
     probabilistic_histo_walk(n: number): Map<StateType, number>;
     /********
      *
@@ -1227,7 +1852,10 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
-     *  @param whichState The state whose actions to have listed
+     *  @param whichState The state whose actions to list.  Defaults to the
+     *  current state.
+     *
+     *  @returns An array of action names available from the given state.
      *
      */
     actions(whichState?: StateType): Array<StateType>;
@@ -1254,40 +1882,276 @@ declare class Machine<mDT> {
      *
      */
     list_states_having_action(whichState: StateType): Array<StateType>;
+    /** List all action names available as exits from a given state.
+     *  @param whichState - The state to inspect.  Defaults to the current state.
+     *  @returns An array of action name strings.
+     *  @throws {JssmError} If the state does not exist.
+     */
     list_exit_actions(whichState?: StateType): Array<StateType>;
+    /** List all action exits from a state with their probabilities.
+     *  @param whichState - The state to inspect.  Defaults to the current state.
+     *  @returns An array of `{ action, probability }` objects.
+     *  @throws {JssmError} If the state does not exist.
+     */
     probable_action_exits(whichState?: StateType): Array<any>;
+    /** Check whether a state has no incoming transitions (unreachable after start).
+     *  @param whichState - The state to check.
+     *  @returns `true` if the state has zero entrances.
+     *  @throws {JssmError} If the state does not exist.
+     */
     is_unenterable(whichState: StateType): boolean;
+    /** Check whether any state in the machine is unenterable.
+     *  @returns `true` if at least one state has no incoming transitions.
+     */
     has_unenterables(): boolean;
+    /** Check whether the current state is terminal (has no exits).
+     *  @returns `true` if the current state has zero exits.
+     */
     is_terminal(): boolean;
+    /** Check whether a specific state is terminal (has no exits).
+     *  @param whichState - The state to check.
+     *  @returns `true` if the state has zero exits.
+     *  @throws {JssmError} If the state does not exist.
+     */
     state_is_terminal(whichState: StateType): boolean;
+    /** Check whether any state in the machine is terminal.
+     *  @returns `true` if at least one state has no exits.
+     */
     has_terminals(): boolean;
+    /** Check whether the current state is complete (every exit has an action).
+     *  @returns `true` if the current state is complete.
+     */
     is_complete(): boolean;
+    /** Check whether a specific state is complete (every exit has an action).
+     *  @param whichState - The state to check.
+     *  @returns `true` if the state is complete.
+     *  @throws {JssmError} If the state does not exist.
+     */
     state_is_complete(whichState: StateType): boolean;
+    /** Check whether any state in the machine is complete.
+     *  @returns `true` if at least one state is complete.
+     */
     has_completes(): boolean;
+    /** Low-level hook registration.  Installs a handler described by a
+     *  {@link HookDescription} into the appropriate internal map.  Prefer the
+     *  convenience wrappers ({@link hook}, {@link hook_entry}, etc.) over
+     *  calling this directly.
+     *  @param HookDesc - A hook descriptor specifying kind, states, and handler.
+     */
     set_hook(HookDesc: HookDescription<mDT>): void;
+    /** Register a pre-transition hook on a specific edge.  Fires before
+     *  transitioning from `from` to `to`.  If the handler returns `false`, the
+     *  transition is blocked.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b -> c;`;
+     *  m.hook('a', 'b', () => console.log('a->b'));
+     *  ```
+     *
+     *  @param from    - Source state name.
+     *  @param to      - Target state name.
+     *  @param handler - Callback invoked before the transition.
+     *  @returns `this` for chaining.
+     */
     hook(from: string, to: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook on a specific action-labeled edge.
+     *  @param from    - Source state name.
+     *  @param to      - Target state name.
+     *  @param action  - The action label that triggers this hook.
+     *  @param handler - Callback invoked before the transition.
+     *  @returns `this` for chaining.
+     */
     hook_action(from: string, to: string, action: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook on any edge triggered by a specific action.
+     *  @param action  - The action name to hook.
+     *  @param handler - Callback invoked before any transition with this action.
+     *  @returns `this` for chaining.
+     */
     hook_global_action(action: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook on any action-driven transition.
+     *  @param handler - Callback invoked before any action transition.
+     *  @returns `this` for chaining.
+     */
     hook_any_action(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook on any standard (`->`) transition.
+     *  @param handler - Callback invoked before any legal transition.
+     *  @returns `this` for chaining.
+     */
     hook_standard_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook on any main-path (`=>`) transition.
+     *  @param handler - Callback invoked before any main transition.
+     *  @returns `this` for chaining.
+     */
     hook_main_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook on any forced (`~>`) transition.
+     *  @param handler - Callback invoked before any forced transition.
+     *  @returns `this` for chaining.
+     */
     hook_forced_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook on any transition regardless of kind.
+     *  @param handler - Callback invoked before every transition.
+     *  @returns `this` for chaining.
+     */
     hook_any_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a hook that fires when entering a specific state.
+     *  @param to      - The state being entered.
+     *  @param handler - Callback invoked on entry.
+     *  @returns `this` for chaining.
+     */
     hook_entry(to: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a hook that fires when leaving a specific state.
+     *  @param from    - The state being exited.
+     *  @param handler - Callback invoked on exit.
+     *  @returns `this` for chaining.
+     */
     hook_exit(from: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a hook that fires after leaving a specific state (post-exit).
+     *  @param from    - The state that was exited.
+     *  @param handler - Callback invoked after exit completes.
+     *  @returns `this` for chaining.
+     */
     hook_after(from: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook on a specific edge.  Fires after the transition
+     *  from `from` to `to` has completed.  Cannot block the transition.
+     *  @param from    - Source state name.
+     *  @param to      - Target state name.
+     *  @param handler - Callback invoked after the transition.
+     *  @returns `this` for chaining.
+     */
     post_hook(from: string, to: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook on a specific action-labeled edge.
+     *  @param from    - Source state name.
+     *  @param to      - Target state name.
+     *  @param action  - The action label.
+     *  @param handler - Callback invoked after the transition.
+     *  @returns `this` for chaining.
+     */
     post_hook_action(from: string, to: string, action: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook on any edge triggered by a specific action.
+     *  @param action  - The action name.
+     *  @param handler - Callback invoked after any transition with this action.
+     *  @returns `this` for chaining.
+     */
     post_hook_global_action(action: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook on any action-driven transition.
+     *  @param handler - Callback invoked after any action transition.
+     *  @returns `this` for chaining.
+     */
     post_hook_any_action(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook on any standard (`->`) transition.
+     *  @param handler - Callback invoked after any legal transition.
+     *  @returns `this` for chaining.
+     */
     post_hook_standard_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook on any main-path (`=>`) transition.
+     *  @param handler - Callback invoked after any main transition.
+     *  @returns `this` for chaining.
+     */
     post_hook_main_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook on any forced (`~>`) transition.
+     *  @param handler - Callback invoked after any forced transition.
+     *  @returns `this` for chaining.
+     */
     post_hook_forced_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook on any transition regardless of kind.
+     *  @param handler - Callback invoked after every transition.
+     *  @returns `this` for chaining.
+     */
     post_hook_any_transition(handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook that fires after entering a specific state.
+     *  @param to      - The state that was entered.
+     *  @param handler - Callback invoked after entry.
+     *  @returns `this` for chaining.
+     */
     post_hook_entry(to: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Post-transition hook that fires after leaving a specific state.
+     *  @param from    - The state that was exited.
+     *  @param handler - Callback invoked after exit.
+     *  @returns `this` for chaining.
+     */
     post_hook_exit(from: string, handler: HookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook that fires **before** all other pre-hooks
+     *  on every transition.  If the handler returns `false`, the transition is
+     *  blocked.  The handler receives an {@link EverythingHookContext} whose
+     *  `hook_name` is `'pre everything'`.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b -> c;`;
+     *  m.hook_pre_everything(({ hook_name }) => {
+     *    console.log(`${hook_name} fired`);
+     *    return true;
+     *  });
+     *  ```
+     *
+     *  @param handler - Callback invoked before all other pre-hooks.
+     *  @returns `this` for chaining.
+     */
+    hook_pre_everything(handler: EverythingHookHandler<mDT>): Machine<mDT>;
+    /** Register a pre-transition hook that fires **after** all other pre-hooks
+     *  on every transition.  If the handler returns `false`, the transition is
+     *  blocked.  The handler receives an {@link EverythingHookContext} whose
+     *  `hook_name` is `'everything'`.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b -> c;`;
+     *  m.hook_everything(({ hook_name }) => {
+     *    console.log(`${hook_name} fired`);
+     *    return true;
+     *  });
+     *  ```
+     *
+     *  @param handler - Callback invoked after all other pre-hooks.
+     *  @returns `this` for chaining.
+     */
+    hook_everything(handler: EverythingHookHandler<mDT>): Machine<mDT>;
+    /** Register a post-transition hook that fires **after** all other
+     *  post-hooks on every transition.  Cannot block the transition.  The
+     *  handler receives an {@link EverythingHookContext} whose `hook_name` is
+     *  `'post everything'`.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b -> c;`;
+     *  m.hook_post_everything(({ hook_name }) => {
+     *    console.log(`${hook_name} fired`);
+     *  });
+     *  ```
+     *
+     *  @param handler - Callback invoked after all other post-hooks.
+     *  @returns `this` for chaining.
+     */
+    hook_post_everything(handler: PostEverythingHookHandler<mDT>): Machine<mDT>;
+    /** Register a post-transition hook that fires **before** all other
+     *  post-hooks on every transition.  Cannot block the transition.  The
+     *  handler receives an {@link EverythingHookContext} whose `hook_name` is
+     *  `'pre post everything'`.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b -> c;`;
+     *  m.hook_pre_post_everything(({ hook_name }) => {
+     *    console.log(`${hook_name} fired`);
+     *  });
+     *  ```
+     *
+     *  @param handler - Callback invoked before all other post-hooks.
+     *  @returns `this` for chaining.
+     */
+    hook_pre_post_everything(handler: PostEverythingHookHandler<mDT>): Machine<mDT>;
+    /** Get the current RNG seed used for probabilistic transitions.
+     *  @returns The numeric seed value.
+     */
     get rng_seed(): number;
+    /** Set the RNG seed.  Pass `undefined` to reseed from the current time.
+     *  Resets the internal PRNG so subsequent probabilistic operations use the
+     *  new seed.
+     *  @param to - The seed value, or `undefined` for time-based seeding.
+     */
     set rng_seed(to: number | undefined);
+    /** Get all edges between two states (there can be multiple with
+     *  different actions).
+     *  @param from - Source state name.
+     *  @param to   - Target state name.
+     *  @returns An array of matching {@link JssmTransition} objects.
+     */
     edges_between(from: string, to: string): JssmTransition<StateType, mDT>[];
     /*********
      *
@@ -1309,7 +2173,53 @@ declare class Machine<mDT> {
      *
      */
     override(newState: StateType, newData?: mDT | undefined): void;
+    /*********
+     *
+     *  Shared transition core used by {@link transition}, {@link force_transition},
+     *  and {@link action}.  Runs validation, fires the full hook pipeline (pre-
+     *  everything, any-action, after, any-transition, exit, named, basic,
+     *  edge-type, entry, everything), commits the new state if nothing
+     *  rejected, and returns whether the transition succeeded.
+     *
+     *  Not meant for external use.  Call one of the public wrappers instead:
+     *  - `transition` for an ordinary legal transition
+     *  - `force_transition` to bypass the legality check
+     *  - `action` to dispatch by action name rather than target state
+     *
+     *  @remarks
+     *  Known sharp edges, carried over from the original `// TODO` comments:
+     *  - The forced-ness behavior needs to be cleaned up a lot here.
+     *  - The callbacks are not fully correct across the forced / action / plain
+     *    cases and should be revisited.
+     *  - When multiple edges exist between two states with different `kind`
+     *    values, only the first edge's kind is used to pick the edge-type hook.
+     *
+     *  @typeparam mDT The type of the machine data member; usually omitted.
+     *
+     *  @param newStateOrAction The target state name (for a plain or forced
+     *  transition) or the action name (when `wasAction` is true).
+     *
+     *  @param newData Optional replacement machine data to install alongside
+     *  the transition.  Hooks may further override this via complex results.
+     *
+     *  @param wasForced `true` if the caller invoked `force_transition`, in
+     *  which case legality is checked against `valid_force_transition` rather
+     *  than `valid_transition`.
+     *
+     *  @param wasAction `true` if the caller invoked `action`, in which case
+     *  `newStateOrAction` is an action name and the target state is looked up
+     *  via the current action edge.
+     *
+     *  @returns `true` if the transition was valid and every hook passed;
+     *  `false` if the transition was invalid or any hook rejected.
+     *
+     *  @internal
+     *
+     */
     transition_impl(newStateOrAction: StateType, newData: mDT | undefined, wasForced: boolean, wasAction: boolean): boolean;
+    /** If the current state has an `after` timeout configured, schedule it.
+     *  Called internally after each transition.
+     */
     auto_set_state_timeout(): void;
     /*********
      *
@@ -1411,6 +2321,9 @@ declare class Machine<mDT> {
      *
      *  @param newData The data change to insert during the action
      *
+     *  @returns `true` if the action was valid and the transition occurred,
+     *  `false` otherwise.
+     *
      */
     action(actionName: StateType, newData?: mDT): boolean;
     /********
@@ -1431,6 +2344,8 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns The {@link JssmStateConfig} for standard states.
+     *
      */
     get standard_state_style(): JssmStateConfig;
     /********
@@ -1455,6 +2370,8 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns The {@link JssmStateConfig} for hooked states.
+     *
      */
     get hooked_state_style(): JssmStateConfig;
     /********
@@ -1478,6 +2395,8 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns The {@link JssmStateConfig} for start states.
+     *
      */
     get start_state_style(): JssmStateConfig;
     /********
@@ -1506,6 +2425,8 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns The {@link JssmStateConfig} for end states.
+     *
      */
     get end_state_style(): JssmStateConfig;
     /********
@@ -1529,6 +2450,8 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns The {@link JssmStateConfig} for terminal states.
+     *
      */
     get terminal_state_style(): JssmStateConfig;
     /********
@@ -1549,6 +2472,8 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @returns The {@link JssmStateConfig} for the active state.
+     *
      */
     get active_state_style(): JssmStateConfig;
     /********
@@ -1569,6 +2494,10 @@ declare class Machine<mDT> {
      *
      *  @typeparam mDT The type of the machine data member; usually omitted
      *
+     *  @param state The state to compute the composite style for.
+     *
+     *  @returns The fully composited {@link JssmStateConfig} for the given state.
+     *
      */
     style_for(state: StateType): JssmStateConfig;
     /********
@@ -1601,6 +2530,9 @@ declare class Machine<mDT> {
      *
      *  @param newData The data change to insert during the action
      *
+     *  @returns `true` if the action was valid and the transition occurred,
+     *  `false` otherwise.
+     *
      */
     do(actionName: StateType, newData?: mDT): boolean;
     /********
@@ -1631,6 +2563,8 @@ declare class Machine<mDT> {
      *
      *  @param newData The data change to insert during the transition
      *
+     *  @returns `true` if the transition was legal and occurred, `false` otherwise.
+     *
      */
     transition(newState: StateType, newData?: mDT): boolean;
     /********
@@ -1651,6 +2585,8 @@ declare class Machine<mDT> {
      *
      *  @param newData The data change to insert during the transition
      *
+     *  @returns `true` if the transition was legal and occurred, `false` otherwise.
+     *
      */
     go(newState: StateType, newData?: mDT): boolean;
     /********
@@ -1674,21 +2610,84 @@ declare class Machine<mDT> {
      *
      *  @param newData The data change to insert during the transition
      *
+     *  @returns `true` if a transition (forced or otherwise) existed and occurred,
+     *  `false` otherwise.
+     *
      */
     force_transition(newState: StateType, newData?: mDT): boolean;
+    /** Get the edge index for an action from the current state.
+     *  @param action - The action name.
+     *  @returns The edge index, or `undefined` if the action is not available.
+     */
     current_action_for(action: StateType): number;
+    /** Get the full transition object for an action from the current state.
+     *  @param action - The action name.
+     *  @returns The {@link JssmTransition} object.
+     *  @throws {JssmError} If the action is not available from the current state.
+     */
     current_action_edge_for(action: StateType): JssmTransition<StateType, mDT>;
+    /** Check whether an action is available from the current state.
+     *  @param action   - The action name to check.
+     *  @param _newData - Reserved for future data validation.
+     *  @returns `true` if the action can be taken.
+     */
     valid_action(action: StateType, _newData?: mDT): boolean;
+    /** Check whether a transition to a given state is legal (non-forced) from
+     *  the current state.
+     *  @param newState - The target state.
+     *  @param _newData - Reserved for future data validation.
+     *  @returns `true` if the transition is legal.
+     */
     valid_transition(newState: StateType, _newData?: mDT): boolean;
+    /** Check whether a forced transition to a given state exists from the
+     *  current state.
+     *  @param newState - The target state.
+     *  @param _newData - Reserved for future data validation.
+     *  @returns `true` if a forced (or any) transition exists.
+     */
     valid_force_transition(newState: StateType, _newData?: mDT): boolean;
+    /** Get the instance name of this machine, if one was assigned at creation.
+     *  @returns The instance name string, or `undefined`.
+     */
     instance_name(): string | undefined;
+    /** Get the creation date of this machine as a `Date` object.
+     *  @returns A `Date` representing when the machine was created.
+     */
     get creation_date(): Date;
+    /** Get the creation timestamp (milliseconds since epoch).
+     *  @returns The timestamp as a number.
+     */
     get creation_timestamp(): number;
+    /** Get the timestamp when construction began (before parsing).
+     *  @returns The start-of-construction timestamp as a number.
+     */
     get create_start_time(): number;
+    /** Schedule an automatic transition to `next_state` after `after_time`
+     *  milliseconds.  Only one timeout may be active at a time.
+     *  @param next_state - The state to transition to when the timer fires.
+     *  @param after_time - Delay in milliseconds.
+     *  @throws {JssmError} If a timeout is already pending.
+     */
     set_state_timeout(next_state: StateType, after_time: number): void;
+    /** Cancel any pending state timeout.  Safe to call when no timeout is active.
+     */
     clear_state_timeout(): void;
+    /** Get the configured `after` timeout for a given state, if any.
+     *  @param which_state - The state to look up.
+     *  @returns A `[targetState, delayMs]` tuple, or `undefined` if no timeout
+     *  is configured for that state.
+     */
     state_timeout_for(which_state: StateType): [StateType, number] | undefined;
+    /** Get the configured `after` timeout for the current state, if any.
+     *  @returns A `[targetState, delayMs]` tuple, or `undefined`.
+     */
     current_state_timeout(): [StateType, number] | undefined;
+    /** Convenience method to create a new machine from a tagged template literal.
+     *  Equivalent to calling the top-level `sm` function.
+     *  @param template_strings - The template string array.
+     *  @param remainder        - Interpolated values.
+     *  @returns A new {@link Machine} instance.
+     */
     sm(template_strings: TemplateStringsArray, ...remainder: any[]): Machine<mDT>;
 }
 /*********
@@ -1738,9 +2737,158 @@ declare function sm<mDT>(template_strings: TemplateStringsArray, ...remainder: a
  *
  */
 declare function from<mDT>(MachineAsString: string, ExtraConstructorFields?: Partial<JssmGenericConfig<StateType, mDT>> | undefined): Machine<mDT>;
+/**
+ *
+ *  Type guard that narrows an unknown value to a {@link HookComplexResult}.
+ *
+ *  A hook complex result is an object with at minimum a boolean `pass` field,
+ *  and may optionally also carry replacement `data` / `next_data` fields that
+ *  the machine should adopt if the hook passes.  This helper is used by the
+ *  hook-dispatch machinery to tell "hook returned a complex object" from
+ *  "hook returned a bare boolean / null / undefined".
+ *
+ *  ```typescript
+ *  is_hook_complex_result({ pass: true });                 // true
+ *  is_hook_complex_result({ pass: false, data: { x: 1 }}); // true
+ *  is_hook_complex_result(true);                           // false
+ *  is_hook_complex_result(null);                           // false
+ *  is_hook_complex_result({ other: 'thing' });             // false
+ *  ```
+ *
+ *  @typeparam mDT The type of the machine data member; usually omitted.
+ *
+ *  @param hr The value to test.
+ *
+ *  @returns `true` if `hr` is a non-null object with a boolean `pass` field;
+ *  `false` otherwise.  When `true`, TypeScript narrows `hr` to
+ *  `HookComplexResult<mDT>`.
+ *
+ */
 declare function is_hook_complex_result<mDT>(hr: unknown): hr is HookComplexResult<mDT>;
+/**
+ *
+ *  Normalize any legal hook return value to a single "did it reject?" boolean.
+ *
+ *  Hooks in jssm may return any of the following to indicate success:
+ *  `true`, `undefined`, or a complex result whose `pass` field is `true`.
+ *  They may return any of the following to indicate rejection:
+ *  `false`, or a complex result whose `pass` field is `false`.  This helper
+ *  collapses all of those shapes into one boolean so callers don't have to
+ *  re-implement the matrix.
+ *
+ *  ```typescript
+ *  is_hook_rejection(true);            // false (pass)
+ *  is_hook_rejection(undefined);       // false (pass)
+ *  is_hook_rejection(false);           // true  (reject)
+ *  is_hook_rejection({ pass: true });  // false (pass)
+ *  is_hook_rejection({ pass: false }); // true  (reject)
+ *  ```
+ *
+ *  @typeparam mDT The type of the machine data member; usually omitted.
+ *
+ *  @param hr A hook result of any legal shape.
+ *
+ *  @returns `true` if the hook rejected the transition; `false` if it passed.
+ *
+ *  @throws {TypeError} If `hr` is not a recognized hook result shape (for
+ *  example, a number or a plain object without a `pass` field).
+ *
+ */
 declare function is_hook_rejection<mDT>(hr: HookResult<mDT>): boolean;
+/**
+ *
+ *  Invoke an optional transition/action hook and normalize its return value
+ *  into a {@link HookComplexResult}.
+ *
+ *  This is the central adapter the transition pipeline uses to run every
+ *  non-"everything" hook kind (basic, named, entry, exit, after, action, etc).
+ *  It accepts `undefined` for the hook slot because most hooks are not set on
+ *  most machines; when no hook is installed the step is a no-op pass.
+ *
+ *  The valid return shapes from a hook and their normalized meanings are:
+ *  - `undefined` → `{ pass: true }`
+ *  - `true`      → `{ pass: true }`
+ *  - `false`     → `{ pass: false }`
+ *  - `null`      → `{ pass: false }`
+ *  - a complex result object → returned as-is
+ *
+ *  Anything else is a programmer error and throws.
+ *
+ *  @typeparam mDT The type of the machine data member; usually omitted.
+ *
+ *  @param maybe_hook The hook handler to call, or `undefined` for the
+ *  "no hook installed" case.
+ *
+ *  @param hook_args The context object passed to the hook.  Includes the
+ *  current and proposed state, current and proposed data, action name, and
+ *  transition kind.
+ *
+ *  @returns A {@link HookComplexResult} describing whether the hook passed
+ *  and, optionally, any data replacements it requested.
+ *
+ *  @throws {TypeError} If the hook returns a value that is not one of the
+ *  legal shapes listed above.
+ *
+ *  @internal
+ *
+ */
 declare function abstract_hook_step<mDT>(maybe_hook: HookHandler<mDT> | undefined, hook_args: HookContext<mDT>): HookComplexResult<mDT>;
+/**
+ *
+ *  Invoke an optional "everything" hook and normalize its return value into
+ *  a {@link HookComplexResult}.
+ *
+ *  Mechanically identical to {@link abstract_hook_step}, but typed for the
+ *  everything-hook family (`pre_everything_hook` and `everything_hook`),
+ *  whose context object carries an extra `hook_name` field identifying which
+ *  bracket of the pipeline is firing.  Separated from `abstract_hook_step`
+ *  so TypeScript can enforce that the hook handler and the context object
+ *  agree on shape.
+ *
+ *  The valid return shapes and their meanings are the same as for
+ *  `abstract_hook_step`:
+ *  - `undefined` or `true` → `{ pass: true }`
+ *  - `false` or `null`     → `{ pass: false }`
+ *  - a complex result      → returned as-is
+ *
+ *  @typeparam mDT The type of the machine data member; usually omitted.
+ *
+ *  @param maybe_hook The everything-hook handler, or `undefined` when none
+ *  is installed.
+ *
+ *  @param hook_args The everything-hook context object.  Differs from a
+ *  normal hook context in that it also includes `hook_name`.
+ *
+ *  @returns A {@link HookComplexResult} describing whether the hook passed
+ *  and any data replacements it requested.
+ *
+ *  @throws {TypeError} If the hook returns a value outside the legal shapes.
+ *
+ *  @internal
+ *
+ */
+declare function abstract_everything_hook_step<mDT>(maybe_hook: EverythingHookHandler<mDT> | undefined, hook_args: EverythingHookContext<mDT>): HookComplexResult<mDT>;
+/**
+ * Deserializes a previously serialized machine state.
+ *
+ * This function recreates a machine from a serialization object, restoring its
+ * state, data, and history. For security and compatibility reasons, it will
+ * refuse to deserialize data from future versions of the library.
+ *
+ * @typeparam mDT - The type of the machine data member
+ *
+ * @param {string} machine_string - The FSL string defining the machine structure
+ * @param {JssmSerialization<mDT>} ser - The serialization object to restore from
+ *
+ * @returns {Machine<mDT>} - The restored machine instance
+ *
+ * @throws {Error} If the serialization is from a future version
+ *
+ * @example
+ * const machine = jssm.from("a -> b;");
+ * const serialized = machine.serialize();
+ * const restored = jssm.deserialize("a -> b;", serialized);
+ */
 declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
 
-export { FslDirections, Machine, abstract_hook_step, arrow_direction, arrow_left_kind, arrow_right_kind, build_time, compile, jssm_constants_d as constants, deserialize, find_repeated, from, gviz_shapes, histograph, is_hook_complex_result, is_hook_rejection, make, named_colors, wrap_parse as parse, seq, shapes, sleep, sm, state_style_condense, transfer_state_properties, unique, version, weighted_histo_key, weighted_rand_select, weighted_sample_select };
+export { FslDirections, Machine, abstract_everything_hook_step, abstract_hook_step, arrow_direction, arrow_left_kind, arrow_right_kind, build_time, compile, jssm_constants_d as constants, deserialize, find_repeated, from, gen_splitmix32, gviz_shapes, histograph, is_hook_complex_result, is_hook_rejection, make, named_colors, wrap_parse as parse, seq, shapes, sleep, sm, state_style_condense, transfer_state_properties, unique, version, weighted_histo_key, weighted_rand_select, weighted_sample_select };