@celestea/tools 2.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mcd0LUO
+
+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/dist/args.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Argument readers for tool executors.
+ *
+ * The registry validates `args` against the tool's JSON Schema before dispatch,
+ * so these helpers exist for two reasons: direct `execute()` calls (tests,
+ * embeddings) that bypass the pipeline, and parity error text
+ * (`missing 'path' (expected string)`).
+ */
+export declare function objectArg(args: unknown): Record<string, unknown>;
+/** Required string argument (legacy `arg_str`). */
+export declare function stringArg(args: unknown, key: string): string;
+export declare function optionalStringArg(args: unknown, key: string): string | undefined;
+export declare function boolArg(args: unknown, key: string, fallback: boolean): boolean;
+export declare function optionalIntArg(args: unknown, key: string): number | undefined;
+export declare function optionalRecordArg(args: unknown, key: string): Record<string, unknown> | undefined;

package/dist/args.js

@@ -0,0 +1,55 @@
+/**
+ * Argument readers for tool executors.
+ *
+ * The registry validates `args` against the tool's JSON Schema before dispatch,
+ * so these helpers exist for two reasons: direct `execute()` calls (tests,
+ * embeddings) that bypass the pipeline, and parity error text
+ * (`missing 'path' (expected string)`).
+ */
+import { ToolFailure } from "./tool-failure.js";
+export function objectArg(args) {
+    if (typeof args === "object" && args !== null && !Array.isArray(args)) {
+        return args;
+    }
+    throw new ToolFailure("invalid_arg", "args must be an object");
+}
+/** Required string argument (legacy `arg_str`). */
+export function stringArg(args, key) {
+    const value = objectArg(args)[key];
+    if (typeof value !== "string")
+        throw new ToolFailure("invalid_arg", `missing '${key}' (expected string)`);
+    return value;
+}
+export function optionalStringArg(args, key) {
+    const value = objectArg(args)[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new ToolFailure("invalid_arg", `'${key}' must be a string`);
+    return value;
+}
+export function boolArg(args, key, fallback) {
+    const value = objectArg(args)[key];
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "boolean")
+        throw new ToolFailure("invalid_arg", `'${key}' must be a boolean`);
+    return value;
+}
+export function optionalIntArg(args, key) {
+    const value = objectArg(args)[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new ToolFailure("invalid_arg", `'${key}' must be an integer`);
+    }
+    return value;
+}
+export function optionalRecordArg(args, key) {
+    const value = objectArg(args)[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "object" || Array.isArray(value))
+        throw new ToolFailure("invalid_arg", `'${key}' must be an object`);
+    return value;
+}

package/dist/attachments/image-header.d.ts

@@ -0,0 +1,28 @@
+/**
+ * W847 W0: in-repo, header-only image dimensions for the four attachment formats
+ * (PNG / JPEG / WebP / GIF).
+ *
+ * WHY THIS EXISTS: the attachment store only ever feeds bytes that
+ * `sniffImageMediaType` already accepted, so those four sniffed formats are the
+ * entire surface. Replacing that third-party dependency with this port removes
+ * the only external runtime dependency of packages/*. The offsets and branch order
+ * are a faithful port of the removed parser (MIT) for exactly those four types, so
+ * {width,height} of a stored image stays byte-for-byte identical (see
+ * image-header.test.ts, whose expected values were frozen from the dependency
+ * before it was removed).
+ */
+import type { ImageMediaType } from "@celestea/core";
+/** A header that cannot be parsed as one of the four sniffed formats. */
+export declare class ImageHeaderError extends Error {
+    constructor(message: string);
+}
+/**
+ * Dimensions from a PNG / JPEG / WebP / GIF header. Throws ImageHeaderError when
+ * the bytes are not one of the four sniffed formats or the header is unreadable.
+ */
+export declare function readImageHeader(bytes: Uint8Array): {
+    width: number;
+    height: number;
+};
+/** Re-exported for callers that switch on the detected type. */
+export type { ImageMediaType };

package/dist/attachments/image-header.js

