dungbeetle 0.1.1

package/dist/config.js

@@ -0,0 +1,382 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { BRAND_NAME } from "./brand.js";
+import { captureTypes, isCaptureKind } from "./captures/registry.js";
+import { parseJsonFile } from "./json.js";
+export const CONFIG_FILE_NAME = "dungbeetle.config.json";
+export const defaultMaskRules = [
+    {
+        name: "iso-timestamp",
+        pattern: "\\b\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z\\b",
+        replacement: "<iso-timestamp>"
+    },
+    {
+        name: "uuid",
+        pattern: "\\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\\b",
+        replacement: "<uuid>"
+    },
+    {
+        name: "unix-temp-path",
+        pattern: "/(?:var/)?tmp/[^\\s\"']+",
+        replacement: "<temp-path>"
+    },
+    {
+        name: "windows-temp-path",
+        pattern: "\\b[A-Za-z]:\\\\(?:Users\\\\[^\\\\]+\\\\AppData\\\\Local\\\\Temp|Temp)\\\\[^\\s\"']+",
+        replacement: "<temp-path>"
+    }
+];
+export function createDefaultConfig(projectName = "dungbeetle-project") {
+    return {
+        version: 1,
+        project: {
+            name: projectName
+        },
+        baselinesDir: "dungbeetle.snapshots",
+        artifactsDir: ".dungbeetle/artifacts",
+        lifecycle: {
+            setup: [],
+            start: [],
+            wait: {
+                timeoutMs: 30_000
+            },
+            capture: [],
+            teardown: []
+        },
+        normalization: {
+            ansi: "semantic",
+            masks: defaultMaskRules
+        },
+        comparison: {
+            numericTolerance: {},
+            pixelTolerance: {}
+        }
+    };
+}
+// The capture targets are modelled as a discriminated union on `kind` so zod
+// preserves each kind's field typing and strips nothing. Semantic rules
+// (driver values, image-source requirements, mask regex validity, tolerance
+// ranges) deliberately stay LENIENT here — `driver`, mask `pattern` and the
+// tolerance numbers are plain string/number so their bespoke, test-pinned error
+// messages keep coming from the retained registry/structural validators below,
+// not from zod. The union output is asserted back to `CaptureTarget`; the only
+// looseness vs. the hand-written type is `driver` (string vs. literal union),
+// which the registry validator narrows at runtime.
+const terminalCaptureSchema = z.object({
+    kind: z.literal("terminal"),
+    name: z.string(),
+    command: z.string(),
+    cwd: z.string().optional(),
+    timeoutMs: z.number().optional()
+});
+const pixelToleranceSchema = z.object({
+    maxChangedRatio: z.number().optional(),
+    perChannelThreshold: z.number().optional()
+});
+const webCaptureSchema = z.object({
+    kind: z.literal("web"),
+    name: z.string(),
+    driver: z.string().optional(),
+    url: z.string().optional(),
+    html: z.string().optional(),
+    screenshotFile: z.string().optional(),
+    screenshotMode: z.string().optional(),
+    pixelTolerance: pixelToleranceSchema.optional(),
+    accessibility: z.boolean().optional(),
+    screenshot: z.boolean().optional(),
+    browser: z
+        .object({
+        channel: z.string().optional(),
+        executablePath: z.string().optional()
+    })
+        .optional(),
+    viewport: z
+        .object({
+        width: z.number(),
+        height: z.number()
+    })
+        .optional(),
+    timeoutMs: z.number().optional()
+});
+const checkCaptureSchema = z.object({
+    kind: z.literal("check"),
+    name: z.string(),
+    tool: z.string(),
+    command: z.string().optional(),
+    output: z.string().optional(),
+    cwd: z.string().optional(),
+    timeoutMs: z.number().optional()
+});
+const performanceCaptureSchema = z.object({
+    kind: z.literal("performance"),
+    name: z.string(),
+    tool: z.string().optional(),
+    script: z.string().optional(),
+    command: z.string().optional(),
+    summary: z.string().optional(),
+    metrics: z.array(z.string()).optional(),
+    k6Path: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    cwd: z.string().optional(),
+    timeoutMs: z.number().optional()
+});
+const desktopCaptureSchema = z.object({
+    kind: z.literal("desktop"),
+    name: z.string(),
+    driver: z.string().optional(),
+    app: z.string().optional(),
+    tree: z.string().optional(),
+    command: z.string().optional(),
+    maxDepth: z.number().optional(),
+    ocrFallback: z.boolean().optional(),
+    screenshot: z.string().optional(),
+    screenshotCommand: z.string().optional(),
+    ocrCommand: z.string().optional(),
+    cwd: z.string().optional(),
+    timeoutMs: z.number().optional()
+});
+const gameCaptureSchema = z.object({
+    kind: z.literal("game"),
+    name: z.string(),
+    engine: z.string(),
+    project: z.string(),
+    walkthrough: z.string(),
+    mode: z.string().optional(),
+    enginePath: z.string().optional(),
+    seed: z.number().optional(),
+    physicsFps: z.number().optional(),
+    pixelTolerance: pixelToleranceSchema.optional(),
+    screenshotMode: z.string().optional(),
+    markers: z
+        .record(z.string(), z.object({ pixelTolerance: pixelToleranceSchema.optional() }))
+        .optional(),
+    timeoutMs: z.number().optional()
+});
+const apiCaptureSchema = z.object({
+    kind: z.literal("api"),
+    name: z.string(),
+    url: z.string(),
+    method: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    body: z.string().optional(),
+    query: z.string().optional(),
+    variables: z.record(z.string(), z.unknown()).optional(),
+    includeHeaders: z.array(z.string()).optional(),
+    timeoutMs: z.number().optional()
+});
+const captureTargetSchema = z
+    .discriminatedUnion("kind", [
+    apiCaptureSchema,
+    terminalCaptureSchema,
+    checkCaptureSchema,
+    webCaptureSchema,
+    performanceCaptureSchema,
+    desktopCaptureSchema,
+    gameCaptureSchema
+])
+    .transform((target) => target);
+const maskRuleSchema = z.object({
+    name: z.string(),
+    pattern: z.string(),
+    replacement: z.string()
+});
+// Nested objects use `.prefault({})` (not `.default({})`) so that when a parent
+// key is omitted the value is still parsed THROUGH the schema and its own inner
+// defaults fire — this nested-default chain IS the merge that replaces the old
+// hand-rolled deep spread. Leaf optional fields (e.g. tolerance keys, wait
+// command/url) carry NO default, so an omitted optional is ABSENT from the
+// output rather than set to `undefined`.
+function buildConfigSchema(defaultProjectName) {
+    return z
+        .object({
+        version: z.literal(1).default(1),
+        project: z
+            .object({
+            name: z.string().default(defaultProjectName)
+        })
+            .prefault({}),
+        baselinesDir: z.string().default("dungbeetle.snapshots"),
+        artifactsDir: z.string().default(".dungbeetle/artifacts"),
+        lifecycle: z
+            .object({
+            setup: z.array(z.string()).default([]),
+            start: z.array(z.string()).default([]),
+            wait: z
+                .object({
+                command: z.string().optional(),
+                url: z.string().optional(),
+                timeoutMs: z.number().default(30_000)
+            })
+                .prefault({}),
+            capture: z.array(captureTargetSchema).default([]),
+            teardown: z.array(z.string()).default([])
+        })
+            .prefault({}),
+        normalization: z
+            .object({
+            ansi: z.enum(["semantic", "strip"]).default("semantic"),
+            masks: z.array(maskRuleSchema).default(defaultMaskRules)
+        })
+            .prefault({}),
+        comparison: z
+            .object({
+            numericTolerance: z
+                .object({
+                absolute: z.number().optional(),
+                relative: z.number().optional()
+            })
+                .default({}),
+            pixelTolerance: z
+                .object({
+                maxChangedRatio: z.number().optional(),
+                perChannelThreshold: z.number().optional()
+            })
+                .default({})
+        })
+            .prefault({})
+    })
+        .strip();
+}
+export async function findConfigPath(cwd = process.cwd()) {
+    let current = path.resolve(cwd);
+    while (true) {
+        const candidate = path.join(current, CONFIG_FILE_NAME);
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current) {
+                return null;
+            }
+            current = parent;
+        }
+    }
+}
+export async function loadConfig(configPath, cwd = process.cwd()) {
+    const resolvedPath = configPath ? path.resolve(cwd, configPath) : await findConfigPath(cwd);
+    if (!resolvedPath) {
+        return createDefaultConfig(path.basename(cwd));
+    }
+    const raw = await readFile(resolvedPath, "utf8");
+    const data = parseJsonFile(raw, resolvedPath, (message) => {
+        throw new ConfigValidationError([message], resolvedPath);
+    });
+    // zod owns the structural shape, the defaults and the merge: nested
+    // `.prefault()`/`.default()` fill every omitted key from defaults, so the
+    // file is layered onto defaults without a hand-rolled spread. The project
+    // name falls back to the config dir's basename when omitted.
+    const schema = buildConfigSchema(path.basename(path.dirname(resolvedPath)));
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const issues = result.error.issues.map((issue) => {
+            const location = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+            return `${location}${issue.message}`;
+        });
+        throw new ConfigValidationError(issues, resolvedPath);
+    }
+    // The assignment is the compile-time drift guard: if the schema's parsed
+    // output stops being assignable to the hand-written DungbeetleConfig, tsc fails
+    // here.
+    const config = result.data;
+    // Retained semantic validation (per-kind registry validators + mask regex
+    // validity + tolerance ranges) runs AFTER zod so its bespoke, test-pinned
+    // error messages are preserved.
+    validateConfig(config, resolvedPath);
+    return config;
+}
+export class ConfigValidationError extends Error {
+    issues;
+    configPath;
+    constructor(issues, configPath) {
+        const location = configPath ? ` in ${configPath}` : "";
+        super(`Invalid ${BRAND_NAME} config${location}:\n- ${issues.join("\n- ")}`);
+        this.issues = issues;
+        this.configPath = configPath;
+        this.name = "ConfigValidationError";
+    }
+}
+export function validateConfig(config, configPath) {
+    const issues = [];
+    if (!config.project.name || typeof config.project.name !== "string") {
+        issues.push("project.name must be a non-empty string.");
+    }
+    if (typeof config.baselinesDir !== "string" || !config.baselinesDir) {
+        issues.push("baselinesDir must be a non-empty string.");
+    }
+    if (!Number.isFinite(config.lifecycle.wait.timeoutMs) || config.lifecycle.wait.timeoutMs <= 0) {
+        issues.push("lifecycle.wait.timeoutMs must be a positive number.");
+    }
+    if (!Array.isArray(config.lifecycle.capture)) {
+        issues.push("lifecycle.capture must be an array.");
+    }
+    else {
+        config.lifecycle.capture.forEach((target, index) => {
+            validateCaptureTarget(target, index, issues);
+        });
+    }
+    for (const phase of ["setup", "start", "teardown"]) {
+        if (!Array.isArray(config.lifecycle[phase])) {
+            issues.push(`lifecycle.${phase} must be an array of command strings.`);
+        }
+    }
+    for (const key of ["absolute", "relative"]) {
+        const value = config.comparison.numericTolerance[key];
+        if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+            issues.push(`comparison.numericTolerance.${key} must be a non-negative number.`);
+        }
+    }
+    const { maxChangedRatio, perChannelThreshold } = config.comparison.pixelTolerance;
+    if (maxChangedRatio !== undefined &&
+        (!Number.isFinite(maxChangedRatio) || maxChangedRatio < 0 || maxChangedRatio > 1)) {
+        issues.push("comparison.pixelTolerance.maxChangedRatio must be between 0 and 1.");
+    }
+    if (perChannelThreshold !== undefined &&
+        (!Number.isFinite(perChannelThreshold) || perChannelThreshold < 0 || perChannelThreshold > 255)) {
+        issues.push("comparison.pixelTolerance.perChannelThreshold must be between 0 and 255.");
+    }
+    if (!Array.isArray(config.normalization.masks)) {
+        issues.push("normalization.masks must be an array.");
+    }
+    else {
+        config.normalization.masks.forEach((mask, index) => {
+            if (!mask || typeof mask.pattern !== "string" || typeof mask.replacement !== "string") {
+                issues.push(`normalization.masks[${index}] must have string "pattern" and "replacement".`);
+                return;
+            }
+            try {
+                new RegExp(mask.pattern);
+            }
+            catch (error) {
+                issues.push(`normalization.masks[${index}] has an invalid pattern: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
+    if (issues.length > 0) {
+        throw new ConfigValidationError(issues, configPath);
+    }
+}
+function validateCaptureTarget(target, index, issues) {
+    const label = `lifecycle.capture[${index}]`;
+    if (!target || typeof target !== "object") {
+        issues.push(`${label} must be an object.`);
+        return;
+    }
+    if (!target.name || typeof target.name !== "string") {
+        issues.push(`${label} must have a non-empty "name".`);
+    }
+    if (!isCaptureKind(target.kind)) {
+        issues.push(`${label} has unknown kind "${target.kind ?? ""}".`);
+        return;
+    }
+    captureTypes[target.kind].validateConfig(target, { label, issues });
+}
+export async function writeDefaultConfig(outputPath = CONFIG_FILE_NAME, projectName = path.basename(process.cwd()), targets = []) {
+    const resolvedPath = path.resolve(outputPath);
+    const config = createDefaultConfig(projectName);
+    config.lifecycle.capture = targets;
+    await writeFile(resolvedPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return resolvedPath;
+}

package/dist/desktop/a11y.d.ts

@@ -0,0 +1,18 @@
+import type { MaskRule } from "../config.js";
+export type A11yNode = {
+    role: string;
+    name?: string;
+    value?: string;
+    description?: string;
+    state?: string[];
+    children: A11yNode[];
+};
+export type DesktopSnapshot = {
+    kind: "desktop";
+    tool?: string;
+    root: A11yNode;
+};
+export type NormalizeA11yOptions = {
+    maskRules?: MaskRule[];
+};
+export declare function normalizeA11yTree(raw: unknown, options?: NormalizeA11yOptions): DesktopSnapshot;

package/dist/desktop/a11y.js

@@ -0,0 +1,74 @@
+import { applyMaskRules } from "../normalization.js";
+import { isRecord } from "../guards.js";
+export function normalizeA11yTree(raw, options = {}) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid desktop snapshot: expected an object.");
+    }
+    // Accept either a bare tree or a wrapper of the form { tool?, root }.
+    const tool = typeof raw.tool === "string" ? raw.tool : undefined;
+    const rootSource = isRecord(raw.root) ? raw.root : raw;
+    const snapshot = {
+        kind: "desktop",
+        root: normalizeNode(rootSource, options.maskRules ?? [])
+    };
+    if (tool) {
+        snapshot.tool = tool;
+    }
+    return snapshot;
+}
+function normalizeNode(raw, masks) {
+    if (!isRecord(raw)) {
+        throw new Error("Invalid accessibility node: expected an object.");
+    }
+    const role = pickString(raw.role ?? raw.type) ?? "unknown";
+    const node = {
+        role,
+        children: normalizeChildren(raw.children, masks)
+    };
+    const name = maskOptional(pickString(raw.name ?? raw.title ?? raw.label), masks);
+    if (name !== undefined) {
+        node.name = name;
+    }
+    const value = maskOptional(pickString(raw.value), masks);
+    if (value !== undefined) {
+        node.value = value;
+    }
+    const description = maskOptional(pickString(raw.description ?? raw.help), masks);
+    if (description !== undefined) {
+        node.description = description;
+    }
+    const state = normalizeState(raw.state);
+    if (state.length > 0) {
+        node.state = state;
+    }
+    return node;
+}
+function normalizeChildren(raw, masks) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter(isRecord).map((child) => normalizeNode(child, masks));
+}
+// Normalize the state to a sorted, de-duplicated list of flag names so the
+// representation is stable regardless of input ordering or shape (array of
+// strings, or an object of boolean flags).
+function normalizeState(raw) {
+    if (Array.isArray(raw)) {
+        return dedupeSort(raw.filter((value) => typeof value === "string"));
+    }
+    if (isRecord(raw)) {
+        return dedupeSort(Object.entries(raw)
+            .filter(([, value]) => value === true)
+            .map(([key]) => key));
+    }
+    return [];
+}
+function dedupeSort(values) {
+    return [...new Set(values)].sort();
+}
+function maskOptional(value, masks) {
+    return value === undefined ? undefined : applyMaskRules(value, masks);
+}
+function pickString(value) {
+    return typeof value === "string" ? value : undefined;
+}

package/dist/desktop/capture.d.ts

@@ -0,0 +1,13 @@
+import type { CaptureTarget, MaskRule } from "../config.js";
+import { type DesktopSnapshot } from "./a11y.js";
+import { type ShellRunner } from "./ocr.js";
+export type DesktopTarget = Extract<CaptureTarget, {
+    kind: "desktop";
+}>;
+export type DesktopCaptureOptions = {
+    cwd: string;
+    timeoutMs: number;
+    maskRules: MaskRule[];
+    run?: ShellRunner;
+};
+export declare function captureDesktop(target: DesktopTarget, options: DesktopCaptureOptions): Promise<DesktopSnapshot>;

package/dist/desktop/capture.js

@@ -0,0 +1,80 @@
+import { exec } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { parseJsonFile } from "../json.js";
+import { normalizeA11yTree } from "./a11y.js";
+import { captureMacosAx } from "./macos.js";
+import { captureDesktopOcr } from "./ocr.js";
+const execAsync = promisify(exec);
+// Capture a desktop accessibility snapshot. The primary source is one of: the
+// macOS AX driver, a saved tree JSON file (`tree`), or a command that prints an
+// accessibility tree as JSON (`command`). For targets without reliable
+// structured access, a screenshot + OCR path produces an equivalent snapshot —
+// either directly (`driver: "ocr"`) or as a fallback (`ocrFallback: true`) when
+// the structured capture comes back empty or fails.
+export async function captureDesktop(target, options) {
+    if (target.driver === "ocr") {
+        return captureDesktopOcr(toOcrOptions(target, options));
+    }
+    if (!target.ocrFallback) {
+        return captureStructured(target, options);
+    }
+    // Fallback mode: prefer the structured tree, but drop to pixels + OCR when it
+    // yields nothing usable (an app the accessibility API can't see into) or the
+    // capture throws (e.g. permission denied). The OCR error surfaces if that path
+    // also fails — the caller opted into the fallback.
+    try {
+        const snapshot = await captureStructured(target, options);
+        if (snapshot.root.children.length === 0) {
+            return captureDesktopOcr(toOcrOptions(target, options));
+        }
+        return snapshot;
+    }
+    catch {
+        return captureDesktopOcr(toOcrOptions(target, options));
+    }
+}
+function toOcrOptions(target, options) {
+    return {
+        app: target.app,
+        screenshot: target.screenshot,
+        screenshotCommand: target.screenshotCommand,
+        ocrCommand: target.ocrCommand,
+        cwd: options.cwd,
+        timeoutMs: target.timeoutMs ?? options.timeoutMs,
+        maskRules: options.maskRules,
+        run: options.run
+    };
+}
+async function captureStructured(target, options) {
+    let raw;
+    if (target.driver === "macos-ax") {
+        raw = await captureMacosAx({
+            app: target.app ?? "",
+            maxDepth: target.maxDepth,
+            timeoutMs: target.timeoutMs ?? options.timeoutMs
+        });
+    }
+    else if (target.tree) {
+        const treePath = path.resolve(options.cwd, target.tree);
+        raw = parseJsonFile(await readFile(treePath, "utf8"), treePath);
+    }
+    else if (target.command) {
+        const { stdout } = await execAsync(target.command, {
+            cwd: path.resolve(options.cwd, target.cwd ?? "."),
+            timeout: target.timeoutMs ?? options.timeoutMs,
+            maxBuffer: 32 * 1024 * 1024
+        });
+        try {
+            raw = JSON.parse(stdout);
+        }
+        catch {
+            throw new Error(`Desktop target "${target.name}" command did not emit valid JSON on stdout.`);
+        }
+    }
+    else {
+        throw new Error(`Desktop target "${target.name}" must set a "driver", "tree", or "command".`);
+    }
+    return normalizeA11yTree(raw, { maskRules: options.maskRules });
+}

package/dist/desktop/macos.d.ts

@@ -0,0 +1,8 @@
+export declare const MACOS_AX_JXA = "\nfunction run(argv) {\n  var appName = argv[0];\n  var maxDepth = parseInt(argv[1], 10);\n  if (isNaN(maxDepth)) { maxDepth = 40; }\n\n  var se = Application('System Events');\n  var procs = se.applicationProcesses.whose({ name: appName })();\n  if (!procs.length) {\n    return JSON.stringify({ error: 'process-not-found', app: appName });\n  }\n  var proc = procs[0];\n\n  function read(el, fn) {\n    try { var v = fn(el); return v == null ? '' : String(v); } catch (e) { return ''; }\n  }\n\n  function walk(el, depth) {\n    if (depth > maxDepth) { return null; }\n    var node = { role: read(el, function (e) { return e.role(); }) || 'AXUnknown' };\n    var name = read(el, function (e) { return e.title(); })\n      || read(el, function (e) { return e.name(); })\n      || read(el, function (e) { return e.description(); });\n    if (name) { node.name = name; }\n    var value = read(el, function (e) { return e.value(); });\n    if (value) { node.value = value; }\n\n    var children = [];\n    var kids = [];\n    try { kids = el.uiElements(); } catch (e) { kids = []; }\n    for (var i = 0; i < kids.length; i++) {\n      var child = walk(kids[i], depth + 1);\n      if (child) { children.push(child); }\n    }\n    node.children = children;\n    return node;\n  }\n\n  var root = { role: 'AXApplication', name: appName, children: [] };\n  var windows = [];\n  try { windows = proc.windows(); } catch (e) { windows = []; }\n  for (var w = 0; w < windows.length; w++) {\n    var win = walk(windows[w], 0);\n    if (win) { root.children.push(win); }\n  }\n\n  return JSON.stringify({ tool: 'macos-ax', root: root });\n}\n";
+export type MacosAxOptions = {
+    app: string;
+    maxDepth?: number;
+    timeoutMs?: number;
+    platform?: NodeJS.Platform;
+};
+export declare function captureMacosAx(options: MacosAxOptions): Promise<unknown>;

package/dist/desktop/macos.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { isRecord } from "../guards.js";
+const execFileAsync = promisify(execFile);
+// JXA (JavaScript for Automation) script run via `osascript -l JavaScript`. It
+// walks a process's accessibility tree through System Events and prints a JSON
+// tree in the shape normalizeA11yTree() accepts. Kept as a string so it ships
+// with the compiled CLI (no sidecar resource file to copy into dist).
+//
+// argv: [appName, maxDepth]
+export const MACOS_AX_JXA = `
+function run(argv) {
+  var appName = argv[0];
+  var maxDepth = parseInt(argv[1], 10);
+  if (isNaN(maxDepth)) { maxDepth = 40; }
+
+  var se = Application('System Events');
+  var procs = se.applicationProcesses.whose({ name: appName })();
+  if (!procs.length) {
+    return JSON.stringify({ error: 'process-not-found', app: appName });
+  }
+  var proc = procs[0];
+
+  function read(el, fn) {
+    try { var v = fn(el); return v == null ? '' : String(v); } catch (e) { return ''; }
+  }
+
+  function walk(el, depth) {
+    if (depth > maxDepth) { return null; }
+    var node = { role: read(el, function (e) { return e.role(); }) || 'AXUnknown' };
+    var name = read(el, function (e) { return e.title(); })
+      || read(el, function (e) { return e.name(); })
+      || read(el, function (e) { return e.description(); });
+    if (name) { node.name = name; }
+    var value = read(el, function (e) { return e.value(); });
+    if (value) { node.value = value; }
+
+    var children = [];
+    var kids = [];
+    try { kids = el.uiElements(); } catch (e) { kids = []; }
+    for (var i = 0; i < kids.length; i++) {
+      var child = walk(kids[i], depth + 1);
+      if (child) { children.push(child); }
+    }
+    node.children = children;
+    return node;
+  }
+
+  var root = { role: 'AXApplication', name: appName, children: [] };
+  var windows = [];
+  try { windows = proc.windows(); } catch (e) { windows = []; }
+  for (var w = 0; w < windows.length; w++) {
+    var win = walk(windows[w], 0);
+    if (win) { root.children.push(win); }
+  }
+
+  return JSON.stringify({ tool: 'macos-ax', root: root });
+}
+`;
+// Capture a macOS application's accessibility tree. Requires macOS, and the
+// process running Dungbeetle must be granted Accessibility (and Automation)
+// permission in System Settings → Privacy & Security. This is an experimental,
+// local-only driver — it cannot run headless in CI.
+export async function captureMacosAx(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin") {
+        throw new Error(`The "macos-ax" desktop driver is only supported on macOS (current platform: ${platform}).`);
+    }
+    let stdout;
+    try {
+        ({ stdout } = await execFileAsync("osascript", ["-l", "JavaScript", "-e", MACOS_AX_JXA, options.app, String(options.maxDepth ?? 40)], { timeout: options.timeoutMs ?? 30_000, maxBuffer: 64 * 1024 * 1024 }));
+    }
+    catch (error) {
+        throw new Error(translateOsascriptError(error, options.app));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`macOS accessibility capture for "${options.app}" did not return JSON.`);
+    }
+    if (isRecord(parsed) && parsed.error === "process-not-found") {
+        throw new Error(`App "${options.app}" is not running; launch it before capturing its accessibility tree.`);
+    }
+    return parsed;
+}
+function translateOsascriptError(error, app) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/ENOENT/.test(message)) {
+        return `Could not run "osascript"; the macos-ax driver requires macOS.`;
+    }
+    // -25211 / "assistive access" is macOS's accessibility-permission error.
+    if (/-25211|assistive access|not allowed/i.test(message)) {
+        return `Accessibility permission denied. Grant the terminal/Node process Accessibility access in System Settings → Privacy & Security → Accessibility, then retry capturing "${app}".`;
+    }
+    return `macOS accessibility capture for "${app}" failed: ${message}`;
+}