@rightkit/qa 0.3.2 → 0.4.0

package/README.md

@@ -22,3 +22,52 @@ Web/CDP harnesses launch Chrome for Testing, never regular Google Chrome: on mac
 - `launchChromeForTesting(options)` starts it in its own process group with a temp profile and returns `{ wsEndpoint, port, pid, profileDir, close() }`. Launch one browser per suite and open targets per test.
 - `close()` / `closeChromeGracefully()` sends CDP `Browser.close`, waits up to 5 s, sends SIGTERM to the process group (`taskkill /T` on Windows), waits again, sends SIGKILL only last, then removes the profile. It reports the step that ended the tree.
 - `codeSignCloneEntries()` lists the macOS clone entries so tests can assert that none appear.
+
+## Raw CDP page driver (Node 26)
+
+`QaBrowserSession`, `QaPage`, `QaElement`, `QaKeyboard` & `TimeoutError` are exported from `@rightkit/qa`. Transport uses Node's built-in `WebSocket` directly; no Puppeteer, Playwright, or CDP wrapper dependency.
+
+```ts
+import { launchChromeForTesting, QaBrowserSession } from '@rightkit/qa';
+
+const chrome = await launchChromeForTesting();
+const browser = await QaBrowserSession.connect(chrome.wsEndpoint);
+try {
+  const page = await browser.newPage();
+  await page.setViewport({ width: 1280, height: 720, deviceScaleFactor: 1 });
+  await page.evaluateOnNewDocument(() => { window.localStorage.setItem('qa', '1'); });
+  await page.goto('http://127.0.0.1:3000', { waitUntil: 'networkidle0', timeout: 10_000 });
+  const button = await page.waitForSelector('button', { visible: true });
+  await button?.click();
+  await button?.dispose();
+  await page.screenshot({ path: 'viewport.png', type: 'png', captureBeyondViewport: false });
+} finally {
+  try { await browser.close(); } finally { await chrome.close(); }
+}
+```
+
+Session owns targets it creates; launcher owns browser process & profile. `connect(endpoint, { timeout, debug })` defaults to 30,000 ms per connection/command, with logging off. Positive finite deadlines apply to navigation & waits; failures use typed `TimeoutError`. `page.on(cdpMethod, listener)` subscribes to page-session events & returns an unsubscribe function. Debug callbacks receive method names only. Throwing event subscribers are isolated from transport state.
+
+Evaluation uses main frame's default execution context, awaits promises & returns values by JSON. Functions run in Chrome, so pass external values as arguments rather than closing over Node variables. JavaScript exceptions become `Error` with Chrome's message. `evaluateOnNewDocument` accepts function + arguments or source text & runs before document scripts, including subsequent reloads.
+
+`goto`/`reload` support `load`, `domcontentloaded` & `networkidle0` (zero outstanding requests for 500 ms). `waitForSelector` supports present/visible/hidden states; hidden waits return `null`. `waitForFunction` supports animation-frame or positive millisecond polling & resolves when predicate is truthy. Both name selector/predicate in timeout errors. `$`/`$$` return remote element handles, released by `dispose()`, navigation, or page closure.
+
+Click/hover scroll elements into view & use box centres. Mouse, keyboard & text input use CDP `Input` commands; `select` dispatches DOM `input`/`change` after selecting values. Keyboard supports required navigation/editing keys, letters/digits & modifier chords such as `Control+A`, `Meta+A`, or `Shift+ArrowLeft`. Screenshots return `Buffer`, optionally write `path`, & capture viewport PNG at configured DPR; `fullPage` & `captureBeyondViewport` support `false` only.
+
+| Puppeteer | QaPage equivalent |
+|---|---|
+| `puppeteer.connect({ browserWSEndpoint })` | `QaBrowserSession.connect(wsEndpoint)` |
+| `browser.newPage()` / `browser.close()` | Same calls; session closes owned targets |
+| `page.goto()` / `reload()` / `close()` | Same calls & navigation options |
+| `page.setViewport()` | Same call; CDP device metrics |
+| `page.evaluateOnNewDocument()` | Same call; function or source |
+| `page.evaluate()` / `$eval()` / `$$eval()` | Same calls; JSON results & awaited promises |
+| `page.waitForSelector()` | Same options; `QaElement` or `null` |
+| `page.waitForFunction()` | Same predicate/options/arguments; returns `void` |
+| `page.$()` / `page.$$()` | `QaElement` / `QaElement[]` |
+| `element.click/type/hover/focus/boundingBox/evaluate/dispose()` | Same calls on `QaElement` |
+| `page.click/type/hover/focus/select()` | Same calls; click accepts selector or handle |
+| `page.keyboard.press()` | Same call; named key or modifier chord |
+| `page.screenshot()` | Viewport PNG `Buffer`; optional `path` |
+
+`pnpm --dir packages/qa test` runs mock-WebSocket unit tests & real Chrome for Testing integration against local static fixture. Install Chrome through `@rightkit/qa-chrome` or set `RIGHTKIT_CHROME_FOR_TESTING`; integration requires Chrome & does not silently skip.

package/dist/cdp.d.ts

