@mantaq/inspect 0.2.1 → 0.3.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] [--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.
+**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.
 
 **Vite plugin**: a live page on your dev server that redraws, keeping your walk, when you save.
 
@@ -50,6 +50,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 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 `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,41 +1,87 @@
 #!/usr/bin/env node
-import { l as vizDocument, r as inspectFile } from "./load-DOwsxTyL.mjs";
-import { t as htmlPage } from "./page-rr9IQ-4k.mjs";
+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] [--no-fuzz] [--iterations N] [--config FILE]
+*   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. `--config` loads the files with that Vite config (env,
+* 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] [--no-fuzz] [--iterations N] [--config FILE] [--mode MODE] [--no-open] [--check]\n";
+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" },
@@ -47,20 +93,17 @@ function parse() {
 	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 iterations = Number(values.iterations ?? 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 json = values.json === true;
-	const fuzz = values["no-fuzz"] === true ? false : {
-		seed: seed[1],
-		iterations
-	};
+	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,
-		fuzz,
+		live,
+		fuzz: fuzz[1],
 		check: values.check === true,
 		load: loadOptions(values.config, values.mode),
 		open: values["no-open"] !== true && !json && process.stdout.isTTY === true
@@ -85,7 +128,7 @@ async function main() {
 		process.exitCode = 1;
 		return;
 	}
-	const { files, out, json, fuzz, open, check, load } = options[1];
+	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`);
@@ -100,7 +143,8 @@ async function main() {
 	}
 	const document = vizDocument(machines);
 	const title = `${files.map((file) => basename(file)).join(", ")} · mantaq viz`;
-	writeFileSync(out, json ? serializeViz(document) : await htmlPage(document, title));
+	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);
 }

package/dist/index.d.mts

@@ -123,6 +123,7 @@ interface ModuleAnalysis {
   sites: HandlerSite[];
   stateDocs: ReadonlyMap<string, string>;
   eventDocs: ReadonlyMap<string, string>;
+  effectDocs: ReadonlyMap<string, ReadonlyArray<string>>;
   payloads: Record<string, VizJson[]>;
   machines: MachineExport[];
 }
@@ -147,6 +148,9 @@ 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. */
-export declare function htmlPage(document: VizDocument, title: string): Promise<string>;
+/**
+ * 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.
+ */
+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 };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-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 { 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 { i as execute, r as eventCatalog } from "./run-B5huYj_r.mjs";
-import { t as htmlPage } from "./page-rr9IQ-4k.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 };

package/dist/live-embedded.d.mts

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

package/dist/live-embedded.mjs

@@ -0,0 +1,16 @@
+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-entry.mjs

@@ -1,88 +1,6 @@
-import { createDriver } from "./drive.mjs";
-import { UPDATE_EVENT, parseViz } from "@mantaq/viz";
-import { Either } from "@mantaq/utils";
+import { n as mountLiveDriven } from "./live-page-DEDl_Nio.mjs";
+import { UPDATE_EVENT } from "@mantaq/viz";
 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/live-page-DEDl_Nio.mjs

@@ -0,0 +1,85 @@
+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

@@ -0,0 +1,41 @@
+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 };

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

@@ -1,14 +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 { ANY_STATE, UPDATE_EVENT, VIZ_SCHEMA_VERSION, coveredByAny, isAnyState, livePageHtml, routingWarnings, serializeViz, unhandledSends } from "@mantaq/viz";
 import { INITIAL_NODE_ID, buildGraph, parseInternalEventIds } from "@mantaq/traversal";
 import { Either } from "@mantaq/utils";
 import ts from "typescript";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { DEFAULT_SEED } from "@mantaq/pbt";
 import { VirtualClock } from "@mantaq/core";
