jssm 5.153.0 → 5.154.0

package/dist/wc/instance.js

@@ -1090,6 +1090,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.
  */
@@ -1967,6 +1968,7 @@ class FslInstance extends LitElement {
       ${docked ? '' : html `<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>
     `;
     }

package/dist/wc/widgets.define.js

@@ -1,4 +1,4 @@
-import { FslToolbar, FslActions, FslFooter, FslHelp, FslHistory, FslDataInspector, FslHookLog, FslSimulation, FslExport } from './widgets.js';
+import { FslToolbar, FslActions, FslFooter, FslHelp, FslHistory, FslDataInspector, FslHookLog, FslSimulation, FslExport, FslStochastic } from './widgets.js';
 export * from './widgets.js';
 
 /**
@@ -50,7 +50,7 @@ function define_canonical(canonical_tag, CanonicalClass) {
 
 /**
  * Bundle entry: registers the entire light fsl-* widget suite (toolbar, actions,
- * footer, help, history, data-inspector, hook-log, simulation, export) in one import.
+ * footer, help, history, data-inspector, hook-log, simulation, export, stochastic) in one import.
  * Canonical `fsl-*` tags only — no deprecated `jssm-*` synonyms. Registration
  * is idempotent, so this composes safely with the per-widget `*.define` modules.
  */
@@ -63,3 +63,4 @@ define_canonical('fsl-data-inspector', FslDataInspector);
 define_canonical('fsl-hook-log', FslHookLog);
 define_canonical('fsl-simulation', FslSimulation);
 define_canonical('fsl-export', FslExport);
+define_canonical('fsl-stochastic', FslStochastic);

package/dist/wc/widgets.js

@@ -1,6 +1,7 @@
 import { css, html, LitElement } from 'lit';
 import { state, property } from 'lit/decorators.js';
 import { machine_to_dot, machine_to_svg_string } from 'jssm/viz';
+import { STOCHASTIC_DEFAULT_RUNS, STOCHASTIC_DEFAULT_MAX_STEPS, sm } from 'jssm';
 
 /**
  * Shared FSL appearance contract — the `--fsl-*` design-token vocabulary.
@@ -193,7 +194,7 @@ async function permalink_for(fsl, key = DEFAULT_PERMALINK_KEY, href = location.h
     return `${href.split('#')[0]}#${fragment}`;
 }
 
-var __decorate$7 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$8 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -496,23 +497,23 @@ FslToolbar.styles = css `
     .spacer { flex: 1; }
     ${fslTokens}
   `;
-__decorate$7([
+__decorate$8([
     state()
 ], FslToolbar.prototype, "_openMenu", void 0);
-__decorate$7([
+__decorate$8([
     state()
 ], FslToolbar.prototype, "_dest", void 0);
-__decorate$7([
+__decorate$8([
     property({ attribute: false })
 ], FslToolbar.prototype, "lastDirectory", void 0);
-__decorate$7([
+__decorate$8([
     property({ type: Boolean, attribute: 'no-validate' })
 ], FslToolbar.prototype, "noValidate", void 0);
-__decorate$7([
+__decorate$8([
     property({ type: Boolean, attribute: 'no-lint' })
 ], FslToolbar.prototype, "noLint", void 0);
 
-var __decorate$6 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$7 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -662,20 +663,20 @@ FslActions.styles = css `
     .empty { color: var(--_fsl-muted); font-style: italic; }
     ${fslTokens}
   `;
-__decorate$6([
+__decorate$7([
     state()
 ], FslActions.prototype, "_actions", void 0);
-__decorate$6([
+__decorate$7([
     state()
 ], FslActions.prototype, "_main", void 0);
-__decorate$6([
+__decorate$7([
     state()
 ], FslActions.prototype, "_regular", void 0);
-__decorate$6([
+__decorate$7([
     state()
 ], FslActions.prototype, "_forced", void 0);
 
-var __decorate$5 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$6 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -791,32 +792,32 @@ FslFooter.styles = css `
     .spacer { flex: 1; }
     ${fslTokens}
   `;
-__decorate$5([
+__decorate$6([
     state()
 ], FslFooter.prototype, "_state", void 0);
-__decorate$5([
+__decorate$6([
     state()
 ], FslFooter.prototype, "_actions", void 0);
-__decorate$5([
+__decorate$6([
     state()
 ], FslFooter.prototype, "_transitions", void 0);
-__decorate$5([
+__decorate$6([
     state()
 ], FslFooter.prototype, "_terminal", void 0);
-__decorate$5([
+__decorate$6([
     state()
 ], FslFooter.prototype, "_complete", void 0);
-__decorate$5([
+__decorate$6([
     state()
 ], FslFooter.prototype, "_gActions", void 0);
-__decorate$5([
+__decorate$6([
     state()
 ], FslFooter.prototype, "_gStarts", void 0);
-__decorate$5([
+__decorate$6([
     state()
 ], FslFooter.prototype, "_gTransitions", void 0);
 
-var __decorate$4 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$5 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -885,14 +886,14 @@ FslHelp.styles = css `
     .body { overflow-y: auto; padding: 0.5rem 0.9rem; font-size: 0.86rem; line-height: 1.5; }
     ${fslTokens}
   `;
-__decorate$4([
+__decorate$5([
     property({ type: Boolean, reflect: true })
 ], FslHelp.prototype, "open", void 0);
-__decorate$4([
+__decorate$5([
     property({ type: String })
 ], FslHelp.prototype, "heading", void 0);
 
-var __decorate$3 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$4 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -965,11 +966,11 @@ FslHistory.styles = css `
     .empty { color: var(--_fsl-muted); font-style: italic; padding: 0.5rem 0.7rem; }
     ${fslTokens}
   `;
-__decorate$3([
+__decorate$4([
     state()
 ], FslHistory.prototype, "_history", void 0);
 
-var __decorate$2 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$3 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -1089,11 +1090,11 @@ FslDataInspector.styles = css `
     .tok-bool, .tok-null { color: var(--fsl-color-json-atom, #c2185b); }
     ${fslTokens}
   `;
-__decorate$2([
+__decorate$3([
     state()
 ], FslDataInspector.prototype, "_data", void 0);
 
-var __decorate$1 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$2 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -1163,11 +1164,11 @@ FslHookLog.styles = css `
     .empty { color: var(--_fsl-muted); font-style: italic; }
     ${fslTokens}
   `;
-__decorate$1([
+__decorate$2([
     state()
 ], FslHookLog.prototype, "_log", void 0);
 
-var __decorate = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+var __decorate$1 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
@@ -1261,13 +1262,13 @@ FslSimulation.styles = css `
     .count.idle { font-style: italic; }
     ${fslTokens}
   `;
-__decorate([
+__decorate$1([
     property({ type: Number })
 ], FslSimulation.prototype, "interval", void 0);
-__decorate([
+__decorate$1([
     state()
 ], FslSimulation.prototype, "_running", void 0);
-__decorate([
+__decorate$1([
     state()
 ], FslSimulation.prototype, "_steps", void 0);
 
@@ -1334,4 +1335,300 @@ FslExport.styles = css `
     ${fslTokens}
   `;
 
-export { FslActions, FslDataInspector, FslExport, FslFooter, FslHelp, FslHistory, FslHookLog, FslSimulation, FslToolbar };
+var __decorate = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * `<fsl-stochastic>` — a statistical/Monte-Carlo explorer for a parent
+ * `<fsl-instance>` (fsl#1384).  Builds its own throwaway machine from the
+ * host's `.fsl` source (never touching the live machine) and renders
+ * aggregate run statistics in-panel.  Standalone (no host) the controls are
+ * disabled.
+ *
+ * @element fsl-stochastic
+ * @csspart controls - The control row.
+ * @fires fsl-stochastic-complete - CustomEvent<JssmStochasticSummary> after a run.
+ */
+class FslStochastic extends LitElement {
+    constructor() {
+        super(...arguments);
+        /** Run-count (montecarlo). Defaults from editor_config().stochastic_run_count. */
+        this.runs = STOCHASTIC_DEFAULT_RUNS;
+        /** Per-run step cap (montecarlo) / walk length (steady_state). */
+        this.maxSteps = STOCHASTIC_DEFAULT_MAX_STEPS;
+        /** Seed string ('' = time-based). Kept as string so the field can be blank. */
+        this.seed = '';
+        /** Run mode. */
+        this.mode = 'montecarlo';
+        this._summary = null;
+        this._error = null;
+        this._host = null;
+        this._playing = false;
+        /** Execute a batch synchronously and render the aggregates. */
+        this.run = () => {
+            if (this._host === null) {
+                return;
+            }
+            let machine;
+            try {
+                machine = sm `${this._host.fsl}`;
+            }
+            catch (_a) {
+                this._error = 'Cannot run on invalid FSL source.';
+                this._summary = null;
+                return;
+            }
+            this._error = null;
+            const seedNum = this.seed.trim() === '' ? undefined : Number(this.seed);
+            this._summary = machine.stochastic_summary({
+                mode: this.mode, runs: this.runs, max_steps: this.maxSteps, seed: seedNum,
+            });
+            this.dispatchEvent(new CustomEvent('fsl-stochastic-complete', {
+                detail: this._summary, bubbles: true, composed: true,
+            }));
+        };
+        /**
+         * Animate the batch: accumulate runs incrementally via `requestAnimationFrame`,
+         * redrawing as they land. Resolves when the batch completes or is paused-to-stop.
+         *
+         * Falls back to immediate (synchronous chunk) scheduling under jsdom where
+         * `requestAnimationFrame` is undefined.
+         *
+         * @example
+         * panel.runs = 100;
+         * await panel.play(); // resolves when all 100 runs are done
+         */
+        this.play = () => new Promise((resolve) => {
+            if (this._host === null) {
+                resolve();
+                return;
+            }
+            let machine;
+            try {
+                machine = sm `${this._host.fsl}`;
+            }
+            catch (_a) {
+                this._error = 'Cannot run on invalid FSL source.';
+                this._summary = null;
+                resolve();
+                return;
+            }
+            this._error = null;
+            if (this.seed.trim() !== '') {
+                machine.rng_seed = Number(this.seed);
+            }
+            const effective_seed = machine.rng_seed;
+            const state_visits = new Map();
+            const edges = new Map();
+            const path_lengths = [];
+            let reached = 0;
+            let capped = 0;
+            let runs = 0;
+            const iter = machine.stochastic_runs({ mode: this.mode, runs: this.runs, max_steps: this.maxSteps });
+            this._playing = true;
+            const CHUNK = 50;
+            const schedule = (fn) => {
+                if (typeof requestAnimationFrame === 'function') {
+                    requestAnimationFrame(fn);
+                }
+                else {
+                    fn();
+                }
+            };
+            const tick = () => {
+                var _a, _b;
+                if (!this._playing) {
+                    resolve();
+                    return;
+                }
+                for (let i = 0; i < CHUNK; i++) {
+                    const next = iter.next();
+                    if (next.done) {
+                        this._commit(state_visits, edges, path_lengths, reached, capped, runs, effective_seed);
+                        this._playing = false;
+                        resolve();
+                        return;
+                    }
+                    const r = next.value;
+                    runs += 1;
+                    for (const s of r.states) {
+                        state_visits.set(s, ((_a = state_visits.get(s)) !== null && _a !== void 0 ? _a : 0) + 1);
+                    }
+                    for (const e of r.edges) {
+                        edges.set(e, ((_b = edges.get(e)) !== null && _b !== void 0 ? _b : 0) + 1);
+                    }
+                    if (this.mode === 'montecarlo') {
+                        if (r.terminated) {
+                            reached += 1;
+                            path_lengths.push(r.length);
+                        }
+                        else {
+                            capped += 1;
+                        }
+                    }
+                }
+                this._commit(state_visits, edges, path_lengths, reached, capped, runs, effective_seed);
+                schedule(tick);
+            };
+            schedule(tick);
+        });
+        /** Toggle between playing and paused. Starts a new {@link play} batch when idle. */
+        this._togglePlay = () => { if (this._playing) {
+            this._playing = false;
+        }
+        else {
+            void this.play();
+        } };
+        this._onMode = (e) => { this.mode = e.target.value; };
+        this._onRuns = (e) => { this.runs = Number(e.target.value); };
+        this._onMax = (e) => { this.maxSteps = Number(e.target.value); };
+        this._onSeed = (e) => { this.seed = e.target.value; };
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this._host = closest_wc(this, 'instance');
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this._host = null;
+    }
+    /**
+     * Read `editor_config().stochastic_run_count` after the first render so the
+     * host's machine is guaranteed to be built (machine construction happens in
+     * the host's connectedCallback, which may fire after the panel's own
+     * connectedCallback in some environments).
+     */
+    firstUpdated(_changedProperties) {
+        var _a, _b, _c, _d;
+        super.firstUpdated(_changedProperties);
+        try {
+            const declared = (_d = (_c = (_b = (_a = this._host) === null || _a === void 0 ? void 0 : _a.machine) === null || _b === void 0 ? void 0 : _b.editor_config) === null || _c === void 0 ? void 0 : _c.call(_b)) === null || _d === void 0 ? void 0 : _d.stochastic_run_count;
+            if (typeof declared === 'number') {
+                this.runs = declared;
+            }
+        }
+        catch ( /* machine not ready — leave default */_e) { /* machine not ready — leave default */ }
+    }
+    /**
+     * Fold accumulated counters into a rendered summary. Shared by {@link play}
+     * for incremental rendering during animation.
+     *
+     * @param state_visits     - Accumulated visit counts per state name.
+     * @param edge_traversals  - Accumulated traversal counts per edge key.
+     * @param path_lengths     - Lengths of completed (terminated) paths.
+     * @param terminal_reached - Count of runs that reached a terminal state.
+     * @param capped           - Count of runs that hit the step cap.
+     * @param runs             - Total runs processed so far.
+     * @param seed             - The effective RNG seed used for this batch.
+     */
+    _commit(state_visits, edge_traversals, path_lengths, terminal_reached, capped, runs, seed) {
+        const total = [...state_visits.values()].reduce((a, b) => a + b, 0);
+        const frac = new Map();
+        for (const [s, c] of state_visits) {
+            frac.set(s, c / total);
+        }
+        const summary = {
+            mode: this.mode, runs, seed,
+            state_visits, state_visit_fraction: frac, edge_traversals,
+        };
+        if (this.mode === 'montecarlo') {
+            summary.path_lengths = path_lengths;
+            summary.terminal_reached = terminal_reached;
+            summary.capped = capped;
+        }
+        this._summary = summary;
+    }
+    _bars() {
+        const frac = this._summary.state_visit_fraction;
+        const rows = [...frac.entries()].sort((a, b) => b[1] - a[1]);
+        return html `${rows.map(([name, f]) => html `
+      <div class="bar-row">
+        <span>${name}</span>
+        <span class="track"><span class="bar" style="width:${(f * 100).toFixed(1)}%"></span></span>
+        <span>${(f * 100).toFixed(1)}%</span>
+      </div>`)}`;
+    }
+    _panes() {
+        const s = this._summary;
+        const mc = s.mode === 'montecarlo';
+        const reached = mc && s.runs > 0 ? Math.round((s.terminal_reached / s.runs) * 100) : 0;
+        const capped = mc && s.runs > 0 ? Math.round((s.capped / s.runs) * 100) : 0;
+        return html `
+      <div class="panes">
+        <div><strong>State visits</strong></div>
+        ${this._bars()}
+        ${mc ? html `<div>Reached terminal: ${reached}% · Hit cap: ${capped}%</div>` : html `<div class="muted">steady-state distribution</div>`}
+      </div>`;
+    }
+    render() {
+        const disabled = this._host === null;
+        return html `
+      <div class="controls" part="controls">
+        <select @change=${this._onMode} .value=${this.mode}>
+          <option value="montecarlo">Monte Carlo</option>
+          <option value="steady_state">Steady-state</option>
+        </select>
+        ${this.mode === 'montecarlo'
+            ? html `<label>runs <input type="number" .value=${String(this.runs)} @change=${this._onRuns}></label>`
+            : ''}
+        <label>max steps <input type="number" .value=${String(this.maxSteps)} @change=${this._onMax}></label>
+        <label>seed <input type="text" .value=${this.seed} @change=${this._onSeed}></label>
+        <button class="run" ?disabled=${disabled} @click=${this.run}>Run</button>
+        <button class="btn" ?disabled=${disabled} @click=${this._togglePlay}>${this._playing ? 'Pause' : 'Play'}</button>
+      </div>
+      ${this._error ? html `<div class="error">${this._error}</div>` : ''}
+      ${this._summary && !this._error ? this._panes() : html `<div class="panes muted">No run yet.</div>`}`;
+    }
+}
+FslStochastic.styles = css `
+    :host { display: block; font: 0.8rem var(--_fsl-font); color: var(--_fsl-text); }
+    .controls {
+      display: flex; align-items: center; gap: 0.5rem; flex-wrap: wrap;
+      padding: 0.4rem 0.6rem; background: var(--_fsl-surface);
+      border-top: 1px solid var(--_fsl-border);
+    }
+    .btn, .run {
+      height: 1.8rem; padding: 0 0.7rem; cursor: pointer; border-radius: 4px;
+      border: 1px solid var(--_fsl-border); background: var(--_fsl-surface);
+      color: var(--_fsl-text); font: 600 0.8rem var(--_fsl-font);
+    }
+    .btn:disabled, .run:disabled { opacity: 0.5; cursor: not-allowed; }
+    input { width: 4.5rem; height: 1.6rem; background: var(--_fsl-surface);
+            color: var(--_fsl-text); border: 1px solid var(--_fsl-border); border-radius: 4px; }
+    .panes { padding: 0.4rem 0.6rem; display: grid; gap: 0.5rem; }
+    .bar-row { display: grid; grid-template-columns: 4rem 1fr 3rem; align-items: center; gap: 0.4rem; }
+    .track { background: color-mix(in srgb, var(--_fsl-text) 8%, var(--_fsl-surface)); border-radius: 3px; height: 0.9rem; }
+    .bar { background: var(--_fsl-accent); height: 0.9rem; border-radius: 3px; }
+    .muted { color: var(--_fsl-muted); }
+    .error { color: var(--_fsl-danger, #c0392b); padding: 0.4rem 0.6rem; }
+    ${fslTokens}
+  `;
+__decorate([
+    property({ type: Number })
+], FslStochastic.prototype, "runs", void 0);
+__decorate([
+    property({ type: Number })
+], FslStochastic.prototype, "maxSteps", void 0);
+__decorate([
+    property({ type: String })
+], FslStochastic.prototype, "seed", void 0);
+__decorate([
+    property({ type: String })
+], FslStochastic.prototype, "mode", void 0);
+__decorate([
+    state()
+], FslStochastic.prototype, "_summary", void 0);
+__decorate([
+    state()
+], FslStochastic.prototype, "_error", void 0);
+__decorate([
+    state()
+], FslStochastic.prototype, "_host", void 0);
+__decorate([
+    state()
+], FslStochastic.prototype, "_playing", void 0);
+
+export { FslActions, FslDataInspector, FslExport, FslFooter, FslHelp, FslHistory, FslHookLog, FslSimulation, FslStochastic, FslToolbar };

package/jssm.es5.d.cts

@@ -524,6 +524,34 @@ declare type JssmEditorConfig = {
     stochastic_run_count?: number;
     panels?: Array<string>;
 };
+/** Which stochastic view a run batch produces. */
+declare type JssmStochasticMode = 'montecarlo' | 'steady_state';
+/** Options for {@link Machine.stochastic_summary} / {@link Machine.stochastic_runs}. */
+declare type JssmStochasticOptions = {
+    mode?: JssmStochasticMode;
+    runs?: number;
+    max_steps?: number;
+    seed?: number;
+};
+/** One walk's result, yielded by {@link Machine.stochastic_runs}. */
+declare type JssmStochasticRun = {
+    states: Array<string>;
+    edges: Array<string>;
+    length: number;
+    terminated: boolean;
+};
+/** Aggregate statistics over a stochastic run batch. */
+declare type JssmStochasticSummary = {
+    mode: JssmStochasticMode;
+    runs: number;
+    seed: number;
+    state_visits: Map<string, number>;
+    state_visit_fraction: Map<string, number>;
+    edge_traversals: Map<string, number>;
+    path_lengths?: Array<number>;
+    terminal_reached?: number;
+    capped?: number;
+};
 declare type JssmGenericConfig<StateType, DataType> = {
     graph_layout?: JssmLayout;
     complete?: Array<StateType>;
@@ -1991,6 +2019,10 @@ declare function transfer_state_properties(state_decl: JssmStateDeclaration): Js
  *
  */
 declare function state_style_condense(jssk: JssmStateStyleKeyList, machine?: any): JssmStateConfig;
+/** Default number of independent Monte-Carlo runs when none is declared. */
+declare const STOCHASTIC_DEFAULT_RUNS = 1000;
+/** Default per-run step cap (montecarlo) / walk length (steady_state). */
+declare const STOCHASTIC_DEFAULT_MAX_STEPS = 1000;
 declare class Machine<mDT> {
     _state: StateType;
     _states: Map<StateType, JssmGenericState>;
@@ -2919,6 +2951,65 @@ declare class Machine<mDT> {
      *  @returns A `Map` from state name to visit count.
      */
     probabilistic_histo_walk(n: number): Map<StateType, number>;
+    /** 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.
+     */
+    private _stochastic_one_walk;
+    /** 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?: JssmStochasticOptions): Generator<JssmStochasticRun>;
+    /** 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?: JssmStochasticOptions): JssmStochasticSummary;
     /********
      *
      *  List all actions available from this state.  Please note that the order of
@@ -4691,4 +4782,4 @@ declare function compareVersions(v1: string, v2: string): number;
  */
 declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
 
-export { FslDirections, Machine, abstract_everything_hook_step, abstract_hook_step, action_label_chars, arrow_direction, arrow_left_kind, arrow_right_kind, build_time, compareVersions, compile, jssm_constants_d as constants, deserialize, find_repeated, from, fslCompletions, fslDiagnostics, fslSemanticSpans, gen_splitmix32, gviz_shapes, histograph, is_hook_complex_result, is_hook_rejection, make, named_colors, wrap_parse as parse, seq, shapes, sleep, sm, state_name_chars, state_name_first_chars, state_style_condense, transfer_state_properties, unique, version, weighted_histo_key, weighted_rand_select, weighted_sample_select };
+export { FslDirections, Machine, STOCHASTIC_DEFAULT_MAX_STEPS, STOCHASTIC_DEFAULT_RUNS, abstract_everything_hook_step, abstract_hook_step, action_label_chars, arrow_direction, arrow_left_kind, arrow_right_kind, build_time, compareVersions, compile, jssm_constants_d as constants, deserialize, find_repeated, from, fslCompletions, fslDiagnostics, fslSemanticSpans, gen_splitmix32, gviz_shapes, histograph, is_hook_complex_result, is_hook_rejection, make, named_colors, wrap_parse as parse, seq, shapes, sleep, sm, state_name_chars, state_name_first_chars, state_style_condense, transfer_state_properties, unique, version, weighted_histo_key, weighted_rand_select, weighted_sample_select };