@mcoda/integrations 0.1.8 → 0.1.10

package/dist/qa/ChromiumQaAdapter.js

@@ -1,36 +1,1396 @@
 import path from 'node:path';
-import { exec as execCb } from 'node:child_process';
-import { promisify } from 'node:util';
+import os from 'node:os';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
 import fs from 'node:fs/promises';
-const exec = promisify(execCb);
 const shouldSkipInstall = (ctx) => process.env.MCODA_QA_SKIP_INSTALL === '1' || ctx.env?.MCODA_QA_SKIP_INSTALL === '1';
-export class ChromiumQaAdapter {
-    resolveCwd(profile, ctx) {
-        if (profile.working_dir) {
-            return path.isAbsolute(profile.working_dir)
-                ? profile.working_dir
-                : path.join(ctx.workspaceRoot, profile.working_dir);
+const DOCDEX_CHROMIUM_MISSING_MESSAGE = 'Docdex Chromium not available. Install via docdex or set MCODA_QA_CHROMIUM_PATH.';
+const DEFAULT_BROWSER_TIMEOUT_MS = 15000;
+const DEFAULT_BROWSER_URL = 'about:blank';
+const DOCDEX_STATE_ENV = 'DOCDEX_STATE_DIR';
+const DOCDEX_CONFIG_PATH_ENV = 'DOCDEX_CONFIG_PATH';
+const CHROMIUM_PATH_ENV = 'MCODA_QA_CHROMIUM_PATH';
+const CHROMIUM_HEADLESS_ENV = 'MCODA_QA_CHROMIUM_HEADLESS';
+const CHROMIUM_TIMEOUT_ENV = 'MCODA_QA_CHROMIUM_TIMEOUT_MS';
+const CHROMIUM_USER_AGENT_ENV = 'MCODA_QA_BROWSER_USER_AGENT';
+const CHROMIUM_PROFILE_ENV = 'MCODA_QA_BROWSER_USER_DATA_DIR';
+const CHROMIUM_PROFILE_ENV_ALIAS = 'MCODA_QA_CHROMIUM_USER_DATA_DIR';
+const DOCDEX_WEB_BROWSER_ENV = 'DOCDEX_WEB_BROWSER';
+const DOCDEX_CHROME_PATH_ENV = 'DOCDEX_CHROME_PATH';
+const DOCDEX_BROWSER_PROFILE_ENV = 'DOCDEX_BROWSER_USER_DATA_DIR';
+const DOCDEX_USER_AGENT_ENV = 'DOCDEX_WEB_USER_AGENT';
+const DOCDEX_BROWSER_CONCURRENCY_ENV = 'DOCDEX_WEB_MAX_CONCURRENT_BROWSER_FETCHES';
+const DEFAULT_USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+const CHROME_WINDOW_SIZE = '1920,1080';
+const CHROME_HEALTH_CHECK_TIMEOUT_MS = 800;
+const CHROME_STARTUP_TIMEOUT_MS = 10000;
+const CHROME_COOKIE_DISMISS_TIMEOUT_MS = 1500;
+const CDP_CONNECT_TIMEOUT_MS = 5000;
+const CDP_CALL_TIMEOUT_MS = 8000;
+const CHROME_THINK_DELAY_MIN_MS = 150;
+const CHROME_THINK_DELAY_MAX_MS = 650;
+const MIN_TEXT_LEN = 80;
+const COOKIE_DISMISS_SCRIPT = `(function () {
+  const acceptWords = ["accept", "agree", "allow", "ok", "okay", "got it", "yes"];
+  const cookieWords = ["cookie", "cookies", "consent", "gdpr", "privacy", "tracking"];
+  const nodes = Array.from(
+    document.querySelectorAll("button, a, input[type='button'], input[type='submit']")
+  );
+  for (const node of nodes) {
+    const raw = (node.innerText || node.value || "").trim().toLowerCase();
+    if (!raw) continue;
+    const hasAccept = acceptWords.some((word) => raw.includes(word));
+    const hasCookie = cookieWords.some((word) => raw.includes(word));
+    if (hasAccept && (hasCookie || raw.length <= 16)) {
+      node.click();
+      return true;
+    }
+  }
+  const selectors = [
+    "[id*='cookie']",
+    "[class*='cookie']",
+    "[id*='consent']",
+    "[class*='consent']",
+    "[aria-label*='cookie']",
+    "[aria-label*='consent']",
+    "[data-testid*='cookie']",
+    "[data-testid*='consent']",
+  ];
+  let removed = false;
+  for (const selector of selectors) {
+    document.querySelectorAll(selector).forEach((el) => {
+      el.remove();
+      removed = true;
+    });
+  }
+  return removed;
+})()`;
+const WEBDRIVER_OVERRIDE_SCRIPT = "Object.defineProperty(navigator, 'webdriver', { get: () => undefined });";
+const readJsonFile = async (filePath) => {
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+};
+const readTextFile = async (filePath) => {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
+const fileExists = async (filePath) => {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+};
+const resolveDocdexStateDir = () => {
+    const envDir = process.env[DOCDEX_STATE_ENV];
+    if (envDir && envDir.trim())
+        return envDir.trim();
+    return path.join(os.homedir(), '.docdex', 'state');
+};
+const resolveDocdexConfigPath = () => {
+    const envPath = process.env[DOCDEX_CONFIG_PATH_ENV];
+    if (envPath && envPath.trim())
+        return envPath.trim();
+    const stateDir = resolveDocdexStateDir();
+    const baseDir = path.dirname(stateDir);
+    return path.join(baseDir, 'config.toml');
+};
+const stripTomlInlineComment = (value) => {
+    let inSingle = false;
+    let inDouble = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (char === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (char === '"' && !inSingle) {
+            const prev = value[index - 1];
+            if (prev !== '\\') {
+                inDouble = !inDouble;
+            }
+            continue;
+        }
+        if (char === '#' && !inSingle && !inDouble) {
+            return value.slice(0, index).trim();
         }
-        return ctx.workspaceRoot;
     }
-    async ensureInstalled(profile, ctx) {
-        if (shouldSkipInstall(ctx))
-            return { ok: true, details: { skipped: true } };
-        const cwd = this.resolveCwd(profile, ctx);
+    return value.trim();
+};
+const parseTomlString = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return trimmed.slice(1, -1);
+        }
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1);
+    }
+    return undefined;
+};
+const parseTomlSection = (raw, section) => {
+    const lines = raw.split(/\r?\n/);
+    let inSection = false;
+    const result = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const sectionMatch = /^\[([^\]]+)\]$/.exec(trimmed);
+        if (sectionMatch) {
+            inSection = sectionMatch[1].trim() === section;
+            continue;
+        }
+        if (!inSection)
+            continue;
+        const match = /^([A-Za-z0-9_.-]+)\s*=\s*(.+)$/.exec(trimmed);
+        if (!match)
+            continue;
+        const key = match[1];
+        const rawValue = stripTomlInlineComment(match[2]);
+        const parsed = parseTomlString(rawValue);
+        if (parsed !== undefined)
+            result[key] = parsed;
+    }
+    return result;
+};
+const readDocdexScraperConfig = async () => {
+    const configPath = resolveDocdexConfigPath();
+    if (!configPath)
+        return {};
+    const raw = await readTextFile(configPath);
+    if (!raw)
+        return {};
+    const section = parseTomlSection(raw, 'web.scraper');
+    return {
+        chromeBinaryPath: section.chrome_binary_path,
+        userDataDir: section.user_data_dir,
+    };
+};
+const resolveDocdexBrowserProfileDir = () => path.join(resolveDocdexStateDir(), 'browser_profiles', 'chrome');
+const resolveBinaryFromPath = async (command) => {
+    const pathValue = process.env.PATH;
+    if (!pathValue)
+        return undefined;
+    const extensions = process.platform === 'win32'
+        ? [''].concat((process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM')
+            .split(';')
+            .filter(Boolean)
+            .map((ext) => {
+            const normalized = ext.startsWith('.') ? ext : `.${ext}`;
+            return normalized.toLowerCase();
+        }))
+        : [''];
+    for (const base of pathValue.split(path.delimiter)) {
+        if (!base)
+            continue;
+        for (const ext of extensions) {
+            const candidate = path.join(base, `${command}${ext}`);
+            if (await fileExists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+};
+const resolveBinaryHint = async (hint) => {
+    if (!hint)
+        return undefined;
+    const trimmed = hint.trim();
+    if (!trimmed)
+        return undefined;
+    if (await fileExists(trimmed))
+        return trimmed;
+    if (trimmed.includes('/') || trimmed.includes('\\'))
+        return undefined;
+    return await resolveBinaryFromPath(trimmed);
+};
+const resolveKnownChromiumPath = async () => {
+    if (process.platform === 'darwin') {
+        const candidate = '/Applications/Chromium.app/Contents/MacOS/Chromium';
+        return (await fileExists(candidate)) ? candidate : undefined;
+    }
+    if (process.platform === 'win32') {
+        const bases = [
+            process.env.PROGRAMFILES,
+            process.env['PROGRAMFILES(X86)'],
+            process.env.LOCALAPPDATA,
+        ].filter(Boolean);
+        for (const base of bases) {
+            const candidate = path.join(base, 'Chromium', 'Application', 'chrome.exe');
+            if (await fileExists(candidate))
+                return candidate;
+        }
+        return undefined;
+    }
+    const linuxCandidates = ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'];
+    for (const candidate of linuxCandidates) {
+        if (await fileExists(candidate))
+            return candidate;
+    }
+    return undefined;
+};
+const resolveDocdexChromiumBinary = async () => {
+    const overrides = [
+        process.env[CHROMIUM_PATH_ENV],
+        process.env[DOCDEX_WEB_BROWSER_ENV],
+        process.env[DOCDEX_CHROME_PATH_ENV],
+        process.env.CHROME_PATH,
+    ];
+    for (const override of overrides) {
+        const resolved = await resolveBinaryHint(override);
+        if (resolved)
+            return resolved;
+    }
+    const config = await readDocdexScraperConfig();
+    if (config.chromeBinaryPath && (await fileExists(config.chromeBinaryPath))) {
+        return config.chromeBinaryPath;
+    }
+    const manifestPath = path.join(resolveDocdexStateDir(), 'bin', 'chromium', 'manifest.json');
+    const manifest = await readJsonFile(manifestPath);
+    if (manifest?.path && (await fileExists(manifest.path))) {
+        return manifest.path;
+    }
+    const whichCandidate = (await resolveBinaryFromPath('chromium')) ?? (await resolveBinaryFromPath('chromium-browser'));
+    if (whichCandidate)
+        return whichCandidate;
+    return await resolveKnownChromiumPath();
+};
+export const resolveChromiumBinary = async () => resolveDocdexChromiumBinary();
+const isUrl = (value) => {
+    if (!value)
+        return false;
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+};
+const parseBoolean = (value) => {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'y', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'n', 'off'].includes(normalized))
+        return false;
+    return undefined;
+};
+const resolveHeadless = (ctx) => {
+    const envValue = ctx.env?.[CHROMIUM_HEADLESS_ENV] ?? process.env[CHROMIUM_HEADLESS_ENV];
+    const parsed = parseBoolean(envValue);
+    return parsed ?? true;
+};
+const resolveTimeoutMs = (ctx) => {
+    const raw = ctx.env?.[CHROMIUM_TIMEOUT_ENV] ?? process.env[CHROMIUM_TIMEOUT_ENV];
+    const parsed = raw ? Number(raw) : NaN;
+    return Number.isFinite(parsed) ? parsed : DEFAULT_BROWSER_TIMEOUT_MS;
+};
+const resolveUserAgent = (ctx) => {
+    const envAgent = ctx.env?.[CHROMIUM_USER_AGENT_ENV] ??
+        process.env[CHROMIUM_USER_AGENT_ENV] ??
+        process.env[DOCDEX_USER_AGENT_ENV];
+    return envAgent?.trim() || DEFAULT_USER_AGENT;
+};
+const resolveUserDataDir = async (ctx) => {
+    const envPath = ctx.env?.[CHROMIUM_PROFILE_ENV] ??
+        ctx.env?.[CHROMIUM_PROFILE_ENV_ALIAS] ??
+        process.env[CHROMIUM_PROFILE_ENV] ??
+        process.env[CHROMIUM_PROFILE_ENV_ALIAS] ??
+        process.env[DOCDEX_BROWSER_PROFILE_ENV];
+    if (envPath && envPath.trim()) {
+        const resolved = envPath.trim();
+        await fs.mkdir(resolved, { recursive: true });
+        return { path: resolved, cleanup: null };
+    }
+    const config = await readDocdexScraperConfig();
+    if (config.userDataDir && config.userDataDir.trim()) {
+        const resolved = config.userDataDir.trim();
+        await fs.mkdir(resolved, { recursive: true });
+        return { path: resolved, cleanup: null };
+    }
+    const defaultPath = resolveDocdexBrowserProfileDir();
+    await fs.mkdir(defaultPath, { recursive: true });
+    return { path: defaultPath, cleanup: null };
+};
+const createTempUserDataDir = async () => {
+    const tempBase = path.join(os.tmpdir(), 'mcoda-qa-chrome-');
+    const tempDir = await fs.mkdtemp(tempBase);
+    return {
+        path: tempDir,
+        cleanup: async () => {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        },
+    };
+};
+const resolveBrowserTarget = (profile, ctx) => {
+    const override = ctx.browserBaseUrl ?? ctx.testCommandOverride ?? profile.test_command;
+    if (override && isUrl(override))
+        return override;
+    return undefined;
+};
+const randomDelayMs = (minMs, maxMs) => {
+    if (maxMs <= minMs)
+        return minMs;
+    const span = maxMs - minMs;
+    return minMs + Math.floor(Math.random() * (span + 1));
+};
+const resolveChromeFetchConcurrency = () => {
+    const raw = process.env[DOCDEX_BROWSER_CONCURRENCY_ENV];
+    const parsed = raw ? Number(raw) : NaN;
+    if (Number.isFinite(parsed) && parsed > 0)
+        return Math.floor(parsed);
+    return 1;
+};
+class Semaphore {
+    constructor(capacity) {
+        this.queue = [];
+        this.available = Math.max(1, Math.floor(capacity));
+    }
+    async acquire() {
+        if (this.available > 0) {
+            this.available -= 1;
+            return () => this.release();
+        }
+        return await new Promise((resolve) => {
+            this.queue.push(() => resolve(() => this.release()));
+        });
+    }
+    release() {
+        this.available += 1;
+        const next = this.queue.shift();
+        if (next) {
+            this.available -= 1;
+            next();
+        }
+    }
+}
+const chromeFetchSemaphore = new Semaphore(resolveChromeFetchConcurrency());
+class ChromeInstance {
+    constructor(child, debugPort, config, ownsProcess) {
+        this.child = child;
+        this.debugPort = debugPort;
+        this.config = config;
+        this.ownsProcess = ownsProcess;
+    }
+    static async spawn(config, env) {
+        const debugPort = await pickFreePort();
+        await clearDevtoolsPort(config.userDataDir.path);
+        const launchContext = {
+            chromeBinary: config.chromeBinary,
+            headless: config.headless,
+            userAgent: config.userAgent,
+            userDataDir: config.userDataDir.path,
+            debugPort,
+        };
+        const args = chromeCommonArgs(launchContext);
+        args.push('about:blank');
+        const child = spawn(config.chromeBinary, args, {
+            detached: process.platform !== 'win32',
+            stdio: 'ignore',
+            env: { ...process.env, ...env },
+        });
+        child.unref();
+        try {
+            await waitForCdpReady(debugPort, CHROME_STARTUP_TIMEOUT_MS);
+        }
+        catch (err) {
+            await terminateProcessTree(child);
+            throw err;
+        }
+        return new ChromeInstance(child, debugPort, config, true);
+    }
+    static attachExisting(config, debugPort) {
+        return new ChromeInstance(null, debugPort, config, false);
+    }
+    matches(config) {
+        return (this.config.chromeBinary === config.chromeBinary &&
+            this.config.headless === config.headless &&
+            this.config.userAgent === config.userAgent &&
+            this.config.userDataDir.path === config.userDataDir.path);
+    }
+    async isHealthy() {
+        if (this.child && this.child.exitCode !== null)
+            return false;
+        return await probeCdp(this.debugPort);
+    }
+    getDebugPort() {
+        return this.debugPort;
+    }
+    async fetchDom(url, timeoutMs) {
+        const target = await createCdpTarget(this.debugPort, CHROME_STARTUP_TIMEOUT_MS);
+        try {
+            return await fetchDomViaCdp(target.wsUrl, url, timeoutMs);
+        }
+        finally {
+            if (target.targetId) {
+                try {
+                    await closeCdpTarget(this.debugPort, target.targetId);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    async shutdown() {
+        if (this.ownsProcess && this.child) {
+            await terminateProcessTree(this.child);
+        }
+        if (this.ownsProcess && this.config.userDataDir.cleanup) {
+            try {
+                await this.config.userDataDir.cleanup();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+class ChromeManager {
+    async getOrLaunch(config, env) {
+        const effectiveConfig = this.fallbackUserDataDir
+            ? { ...config, userDataDir: this.fallbackUserDataDir }
+            : config;
+        if (this.instance) {
+            if (this.instance.matches(effectiveConfig) && (await this.instance.isHealthy())) {
+                return this.instance;
+            }
+            await this.resetIfCurrent(this.instance);
+        }
+        if (this.launching) {
+            const instance = await this.launching;
+            if (instance.matches(effectiveConfig) && (await instance.isHealthy())) {
+                this.instance = instance;
+                return instance;
+            }
+        }
+        const existingPort = await readDevtoolsPort(effectiveConfig.userDataDir.path);
+        if (existingPort && (await probeCdp(existingPort))) {
+            const existing = ChromeInstance.attachExisting(effectiveConfig, existingPort);
+            this.instance = existing;
+            return existing;
+        }
+        const spawnInstance = async (targetConfig) => {
+            this.launching = ChromeInstance.spawn(targetConfig, env);
+            try {
+                const instance = await this.launching;
+                this.instance = instance;
+                return instance;
+            }
+            finally {
+                this.launching = undefined;
+            }
+        };
+        try {
+            return await spawnInstance(effectiveConfig);
+        }
+        catch (err) {
+            if (!this.fallbackUserDataDir && !effectiveConfig.userDataDir.cleanup) {
+                const tempUserDataDir = await createTempUserDataDir();
+                this.fallbackUserDataDir = tempUserDataDir;
+                return await spawnInstance({ ...config, userDataDir: tempUserDataDir });
+            }
+            throw err;
+        }
+    }
+    async resetIfCurrent(instance) {
+        if (this.instance !== instance)
+            return false;
+        this.instance = undefined;
+        await instance.shutdown();
+        return true;
+    }
+    async resetIfUnhealthy(instance) {
+        if (await instance.isHealthy())
+            return false;
+        return await this.resetIfCurrent(instance);
+    }
+}
+const chromeManager = new ChromeManager();
+const chromeCommonArgs = (ctx) => {
+    const args = [];
+    if (ctx.headless)
+        args.push('--headless=new');
+    args.push('--disable-gpu');
+    args.push('--disable-extensions');
+    args.push('--disable-dev-shm-usage');
+    args.push('--disable-blink-features=AutomationControlled');
+    args.push('--no-sandbox');
+    args.push('--no-first-run');
+    args.push('--no-default-browser-check');
+    args.push('--remote-allow-origins=*');
+    args.push(`--window-size=${CHROME_WINDOW_SIZE}`);
+    args.push(`--user-data-dir=${ctx.userDataDir}`);
+    args.push('--disable-background-timer-throttling');
+    args.push('--disable-backgrounding-occluded-windows');
+    args.push('--disable-renderer-backgrounding');
+    args.push('--run-all-compositor-stages-before-draw');
+    args.push(`--user-agent=${ctx.userAgent}`);
+    args.push('--remote-debugging-address=127.0.0.1');
+    args.push(`--remote-debugging-port=${ctx.debugPort}`);
+    return args;
+};
+const clearDevtoolsPort = async (userDataDir) => {
+    const portFile = path.join(userDataDir, 'DevToolsActivePort');
+    try {
+        await fs.rm(portFile, { force: true });
+    }
+    catch {
+        // ignore
+    }
+};
+const readDevtoolsPort = async (userDataDir) => {
+    const portFile = path.join(userDataDir, 'DevToolsActivePort');
+    try {
+        const raw = await fs.readFile(portFile, 'utf8');
+        const [portLine] = raw.trim().split(/\s+/);
+        const port = Number(portLine);
+        if (Number.isFinite(port) && port > 0)
+            return port;
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+};
+const pickFreePort = async () => await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+        const address = server.address();
+        if (typeof address === 'object' && address?.port) {
+            const port = address.port;
+            server.close(() => resolve(port));
+        }
+        else {
+            server.close(() => reject(new Error('Failed to acquire free port')));
+        }
+    });
+});
+const fetchWithTimeout = async (url, timeoutMs, init) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { signal: controller.signal, ...init });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const probeCdp = async (port) => {
+    try {
+        const resp = await fetchWithTimeout(`http://127.0.0.1:${port}/json/version`, CHROME_HEALTH_CHECK_TIMEOUT_MS);
+        return resp.ok;
+    }
+    catch {
+        return false;
+    }
+};
+const waitForCdpReady = async (port, timeoutMs) => {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (await probeCdp(port))
+            return;
+        await delay(100);
+    }
+    throw new Error(`devtools endpoint not available within ${timeoutMs}ms`);
+};
+const extractCdpTarget = (value) => {
+    if (value && typeof value === 'object' && value.webSocketDebuggerUrl) {
+        return { wsUrl: String(value.webSocketDebuggerUrl), targetId: value.id ? String(value.id) : undefined };
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (item && item.webSocketDebuggerUrl) {
+                return { wsUrl: String(item.webSocketDebuggerUrl), targetId: item.id ? String(item.id) : undefined };
+            }
+        }
+    }
+    return undefined;
+};
+const fetchDevtoolsTarget = async (endpoint, method = 'GET') => {
+    const resp = await fetchWithTimeout(endpoint, CHROME_HEALTH_CHECK_TIMEOUT_MS, { method });
+    if (!resp.ok) {
+        throw new Error(`devtools endpoint ${endpoint} failed with status ${resp.status}`);
+    }
+    const body = await resp.text();
+    try {
+        const value = JSON.parse(body);
+        return extractCdpTarget(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+const createCdpTarget = async (port, timeoutMs) => {
+    const endpointNew = `http://127.0.0.1:${port}/json/new`;
+    const endpointList = `http://127.0.0.1:${port}/json/list`;
+    const start = Date.now();
+    let lastError;
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const target = await fetchDevtoolsTarget(endpointNew, 'PUT');
+            if (target)
+                return target;
+        }
+        catch (err) {
+            lastError = err;
+        }
+        try {
+            const target = await fetchDevtoolsTarget(endpointList);
+            if (target)
+                return target;
+        }
+        catch (err) {
+            lastError = err;
+        }
+        await delay(100);
+    }
+    if (lastError)
+        throw lastError;
+    throw new Error(`devtools websocket not available within ${timeoutMs}ms`);
+};
+const closeCdpTarget = async (port, targetId) => {
+    const endpoint = `http://127.0.0.1:${port}/json/close/${targetId}`;
+    const resp = await fetchWithTimeout(endpoint, CHROME_HEALTH_CHECK_TIMEOUT_MS);
+    if (!resp.ok) {
+        throw new Error(`devtools close target ${targetId} failed with status ${resp.status}`);
+    }
+};
+class MessageQueue {
+    constructor() {
+        this.queue = [];
+        this.resolvers = [];
+    }
+    push(value) {
+        const resolver = this.resolvers.shift();
+        if (resolver) {
+            resolver(value);
+            return;
+        }
+        this.queue.push(value);
+    }
+    async next(timeoutMs) {
+        if (this.queue.length)
+            return this.queue.shift();
+        return await new Promise((resolve) => {
+            const timer = typeof timeoutMs === 'number'
+                ? setTimeout(() => {
+                    this.resolvers = this.resolvers.filter((r) => r !== resolve);
+                    resolve(undefined);
+                }, timeoutMs)
+                : undefined;
+            this.resolvers.push((value) => {
+                if (timer)
+                    clearTimeout(timer);
+                resolve(value);
+            });
+        });
+    }
+}
+class NetworkIdleTracker {
+    constructor() {
+        this.inflight = 0;
+        this.lastActivity = Date.now();
+        this.sawLoad = false;
+    }
+    handle(method, params) {
+        switch (method) {
+            case 'Network.requestWillBeSent':
+                this.inflight += 1;
+                this.lastActivity = Date.now();
+                break;
+            case 'Network.loadingFinished':
+            case 'Network.loadingFailed':
+                this.inflight = Math.max(0, this.inflight - 1);
+                this.lastActivity = Date.now();
+                break;
+            case 'Network.responseReceived': {
+                const resourceType = params?.type;
+                if (resourceType === 'Document') {
+                    const status = params?.response?.status;
+                    const url = params?.response?.url;
+                    if (typeof status === 'number')
+                        this.documentStatus = status;
+                    if (typeof url === 'string')
+                        this.documentUrl = url;
+                }
+                this.lastActivity = Date.now();
+                break;
+            }
+            case 'Page.loadEventFired':
+                this.sawLoad = true;
+                this.lastActivity = Date.now();
+                break;
+            default:
+                break;
+        }
+    }
+}
+class CdpClient {
+    static async connect(wsUrl) {
+        const WebSocketImpl = globalThis.WebSocket;
+        if (!WebSocketImpl) {
+            throw new Error('WebSocket is not available in this Node runtime.');
+        }
+        const ws = new WebSocketImpl(wsUrl);
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error('devtools websocket connect timeout'));
+            }, CDP_CONNECT_TIMEOUT_MS);
+            ws.addEventListener('open', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            ws.addEventListener('error', (event) => {
+                clearTimeout(timer);
+                reject(new Error(event?.message || 'devtools websocket error'));
+            });
+            ws.addEventListener('close', () => {
+                clearTimeout(timer);
+            });
+        });
+        return new CdpClient(ws);
+    }
+    constructor(ws) {
+        this.queue = new MessageQueue();
+        this.nextId = 1;
+        this.closed = false;
+        this.ws = ws;
+        ws.addEventListener('message', (event) => {
+            const data = event?.data ?? event;
+            let text = '';
+            if (typeof data === 'string')
+                text = data;
+            else if (data instanceof Buffer)
+                text = data.toString('utf8');
+            else if (data instanceof ArrayBuffer)
+                text = Buffer.from(data).toString('utf8');
+            else if (ArrayBuffer.isView(data))
+                text = Buffer.from(data.buffer).toString('utf8');
+            else
+                text = String(data ?? '');
+            if (!text.trim())
+                return;
+            try {
+                const value = JSON.parse(text);
+                this.queue.push(value);
+            }
+            catch {
+                // ignore malformed
+            }
+        });
+        ws.addEventListener('close', () => {
+            this.closed = true;
+            this.queue.push({ __closed: true });
+        });
+        ws.addEventListener('error', (event) => {
+            this.queue.push({ __error: event?.message || 'devtools websocket error' });
+        });
+    }
+    async call(method, params, tracker, timeoutMs = CDP_CALL_TIMEOUT_MS) {
+        if (this.closed)
+            throw new Error('devtools websocket closed');
+        const id = this.nextId++;
+        this.ws.send(JSON.stringify({ id, method, params }));
+        const startedAt = Date.now();
+        while (true) {
+            const remaining = timeoutMs - (Date.now() - startedAt);
+            if (Number.isFinite(timeoutMs) && remaining <= 0) {
+                throw new Error(`devtools timeout waiting for ${method}`);
+            }
+            const message = await this.queue.next(Number.isFinite(timeoutMs) ? Math.max(0, remaining) : undefined);
+            if (!message && Number.isFinite(timeoutMs)) {
+                throw new Error(`devtools timeout waiting for ${method}`);
+            }
+            if (!message)
+                continue;
+            if (message.__closed)
+                throw new Error('devtools websocket closed');
+            if (message.__error)
+                throw new Error(String(message.__error));
+            if (message.id === id) {
+                if (message.error) {
+                    throw new Error(`devtools error for ${method}: ${JSON.stringify(message.error)}`);
+                }
+                return message.result ?? null;
+            }
+            if (message.method && tracker) {
+                tracker.handle(message.method, message.params);
+            }
+        }
+    }
+    async waitForNetworkIdle(tracker, timeoutMs) {
+        const idleDelay = 800;
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            const elapsed = Date.now() - start;
+            const idleReady = tracker.inflight === 0 &&
+                Date.now() - tracker.lastActivity >= idleDelay &&
+                (tracker.sawLoad || elapsed >= idleDelay);
+            if (idleReady)
+                return true;
+            const remaining = timeoutMs - elapsed;
+            const waitFor = tracker.inflight === 0
+                ? Math.min(idleDelay - (Date.now() - tracker.lastActivity), remaining)
+                : Math.min(100, remaining);
+            const message = await this.queue.next(Math.max(0, waitFor));
+            if (message?.method) {
+                tracker.handle(message.method, message.params);
+            }
+        }
+        return false;
+    }
+    close() {
         try {
-            await exec('npx playwright --version', { cwd, env: { ...process.env, ...profile.env, ...ctx.env } });
-            return { ok: true };
+            this.ws.close();
+        }
+        catch {
+            // ignore
         }
-        catch (versionError) {
-            const installCommand = profile.install_command ?? 'npx playwright install chromium';
+    }
+}
+const injectWebdriverOverride = async (client) => {
+    await client.call('Page.addScriptToEvaluateOnNewDocument', { source: WEBDRIVER_OVERRIDE_SCRIPT });
+};
+const dismissCookieBanners = async (client) => {
+    const result = await client.call('Runtime.evaluate', {
+        expression: COOKIE_DISMISS_SCRIPT,
+        returnByValue: true,
+    });
+    return Boolean(result?.result?.value ?? result?.value ?? false);
+};
+const evalString = async (client, expression) => {
+    const result = await client.call('Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+    });
+    const value = result?.result?.value ?? result?.value;
+    return typeof value === 'string' ? value : '';
+};
+const evalNumber = async (client, expression) => {
+    const result = await client.call('Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+    });
+    const value = result?.result?.value ?? result?.value;
+    return typeof value === 'number' ? value : Number(value) || 0;
+};
+const captureDomText = async (client, timeoutMs, pollIntervalMs, useInnerText) => {
+    const start = Date.now();
+    const expression = useInnerText
+        ? 'document.body ? document.body.innerText : ""'
+        : 'document.body ? document.body.textContent : ""';
+    let lastValue = '';
+    while (Date.now() - start < timeoutMs) {
+        const value = await evalString(client, expression).catch(() => '');
+        if (value.trim())
+            return value.trim();
+        lastValue = value;
+        await delay(pollIntervalMs);
+    }
+    return lastValue.trim();
+};
+const evalJson = async (client, expression) => {
+    const result = await client.call('Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+    });
+    return result?.result?.value ?? result?.value;
+};
+const resolveActionTimeoutMs = (action, fallbackMs) => {
+    if ('timeout_ms' in action && typeof action.timeout_ms === 'number') {
+        const value = Math.round(action.timeout_ms);
+        if (Number.isFinite(value) && value > 0)
+            return value;
+    }
+    return fallbackMs;
+};
+const resolveActionUrl = (actionUrl, baseUrl) => {
+    if (actionUrl && isUrl(actionUrl))
+        return actionUrl;
+    if (!baseUrl || !isUrl(baseUrl))
+        return undefined;
+    if (!actionUrl)
+        return baseUrl;
+    try {
+        return new URL(actionUrl, baseUrl).toString();
+    }
+    catch {
+        return baseUrl;
+    }
+};
+const waitForDocumentReady = async (client, timeoutMs) => {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const readyState = await evalString(client, 'document.readyState');
+        if (readyState === 'complete' || readyState === 'interactive')
+            return true;
+        await delay(200);
+    }
+    return false;
+};
+const waitForSelector = async (client, selector, timeoutMs) => {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const exists = await evalJson(client, `Boolean(document.querySelector(${JSON.stringify(selector)}))`);
+        if (exists)
+            return true;
+        await delay(200);
+    }
+    return false;
+};
+const clickSelector = async (client, selector, text) => {
+    const expression = `(function () {
+    const selector = ${JSON.stringify(selector)};
+    const text = ${text ? JSON.stringify(text) : 'null'};
+    const nodes = Array.from(document.querySelectorAll(selector));
+    if (!nodes.length) return { ok: false, message: 'element not found' };
+    let target = nodes[0];
+    if (text) {
+      const normalized = text.toLowerCase();
+      target =
+        nodes.find((node) =>
+          ((node.innerText || node.textContent || '') + '').toLowerCase().includes(normalized),
+        ) || null;
+    }
+    if (!target) return { ok: false, message: 'element with text not found' };
+    if (target.scrollIntoView) target.scrollIntoView({ block: 'center', inline: 'center' });
+    if (target.click) target.click();
+    return { ok: true };
+  })()`;
+    const result = await evalJson(client, expression);
+    if (result?.ok)
+        return { ok: true };
+    return { ok: false, message: result?.message || 'click failed' };
+};
+const typeSelector = async (client, selector, text, clear) => {
+    const expression = `(function () {
+    const selector = ${JSON.stringify(selector)};
+    const text = ${JSON.stringify(text)};
+    const clear = ${clear ? 'true' : 'false'};
+    const el = document.querySelector(selector);
+    if (!el) return { ok: false, message: 'element not found' };
+    if (el.focus) el.focus();
+    if (clear && 'value' in el) {
+      el.value = '';
+    }
+    if ('value' in el) {
+      el.value = String(el.value ?? '') + text;
+    } else {
+      el.textContent = String(el.textContent ?? '') + text;
+    }
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    return { ok: true };
+  })()`;
+    const result = await evalJson(client, expression);
+    if (result?.ok)
+        return { ok: true };
+    return { ok: false, message: result?.message || 'type failed' };
+};
+const assertText = async (client, selector, text, contains) => {
+    const expression = selector
+        ? `(() => {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        return el ? (el.innerText || el.textContent || '') : '';
+      })()`
+        : `document.body ? (document.body.innerText || document.body.textContent || '') : ''`;
+    const actual = String((await evalJson(client, expression)) ?? '');
+    const matches = contains ? actual.includes(text) : actual.trim() === text;
+    if (matches)
+        return { ok: true };
+    return {
+        ok: false,
+        message: `assert_text failed (expected ${contains ? 'contains' : 'equals'} "${text}")`,
+    };
+};
+const captureSnapshot = async (client, index, name) => {
+    const html = await evalString(client, 'document.documentElement.outerHTML');
+    const innerText = await evalString(client, 'document.body ? document.body.innerText : ""');
+    const textContent = await evalString(client, 'document.body ? document.body.textContent : ""');
+    const url = await evalString(client, 'document.location.href');
+    return {
+        index,
+        name,
+        html: html || '',
+        innerText: innerText || undefined,
+        textContent: textContent || undefined,
+        url: url || undefined,
+    };
+};
+const captureFinalDom = async (client) => {
+    const html = await evalString(client, 'document.documentElement.outerHTML');
+    const innerText = await evalString(client, 'document.body ? document.body.innerText : ""');
+    const textContent = await evalString(client, 'document.body ? document.body.textContent : ""');
+    const url = await evalString(client, 'document.location.href');
+    return {
+        html: html || '',
+        innerText: innerText || undefined,
+        textContent: textContent || undefined,
+        status: undefined,
+        finalUrl: url || undefined,
+    };
+};
+const fetchDomViaCdp = async (wsUrl, url, timeoutMs) => {
+    const deadline = Date.now() + timeoutMs;
+    const targetUrl = url ?? DEFAULT_BROWSER_URL;
+    const allowBlank = targetUrl === DEFAULT_BROWSER_URL;
+    const client = await CdpClient.connect(wsUrl);
+    try {
+        await client.call('Network.enable', {});
+        await client.call('Page.enable', {});
+        await client.call('Runtime.enable', {});
+        await injectWebdriverOverride(client);
+        const thinkDelay = randomDelayMs(CHROME_THINK_DELAY_MIN_MS, CHROME_THINK_DELAY_MAX_MS);
+        if (thinkDelay > 0)
+            await delay(thinkDelay);
+        const navResult = await client.call('Page.navigate', { url: targetUrl });
+        if (navResult?.errorText) {
+            throw new Error(`navigation failed: ${navResult.errorText}`);
+        }
+        const dismissed = await dismissCookieBanners(client).catch(() => false);
+        if (dismissed) {
+            const followUp = Math.min(Math.max(0, deadline - Date.now()), CHROME_COOKIE_DISMISS_TIMEOUT_MS);
+            if (followUp > 0)
+                await delay(followUp);
+        }
+        let html = '';
+        let finalUrl;
+        const pollInterval = 200;
+        while (Date.now() < deadline) {
+            const href = await evalString(client, 'document.location.href');
+            if (!finalUrl && href.trim())
+                finalUrl = href.trim();
+            const readyState = await evalString(client, 'document.readyState');
+            const textLen = await evalNumber(client, 'document.body ? document.body.innerText.length : 0');
+            const htmlValue = await evalString(client, 'document.documentElement.outerHTML');
+            if (htmlValue.trim())
+                html = htmlValue;
+            const hasText = textLen >= MIN_TEXT_LEN;
+            const readyComplete = readyState === 'complete' && (allowBlank || href !== 'about:blank');
+            if (hasText || readyComplete)
+                break;
+            await delay(pollInterval);
+        }
+        if (!html.trim())
+            throw new Error('devtools returned empty HTML');
+        const remaining = Math.max(0, deadline - Date.now());
+        const innerText = await captureDomText(client, remaining, pollInterval, true);
+        const textContent = await captureDomText(client, remaining, pollInterval, false);
+        return {
+            html,
+            innerText: innerText || undefined,
+            textContent: textContent || undefined,
+            status: undefined,
+            finalUrl,
+        };
+    }
+    finally {
+        client.close();
+    }
+};
+const runBrowserActionsWithClient = async (client, actions, baseUrl, timeoutMs) => {
+    await client.call('Network.enable', {});
+    await client.call('Page.enable', {});
+    await client.call('Runtime.enable', {});
+    await injectWebdriverOverride(client);
+    const tracker = new NetworkIdleTracker();
+    const results = [];
+    const snapshots = [];
+    for (let index = 0; index < actions.length; index += 1) {
+        const action = actions[index];
+        const actionType = action.type;
+        const actionIndex = index + 1;
+        const startedAt = Date.now();
+        const actionTimeoutMs = resolveActionTimeoutMs(action, timeoutMs);
+        try {
+            if (action.type === 'navigate') {
+                const targetUrl = resolveActionUrl(action.url, baseUrl);
+                if (!targetUrl) {
+                    throw new Error('navigate requires base_url or absolute url');
+                }
+                const navResult = await client.call('Page.navigate', { url: targetUrl }, tracker, actionTimeoutMs);
+                if (navResult?.errorText) {
+                    throw new Error(`navigation failed: ${navResult.errorText}`);
+                }
+                if (action.wait_for === 'idle') {
+                    await client.waitForNetworkIdle(tracker, actionTimeoutMs);
+                }
+                else {
+                    await waitForDocumentReady(client, actionTimeoutMs);
+                }
+                await dismissCookieBanners(client).catch(() => false);
+                results.push({
+                    index: actionIndex,
+                    type: actionType,
+                    ok: true,
+                    url: targetUrl,
+                    durationMs: Date.now() - startedAt,
+                });
+                continue;
+            }
+            if (action.type === 'click') {
+                const clickResult = await clickSelector(client, action.selector, action.text);
+                if (!clickResult.ok)
+                    throw new Error(clickResult.message ?? 'click failed');
+                results.push({
+                    index: actionIndex,
+                    type: actionType,
+                    ok: true,
+                    durationMs: Date.now() - startedAt,
+                });
+                continue;
+            }
+            if (action.type === 'type') {
+                const typeResult = await typeSelector(client, action.selector, action.text, action.clear ?? true);
+                if (!typeResult.ok)
+                    throw new Error(typeResult.message ?? 'type failed');
+                results.push({
+                    index: actionIndex,
+                    type: actionType,
+                    ok: true,
+                    durationMs: Date.now() - startedAt,
+                });
+                continue;
+            }
+            if (action.type === 'wait_for') {
+                if (action.selector) {
+                    const ok = await waitForSelector(client, action.selector, actionTimeoutMs);
+                    if (!ok) {
+                        throw new Error(`wait_for timeout for selector ${action.selector}`);
+                    }
+                }
+                else {
+                    await delay(actionTimeoutMs);
+                }
+                results.push({
+                    index: actionIndex,
+                    type: actionType,
+                    ok: true,
+                    durationMs: Date.now() - startedAt,
+                });
+                continue;
+            }
+            if (action.type === 'assert_text') {
+                const assertResult = await assertText(client, action.selector, action.text, action.contains ?? true);
+                if (!assertResult.ok)
+                    throw new Error(assertResult.message ?? 'assert_text failed');
+                results.push({
+                    index: actionIndex,
+                    type: actionType,
+                    ok: true,
+                    durationMs: Date.now() - startedAt,
+                });
+                continue;
+            }
+            if (action.type === 'snapshot') {
+                const name = action.name?.trim() || `snapshot-${actionIndex}`;
+                const snapshot = await captureSnapshot(client, actionIndex, name);
+                snapshots.push(snapshot);
+                results.push({
+                    index: actionIndex,
+                    type: actionType,
+                    ok: true,
+                    durationMs: Date.now() - startedAt,
+                });
+                continue;
+            }
+            if (action.type === 'script') {
+                const value = await evalJson(client, action.expression);
+                if (action.expect !== undefined) {
+                    const actual = value === undefined || value === null ? '' : String(value);
+                    if (!actual.includes(action.expect)) {
+                        throw new Error(`script expect failed (expected "${action.expect}")`);
+                    }
+                }
+                results.push({
+                    index: actionIndex,
+                    type: actionType,
+                    ok: true,
+                    durationMs: Date.now() - startedAt,
+                });
+                continue;
+            }
+            results.push({
+                index: actionIndex,
+                type: actionType,
+                ok: false,
+                message: 'unsupported action',
+                durationMs: Date.now() - startedAt,
+            });
+            return {
+                outcome: 'fail',
+                errorMessage: 'unsupported action',
+                results,
+                snapshots,
+                finalDom: await captureFinalDom(client).catch(() => undefined),
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({
+                index: actionIndex,
+                type: actionType,
+                ok: false,
+                message,
+                durationMs: Date.now() - startedAt,
+            });
+            return {
+                outcome: 'fail',
+                errorMessage: message,
+                results,
+                snapshots,
+                finalDom: await captureFinalDom(client).catch(() => undefined),
+            };
+        }
+    }
+    return {
+        outcome: 'pass',
+        results,
+        snapshots,
+        finalDom: await captureFinalDom(client).catch(() => undefined),
+    };
+};
+const runDumpDom = async (chromeBinary, url, headless, userAgent, userDataDir, timeoutMs) => {
+    const targetUrl = url ?? DEFAULT_BROWSER_URL;
+    const args = chromeCommonArgs({
+        chromeBinary,
+        headless,
+        userAgent,
+        userDataDir,
+        debugPort: 0,
+    }).filter((arg) => !arg.startsWith('--remote-debugging-'));
+    args.push('--virtual-time-budget=15000');
+    args.push('--dump-dom');
+    args.push(targetUrl);
+    const child = spawn(chromeBinary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => {
+        stdout += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderr += chunk.toString();
+    });
+    const result = await new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGTERM');
+            setTimeout(() => child.kill('SIGKILL'), 2000).unref();
+            resolve({ exitCode: null, timedOut: true });
+        }, timeoutMs);
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode: code ?? null, timedOut: false });
+        });
+        child.on('error', () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode: null, timedOut: false });
+        });
+    });
+    return { html: stdout.trim(), stdout, stderr, exitCode: result.exitCode, timedOut: result.timedOut };
+};
+const terminateProcessTree = async (child) => {
+    if (!child.pid || child.exitCode !== null)
+        return;
+    try {
+        if (process.platform !== 'win32') {
             try {
-                await exec(installCommand, { cwd, env: { ...process.env, ...profile.env, ...ctx.env } });
-                return { ok: true, details: { installedVia: installCommand } };
+                process.kill(-child.pid, 'SIGTERM');
+            }
+            catch {
+                child.kill('SIGTERM');
+            }
+        }
+        else {
+            child.kill('SIGTERM');
+        }
+    }
+    catch {
+        // ignore
+    }
+    await delay(2000);
+    if (child.exitCode === null) {
+        try {
+            if (process.platform !== 'win32') {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch {
+                    child.kill('SIGKILL');
+                }
             }
-            catch (error) {
-                return { ok: false, message: error?.message ?? versionError?.message ?? 'Chromium QA install failed' };
+            else {
+                child.kill('SIGKILL');
             }
         }
+        catch {
+            // ignore
+        }
+    }
+};
+const truncateText = (value, maxLength) => {
+    if (!value)
+        return '';
+    if (value.length <= maxLength)
+        return value;
+    return `${value.slice(0, maxLength)}\n[truncated ${value.length - maxLength} chars]`;
+};
+const formatBrowserStdout = (result, url) => {
+    const displayUrl = result.finalUrl ?? url ?? DEFAULT_BROWSER_URL;
+    const lines = [
+        'MCODA_BROWSER_QA_RESULT',
+        `status: ${result.status ?? 'unknown'}`,
+        `final_url: ${displayUrl}`,
+    ];
+    const text = result.innerText ?? result.textContent ?? '';
+    if (text.trim()) {
+        lines.push('');
+        lines.push('inner_text:');
+        lines.push(truncateText(text.trim(), 8000));
+    }
+    return lines.join('\n');
+};
+export class ChromiumQaAdapter {
+    async ensureInstalled(profile, ctx) {
+        if (shouldSkipInstall(ctx))
+            return { ok: true, details: { skipped: true } };
+        const chromiumPath = await resolveDocdexChromiumBinary();
+        if (!chromiumPath) {
+            return { ok: false, message: DOCDEX_CHROMIUM_MISSING_MESSAGE };
+        }
+        return { ok: true, details: { chromiumPath } };
     }
     async persistLogs(ctx, stdout, stderr) {
         const artifacts = [];
@@ -44,42 +1404,274 @@ export class ChromiumQaAdapter {
         artifacts.push(path.relative(ctx.workspaceRoot, outPath), path.relative(ctx.workspaceRoot, errPath));
         return artifacts;
     }
+    async persistBrowserArtifacts(ctx, result) {
+        const artifacts = [];
+        if (!ctx.artifactDir)
+            return artifacts;
+        await fs.mkdir(ctx.artifactDir, { recursive: true });
+        const htmlPath = path.join(ctx.artifactDir, 'browser.html');
+        await fs.writeFile(htmlPath, result.html ?? '', 'utf8');
+        artifacts.push(path.relative(ctx.workspaceRoot, htmlPath));
+        if (result.innerText) {
+            const innerPath = path.join(ctx.artifactDir, 'browser.inner_text.txt');
+            await fs.writeFile(innerPath, result.innerText, 'utf8');
+            artifacts.push(path.relative(ctx.workspaceRoot, innerPath));
+        }
+        if (result.textContent) {
+            const textPath = path.join(ctx.artifactDir, 'browser.text_content.txt');
+            await fs.writeFile(textPath, result.textContent, 'utf8');
+            artifacts.push(path.relative(ctx.workspaceRoot, textPath));
+        }
+        const metaPath = path.join(ctx.artifactDir, 'browser.json');
+        await fs.writeFile(metaPath, JSON.stringify({
+            status: result.status ?? null,
+            final_url: result.finalUrl ?? null,
+        }, null, 2), 'utf8');
+        artifacts.push(path.relative(ctx.workspaceRoot, metaPath));
+        return artifacts;
+    }
     async invoke(profile, ctx) {
-        const command = ctx.testCommandOverride ?? profile.test_command ?? 'npx playwright test --reporter=list';
         const startedAt = new Date().toISOString();
-        const cwd = this.resolveCwd(profile, ctx);
-        try {
-            const { stdout, stderr } = await exec(command, {
-                cwd,
-                env: { ...process.env, ...profile.env, ...ctx.env },
-            });
+        const actions = (ctx.browserActions ?? []).filter(Boolean);
+        if (actions.length) {
+            return await this.runBrowserActions(actions, ctx, startedAt);
+        }
+        const url = resolveBrowserTarget(profile, ctx);
+        return await this.runBrowser(url, ctx, startedAt);
+    }
+    async runBrowserActions(actions, ctx, startedAt) {
+        const chromiumPath = await resolveDocdexChromiumBinary();
+        if (!chromiumPath) {
             const finishedAt = new Date().toISOString();
-            const artifacts = await this.persistLogs(ctx, stdout, stderr);
             return {
-                outcome: 'pass',
-                exitCode: 0,
-                stdout,
-                stderr,
+                outcome: 'infra_issue',
+                exitCode: null,
+                stdout: '',
+                stderr: DOCDEX_CHROMIUM_MISSING_MESSAGE,
+                artifacts: [],
+                startedAt,
+                finishedAt,
+            };
+        }
+        const headless = resolveHeadless(ctx);
+        const timeoutMs = resolveTimeoutMs(ctx);
+        const userAgent = resolveUserAgent(ctx);
+        const userDataDir = await resolveUserDataDir(ctx);
+        const sessionConfig = {
+            chromeBinary: chromiumPath,
+            headless,
+            userAgent,
+            userDataDir,
+        };
+        let actionOutcome;
+        let actionError;
+        let infraError;
+        let actionResults = [];
+        let snapshots = [];
+        let finalDom;
+        const executeOnce = async () => {
+            const instance = await chromeManager.getOrLaunch(sessionConfig, ctx.env);
+            const target = await createCdpTarget(instance.getDebugPort(), CHROME_STARTUP_TIMEOUT_MS);
+            const client = await CdpClient.connect(target.wsUrl);
+            try {
+                return await runBrowserActionsWithClient(client, actions, ctx.browserBaseUrl, timeoutMs);
+            }
+            finally {
+                client.close();
+                if (target.targetId) {
+                    try {
+                        await closeCdpTarget(instance.getDebugPort(), target.targetId);
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        };
+        try {
+            const release = await chromeFetchSemaphore.acquire();
+            try {
+                const result = await executeOnce();
+                actionOutcome = result.outcome;
+                actionError = result.errorMessage;
+                actionResults = result.results;
+                snapshots = result.snapshots;
+                finalDom = result.finalDom;
+            }
+            finally {
+                release();
+            }
+        }
+        catch (err) {
+            infraError = err instanceof Error ? err.message : String(err);
+        }
+        const finishedAt = new Date().toISOString();
+        if (infraError) {
+            const artifacts = await this.persistLogs(ctx, '', infraError);
+            return {
+                outcome: 'infra_issue',
+                exitCode: null,
+                stdout: '',
+                stderr: infraError,
                 artifacts,
                 startedAt,
                 finishedAt,
             };
         }
-        catch (error) {
-            const stdout = error?.stdout ?? '';
-            const stderr = error?.stderr ?? String(error);
-            const exitCode = typeof error?.code === 'number' ? error.code : null;
+        const lines = ['MCODA_BROWSER_QA_ACTIONS'];
+        for (const result of actionResults) {
+            const status = result.ok ? 'ok' : 'fail';
+            lines.push(`${result.index}. ${result.type} ${status}${result.message ? ` - ${result.message}` : ''}`);
+        }
+        const stdout = lines.join('\n');
+        const stderr = actionOutcome === 'fail' ? actionError ?? 'Browser action failed' : '';
+        const artifacts = await this.persistLogs(ctx, stdout, stderr);
+        if (finalDom) {
+            const browserArtifacts = await this.persistBrowserArtifacts(ctx, finalDom);
+            artifacts.push(...browserArtifacts);
+        }
+        if (ctx.artifactDir) {
+            await fs.mkdir(ctx.artifactDir, { recursive: true });
+            const actionsPath = path.join(ctx.artifactDir, 'browser-actions.json');
+            await fs.writeFile(actionsPath, JSON.stringify({ actions: actionResults, snapshots }, null, 2), 'utf8');
+            artifacts.push(path.relative(ctx.workspaceRoot, actionsPath));
+            if (snapshots.length) {
+                const snapDir = path.join(ctx.artifactDir, 'browser-snapshots');
+                await fs.mkdir(snapDir, { recursive: true });
+                for (const snapshot of snapshots) {
+                    const safeName = snapshot.name.replace(/[^a-zA-Z0-9_-]+/g, '-');
+                    const baseName = `${snapshot.index}-${safeName}`;
+                    const htmlPath = path.join(snapDir, `${baseName}.html`);
+                    await fs.writeFile(htmlPath, snapshot.html ?? '', 'utf8');
+                    artifacts.push(path.relative(ctx.workspaceRoot, htmlPath));
+                    if (snapshot.innerText) {
+                        const innerPath = path.join(snapDir, `${baseName}.inner_text.txt`);
+                        await fs.writeFile(innerPath, snapshot.innerText, 'utf8');
+                        artifacts.push(path.relative(ctx.workspaceRoot, innerPath));
+                    }
+                    if (snapshot.textContent) {
+                        const textPath = path.join(snapDir, `${baseName}.text_content.txt`);
+                        await fs.writeFile(textPath, snapshot.textContent, 'utf8');
+                        artifacts.push(path.relative(ctx.workspaceRoot, textPath));
+                    }
+                }
+            }
+        }
+        return {
+            outcome: actionOutcome === 'fail' ? 'fail' : 'pass',
+            exitCode: actionOutcome === 'fail' ? 1 : 0,
+            stdout,
+            stderr: stderr || '',
+            artifacts,
+            startedAt,
+            finishedAt,
+        };
+    }
+    async runBrowser(url, ctx, startedAt) {
+        const chromiumPath = await resolveDocdexChromiumBinary();
+        if (!chromiumPath) {
             const finishedAt = new Date().toISOString();
-            const artifacts = await this.persistLogs(ctx, stdout, stderr);
             return {
-                outcome: exitCode === null ? 'infra_issue' : exitCode === 0 ? 'pass' : 'fail',
-                exitCode,
-                stdout,
+                outcome: 'infra_issue',
+                exitCode: null,
+                stdout: '',
+                stderr: DOCDEX_CHROMIUM_MISSING_MESSAGE,
+                artifacts: [],
+                startedAt,
+                finishedAt,
+            };
+        }
+        const headless = resolveHeadless(ctx);
+        const timeoutMs = resolveTimeoutMs(ctx);
+        const userAgent = resolveUserAgent(ctx);
+        const userDataDir = await resolveUserDataDir(ctx);
+        const sessionConfig = {
+            chromeBinary: chromiumPath,
+            headless,
+            userAgent,
+            userDataDir,
+        };
+        let browserResult;
+        let cdpError;
+        try {
+            const release = await chromeFetchSemaphore.acquire();
+            try {
+                const instance = await chromeManager.getOrLaunch(sessionConfig, ctx.env);
+                try {
+                    browserResult = await instance.fetchDom(url, timeoutMs);
+                }
+                catch (err) {
+                    cdpError = err instanceof Error ? err.message : String(err);
+                    if (await chromeManager.resetIfUnhealthy(instance)) {
+                        try {
+                            const nextInstance = await chromeManager.getOrLaunch(sessionConfig, ctx.env);
+                            browserResult = await nextInstance.fetchDom(url, timeoutMs);
+                            cdpError = undefined;
+                        }
+                        catch (err2) {
+                            cdpError = err2 instanceof Error ? err2.message : String(err2);
+                        }
+                    }
+                }
+            }
+            finally {
+                release();
+            }
+        }
+        catch (err) {
+            cdpError = err instanceof Error ? err.message : String(err);
+        }
+        if (!browserResult) {
+            try {
+                const dump = await runDumpDom(chromiumPath, url, headless, userAgent, userDataDir.path, timeoutMs);
+                if (dump.html.trim()) {
+                    browserResult = { html: dump.html, finalUrl: url ?? DEFAULT_BROWSER_URL };
+                    if (!cdpError && dump.stderr)
+                        cdpError = dump.stderr;
+                }
+                else if (!cdpError) {
+                    cdpError = dump.timedOut
+                        ? `Timed out after ${timeoutMs}ms while loading ${url ?? DEFAULT_BROWSER_URL}.`
+                        : 'chrome dump-dom returned empty HTML';
+                }
+            }
+            catch (err) {
+                if (!cdpError)
+                    cdpError = err instanceof Error ? err.message : String(err);
+            }
+        }
+        const finishedAt = new Date().toISOString();
+        if (!browserResult) {
+            const stderr = cdpError || 'Chromium QA failed to load page.';
+            const artifacts = await this.persistLogs(ctx, '', stderr);
+            return {
+                outcome: 'infra_issue',
+                exitCode: null,
+                stdout: '',
                 stderr,
                 artifacts,
                 startedAt,
                 finishedAt,
             };
         }
+        const stdout = formatBrowserStdout(browserResult, url);
+        const stderr = cdpError ?? '';
+        const artifacts = await this.persistLogs(ctx, stdout, stderr || '');
+        const browserArtifacts = await this.persistBrowserArtifacts(ctx, browserResult);
+        artifacts.push(...browserArtifacts);
+        return {
+            outcome: 'pass',
+            exitCode: 0,
+            stdout,
+            stderr: stderr || '',
+            artifacts,
+            startedAt,
+            finishedAt,
+        };
     }
 }
+export const __testing = {
+    resolveActionUrl,
+    resolveActionTimeoutMs,
+    runBrowserActionsWithClient,
+};