@mantaq/viz 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anders Can
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @mantaq/viz
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Draws a Mantaq machine in the browser and lets you walk it. Input is a viz document: versioned, deterministic JSON. `@mantaq/inspect` makes one from your machine; this package only reads it, and runs nothing.
+
+- `@mantaq/viz`: the document. Types, `parseViz` / `validateViz` (untrusted JSON → `Either<VizIssue[], VizDocument>`, every issue with its path), `serializeViz`, and the walk (`movesFrom`, `decodePath`, …). No DOM.
+- `@mantaq/viz/viewer`: `mountViewer(root, document)` / `mountVizText(root, { source, text })` to embed it in a page, plus `@mantaq/viz/viewer.css`.
+- `@mantaq/viz/standalone`, `@mantaq/viz/live`: whole-page entries used by `mantaq-inspect` (one HTML file) and the Vite plugin (live page).
+
+Dev page with the bundled examples: `vp run viz:export`, then `cd packages/viz && vp dev`. It loads `examples/examples.json`, `?src=<url>`, or a picked file.
+
+## Walking the graph
+
+The viewer keeps a cursor on one state, starting at the initial one. The panel lists what can happen next, in three groups:
+
+- **Send an input**: edges on input events.
+- **Effect reports back**: internal events that an effect of the current state declares in `sends` (`m.effect(state, { name, sends: [...], fn })`). Entering `submitting` runs `chargeCard`, which sends `paymentOk | paymentFail | paymentTimeout`.
+- **Other internal events**: internal events that no effect of the state declares.
+
+Take a step with a panel button, by clicking a pulsing edge, or by clicking a state that exactly one next step reaches. An undetermined edge (`to: null`) offers each target its AST explanation names. Without one, it cannot be taken. A final state ends the walk. **Back** (or ←), **Reset** and the path list undo steps. The standalone page keeps the walk in the URL: `?step=` holds one edge id per step, plus `~target` for an undetermined edge.
+
+Nothing runs. The walk follows declarations, so guards are not evaluated, and a path may not happen at runtime. The logic is in `src/moves.ts`: `movesFrom`, `unhandledSends`, `decodePath`.
+
+## Schema (v7)
+
+`VizDocument { schemaVersion: 7, machines: VizMachine[] }`, keys sorted, two-space indent. Types in `src/schema.ts`.
+
+| field              | meaning                                                                                                                                                                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `machine.states[]` | `id` (region-prefixed `region.state`), `region`, `initial`, `final`, `effects` (`[{ name, sends }]` run on entry, registration order; `sends`: declared event ids, `null` = not declared), `coverage` (`null` = no run, else `{ hits }`)                      |
+| `edge.from`        | a state id, `__initial__`, or `*` (`region.*` in a region): an `onAny` registration, meaning any non-final state. `*` is never in `states`; a `stay` from `*` has `to: "*"`                                                                                   |
+| `machine.events[]` | `id`, `internal`, `payloadType` (always `null`: erased at runtime)                                                                                                                                                                                            |
+| `edge.kind`        | `initial` · `transition` · `effect` (state runs effects on entry) · `stay` (handled, no state change: a registration without `to`, or observed while fuzzing)                                                                                                 |
+| `edge.to`          | `null` = **undetermined**: only for actors that carry no `to` declarations                                                                                                                                                                                    |
+| `edge.origin`      | `declared` (builder `to`, vouched for by the type checker) · `probe` (synthetic traversal, undeclared actors) · `fuzz` (observed only while fuzzing)                                                                                                          |
+| `edge.explanation` | `null` (no handler: initial/effect, or AST not run) · `{ status: "analyzed", location, registration, branches, payloadReads, contextReads, contextWrites, readsActorState, comparisons, literals }` · `{ status: "not_analyzed", location, reason, snippet }` |
+| `machine.fuzz`     | `null` or `{ seed, iterations, corpus: [{ steps, discovered }], errors: [{ from, event, message, steps }] }`; every sequence is shrunk and replayable from a fresh actor                                                                                      |
+
+Bump `VIZ_SCHEMA_VERSION` on any breaking change. The validator accepts only the current version.
+
+## Coverage: two sources, two questions
+
+The viewer's "Coverage from" picker dims elements with zero hits. What dimmed means depends on the source:
+
+- **example tests** (`tested`): no test exercises this. It is the classic "what is untested" view, and the default when tests are supplied. Supply the event sequences your tests send (`inspect({ tests })`).
+- **fuzz runs** (`coverage`): no fuzz run produced this. Fuzzing reaches almost everything, so little is dimmed. What does stay dimmed is usually a **declared but unreached edge**: the handler lists the target in `to`, but its guards may never allow it. Saga's `compensatingRefund -REFUND_DONE-> failed` is an example. The edge panel calls these out. Fuzzing is not proof, so check the handler.

package/dist/embed-BRQxeM4W.d.mts

@@ -0,0 +1,32 @@
+import { r as VizIssue, u as VizDocument } from "./validate-3D5LrtlE.mjs";
+declare const STRUCTURE_BANNER = "Click a pulsing edge, or a state it leads to, to walk the machine. Edges come from each handler's declared `to` list and effects' `sends`; guards are not evaluated, so a path here may not happen at runtime.";
+declare const FUZZ_NOTE = "Green edges were observed while fuzzing but not declared. Fuzzing finds behaviour; it never proves an edge is impossible.";
+interface ViewerOptions {
+  /** Title element. Embedded viewers use `h2`/`h3` to fit the host page's outline. */
+  heading?: "h1" | "h2" | "h3";
+  /** Machine to show first; defaults to the first one. */
+  machine?: string;
+  /** Encoded steps to open on (from `?step=`), in the shown machine. */
+  steps?: ReadonlyArray<string>;
+  /** Called after every walk or machine change, e.g. to keep the URL shareable. */
+  onNavigate?: (where: {
+    machine: string;
+    steps: string[];
+  }) => void;
+}
+/**
+ * Mount a viewer for an viz document into `root`. Walking the graph moves a
+ * cursor over the drawn edges; no actor runs. The document is the only input.
+ */
+declare function mountViewer(root: HTMLElement, viz: VizDocument, options?: ViewerOptions): void;
+/** Replace `root` with a list of reasons `source` cannot be shown. */
+declare function showIssues(root: HTMLElement, context: {
+  source: string;
+  issues: VizIssue[];
+}): void;
+/** Validate viz JSON text and mount it, or list what is wrong with it. */
+declare function mountVizText(root: HTMLElement, context: {
+  source: string;
+  text: string;
+}, options?: ViewerOptions): void;
+export { ViewerOptions as a, STRUCTURE_BANNER as i, showIssues as n, mountViewer as o, FUZZ_NOTE as r, mountVizText as t };