@rightkit/qa 0.4.0 → 0.4.2

package/README.md

@@ -1,73 +1,106 @@
-# `@rightkit/qa`
+# @rightkit/qa
 
-> **Which QA tool?** To drive a Right Suite desktop app under test, use the Rust **`rightkit-qa`** crate with **`rightkit-control`**; that is the one supported engine. For a test browser only, use the zero-dependency **`@rightkit/qa-chrome`**. For an agent driving an installed app, use **`right-ctl`**. This package's WebdriverIO native lane & `right-qa` CLI were removed in 0.3.0.
+Shared browser and QA primitives for Right Suite apps: run storage and evidence bundles, bearer-authenticated loopback control, owned-process cleanup, pane and frame checks, paint checks, workspace environment, a raw Chrome DevTools Protocol page driver, and the Chrome for Testing re-export.
 
-Shared QA primitives for Right Suite desktop apps. The package owns run locking, bearer-authenticated loopback control, deterministic evidence bundles, exact owned-process cleanup, and the guard that keeps development WebDriver access out of production builds.
-
-This package is intentionally private until the Windows and macOS phase gate passes. App repositories must never consume it through a Git, path, `file:`, `link:`, or `workspace:` dependency; adoption happens only after a registry version is published.
-
-## Run storage
-
-Run roots, harness evidence, captures & summaries remain under `<managed>/runs/<app>/<run-id>`. App homes, profiles, service/port files, live logs & app-provided output paths use an owned internal system-temp companion recorded as `appRoot` in `.rightkit-run.json`. On macOS, companions always use `/private/tmp/rightkit-qa/<app-prefix>-<random>` with short names so launchd can open app files & control socket paths fit `sockaddr_un`.
-
-Finish copies app logs to managed `evidence/`, app-written evidence to `evidence/app/` & app captures to `captures/` before releasing ownership. Disposal removes temp companions; failed copies or cleanup preserve ownership metadata for recovery. Retention & orphan pruning validate companion bindings & protect live runs.
-
-Workspace env sets `RIGHTKIT_RUN_ROOT`, `HOME` & `USERPROFILE` to `home`; `RIGHTKIT_SUITE_ROOT` to `home/suite`; data/profile keys to `home/data`; `XDG_CACHE_HOME` to `home/cache`; `TMPDIR`, `TMP` & `TEMP` to `home/tmp`. `RIGHTKIT_QA_EVIDENCE_DIR` & `RIGHTKIT_QA_CAPTURE_DIR` use `home/evidence` & `home/captures`. The JS package supplies workspace env; native UI bundle staging & unique per-launch suite/service identity belong to Rust `control::launch`.
+| Item | Value |
+|---|---|
+| Where it runs | Dev and test tooling (Node, and browser-driven test harnesses) |
+| Rust pair | None declared. For native desktop QA use the Rust `rightkit-qa` crate with `rightkit-control`. |
+| Version | see INDEX.md |
+| License | MIT OR Apache-2.0 |
 
-## Chrome for Testing (`@rightkit/qa/chrome`)
+## Entry points
 
-Web/CDP harnesses launch Chrome for Testing, never regular Google Chrome: on macOS each regular Chrome instance clones its app bundle under `<DARWIN_USER_TEMP_DIR>/../X/com.google.Chrome.code_sign_clone/`, and a killed instance leaks that clone.
+| 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/chrome` | Re-export of `@rightkit/qa-chrome` |
 
-- `resolveChromeForTesting({ executablePath? })` resolves the explicit option, then `RIGHTKIT_CHROME_FOR_TESTING`, then `/Applications` and `~/Applications` app installs, then the newest Puppeteer (`~/.cache/puppeteer`, `PUPPETEER_CACHE_DIR`) and Playwright (`~/Library/Caches/ms-playwright`, `PLAYWRIGHT_BROWSERS_PATH`) builds. It throws `ChromeForTestingNotFoundError` with install instructions; it never falls back. `findChromeForTesting()` returns `{ path }` or `{ reason }` for test skips.
-- `launchChromeForTesting(options)` starts it in its own process group with a temp profile and returns `{ wsEndpoint, port, pid, profileDir, close() }`. Launch one browser per suite and open targets per test.
-- `close()` / `closeChromeGracefully()` sends CDP `Browser.close`, waits up to 5 s, sends SIGTERM to the process group (`taskkill /T` on Windows), waits again, sends SIGKILL only last, then removes the profile. It reports the step that ended the tree.
-- `codeSignCloneEntries()` lists the macOS clone entries so tests can assert that none appear.
+Dependency: `@rightkit/qa-chrome` (exact `0.1.3`).
 
-## Raw CDP page driver (Node 26)
+Peer dependencies: none.
 
-`QaBrowserSession`, `QaPage`, `QaElement`, `QaKeyboard` & `TimeoutError` are exported from `@rightkit/qa`. Transport uses Node's built-in `WebSocket` directly; no Puppeteer, Playwright, or CDP wrapper dependency.
+## Example
 
 ```ts
