@celestea/tools 2.7.1

package/dist/browser/session.js

@@ -0,0 +1,371 @@
+/**
+ * F4 step 2b: one SESSION's headless browser, launched THROUGH the sandbox.
+ *
+ * Why through the sandbox: the browser is the one workload that must run with
+ * `noAddressSpaceLimit: true` (step 2a) and, on the bwrap provider, with a
+ * SHARED network namespace (the DevTools ws:// endpoint lives on 127.0.0.1 and
+ * would be unreachable inside `--unshare-all`). Both facts are asserted here,
+ * never inferred: `spawned.sandbox.net_isolated === true` refuses the call with
+ * a structured `network_required` error instead of silently failing to connect.
+ *
+ * Lifecycle: the browser child is registered in the session ProcessRegistry, so
+ * the host's existing shutdown hook (`processes.dispose()`) reaps it; the
+ * manager ALSO exposes `dispose()` and removes the profile dir as soon as the
+ * child exits. No orphan is left behind.
+ *
+ * The result carries an explicit isolation block: the RLIMIT_AS exemption and
+ * the memory backstop are stated in the VALUE, so a caller can never mistake an
+ * exempted call for a sandboxed one.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { contractFailure } from "../errors.js";
+import { resolveShellKind } from "../platform/exec.js";
+import { quoteWord } from "../platform/quote.js";
+import { delay, TIMED_OUT, withTimeout } from "../sandbox/async.js";
+import { CdpClient } from "./cdp.js";
+import { attachBrowser, findHeadlessShell, parseDevToolsEndpoint } from "./launch.js";
+import { armMemoryGuard, DEFAULT_BROWSER_MEMORY_MB } from "./memory-guard.js";
+import { buildAxSnapshot, collectBoxes, isInteractiveRole } from "./snapshot.js";
+/** Default cap on rendered AX nodes / bytes (step 1's limits). */
+export const DEFAULT_BROWSER_MAX_NODES = 200;
+export const DEFAULT_BROWSER_MAX_BYTES = 32 * 1024;
+/** Default wait for the DevTools endpoint. */
+export const DEFAULT_BROWSER_STARTUP_MS = 20_000;
+/** Grace between terminate() and kill() when disposing. */
+export const DEFAULT_BROWSER_DISPOSE_GRACE_MS = 3_000;
+/** How long to wait for document.readyState after navigate. */
+export const DEFAULT_NAVIGATE_TIMEOUT_MS = 20_000;
+/** The model-visible sentence that must appear on every browser result. */
+export const ADDRESS_SPACE_NOTE = "RLIMIT_AS is EXEMPTED for this browser process (noAddressSpaceLimit=true): its virtual address space is NOT bounded by the sandbox.";
+/** Per-session browser owner. One instance is shared by both browser tools. */
+export class BrowserManager {
+    options;
+    session = null;
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Open (or reuse) the page and return its snapshot + screenshot. */
+    async open(url, viewport) {
+        const session = await this.ensure();
+        if (viewport !== undefined) {
+            await session.client.setDeviceMetricsOverride({ width: viewport.width, height: viewport.height }, session.sessionId);
+        }
+        await this.navigate(session, url);
+        return this.capture(session);
+    }
+    /** Act on the page opened by [open]; returns the updated snapshot. */
+    async act(request) {
+        const session = this.session;
+        if (session === null || session.exited) {
+            throw contractFailure("browser", "no_page", "no browser page is open; call browser_open first");
+        }
+        await this.perform(session, request);
+        await delay(150);
+        return this.capture(session);
+    }
+    /** Reclaim the browser: terminate the tree, wait, kill, remove the profile. */
+    async dispose() {
+        const session = this.session;
+        this.session = null;
+        this.disposed = true;
+        if (session === null)
+            return;
+        session.guard.dispose();
+        session.client.close();
+        try {
+            session.child.terminate();
+        }
+        catch {
+            /* already gone */
+        }
+        const exit = await withTimeout(session.child.wait(), this.graceMs);
+        if (exit === TIMED_OUT) {
+            try {
+                session.child.kill();
+            }
+            catch {
+                /* already gone */
+            }
+            await withTimeout(session.child.wait(), this.graceMs);
+        }
+        removeDir(session.profileDir);
+    }
+    /** True while a live browser is attached (diagnostics / tests). */
+    get running() {
+        return this.session !== null && !this.session.exited;
+    }
+    // ---- launch / attach -------------------------------------------------------
+    async ensure() {
+        if (this.session !== null && !this.session.exited)
+            return this.session;
+        if (this.disposed)
+            throw contractFailure("browser", "disposed", "this browser manager was disposed");
+        const executable = (this.options.findExecutable ?? findHeadlessShell)();
+        if (executable === null || executable === undefined || executable === "") {
+            throw contractFailure("browser", "browser_unavailable", "no chrome-headless-shell found; install Playwright chromium or set an executable path");
+        }
+        const profileDir = mkdtempSync(join(tmpdir(), "celestea-browser-"));
+        const spawned = await this.spawnBrowser(this.browserCommand(executable, profileDir));
+        if (spawned.sandbox.net_isolated) {
+            spawned.child.kill();
+            removeDir(profileDir);
+            throw contractFailure("browser", "network_required", "the sandbox is network-isolated (net_isolated=true), so the browser's DevTools endpoint on 127.0.0.1 is unreachable; grant this session the 'network' capability (grants.network / CELESTEA_SANDBOX_NET=1) so the sandbox shares the host network");
+        }
+        let client;
+        try {
+            const endpoint = await this.readEndpoint(spawned.child);
+            client = await (this.options.attach ?? defaultAttach)(endpoint);
+        }
+        catch (error) {
+            spawned.child.kill();
+            removeDir(profileDir);
+            throw error;
+        }
+        const guard = armMemoryGuard({ pid: spawned.child.pid, limitMb: this.memoryLimitMb });
+        const session = {
+            child: spawned.child,
+            client,
+            targetId: "",
+            sessionId: "",
+            meta: spawned.sandbox,
+            profileDir,
+            guard,
+            refs: new Map(),
+            exited: false,
+        };
+        this.session = session;
+        void spawned.child.wait().then(() => {
+            session.exited = true;
+            guard.dispose();
+            removeDir(profileDir);
+        });
+        this.options.processes?.insert(spawned.child, false);
+        const target = await client.createTarget("about:blank");
+        const attached = await client.attachToTarget(target.targetId);
+        session.targetId = target.targetId;
+        session.sessionId = attached.sessionId;
+        await client.pageEnable(session.sessionId);
+        await client.runtimeEnable(session.sessionId);
+        await client.accessibilityEnable(session.sessionId);
+        return session;
+    }
+    spawnBrowser(command) {
+        if (this.options.spawn !== undefined)
+            return this.options.spawn(command);
+        // HARD REQUIREMENT (F4 step 2a): the browser cannot start under RLIMIT_AS.
+        return this.options.sandbox.spawn({ command, noAddressSpaceLimit: true });
+    }
+    browserCommand(executable, profileDir) {
+        const kind = resolveShellKind(this.options.sandbox.shell ?? {}).kind;
+        const words = [
+            executable,
+            "--headless",
+            "--no-sandbox",
+            "--disable-gpu",
+            "--remote-debugging-port=0",
+            "--user-data-dir=" + profileDir,
+            "about:blank",
+        ];
+        return words.map((word) => quoteWord(kind, word)).join(" ");
+    }
+    readEndpoint(child) {
+        return new Promise((resolve, reject) => {
+            let buffer = "";
+            let settled = false;
+            const finish = (endpoint, error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (error === null)
+                    resolve(endpoint);
+                else
+                    reject(error);
+            };
+            const timer = setTimeout(() => {
+                finish(null, contractFailure("browser", "browser_startup", "browser did not print a DevTools endpoint within " + this.startupMs + "ms; stderr tail: " + tail(buffer)));
+            }, this.startupMs);
+            timer.unref();
+            child.stderr?.on("data", (chunk) => {
+                buffer += String(chunk);
+                const endpoint = parseDevToolsEndpoint(buffer);
+                if (endpoint !== null)
+                    finish(endpoint, null);
+            });
+            void child.wait().then((exit) => {
+                finish(null, contractFailure("browser", "browser_startup", "browser exited code=" + String(exit.code) + " before a DevTools endpoint; stderr tail: " + tail(buffer)));
+            });
+        });
+    }
+    // ---- page operations -------------------------------------------------------
+    async navigate(session, url) {
+        await session.client.navigate(url, session.sessionId);
+        const deadline = Date.now() + this.navigateMs;
+        while (Date.now() < deadline) {
+            const state = await session.client.evaluate("document.readyState", session.sessionId).catch(() => null);
+            if (state === "complete")
+                return;
+            await delay(50);
+        }
+    }
+    async perform(session, request) {
+        const ref = request.ref === undefined ? undefined : session.refs.get(request.ref);
+        if (request.action !== "key" && request.action !== "scroll" && ref === undefined) {
+            throw contractFailure("browser", "unknown_ref", "ref '" + String(request.ref) + "' is unknown; take a browser_open snapshot first");
+        }
+        if (request.action === "click")
+            await this.click(session, ref);
+        else if (request.action === "type")
+            await this.typeText(session, ref, request.text ?? "");
+        else if (request.action === "key")
+            await this.key(session, request.key ?? "Enter");
+        else
+            await this.scroll(session, ref, request.deltaX ?? 0, request.deltaY ?? 0);
+    }
+    async click(session, ref) {
+        const box = ref.box ?? (await this.boxOf(session, ref));
+        if (box === null)
+            throw contractFailure("browser", "no_box", "ref '" + ref.ref + "' has no layout box (not visible?)");
+        const x = Math.round(box.x + box.width / 2);
+        const y = Math.round(box.y + box.height / 2);
+        await session.client.dispatchMouseEvent({ type: "mousePressed", x, y, button: "left", clickCount: 1 }, session.sessionId);
+        await session.client.dispatchMouseEvent({ type: "mouseReleased", x, y, button: "left", clickCount: 1 }, session.sessionId);
+    }
+    async typeText(session, ref, text) {
+        const backend = ref.backendDOMNodeId;
+        if (backend === null)
+            throw contractFailure("browser", "no_node", "ref '" + ref.ref + "' has no backend node id");
+        await session.client.send("DOM.focus", { backendNodeId: backend }, session.sessionId);
+        await session.client.insertText(text, session.sessionId);
+    }
+    async key(session, key) {
+        await session.client.dispatchKeyEvent({ type: "keyDown", key }, session.sessionId);
+        await session.client.dispatchKeyEvent({ type: "keyUp", key }, session.sessionId);
+    }
+    async scroll(session, ref, deltaX, deltaY) {
+        let x = 400;
+        let y = 300;
+        if (ref !== undefined) {
+            const box = ref.box ?? (await this.boxOf(session, ref));
+            if (box !== null) {
+                x = Math.round(box.x + box.width / 2);
+                y = Math.round(box.y + box.height / 2);
+            }
+        }
+        await session.client.dispatchMouseEvent({ type: "mouseWheel", x, y, deltaX, deltaY }, session.sessionId);
+    }
+    async boxOf(session, ref) {
+        if (ref.backendDOMNodeId === null)
+            return null;
+        const model = await session.client.getBoxModel(ref.backendDOMNodeId, session.sessionId).catch(() => null);
+        if (model === null)
+            return null;
+        const quad = model.content.map(Number);
+        if (quad.length < 8)
+            return null;
+        const xs = [quad[0], quad[2], quad[4], quad[6]];
+        const ys = [quad[1], quad[3], quad[5], quad[7]];
+        const minX = Math.min(...xs);
+        const minY = Math.min(...ys);
+        return { x: minX, y: minY, width: Math.max(...xs) - minX, height: Math.max(...ys) - minY };
+    }
+    // ---- snapshot + screenshot -------------------------------------------------
+    async capture(session) {
+        const nodes = await session.client.getFullAXTree(session.sessionId);
+        const interactive = nodes.filter((node) => node.ignored !== true && isInteractiveRole(node.role?.value ?? "")).slice(0, this.maxNodes);
+        const boxes = await collectBoxes(session.client, interactive, session.sessionId);
+        const snap = buildAxSnapshot(nodes, { boxes, maxNodes: this.maxNodes, maxBytes: this.maxBytes });
+        session.refs = new Map(snap.refs.map((ref) => [ref.ref, ref]));
+        const title = await session.client.evaluate("document.title", session.sessionId).catch(() => "");
+        const url = await session.client.evaluate("location.href", session.sessionId).catch(() => "");
+        const shot = await this.screenshot(session);
+        return {
+            ok: true,
+            url: typeof url === "string" ? url : "",
+            title: typeof title === "string" ? title : "",
+            snapshot: {
+                text: snap.text,
+                refs: snap.refs.map((ref) => ({
+                    ref: ref.ref,
+                    role: ref.role,
+                    name: ref.name,
+                    backend_dom_node_id: ref.backendDOMNodeId,
+                    box: ref.box,
+                })),
+                truncated: snap.truncated,
+                truncation_reason: snap.truncationReason,
+                total_nodes: snap.totalNodes,
+                included_nodes: snap.includedNodes,
+            },
+            ...shot,
+            isolation: this.isolation(session),
+            notes: this.notes(shot.screenshot),
+        };
+    }
+    async screenshot(session) {
+        const store = this.options.attachments;
+        if (store === undefined || store === null)
+            return { screenshot: null, attachments: [] };
+        const shot = await session.client.captureScreenshot(session.sessionId);
+        const bytes = Buffer.from(shot.data, "base64");
+        const ref = await store.put({ bytes, name: "browser-" + Date.now() + ".png" });
+        return {
+            screenshot: { attachment_id: ref.attachment_id, media_type: ref.media_type, width: ref.width, height: ref.height, bytes: bytes.length },
+            attachments: [ref],
+        };
+    }
+    isolation(session) {
+        return {
+            provider: session.meta.provider,
+            net_isolated: session.meta.net_isolated,
+            tmp_private: session.meta.tmp_private,
+            seccomp: session.meta.seccomp,
+            address_space_limit: "exempted",
+            address_space_note: ADDRESS_SPACE_NOTE,
+            memory_guard: session.guard.status(),
+        };
+    }
+    notes(screenshot) {
+        const notes = [ADDRESS_SPACE_NOTE];
+        if (screenshot === null)
+            notes.push("no attachment store: the screenshot was not captured (the accessibility snapshot is still returned)");
+        return notes;
+    }
+    // ---- option accessors ------------------------------------------------------
+    get startupMs() {
+        return this.options.startupTimeoutMs ?? DEFAULT_BROWSER_STARTUP_MS;
+    }
+    get navigateMs() {
+        return this.options.navigateTimeoutMs ?? DEFAULT_NAVIGATE_TIMEOUT_MS;
+    }
+    get graceMs() {
+        return this.options.disposeGraceMs ?? DEFAULT_BROWSER_DISPOSE_GRACE_MS;
+    }
+    get memoryLimitMb() {
+        return this.options.memoryLimitMb ?? DEFAULT_BROWSER_MEMORY_MB;
+    }
+    get maxNodes() {
+        return this.options.maxNodes ?? DEFAULT_BROWSER_MAX_NODES;
+    }
+    get maxBytes() {
+        return this.options.maxBytes ?? DEFAULT_BROWSER_MAX_BYTES;
+    }
+}
+async function defaultAttach(endpoint) {
+    const attached = await attachBrowser(endpoint);
+    return attached.client;
+}
+function removeDir(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        /* best effort */
+    }
+}
+function tail(text, max = 800) {
+    return text.length > max ? text.slice(text.length - max) : text;
+}

