@mantaq/inspect 0.3.0 → 0.4.0

package/README.md

@@ -1,16 +1,12 @@
 # @mantaq/inspect
 
-Turns your Mantaq machine into a picture you can walk: one command, no config.
+Turns your Mantaq machine into a picture you can walk: add the Vite plugin, no other config.
 
-```sh
-mantaq-inspect src/cart.ts     # writes mantaq-viz.html and opens it
-```
-
-It finds every exported actor, or function that builds one, from the file's types. It reads handler explanations and sample payloads from the source, fuzzes each machine that runs on a `VirtualClock`, and writes one self-contained HTML page that works offline: commit it, attach it to a PR. The viewer is [`@mantaq/viz`](../viz/README.md).
+It finds every exported actor, or function that builds one, from the file's types. It reads handler explanations and sample payloads from the source, fuzzes each machine that runs on a `VirtualClock`, and shows them in a live page on your Vite dev server. The viewer is [`@mantaq/viz`](../viz/README.md).
 
-## Three ways in
+## Ways in
 
-**CLI**: `mantaq-inspect <file.ts>... [--out FILE] [--json] [--live] [--no-fuzz] [--iterations N] [--config FILE] [--mode MODE] [--no-open] [--check]`. `--config` loads the files with that Vite config (env, aliases, plugins) and `--mode` picks its mode; without `--config` no project config is read. `--check` exits 1 if a warning was printed or fuzzing found a handler error (printed as `error:`), so CI can gate on design errors. `--json` writes the viz document instead of the page. `--live` bundles your machine files into the page with Vite, so it is still one offline HTML file but its steps run the real actors (same rules as the Vite plugin's live page); it cannot be combined with `--json`. Seed: `MANTAQ_SEED` (default from `@mantaq/pbt`). Same seed → same output.
+**Gate in tests**: see the docs page "Design gate in vitest" for `expectNoDesignErrors`, `expectReached` and `expectAllStatesReached`.
 
 **Vite plugin**: a live page on your dev server that redraws, keeping your walk, when you save.
 
@@ -43,14 +39,14 @@ const { machine, warnings } = inspect({
 const json = serializeViz(vizDocument([machine]));
 ```
 
-`inspectFile(file)` / `inspectModule(file, { load })` do the discovery the CLI 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. The building blocks (`toVizMachine`, `annotateMachine`, `fuzz`, `fuzzedMachine`, `withTestCoverage`, `guidance`) stay exported for custom pipelines.
 
 ## What it needs from your file
 
 - **Exports.** An actor, or a function that returns one (or `{ actor }`). Functions are called with no arguments, with a `VirtualClock` when the first parameter is a clock, or with `{ clock }` when it is an options object with a `clock`. Functions with other required parameters are skipped. Discovery reads types only; nothing is called to find out.
 - **A fresh actor per call**, to fuzz. A file that only exports one actor instance is drawn, not fuzzed. When a file has factories, its actor instances are skipped.
 - **Exported factories.** Export a factory that takes ports and a clock, not only a built instance. See [Machines in an application](https://anderscan.github.io/mantaq/guides/machines-in-an-app/).
-- **A factory, for `--live`.** The live page recreates the actor on every step, so it needs an exported factory; a file that only exports an instance stays a static walk, with the usual warning.
+- **A factory, for the live page.** The page recreates the actor on every step, so it needs an exported factory; a file that only exports an instance stays a static walk, with the usual warning.
 - **A `VirtualClock`**, to fuzz. An actor on the real clock is drawn, with a warning.
 
 Every part that cannot run is skipped with a warning, never guessed.
@@ -59,6 +55,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.
 - **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/index.d.mts

@@ -37,6 +37,8 @@ interface FuzzOptions {
    * the run in the corpus as a stepping stone even without new coverage.
    */
   guide?: (trace: Trace) => boolean;
+  /** Known-good sequences (e.g. example tests) the corpus starts from, before any mutation. */
+  initial?: ReadonlyArray<ReadonlyArray<VizStep>>;
 }
 interface CorpusEntry {
   steps: VizStep[];
@@ -149,8 +151,39 @@ interface LoadOptions {
 /** Load `file` with Vite (TS, tsconfig paths, extensionless imports) and inspect its machines. */
 export declare function inspectFile(file: string, options?: FileOptions, load?: LoadOptions): Promise<LoadedFile>;
 /**
- * A self-contained HTML page for `document`: open it from disk, attach it, commit it.
- * With `live` (a built script that drives the machines), that script replaces the static viewer.
+ * States no edge path leads to from the initial state. Empty when an undetermined
+ * edge hides the answer. Region states are never reported: the graph does not
+ * record where a region starts.
  */
-export declare function htmlPage(document: VizDocument, title: string, live?: string): Promise<string>;
-export { type AnalysisSource, type CorpusEntry, type FileOptions, type FuzzOptions, type FuzzResult, type FuzzSettings, type FuzzTarget, type HandlerSite, type InspectTarget, type Inspected, type InspectedModule, type LiteralPool, type MachineExport, type ModuleAnalysis, type ModuleOptions, type Observation, type RunError, type Trace, type VizInput, eventCatalog, execute, inspect, inspectModule, machineId, vizDocument };
+export declare function unreachableStates(machine: VizMachine): string[];
+/** Design errors of an inspected machine, one line each. Unreached edges and routing warnings are not errors. */
+export declare function designErrors(machine: VizMachine): string[];
+/**
+ * Call from a test: throws when fuzzing finds a handler or effect that throws,
+ * an effect sends an event its state does not handle, or a declared state has
+ * no path from the initial state. Runs are seeded, so the result is stable.
+ */
+export declare function expectNoDesignErrors(target: InspectTarget): void;
+interface ReachTransition {
+  from: string;
+  event: string;
+  /** Omit to accept any target. */
+  to?: string;
+}
+interface ReachExpectation {
+  states?: ReadonlyArray<string>;
+  transitions?: ReadonlyArray<ReachTransition>;
+}
+/** Ids of the states a fuzz run or the supplied test sequences visited. */
+export declare function reachedStates(machine: VizMachine): string[];
+/** What the expectation asks for and the machine did not reach, one line each. */
+export declare function missedReach(machine: VizMachine, expected: ReachExpectation): string[];
+/**
+ * Call from a test: throws unless fuzzing or the target's `tests` visited every
+ * listed state and took every listed transition. Reaching is proof; a miss only
+ * says nothing got there yet.
+ */
+export declare function expectReached(target: InspectTarget, expected: ReachExpectation): void;
+/** Call from a test: throws unless fuzzing or the target's `tests` visited every declared state. */
+export declare function expectAllStatesReached(target: InspectTarget): void;
+export { type AnalysisSource, type CorpusEntry, type FileOptions, type FuzzOptions, type FuzzResult, type FuzzSettings, type FuzzTarget, type HandlerSite, type InspectTarget, type Inspected, type InspectedModule, type LiteralPool, type MachineExport, type ModuleAnalysis, type ModuleOptions, type Observation, type ReachExpectation, type ReachTransition, type RunError, type Trace, type VizInput, eventCatalog, execute, inspect, inspectModule, machineId, vizDocument };

package/dist/index.mjs

@@ -1,4 +1,98 @@
-import { C as toViz, S as shrink, _ as guidance, b as withTestCoverage, c as inspect, d as vizDocument, f as analyzeModule, g as branchDistanceGuide, h as branchDistance, l as inspectModule, m as annotateMachine, p as analyzeSource, s as inspectFile, u as machineId, v as literalPool, w as toVizMachine, x as fuzz, y as fuzzedMachine } from "./vite-BBW0CmYr.mjs";
+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 { i as execute, r as eventCatalog } from "./run-B5huYj_r.mjs";
-import { t as htmlPage } from "./page-CK7-IsLJ.mjs";
-export { analyzeModule, analyzeSource, annotateMachine, branchDistance, branchDistanceGuide, eventCatalog, execute, fuzz, fuzzedMachine, guidance, htmlPage, inspect, inspectFile, inspectModule, literalPool, machineId, shrink, toViz, toVizMachine, vizDocument, withTestCoverage };
+import { coveredByAny, unhandledSends } from "@mantaq/viz";
+// src/gate.ts
+/**
+* States no edge path leads to from the initial state. Empty when an undetermined
+* edge hides the answer. Region states are never reported: the graph does not
+* record where a region starts.
+*/
+function unreachableStates(machine) {
+	const reached = new Set(machine.states.filter((state) => state.initial || state.region !== null).map((state) => state.id));
+	const queue = [...reached];
+	let undetermined = false;
+	for (let next = queue.shift(); next !== void 0; next = queue.shift()) {
+		const from = next;
+		for (const edge of machine.edges) {
+			if (edge.kind === "effect" || edge.from !== from && !coveredByAny(edge.from, from)) continue;
+			if (edge.to === null) {
+				undetermined = true;
+				continue;
+			}
+			if (reached.has(edge.to)) continue;
+			reached.add(edge.to);
+			queue.push(edge.to);
+		}
+	}
+	if (undetermined) return [];
+	return machine.states.map((state) => state.id).filter((id) => !reached.has(id));
+}
+/** Design errors of an inspected machine, one line each. Unreached edges and routing warnings are not errors. */
+function designErrors(machine) {
+	const thrown = (machine.fuzz?.errors ?? []).map((error) => `${error.event} in ${error.from} throws: ${error.message}`);
+	const sends = machine.states.flatMap((state) => unhandledSends(machine, state.id).map(({ effect, event }) => `effect ${effect} in ${state.id} sends ${event}, but ${state.id} has no handler for it`));
+	const orphans = unreachableStates(machine).map((id) => `state ${id} is declared but no path leads to it from the initial state`);
+	return [
+		...thrown,
+		...sends,
+		...orphans
+	];
+}
+/**
+* Call from a test: throws when fuzzing finds a handler or effect that throws,
+* an effect sends an event its state does not handle, or a declared state has
+* no path from the initial state. Runs are seeded, so the result is stable.
+*/
+function expectNoDesignErrors(target) {
+	const { machine } = inspect(target);
+	const errors = designErrors(machine);
+	if (errors.length === 0) return;
+	throw new Error(`${machine.id} has ${errors.length} design error${errors.length === 1 ? "" : "s"}:\n${errors.map((each) => `  - ${each}`).join("\n")}`);
+}
+// src/reach.ts
+function hitCount(coverage) {
+	return coverage?.hits ?? 0;
+}
+/** Ids of the states a fuzz run or the supplied test sequences visited. */
+function reachedStates(machine) {
+	return machine.states.filter((state) => hitCount(state.coverage) + hitCount(state.tested) > 0).map((state) => state.id);
+}
+function isTaken(edge) {
+	return hitCount(edge.coverage) + hitCount(edge.tested) > 0;
+}
+function describeTransition({ from, event, to }) {
+	return to === void 0 ? `${from} --${event}-->` : `${from} --${event}--> ${to}`;
+}
+/** What the expectation asks for and the machine did not reach, one line each. */
+function missedReach(machine, expected) {
+	const reached = new Set(reachedStates(machine));
+	const states = (expected.states ?? []).map((id) => {
+		if (!machine.states.some((state) => state.id === id)) return `state ${id} does not exist`;
+		return reached.has(id) ? null : `state ${id} was not reached`;
+	});
+	const transitions = (expected.transitions ?? []).map((wanted) => {
+		const matching = machine.edges.filter((edge) => edge.kind !== "effect" && edge.kind !== "initial" && edge.from === wanted.from && edge.event === wanted.event && (wanted.to === void 0 || edge.to === wanted.to));
+		if (matching.length === 0) return `transition ${describeTransition(wanted)} does not exist`;
+		return matching.some(isTaken) ? null : `transition ${describeTransition(wanted)} was not taken`;
+	});
+	return [...states, ...transitions].filter((line) => line !== null);
+}
+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.`);
+}
+/**
+* Call from a test: throws unless fuzzing or the target's `tests` visited every
+* listed state and took every listed transition. Reaching is proof; a miss only
+* says nothing got there yet.
+*/
+function expectReached(target, expected) {
+	const { machine } = inspect(target);
+	failOnMiss(machine, missedReach(machine, expected));
+}
+/** Call from a test: throws unless fuzzing or the target's `tests` visited every declared state. */
+function expectAllStatesReached(target) {
+	const { machine } = inspect(target);
+	failOnMiss(machine, missedReach(machine, { states: machine.states.map((state) => state.id) }));
+}
+export { analyzeModule, analyzeSource, annotateMachine, branchDistance, branchDistanceGuide, designErrors, eventCatalog, execute, expectAllStatesReached, expectNoDesignErrors, expectReached, fuzz, fuzzedMachine, guidance, inspect, inspectFile, inspectModule, literalPool, machineId, missedReach, reachedStates, shrink, toViz, toVizMachine, unreachableStates, vizDocument, withTestCoverage };

package/dist/live-entry.mjs

@@ -1,6 +1,88 @@
-import { n as mountLiveDriven } from "./live-page-DEDl_Nio.mjs";
-import { UPDATE_EVENT } from "@mantaq/viz";
+import { createDriver } from "./drive.mjs";
+import { UPDATE_EVENT, parseViz } from "@mantaq/viz";
+import { Either } from "@mantaq/utils";
 import { targets } from "virtual:mantaq/targets";
+import { mountViewer, showIssues } from "@mantaq/viz/viewer";
+import { linkOptions } from "@mantaq/viz/page";
+// src/live-page.ts
+/**
+* The live page of the Vite plugin: the served document, with each machine
+* that has a target running for real behind the viewer. The walk lives in the
+* address bar (`?machine=&step=`), so a redraw after a save replays it on the
+* new code.
+*/
+/** A document holding only `machine`, so the viewer shows the machine its driver runs. */
+function only(viz, machine) {
+	const chosen = viz.machines.find((each) => each.id === machine) ?? viz.machines[0];
+	return {
+		...viz,
+		machines: chosen === void 0 ? [] : [chosen]
+	};
+}
+/** Mount the document at `text`; machines with a target run live, the rest stay static walks. */
+function mountDriven(root, context) {
+	const parsed = parseViz(context.text);
+	if (Either.isLeft(parsed)) {
+		showIssues(root, {
+			source: context.source,
+			issues: parsed[0]
+		});
+		return;
+	}
+	const options = linkOptions();
+	const viz = parsed[1];
+	const shown = only(viz, options.machine ?? null);
+	const id = shown.machines[0]?.id ?? "";
+	const target = context.targets[id];
+	const create = target !== void 0 && typeof Reflect.get(target().clock, "advance") === "function" ? target : void 0;
+	const picker = viz.machines.length > 1;
+	const select = (machine) => {
+		const next = new URLSearchParams(location.search);
+		next.set("machine", machine);
+		next.delete("step");
+		history.replaceState(null, "", `?${next.toString()}`);
+		mountDriven(root, context);
+	};
+	const doc = root.ownerDocument;
+	const bar = doc.createElement("nav");
+	bar.className = "machines";
+	if (picker) for (const machine of viz.machines) {
+		const button = doc.createElement("button");
+		button.type = "button";
+		button.textContent = machine.id;
+		button.disabled = machine.id === id;
+		button.addEventListener("click", () => select(machine.id));
+		bar.append(button);
+	}
+	const viewer = doc.createElement("div");
+	root.replaceChildren(...picker ? [bar] : [], viewer);
+	mountViewer(viewer, shown, {
+		...options,
+		...create === void 0 ? {} : { driver: createDriver({
+			id,
+			create
+		}) }
+	});
+}
+/** Fetch the document from `source` and mount it; call again to redraw, keeping the walk. */
+async function mountLiveDriven(root, context) {
+	const response = await fetch(context.source).catch(() => null);
+	if (response === null || !response.ok) {
+		const status = response === null ? "network error" : `HTTP ${response.status}`;
+		showIssues(root, {
+			source: context.source,
+			issues: [{
+				path: "$",
+				message: status
+			}]
+		});
+		return;
+	}
+	mountDriven(root, {
+		...context,
+		text: await response.text()
+	});
+}
 // src/live-entry.ts
 /**
 * Entry of the page `@mantaq/inspect/vite` serves. Redraws when the dev

package/dist/{vite-BBW0CmYr.mjs → load-D0_Jl6Wr.mjs}

@@ -1,14 +1,14 @@
 import { i as execute, r as eventCatalog } from "./run-B5huYj_r.mjs";
-import { ANY_STATE, UPDATE_EVENT, VIZ_SCHEMA_VERSION, coveredByAny, isAnyState, livePageHtml, routingWarnings, serializeViz, unhandledSends } from "@mantaq/viz";
+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, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { DEFAULT_SEED } from "@mantaq/pbt";
 import { VirtualClock } from "@mantaq/core";
-import { existsSync, globSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { loadConfigFromFile, loadEnv, runnerImport, searchForWorkspaceRoot } from "vite";
+import { loadConfigFromFile, loadEnv, runnerImport } from "vite";
 // src/structure.ts
 function byId$1(left, right) {
 	if (left.id < right.id) return -1;
@@ -407,6 +407,7 @@ function fuzz(target, options) {
 		}
 	}
 	consider([], 0);
+	for (const steps of options.initial ?? []) consider([...steps], 0);
 	for (let iteration = 1; iteration <= options.iterations; iteration += 1) {
 		const at = context.rng.int(corpus.length);
 		consider(mutate({
@@ -1600,6 +1601,7 @@ 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 },
 		...guidance(structure)
 	}));
 	return {
@@ -1858,155 +1860,4 @@ async function inspectFile(file, options = {}, load = {}) {
 		failed: false
 	};
 }
-// src/vite.ts
-/**
-* Vite plugin: a live page of your machines on your own dev server.
-*
-*   // vite.config.ts
-*   import { mantaqViz } from "@mantaq/inspect/vite";
-*   export default defineConfig({ plugins: [mantaqViz({ machines: "src/**\/*.machine.ts" })] });
-*
-* 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.
-*/
-const STYLESHEETS = ["@mantaq/viz/viewer.css", "@mantaq/viz/page.css"];
-const DEV_ITERATIONS = 500;
-const TARGETS = "virtual:mantaq/targets";
-const TARGETS_RESOLVED = `\0${TARGETS}`;
-function createExpression(found, index) {
-	const callee = `m${index}[${JSON.stringify(found.name)}]`;
-	const call = found.call === "clock" ? `${callee}(VirtualClock())` : found.call === "options" ? `${callee}({ clock: VirtualClock() })` : `${callee}()`;
-	return found.unwrap === "actor" ? `${call}.actor` : call;
-}
-/**
-* Source of `virtual:mantaq/targets`: one factory per exported actor factory,
-* shaped by its type (`call`, `clock`, `options`). A bare actor export cannot
-* be recreated, so it gets none. Like the server-side inspection, plain actors
-* are skipped when a file has factories.
-*/
-function targetsSource(files) {
-	const core = fileURLToPath(import.meta.resolve("@mantaq/core"));
-	const imports = [];
-	const entries = [];
-	files.forEach((file, index) => {
-		const analysis = analyzeModule({
-			file,
-			root: projectRoot(file)
-		});
-		if (Either.isLeft(analysis)) return;
-		const factories = analysis[1].machines.filter((found) => found.call !== "instance");
-		if (factories.length === 0) return;
-		imports.push(`import * as m${index} from ${JSON.stringify(file)};`);
-		for (const found of factories) entries.push(`  ${JSON.stringify(machineId(found.name))}: () => { const actor = ${createExpression(found, index)}; return { actor, clock: actor.clock }; },`);
-	});
-	return [
-		`import { VirtualClock } from ${JSON.stringify(core)};`,
-		...imports,
-		"export const targets = {",
-		...entries,
-		"};"
-	].join("\n");
-}
-function machineFiles(root, patterns) {
-	const files = patterns.flatMap((pattern) => globSync(pattern, { cwd: root }));
-	return [...new Set(files.map((file) => isAbsolute(file) ? file : resolve(root, file)))].sort();
-}
-async function documentText(server, context) {
-	const results = [];
-	for (const file of context.files) {
-		const run = runOf(await server.ssrLoadModule(entryId(file)));
-		results.push(run === null ? {
-			machines: [],
-			warnings: [`${file}: could not load the inspector`]
-		} : await run({ fuzz: context.fuzz }));
-	}
-	return {
-		text: serializeViz(vizDocument(results.flatMap((result) => result.machines))),
-		warnings: results.flatMap((result) => result.warnings)
-	};
-}
-function mantaqViz(options) {
-	const base = (options.base ?? "/__mantaq/").replace(/\/?$/, "/");
-	const patterns = Array.isArray(options.machines) ? options.machines : [options.machines];
-	const fuzz = options.fuzz ?? { iterations: DEV_ITERATIONS };
-	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
-		},
-		{
-			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
-					});
-				});
-				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);
-					});
-				});
-				server.httpServer?.once("listening", () => {
-					server.config.logger.info(`  mantaq viz: ${base}`);
-				});
-			}
-		}
-	];
-}
-export { toViz as C, shrink as S, guidance as _, targetsSource as a, withTestCoverage as b, inspect as c, vizDocument as d, analyzeModule as f, branchDistanceGuide as g, branchDistance as h, mantaqViz as i, inspectModule as l, annotateMachine as m, TARGETS as n, inlineConfig as o, analyzeSource as p, TARGETS_RESOLVED as r, inspectFile as s, STYLESHEETS as t, machineId as u, literalPool as v, toVizMachine as w, fuzz as x, fuzzedMachine as y };
+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 };

