jssm 5.162.12 → 5.162.13

package/jssm.es6.d.ts

@@ -308,6 +308,32 @@ type FslSourceLocation = {
     start: FslSourcePoint;
     end: FslSourcePoint;
 };
+/**
+ *  Options accepted by the FSL parser and its {@link wrap_parse} wrapper
+ *  (exported from the package as `parse`).  Exists so the two-argument parse
+ *  call is typed against what the parser actually reads, instead of a bare
+ *  `object`.
+ *
+ *  - `locations` — when `true`, the grammar attaches a `loc` field of type
+ *    {@link FslSourceLocation} (plus curated `*_loc` token sub-spans) to every
+ *    AST node.  When absent or `false`, the tree is byte-for-byte identical to
+ *    the historical location-free output.
+ *
+ *  - `startRule` — honored by the generated PEG.js boilerplate, which throws
+ *    on any rule name it doesn't expose.  This grammar exposes only its
+ *    default rule, `Document`, so the field is only useful for explicitness.
+ *
+ *  ```typescript
+ *  const [t] = parse('a -> b;', { locations: true });
+ *  // t.loc === { start: { offset: 0, line: 1, column: 1 },
+ *  //             end:   { offset: 7, line: 1, column: 8 } }
+ *  ```
+ *  @see FslSourceLocation
+ */
+type JssmParseOptions = {
+    locations?: boolean;
+    startRule?: 'Document';
+};
 /**
  *  A single key/value pair from an FSL `state X: { ... };` block, in the
  *  raw form produced by the parser before being condensed into a
@@ -1357,13 +1383,25 @@ interface FenceDimension {
     value: number;
     unit: FenceDimensionUnit;
 }
-/** The fully-parsed, validated description of one FSL Markdown fence block. */
+/**
+ *  The fully-parsed, validated description of one FSL Markdown fence block.
+ *
+ *  Sizing semantics: `width`/`height` (from `width=`/`height=` tokens) are
+ *  *exact* dimensions — the host renders the block at that size.
+ *  `max_width`/`max_height` (from `max-width=`/`max-height=` tokens) are
+ *  *upper bounds* on natural sizing — the block renders at its natural size
+ *  but is capped on that axis.  When both an exact and a max token are given
+ *  for the same axis, the exact dimension wins and the cap is moot.  All four
+ *  are `null` when their token is absent.
+ */
 interface FenceDescriptor {
     parts: FencePart[];
     ide: boolean;
     format: FenceImageFormat;
     width: FenceDimension | null;
     height: FenceDimension | null;
+    max_width: FenceDimension | null;
+    max_height: FenceDimension | null;
     interactive: boolean;
     notes: string[];
 }
@@ -1381,13 +1419,18 @@ declare function fsl_fence_lang(info: string): 'fsl' | 'jssm' | null;
 /**
  *  Parse a fence info string into a {@link FenceDescriptor}.  The first token is
  *  the (already-validated) language and is ignored; remaining tokens are
- *  classified as parts, image formats, the `ide` macro, or `width`/`height`
- *  options.  Unrecognized or conflicting tokens are dropped and recorded in
+ *  classified as parts, image formats, the `ide` macro, or the dimension
+ *  options `width`/`height` (exact size) and `max-width`/`max-height`
+ *  (upper bounds on natural size — see {@link FenceDescriptor} for the
+ *  precedence rule when both appear on one axis).  All four dimension tokens
+ *  share one value syntax: a bare number (pixels), `<n>px`, or `<n>%`.
+ *  Unrecognized or conflicting tokens are dropped and recorded in
  *  `notes` rather than throwing, so a host can render forward-compatibly.
  *  @param info The full fence info string, e.g. `'fsl image code width=300'`.
  *  @returns The validated descriptor; `notes` lists anything ignored or overridden.
  *  @example parse_fence_info('fsl').parts // => ['image', 'code']
  *  @example parse_fence_info('fsl code image').parts // => ['code', 'image']
+ *  @example parse_fence_info('fsl image max-width=300 max-height=50%').max_width // => { value: 300, unit: 'px' }
  */
 declare function parse_fence_info(info: string): FenceDescriptor;
 
