clearcote 0.38.0 → 0.39.0

package/README.md

@@ -203,7 +203,9 @@ if (!verdict.coherent) console.warn(verdict.warnings);
 
 It reads the (unmasked) WebGL vendor/renderer the page sees, flags a software rasterizer (a fatal headless tell — enable the canvas bridge or run headed on a real GPU) and an incoherent vendor/renderer pair. Pass a second arg (`claimedGpu`) to also assert the rendered family.
 
-The renderer *string* alone is not enough: a persona renames the backend, so a SwiftShader fallback stops looking like one. The check therefore also measures limits the string cannot move — `MAX_TEXTURE_SIZE`, the vertex/fragment uniform-vector pair, and an actual 16384-wide texture allocation — and reports them as `maxTextureSize`, `maxVertexUniformVectors`, `maxFragmentUniformVectors` and `canAllocate16kTexture`. A renderer naming a desktop GPU while `MAX_TEXTURE_SIZE` is below 16384 is a spoof over a software rasterizer and comes back `coherent: false`. **Headless on Linux with no GPU hits exactly this** — Chromium falls back to SwiftShader (8192) whatever the persona claims, and no launch flag changes it on a display-less host. Run headed under Xvfb, or use the canvas bridge.
+The renderer *string* alone is not enough: a persona renames the backend, so a SwiftShader fallback stops looking like one. The check therefore also measures limits the string cannot move — `MAX_TEXTURE_SIZE`, the vertex/fragment uniform-vector pair, and an actual 16384-wide texture allocation — and reports them as `maxTextureSize`, `maxVertexUniformVectors`, `maxFragmentUniformVectors` and `canAllocate16kTexture`. A renderer naming a desktop GPU while `MAX_TEXTURE_SIZE` is below 16384 is a spoof over a software rasterizer and comes back `coherent: false`. **Headless on Linux with no GPU hits exactly this** when Chromium renders through SwiftShader (8192): a Windows persona always does, and a Linux persona does on a host without Mesa's EGL (`libegl1`). Run headed under Xvfb, or use the canvas bridge.
+
+On a Linux host the SDK picks the software backend that matches the GPU the persona names: a Linux persona (Mesa/OpenGL) renders through Mesa's own GL — over the X display when one is reachable (headed, or headless with `DISPLAY` pointing at an Xvfb), otherwise over EGL when the host has Mesa's EGL (`libegl1` on Debian/Ubuntu) — and a Windows persona (Direct3D11) renders through SwiftShader, whose limits match Direct3D11. Your own `--use-angle=` / `--use-gl=` in `args` wins.
 
 ### Hardened launch defaults
 

package/dist/cdpws.d.ts

@@ -0,0 +1,11 @@
+/** One browser-level CDP WebSocket. `send()` resolves with its own reply; events are dropped. */
+export interface CdpConnection {
+    send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<Record<string, unknown>>;
+    close(): void;
+}
+/**
+ * Open a CDP WebSocket (ws:// or wss://). Rejects when the endpoint refuses the upgrade or does not
+ * answer within `timeoutMs`; each `send()` gets the same budget for its reply.
+ */
+export declare function connectCdp(wsUrl: string, timeoutMs: number): Promise<CdpConnection>;
+//# sourceMappingURL=cdpws.d.ts.map

package/dist/cdpws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdpws.d.ts","sourceRoot":"","sources":["../src/cdpws.ts"],"names":[],"mappings":"AAeA,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7G,KAAK,IAAI,IAAI,CAAC;CACf;AA4BD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA+InF"}

package/dist/cdpws.js