package/dist/vite.mjs

@@ -1 +1,159 @@
-export { t as STYLESHEETS, n as TARGETS, r as TARGETS_RESOLVED, i as mantaqViz, a as targetsSource } from "./vite-BBW0CmYr.mjs";
+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 { 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 { fileURLToPath } from "node:url";
+import { searchForWorkspaceRoot } from "vite";
+// src/vite.ts
+/**
+* Vite plugin: a live page of your machines on your own dev server.
+*
+*   // vite.config.ts
+*   import { mantaqViz } from "@mantaq/inspect/vite";
+*   export default defineConfig({ plugins: [mantaqViz({ machines: "src/**\/*.machine.ts" })] });
+*
+* 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.
+*/
+const STYLESHEETS = ["@mantaq/viz/viewer.css", "@mantaq/viz/page.css"];
+const DEV_ITERATIONS = 500;
+const TARGETS = "virtual:mantaq/targets";
+const TARGETS_RESOLVED = `\0${TARGETS}`;
+function createExpression(found, index) {
+	const callee = `m${index}[${JSON.stringify(found.name)}]`;
+	const call = found.call === "clock" ? `${callee}(VirtualClock())` : found.call === "options" ? `${callee}({ clock: VirtualClock() })` : `${callee}()`;
+	return found.unwrap === "actor" ? `${call}.actor` : call;
+}
+/**
+* Source of `virtual:mantaq/targets`: one factory per exported actor factory,
+* shaped by its type (`call`, `clock`, `options`). A bare actor export cannot
+* be recreated, so it gets none. Like the server-side inspection, plain actors
+* are skipped when a file has factories.
+*/
+function targetsSource(files) {
+	const core = fileURLToPath(import.meta.resolve("@mantaq/core"));
+	const imports = [];
+	const entries = [];
+	files.forEach((file, index) => {
+		const analysis = analyzeModule({
+			file,
+			root: projectRoot(file)
+		});
+		if (Either.isLeft(analysis)) return;
+		const factories = analysis[1].machines.filter((found) => found.call !== "instance");
+		if (factories.length === 0) return;
+		imports.push(`import * as m${index} from ${JSON.stringify(file)};`);
+		for (const found of factories) entries.push(`  ${JSON.stringify(machineId(found.name))}: () => { const actor = ${createExpression(found, index)}; return { actor, clock: actor.clock }; },`);
+	});
+	return [
+		`import { VirtualClock } from ${JSON.stringify(core)};`,
+		...imports,
+		"export const targets = {",
+		...entries,
+		"};"
+	].join("\n");
+}
+function machineFiles(root, patterns) {
+	const files = patterns.flatMap((pattern) => globSync(pattern, { cwd: root }));
+	return [...new Set(files.map((file) => isAbsolute(file) ? file : resolve(root, file)))].sort();
+}
+async function documentText(server, context) {
+	const results = [];
+	for (const file of context.files) {
+		const run = runOf(await server.ssrLoadModule(entryId(file)));
+		results.push(run === null ? {
+			machines: [],
+			warnings: [`${file}: could not load the inspector`]
+		} : await run({ fuzz: context.fuzz }));
+	}
+	return {
+		text: serializeViz(vizDocument(results.flatMap((result) => result.machines))),
+		warnings: results.flatMap((result) => result.warnings)
+	};
+}
+function mantaqViz(options) {
+	const base = (options.base ?? "/__mantaq/").replace(/\/?$/, "/");
+	const patterns = Array.isArray(options.machines) ? options.machines : [options.machines];
+	const fuzz = options.fuzz ?? { iterations: DEV_ITERATIONS };
+	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
+		},
+		{
+			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
+					});
+				});
+				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);
+					});
+				});
+				server.httpServer?.once("listening", () => {
+					server.config.logger.info(`  mantaq viz: ${base}`);
+				});
+			}
+		}
+	];
+}
+export { STYLESHEETS, TARGETS, TARGETS_RESOLVED, mantaqViz, targetsSource };