package/dist/browser/snapshot.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Accessibility-tree snapshot (F4 slice 1).
+ *
+ * A raw Accessibility.getFullAXTree is unusable as model input: the measured
+ * Studio home page is 3687 nodes / 1.23MB. This module turns it into a BOUNDED
+ * text snapshot where every interactive node carries a stable ref (e1, e2, ...)
+ * plus its box, so click/type can target a ref instead of raw coordinates.
+ *
+ * Hard limits: a node cap and a byte cap. Both are explicit in the result
+ * (truncated / truncationReason) and the text ends with a visible note -- a
+ * silently clipped snapshot would make the model act on an incomplete page.
+ *
+ * Pure: no CDP, no filesystem. Boxes are injected (collectBoxes fills them from
+ * DOM.getBoxModel when a caller has a live session).
+ */
+import type { AxNode, BoundingBox, BoxModel } from "./types.js";
+/** Default cap on rendered nodes. */
+export declare const DEFAULT_MAX_NODES = 200;
+/** Default cap on rendered UTF-8 bytes. */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Longest name kept per node (the rest is elided). */
+export declare const MAX_NAME_CHARS = 120;
+/** Roles that receive a ref (clickable / typeable). */
+export declare const INTERACTIVE_ROLES: ReadonlySet<string>;
+/** Roles rendered as context (no ref) when they carry a name. */
+export declare const CONTEXT_ROLES: ReadonlySet<string>;
+/** One addressable element in the snapshot. */
+export interface SnapshotRef {
+    ref: string;
+    role: string;
+    name: string;
+    backendDOMNodeId: number | null;
+    box: BoundingBox | null;
+}
+/** The bounded result handed to the model. */
+export interface AxSnapshot {
+    text: string;
+    refs: SnapshotRef[];
+    totalNodes: number;
+    includedNodes: number;
+    omittedNodes: number;
+    truncated: boolean;
+    truncationReason: string | null;
+}
+export interface SnapshotOptions {
+    maxNodes?: number;
+    maxBytes?: number;
+    /** Boxes keyed by backendDOMNodeId (see collectBoxes). */
+    boxes?: ReadonlyMap<number, BoundingBox>;
+}
+/** true when a role can be clicked or typed into. */
+export declare function isInteractiveRole(role: string): boolean;
+/** Role of a node (CDP omits it for some ignored nodes). */
+export declare function roleOf(node: AxNode): string;
+/** Collapsed, trimmed, elided accessible name. */
+export declare function nameOf(node: AxNode): string;
+/**
+ * Build the bounded snapshot. Iterates the tree in its given order (CDP returns
+ * pre-order), so refs are stable for an unchanged tree.
+ */
+export declare function buildAxSnapshot(nodes: readonly AxNode[], options?: SnapshotOptions): AxSnapshot;
+/** The slice of CdpClient collectBoxes needs (structural, avoids a cycle). */
+export interface BoxSource {
+    getBoxModel(backendNodeId: number, sessionId: string): Promise<BoxModel | null>;
+}
+/** Fetch a box per distinct backendDOMNodeId; a failed lookup is simply absent. */
+export declare function collectBoxes(source: BoxSource, nodes: readonly AxNode[], sessionId: string): Promise<Map<number, BoundingBox>>;
+/** The axis-aligned bounds of a CDP content quad ([x1,y1,x2,y2,x3,y3,x4,y4]). */
+export declare function quadToBox(quad: readonly number[]): BoundingBox | null;

