dungbeetle 0.1.1

package/dist/captures/check.js

@@ -0,0 +1,116 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { coerceSnapshot, render } from "../compare/shared.js";
+import { captureCheck, checkParserFor } from "../check/capture.js";
+import { checkParsers } from "../check/parsers.js";
+import { structuralChanges } from "../diff/structural.js";
+import { canonicalizeSnapshot } from "../snapshot.js";
+// Check snapshots hold keyed records (entry identity → attributes), so the
+// structural diff names exactly the added/removed/changed entry — e.g.
+// `~ data["GET|HEAD /users"]: … → undefined` for a removed route.
+function compareCheck(baseline, candidate, options) {
+    const sections = [];
+    if (baseline.tool !== candidate.tool) {
+        sections.push(`~ tool: ${String(baseline.tool)} → ${String(candidate.tool)}`);
+    }
+    const changes = structuralChanges({ data: baseline.data }, { data: candidate.data }, { numericTolerance: options.comparison.numericTolerance });
+    for (const change of changes) {
+        sections.push(`~ ${change.path}: ${render(change.before)} → ${render(change.after)}`);
+    }
+    return {
+        equal: sections.length === 0,
+        rendered: sections.join("\n")
+    };
+}
+function doctorCheckFor(target) {
+    if (!Object.hasOwn(checkParsers, target.tool)) {
+        return {
+            name: "check-target",
+            severity: "fail",
+            target: target.name,
+            message: `Check target "${target.name}" uses unknown tool "${target.tool}". ` +
+                `Available: ${Object.keys(checkParsers).join(", ")}.`
+        };
+    }
+    const parser = checkParserFor(target);
+    return {
+        name: "check-target",
+        severity: "pass",
+        target: target.name,
+        message: describeCheckTarget(target, parser.tool, parser.defaultCommand, parser.defaultOutput)
+    };
+}
+function describeCheckTarget(target, tool, defaultCommand, defaultOutput) {
+    const command = target.command ?? (target.output ? undefined : defaultCommand);
+    const output = target.output ?? (target.command ? undefined : defaultOutput);
+    if (!command) {
+        return `Check target "${target.name}" ingests ${String(output)} as ${tool}.`;
+    }
+    return output
+        ? `Check target "${target.name}" runs \`${command}\` and reads ${output}.`
+        : `Check target "${target.name}" runs \`${command}\`.`;
+}
+// The wrapped binary must exist before the command can work: `vendor/bin/x`
+// commands need `composer install`, `php artisan …` needs an artisan file.
+// Bare binaries resolved via PATH (e.g. `php` itself) are left to runtime.
+async function binaryCheck(target, cwd) {
+    const parser = checkParsers[target.tool];
+    if (!parser) {
+        return undefined;
+    }
+    const command = target.command ?? (target.output ? undefined : parser.defaultCommand);
+    if (!command) {
+        return undefined;
+    }
+    const targetCwd = path.resolve(cwd, target.cwd ?? ".");
+    const first = command.split(" ")[0];
+    const requirement = first.includes("/")
+        ? { file: first, hint: "run `composer install`?" }
+        : first === "php" && /\bartisan\b/.test(command)
+            ? { file: "artisan", hint: "is this a Laravel app directory?" }
+            : undefined;
+    if (!requirement) {
+        return undefined;
+    }
+    const present = await access(path.resolve(targetCwd, requirement.file)).then(() => true, () => false);
+    return {
+        name: "check-binary",
+        severity: present ? "pass" : "fail",
+        target: target.name,
+        message: present
+            ? `Check target "${target.name}" found ${requirement.file}.`
+            : `Check target "${target.name}" needs ${requirement.file}, which is missing — ${requirement.hint}`
+    };
+}
+export const check = {
+    kind: "check",
+    capture: (target, { config, cwd }) => {
+        const checkTarget = target;
+        return captureCheck(checkTarget, {
+            cwd: path.resolve(cwd, checkTarget.cwd ?? "."),
+            timeoutMs: checkTarget.timeoutMs ?? config.lifecycle.wait.timeoutMs
+        });
+    },
+    canonicalize: (value) => ({
+        kind: value.kind,
+        tool: value.tool,
+        data: canonicalizeSnapshot(value.data)
+    }),
+    compare: (baseline, candidate, options) => compareCheck(coerceSnapshot(baseline), coerceSnapshot(candidate), options),
+    validateConfig: (target, { label, issues }) => {
+        const checkTarget = target;
+        if (!checkTarget.tool || typeof checkTarget.tool !== "string") {
+            issues.push(`${label} (check "${checkTarget.name}") must have a "tool".`);
+            return;
+        }
+        if (!Object.hasOwn(checkParsers, checkTarget.tool)) {
+            issues.push(`${label} (check "${checkTarget.name}") uses unknown tool "${checkTarget.tool}". ` +
+                `Available: ${Object.keys(checkParsers).join(", ")}.`);
+        }
+    },
+    doctorChecks: async (target, cwd) => {
+        const checkTarget = target;
+        const binary = await binaryCheck(checkTarget, cwd);
+        return binary ? [doctorCheckFor(checkTarget), binary] : [doctorCheckFor(checkTarget)];
+    }
+};

