jssm 5.136.0 → 5.138.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.136.0 at 5/27/2026, 10:35:53 PM
+* Generated for version 5.138.0 at 5/28/2026, 7:32:08 AM
 
 -->
-# jssm 5.136.0
+# jssm 5.138.0
 
 [**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
 [Documentation](https://stonecypher.github.io/jssm/docs/) ·
@@ -281,7 +281,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.**  6,277 tests at 100.0% line coverage
+  library.**  6,349 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.
@@ -414,11 +414,11 @@ If your contribution is missing here, please open an issue.
 
 <br/>
 
-***6,277 tests***, run 57,064 times.
+***6,349 tests***, run 57,136 times.
 
-- 5,764 specs with 100.0% coverage
-- 513 fuzz tests with 3.8% coverage
-- 5,014 TypeScript lines - 1.3 tests per line, 11.4 generated tests per line
+- 5,836 specs with 100.0% coverage
+- 513 fuzz tests with 3.6% coverage
+- 5,288 TypeScript lines - 1.2 tests per line, 10.8 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

@@ -2,6 +2,254 @@
   "schemaVersion": "1.0.0",
   "readme": "",
   "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/ts/wc/jssm_hook_wc.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "make_hook_proxy",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "ctx",
+              "type": {
+                "text": "{ data?: TData; from?: string; to?: string; action?: string }"
+              },
+              "description": "Raw hook context passed by jssm."
+            },
+            {
+              "name": "machine",
+              "type": {
+                "text": "{ state(): unknown }"
+              },
+              "description": "The owning machine; used for the `state()` accessor."
+            }
+          ],
+          "description": "Build a JssmHookProxy that wraps an arbitrary hook context object.\n\nThe context shape varies by hook kind (`from`/`to`/`action` may be absent\nfor transition-kind hooks), so this normalizes the shape via optional\nfields and exposes mutable `data` while keeping the rest read-only.\n\nThe `machine` parameter is used only for `state()`, so unit tests can\nsubstitute any object with a `state(): unknown` method."
+        },
+        {
+          "kind": "function",
+          "name": "compile_inline_body",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "body",
+              "type": {
+                "text": "string"
+              },
+              "description": "Trimmed textContent of the `<jssm-hook>` element."
+            },
+            {
+              "name": "debug_id",
+              "type": {
+                "text": "string"
+              },
+              "description": "Identifier appended to the synthetic sourceURL."
+            }
+          ],
+          "description": "Compile a textContent body into a callable user handler.\n\nUses dynamic function construction — the same primitive browsers use\ninternally for `<a onclick=\"...\">` and `setTimeout(stringBody, ms)`.\nStrict CSP without `'unsafe-eval'` blocks this and the call will throw;\nconsumers should fall back to the `handler=\"name\"` form there.\n\nPrepends a `//# sourceURL=` comment so devtools surface a meaningful name\nin stack traces instead of `anonymous`."
+        },
+        {
+          "kind": "function",
+          "name": "resolve_named_handler",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "description": "The handler name from the `handler=\"\"` attribute."
+            },
+            {
+              "name": "registry",
+              "optional": true,
+              "type": {
+                "text": "JssmHookRegistry"
+              },
+              "description": "Optional in-WC registry to consult first."
+            }
+          ],
+          "description": "Resolve a `handler=\"name\"` attribute to a callable by consulting first the\noptional in-WC registry, then `globalThis[name]`.  Throws a clear error if\nneither resolves."
+        },
+        {
+          "kind": "function",
+          "name": "normalize_hook_kind",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "raw",
+              "type": {
+                "text": "string | null | undefined"
+              },
+              "description": "The raw attribute value, or null if not present."
+            }
+          ],
+          "description": "Validate and normalize a `<jssm-hook kind=\"...\">` value, defaulting to\n`\"hook\"` when the attribute is absent.  Throws on unknown kinds rather\nthan silently doing nothing later."
+        },
+        {
+          "kind": "function",
+          "name": "parse_hook_element",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "el",
+              "type": {
+                "text": "HTMLElement"
+              },
+              "description": "The `<jssm-hook>` element to parse."
+            },
+            {
+              "name": "debug_id",
+              "type": {
+                "text": "string"
+              },
+              "description": "Identifier used in the inline body's sourceURL."
+            },
+            {
+              "name": "registry",
+              "optional": true,
+              "type": {
+                "text": "JssmHookRegistry"
+              },
+              "description": "Optional in-WC registry of named handlers."
+            }
+          ],
+          "description": "Parse a single `<jssm-hook>` element into a JssmHookInstallSpec.\n\nValidates the mutual-exclusion rule between `handler=\"name\"` and inline\nbody, defaults `kind` to `\"hook\"`, resolves named handlers against the\noptional registry then `globalThis`, and compiles inline bodies via\ndynamic function construction.  Conditional-required attributes (e.g.\n`from`/`to` for `kind=\"hook\"`) are NOT validated here — `set_hook` will\nthrow with its own clear errors on missing pieces, which keeps the\nerror surface single-sourced."
+        },
+        {
+          "kind": "function",
+          "name": "wrap_user_handler",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "spec",
+              "type": {
+                "text": "JssmHookInstallSpec"
+              },
+              "description": "The parsed install spec carrying the user handler."
+            },
+            {
+              "name": "machine",
+              "type": {
+                "text": "{ state(): unknown }"
+              },
+              "description": "The owning machine; used by the proxy's `state()`."
+            }
+          ],
+          "description": "Wrap a JssmHookUserHandler so that jssm's native hook contract is\nsatisfied: the user gets a friendly proxy, the proxy's mutated `data`\nbecomes the `HookComplexResult.data`, and an explicit `false` return\ncancels the transition.\n\nAny non-`false` return — including `undefined`, `true`, or an arbitrary\nobject — allows the transition.  This matches the contract spelled out\nin the issue (#641): \"return false cancels; anything else allows\"."
+        },
+        {
+          "kind": "function",
+          "name": "build_hook_descriptor",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "spec",
+              "type": {
+                "text": "JssmHookInstallSpec"
+              },
+              "description": "The parsed install spec."
+            },
+            {
+              "name": "wrapped",
+              "type": {
+                "text": "(ctx: RawHookContext) => unknown"
+              },
+              "description": "The wrapped (friendly-proxy) handler from {@link wrap_user_handler}.\n * "
+            }
+          ],
+          "description": "Build the typed descriptor object passed to `machine.set_hook` (and later\nto `machine.remove_hook` for cleanup) from a parsed JssmHookInstallSpec\nand the wrapped handler.\n\nFor kinds that need `from`/`to`/`action`, the descriptor includes those.\nMissing required keys produce `undefined` here; jssm's `set_hook` will\nsurface the error with its own clear message so we don't duplicate\nvalidation.\n\nReturn type is `unknown` because jssm's `HookDescription` is a\ndiscriminated union and our runtime-discriminator value can't be tracked\nby TypeScript across the build.  The WC casts at the `set_hook` call site."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "make_hook_proxy",
+          "declaration": {
+            "name": "make_hook_proxy",
+            "module": "src/ts/wc/jssm_hook_wc.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "compile_inline_body",
+          "declaration": {
+            "name": "compile_inline_body",
+            "module": "src/ts/wc/jssm_hook_wc.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "resolve_named_handler",
+          "declaration": {
+            "name": "resolve_named_handler",
+            "module": "src/ts/wc/jssm_hook_wc.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "normalize_hook_kind",
+          "declaration": {
+            "name": "normalize_hook_kind",
+            "module": "src/ts/wc/jssm_hook_wc.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "parse_hook_element",
+          "declaration": {
+            "name": "parse_hook_element",
+            "module": "src/ts/wc/jssm_hook_wc.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "wrap_user_handler",
+          "declaration": {
+            "name": "wrap_user_handler",
+            "module": "src/ts/wc/jssm_hook_wc.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "build_hook_descriptor",
+          "declaration": {
+            "name": "build_hook_descriptor",
+            "module": "src/ts/wc/jssm_hook_wc.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/ts/wc/jssm_instance_wc.ts",
@@ -30,11 +278,11 @@
               "description": "The current value of the host's `fsl` attribute (or property), or empty string."
             }
           ],
-          "description": "Resolve a `<jssm-instance>`'s FSL source from the three legal channels:\nthe `fsl=\"\"` attribute, a child `<script type=\"text/fsl\">`, and the\nelement's own text content (after stripping the script and any\n`<jssm-*>` companion tags).  Exactly one channel may be used; using\nnone or more than one is an error.\n\nPulled out as a pure function so it's testable without spinning up a\nLit element.\n\n```typescript\nconst div = document.createElement('div');\ndiv.setAttribute('fsl', 'Off -> On;');\nresolve_fsl_source(div as HTMLElement, 'Off -> On;');\n// => { fsl: 'Off -> On;', provided_count: 1, error: undefined }\n```"
+          "description": "Resolve a `<jssm-instance>`'s FSL source from the three legal channels:\r\nthe `fsl=\"\"` attribute, a child `<script type=\"text/fsl\">`, and the\r\nelement's own text content (after stripping the script and any\r\n`<jssm-*>` companion tags).  Exactly one channel may be used; using\r\nnone or more than one is an error.\r\n\r\nPulled out as a pure function so it's testable without spinning up a\r\nLit element.\r\n\r\n```typescript\r\nconst div = document.createElement('div');\r\ndiv.setAttribute('fsl', 'Off -> On;');\r\nresolve_fsl_source(div as HTMLElement, 'Off -> On;');\r\n// => { fsl: 'Off -> On;', provided_count: 1, error: undefined }\r\n```"
         },
         {
           "kind": "class",
-          "description": "Web component that owns a single `Machine<unknown>` constructed from an\nFSL source supplied via one of three mutually exclusive channels:\n\n  1. The `fsl=\"\"` attribute,\n  2. A child `<script type=\"text/fsl\">`,\n  3. The element's own text content (companion `<jssm-*>` children and\n     any `<script type=\"text/fsl\">` are excluded from this channel).\n\nSupplying zero or more than one channel is a thrown error.\n\nOn every transition the component reflects machine state to its own\nattributes (`current-state`, `legal-actions`, `terminal`, `complete`)\nand sets a `--current-state` CSS custom property so consumer CSS can\nstyle by state without subclassing.",
+          "description": "Web component that owns a single `Machine<unknown>` constructed from an\r\nFSL source supplied via one of three mutually exclusive channels:\r\n\r\n  1. The `fsl=\"\"` attribute,\r\n  2. A child `<script type=\"text/fsl\">`,\r\n  3. The element's own text content (companion `<jssm-*>` children and\r\n     any `<script type=\"text/fsl\">` are excluded from this channel).\r\n\r\nSupplying zero or more than one channel is a thrown error.\r\n\r\nOn every transition the component reflects machine state to its own\r\nattributes (`current-state`, `legal-actions`, `terminal`, `complete`)\r\nand sets a `--current-state` CSS custom property so consumer CSS can\r\nstyle by state without subclassing.",
           "name": "JssmInstance",
           "cssProperties": [
             {
@@ -81,7 +329,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "FSL source attribute.  When non-empty, this is the sole channel\nsupplying the machine's source.  Setting both this and a child\n`<script type=\"text/fsl\">` (or non-empty text content) is an error.",
+              "description": "FSL source attribute.  When non-empty, this is the sole channel\r\nsupplying the machine's source.  Setting both this and a child\r\n`<script type=\"text/fsl\">` (or non-empty text content) is an error.",
               "attribute": "fsl"
             },
             {
@@ -92,7 +340,47 @@
               },
               "privacy": "private",
               "default": "undefined",
-              "description": "The underlying machine instance, constructed at `connectedCallback`.\nExposed raw (not proxied) per the #639/#648 design decision so that\nconsumers can use the full Machine API directly.\n\nMarked optional because Lit will instantiate the element before\n`connectedCallback` runs; the instance is guaranteed present after\nconnection."
+              "description": "The underlying machine instance, constructed at `connectedCallback`.\r\nExposed raw (not proxied) per the #639/#648 design decision so that\r\nconsumers can use the full Machine API directly.\r\n\r\nMarked optional because Lit will instantiate the element before\r\n`connectedCallback` runs; the instance is guaranteed present after\r\nconnection."
+            },
+            {
+              "kind": "field",
+              "name": "registry",
+              "type": {
+                "text": "JssmHookRegistry"
+              },
+              "readonly": true,
+              "default": "new Map()",
+              "description": "Per-instance registry of named hook handlers consulted before\r\n`globalThis` when resolving `<jssm-hook handler=\"name\">`.\r\n\r\nInitialized to an empty `Map`; consumers may populate it before the\r\nelement connects to provide handlers without polluting global scope —\r\nuseful for module-scoped SPAs where strict CSP blocks inline-body hooks."
+            },
+            {
+              "kind": "field",
+              "name": "_installed_hooks",
+              "type": {
+                "text": "unknown[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "Descriptors for hooks this WC installed at connect time, used in\r\n`disconnectedCallback` to call `remove_hook` for each so the underlying\r\nmachine doesn't leak handlers when the element is detached.\r\n\r\nCaptured at install time because `remove_hook` matches by descriptor\r\nshape (not handler identity), and we need to record the wrapped handler\r\nwe passed to `set_hook` to undo the registration cleanly.  Stored as\r\n`unknown[]` and cast at the call site because jssm's `HookDescription`\r\nis a discriminated union whose discriminator is only known at runtime."
+            },
+            {
+              "kind": "field",
+              "name": "_hook_debug_counter",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "Counter used to give each compiled inline-body hook a unique debug id\r\nfor its `//# sourceURL=jssm-hook:N` annotation.  Per-instance so that\r\nmultiple `<jssm-instance>` elements on a page don't share numbering."
+            },
+            {
+              "kind": "field",
+              "name": "_action_listeners",
+              "type": {
+                "text": "Array<{\r\n    target  : EventTarget;\r\n    event   : string;\r\n    handler : EventListener;\r\n  }>"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "Records every DOM listener installed by `<jssm-action>` / `data-jssm-action`\r\ndiscovery so disconnectedCallback can remove each one with the\r\nsame handler reference originally passed to `addEventListener`.\r\n\r\nListeners installed via the dedicated `<jssm-action>` tag form may target\r\nelements outside the host (its `selector` is resolved against the host,\r\nbut matching elements live in the document tree), so cleanup must be\r\nexplicit — relying on the host's GC is not sufficient."
             },
             {
               "kind": "field",
@@ -128,7 +416,7 @@
                   "description": "Optional data payload to pass to the action."
                 }
               ],
-              "description": "Convenience wrapper for `machine.action(action, data)`.\nAfter the action, reflects updated state to host attributes and the\n`--current-state` CSS custom property, and requests a Lit update so\nthe state-specific `<slot name=\"state-...\">` can re-pick."
+              "description": "Convenience wrapper for `machine.action(action, data)`.\r\nAfter the action, reflects updated state to host attributes and the\r\n`--current-state` CSS custom property, and requests a Lit update so\r\nthe state-specific `<slot name=\"state-...\">` can re-pick."
             },
             {
               "kind": "method",
@@ -138,7 +426,88 @@
                   "text": "string"
                 }
               },
-              "description": "Convenience wrapper for `machine.state()`.  Returns the current\nstate's name."
+              "description": "Convenience wrapper for `machine.state()`.  Returns the current\r\nstate's name."
+            },
+            {
+              "kind": "method",
+              "name": "_install_declarative_hooks",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Discover every direct-child `<jssm-hook>` element and install each\r\nagainst the owned machine.  Handlers are wrapped with the friendly-proxy\r\nadapter that lets user code write `m.data = ...` and return `false` to\r\ncancel — see make_hook_proxy and the issue (#641) doc-comment\r\nfor the full contract.\r\n\r\nDirect children only (the `:scope > jssm-hook` selector) so that nested\r\n`<jssm-instance>` elements don't have their child hooks installed on\r\nthe outer machine.\r\n\r\nTracks every installed descriptor in `_installed_hooks` so that\r\n`disconnectedCallback` can remove them on detach."
+            },
+            {
+              "kind": "method",
+              "name": "_hook_id_prefix",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "description": "Prefix used in synthetic `//# sourceURL=jssm-hook:<prefix><n>` annotations\r\nfor inline-body hooks compiled by this element.  Includes the element's\r\n`id` when present so multi-instance pages can tell sources apart in\r\ndevtools."
+            },
+            {
+              "kind": "method",
+              "name": "_discover_jssm_actions",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Wire DOM events to machine actions, using the two declarative forms from\r\nissue #640:\r\n\r\n 1. Inline attribute form: every descendant of the host carrying a\r\n    `data-jssm-action=\"<name>\"` attribute receives a listener on the\r\n    event named by `data-jssm-event` (default `click`).\r\n 2. Dedicated tag form: each direct `<jssm-action>` child of the host\r\n    supplies a CSS `selector` (scoped to the host), an `action`, and an\r\n    optional `event` (default `click`); every matching descendant\r\n    receives a listener configured by the tag's attributes.\r\n\r\nBoth forms support optional `from-state` guards (dispatch only when the\r\nmachine's current state matches), `from-property` data extraction (pass\r\nthe source element's named property as the action's data argument), and\r\n`prevent-default` / `stop-propagation` modifiers.\r\n\r\nEvery installed listener is recorded in _action_listeners so\r\ndisconnectedCallback can detach them cleanly."
+            },
+            {
+              "kind": "method",
+              "name": "_install_action_listener",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "config",
+                  "type": {
+                    "text": "{\r\n    source           : HTMLElement;\r\n    event_name       : string;\r\n    action_name      : string;\r\n    from_state       : string | undefined;\r\n    from_property    : string | undefined;\r\n    prevent_default  : boolean;\r\n    stop_propagation : boolean;\r\n  }"
+                  },
+                  "description": "Listener configuration."
+                },
+                {
+                  "description": "Element to attach the listener to.",
+                  "name": "config.source"
+                },
+                {
+                  "description": "DOM event to listen for.",
+                  "name": "config.event_name"
+                },
+                {
+                  "description": "Action to dispatch on the machine.",
+                  "name": "config.action_name"
+                },
+                {
+                  "description": "If set, only fire when `machine.state() === from_state`.",
+                  "name": "config.from_state"
+                },
+                {
+                  "description": "If set, pass `source[from_property]` as the action's data argument.",
+                  "name": "config.from_property"
+                },
+                {
+                  "description": "If true, call `e.preventDefault()` before checking the guard.",
+                  "name": "config.prevent_default"
+                },
+                {
+                  "description": "If true, call `e.stopPropagation()` before checking the guard.",
+                  "name": "config.stop_propagation"
+                }
+              ],
+              "description": "Attach one DOM listener that translates a DOM event into a\r\n`machine.action(...)` call, honoring the configured modifiers.  The\r\nlistener is recorded in _action_listeners so it can be removed\r\non disconnect."
             },
             {
               "kind": "method",
@@ -149,7 +518,7 @@
                   "text": "void"
                 }
               },
-              "description": "Reflect machine state onto host attributes and CSS custom properties.\nCalled after every transition and once during `connectedCallback`.\n\nMechanism 1 (#639): writes to host attributes.\nMechanism 3 (#639): writes to host inline-style custom properties."
+              "description": "Reflect machine state onto host attributes and CSS custom properties.\r\nCalled after every transition and once during `connectedCallback`.\r\n\r\nMechanism 1 (#639): writes to host attributes.\r\nMechanism 3 (#639): writes to host inline-style custom properties."
             }
           ],
           "attributes": [
@@ -159,7 +528,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "FSL source attribute.  When non-empty, this is the sole channel\nsupplying the machine's source.  Setting both this and a child\n`<script type=\"text/fsl\">` (or non-empty text content) is an error.",
+              "description": "FSL source attribute.  When non-empty, this is the sole channel\r\nsupplying the machine's source.  Setting both this and a child\r\n`<script type=\"text/fsl\">` (or non-empty text content) is an error.",
               "fieldName": "fsl"
             }
           ],