@mantaq/viz 0.2.1 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Draws a Mantaq machine in the browser and lets you walk it. Input is a viz docum
 
 - `@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).
+- `@mantaq/viz/standalone`, `@mantaq/viz/live`: whole-page entries used by 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.
 
@@ -18,7 +18,7 @@ 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.
 
-**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`.
+**Static walk** (standalone page): 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.
 
@@ -35,7 +35,7 @@ Take a step with a panel button, by clicking a pulsing edge, or by clicking a st
 | `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                                                                                                                                                                                                                       |
+| `edge.doc`         | leading JSDoc of the `m.on` / `m.onAny` call behind the edge, or of the `m.effect` calls of the state for an `effect` edge (joined in order); `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.
@@ -44,5 +44,6 @@ Bump `VIZ_SCHEMA_VERSION` on any breaking change. The validator accepts only the
 
 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 })`).
+- **examples + fuzz** (`reached`): neither an example nor fuzzing reached this. The default when both sources are present, and the same merge `expectReached` uses. Fix a miss by adding an example to `tests`.
+- **example tests** (`tested`): no test exercises this. It is the classic "what is untested" view. 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-QX7vRXoL.mjs → embed-Dpjn47Qx.mjs}

@@ -45,42 +45,42 @@ function items(machine) {
 /** Modes this machine has data for, best first: tests answer "what is untested?". */
 function availableModes(machine) {
 	const modes = [];
-	if (items(machine).some((item) => item.tested !== null)) modes.push("tests");
-	if (items(machine).some((item) => item.coverage !== null)) modes.push("run");
+	const tested = items(machine).some((item) => item.tested !== null);
+	const run = items(machine).some((item) => item.coverage !== null);
+	if (tested && run) modes.push("reached");
+	if (tested) modes.push("tests");
+	if (run) modes.push("run");
 	return modes;
 }
 function measure(mode, item) {
 	if (mode === "run") return item.coverage;
 	if (mode === "tests") return item.tested;
+	if (mode === "reached") {
+		if (item.coverage === null && item.tested === null) return null;
+		return { hits: (item.coverage?.hits ?? 0) + (item.tested?.hits ?? 0) };
+	}
 	return null;
 }
 function modeLabel(mode, machine) {
 	if (mode === "tests") return "example tests";
+	if (mode === "reached") return "examples + fuzz";
 	if (mode === "run") return machine.fuzz === null ? "supplied run" : "fuzz runs";
 	return "off";
 }
-/** Legend text for a dimmed element: what "unreached" means for this source. */
-function unreachedText(mode, machine) {
-	if (mode === "tests") return "dimmed and dashed: no test exercises this";
-	if (machine.fuzz === null) return "dimmed and dashed: never taken in the supplied run";
-	return "dimmed and dashed: never observed while fuzzing (declared edges here may be unreachable)";
-}
 // src/viewer/labels.ts
-/** Names of the effects the state behind an effect edge runs on entry. */
-function effectNames(edge, machine) {
-	return (machine.states.find((state) => state.id === edge.from)?.effects ?? []).map((effect) => effect.name);
-}
-/** Text drawn on an edge: the event, or for an effect loop the effects it runs. */
-function edgeText(edge, machine) {
-	if (edge.kind !== "effect") return edge.event;
-	const names = effectNames(edge, machine);
-	return names.length === 0 ? "effect" : `runs ${names.join(", ")}`;
+/** Text drawn on an edge: the event it carries. */
+function edgeText(edge) {
+	return edge.event;
 }
 // src/viewer/layout.ts
 const CHAR_WIDTH = 7;
 const NODE_HEIGHT = 36;
+const CHIP_ROW_HEIGHT = 20;
 const LABEL_HEIGHT = 16;
 const UNKNOWN_SIZE = 28;
+const MIN_DOT_GAP = 3;
+const MAX_DOT_GAP = 12;
+const DOT_GAP_PER_LENGTH = 1 / 24;
 function anyIds(machine) {
 	return [...new Set(machine.edges.map((edge) => edge.from).filter(isAnyState))].sort();
 }
@@ -90,8 +90,13 @@ function unknownNodeId(edge) {
 function regionNodeId(region) {
 	return `region:${region}`;
 }
+const HINT_WIDTH = 14;
 function stateWidth(state) {
-	return Math.max(80, state.label.length * CHAR_WIDTH + 24);
+	const chips = state.effects.map((effect) => effect.name.length * CHAR_WIDTH + 24 + (effect.sends === null ? HINT_WIDTH : 0));
+	return Math.max(80, state.label.length * CHAR_WIDTH + 24, ...chips);
+}
+function stateHeight(state) {
+	return NODE_HEIGHT + state.effects.length * CHIP_ROW_HEIGHT;
 }
 function parentRegion(region) {
 	const cut = region.lastIndexOf(".");
@@ -111,7 +116,7 @@ function addStates(graph, machine) {
 	for (const state of machine.states) {
 		graph.setNode(state.id, {
 			width: stateWidth(state),
-			height: NODE_HEIGHT
+			height: stateHeight(state)
 		});
 		if (state.region !== null) graph.setParent(state.id, regionNodeId(state.region));
 	}
@@ -128,7 +133,7 @@ function addAnyNodes(graph, machine) {
 }
 function addEdges(graph, machine) {
 	for (const edge of machine.edges) {
-		if (edge.kind === "initial" || edge.to === edge.from) continue;
+		if (edge.kind === "initial" || edge.kind === "effect" || edge.to === edge.from) continue;
 		const target = edge.to ?? unknownNodeId(edge);
 		if (edge.to === null) {
 			graph.setNode(target, {
@@ -139,7 +144,7 @@ function addEdges(graph, machine) {
 			if (region !== null) graph.setParent(target, regionNodeId(region));
 		}
 		const label = {
-			width: edgeText(edge, machine).length * CHAR_WIDTH + 8,
+			width: edgeText(edge).length * CHAR_WIDTH + 8,
 			height: LABEL_HEIGHT,
 			labelpos: "c"
 		};
@@ -161,7 +166,7 @@ function placeNodes(graph, machine) {
 		state,
 		...box(graph.node(state.id))
 	}));
-	const unknowns = machine.edges.filter((edge) => edge.kind !== "initial" && edge.to === null).map((edge) => ({
+	const unknowns = machine.edges.filter((edge) => edge.kind !== "initial" && edge.kind !== "effect" && edge.to === null).map((edge) => ({
 		kind: "unknown",
 		id: unknownNodeId(edge),
 		edgeId: edge.id,
@@ -198,15 +203,66 @@ function selfLoop(node, nth) {
 		}
 	};
 }
+function pathLength(points) {
+	let total = 0;
+	for (let index = 1; index < points.length; index++) {
+		const from = points[index - 1];
+		const to = points[index];
+		if (from === void 0 || to === void 0) continue;
+		total += Math.hypot(to.x - from.x, to.y - from.y);
+	}
+	return total;
+}
+function dotGapFor(length) {
+	return Math.min(MAX_DOT_GAP, Math.max(MIN_DOT_GAP, length * DOT_GAP_PER_LENGTH));
+}
+const LABEL_GAP = 2;
+function collides(a, b) {
+	return Math.abs(a.x - b.x) < (a.width + b.width) / 2 + LABEL_GAP && Math.abs(a.y - b.y) < (a.height + b.height) / 2 + LABEL_GAP;
+}
+/**
+* Moves each label vertically (0, +1, -1, +2, -2 steps) to the first spot that
+* clears every label placed before it. Pure and order-stable.
+*/
+function separateLabels(boxes) {
+	const placed = [];
+	for (const labelBox of boxes) {
+		let candidate = labelBox;
+		for (let step = 1; placed.some((other) => collides(candidate, other)); step++) {
+			const shift = 18 * Math.ceil(step / 2);
+			candidate = {
+				...labelBox,
+				y: labelBox.y + (step % 2 === 1 ? shift : -shift)
+			};
+		}
+		placed.push(candidate);
+	}
+	return placed;
+}
+function avoidLabelCollisions(edges) {
+	const moved = separateLabels(edges.map((placed) => ({
+		...placed.label,
+		width: edgeText(placed.edge).length * CHAR_WIDTH + 8,
+		height: LABEL_HEIGHT
+	})));
+	return edges.map((placed, index) => ({
+		...placed,
+		label: {
+			x: placed.label.x,
+			y: moved[index]?.y ?? placed.label.y
+		}
+	}));
+}
 function placeEdges(graph, machine) {
 	const loopsSeen = /* @__PURE__ */ new Map();
-	return machine.edges.filter((edge) => edge.kind !== "initial").map((edge) => {
+	return machine.edges.filter((edge) => edge.kind !== "initial" && edge.kind !== "effect").map((edge) => {
 		if (edge.to === edge.from) {
 			const nth = loopsSeen.get(edge.from) ?? 0;
 			loopsSeen.set(edge.from, nth + 1);
 			return {
 				edge,
 				target: edge.from,
+				dotGap: dotGapFor(72),
 				...selfLoop(graph.node(edge.from), nth)
 			};
 		}
@@ -219,7 +275,8 @@ function placeEdges(graph, machine) {
 			label: {
 				x: label.x ?? 0,
 				y: label.y ?? 0
-			}
+			},
+			dotGap: dotGapFor(pathLength(label.points ?? []))
 		};
 	});
 }
@@ -249,8 +306,8 @@ function layoutMachine(machine) {
 	});
 	graph.setGraph({
 		rankdir: "LR",
-		nodesep: 28,
-		ranksep: 64,
+		nodesep: 36,
+		ranksep: 72,
 		edgesep: 14,
 		marginx: 48,
 		marginy: 64
@@ -265,7 +322,7 @@ function layoutMachine(machine) {
 		width: size.width ?? 0,
 		height: size.height ?? 0,
 		nodes: placeNodes(graph, machine),
-		edges: placeEdges(graph, machine),
+		edges: avoidLabelCollisions(placeEdges(graph, machine)),
 		regions: machine.regions.map((region) => ({
 			region,
 			...box(graph.node(regionNodeId(region)))
@@ -312,6 +369,39 @@ function regionGroup(doc, placed) {
 		y: placed.y - placed.height / 2 + 14
 	}, [placed.region])]);
 }
+function chipGroups(doc, placed) {
+	const top = placed.y - placed.height / 2;
+	const width = placed.width - 16;
+	return placed.state.effects.map((effect, index) => {
+		const y = top + 36 + index * 20 - 8;
+		return svg(doc, "g", {
+			class: "chip",
+			"data-effect": effect.name,
+			"data-state": placed.state.id,
+			tabindex: 0,
+			"aria-label": effect.sends === null ? `effect ${effect.name} (declare sends to see links)` : `effect ${effect.name}`
+		}, [
+			svg(doc, "rect", {
+				x: placed.x - width / 2,
+				y,
+				width,
+				height: 16,
+				rx: 8
+			}),
+			svg(doc, "text", {
+				x: placed.x,
+				y: y + 12,
+				"text-anchor": "middle"
+			}, [effect.name]),
+			effect.sends === null ? svg(doc, "text", {
+				class: "hint",
+				x: placed.x + width / 2 - 8,
+				y: y + 12,
+				"text-anchor": "middle"
+			}, ["?", svg(doc, "title", {}, ["declare `sends` to see links"])]) : null
+		]);
+	});
+}
 function stateGroup(doc, placed, callbacks) {
 	const { state } = placed;
 	const left = placed.x - placed.width / 2;
@@ -347,9 +437,10 @@ function stateGroup(doc, placed, callbacks) {
 		}) : null,
 		svg(doc, "text", {
 			x: placed.x,
-			y: placed.y + 4,
+			y: top + 22,
 			"text-anchor": "middle"
-		}, [state.label])
+		}, [state.label]),
+		...chipGroups(doc, placed)
 	]);
 	activatable(group, () => callbacks.select({
 		kind: "state",
@@ -394,18 +485,16 @@ function nodeGroup(doc, node, callbacks) {
 	return node.kind === "any" ? anyGroup(doc, node) : unknownGroup(doc, node);
 }
 function edgeAria(edge, text) {
-	if (edge.kind === "effect") return `${edge.from} ${text} on entry`;
 	if (edge.kind === "stay") return `${sourceText$1(edge.from)} on ${text} stays`;
 	return `${sourceText$1(edge.from)} on ${text} to ${edge.to ?? "undetermined"}`;
 }
 function edgeGroup(doc, placed, context) {
 	const { edge } = placed;
 	const internal = context.machine.events.find((event) => event.id === edge.event)?.internal;
-	const text = edgeText(edge, context.machine);
+	const text = edgeText(edge);
 	const group = svg(doc, "g", {
 		class: classes({
 			edge: true,
-			effect: edge.kind === "effect",
 			stay: edge.kind === "stay",
 			fuzz: edge.origin === "fuzz",
 			undetermined: edge.to === null,
@@ -418,7 +507,8 @@ function edgeGroup(doc, placed, context) {
 		"aria-label": edgeAria(edge, text)
 	}, [svg(doc, "path", {
 		d: placed.path,
-		"marker-end": "url(#viz-arrow)"
+		"marker-end": "url(#viz-arrow)",
+		style: internal === true || edge.kind === "stay" ? `--viz-dot-gap: ${placed.dotGap.toFixed(1)}` : null
 	}), svg(doc, "text", {
 		x: placed.label.x,
 		y: placed.label.y + 4,
@@ -456,6 +546,35 @@ function wireHover(root) {
 		});
 	}
 }
+/** Edges a chip's effect sends, including `onAny` handlers, by edge id. */
+function sentEdges(root, machine, chip) {
+	const effect = chip.dataset["effect"] ?? "";
+	const ids = new Set(movesFrom(machine, chip.dataset["state"] ?? "").filter((move) => move.sentBy.includes(effect)).map((move) => move.edge.id));
+	return [...root.querySelectorAll(".edge")].filter((edge) => ids.has(edge.dataset["edgeId"] ?? ""));
+}
+/** Hovering or focusing a chip highlights the edges for its `sends` and dims the rest. */
+function wireChips(root, doc, machine) {
+	const emitters = /* @__PURE__ */ new Map();
+	for (const chip of root.querySelectorAll(".chip")) {
+		const edges = sentEdges(root, machine, chip);
+		const effect = chip.dataset["effect"] ?? "";
+		for (const edge of edges) emitters.set(edge, [...emitters.get(edge) ?? [], effect]);
+		const on = () => {
+			if (edges.length === 0) return;
+			root.classList.add("chip-active");
+			for (const edge of edges) edge.classList.add("sent");
+		};
+		const off = () => {
+			root.classList.remove("chip-active");
+			for (const edge of edges) edge.classList.remove("sent");
+		};
+		chip.addEventListener("mouseenter", on);
+		chip.addEventListener("mouseleave", off);
+		chip.addEventListener("focusin", on);
+		chip.addEventListener("focusout", off);
+	}
+	for (const [edge, names] of emitters) edge.prepend(svg(doc, "title", {}, [`emitted by ${names.join(", ")}`]));
+}
 /** Static SVG for one machine. Regions first, then edges, then nodes, so nodes sit on top. */
 function renderGraph(doc, machine, callbacks) {
 	const placed = layoutMachine(machine);
@@ -478,6 +597,7 @@ function renderGraph(doc, machine, callbacks) {
 		...placed.nodes.map((node) => nodeGroup(doc, node, callbacks))
 	]);
 	wireHover(root);
+	wireChips(root, doc, machine);
 	return root;
 }
 // src/viewer/explanation.ts
@@ -703,6 +823,59 @@ function renderPanel(doc, machine, context) {
 	}
 	return html(doc, "div", {}, [html(doc, "p", { class: "hint" }, ["Select a state or edge."]), fuzzSummary(doc, machine)]);
 }
+// src/viewer/context-diff.ts
+function same(left, right) {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+function childOf(value, key) {
+	if (value === null || typeof value !== "object") return void 0;
+	if (Array.isArray(value)) return /^\d+$/.test(key) ? value[Number(key)] : void 0;
+	return Object.hasOwn(value, key) ? value[key] : void 0;
+}
+function lines(value, context) {
+	const { before, depth, label, comma } = context;
+	const pad = "  ".repeat(depth);
+	const entries = Array.isArray(value) ? value.map((item, index) => [String(index), item]) : value !== null && typeof value === "object" ? Object.entries(value) : [];
+	if (entries.length === 0) return [{
+		text: `${pad}${label}${JSON.stringify(value) ?? "undefined"}${comma}`,
+		changed: !same(value, before)
+	}];
+	const [open, close] = Array.isArray(value) ? ["[", "]"] : ["{", "}"];
+	const body = entries.flatMap(([key, item], index) => lines(item, {
+		before: childOf(before, key),
+		depth: depth + 1,
+		label: Array.isArray(value) ? "" : `${JSON.stringify(key)}: `,
+		comma: index === entries.length - 1 ? "" : ","
+	}));
+	return [
+		{
+			text: `${pad}${label}${open}`,
+			changed: false
+		},
+		...body,
+		{
+			text: `${pad}${close}${comma}`,
+			changed: false
+		}
+	];
+}
+/**
+* The context pretty-printed like `JSON.stringify(value, null, 2)`, one entry per
+* line, with the lines whose value is new or different from `before` marked.
+* `before` of undefined marks nothing.
+*/
+function contextLines(value, before) {
+	const marked = lines(value, {
+		before,
+		depth: 0,
+		label: "",
+		comma: ""
+	});
+	return before === void 0 ? marked.map((line) => ({
+		...line,
+		changed: false
+	})) : marked;
+}
 // src/viewer/explore.ts
 const GROUP_TITLES = {
 	input: "Send an input",
@@ -765,8 +938,13 @@ function effectsSection(doc, machine, current) {
 	if (effects.length === 0) return null;
 	const unhandled = unhandledSends(machine, current);
 	const isUnhandled = (effect, event) => unhandled.some((each) => each.effect === effect && each.event === event);
+	const effectDoc = machine.edges.find((edge) => edge.kind === "effect" && edge.from === current)?.doc;
 	return html(doc, "div", { class: "explore-effects" }, [
 		html(doc, "p", {}, [`Entering ${current} runs:`]),
+		docNote(doc, {
+			text: effectDoc ?? null,
+			scope: "edge"
+		}),
 		html(doc, "ul", {}, effects.map((effect) => {
 			const sends = effect.sends ?? [];
 			const summary = effect.sends === null ? html(doc, "span", { class: "muted" }, [" (sends not declared)"]) : sends.length === 0 ? " sends nothing" : " sends ";
@@ -943,8 +1121,26 @@ function outcomeText(last) {
 	if (last.outcome === "stay") return ` handled in ${last.from}: stays`;
 	return ` ignored in ${last.from}: no handler`;
 }
-function liveResultSection(doc, state) {
-	const { last } = state;
+const collapsedContexts = /* @__PURE__ */ new WeakSet();
+/** Collapsible, pretty-printed context. The fold survives the panel redraw after each step. */
+function contextSection(doc, value, context) {
+	const { viewer, previous } = context;
+	const section = html(doc, "details", {
+		class: "explore-context",
+		"data-live-context": ""
+	}, [html(doc, "summary", {}, ["Context"]), html(doc, "pre", {}, contextLines(value, previous).flatMap((line, index) => [index === 0 ? "" : "\n", line.changed ? html(doc, "mark", {
+		class: "context-changed",
+		"data-context-changed": ""
+	}, [line.text]) : line.text]))]);
+	section.open = !collapsedContexts.has(viewer);
+	section.addEventListener("toggle", () => {
+		if (section.open) collapsedContexts.delete(viewer);
+		else collapsedContexts.add(viewer);
+	});
+	return section;
+}
+function liveResultSection(doc, live) {
+	const { last } = live.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
@@ -956,7 +1152,10 @@ function liveResultSection(doc, state) {
 			role: "alert",
 			"data-live-error": ""
 		}, [`Handler threw: ${last.error}`])
-	]), html(doc, "p", { "data-live-context": "" }, ["Context: ", code(doc, JSON.stringify(state.context))])]);
+	]), contextSection(doc, live.state.context, {
+		viewer: live.send,
+		previous: live.previous
+	})]);
 }
 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"], {
@@ -995,7 +1194,7 @@ function explorePanel(doc, context) {
 			final
 		}),
 		...live ? [
-			liveResultSection(doc, live.state),
+			liveResultSection(doc, live),
 			liveMovesSection(doc, machine, {
 				state: live.state,
 				send: live.send,
@@ -1049,8 +1248,8 @@ function markExplore(root, context) {
 		const id = element.dataset["edgeId"] ?? "";
 		element.classList.toggle("taken", taken.has(id));
 		element.classList.toggle("next", next.has(id));
-		element.classList.toggle("running", element.classList.contains("effect") && element.dataset["from"] === current);
 	}
+	for (const element of root.querySelectorAll(".graph g.chip")) element.classList.toggle("running", element.dataset["state"] === current);
 	for (const element of root.querySelectorAll(".graph g[data-node-id]")) {
 		const id = element.dataset["nodeId"];
 		element.classList.toggle("current", id === current);
@@ -1058,29 +1257,13 @@ 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.";
+const DOCS_URL = "https://anderscan.github.io/mantaq/guides/visualizer/";
 function effectiveMode(view, machine) {
 	const modes = availableModes(machine);
 	if (view.coverage === "off") return "off";
 	if (view.coverage !== null && modes.includes(view.coverage)) return view.coverage;
 	return modes[0] ?? "off";
 }
-function legend(doc, { mode, machine }) {
-	const entries = [
-		["legend-final", "double border: final state"],
-		["legend-undetermined", "dashed edge to ?: target undetermined"],
-		["legend-internal", "dotted edge, italic label: internal event"],
-		["legend-effect", "faint self-loop: state runs effects on entry"],
-		["legend-current", "thick accent border: where the walk is"],
-		["legend-next", "pulsing: a possible next step"],
-		["legend-taken", "bold accent: path taken"]
-	];
-	if (machine.fuzz !== null) entries.push(["legend-fuzz", "green: observed only while fuzzing"], ["legend-stay", "dotted self-loop: handled, no state change"]);
-	if (mode !== "off") entries.push(["legend-unreached", unreachedText(mode, machine)]);
-	return html(doc, "ul", { class: "legend" }, entries.map(([name, text]) => html(doc, "li", { class: name }, [text])));
-}
 function machineSelect(doc, viz, context) {
 	if (viz.machines.length < 2) return null;
 	const select = html(doc, "select", { class: "machine-select" }, viz.machines.map((machine) => html(doc, "option", {
@@ -1091,7 +1274,7 @@ function machineSelect(doc, viz, context) {
 	return html(doc, "label", {}, ["Machine ", select]);
 }
 function isMode(value) {
-	return value === "off" || value === "run" || value === "tests";
+	return value === "off" || value === "run" || value === "tests" || value === "reached";
 }
 function coveragePicker(doc, context) {
 	const modes = availableModes(context.machine);
@@ -1117,10 +1300,11 @@ function mountViewer(root, viz, options = {}) {
 		selection: null,
 		coverage: null,
 		path: first === void 0 || options.driver !== void 0 ? [] : decodePath(first, options.steps ?? []),
-		live: null
+		live: null,
+		previous: void 0
 	};
 	const { driver } = options;
-	if (driver !== void 0) view.live = replay(driver, decodeLiveSteps(options.steps ?? []));
+	if (driver !== void 0) replayInto(view, driver, decodeLiveSteps(options.steps ?? []));
 	let back = () => void 0;
 	root.addEventListener("keydown", (event) => {
 		if (!("key" in event) || event.target instanceof HTMLSelectElement) return;
@@ -1148,7 +1332,8 @@ function mountViewer(root, viz, options = {}) {
 				rewind,
 				...view.live === null ? {} : { live: {
 					state: view.live,
-					send
+					send,
+					previous: view.previous
 				} }
 			}), renderPanel(doc, machine, {
 				selection: view.selection,
@@ -1171,6 +1356,7 @@ function mountViewer(root, viz, options = {}) {
 		};
 		const send = (step) => {
 			if (driver === void 0) return;
+			view.previous = view.live?.context;
 			view.live = stepSafely(driver, {
 				before: view.live,
 				step
@@ -1192,7 +1378,7 @@ function mountViewer(root, viz, options = {}) {
 		};
 		const rewind = (length) => {
 			if (driver !== void 0 && view.live !== null) {
-				view.live = replay(driver, view.live.steps.slice(0, Math.max(0, length)));
+				replayInto(view, driver, view.live.steps.slice(0, Math.max(0, length)));
 				walked();
 				return;
 			}
@@ -1219,12 +1405,6 @@ function mountViewer(root, viz, options = {}) {
 			render,
 			onNavigate: options.onNavigate,
 			live: driver !== void 0
-		}), html(doc, "p", {
-			class: "banner",
-			role: "note"
-		}, [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, {
 			select,
 			mode
@@ -1234,6 +1414,11 @@ function mountViewer(root, viz, options = {}) {
 	render();
 }
 /** A driver that throws leaves the state where it was and shows the message as a handler error. */
+/** Sets `view.live` to the state after `steps` and `view.previous` to the context before the last of them. */
+function replayInto(view, driver, steps) {
+	view.previous = steps.length === 0 ? void 0 : replay(driver, steps.slice(0, -1)).context;
+	view.live = replay(driver, steps);
+}
 function stepSafely(driver, context) {
 	const { before, step } = context;
 	try {
@@ -1278,12 +1463,15 @@ function headerOf(doc, context) {
 				view.coverage = next;
 				render();
 			}
-		})
+		}),
+		html(doc, "a", {
+			class: "help-link",
+			href: DOCS_URL,
+			target: "_blank",
+			rel: "noopener noreferrer"
+		}, ["How this works"])
 	]);
 }
-function banner(machine) {
-	return machine.fuzz === null ? STRUCTURE_BANNER : `${STRUCTURE_BANNER} ${FUZZ_NOTE}`;
-}
 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);
@@ -1329,4 +1517,4 @@ function mountVizText(root, context, options = {}) {
 	}
 	mountViewer(root, result[1], options);
 }
-export { mountViewer as a, STRUCTURE_BANNER as i, showIssues as n, FUZZ_NOTE as r, mountVizText as t };
+export { showIssues as n, mountViewer as r, mountVizText as t };

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

@@ -1,6 +1,4 @@
 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 {
   /** Title element. Embedded viewers use `h2`/`h3` to fit the host page's outline. */
   heading?: "h1" | "h2" | "h3";
@@ -34,4 +32,4 @@ 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 };
+export { mountViewer as i, showIssues as n, ViewerOptions as r, mountVizText as t };

package/dist/page.d.mts

@@ -1,4 +1,4 @@
-import { a as ViewerOptions } from "./embed-CISoaFIK.mjs";
+import { r as ViewerOptions } from "./embed-OmMnILen.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-QX7vRXoL.mjs";
+import { n as showIssues, t as mountVizText } from "./embed-Dpjn47Qx.mjs";
 // src/viewer/page.ts
 /**
 * Whole-page entries: a self-contained HTML file (`mountEmbedded`) and a live

package/dist/standalone.mjs

@@ -1,6 +1,6 @@
 import { mountEmbedded } from "./page.mjs";
 // src/viewer/standalone.ts
-/** Entry of the self-contained HTML page `mantaq-inspect` writes. */
+/** Entry of the self-contained static page. */
 const root = document.querySelector("#app");
 if (root) mountEmbedded(root);
 export {};

package/dist/style.css

@@ -46,21 +46,10 @@
   font-size: 18px;
 }
 
-.viz .banner {
-  background: var(--banner-bg);
-  color: var(--banner-fg);
-  border-radius: 6px;
-  padding: 8px 12px;
-}
-
-.viz .legend {
+.viz .help-link {
   color: var(--muted);
-  flex-wrap: wrap;
-  gap: 4px 18px;
-  padding: 0;
+  margin-left: auto;
   font-size: 12px;
-  list-style: none;
-  display: flex;
 }
 
 .viz .viz-main {
@@ -158,7 +147,7 @@
 }
 
 .viz .edge.internal path {
-  stroke-dasharray: 1 3;
+  stroke-dasharray: 1 var(--viz-dot-gap, 3);
   stroke-linecap: round;
 }
 
@@ -166,8 +155,20 @@
   font-style: italic;
 }
 
-.viz .edge.effect {
-  opacity: .45;
+.viz .chip rect {
+  fill: var(--accent);
+  fill-opacity: .12;
+  stroke: var(--accent);
+}
+
+.viz .chip text {
+  font-size: 11px;
+}
+
+.viz .chip .hint {
+  fill: var(--unknown);
+  cursor: help;
+  font-weight: bold;
 }
 
 .viz .edge.undetermined path {
@@ -184,7 +185,7 @@
 }
 
 .viz .edge.stay path {
-  stroke-dasharray: 1 3;
+  stroke-dasharray: 1 var(--viz-dot-gap, 3);
   stroke-linecap: round;
 }
 
@@ -240,6 +241,19 @@
   stroke-width: 2.5px;
 }
 
+.viz .chip {
+  cursor: help;
+}
+
+.viz .graph.chip-active .edge:not(.sent) {
+  opacity: .2;
+}
+
+.viz .edge.sent path {
+  stroke: var(--accent);
+  stroke-width: 2.5px;
+}
+
 .viz .state:focus-visible .frame, .viz .edge:focus-visible path {
   stroke: var(--accent);
   stroke-width: 3px;
@@ -306,8 +320,8 @@
   font-weight: 700;
 }
 
-.viz .edge.effect.running {
-  opacity: 1;
+.viz .chip.running rect {
+  fill-opacity: .35;
 }
 
 .viz .running path {
@@ -393,6 +407,25 @@
   stroke: var(--accent);
   stroke-dasharray: 4 3;
 }
+
+.viz .explore-context summary {
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.viz .explore-context pre {
+  background: var(--region-bg);
+  max-height: 40vh;
+  margin: 4px 0 0;
+  font-size: 12px;
+  overflow: auto;
+}
+
+.viz .explore-context mark.context-changed {
+  background: var(--banner-bg);
+  color: var(--banner-fg);
+  font-weight: 600;
+}
 body {
   margin: 0;
   padding: 16px;

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-CISoaFIK.mjs";
-export { FUZZ_NOTE, STRUCTURE_BANNER, type ViewerOptions, mountViewer, mountVizText, showIssues };
+import { i as mountViewer, n as showIssues, r as ViewerOptions, t as mountVizText } from "./embed-OmMnILen.mjs";
+export { 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-QX7vRXoL.mjs";
+export { r as mountViewer, t as mountVizText, n as showIssues } from "./embed-Dpjn47Qx.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/viz",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Draw and walk a Mantaq machine in the browser, from a versioned, deterministic JSON document.",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@dagrejs/dagre": "^3.1.2",
-    "@mantaq/utils": "0.0.4"
+    "@mantaq/utils": "0.0.5"
   },
   "devDependencies": {
     "@typescript/native-preview": "7.0.0-dev.20260707.2",

package/src/viewer/viewer.css

@@ -46,19 +46,8 @@
   margin: 0;
 }
 
-.viz .banner {
-  background: var(--banner-bg);
-  color: var(--banner-fg);
-  padding: 8px 12px;
-  border-radius: 6px;
-}
-
-.viz .legend {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 4px 18px;
-  padding: 0;
-  list-style: none;
+.viz .help-link {
+  margin-left: auto;
   color: var(--muted);
   font-size: 12px;
 }
@@ -159,7 +148,7 @@
 }
 
 .viz .edge.internal path {
-  stroke-dasharray: 1 3;
+  stroke-dasharray: 1 var(--viz-dot-gap, 3);
   stroke-linecap: round;
 }
 
@@ -167,8 +156,20 @@
   font-style: italic;
 }
 
-.viz .edge.effect {
-  opacity: 0.45;
+.viz .chip rect {
+  fill: var(--accent);
+  fill-opacity: 0.12;
+  stroke: var(--accent);
+}
+
+.viz .chip text {
+  font-size: 11px;
+}
+
+.viz .chip .hint {
+  font-weight: bold;
+  fill: var(--unknown);
+  cursor: help;
 }
 
 .viz .edge.undetermined path {
@@ -185,7 +186,7 @@
 }
 
 .viz .edge.stay path {
-  stroke-dasharray: 1 3;
+  stroke-dasharray: 1 var(--viz-dot-gap, 3);
   stroke-linecap: round;
 }
 
@@ -246,6 +247,19 @@
   stroke-width: 2.5;
 }
 
+.viz .chip {
+  cursor: help;
+}
+
+.viz .graph.chip-active .edge:not(.sent) {
+  opacity: 0.2;
+}
+
+.viz .edge.sent path {
+  stroke: var(--accent);
+  stroke-width: 2.5;
+}
+
 .viz .state:focus-visible .frame,
 .viz .edge:focus-visible path {
   stroke: var(--accent);
@@ -316,8 +330,8 @@
   font-weight: 700;
 }
 
-.viz .edge.effect.running {
-  opacity: 1;
+.viz .chip.running rect {
+  fill-opacity: 0.35;
 }
 
 .viz .running path {
@@ -404,3 +418,22 @@
   stroke: var(--accent);
   stroke-dasharray: 4 3;
 }
+
+.viz .explore-context summary {
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.viz .explore-context pre {
+  margin: 4px 0 0;
+  overflow: auto;
+  max-height: 40vh;
+  font-size: 12px;
+  background: var(--region-bg);
+}
+
+.viz .explore-context mark.context-changed {
+  background: var(--banner-bg);
+  color: var(--banner-fg);
+  font-weight: 600;
+}