electron-verify-mcp 0.0.1

package/dist/core/launch.d.ts

@@ -0,0 +1,29 @@
+import { type ElectronApplication } from "playwright-core";
+export interface LaunchOptions {
+    /** Path to the app's built main entry, relative to `cwd` (e.g. "dist/main/index.js"). */
+    appPath: string;
+    /** App project root. Defaults to the directory of `appPath`. */
+    cwd?: string;
+    /** Extra args appended after the main entry. */
+    args?: string[];
+    /** Extra environment for the launched app. */
+    env?: Record<string, string>;
+    /** Optional command run in `cwd` before launch so we never verify a stale build. */
+    buildCommand?: string;
+    /** Explicit Electron binary. If omitted we resolve the app's own, then ours. */
+    executablePath?: string;
+    /** ms to wait for the app to open its first window. */
+    launchTimeoutMs?: number;
+}
+/**
+ * Resolve the Electron binary to launch with. Playwright resolves Electron relative to
+ * ITS OWN install, which will miss the target app's version — so we explicitly resolve the
+ * app's `node_modules/electron` first, then fall back to this tool's bundled Electron.
+ */
+export declare function resolveElectron(cwd: string): string;
+/**
+ * Run a build command with stdout/stderr captured — never write to fd 1.
+ * MCP uses stdout as the JSON-RPC channel; build noise must stay on stderr.
+ */
+export declare function runBuildCommand(cmd: string, cwd: string, timeoutMs?: number): void;
+export declare function launchApp(opts: LaunchOptions): Promise<ElectronApplication>;

package/dist/core/launch.js