package/dist/browser/snapshot.js

@@ -0,0 +1,163 @@
+/**
+ * Accessibility-tree snapshot (F4 slice 1).
+ *
+ * A raw Accessibility.getFullAXTree is unusable as model input: the measured
+ * Studio home page is 3687 nodes / 1.23MB. This module turns it into a BOUNDED
+ * text snapshot where every interactive node carries a stable ref (e1, e2, ...)
+ * plus its box, so click/type can target a ref instead of raw coordinates.
+ *
+ * Hard limits: a node cap and a byte cap. Both are explicit in the result
+ * (truncated / truncationReason) and the text ends with a visible note -- a
+ * silently clipped snapshot would make the model act on an incomplete page.
+ *
+ * Pure: no CDP, no filesystem. Boxes are injected (collectBoxes fills them from
+ * DOM.getBoxModel when a caller has a live session).
+ */
+/** Default cap on rendered nodes. */
+export const DEFAULT_MAX_NODES = 200;
+/** Default cap on rendered UTF-8 bytes. */
+export const DEFAULT_MAX_BYTES = 32 * 1024;
+/** Longest name kept per node (the rest is elided). */
+export const MAX_NAME_CHARS = 120;
+/** Roles that receive a ref (clickable / typeable). */
+export const INTERACTIVE_ROLES = new Set([
+    "button",
+    "link",
+    "textbox",
+    "searchbox",
+    "checkbox",
+    "radio",
+    "combobox",
+    "listbox",
+    "option",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "tab",
+    "switch",
+    "slider",
+    "spinbutton",
+]);
+/** Roles rendered as context (no ref) when they carry a name. */
+export const CONTEXT_ROLES = new Set([
+    "heading",
+    "cell",
+    "columnheader",
+    "rowheader",
+    "article",
+    "img",
+    "alert",
+]);
+/** true when a role can be clicked or typed into. */
+export function isInteractiveRole(role) {
+    return INTERACTIVE_ROLES.has(role);
+}
+/** Role of a node (CDP omits it for some ignored nodes). */
+export function roleOf(node) {
+    return node.role?.value ?? "generic";
+}
+/** Collapsed, trimmed, elided accessible name. */
+export function nameOf(node) {
+    const raw = node.name?.value ?? node.value?.value ?? "";
+    const collapsed = raw.replace(/\s+/g, " ").trim();
+    return collapsed.length > MAX_NAME_CHARS ? collapsed.slice(0, MAX_NAME_CHARS) + "..." : collapsed;
+}
+/**
+ * Build the bounded snapshot. Iterates the tree in its given order (CDP returns
+ * pre-order), so refs are stable for an unchanged tree.
+ */
+export function buildAxSnapshot(nodes, options = {}) {
+    const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const lines = [];
+    const refs = [];
+    let bytes = 0;
+    let reason = null;
+    for (const node of nodes) {
+        if (node.ignored === true)
+            continue;
+        const role = roleOf(node);
+        const name = nameOf(node);
+        const interactive = INTERACTIVE_ROLES.has(role);
+        const context = CONTEXT_ROLES.has(role) && name !== "";
+        if (!interactive && !context)
+            continue;
+        if (refs.length >= maxNodes) {
+            reason = "node cap (" + maxNodes + ") reached";
+            break;
+        }
+        const line = interactive ? renderRefLine(refs.length + 1, role, name, boxOf(node, options.boxes)) : role + ' "' + name + '"';
+        const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+        if (bytes + lineBytes > maxBytes) {
+            reason = "byte cap (" + maxBytes + ") reached";
+            break;
+        }
+        lines.push(line);
+        bytes += lineBytes;
+        if (interactive) {
+            refs.push({
+                ref: "e" + (refs.length + 1),
+                role,
+                name,
+                backendDOMNodeId: node.backendDOMNodeId ?? null,
+                box: boxOf(node, options.boxes),
+            });
+        }
+    }
+    const includedNodes = lines.length;
+    const omittedNodes = nodes.length - includedNodes;
+    if (reason !== null) {
+        lines.push("[snapshot truncated: " + includedNodes + " of " + nodes.length + " nodes included (" + reason + ")]");
+    }
+    else if (includedNodes === 0) {
+        lines.push("(no interactive or named accessibility nodes)");
+    }
+    return {
+        text: lines.join("\n"),
+        refs,
+        totalNodes: nodes.length,
+        includedNodes,
+        omittedNodes,
+        truncated: reason !== null,
+        truncationReason: reason,
+    };
+}
+function renderRefLine(index, role, name, box) {
+    const head = "[e" + index + "] " + role + ' "' + name + '"';
+    return box === null ? head : head + " @ (" + box.x + "," + box.y + "," + box.width + "," + box.height + ")";
+}
+function boxOf(node, boxes) {
+    const id = node.backendDOMNodeId;
+    if (id === undefined || boxes === undefined)
+        return null;
+    return boxes.get(id) ?? null;
+}
+/** Fetch a box per distinct backendDOMNodeId; a failed lookup is simply absent. */
+export async function collectBoxes(source, nodes, sessionId) {
+    const boxes = new Map();
+    for (const node of nodes) {
+        if (node.ignored === true)
+            continue;
+        const id = node.backendDOMNodeId;
+        if (id === undefined || boxes.has(id))
+            continue;
+        const model = await source.getBoxModel(id, sessionId).catch(() => null);
+        const box = model === null ? null : quadToBox(model.content);
+        if (box !== null)
+            boxes.set(id, box);
+    }
+    return boxes;
+}
+/** The axis-aligned bounds of a CDP content quad ([x1,y1,x2,y2,x3,y3,x4,y4]). */
+export function quadToBox(quad) {
+    const q = quad.slice(0, 8).map(Number);
+    if (q.length < 8)
+        return null;
+    const xs = [q[0], q[2], q[4], q[6]];
+    const ys = [q[1], q[3], q[5], q[7]];
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const minY = Math.min(...ys);
+    const maxY = Math.max(...ys);
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}

