jssm 5.155.0 → 5.156.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.155.0 at 6/28/2026, 7:41:44 PM
+* Generated for version 5.156.0 at 6/28/2026, 9:25:43 PM
 
 -->
-# jssm 5.155.0
+# jssm 5.156.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,811 tests at 100.0% line coverage
+  library.**  7,822 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,811 tests***, run 82,853 times.
+***7,822 tests***, run 82,864 times.
 
-- 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
+- 7,064 specs with 100.0% coverage
+- 758 fuzz tests with 54.1% coverage
+- 9,761 TypeScript lines - 0.8 tests per line, 8.5 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

@@ -3107,6 +3107,11 @@
           ],
           "description": "DEFLATE `bytes` (raw, headerless) via the platform `CompressionStream`."
         },
+        {
+          "kind": "variable",
+          "name": "MAX_PERMALINK_INFLATE_BYTES",
+          "description": "Hard ceiling on the inflated size of a permalink, in bytes. A permalink rides\r\nin a URL an attacker can hand a victim, and inflate_raw runs on it\r\nautomatically on page load, so an uncapped inflate is a decompression-bomb\r\nvector (a tiny `#m=…` could expand to hundreds of MB and OOM the tab). This is\r\ngenerous for real FSL (text — even a vast machine is well under a megabyte)."
+        },
         {
           "kind": "function",
           "name": "inflate_raw",
@@ -3123,7 +3128,7 @@
               }
             }
           ],
-          "description": "Inverse of deflate_raw."
+          "description": "Inverse of deflate_raw, reading the stream in chunks and aborting once\r\nthe inflated output would exceed MAX_PERMALINK_INFLATE_BYTES (a\r\ndecompression-bomb guard — see that constant)."
         },
         {
           "kind": "function",
@@ -3331,6 +3336,14 @@
             "module": "src/ts/wc/fsl_permalink.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "MAX_PERMALINK_INFLATE_BYTES",
+          "declaration": {
+            "name": "MAX_PERMALINK_INFLATE_BYTES",
+            "module": "src/ts/wc/fsl_permalink.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "inflate_raw",
@@ -4530,6 +4543,45 @@
                 }
               },
               "description": "Render the current `fsl` source to an SVG string via the headless\r\n`fsl_to_svg_string` pipeline. Updates `_svg` on success; emits a\r\n`viz-error` `CustomEvent` on failure. Guards against stale results\r\nwhen `fsl` changes mid-flight."
