@rightkit/qa 0.4.4 → 0.4.6

package/README.md

@@ -93,7 +93,15 @@ try {
 - `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.
+- `waitForFunction(fn, { failureArtifacts: { directory, label?, extra?, allowInsideRunRoot? } })` and `waitForSelector(...)` write a screenshot and a JSON state dump on timeout: url, title, bounded page text (`pageText`), the focused element's descriptor without its value (`activeElement`), console entries, and `extra()` if given (`extra`, or `extraError` when it throws, never settles or cannot serialise). Paths are on `error.artifacts` (`json`, `screenshot?`). `directory` must be absolute and must not lie inside `RIGHTKIT_RUN_ROOT`, which `disposeQaWorkspace` deletes; `allowInsideRunRoot: true` opts in, and those files then go with the workspace, so copy them out before dispose. 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.
 
@@ -135,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.5`. 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/page.d.ts

@@ -16,34 +16,67 @@ export interface ViewportOptions {
 }
 /** 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. */
+    /**
+     * Absolute directory, created if missing. Must lie outside RIGHTKIT_RUN_ROOT, which
+     * disposeQaWorkspace deletes, unless allowInsideRunRoot is set.
+     */
     directory: string;
     /** Short name used in the file names and the dump. Default 'wait'. */
     label?: string;
+    /**
+     * Opt-in: the directory may lie inside RIGHTKIT_RUN_ROOT. These files are deleted with the
+     * workspace by disposeQaWorkspace; copy them out before dispose. Default false.
+     */
+    allowInsideRunRoot?: boolean;
+    /**
+     * Host state to embed in the JSON dump under `extra` (bounded to 64 KiB, cut off after 1 s). A
+     * throw, a timeout or an unserialisable result is recorded under `extraError` and never masks the
+     * timeout.
+     */
+    extra?: () => unknown | Promise<unknown>;
 }
+/** 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. Reads the value back after insertion and throws FillMismatchError on a difference. Requires replace. */
-    verify?: 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 {
@@ -183,8 +216,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;
@@ -227,22 +269,29 @@ export declare class QaPage {
     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 (requires replace) the value is read back
-     * once after insertion and FillMismatchError is thrown on a difference.
+     * 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;
+    /** URL, title, bounded page text and the active element. Each part is null when unreadable; never throws. */
+    private failureState;
     /** 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>;
@@ -263,7 +312,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

@@ -31,6 +31,31 @@ export class FillMismatchError extends Error {
         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)
@@ -71,22 +96,53 @@ function exceptionEntry(event) {
 function failureTarget(options) {
     if (!options)
         return undefined;
-    const { directory, label } = options;
+    const { directory, label, extra, allowInsideRunRoot } = 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');
+    if (extra !== undefined && typeof extra !== 'function')
+        throw new Error('failureArtifacts.extra must be a function');
     const resolved = path.resolve(directory);
     const runRoot = process.env.RIGHTKIT_RUN_ROOT;
-    if (runRoot) {
+    if (runRoot && !allowInsideRunRoot) {
         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' };
+    return { directory: resolved, label: (label ?? 'wait').replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 60) || 'wait', extra };
 }
 let failureSequence = 0;
+/** Bounds for the failure dump: extra state, page text, and the time a host callback may take. */
+const EXTRA_LIMIT = 64 * 1024;
+const EXTRA_TIMEOUT_MS = 1_000;
+const PAGE_TEXT_LIMIT = 20_000;
+function errorText(error) { return error instanceof Error ? error.message : String(error); }
+/** Runs the host's extra callback under a bound, and keeps its JSON within EXTRA_LIMIT. Never throws. */
+async function runExtra(extra) {
+    if (!extra)
+        return { value: null, error: null };
+    let timer;
+    try {
+        const value = await Promise.race([
+            Promise.resolve().then(() => extra()),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`extra timed out after ${EXTRA_TIMEOUT_MS}ms`)), EXTRA_TIMEOUT_MS); }),
+        ]);
+        const json = JSON.stringify(value);
+        if (json === undefined)
+            return { value: null, error: null };
+        if (json.length > EXTRA_LIMIT)
+            return { value: { truncated: true, length: json.length, preview: json.slice(0, EXTRA_LIMIT) }, error: null };
+        return { value: JSON.parse(json), error: null };
+    }
+    catch (error) {
+        return { value: null, error: errorText(error) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function functionSource(fn) {
     const source = fn.toString();
@@ -445,12 +501,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++;
@@ -597,14 +668,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));
@@ -676,9 +769,13 @@ export class QaPage {
         const source = typeof fn === 'string' ? `function() { return (${fn}); }` : functionSource(fn);
         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;
@@ -702,8 +799,9 @@ export class QaPage {
             });
         }
         catch (error) {
-            if (artifacts && error instanceof TimeoutError)
+            if (artifacts && (error instanceof TimeoutError || (pollState.failed && pollState.error === error))) {
                 await this.attachFailureArtifacts(error, artifacts, source, timeout);
+            }
             throw error;
         }
     }