package/dist/captures/desktop.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureType } from "./types.js";
+export declare const desktop: CaptureType;

package/dist/captures/desktop.js

@@ -0,0 +1,97 @@
+import { a11yToDomNode, coerceSnapshot } from "../compare/shared.js";
+import { diffDomTrees, renderTreeChanges } from "../diff/tree.js";
+import { captureDesktop } from "../desktop/capture.js";
+import { canonicalizeSnapshot } from "../snapshot.js";
+function captureDesktopTarget(target, { config, cwd }) {
+    return captureDesktop(target, {
+        cwd,
+        timeoutMs: target.timeoutMs ?? config.lifecycle.wait.timeoutMs,
+        maskRules: config.normalization.masks
+    });
+}
+// Desktop accessibility trees reuse the structural DOM tree diff: each a11y
+// node maps to an element whose tag is the role and whose attributes carry the
+// name/value/description/state. Alignment is by role, so a renamed control
+// surfaces as a changed @name rather than a remove + add.
+function compareDesktop(baseline, candidate) {
+    const diff = diffDomTrees([a11yToDomNode(baseline.root)], [a11yToDomNode(candidate.root)]);
+    return {
+        equal: diff.equal,
+        rendered: diff.equal ? "" : renderTreeChanges(diff.changes)
+    };
+}
+function validateDesktopTarget(target) {
+    if (target.driver === "macos-ax") {
+        if (!target.app) {
+            return {
+                name: "desktop-target",
+                severity: "fail",
+                target: target.name,
+                message: `Desktop target "${target.name}" uses the macos-ax driver and must set "app".`
+            };
+        }
+        return {
+            name: "desktop-target",
+            severity: process.platform === "darwin" ? "pass" : "warn",
+            target: target.name,
+            message: process.platform === "darwin"
+                ? `Desktop target "${target.name}" captures "${target.app}" via macos-ax (needs Accessibility permission).`
+                : `Desktop target "${target.name}" uses the macos-ax driver, which only runs on macOS (current platform: ${process.platform}).`
+        };
+    }
+    return target.tree || target.command
+        ? {
+            name: "desktop-target",
+            severity: "pass",
+            target: target.name,
+            message: `Desktop target "${target.name}" has a ${target.tree ? "tree file" : "command"}.`
+        }
+        : {
+            name: "desktop-target",
+            severity: "fail",
+            target: target.name,
+            message: `Desktop target "${target.name}" must set "driver", "tree", or "command".`
+        };
+}
+export const desktop = {
+    kind: "desktop",
+    capture: (target, ctx) => captureDesktopTarget(target, ctx),
+    canonicalize: (value) => {
+        const canonical = {
+            kind: value.kind,
+            root: canonicalizeSnapshot(value.root)
+        };
+        if (value.tool !== undefined) {
+            canonical.tool = value.tool;
+        }
+        return canonical;
+    },
+    compare: (baseline, candidate) => compareDesktop(coerceSnapshot(baseline), coerceSnapshot(candidate)),
+    validateConfig: (target, { label, issues }) => {
+        const desktopTarget = target;
+        const hasImageSource = Boolean(desktopTarget.screenshot || desktopTarget.screenshotCommand);
+        if (desktopTarget.driver &&
+            desktopTarget.driver !== "macos-ax" &&
+            desktopTarget.driver !== "ocr") {
+            issues.push(`${label} (desktop "${desktopTarget.name}") has unknown driver "${desktopTarget.driver}".`);
+        }
+        else if (desktopTarget.driver === "macos-ax") {
+            if (!desktopTarget.app) {
+                issues.push(`${label} (desktop "${desktopTarget.name}") uses the macos-ax driver and must set "app".`);
+            }
+        }
+        else if (desktopTarget.driver === "ocr") {
+            if (!hasImageSource) {
+                issues.push(`${label} (desktop "${desktopTarget.name}") uses the ocr driver and must set "screenshot" or "screenshotCommand".`);
+            }
+        }
+        else if (!desktopTarget.tree && !desktopTarget.command) {
+            issues.push(`${label} (desktop "${desktopTarget.name}") must set "driver", "tree", or "command".`);
+        }
+        // The OCR fallback needs an image source regardless of the primary driver.
+        if (desktopTarget.ocrFallback && !hasImageSource) {
+            issues.push(`${label} (desktop "${desktopTarget.name}") sets "ocrFallback" but no "screenshot" or "screenshotCommand" to capture.`);
+        }
+    },
+    doctorChecks: (target) => [validateDesktopTarget(target)]
+};

