jssm 5.113.0 → 5.119.0

package/dist/wc/viz.define.js

@@ -0,0 +1,6 @@
+import { JssmViz } from './viz.js';
+export { JssmViz } from './viz.js';
+
+if (!customElements.get('jssm-viz')) {
+    customElements.define('jssm-viz', JssmViz);
+}

package/dist/wc/viz.js

@@ -0,0 +1,135 @@
+import { css, LitElement, html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { fsl_to_svg_string } from 'jssm/viz';
+
+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;
+};
+/**
+ * Normalize an arbitrary thrown value into a {@link JssmVizErrorDetail}.
+ * Accepts anything (Error instances, JssmErrors with `.location`, plain
+ * strings, etc.) and always produces a string `message`.
+ *
+ * ```typescript
+ * normalize_viz_error(new Error('boom'));
+ * // => { message: 'boom', location: undefined }
+ *
+ * normalize_viz_error({ message: 'parse failed', location: { line: 1 } });
+ * // => { message: 'parse failed', location: { line: 1 } }
+ *
+ * normalize_viz_error('bare string failure');
+ * // => { message: 'bare string failure', location: undefined }
+ * ```
+ *
+ * @param e The thrown value to normalize.
+ * @returns A `{ message, location }` object suitable for use as the
+ * `detail` of a `viz-error` `CustomEvent`.
+ */
+function normalize_viz_error(e) {
+    if (typeof e === 'object' && e !== null) {
+        const rec = e;
+        const raw_message = rec.message;
+        const message = (typeof raw_message === 'string' && raw_message.length > 0)
+            ? raw_message
+            : String(e);
+        return { message, location: rec.location };
+    }
+    return { message: String(e), location: undefined };
+}
+/**
+ * Web component that renders a jssm machine as inline SVG.
+ *
+ * @element jssm-viz
+ * @cssproperty [--jssm-viz-min-height=100px] - Minimum height of the rendered SVG container.
+ * @fires {CustomEvent<{ message: string; location?: unknown }>} viz-error - Fires when the FSL source fails to parse or render.
+ */
+class JssmViz extends LitElement {
+    constructor() {
+        super(...arguments);
+        /** FSL source to render. */
+        this.fsl = '';
+        /** Optional Graphviz layout engine override (e.g. 'dot', 'neato'). */
+        this.engine = undefined;
+        this._svg = '';
+    }
+    /**
+     * Lit lifecycle hook. Triggers an async SVG render whenever `fsl` or
+     * `engine` change.
+     *
+     * @param changed - Map of changed reactive properties supplied by Lit.
+     */
+    willUpdate(changed) {
+        if (changed.has('fsl') || changed.has('engine')) {
+            this._renderSvg();
+        }
+    }
+    /**
+     * Render the current `fsl` source to an SVG string via the headless
+     * `fsl_to_svg_string` pipeline. Updates `_svg` on success; emits a
+     * `viz-error` `CustomEvent` on failure. Guards against stale results
+     * when `fsl` changes mid-flight.
+     *
+     * @returns A promise that resolves once the render attempt has finished.
+     */
+    async _renderSvg() {
+        const source = this.fsl;
+        if (!source) {
+            this._svg = '';
+            return;
+        }
+        try {
+            const result = await fsl_to_svg_string(source, this.engine ? { engine: this.engine } : undefined);
+            // Guard against stale results: only commit if fsl has not changed since this render started.
+            if (this.fsl === source) {
+                this._svg = result;
+            }
+        }
+        catch (e) {
+            this._svg = '';
+            this.dispatchEvent(new CustomEvent('viz-error', {
+                detail: normalize_viz_error(e),
+                bubbles: true,
+                composed: true,
+            }));
+        }
+    }
+    /**
+     * Lit render method. Injects the most recent SVG string into the shadow
+     * tree via the `unsafeHTML` directive.
+     *
+     * SVG content originates from `@viz-js/viz` (Graphviz WASM), which emits
+     * sanitized SVG. `unsafeHTML` is required because Lit's template-literal
+     * interpolation otherwise escapes the markup as text. The directive name
+     * makes the trust boundary explicit at the call site.
+     *
+     * @returns A Lit `TemplateResult` wrapping the SVG in a `.container` div.
+     */
+    render() {
+        return html `<div class="container">${unsafeHTML(this._svg)}</div>`;
+    }
+}
+JssmViz.styles = css `
+    :host {
+      display: block;
+      min-height: var(--jssm-viz-min-height, 100px);
+    }
+    .container {
+      width: 100%;
+      height: 100%;
+    }
+  `;
+__decorate([
+    property({ type: String })
+], JssmViz.prototype, "fsl", void 0);
+__decorate([
+    property({ type: String })
+], JssmViz.prototype, "engine", void 0);
+__decorate([
+    state()
+], JssmViz.prototype, "_svg", void 0);
+
+export { JssmViz, normalize_viz_error };