@@ -0,0 +1,148 @@
+/** A header that cannot be parsed as one of the four sniffed formats. */
+export class ImageHeaderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ImageHeaderError";
+    }
+}
+function asBuffer(bytes) {
+    return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+/** ASCII compare window (the compared literals are ASCII, so latin1 is exact). */
+function ascii(b, start, end) {
+    return b.subarray(start, end).toString("latin1");
+}
+function hex(b, start, end) {
+    let out = "";
+    for (let i = start; i < end; i += 1) {
+        out += (b[i] ?? 0).toString(16).padStart(2, "0");
+    }
+    return out;
+}
+function u16le(b, offset) {
+    return b.readUInt16LE(offset);
+}
+function i16le(b, offset) {
+    return b.readInt16LE(offset);
+}
+function u24le(b, offset) {
+    return b.readUInt16LE(offset) + ((b[offset + 2] ?? 0) << 16);
+}
+/** the removed parser PNG.validate + calculate, including Apple's CgBI layout. */
+function pngSize(b) {
+    if (ascii(b, 1, 8) !== "PNG\r\n\u001a\n")
+        throw new ImageHeaderError("Invalid PNG");
+    let chunkName = ascii(b, 12, 16);
+    if (chunkName === "CgBI")
+        chunkName = ascii(b, 28, 32);
+    if (chunkName !== "IHDR")
+        throw new ImageHeaderError("Invalid PNG");
+    if (ascii(b, 12, 16) === "CgBI")
+        return { width: b.readUInt32BE(32), height: b.readUInt32BE(36) };
+    return { width: b.readUInt32BE(16), height: b.readUInt32BE(20) };
+}
+/** the removed parser GIF.validate + calculate (logical screen descriptor). */
+function gifSize(b) {
+    if (!/^GIF8[79]a/.test(ascii(b, 0, 6)))
+        throw new ImageHeaderError("Invalid GIF");
+    return { width: u16le(b, 6), height: u16le(b, 8) };
+}
+/** the removed parser WEBP.validate + calculate (VP8X / VP8 / VP8L chunks). */
+function webpSize(b) {
+    if (!(ascii(b, 0, 4) === "RIFF" && ascii(b, 8, 12) === "WEBP" && ascii(b, 12, 15) === "VP8")) {
+        throw new ImageHeaderError("Invalid WebP");
+    }
+    const chunkHeader = ascii(b, 12, 16);
+    const input = b.subarray(20, 30);
+    if (chunkHeader === "VP8X") {
+        const flags = input[0] ?? 0;
+        if ((flags & 0xc0) === 0 && (flags & 0x01) === 0) {
+            return { width: 1 + u24le(input, 4), height: 1 + u24le(input, 7) };
+        }
+        throw new ImageHeaderError("Invalid WebP");
+    }
+    if (chunkHeader === "VP8 " && (input[0] ?? 0) !== 0x2f) {
+        return { width: i16le(input, 6) & 0x3fff, height: i16le(input, 8) & 0x3fff };
+    }
+    if (chunkHeader === "VP8L" && hex(input, 3, 6) !== "9d012a") {
+        const b1 = input[1] ?? 0;
+        const b2 = input[2] ?? 0;
+        const b3 = input[3] ?? 0;
+        const b4 = input[4] ?? 0;
+        return {
+            width: 1 + (((b2 & 0x3f) << 8) | b1),
+            height: 1 + (((b4 & 0xf) << 10) | (b3 << 2) | ((b2 & 0xc0) >> 6)),
+        };
+    }
+    throw new ImageHeaderError("Invalid WebP");
+}
+function readUInt(b, bits, offset, bigEndian) {
+    if (bits === 16)
+        return bigEndian ? b.readUInt16BE(offset) : b.readUInt16LE(offset);
+    return bigEndian ? b.readUInt32BE(offset) : b.readUInt32LE(offset);
+}
+/**
+ * the removed parser JPEG EXIF orientation scan. The returned orientation never
+ * changes the dimensions, but parsing it (and failing on a corrupt block exactly
+ * like the dependency did) is part of byte-for-byte parity.
+ */
+function readJpegExif(input, index) {
+    const exifBlock = input.subarray(2, index);
+    const align = hex(exifBlock, 6, 8);
+    const bigEndian = align === "4d4d";
+    const littleEndian = align === "4949";
+    if (!bigEndian && !littleEndian)
+        return;
+    const entries = readUInt(exifBlock, 16, 14, bigEndian);
+    for (let n = 0; n < entries; n += 1) {
+        const start = 14 + 2 + n * 12;
+        if (start > exifBlock.length)
+            return;
+        const block = exifBlock.subarray(start, start + 12);
+        if (readUInt(block, 16, 0, bigEndian) !== 274)
+            continue;
+        if (readUInt(block, 16, 2, bigEndian) !== 3)
+            return;
+        if (readUInt(block, 32, 4, bigEndian) !== 1)
+            return;
+        readUInt(block, 16, 8, bigEndian);
+        return;
+    }
+}
+/** the removed parser JPG.validate + calculate (SOF0/SOF1/SOF2 scan). */
+function jpegSize(b) {
+    let input = b.subarray(4);
+    while (input.length > 0) {
+        const i = input.readUInt16BE(0);
+        if (i > input.length)
+            throw new ImageHeaderError("Corrupt JPG, exceeded buffer limits");
+        if (input[i] !== 0xff) {
+            input = input.subarray(1);
+            continue;
+        }
+        if (hex(input, 2, 6) === "45786966")
+            readJpegExif(input, i);
+        const next = input[i + 1];
+        if (next === 0xc0 || next === 0xc1 || next === 0xc2) {
+            return { width: input.readUInt16BE(i + 7), height: input.readUInt16BE(i + 5) };
+        }
+        input = input.subarray(i + 2);
+    }
+    throw new ImageHeaderError("Invalid JPG, no size found");
+}
+/**
+ * Dimensions from a PNG / JPEG / WebP / GIF header. Throws ImageHeaderError when
+ * the bytes are not one of the four sniffed formats or the header is unreadable.
+ */
+export function readImageHeader(bytes) {
+    const b = asBuffer(bytes);
+    if (ascii(b, 1, 8) === "PNG\r\n\u001a\n")
+        return pngSize(b);
+    if (hex(b, 0, 2) === "ffd8")
+        return jpegSize(b);
+    if (/^GIF8[79]a/.test(ascii(b, 0, 6)))
+        return gifSize(b);
+    if (ascii(b, 0, 4) === "RIFF" && ascii(b, 8, 12) === "WEBP")
+        return webpSize(b);
+    throw new ImageHeaderError("unsupported image format");
+}

package/dist/attachments/store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * W804 (multimodal P0 section 5): the per-session, content-addressed attachment
+ * store.
+ *
+ * Layout: <session-dir>/attachments/<sha256>.<ext>. The session directory is
+ * renamed wholesale by trash/archive, so attachments follow it with no second
+ * lifecycle. Bytes NEVER enter the session log: the log carries only an
+ * [ImageRef].
+ *
+ * P0 scope (user decision 2026-09-16): sniff the four magic-byte formats, reject
+ * oversize/oversized-pixel inputs, store the ORIGINAL bytes unchanged (no
+ * re-encode, no downscale). Dimensions are read from the header by the in-repo
+ * parser (attachments/image-header.ts) for the same four sniffed formats.
+ */
+import type { ImageMediaType, ImageRef } from "@celestea/core";
+/** Directory name under the session dir. */
+export declare const ATTACHMENTS_DIRNAME = "attachments";
+/** P0 stored-byte ceiling (section 5.3 "bytes <= 4 MiB", original bytes). */
+export declare const ATTACHMENT_MAX_BYTES: number;
+/** P0 decoded-pixel ceiling (decompression-bomb guard). */
+export declare const ATTACHMENT_MAX_PIXELS = 40000000;
+/** P0 single-side pixel ceiling. */
+export declare const ATTACHMENT_MAX_SIDE = 8192;
+export type AttachmentErrorCode = "unsupported_media_type" | "too_large" | "too_many_pixels" | "decode_failed" | "not_found" | "io";
+/** A structured attachment failure; read_image maps it onto a ToolFailure. */
+export declare class AttachmentError extends Error {
+    readonly code: AttachmentErrorCode;
+    constructor(code: AttachmentErrorCode, message: string);
+}
+/** Magic-byte sniffing (section 5.4): the extension is NEVER trusted. */
+export declare function sniffImageMediaType(bytes: Uint8Array): ImageMediaType | null;
+/** Header-only dimensions; an unreadable header is a decode failure. */
+export declare function readImageDimensions(bytes: Uint8Array): {
+    width: number;
+    height: number;
+};
+/** One already-stored attachment: its reference plus the raw bytes. */
+export interface StoredAttachment {
+    ref: ImageRef;
+    bytes: Buffer;
+}
+export interface AttachmentStore {
+    /** The attachments/ directory this store owns. */
+    readonly dir: string;
+    /** Validate + content-address + atomically store one image; returns its ref. */
+    put(input: {
+        bytes: Uint8Array;
+        name?: string;
+    }): Promise<ImageRef>;
+    /** Bytes by attachment_id (scans the directory for <id>.<ext>); null = absent. */
+    readById(id: string): Promise<StoredAttachment | null>;
+    /** A data URL for the request-time projection, or null when absent. */
+    readDataUrl(id: string): Promise<string | null>;
+}
+/** Create the store over one session's attachments/ directory. */
+export declare function createAttachmentStore(dir: string): AttachmentStore;

package/dist/attachments/store.js

@@ -0,0 +1,148 @@
+/**
+ * W804 (multimodal P0 section 5): the per-session, content-addressed attachment
+ * store.
+ *
+ * Layout: <session-dir>/attachments/<sha256>.<ext>. The session directory is
+ * renamed wholesale by trash/archive, so attachments follow it with no second
+ * lifecycle. Bytes NEVER enter the session log: the log carries only an
+ * [ImageRef].
+ *
+ * P0 scope (user decision 2026-09-16): sniff the four magic-byte formats, reject
+ * oversize/oversized-pixel inputs, store the ORIGINAL bytes unchanged (no
+ * re-encode, no downscale). Dimensions are read from the header by the in-repo
+ * parser (attachments/image-header.ts) for the same four sniffed formats.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readImageHeader } from "./image-header.js";
+/** Directory name under the session dir. */
+export const ATTACHMENTS_DIRNAME = "attachments";
+/** P0 stored-byte ceiling (section 5.3 "bytes <= 4 MiB", original bytes). */
+export const ATTACHMENT_MAX_BYTES = 4 * 1024 * 1024;
+/** P0 decoded-pixel ceiling (decompression-bomb guard). */
+export const ATTACHMENT_MAX_PIXELS = 40_000_000;
+/** P0 single-side pixel ceiling. */
+export const ATTACHMENT_MAX_SIDE = 8192;
+/** A structured attachment failure; read_image maps it onto a ToolFailure. */
+export class AttachmentError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AttachmentError";
+        this.code = code;
+    }
+}
+const EXTENSIONS = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/webp": "webp",
+    "image/gif": "gif",
+};
+/** Magic-byte sniffing (section 5.4): the extension is NEVER trusted. */
+export function sniffImageMediaType(bytes) {
+    const b = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47)
+        return "image/png";
+    if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+        return "image/jpeg";
+    if (b.length >= 6) {
+        const head = b.subarray(0, 6).toString("ascii");
+        if (head === "GIF87a" || head === "GIF89a")
+            return "image/gif";
+    }
+    if (b.length >= 12 && b.subarray(0, 4).toString("ascii") === "RIFF" && b.subarray(8, 12).toString("ascii") === "WEBP") {
+        return "image/webp";
+    }
+    return null;
+}
+/** Header-only dimensions; an unreadable header is a decode failure. */
+export function readImageDimensions(bytes) {
+    let out;
+    try {
+        out = readImageHeader(bytes);
+    }
+    catch (e) {
+        throw new AttachmentError("decode_failed", `cannot read image header: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const { width, height } = out;
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+        throw new AttachmentError("decode_failed", "image header carries no usable dimensions");
+    }
+    return { width, height };
+}
+/** Create the store over one session's attachments/ directory. */
+export function createAttachmentStore(dir) {
+    return {
+        dir,
+        async put(input) {
+            const bytes = Buffer.isBuffer(input.bytes)
+                ? input.bytes
+                : Buffer.from(input.bytes.buffer, input.bytes.byteOffset, input.bytes.byteLength);
+            if (bytes.length === 0)
+                throw new AttachmentError("decode_failed", "the image is empty");
+            const media = sniffImageMediaType(bytes);
+            if (media === null) {
+                throw new AttachmentError("unsupported_media_type", "unsupported image format (expected PNG, JPEG, WebP or GIF, detected by content)");
+            }
+            if (bytes.length > ATTACHMENT_MAX_BYTES) {
+                throw new AttachmentError("too_large", `image is ${bytes.length} bytes, over the ${ATTACHMENT_MAX_BYTES}-byte limit`);
+            }
+            const { width, height } = readImageDimensions(bytes);
+            if (width > ATTACHMENT_MAX_SIDE || height > ATTACHMENT_MAX_SIDE || width * height > ATTACHMENT_MAX_PIXELS) {
+                throw new AttachmentError("too_many_pixels", `image is ${width}x${height}, over the pixel limit`);
+            }
+            const id = createHash("sha256").update(bytes).digest("hex");
+            const ref = { attachment_id: id, media_type: media, width, height };
+            if (input.name !== undefined && input.name !== "")
+                ref.name = input.name;
+            const target = join(dir, `${id}.${EXTENSIONS[media]}`);
+            await mkdir(dir, { recursive: true });
+            // Content addressing dedupes within the session: the same bytes are one file.
+            let exists = false;
+            try {
+                const entries = await readdir(dir);
+                exists = entries.includes(`${id}.${EXTENSIONS[media]}`);
+            }
+            catch {
+                exists = false;
+            }
+            if (!exists) {
+                const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+                await writeFile(tmp, bytes);
+                try {
+                    await rename(tmp, target);
+                }
+                catch (e) {
+                    await unlink(tmp).catch(() => undefined);
+                    throw new AttachmentError("io", `cannot store attachment: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            return ref;
+        },
+        async readById(id) {
+            let entries;
+            try {
+                entries = await readdir(dir);
+            }
+            catch {
+                return null;
+            }
+            const name = entries.find((entry) => entry.startsWith(`${id}.`));
+            if (name === undefined)
+                return null;
+            const bytes = await readFile(join(dir, name));
+            const media = sniffImageMediaType(bytes);
+            if (media === null)
+                return null;
+            const { width, height } = readImageDimensions(bytes);
+            return { ref: { attachment_id: id, media_type: media, width, height }, bytes };
+        },
+        async readDataUrl(id) {
+            const found = await this.readById(id);
+            if (found === null)
+                return null;
+            return `data:${found.ref.media_type};base64,${found.bytes.toString("base64")}`;
+        },
+    };
+}