+            },
+            {
+              "kind": "method",
+              "name": "clearHighlights",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Clears any active programmatic highlights from the rendered SVG,\r\nrestoring every node and edge to its default Graphviz presentation.\r\n\r\nRemoves only the inline `fill` / `stroke` / `opacity` overrides that\r\nhighlightTrace installs; the SVG's own presentation attributes\r\nare untouched. Safe to call when nothing is highlighted, before the\r\nfirst render, or while detached — it no-ops if there is no rendered\r\nSVG to clear.\r\n\r\n```typescript\r\nconst viz = document.querySelector('fsl-viz');\r\nviz.highlightTrace(['a', 'b']);\r\nviz.clearHighlights();   // back to the default rendering\r\n```"
+            },
+            {
+              "kind": "method",
+              "name": "highlightTrace",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "trace",
+                  "type": {
+                    "text": "string[]"
+                  },
+                  "description": "Ordered state names describing the path (e.g.\r\n`['A', 'B', 'C']`). Consecutive pairs select the edges\r\n`A->B` and `B->C`. An empty array is a no-op."
+                },
+                {
+                  "name": "options",
+                  "default": "{}",
+                  "type": {
+                    "text": "HighlightOptions"
+                  },
+                  "description": "Highlight styling; see {@link HighlightOptions}. Defaults\r\n   *                to crimson with off-trace fading enabled.\r\n   *\r\n   * "
+                }
+              ],
+              "description": "Programmatically highlights one execution trace (a path of state names)\r\nthrough the rendered graph, optionally fading everything off the path.\r\n\r\nMatches nodes by their Graphviz `<title>` (the state name) and edges by\r\nthe `from->to` title Graphviz emits, applying inline style overrides so\r\nthe highlight composes over — and is reversible against — the default\r\nrendering (see clearHighlights, which this calls first). No-ops\r\nwhen detached, before the first render, or given an empty trace.\r\n\r\n```typescript\r\n// Highlight a -> b -> c in green, without dimming the rest:\r\nviz.highlightTrace(['a', 'b', 'c'], { color: '#2e7d32', fadeOthers: false });\r\n```"
             }
           ],
           "events": [

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.155.0";
+const version = "5.156.0";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -29436,7 +29436,19 @@ async function deflate_raw(bytes) {
     return new Uint8Array(await new Response(stream.readable).arrayBuffer());
 }
 /**
- * Inverse of {@link deflate_raw}.
+ * Hard ceiling on the inflated size of a permalink, in bytes. A permalink rides
+ * in a URL an attacker can hand a victim, and {@link inflate_raw} runs on it
+ * automatically on page load, so an uncapped inflate is a decompression-bomb
+ * vector (a tiny `#m=…` could expand to hundreds of MB and OOM the tab). This is
+ * generous for real FSL (text — even a vast machine is well under a megabyte).
+ */
+const MAX_PERMALINK_INFLATE_BYTES = 5 * 1024 * 1024;
+/**
+ * Inverse of {@link deflate_raw}, reading the stream in chunks and aborting once
+ * the inflated output would exceed {@link MAX_PERMALINK_INFLATE_BYTES} (a
+ * decompression-bomb guard — see that constant).
+ *
+ * @throws RangeError when the inflated output exceeds the cap.
  *
  * @example
  * new TextDecoder().decode(await inflate_raw(await deflate_raw(new TextEncoder().encode("hi")))); // "hi"
@@ -29446,7 +29458,30 @@ async function inflate_raw(bytes) {
     const writer = stream.writable.getWriter();
     void writer.write(bytes);
     void writer.close();
-    return new Uint8Array(await new Response(stream.readable).arrayBuffer());
+    // Read incrementally; stopping past the cap leaves the stream half-drained, so
+    // backpressure halts further inflation and the abandoned stream is GC'd. We do
+    // not cancel (which would abort the writable and leak an unhandled rejection).
+    const reader = stream.readable.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        total += value.length;
+        if (total > MAX_PERMALINK_INFLATE_BYTES) {
+            throw new RangeError(`permalink inflate exceeded ${MAX_PERMALINK_INFLATE_BYTES} bytes`);
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
 }
 /**
  * Encode FSL to a `<scheme><payload>` segment value (the part after `key=`).
@@ -29475,14 +29510,28 @@ async function decode_machine(segment) {
     const plain = scheme === '1' ? await inflate_raw(bytes) : bytes;
     return new TextDecoder().decode(plain);
 }
-/** Split a fragment (leading `#` optional) into `[key, value]` pairs, dropping empties. */
+/** `decodeURIComponent` that returns its input untouched on a malformed escape,
+ *  so a hand-mangled fragment never throws out of {@link read_fragment_param}. */
+function safe_decode(text) {
+    try {
+        return decodeURIComponent(text);
+    }
+    catch (_a) {
+        return text;
+    }
+}
+/**
+ * Split a fragment (leading `#` optional) into `[key, value]` pairs, dropping
+ * empties. Keys are percent-decoded (they are percent-encoded on write by
+ * {@link set_fragment_param}); values are the URL-safe base64 payload as-is.
+ */
 function fragment_pairs(hash) {
     const body = hash.startsWith('#') ? hash.slice(1) : hash;
     return body.split('&').filter(Boolean).map(seg => {
         const eq = seg.indexOf('=');
         return eq === -1
-            ? [seg, '']
-            : [seg.slice(0, eq), seg.slice(eq + 1)];
+            ? [safe_decode(seg), '']
+            : [safe_decode(seg.slice(0, eq)), seg.slice(eq + 1)];
     });
 }
 /**
@@ -29513,7 +29562,9 @@ function set_fragment_param(hash, key, value) {
     else {
         pairs[at] = [key, value];
     }
-    return pairs.map(([k, v]) => `${k}=${v}`).join('&');
+    // Percent-encode the key so an `id`/`uhash` containing `=`, `&`, or `#` cannot
+    // break segmentation or collide with a sibling. Values are URL-safe base64.
+    return pairs.map(([k, v]) => `${encodeURIComponent(k)}=${v}`).join('&');
 }
 /**
  * The fragment key an element owns: its `uhash` attribute if set, else its
@@ -29581,6 +29632,13 @@ class FslPermalinkSync {
         }
         try {
             const fsl = await decode_machine(segment);
+            // The decode is async; if the host was disconnected while it ran, drop the
+            // result rather than mutating a detached element (and triggering a stray
+            // rebuild on a later reconnect). A reconnect runs hostConnected → _restore
+            // afresh.
+            if (!this.host.isConnected) {
+                return;
+            }
             this._last = segment;
             this.host.fsl = fsl;
         }

package/dist/cdn/viz.js

@@ -23588,7 +23588,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.155.0";
+const version = "5.156.0";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -30372,6 +30372,125 @@ class FslViz extends i$1 {
     render() {
         return b `<div class="container">${o(this._svg)}</div>`;
     }
+    /**
+     * Clears any active programmatic highlights from the rendered SVG,
+     * restoring every node and edge to its default Graphviz presentation.
+     *
+     * Removes only the inline `fill` / `stroke` / `opacity` overrides that
+     * {@link highlightTrace} installs; the SVG's own presentation attributes
+     * are untouched. Safe to call when nothing is highlighted, before the
+     * first render, or while detached — it no-ops if there is no rendered
+     * SVG to clear.
+     *
+     * ```typescript
+     * const viz = document.querySelector('fsl-viz');
+     * viz.highlightTrace(['a', 'b']);
+     * viz.clearHighlights();   // back to the default rendering
+     * ```
+     *
+     * @see highlightTrace
+     */
+    clearHighlights() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const container = this.shadowRoot.querySelector('.container');
+        if (!container) {
+            return;
+        }
+        // Remove the inline styles that override the SVG presentation attributes.
+        const elements = container.querySelectorAll('.node, .edge, .node *, .edge *');
+        elements.forEach(el => {
+            el.style.removeProperty('fill');
+            el.style.removeProperty('stroke');
+            el.style.removeProperty('opacity');
+        });
+    }
+    /**
+     * Programmatically highlights one execution trace (a path of state names)
+     * through the rendered graph, optionally fading everything off the path.
+     *
+     * Matches nodes by their Graphviz `<title>` (the state name) and edges by
+     * the `from->to` title Graphviz emits, applying inline style overrides so
+     * the highlight composes over — and is reversible against — the default
+     * rendering (see {@link clearHighlights}, which this calls first). No-ops
+     * when detached, before the first render, or given an empty trace.
+     *
+     * ```typescript
+     * // Highlight a -> b -> c in green, without dimming the rest:
+     * viz.highlightTrace(['a', 'b', 'c'], { color: '#2e7d32', fadeOthers: false });
+     * ```
+     *
+     * @param trace   Ordered state names describing the path (e.g.
+     *                `['A', 'B', 'C']`). Consecutive pairs select the edges
+     *                `A->B` and `B->C`. An empty array is a no-op.
+     * @param options Highlight styling; see {@link HighlightOptions}. Defaults
+     *                to crimson with off-trace fading enabled.
+     *
+     * @see clearHighlights
+     * @see HighlightOptions
+     */
+    highlightTrace(trace, options = {}) {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const container = this.shadowRoot.querySelector('.container');
+        if (!container || trace.length === 0) {
+            return;
+        }
+        this.clearHighlights();
+        const color = options.color || '#b71c1c'; // default: a distinct crimson
+        const fadeOthers = options.fadeOthers !== false; // default: true
+        const targetNodes = new Set();
+        const targetEdges = new Set();
+        for (let i = 0; i < trace.length; i++) {
+            targetNodes.add(trace[i]);
+            if (i < trace.length - 1) {
+                targetEdges.add(`${trace[i]}->${trace[i + 1]}`);
+            }
+        }
+        const allNodes = container.querySelectorAll('.node');
+        const allEdges = container.querySelectorAll('.edge');
+        // Graphviz escapes '->' inside <title> as '&#45;&gt;'; DOM textContent
+        // usually decodes it, but normalize defensively (and drop quotes).
+        const unescapeTitle = (title) => title.replace(/&#45;/g, '-').replace(/&gt;/g, '>').replace(/"/g, '');
+        allNodes.forEach(node => {
+            const titleEl = node.querySelector('title');
+            const title = titleEl ? unescapeTitle(titleEl.textContent || '') : '';
+            if (targetNodes.has(title)) {
+                node.querySelectorAll('polygon, ellipse, path').forEach(shape => {
+                    shape.style.stroke = color;
+                    shape.style.strokeWidth = '2px';
+                });
+                node.querySelectorAll('text').forEach(text => {
+                    text.style.fill = color;
+                });
+            }
+            else if (fadeOthers) {
+                node.style.opacity = '0.2';
+            }
+        });
+        allEdges.forEach(edge => {
+            const titleEl = edge.querySelector('title');
+            const title = titleEl ? unescapeTitle(titleEl.textContent || '') : '';
+            if (targetEdges.has(title)) {
+                // Recolour the edge line and its arrowhead. The edge's action label
+                // is intentionally left alone: reorder_svg_layers() hoists every edge
+                // <text> out of its group onto a top paint layer (so labels can't be
+                // overdrawn), where it carries no <title> to correlate back to this
+                // edge — so a state-name trace cannot reliably re-style it.
+                edge.querySelectorAll('path, polygon').forEach(shape => {
+                    shape.style.stroke = color;
+                    if (shape.tagName.toLowerCase() === 'polygon') {
+                        shape.style.fill = color; // arrowheads
+                    }
+                });
+            }
+            else if (fadeOthers) {
+                edge.style.opacity = '0.2';
+            }
+        });
+    }
 }
 FslViz.styles = i$4 `
     :host {
@@ -30392,6 +30511,21 @@ FslViz.styles = i$4 `
       width: 90%;
       height: 90%;
     }
+
+    /* Smoothly animate the inline style overrides applied by highlightTrace()
+       so a trace fades in/out rather than snapping. */
+    .container svg g.node path,
+    .container svg g.node polygon,
+    .container svg g.node ellipse,
+    .container svg g.edge path,
+    .container svg g.edge polygon {
+      transition: fill 0.3s ease, stroke 0.3s ease, opacity 0.3s ease;
+    }
+
+    .container svg g.node text,
+    .container svg g.edge text {
+      transition: fill 0.3s ease, opacity 0.3s ease;
+    }
   `;
 __decorate([
     n({ type: String })

package/dist/cli/fsl-export-system-prompt.cjs

@@ -108,7 +108,7 @@ function parseFslArgs(argv, spec) {
   return { positional, flags, helpText };
 }
 
-const getVersion = () => "5.155.0";
+const getVersion = () => "5.156.0";
 const SPEC = {
   flags: {
     help: { short: "h", boolean: true },