package/jssm.es5.d.cts

@@ -973,6 +973,63 @@ declare const shapes$1: string[];
  *
  */
 declare const named_colors$1: string[];
+/*******
+ *
+ *  Character ranges accepted by the FSL grammar for identifier and label
+ *  tokens.  Each entry is an inclusive `{from, to}` range of single Unicode
+ *  characters.  Single-character entries (e.g. `.`) appear with `from === to`.
+ *
+ *  These are intended for tooling, validators, and editors that need to know
+ *  which characters are legal in a given FSL token position without re-parsing
+ *  the PEG grammar.
+ *
+ */
+/**
+ *  Inclusive character ranges accepted by `AtomLetter` — i.e., the characters
+ *  legal in any but the first position of an FSL state name (atom).
+ *
+ *  Includes ASCII digits/letters and the symbols
+ *  `.`, `+`, `_`, `^`, `(`, `)`, `*`, `&`, `$`, `#`, `@`, `!`, `?`, `,`,
+ *  plus the high-Unicode range `U+0080`–`U+FFFF`.
+ *
+ *  @example
+ *  state_name_chars.some(r => 'A' >= r.from && 'A' <= r.to);  // true
+ */
+declare const state_name_chars$1: ReadonlyArray<{
+    from: string;
+    to: string;
+}>;
+/**
+ *  Inclusive character ranges accepted by `AtomFirstLetter` — i.e., the
+ *  characters legal in the first position of an FSL state name (atom).
+ *
+ *  Notably narrower than {@link state_name_chars}: omits `+`, `(`, `)`, `&`,
+ *  `#`, `@`.  Includes ASCII digits/letters, `.`, `_`, `!`, `$`, `^`, `*`,
+ *  `?`, `,`, and the high-Unicode range `U+0080`–`U+FFFF`.
+ *
+ *  @example
+ *  state_name_first_chars.some(r => '+' >= r.from && '+' <= r.to);  // false
+ */
+declare const state_name_first_chars$1: ReadonlyArray<{
+    from: string;
+    to: string;
+}>;
+/**
+ *  Inclusive character ranges accepted by `ActionLabelUnescaped` — i.e., the
+ *  characters legal inside a single-quoted action label without escaping.
+ *  Space (`U+0020`) is included; the apostrophe `'` (`U+0027`) is explicitly
+ *  excluded since it terminates the label.
+ *
+ *  Three ranges: `U+0020`–`U+0026`, `U+0028`–`U+005B`, `U+005D`–`U+FFFF`.
+ *
+ *  @example
+ *  action_label_chars.some(r => ' ' >= r.from && ' ' <= r.to);   // true
+ *  action_label_chars.some(r => "'" >= r.from && "'" <= r.to);   // false
+ */
+declare const action_label_chars$1: ReadonlyArray<{
+    from: string;
+    to: string;
+}>;
 
 declare const jssm_constants_d_E: typeof E;
 declare const jssm_constants_d_Epsilon: typeof Epsilon;
@@ -1010,13 +1067,27 @@ declare namespace jssm_constants_d {
     jssm_constants_d_PosInfinity as PosInfinity,
     jssm_constants_d_Root2 as Root2,
     jssm_constants_d_RootHalf as RootHalf,
+    action_label_chars$1 as action_label_chars,
     gviz_shapes$1 as gviz_shapes,
     named_colors$1 as named_colors,
     shapes$1 as shapes,
+    state_name_chars$1 as state_name_chars,
+    state_name_first_chars$1 as state_name_first_chars,
   };
 }
 