@@ -0,0 +1,98 @@
+import { createRequire } from "node:module";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { _electron as electron } from "playwright-core";
+/**
+ * Resolve the Electron binary to launch with. Playwright resolves Electron relative to
+ * ITS OWN install, which will miss the target app's version — so we explicitly resolve the
+ * app's `node_modules/electron` first, then fall back to this tool's bundled Electron.
+ */
+export function resolveElectron(cwd) {
+    // 1. The target app's own Electron (correct version / native ABI match).
+    try {
+        const appRequire = createRequire(path.join(cwd, "package.json"));
+        const bin = appRequire("electron");
+        if (typeof bin === "string")
+            return bin;
+    }
+    catch {
+        /* fall through */
+    }
+    // 2. This tool's bundled Electron (used by fixtures and apps without their own).
+    const ourRequire = createRequire(import.meta.url);
+    const bin = ourRequire("electron");
+    if (typeof bin !== "string") {
+        throw new Error("Could not resolve an Electron binary from the app or from electron-verify-mcp.");
+    }
+    return bin;
+}
+/**
+ * Resolve the main entry to an absolute path.
+ * Accepts either a path relative to `cwd` (e.g. "dist/main/index.js") or a path
+ * relative to the process CWD (e.g. "test/fixtures/good-app/main.js" with a cwd of
+ * the fixture dir) so both CLI forms work without double-joining.
+ */
+function resolveMainEntry(appPath, cwd) {
+    if (path.isAbsolute(appPath))
+        return appPath;
+    const fromProcess = path.resolve(appPath);
+    if (fs.existsSync(fromProcess))
+        return fromProcess;
+    const fromCwd = path.resolve(cwd, appPath);
+    if (fs.existsSync(fromCwd))
+        return fromCwd;
+    // Prefer cwd-relative for the error message / launch attempt (matches docs).
+    return fromCwd;
+}
+/**
+ * Run a build command with stdout/stderr captured — never write to fd 1.
+ * MCP uses stdout as the JSON-RPC channel; build noise must stay on stderr.
+ */
+export function runBuildCommand(cmd, cwd, timeoutMs = 120_000) {
+    try {
+        const out = execSync(cmd, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: timeoutMs,
+            encoding: "utf8",
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        if (out)
+            process.stderr.write(out);
+    }
+    catch (err) {
+        const e = err;
+        const stdout = bufToStr(e.stdout);
+        const stderr = bufToStr(e.stderr);
+        if (stdout)
+            process.stderr.write(stdout);
+        if (stderr)
+            process.stderr.write(stderr);
+        const combined = [stdout, stderr].filter(Boolean).join("\n").trim();
+        const tail = combined.length > 4000 ? combined.slice(-4000) : combined;
+        throw new Error(`buildCommand failed${e.status != null ? ` (exit ${e.status})` : ""}: ${cmd}` +
+            (tail ? `\n--- build output ---\n${tail}` : `\n${e.message ?? String(err)}`));
+    }
+}
+function bufToStr(v) {
+    if (v == null)
+        return "";
+    return typeof v === "string" ? v : v.toString("utf8");
+}
+export async function launchApp(opts) {
+    const cwd = path.resolve(opts.cwd ?? path.dirname(path.resolve(opts.appPath)));
+    const mainEntry = resolveMainEntry(opts.appPath, cwd);
+    if (opts.buildCommand) {
+        // Build synchronously; capture all output → stderr only (never MCP stdout).
+        runBuildCommand(opts.buildCommand, cwd);
+    }
+    const executablePath = opts.executablePath ?? resolveElectron(cwd);
+    return electron.launch({
+        executablePath,
+        args: [mainEntry, ...(opts.args ?? [])],
+        cwd,
+        env: { ...process.env, ...(opts.env ?? {}) },
+        timeout: opts.launchTimeoutMs ?? 30_000,
+    });
+}

package/dist/core/readiness.d.ts

@@ -0,0 +1,23 @@
+import type { Page } from "playwright-core";
+import type { ReadinessSignal } from "./types.js";
+export interface ReadinessOptions {
+    /** Max time to wait for pixel stability. Default 10s. */
+    timeoutMs?: number;
+    /** Interval between samples. Default 150ms. */
+    intervalMs?: number;
+    /** Consecutive stable samples required. Default 3. */
+    stableSamples?: number;
+    /** Max fraction of pixels that may change and still count as stable. Default 0.005 (0.5%). */
+    changeThreshold?: number;
+    /** Width of the downscaled comparison frame. Default 320. */
+    sampleWidth?: number;
+}
+/**
+ * Wait until the renderer is pixel-stable (not merely "loaded").
+ *
+ * Captures tiny consecutive screenshots and counts changed pixels. Stable when
+ * change stays below ~0.5% for N consecutive samples. On timeout returns
+ * `{stable:false, timedOut:true}` — never throws. Timeout is a WARN, not FAIL
+ * (animations / spinners must not hard-fail verification).
+ */
+export declare function waitUntilReady(page: Page, opts?: ReadinessOptions): Promise<ReadinessSignal>;

package/dist/core/readiness.js

@@ -0,0 +1,109 @@
+import { PNG } from "pngjs";
+/**
+ * Wait until the renderer is pixel-stable (not merely "loaded").
+ *
+ * Captures tiny consecutive screenshots and counts changed pixels. Stable when
+ * change stays below ~0.5% for N consecutive samples. On timeout returns
+ * `{stable:false, timedOut:true}` — never throws. Timeout is a WARN, not FAIL
+ * (animations / spinners must not hard-fail verification).
+ */
+export async function waitUntilReady(page, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const intervalMs = opts.intervalMs ?? 150;
+    const stableSamples = opts.stableSamples ?? 3;
+    const changeThreshold = opts.changeThreshold ?? 0.005;
+    const sampleWidth = opts.sampleWidth ?? 320;
+    const started = Date.now();
+    try {
+        await page.waitForLoadState("load", { timeout: Math.min(timeoutMs, 15_000) });
+    }
+    catch {
+        // Load may never fire on some shells; still try pixel stability.
+    }
+    let prev = null;
+    let streak = 0;
+    while (Date.now() - started < timeoutMs) {
+        let frame;
+        try {
+            const raw = await page.screenshot({ type: "png" });
+            frame = downscalePng(PNG.sync.read(raw), sampleWidth);
+        }
+        catch {
+            // Page may be mid-navigation; wait and retry.
+            await sleep(intervalMs);
+            continue;
+        }
+        if (prev && sameSize(prev, frame)) {
+            const changed = changedPixelFraction(prev, frame);
+            if (changed < changeThreshold) {
+                streak += 1;
+                if (streak >= stableSamples) {
+                    return {
+                        stable: true,
+                        waitedMs: Date.now() - started,
+                        timedOut: false,
+                    };
+                }
+            }
+            else {
+                streak = 0;
+            }
+        }
+        else {
+            streak = 0;
+        }
+        prev = frame;
+        await sleep(intervalMs);
+    }
+    return {
+        stable: false,
+        waitedMs: Date.now() - started,
+        timedOut: true,
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function sameSize(a, b) {
+    return a.width === b.width && a.height === b.height;
+}
+/** Fraction of pixels whose RGB differs by more than a small epsilon. */
+function changedPixelFraction(a, b) {
+    const n = a.width * a.height;
+    if (n === 0)
+        return 0;
+    let changed = 0;
+    const ad = a.data;
+    const bd = b.data;
+    for (let i = 0; i < n; i++) {
+        const o = i << 2;
+        if (Math.abs(ad[o] - bd[o]) > 2 ||
+            Math.abs(ad[o + 1] - bd[o + 1]) > 2 ||
+            Math.abs(ad[o + 2] - bd[o + 2]) > 2) {
+            changed++;
+        }
+    }
+    return changed / n;
+}
+/** Nearest-neighbor downscale to a target max width (keeps aspect). */
+function downscalePng(src, maxWidth) {
+    if (src.width <= maxWidth)
+        return src;
+    const scale = maxWidth / src.width;
+    const dstW = maxWidth;
+    const dstH = Math.max(1, Math.round(src.height * scale));
+    const dst = new PNG({ width: dstW, height: dstH });
+    for (let y = 0; y < dstH; y++) {
+        const sy = Math.min(src.height - 1, Math.floor(y / scale));
+        for (let x = 0; x < dstW; x++) {
+            const sx = Math.min(src.width - 1, Math.floor(x / scale));
+            const si = (src.width * sy + sx) << 2;
+            const di = (dstW * y + x) << 2;
+            dst.data[di] = src.data[si];
+            dst.data[di + 1] = src.data[si + 1];
+            dst.data[di + 2] = src.data[si + 2];
+            dst.data[di + 3] = src.data[si + 3];
+        }
+    }
+    return dst;
+}

package/dist/core/screenshot.d.ts

@@ -0,0 +1,30 @@
+import type { Page } from "playwright-core";
+import { PNG } from "pngjs";
+import type { HoleRect } from "./types.js";
+export interface CaptureOptions {
+    /** Max width of the returned PNG. Wider captures are downscaled. Default 1280. */
+    maxWidth?: number;
+    /**
+     * BrowserView (or other native) rectangles in the *source* screenshot coordinate
+     * space. Annotated with an outline + label so agents don't judge the void as a bug.
+     */
+    holes?: HoleRect[];
+}
+/**
+ * Capture a window screenshot as a PNG Buffer, downscale if needed, and annotate
+ * any BrowserView "holes" so the agent can see them as intentional exclusions.
+ */
+export declare function captureScreenshot(page: Page, opts?: CaptureOptions): Promise<Buffer>;
+/**
+ * Capture raw PNG without annotation (for blank-screen pixel analysis with hole exclusion).
+ */
+export declare function captureRawScreenshot(page: Page): Promise<Buffer>;
+/**
+ * Draw a hatch fill + dashed outline + label on each hole rectangle.
+ * Coordinates are in the raw (pre-downscale) screenshot space.
+ */
+export declare function annotateHoles(src: PNG, holes: HoleRect[]): PNG;
+/** Test whether pixel (x,y) falls inside any hole rectangle. */
+export declare function isInsideHole(x: number, y: number, holes: HoleRect[]): boolean;
+/** Nearest-neighbor downscale when the PNG is wider than maxWidth. */
+export declare function downscaleIfNeeded(pngBuf: Buffer, maxWidth: number): Buffer;

package/dist/core/screenshot.js

@@ -0,0 +1,176 @@
+import { PNG } from "pngjs";
+/**
+ * Capture a window screenshot as a PNG Buffer, downscale if needed, and annotate
+ * any BrowserView "holes" so the agent can see them as intentional exclusions.
+ */
+export async function captureScreenshot(page, opts = {}) {
+    const maxWidth = opts.maxWidth ?? 1280;
+    const raw = await page.screenshot({ type: "png" });
+    const holes = opts.holes ?? [];
+    const rawPng = PNG.sync.read(raw);
+    const srcW = rawPng.width;
+    const png = holes.length > 0 ? annotateHoles(rawPng, holes) : rawPng;
+    let buf = PNG.sync.write(png);
+    if (srcW > maxWidth) {
+        buf = downscaleIfNeeded(buf, maxWidth);
+    }
+    return buf;
+}
+/**
+ * Capture raw PNG without annotation (for blank-screen pixel analysis with hole exclusion).
+ */
+export async function captureRawScreenshot(page) {
+    return page.screenshot({ type: "png" });
+}
+/**
+ * Draw a hatch fill + dashed outline + label on each hole rectangle.
+ * Coordinates are in the raw (pre-downscale) screenshot space.
+ */
+export function annotateHoles(src, holes) {
+    const out = new PNG({ width: src.width, height: src.height });
+    src.data.copy(out.data);
+    for (const hole of holes) {
+        const x0 = Math.max(0, Math.floor(hole.x));
+        const y0 = Math.max(0, Math.floor(hole.y));
+        const x1 = Math.min(src.width, Math.ceil(hole.x + hole.width));
+        const y1 = Math.min(src.height, Math.ceil(hole.y + hole.height));
+        if (x1 <= x0 || y1 <= y0)
+            continue;
+        for (let y = y0; y < y1; y++) {
+            for (let x = x0; x < x1; x++) {
+                const i = (src.width * y + x) << 2;
+                const hatch = (x + y) % 8 < 2;
+                if (hatch) {
+                    out.data[i] = Math.min(255, out.data[i] + 40);
+                    out.data[i + 1] = Math.min(255, out.data[i + 1] + 30);
+                    out.data[i + 2] = Math.min(255, out.data[i + 2] + 10);
+                }
+            }
+        }
+        const outline = { r: 255, g: 140, b: 0, a: 255 };
+        const t = 3;
+        for (let y = y0; y < y1; y++) {
+            for (let x = x0; x < x1; x++) {
+                const onEdge = x < x0 + t || x >= x1 - t || y < y0 + t || y >= y1 - t;
+                if (!onEdge)
+                    continue;
+                const along = x < x0 + t || x >= x1 - t ? y : x;
+                if (Math.floor(along / 8) % 2 === 1)
+                    continue;
+                setPx(out, x, y, outline);
+            }
+        }
+        drawLabelBar(out, x0, y0, x1 - x0, "embedded view - not captured");
+    }
+    return out;
+}
+/** Test whether pixel (x,y) falls inside any hole rectangle. */
+export function isInsideHole(x, y, holes) {
+    for (const h of holes) {
+        if (x >= h.x && x < h.x + h.width && y >= h.y && y < h.y + h.height) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Nearest-neighbor downscale when the PNG is wider than maxWidth. */
+export function downscaleIfNeeded(pngBuf, maxWidth) {
+    const src = PNG.sync.read(pngBuf);
+    if (src.width <= maxWidth)
+        return pngBuf;
+    const scale = maxWidth / src.width;
+    const dstW = maxWidth;
+    const dstH = Math.max(1, Math.round(src.height * scale));
+    const dst = new PNG({ width: dstW, height: dstH });
+    for (let y = 0; y < dstH; y++) {
+        const sy = Math.min(src.height - 1, Math.floor(y / scale));
+        for (let x = 0; x < dstW; x++) {
+            const sx = Math.min(src.width - 1, Math.floor(x / scale));
+            const si = (src.width * sy + sx) << 2;
+            const di = (dstW * y + x) << 2;
+            dst.data[di] = src.data[si];
+            dst.data[di + 1] = src.data[si + 1];
+            dst.data[di + 2] = src.data[si + 2];
+            dst.data[di + 3] = src.data[si + 3];
+        }
+    }
+    return PNG.sync.write(dst);
+}
+function setPx(img, x, y, c) {
+    if (x < 0 || y < 0 || x >= img.width || y >= img.height)
+        return;
+    const i = (img.width * y + x) << 2;
+    img.data[i] = c.r;
+    img.data[i + 1] = c.g;
+    img.data[i + 2] = c.b;
+    img.data[i + 3] = c.a;
+}
+/**
+ * Solid filled label bar just inside the top edge of the hole.
+ * Uses 2×-scaled 5×7 glyphs so the text stays legible after downscale.
+ */
+function drawLabelBar(img, x0, y0, maxW, text) {
+    const scale = 2; // 5×7 → 10×14 glyphs
+    const pad = 6;
+    const charW = 5 * scale + 2; // 2px letter spacing
+    const charH = 7 * scale;
+    const barH = charH + pad * 2;
+    const neededW = pad * 2 + text.length * charW;
+    const barW = Math.min(maxW, Math.max(80, neededW));
+    // Inset 1px so the bar sits clearly inside the dashed outline.
+    const bx0 = x0 + 1;
+    const by0 = y0 + 1;
+    const x1 = Math.min(img.width, bx0 + barW);
+    const y1 = Math.min(img.height, by0 + barH);
+    // Fully opaque solid bar so text is readable over any app content.
+    for (let y = by0; y < y1; y++) {
+        for (let x = bx0; x < x1; x++) {
+            setPx(img, x, y, { r: 40, g: 24, b: 0, a: 255 });
+        }
+    }
+    let cx = bx0 + pad;
+    const cy = by0 + pad;
+    for (const ch of text) {
+        if (cx + 5 * scale > x1)
+            break;
+        drawChar(img, cx, cy, ch, { r: 255, g: 190, b: 70, a: 255 }, scale);
+        cx += charW;
+    }
+}
+function drawChar(img, x, y, ch, color, scale = 1) {
+    const g = GLYPHS[ch] ?? GLYPHS["?"];
+    for (let row = 0; row < 7; row++) {
+        const bits = g[row] ?? 0;
+        for (let col = 0; col < 5; col++) {
+            if (bits & (1 << (4 - col))) {
+                for (let dy = 0; dy < scale; dy++) {
+                    for (let dx = 0; dx < scale; dx++) {
+                        setPx(img, x + col * scale + dx, y + row * scale + dy, color);
+                    }
+                }
+            }
+        }
+    }
+}
+/** 5x7 glyphs (7 rows of 5-bit masks). Enough for the hole label alphabet. */
+const GLYPHS = {
+    " ": [0, 0, 0, 0, 0, 0, 0],
+    "-": [0, 0, 0, 0x1f, 0, 0, 0],
+    "?": [0x0e, 0x11, 0x01, 0x02, 0x04, 0, 0x04],
+    a: [0, 0x0e, 0x01, 0x0f, 0x11, 0x0f, 0],
+    b: [0x10, 0x10, 0x1e, 0x11, 0x11, 0x1e, 0],
+    c: [0, 0x0e, 0x11, 0x10, 0x11, 0x0e, 0],
+    d: [0x01, 0x01, 0x0f, 0x11, 0x11, 0x0f, 0],
+    e: [0, 0x0e, 0x11, 0x1f, 0x10, 0x0e, 0],
+    i: [0x04, 0, 0x0c, 0x04, 0x04, 0x0e, 0],
+    m: [0, 0x1b, 0x15, 0x15, 0x15, 0x15, 0],
+    n: [0, 0x1e, 0x11, 0x11, 0x11, 0x11, 0],
+    o: [0, 0x0e, 0x11, 0x11, 0x11, 0x0e, 0],
+    p: [0, 0x1e, 0x11, 0x1e, 0x10, 0x10, 0],
+    r: [0, 0x16, 0x19, 0x10, 0x10, 0x10, 0],
+    s: [0, 0x0f, 0x10, 0x0e, 0x01, 0x1e, 0],
+    t: [0x08, 0x1c, 0x08, 0x08, 0x08, 0x06, 0],
+    u: [0, 0x11, 0x11, 0x11, 0x13, 0x0d, 0],
+    v: [0, 0x11, 0x11, 0x11, 0x0a, 0x04, 0],
+    w: [0, 0x11, 0x11, 0x15, 0x15, 0x0a, 0],
+};

package/dist/core/session.d.ts

@@ -0,0 +1,54 @@
+import type { ElectronApplication, Page } from "playwright-core";
+import { type LaunchOptions } from "./launch.js";
+import { ConsoleCollector } from "./signals/console.js";
+import { MainProcessCollector } from "./signals/mainProcess.js";
+import { ResourcesCollector } from "./signals/resources.js";
+export interface SessionLaunchOptions extends LaunchOptions {
+    /** Force target window URL substring. */
+    windowUrlMatch?: string;
+    /** Extra console ignore patterns (appended to defaults). */
+    ignoreConsolePatterns?: string[];
+    /** Selectors that must be present + non-zero size (WARN if missing). */
+    criticalSelectors?: string[];
+    /** Source globs for stale-build detection. */
+    srcGlobs?: string[];
+    /** Promote bare console.error to hard-FAIL (default: WARN). */
+    strictConsole?: boolean;
+}
+/**
+ * One live Electron app under inspection.
+ * Signal collectors attach at launch so they accumulate across the session.
+ */
+export declare class AppSession {
+    readonly app: ElectronApplication;
+    private mainPage;
+    readonly consoleCollector: ConsoleCollector;
+    readonly mainProcessCollector: MainProcessCollector;
+    readonly resourcesCollector: ResourcesCollector;
+    readonly launchedAt: number;
+    readonly cwd: string;
+    readonly windowUrlMatch?: string;
+    readonly criticalSelectors?: string[];
+    readonly srcGlobs?: string[];
+    readonly strictConsole: boolean;
+    /**
+     * True when app_click / app_type / mutating app_evaluate ran since last verify.
+     * Used to default freshLoad=true when re-verifying an unchanged app.
+     */
+    interactionSinceVerify: boolean;
+    private constructor();
+    static launch(opts: SessionLaunchOptions): Promise<AppSession>;
+    /** The selected app window's renderer. */
+    page(): Page;
+    /** Update the target page (e.g. after re-select during verify). */
+    setPage(page: Page): void;
+    /** Mark that a mutating interaction happened (affects freshLoad default). */
+    noteInteraction(): void;
+    /** Call after verify completes so the next pass can re-check cleanly. */
+    clearInteractionFlag(): void;
+    /**
+     * Close the app. Races graceful close against a 5s timeout; on hang or throw,
+     * force-kills the process tree (Windows taskkill / Unix SIGKILL).
+     */
+    close(): Promise<void>;
+}

package/dist/core/session.js

@@ -0,0 +1,148 @@
+import { launchApp } from "./launch.js";
+import { ConsoleCollector } from "./signals/console.js";
+import { MainProcessCollector } from "./signals/mainProcess.js";
+import { ResourcesCollector } from "./signals/resources.js";
+import { selectTargetWindow } from "./windows.js";
+import path from "node:path";
+import { execSync } from "node:child_process";
+const CLOSE_TIMEOUT_MS = 5_000;
+/**
+ * One live Electron app under inspection.
+ * Signal collectors attach at launch so they accumulate across the session.
+ */
+export class AppSession {
+    app;
+    mainPage;
+    consoleCollector;
+    mainProcessCollector;
+    resourcesCollector;
+    launchedAt;
+    cwd;
+    windowUrlMatch;
+    criticalSelectors;
+    srcGlobs;
+    strictConsole;
+    /**
+     * True when app_click / app_type / mutating app_evaluate ran since last verify.
+     * Used to default freshLoad=true when re-verifying an unchanged app.
+     */
+    interactionSinceVerify = false;
+    constructor(app, mainPage, extras) {
+        this.app = app;
+        this.mainPage = mainPage;
+        this.consoleCollector = extras.consoleCollector;
+        this.mainProcessCollector = extras.mainProcessCollector;
+        this.resourcesCollector = extras.resourcesCollector;
+        this.launchedAt = extras.launchedAt;
+        this.cwd = extras.cwd;
+        this.windowUrlMatch = extras.windowUrlMatch;
+        this.criticalSelectors = extras.criticalSelectors;
+        this.srcGlobs = extras.srcGlobs;
+        this.strictConsole = extras.strictConsole === true;
+    }
+    static async launch(opts) {
+        const launchedAt = Date.now();
+        const cwd = path.resolve(opts.cwd ?? path.dirname(path.resolve(opts.appPath)));
+        const consoleCollector = new ConsoleCollector({
+            ignoreConsolePatterns: opts.ignoreConsolePatterns,
+        });
+        const mainProcessCollector = new MainProcessCollector();
+        const resourcesCollector = new ResourcesCollector();
+        const app = await launchApp(opts);
+        // Attach process collectors ASAP (before firstWindow) so boot stderr is captured.
+        mainProcessCollector.attach(app);
+        await consoleCollector.attachApp(app);
+        resourcesCollector.attachApp(app);
+        // Wait for at least one window, then pick the app-owned target (not BrowserView).
+        await app.firstWindow({ timeout: opts.launchTimeoutMs ?? 30_000 });
+        // Brief yield so multi-window shells (Pursuit) register both surfaces.
+        await new Promise((r) => setTimeout(r, 300));
+        const selected = await selectTargetWindow(app, {
+            windowUrlMatch: opts.windowUrlMatch,
+        });
+        // Ensure the selected page also has collectors (in case it appeared after attachApp).
+        consoleCollector.attachPage(selected.page);
+        resourcesCollector.attachPage(selected.page);
+        if (selected.warning) {
+            console.error(`[electron-verify] window select warning: ${selected.warning}`);
+        }
+        return new AppSession(app, selected.page, {
+            consoleCollector,
+            mainProcessCollector,
+            resourcesCollector,
+            launchedAt,
+            cwd,
+            windowUrlMatch: opts.windowUrlMatch,
+            criticalSelectors: opts.criticalSelectors,
+            srcGlobs: opts.srcGlobs,
+            strictConsole: opts.strictConsole,
+        });
+    }
+    /** The selected app window's renderer. */
+    page() {
+        return this.mainPage;
+    }
+    /** Update the target page (e.g. after re-select during verify). */
+    setPage(page) {
+        this.mainPage = page;
+        this.consoleCollector.attachPage(page);
+        this.resourcesCollector.attachPage(page);
+    }
+    /** Mark that a mutating interaction happened (affects freshLoad default). */
+    noteInteraction() {
+        this.interactionSinceVerify = true;
+    }
+    /** Call after verify completes so the next pass can re-check cleanly. */
+    clearInteractionFlag() {
+        this.interactionSinceVerify = false;
+    }
+    /**
+     * Close the app. Races graceful close against a 5s timeout; on hang or throw,
+     * force-kills the process tree (Windows taskkill / Unix SIGKILL).
+     */
+    async close() {
+        let pid;
+        try {
+            pid = this.app.process()?.pid;
+        }
+        catch {
+            pid = undefined;
+        }
+        const forceKill = () => {
+            if (pid == null)
+                return;
+            try {
+                if (process.platform === "win32") {
+                    execSync(`taskkill /PID ${pid} /T /F`, { stdio: "ignore" });
+                }
+                else {
+                    try {
+                        process.kill(pid, "SIGKILL");
+                    }
+                    catch {
+                        /* already dead */
+                    }
+                    // Also try via ElectronApplication process handle if still alive.
+                    try {
+                        this.app.process()?.kill("SIGKILL");
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+        };
+        try {
+            await Promise.race([
+                this.app.close(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("app.close timed out")), CLOSE_TIMEOUT_MS)),
+            ]);
+        }
+        catch {
+            forceKill();
+        }
+    }
+}