package/dist/captures/game.d.ts

@@ -0,0 +1,4 @@
+import type { PixelTolerance } from "../diff/pixel.js";
+import type { CaptureType } from "./types.js";
+export declare const GAME_PIXEL_TOLERANCE: PixelTolerance;
+export declare const game: CaptureType;

package/dist/captures/game.js

@@ -0,0 +1,266 @@
+import { execFile } from "node:child_process";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { coerceSnapshot, compareScreenshotPair, digestOf, render } from "../compare/shared.js";
+import { structuralChanges } from "../diff/structural.js";
+import { captureGame, resolveEnginePath } from "../game/capture.js";
+import { PROTOCOL_VERSION } from "../game/protocol.js";
+const execFileAsync = promisify(execFile);
+import { walkthroughIssues } from "../game/walkthrough.js";
+import { isRecord } from "../guards.js";
+import { canonicalizeSnapshot } from "../snapshot.js";
+import { digestScreenshot } from "./web.js";
+function canonicalizeGame(value) {
+    const canonical = {
+        kind: value.kind,
+        engine: value.engine,
+        markers: canonicalizeSnapshot(value.markers)
+    };
+    // engineVersion/adapterVersion/ticks are runtime metadata: an engine patch
+    // release must not diff every baseline. Version compat is doctor's job.
+    if (isRecord(value.screenshots)) {
+        canonical.screenshots = Object.fromEntries(Object.entries(value.screenshots).map(([marker, screenshot]) => [
+            marker,
+            isRecord(screenshot) ? digestScreenshot(screenshot) : screenshot
+        ]));
+    }
+    return canonical;
+}
+// Semantic marker state is the gate; screenshot digests are compared as
+// named-marker lines. Pixel-diff fallback and the review-UI wiring for the
+// Non-zero visual default for the game kind: GPU/driver rasterization varies
+// across machines even when the simulation is byte-identical (measured zero
+// variance same-platform, so this only absorbs cross-machine noise).
+export const GAME_PIXEL_TOLERANCE = {
+    maxChangedRatio: 0.002,
+    perChannelThreshold: 3
+};
+// Per-marker tolerance resolution: marker override → target → explicit global
+// comparison config → the game kind default.
+function markerTolerance(target, options, marker) {
+    const override = target?.markers?.[marker]?.pixelTolerance;
+    if (override) {
+        return override;
+    }
+    if (target?.pixelTolerance) {
+        return target.pixelTolerance;
+    }
+    const global = options.comparison.pixelTolerance;
+    if (global.maxChangedRatio !== undefined || global.perChannelThreshold !== undefined) {
+        return global;
+    }
+    return GAME_PIXEL_TOLERANCE;
+}
+// Semantic marker state is the gate. Screenshot changes are ADVISORY by
+// default — reported in the diff but not failing the run — because rendering
+// varies across machines while the simulation doesn't. `screenshotMode:
+// "strict"` opts a target into visual changes gating like any other diff.
+function compareGame(baseline, candidate, options) {
+    const gameTarget = options.target?.kind === "game" ? options.target : undefined;
+    const strict = gameTarget?.screenshotMode === "strict";
+    const sections = [];
+    const advisory = [];
+    const changes = structuralChanges({ engine: baseline.engine, markers: baseline.markers }, { engine: candidate.engine, markers: candidate.markers }, { numericTolerance: options.comparison.numericTolerance });
+    for (const change of changes) {
+        sections.push(`~ ${change.path}: ${render(change.before)} → ${render(change.after)}`);
+    }
+    const markerDigests = (value) => isRecord(value.screenshots) ? value.screenshots : {};
+    const baselineShots = markerDigests(baseline);
+    const candidateShots = markerDigests(candidate);
+    const imagesByMarker = {};
+    for (const marker of new Set([...Object.keys(baselineShots), ...Object.keys(candidateShots)])) {
+        const shot = compareScreenshotPair(digestOf(baselineShots[marker]), digestOf(candidateShots[marker]), options.baselineScreenshots?.[marker], options.candidateScreenshots?.[marker], markerTolerance(gameTarget, options, marker), `screenshot[${marker}]`);
+        if (shot.line) {
+            if (strict) {
+                sections.push(shot.line);
+            }
+            else {
+                advisory.push(`${shot.line} (advisory — semantic state is the gate)`);
+            }
+        }
+        if (shot.images) {
+            imagesByMarker[marker] = shot.images;
+        }
+    }
+    return {
+        equal: sections.length === 0,
+        rendered: [...sections, ...advisory].join("\n"),
+        ...(Object.keys(imagesByMarker).length > 0 ? { screenshotImagesByMarker: imagesByMarker } : {})
+    };
+}
+async function gameDoctorChecks(target, cwd) {
+    const checks = [];
+    const project = path.resolve(cwd, target.project);
+    try {
+        await access(path.join(project, "project.godot"));
+        checks.push({
+            name: "game-project",
+            severity: "pass",
+            target: target.name,
+            message: `Godot project exists at ${project}.`
+        });
+    }
+    catch {
+        checks.push({
+            name: "game-project",
+            severity: "fail",
+            target: target.name,
+            message: `No project.godot found at ${project}.`
+        });
+    }
+    const walkthroughPath = path.resolve(cwd, target.walkthrough);
+    try {
+        const parsed = JSON.parse(await readFile(walkthroughPath, "utf8"));
+        const issues = walkthroughIssues(parsed);
+        checks.push(issues.length === 0
+            ? {
+                name: "game-walkthrough",
+                severity: "pass",
+                target: target.name,
+                message: `Walkthrough is valid at ${walkthroughPath}.`
+            }
+            : {
+                name: "game-walkthrough",
+                severity: "fail",
+                target: target.name,
+                message: `Walkthrough at ${walkthroughPath} is invalid: ${issues.join(" ")}`
+            });
+        // Per-marker overrides that don't match any walkthrough marker are dead
+        // config — almost always a typo.
+        if (issues.length === 0 && target.markers) {
+            const known = new Set(parsed.steps.flatMap((step) => typeof step.screenshot === "string" ? [step.screenshot] : []));
+            const unknown = Object.keys(target.markers).filter((marker) => !known.has(marker));
+            if (unknown.length > 0) {
+                checks.push({
+                    name: "game-marker-overrides",
+                    severity: "warn",
+                    target: target.name,
+                    message: `Marker override(s) ${unknown.map((m) => `"${m}"`).join(", ")} do not match any walkthrough marker (${[...known].join(", ") || "none"}).`
+                });
+            }
+        }
+    }
+    catch (error) {
+        checks.push({
+            name: "game-walkthrough",
+            severity: "fail",
+            target: target.name,
+            message: `Walkthrough at ${walkthroughPath} could not be read: ${error.message}`
+        });
+    }
+    if (target.mode === "visual") {
+        checks.push({
+            name: "game-screenshots",
+            severity: "warn",
+            target: target.name,
+            message: `Game target "${target.name}" uses visual mode (one screenshot per marker). Anonymous pushes cap reports at 25MB — push with an API key or keep marker count and viewport modest.`
+        });
+    }
+    // Determinism is adapter-enforced, not opt-in — surface the effective knobs
+    // so a reviewer can see what a "deterministic run" means for this target.
+    checks.push({
+        name: "game-determinism",
+        severity: "pass",
+        target: target.name,
+        message: `Deterministic run enforced: seed ${target.seed ?? 0}, ${target.physicsFps ?? 60} physics ticks/s, vsync off, action-level input injection. Screenshots are ${target.screenshotMode === "strict" ? "strict (visual changes gate the run)" : "advisory (semantic state is the gate)"}.`
+    });
+    // Adapter presence + protocol compatibility, from the addon source — support
+    // triage starts from facts, not from a hung handshake.
+    checks.push(await validateAdapterInstall(target, project));
+    const engine = resolveEnginePath(target);
+    checks.push(await validateEngineBinary(target, engine));
+    return checks;
+}
+async function validateAdapterInstall(target, project) {
+    const adapterPath = path.join(project, "addons", "dungbeetle", "dungbeetle.gd");
+    let source;
+    try {
+        source = await readFile(adapterPath, "utf8");
+    }
+    catch {
+        return {
+            name: "game-adapter",
+            severity: "fail",
+            target: target.name,
+            message: `Dungbeetle adapter not found at ${adapterPath}. Copy addons/dungbeetle/ from the adapter package into the project and register the autoload.`
+        };
+    }
+    const version = source.match(/ADAPTER_VERSION\s*:?=\s*"([^"]+)"/)?.[1] ?? "unknown";
+    const min = Number(source.match(/PROTOCOL_MIN\s*:?=\s*(\d+)/)?.[1] ?? Number.NaN);
+    const max = Number(source.match(/PROTOCOL_MAX\s*:?=\s*(\d+)/)?.[1] ?? Number.NaN);
+    const compatible = min <= PROTOCOL_VERSION && PROTOCOL_VERSION <= max;
+    return compatible
+        ? {
+            name: "game-adapter",
+            severity: "pass",
+            target: target.name,
+            message: `Adapter ${version} installed (protocol v${min}–v${max}, CLI speaks v${PROTOCOL_VERSION}).`
+        }
+        : {
+            name: "game-adapter",
+            severity: "fail",
+            target: target.name,
+            message: `Adapter ${version} supports protocol v${min}–v${max}, but this CLI speaks v${PROTOCOL_VERSION}. Upgrade the ${Number.isFinite(min) && min > PROTOCOL_VERSION ? "CLI" : "adapter"}.`
+        };
+}
+async function validateEngineBinary(target, engine) {
+    if (!path.isAbsolute(engine)) {
+        return {
+            name: "game-engine",
+            severity: "warn",
+            target: target.name,
+            message: `Engine resolves to "${engine}" on PATH. Set "enginePath" or DUNGBEETLE_GODOT_PATH for a pinned binary.`
+        };
+    }
+    try {
+        const { stdout } = await execFileAsync(engine, ["--version"], { timeout: 15_000 });
+        const version = stdout.trim().split("\n")[0] ?? "unknown";
+        return {
+            name: "game-engine",
+            severity: "pass",
+            target: target.name,
+            message: `Engine binary at ${engine} reports version ${version}.`
+        };
+    }
+    catch {
+        return {
+            name: "game-engine",
+            severity: "fail",
+            target: target.name,
+            message: `Engine binary at ${engine} could not be executed (ran "--version").`
+        };
+    }
+}
+export const game = {
+    kind: "game",
+    // Each run owns a child engine process (and the display, in visual mode) —
+    // never batched into the parallel pool.
+    capture: (target, ctx) => captureGame(target, {
+        cwd: ctx.cwd,
+        timeoutMs: ctx.config.lifecycle.wait.timeoutMs
+    }),
+    canonicalize: canonicalizeGame,
+    compare: (baseline, candidate, options) => compareGame(coerceSnapshot(baseline), coerceSnapshot(candidate), options),
+    validateConfig: (target, { label, issues }) => {
+        const gameTarget = target;
+        if (!gameTarget.project) {
+            issues.push(`${label} (game "${gameTarget.name}") must set "project".`);
+        }
+        if (!gameTarget.walkthrough) {
+            issues.push(`${label} (game "${gameTarget.name}") must set "walkthrough".`);
+        }
+        if (gameTarget.engine !== "godot") {
+            issues.push(`${label} (game "${gameTarget.name}") has unknown engine "${String(gameTarget.engine)}" — "godot" is the only supported engine.`);
+        }
+        if (gameTarget.mode && gameTarget.mode !== "semantic" && gameTarget.mode !== "visual") {
+            issues.push(`${label} (game "${gameTarget.name}") has unknown mode "${String(gameTarget.mode)}".`);
+        }
+        if (gameTarget.screenshotMode &&
+            gameTarget.screenshotMode !== "advisory" &&
+            gameTarget.screenshotMode !== "strict") {
+            issues.push(`${label} (game "${gameTarget.name}") has unknown screenshotMode "${String(gameTarget.screenshotMode)}" — use "advisory" or "strict".`);
+        }
+    },
+    doctorChecks: (target, cwd) => gameDoctorChecks(target, cwd)
+};

