@mantaq/inspect 0.1.0 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@ It finds every exported actor, or function that builds one, from the file's type
 
 ## Three ways in
 
-**CLI**: `mantaq-inspect <file.ts>... [--out FILE] [--json] [--no-fuzz] [--iterations N] [--no-open]`. `--json` writes the viz document instead of the page. Seed: `MANTAQ_SEED` (default from `@mantaq/pbt`). Same seed → same output.
+**CLI**: `mantaq-inspect <file.ts>... [--out FILE] [--json] [--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. Seed: `MANTAQ_SEED` (default from `@mantaq/pbt`). Same seed → same output.
 
 **Vite plugin**: a live page on your dev server that redraws, keeping your walk, when you save.
 
@@ -47,6 +47,7 @@ const json = serializeViz(vizDocument([machine]));
 
 - **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 `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.

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as vizDocument, r as inspectFile } from "./load-C4rGWmGU.mjs";
+import { l as vizDocument, r as inspectFile } from "./load-DOwsxTyL.mjs";
 import { t as htmlPage } from "./page-rr9IQ-4k.mjs";
 import { serializeViz } from "@mantaq/viz";
 import { Either } from "@mantaq/utils";
@@ -12,15 +12,24 @@ import { parseArgs } from "node:util";
 /**
 * mantaq-inspect: draw the machines a file exports.
 *
-*   mantaq-inspect <file.ts>... [--out FILE] [--json] [--no-fuzz] [--iterations N] [--no-open]
+*   mantaq-inspect <file.ts>... [--out FILE] [--json] [--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. Seed: MANTAQ_SEED (default from @mantaq/pbt).
+* viz document instead. `--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] [--no-fuzz] [--iterations N] [--no-open]\n";
+const USAGE = "usage: mantaq-inspect <file.ts>... [--out FILE] [--json] [--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 parse() {
 	const parsed = Either.from(() => parseArgs({
 		allowPositionals: true,
@@ -28,8 +37,11 @@ function parse() {
 			out: { type: "string" },
 			json: { type: "boolean" },
 			iterations: { type: "string" },
+			config: { type: "string" },
+			mode: { type: "string" },
 			"no-fuzz": { type: "boolean" },
-			"no-open": { type: "boolean" }
+			"no-open": { type: "boolean" },
+			check: { type: "boolean" }
 		}
 	}));
 	if (Either.isLeft(parsed)) return Either.left(String(parsed[0]));
@@ -49,6 +61,8 @@ function parse() {
 		out: resolve(values.out ?? (json ? "mantaq-viz.json" : "mantaq-viz.html")),
 		json,
 		fuzz,
+		check: values.check === true,
+		load: loadOptions(values.config, values.mode),
 		open: values["no-open"] !== true && !json && process.stdout.isTTY === true
 	});
 }
@@ -59,6 +73,11 @@ function openInBrowser(path) {
 		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)) {
@@ -66,13 +85,16 @@ async function main() {
 		process.exitCode = 1;
 		return;
 	}
-	const { files, out, json, fuzz, open } = options[1];
+	const { files, out, json, fuzz, open, check, load } = options[1];
 	const results = [];
-	for (const file of files) results.push(await inspectFile(file, { fuzz }));
+	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) {
-		process.stderr.write("no machines found\n");
+		if (!failed) process.stderr.write("no machines found\n");
 		process.exitCode = 1;
 		return;
 	}

package/dist/drive.d.mts

@@ -0,0 +1,7 @@
+import { t as FuzzTarget } from "./run-BLt0mwXe.mjs";
+import { VizDriver } from "@mantaq/viz";
+/**
+ * A running actor for the viewer. Steps go through the same function the
+ * fuzzer replays with, so live and fuzzed behaviour cannot drift. No node APIs.
+ */
+export declare function createDriver(target: FuzzTarget): VizDriver;

package/dist/drive.mjs