@@ -1523,14 +1566,31 @@ declare function arrow_right_kind(arrow: JssmArrow): JssmArrowKind;
  *  `wrap_parse` itself is an internal convenience method for alting out an
  *  object as the options call.  Not generally meant for external use.
  *
+ *  @typeParam StateType The type of state names in the resulting tree; the
+ *                       grammar itself always produces `string`s, so only
+ *                       override this when threading a caller's own state
+ *                       naming through to {@link compile}.
+ *  @typeParam mDT       The type of the machine data member; usually omitted.
+ *
  *  @param input The FSL code to be evaluated
  *
- *  @param options Things to control about the instance.  Pass
+ *  @param options Things to control about the parse.  Pass
  *                 `{ locations: true }` to enable opt-in source location
- *                 tracking on every AST node.
+ *                 tracking on every AST node.  When omitted, an empty options
+ *                 object is passed through to the parser.
+ *
+ *  @returns The machine's intermediate representation: a flat
+ *           {@link JssmParseTree} with one node per top-level FSL statement.
+ *
+ *  @throws {SyntaxError} The generated PEG.js parser's `SyntaxError` when
+ *                        `input` is not valid FSL.
+ *
+ *  @see {@link compile}
+ *  @see {@link make}
+ *  @see {@link JssmParseOptions}
  *
  */
