@rightkit/qa 0.4.1 → 0.4.3

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`, `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`. |
 | `@rightkit/qa/chrome` | Re-export of `@rightkit/qa-chrome` |
 
 Dependency: `@rightkit/qa-chrome` (exact `0.1.3`).
@@ -41,6 +41,87 @@ try {
 
 The page driver uses Node's built-in `WebSocket`. It has no Puppeteer or Playwright dependency. Method names mirror Puppeteer's for the common calls (`goto`, `click`, `evaluate`, `waitForSelector`, `screenshot`).
 
+## Attach to a running app and drive its mouse
+
+`QaBrowserSession.attach` connects to an app that is already running with a debugging port, such as an installed WebView2 app started with `--remote-debugging-port`. It reads the browser socket from `http://<host>:<port>/json/version`. It creates no target, and nothing it attaches to is closed.
+
+- `pages()` lists page targets (`targetId`, `url`, `title`).
+- `attachPage(targetId)` or `attachPage(info => ...)` (the predicate must match exactly one page) returns a `QaPage` attached with `Target.attachToTarget`, flattened.
+- `close()` on an attached page detaches it. Closing the session detaches every attached page. Neither sends `Target.closeTarget`.
+- The host defaults to `127.0.0.1`. Any other host, and any browser socket on another host, is refused unless `allowRemoteHost: true`. A debugging port controls the whole app, so only allow a machine you control.
+
+`page.mouse` holds the pointer position and pressed buttons. A move while a button is held sends the matching `buttons` mask. `page.click` and `page.hover` send their own events, so release any held mouse button before calling them.
+
+Hover, pressed and after-click capture of a control in a running app:
+
+```ts
+import { QaBrowserSession } from "@rightkit/qa";
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 120));
+const browser = await QaBrowserSession.attach({ port: 9333 }); // host defaults to 127.0.0.1
+try {
+  const [target] = await browser.pages();
+  if (!target) throw new Error("the app has no page target");
+  const page = await browser.attachPage(target.targetId);
+  const box = await (await page.$("#save"))?.boundingBox();
+  if (!box) throw new Error("#save is not visible");
+  const x = box.x + box.width / 2, y = box.y + box.height / 2;
+
+  await page.mouse.move(x, y, { steps: 4 });   // pointer rests on the control
+  await settle();
+  await page.screenshot({ path: "save-hover.png" });
+
+  await page.mouse.down();                     // held press, not yet released
+  await settle();
+  await page.screenshot({ path: "save-pressed.png" });
+
+  await page.mouse.up();                       // release on the control: this is the click
+  await settle();
+  await page.screenshot({ path: "save-after.png" });
+  await page.close();                          // detaches; the app's page stays open
+} finally {
+  await browser.close();                       // detaches attached pages; never closes the app
+}
+```
+
+`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.
+
+## 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.
+
+- Shifted symbols send Shift. `?` is Shift+`/`, `+` is Shift+`=`, `!` is Shift+`1`. Such a key carries `modifiers` 8 and its shifted `key` and `text`; no separate Shift key-down is sent.
+- Chords join parts with `+`. A literal plus key goes last: `+` and `Control++`.
+- `code` follows the US layout (`?` has code `Slash`). Other layouts are not modelled.
+
+## Browser escape hatch (unsupported surface)
+
+These methods expose Chrome's own DevTools protocol. Their names, params and results follow the browser version, not this package, and may break when Chrome changes. Use the typed `QaPage` API where it exists.
+
+- `browser.send(method, params?)` sends one browser-scoped command with no `sessionId` and resolves with its raw result.
+- `browser.version()` returns `Browser.getVersion`.
+- `browser.commandLine()` returns the browser argv from `Browser.getBrowserCommandLine` as `string[]`.
+
+`commandLine()` needs the browser launched with `--enable-automation`. `launchChromeForTesting` does not pass that flag, so launch with `launchChromeForTesting({ args: ["--enable-automation"] })`. Without it, the call rejects with an error that names the requirement; the browser is unchanged.
+
+## Run root and workspace disposal
+
+`createQaWorkspace` sets `RIGHTKIT_RUN_ROOT` to the workspace `home`. `disposeQaWorkspace` deletes that home, and deletes the workspace root too unless `keepEvidence` is set. A host must never map a directory that holds artifacts it wants to keep onto `RIGHTKIT_RUN_ROOT`, or onto the workspace root or home. Copy artifacts out before disposal, or use `keepEvidence: true` and keep anything written under `evidence` or `captures`.
+
+## Ownership: this package versus the Rust `rightkit-qa` crate
+
+Both runners stay. Pick by what the test drives.
+
+| Surface | Owner | Evidence in code |
+|---|---|---|
+| Browser page (any web app in Chrome for Testing) | `@rightkit/qa` and `@rightkit/qa-chrome` | `src/page.ts` (`QaBrowserSession`, `QaPage`), `@rightkit/qa-chrome` `launchChromeForTesting` |
+| Pane, frame and paint checks on a browser page | `@rightkit/qa` | `src/panes.ts`, `src/frames.ts`, `src/paint.ts` |
+| macOS native app | Rust `rightkit-qa` (`control::launch`, in-app `rightkit-control` server) | `crates/rightkit-qa/src/control.rs` |
+| Windows WebView2 (Tauri) app | Rust `rightkit-qa` (embedded control server on a named pipe) | `crates/rightkit-qa/src/control.rs`, `suite.rs` |
+| Engine (CLI words, framed stdio sidecar) | Rust `rightkit-qa` (`engine::EngineTarget`) | `crates/rightkit-qa/src/engine.rs` |
+
+This package launches no native app and no WebView2 window; it never replaces the Rust crate for them.
+
 ## 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).

package/dist/keyboard.d.ts

@@ -4,6 +4,9 @@ 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. */
+    /**
+     * Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft, F3, ?, Control+/.
+     * Function keys F1-F24 and US-layout printable keys (shifted ones included) are supported.
+     */
     press(chord: string): Promise<void>;
 }

package/dist/keyboard.js

@@ -6,45 +6,89 @@ const special = {
     Shift: ['ShiftLeft', 16], Control: ['ControlLeft', 17], Alt: ['AltLeft', 18], Meta: ['MetaLeft', 91],
 };
 export const modifierBits = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+/** Function keys F1-F24: code "F<n>", Windows virtual key 111 + n (VK_F1 = 112 ... VK_F24 = 135). */
+const functionKey = /^F(?:[1-9]|1\d|2[0-4])$/;
+/** [base, shifted, code, Windows virtual key] for each US-layout punctuation key. */
+const punctuation = [
+    ['`', '~', 'Backquote', 192], ['-', '_', 'Minus', 189], ['=', '+', 'Equal', 187],
+    ['[', '{', 'BracketLeft', 219], [']', '}', 'BracketRight', 221], ['\\', '|', 'Backslash', 220],
+    [';', ':', 'Semicolon', 186], ["'", '"', 'Quote', 222], [',', '<', 'Comma', 188],
+    ['.', '>', 'Period', 190], ['/', '?', 'Slash', 191],
+];
+const shiftedDigits = ')!@#$%^&*(';
+/** Keyed by the character the key prints, so "?" and "/" both resolve, the first with Shift forced. */
+const printable = new Map();
+for (const [base, shifted, code, keyCode] of punctuation) {
+    printable.set(base, { base, shifted, code, keyCode, requiresShift: false });
+    printable.set(shifted, { base, shifted, code, keyCode, requiresShift: true });
+}
+for (let digit = 0; digit <= 9; digit++) {
+    const base = String(digit), code = `Digit${digit}`, keyCode = 48 + digit;
+    printable.set(base, { base, shifted: shiftedDigits[digit], code, keyCode, requiresShift: false });
+    printable.set(shiftedDigits[digit], { base, shifted: shiftedDigits[digit], code, keyCode, requiresShift: true });
+}
 export function keyDefinition(key, modifiers) {
     const named = special[key];
-    let code, windowsVirtualKeyCode, text;
-    if (named)
+    let code, windowsVirtualKeyCode, text, unmodifiedText;
+    let effective = modifiers;
+    if (named) {
         [code, windowsVirtualKeyCode, text] = named;
+        unmodifiedText = text;
+    }
+    else if (functionKey.test(key)) {
+        code = key;
+        windowsVirtualKeyCode = 111 + Number(key.slice(1));
+    }
     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;
+        unmodifiedText = code.slice(3).toLowerCase();
     }
