jssm 5.162.13 → 5.162.16

package/dist/deno/jssm_types.d.ts

@@ -38,12 +38,18 @@ type JssmPermitted = 'required' | 'disallowed';
  */
 type JssmPermittedOpt = 'required' | 'disallowed' | 'optional';
 /**
- *  The set of ASCII arrow tokens recognized by the FSL grammar.  Each arrow
- *  encodes a direction (one-way left/right, or two-way) and a "kind" for
+ *  Every arrow token recognized by the FSL grammar — all 42 spellings.  Each
+ *  arrow encodes a direction (one-way left/right, or two-way) and a "kind" for
  *  each direction (`-` legal, `=` main path, `~` forced-only).  See the
  *  Language Reference docs for the full semantic table.
+ *
+ *  Every arrow has an ASCII spelling and a unicode spelling, and each half of a
+ *  two-way arrow may be spelled independently, so the two-way arrows also have
+ *  mixed ASCII/unicode spellings (`←=>`, `<-⇒`, and so on).  All of them are
+ *  accepted, by the grammar and by {@link arrow_direction},
+ *  {@link arrow_left_kind}, and {@link arrow_right_kind}.
  */
-type JssmArrow = '->' | '<-' | '<->' | '<=->' | '<~->' | '=>' | '<=' | '<=>' | '<-=>' | '<~=>' | '~>' | '<~' | '<~>' | '<-~>' | '<=~>';
+type JssmArrow = '->' | '→' | '=>' | '⇒' | '~>' | '↛' | '<-' | '←' | '<=' | '⇐' | '<~' | '↚' | '<->' | '↔' | '<=>' | '⇔' | '<~>' | '↮' | '<-=>' | '←⇒' | '←=>' | '<-⇒' | '<-~>' | '←↛' | '←~>' | '<-↛' | '<=->' | '⇐→' | '⇐->' | '<=→' | '<=~>' | '⇐↛' | '⇐~>' | '<=↛' | '<~->' | '↚→' | '↚->' | '<~→' | '<~=>' | '↚⇒' | '↚=>' | '<~⇒';
 /**
  * A type teaching Typescript the various supported shapes for nodes, mostly inherited from GraphViz
  */
@@ -786,8 +792,22 @@ type JssmGenericConfig<StateType, DataType> = {
     state_hooks?: JssmStateHooks;
     rng_seed?: number | undefined;
     time_source?: () => number;
-    timeout_source?: (Function: any, number: any) => number;
-    clear_timeout_source?: (number: any) => void;
+    /**
+     *  Schedules `fn` to run after `delay_ms`, and returns a handle that will be
+     *  handed back to `clear_timeout_source` untouched.  Defaults to `setTimeout`.
+     *
+     *  The handle is typed `number` — the browser shape.  Node's `setTimeout`
+     *  returns a `Timeout` object instead, so a Node-shaped source casts it (as
+     *  jssm's own `DEFAULT_TIMEOUT_SOURCE` does); jssm never inspects the handle,
+     *  it only stores it and gives it back.
+     *
+     *  (Before 5.162.14 these read `(Function, number) => number`, in which
+     *  `Function` and `number` were *parameter names*, not types — so both
+     *  parameters were silently `any`.)
+     */
+    timeout_source?: (fn: () => void, delay_ms: number) => number;
+    /** Cancels a timer previously scheduled by `timeout_source`.  Defaults to `clearTimeout`. */
+    clear_timeout_source?: (handle: number) => void;
 };
 /**
  *  Internal compiler intermediate: a single aggregated rule produced while
@@ -810,7 +830,15 @@ type JssmCompileRule<StateType> = {
 type JssmCompileSe<StateType, mDT> = {
     to: StateType;
     se?: JssmCompileSe<StateType, mDT>;
-    kind: JssmArrow;
+    /**
+     *  The arrow token as the parser emitted it.  Deliberately `string` and not
+     *  {@link JssmArrow}: this internal intermediate flows through the whole
+     *  compiler, and threading a 42-member string-literal union through that much
+     *  control-flow analysis overflows `tsc`'s stack (it type-checks standalone
+     *  but dies under `npm run make`).  The value *is* a `JssmArrow` — the two
+     *  places that care re-assert it on the way into the arrow classifiers.
+     */
+    kind: string;
     l_action?: StateType;
     r_action?: StateType;
     l_probability: number;
