@ap3x/browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+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/README.md

@@ -0,0 +1,30 @@
+# @ap3x/browser
+
+Primitives for driving Chromium over the Chrome DevTools Protocol: sessions, navigation, DOM extraction, input, screenshots, and recording.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/browser
+```
+
+## What's inside
+
+- **`openBrowserSession(config)`** — the entry point; resolves to a local launch or a remote CDP endpoint.
+- **CDP transport** — typed protocol access with a target registry and reconnect handling.
+- **DOM** — extraction, serialization, clickability and paint-order analysis, and stable element hashing.
+- **Navigation** — a navigation policy with domain allow-lists and IP-blocking rules.
+- **Input** — human-like input dispatch with dialog resilience.
+- **Capture** — screenshots, HAR recording, and screencast.
+
+The agent that drives these lives in [`@ap3x/browser-agent`](https://www.npmjs.com/package/@ap3x/browser-agent).
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/cdp/connection.d.ts

@@ -0,0 +1,53 @@
+import { CdpConnectionError } from "../errors";
+import type { CdpCommand, CdpCommandParams, CdpCommandReturn, CdpEventListener, CdpEventName, CdpSendOptions, CdpTransport } from "../types";
+/**
+ * The minimal socket surface {@link CdpConnection} needs. `ws` is adapted to it
+ * by {@link openWebSocket}; tests inject a fake so no real browser is required.
+ */
+export interface CdpSocket {
+    send(data: string): void;
+    close(): void;
+    onMessage(cb: (data: string) => void): void;
+    onClose(cb: () => void): void;
+    onError(cb: (err: Error) => void): void;
+}
+export interface OpenWebSocketOptions {
+    headers?: Record<string, string>;
+    maxPayload?: number;
+    signal?: AbortSignal;
+}
+/** Open a real `ws` WebSocket and adapt it to {@link CdpSocket}. */
+export declare function openWebSocket(url: string, options?: OpenWebSocketOptions): Promise<CdpSocket>;
+export interface CdpConnectionOptions {
+    /** Default per-request timeout in ms (default 60000). */
+    defaultTimeoutMs?: number;
+    /**
+     * Debug-level diagnostic sink (e.g. a dropped malformed frame). Default:
+     * silent — this is a library, not a host; callers opt in.
+     */
+    onDebug?: (message: string, fields?: Record<string, unknown>) => void;
+}
+export declare class CdpConnection implements CdpTransport {
+    private readonly socket;
+    private nextId;
+    private readonly pending;
+    private readonly registrations;
+    private readonly disconnectListeners;
+    private readonly defaultTimeoutMs;
+    private readonly onDebug;
+    private closedError;
+    private intentional;
+    constructor(socket: CdpSocket, options?: CdpConnectionOptions);
+    /** Open a live connection to a `ws://` DevTools endpoint. */
+    static connect(wsUrl: string, options?: CdpConnectionOptions & OpenWebSocketOptions): Promise<CdpConnection>;
+    get isClosed(): boolean;
+    /** Fired once when the socket drops unexpectedly (not on {@link close}). */
+    onDisconnect(cb: (err: CdpConnectionError) => void): () => void;
+    send<T extends CdpCommand>(method: T, params?: CdpCommandParams<T>, options?: CdpSendOptions): Promise<CdpCommandReturn<T>>;
+    on<M extends CdpEventName>(method: M, listener: CdpEventListener<M>, sessionId?: string): () => void;
+    close(): Promise<void>;
+    private handleMessage;
+    private dispatchEvent;
+    private handleClose;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/cdp/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/cdp/connection.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,YAAY,EACb,MAAM,UAAU,CAAC;AAMlB;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9B,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CAiC7F;AAaD,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACvE;AAED,qBAAa,aAAc,YAAW,YAAY;IAW9C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVzB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;IACtE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAgD;IACpF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8D;IACtF,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,WAAW,CAAS;gBAGT,MAAM,EAAE,SAAS,EAClC,OAAO,CAAC,EAAE,oBAAoB;IAUhC,6DAA6D;WAChD,OAAO,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,GACpD,OAAO,CAAC,aAAa,CAAC;IAKzB,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,4EAA4E;IAC5E,YAAY,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI;IAOzD,IAAI,CAAC,CAAC,SAAS,UAAU,EAC7B,MAAM,EAAE,CAAC,EACT,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IA4C/B,EAAE,CAAC,CAAC,SAAS,YAAY,EACvB,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC7B,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,IAAI;IAiBP,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B,OAAO,CAAC,aAAa;IA0DrB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;CAapB"}