package/dist/captures/performance.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureType } from "./types.js";
+export declare const performance: CaptureType;

package/dist/captures/performance.js

@@ -0,0 +1,47 @@
+import path from "node:path";
+import { coerceSnapshot, renderPerformanceChange } from "../compare/shared.js";
+import { structuralChanges } from "../diff/structural.js";
+import { capturePerformance } from "../perf/capture.js";
+import { perfParserFor, perfParsers } from "../perf/parsers.js";
+import { canonicalizeRecord } from "../snapshot.js";
+function capturePerformanceTarget(target, { config, cwd }) {
+    return capturePerformance(target, {
+        cwd: path.resolve(cwd, target.cwd ?? "."),
+        timeoutMs: target.timeoutMs ?? config.lifecycle.wait.timeoutMs
+    });
+}
+// Performance snapshots compare numerically (within the configured tolerance)
+// and render each changed metric with its percentage delta — what a reviewer
+// reading a perf regression actually cares about.
+function comparePerformance(baseline, candidate, options) {
+    const changes = structuralChanges(baseline, candidate, {
+        numericTolerance: options.comparison.numericTolerance
+    });
+    return {
+        equal: changes.length === 0,
+        rendered: changes.map(renderPerformanceChange).join("\n")
+    };
+}
+export const performance = {
+    kind: "performance",
+    capture: (target, ctx) => capturePerformanceTarget(target, ctx),
+    // Performance snapshots have no dedicated canonical shape — they use the same
+    // generic record canonicalization (recurse, drop runtime metadata) as plain
+    // objects.
+    canonicalize: (value) => canonicalizeRecord(value),
+    compare: (baseline, candidate, options) => comparePerformance(coerceSnapshot(baseline), coerceSnapshot(candidate), options),
+    validateConfig: (target, { label, issues }) => {
+        const performanceTarget = target;
+        const tool = performanceTarget.tool ?? "k6";
+        const parser = perfParsers[tool];
+        if (!parser) {
+            issues.push(`${label} (performance "${performanceTarget.name}") uses unknown tool "${tool}". ` +
+                `Available: ${Object.keys(perfParsers).join(", ")}.`);
+            return;
+        }
+        for (const issue of parser.validate(performanceTarget)) {
+            issues.push(`${label} (performance "${performanceTarget.name}") ${issue}`);
+        }
+    },
+    doctorChecks: (target) => perfParserFor(target).doctorChecks(target)
+};