@@ -0,0 +1,92 @@
+import { a as messageOf, n as contextText, o as parsed, r as eventCatalog, t as applyStep } from "./run-B5huYj_r.mjs";
+// src/drive.ts
+function json(text) {
+	return parsed(text);
+}
+/**
+* A running actor for the viewer. Steps go through the same function the
+* fuzzer replays with, so live and fuzzed behaviour cannot drift. No node APIs.
+*/
+function createDriver(target) {
+	let session = start(target);
+	function start(from) {
+		const { actor, clock } = from.create();
+		const internal = new Set(eventCatalog(actor).internal);
+		const seen = { last: null };
+		const steps = [];
+		actor.on("transition", { fn: ({ event, from: before, to, transitioned, effects }) => {
+			seen.last = {
+				from: before,
+				event: event.type,
+				to,
+				outcome: transitioned ? "transition" : "stay",
+				effects,
+				context: json(contextText(actor)),
+				error: null
+			};
+		} });
+		actor.on("error", { fn: (info) => {
+			const error = messageOf(info.error);
+			seen.last = {
+				from: info.state.name,
+				event: info.event.type,
+				to: actor.state.name,
+				outcome: "stay",
+				effects: [],
+				context: json(contextText(actor)),
+				error
+			};
+		} });
+		return {
+			actor,
+			clock,
+			internal,
+			seen,
+			steps
+		};
+	}
+	function view() {
+		const { actor, clock, steps, seen } = session;
+		return {
+			state: actor.state.name,
+			steps: [...steps],
+			last: seen.last,
+			timers: clock.pendingTimers().map((timer) => ({
+				id: String(timer.id),
+				ms: timer.ms,
+				deadline: timer.deadline,
+				eventName: timer.eventName ?? null
+			})),
+			context: json(contextText(actor))
+		};
+	}
+	return {
+		reset() {
+			session.actor.dispose();
+			session = start(target);
+			return view();
+		},
+		step(step) {
+			const { actor, clock, internal, seen, steps } = session;
+			seen.last = null;
+			const before = actor.state.name;
+			applyStep(actor, {
+				step,
+				clock,
+				internal
+			});
+			steps.push(step);
+			if (seen.last === null && step.kind === "event") seen.last = {
+				from: before,
+				event: step.event,
+				to: before,
+				outcome: "ignored",
+				effects: [],
+				context: json(contextText(actor)),
+				error: null
+			};
+			return view();
+		}
+	};
+}
+export { createDriver };

package/dist/index.d.mts

@@ -1,8 +1,9 @@
+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 { VizComparison, VizDocument, VizExplanation, VizFuzzError, VizJson, VizMachine, VizStep } from "@mantaq/viz";
 import { History } from "@mantaq/traversal";
 import { Either } from "@mantaq/utils";
