jssm 5.162.9 → 5.162.11

package/jssm_viz.es5.d.cts

@@ -69,6 +69,27 @@ type JssmDefaultSize = {
     width?: number;
     height?: number;
 };
+/**
+ *  A parsed semantic-version breakdown, as produced by the FSL parser for
+ *  version-valued directives (`machine_version`, `fsl_version`).  `major`,
+ *  `minor`, and `patch` are the three numeric components; `full` preserves
+ *  the exact source text of the version.  `loc` is present only when the
+ *  source was parsed with `{ locations: true }`.
+ *
+ *  ```typescript
+ *  const m = sm`machine_version: 1.2.3; a -> b;`;
+ *  m.machine_version();  // { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+ *  ```
+ *  @see Machine.machine_version
+ *  @see Machine.fsl_version
+ */
+type JssmParsedSemver = {
+    major: number;
+    minor: number;
+    patch: number;
+    full: string;
+    loc?: FslSourceLocation;
+};
 /**
  *  Runtime-iterable list of valid `flow` directions for FSL diagrams.
  *  Use this when you need to enumerate directions; for the type itself
@@ -559,10 +580,10 @@ type JssmGenericConfig<StateType, DataType> = {
     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;
     auto_api?: boolean | string;
     instance_name?: string | undefined;
     default_state_config?: JssmStateStyleKeyList;
@@ -1225,10 +1246,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;
@@ -1851,10 +1872,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.
@@ -1872,10 +1901,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,
@@ -2078,7 +2115,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[]);
     /**
@@ -2188,10 +2237,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;
     /**
@@ -2199,6 +2272,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>;
     /**
@@ -2206,6 +2281,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>;
     /**
@@ -2225,6 +2302,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;
     /**
@@ -3391,8 +3471,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`

package/jssm_viz.es6.d.ts

@@ -69,6 +69,27 @@ type JssmDefaultSize = {
     width?: number;
     height?: number;
 };
+/**
+ *  A parsed semantic-version breakdown, as produced by the FSL parser for
+ *  version-valued directives (`machine_version`, `fsl_version`).  `major`,
+ *  `minor`, and `patch` are the three numeric components; `full` preserves
+ *  the exact source text of the version.  `loc` is present only when the
+ *  source was parsed with `{ locations: true }`.
+ *
+ *  ```typescript
+ *  const m = sm`machine_version: 1.2.3; a -> b;`;
+ *  m.machine_version();  // { major: 1, minor: 2, patch: 3, full: '1.2.3' }
+ *  ```
+ *  @see Machine.machine_version
+ *  @see Machine.fsl_version
+ */
+type JssmParsedSemver = {
+    major: number;
+    minor: number;
+    patch: number;
+    full: string;
+    loc?: FslSourceLocation;
+};
 /**
  *  Runtime-iterable list of valid `flow` directions for FSL diagrams.
  *  Use this when you need to enumerate directions; for the type itself
@@ -559,10 +580,10 @@ type JssmGenericConfig<StateType, DataType> = {
     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;
     auto_api?: boolean | string;
     instance_name?: string | undefined;
     default_state_config?: JssmStateStyleKeyList;
@@ -1225,10 +1246,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;
@@ -1851,10 +1872,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.
@@ -1872,10 +1901,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,
@@ -2078,7 +2115,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[]);
     /**
@@ -2188,10 +2237,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;
     /**
@@ -2199,6 +2272,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>;
     /**
@@ -2206,6 +2281,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>;
     /**
@@ -2225,6 +2302,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;
     /**
@@ -3391,8 +3471,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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.162.9",
+  "version": "5.162.11",
   "engines": {
     "node": ">=10.0.0"
   },