@digital-gravy/etch-connector 0.1.1

package/dist/cdp-client.js

@@ -0,0 +1,285 @@
+/**
+ * CDP backend — the out-of-band counterpart to {@link BridgeServer}.
+ *
+ * Where the bridge waits for a tab to dial *in* (and runs page-sandboxed,
+ * safe/unsafe scripts), this connects *out* to a Chrome started with
+ * `--remote-debugging-port=<n>` and drives the tab over the Chrome DevTools
+ * Protocol. That runs at DevTools privilege, so it unlocks what the in-page
+ * sandbox can't: full-`window` eval, `Page.captureScreenshot`, rendered
+ * `outerHTML`, and computed styles.
+ *
+ * Chrome already hosts the persistent endpoint, so this is a stateless client —
+ * no daemon. It speaks just enough CDP (Runtime + Page) to do the job; HTML and
+ * computed style ride on `Runtime.evaluate` rather than the DOM/CSS domains, to
+ * keep the surface small.
+ */
+import { WebSocket } from 'ws';
+/** A script evaluated over CDP threw. Distinct from operational failures. */
+export class CdpEvalError extends Error {
+    /** The full page-side exception text (description + stack), if any. */
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = 'CdpEvalError';
+        this.details = details;
+    }
+}
+/** Operational CDP failure (no Chrome, no/ambiguous target, timeout). */
+export class CdpError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CdpError';
+    }
+}
+const DEFAULT_PORT = 9222;
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class CdpClient {
+    host;
+    port;
+    ws = null;
+    nextId = 0;
+    pending = new Map();
+    target = null;
+    constructor(options = {}) {
+        this.host = options.host ?? DEFAULT_HOST;
+        this.port = options.port ?? DEFAULT_PORT;
+    }
+    /** List page targets from a Chrome remote-debugging endpoint. */
+    static async listTargets(options = {}) {
+        const host = options.host ?? DEFAULT_HOST;
+        const port = options.port ?? DEFAULT_PORT;
+        let list;
+        try {
+            const res = await fetch(`http://${host}:${port}/json/list`);
+            list = (await res.json());
+        }
+        catch (err) {
+            throw new CdpError(`cannot reach Chrome remote debugging at ${host}:${port} — start Chrome with --remote-debugging-port=${port} (${String(err)})`);
+        }
+        return list.filter((t) => t.type === 'page' && !t.url.startsWith('devtools://'));
+    }
+    /**
+     * Pick a target (by url/title substring, case-insensitive) and attach.
+     * With no match string, requires exactly one page target.
+     */
+    async connect(match) {
+        const pages = await CdpClient.listTargets({
+            host: this.host,
+            port: this.port
+        });
+        const chosen = this.pickTarget(pages, match);
+        await new Promise((resolve, reject) => {
+            const ws = new WebSocket(chosen.webSocketDebuggerUrl, {
+                perMessageDeflate: false
+            });
+            ws.on('open', () => resolve());
+            ws.on('error', (err) => reject(new CdpError(`failed to attach to target: ${String(err)}`)));
+            ws.on('message', (data) => this.onMessage(data.toString()));
+            ws.on('close', () => this.failAll(new CdpError('CDP connection closed')));
+            this.ws = ws;
+        });
+        this.target = chosen;
+        await this.send('Runtime.enable');
+        await this.send('Page.enable');
+        return chosen;
+    }
+    pickTarget(pages, match) {
+        if (match !== undefined) {
+            const m = match.toLowerCase();
+            const hits = pages.filter((t) => t.url.toLowerCase().includes(m) ||
+                (t.title ?? '').toLowerCase().includes(m));
+            if (hits.length === 0)
+                throw new CdpError(`no page target matches "${match}"`);
+            if (hits.length > 1) {
+                throw new CdpError(`"${match}" matches ${hits.length} targets: ${hits.map((t) => t.url).join(', ')}`);
+            }
+            return hits[0];
+        }
+        if (pages.length === 0)
+            throw new CdpError('no page targets open in Chrome');
+        if (pages.length > 1) {
+            throw new CdpError(`${pages.length} page targets open; pass -t <url-or-title substring>: ${pages
+                .map((t) => t.title || t.url)
+                .join(' | ')}`);
+        }
+        return pages[0];
+    }
+    async close() {
+        this.failAll(new CdpError('client closing'));
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* already gone */
+        }
+        this.ws = null;
+    }
+    /** Send a CDP command and await its result. */
+    send(method, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        if (!this.ws)
+            return Promise.reject(new CdpError('not connected'));
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new CdpError(`CDP "${method}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+                timer
+            });
+            this.ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    onMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (typeof msg.id !== 'number')
+            return; // an event, not a command reply
+        const pending = this.pending.get(msg.id);
+        if (!pending)
+            return;
+        this.pending.delete(msg.id);
+        clearTimeout(pending.timer);
+        if (msg.error)
+            pending.reject(new CdpError(`CDP error: ${msg.error.message ?? JSON.stringify(msg.error)}`));
+        else
+            pending.resolve(msg.result);
+    }
+    failAll(error) {
+        for (const [id, p] of this.pending) {
+            clearTimeout(p.timer);
+            this.pending.delete(id);
+            p.reject(error);
+        }
+    }
+    /** Evaluate a raw expression, returning its (JSON-safe) value. */
+    async evaluate(expression, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const result = await this.send('Runtime.evaluate', {
+            expression,
+            awaitPromise: true,
+            returnByValue: true,
+            userGesture: true
+        }, timeoutMs);
+        if (result.exceptionDetails) {
+            const ex = result.exceptionDetails.exception;
+            const message = ex?.description ??
+                ex?.value ??
+                result.exceptionDetails.text ??
+                'evaluation failed';
+            throw new CdpEvalError(String(message).split('\n')[0], String(message));
+        }
+        return result.result?.value;
+    }
+    /**
+     * Run `code` as an async function body with full page access (it may `return`
+     * a value and use top-level `await`). Returns the JSON-safe return value.
+     */
+    eval(code, options = {}) {
+        return this.evaluate(`(async () => { ${code} })()`, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    }
+    /** Rendered `outerHTML` of the first element matching `selector`. */
+    async outerHtml(selector) {
+        const v = await this.evaluate(`(() => { const el = document.querySelector(${JSON.stringify(selector)}); return el ? el.outerHTML : null; })()`);
+        if (v === null)
+            throw new CdpError(`no element matches "${selector}"`);
+        return v;
+    }
+    /** Computed style of `selector` as a plain object (all properties, or a subset). */
+    async computedStyle(selector, props) {
+        const keys = props ? JSON.stringify(props) : 'Array.from(cs)';
+        const expr = `(() => {
+			const el = document.querySelector(${JSON.stringify(selector)});
+			if (!el) return null;
+			const cs = getComputedStyle(el);
+			const out = {};
+			for (const k of ${keys}) out[k] = cs.getPropertyValue(k);
+			return out;
+		})()`;
+        const v = await this.evaluate(expr);
+        if (v === null)
+            throw new CdpError(`no element matches "${selector}"`);
+        return v;
+    }
+    /** Capture a PNG/JPEG of the viewport, a selector's box, or the full page. */
+    async screenshot(options = {}) {
+        const format = options.format ?? 'png';
+        // Freeze first, so the clip rect is measured on the same frame we capture.
+        if (options.freeze)
+            await this.freezeAnimations();
+        try {
+            let clip;
+            let captureBeyondViewport = false;
+            if (options.selector) {
+                const rect = (await this.evaluate(`(() => {
+					const el = document.querySelector(${JSON.stringify(options.selector)});
+					if (!el) return null;
+					const b = el.getBoundingClientRect();
+					return { x: b.left + scrollX, y: b.top + scrollY, width: b.width, height: b.height };
+				})()`));
+                if (!rect)
+                    throw new CdpError(`no element matches "${options.selector}"`);
+                clip = { ...rect, scale: 1 };
+                captureBeyondViewport = true;
+            }
+            else if (options.full) {
+                const metrics = await this.send('Page.getLayoutMetrics');
+                const size = metrics.cssContentSize ?? metrics.contentSize;
+                clip = {
+                    x: 0,
+                    y: 0,
+                    width: size.width,
+                    height: size.height,
+                    scale: 1
+                };
+                captureBeyondViewport = true;
+            }
+            const { data } = await this.send('Page.captureScreenshot', {
+                format,
+                ...(clip ? { clip } : {}),
+                captureBeyondViewport
+            });
+            return Buffer.from(data, 'base64');
+        }
+        finally {
+            if (options.freeze)
+                await this.restoreAnimations();
+        }
+    }
+    /** Pause every animation/transition and seek it to a deterministic frame. */
+    async freezeAnimations() {
+        await this.evaluate(`(() => {
+			let s = document.getElementById('__etch_freeze__');
+			if (!s) {
+				s = document.createElement('style');
+				s.id = '__etch_freeze__';
+				s.textContent = '*,*::before,*::after{transition:none!important}';
+				(document.head || document.documentElement).appendChild(s);
+			}
+			for (const a of document.getAnimations()) {
+				try {
+					a.pause();
+					const end = a.effect && a.effect.getComputedTiming ? a.effect.getComputedTiming().endTime : 0;
+					a.currentTime = (typeof end === 'number' && isFinite(end)) ? end : 0;
+				} catch (e) { /* leave this one as-is */ }
+			}
+			return true;
+		})()`);
+    }
+    /** Undo {@link freezeAnimations}: resume playback and remove the helper style. */
+    async restoreAnimations() {
+        await this.evaluate(`(() => {
+			const s = document.getElementById('__etch_freeze__');
+			if (s) s.remove();
+			for (const a of document.getAnimations()) { try { a.play(); } catch (e) {} }
+			return true;
+		})()`);
+    }
+}