@aivi/chrome 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @aivi/chrome
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A puppeteer-shaped driver for the Chrome that is already installed. One
+launch, one websocket, a dozen page verbs — and the full DevTools Protocol
+still reachable underneath, because a wrapper that hides the protocol is a
+leash.
+
+Why not puppeteer: its npm tree is 32 MB (`chromium-bidi`, its own `zod`,
+`devtools-protocol`, more) for helpers we can write in a page function. This
+package has **no dependencies**: Node 26 ships `fetch`, `WebSocket`, and
+`EventTarget` itself.
+
+## Use
+
+```ts
+import { Chrome } from '@aivi/chrome'
+
+const chrome = await Chrome.launch({ profileDir: '/tmp/aivi-browser' })
+const tab = await chrome.newTab()
+
+// the face trick: install before the page's own scripts run
+await tab.send('Page.addScriptToEvaluateOnNewDocument', { source: faceSource })
+await tab.goto('https://meet.google.com/abc-defg-hij')
+
+await tab.waitForText('Ask to join')
+await tab.fill('input[aria-label="Your name"]', 'aivi')
+await tab.click('button[aria-label="Ask to join"]')
+await tab.waitForText('Leave call')
+
+await chrome.close() // ends the browser it launched
+```
+
+`Chrome.attach({ debugUrl })` takes over a browser somebody else started;
+its `close()` disconnects and leaves that browser running.
+
+## The verbs
+
+| | |
+| --- | --- |
+| `evaluate(expr)` / `call(fn, ...args)` | run code in the page, plain values back |
+| `waitFor(fn)` / `waitForSelector` / `waitForText` | poll until truthy, bounded |
+| `exists` / `text` / `attr` / `url` | read the DOM |
+| `click` / `fill` | act on it (`fill` does the native-setter dance frameworks need) |
+| `screenshot` / `goto` / `close` | the rest of the day |
+| `send(method, params)` / `on(event)` | the escape hatch: any command, any event, this tab |
+
+Page functions travel as source text: they close over nothing from your
+file, take data as arguments, and return plain values.
+
+## Honest edges
+
+- Clicks are synthetic (`element.click()`). Proven on real Meet screens; an
+  app that demands trusted input gets `Input.dispatchMouseEvent` through
+  `send`.
+- Timers are bounded one-shot waits for the two things the protocol has no
+  event for — "an element finally exists" and "the booting browser wrote its
+  port file". Nothing here repeats on a schedule.
+- No silent reconnect: the socket to a browser you launched dies with it, on
+  purpose.
+- Chrome 136+ ignores the debug port on the default profile, so a launch
+  always carries its own `--user-data-dir`.
+- macOS and Linux. Windows: not yet, say so if you need it.

package/dist/chrome.d.ts

@@ -0,0 +1,62 @@
+import { CdpConnection } from './connection.ts';
+import { Tab } from './tab.ts';
+/** Find the browser binary: `AIVI_CHROME_PATH` if set (a set-but-wrong value
+ *  is a loud error, not a silent miss), then the usual paths, then PATH.
+ *  Undefined means no browser found; the caller decides what that means. */
+export declare function findChrome(): string | undefined;
+export interface ChromeLaunchOptions {
+    /** A directory for this browser alone. Chrome refuses its debug port on
+     *  the default profile, so this is not optional; a throwaway one is fine
+     *  and `rm` then cleans up. */
+    profileDir: string;
+    /** Skip the search and say which binary to run. */
+    executablePath?: string;
+    /** Default true: `--headless=new`, the mode proven on the face route. */
+    headless?: boolean;
+    /** Appended after the default flags. */
+    args?: string[];
+    /** How long the browser gets to boot and answer. Default 20000. */
+    startupTimeoutMs?: number;
+    commandMaxTime?: number;
+}
+export interface ChromeAttachOptions {
+    /** Base URL of a browser already started with `--remote-debugging-port`.
+     *  Default `http://127.0.0.1:9222`. */
+    debugUrl?: string;
+    /** The websocket URL straight from `/json/version`, when discovery is
+     *  already done. */
+    wsUrl?: string;
+    /** How long to wait for the answer. Default 20000. */
+    timeoutMs?: number;
+    commandMaxTime?: number;
+}
+export declare class Chrome {
+    #private;
+    readonly connection: CdpConnection;
+    /** The browser's own version string, e.g. `Chrome/141.0.7390.107`. */
+    readonly browser: string;
+    /** The debug port, so an attach or a status line can name it. */
+    readonly port: number;
+    private constructor();
+    /** Launch the installed Chrome as a child of this process. */
+    static launch(options: ChromeLaunchOptions): Promise<Chrome>;
+    /** Take over a browser somebody else started with
+     *  `--remote-debugging-port`. `close()` disconnects and leaves it running —
+     *  it is not ours to kill. */
+    static attach(options?: ChromeAttachOptions): Promise<Chrome>;
+    /** True when this handle launched the browser and owns ending it. */
+    get launched(): boolean;
+    /** Notice the browser going away on its own — a crash, or a hand at the
+     *  Activity Monitor. The listener fires once when the connection dies;
+     *  our own `close()` does not count. A caller holding live state in the
+     *  page (a meeting) uses this to say the state is over instead of
+     *  knocking on a dead browser forever. */
+    onGone(listener: () => void): void;
+    /** Open a tab, blank on purpose: the caller installs its scripts before
+     *  the first navigation — `tab.send('Page.addScriptToEvaluateOnNewDocument',
+     *  ...)`, then `tab.goto(url)` — which is the whole face trick. */
+    newTab(): Promise<Tab>;
+    /** Disconnect, and end the browser when we launched it. An attached browser
+     *  keeps running. */
+    close(): Promise<void>;
+}

package/dist/chrome.js