-import { existsSync } from "node:fs";
+import { existsSync, globSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { loadConfigFromFile, loadEnv, runnerImport } from "vite";
+import { loadConfigFromFile, loadEnv, runnerImport, searchForWorkspaceRoot } from "vite";
 // src/structure.ts
 function byId$1(left, right) {
 	if (left.id < right.id) return -1;
@@ -793,6 +793,15 @@ function callDoc(call) {
 	while (ts.isPropertyAccessExpression(top.parent) || ts.isCallExpression(top.parent)) top = top.parent;
 	return docOf(ts.isExpressionStatement(top.parent) ? top.parent : call);
 }
+function collectEffectDoc(checker, call, effectDocs) {
+	if (!ts.isPropertyAccessExpression(call.expression) || call.expression.name.text !== "effect") return;
+	const [stateArg] = call.arguments;
+	if (stateArg === void 0) return;
+	const state = literalProperty(checker, stateArg, "name");
+	const doc = callDoc(call);
+	if (state === null || doc === null) return;
+	effectDocs.set(state, [...effectDocs.get(state) ?? [], doc]);
+}
 function compilerOptions(source) {
 	const configPath = source.tsconfig ?? ts.findConfigFile(dirname(source.file), (path) => ts.sys.fileExists(path));
 	if (configPath === void 0) return {
@@ -880,6 +889,7 @@ function loadSource(source) {
 		const registrations = [];
 		const stateDocs = /* @__PURE__ */ new Map();
 		const eventDocs = /* @__PURE__ */ new Map();
+		const effectDocs = /* @__PURE__ */ new Map();
 		const visit = (node) => {
 			const found = ts.isCallExpression(node) ? toRegistration(checker, node) : null;
 			if (found) registrations.push(found);
@@ -888,6 +898,7 @@ function loadSource(source) {
 				eventDocs
 			});
 			ts.forEachChild(node, visit);
+			if (ts.isCallExpression(node)) collectEffectDoc(checker, node, effectDocs);
 		};
 		visit(sourceFile);
 		return {
@@ -896,7 +907,8 @@ function loadSource(source) {
 			root: source.root,
 			registrations,
 			stateDocs,
-			eventDocs
+			eventDocs,
+			effectDocs
 		};
 	});
 	if (Either.isLeft(loaded)) return Either.left(`compiler failed: ${String(loaded[0])}`);
@@ -1444,7 +1456,8 @@ function docsOf(loaded) {
 	return {
 		sites: sitesOf(loaded),
 		stateDocs: loaded.stateDocs,
-		eventDocs: loaded.eventDocs
+		eventDocs: loaded.eventDocs,
+		effectDocs: loaded.effectDocs
 	};
 }
 /** Handlers, payload samples and machine exports of a file, from one TypeScript program. */
@@ -1460,10 +1473,17 @@ function localState(id) {
 	return id.slice(id.lastIndexOf(".") + 1);
 }
 function explain(edge, context) {
-	if (edge.kind === "initial" || edge.kind === "effect") return {
+	if (edge.kind === "initial") return {
 		explanation: null,
 		doc: null
 	};
+	if (edge.kind === "effect") {
+		const docs = context.effectDocs.get(localState(edge.from));
+		return {
+			explanation: null,
+			doc: docs === void 0 ? null : docs.join("\n\n")
+		};
+	}
 	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 {
@@ -1513,6 +1533,7 @@ function annotateWith(machine, context) {
 			...edge,
 			...explain(edge, {
 				sites: analysis[1].sites,
+				effectDocs: analysis[1].effectDocs,
 				file
 			})
 		};
@@ -1837,4 +1858,155 @@ async function inspectFile(file, options = {}, load = {}) {
 		failed: false
 	};
 }
-export { toVizMachine as S, fuzzedMachine as _, inspect as a, shrink as b, projectRoot as c, analyzeSource as d, annotateMachine as f, literalPool as g, guidance as h, runOf as i, vizDocument as l, branchDistanceGuide as m, inspectEntry as n, inspectModule as o, branchDistance as p, inspectFile as r, machineId as s, entryId as t, analyzeModule as u, withTestCoverage as v, toViz as x, fuzz as y };
+// 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 };

package/dist/vite.d.mts

@@ -1,5 +1,6 @@
 import { t as FuzzSettings } from "./inspect-DvQtAcwv.mjs";
 import { Plugin } from "vite";
+export declare const STYLESHEETS: string[];
 export interface MantaqVizOptions {
   /** Files that export machines: paths or globs, relative to the Vite root. */
   machines: string | string[];
@@ -8,4 +9,13 @@ export interface MantaqVizOptions {
   /** `false` = structure only. Default: 500 iterations, so a save redraws quickly. */
   fuzz?: false | FuzzSettings;
 }
+export declare const TARGETS = "virtual:mantaq/targets";
+export declare const TARGETS_RESOLVED = "\0virtual:mantaq/targets";
+/**
+ * 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.
+ */
+export declare function targetsSource(files: ReadonlyArray<string>): string;
 export declare function mantaqViz(options: MantaqVizOptions): Plugin[];

package/dist/vite.mjs

@@ -1,159 +1 @@
-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";
-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 === 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));
-						});
-						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 { mantaqViz };
+export { t as STYLESHEETS, n as TARGETS, r as TARGETS_RESOLVED, i as mantaqViz, a as targetsSource } from "./vite-BBW0CmYr.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/inspect",
-  "version": "0.2.1",
+  "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.",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,7 @@
   "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"
@@ -27,11 +28,11 @@
   },
   "dependencies": {
     "typescript": "6.0.3",
-    "@mantaq/pbt": "0.0.3",
-    "@mantaq/traversal": "0.3.2",
-    "@mantaq/core": "0.5.2",
-    "@mantaq/viz": "0.2.1",
-    "@mantaq/utils": "0.0.4"
+    "@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"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
@@ -39,7 +40,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.2"
+    "@mantaq/sugar": "2.0.3"
   },
   "peerDependencies": {
     "vite": "*"

package/dist/page-rr9IQ-4k.mjs

@@ -1,38 +0,0 @@
-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`, plus its stylesheets. */
-async function viewerBundle() {
-	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 {
-		script: (Array.isArray(output) ? output : [output]).flatMap((each) => "output" in each ? each.output : []).flatMap((file) => file.type === "chunk" ? [file.code] : []).join("\n"),
-		css: ["@mantaq/viz/viewer.css", "@mantaq/viz/page.css"].map((id) => readFileSync(fileURLToPath(import.meta.resolve(id)), "utf8")).join("\n")
-	};
-}
-/** A self-contained HTML page for `document`: open it from disk, attach it, commit it. */
-async function htmlPage(document, title) {
-	const bundle = await viewerBundle();
-	return standaloneHtml({
-		title,
-		...bundle,
-		document: serializeViz(document)
-	});
-}
-export { htmlPage as t };