@@ -712,6 +810,8 @@ export class QaPage {
             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}`, timeout, async (remaining) => {
                 await this.waitForFunction((selector, visible, hidden) => {
@@ -721,7 +821,7 @@ 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());
             });
         }
@@ -732,6 +832,9 @@ export class QaPage {
                     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;
         }
     }
@@ -752,9 +855,9 @@ 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');
@@ -796,14 +899,17 @@ export class QaPage {
     }
     /**
      * 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 (requires replace) the value is read back
-     * once after insertion and FillMismatchError is thrown on a difference.
+     * 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');
-        if (options.verify && !options.replace)
+        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);
@@ -815,11 +921,19 @@ export class QaPage {
                 await this.keyboard.press('Backspace');
             else
                 await this.send('Input.insertText', { text: value });
-            if (options.verify) {
-                const actual = await handle.evaluate((element) => (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement ? element.value : element.textContent) ?? '');
-                if (actual !== value)
-                    throw new FillMismatchError(value.length, actual.length);
+            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) {
@@ -866,12 +980,38 @@ export class QaPage {
         if (occluder !== null)
             throw new ElementOccludedError(occluder, point);
     }
+    /** URL, title, bounded page text and the active element. Each part is null when unreadable; never throws. */
+    async failureState() {
+        try {
+            const raw = resultValue(await this.run(() => {
+                const el = document.activeElement;
+                const attr = (name) => el?.getAttribute(name) || undefined;
+                return {
+                    url: location.href,
+                    title: document.title,
+                    text: document.body ? document.body.innerText : '',
+                    // Descriptor only: never the value, which may be a secret.
+                    active: el ? { tag: el.tagName.toLowerCase(), id: el.id || undefined, name: attr('name'), type: attr('type'), role: attr('role'), ariaLabel: attr('aria-label') } : null,
+                };
+            }, [], true, 2_000)) ?? {};
+            const text = typeof raw.text === 'string' ? raw.text : '';
+            return {
+                url: typeof raw.url === 'string' ? raw.url : null,
+                title: typeof raw.title === 'string' ? raw.title : null,
+                pageText: { text: text.slice(0, PAGE_TEXT_LIMIT), truncated: text.length > PAGE_TEXT_LIMIT, length: text.length },
+                activeElement: raw.active ?? null,
+            };
+        }
+        catch {
+            return { url: null, title: null, pageText: null, activeElement: null };
+        }
+    }
     /** 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`);
+    async captureFailure(target, predicate, timeout) {
+        await mkdir(target.directory, { recursive: true });
+        const stem = `${target.label}-${Date.now()}-${++failureSequence}`;
+        const json = path.join(target.directory, `${stem}.json`);
+        const png = path.join(target.directory, `${stem}.png`);
         let screenshot;
         let screenshotError;
         try {
@@ -879,40 +1019,48 @@ export class QaPage {
             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)) ?? {};
+            screenshotError = errorText(error);
         }
-        catch { /* page gone or stuck: the dump records no url or title */ }
+        const state = await this.failureState();
+        const extra = await runExtra(target.extra);
         const dump = {
-            label,
+            label: target.label,
             predicate,
             timeoutMs: timeout,
             timestamp: new Date().toISOString(),
-            url: where.url ?? null,
-            title: where.title ?? null,
+            url: state.url,
+            title: state.title,
+            pageText: state.pageText,
+            activeElement: state.activeElement,
             screenshot: screenshot ? path.basename(screenshot) : null,
             screenshotError: screenshotError ?? null,
             console: this.consoleEntries(),
+            extra: extra.value,
+            extraError: extra.error,
         };
         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 {
-            error.artifacts = await this.captureFailure(target.directory, target.label, predicate, timeout);
+            const written = await this.captureFailure(target, predicate, timeout);
+            if (error instanceof TimeoutError)
+                error.artifacts = written;
         }
         catch (captureError) {
-            error.message += ` (failure artifacts were not written: ${captureError instanceof Error ? captureError.message : String(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)
@@ -940,10 +1088,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);
         });
@@ -1009,7 +1158,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;
@@ -25,3 +26,37 @@ export declare function runOwnedProcess(command: string, args?: string[], option
 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

@@ -133,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.4",
+  "version": "0.4.6",
   "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.5"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",