-declare function wrap_parse(input: string, options?: object): any;
+declare function wrap_parse<StateType = string, mDT = unknown>(input: string, options?: JssmParseOptions): JssmParseTree<StateType, mDT>;
 /*********
  *
  *  Compile a machine's JSON intermediate representation to a config object.  If
@@ -4737,4 +4797,4 @@ declare function compareVersions(v1: string, v2: string): number;
 declare function deserialize<mDT>(machine_string: string, ser: JssmSerialization<mDT>): Machine<mDT>;
 
 export { FslDirections, Machine, STOCHASTIC_DEFAULT_MAX_STEPS, STOCHASTIC_DEFAULT_RUNS, abstract_everything_hook_step, abstract_hook_step, action_label_chars, arrow_direction, arrow_left_kind, arrow_right_kind, build_time, compareVersions, compile, jssm_constants_d as constants, deserialize, find_repeated, from, fslCompletions, fslDiagnostics, fslSemanticSpans, fsl_fence_lang, gen_splitmix32, gviz_shapes, histograph, is_hook_complex_result, is_hook_rejection, make, named_colors, wrap_parse as parse, parse_fence_info, seq, shapes, sleep, sm, state_name_chars, state_name_first_chars, state_style_condense, transfer_state_properties, unique, version, weighted_histo_key, weighted_rand_select, weighted_sample_select };
-export type { FenceDescriptor, FenceDimension, FenceDimensionUnit, FenceImageFormat, FencePart };
+export type { FenceDescriptor, FenceDimension, FenceDimensionUnit, FenceImageFormat, FencePart, JssmParseOptions };

package/jssm_viz.es5.d.cts

@@ -3761,11 +3761,48 @@ declare class Machine<mDT> {
  */
 type RenderGroups = 'cluster' | 'chips' | 'off';
 /**
- *  Inject runtime configuration for jssm/viz.  Currently only accepts a
- *  custom `DOMParser` constructor for use by `*_svg_element` functions in
- *  environments that do not provide one globally (e.g. Node + jsdom).
+ *  The Graphviz engine surface jssm/viz actually consumes: one ready-to-use
+ *  object with a `renderString(dot, options)` method.  This is the contract
+ *  for {@link configure}`({ viz })` injection — a *direct adapter*, not a
+ *  factory: the caller instantiates (and, if needed, awaits) their engine
+ *  themselves, then hands over the finished object.  `renderString` receives
+ *  the dot source and an options object whose members jssm/viz uses are
+ *  `format` (always `'svg'`) and `engine` (a Graphviz layout engine name,
+ *  when the caller of a render function supplied one); it may return the
+ *  output string synchronously (like `@viz-js/viz`) or as a promise (like
+ *  asm.js `viz.js` 2.x), and jssm/viz awaits either.
  *
- *  Idempotent — last call wins.  No-op if called with no recognized keys.
+ *  ```typescript
+ *  import { instance } from '@viz-js/viz';
+ *  configure({ viz: await instance() });   // the default engine, injected by hand
+ *  ```
+ *  @see configure
+ */
+type VizEngine = {
+    renderString: (dot: string, options?: {
+        format?: string;
+        engine?: string;
+    }) => string | Promise<string>;
+};
+/**
+ *  Inject runtime configuration for jssm/viz — a custom `DOMParser`
+ *  constructor for the `*_svg_element` functions, a replacement Graphviz
+ *  engine for every render path, or both.
+ *
+ *  Each key is handled independently.  Idempotent — last call wins per key;
+ *  an omitted (or `undefined`) key leaves any earlier injection for that key
+ *  in place, so neither injection can be un-set.  No-op if called with no
+ *  recognized keys.
+ *
+ *  Precedence differs by key, on purpose:
+ *
+ *  - `DOMParser` is a *fallback* — `globalThis.DOMParser` (browsers, jsdom
+ *    test environments) still wins when present.
+ *  - `viz` is an *override* — once injected it is used for every render, and
+ *    the default `@viz-js/viz` import is never even attempted.  This is what
+ *    lets WASM-hostile environments (strict-CSP webviews such as VS Code's
+ *    markdown preview) supply an asm.js Graphviz build at runtime, without
+ *    bundler aliasing.  See {@link VizEngine} for the exact contract.
  *
  *  ```typescript
  *  // Node, with jsdom:
@@ -3775,13 +3812,27 @@ type RenderGroups = 'cluster' | 'chips' | 'off';
  *  configure({ DOMParser: new JSDOM().window.DOMParser });
  *  const el = await fsl_to_svg_element('a -> b;');
  *  ```
+ *
+ *  ```typescript
+ *  // strict-CSP webview, with an asm.js Graphviz:
+ *  import { configure, fsl_to_svg_string } from 'jssm/viz';
+ *
+ *  configure({ viz: my_asm_graphviz });  // anything with renderString(dot, opts)
+ *  const svg = await fsl_to_svg_string('a -> b;');
+ *  ```
  *  @param opts Configuration overrides.
  *  @param opts.DOMParser Constructor compatible with the WHATWG `DOMParser`
  *  interface.  Used as a fallback when `globalThis.DOMParser` is undefined.
+ *  @param opts.viz A ready-to-use Graphviz engine implementing
+ *  {@link VizEngine} (`renderString(dot, opts)`).  Overrides the default
+ *  `@viz-js/viz` engine for all subsequent renders.
  *  @throws {JssmError} if `DOMParser` is provided and is not a constructor.
+ *  @throws {JssmError} if `viz` is provided and lacks a callable `renderString`.
+ *  @see VizEngine
  */
 declare function configure(opts: {
     DOMParser?: typeof globalThis.DOMParser;
+    viz?: VizEngine;
 }): void;
 /**
  *  Look up a color from the default viz palette by key, returning empty
@@ -3839,9 +3890,14 @@ declare function undoublequote(txt: string): string;
  *  slug_for('!!!');          // ''
  *  slug_for('  Foo  Bar  '); // 'foo-bar'
  *  ```
+ *  Exported so consumers which must match rendered SVG node `<title>`s back
+ *  to state names (notably `FslViz.highlightTrace`, fsl#1935) can slug with
+ *  the *same* function the dot generator used, rather than a drifting copy.
+ *
  *  @param state The state name to slugify.
  *  @returns The lowercase hyphen-separated slug, or empty string if none of
  *  the characters were retainable.
+ *  @see slug_states
  *  @internal
  */
 declare function slug_for(state: string): string;
