jssm 5.162.12 → 5.162.13

package/dist/deno/jssm_compiler.d.ts

@@ -1,4 +1,4 @@
-import { JssmTransition, JssmCompileSe, JssmCompileSeStart, JssmParseTree, JssmGenericConfig, JssmGroupRegistry, FslSourceLocation } from './jssm_types.js';
+import { JssmTransition, JssmCompileSe, JssmCompileSeStart, JssmParseTree, JssmParseOptions, JssmGenericConfig, JssmGroupRegistry, FslSourceLocation } from './jssm_types.js';
 /*********
  *
  *  Returns the source span of the `n`-th parse-tree node (1-based) matching
@@ -123,14 +123,31 @@ declare function makeTransition<StateType, mDT>(this_se: JssmCompileSe<StateType
  *  `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>;
 /*********
  *
  *  Builds the ordered {@link JssmGroupRegistry} from every `named_list` node

package/dist/deno/jssm_types.d.ts

@@ -407,6 +407,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
@@ -1345,4 +1371,4 @@ type JssmEventHandler<mDT, Ev extends JssmEventName> = (detail: JssmEventDetailM
  *  removes the subscription.  Calling it more than once is a no-op.
  */
 type JssmUnsubscribe = () => void;
-export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmEditorConfig, JssmStochasticMode, JssmStochasticOptions, JssmStochasticRun, JssmStochasticSummary, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmStateConfig, JssmStateStyleKey, JssmStateStyleKeyList, JssmGraphDefaultEdgeColor, JssmTransitionStyleKey, JssmTransitionConfig, JssmGraphAliasKey, JssmGraphStyleKey, JssmGraphConfig, JssmBaseTheme, JssmTheme, JssmLayout, JssmHistory, JssmSerialization, JssmPropertyDefinition, JssmAllowsOverride, JssmAllowIslands, JssmDefaultSize, JssmParsedSemver, JssmGroupRef, JssmGroupMemberRef, JssmGroupRegistry, JssmHookDeclaration, JssmBoundaryHooks, JssmGroupHooks, JssmStateHooks, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirections, FslDirection, FslThemes, FslTheme, FslSourcePoint, FslSourceLocation, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, EverythingHookContext, EverythingHookHandler, PostEverythingHookHandler, HookPhase, HookTargetScope, HookTarget, HookBoundaryKind, HookRegistryEntry, HookQuery, JssmEventName, JssmEventDetailMap, JssmEventFilterMap, JssmEventFilter, JssmEventHandler, JssmUnsubscribe, JssmTransitionEventDetail, JssmRejectionEventDetail, JssmActionEventDetail, JssmEntryEventDetail, JssmExitEventDetail, JssmTerminalEventDetail, JssmCompleteEventDetail, JssmErrorEventDetail, JssmDataChangeEventDetail, JssmOverrideEventDetail, JssmTimeoutEventDetail, JssmHookLifecycleEventDetail, JssmRng };
+export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmEditorConfig, JssmStochasticMode, JssmStochasticOptions, JssmStochasticRun, JssmStochasticSummary, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmParseOptions, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmStateConfig, JssmStateStyleKey, JssmStateStyleKeyList, JssmGraphDefaultEdgeColor, JssmTransitionStyleKey, JssmTransitionConfig, JssmGraphAliasKey, JssmGraphStyleKey, JssmGraphConfig, JssmBaseTheme, JssmTheme, JssmLayout, JssmHistory, JssmSerialization, JssmPropertyDefinition, JssmAllowsOverride, JssmAllowIslands, JssmDefaultSize, JssmParsedSemver, JssmGroupRef, JssmGroupMemberRef, JssmGroupRegistry, JssmHookDeclaration, JssmBoundaryHooks, JssmGroupHooks, JssmStateHooks, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirections, FslDirection, FslThemes, FslTheme, FslSourcePoint, FslSourceLocation, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, EverythingHookContext, EverythingHookHandler, PostEverythingHookHandler, HookPhase, HookTargetScope, HookTarget, HookBoundaryKind, HookRegistryEntry, HookQuery, JssmEventName, JssmEventDetailMap, JssmEventFilterMap, JssmEventFilter, JssmEventHandler, JssmUnsubscribe, JssmTransitionEventDetail, JssmRejectionEventDetail, JssmActionEventDetail, JssmEntryEventDetail, JssmExitEventDetail, JssmTerminalEventDetail, JssmCompleteEventDetail, JssmErrorEventDetail, JssmDataChangeEventDetail, JssmOverrideEventDetail, JssmTimeoutEventDetail, JssmHookLifecycleEventDetail, JssmRng };

package/dist/deno/jssm_viz.d.ts

@@ -16,11 +16,48 @@ import type { JssmGroupMemberRef, JssmTransitionConfig, JssmGraphConfig } from '
  */
 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:
@@ -30,13 +67,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
@@ -94,9 +145,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;
@@ -534,9 +590,10 @@ declare function machine_to_dot<T>(u_jssm: jssm.Machine<T>, opts?: VizRenderOpts
  */
 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 }');
