@rightkit/qa 0.4.3 → 0.4.5

package/README.md

@@ -13,7 +13,7 @@ Shared browser and QA primitives for Right Suite apps: run storage and evidence
 
 | Import | Contents |
 |---|---|
-| `@rightkit/qa` | `export *` from evidence, frames, guard, loopback, ownership, paint, panes, process, workspace, storage, page and chrome modules. Includes `QaBrowserSession`, `QaPage`, `QaElement`, `QaKeyboard`, `QaMouse`, `TimeoutError`. |
+| `@rightkit/qa` | `export *` from evidence, frames, guard, loopback, ownership, paint, panes, process, workspace, storage, page and chrome modules. Includes `QaBrowserSession`, `QaPage`, `QaElement`, `QaKeyboard`, `QaMouse`, `TimeoutError`, `ElementOccludedError`, `FillMismatchError`, `freePort`. |
 | `@rightkit/qa/chrome` | Re-export of `@rightkit/qa-chrome` |
 
 Dependency: `@rightkit/qa-chrome` (exact `0.1.3`).
@@ -86,6 +86,25 @@ try {
 
 `evaluate` throws the page's JavaScript exception (or a `TimeoutError`) rather than returning an error value. Wrap the call if you need the error as data.
 
+## Console, occlusion, fill, wheel, user agent and failure artifacts
+
+- `page.consoleEntries()` returns the newest 200 console calls and uncaught exceptions of the page, oldest first, as `{ type, text, url?, line?, timestamp }`. `type` is the console method (`log`, `error`, ...) or `exception`. Capture is always on; `clearConsoleEntries()` empties the buffer. Entries may contain page data, so do not write them to shared logs.
+- `page.click(target, { checkOccluded: true })` checks, after the pointer moves and before it presses, that `elementFromPoint` at the click point is the target or one of its descendants. Otherwise it throws `ElementOccludedError`, whose `occluder` names the element on top (tag, id, class; never text). The check walks into open shadow roots to name the element on top; a cover inside a closed shadow root is named by its host. The default is `false`.
+- `page.fill(target, value, { replace?, verify? })`. The default inserts at the caret, as `type()` does. `replace: true` selects the whole field first; an empty value then deletes it. `verify: true` (requires `replace`) reads the value back once and throws `FillMismatchError` on a difference. The error gives lengths, not values.
+- `page.mouse.wheel({ deltaX?, deltaY? })` sends one `mouseWheel` event at the tracked pointer position. The pointer does not move.
+- `page.setUserAgent(ua, { platform?, acceptLanguage? })` overrides the user agent for the page and its later navigations. Each call replaces the whole override. `page.resetUserAgent()` restores the `navigator.userAgent` captured before the first override.
+- `waitForFunction(fn, { failureArtifacts: { directory, label? } })` and `waitForSelector(...)` write a screenshot and a JSON state dump (url, title, predicate text, timeout, console entries) when they time out. Paths are on `error.artifacts` (`json`, `screenshot?`). `directory` must be absolute and must not lie inside `RIGHTKIT_RUN_ROOT`: `disposeQaWorkspace` deletes that tree. A failed write is appended to the error message; the timeout still throws.
+
+- `page.send(method, params?, timeout?)` is a page-scoped raw CDP escape hatch: unsupported surface, with Chrome's names, params and results. Prefer the typed methods. `page.setFocusEmulation(enabled)` sends `Emulation.setFocusEmulationEnabled`.
+- Navigation and reloads: `evaluate`, `waitForFunction` and `waitForSelector` re-resolve the main-frame context when Chrome reports it missing, and retry within the caller's timeout.
+- `onPoll: () => void | Promise<void>` on `waitForFunction` and `waitForSelector` runs once per poll, before the predicate. A throw rejects the wait with that error.
+- `click(target, { scroll: { inline: "nearest" } })` and `hover(target, { scroll })` choose horizontal alignment; the default is `center`, as before.
+- `fill(target, value, { replace: true, verify: { timeoutMs } })` polls the readback until it matches or the window ends; `verify: true` reads once.
+
+`spawnOwnedProcess(command, args, options)` starts a process in its own group (POSIX) and records it. `stopOwnedProcess(handle)` stops only a handle that `spawnOwnedProcess` returned, signalling the whole group. Bare pids and other objects are refused. `ownedProcessReceipt()` lists launched processes still running.
+
+`freePort()` returns a free `127.0.0.1` port by binding port 0 and releasing it. Another process can take the port before use.
+
 ## Keyboard keys
 
 `page.keyboard.press(chord)` accepts named keys (`Enter`, `Tab`, `Escape`, arrows, `Home`, `End`, `PageUp`, `PageDown`, `Backspace`, `Delete`, `Space`, `Shift`, `Control`, `Alt`, `Meta`), function keys `F1` through `F24`, letters, digits, and every printable US-layout symbol, including backslash.
@@ -124,5 +143,5 @@ This package launches no native app and no WebView2 window; it never replaces th
 
 ## Known issues
 
-- `@rightkit/qa-chrome` is pinned exactly to `0.1.3`. A qa-chrome release therefore needs a `@rightkit/qa` republish to reach consumers (npm audit 2026-10-08, qa finding).
+- `@rightkit/qa-chrome` is pinned exactly to `0.1.4`. A qa-chrome release therefore needs a `@rightkit/qa` republish to reach consumers (npm audit 2026-10-08, qa finding).
 - Three consumers pin three different versions of `@rightkit/qa-chrome` as dev dependencies (npm audit 2026-10-08).

package/dist/cdp.d.ts

@@ -1,5 +1,10 @@
 /** Minimal flattened-session CDP transport using Node's built-in WebSocket. */
 export declare class TimeoutError extends Error {
+    /** Set when the wait was given failureArtifacts and the artifacts were written. */
+    artifacts?: {
+        json: string;
+        screenshot?: string;
+    };
     constructor(message: string);
 }
 export interface QaConnectOptions {

package/dist/cdp.js

@@ -1,5 +1,7 @@
 /** Minimal flattened-session CDP transport using Node's built-in WebSocket. */
 export class TimeoutError extends Error {
+    /** Set when the wait was given failureArtifacts and the artifacts were written. */
+    artifacts;
     constructor(message) { super(message); this.name = 'TimeoutError'; }
 }
 /** @internal All operations use finite deadlines. */

package/dist/mouse.d.ts

@@ -11,6 +11,10 @@ export interface MousePosition {
     x: number;
     y: number;
 }
+export interface MouseWheelOptions {
+    deltaX?: number; /** Vertical scroll delta in CSS pixels; positive scrolls down. Default 0. */
+    deltaY?: number;
+}
 /**
  * Pointer state for one page: position and held buttons, so a move while a button is held
  * sends the right `buttons` mask. Coordinates are CSS pixels of the viewport, as for `click`.
@@ -30,6 +34,11 @@ export declare class QaMouse {
     down(options?: MouseButtonOptions): Promise<void>;
     /** Release a held button at the current position. */
     up(options?: MouseButtonOptions): Promise<void>;
+    /**
+     * Wheel (scroll) at the tracked position. Sends one mouseWheel event with the given deltas;
+     * the pointer does not move. At least one delta must be non-zero.
+     */
+    wheel(options?: MouseWheelOptions): Promise<void>;
     /** @internal Called by page.click & page.hover after they dispatch at a point. */
     track(x: number, y: number): void;
     /** @internal Page-level click & hover send their own events without a held mask, so refuse to run while held. */

package/dist/mouse.js

@@ -62,6 +62,18 @@ export class QaMouse {
         await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: this.x, y: this.y, button, buttons, clickCount });
         this.held.delete(button);
     }
