jssm 5.143.35 → 5.144.1

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.143.35 at 6/17/2026, 9:46:56 PM
+* Generated for version 5.144.0 at 6/21/2026, 3:13:56 PM
 
 -->
-# jssm 5.143.35
+# jssm 5.144.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,232 tests at 100.0% line coverage
+  library.**  7,305 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,232 tests***, run 82,274 times.
+***7,305 tests***, run 82,347 times.
 
-- 6,474 specs with 100.0% coverage
-- 758 fuzz tests with 76.8% coverage
-- 6,605 TypeScript lines - 1.1 tests per line, 12.5 generated tests per line
+- 6,547 specs with 100.0% coverage
+- 758 fuzz tests with 74.4% coverage
+- 6,801 TypeScript lines - 1.1 tests per line, 12.1 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/dist/cdn/instance.js

@@ -22922,6 +22922,9 @@ const base_active_state_style$5 = {
     textColor: 'white',
     backgroundColor: 'dodgerblue4'
 };
+const base_hooked_state_style$5 = {
+    shape: 'component'
+};
 const base_terminal_state_style$5 = {
     textColor: 'white',
     backgroundColor: 'crimson'
@@ -22938,6 +22941,7 @@ const base_theme = {
     start: base_start_state_style$5,
     end: base_end_state_style$5,
     terminal: base_terminal_state_style$5,
+    hooked: base_hooked_state_style$5,
     active: base_active_state_style$5};
 
 const base_state_style$4 = {
@@ -23370,6 +23374,30 @@ function pair_key(a, b) {
         ? (a * a) + a + b
         : (b * b) + a;
 }
+/**
+ * Inverse of {@link pair_key}: recovers the ordered pair `(a, b)` that was
+ * packed into a Szudzik key.  Exact for any key produced by `pair_key` over
+ * non-negative integer inputs, so `un_pair_key(pair_key(a, b))` round-trips
+ * to `[a, b]`.  Used to walk interned, pair-keyed maps (e.g. the hook tables)
+ * back to their original `(from_id, to_id)` ids for {@link Interner.name_of}.
+ *
+ * Behavior is only defined for keys `pair_key` actually emits; a NaN key (the
+ * unknown-name sentinel) yields `[NaN, NaN]`, never a spurious real pair.
+ *
+ * @param z - A key produced by `pair_key`.
+ * @returns The ordered pair `[a, b]` such that `pair_key(a, b) === z`.
+ *
+ * @example
+ *   un_pair_key(27);  // [2, 5]
+ *   un_pair_key(32);  // [5, 2] — order preserved
+ *
+ * @see pair_key
+ */
+function un_pair_key(z) {
+    const s = Math.floor(Math.sqrt(z));
+    const l = z - (s * s);
+    return (l < s) ? [l, s] : [s, l - s];
+}
 
 /*******
  *
@@ -23486,7 +23514,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.143.35";
+const version = "5.144.1";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -25889,6 +25917,12 @@ class Machine {
             default:
                 throw new JssmError(this, `Unknown hook type ${HookDesc.kind}, should be impossible`);
         }
+        // The hooked-state styling layer (tier 2.5 of resolve_state_config) depends
+        // on which states carry hooks, so registering a hook can change the composed
+        // style of a state.  The static config cache assumes tiers 1–5 are fixed
+        // after construction; invalidate it so styling stays correct when a hook is
+        // added after a style has already been computed and memoized.
+        this._static_state_config_cache.clear();
         // fire the registration event for inspector tools (#638)
         this._fire('hook-registration', { description: HookDesc });
     }
@@ -26061,6 +26095,9 @@ class Machine {
                 throw new JssmError(this, `Unknown hook type ${HookDesc.kind}, should be impossible`);
         }
         if (removed) {
+            // See set_hook: the hooked-state styling layer depends on which states
+            // carry hooks, so removing one can change a state's composed style.
+            this._static_state_config_cache.clear();
             this._fire('hook-removal', { description: HookDesc });
         }
         return removed;
@@ -27387,12 +27424,319 @@ class Machine {
     get active_state_style() {
         return this._active_state_style;
     }
-    /*
+    /********
+     *
+     *  Generate the uniform observational-hook registry — every currently
+     *  registered hook projected onto a normalized `(kind, target, phase)` row
+     *  (megaspec §12, → #1357).  The registry is *generated* on demand by
+     *  walking the concrete per-kind storage tables rather than maintained as a
+     *  second copy, so it can never drift from the tables {@link Machine.set_hook}
+     *  actually dispatches into.  It is the single source of truth behind the
+     *  introspection accessors ({@link Machine.has_hook}, {@link Machine.hooks_on})
+     *  and the `hooked_state` viz styling.
+     *
+     *  Targets are normalized: edge hooks become `{ scope: 'edge', from, to }`
+     *  (named hooks add `action`), entry/exit/after become `{ scope: 'state' }`,
+     *  global-action hooks become `{ scope: 'action' }`, and the `any-*`,
+     *  transition-class, and `everything` observers become `{ scope: 'global' }`.
+     *
+     *  ```typescript
+     *  const m = sm`a 'go' -> b;`;
+     *  m.hook_entry('b', () => true);
+     *  m.hook_registry();
+     *  // => [ { kind: 'entry', phase: 'pre', target: { scope: 'state', state: 'b' } } ]
+     *  ```
+     *
+     *  @returns Every registered hook as a {@link HookRegistryEntry}, in a stable
+     *  table-walk order (pre-phase tables first, then post-phase).
+     *
      */
-    // TODO COMEBACK IMPLEMENTME FIXME
-    // has_hooks(state: StateType): false {
-    //   return false;
-    // }
+    hook_registry() {
+        const entries = [];
+        // The hot-path hook tables are keyed by interned integer ids (states and
+        // actions) and, for edges, by `pair_key(from_id, to_id)`.  Decode each key
+        // back to its original name so the registry speaks states/actions, never
+        // ids.  The lone exception is `_after_hooks`, deliberately string-keyed.
+        const state_name = (id) => this._state_interner.name_of(id);
+        const action_name = (id) => this._action_interner.name_of(id);
+        // edge tables: pair_key(from_id, to_id) -> handler
+        const push_edges = (table, kind, phase) => {
+            table.forEach((_handler, pk) => {
+                const [fid, tid] = un_pair_key(pk);
+                entries.push({ kind, phase, target: { scope: 'edge', from: state_name(fid), to: state_name(tid) } });
+            });
+        };
+        // named-edge tables: pair_key(from_id, to_id) -> action_id -> handler
+        const push_named = (table, kind, phase) => {
+            table.forEach((byAction, pk) => {
+                const [fid, tid] = un_pair_key(pk);
+                const from = state_name(fid), to = state_name(tid);
+                byAction.forEach((_handler, aid) => {
+                    entries.push({ kind, phase, target: { scope: 'edge', from, to, action: action_name(aid) } });
+                });
+            });
+        };
+        // entry/exit tables: interned state_id -> handler
+        const push_states = (table, kind, phase) => {
+            table.forEach((_handler, sid) => {
+                entries.push({ kind, phase, target: { scope: 'state', state: state_name(sid) } });
+            });
+        };
+        // the `after` table is the lone string-keyed exception: state name -> handler
+        const push_states_by_name = (table, kind, phase) => {
+            table.forEach((_handler, state) => {
+                entries.push({ kind, phase, target: { scope: 'state', state: state } });
+            });
+        };
+        // global-action tables: interned action_id -> handler
+        const push_actions = (table, kind, phase) => {
+            table.forEach((_handler, aid) => {
+                entries.push({ kind, phase, target: { scope: 'action', action: action_name(aid) } });
+            });
+        };
+        const push_global = (handler, kind, phase) => {
+            if (handler !== undefined) {
+                entries.push({ kind, phase, target: { scope: 'global' } });
+            }
+        };
+        // FSL boundary hooks: subject name -> { onEnter?, onExit? }, fired post-
+        // commit.  Each present direction becomes its own row, all phase 'post'.
+        const push_boundary = (table, enterKind, exitKind, target_of) => {
+            table.forEach((bh, subject) => {
+                if (bh.onEnter !== undefined) {
+                    entries.push({ kind: enterKind, phase: 'post', target: target_of(subject) });
+                }
+                if (bh.onExit !== undefined) {
+                    entries.push({ kind: exitKind, phase: 'post', target: target_of(subject) });
+                }
+            });
+        };
+        // pre-phase, edge- and state-keyed tables
+        push_edges(this._hooks, 'hook', 'pre');
+        push_named(this._named_hooks, 'named', 'pre');
+        push_states(this._entry_hooks, 'entry', 'pre');
+        push_states(this._exit_hooks, 'exit', 'pre');
+        push_states_by_name(this._after_hooks, 'after', 'pre');
+        push_actions(this._global_action_hooks, 'global action', 'pre');
+        // pre-phase, global singletons
+        push_global(this._any_action_hook, 'any action', 'pre');
+        push_global(this._standard_transition_hook, 'standard transition', 'pre');
+        push_global(this._main_transition_hook, 'main transition', 'pre');
+        push_global(this._forced_transition_hook, 'forced transition', 'pre');
+        push_global(this._any_transition_hook, 'any transition', 'pre');
+        push_global(this._pre_everything_hook, 'pre everything', 'pre');
+        push_global(this._everything_hook, 'everything', 'pre');
+        // post-phase, edge- and state-keyed tables
+        push_edges(this._post_hooks, 'post hook', 'post');
+        push_named(this._post_named_hooks, 'post named', 'post');
+        push_states(this._post_entry_hooks, 'post entry', 'post');
+        push_states(this._post_exit_hooks, 'post exit', 'post');
+        push_actions(this._post_global_action_hooks, 'post global action', 'post');
+        // post-phase, global singletons
+        push_global(this._post_any_action_hook, 'post any action', 'post');
+        push_global(this._post_standard_transition_hook, 'post standard transition', 'post');
+        push_global(this._post_main_transition_hook, 'post main transition', 'post');
+        push_global(this._post_forced_transition_hook, 'post forced transition', 'post');
+        push_global(this._post_any_transition_hook, 'post any transition', 'post');
+        push_global(this._pre_post_everything_hook, 'pre post everything', 'post');
+        push_global(this._post_everything_hook, 'post everything', 'post');
+        // FSL boundary hooks (post-commit): group and plain-state subjects
+        push_boundary(this._group_hooks, 'group enter', 'group exit', (group) => ({ scope: 'group', group }));
+        push_boundary(this._state_hooks, 'state enter', 'state exit', (state) => ({ scope: 'state', state: state }));
+        return entries;
+    }
+    /********
+     *
+     *  Does a single registry entry reference the state `state`?  An entry
+     *  references a state when it is a `'state'`-scoped hook on that state, or an
+     *  `'edge'`-scoped hook whose `from` or `to` is that state.  `'action'`- and
+     *  `'global'`-scoped entries reference no particular state.  This is the
+     *  predicate behind both per-state introspection and the `hooked_state`
+     *  styling layer.
+     *
+     *  @param entry The registry entry to test.
+     *  @param state The state name to test membership of.
+     *  @returns `true` when the entry observes that state.
+     *
+     */
+    static _entry_touches_state(entry, state) {
+        const t = entry.target;
+        if (t.scope === 'state') {
+            return t.state === state;
+        }
+        if (t.scope === 'edge') {
+            return t.from === state || t.to === state;
+        }
+        return false;
+    }
+    /********
+     *
+     *  Does a single registry entry match a `{ from, to, action? }` edge query?
+     *  Only `'edge'`-scoped entries can match.  When the query omits `action`
+     *  the entry's action (if any) is ignored; when the query supplies `action`
+     *  it must match exactly.
+     *
+     *  @param entry The registry entry to test.
+     *  @param from  The edge origin to match.
+     *  @param to    The edge destination to match.
+     *  @param action Optional named action to match exactly.
+     *  @returns `true` when the entry observes that edge.
+     *
+     */
+    static _entry_matches_edge(entry, from, to, action) {
+        const t = entry.target;
+        if (t.scope !== 'edge') {
+            return false;
+        }
+        if (t.from !== from || t.to !== to) {
+            return false;
+        }
+        if (action !== undefined) {
+            return t.action === action;
+        }
+        return true;
+    }
+    /********
+     *
+     *  Does a single registry entry match an action name?  Both `'action'`-scoped
+     *  hooks (global-action hooks) and named-edge hooks carrying that action
+     *  count as matches.
+     *
+     *  @param entry  The registry entry to test.
+     *  @param action The action name to match.
+     *  @returns `true` when the entry observes that action.
+     *
+     */
+    static _entry_matches_action(entry, action) {
+        const t = entry.target;
+        if (t.scope === 'action') {
+            return t.action === action;
+        }
+        if (t.scope === 'edge') {
+            return t.action === action;
+        }
+        return false;
+    }
+    /********
+     *
+     *  Does a single registry entry match a named state group?  Only
+     *  `'group'`-scoped entries (FSL group-boundary hooks) match.  Group hooks
+     *  are matched by group name only — they deliberately do not propagate to
+     *  member states, so a member-state query never returns them.
+     *
+     *  @param entry The registry entry to test.
+     *  @param group The group name to match.
+     *  @returns `true` when the entry observes that group's boundary.
+     *
+     */
+    static _entry_matches_group(entry, group) {
+        const t = entry.target;
+        if (t.scope === 'group') {
+            return t.group === group;
+        }
+        return false;
+    }
+    /********
+     *
+     *  Return every registry entry observing the given target (megaspec §12).
+     *  The `query` selects the target shape:
+     *
+     *  - a bare **state name** matches entry/exit/after hooks on that state, its
+     *    state-boundary hooks, and every edge hook touching it (`from` or `to`),
+     *  - a `{ from, to, action? }` **edge** matches edge hooks on that
+     *    transition (optionally narrowed to the named action),
+     *  - a `{ action }` **action** matches global-action and named-edge hooks
+     *    carrying that action,
+     *  - a `{ group }` **group** matches that group's boundary hooks (group hooks
+     *    are matched by name only and do not propagate to member states).
+     *
+     *  ```typescript
+     *  const m = sm`a 'go' -> b;`;
+     *  m.hook_entry('b', () => true);
+     *  m.hooks_on('b').length;             // 1
+     *  m.hooks_on({ from: 'a', to: 'b' }); // []  (no edge hook registered)
+     *  ```
+     *
+     *  @param query The {@link HookQuery} naming the target to inspect.
+     *  @returns The matching {@link HookRegistryEntry} rows (possibly empty).
+     *
+     */
+    hooks_on(query) {
+        const registry = this.hook_registry();
+        if (typeof query === 'string') {
+            return registry.filter(e => Machine._entry_touches_state(e, query));
+        }
+        // An edge query is distinguished by carrying `from` (it may *also* carry
+        // `action`, which narrows the edge — so this must be tested before the
+        // action-only case, whose discriminator `action` an edge query can share).
+        if ('from' in query) {
+            return registry.filter(e => Machine._entry_matches_edge(e, query.from, query.to, query.action));
+        }
+        if ('group' in query) {
+            return registry.filter(e => Machine._entry_matches_group(e, query.group));
+        }
+        return registry.filter(e => Machine._entry_matches_action(e, query.action));
+    }
+    /********
+     *
+     *  Is at least one observational hook bound to the given target (megaspec
+     *  §12)?  The `query` is read exactly as in {@link Machine.hooks_on}.  An
+     *  optional `phase` narrows the test to pre- or post-transition hooks only;
+     *  omitted, either phase satisfies it.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b;`;
+     *  m.has_hook('b');                 // false
+     *  m.hook_entry('b', () => true);
+     *  m.has_hook('b');                 // true
+     *  m.has_hook('b', 'post');         // false  (the entry hook is pre-phase)
+     *  ```
+     *
+     *  @param query The {@link HookQuery} naming the target to inspect.
+     *  @param phase Optional {@link HookPhase} to restrict the test to.
+     *  @returns `true` when a matching hook exists.
+     *
+     */
+    has_hook(query, phase) {
+        const matches = this.hooks_on(query);
+        if (phase === undefined) {
+            return matches.length > 0;
+        }
+        return matches.some(e => e.phase === phase);
+    }
+    /********
+     *
+     *  Does the given state carry any observational hook — i.e. should it receive
+     *  the `hooked_state` viz styling?  True when an entry/exit/after hook is
+     *  bound to the state, any edge hook touches it, or the state has its own
+     *  boundary hook.  Group-boundary hooks do *not* count here — they are
+     *  matched by group only and never propagate to member states.  Powers the
+     *  `hooked` styling layer in {@link Machine.resolve_state_config}; replaces
+     *  the long-stubbed `has_hooks` placeholder (megaspec §12).
+     *
+     *  ```typescript
+     *  const m = sm`a -> b;`;
+     *  m.state_has_hooks('a');          // false
+     *  m.hook_exit('a', () => true);
+     *  m.state_has_hooks('a');          // true
+     *  ```
+     *
+     *  @param state The state to test.
+     *  @returns `true` when the state is observed by at least one hook.
+     *
+     */
+    state_has_hooks(state) {
+        // Boundary hooks are a separate mechanism that sets neither _has_hooks nor
+        // _has_post_hooks, so the fast-out must also consult the boundary tables —
+        // otherwise a state whose only hook is a boundary hook reports unhooked.
+        if (!this._has_hooks
+            && !this._has_post_hooks
+            && (this._state_hooks.size === 0)
+            && (this._group_hooks.size === 0)) {
+            return false;
+        }
+        return this.hook_registry().some(e => Machine._entry_touches_state(e, state));
+    }
     /********
      *
      *  Returns the list of resolved theme implementations for this machine, in
@@ -27530,6 +27874,17 @@ class Machine {
         });
         // tier 2 — default_state_config (implicit root over all states)
         acc = merge_state_config(acc, this._state_style);
+        // tier 2.5 — hooked-state styling, applied when the state carries any
+        // observational or boundary hook.  Sits above the root default and below
+        // the per-kind/group/per-state tiers, preserving the historical layer
+        // order the pre-cascade `style_for` used.  See {@link state_has_hooks}.
+        if (this.state_has_hooks(state)) {
+            acc = merge_state_config(acc, base_theme.hooked);
+            themes.forEach(theme => { if (theme.hooked) {
+                acc = merge_state_config(acc, theme.hooked);
+            } });
+            acc = merge_state_config(acc, this._hooked_state_style);
+        }
         // tier 3 — static per-kind defaults, selected by structural kind
         if (this.state_is_terminal(state)) {
             acc = merge_state_config(acc, base_theme.terminal);