@@ -0,0 +1,208 @@
+// A minimal CDP client over a WebSocket, on Node's standard library only. Port of the Python SDK's
+// `_cdpws.py`.
+//
+// serve() launches the engine itself, so there is no Playwright connection to borrow, and Node only
+// has a global WebSocket from 22 on while the SDK supports 20. The headless window fit used to ride
+// on that global, so on Node 20 it was silently skipped: the browser got its display but kept the
+// engine's default window, about 1000px wide inside a 1920px screen. What the fit needs is small: a
+// handful of request/response calls on the browser endpoint (flat sessions for the one page it
+// reads), text frames only, never a subscription. That is all this implements, deliberately not a
+// general client.
+import { createHash, randomBytes } from "node:crypto";
+import net from "node:net";
+import tls from "node:tls";
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+const OP_CONTINUATION = 0x0, OP_TEXT = 0x1, OP_BINARY = 0x2, OP_CLOSE = 0x8, OP_PING = 0x9, OP_PONG = 0xa;
+/** A client frame: FIN set, payload masked (RFC 6455 5.3 requires it of clients). */
+function frame(opcode, payload) {
+    const n = payload.length;
+    let head;
+    if (n < 126) {
+        head = Buffer.from([0x80 | opcode, 0x80 | n]);
+    }
+    else if (n < 65536) {
+        head = Buffer.alloc(4);
+        head[0] = 0x80 | opcode;
+        head[1] = 0x80 | 126;
+        head.writeUInt16BE(n, 2);
+    }
+    else {
+        head = Buffer.alloc(10);
+        head[0] = 0x80 | opcode;
+        head[1] = 0x80 | 127;
+        head.writeBigUInt64BE(BigInt(n), 2);
+    }
+    const mask = randomBytes(4);
+    const masked = Buffer.alloc(n);
+    for (let i = 0; i < n; i++)
+        masked[i] = payload[i] ^ mask[i & 3];
+    return Buffer.concat([head, mask, masked]);
+}
+/**
+ * Open a CDP WebSocket (ws:// or wss://). Rejects when the endpoint refuses the upgrade or does not
+ * answer within `timeoutMs`; each `send()` gets the same budget for its reply.
+ */
+export function connectCdp(wsUrl, timeoutMs) {
+    return new Promise((resolveOpen, rejectOpen) => {
+        let u;
+        try {
+            u = new URL(wsUrl);
+        }
+        catch {
+            return rejectOpen(new Error(`expected a ws:// CDP URL, got ${JSON.stringify(wsUrl)}`));
+        }
+        if ((u.protocol !== "ws:" && u.protocol !== "wss:") || !u.hostname) {
+            return rejectOpen(new Error(`expected a ws:// CDP URL, got ${JSON.stringify(wsUrl)}`));
+        }
+        const secure = u.protocol === "wss:";
+        const host = u.hostname.replace(/^\[(.*)\]$/, "$1"); // an IPv6 literal comes bracketed
+        const port = Number(u.port) || (secure ? 443 : 80);
+        const key = randomBytes(16).toString("base64");
+        const accept = createHash("sha1").update(key + WS_GUID).digest("base64");
+        let open = false;
+        let closed = false;
+        let buf = Buffer.alloc(0);
+        let parts = [];
+        let next = 0;
+        const pending = new Map();
+        const sock = secure
+            ? tls.connect({ host, port, servername: net.isIP(host) ? undefined : host })
+            : net.connect({ host, port });
+        const openTimer = setTimeout(() => fail(new Error("CDP connect timed out")), timeoutMs);
+        /** End the connection once: settle everything still waiting, then let the socket go. */
+        function fail(err, closeFrame) {
+            if (closed)
+                return;
+            closed = true;
+            clearTimeout(openTimer);
+            if (closeFrame) {
+                // Flush the close frame before letting go; an endpoint that never answers it is cut off.
+                sock.end(closeFrame);
+                setTimeout(() => sock.destroy(), 1000).unref();
+            }
+            else {
+                sock.destroy();
+            }
+            if (!open)
+                rejectOpen(err);
+            for (const p of pending.values())
+                p.reject(err);
+            pending.clear();
+        }
+        function onMessage(text) {
+            let m;
+            try {
+                m = JSON.parse(text);
+            }
+            catch {
+                return;
+            }
+            const p = m.id === undefined ? undefined : pending.get(m.id);
+            if (!p)
+                return; // an event, or a stale reply: this client subscribes to nothing
+            pending.delete(m.id);
+            if (m.error)
+                p.reject(new Error(m.error.message ?? JSON.stringify(m.error)));
+            else
+                p.resolve(m.result ?? {});
+        }
+        /** Consume every complete frame in `buf` (fragments joined; pings answered). */
+        function readFrames() {
+            while (!closed && buf.length >= 2) {
+                const fin = buf[0] & 0x80, opcode = buf[0] & 0x0f, masked = buf[1] & 0x80;
+                let n = buf[1] & 0x7f;
+                let off = 2;
+                if (n === 126) {
+                    if (buf.length < 4)
+                        return;
+                    n = buf.readUInt16BE(2);
+                    off = 4;
+                }
+                else if (n === 127) {
+                    if (buf.length < 10)
+                        return;
+                    n = Number(buf.readBigUInt64BE(2));
+                    off = 10;
+                }
+                const mask = masked ? off : -1;
+                if (masked)
+                    off += 4;
+                if (buf.length < off + n)
+                    return;
+                let payload = buf.subarray(off, off + n);
+                if (mask >= 0)
+                    payload = Buffer.from(payload.map((b, i) => b ^ buf[mask + (i & 3)]));
+                buf = buf.subarray(off + n);
+                if (opcode === OP_CLOSE)
+                    return fail(new Error("CDP connection closed"));
+                if (opcode === OP_PING) {
+                    sock.write(frame(OP_PONG, payload));
+                    continue;
+                }
+                if (opcode === OP_PONG)
+                    continue;
+                if (opcode === OP_TEXT || opcode === OP_BINARY || opcode === OP_CONTINUATION) {
+                    parts.push(payload);
+                    if (fin) {
+                        const text = Buffer.concat(parts).toString("utf8");
+                        parts = [];
+                        onMessage(text);
+                    }
+                }
+            }
+        }
+        /** The upgrade response: `101` and the accept hash RFC 6455 4.1 derives from our key. */
+        function readHandshake() {
+            const end = buf.indexOf("\r\n\r\n");
+            if (end < 0)
+                return;
+            const lines = buf.subarray(0, end).toString("latin1").split("\r\n");
+            buf = buf.subarray(end + 4);
+            if (!/^HTTP\/1\.[01] 101\b/.test(lines[0]))
+                return fail(new Error(`CDP WebSocket upgrade refused: ${lines[0]}`));
+            const line = lines.slice(1).find((l) => /^sec-websocket-accept:/i.test(l));
+            const got = line?.slice(line.indexOf(":") + 1).trim();
+            if (got !== accept)
+                return fail(new Error("CDP WebSocket upgrade answered with the wrong accept key"));
+            open = true;
+            clearTimeout(openTimer);
+            resolveOpen(connection);
+            readFrames();
+        }
+        const connection = {
+            send(method, params = {}, sessionId) {
+                return new Promise((resolve, reject) => {
+                    if (closed)
+                        return reject(new Error("CDP connection closed"));
+                    const id = ++next;
+                    const t = setTimeout(() => { pending.delete(id); reject(new Error(`${method} timed out`)); }, timeoutMs);
+                    pending.set(id, {
+                        resolve: (v) => { clearTimeout(t); resolve(v); },
+                        reject: (e) => { clearTimeout(t); reject(e); },
+                    });
+                    sock.write(frame(OP_TEXT, Buffer.from(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }))));
+                });
+            },
+            close() {
+                fail(new Error("CDP connection closed"), frame(OP_CLOSE, Buffer.from([0x03, 0xe8]))); // 1000: normal closure
+            },
+        };
+        sock.on(secure ? "secureConnect" : "connect", () => {
+            const path = (u.pathname || "/") + u.search;
+            sock.write(`GET ${path} HTTP/1.1\r\nHost: ${u.host}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n` +
+                `Sec-WebSocket-Key: ${key}\r\nSec-WebSocket-Version: 13\r\n\r\n`);
+        });
+        sock.on("data", (chunk) => {
+            if (closed)
+                return;
+            buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+            if (open)
+                readFrames();
+            else
+                readHandshake();
+        });
+        sock.on("error", (err) => fail(new Error(`CDP connection failed: ${err.message}`)));
+        sock.on("close", () => fail(new Error("CDP connection closed")));
+    });
+}
+//# sourceMappingURL=cdpws.js.map