package/dist/browser/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared CDP protocol shapes (F4 slice 1).
+ *
+ * Only the fields this layer actually reads are declared: the goal is a
+ * zero-dependency client, not a full CDP type surface. Everything here is
+ * structural, so a test can hand-build an AX tree without a browser.
+ */
+/** A rectangle in CSS pixels, top-left origin. */
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** CDP DOM.getBoxModel result (content quad + declared size). */
+export interface BoxModel {
+    content: number[];
+    width?: number;
+    height?: number;
+}
+/** A CDP AX string value (role / name / description). */
+export interface AxValue {
+    type?: string;
+    value?: string;
+}
+/** A CDP AX property (checked, disabled, focused, ...). */
+export interface AxProperty {
+    name: string;
+    value?: {
+        type?: string;
+        value?: unknown;
+    };
+}
+/** The subset of Accessibility.AXNode this layer reads. */
+export interface AxNode {
+    nodeId?: string;
+    ignored?: boolean;
+    role?: AxValue;
+    name?: AxValue;
+    value?: AxValue;
+    description?: AxValue;
+    backendDOMNodeId?: number;
+    childIds?: string[];
+    properties?: AxProperty[];
+}
+/** A CDP error object as it appears on a response envelope. */
+export interface CdpErrorShape {
+    code: number;
+    message: string;
+    data?: unknown;
+}

package/dist/browser/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared CDP protocol shapes (F4 slice 1).
+ *
+ * Only the fields this layer actually reads are declared: the goal is a
+ * zero-dependency client, not a full CDP type surface. Everything here is
+ * structural, so a test can hand-build an AX tree without a browser.
+ */
+export {};