+/**
+ *  The published semantic version of the jssm package this build was cut from.
+ *  Mirrored from `package.json` by `src/buildjs/makever.cjs` at build time.
+ *  Useful for runtime diagnostics and for embedding in serialized machine
+ *  snapshots so that deserializers can detect version-skew.
+ */
 declare const version: string;
+/**
+ *  The Unix epoch timestamp (in milliseconds) at which this build was produced,
+ *  written by `src/buildjs/makever.cjs`.  Useful for distinguishing builds
+ *  with the same `version` string during development, and for diagnostic logs.
+ */
 declare const build_time: number;
 
 declare type StateType = string;
@@ -1024,6 +1095,18 @@ declare type StateType = string;
 declare const shapes: string[];
 declare const gviz_shapes: string[];
 declare const named_colors: string[];
+declare const state_name_chars: readonly {
+    from: string;
+    to: string;
+}[];
+declare const state_name_first_chars: readonly {
+    from: string;
+    to: string;
+}[];
+declare const action_label_chars: readonly {
+    from: string;
+    to: string;
+}[];
 
 /*********
  *
@@ -1704,6 +1787,49 @@ declare class Machine<mDT> {
      *  @returns An array of theme name strings.
      */
     all_themes(): FslTheme[];
+    /** List the character ranges accepted by the FSL grammar in any but the
+     *  first position of a state name (atom).  Each entry is an inclusive
+     *  `{from, to}` range of single Unicode characters.
+     *
+     *  @returns An array of `{from, to}` inclusive character ranges.
+     *
+     *  @example
+     *  const m = sm`a -> b;`;
+     *  m.all_state_name_chars().some(r => '+' >= r.from && '+' <= r.to);  // true
+     */
+    all_state_name_chars(): ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
+    /** List the character ranges accepted by the FSL grammar in the first
+     *  position of a state name (atom).  Narrower than
+     *  {@link all_state_name_chars}: notably omits `+`, `(`, `)`, `&`, `#`, `@`.
+     *
+     *  @returns An array of `{from, to}` inclusive character ranges.
+     *
+     *  @example
+     *  const m = sm`a -> b;`;
+     *  m.all_state_name_first_chars().some(r => '+' >= r.from && '+' <= r.to);  // false
+     */
+    all_state_name_first_chars(): ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
+    /** List the character ranges accepted inside a single-quoted FSL action
+     *  label without escaping.  Space is allowed; the apostrophe `'` is
+     *  explicitly excluded since it terminates the label.
+     *
+     *  @returns An array of `{from, to}` inclusive character ranges.
+     *
+     *  @example
+     *  const m = sm`a -> b;`;
+     *  m.all_action_label_chars().some(r => ' ' >= r.from && ' ' <= r.to);   // true
+     *  m.all_action_label_chars().some(r => "'" >= r.from && "'" <= r.to);   // false
+     */
+    all_action_label_chars(): ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
     /** 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.
@@ -1797,10 +1923,23 @@ 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.
+    /** Get the transitions available from a state for use by the probabilistic
+     *  walk system.
+     *
+     *  If any exit declares a `probability`, only those probability-bearing
+     *  exits are returned, so that non-probability peers cannot dilute the
+     *  declared distribution.  If no exit declares a `probability`, every
+     *  legal (non-forced) exit is returned, which `weighted_rand_select`
+     *  treats as equal weight.  Forced-only exits (`~>`) are always excluded,
+     *  since they cannot be taken by an ordinary `transition()` call.
+     *
+     *  Fixes StoneCypher/fsl#1325, in which the function previously returned
+     *  every exit unconditionally — including forced-only exits and exits
+     *  with no `probability`, which distorted the weighted distribution.
+     *
      *  @param whichState - The state to inspect.
-     *  @returns An array of {@link JssmTransition} edges exiting the state.
+     *  @returns An array of {@link JssmTransition} edges exiting the state,
+     *  filtered as described above.  May be empty.
      *  @throws {JssmError} If the state does not exist.
      */
     probable_exits_for(whichState: StateType): Array<JssmTransition<StateType, mDT>>;
