browxai 0.7.0

package/dist/page/network.js

@@ -0,0 +1,415 @@
+// CDP network tap for an "action window" — open before dispatch, close after
+// network-idle-ish quiet. Filters out the high-noise/low-signal resource types by
+// default (images, fonts, stylesheets, media, beacons); they're still counted in
+// the summary's `byType.other` bucket if you want the totals back.
+import { invariant } from "../util/invariant.js";
+import { patternisePath } from "../util/url-sanitizer.js";
+import { maskedUrl } from "./network-mask.js";
+export const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+const MAX_RESPONSE_SHAPE_KEYS = 20;
+export const MAX_BODY_BYTES_TO_PARSE = 256_000; // skip parsing huge bodies; ~256KB JSON ceiling
+const NOISE_TYPES = new Set(["Image", "Font", "Stylesheet", "Media", "Manifest"]);
+const BEACON_HINTS = ["beacon", "/collect", "analytics", "gtag", "doubleclick", "pixel"];
+function isBeacon(url) {
+    const lower = url.toLowerCase();
+    return BEACON_HINTS.some((h) => lower.includes(h));
+}
+/** Map Playwright's `request.resourceType()` (lowercase, a slightly coarser
+ *  taxonomy) onto the CDP-capitalised type names the CDP tap emits, so the
+ *  noise-fold (`NOISE_TYPES`) + `byType` summary buckets are identical in shape
+ *  across engines. The resourceType nuance to be aware of: a few
+ *  CDP types (`Ping`, `CSPViolationReport`, `Preflight`, …) have no Playwright
+ *  equivalent and fold into `Other`; `xhr`/`fetch` both map to their CDP forms.
+ *  This is the only place engine resourceType skew is reconciled. */
+const PW_RESOURCE_TYPE = {
+    document: "Document",
+    stylesheet: "Stylesheet",
+    image: "Image",
+    media: "Media",
+    font: "Font",
+    script: "Script",
+    texttrack: "TextTrack",
+    xhr: "XHR",
+    fetch: "Fetch",
+    eventsource: "EventSource",
+    websocket: "WebSocket",
+    manifest: "Manifest",
+    other: "Other",
+};
+/** Exported for unit tests of the cross-engine resourceType reconciliation. */
+export function cdpTypeFromPlaywright(resourceType) {
+    return PW_RESOURCE_TYPE[resourceType] ?? "Other";
+}
+/** Fold a finished-entry list into the `{summary, requests}` the network_read /
+ *  action-tap egress emits: noise/beacon entries collapse into `summary.byType
+ *  .other` (and stay out of `requests`), failures count toward `summary.failed`,
+ *  and the surviving "interesting" entries have their URL masked at egress. This
+ *  is the EXACT logic the CDP `NetworkTap.close()` / `NetworkBuffer.recent()`
+ *  loops run inline; extracted so the Playwright-event buffers/tap produce a
+ *  byte-identical shape without duplicating the rule. */
+export function foldInteresting(entries, secrets) {
+    const summary = { total: entries.length, byType: {}, failed: 0 };
+    const interesting = [];
+    for (const e of entries) {
+        let bucket = e.type;
+        if (NOISE_TYPES.has(e.type) || isBeacon(e.url))
+            bucket = "other";
+        summary.byType[bucket] = (summary.byType[bucket] ?? 0) + 1;
+        if (e.failed)
+            summary.failed += 1;
+        if (bucket !== "other")
+            interesting.push({ ...e, url: maskedUrl(e.url, secrets) });
+    }
+    return { summary, requests: interesting };
+}
+export class NetworkTap {
+    cdp;
+    secrets;
+    requests = new Map();
+    finished = [];
+    mutationPromises = [];
+    listeners = [];
+    enabled = false;
+    /** Optional per-session secrets registry. When non-null, every URL +
+     *  response-shape key that leaves through `close()` is run through the
+     *  egress masking layer in addition to the URL sanitiser. */
+    constructor(cdp, secrets = null) {
+        this.cdp = cdp;
+        this.secrets = secrets;
+    }
+    async open() {
+        if (!this.enabled) {
+            await this.cdp.send("Network.enable");
+            this.enabled = true;
+        }
+        this.requests.clear();
+        this.finished = [];
+        this.mutationPromises = [];
+        const onRequest = (e) => {
+            this.requests.set(e.requestId, {
+                method: e.request.method,
+                url: e.request.url,
+                type: e.type ?? "Other",
+                startedAt: Date.now(),
+            });
+        };
+        const onResponse = (e) => {
+            const r = this.requests.get(e.requestId);
+            if (!r)
+                return;
+            const ms = Date.now() - r.startedAt;
+            this.finished.push({
+                method: r.method,
+                url: r.url,
+                status: e.response.status,
+                type: r.type,
+                ms,
+            });
+            // write-shaped + 2xx → kick off a bounded body probe for `mutations`.
+            // Captured request fields are snapshotted into the closure since the entry
+            // gets deleted below.
+            if (MUTATION_METHODS.has(r.method) && e.response.status >= 200 && e.response.status < 300) {
+                this.mutationPromises.push(probeMutation(this.cdp, e.requestId, {
+                    method: r.method,
+                    url: r.url,
+                    status: e.response.status,
+                    durationMs: ms,
+                }));
+            }
+            this.requests.delete(e.requestId);
+        };
+        const onFailed = (e) => {
+            const r = this.requests.get(e.requestId);
+            if (!r)
+                return;
+            this.finished.push({
+                method: r.method,
+                url: r.url,
+                type: r.type,
+                failed: true,
+                ms: Date.now() - r.startedAt,
+            });
+            this.requests.delete(e.requestId);
+        };
+        this.cdp.on("Network.requestWillBeSent", onRequest);
+        this.cdp.on("Network.responseReceived", onResponse);
+        this.cdp.on("Network.loadingFailed", onFailed);
+        this.listeners = [
+            () => this.cdp.off("Network.requestWillBeSent", onRequest),
+            () => this.cdp.off("Network.responseReceived", onResponse),
+            () => this.cdp.off("Network.loadingFailed", onFailed),
+        ];
+    }
+    /**
+     * Stop listening and produce a `{ summary, requests, mutations }` snapshot of
+     * the window. `requests` only includes the "interesting" entries (non-noise,
+     * non-beacon). Noise still counts toward `summary.byType.other`. `mutations`
+     * is awaited from the response-body probes kicked off during the window.
+     */
+    async close() {
+        for (const off of this.listeners)
+            off();
+        this.listeners = [];
+        // The summary/interesting fold is the shared `foldInteresting` rule (RFC 0004
+        // P3 / D4) — noise/beacon entries collapse into `summary.byType.other` and stay
+        // out of `requests`, failures count toward `summary.failed`, and surviving
+        // entries are URL-masked at egress. The ring keeps the raw url so beacon
+        // detection / url-substring filtering still see the real value; masking
+        // composes with the URL sanitiser (regex on URL shape vs literal value scan).
+        const { summary, requests: interesting } = foldInteresting(this.finished, this.secrets);
+        const mutationsRaw = (await Promise.all(this.mutationPromises)).filter((m) => m !== null);
+        // mask mutation URLs + responseShape keys at egress. A response-key name
+        // (`sessionToken`, `apiSecret`) typically won't literally equal a
+        // registered value, but the key list is still string data — applying the
+        // egress layer here keeps the rule "every egress sink masks" absolute.
+        const mutations = mutationsRaw.map((m) => {
+            const out = {
+                ...m,
+                urlPattern: this.secrets ? this.secrets.applyMaskInText(m.urlPattern) : m.urlPattern,
+            };
+            if (m.responseShape && this.secrets) {
+                out.responseShape = m.responseShape.map((k) => this.secrets.applyMaskInText(k));
+            }
+            return out;
+        });
+        return { summary, requests: interesting, mutations };
+    }
+}
+export { sanitizeFrame, WsBuffer } from "./network-ws.js";
+/**
+ * fetch a response body by CDP request id. Gated behind the off-by-
+ * default `network-body` capability — full bodies can carry PII / tokens.
+ * Bounded (`maxBytes`, default 256 KB). Best-effort: the renderer discards
+ * bodies fairly quickly, so this can legitimately fail with "not available".
+ */
+export async function fetchResponseBody(cdp, requestId, maxBytes = 256_000, secrets = null) {
+    try {
+        const { body, base64Encoded } = await cdp.send("Network.getResponseBody", { requestId });
+        const sliced = body.length > maxBytes ? body.slice(0, maxBytes) : body;
+        const truncated = body.length > maxBytes;
+        // egress masking. Base64 bodies pass through unchanged — the literal
+        // real-value scan would never match an encoded form, and the agent's
+        // contract for base64 is "decode then re-mask on your side." Document
+        // this caveat in docs/tool-reference.md.
+        const out = !base64Encoded && secrets ? secrets.applyMaskInText(sliced) : sliced;
+        return { ok: true, body: out, base64Encoded, ...(truncated ? { truncated: true } : {}) };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: (e instanceof Error ? e.message : String(e)) +
+                " — response bodies are short-lived; fetch right after the request, and note bodies aren't retained across navigations.",
+        };
+    }
+}
+async function probeMutation(cdp, requestId, detail) {
+    try {
+        const { body, base64Encoded } = await cdp.send("Network.getResponseBody", { requestId });
+        if (base64Encoded)
+            return mutationWithoutShape(detail);
+        if (body.length > MAX_BODY_BYTES_TO_PARSE)
+            return mutationWithoutShape(detail);
+        const trimmed = body.trim();
+        if (!trimmed)
+            return mutationWithoutShape(detail);
+        if (trimmed[0] !== "{" && trimmed[0] !== "[")
+            return mutationWithoutShape(detail);
+        const parsed = JSON.parse(trimmed);
+        return mutationWithShape(detail, extractTopLevelKeys(parsed));
+    }
+    catch {
+        // Body unavailable (already discarded), CDP error, or JSON parse failure.
+        // Skip the entry — we'd rather omit than emit something misleading.
+        return null;
+    }
+}
+export function mutationWithoutShape(detail) {
+    return {
+        method: detail.method,
+        urlPattern: patterniseUrl(detail.url),
+        status: detail.status,
+        ok: true,
+        durationMs: detail.durationMs,
+    };
+}
+/** Build a mutation entry, attaching the response shape only when non-empty —
+ *  the success path shared by the CDP and Playwright probes. */
+export function mutationWithShape(detail, responseShape) {
+    const entry = mutationWithoutShape(detail);
+    if (responseShape && responseShape.length > 0)
+        entry.responseShape = responseShape;
+    return entry;
+}
+/**
+ * Strip the query string and replace id-shaped path segments with `:id`. Keeps
+ * the route stable across requests for the same logical endpoint without
+ * leaking the specific record id in the result.
+ *
+ * Exported for unit tests.
+ */
+export function patterniseUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return url;
+    }
+    return `${u.origin}${patternisePath(u.pathname)}`;
+}
+/**
+ * Extract the top-level keys of a parsed JSON body. For an object, returns
+ * `Object.keys()`. For an array of objects, returns the first element's keys
+ * (prefixed with `[].` to signal array shape). Returns null otherwise.
+ *
+ * Capped at MAX_RESPONSE_SHAPE_KEYS entries. Exported for unit tests.
+ */
+export function extractTopLevelKeys(parsed) {
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return Object.keys(parsed).slice(0, MAX_RESPONSE_SHAPE_KEYS);
+    }
+    if (Array.isArray(parsed) &&
+        parsed.length > 0 &&
+        parsed[0] &&
+        typeof parsed[0] === "object" &&
+        !Array.isArray(parsed[0])) {
+        return Object.keys(parsed[0])
+            .slice(0, MAX_RESPONSE_SHAPE_KEYS)
+            .map((k) => `[].${k}`);
+    }
+    return null;
+}
+/**
+ * Session-wide ring buffer of network requests. Same shape as NetworkTap but
+ * always-on for the lifetime of the session — exposed via the `network_read`
+ * MCP tool. Per-action attribution still lives in `ActionResult.network`;
+ * this is the "what happened recently across the session" surface.
+ */
+export class NetworkBuffer {
+    cdp;
+    cap;
+    requests = new Map();
+    ring = [];
+    /** requestId → entry pointer for the entries currently in `ring`. Lets
+     *  `Network.loadingFinished` stamp `bytes` onto the corresponding entry
+     *  without a linear scan. Pruned in `push` when an entry is evicted. */
+    byReqId = new Map();
+    enabled = false;
+    secrets = null;
+    constructor(
+    // CDP is the network-tap substrate today; a later change will port it onto
+    // Playwright's request/response events so non-CDP engines are supported.
+    // On an engine without CDP (Firefox) the buffer
+    // is constructed but never attaches — `recent`/`since` reads return empty
+    // until the substrate port lands, rather than throwing at session creation.
+    cdp, cap = 500) {
+        this.cdp = cdp;
+        this.cap = cap;
+        // L7/L8: the ring cap is the bound that keeps the buffer from growing without
+        // limit (the audit's bounded-resource inventory pins it at 500). A
+        // non-positive cap would break `push`'s eviction (the ring could never retain
+        // an entry, or `shift()` would underflow), so the bound MUST be positive. The
+        // default is 500 and the only caller passes nothing, so this holds; the
+        // invariant makes the bound's positivity an asserted contract, not an
+        // assumption.
+        invariant(this.cap > 0, `NetworkBuffer ring cap must be positive, got ${this.cap}`);
+    }
+    setSecrets(secrets) {
+        this.secrets = secrets;
+    }
+    async attach() {
+        if (this.enabled || !this.cdp)
+            return;
+        await this.cdp.send("Network.enable");
+        this.enabled = true;
+        this.cdp.on("Network.requestWillBeSent", (e) => {
+            this.requests.set(e.requestId, {
+                method: e.request.method,
+                url: e.request.url,
+                type: e.type ?? "Other",
+                startedAt: Date.now(),
+            });
+        });
+        this.cdp.on("Network.responseReceived", (e) => {
+            const r = this.requests.get(e.requestId);
+            if (!r)
+                return;
+            const entry = {
+                method: r.method,
+                url: r.url,
+                status: e.response.status,
+                type: r.type,
+                ms: Date.now() - r.startedAt,
+                requestId: e.requestId,
+            };
+            if (e.response.mimeType)
+                entry.mimeType = e.response.mimeType;
+            this.push(entry);
+            // Index the just-pushed entry by requestId so a subsequent
+            // `Network.loadingFinished` can stamp the encoded byte size on it
+            // without a linear scan. Cleared on eviction (see `push`).
+            this.byReqId.set(e.requestId, entry);
+            this.requests.delete(e.requestId);
+        });
+        this.cdp.on("Network.loadingFinished", (e) => {
+            const entry = this.byReqId.get(e.requestId);
+            if (!entry)
+                return;
+            if (typeof e.encodedDataLength === "number" && e.encodedDataLength >= 0) {
+                entry.bytes = e.encodedDataLength;
+            }
+        });
+        this.cdp.on("Network.loadingFailed", (e) => {
+            const r = this.requests.get(e.requestId);
+            if (!r)
+                return;
+            this.push({
+                method: r.method,
+                url: r.url,
+                type: r.type,
+                failed: true,
+                ms: Date.now() - r.startedAt,
+                requestId: e.requestId,
+            });
+            this.requests.delete(e.requestId);
+        });
+    }
+    push(entry) {
+        this.ring.push(entry);
+        if (this.ring.length > this.cap) {
+            const evicted = this.ring.shift();
+            if (evicted?.requestId)
+                this.byReqId.delete(evicted.requestId);
+        }
+        // L7: the ring is bounded — one push evicts at most one entry, so the length
+        // is `<= cap` after every push. This is the bounded-buffer property the
+        // network surface depends on; asserting it post-eviction makes "the ring
+        // never exceeds its cap" a tested invariant rather than a comment.
+        invariant(this.ring.length <= this.cap, `NetworkBuffer ring exceeded cap (${this.ring.length} > ${this.cap})`);
+    }
+    /** Raw, read-only snapshot of the ring — every entry, no noise/beacon
+     *  folding, no egress masking. The masked / bucketed shape used by the
+     *  `network_read` tool stays unchanged (see `recent`). This view is for
+     *  consumers that need the full set as captured (e.g. `asset_export`
+     *  iterating to pick image/font/media responses out of the ring). */
+    iter() {
+        return this.ring;
+    }
+    /** Most-recent N entries; noise + beacons are folded into the `other` bucket of the summary. */
+    recent(limit = 50) {
+        // Routed through the shared `foldInteresting` rule (RFC 0004 P3 / D4) — the
+        // CDP `NetworkBuffer.recent()` now produces the byte-identical shape the
+        // Playwright buffer already did, instead of a fourth inlined copy of the fold.
+        return foldInteresting(this.ring.slice(-limit), this.secrets);
+    }
+}
+// ===========================================================================
+// Off-Chromium (Playwright-events) network/WebSocket capture lives in a sibling
+// module (`network-playwright.ts`) to keep this file under the size budget.
+//
+// RFC 0004 P4 / D10 — these classes are NOT re-exported through this barrel: a
+// runtime re-export here (and `network-playwright.ts` importing runtime helpers
+// back from here) formed a genuine import cycle that the no-circular rule flags
+// at `error`. The sole runtime consumer (`network-substrate.ts`) now imports
+// them DIRECTLY from `./network-playwright.js`, so the only surviving edge is
+// `network-playwright.ts` → `network.ts` — one-directional, no cycle.