package/dist/cdp/endpoint.d.ts

@@ -0,0 +1,18 @@
+export interface ResolveCdpOptions {
+    /** Injected fetch (tests / proxy control). Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Resolve a CDP endpoint to a `ws(s)://` debugger url.
+ *
+ * - `ws://` / `wss://` → returned as-is.
+ * - `http://` / `https://` → fetch `<base>/json/version` and read
+ *   `webSocketDebuggerUrl`.
+ *
+ * localhost DevTools is proxy-exempt (design §7.3.1 `trust_env=False`): Node's
+ * global fetch (undici) does not honour HTTP(S)_PROXY env by default, so no
+ * proxy stripping is needed for 127.0.0.1/localhost/::1.
+ * ponytail: revisit only if a global undici ProxyAgent is ever installed.
+ */
+export declare function resolveCdpWebSocketUrl(url: string, options?: ResolveCdpOptions): Promise<string>;
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/cdp/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../src/cdp/endpoint.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAsDjB"}

package/dist/cdp/reconnect.d.ts

@@ -0,0 +1,22 @@
+import { CdpConnectionError } from "../errors";
+import type { CdpConnection } from "./connection";
+export interface ReconnectEvents {
+    onReconnecting?: (attempt: number, max: number) => void;
+    onReconnected?: (connection: CdpConnection) => void;
+    onFailed?: (err: CdpConnectionError) => void;
+}
+export interface ReconnectOptions {
+    /** Number of attempts (default 3). */
+    attempts?: number;
+    /** Backoff before attempts 2..N (default [1000, 2000, 4000] ms). */
+    delaysMs?: number[];
+    /** Per-attempt timeout (default 15000 ms). */
+    attemptTimeoutMs?: number;
+}
+/**
+ * Rebuild a connection with bounded retries. `connect` receives an AbortSignal
+ * that fires when the per-attempt budget is exceeded. Resolves with the first
+ * successful connection or throws a `reconnect_failed` {@link CdpConnectionError}.
+ */
+export declare function reconnectWithBackoff(connect: (signal: AbortSignal) => Promise<CdpConnection>, events?: ReconnectEvents, options?: ReconnectOptions): Promise<CdpConnection>;
+//# sourceMappingURL=reconnect.d.ts.map

package/dist/cdp/reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.d.ts","sourceRoot":"","sources":["../../src/cdp/reconnect.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,aAAa,KAAK,IAAI,CAAC;IACpD,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAiBD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,EACxD,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,aAAa,CAAC,CA2BxB"}

package/dist/chunk-DXCP25KX.js

@@ -0,0 +1,77 @@
+// src/testing.ts
+var FakeCdpTransport = class {
+  constructor(responses = /* @__PURE__ */ new Map()) {
+    this.responses = responses;
+  }
+  responses;
+  /** Every `send` in order, for assertions. */
+  calls = [];
+  registrations = /* @__PURE__ */ new Map();
+  disconnectListeners = /* @__PURE__ */ new Set();
+  async send(method, params, options) {
+    this.calls.push({ method, params, sessionId: options?.sessionId });
+    const responder = this.responses.get(method);
+    const value = typeof responder === "function" ? responder(params, options?.sessionId) : responder;
+    return value ?? {};
+  }
+  on(method, listener, sessionId) {
+    const key = method;
+    let set = this.registrations.get(key);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.registrations.set(key, set);
+    }
+    const registration = {
+      listener,
+      sessionId
+    };
+    set.add(registration);
+    return () => {
+      set.delete(registration);
+    };
+  }
+  /** Push a canned CDP event to matching subscribers. */
+  emitEvent(method, params, sessionId) {
+    const set = this.registrations.get(method);
+    if (!set) return;
+    for (const registration of [...set]) {
+      if (registration.sessionId === void 0 || registration.sessionId === sessionId) {
+        registration.listener(params, sessionId);
+      }
+    }
+  }
+  onDisconnect(cb) {
+    this.disconnectListeners.add(cb);
+    return () => {
+      this.disconnectListeners.delete(cb);
+    };
+  }
+  /** Simulate an unexpected socket drop for tests. */
+  emitDisconnect(err) {
+    for (const cb of [...this.disconnectListeners]) cb(err);
+  }
+  /** Number of `send`s recorded for a method. */
+  sendCount(method) {
+    return this.calls.filter((c) => c.method === method).length;
+  }
+  async close() {
+    this.registrations.clear();
+  }
+};
+function groundTruth(session) {
+  return {
+    /** Evaluate an arbitrary expression in the page and return the JSON value. */
+    evalInPage: (expression) => session.evaluate(expression),
+    /** `window.getClickCount()` — the golden-fixture click-counter contract (design/08-09 §9.3). */
+    clickCount: () => session.evaluate("window.getClickCount()"),
+    /** The live `.value` of the element matched by `selector`. */
+    inputValue: (selector) => session.evaluate(`document.querySelector(${JSON.stringify(selector)}).value`),
+    /** The live `.checked` of the element matched by `selector`. */
+    checked: (selector) => session.evaluate(`document.querySelector(${JSON.stringify(selector)}).checked`)
+  };
+}
+
+export {
+  FakeCdpTransport,
+  groundTruth
+};