package/dist/captures/registry.d.ts

@@ -0,0 +1,4 @@
+import type { CaptureTarget } from "../config.js";
+import type { CaptureType } from "./types.js";
+export declare const captureTypes: Record<CaptureTarget["kind"], CaptureType>;
+export declare function isCaptureKind(value: unknown): value is CaptureTarget["kind"];

package/dist/captures/registry.js

@@ -0,0 +1,23 @@
+import { api } from "./api.js";
+import { check } from "./check.js";
+import { desktop } from "./desktop.js";
+import { game } from "./game.js";
+import { performance } from "./performance.js";
+import { terminal } from "./terminal.js";
+import { web } from "./web.js";
+// The single source of truth for capture kinds. Adding a capture type is one new
+// `src/captures/<kind>.ts` module exporting a `CaptureType`, plus one line here —
+// every dispatcher (capture, compare, canonicalize, doctor, config) routes
+// through this registry, so there is no per-kind branching to update.
+export const captureTypes = {
+    api,
+    check,
+    terminal,
+    web,
+    performance,
+    desktop,
+    game
+};
+export function isCaptureKind(value) {
+    return typeof value === "string" && Object.hasOwn(captureTypes, value);
+}

package/dist/captures/terminal.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureType } from "./types.js";
+export declare const terminal: CaptureType;

