jssm 5.157.18 → 5.158.0

package/dist/deno/README.md

@@ -18,10 +18,10 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.157.18 at 7/3/2026, 1:55:46 AM
+* Generated for version 5.158.0 at 7/3/2026, 11:48:59 AM
 
 -->
-# jssm 5.157.18
+# jssm 5.158.0
 
 [**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
 [Documentation](https://stonecypher.github.io/jssm/docs/) ·
@@ -179,6 +179,27 @@ if (result.kind === 'text') console.log(result.content);
 
 
 
+<br/>
+
+## Static fence rendering (`jssm/fence`)
+
+`jssm/fence` renders FSL code fences to static, editor-parity-highlighted HTML — no browser, no editor, no live machine required — for Markdown pipelines, static site generators, and doc tooling.
+
+```typescript
+import { transform_markdown } from 'jssm/fence';
+
+const html = await transform_markdown(markdown);
+// every fsl/jssm fence becomes rendered, highlighted HTML
+// everything else in the document passes through untouched
+console.log(html);
+```
+
+`render_fence_gif` walks a machine's main path (or every edge, if there is no main path) into a looping animated GIF, one Graphviz layout patched per frame: 70cs per-frame delay, loops forever, and a 64-frame walk cap by default, all overridable via options.
+
+PNG, JPEG, and GIF output rasterize through the same optional backend as the CLI — install it with `npm install @resvg/resvg-wasm`.
+
+
+
 <br/>
 
 ## Web Components
@@ -312,7 +333,7 @@ That decision shows up everywhere downstream:
   or run `npm run benny` against your own machine.
 
 - **More thoroughly tested than any other JavaScript state-machine
-  library.**  7,902 tests at 100.0% line coverage
+  library.**  7,998 tests at 100.0% line coverage
   ([report](https://coveralls.io/github/StoneCypher/jssm)), plus
   fuzz testing via `fast-check`, with parser test data across ten natural
   languages and Emoji.
@@ -445,11 +466,11 @@ If your contribution is missing here, please open an issue.
 
 <br/>
 
-***7,902 tests***, run 82,944 times.
+***7,998 tests***, run 83,040 times.
 
-- 7,144 specs with 100.0% coverage
-- 758 fuzz tests with 52.7% coverage
-- 10,013 TypeScript lines - 0.8 tests per line, 8.3 generated tests per line
+- 7,240 specs with 100.0% coverage
+- 758 fuzz tests with 49.4% coverage
+- 10,615 TypeScript lines - 0.8 tests per line, 7.8 generated tests per line
 
 [![Actions Status](https://github.com/StoneCypher/jssm/workflows/Node%20CI/badge.svg)](https://github.com/StoneCypher/jssm/actions)
 [![NPM version](https://img.shields.io/npm/v/jssm.svg)](https://www.npmjs.com/package/jssm)

package/dist/deno/fence.d.ts

@@ -0,0 +1,18 @@
+/**
+ *  Bundle entry for the `jssm/fence` subpath: host-agnostic static rendering
+ *  of FSL markdown fences — HTML parts stacks with editor-parity
+ *  highlighting, animated walk GIFs, and a whole-document Markdown
+ *  transformer — plus the reusable primitives behind them (GIF89a encoder,
+ *  walk planner, SVG patching).
+ *
+ *  @see render_fence_html
+ *  @see transform_markdown
+ */
+export { render_fence_html, render_fence_gif, transform_markdown } from './fsl_fence_render.js';
+export type { FenceRenderOptions, GifRenderOptions } from './fsl_fence_render.js';
+export { encode_gif, quantize, lzw_encode } from './fsl_gif.js';
+export type { GifFrame, GifOptions, Quantized } from './fsl_gif.js';
+export { plan_walk } from './fsl_walk.js';
+export { highlight_fsl_runs, highlight_fsl_html } from './fsl_fence_highlight.js';
+export type { HighlightRun } from './fsl_fence_highlight.js';
+export { extract_state_fills, patch_state_fill } from './fsl_svg_patch.js';

package/dist/deno/fsl_fence_highlight.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Two-layer static FSL highlighter: the SAME `fslLanguage` stream grammar and
+ * `fslSemanticSpans` parser overlay the CodeMirror editor uses, merged into
+ * flat runs and (optionally) serialized to HTML. There is no third
+ * tokenizer — this is the parity guarantee between the editor and any
+ * static render (markdown fences, the cookbook, docs).
+ */
+/** One classified slice of highlighted FSL source. */
+export interface HighlightRun {
+    text: string;
+    /** Space-separated classes: `fsl-tok-*` token layer, `fsl-sem-*` semantic layer. */
+    classes: string;
+    /** The state name, present exactly on semantic state-name runs. */
+    state?: string;
+}
+/**
+ *  Tokenize FSL source through the SAME two layers the editor uses — the
+ *  `fslLanguage` stream grammar for token classes and `fslSemanticSpans` for
+ *  parser-derived roles — merged into flat runs whose concatenated text
+ *  reproduces the source byte-for-byte.  Semantic classes overlay token
+ *  classes (both are kept).
+ *
+ *  This is the parity guarantee: there is no third tokenizer, so static
+ *  output can never disagree with the editor.
+ *
+ *  @param source  FSL source text to classify.
+ *  @returns       Flat, gap-free, order-preserving runs; `runs.map(r => r.text).join('')` is `source`.
+ *
+ *  @example
+ *  highlight_fsl_runs('Red -> Green;').find(r => r.state === 'Red');
+ *  // { text: 'Red', classes: 'fsl-tok-variableName fsl-sem-state', state: 'Red' }
+ */
+export declare function highlight_fsl_runs(source: string): HighlightRun[];
+/**
+ *  Render FSL source as highlighted HTML (`<pre class="fsl-code">` inner
+ *  content) using {@link highlight_fsl_runs}.  Semantic state-name spans get
+ *  `data-state`; when `inline_colors` (default true) and the state appears in
+ *  `state_colors`, an inline `style="color:…"` ties the code block's state
+ *  names to the diagram's node colors with zero host CSS.
+ *
+ *  @param source  FSL source text to render.
+ *  @param opts.state_colors    Maps a state name to its diagram fill color (e.g. from `extract_state_fills`).
+ *  @param opts.inline_colors   Whether to emit inline `style="color:…"` for matched states. Defaults to `true`.
+ *  @returns       HTML markup for the highlighted source; unclassed runs are emitted as escaped text with no wrapping span.
+ *
+ *  @example
+ *  highlight_fsl_html('Red -> Green;', { state_colors: new Map([['Red', '#a00']]) });
+ *  // '…<span class="… fsl-sem-state" data-state="Red" style="color:#a00">Red</span>…'
+ */
+export declare function highlight_fsl_html(source: string, opts?: {
+    state_colors?: ReadonlyMap<string, string>;
+    inline_colors?: boolean;
+}): string;

package/dist/deno/fsl_fence_render.d.ts

@@ -0,0 +1,87 @@
+/**
+ *  The descriptor interpreter for the FSL Markdown fence convention: turns a
+ *  parsed {@link FenceDescriptor} plus FSL source into static HTML, and walks
+ *  a whole Markdown document replacing every `fsl`/`jssm` fence in place.
+ *  This is the integration point for the five pieces built ahead of it — the
+ *  fence-info parser, the viz pipeline, the rasterizer, the SVG fill
+ *  extractor, and the editor-parity highlighter.
+ *
+ *  @see notes/superpowers/specs/2026-06-23-fsl-markdown-fence-convention-design.md
+ */
+/** Options shared by the static fence renderers. */
+export interface FenceRenderOptions {
+    /** Inline state colors in code spans (default true).  @see highlight_fsl_html */
+    inline_colors?: boolean;
+}
+/**
+ *  Render one FSL markdown fence to static HTML per the fence convention:
+ *  parts stack top-down in the order written, sized by width/height, with
+ *  editor-parity code highlighting whose state names carry the diagram's own
+ *  node colors.  Invalid FSL renders a visible error box — this function
+ *  never throws for bad machine source.
+ *
+ *  @param source - The FSL machine source (fence body).
+ *  @param info - The fence info string (e.g. `'fsl image code width=300'`).
+ *  @param opts.inline_colors - Whether code spans carry inline diagram colors (default true).
+ *  @returns The rendered `<div class="fsl-fence">…</div>` markup.
+ *
+ *  @example
+ *  await render_fence_html('Red => Green => Red;', 'fsl');
+ *  // '<div class="fsl-fence" …><svg…/svg><pre class="fsl-code">…</pre></div>'
+ */
+export declare function render_fence_html(source: string, info: string, opts?: FenceRenderOptions): Promise<string>;
+/**
+ *  Replace every fsl/jssm fenced code block in a Markdown string with its
+ *  rendered static HTML; all other content passes through byte-identical.
+ *  Each fence is isolated — a broken machine becomes its own error box and
+ *  the rest of the document still renders.  Backtick fences of length ≥3
+ *  are recognized; tilde fences are out of scope (v1, spec §9).
+ *
+ *  @param markdown - The full Markdown document source.
+ *  @param opts.inline_colors - Whether code spans carry inline diagram colors (default true).
+ *  @returns The document with every `fsl`/`jssm` fence replaced by rendered HTML.
+ *
+ *  @example
+ *  await transform_markdown('# Doc\n\n```fsl\na -> b;\n```\n');
+ *  // '# Doc\n\n<div class="fsl-fence">…</div>\n'
+ */
+export declare function transform_markdown(markdown: string, opts?: FenceRenderOptions): Promise<string>;
+/** Options for {@link render_fence_gif}. */
+export interface GifRenderOptions {
+    /** Per-frame delay, centiseconds.  Default 70 (~0.7s). */
+    delay_cs?: number;
+    /** Netscape loop count; 0 = forever (default). */
+    loop?: number;
+    /** Walk-length ceiling; longer walks truncate.  Default 64. */
+    max_frames?: number;
+    /** Raster zoom percentage; 100 = 3× natural (the CLI raster convention). Default 100. */
+    scale?: number;
+    /** Fill painted on the walked state each frame.  Default '#ff9930'. */
+    highlight_fill?: string;
+}
+/**
+ *  Render an FSL machine as a looping animated GIF that walks its states:
+ *  main-path (`=>`) states in order when a main path exists, else an
+ *  every-edge tour.  Graphviz lays the machine out ONCE; each frame patches
+ *  one state's fill in the SVG string and rasterizes — identical geometry
+ *  across frames, no layout jitter.
+ *
+ *  @param source - The FSL machine source.
+ *  @param opts.delay_cs - Per-frame delay in centiseconds (default 70).
+ *  @param opts.loop - Netscape loop count, 0 = forever (default 0).
+ *  @param opts.max_frames - Walk-length ceiling; longer walks truncate (default 64).
+ *  @param opts.scale - Raster zoom percentage, 100 = 3× natural size (default 100).
+ *  @param opts.highlight_fill - Fill painted on the walked state (default '#ff9930').
+ *  @returns The encoded GIF89a bytes.
+ *
+ *  @throws {JssmError} on invalid FSL (programmatic callers want exceptions;
+ *  the HTML renderers catch and box instead).
+ *
+ *  @example
+ *  const gif = await render_fence_gif('Red => Green => Yellow => Red;');
+ *  // Uint8Array starting "GIF89a", three frames, looping forever
+ *
+ *  @see plan_walk
+ *  @see encode_gif
+ */
+export declare function render_fence_gif(source: string, opts?: GifRenderOptions): Promise<Uint8Array>;

package/dist/deno/fsl_gif.d.ts

@@ -0,0 +1,77 @@
+/** Result of {@link quantize}: an RGB palette plus one palette index per input pixel. */
+export interface Quantized {
+    /** RGB triples, `3 · palette_count` bytes. */
+    palette: Uint8Array;
+    /** Number of colors actually used (≤ the requested maximum). */
+    palette_count: number;
+    /** One palette index per input pixel. */
+    indices: Uint8Array;
+}
+/**
+ *  Reduce an RGBA8888 buffer to an indexed-color image with at most
+ *  `max_colors` colors, for GIF encoding.  Alpha is composited over white
+ *  (GIF v1 output carries no transparency).  When the input already has
+ *  `max_colors` or fewer distinct colors they are preserved exactly;
+ *  otherwise a median-cut partition supplies the palette and each pixel maps
+ *  to its box's weighted-average color.
+ *
+ *  @param rgba - Straight RGBA bytes; length must be a multiple of 4.
+ *  @param max_colors - Palette ceiling, 2..256.
+ *
+ *  @throws {JssmError} when `rgba.length` is not a multiple of 4.
+ *  @throws {JssmError} when `max_colors` is outside 2..256 — above 256 the
+ *  palette index no longer fits the `Uint8Array` indices this module packs
+ *  into GIF codes (silent index corruption instead of a clear failure);
+ *  below 2 there is no palette to quantize into.
+ *
+ *  @example
+ *  const q = quantize(new Uint8Array([255,0,0,255, 0,255,0,255]));
+ *  q.palette_count;  // 2
+ */
+export declare function quantize(rgba: Uint8Array, max_colors?: number): Quantized;
+/**
+ *  GIF-variant LZW compression: emits a leading clear code, grows code width
+ *  from `min_code_size + 1` up to the format's 12-bit ceiling, resets the
+ *  dictionary when full, terminates with EOI, and packs codes LSB-first.
+ *  Returns raw compressed bytes; the caller wraps them in GIF data sub-blocks.
+ *
+ *  @param indices - Palette indices, each `< 2^min_code_size`.
+ *  @param min_code_size - Bits needed for the palette (2..8 for GIF).
+ *
+ *  @example
+ *  lzw_encode(new Uint8Array([0, 0, 1]), 2);  // Uint8Array of packed codes
+ */
+export declare function lzw_encode(indices: Uint8Array, min_code_size: number): Uint8Array;
+/** One animation frame for {@link encode_gif}: straight RGBA8888 pixels. */
+export interface GifFrame {
+    rgba: Uint8Array;
+    width: number;
+    height: number;
+}
+/** Options for {@link encode_gif}. */
+export interface GifOptions {
+    /** Per-frame delay in centiseconds (GIF's native unit).  Default 70 (~0.7s). */
+    delay_cs?: number;
+    /** Netscape loop count; 0 = loop forever (the default). */
+    loop?: number;
+}
+/**
+ *  Encode RGBA frames as a looping animated GIF89a.  A single global color
+ *  table is quantized over the UNION of all frames' pixels (≤256 colors,
+ *  median-cut when over); each frame then maps nearest-neighbor into that
+ *  palette, so every frame is pixel-exact while the union stays within 256
+ *  distinct colors.  Frames must share dimensions.  No transparency,
+ *  full-frame disposal — simple and correct first.
+ *
+ *  @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.
+ *
+ *  @example
+ *  const red = { rgba: new Uint8Array([255,0,0,255]), width: 1, height: 1 };
+ *  const gif = encode_gif([red], { delay_cs: 50 });
+ *  gif.slice(0, 6);  // "GIF89a" bytes
+ */
+export declare function encode_gif(frames: GifFrame[], opts?: GifOptions): Uint8Array;

package/dist/deno/fsl_svg_patch.d.ts

@@ -0,0 +1,28 @@
+/**
+ *  Read each state's current fill color out of a graphviz-rendered machine
+ *  SVG, keyed by state name.  States whose shape carries no `fill` attribute
+ *  are omitted.
+ *
+ *  @param svg - SVG markup from the jssm viz pipeline (`fsl_to_svg_string`).
+ *
+ *  @example
+ *  extract_state_fills(await fsl_to_svg_string('A -> B;'));  // Map { 'A' => '#…', 'B' => '#…' }
+ *
+ *  @see patch_state_fill
+ */
+export declare function extract_state_fills(svg: string): Map<string, string>;
+/**
+ *  Return a copy of the SVG with the named state's first shape fill replaced.
+ *  The unmatched-state case returns the input unchanged (walk truncation and
+ *  render races surface as a missing highlight, never a throw).
+ *
+ *  @param svg - SVG markup from the jssm viz pipeline.
+ *  @param state - State name as written in FSL (unescaped).
+ *  @param fill - Any SVG paint value, e.g. `'#ff9930'`.
+ *
+ *  @example
+ *  patch_state_fill(svg, 'Red', '#ff9930');  // Red's node now renders orange
+ *
+ *  @see extract_state_fills
+ */
+export declare function patch_state_fill(svg: string, state: string, fill: string): string;

package/dist/deno/fsl_walk.d.ts

@@ -0,0 +1,21 @@
+import type { Machine } from './jssm.js';
+/**
+ *  Plan the frame sequence for an animated machine walk, as state names.
+ *
+ *  With main-path edges (FSL `=>`, `main_path === true`): start at the
+ *  machine's current state — the start state for a freshly-constructed
+ *  machine, which is what the fence pipeline always passes — and follow
+ *  main-path edges in declaration order, stopping at the first revisited
+ *  state (the animation loops, so the cycle closes visually).  Without any:
+ *  tour every edge in declaration order, emitting each edge's endpoints and
+ *  collapsing consecutive duplicates.
+ *
+ *  This is presentation, not simulation — a tour's consecutive entries need
+ *  not be legal transitions, and no machine state is mutated.
+ *
+ *  @example
+ *  plan_walk(sm`Red => Green => Yellow => Red;`);  // ['Red', 'Green', 'Yellow']
+ *
+ *  @see encode_gif
+ */
+export declare function plan_walk(machine: Machine<unknown>): string[];