-    else if (/^[0-9]$/.test(key)) {
-        code = `Digit${key}`;
-        windowsVirtualKeyCode = key.charCodeAt(0);
-        key = modifiers & 8 ? ')!@#$%^&*('[Number(key)] : key;
+    else if (printable.has(key)) {
+        const symbol = printable.get(key);
+        code = symbol.code;
+        windowsVirtualKeyCode = symbol.keyCode;
+        if (symbol.requiresShift)
+            effective |= 8;
+        key = effective & 8 ? symbol.shifted : symbol.base;
         text = key;
+        unmodifiedText = symbol.base;
     }
     else if (key === ' ') {
         code = 'Space';
         windowsVirtualKeyCode = 32;
         text = ' ';
+        unmodifiedText = ' ';
     }
     else
         throw new Error(`Unsupported key: ${key}`);
     if (key === 'Space')
         key = ' ';
-    if (modifiers & (1 | 2 | 4))
+    if (effective & (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 } : {}) };
+    return { key, code, windowsVirtualKeyCode, modifiers: effective, ...(text ? { text, unmodifiedText } : {}) };
+}
+/** Splits "Control+A" into parts. A literal plus key is the last part: "+" and "Control++". */
+function splitChord(chord) {
+    if (chord === '+')
+        return ['+'];
+    if (chord.endsWith('++'))
+        return [...chord.slice(0, -2).split('+'), '+'];
+    return chord.split('+');
 }
 export class QaKeyboard {
     send;
     constructor(send) {
         this.send = send;
     }
-    /** Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft. */
+    /**
+     * Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft, F3, ?, Control+/.
+     * Function keys F1-F24 and US-layout printable keys (shifted ones included) are supported.
+     */
     async press(chord) {
-        const parts = chord.split('+');
+        const parts = splitChord(chord);
         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.

package/dist/mouse.d.ts

@@ -0,0 +1,39 @@
+import type { CdpParams } from './cdp.js';
+export type MouseButton = 'left' | 'right' | 'middle';
+export interface MouseMoveOptions {
+    steps?: number;
+}
+export interface MouseButtonOptions {
+    button?: MouseButton;
+    clickCount?: number;
+}
+export interface MousePosition {
+    x: number;
+    y: 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`.
+ */
+export declare class QaMouse {
+    private send;
+    private x;
+    private y;
+    /** Held buttons in press order, with the clickCount each was pressed with. */
+    private held;
+    constructor(send: (method: string, params: CdpParams) => Promise<CdpParams>);
+    /** Last position this object sent or observed; starts at (0, 0). */
+    position(): MousePosition;
+    /** Move to (x, y), optionally in linear intermediate steps. Dispatches mouseMoved per step. */
+    move(x: number, y: number, options?: MouseMoveOptions): Promise<void>;
+    /** Press a button at the current position and keep it held until `up`. */
+    down(options?: MouseButtonOptions): Promise<void>;
+    /** Release a held button at the current position. */
+    up(options?: MouseButtonOptions): 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. */
+    assertReleased(): void;
+    private mask;
+    private pressedState;
+}

package/dist/mouse.js

@@ -0,0 +1,82 @@
+/** CDP `buttons` bit per button. */
+const buttonBits = { left: 1, right: 2, middle: 4 };
+function checkButton(button) {
+    if (!(button in buttonBits))
+        throw new Error(`Unsupported button: ${button}`);
+    return button;
+}
+function checkCoordinates(x, y) {
+    if (!Number.isFinite(x) || !Number.isFinite(y))
+        throw new Error('Mouse coordinates must be finite numbers');
+}
+/**
+ * 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`.
+ */
+export class QaMouse {
+    send;
+    x = 0;
+    y = 0;
+    /** Held buttons in press order, with the clickCount each was pressed with. */
+    held = new Map();
+    constructor(send) {
+        this.send = send;
+    }
+    /** Last position this object sent or observed; starts at (0, 0). */
+    position() { return { x: this.x, y: this.y }; }
+    /** Move to (x, y), optionally in linear intermediate steps. Dispatches mouseMoved per step. */
+    async move(x, y, options = {}) {
+        const steps = options.steps ?? 1;
+        if (!Number.isInteger(steps) || steps < 1)
+            throw new Error('Mouse move steps must be a positive integer');
+        checkCoordinates(x, y);
+        const [fromX, fromY] = [this.x, this.y];
+        const [button, buttons] = this.pressedState();
+        for (let step = 1; step <= steps; step++) {
+            const nextX = step === steps ? x : fromX + ((x - fromX) * step) / steps;
+            const nextY = step === steps ? y : fromY + ((y - fromY) * step) / steps;
+            await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: nextX, y: nextY, button, buttons });
+            this.x = nextX;
+            this.y = nextY;
+        }
+    }
+    /** Press a button at the current position and keep it held until `up`. */
+    async down(options = {}) {
+        const button = checkButton(options.button ?? 'left');
+        const clickCount = options.clickCount ?? 1;
+        if (!Number.isInteger(clickCount) || clickCount < 1)
+            throw new Error('Mouse clickCount must be a positive integer');
+        if (this.held.has(button))
+            throw new Error(`Mouse ${button} button already pressed`);
+        const buttons = this.mask() | buttonBits[button];
+        await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: this.x, y: this.y, button, buttons, clickCount });
+        this.held.set(button, clickCount);
+    }
+    /** Release a held button at the current position. */
+    async up(options = {}) {
+        const button = checkButton(options.button ?? 'left');
+        const clickCount = this.held.get(button);
+        if (clickCount === undefined)
+            throw new Error(`Mouse ${button} button not pressed`);
+        const buttons = this.mask() & ~buttonBits[button];
+        await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: this.x, y: this.y, button, buttons, clickCount });
+        this.held.delete(button);
+    }
+    /** @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. */
+    assertReleased() {
+        if (this.held.size)
+            throw new Error('Release page.mouse buttons before page click or hover');
+    }
+    mask() {
+        let buttons = 0;
+        for (const button of this.held.keys())
+            buttons |= buttonBits[button];
+        return buttons;
+    }
+    pressedState() {
+        const last = [...this.held.keys()].at(-1);
+        return [last ?? 'none', this.mask()];
+    }
+}