-import { launchChromeForTesting, QaBrowserSession } from '@rightkit/qa';
+import { launchChromeForTesting, QaBrowserSession } from "@rightkit/qa";
 
 const chrome = await launchChromeForTesting();
 const browser = await QaBrowserSession.connect(chrome.wsEndpoint);
 try {
   const page = await browser.newPage();
   await page.setViewport({ width: 1280, height: 720, deviceScaleFactor: 1 });
-  await page.evaluateOnNewDocument(() => { window.localStorage.setItem('qa', '1'); });
-  await page.goto('http://127.0.0.1:3000', { waitUntil: 'networkidle0', timeout: 10_000 });
-  const button = await page.waitForSelector('button', { visible: true });
+  await page.goto("http://127.0.0.1:3000", { waitUntil: "networkidle0", timeout: 10_000 });
+  const button = await page.waitForSelector("button", { visible: true });
   await button?.click();
-  await button?.dispose();
-  await page.screenshot({ path: 'viewport.png', type: 'png', captureBeyondViewport: false });
+  await page.screenshot({ path: "viewport.png" });
 } finally {
   try { await browser.close(); } finally { await chrome.close(); }
 }
 ```
 
-Session owns targets it creates; launcher owns browser process & profile. `connect(endpoint, { timeout, debug })` defaults to 30,000 ms per connection/command, with logging off. Positive finite deadlines apply to navigation & waits; failures use typed `TimeoutError`. `page.on(cdpMethod, listener)` subscribes to page-session events & returns an unsubscribe function. Debug callbacks receive method names only. Throwing event subscribers are isolated from transport state.
+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`).
 
-Evaluation uses main frame's default execution context, awaits promises & returns values by JSON. Functions run in Chrome, so pass external values as arguments rather than closing over Node variables. JavaScript exceptions become `Error` with Chrome's message. `evaluateOnNewDocument` accepts function + arguments or source text & runs before document scripts, including subsequent reloads.
+## Attach to a running app and drive its mouse
 
-`goto`/`reload` support `load`, `domcontentloaded` & `networkidle0` (zero outstanding requests for 500 ms). `waitForSelector` supports present/visible/hidden states; hidden waits return `null`. `waitForFunction` supports animation-frame or positive millisecond polling & resolves when predicate is truthy. Both name selector/predicate in timeout errors. `$`/`$$` return remote element handles, released by `dispose()`, navigation, or page closure.
+`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.
 
-Click/hover scroll elements into view & use box centres. Mouse, keyboard & text input use CDP `Input` commands; `select` dispatches DOM `input`/`change` after selecting values. Keyboard supports required navigation/editing keys, letters/digits & modifier chords such as `Control+A`, `Meta+A`, or `Shift+ArrowLeft`. Screenshots return `Buffer`, optionally write `path`, & capture viewport PNG at configured DPR; `fullPage` & `captureBeyondViewport` support `false` only.
+- `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.
 
-| Puppeteer | QaPage equivalent |
-|---|---|
-| `puppeteer.connect({ browserWSEndpoint })` | `QaBrowserSession.connect(wsEndpoint)` |
-| `browser.newPage()` / `browser.close()` | Same calls; session closes owned targets |
-| `page.goto()` / `reload()` / `close()` | Same calls & navigation options |
-| `page.setViewport()` | Same call; CDP device metrics |
-| `page.evaluateOnNewDocument()` | Same call; function or source |
-| `page.evaluate()` / `$eval()` / `$$eval()` | Same calls; JSON results & awaited promises |
-| `page.waitForSelector()` | Same options; `QaElement` or `null` |
-| `page.waitForFunction()` | Same predicate/options/arguments; returns `void` |
-| `page.$()` / `page.$$()` | `QaElement` / `QaElement[]` |
-| `element.click/type/hover/focus/boundingBox/evaluate/dispose()` | Same calls on `QaElement` |
-| `page.click/type/hover/focus/select()` | Same calls; click accepts selector or handle |
-| `page.keyboard.press()` | Same call; named key or modifier chord |
-| `page.screenshot()` | Viewport PNG `Buffer`; optional `path` |
-
-`pnpm --dir packages/qa test` runs mock-WebSocket unit tests & real Chrome for Testing integration against local static fixture. Install Chrome through `@rightkit/qa-chrome` or set `RIGHTKIT_CHROME_FOR_TESTING`; integration requires Chrome & does not silently skip.
+`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.
+
+## 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).
+- Three consumers pin three different versions of `@rightkit/qa-chrome` as dev dependencies (npm audit 2026-10-08).

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,16 +43,46 @@ 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;
     close(): Promise<void>;
@@ -60,7 +92,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 +110,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 +122,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,7 +205,7 @@ 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;
@@ -81,7 +218,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 +235,9 @@ export class QaPage {
     targetId;
     sessionId;
     onClosed;
+    owned;
     keyboard;
+    mouse;
     frameId;
     contexts = new Map();
     contextId;
@@ -114,13 +253,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 +353,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 +622,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 +651,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -37,12 +37,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bogusyogi/claude.git",
-    "directory": "tools/rightkit/packages/qa"
+    "url": "git+https://github.com/bogusyogi/rightkit.git",
+    "directory": "packages/qa"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run && node --test public-storage.test.mjs"
+    "test": "pnpm --filter @rightkit/qa-chrome build && pnpm run build && vitest run && node --test public-storage.test.mjs"
   }
 }