jssm 5.158.2 → 5.159.1

package/jssm.cli.d.cts

@@ -1,8 +1,20 @@
 /**
- * Render targets supported in v1. Future targets (mermaid, plantuml, scxml,
- * ascii, fsl) will be added in v0.2+.
+ * The render targets supported in v1, in canonical order (the CLI `--target`
+ * enum and `--help` list order).  This tuple is the single runtime source of
+ * truth: both the {@link RenderTarget} type and the `fsl-render` CLI's
+ * `--target` enum derive from it, so a new target is declared in exactly one
+ * place.  Future targets (mermaid, plantuml, scxml, ascii, fsl) land here in
+ * v0.2+.
+ *
+ * @example
+ * RENDER_TARGETS.includes('gif' as RenderTarget);  // true
+ */
+declare const RENDER_TARGETS: readonly ["svg", "dot", "png", "jpeg", "html", "gif"];
+/**
+ * A render target the CLI and library can produce.  Derived from
+ * {@link RENDER_TARGETS} so the type can never drift from the runtime enum.
  */
-declare type RenderTarget = 'svg' | 'dot' | 'png' | 'jpeg' | 'html' | 'gif';
+declare type RenderTarget = typeof RENDER_TARGETS[number];
 /**
  * Options accepted by `render()` and `renderSet()`.
  *

package/jssm.cli.d.ts

@@ -1,8 +1,20 @@
 /**
- * Render targets supported in v1. Future targets (mermaid, plantuml, scxml,
- * ascii, fsl) will be added in v0.2+.
+ * The render targets supported in v1, in canonical order (the CLI `--target`
+ * enum and `--help` list order).  This tuple is the single runtime source of
+ * truth: both the {@link RenderTarget} type and the `fsl-render` CLI's
+ * `--target` enum derive from it, so a new target is declared in exactly one
+ * place.  Future targets (mermaid, plantuml, scxml, ascii, fsl) land here in
+ * v0.2+.
+ *
+ * @example
+ * RENDER_TARGETS.includes('gif' as RenderTarget);  // true
+ */
+declare const RENDER_TARGETS: readonly ["svg", "dot", "png", "jpeg", "html", "gif"];
+/**
+ * A render target the CLI and library can produce.  Derived from
+ * {@link RENDER_TARGETS} so the type can never drift from the runtime enum.
  */
-declare type RenderTarget = 'svg' | 'dot' | 'png' | 'jpeg' | 'html' | 'gif';
+declare type RenderTarget = typeof RENDER_TARGETS[number];
 /**
  * Options accepted by `render()` and `renderSet()`.
  *

package/jssm.es5.d.cts

@@ -1920,11 +1920,21 @@ declare function fslCompletions(text: string, offset: number): CompletionItem[];
  */
 
 /**
- * Collect color / state / shape-enum semantic spans from `text`.
+ * Collect color / state / shape-enum semantic spans from `text`. State spans
+ * cover transition endpoints, state-declaration subjects, group-list members
+ * (`&G : [a b c];` — but not the group's own name, nor `&`/`...&` nested
+ * group references), and plain-label hook subjects (`on enter x do 'act';` —
+ * but not `&group` subjects). Every state span's `value` is the parser's
+ * resolved name (unquoted, unescaped), while `from`/`to` cover the source
+ * spelling including any quotes.
  *
  * @example
  *   fslSemanticSpans('state s : { color: crimson; };')
  *     .find(s => s.kind === 'color')?.value;   // => '#dc143cff'
+ *
+ * @example
+ *   fslSemanticSpans('&G : [a b];\na -> b;')
+ *     .filter(s => s.kind === 'state').length;   // => 4 (two members + two endpoints)
  */
 declare function fslSemanticSpans(text: string): SemanticSpan[];
 

package/jssm.es6.d.ts