package/dist/cdpws.js.map

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

package/dist/geometry.d.ts

@@ -86,13 +86,19 @@ export declare function applyHeadlessGeometry(opts: Record<string, unknown>, see
 /**
  * The bounds correction, given what the window reported after the first attempt.
  *
- * Requested bounds and reported outerHeight are not the same quantity: on 149 the window reports
- * 33px less than the bounds height it was given, so fitting bounds to the work area lands 33px short
- * of maximized (real maximized captures have outer == avail). Rather than hardcode 33, measure the
- * shortfall and add it back — that self-tunes if the engine changes. Never asks for more than the
- * shortfall, so the window cannot be pushed past the work area.
+ * Requested bounds and reported outerHeight are not always the same quantity: on 149 the window
+ * reported 33px less than the bounds height it was given, and on 150 a persona's window does (33px in
+ * a launch, 89 in serve(); without a persona it reports the bounds exactly). Fitting bounds to the
+ * work area then lands short of maximized (real maximized captures have outer == avail). Rather than
+ * hardcode it, measure the shortfall and add it back — that self-tunes if the engine changes. Never
+ * asks for more than the shortfall.
+ *
+ * `room` is the space from the window's position to the work area's far edges. On an axis where the
+ * window is smaller than that, the correction never takes the bounds past the edge: only a window that
+ * fills the work area needs bounds beyond it (the persona engine then clamps the window to the work
+ * area), and an engine without a persona does not clamp at all.
  */
-export declare function fitPlan(avail: number[], outer: number[]): [number, number] | null;
+export declare function fitPlan(avail: number[], outer: number[], room?: readonly number[] | null): [number, number] | null;
 /**
  * Size the headless window to the display's work area — the persona's (regime 1) or the one
  * `--screen-info` set (regime 2) — so the page reports a maximized window (outer == avail) instead
@@ -174,17 +180,19 @@ export interface ServedFit {
 /**
  * Put the served browser's first window on its display's work area (or `windowSize`, clamped into
  * it); under a persona, first make the headless display the persona's own. Over the caller's CDP
- * connection, on the first page target. Only Target/Emulation/Browser commands plus one
- * Runtime.evaluate (never Runtime.enable) on that page, and every change is browser-level, so
+ * connection, on the first page target. Only Target/Emulation/Browser commands plus
+ * Runtime.evaluate reads (never Runtime.enable) on that page, and every change is browser-level, so
  * nothing lingers on the page when the connection closes.
  *
  * Returns null when it could not act (no page, an implausible persona display, or an engine without
  * `Emulation.updateScreen` under a persona, whose window cannot outgrow 800x600 without it). Never
- * throws: geometry must not be able to fail a launch.
+ * throws: geometry must not be able to fail a launch. `settleMs` bounds the wait for each resize to
+ * reach the page ({@link settledOuter}).
  */
 export declare function fitWindowOverCdp(cdp: CdpSend, opts: {
     persona: boolean;
     windowSize?: Size | null;
+    settleMs?: number;
 }): Promise<ServedFit | null>;
 /** {@link fitWindowOverCdp} on the SDK's own short connection to a served browser. Never throws. */
 export declare function fitServedWindow(wsUrl: string | undefined, opts: {

package/dist/geometry.d.ts.map

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

package/dist/geometry.js

@@ -52,6 +52,7 @@
  */
 import { createHash } from "node:crypto";
 import { gunzipSync } from "node:zlib";
+import { connectCdp } from "./cdpws.js";
 import { lightStealthScreen } from "./fingerprint.js";
 /**
  * The linux-x64 engine's window frame around an EMULATED viewport: outer = inner + (WIDTH, HEIGHT).
@@ -209,18 +210,75 @@ function bounds(width, height) {
 /**
  * The bounds correction, given what the window reported after the first attempt.
  *
- * Requested bounds and reported outerHeight are not the same quantity: on 149 the window reports
- * 33px less than the bounds height it was given, so fitting bounds to the work area lands 33px short
- * of maximized (real maximized captures have outer == avail). Rather than hardcode 33, measure the
- * shortfall and add it back — that self-tunes if the engine changes. Never asks for more than the
- * shortfall, so the window cannot be pushed past the work area.
+ * Requested bounds and reported outerHeight are not always the same quantity: on 149 the window
+ * reported 33px less than the bounds height it was given, and on 150 a persona's window does (33px in
+ * a launch, 89 in serve(); without a persona it reports the bounds exactly). Fitting bounds to the
+ * work area then lands short of maximized (real maximized captures have outer == avail). Rather than
+ * hardcode it, measure the shortfall and add it back — that self-tunes if the engine changes. Never
+ * asks for more than the shortfall.
+ *
+ * `room` is the space from the window's position to the work area's far edges. On an axis where the
+ * window is smaller than that, the correction never takes the bounds past the edge: only a window that
+ * fills the work area needs bounds beyond it (the persona engine then clamps the window to the work
+ * area), and an engine without a persona does not clamp at all.
  */
-export function fitPlan(avail, outer) {
+export function fitPlan(avail, outer, room) {
     const dw = avail[0] - outer[0];
     const dh = avail[1] - outer[1];
     if (dw <= 0 && dh <= 0)
         return null;
-    return [avail[0] + Math.max(dw, 0), avail[1] + Math.max(dh, 0)];
+    const capped = (want, i) => (room && avail[i] < room[i] ? Math.min(want, room[i]) : want);
+    return [capped(avail[0] + Math.max(dw, 0), 0), capped(avail[1] + Math.max(dh, 0), 1)];
+}
+/** How long a window resize may take to reach the page before a read is taken as it stands. */
+const SETTLE_MS = 1000;
+const SETTLE_POLL_MS = 20;
+const sameSize = (a, b) => a[0] === b[0] && a[1] === b[1];
+/**
+ * Read `[outerWidth, outerHeight]` until it reflects the last `Browser.setWindowBounds`. The call
+ * returns before the page has the new window size, so a read straight after it can still report the
+ * previous one (measured on 150/linux-x64: for tens of milliseconds). Correcting from such a
+ * read once asked for 1440+495 px on a 1920 px screen. Settled means the asked-for size, or a size
+ * other than `before` that is still there one poll later; `settled` is false when neither happened
+ * within `timeoutMs`.
+ */
+async function settledOuter(read, before, want, timeoutMs = SETTLE_MS) {
+    const deadline = Date.now() + timeoutMs;
+    let outer = await read();
+    for (;;) {
+        if (sameSize(outer, want))
+            return { outer, settled: true };
+        if (Date.now() >= deadline)
+            return { outer, settled: false };
+        await new Promise((r) => setTimeout(r, SETTLE_POLL_MS));
+        const next = await read();
+        if (!sameSize(outer, before) && sameSize(next, outer))
+            return { outer, settled: true };
+        outer = next;
+    }
+}
+/**
+ * Give the window `target`, then correct what the engine reports (see {@link fitPlan}), on settled
+ * reads only: a correction is planned from a size the page has actually seen, and kept only when the
+ * page then sees a window no larger than `target`; otherwise the bounds go back to `target`. With no
+ * settled read there is nothing to correct from, and `target` lies inside the work area. Returns the
+ * last outer size read.
+ */
+async function fitWindow(setBounds, read, target, room, settleMs) {
+    const [w, h] = target;
+    const before = await read();
+    await setBounds(w, h);
+    const first = await settledOuter(read, before, target, settleMs);
+    const plan = first.settled ? fitPlan(target, first.outer, room) : null;
+    if (!plan)
+        return first.outer;
+    await setBounds(plan[0], plan[1]);
+    const fixed = await settledOuter(read, first.outer, plan, settleMs);
+    // Overshooting would trade one impossible geometry for another (outer > target).
+    if (fixed.settled && fixed.outer[0] <= w && fixed.outer[1] <= h)
+        return fixed.outer;
+    await setBounds(w, h);
+    return (await settledOuter(read, fixed.outer, target, settleMs)).outer;
 }
 /**
  * Size the headless window to the display's work area — the persona's (regime 1) or the one
@@ -241,18 +299,7 @@ export async function fitWindowToWorkArea(page, args) {
             return null;
         const cdp = await page.context().newCDPSession(page);
         const { windowId } = (await cdp.send("Browser.getWindowForTarget"));
-        await cdp.send("Browser.setWindowBounds", { windowId, bounds: bounds(avail[0], avail[1]) });
-        let outer = (await page.evaluate(OUTER_JS));
-        const plan = fitPlan(avail, outer);
-        if (plan) {
-            await cdp.send("Browser.setWindowBounds", { windowId, bounds: bounds(plan[0], plan[1]) });
-            outer = (await page.evaluate(OUTER_JS));
-            // Overshooting would trade one impossible geometry for another (outer > avail).
-            if (outer[0] > avail[0] || outer[1] > avail[1]) {
-                await cdp.send("Browser.setWindowBounds", { windowId, bounds: bounds(avail[0], avail[1]) });
-                outer = (await page.evaluate(OUTER_JS));
-            }
-        }
+        const outer = await fitWindow((w, h) => cdp.send("Browser.setWindowBounds", { windowId, bounds: bounds(w, h) }), async () => (await page.evaluate(OUTER_JS)), [avail[0], avail[1]], [avail[0], avail[1]], SETTLE_MS);
         return [outer[0], outer[1]];
     }
     catch {
@@ -294,8 +341,7 @@ export function geometryIsCoherent(screen, avail, inner, outer) {
 // fit runs on each context's first page. A raw endpoint has neither, and a CDP emulation override
 // would not survive either, being scoped to the session that set it. What every
 // target and every client of a served browser inherits is the headless DISPLAY and the real WINDOW,
-// both browser-level. Untouched, measured on 153.0.8010.36/win-x64 (cc-gateway
-// tools/probe-geometry.mjs):
+// both browser-level. Untouched, measured on 153.0.8010.36/win-x64:
 //
 //     no persona:           screen 800x600    avail 800x600    outer 780x580   <- the headless surface
 //     no persona + --window-size=1440,900:    outer 1440x900 on that 800x600 screen
@@ -379,13 +425,14 @@ const DISPLAY_JS = "[screen.width, screen.height, screen.availLeft, screen.avail
 /**
  * Put the served browser's first window on its display's work area (or `windowSize`, clamped into
  * it); under a persona, first make the headless display the persona's own. Over the caller's CDP
- * connection, on the first page target. Only Target/Emulation/Browser commands plus one
- * Runtime.evaluate (never Runtime.enable) on that page, and every change is browser-level, so
+ * connection, on the first page target. Only Target/Emulation/Browser commands plus
+ * Runtime.evaluate reads (never Runtime.enable) on that page, and every change is browser-level, so
  * nothing lingers on the page when the connection closes.
  *
  * Returns null when it could not act (no page, an implausible persona display, or an engine without
  * `Emulation.updateScreen` under a persona, whose window cannot outgrow 800x600 without it). Never
- * throws: geometry must not be able to fail a launch.
+ * throws: geometry must not be able to fail a launch. `settleMs` bounds the wait for each resize to
+ * reach the page ({@link settledOuter}).
  */
 export async function fitWindowOverCdp(cdp, opts) {
     let sessionId;
@@ -417,19 +464,9 @@ export async function fitWindowOverCdp(cdp, opts) {
         const top = at + Math.min(10, ah - h);
         const { windowId } = (await cdp.send("Browser.getWindowForTarget", { targetId: page.targetId }));
         const setBounds = (bw, bh) => cdp.send("Browser.setWindowBounds", { windowId, bounds: { left, top, width: Math.round(bw), height: Math.round(bh) } });
-        await setBounds(w, h);
-        let outer = await read(OUTER_JS);
-        // Same self-tuning as fitWindowToWorkArea: an engine that reports less than the bounds it was
-        // given gets the shortfall added back, and an overshoot is reverted.
-        const plan = fitPlan([w, h], outer);
-        if (plan) {
-            await setBounds(plan[0], plan[1]);
-            outer = await read(OUTER_JS);
-            if (outer[0] > w || outer[1] > h) {
-                await setBounds(w, h);
-                outer = await read(OUTER_JS);
-            }
-        }
+        // Same as fitWindowToWorkArea: an engine that reports less than the bounds it was given gets the
+        // shortfall added back, an overshoot is reverted, and only settled reads count.
+        const outer = await fitWindow(setBounds, () => read(OUTER_JS), [w, h], [al + aw - left, at + ah - top], opts.settleMs ?? SETTLE_MS);
         return { display: { width: sw, height: sh, availWidth: aw, availHeight: ah }, outer: [outer[0], outer[1]] };
     }
     catch {
@@ -440,69 +477,15 @@ export async function fitWindowOverCdp(cdp, opts) {
             await cdp.send("Target.detachFromTarget", { sessionId }).catch(() => { });
     }
 }
-/** A minimal CDP client on Node's built-in WebSocket (Node 22+), or null where there is none. */
-async function openCdp(wsUrl, timeoutMs) {
-    const WS = globalThis.WebSocket;
-    if (!WS)
-        return null;
-    const ws = new WS(wsUrl);
-    await new Promise((resolve, reject) => {
-        const t = setTimeout(() => reject(new Error("CDP connect timed out")), timeoutMs);
-        ws.onopen = () => { clearTimeout(t); resolve(); };
-        ws.onerror = () => { clearTimeout(t); reject(new Error("CDP connect failed")); };
-    });
-    let next = 0;
-    const pending = new Map();
-    ws.onmessage = (ev) => {
-        let m;
-        try {
-            m = JSON.parse(String(ev.data));
-        }
-        catch {
-            return;
-        }
-        const p = m.id === undefined ? undefined : pending.get(m.id);
-        if (!p)
-            return;
-        pending.delete(m.id);
-        if (m.error)
-            p.reject(new Error(m.error.message));
-        else
-            p.resolve(m.result ?? {});
-    };
-    ws.onclose = () => {
-        for (const p of pending.values())
-            p.reject(new Error("CDP connection closed"));
-        pending.clear();
-    };
-    return {
-        send(method, params = {}, sessionId) {
-            return new Promise((resolve, reject) => {
-                const id = ++next;
-                const t = setTimeout(() => { pending.delete(id); reject(new Error(`${method} timed out`)); }, timeoutMs);
-                pending.set(id, {
-                    resolve: (v) => { clearTimeout(t); resolve(v); },
-                    reject: (e) => { clearTimeout(t); reject(e); },
-                });
-                ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
-            });
-        },
-        close() {
-            try {
-                ws.close();
-            }
-            catch { /* ignore */ }
-        },
-    };
-}
 /** {@link fitWindowOverCdp} on the SDK's own short connection to a served browser. Never throws. */
 export async function fitServedWindow(wsUrl, opts) {
     if (!wsUrl)
         return null;
     let cdp = null;
     try {
-        cdp = await openCdp(wsUrl, opts.timeoutMs ?? 5000);
-        return cdp ? await fitWindowOverCdp(cdp, opts) : null;
+        // The SDK's own WebSocket client, not Node's global one: that only exists from Node 22 on.
+        cdp = await connectCdp(wsUrl, opts.timeoutMs ?? 5000);
+        return await fitWindowOverCdp(cdp, opts);
     }
     catch {
         return null;