@@ -4279,9 +4335,10 @@ declare function machine_to_dot<T>(u_jssm: Machine<T>, opts?: VizRenderOpts): st
  */
 declare function fsl_to_dot(fsl: string, opts?: VizRenderOpts): string;
 /**
- *  Render a graphviz dot source string to SVG using `@viz-js/viz`.  The
- *  underlying viz instance is lazy-initialized on first call and cached for
- *  the lifetime of the module.
+ *  Render a graphviz dot source string to SVG using `@viz-js/viz`, or the
+ *  engine injected via {@link configure}`({ viz })` when one is set.  The
+ *  default viz instance is lazy-initialized on first call and cached for
+ *  the lifetime of the module; an injected engine bypasses it entirely.
  *
  *  ```typescript
  *  const svg = await dot_to_svg('digraph G { a -> b }');
@@ -4369,5 +4426,5 @@ declare const _test: {
     graph_bg_color_from_config: typeof graph_bg_color_from_config;
 };
 
-export { _test, build_time, configure, dot, dot_to_svg, fsl_to_dot, fsl_to_svg_element, fsl_to_svg_string, machine_to_dot, machine_to_svg_element, machine_to_svg_string, state_svg_label_texts, version };
-export type { RenderGroups, VizRenderOpts };
+export { _test, build_time, configure, dot, dot_to_svg, fsl_to_dot, fsl_to_svg_element, fsl_to_svg_string, machine_to_dot, machine_to_svg_element, machine_to_svg_string, slug_for, state_svg_label_texts, version };
+export type { RenderGroups, VizEngine, VizRenderOpts };

package/jssm_viz.es6.d.ts

@@ -3761,11 +3761,48 @@ declare class Machine<mDT> {
  */
 type RenderGroups = 'cluster' | 'chips' | 'off';
 /**
- *  Inject runtime configuration for jssm/viz.  Currently only accepts a
- *  custom `DOMParser` constructor for use by `*_svg_element` functions in
- *  environments that do not provide one globally (e.g. Node + jsdom).
+ *  The Graphviz engine surface jssm/viz actually consumes: one ready-to-use
+ *  object with a `renderString(dot, options)` method.  This is the contract
+ *  for {@link configure}`({ viz })` injection — a *direct adapter*, not a
+ *  factory: the caller instantiates (and, if needed, awaits) their engine
+ *  themselves, then hands over the finished object.  `renderString` receives
+ *  the dot source and an options object whose members jssm/viz uses are
+ *  `format` (always `'svg'`) and `engine` (a Graphviz layout engine name,
+ *  when the caller of a render function supplied one); it may return the
+ *  output string synchronously (like `@viz-js/viz`) or as a promise (like
+ *  asm.js `viz.js` 2.x), and jssm/viz awaits either.
  *
- *  Idempotent — last call wins.  No-op if called with no recognized keys.
+ *  ```typescript
+ *  import { instance } from '@viz-js/viz';
+ *  configure({ viz: await instance() });   // the default engine, injected by hand
+ *  ```
+ *  @see configure
+ */
+type VizEngine = {
+    renderString: (dot: string, options?: {
+        format?: string;
+        engine?: string;
+    }) => string | Promise<string>;
+};
+/**
+ *  Inject runtime configuration for jssm/viz — a custom `DOMParser`
+ *  constructor for the `*_svg_element` functions, a replacement Graphviz
+ *  engine for every render path, or both.
+ *
+ *  Each key is handled independently.  Idempotent — last call wins per key;
+ *  an omitted (or `undefined`) key leaves any earlier injection for that key
+ *  in place, so neither injection can be un-set.  No-op if called with no
+ *  recognized keys.
+ *
+ *  Precedence differs by key, on purpose:
+ *
+ *  - `DOMParser` is a *fallback* — `globalThis.DOMParser` (browsers, jsdom
+ *    test environments) still wins when present.
+ *  - `viz` is an *override* — once injected it is used for every render, and
+ *    the default `@viz-js/viz` import is never even attempted.  This is what
+ *    lets WASM-hostile environments (strict-CSP webviews such as VS Code's
+ *    markdown preview) supply an asm.js Graphviz build at runtime, without
+ *    bundler aliasing.  See {@link VizEngine} for the exact contract.
  *
  *  ```typescript
  *  // Node, with jsdom:
@@ -3775,13 +3812,27 @@ type RenderGroups = 'cluster' | 'chips' | 'off';
  *  configure({ DOMParser: new JSDOM().window.DOMParser });
  *  const el = await fsl_to_svg_element('a -> b;');
  *  ```
+ *
+ *  ```typescript
+ *  // strict-CSP webview, with an asm.js Graphviz:
+ *  import { configure, fsl_to_svg_string } from 'jssm/viz';
+ *
+ *  configure({ viz: my_asm_graphviz });  // anything with renderString(dot, opts)
+ *  const svg = await fsl_to_svg_string('a -> b;');
+ *  ```
  *  @param opts Configuration overrides.
  *  @param opts.DOMParser Constructor compatible with the WHATWG `DOMParser`
  *  interface.  Used as a fallback when `globalThis.DOMParser` is undefined.
+ *  @param opts.viz A ready-to-use Graphviz engine implementing
+ *  {@link VizEngine} (`renderString(dot, opts)`).  Overrides the default
+ *  `@viz-js/viz` engine for all subsequent renders.
  *  @throws {JssmError} if `DOMParser` is provided and is not a constructor.
+ *  @throws {JssmError} if `viz` is provided and lacks a callable `renderString`.
+ *  @see VizEngine
  */
 declare function configure(opts: {
     DOMParser?: typeof globalThis.DOMParser;
+    viz?: VizEngine;
 }): void;
 /**
  *  Look up a color from the default viz palette by key, returning empty
@@ -3839,9 +3890,14 @@ declare function undoublequote(txt: string): string;
  *  slug_for('!!!');          // ''
  *  slug_for('  Foo  Bar  '); // 'foo-bar'
  *  ```
+ *  Exported so consumers which must match rendered SVG node `<title>`s back
+ *  to state names (notably `FslViz.highlightTrace`, fsl#1935) can slug with
+ *  the *same* function the dot generator used, rather than a drifting copy.
+ *
  *  @param state The state name to slugify.
  *  @returns The lowercase hyphen-separated slug, or empty string if none of
  *  the characters were retainable.
+ *  @see slug_states
  *  @internal
  */
 declare function slug_for(state: string): string;
