@mlola/backend-playwright 0.1.0

package/dist/backend.js

@@ -0,0 +1,945 @@
+/**
+ * Playwright browser backend (PRD §9.2, §9.3, §48).
+ *
+ * Browser mechanics only: sessions, atomic observation, typed execution,
+ * freshness/preflight checks, tabs, downloads, uploads, diagnostics and
+ * screenshots. No decisions, no model output, no policy.
+ */
+import { mkdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { chromium, } from "playwright-core";
+import { DEFAULT_BROWSER_CONFIG, RuntimeError, newSnapshotId, newTabId, } from "@mlola/browser-protocol";
+import { collectSnapshot, probeDocument, validateTarget } from "./snapshot-script.js";
+import { pageFn } from "./page-fn.js";
+const CAPABILITIES = {
+    observe: true,
+    click: true,
+    type: true,
+    select: true,
+    scroll: true,
+    press: true,
+    history: true,
+    tabs: true,
+    open_tab: true,
+    close_tab: true,
+    borrow: false,
+    return_tab: false,
+    human_help: false,
+    download: true,
+    upload: true,
+    console: true,
+    network: true,
+    screenshot: true,
+    canvas: false,
+    dialog_handling: true,
+    clipboard: false,
+};
+const MAX_DIAGNOSTICS = 40;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class PlaywrightBackend {
+    name = "playwright";
+    capabilities = CAPABILITIES;
+    #config = DEFAULT_BROWSER_CONFIG;
+    #browser;
+    #context;
+    #pages = [];
+    #activeTab;
+    #cdp = new Map();
+    #nodeIndex = new Map();
+    #pendingDialog;
+    #dialogWaiters = new Set();
+    #dialogDiagnostics = [];
+    #pendingFileChooser;
+    #downloads = [];
+    #console = [];
+    #failedRequests = [];
+    #navCounter = 0;
+    #tabCounter = 0;
+    #generation = 0;
+    #artifactsDir = "";
+    #screenshotsDir = "";
+    #closeDiagnostics = [];
+    #humanHandler;
+    /* ─────────────────────────────── session ──────────────────────────────── */
+    async startSession(input) {
+        this.#config = { ...DEFAULT_BROWSER_CONFIG, ...input.browser };
+        this.#artifactsDir = input.artifactsDir;
+        this.#screenshotsDir = input.screenshotsDir ?? join(input.artifactsDir, "screenshots");
+        mkdirSync(this.#artifactsDir, { recursive: true });
+        mkdirSync(this.#screenshotsDir, { recursive: true });
+        if (this.#config.mode === "cdp") {
+            const url = this.#config.cdpUrl ?? "http://127.0.0.1:9222";
+            this.#browser = await chromium.connectOverCDP(url);
+            const context = this.#browser.contexts()[0];
+            this.#context = context ?? (await this.#browser.newContext(this.#contextOptions()));
+            // Everything that already exists belongs to the user (PRD §10).
+            for (const page of this.#context.pages())
+                this.#registerPage(page, "user_owned", false);
+        }
+        else {
+            const launched = await this.#launch();
+            this.#browser = launched.browser;
+            this.#context = launched.context;
+            const existing = this.#context.pages();
+            for (const page of existing)
+                this.#registerPage(page, "agent_created", true);
+        }
+        const context = this.#context;
+        if (!context)
+            throw new RuntimeError("INTERNAL", "failed to create a browser context");
+        context.on("page", (page) => {
+            this.#registerPage(page, "agent_created", true);
+        });
+        if (this.#pages.length === 0) {
+            const page = await context.newPage();
+            this.#registerPage(page, "agent_created", true);
+        }
+        const active = this.#pages.find((p) => p.openedByRuntime) ?? this.#pages[0];
+        if (active) {
+            this.#activeTab = active.tabId;
+            await active.page.bringToFront().catch(() => undefined);
+        }
+        return {
+            sessionId: input.sessionId,
+            runId: input.runId,
+            backend: this.name,
+            capabilities: CAPABILITIES,
+            startedAt: Date.now(),
+        };
+    }
+    async #launch() {
+        const options = this.#launchOptions();
+        const channel = this.#config.channel ?? "chrome";
+        if (this.#config.userDataDir) {
+            try {
+                const context = await chromium.launchPersistentContext(this.#config.userDataDir, {
+                    ...this.#contextOptions(),
+                    ...options,
+                    channel,
+                });
+                const browser = context.browser();
+                if (!browser)
+                    throw new Error("persistent context has no browser handle");
+                return { browser, context };
+            }
+            catch (err) {
+                this.#closeDiagnostics.push(`persistent launch failed: ${String(err)}`);
+            }
+        }
+        try {
+            const browser = await chromium.launch({ ...options, channel });
+            const context = await browser.newContext(this.#contextOptions());
+            return { browser, context };
+        }
+        catch (err) {
+            this.#closeDiagnostics.push(`channel "${channel}" launch failed (${String(err)}); using bundled chromium`);
+            const browser = await chromium.launch(options);
+            const context = await browser.newContext(this.#contextOptions());
+            return { browser, context };
+        }
+    }
+    #launchOptions() {
+        return {
+            headless: this.#config.headless ?? false,
+            ...(this.#config.executablePath ? { executablePath: this.#config.executablePath } : {}),
+            ...(this.#config.slowMoMs ? { slowMo: this.#config.slowMoMs } : {}),
+            args: ["--no-first-run", "--no-default-browser-check"],
+        };
+    }
+    #contextOptions() {
+        return {
+            acceptDownloads: this.#config.acceptDownloads ?? true,
+            viewport: this.#config.viewport ?? { width: 1280, height: 800 },
+            ...(this.#config.locale ? { locale: this.#config.locale } : {}),
+            ...(this.#config.timezone ? { timezoneId: this.#config.timezone } : {}),
+        };
+    }
+    #registerPage(page, ownership, openedByRuntime) {
+        const existing = this.#pages.find((p) => p.page === page);
+        if (existing)
+            return existing;
+        const state = {
+            page,
+            tabId: newTabId(++this.#tabCounter),
+            ownership,
+            token: `p${++this.#navCounter}`,
+            openedByRuntime,
+        };
+        this.#pages.push(state);
+        page.on("framenavigated", (frame) => {
+            if (frame === page.mainFrame()) {
+                state.token = `p${++this.#navCounter}`;
+                this.#nodeIndex.clear();
+            }
+        });
+        page.on("dialog", (dialog) => {
+            if (dialog.type() === "alert") {
+                void dialog.accept().catch(() => undefined);
+                this.#dialogDiagnostics.push({
+                    level: "info",
+                    text: `alert auto-accepted: ${dialog.message().slice(0, 200)}`,
+                    at: Date.now(),
+                    count: 1,
+                });
+                return;
+            }
+            this.#pendingDialog = dialog;
+            for (const notify of this.#dialogWaiters)
+                notify();
+        });
+        page.on("console", (msg) => {
+            if (msg.type() !== "error" && msg.type() !== "warning")
+                return;
+            this.#pushDiagnostic(this.#console, {
+                level: msg.type() === "error" ? "error" : "warning",
+                text: msg.text().slice(0, 300),
+                at: Date.now(),
+                count: 1,
+            });
+        });
+        page.on("requestfailed", (request) => {
+            this.#pushDiagnostic(this.#failedRequests, {
+                url: request.url().slice(0, 300),
+                method: request.method(),
+                failure: request.failure()?.errorText ?? "failed",
+                at: Date.now(),
+            });
+        });
+        page.on("download", (download) => {
+            this.#downloads.push(download);
+        });
+        page.on("filechooser", (chooser) => {
+            this.#pendingFileChooser = chooser;
+        });
+        page.on("close", () => {
+            this.#pages = this.#pages.filter((p) => p.page !== page);
+            if (this.#activeTab === state.tabId)
+                this.#activeTab = this.#pages[0]?.tabId;
+        });
+        return state;
+    }
+    #pushDiagnostic(list, item) {
+        list.push(item);
+        if (list.length > MAX_DIAGNOSTICS)
+            list.shift();
+    }
+    async stopSession(_sessionId) {
+        const closedTabs = [];
+        const errors = [...this.#closeDiagnostics];
+        const returned = [];
+        // A modal dialog blocks the page; release it so tabs can actually close.
+        if (this.#pendingDialog) {
+            await this.#pendingDialog.dismiss().catch(() => undefined);
+            this.#pendingDialog = undefined;
+        }
+        const context = this.#context;
+        const browser = this.#browser;
+        this.#context = undefined;
+        this.#browser = undefined;
+        try {
+            if (context) {
+                // Only close tabs this runtime opened; never touch user tabs (PRD §10.2).
+                for (const state of [...this.#pages]) {
+                    if (!state.openedByRuntime) {
+                        returned.push({ tabId: state.tabId, ok: true, detail: "left open (not owned by the runtime)" });
+                        continue;
+                    }
+                    try {
+                        await state.page.close({ runBeforeUnload: false });
+                        closedTabs.push(state.tabId);
+                    }
+                    catch (err) {
+                        errors.push(`failed to close ${state.tabId}: ${String(err)}`);
+                    }
+                }
+                await context.close().catch((err) => errors.push(`context close: ${String(err)}`));
+            }
+            if (browser)
+                await browser.close().catch((err) => errors.push(`browser close: ${String(err)}`));
+        }
+        finally {
+            this.#pages = [];
+            this.#activeTab = undefined;
+            this.#cdp.clear();
+            this.#nodeIndex.clear();
+            this.#pendingDialog = undefined;
+            this.#pendingFileChooser = undefined;
+            this.#downloads = [];
+        }
+        return {
+            stoppedAt: Date.now(),
+            closedTabs,
+            returnedTabs: returned,
+            orphanLocks: [],
+            errors,
+        };
+    }
+    setHumanHelpHandler(handler) {
+        this.#humanHandler = handler;
+    }
+    /* ────────────────────────────── observation ───────────────────────────── */
+    async observe(sessionId) {
+        void sessionId;
+        const state = this.#requireActive();
+        const page = state.page;
+        if (this.#pendingDialog) {
+            const dialog = this.#pendingDialog;
+            const message = dialog.message().slice(0, 300);
+            const tabs = this.#tabInfosWithoutTitles();
+            return {
+                snapshotId: newSnapshotId(),
+                generation: ++this.#generation,
+                capturedAt: Date.now(),
+                pageToken: state.token,
+                url: page.url(),
+                title: "",
+                readyState: "complete",
+                textSummary: "",
+                injectedTexts: [],
+                nodes: [],
+                viewport: { width: 0, height: 0, scrollX: 0, scrollY: 0, documentWidth: 0, documentHeight: 0 },
+                tabs,
+                activeTabId: state.tabId, blockingUi: {
+                    kind: dialog.type() === "confirm"
+                        ? "confirm"
+                        : dialog.type() === "prompt"
+                            ? "prompt"
+                            : dialog.type() === "beforeunload"
+                                ? "beforeunload"
+                                : "alert",
+                    text: message,
+                    nodeIndexes: [],
+                    provenance: "browser_runtime",
+                },
+                fingerprint: `dialog:${dialog.type()}:${message.length}`,
+                history: { canGoBack: false, canGoForward: false },
+            };
+        }
+        let collected;
+        try {
+            collected = await page.evaluate(pageFn(collectSnapshot), { generation: this.#generation + 1,
+                token: state.token,
+                maxNodes: 900,
+                maxText: 2400,
+            });
+        }
+        catch (err) {
+            throw new RuntimeError("PAGE_MUTATED", `observation failed: ${String(err)}`, { cause: err, retryable: true });
+        }
+        this.#generation += 1;
+        this.#nodeIndex.clear();
+        for (const node of collected.nodes) {
+            this.#nodeIndex.set(node.nodeId, { tag: node.tag, role: node.role, token: state.token });
+        }
+        const history = await this.#history(page);
+        const tabs = await this.#tabInfos();
+        const snapshot = {
+            snapshotId: newSnapshotId(),
+            generation: this.#generation,
+            capturedAt: Date.now(),
+            pageToken: state.token,
+            url: collected.url,
+            title: collected.title,
+            readyState: collected.readyState === "complete" ? "complete" : collected.readyState === "loading" ? "loading" : "interactive",
+            textSummary: collected.textSummary,
+            injectedTexts: collected.injectedTexts.map((t) => ({
+                text: t.text,
+                provenance: "untrusted_page_content",
+                suspicious: true,
+            })),
+            nodes: collected.nodes.map((n) => ({
+                index: n.index,
+                nodeId: n.nodeId,
+                role: n.role,
+                label: n.label,
+                labelHash: n.labelHash,
+                tag: n.tag,
+                ...(n.kind !== undefined ? { kind: n.kind } : {}),
+                ...(n.inputType !== undefined ? { inputType: n.inputType } : {}),
+                ...(n.value !== undefined ? { value: n.value } : {}),
+                ...(n.placeholder !== undefined ? { placeholder: n.placeholder } : {}),
+                ...(n.title !== undefined ? { title: n.title } : {}),
+                ...(n.href !== undefined ? { href: n.href } : {}),
+                ...(n.accept !== undefined ? { accept: n.accept } : {}),
+                ...(n.multiple !== undefined ? { multiple: n.multiple } : {}),
+                ...(n.options !== undefined ? { options: n.options } : {}),
+                flags: n.flags,
+                operations: n.operations,
+                ...(n.geometry !== undefined ? { geometry: n.geometry } : {}),
+                ...(n.documentRect !== undefined ? { documentRect: n.documentRect } : {}),
+                ...(n.formNodeId !== undefined ? { formNodeId: n.formNodeId } : {}),
+                provenance: "interface_structure",
+            })),
+            viewport: collected.viewport,
+            tabs,
+            activeTabId: state.tabId,
+            blockingUi: collected.blockingUi
+                ? {
+                    kind: collected.blockingUi.kind,
+                    ...(collected.blockingUi.title !== undefined ? { title: collected.blockingUi.title } : {}),
+                    ...(collected.blockingUi.text !== undefined ? { text: collected.blockingUi.text } : {}),
+                    nodeIndexes: collected.blockingUi.nodeIndexes,
+                    provenance: "interface_structure",
+                }
+                : undefined,
+            diagnostics: { consoleErrors: [...this.#dialogDiagnostics, ...this.#console].slice(-20), failedRequests: this.#failedRequests.slice(-20) },
+            fingerprint: collected.fingerprint,
+            ...(collected.visualOnly ? { visualOnly: true } : {}),
+            history,
+        };
+        return snapshot;
+    }
+    async #history(page) {
+        try {
+            const cdp = await this.#cdpSession(page);
+            const result = (await cdp.send("Page.getNavigationHistory"));
+            return {
+                canGoBack: result.currentIndex > 0,
+                canGoForward: result.currentIndex < result.entries.length - 1,
+            };
+        }
+        catch {
+            // Non-Chromium (or CDP unavailable): history navigation is not offered.
+            return { canGoBack: false, canGoForward: false };
+        }
+    }
+    async #cdpSession(page) {
+        const existing = this.#cdp.get(page);
+        if (existing)
+            return existing;
+        const context = this.#context;
+        if (!context)
+            throw new Error("no browser context");
+        const session = await context.newCDPSession(page);
+        this.#cdp.set(page, session);
+        return session;
+    }
+    async #tabInfos() {
+        const infos = [];
+        for (const state of this.#pages) {
+            let title = "";
+            try {
+                title = state.page.isClosed() ? "" : await state.page.title();
+            }
+            catch {
+                title = "";
+            }
+            infos.push({
+                id: state.tabId,
+                title: title.slice(0, 200),
+                url: state.page.isClosed() ? "" : state.page.url(),
+                active: state.tabId === this.#activeTab,
+                ownership: state.ownership,
+            });
+        }
+        return infos;
+    }
+    /** Tab list that never round-trips to a page (safe while a dialog blocks). */
+    #tabInfosWithoutTitles() {
+        return this.#pages.map((state) => ({
+            id: state.tabId,
+            title: "",
+            url: state.page.isClosed() ? "" : state.page.url(),
+            active: state.tabId === this.#activeTab,
+            ownership: state.ownership,
+        }));
+    }
+    /* ─────────────────────────────── preflight ────────────────────────────── */
+    async preflight(_sessionId, action) {
+        const state = this.#requireActive();
+        if (this.#pendingDialog) {
+            if (action.op === "ACCEPT_DIALOG" || action.op === "DISMISS_DIALOG" || action.op === "WAIT") {
+                return { ok: true };
+            }
+            return {
+                ok: false,
+                code: "UNEXPECTED_DIALOG",
+                detail: "a blocking dialog is open; it must be resolved first",
+            };
+        }
+        if (action.op === "WAIT" || action.op === "BACK" || action.op === "FORWARD")
+            return { ok: true };
+        if (action.op === "ACCEPT_DIALOG" || action.op === "DISMISS_DIALOG") {
+            return { ok: false, code: "STALE_DECISION", detail: "no dialog is currently open" };
+        }
+        const ref = "ref" in action ? action.ref : undefined;
+        if (!ref)
+            return { ok: true };
+        const evidence = this.#nodeIndex.get(ref.nodeId);
+        if (!evidence) {
+            return {
+                ok: false,
+                code: "STALE_DECISION",
+                detail: "the target was not part of the most recent observation",
+                evidence: { nodeId: ref.nodeId },
+            };
+        }
+        const needsEditable = action.op === "TYPE_TEXT";
+        const requireHitTarget = action.op === "CLICK" || action.op === "DOWNLOAD" || action.op === "OPEN_TAB";
+        const result = await state.page.evaluate(pageFn(validateTarget), {
+            nodeId: ref.nodeId,
+            pageToken: state.token,
+            expectedToken: ref.pageToken,
+            tag: evidence.tag,
+            role: evidence.role,
+            operation: action.op,
+            ...(action.op === "SELECT" ? { optionValue: action.option.value, optionIndex: action.option.index } : {}),
+            ...(needsEditable ? { editableOnly: true } : {}),
+            ...(requireHitTarget ? { requireHitTarget: true } : {}),
+        });
+        if (!result.ok) {
+            return {
+                ok: false,
+                code: (result.code ?? "TARGET_INVALID"),
+                detail: result.detail,
+                ...(result.evidence ? { evidence: result.evidence } : {}),
+            };
+        }
+        return { ok: true };
+    }
+    /* ─────────────────────────────── execution ────────────────────────────── */
+    async execute(_sessionId, action) {
+        const state = this.#requireActive();
+        const page = state.page;
+        const started = Date.now();
+        const before = await this.#probe(page);
+        const urlBefore = page.url();
+        const tokenBefore = state.token;
+        const tabsBefore = this.#pages.length;
+        const downloadsBefore = this.#downloads.length;
+        const timeout = this.#config.actionTimeoutMs ?? 10_000;
+        let effect = "none";
+        let detail;
+        let newTabId;
+        let dialog;
+        const nodeHandle = async (nodeId) => {
+            const resolver = pageFn((id) => {
+                const w = window;
+                const bridge = w.__mlola_bridge_v1;
+                if (!bridge)
+                    return null;
+                const ref = bridge.byId.get(id);
+                const el = ref && typeof ref.deref === "function"
+                    ? ref.deref()
+                    : ref;
+                return el ?? null;
+            });
+            const handle = await page.evaluateHandle(resolver, nodeId);
+            const element = handle.asElement();
+            if (!element)
+                throw new RuntimeError("DETACHED_TARGET", "the target element is gone");
+            return element;
+        };
+        /**
+         * Runs a browser action and returns early when a native dialog opens: a
+         * modal dialog blocks the renderer, so the action's promise may not settle
+         * until the dialog is resolved (PRD §37).
+         */
+        const act = async (operation) => {
+            if (this.#pendingDialog)
+                return "dialog";
+            const promise = operation();
+            let notify;
+            const signal = new Promise((resolve) => {
+                notify = () => resolve("dialog");
+            });
+            this.#dialogWaiters.add(notify);
+            try {
+                const outcome = await Promise.race([promise.then((value) => ({ kind: "done", value })), signal]);
+                if (outcome === "dialog") {
+                    void promise.catch(() => undefined);
+                    return "dialog";
+                }
+                return outcome.value;
+            }
+            finally {
+                this.#dialogWaiters.delete(notify);
+            }
+        };
+        switch (action.op) {
+            case "CLICK": {
+                const element = await nodeHandle(action.ref.nodeId);
+                const clicked = await act(() => element.click({ timeout, clickCount: action.clickCount ?? 1 }));
+                detail = clicked === "dialog" ? "click opened a dialog" : "clicked";
+                break;
+            }
+            case "TYPE_TEXT": {
+                const element = await nodeHandle(action.ref.nodeId);
+                if (action.mode === "fill") {
+                    await element.fill(action.text, { timeout });
+                }
+                else {
+                    await element.click({ timeout });
+                    await page.keyboard.type(action.text, { delay: 12 });
+                }
+                if (action.submitAfter) {
+                    const pressed = await act(() => element.press("Enter", { timeout }));
+                    if (pressed === "dialog")
+                        detail = "submit opened a dialog";
+                }
+                if (!this.#pendingDialog)
+                    await this.#settle(page, true);
+                detail ??= `typed ${action.text.length} char(s)`;
+                break;
+            }
+            case "SELECT": {
+                const element = await nodeHandle(action.ref.nodeId);
+                const option = action.option.value.length > 0 ? { value: action.option.value } : { label: action.option.label };
+                await element.selectOption(option, { timeout });
+                detail = `selected ${action.option.label}`;
+                break;
+            }
+            case "SCROLL_UP":
+            case "SCROLL_DOWN": {
+                const viewport = page.viewportSize() ?? { width: 1280, height: 800 };
+                const amount = action.amount === "page" ? 0.9 : action.amount === "half" ? 0.5 : 0.25;
+                const delta = Math.round(viewport.height * amount) * (action.op === "SCROLL_DOWN" ? 1 : -1);
+                await page.mouse.move(Math.round(viewport.width / 2), Math.round(viewport.height / 2));
+                await page.mouse.wheel(0, delta);
+                effect = "scrolled";
+                detail = `scrolled ${delta}px`;
+                break;
+            }
+            case "WAIT":
+                await sleep(action.ms);
+                effect = "none";
+                detail = `waited ${action.ms}ms`;
+                break;
+            case "BACK": {
+                const response = await page.goBack({ waitUntil: "domcontentloaded", timeout }).catch(() => null);
+                if (response === null) {
+                    detail = "no previous entry";
+                    effect = "none";
+                }
+                else {
+                    effect = "navigated";
+                    detail = `back to ${page.url()}`;
+                }
+                break;
+            }
+            case "FORWARD": {
+                const response = await page.goForward({ waitUntil: "domcontentloaded", timeout }).catch(() => null);
+                if (response === null) {
+                    detail = "no forward entry";
+                    effect = "none";
+                }
+                else {
+                    effect = "navigated";
+                    detail = `forward to ${page.url()}`;
+                }
+                break;
+            }
+            case "OPEN_TAB": {
+                const beforeCount = this.#pages.length;
+                if (action.sourceRef) {
+                    const element = await nodeHandle(action.sourceRef.nodeId);
+                    await element.click({ timeout }).catch(() => undefined);
+                    await this.#waitFor(() => this.#pages.length > beforeCount, 2500);
+                }
+                if (this.#pages.length === beforeCount) {
+                    const context = this.#context;
+                    if (!context)
+                        throw new RuntimeError("INTERNAL", "no browser context");
+                    const created = await context.newPage();
+                    this.#registerPage(created, "agent_created", true);
+                    await created.goto(action.url, { waitUntil: "domcontentloaded", timeout });
+                }
+                const created = this.#pages[this.#pages.length - 1];
+                if (created) {
+                    newTabId = created.tabId;
+                    this.#activeTab = created.tabId;
+                    await created.page.bringToFront().catch(() => undefined);
+                }
+                effect = "new_tab";
+                detail = `opened ${action.url}`;
+                break;
+            }
+            case "SWITCH_TAB": {
+                const target = this.#pages.find((p) => p.tabId === action.tabId);
+                if (!target)
+                    throw new RuntimeError("TARGET_NOT_FOUND", `unknown tab ${action.tabId}`);
+                this.#activeTab = target.tabId;
+                await target.page.bringToFront().catch(() => undefined);
+                effect = "tab_switched";
+                detail = `switched to ${target.tabId}`;
+                break;
+            }
+            case "CLOSE_TAB": {
+                const target = this.#pages.find((p) => p.tabId === action.tabId);
+                if (!target)
+                    throw new RuntimeError("TARGET_NOT_FOUND", `unknown tab ${action.tabId}`);
+                await target.page.close({ runBeforeUnload: false });
+                effect = "tab_closed";
+                detail = `closed ${action.tabId}`;
+                break;
+            }
+            case "DOWNLOAD": {
+                const element = await nodeHandle(action.ref.nodeId);
+                await act(() => element.click({ timeout }));
+                await this.#waitFor(() => this.#downloads.length > downloadsBefore, 3000);
+                detail = "download triggered";
+                break;
+            }
+            case "UPLOAD": {
+                const element = await nodeHandle(action.ref.nodeId);
+                const filePath = this.#uploadPath(action.artifactId);
+                const mechanism = action.mechanism;
+                if (mechanism === "file_input") {
+                    await element.setInputFiles(filePath, { timeout });
+                }
+                else if (mechanism === "file_chooser") {
+                    this.#pendingFileChooser = undefined;
+                    await element.click({ timeout });
+                    const chooser = await this.#waitForValue(() => this.#pendingFileChooser, 2500);
+                    if (!chooser)
+                        throw new RuntimeError("UPLOAD_FAILED", "no file chooser appeared");
+                    await chooser.setFiles(filePath);
+                    this.#pendingFileChooser = undefined;
+                }
+                else {
+                    await this.#dropFiles(element, filePath);
+                }
+                effect = "upload_dispatched";
+                detail = `uploaded ${basename(filePath)} via ${mechanism}`;
+                break;
+            }
+            case "PRESS": {
+                if (action.ref) {
+                    const element = await nodeHandle(action.ref.nodeId);
+                    await act(() => element.press(action.key, { timeout }));
+                }
+                else {
+                    await act(() => page.keyboard.press(action.key));
+                }
+                detail = `pressed ${action.key}`;
+                break;
+            }
+            case "ACCEPT_DIALOG":
+            case "DISMISS_DIALOG": {
+                const dialog = this.#pendingDialog;
+                if (!dialog)
+                    throw new RuntimeError("STALE_DECISION", "no dialog is open");
+                if (action.op === "ACCEPT_DIALOG")
+                    await dialog.accept();
+                else
+                    await dialog.dismiss();
+                this.#pendingDialog = undefined;
+                effect = "dialog_closed";
+                detail = `dialog ${action.op === "ACCEPT_DIALOG" ? "accepted" : "dismissed"}`;
+                break;
+            }
+            default:
+                throw new RuntimeError("TARGET_INVALID", `playwright backend cannot execute ${action.op}`);
+        }
+        // Bounded settle + effect probe (PRD §26). While a native dialog is open the
+        // renderer is blocked, so page round-trips must be skipped.
+        const dialogOpen = this.#pendingDialog !== undefined;
+        if (!dialogOpen)
+            await this.#settle(page, action.op === "TYPE_TEXT");
+        const after = dialogOpen ? undefined : await this.#probe(page).catch(() => undefined);
+        const tokenAfter = state.token;
+        const urlAfter = page.url();
+        const tabCountAfter = this.#pages.length;
+        if (tokenBefore !== tokenAfter || urlBefore !== urlAfter) {
+            if (effect === "none")
+                effect = "navigated";
+        }
+        else if (after && before && after.mutationCount > before.mutationCount && effect === "none") {
+            effect = "dom_mutated";
+        }
+        if (effect === "scrolled" && after && before && after.scrollY === before.scrollY) {
+            effect = "none";
+        }
+        if (tabCountAfter < tabsBefore && effect === "none")
+            effect = "tab_closed";
+        if (tabCountAfter > tabsBefore) {
+            if (effect === "none" || effect === "dom_mutated")
+                effect = "new_tab";
+            const newest = this.#pages[this.#pages.length - 1];
+            if (newest && newest.tabId !== state.tabId)
+                newTabId = newest.tabId;
+        }
+        if (this.#pendingDialog && effect === "none") {
+            effect = "dialog_opened";
+            dialog = { kind: this.#pendingDialog.type(), text: this.#pendingDialog.message().slice(0, 200) };
+        }
+        // Downloads started by this action: wait for completion and hand the file over.
+        let downloadedFile;
+        if (this.#downloads.length > downloadsBefore) {
+            const download = this.#downloads[this.#downloads.length - 1];
+            if (download) {
+                downloadedFile = await this.#collectDownload(download);
+                if (effect === "none" || effect === "dom_mutated")
+                    effect = "download_completed";
+            }
+        }
+        let unknownEffect = false;
+        if (action.op === "DOWNLOAD" && !downloadedFile) {
+            const inconclusive = effect === "none" || effect === "dom_mutated" || effect === "scrolled";
+            unknownEffect = inconclusive;
+            detail = `${detail ?? "download"} (no file captured)`;
+        }
+        if (action.op === "UPLOAD" && effect !== "upload_dispatched")
+            unknownEffect = true;
+        if (action.op === "CLICK" && effect === "none") {
+            // Clicks can legitimately have no visible effect; do not claim failure.
+            detail = `${detail ?? "clicked"} (no observable effect)`;
+        }
+        return {
+            ok: true,
+            effect,
+            ...(detail !== undefined ? { detail } : {}),
+            latencyMs: Date.now() - started,
+            urlBefore,
+            urlAfter,
+            pageTokenBefore: tokenBefore,
+            pageTokenAfter: tokenAfter,
+            ...(unknownEffect ? { unknownEffect: true } : {}),
+            ...(downloadedFile ? { downloadedFile } : {}),
+            ...(newTabId ? { newTabId } : {}),
+            ...(dialog ? { dialog } : {}),
+        };
+    }
+    async navigate(_sessionId, url) {
+        const state = this.#requireActive();
+        const started = Date.now();
+        const urlBefore = state.page.url();
+        const tokenBefore = state.token;
+        try {
+            await state.page.goto(url, { waitUntil: "domcontentloaded", timeout: this.#config.actionTimeoutMs ?? 15_000 });
+        }
+        catch (err) {
+            const message = String(err);
+            if (/Timeout/i.test(message)) {
+                throw new RuntimeError("NAVIGATION_TIMEOUT", `navigation to ${url} timed out`, { cause: err });
+            }
+            throw new RuntimeError("NETWORK_FAILURE", `navigation to ${url} failed: ${message}`, { cause: err });
+        }
+        await this.#settle(state.page, false);
+        return {
+            ok: true,
+            effect: "navigated",
+            detail: `navigated to ${state.page.url()}`,
+            latencyMs: Date.now() - started,
+            urlBefore,
+            urlAfter: state.page.url(),
+            pageTokenBefore: tokenBefore,
+            pageTokenAfter: state.token,
+        };
+    }
+    async listTabs(_sessionId) {
+        return this.#tabInfos();
+    }
+    async switchTab(_sessionId, tabId) {
+        const target = this.#pages.find((p) => p.tabId === tabId);
+        if (!target)
+            throw new RuntimeError("TARGET_NOT_FOUND", `unknown tab ${tabId}`);
+        this.#activeTab = tabId;
+        await target.page.bringToFront().catch(() => undefined);
+    }
+    async getDiagnostics(_sessionId) {
+        return {
+            consoleErrors: [...this.#dialogDiagnostics, ...this.#console].slice(-20),
+            failedRequests: this.#failedRequests.slice(-20),
+        };
+    }
+    async screenshot(_sessionId, reason) {
+        const state = this.#requireActive();
+        const safeReason = reason.replace(/[^a-z0-9-]+/gi, "-").slice(0, 40);
+        const path = join(this.#screenshotsDir, `${Date.now()}-${safeReason}.png`);
+        await state.page.screenshot({ path, fullPage: false });
+        const size = state.page.viewportSize() ?? { width: 0, height: 0 };
+        return { path, width: size.width, height: size.height };
+    }
+    /* ──────────────────────────────── helpers ─────────────────────────────── */
+    #requireActive() {
+        const state = this.#pages.find((p) => p.tabId === this.#activeTab) ?? this.#pages[0];
+        if (!state)
+            throw new RuntimeError("INTERNAL", "no active browser tab");
+        return state;
+    }
+    async #probe(page) {
+        return page.evaluate(pageFn(probeDocument)).catch(() => undefined);
+    }
+    async #settle(page, waitForOptions) {
+        const settleMs = this.#config.settleMs ?? 250;
+        if (waitForOptions) {
+            // Autocomplete/combobox: wait for a visible option list, bounded (PRD §26).
+            await page
+                .waitForSelector('[role="listbox"], [role="option"], .autocomplete-items li, datalist option', {
+                timeout: 900,
+                state: "attached",
+            })
+                .catch(() => undefined);
+        }
+        await sleep(settleMs);
+        await page.waitForLoadState("domcontentloaded", { timeout: 3000 }).catch(() => undefined);
+    }
+    async #waitFor(predicate, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (predicate())
+                return true;
+            await sleep(60);
+        }
+        return predicate();
+    }
+    async #waitForValue(get, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const value = get();
+            if (value !== undefined)
+                return value;
+            await sleep(60);
+        }
+        return get();
+    }
+    #uploadPath(artifactId) {
+        const registryPath = join(this.#artifactsDir, "registry.json");
+        try {
+            const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
+            const record = parsed.records?.find((r) => r.id === artifactId);
+            if (record)
+                return record.localPath;
+        }
+        catch {
+            /* fall through */
+        }
+        throw new RuntimeError("UPLOAD_FAILED", `artifact ${artifactId} is not registered on disk`);
+    }
+    async #dropFiles(element, filePath) {
+        const bytes = readFileSync(filePath);
+        const b64 = bytes.toString("base64");
+        const name = basename(filePath);
+        await element.evaluate(pageFn((el, arg) => {
+            const bin = atob(arg.b64);
+            const arr = new Uint8Array(bin.length);
+            for (let i = 0; i < bin.length; i += 1)
+                arr[i] = bin.charCodeAt(i);
+            const file = new File([arr], arg.name, { type: "application/octet-stream" });
+            const dt = new DataTransfer();
+            dt.items.add(file);
+            for (const type of ["dragenter", "dragover", "drop"]) {
+                el.dispatchEvent(new DragEvent(type, { bubbles: true, cancelable: true, dataTransfer: dt }));
+            }
+        }), { b64, name });
+    }
+    async #collectDownload(download) {
+        const suggestedName = download.suggestedFilename();
+        const url = download.url();
+        try {
+            const failure = await download.failure();
+            if (failure)
+                return { path: "", suggestedName, url, completed: false, failure };
+            const target = join(this.#artifactsDir, "downloads", suggestedName);
+            mkdirSync(join(this.#artifactsDir, "downloads"), { recursive: true });
+            await download.saveAs(target);
+            return { path: target, suggestedName, url, completed: true };
+        }
+        catch (err) {
+            return { path: "", suggestedName, url, completed: false, failure: String(err) };
+        }
+    }
+}
+export const createPlaywrightBackend = () => new PlaywrightBackend();
+//# sourceMappingURL=backend.js.map