package/dist/page.d.ts

@@ -1,7 +1,9 @@
 import { CdpClient, type CdpParams, type QaConnectOptions } from './cdp.js';
 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 interface NavigationOptions {
     waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0';
     timeout?: number;
@@ -41,18 +43,63 @@ export interface BoundingBox {
     width: number;
     height: number;
 }
+/** One page target listed by the browser. */
+export interface QaPageInfo {
+    targetId: string;
+    url: string;
+    title: string;
+}
+export interface QaAttachOptions extends QaConnectOptions {
+    /** Debugging port on `host`; the browser socket is read from http://<host>:<port>/json/version. Give this or httpEndpoint. */
+    port?: number;
+    /** Full http or https origin of the debugging endpoint, e.g. http://127.0.0.1:9333. Give this or port. */
+    httpEndpoint?: string;
+    /** Default 127.0.0.1. */
+    host?: string;
+    /** Default false. A debugging port is full control of the app; allow a non-loopback host only for a machine you control. */
+    allowRemoteHost?: boolean;
+}
 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 openPages;
     private closed;
     private closing?;
     private opening;
     private constructor();
     static connect(wsEndpoint: string, options?: QaConnectOptions): Promise<QaBrowserSession>;
+    /**
+     * Attach to a browser that is already running with a debugging port (for example an installed
+     * WebView2 app). Reads the browser socket from /json/version. Never creates or closes targets:
+     * use pages() and attachPage() to reach the app's own pages.
+     */
+    static attach(options?: QaAttachOptions): Promise<QaBrowserSession>;
+    /** Page targets (type "page") the browser lists now. Read only. */
+    pages(): Promise<QaPageInfo[]>;
+    /**
+     * Attach to an existing page by target id, or by a predicate that must match exactly one page.
+     * The returned QaPage detaches on close; it never closes the app's target.
+     */
+    attachPage(target: string | ((info: QaPageInfo) => boolean)): Promise<QaPage>;
+    private attachExisting;
     newPage(): Promise<QaPage>;
     private createPage;
+    /**
+     * UNSUPPORTED escape hatch: sends one browser-scoped CDP command (no sessionId) and resolves
+     * with its raw result. The protocol is Chrome's, not this package's: method names, params and
+     * results may change or disappear with a browser version. Prefer the typed QaPage API.
+     */
+    send(method: string, params?: CdpParams): Promise<CdpParams>;
+    /** Browser.getVersion (unsupported surface, see send). Read only. */
+    version(): Promise<CdpParams>;
+    /**
+     * Browser argv via Browser.getBrowserCommandLine (unsupported surface, see send). The browser
+     * answers only when it was launched with --enable-automation; launchChromeForTesting passes no
+     * such flag by default, so pass { args: ['--enable-automation'] } to use this. A refusal rejects
+     * with an error that names the requirement; the browser is not changed.
+     */
+    commandLine(): Promise<string[]>;
     close(): Promise<void>;
 }
 export declare class QaPage {
@@ -60,7 +107,9 @@ export declare class QaPage {
     readonly targetId: string;
     private sessionId;
     private onClosed;
+    private owned;
     readonly keyboard: QaKeyboard;
+    readonly mouse: QaMouse;
     private frameId?;
     private contexts;
     private contextId?;
@@ -76,8 +125,8 @@ export declare class QaPage {
     private generation;
     private navigating;
     private get objectGroup();
-    /** @internal Use QaBrowserSession.newPage(). */
-    constructor(client: CdpClient, targetId: string, sessionId: string, onClosed: () => void);
+    /** @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);
     private chooseContext;
     /** Subscribe to this page's raw CDP events; returned function unsubscribes. */
     on(method: string, listener: (params: CdpParams) => void): () => void;
@@ -88,6 +137,7 @@ export declare class QaPage {
     private invalidateHandles;
     /** @internal */
     markClosed(error?: Error): void;
+    /** Owned pages (newPage) close their target. Attached pages (attachPage) only detach; the app's page stays open. */
     close(): Promise<void>;
     private bounded;
     private mainContext;

package/dist/page.js

@@ -1,8 +1,10 @@
 import { writeFile } from 'node:fs/promises';
 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';
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function functionSource(fn) {
     const source = fn.toString();
@@ -34,10 +36,71 @@ function resultValue(result) {
     }
     return result.result?.value;
 }
+const LOOPBACK_NAMES = new Set(['localhost', '::1']);
+/** Bare host name (IPv6 without brackets) for a URL hostname or a host option. */
+function bareHost(host) { return host.replace(/^\[(.*)\]$/, '$1'); }
+function isLoopback(host) {
+    const bare = bareHost(host);
+    return LOOPBACK_NAMES.has(bare) || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(bare);
+}
+function assertDebugHost(host, allowRemoteHost, what) {
+    if (allowRemoteHost || isLoopback(host))
+        return;
+    throw new Error(`Refusing non-loopback ${what} ${host}: a debugging port controls the whole app. Pass allowRemoteHost: true only for a machine you control.`);
+}
+function debugOrigin(options) {
+    const given = [options.port !== undefined, options.httpEndpoint !== undefined].filter(Boolean).length;
+    if (given !== 1)
+        throw new Error('Pass exactly one of port or httpEndpoint');
+    if (options.httpEndpoint !== undefined) {
+        let url;
+        try {
+            url = new URL(options.httpEndpoint);
+        }
+        catch {
+            throw new Error('httpEndpoint must be an http or https URL');
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            throw new Error('httpEndpoint must be an http or https URL');
+        return url;
+    }
+    const port = options.port;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error('Port must be an integer from 1 to 65535');
+    const host = options.host ?? '127.0.0.1';
+    const authority = host.includes(':') ? `[${bareHost(host)}]` : host;
+    try {
+        return new URL(`http://${authority}:${port}`);
+    }
+    catch {
+        throw new Error('Debugging host is not a valid host name');
+    }
+}
+async function readVersion(origin, timeout) {
+    const url = new URL('/json/version', origin);
+    let response;
+    try {
+        // Redirects are refused so the request cannot be bounced to another host.
+        response = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(timeout) });
+    }
+    catch (error) {
+        if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError'))
+            throw new TimeoutError(`Debugging endpoint ${origin.origin} timed out after ${timeout}ms`);
+        throw new Error(`Could not reach debugging endpoint ${origin.origin}`);
+    }
+    if (!response.ok)
+        throw new Error(`Debugging endpoint ${url.pathname} answered ${response.status}`);
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new Error(`Debugging endpoint ${url.pathname} did not return JSON`);
+    }
+}
 /** Owns only targets it creates; launcher owns browser process & profile cleanup. */
 export class QaBrowserSession {
     client;
-    pages = new Set();
+    openPages = new Set();
     closed = false;
     closing;
     opening = new Set();
@@ -47,6 +110,80 @@ export class QaBrowserSession {
     static async connect(wsEndpoint, options = {}) {
         return new QaBrowserSession(await CdpClient.connect(wsEndpoint, options));
     }
+    /**
+     * Attach to a browser that is already running with a debugging port (for example an installed
+     * WebView2 app). Reads the browser socket from /json/version. Never creates or closes targets:
+     * use pages() and attachPage() to reach the app's own pages.
+     */
+    static async attach(options = {}) {
+        const timeout = validateTimeout(options.timeout ?? 30_000);
+        const origin = debugOrigin(options);
+        assertDebugHost(origin.hostname, options.allowRemoteHost, 'debugging host');
+        const version = await readVersion(origin, timeout);
+        const socketUrl = version.webSocketDebuggerUrl;
+        if (typeof socketUrl !== 'string' || !socketUrl)
+            throw new Error('/json/version has no webSocketDebuggerUrl');
+        let socket;
+        try {
+            socket = new URL(socketUrl);
+        }
+        catch {
+            throw new Error('webSocketDebuggerUrl is not a valid URL');
+        }
+        if (socket.protocol !== 'ws:' && socket.protocol !== 'wss:')
+            throw new Error('webSocketDebuggerUrl must be a ws or wss URL');
+        assertDebugHost(socket.hostname, options.allowRemoteHost, 'browser socket host');
+        return new QaBrowserSession(await CdpClient.connect(socketUrl, { timeout, debug: options.debug }));
+    }
+    /** Page targets (type "page") the browser lists now. Read only. */
+    async pages() {
+        if (this.closed)
+            throw new Error('Browser session closed');
+        const { targetInfos } = await this.client.send('Target.getTargets');
+        return targetInfos
+            .filter((info) => info.type === 'page')
+            .map((info) => ({ targetId: info.targetId, url: info.url, title: info.title }));
+    }
+    /**
+     * Attach to an existing page by target id, or by a predicate that must match exactly one page.
+     * The returned QaPage detaches on close; it never closes the app's target.
+     */
+    attachPage(target) {
+        if (this.closed)
+            return Promise.reject(new Error('Browser session closed'));
+        const pending = this.attachExisting(target);
+        this.opening.add(pending);
+        void pending.then(() => this.opening.delete(pending), () => this.opening.delete(pending));
+        return pending;
+    }
+    async attachExisting(target) {
+        const pages = await this.pages();
+        let info;
+        if (typeof target === 'string') {
+            info = pages.find((page) => page.targetId === target);
+            if (!info)
+                throw new Error(`No page target with id ${target}`);
+        }
+        else {
+            const matches = pages.filter(target);
+            if (matches.length !== 1)
+                throw new Error(`Predicate matched ${matches.length} pages; it must match exactly one`);
+            info = matches[0];
+        }
+        const { sessionId } = await this.client.send('Target.attachToTarget', { targetId: info.targetId, flatten: true });
+        const page = new QaPage(this.client, info.targetId, sessionId, () => this.openPages.delete(page), false);
+        this.openPages.add(page);
+        try {
+            await page.initialize();
+            if (this.closed)
+                throw new Error('Browser session closed');
+            return page;
+        }
+        catch (error) {
+            await page.close().catch(() => { }); // detach only
+            throw error;
+        }
+    }
     newPage() {
         if (this.closed)
             return Promise.reject(new Error('Browser session closed'));
@@ -59,8 +196,8 @@ export class QaBrowserSession {
         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);
+            const page = new QaPage(this.client, targetId, sessionId, () => this.openPages.delete(page));
+            this.openPages.add(page);
             await page.initialize();
             if (this.closed)
                 throw new Error('Browser session closed');
@@ -68,12 +205,51 @@ export class QaBrowserSession {
         }
         catch (error) {
             await this.client.send('Target.closeTarget', { targetId }).catch(() => { });
-            for (const page of this.pages)
+            for (const page of this.openPages)
                 if (page.targetId === targetId)
                     page.markClosed();
             throw error;
         }
     }
+    /**
+     * UNSUPPORTED escape hatch: sends one browser-scoped CDP command (no sessionId) and resolves
+     * with its raw result. The protocol is Chrome's, not this package's: method names, params and
+     * results may change or disappear with a browser version. Prefer the typed QaPage API.
+     */
+    send(method, params = {}) {
+        if (this.closed)
+            return Promise.reject(new Error('Browser session 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);
+    }
+    /** Browser.getVersion (unsupported surface, see send). Read only. */
+    version() {
+        return this.send('Browser.getVersion');
+    }
+    /**
+     * Browser argv via Browser.getBrowserCommandLine (unsupported surface, see send). The browser
+     * answers only when it was launched with --enable-automation; launchChromeForTesting passes no
+     * such flag by default, so pass { args: ['--enable-automation'] } to use this. A refusal rejects
+     * with an error that names the requirement; the browser is not changed.
+     */
+    async commandLine() {
+        let reply;
+        try {
+            reply = await this.send('Browser.getBrowserCommandLine');
+        }
+        catch (error) {
+            // CdpClient prefixes errors the browser itself returned with "CDP: "; timeouts and closed sockets pass through.
+            if (error instanceof Error && error.message.startsWith('CDP: ')) {
+                throw new Error(`Browser.getBrowserCommandLine was refused (${error.message.slice(5)}). It requires the browser to be launched with --enable-automation, e.g. launchChromeForTesting({ args: ['--enable-automation'] }).`, { cause: error });
+            }
+            throw error;
+        }
+        const argv = reply.arguments;
+        if (!Array.isArray(argv) || !argv.every((arg) => typeof arg === 'string'))
+            throw new Error('Browser.getBrowserCommandLine did not return an argument list');
+        return argv;
+    }
     close() {
         if (this.closing)
             return this.closing;
@@ -81,7 +257,7 @@ export class QaBrowserSession {
         this.closing = (async () => {
             try {
                 await Promise.allSettled([...this.opening]);
-                const results = await Promise.allSettled([...this.pages].map((page) => page.close()));
+                const results = await Promise.allSettled([...this.openPages].map((page) => page.close()));
                 const failed = results.find((result) => result.status === 'rejected');
                 if (failed?.status === 'rejected')
                     throw failed.reason;
@@ -98,7 +274,9 @@ export class QaPage {
     targetId;
     sessionId;
     onClosed;
+    owned;
     keyboard;
+    mouse;
     frameId;
     contexts = new Map();
     contextId;
@@ -114,13 +292,15 @@ export class QaPage {
     generation = 0;
     navigating = false;
     get objectGroup() { return `qa-elements-${this.generation}`; }
-    /** @internal Use QaBrowserSession.newPage(). */
-    constructor(client, targetId, sessionId, onClosed) {
+    /** @internal Use QaBrowserSession.newPage() or attachPage(). `owned` pages are closed on close(); attached ones only detach. */
+    constructor(client, targetId, sessionId, onClosed, owned = true) {
         this.client = client;
         this.targetId = targetId;
         this.sessionId = sessionId;
         this.onClosed = onClosed;
+        this.owned = owned;
         this.keyboard = new QaKeyboard((method, params) => this.send(method, params));
+        this.mouse = new QaMouse((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) {
@@ -212,15 +392,26 @@ export class QaPage {
         this.closedListeners.clear();
         this.onClosed();
     }
+    /** Owned pages (newPage) close their target. Attached pages (attachPage) only detach; the app's page stays open. */
     close() {
         if (this.closing)
             return this.closing;
         if (this.closed)
             return Promise.resolve();
         this.closing = (async () => {
+            if (this.owned) {
+                try {
+                    await this.client.send('Target.closeTarget', { targetId: this.targetId });
+                }
+                finally {
+                    this.markClosed();
+                }
+                return;
+            }
             try {
-                await this.client.send('Target.closeTarget', { targetId: this.targetId });
+                await this.client.send('Target.detachFromTarget', { sessionId: this.sessionId });
             }
+            catch { /* already detached: the local page is closed either way */ }
             finally {
                 this.markClosed();
             }
@@ -470,9 +661,11 @@ export class QaPage {
         return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
     }
     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;
             await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point });
+            this.mouse.track(point.x, point.y);
             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)
@@ -497,7 +690,12 @@ export class QaPage {
         }
     }
     async hover(target) {
-        await this.withElement(target, async (handle) => { await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...await this.point(handle) }); });
+        this.mouse.assertReleased();
+        await this.withElement(target, async (handle) => {
+            const point = await this.point(handle);
+            await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point });
+            this.mouse.track(point.x, point.y);
+        });
     }
     async focus(target) { await this.withElement(target, (handle) => handle.focus()); }
     async select(selector, ...values) {

package/dist/workspace.d.ts

@@ -31,6 +31,11 @@ export interface CreateQaWorkspaceOptions {
     leaseMs?: number;
     retention?: import('./storage.js').RetentionPolicy;
 }
+/**
+ * Create an isolated run home. `env.RIGHTKIT_RUN_ROOT` is set to `home`, which lives inside the
+ * workspace that {@link disposeQaWorkspace} deletes. A host must never map a directory holding
+ * artifacts it wants to keep onto RIGHTKIT_RUN_ROOT: disposal removes that tree.
+ */
 export declare function createQaWorkspace(options: CreateQaWorkspaceOptions): QaWorkspace;
 export interface DisposeOptions {
     /** Keep the recorded evidence and remove only the volatile profile. */
@@ -43,6 +48,11 @@ export interface DisposeOptions {
  * Remove the workspace, retrying through the brief window in which an exiting
  * app still holds its files open. Anything still present afterwards is returned,
  * never silently ignored.
+ *
+ * Deletes `workspace.home`, which is what RIGHTKIT_RUN_ROOT points at, and also
+ * `workspace.root` unless `keepEvidence` is set. Anything a host maps under
+ * RIGHTKIT_RUN_ROOT is deleted: never map a directory holding artifacts you want
+ * to keep onto it.
  */
 export declare function disposeQaWorkspace(workspace: QaWorkspace, options?: DisposeOptions): DisposeReport;
 /**

package/dist/workspace.js

@@ -18,6 +18,11 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createManagedRun, createManagedAppRoot, finishManagedRun, pruneManagedRuns, resolveManagedRoot, } from './storage.js';
+/**
+ * Create an isolated run home. `env.RIGHTKIT_RUN_ROOT` is set to `home`, which lives inside the
+ * workspace that {@link disposeQaWorkspace} deletes. A host must never map a directory holding
+ * artifacts it wants to keep onto RIGHTKIT_RUN_ROOT: disposal removes that tree.
+ */
 export function createQaWorkspace(options) {
     const appKey = requireText(options.appKey, 'appKey');
     const managed = createManagedRun({ managedRoot: options.root ? requireText(options.root, 'root') : resolveManagedRoot(), app: appKey, runId: options.runId ?? crypto.randomUUID(), leaseMs: options.leaseMs, retention: options.retention });
@@ -77,6 +82,11 @@ export function createQaWorkspace(options) {
  * Remove the workspace, retrying through the brief window in which an exiting
  * app still holds its files open. Anything still present afterwards is returned,
  * never silently ignored.
+ *
+ * Deletes `workspace.home`, which is what RIGHTKIT_RUN_ROOT points at, and also
+ * `workspace.root` unless `keepEvidence` is set. Anything a host maps under
+ * RIGHTKIT_RUN_ROOT is deleted: never map a directory holding artifacts you want
+ * to keep onto it.
  */
 export function disposeQaWorkspace(workspace, options = {}) {
     const attempts = Math.max(1, options.attempts ?? 5);

package/package.json

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