@@ -1920,11 +1920,21 @@ declare function fslCompletions(text: string, offset: number): CompletionItem[];
  */
 
 /**
- * Collect color / state / shape-enum semantic spans from `text`.
+ * Collect color / state / shape-enum semantic spans from `text`. State spans
+ * cover transition endpoints, state-declaration subjects, group-list members
+ * (`&G : [a b c];` — but not the group's own name, nor `&`/`...&` nested
+ * group references), and plain-label hook subjects (`on enter x do 'act';` —
+ * but not `&group` subjects). Every state span's `value` is the parser's
+ * resolved name (unquoted, unescaped), while `from`/`to` cover the source
+ * spelling including any quotes.
  *
  * @example
  *   fslSemanticSpans('state s : { color: crimson; };')
  *     .find(s => s.kind === 'color')?.value;   // => '#dc143cff'
+ *
+ * @example
+ *   fslSemanticSpans('&G : [a b];\na -> b;')
+ *     .filter(s => s.kind === 'state').length;   // => 4 (two members + two endpoints)
  */
 declare function fslSemanticSpans(text: string): SemanticSpan[];
 

package/jssm.fence.d.ts

@@ -156,8 +156,9 @@ interface GifOptions {
  *  @param frames - At least one frame; all with identical width/height and
  *  `rgba.length === 4 · width · height`.
  *
- *  @throws {JssmError} on zero frames, mismatched dimensions, or an rgba
- *  buffer whose length contradicts its stated dimensions.
+ *  @throws {JssmError} on zero frames, a zero-width or zero-height frame,
+ *  mismatched dimensions, or an rgba buffer whose length contradicts its
+ *  stated dimensions.
  *
  *  @example
  *  const red = { rgba: new Uint8Array([255,0,0,255]), width: 1, height: 1 };

package/jssm_viz.es5.d.cts

@@ -3888,6 +3888,24 @@ declare function vc(col: string): string;
  *  @internal
  */
 declare function doublequote(txt: string): string;
+/**
+ *  Reverse {@link doublequote}: turn DOT's `\"` escape back into the literal
+ *  `"` that graphviz renders into SVG `<text>` content.  Used by
+ *  {@link state_svg_label_texts} to reconstruct a node's on-screen label from
+ *  the DOT label it was handed, so the fence renderer keys against exactly what
+ *  was drawn.
+ *
+ *  ```typescript
+ *  undoublequote('a\\"b');  // 'a"b'
+ *  undoublequote('safe');   // 'safe'
+ *  ```
+ *
+ *  @param txt A DOT-escaped attribute string (as produced by `doublequote`).
+ *  @returns The string with every `\"` collapsed back to `"`.
+ *
+ *  @internal
+ */
+declare function undoublequote(txt: string): string;
 /**
  *  Convert a state name into a URL-friendly slug suitable for use as the
  *  body of a dot/SVG node identifier.  The transformation is:
@@ -4282,6 +4300,50 @@ declare type VizRenderOpts = {
  *  @internal
  */
 declare function node_block_for<T>(u_jssm: Machine<T>, l_states: string[], state_index: Map<string, string>, state_kinds: Map<string, StateKind>, hide_labels: boolean, mode: RenderGroups): string;
+/**
+ *  The per-state group-chip map that {@link node_block_for} appends to labels
+ *  in a given render mode.  Mirrors that function's mode dispatch and calls the
+ *  very same chip sources — {@link chips_for_all_groups} for `'chips'`,
+ *  {@link plan_cluster_groups} (with identical inputs) for `'cluster'` — so a
+ *  reconstructed label can never disagree with the one graphviz was handed.
+ *  `'off'`, and any machine that declares no groups, yields an empty map.
+ *
+ *  @internal
+ */
+declare function chips_for_render_mode<T>(u_jssm: Machine<T>, l_states: string[], mode: RenderGroups): Map<string, string[]>;
+/**
+ *  The exact text graphviz places in each state's SVG `<text>` element(s) when
+ *  a machine is rendered via {@link machine_to_dot} / {@link fsl_to_svg_string}:
+ *  the state's display text plus any group chips the node builder appends, with
+ *  DOT's `\"` escaping undone (SVG carries the literal character).  A label that
+ *  wraps across lines becomes several `<text>` elements; this returns the lines
+ *  joined by `\n`, exactly how {@link extract_state_fills} reads them back — so
+ *  the derived key and the extracted key meet at the same string.
+ *
+ *  This is the single source of truth the static fence renderer keys its
+ *  highlight and recolor lookups against, so those lookups can never drift from
+ *  what was actually drawn — plain labels, group chips, and multi-line wraps
+ *  alike.  It is built by running the node builder's own
+ *  `label_with_chips(doublequote(display_text), chips)` and inverting the one
+ *  escaping step, so it follows any change to the label format for free.
+ *
+ *  @param u_jssm The machine being rendered.
+ *  @param opts Render flags; only `render_groups` affects the label text
+ *  (default `'cluster'`, matching `fsl_to_svg_string`).
+ *  @returns A map from each state name to its rendered SVG label text.
+ *
+ *  ```typescript
+ *  import { sm } from 'jssm';
+ *  import { state_svg_label_texts } from 'jssm/viz';
+ *
+ *  // a state in two groups renders a chip suffix in its node label
+ *  state_svg_label_texts(sm`&g1 : [a b]; &g2 : [a]; a -> b;`).get('a');  // 'a [g1]'
+ *  state_svg_label_texts(sm`a -> b;`).get('a');                          // 'a'
+ *  ```
+ *
+ *  @see extract_state_fills
+ */
+declare function state_svg_label_texts<T>(u_jssm: Machine<T>, opts?: VizRenderOpts): Map<string, string>;
 /**
  *  Render a {@link jssm.Machine} as a graphviz dot string.
  *
@@ -4416,6 +4478,7 @@ declare const _test: {
     style_for_state: typeof style_for_state;
     cluster_id_for: typeof cluster_id_for;
     label_with_chips: typeof label_with_chips;
+    undoublequote: typeof undoublequote;
     group_parent_map: typeof group_parent_map;
     group_ancestry: typeof group_ancestry;
     primary_group_for: typeof primary_group_for;
@@ -4423,6 +4486,7 @@ declare const _test: {
     groups_to_subgraph_string: typeof groups_to_subgraph_string;
     chips_for_all_groups: typeof chips_for_all_groups;
     node_block_for: typeof node_block_for;
+    chips_for_render_mode: typeof chips_for_render_mode;
     edge_attr_for: typeof edge_attr_for;
     edge_defaults_body: typeof edge_defaults_body;
     graph_attr_for: typeof graph_attr_for;
@@ -4430,5 +4494,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, version };
+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 };

package/jssm_viz.es6.d.ts

@@ -3888,6 +3888,24 @@ declare function vc(col: string): string;
  *  @internal
  */
 declare function doublequote(txt: string): string;
+/**
+ *  Reverse {@link doublequote}: turn DOT's `\"` escape back into the literal
+ *  `"` that graphviz renders into SVG `<text>` content.  Used by
+ *  {@link state_svg_label_texts} to reconstruct a node's on-screen label from
+ *  the DOT label it was handed, so the fence renderer keys against exactly what
+ *  was drawn.
+ *
+ *  ```typescript
+ *  undoublequote('a\\"b');  // 'a"b'
+ *  undoublequote('safe');   // 'safe'
+ *  ```
+ *
+ *  @param txt A DOT-escaped attribute string (as produced by `doublequote`).
+ *  @returns The string with every `\"` collapsed back to `"`.
+ *
+ *  @internal
+ */
+declare function undoublequote(txt: string): string;
 /**
  *  Convert a state name into a URL-friendly slug suitable for use as the
  *  body of a dot/SVG node identifier.  The transformation is:
@@ -4282,6 +4300,50 @@ declare type VizRenderOpts = {
  *  @internal
  */
 declare function node_block_for<T>(u_jssm: Machine<T>, l_states: string[], state_index: Map<string, string>, state_kinds: Map<string, StateKind>, hide_labels: boolean, mode: RenderGroups): string;
+/**
+ *  The per-state group-chip map that {@link node_block_for} appends to labels
+ *  in a given render mode.  Mirrors that function's mode dispatch and calls the
+ *  very same chip sources — {@link chips_for_all_groups} for `'chips'`,
+ *  {@link plan_cluster_groups} (with identical inputs) for `'cluster'` — so a
+ *  reconstructed label can never disagree with the one graphviz was handed.
+ *  `'off'`, and any machine that declares no groups, yields an empty map.
+ *
+ *  @internal
+ */
+declare function chips_for_render_mode<T>(u_jssm: Machine<T>, l_states: string[], mode: RenderGroups): Map<string, string[]>;
+/**
+ *  The exact text graphviz places in each state's SVG `<text>` element(s) when
+ *  a machine is rendered via {@link machine_to_dot} / {@link fsl_to_svg_string}:
+ *  the state's display text plus any group chips the node builder appends, with
+ *  DOT's `\"` escaping undone (SVG carries the literal character).  A label that
+ *  wraps across lines becomes several `<text>` elements; this returns the lines
+ *  joined by `\n`, exactly how {@link extract_state_fills} reads them back — so
+ *  the derived key and the extracted key meet at the same string.
+ *
+ *  This is the single source of truth the static fence renderer keys its
+ *  highlight and recolor lookups against, so those lookups can never drift from
+ *  what was actually drawn — plain labels, group chips, and multi-line wraps
+ *  alike.  It is built by running the node builder's own
+ *  `label_with_chips(doublequote(display_text), chips)` and inverting the one
+ *  escaping step, so it follows any change to the label format for free.
+ *
+ *  @param u_jssm The machine being rendered.
+ *  @param opts Render flags; only `render_groups` affects the label text
+ *  (default `'cluster'`, matching `fsl_to_svg_string`).
+ *  @returns A map from each state name to its rendered SVG label text.
+ *
+ *  ```typescript
+ *  import { sm } from 'jssm';
+ *  import { state_svg_label_texts } from 'jssm/viz';
+ *
+ *  // a state in two groups renders a chip suffix in its node label
+ *  state_svg_label_texts(sm`&g1 : [a b]; &g2 : [a]; a -> b;`).get('a');  // 'a [g1]'
+ *  state_svg_label_texts(sm`a -> b;`).get('a');                          // 'a'
+ *  ```
+ *
+ *  @see extract_state_fills
+ */
+declare function state_svg_label_texts<T>(u_jssm: Machine<T>, opts?: VizRenderOpts): Map<string, string>;
 /**
  *  Render a {@link jssm.Machine} as a graphviz dot string.
  *
@@ -4416,6 +4478,7 @@ declare const _test: {
     style_for_state: typeof style_for_state;
     cluster_id_for: typeof cluster_id_for;
     label_with_chips: typeof label_with_chips;
+    undoublequote: typeof undoublequote;
     group_parent_map: typeof group_parent_map;
     group_ancestry: typeof group_ancestry;
     primary_group_for: typeof primary_group_for;
@@ -4423,6 +4486,7 @@ declare const _test: {
     groups_to_subgraph_string: typeof groups_to_subgraph_string;
     chips_for_all_groups: typeof chips_for_all_groups;
     node_block_for: typeof node_block_for;
+    chips_for_render_mode: typeof chips_for_render_mode;
     edge_attr_for: typeof edge_attr_for;
     edge_defaults_body: typeof edge_defaults_body;
     graph_attr_for: typeof graph_attr_for;
@@ -4430,5 +4494,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, version };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.158.2",
+  "version": "5.159.1",
   "engines": {
     "node": ">=10.0.0"
   },