browser-debugging-daemon 1.0.0

package/runtime/BrowserRuntime.js

@@ -0,0 +1,1706 @@
+import path from "path";
+import fs from "fs";
+import { spawn, spawnSync } from "child_process";
+import { chromium } from "playwright";
+import {
+    clearOverlays,
+    collectInteractableElements,
+    collectPageContent,
+    getSelectAllShortcut,
+    loadStorageState,
+    refreshTarget,
+    saveBrowserState,
+    writeBase64Files,
+} from "../shared.js";
+import { ArtifactStore } from "./ArtifactStore.js";
+
+const SUPPORTED_BROWSER_SOURCES = new Set(["auto", "managed", "attached"]);
+const DEFAULT_TEXT_AUDIT_SELECTORS = [
+    "button",
+    "a",
+    "label",
+    "input[type='button']",
+    "input[type='submit']",
+    "input[type='reset']",
+    "[role='button']",
+    "[role='link']",
+    "[data-testid]",
+].join(", ");
+const ATTACHED_SCREENCAST_FPS = 10;
+const ATTACHED_SCREENCAST_MAX_PENDING_WRITES = Number.parseInt(process.env.BROWSER_ATTACHED_SCREENCAST_MAX_PENDING_WRITES, 10) || 80;
+
+function trimLogBuffer(buffer, limit = 200) {
+    if (buffer.length <= limit) return buffer;
+    return buffer.slice(buffer.length - limit);
+}
+
+function normalizeBrowserSource(source) {
+    const candidate = typeof source === "string" ? source.trim().toLowerCase() : "";
+    if (SUPPORTED_BROWSER_SOURCES.has(candidate)) {
+        return candidate;
+    }
+    return "auto";
+}
+
+export class BrowserRuntime {
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+        this.storageStatePath = path.join(baseDir, "storage_state.json");
+        this.artifacts = new ArtifactStore(baseDir);
+        this.lastSessionSummary = null;
+        this.requestedSource = "auto";
+        this.sessionSource = "managed";
+        this.cdpEndpoint = process.env.CHROME_REMOTE_DEBUG_URL || "http://127.0.0.1:9222";
+        this.autoFallbackReason = null;
+        this.browserMode = "stopped";
+        this.manualControlActive = false;
+        this.traceActive = false;
+        this.attachedVideoCapability = false;
+        this.attachedScreencast = null;
+        this.ffmpegAvailable = null;
+        this.resetRuntimeState();
+    }
+
+    resetRuntimeState() {
+        this.browser = null;
+        this.context = null;
+        this.page = null;
+        this.interactableElements = [];
+        this.consoleMessages = [];
+        this.networkEvents = [];
+        this.pageErrors = [];
+        this.requestedSource = "auto";
+        this.sessionSource = "managed";
+        this.autoFallbackReason = null;
+        this.browserMode = "stopped";
+        this.manualControlActive = false;
+        this.traceActive = false;
+        this.attachedVideoCapability = false;
+        this.attachedScreencast = null;
+    }
+
+    async ensureStarted(options = {}) {
+        if (!this.browser) {
+            await this.start(options);
+        }
+    }
+
+    async start(options = {}) {
+        if (this.browser) {
+            return {
+                alreadyRunning: true,
+                artifacts: this.artifacts.getSummary(),
+                requestedSource: this.requestedSource,
+                browserMode: this.browserMode,
+                sessionSource: this.sessionSource,
+                autoFallbackReason: this.autoFallbackReason,
+            };
+        }
+
+        this.artifacts.startSession();
+        this.requestedSource = normalizeBrowserSource(options.source || "auto");
+        this.sessionSource = this.requestedSource;
+        this.cdpEndpoint = options.cdpEndpoint || this.cdpEndpoint;
+        this.autoFallbackReason = null;
+
+        if (this.requestedSource === "attached") {
+            await this.attachBrowserSession({
+                endpoint: this.cdpEndpoint,
+                eventType: "session_attached",
+            });
+        } else if (this.requestedSource === "auto") {
+            try {
+                await this.attachBrowserSession({
+                    endpoint: this.cdpEndpoint,
+                    eventType: "session_auto_attached",
+                });
+            } catch (error) {
+                this.autoFallbackReason = error.message;
+                await this.cleanupBrokenSession();
+                this.sessionSource = "managed";
+                this.artifacts.appendEvent("session_auto_attach_failed", {
+                    requestedSource: this.requestedSource,
+                    endpoint: this.cdpEndpoint,
+                    error: this.autoFallbackReason,
+                });
+                await this.launchBrowserSession({
+                    headless: options.headless ?? true,
+                    eventType: "session_auto_fallback_started",
+                });
+            }
+        } else {
+            this.sessionSource = "managed";
+            await this.launchBrowserSession({
+                headless: options.headless ?? true,
+                eventType: "session_started",
+            });
+        }
+
+        return {
+            alreadyRunning: false,
+            artifacts: this.artifacts.getSummary(),
+            requestedSource: this.requestedSource,
+            browserMode: this.browserMode,
+            sessionSource: this.sessionSource,
+            autoFallbackReason: this.autoFallbackReason,
+        };
+    }
+
+    async cleanupBrokenSession() {
+        await this.stopAttachedScreencast({
+            reason: "cleanup-broken-session",
+            persist: false,
+        }).catch(() => {});
+        if (this.browser) {
+            await this.browser.close().catch(() => {});
+        }
+        this.browser = null;
+        this.context = null;
+        this.page = null;
+        this.interactableElements = [];
+        this.browserMode = "stopped";
+        this.manualControlActive = false;
+        this.traceActive = false;
+        this.attachedVideoCapability = false;
+    }
+
+    async launchBrowserSession({ headless, navigateToUrl = null, eventType = "session_started" }) {
+        this.browser = await chromium.launch({
+            headless,
+            args: ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"],
+        });
+
+        const contextOptions = {
+            viewport: { width: 1280, height: 800 },
+            userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/121.0.0.0 Safari/537.36",
+            recordVideo: {
+                dir: this.artifacts.getVideoDir(),
+                size: { width: 1280, height: 800 },
+            },
+        };
+
+        const storageState = await loadStorageState(this.storageStatePath);
+        if (storageState) {
+            contextOptions.storageState = storageState;
+        }
+
+        this.context = await this.browser.newContext(contextOptions);
+        await this.context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+        this.traceActive = true;
+        this.page = await this.context.newPage();
+        this.attachPageObservers();
+        this.browserMode = headless ? "headless" : "headful";
+        this.manualControlActive = !headless;
+        this.interactableElements = [];
+
+        if (navigateToUrl && !navigateToUrl.startsWith("about:blank")) {
+            await this.page.goto(navigateToUrl, { waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => {});
+            await this.smartWait();
+        }
+
+        this.artifacts.appendEvent(eventType, {
+            reusedStorageState: Boolean(storageState),
+            requestedSource: this.requestedSource,
+            sessionSource: this.sessionSource,
+            browserMode: this.browserMode,
+            resumedUrl: navigateToUrl,
+        });
+    }
+
+    async attachBrowserSession({ endpoint, eventType = "session_attached" }) {
+        this.browser = await chromium.connectOverCDP(endpoint);
+        this.sessionSource = "attached";
+        this.browserMode = "attached";
+        this.manualControlActive = true;
+        this.interactableElements = [];
+
+        const contexts = this.browser.contexts();
+        this.context = contexts[0] || null;
+        if (!this.context) {
+            throw new Error(`No attachable browser context found at ${endpoint}. Open a Chrome tab after enabling remote debugging.`);
+        }
+
+        try {
+            await this.context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+            this.traceActive = true;
+        } catch (error) {
+            this.traceActive = false;
+            this.artifacts.appendEvent("session_trace_unavailable", {
+                sessionSource: this.sessionSource,
+                browserMode: this.browserMode,
+                error: error.message,
+            });
+        }
+
+        const pages = this.context.pages();
+        this.page = pages[0] || await this.context.newPage();
+        this.attachPageObservers();
+        await this.startAttachedScreencast();
+
+        this.artifacts.appendEvent(eventType, {
+            requestedSource: this.requestedSource,
+            sessionSource: this.sessionSource,
+            browserMode: this.browserMode,
+            endpoint,
+            attachedPageUrl: this.page.url(),
+        });
+    }
+
+    detectFfmpegAvailability() {
+        if (typeof this.ffmpegAvailable === "boolean") {
+            return this.ffmpegAvailable;
+        }
+
+        try {
+            const result = spawnSync("ffmpeg", ["-version"], { stdio: "ignore" });
+            this.ffmpegAvailable = result.status === 0;
+        } catch (error) {
+            this.ffmpegAvailable = false;
+        }
+
+        return this.ffmpegAvailable;
+    }
+
+    async encodeScreencastFramesToWebm({ inputPattern, outputPath, fps }) {
+        return new Promise((resolve, reject) => {
+            const args = [
+                "-y",
+                "-framerate",
+                String(fps),
+                "-i",
+                inputPattern,
+                "-c:v",
+                "libvpx-vp9",
+                "-pix_fmt",
+                "yuv420p",
+                outputPath,
+            ];
+
+            const child = spawn("ffmpeg", args, {
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+
+            let stderr = "";
+            child.stderr.on("data", (chunk) => {
+                stderr += chunk.toString();
+                if (stderr.length > 4000) {
+                    stderr = stderr.slice(-4000);
+                }
+            });
+
+            child.on("error", (error) => {
+                reject(new Error(`Failed to start ffmpeg: ${error.message}`));
+            });
+
+            child.on("close", (code) => {
+                if (code === 0) {
+                    resolve(outputPath);
+                    return;
+                }
+                reject(new Error(`ffmpeg exited with code ${code}: ${stderr.trim()}`));
+            });
+        });
+    }
+
+    async startAttachedScreencast() {
+        if (this.sessionSource !== "attached" || !this.context || !this.page) {
+            return;
+        }
+
+        if (this.attachedScreencast?.active) {
+            return;
+        }
+
+        if (!this.detectFfmpegAvailability()) {
+            this.attachedVideoCapability = false;
+            this.artifacts.appendEvent("session_attached_video_unavailable", {
+                reason: "ffmpeg_not_found",
+                hint: "Install ffmpeg to enable attached-mode video replay artifacts.",
+            });
+            return;
+        }
+
+        const framesDir = this.artifacts.getAttachedFramesDir("attached-screencast-frames");
+        const inputPattern = path.join(framesDir, "frame_%06d.jpg");
+
+        let cdpSession = null;
+        let onFrame = null;
+        try {
+            cdpSession = await this.context.newCDPSession(this.page);
+            const recorder = {
+                active: true,
+                cdpSession,
+                framesDir,
+                inputPattern,
+                frameCount: 0,
+                receivedFrames: 0,
+                droppedFrames: 0,
+                startedAt: Date.now(),
+                maxPendingWrites: ATTACHED_SCREENCAST_MAX_PENDING_WRITES,
+                pendingFrameWrites: new Set(),
+                onFrame: null,
+            };
+
+            recorder.onFrame = async (payload) => {
+                if (!recorder.active) return;
+                recorder.receivedFrames += 1;
+
+                if (recorder.pendingFrameWrites.size >= recorder.maxPendingWrites) {
+                    recorder.droppedFrames += 1;
+                } else {
+                    recorder.frameCount += 1;
+                    const frameName = `frame_${String(recorder.frameCount).padStart(6, "0")}.jpg`;
+                    const framePath = path.join(recorder.framesDir, frameName);
+                    const writePromise = fs.promises
+                        .writeFile(framePath, payload.data, "base64")
+                        .catch(() => {
+                            recorder.droppedFrames += 1;
+                        })
+                        .finally(() => {
+                            recorder.pendingFrameWrites.delete(writePromise);
+                        });
+                    recorder.pendingFrameWrites.add(writePromise);
+                }
+
+                try {
+                    await recorder.cdpSession.send("Page.screencastFrameAck", { sessionId: payload.sessionId });
+                } catch (error) {
+                    // Best effort; ack failures are surfaced during stop.
+                }
+            };
+            onFrame = recorder.onFrame;
+
+            cdpSession.on("Page.screencastFrame", recorder.onFrame);
+            await cdpSession.send("Page.startScreencast", {
+                format: "jpeg",
+                quality: 75,
+                maxWidth: 1280,
+                maxHeight: 800,
+                everyNthFrame: 1,
+            });
+            this.attachedScreencast = recorder;
+            this.attachedVideoCapability = true;
+            this.artifacts.appendEvent("session_attached_video_started", {
+                framesDir,
+                fps: ATTACHED_SCREENCAST_FPS,
+                maxPendingWrites: recorder.maxPendingWrites,
+            });
+        } catch (error) {
+            if (cdpSession && onFrame) {
+                cdpSession.removeListener("Page.screencastFrame", onFrame);
+            }
+            if (cdpSession) {
+                await cdpSession.detach().catch(() => {});
+            }
+            this.attachedVideoCapability = false;
+            this.artifacts.appendEvent("session_attached_video_unavailable", {
+                reason: "cdp_start_failed",
+                error: error.message,
+            });
+            fs.rmSync(framesDir, { recursive: true, force: true });
+        }
+    }
+
+    async stopAttachedScreencast({ reason = "session-stop", persist = true } = {}) {
+        const recorder = this.attachedScreencast;
+        if (!recorder) {
+            return null;
+        }
+
+        this.attachedScreencast = null;
+        recorder.active = false;
+
+        try {
+            await recorder.cdpSession.send("Page.stopScreencast");
+        } catch (error) {
+            // Ignore stop errors; detach still runs.
+        }
+
+        recorder.cdpSession.removeListener("Page.screencastFrame", recorder.onFrame);
+        await recorder.cdpSession.detach().catch(() => {});
+        if (recorder.pendingFrameWrites.size > 0) {
+            await Promise.allSettled(Array.from(recorder.pendingFrameWrites));
+        }
+
+        if (!persist) {
+            fs.rmSync(recorder.framesDir, { recursive: true, force: true });
+            return null;
+        }
+
+        if (recorder.frameCount < 2) {
+            this.artifacts.appendEvent("session_attached_video_skipped", {
+                reason: "insufficient_frames",
+                frameCount: recorder.frameCount,
+                receivedFrames: recorder.receivedFrames,
+                droppedFrames: recorder.droppedFrames,
+            });
+            fs.rmSync(recorder.framesDir, { recursive: true, force: true });
+            return null;
+        }
+
+        const outputPath = this.artifacts.getVideoPath(`attached-${reason}`);
+        try {
+            await this.encodeScreencastFramesToWebm({
+                inputPattern: recorder.inputPattern,
+                outputPath,
+                fps: ATTACHED_SCREENCAST_FPS,
+            });
+        } catch (error) {
+            this.attachedVideoCapability = false;
+            this.artifacts.appendEvent("session_attached_video_failed", {
+                error: error.message,
+                frameCount: recorder.frameCount,
+                receivedFrames: recorder.receivedFrames,
+                droppedFrames: recorder.droppedFrames,
+                framesDir: recorder.framesDir,
+            });
+            return null;
+        }
+
+        this.artifacts.appendEvent("session_attached_video_saved", {
+            videoPath: outputPath,
+            frameCount: recorder.frameCount,
+            receivedFrames: recorder.receivedFrames,
+            droppedFrames: recorder.droppedFrames,
+            durationMs: Math.max(0, Date.now() - recorder.startedAt),
+            fps: ATTACHED_SCREENCAST_FPS,
+        });
+        fs.rmSync(recorder.framesDir, { recursive: true, force: true });
+        return outputPath;
+    }
+
+    async finalizeTraceSegment(label) {
+        if (!this.context || !this.traceActive) {
+            return null;
+        }
+
+        const tracePath = this.artifacts.getTracePath(label);
+        await this.context.tracing.stop({ path: tracePath });
+        this.traceActive = false;
+        return tracePath;
+    }
+
+    async switchBrowserMode(targetMode, reason = "mode_switch") {
+        await this.ensureStarted();
+        if (this.sessionSource === "attached") {
+            return {
+                changed: false,
+                browserMode: this.browserMode,
+                sessionSource: this.sessionSource,
+                artifacts: this.artifacts.getSummary(),
+            };
+        }
+        if (this.browserMode === targetMode) {
+            return {
+                changed: false,
+                browserMode: this.browserMode,
+                sessionSource: this.sessionSource,
+                artifacts: this.artifacts.getSummary(),
+            };
+        }
+
+        const resumeUrl = this.page?.url?.() || null;
+        const previousMode = this.browserMode;
+        this.artifacts.appendEvent("session_switch_requested", {
+            from: previousMode,
+            to: targetMode,
+            reason,
+            resumeUrl,
+        });
+
+        await saveBrowserState(this.context, this.storageStatePath);
+        await this.finalizeTraceSegment(`${reason}-${previousMode}`);
+        await this.browser.close();
+        this.browser = null;
+        this.context = null;
+        this.page = null;
+        this.interactableElements = [];
+
+        try {
+            await this.launchBrowserSession({
+                headless: targetMode !== "headful",
+                navigateToUrl: resumeUrl,
+                eventType: "session_switched",
+            });
+        } catch (error) {
+            this.artifacts.appendEvent("session_switch_failed", {
+                from: previousMode,
+                to: targetMode,
+                reason,
+                error: error.message,
+            });
+
+            try {
+                await this.launchBrowserSession({
+                    headless: previousMode !== "headful",
+                    navigateToUrl: resumeUrl,
+                    eventType: "session_switch_recovered",
+                });
+            } catch (recoveryError) {
+                this.artifacts.appendEvent("session_switch_recovery_failed", {
+                    from: previousMode,
+                    to: targetMode,
+                    reason,
+                    error: recoveryError.message,
+                });
+                throw new Error(`Failed to switch browser mode to ${targetMode}: ${error.message}. Recovery also failed: ${recoveryError.message}`);
+            }
+
+            throw new Error(`Failed to switch browser mode to ${targetMode}: ${error.message}. Restored ${previousMode} mode instead.`);
+        }
+
+        this.artifacts.appendEvent("session_switch_completed", {
+            from: previousMode,
+            to: this.browserMode,
+            reason,
+            resumedUrl: this.page?.url?.() || resumeUrl,
+        });
+
+        return {
+            changed: true,
+            browserMode: this.browserMode,
+            sessionSource: this.sessionSource,
+            resumedUrl: this.page?.url?.() || resumeUrl,
+            artifacts: this.artifacts.getSummary(),
+        };
+    }
+
+    async enterManualControl() {
+        return this.switchBrowserMode("headful", "manual_control");
+    }
+
+    async exitManualControl() {
+        return this.switchBrowserMode("headless", "resume_automation");
+    }
+
+    attachPageObservers() {
+        this.page.on("console", (msg) => {
+            const location = msg.location();
+            const entry = {
+                type: msg.type(),
+                text: msg.text(),
+                location: location?.url ? {
+                    url: location.url,
+                    lineNumber: location.lineNumber,
+                    columnNumber: location.columnNumber,
+                } : null,
+            };
+            this.consoleMessages = trimLogBuffer([...this.consoleMessages, entry]);
+        });
+
+        this.page.on("pageerror", (error) => {
+            const entry = {
+                message: error.message,
+                stack: error.stack || null,
+            };
+            this.pageErrors = trimLogBuffer([...this.pageErrors, entry]);
+        });
+
+        this.page.on("requestfinished", async (request) => {
+            const response = await request.response().catch(() => null);
+            const entry = {
+                type: "requestfinished",
+                url: request.url(),
+                method: request.method(),
+                resourceType: request.resourceType(),
+                status: response?.status() ?? null,
+                ok: response?.ok() ?? null,
+            };
+
+            // Capture request body for non-GET requests
+            if (request.method() !== "GET") {
+                const postData = request.postData();
+                if (postData) {
+                    entry.requestBody = postData.length > 4096
+                        ? postData.slice(0, 4096) + `... (${postData.length} bytes total)`
+                        : postData;
+                }
+            }
+
+            // Capture response body for relevant resource types
+            const captureTypes = new Set(["document", "xhr", "fetch"]);
+            if (response && captureTypes.has(request.resourceType())) {
+                try {
+                    const body = await response.text().catch(() => null);
+                    if (body !== null) {
+                        entry.responseBody = body.length > 4096
+                            ? body.slice(0, 4096) + `... (${body.length} bytes total)`
+                            : body;
+                        entry.responseBodyTruncated = body.length > 4096;
+                    }
+                } catch (_) {
+                    // Body not available for some responses (e.g. redirects)
+                }
+            }
+
+            this.networkEvents = trimLogBuffer([...this.networkEvents, entry]);
+        });
+
+        this.page.on("requestfailed", (request) => {
+            const entry = {
+                type: "requestfailed",
+                url: request.url(),
+                method: request.method(),
+                resourceType: request.resourceType(),
+                failure: request.failure()?.errorText ?? "unknown",
+            };
+
+            if (request.method() !== "GET") {
+                const postData = request.postData();
+                if (postData) {
+                    entry.requestBody = postData.length > 4096
+                        ? postData.slice(0, 4096) + `... (${postData.length} bytes total)`
+                        : postData;
+                }
+            }
+
+            this.networkEvents = trimLogBuffer([...this.networkEvents, entry]);
+        });
+    }
+
+    async smartWait() {
+        if (!this.page) return;
+
+        try {
+            await this.page.waitForLoadState("networkidle", { timeout: 1500 }).catch(() => { });
+        } catch (error) {
+            // Best-effort wait for apps that keep a connection open.
+        }
+
+        await this.page.waitForTimeout(500);
+    }
+
+    async captureStepScreenshot(label, { fullPage = false } = {}) {
+        if (!this.page) return null;
+
+        const screenshotPath = this.artifacts.getStepScreenshotPath(label);
+        await this.page.screenshot({ path: screenshotPath, fullPage });
+        return screenshotPath;
+    }
+
+    async goto(url) {
+        await this.ensureStarted();
+        await this.page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });
+        await this.smartWait();
+
+        // Auto-observe: collect elements and page content so the caller gets a full picture
+        this.interactableElements = await collectInteractableElements(this.page, { drawOverlays: true });
+        const screenshotPath = this.artifacts.getCurrentViewPath();
+        await this.page.screenshot({ path: screenshotPath, fullPage: true });
+        await clearOverlays(this.page);
+
+        // Accessibility Tree
+        let accessibilityTree = null;
+        try {
+            accessibilityTree = await this.page.locator(":root").ariaSnapshot({ timeout: 5000 });
+        } catch (_) {}
+
+        const pageContent = await collectPageContent(this.page);
+        const metadata = await this.getPageMetadata(500);
+
+        this.artifacts.appendEvent("goto", {
+            url,
+            elementCount: this.interactableElements.length,
+            hasA11yTree: accessibilityTree !== null,
+            screenshotPath,
+        });
+
+        return {
+            url,
+            metadata,
+            elements: this.interactableElements,
+            accessibilityTree,
+            pageContent,
+            screenshotPath,
+        };
+    }
+
+    async observe() {
+        await this.ensureStarted();
+        this.interactableElements = await collectInteractableElements(this.page, { drawOverlays: true });
+
+        const screenshotPath = this.artifacts.getCurrentViewPath();
+        await this.page.screenshot({ path: screenshotPath, fullPage: true });
+        await clearOverlays(this.page);
+
+        // Accessibility Tree via Playwright's ariaSnapshot (YAML string)
+        let accessibilityTree = null;
+        try {
+            accessibilityTree = await this.page.locator(":root").ariaSnapshot({ timeout: 5000 });
+        } catch (_) {
+            // ariaSnapshot may fail on some pages (e.g. about:blank)
+        }
+
+        const pageContent = await collectPageContent(this.page);
+        const recentErrors = this.pageErrors.filter((e) => e.message).slice(-5);
+
+        this.artifacts.appendEvent("observe", {
+            count: this.interactableElements.length,
+            hasA11yTree: accessibilityTree !== null,
+            screenshotPath,
+        });
+
+        return {
+            elements: this.interactableElements,
+            accessibilityTree,
+            pageContent,
+            recentErrors: recentErrors.length > 0 ? recentErrors : undefined,
+            screenshotPath,
+        };
+    }
+
+    async resolveTarget(id) {
+        await this.ensureStarted();
+        const target = await refreshTarget(this.page, this.interactableElements, id);
+        this.interactableElements = this.interactableElements.map((element) => element.id === id ? target : element);
+        return target;
+    }
+
+    async click(id) {
+        const target = await this.resolveTarget(id);
+        await this.page.mouse.click(target.x, target.y);
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`click-${id}`);
+        this.artifacts.appendEvent("click", { id, target, screenshotPath });
+        return { id, target, screenshotPath };
+    }
+
+    async type(id, text, { submit = false } = {}) {
+        const target = await this.resolveTarget(id);
+        await this.page.mouse.click(target.x, target.y);
+        await this.page.keyboard.press(getSelectAllShortcut());
+        await this.page.keyboard.press("Backspace");
+        await this.page.waitForTimeout(100);
+        await this.page.keyboard.type(text);
+        if (submit) {
+            await this.page.keyboard.press("Enter");
+        }
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`type-${id}`);
+        this.artifacts.appendEvent("type", { id, text, submit, target, screenshotPath });
+        return { id, target, text, submit, screenshotPath };
+    }
+
+    async hover(id) {
+        const target = await this.resolveTarget(id);
+        await this.page.mouse.move(target.x, target.y);
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`hover-${id}`);
+        this.artifacts.appendEvent("hover", { id, target, screenshotPath });
+        return { id, target, screenshotPath };
+    }
+
+    // --- New Playwright-parity methods ---
+
+    async evaluate(expression) {
+        await this.ensureStarted();
+        let result;
+        let isError = false;
+        try {
+            const fn = new Function("page", `return (async () => { ${expression} })()`);
+            result = await fn(this.page);
+        } catch (error) {
+            result = error.message || String(error);
+            isError = true;
+        }
+        const serialized = typeof result === "object" && result !== null
+            ? JSON.stringify(result, null, 2).slice(0, 8192)
+            : String(result ?? "").slice(0, 8192);
+        this.artifacts.appendEvent("evaluate", { isError, length: serialized.length });
+        return { result: serialized, isError };
+    }
+
+    async selectOption(id, values) {
+        const target = await this.resolveTarget(id);
+        // Find the <select> element at or near the SoM target
+        const selectHandle = await this.page.evaluateHandle((targetInfo) => {
+            const elements = document.querySelectorAll("select");
+            // Check if the target itself is a select at the same position
+            for (const el of elements) {
+                const rect = el.getBoundingClientRect();
+                const cx = rect.x + rect.width / 2;
+                const cy = rect.y + rect.height / 2;
+                if (Math.abs(cx - targetInfo.x) < 10 && Math.abs(cy - targetInfo.y) < 10) {
+                    return el;
+                }
+            }
+            // Fallback: closest visible select
+            for (const el of elements) {
+                const rect = el.getBoundingClientRect();
+                if (rect.width > 0 && rect.height > 0) return el;
+            }
+            return null;
+        }, { x: target.x, y: target.y });
+
+        if (!selectHandle) {
+            throw new Error(`No <select> element found near element ${id}.`);
+        }
+
+        const valueArray = Array.isArray(values) ? values : [values];
+        await selectHandle.selectOption(valueArray);
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`select-${id}`);
+        this.artifacts.appendEvent("selectOption", { id, values: valueArray, target, screenshotPath });
+        return { id, values: valueArray, target, screenshotPath };
+    }
+
+    async handleDialog({ action = "accept", promptText = "" } = {}) {
+        await this.ensureStarted();
+        // Wait for a dialog to appear (or check if one is already being handled)
+        const dialogPromise = new Promise((resolve) => {
+            const handler = async (dialog) => {
+                this.page.off("dialog", handler);
+                const info = {
+                    type: dialog.type(),
+                    message: dialog.message(),
+                    defaultValue: dialog.defaultValue(),
+                };
+                if (action === "dismiss") {
+                    await dialog.dismiss();
+                } else {
+                    await dialog.accept(promptText || undefined);
+                }
+                resolve(info);
+            };
+            this.page.on("dialog", handler);
+            // Timeout: if no dialog appears within 3s, remove handler and return null
+            setTimeout(() => {
+                this.page.off("dialog", handler);
+                resolve(null);
+            }, 3000);
+        });
+
+        const dialogInfo = await dialogPromise;
+        if (!dialogInfo) {
+            return { handled: false, message: "No dialog appeared within 3 seconds." };
+        }
+
+        const screenshotPath = await this.captureStepScreenshot(`dialog-${action}`);
+        this.artifacts.appendEvent("handleDialog", { action, dialogInfo, screenshotPath });
+        return { handled: true, action, dialogInfo, screenshotPath };
+    }
+
+    async goBack() {
+        await this.ensureStarted();
+        await this.page.goBack({ waitUntil: "domcontentloaded", timeout: 15000 });
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot("goback");
+        this.artifacts.appendEvent("goBack", { url: this.page.url(), screenshotPath });
+        return { url: this.page.url(), screenshotPath };
+    }
+
+    async tabAction(action, { index = null, url = null } = {}) {
+        await this.ensureStarted();
+
+        if (action === "list") {
+            const pages = this.context.pages();
+            const currentPageIndex = pages.indexOf(this.page);
+            const tabs = [];
+            for (let i = 0; i < pages.length; i++) {
+                const p = pages[i];
+                const title = await p.title().catch(() => "");
+                tabs.push({ index: i, url: p.url(), title, active: i === currentPageIndex });
+            }
+            return { tabs };
+        }
+
+        if (action === "new") {
+            const newPage = await this.context.newPage();
+            if (url) {
+                await newPage.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => {});
+            }
+            // Switch to new page
+            this.page.off("console", this._consoleHandler);
+            this.page.off("pageerror", this._pageErrorHandler);
+            this.page.off("requestfinished", this._requestFinishedHandler);
+            this.page.off("requestfailed", this._requestFailedHandler);
+            this.page = newPage;
+            this.attachPageObservers();
+            this.interactableElements = [];
+            const screenshotPath = await this.captureStepScreenshot("tab-new");
+            return { url: this.page.url(), index: this.context.pages().length - 1, screenshotPath };
+        }
+
+        if (action === "close") {
+            const pages = this.context.pages();
+            const targetIndex = index != null ? index : pages.indexOf(this.page);
+            const targetPage = pages[targetIndex];
+            if (!targetPage) {
+                throw new Error(`Tab index ${targetIndex} not found.`);
+            }
+            await targetPage.close();
+
+            // If we closed the active tab, switch to the last remaining
+            if (targetPage === this.page) {
+                const remaining = this.context.pages();
+                if (remaining.length > 0) {
+                    this.page = remaining[remaining.length - 1];
+                    this.attachPageObservers();
+                } else {
+                    this.page = null;
+                }
+            }
+            this.interactableElements = [];
+            return { closed: targetIndex, remaining: this.context.pages().length };
+        }
+
+        if (action === "select") {
+            const pages = this.context.pages();
+            const targetIndex = index != null ? index : pages.length - 1;
+            const targetPage = pages[targetIndex];
+            if (!targetPage) {
+                throw new Error(`Tab index ${targetIndex} not found.`);
+            }
+            if (targetPage === this.page) {
+                return { active: targetIndex, url: this.page.url() };
+            }
+            this.page = targetPage;
+            this.attachPageObservers();
+            this.interactableElements = [];
+            const screenshotPath = await this.captureStepScreenshot(`tab-select-${targetIndex}`);
+            return { active: targetIndex, url: this.page.url(), screenshotPath };
+        }
+
+        throw new Error(`Unknown tab action: ${action}. Use: list, new, close, select.`);
+    }
+
+    async keypress(key) {
+        await this.ensureStarted();
+        await this.page.keyboard.press(key);
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`keypress-${key}`);
+        this.artifacts.appendEvent("keypress", { key, screenshotPath });
+        return { key, screenshotPath };
+    }
+
+    async scroll(direction) {
+        await this.ensureStarted();
+        await this.page.evaluate((dir) => {
+            const h = window.innerHeight;
+            if (dir === "down") window.scrollBy({ top: h * 0.8, behavior: "smooth" });
+            else if (dir === "up") window.scrollBy({ top: -h * 0.8, behavior: "smooth" });
+            else if (dir === "top") window.scrollTo({ top: 0, behavior: "smooth" });
+            else if (dir === "bottom") window.scrollTo({ top: document.body.scrollHeight, behavior: "smooth" });
+        }, direction);
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`scroll-${direction}`);
+        this.artifacts.appendEvent("scroll", { direction, screenshotPath });
+        return { direction, screenshotPath };
+    }
+
+    async waitFor({ text, textGone, selector, timeout = 30000 } = {}) {
+        await this.ensureStarted();
+
+        const conditions = [];
+        if (text) conditions.push("text");
+        if (textGone) conditions.push("textGone");
+        if (selector) conditions.push("selector");
+        if (conditions.length === 0) {
+            throw new Error("waitFor requires at least one of: text, textGone, selector.");
+        }
+
+        const startedAt = Date.now();
+        const timeoutMs = Math.max(1000, Math.min(timeout, 300000));
+        const pollIntervalMs = 500;
+        const result = { matched: null, waitedMs: 0, condition: conditions[0] };
+
+        try {
+            if (text) {
+                await this.page.waitForFunction(
+                    (expected) => {
+                        const bodyText = document.body?.innerText || "";
+                        if (bodyText.includes(expected)) return true;
+                        const ph = "place" + "holder";
+                        const checkAttrs = [ph, "aria-label", "title", "data-testid"];
+                        for (const attr of checkAttrs) {
+                            for (const el of document.querySelectorAll(`[${attr}]`)) {
+                                const val = el.getAttribute(attr) || "";
+                                if (val.includes(expected)) return true;
+                            }
+                        }
+                        for (const el of document.querySelectorAll("input, textarea")) {
+                            const val = typeof el.value === "string" ? el.value : "";
+                            if (val.includes(expected)) return true;
+                        }
+                        return false;
+                    },
+                    text,
+                    { timeout: timeoutMs, polling: pollIntervalMs }
+                );
+                result.matched = "text";
+            }
+
+            if (textGone) {
+                await this.page.waitForFunction(
+                    (expected) => {
+                        const bodyText = document.body?.innerText || "";
+                        if (bodyText.includes(expected)) return false;
+                        const ph = "place" + "holder";
+                        const checkAttrs = [ph, "aria-label", "title", "data-testid"];
+                        for (const attr of checkAttrs) {
+                            for (const el of document.querySelectorAll(`[${attr}]`)) {
+                                const val = el.getAttribute(attr) || "";
+                                if (val.includes(expected)) return false;
+                            }
+                        }
+                        for (const el of document.querySelectorAll("input, textarea")) {
+                            const val = typeof el.value === "string" ? el.value : "";
+                            if (val.includes(expected)) return false;
+                        }
+                        return true;
+                    },
+                    textGone,
+                    { timeout: timeoutMs, polling: pollIntervalMs }
+                );
+                result.matched = "textGone";
+            }
+
+            if (selector) {
+                await this.page.waitForSelector(selector, { timeout: timeoutMs, state: "visible" });
+                result.matched = "selector";
+            }
+        } catch (error) {
+            result.matched = null;
+            result.timedOut = true;
+            result.error = error.message;
+        }
+
+        result.waitedMs = Date.now() - startedAt;
+        const screenshotPath = await this.captureStepScreenshot(`waitfor-${result.matched || "timeout"}`);
+        this.artifacts.appendEvent("waitFor", { ...result, screenshotPath });
+        return { ...result, screenshotPath };
+    }
+
+    async upload(id, { paths = [], files = [] } = {}) {
+        const target = await this.resolveTarget(id);
+        const base64Paths = files.length > 0 ? writeBase64Files(files) : [];
+        const allPaths = [...paths, ...base64Paths];
+
+        if (allPaths.length === 0) {
+            throw new Error("No files provided. Supply 'paths' (local file paths) or 'files' (base64-encoded file objects).");
+        }
+
+        for (const filePath of allPaths) {
+            if (!fs.existsSync(filePath)) {
+                throw new Error(`File not found: ${filePath}`);
+            }
+        }
+
+        // Find the file input element near the resolved target
+        const fileInput = await this.page.evaluateHandle((targetInfo) => {
+            const elements = document.querySelectorAll('input[type="file"]');
+            if (targetInfo.tag === "input" && targetInfo.type === "file") {
+                // The target itself is a file input — find it by position
+                for (const el of elements) {
+                    const rect = el.getBoundingClientRect();
+                    const cx = rect.x + rect.width / 2;
+                    const cy = rect.y + rect.height / 2;
+                    if (Math.abs(cx - targetInfo.x) < 5 && Math.abs(cy - targetInfo.y) < 5) {
+                        return el;
+                    }
+                }
+            }
+            // Fallback: find closest visible file input
+            for (const el of elements) {
+                const rect = el.getBoundingClientRect();
+                if (rect.width > 0 && rect.height > 0) return el;
+            }
+            return null;
+        }, { tag: target.tag, type: target.type, x: target.x, y: target.y });
+
+        if (!fileInput || !(await fileInput.isVisible().catch(() => false))) {
+            // Use filechooser event as fallback
+            const [chooser] = await Promise.all([
+                this.page.waitForEvent("filechooser", { timeout: 5000 }),
+                this.page.mouse.click(target.x, target.y),
+            ]);
+            await chooser.setFiles(allPaths);
+        } else {
+            await fileInput.setInputFiles(allPaths);
+        }
+
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`upload-${id}`);
+        this.artifacts.appendEvent("upload", { id, target, fileCount: allPaths.length, screenshotPath });
+        return { id, target, fileCount: allPaths.length, screenshotPath };
+    }
+
+    async drag(fromId, toId) {
+        const from = await this.resolveTarget(fromId);
+        const to = await this.resolveTarget(toId);
+
+        // Move to source, press down
+        await this.page.mouse.move(from.x, from.y);
+        await this.page.waitForTimeout(100);
+        await this.page.mouse.down();
+
+        // Stepwise movement toward target for realistic drag
+        const steps = 6;
+        for (let i = 1; i <= steps; i++) {
+            const progress = i / steps;
+            const x = from.x + (to.x - from.x) * progress;
+            const y = from.y + (to.y - from.y) * progress;
+            await this.page.mouse.move(x, y);
+            await this.page.waitForTimeout(30);
+        }
+
+        // Release on target
+        await this.page.mouse.move(to.x, to.y);
+        await this.page.mouse.up();
+
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`drag-${fromId}-to-${toId}`);
+        this.artifacts.appendEvent("drag", { fromId, toId, from, to, screenshotPath });
+        return { fromId, toId, from, to, screenshotPath };
+    }
+
+    async dragFile({ paths = [], files = [], toId } = {}) {
+        const base64Paths = files.length > 0 ? writeBase64Files(files) : [];
+        const allPaths = [...paths, ...base64Paths];
+
+        if (allPaths.length === 0) {
+            throw new Error("No files provided. Supply 'paths' (local file paths) or 'files' (base64-encoded file objects).");
+        }
+
+        for (const filePath of allPaths) {
+            if (!fs.existsSync(filePath)) {
+                throw new Error(`File not found: ${filePath}`);
+            }
+        }
+
+        const target = await this.resolveTarget(toId);
+
+        // Dispatch a synthetic drop event with files on the target element
+        const dropAccepted = await this.page.evaluate(
+            async ({ x, y, filePaths }) => {
+                const elementAtPoint = document.elementFromPoint(x, y);
+                if (!elementAtPoint) return false;
+
+                // Create a DataTransfer with the file references
+                // Note: browser cannot read local files directly, so we use a different approach
+                // We'll try the filechooser approach if the drop zone has a hidden file input
+                const dropZone = elementAtPoint.closest("[class*='drop'], [class*='upload'], [data-testid*='drop'], [role='presentation']") || elementAtPoint;
+
+                // Try to find a hidden file input within the drop zone
+                const fileInput = dropZone.querySelector('input[type="file"]') ||
+                    dropZone.closest("form")?.querySelector('input[type="file"]');
+
+                if (fileInput) {
+                    return { hasFileInput: true };
+                }
+
+                // Dispatch drag events for visual feedback
+                const dataTransfer = new DataTransfer();
+                for (const eventType of ["dragenter", "dragover", "drop"]) {
+                    const event = new DragEvent(eventType, {
+                        bubbles: true,
+                        cancelable: true,
+                        dataTransfer,
+                        clientX: x,
+                        clientY: y,
+                    });
+                    elementAtPoint.dispatchEvent(event);
+                }
+
+                return { hasFileInput: false };
+            },
+            { x: target.x, y: target.y, filePaths: allPaths }
+        );
+
+        // If a file input was found, set files on it
+        if (dropAccepted?.hasFileInput) {
+            const fileInput = await this.page.evaluateHandle(({ x, y }) => {
+                const elementAtPoint = document.elementFromPoint(x, y);
+                if (!elementAtPoint) return null;
+                const dropZone = elementAtPoint.closest("[class*='drop'], [class*='upload'], [data-testid*='drop'], [role='presentation']") || elementAtPoint;
+                return dropZone.querySelector('input[type="file"]') ||
+                    dropZone.closest("form")?.querySelector('input[type="file"]');
+            }, { x: target.x, y: target.y });
+
+            if (fileInput) {
+                await fileInput.setInputFiles(allPaths);
+            }
+        }
+
+        await this.smartWait();
+        const screenshotPath = await this.captureStepScreenshot(`dragfile-to-${toId}`);
+        this.artifacts.appendEvent("dragFile", { toId, target, fileCount: allPaths.length, screenshotPath });
+        return { toId, target, fileCount: allPaths.length, screenshotPath };
+    }
+
+    async getPageMetadata(textLimit = 1500) {
+        await this.ensureStarted();
+        const title = await this.page.title().catch(() => "");
+        const textPreview = await this.page.evaluate((limit) => {
+            const bodyText = document.body?.innerText || "";
+            return bodyText.replace(/\s+/g, " ").trim().slice(0, limit);
+        }, textLimit).catch(() => "");
+
+        return {
+            url: this.page.url(),
+            title,
+            textPreview,
+        };
+    }
+
+    async getCdpHealth(options = {}) {
+        const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(1000, options.timeoutMs) : 3000;
+        const endpoint = String(options.endpoint || this.cdpEndpoint || "").trim();
+        if (!endpoint) {
+            return {
+                ok: false,
+                endpoint: null,
+                versionUrl: null,
+                error: "CDP endpoint is empty.",
+            };
+        }
+
+        let versionUrl = endpoint;
+        if (!versionUrl.includes("/json/version")) {
+            try {
+                versionUrl = new URL("/json/version", endpoint).toString();
+            } catch (error) {
+                return {
+                    ok: false,
+                    endpoint,
+                    versionUrl: null,
+                    error: `Invalid CDP endpoint: ${error.message}`,
+                };
+            }
+        }
+
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+        try {
+            const response = await fetch(versionUrl, {
+                method: "GET",
+                signal: controller.signal,
+                headers: {
+                    Accept: "application/json",
+                },
+            });
+
+            if (!response.ok) {
+                return {
+                    ok: false,
+                    endpoint,
+                    versionUrl,
+                    status: response.status,
+                    error: `Unexpected status ${response.status}.`,
+                };
+            }
+
+            const data = await response.json();
+            return {
+                ok: true,
+                endpoint,
+                versionUrl,
+                browser: data?.Browser || null,
+                protocolVersion: data?.["Protocol-Version"] || null,
+                webSocketDebuggerUrl: data?.webSocketDebuggerUrl || null,
+                userAgent: data?.["User-Agent"] || null,
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                endpoint,
+                versionUrl,
+                error: error.name === "AbortError"
+                    ? `Timed out after ${timeoutMs}ms.`
+                    : error.message,
+            };
+        } finally {
+            clearTimeout(timeoutId);
+        }
+    }
+
+    async getCdpDiagnostics(options = {}) {
+        const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(1000, options.timeoutMs) : 3000;
+        const endpoint = String(options.endpoint || this.cdpEndpoint || "").trim();
+        const health = await this.getCdpHealth({ endpoint, timeoutMs });
+        const hints = [];
+        const warnings = [];
+
+        let targets = {
+            endpoint: endpoint || null,
+            listUrl: null,
+            count: null,
+            pageTargets: null,
+            serviceWorkerTargets: null,
+            browserTargets: null,
+            sample: [],
+            error: null,
+        };
+
+        if (!health.ok) {
+            const healthError = String(health.error || "");
+            if (health.status === 404) {
+                hints.push("CDP endpoint is reachable but /json/version returned 404. Enable remote debugging from chrome://inspect/#remote-debugging and verify the endpoint.");
+            } else if (healthError.includes("Timed out")) {
+                hints.push("CDP endpoint timed out. Ensure Chrome is running and remote debugging is enabled.");
+            } else if (healthError.toLowerCase().includes("fetch failed") || healthError.toLowerCase().includes("ecconnrefused")) {
+                hints.push("CDP endpoint refused the connection. Start Chrome remote debugging and check the host/port.");
+            } else if (healthError.toLowerCase().includes("invalid cdp endpoint")) {
+                hints.push("CDP endpoint format is invalid. Use a URL like http://127.0.0.1:9222.");
+            } else {
+                hints.push("CDP health check failed. Confirm chrome://inspect/#remote-debugging is enabled for the browser instance.");
+            }
+
+            hints.push("If you continue with browser_source=auto, the runtime will fall back to managed mode.");
+            return {
+                ok: false,
+                endpoint: endpoint || null,
+                health,
+                targets,
+                hints,
+                warnings,
+            };
+        }
+
+        try {
+            const listUrl = health.versionUrl
+                ? new URL("/json/list", health.versionUrl).toString()
+                : new URL("/json/list", endpoint).toString();
+            targets.listUrl = listUrl;
+            const response = await fetch(listUrl, {
+                method: "GET",
+                headers: {
+                    Accept: "application/json",
+                },
+            });
+
+            if (!response.ok) {
+                targets.error = `Unexpected status ${response.status} from /json/list.`;
+                warnings.push(targets.error);
+            } else {
+                const list = await response.json();
+                const typed = Array.isArray(list) ? list : [];
+                const byType = typed.reduce((acc, item) => {
+                    const type = item?.type || "unknown";
+                    acc[type] = (acc[type] || 0) + 1;
+                    return acc;
+                }, {});
+                targets.count = typed.length;
+                targets.pageTargets = byType.page || 0;
+                targets.serviceWorkerTargets = byType.service_worker || 0;
+                targets.browserTargets = byType.browser || 0;
+                targets.sample = typed.slice(0, 3).map((item) => ({
+                    type: item?.type || null,
+                    title: item?.title || null,
+                    url: item?.url || null,
+                }));
+
+                if (targets.pageTargets === 0) {
+                    warnings.push("No page targets are open in the attached profile. Open a regular Chrome tab before starting an attached run.");
+                }
+            }
+        } catch (error) {
+            targets.error = error.message;
+            warnings.push(`Could not inspect /json/list: ${error.message}`);
+        }
+
+        if (!health.webSocketDebuggerUrl) {
+            warnings.push("No webSocketDebuggerUrl was reported by /json/version. Attach may be unstable.");
+        }
+
+        if (!warnings.length) {
+            hints.push("CDP endpoint looks healthy. Attached mode should be available.");
+        } else {
+            hints.push("CDP endpoint is reachable, but diagnostics found issues that may affect attached runs.");
+            hints.push("You can still run with browser_source=auto to attach when possible and fall back to managed mode.");
+        }
+
+        return {
+            ok: warnings.length === 0,
+            endpoint: endpoint || null,
+            health,
+            targets,
+            hints,
+            warnings,
+        };
+    }
+
+    async auditTextLayout(options = {}) {
+        await this.ensureStarted();
+        const limit = Number.isFinite(options.limit) ? Math.max(1, Math.min(500, options.limit)) : 80;
+        const selectors = typeof options.selectors === "string" && options.selectors.trim()
+            ? options.selectors.trim()
+            : DEFAULT_TEXT_AUDIT_SELECTORS;
+        const overflowThreshold = Number.isFinite(options.overflowThreshold)
+            ? Math.max(0, Number(options.overflowThreshold))
+            : 1;
+
+        const audit = await this.page.evaluate(({ limit, selectors, overflowThreshold }) => {
+            function parsePx(value, fallback = 0) {
+                if (typeof value !== "string") return fallback;
+                const num = Number.parseFloat(value);
+                return Number.isFinite(num) ? num : fallback;
+            }
+
+            function toSelector(node) {
+                if (!node || node.nodeType !== Node.ELEMENT_NODE) {
+                    return "";
+                }
+
+                if (node.id) {
+                    const escaped = typeof CSS !== "undefined" && typeof CSS.escape === "function"
+                        ? CSS.escape(node.id)
+                        : node.id.replace(/[^a-zA-Z0-9_-]/g, "");
+                    return `#${escaped}`;
+                }
+
+                const parts = [];
+                let current = node;
+                while (current && current.nodeType === Node.ELEMENT_NODE && parts.length < 4) {
+                    const parent = current.parentElement;
+                    const tag = current.tagName.toLowerCase();
+                    if (!parent) {
+                        parts.unshift(tag);
+                        break;
+                    }
+                    const siblings = Array.from(parent.children).filter((child) => child.tagName === current.tagName);
+                    if (siblings.length === 1) {
+                        parts.unshift(tag);
+                    } else {
+                        const index = siblings.indexOf(current) + 1;
+                        parts.unshift(`${tag}:nth-of-type(${index})`);
+                    }
+                    current = parent;
+                }
+                return parts.join(" > ");
+            }
+
+            function toGraphemes(text) {
+                if (!text) return [];
+                if (typeof Intl !== "undefined" && typeof Intl.Segmenter === "function") {
+                    const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+                    return Array.from(segmenter.segment(text), (entry) => entry.segment);
+                }
+                return Array.from(text);
+            }
+
+            function estimateLineCount(text, maxWidth, font) {
+                if (!text) return 0;
+                if (!Number.isFinite(maxWidth) || maxWidth <= 0) return 1;
+
+                const canvas = document.createElement("canvas");
+                const context = canvas.getContext("2d");
+                if (!context) {
+                    return null;
+                }
+                context.font = font;
+
+                const paragraphs = text.split("\n");
+                let lineCount = 0;
+                for (const paragraph of paragraphs) {
+                    if (!paragraph.length) {
+                        lineCount += 1;
+                        continue;
+                    }
+                    let lineWidth = 0;
+                    let activeLine = 1;
+                    const graphemes = toGraphemes(paragraph);
+                    for (const grapheme of graphemes) {
+                        const width = context.measureText(grapheme).width;
+                        if (lineWidth + width > maxWidth && lineWidth > 0) {
+                            activeLine += 1;
+                            lineWidth = width;
+                        } else {
+                            lineWidth += width;
+                        }
+                    }
+                    lineCount += activeLine;
+                }
+                return lineCount;
+            }
+
+            const result = [];
+            const elements = Array.from(document.querySelectorAll(selectors));
+
+            for (const node of elements) {
+                if (result.length >= limit) break;
+                if (!(node instanceof HTMLElement)) continue;
+
+                const style = window.getComputedStyle(node);
+                if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") {
+                    continue;
+                }
+
+                const text = (node.innerText || node.textContent || "").trim();
+                if (!text) continue;
+
+                const lineHeight = parsePx(style.lineHeight, parsePx(style.fontSize, 16) * 1.2);
+                const font = style.font && style.font !== "normal normal normal normal 16px / normal sans-serif"
+                    ? style.font
+                    : `${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+                const paddingLeft = parsePx(style.paddingLeft, 0);
+                const paddingRight = parsePx(style.paddingRight, 0);
+                const maxTextWidth = Math.max(0, node.clientWidth - paddingLeft - paddingRight);
+                const normalizedText = style.whiteSpace.startsWith("pre")
+                    ? text
+                    : text.replace(/\s+/g, " ");
+                const estimatedLineCount = estimateLineCount(normalizedText, maxTextWidth, font);
+                const expectedHeight = Number.isFinite(estimatedLineCount) ? estimatedLineCount * lineHeight : null;
+
+                const hasActualOverflow = (node.scrollWidth - node.clientWidth > overflowThreshold)
+                    || (node.scrollHeight - node.clientHeight > overflowThreshold);
+                const hasEstimatedOverflow = Number.isFinite(expectedHeight)
+                    ? expectedHeight - node.clientHeight > overflowThreshold
+                    : false;
+
+                if (!hasActualOverflow && !hasEstimatedOverflow) {
+                    continue;
+                }
+
+                result.push({
+                    selector: toSelector(node),
+                    tag: node.tagName.toLowerCase(),
+                    text: normalizedText.slice(0, 200),
+                    whiteSpace: style.whiteSpace,
+                    font,
+                    lineHeight,
+                    maxTextWidth,
+                    clientHeight: node.clientHeight,
+                    scrollHeight: node.scrollHeight,
+                    clientWidth: node.clientWidth,
+                    scrollWidth: node.scrollWidth,
+                    estimatedLineCount,
+                    expectedHeight,
+                    hasActualOverflow,
+                    hasEstimatedOverflow,
+                });
+            }
+
+            return {
+                summary: {
+                    checkedElements: elements.length,
+                    flaggedElements: result.length,
+                    hasIssues: result.length > 0,
+                },
+                flaggedElements: result,
+            };
+        }, { limit, selectors, overflowThreshold });
+
+        this.artifacts.appendEvent("text_layout_audit", {
+            ...audit.summary,
+            limit,
+            selectors,
+        });
+
+        return {
+            ...audit,
+            page: await this.getPageMetadata(400),
+            options: {
+                limit,
+                selectors,
+                overflowThreshold,
+            },
+        };
+    }
+
+    recordEvent(type, payload = {}) {
+        if (!this.artifacts.sessionDir) return;
+        this.artifacts.appendEvent(type, payload);
+    }
+
+    writeArtifactJson(filename, data) {
+        return this.artifacts.writeJson(filename, data);
+    }
+
+    writeArtifactText(filename, text) {
+        return this.artifacts.writeText(filename, text);
+    }
+
+    getDebugState(limit = 20) {
+        const artifacts = this.artifacts.sessionDir ? this.artifacts.getSummary() : this.lastSessionSummary;
+        const capabilities = this.sessionSource === "attached"
+            ? {
+                sessionReuse: true,
+                visibleBrowser: true,
+                videos: this.attachedVideoCapability,
+                traces: this.traceActive,
+                modeSwitching: false,
+            }
+            : {
+                sessionReuse: true,
+                visibleBrowser: this.browserMode === "headful",
+                videos: true,
+                traces: true,
+                modeSwitching: true,
+            };
+
+        return {
+            active: Boolean(this.browser),
+            requestedSource: this.requestedSource,
+            sessionSource: this.sessionSource,
+            autoFallbackReason: this.autoFallbackReason,
+            cdpEndpoint: this.cdpEndpoint,
+            browserMode: this.browserMode,
+            manualControlActive: this.manualControlActive,
+            capabilities,
+            recentConsole: this.consoleMessages.slice(-limit),
+            recentNetwork: this.networkEvents.slice(-limit),
+            recentErrors: this.pageErrors.slice(-limit),
+            counts: {
+                console: this.consoleMessages.length,
+                network: this.networkEvents.length,
+                errors: this.pageErrors.length,
+                observedElements: this.interactableElements.length,
+            },
+            artifacts,
+        };
+    }
+
+    flushLogsToArtifacts() {
+        if (!this.artifacts.sessionDir) return;
+
+        try {
+            if (this.consoleMessages.length > 0) {
+                const consolePath = this.artifacts.getConsoleLogPath();
+                fs.writeFileSync(consolePath, JSON.stringify(this.consoleMessages, null, 2), "utf8");
+            }
+            if (this.networkEvents.length > 0) {
+                const networkPath = this.artifacts.getNetworkLogPath();
+                fs.writeFileSync(networkPath, JSON.stringify(this.networkEvents, null, 2), "utf8");
+            }
+            if (this.pageErrors.length > 0) {
+                const errorsPath = this.artifacts.getErrorLogPath();
+                fs.writeFileSync(errorsPath, JSON.stringify(this.pageErrors, null, 2), "utf8");
+            }
+        } catch (error) {
+            console.error(`Failed to flush logs to artifacts: ${error.message}`);
+        }
+    }
+
+    async stop() {
+        if (!this.browser) {
+            return {
+                alreadyStopped: true,
+                artifacts: this.lastSessionSummary,
+            };
+        }
+
+        this.artifacts.appendEvent("session_stopping", this.getDebugState(10));
+        await this.stopAttachedScreencast({
+            reason: "session-stop",
+            persist: true,
+        });
+        await saveBrowserState(this.context, this.storageStatePath);
+
+        await this.finalizeTraceSegment("session-stop");
+        await this.browser.close();
+
+        // Persist in-memory logs to artifacts before resetting
+        this.flushLogsToArtifacts();
+
+        this.lastSessionSummary = this.artifacts.getSummary();
+        const result = {
+            alreadyStopped: false,
+            artifacts: this.lastSessionSummary,
+        };
+
+        this.resetRuntimeState();
+        return result;
+    }
+}