@rynx-ai/browser-cdp 0.1.10

package/dist/client.d.ts

@@ -0,0 +1,120 @@
+export type BrowserAutomationEndpointKind = "browser" | "page";
+export interface BrowserAutomationWebSocket {
+    readonly readyState: number;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+export type BrowserAutomationWebSocketFactory = (endpoint: string) => BrowserAutomationWebSocket;
+export interface BrowserAutomationClientOptions {
+    /** A page-level or browser-level loopback CDP WebSocket endpoint. */
+    endpoint: string;
+    /** Override endpoint inference when a non-standard CDP path is unavoidable. */
+    endpointKind?: BrowserAutomationEndpointKind;
+    /** Required only when a browser endpoint contains more than one Page. */
+    pageTargetId?: string;
+    /**
+     * Stable secret for the lifetime of the owning Rynx Runtime. It lets refs
+     * cross short-lived client processes while making modified refs fail closed.
+     */
+    referenceKey: string | Uint8Array;
+    commandTimeoutMs?: number;
+    createWebSocket?: BrowserAutomationWebSocketFactory;
+}
+export interface BrowserAutomationSnapshotNode {
+    nodeId: string;
+    parentId?: string;
+    childIds: string[];
+    role: string;
+    name: string;
+    value?: string;
+    description?: string;
+    ignored: boolean;
+    /**
+     * Opaque, process-independent reference valid only for this endpoint's Page
+     * target and current document. A navigation or Browser restart invalidates it.
+     */
+    ref?: string;
+    properties: Readonly<Record<string, string | number | boolean>>;
+}
+export interface BrowserAutomationSnapshot {
+    documentGeneration: number;
+    nodes: BrowserAutomationSnapshotNode[];
+}
+export interface BrowserAutomationNavigateResult {
+    frameId?: string;
+    loaderId?: string;
+}
+export type BrowserAutomationElementTarget = {
+    ref: string;
+} | {
+    selector: string;
+};
+export type BrowserAutomationClickTarget = BrowserAutomationElementTarget | {
+    x: number;
+    y: number;
+};
+export interface BrowserAutomationScreenshotOptions {
+    format?: "png" | "jpeg" | "webp";
+    quality?: number;
+}
+export interface BrowserAutomationScreenshot {
+    format: "png" | "jpeg" | "webp";
+    mimeType: "image/png" | "image/jpeg" | "image/webp";
+    /** Canonical base64 returned by CDP, without a data-URL prefix. */
+    data: string;
+}
+export declare class BrowserAutomationError extends Error {
+    readonly code: "connection" | "invalid_input" | "protocol" | "target_not_found" | "timeout";
+    readonly name = "BrowserAutomationError";
+    constructor(message: string, code: "connection" | "invalid_input" | "protocol" | "target_not_found" | "timeout");
+}
+export declare class BrowserAutomationStaleReferenceError extends Error {
+    readonly ref: string;
+    readonly name = "BrowserAutomationStaleReferenceError";
+    constructor(ref: string);
+}
+/**
+ * A deliberately small automation facade over CDP.
+ *
+ * It does not infer selectors or wait for application-specific readiness.
+ * Snapshot refs can cross short-lived CLI processes, but are bound to the
+ * endpoint, Page target, and current main-document loader.
+ */
+export declare class BrowserAutomationClient {
+    private readonly connection;
+    private readonly pageSessionId;
+    private readonly referenceScope;
+    private readonly referenceKey;
+    private documentGenerationValue;
+    private accessibilityEnabled;
+    private domEnabled;
+    private closed;
+    private constructor();
+    static connect(options: BrowserAutomationClientOptions): Promise<BrowserAutomationClient>;
+    get documentGeneration(): number;
+    snapshot(): Promise<BrowserAutomationSnapshot>;
+    navigate(url: string): Promise<BrowserAutomationNavigateResult>;
+    click(target: BrowserAutomationClickTarget): Promise<void>;
+    type(target: BrowserAutomationElementTarget, text: string): Promise<void>;
+    screenshot(options?: BrowserAutomationScreenshotOptions): Promise<BrowserAutomationScreenshot>;
+    close(): void;
+    private pageCall;
+    private ensureDomEnabled;
+    private snapshotNode;
+    private resolveElement;
+    private resolveObjectId;
+    private currentDocumentIdentity;
+    private elementCenter;
+    private invalidateDocument;
+    private assertOpen;
+}
+export declare function connectBrowserAutomation(options: BrowserAutomationClientOptions): Promise<BrowserAutomationClient>;

package/dist/client.js

@@ -0,0 +1,788 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+const MAX_COMMAND_TIMEOUT_MS = 120_000;
+const MAX_PENDING_COMMANDS = 128;
+const MAX_MESSAGE_BYTES = 16 * 1024 * 1024;
+const MAX_SNAPSHOT_NODES = 10_000;
+const MAX_SELECTOR_CHARS = 4_096;
+const MAX_INPUT_TEXT_BYTES = 64 * 1024;
+const WEB_SOCKET_OPEN = 1;
+const REFERENCE_VERSION = 1;
+const REFERENCE_DOCUMENT_FINGERPRINT_BYTES = 12;
+const REFERENCE_BACKEND_NODE_BYTES = 8;
+const REFERENCE_TAG_BYTES = 16;
+const REFERENCE_PAYLOAD_BYTES = 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES + REFERENCE_BACKEND_NODE_BYTES;
+const REFERENCE_BYTES = REFERENCE_PAYLOAD_BYTES + REFERENCE_TAG_BYTES;
+const REFERENCE_DOMAIN = Buffer.from("rynx-browser-cdp-ref-v1\0", "utf8");
+export class BrowserAutomationError extends Error {
+    code;
+    name = "BrowserAutomationError";
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+export class BrowserAutomationStaleReferenceError extends Error {
+    ref;
+    name = "BrowserAutomationStaleReferenceError";
+    constructor(ref) {
+        super(`Browser reference ${ref} is stale; take a new snapshot`);
+        this.ref = ref;
+    }
+}
+/**
+ * A deliberately small automation facade over CDP.
+ *
+ * It does not infer selectors or wait for application-specific readiness.
+ * Snapshot refs can cross short-lived CLI processes, but are bound to the
+ * endpoint, Page target, and current main-document loader.
+ */
+export class BrowserAutomationClient {
+    connection;
+    pageSessionId;
+    referenceScope;
+    referenceKey;
+    documentGenerationValue = 1;
+    accessibilityEnabled = false;
+    domEnabled = false;
+    closed = false;
+    constructor(connection, referenceScope, referenceKey, pageSessionId) {
+        this.connection = connection;
+        this.referenceScope = referenceScope;
+        this.referenceKey = referenceKey;
+        this.pageSessionId = pageSessionId;
+        this.connection.onEvent((method, params, sessionId) => {
+            if (this.pageSessionId && sessionId && sessionId !== this.pageSessionId)
+                return;
+            if (method === "DOM.documentUpdated") {
+                this.invalidateDocument();
+                return;
+            }
+            if (method === "Page.frameNavigated") {
+                const frame = recordAt(params, "frame");
+                if (frame && typeof frame.parentId !== "string")
+                    this.invalidateDocument();
+                return;
+            }
+            if (method === "Inspector.detached" ||
+                (method === "Target.detachedFromTarget" &&
+                    stringAt(params, "sessionId") === this.pageSessionId)) {
+                this.invalidateDocument();
+            }
+        });
+    }
+    static async connect(options) {
+        const endpoint = parseEndpoint(options.endpoint);
+        const endpointKind = options.endpointKind ?? inferEndpointKind(endpoint);
+        const timeoutMs = boundedInteger(options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS, 10, MAX_COMMAND_TIMEOUT_MS, "commandTimeoutMs");
+        const referenceKey = parseReferenceKey(options.referenceKey);
+        const connection = await CdpConnection.connect(endpoint.href, timeoutMs, options.createWebSocket ?? defaultWebSocketFactory);
+        try {
+            if (endpointKind === "page") {
+                return new BrowserAutomationClient(connection, endpoint.href, referenceKey);
+            }
+            const targetId = await selectPageTarget(connection, options.pageTargetId);
+            const attached = requireRecord(await connection.call("Target.attachToTarget", {
+                targetId,
+                flatten: true,
+            }), "Target.attachToTarget result");
+            const sessionId = requiredString(attached.sessionId, "Target.attachToTarget sessionId");
+            return new BrowserAutomationClient(connection, `${endpoint.href}\0${targetId}`, referenceKey, sessionId);
+        }
+        catch (error) {
+            connection.close();
+            throw error;
+        }
+    }
+    get documentGeneration() {
+        return this.documentGenerationValue;
+    }
+    async snapshot() {
+        this.assertOpen();
+        // Enable DOM before minting refs. Chromium may announce an initial
+        // DOM.documentUpdated while the domain comes online; any such event must
+        // precede, rather than immediately invalidate, this snapshot's refs.
+        await this.ensureDomEnabled();
+        if (!this.accessibilityEnabled) {
+            await this.pageCall("Accessibility.enable");
+            this.accessibilityEnabled = true;
+        }
+        const documentIdentity = await this.currentDocumentIdentity();
+        const result = requireRecord(await this.pageCall("Accessibility.getFullAXTree"), "Accessibility.getFullAXTree result");
+        if (!Array.isArray(result.nodes)) {
+            throw protocolError("Accessibility.getFullAXTree result nodes must be an array");
+        }
+        if (result.nodes.length > MAX_SNAPSHOT_NODES) {
+            throw protocolError(`Accessibility snapshot exceeds ${MAX_SNAPSHOT_NODES} nodes`);
+        }
+        if ((await this.currentDocumentIdentity()) !== documentIdentity) {
+            throw protocolError("Browser document changed while taking the accessibility snapshot");
+        }
+        return {
+            documentGeneration: this.documentGenerationValue,
+            nodes: result.nodes.map((value, index) => this.snapshotNode(value, index, documentIdentity)),
+        };
+    }
+    async navigate(url) {
+        this.assertOpen();
+        const parsed = parseNavigationUrl(url);
+        // Refs must fail immediately, not after Chrome eventually emits a lifecycle event.
+        this.invalidateDocument();
+        const result = requireRecord(await this.pageCall("Page.navigate", { url: parsed }), "Page.navigate result");
+        const errorText = optionalString(result.errorText);
+        if (errorText)
+            throw protocolError(`Page.navigate failed: ${errorText}`);
+        return {
+            ...(optionalString(result.frameId)
+                ? { frameId: optionalString(result.frameId) }
+                : {}),
+            ...(optionalString(result.loaderId)
+                ? { loaderId: optionalString(result.loaderId) }
+                : {}),
+        };
+    }
+    async click(target) {
+        this.assertOpen();
+        const element = "x" in target ? undefined : await this.resolveElement(target);
+        try {
+            const point = element
+                ? await this.elementCenter(element)
+                : coordinateTarget(target);
+            await this.pageCall("Input.dispatchMouseEvent", {
+                type: "mouseMoved",
+                x: point.x,
+                y: point.y,
+                button: "none",
+                buttons: 0,
+            });
+            await this.pageCall("Input.dispatchMouseEvent", {
+                type: "mousePressed",
+                x: point.x,
+                y: point.y,
+                button: "left",
+                buttons: 1,
+                clickCount: 1,
+            });
+            await this.pageCall("Input.dispatchMouseEvent", {
+                type: "mouseReleased",
+                x: point.x,
+                y: point.y,
+                button: "left",
+                buttons: 0,
+                clickCount: 1,
+            });
+        }
+        finally {
+            if (element?.objectId) {
+                await this.pageCall("Runtime.releaseObject", {
+                    objectId: element.objectId,
+                }).catch(() => undefined);
+            }
+        }
+    }
+    async type(target, text) {
+        this.assertOpen();
+        if (typeof text !== "string" ||
+            Buffer.byteLength(text, "utf8") > MAX_INPUT_TEXT_BYTES) {
+            throw invalidInput(`text must be at most ${MAX_INPUT_TEXT_BYTES} UTF-8 bytes`);
+        }
+        const element = await this.resolveElement(target);
+        await this.ensureDomEnabled();
+        const objectId = element.objectId ?? await this.resolveObjectId(element);
+        try {
+            const focused = requireRecord(await this.pageCall("Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration: "function() { this.focus(); }",
+                returnByValue: true,
+            }), "Runtime.callFunctionOn result");
+            if (focused.exceptionDetails !== undefined) {
+                throw protocolError("Browser element could not be focused");
+            }
+            await this.pageCall("Input.insertText", { text });
+        }
+        finally {
+            await this.pageCall("Runtime.releaseObject", { objectId }).catch(() => undefined);
+        }
+    }
+    async screenshot(options = {}) {
+        this.assertOpen();
+        const format = options.format ?? "png";
+        if (format !== "png" && format !== "jpeg" && format !== "webp") {
+            throw invalidInput("screenshot format must be png, jpeg, or webp");
+        }
+        if (options.quality !== undefined &&
+            (!Number.isInteger(options.quality) ||
+                options.quality < 0 ||
+                options.quality > 100)) {
+            throw invalidInput("screenshot quality must be an integer from 0 to 100");
+        }
+        if (format === "png" && options.quality !== undefined) {
+            throw invalidInput("screenshot quality is unsupported for png");
+        }
+        const result = requireRecord(await this.pageCall("Page.captureScreenshot", {
+            format,
+            ...(options.quality === undefined ? {} : { quality: options.quality }),
+        }), "Page.captureScreenshot result");
+        const data = requiredString(result.data, "Page.captureScreenshot data");
+        if (!canonicalBase64(data)) {
+            throw protocolError("Page.captureScreenshot returned invalid base64");
+        }
+        return {
+            format,
+            mimeType: format === "png"
+                ? "image/png"
+                : format === "jpeg"
+                    ? "image/jpeg"
+                    : "image/webp",
+            data,
+        };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.invalidateDocument();
+        this.connection.close();
+    }
+    async pageCall(method, params = {}) {
+        return await this.connection.call(method, params, this.pageSessionId);
+    }
+    async ensureDomEnabled() {
+        if (this.domEnabled)
+            return;
+        await this.pageCall("DOM.enable");
+        this.domEnabled = true;
+    }
+    snapshotNode(value, index, documentIdentity) {
+        const node = requireRecord(value, `Accessibility node ${index}`);
+        const nodeId = requiredString(node.nodeId, `Accessibility node ${index} nodeId`);
+        const backendNodeId = positiveInteger(node.backendDOMNodeId);
+        const ignored = node.ignored === true;
+        const role = axString(node.role);
+        const name = axString(node.name);
+        const rawChildIds = node.childIds;
+        const childIds = rawChildIds === undefined
+            ? []
+            : Array.isArray(rawChildIds)
+                ? rawChildIds.map((child, childIndex) => requiredString(child, `Accessibility node ${index} childIds[${childIndex}]`))
+                : (() => {
+                    throw protocolError(`Accessibility node ${index} childIds must be an array`);
+                })();
+        const ref = !ignored && backendNodeId !== undefined
+            ? encodeElementReference(this.referenceScope, documentIdentity, backendNodeId, this.referenceKey)
+            : undefined;
+        return {
+            nodeId,
+            ...(optionalString(node.parentId)
+                ? { parentId: optionalString(node.parentId) }
+                : {}),
+            childIds,
+            role,
+            name,
+            ...(axOptionalString(node.value)
+                ? { value: axOptionalString(node.value) }
+                : {}),
+            ...(axOptionalString(node.description)
+                ? { description: axOptionalString(node.description) }
+                : {}),
+            ignored,
+            ...(ref ? { ref } : {}),
+            properties: axProperties(node.properties),
+        };
+    }
+    async resolveElement(target) {
+        await this.ensureDomEnabled();
+        if ("ref" in target) {
+            if (typeof target.ref !== "string")
+                throw invalidInput("ref must be a string");
+            const documentIdentity = await this.currentDocumentIdentity();
+            const backendNodeId = decodeElementReference(target.ref, this.referenceScope, documentIdentity, this.referenceKey);
+            try {
+                return {
+                    backendNodeId,
+                    objectId: await this.resolveObjectId({ backendNodeId }),
+                };
+            }
+            catch (error) {
+                if (error instanceof BrowserAutomationError && error.code === "protocol") {
+                    throw new BrowserAutomationStaleReferenceError(target.ref);
+                }
+                throw error;
+            }
+        }
+        if (typeof target.selector !== "string" ||
+            target.selector.length === 0 ||
+            target.selector.length > MAX_SELECTOR_CHARS) {
+            throw invalidInput(`selector must be a non-empty string of at most ${MAX_SELECTOR_CHARS} characters`);
+        }
+        const document = requireRecord(await this.pageCall("DOM.getDocument", { depth: 0 }), "DOM.getDocument result");
+        const root = requireRecord(document.root, "DOM.getDocument root");
+        const rootNodeId = positiveInteger(root.nodeId);
+        if (rootNodeId === undefined) {
+            throw protocolError("DOM.getDocument root nodeId is invalid");
+        }
+        const query = requireRecord(await this.pageCall("DOM.querySelector", {
+            nodeId: rootNodeId,
+            selector: target.selector,
+        }), "DOM.querySelector result");
+        const nodeId = positiveInteger(query.nodeId);
+        if (nodeId === undefined) {
+            throw new BrowserAutomationError(`No element matches selector ${JSON.stringify(target.selector)}`, "target_not_found");
+        }
+        return { nodeId };
+    }
+    async resolveObjectId(element) {
+        const resolved = requireRecord(await this.pageCall("DOM.resolveNode", domLocator(element)), "DOM.resolveNode result");
+        const object = requireRecord(resolved.object, "DOM.resolveNode object");
+        return requiredString(object.objectId, "DOM.resolveNode objectId");
+    }
+    async currentDocumentIdentity() {
+        const result = requireRecord(await this.pageCall("Page.getFrameTree"), "Page.getFrameTree result");
+        const frameTree = requireRecord(result.frameTree, "Page.getFrameTree frameTree");
+        const frame = requireRecord(frameTree.frame, "Page.getFrameTree frame");
+        return requiredString(frame.loaderId, "Page.getFrameTree loaderId");
+    }
+    async elementCenter(element) {
+        await this.ensureDomEnabled();
+        const locator = domLocator(element);
+        await this.pageCall("DOM.scrollIntoViewIfNeeded", locator);
+        const result = requireRecord(await this.pageCall("DOM.getBoxModel", locator), "DOM.getBoxModel result");
+        const model = requireRecord(result.model, "DOM.getBoxModel model");
+        const quad = numericQuad(model.content ?? model.border);
+        return {
+            x: (quad[0] + quad[2] + quad[4] + quad[6]) / 4,
+            y: (quad[1] + quad[3] + quad[5] + quad[7]) / 4,
+        };
+    }
+    invalidateDocument() {
+        this.documentGenerationValue += 1;
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new BrowserAutomationError("Browser automation client is closed", "connection");
+        }
+    }
+}
+export async function connectBrowserAutomation(options) {
+    return await BrowserAutomationClient.connect(options);
+}
+class CdpConnection {
+    socket;
+    timeoutMs;
+    nextId = 1;
+    closed = false;
+    pending = new Map();
+    eventListeners = new Set();
+    constructor(socket, timeoutMs) {
+        this.socket = socket;
+        this.timeoutMs = timeoutMs;
+        socket.onmessage = (event) => this.receive(event.data);
+        socket.onerror = () => this.failConnection("CDP WebSocket failed");
+        socket.onclose = (event) => {
+            const detail = event.reason
+                ? `: ${event.reason}`
+                : event.code
+                    ? ` (code ${event.code})`
+                    : "";
+            this.failConnection(`CDP WebSocket closed${detail}`);
+        };
+    }
+    static async connect(endpoint, timeoutMs, createWebSocket) {
+        let socket;
+        try {
+            socket = createWebSocket(endpoint);
+        }
+        catch (error) {
+            throw new BrowserAutomationError(`Could not create CDP WebSocket: ${errorMessage(error)}`, "connection");
+        }
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                socket.close(1000, "connection timeout");
+                reject(new BrowserAutomationError(`CDP WebSocket did not open within ${timeoutMs}ms`, "timeout"));
+            }, timeoutMs);
+            socket.onopen = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            socket.onerror = () => {
+                clearTimeout(timer);
+                reject(new BrowserAutomationError("CDP WebSocket failed to open", "connection"));
+            };
+            socket.onclose = () => {
+                clearTimeout(timer);
+                reject(new BrowserAutomationError("CDP WebSocket closed before opening", "connection"));
+            };
+        });
+        return new CdpConnection(socket, timeoutMs);
+    }
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+    }
+    async call(method, params = {}, sessionId) {
+        if (this.closed || this.socket.readyState !== WEB_SOCKET_OPEN) {
+            throw new BrowserAutomationError("CDP WebSocket is not open", "connection");
+        }
+        if (this.pending.size >= MAX_PENDING_COMMANDS) {
+            throw new BrowserAutomationError(`CDP has ${MAX_PENDING_COMMANDS} pending commands`, "connection");
+        }
+        const id = this.nextId++;
+        const request = {
+            id,
+            method,
+            params,
+            ...(sessionId ? { sessionId } : {}),
+        };
+        return await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new BrowserAutomationError(`${method} timed out after ${this.timeoutMs}ms`, "timeout"));
+            }, this.timeoutMs);
+            this.pending.set(id, { method, resolve, reject, timer });
+            try {
+                this.socket.send(JSON.stringify(request));
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(new BrowserAutomationError(`${method} could not be sent: ${errorMessage(error)}`, "connection"));
+            }
+        });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.rejectPending(new BrowserAutomationError("CDP WebSocket was closed", "connection"));
+        if (this.socket.readyState <= WEB_SOCKET_OPEN) {
+            this.socket.close(1000, "automation client closed");
+        }
+    }
+    receive(data) {
+        let raw;
+        if (typeof data === "string") {
+            raw = data;
+        }
+        else if (data instanceof ArrayBuffer) {
+            if (data.byteLength > MAX_MESSAGE_BYTES) {
+                this.failConnection("CDP message exceeded its size limit");
+                return;
+            }
+            raw = new TextDecoder().decode(data);
+        }
+        else if (ArrayBuffer.isView(data)) {
+            if (data.byteLength > MAX_MESSAGE_BYTES) {
+                this.failConnection("CDP message exceeded its size limit");
+                return;
+            }
+            raw = new TextDecoder().decode(data);
+        }
+        else {
+            this.failConnection("CDP returned a non-text message");
+            return;
+        }
+        if (Buffer.byteLength(raw, "utf8") > MAX_MESSAGE_BYTES) {
+            this.failConnection("CDP message exceeded its size limit");
+            return;
+        }
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            this.failConnection("CDP returned invalid JSON");
+            return;
+        }
+        if (!message || typeof message !== "object" || Array.isArray(message)) {
+            this.failConnection("CDP returned an invalid message");
+            return;
+        }
+        if (typeof message.id === "number" && Number.isSafeInteger(message.id)) {
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            clearTimeout(pending.timer);
+            this.pending.delete(message.id);
+            if (message.error !== undefined) {
+                const error = isRecord(message.error) ? message.error : {};
+                const detail = optionalString(error.message) ?? "unknown protocol error";
+                pending.reject(protocolError(`${pending.method} failed: ${detail}`));
+            }
+            else {
+                pending.resolve(message.result ?? {});
+            }
+            return;
+        }
+        if (typeof message.method === "string") {
+            const params = isRecord(message.params) ? message.params : {};
+            const sessionId = optionalString(message.sessionId);
+            for (const listener of this.eventListeners) {
+                try {
+                    listener(message.method, params, sessionId);
+                }
+                catch {
+                    // Observers cannot corrupt command transport.
+                }
+            }
+            return;
+        }
+        this.failConnection("CDP returned an unrecognized message");
+    }
+    failConnection(message) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.rejectPending(new BrowserAutomationError(message, "connection"));
+        if (this.socket.readyState <= WEB_SOCKET_OPEN) {
+            this.socket.close(1002, "invalid CDP connection");
+        }
+    }
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}
+async function selectPageTarget(connection, requestedTargetId) {
+    const result = requireRecord(await connection.call("Target.getTargets"), "Target.getTargets result");
+    if (!Array.isArray(result.targetInfos)) {
+        throw protocolError("Target.getTargets result targetInfos must be an array");
+    }
+    const pages = result.targetInfos
+        .map((value) => (isRecord(value) ? value : undefined))
+        .filter((value) => value !== undefined &&
+        value.type === "page" &&
+        typeof value.targetId === "string");
+    const selected = requestedTargetId
+        ? pages.find((target) => target.targetId === requestedTargetId)
+        : pages[0];
+    if (!selected) {
+        throw new BrowserAutomationError(requestedTargetId
+            ? `CDP Page target ${requestedTargetId} was not found`
+            : "CDP endpoint has no Page target", "target_not_found");
+    }
+    return selected.targetId;
+}
+function defaultWebSocketFactory(endpoint) {
+    const Constructor = globalThis.WebSocket;
+    if (typeof Constructor !== "function") {
+        throw new BrowserAutomationError("This runtime does not provide a WebSocket client", "connection");
+    }
+    return new Constructor(endpoint);
+}
+function encodeElementReference(referenceScope, documentIdentity, backendNodeId, referenceKey) {
+    const payload = Buffer.alloc(REFERENCE_PAYLOAD_BYTES);
+    payload[0] = REFERENCE_VERSION;
+    documentFingerprint(referenceScope, documentIdentity).copy(payload, 1);
+    payload.writeBigUInt64BE(BigInt(backendNodeId), 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
+    const tag = referenceTag(payload, referenceKey);
+    return Buffer.concat([payload, tag]).toString("base64url");
+}
+function decodeElementReference(ref, referenceScope, documentIdentity, referenceKey) {
+    if (typeof ref !== "string" ||
+        ref.length === 0 ||
+        !/^[A-Za-z0-9_-]+$/.test(ref)) {
+        throw new BrowserAutomationStaleReferenceError(String(ref));
+    }
+    let encoded;
+    try {
+        encoded = Buffer.from(ref, "base64url");
+    }
+    catch {
+        throw new BrowserAutomationStaleReferenceError(ref);
+    }
+    if (encoded.length !== REFERENCE_BYTES ||
+        encoded.toString("base64url") !== ref ||
+        encoded[0] !== REFERENCE_VERSION) {
+        throw new BrowserAutomationStaleReferenceError(ref);
+    }
+    const payload = encoded.subarray(0, REFERENCE_PAYLOAD_BYTES);
+    const actualTag = encoded.subarray(REFERENCE_PAYLOAD_BYTES);
+    if (!timingSafeEqual(actualTag, referenceTag(payload, referenceKey))) {
+        throw new BrowserAutomationStaleReferenceError(ref);
+    }
+    const expectedDocument = documentFingerprint(referenceScope, documentIdentity);
+    const actualDocument = payload.subarray(1, 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
+    if (!timingSafeEqual(actualDocument, expectedDocument)) {
+        throw new BrowserAutomationStaleReferenceError(ref);
+    }
+    const rawNodeId = payload.readBigUInt64BE(1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
+    if (rawNodeId < 1n || rawNodeId > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new BrowserAutomationStaleReferenceError(ref);
+    }
+    return Number(rawNodeId);
+}
+function documentFingerprint(referenceScope, documentIdentity) {
+    return createHash("sha256")
+        .update("rynx-browser-cdp-document-v1\0")
+        .update(referenceScope)
+        .update("\0")
+        .update(documentIdentity)
+        .digest()
+        .subarray(0, REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
+}
+function referenceTag(payload, referenceKey) {
+    return createHmac("sha256", referenceKey)
+        .update(REFERENCE_DOMAIN)
+        .update(payload)
+        .digest()
+        .subarray(0, REFERENCE_TAG_BYTES);
+}
+function parseReferenceKey(value) {
+    const key = typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(value);
+    if (key.length < 32 || key.length > 256) {
+        throw invalidInput("referenceKey must contain between 32 and 256 bytes");
+    }
+    return key;
+}
+function domLocator(element) {
+    if (element.objectId)
+        return { objectId: element.objectId };
+    if (element.backendNodeId !== undefined) {
+        return { backendNodeId: element.backendNodeId };
+    }
+    if (element.nodeId !== undefined)
+        return { nodeId: element.nodeId };
+    throw protocolError("Browser element has no CDP identity");
+}
+function parseEndpoint(endpoint) {
+    if (typeof endpoint !== "string" || endpoint.length === 0 || endpoint.length > 4_096) {
+        throw invalidInput("endpoint must be a non-empty bounded string");
+    }
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw invalidInput("endpoint must be a WebSocket URL");
+    }
+    if (url.protocol !== "ws:" ||
+        url.hostname !== "127.0.0.1" ||
+        url.port.length === 0 ||
+        url.username.length > 0 ||
+        url.password.length > 0 ||
+        url.pathname === "/" ||
+        url.search.length > 0 ||
+        url.hash.length > 0) {
+        throw invalidInput("endpoint must be a canonical 127.0.0.1 CDP WebSocket URL");
+    }
+    return url;
+}
+function inferEndpointKind(endpoint) {
+    if (endpoint.pathname.startsWith("/devtools/browser/"))
+        return "browser";
+    if (endpoint.pathname.startsWith("/devtools/page/"))
+        return "page";
+    throw invalidInput("endpointKind is required for a non-standard CDP WebSocket path");
+}
+function parseNavigationUrl(value) {
+    if (value === "about:blank")
+        return value;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw invalidInput("navigation URL must be absolute");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw invalidInput("navigation URL must use http or https");
+    }
+    return url.href;
+}
+function coordinateTarget(value) {
+    if (!Number.isFinite(value.x) || !Number.isFinite(value.y)) {
+        throw invalidInput("click coordinates must be finite");
+    }
+    return { x: value.x, y: value.y };
+}
+function numericQuad(value) {
+    if (!Array.isArray(value) ||
+        value.length !== 8 ||
+        value.some((coordinate) => typeof coordinate !== "number" || !Number.isFinite(coordinate))) {
+        throw protocolError("DOM.getBoxModel returned an invalid content quad");
+    }
+    return value;
+}
+function axString(value) {
+    return axOptionalString(value) ?? "";
+}
+function axOptionalString(value) {
+    if (!isRecord(value))
+        return undefined;
+    const candidate = value.value;
+    if (typeof candidate === "string" ||
+        typeof candidate === "number" ||
+        typeof candidate === "boolean") {
+        return String(candidate);
+    }
+    return undefined;
+}
+function axProperties(value) {
+    if (!Array.isArray(value))
+        return Object.freeze({});
+    const properties = {};
+    for (const entry of value) {
+        if (!isRecord(entry) || typeof entry.name !== "string")
+            continue;
+        const property = isRecord(entry.value) ? entry.value.value : undefined;
+        if (typeof property === "string" ||
+            typeof property === "number" ||
+            typeof property === "boolean") {
+            properties[entry.name] = property;
+        }
+    }
+    return Object.freeze(properties);
+}
+function canonicalBase64(value) {
+    if (value.length === 0 || value.length > MAX_MESSAGE_BYTES)
+        return false;
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+        return false;
+    }
+    return Buffer.from(value, "base64").toString("base64") === value;
+}
+function boundedInteger(value, minimum, maximum, field) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw invalidInput(`${field} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return value;
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0
+        ? value
+        : undefined;
+}
+function recordAt(value, key) {
+    return isRecord(value[key]) ? value[key] : undefined;
+}
+function stringAt(value, key) {
+    return optionalString(value[key]);
+}
+function optionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function requiredString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw protocolError(`${field} must be a non-empty string`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireRecord(value, field) {
+    if (!isRecord(value))
+        throw protocolError(`${field} must be an object`);
+    return value;
+}
+function invalidInput(message) {
+    return new BrowserAutomationError(message, "invalid_input");
+}
+function protocolError(message) {
+    return new BrowserAutomationError(message, "protocol");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { BrowserAutomationClient, BrowserAutomationError, BrowserAutomationStaleReferenceError, connectBrowserAutomation, type BrowserAutomationClientOptions, type BrowserAutomationClickTarget, type BrowserAutomationElementTarget, type BrowserAutomationEndpointKind, type BrowserAutomationNavigateResult, type BrowserAutomationScreenshot, type BrowserAutomationScreenshotOptions, type BrowserAutomationSnapshot, type BrowserAutomationSnapshotNode, type BrowserAutomationWebSocket, type BrowserAutomationWebSocketFactory, } from "./client.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { BrowserAutomationClient, BrowserAutomationError, BrowserAutomationStaleReferenceError, connectBrowserAutomation, } from "./client.js";

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@rynx-ai/browser-cdp",
+  "version": "0.1.10",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rynx-ai/rynx.git",
+    "directory": "packages/browser-cdp"
+  },
+  "description": "Dependency-free CDP client for Rynx Browser automation.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json"
+  }
+}