@@ -1101,10 +1129,33 @@ type HookResult<mDT> = true | false | undefined | void | HookComplexResult<mDT>;
  *  the payload that will be committed if the transition is accepted —
  *  handlers may inspect or mutate the latter via a
  *  {@link HookComplexResult} return value.
+ *
+ *  The remaining fields describe the transition the hook is firing on.  They
+ *  are optional because a handler is not obliged to care about them, but the
+ *  transition path always supplies all of them; `action` is `undefined` when
+ *  the transition was not driven by an action.
  */
 type HookContext<mDT> = {
     data: mDT;
     next_data: mDT;
+    /** The state being left. */
+    from?: string;
+    /** The state being entered. */
+    to?: string;
+    /** The action that drove the transition, or `undefined` if none did. */
+    action?: string;
+    /** Whether this transition came from `force_transition` rather than `transition`. */
+    forced?: boolean;
+    /**
+     *  Which arrow kind the traversed edge carries — `legal`, `main`, or `forced`.
+     *
+     *  Populated **only when a transition-kind hook is installed** (a standard,
+     *  main, or forced transition hook, or their post- equivalents).  With no such
+     *  hook registered there is nothing to switch on, so jssm skips resolving the
+     *  edge's kind and this is `undefined`.  Install `hook_standard_transition`
+     *  (or a sibling) if a general handler needs to read it.
+     */
+    trans_type?: JssmArrowKind;
 };
 /**
  *  Context object passed to "everything" hooks ({@link EverythingHookHandler}

package/dist/deno/jssm_util.d.ts

@@ -63,7 +63,7 @@ declare const array_box_if_string: (n: any) => any;
  *  @throws {TypeError} If `options` is not a non-empty array of objects.
  *
  */
-declare const weighted_rand_select: (options: Array<any>, probability_property: string, rng: JssmRng) => any;
+declare const weighted_rand_select: (options: Array<any>, probability_property?: string, rng?: JssmRng) => any;
 /*******
  *
  *  Returns, for a non-negative integer argument `n`, the series `[0 .. n]`.

package/dist/fence/fence.js

@@ -22318,9 +22318,12 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
     if (to === '') {
         throw new JssmError(undefined, 'A state name may not be the empty string (transition target)');
     }
-    const kind = isRight
-        ? arrow_right_kind(this_se.kind)
-        : arrow_left_kind(this_se.kind), 
+    // `this_se.kind` is typed `string` rather than JssmArrow — see the field's own
+    // note in jssm_types.ts.  The classifiers reject anything that isn't a real
+    // arrow, so an unsound value throws here rather than passing silently.
+    const arrow = this_se.kind, kind = isRight
+        ? arrow_right_kind(arrow)
+        : arrow_left_kind(arrow), 
     // action and probability are pre-declared (as after_time always was)
     // so every compiled edge shares ONE hidden class regardless of which
     // optional fields its declaration carries.  The conditional assigns
@@ -24223,7 +24226,7 @@ function fslSemanticSpans(text) {
  *  Useful for runtime diagnostics and for embedding in serialized machine
  *  snapshots so that deserializers can detect version-skew.
  */