package/dist/page/overflow-detect.d.ts

@@ -0,0 +1,102 @@
+export type OverflowType = "layout" | "clipped" | "text-ellipsis" | "viewport-horizontal";
+export type OverflowScope = "viewport" | "document";
+export interface OverflowDetectArgs {
+    /** Scope of the scan. `"document"` (default) walks every element; `"viewport"`
+     *  skips elements whose bounding rect is fully outside the current viewport. */
+    scope?: OverflowScope;
+    /** Overflow shapes to surface. Default = all four. Empty array also
+     *  treated as "all" (an empty filter is a usage error, not a no-op). */
+    types?: OverflowType[];
+    /** Cap on findings returned. Default 50, max 500. Findings past the cap
+     *  are dropped (oldest-discovered are kept) and `truncated:true` is set. */
+    limit?: number;
+}
+export interface OverflowBbox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type OverflowEvidence = {
+    scrollWidth: number;
+    clientWidth: number;
+    scrollHeight: number;
+    clientHeight: number;
+    overflowX: string;
+    overflowY: string;
+} | {
+    scrollWidth: number;
+    clientWidth: number;
+    visibleText: string;
+    fullText: string;
+} | {
+    documentScrollWidth: number;
+    viewportWidth: number;
+    overrunPx: number;
+    widestDescendantSelector?: string;
+    widestDescendantWidth?: number;
+} | {
+    selectorTruncated: true;
+    originalLength: number;
+};
+export interface OverflowFinding {
+    selector: string;
+    bbox: OverflowBbox | null;
+    type: OverflowType;
+    evidence: OverflowEvidence;
+}
+export interface OverflowDetectResult {
+    ok: true;
+    scope: OverflowScope;
+    findings: OverflowFinding[];
+    truncated: boolean;
+    warnings: string[];
+}
+export interface SelectorSynth {
+    selector: string;
+    truncated: boolean;
+    originalLength: number;
+}
+/** Pure helper for synthesising a selector against a `MinimalElement` shape.
+ *  Used by the unit tests; the page-side mirror in `PAGE_DETECT_FN` follows
+ *  the same tier order but operates on real `Element` instances. */
+export interface MinimalElement {
+    tagName: string;
+    testId: string | null;
+    role: string | null;
+    ariaLabel: string | null;
+    classList: string[];
+    /** Optional parent chain — first entry is the immediate parent. Used
+     *  by the nth-of-type tier (bounded at 5 levels). Each entry must
+     *  carry `nthOfType` (1-based) + `tagName`. */
+    parentChain?: Array<{
+        tagName: string;
+        nthOfType: number;
+    }>;
+    nthOfType?: number;
+}
+export declare function synthesiseSelector(el: MinimalElement): SelectorSynth;
+/** Pure helper: cap findings at `limit`, set `truncated` when exceeded.
+ *  Exported for unit tests. */
+export declare function applyLimit<T>(findings: T[], limit: number): {
+    kept: T[];
+    truncated: boolean;
+};
+/** Pure helper: which detector mask should be active. Empty array →
+ *  all four (an empty filter is treated as "default", not "exclude
+ *  everything" — the latter would be a usage error with no signal). */
+export declare function resolveTypes(requested: OverflowType[] | undefined): Set<OverflowType>;
+/** Pure helper for the EPSILON math — returns true when content actually
+ *  overruns its container past the sub-pixel-noise tolerance. Centralised
+ *  so the unit tests can pin the threshold + so changes flow through one
+ *  site instead of four detector branches. */
+export declare const OVERFLOW_EPSILON = 1;
+export declare function overflows(scrollDim: number, clientDim: number, epsilon?: number): boolean;
+/** Thin Page-shaped adapter so the unit tests can stub the page surface.
+ *  Mirrors the patterns in `dom_export` / `element_export`. `evaluate`
+ *  takes a real function (Playwright serializes it + invokes in-page) —
+ *  passing a stringified arrow returns the function uncalled. */
+export interface OverflowDetectPage {
+    evaluate<T, Arg>(fn: (arg: Arg) => T | Promise<T>, args?: Arg): Promise<T>;
+}
+export declare function detectOverflow(page: OverflowDetectPage, args?: OverflowDetectArgs): Promise<OverflowDetectResult>;