package/dist/captures/terminal.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { coerceSnapshot, compareStream } from "../compare/shared.js";
+import { canonicalizeSnapshot } from "../snapshot.js";
+import { captureTerminal } from "../terminal/capture.js";
+function captureTerminalTarget(target, { config, cwd }) {
+    return captureTerminal({
+        command: target.command,
+        cwd: path.resolve(cwd, target.cwd ?? "."),
+        timeoutMs: target.timeoutMs ?? config.lifecycle.wait.timeoutMs,
+        maskRules: config.normalization.masks
+    });
+}
+function compareTerminal(baseline, candidate, options) {
+    const sections = [];
+    if (baseline.exitCode !== candidate.exitCode) {
+        sections.push(`~ exitCode: ${String(baseline.exitCode)} → ${String(candidate.exitCode)}`);
+    }
+    if (baseline.signal !== candidate.signal) {
+        sections.push(`~ signal: ${String(baseline.signal)} → ${String(candidate.signal)}`);
+    }
+    for (const stream of ["stdout", "stderr"]) {
+        const change = compareStream(stream, baseline[stream], candidate[stream], options);
+        if (change) {
+            sections.push(change);
+        }
+    }
+    return {
+        equal: sections.length === 0,
+        rendered: sections.join("\n")
+    };
+}
+function validateTerminalTarget(target) {
+    return target.command.trim()
+        ? {
+            name: "terminal-target",
+            severity: "pass",
+            target: target.name,
+            message: `Terminal target "${target.name}" has a command.`
+        }
+        : {
+            name: "terminal-target",
+            severity: "fail",
+            target: target.name,
+            message: `Terminal target "${target.name}" is missing a command.`
+        };
+}
+export const terminal = {
+    kind: "terminal",
+    capture: (target, ctx) => captureTerminalTarget(target, ctx),
+    canonicalize: (value) => ({
+        kind: value.kind,
+        exitCode: value.exitCode,
+        signal: value.signal,
+        stdout: canonicalizeSnapshot(value.stdout),
+        stderr: canonicalizeSnapshot(value.stderr)
+    }),
+    compare: (baseline, candidate, options) => compareTerminal(coerceSnapshot(baseline), coerceSnapshot(candidate), options),
+    validateConfig: (target, { label, issues }) => {
+        const terminalTarget = target;
+        if (!terminalTarget.command || typeof terminalTarget.command !== "string") {
+            issues.push(`${label} (terminal "${terminalTarget.name}") must have a "command".`);
+        }
+    },
+    doctorChecks: (target) => [validateTerminalTarget(target)]
+};