@@ -2891,4 +3030,4 @@ declare function abstract_everything_hook_step<mDT>(maybe_hook: EverythingHookHa
  */
 declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
 
-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 };
+export { FslDirections, Machine, abstract_everything_hook_step, abstract_hook_step, action_label_chars, 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_name_chars, state_name_first_chars, state_style_condense, transfer_state_properties, unique, version, weighted_histo_key, weighted_rand_select, weighted_sample_select };

package/jssm.es6.d.ts

@@ -973,6 +973,63 @@ declare const shapes$1: string[];
  *
  */
 declare const named_colors$1: string[];
+/*******
+ *
+ *  Character ranges accepted by the FSL grammar for identifier and label
+ *  tokens.  Each entry is an inclusive `{from, to}` range of single Unicode
+ *  characters.  Single-character entries (e.g. `.`) appear with `from === to`.
+ *
+ *  These are intended for tooling, validators, and editors that need to know
+ *  which characters are legal in a given FSL token position without re-parsing
+ *  the PEG grammar.
+ *
+ */
+/**
+ *  Inclusive character ranges accepted by `AtomLetter` — i.e., the characters
+ *  legal in any but the first position of an FSL state name (atom).
+ *
+ *  Includes ASCII digits/letters and the symbols
+ *  `.`, `+`, `_`, `^`, `(`, `)`, `*`, `&`, `$`, `#`, `@`, `!`, `?`, `,`,
+ *  plus the high-Unicode range `U+0080`–`U+FFFF`.
+ *
+ *  @example
+ *  state_name_chars.some(r => 'A' >= r.from && 'A' <= r.to);  // true
+ */
+declare const state_name_chars$1: ReadonlyArray<{
+    from: string;
+    to: string;
+}>;
+/**
+ *  Inclusive character ranges accepted by `AtomFirstLetter` — i.e., the
+ *  characters legal in the first position of an FSL state name (atom).
+ *
+ *  Notably narrower than {@link state_name_chars}: omits `+`, `(`, `)`, `&`,
+ *  `#`, `@`.  Includes ASCII digits/letters, `.`, `_`, `!`, `$`, `^`, `*`,
+ *  `?`, `,`, and the high-Unicode range `U+0080`–`U+FFFF`.
+ *
+ *  @example
+ *  state_name_first_chars.some(r => '+' >= r.from && '+' <= r.to);  // false
+ */
+declare const state_name_first_chars$1: ReadonlyArray<{
+    from: string;
+    to: string;
+}>;
+/**
+ *  Inclusive character ranges accepted by `ActionLabelUnescaped` — i.e., the
+ *  characters legal inside a single-quoted action label without escaping.
+ *  Space (`U+0020`) is included; the apostrophe `'` (`U+0027`) is explicitly
+ *  excluded since it terminates the label.
+ *
+ *  Three ranges: `U+0020`–`U+0026`, `U+0028`–`U+005B`, `U+005D`–`U+FFFF`.
+ *
+ *  @example
+ *  action_label_chars.some(r => ' ' >= r.from && ' ' <= r.to);   // true
+ *  action_label_chars.some(r => "'" >= r.from && "'" <= r.to);   // false
+ */
+declare const action_label_chars$1: ReadonlyArray<{
+    from: string;
+    to: string;
+}>;
 
 declare const jssm_constants_d_E: typeof E;
 declare const jssm_constants_d_Epsilon: typeof Epsilon;
@@ -1010,13 +1067,27 @@ declare namespace jssm_constants_d {
     jssm_constants_d_PosInfinity as PosInfinity,
     jssm_constants_d_Root2 as Root2,
     jssm_constants_d_RootHalf as RootHalf,
+    action_label_chars$1 as action_label_chars,
     gviz_shapes$1 as gviz_shapes,
     named_colors$1 as named_colors,
     shapes$1 as shapes,
+    state_name_chars$1 as state_name_chars,
+    state_name_first_chars$1 as state_name_first_chars,
   };
 }
 
+/**
+ *  The published semantic version of the jssm package this build was cut from.
+ *  Mirrored from `package.json` by `src/buildjs/makever.cjs` at build time.
+ *  Useful for runtime diagnostics and for embedding in serialized machine
+ *  snapshots so that deserializers can detect version-skew.
+ */
 declare const version: string;
