jssm 5.155.1 → 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.1 at 6/28/2026, 7:52:33 PM
+* Generated for version 5.156.0 at 6/28/2026, 9:25:43 PM
 
 -->
-# jssm 5.155.1
+# 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,815 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,815 tests***, run 82,857 times.
+***7,822 tests***, run 82,864 times.
 
-- 7,057 specs with 100.0% coverage
-- 758 fuzz tests with 54.7% coverage
-- 9,686 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

@@ -4543,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.1";
+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;

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.1";
+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.1";
+const getVersion = () => "5.156.0";
 const SPEC = {
   flags: {
     help: { short: "h", boolean: true },