@@ -4279,9 +4335,10 @@ declare function machine_to_dot<T>(u_jssm: Machine<T>, opts?: VizRenderOpts): st
  */
 declare function fsl_to_dot(fsl: string, opts?: VizRenderOpts): string;
 /**
- *  Render a graphviz dot source string to SVG using `@viz-js/viz`.  The
- *  underlying viz instance is lazy-initialized on first call and cached for
- *  the lifetime of the module.
+ *  Render a graphviz dot source string to SVG using `@viz-js/viz`, or the
+ *  engine injected via {@link configure}`({ viz })` when one is set.  The
+ *  default viz instance is lazy-initialized on first call and cached for
+ *  the lifetime of the module; an injected engine bypasses it entirely.
  *
  *  ```typescript
  *  const svg = await dot_to_svg('digraph G { a -> b }');
@@ -4369,5 +4426,5 @@ declare const _test: {
     graph_bg_color_from_config: typeof graph_bg_color_from_config;
 };
 
-export { _test, build_time, configure, dot, dot_to_svg, fsl_to_dot, fsl_to_svg_element, fsl_to_svg_string, machine_to_dot, machine_to_svg_element, machine_to_svg_string, state_svg_label_texts, version };
-export type { RenderGroups, VizRenderOpts };
+export { _test, build_time, configure, dot, dot_to_svg, fsl_to_dot, fsl_to_svg_element, fsl_to_svg_string, machine_to_dot, machine_to_svg_element, machine_to_svg_string, slug_for, state_svg_label_texts, version };
+export type { RenderGroups, VizEngine, VizRenderOpts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.162.12",
+  "version": "5.162.13",
   "engines": {
     "node": ">=10.0.0"
   },
@@ -234,6 +234,7 @@
     "ci_test": "npm run vet && npm run make_ci && npm run vitest",
     "ci_test_runtime": "npm run make_ci && npm run vitest",
     "attw": "attw --pack .",
+    "decl_parity": "node src/buildjs/decl_parity.cjs",
     "minify": "mv dist/es6/fsl_parser.js dist/es6/fsl_parser.nonmin.js && terser dist/es6/fsl_parser.nonmin.js > dist/es6/fsl_parser.js",
     "min_iife": "mv dist/jssm.es5.iife.js dist/jssm.es5.iife.nonmin.js && terser dist/jssm.es5.iife.nonmin.js > dist/jssm.es5.iife.js && cp dist/jssm.es5.iife.nonmin.js ./src/tools/",
     "min_cjs": "mv dist/jssm.es5.cjs.js dist/jssm.es5.nonmin.cjs && terser dist/jssm.es5.nonmin.cjs > dist/jssm.es5.cjs",