-import { AnyActor, VirtualClock } from "@mantaq/core";
+import { AnyActor } from "@mantaq/core";
 import { Plugin } from "vite";
 interface VizInput {
   id: string;
@@ -23,63 +24,6 @@ interface LiteralPool {
   numbers: number[];
   strings: string[];
 }
-/** A machine the fuzzer can drive: a fresh actor plus the virtual clock it runs on. */
-interface FuzzTarget {
-  id: string;
-  create(): {
-    actor: AnyActor<unknown>;
-    clock: VirtualClock;
-  };
-  /**
-   * Sample payloads per event type. Payload types are erased at runtime, so
-   * the fuzzer only mutates shapes it was given. Events without samples are
-   * sent without a payload.
-   */
-  payloads?: Readonly<Record<string, ReadonlyArray<VizJson>>>;
-}
-interface Observation {
-  from: string;
-  event: string;
-  to: string;
-  transitioned: boolean;
-  /** Names of the effects that ran on entry into `to`. */
-  effects: string[];
-  /** Index of the step that caused it. */
-  step: number;
-  /** Payload the handler received (for branch-distance guidance). */
-  payload: unknown;
-  /** JSON copy of the actor context right after the handler ran; null if not JSON. */
-  context: unknown;
-}
-interface RunError {
-  from: string;
-  event: string;
-  message: string;
-  /** Index of the step that triggered it. */
-  step: number;
-}
-interface Trace {
-  visited: string[];
-  observations: Observation[];
-  errors: RunError[];
-  /** Indices of steps after which the actor context differed: loop candidates. */
-  contextSteps: number[];
-  /**
-   * Coverage features, sorted: `state:x`, `edge:a>e>b` (state changed or
-   * re-entered), `stay:a>e` (handled, no change), `error:a>e` (handler threw).
-   */
-  features: string[];
-}
-/** Declared inputs and internal events, each sorted. */
-export declare function eventCatalog(actor: AnyActor<unknown>): {
-  inputs: string[];
-  internal: string[];
-};
-/**
- * Replay steps against a fresh actor. Synchronous and deterministic: effects
- * only run via the virtual clock, and nothing here reads wall time.
- */
-export declare function execute(target: FuzzTarget, steps: ReadonlyArray<VizStep>): Trace;
 interface FuzzOptions {
   seed: number;
   iterations: number;
@@ -169,12 +113,16 @@ interface HandlerSite {
   state: string | null;
   event: string;
   explanation: VizExplanation;
+  /** Leading JSDoc of the registration. null = undocumented. */
+  doc: string | null;
 }
 /** Explain every handler registration in a file. Left = the file could not be analyzed at all. */
 export declare function analyzeSource(source: AnalysisSource): Either<string, HandlerSite[]>;
 /** Everything one type-check of a machine file yields. */
 interface ModuleAnalysis {
   sites: HandlerSite[];
+  stateDocs: ReadonlyMap<string, string>;
+  eventDocs: ReadonlyMap<string, string>;
   payloads: Record<string, VizJson[]>;
   machines: MachineExport[];
 }
@@ -188,8 +136,17 @@ export declare function analyzeModule(source: AnalysisSource): Either<string, Mo
 export declare function annotateMachine(machine: VizMachine, source: AnalysisSource): VizMachine;
 /** Options `inspectFile` passes through to `inspectModule`; loading is its job. */
 type FileOptions = Omit<ModuleOptions, "load">;
+/** An inspected file; `failed` when it could not be loaded at all (its warnings say why). */
+type LoadedFile = InspectedModule & {
+  failed: boolean;
+};
+/** Which Vite config and mode load the file; without a config, no project config is read. */
+interface LoadOptions {
+  config?: string;
+  mode?: string;
+}
 /** Load `file` with Vite (TS, tsconfig paths, extensionless imports) and inspect its machines. */
-export declare function inspectFile(file: string, options?: FileOptions): Promise<InspectedModule>;
+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. */
 export declare function htmlPage(document: VizDocument, title: 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, inspect, inspectModule, machineId, vizDocument };
+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 };

package/dist/index.mjs

@@ -1,3 +1,4 @@
-import { C as toVizMachine, S as toViz, _ as withTestCoverage, a as inspect, b as eventCatalog, c as vizDocument, d as annotateMachine, f as branchDistance, g as fuzzedMachine, h as literalPool, l as analyzeModule, m as guidance, o as inspectModule, p as branchDistanceGuide, r as inspectFile, s as machineId, u as analyzeSource, v as fuzz, x as execute, y as shrink } from "./load-C4rGWmGU.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-DOwsxTyL.mjs";
+import { i as execute, r as eventCatalog } from "./run-B5huYj_r.mjs";
 import { t as htmlPage } from "./page-rr9IQ-4k.mjs";
 export { analyzeModule, analyzeSource, annotateMachine, branchDistance, branchDistanceGuide, eventCatalog, execute, fuzz, fuzzedMachine, guidance, htmlPage, inspect, inspectFile, inspectModule, literalPool, machineId, shrink, toViz, toVizMachine, vizDocument, withTestCoverage };

package/dist/live-entry.d.mts

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

package/dist/live-entry.mjs

@@ -0,0 +1,106 @@
+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
+* server reports a change, and when the machine code itself hot-updates.
+*/
+const root = document.querySelector("#app");
+const source = root?.dataset["src"];
+const current = { targets };
+if (root && source !== void 0) {
+	const draw = () => void mountLiveDriven(root, {
+		source,
+		targets: current.targets
+	});
+	draw();
+	import.meta.hot?.on(UPDATE_EVENT, draw);
+	import.meta.hot?.accept("virtual:mantaq/targets", (module) => {
+		if (module !== void 0) current.targets = module["targets"];
+		draw();
+	});
+}
+export {};

package/dist/{load-C4rGWmGU.mjs → load-DOwsxTyL.mjs}

@@ -1,13 +1,14 @@
+import { i as execute, r as eventCatalog } 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, 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 } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { runnerImport } from "vite";
+import { loadConfigFromFile, loadEnv, runnerImport } from "vite";
 // src/structure.ts
 function byId$1(left, right) {
 	if (left.id < right.id) return -1;
@@ -35,7 +36,8 @@ function toState(node, context) {
 		final: node.isFinal,
 		effects: context.effects.find((edge) => edge.source === node.id)?.effects ?? [],
 		coverage: visits ? hits(visits.get(node.id)) : null,
-		tested: null
+		tested: null,
+		doc: null
 	};
 }
 function edgeKind(edge) {
@@ -91,6 +93,7 @@ function toEdge(edge, transitions) {
 		emits: emitsOf(edge),
 		contexts: [...new Set(edge.contexts)].sort(),
 		explanation: null,
+		doc: null,
 		coverage: transitions && kind === "transition" ? hits(edgeHits$1(edge, transitions)) : null,
 		tested: null
 	};
@@ -112,6 +115,7 @@ function toVizMachine(input) {
 	const events = [...new Set(edges.map((edge) => edge.event).filter(Boolean))].filter((eventId) => !eventId.startsWith("effect:")).sort().map((eventId) => ({
 		id: eventId,
 		internal: internalIds.has(eventId),
+		doc: null,
 		payloadType: null
 	}));
 	const regions = [...new Set(states.flatMap((state) => state.region ? [state.region] : []))].sort();
@@ -330,120 +334,6 @@ function createRng(seed) {
 		chance: (probability) => next() < probability
 	};
 }
-// src/fuzz/run.ts
-const ERROR_STATE = "__error";
-function eventTypes(options, key) {
-	if (typeof options !== "object" || options === null) return [];
-	const list = Reflect.get(options, key);
-	if (!Array.isArray(list)) return [];
-	return list.flatMap((entry) => {
-		if (typeof entry !== "object" || entry === null) return [];
-		const type = Reflect.get(entry, "type");
-		return typeof type === "string" ? [type] : [];
-	});
-}
-/** Declared inputs and internal events, each sorted. */
-function eventCatalog(actor) {
-	return {
-		inputs: eventTypes(actor.options, "inputs").sort(),
-		internal: eventTypes(actor.options, "internal").sort()
-	};
-}
-/** onAny handlers live under this key in the dispatch map (core builder). */
-const ANY_KEY = "Any";
-function handles(actor, event) {
-	const transitions = actor.options?.transitions;
-	return transitions?.[actor.state.name]?.[event] !== void 0 || transitions?.[ANY_KEY]?.[event] !== void 0;
-}
-function toEvent(step) {
-	return step.payload === null ? { type: step.event } : {
-		type: step.event,
-		payload: step.payload
-	};
-}
-function messageOf(error) {
-	return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-}
-function featuresOf(trace) {
-	const features = /* @__PURE__ */ new Set();
-	for (const state of trace.visited) features.add(`state:${state}`);
-	for (const seen of trace.observations) features.add(seen.transitioned ? `edge:${seen.from}>${seen.event}>${seen.to}` : `stay:${seen.from}>${seen.event}`);
-	for (const error of trace.errors) features.add(`error:${error.from}>${error.event}`);
-	return [...features].sort();
-}
-/** JSON text of the context, or null when it is not serializable (functions, cycles). */
-function contextText(actor) {
-	const text = Either.from(() => JSON.stringify(actor.context ?? null));
-	return Either.isRight(text) ? text[1] : null;
-}
-function parsed(text) {
-	return text === null ? null : JSON.parse(text);
-}
-function dispatch(actor, context) {
-	const { step } = context;
-	if (step.kind === "advance") context.clock.advance(step.ms);
-	else if (context.internal.has(step.event)) {
-		if (handles(actor, step.event)) actor.inject(toEvent(step));
-	} else actor.send(toEvent(step));
-}
-/**
-* Replay steps against a fresh actor. Synchronous and deterministic: effects
-* only run via the virtual clock, and nothing here reads wall time.
-*/
-function execute(target, steps) {
-	const { actor, clock } = target.create();
-	const internal = new Set(eventCatalog(actor).internal);
-	const visited = [actor.state.name];
-	const observations = [];
-	const errors = [];
-	const contextSteps = [];
-	let index = 0;
-	actor.on("transition", { fn: ({ event, from, to, transitioned, effects }) => {
-		const context = parsed(contextText(actor));
-		observations.push({
-			from,
-			event: event.type,
-			to,
-			transitioned,
-			effects,
-			step: index,
-			payload: event.payload,
-			context
-		});
-		if (transitioned) visited.push(to);
-	} });
-	actor.on("error", { fn: (info) => {
-		errors.push({
-			from: info.state.name,
-			event: info.event.type,
-			message: messageOf(info.error),
-			step: index
-		});
-	} });
-	for (const step of steps) {
-		if (actor.state.name === ERROR_STATE) break;
-		const before = contextText(actor);
-		dispatch(actor, {
-			step,
-			clock,
-			internal
-		});
-		if (contextText(actor) !== before) contextSteps.push(index);
-		index += 1;
-	}
-	actor.dispose();
-	return {
-		visited,
-		observations,
-		errors,
-		contextSteps,
-		features: featuresOf({
-			visited,
-			observations,
-			errors
-		})
-	};
-}
 // src/fuzz/fuzz.ts
 function covers(target, steps, wanted) {
 	const reached = new Set(execute(target, steps).features);
@@ -605,6 +495,7 @@ function fuzzEdge(seen, from) {
 		emits: [],
 		contexts: [],
 		explanation: null,
+		doc: null,
 		coverage: null,
 		tested: null
 	};
@@ -650,6 +541,7 @@ function fuzzedMachine(target, result) {
 	const events = [...base.events, ...[...new Set(added.map((edge) => edge.event))].filter((id) => !known.has(id)).map((id) => ({
 		id,
 		internal: internal.has(id),
+		doc: null,
 		payloadType: null
 	}))].sort(byId);
 	return {
@@ -874,6 +766,33 @@ function machineExports(loaded) {
 	}).sort((left, right) => left.at - right.at).map(({ found }) => found);
 }
 // src/ast/program.ts
+/**
+* Prose of the JSDoc block found in the trivia starting at `pos`, or null when
+* there is none. Block tags (`@param`, ...) and everything after them are cut;
+* `{@link x}` reads as `x`.
+*/
+function docAt(sourceFile, pos) {
+	const block = (ts.getLeadingCommentRanges(sourceFile.text, pos) ?? []).filter((range) => sourceFile.text.startsWith("/**", range.pos)).at(-1);
+	if (block === void 0) return null;
+	const lines = sourceFile.text.slice(block.pos + 3, block.end - 2).split(/\r?\n/).map((line) => line.replace(/^\s*\* ?/, "").trim());
+	const tag = lines.findIndex((line) => line.startsWith("@"));
+	const text = (tag === -1 ? lines : lines.slice(0, tag)).join("\n").replace(/\{@link(?:code|plain)?\s+([^}|\s]+)[^}]*\}/g, "$1").trim();
+	return text === "" ? null : text;
+}
+function docOf(node) {
+	return docAt(node.getSourceFile(), node.getFullStart());
+}
+/**
+* Doc of one `m.on(...)` link. The first link of a chain owns the comment above
+* the statement; later links own the comment just before their `.on`.
+*/
+function callDoc(call) {
+	const callee = call.expression;
+	if (ts.isPropertyAccessExpression(callee) && ts.isCallExpression(callee.expression)) return docAt(call.getSourceFile(), callee.expression.end);
+	let top = call;
+	while (ts.isPropertyAccessExpression(top.parent) || ts.isCallExpression(top.parent)) top = top.parent;
+	return docOf(ts.isExpressionStatement(top.parent) ? top.parent : call);
+}
 function compilerOptions(source) {
 	const configPath = source.tsconfig ?? ts.findConfigFile(dirname(source.file), (path) => ts.sys.fileExists(path));
 	if (configPath === void 0) return {
@@ -914,7 +833,8 @@ function toRegistration(checker, call) {
 		event: literalProperty(checker, eventRef, "type"),
 		eventRef,
 		handler: property(options, "handler"),
-		call
+		call,
+		doc: callDoc(call)
 	};
 }
 function locationOf(node, root) {
@@ -926,6 +846,27 @@ function locationOf(node, root) {
 		column: position.character + 1
 	};
 }
+/** Name literal of `state("x")()` / `event("X")()`, with which builder it came from. */
+function declaredName(init) {
+	if (!ts.isCallExpression(init) || !ts.isCallExpression(init.expression)) return null;
+	const builder = init.expression.expression;
+	const [name] = init.expression.arguments;
+	if (!ts.isIdentifier(builder) || name === void 0 || !ts.isStringLiteralLike(name)) return null;
+	return {
+		builder: builder.text,
+		name: name.text
+	};
+}
+function collectDeclarationDocs(statement, docs) {
+	const doc = docOf(statement);
+	if (doc === null) return;
+	for (const declaration of statement.declarationList.declarations) {
+		const declared = declaration.initializer && declaredName(declaration.initializer);
+		if (!declared) continue;
+		if (declared.builder === "state") docs.stateDocs.set(declared.name, doc);
+		if (declared.builder === "event") docs.eventDocs.set(declared.name, doc);
+	}
+}
 /**
 * Type-check one file and collect its handler registrations. Any compiler
 * failure becomes a Left reason; it never throws.
@@ -937,9 +878,15 @@ function loadSource(source) {
 		if (sourceFile === void 0) return `source not found: ${source.file}`;
 		const checker = program.getTypeChecker();
 		const registrations = [];
+		const stateDocs = /* @__PURE__ */ new Map();
+		const eventDocs = /* @__PURE__ */ new Map();
 		const visit = (node) => {
 			const found = ts.isCallExpression(node) ? toRegistration(checker, node) : null;
 			if (found) registrations.push(found);
+			if (ts.isVariableStatement(node)) collectDeclarationDocs(node, {
+				stateDocs,
+				eventDocs
+			});
 			ts.forEachChild(node, visit);
 		};
 		visit(sourceFile);
@@ -947,7 +894,9 @@ function loadSource(source) {
 			checker,
 			sourceFile,
 			root: source.root,
-			registrations
+			registrations,
+			stateDocs,
+			eventDocs
 		};
 	});
 	if (Either.isLeft(loaded)) return Either.left(`compiler failed: ${String(loaded[0])}`);
