jssm 5.162.10 → 5.162.12

package/dist/deno/README.md

@@ -18,10 +18,10 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.162.10 at 7/12/2026, 5:25:34 AM
+* Generated for version 5.162.12 at 7/12/2026, 10:09:04 AM
 
 -->
-# jssm 5.162.10
+# jssm 5.162.12
 
 [**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
 [Documentation](https://stonecypher.github.io/jssm/docs/) ·
@@ -333,7 +333,7 @@ That decision shows up everywhere downstream:
   or run `npm run benny` against your own machine.
 
 - **More thoroughly tested than any other JavaScript state-machine
-  library.**  8,475 tests at 100.0% line coverage
+  library.**  8,640 tests at 100.0% line coverage
   ([report](https://coveralls.io/github/StoneCypher/jssm)), plus
   fuzz testing via `fast-check`, with parser test data across ten natural
   languages and Emoji.
@@ -467,11 +467,11 @@ If your contribution is missing here, please open an issue.
 
 <br/>
 
-***8,475 tests***, run 83,913 times.
+***8,640 tests***, run 98,037 times.
 
-- 7,713 specs with 100.0% coverage
-- 762 fuzz tests with 47.9% coverage
-- 10,882 TypeScript lines - 0.8 tests per line, 7.7 generated tests per line
+- 7,737 specs with 100.0% coverage
+- 903 fuzz tests with 56.5% coverage
+- 10,946 TypeScript lines - 0.8 tests per line, 9.0 generated tests per line
 
 [![Actions Status](https://github.com/StoneCypher/jssm/workflows/Node%20CI/badge.svg)](https://github.com/StoneCypher/jssm/actions)
 [![NPM version](https://img.shields.io/npm/v/jssm.svg)](https://www.npmjs.com/package/jssm)

package/dist/deno/jssm.d.ts

@@ -1,6 +1,6 @@
 type StateType = string;
 import { JssmGenericState, JssmGenericConfig, JssmStateConfig, JssmTransition, JssmTransitionList, // JssmTransitionRule,
-JssmMachineInternalState, JssmAllowsOverride, JssmAllowIslands, JssmEditorConfig, JssmStochasticOptions, JssmStochasticRun, JssmStochasticSummary, JssmDefaultSize, JssmStateDeclaration, JssmStateStyleKeyList, JssmTransitionConfig, JssmGraphConfig, JssmLayout, JssmHistory, JssmSerialization, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, EverythingHookContext, EverythingHookHandler, PostEverythingHookHandler, HookPhase, HookRegistryEntry, HookQuery, JssmEventName, JssmEventFilter, JssmEventHandler, JssmUnsubscribe, JssmGroupRegistry, JssmGroupHooks, JssmStateHooks, JssmRng } from './jssm_types.js';
+JssmMachineInternalState, JssmAllowsOverride, JssmAllowIslands, JssmEditorConfig, JssmStochasticOptions, JssmStochasticRun, JssmStochasticSummary, JssmDefaultSize, JssmParsedSemver, JssmStateDeclaration, JssmStateStyleKeyList, JssmTransitionConfig, JssmGraphConfig, JssmLayout, JssmHistory, JssmSerialization, FslDirection, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, EverythingHookContext, EverythingHookHandler, PostEverythingHookHandler, HookPhase, HookRegistryEntry, HookQuery, JssmEventName, JssmEventFilter, JssmEventHandler, JssmUnsubscribe, JssmGroupRegistry, JssmGroupHooks, JssmStateHooks, JssmRng } from './jssm_types.js';
 import { Interner } from './jssm_intern.js';
 declare const shapes: string[], gviz_shapes: string[], named_colors: string[], state_name_chars: readonly {
     from: string;
@@ -58,10 +58,10 @@ declare class Machine<mDT> {
     _machine_language?: string;
     _machine_license?: string;
     _machine_name?: string;
-    _machine_version?: string;
+    _machine_version?: JssmParsedSemver;
     _npm_name?: string;
     _default_size?: JssmDefaultSize;
-    _fsl_version?: string;
+    _fsl_version?: JssmParsedSemver;
     _raw_state_declaration?: Array<object>;
     _state_declarations: Map<StateType, JssmStateDeclaration>;
     _data?: mDT;
@@ -684,10 +684,18 @@ declare class Machine<mDT> {
      */
     default_size(): JssmDefaultSize | undefined;
     /**
-     * Get the machine's version string.  Set via the FSL `machine_version` directive.
-     *  @returns The version string.
+     * Get the machine's declared version, parsed.  Set via the FSL
+     *  `machine_version` directive, which takes a semver triple; the parser
+     *  breaks it into numeric `major`/`minor`/`patch` fields and keeps the
+     *  exact source text in `full`.  Returns `undefined` when the directive
+     *  was not given.
+     *  @returns The parsed {@link JssmParsedSemver}, or `undefined` if unset.
+     *  @example
+     *    const m = sm`machine_version: 1.2.3; a -> b;`;
+     *    m.machine_version();  // => { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+     *  @see fsl_version
      */
-    machine_version(): string;
+    machine_version(): JssmParsedSemver | undefined;
     /**
      * Get the raw state declaration objects as parsed from the FSL source.
      *  @returns An array of raw state declaration objects.
@@ -705,10 +713,18 @@ declare class Machine<mDT> {
      */
     state_declarations(): Map<StateType, JssmStateDeclaration>;
     /**
-     * Get the FSL language version this machine was compiled under.
-     *  @returns The FSL version string.
+     * Get the FSL language version this machine declares, parsed.  Set via
+     *  the FSL `fsl_version` directive, which takes a semver triple; the
+     *  parser breaks it into numeric `major`/`minor`/`patch` fields and keeps
+     *  the exact source text in `full`.  Returns `undefined` when the
+     *  directive was not given.
+     *  @returns The parsed {@link JssmParsedSemver}, or `undefined` if unset.
+     *  @example
+     *    const m = sm`fsl_version: 1.0.0; a -> b;`;
+     *    m.fsl_version();  // => { major: 1, minor: 0, patch: 0, full: '1.0.0' }
+     *  @see machine_version
      */
-    fsl_version(): string;
+    fsl_version(): JssmParsedSemver | undefined;
     /**
      * Get the complete internal state of the machine as a serializable
      *  structure.  Includes actions, edges, edge map, named transitions,
@@ -911,7 +927,19 @@ declare class Machine<mDT> {
     get themes(): FslTheme | FslTheme[];
     /**
      * Set the active theme(s).  Accepts a single theme name or an array.
+     *  Also drops every memoized static state config, so styles resolved
+     *  before the change re-resolve under the new theme stack.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b;`;
+     *  m.style_for('b');                 // resolved under the default theme
+     *  m.themes = 'ocean';
+     *  m.style_for('b').backgroundColor; // 'cadetblue1' — ocean, not a stale default
+     *  ```
+     *
      *  @param to - A theme name or array of theme names to apply.
+     *
+     *  @see resolve_state_config
      */
     set themes(to: FslTheme | FslTheme[]);
     /**
@@ -1021,10 +1049,34 @@ declare class Machine<mDT> {
      *  @throws {JssmError} If the state does not exist.
      */
     probable_exits_for(whichState: StateType): Array<JssmTransition<StateType, mDT>>;
+    /**
+     * Guard for the random-selection paths ({@link Machine.probabilistic_transition},
+     *  {@link Machine.stochastic_runs}): rejects a candidate pool whose total
+     *  selectable weight is zero, because weighted selection over an all-zero
+     *  pool has no meaningful answer (StoneCypher/fsl#1248).  Undeclared
+     *  probabilities count as weight 1, matching {@link weighted_rand_select}.
+     *  An empty pool is not this guard's concern (terminality is handled by the
+     *  callers) and passes through untouched.
+     *
+     *  ```typescript
+     *  const m = sm`a 0% -> b; a 0% -> c;`;
+     *  m.probabilistic_transition();  // throws JssmError — every exit is 0%
+     *  ```
+     *  @param whichState - The state the pool exits from, named in the error.
+     *  @param exits - The candidate pool, as built by {@link Machine.probable_exits_for}.
+     *  @throws {JssmError} If the pool is non-empty and every candidate edge
+     *  has probability 0 — including the case where explicit `0%` edges
+     *  excluded their unweighted sibling edges from the candidate pool.
+     *  @see probable_exits_for
+     */
+    private _assert_selectable_exit_pool;
     /**
      * Take a single random transition from the current state, weighted by
      *  edge probabilities.
      *  @returns `true` if a transition was taken, `false` otherwise.
+     *  @throws {JssmError} If the candidate exit pool is non-empty but its
+     *  total weight is zero — every candidate declares `0%` — per
+     *  StoneCypher/fsl#1248.
      */
     probabilistic_transition(): boolean;
     /**
@@ -1032,6 +1084,8 @@ declare class Machine<mDT> {
      *  of states visited (before each transition).
      *  @param n - Number of steps to walk.
      *  @returns An array of state names visited during the walk.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight (StoneCypher/fsl#1248).
      */
     probabilistic_walk(n: number): Array<StateType>;
     /**
@@ -1039,6 +1093,8 @@ declare class Machine<mDT> {
      *  each state was visited.
      *  @param n - Number of steps to walk.
      *  @returns A `Map` from state name to visit count.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight (StoneCypher/fsl#1248).
      */
     probabilistic_histo_walk(n: number): Map<StateType, number>;
     /**
@@ -1048,6 +1104,12 @@ declare class Machine<mDT> {
      *  {@link Machine.transition}, so it fires no hooks, mutates no machine
      *  state, and touches no `data`.  A state with no probabilistic exits
      *  (a terminal, or a forced-only `~>` state) ends the walk.
+     *
+     *  Terminality is checked before the first transition and after every
+     *  transition.  A terminal start therefore completes with length zero even
+     *  when `max_steps` is zero, and a terminal reached on the final permitted
+     *  transition is completed rather than step-capped.
+     *
      *  @param start - State to begin the walk from.
      *  @param max_steps - Maximum transitions before the walk is step-capped.
      *  @param exit_memo - Per-run-set cache of {@link Machine.probable_exits_for}
@@ -1058,6 +1120,9 @@ declare class Machine<mDT> {
      *    the derived arrays — RNG draw order is untouched, so seeded walks
      *    reproduce exactly.
      *  @returns The {@link JssmStochasticRun} for this walk.
+     *  @throws {JssmError} If a visited state's candidate exit pool is
+     *  non-empty but all-zero-weight — see
+     *  {@link Machine._assert_selectable_exit_pool} (StoneCypher/fsl#1248).
      */
     private _stochastic_one_walk;
     /**
@@ -1067,7 +1132,9 @@ declare class Machine<mDT> {
      *  current state, each ending at a terminal or after `max_steps`.  In
      *  `steady_state` mode yields exactly one walk of `max_steps` steps.  This
      *  is the lazy engine behind {@link Machine.stochastic_summary}; the
-     *  fsl-stochastic panel drives it across animation frames.
+     *  fsl-stochastic panel drives it across animation frames.  A walk already
+     *  at a terminal is reported as terminated with length zero, including when
+     *  `max_steps` is zero.
      *
      *  Passing `seed` reseeds the machine for reproducible runs.  Unlike
      *  {@link Machine.stochastic_summary}, the generator does NOT restore the
@@ -1090,6 +1157,10 @@ declare class Machine<mDT> {
      *  per-run `path_lengths`, `terminal_reached`, and `capped`; `steady_state`
      *  mode runs one long walk and omits those fields.
      *
+     *  Monte-Carlo runs count as `terminal_reached` when they start at a
+     *  terminal or reach one on the final permitted transition.  Terminal
+     *  starts contribute zero to `path_lengths`, even when `max_steps` is zero.
+     *
      *  Timing (`after`) decorations and data-guard conditions are not modeled
      *  by this sampler; it walks the probabilistic graph topology.
      *  @param opts - {@link JssmStochasticOptions}.  `runs` defaults to the
@@ -2224,8 +2295,12 @@ declare class Machine<mDT> {
      *  For any state OTHER than the current one, this returns the memoized static
      *  resolution (tiers 1–5; see `_compose_state_config`) — theme →
      *  `default_state_config` → per-kind defaults → depth-ordered group metadata →
-     *  per-state config.  The cache is keyed by state and never invalidated, since
-     *  those tiers do not depend on which state is current.
+     *  per-state config.  The cache is keyed by state; those tiers do not depend
+     *  on which state is current, so it survives transitions, but the mutable
+     *  cascade inputs each clear it when they change — hook registration and
+     *  removal ({@link Machine.set_hook}, {@link Machine.remove_hook}; the
+     *  hooked layer) and theme assignment (the `themes` setter; tier 1 and the
+     *  per-kind theme layers).
      *
      *  For the machine's CURRENTLY-occupied state the result is recomputed each
      *  call (never cached) and additionally carries the dynamic `active_state`