@mantaq/viz 0.0.0-stage → 0.1.0

package/dist/embed-BtlbyzmZ.mjs

@@ -0,0 +1,1080 @@
+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 { Either } from "@mantaq/utils";
+import { Graph, layout } from "@dagrejs/dagre";
+// src/viewer/dom.ts
+const SVG_NS = "http://www.w3.org/2000/svg";
+function append(parent, children) {
+	for (const child of children) {
+		if (child === null) continue;
+		parent.append(child);
+	}
+}
+function setAttributes(element, attrs) {
+	for (const [name, value] of Object.entries(attrs)) if (value !== null) element.setAttribute(name, String(value));
+}
+/** HTML element with attributes (null skips) and children. */
+function html(doc, tag, attrs = {}, children = []) {
+	const element = doc.createElement(tag);
+	setAttributes(element, attrs);
+	append(element, children);
+	return element;
+}
+/** SVG element with attributes (null skips) and children. */
+function svg(doc, tag, attrs = {}, children = []) {
+	const element = doc.createElementNS(SVG_NS, tag);
+	setAttributes(element, attrs);
+	append(element, children);
+	return element;
+}
+/** Make an element act as a button for mouse and keyboard (Enter / Space). */
+function activatable(element, onActivate) {
+	element.setAttribute("tabindex", "0");
+	element.setAttribute("role", "button");
+	element.addEventListener("click", onActivate);
+	element.addEventListener("keydown", (event) => {
+		if (!("key" in event)) return;
+		if (event.key !== "Enter" && event.key !== " ") return;
+		event.preventDefault();
+		onActivate();
+	});
+}
+// src/viewer/coverage-mode.ts
+function items(machine) {
+	return [...machine.states, ...machine.edges];
+}
+/** 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");
+	return modes;
+}
+function measure(mode, item) {
+	if (mode === "run") return item.coverage;
+	if (mode === "tests") return item.tested;
+	return null;
+}
+function modeLabel(mode, machine) {
+	if (mode === "tests") return "example tests";
+	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(", ")}`;
+}
+// src/viewer/layout.ts
+const CHAR_WIDTH = 7;
+const NODE_HEIGHT = 36;
+const LABEL_HEIGHT = 16;
+const UNKNOWN_SIZE = 28;
+function anyIds(machine) {
+	return [...new Set(machine.edges.map((edge) => edge.from).filter(isAnyState))].sort();
+}
+function unknownNodeId(edge) {
+	return `?:${edge.id}`;
+}
+function regionNodeId(region) {
+	return `region:${region}`;
+}
+function stateWidth(state) {
+	return Math.max(80, state.label.length * CHAR_WIDTH + 24);
+}
+function parentRegion(region) {
+	const cut = region.lastIndexOf(".");
+	return cut === -1 ? null : region.slice(0, cut);
+}
+function addRegions(graph, regions) {
+	for (const region of regions) graph.setNode(regionNodeId(region), {
+		width: 0,
+		height: 0
+	});
+	for (const region of regions) {
+		const parent = parentRegion(region);
+		if (parent !== null && regions.includes(parent)) graph.setParent(regionNodeId(region), regionNodeId(parent));
+	}
+}
+function addStates(graph, machine) {
+	for (const state of machine.states) {
+		graph.setNode(state.id, {
+			width: stateWidth(state),
+			height: NODE_HEIGHT
+		});
+		if (state.region !== null) graph.setParent(state.id, regionNodeId(state.region));
+	}
+}
+function addAnyNodes(graph, machine) {
+	for (const id of anyIds(machine)) {
+		graph.setNode(id, {
+			width: 87,
+			height: NODE_HEIGHT
+		});
+		const region = scopeOf(id);
+		if (region !== "" && machine.regions.includes(region)) graph.setParent(id, regionNodeId(region));
+	}
+}
+function addEdges(graph, machine) {
+	for (const edge of machine.edges) {
+		if (edge.kind === "initial" || edge.to === edge.from) continue;
+		const target = edge.to ?? unknownNodeId(edge);
+		if (edge.to === null) {
+			graph.setNode(target, {
+				width: UNKNOWN_SIZE,
+				height: UNKNOWN_SIZE
+			});
+			const region = machine.states.find((state) => state.id === edge.from)?.region ?? null;
+			if (region !== null) graph.setParent(target, regionNodeId(region));
+		}
+		const label = {
+			width: edgeText(edge, machine).length * CHAR_WIDTH + 8,
+			height: LABEL_HEIGHT,
+			labelpos: "c"
+		};
+		graph.setEdge(edge.from, target, label, edge.id);
+	}
+}
+function box(label) {
+	return {
+		x: label.x ?? 0,
+		y: label.y ?? 0,
+		width: label.width,
+		height: label.height
+	};
+}
+function placeNodes(graph, machine) {
+	const states = machine.states.map((state) => ({
+		kind: "state",
+		id: state.id,
+		state,
+		...box(graph.node(state.id))
+	}));
+	const unknowns = machine.edges.filter((edge) => edge.kind !== "initial" && edge.to === null).map((edge) => ({
+		kind: "unknown",
+		id: unknownNodeId(edge),
+		edgeId: edge.id,
+		...box(graph.node(unknownNodeId(edge)))
+	}));
+	const anys = anyIds(machine).map((id) => ({
+		kind: "any",
+		id,
+		...box(graph.node(id))
+	}));
+	return [
+		...states,
+		...anys,
+		...unknowns
+	];
+}
+function polyline(points) {
+	return points.map((point, index) => `${index === 0 ? "M" : "L"}${point.x.toFixed(1)},${point.y.toFixed(1)}`).join(" ");
+}
+/**
+* Self-loops are drawn by hand above the node: dagre routes them as a flat
+* line. The nth loop on a node is taller, so several loops stay readable.
+*/
+function selfLoop(node, nth) {
+	const { x, y, width, height } = box(node);
+	const top = y - height / 2;
+	const rise = 26 + nth * 18;
+	const spread = width / 2;
+	return {
+		path: `M${(x - width / 4).toFixed(1)},${top.toFixed(1)} C${(x - spread).toFixed(1)},${(top - rise).toFixed(1)} ${(x + spread).toFixed(1)},${(top - rise).toFixed(1)} ${(x + width / 4).toFixed(1)},${top.toFixed(1)}`,
+		label: {
+			x,
+			y: top - rise * .75 - 4
+		}
+	};
+}
+function placeEdges(graph, machine) {
+	const loopsSeen = /* @__PURE__ */ new Map();
+	return machine.edges.filter((edge) => edge.kind !== "initial").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,
+				...selfLoop(graph.node(edge.from), nth)
+			};
+		}
+		const target = edge.to ?? unknownNodeId(edge);
+		const label = graph.edge(edge.from, target, edge.id);
+		return {
+			edge,
+			target,
+			path: polyline(label.points ?? []),
+			label: {
+				x: label.x ?? 0,
+				y: label.y ?? 0
+			}
+		};
+	});
+}
+function placeEntry(graph, machine) {
+	if (machine.initial === null) return null;
+	const node = box(graph.node(machine.initial));
+	const left = node.x - node.width / 2;
+	return {
+		from: {
+			x: left - 28,
+			y: node.y
+		},
+		to: {
+			x: left,
+			y: node.y
+		}
+	};
+}
+/**
+* Layered layout (dagre, left to right). Pure: same machine in, same
+* coordinates out. The initial edge is drawn as an entry arrow, not a graph edge.
+*/
+function layoutMachine(machine) {
+	const graph = new Graph({
+		multigraph: true,
+		compound: true
+	});
+	graph.setGraph({
+		rankdir: "LR",
+		nodesep: 28,
+		ranksep: 64,
+		edgesep: 14,
+		marginx: 48,
+		marginy: 64
+	});
+	addRegions(graph, machine.regions);
+	addStates(graph, machine);
+	addAnyNodes(graph, machine);
+	addEdges(graph, machine);
+	layout(graph);
+	const size = graph.graph();
+	return {
+		width: size.width ?? 0,
+		height: size.height ?? 0,
+		nodes: placeNodes(graph, machine),
+		edges: placeEdges(graph, machine),
+		regions: machine.regions.map((region) => ({
+			region,
+			...box(graph.node(regionNodeId(region)))
+		})),
+		entry: placeEntry(graph, machine)
+	};
+}
+// src/viewer/graph.ts
+function sourceText$1(from) {
+	return isAnyState(from) ? "any state" : from;
+}
+function isUnreached(coverage) {
+	return coverage !== null && coverage.hits === 0;
+}
+function classes(names) {
+	return Object.entries(names).filter(([, on]) => on).map(([name]) => name).join(" ");
+}
+function defs(doc) {
+	return svg(doc, "defs", {}, [svg(doc, "marker", {
+		id: "viz-arrow",
+		viewBox: "0 0 10 10",
+		refX: 9,
+		refY: 5,
+		markerWidth: 7,
+		markerHeight: 7,
+		orient: "auto-start-reverse"
+	}, [svg(doc, "path", {
+		d: "M0,0 L10,5 L0,10 z",
+		class: "arrow-head"
+	})])]);
+}
+function regionGroup(doc, placed) {
+	return svg(doc, "g", {
+		class: "region",
+		"data-region": placed.region
+	}, [svg(doc, "rect", {
+		x: placed.x - placed.width / 2,
+		y: placed.y - placed.height / 2,
+		width: placed.width,
+		height: placed.height,
+		rx: 10
+	}), svg(doc, "text", {
+		x: placed.x - placed.width / 2 + 8,
+		y: placed.y - placed.height / 2 + 14
+	}, [placed.region])]);
+}
+function stateGroup(doc, placed, callbacks) {
+	const { state } = placed;
+	const left = placed.x - placed.width / 2;
+	const top = placed.y - placed.height / 2;
+	const frame = {
+		x: left,
+		y: top,
+		width: placed.width,
+		height: placed.height,
+		rx: 8
+	};
+	const group = svg(doc, "g", {
+		class: classes({
+			state: true,
+			initial: state.initial,
+			final: state.final,
+			unreached: isUnreached(measure(callbacks.mode, state))
+		}),
+		"data-node-id": state.id,
+		"aria-label": `state ${state.id}${state.final ? " (final)" : ""}`
+	}, [
+		svg(doc, "rect", {
+			...frame,
+			class: "frame"
+		}),
+		state.final ? svg(doc, "rect", {
+			x: left + 4,
+			y: top + 4,
+			width: placed.width - 8,
+			height: placed.height - 8,
+			rx: 5,
+			class: "frame inner"
+		}) : null,
+		svg(doc, "text", {
+			x: placed.x,
+			y: placed.y + 4,
+			"text-anchor": "middle"
+		}, [state.label])
+	]);
+	activatable(group, () => callbacks.select({
+		kind: "state",
+		id: state.id
+	}));
+	return group;
+}
+function unknownGroup(doc, placed) {
+	return svg(doc, "g", {
+		class: "unknown-node",
+		"data-node-id": placed.id,
+		"aria-label": "undetermined target"
+	}, [svg(doc, "circle", {
+		cx: placed.x,
+		cy: placed.y,
+		r: placed.width / 2
+	}), svg(doc, "text", {
+		x: placed.x,
+		y: placed.y + 5,
+		"text-anchor": "middle"
+	}, ["?"])]);
+}
+function anyGroup(doc, placed) {
+	return svg(doc, "g", {
+		class: "any-node",
+		"data-node-id": placed.id,
+		"aria-label": "any non-final state (onAny handlers)"
+	}, [svg(doc, "rect", {
+		x: placed.x - placed.width / 2,
+		y: placed.y - placed.height / 2,
+		width: placed.width,
+		height: placed.height,
+		rx: placed.height / 2
+	}), svg(doc, "text", {
+		x: placed.x,
+		y: placed.y + 4,
+		"text-anchor": "middle"
+	}, ["any state"])]);
+}
+function nodeGroup(doc, node, callbacks) {
+	if (node.kind === "state") return stateGroup(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 group = svg(doc, "g", {
+		class: classes({
+			edge: true,
+			effect: edge.kind === "effect",
+			stay: edge.kind === "stay",
+			fuzz: edge.origin === "fuzz",
+			undetermined: edge.to === null,
+			internal: internal === true,
+			unreached: isUnreached(measure(context.callbacks.mode, edge))
+		}),
+		"data-edge-id": edge.id,
+		"data-from": edge.from,
+		"data-to": placed.target,
+		"aria-label": edgeAria(edge, text)
+	}, [svg(doc, "path", {
+		d: placed.path,
+		"marker-end": "url(#viz-arrow)"
+	}), svg(doc, "text", {
+		x: placed.label.x,
+		y: placed.label.y + 4,
+		"text-anchor": "middle"
+	}, [text])]);
+	activatable(group, () => context.callbacks.select({
+		kind: "edge",
+		id: edge.id
+	}));
+	return group;
+}
+function entryArrow(doc, entry) {
+	return svg(doc, "g", {
+		class: "entry",
+		"aria-hidden": "true"
+	}, [svg(doc, "circle", {
+		cx: entry.from.x,
+		cy: entry.from.y,
+		r: 4
+	}), svg(doc, "path", {
+		d: `M${entry.from.x},${entry.from.y} L${entry.to.x},${entry.to.y}`,
+		"marker-end": "url(#viz-arrow)"
+	})]);
+}
+/** Toggle `highlight` on an edge and both of its endpoints while hovered. */
+function wireHover(root) {
+	for (const edge of root.querySelectorAll(".edge")) {
+		const ends = /* @__PURE__ */ new Set([edge.dataset["from"], edge.dataset["to"]]);
+		const endpoints = () => [...root.querySelectorAll("[data-node-id]")].filter((node) => ends.has(node.dataset["nodeId"]));
+		edge.addEventListener("mouseenter", () => {
+			for (const element of [edge, ...endpoints()]) element.classList.add("highlight");
+		});
+		edge.addEventListener("mouseleave", () => {
+			for (const element of [edge, ...endpoints()]) element.classList.remove("highlight");
+		});
+	}
+}
+/** 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);
+	const root = svg(doc, "svg", {
+		class: "graph",
+		viewBox: `0 0 ${Math.ceil(placed.width)} ${Math.ceil(placed.height)}`,
+		width: Math.ceil(placed.width),
+		height: Math.ceil(placed.height),
+		style: `max-width: ${Math.ceil(placed.width)}px`,
+		role: "group",
+		"aria-label": `machine ${machine.id}`
+	}, [
+		defs(doc),
+		...placed.regions.map((region) => regionGroup(doc, region)),
+		...placed.edges.map((edge) => edgeGroup(doc, edge, {
+			machine,
+			callbacks
+		})),
+		placed.entry ? entryArrow(doc, placed.entry) : null,
+		...placed.nodes.map((node) => nodeGroup(doc, node, callbacks))
+	]);
+	wireHover(root);
+	return root;
+}
+// src/viewer/explanation.ts
+function where(location) {
+	return location === null ? "unknown location" : `${location.file}:${location.line}:${location.column}`;
+}
+function targetText$2(branch) {
+	if (branch.target.kind === "state") return branch.target.state;
+	if (branch.target.kind === "stay") return "(stay)";
+	return `? ${branch.target.text}`;
+}
+/** Does the graph hold an edge for this branch from the selected edge's state? */
+function inGraph(branch, context) {
+	const { edge, machine } = context;
+	const target = branch.target;
+	return machine.edges.some((candidate) => {
+		if (candidate.from !== edge.from || candidate.event !== edge.event) return false;
+		if (target.kind === "stay") return candidate.kind === "stay";
+		return target.kind === "state" && candidate.to === target.state;
+	});
+}
+function isThisEdge(branch, edge) {
+	if (branch.target.kind === "stay") return edge.kind === "stay";
+	return branch.target.kind === "state" && branch.target.state === edge.to;
+}
+function branchItem(doc, branch, context) {
+	const condition = branch.conditions.length === 0 ? "always" : branch.conditions.join(" && ");
+	const status = isThisEdge(branch, context.edge) ? "this edge" : inGraph(branch, context) ? "in graph" : "not in graph";
+	return html(doc, "li", {
+		class: "branch",
+		"data-branch-status": status
+	}, [
+		html(doc, "code", {}, [condition]),
+		` → ${targetText$2(branch)} `,
+		html(doc, "span", { class: "branch-status" }, [`(${status})`])
+	]);
+}
+function comparisonText(comparison) {
+	return `${comparison.source}.${comparison.path} ${comparison.operator} ${JSON.stringify(comparison.literal)}`;
+}
+function line(doc, label, value) {
+	return html(doc, "p", { "data-explain": label }, [html(doc, "span", { class: "muted" }, [`${label}: `]), value]);
+}
+function joined$1(values) {
+	return values.length === 0 ? "none" : values.join(", ");
+}
+/**
+* Static explanation of an edge's handler. Branches the graph lacks are
+* listed as "not in graph": the AST annotates, it never adds edges.
+*/
+function renderExplanation(doc, context) {
+	const explanation = context.edge.explanation;
+	if (explanation === null) {
+		const kind = context.edge.kind;
+		return kind === "initial" || kind === "effect" ? "no handler behind this edge" : "not analyzed";
+	}
+	if (explanation.status === "not_analyzed") return html(doc, "div", { class: "explanation not-analyzed" }, [
+		line(doc, "not analyzed", explanation.reason),
+		line(doc, "at", where(explanation.location)),
+		explanation.snippet === null ? null : html(doc, "pre", {}, [explanation.snippet])
+	]);
+	return html(doc, "div", { class: "explanation" }, [
+		line(doc, "at", `${where(explanation.location)} (m.${explanation.registration})`),
+		html(doc, "ul", { class: "branches" }, explanation.branches.map((branch) => branchItem(doc, branch, context))),
+		explanation.readsActorState ? line(doc, "note", "reads live actor state; probing cannot determine the target") : null,
+		line(doc, "payload reads", joined$1(explanation.payloadReads)),
+		line(doc, "context reads", joined$1(explanation.contextReads)),
+		line(doc, "context writes", joined$1(explanation.contextWrites)),
+		line(doc, "comparisons", joined$1(explanation.comparisons.map(comparisonText)))
+	]);
+}
+// src/viewer/panel.ts
+function list(doc, rows) {
+	return html(doc, "dl", {}, rows.flatMap(([label, value]) => [html(doc, "dt", {}, [label]), html(doc, "dd", { "data-field": label }, [value])]));
+}
+function joined(values) {
+	return values.length === 0 ? "none" : values.join(", ");
+}
+function hitsText(coverage) {
+	return coverage === null ? "not supplied" : String(coverage.hits);
+}
+const ORIGIN_LABELS = {
+	declared: "declared (builder `to`)",
+	probe: "probe",
+	fuzz: "fuzz (observed, not declared)"
+};
+function runLabel(machine) {
+	return machine.fuzz === null ? "run hits" : "fuzz hits";
+}
+/**
+* A declared or probed edge no fuzz run produced. `to` lists what the handler
+* may return, not what its guards allow; probing runs it with `{}` and a sample
+* context. Either way the live machine may never take it.
+*/
+function predictionNote(doc, edge, machine) {
+	const unobserved = edge.coverage !== null && edge.coverage.hits === 0;
+	if (machine.fuzz === null || edge.origin === "fuzz" || edge.kind !== "transition" || !unobserved) return null;
+	return html(doc, "p", {
+		class: "prediction-note",
+		role: "note"
+	}, [`${edge.origin === "declared" ? "The handler declares this target in `to`, but no fuzz run produced it. Its guards may never allow it." : "Probing predicted this edge, but no fuzz run produced it. Probing calls the handler with an empty payload and a sample context, so this edge may be impossible in a real run."} Fuzzing never proves that, so check the handler.`]);
+}
+function stepText(step) {
+	if (step.kind === "advance") return `advance ${step.ms}ms`;
+	return step.payload === null ? step.event : `${step.event} ${JSON.stringify(step.payload)}`;
+}
+function featureOf(edge) {
+	if (edge.kind === "stay") return `stay:${edge.from}>${edge.event}`;
+	if (edge.kind !== "transition" || edge.to === null) return null;
+	return `edge:${edge.from}>${edge.event}>${edge.to}`;
+}
+/** Shortest kept fuzz sequence that first reached this edge, as a numbered list. */
+function reachedBy(doc, edge, machine) {
+	const feature = featureOf(edge);
+	if (machine.fuzz === null) return "not fuzzed";
+	const shortest = machine.fuzz.corpus.filter((sequence) => feature !== null && sequence.discovered.includes(feature)).sort((left, right) => left.steps.length - right.steps.length)[0];
+	if (shortest === void 0) return "no kept sequence";
+	if (shortest.steps.length === 0) return "initial state";
+	return html(doc, "ol", { class: "steps" }, shortest.steps.map((step) => html(doc, "li", {}, [stepText(step)])));
+}
+function targetText$1(edge) {
+	if (edge.kind === "stay") return `${edge.to ?? edge.from} (handled, no state change)`;
+	return edge.to ?? "undetermined";
+}
+function sourceText(from) {
+	return isAnyState(from) ? "any state" : from;
+}
+function routingNote(doc, edge, machine) {
+	if (!isAnyState(edge.from)) return null;
+	const warning = routingWarnings(machine).find((each) => each.event === edge.event);
+	return warning ? html(doc, "p", {
+		class: "routing-note",
+		role: "note"
+	}, [warning.message]) : null;
+}
+function edgeLink(doc, edge, select) {
+	const link = html(doc, "span", {
+		class: "link",
+		"data-edge-link": edge.id
+	}, [`${sourceText(edge.from)} —${edge.event || "initial"}→ ${edge.to ?? "?"}`]);
+	activatable(link, () => select({
+		kind: "edge",
+		id: edge.id
+	}));
+	return html(doc, "li", {}, [link]);
+}
+function edgeList(doc, edges, select) {
+	if (edges.length === 0) return "none";
+	return html(doc, "ul", {}, edges.map((edge) => edgeLink(doc, edge, select)));
+}
+function edgePanel(doc, edge, machine) {
+	const internal = machine.events.find((event) => event.id === edge.event)?.internal === true;
+	return html(doc, "section", {
+		class: "details",
+		"data-selected-edge": edge.id
+	}, [
+		html(doc, "h2", {}, [`Edge ${edge.id}`]),
+		routingNote(doc, edge, machine),
+		predictionNote(doc, edge, machine),
+		list(doc, [
+			["source", isAnyState(edge.from) ? "any state (onAny)" : edge.from],
+			["event", edge.kind === "initial" ? "(initial)" : `${edge.event}${internal ? " (internal)" : ""}`],
+			["target", targetText$1(edge)],
+			["kind", edge.kind],
+			["origin", ORIGIN_LABELS[edge.origin]],
+			["emits", joined(edge.emits)],
+			["contexts", joined(edge.contexts)],
+			[runLabel(machine), hitsText(edge.coverage)],
+			["test hits", hitsText(edge.tested)],
+			["explanation", renderExplanation(doc, {
+				edge,
+				machine
+			})],
+			["reached by", reachedBy(doc, edge, machine)]
+		])
+	]);
+}
+function statePanel(doc, state, context) {
+	const { machine, select } = context;
+	const flags = [state.initial ? "initial" : "", state.final ? "final" : ""].filter(Boolean);
+	const outgoing = machine.edges.filter((edge) => edge.from === state.id || !state.final && coveredByAny(edge.from, state.id));
+	const incoming = machine.edges.filter((edge) => edge.to === state.id && edge.kind !== "initial");
+	return html(doc, "section", {
+		class: "details",
+		"data-selected-state": state.id
+	}, [html(doc, "h2", {}, [`State ${state.id}`]), list(doc, [
+		["id", state.id],
+		["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"})`))],
+		[machine.fuzz === null ? "run visits" : "fuzz visits", hitsText(state.coverage)],
+		["test visits", hitsText(state.tested)],
+		["outgoing", edgeList(doc, outgoing, select)],
+		["incoming", edgeList(doc, incoming, select)]
+	])]);
+}
+function fuzzSummary(doc, machine) {
+	const { fuzz } = machine;
+	if (fuzz === null) return null;
+	const errors = fuzz.errors.length === 0 ? "none" : html(doc, "ul", {}, fuzz.errors.map((error) => html(doc, "li", { class: "fuzz-error" }, [`${error.from} on ${error.event}: ${error.message} — `, html(doc, "code", {}, [error.steps.map(stepText).join(" → ")])])));
+	return html(doc, "section", { class: "fuzz-summary" }, [html(doc, "h2", {}, ["Fuzz run"]), list(doc, [
+		["seed", String(fuzz.seed)],
+		["iterations", String(fuzz.iterations)],
+		["kept sequences", String(fuzz.corpus.length)],
+		["handler errors", errors]
+	])]);
+}
+/** Side-panel body for the current selection, or a hint when nothing is selected. */
+function renderPanel(doc, machine, context) {
+	const { selection } = context;
+	if (selection?.kind === "edge") {
+		const edge = machine.edges.find((candidate) => candidate.id === selection.id);
+		if (edge) return edgePanel(doc, edge, machine);
+	}
+	if (selection?.kind === "state") {
+		const state = machine.states.find((candidate) => candidate.id === selection.id);
+		if (state) return statePanel(doc, state, {
+			machine,
+			select: context.select
+		});
+	}
+	return html(doc, "div", {}, [html(doc, "p", { class: "hint" }, ["Select a state or edge."]), fuzzSummary(doc, machine)]);
+}
+// src/viewer/explore.ts
+const GROUP_TITLES = {
+	input: "Send an input",
+	effect: "Effect reports back",
+	internal: "Other internal events"
+};
+function code(doc, text) {
+	return html(doc, "code", {}, [text]);
+}
+function button(doc, label, context) {
+	const element = html(doc, "button", {
+		type: "button",
+		disabled: context.disabled ? "" : null,
+		...context.attrs
+	}, label);
+	element.addEventListener("click", context.onClick);
+	return element;
+}
+function targetText(move, target, current) {
+	return target === current && move.edge.kind === "stay" ? "stays" : `→ ${target}`;
+}
+function moveItem(doc, move, context) {
+	const { edge } = move;
+	const via = edge.from === context.current ? null : html(doc, "span", { class: "muted" }, [" (any state)"]);
+	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"])
+	]);
+	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] : []
+	], {
+		onClick: () => context.take({
+			edge: edge.id,
+			to: target
+		}),
+		attrs: {
+			"data-take": edge.id,
+			"data-target": target
+		}
+	})));
+}
+function effectsSection(doc, machine, current) {
+	const effects = machine.states.find((state) => state.id === current)?.effects ?? [];
+	if (effects.length === 0) return null;
+	const unhandled = unhandledSends(machine, current);
+	const isUnhandled = (effect, event) => unhandled.some((each) => each.effect === effect && each.event === event);
+	return html(doc, "div", { class: "explore-effects" }, [
+		html(doc, "p", {}, [`Entering ${current} runs:`]),
+		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 ";
+			return html(doc, "li", { "data-effect": effect.name }, [
+				code(doc, effect.name),
+				summary,
+				...sends.flatMap((event, index) => [index === 0 ? "" : ", ", html(doc, "span", { class: isUnhandled(effect.name, event) ? "unhandled" : null }, [code(doc, event)])])
+			]);
+		})),
+		unhandled.length === 0 ? null : html(doc, "p", {
+			class: "explore-warning",
+			role: "note"
+		}, [
+			`No handler in ${current} for `,
+			...unhandled.flatMap((each, index) => [index === 0 ? "" : ", ", code(doc, each.event)]),
+			": the actor ignores it."
+		])
+	]);
+}
+function movesSection(doc, moves, context) {
+	if (context.final) return html(doc, "p", {
+		class: "explore-end explore-done",
+		role: "status"
+	}, [html(doc, "strong", {}, ["Done."]), ` ${context.current} is final: the actor has stopped.`]);
+	if (moves.length === 0) return html(doc, "p", { class: "explore-end" }, [`No handler in ${context.current}: stuck.`]);
+	return html(doc, "div", { class: "explore-moves" }, [
+		"input",
+		"effect",
+		"internal"
+	].flatMap((group) => {
+		const inGroup = moves.filter((move) => move.group === group);
+		if (inGroup.length === 0) return [];
+		return [html(doc, "h3", {}, [GROUP_TITLES[group]]), html(doc, "ul", { "data-group": group }, inGroup.map((move) => moveItem(doc, move, context)))];
+	}));
+}
+function pathSection(doc, context) {
+	const { machine, path } = context;
+	const edges = new Map(machine.edges.map((edge) => [edge.id, edge]));
+	let from = machine.initial ?? "";
+	const items = path.map((step, index) => {
+		const event = edges.get(step.edge)?.event ?? step.edge;
+		const text = step.to === from ? `${event} in ${from}: stays` : `${event}: ${from} → ${step.to}`;
+		from = step.to;
+		return html(doc, "li", { "aria-current": index === path.length - 1 ? "step" : null }, [button(doc, [text], {
+			onClick: () => context.rewind(index + 1),
+			attrs: { "data-rewind": String(index + 1) }
+		})]);
+	});
+	return html(doc, "div", { class: "explore-path" }, [html(doc, "h3", {}, ["Path"]), html(doc, "ol", {}, [html(doc, "li", { "aria-current": path.length === 0 ? "step" : null }, [button(doc, [`start in ${machine.initial ?? "?"}`], {
+		onClick: () => context.rewind(0),
+		attrs: { "data-rewind": "0" }
+	})]), ...items])]);
+}
+/** 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 final = machine.states.find((state) => state.id === current)?.final === true;
+	const moves = movesFrom(machine, current);
+	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, {
+			current,
+			final,
+			take: context.take
+		}),
+		html(doc, "div", { class: "explore-controls" }, [button(doc, ["Back"], {
+			onClick: () => context.rewind(path.length - 1),
+			disabled: path.length === 0,
+			attrs: { "data-explore-action": "back" }
+		}), button(doc, ["Reset"], {
+			onClick: () => context.rewind(0),
+			disabled: path.length === 0,
+			attrs: { "data-explore-action": "reset" }
+		})]),
+		pathSection(doc, context)
+	]);
+}
+/**
+* Where a click on the diagram moves the walk, or null to just show details:
+* 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);
+	if (current === null) return null;
+	const { selection } = context;
+	const steps = movesFrom(machine, current).flatMap((move) => move.targets.map((to) => ({
+		edge: move.edge.id,
+		to
+	})));
+	const matching = selection.kind === "edge" ? steps.filter((step) => step.edge === selection.id) : steps.filter((step) => step.to === selection.id && step.to !== current);
+	return matching.length === 1 ? matching[0] ?? null : null;
+}
+/** 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 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));
+	const taken = new Set(path.map((step) => step.edge));
+	for (const element of root.querySelectorAll(".graph g[data-edge-id]")) {
+		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[data-node-id]")) {
+		const id = element.dataset["nodeId"];
+		element.classList.toggle("current", id === current);
+		element.classList.toggle("reachable", id !== void 0 && reachable.has(id));
+	}
+}
+// 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 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);
+	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", {
+		value: machine.id,
+		selected: machine.id === context.view.machineId ? "" : null
+	}, [machine.id])));
+	select.addEventListener("change", () => context.onChange(select.value));
+	return html(doc, "label", {}, ["Machine ", select]);
+}
+function isMode(value) {
+	return value === "off" || value === "run" || value === "tests";
+}
+function coveragePicker(doc, context) {
+	const modes = availableModes(context.machine);
+	if (modes.length === 0) return null;
+	const select = html(doc, "select", { class: "coverage-mode" }, [...modes, "off"].map((mode) => html(doc, "option", {
+		value: mode,
+		selected: mode === context.mode ? "" : null
+	}, [modeLabel(mode, context.machine)])));
+	select.addEventListener("change", () => {
+		if (isMode(select.value)) context.onChange(select.value);
+	});
+	return html(doc, "label", {}, ["Coverage from ", select]);
+}
+/**
+* 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.
+*/
+function mountViewer(root, viz, options = {}) {
+	const doc = root.ownerDocument;
+	const first = viz.machines.find((machine) => machine.id === options.machine) ?? viz.machines[0];
+	const view = {
+		machineId: first?.id ?? "",
+		selection: null,
+		coverage: null,
+		path: first === void 0 ? [] : decodePath(first, options.steps ?? [])
+	};
+	let back = () => void 0;
+	root.addEventListener("keydown", (event) => {
+		if (!("key" in event) || event.target instanceof HTMLSelectElement) return;
+		if (event.key === "ArrowLeft") back();
+	});
+	function render() {
+		const machine = viz.machines.find((candidate) => candidate.id === view.machineId);
+		root.replaceChildren();
+		root.classList.add("viz");
+		if (!machine) {
+			root.append(html(doc, "p", { class: "empty" }, ["Document has no machines."]));
+			return;
+		}
+		const mode = effectiveMode(view, machine);
+		root.classList.toggle("coverage-on", mode !== "off");
+		const panel = html(doc, "aside", {
+			class: "panel",
+			"aria-live": "polite"
+		});
+		const refresh = () => {
+			panel.replaceChildren(explorePanel(doc, {
+				machine,
+				path: view.path,
+				take,
+				rewind
+			}), renderPanel(doc, machine, {
+				selection: view.selection,
+				select
+			}));
+			markExplore(root, {
+				machine,
+				path: view.path
+			});
+			markSelection(root, view.selection);
+		};
+		const walked = () => {
+			options.onNavigate?.({
+				machine: machine.id,
+				steps: view.path.map((step) => encodeStep(machine, step))
+			});
+			refresh();
+		};
+		const take = (step) => {
+			view.path = [...view.path, step];
+			walked();
+		};
+		const rewind = (length) => {
+			view.path = view.path.slice(0, Math.max(0, length));
+			walked();
+		};
+		const select = (selection) => {
+			const step = clickStep(machine, {
+				path: view.path,
+				selection
+			});
+			view.selection = selection;
+			if (step === null) refresh();
+			else take(step);
+		};
+		back = () => rewind(view.path.length - 1);
+		root.append(headerOf(doc, {
+			viz,
+			machine,
+			view,
+			heading: options.heading ?? "h1",
+			mode,
+			render,
+			onNavigate: options.onNavigate
+		}), html(doc, "p", {
+			class: "banner",
+			role: "note"
+		}, [banner(machine)]), legend(doc, {
+			mode,
+			machine
+		}), html(doc, "div", { class: "viz-main" }, [html(doc, "div", { class: "canvas" }, [renderGraph(doc, machine, {
+			select,
+			mode
+		})]), panel]));
+		refresh();
+	}
+	render();
+}
+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, {
+			view,
+			onChange: (id) => {
+				view.machineId = id;
+				view.selection = null;
+				view.path = [];
+				context.onNavigate?.({
+					machine: id,
+					steps: []
+				});
+				render();
+			}
+		}),
+		coveragePicker(doc, {
+			machine,
+			mode: context.mode,
+			onChange: (next) => {
+				view.coverage = next;
+				render();
+			}
+		})
+	]);
+}
+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);
+}
+// src/viewer/embed.ts
+/**
+* Browser entry for embedding the viewer in another page (e.g. the docs site).
+* Kept apart from the root entry so bundles skip the fuzzer and the AST
+* annotator (TypeScript compiler).
+*/
+/** Replace `root` with a list of reasons `source` cannot be shown. */
+function showIssues(root, context) {
+	const doc = root.ownerDocument;
+	root.replaceChildren(html(doc, "section", {
+		class: "load-error",
+		role: "alert"
+	}, [html(doc, "h2", {}, [`Cannot show ${context.source}`]), html(doc, "ul", {}, context.issues.map((issue) => html(doc, "li", {}, [`${issue.path}: ${issue.message}`])))]));
+}
+/** Validate viz JSON text and mount it, or list what is wrong with it. */
+function mountVizText(root, context, options = {}) {
+	const result = parseViz(context.text);
+	if (Either.isLeft(result)) {
+		showIssues(root, {
+			source: context.source,
+			issues: result[0]
+		});
+		return;
+	}
+	mountViewer(root, result[1], options);
+}
+export { mountViewer as a, STRUCTURE_BANNER as i, showIssues as n, FUZZ_NOTE as r, mountVizText as t };