jssm 5.159.0 → 5.159.2

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.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.159.0",
+  "version": "5.159.2",
   "engines": {
     "node": ">=10.0.0"
   },
@@ -352,8 +352,12 @@
     "reduce-to-639-1": "^1.1.0"
   },
   "peerDependencies": {
+    "@codemirror/autocomplete": ">=6",
+    "@codemirror/commands": ">=6",
     "@codemirror/language": ">=6",
+    "@codemirror/lint": ">=6",
     "@codemirror/state": ">=6",
+    "@codemirror/view": ">=6 <6.43.3 || >6.43.4",
     "@lezer/highlight": ">=1",
     "lit": ">=3"
   },
@@ -361,13 +365,22 @@
     "lit": {
       "optional": true
     },
+    "@codemirror/autocomplete": {
+      "optional": true
+    },
+    "@codemirror/commands": {
+      "optional": true
+    },
     "@codemirror/language": {
       "optional": true
     },
+    "@codemirror/lint": {
+      "optional": true
+    },
     "@codemirror/state": {
       "optional": true
     },
-    "@lezer/highlight": {
+    "@codemirror/view": {
       "optional": true
     }
   },