@mantaq/inspect 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anders Can
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @mantaq/inspect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turns your Mantaq machine into a picture you can walk: one command, no config.
+
+```sh
+mantaq-inspect src/cart.ts     # writes mantaq-viz.html and opens it
+```
+
+It finds every exported actor, or function that builds one, from the file's types. It reads handler explanations and sample payloads from the source, fuzzes each machine that runs on a `VirtualClock`, and writes one self-contained HTML page that works offline: commit it, attach it to a PR. The viewer is [`@mantaq/viz`](../viz/README.md).
+
+## 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.
+
+**Vite plugin**: a live page on your dev server that redraws, keeping your walk, when you save.
+
+```ts
+// vite.config.ts
+import { mantaqViz } from "@mantaq/inspect/vite";
+
+export default defineConfig({
+  plugins: [mantaqViz({ machines: "src/**/*.machine.ts" })],
+});
+// open /__mantaq/ while `vp dev` runs
+```
+
+Options: `base` (default `/__mantaq/`), `fuzz` (`false`, or `{ seed, iterations }`; default 500 iterations so a save redraws fast).
+
+**Library**: one call per machine.
+
+```ts
+import { inspect, vizDocument } from "@mantaq/inspect";
+import { serializeViz } from "@mantaq/viz";
+
+const { machine, warnings } = inspect({
+  id: "cart",
+  create: () => createCart(), // a fresh actor every call
+  source: { file: "/abs/src/cart.ts", root: "/abs" }, // optional: explanations + payloads from types
+  tests: [[{ kind: "event", event: "addItem", payload: { sku: "A1" } }]], // optional: "example tests" coverage
+});
+const json = serializeViz(vizDocument([machine]));
+```
+
+`inspectFile(file)` / `inspectModule(file, { load })` do the discovery the CLI does. The building blocks (`toVizMachine`, `annotateMachine`, `fuzz`, `fuzzedMachine`, `withTestCoverage`, `guidance`) stay exported for custom pipelines.
+
+## What it needs from your file
+
+- **Exports.** An actor, or a function that returns one (or `{ actor }`). Functions are called with no arguments, with a `VirtualClock` when the first parameter is a clock, or with `{ clock }` when it is an options object with a `clock`. Functions with other required parameters are skipped. Discovery reads types only; nothing is called to find out.
+- **A fresh actor per call**, to fuzz. A file that only exports one actor instance is drawn, not fuzzed. When a file has factories, its actor instances are skipped.
+- **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.
+
+## Coverage: two sources, two questions
+
+The viewer's "Coverage from" picker dims elements with zero hits. What dimmed means depends on the source:
+
+- **example tests** (`tested`): no test exercises this. Collected by replaying the event sequences you pass as `tests`, each on a fresh actor.
+- **fuzz runs** (`coverage`): no fuzz run produced this. Fuzzing reaches almost everything, so little is dimmed. What does stay dimmed is usually a **declared but unreached edge**: the handler lists the target in `to`, but its guards may never allow it. Saga's `compensatingRefund -REFUND_DONE-> failed` is an example. The edge panel calls these out. Fuzzing is not proof, so check the handler.
+
+## How each tool works
+
+**Structure** (`toViz`, Phase 1): states come from the actor's `states`, edges from each registration's `to` (`actor.options.targets`): one edge per declared target, a `stay` edge when `to` is absent. `onAny` registrations draw from one `*` source per machine or region, never once per state. Coverage of a `*` edge counts every covered state; a state's own handler for the same event is not told apart. Nothing runs to find them. `@mantaq/traversal` still calls each handler with payload `{}` and each sample context, but only to label edges with the contexts that reach them and what they emit.
+
+**Fuzzer** (`fuzz`, Phase 3): a fresh actor and `VirtualClock` per run, so it is synchronous and deterministic. Mutations: insert, delete, swap, payload leaf tweak, time advance, and **loop**. Loop repeats, 2–13 times or a compared literal's count, a step that changed the actor's context, so counter guards like `if (attempts > 10)` become reachable. A step that changes nothing is never looped. A run is kept when it reaches a new feature (`state:x`, `edge:a>e>b`, `stay:a>e`, `error:a>e`), then shrunk to 1-minimal. Internal events are injected only when the current state handles them, as a live effect would (core rejects the rest). Payloads come from the per-machine samples and are mutated leaf by leaf, keeping each leaf's JSON type and never dropping keys. So a handler that throws is a real finding, not a type violation the compiler would reject.
+
+**Payloads** (`analyzeModule`): the TypeScript checker reads each handled event's payload type (`event("x")<{ ... }>()`) and builds samples: `"sample"` for strings, `1` for numbers, every member of a literal union (varied one field at a time), one element per array. The fuzzer mutates from there. Samples you pass replace them per event.
+
+**AST** (`annotateMachine`, Phase 4): one `ts.Program` per source file with the project tsconfig. It finds `m.on(state, { event, handler })` / `m.onAny({ event, handler })` and resolves names from the literal types of `state.name` / `event.type`. It walks inline handlers: if/else, early returns, ternaries, and a ternary inside `state:`. A specific `on` wins over `onAny`, as at runtime.
+
+**Guidance** (`guidance`, Phase 5): literal seeding plus a branch-distance guide built from AST comparisons on payload and context. It helps when handlers compare payload fields against literals far from the samples, or count in context toward a threshold. See `docs/atlas/phase5-comparison.md`.
+
+## What it cannot show
+
+- **Guards** are not evaluated. A declared edge says "the handler may return this", not "some input reaches it". Fuzz coverage and the AST's branch conditions are the evidence; neither is proof.
+- **`onAny` routing on live actor state** (`actor.state.name`) cannot be drawn exactly: the `*` edges say "from any state, may go to X", not which state leads where. Register per-state `m.on` handlers instead, as checkout's `back` does. `routingWarnings(machine)` lists these handlers (the viewer and `inspect` warnings show them); it needs AST explanations.
+- **Payload types** come from the source. Without `source`, the fuzzer knows only the shapes you sample. Loose types (`string`, `unknown`) give loose samples. The document's `payloadType` is always `null`.
+- **Effects** are known by name and declared `sends` only. An effect without `sends` shows `sends not declared`, and its events fall under "other internal events". `inspect` warns when a declared send has no handler in the effect's state. Example fixtures stub effects, and the fuzzer stands in for them by injecting internal events. It can therefore produce event orders a real effect never would, but only in states that handle the event.
+- **Regions**: the fuzzer observes the root actor only. Region transitions are probed but not fuzzed.
+- **AST limits**: handlers passed by reference, returns inside `switch` / loops / `try`, and computed `event`s are `not_analyzed`, with a reason and snippet. Comparisons against actor state or computed values carry no guidance.
+- **History** cannot distinguish an ignored event from a self-loop. The fuzzer can (`stay` vs `transition`), but probe-only coverage cannot.
+- **Fuzzing is not proof.** An edge that is absent was not reached; it is not shown to be impossible.
+
+## Fixtures
+
+`src/fixtures/{checkout,auth,saga}.ts` copy the handlers of `packages/examples/*.test.ts` verbatim, with effects stubbed. The examples live in test files and cannot be imported, so the copies can drift from them. `credit.ts` (conditional handlers, far literals), `retry.ts` (context counter, `attempts > 10`) and `switchy.ts` (unsupported control flow) exist for the AST, loop and guidance tests.
+
+## Repo scripts
+
+```sh
+vp run viz:export     # bundled examples -> packages/viz/public/examples/*.json (the viz dev page loads them)
+vp run viz:compare    # blind vs guided fuzzing report (Markdown, 30 seeds)
+```
+
+`export` options: `[outDir] --iterations N --no-fuzz --no-ast`.

