jssm 5.138.0 → 5.141.0

package/dist/wc/instance.js

@@ -1,6 +1,222 @@
 import { css, LitElement, html } from 'lit';
 import { sm } from 'jssm';
 
+/**
+ * Walk a dotted path into a value.  Used by the `data.path.to.field`
+ * variant of {@link resolve_binding}.  Returns `undefined` whenever the
+ * traversal would dereference a non-object, missing field, or `null` —
+ * matching the natural "missing data" semantics rather than throwing.
+ *
+ * ```typescript
+ * walk_path({ a: { b: 7 } }, 'a.b');     // => 7
+ * walk_path({ a: { b: 7 } }, 'a.c');     // => undefined
+ * walk_path({ a: { b: 7 } }, 'a.b.c');   // => undefined (7 is not an object)
+ * walk_path(undefined,        'a');      // => undefined
+ * walk_path({ a: null },     'a.b');     // => undefined (null is not an object)
+ * walk_path({ a: 1 },         '');       // => { a: 1 } (empty path = identity)
+ * ```
+ *
+ * @param obj  - The root value to traverse.
+ * @param path - Dotted path of property names, e.g. `"a.b.c"`.
+ * @returns The terminal value, or `undefined` if any step fails.
+ */
+function walk_path(obj, path) {
+    if (path.length === 0) {
+        return obj;
+    }
+    let cur = obj;
+    for (const part of path.split('.')) {
+        if (cur === null || typeof cur !== 'object') {
+            return undefined;
+        }
+        cur = cur[part];
+    }
+    return cur;
+}
+/**
+ * Resolve a `<jssm-bind>` / `data-jssm-bind` expression against a live
+ * machine.  Throws on any unknown expression — bindings fail fast at
+ * install time rather than silently producing `undefined` strings in the
+ * DOM.
+ *
+ * Recognized expressions:
+ *
+ * | Expression       | Resolves to                                   |
+ * | ---------------- | --------------------------------------------- |
+ * | `data`           | `machine.data()`                              |
+ * | `data.a.b.c`     | dotted-path traversal into `machine.data()`   |
+ * | `state`          | `machine.state()`                             |
+ * | `terminal`       | `machine.is_terminal()`                       |
+ * | `complete`       | `machine.is_complete()`                       |
+ * | `legal-actions`  | `machine.list_exit_actions().join(' ')`       |
+ *
+ * ```typescript
+ * resolve_binding(m, 'state');              // current state name
+ * resolve_binding(m, 'data.username');      // typed-data subfield
+ * resolve_binding(m, 'wat');                // throws
+ * ```
+ *
+ * @param m    - The machine whose state/data is being projected.
+ * @param expr - The binding expression text (raw attribute value).
+ * @returns The resolved value, typed `unknown` since each expression
+ *          yields a different shape.
+ *
+ * @throws Error - When `expr` is not a recognized binding form.
+ */
+function resolve_binding(m, expr) {
+    switch (expr) {
+        case 'state': return m.state();
+        case 'terminal': return m.is_terminal();
+        case 'complete': return m.is_complete();
+        case 'legal-actions': return m.list_exit_actions().map(a => String(a)).join(' ');
+        case 'data': return m.data();
+        default:
+            if (expr.startsWith('data.')) {
+                return walk_path(m.data(), expr.slice(5));
+            }
+            throw new Error(`<jssm-bind>: unknown binding expression "${expr}"`);
+    }
+}
+/**
+ * Apply a resolved binding value to an element's target property.  The
+ * `target` selector follows the rules documented in #645:
+ *
+ * - `textContent` (or omitted) sets `el.textContent` to the value coerced
+ *   with `String()`.
+ * - Any string starting with `data-` is treated as an attribute name and
+ *   set via `setAttribute`, value coerced with `String()`.
+ * - Any other string is assigned directly as a property of the element
+ *   (no coercion) — supports `value`, `disabled`, `hidden`, `checked`,
+ *   and the documented power-user escape hatch.
+ *
+ * ```typescript
+ * set_on_element(span,   'textContent',     7);            // span.textContent = '7'
+ * set_on_element(input,  'value',           'hi');         // input.value = 'hi'
+ * set_on_element(button, 'disabled',        true);         // button.disabled = true
+ * set_on_element(div,    'data-current',    'red');        // setAttribute('data-current', 'red')
+ * ```
+ *
+ * @param el     - The element to update.
+ * @param target - Target property name, possibly a `data-*` attribute.
+ * @param value  - The resolved value to assign.
+ */
+function set_on_element(el, target, value) {
+    if (target.startsWith('data-')) {
+        el.setAttribute(target, String(value));
+    }
+    else if (target === 'textContent') {
+        el.textContent = String(value);
+    }
+    else {
+        // Power-user escape hatch — assigns value as-is so booleans hit
+        // properties like `disabled`/`hidden`/`checked` with the correct
+        // semantics rather than being coerced to a string.
+        el[target] = value;
+    }
+}
+/**
+ * Discover every binding declaration under `host` and install live
+ * subscriptions that refresh them on every machine transition.  Returns
+ * a list of unsubscribe callbacks so the host's `disconnectedCallback`
+ * can tear them all down.
+ *
+ * Two surface forms are recognized:
+ *
+ * 1. Inline attribute — any descendant with `data-jssm-bind="<expr>"`.
+ *    Optional `data-jssm-bind-to="<target>"` chooses the target property
+ *    (defaults to `textContent`).
+ *
+ * 2. Dedicated tag — direct-child `<jssm-bind>` configuration tags with
+ *    `selector="<css>"` and `source="<expr>"` attributes, plus an
+ *    optional `target="<target>"` (also defaulting to `textContent`).
+ *    The `selector` is scoped to `host`'s descendants.
+ *
+ * Each binding is painted once immediately (using the machine's current
+ * state) and then re-painted on every `transition` event.
+ *
+ * ```typescript
+ * // typical install during <jssm-instance>.connectedCallback:
+ * const unsubs = install_bindings(this, this.machine);
+ * this._unsubs.push(...unsubs);
+ * ```
+ *
+ * @param host    - The host element whose descendants carry the bindings.
+ * @param machine - The machine whose state/data is being projected.
+ * @returns A flat array of unsubscribe callbacks, one per installed
+ *          subscription.
+ *
+ * @throws Error - When any binding expression is unrecognized
+ *                 (propagated from {@link resolve_binding}).
+ * @throws Error - When a `<jssm-bind>` tag is missing its `selector`
+ *                 or `source` attribute.
+ */
+function install_bindings(host, machine) {
+    var _a, _b;
+    const unsubs = [];
+    // Form 1: inline `data-jssm-bind` on descendants.
+    const inline_nodes = host.querySelectorAll('[data-jssm-bind]');
+    for (const el of Array.from(inline_nodes)) {
+        const expr = el.dataset.jssmBind;
+        const target = (_a = el.dataset.jssmBindTo) !== null && _a !== void 0 ? _a : 'textContent';
+        const apply = () => {
+            set_on_element(el, target, resolve_binding(machine, expr));
+        };
+        apply();
+        unsubs.push(machine.on('transition', apply));
+    }
+    // Form 2: dedicated `<jssm-bind>` configuration tags.  Only direct
+    // children are considered configuration tags for THIS host — nested
+    // `<jssm-instance>` children would have their own bindings handled by
+    // their own component.
+    const config_tags = host.querySelectorAll(':scope > jssm-bind');
+    for (const tag of Array.from(config_tags)) {
+        const selector = tag.getAttribute('selector');
+        const expr = tag.getAttribute('source');
+        const target = (_b = tag.getAttribute('target')) !== null && _b !== void 0 ? _b : 'textContent';
+        if (selector === null || selector.length === 0) {
+            throw new Error('<jssm-bind>: missing required "selector" attribute');
+        }
+        if (expr === null || expr.length === 0) {
+            throw new Error('<jssm-bind>: missing required "source" attribute');
+        }
+        const targets = host.querySelectorAll(selector);
+        for (const el of Array.from(targets)) {
+            const apply = () => {
+                set_on_element(el, target, resolve_binding(machine, expr));
+            };
+            apply();
+            unsubs.push(machine.on('transition', apply));
+        }
+    }
+    return unsubs;
+}
+/**
+ * `<jssm-bind>` configuration tag.  The element itself is invisible —
+ * it carries `selector`, `source`, and optional `target` attributes
+ * that the parent `<jssm-instance>` reads during its connection
+ * lifecycle to wire up a machine-to-DOM binding.
+ *
+ * Registering it as a `LitElement` (rather than leaving it as a generic
+ * unknown tag) gives it a stable upgrade timing, a `display: none`
+ * default style, and a proper place in the custom-elements registry so
+ * `customElements.get('jssm-bind')` resolves.
+ *
+ * @element jssm-bind
+ * @attribute selector - CSS selector for the target element(s), scoped to the host.
+ * @attribute source - Binding expression (see {@link resolve_binding}).
+ * @attribute target - Target property name; defaults to `textContent`.
+ */
+class JssmBind extends LitElement {
+    /**
+     * No-op render.  The tag's purpose is purely declarative
+     * configuration; it must not contribute any DOM to the page.
+     */
+    render() {
+        return null;
+    }
+}
+JssmBind.styles = css `:host { display: none; }`;
+
 const VALID_KINDS = new Set([
     'hook',
     'named',
@@ -64,7 +280,7 @@ function make_hook_proxy(ctx, machine) {
  * @param debug_id - Identifier appended to the synthetic sourceURL.
  * @returns The compiled handler.
  */
-function compile_inline_body(body, debug_id) {
+function compile_inline_body$1(body, debug_id) {
     const annotated = `//# sourceURL=jssm-hook:${debug_id}\n${body}`;
     const ctor = Function;
     return new ctor('m', annotated);
@@ -79,7 +295,7 @@ function compile_inline_body(body, debug_id) {
  * @returns The resolved handler.
  * @throws Error  - If no callable of that name is found in either location.
  */
-function resolve_named_handler(name, registry) {
+function resolve_named_handler$1(name, registry) {
     if (registry !== undefined) {
         const registered = registry.get(name);
         if (registered !== undefined) {
@@ -139,8 +355,8 @@ function parse_hook_element(el, debug_id, registry) {
         throw new Error('<jssm-hook>: must specify either handler="name" attribute or an inline body');
     }
     const user_handler = handler_attr !== null
-        ? resolve_named_handler(handler_attr, registry)
-        : compile_inline_body(body_text, debug_id);
+        ? resolve_named_handler$1(handler_attr, registry)
+        : compile_inline_body$1(body_text, debug_id);
     const kind = normalize_hook_kind(el.getAttribute('kind'));
     // Convert null → undefined so downstream descriptors omit absent keys.
     const from = (_a = el.getAttribute('from')) !== null && _a !== void 0 ? _a : undefined;
@@ -203,6 +419,177 @@ function build_hook_descriptor(spec, wrapped) {
     return base;
 }
 
+/**
+ * Allow-list of event names accepted by `<jssm-on event="...">`.  Must stay
+ * in sync with the `JssmEventName` union in `jssm_types.ts` (the library's
+ * `machine.on(...)` event API, added in #638).  Validating here gives the
+ * declarative wiring a clear "unknown event name" error at the WC layer
+ * instead of relying on a downstream library throw whose message would
+ * mention `machine.on(...)` rather than the offending tag.
+ */
+const JSSM_ON_EVENT_NAMES = new Set([
+    'transition',
+    'rejection',
+    'action',
+    'entry',
+    'exit',
+    'terminal',
+    'complete',
+    'error',
+    'data-change',
+    'override',
+    'timeout',
+    'hook-registration',
+    'hook-removal'
+]);
+/**
+ * Parse a `<jssm-on>` element into a validated {@link ParsedJssmOn}
+ * record.  Centralized so the declarative-tag logic is testable without
+ * spinning up the full `<jssm-instance>` lifecycle.
+ *
+ * Validation rules (per #643):
+ *   - `event` is required and must be in {@link JSSM_ON_EVENT_NAMES}.
+ *   - Either a `handler="name"` attribute or non-empty `textContent`
+ *     must be supplied, but not both.
+ *   - `state` is only meaningful for `event="entry"` / `event="exit"`;
+ *     it's silently ignored on other events.
+ *   - `from` / `to` are only meaningful for `event="transition"`; they
+ *     are silently ignored on other events.  Both → AND (a specific
+ *     edge).  Neither → unfiltered.
+ *
+ * ```typescript
+ * const el = document.createElement('jssm-on');
+ * el.setAttribute('event', 'entry');
+ * el.setAttribute('state', 'paid');
+ * el.setAttribute('handler', 'onPaid');
+ * parse_jssm_on_element(el);
+ * // => { event: 'entry', handler_name: 'onPaid', inline_body: undefined,
+ * //      once: false, name: undefined, filter: { state: 'paid' } }
+ * ```
+ *
+ * @param el - The `<jssm-on>` element to parse.
+ * @returns A validated {@link ParsedJssmOn} record.
+ * @throws If `event` is missing, unknown, both handler forms are
+ *         supplied, or neither handler form is supplied.
+ */
+function parse_jssm_on_element(el) {
+    const event_attr = el.getAttribute('event');
+    if (event_attr === null || event_attr.trim().length === 0) {
+        throw new Error('<jssm-on>: missing required `event` attribute');
+    }
+    const event = event_attr.trim();
+    if (!JSSM_ON_EVENT_NAMES.has(event)) {
+        throw new Error(`<jssm-on>: unknown event "${event}"`);
+    }
+    const handler_attr = el.getAttribute('handler');
+    const handler_name = (handler_attr !== null && handler_attr.trim().length > 0)
+        ? handler_attr.trim()
+        : undefined;
+    // textContent on a connected HTMLElement is always a string, so the
+    // historical `?? ''` fallback never executed.  Use a direct cast here
+    // and let test cases that supply a literal `null` (defensive coverage)
+    // hit the `=== null` branch instead — that branch is reachable via
+    // Object.defineProperty in tests, where the `??` form would be a dead
+    // operator.
+    const body_text = el.textContent;
+    const inline_body = (body_text !== null && body_text.trim().length > 0) ? body_text : undefined;
+    if (handler_name !== undefined && inline_body !== undefined) {
+        throw new Error('<jssm-on>: specify handler="name" OR inline body, not both');
+    }
+    if (handler_name === undefined && inline_body === undefined) {
+        throw new Error('<jssm-on>: must specify handler="name" or an inline body');
+    }
+    const once_attr = el.hasAttribute('once');
+    const name_attr = el.getAttribute('name');
+    const name = (name_attr !== null && name_attr.trim().length > 0) ? name_attr.trim() : undefined;
+    // Build the filter, but only honour attributes that apply to this event.
+    // Unknown filter attributes for an event are silently ignored, matching
+    // the documented semantics in the issue.
+    let filter;
+    if (event === 'entry' || event === 'exit') {
+        const state_attr = el.getAttribute('state');
+        if (state_attr !== null && state_attr.length > 0) {
+            filter = { state: state_attr };
+        }
+    }
+    else if (event === 'transition') {
+        const from_attr = el.getAttribute('from');
+        const to_attr = el.getAttribute('to');
+        const candidate = {};
+        if (from_attr !== null && from_attr.length > 0) {
+            candidate.from = from_attr;
+        }
+        if (to_attr !== null && to_attr.length > 0) {
+            candidate.to = to_attr;
+        }
+        if (Object.keys(candidate).length > 0) {
+            filter = candidate;
+        }
+    }
+    return {
+        event,
+        handler_name,
+        inline_body,
+        once: once_attr,
+        name,
+        filter
+    };
+}
+/**
+ * Optional global registry that `<jssm-on>` (and, later, `<jssm-hook>`)
+ * consult first when resolving a `handler="name"` attribute.  Consumers
+ * register named handlers here in a strict-CSP environment where a stray
+ * `globalThis[name]` isn't acceptable.  Falls through to `globalThis[name]`
+ * if the registry has no entry.
+ *
+ * Intentionally a `Map<string, Function>` rather than a class with methods,
+ * so consumers can use any of `.get`, `.set`, `.delete`, `.clear` directly
+ * without a thin wrapper API.
+ */
+const jssm_handler_registry = new Map();
+/**
+ * Resolve a named handler from the registry, then from `globalThis`.
+ * Throws if neither lookup finds a function — earlier failure here is
+ * better than a delayed "is not a function" at first event delivery.
+ *
+ * @param name - The handler name as supplied by `handler="..."`.
+ * @returns The resolved function.
+ * @throws If no function is registered under `name`.
+ */
+function resolve_named_handler(name) {
+    const from_registry = jssm_handler_registry.get(name);
+    if (typeof from_registry === 'function') {
+        return from_registry;
+    }
+    const from_global = globalThis[name];
+    if (typeof from_global === 'function') {
+        return from_global;
+    }
+    throw new Error(`<jssm-on>: handler "${name}" not found in registry or globalThis`);
+}
+/**
+ * Compile an inline-body string into a handler function whose single
+ * parameter is `e` (the event detail object).  Uses the same dynamic
+ * `Function(...)` constructor that browsers use internally for inline
+ * event-handler attributes such as `<a onclick="...">`; the input here
+ * is consumer-authored markup, never network data, so the surface is
+ * exactly that of an inline event-handler attribute and the same CSP
+ * caveats apply (strict CSP without `'unsafe-eval'` blocks it).  A
+ * `//# sourceURL=jssm-on:N` pragma is appended so devtools stack traces
+ * point at a meaningful name.
+ *
+ * @param body - The inline JS body (function body, not full function).
+ * @param source_id - A short identifier for the sourceURL pragma.
+ * @returns The compiled handler.
+ */
+function compile_inline_body(body, source_id) {
+    const wrapped = `${body}\n//# sourceURL=jssm-on:${source_id}`;
+    // The Function constructor is intentional here — see the docblock above
+    // for the rationale and the CSP caveat.  Equivalent to how browsers wire
+    // up inline event handlers; the input is consumer-authored markup.
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+    return new Function('e', wrapped); // skipcq: JS-0086
+}
 /**
  * Resolve a `<jssm-instance>`'s FSL source from the three legal channels:
  * the `fsl=""` attribute, a child `<script type="text/fsl">`, and the
@@ -318,44 +705,33 @@ class JssmInstance extends LitElement {
          * connection.
          */
         this._machine = undefined;
+        /**
+         * Live unsubscribe callbacks for #645 `<jssm-bind>` / `data-jssm-bind`
+         * projections.  Every entry must be invoked exactly once during
+         * {@link disconnectedCallback}.
+         */
+        this._unsubs = [];
+        /**
+         * Unsubscribe callbacks for every `machine.on(...)` / `machine.once(...)`
+         * subscription installed from a `<jssm-on>` child during
+         * `connectedCallback`.  Walked in `disconnectedCallback`.
+         */
+        this._on_unsubscribes = [];
         /**
          * Per-instance registry of named hook handlers consulted before
          * `globalThis` when resolving `<jssm-hook handler="name">`.
-         *
-         * Initialized to an empty `Map`; consumers may populate it before the
-         * element connects to provide handlers without polluting global scope —
-         * useful for module-scoped SPAs where strict CSP blocks inline-body hooks.
-         *
-         * @see {@link parse_hook_element}
          */
         this.registry = new Map();
         /**
-         * Descriptors for hooks this WC installed at connect time, used in
-         * `disconnectedCallback` to call `remove_hook` for each so the underlying
-         * machine doesn't leak handlers when the element is detached.
-         *
-         * Captured at install time because `remove_hook` matches by descriptor
-         * shape (not handler identity), and we need to record the wrapped handler
-         * we passed to `set_hook` to undo the registration cleanly.  Stored as
-         * `unknown[]` and cast at the call site because jssm's `HookDescription`
-         * is a discriminated union whose discriminator is only known at runtime.
+         * Descriptors for hooks this WC installed at connect time.
          */
         this._installed_hooks = [];
         /**
-         * Counter used to give each compiled inline-body hook a unique debug id
-         * for its `//# sourceURL=jssm-hook:N` annotation.  Per-instance so that
-         * multiple `<jssm-instance>` elements on a page don't share numbering.
+         * Counter for compiled inline-body hook debug ids.
          */
         this._hook_debug_counter = 0;
         /**
-         * Records every DOM listener installed by `<jssm-action>` / `data-jssm-action`
-         * discovery so {@link disconnectedCallback} can remove each one with the
-         * same handler reference originally passed to `addEventListener`.
-         *
-         * Listeners installed via the dedicated `<jssm-action>` tag form may target
-         * elements outside the host (its `selector` is resolved against the host,
-         * but matching elements live in the document tree), so cleanup must be
-         * explicit — relying on the host's GC is not sufficient.
+         * DOM listeners installed by `<jssm-action>` / `data-jssm-action` discovery.
          */
         this._action_listeners = [];
     }
@@ -424,9 +800,54 @@ class JssmInstance extends LitElement {
         //            and dispatch DOM CustomEvents from this element.
         // #641: <jssm-hook> declarative discovery.
         this._install_declarative_hooks();
-        // TODO #643: <jssm-on> discovery happens here.
+        // #643: <jssm-on> declarative event observation.
+        this._install_jssm_on_children();
+        // #645: discover <jssm-bind> tags and `data-jssm-bind` descendants,
+        // install live machine-to-DOM projections.
+        this._unsubs.push(...install_bindings(this, this._machine));
+        // #640: <jssm-action> DOM event → machine action wiring.
         this._discover_jssm_actions();
-        // TODO #645: <jssm-bind> discovery happens here.
+    }
+    /**
+     * Discover direct-child `<jssm-on>` elements and install their
+     * subscriptions on the owned machine.  Per #643:
+     *
+     * - Direct children only (`:scope > jssm-on`).  Deeper nesting is the
+     *   responsibility of a future MutationObserver-driven v2.
+     * - Each `<jssm-on>` is parsed by {@link parse_jssm_on_element}, which
+     *   enforces the form / event-name / filter rules.
+     * - Handlers come from {@link resolve_named_handler} (form A) or
+     *   {@link compile_inline_body} (form B), and the result is installed
+     *   via `machine.on(...)` or `machine.once(...)` depending on the
+     *   element's `once` attribute.
+     * - Every returned unsubscribe is tracked in {@link _on_unsubscribes}
+     *   so {@link disconnectedCallback} can release them all.
+     *
+     * Called once from `connectedCallback` after the machine has been
+     * constructed.  Any error thrown by parsing or resolution propagates
+     * out so it surfaces via jsdom's error event (matching the rest of
+     * `<jssm-instance>`'s "fail loud at connect" policy).
+     */
+    _install_jssm_on_children() {
+        const machine = this._machine;
+        const on_nodes = this.querySelectorAll(':scope > jssm-on');
+        let index = 0;
+        for (const el of Array.from(on_nodes)) {
+            index += 1;
+            const parsed = parse_jssm_on_element(el);
+            const handler = parsed.handler_name !== undefined
+                ? resolve_named_handler(parsed.handler_name)
+                : compile_inline_body(parsed.inline_body, String(index));
+            // Argument shape: machine.on(name, handler) when no filter, or
+            // machine.on(name, filter, handler) when filtered.  Same for once.
+            // `as any` collapses the per-event detail typing — the WC is a
+            // schema-erased entry point and the type-safety belongs upstream.
+            const subscribe = parsed.once ? machine.once.bind(machine) : machine.on.bind(machine);
+            const unsubscribe = parsed.filter === undefined
+                ? subscribe(parsed.event, handler)
+                : subscribe(parsed.event, parsed.filter, handler);
+            this._on_unsubscribes.push(unsubscribe);
+        }
     }
     /**
      * Discover every direct-child `<jssm-hook>` element and install each
@@ -434,17 +855,6 @@ class JssmInstance extends LitElement {
      * adapter that lets user code write `m.data = ...` and return `false` to
      * cancel — see {@link make_hook_proxy} and the issue (#641) doc-comment
      * for the full contract.
-     *
-     * Direct children only (the `:scope > jssm-hook` selector) so that nested
-     * `<jssm-instance>` elements don't have their child hooks installed on
-     * the outer machine.
-     *
-     * Tracks every installed descriptor in `_installed_hooks` so that
-     * `disconnectedCallback` can remove them on detach.
-     *
-     * @throws Error - On a malformed `<jssm-hook>` (mutual-exclusion violation,
-     *                 unknown kind, unresolved name, or jssm's own missing-key
-     *                 errors from `set_hook`).
      */
     _install_declarative_hooks() {
         const machine = this._machine;
@@ -454,35 +864,26 @@ class JssmInstance extends LitElement {
             const spec = parse_hook_element(el, debug_id, this.registry);
             const wrapped = wrap_user_handler(spec, machine);
             const desc = build_hook_descriptor(spec, wrapped);
-            // `desc` is shaped from runtime kind discrimination; jssm's typed
-            // `HookDescription` is a static discriminated union that TS can't
-            // unify with our runtime-built object, hence the cast.
             machine.set_hook(desc);
             this._installed_hooks.push(desc);
         }
     }
     /**
      * Prefix used in synthetic `//# sourceURL=jssm-hook:<prefix><n>` annotations
-     * for inline-body hooks compiled by this element.  Includes the element's
-     * `id` when present so multi-instance pages can tell sources apart in
-     * devtools.
+     * for inline-body hooks compiled by this element.
      */
     _hook_id_prefix() {
         const host_id = this.getAttribute('id');
         return host_id !== null && host_id.length > 0 ? `${host_id}-` : '';
     }
     /**
-     * Lifecycle hook.  Removes every hook this WC installed via
-     * `<jssm-hook>` discovery so the underlying machine doesn't leak handlers
-     * when the element detaches.  Called automatically by the browser; the
-     * machine itself is not destroyed (consumers can reuse it).
-     *
-     * Future tickets #638/#643/#645 will extend this to drop other
-     * subscriptions / listeners installed by their respective tags.
+     * Lifecycle hook.  Cleans up everything the WC installed at connect: hook
+     * registrations from `<jssm-hook>`, event subscriptions from `<jssm-on>`,
+     * and DOM listeners from `<jssm-action>` / `data-jssm-action`.
      */
     disconnectedCallback() {
         super.disconnectedCallback();
-        // TODO #638: unsubscribe from machine.on(...) handlers.
+        // TODO #638: unsubscribe from any direct machine.on(...) handlers added by host.
         // #641: remove installed hooks.
         if (this._machine !== undefined) {
             const machine = this._machine;
@@ -491,10 +892,20 @@ class JssmInstance extends LitElement {
             }
         }
         this._installed_hooks = [];
-        // TODO #643/#645: remove installed listeners / bindings.
-        // Remove every listener installed during `<jssm-action>` / `data-jssm-action`
-        // discovery.  Using the original handler reference ensures `removeEventListener`
-        // actually unbinds — anonymous re-creation here would silently leak.
+        // #643: release every subscription installed from a <jssm-on> child.
+        for (const off of this._on_unsubscribes) {
+            try {
+                off();
+            }
+            catch ( /* swallow — cleanup must not throw past us */_a) { /* swallow — cleanup must not throw past us */ }
+        }
+        this._on_unsubscribes = [];
+        // #645: tear down every live binding.
+        for (const off of this._unsubs) {
+            off();
+        }
+        this._unsubs = [];
+        // #640: remove DOM listeners installed via <jssm-action> / data-jssm-action.
         for (const entry of this._action_listeners) {
             entry.target.removeEventListener(entry.event, entry.handler);
         }
@@ -502,30 +913,12 @@ class JssmInstance extends LitElement {
     }
     /**
      * Wire DOM events to machine actions, using the two declarative forms from
-     * issue #640:
-     *
-     *  1. Inline attribute form: every descendant of the host carrying a
-     *     `data-jssm-action="<name>"` attribute receives a listener on the
-     *     event named by `data-jssm-event` (default `click`).
-     *  2. Dedicated tag form: each direct `<jssm-action>` child of the host
-     *     supplies a CSS `selector` (scoped to the host), an `action`, and an
-     *     optional `event` (default `click`); every matching descendant
-     *     receives a listener configured by the tag's attributes.
-     *
-     * Both forms support optional `from-state` guards (dispatch only when the
-     * machine's current state matches), `from-property` data extraction (pass
-     * the source element's named property as the action's data argument), and
-     * `prevent-default` / `stop-propagation` modifiers.
-     *
-     * Every installed listener is recorded in {@link _action_listeners} so
-     * {@link disconnectedCallback} can detach them cleanly.
+     * issue #640.  Both forms support optional `from-state` guards,
+     * `from-property` data extraction, and `prevent-default` /
+     * `stop-propagation` modifiers.
      */
     _discover_jssm_actions() {
         var _a, _b, _c, _d;
-        // Inline attribute form: `[data-jssm-action]` descendants.  Per the
-        // ticket, we scan the host's light DOM (not the shadow tree, which is
-        // owned by us) and skip any element living inside a `<jssm-action>` tag
-        // — those tags are pure data markup, never the source of an event.
         const inline_targets = Array.from(this.querySelectorAll('[data-jssm-action]')).filter(el => el.closest('jssm-action') === null);
         for (const el of inline_targets) {
             this._install_action_listener({
@@ -538,16 +931,11 @@ class JssmInstance extends LitElement {
                 stop_propagation: 'jssmStopPropagation' in el.dataset,
             });
         }
-        // Dedicated tag form: direct `<jssm-action>` children of the host.
-        // `:scope >` keeps a nested `<jssm-instance>`'s actions from being
-        // claimed by an outer host.
         const tags = this.querySelectorAll(':scope > jssm-action');
         for (const tag of Array.from(tags)) {
             const selector = tag.getAttribute('selector');
             const action_name = tag.getAttribute('action');
             if (selector === null || action_name === null) {
-                // Required attrs missing — skip, but don't throw: a malformed tag
-                // shouldn't break the rest of the host's wiring.
                 continue;
             }
             const event_name = (_b = tag.getAttribute('event')) !== null && _b !== void 0 ? _b : 'click';
@@ -571,18 +959,7 @@ class JssmInstance extends LitElement {
     }
     /**
      * Attach one DOM listener that translates a DOM event into a
-     * `machine.action(...)` call, honoring the configured modifiers.  The
-     * listener is recorded in {@link _action_listeners} so it can be removed
-     * on disconnect.
-     *
-     * @param config - Listener configuration.
-     * @param config.source - Element to attach the listener to.
-     * @param config.event_name - DOM event to listen for.
-     * @param config.action_name - Action to dispatch on the machine.
-     * @param config.from_state - If set, only fire when `machine.state() === from_state`.
-     * @param config.from_property - If set, pass `source[from_property]` as the action's data argument.
-     * @param config.prevent_default - If true, call `e.preventDefault()` before checking the guard.
-     * @param config.stop_propagation - If true, call `e.stopPropagation()` before checking the guard.
+     * `machine.action(...)` call, honoring the configured modifiers.
      */
     _install_action_listener(config) {
         const handler = (e) => {
@@ -592,7 +969,6 @@ class JssmInstance extends LitElement {
             if (config.stop_propagation) {
                 e.stopPropagation();
             }
-            // Guard: skip dispatch when the machine isn't in the required state.
             if (config.from_state !== undefined && this.state() !== config.from_state) {
                 return;
             }
@@ -696,4 +1072,4 @@ JssmInstance.properties = {
     fsl: { type: String, reflect: false },
 };
 
-export { JssmInstance, resolve_fsl_source };
+export { JSSM_ON_EVENT_NAMES, JssmInstance, compile_inline_body, jssm_handler_registry, parse_jssm_on_element, resolve_fsl_source, resolve_named_handler };