jssm 5.153.0 → 5.155.0

package/README.md

@@ -18,10 +18,10 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.153.0 at 6/28/2026, 6:29:10 PM
+* Generated for version 5.155.0 at 6/28/2026, 7:41:44 PM
 
 -->
-# jssm 5.153.0
+# jssm 5.155.0
 
 [**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
 [Documentation](https://stonecypher.github.io/jssm/docs/) ·
@@ -312,7 +312,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.**  7,769 tests at 100.0% line coverage
+  library.**  7,811 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.
@@ -445,11 +445,11 @@ If your contribution is missing here, please open an issue.
 
 <br/>
 
-***7,769 tests***, run 82,415 times.
+***7,811 tests***, run 82,853 times.
 
-- 7,015 specs with 100.0% coverage
-- 754 fuzz tests with 55.5% coverage
-- 9,374 TypeScript lines - 0.8 tests per line, 8.8 generated tests per line
+- 7,053 specs with 100.0% coverage
+- 758 fuzz tests with 54.8% coverage
+- 9,666 TypeScript lines - 0.8 tests per line, 8.6 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/custom-elements.json

@@ -444,7 +444,7 @@
           "kind": "variable",
           "name": "FSL_COLOR_KEYS",
           "default": "new Set([ 'color', 'text-color', 'background-color', 'border-color', 'edge-color', ])",
-          "description": "Attribute keys whose value is a color, mirroring the editor's `COLOR_KEYS`\n(language_service). The value token following one of these (plus its `:`) is\ntagged `color` and rendered with a swatch, matching the editor overlay."
+          "description": "Attribute keys whose value is a color, mirroring the editor's `COLOR_KEYS`\r\n(language_service). The value token following one of these (plus its `:`) is\r\ntagged `color` and rendered with a swatch, matching the editor overlay."
         },
         {
           "kind": "function",
@@ -462,7 +462,7 @@
               }
             }
           ],
-          "description": "Tokenize FSL source into `{cls, text}` runs for syntax highlighting. A pure,\nregex-driven scanner — never parses, so it cannot throw on malformed input.\n`cls` is null for uncategorized text (punctuation, identifiers, whitespace).\n\nBeyond the lexical classes it tracks one bit of structural context: an\nidentifier immediately before a `:` is retro-tagged `key` (an attribute key,\nunless it is already a `keyword`), and the value token after a color key's\ncolon — or any hex literal — is tagged `color`. The context never spans a\n`;`, so a value can't leak past its statement."
+          "description": "Tokenize FSL source into `{cls, text}` runs for syntax highlighting. A pure,\r\nregex-driven scanner — never parses, so it cannot throw on malformed input.\r\n`cls` is null for uncategorized text (punctuation, identifiers, whitespace).\r\n\r\nBeyond the lexical classes it tracks one bit of structural context: an\r\nidentifier immediately before a `:` is retro-tagged `key` (an attribute key,\r\nunless it is already a `keyword`), and the value token after a color key's\r\ncolon — or any hex literal — is tagged `color`. The context never spans a\r\n`;`, so a value can't leak past its statement."
         },
         {
           "kind": "function",
@@ -480,7 +480,7 @@
               }
             }
           ],
