@mantaq/viz 0.1.0 → 0.2.1

package/README.md

@@ -18,22 +18,25 @@ The viewer keeps a cursor on one state, starting at the initial one. The panel l
 
 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                                                                                      |
+**Static walk** (standalone HTML, `mantaq-inspect --out`): 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`.
+
+**Live** (the Vite plugin page, or `mountViewer(root, doc, { driver })`): steps run the real actor through `createDriver` from `@mantaq/inspect/drive`, so guards are evaluated. Timers advance by button, and **Back** replays the path from a fresh actor.
+
+## Schema (v8)
+
+`VizDocument { schemaVersion: 8, 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 }`), `doc` (leading JSDoc of the `state(...)` declaration, `null` = undocumented or AST not run) |
+| `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), `doc` (leading JSDoc of the `event(...)` declaration, `null` = none)                                                                                                                                                                                              |
+| `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 }`                                                                         |
+| `edge.doc`         | leading JSDoc of the `m.on` / `m.onAny` call behind the edge; `null` = undocumented, no handler, or AST not run                                                                                                                                                                                                                       |
+| `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.
 

package/dist/{embed-BRQxeM4W.d.mts → embed-CISoaFIK.d.mts}

@@ -1,4 +1,4 @@
-import { r as VizIssue, u as VizDocument } from "./validate-3D5LrtlE.mjs";
+import { d as VizDriver, r as VizIssue, u as VizDocument } from "./validate-C_EXBtem.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 {
@@ -6,8 +6,13 @@ interface ViewerOptions {
   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. */
+  /** Encoded steps to open on (from `?step=`), in the shown machine. With a `driver`, live steps replayed through it. */
   steps?: ReadonlyArray<string>;
+  /**
+   * Runs the machine for real: steps go to the driver and the cursor follows its state.
+   * The driver runs one machine, so the machine picker is hidden.
+   */
+  driver?: VizDriver;
   /** Called after every walk or machine change, e.g. to keep the URL shareable. */
   onNavigate?: (where: {
     machine: string;

package/dist/{embed-BtlbyzmZ.mjs → embed-QX7vRXoL.mjs}

@@ -1,4 +1,4 @@
-import { a as stateAfter, d as coveredByAny, f as isAnyState, i as movesFrom, n as decodePath, o as unhandledSends, p as scopeOf, r as encodeStep, s as parseViz, t as routingWarnings } from "./routing-BNJN5Oiu.mjs";
+import { a as encodeStep, c as stateAfter, g as scopeOf, h as isAnyState, i as encodeLiveStep, l as unhandledSends, m as coveredByAny, n as decodeLiveSteps, o as movesFrom, r as decodePath, s as payloadSamples, t as routingWarnings, u as parseViz } from "./routing-xXYo05xv.mjs";
 import { Either } from "@mantaq/utils";
 import { Graph, layout } from "@dagrejs/dagre";
 // src/viewer/dom.ts
@@ -641,6 +641,7 @@ function edgePanel(doc, edge, machine) {
 			["source", isAnyState(edge.from) ? "any state (onAny)" : edge.from],
 			["event", edge.kind === "initial" ? "(initial)" : `${edge.event}${internal ? " (internal)" : ""}`],
 			["target", targetText$1(edge)],
+			["doc", edge.doc ?? "none"],
 			["kind", edge.kind],
 			["origin", ORIGIN_LABELS[edge.origin]],
 			["emits", joined(edge.emits)],
@@ -665,6 +666,7 @@ function statePanel(doc, state, context) {
 		"data-selected-state": state.id
 	}, [html(doc, "h2", {}, [`State ${state.id}`]), list(doc, [
 		["id", state.id],
+		["doc", state.doc ?? "none"],
 		["region", state.region ?? "(root)"],
 		["flags", joined(flags)],
 		["effects on entry", joined(state.effects.map((effect) => effect.sends === null ? effect.name : `${effect.name} (sends ${effect.sends.join(", ") || "nothing"})`))],
@@ -719,6 +721,12 @@ function button(doc, label, context) {
 	element.addEventListener("click", context.onClick);
 	return element;
 }
+function docNote(doc, note) {
+	return note.text === null ? null : html(doc, "p", {
+		class: "doc",
+		"data-doc": note.scope
+	}, [note.text]);
+}
 function targetText(move, target, current) {
 	return target === current && move.edge.kind === "stay" ? "stays" : `→ ${target}`;
 }
@@ -728,9 +736,13 @@ function moveItem(doc, move, context) {
 	if (move.targets.length === 0) return html(doc, "li", { "data-move": edge.id }, [
 		code(doc, edge.event),
 		via,
-		html(doc, "span", { class: "muted" }, [" → ? target depends on payload or context"])
+		html(doc, "span", { class: "muted" }, [" → ? target depends on payload or context"]),
+		docNote(doc, {
+			text: edge.doc,
+			scope: "edge"
+		})
 	]);
-	return html(doc, "li", { "data-move": edge.id }, move.targets.map((target) => button(doc, [
+	return html(doc, "li", { "data-move": edge.id }, [...move.targets.map((target) => button(doc, [
 		code(doc, edge.event),
 		` ${targetText(move, target, context.current)}`,
 		...via ? [via] : []
@@ -743,7 +755,10 @@ function moveItem(doc, move, context) {
 			"data-take": edge.id,
 			"data-target": target
 		}
-	})));
+	})), docNote(doc, {
+		text: edge.doc,
+		scope: "edge"
+	})]);
 }
 function effectsSection(doc, machine, current) {
 	const effects = machine.states.find((state) => state.id === current)?.effects ?? [];
@@ -805,39 +820,206 @@ function pathSection(doc, context) {
 		attrs: { "data-rewind": "0" }
 	})]), ...items])]);
 }
+function describeStep(step) {
+	if (step.kind === "advance") return `advance ${step.ms} ms`;
+	return step.payload === null ? step.event : `${step.event} ${JSON.stringify(step.payload)}`;
+}
+/** The clock starts at 0 and only `advance` steps move it. */
+function elapsed(steps) {
+	return steps.reduce((sum, step) => sum + (step.kind === "advance" ? step.ms : 0), 0);
+}
+function timersSection(doc, context) {
+	const now = elapsed(context.state.steps);
+	const input = html(doc, "input", {
+		type: "number",
+		min: "0",
+		value: "100",
+		"aria-label": "milliseconds",
+		"data-advance-ms": ""
+	});
+	const problem = html(doc, "p", {
+		class: "explore-warning",
+		role: "alert",
+		hidden: ""
+	}, ["Enter a number of milliseconds, 0 or more."]);
+	const advance = () => {
+		const ms = Number(input.value);
+		const valid = input.value.trim() !== "" && Number.isFinite(ms) && ms >= 0;
+		problem.toggleAttribute("hidden", valid);
+		if (valid) context.send({
+			kind: "advance",
+			ms
+		});
+	};
+	return html(doc, "div", { class: "explore-time" }, [
+		html(doc, "h3", {}, ["Time"]),
+		html(doc, "ul", { "data-group": "timers" }, context.state.timers.map((timer) => {
+			const remaining = Math.max(0, timer.deadline - now);
+			return html(doc, "li", { "data-timer": timer.id }, [button(doc, [`advance ${remaining} ms → ${timer.eventName ?? timer.id}`], {
+				onClick: () => context.send({
+					kind: "advance",
+					ms: remaining
+				}),
+				attrs: { "data-advance-timer": timer.id }
+			})]);
+		})),
+		context.state.timers.length === 0 ? html(doc, "p", {
+			class: "muted",
+			"data-no-timers": ""
+		}, ["No timers pending."]) : null,
+		html(doc, "div", {}, [
+			input,
+			" ms ",
+			button(doc, ["advance"], {
+				onClick: advance,
+				attrs: { "data-advance": "" }
+			})
+		]),
+		problem
+	]);
+}
+function liveMovesSection(doc, machine, context) {
+	const current = context.state.state;
+	if (context.final) return html(doc, "p", {
+		class: "explore-end explore-done",
+		role: "status"
+	}, [html(doc, "strong", {}, ["Done."]), ` ${current} is final: the actor has stopped.`]);
+	const handled = new Set(movesFrom(machine, current).map((move) => move.edge.event));
+	const inputs = machine.events.filter((event) => !event.internal).map((event) => event.id);
+	const events = [.../* @__PURE__ */ new Set([...handled, ...inputs])].sort();
+	const json = html(doc, "textarea", {
+		rows: "2",
+		placeholder: "payload as JSON (empty: the sample, or none)",
+		"aria-label": "payload JSON",
+		"data-payload-json": ""
+	});
+	const problem = html(doc, "p", {
+		class: "explore-warning",
+		role: "alert",
+		hidden: ""
+	}, ["Payload is not valid JSON."]);
+	const payloadFor = (sample) => {
+		try {
+			if (json.value.trim() !== "") return { value: JSON.parse(json.value) };
+			return { value: sample === null || sample.value === "" ? null : JSON.parse(sample.value) };
+		} catch {
+			return null;
+		}
+	};
+	return html(doc, "div", { class: "explore-moves" }, [
+		html(doc, "h3", {}, ["Send"]),
+		json,
+		problem,
+		html(doc, "ul", { "data-group": "live" }, events.map((event) => {
+			const samples = payloadSamples(machine, event);
+			const sample = samples.length === 0 ? null : html(doc, "select", {
+				"aria-label": `${event} payload sample`,
+				"data-sample": event
+			}, [html(doc, "option", { value: "" }, ["no payload"]), ...samples.map((each) => html(doc, "option", { value: JSON.stringify(each) }, [JSON.stringify(each)]))]);
+			return html(doc, "li", { "data-send-item": event }, [
+				button(doc, [code(doc, event)], {
+					onClick: () => {
+						const payload = payloadFor(sample);
+						problem.toggleAttribute("hidden", payload !== null);
+						if (payload !== null) context.send({
+							kind: "event",
+							event,
+							payload: payload.value
+						});
+					},
+					attrs: { "data-send": event }
+				}),
+				sample,
+				handled.has(event) ? null : html(doc, "span", {
+					class: "muted",
+					"data-ignored": ""
+				}, [` ignored in ${current}`])
+			]);
+		}))
+	]);
+}
+function outcomeText(last) {
+	if (last.outcome === "transition") return ` ${last.from} → ${last.to}`;
+	if (last.outcome === "stay") return ` handled in ${last.from}: stays`;
+	return ` ignored in ${last.from}: no handler`;
+}
+function liveResultSection(doc, state) {
+	const { last } = state;
+	return html(doc, "div", { class: "explore-live" }, [last === null ? html(doc, "p", { class: "muted" }, ["Nothing has run yet."]) : html(doc, "div", {
+		class: "explore-outcome",
+		"data-outcome": last.outcome
+	}, [
+		html(doc, "p", {}, [code(doc, last.event), outcomeText(last)]),
+		last.effects.length === 0 ? null : html(doc, "p", { "data-live-effects": "" }, ["Effects run: ", ...last.effects.flatMap((name, index) => [index === 0 ? "" : ", ", code(doc, name)])]),
+		last.error === null ? null : html(doc, "p", {
+			class: "explore-warning",
+			role: "alert",
+			"data-live-error": ""
+		}, [`Handler threw: ${last.error}`])
+	]), html(doc, "p", { "data-live-context": "" }, ["Context: ", code(doc, JSON.stringify(state.context))])]);
+}
+function livePathSection(doc, context, state) {
+	return html(doc, "div", { class: "explore-path" }, [html(doc, "h3", {}, ["Path"]), html(doc, "ol", {}, [html(doc, "li", { "aria-current": state.steps.length === 0 ? "step" : null }, [button(doc, ["start"], {
+		onClick: () => context.rewind(0),
+		attrs: { "data-rewind": "0" }
+	})]), ...state.steps.map((step, index) => html(doc, "li", { "aria-current": index === state.steps.length - 1 ? "step" : null }, [button(doc, [describeStep(step)], {
+		onClick: () => context.rewind(index + 1),
+		attrs: { "data-rewind": String(index + 1) }
+	})]))])]);
+}
+function nowSection(doc, machine, context) {
+	const { current, final } = context;
+	return [html(doc, "p", { class: "explore-now" }, [
+		"In ",
+		html(doc, "strong", {}, [current]),
+		final ? " (final)" : ""
+	]), docNote(doc, {
+		text: machine.states.find((state) => state.id === current)?.doc ?? null,
+		scope: "state"
+	})];
+}
 /** Side-panel section: where the walk is, what can happen next, and how it got here. */
 function explorePanel(doc, context) {
-	const { machine, path } = context;
-	const current = stateAfter(machine, path) ?? "";
+	const { machine, path, live } = context;
+	const current = live?.state.state ?? stateAfter(machine, path) ?? "";
 	const final = machine.states.find((state) => state.id === current)?.final === true;
-	const moves = movesFrom(machine, current);
+	const length = live?.state.steps.length ?? path.length;
 	return html(doc, "section", {
 		class: "explore",
 		"data-current": current,
 		"data-done": final ? "" : null
 	}, [
 		html(doc, "h2", {}, ["Explore"]),
-		html(doc, "p", { class: "explore-now" }, [
-			"In ",
-			html(doc, "strong", {}, [current]),
-			final ? " (final)" : ""
-		]),
-		effectsSection(doc, machine, current),
-		movesSection(doc, moves, {
+		...nowSection(doc, machine, {
+			current,
+			final
+		}),
+		...live ? [
+			liveResultSection(doc, live.state),
+			liveMovesSection(doc, machine, {
+				state: live.state,
+				send: live.send,
+				final
+			}),
+			final ? null : timersSection(doc, {
+				state: live.state,
+				send: live.send
+			})
+		] : [effectsSection(doc, machine, current), movesSection(doc, movesFrom(machine, current), {
 			current,
 			final,
 			take: context.take
-		}),
+		})],
 		html(doc, "div", { class: "explore-controls" }, [button(doc, ["Back"], {
-			onClick: () => context.rewind(path.length - 1),
-			disabled: path.length === 0,
+			onClick: () => context.rewind(length - 1),
+			disabled: length === 0,
 			attrs: { "data-explore-action": "back" }
 		}), button(doc, ["Reset"], {
 			onClick: () => context.rewind(0),
-			disabled: path.length === 0,
+			disabled: length === 0,
 			attrs: { "data-explore-action": "reset" }
 		})]),
-		pathSection(doc, context)
+		live ? livePathSection(doc, context, live.state) : pathSection(doc, context)
 	]);
 }
 /**
@@ -845,7 +1027,7 @@ function explorePanel(doc, context) {
 * a next-step edge with one target, or a state exactly one next step reaches.
 */
 function clickStep(machine, context) {
-	const current = stateAfter(machine, context.path);
+	const current = context.live ?? stateAfter(machine, context.path);
 	if (current === null) return null;
 	const { selection } = context;
 	const steps = movesFrom(machine, current).flatMap((move) => move.targets.map((to) => ({
@@ -858,7 +1040,7 @@ function clickStep(machine, context) {
 /** Mark the walk on the drawn graph: current state, path taken, possible next steps. */
 function markExplore(root, context) {
 	const { machine, path } = context;
-	const current = stateAfter(machine, path);
+	const current = context.live ?? stateAfter(machine, path);
 	const moves = current === null ? [] : movesFrom(machine, current);
 	const next = new Set(moves.filter((move) => move.targets.length > 0).map((move) => move.edge.id));
 	const reachable = new Set(moves.flatMap((move) => move.targets).filter((to) => to !== current));
@@ -877,6 +1059,7 @@ function markExplore(root, context) {
 }
 // src/viewer/viewer.ts
 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.";
+const LIVE_BANNER = "Live: the real machine runs. Send an input and the cursor follows its actual state; guards and effects run.";
 const FUZZ_NOTE = "Green edges were observed while fuzzing but not declared. Fuzzing finds behaviour; it never proves an edge is impossible.";
 function effectiveMode(view, machine) {
 	const modes = availableModes(machine);
@@ -933,8 +1116,11 @@ function mountViewer(root, viz, options = {}) {
 		machineId: first?.id ?? "",
 		selection: null,
 		coverage: null,
-		path: first === void 0 ? [] : decodePath(first, options.steps ?? [])
+		path: first === void 0 || options.driver !== void 0 ? [] : decodePath(first, options.steps ?? []),
+		live: null
 	};
+	const { driver } = options;
+	if (driver !== void 0) view.live = replay(driver, decodeLiveSteps(options.steps ?? []));
 	let back = () => void 0;
 	root.addEventListener("keydown", (event) => {
 		if (!("key" in event) || event.target instanceof HTMLSelectElement) return;
@@ -959,42 +1145,71 @@ function mountViewer(root, viz, options = {}) {
 				machine,
 				path: view.path,
 				take,
-				rewind
+				rewind,
+				...view.live === null ? {} : { live: {
+					state: view.live,
+					send
+				} }
 			}), renderPanel(doc, machine, {
 				selection: view.selection,
 				select
 			}));
 			markExplore(root, {
 				machine,
-				path: view.path
+				path: view.path,
+				...liveState(view)
 			});
 			markSelection(root, view.selection);
 		};
 		const walked = () => {
+			const steps = view.live === null ? view.path.map((step) => encodeStep(machine, step)) : view.live.steps.map(encodeLiveStep);
 			options.onNavigate?.({
 				machine: machine.id,
-				steps: view.path.map((step) => encodeStep(machine, step))
+				steps
 			});
 			refresh();
 		};
+		const send = (step) => {
+			if (driver === void 0) return;
+			view.live = stepSafely(driver, {
+				before: view.live,
+				step
+			});
+			walked();
+		};
 		const take = (step) => {
+			if (driver !== void 0) {
+				const event = machine.edges.find((edge) => edge.id === step.edge)?.event;
+				if (event !== void 0) send({
+					kind: "event",
+					event,
+					payload: null
+				});
+				return;
+			}
 			view.path = [...view.path, step];
 			walked();
 		};
 		const rewind = (length) => {
+			if (driver !== void 0 && view.live !== null) {
+				view.live = replay(driver, view.live.steps.slice(0, Math.max(0, length)));
+				walked();
+				return;
+			}
 			view.path = view.path.slice(0, Math.max(0, length));
 			walked();
 		};
 		const select = (selection) => {
 			const step = clickStep(machine, {
 				path: view.path,
-				selection
+				selection,
+				...liveState(view)
 			});
 			view.selection = selection;
 			if (step === null) refresh();
 			else take(step);
 		};
-		back = () => rewind(view.path.length - 1);
+		back = () => rewind((view.live?.steps.length ?? view.path.length) - 1);
 		root.append(headerOf(doc, {
 			viz,
 			machine,
@@ -1002,11 +1217,12 @@ function mountViewer(root, viz, options = {}) {
 			heading: options.heading ?? "h1",
 			mode,
 			render,
-			onNavigate: options.onNavigate
+			onNavigate: options.onNavigate,
+			live: driver !== void 0
 		}), html(doc, "p", {
 			class: "banner",
 			role: "note"
-		}, [banner(machine)]), legend(doc, {
+		}, [driver === void 0 ? banner(machine) : LIVE_BANNER]), legend(doc, {
 			mode,
 			machine
 		}), html(doc, "div", { class: "viz-main" }, [html(doc, "div", { class: "canvas" }, [renderGraph(doc, machine, {
@@ -1017,11 +1233,32 @@ function mountViewer(root, viz, options = {}) {
 	}
 	render();
 }
+/** A driver that throws leaves the state where it was and shows the message as a handler error. */
+function stepSafely(driver, context) {
+	const { before, step } = context;
+	try {
+		return driver.step(step);
+	} catch (error) {
+		if (before === null) throw error;
+		return {
+			...before,
+			last: {
+				from: before.state,
+				event: step.kind === "event" ? step.event : step.kind,
+				to: before.state,
+				outcome: "stay",
+				effects: [],
+				context: before.context,
+				error: error instanceof Error ? error.message : String(error)
+			}
+		};
+	}
+}
 function headerOf(doc, context) {
 	const { machine, view, render } = context;
 	return html(doc, "header", { class: "viz-header" }, [
 		html(doc, context.heading, {}, [`Viz: ${machine.id}`]),
-		machineSelect(doc, context.viz, {
+		context.live ? null : machineSelect(doc, context.viz, {
 			view,
 			onChange: (id) => {
 				view.machineId = id;
@@ -1051,6 +1288,21 @@ function markSelection(root, selection) {
 	const attribute = selection?.kind === "edge" ? "edgeId" : "nodeId";
 	for (const element of root.querySelectorAll(".graph g")) element.classList.toggle("selected", selection !== null && element.dataset[attribute] === selection.id);
 }
+function liveState(view) {
+	return view.live === null ? {} : { live: view.live.state };
+}
+/** Back is reset plus replay: the driver keeps no history. Stops at the first step the driver throws on. */
+function replay(driver, steps) {
+	let live = driver.reset();
+	for (const step of steps) {
+		live = stepSafely(driver, {
+			before: live,
+			step
+		});
+		if (live.last?.error) return live;
+	}
+	return live;
+}
 // src/viewer/embed.ts
 /**
 * Browser entry for embedding the viewer in another page (e.g. the docs site).

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as VizState, D as scopeOf, E as isAnyState, S as VizMachine, T as coveredByAny, _ as VizFuzz, a as VIZ_SCHEMA_VERSION, b as VizJson, c as VizComparison, d as VizEdge, f as VizEdgeKind, g as VizExplanation, h as VizEvent, i as ANY_STATE, l as VizCoverage, m as VizEffect, n as validateViz, o as VizBranch, p as VizEdgeOrigin, r as VizIssue, s as VizBranchTarget, t as parseViz, u as VizDocument, v as VizFuzzError, w as VizStep, x as VizLocation, y as VizFuzzSequence } from "./validate-3D5LrtlE.mjs";
+import { A as coveredByAny, C as VizLiveState, D as VizMachine, E as VizLocation, M as scopeOf, O as VizState, S as VizLiveOutcome, T as VizLiveTimer, _ as VizExplanation, a as VIZ_SCHEMA_VERSION, b as VizFuzzSequence, c as VizComparison, d as VizDriver, f as VizEdge, g as VizEvent, h as VizEffect, i as ANY_STATE, j as isAnyState, k as VizStep, l as VizCoverage, m as VizEdgeOrigin, n as validateViz, o as VizBranch, p as VizEdgeKind, r as VizIssue, s as VizBranchTarget, t as parseViz, u as VizDocument, v as VizFuzz, w as VizLiveStep, x as VizJson, y as VizFuzzError } from "./validate-C_EXBtem.mjs";
 /** Byte-stable JSON: sorted object keys, two-space indent, trailing newline. */
 export declare function serializeViz(document: VizDocument): string;
 /**
@@ -79,4 +79,4 @@ export declare function livePageHtml(parts: {
   /** Stylesheet text, inlined: the built entry carries no CSS of its own. */
   css: string;
 }): string;
-export { ANY_STATE, type ExploreStep, type Move, type MoveGroup, type RoutingWarning, VIZ_SCHEMA_VERSION, VizBranch, VizBranchTarget, VizComparison, VizCoverage, VizDocument, VizEdge, VizEdgeKind, VizEdgeOrigin, VizEffect, VizEvent, VizExplanation, VizFuzz, VizFuzzError, VizFuzzSequence, type VizIssue, VizJson, VizLocation, VizMachine, VizState, VizStep, coveredByAny, isAnyState, parseViz, scopeOf, validateViz };
+export { ANY_STATE, type ExploreStep, type Move, type MoveGroup, type RoutingWarning, VIZ_SCHEMA_VERSION, VizBranch, VizBranchTarget, VizComparison, VizCoverage, VizDocument, VizDriver, VizEdge, VizEdgeKind, VizEdgeOrigin, VizEffect, VizEvent, VizExplanation, VizFuzz, VizFuzzError, VizFuzzSequence, type VizIssue, VizJson, VizLiveOutcome, VizLiveState, VizLiveStep, VizLiveTimer, VizLocation, VizMachine, VizState, VizStep, coveredByAny, isAnyState, parseViz, scopeOf, validateViz };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as stateAfter, c as validateViz, d as coveredByAny, f as isAnyState, i as movesFrom, l as ANY_STATE, n as decodePath, o as unhandledSends, p as scopeOf, r as encodeStep, s as parseViz, t as routingWarnings, u as VIZ_SCHEMA_VERSION } from "./routing-BNJN5Oiu.mjs";
+import { a as encodeStep, c as stateAfter, d as validateViz, f as ANY_STATE, g as scopeOf, h as isAnyState, l as unhandledSends, m as coveredByAny, o as movesFrom, p as VIZ_SCHEMA_VERSION, r as decodePath, t as routingWarnings, u as parseViz } from "./routing-xXYo05xv.mjs";
 import { i as standaloneHtml, n as UPDATE_EVENT, r as livePageHtml, t as DOCUMENT_ELEMENT_ID } from "./html-BfvuzJs6.mjs";
 // src/serialize.ts
 function sortKeys(value) {

package/dist/page.d.mts

@@ -1,4 +1,4 @@
-import { a as ViewerOptions } from "./embed-BRQxeM4W.mjs";
+import { a as ViewerOptions } from "./embed-CISoaFIK.mjs";
 /** Options that open the walk named in the address bar and keep it there. */
 export declare function linkOptions(): ViewerOptions;
 /** Mount the document embedded in the page itself. */

package/dist/page.mjs

@@ -1,5 +1,5 @@
 import "./html-BfvuzJs6.mjs";
-import { n as showIssues, t as mountVizText } from "./embed-BtlbyzmZ.mjs";
+import { n as showIssues, t as mountVizText } from "./embed-QX7vRXoL.mjs";
 // src/viewer/page.ts
 /**
 * Whole-page entries: a self-contained HTML file (`mountEmbedded`) and a live

package/dist/{routing-BNJN5Oiu.mjs → routing-xXYo05xv.mjs}

@@ -4,7 +4,7 @@ import { Either } from "@mantaq/utils";
 * Viz document schema. Bump `VIZ_SCHEMA_VERSION` on any breaking change.
 * Everything not observable at runtime is `null`, never guessed.
 */
-const VIZ_SCHEMA_VERSION = 7;
+const VIZ_SCHEMA_VERSION = 8;
 /**
 * Edge source of an `onAny` registration: any non-final state of the machine,
 * or `region.*` inside a region. Never listed in `states`.
@@ -485,6 +485,11 @@ function readState(reader, record, path) {
 			record,
 			key: "tested",
 			path
+		}),
+		doc: readNullableString(reader, {
+			record,
+			key: "doc",
+			path
 		})
 	};
 }
@@ -504,6 +509,11 @@ function readEvent(reader, record, path) {
 			key: "internal",
 			path
 		}),
+		doc: readNullableString(reader, {
+			record,
+			key: "doc",
+			path
+		}),
 		payloadType: null
 	};
 }
@@ -553,6 +563,11 @@ function readEdge(reader, record, path) {
 			record,
 			path
 		}),
+		doc: readNullableString(reader, {
+			record,
+			key: "doc",
+			path
+		}),
 		coverage: readCoverage(reader, {
 			record,
 			key: "coverage",
@@ -635,9 +650,9 @@ function validateViz(value) {
 		path: "$",
 		message: "expected object"
 	}]);
-	if (value["schemaVersion"] !== 7) return Either.left([{
+	if (value["schemaVersion"] !== 8) return Either.left([{
 		path: "$.schemaVersion",
-		message: `expected 7, got ${JSON.stringify(value["schemaVersion"])}`
+		message: `expected 8, got ${JSON.stringify(value["schemaVersion"])}`
 	}]);
 	const machines = readList(reader, {
 		record: value,
@@ -646,7 +661,7 @@ function validateViz(value) {
 	}, (item, at) => readMachine(reader, item, at));
 	if (reader.issues.length > 0) return Either.left(reader.issues);
 	const document = {
-		schemaVersion: 7,
+		schemaVersion: 8,
 		machines
 	};
 	return Either.right(document);
@@ -743,6 +758,65 @@ function decodePath(machine, encoded) {
 	}
 	return path;
 }
+/**
+* A live step as text for a URL: `@800` advances the clock 800 ms, `go` sends
+* `go` with no payload, `pay={"amount":5}` sends `pay` with a JSON payload.
+*/
+function encodeLiveStep(step) {
+	if (step.kind === "advance") return `@${step.ms}`;
+	return step.payload === null ? step.event : `${step.event}=${JSON.stringify(step.payload)}`;
+}
+function parseJson(text) {
+	try {
+		return { value: JSON.parse(text) };
+	} catch {
+		return null;
+	}
+}
+/** Inverse of `encodeLiveStep`; null when the text is not a step. */
+function decodeLiveStep(text) {
+	if (text.startsWith("@")) {
+		const ms = Number(text.slice(1));
+		return text.length > 1 && Number.isFinite(ms) && ms >= 0 ? {
+			kind: "advance",
+			ms
+		} : null;
+	}
+	const cut = text.indexOf("=");
+	const event = cut === -1 ? text : text.slice(0, cut);
+	if (event === "") return null;
+	if (cut === -1) return {
+		kind: "event",
+		event,
+		payload: null
+	};
+	const payload = parseJson(text.slice(cut + 1));
+	return payload === null ? null : {
+		kind: "event",
+		event,
+		payload: payload.value
+	};
+}
+/** Steps from a shared link, up to the first one that does not parse. */
+function decodeLiveSteps(encoded) {
+	const steps = [];
+	for (const text of encoded) {
+		const step = decodeLiveStep(text);
+		if (step === null) break;
+		steps.push(step);
+	}
+	return steps;
+}
+/** Distinct payloads the fuzzer sent with `event`, in first-seen order. */
+function payloadSamples(machine, event) {
+	const steps = [...machine.fuzz?.corpus.flatMap((sequence) => sequence.steps) ?? [], ...machine.fuzz?.errors.flatMap((error) => error.steps) ?? []];
+	const seen = /* @__PURE__ */ new Map();
+	for (const step of steps) {
+		if (step.kind !== "event" || step.event !== event || step.payload === null) continue;
+		seen.set(JSON.stringify(step.payload), step.payload);
+	}
+	return [...seen.values()];
+}
 // src/routing.ts
 /**
 * `onAny` handlers that pick their target from the current state. Drawn from
@@ -756,4 +830,4 @@ function routingWarnings(machine) {
 		message: `onAny(${event}) reads actor state to pick its target, so the diagram cannot tell which state leads where. Register m.on per state instead.`
 	}));
 }
-export { stateAfter as a, validateViz as c, coveredByAny as d, isAnyState as f, movesFrom as i, ANY_STATE as l, decodePath as n, unhandledSends as o, scopeOf as p, encodeStep as r, parseViz as s, routingWarnings as t, VIZ_SCHEMA_VERSION as u };
+export { encodeStep as a, stateAfter as c, validateViz as d, ANY_STATE as f, scopeOf as g, isAnyState as h, encodeLiveStep as i, unhandledSends as l, coveredByAny as m, decodeLiveSteps as n, movesFrom as o, VIZ_SCHEMA_VERSION as p, decodePath as r, payloadSamples as s, routingWarnings as t, parseViz as u };

package/dist/{validate-3D5LrtlE.d.mts → validate-C_EXBtem.d.mts}

@@ -3,7 +3,7 @@ import { Either } from "@mantaq/utils";
  * Viz document schema. Bump `VIZ_SCHEMA_VERSION` on any breaking change.
  * Everything not observable at runtime is `null`, never guessed.
  */
-declare const VIZ_SCHEMA_VERSION = 7;
+declare const VIZ_SCHEMA_VERSION = 8;
 /**
  * Edge source of an `onAny` registration: any non-final state of the machine,
  * or `region.*` inside a region. Never listed in `states`.
@@ -37,10 +37,14 @@ interface VizState {
   coverage: VizCoverage | null;
   /** Visits by the supplied test sequences. null = no tests supplied. */
   tested: VizCoverage | null;
+  /** Leading JSDoc of the `state(...)` declaration. null = undocumented or AST not run. */
+  doc: string | null;
 }
 interface VizEvent {
   id: string;
   internal: boolean;
+  /** Leading JSDoc of the `event(...)` declaration. null = undocumented or AST not run. */
+  doc: string | null;
   /** Payload types are erased at runtime; always null. */
   payloadType: null;
 }
@@ -123,6 +127,8 @@ interface VizEdge {
   contexts: string[];
   /** null = no handler behind this edge (initial, effect) or analysis not run. */
   explanation: VizExplanation | null;
+  /** Leading JSDoc of the `m.on` / `m.onAny` call. null = undocumented, no handler, or AST not run. */
+  doc: string | null;
   /** Times taken in the supplied run (history or fuzz corpus replay). null = no run. */
   coverage: VizCoverage | null;
   /** Times taken by the supplied test sequences. null = no tests supplied. */
@@ -151,6 +157,41 @@ type VizStep = {
   kind: "advance";
   ms: number;
 };
+/** What one step did: the actor moved, handled it without moving, or had no handler. */
+type VizLiveOutcome = "transition" | "stay" | "ignored";
+interface VizLiveStep {
+  from: string;
+  event: string;
+  to: string;
+  outcome: VizLiveOutcome;
+  /** Names of the effects the step ran. */
+  effects: string[];
+  context: VizJson;
+  /** Message of a handler that threw; null when none did. */
+  error: string | null;
+}
+interface VizLiveTimer {
+  id: string;
+  ms: number;
+  deadline: number;
+  eventName: string | null;
+}
+/** Where a running actor is, after the steps in `steps`. */
+interface VizLiveState {
+  state: string;
+  steps: VizStep[];
+  last: VizLiveStep | null;
+  timers: VizLiveTimer[];
+  context: VizJson;
+}
+/**
+ * A running actor behind the viewer. JSON in, JSON out, so viz needs no core:
+ * `@mantaq/inspect` implements it on the step function the fuzzer uses.
+ */
+interface VizDriver {
+  reset(): VizLiveState;
+  step(step: VizStep): VizLiveState;
+}
 interface VizFuzzSequence {
   /** Shrunk replayable sequence, starting from a fresh actor. */
   steps: VizStep[];
@@ -186,4 +227,4 @@ interface VizIssue {
 declare function validateViz(value: unknown): Either<VizIssue[], VizDocument>;
 /** Parse JSON text and validate it. JSON syntax errors become an issue at `$`. */
 declare function parseViz(text: string): Either<VizIssue[], VizDocument>;
-export { VizState as C, scopeOf as D, isAnyState as E, VizMachine as S, coveredByAny as T, VizFuzz as _, VIZ_SCHEMA_VERSION as a, VizJson as b, VizComparison as c, VizEdge as d, VizEdgeKind as f, VizExplanation as g, VizEvent as h, ANY_STATE as i, VizCoverage as l, VizEffect as m, validateViz as n, VizBranch as o, VizEdgeOrigin as p, VizIssue as r, VizBranchTarget as s, parseViz as t, VizDocument as u, VizFuzzError as v, VizStep as w, VizLocation as x, VizFuzzSequence as y };
+export { coveredByAny as A, VizLiveState as C, VizMachine as D, VizLocation as E, scopeOf as M, VizState as O, VizLiveOutcome as S, VizLiveTimer as T, VizExplanation as _, VIZ_SCHEMA_VERSION as a, VizFuzzSequence as b, VizComparison as c, VizDriver as d, VizEdge as f, VizEvent as g, VizEffect as h, ANY_STATE as i, isAnyState as j, VizStep as k, VizCoverage as l, VizEdgeOrigin as m, validateViz as n, VizBranch as o, VizEdgeKind as p, VizIssue as r, VizBranchTarget as s, parseViz as t, VizDocument as u, VizFuzz as v, VizLiveStep as w, VizJson as x, VizFuzzError as y };

package/dist/viewer.d.mts

@@ -1,2 +1,2 @@
-import { a as ViewerOptions, i as STRUCTURE_BANNER, n as showIssues, o as mountViewer, r as FUZZ_NOTE, t as mountVizText } from "./embed-BRQxeM4W.mjs";
+import { a as ViewerOptions, i as STRUCTURE_BANNER, n as showIssues, o as mountViewer, r as FUZZ_NOTE, t as mountVizText } from "./embed-CISoaFIK.mjs";
 export { FUZZ_NOTE, STRUCTURE_BANNER, type ViewerOptions, mountViewer, mountVizText, showIssues };

package/dist/viewer.mjs

@@ -1 +1 @@
-export { r as FUZZ_NOTE, i as STRUCTURE_BANNER, a as mountViewer, t as mountVizText, n as showIssues } from "./embed-BtlbyzmZ.mjs";
+export { r as FUZZ_NOTE, i as STRUCTURE_BANNER, a as mountViewer, t as mountVizText, n as showIssues } from "./embed-QX7vRXoL.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/viz",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Draw and walk a Mantaq machine in the browser, from a versioned, deterministic JSON document.",
   "license": "MIT",
   "repository": {