@@ -0,0 +1,244 @@
+/**
+ * The browser itself: launch the installed Chrome as our child, or attach to
+ * one somebody else started, and hand out tabs.
+ *
+ * Chrome 136 and later ignore `--remote-debugging-port` on the default
+ * profile, so a launch always carries its own `--user-data-dir` — which is
+ * also what lets several aivi browsers sit side by side, and keeps the
+ * operator's own browser out of it. We ask for port 0 and read the real port
+ * from the `DevToolsActivePort` file Chrome writes in the profile, so two
+ * launches never fight over a number.
+ *
+ * The default flags are the ones proven on real Meet screens: camera and mic
+ * prompts answer themselves, WebGL paints without a GPU, nothing waits for a
+ * human gesture. Further flags append after them.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { delimiter, join } from 'node:path';
+import { CdpConnection, sleep } from './connection.js';
+import { Tab } from './tab.js';
+/** Usual install paths per platform, after the `AIVI_CHROME_PATH`
+ *  environment variable. No Windows: aivi's hosts are mac and linux. */
+const CANDIDATES = {
+    darwin: [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ],
+    linux: [
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/google-chrome',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+    ],
+};
+const PATH_NAMES = ['google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser'];
+const DEFAULT_ARGS = [
+    '--use-fake-ui-for-media-stream', // the camera and mic prompts answer themselves
+    '--autoplay-policy=no-user-gesture-required',
+    '--enable-unsafe-swiftshader', // WebGL without a GPU: the face is a WebGL canvas
+    '--disable-blink-features=AutomationControlled', // navigator.webdriver reads false, like a normal browser (CDP otherwise sets it true, and conferencing pages read it)
+    // the face animates on requestAnimationFrame, and Chrome throttles that
+    // clock for windows sitting behind others — the meeting tile froze on
+    // the last frame while our window was occluded (real meeting,
+    // 2026-10-14). These two flags keep our own window's clock honest.
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+    '--window-size=1280,720',
+    '--lang=en-US',
+];
+const DEFAULT_STARTUP_TIMEOUT_MS = 20_000;
+/** Find the browser binary: `AIVI_CHROME_PATH` if set (a set-but-wrong value
+ *  is a loud error, not a silent miss), then the usual paths, then PATH.
+ *  Undefined means no browser found; the caller decides what that means. */
+export function findChrome() {
+    const fromEnv = process.env.AIVI_CHROME_PATH;
+    if (fromEnv !== undefined && fromEnv !== '') {
+        if (!existsSync(fromEnv))
+            throw new Error(`AIVI_CHROME_PATH points at nothing: ${fromEnv}`);
+        return fromEnv;
+    }
+    const known = [...(CANDIDATES[process.platform] ?? [])];
+    for (const name of PATH_NAMES) {
+        for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+            if (dir !== '' && existsSync(join(dir, name)))
+                known.push(join(dir, name));
+        }
+    }
+    return known.find(path => existsSync(path));
+}
+function exited(child) {
+    return child.exitCode !== null || child.signalCode !== null;
+}
+function exitCodeOf(child) {
+    return child.exitCode !== null ? String(child.exitCode) : (child.signalCode ?? '?');
+}
+/** Wait for the port file Chrome writes in the profile, watching the process
+ *  so a browser that dies on a bad flag fails here with its code, not with a
+ *  timeout much later. */
+async function readActivePort(portFile, child, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        try {
+            const port = Number((await readFile(portFile, 'utf8')).split('\n')[0]?.trim());
+            if (Number.isInteger(port) && port > 0 && port < 65536)
+                return port;
+        }
+        catch {
+            // Chrome has not written the file yet
+        }
+        if (exited(child)) {
+            throw new Error(`chrome exited before reporting a port (code ${exitCodeOf(child)}) — check the flags`);
+        }
+        await sleep(50);
+    } while (Date.now() < deadline);
+    throw new Error(`no DevToolsActivePort in the profile within ${timeoutMs} ms`);
+}
+/** Ask `/json/version` until it answers, watching the process when there is
+ *  one. The websocket URL is the browser's own — we never build it. */
+async function discoverVersion(baseUrl, deadline, child) {
+    do {
+        try {
+            const response = await fetch(`${baseUrl}/json/version`);
+            if (response.ok) {
+                const info = (await response.json());
+                if (info.webSocketDebuggerUrl !== undefined)
+                    return info;
+            }
+        }
+        catch {
+            // nothing listening yet
+        }
+        if (child !== undefined && exited(child)) {
+            throw new Error(`chrome exited before answering /json/version (code ${exitCodeOf(child)})`);
+        }
+        await sleep(100);
+    } while (Date.now() < deadline);
+    throw new Error(`the browser at ${baseUrl} never answered /json/version`);
+}
+/** SIGTERM so Chrome can flush the profile, SIGKILL only if it ignores
+ *  that. One bounded wait either way. */
+async function killChild(child) {
+    if (exited(child))
+        return;
+    child.kill('SIGTERM');
+    await new Promise(resolve => {
+        const killer = setTimeout(() => child.kill('SIGKILL'), 5_000);
+        child.once('exit', () => {
+            clearTimeout(killer);
+            resolve();
+        });
+    });
+}
+export class Chrome {
+    connection;
+    /** The browser's own version string, e.g. `Chrome/141.0.7390.107`. */
+    browser;
+    /** The debug port, so an attach or a status line can name it. */
+    port;
+    #child;
+    #closed = false;
+    constructor(connection, info, port, child) {
+        this.connection = connection;
+        this.browser = info.Browser ?? 'unknown';
+        this.port = port;
+        this.#child = child;
+    }
+    /** Launch the installed Chrome as a child of this process. */
+    static async launch(options) {
+        const bin = options.executablePath ?? findChrome();
+        if (bin === undefined)
+            throw new Error('no Chrome binary found — install Chrome or set AIVI_CHROME_PATH');
+        if (options.profileDir === '')
+            throw new Error('launch needs its own profileDir (Chrome ignores the debug port on the default profile)');
+        const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+        await mkdir(options.profileDir, { recursive: true });
+        const portFile = join(options.profileDir, 'DevToolsActivePort');
+        // a file from an earlier run would advertise a dead port
+        await rm(portFile, { force: true });
+        const flags = [
+            ...((options.headless ?? true) ? ['--headless=new'] : []),
+            `--user-data-dir=${options.profileDir}`,
+            '--remote-debugging-port=0',
+            '--no-first-run',
+            '--no-default-browser-check',
+            ...DEFAULT_ARGS,
+            ...(options.args ?? []),
+            // headless Chrome exits when its last tab closes, so one stays open
+            'about:blank',
+        ];
+        const child = spawn(bin, flags, { stdio: 'ignore' });
+        try {
+            const port = await readActivePort(portFile, child, startupTimeoutMs);
+            const info = await discoverVersion(`http://127.0.0.1:${port}`, Date.now() + startupTimeoutMs, child);
+            const connection = await CdpConnection.open(info.webSocketDebuggerUrl ?? '', {
+                ...(options.commandMaxTime === undefined ? {} : { commandMaxTime: options.commandMaxTime }),
+            });
+            return new Chrome(connection, info, port, child);
+        }
+        catch (error) {
+            await killChild(child);
+            throw error;
+        }
+    }
+    /** Take over a browser somebody else started with
+     *  `--remote-debugging-port`. `close()` disconnects and leaves it running —
+     *  it is not ours to kill. */
+    static async attach(options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+        let info = {};
+        let wsUrl = options.wsUrl;
+        if (wsUrl === undefined) {
+            const baseUrl = options.debugUrl ?? 'http://127.0.0.1:9222';
+            info = await discoverVersion(baseUrl, Date.now() + timeoutMs, undefined);
+            wsUrl = info.webSocketDebuggerUrl ?? '';
+        }
+        // the answer carries the real host and port, so trust it over the question
+        const port = Number(new URL(wsUrl).port);
+        const connection = await CdpConnection.open(wsUrl, {
+            ...(options.commandMaxTime === undefined ? {} : { commandMaxTime: options.commandMaxTime }),
+        });
+        return new Chrome(connection, info, port, undefined);
+    }
+    /** True when this handle launched the browser and owns ending it. */
+    get launched() {
+        return this.#child !== undefined;
+    }
+    /** Notice the browser going away on its own — a crash, or a hand at the
+     *  Activity Monitor. The listener fires once when the connection dies;
+     *  our own `close()` does not count. A caller holding live state in the
+     *  page (a meeting) uses this to say the state is over instead of
+     *  knocking on a dead browser forever. */
+    onGone(listener) {
+        this.connection.addEventListener('close', () => {
+            if (!this.#closed)
+                listener();
+        }, { once: true });
+    }
+    /** Open a tab, blank on purpose: the caller installs its scripts before
+     *  the first navigation — `tab.send('Page.addScriptToEvaluateOnNewDocument',
+     *  ...)`, then `tab.goto(url)` — which is the whole face trick. */
+    async newTab() {
+        const { targetId } = await this.connection.send('Target.createTarget', {
+            url: 'about:blank',
+        });
+        const { sessionId } = await this.connection.send('Target.attachToTarget', {
+            targetId,
+            flatten: true,
+        });
+        return new Tab(this.connection, targetId, sessionId);
+    }
+    /** Disconnect, and end the browser when we launched it. An attached browser
+     *  keeps running. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.connection.close();
+        if (this.#child !== undefined)
+            await killChild(this.#child);
+    }
+}

package/dist/connection.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One websocket to one Chrome browser: the bottom of the protocol. Commands
+ * are matched to their answers by id. A command carrying a session id
+ * addresses one tab; without one it addresses the browser itself. Events
+ * arrive named `Domain.event` and carry the session they belong to.
+ *
+ * There is no silent reconnection. A socket to a browser we launched dies
+ * with it, and hiding that would turn a dead meeting into a hung process:
+ * calls still waiting reject as closed, and the `close` event says it
+ * happened.
+ */
+/** A protocol answer or a connection trouble, either way with a `code`.
+ *  Answers from the browser carry the protocol's numeric codes (e.g. -32601
+ *  for a method that does not exist); our own troubles use the string
+ *  constants exported below. */
+export declare class CdpError extends Error {
+    readonly code: number | string;
+    constructor(message: string, code: number | string);
+}
+export declare const CONNECTION_CLOSED = "connectionClosed";
+export declare const CONNECTION_REFUSED = "connectionRefused";
+export declare const CONNECTION_TIMED_OUT = "connectionTimedOut";
+export declare const COMMAND_TIMED_OUT = "commandTimedOut";
+/** A protocol event (`Page.loadEventFired` and friends). `sessionId` is the
+ *  tab the event came from, undefined for browser-level events. */
+export declare class CdpEvent extends Event {
+    readonly params: Record<string, unknown> | undefined;
+    readonly sessionId: string | undefined;
+    constructor(type: string, init?: {
+        params?: Record<string, unknown> | undefined;
+        sessionId?: string | undefined;
+    });
+}
+/** A one-shot wait. This package's only timer: polling is honest when the
+ *  protocol reports events like "the page loaded" but not "an element
+ *  finally exists", and puppeteer and playwright poll the same way. Nothing
+ *  here repeats on a schedule; every sleep belongs to a bounded wait that a
+ *  caller started and can end. */
+export declare function sleep(ms: number): Promise<void>;
+export interface CdpConnectionOptions {
+    /** Reject a command whose answer never arrives, after this many
+     *  milliseconds. The connection stays usable: the protocol cannot cancel a
+     *  command once it is sent, so the browser may still have acted on it.
+     *  Default 30000, 0 to disable. */
+    commandMaxTime?: number;
+    /** Bound the websocket handshake itself. Default 10000. */
+    connectMaxTime?: number;
+}
+export declare class CdpConnection extends EventTarget {
+    #private;
+    private constructor();
+    /** Open the socket and fail fast if nothing answers. A caller waiting for
+     *  a booting browser retries at its own level, where it also watches that
+     *  browser's process. */
+    static open(wsUrl: string, options?: CdpConnectionOptions): Promise<CdpConnection>;
+    get closed(): boolean;
+    send<T = unknown>(method: string, params?: object, sessionId?: string): Promise<T>;
+    /** Close the socket. Waiting calls reject; listeners are not kept, so a
+     *  consumer that wants to reconnect builds it with its own knowledge. */
+    close(): void;
+}

package/dist/connection.js

@@ -0,0 +1,181 @@
+/**
+ * One websocket to one Chrome browser: the bottom of the protocol. Commands
+ * are matched to their answers by id. A command carrying a session id
+ * addresses one tab; without one it addresses the browser itself. Events
+ * arrive named `Domain.event` and carry the session they belong to.
+ *
+ * There is no silent reconnection. A socket to a browser we launched dies
+ * with it, and hiding that would turn a dead meeting into a hung process:
+ * calls still waiting reject as closed, and the `close` event says it
+ * happened.
+ */
+/** A protocol answer or a connection trouble, either way with a `code`.
+ *  Answers from the browser carry the protocol's numeric codes (e.g. -32601
+ *  for a method that does not exist); our own troubles use the string
+ *  constants exported below. */
+export class CdpError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'CdpError';
+        this.code = code;
+    }
+}
+export const CONNECTION_CLOSED = 'connectionClosed';
+export const CONNECTION_REFUSED = 'connectionRefused';
+export const CONNECTION_TIMED_OUT = 'connectionTimedOut';
+export const COMMAND_TIMED_OUT = 'commandTimedOut';
+/** A protocol event (`Page.loadEventFired` and friends). `sessionId` is the
+ *  tab the event came from, undefined for browser-level events. */
+export class CdpEvent extends Event {
+    params;
+    sessionId;
+    constructor(type, init = {}) {
+        super(type);
+        this.params = init.params;
+        this.sessionId = init.sessionId;
+    }
+}
+/** A one-shot wait. This package's only timer: polling is honest when the
+ *  protocol reports events like "the page loaded" but not "an element
+ *  finally exists", and puppeteer and playwright poll the same way. Nothing
+ *  here repeats on a schedule; every sleep belongs to a bounded wait that a
+ *  caller started and can end. */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+const DEFAULT_COMMAND_MAX_TIME = 30_000;
+const DEFAULT_CONNECT_MAX_TIME = 10_000;
+export class CdpConnection extends EventTarget {
+    #wsUrl;
+    #commandMaxTime;
+    #connectMaxTime;
+    #pending = new Map();
+    #ws;
+    #nextId = 0;
+    #closed = false;
+    constructor(wsUrl, options) {
+        super();
+        this.#wsUrl = wsUrl;
+        this.#commandMaxTime = options.commandMaxTime ?? DEFAULT_COMMAND_MAX_TIME;
+        this.#connectMaxTime = options.connectMaxTime ?? DEFAULT_CONNECT_MAX_TIME;
+    }
+    /** Open the socket and fail fast if nothing answers. A caller waiting for
+     *  a booting browser retries at its own level, where it also watches that
+     *  browser's process. */
+    static async open(wsUrl, options = {}) {
+        const connection = new CdpConnection(wsUrl, options);
+        await connection.#connect();
+        return connection;
+    }
+    get closed() {
+        return this.#closed;
+    }
+    #connect() {
+        const ws = new WebSocket(this.#wsUrl);
+        this.#ws = ws;
+        ws.addEventListener('message', event => this.#onMessage(event.data));
+        ws.addEventListener('close', event => {
+            this.#ws = undefined;
+            this.#drain(event.reason === '' ? undefined : ` (${event.reason})`);
+            if (!this.#closed) {
+                this.#closed = true;
+                this.dispatchEvent(new Event('close'));
+            }
+        });
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer;
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                ws.close();
+                reject(error);
+            };
+            timer = setTimeout(() => fail(new CdpError(`socket not opened within ${this.#connectMaxTime} ms`, CONNECTION_TIMED_OUT)), this.#connectMaxTime);
+            ws.addEventListener('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+            ws.addEventListener('error', () => fail(new CdpError(`could not reach the browser at ${this.#wsUrl}`, CONNECTION_REFUSED)), { once: true });
+        });
+    }
+    send(method, params = {}, sessionId) {
+        const ws = this.#ws;
+        if (this.#closed || ws === undefined || ws.readyState !== WebSocket.OPEN) {
+            return Promise.reject(new CdpError(`connection closed when calling ${method}`, CONNECTION_CLOSED));
+        }
+        const id = this.#nextId;
+        this.#nextId = (this.#nextId + 1) % Number.MAX_SAFE_INTEGER;
+        const message = { id, method, params };
+        if (sessionId !== undefined)
+            message.sessionId = sessionId;
+        return new Promise((resolve, reject) => {
+            const timer = this.#commandMaxTime === 0
+                ? undefined
+                : setTimeout(() => {
+                    this.#pending.delete(id);
+                    reject(new CdpError(`no answer for ${method} within ${this.#commandMaxTime} ms`, COMMAND_TIMED_OUT));
+                }, this.#commandMaxTime);
+            this.#pending.set(id, { method, resolve: resolve, reject, timer });
+            try {
+                ws.send(JSON.stringify(message));
+            }
+            catch (error) {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                this.#pending.delete(id);
+                reject(new CdpError(`send failed when calling ${method}: ${String(error)}`, CONNECTION_CLOSED));
+            }
+        });
+    }
+    /** Close the socket. Waiting calls reject; listeners are not kept, so a
+     *  consumer that wants to reconnect builds it with its own knowledge. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#drain(' by us');
+        this.#ws?.close();
+        this.dispatchEvent(new Event('close'));
+    }
+    #onMessage(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (message.id !== undefined) {
+            const pending = this.#pending.get(message.id);
+            if (pending !== undefined) {
+                this.#pending.delete(message.id);
+                if (pending.timer !== undefined)
+                    clearTimeout(pending.timer);
+                if (message.error === undefined) {
+                    pending.resolve(message.result);
+                }
+                else {
+                    pending.reject(new CdpError(`${message.error.message ?? 'protocol error'} when calling ${pending.method}`, message.error.code ?? -32000));
+                }
+            }
+        }
+        if (message.method !== undefined) {
+            this.dispatchEvent(new CdpEvent(message.method, { params: message.params, sessionId: message.sessionId }));
+        }
+    }
+    #drain(reasonSuffix) {
+        for (const pending of this.#pending.values()) {
+            if (pending.timer !== undefined)
+                clearTimeout(pending.timer);
+            pending.reject(new CdpError(`connection closed${reasonSuffix ?? ''} when calling ${pending.method}`, CONNECTION_CLOSED));
+        }
+        this.#pending.clear();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Chrome, type ChromeAttachOptions, type ChromeLaunchOptions, findChrome } from './chrome.ts';
+export { CdpConnection, type CdpConnectionOptions, CdpError, CdpEvent, COMMAND_TIMED_OUT, CONNECTION_CLOSED, CONNECTION_REFUSED, CONNECTION_TIMED_OUT, sleep, } from './connection.ts';
+export { type Locator, type PageFunction, Tab, type WaitOptions } from './tab.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Chrome, findChrome } from './chrome.js';
+export { CdpConnection, CdpError, CdpEvent, COMMAND_TIMED_OUT, CONNECTION_CLOSED, CONNECTION_REFUSED, CONNECTION_TIMED_OUT, sleep, } from './connection.js';
+export { Tab } from './tab.js';

package/dist/tab.d.ts

@@ -0,0 +1,132 @@
+/**
+ * One tab, addressed by the session id the browser handed us.
+ *
+ * The helpers are the everyday verbs — read, wait, click, type — and every
+ * one of them is the same trick: a small function, sent as source text and
+ * run inside the page by `Runtime.evaluate`, whose return value comes back
+ * as a plain value. A page function must not close over anything from this
+ * file; data goes in as arguments, and only plain values come back. That
+ * is why the locators below carry their matcher as an argument and their
+ * finder as a self-contained function, not as shared code.
+ *
+ * Waiting is the package's job, never the caller's. `tab.locator(matcher)`
+ * hands back a handle whose verbs wait for the page to be ready for them:
+ * `click()` does not fire until the element exists AND is enabled, the way
+ * playwright's actionability works
+ * (https://playwright.dev/docs/actionability). A framework keeps its own
+ * submit buttons disabled until it has accepted what was typed — so the
+ * wait for enabled is the verification that the page will listen, and no
+ * caller ever clicks in a loop hoping one lands.
+ *
+ * Whatever the helpers do not cover is one `send` away: the full protocol
+ * stays reachable per tab, because the face trick itself — installing a
+ * script before the page's own scripts run — is exactly such a raw call.
+ */
+import type { CdpConnection, CdpEvent } from './connection.ts';
+/** A function that runs inside the page. It travels as source text, so it
+ *  closes over nothing from here. */
+export type PageFunction<T = unknown> = (...args: never[]) => T;
+export interface WaitOptions {
+    /** Give up after this many milliseconds. Default 10000. */
+    timeoutMs?: number;
+    /** Pause between looks. Default 120. */
+    intervalMs?: number;
+}
+/** A waiting handle on an element, in the shape playwright made popular:
+ *  get it once from `tab.locator(matcher)`, and every verb on it waits
+ *  for the page to be ready instead of the caller guessing in a loop. */
+export interface Locator {
+    /** The matcher it was built from, for logs and errors. */
+    readonly matcher: string;
+    /** There right now — disabled counts. No waiting. */
+    exists(): Promise<boolean>;
+    /** There right now AND able to take a click. No waiting. */
+    enabled(): Promise<boolean>;
+    /** One attribute's value, right now; undefined when the element or the
+     *  attribute is absent. The page's own state often lives in attributes
+     *  (`data-is-muted` on Meet's mic button) where names cannot see it. */
+    attr(name: string): Promise<string | undefined>;
+    /** Wait until it is there. */
+    waitFor(options?: WaitOptions): Promise<void>;
+    /** Wait until it is there and enabled, then click it ONCE, and answer
+     *  the words it carries (aria-label, text, or tag). A framework keeps
+     *  its submit buttons disabled until it accepts what was typed, so this
+     *  wait is the proof the page will listen — the old failure was clicking
+     *  a still-hydrating screen, reporting success, and then waiting on a
+     *  human for an action the page never received (real Meet, 2026-10-14). */
+    click(options?: WaitOptions): Promise<string>;
+    /** Wait until it is there, then type into it the way its framework
+     *  expects. */
+    fill(value: string, options?: WaitOptions): Promise<void>;
+}
+export declare class Tab {
+    #private;
+    constructor(connection: CdpConnection, targetId: string, sessionId: string);
+    get targetId(): string;
+    get sessionId(): string;
+    /** The escape hatch: any protocol command, addressed to this tab. */
+    send<T = unknown>(method: string, params?: object): Promise<T>;
+    /** Listen for a protocol event of this tab. The listener sees only events
+     *  carrying our session id. */
+    on(event: string, listener: (event: CdpEvent) => void): this;
+    off(event: string, listener: (event: CdpEvent) => void): this;
+    /** Navigate and wait for the load event. Blank on arrival is normal for a
+     *  fresh tab: the caller installs its scripts first, then drives here. */
+    goto(url: string, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** Run an expression in the page and take its value back. */
+    evaluate<T = unknown>(expression: string): Promise<T>;
+    /** Run a function in the page and take its value back. A string is sent as
+     *  source, for text that was built elsewhere. Arguments travel as JSON —
+     *  the same rule as return values, so a page function truly cannot close
+     *  over anything or carry anything but plain data. `Runtime.evaluate` in a
+     *  wrapped expression is used instead of `callFunctionOn` because it works
+     *  from the first breath of a fresh tab, before any execution context is
+     *  announced. */
+    call<T = unknown>(fn: PageFunction<T> | string, ...args: unknown[]): Promise<T>;
+    /** Poll until the condition answers truthy, and take that answer. CDP
+     *  reports "the page loaded", never "this element finally exists", so
+     *  polling is the honest mechanism — bounded, one-shot sleeps. Extra
+     *  arguments travel to the page function as plain JSON, the same rule
+     *  as `call`. */
+    waitFor<T>(condition: PageFunction<T> | string, options?: WaitOptions, ...args: unknown[]): Promise<NonNullable<T>>;
+    waitForSelector(selector: string, options?: WaitOptions): Promise<void>;
+    waitForText(needle: string, options?: WaitOptions): Promise<void>;
+    /** A waiting handle on the first element the matcher describes: a CSS
+     *  selector, or `name:` followed by a case-insensitive regex the
+     *  accessible name of a button must match (`aria-label` first, then its
+     *  text). Buttons that live behind accessible names and inputs addressed
+     *  by CSS hand back the same kind of handle, and every verb on it waits
+     *  before it acts. */
+    locator(matcher: string): Locator;
+    /** Whether anything matches, right now. */
+    exists(matcher: string): Promise<boolean>;
+    /** The words on the page, as a person reads them. */
+    words(): Promise<string>;
+    /** Wait until the element is there and enabled, click it once, answer
+     *  its words. For more than one verb on the same element, keep the
+     *  handle: `tab.locator(matcher)`. */
+    click(matcher: string, options?: WaitOptions): Promise<string>;
+    /** Type into a box the way its framework expects, after waiting for it
+     *  to be there. */
+    fill(matcher: string, value: string, options?: WaitOptions): Promise<void>;
+    /** The visible text of the first match, or undefined when there is none. */
+    text(selector: string): Promise<string | undefined>;
+    attr(selector: string, name: string): Promise<string | undefined>;
+    url(): Promise<string>;
+    screenshot(): Promise<Buffer>;
+    /** Make the page unable to tell headless from headed: `HeadlessChrome/`
+     *  in the user agent is a fingerprint conferencing apps read. The launch
+     *  flag keeps `navigator.webdriver` false NATIVELY — patching it with a
+     *  script is itself the tell (measured 2026-10-14: a defineProperty
+     *  getter on Navigator.prototype alone got us refused by Meet; the page
+     *  inspects the getter's source). The override carries the browser's
+     *  own client-hint metadata from `Browser.getVersion`, so the story the
+     *  page reads is self-consistent and none of it is invented. Answers
+     *  false when there was nothing to hide. */
+    hideHeadless(): Promise<boolean>;
+    /** Close the tab. The browser itself outlives it, so another tab can open
+     *  in a moment. */
+    close(): Promise<void>;
+}

package/dist/tab.js

@@ -0,0 +1,329 @@
+import { sleep } from './connection.js';
+const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
+const DEFAULT_WAIT_INTERVAL_MS = 120;
+function unwrap(answer) {
+    const details = answer.exceptionDetails;
+    if (details !== undefined) {
+        throw new Error(details.exception?.description ?? details.text ?? 'the page function threw');
+    }
+    return answer.result?.value;
+}
+function labelOf(condition) {
+    const source = typeof condition === 'string' ? condition : condition.toString();
+    return source.length > 120 ? `${source.slice(0, 120)}…` : source;
+}
+/** The package's one way to wait: look, and if not yet, look again after a
+ *  pause. CDP announces "the page loaded", never "this element finally
+ *  exists", so bounded re-looking is the honest mechanism. */
+async function poll(look, what, options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const intervalMs = options.intervalMs ?? DEFAULT_WAIT_INTERVAL_MS;
+    const deadline = Date.now() + timeoutMs;
+    do {
+        if (await look())
+            return;
+        await sleep(intervalMs);
+    } while (Date.now() < deadline);
+    throw new Error(`no ${what} within ${timeoutMs} ms`);
+}
+/** One page-side look: the first element the matcher describes. `name:`
+ *  matches a button's accessible name — `aria-label` first, then its text,
+ *  what real apps like Meet put on their buttons — as a case-insensitive
+ *  regex; anything else is a CSS selector. Answers the element's own words,
+ *  whether it can take a click, and (when asked for) one attribute. */
+const locate = (kind, matcher, attribute) => {
+    const words = (el) => (el.getAttribute('aria-label') || el.textContent || '').trim();
+    const live = (el) => !el.disabled && el.getAttribute('aria-disabled') !== 'true';
+    let el;
+    if (kind === 'name') {
+        const rx = new RegExp(matcher, 'i');
+        el = Array.from(document.querySelectorAll('button, [role="button"]')).find(e => rx.test(words(e)));
+    }
+    else {
+        el = document.querySelector(matcher) ?? undefined;
+    }
+    if (el === undefined)
+        return null;
+    return {
+        label: words(el) || el.tagName.toLowerCase(),
+        enabled: live(el),
+        attr: attribute === '' ? undefined : (el.getAttribute(attribute) ?? undefined),
+    };
+};
+/** Find the first element the matcher describes that is ENABLED, and click
+ *  it — one page-side move, no window between looking and touching where
+ *  the element could change its mind. Null when there was nothing to click
+ *  (absent, or there but disabled). */
+const clickLocated = (kind, matcher) => {
+    const words = (el) => (el.getAttribute('aria-label') || el.textContent || '').trim();
+    const live = (el) => !el.disabled && el.getAttribute('aria-disabled') !== 'true';
+    let el;
+    if (kind === 'name') {
+        const rx = new RegExp(matcher, 'i');
+        el = Array.from(document.querySelectorAll('button, [role="button"]')).find(e => rx.test(words(e)) && live(e));
+    }
+    else {
+        const found = document.querySelector(matcher);
+        if (found !== null && live(found))
+            el = found;
+    }
+    if (el === undefined)
+        return null;
+    el.click();
+    return words(el) || el.tagName.toLowerCase();
+};
+/** Type into a box the way its framework expects: set the value through the
+ *  native setter, then dispatch `input`. A plain `.value =` leaves
+ *  frameworks like Meet's convinced the box is still empty — proven on the
+ *  real waiting-room name box. */
+const fillLocated = (kind, matcher, value) => {
+    const el = kind === 'name'
+        ? Array.from(document.querySelectorAll('button, [role="button"]')).find(e => new RegExp(matcher, 'i').test((e.getAttribute('aria-label') || e.textContent || '').trim()))
+        : document.querySelector(matcher);
+    if (el === null || el === undefined)
+        return 'absent';
+    if (!(el instanceof HTMLInputElement))
+        return 'not-an-input';
+    const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
+    if (setter === undefined)
+        return 'not-an-input';
+    setter.call(el, value);
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+    return 'filled';
+};
+class LocatorHandle {
+    #tab;
+    matcher;
+    #kind;
+    #body;
+    constructor(tab, matcher) {
+        this.#tab = tab;
+        this.matcher = matcher;
+        this.#kind = matcher.startsWith('name:') ? 'name' : 'css';
+        this.#body = this.#kind === 'name' ? matcher.slice('name:'.length) : matcher;
+    }
+    async #probe(attribute = '') {
+        return this.#tab.call(locate, this.#kind, this.#body, attribute);
+    }
+    async exists() {
+        return (await this.#probe()) !== null;
+    }
+    async enabled() {
+        return (await this.#probe())?.enabled === true;
+    }
+    async attr(name) {
+        return (await this.#probe(name))?.attr;
+    }
+    async waitFor(options = {}) {
+        await poll(async () => (await this.#probe()) !== null, `element ${this.matcher}`, options);
+    }
+    async click(options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+        const intervalMs = options.intervalMs ?? DEFAULT_WAIT_INTERVAL_MS;
+        const deadline = Date.now() + timeoutMs;
+        do {
+            const hit = await this.#tab.call(clickLocated, this.#kind, this.#body);
+            if (hit !== null)
+                return hit;
+            await sleep(intervalMs);
+        } while (Date.now() < deadline);
+        const seen = await this.#probe();
+        throw new Error(seen === null
+            ? `no element matching ${this.matcher} within ${timeoutMs} ms`
+            : `${this.matcher} stayed disabled for ${timeoutMs} ms — the page never took it`);
+    }
+    async fill(value, options = {}) {
+        await this.waitFor(options);
+        const answer = await this.#tab.call(fillLocated, this.#kind, this.#body, value);
+        if (answer === 'absent')
+            throw new Error(`${this.matcher} vanished before the fill`);
+        if (answer === 'not-an-input')
+            throw new Error(`cannot fill ${this.matcher}: it is not an <input>`);
+    }
+}
+export class Tab {
+    #connection;
+    #targetId;
+    #sessionId;
+    #listeners = new Map();
+    #pageEnabled = false;
+    constructor(connection, targetId, sessionId) {
+        this.#connection = connection;
+        this.#targetId = targetId;
+        this.#sessionId = sessionId;
+    }
+    get targetId() {
+        return this.#targetId;
+    }
+    get sessionId() {
+        return this.#sessionId;
+    }
+    /** The escape hatch: any protocol command, addressed to this tab. */
+    send(method, params = {}) {
+        return this.#connection.send(method, params, this.#sessionId);
+    }
+    /** Listen for a protocol event of this tab. The listener sees only events
+     *  carrying our session id. */
+    on(event, listener) {
+        const wrapper = raw => {
+            const event = raw;
+            if (event.sessionId === this.#sessionId)
+                listener(event);
+        };
+        this.#listeners.set(listener, wrapper);
+        this.#connection.addEventListener(event, wrapper);
+        return this;
+    }
+    off(event, listener) {
+        const wrapper = this.#listeners.get(listener);
+        if (wrapper !== undefined) {
+            this.#connection.removeEventListener(event, wrapper);
+            this.#listeners.delete(listener);
+        }
+        return this;
+    }
+    #once(event, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const listener = (arrived) => {
+                this.off(event, listener);
+                clearTimeout(timer);
+                resolve(arrived);
+            };
+            const timer = setTimeout(() => {
+                this.off(event, listener);
+                reject(new Error(`no ${event} within ${timeoutMs} ms`));
+            }, timeoutMs);
+            this.on(event, listener);
+        });
+    }
+    /** Navigate and wait for the load event. Blank on arrival is normal for a
+     *  fresh tab: the caller installs its scripts first, then drives here. */
+    async goto(url, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        if (!this.#pageEnabled) {
+            await this.send('Page.enable');
+            this.#pageEnabled = true;
+        }
+        const loaded = this.#once('Page.loadEventFired', timeoutMs);
+        const answer = await this.send('Page.navigate', { url });
+        if (answer.errorText !== undefined) {
+            throw new Error(`navigation to ${url} failed: ${answer.errorText}`);
+        }
+        await loaded;
+    }
+    /** Run an expression in the page and take its value back. */
+    async evaluate(expression) {
+        return unwrap(await this.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }));
+    }
+    /** Run a function in the page and take its value back. A string is sent as
+     *  source, for text that was built elsewhere. Arguments travel as JSON —
+     *  the same rule as return values, so a page function truly cannot close
+     *  over anything or carry anything but plain data. `Runtime.evaluate` in a
+     *  wrapped expression is used instead of `callFunctionOn` because it works
+     *  from the first breath of a fresh tab, before any execution context is
+     *  announced. */
+    async call(fn, ...args) {
+        const source = typeof fn === 'string' ? fn : fn.toString();
+        const given = args.map(value => JSON.stringify(value) ?? 'undefined');
+        return unwrap(await this.send('Runtime.evaluate', {
+            expression: `(${source})(${given.join(', ')})`,
+            awaitPromise: true,
+            returnByValue: true,
+        }));
+    }
+    /** Poll until the condition answers truthy, and take that answer. CDP
+     *  reports "the page loaded", never "this element finally exists", so
+     *  polling is the honest mechanism — bounded, one-shot sleeps. Extra
+     *  arguments travel to the page function as plain JSON, the same rule
+     *  as `call`. */
+    async waitFor(condition, options = {}, ...args) {
+        return this.#wait(condition, args, options);
+    }
+    async waitForSelector(selector, options = {}) {
+        await this.#wait((sel) => document.querySelector(sel) !== null, [selector], options);
+    }
+    async waitForText(needle, options = {}) {
+        await this.#wait((text) => (document.body?.innerText ?? '').includes(text), [needle], options);
+    }
+    async #wait(condition, args, options) {
+        let answer;
+        await poll(async () => {
+            answer = await this.call(condition, ...args);
+            return Boolean(answer);
+        }, labelOf(condition), options);
+        return answer;
+    }
+    /** A waiting handle on the first element the matcher describes: a CSS
+     *  selector, or `name:` followed by a case-insensitive regex the
+     *  accessible name of a button must match (`aria-label` first, then its
+     *  text). Buttons that live behind accessible names and inputs addressed
+     *  by CSS hand back the same kind of handle, and every verb on it waits
+     *  before it acts. */
+    locator(matcher) {
+        return new LocatorHandle(this, matcher);
+    }
+    /** Whether anything matches, right now. */
+    async exists(matcher) {
+        return this.locator(matcher).exists();
+    }
+    /** The words on the page, as a person reads them. */
+    async words() {
+        return this.call(() => {
+            const body = document.body;
+            return body === null ? '' : body.innerText || body.textContent || '';
+        });
+    }
+    /** Wait until the element is there and enabled, click it once, answer
+     *  its words. For more than one verb on the same element, keep the
+     *  handle: `tab.locator(matcher)`. */
+    click(matcher, options = {}) {
+        return this.locator(matcher).click(options);
+    }
+    /** Type into a box the way its framework expects, after waiting for it
+     *  to be there. */
+    async fill(matcher, value, options = {}) {
+        await this.locator(matcher).fill(value, options);
+    }
+    /** The visible text of the first match, or undefined when there is none. */
+    async text(selector) {
+        return this.call((sel) => {
+            const el = document.querySelector(sel);
+            return el === null ? undefined : el.innerText;
+        }, selector);
+    }
+    async attr(selector, name) {
+        return this.call((sel, attribute) => document.querySelector(sel)?.getAttribute(attribute) ?? undefined, selector, name);
+    }
+    async url() {
+        return this.evaluate('location.href');
+    }
+    async screenshot() {
+        const { data } = await this.send('Page.captureScreenshot', { format: 'png' });
+        return Buffer.from(data, 'base64');
+    }
+    /** Make the page unable to tell headless from headed: `HeadlessChrome/`
+     *  in the user agent is a fingerprint conferencing apps read. The launch
+     *  flag keeps `navigator.webdriver` false NATIVELY — patching it with a
+     *  script is itself the tell (measured 2026-10-14: a defineProperty
+     *  getter on Navigator.prototype alone got us refused by Meet; the page
+     *  inspects the getter's source). The override carries the browser's
+     *  own client-hint metadata from `Browser.getVersion`, so the story the
+     *  page reads is self-consistent and none of it is invented. Answers
+     *  false when there was nothing to hide. */
+    async hideHeadless() {
+        const ua = await this.call(() => navigator.userAgent);
+        if (!ua.includes('HeadlessChrome/'))
+            return false;
+        const { userAgentMetadata } = (await this.send('Browser.getVersion'));
+        await this.send('Network.setUserAgentOverride', {
+            userAgent: ua.replace('HeadlessChrome/', 'Chrome/'),
+            ...(userAgentMetadata === undefined ? {} : { userAgentMetadata }),
+        });
+        return true;
+    }
+    /** Close the tab. The browser itself outlives it, so another tab can open
+     *  in a moment. */
+    async close() {
+        await this.#connection.send('Target.closeTarget', { targetId: this.#targetId });
+    }
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@aivi/chrome",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "description": "a puppeteer-shaped driver for an installed Chrome: a dozen page verbs over the DevTools Protocol, with the full protocol left reachable",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=26.1.0 <27"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aivi-hq/aivi.git",
+    "directory": "packages/chrome"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "tsc -b tsconfig.build.json"
+  }
+}