jssm 5.155.0 → 5.156.0

package/dist/wc/instance.js

@@ -521,7 +521,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"
@@ -531,7 +543,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=`).
@@ -560,14 +595,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)];
     });
 }
 /**
@@ -598,7 +647,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
@@ -666,6 +717,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/wc/viz.js

@@ -351,6 +351,125 @@ class FslViz extends LitElement {
     render() {
         return html `<div class="container">${unsafeHTML(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 = css `
     :host {
@@ -371,6 +490,21 @@ FslViz.styles = css `
       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([
     property({ type: String })

package/dist/wc/widgets.js

@@ -136,14 +136,28 @@ async function encode_machine(fsl) {
     const deflated = bytes_to_base64url(await deflate_raw(utf8));
     return deflated.length < raw.length ? `1${deflated}` : `0${raw}`;
 }
-/** 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)];
     });
 }
 /**
@@ -162,7 +176,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.155.0",
+  "version": "5.156.0",
   "engines": {
     "node": ">=10.0.0"
   },