jssm 5.144.5 → 5.144.8

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.144.5 at 6/22/2026, 10:56:54 AM
+* Generated for version 5.144.8 at 6/22/2026, 3:15:53 PM
 
 -->
-# jssm 5.144.5
+# jssm 5.144.8
 
 [**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,316 tests at 100.0% line coverage
+  library.**  7,328 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,316 tests***, run 82,358 times.
+***7,328 tests***, run 82,370 times.
 
-- 6,558 specs with 100.0% coverage
+- 6,570 specs with 100.0% coverage
 - 758 fuzz tests with 73.9% coverage
-- 6,888 TypeScript lines - 1.1 tests per line, 12.0 generated tests per line
+- 6,936 TypeScript lines - 1.1 tests per line, 11.9 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

@@ -20755,7 +20755,7 @@ const weighted_rand_select = (options, probability_property = 'probability', rng
  *  Returns, for a non-negative integer argument `n`, the series `[0 .. n]`.
  *
  *  ```typescript
- *  import { seq } from './jssm';
+ *  import { seq } from './jssm.js';
  *
  *  seq(5);  // [0, 1, 2, 3, 4]
  *  seq(0);  // []
@@ -20779,7 +20779,7 @@ function seq(n) {
  *  with deep equality; will fail for complex contents, as such.
  *
  *  ```typescript
- *  import { histograph } from './jssm';
+ *  import { histograph } from './jssm.js';
  *
  *  histograph( [0, 0, 1, 1, 2, 2, 1] );  // Map()
  *  ```
@@ -23512,11 +23512,48 @@ 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.144.5";
+const version = "5.144.8";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
 const empty_string_set = new Set();
+// The spatial fields (besides `handler`, which every hook needs) that each
+// hook kind requires, mirroring exactly what `set_hook` reads per case.  Used
+// to validate a HookDescription so a mis-shaped one is rejected rather than
+// silently registering a dead hook — e.g. an `exit` hook given `to` instead of
+// `from` would otherwise intern `undefined` and never fire (#734).  Typed as a
+// `Record` over the kind union so the table is exhaustive at compile time:
+// adding a hook kind without listing its fields is a build error.
+const hook_required_fields = {
+    'hook': ['from', 'to'],
+    'named': ['from', 'to', 'action'],
+    'global action': ['action'],
+    'any action': [],
+    'standard transition': [],
+    'main transition': [],
+    'forced transition': [],
+    'any transition': [],
+    'entry': ['to'],
+    'exit': ['from'],
+    'after': ['from'],
+    'post hook': ['from', 'to'],
+    'post named': ['from', 'to', 'action'],
+    'post global action': ['action'],
+    'post any action': [],
+    'post standard transition': [],
+    'post main transition': [],
+    'post forced transition': [],
+    'post any transition': [],
+    'post entry': ['to'],
+    'post exit': ['from'],
+    'pre everything': [],
+    'everything': [],
+    'pre post everything': [],
+    'post everything': [],
+};
+// The spatial fields a hook descriptor can carry, checked against the per-kind
+// requirements above.
+const hook_spatial_fields = ['from', 'to', 'action'];
 /*********
  *
  *  An internal method meant to take a series of declarations and fold them into
@@ -25774,7 +25811,44 @@ class Machine {
      *  calling this directly.
      *  @param HookDesc - A hook descriptor specifying kind, states, and handler.
      */
+    /**
+     *  Validate a {@link HookDescription} before registration.  Every hook needs
+     *  a `handler` function, and each kind's identifying spatial fields
+     *  (`from`/`to`/`action`) must be exactly those `set_hook` reads for that
+     *  kind — present when required, absent otherwise.  This turns a mis-shaped
+     *  descriptor into a thrown error instead of a silently dead hook keyed on
+     *  `undefined` (e.g. an `exit` hook handed `to` instead of `from`, #734).
+     *
+     *  @param HookDesc - The descriptor about to be registered.
+     *  @throws JssmError if the kind is unknown, the handler is not a function, a
+     *          required field is missing, or an inapplicable field is present.
+     *
+     *  @example
+     *    const m = sm`a -> b;`;
+     *    // an exit hook is keyed by `from`, so supplying `to` is rejected:
+     *    expect(() => m.set_hook({ kind: 'exit', to: 'a', handler: () => true })).toThrow();
+     */
+    _validate_hook_description(HookDesc) {
+        const required = hook_required_fields[HookDesc.kind];
+        if (required === undefined) {
+            throw new JssmError(this, `unknown hook kind ${JSON.stringify(HookDesc.kind)}`);
+        }
+        if (typeof HookDesc.handler !== 'function') {
+            throw new JssmError(this, `${HookDesc.kind} hook requires a handler function`);
+        }
+        for (const field of hook_spatial_fields) {
+            const needed = required.includes(field);
+            const present = HookDesc[field] !== undefined;
+            if (needed && !present) {
+                throw new JssmError(this, `${HookDesc.kind} hook requires '${field}'`);
+            }
+            if (!needed && present) {
+                throw new JssmError(this, `${HookDesc.kind} hook does not take '${field}'`);
+            }
+        }
+    }
     set_hook(HookDesc) {
+        this._validate_hook_description(HookDesc);
         switch (HookDesc.kind) {
             case 'hook': {
                 // Numeric pair key (#729).  intern() rather than id_of(): a hook may
@@ -25916,8 +25990,8 @@ class Machine {
                 this._post_everything_hook = HookDesc.handler;
                 this._has_post_hooks = true;
                 break;
-            default:
-                throw new JssmError(this, `Unknown hook type ${HookDesc.kind}, should be impossible`);
+            // No default: `_validate_hook_description` above rejects any unknown kind
+            // before we reach here, so the switch is exhaustive over the known kinds.
         }
         // 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

package/dist/cdn/viz.js

@@ -20780,7 +20780,7 @@ const weighted_rand_select = (options, probability_property = 'probability', rng
  *  Returns, for a non-negative integer argument `n`, the series `[0 .. n]`.
  *
  *  ```typescript
- *  import { seq } from './jssm';
+ *  import { seq } from './jssm.js';
  *
  *  seq(5);  // [0, 1, 2, 3, 4]
  *  seq(0);  // []
@@ -20804,7 +20804,7 @@ function seq(n) {
  *  with deep equality; will fail for complex contents, as such.
  *
  *  ```typescript
- *  import { histograph } from './jssm';
+ *  import { histograph } from './jssm.js';
  *
  *  histograph( [0, 0, 1, 1, 2, 2, 1] );  // Map()
  *  ```
@@ -23537,11 +23537,48 @@ 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.144.5";
+const version = "5.144.8";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
 const empty_string_set = new Set();
+// The spatial fields (besides `handler`, which every hook needs) that each
+// hook kind requires, mirroring exactly what `set_hook` reads per case.  Used
+// to validate a HookDescription so a mis-shaped one is rejected rather than
+// silently registering a dead hook — e.g. an `exit` hook given `to` instead of
+// `from` would otherwise intern `undefined` and never fire (#734).  Typed as a
+// `Record` over the kind union so the table is exhaustive at compile time:
+// adding a hook kind without listing its fields is a build error.
+const hook_required_fields = {
+    'hook': ['from', 'to'],
+    'named': ['from', 'to', 'action'],
+    'global action': ['action'],
+    'any action': [],
+    'standard transition': [],
+    'main transition': [],
+    'forced transition': [],
+    'any transition': [],
+    'entry': ['to'],
+    'exit': ['from'],
+    'after': ['from'],
+    'post hook': ['from', 'to'],
+    'post named': ['from', 'to', 'action'],
+    'post global action': ['action'],
+    'post any action': [],
+    'post standard transition': [],
+    'post main transition': [],
+    'post forced transition': [],
+    'post any transition': [],
+    'post entry': ['to'],
+    'post exit': ['from'],
+    'pre everything': [],
+    'everything': [],
+    'pre post everything': [],
+    'post everything': [],
+};
+// The spatial fields a hook descriptor can carry, checked against the per-kind
+// requirements above.
+const hook_spatial_fields = ['from', 'to', 'action'];
 /*********
  *
  *  An internal method meant to take a series of declarations and fold them into
@@ -25799,7 +25836,44 @@ class Machine {
      *  calling this directly.
      *  @param HookDesc - A hook descriptor specifying kind, states, and handler.
      */
+    /**
+     *  Validate a {@link HookDescription} before registration.  Every hook needs
+     *  a `handler` function, and each kind's identifying spatial fields
+     *  (`from`/`to`/`action`) must be exactly those `set_hook` reads for that
+     *  kind — present when required, absent otherwise.  This turns a mis-shaped
+     *  descriptor into a thrown error instead of a silently dead hook keyed on
+     *  `undefined` (e.g. an `exit` hook handed `to` instead of `from`, #734).
+     *
+     *  @param HookDesc - The descriptor about to be registered.
+     *  @throws JssmError if the kind is unknown, the handler is not a function, a
+     *          required field is missing, or an inapplicable field is present.
+     *
+     *  @example
+     *    const m = sm`a -> b;`;
+     *    // an exit hook is keyed by `from`, so supplying `to` is rejected:
+     *    expect(() => m.set_hook({ kind: 'exit', to: 'a', handler: () => true })).toThrow();
+     */
+    _validate_hook_description(HookDesc) {
+        const required = hook_required_fields[HookDesc.kind];
+        if (required === undefined) {
+            throw new JssmError(this, `unknown hook kind ${JSON.stringify(HookDesc.kind)}`);
+        }
+        if (typeof HookDesc.handler !== 'function') {
+            throw new JssmError(this, `${HookDesc.kind} hook requires a handler function`);
+        }
+        for (const field of hook_spatial_fields) {
+            const needed = required.includes(field);
+            const present = HookDesc[field] !== undefined;
+            if (needed && !present) {
+                throw new JssmError(this, `${HookDesc.kind} hook requires '${field}'`);
+            }
+            if (!needed && present) {
+                throw new JssmError(this, `${HookDesc.kind} hook does not take '${field}'`);
+            }
+        }
+    }
     set_hook(HookDesc) {
+        this._validate_hook_description(HookDesc);
         switch (HookDesc.kind) {
             case 'hook': {
                 // Numeric pair key (#729).  intern() rather than id_of(): a hook may
@@ -25941,8 +26015,8 @@ class Machine {
                 this._post_everything_hook = HookDesc.handler;
                 this._has_post_hooks = true;
                 break;
-            default:
-                throw new JssmError(this, `Unknown hook type ${HookDesc.kind}, should be impossible`);
+            // No default: `_validate_hook_description` above rejects any unknown kind
+            // before we reach here, so the switch is exhaustive over the known kinds.
         }
         // 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

package/dist/cli/fsl-export-system-prompt.cjs

@@ -108,7 +108,7 @@ function parseFslArgs(argv, spec) {
   return { positional, flags, helpText };
 }
 
-const getVersion = () => "5.144.5";
+const getVersion = () => "5.144.8";
 const SPEC = {
   flags: {
     help: { short: "h", boolean: true },
@@ -214,6 +214,6 @@ async function cli(argv) {
 async function main() {
   const argv = process.argv.slice(2);
   const code = await cli(argv);
-  process.exit(code);
+  process.exitCode = code;
 }
 void main();