@@ -593,8 +650,8 @@ declare function machine_to_svg_element<T>(u_jssm: jssm.Machine<T>, opts?: VizRe
  *  @deprecated Use {@link machine_to_dot} instead.
  */
 declare function dot<T>(machine: jssm.Machine<T>): string;
-export { configure, dot, dot_to_svg, fsl_to_dot, fsl_to_svg_string, fsl_to_svg_element, machine_to_dot, machine_to_svg_string, machine_to_svg_element, state_svg_label_texts, };
-export type { VizRenderOpts, RenderGroups };
+export { configure, dot, dot_to_svg, fsl_to_dot, fsl_to_svg_string, fsl_to_svg_element, machine_to_dot, machine_to_svg_string, machine_to_svg_element, state_svg_label_texts, slug_for, };
+export type { VizRenderOpts, RenderGroups, VizEngine };
 /** @internal */
 export declare const _test: {
     doublequote: typeof doublequote;

package/dist/fence/fence.js

@@ -22444,11 +22444,28 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
  *  `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}
  *
  */
 function wrap_parse(input, options) {
@@ -24206,7 +24223,7 @@ function fslSemanticSpans(text) {
  *  Useful for runtime diagnostics and for embedding in serialized machine
  *  snapshots so that deserializers can detect version-skew.
  */
-const version = "5.162.12";
+const version = "5.162.13";
 
 /**
  *  The FSL Markdown fence convention parser — pure, host-agnostic logic that
@@ -24252,7 +24269,7 @@ const INTERACTIVE_PARTS$1 = new Set(['editor', 'actions', 'toolbar', 'info-panel
 /**
  *  Parse a dimension value like `300`, `120px`, or `100%` into a
  *  {@link FenceDimension}.  A bare number is pixels.
- *  @param raw The value portion of a `width=`/`height=` token.
+ *  @param raw The value portion of a `width=`/`height=`/`max-width=`/`max-height=` token.
  *  @returns The parsed dimension, or `null` if malformed.
  *  @example parse_dimension('300')  // => { value: 300, unit: 'px' }
  *  @example parse_dimension('100%') // => { value: 100, unit: 'percent' }
@@ -24270,13 +24287,18 @@ const IDE_LAYOUT = ['title', 'image', 'actions', 'info-panel', 'toolbar', 'edito
 /**
  *  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' }
  */
 function parse_fence_info(info) {
     const tokens = info.trim().split(/\s+/).filter(Boolean);
@@ -24285,9 +24307,14 @@ function parse_fence_info(info) {
     const notes = [];
     let format = 'svg';
     let format_set = false;
-    let width = null;
-    let height = null;
     let ide = false;
+    // the four dimension tokens share one assignment path, keyed by token name
+    const dims = {
+        'width': null,
+        'height': null,
+        'max-width': null,
+        'max-height': null,
+    };
     for (const arg of args) {
         if (arg === 'ide') {
             ide = true;
@@ -24313,7 +24340,7 @@ function parse_fence_info(info) {
             }
             continue;
         }
-        if (arg.startsWith('width=') || arg.startsWith('height=')) {
+        if (arg.startsWith('width=') || arg.startsWith('height=') || arg.startsWith('max-width=') || arg.startsWith('max-height=')) {
             const eq = arg.indexOf('=');
             const key = arg.slice(0, eq);
             const raw = arg.slice(eq + 1);
@@ -24321,11 +24348,8 @@ function parse_fence_info(info) {
             if (dim === null) {
                 notes.push(`invalid ${key} value "${raw}" ignored`);
             }
-            else if (key === 'width') {
-                width = dim;
-            }
             else {
-                height = dim;
+                dims[key] = dim;
             }
             continue;
         }
@@ -24350,8 +24374,10 @@ function parse_fence_info(info) {
         parts,
         ide,
         format,
-        width,
-        height,
+        width: dims.width,
+        height: dims.height,
+        max_width: dims['max-width'],
+        max_height: dims['max-height'],
         interactive,
         notes
     };
@@ -29895,8 +29921,12 @@ const default_viz_colors = {
  */
 let viz_instance = null;
 /**
- *  Returns a cached @viz-js/viz instance, lazily instantiated on first call.
- *  Internal helper for the rendering functions.
+ *  Returns the Graphviz engine the render path should use: the engine
+ *  injected via {@link configure}`({ viz })` when one is set (checked
+ *  *before* the default import, so the `@viz-js/viz` WASM module is never
+ *  even loaded in environments that injected their own); otherwise a cached
+ *  `@viz-js/viz` instance, lazily instantiated on first call.  Internal
+ *  helper for the rendering functions.
  *  @internal
  */
 async function get_viz() {
@@ -29970,9 +30000,14 @@ function undoublequote(txt) {
  *  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
  */
 function slug_for(state) {
@@ -30994,9 +31029,10 @@ function fsl_to_dot(fsl, opts = {}) {
     return machine_to_dot(sm `${fsl}`, opts);
 }
 /**
- *  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 }');