package/dist/cli.d.mts

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

package/dist/cli.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { c as vizDocument, r as inspectFile } from "./load-C4rGWmGU.mjs";
+import { t as htmlPage } from "./page-rr9IQ-4k.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 { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+// src/cli.ts
+/**
+* mantaq-inspect: draw the machines a file exports.
+*
+*   mantaq-inspect <file.ts>... [--out FILE] [--json] [--no-fuzz] [--iterations N] [--no-open]
+*
+* 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).
+*/
+const USAGE = "usage: mantaq-inspect <file.ts>... [--out FILE] [--json] [--no-fuzz] [--iterations N] [--no-open]\n";
+function parse() {
+	const parsed = Either.from(() => parseArgs({
+		allowPositionals: true,
+		options: {
+			out: { type: "string" },
+			json: { type: "boolean" },
+			iterations: { type: "string" },
+			"no-fuzz": { type: "boolean" },
+			"no-open": { type: "boolean" }
+		}
+	}));
+	if (Either.isLeft(parsed)) return Either.left(String(parsed[0]));
+	const { positionals, values } = parsed[1];
+	if (positionals.length === 0) return Either.left("no file given");
+	const 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
+	};
+	return Either.right({
+		files: positionals.map((file) => resolve(file)),
+		out: resolve(values.out ?? (json ? "mantaq-viz.json" : "mantaq-viz.html")),
+		json,
+		fuzz,
+		open: values["no-open"] !== true && !json && process.stdout.isTTY === true
+	});
+}
+function openInBrowser(path) {
+	const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+	spawn(command, [path], {
+		stdio: "ignore",
+		detached: true
+	}).on("error", () => {}).unref();
+}
+async function main() {
+	const options = parse();
+	if (Either.isLeft(options)) {
+		process.stderr.write(`${options[0]}\n${USAGE}`);
+		process.exitCode = 1;
+		return;
+	}
+	const { files, out, json, fuzz, open } = options[1];
+	const results = [];
+	for (const file of files) results.push(await inspectFile(file, { fuzz }));
+	for (const warning of results.flatMap((result) => result.warnings)) process.stderr.write(`warning: ${warning}\n`);
+	const machines = results.flatMap((result) => result.machines);
+	if (machines.length === 0) {
+		process.stderr.write("no machines found\n");
+		process.exitCode = 1;
+		return;
+	}
+	const document = vizDocument(machines);
+	const title = `${files.map((file) => basename(file)).join(", ")} · mantaq viz`;
+	writeFileSync(out, json ? serializeViz(document) : await htmlPage(document, title));
+	process.stdout.write(`wrote ${out} (${machines.map((machine) => machine.id).join(", ")})\n`);
+	if (open) openInBrowser(out);
+}
+main();
+export {};