+    /**
+     * Wheel (scroll) at the tracked position. Sends one mouseWheel event with the given deltas;
+     * the pointer does not move. At least one delta must be non-zero.
+     */
+    async wheel(options = {}) {
+        const deltaX = options.deltaX ?? 0, deltaY = options.deltaY ?? 0;
+        if (!Number.isFinite(deltaX) || !Number.isFinite(deltaY))
+            throw new Error('Mouse wheel deltas must be finite numbers');
+        if (deltaX === 0 && deltaY === 0)
+            throw new Error('Mouse wheel needs a non-zero deltaX or deltaY');
+        await this.send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: this.x, y: this.y, deltaX, deltaY });
+    }
     /** @internal Called by page.click & page.hover after they dispatch at a point. */
     track(x, y) { this.x = x; this.y = y; }
     /** @internal Page-level click & hover send their own events without a held mask, so refuse to run while held. */

package/dist/page.d.ts

@@ -3,7 +3,7 @@ import { QaKeyboard } from './keyboard.js';
 import { QaMouse } from './mouse.js';
 export { TimeoutError, type QaConnectOptions } from './cdp.js';
 export { QaKeyboard } from './keyboard.js';
-export { QaMouse, type MouseButton, type MouseButtonOptions, type MouseMoveOptions, type MousePosition } from './mouse.js';
+export { QaMouse, type MouseButton, type MouseButtonOptions, type MouseMoveOptions, type MousePosition, type MouseWheelOptions } from './mouse.js';
 export interface NavigationOptions {
     waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0';
     timeout?: number;
@@ -14,19 +14,67 @@ export interface ViewportOptions {
     deviceScaleFactor?: number;
     mobile?: boolean;
 }
+/** Where a timed-out wait writes its screenshot and JSON state dump. */
+export interface FailureArtifactOptions {
+    /** Absolute directory, created if missing. Must lie outside RIGHTKIT_RUN_ROOT, which disposeQaWorkspace deletes. */
+    directory: string;
+    /** Short name used in the file names and the dump. Default 'wait'. */
+    label?: string;
+}
+/** Called once per poll, before the predicate. A throw rejects the wait with that error. */
+export type PollHook = () => void | Promise<void>;
 export interface WaitOptions {
     timeout?: number;
     polling?: 'raf' | number;
+    failureArtifacts?: FailureArtifactOptions;
+    onPoll?: PollHook;
 }
 export interface SelectorWaitOptions {
     visible?: boolean;
     hidden?: boolean;
     timeout?: number;
+    failureArtifacts?: FailureArtifactOptions;
+    onPoll?: PollHook;
+}
+/** How the target is brought into view before the pointer moves. Vertical alignment is always centre. */
+export interface ScrollOptions {
+    /** Default 'center', as before 0.4.5. 'nearest' scrolls the least needed to show the target at the edge. */
+    inline?: 'center' | 'nearest';
+}
+export interface HoverOptions {
+    scroll?: ScrollOptions;
 }
 export interface ClickOptions {
     button?: 'left' | 'right' | 'middle';
     clickCount?: number;
     delay?: number;
+    scroll?: ScrollOptions;
+    /** Default false. When true, after the pointer moves and before pressing, checks that the element at the click point is the target or its descendant; otherwise throws ElementOccludedError. */
+    checkOccluded?: boolean;
+}
+export interface FillOptions {
+    /** Default false: insert at the caret, exactly as type() does. True selects the whole field first, so the value replaces its content; an empty value then deletes the selection. */
+    replace?: boolean;
+    /**
+     * Default false: read the value back once after insertion and throw FillMismatchError on a difference.
+     * `{ timeoutMs }` polls the readback every 25 ms until it matches or the window ends, for fields that
+     * settle late (a framework rewrites the value after an input event). Requires replace.
+     */
+    verify?: boolean | {
+        timeoutMs: number;
+    };
+}
+/** One console call or uncaught exception of a page. `line` is 1-based. */
+export interface ConsoleEntry {
+    type: string;
+    text: string;
+    url?: string;
+    line?: number;
+    timestamp: number;
+}
+export interface UserAgentOptions {
+    platform?: string;
+    acceptLanguage?: string;
 }
 export interface TypeOptions {
     delay?: number;
@@ -60,6 +108,25 @@ export interface QaAttachOptions extends QaConnectOptions {
     allowRemoteHost?: boolean;
 }
 type PageFunction<Args extends unknown[], Result> = (...args: Args) => Result;
+/** Thrown by click({ checkOccluded: true }) when another element is on top of the target at the click point. */
+export declare class ElementOccludedError extends Error {
+    readonly point: {
+        x: number;
+        y: number;
+    };
+    /** Short description of the element on top, e.g. <div id="toast">. Text content is never included. */
+    readonly occluder: string;
+    constructor(occluder: string, point: {
+        x: number;
+        y: number;
+    });
+}
+/** Thrown by fill({ verify: true }) when the field does not hold the requested value. The values are not included. */
+export declare class FillMismatchError extends Error {
+    readonly expectedLength: number;
+    readonly actualLength: number;
+    constructor(expectedLength: number, actualLength: number);
+}
 /** Owns only targets it creates; launcher owns browser process & profile cleanup. */
 export declare class QaBrowserSession {
     private client;
@@ -124,6 +191,9 @@ export declare class QaPage {
     private lastNetworkActivity;
     private generation;
     private navigating;
+    private consoleBuffer;
+    private userAgentBaseline?;
+    private userAgentOverridden;
     private get objectGroup();
     /** @internal Use QaBrowserSession.newPage() or attachPage(). `owned` pages are closed on close(); attached ones only detach. */
     constructor(client: CdpClient, targetId: string, sessionId: string, onClosed: () => void, owned?: boolean);
@@ -132,8 +202,17 @@ export declare class QaPage {
     on(method: string, listener: (params: CdpParams) => void): () => void;
     /** @internal */
     initialize(): Promise<void>;
-    /** @internal */
+    /**
+     * UNSUPPORTED escape hatch: sends one page-scoped CDP command on this page's session and resolves
+     * with its raw result. Method names, params and results follow Chrome's protocol, not this package,
+     * and may change with the browser version. Prefer the typed QaPage methods where they exist.
+     */
     send(method: string, params?: CdpParams, timeout?: number): Promise<CdpParams>;
+    /**
+     * Emulation.setFocusEmulationEnabled: the page behaves as focused while its window is not
+     * (background or headless). Persists for the page until turned off.
+     */
+    setFocusEmulation(enabled: boolean): Promise<void>;
     private invalidateHandles;
     /** @internal */
     markClosed(error?: Error): void;
@@ -162,11 +241,42 @@ export declare class QaPage {
     private requireElement;
     private withElement;
     private point;
+    /** Recent console calls and uncaught exceptions of this page, oldest first. Bounded to the newest 200. Returns copies. */
+    consoleEntries(): ConsoleEntry[];
+    /** Empties the console buffer. */
+    clearConsoleEntries(): void;
+    private recordConsole;
+    /**
+     * Overrides the user agent (Emulation.setUserAgentOverride) for this page, including later navigations.
+     * Each call replaces the whole override, so platform & acceptLanguage are sent only when given.
+     */
+    setUserAgent(userAgent: string, options?: UserAgentOptions): Promise<void>;
+    /** Restores the navigator.userAgent captured before the first setUserAgent. A no-op when this page never overrode it. */
+    resetUserAgent(): Promise<void>;
+    /**
+     * Types a value into a field. Default: insert at the caret, exactly as type() does. With replace the
+     * whole content is selected first and replaced. With verify the value is read back and
+     * FillMismatchError is thrown on a difference: once by default, or polled until `timeoutMs` with
+     * `verify: { timeoutMs }`. Verify requires replace.
+     */
+    fill(target: string | QaElement, value: string, options?: FillOptions): Promise<void>;
+    private selectAll;
+    /** Throws ElementOccludedError naming the element on top unless the target itself or a composed descendant is hit. */
+    private assertUnoccluded;
+    /** Writes a PNG and a JSON state dump for a timed-out wait into the caller directory. */
+    private captureFailure;
+    /** Attaches artifact paths to a timeout error. A write failure is appended to its message; the timeout still throws. */
+    /**
+     * Writes the failure artifacts for a timed-out wait or a failed onPoll hook. The paths are attached as
+     * `artifacts` only on a TimeoutError; for other errors the files are written and the paths are not attached.
+     * A write failure is appended to a TimeoutError's message; the original error still throws.
+     */
+    private attachFailureArtifacts;
     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>;
+    hover(target: string | QaElement, options?: HoverOptions): Promise<void>;
     focus(target: string | QaElement): Promise<void>;
     select(selector: string, ...values: string[]): Promise<string[]>;
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
@@ -187,7 +297,7 @@ export declare class QaElement {
     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>;
+    hover(options?: HoverOptions): Promise<void>;
     focus(): Promise<void>;
     boundingBox(): Promise<BoundingBox | null>;
 }

package/dist/page.js

@@ -1,10 +1,117 @@
-import { writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { CdpClient, TimeoutError, validateTimeout } from './cdp.js';
 import { QaKeyboard } from './keyboard.js';
 import { QaMouse } from './mouse.js';
 export { TimeoutError } from './cdp.js';
 export { QaKeyboard } from './keyboard.js';
 export { QaMouse } from './mouse.js';
+/** Newest console entries kept per page. */
+const CONSOLE_LIMIT = 200;
+/** Thrown by click({ checkOccluded: true }) when another element is on top of the target at the click point. */
+export class ElementOccludedError extends Error {
+    point;
+    /** Short description of the element on top, e.g. <div id="toast">. Text content is never included. */
+    occluder;
+    constructor(occluder, point) {
+        super(`Click target is covered by ${occluder} at (${point.x}, ${point.y})`);
+        this.name = 'ElementOccludedError';
+        this.occluder = occluder;
+        this.point = point;
+    }
+}
+/** Thrown by fill({ verify: true }) when the field does not hold the requested value. The values are not included. */
+export class FillMismatchError extends Error {
+    expectedLength;
+    actualLength;
+    constructor(expectedLength, actualLength) {
+        super(`fill verification failed: field holds ${actualLength} characters, expected ${expectedLength}`);
+        this.name = 'FillMismatchError';
+        this.expectedLength = expectedLength;
+        this.actualLength = actualLength;
+    }
+}
+/** CDP's answer for a context id that no longer exists. The command did not run, so retrying is safe. */
+function isMissingContext(error) {
+    return error instanceof Error && /Cannot find context with specified id/.test(error.message);
+}
+function scrollInline(scroll) {
+    const inline = scroll?.inline ?? 'center';
+    if (inline !== 'center' && inline !== 'nearest')
+        throw new Error('scroll.inline must be center or nearest');
+    return inline;
+}
+/** Wraps an onPoll hook so a throw is recorded on `state` (failure artifacts then apply to it). */
+function pollHook(onPoll, state) {
+    if (!onPoll)
+        return undefined;
+    return async () => {
+        try {
+            await onPoll();
+        }
+        catch (error) {
+            state.failed = true;
+            state.error = error;
+            throw error;
+        }
+    };
+}
+/** Text of one console argument, from its CDP RemoteObject. */
+function remoteText(object) {
+    if ('value' in object)
+        return typeof object.value === 'string' ? object.value : JSON.stringify(object.value) ?? String(object.value);
+    return String(object.unserializableValue ?? object.description ?? object.type ?? '');
+}
+/** url and 1-based line, present only when the event carries them. */
+function locationOf(url, zeroBasedLine) {
+    const location = {};
+    if (typeof url === 'string' && url)
+        location.url = url;
+    if (typeof zeroBasedLine === 'number' && zeroBasedLine >= 0)
+        location.line = zeroBasedLine + 1;
+    return location;
+}
+function consoleEntry(event) {
+    const frame = event.stackTrace?.callFrames?.[0];
+    return {
+        type: String(event.type),
+        text: (event.args ?? []).map(remoteText).join(' '),
+        ...locationOf(frame?.url, frame?.lineNumber),
+        timestamp: typeof event.timestamp === 'number' ? event.timestamp : Date.now(),
+    };
+}
+function exceptionEntry(event) {
+    const details = event.exceptionDetails ?? {};
+    return {
+        type: 'exception',
+        text: String(details.exception?.description ?? details.exception?.value ?? details.text ?? 'Uncaught exception'),
+        ...locationOf(details.url, details.lineNumber),
+        timestamp: typeof event.timestamp === 'number' ? event.timestamp : Date.now(),
+    };
+}
+/**
+ * Validates a failureArtifacts option before any CDP work: absolute, and never inside
+ * RIGHTKIT_RUN_ROOT (the workspace home that disposeQaWorkspace deletes).
+ */
+function failureTarget(options) {
+    if (!options)
+        return undefined;
+    const { directory, label } = options;
+    if (typeof directory !== 'string' || !path.isAbsolute(directory))
+        throw new Error('failureArtifacts.directory must be an absolute path');
+    if (label !== undefined && typeof label !== 'string')
+        throw new Error('failureArtifacts.label must be a string');
+    const resolved = path.resolve(directory);
+    const runRoot = process.env.RIGHTKIT_RUN_ROOT;
+    if (runRoot) {
+        const relative = path.relative(path.resolve(runRoot), resolved);
+        const inside = relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+        if (inside)
+            throw new Error('failureArtifacts.directory must be outside RIGHTKIT_RUN_ROOT: disposeQaWorkspace deletes that tree');
+    }
+    return { directory: resolved, label: (label ?? 'wait').replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 60) || 'wait' };
+}
+let failureSequence = 0;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function functionSource(fn) {
     const source = fn.toString();
@@ -291,6 +398,9 @@ export class QaPage {
     lastNetworkActivity = 0;
     generation = 0;
     navigating = false;
+    consoleBuffer = [];
+    userAgentBaseline;
+    userAgentOverridden = false;
     get objectGroup() { return `qa-elements-${this.generation}`; }
     /** @internal Use QaBrowserSession.newPage() or attachPage(). `owned` pages are closed on close(); attached ones only detach. */
     constructor(client, targetId, sessionId, onClosed, owned = true) {
@@ -335,7 +445,7 @@ export class QaPage {
             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.on('Runtime.consoleAPICalled', (event) => this.recordConsole(consoleEntry(event))), this.on('Runtime.exceptionThrown', (event) => this.recordConsole(exceptionEntry(event))), 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() {
@@ -360,12 +470,27 @@ export class QaPage {
         await this.send('Network.enable');
         await this.send('Page.setLifecycleEventsEnabled', { enabled: true });
     }
-    /** @internal */
+    /**
+     * UNSUPPORTED escape hatch: sends one page-scoped CDP command on this page's session and resolves
+     * with its raw result. Method names, params and results follow Chrome's protocol, not this package,
+     * and may change with the browser version. Prefer the typed QaPage methods where they exist.
+     */
     send(method, params = {}, timeout) {
         if (this.closed)
             return Promise.reject(this.closed);
+        if (typeof method !== 'string' || !method)
+            return Promise.reject(new Error('CDP method must be a non-empty string'));
         return this.client.send(method, params, this.sessionId, timeout);
     }
+    /**
+     * Emulation.setFocusEmulationEnabled: the page behaves as focused while its window is not
+     * (background or headless). Persists for the page until turned off.
+     */
+    async setFocusEmulation(enabled) {
+        if (typeof enabled !== 'boolean')
+            throw new Error('setFocusEmulation expects a boolean');
+        await this.send('Emulation.setFocusEmulationEnabled', { enabled });
+    }
     invalidateHandles() {
         const objectGroup = this.objectGroup;
         this.generation++;
@@ -512,14 +637,36 @@ export class QaPage {
     }
     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;
+        // A reload destroys the context an earlier call resolved. CDP refuses a call against a missing
+        // context without running it, so re-resolve the main context and retry until the caller's deadline.
+        let missing;
+        for (;;) {
+            const remaining = Math.max(1, deadline - Date.now());
+            let result;
+            try {
+                const contextId = await this.mainContext(remaining);
+                const common = { returnByValue, awaitPromise: true, objectGroup: this.objectGroup, timeout: remaining };
+                result = typeof fn === 'string'
+                    ? await this.send('Runtime.evaluate', { expression: fn, contextId, ...common }, remaining)
+                    : await this.send('Runtime.callFunctionOn', { functionDeclaration: functionSource(fn), executionContextId: contextId, arguments: args.map(argument), ...common }, remaining);
+            }
+            catch (error) {
+                if (isMissingContext(error)) {
+                    missing = error;
+                    if (Date.now() < deadline) {
+                        await sleep(10);
+                        continue;
+                    }
+                    throw error;
+                }
+                // The budget ran out while a context was missing: report the cause, not a bare timeout.
+                if (error instanceof TimeoutError && missing)
+                    throw missing;
+                throw error;
+            }
+            resultValue(result);
+            return result;
+        }
     }
     async evaluate(fn, ...args) {
         return resultValue(await this.run(fn, args, true));
@@ -589,35 +736,53 @@ export class QaPage {
         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());
+        const artifacts = failureTarget(options.failureArtifacts);
+        const timeout = options.timeout ?? this.client.timeout;
+        const pollState = { failed: false, error: undefined };
+        const poll = pollHook(options.onPoll, pollState);
+        try {
+            await this.bounded(`Predicate ${source}`, timeout, async (remaining, stopped) => {
+                while (!stopped()) {
+                    if (poll)
+                        await poll();
+                    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()));
                     }
-                    else
-                        await sleep(Math.min(polling, remaining()));
-                }
-                catch (error) {
-                    if (error instanceof TimeoutError) {
-                        await sleep(remaining());
-                        continue;
+                    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()));
                     }
-                    if (!/context.*(destroyed|not found)|Cannot find context/i.test(String(error)))
-                        throw error;
-                    await sleep(Math.min(10, remaining()));
                 }
+            });
+        }
+        catch (error) {
+            if (artifacts && (error instanceof TimeoutError || (pollState.failed && pollState.error === error))) {
+                await this.attachFailureArtifacts(error, artifacts, source, timeout);
             }
-        });
+            throw error;
+        }
     }
     async waitForSelector(selector, options = {}) {
         if (options.visible && options.hidden)
             throw new Error('visible & hidden cannot both be true');
+        const artifacts = failureTarget(options.failureArtifacts);
+        const timeout = options.timeout ?? this.client.timeout;
+        const pollState = { failed: false, error: undefined };
+        const poll = pollHook(options.onPoll, pollState);
         try {
-            return await this.bounded(`Selector ${selector}`, options.timeout ?? this.client.timeout, async (remaining) => {
+            return await this.bounded(`Selector ${selector}`, timeout, async (remaining) => {
                 await this.waitForFunction((selector, visible, hidden) => {
                     const element = document.querySelector(selector);
                     if (!element)
@@ -625,13 +790,20 @@ export class QaPage {
                     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);
+                }, { timeout: remaining(), onPoll: poll }, 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`);
+            if (error instanceof TimeoutError) {
+                const named = new TimeoutError(`Selector ${selector} timed out after ${timeout}ms`);
+                if (artifacts)
+                    await this.attachFailureArtifacts(named, artifacts, `waitForSelector ${JSON.stringify(selector)} visible=${!!options.visible} hidden=${!!options.hidden}`, timeout);
+                throw named;
+            }
+            if (artifacts && pollState.failed && pollState.error === error) {
+                await this.attachFailureArtifacts(error, artifacts, `waitForSelector ${JSON.stringify(selector)} onPoll`, timeout);
+            }
             throw error;
         }
     }
@@ -652,20 +824,190 @@ export class QaPage {
                 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' }); });
+    async point(handle, inline = 'center') {
+        await handle.evaluate((element, inline) => { if (!element.isConnected)
+            throw new Error('Element detached'); element.scrollIntoView({ block: 'center', inline: inline, behavior: 'instant' }); }, inline);
         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 };
     }
+    /** Recent console calls and uncaught exceptions of this page, oldest first. Bounded to the newest 200. Returns copies. */
+    consoleEntries() { return this.consoleBuffer.map((entry) => ({ ...entry })); }
+    /** Empties the console buffer. */
+    clearConsoleEntries() { this.consoleBuffer.length = 0; }
+    recordConsole(entry) {
+        this.consoleBuffer.push(entry);
+        if (this.consoleBuffer.length > CONSOLE_LIMIT)
+            this.consoleBuffer.splice(0, this.consoleBuffer.length - CONSOLE_LIMIT);
+    }
+    /**
+     * Overrides the user agent (Emulation.setUserAgentOverride) for this page, including later navigations.
+     * Each call replaces the whole override, so platform & acceptLanguage are sent only when given.
+     */
+    async setUserAgent(userAgent, options = {}) {
+        if (typeof userAgent !== 'string' || !userAgent.trim())
+            throw new Error('User agent must be a non-empty string');
+        // The first override records the page's own navigator.userAgent so resetUserAgent can restore it.
+        if (!this.userAgentOverridden)
+            this.userAgentBaseline = await this.evaluate(() => navigator.userAgent);
+        await this.send('Emulation.setUserAgentOverride', {
+            userAgent,
+            ...(options.platform !== undefined ? { platform: options.platform } : {}),
+            ...(options.acceptLanguage !== undefined ? { acceptLanguage: options.acceptLanguage } : {}),
+        });
+        this.userAgentOverridden = true;
+    }
+    /** Restores the navigator.userAgent captured before the first setUserAgent. A no-op when this page never overrode it. */
+    async resetUserAgent() {
+        if (!this.userAgentOverridden || this.userAgentBaseline === undefined)
+            return;
+        await this.send('Emulation.setUserAgentOverride', { userAgent: this.userAgentBaseline });
+        this.userAgentOverridden = false;
+        this.userAgentBaseline = undefined;
+    }
+    /**
+     * Types a value into a field. Default: insert at the caret, exactly as type() does. With replace the
+     * whole content is selected first and replaced. With verify the value is read back and
+     * FillMismatchError is thrown on a difference: once by default, or polled until `timeoutMs` with
+     * `verify: { timeoutMs }`. Verify requires replace.
+     */
+    async fill(target, value, options = {}) {
+        if (typeof value !== 'string')
+            throw new Error('fill value must be a string');
+        const verify = options.verify;
+        if (verify && !options.replace)
+            throw new Error('fill verify requires replace: true; an insert-only fill has no fixed expected value');
+        const windowMs = typeof verify === 'object' && verify !== null ? validateTimeout(verify.timeoutMs) : undefined;
+        await this.withElement(target, async (handle) => {
+            if (!options.replace) {
+                await this.typeElement(handle, value);
+                return;
+            }
+            await handle.focus();
+            await this.selectAll(handle);
+            if (value === '')
+                await this.keyboard.press('Backspace');
+            else
+                await this.send('Input.insertText', { text: value });
+            if (!verify)
+                return;
+            const read = () => handle.evaluate((element) => (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement ? element.value : element.textContent) ?? '');
+            let actual = await read();
+            if (windowMs !== undefined) {
+                const deadline = Date.now() + windowMs;
+                while (actual !== value && Date.now() < deadline) {
+                    await sleep(Math.min(25, Math.max(1, deadline - Date.now())));
+                    actual = await read();
+                }
+            }
+            if (actual !== value)
+                throw new FillMismatchError(value.length, actual.length);
+        });
+    }
+    async selectAll(handle) {
+        const selected = await handle.evaluate((element) => {
+            if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+                element.select();
+                return true;
+            }
+            if (element.isContentEditable) {
+                const range = element.ownerDocument.createRange();
+                range.selectNodeContents(element);
+                const selection = element.ownerDocument.getSelection();
+                selection?.removeAllRanges();
+                selection?.addRange(range);
+                return true;
+            }
+            return false;
+        });
+        if (!selected)
+            throw new Error('fill target is not an editable input, textarea or contenteditable element');
+    }
+    /** Throws ElementOccludedError naming the element on top unless the target itself or a composed descendant is hit. */
+    async assertUnoccluded(handle, point) {
+        const occluder = await handle.evaluate((element, x, y) => {
+            let hit = element.ownerDocument.elementFromPoint(x, y);
+            // The document reports a shadow host, not the element inside its open shadow root: descend.
+            while (hit?.shadowRoot) {
+                const inner = hit.shadowRoot.elementFromPoint(x, y);
+                if (!inner || inner === hit)
+                    break;
+                hit = inner;
+            }
+            // Composed ancestry: a shadow root's host counts as its parent, so shadow content inside the target passes.
+            for (let node = hit; node; node = node.parentNode ?? node.host ?? null) {
+                if (node === element)
+                    return null;
+            }
+            if (!hit)
+                return '(no element at the click point)';
+            const id = hit.id ? ` id="${hit.id}"` : '';
+            const className = typeof hit.className === 'string' ? hit.className.trim().slice(0, 80) : '';
+            return `<${hit.tagName.toLowerCase()}${id}${className ? ` class="${className}"` : ''}>`;
+        }, point.x, point.y);
+        if (occluder !== null)
+            throw new ElementOccludedError(occluder, point);
+    }
+    /** Writes a PNG and a JSON state dump for a timed-out wait into the caller directory. */
+    async captureFailure(directory, label, predicate, timeout) {
+        await mkdir(directory, { recursive: true });
+        const stem = `${label}-${Date.now()}-${++failureSequence}`;
+        const json = path.join(directory, `${stem}.json`);
+        const png = path.join(directory, `${stem}.png`);
+        let screenshot;
+        let screenshotError;
+        try {
+            await writeFile(png, await this.screenshot());
+            screenshot = png;
+        }
+        catch (error) {
+            screenshotError = error instanceof Error ? error.message : String(error);
+        }
+        let where = {};
+        try {
+            where = resultValue(await this.run(() => ({ url: location.href, title: document.title }), [], true, 2_000)) ?? {};
+        }
+        catch { /* page gone or stuck: the dump records no url or title */ }
+        const dump = {
+            label,
+            predicate,
+            timeoutMs: timeout,
+            timestamp: new Date().toISOString(),
+            url: where.url ?? null,
+            title: where.title ?? null,
+            screenshot: screenshot ? path.basename(screenshot) : null,
+            screenshotError: screenshotError ?? null,
+            console: this.consoleEntries(),
+        };
+        await writeFile(json, JSON.stringify(dump, null, 2));
+        return screenshot ? { json, screenshot } : { json };
+    }
+    /** Attaches artifact paths to a timeout error. A write failure is appended to its message; the timeout still throws. */
+    /**
+     * Writes the failure artifacts for a timed-out wait or a failed onPoll hook. The paths are attached as
+     * `artifacts` only on a TimeoutError; for other errors the files are written and the paths are not attached.
+     * A write failure is appended to a TimeoutError's message; the original error still throws.
+     */
+    async attachFailureArtifacts(error, target, predicate, timeout) {
+        try {
+            const written = await this.captureFailure(target.directory, target.label, predicate, timeout);
+            if (error instanceof TimeoutError)
+                error.artifacts = written;
+        }
+        catch (captureError) {
+            if (error instanceof TimeoutError)
+                error.message += ` (failure artifacts were not written: ${captureError instanceof Error ? captureError.message : String(captureError)})`;
+        }
+    }
     async click(target, options = {}) {
         this.mouse.assertReleased();
         await this.withElement(target, async (handle) => {
-            const point = await this.point(handle), button = options.button ?? 'left', count = options.clickCount ?? 1;
+            const point = await this.point(handle, scrollInline(options.scroll)), button = options.button ?? 'left', count = options.clickCount ?? 1;
             await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point });
             this.mouse.track(point.x, point.y);
+            if (options.checkOccluded)
+                await this.assertUnoccluded(handle, 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)
@@ -689,10 +1031,11 @@ export class QaPage {
             await sleep(options.delay);
         }
     }
-    async hover(target) {
+    async hover(target, options = {}) {
         this.mouse.assertReleased();
+        const inline = scrollInline(options.scroll);
         await this.withElement(target, async (handle) => {
-            const point = await this.point(handle);
+            const point = await this.point(handle, inline);
             await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point });
             this.mouse.track(point.x, point.y);
         });
@@ -758,7 +1101,7 @@ export class QaElement {
     }
     click(options = {}) { return this.page.click(this, options); }
     type(text, options = {}) { return this.page.typeElement(this, text, options); }
-    hover() { return this.page.hover(this); }
+    hover(options = {}) { return this.page.hover(this, options); }
     async focus() { await this.evaluate((element) => element.focus()); }
     boundingBox() {
         return this.evaluate((element) => {

package/dist/process.d.ts

@@ -1,3 +1,4 @@
+import { type ChildProcess } from 'node:child_process';
 export interface OwnedProcessResult {
     pid: number;
     code: number | null;
@@ -18,5 +19,44 @@ export declare class ProcessTimeoutError extends Error {
     constructor(pid: number, timeoutMs: number, stdout: string, stderr: string);
 }
 export declare function runOwnedProcess(command: string, args?: string[], options?: RunOwnedProcessOptions): Promise<OwnedProcessResult>;
+/**
+ * A free TCP port on 127.0.0.1, found by binding port 0 and releasing it. Another process can take
+ * the port before the caller binds it; bind promptly or retry on EADDRINUSE.
+ */
+export declare function freePort(): Promise<number>;
 export declare function isProcessAlive(pid: number): boolean;
 export declare function killProcessTree(pid: number): Promise<void>;
+export interface SpawnOwnedProcessOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Default 'ignore'. 'pipe' exposes child.stdout and child.stderr. */
+    stdio?: 'ignore' | 'pipe';
+    windowsHide?: boolean;
+}
+/**
+ * A process this package launched. Only the object returned by spawnOwnedProcess is accepted by
+ * stopOwnedProcess: a bare pid or a look-alike object is refused.
+ */
+export interface OwnedProcess {
+    readonly pid: number;
+    readonly child: ChildProcess;
+}
+/**
+ * Launches a long-running process in its own process group (POSIX) and records it. Stopping it
+ * with stopOwnedProcess signals the whole group, so grandchildren go too.
+ */
+export declare function spawnOwnedProcess(command: string, args?: string[], options?: SpawnOwnedProcessOptions): OwnedProcess;
+/**
+ * Stops a process returned by spawnOwnedProcess: SIGTERM to its process group, SIGKILL after 1 s
+ * if members remain (POSIX); taskkill /T /F on Windows. Idempotent. Refuses anything else.
+ */
+export declare function stopOwnedProcess(handle: OwnedProcess): Promise<void>;
+export interface OwnedProcessReceipt {
+    /**
+     * Pids launched by spawnOwnedProcess and not stopped whose process group (POSIX) or process
+     * (Windows) still exists. Empty when nothing this package launched is left running.
+     */
+    leftoverPids: number[];
+}
+/** Receipt of what this package launched and still has running. Read only; signals nothing. */
+export declare function ownedProcessReceipt(): OwnedProcessReceipt;

package/dist/process.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { createServer } from 'node:net';
 export class ProcessTimeoutError extends Error {
     pid;
     stdout;
@@ -54,6 +55,26 @@ export function runOwnedProcess(command, args = [], options = {}) {
         });
     });
 }
+/**
+ * A free TCP port on 127.0.0.1, found by binding port 0 and releasing it. Another process can take
+ * the port before the caller binds it; bind promptly or retry on EADDRINUSE.
+ */
+export function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                server.close();
+                reject(new Error('freePort: no TCP address'));
+                return;
+            }
+            const port = address.port;
+            server.close((error) => (error ? reject(error) : resolve(port)));
+        });
+    });
+}
 export function isProcessAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
         return false;
@@ -112,3 +133,82 @@ async function waitForExit(pid, timeoutMs) {
         await new Promise((resolve) => setTimeout(resolve, 25));
     }
 }
+/** Every handle this package has launched in this process, stopped or not. */
+const launched = new Set();
+const stopped = new WeakSet();
+/**
+ * Launches a long-running process in its own process group (POSIX) and records it. Stopping it
+ * with stopOwnedProcess signals the whole group, so grandchildren go too.
+ */
+export function spawnOwnedProcess(command, args = [], options = {}) {
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: options.stdio === 'pipe' ? ['ignore', 'pipe', 'pipe'] : 'ignore',
+        windowsHide: options.windowsHide ?? true,
+        detached: process.platform !== 'win32',
+    });
+    // Spawn failures arrive as 'error'; surface them through the missing pid, not as an unhandled event.
+    child.on('error', () => { });
+    if (!child.pid)
+        throw new Error(`failed to start owned process: ${command}`);
+    const handle = Object.freeze({ pid: child.pid, child });
+    launched.add(handle);
+    return handle;
+}
+/**
+ * Stops a process returned by spawnOwnedProcess: SIGTERM to its process group, SIGKILL after 1 s
+ * if members remain (POSIX); taskkill /T /F on Windows. Idempotent. Refuses anything else.
+ */
+export async function stopOwnedProcess(handle) {
+    if (!handle || typeof handle !== 'object' || !launched.has(handle)) {
+        const pid = handle && typeof handle === 'object' ? handle.pid : handle;
+        throw new Error(`refusing to stop pid ${String(pid)}: this package did not launch it`);
+    }
+    if (stopped.has(handle))
+        return;
+    const pid = handle.pid;
+    if (process.platform === 'win32') {
+        await runCleanupCommand('taskkill.exe', ['/PID', String(pid), '/T', '/F']);
+    }
+    else {
+        signalGroup(pid, 'SIGTERM');
+        if (!(await waitGroupGone(pid, 1_000))) {
+            signalGroup(pid, 'SIGKILL');
+            await waitGroupGone(pid, 2_000);
+        }
+    }
+    stopped.add(handle);
+}
+/** Receipt of what this package launched and still has running. Read only; signals nothing. */
+export function ownedProcessReceipt() {
+    const leftoverPids = [...launched]
+        .filter((handle) => !stopped.has(handle))
+        .filter((handle) => (process.platform === 'win32' ? isProcessAlive(handle.pid) : groupAlive(handle.pid)))
+        .map((handle) => handle.pid);
+    return { leftoverPids };
+}
+function groupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function signalGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch { /* group already gone */ }
+}
+async function waitGroupGone(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (groupAlive(pid)) {
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -24,7 +24,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@rightkit/qa-chrome": "0.1.3"
+    "@rightkit/qa-chrome": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",