package/dist/captures/types.d.ts

@@ -0,0 +1,18 @@
+import type { CaptureContext, SnapshotArtifact } from "../capture.js";
+import type { CompareOptions, SnapshotComparison } from "../compare/shared.js";
+import type { CaptureTarget } from "../config.js";
+import type { DoctorCheck } from "../doctor.js";
+export type ValidateConfigContext = {
+    label: string;
+    issues: string[];
+};
+export interface CaptureType {
+    kind: CaptureTarget["kind"];
+    hasScreenshots?: boolean;
+    parallelSafe?: boolean;
+    capture(target: CaptureTarget, ctx: CaptureContext): Promise<SnapshotArtifact>;
+    canonicalize(value: Record<string, unknown>): unknown;
+    compare(baseline: unknown, candidate: unknown, options: CompareOptions): SnapshotComparison;
+    validateConfig(target: CaptureTarget, ctx: ValidateConfigContext): void;
+    doctorChecks(target: CaptureTarget, cwd: string): DoctorCheck[] | Promise<DoctorCheck[]>;
+}

package/dist/captures/types.js

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

package/dist/captures/web.d.ts

@@ -0,0 +1,3 @@
+import type { CaptureType } from "./types.js";
+export declare function digestScreenshot(screenshot: Record<string, unknown>): unknown;
+export declare const web: CaptureType;