-          "description": "Highlight FSL source to an HTML string of `<span class=\"fsl-tok-…\">` runs.\nA `color` token is preceded by an inline `<span class=\"fsl-swatch\">` whose\nbackground is the literal color text (a CSS-valid named color or hex), giving\nthe docs the same swatch the editor overlay shows. Color text is a hex or\nidentifier run, so it is a safe `background:` value."
+          "description": "Highlight FSL source to an HTML string of `<span class=\"fsl-tok-…\">` runs.\r\nA `color` token is preceded by an inline `<span class=\"fsl-swatch\">` whose\r\nbackground is the literal color text (a CSS-valid named color or hex), giving\r\nthe docs the same swatch the editor overlay shows. Color text is a hex or\r\nidentifier run, so it is a safe `background:` value."
         },
         {
           "kind": "function",
@@ -558,7 +558,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<fsl-docs>` — the language-docs content engine: drill-in nav over the bundled\ncurriculum (Getting Started / About State Machines / Tutorials / Example\nMachines / Index / Search), a markdown page renderer, and \"load into editor\"\nfor tagged FSL examples. Content-only; slot it into `<fsl-help>`.",
+          "description": "`<fsl-docs>` — the language-docs content engine: drill-in nav over the bundled\r\ncurriculum (Getting Started / About State Machines / Tutorials / Example\r\nMachines / Index / Search), a markdown page renderer, and \"load into editor\"\r\nfor tagged FSL examples. Content-only; slot it into `<fsl-help>`.",
           "name": "FslDocs",
           "members": [
             {
@@ -2138,6 +2138,10 @@
               "description": "Slot for the random-walk simulation (`<fsl-simulation>`, #668).",
               "name": "simulation"
             },
+            {
+              "description": "Slot for the stochastic analysis panel (`<fsl-stochastic>`, fsl#1384).",
+              "name": "stochastic"
+            },
             {
               "description": "Slot for the export menu (`<fsl-export>`, #667).",
               "name": "export"
@@ -3653,6 +3657,280 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/ts/wc/fsl_stochastic_wc.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "`<fsl-stochastic>` — a statistical/Monte-Carlo explorer for a parent\r\n`<fsl-instance>` (fsl#1384).  Builds its own throwaway machine from the\r\nhost's `.fsl` source (never touching the live machine) and renders\r\naggregate run statistics in-panel.  Standalone (no host) the controls are\r\ndisabled.",
+          "name": "FslStochastic",
+          "cssParts": [
+            {
+              "description": "The control row.",
+              "name": "controls"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "runs",
+              "default": "STOCHASTIC_DEFAULT_RUNS",
+              "description": "Run-count (montecarlo). Defaults from editor_config().stochastic_run_count.",
+              "attribute": "runs"
+            },
+            {
+              "kind": "field",
+              "name": "maxSteps",
+              "default": "STOCHASTIC_DEFAULT_MAX_STEPS",
+              "description": "Per-run step cap (montecarlo) / walk length (steady_state).",
+              "attribute": "maxSteps"
+            },
+            {
+              "kind": "field",
+              "name": "seed",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "Seed string ('' = time-based). Kept as string so the field can be blank.",
+              "attribute": "seed"
+            },
+            {
+              "kind": "field",
+              "name": "mode",
+              "type": {
+                "text": "JssmStochasticMode"
+              },
+              "default": "'montecarlo'",
+              "description": "Run mode.",
+              "attribute": "mode"
+            },
+            {
+              "kind": "field",
+              "name": "_summary",
+              "type": {
+                "text": "JssmStochasticSummary | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_error",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_host",
+              "type": {
+                "text": "StochHost | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_playing",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "run",
+              "description": "Execute a batch synchronously and render the aggregates."
+            },
+            {
+              "kind": "field",
+              "name": "play",
+              "description": "Animate the batch: accumulate runs incrementally via `requestAnimationFrame`,\r\nredrawing as they land. Resolves when the batch completes or is paused-to-stop.\r\n\r\nFalls back to immediate (synchronous chunk) scheduling under jsdom where\r\n`requestAnimationFrame` is undefined."
+            },
+            {
+              "kind": "method",
+              "name": "_commit",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "state_visits",
+                  "type": {
+                    "text": "Map<string, number>"
+                  },
+                  "description": "Accumulated visit counts per state name."
+                },
+                {
+                  "name": "edge_traversals",
+                  "type": {
+                    "text": "Map<string, number>"
+                  },
+                  "description": "Accumulated traversal counts per edge key."
+                },
+                {
+                  "name": "path_lengths",
+                  "type": {
+                    "text": "number[]"
+                  },
+                  "description": "Lengths of completed (terminated) paths."
+                },
+                {
+                  "name": "terminal_reached",
+                  "type": {
+                    "text": "number"
+                  },
+                  "description": "Count of runs that reached a terminal state."
+                },
+                {
+                  "name": "capped",
+                  "type": {
+                    "text": "number"
+                  },
+                  "description": "Count of runs that hit the step cap."
+                },
+                {
+                  "name": "runs",
+                  "type": {
+                    "text": "number"
+                  },
+                  "description": "Total runs processed so far."
+                },
+                {
+                  "name": "seed",
+                  "type": {
+                    "text": "number"
+                  },
+                  "description": "The effective RNG seed used for this batch."
+                }
+              ],
+              "description": "Fold accumulated counters into a rendered summary. Shared by play\r\nfor incremental rendering during animation."
+            },
+            {
+              "kind": "field",
+              "name": "_togglePlay",
+              "privacy": "private",
+              "description": "Toggle between playing and paused. Starts a new play batch when idle."
+            },
+            {
+              "kind": "field",
+              "name": "_onMode",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_onRuns",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_onMax",
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_onSeed",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_bars",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_panes",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              }
+            }
+          ],
+          "events": [
+            {
+              "description": "CustomEvent<JssmStochasticSummary> after a run.",
+              "name": "fsl-stochastic-complete"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "runs",
+              "default": "STOCHASTIC_DEFAULT_RUNS",
+              "description": "Run-count (montecarlo). Defaults from editor_config().stochastic_run_count.",
+              "fieldName": "runs"
+            },
+            {
+              "name": "maxSteps",
+              "default": "STOCHASTIC_DEFAULT_MAX_STEPS",
+              "description": "Per-run step cap (montecarlo) / walk length (steady_state).",
+              "fieldName": "maxSteps"
+            },
+            {
+              "name": "seed",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "Seed string ('' = time-based). Kept as string so the field can be blank.",
+              "fieldName": "seed"
+            },
+            {
+              "name": "mode",
+              "type": {
+                "text": "JssmStochasticMode"
+              },
+              "default": "'montecarlo'",
+              "description": "Run mode.",
+              "fieldName": "mode"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "fsl-stochastic",
+          "customElement": true
+        },
+        {
+          "kind": "variable",
+          "name": "state_visits",
+          "default": "new Map<string, number>()"
+        },
+        {
+          "kind": "variable",
+          "name": "runs",
+          "type": {
+            "text": "number"
+          },
+          "default": "0"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "FslStochastic",
+          "declaration": {
+            "name": "FslStochastic",
+            "module": "src/ts/wc/fsl_stochastic_wc.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/ts/wc/fsl_themes.ts",
@@ -4603,6 +4881,14 @@
             "name": "FslExport",
             "module": "./fsl_export_wc.js"
           }
+        },
+        {
+          "kind": "js",
+          "name": "FslStochastic",
+          "declaration": {
+            "name": "FslStochastic",
+            "module": "./fsl_stochastic_wc.js"
+          }
         }
       ]
     }

package/dist/cdn/instance.js

@@ -23563,7 +23563,7 @@ var constants = /*#__PURE__*/Object.freeze({
  *  Useful for runtime diagnostics and for embedding in serialized machine
  *  snapshots so that deserializers can detect version-skew.
  */
-const version = "5.153.0";
+const version = "5.155.0";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -23878,6 +23878,10 @@ function find_connected_components(states, edges) {
     }
     return result;
 }
+/** Default number of independent Monte-Carlo runs when none is declared. */
+const STOCHASTIC_DEFAULT_RUNS = 1000;
+/** Default per-run step cap (montecarlo) / walk length (steady_state). */
+const STOCHASTIC_DEFAULT_MAX_STEPS = 1000;
 class Machine {
     // whargarbl this badly needs to be broken up, monolith master
     constructor({ start_states, end_states = [], failed_outputs = [], initial_state, start_states_no_enforce, complete = [], transitions, machine_author, machine_comment, machine_contributor, machine_definition, machine_language, machine_license, machine_name, machine_version, npm_name, default_size, state_declaration, property_definition, state_property, fsl_version, dot_preamble = undefined, arrange_declaration = [], arrange_start_declaration = [], arrange_end_declaration = [], oarrange_declaration = [], farrange_declaration = [], theme = ['default'], flow = 'down', graph_layout = 'dot', instance_name, history, boundary_depth_limit, data, default_state_config, default_active_state_config, default_hooked_state_config, default_terminal_state_config, default_start_state_config, default_end_state_config, default_transition_config, default_graph_config, group_registry, group_metadata, group_hooks, state_hooks, allows_override, config_allows_override, allow_islands, editor_config, rng_seed, time_source, timeout_source, clear_timeout_source }) {
@@ -25394,6 +25398,147 @@ class Machine {
     probabilistic_histo_walk(n) {
         return histograph(this.probabilistic_walk(n));
     }
+    /** One non-destructive weighted-random walk over the graph from `start`.
+     *
+     *  Reads the graph and advances the PRNG only — it never calls
+     *  {@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.
+     *
+     *  @param start - State to begin the walk from.
+     *  @param max_steps - Maximum transitions before the walk is step-capped.
+     *  @returns The {@link JssmStochasticRun} for this walk.
+     */
+    _stochastic_one_walk(start, max_steps) {
+        const states = [start];
+        const edges = [];
+        let cur = start;
+        let terminated = false;
+        for (let step = 0; step < max_steps; step++) {
+            const exits = this.probable_exits_for(cur);
+            if (exits.length === 0) {
+                terminated = true;
+                break;
+            }
+            const selected = weighted_rand_select(exits, undefined, this._rng);
+            edges.push(`${cur}→${selected.to}`);
+            cur = selected.to;
+            states.push(cur);
+        }
+        return { states, edges, length: states.length - 1, terminated };
+    }
+    /** Lazily yield one {@link JssmStochasticRun} at a time.
+     *
+     *  In `montecarlo` mode (default) yields `runs` independent walks from the
+     *  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.
+     *
+     *  Passing `seed` reseeds the machine for reproducible runs.  Unlike
+     *  {@link Machine.stochastic_summary}, the generator does NOT restore the
+     *  prior seed afterward — a direct caller's machine is left reseeded.
+     *
+     *  @param opts - {@link JssmStochasticOptions}.
+     *  @returns A generator of per-run results.
+     *
+     *  @example
+     *  const m = sm`a 'go' -> b 'go' -> c;`;
+     *  [...m.stochastic_runs({ runs: 2, seed: 1 })].length;  // => 2
+     */
+    *stochastic_runs(opts = {}) {
+        var _a, _b, _c, _d, _e;
+        if (opts.seed !== undefined) {
+            this.rng_seed = opts.seed;
+        }
+        const mode = (_a = opts.mode) !== null && _a !== void 0 ? _a : 'montecarlo';
+        const max_steps = (_b = opts.max_steps) !== null && _b !== void 0 ? _b : STOCHASTIC_DEFAULT_MAX_STEPS;
+        const runs = (mode === 'steady_state')
+            ? 1
+            : ((_e = (_c = opts.runs) !== null && _c !== void 0 ? _c : (_d = this.editor_config()) === null || _d === void 0 ? void 0 : _d.stochastic_run_count) !== null && _e !== void 0 ? _e : STOCHASTIC_DEFAULT_RUNS);
+        const start = this.state();
+        for (let i = 0; i < runs; i++) {
+            yield this._stochastic_one_walk(start, max_steps);
+        }
+    }
+    /** Run many weighted-random walks and return aggregate statistics.
+     *
+     *  Honors `%` transition probabilities (via the existing probabilistic
+     *  machinery).  Non-destructive: the machine's current state and
+     *  {@link Machine.rng_seed} are restored before returning, so calling this
+     *  never perturbs the live machine.  `montecarlo` mode (default) reports
+     *  per-run `path_lengths`, `terminal_reached`, and `capped`; `steady_state`
+     *  mode runs one long walk and omits those fields.
+     *
+     *  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
+     *  machine's declared `editor: { stochastic_run_count }` (fsl#1334) when
+     *  present, otherwise {@link STOCHASTIC_DEFAULT_RUNS}.
+     *  @returns A {@link JssmStochasticSummary}.
+     *
+     *  @see Machine.stochastic_runs
+     *  @see Machine.probabilistic_walk
+     *  @see Machine.editor_config
+     *
+     *  @example
+     *  const m = sm`a 'go' -> b 'go' -> c;`;
+     *  const s = m.stochastic_summary({ runs: 100, seed: 1 });
+     *  s.terminal_reached;  // => 100
+     */
+    stochastic_summary(opts = {}) {
+        var _a, _b, _c;
+        const mode = (_a = opts.mode) !== null && _a !== void 0 ? _a : 'montecarlo';
+        const saved_seed = this._rng_seed;
+        if (opts.seed !== undefined) {
+            this.rng_seed = opts.seed;
+        }
+        const effective_seed = this._rng_seed;
+        const state_visits = new Map();
+        const edge_traversals = new Map();
+        const path_lengths = [];
+        let terminal_reached = 0, capped = 0, runs = 0;
+        try {
+            for (const run of this.stochastic_runs(Object.assign(Object.assign({}, opts), { mode }))) {
+                runs += 1;
+                for (const s of run.states) {
+                    state_visits.set(s, ((_b = state_visits.get(s)) !== null && _b !== void 0 ? _b : 0) + 1);
+                }
+                for (const e of run.edges) {
+                    edge_traversals.set(e, ((_c = edge_traversals.get(e)) !== null && _c !== void 0 ? _c : 0) + 1);
+                }
+                if (mode === 'montecarlo') {
+                    if (run.terminated) {
+                        terminal_reached += 1;
+                        path_lengths.push(run.length);
+                    }
+                    else {
+                        capped += 1;
+                    }
+                }
+            }
+        }
+        finally {
+            // restore the PRNG so the call is non-destructive even when the loop throws
+            this.rng_seed = saved_seed;
+        }
+        const total_visits = [...state_visits.values()].reduce((a, b) => a + b, 0);
+        const state_visit_fraction = new Map();
+        for (const [s, c] of state_visits) {
+            state_visit_fraction.set(s, c / total_visits);
+        }
+        const summary = {
+            mode, runs, seed: effective_seed,
+            state_visits, state_visit_fraction, edge_traversals,
+        };
+        if (mode === 'montecarlo') {
+            summary.path_lengths = path_lengths;
+            summary.terminal_reached = terminal_reached;
+            summary.capped = capped;
+        }
+        return summary;
+    }
     /********
      *
      *  List all actions available from this state.  Please note that the order of
@@ -29860,6 +30005,7 @@ function split_ratio(coord, start, size) {
  * @slot hook-log - Slot for the hook-firing log (`<fsl-hook-log>`, #664).
  * @slot effective-properties - Slot for the resolved-properties panel (`<fsl-effective-properties>`, #665).
  * @slot simulation - Slot for the random-walk simulation (`<fsl-simulation>`, #668).
+ * @slot stochastic - Slot for the stochastic analysis panel (`<fsl-stochastic>`, fsl#1384).
  * @slot export - Slot for the export menu (`<fsl-export>`, #667).
  * @slot footer - Footer slot.
  */
@@ -30737,6 +30883,7 @@ class FslInstance extends i {
       ${docked ? '' : b `<section class="hook-log" ?hidden=${h('hook-log')}><slot name="hook-log"></slot></section>`}
       <section class="effective-properties" ?hidden=${h('effective-properties')}><slot name="effective-properties"></slot></section>
       <section class="simulation" ?hidden=${h('simulation')}><slot name="simulation"></slot></section>
+      <section class="stochastic" ?hidden=${h('stochastic')}><slot name="stochastic"></slot></section>
       <section class="export" ?hidden=${h('export')}><slot name="export"></slot></section>
     `;
     }