jssm 5.104.2 → 5.112.3

package/dist/es6/jssm_arrow.js

@@ -99,8 +99,12 @@ function arrow_left_kind(arrow) {
         case '↔':
         case '<-=>':
         case '←⇒':
+        case '←=>':
+        case '<-⇒':
         case '<-~>':
         case '←↛':
+        case '←~>':
+        case '<-↛':
             return 'legal';
         case '<=':
         case '⇐':
@@ -108,8 +112,12 @@ function arrow_left_kind(arrow) {
         case '⇔':
         case '<=->':
         case '⇐→':
+        case '⇐->':
+        case '<=→':
         case '<=~>':
         case '⇐↛':
+        case '⇐~>':
+        case '<=↛':
             return 'main';
         case '<~':
         case '↚':
@@ -117,8 +125,12 @@ function arrow_left_kind(arrow) {
         case '↮':
         case '<~->':
         case '↚→':
+        case '↚->':
+        case '<~→':
         case '<~=>':
         case '↚⇒':
+        case '↚=>':
+        case '<~⇒':
             return 'forced';
         default:
             throw new JssmError(undefined, `arrow_direction: unknown arrow type ${arrow}`);
@@ -158,8 +170,12 @@ function arrow_right_kind(arrow) {
         case '↔':
         case '<=->':
         case '⇐→':
+        case '⇐->':
+        case '<=→':
         case '<~->':
         case '↚→':
+        case '↚->':
+        case '<~→':
             return 'legal';
         case '=>':
         case '⇒':
@@ -167,8 +183,12 @@ function arrow_right_kind(arrow) {
         case '⇔':
         case '<-=>':
         case '←⇒':
+        case '←=>':
+        case '<-⇒':
         case '<~=>':
         case '↚⇒':
+        case '↚=>':
+        case '<~⇒':
             return 'main';
         case '~>':
         case '↛':
@@ -176,8 +196,12 @@ function arrow_right_kind(arrow) {
         case '↮':
         case '<-~>':
         case '←↛':
+        case '←~>':
+        case '<-↛':
         case '<=~>':
         case '⇐↛':
+        case '⇐~>':
+        case '<=↛':
             return 'forced';
         default:
             throw new JssmError(undefined, `arrow_direction: unknown arrow type ${arrow}`);

package/dist/es6/jssm_compiler.d.ts

@@ -2,11 +2,26 @@ import { JssmTransition, JssmCompileSe, JssmParseTree, JssmGenericConfig } from
 /*********
  *
  *  Internal method meant to perform factory assembly of an edge.  Not meant for
- *  external use.
+ *  external use.  Constructs a {@link JssmTransition} from a parsed
+ *  semi-edge (`this_se`), a source state, a target state, and directionality.
  *
  *  @internal
  *
- *  @typeparam mDT The type of the machine data member; usually omitted
+ *  @typeparam StateType The type of state names (usually `string`).
+ *  @typeparam mDT       The type of the machine data member; usually omitted.
+ *
+ *  @param this_se    - The parsed semi-edge containing kind, action, and
+ *                      probability metadata.
+ *  @param from       - The source state of the transition.
+ *  @param to         - The target state of the transition.
+ *  @param isRight    - `true` if this is a left-to-right transition, `false`
+ *                      for right-to-left.  Determines which arrow kind
+ *                      extraction function is used.
+ *  @param _wasList   - If the transition was expanded from a list (e.g.
+ *                      `[A B C] -> D`), the original list of states.
+ *  @param _wasIndex  - The index of `from` within `_wasList`, if applicable.
+ *
+ *  @returns A fully assembled {@link JssmTransition} edge object.
  *
  */
 declare function makeTransition<StateType, mDT>(this_se: JssmCompileSe<StateType, mDT>, from: StateType, to: StateType, isRight: boolean, _wasList?: Array<StateType>, _wasIndex?: number): JssmTransition<StateType, mDT>;

package/dist/es6/jssm_compiler.js

@@ -6,14 +6,28 @@ import { reduce as reduce_to_639 } from 'reduce-to-639-1';
 /*********
  *
  *  Internal method meant to perform factory assembly of an edge.  Not meant for
- *  external use.
+ *  external use.  Constructs a {@link JssmTransition} from a parsed
+ *  semi-edge (`this_se`), a source state, a target state, and directionality.
  *
  *  @internal
  *
- *  @typeparam mDT The type of the machine data member; usually omitted
+ *  @typeparam StateType The type of state names (usually `string`).
+ *  @typeparam mDT       The type of the machine data member; usually omitted.
+ *
+ *  @param this_se    - The parsed semi-edge containing kind, action, and
+ *                      probability metadata.
+ *  @param from       - The source state of the transition.
+ *  @param to         - The target state of the transition.
+ *  @param isRight    - `true` if this is a left-to-right transition, `false`
+ *                      for right-to-left.  Determines which arrow kind
+ *                      extraction function is used.
+ *  @param _wasList   - If the transition was expanded from a list (e.g.
+ *                      `[A B C] -> D`), the original list of states.
+ *  @param _wasIndex  - The index of `from` within `_wasList`, if applicable.
+ *
+ *  @returns A fully assembled {@link JssmTransition} edge object.
  *
  */
-// TODO add at-param to docblock
 function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
     const kind = isRight
         ? arrow_right_kind(this_se.kind)

package/dist/es6/jssm_constants.d.ts

@@ -1,5 +1,32 @@
+/*******
+ *
+ *  Convenience aliases for common mathematical and numeric constants from
+ *  `Number` and `Math`.  Re-exported so that FSL data expressions and tests
+ *  can reference them without importing `Math` directly.
+ *
+ *  Includes: `NegInfinity`, `PosInfinity`, `Epsilon`, `Pi`, `E`, `Root2`,
+ *  `RootHalf`, `Ln2`, `Ln10`, `Log2E`, `Log10E`, `MaxSafeInt`, `MinSafeInt`,
+ *  `MaxPosNum`, `MinPosNum`, `Phi` (golden ratio), `EulerC` (Euler–Mascheroni).
+ *
+ */
 export declare const NegInfinity: number, PosInfinity: number, Epsilon: number, Pi: number, E: number, Root2: number, RootHalf: number, Ln2: number, Ln10: number, Log2E: number, Log10E: number, MaxSafeInt: number, MinSafeInt: number, MaxPosNum: number, MinPosNum: number, Phi = 1.618033988749895, EulerC = 0.5772156649015329;
+/*******
+ *
+ *  Complete list of node shapes supported by Graphviz.  Used by jssm-viz to
+ *  validate and render state shapes in FSL `state ... : { shape: ... }` blocks.
+ *
+ *  `shapes` is an alias for `gviz_shapes`.
+ *
+ */
 declare const gviz_shapes: string[];
 declare const shapes: string[];
+/*******
+ *
+ *  List of CSS/SVG named colors accepted by jssm-viz for state styling
+ *  properties like `background-color` and `text-color`.  Case-insensitive
+ *  matching is done at parse time; the canonical casing here follows the
+ *  CSS specification.
+ *
+ */
 declare const named_colors: string[];
 export { gviz_shapes, shapes, named_colors, };

package/dist/es6/jssm_constants.js

@@ -1,4 +1,23 @@
+/*******
+ *
+ *  Convenience aliases for common mathematical and numeric constants from
+ *  `Number` and `Math`.  Re-exported so that FSL data expressions and tests
+ *  can reference them without importing `Math` directly.
+ *
+ *  Includes: `NegInfinity`, `PosInfinity`, `Epsilon`, `Pi`, `E`, `Root2`,
+ *  `RootHalf`, `Ln2`, `Ln10`, `Log2E`, `Log10E`, `MaxSafeInt`, `MinSafeInt`,
+ *  `MaxPosNum`, `MinPosNum`, `Phi` (golden ratio), `EulerC` (Euler–Mascheroni).
+ *
+ */
 export const NegInfinity = Number.NEGATIVE_INFINITY, PosInfinity = Number.POSITIVE_INFINITY, Epsilon = Number.EPSILON, Pi = Math.PI, E = Math.E, Root2 = Math.SQRT2, RootHalf = Math.SQRT1_2, Ln2 = Math.LN2, Ln10 = Math.LN10, Log2E = Math.LOG2E, Log10E = Math.LOG10E, MaxSafeInt = Number.MAX_SAFE_INTEGER, MinSafeInt = Number.MIN_SAFE_INTEGER, MaxPosNum = Number.MAX_VALUE, MinPosNum = Number.MIN_VALUE, Phi = 1.61803398874989484820, EulerC = 0.57721566490153286060;
+/*******
+ *
+ *  Complete list of node shapes supported by Graphviz.  Used by jssm-viz to
+ *  validate and render state shapes in FSL `state ... : { shape: ... }` blocks.
+ *
+ *  `shapes` is an alias for `gviz_shapes`.
+ *
+ */
 const gviz_shapes = [
     "box3d",
     "polygon",
@@ -62,6 +81,14 @@ const gviz_shapes = [
     "record"
 ];
 const shapes = gviz_shapes;
+/*******
+ *
+ *  List of CSS/SVG named colors accepted by jssm-viz for state styling
+ *  properties like `background-color` and `text-color`.  Case-insensitive
+ *  matching is done at parse time; the canonical casing here follows the
+ *  CSS specification.
+ *
+ */
 const named_colors = [
     "AliceBlue", "AntiqueWhite", "Aqua", "Aquamarine", "Azure", "Beige",
     "Bisque", "Black", "BlanchedAlmond", "Blue", "BlueViolet", "Brown",

package/dist/es6/jssm_error.d.ts

@@ -1,4 +1,23 @@
 import { JssmErrorExtendedInfo } from './jssm_types';
+/*******
+ *
+ *  Custom error class for jssm.  Enriches the standard `Error` with
+ *  machine context (current state, instance name) and an optional
+ *  `requested_state` so that error messages are self-describing.
+ *
+ *  ```typescript
+ *  throw new JssmError(machine, 'no such state', { requested_state: 'Blue' });
+ *  // JssmError: [[my-light]]: no such state (at "Red", requested "Blue")
+ *  ```
+ *
+ *  @param machine         - The `Machine` instance that raised the error, or
+ *                           `undefined` if no machine is available.  Used to
+ *                           read `state()` and `instance_name()` for context.
+ *  @param message         - A human-readable description of the error.
+ *  @param JEEI            - Optional {@link JssmErrorExtendedInfo} with extra
+ *                           context such as `requested_state`.
+ *
+ */
 declare class JssmError extends Error {
     message: string;
     base_message: string;

package/dist/es6/jssm_error.js

@@ -1,3 +1,22 @@
+/*******
+ *
+ *  Custom error class for jssm.  Enriches the standard `Error` with
+ *  machine context (current state, instance name) and an optional
+ *  `requested_state` so that error messages are self-describing.
+ *
+ *  ```typescript
+ *  throw new JssmError(machine, 'no such state', { requested_state: 'Blue' });
+ *  // JssmError: [[my-light]]: no such state (at "Red", requested "Blue")
+ *  ```
+ *
+ *  @param machine         - The `Machine` instance that raised the error, or
+ *                           `undefined` if no machine is available.  Used to
+ *                           read `state()` and `instance_name()` for context.
+ *  @param message         - A human-readable description of the error.
+ *  @param JEEI            - Optional {@link JssmErrorExtendedInfo} with extra
+ *                           context such as `requested_state`.
+ *
+ */
 class JssmError extends Error {
     constructor(machine, message, JEEI) {
         const { requested_state } = (JEEI === undefined)

package/dist/es6/jssm_theme.d.ts

@@ -1,4 +1,15 @@
 import { FslTheme, JssmBaseTheme } from './jssm_types';
 import { base_theme } from './themes/jssm_base_stylesheet';
+/*******
+ *
+ *  Registry mapping theme names to their stylesheet definitions.  Each entry
+ *  maps an {@link FslTheme} string (e.g. `'default'`, `'ocean'`) to a
+ *  {@link JssmBaseTheme} object containing colors, shapes, and other visual
+ *  defaults used by jssm-viz when rendering state machine diagrams.
+ *
+ *  Add new themes by importing their definition and calling
+ *  `theme_mapping.set(name, theme)`.
+ *
+ */
 declare const theme_mapping: Map<FslTheme, JssmBaseTheme>;
 export { theme_mapping, base_theme };

package/dist/es6/jssm_theme.js

@@ -4,6 +4,17 @@ import { modern_theme } from './themes/jssm_theme_modern';
 import { ocean_theme } from './themes/jssm_theme_ocean';
 import { plain_theme } from './themes/jssm_theme_plain';
 import { bold_theme } from './themes/jssm_theme_bold';
+/*******
+ *
+ *  Registry mapping theme names to their stylesheet definitions.  Each entry
+ *  maps an {@link FslTheme} string (e.g. `'default'`, `'ocean'`) to a
+ *  {@link JssmBaseTheme} object containing colors, shapes, and other visual
+ *  defaults used by jssm-viz when rendering state machine diagrams.
+ *
+ *  Add new themes by importing their definition and calling
+ *  `theme_mapping.set(name, theme)`.
+ *
+ */
 const theme_mapping = new Map();
 theme_mapping.set('default', default_theme);
 theme_mapping.set('modern', modern_theme);

package/dist/es6/jssm_types.d.ts

@@ -115,6 +115,7 @@ declare type JssmStateDeclaration = {
     textColor?: JssmColor;
     backgroundColor?: JssmColor;
     borderColor?: JssmColor;
+    image?: string;
     state: StateType;
     property?: {
         name: string;
@@ -154,7 +155,11 @@ declare type JssmStateStyleBorderColor = {
     key: 'border-color';
     value: JssmColor;
 };
-declare type JssmStateStyleKey = JssmStateStyleShape | JssmStateStyleColor | JssmStateStyleTextColor | JssmStateStyleCorners | JssmStateStyleLineStyle | JssmStateStyleBackgroundColor | JssmStateStyleStateLabel | JssmStateStyleBorderColor;
+declare type JssmStateStyleImage = {
+    key: 'image';
+    value: string;
+};
+declare type JssmStateStyleKey = JssmStateStyleShape | JssmStateStyleColor | JssmStateStyleTextColor | JssmStateStyleCorners | JssmStateStyleLineStyle | JssmStateStyleBackgroundColor | JssmStateStyleStateLabel | JssmStateStyleBorderColor | JssmStateStyleImage;
 declare type JssmStateStyleKeyList = JssmStateStyleKey[];
 declare type JssmBaseTheme = {
     name: string;
@@ -356,7 +361,23 @@ declare type PostExitHook<mDT> = {
     from: string;
     handler: PostHookHandler<mDT>;
 };
-declare type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT> | AfterHook<mDT> | PostBasicHookDescription<mDT> | PostHookDescriptionWithAction<mDT> | PostGlobalActionHook<mDT> | PostAnyActionHook<mDT> | PostStandardTransitionHook<mDT> | PostMainTransitionHook<mDT> | PostForcedTransitionHook<mDT> | PostAnyTransitionHook<mDT> | PostEntryHook<mDT> | PostExitHook<mDT>;
+declare type PreEverythingHook<mDT> = {
+    kind: 'pre everything';
+    handler: EverythingHookHandler<mDT>;
+};
+declare type EverythingHook<mDT> = {
+    kind: 'everything';
+    handler: EverythingHookHandler<mDT>;
+};
+declare type PrePostEverythingHook<mDT> = {
+    kind: 'pre post everything';
+    handler: PostEverythingHookHandler<mDT>;
+};
+declare type PostEverythingHook<mDT> = {
+    kind: 'post everything';
+    handler: PostEverythingHookHandler<mDT>;
+};
+declare type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT> | AfterHook<mDT> | PostBasicHookDescription<mDT> | PostHookDescriptionWithAction<mDT> | PostGlobalActionHook<mDT> | PostAnyActionHook<mDT> | PostStandardTransitionHook<mDT> | PostMainTransitionHook<mDT> | PostForcedTransitionHook<mDT> | PostAnyTransitionHook<mDT> | PostEntryHook<mDT> | PostExitHook<mDT> | PreEverythingHook<mDT> | EverythingHook<mDT> | PrePostEverythingHook<mDT> | PostEverythingHook<mDT>;
 declare type HookComplexResult<mDT> = {
     pass: boolean;
     state?: StateType;
@@ -368,11 +389,16 @@ declare type HookContext<mDT> = {
     data: mDT;
     next_data: mDT;
 };
+declare type EverythingHookContext<mDT> = HookContext<mDT> & {
+    hook_name: string;
+};
 declare type HookHandler<mDT> = (hook_context: HookContext<mDT>) => HookResult<mDT>;
 declare type PostHookHandler<mDT> = (hook_context: HookContext<mDT>) => void;
+declare type EverythingHookHandler<mDT> = (hook_context: EverythingHookContext<mDT>) => HookResult<mDT>;
+declare type PostEverythingHookHandler<mDT> = (hook_context: EverythingHookContext<mDT>) => void;
 declare type JssmErrorExtendedInfo = {
     requested_state?: StateType | undefined;
 };
 declare type JssmHistory<mDT> = circular_buffer<[StateType, mDT]>;
 declare type JssmRng = () => number;
-export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmStateConfig, JssmStateStyleKey, JssmStateStyleKeyList, JssmBaseTheme, JssmTheme, JssmLayout, JssmHistory, JssmSerialization, JssmPropertyDefinition, JssmAllowsOverride, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirections, FslDirection, FslThemes, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, JssmRng };
+export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmStateConfig, JssmStateStyleKey, JssmStateStyleKeyList, JssmBaseTheme, JssmTheme, JssmLayout, JssmHistory, JssmSerialization, JssmPropertyDefinition, JssmAllowsOverride, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirections, FslDirection, FslThemes, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, EverythingHookContext, EverythingHookHandler, PostEverythingHookHandler, JssmRng };

package/dist/es6/jssm_util.d.ts

@@ -1,11 +1,67 @@
 /*******
  *
- *  Predicate for validating an array for uniqueness.  Not generally meant for
- *  external use.
+ *  Predicate for validating an array for uniqueness.  Returns `true` when
+ *  `el` is the first occurrence in `source`, `false` otherwise.  Intended
+ *  for use as an `Array.filter` callback.  Not generally meant for external
+ *  use.
+ *
+ *  ```typescript
+ *  [1, 2, 2, 3].filter(arr_uniq_p);  // [1, 2, 3]
+ *  ```
+ *
+ *  @param el     - The current element being tested.
+ *  @param i      - The index of the current element.
+ *  @param source - The full array being filtered.
+ *
+ *  @returns `true` if `el` is the first occurrence in `source`.
  *
  */
 declare function arr_uniq_p<T>(el: T, i: number, source: T[]): boolean;
+/*******
+ *
+ *  Wraps a string in an array, or passes through if already non-string.
+ *  Used to normalize arguments that accept either a single state name or
+ *  an array of state names.
+ *
+ *  ```typescript
+ *  array_box_if_string('hello');    // ['hello']
+ *  array_box_if_string(['a','b']); // ['a','b']
+ *  ```
+ *
+ *  @param n - A string to box, or a value to pass through unchanged.
+ *
+ *  @returns The input wrapped in an array if it was a string, otherwise the
+ *           input unchanged.
+ *
+ */
 declare const array_box_if_string: (n: any) => any;
+/*******
+ *
+ *  Selects a single item from a weighted array of objects using cumulative
+ *  probability.  Each object in the array should have a numeric property
+ *  indicating its relative weight (defaults to `'probability'`).  Objects
+ *  missing the property are treated as weight 1.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { value: 'common',  probability: 0.8 },
+ *    { value: 'rare',    probability: 0.2 }
+ *  ];
+ *
+ *  weighted_rand_select(opts);  // most often { value: 'common', ... }
+ *  ```
+ *
+ *  @param options              - Non-empty array of objects to choose from.
+ *  @param probability_property - Name of the numeric weight property on each
+ *                                object.  Defaults to `'probability'`.
+ *  @param rng                  - Optional random number generator `() => number`
+ *                                in `[0, 1)`.  Defaults to `Math.random`.
+ *
+ *  @returns One element from `options`, chosen by weighted random selection.
+ *
+ *  @throws {TypeError} If `options` is not a non-empty array of objects.
+ *
+ */
 declare const weighted_rand_select: Function;
 /*******
  *
@@ -33,26 +89,108 @@ declare function seq(n: number): number[];
  *
  */
 declare const histograph: Function;
+/*******
+ *
+ *  Draws `n` weighted random samples from an array of objects.  Each draw is
+ *  independent (with replacement), delegating to {@link weighted_rand_select}.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { value: 'a', probability: 0.9 },
+ *    { value: 'b', probability: 0.1 }
+ *  ];
+ *
+ *  weighted_sample_select(3, opts, 'probability');
+ *  // e.g. [ { value: 'a', ... }, { value: 'a', ... }, { value: 'b', ... } ]
+ *  ```
+ *
+ *  @param n                    - Number of samples to draw.
+ *  @param options              - Non-empty array of weighted objects.
+ *  @param probability_property - Name of the numeric weight property.
+ *  @param rng                  - Optional random number generator.
+ *
+ *  @returns An array of `n` independently selected items.
+ *
+ */
 declare const weighted_sample_select: Function;
+/*******
+ *
+ *  Draws `n` weighted random samples, extracts a named key from each, and
+ *  returns a histograph (`Map`) of how often each key value appeared.  Useful
+ *  for validating that a probabilistic transition distribution is roughly
+ *  correct over many trials.
+ *
+ *  ```typescript
+ *  const opts = [
+ *    { to: 'a', probability: 0.7 },
+ *    { to: 'b', probability: 0.3 }
+ *  ];
+ *
+ *  weighted_histo_key(1000, opts, 'probability', 'to');
+ *  // Map { 'a' => ~700, 'b' => ~300 }
+ *  ```
+ *
+ *  @param n         - Number of samples to draw.
+ *  @param opts      - Non-empty array of weighted objects.
+ *  @param prob_prop - Name of the numeric weight property.
+ *  @param extract   - Name of the property to extract from each sample for
+ *                     histogramming.
+ *  @param rng       - Optional random number generator.
+ *
+ *  @returns A `Map` from extracted key values to their occurrence counts.
+ *
+ */
 declare const weighted_histo_key: Function;
 /*******
  *
- *  Internal method generating names for edges for the hook lookup map.  Not
- *  meant for external use.
+ *  Internal method generating composite keys for the hook lookup map by
+ *  JSON-serializing a `[property, state]` pair.  Not meant for external use.
+ *
+ *  ```typescript
+ *  name_bind_prop_and_state('color', 'Red');  // '["color","Red"]'
+ *  ```
+ *
+ *  @param prop  - The property name (e.g. a data key or hook category).
+ *  @param state - The state name to bind to.
+ *
+ *  @returns A deterministic JSON string key for the `[prop, state]` pair.
+ *
+ *  @throws {JssmError} If either argument is not a string.
  *
  */
 declare function name_bind_prop_and_state(prop: string, state: string): string;
 /*******
  *
- *  Internal method generating names for edges for the hook lookup map.  Not
- *  meant for external use.
+ *  Internal method generating composite keys for transition hooks by
+ *  JSON-serializing a `[from, to]` state pair.  Used to look up hooks
+ *  registered on a specific edge.  Not meant for external use.
+ *
+ *  ```typescript
+ *  hook_name('Red', 'Green');  // '["Red","Green"]'
+ *  ```
+ *
+ *  @param from - The source state name.
+ *  @param to   - The target state name.
+ *
+ *  @returns A deterministic JSON string key for the `[from, to]` pair.
  *
  */
 declare const hook_name: (from: string, to: string) => string;
 /*******
  *
- *  Internal method generating names for actions for the hook lookup map.  Not
- *  meant for external use.
+ *  Internal method generating composite keys for named-action hooks by
+ *  JSON-serializing a `[from, to, action]` triple.  Used to look up hooks
+ *  registered on a specific action-labeled edge.  Not meant for external use.
+ *
+ *  ```typescript
+ *  named_hook_name('Red', 'Green', 'next');  // '["Red","Green","next"]'
+ *  ```
+ *
+ *  @param from   - The source state name.
+ *  @param to     - The target state name.
+ *  @param action - The action label on the edge.
+ *
+ *  @returns A deterministic JSON string key for the `[from, to, action]` triple.
  *
  */
 declare const named_hook_name: (from: string, to: string, action: string) => string;
@@ -82,7 +220,7 @@ declare function gen_splitmix32(a?: number | undefined): () => number;
  *  ```
  *
  */
-declare const unique: <T>(arr?: T[]) => T[];
+declare const unique: <T>(arr: T[]) => T[];
 /*******
  *
  *  Lists all repeated items in an array along with their counts.  Subject to
@@ -102,5 +240,19 @@ declare const unique: <T>(arr?: T[]) => T[];
  *
  */
 declare function find_repeated<T>(arr: T[]): [T, number][];
+/*******
+ *
+ *  Returns a `Promise` that resolves after `ms` milliseconds.  Useful for
+ *  inserting delays in async test flows or demos.
+ *
+ *  ```typescript
+ *  await sleep(100);  // pauses execution for 100ms
+ *  ```
+ *
+ *  @param ms - Number of milliseconds to wait before resolving.
+ *
+ *  @returns A `Promise<void>` that resolves after the timeout.
+ *
+ */
 declare function sleep(ms: number): Promise<unknown>;
 export { seq, unique, find_repeated, arr_uniq_p, histograph, weighted_histo_key, weighted_rand_select, weighted_sample_select, array_box_if_string, name_bind_prop_and_state, hook_name, named_hook_name, gen_splitmix32, sleep };