@@ -1477,6 +1426,7 @@ function sitesOf(loaded) {
 		return [{
 			state: registration.state,
 			event: registration.event,
+			doc: registration.doc,
 			explanation: Either.getOrElse(explanation, { onLeft: (error) => ({
 				status: "not_analyzed",
 				location: null,
@@ -1490,10 +1440,17 @@ function sitesOf(loaded) {
 function analyzeSource(source) {
 	return Either.chain(loadSource(source), { onRight: (loaded) => Either.right(sitesOf(loaded)) });
 }
+function docsOf(loaded) {
+	return {
+		sites: sitesOf(loaded),
+		stateDocs: loaded.stateDocs,
+		eventDocs: loaded.eventDocs
+	};
+}
 /** Handlers, payload samples and machine exports of a file, from one TypeScript program. */
 function analyzeModule(source) {
 	return Either.chain(loadSource(source), { onRight: (loaded) => Either.right({
-		sites: sitesOf(loaded),
+		...docsOf(loaded),
 		payloads: payloadSamples(loaded),
 		machines: machineExports(loaded)
 	}) });
@@ -1503,15 +1460,24 @@ function localState(id) {
 	return id.slice(id.lastIndexOf(".") + 1);
 }
 function explain(edge, context) {
-	if (edge.kind === "initial" || edge.kind === "effect") return null;
+	if (edge.kind === "initial" || edge.kind === "effect") return {
+		explanation: null,
+		doc: null
+	};
 	const state = localState(edge.from);
 	const site = context.sites.find((candidate) => candidate.state === state && candidate.event === edge.event) ?? context.sites.find((candidate) => candidate.state === null && candidate.event === edge.event);
-	if (site) return site.explanation;
+	if (site) return {
+		explanation: site.explanation,
+		doc: site.doc
+	};
 	return {
-		status: "not_analyzed",
-		location: null,
-		reason: `no m.on/m.onAny registration for (${state}, ${edge.event}) found in ${context.file}`,
-		snippet: null
+		explanation: {
+			status: "not_analyzed",
+			location: null,
+			reason: `no m.on/m.onAny registration for (${state}, ${edge.event}) found in ${context.file}`,
+			snippet: null
+		},
+		doc: null
 	};
 }
 /**
@@ -1521,7 +1487,7 @@ function explain(edge, context) {
 */
 function annotateMachine(machine, source) {
 	return annotateWith(machine, {
-		analysis: analyzeSource(source),
+		analysis: Either.chain(loadSource(source), { onRight: (loaded) => Either.right(docsOf(loaded)) }),
 		source
 	});
 }
@@ -1539,19 +1505,33 @@ function annotateWith(machine, context) {
 			} : null;
 			return {
 				...edge,
-				explanation
+				explanation,
+				doc: null
 			};
 		}
 		return {
 			...edge,
-			explanation: explain(edge, {
-				sites: analysis[1],
+			...explain(edge, {
+				sites: analysis[1].sites,
 				file
 			})
 		};
 	});
+	if (Either.isLeft(analysis)) return {
+		...machine,
+		edges
+	};
+	const { stateDocs, eventDocs } = analysis[1];
 	return {
 		...machine,
+		states: machine.states.map((state) => ({
+			...state,
+			doc: stateDocs.get(localState(state.id)) ?? null
+		})),
+		events: machine.events.map((event) => ({
+			...event,
+			doc: eventDocs.get(event.id) ?? null
+		})),
 		edges
 	};
 }
@@ -1583,9 +1563,8 @@ function runner(target, payloads) {
 function annotator(target, analysis) {
 	const { source } = target;
 	if (analysis === null || source === void 0) return (machine) => machine;
-	const sites = Either.map(analysis, { onRight: (found) => found.sites });
 	return (machine) => annotateWith(machine, {
-		analysis: sites,
+		analysis,
 		source
 	});
 }
@@ -1734,6 +1713,7 @@ function vizDocument(machines) {
 	};
 }
 // src/load.ts
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
 const ENTRY = "virtual:mantaq-inspect";
 const RESOLVED = `\0${ENTRY}`;
 /**
@@ -1773,18 +1753,88 @@ function runOf(module) {
 	if (typeof run !== "function") return null;
 	return async (options) => Reflect.apply(run, void 0, [options]);
 }
-/** Load `file` with Vite (TS, tsconfig paths, extensionless imports) and inspect its machines. */
-async function inspectFile(file, options = {}) {
-	const { module } = await runnerImport(entryId(file), {
-		configFile: false,
-		logLevel: "silent",
-		plugins: [inspectEntry()]
+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`]
+		warnings: [`${file}: could not load the inspector`],
+		failed: true
+	};
+	return {
+		...await run(options),
+		failed: false
 	};
-	return run(options);
 }
-export { toVizMachine as C, toViz as S, withTestCoverage as _, inspect as a, eventCatalog as b, vizDocument as c, annotateMachine as d, branchDistance as f, fuzzedMachine as g, literalPool as h, runOf as i, analyzeModule as l, guidance as m, inspectEntry as n, inspectModule as o, branchDistanceGuide as p, inspectFile as r, machineId as s, entryId as t, analyzeSource as u, fuzz as v, execute as x, shrink 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/run-B5huYj_r.mjs

@@ -0,0 +1,117 @@
+import { Either } from "@mantaq/utils";
+// src/fuzz/run.ts
+const ERROR_STATE = "__error";
+function eventTypes(options, key) {
+	if (typeof options !== "object" || options === null) return [];
+	const list = Reflect.get(options, key);
+	if (!Array.isArray(list)) return [];
+	return list.flatMap((entry) => {
+		if (typeof entry !== "object" || entry === null) return [];
+		const type = Reflect.get(entry, "type");
+		return typeof type === "string" ? [type] : [];
+	});
+}
+/** Declared inputs and internal events, each sorted. */
+function eventCatalog(actor) {
+	return {
+		inputs: eventTypes(actor.options, "inputs").sort(),
+		internal: eventTypes(actor.options, "internal").sort()
+	};
+}
+/** onAny handlers live under this key in the dispatch map (core builder). */
+const ANY_KEY = "Any";
+function handles(actor, event) {
+	const transitions = actor.options?.transitions;
+	return transitions?.[actor.state.name]?.[event] !== void 0 || transitions?.[ANY_KEY]?.[event] !== void 0;
+}
+function toEvent(step) {
+	return step.payload === null ? { type: step.event } : {
+		type: step.event,
+		payload: step.payload
+	};
+}
+function messageOf(error) {
+	return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+function featuresOf(trace) {
+	const features = /* @__PURE__ */ new Set();
+	for (const state of trace.visited) features.add(`state:${state}`);
+	for (const seen of trace.observations) features.add(seen.transitioned ? `edge:${seen.from}>${seen.event}>${seen.to}` : `stay:${seen.from}>${seen.event}`);
+	for (const error of trace.errors) features.add(`error:${error.from}>${error.event}`);
+	return [...features].sort();
+}
+/** JSON text of the context, or null when it is not serializable (functions, cycles). */
+function contextText(actor) {
+	const text = Either.from(() => JSON.stringify(actor.context ?? null));
+	return Either.isRight(text) ? text[1] : null;
+}
+function parsed(text) {
+	return text === null ? null : JSON.parse(text);
+}
+/** The one step function: the fuzzer and the live driver both apply steps through it. */
+function applyStep(actor, context) {
+	const { step } = context;
+	if (step.kind === "advance") context.clock.advance(step.ms);
+	else if (context.internal.has(step.event)) {
+		if (handles(actor, step.event)) actor.inject(toEvent(step));
+	} else actor.send(toEvent(step));
+}
+/**
+* Replay steps against a fresh actor. Synchronous and deterministic: effects
+* only run via the virtual clock, and nothing here reads wall time.
+*/
+function execute(target, steps) {
+	const { actor, clock } = target.create();
+	const internal = new Set(eventCatalog(actor).internal);
+	const visited = [actor.state.name];
+	const observations = [];
+	const errors = [];
+	const contextSteps = [];
+	let index = 0;
+	actor.on("transition", { fn: ({ event, from, to, transitioned, effects }) => {
+		const context = parsed(contextText(actor));
+		observations.push({
+			from,
+			event: event.type,
+			to,
+			transitioned,
+			effects,
+			step: index,
+			payload: event.payload,
+			context
+		});
+		if (transitioned) visited.push(to);
+	} });
+	actor.on("error", { fn: (info) => {
+		errors.push({
+			from: info.state.name,
+			event: info.event.type,
+			message: messageOf(info.error),
+			step: index
+		});
+	} });
+	for (const step of steps) {
+		if (actor.state.name === ERROR_STATE) break;
+		const before = contextText(actor);
+		applyStep(actor, {
+			step,
+			clock,
+			internal
+		});
+		if (contextText(actor) !== before) contextSteps.push(index);
+		index += 1;
+	}
+	actor.dispose();
+	return {
+		visited,
+		observations,
+		errors,
+		contextSteps,
+		features: featuresOf({
+			visited,
+			observations,
+			errors
+		})
+	};
+}
+export { messageOf as a, execute as i, contextText as n, parsed as o, eventCatalog as r, applyStep as t };

package/dist/run-BLt0mwXe.d.mts

@@ -0,0 +1,60 @@
+import { VizJson, VizStep } from "@mantaq/viz";
+import { AnyActor, VirtualClock } from "@mantaq/core";
+/** A machine the fuzzer can drive: a fresh actor plus the virtual clock it runs on. */
+interface FuzzTarget {
+  id: string;
+  create(): {
+    actor: AnyActor<unknown>;
+    clock: VirtualClock;
+  };
+  /**
+   * Sample payloads per event type. Payload types are erased at runtime, so
+   * the fuzzer only mutates shapes it was given. Events without samples are
+   * sent without a payload.
+   */
+  payloads?: Readonly<Record<string, ReadonlyArray<VizJson>>>;
+}
+interface Observation {
+  from: string;
+  event: string;
+  to: string;
+  transitioned: boolean;
+  /** Names of the effects that ran on entry into `to`. */
+  effects: string[];
+  /** Index of the step that caused it. */
+  step: number;
+  /** Payload the handler received (for branch-distance guidance). */
+  payload: unknown;
+  /** JSON copy of the actor context right after the handler ran; null if not JSON. */
+  context: unknown;
+}
+interface RunError {
+  from: string;
+  event: string;
+  message: string;
+  /** Index of the step that triggered it. */
+  step: number;
+}
+interface Trace {
+  visited: string[];
+  observations: Observation[];
+  errors: RunError[];
+  /** Indices of steps after which the actor context differed: loop candidates. */
+  contextSteps: number[];
+  /**
+   * Coverage features, sorted: `state:x`, `edge:a>e>b` (state changed or
+   * re-entered), `stay:a>e` (handled, no change), `error:a>e` (handler threw).
+   */
+  features: string[];
+}
+/** Declared inputs and internal events, each sorted. */
+declare function eventCatalog(actor: AnyActor<unknown>): {
+  inputs: string[];
+  internal: string[];
+};
+/**
+ * Replay steps against a fresh actor. Synchronous and deterministic: effects
+ * only run via the virtual clock, and nothing here reads wall time.
+ */
+declare function execute(target: FuzzTarget, steps: ReadonlyArray<VizStep>): Trace;
+export { eventCatalog as a, Trace as i, Observation as n, execute as o, RunError as r, FuzzTarget as t };

package/dist/vite.mjs

@@ -1,5 +1,6 @@
-import { c as vizDocument, i as runOf, n as inspectEntry, t as entryId } from "./load-C4rGWmGU.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-DOwsxTyL.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";
@@ -18,6 +19,42 @@ import { searchForWorkspaceRoot } from "vite";
 */
 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();
@@ -40,63 +77,83 @@ 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("@mantaq/viz/live"));
-	return [inspectEntry(), {
-		name: "mantaq-viz",
-		apply: "serve",
-		config: (config) => ({ server: { fs: { allow: [searchForWorkspaceRoot(config.root ?? process.cwd()), dirname(dirname(live))] } } }),
-		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;
-				server.environments.ssr.moduleGraph.invalidateAll();
-				server.ws.send({
-					type: "custom",
-					event: UPDATE_EVENT
+	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 === TARGETS ? TARGETS_RESOLVED : null,
+			load: (id) => id === TARGETS_RESOLVED ? 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));
+				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);
 					});
-					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}`);
 				});
-			});
-			server.httpServer?.once("listening", () => {
-				server.config.logger.info(`  mantaq viz: ${base}`);
-			});
+			}
 		}
-	}];
+	];
 }
 export { mantaqViz };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/inspect",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Turn a Mantaq machine into a viz document: structure, handler explanations (AST), fuzz and test coverage. CLI and Vite plugin included.",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,8 @@
   "type": "module",
   "exports": {
     ".": "./dist/index.mjs",
+    "./drive": "./dist/drive.mjs",
+    "./live-entry": "./dist/live-entry.mjs",
     "./vite": "./dist/vite.mjs",
     "./package.json": "./package.json"
   },
@@ -25,11 +27,11 @@
   },
   "dependencies": {
     "typescript": "6.0.3",
-    "@mantaq/core": "0.5.0",
+    "@mantaq/core": "0.5.1",
     "@mantaq/pbt": "0.0.3",
-    "@mantaq/traversal": "0.3.0",
+    "@mantaq/traversal": "0.3.1",
     "@mantaq/utils": "0.0.4",
-    "@mantaq/viz": "0.1.0"
+    "@mantaq/viz": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
@@ -37,7 +39,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.0"
+    "@mantaq/sugar": "2.0.1"
   },
   "peerDependencies": {
     "vite": "*"