+/**
+ *  The Unix epoch timestamp (in milliseconds) at which this build was produced,
+ *  written by `src/buildjs/makever.cjs`.  Useful for distinguishing builds
+ *  with the same `version` string during development, and for diagnostic logs.
+ */
 declare const build_time: number;
 
 declare type StateType = string;
@@ -1024,6 +1095,18 @@ declare type StateType = string;
 declare const shapes: string[];
 declare const gviz_shapes: string[];
 declare const named_colors: string[];
+declare const state_name_chars: readonly {
+    from: string;
+    to: string;
+}[];
+declare const state_name_first_chars: readonly {
+    from: string;
+    to: string;
+}[];
+declare const action_label_chars: readonly {
+    from: string;
+    to: string;
+}[];
 
 /*********
  *
@@ -1704,6 +1787,49 @@ declare class Machine<mDT> {
      *  @returns An array of theme name strings.
      */
     all_themes(): FslTheme[];
+    /** List the character ranges accepted by the FSL grammar in any but the
+     *  first position of a state name (atom).  Each entry is an inclusive
+     *  `{from, to}` range of single Unicode characters.
+     *
+     *  @returns An array of `{from, to}` inclusive character ranges.
+     *
+     *  @example
+     *  const m = sm`a -> b;`;
+     *  m.all_state_name_chars().some(r => '+' >= r.from && '+' <= r.to);  // true
+     */
+    all_state_name_chars(): ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
+    /** List the character ranges accepted by the FSL grammar in the first
+     *  position of a state name (atom).  Narrower than
+     *  {@link all_state_name_chars}: notably omits `+`, `(`, `)`, `&`, `#`, `@`.
+     *
+     *  @returns An array of `{from, to}` inclusive character ranges.
+     *
+     *  @example
+     *  const m = sm`a -> b;`;
+     *  m.all_state_name_first_chars().some(r => '+' >= r.from && '+' <= r.to);  // false
+     */
+    all_state_name_first_chars(): ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
+    /** List the character ranges accepted inside a single-quoted FSL action
+     *  label without escaping.  Space is allowed; the apostrophe `'` is
+     *  explicitly excluded since it terminates the label.
+     *
+     *  @returns An array of `{from, to}` inclusive character ranges.
+     *
+     *  @example
+     *  const m = sm`a -> b;`;
+     *  m.all_action_label_chars().some(r => ' ' >= r.from && ' ' <= r.to);   // true
+     *  m.all_action_label_chars().some(r => "'" >= r.from && "'" <= r.to);   // false
+     */
+    all_action_label_chars(): ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
     /** 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.
@@ -1797,10 +1923,23 @@ 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.
+    /** Get the transitions available from a state for use by the probabilistic
+     *  walk system.
+     *
+     *  If any exit declares a `probability`, only those probability-bearing
+     *  exits are returned, so that non-probability peers cannot dilute the
+     *  declared distribution.  If no exit declares a `probability`, every
+     *  legal (non-forced) exit is returned, which `weighted_rand_select`
+     *  treats as equal weight.  Forced-only exits (`~>`) are always excluded,
+     *  since they cannot be taken by an ordinary `transition()` call.
+     *
+     *  Fixes StoneCypher/fsl#1325, in which the function previously returned
+     *  every exit unconditionally — including forced-only exits and exits
+     *  with no `probability`, which distorted the weighted distribution.
+     *
      *  @param whichState - The state to inspect.
-     *  @returns An array of {@link JssmTransition} edges exiting the state.
+     *  @returns An array of {@link JssmTransition} edges exiting the state,
+     *  filtered as described above.  May be empty.
      *  @throws {JssmError} If the state does not exist.
      */
     probable_exits_for(whichState: StateType): Array<JssmTransition<StateType, mDT>>;
@@ -2891,4 +3030,4 @@ declare function abstract_everything_hook_step<mDT>(maybe_hook: EverythingHookHa
  */
 declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
 
-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 };
+export { FslDirections, Machine, abstract_everything_hook_step, abstract_hook_step, action_label_chars, 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_name_chars, state_name_first_chars, state_style_condense, transfer_state_properties, unique, version, weighted_histo_key, weighted_rand_select, weighted_sample_select };