@@ -0,0 +1,32 @@
+/** Minimal flattened-session CDP transport using Node's built-in WebSocket. */
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+export interface QaConnectOptions {
+    /** Default 30 seconds; applies to connection & each CDP command. */
+    timeout?: number;
+    /** Off by default. Receives method names only, never evaluated source or input text. */
+    debug?: (message: string) => void;
+}
+export type CdpParams = Record<string, any>;
+type Listener = (params: CdpParams) => void;
+/** @internal All operations use finite deadlines. */
+export declare function validateTimeout(timeout: number): number;
+export declare class CdpClient {
+    private socket;
+    readonly timeout: number;
+    private debug?;
+    private nextId;
+    private pending;
+    private listeners;
+    private closed?;
+    private constructor();
+    static connect(endpoint: string, options?: QaConnectOptions): Promise<CdpClient>;
+    send(method: string, params?: CdpParams, session?: string, timeout?: number): Promise<CdpParams>;
+    on(method: string, listener: Listener, session?: string): () => void;
+    private emit;
+    rejectSession(session: string, error: Error): void;
+    private fail;
+    close(): void;
+}
+export {};

package/dist/cdp.js

@@ -0,0 +1,141 @@
+/** Minimal flattened-session CDP transport using Node's built-in WebSocket. */
+export class TimeoutError extends Error {
+    constructor(message) { super(message); this.name = 'TimeoutError'; }
+}
+/** @internal All operations use finite deadlines. */
+export function validateTimeout(timeout) {
+    if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 2_147_483_647)
+        throw new Error('Timeout must be a positive finite number below 2147483648ms');
+    return timeout;
+}
+export class CdpClient {
+    socket;
+    timeout;
+    debug;
+    nextId = 0;
+    pending = new Map();
+    listeners = new Map();
+    closed;
+    constructor(socket, timeout, debug) {
+        this.socket = socket;
+        this.timeout = timeout;
+        this.debug = debug;
+        socket.addEventListener('message', (event) => {
+            let message;
+            try {
+                message = JSON.parse(String(event.data));
+            }
+            catch (error) {
+                this.fail(new Error(`Invalid CDP message: ${String(error)}`));
+                this.socket.close();
+                return;
+            }
+            if (message.id !== undefined) {
+                const pending = this.pending.get(message.id);
+                if (!pending)
+                    return;
+                this.pending.delete(message.id);
+                clearTimeout(pending.timer);
+                if (message.error)
+                    pending.reject(new Error(`CDP: ${message.error.message}`));
+                else
+                    pending.resolve(message.result ?? {});
+            }
+            else if (message.method) {
+                this.emit(message.method, message.params ?? {}, message.sessionId);
+            }
+        });
+        socket.addEventListener('close', () => this.fail(new Error('CDP socket closed')));
+        socket.addEventListener('error', () => this.fail(new Error('CDP socket error')));
+    }
+    static async connect(endpoint, options = {}) {
+        const timeout = validateTimeout(options.timeout ?? 30_000);
+        const socket = new WebSocket(endpoint);
+        const client = new CdpClient(socket, timeout, options.debug);
+        await new Promise((resolve, reject) => {
+            const done = (error) => {
+                clearTimeout(timer);
+                socket.removeEventListener('open', open);
+                socket.removeEventListener('error', errorHandler);
+                socket.removeEventListener('close', close);
+                if (error) {
+                    client.close();
+                    reject(error);
+                }
+                else
+                    resolve();
+            };
+            const open = () => done();
+            const errorHandler = () => done(new Error('CDP connection failed'));
+            const close = () => done(new Error('CDP socket closed while connecting'));
+            const timer = setTimeout(() => done(new TimeoutError(`CDP connect timed out after ${timeout}ms`)), timeout);
+            socket.addEventListener('open', open);
+            socket.addEventListener('error', errorHandler);
+            socket.addEventListener('close', close);
+        });
+        return client;
+    }
+    send(method, params = {}, session, timeout = this.timeout) {
+        if (this.closed)
+            return Promise.reject(this.closed);
+        validateTimeout(timeout);
+        this.debug?.(`CDP ${method}`);
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new TimeoutError(`${method} timed out after ${timeout}ms`));
+            }, timeout);
+            this.pending.set(id, { resolve, reject, timer, session });
+            try {
+                this.socket.send(JSON.stringify({ id, method, params, ...(session ? { sessionId: session } : {}) }));
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(error);
+            }
+        });
+    }
+    on(method, listener, session) {
+        const key = `${session ?? ''}:${method}`;
+        let listeners = this.listeners.get(key);
+        if (!listeners)
+            this.listeners.set(key, listeners = new Set());
+        listeners.add(listener);
+        return () => { listeners.delete(listener); if (!listeners.size)
+            this.listeners.delete(key); };
+    }
+    emit(method, params, session) {
+        for (const listener of [...(this.listeners.get(`${session ?? ''}:${method}`) ?? [])]) {
+            // A user subscription cannot corrupt transport state or suppress internal listeners.
+            try {
+                listener(params);
+            }
+            catch {
+                this.debug?.(`CDP listener failed: ${method}`);
+            }
+        }
+    }
+    rejectSession(session, error) {
+        for (const [id, pending] of this.pending)
+            if (pending.session === session) {
+                clearTimeout(pending.timer);
+                this.pending.delete(id);
+                pending.reject(error);
+            }
+    }
+    fail(error) {
+        if (this.closed)
+            return;
+        this.closed = error;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+        this.emit('Disconnected', { error });
+        this.listeners.clear();
+    }
+    close() { this.fail(new Error('CDP socket closed')); this.socket.close(); }
+}

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './panes.js';
 export * from './process.js';
 export * from './workspace.js';
 export * from './storage.js';
+export * from './page.js';

package/dist/index.js

@@ -9,3 +9,4 @@ export * from './panes.js';
 export * from './process.js';
 export * from './workspace.js';
 export * from './storage.js';
+export * from './page.js';