package/dist/browser/cdp.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Minimal Chrome DevTools Protocol client (F4 slice 1).
+ *
+ * Design: the TRANSPORT is a seam. \`WebSocketTransport\` is the production
+ * implementation (Node's global WebSocket), while a test supplies an in-memory
+ * fake and never needs a browser or a WebSocket server. This file owns request
+ * id correlation, response/error settling, event fan-out, per-request
+ * deadlines and close semantics.
+ *
+ * Only the domains the F4 tools need are wrapped; \`send\` stays public for
+ * anything else. Zero npm dependencies.
+ */
+import type { AxNode, BoxModel, CdpErrorShape } from "./types.js";
+/** Callbacks a transport delivers to its single subscriber. */
+export interface CdpTransportHandlers {
+    onMessage(data: string): void;
+    onError(error: Error): void;
+    onClose(): void;
+}
+/** The transport seam: real WebSocket in production, in-memory in tests. */
+export interface CdpTransport {
+    send(data: string): void;
+    subscribe(handlers: CdpTransportHandlers): void;
+    close(): void;
+}
+/** A structural WebSocket, so this module needs no DOM lib types. */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: string, listener: (event: {
+        data?: unknown;
+    }) => void): void;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export interface CdpClientOptions {
+    transport: CdpTransport;
+    /** Per-request deadline; default 15000ms. */
+    timeoutMs?: number;
+}
+export type CdpEventHandler = (params: Record<string, unknown>, sessionId: string | undefined) => void;
+/** Options for Runtime.evaluate. */
+export interface EvaluateOptions {
+    returnByValue?: boolean;
+    awaitPromise?: boolean;
+}
+/** Options for Page.captureScreenshot. */
+export interface ScreenshotOptions {
+    format?: "png" | "jpeg";
+    quality?: number;
+    captureBeyondViewport?: boolean;
+}
+/** A decoded screenshot: base64 plus its decoded byte count. */
+export interface Screenshot {
+    data: string;
+    bytes: number;
+}
+/** Input.dispatchMouseEvent parameters. */
+export interface MouseEventParams {
+    type: "mousePressed" | "mouseReleased" | "mouseMoved" | "mouseWheel";
+    x: number;
+    y: number;
+    button?: "left" | "right" | "middle" | "none";
+    clickCount?: number;
+    deltaX?: number;
+    deltaY?: number;
+}
+/** Input.dispatchKeyEvent parameters. */
+export interface KeyEventParams {
+    type: "keyDown" | "keyUp" | "char" | "rawKeyDown";
+    key?: string;
+    code?: string;
+    text?: string;
+    windowsVirtualKeyCode?: number;
+}
+/** Emulation.setDeviceMetricsOverride parameters. */
+export interface DeviceMetrics {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+    mobile?: boolean;
+}
+/** Default per-request deadline. */
+export declare const DEFAULT_CDP_TIMEOUT_MS = 15000;
+/** Default WebSocket open deadline. */
+export declare const DEFAULT_OPEN_TIMEOUT_MS = 10000;
+/** The transport could not be created / connected / used. */
+export declare class CdpTransportError extends Error {
+    readonly code = "cdp_transport";
+    constructor(message: string);
+}
+/** A request exceeded its deadline. */
+export declare class CdpTimeoutError extends Error {
+    readonly code = "cdp_timeout";
+    constructor(method: string, timeoutMs: number);
+}
+/** The browser answered with a protocol error (negative code). */
+export declare class CdpProtocolError extends Error {
+    readonly code: number;
+    readonly data: unknown;
+    constructor(error: CdpErrorShape);
+}
+/** The client (or its transport) is closed; no further requests are accepted. */
+export declare class CdpClosedError extends Error {
+    readonly code = "cdp_closed";
+    constructor();
+}
+/** Production transport over Node's global WebSocket. */
+export declare class WebSocketTransport implements CdpTransport {
+    private readonly socket;
+    constructor(socket: WebSocketLike);
+    send(data: string): void;
+    subscribe(handlers: CdpTransportHandlers): void;
+    close(): void;
+}
+/** The runtime WebSocket constructor, or a structured error when absent. */
+export declare function defaultWebSocketFactory(): WebSocketFactory;
+export interface OpenTransportOptions {
+    factory?: WebSocketFactory;
+    openTimeoutMs?: number;
+}
+/** Connect and wait for the socket to open (sending before open would throw). */
+export declare function openWebSocketTransport(url: string, options?: OpenTransportOptions): Promise<WebSocketTransport>;
+/** A tiny CDP client over an injected transport. */
+export declare class CdpClient {
+    private readonly transport;
+    private readonly timeoutMs;
+    private seq;
+    private readonly pending;
+    private readonly handlers;
+    private closed;
+    constructor(options: CdpClientOptions);
+    /** Send one request; the promise settles on its correlated response. */
+    send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<Record<string, unknown>>;
+    /** Subscribe to a CDP event (method name, or "*" for every event). */
+    on(event: string, handler: CdpEventHandler): () => void;
+    /** Close the transport and reject every in-flight request. */
+    close(): void;
+    get isClosed(): boolean;
+    createTarget(url: string): Promise<{
+        targetId: string;
+    }>;
+    attachToTarget(targetId: string): Promise<{
+        sessionId: string;
+    }>;
+    closeTarget(targetId: string): Promise<void>;
+    pageEnable(sessionId: string): Promise<void>;
+    runtimeEnable(sessionId: string): Promise<void>;
+    accessibilityEnable(sessionId: string): Promise<void>;
+    navigate(url: string, sessionId: string): Promise<Record<string, unknown>>;
+    evaluate(expression: string, sessionId: string, options?: EvaluateOptions): Promise<unknown>;
+    captureScreenshot(sessionId: string, options?: ScreenshotOptions): Promise<Screenshot>;
+    dispatchMouseEvent(params: MouseEventParams, sessionId: string): Promise<void>;
+    insertText(text: string, sessionId: string): Promise<void>;
+    dispatchKeyEvent(params: KeyEventParams, sessionId: string): Promise<void>;
+    setDeviceMetricsOverride(metrics: DeviceMetrics, sessionId: string): Promise<void>;
+    getFullAXTree(sessionId: string): Promise<AxNode[]>;
+    getBoxModel(backendNodeId: number, sessionId: string): Promise<BoxModel | null>;
+    private receive;
+    private settle;
+    private emit;
+    private failAll;
+}