package/dist/config.d.ts

@@ -0,0 +1,91 @@
+/** Cloak (CloakBrowser / cloakserve) connection settings. All optional here — the
+ * factory requires `endpoint` before building a {@link CloakProvider}. */
+export interface CloakConfig {
+    /** cloakserve base URL or a launched CloakBrowser CDP url (http(s):// or ws(s)://). */
+    readonly endpoint?: string;
+    /** Fingerprint seed (cloakserve `fingerprint`). */
+    readonly fingerprint?: string;
+    /** Fingerprint platform (cloakserve `fingerprint-platform`). */
+    readonly platform?: "windows" | "macos";
+    /** Upstream proxy (cloakserve `proxy`). */
+    readonly proxy?: string;
+    /** Derive geo from the proxy IP (cloakserve `geoip`). */
+    readonly geoip?: string;
+    /** Humanize input timing (cloakserve `humanize`). */
+    readonly humanize?: boolean;
+    /** Spoofed timezone (cloakserve `timezone`). */
+    readonly timezone?: string;
+    /** Spoofed locale (cloakserve `locale`). */
+    readonly locale?: string;
+}
+/** The frozen configuration a {@link BrowserSession} is built from. */
+export interface ResolvedBrowserConfig {
+    /** Which provider yields the session — stock local Chrome or a stealth CloakBrowser. */
+    readonly provider: "local" | "cloak";
+    /** Cloak connection settings (only used when `provider === "cloak"`). */
+    readonly cloak: CloakConfig;
+    /** Launch headless (only relevant to the launch path). */
+    readonly headless: boolean;
+    /** CDP endpoint to connect to (the connect path / CloakBrowser seam). */
+    readonly cdpUrl?: string;
+    /** Allow-list for navigation (empty = open). */
+    readonly allowedDomains: readonly string[];
+    /** Deny-list for navigation. */
+    readonly prohibitedDomains: readonly string[];
+    /** Block navigation to raw IP addresses (SSRF guard). */
+    readonly blockIpAddresses: boolean;
+    /** Opt-in (W27): permit `file://` navigation, otherwise unconditionally
+     * blocked by NavigationPolicy. Default-deny — reads local disk. */
+    readonly allowFileUrls: boolean;
+    /**
+     * C3 global dialog override: force-accept (true) or force-dismiss (false)
+     * ALL dialog types. When undefined (the default), each type uses its own
+     * per-type default (prompt→dismiss, others→accept).
+     */
+    readonly dialogAccept?: boolean;
+    /** Text for accepted `prompt()` dialogs. */
+    readonly dialogPromptText?: string;
+    /** Draw the numbered highlight overlay before screenshots (M5). */
+    readonly highlightElements: boolean;
+    /** Descend cross-origin (out-of-process) iframes during DOM capture. */
+    readonly crossOriginIframes: boolean;
+    /**
+     * The five DomServiceOptions perception knobs. Undefined (the default at
+     * every level) means DomService's own default stays authoritative — config
+     * never hardcodes a value that could drift from it.
+     */
+    readonly maxIframeDepth?: number;
+    readonly viewportThreshold?: number | null;
+    readonly includeAttributes?: readonly string[];
+    readonly paintOrderFiltering?: boolean;
+    readonly enableBboxFiltering?: boolean;
+}
+/** Overrides accepted by {@link resolveBrowserConfig} (all optional). */
+export type BrowserConfigOverrides = Partial<{
+    provider: "local" | "cloak";
+    cloak: CloakConfig;
+    headless: boolean;
+    cdpUrl: string;
+    allowedDomains: readonly string[];
+    prohibitedDomains: readonly string[];
+    blockIpAddresses: boolean;
+    allowFileUrls: boolean;
+    dialogAccept: boolean;
+    dialogPromptText: string;
+    highlightElements: boolean;
+    crossOriginIframes: boolean;
+    maxIframeDepth: number;
+    viewportThreshold: number | null;
+    includeAttributes: readonly string[];
+    paintOrderFiltering: boolean;
+    enableBboxFiltering: boolean;
+}>;
+/** The env source read by {@link resolveBrowserConfig} (a subset of process.env). */
+export type EnvSource = Record<string, string | undefined>;
+/**
+ * Merge overrides over the `AP3X_BROWSER_*` environment over the defaults and
+ * freeze the result. Call once per session; the object never re-reads env. The
+ * env source is injectable (defaults to `process.env`) for pure testing.
+ */
+export declare function resolveBrowserConfig(overrides?: BrowserConfigOverrides, source?: EnvSource): ResolvedBrowserConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/dialogs/handler.d.ts