-const version = "5.162.13";
+const version = "5.162.16";
 
 /**
  *  The FSL Markdown fence convention parser — pure, host-agnostic logic that
@@ -27883,7 +27886,13 @@ class Machine {
      *
      */
     transition_impl(newStateOrAction, newData, wasForced, wasAction, dataProvided = newData !== undefined) {
-        let valid = false, trans_type, newState, newStateId = NaN, actionId = NaN, fromAction;
+        let valid = false, 
+        // deliberately `string`, not `JssmArrowKind`, though only arrow kinds are
+        // ever assigned: declaring this local as the 4-member union makes tsc's
+        // control-flow analysis narrow it across the whole of this (very large)
+        // function, which overflows the checker's stack under `npm run make`.
+        // The union is recovered at the hook boundary below -- see hook_args_obj.
+        trans_type, newState, newStateId = NaN, actionId = NaN, fromAction;
         if (wasForced) {
             // numeric inline of valid_force_transition: any existing edge
             // qualifies, forced or not.  one string probe (the user's target name)
@@ -27955,7 +27964,10 @@ class Machine {
                 to: newState,
                 next_data: newData,
                 forced: wasForced,
-                trans_type
+                // sound: the only values ever assigned to trans_type are an edge's
+                // `kind` and the literal 'forced'.  The local is typed `string` only
+                // to keep tsc's flow analysis off it (see its declaration above).
+                trans_type: trans_type
             }
             : undefined;
         const hook_args = hook_args_obj;
@@ -29963,6 +29975,50 @@ function vc(col) {
 function doublequote(txt) {
     return txt.replace(/"/g, String.raw `\"`);
 }
+/**
+ *  URL schemes that are safe to emit into a rendered diagram's `<a xlink:href>`.
+ *  Anything not in this set (notably `javascript:`, `data:`, `vbscript:`) is a
+ *  script-execution vector once the SVG is injected into a live DOM.
+ *  @internal
+ */
+const SAFE_URL_SCHEMES = new Set(['http', 'https', 'mailto', 'ftp', 'ftps', 'tel']);
+/**
+ *  Sanitize a state's `url` before it is embedded in DOT (and thence in the
+ *  rendered SVG's `xlink:href`).  A URL with a scheme is kept only when that
+ *  scheme is on the {@link SAFE_URL_SCHEMES} allowlist; a schemeless URL
+ *  (relative path, `#anchor`, query) is always safe and kept as-is.  An unsafe
+ *  URL is dropped (returns `''`) and a warning is emitted, so the diagram still
+ *  renders — just without the dangerous link.
+ *
+ *  Leading ASCII control characters and whitespace are stripped **before**
+ *  inspecting the scheme, because browsers ignore them when parsing a URL — so
+ *  `java\tscript:alert(1)` is recognized and dropped rather than smuggled past.
+ *
+ *  ```typescript
+ *  render_safe_url('https://example.com');       // 'https://example.com'
+ *  render_safe_url('#node');                      // '#node'
+ *  render_safe_url('javascript:alert(1)');        // ''  (dropped + warned)
+ *  ```
+ *  @param raw The raw `url` value from a state's config.
+ *  @returns The original URL if its scheme is safe or absent, otherwise `''`.
+ *  @internal
+ */
+function render_safe_url(raw) {
+    if (!raw) {
+        return '';
+    }
+    // eslint-disable-next-line no-control-regex -- browsers strip these before scheme parsing
+    const stripped = raw.replace(/[\u{0}-\u{20}]+/gu, '');
+    const scheme_match = /^([a-z][a-z0-9+.-]*):/i.exec(stripped);
+    if (scheme_match) {
+        const scheme = scheme_match[1].toLowerCase();
+        if (!SAFE_URL_SCHEMES.has(scheme)) {
+            console.warn(`jssm-viz: dropping state url with unsafe scheme "${scheme}:"`);
+            return '';
+        }
+    }
+    return raw;
+}
 /**
  *  Reverse {@link doublequote}: turn DOT's `\"` escape back into the literal
  *  `"` that graphviz renders into SVG `<text>` content.  Used by
@@ -30398,7 +30454,7 @@ function state_node_line(u_jssm, s, state_index, state_kinds, hide_state_labels,
         ['style', compose_style_string(style)],
         ['fontcolor', style.textColor || ''],
         ['image', style.image || ''],
-        ['URL', style.url || ''],
+        ['URL', render_safe_url(style.url || '')],
         ['fillcolor', fillcolor]
     ]
         .filter(r => r[1])