package/dist/index.d.mts

@@ -0,0 +1,195 @@
+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 { Plugin } from "vite";
+interface VizInput {
+  id: string;
+  /**
+   * Fresh actor to probe for structure. Handlers that read live actor state
+   * see this actor's current state, so pass one that has not been driven.
+   */
+  actor: AnyActor<unknown>;
+  /** History from `instrument(actor)`; omit for a structure-only document. */
+  history?: History;
+  sampleContexts?: Record<string, Record<string, unknown>>;
+}
+/** One machine; `toViz` is this plus sorting into a document. */
+export declare function toVizMachine(input: VizInput): VizMachine;
+export declare function toViz(inputs: ReadonlyArray<VizInput>): VizDocument;
+/** Extra values to try at payload leaves (Phase 5 literal seeding). Empty = blind mutation. */
+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;
+  /** Longest sequence the mutator will grow. Default 24. */
+  maxLength?: number;
+  literals?: LiteralPool;
+  /** Loop context-changing steps (default true). False reproduces plain Phase 3 mutation. */
+  repeat?: boolean;
+  /**
+   * Optional search guidance (Phase 5). Sees every run; returning true keeps
+   * the run in the corpus as a stepping stone even without new coverage.
+   */
+  guide?: (trace: Trace) => boolean;
+}
+interface CorpusEntry {
+  steps: VizStep[];
+  /** Features first reached by this entry. Empty for guide-only keeps. */
+  discovered: string[];
+  iteration: number;
+}
+interface FuzzResult {
+  seed: number;
+  iterations: number;
+  corpus: CorpusEntry[];
+  /** Feature -> iteration that first reached it. */
+  firstHit: Map<string, number>;
+  errors: VizFuzzError[];
+}
+/** Greedy one-step deletion, last to first, while `wanted` stays covered. Deterministic. */
+export declare function shrink(target: FuzzTarget, steps: ReadonlyArray<VizStep>, wanted: ReadonlyArray<string>): VizStep[];
+/**
+ * Coverage-guided fuzzing. Each iteration mutates a corpus entry, runs it on a
+ * fresh actor and keeps it if it reaches a feature (state, edge, stay, error)
+ * no earlier run reached. Same target + options => identical result.
+ */
+export declare function fuzz(target: FuzzTarget, options: FuzzOptions): FuzzResult;
+/**
+ * Viz machine with fuzz results written in: coverage from replaying the
+ * shrunk corpus, newly discovered edges (origin `fuzz`), and the corpus itself.
+ */
+export declare function fuzzedMachine(target: FuzzTarget, result: FuzzResult): VizMachine;
+/**
+ * Fill `tested` from replaying test sequences (each from a fresh actor).
+ * Lets the viewer show what the tests never exercise, next to what fuzzing reached.
+ */
+export declare function withTestCoverage(target: FuzzTarget, machine: VizMachine, sequences: ReadonlyArray<ReadonlyArray<VizStep>>): VizMachine;
+/**
+ * Literal seeding: every literal the handlers compare against, plus its
+ * neighbours (`L - 1`, `L + 1`) so boundary sides are both reachable.
+ */
+export declare function literalPool(machine: VizMachine): LiteralPool;
+/**
+ * Branch distance (Korel/Tracey): how far `value` is from making the
+ * comparison `outcome`. 0 = that side is taken. Undefined when incomparable.
+ */
+export declare function branchDistance(comparison: VizComparison, context: {
+  value: unknown;
+  outcome: boolean;
+}): number | undefined;
+/**
+ * Stateful guide for `fuzz({ guide })`. For every comparison outcome not yet
+ * reached it remembers the smallest distance seen; a run that gets closer is
+ * kept as a stepping stone. Reached outcomes stop counting.
+ */
+export declare function branchDistanceGuide(machine: VizMachine): (trace: Trace) => boolean;
+/** Phase 5 search options for an AST-annotated machine: literal seeding + branch distance. */
+export declare function guidance(machine: VizMachine): Pick<FuzzOptions, "literals" | "guide">;
+/**
+ * How to get a fresh actor from an export, read from its type alone (nothing
+ * is called to find out):
+ * - `instance`: the export is an actor. It cannot be recreated, so it is
+ *   drawn but not fuzzed.
+ * - `call`: call it with no arguments.
+ * - `clock`: call it with a VirtualClock.
+ * - `options`: call it with `{ clock: VirtualClock }`.
+ *
+ * `unwrap`: the result is the actor (`self`) or carries it as `.actor`.
+ */
+interface MachineExport {
+  name: string;
+  call: "instance" | "call" | "clock" | "options";
+  unwrap: "self" | "actor";
+}
+/** One explained registration, keyed the way runtime edges are: state + event. */
+interface HandlerSite {
+  /** null = onAny. */
+  state: string | null;
+  event: string;
+  explanation: VizExplanation;
+}
+/** 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[];
+  payloads: Record<string, VizJson[]>;
+  machines: MachineExport[];
+}
+/** Handlers, payload samples and machine exports of a file, from one TypeScript program. */
+export declare function analyzeModule(source: AnalysisSource): Either<string, ModuleAnalysis>;
+/**
+ * Fill `explanation` on handler-driven edges. Never adds or removes edges:
+ * the runtime graph stays the source of truth. A source that cannot be
+ * analyzed marks every handler edge `not_analyzed` with the reason.
+ */
+export declare function annotateMachine(machine: VizMachine, source: AnalysisSource): VizMachine;
+/** Options `inspectFile` passes through to `inspectModule`; loading is its job. */
+type FileOptions = Omit<ModuleOptions, "load">;
+/** Load `file` with Vite (TS, tsconfig paths, extensionless imports) and inspect its machines. */
+export declare function inspectFile(file: string, options?: FileOptions): Promise<InspectedModule>;
+/** 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 };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+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 { 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/inspect-DvQtAcwv.d.mts

@@ -0,0 +1,66 @@
+import { VizDocument, VizJson, VizMachine, VizStep } from "@mantaq/viz";
+import { Either } from "@mantaq/utils";
+import ts from "typescript";
+import { AnyActor } from "@mantaq/core";
+interface AnalysisSource {
+  /** Absolute path of the file that registers the handlers (`m.on` / `m.onAny`). */
+  file: string;
+  /** Locations are reported relative to this directory. */
+  root: string;
+  /** tsconfig used to type-check the file. Default: nearest one above `file`. */
+  tsconfig?: string;
+}
+interface FuzzSettings {
+  seed?: number;
+  /** Default 2000. */
+  iterations?: number;
+}
+interface InspectTarget {
+  id: string;
+  /** A fresh actor on every call. Fuzzing needs it to run on a VirtualClock. */
+  create: () => AnyActor<unknown>;
+  /** File with the `m.on` calls: edge explanations, and payload samples from the event types. */
+  source?: AnalysisSource;
+  /** Sample payloads per event; replace the ones read from types. */
+  payloads?: Readonly<Record<string, ReadonlyArray<VizJson>>>;
+  /** Event sequences your tests send, for "Coverage from: example tests". */
+  tests?: ReadonlyArray<ReadonlyArray<VizStep>>;
+  /** `false` = structure only. */
+  fuzz?: false | FuzzSettings;
+}
+interface Inspected {
+  machine: VizMachine;
+  /** Things worth fixing or knowing: unreachable routing, unhandled sends, why fuzzing was skipped. */
+  warnings: string[];
+}
+/**
+ * One machine in, one viz machine out: structure, edge explanations and
+ * payloads from the source's types, fuzz coverage, test coverage. Each part
+ * that cannot run is skipped with a warning, never guessed.
+ */
+declare function inspect(target: InspectTarget): Inspected;
+/** `createCheckoutActor` → `checkout`; other names are kept. */
+declare function machineId(exportName: string): string;
+interface ModuleOptions {
+  /** Import the file and return its exports (e.g. Vite's `runnerImport`, `ssrLoadModule`). */
+  load: (file: string) => Promise<Record<string, unknown>>;
+  /** Locations are relative to this. Default: nearest package.json above the file. */
+  root?: string;
+  tsconfig?: string;
+  fuzz?: false | FuzzSettings;
+}
+interface InspectedModule {
+  machines: VizMachine[];
+  /** Prefixed with the machine id, or the file when it is about the file. */
+  warnings: string[];
+}
+/**
+ * Every machine a file exports, found from its types: actors, and functions
+ * that build one (optionally taking a clock or `{ clock }`). When a file has
+ * factories, plain actor exports are skipped: they are usually one of those
+ * factories' results, and cannot be fuzzed.
+ */
+declare function inspectModule(file: string, options: ModuleOptions): Promise<InspectedModule>;
+/** Machines as a document, ready for `serializeViz`. */
+declare function vizDocument(machines: ReadonlyArray<VizMachine>): VizDocument;
+export { ModuleOptions as a, machineId as c, InspectedModule as i, vizDocument as l, InspectTarget as n, inspect as o, Inspected as r, inspectModule as s, FuzzSettings as t, AnalysisSource as u };