@@ -0,0 +1,43 @@
+import { TypedEmitter } from "../events";
+import type { CdpTransport } from "../types";
+/** A dialog that opened and was auto-answered. */
+export interface DialogNotification {
+    type: string;
+    message: string;
+    accepted: boolean;
+    sessionId?: string;
+}
+export interface DialogHandlerEvents {
+    dialog: DialogNotification;
+}
+export interface DialogHandlerOptions {
+    /**
+     * C3 global override: force-accept (true) or force-dismiss (false) EVERY
+     * dialog type. When undefined (the default), each type uses its own per-type
+     * default — see {@link DialogHandler.policyFor}.
+     */
+    accept?: boolean;
+    /** Text supplied to `prompt()` dialogs when accepting. */
+    promptText?: string;
+}
+export declare class DialogHandler {
+    private readonly transport;
+    readonly events: TypedEmitter<DialogHandlerEvents>;
+    private readonly accept?;
+    private readonly promptText?;
+    private unsubscribe?;
+    constructor(transport: CdpTransport, options?: DialogHandlerOptions);
+    /**
+     * The accept/dismiss decision for a dialog type. The C3 global override wins
+     * when set; otherwise the per-type default applies: `prompt` is
+     * dismissed (accepting would send "" instead of null — no input available),
+     * everything else (alert / confirm / beforeunload) is accepted.
+     */
+    private policyFor;
+    /** Begin auto-answering dialogs across all sessions. Idempotent. */
+    start(): void;
+    /** Stop auto-answering. */
+    stop(): void;
+    private handle;
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/dialogs/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/dialogs/handler.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN5B,QAAQ,CAAC,MAAM,oCAA2C;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,WAAW,CAAC,CAAa;gBAGd,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,oBAAyB;IAMpC;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAKjB,oEAAoE;IACpE,KAAK,IAAI,IAAI;IAOb,2BAA2B;IAC3B,IAAI,IAAI,IAAI;YAKE,MAAM;CAoBrB"}

package/dist/dom/clickability.d.ts

@@ -0,0 +1,4 @@
+import { type EnhancedDOMTreeNode } from "./types";
+/** True iff the node is treated as clickable/interactive. Pure. */
+export declare function isInteractive(node: EnhancedDOMTreeNode): boolean;
+//# sourceMappingURL=clickability.d.ts.map

package/dist/dom/clickability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickability.d.ts","sourceRoot":"","sources":["../../src/dom/clickability.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,mBAAmB,EAAY,MAAM,SAAS,CAAC;AAwE7D,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAiHhE"}

package/dist/dom/compound.d.ts

@@ -0,0 +1,4 @@
+import { type EnhancedDOMTreeNode, type SimplifiedNode } from "./types";
+/** Append compound sub-components to `node.compoundChildren`; mark `simplified`. */
+export declare function addCompoundComponents(simplified: SimplifiedNode, node: EnhancedDOMTreeNode): void;
+//# sourceMappingURL=compound.d.ts.map

package/dist/dom/compound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compound.d.ts","sourceRoot":"","sources":["../../src/dom/compound.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,mBAAmB,EAExB,KAAK,cAAc,EACpB,MAAM,SAAS,CAAC;AA+FjB,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,cAAc,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAsGjG"}

package/dist/dom/constants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The ~55 attributes the serializer surfaces to the LLM by default, in the
+ * order they are emitted. Mixes HTML attributes, synthetic format hints, and
+ * AX-derived properties (see design/04a §4.25). `class` is intentionally omitted
+ * (deliberately omitted, to force structural rather than class-name reasoning).
+ */
+export declare const DEFAULT_INCLUDE_ATTRIBUTES: readonly string[];
+/** Attributes considered identity-stable, fed into element hashing (design/05). */
+export declare const STATIC_ATTRIBUTES: ReadonlySet<string>;
+/** Substrings marking transient CSS-state classes, dropped from the stable hash. */
+export declare const DYNAMIC_CLASS_PATTERNS: ReadonlySet<string>;
+/**
+ * The 10 computed styles requested from `DOMSnapshot.captureSnapshot`, in order.
+ * The response returns style values positionally aligned to THIS list, so the
+ * order is load-bearing. Deliberately minimal: requesting more crashes Chrome on
+ * heavy pages (design/04a §4.26).
+ */
+export declare const REQUIRED_COMPUTED_STYLES: readonly string[];
+/** Elements never serialized (no interaction / content value). */
+export declare const DISABLED_ELEMENTS: ReadonlySet<string>;
+/** SVG child elements skipped as decorative. */
+export declare const SVG_ELEMENTS: ReadonlySet<string>;
+/**
+ * AP3X's opt-out attribute — AP3X-branded, per Hard Constraint 1. An element whose
+ * value is "true" (case-insensitive) is dropped from serialization.
+ */
+export declare const EXCLUDE_ATTRIBUTE = "data-ap3x-exclude";
+//# sourceMappingURL=constants.d.ts.map

package/dist/dom/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/dom/constants.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAyDvD,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAkDhD,CAAC;AAEH,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAqBrD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAWrD,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAOhD,CAAC;AAEH,gDAAgD;AAChD,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAiB3C,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC"}

package/dist/dom/dom-service.d.ts

@@ -0,0 +1,65 @@
+import type { CdpTransport } from "../types";
+import type { BackendNodeId, TargetId } from "../types";
+import { type SerializerOptions } from "./serializer";
+import type { DomSelectorMap, EnhancedDOMTreeNode, TargetAllTrees } from "./types";
+/** The serialized page state the agent consumes. */
+export interface SerializedDom {
+    /** The numbered/indented text projection the LLM reads. */
+    serializedText: string;
+    /** backendNodeId → node. The `[N]` in `serializedText` == a key here. */
+    selectorMap: DomSelectorMap;
+    /** The raw merged tree root (kept for downstream geometry/coordinate needs). */
+    enhancedTree: EnhancedDOMTreeNode;
+}
+export interface SerializeFromSnapshotOptions extends SerializerOptions {
+    targetId: TargetId;
+    includeAttributes?: readonly string[];
+    viewportThreshold?: number | null;
+}
+/**
+ * Pure pipeline: raw trees → { serializedText, selectorMap, enhancedTree }. No
+ * CDP, no I/O. Handles same-origin iframe content and shadow roots inline (both
+ * present in the pierce:true capture). Cross-origin iframes must be pre-attached
+ * to the trees' DOM (the live orchestrator does this).
+ */
+export declare function serializeFromSnapshot(trees: TargetAllTrees, opts: SerializeFromSnapshotOptions): SerializedDom;
+/** Resolves a cross-origin iframe's frame to its own CDP target/session. */
+export type FrameTargetResolver = (frameId: string | undefined, src: string | undefined) => {
+    targetId: TargetId;
+    sessionId?: string;
+} | undefined;
+export interface DomServiceOptions {
+    /** Descend into out-of-process (cross-origin) iframes. Default false. */
+    crossOriginIframes?: boolean;
+    maxIframeDepth?: number;
+    viewportThreshold?: number | null;
+    includeAttributes?: readonly string[];
+    paintOrderFiltering?: boolean;
+    enableBboxFiltering?: boolean;
+    /** Required to descend OOPIFs when `crossOriginIframes` is on. */
+    resolveFrameTarget?: FrameTargetResolver;
+}
+/**
+ * Orchestrates the live capture + serialize for a focus target. Reuses one
+ * transport across steps. OOPIF descent recurses into child targets, threading
+ * the accumulated frame offset so child coordinates land in main-page space.
+ */
+export declare class DomService {
+    private readonly transport;
+    private readonly opts;
+    constructor(transport: CdpTransport, opts?: DomServiceOptions);
+    getSerializedDom(targetId: TargetId, sessionId: string | undefined, serializerOpts?: SerializerOptions, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SerializedDom>;
+    /** Build the merged tree, descending OOPIFs (recursively — an OOPIF's own
+     * subtree may itself contain further OOPIFs) when enabled. Bounded by
+     * `maxIframeDepth` (default 5, via `buildEnhancedTree`'s own gate), so a
+     * cyclic frame graph cannot recurse forever. */
+    private buildWithOopif;
+}
+/**
+ * Resolve an element by its map key — the CDP backendNodeId, i.e. the `[N]` the
+ * LLM emitted. Same integer everywhere (design/10 gap #1).
+ */
+export declare function getElementByIndex(selectorMap: DomSelectorMap, index: BackendNodeId): EnhancedDOMTreeNode | undefined;
+//# sourceMappingURL=dom-service.d.ts.map

package/dist/dom/dom-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-service.d.ts","sourceRoot":"","sources":["../../src/dom/dom-service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAIxD,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAErE,OAAO,KAAK,EAAW,cAAc,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAI5F,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,WAAW,EAAE,cAAc,CAAC;IAC5B,gFAAgF;IAChF,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED,MAAM,WAAW,4BAA6B,SAAQ,iBAAiB;IACrE,QAAQ,EAAE,QAAQ,CAAC;IACnB,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,4BAA4B,GACjC,aAAa,CAUf;AAED,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,GAAG,EAAE,MAAM,GAAG,SAAS,KACpB;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,mBAAmB,CAAC;CAC1C;AAED;;;;GAIG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,SAAS,EAAE,YAAY,EACvB,IAAI,GAAE,iBAAsB;IAGzC,gBAAgB,CACpB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,cAAc,GAAE,iBAAsB,EACtC,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAClC,OAAO,CAAC,aAAa,CAAC;IAmBzB;;;oDAGgD;YAClC,cAAc;CA2C7B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,cAAc,EAC3B,KAAK,EAAE,aAAa,GACnB,mBAAmB,GAAG,SAAS,CAEjC"}

package/dist/dom/enhanced-tree.d.ts

@@ -0,0 +1,52 @@
+import type { TargetId } from "../types";
+import { type DOMRect, type EnhancedDOMTreeNode, type TargetAllTrees } from "./types";
+export interface BuildTreeOptions {
+    targetId: TargetId;
+    viewportThreshold?: number | null;
+    crossOriginIframes?: boolean;
+    maxIframeDepth?: number;
+    iframeDepth?: number;
+    /** Carried into an OOPIF recursion so its coordinates land in main-page space. */
+    initialFrameOffset?: DOMRect;
+    /**
+     * The CDP session this capture was taken from. Stamped on every node built by
+     * this call so `InputDispatcher` routes a backendNodeId to the session that
+     * minted it (design §4.23) — required for OOPIF subtrees, which are captured
+     * against a different target/session than the main page. Leave unset for the
+     * main-page build; same-origin iframe content (arrives inline via
+     * `pierce:true`) legitimately belongs to the parent session.
+     */
+    sessionId?: string;
+    /**
+     * Seam for cross-origin (out-of-process) iframes: called for each IFRAME with
+     * no inline content document, passing the node and the accumulated frame
+     * offset. The orchestrator captures that frame's target and attaches the built
+     * subtree as `contentDocument`. Same-origin iframes never reach here (their
+     * content arrives inline via `pierce:true`).
+     */
+    onOopifIframe?: (node: EnhancedDOMTreeNode, frameOffset: DOMRect) => void;
+}
+/**
+ * Element visibility per its full frame chain. CSS excludes first
+ * (display/visibility/opacity), then a geometric viewport-intersection test at
+ * each ancestor HTML frame. `viewportThreshold === null` skips geometry
+ * (CSS-only mode). Faithful to design/04a §4.24.
+ */
+export declare function isElementVisibleAccordingToAllParents(node: EnhancedDOMTreeNode, htmlFrames: EnhancedDOMTreeNode[], viewportThreshold?: number | null): boolean;
+/**
+ * Build the merged tree for one target's captures. Same-origin iframe content
+ * and shadow roots (both present in the `pierce:true` document) are recursed
+ * inline; cross-origin iframes are surfaced to `opts.onOopifIframe`.
+ */
+export declare function buildEnhancedTree(trees: TargetAllTrees, opts: BuildTreeOptions): EnhancedDOMTreeNode;
+/**
+ * Annotate every IFRAME/FRAME node that has a content document with hints about
+ * interactive elements hidden below its viewport: `hiddenElementsInfo` (sorted by
+ * pages-down, capped at 10) and `hasHiddenContent` (set when no interactive
+ * element is hidden but some non-interactive content is). Run on the fully
+ * assembled tree, AFTER build (and OOPIF attach), BEFORE serialization — the
+ * serializer reads these off the iframe node to emit scroll hints. Faithful to
+ * design/04a §4.24 (hidden-element counting across iframes).
+ */
+export declare function countHiddenElementsInIframes(node: EnhancedDOMTreeNode): void;
+//# sourceMappingURL=enhanced-tree.d.ts.map

package/dist/dom/enhanced-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhanced-tree.d.ts","sourceRoot":"","sources":["../../src/dom/enhanced-tree.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAIzC,OAAO,EACL,KAAK,OAAO,EAGZ,KAAK,mBAAmB,EAIxB,KAAK,cAAc,EACpB,MAAM,SAAS,CAAC;AAKjB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,EAAE,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3E;AA+CD;;;;;GAKG;AACH,wBAAgB,qCAAqC,CACnD,IAAI,EAAE,mBAAmB,EACzB,UAAU,EAAE,mBAAmB,EAAE,EACjC,iBAAiB,GAAE,MAAM,GAAG,IAAiC,GAC5D,OAAO,CAyCT;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,gBAAgB,GACrB,mBAAmB,CAgJrB;AAmDD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAoB5E"}

package/dist/dom/hashing.d.ts

@@ -0,0 +1,21 @@
+import { type DOMInteractedElement, type EnhancedDOMTreeNode } from "./types";
+/** Tag names of every ELEMENT ancestor, root → self. */
+export declare function parentBranchPath(node: EnhancedDOMTreeNode): string[];
+/**
+ * Drop transient CSS-state classes (any class whose lowercased form CONTAINS a
+ * dynamic pattern), then return the survivors sorted and space-joined — sorting
+ * makes the stable hash deterministic.
+ */
+export declare function filterDynamicClasses(classStr: string | undefined): string;
+/** Exact hash (MatchLevel.Exact): full static attributes, unfiltered. */
+export declare function elementHash(node: EnhancedDOMTreeNode): string;
+/** Stable hash (MatchLevel.Stable): dynamic classes filtered — survives class churn. */
+export declare function stableHash(node: EnhancedDOMTreeNode): string;
+/** Parent-branch hash: structural identity only (no attributes/ax). */
+export declare function parentBranchHash(node: EnhancedDOMTreeNode): string;
+/**
+ * Snapshot a node into a persisted interaction record. Both hashes are captured
+ * here so replay has a single source of truth (design/05 invariant).
+ */
+export declare function buildInteractedElement(node: EnhancedDOMTreeNode): DOMInteractedElement;
+//# sourceMappingURL=hashing.d.ts.map

package/dist/dom/hashing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing.d.ts","sourceRoot":"","sources":["../../src/dom/hashing.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,mBAAmB,EAAY,MAAM,SAAS,CAAC;AAMxF,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,EAAE,CASpE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAWzE;AAuBD,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAG7D;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAG5D;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAElE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,oBAAoB,CAgBtF"}

package/dist/dom/node.d.ts

@@ -0,0 +1,43 @@
+import { type DOMRect, type EnhancedDOMTreeNode } from "./types";
+/** Lower-cased tag name. */
+export declare function tagName(node: EnhancedDOMTreeNode): string;
+/** Real children (never the shared array). */
+export declare function children(node: EnhancedDOMTreeNode): EnhancedDOMTreeNode[];
+/** Children plus shadow roots — a fresh array, safe to iterate/mutate. */
+export declare function childrenAndShadowRoots(node: EnhancedDOMTreeNode): EnhancedDOMTreeNode[];
+/**
+ * Scroll detection combining CDP's flag with a CSS/geometry heuristic — catches
+ * scrollable containers CDP misses (common in iframes and dynamically-sized
+ * elements). Faithful to design/04a §4.25.
+ */
+export declare function isActuallyScrollable(node: EnhancedDOMTreeNode): boolean;
+/**
+ * Whether to render scroll info for this node. Always for iframes; else the node
+ * must be scrollable and not nested inside another scrollable (avoids spam);
+ * always for iframe-content body/html.
+ */
+export declare function shouldShowScrollInfo(node: EnhancedDOMTreeNode): boolean;
+interface ScrollInfo {
+    scrollableHeight: number;
+    scrollableWidth: number;
+    visibleHeight: number;
+    visibleWidth: number;
+    pagesAbove: number;
+    pagesBelow: number;
+    verticalScrollPct: number;
+    horizontalScrollPct: number;
+}
+/** Scroll geometry (pages above/below, percentages) or undefined if not scrollable. */
+export declare function scrollInfo(node: EnhancedDOMTreeNode): ScrollInfo | undefined;
+/** Human-readable scroll text, e.g. "1.0 pages above, 3.0 pages below". */
+export declare function getScrollInfoText(node: EnhancedDOMTreeNode): string;
+/**
+ * XPath for a node, passing THROUGH shadow roots and stopping AT iframe
+ * boundaries (xpath is per-document). Position `[n]` is 1-based and only emitted
+ * when there is more than one same-tag sibling.
+ */
+export declare function xpath(node: EnhancedDOMTreeNode): string;
+/** Absolute bounds, if known. */
+export declare function absoluteBounds(node: EnhancedDOMTreeNode): DOMRect | undefined;
+export {};
+//# sourceMappingURL=node.d.ts.map