package/package.json

@@ -1,16 +1,13 @@
 {
   "name": "@mantaq/inspect",
-  "version": "0.3.0",
-  "description": "Turn a Mantaq machine into a viz document: structure, handler explanations (AST), fuzz and test coverage. CLI and Vite plugin included.",
+  "version": "0.4.0",
+  "description": "Turn a Mantaq machine into a viz document: structure, handler explanations (AST), fuzz and test coverage. Vite plugin included.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/AndersCan/mantaq",
     "directory": "packages/inspect"
   },
-  "bin": {
-    "mantaq-inspect": "./dist/cli.mjs"
-  },
   "files": [
     "dist"
   ],
@@ -18,7 +15,6 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./drive": "./dist/drive.mjs",
-    "./live-embedded": "./dist/live-embedded.mjs",
     "./live-entry": "./dist/live-entry.mjs",
     "./vite": "./dist/vite.mjs",
     "./package.json": "./package.json"
@@ -28,11 +24,11 @@
   },
   "dependencies": {
     "typescript": "6.0.3",
-    "@mantaq/core": "0.5.3",
-    "@mantaq/traversal": "0.3.3",
-    "@mantaq/viz": "0.2.3",
-    "@mantaq/pbt": "0.0.4",
-    "@mantaq/utils": "0.0.5"
+    "@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"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
@@ -40,7 +36,7 @@
     "happy-dom": "^21.0.4",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
     "vite-plus": "1.4.0",
-    "@mantaq/sugar": "2.0.3"
+    "@mantaq/sugar": "2.0.4"
   },
   "peerDependencies": {
     "vite": "*"

package/dist/cli.d.mts

@@ -1 +0,0 @@
-export {}

package/dist/cli.mjs

@@ -1,152 +0,0 @@
-#!/usr/bin/env node
-import { a as targetsSource, d as vizDocument, o as inlineConfig, r as TARGETS_RESOLVED, s as inspectFile } from "./vite-BBW0CmYr.mjs";
-import { t as htmlPage } from "./page-CK7-IsLJ.mjs";
-import { serializeViz } from "@mantaq/viz";
-import { Either } from "@mantaq/utils";
-import { basename, resolve } from "node:path";
-import { SEED_ENV, parseSeed } from "@mantaq/pbt";
-import { writeFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { build } from "vite";
-import { spawn } from "node:child_process";
-import { parseArgs } from "node:util";
-// src/live-html.ts
-/**
-* The live page as one classic script: the viewer, the driver and every
-* exported factory of `files`, built with the project's Vite config.
-*/
-async function liveBundle(files, load) {
-	const entry = fileURLToPath(import.meta.resolve(import.meta.url.endsWith(".ts") ? "./live-embedded.ts" : "./live-embedded.mjs"));
-	const targets = {
-		name: "mantaq-live-targets",
-		resolveId: (id) => id === "virtual:mantaq/targets" ? TARGETS_RESOLVED : null,
-		load: (id) => id === "\0virtual:mantaq/targets" ? targetsSource(files) : null
-	};
-	const inline = await inlineConfig(load);
-	const output = await build({
-		...inline,
-		logLevel: "silent",
-		plugins: [...inline.plugins ?? [], targets],
-		build: {
-			write: false,
-			minify: true,
-			cssCodeSplit: false,
-			lib: {
-				entry,
-				formats: ["iife"],
-				name: "MantaqLive",
-				fileName: () => "live.js"
-			}
-		}
-	});
-	return (Array.isArray(output) ? output : [output]).flatMap((each) => "output" in each ? each.output : []).flatMap((file) => file.type === "chunk" ? [file.code] : []).join("\n");
-}
-// src/cli.ts
-/**
-* mantaq-inspect: draw the machines a file exports.
-*
-*   mantaq-inspect <file.ts>... [--out FILE] [--json] [--live] [--no-fuzz] [--iterations N] [--config FILE]
-*                  [--mode MODE] [--no-open] [--check]
-*
-* Finds every exported actor or actor factory from the file's types, reads
-* handler explanations and sample payloads from the source, fuzzes each
-* machine that runs on a VirtualClock, and writes one self-contained HTML page
-* (default `mantaq-viz.html`) that opens without a server. `--json` writes the
-* viz document instead. `--live` bundles the machine files into the page, so its
-* steps run the real actors (factories on a VirtualClock) with no server. `--config` loads the files with that Vite config (env,
-* aliases, plugins) and `--mode` picks its mode. `--check` exits 1 if any warning was printed or
-* fuzzing found a handler error (each printed as `error:`). Seed: MANTAQ_SEED (default from @mantaq/pbt).
-*/
-const USAGE = "usage: mantaq-inspect <file.ts>... [--out FILE] [--json] [--live] [--no-fuzz] [--iterations N] [--config FILE] [--mode MODE] [--no-open] [--check]\n";
-function loadOptions(config, mode) {
-	return {
-		...config === void 0 ? {} : { config: resolve(config) },
-		...mode === void 0 ? {} : { mode }
-	};
-}
-function fuzzSettings(iterationsArg, off) {
-	const iterations = Number(iterationsArg ?? 2e3);
-	if (!Number.isInteger(iterations) || iterations < 0) return Either.left("bad --iterations");
-	const seed = parseSeed(process.env[SEED_ENV]);
-	if (Either.isLeft(seed)) return Either.left(seed[0].message);
-	const settings = off ? false : {
-		seed: seed[1],
-		iterations
-	};
-	return Either.right(settings);
-}
-function parse() {
-	const parsed = Either.from(() => parseArgs({
-		allowPositionals: true,
-		options: {
-			out: { type: "string" },
-			json: { type: "boolean" },
-			live: { type: "boolean" },
-			iterations: { type: "string" },
-			config: { type: "string" },
-			mode: { type: "string" },
-			"no-fuzz": { type: "boolean" },
-			"no-open": { type: "boolean" },
-			check: { type: "boolean" }
-		}
-	}));
-	if (Either.isLeft(parsed)) return Either.left(String(parsed[0]));
-	const { positionals, values } = parsed[1];
-	if (positionals.length === 0) return Either.left("no file given");
-	const json = values.json === true;
-	const live = values.live === true;
-	if (live && json) return Either.left("--live and --json cannot be combined");
-	const fuzz = fuzzSettings(values.iterations, values["no-fuzz"] === true);
-	if (Either.isLeft(fuzz)) return Either.left(fuzz[0]);
-	return Either.right({
-		files: positionals.map((file) => resolve(file)),
-		out: resolve(values.out ?? (json ? "mantaq-viz.json" : "mantaq-viz.html")),
-		json,
-		live,
-		fuzz: fuzz[1],
-		check: values.check === true,
-		load: loadOptions(values.config, values.mode),
-		open: values["no-open"] !== true && !json && process.stdout.isTTY === true
-	});
-}
-function openInBrowser(path) {
-	const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
-	spawn(command, [path], {
-		stdio: "ignore",
-		detached: true
-	}).on("error", () => {}).unref();
-}
-function checkFails(results, machines) {
-	const errors = machines.flatMap((machine) => (machine.fuzz?.errors ?? []).map((error) => `${machine.id}: ${error.from} -${error.event}-> ${error.message}`));
-	for (const error of errors) process.stderr.write(`error: ${error}\n`);
-	return errors.length > 0 || results.some((result) => result.warnings.length > 0);
-}
-async function main() {
-	const options = parse();
-	if (Either.isLeft(options)) {
-		process.stderr.write(`${options[0]}\n${USAGE}`);
-		process.exitCode = 1;
-		return;
-	}
-	const { files, out, json, live, fuzz, open, check, load } = options[1];
-	const results = [];
-	for (const file of files) results.push(await inspectFile(file, { fuzz }, load));
-	for (const warning of results.flatMap((result) => result.warnings)) process.stderr.write(`warning: ${warning}\n`);
-	const failed = results.some((result) => result.failed);
-	if (failed) process.exitCode = 1;
-	const machines = results.flatMap((result) => result.machines);
-	if (check && checkFails(results, machines)) process.exitCode = 1;
-	if (machines.length === 0) {
-		if (!failed) process.stderr.write("no machines found\n");
-		process.exitCode = 1;
-		return;
-	}
-	const document = vizDocument(machines);
-	const title = `${files.map((file) => basename(file)).join(", ")} · mantaq viz`;
-	const liveScript = live ? await liveBundle(files, load) : void 0;
-	writeFileSync(out, json ? serializeViz(document) : await htmlPage(document, title, liveScript));
-	process.stdout.write(`wrote ${out} (${machines.map((machine) => machine.id).join(", ")})\n`);
-	if (open) openInBrowser(out);
-}
-main();
-export {};

package/dist/live-embedded.d.mts

@@ -1 +0,0 @@
-export {}

package/dist/live-embedded.mjs

@@ -1,16 +0,0 @@
-import { t as mountDriven } from "./live-page-DEDl_Nio.mjs";
-import { DOCUMENT_ELEMENT_ID } from "@mantaq/viz";
-import { targets } from "virtual:mantaq/targets";
-// src/live-embedded.ts
-/**
-* Entry of the standalone live page `mantaq-inspect --live` writes: the viz
-* document sits in the page, the machines are bundled in, nothing is fetched.
-*/
-const root = document.querySelector("#app");
-const text = document.getElementById(DOCUMENT_ELEMENT_ID)?.textContent;
-if (root && text) mountDriven(root, {
-	source: "this page",
-	text,
-	targets
-});
-export {};

package/dist/live-page-DEDl_Nio.mjs

@@ -1,85 +0,0 @@
-import { createDriver } from "./drive.mjs";
-import { parseViz } from "@mantaq/viz";
-import { Either } from "@mantaq/utils";
-import { mountViewer, showIssues } from "@mantaq/viz/viewer";
-import { linkOptions } from "@mantaq/viz/page";
-// src/live-page.ts
-/**
-* The live page of the Vite plugin: the served document, with each machine
-* that has a target running for real behind the viewer. The walk lives in the
-* address bar (`?machine=&step=`), so a redraw after a save replays it on the
-* new code.
-*/
-/** A document holding only `machine`, so the viewer shows the machine its driver runs. */
-function only(viz, machine) {
-	const chosen = viz.machines.find((each) => each.id === machine) ?? viz.machines[0];
-	return {
-		...viz,
-		machines: chosen === void 0 ? [] : [chosen]
-	};
-}
-/** Mount the document at `text`; machines with a target run live, the rest stay static walks. */
-function mountDriven(root, context) {
-	const parsed = parseViz(context.text);
-	if (Either.isLeft(parsed)) {
-		showIssues(root, {
-			source: context.source,
-			issues: parsed[0]
-		});
-		return;
-	}
-	const options = linkOptions();
-	const viz = parsed[1];
-	const shown = only(viz, options.machine ?? null);
-	const id = shown.machines[0]?.id ?? "";
-	const target = context.targets[id];
-	const create = target !== void 0 && typeof Reflect.get(target().clock, "advance") === "function" ? target : void 0;
-	const picker = viz.machines.length > 1;
-	const select = (machine) => {
-		const next = new URLSearchParams(location.search);
-		next.set("machine", machine);
-		next.delete("step");
-		history.replaceState(null, "", `?${next.toString()}`);
-		mountDriven(root, context);
-	};
-	const doc = root.ownerDocument;
-	const bar = doc.createElement("nav");
-	bar.className = "machines";
-	if (picker) for (const machine of viz.machines) {
-		const button = doc.createElement("button");
-		button.type = "button";
-		button.textContent = machine.id;
-		button.disabled = machine.id === id;
-		button.addEventListener("click", () => select(machine.id));
-		bar.append(button);
-	}
-	const viewer = doc.createElement("div");
-	root.replaceChildren(...picker ? [bar] : [], viewer);
-	mountViewer(viewer, shown, {
-		...options,
-		...create === void 0 ? {} : { driver: createDriver({
-			id,
-			create
-		}) }
-	});
-}
-/** Fetch the document from `source` and mount it; call again to redraw, keeping the walk. */
-async function mountLiveDriven(root, context) {
-	const response = await fetch(context.source).catch(() => null);
-	if (response === null || !response.ok) {
-		const status = response === null ? "network error" : `HTTP ${response.status}`;
-		showIssues(root, {
-			source: context.source,
-			issues: [{
-				path: "$",
-				message: status
-			}]
-		});
-		return;
-	}
-	mountDriven(root, {
-		...context,
-		text: await response.text()
-	});
-}
-export { mountLiveDriven as n, mountDriven as t };

package/dist/page-CK7-IsLJ.mjs

@@ -1,41 +0,0 @@
-import { t as STYLESHEETS } from "./vite-BBW0CmYr.mjs";
-import { serializeViz, standaloneHtml } from "@mantaq/viz";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { build } from "vite";
-// src/page.ts
-/** The viewer as one classic script, built from `@mantaq/viz/standalone`. */
-async function viewerScript() {
-	const entry = fileURLToPath(import.meta.resolve("@mantaq/viz/standalone"));
-	const output = await build({
-		configFile: false,
-		logLevel: "silent",
-		build: {
-			write: false,
-			minify: true,
-			cssCodeSplit: false,
-			lib: {
-				entry,
-				formats: ["iife"],
-				name: "MantaqViz",
-				fileName: () => "viz.js"
-			}
-		}
-	});
-	return (Array.isArray(output) ? output : [output]).flatMap((each) => "output" in each ? each.output : []).flatMap((file) => file.type === "chunk" ? [file.code] : []).join("\n");
-}
-/**
-* A self-contained HTML page for `document`: open it from disk, attach it, commit it.
-* With `live` (a built script that drives the machines), that script replaces the static viewer.
-*/
-async function htmlPage(document, title, live) {
-	const css = STYLESHEETS.map((id) => readFileSync(fileURLToPath(import.meta.resolve(id)), "utf8")).join("\n");
-	const script = live ?? await viewerScript();
-	return standaloneHtml({
-		title,
-		script,
-		css,
-		document: serializeViz(document)
-	});
-}
-export { htmlPage as t };