package/dist/keyboard.d.ts

@@ -0,0 +1,9 @@
+import type { CdpParams } from './cdp.js';
+export declare const modifierBits: Record<string, number>;
+export declare function keyDefinition(key: string, modifiers: number): CdpParams;
+export declare class QaKeyboard {
+    private send;
+    constructor(send: (method: string, params: CdpParams) => Promise<CdpParams>);
+    /** Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft. */
+    press(chord: string): Promise<void>;
+}

package/dist/keyboard.js

@@ -0,0 +1,79 @@
+const special = {
+    Escape: ['Escape', 27], Enter: ['Enter', 13, '\r'], Tab: ['Tab', 9],
+    ArrowLeft: ['ArrowLeft', 37], ArrowUp: ['ArrowUp', 38], ArrowRight: ['ArrowRight', 39], ArrowDown: ['ArrowDown', 40],
+    Backspace: ['Backspace', 8], Delete: ['Delete', 46], Home: ['Home', 36], End: ['End', 35],
+    PageUp: ['PageUp', 33], PageDown: ['PageDown', 34], Space: ['Space', 32, ' '],
+    Shift: ['ShiftLeft', 16], Control: ['ControlLeft', 17], Alt: ['AltLeft', 18], Meta: ['MetaLeft', 91],
+};
+export const modifierBits = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+export function keyDefinition(key, modifiers) {
+    const named = special[key];
+    let code, windowsVirtualKeyCode, text;
+    if (named)
+        [code, windowsVirtualKeyCode, text] = named;
+    else if (/^[a-z]$/i.test(key)) {
+        code = `Key${key.toUpperCase()}`;
+        windowsVirtualKeyCode = key.toUpperCase().charCodeAt(0);
+        key = modifiers & 8 ? key.toUpperCase() : modifiers & 7 ? key.toLowerCase() : key;
+        text = key;
+    }
+    else if (/^[0-9]$/.test(key)) {
+        code = `Digit${key}`;
+        windowsVirtualKeyCode = key.charCodeAt(0);
+        key = modifiers & 8 ? ')!@#$%^&*('[Number(key)] : key;
+        text = key;
+    }
+    else if (key === ' ') {
+        code = 'Space';
+        windowsVirtualKeyCode = 32;
+        text = ' ';
+    }
+    else
+        throw new Error(`Unsupported key: ${key}`);
+    if (key === 'Space')
+        key = ' ';
+    if (modifiers & (1 | 2 | 4))
+        text = undefined;
+    const unmodifiedText = code.startsWith('Key') ? code.slice(3).toLowerCase() : code.startsWith('Digit') ? code.slice(5) : text;
+    return { key, code, windowsVirtualKeyCode, modifiers, ...(text ? { text, unmodifiedText } : {}) };
+}
+export class QaKeyboard {
+    send;
+    constructor(send) {
+        this.send = send;
+    }
+    /** Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft. */
+    async press(chord) {
+        const parts = chord.split('+');
+        if (parts.some((part, i) => i < parts.length - 1 && !modifierBits[part]))
+            throw new Error(`Invalid key chord: ${chord}`);
+        keyDefinition(parts.at(-1), 0); // Validate before holding any modifier.
+        let modifiers = 0;
+        const held = [];
+        let failure;
+        try {
+            for (const part of parts) {
+                modifiers |= modifierBits[part] ?? 0;
+                const definition = keyDefinition(part, modifiers);
+                await this.send('Input.dispatchKeyEvent', { type: definition.text ? 'keyDown' : 'rawKeyDown', ...definition });
+                held.push(part);
+            }
+        }
+        catch (error) {
+            failure = error;
+        }
+        finally {
+            for (const part of held.reverse()) {
+                modifiers &= ~(modifierBits[part] ?? 0);
+                try {
+                    await this.send('Input.dispatchKeyEvent', { type: 'keyUp', ...keyDefinition(part, modifiers), text: undefined, unmodifiedText: undefined });
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+            }
+        }
+        if (failure)
+            throw failure;
+    }
+}

package/dist/page.d.ts

@@ -0,0 +1,143 @@
+import { CdpClient, type CdpParams, type QaConnectOptions } from './cdp.js';
+import { QaKeyboard } from './keyboard.js';
+export { TimeoutError, type QaConnectOptions } from './cdp.js';
+export { QaKeyboard } from './keyboard.js';
+export interface NavigationOptions {
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0';
+    timeout?: number;
+}
+export interface ViewportOptions {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+    mobile?: boolean;
+}
+export interface WaitOptions {
+    timeout?: number;
+    polling?: 'raf' | number;
+}
+export interface SelectorWaitOptions {
+    visible?: boolean;
+    hidden?: boolean;
+    timeout?: number;
+}
+export interface ClickOptions {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+    delay?: number;
+}
+export interface TypeOptions {
+    delay?: number;
+}
+export interface ScreenshotOptions {
+    path?: string;
+    type?: 'png';
+    captureBeyondViewport?: false;
+    fullPage?: false;
+}
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type PageFunction<Args extends unknown[], Result> = (...args: Args) => Result;
+/** Owns only targets it creates; launcher owns browser process & profile cleanup. */
+export declare class QaBrowserSession {
+    private client;
+    private pages;
+    private closed;
+    private closing?;
+    private opening;
+    private constructor();
+    static connect(wsEndpoint: string, options?: QaConnectOptions): Promise<QaBrowserSession>;
+    newPage(): Promise<QaPage>;
+    private createPage;
+    close(): Promise<void>;
+}
+export declare class QaPage {
+    private client;
+    readonly targetId: string;
+    private sessionId;
+    private onClosed;
+    readonly keyboard: QaKeyboard;
+    private frameId?;
+    private contexts;
+    private contextId?;
+    private handles;
+    private unsubs;
+    private subscriptions;
+    private closed?;
+    private closing?;
+    private closedListeners;
+    private requests;
+    private frameParents;
+    private lastNetworkActivity;
+    private generation;
+    private navigating;
+    private get objectGroup();
+    /** @internal Use QaBrowserSession.newPage(). */
+    constructor(client: CdpClient, targetId: string, sessionId: string, onClosed: () => void);
+    private chooseContext;
+    /** Subscribe to this page's raw CDP events; returned function unsubscribes. */
+    on(method: string, listener: (params: CdpParams) => void): () => void;
+    /** @internal */
+    initialize(): Promise<void>;
+    /** @internal */
+    send(method: string, params?: CdpParams, timeout?: number): Promise<CdpParams>;
+    private invalidateHandles;
+    /** @internal */
+    markClosed(error?: Error): void;
+    close(): Promise<void>;
+    private bounded;
+    private mainContext;
+    private navigate;
+    goto(url: string, options?: NavigationOptions): Promise<void>;
+    reload(options?: NavigationOptions): Promise<void>;
+    setViewport(options: ViewportOptions): Promise<void>;
+    evaluateOnNewDocument<Args extends unknown[]>(fn: PageFunction<Args, unknown> | string, ...args: Args): Promise<void>;
+    private run;
+    evaluate<Args extends unknown[], Result>(fn: PageFunction<Args, Result> | string, ...args: Args): Promise<Awaited<Result>>;
+    /** @internal */
+    callElement<Args extends unknown[], Result>(handle: QaElement, fn: (element: HTMLElement, ...args: Args) => Result, args: Args): Promise<Awaited<Result>>;
+    private handle;
+    $(selector: string): Promise<QaElement | null>;
+    private lookup;
+    $$(selector: string): Promise<QaElement[]>;
+    $eval<Args extends unknown[], Result>(selector: string, fn: (element: HTMLElement, ...args: Args) => Result, ...args: Args): Promise<Awaited<Result>>;
+    $$eval<Args extends unknown[], Result>(selector: string, fn: (elements: HTMLElement[], ...args: Args) => Result, ...args: Args): Promise<Awaited<Result>>;
+    private runSourceFunction;
+    waitForFunction<Args extends unknown[]>(fn: PageFunction<Args, unknown> | string, options?: WaitOptions, ...args: Args): Promise<void>;
+    waitForSelector(selector: string, options?: SelectorWaitOptions): Promise<QaElement | null>;
+    private requireElement;
+    private withElement;
+    private point;
+    click(target: string | QaElement, options?: ClickOptions): Promise<void>;
+    type(selector: string, text: string, options?: TypeOptions): Promise<void>;
+    /** @internal */
+    typeElement(handle: QaElement, text: string, options?: TypeOptions): Promise<void>;
+    hover(target: string | QaElement): Promise<void>;
+    focus(target: string | QaElement): Promise<void>;
+    select(selector: string, ...values: string[]): Promise<string[]>;
+    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+}
+/** Remote DOM reference; dispose explicitly or let navigation release its object group. */
+export declare class QaElement {
+    private page;
+    readonly objectId: string;
+    private onDisposed;
+    private disposed;
+    /** @internal */
+    constructor(page: QaPage, objectId: string, onDisposed: () => void);
+    /** @internal */
+    assertUsable(page: QaPage): void;
+    /** @internal */
+    invalidate(): void;
+    dispose(): Promise<void>;
+    evaluate<Args extends unknown[], Result>(fn: (element: HTMLElement, ...args: Args) => Result, ...args: Args): Promise<Awaited<Result>>;
+    click(options?: ClickOptions): Promise<void>;
+    type(text: string, options?: TypeOptions): Promise<void>;
+    hover(): Promise<void>;
+    focus(): Promise<void>;
+    boundingBox(): Promise<BoundingBox | null>;
+}

package/dist/page.js

@@ -0,0 +1,573 @@
+import { writeFile } from 'node:fs/promises';
+import { CdpClient, TimeoutError, validateTimeout } from './cdp.js';
+import { QaKeyboard } from './keyboard.js';
+export { TimeoutError } from './cdp.js';
+export { QaKeyboard } from './keyboard.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function functionSource(fn) {
+    const source = fn.toString();
+    if (source.includes('[native code]'))
+        throw new Error('Cannot evaluate native function');
+    // Parse only (never execute) to distinguish methods from async arrow functions.
+    try {
+        new Function(`return (${source}\n)`);
+    }
+    catch {
+        const declaration = source.startsWith('async ') ? source.replace(/^async\s+/, 'async function ') : `function ${source}`;
+        new Function(`return (${declaration}\n)`);
+        return declaration;
+    }
+    return source;
+}
+function argument(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value === 'number' && (!Number.isFinite(value) || Object.is(value, -0)))
+        return { unserializableValue: Object.is(value, -0) ? '-0' : String(value) };
+    if (typeof value === 'bigint')
+        return { unserializableValue: `${value}n` };
+    return { value };
+}
+function resultValue(result) {
+    if (result.exceptionDetails) {
+        throw new Error(result.exceptionDetails.exception?.description ?? result.exceptionDetails.exception?.value ?? result.exceptionDetails.text ?? 'JavaScript evaluation failed');
+    }
+    return result.result?.value;
+}
+/** Owns only targets it creates; launcher owns browser process & profile cleanup. */
+export class QaBrowserSession {
+    client;
+    pages = new Set();
+    closed = false;
+    closing;
+    opening = new Set();
+    constructor(client) {
+        this.client = client;
+    }
+    static async connect(wsEndpoint, options = {}) {
+        return new QaBrowserSession(await CdpClient.connect(wsEndpoint, options));
+    }
+    newPage() {
+        if (this.closed)
+            return Promise.reject(new Error('Browser session closed'));
+        const pending = this.createPage();
+        this.opening.add(pending);
+        void pending.then(() => this.opening.delete(pending), () => this.opening.delete(pending));
+        return pending;
+    }
+    async createPage() {
+        const { targetId } = await this.client.send('Target.createTarget', { url: 'about:blank' });
+        try {
+            const { sessionId } = await this.client.send('Target.attachToTarget', { targetId, flatten: true });
+            const page = new QaPage(this.client, targetId, sessionId, () => this.pages.delete(page));
+            this.pages.add(page);
+            await page.initialize();
+            if (this.closed)
+                throw new Error('Browser session closed');
+            return page;
+        }
+        catch (error) {
+            await this.client.send('Target.closeTarget', { targetId }).catch(() => { });
+            for (const page of this.pages)
+                if (page.targetId === targetId)
+                    page.markClosed();
+            throw error;
+        }
+    }
+    close() {
+        if (this.closing)
+            return this.closing;
+        this.closed = true;
+        this.closing = (async () => {
+            try {
+                await Promise.allSettled([...this.opening]);
+                const results = await Promise.allSettled([...this.pages].map((page) => page.close()));
+                const failed = results.find((result) => result.status === 'rejected');
+                if (failed?.status === 'rejected')
+                    throw failed.reason;
+            }
+            finally {
+                this.client.close();
+            }
+        })();
+        return this.closing;
+    }
+}
+export class QaPage {
+    client;
+    targetId;
+    sessionId;
+    onClosed;
+    keyboard;
+    frameId;
+    contexts = new Map();
+    contextId;
+    handles = new Set();
+    unsubs = [];
+    subscriptions = new Set();
+    closed;
+    closing;
+    closedListeners = new Set();
+    requests = new Map();
+    frameParents = new Map();
+    lastNetworkActivity = 0;
+    generation = 0;
+    navigating = false;
+    get objectGroup() { return `qa-elements-${this.generation}`; }
+    /** @internal Use QaBrowserSession.newPage(). */
+    constructor(client, targetId, sessionId, onClosed) {
+        this.client = client;
+        this.targetId = targetId;
+        this.sessionId = sessionId;
+        this.onClosed = onClosed;
+        this.keyboard = new QaKeyboard((method, params) => this.send(method, params));
+        this.unsubs.push(this.on('Runtime.executionContextCreated', ({ context }) => { this.contexts.set(context.id, context); this.chooseContext(); }), this.on('Runtime.executionContextDestroyed', ({ executionContextId }) => {
+            this.contexts.delete(executionContextId);
+            if (executionContextId === this.contextId) {
+                this.invalidateHandles();
+                this.chooseContext();
+            }
+        }), this.on('Runtime.executionContextsCleared', () => { this.contexts.clear(); this.contextId = undefined; this.invalidateHandles(); }), this.on('Page.frameNavigated', ({ frame }) => {
+            if (frame.parentId)
+                this.frameParents.set(frame.id, frame.parentId);
+            else {
+                this.frameId = frame.id;
+                this.frameParents.clear();
+                this.invalidateHandles();
+                this.chooseContext();
+            }
+            // Chrome can abandon old-document favicon/fetch requests without a terminal event.
+            // New document requests have already started by frameNavigated; preserve that loader.
+            for (const [id, request] of this.requests) {
+                if ((!frame.parentId || request.frameId === frame.id) && request.loaderId !== frame.loaderId)
+                    this.requests.delete(id);
+            }
+        }), this.on('Page.frameAttached', ({ frameId, parentFrameId }) => this.frameParents.set(frameId, parentFrameId)), this.on('Page.frameDetached', ({ frameId, reason }) => {
+            if (reason === 'swap')
+                return;
+            const removed = new Set([frameId]);
+            for (const id of removed)
+                for (const [child, parent] of this.frameParents)
+                    if (parent === id)
+                        removed.add(child);
+            for (const id of removed)
+                this.frameParents.delete(id);
+            for (const [id, request] of this.requests)
+                if (request.frameId && removed.has(request.frameId))
+                    this.requests.delete(id);
+        }), this.on('Network.requestWillBeSent', ({ requestId, frameId, loaderId }) => { this.requests.set(requestId, { frameId, loaderId }); this.lastNetworkActivity = Date.now(); }), this.on('Network.loadingFinished', ({ requestId }) => { this.requests.delete(requestId); this.lastNetworkActivity = Date.now(); }), this.on('Network.loadingFailed', ({ requestId }) => { this.requests.delete(requestId); this.lastNetworkActivity = Date.now(); }), client.on('Disconnected', ({ error }) => this.markClosed(error)), client.on('Target.detachedFromTarget', ({ sessionId }) => { if (sessionId === this.sessionId)
+            this.markClosed(); }), this.on('Inspector.detached', () => this.markClosed()));
+    }
+    chooseContext() {
+        this.contextId = [...this.contexts.values()].reverse().find((context) => context.auxData?.isDefault && context.auxData.frameId === this.frameId)?.id;
+    }
+    /** Subscribe to this page's raw CDP events; returned function unsubscribes. */
+    on(method, listener) {
+        if (this.closed)
+            throw this.closed;
+        const off = this.client.on(method, listener, this.sessionId);
+        const unsubscribe = () => { off(); this.subscriptions.delete(unsubscribe); };
+        this.subscriptions.add(unsubscribe);
+        return unsubscribe;
+    }
+    /** @internal */
+    async initialize() {
+        await this.send('Page.enable');
+        const { frameTree } = await this.send('Page.getFrameTree');
+        this.frameId = frameTree.frame.id;
+        this.chooseContext();
+        await this.send('Runtime.enable');
+        await this.send('Network.enable');
+        await this.send('Page.setLifecycleEventsEnabled', { enabled: true });
+    }
+    /** @internal */
+    send(method, params = {}, timeout) {
+        if (this.closed)
+            return Promise.reject(this.closed);
+        return this.client.send(method, params, this.sessionId, timeout);
+    }
+    invalidateHandles() {
+        const objectGroup = this.objectGroup;
+        this.generation++;
+        for (const handle of this.handles)
+            handle.invalidate();
+        this.handles.clear();
+        // Navigation destroys the context; explicitly release any surviving remote references.
+        if (!this.closed)
+            void this.send('Runtime.releaseObjectGroup', { objectGroup }).catch(() => { });
+    }
+    /** @internal */
+    markClosed(error = new Error('Page closed')) {
+        if (this.closed)
+            return;
+        this.closed = error;
+        this.invalidateHandles();
+        this.client.rejectSession(this.sessionId, error);
+        for (const unsubscribe of this.unsubs.splice(0))
+            unsubscribe();
+        for (const unsubscribe of this.subscriptions)
+            unsubscribe();
+        for (const listener of this.closedListeners)
+            listener(error);
+        this.closedListeners.clear();
+        this.onClosed();
+    }
+    close() {
+        if (this.closing)
+            return this.closing;
+        if (this.closed)
+            return Promise.resolve();
+        this.closing = (async () => {
+            try {
+                await this.client.send('Target.closeTarget', { targetId: this.targetId });
+            }
+            finally {
+                this.markClosed();
+            }
+        })();
+        return this.closing;
+    }
+    bounded(label, timeout, work) {
+        if (this.closed)
+            return Promise.reject(this.closed);
+        validateTimeout(timeout);
+        const deadline = Date.now() + timeout;
+        let stopped = false;
+        return new Promise((resolve, reject) => {
+            const finish = (error, value) => {
+                if (stopped)
+                    return;
+                stopped = true;
+                clearTimeout(timer);
+                this.closedListeners.delete(onClose);
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const onClose = (error) => finish(error);
+            this.closedListeners.add(onClose);
+            const timer = setTimeout(() => finish(new TimeoutError(`${label} timed out after ${timeout}ms`)), timeout);
+            work(() => Math.max(1, deadline - Date.now()), () => stopped).then((value) => finish(undefined, value), (error) => finish(error));
+        });
+    }
+    async mainContext(timeout = this.client.timeout) {
+        return this.bounded('Main execution context', timeout, async (_remaining, stopped) => {
+            while (this.contextId === undefined) {
+                if (stopped())
+                    throw new Error('Context wait cancelled');
+                await sleep(10);
+            }
+            return this.contextId;
+        });
+    }
+    async navigate(method, params, options) {
+        if (this.navigating)
+            throw new Error('Navigation already in progress');
+        const waitUntil = options.waitUntil ?? 'load';
+        if (!['load', 'domcontentloaded', 'networkidle0'].includes(waitUntil))
+            throw new Error(`Unsupported waitUntil: ${waitUntil}`);
+        const timeout = validateTimeout(options.timeout ?? this.client.timeout);
+        this.navigating = true;
+        const events = [];
+        let sameDocument = false;
+        let loaderId;
+        const off = this.on('Page.lifecycleEvent', (event) => events.push(event));
+        const offSame = this.on('Page.navigatedWithinDocument', ({ frameId }) => { if (frameId === this.frameId)
+            sameDocument = true; });
+        try {
+            await this.bounded(`Navigation (${waitUntil})`, timeout, async (remaining, stopped) => {
+                const response = await this.send(method, params, remaining());
+                if (response.errorText)
+                    throw new Error(`Navigation failed: ${response.errorText}`);
+                loaderId = response.loaderId;
+                if (method === 'Page.navigate' && !loaderId)
+                    sameDocument = true;
+                let idleSince;
+                while (!stopped()) {
+                    const name = waitUntil === 'domcontentloaded' ? 'DOMContentLoaded' : 'load';
+                    // Reload's loader is learned from init, never a previous document's load event.
+                    if (!loaderId && !sameDocument)
+                        loaderId = events.find((event) => event.frameId === this.frameId && event.name === 'init')?.loaderId;
+                    const ready = sameDocument || events.some((event) => event.frameId === this.frameId && event.loaderId === loaderId && event.name === name);
+                    if (ready && waitUntil !== 'networkidle0')
+                        return;
+                    const committed = sameDocument || !!loaderId;
+                    if (waitUntil === 'networkidle0' && committed && !this.requests.size) {
+                        idleSince = Math.max(idleSince ?? Date.now(), this.lastNetworkActivity);
+                        if (Date.now() - idleSince >= 500)
+                            return;
+                    }
+                    else
+                        idleSince = undefined;
+                    await sleep(Math.min(20, remaining()));
+                }
+            });
+        }
+        finally {
+            off();
+            offSame();
+            this.navigating = false;
+        }
+    }
+    goto(url, options = {}) { return this.navigate('Page.navigate', { url }, options); }
+    reload(options = {}) { return this.navigate('Page.reload', {}, options); }
+    async setViewport(options) {
+        await this.send('Emulation.setDeviceMetricsOverride', { ...options, deviceScaleFactor: options.deviceScaleFactor ?? 1, mobile: options.mobile ?? false });
+    }
+    async evaluateOnNewDocument(fn, ...args) {
+        const source = typeof fn === 'string' ? fn : `(${functionSource(fn)})(...${JSON.stringify(args)})`;
+        await this.send('Page.addScriptToEvaluateOnNewDocument', { source });
+    }
+    async run(fn, args, returnByValue, timeout = this.client.timeout) {
+        const deadline = Date.now() + timeout;
+        const contextId = await this.mainContext(timeout);
+        timeout = Math.max(1, deadline - Date.now());
+        const common = { returnByValue, awaitPromise: true, objectGroup: this.objectGroup, timeout };
+        const result = typeof fn === 'string'
+            ? await this.send('Runtime.evaluate', { expression: fn, contextId, ...common }, timeout)
+            : await this.send('Runtime.callFunctionOn', { functionDeclaration: functionSource(fn), executionContextId: contextId, arguments: args.map(argument), ...common }, timeout);
+        resultValue(result);
+        return result;
+    }
+    async evaluate(fn, ...args) {
+        return resultValue(await this.run(fn, args, true));
+    }
+    /** @internal */
+    async callElement(handle, fn, args) {
+        handle.assertUsable(this);
+        const result = await this.send('Runtime.callFunctionOn', {
+            objectId: handle.objectId, functionDeclaration: `function(...args) { return (${functionSource(fn)})(this, ...args); }`,
+            arguments: args.map(argument), returnByValue: true, awaitPromise: true,
+        });
+        return resultValue(result);
+    }
+    handle(objectId) {
+        const handle = new QaElement(this, objectId, () => this.handles.delete(handle));
+        this.handles.add(handle);
+        return handle;
+    }
+    async $(selector) {
+        return this.lookup(selector);
+    }
+    async lookup(selector, timeout = this.client.timeout) {
+        const generation = this.generation;
+        const { result } = await this.run((selector) => document.querySelector(selector), [selector], false, timeout);
+        if (generation !== this.generation)
+            throw new Error('Element lookup interrupted by navigation');
+        return result.objectId ? this.handle(result.objectId) : null;
+    }
+    async $$(selector) {
+        const generation = this.generation;
+        const { result } = await this.run((selector) => Array.from(document.querySelectorAll(selector)), [selector], false);
+        if (!result.objectId)
+            return [];
+        try {
+            const { result: properties } = await this.send('Runtime.getProperties', { objectId: result.objectId, ownProperties: true });
+            if (generation !== this.generation)
+                throw new Error('Element lookup interrupted by navigation');
+            return properties.filter((property) => /^\d+$/.test(property.name) && property.value?.objectId).map((property) => this.handle(property.value.objectId));
+        }
+        finally {
+            await this.send('Runtime.releaseObject', { objectId: result.objectId }).catch(() => { });
+        }
+    }
+    async $eval(selector, fn, ...args) {
+        const handle = await this.requireElement(selector);
+        try {
+            return await handle.evaluate(fn, ...args);
+        }
+        finally {
+            await handle.dispose();
+        }
+    }
+    async $$eval(selector, fn, ...args) {
+        const source = `function(selector, ...args) { return (${functionSource(fn)})(Array.from(document.querySelectorAll(selector)), ...args); }`;
+        return resultValue(await this.runSourceFunction(source, [selector, ...args]));
+    }
+    async runSourceFunction(source, args, timeout = this.client.timeout) {
+        const deadline = Date.now() + timeout;
+        const executionContextId = await this.mainContext(timeout);
+        timeout = Math.max(1, deadline - Date.now());
+        const result = await this.send('Runtime.callFunctionOn', { functionDeclaration: source, executionContextId, arguments: args.map(argument), returnByValue: true, awaitPromise: true, timeout }, timeout);
+        resultValue(result);
+        return result;
+    }
+    async waitForFunction(fn, options = {}, ...args) {
+        const polling = options.polling ?? 'raf';
+        if (typeof polling === 'number' && (!(polling > 0) || !Number.isFinite(polling)))
+            throw new Error('Polling interval must be positive');
+        const source = typeof fn === 'string' ? `function() { return (${fn}); }` : functionSource(fn);
+        await this.bounded(`Predicate ${source}`, options.timeout ?? this.client.timeout, async (remaining, stopped) => {
+            while (!stopped()) {
+                try {
+                    if (resultValue(await this.runSourceFunction(source, args, remaining())))
+                        return;
+                    if (polling === 'raf') {
+                        // A browser animation frame, bounded fallback for background targets.
+                        await this.runSourceFunction('function() { return new Promise(resolve => { const timer = setTimeout(resolve, 100); requestAnimationFrame(() => { clearTimeout(timer); resolve(); }); }); }', [], remaining());
+                    }
+                    else
+                        await sleep(Math.min(polling, remaining()));
+                }
+                catch (error) {
+                    if (error instanceof TimeoutError) {
+                        await sleep(remaining());
+                        continue;
+                    }
+                    if (!/context.*(destroyed|not found)|Cannot find context/i.test(String(error)))
+                        throw error;
+                    await sleep(Math.min(10, remaining()));
+                }
+            }
+        });
+    }
+    async waitForSelector(selector, options = {}) {
+        if (options.visible && options.hidden)
+            throw new Error('visible & hidden cannot both be true');
+        try {
+            return await this.bounded(`Selector ${selector}`, options.timeout ?? this.client.timeout, async (remaining) => {
+                await this.waitForFunction((selector, visible, hidden) => {
+                    const element = document.querySelector(selector);
+                    if (!element)
+                        return hidden;
+                    const style = getComputedStyle(element), box = element.getBoundingClientRect();
+                    const shown = style.visibility !== 'hidden' && style.visibility !== 'collapse' && box.width > 0 && box.height > 0;
+                    return hidden ? !shown : visible ? shown : true;
+                }, { timeout: remaining() }, selector, !!options.visible, !!options.hidden);
+                return options.hidden ? null : this.lookup(selector, remaining());
+            });
+        }
+        catch (error) {
+            if (error instanceof TimeoutError)
+                throw new TimeoutError(`Selector ${selector} timed out after ${options.timeout ?? this.client.timeout}ms`);
+            throw error;
+        }
+    }
+    async requireElement(selector) {
+        const handle = await this.$(selector);
+        if (!handle)
+            throw new Error(`No element matches selector: ${selector}`);
+        return handle;
+    }
+    async withElement(target, work) {
+        const handle = typeof target === 'string' ? await this.requireElement(target) : target;
+        handle.assertUsable(this);
+        try {
+            return await work(handle);
+        }
+        finally {
+            if (typeof target === 'string')
+                await handle.dispose();
+        }
+    }
+    async point(handle) {
+        await handle.evaluate((element) => { if (!element.isConnected)
+            throw new Error('Element detached'); element.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' }); });
+        const box = await handle.boundingBox();
+        if (!box || !box.width || !box.height)
+            throw new Error('Element has no clickable box');
+        return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+    }
+    async click(target, options = {}) {
+        await this.withElement(target, async (handle) => {
+            const point = await this.point(handle), button = options.button ?? 'left', count = options.clickCount ?? 1;
+            await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point });
+            for (let clickCount = 1; clickCount <= count; clickCount++) {
+                await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', ...point, button, buttons: button === 'left' ? 1 : button === 'right' ? 2 : 4, clickCount });
+                if (options.delay)
+                    await sleep(options.delay);
+                await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', ...point, button, buttons: 0, clickCount });
+            }
+        });
+    }
+    async type(selector, text, options = {}) {
+        await this.withElement(selector, (handle) => this.typeElement(handle, text, options));
+    }
+    /** @internal */
+    async typeElement(handle, text, options = {}) {
+        await handle.focus();
+        if (!options.delay) {
+            await this.send('Input.insertText', { text });
+            return;
+        }
+        for (const char of text) {
+            await this.send('Input.insertText', { text: char });
+            await sleep(options.delay);
+        }
+    }
+    async hover(target) {
+        await this.withElement(target, async (handle) => { await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...await this.point(handle) }); });
+    }
+    async focus(target) { await this.withElement(target, (handle) => handle.focus()); }
+    async select(selector, ...values) {
+        return this.$eval(selector, (element, values) => {
+            if (!(element instanceof HTMLSelectElement))
+                throw new Error('Element is not a select');
+            element.selectedIndex = -1;
+            const selected = [];
+            for (const option of Array.from(element.options)) {
+                if (!element.multiple && selected.length)
+                    break;
+                option.selected = values.includes(option.value);
+                if (option.selected)
+                    selected.push(option.value);
+            }
+            element.dispatchEvent(new Event('input', { bubbles: true }));
+            element.dispatchEvent(new Event('change', { bubbles: true }));
+            return selected;
+        }, values);
+    }
+    async screenshot(options = {}) {
+        if (options.type && options.type !== 'png' || options.fullPage || options.captureBeyondViewport)
+            throw new Error('Only viewport PNG screenshots are supported');
+        const { data } = await this.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false, fromSurface: true });
+        const buffer = Buffer.from(data, 'base64');
+        if (options.path)
+            await writeFile(options.path, buffer);
+        return buffer;
+    }
+}
+/** Remote DOM reference; dispose explicitly or let navigation release its object group. */
+export class QaElement {
+    page;
+    objectId;
+    onDisposed;
+    disposed = false;
+    /** @internal */
+    constructor(page, objectId, onDisposed) {
+        this.page = page;
+        this.objectId = objectId;
+        this.onDisposed = onDisposed;
+    }
+    /** @internal */
+    assertUsable(page) {
+        if (this.disposed)
+            throw new Error('Element handle disposed or released by navigation');
+        if (page !== this.page)
+            throw new Error('Element belongs to another page');
+    }
+    /** @internal */
+    invalidate() { this.disposed = true; this.onDisposed(); }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.invalidate();
+        await this.page.send('Runtime.releaseObject', { objectId: this.objectId });
+    }
+    evaluate(fn, ...args) {
+        return this.page.callElement(this, fn, args);
+    }
+    click(options = {}) { return this.page.click(this, options); }
+    type(text, options = {}) { return this.page.typeElement(this, text, options); }
+    hover() { return this.page.hover(this); }
+    async focus() { await this.evaluate((element) => element.focus()); }
+    boundingBox() {
+        return this.evaluate((element) => {
+            if (!element.isConnected || !element.getClientRects().length || getComputedStyle(element).visibility === 'hidden')
+                return null;
+            const { x, y, width, height } = element.getBoundingClientRect();
+            return { x, y, width, height };
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",