@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/cdp.js

@@ -0,0 +1,536 @@
+/**
+ * CDP client — implements IPage by connecting directly to a Chrome/Electron CDP WebSocket.
+ *
+ * Fixes applied:
+ * - send() now has a 30s timeout guard (P0 #4)
+ * - goto() waits for Page.loadEventFired instead of hardcoded 1s sleep (P1 #3)
+ * - Implemented scroll, autoScroll, screenshot, networkRequests (P1 #2)
+ * - Shared DOM helper methods extracted to reduce duplication with Page (P1 #5)
+ */
+import { WebSocket } from 'ws';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { buildEvaluateExpression } from './utils.js';
+import { generateStealthJs } from './stealth.js';
+import { waitForDomStableJs } from './dom-helpers.js';
+import { isRecord, saveBase64ToFile } from '../utils.js';
+import { getAllElectronApps } from '../electron-apps.js';
+import { BasePage } from './base-page.js';
+const CDP_SEND_TIMEOUT = 30_000;
+// Memory guard for in-process capture. The 4k cap we used to apply everywhere
+// silently truncated JSON so `JSON.parse` failed or gave partial objects — the
+// primary agent-facing bug. Now we keep the full body up to a large cap and
+// surface `responseBodyFullSize` + `responseBodyTruncated` so downstream layers
+// can tell the agent what happened instead of lying about the payload.
+export const CDP_RESPONSE_BODY_CAPTURE_LIMIT = 8 * 1024 * 1024;
+export class CDPBridge {
+    _ws = null;
+    _idCounter = 0;
+    _pending = new Map();
+    _eventListeners = new Map();
+    async connect(opts) {
+        if (this._ws)
+            throw new Error('CDPBridge is already connected. Call close() before reconnecting.');
+        const endpoint = opts?.cdpEndpoint ?? process.env.WEBCMD_CDP_ENDPOINT;
+        if (!endpoint)
+            throw new Error('CDP endpoint not provided (pass cdpEndpoint or set WEBCMD_CDP_ENDPOINT)');
+        let wsUrl = endpoint;
+        if (endpoint.startsWith('http')) {
+            const targets = await fetchJsonDirect(`${endpoint.replace(/\/$/, '')}/json`);
+            const target = selectCDPTarget(targets);
+            if (!target || !target.webSocketDebuggerUrl) {
+                throw new Error('No inspectable targets found at CDP endpoint');
+            }
+            wsUrl = target.webSocketDebuggerUrl;
+        }
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(wsUrl);
+            const timeoutMs = (opts?.timeout ?? 10) * 1000;
+            const timeout = setTimeout(() => {
+                this._ws = null;
+                ws.close();
+                reject(new Error('CDP connect timeout'));
+            }, timeoutMs);
+            ws.on('open', async () => {
+                clearTimeout(timeout);
+                this._ws = ws;
+                try {
+                    await this.send('Page.enable');
+                    await this.send('Page.addScriptToEvaluateOnNewDocument', { source: generateStealthJs() });
+                }
+                catch (err) {
+                    ws.close();
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                resolve(new CDPPage(this));
+            });
+            ws.on('error', (err) => {
+                clearTimeout(timeout);
+                reject(err);
+            });
+            ws.on('message', (data) => {
+                try {
+                    const msg = JSON.parse(data.toString());
+                    if (msg.id && this._pending.has(msg.id)) {
+                        const entry = this._pending.get(msg.id);
+                        clearTimeout(entry.timer);
+                        this._pending.delete(msg.id);
+                        if (msg.error) {
+                            entry.reject(new Error(msg.error.message));
+                        }
+                        else {
+                            entry.resolve(msg.result);
+                        }
+                    }
+                    if (msg.method) {
+                        const listeners = this._eventListeners.get(msg.method);
+                        if (listeners) {
+                            for (const fn of listeners)
+                                fn(msg.params);
+                        }
+                    }
+                }
+                catch (err) {
+                    if (process.env.WEBCMD_VERBOSE) {
+                        // eslint-disable-next-line no-console
+                        console.error('[cdp] Failed to parse WebSocket message:', err instanceof Error ? err.message : err);
+                    }
+                }
+            });
+        });
+    }
+    async close() {
+        if (this._ws) {
+            this._ws.close();
+            this._ws = null;
+        }
+        for (const p of this._pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new Error('CDP connection closed'));
+        }
+        this._pending.clear();
+        this._eventListeners.clear();
+    }
+    async send(method, params = {}, timeoutMs = CDP_SEND_TIMEOUT) {
+        if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+            throw new Error('CDP connection is not open');
+        }
+        const id = ++this._idCounter;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this._pending.delete(id);
+                reject(new Error(`CDP command '${method}' timed out after ${timeoutMs / 1000}s`));
+            }, timeoutMs);
+            this._pending.set(id, { resolve, reject, timer });
+            this._ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    on(event, handler) {
+        let set = this._eventListeners.get(event);
+        if (!set) {
+            set = new Set();
+            this._eventListeners.set(event, set);
+        }
+        set.add(handler);
+    }
+    off(event, handler) {
+        this._eventListeners.get(event)?.delete(handler);
+    }
+    waitForEvent(event, timeoutMs = 15_000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.off(event, handler);
+                reject(new Error(`Timed out waiting for CDP event '${event}'`));
+            }, timeoutMs);
+            const handler = (params) => {
+                clearTimeout(timer);
+                this.off(event, handler);
+                resolve(params);
+            };
+            this.on(event, handler);
+        });
+    }
+}
+class CDPPage extends BasePage {
+    bridge;
+    _pageEnabled = false;
+    // Network capture state (mirrors extension/src/cdp.ts NetworkCaptureEntry shape)
+    _networkCapturing = false;
+    _networkCapturePattern = '';
+    _networkEntries = [];
+    _pendingRequests = new Map(); // requestId → index in _networkEntries
+    _pendingBodyFetches = new Set(); // track in-flight getResponseBody calls
+    _consoleMessages = [];
+    _consoleCapturing = false;
+    constructor(bridge) {
+        super();
+        this.bridge = bridge;
+    }
+    async goto(url, options) {
+        if (!this._pageEnabled) {
+            await this.bridge.send('Page.enable');
+            this._pageEnabled = true;
+        }
+        const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
+        await this.bridge.send('Page.navigate', { url });
+        await loadPromise;
+        this._lastUrl = url;
+        if (options?.waitUntil !== 'none') {
+            const maxMs = options?.settleMs ?? 1000;
+            await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+        }
+    }
+    async evaluate(input, ...args) {
+        const expression = buildEvaluateExpression(input, args);
+        const result = await this.bridge.send('Runtime.evaluate', {
+            expression,
+            returnByValue: true,
+            awaitPromise: true,
+        });
+        if (result.exceptionDetails) {
+            throw new Error('Evaluate error: ' + (result.exceptionDetails.exception?.description || 'Unknown exception'));
+        }
+        return result.result?.value;
+    }
+    async getCookies(opts = {}) {
+        const result = await this.bridge.send('Network.getCookies', opts.url ? { urls: [opts.url] } : {});
+        const cookies = isRecord(result) && Array.isArray(result.cookies) ? result.cookies : [];
+        const domain = opts.domain;
+        return domain
+            ? cookies.filter((cookie) => isCookie(cookie) && matchesCookieDomain(cookie.domain, domain))
+            : cookies;
+    }
+    async screenshot(options = {}) {
+        const fullPage = options.fullPage === true;
+        const overrideWidth = options.width && options.width > 0 ? Math.ceil(options.width) : undefined;
+        // height is ignored under fullPage so the captureBeyondViewport path stays unchanged for users who pass --height alongside --full-page.
+        const overrideHeight = !fullPage && options.height && options.height > 0 ? Math.ceil(options.height) : undefined;
+        const needsOverride = overrideWidth !== undefined || overrideHeight !== undefined;
+        if (needsOverride) {
+            if (overrideWidth !== undefined && fullPage) {
+                await this.bridge.send('Emulation.setDeviceMetricsOverride', {
+                    mobile: false,
+                    width: overrideWidth,
+                    height: 0,
+                    deviceScaleFactor: 1,
+                });
+            }
+            let finalWidth = overrideWidth ?? 0;
+            let finalHeight = overrideHeight ?? 0;
+            if (fullPage) {
+                const metrics = await this.bridge.send('Page.getLayoutMetrics');
+                const m = isRecord(metrics) ? metrics : {};
+                const css = isRecord(m.cssContentSize) ? m.cssContentSize : undefined;
+                const fb = isRecord(m.contentSize) ? m.contentSize : undefined;
+                const size = css ?? fb;
+                if (size && typeof size.width === 'number' && typeof size.height === 'number') {
+                    if (finalWidth === 0)
+                        finalWidth = Math.ceil(size.width);
+                    finalHeight = Math.ceil(size.height);
+                }
+            }
+            await this.bridge.send('Emulation.setDeviceMetricsOverride', {
+                mobile: false,
+                width: finalWidth,
+                height: finalHeight,
+                deviceScaleFactor: 1,
+            });
+        }
+        try {
+            const result = await this.bridge.send('Page.captureScreenshot', {
+                format: options.format ?? 'png',
+                quality: options.format === 'jpeg' ? (options.quality ?? 80) : undefined,
+                captureBeyondViewport: !needsOverride && fullPage,
+            });
+            const base64 = isRecord(result) && typeof result.data === 'string' ? result.data : '';
+            if (options.path) {
+                await saveBase64ToFile(base64, options.path);
+            }
+            return base64;
+        }
+        finally {
+            if (needsOverride) {
+                await this.bridge.send('Emulation.clearDeviceMetricsOverride').catch(() => { });
+            }
+        }
+    }
+    async startNetworkCapture(pattern = '') {
+        // Always update the filter pattern
+        this._networkCapturePattern = pattern;
+        // Reset state only on first start; avoid wiping entries if already capturing
+        if (!this._networkCapturing) {
+            this._networkEntries = [];
+            this._pendingRequests.clear();
+            this._pendingBodyFetches.clear();
+            await this.bridge.send('Network.enable');
+            // Step 1: Record request method/url on requestWillBeSent
+            this.bridge.on('Network.requestWillBeSent', (params) => {
+                const p = params;
+                if (!this._networkCapturePattern || p.request.url.includes(this._networkCapturePattern)) {
+                    const idx = this._networkEntries.push({
+                        url: p.request.url,
+                        method: p.request.method,
+                        timestamp: Date.now(),
+                    }) - 1;
+                    this._pendingRequests.set(p.requestId, idx);
+                }
+            });
+            // Step 2: Fill in response metadata on responseReceived
+            this.bridge.on('Network.responseReceived', (params) => {
+                const p = params;
+                const idx = this._pendingRequests.get(p.requestId);
+                if (idx !== undefined) {
+                    this._networkEntries[idx].responseStatus = p.response.status;
+                    this._networkEntries[idx].responseContentType = p.response.mimeType || '';
+                }
+            });
+            // Step 3: Fetch body on loadingFinished (body is only reliably available after this)
+            this.bridge.on('Network.loadingFinished', (params) => {
+                const p = params;
+                const idx = this._pendingRequests.get(p.requestId);
+                if (idx !== undefined) {
+                    const bodyFetch = this.bridge.send('Network.getResponseBody', { requestId: p.requestId }).then((result) => {
+                        const r = result;
+                        if (typeof r?.body === 'string') {
+                            const fullSize = r.body.length;
+                            const truncated = fullSize > CDP_RESPONSE_BODY_CAPTURE_LIMIT;
+                            const body = truncated ? r.body.slice(0, CDP_RESPONSE_BODY_CAPTURE_LIMIT) : r.body;
+                            this._networkEntries[idx].responsePreview = r.base64Encoded ? `base64:${body}` : body;
+                            this._networkEntries[idx].responseBodyFullSize = fullSize;
+                            this._networkEntries[idx].responseBodyTruncated = truncated;
+                        }
+                    }).catch((err) => {
+                        // Body unavailable for some requests (e.g. uploads) — non-fatal
+                        if (process.env.WEBCMD_VERBOSE) {
+                            // eslint-disable-next-line no-console
+                            console.error(`[cdp] getResponseBody failed for ${p.requestId}:`, err instanceof Error ? err.message : err);
+                        }
+                    }).finally(() => {
+                        this._pendingBodyFetches.delete(bodyFetch);
+                    });
+                    this._pendingBodyFetches.add(bodyFetch);
+                    this._pendingRequests.delete(p.requestId);
+                }
+            });
+            this._networkCapturing = true;
+        }
+        return true;
+    }
+    async readNetworkCapture() {
+        // Await all in-flight body fetches so entries have responsePreview populated
+        if (this._pendingBodyFetches.size > 0) {
+            await Promise.all([...this._pendingBodyFetches]);
+        }
+        const entries = [...this._networkEntries];
+        this._networkEntries = [];
+        return entries;
+    }
+    async consoleMessages(level = 'all') {
+        if (!this._consoleCapturing) {
+            await this.bridge.send('Runtime.enable');
+            this.bridge.on('Runtime.consoleAPICalled', (params) => {
+                const p = params;
+                const text = (p.args || []).map(a => a.value !== undefined ? String(a.value) : (a.description || '')).join(' ');
+                this._consoleMessages.push({ type: p.type, text, timestamp: Date.now() });
+                if (this._consoleMessages.length > 500)
+                    this._consoleMessages.shift();
+            });
+            // Capture uncaught exceptions as error-level messages
+            this.bridge.on('Runtime.exceptionThrown', (params) => {
+                const p = params;
+                const desc = p.exceptionDetails?.exception?.description || p.exceptionDetails?.text || 'Unknown exception';
+                this._consoleMessages.push({ type: 'error', text: desc, timestamp: Date.now() });
+                if (this._consoleMessages.length > 500)
+                    this._consoleMessages.shift();
+            });
+            this._consoleCapturing = true;
+        }
+        if (level === 'all')
+            return [...this._consoleMessages];
+        // 'error' level includes both console.error() and uncaught exceptions
+        if (level === 'error')
+            return this._consoleMessages.filter(m => m.type === 'error' || m.type === 'warning');
+        return this._consoleMessages.filter(m => m.type === level);
+    }
+    async tabs() {
+        return [];
+    }
+    async selectTab(_target) {
+        // Not supported in direct CDP mode
+    }
+    async cdp(method, params = {}) {
+        return this.bridge.send(method, params);
+    }
+    async handleJavaScriptDialog(accept, promptText) {
+        await this.cdp('Page.handleJavaScriptDialog', {
+            accept,
+            ...(promptText !== undefined && { promptText }),
+        });
+    }
+    async nativeClick(x, y) {
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseMoved',
+            x,
+            y,
+        });
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mousePressed',
+            x,
+            y,
+            button: 'left',
+            clickCount: 1,
+        });
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseReleased',
+            x,
+            y,
+            button: 'left',
+            clickCount: 1,
+        });
+    }
+    async nativeType(text) {
+        await this.cdp('Input.insertText', { text });
+    }
+    async insertText(text) {
+        await this.nativeType(text);
+    }
+    async nativeKeyPress(key, modifiers = []) {
+        let modifierFlags = 0;
+        for (const mod of modifiers) {
+            if (mod === 'Alt')
+                modifierFlags |= 1;
+            if (mod === 'Ctrl' || mod === 'Control')
+                modifierFlags |= 2;
+            if (mod === 'Meta')
+                modifierFlags |= 4;
+            if (mod === 'Shift')
+                modifierFlags |= 8;
+        }
+        await this.cdp('Input.dispatchKeyEvent', {
+            type: 'keyDown',
+            key,
+            modifiers: modifierFlags,
+        });
+        await this.cdp('Input.dispatchKeyEvent', {
+            type: 'keyUp',
+            key,
+            modifiers: modifierFlags,
+        });
+    }
+}
+function isCookie(value) {
+    return isRecord(value)
+        && typeof value.name === 'string'
+        && typeof value.value === 'string'
+        && typeof value.domain === 'string';
+}
+function matchesCookieDomain(cookieDomain, targetDomain) {
+    const normalizedCookieDomain = cookieDomain.replace(/^\./, '').toLowerCase();
+    const normalizedTargetDomain = targetDomain.replace(/^\./, '').toLowerCase();
+    return normalizedTargetDomain === normalizedCookieDomain
+        || normalizedTargetDomain.endsWith(`.${normalizedCookieDomain}`);
+}
+function selectCDPTarget(targets) {
+    const preferredPattern = compilePreferredPattern(process.env.WEBCMD_CDP_TARGET);
+    const ranked = targets
+        .map((target, index) => ({ target, index, score: scoreCDPTarget(target, preferredPattern) }))
+        .filter(({ score }) => Number.isFinite(score))
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.index - b.index;
+    });
+    return ranked[0]?.target;
+}
+function scoreCDPTarget(target, preferredPattern) {
+    if (!target.webSocketDebuggerUrl)
+        return Number.NEGATIVE_INFINITY;
+    const type = (target.type ?? '').toLowerCase();
+    const url = (target.url ?? '').toLowerCase();
+    const title = (target.title ?? '').toLowerCase();
+    const haystack = `${title} ${url}`;
+    if (!haystack.trim() && !type)
+        return Number.NEGATIVE_INFINITY;
+    if (haystack.includes('devtools'))
+        return Number.NEGATIVE_INFINITY;
+    if (type === 'background_page' || type === 'service_worker')
+        return Number.NEGATIVE_INFINITY;
+    let score = 0;
+    if (preferredPattern && preferredPattern.test(haystack))
+        score += 1000;
+    if (type === 'app')
+        score += 120;
+    else if (type === 'webview')
+        score += 100;
+    else if (type === 'page')
+        score += 80;
+    else if (type === 'iframe')
+        score += 20;
+    if (url.startsWith('http://localhost') || url.startsWith('https://localhost'))
+        score += 90;
+    if (url.startsWith('file://'))
+        score += 60;
+    if (url.startsWith('http://127.0.0.1') || url.startsWith('https://127.0.0.1'))
+        score += 50;
+    if (url.startsWith('about:blank'))
+        score -= 120;
+    if (url === '' || url === 'about:blank')
+        score -= 40;
+    if (title && title !== 'devtools')
+        score += 25;
+    // Boost score for known Electron app names from the registry (builtin + user-defined)
+    const appNames = Object.values(getAllElectronApps()).map(a => (a.displayName ?? a.processName).toLowerCase());
+    for (const name of appNames) {
+        if (title.includes(name)) {
+            score += 120;
+            break;
+        }
+    }
+    for (const name of appNames) {
+        if (url.includes(name)) {
+            score += 100;
+            break;
+        }
+    }
+    return score;
+}
+function compilePreferredPattern(raw) {
+    const value = raw?.trim();
+    if (!value)
+        return undefined;
+    return new RegExp(escapeRegExp(value.toLowerCase()));
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export const __test__ = {
+    selectCDPTarget,
+    scoreCDPTarget,
+};
+function fetchJsonDirect(url) {
+    return new Promise((resolve, reject) => {
+        const parsed = new URL(url);
+        const request = (parsed.protocol === 'https:' ? httpsRequest : httpRequest)(parsed, (res) => {
+            const statusCode = res.statusCode ?? 0;
+            if (statusCode < 200 || statusCode >= 300) {
+                res.resume();
+                reject(new Error(`Failed to fetch CDP targets: HTTP ${statusCode}`));
+                return;
+            }
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+                }
+                catch (error) {
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+        request.on('error', reject);
+        request.setTimeout(10_000, () => request.destroy(new Error('Timed out fetching CDP targets')));
+        request.end();
+    });
+}

package/dist/src/browser/cdp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/cdp.test.js

@@ -0,0 +1,79 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const { MockWebSocket } = vi.hoisted(() => {
+    class MockWebSocket {
+        static OPEN = 1;
+        readyState = 1;
+        handlers = new Map();
+        constructor(_url) {
+            queueMicrotask(() => this.emit('open'));
+        }
+        on(event, handler) {
+            const handlers = this.handlers.get(event) ?? [];
+            handlers.push(handler);
+            this.handlers.set(event, handlers);
+        }
+        send(_message) { }
+        close() {
+            this.readyState = 3;
+        }
+        emit(event, ...args) {
+            for (const handler of this.handlers.get(event) ?? []) {
+                handler(...args);
+            }
+        }
+    }
+    return { MockWebSocket };
+});
+vi.mock('ws', () => ({
+    WebSocket: MockWebSocket,
+}));
+import { CDPBridge } from './cdp.js';
+describe('CDPBridge cookies', () => {
+    beforeEach(() => {
+        vi.unstubAllEnvs();
+    });
+    it('filters cookies by actual domain match instead of substring match', async () => {
+        vi.stubEnv('WEBCMD_CDP_ENDPOINT', 'ws://127.0.0.1:9222/devtools/page/1');
+        const bridge = new CDPBridge();
+        vi.spyOn(bridge, 'send').mockResolvedValue({
+            cookies: [
+                { name: 'good', value: '1', domain: '.example.com' },
+                { name: 'exact', value: '2', domain: 'example.com' },
+                { name: 'bad', value: '3', domain: 'notexample.com' },
+            ],
+        });
+        const page = await bridge.connect();
+        const cookies = await page.getCookies({ domain: 'example.com' });
+        expect(cookies).toEqual([
+            { name: 'good', value: '1', domain: '.example.com' },
+            { name: 'exact', value: '2', domain: 'example.com' },
+        ]);
+    });
+    it('exposes native input helpers on direct CDP pages', async () => {
+        vi.stubEnv('WEBCMD_CDP_ENDPOINT', 'ws://127.0.0.1:9222/devtools/page/1');
+        const bridge = new CDPBridge();
+        const send = vi.spyOn(bridge, 'send').mockResolvedValue({});
+        const page = await bridge.connect();
+        send.mockClear();
+        expect(page.nativeType).toBeTypeOf('function');
+        expect(page.nativeKeyPress).toBeTypeOf('function');
+        expect(page.nativeClick).toBeTypeOf('function');
+        expect(page.handleJavaScriptDialog).toBeTypeOf('function');
+        expect(page.cdp).toBeTypeOf('function');
+        await page.nativeType('hello');
+        await page.nativeKeyPress('a', ['Ctrl']);
+        await page.nativeClick(10, 20);
+        await page.handleJavaScriptDialog(true, 'ok');
+        await page.cdp('Page.getLayoutMetrics', {});
+        expect(send.mock.calls).toEqual([
+            ['Input.insertText', { text: 'hello' }],
+            ['Input.dispatchKeyEvent', { type: 'keyDown', key: 'a', modifiers: 2 }],
+            ['Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', modifiers: 2 }],
+            ['Input.dispatchMouseEvent', { type: 'mouseMoved', x: 10, y: 20 }],
+            ['Input.dispatchMouseEvent', { type: 'mousePressed', x: 10, y: 20, button: 'left', clickCount: 1 }],
+            ['Input.dispatchMouseEvent', { type: 'mouseReleased', x: 10, y: 20, button: 'left', clickCount: 1 }],
+            ['Page.handleJavaScriptDialog', { accept: true, promptText: 'ok' }],
+            ['Page.getLayoutMetrics', {}],
+        ]);
+    });
+});

package/dist/src/browser/compound.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Compound-component expansion for high-agent-failure form controls.
+ *
+ * Agents burn turns on three recurring input categories because the raw
+ * attribute dump from `browser state` under-specifies them:
+ *
+ *   - date / time / datetime-local / month / week — agents type
+ *     free-form strings and the browser silently ignores mismatched formats.
+ *   - select — the snapshot caps visible options at ~6; agents don't know
+ *     the full option set, can't match by label, and waste turns clicking
+ *     to open the dropdown just to read options.
+ *   - file — the snapshot shows current filenames but not `accept` or
+ *     `multiple`; agents re-upload or pick unsupported MIME types.
+ *
+ * `compoundInfoOf(el)` returns a structured JSON summary agents can rely
+ * on. Included in `browser find --css` envelope so the agent gets the
+ * rich view without extra round-trips.
+ *
+ * Emitted as a JS source string (`COMPOUND_INFO_JS`) so it can be inlined
+ * into the generated evaluate scripts under find / snapshot / eval.
+ */
+export type DateLikeControl = 'date' | 'time' | 'datetime-local' | 'month' | 'week';
+export interface DateCompound {
+    control: DateLikeControl;
+    format: string;
+    current: string;
+    min?: string;
+    max?: string;
+}
+export interface SelectOption {
+    label: string;
+    value: string;
+    selected: boolean;
+    disabled?: boolean;
+}
+export interface SelectCompound {
+    control: 'select';
+    multiple: boolean;
+    current: string | string[];
+    options: SelectOption[];
+    options_total: number;
+}
+export interface FileCompound {
+    control: 'file';
+    multiple: boolean;
+    current: string[];
+    accept?: string;
+}
+export type CompoundInfo = DateCompound | SelectCompound | FileCompound;
+/** Max options included in a SelectCompound.options[]. Above this, `options_total` still reflects the true count. */
+export declare const COMPOUND_SELECT_OPTIONS_CAP = 50;
+/** Max characters per option label / file name. */
+export declare const COMPOUND_LABEL_CAP = 80;
+/**
+ * JavaScript source declaring `compoundInfoOf(el)`. Inlined into the JS
+ * emitted by `buildFindJs` (and any other evaluate script that needs the
+ * rich compound view). Returns a `CompoundInfo` object or `null`.
+ */
+export declare const COMPOUND_INFO_JS = "\nfunction compoundInfoOf(el) {\n  if (!el || !el.tagName) return null;\n  const tag = el.tagName;\n  const LABEL_CAP = 80;\n  const OPTS_CAP = 50;\n  if (tag === 'INPUT') {\n    const type = (el.getAttribute('type') || 'text').toLowerCase();\n    const FORMATS = {\n      'date': 'YYYY-MM-DD',\n      'time': 'HH:MM',\n      'datetime-local': 'YYYY-MM-DDTHH:MM',\n      'month': 'YYYY-MM',\n      'week': 'YYYY-W##',\n    };\n    if (FORMATS[type]) {\n      const info = {\n        control: type,\n        format: FORMATS[type],\n        current: (el.value == null ? '' : String(el.value)),\n      };\n      const min = el.getAttribute('min');\n      if (min) info.min = min;\n      const max = el.getAttribute('max');\n      if (max) info.max = max;\n      return info;\n    }\n    if (type === 'file') {\n      const info = {\n        control: 'file',\n        multiple: !!el.multiple,\n        current: [],\n      };\n      const accept = el.getAttribute('accept');\n      if (accept) info.accept = accept;\n      try {\n        if (el.files && el.files.length) {\n          for (let i = 0; i < el.files.length; i++) {\n            const name = (el.files[i].name || '').slice(0, LABEL_CAP);\n            info.current.push(name);\n          }\n        }\n      } catch (_) {}\n      return info;\n    }\n    return null;\n  }\n  if (tag === 'SELECT') {\n    const multiple = !!el.multiple;\n    const options = [];\n    const selectedLabels = [];\n    let total = 0;\n    try {\n      const opts = el.options || [];\n      total = opts.length;\n      // Walk ALL options so `current` reflects selections that sit beyond the\n      // serialization cap. Only the first OPTS_CAP entries get pushed into\n      // options[]; anything past the cap still contributes to selectedLabels\n      // so agents see the true current state of big dropdowns.\n      for (let i = 0; i < opts.length; i++) {\n        const o = opts[i];\n        const labelRaw = (o.label != null && o.label !== '') ? o.label : (o.text || '');\n        const label = String(labelRaw).trim().slice(0, LABEL_CAP);\n        if (i < OPTS_CAP) {\n          const entry = { label: label, value: o.value, selected: !!o.selected };\n          if (o.disabled) entry.disabled = true;\n          options.push(entry);\n        }\n        if (o.selected) selectedLabels.push(label);\n      }\n    } catch (_) {}\n    return {\n      control: 'select',\n      multiple: multiple,\n      current: multiple ? selectedLabels : (selectedLabels[0] || ''),\n      options: options,\n      options_total: total,\n    };\n  }\n  return null;\n}\n";