@rightkit/qa 0.1.0 → 0.2.1

package/dist/cli.js

@@ -4,7 +4,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { addEvidenceCheck, createEvidenceBundle, finishEvidenceBundle, writeEvidenceBundle, } from './evidence.js';
+import { addEvidenceArtifact, addEvidenceCheck, createEvidenceBundle, finishEvidenceBundle, writeEvidenceBundle, } from './evidence.js';
+import { createQaWorkspace, pruneAbandonedWorkspaces } from './workspace.js';
 import { createWdioConfig, defineRightQaConfig } from './native.js';
 import { acquireRunOwnership } from './ownership.js';
 import { runOwnedProcess } from './process.js';
@@ -17,10 +18,13 @@ export async function runNativeQa(rawConfig, options = {}) {
         throw new Error(`native QA binary not found: ${binary}`);
     const cacheRoot = path.resolve(app.appRoot, app.evidenceDir ?? '.cache/rightkit-qa');
     const runId = crypto.randomUUID();
-    const runRoot = path.join(cacheRoot, 'runs', runId);
+    // Earlier crashed runs left their directories behind; sweep them before adding
+    // one more, and never touch the run about to start.
+    pruneAbandonedWorkspaces(cacheRoot, { keep: [runId] });
+    const workspace = createQaWorkspace({ root: cacheRoot, runId, appKey: app.app });
+    const runRoot = workspace.root;
     const generatedConfig = path.join(runRoot, 'wdio.generated.mjs');
     const evidencePath = path.join(runRoot, 'evidence.json');
-    fs.mkdirSync(runRoot, { recursive: true });
     fs.writeFileSync(generatedConfig, [
         `import { Agent, setGlobalDispatcher } from ${JSON.stringify(resolveUndiciEntry())};`,
         'setGlobalDispatcher(new Agent());',
@@ -38,15 +42,21 @@ export async function runNativeQa(rawConfig, options = {}) {
             timeoutMs: options.timeoutMs ?? 5 * 60_000,
             env: {
                 ...process.env,
-                RIGHTKIT_QA_NATIVE: '1',
+                // The isolated data directory is what makes this a separate instance
+                // rather than a second claimant on the installed app's single-instance lock.
+                ...workspace.env,
                 RIGHTKIT_QA_HIDDEN: '1',
                 TAURI_WEBDRIVER_PORT: String(options.embeddedPort ?? 4445),
             },
         });
         const passed = result.code === 0;
+        // Bind the receipt to the driver log actually produced, so "the run passed"
+        // is checkable against bytes rather than taken on trust.
+        const logArtifacts = recordRunArtifacts(evidence, path.join(runRoot, 'wdio'));
         addEvidenceCheck(evidence, {
             name: 'wdio.run',
             status: passed ? 'passed' : 'failed',
+            artifacts: logArtifacts,
             details: {
                 code: result.code,
                 signal: result.signal,
@@ -113,6 +123,34 @@ function valueAfter(argv, flag) {
     const index = argv.indexOf(flag);
     return index >= 0 ? argv[index + 1] : undefined;
 }
+/**
+ * Hash whatever the driver actually wrote. Missing logs are simply not recorded
+ * — a check that references nothing is honest; a check that references a file
+ * that was never hashed is refused by addEvidenceCheck.
+ */
+function recordRunArtifacts(evidence, logDir) {
+    const names = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(logDir);
+    }
+    catch {
+        return names;
+    }
+    for (const entry of entries.sort()) {
+        const file = path.join(logDir, entry);
+        try {
+            if (!fs.statSync(file).isFile())
+                continue;
+            addEvidenceArtifact(evidence, { name: `wdio/${entry}`, path: file });
+            names.push(`wdio/${entry}`);
+        }
+        catch {
+            // An unreadable log is not evidence; leaving it unreferenced is the point.
+        }
+    }
+    return names;
+}
 function tail(value, maxLength = 4_000) {
     return value.length <= maxLength ? value : value.slice(-maxLength);
 }

package/dist/evidence.d.ts

@@ -1,12 +1,21 @@
 export type EvidenceCheckStatus = 'passed' | 'failed' | 'skipped';
 export type EvidenceRunStatus = 'running' | 'passed' | 'failed';
+export interface EvidenceArtifact {
+    name: string;
+    path: string;
+    sha256: string;
+    sizeBytes: number;
+    recordedAt: string;
+}
 export interface EvidenceCheck {
     name: string;
     status: EvidenceCheckStatus;
     details?: Record<string, unknown>;
+    /** Names of artifacts recorded via addEvidenceArtifact that back this check. */
+    artifacts?: string[];
 }
 export interface EvidenceBundle {
-    schemaVersion: 1;
+    schemaVersion: 2;
     app: string;
     platform: string;
     runId: string;
@@ -14,6 +23,7 @@ export interface EvidenceBundle {
     finishedAt?: string;
     status: EvidenceRunStatus;
     checks: EvidenceCheck[];
+    artifacts: EvidenceArtifact[];
 }
 export interface EvidenceBundleInput {
     app: string;
@@ -22,9 +32,25 @@ export interface EvidenceBundleInput {
     startedAt?: string;
 }
 export declare function createEvidenceBundle(input: EvidenceBundleInput): EvidenceBundle;
+/**
+ * Hash a file into the bundle. Reading happens now, not at write time, so a file
+ * that is later replaced or deleted cannot masquerade as the one that was seen.
+ */
+export declare function addEvidenceArtifact(bundle: EvidenceBundle, artifact: {
+    name: string;
+    path: string;
+}, now?: Date): EvidenceArtifact;
 export declare function addEvidenceCheck(bundle: EvidenceBundle, check: EvidenceCheck): void;
 export declare function finishEvidenceBundle(bundle: EvidenceBundle, result: {
     status: Exclude<EvidenceRunStatus, 'running'>;
     finishedAt?: string;
 }): void;
+/**
+ * Re-hash every recorded artifact. Returns the artifacts whose bytes no longer
+ * match — empty means the receipt still describes what is on disk.
+ */
+export declare function verifyEvidenceArtifacts(bundle: EvidenceBundle): Array<{
+    name: string;
+    reason: string;
+}>;
 export declare function writeEvidenceBundle(filePath: string, bundle: EvidenceBundle): void;

package/dist/evidence.js

@@ -1,30 +1,107 @@
+// A receipt that names a file without hashing it is a claim, not evidence.
+//
+// The previous bundle recorded check names, statuses, and free-form details, then
+// declared the run passed. Nothing tied those claims to the artifacts they were
+// about: a screenshot could be regenerated, truncated, or never written at all
+// and the receipt read exactly the same. "Signature verified" and "verified the
+// signature of THESE bytes" are different statements, and only the second one
+// survives someone asking later.
+//
+// So every artifact a check refers to is hashed at the moment it is recorded, a
+// check may only reference artifacts that were hashed, and the bundle can be
+// re-verified against the filesystem afterwards.
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 export function createEvidenceBundle(input) {
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         app: requireText(input.app, 'app'),
         platform: requireText(input.platform, 'platform'),
         runId: requireText(input.runId, 'runId'),
         startedAt: input.startedAt ?? new Date().toISOString(),
         status: 'running',
         checks: [],
+        artifacts: [],
     };
 }
+/**
+ * Hash a file into the bundle. Reading happens now, not at write time, so a file
+ * that is later replaced or deleted cannot masquerade as the one that was seen.
+ */
+export function addEvidenceArtifact(bundle, artifact, now = new Date()) {
+    requireRunning(bundle);
+    const name = requireText(artifact.name, 'artifact name');
+    if (bundle.artifacts.some((existing) => existing.name === name)) {
+        throw new Error(`QA evidence already records an artifact named ${name}`);
+    }
+    const resolved = path.resolve(requireText(artifact.path, 'artifact path'));
+    let bytes;
+    try {
+        bytes = fs.readFileSync(resolved);
+    }
+    catch (error) {
+        throw new Error(`cannot record QA evidence artifact ${name}: ${resolved} is unreadable (${error.message})`);
+    }
+    const recorded = {
+        name,
+        path: resolved,
+        sha256: crypto.createHash('sha256').update(bytes).digest('hex'),
+        sizeBytes: bytes.length,
+        recordedAt: now.toISOString(),
+    };
+    bundle.artifacts.push(recorded);
+    return recorded;
+}
 export function addEvidenceCheck(bundle, check) {
-    if (bundle.status !== 'running') {
-        throw new Error('cannot add a QA evidence check after the run has finished');
+    requireRunning(bundle);
+    const name = requireText(check.name, 'check name');
+    const artifacts = check.artifacts ?? [];
+    const unknown = artifacts.filter((reference) => !bundle.artifacts.some((item) => item.name === reference));
+    if (unknown.length > 0) {
+        throw new Error(`QA check ${name} references artifacts that were never hashed: ${unknown.join(', ')}. `
+            + 'Record them with addEvidenceArtifact so the receipt is bound to real bytes.');
     }
-    bundle.checks.push({ ...check, name: requireText(check.name, 'check name') });
+    bundle.checks.push({ ...check, name, ...(artifacts.length > 0 ? { artifacts: [...artifacts] } : {}) });
 }
 export function finishEvidenceBundle(bundle, result) {
     bundle.status = result.status;
     bundle.finishedAt = result.finishedAt ?? new Date().toISOString();
 }
+/**
+ * Re-hash every recorded artifact. Returns the artifacts whose bytes no longer
+ * match — empty means the receipt still describes what is on disk.
+ */
+export function verifyEvidenceArtifacts(bundle) {
+    const drift = [];
+    for (const artifact of bundle.artifacts) {
+        let bytes;
+        try {
+            bytes = fs.readFileSync(artifact.path);
+        }
+        catch {
+            drift.push({ name: artifact.name, reason: `missing at ${artifact.path}` });
+            continue;
+        }
+        const sha256 = crypto.createHash('sha256').update(bytes).digest('hex');
+        if (sha256 !== artifact.sha256) {
+            drift.push({ name: artifact.name, reason: `sha256 ${sha256} does not match recorded ${artifact.sha256}` });
+        }
+    }
+    return drift;
+}
 export function writeEvidenceBundle(filePath, bundle) {
     if (bundle.status === 'running' || !bundle.finishedAt) {
         throw new Error('refusing to write unfinished QA evidence');
     }
+    // A passing receipt is the one people trust without reading, so it is the one
+    // whose artifacts must still be intact at write time.
+    if (bundle.status === 'passed') {
+        const drift = verifyEvidenceArtifacts(bundle);
+        if (drift.length > 0) {
+            throw new Error(`refusing to write a passing QA receipt whose evidence changed: ${drift.map((item) => `${item.name} (${item.reason})`).join('; ')}`);
+        }
+    }
     const resolved = path.resolve(filePath);
     fs.mkdirSync(path.dirname(resolved), { recursive: true });
     const temporary = `${resolved}.tmp-${process.pid}`;
@@ -36,8 +113,12 @@ export function writeEvidenceBundle(filePath, bundle) {
         fs.rmSync(temporary, { force: true });
     }
 }
+function requireRunning(bundle) {
+    if (bundle.status !== 'running')
+        throw new Error('cannot modify a QA evidence bundle after the run has finished');
+}
 function requireText(value, name) {
-    const normalized = value.trim();
+    const normalized = String(value ?? '').trim();
     if (!normalized)
         throw new Error(`${name} is required`);
     return normalized;

package/dist/frames.d.ts

@@ -0,0 +1,39 @@
+export interface QaFrameBrowser {
+    execute<T>(script: string, ...args: unknown[]): Promise<T>;
+    switchToFrame(target: number | null | unknown): Promise<unknown>;
+    switchToParentFrame(): Promise<unknown>;
+}
+/** Index path from the top document to a nested frame (`[]` is the top document). */
+export type FramePath = readonly number[];
+export interface FrameMatch {
+    framePath: FramePath;
+    count: number;
+}
+/**
+ * Run `body` with the driver focused on `framePath`, then return to the top
+ * document. Restoration happens in a finally block: a spec that throws mid-frame
+ * used to leave every later selector silently scoped to that iframe.
+ */
+export declare function withFrame<T>(browser: QaFrameBrowser, framePath: FramePath, body: () => Promise<T>): Promise<T>;
+export declare function countMatchesScript(selector: string): string;
+export declare function countFramesScript(): string;
+/**
+ * Search every document — top level and nested frames — and report each one that
+ * matches. Callers get the ambiguity rather than a single arbitrary winner.
+ */
+export declare function findAcrossFrames(browser: QaFrameBrowser, selector: string, { maxDepth }?: {
+    maxDepth?: number;
+}): Promise<FrameMatch[]>;
+/**
+ * Resolve the one document a selector is allowed to match. Ambiguity fails with
+ * both locations named, because "it matched somewhere" is what let chrome-level
+ * matches stand in for content-level ones.
+ */
+export declare function resolveUniqueFrame(browser: QaFrameBrowser, selector: string, options?: {
+    maxDepth?: number;
+}): Promise<FramePath>;
+/** Run `body` inside the single document that matches `selector`. */
+export declare function withContentFrame<T>(browser: QaFrameBrowser, selector: string, body: (framePath: FramePath) => Promise<T>, options?: {
+    maxDepth?: number;
+}): Promise<T>;
+export declare function describeFrame(framePath: FramePath): string;

package/dist/frames.js

@@ -0,0 +1,90 @@
+// Selectors must name a document, not just an element.
+//
+// The app renders untrusted document content inside iframes. A selector run
+// against the top-level document therefore searches the CHROME, not the content
+// — and because the chrome often contains a same-named element (a toolbar title,
+// a placeholder, a template node), the query succeeds and the assertion passes
+// while never having looked at the thing under test.
+//
+// Two rules encoded here:
+//   - entering a frame is always paired with leaving it, even when the body throws;
+//   - a selector that matches in more than one document is an error, not a
+//     coin-flip resolved by document order.
+/**
+ * Run `body` with the driver focused on `framePath`, then return to the top
+ * document. Restoration happens in a finally block: a spec that throws mid-frame
+ * used to leave every later selector silently scoped to that iframe.
+ */
+export async function withFrame(browser, framePath, body) {
+    await enterFrame(browser, framePath);
+    try {
+        return await body();
+    }
+    finally {
+        await browser.switchToFrame(null);
+    }
+}
+async function enterFrame(browser, framePath) {
+    await browser.switchToFrame(null);
+    for (const index of framePath) {
+        if (!Number.isInteger(index) || index < 0)
+            throw new Error(`invalid frame index in path: ${JSON.stringify(framePath)}`);
+        await browser.switchToFrame(index);
+    }
+}
+export function countMatchesScript(selector) {
+    return `return document.querySelectorAll(${JSON.stringify(selector)}).length;`;
+}
+export function countFramesScript() {
+    return 'return window.frames.length;';
+}
+/**
+ * Search every document — top level and nested frames — and report each one that
+ * matches. Callers get the ambiguity rather than a single arbitrary winner.
+ */
+export async function findAcrossFrames(browser, selector, { maxDepth = 4 } = {}) {
+    const matches = [];
+    async function visit(framePath, depth) {
+        await enterFrame(browser, framePath);
+        const count = Number(await browser.execute(countMatchesScript(selector)));
+        if (count > 0)
+            matches.push({ framePath: [...framePath], count });
+        if (depth >= maxDepth)
+            return;
+        const frameCount = Number(await browser.execute(countFramesScript()));
+        for (let index = 0; index < frameCount; index += 1) {
+            await visit([...framePath, index], depth + 1);
+        }
+    }
+    try {
+        await visit([], 0);
+    }
+    finally {
+        await browser.switchToFrame(null);
+    }
+    return matches;
+}
+/**
+ * Resolve the one document a selector is allowed to match. Ambiguity fails with
+ * both locations named, because "it matched somewhere" is what let chrome-level
+ * matches stand in for content-level ones.
+ */
+export async function resolveUniqueFrame(browser, selector, options = {}) {
+    const matches = await findAcrossFrames(browser, selector, options);
+    if (matches.length === 0)
+        throw new Error(`selector matched no document: ${selector}`);
+    if (matches.length > 1) {
+        const where = matches.map((match) => `${describeFrame(match.framePath)} (${match.count})`).join(', ');
+        throw new Error(`selector ${selector} matches in ${matches.length} documents: ${where}. `
+            + 'Scope it with withFrame() so the assertion names the document it means.');
+    }
+    return matches[0].framePath;
+}
+/** Run `body` inside the single document that matches `selector`. */
+export async function withContentFrame(browser, selector, body, options = {}) {
+    const framePath = await resolveUniqueFrame(browser, selector, options);
+    return withFrame(browser, framePath, () => body(framePath));
+}
+export function describeFrame(framePath) {
+    return framePath.length === 0 ? 'top document' : `frame ${framePath.join('.')}`;
+}

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export * from './evidence.js';
+export * from './frames.js';
 export * from './guard.js';
 export * from './loopback.js';
 export * from './native.js';
 export * from './ownership.js';
+export * from './paint.js';
+export * from './panes.js';
 export * from './process.js';
+export * from './workspace.js';

package/dist/index.js

@@ -1,6 +1,10 @@
 export * from './evidence.js';
+export * from './frames.js';
 export * from './guard.js';
 export * from './loopback.js';
 export * from './native.js';
 export * from './ownership.js';
+export * from './paint.js';
+export * from './panes.js';
 export * from './process.js';
+export * from './workspace.js';

package/dist/loopback.d.ts

@@ -2,18 +2,33 @@ export interface LoopbackClientOptions {
     baseUrl: string;
     token: string;
     pollIntervalMs?: number;
+    /** Ceiling for a single HTTP round trip. */
+    requestTimeoutMs?: number;
+    /** Default ceiling for a queued action, measured from queue to result. */
+    actionTimeoutMs?: number;
     fetchImpl?: typeof fetch;
+    newRequestId?: () => string;
 }
 export interface ActionResult {
     id: string;
     ok: boolean;
     message?: string;
+    requestId?: string;
     [key: string]: unknown;
 }
+export interface RequestOptions {
+    timeoutMs?: number;
+    requestId?: string;
+}
 export interface LoopbackClient {
-    request<T = unknown>(method: string, route: string, body?: unknown): Promise<T>;
-    action(kind: string, payload?: Record<string, unknown>, options?: {
-        timeoutMs?: number;
-    }): Promise<ActionResult>;
+    request<T = unknown>(method: string, route: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    action(kind: string, payload?: Record<string, unknown>, options?: RequestOptions): Promise<ActionResult>;
+}
+export declare class LoopbackTimeoutError extends Error {
+    readonly requestId: string | undefined;
+    readonly timeoutMs: number;
+    constructor(what: string, timeoutMs: number, requestId?: string);
 }
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+export declare const DEFAULT_ACTION_TIMEOUT_MS = 30000;
 export declare function createLoopbackClient(options: LoopbackClientOptions): LoopbackClient;

package/dist/loopback.js

@@ -1,19 +1,64 @@
+// Control-plane client for the app's loopback QA endpoint.
+//
+// Two properties this file exists to guarantee:
+//
+//  1. NO CALL IS UNBOUNDED. Every fetch carries its own abort deadline, and the
+//     action poll's deadline covers the whole queue-and-await cycle. An app that
+//     accepts a request and then blocks — a resize that never repaints, a window
+//     operation waiting on a message loop that is itself waiting on us — must
+//     surface as a timed-out test, not a hung run that a human eventually kills.
+//  2. RESULTS ARE CORRELATED, NOT GUESSED. Every action carries a caller-minted
+//     request id which is echoed back in the result. Matching on "the most recent
+//     result of this kind" attributes one action's outcome to another whenever
+//     two actions of the same kind overlap.
+import { randomUUID } from 'node:crypto';
+export class LoopbackTimeoutError extends Error {
+    requestId;
+    timeoutMs;
+    constructor(what, timeoutMs, requestId) {
+        super(`${what} exceeded ${timeoutMs}ms${requestId ? ` (requestId ${requestId})` : ''}`);
+        this.name = 'LoopbackTimeoutError';
+        this.timeoutMs = timeoutMs;
+        this.requestId = requestId;
+    }
+}
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+export const DEFAULT_ACTION_TIMEOUT_MS = 30_000;
 export function createLoopbackClient(options) {
     const baseUrl = validateLoopbackUrl(options.baseUrl);
     const token = options.token.trim();
     if (!token)
         throw new Error('loopback bearer token is required');
     const fetchImpl = options.fetchImpl ?? fetch;
-    const pollIntervalMs = options.pollIntervalMs ?? 250;
-    async function request(method, route, body) {
-        const response = await fetchImpl(new URL(route, baseUrl), {
-            method,
-            headers: {
-                authorization: `Bearer ${token}`,
-                'content-type': 'application/json',
-            },
-            body: body === undefined ? undefined : JSON.stringify(body),
-        });
+    const pollIntervalMs = requirePositive(options.pollIntervalMs ?? 250, 'pollIntervalMs');
+    const requestTimeoutMs = requirePositive(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, 'requestTimeoutMs');
+    const actionTimeoutMs = requirePositive(options.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS, 'actionTimeoutMs');
+    const newRequestId = options.newRequestId ?? (() => randomUUID());
+    async function request(method, route, body, requestOptions = {}) {
+        const timeoutMs = requirePositive(requestOptions.timeoutMs ?? requestTimeoutMs, 'timeoutMs');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetchImpl(new URL(route, baseUrl), {
+                method,
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    'content-type': 'application/json',
+                    ...(requestOptions.requestId ? { 'x-rightkit-qa-request-id': requestOptions.requestId } : {}),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw new LoopbackTimeoutError(`${method} ${route}`, timeoutMs, requestOptions.requestId);
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
         const text = await response.text();
         let data = null;
         try {
@@ -22,39 +67,71 @@ export function createLoopbackClient(options) {
         catch {
             data = text;
         }
-        if (!response.ok) {
+        if (!response.ok)
             throw new Error(`${method} ${route} failed ${response.status}: ${text}`);
-        }
         return data;
     }
     async function action(kind, payload = {}, actionOptions = {}) {
-        const queued = await request('POST', '/app-control/actions', { kind, payload });
+        const requestId = actionOptions.requestId ?? newRequestId();
+        const timeoutMs = requirePositive(actionOptions.timeoutMs ?? actionTimeoutMs, 'timeoutMs');
+        const deadline = Date.now() + timeoutMs;
+        const queued = await request('POST', '/app-control/actions', { kind, payload, requestId }, { requestId, timeoutMs: remaining(deadline, timeoutMs, requestId, `app-control ${kind}`) });
         const id = queued.action?.id;
         if (!id)
-            throw new Error(`app-control ${kind} did not return an action id`);
-        const deadline = Date.now() + (actionOptions.timeoutMs ?? 30_000);
+            throw new Error(`app-control ${kind} did not return an action id (requestId ${requestId})`);
         while (Date.now() < deadline) {
-            await delay(pollIntervalMs);
-            const state = await request('GET', '/app-control/state');
-            const result = state.recentResults?.find((entry) => entry.id === id);
+            await delay(Math.min(pollIntervalMs, Math.max(1, deadline - Date.now())));
+            let state;
+            try {
+                state = await request('GET', '/app-control/state', undefined, { requestId, timeoutMs: remaining(deadline, timeoutMs, requestId, `app-control ${kind}`) });
+            }
+            catch (error) {
+                // A poll cut short by the action's own deadline is an action timeout.
+                // Reporting the truncated per-request budget instead would name a number
+                // the caller never chose and hide the deadline that actually expired.
+                if (error instanceof LoopbackTimeoutError && Date.now() >= deadline) {
+                    throw new LoopbackTimeoutError(`app-control ${kind}`, timeoutMs, requestId);
+                }
+                throw error;
+            }
+            // Prefer the request id; fall back to the action id for apps that predate
+            // request-id echo. Never fall back to "the newest result".
+            const result = state.recentResults?.find((entry) => entry.requestId === requestId)
+                ?? state.recentResults?.find((entry) => entry.id === id && entry.requestId === undefined);
             if (!result)
                 continue;
             if (!result.ok)
-                throw new Error(`app-control ${kind} failed: ${result.message ?? 'unknown error'}`);
-            return result;
+                throw new Error(`app-control ${kind} failed: ${result.message ?? 'unknown error'} (requestId ${requestId})`);
+            return { ...result, requestId };
         }
-        throw new Error(`app-control ${kind} timed out`);
+        throw new LoopbackTimeoutError(`app-control ${kind}`, timeoutMs, requestId);
     }
     return { request, action };
 }
+/**
+ * Time left before the action's deadline. Exhaustion reports the ORIGINAL budget,
+ * not the zero milliseconds remaining — "exceeded 0ms" tells the reader nothing
+ * about what was actually allowed.
+ */
+function remaining(deadline, budgetMs, requestId, what) {
+    const left = deadline - Date.now();
+    if (left <= 0)
+        throw new LoopbackTimeoutError(what, budgetMs, requestId);
+    return left;
+}
 function validateLoopbackUrl(value) {
     const url = new URL(value);
     const host = url.hostname.toLowerCase();
-    if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(host)) {
+    if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]', '::1'].includes(host)) {
         throw new Error(`QA control endpoint must be an HTTP loopback URL, received ${url.origin}`);
     }
     return url;
 }
+function requirePositive(value, name) {
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`${name} must be a positive number of milliseconds`);
+    return value;
+}
 async function delay(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/paint.d.ts

@@ -0,0 +1,48 @@
+export interface QaBrowser {
+    execute<T>(script: string, ...args: unknown[]): Promise<T>;
+    executeAsync<T>(script: string, ...args: unknown[]): Promise<T>;
+}
+export interface PaintMetrics {
+    requestId: string;
+    /** Milliseconds from the caller's mark to the second animation frame. */
+    durationMs: number;
+    /** Milliseconds spent waiting for DOM mutations to stop. */
+    settleMs: number;
+    mutations: number;
+    /** True when rAF x2 completed; false when the page fell back to a timer. */
+    animationFrames: boolean;
+}
+export declare const DEFAULT_SETTLE_MS = 120;
+export declare const DEFAULT_PAINT_TIMEOUT_MS = 10000;
+/**
+ * Install the page-side ledger. Idempotent, so specs may call it after every
+ * navigation without accumulating observers.
+ */
+export declare function installPaintLedgerScript(): string;
+/** Record the start of a measured interaction, keyed by request id. */
+export declare function beginPaintScript(requestId: string, selector?: string): string;
+/**
+ * Resolve once the target subtree has been quiet for `settleMs` and two
+ * animation frames have elapsed. Falls back to a timer only if the document is
+ * hidden, where the browser throttles rAF indefinitely — reported honestly via
+ * `animationFrames: false` rather than silently producing a number.
+ */
+export declare function awaitPaintScript(requestId: string, settleMs: number, timeoutMs: number): string;
+export interface MeasurePaintOptions {
+    requestId: string;
+    /** CSS selector for the subtree that should render. Defaults to the document. */
+    selector?: string;
+    settleMs?: number;
+    timeoutMs?: number;
+}
+/**
+ * Run `trigger` and return when the resulting render has actually been painted.
+ * The mark is installed BEFORE the trigger so no mutation can slip between them.
+ */
+export declare function measurePaint(browser: QaBrowser, trigger: () => Promise<unknown>, options: MeasurePaintOptions): Promise<PaintMetrics>;
+/**
+ * Assert a paint completed within budget. Separate from measurement so a spec can
+ * record a timing without failing on it, and so the failure text carries the
+ * evidence rather than just a boolean.
+ */
+export declare function assertPaintWithin(metrics: PaintMetrics, budgetMs: number, label: string): PaintMetrics;

package/dist/paint.js

@@ -0,0 +1,134 @@
+// Measure when the UI was PAINTED, not when the command returned.
+//
+// A driver command resolves as soon as the app acknowledges it. For anything that
+// renders — opening a document, switching tabs, re-laying out after a resize —
+// that acknowledgement happens well before pixels change, so timings taken from
+// it measure the RPC and report it as UI latency. Every such number is wrong in
+// the same direction, which is why they looked plausible.
+//
+// What this module measures instead: from a caller-marked start, wait for DOM
+// mutations in the target subtree to go quiet, then wait two animation frames.
+// The second frame callback runs after the frame containing the layout+paint work
+// has been committed for rendering.
+//
+// Honest limit: rAF x2 fires after commit but before the compositor has
+// necessarily put pixels on the physical display. It is the right signal for
+// catching latency regressions and for ordering ("did it render before we
+// asserted?"). It is NOT proof of pixels; when that is what you need, follow it
+// with a screenshot comparison.
+export const DEFAULT_SETTLE_MS = 120;
+export const DEFAULT_PAINT_TIMEOUT_MS = 10_000;
+const LEDGER = '__rightkitQaPaint';
+/**
+ * Install the page-side ledger. Idempotent, so specs may call it after every
+ * navigation without accumulating observers.
+ */
+export function installPaintLedgerScript() {
+    return `
+    (function () {
+      if (window.${LEDGER}) return true;
+      window.${LEDGER} = { marks: new Map() };
+      return true;
+    })();
+  `;
+}
+/** Record the start of a measured interaction, keyed by request id. */
+export function beginPaintScript(requestId, selector) {
+    return `
+    (function () {
+      var ledger = window.${LEDGER};
+      if (!ledger) throw new Error('paint ledger is not installed');
+      var root = ${selector ? `document.querySelector(${JSON.stringify(selector)})` : 'document.documentElement'};
+      if (!root) throw new Error('paint target not found: ' + ${JSON.stringify(selector ?? 'document')});
+      var mark = { startedAt: performance.now(), mutations: 0, lastMutationAt: performance.now() };
+      mark.observer = new MutationObserver(function (records) {
+        mark.mutations += records.length;
+        mark.lastMutationAt = performance.now();
+      });
+      mark.observer.observe(root, { subtree: true, childList: true, characterData: true, attributes: true });
+      ledger.marks.set(${JSON.stringify(requestId)}, mark);
+      return true;
+    })();
+  `;
+}
+/**
+ * Resolve once the target subtree has been quiet for `settleMs` and two
+ * animation frames have elapsed. Falls back to a timer only if the document is
+ * hidden, where the browser throttles rAF indefinitely — reported honestly via
+ * `animationFrames: false` rather than silently producing a number.
+ */
+export function awaitPaintScript(requestId, settleMs, timeoutMs) {
+    return `
+    (function () {
+      var done = arguments[arguments.length - 1];
+      var ledger = window.${LEDGER};
+      var mark = ledger && ledger.marks.get(${JSON.stringify(requestId)});
+      if (!mark) { done({ error: 'no paint mark for request ${requestId}' }); return; }
+      var deadline = performance.now() + ${timeoutMs};
+
+      function finish(animationFrames) {
+        mark.observer.disconnect();
+        ledger.marks.delete(${JSON.stringify(requestId)});
+        done({
+          durationMs: performance.now() - mark.startedAt,
+          settleMs: mark.lastMutationAt - mark.startedAt,
+          mutations: mark.mutations,
+          animationFrames: animationFrames,
+        });
+      }
+
+      function afterSettle() {
+        if (document.hidden) { finish(false); return; }
+        requestAnimationFrame(function () { requestAnimationFrame(function () { finish(true); }); });
+      }
+
+      (function poll() {
+        var quietFor = performance.now() - mark.lastMutationAt;
+        if (quietFor >= ${settleMs}) { afterSettle(); return; }
+        if (performance.now() >= deadline) {
+          mark.observer.disconnect();
+          ledger.marks.delete(${JSON.stringify(requestId)});
+          done({ error: 'paint did not settle within ${timeoutMs}ms; ' + mark.mutations + ' mutations, last ' + Math.round(quietFor) + 'ms ago' });
+          return;
+        }
+        setTimeout(poll, 16);
+      })();
+    })();
+  `;
+}
+/**
+ * Run `trigger` and return when the resulting render has actually been painted.
+ * The mark is installed BEFORE the trigger so no mutation can slip between them.
+ */
+export async function measurePaint(browser, trigger, options) {
+    const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PAINT_TIMEOUT_MS;
+    await browser.execute(installPaintLedgerScript());
+    await browser.execute(beginPaintScript(options.requestId, options.selector));
+    await trigger();
+    const result = await browser.executeAsync(awaitPaintScript(options.requestId, settleMs, timeoutMs));
+    if (!result || result.error) {
+        throw new Error(`paint measurement failed for ${options.requestId}: ${result?.error ?? 'no result'}`);
+    }
+    return {
+        requestId: options.requestId,
+        durationMs: Number(result.durationMs),
+        settleMs: Number(result.settleMs),
+        mutations: Number(result.mutations ?? 0),
+        animationFrames: result.animationFrames === true,
+    };
+}
+/**
+ * Assert a paint completed within budget. Separate from measurement so a spec can
+ * record a timing without failing on it, and so the failure text carries the
+ * evidence rather than just a boolean.
+ */
+export function assertPaintWithin(metrics, budgetMs, label) {
+    if (!Number.isFinite(budgetMs) || budgetMs <= 0)
+        throw new Error('paint budget must be a positive number of milliseconds');
+    if (metrics.durationMs > budgetMs) {
+        throw new Error(`${label} painted in ${Math.round(metrics.durationMs)}ms, over its ${budgetMs}ms budget `
+            + `(${metrics.mutations} DOM mutations, settled after ${Math.round(metrics.settleMs)}ms, requestId ${metrics.requestId})`);
+    }
+    return metrics;
+}

package/dist/panes.d.ts

@@ -0,0 +1,39 @@
+export interface QaGeometryBrowser {
+    execute<T>(script: string, ...args: unknown[]): Promise<T>;
+}
+export interface PaneGeometry {
+    selector: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    visible: boolean;
+    active: boolean;
+    matches: number;
+    viewport: {
+        width: number;
+        height: number;
+        devicePixelRatio: number;
+    };
+}
+export declare function readPaneGeometryScript(selector: string): string;
+export declare function readPaneGeometry(browser: QaGeometryBrowser, selector: string): Promise<PaneGeometry>;
+/**
+ * The pane under test must be the visible, active one. Both halves matter: a
+ * hidden pane fails "visible", and a background tab that happens to be laid out
+ * fails "active".
+ */
+export declare function assertActivePane(geometry: PaneGeometry): PaneGeometry;
+export interface ResizeSettleOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Consecutive identical readings required before the box counts as settled. */
+    stableReads?: number;
+}
+export declare const DEFAULT_RESIZE_TIMEOUT_MS = 5000;
+/**
+ * Wait until the ACTIVE pane's box has changed from `before` and then held still.
+ * Bounded: a resize the app never applies fails as a timeout naming both boxes,
+ * instead of hanging on an RPC that will not answer.
+ */
+export declare function waitForPaneResize(browser: QaGeometryBrowser, selector: string, before: Pick<PaneGeometry, 'width' | 'height'>, options?: ResizeSettleOptions): Promise<PaneGeometry>;

package/dist/panes.js

@@ -0,0 +1,102 @@
+// Assert against the pane the user is actually looking at.
+//
+// Tab and split-view UIs keep inactive panes in the DOM — hidden, zero-sized, or
+// positioned offscreen. A selector that matches "the editor pane" therefore
+// resolves just as happily to a background tab, and the resulting assertion
+// describes a pane nobody can see. Worse, it is stable: it passes every run, for
+// the wrong pane, forever.
+//
+// So geometry is read together with visibility and activeness, and a resize is
+// only considered complete once the ACTIVE pane's box has actually changed and
+// settled. Waiting on the window size alone reports success while the pane
+// inside it is still laid out at its old dimensions.
+export function readPaneGeometryScript(selector) {
+    return `
+    (function () {
+      var nodes = document.querySelectorAll(${JSON.stringify(selector)});
+      if (nodes.length === 0) return null;
+      // Prefer the node the UI marks as current; fall back to the sole match.
+      var chosen = null;
+      for (var i = 0; i < nodes.length; i += 1) {
+        var node = nodes[i];
+        if (node.getAttribute('aria-selected') === 'true'
+            || node.getAttribute('aria-current') === 'true'
+            || node.dataset.active === 'true'
+            || node.classList.contains('active')) { chosen = node; break; }
+      }
+      if (!chosen) chosen = nodes[0];
+      var rect = chosen.getBoundingClientRect();
+      var style = getComputedStyle(chosen);
+      var hiddenByStyle = style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0;
+      var hiddenByAttr = chosen.hasAttribute('hidden') || chosen.getAttribute('aria-hidden') === 'true';
+      return {
+        x: rect.x, y: rect.y, width: rect.width, height: rect.height,
+        visible: !hiddenByStyle && !hiddenByAttr && rect.width > 0 && rect.height > 0,
+        active: chosen.getAttribute('aria-selected') === 'true'
+          || chosen.getAttribute('aria-current') === 'true'
+          || chosen.dataset.active === 'true'
+          || chosen.classList.contains('active')
+          || (nodes.length === 1 && !hiddenByStyle && !hiddenByAttr),
+        matches: nodes.length,
+        viewport: { width: window.innerWidth, height: window.innerHeight, devicePixelRatio: window.devicePixelRatio },
+      };
+    })();
+  `;
+}
+export async function readPaneGeometry(browser, selector) {
+    const raw = await browser.execute(readPaneGeometryScript(selector));
+    if (!raw)
+        throw new Error(`pane selector matched no element: ${selector}`);
+    return { selector, ...raw };
+}
+/**
+ * The pane under test must be the visible, active one. Both halves matter: a
+ * hidden pane fails "visible", and a background tab that happens to be laid out
+ * fails "active".
+ */
+export function assertActivePane(geometry) {
+    if (!geometry.visible) {
+        throw new Error(`${geometry.selector} is not visible (${geometry.width}x${geometry.height} at ${geometry.x},${geometry.y}); `
+            + 'the assertion would describe a pane the user cannot see');
+    }
+    if (!geometry.active) {
+        throw new Error(`${geometry.selector} matched ${geometry.matches} panes and the chosen one is not the active pane; `
+            + 'scope the selector to the active tab before asserting');
+    }
+    return geometry;
+}
+export const DEFAULT_RESIZE_TIMEOUT_MS = 5_000;
+/**
+ * Wait until the ACTIVE pane's box has changed from `before` and then held still.
+ * Bounded: a resize the app never applies fails as a timeout naming both boxes,
+ * instead of hanging on an RPC that will not answer.
+ */
+export async function waitForPaneResize(browser, selector, before, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_RESIZE_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? 50;
+    const stableReads = options.stableReads ?? 2;
+    const deadline = Date.now() + timeoutMs;
+    let stable = 0;
+    let previous = null;
+    let latest = null;
+    while (Date.now() < deadline) {
+        latest = assertActivePane(await readPaneGeometry(browser, selector));
+        const changed = latest.width !== before.width || latest.height !== before.height;
+        const held = previous !== null && previous.width === latest.width && previous.height === latest.height;
+        if (changed && held) {
+            stable += 1;
+            if (stable >= stableReads)
+                return latest;
+        }
+        else if (!held) {
+            stable = 0;
+        }
+        previous = latest;
+        await delay(pollIntervalMs);
+    }
+    throw new Error(`${selector} did not settle at a new size within ${timeoutMs}ms: `
+        + `before ${before.width}x${before.height}, last ${latest ? `${latest.width}x${latest.height}` : 'unreadable'}`);
+}
+async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/workspace.d.ts

@@ -0,0 +1,46 @@
+export interface QaWorkspace {
+    runId: string;
+    root: string;
+    /** Isolated user-data directory; pass to the app so it takes its own lock. */
+    dataDir: string;
+    /** Somewhere for screenshots, logs, and other recorded evidence. */
+    evidenceDir: string;
+    /** Environment overrides that point the app at this workspace. */
+    env: Record<string, string>;
+}
+export interface DisposeReport {
+    removed: string[];
+    retained: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+export interface CreateQaWorkspaceOptions {
+    root: string;
+    runId?: string;
+    appKey: string;
+}
+export declare function createQaWorkspace(options: CreateQaWorkspaceOptions): QaWorkspace;
+export interface DisposeOptions {
+    /** Keep the recorded evidence and remove only the volatile profile. */
+    keepEvidence?: boolean;
+    attempts?: number;
+    retryDelayMs?: number;
+    sleep?: (ms: number) => void;
+}
+/**
+ * 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.
+ */
+export declare function disposeQaWorkspace(workspace: QaWorkspace, options?: DisposeOptions): DisposeReport;
+/**
+ * Sweep run directories left behind by earlier crashed runs. Bounded to the
+ * workspace's own `runs` directory and to entries older than `olderThanMs`, so a
+ * concurrent run is never removed out from under itself.
+ */
+export declare function pruneAbandonedWorkspaces(root: string, { olderThanMs, now, keep }?: {
+    olderThanMs?: number;
+    now?: number;
+    keep?: string[];
+}): DisposeReport;

package/dist/workspace.js

@@ -0,0 +1,151 @@
+// An isolated, reliably-removable home for one QA run.
+//
+// Two failures this addresses:
+//
+//   Single instance. The apps hold a single-instance lock keyed on their user
+//   data directory. A harness that launches the app with the real data directory
+//   either loses to an already-running copy (the launch silently hands off to the
+//   existing window and the driver attaches to nothing) or steals the user's
+//   session. Giving the run its own data directory makes the harness a genuinely
+//   separate instance instead of a competitor for the same lock.
+//
+//   Cleanup. Best-effort `rm -rf` in a finally block is not rollback. On Windows a
+//   file still mapped by an exiting process fails with EBUSY/EPERM for a short
+//   window, so a single attempt leaves directories behind — which is exactly the
+//   litter found in packages/legal-ui/.cache. Removal retries, and whatever
+//   genuinely could not be removed is REPORTED rather than swallowed.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+export function createQaWorkspace(options) {
+    const appKey = requireText(options.appKey, 'appKey');
+    const runId = options.runId ?? crypto.randomUUID();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId))
+        throw new Error(`unsafe QA run id: ${runId}`);
+    const root = path.resolve(requireText(options.root, 'root'), 'runs', runId);
+    const dataDir = path.join(root, 'data');
+    const evidenceDir = path.join(root, 'evidence');
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.mkdirSync(evidenceDir, { recursive: true });
+    return {
+        runId,
+        root,
+        dataDir,
+        evidenceDir,
+        env: {
+            RIGHTKIT_QA_NATIVE: '1',
+            RIGHTKIT_QA_RUN_ID: runId,
+            RIGHTKIT_QA_DATA_DIR: dataDir,
+            RIGHTKIT_QA_EVIDENCE_DIR: evidenceDir,
+            // Tauri/webview honour these for profile isolation; setting all three keeps
+            // the run off the user's real profile regardless of which the app reads.
+            XDG_DATA_HOME: dataDir,
+            XDG_CONFIG_HOME: dataDir,
+            WEBVIEW2_USER_DATA_FOLDER: path.join(dataDir, 'webview2'),
+            [`${appKey.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_DATA_DIR`]: dataDir,
+        },
+    };
+}
+/**
+ * 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.
+ */
+export function disposeQaWorkspace(workspace, options = {}) {
+    const attempts = Math.max(1, options.attempts ?? 5);
+    const retryDelayMs = options.retryDelayMs ?? 200;
+    const sleep = options.sleep ?? sleepSync;
+    const targets = options.keepEvidence ? [workspace.dataDir] : [workspace.root];
+    const report = { removed: [], retained: [] };
+    for (const target of targets) {
+        // Only ever remove inside the workspace root we created.
+        const resolved = path.resolve(target);
+        if (resolved !== path.resolve(workspace.root) && !isInside(workspace.root, resolved)) {
+            report.retained.push({ path: resolved, reason: 'outside the QA workspace root' });
+            continue;
+        }
+        if (!fs.existsSync(resolved)) {
+            report.removed.push(resolved);
+            continue;
+        }
+        let lastError;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            try {
+                fs.rmSync(resolved, { recursive: true, force: true });
+                lastError = undefined;
+                break;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < attempts)
+                    sleep(retryDelayMs);
+            }
+        }
+        if (lastError === undefined && !fs.existsSync(resolved))
+            report.removed.push(resolved);
+        else
+            report.retained.push({ path: resolved, reason: describeError(lastError) });
+    }
+    return report;
+}
+/**
+ * Sweep run directories left behind by earlier crashed runs. Bounded to the
+ * workspace's own `runs` directory and to entries older than `olderThanMs`, so a
+ * concurrent run is never removed out from under itself.
+ */
+export function pruneAbandonedWorkspaces(root, { olderThanMs = 6 * 60 * 60_000, now = Date.now(), keep = [] } = {}) {
+    const runsRoot = path.resolve(root, 'runs');
+    const report = { removed: [], retained: [] };
+    let entries;
+    try {
+        entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+    }
+    catch {
+        return report;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            continue;
+        if (keep.includes(entry.name))
+            continue;
+        const target = path.join(runsRoot, entry.name);
+        let ageMs;
+        try {
+            ageMs = now - fs.statSync(target).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (ageMs < olderThanMs) {
+            report.retained.push({ path: target, reason: `only ${Math.round(ageMs / 1000)}s old; may belong to a live run` });
+            continue;
+        }
+        try {
+            fs.rmSync(target, { recursive: true, force: true });
+            report.removed.push(target);
+        }
+        catch (error) {
+            report.retained.push({ path: target, reason: describeError(error) });
+        }
+    }
+    return report;
+}
+function isInside(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+function describeError(error) {
+    if (error === undefined)
+        return 'still present after removal reported success';
+    const code = error.code;
+    return code ? `${code}: ${error.message}` : String(error?.message ?? error);
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function requireText(value, name) {
+    const normalized = String(value ?? '').trim();
+    if (!normalized)
+        throw new Error(`${name} is required`);
+    return normalized;
+}

package/package.json

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