jssm 5.118.0 → 5.120.0

package/README.md

@@ -18,10 +18,10 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.118.0 at 5/13/2026, 7:36:40 AM
+* Generated for version 5.119.0 at 5/13/2026, 4:32:50 PM
 
 -->
-# jssm 5.118.0
+# jssm 5.119.0
 
 [**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
 [Documentation](https://stonecypher.github.io/jssm/docs/) ·
@@ -120,6 +120,89 @@ usage patterns.
 
 
 
+<br/>
+
+## Command-line interface
+
+`jssm` ships a CLI for rendering FSL machines to images and other formats.
+
+### Installation
+
+```sh
+npm install -g jssm
+```
+
+This installs three binaries: `fsl` (the dispatcher), `jssm` (alias for `fsl`), and `fsl-render` (the render plugin).
+
+### Render
+
+Render a single machine to SVG (default):
+
+```sh
+fsl render machine.fsl
+# → machine.svg next to input
+```
+
+Specify a format:
+
+```sh
+fsl render machine.fsl --target=png --width=800
+fsl render machine.fsl --target=dot --stdout > machine.dot
+```
+
+Render multiple machines:
+
+```sh
+fsl render *.fsl --target=svg --out-dir=./diagrams
+```
+
+Pipe FSL via stdin:
+
+```sh
+cat machine.fsl | fsl render --target=dot | dot -Tpng > out.png
+```
+
+### Plugin architecture
+
+Every `fsl-<name>` executable on PATH is dispatched when you run `fsl <name>`. Third-party plugins follow the same contract as first-party `fsl-render`. See `notes/superpowers/specs/2026-05-12-fsl-cli-design.md` for the contract.
+
+### Library API
+
+The same render functions are available programmatically:
+
+```js
+import { render, renderSet } from 'jssm/cli';
+
+const result = await render(fslText, { target: 'svg' });
+if (result.kind === 'text') console.log(result.content);
+```
+
+
+
+<br/>
+
+## Web Components
+
+`jssm` ships Lit-based web components for use in plain HTML or as a base for framework wrappers.
+
+CDN one-liner (with an import map for `@viz-js/viz`):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/jssm/dist/cdn/viz.js"></script>
+<jssm-viz fsl="Off -> On -> Off;"></jssm-viz>
+```
+
+npm one-liner:
+
+```ts
+import 'jssm/wc/viz/define';
+// then use <jssm-viz fsl="..."> anywhere
+```
+
+Full documentation: [src/doc_md/WebComponents.md](src/doc_md/WebComponents.md).
+
+
+
 <br/>
 
 ## 60-second tour
@@ -198,7 +281,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.**  5,385 tests at 100.0% line coverage
+  library.**  5,809 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.
@@ -331,11 +414,11 @@ If your contribution is missing here, please open an issue.
 
 <br/>
 
-***5,385 tests***, run 14,394 times.
+***5,809 tests***, run 56,596 times.
 
-- 5,294 specs with 100.0% coverage
-- 91 fuzz tests with 62.5% coverage
-- 3,521 TypeScript lines - 1.5 tests per line, 4.1 generated tests per line
+- 5,296 specs with 100.0% coverage
+- 513 fuzz tests with 59.2% coverage
+- 3,593 TypeScript lines - 1.6 tests per line, 15.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/custom-elements.json

@@ -0,0 +1,138 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/ts/wc/jssm_viz_wc.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "normalize_viz_error",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "e",
+              "type": {
+                "text": "unknown"
+              },
+              "description": "The thrown value to normalize."
+            }
+          ],
+          "description": "Normalize an arbitrary thrown value into a JssmVizErrorDetail.\r\nAccepts anything (Error instances, JssmErrors with `.location`, plain\r\nstrings, etc.) and always produces a string `message`.\r\n\r\n```typescript\r\nnormalize_viz_error(new Error('boom'));\r\n// => { message: 'boom', location: undefined }\r\n\r\nnormalize_viz_error({ message: 'parse failed', location: { line: 1 } });\r\n// => { message: 'parse failed', location: { line: 1 } }\r\n\r\nnormalize_viz_error('bare string failure');\r\n// => { message: 'bare string failure', location: undefined }\r\n```"
+        },
+        {
+          "kind": "class",
+          "description": "Web component that renders a jssm machine as inline SVG.",
+          "name": "JssmViz",
+          "cssProperties": [
+            {
+              "description": "Minimum height of the rendered SVG container.",
+              "name": "--jssm-viz-min-height",
+              "default": "100px"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "fsl",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "FSL source to render.",
+              "attribute": "fsl"
+            },
+            {
+              "kind": "field",
+              "name": "engine",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Optional Graphviz layout engine override (e.g. 'dot', 'neato').",
+              "attribute": "engine"
+            },
+            {
+              "kind": "field",
+              "name": "_svg",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''"
+            },
+            {
+              "kind": "method",
+              "name": "_renderSvg",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": ""
+                }
+              },
+              "description": "Render the current `fsl` source to an SVG string via the headless\r\n`fsl_to_svg_string` pipeline. Updates `_svg` on success; emits a\r\n`viz-error` `CustomEvent` on failure. Guards against stale results\r\nwhen `fsl` changes mid-flight."
+            }
+          ],
+          "events": [
+            {
+              "name": "viz-error",
+              "type": {
+                "text": "CustomEvent<{ message: string; location?: unknown }>"
+              },
+              "description": "Fires when the FSL source fails to parse or render."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "fsl",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "FSL source to render.",
+              "fieldName": "fsl"
+            },
+            {
+              "name": "engine",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Optional Graphviz layout engine override (e.g. 'dot', 'neato').",
+              "fieldName": "engine"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "jssm-viz",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "normalize_viz_error",
+          "declaration": {
+            "name": "normalize_viz_error",
+            "module": "src/ts/wc/jssm_viz_wc.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "JssmViz",
+          "declaration": {
+            "name": "JssmViz",
+            "module": "src/ts/wc/jssm_viz_wc.ts"
+          }
+        }
+      ]
+    }
+  ]
+}