@mantaq/inspect 0.4.0 → 0.5.1

package/README.md

@@ -22,6 +22,8 @@ export default defineConfig({
 
 The live page runs the real actor, so it needs an exported factory on a `VirtualClock`; instance or `RealClock` machines fall back to the static walk.
 
+`vite build` with the plugin also writes the page as a static site: `index.html`, `viz.json` and a script under `base` (set `base: "/"` to put them at the output root). Machines load through your Vite config, and the fuzz runs at build time.
+
 Options: `base` (default `/__mantaq/`), `fuzz` (`false`, or `{ seed, iterations }`; default 500 iterations so a save redraws fast).
 
 **Library**: one call per machine.
@@ -34,12 +36,14 @@ const { machine, warnings } = inspect({
   id: "cart",
   create: () => createCart(), // a fresh actor every call
   source: { file: "/abs/src/cart.ts", root: "/abs" }, // optional: explanations + payloads from types
-  tests: [[{ kind: "event", event: "addItem", payload: { sku: "A1" } }]], // optional: "example tests" coverage
+  tests: [
+    { name: "add an item", steps: [{ kind: "event", event: "addItem", payload: { sku: "A1" } }] },
+  ], // optional: named runs for "example tests" coverage
 });
 const json = serializeViz(vizDocument([machine]));
 ```
 
-`inspectFile(file)` / `inspectModule(file, { load })` do the discovery the Vite plugin does. The building blocks (`toVizMachine`, `annotateMachine`, `fuzz`, `fuzzedMachine`, `withTestCoverage`, `guidance`) stay exported for custom pipelines.
+`inspectFile(file)` / `inspectModule(file, { load })` do the discovery the Vite plugin does, and read recorded runs from `__runs__/*.json` next to the machine file (`{ [machineId]: { name, end, steps }[] }`). A run is replayed on a fresh actor; internal events the replay already produces (timers, synchronous emits) are dropped, and a run that replays to a different state than `end` is dropped with a warning. The building blocks (`toVizMachine`, `annotateMachine`, `fuzz`, `fuzzedMachine`, `withTestCoverage`, `guidance`) stay exported for custom pipelines.
 
 ## What it needs from your file
 
@@ -56,7 +60,7 @@ Every part that cannot run is skipped with a warning, never guessed.
 The viewer's "Coverage from" picker dims elements with zero hits. What dimmed means depends on the source:
 
 - **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. Collected by replaying the event sequences you pass as `tests`, each on a fresh actor.
+- **example tests** (`tested`): no test exercises this. Collected by replaying the named runs you pass as `tests`, each on a fresh actor.
 - **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.
 
 ## How each tool works
@@ -71,6 +75,18 @@ The viewer's "Coverage from" picker dims elements with zero hits. What dimmed me
 
 **Guidance** (`guidance`, Phase 5): literal seeding plus a branch-distance guide built from AST comparisons on payload and context. It helps when handlers compare payload fields against literals far from the samples, or count in context toward a threshold. See `docs/atlas/phase5-comparison.md`.
 
+## Record runs from your tests
+
+In a vitest file, wrap the factory once and your tests become runs:
+
+```ts
+import { recordRuns } from "@mantaq/inspect/record";
+
+const make = recordRuns(createInviteLinkActor);
+```
+
+Every passing test that builds an actor with `make` writes its events and clock moves to `__runs__/<test file>.json` next to the test, keyed by machine id. `inspectModule` and the Vite plugin read those files, so each test shows up in the live page's Runs list and counts as an example run. Run the whole test file to refresh it. With `CI` set, a run that differs from the committed file fails the test, like a stale snapshot. The factory may be called in the test or in `beforeEach`; a retried test is recorded once. Runs with a payload that does not survive JSON (functions, `bigint`, `Map`, class instances) are skipped with a warning. `vitest` is an optional peer dependency.
+
 ## What it cannot show
 
 - **Guards** are not evaluated. A declared edge says "the handler may return this", not "some input reaches it". Fuzz coverage and the AST's branch conditions are the evidence; neither is proof.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { a as eventCatalog, i as Trace, n as Observation, o as execute, r as RunError, t as FuzzTarget } from "./run-BLt0mwXe.mjs";
-import { a as ModuleOptions, c as machineId, i as InspectedModule, l as vizDocument, n as InspectTarget, o as inspect, r as Inspected, s as inspectModule, t as FuzzSettings, u as AnalysisSource } from "./inspect-DvQtAcwv.mjs";
+import { a as ModuleOptions, c as machineId, i as InspectedModule, l as vizDocument, n as InspectTarget, o as inspect, r as Inspected, s as inspectModule, t as FuzzSettings, u as AnalysisSource } from "./inspect-vSdt2qtL.mjs";
 import { VizComparison, VizDocument, VizExplanation, VizFuzzError, VizJson, VizMachine, VizStep } from "@mantaq/viz";
 import { History } from "@mantaq/traversal";
 import { Either } from "@mantaq/utils";

package/dist/index.mjs

@@ -1,5 +1,6 @@
-import { S as toVizMachine, _ as fuzzedMachine, a as inspect, b as shrink, d as analyzeSource, f as annotateMachine, g as literalPool, h as guidance, l as vizDocument, m as branchDistanceGuide, o as inspectModule, p as branchDistance, r as inspectFile, s as machineId, u as analyzeModule, v as withTestCoverage, x as toViz, y as fuzz } from "./load-D0_Jl6Wr.mjs";
+import { _ as toViz, a as vizDocument, c as annotateMachine, d as guidance, f as literalPool, g as shrink, h as fuzz, l as branchDistance, m as withTestCoverage, n as inspectModule, o as analyzeModule, p as fuzzedMachine, r as machineId, s as analyzeSource, t as inspect, u as branchDistanceGuide, v as toVizMachine } from "./inspect-B7ZQCNM2.mjs";
 import { i as execute, r as eventCatalog } from "./run-B5huYj_r.mjs";
+import { r as inspectFile } from "./load-CWubcSZU.mjs";
 import { coveredByAny, unhandledSends } from "@mantaq/viz";
 // src/gate.ts
 /**
@@ -79,7 +80,7 @@ function missedReach(machine, expected) {
 }
 function failOnMiss(machine, misses) {
 	if (misses.length === 0) return;
-	throw new Error(`${machine.id} missed ${misses.length} expected ${misses.length === 1 ? "reach" : "reaches"}:\n${misses.map((each) => `  - ${each}`).join("\n")}\nAdd an example run to \`tests\`, or raise \`fuzz.iterations\`, to cover it.`);
+	throw new Error(`${machine.id} missed ${misses.length} expected ${misses.length === 1 ? "reach" : "reaches"}:\n${misses.map((each) => `  - ${each}`).join("\n")}\nAdd a named run to \`tests\`, or raise \`fuzz.iterations\`, to cover it.`);
 }
 /**
 * Call from a test: throws unless fuzzing or the target's `tests` visited every

package/dist/{load-D0_Jl6Wr.mjs → inspect-B7ZQCNM2.mjs}

@@ -1,14 +1,12 @@
-import { i as execute, r as eventCatalog } from "./run-B5huYj_r.mjs";
+import { i as execute, r as eventCatalog, t as applyStep } from "./run-B5huYj_r.mjs";
 import { ANY_STATE, VIZ_SCHEMA_VERSION, coveredByAny, isAnyState, routingWarnings, unhandledSends } from "@mantaq/viz";
 import { INITIAL_NODE_ID, buildGraph, parseInternalEventIds } from "@mantaq/traversal";
 import { Either } from "@mantaq/utils";
 import ts from "typescript";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
 import { DEFAULT_SEED } from "@mantaq/pbt";
 import { VirtualClock } from "@mantaq/core";
-import { existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { loadConfigFromFile, loadEnv, runnerImport } from "vite";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 // src/structure.ts
 function byId$1(left, right) {
 	if (left.id < right.id) return -1;
@@ -126,7 +124,8 @@ function toVizMachine(input) {
 		states,
 		events,
 		edges,
-		fuzz: null
+		fuzz: null,
+		runs: []
 	};
 }
 function toViz(inputs) {
@@ -1557,6 +1556,107 @@ function annotateWith(machine, context) {
 		edges
 	};
 }
+// src/runs.ts
+/** Name of the folder, next to the test files, that holds recorded runs. */
+const RUNS_DIR = "__runs__";
+function dropOne(list, item) {
+	const at = list.indexOf(item);
+	if (at < 0) return false;
+	list.splice(at, 1);
+	return true;
+}
+/**
+* Replay a raw recording on a fresh actor and keep only the steps that cannot
+* be reproduced: an internal event the replay already produced (a timer after
+* its advance, a synchronous emit after its send) is dropped, one it did not
+* (a promise result) is kept. Left when the replay ends elsewhere than the
+* test did.
+*/
+function normalizeRun(target, run) {
+	const { actor, clock } = target.create();
+	const internal = new Set(eventCatalog(actor).internal);
+	let produced = [];
+	actor.on("transition", { fn: ({ event }) => void produced.push(event.type) });
+	const known = /* @__PURE__ */ new Set([...eventCatalog(actor).inputs, ...internal]);
+	const unknown = run.steps.find((step) => step.kind === "event" && !known.has(step.event));
+	if (unknown?.kind === "event") {
+		actor.dispose();
+		return Either.left(`unknown event "${unknown.event}"`);
+	}
+	const kept = [];
+	for (const step of run.steps) {
+		if (step.kind === "event" && internal.has(step.event) && dropOne(produced, step.event)) continue;
+		produced = [];
+		applyStep(actor, {
+			step,
+			clock,
+			internal
+		});
+		if (step.kind === "event" && internal.has(step.event)) dropOne(produced, step.event);
+		kept.push(step);
+	}
+	const ended = actor.state.name;
+	actor.dispose();
+	return ended === run.end ? Either.right(kept) : Either.left(`replays to ${ended}, the test ended in ${run.end}`);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isJson(value) {
+	return Either.isRight(Either.from(() => JSON.stringify(value)));
+}
+function isStep(value) {
+	if (!isRecord(value)) return false;
+	if (value["kind"] === "advance") return typeof value["ms"] === "number" && value["ms"] >= 0;
+	return value["kind"] === "event" && typeof value["event"] === "string" && isJson(value["payload"]);
+}
+function isRecorded(value) {
+	return isRecord(value) && typeof value["name"] === "string" && typeof value["end"] === "string" && Array.isArray(value["steps"]) && value["steps"].every(isStep);
+}
+function readFile(file) {
+	const name = basename(file);
+	const text = Either.from(() => JSON.parse(readFileSync(file, "utf8")));
+	if (Either.isLeft(text) || !isRecord(text[1])) return {
+		runs: {},
+		warnings: [`${RUNS_DIR}/${name}: not a JSON object, ignored`]
+	};
+	const entries = Object.entries(text[1]).map(([id, runs]) => {
+		const list = Array.isArray(runs) ? runs : [];
+		const valid = list.filter(isRecorded);
+		return {
+			id,
+			valid,
+			bad: Array.isArray(runs) ? list.length - valid.length : 1
+		};
+	});
+	return {
+		runs: Object.fromEntries(entries.map(({ id, valid }) => [id, valid])),
+		warnings: entries.filter(({ bad }) => bad > 0).map(({ id, bad }) => `${RUNS_DIR}/${name}: ${bad} malformed run(s) for "${id}" ignored`)
+	};
+}
+/**
+* Every run recorded for the test files in `dir`: the `__runs__/*.json` files
+* next to them, merged by machine id in file-name order, and a warning for
+* each file or run that could not be read.
+*/
+function readRuns(dir) {
+	const listing = Either.from(() => readdirSync(join(dir, RUNS_DIR)).sort());
+	if (Either.isLeft(listing)) return {
+		runs: {},
+		warnings: []
+	};
+	const merged = {};
+	const warnings = [];
+	for (const name of listing[1].filter((each) => each.endsWith(".json"))) {
+		const read = readFile(join(dir, RUNS_DIR, name));
+		warnings.push(...read.warnings);
+		for (const [id, runs] of Object.entries(read.runs)) merged[id] = [...merged[id] ?? [], ...runs];
+	}
+	return {
+		runs: merged,
+		warnings
+	};
+}
 // src/inspect.ts
 const DEFAULT_ITERATIONS = 2e3;
 function isVirtualClock(clock) {
@@ -1601,11 +1701,11 @@ function driven(target, context) {
 	const fuzzed = settings === false ? structure : fuzzedMachine(run[1], fuzz(run[1], {
 		seed: settings?.seed ?? DEFAULT_SEED,
 		iterations: settings?.iterations ?? DEFAULT_ITERATIONS,
-		...target.tests === void 0 ? {} : { initial: target.tests },
+		...target.tests === void 0 ? {} : { initial: target.tests.map((run) => run.steps) },
 		...guidance(structure)
 	}));
 	return {
-		machine: target.tests === void 0 ? fuzzed : withTestCoverage(run[1], fuzzed, target.tests),
+		machine: target.tests === void 0 ? fuzzed : withTestCoverage(run[1], fuzzed, target.tests.map((each) => each.steps)),
 		skipped: []
 	};
 }
@@ -1624,7 +1724,10 @@ function inspectWith(target, analysis) {
 	});
 	const quiet = target.fuzz === false && target.tests === void 0;
 	const unanalyzed = analysis === null ? [] : [Either.getLeft(analysis)].filter((each) => each !== void 0);
-	const annotated = annotate(machine);
+	const annotated = annotate({
+		...machine,
+		runs: [...target.tests ?? []]
+	});
 	return {
 		machine: annotated,
 		warnings: [
@@ -1678,6 +1781,33 @@ function actorFactory(found, value) {
 		return isActor(actor) ? actor : sample;
 	};
 }
+/** The recorded runs of one machine that replay faithfully, and a warning for each that does not. */
+function replayedRuns(id, create, recorded) {
+	const found = recorded[id] ?? [];
+	if (found.length === 0) return {
+		runs: [],
+		warnings: []
+	};
+	const run = runner({
+		id,
+		create
+	}, {});
+	if (Either.isLeft(run)) return {
+		runs: [],
+		warnings: [`runs not shown: ${run[0]}`]
+	};
+	const results = found.map((each) => ({
+		each,
+		result: normalizeRun(run[1], each)
+	}));
+	return {
+		runs: results.flatMap(({ each, result }) => Either.isRight(result) ? [{
+			name: each.name,
+			steps: result[1]
+		}] : []),
+		warnings: results.flatMap(({ each, result }) => Either.isLeft(result) ? [`run "${each.name}" dropped: ${result[0]}`] : [])
+	};
+}
 /**
 * Every machine a file exports, found from its types: actors, and functions
 * that build one (optionally taking a clock or `{ clock }`). When a file has
@@ -1703,6 +1833,7 @@ async function inspectModule(file, options) {
 		warnings: [`${file}: no exported actor or actor factory found`]
 	};
 	const exports = await options.load(file);
+	const { runs: recorded, warnings: runWarnings } = readRuns(dirname(file));
 	const results = chosen.map((each) => {
 		const id = machineId(each.name);
 		const create = actorFactory(each, exports[each.name]);
@@ -1711,21 +1842,30 @@ async function inspectModule(file, options) {
 			warnings: [`${id}: ${each.name} did not return an actor`]
 		};
 		const fuzzSettings = each.call === "instance" ? false : options.fuzz ?? {};
+		const replayed = each.call === "instance" ? {
+			runs: [],
+			warnings: (recorded[id] ?? []).length === 0 ? [] : ["runs not shown: exported as one actor, so they cannot be replayed safely"]
+		} : replayedRuns(id, create, recorded);
 		const inspected = inspectWith({
 			id,
 			create,
 			source,
-			fuzz: fuzzSettings
+			fuzz: fuzzSettings,
+			...replayed.runs.length === 0 ? {} : { tests: replayed.runs }
 		}, analysis);
 		const instance = each.call === "instance" ? ["not fuzzed: exported as one actor, not a factory"] : [];
 		return {
 			machine: inspected.machine,
-			warnings: [...instance, ...inspected.warnings].map((warning) => `${id}: ${warning}`)
+			warnings: [
+				...instance,
+				...replayed.warnings,
+				...inspected.warnings
+			].map((warning) => `${id}: ${warning}`)
 		};
 	});
 	return {
 		machines: results.flatMap((result) => result.machine === null ? [] : [result.machine]),
-		warnings: results.flatMap((result) => result.warnings)
+		warnings: [...runWarnings.map((warning) => `${file}: ${warning}`), ...results.flatMap((result) => result.warnings)]
 	};
 }
 /** Machines as a document, ready for `serializeViz`. */
@@ -1735,129 +1875,4 @@ function vizDocument(machines) {
 		machines: [...machines]
 	};
 }
-// src/load.ts
-const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
-const ENTRY = "virtual:mantaq-inspect";
-const RESOLVED = `\0${ENTRY}`;
-/**
-* A module that imports the machine file and the inspector side by side. Run
-* through one module graph, both see the same `@mantaq/core` instance: core
-* recognizes its state refs by a module-level registry, so a machine loaded
-* through a bundler and inspected from plain Node would look stateless.
-*/
-function entrySource(file) {
-	const inspect = fileURLToPath(import.meta.resolve("@mantaq/inspect"));
-	return [
-		`import * as machines from ${JSON.stringify(file)};`,
-		`import { inspectModule } from ${JSON.stringify(inspect)};`,
-		`export function run(options) {`,
-		`  return inspectModule(${JSON.stringify(file)}, { ...options, load: async () => machines });`,
-		`}`
-	].join("\n");
-}
-/** Vite plugin serving the entry for each `virtual:mantaq-inspect?file=<path>` id. */
-function inspectEntry() {
-	return {
-		name: "mantaq-inspect-entry",
-		resolveId: (id) => id.startsWith(ENTRY) ? `\0${id}` : null,
-		load: (id) => {
-			if (!id.startsWith(RESOLVED)) return null;
-			const file = new URLSearchParams(id.slice(id.indexOf("?") + 1)).get("file");
-			return file === null ? null : entrySource(file);
-		}
-	};
-}
-function entryId(file) {
-	return `${ENTRY}?${new URLSearchParams({ file }).toString()}`;
-}
-/** The `run` export of an entry module, checked: module objects are untyped. */
-function runOf(module) {
-	const run = typeof module === "object" && module !== null ? Reflect.get(module, "run") : void 0;
-	if (typeof run !== "function") return null;
-	return async (options) => Reflect.apply(run, void 0, [options]);
-}
-const ENV_ACCESS = [
-	"import",
-	"meta",
-	"env"
-].join(".");
-/**
-* Replaces the env object with the project's env: `runnerImport` never reads
-* env files, so `VITE_*` variables would otherwise be missing. A textual
-* replace: it also rewrites matches in strings and comments, and a frozen
-* snapshot replaces Vite's own `import.meta.env`, so assigning to it fails.
-*/
-function projectEnv(env, mode) {
-	const value = JSON.stringify({
-		...env,
-		BASE_URL: "/",
-		MODE: mode,
-		DEV: true,
-		PROD: false,
-		SSR: true
-	});
-	return {
-		name: "mantaq-inspect-env",
-		enforce: "pre",
-		transform: (code, id) => id.includes("/node_modules/") || !code.includes(ENV_ACCESS) ? null : {
-			code: code.replaceAll(ENV_ACCESS, `(${value})`),
-			map: null
-		}
-	};
-}
-/**
-* The inline config for a load: empty without `--config`; otherwise the
-* project's Vite config (plugins, aliases, define) plus its env files.
-*/
-async function inlineConfig({ config, mode }) {
-	const base = {
-		configFile: false,
-		logLevel: "silent"
-	};
-	if (config === void 0) return {
-		...base,
-		...mode === void 0 ? {} : { mode }
-	};
-	const chosen = mode ?? "development";
-	const user = (await loadConfigFromFile({
-		command: "serve",
-		mode: chosen
-	}, config))?.config ?? {};
-	const envDir = resolve(dirname(config), user.envDir === false ? "." : user.envDir ?? ".");
-	const env = user.envDir === false ? {} : loadEnv(chosen, envDir, user.envPrefix ?? "VITE_");
-	return {
-		...user,
-		...base,
-		mode: chosen,
-		plugins: [...user.plugins ?? [], projectEnv(env, chosen)]
-	};
-}
-/** Load `file` with Vite (TS, tsconfig paths, extensionless imports) and inspect its machines. */
-async function inspectFile(file, options = {}, load = {}) {
-	if (load.config !== void 0 && !existsSync(load.config)) return {
-		machines: [],
-		warnings: [`${file}: Vite config not found: ${load.config}`],
-		failed: true
-	};
-	const loaded = await inlineConfig(load).then((inline) => runnerImport(entryId(file), {
-		...inline,
-		plugins: [...inline.plugins ?? [], inspectEntry()]
-	})).then((value) => Either.right(value), (error) => Either.left((error instanceof Error ? error.message : String(error)).replace(ANSI, "")));
-	if (Either.isLeft(loaded)) return {
-		machines: [],
-		warnings: [`${file}: ${loaded[0]}`],
-		failed: true
-	};
-	const { module } = loaded[1];
-	const run = runOf(module);
-	if (run === null) return {
-		machines: [],
-		warnings: [`${file}: could not load the inspector`],
-		failed: true
-	};
-	return {
-		...await run(options),
-		failed: false
-	};
-}
-export { toVizMachine as S, fuzzedMachine as _, inspect as a, shrink as b, projectRoot as c, analyzeSource as d, annotateMachine as f, literalPool as g, guidance as h, runOf as i, vizDocument as l, branchDistanceGuide as m, inspectEntry as n, inspectModule as o, branchDistance as p, inspectFile as r, machineId as s, entryId as t, analyzeModule as u, withTestCoverage as v, toViz as x, fuzz as y };
+export { toViz as _, vizDocument as a, annotateMachine as c, guidance as d, literalPool as f, shrink as g, fuzz as h, projectRoot as i, branchDistance as l, withTestCoverage as m, inspectModule as n, analyzeModule as o, fuzzedMachine as p, machineId as r, analyzeSource as s, inspect as t, branchDistanceGuide as u, toVizMachine as v };

package/dist/{inspect-DvQtAcwv.d.mts → inspect-vSdt2qtL.d.mts}

@@ -1,4 +1,4 @@
-import { VizDocument, VizJson, VizMachine, VizStep } from "@mantaq/viz";
+import { VizDocument, VizJson, VizMachine, VizRun } from "@mantaq/viz";
 import { Either } from "@mantaq/utils";
 import ts from "typescript";
 import { AnyActor } from "@mantaq/core";
@@ -23,8 +23,8 @@ interface InspectTarget {
   source?: AnalysisSource;
   /** Sample payloads per event; replace the ones read from types. */
   payloads?: Readonly<Record<string, ReadonlyArray<VizJson>>>;
-  /** Event sequences your tests send, for "Coverage from: example tests". */
-  tests?: ReadonlyArray<ReadonlyArray<VizStep>>;
+  /** Named runs your tests take: "Coverage from: example tests", fuzz seeds, and the live page's Runs list. */
+  tests?: ReadonlyArray<VizRun>;
   /** `false` = structure only. */
   fuzz?: false | FuzzSettings;
 }

package/dist/load-CWubcSZU.mjs

@@ -0,0 +1,131 @@
+import { Either } from "@mantaq/utils";
+import { dirname, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { loadConfigFromFile, loadEnv, runnerImport } from "vite";
+// src/load.ts
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+const ENTRY = "virtual:mantaq-inspect";
+const RESOLVED = `\0${ENTRY}`;
+/**
+* A module that imports the machine file and the inspector side by side. Run
+* through one module graph, both see the same `@mantaq/core` instance: core
+* recognizes its state refs by a module-level registry, so a machine loaded
+* through a bundler and inspected from plain Node would look stateless.
+*/
+function entrySource(file) {
+	const inspect = fileURLToPath(import.meta.resolve("@mantaq/inspect"));
+	return [
+		`import * as machines from ${JSON.stringify(file)};`,
+		`import { inspectModule } from ${JSON.stringify(inspect)};`,
+		`export function run(options) {`,
+		`  return inspectModule(${JSON.stringify(file)}, { ...options, load: async () => machines });`,
+		`}`
+	].join("\n");
+}
+/** Vite plugin serving the entry for each `virtual:mantaq-inspect?file=<path>` id. */
+function inspectEntry() {
+	return {
+		name: "mantaq-inspect-entry",
+		resolveId: (id) => id.startsWith(ENTRY) ? `\0${id}` : null,
+		load: (id) => {
+			if (!id.startsWith(RESOLVED)) return null;
+			const file = new URLSearchParams(id.slice(id.indexOf("?") + 1)).get("file");
+			return file === null ? null : entrySource(file);
+		}
+	};
+}
+function entryId(file) {
+	return `${ENTRY}?${new URLSearchParams({ file }).toString()}`;
+}
+/** The `run` export of an entry module, checked: module objects are untyped. */
+function runOf(module) {
+	const run = typeof module === "object" && module !== null ? Reflect.get(module, "run") : void 0;
+	if (typeof run !== "function") return null;
+	return async (options) => Reflect.apply(run, void 0, [options]);
+}
+const ENV_ACCESS = [
+	"import",
+	"meta",
+	"env"
+].join(".");
+/**
+* Replaces the env object with the project's env: `runnerImport` never reads
+* env files, so `VITE_*` variables would otherwise be missing. A textual
+* replace: it also rewrites matches in strings and comments, and a frozen
+* snapshot replaces Vite's own `import.meta.env`, so assigning to it fails.
+*/
+function projectEnv(env, mode) {
+	const value = JSON.stringify({
+		...env,
+		BASE_URL: "/",
+		MODE: mode,
+		DEV: true,
+		PROD: false,
+		SSR: true
+	});
+	return {
+		name: "mantaq-inspect-env",
+		enforce: "pre",
+		transform: (code, id) => id.includes("/node_modules/") || !code.includes(ENV_ACCESS) ? null : {
+			code: code.replaceAll(ENV_ACCESS, `(${value})`),
+			map: null
+		}
+	};
+}
+/**
+* The inline config for a load: empty without `--config`; otherwise the
+* project's Vite config (plugins, aliases, define) plus its env files.
+*/
+async function inlineConfig({ config, mode }) {
+	const base = {
+		configFile: false,
+		logLevel: "silent"
+	};
+	if (config === void 0) return {
+		...base,
+		...mode === void 0 ? {} : { mode }
+	};
+	const chosen = mode ?? "development";
+	const user = (await loadConfigFromFile({
+		command: "serve",
+		mode: chosen
+	}, config))?.config ?? {};
+	const envDir = resolve(dirname(config), user.envDir === false ? "." : user.envDir ?? ".");
+	const env = user.envDir === false ? {} : loadEnv(chosen, envDir, user.envPrefix ?? "VITE_");
+	return {
+		...user,
+		...base,
+		mode: chosen,
+		plugins: [...user.plugins ?? [], projectEnv(env, chosen)]
+	};
+}
+/** Load `file` with Vite (TS, tsconfig paths, extensionless imports) and inspect its machines. */
+async function inspectFile(file, options = {}, load = {}) {
+	if (load.config !== void 0 && !existsSync(load.config)) return {
+		machines: [],
+		warnings: [`${file}: Vite config not found: ${load.config}`],
+		failed: true
+	};
+	const loaded = await inlineConfig(load).then((inline) => runnerImport(entryId(file), {
+		...inline,
+		plugins: [...inline.plugins ?? [], inspectEntry()]
+	})).then((value) => Either.right(value), (error) => Either.left((error instanceof Error ? error.message : String(error)).replace(ANSI, "")));
+	if (Either.isLeft(loaded)) return {
+		machines: [],
+		warnings: [`${file}: ${loaded[0]}`],
+		failed: true
+	};
+	const { module } = loaded[1];
+	const run = runOf(module);
+	if (run === null) return {
+		machines: [],
+		warnings: [`${file}: could not load the inspector`],
+		failed: true
+	};
+	return {
+		...await run(options),
+		failed: false
+	};
+}
+export { runOf as i, inspectEntry as n, inspectFile as r, entryId as t };

package/dist/record.d.mts

@@ -0,0 +1,14 @@
+import { AnyActor } from "@mantaq/core";
+type Made = AnyActor<unknown> | {
+  actor: AnyActor<unknown>;
+};
+/**
+ * Wrap a machine factory in a vitest test file so every passing test that
+ * builds an actor with it is recorded to `__runs__/<test file>.json` next to
+ * the test: the events it handled and how far its clock moved. Run the whole
+ * file to refresh it; with `CI` set a stale file fails the test instead.
+ * The factory may be called in the test or in `beforeEach`. A retried test is
+ * recorded once, from the attempt that passed.
+ */
+export declare function recordRuns<F extends (...args: never[]) => Made>(factory: F): F;
+export {};

package/dist/record.mjs

@@ -0,0 +1,154 @@
+import { r as machineId } from "./inspect-B7ZQCNM2.mjs";
+import { Either } from "@mantaq/utils";
+import { basename, dirname, join } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+// ../../node_modules/.pnpm/vite-plus@1.4.0_@types+node@26.2.0_@typescript+native-preview@7.0.0-dev.20260707.2_@vit_594a0913d1d55d70a26e6ccc5f2ebd7d/node_modules/vite-plus/dist/test/index.js
+var test_exports = /* @__PURE__ */ __exportAll({});
+import * as import_vitest from "vitest";
+__reExport(test_exports, import_vitest);
+// src/record.ts
+/** Actors built during the running test attempt, flushed when it ends. */
+let pending = [];
+/** Runs recorded so far, per test file, per machine id. */
+const files = /* @__PURE__ */ new Map();
+function actorOf(made) {
+	return "actor" in made ? made.actor : made;
+}
+function isJson(value) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJson);
+	if (typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	if (proto !== Object.prototype && proto !== null) return false;
+	return Object.values(value).every((each) => each === void 0 || isJson(each));
+}
+function jsonPayload(payload) {
+	if (payload !== void 0 && !isJson(payload)) return Either.left("payload is not JSON");
+	const text = Either.from(() => JSON.stringify(payload ?? null));
+	if (Either.isLeft(text)) return Either.left("payload is not JSON");
+	return Either.right(JSON.parse(text[1]));
+}
+function textOf(runs) {
+	const body = [...runs].sort(([a], [b]) => a.localeCompare(b)).map(([id, list]) => [id, [...list].sort((a, b) => a.name.localeCompare(b.name))]);
+	return `${JSON.stringify(Object.fromEntries(body), null, 2)}\n`;
+}
+function sidecarOf(testPath) {
+	return join(dirname(testPath), "__runs__", `${basename(testPath).replace(/\.[cm]?[jt]sx?$/, "")}.json`);
+}
+function check(file, id, run) {
+	const committed = Either.from(() => JSON.parse(readFileSync(file, "utf8")));
+	const list = Either.isRight(committed) ? committed[1]?.[id] : void 0;
+	const found = Array.isArray(list) ? list.find((each) => each?.name === run.name) : void 0;
+	if (JSON.stringify(found) !== JSON.stringify(run)) throw new Error(`recordRuns: ${file} is out of date for "${run.name}". Run the tests locally without CI set and commit the result.`);
+}
+function flush(testPath, id, run, runs) {
+	const file = sidecarOf(testPath);
+	if (process.env["CI"]) return check(file, id, run);
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, textOf(runs));
+}
+function finish(attempt, passed) {
+	if (!passed) return;
+	const counts = /* @__PURE__ */ new Map();
+	for (const each of attempt) {
+		if (each.problem !== "") {
+			console.warn(`recordRuns: "${each.name}" not recorded, ${each.problem}`);
+			continue;
+		}
+		const now = each.actor.clock.now();
+		if (now > each.seen) each.steps.push({
+			kind: "advance",
+			ms: now - each.seen
+		});
+		const count = (counts.get(each.name) ?? 0) + 1;
+		counts.set(each.name, count);
+		const name = count === 1 ? each.name : `${each.name} #${count}`;
+		const runs = files.get(each.testPath) ?? /* @__PURE__ */ new Map();
+		files.set(each.testPath, runs);
+		const list = runs.get(each.id) ?? [];
+		runs.set(each.id, list);
+		const run = {
+			name,
+			end: each.actor.state.name,
+			steps: each.steps
+		};
+		list.push(run);
+		flush(each.testPath, each.id, run, runs);
+	}
+}
+(0, test_exports.afterEach)(({ task }) => {
+	const attempt = pending;
+	pending = [];
+	finish(attempt, task.result?.state !== "fail");
+});
+/**
+* Wrap a machine factory in a vitest test file so every passing test that
+* builds an actor with it is recorded to `__runs__/<test file>.json` next to
+* the test: the events it handled and how far its clock moved. Run the whole
+* file to refresh it; with `CI` set a stale file fails the test instead.
+* The factory may be called in the test or in `beforeEach`. A retried test is
+* recorded once, from the attempt that passed.
+*/
+function recordRuns(factory) {
+	const id = machineId(factory.name);
+	const wrapped = (...args) => {
+		const made = factory(...args);
+		const actor = actorOf(made);
+		const { testPath = "", currentTestName = "" } = test_exports.expect.getState();
+		const entry = {
+			actor,
+			id,
+			name: currentTestName,
+			testPath,
+			steps: [],
+			problem: "",
+			seen: actor.clock.now()
+		};
+		pending.push(entry);
+		actor.on("transition", { fn: ({ event }) => {
+			const now = actor.clock.now();
+			if (now > entry.seen) entry.steps.push({
+				kind: "advance",
+				ms: now - entry.seen
+			});
+			entry.seen = now;
+			const payload = jsonPayload(event.payload);
+			if (Either.isLeft(payload)) entry.problem = payload[0];
+			else entry.steps.push({
+				kind: "event",
+				event: event.type,
+				payload: payload[1]
+			});
+		} });
+		return made;
+	};
+	Object.defineProperty(wrapped, "name", { value: factory.name });
+	return wrapped;
+}
+export { recordRuns };

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { t as FuzzSettings } from "./inspect-DvQtAcwv.mjs";
+import { t as FuzzSettings } from "./inspect-vSdt2qtL.mjs";
 import { Plugin } from "vite";
 export declare const STYLESHEETS: string[];
 export interface MantaqVizOptions {

package/dist/vite.mjs

@@ -1,8 +1,9 @@
-import { c as projectRoot, i as runOf, l as vizDocument, n as inspectEntry, s as machineId, t as entryId, u as analyzeModule } from "./load-D0_Jl6Wr.mjs";
+import { a as vizDocument, i as projectRoot, o as analyzeModule, r as machineId } from "./inspect-B7ZQCNM2.mjs";
+import { i as runOf, n as inspectEntry, r as inspectFile, t as entryId } from "./load-CWubcSZU.mjs";
 import { UPDATE_EVENT, livePageHtml, serializeViz } from "@mantaq/viz";
 import { Either } from "@mantaq/utils";
-import { dirname, isAbsolute, resolve } from "node:path";
-import { globSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, posix, resolve } from "node:path";
+import { existsSync, globSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { searchForWorkspaceRoot } from "vite";
 // src/vite.ts
@@ -13,6 +14,9 @@ import { searchForWorkspaceRoot } from "vite";
 *   import { mantaqViz } from "@mantaq/inspect/vite";
 *   export default defineConfig({ plugins: [mantaqViz({ machines: "src/**\/*.machine.ts" })] });
 *
+* `vite build` with the plugin also writes the page as a static site
+* (`index.html`, `viz.json`, a script) under `base`.
+*
 * Open `/__mantaq/` while the dev server runs. Machines load through your own
 * Vite config (aliases, tsconfig paths), are inspected on the server, and the
 * page redraws, keeping the walk, when you save a file.
@@ -73,6 +77,64 @@ async function documentText(server, context) {
 		warnings: results.flatMap((result) => result.warnings)
 	};
 }
+function stylesheets() {
+	return STYLESHEETS.map((id) => readFileSync(fileURLToPath(import.meta.resolve(id)), "utf8")).join("\n");
+}
+/** Build mode: write the page, `viz.json` and the viewer script under `base`. */
+function siteBuild(context) {
+	let standalone = false;
+	return {
+		name: "mantaq-viz-build",
+		apply: "build",
+		config: (config) => {
+			const input = config.build?.rollupOptions?.input;
+			const root = resolve(config.root ?? process.cwd());
+			standalone = input === void 0 && !existsSync(resolve(root, "index.html"));
+			return standalone ? { build: { rollupOptions: { input: { "mantaq-live": context.live } } } } : {};
+		},
+		buildStart() {
+			if (!standalone) this.emitFile({
+				type: "chunk",
+				id: context.live,
+				name: "mantaq-live"
+			});
+		},
+		async generateBundle(_options, bundle) {
+			const results = [];
+			for (const file of machineFiles(context.root(), context.patterns)) {
+				const load = { config: context.project.configFile };
+				try {
+					results.push(await inspectFile(file, { fuzz: context.fuzz }, load));
+				} catch (error) {
+					this.warn(`[mantaq-viz] ${file}: could not inspect (${String(error)})`);
+				}
+			}
+			for (const warning of results.flatMap((result) => result.warnings)) this.warn(`[mantaq-viz] ${warning}`);
+			const text = serializeViz(vizDocument(results.flatMap((result) => result.machines)));
+			const dir = context.base.replace(/^\//, "");
+			const entry = Object.values(bundle).find((chunk) => chunk.type === "chunk" && chunk.isEntry && chunk.name === "mantaq-live");
+			if (entry === void 0) {
+				this.error("[mantaq-viz] the live page entry was not bundled");
+				return;
+			}
+			this.emitFile({
+				type: "asset",
+				fileName: `${dir}viz.json`,
+				source: text
+			});
+			this.emitFile({
+				type: "asset",
+				fileName: `${dir}index.html`,
+				source: livePageHtml({
+					title: "mantaq viz",
+					source: "viz.json",
+					entry: posix.relative(dir === "" ? "." : dir, entry.fileName),
+					css: stylesheets()
+				})
+			});
+		}
+	};
+}
 function mantaqViz(options) {
 	const base = (options.base ?? "/__mantaq/").replace(/\/?$/, "/");
 	const patterns = Array.isArray(options.machines) ? options.machines : [options.machines];
@@ -80,80 +142,92 @@ function mantaqViz(options) {
 	const live = fileURLToPath(import.meta.resolve(import.meta.url.endsWith(".ts") ? "./live-entry.ts" : "./live-entry.mjs"));
 	const viz = dirname(dirname(fileURLToPath(import.meta.resolve("@mantaq/viz/live"))));
 	let root = process.cwd();
-	return [
-		inspectEntry(),
-		{
-			name: "mantaq-viz-targets",
-			apply: "serve",
-			configResolved: (config) => {
-				root = config.root;
-			},
-			resolveId: (id) => id === "virtual:mantaq/targets" ? TARGETS_RESOLVED : null,
-			load: (id) => id === "\0virtual:mantaq/targets" ? targetsSource(machineFiles(root, patterns)) : null
+	const project = { configFile: void 0 };
+	const targets = {
+		name: "mantaq-viz-targets",
+		configResolved: (config) => {
+			root = config.root;
+			project.configFile = config.configFile;
 		},
-		{
-			name: "mantaq-viz",
-			apply: "serve",
-			config: (config) => ({ server: { fs: { allow: [
-				searchForWorkspaceRoot(config.root ?? process.cwd()),
-				dirname(dirname(live)),
-				viz
-			] } } }),
-			configureServer(server) {
-				let cached = null;
-				const build = async () => {
-					const { text, warnings } = await documentText(server, {
-						files: machineFiles(server.config.root, patterns),
-						fuzz
-					});
-					for (const warning of warnings) server.config.logger.warn(`[mantaq-viz] ${warning}`);
-					return text;
-				};
-				server.watcher.on("all", (_event, path) => {
-					if (!/\.[cm]?[jt]sx?$/.test(path)) return;
-					cached = null;
-					const generated = server.moduleGraph.getModuleById(TARGETS_RESOLVED);
-					if (generated !== void 0) server.moduleGraph.invalidateModule(generated);
-					server.environments.ssr.moduleGraph.invalidateAll();
-					server.ws.send({
-						type: "custom",
-						event: UPDATE_EVENT
-					});
+		resolveId: (id) => id === "virtual:mantaq/targets" ? TARGETS_RESOLVED : null,
+		load: (id) => id === "\0virtual:mantaq/targets" ? targetsSource(machineFiles(root, patterns)) : null
+	};
+	const plugin = {
+		name: "mantaq-viz",
+		apply: "serve",
+		config: (config) => ({ server: { fs: { allow: [
+			searchForWorkspaceRoot(config.root ?? process.cwd()),
+			dirname(dirname(live)),
+			viz
+		] } } }),
+		configureServer(server) {
+			let cached = null;
+			const build = async () => {
+				const { text, warnings } = await documentText(server, {
+					files: machineFiles(server.config.root, patterns),
+					fuzz
 				});
-				server.middlewares.use((request, response, next) => {
-					const path = request.url?.split("?")[0];
-					if (path === `${base}viz.json`) {
-						cached ??= build();
-						cached.then((text) => {
-							response.setHeader("content-type", "application/json");
-							response.end(text);
-						}, (error) => {
-							cached = null;
-							response.statusCode = 500;
-							response.end(String(error));
-						});
-						return;
-					}
-					if (path !== base && path !== base.slice(0, -1)) {
-						next();
-						return;
-					}
-					const html = livePageHtml({
-						title: "mantaq viz",
-						source: `${base}viz.json`,
-						entry: `/@fs${live}`,
-						css: STYLESHEETS.map((id) => readFileSync(fileURLToPath(import.meta.resolve(id)), "utf8")).join("\n")
-					});
-					server.transformIndexHtml(request.url ?? base, html).then((page) => {
-						response.setHeader("content-type", "text/html");
-						response.end(page);
+				for (const warning of warnings) server.config.logger.warn(`[mantaq-viz] ${warning}`);
+				return text;
+			};
+			server.watcher.on("all", (_event, path) => {
+				if (!/\.[cm]?[jt]sx?$/.test(path) && !/[\\/]__runs__[\\/][^\\/]+\.json$/.test(path)) return;
+				cached = null;
+				const generated = server.moduleGraph.getModuleById(TARGETS_RESOLVED);
+				if (generated !== void 0) server.moduleGraph.invalidateModule(generated);
+				server.environments.ssr.moduleGraph.invalidateAll();
+				server.ws.send({
+					type: "custom",
+					event: UPDATE_EVENT
+				});
+			});
+			server.middlewares.use((request, response, next) => {
+				const path = request.url?.split("?")[0];
+				if (path === `${base}viz.json`) {
+					cached ??= build();
+					cached.then((text) => {
+						response.setHeader("content-type", "application/json");
+						response.end(text);
+					}, (error) => {
+						cached = null;
+						response.statusCode = 500;
+						response.end(String(error));
 					});
+					return;
+				}
+				if (path !== base && path !== base.slice(0, -1)) {
+					next();
+					return;
+				}
+				const html = livePageHtml({
+					title: "mantaq viz",
+					source: `${base}viz.json`,
+					entry: `/@fs${live}`,
+					css: stylesheets()
 				});
-				server.httpServer?.once("listening", () => {
-					server.config.logger.info(`  mantaq viz: ${base}`);
+				server.transformIndexHtml(request.url ?? base, html).then((page) => {
+					response.setHeader("content-type", "text/html");
+					response.end(page);
 				});
-			}
+			});
+			server.httpServer?.once("listening", () => {
+				server.config.logger.info(`  mantaq viz: ${base}`);
+			});
 		}
+	};
+	const site = siteBuild({
+		base,
+		patterns,
+		fuzz,
+		live,
+		project,
+		root: () => root
+	});
+	return [
+		inspectEntry(),
+		targets,
+		site,
+		plugin
 	];
 }
 export { STYLESHEETS, TARGETS, TARGETS_RESOLVED, mantaqViz, targetsSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/inspect",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Turn a Mantaq machine into a viz document: structure, handler explanations (AST), fuzz and test coverage. Vite plugin included.",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
     ".": "./dist/index.mjs",
     "./drive": "./dist/drive.mjs",
     "./live-entry": "./dist/live-entry.mjs",
+    "./record": "./dist/record.mjs",
     "./vite": "./dist/vite.mjs",
     "./package.json": "./package.json"
   },
@@ -26,9 +27,9 @@
     "typescript": "6.0.3",
     "@mantaq/core": "0.5.4",
     "@mantaq/traversal": "0.3.4",
-    "@mantaq/viz": "0.3.0",
     "@mantaq/utils": "0.0.5",
-    "@mantaq/pbt": "0.0.4"
+    "@mantaq/pbt": "0.0.4",
+    "@mantaq/viz": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
@@ -36,10 +37,20 @@
     "happy-dom": "^21.0.4",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
     "vite-plus": "1.4.0",
+    "vitest": "5.0.5",
     "@mantaq/sugar": "2.0.4"
   },
   "peerDependencies": {
-    "vite": "*"
+    "vite": "*",
+    "vitest": "*"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "inlinedDependencies": {
+    "vite-plus": "1.4.0"
   },
   "scripts": {
     "build": "vp pack",