opendevbrowser 0.0.17 → 0.0.19

package/extension/dist/ops/ops-runtime.js

@@ -1,4 +1,5 @@
 import { MAX_OPS_PAYLOAD_BYTES, MAX_SNAPSHOT_BYTES, OPS_PROTOCOL_VERSION } from "../types.js";
+import { isAttachBlockedError } from "../services/attach-errors.js";
 import { TabManager } from "../services/TabManager.js";
 import { getRestrictionMessage, isRestrictedUrl } from "../services/url-restrictions.js";
 import { logError } from "../logging.js";
@@ -12,12 +13,195 @@ const MAX_NETWORK_EVENTS = 300;
 const SESSION_TTL_MS = 20_000;
 const SCREENSHOT_TIMEOUT_MS = 8000;
 const TAB_CLOSE_TIMEOUT_MS = 5000;
+const POPUP_ATTACH_RETRY_DELAY_MS = 100;
+const STALE_REF_ERROR_SUFFIX = "Take a new snapshot first.";
+const DOM_OUTER_HTML_DECLARATION = `
+  function() {
+    if (!(this instanceof Element)) return "";
+    return this.outerHTML;
+  }
+`;
+const DOM_INNER_TEXT_DECLARATION = `
+  function() {
+    if (!(this instanceof Element)) return "";
+    return this instanceof HTMLElement ? (this.innerText || this.textContent || "") : (this.textContent || "");
+  }
+`;
+const DOM_GET_ATTR_DECLARATION = `
+  function(name) {
+    if (!(this instanceof Element)) return null;
+    const value = this.getAttribute(name);
+    return value === null ? null : String(value);
+  }
+`;
+const DOM_GET_VALUE_DECLARATION = `
+  function() {
+    if (this instanceof HTMLInputElement || this instanceof HTMLTextAreaElement || this instanceof HTMLSelectElement) {
+      return this.value;
+    }
+    if (!(this instanceof Element)) return null;
+    const value = this.getAttribute("value");
+    return value === null ? null : String(value);
+  }
+`;
+const DOM_IS_VISIBLE_DECLARATION = `
+  function() {
+    if (!(this instanceof Element)) return false;
+    const style = window.getComputedStyle(this);
+    if (!style || style.display === "none" || style.visibility === "hidden" || style.opacity === "0") {
+      return false;
+    }
+    const rect = this.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  }
+`;
+const DOM_IS_ENABLED_DECLARATION = `
+  function() {
+    if (!(this instanceof Element)) return false;
+    return !this.hasAttribute("disabled") && this.getAttribute("aria-disabled") !== "true";
+  }
+`;
+const DOM_IS_CHECKED_DECLARATION = `
+  function() {
+    if (this instanceof HTMLInputElement && (this.type === "checkbox" || this.type === "radio")) {
+      return this.checked;
+    }
+    if (!(this instanceof Element)) return false;
+    return this.getAttribute("aria-checked") === "true";
+  }
+`;
+const DOM_SELECTOR_STATE_DECLARATION = `
+  function() {
+    if (!(this instanceof Element)) {
+      return { attached: false, visible: false };
+    }
+    const style = window.getComputedStyle(this);
+    const rect = this.getBoundingClientRect();
+    return {
+      attached: true,
+      visible: Boolean(style && style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0" && rect.width > 0 && rect.height > 0)
+    };
+  }
+`;
+const DOM_HOVER_DECLARATION = `
+  function() {
+    if (!(this instanceof Element)) return;
+    const init = { bubbles: true, cancelable: true, view: window };
+    this.dispatchEvent(new MouseEvent("mouseenter", init));
+    this.dispatchEvent(new MouseEvent("mouseover", init));
+    this.dispatchEvent(new MouseEvent("mousemove", init));
+  }
+`;
+const DOM_FOCUS_DECLARATION = `
+  function() {
+    if (this instanceof HTMLElement) {
+      this.focus();
+    }
+  }
+`;
+const DOM_SET_CHECKED_DECLARATION = `
+  function(checked) {
+    if (this instanceof HTMLInputElement && (this.type === "checkbox" || this.type === "radio")) {
+      this.checked = Boolean(checked);
+      this.dispatchEvent(new Event("input", { bubbles: true }));
+      this.dispatchEvent(new Event("change", { bubbles: true }));
+      return;
+    }
+    if (this instanceof Element) {
+      this.setAttribute("aria-checked", checked ? "true" : "false");
+    }
+  }
+`;
+const DOM_TYPE_DECLARATION = `
+  function(value, clear, submit) {
+    if (!(this instanceof Element)) return;
+    if (this instanceof HTMLElement) {
+      this.focus();
+    }
+    if (this instanceof HTMLInputElement || this instanceof HTMLTextAreaElement) {
+      this.value = clear ? "" : this.value;
+      this.value = String(value);
+      this.dispatchEvent(new Event("input", { bubbles: true }));
+      this.dispatchEvent(new Event("change", { bubbles: true }));
+      if (submit) {
+        this.form?.requestSubmit?.();
+      }
+      return;
+    }
+    if (this instanceof HTMLSelectElement) {
+      this.value = String(value);
+      this.dispatchEvent(new Event("input", { bubbles: true }));
+      this.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+  }
+`;
+const DOM_SELECT_DECLARATION = `
+  function(values) {
+    if (!(this instanceof HTMLSelectElement)) return;
+    const nextValues = Array.isArray(values) ? values.map((value) => String(value)) : [];
+    for (const option of Array.from(this.options)) {
+      option.selected = nextValues.includes(option.value);
+    }
+    this.dispatchEvent(new Event("input", { bubbles: true }));
+    this.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+`;
+const DOM_SCROLL_BY_DECLARATION = `
+  function(dy) {
+    if (!(this instanceof HTMLElement)) return;
+    this.scrollBy(0, Number(dy) || 0);
+  }
+`;
+const DOM_SCROLL_INTO_VIEW_DECLARATION = `
+  function() {
+    if (this instanceof Element) {
+      this.scrollIntoView({ block: "center", inline: "center", behavior: "auto" });
+    }
+  }
+`;
+const DOM_REF_POINT_DECLARATION = `
+  function() {
+    if (!(this instanceof Element)) return null;
+    const rect = this.getBoundingClientRect();
+    return {
+      x: rect.left + rect.width / 2,
+      y: rect.top + rect.height / 2
+    };
+  }
+`;
+const DOM_SCREENSHOT_CLIP_DECLARATION = `
+  function() {
+    /* odb-dom-screenshot-clip */
+    if (!(this instanceof Element)) return null;
+    const rect = this.getBoundingClientRect();
+    if (!Number.isFinite(rect.width) || !Number.isFinite(rect.height) || rect.width <= 0 || rect.height <= 0) {
+      return null;
+    }
+    return {
+      x: rect.left + window.scrollX,
+      y: rect.top + window.scrollY,
+      width: rect.width,
+      height: rect.height
+    };
+  }
+`;
+const DOM_FILE_INPUT_INFO_DECLARATION = `
+  function() {
+    /* odb-dom-file-input-info */
+    const isFileInput = this instanceof HTMLInputElement && this.type === "file";
+    return {
+      isFileInput,
+      disabled: isFileInput ? this.disabled : false
+    };
+  }
+`;
 const TARGET_SCOPED_COMMANDS = new Set([
     "storage.setCookies",
     "storage.getCookies",
     "nav.goto",
     "nav.wait",
     "nav.snapshot",
+    "nav.review",
     "interact.click",
     "interact.hover",
     "interact.press",
@@ -27,6 +211,11 @@ const TARGET_SCOPED_COMMANDS = new Set([
     "interact.select",
     "interact.scroll",
     "interact.scrollIntoView",
+    "interact.upload",
+    "pointer.move",
+    "pointer.down",
+    "pointer.up",
+    "pointer.drag",
     "dom.getHtml",
     "dom.getText",
     "dom.getAttr",
@@ -34,12 +223,20 @@ const TARGET_SCOPED_COMMANDS = new Set([
     "dom.isVisible",
     "dom.isEnabled",
     "dom.isChecked",
+    "dom.refPoint",
+    "canvas.overlay.mount",
+    "canvas.overlay.unmount",
+    "canvas.overlay.select",
+    "canvas.overlay.sync",
     "canvas.applyRuntimePreviewBridge",
     "export.clonePage",
     "export.cloneComponent",
     "devtools.perf",
     "page.screenshot"
 ]);
+const DIALOG_SCOPED_COMMANDS = new Set([
+    "page.dialog"
+]);
 export class OpsRuntime {
     sendEnvelope;
     cdp;
@@ -49,6 +246,10 @@ export class OpsRuntime {
     dom = new DomBridge();
     sessions = new OpsSessionStore();
     encoder = new TextEncoder();
+    popupOpenerTabIds = new Map();
+    popupAttachDiagnostics = new Map();
+    commandCreatedTabs = new Map();
+    dialogQueues = new Map();
     closingTimers = new Map();
     parallelWaiters = new Map();
     constructor(options) {
@@ -56,10 +257,29 @@ export class OpsRuntime {
         this.cdp = options.cdp;
         this.getCanvasPageState = options.getCanvasPageState;
         this.performCanvasPageAction = options.performCanvasPageAction;
+        chrome.tabs.onCreated.addListener(this.handleTabCreated);
         chrome.tabs.onRemoved.addListener(this.handleTabRemoved);
         chrome.tabs.onUpdated.addListener(this.handleTabUpdated);
+        chrome.webNavigation?.onCreatedNavigationTarget?.addListener?.(this.handleCreatedNavigationTarget);
         chrome.debugger.onEvent.addListener(this.handleDebuggerEvent);
         chrome.debugger.onDetach.addListener(this.handleDebuggerDetach);
+        if (typeof this.cdp.addEventListener === "function") {
+            this.cdp.addEventListener(this.handleCdpRouterEvent);
+        }
+    }
+    async registerCanvasTargetForSession(opsSessionId, targetId) {
+        const session = this.sessions.get(opsSessionId);
+        if (!session) {
+            return null;
+        }
+        return await this.registerCanvasTarget(session, targetId);
+    }
+    unregisterCanvasTargetForSession(opsSessionId, targetId) {
+        const session = this.sessions.get(opsSessionId);
+        if (!session || targetId === session.targetId) {
+            return false;
+        }
+        return this.sessions.removeTarget(session.id, targetId) !== null;
     }
     handleMessage(message) {
         if (message.type === "ops_hello") {
@@ -122,18 +342,125 @@ export class OpsRuntime {
         const clientId = message.clientId;
         if (!clientId)
             return;
+        this.cdp.markClientClosed();
         const sessions = this.sessions.listOwnedBy(clientId);
         for (const session of sessions) {
-            this.markSessionClosing(session, "ops_session_expired");
+            if (this.markSessionClosing(session, "ops_session_expired")) {
+                this.emitSessionEvent(session, "ops_session_released");
+            }
         }
     }
     handleTabRemoved = (tabId) => {
+        this.forgetCommandCreatedTab(tabId);
+        this.popupOpenerTabIds.delete(tabId);
         this.handleClosedTarget(tabId, "ops_tab_closed");
     };
+    handleCreatedNavigationTarget = (details) => {
+        const tabId = typeof details.tabId === "number" ? details.tabId : null;
+        const openerTabId = typeof details.sourceTabId === "number" ? details.sourceTabId : null;
+        if (tabId === null || openerTabId === null) {
+            return;
+        }
+        this.popupOpenerTabIds.set(tabId, openerTabId);
+    };
+    handleTabCreated = (tab) => {
+        const tabId = typeof tab.id === "number" ? tab.id : null;
+        if (tabId === null) {
+            return;
+        }
+        if (this.isCommandCreatedTab(tabId)) {
+            return;
+        }
+        const openerTabId = typeof tab.openerTabId === "number" ? tab.openerTabId : null;
+        if (openerTabId !== null) {
+            const session = this.sessions.getByTabId(openerTabId);
+            if (!session) {
+                return;
+            }
+            this.finishCreatedTab(session, this.sessions.getTargetIdByTabId(session.id, openerTabId) ?? session.targetId, tab, tabId);
+            return;
+        }
+        void this.handleCreatedTab(tab, tabId);
+    };
+    async handleCreatedTab(tab, tabId) {
+        const opener = await this.resolvePopupOpenerContext(tabId, typeof tab.openerTabId === "number" ? tab.openerTabId : null);
+        if (!opener) {
+            return;
+        }
+        this.finishCreatedTab(opener.session, opener.openerTargetId, tab, tabId);
+    }
+    finishCreatedTab(session, openerTargetId, tab, tabId) {
+        this.popupOpenerTabIds.delete(tabId);
+        const existingTargetId = this.updateKnownTabTarget(session, tab);
+        if (existingTargetId) {
+            const existingTarget = session.targets.get(existingTargetId) ?? null;
+            if (existingTarget && !existingTarget.openerTargetId) {
+                existingTarget.openerTargetId = openerTargetId;
+            }
+            const resolvedTarget = this.resolveTargetContext(session, existingTargetId);
+            if (resolvedTarget
+                && this.shouldPromotePopupTarget(session, openerTargetId, resolvedTarget)) {
+                session.activeTargetId = existingTargetId;
+            }
+            return;
+        }
+        const target = this.sessions.addTarget(session.id, tabId, {
+            url: tab.url ?? undefined,
+            title: tab.title ?? undefined,
+            openerTargetId: openerTargetId
+        });
+        void this.attachCreatedTab(session, target.targetId, tabId);
+    }
+    async resolvePopupOpenerContext(tabId, openerTabId) {
+        let resolvedOpenerTabId = openerTabId ?? this.popupOpenerTabIds.get(tabId) ?? null;
+        if (resolvedOpenerTabId === null && typeof this.cdp.resolveTabOpenerTargetId === "function") {
+            const openerTargetId = await this.cdp.resolveTabOpenerTargetId(tabId).catch(() => null);
+            resolvedOpenerTabId = parseTargetAliasTabId(openerTargetId ?? undefined);
+        }
+        if (resolvedOpenerTabId === null) {
+            return null;
+        }
+        const session = this.sessions.getByTabId(resolvedOpenerTabId);
+        if (!session) {
+            return null;
+        }
+        return {
+            session,
+            openerTargetId: this.sessions.getTargetIdByTabId(session.id, resolvedOpenerTabId) ?? session.targetId
+        };
+    }
+    async hydratePopupOpenerTarget(session, targetId) {
+        const target = session.targets.get(targetId) ?? null;
+        if (!target || target.openerTargetId) {
+            return target;
+        }
+        const opener = await this.resolvePopupOpenerContext(target.tabId, null);
+        if (!opener || opener.session.id !== session.id) {
+            return target;
+        }
+        target.openerTargetId = opener.openerTargetId;
+        return target;
+    }
     handleTabUpdated = (tabId, changeInfo, tab) => {
         const session = this.sessions.getByTabId(tabId);
-        if (!session)
+        if (!session) {
+            if (this.isCommandCreatedTab(tabId)) {
+                return;
+            }
+            if (changeInfo.status === "complete" || tab.status === "complete" || typeof tab.openerTabId === "number") {
+                void this.handleCreatedTab(tab, tabId);
+            }
             return;
+        }
+        const targetId = this.updateKnownTabTarget(session, tab);
+        if (targetId
+            && tab.active === true
+            && (changeInfo.status === "complete" || tab.status === "complete")) {
+            const target = this.resolveTargetContext(session, targetId);
+            if (target && (!target.openerTargetId || this.hasUsableDebuggee(target))) {
+                session.activeTargetId = targetId;
+            }
+        }
         if (changeInfo.discarded === true || tab.discarded === true) {
             session.discardedSignals += 1;
         }
@@ -148,10 +475,60 @@ export class OpsRuntime {
             return;
         void this.handleDebuggerDetachForTab(source.tabId);
     };
+    updateKnownTabTarget(session, tab) {
+        const tabId = typeof tab.id === "number" ? tab.id : null;
+        if (tabId === null) {
+            return null;
+        }
+        const targetId = this.sessions.getTargetIdByTabId(session.id, tabId);
+        if (!targetId) {
+            return null;
+        }
+        const target = session.targets.get(targetId);
+        if (!target) {
+            return targetId;
+        }
+        const nextUrl = getReportedTabUrl(tab);
+        const nextTitle = getReportedTabTitle(tab);
+        if (typeof nextUrl === "string" && nextUrl.length > 0) {
+            target.url = nextUrl;
+        }
+        if (typeof nextTitle === "string" && nextTitle.length > 0) {
+            target.title = nextTitle;
+        }
+        return targetId;
+    }
+    async attachCreatedTab(session, targetId, tabId) {
+        const target = await this.hydratePopupOpenerTarget(session, targetId);
+        if (target?.openerTargetId) {
+            // Keep the opener root stable and attach popup tabs only when the caller explicitly targets them.
+            return;
+        }
+        await this.tabs.waitForTabComplete(tabId, 5000).catch(() => undefined);
+        try {
+            await this.attachTargetTab(tabId);
+            await this.enableTargetDomains(tabId, true);
+            this.promotePopupTarget(session, targetId);
+        }
+        catch (error) {
+            if (target && isAttachBlockedError(error)) {
+                const bridged = await this.attachTargetViaOpenerSession(session, target).catch(() => false);
+                if (bridged) {
+                    this.promotePopupTarget(session, targetId);
+                    return;
+                }
+            }
+            logError("ops.popup_tab_attach", error, {
+                code: "popup_tab_attach_failed",
+                extra: { tabId }
+            });
+        }
+    }
     handleDebuggerEvent = (source, method, params) => {
-        if (typeof source.tabId !== "number")
+        const eventTabId = this.cdp.resolveSourceTabId(source);
+        if (eventTabId === null)
             return;
-        const session = this.sessions.getByTabId(source.tabId);
+        const session = this.sessions.getByTabId(eventTabId);
         if (!session)
             return;
         if (method === "Runtime.consoleAPICalled") {
@@ -180,6 +557,29 @@ export class OpsRuntime {
             }
             return;
         }
+        if (method === "Page.javascriptDialogOpening") {
+            const targetId = this.resolveDebuggerEventTargetId(session, source, eventTabId);
+            if (!targetId) {
+                return;
+            }
+            this.applyDialogOpening(session, targetId, params);
+            return;
+        }
+        if (method === "Page.javascriptDialogClosed") {
+            const targetId = this.resolveDebuggerEventTargetId(session, source, eventTabId);
+            if (targetId) {
+                this.applyDialogClosed(session, targetId);
+            }
+            return;
+        }
+        if (method === "Page.fileChooserOpened") {
+            const targetId = this.resolveDebuggerEventTargetId(session, source, eventTabId);
+            if (!targetId) {
+                return;
+            }
+            this.applyFileChooserOpened(session, targetId, params);
+            return;
+        }
         if (method === "Network.requestWillBeSent") {
             const payload = params;
             const requestId = payload.requestId;
@@ -228,6 +628,130 @@ export class OpsRuntime {
             }
         }
     };
+    handleCdpRouterEvent = (event) => {
+        const session = this.sessions.getByTabId(event.tabId);
+        if (!session) {
+            return;
+        }
+        switch (event.method) {
+            case "Page.javascriptDialogOpening": {
+                const targetId = this.resolveRouterEventTargetId(session, event);
+                if (!targetId) {
+                    return;
+                }
+                this.applyDialogOpening(session, targetId, event.params);
+                return;
+            }
+            case "Page.javascriptDialogClosed": {
+                const targetId = this.resolveRouterEventTargetId(session, event);
+                if (!targetId) {
+                    return;
+                }
+                this.applyDialogClosed(session, targetId);
+                return;
+            }
+            case "Page.fileChooserOpened": {
+                const targetId = this.resolveRouterEventTargetId(session, event);
+                if (!targetId) {
+                    return;
+                }
+                this.applyFileChooserOpened(session, targetId, event.params);
+                return;
+            }
+            case "Target.targetCreated":
+                this.handleSyntheticTargetCreated(session, event);
+                return;
+            case "Target.attachedToTarget":
+                this.handleSyntheticTargetAttached(session, event);
+                return;
+            case "Target.targetDestroyed":
+                this.handleSyntheticTargetDestroyed(session, event);
+                return;
+            case "Target.detachedFromTarget":
+                this.handleSyntheticTargetDetached(session, event);
+                return;
+            default:
+                return;
+        }
+    };
+    handleSyntheticTargetCreated(session, event) {
+        const targetInfo = extractTargetInfo(event.params);
+        if (!targetInfo || !isSyntheticPageTarget(session, targetInfo.targetId, targetInfo.type)) {
+            return;
+        }
+        const resolvedTabId = parseTabTargetId(targetInfo.targetId) ?? event.tabId;
+        this.sessions.upsertSyntheticTarget(session.id, {
+            targetId: targetInfo.targetId,
+            tabId: resolvedTabId,
+            type: targetInfo.type,
+            ...(typeof targetInfo.url === "string" ? { url: targetInfo.url } : {}),
+            ...(typeof targetInfo.title === "string" ? { title: targetInfo.title } : {}),
+            ...(typeof targetInfo.openerId === "string" ? { openerTargetId: targetInfo.openerId } : {}),
+            attachedAt: Date.now()
+        });
+    }
+    handleSyntheticTargetAttached(session, event) {
+        const payload = isRecord(event.params) ? event.params : null;
+        const targetInfo = extractTargetInfo(payload);
+        const childSessionId = payload && typeof payload.sessionId === "string" ? payload.sessionId : undefined;
+        if (!targetInfo || !isSyntheticPageTarget(session, targetInfo.targetId, targetInfo.type)) {
+            return;
+        }
+        const resolvedTabId = parseTabTargetId(targetInfo.targetId) ?? event.tabId;
+        const synthetic = this.sessions.upsertSyntheticTarget(session.id, {
+            targetId: targetInfo.targetId,
+            tabId: resolvedTabId,
+            type: targetInfo.type,
+            ...(typeof targetInfo.url === "string" ? { url: targetInfo.url } : {}),
+            ...(typeof targetInfo.title === "string" ? { title: targetInfo.title } : {}),
+            ...(childSessionId ? { sessionId: childSessionId } : {}),
+            ...(typeof targetInfo.openerId === "string" ? { openerTargetId: targetInfo.openerId } : {}),
+            attachedAt: Date.now()
+        });
+        if (!session.activeTargetId
+            || session.activeTargetId === session.targetId
+            || session.activeTargetId === synthetic.openerTargetId) {
+            session.activeTargetId = synthetic.targetId;
+        }
+    }
+    handleSyntheticTargetDestroyed(session, event) {
+        const payload = isRecord(event.params) ? event.params : null;
+        const targetId = payload && typeof payload.targetId === "string" ? payload.targetId : null;
+        if (!targetId) {
+            return;
+        }
+        const removed = this.sessions.removeSyntheticTarget(session.id, targetId);
+        if (!removed) {
+            return;
+        }
+        this.restoreSyntheticFallbackTarget(session, removed);
+    }
+    handleSyntheticTargetDetached(session, event) {
+        const payload = isRecord(event.params) ? event.params : null;
+        const targetId = payload && typeof payload.targetId === "string" ? payload.targetId : null;
+        const sessionId = payload && typeof payload.sessionId === "string" ? payload.sessionId : null;
+        const removed = targetId
+            ? this.sessions.removeSyntheticTarget(session.id, targetId)
+            : (sessionId ? this.sessions.findSyntheticTargetBySessionId(session.id, sessionId) : null);
+        if (!removed) {
+            return;
+        }
+        if (!targetId && sessionId) {
+            this.sessions.removeSyntheticTarget(session.id, removed.targetId);
+        }
+        this.restoreSyntheticFallbackTarget(session, removed);
+    }
+    restoreSyntheticFallbackTarget(session, removed) {
+        if (session.activeTargetId !== removed.targetId) {
+            return;
+        }
+        if (removed.openerTargetId && this.hasOpsTarget(session, removed.openerTargetId)) {
+            session.activeTargetId = removed.openerTargetId;
+            return;
+        }
+        const firstSynthetic = this.sessions.listSyntheticTargets(session.id)[0];
+        session.activeTargetId = firstSynthetic?.targetId ?? session.targetId;
+    }
     async handleRequest(message) {
         const clientId = message.clientId;
         if (!clientId) {
@@ -284,6 +808,9 @@ export class OpsRuntime {
             case "nav.snapshot":
                 await this.withSession(message, clientId, (session) => this.handleSnapshot(message, session));
                 return;
+            case "nav.review":
+                await this.withSession(message, clientId, (session) => this.handleReview(message, session));
+                return;
             case "interact.click":
                 await this.withSession(message, clientId, (session) => this.handleClick(message, session));
                 return;
@@ -311,6 +838,21 @@ export class OpsRuntime {
             case "interact.scrollIntoView":
                 await this.withSession(message, clientId, (session) => this.handleScrollIntoView(message, session));
                 return;
+            case "interact.upload":
+                await this.withSession(message, clientId, (session) => this.handleUpload(message, session));
+                return;
+            case "pointer.move":
+                await this.withSession(message, clientId, (session) => this.handlePointerMove(message, session));
+                return;
+            case "pointer.down":
+                await this.withSession(message, clientId, (session) => this.handlePointerDown(message, session));
+                return;
+            case "pointer.up":
+                await this.withSession(message, clientId, (session) => this.handlePointerUp(message, session));
+                return;
+            case "pointer.drag":
+                await this.withSession(message, clientId, (session) => this.handlePointerDrag(message, session));
+                return;
             case "dom.getHtml":
                 await this.withSession(message, clientId, (session) => this.handleDomGetHtml(message, session));
                 return;
@@ -332,6 +874,21 @@ export class OpsRuntime {
             case "dom.isChecked":
                 await this.withSession(message, clientId, (session) => this.handleDomIsChecked(message, session));
                 return;
+            case "dom.refPoint":
+                await this.withSession(message, clientId, (session) => this.handleDomRefPoint(message, session));
+                return;
+            case "canvas.overlay.mount":
+                await this.withSession(message, clientId, (session) => this.handleCanvasOverlayMount(message, session));
+                return;
+            case "canvas.overlay.unmount":
+                await this.withSession(message, clientId, (session) => this.handleCanvasOverlayUnmount(message, session));
+                return;
+            case "canvas.overlay.select":
+                await this.withSession(message, clientId, (session) => this.handleCanvasOverlaySelect(message, session));
+                return;
+            case "canvas.overlay.sync":
+                await this.withSession(message, clientId, (session) => this.handleCanvasOverlaySync(message, session));
+                return;
             case "canvas.applyRuntimePreviewBridge":
                 await this.withSession(message, clientId, (session) => this.handleCanvasRuntimePreviewBridge(message, session));
                 return;
@@ -347,6 +904,9 @@ export class OpsRuntime {
             case "page.screenshot":
                 await this.withSession(message, clientId, (session) => this.handleScreenshot(message, session));
                 return;
+            case "page.dialog":
+                await this.withSession(message, clientId, (session) => this.handleDialog(message, session));
+                return;
             case "devtools.consolePoll":
                 await this.withSession(message, clientId, (session) => this.handleConsolePoll(message, session));
                 return;
@@ -361,6 +921,13 @@ export class OpsRuntime {
         const payload = isRecord(message.payload) ? message.payload : {};
         const parallelismPolicy = parseParallelismPolicy(payload.parallelismPolicy);
         const startUrl = typeof payload.startUrl === "string" ? payload.startUrl : undefined;
+        const isStartUrlConnect = message.command === "session.connect" && typeof startUrl === "string";
+        const requestedSessionId = typeof payload.sessionId === "string" && payload.sessionId.trim().length > 0
+            ? payload.sessionId.trim()
+            : undefined;
+        const requestedTabId = typeof payload.tabId === "number" && Number.isInteger(payload.tabId)
+            ? payload.tabId
+            : undefined;
         if (startUrl) {
             try {
                 const restriction = getRestrictionMessage(new URL(startUrl));
@@ -374,15 +941,31 @@ export class OpsRuntime {
                 return;
             }
         }
-        const activeTab = startUrl
+        let activeTab = startUrl
             ? await this.tabs.createTab(startUrl, true)
-            : await this.tabs.getActiveTab();
+            : typeof requestedTabId === "number"
+                ? await this.tabs.getTab(requestedTabId)
+                : await this.tabs.getActiveTab();
+        if (!startUrl && typeof requestedTabId !== "number") {
+            const currentRawUrl = activeTab?.url ?? activeTab?.pendingUrl ?? "";
+            const needsFallback = !activeTab
+                || typeof activeTab.id !== "number"
+                || currentRawUrl.length === 0
+                || isRestrictedUrl(currentRawUrl).restricted;
+            if (needsFallback) {
+                activeTab = await this.tabs.getFirstAttachableTab(typeof activeTab?.id === "number" ? activeTab.id : undefined) ?? activeTab;
+            }
+        }
         if (!activeTab || typeof activeTab.id !== "number") {
+            if (typeof requestedTabId === "number") {
+                this.sendError(message, buildError("invalid_request", `Unknown tabId: ${requestedTabId}`, false));
+                return;
+            }
             this.sendError(message, buildError("ops_unavailable", "No active tab to attach.", true));
             return;
         }
         const activeTabId = activeTab.id;
-        const resolvedTab = startUrl
+        let resolvedTab = startUrl
             ? await this.tabs.waitForTabComplete(activeTabId)
                 .catch(() => undefined)
                 .then(async () => await this.tabs.getTab(activeTabId) ?? activeTab)
@@ -395,16 +978,29 @@ export class OpsRuntime {
             }
         }
         try {
-            await this.cdp.attach(activeTabId);
+            const refreshedTab = isStartUrlConnect
+                ? await this.attachStartUrlConnectTab(activeTabId)
+                : await this.attachLaunchTargetTab(activeTabId, false);
+            if (refreshedTab) {
+                resolvedTab = refreshedTab;
+            }
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : "Debugger attach failed";
-            this.sendError(message, buildError("cdp_attach_failed", detail, false));
+            this.sendError(message, buildError("cdp_attach_failed", detail, false, this.getDirectAttachErrorDetails(error)));
             return;
         }
         if (!startUrl) {
             await this.tabs.waitForTabComplete(activeTab.id).catch(() => undefined);
         }
+        try {
+            await this.enableTargetDomains(activeTabId, true);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : "Debugger attach failed";
+            this.sendError(message, buildError("cdp_attach_failed", detail, false, this.getDirectAttachErrorDetails(error)));
+            return;
+        }
         const leaseId = typeof message.leaseId === "string" && message.leaseId.trim().length > 0
             ? message.leaseId.trim()
             : createId();
@@ -413,15 +1009,8 @@ export class OpsRuntime {
             title: resolvedTab.title ?? undefined
         }, {
             parallelismPolicy
-        });
-        await this.enableSessionDomains(session);
-        this.sendEvent({
-            type: "ops_event",
-            clientId,
-            opsSessionId: session.id,
-            event: "ops_session_created",
-            payload: { tabId: session.tabId, targetId: session.targetId }
-        });
+        }, requestedSessionId);
+        this.emitSessionEvent(session, "ops_session_created");
         this.sendResponse(message, {
             opsSessionId: session.id,
             activeTargetId: session.activeTargetId,
@@ -441,12 +1030,18 @@ export class OpsRuntime {
         const session = this.getSessionForMessage(message, clientId);
         if (!session)
             return;
-        const tab = await this.tabs.getTab(session.tabId);
+        const activeTargetId = session.activeTargetId ?? session.targetId;
+        const reportedTarget = activeTargetId
+            ? this.resolveRequestedTargetContext(session, activeTargetId, false)
+            : null;
+        const reportedTargetId = reportedTarget?.targetId ?? null;
+        const tab = reportedTarget ? await this.tabs.getTab(reportedTarget.tabId) : null;
         this.sendResponse(message, {
             mode: "extension",
-            activeTargetId: session.activeTargetId || null,
-            url: tab?.url ?? undefined,
-            title: tab?.title ?? undefined,
+            activeTargetId: reportedTargetId,
+            url: resolveReportedTargetUrl(reportedTarget, tab),
+            title: resolveReportedTargetTitle(reportedTarget, tab),
+            dialog: this.serializeDialogState(session, reportedTargetId),
             leaseId: session.leaseId,
             state: session.state
         });
@@ -454,14 +1049,26 @@ export class OpsRuntime {
     async handleTargetsList(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
         const includeUrls = payload.includeUrls === true;
-        const targets = await Promise.all(Array.from(session.targets.values()).map(async (target) => {
-            const tab = await this.tabs.getTab(target.tabId);
-            const synthetic = session.syntheticTargets.get(target.targetId);
-            return {
+        const targetContexts = [
+            ...Array.from(session.targets.values()).map((target) => ({
                 targetId: target.targetId,
+                tabId: target.tabId
+            })),
+            ...this.sessions.listSyntheticTargets(session.id)
+                .filter((target) => !session.targets.has(target.targetId))
+                .map((target) => ({
+                targetId: target.targetId,
+                tabId: target.tabId
+            }))
+        ];
+        const targets = await Promise.all(targetContexts.map(async ({ targetId, tabId }) => {
+            const target = this.resolveTargetContext(session, targetId);
+            const tab = await this.tabs.getTab(tabId);
+            return {
+                targetId,
                 type: "page",
-                title: resolveReportedTargetTitle(target, tab?.title, synthetic),
-                url: includeUrls ? resolveReportedTargetUrl(target, tab?.url, synthetic) : undefined
+                title: resolveReportedTargetTitle(target, tab),
+                url: includeUrls ? resolveReportedTargetUrl(target, tab) : undefined
             };
         }));
         this.sendResponse(message, { activeTargetId: session.activeTargetId || null, targets });
@@ -469,22 +1076,125 @@ export class OpsRuntime {
     async handleTargetsUse(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
         const targetId = typeof payload.targetId === "string" ? payload.targetId : null;
-        if (!targetId || !session.targets.has(targetId)) {
+        if (!targetId || !this.hasOpsTarget(session, targetId)) {
             this.sendError(message, buildError("invalid_request", "Unknown targetId", false));
             return;
         }
-        session.activeTargetId = targetId;
-        const target = session.targets.get(targetId) ?? null;
-        if (target) {
-            await this.tabs.activateTab(target.tabId).catch(() => undefined);
+        let target = this.rehydrateSyntheticPopupBridge(session, targetId) ?? this.resolveTargetContext(session, targetId);
+        if (target && !this.hasUsableDebuggee(target) && (target.synthetic || !!target.openerTargetId)) {
+            try {
+                target = await this.preparePopupTarget(session, targetId) ?? target;
+                target = this.rehydrateSyntheticPopupBridge(session, targetId) ?? target;
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : "Debugger attach failed";
+                this.sendError(message, buildError("cdp_attach_failed", detail, false, this.getDirectAttachErrorDetails(error)));
+                return;
+            }
         }
-        const tab = target ? await this.tabs.getTab(target.tabId) : null;
-        const synthetic = target ? session.syntheticTargets.get(target.targetId) : undefined;
-        this.sendResponse(message, {
-            activeTargetId: targetId,
-            url: target ? resolveReportedTargetUrl(target, tab?.url, synthetic) : undefined,
-            title: target ? resolveReportedTargetTitle(target, tab?.title, synthetic) : undefined
-        });
+        if (target?.synthetic && !target.sessionId) {
+            const syntheticPopupTarget = target.openerTargetId
+                ? {
+                    targetId,
+                    tabId: target.tabId,
+                    ...(typeof target.url === "string" ? { url: target.url } : {}),
+                    ...(typeof target.title === "string" ? { title: target.title } : {}),
+                    openerTargetId: target.openerTargetId
+                }
+                : null;
+            if (syntheticPopupTarget && await this.attachTargetViaOpenerSession(session, syntheticPopupTarget).catch(() => false)) {
+                this.clearPopupAttachDiagnostic(session.id, targetId);
+                await this.activateTargetAndRespond(message, session, targetId);
+                return;
+            }
+            this.sendPopupAttachPendingError(message, session, targetId);
+            return;
+        }
+        if (target && !target.synthetic) {
+            const targetHasUsableDebuggee = this.hasUsableDebuggee(target);
+            const hydratedPopupTarget = !targetHasUsableDebuggee
+                ? await this.hydratePopupOpenerTarget(session, targetId)
+                : null;
+            const popupTarget = hydratedPopupTarget?.openerTargetId
+                ? hydratedPopupTarget
+                : target.openerTargetId
+                    ? {
+                        targetId,
+                        tabId: target.tabId,
+                        ...(typeof target.url === "string" ? { url: target.url } : {}),
+                        ...(typeof target.title === "string" ? { title: target.title } : {}),
+                        openerTargetId: target.openerTargetId
+                    }
+                    : null;
+            if (popupTarget?.openerTargetId) {
+                const resolvedPopupTarget = this.resolveTargetContext(session, targetId);
+                if (resolvedPopupTarget && this.hasUsableDebuggee(resolvedPopupTarget)) {
+                    this.clearPopupAttachDiagnostic(session.id, targetId);
+                    await this.activateTargetAndRespond(message, session, targetId);
+                    return;
+                }
+            }
+            const deferPopupActivation = Boolean(popupTarget?.openerTargetId && !targetHasUsableDebuggee);
+            if (!deferPopupActivation) {
+                await this.tabs.activateTab(target.tabId).catch(() => undefined);
+            }
+            if (!targetHasUsableDebuggee) {
+                if (popupTarget?.openerTargetId && await this.attachTargetViaOpenerSession(session, popupTarget).catch(() => false)) {
+                    this.clearPopupAttachDiagnostic(session.id, targetId);
+                    await this.activateTargetAndRespond(message, session, targetId);
+                    return;
+                }
+                if (popupTarget?.openerTargetId) {
+                    const resolvedPopupTarget = this.resolveTargetContext(session, targetId);
+                    if (resolvedPopupTarget && this.hasUsableDebuggee(resolvedPopupTarget)) {
+                        this.clearPopupAttachDiagnostic(session.id, targetId);
+                        await this.activateTargetAndRespond(message, session, targetId);
+                        return;
+                    }
+                    if (this.shouldPreferDirectPopupTabAttach(popupTarget)) {
+                        try {
+                            await this.attachTargetTab(target.tabId);
+                            await this.enableTargetDomains(target.tabId, true);
+                            this.clearPopupAttachDiagnostic(session.id, targetId);
+                            await this.activateTargetAndRespond(message, session, targetId);
+                            return;
+                        }
+                        catch (error) {
+                            if (!isAttachBlockedError(error)) {
+                                const detail = error instanceof Error ? error.message : "Debugger attach failed";
+                                this.sendError(message, buildError("cdp_attach_failed", detail, false, this.getDirectAttachErrorDetails(error)));
+                                return;
+                            }
+                        }
+                    }
+                    this.sendPopupAttachPendingError(message, session, targetId);
+                    return;
+                }
+                try {
+                    await this.attachTargetTab(target.tabId);
+                    await this.enableTargetDomains(target.tabId, true);
+                    this.clearPopupAttachDiagnostic(session.id, targetId);
+                }
+                catch (error) {
+                    if (isAttachBlockedError(error) && popupTarget && await this.attachTargetViaOpenerSession(session, popupTarget).catch(() => false)) {
+                        session.activeTargetId = targetId;
+                        this.clearPopupAttachDiagnostic(session.id, targetId);
+                        await this.tabs.activateTab(target.tabId).catch(() => undefined);
+                        const tab = await this.tabs.getTab(target.tabId);
+                        this.sendResponse(message, {
+                            activeTargetId: targetId,
+                            url: resolveReportedTargetUrl(this.resolveTargetContext(session, targetId), tab),
+                            title: resolveReportedTargetTitle(this.resolveTargetContext(session, targetId), tab)
+                        });
+                        return;
+                    }
+                    const detail = error instanceof Error ? error.message : "Debugger attach failed";
+                    this.sendError(message, buildError("cdp_attach_failed", detail, false, this.getDirectAttachErrorDetails(error)));
+                    return;
+                }
+            }
+        }
+        await this.activateTargetAndRespond(message, session, targetId);
     }
     async handleTargetsRegisterCanvas(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
@@ -493,37 +1203,59 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing targetId", false));
             return;
         }
+        try {
+            this.sendResponse(message, await this.registerCanvasTarget(session, targetId));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : "Canvas target registration failed";
+            if (detail === "Canvas targetId must be tab-<id>.") {
+                this.sendError(message, buildError("invalid_request", detail, false));
+                return;
+            }
+            if (detail === "Unknown targetId") {
+                this.sendError(message, buildError("invalid_request", detail, false));
+                return;
+            }
+            if (detail === "Only the extension canvas tab can be registered.") {
+                this.sendError(message, buildError("restricted_url", detail, false));
+                return;
+            }
+            logError("ops.register_canvas_target", error, {
+                code: "canvas_target_attach_failed",
+                extra: { targetId }
+            });
+            this.sendError(message, buildError("execution_failed", detail, false));
+            return;
+        }
+    }
+    async registerCanvasTarget(session, targetId) {
         const tabId = parseTabTargetId(targetId);
         if (tabId === null) {
-            this.sendError(message, buildError("invalid_request", "Canvas targetId must be tab-<id>.", false));
-            return;
+            throw new Error("Canvas targetId must be tab-<id>.");
         }
         let tab = await this.tabs.getTab(tabId);
         if (!tab) {
-            this.sendError(message, buildError("invalid_request", "Unknown targetId", false));
-            return;
+            throw new Error("Unknown targetId");
         }
         await this.tabs.waitForTabComplete(tabId, 5000).catch(() => undefined);
         tab = await this.tabs.getTab(tabId) ?? tab;
         if (!this.isAllowedCanvasTargetUrl(tab.url)) {
-            this.sendError(message, buildError("restricted_url", "Only the extension canvas tab can be registered.", false));
-            return;
+            throw new Error("Only the extension canvas tab can be registered.");
         }
         const existing = session.targets.get(targetId);
         if (existing) {
             existing.url = tab.url ?? existing.url;
             existing.title = tab.title ?? existing.title;
             session.activeTargetId = targetId;
-            this.sendResponse(message, {
+            return {
                 targetId,
                 url: existing.url,
                 title: existing.title,
                 adopted: false
-            });
-            return;
+            };
         }
         try {
-            await this.cdp.attach(tabId);
+            await this.attachTargetTab(tabId);
             await this.enableTargetDomains(tabId);
         }
         catch (error) {
@@ -534,33 +1266,43 @@ export class OpsRuntime {
         }
         const target = this.sessions.addTarget(session.id, tabId, { url: tab.url ?? undefined, title: tab.title ?? undefined });
         session.activeTargetId = target.targetId;
-        this.sendResponse(message, {
+        return {
             targetId: target.targetId,
             url: target.url,
             title: target.title,
             adopted: true
-        });
+        };
     }
     async handleTargetsNew(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
         const url = typeof payload.url === "string" ? payload.url : undefined;
-        const tab = await this.tabs.createTab(url, true);
+        const tab = await this.tabs.createTab(url, false);
         if (!tab?.id) {
             this.sendError(message, buildError("execution_failed", "Target creation failed", false));
             return;
         }
-        await this.tabs.waitForTabComplete(tab.id).catch(() => undefined);
+        this.rememberCommandCreatedTab(session.id, tab.id, "targets.new");
         try {
-            await this.cdp.attach(tab.id);
+            const existingTarget = await this.claimCommandCreatedTab(session, tab);
+            try {
+                if (!this.hasAttachedTabDebuggee(tab.id)) {
+                    await this.attachCreatedTargetTab(tab.id);
+                }
+                await this.enableTargetDomains(tab.id, true);
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : "Debugger attach failed";
+                this.sendError(message, buildError("cdp_attach_failed", detail, false, this.getDirectAttachErrorDetails(error)));
+                return;
+            }
+            const target = existingTarget ?? this.sessions.addTarget(session.id, tab.id, await this.getCreatedTabSeed(tab));
+            session.activeTargetId = target.targetId;
+            await this.activateCreatedTab(tab.id);
+            this.sendResponse(message, { targetId: target.targetId });
         }
-        catch (error) {
-            const detail = error instanceof Error ? error.message : "Debugger attach failed";
-            this.sendError(message, buildError("cdp_attach_failed", detail, false));
-            return;
+        finally {
+            this.forgetCommandCreatedTab(tab.id);
         }
-        const target = this.sessions.addTarget(session.id, tab.id, { url: tab.url ?? undefined, title: tab.title ?? undefined });
-        session.activeTargetId = target.targetId;
-        this.sendResponse(message, { targetId: target.targetId });
     }
     async handleTargetsClose(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
@@ -569,13 +1311,27 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing targetId", false));
             return;
         }
-        const target = session.targets.get(targetId);
+        const target = session.targets.get(targetId) ?? null;
+        const synthetic = this.sessions.getSyntheticTarget(session.id, targetId);
+        if (!target && !synthetic) {
+            this.sendError(message, buildError("invalid_request", "Unknown targetId", false));
+            return;
+        }
+        if (synthetic) {
+            this.sessions.removeSyntheticTarget(session.id, targetId);
+            await this.cdp.sendCommand(synthetic.sessionId ? { tabId: synthetic.tabId, sessionId: synthetic.sessionId } : { tabId: synthetic.tabId }, "Target.closeTarget", {
+                targetId: synthetic.targetId
+            }).catch(() => undefined);
+            this.restoreSyntheticFallbackTarget(session, synthetic);
+            this.sendResponse(message, { ok: true });
+            return;
+        }
         if (!target) {
             this.sendError(message, buildError("invalid_request", "Unknown targetId", false));
             return;
         }
         this.sessions.removeTarget(session.id, targetId);
-        await this.closeTabBestEffort(target.tabId);
+        void this.closeTabBestEffort(target.tabId);
         if (target.targetId === session.targetId || session.targets.size === 0) {
             this.sendResponse(message, { ok: true });
             this.scheduleSessionCleanup(session.id, "ops_session_closed");
@@ -597,35 +1353,44 @@ export class OpsRuntime {
             return;
         }
         const url = typeof payload.url === "string" ? payload.url : undefined;
-        const tab = await this.tabs.createTab(url, true);
+        const tab = await this.tabs.createTab(url, false);
         if (!tab?.id) {
             this.sendError(message, buildError("execution_failed", "Target creation failed", false));
             return;
         }
-        await this.tabs.waitForTabComplete(tab.id).catch(() => undefined);
+        this.rememberCommandCreatedTab(session.id, tab.id, "page.open");
         try {
-            await this.cdp.attach(tab.id);
+            const existingTarget = await this.claimCommandCreatedTab(session, tab);
+            try {
+                if (!this.hasAttachedTabDebuggee(tab.id)) {
+                    await this.attachCreatedTargetTab(tab.id);
+                }
+                await this.enableTargetDomains(tab.id, true);
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : "Debugger attach failed";
+                this.sendError(message, buildError("cdp_attach_failed", detail, false, this.getDirectAttachErrorDetails(error)));
+                return;
+            }
+            const target = existingTarget ?? this.sessions.addTarget(session.id, tab.id, await this.getCreatedTabSeed(tab));
+            this.sessions.setName(session.id, target.targetId, name);
+            session.activeTargetId = target.targetId;
+            await this.activateCreatedTab(tab.id);
+            this.sendResponse(message, { targetId: target.targetId, created: true, url: target.url, title: target.title });
         }
-        catch (error) {
-            const detail = error instanceof Error ? error.message : "Debugger attach failed";
-            this.sendError(message, buildError("cdp_attach_failed", detail, false));
-            return;
+        finally {
+            this.forgetCommandCreatedTab(tab.id);
         }
-        const target = this.sessions.addTarget(session.id, tab.id, { url: tab.url ?? undefined, title: tab.title ?? undefined });
-        this.sessions.setName(session.id, target.targetId, name);
-        session.activeTargetId = target.targetId;
-        this.sendResponse(message, { targetId: target.targetId, created: true, url: target.url, title: target.title });
     }
     async handlePageList(message, session) {
         const pages = await Promise.all(this.sessions.listNamedTargets(session.id).map(async ({ name, targetId }) => {
-            const target = session.targets.get(targetId);
+            const target = this.resolveTargetContext(session, targetId);
             const tab = target ? await this.tabs.getTab(target.tabId) : null;
-            const synthetic = session.syntheticTargets.get(targetId);
             return {
                 name,
                 targetId,
-                url: resolveReportedTargetUrl(target, tab?.url, synthetic),
-                title: resolveReportedTargetTitle(target, tab?.title, synthetic)
+                url: resolveReportedTargetUrl(target, tab),
+                title: resolveReportedTargetTitle(target, tab)
             };
         }));
         this.sendResponse(message, { pages });
@@ -645,7 +1410,7 @@ export class OpsRuntime {
         const target = session.targets.get(targetId);
         if (target) {
             this.sessions.removeTarget(session.id, targetId);
-            await this.closeTabBestEffort(target.tabId);
+            void this.closeTabBestEffort(target.tabId);
             if (target.targetId === session.targetId || session.targets.size === 0) {
                 this.sendResponse(message, { ok: true });
                 this.scheduleSessionCleanup(session.id, "ops_session_closed");
@@ -661,11 +1426,14 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing url", false));
             return;
         }
+        const syntheticHtml = decodeHtmlDataUrl(url);
         try {
-            const restriction = getRestrictionMessage(new URL(url));
-            if (restriction) {
-                this.sendError(message, buildError("restricted_url", restriction, false));
-                return;
+            if (syntheticHtml === null) {
+                const restriction = getRestrictionMessage(new URL(url));
+                if (restriction) {
+                    this.sendError(message, buildError("restricted_url", restriction, false));
+                    return;
+                }
             }
         }
         catch {
@@ -679,15 +1447,18 @@ export class OpsRuntime {
             return;
         await this.tabs.activateTab(target.tabId).catch(() => undefined);
         const targetRecord = session.targets.get(target.targetId);
-        const syntheticHtml = decodeHtmlDataUrl(url);
         if (syntheticHtml !== null) {
             const result = await executeInTab(target.tabId, replaceDocumentWithHtmlScript, [{ html: syntheticHtml }]);
             session.refStore.clearTarget(target.targetId);
-            session.syntheticTargets.set(target.targetId, {
+            this.sessions.upsertSyntheticTarget(session.id, {
+                targetId: target.targetId,
+                tabId: target.tabId,
+                type: "page",
                 url,
                 title: typeof result?.title === "string" && result.title.trim().length > 0
                     ? result.title
-                    : targetRecord?.title
+                    : targetRecord?.title,
+                attachedAt: Date.now()
             });
             this.sendResponse(message, {
                 finalUrl: url,
@@ -703,7 +1474,7 @@ export class OpsRuntime {
         });
         await this.tabs.waitForTabComplete(target.tabId, timeoutMs).catch(() => undefined);
         const refreshed = await this.tabs.getTab(target.tabId);
-        session.syntheticTargets.delete(target.targetId);
+        this.sessions.removeSyntheticTarget(session.id, target.targetId);
         if (targetRecord) {
             session.targets.set(target.targetId, {
                 ...targetRecord,
@@ -726,11 +1497,16 @@ export class OpsRuntime {
             return;
         if (typeof payload.ref === "string") {
             const state = payload.state === "visible" || payload.state === "hidden" ? payload.state : "attached";
-            const selector = this.resolveSelector(session, payload.ref, message);
-            if (!selector)
+            const resolved = this.resolveRefFromPayload(session, payload.ref, message);
+            if (!resolved)
                 return;
             try {
-                await this.waitForSelector(target, selector, state, timeoutMs);
+                if (this.isAllowedCanvasTargetUrl(target.url)) {
+                    await this.waitForSelector(target, resolved.selector, state, timeoutMs);
+                }
+                else {
+                    await this.waitForRefState(resolved, state, timeoutMs);
+                }
                 this.sendResponse(message, { timingMs: Date.now() - start });
             }
             catch (error) {
@@ -748,64 +1524,90 @@ export class OpsRuntime {
     }
     async handleSnapshot(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
-        const mode = payload.mode === "actionables" ? "actionables" : "outline";
-        const maxChars = typeof payload.maxChars === "number" ? payload.maxChars : 16000;
-        const cursor = typeof payload.cursor === "string" ? payload.cursor : undefined;
-        const maxNodes = typeof payload.maxNodes === "number" ? payload.maxNodes : undefined;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const snapshot = await this.captureSnapshotPayload(message, session, {
+            mode: payload.mode === "actionables" ? "actionables" : "outline",
+            maxChars: typeof payload.maxChars === "number" ? payload.maxChars : 16000,
+            cursor: typeof payload.cursor === "string" ? payload.cursor : undefined,
+            maxNodes: typeof payload.maxNodes === "number" ? payload.maxNodes : undefined
+        });
+        if (!snapshot)
             return;
-        const start = Date.now();
-        const entriesData = await buildSnapshot((method, params) => this.cdp.sendCommand({ tabId: target.tabId }, method, params), mode, true, maxNodes);
-        const snapshot = session.refStore.setSnapshot(target.targetId, entriesData.entries);
-        const startIndex = parseCursor(cursor);
-        const { content, truncated, nextCursor } = paginate(entriesData.lines, startIndex, maxChars);
-        const contentBytes = this.encoder.encode(content).length;
-        if (contentBytes > MAX_SNAPSHOT_BYTES) {
-            this.sendError(message, buildError("snapshot_too_large", "Snapshot exceeded max size.", false, {
-                maxSnapshotBytes: MAX_SNAPSHOT_BYTES,
-                actualBytes: contentBytes
-            }));
+        this.sendResponse(message, {
+            snapshotId: snapshot.snapshotId,
+            url: snapshot.url,
+            title: snapshot.title,
+            content: snapshot.content,
+            truncated: snapshot.truncated,
+            ...(snapshot.nextCursor ? { nextCursor: snapshot.nextCursor } : {}),
+            refCount: snapshot.refCount,
+            timingMs: snapshot.timingMs,
+            warnings: snapshot.warnings
+        });
+    }
+    async handleReview(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const snapshot = await this.captureSnapshotPayload(message, session, {
+            mode: "actionables",
+            maxChars: typeof payload.maxChars === "number" ? payload.maxChars : 16000,
+            cursor: typeof payload.cursor === "string" ? payload.cursor : undefined,
+            maxNodes: typeof payload.maxNodes === "number" ? payload.maxNodes : undefined
+        });
+        if (!snapshot)
             return;
-        }
-        const tab = await this.tabs.getTab(target.tabId);
-        const targetRecord = session.targets.get(target.targetId);
-        const synthetic = session.syntheticTargets.get(target.targetId);
         this.sendResponse(message, {
+            sessionId: session.id,
+            targetId: snapshot.target.targetId,
+            mode: "extension",
             snapshotId: snapshot.snapshotId,
-            url: resolveReportedTargetUrl(targetRecord ?? null, tab?.url, synthetic),
-            title: resolveReportedTargetTitle(targetRecord ?? null, tab?.title, synthetic),
-            content,
-            truncated,
-            nextCursor,
-            refCount: snapshot.count,
-            timingMs: Date.now() - start,
-            warnings: entriesData.warnings
+            url: snapshot.url,
+            title: snapshot.title,
+            content: snapshot.content,
+            truncated: snapshot.truncated,
+            ...(snapshot.nextCursor ? { nextCursor: snapshot.nextCursor } : {}),
+            refCount: snapshot.refCount,
+            timingMs: snapshot.timingMs,
+            dialog: this.serializeDialogState(session, snapshot.target.targetId),
+            ...(snapshot.warnings.length > 0 ? { warnings: snapshot.warnings } : {})
         });
     }
     async handleClick(message, session) {
-        const selector = this.resolveSelector(session, message.payload, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, message.payload, message);
+        if (!resolved)
             return;
         const start = Date.now();
-        const before = await this.tabs.getTab(target.tabId);
-        await this.runElementAction(target, selector, { type: "click" }, () => this.dom.click(target.tabId, selector));
-        const after = await this.tabs.getTab(target.tabId);
+        const before = await this.tabs.getTab(resolved.target.tabId);
+        await this.tabs.activateTab(resolved.target.tabId).catch(() => undefined);
+        if (this.isAllowedCanvasTargetUrl(resolved.target.url)) {
+            await this.runElementAction(resolved.target, resolved.selector, { type: "click" }, () => this.dom.click(resolved.target.tabId, resolved.selector));
+        }
+        else {
+            await this.callFunctionOnRef(resolved, DOM_SCROLL_INTO_VIEW_DECLARATION);
+            const point = await this.resolveRefPoint(resolved);
+            await this.dispatchMouseEvent(resolved.target.debuggee, "mouseMoved", point.x, point.y);
+            await this.dispatchMouseEvent(resolved.target.debuggee, "mousePressed", point.x, point.y, {
+                button: "left",
+                clickCount: 1
+            });
+            await this.dispatchMouseEvent(resolved.target.debuggee, "mouseReleased", point.x, point.y, {
+                button: "left",
+                clickCount: 1
+            });
+        }
+        const after = await this.tabs.getTab(resolved.target.tabId);
         const navigated = Boolean(before?.url && after?.url && before.url !== after.url);
         this.sendResponse(message, { timingMs: Date.now() - start, navigated });
     }
     async handleHover(message, session) {
-        const selector = this.resolveSelector(session, message.payload, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, message.payload, message);
+        if (!resolved)
             return;
         const start = Date.now();
-        await this.runElementAction(target, selector, { type: "hover" }, () => this.dom.hover(target.tabId, selector));
+        if (this.isAllowedCanvasTargetUrl(resolved.target.url)) {
+            await this.runElementAction(resolved.target, resolved.selector, { type: "hover" }, () => this.dom.hover(resolved.target.tabId, resolved.selector));
+        }
+        else {
+            await this.callFunctionOnRef(resolved, DOM_HOVER_DECLARATION);
+        }
         this.sendResponse(message, { timingMs: Date.now() - start });
     }
     async handlePress(message, session) {
@@ -818,22 +1620,33 @@ export class OpsRuntime {
         const target = this.requireActiveTarget(session, message);
         if (!target)
             return;
-        const selector = typeof payload.ref === "string" ? this.resolveSelector(session, payload.ref, message) : null;
-        if (payload.ref && !selector)
+        const resolved = typeof payload.ref === "string" ? this.resolveRefFromPayload(session, payload.ref, message) : null;
+        if (payload.ref && !resolved)
             return;
         const start = Date.now();
-        await this.runCanvasPageAction(target, { type: "press", key }, selector, () => this.dom.press(target.tabId, selector, key));
+        if (resolved && this.isAllowedCanvasTargetUrl(target.url)) {
+            await this.runCanvasPageAction(target, { type: "press", key }, resolved.selector, () => this.dom.press(target.tabId, resolved.selector, key));
+        }
+        else if (resolved) {
+            await this.callFunctionOnRef(resolved, DOM_FOCUS_DECLARATION);
+            await this.dispatchKeyPress(target.debuggee, key);
+        }
+        else {
+            await this.dispatchKeyPress(target.debuggee, key);
+        }
         this.sendResponse(message, { timingMs: Date.now() - start });
     }
     async handleCheck(message, session, checked) {
-        const selector = this.resolveSelector(session, message.payload, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, message.payload, message);
+        if (!resolved)
             return;
         const start = Date.now();
-        await this.runElementAction(target, selector, { type: "setChecked", checked }, () => this.dom.setChecked(target.tabId, selector, checked));
+        if (this.isAllowedCanvasTargetUrl(resolved.target.url)) {
+            await this.runElementAction(resolved.target, resolved.selector, { type: "setChecked", checked }, () => this.dom.setChecked(resolved.target.tabId, resolved.selector, checked));
+        }
+        else {
+            await this.callFunctionOnRef(resolved, DOM_SET_CHECKED_DECLARATION, [checked]);
+        }
         this.sendResponse(message, { timingMs: Date.now() - start });
     }
     async handleType(message, session) {
@@ -844,14 +1657,16 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing ref or text", false));
             return;
         }
-        const selector = this.resolveSelector(session, ref, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, ref, message);
+        if (!resolved)
             return;
         const start = Date.now();
-        await this.runElementAction(target, selector, { type: "type", value: text, clear: payload.clear === true, submit: payload.submit === true }, () => this.dom.type(target.tabId, selector, text, payload.clear === true, payload.submit === true));
+        if (this.isAllowedCanvasTargetUrl(resolved.target.url)) {
+            await this.runElementAction(resolved.target, resolved.selector, { type: "type", value: text, clear: payload.clear === true, submit: payload.submit === true }, () => this.dom.type(resolved.target.tabId, resolved.selector, text, payload.clear === true, payload.submit === true));
+        }
+        else {
+            await this.callFunctionOnRef(resolved, DOM_TYPE_DECLARATION, [text, payload.clear === true, payload.submit === true]);
+        }
         this.sendResponse(message, { timingMs: Date.now() - start });
     }
     async handleSelect(message, session) {
@@ -862,37 +1677,126 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing ref or values", false));
             return;
         }
-        const selector = this.resolveSelector(session, ref, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, ref, message);
+        if (!resolved)
             return;
-        await this.runElementAction(target, selector, { type: "select", values: values }, () => this.dom.select(target.tabId, selector, values));
+        if (this.isAllowedCanvasTargetUrl(resolved.target.url)) {
+            await this.runElementAction(resolved.target, resolved.selector, { type: "select", values: values }, () => this.dom.select(resolved.target.tabId, resolved.selector, values));
+        }
+        else {
+            await this.callFunctionOnRef(resolved, DOM_SELECT_DECLARATION, [values]);
+        }
         this.sendResponse(message, {});
     }
     async handleScroll(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
         const dy = typeof payload.dy === "number" ? payload.dy : 0;
         const ref = typeof payload.ref === "string" ? payload.ref : undefined;
-        const selector = ref ? this.resolveSelector(session, ref, message) ?? undefined : undefined;
-        if (ref && !selector)
-            return;
         const target = this.requireActiveTarget(session, message);
         if (!target)
             return;
-        await this.runCanvasPageAction(target, { type: "scroll", dy }, selector ?? null, () => this.dom.scroll(target.tabId, dy, selector));
+        const resolved = ref ? this.resolveRefFromPayload(session, ref, message) : null;
+        if (ref && !resolved)
+            return;
+        if (resolved && !this.isAllowedCanvasTargetUrl(target.url)) {
+            await this.callFunctionOnRef(resolved, DOM_SCROLL_BY_DECLARATION, [dy]);
+        }
+        else {
+            const selector = resolved?.selector;
+            await this.runCanvasPageAction(target, { type: "scroll", dy }, selector ?? null, () => this.dom.scroll(target.tabId, dy, selector));
+        }
         this.sendResponse(message, {});
     }
     async handleScrollIntoView(message, session) {
-        const selector = this.resolveSelector(session, message.payload, message);
-        if (!selector)
+        const resolved = this.resolveRefFromPayload(session, message.payload, message);
+        if (!resolved)
+            return;
+        const start = Date.now();
+        if (this.isAllowedCanvasTargetUrl(resolved.target.url)) {
+            await this.runElementAction(resolved.target, resolved.selector, { type: "scrollIntoView" }, () => this.dom.scrollIntoView(resolved.target.tabId, resolved.selector));
+        }
+        else {
+            await this.callFunctionOnRef(resolved, DOM_SCROLL_INTO_VIEW_DECLARATION);
+        }
+        this.sendResponse(message, { timingMs: Date.now() - start });
+    }
+    async handlePointerMove(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const coords = this.parsePointerCoords(payload);
+        if (!coords) {
+            this.sendError(message, buildError("invalid_request", "Pointer move requires numeric x and y.", false));
+            return;
+        }
+        const target = this.requireActiveTarget(session, message);
+        if (!target)
+            return;
+        const start = Date.now();
+        await this.dispatchMouseEvent(target.debuggee, "mouseMoved", coords.x, coords.y, {
+            steps: typeof payload.steps === "number" && Number.isFinite(payload.steps)
+                ? Math.max(1, Math.floor(payload.steps))
+                : undefined
+        });
+        this.sendResponse(message, { timingMs: Date.now() - start });
+    }
+    async handlePointerDown(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const coords = this.parsePointerCoords(payload);
+        if (!coords) {
+            this.sendError(message, buildError("invalid_request", "Pointer down requires numeric x and y.", false));
+            return;
+        }
+        const target = this.requireActiveTarget(session, message);
+        if (!target)
+            return;
+        const start = Date.now();
+        await this.dispatchMouseEvent(target.debuggee, "mouseMoved", coords.x, coords.y);
+        await this.dispatchMouseEvent(target.debuggee, "mousePressed", coords.x, coords.y, {
+            button: this.parsePointerButton(payload.button),
+            clickCount: typeof payload.clickCount === "number" && Number.isFinite(payload.clickCount)
+                ? Math.max(1, Math.floor(payload.clickCount))
+                : 1
+        });
+        this.sendResponse(message, { timingMs: Date.now() - start });
+    }
+    async handlePointerUp(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const coords = this.parsePointerCoords(payload);
+        if (!coords) {
+            this.sendError(message, buildError("invalid_request", "Pointer up requires numeric x and y.", false));
+            return;
+        }
+        const target = this.requireActiveTarget(session, message);
+        if (!target)
+            return;
+        const start = Date.now();
+        await this.dispatchMouseEvent(target.debuggee, "mouseMoved", coords.x, coords.y);
+        await this.dispatchMouseEvent(target.debuggee, "mouseReleased", coords.x, coords.y, {
+            button: this.parsePointerButton(payload.button),
+            clickCount: typeof payload.clickCount === "number" && Number.isFinite(payload.clickCount)
+                ? Math.max(1, Math.floor(payload.clickCount))
+                : 1
+        });
+        this.sendResponse(message, { timingMs: Date.now() - start });
+    }
+    async handlePointerDrag(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const from = isRecord(payload.from) ? this.parsePointerCoords(payload.from) : null;
+        const to = isRecord(payload.to) ? this.parsePointerCoords(payload.to) : null;
+        if (!from || !to) {
+            this.sendError(message, buildError("invalid_request", "Pointer drag requires numeric from/to coordinates.", false));
             return;
+        }
         const target = this.requireActiveTarget(session, message);
         if (!target)
             return;
         const start = Date.now();
-        await this.runElementAction(target, selector, { type: "scrollIntoView" }, () => this.dom.scrollIntoView(target.tabId, selector));
+        const steps = typeof payload.steps === "number" && Number.isFinite(payload.steps)
+            ? Math.max(1, Math.floor(payload.steps))
+            : 1;
+        await this.dispatchMouseEvent(target.debuggee, "mouseMoved", from.x, from.y);
+        await this.dispatchMouseEvent(target.debuggee, "mousePressed", from.x, from.y);
+        await this.dispatchMouseEvent(target.debuggee, "mouseMoved", to.x, to.y, { steps });
+        await this.dispatchMouseEvent(target.debuggee, "mouseReleased", to.x, to.y);
         this.sendResponse(message, { timingMs: Date.now() - start });
     }
     async handleDomGetHtml(message, session) {
@@ -903,13 +1807,12 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing ref", false));
             return;
         }
-        const selector = this.resolveSelector(session, ref, message);
-        if (!selector)
+        const resolved = this.resolveRefFromPayload(session, ref, message);
+        if (!resolved)
             return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
-            return;
-        const html = await this.runElementAction(target, selector, { type: "outerHTML" }, () => this.dom.getOuterHtml(target.tabId, selector));
+        const html = this.isAllowedCanvasTargetUrl(resolved.target.url)
+            ? await this.runElementAction(resolved.target, resolved.selector, { type: "outerHTML" }, () => this.dom.getOuterHtml(resolved.target.tabId, resolved.selector))
+            : await this.callFunctionOnRef(resolved, DOM_OUTER_HTML_DECLARATION);
         const truncated = html.length > maxChars;
         const outerHTML = truncated ? html.slice(0, maxChars) : html;
         this.sendResponse(message, { outerHTML, truncated });
@@ -922,13 +1825,12 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing ref", false));
             return;
         }
-        const selector = this.resolveSelector(session, ref, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, ref, message);
+        if (!resolved)
             return;
-        const text = await this.runElementAction(target, selector, { type: "innerText" }, () => this.dom.getInnerText(target.tabId, selector));
+        const text = this.isAllowedCanvasTargetUrl(resolved.target.url)
+            ? await this.runElementAction(resolved.target, resolved.selector, { type: "innerText" }, () => this.dom.getInnerText(resolved.target.tabId, resolved.selector))
+            : await this.callFunctionOnRef(resolved, DOM_INNER_TEXT_DECLARATION);
         const truncated = text.length > maxChars;
         this.sendResponse(message, { text: truncated ? text.slice(0, maxChars) : text, truncated });
     }
@@ -940,13 +1842,12 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing ref or name", false));
             return;
         }
-        const selector = this.resolveSelector(session, ref, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, ref, message);
+        if (!resolved)
             return;
-        const value = await this.runElementAction(target, selector, { type: "getAttr", name }, () => this.dom.getAttr(target.tabId, selector, name));
+        const value = this.isAllowedCanvasTargetUrl(resolved.target.url)
+            ? await this.runElementAction(resolved.target, resolved.selector, { type: "getAttr", name }, () => this.dom.getAttr(resolved.target.tabId, resolved.selector, name))
+            : await this.callFunctionOnRef(resolved, DOM_GET_ATTR_DECLARATION, [name]);
         this.sendResponse(message, { value });
     }
     async handleDomGetValue(message, session) {
@@ -956,47 +1857,144 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "Missing ref", false));
             return;
         }
-        const selector = this.resolveSelector(session, ref, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, ref, message);
+        if (!resolved)
             return;
-        const value = await this.runElementAction(target, selector, { type: "getValue" }, () => this.dom.getValue(target.tabId, selector));
+        const value = this.isAllowedCanvasTargetUrl(resolved.target.url)
+            ? await this.runElementAction(resolved.target, resolved.selector, { type: "getValue" }, () => this.dom.getValue(resolved.target.tabId, resolved.selector))
+            : await this.callFunctionOnRef(resolved, DOM_GET_VALUE_DECLARATION);
         this.sendResponse(message, { value });
     }
     async handleDomIsVisible(message, session) {
-        const selector = this.resolveSelector(session, message.payload, message);
-        if (!selector)
-            return;
-        const target = this.requireActiveTarget(session, message);
-        if (!target)
+        const resolved = this.resolveRefFromPayload(session, message.payload, message);
+        if (!resolved)
             return;
-        const visible = await this.runElementAction(target, selector, { type: "getSelectorState" }, async () => await this.dom.getSelectorState(target.tabId, selector));
+        const visible = this.isAllowedCanvasTargetUrl(resolved.target.url)
+            ? await this.runElementAction(resolved.target, resolved.selector, { type: "getSelectorState" }, async () => await this.dom.getSelectorState(resolved.target.tabId, resolved.selector))
+            : await this.callFunctionOnRef(resolved, DOM_IS_VISIBLE_DECLARATION);
         const isVisible = typeof visible === "object" && visible !== null && "visible" in visible
             ? Boolean(visible.visible)
             : Boolean(visible);
         this.sendResponse(message, { value: isVisible });
     }
     async handleDomIsEnabled(message, session) {
-        const selector = this.resolveSelector(session, message.payload, message);
-        if (!selector)
+        const resolved = this.resolveRefFromPayload(session, message.payload, message);
+        if (!resolved)
+            return;
+        const enabled = this.isAllowedCanvasTargetUrl(resolved.target.url)
+            ? await this.runElementAction(resolved.target, resolved.selector, { type: "isEnabled" }, () => this.dom.isEnabled(resolved.target.tabId, resolved.selector))
+            : await this.callFunctionOnRef(resolved, DOM_IS_ENABLED_DECLARATION);
+        this.sendResponse(message, { value: enabled });
+    }
+    async handleDomIsChecked(message, session) {
+        const resolved = this.resolveRefFromPayload(session, message.payload, message);
+        if (!resolved)
+            return;
+        const checked = this.isAllowedCanvasTargetUrl(resolved.target.url)
+            ? await this.runElementAction(resolved.target, resolved.selector, { type: "isChecked" }, () => this.dom.isChecked(resolved.target.tabId, resolved.selector))
+            : await this.callFunctionOnRef(resolved, DOM_IS_CHECKED_DECLARATION);
+        this.sendResponse(message, { value: checked });
+    }
+    async handleDomRefPoint(message, session) {
+        const resolved = this.resolveRefFromPayload(session, message.payload, message);
+        if (!resolved)
             return;
+        const point = await this.resolveRefPoint(resolved);
+        this.sendResponse(message, point);
+    }
+    async handleCanvasOverlayMount(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const mountId = typeof payload.mountId === "string" && payload.mountId.trim().length > 0
+            ? payload.mountId.trim()
+            : `mount_${createId()}`;
+        const title = typeof payload.title === "string" && payload.title.trim().length > 0
+            ? payload.title.trim()
+            : "OpenDevBrowser Canvas";
+        const prototypeId = typeof payload.prototypeId === "string" && payload.prototypeId.trim().length > 0
+            ? payload.prototypeId.trim()
+            : "prototype";
         const target = this.requireActiveTarget(session, message);
         if (!target)
             return;
-        const enabled = await this.runElementAction(target, selector, { type: "isEnabled" }, () => this.dom.isEnabled(target.tabId, selector));
-        this.sendResponse(message, { value: enabled });
+        const selection = parseCanvasOverlaySelection(payload.selection, target.targetId);
+        const result = await this.dom.mountCanvasOverlay(target.tabId, {
+            mountId,
+            title,
+            prototypeId,
+            selection
+        });
+        this.sendResponse(message, {
+            mountId,
+            targetId: target.targetId,
+            previewState: "background",
+            overlayState: result.overlayState ?? "mounted",
+            capabilities: { selection: true, guides: true }
+        });
     }
-    async handleDomIsChecked(message, session) {
-        const selector = this.resolveSelector(session, message.payload, message);
-        if (!selector)
+    async handleCanvasOverlayUnmount(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const mountId = typeof payload.mountId === "string" ? payload.mountId.trim() : "";
+        if (!mountId) {
+            this.sendError(message, buildError("invalid_request", "Missing mountId", false));
             return;
+        }
         const target = this.requireActiveTarget(session, message);
         if (!target)
             return;
-        const checked = await this.runElementAction(target, selector, { type: "isChecked" }, () => this.dom.isChecked(target.tabId, selector));
-        this.sendResponse(message, { value: checked });
+        await this.dom.unmountCanvasOverlay(target.tabId, mountId);
+        this.sendResponse(message, {
+            ok: true,
+            mountId,
+            targetId: target.targetId,
+            overlayState: "idle"
+        });
+    }
+    async handleCanvasOverlaySelect(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const mountId = typeof payload.mountId === "string" ? payload.mountId.trim() : "";
+        const nodeId = typeof payload.nodeId === "string" && payload.nodeId.trim().length > 0
+            ? payload.nodeId.trim()
+            : null;
+        const selectionHint = isRecord(payload.selectionHint) ? payload.selectionHint : {};
+        if (!mountId || (!nodeId && Object.keys(selectionHint).length === 0)) {
+            this.sendError(message, buildError("invalid_request", "Missing mountId or selection target", false));
+            return;
+        }
+        const target = this.requireActiveTarget(session, message);
+        if (!target)
+            return;
+        const selection = await this.dom.selectCanvasOverlay(target.tabId, { nodeId, selectionHint });
+        this.sendResponse(message, {
+            mountId,
+            targetId: target.targetId,
+            selection
+        });
+    }
+    async handleCanvasOverlaySync(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const mountId = typeof payload.mountId === "string" ? payload.mountId.trim() : "";
+        if (!mountId) {
+            this.sendError(message, buildError("invalid_request", "Missing mountId", false));
+            return;
+        }
+        const title = typeof payload.title === "string" && payload.title.trim().length > 0
+            ? payload.title.trim()
+            : "OpenDevBrowser Canvas";
+        const target = this.requireActiveTarget(session, message);
+        if (!target)
+            return;
+        const selection = parseCanvasOverlaySelection(payload.selection, target.targetId);
+        const result = await this.dom.syncCanvasOverlay(target.tabId, {
+            mountId,
+            title,
+            selection
+        });
+        this.sendResponse(message, {
+            ok: true,
+            mountId,
+            targetId: target.targetId,
+            overlayState: result.overlayState ?? "mounted"
+        });
     }
     async handleCanvasRuntimePreviewBridge(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
@@ -1058,15 +2056,72 @@ export class OpsRuntime {
         const target = this.requireActiveTarget(session, message);
         if (!target)
             return;
-        const result = await this.cdp.sendCommand({ tabId: target.tabId }, "Performance.getMetrics", {});
+        const result = await this.cdp.sendCommand(target.debuggee, "Performance.getMetrics", {});
         this.sendResponse(message, { metrics: Array.isArray(result.metrics) ? result.metrics : [] });
     }
     async handleScreenshot(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        if (payload.fullPage === true && typeof payload.ref === "string") {
+            this.sendError(message, buildError("invalid_request", "ref and fullPage cannot be combined.", false));
+            return;
+        }
+        if (typeof payload.ref === "string") {
+            const resolved = this.resolveRefFromPayload(session, payload, message);
+            if (!resolved)
+                return;
+            try {
+                await this.callFunctionOnRef(resolved, DOM_SCROLL_INTO_VIEW_DECLARATION);
+                const clip = await this.callFunctionOnRef(resolved, DOM_SCREENSHOT_CLIP_DECLARATION);
+                const result = await withTimeout(this.cdp.sendCommand(resolved.target.debuggee, "Page.captureScreenshot", {
+                    format: "png",
+                    captureBeyondViewport: true,
+                    clip: this.normalizeScreenshotClip(clip, resolved.ref)
+                }), SCREENSHOT_TIMEOUT_MS, "Ops screenshot timed out");
+                if (result?.data) {
+                    this.sendResponse(message, { base64: result.data });
+                    return;
+                }
+            }
+            catch (error) {
+                logError("ops.screenshot.ref", error, { code: "screenshot_failed" });
+            }
+            this.sendError(message, buildError("execution_failed", "Screenshot failed", false));
+            return;
+        }
         const target = this.requireActiveTarget(session, message);
         if (!target)
             return;
+        if (payload.fullPage === true) {
+            try {
+                const metrics = await this.cdp.sendCommand(target.debuggee, "Page.getLayoutMetrics", {});
+                const contentSize = isRecord(metrics.cssContentSize) ? metrics.cssContentSize : metrics.contentSize;
+                const width = typeof contentSize?.width === "number" && Number.isFinite(contentSize.width)
+                    ? Math.max(1, Math.ceil(contentSize.width))
+                    : null;
+                const height = typeof contentSize?.height === "number" && Number.isFinite(contentSize.height)
+                    ? Math.max(1, Math.ceil(contentSize.height))
+                    : null;
+                if (width === null || height === null) {
+                    throw new Error("Full-page screenshot metrics unavailable");
+                }
+                const result = await withTimeout(this.cdp.sendCommand(target.debuggee, "Page.captureScreenshot", {
+                    format: "png",
+                    captureBeyondViewport: true,
+                    clip: { x: 0, y: 0, width, height, scale: 1 }
+                }), SCREENSHOT_TIMEOUT_MS, "Ops screenshot timed out");
+                if (result?.data) {
+                    this.sendResponse(message, { base64: result.data });
+                    return;
+                }
+            }
+            catch (error) {
+                logError("ops.screenshot.full_page", error, { code: "screenshot_failed" });
+            }
+            this.sendError(message, buildError("execution_failed", "Screenshot failed", false));
+            return;
+        }
         try {
-            const result = await withTimeout(this.cdp.sendCommand({ tabId: target.tabId }, "Page.captureScreenshot", { format: "png" }), SCREENSHOT_TIMEOUT_MS, "Ops screenshot timed out");
+            const result = await withTimeout(this.cdp.sendCommand(target.debuggee, "Page.captureScreenshot", { format: "png" }), SCREENSHOT_TIMEOUT_MS, "Ops screenshot timed out");
             if (result?.data) {
                 this.sendResponse(message, { base64: result.data });
                 return;
@@ -1082,16 +2137,112 @@ export class OpsRuntime {
         }
         this.sendError(message, buildError("execution_failed", "Screenshot failed", false));
     }
-    async handleConsolePoll(message, session) {
+    async handleUpload(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
-        const sinceSeq = typeof payload.sinceSeq === "number" ? payload.sinceSeq : 0;
-        const max = typeof payload.max === "number" ? payload.max : 50;
-        const events = session.consoleEvents.filter((event) => event.seq > sinceSeq).slice(0, max);
-        const lastEvent = events.at(-1);
-        const nextSeq = lastEvent ? lastEvent.seq : sinceSeq;
-        this.sendResponse(message, { events, nextSeq });
-    }
-    async handleNetworkPoll(message, session) {
+        const files = Array.isArray(payload.files)
+            ? payload.files.filter((value) => typeof value === "string" && value.trim().length > 0)
+            : [];
+        if (files.length === 0) {
+            this.sendError(message, buildError("invalid_request", "Missing files", false));
+            return;
+        }
+        const resolved = this.resolveRefFromPayload(session, payload, message);
+        if (!resolved)
+            return;
+        try {
+            const info = await this.callFunctionOnRef(resolved, DOM_FILE_INPUT_INFO_DECLARATION);
+            if (info?.disabled === true) {
+                this.sendError(message, buildError("execution_failed", `Cannot upload files to disabled ref: ${resolved.ref}`, false));
+                return;
+            }
+            if (info?.isFileInput === true) {
+                await this.cdp.sendCommand(resolved.target.debuggee, "DOM.setFileInputFiles", {
+                    backendNodeId: resolved.backendNodeId,
+                    files
+                });
+                this.sendResponse(message, {
+                    targetId: resolved.target.targetId,
+                    fileCount: files.length,
+                    mode: "direct_input"
+                });
+                return;
+            }
+            this.sessions.clearFileChooser(session.id, resolved.target.targetId);
+            await this.cdp.sendCommand(resolved.target.debuggee, "Page.setInterceptFileChooserDialog", { enabled: true });
+            await this.callFunctionOnRef(resolved, DOM_SCROLL_INTO_VIEW_DECLARATION);
+            const point = await this.resolveRefPoint(resolved);
+            await this.dispatchMouseEvent(resolved.target.debuggee, "mouseMoved", point.x, point.y);
+            await this.dispatchMouseEvent(resolved.target.debuggee, "mousePressed", point.x, point.y, {
+                button: "left",
+                clickCount: 1
+            });
+            await this.dispatchMouseEvent(resolved.target.debuggee, "mouseReleased", point.x, point.y, {
+                button: "left",
+                clickCount: 1
+            });
+            const chooser = await this.waitForFileChooser(session.id, resolved.target.targetId);
+            if (typeof chooser.backendNodeId !== "number") {
+                throw new Error("File chooser opened without backend node id");
+            }
+            await this.cdp.sendCommand(resolved.target.debuggee, "DOM.setFileInputFiles", {
+                backendNodeId: chooser.backendNodeId,
+                files
+            });
+            this.sessions.clearFileChooser(session.id, resolved.target.targetId);
+            this.sendResponse(message, {
+                targetId: resolved.target.targetId,
+                fileCount: files.length,
+                mode: "file_chooser"
+            });
+        }
+        catch (error) {
+            this.sessions.clearFileChooser(session.id, resolved.target.targetId);
+            logError("ops.upload", error, { code: "upload_failed" });
+            this.sendError(message, buildError("execution_failed", error instanceof Error ? error.message : "Upload failed", false));
+        }
+    }
+    async handleDialog(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const action = payload.action === "accept" || payload.action === "dismiss" || payload.action === "status"
+            ? payload.action
+            : "status";
+        const target = this.requireActiveTarget(session, message);
+        if (!target)
+            return;
+        const dialog = this.serializeDialogState(session, target.targetId);
+        if (!dialog.open || action === "status") {
+            this.sendResponse(message, {
+                dialog,
+                ...(action === "status" ? {} : { handled: false })
+            });
+            return;
+        }
+        try {
+            await this.cdp.sendCommand(target.debuggee, "Page.handleJavaScriptDialog", {
+                accept: action === "accept",
+                ...(action === "accept" && typeof payload.promptText === "string" ? { promptText: payload.promptText } : {})
+            });
+            this.sessions.clearDialog(session.id, target.targetId);
+            this.sendResponse(message, {
+                dialog: { open: false, targetId: target.targetId },
+                handled: true
+            });
+        }
+        catch (error) {
+            logError("ops.dialog", error, { code: "dialog_failed" });
+            this.sendError(message, buildError("execution_failed", error instanceof Error ? error.message : "Dialog handling failed", false));
+        }
+    }
+    async handleConsolePoll(message, session) {
+        const payload = isRecord(message.payload) ? message.payload : {};
+        const sinceSeq = typeof payload.sinceSeq === "number" ? payload.sinceSeq : 0;
+        const max = typeof payload.max === "number" ? payload.max : 50;
+        const events = session.consoleEvents.filter((event) => event.seq > sinceSeq).slice(0, max);
+        const lastEvent = events.at(-1);
+        const nextSeq = lastEvent ? lastEvent.seq : sinceSeq;
+        this.sendResponse(message, { events, nextSeq });
+    }
+    async handleNetworkPoll(message, session) {
         const payload = isRecord(message.payload) ? message.payload : {};
         const sinceSeq = typeof payload.sinceSeq === "number" ? payload.sinceSeq : 0;
         const max = typeof payload.max === "number" ? payload.max : 50;
@@ -1134,7 +2285,7 @@ export class OpsRuntime {
             if (!target)
                 return;
             try {
-                await this.cdp.sendCommand({ tabId: target.tabId }, "Network.setCookies", { cookies: normalized });
+                await this.cdp.sendCommand(target.debuggee, "Network.setCookies", { cookies: normalized });
             }
             catch (error) {
                 const detail = error instanceof Error ? error.message : "Cookie import failed";
@@ -1167,7 +2318,7 @@ export class OpsRuntime {
             return;
         let rawCookies = [];
         try {
-            const response = await this.cdp.sendCommand({ tabId: target.tabId }, "Network.getCookies", urls ? { urls } : {});
+            const response = await this.cdp.sendCommand(target.debuggee, "Network.getCookies", urls ? { urls } : {});
             rawCookies = Array.isArray(response.cookies) ? response.cookies : [];
         }
         catch (error) {
@@ -1184,23 +2335,323 @@ export class OpsRuntime {
             count: cookies.length
         });
     }
-    async enableSessionDomains(session) {
-        await this.enableTargetDomains(session.tabId);
+    async attachTargetTab(tabId) {
+        try {
+            await this.cdp.attach(tabId);
+        }
+        catch (error) {
+            if (isAttachBlockedError(error)) {
+                await delay(50);
+                try {
+                    await this.cdp.attach(tabId);
+                    return;
+                }
+                catch (retryError) {
+                    error = retryError;
+                }
+            }
+            const diagnostic = this.cdp.getLastRootAttachDiagnostic?.(tabId) ?? null;
+            const detail = error instanceof Error ? error.message : "Debugger attach failed";
+            logError("ops.direct_attach_stage", error instanceof Error ? error : new Error(detail), {
+                code: "direct_attach_stage",
+                extra: {
+                    tabId,
+                    ...(this.toDirectAttachDiagnosticDetails(diagnostic) ?? {}),
+                    ...(!diagnostic ? { reason: detail } : {})
+                }
+            });
+            throw this.decorateDirectAttachError(error, diagnostic);
+        }
     }
-    async enableTargetDomains(tabId) {
+    async attachCreatedTargetTab(tabId) {
         try {
-            await this.cdp.sendCommand({ tabId }, "Runtime.enable", {});
-            await this.cdp.sendCommand({ tabId }, "Network.enable", {});
-            await this.cdp.sendCommand({ tabId }, "Performance.enable", {});
+            await this.attachTargetTab(tabId);
+            return;
         }
         catch (error) {
-            logError("ops.enable_domains", error, { code: "enable_domains_failed" });
+            if (!isAttachBlockedError(error)) {
+                throw error;
+            }
         }
+        await this.tabs.waitForTabComplete(tabId).catch(() => undefined);
+        if (this.hasAttachedTabDebuggee(tabId)) {
+            return;
+        }
+        this.cdp.markClientClosed();
+        await this.attachTargetTab(tabId);
+    }
+    async attachStartUrlConnectTab(tabId) {
+        return this.attachLaunchTargetTab(tabId, true);
+    }
+    async attachLaunchTargetTab(tabId, waitForTabCompleteBeforeRetry) {
+        try {
+            await this.attachTargetTab(tabId);
+            return null;
+        }
+        catch (error) {
+            if (!isAttachBlockedError(error)) {
+                throw error;
+            }
+        }
+        this.cdp.markClientClosed();
+        if (waitForTabCompleteBeforeRetry) {
+            await this.tabs.waitForTabComplete(tabId).catch(() => undefined);
+        }
+        const refreshedTab = waitForTabCompleteBeforeRetry
+            ? await this.tabs.getTab(tabId)
+            : null;
+        try {
+            await this.attachTargetTab(tabId);
+            return refreshedTab ?? null;
+        }
+        catch (error) {
+            if (!isAttachBlockedError(error) || typeof this.cdp.refreshTabAttachment !== "function") {
+                throw error;
+            }
+            await this.cdp.refreshTabAttachment(tabId);
+            await this.resolveReadyTabDebuggee(tabId, { strict: true, allowRefresh: false });
+            return await this.tabs.getTab(tabId) ?? refreshedTab ?? null;
+        }
+    }
+    async getCreatedTabSeed(tab) {
+        const refreshedTab = typeof tab.id === "number"
+            ? await this.tabs.getTab(tab.id)
+            : null;
+        return getReportedTabSeed(refreshedTab ?? tab);
+    }
+    async claimCommandCreatedTab(session, tab) {
+        const tabId = typeof tab.id === "number" ? tab.id : null;
+        if (tabId === null) {
+            return null;
+        }
+        const currentOwner = this.sessions.getByTabId(tabId);
+        if (currentOwner && currentOwner.id !== session.id) {
+            this.sessions.removeTargetByTabId(currentOwner.id, tabId);
+        }
+        const existingTargetId = this.sessions.getTargetIdByTabId(session.id, tabId);
+        if (!existingTargetId) {
+            return null;
+        }
+        const target = session.targets.get(existingTargetId) ?? null;
+        if (!target) {
+            return null;
+        }
+        const seed = await this.getCreatedTabSeed(tab);
+        if (typeof seed.url === "string" && seed.url.length > 0) {
+            target.url = seed.url;
+        }
+        if (typeof seed.title === "string" && seed.title.length > 0) {
+            target.title = seed.title;
+        }
+        target.openerTargetId = undefined;
+        return target;
+    }
+    async activateCreatedTab(tabId) {
+        await this.tabs.activateTab(tabId).catch(() => undefined);
+    }
+    rememberCommandCreatedTab(sessionId, tabId, kind) {
+        this.commandCreatedTabs.set(tabId, { sessionId, kind });
+    }
+    isCommandCreatedTab(tabId, sessionId) {
+        const entry = this.commandCreatedTabs.get(tabId);
+        return sessionId ? entry?.sessionId === sessionId : Boolean(entry);
+    }
+    forgetCommandCreatedTab(tabId) {
+        this.commandCreatedTabs.delete(tabId);
+    }
+    isConcreteDebuggee(debuggee) {
+        return Boolean(debuggee
+            && ((typeof debuggee.sessionId === "string" && debuggee.sessionId.length > 0)
+                || (typeof debuggee.targetId === "string" && debuggee.targetId.length > 0)));
+    }
+    hasAttachedSessionDebuggee(debuggee) {
+        return Boolean(debuggee && typeof debuggee.sessionId === "string" && debuggee.sessionId.length > 0);
+    }
+    hasAttachedTabDebuggee(tabId) {
+        if (typeof this.cdp.isTabAttached === "function") {
+            return this.cdp.isTabAttached(tabId);
+        }
+        if (typeof this.cdp.getAttachedTabIds === "function") {
+            return this.cdp.getAttachedTabIds().includes(tabId);
+        }
+        return false;
+    }
+    async resolveReadyTabDebuggee(tabId, options) {
+        const readDebuggee = () => this.cdp.getTabDebuggee?.(tabId);
+        let pageDebuggee = readDebuggee();
+        if (this.hasAttachedSessionDebuggee(pageDebuggee)) {
+            return pageDebuggee;
+        }
+        if (!options.strict && this.isConcreteDebuggee(pageDebuggee)) {
+            return pageDebuggee;
+        }
+        await this.cdp.primeAttachedRootSession?.(tabId);
+        pageDebuggee = readDebuggee();
+        if (this.hasAttachedSessionDebuggee(pageDebuggee)) {
+            return pageDebuggee;
+        }
+        if (!options.strict && this.isConcreteDebuggee(pageDebuggee)) {
+            return pageDebuggee;
+        }
+        if (options.allowRefresh && typeof this.cdp.refreshTabAttachment === "function") {
+            await this.cdp.refreshTabAttachment(tabId);
+            await this.cdp.primeAttachedRootSession?.(tabId);
+            pageDebuggee = readDebuggee();
+            if (this.hasAttachedSessionDebuggee(pageDebuggee)) {
+                return pageDebuggee;
+            }
+            if (!options.strict && this.isConcreteDebuggee(pageDebuggee)) {
+                return pageDebuggee;
+            }
+        }
+        if (this.isConcreteDebuggee(pageDebuggee)) {
+            return pageDebuggee;
+        }
+        if (options.strict) {
+            throw new Error(`Concrete debugger session unavailable for tab ${tabId}.`);
+        }
+        return pageDebuggee ?? { tabId };
+    }
+    async enableTargetDomains(tabId, strict = false) {
+        const buildEnablementFailureDetails = (allowRefresh, refreshedAfterBlock, enablementStage) => ({
+            phase: "strict_enablement",
+            enablementStage,
+            tabId,
+            strict,
+            allowRefresh,
+            refreshedAfterBlock
+        });
+        const enableOnce = async (allowRefresh, refreshedAfterBlock) => {
+            let pageDebuggee;
+            try {
+                pageDebuggee = await this.resolveReadyTabDebuggee(tabId, {
+                    strict,
+                    allowRefresh
+                });
+            }
+            catch (error) {
+                throw this.decorateCdpFailure(error, buildEnablementFailureDetails(allowRefresh, refreshedAfterBlock, "resolve_ready_debuggee"));
+            }
+            await this.enableRootTracking(buildEnablementFailureDetails(allowRefresh, refreshedAfterBlock, "configure_auto_attach"));
+            await this.enableTargetDomainsOnDebuggee(pageDebuggee, buildEnablementFailureDetails(allowRefresh, refreshedAfterBlock, "page_enable"));
+            await this.enableTargetDiscovery(buildEnablementFailureDetails(allowRefresh, refreshedAfterBlock, "set_discover_targets"));
+        };
+        try {
+            try {
+                await enableOnce(strict, false);
+            }
+            catch (error) {
+                if (!strict || !isAttachBlockedError(error) || typeof this.cdp.refreshTabAttachment !== "function") {
+                    throw error;
+                }
+                this.cdp.markClientClosed?.();
+                await this.cdp.refreshTabAttachment(tabId);
+                await enableOnce(false, true);
+            }
+        }
+        catch (error) {
+            logError("ops.enable_domains", error, { code: "enable_domains_failed", extra: { tabId, strict } });
+            if (strict) {
+                throw error;
+            }
+        }
+    }
+    async enableRootTracking(baseDetails) {
+        try {
+            await this.cdp.configureAutoAttach?.({
+                autoAttach: true,
+                waitForDebuggerOnStart: false,
+                flatten: true
+            });
+        }
+        catch (error) {
+            throw this.decorateCdpFailure(error, {
+                ...baseDetails,
+                enablementStage: "configure_auto_attach"
+            });
+        }
+    }
+    async enableTargetDiscovery(baseDetails) {
+        try {
+            await this.cdp.setDiscoverTargetsEnabled?.(true);
+        }
+        catch (error) {
+            logError("ops.discover_targets", error, {
+                code: "discover_targets_enable_failed",
+                extra: baseDetails
+            });
+        }
+    }
+    async enableTargetDomainsOnDebuggee(debuggee, baseDetails) {
+        const enableCommands = [
+            { method: "Page.enable", params: {}, stage: "page_enable" },
+            { method: "Page.setInterceptFileChooserDialog", params: { enabled: true }, stage: "page_file_chooser" },
+            { method: "Runtime.enable", params: {}, stage: "runtime_enable" },
+            { method: "Network.enable", params: {}, stage: "network_enable" },
+            { method: "Performance.enable", params: {}, stage: "performance_enable" }
+        ];
+        for (const command of enableCommands) {
+            try {
+                await this.cdp.sendCommand(debuggee, command.method, command.params);
+            }
+            catch (error) {
+                throw this.decorateCdpFailure(error, {
+                    ...baseDetails,
+                    enablementStage: command.stage
+                });
+            }
+        }
+    }
+    parsePointerCoords(payload) {
+        const x = typeof payload.x === "number" && Number.isFinite(payload.x) ? payload.x : null;
+        const y = typeof payload.y === "number" && Number.isFinite(payload.y) ? payload.y : null;
+        return x === null || y === null ? null : { x, y };
+    }
+    parsePointerButton(value) {
+        return value === "middle" || value === "right" ? value : "left";
+    }
+    async dispatchMouseEvent(debuggee, type, x, y, options = {}) {
+        if (type === "mouseMoved" && options.steps && options.steps > 1) {
+            const stepCount = Math.max(1, options.steps);
+            for (let index = 1; index <= stepCount; index += 1) {
+                await this.cdp.sendCommand(debuggee, "Input.dispatchMouseEvent", {
+                    type,
+                    x,
+                    y,
+                    button: options.button ?? "none",
+                    clickCount: options.clickCount ?? 0
+                });
+            }
+            return;
+        }
+        await this.cdp.sendCommand(debuggee, "Input.dispatchMouseEvent", {
+            type,
+            x,
+            y,
+            button: options.button ?? (type === "mouseMoved" ? "none" : "left"),
+            clickCount: options.clickCount ?? (type === "mouseMoved" ? 0 : 1)
+        });
+    }
+    async dispatchKeyPress(debuggee, key) {
+        const text = key.length === 1 ? key : undefined;
+        await this.cdp.sendCommand(debuggee, "Input.dispatchKeyEvent", {
+            type: "keyDown",
+            key,
+            ...(text ? { text } : {})
+        });
+        await this.cdp.sendCommand(debuggee, "Input.dispatchKeyEvent", {
+            type: "keyUp",
+            key
+        });
     }
     async withSession(message, clientId, handler) {
         const session = this.getSessionForMessage(message, clientId);
         if (!session)
             return;
+        if (DIALOG_SCOPED_COMMANDS.has(message.command)) {
+            await this.withDialogQueue(message, session, handler);
+            return;
+        }
         if (!TARGET_SCOPED_COMMANDS.has(message.command)) {
             session.queue = session.queue.then(() => handler(session), () => handler(session));
             await session.queue;
@@ -1222,6 +2673,9 @@ export class OpsRuntime {
         const requested = typeof payload.targetId === "string" ? payload.targetId.trim() : "";
         return requested || session.activeTargetId || session.targetId;
     }
+    dialogQueueKey(sessionId, targetId) {
+        return `${sessionId}:${targetId}`;
+    }
     sessionQueueAgeMs(session) {
         let oldest = null;
         for (const value of session.targetQueueOldestAt.values()) {
@@ -1352,83 +2806,814 @@ export class OpsRuntime {
             acquired = true;
             await handler(session);
         }
-        finally {
-            if (acquired) {
-                this.releaseParallelSlot(session);
+        finally {
+            if (acquired) {
+                this.releaseParallelSlot(session);
+            }
+            releaseQueue();
+            const depth = (session.targetQueueDepth.get(targetId) ?? 1) - 1;
+            if (depth <= 0) {
+                session.targetQueueDepth.delete(targetId);
+                session.targetQueueOldestAt.delete(targetId);
+            }
+            else {
+                session.targetQueueDepth.set(targetId, depth);
+            }
+            session.pendingParallel = Math.max(0, session.pendingParallel - 1);
+            if (session.targetQueues.get(targetId) === tail) {
+                session.targetQueues.delete(targetId);
+            }
+        }
+    }
+    async withDialogQueue(message, session, handler) {
+        const targetId = this.resolveTargetIdForQueue(session, message);
+        const queueKey = this.dialogQueueKey(session.id, targetId);
+        const previous = this.dialogQueues.get(queueKey) ?? Promise.resolve();
+        let releaseQueue = () => { };
+        const gate = new Promise((resolve) => {
+            releaseQueue = resolve;
+        });
+        const tail = previous.then(() => gate, () => gate);
+        this.dialogQueues.set(queueKey, tail);
+        await previous;
+        try {
+            await handler(session);
+        }
+        finally {
+            releaseQueue();
+            if (this.dialogQueues.get(queueKey) === tail) {
+                this.dialogQueues.delete(queueKey);
+            }
+        }
+    }
+    getSessionForMessage(message, clientId) {
+        const opsSessionId = message.opsSessionId;
+        if (!opsSessionId) {
+            this.sendError(message, buildError("invalid_request", "Missing opsSessionId", false));
+            return null;
+        }
+        const session = this.sessions.get(opsSessionId);
+        if (!session) {
+            this.sendError(message, buildError("invalid_session", "Unknown ops session", false));
+            return null;
+        }
+        const leaseId = typeof message.leaseId === "string" ? message.leaseId : "";
+        if (session.ownerClientId !== clientId) {
+            if (leaseId && leaseId === session.leaseId) {
+                this.reclaimSession(session, clientId);
+            }
+            else {
+                this.sendError(message, buildError("not_owner", "Client does not own session", false));
+                return null;
+            }
+        }
+        else if (session.state === "closing") {
+            if (leaseId && leaseId === session.leaseId) {
+                this.reclaimSession(session, clientId);
+            }
+            else {
+                this.sendError(message, buildError("not_owner", "Client does not own session", false));
+                return null;
+            }
+        }
+        if (leaseId !== session.leaseId) {
+            this.sendError(message, buildError("not_owner", "Lease does not match session owner", false));
+            return null;
+        }
+        session.lastUsedAt = Date.now();
+        return session;
+    }
+    requestedTargetId(session, message) {
+        return this.extractPayloadTargetId(message.payload) ?? session.activeTargetId ?? session.targetId;
+    }
+    hasOpsTarget(session, targetId) {
+        return session.targets.has(targetId) || this.sessions.getSyntheticTarget(session.id, targetId) !== null;
+    }
+    resolveTargetContext(session, targetId) {
+        const target = session.targets.get(targetId) ?? null;
+        const explicitSynthetic = this.sessions.getSyntheticTarget(session.id, targetId);
+        const bridgeSynthetic = explicitSynthetic ? null : this.findSyntheticSessionBridge(session, target);
+        const synthetic = explicitSynthetic ?? bridgeSynthetic;
+        if (!target && !synthetic) {
+            return null;
+        }
+        const targetTabId = target?.tabId ?? synthetic?.tabId ?? session.tabId;
+        const baseType = synthetic?.type ?? "page";
+        return {
+            targetId,
+            tabId: targetTabId,
+            type: baseType,
+            synthetic: explicitSynthetic !== null && !session.targets.has(targetId),
+            ...(explicitSynthetic?.url ? { url: explicitSynthetic.url } : target?.url ? { url: target.url } : bridgeSynthetic?.url ? { url: bridgeSynthetic.url } : {}),
+            ...(explicitSynthetic?.title ? { title: explicitSynthetic.title } : target?.title ? { title: target.title } : bridgeSynthetic?.title ? { title: bridgeSynthetic.title } : {}),
+            ...(synthetic?.sessionId ? { sessionId: synthetic.sessionId } : {}),
+            ...(explicitSynthetic?.openerTargetId
+                ? { openerTargetId: explicitSynthetic.openerTargetId }
+                : target?.openerTargetId
+                    ? { openerTargetId: target.openerTargetId }
+                    : bridgeSynthetic?.openerTargetId
+                        ? { openerTargetId: bridgeSynthetic.openerTargetId }
+                        : {}),
+            debuggee: synthetic?.sessionId
+                ? { tabId: synthetic.tabId, sessionId: synthetic.sessionId }
+                : this.cdp.getTabDebuggee?.(targetTabId) ?? { tabId: targetTabId }
+        };
+    }
+    resolveDebuggerEventTargetId(session, source, resolvedTabId) {
+        const sourceSessionId = typeof source.sessionId === "string"
+            ? source.sessionId
+            : null;
+        if (sourceSessionId) {
+            const synthetic = this.sessions.findSyntheticTargetBySessionId(session.id, sourceSessionId);
+            if (synthetic) {
+                return synthetic.targetId;
+            }
+        }
+        const sourceTargetId = typeof source.targetId === "string" ? source.targetId : null;
+        if (sourceTargetId) {
+            const synthetic = this.sessions.getSyntheticTarget(session.id, sourceTargetId);
+            if (synthetic) {
+                return synthetic.targetId;
+            }
+            if (session.targets.has(sourceTargetId)) {
+                return sourceTargetId;
+            }
+        }
+        const tabId = resolvedTabId ?? this.cdp.resolveSourceTabId(source);
+        if (tabId !== null) {
+            return this.sessions.getTargetIdByTabId(session.id, tabId) ?? session.activeTargetId ?? session.targetId;
+        }
+        return session.activeTargetId ?? session.targetId;
+    }
+    resolveRouterEventTargetId(session, event) {
+        if (typeof event.sessionId === "string") {
+            const synthetic = this.sessions.findSyntheticTargetBySessionId(session.id, event.sessionId);
+            if (synthetic) {
+                return synthetic.targetId;
+            }
+        }
+        return this.sessions.getTargetIdByTabId(session.id, event.tabId) ?? session.activeTargetId ?? session.targetId;
+    }
+    applyDialogOpening(session, targetId, params) {
+        const payload = params;
+        this.sessions.setDialog(session.id, targetId, {
+            open: true,
+            targetId,
+            ...(typeof payload?.type === "string" ? { type: payload.type } : {}),
+            ...(typeof payload?.message === "string" ? { message: payload.message } : {}),
+            ...(typeof payload?.defaultPrompt === "string" ? { defaultPrompt: payload.defaultPrompt } : {}),
+            ...(typeof payload?.url === "string" ? { url: payload.url } : {}),
+            openedAt: new Date().toISOString()
+        });
+    }
+    applyDialogClosed(session, targetId) {
+        this.sessions.clearDialog(session.id, targetId);
+    }
+    applyFileChooserOpened(session, targetId, params) {
+        const payload = params;
+        this.sessions.setFileChooser(session.id, targetId, {
+            open: true,
+            targetId,
+            ...(typeof payload?.backendNodeId === "number" ? { backendNodeId: payload.backendNodeId } : {}),
+            openedAt: new Date().toISOString()
+        });
+    }
+    serializeDialogState(session, targetId) {
+        if (!targetId) {
+            return { open: false, targetId: session.activeTargetId ?? session.targetId };
+        }
+        return this.sessions.getDialog(session.id, targetId) ?? { open: false, targetId };
+    }
+    hasUsableDebuggee(target) {
+        if (typeof target.sessionId === "string" && target.sessionId.length > 0) {
+            if (typeof this.cdp.hasDebuggerSession === "function") {
+                return this.cdp.hasDebuggerSession(target.sessionId);
+            }
+            return true;
+        }
+        return this.isConcreteDebuggee(this.cdp.getTabDebuggee?.(target.tabId));
+    }
+    extractPayloadTargetId(payload) {
+        if (!isRecord(payload)) {
+            return null;
+        }
+        return typeof payload.targetId === "string" && payload.targetId.trim().length > 0
+            ? payload.targetId.trim()
+            : null;
+    }
+    resolveRequestedTargetContext(session, targetId, explicitTarget) {
+        const target = this.resolveTargetContext(session, targetId);
+        if (!target) {
+            return null;
+        }
+        if (!explicitTarget
+            && target.targetId !== session.targetId
+            && !this.hasUsableDebuggee(target)
+            && (target.synthetic || typeof target.openerTargetId === "string" || typeof target.sessionId === "string")) {
+            const fallbackTarget = this.resolveTargetContext(session, session.targetId);
+            if (fallbackTarget) {
+                session.activeTargetId = fallbackTarget.targetId;
+                return fallbackTarget;
+            }
+        }
+        return target;
+    }
+    async preparePopupTarget(session, targetId) {
+        let target = this.resolveTargetContext(session, targetId);
+        if (!target || this.hasUsableDebuggee(target)) {
+            return target;
+        }
+        const hydratedPopupTarget = typeof target.sessionId !== "string"
+            ? await this.hydratePopupOpenerTarget(session, targetId)
+            : null;
+        const popupTarget = hydratedPopupTarget?.openerTargetId
+            ? hydratedPopupTarget
+            : target.openerTargetId
+                ? {
+                    targetId,
+                    tabId: target.tabId,
+                    ...(typeof target.url === "string" ? { url: target.url } : {}),
+                    ...(typeof target.title === "string" ? { title: target.title } : {}),
+                    openerTargetId: target.openerTargetId
+                }
+                : null;
+        if (!popupTarget?.openerTargetId) {
+            return target;
+        }
+        if (this.shouldPreferDirectPopupTabAttach(popupTarget)) {
+            await this.tabs.activateTab(popupTarget.tabId).catch(() => undefined);
+            try {
+                await this.attachTargetTab(popupTarget.tabId);
+                await this.enableTargetDomains(popupTarget.tabId, true);
+                this.clearPopupAttachDiagnostic(session.id, targetId);
+                target = this.resolveTargetContext(session, targetId) ?? target;
+                if (this.hasUsableDebuggee(target)) {
+                    return target;
+                }
+            }
+            catch (error) {
+                if (!isAttachBlockedError(error)) {
+                    throw error;
+                }
+                this.cdp.markClientClosed();
+                try {
+                    await this.attachTargetTab(popupTarget.tabId);
+                    await this.enableTargetDomains(popupTarget.tabId, true);
+                    this.clearPopupAttachDiagnostic(session.id, targetId);
+                    target = this.resolveTargetContext(session, targetId) ?? target;
+                    if (this.hasUsableDebuggee(target)) {
+                        return target;
+                    }
+                }
+                catch (resetError) {
+                    if (!isAttachBlockedError(resetError)) {
+                        throw resetError;
+                    }
+                }
+            }
+        }
+        if (await this.attachTargetViaOpenerSession(session, popupTarget).catch(() => false)) {
+            this.clearPopupAttachDiagnostic(session.id, targetId);
+        }
+        return this.resolveTargetContext(session, targetId) ?? target;
+    }
+    shouldPreferDirectPopupTabAttach(target) {
+        const openerTabId = parseTargetAliasTabId(target.openerTargetId);
+        return openerTabId !== null && openerTabId !== target.tabId;
+    }
+    async activateTargetAndRespond(message, session, targetId) {
+        session.activeTargetId = targetId;
+        const target = this.resolveTargetContext(session, targetId);
+        if (target) {
+            await this.tabs.activateTab(target.tabId).catch(() => undefined);
+        }
+        const tab = target ? await this.tabs.getTab(target.tabId) : null;
+        this.sendResponse(message, {
+            activeTargetId: targetId,
+            url: target ? resolveReportedTargetUrl(target, tab) : undefined,
+            title: target ? resolveReportedTargetTitle(target, tab) : undefined
+        });
+    }
+    shouldPromotePopupTarget(session, openerTargetId, target) {
+        return ((!!target.openerTargetId || target.targetId !== session.targetId)
+            && this.hasUsableDebuggee(target)
+            && (!session.activeTargetId
+                || session.activeTargetId === session.targetId
+                || session.activeTargetId === openerTargetId));
+    }
+    promotePopupTarget(session, targetId) {
+        const target = this.resolveTargetContext(session, targetId);
+        if (!target || !target.openerTargetId) {
+            return;
+        }
+        if (this.shouldPromotePopupTarget(session, target.openerTargetId, target)) {
+            session.activeTargetId = targetId;
+        }
+    }
+    rehydrateSyntheticPopupBridge(session, targetId) {
+        const target = session.targets.get(targetId) ?? null;
+        const bridge = this.findSyntheticSessionBridge(session, target);
+        if (!bridge
+            || typeof bridge.sessionId !== "string"
+            || bridge.sessionId.length === 0
+            || typeof this.cdp.registerChildSession !== "function"
+            || this.cdp.hasDebuggerSession?.(bridge.sessionId) === true) {
+            return this.resolveTargetContext(session, targetId);
+        }
+        this.cdp.registerChildSession(bridge.tabId, {
+            targetId: bridge.targetId,
+            type: bridge.type,
+            ...(typeof bridge.url === "string" ? { url: bridge.url } : {}),
+            ...(typeof bridge.title === "string" ? { title: bridge.title } : {}),
+            ...(typeof bridge.openerTargetId === "string" && !bridge.openerTargetId.startsWith("tab-")
+                ? { openerId: bridge.openerTargetId }
+                : {})
+        }, bridge.sessionId);
+        return this.resolveTargetContext(session, targetId);
+    }
+    findSyntheticSessionBridge(session, target) {
+        if (!target) {
+            return null;
+        }
+        const candidates = this.sessions
+            .listSyntheticTargets(session.id)
+            .filter((candidate) => typeof candidate.sessionId === "string" && candidate.sessionId.length > 0);
+        if (candidates.length === 0) {
+            return null;
+        }
+        const targetUrl = typeof target.url === "string" && target.url.length > 0 ? target.url : null;
+        const targetTitle = typeof target.title === "string" && target.title.length > 0 ? target.title : null;
+        let matches = targetUrl
+            ? candidates.filter((candidate) => candidate.url === targetUrl)
+            : [];
+        if (matches.length === 0 && targetTitle) {
+            matches = candidates.filter((candidate) => candidate.title === targetTitle);
+        }
+        else if (matches.length > 1 && targetTitle) {
+            const titledMatches = matches.filter((candidate) => candidate.title === targetTitle);
+            if (titledMatches.length > 0) {
+                matches = titledMatches;
+            }
+        }
+        if (matches.length === 0 && typeof target.openerTargetId === "string" && target.openerTargetId.length > 0) {
+            const targetOpenerTabId = parseTargetAliasTabId(target.openerTargetId);
+            matches = candidates.filter((candidate) => {
+                if (candidate.openerTargetId === target.openerTargetId) {
+                    return true;
+                }
+                const candidateOpenerTabId = parseTargetAliasTabId(candidate.openerTargetId);
+                return targetOpenerTabId !== null && candidateOpenerTabId === targetOpenerTabId;
+            });
+        }
+        if (matches.length === 0) {
+            return null;
+        }
+        if (matches.length === 1) {
+            return matches[0] ?? null;
+        }
+        return matches.sort((left, right) => right.attachedAt - left.attachedAt)[0] ?? null;
+    }
+    async attachTargetViaOpenerSession(session, target) {
+        if (typeof target.openerTargetId !== "string" || target.openerTargetId.length === 0) {
+            return false;
+        }
+        const opener = this.resolveTargetContext(session, target.openerTargetId)
+            ?? this.resolveTargetContext(session, session.targetId);
+        if (!opener) {
+            return false;
+        }
+        const openerBridgeDebuggee = { tabId: opener.tabId };
+        let targetsLookupFailedReason = null;
+        let targetInfos = [];
+        try {
+            const rawTargets = await this.cdp.sendCommand(openerBridgeDebuggee, "Target.getTargets", {}, { preserveTab: true });
+            targetInfos = isRecord(rawTargets) && Array.isArray(rawTargets.targetInfos)
+                ? rawTargets.targetInfos.map((entry) => extractTargetInfo(entry)).filter((entry) => entry !== null)
+                : [];
+        }
+        catch (error) {
+            targetsLookupFailedReason = error instanceof Error ? error.message : String(error);
+            targetInfos = [];
+        }
+        const pageTargets = targetInfos.filter((info) => info.type === "page");
+        const targetUrl = typeof target.url === "string" && target.url.length > 0 ? target.url : null;
+        const targetTitle = typeof target.title === "string" && target.title.length > 0 ? target.title : null;
+        let matcher = targetUrl ? "url" : undefined;
+        let matches = targetUrl
+            ? pageTargets.filter((info) => info.url === targetUrl)
+            : pageTargets;
+        if (matches.length === 0 && targetTitle) {
+            matches = pageTargets.filter((info) => info.title === targetTitle);
+            if (matches.length > 0) {
+                matcher = "title";
+            }
+        }
+        else if (matches.length > 1 && targetTitle) {
+            const titledMatches = matches.filter((info) => info.title === targetTitle);
+            if (titledMatches.length > 0) {
+                matches = titledMatches;
+                matcher = "title";
+            }
+        }
+        if (matches.length === 0 && typeof target.openerTargetId === "string" && target.openerTargetId.length > 0) {
+            const openerUrl = typeof opener.url === "string" && opener.url.length > 0 ? opener.url : null;
+            const openerTitle = typeof opener.title === "string" && opener.title.length > 0 ? opener.title : null;
+            const nonOpenerMatches = pageTargets.filter((info) => {
+                if (openerUrl && info.url === openerUrl) {
+                    return false;
+                }
+                if (openerTitle && info.title === openerTitle) {
+                    return false;
+                }
+                return true;
+            });
+            if (nonOpenerMatches.length === 1) {
+                matches = nonOpenerMatches;
+                matcher = "non_opener";
+            }
+        }
+        const popupTargetInfo = matches[0] ?? null;
+        const resolvedTabTargetId = popupTargetInfo?.targetId
+            ? null
+            : (typeof this.cdp.resolveTabTargetId === "function"
+                ? await this.cdp.resolveTabTargetId(target.tabId)
+                : null);
+        const popupTargetId = popupTargetInfo?.targetId ?? resolvedTabTargetId;
+        if (!popupTargetId) {
+            this.recordPopupAttachDiagnostic(session, target, {
+                stage: targetsLookupFailedReason ? "targets_lookup_failed" : "resolve_tab_target_failed",
+                ...(matcher ? { matcher } : {}),
+                ...(targetsLookupFailedReason ? { reason: targetsLookupFailedReason, targetsLookupFailed: true } : {})
+            });
+            return false;
+        }
+        if (resolvedTabTargetId) {
+            matcher = "resolve_tab_target_id";
+        }
+        const shouldRefreshAfterResolvedFallback = Boolean(resolvedTabTargetId
+            && typeof this.cdp.refreshTabAttachment === "function"
+            && ((targetsLookupFailedReason
+                && this.shouldRefreshPopupOpenerAfterLookupFailure(targetsLookupFailedReason))
+                || (popupTargetInfo === null && pageTargets.length === 0)));
+        let refreshDiagnostic = null;
+        let refreshReasonOverride = null;
+        if (shouldRefreshAfterResolvedFallback) {
+            try {
+                await this.cdp.refreshTabAttachment(opener.tabId);
+            }
+            catch (error) {
+                refreshDiagnostic = this.cdp.getLastRootRefreshDiagnostic?.(opener.tabId) ?? null;
+                const refreshReason = error instanceof Error ? error.message : String(error);
+                const canProceedWithRetainedRoot = Boolean(refreshDiagnostic?.rootSessionPresentAfterRefresh
+                    && refreshDiagnostic?.rootTargetIdAfterRefresh
+                    && refreshReason.includes("Not allowed"));
+                if (canProceedWithRetainedRoot) {
+                    refreshReasonOverride = refreshReason;
+                }
+                else {
+                    this.recordPopupAttachDiagnostic(session, target, {
+                        stage: "raw_attach_failed",
+                        popupTargetId,
+                        ...(matcher ? { matcher } : {}),
+                        ...this.toPopupRefreshDiagnostic(refreshDiagnostic),
+                        ...(targetsLookupFailedReason ? { targetsLookupFailed: true } : {}),
+                        reason: refreshReason
+                    });
+                    return false;
+                }
+            }
+            refreshDiagnostic = this.cdp.getLastRootRefreshDiagnostic?.(opener.tabId) ?? null;
+        }
+        let sessionId = null;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                sessionId = typeof this.cdp.attachChildTarget === "function"
+                    ? await this.cdp.attachChildTarget(opener.tabId, popupTargetId)
+                    : await this.cdp.sendCommand(openerBridgeDebuggee, "Target.attachToTarget", {
+                        targetId: popupTargetId,
+                        flatten: true
+                    }).then((attached) => isRecord(attached) && typeof attached.sessionId === "string" ? attached.sessionId : null);
             }
-            releaseQueue();
-            const depth = (session.targetQueueDepth.get(targetId) ?? 1) - 1;
-            if (depth <= 0) {
-                session.targetQueueDepth.delete(targetId);
-                session.targetQueueOldestAt.delete(targetId);
+            catch (error) {
+                const routerDiagnostic = this.cdp.getLastChildAttachDiagnostic(opener.tabId, popupTargetId);
+                const stage = routerDiagnostic?.stage ?? "attached_root_attach_failed";
+                if (attempt === 0 && this.shouldRetryPopupAttachStage(stage)) {
+                    await this.waitForPopupAttachRetry();
+                    continue;
+                }
+                this.recordPopupAttachDiagnostic(session, target, {
+                    stage,
+                    popupTargetId,
+                    ...(matcher ? { matcher } : {}),
+                    ...this.toPopupChildAttachDiagnostic(routerDiagnostic),
+                    ...this.toPopupRefreshDiagnostic(refreshDiagnostic),
+                    ...(refreshReasonOverride ? { refreshReason: refreshReasonOverride } : {}),
+                    ...(targetsLookupFailedReason ? { targetsLookupFailed: true } : {}),
+                    reason: routerDiagnostic?.reason ?? (error instanceof Error ? error.message : String(error))
+                });
+                return false;
             }
-            else {
-                session.targetQueueDepth.set(targetId, depth);
+            if (sessionId) {
+                break;
             }
-            session.pendingParallel = Math.max(0, session.pendingParallel - 1);
-            if (session.targetQueues.get(targetId) === tail) {
-                session.targetQueues.delete(targetId);
+            const routerDiagnostic = this.cdp.getLastChildAttachDiagnostic(opener.tabId, popupTargetId);
+            const stage = routerDiagnostic?.stage ?? "attached_root_attach_null";
+            if (attempt === 0 && this.shouldRetryPopupAttachStage(stage)) {
+                await this.waitForPopupAttachRetry();
+                continue;
             }
+            this.recordPopupAttachDiagnostic(session, target, {
+                stage,
+                popupTargetId,
+                ...(matcher ? { matcher } : {}),
+                ...this.toPopupChildAttachDiagnostic(routerDiagnostic),
+                ...this.toPopupRefreshDiagnostic(refreshDiagnostic),
+                ...(refreshReasonOverride ? { refreshReason: refreshReasonOverride } : {}),
+                ...(targetsLookupFailedReason ? { targetsLookupFailed: true } : {}),
+                ...(routerDiagnostic?.reason ? { reason: routerDiagnostic.reason } : {})
+            });
+            return false;
+        }
+        this.sessions.upsertSyntheticTarget(session.id, {
+            targetId: popupTargetId,
+            tabId: opener.tabId,
+            type: popupTargetInfo?.type ?? "page",
+            ...(typeof popupTargetInfo?.url === "string" ? { url: popupTargetInfo.url } : targetUrl ? { url: targetUrl } : {}),
+            ...(typeof popupTargetInfo?.title === "string" ? { title: popupTargetInfo.title } : targetTitle ? { title: targetTitle } : {}),
+            sessionId: sessionId ?? undefined,
+            openerTargetId: target.openerTargetId,
+            attachedAt: Date.now()
+        });
+        if (sessionId
+            && popupTargetInfo
+            && typeof this.cdp.registerChildSession === "function") {
+            this.cdp.registerChildSession(opener.tabId, popupTargetInfo, sessionId);
         }
+        this.clearPopupAttachDiagnostic(session.id, target.targetId);
+        return true;
     }
-    getSessionForMessage(message, clientId) {
-        const opsSessionId = message.opsSessionId;
-        if (!opsSessionId) {
-            this.sendError(message, buildError("invalid_request", "Missing opsSessionId", false));
-            return null;
+    popupAttachDiagnosticKey(sessionId, targetId) {
+        return `${sessionId}:${targetId}`;
+    }
+    shouldRefreshPopupOpenerAfterLookupFailure(reason) {
+        return reason.includes("Debugger is not attached")
+            || reason.includes("No tab attached")
+            || reason.includes("Detached while handling command");
+    }
+    shouldRetryPopupAttachStage(stage) {
+        return stage === "raw_attach_failed"
+            || stage === "attached_root_unavailable"
+            || stage === "attached_root_attach_null"
+            || stage === "attached_root_attach_failed";
+    }
+    async waitForPopupAttachRetry() {
+        await new Promise((resolve) => setTimeout(resolve, POPUP_ATTACH_RETRY_DELAY_MS));
+    }
+    toPopupChildAttachDiagnostic(diagnostic) {
+        if (!diagnostic) {
+            return {};
         }
-        const session = this.sessions.get(opsSessionId);
-        if (!session) {
-            this.sendError(message, buildError("invalid_session", "Unknown ops session", false));
-            return null;
+        return {
+            ...(diagnostic.initialStage ? { initialStage: diagnostic.initialStage } : {}),
+            ...(diagnostic.rootTargetRetryStage ? { rootTargetRetryStage: diagnostic.rootTargetRetryStage } : {}),
+            ...(diagnostic.attachedRootRecoveryStage
+                ? { attachedRootRecoveryStage: diagnostic.attachedRootRecoveryStage }
+                : {}),
+            ...(diagnostic.attachedRootRecoverySource
+                ? { attachedRootRecoverySource: diagnostic.attachedRootRecoverySource }
+                : {}),
+            ...(diagnostic.attachedRootRecoveryAttachTargetId
+                ? { attachedRootRecoveryAttachTargetId: diagnostic.attachedRootRecoveryAttachTargetId }
+                : {}),
+            ...(typeof diagnostic.attachedRootRecoveryRetriedAfterRegisterRoot === "boolean"
+                ? { attachedRootRecoveryRetriedAfterRegisterRoot: diagnostic.attachedRootRecoveryRetriedAfterRegisterRoot }
+                : {}),
+            ...(typeof diagnostic.attachedRootRecoveryRegisterRootChanged === "boolean"
+                ? { attachedRootRecoveryRegisterRootChanged: diagnostic.attachedRootRecoveryRegisterRootChanged }
+                : {}),
+            ...(typeof diagnostic.attachedRootRecoveryRegisterRootAttachTargetChanged === "boolean"
+                ? { attachedRootRecoveryRegisterRootAttachTargetChanged: diagnostic.attachedRootRecoveryRegisterRootAttachTargetChanged }
+                : {}),
+            ...(typeof diagnostic.attachedRootRecoveryRegisterAttachedRootSessionCalled === "boolean"
+                ? {
+                    attachedRootRecoveryRegisterAttachedRootSessionCalled: diagnostic.attachedRootRecoveryRegisterAttachedRootSessionCalled
+                }
+                : {}),
+            ...(diagnostic.attachedRootUnavailableTerminalBranch
+                ? { attachedRootUnavailableTerminalBranch: diagnostic.attachedRootUnavailableTerminalBranch }
+                : {}),
+            ...(diagnostic.reattachRecoveryStage
+                ? { reattachRecoveryStage: diagnostic.reattachRecoveryStage }
+                : {}),
+            ...(diagnostic.reattachRecoveryReason
+                ? { reattachRecoveryReason: diagnostic.reattachRecoveryReason }
+                : {}),
+            ...(diagnostic.attachedRootRecoveryReason
+                ? { attachedRootRecoveryReason: diagnostic.attachedRootRecoveryReason }
+                : {})
+        };
+    }
+    formatCdpFailureDiagnosticSuffix(details) {
+        if (details?.phase === "strict_enablement" && details.enablementStage) {
+            return ` (phase: ${details.phase}; stage: ${details.enablementStage})`;
         }
-        if (session.state === "closing") {
-            const leaseId = typeof message.leaseId === "string" ? message.leaseId : "";
-            if (leaseId && leaseId === session.leaseId) {
-                this.reclaimSession(session, clientId);
-            }
-            else {
-                this.sendError(message, buildError("not_owner", "Client does not own session", false));
-                return null;
-            }
+        if (!details?.stage) {
+            return "";
         }
-        if (session.ownerClientId !== clientId) {
-            this.sendError(message, buildError("not_owner", "Client does not own session", false));
-            return null;
+        return ` (origin: ${details.origin}; stage: ${details.stage})`;
+    }
+    toDirectAttachDiagnosticDetails(diagnostic) {
+        if (!diagnostic) {
+            return undefined;
         }
-        if (typeof message.leaseId !== "string" || message.leaseId !== session.leaseId) {
-            this.sendError(message, buildError("not_owner", "Lease does not match session owner", false));
-            return null;
+        return {
+            origin: diagnostic.origin,
+            stage: diagnostic.stage,
+            attachBy: diagnostic.attachBy,
+            ...(diagnostic.probeMethod ? { probeMethod: diagnostic.probeMethod } : {}),
+            ...(diagnostic.reason ? { reason: diagnostic.reason } : {})
+        };
+    }
+    decorateDirectAttachError(error, diagnostic) {
+        const detail = this.getCdpFailureMessage(error);
+        if (!diagnostic) {
+            return error instanceof Error ? error : new Error(detail);
         }
-        session.lastUsedAt = Date.now();
-        return session;
+        return this.decorateCdpFailure(error, this.toDirectAttachDiagnosticDetails(diagnostic) ?? {});
     }
-    requestedTargetId(session, message) {
-        const payload = isRecord(message.payload) ? message.payload : {};
-        if (typeof payload.targetId === "string" && payload.targetId.trim().length > 0) {
-            return payload.targetId.trim();
+    getCdpFailureMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (error && typeof error === "object" && "message" in error) {
+            const message = error.message;
+            if (typeof message === "string") {
+                if ("code" in error) {
+                    const code = error.code;
+                    return typeof code === "number"
+                        ? JSON.stringify({ code, message })
+                        : message;
+                }
+                return message;
+            }
+        }
+        return "Debugger attach failed";
+    }
+    decorateCdpFailure(error, details) {
+        const detail = this.getCdpFailureMessage(error);
+        const decorated = error instanceof Error ? error : new Error(detail);
+        const mergedDetails = {
+            ...(decorated.directAttachDetails ?? {}),
+            ...details,
+            ...(details.reason ? {} : { reason: detail })
+        };
+        const suffix = this.formatCdpFailureDiagnosticSuffix(mergedDetails);
+        decorated.message = suffix.length > 0 && detail.endsWith(suffix)
+            ? detail
+            : `${detail}${suffix}`;
+        decorated.directAttachDetails = mergedDetails;
+        return decorated;
+    }
+    getDirectAttachErrorDetails(error) {
+        if (!(error instanceof Error)) {
+            return undefined;
+        }
+        const decorated = error;
+        return decorated.directAttachDetails;
+    }
+    getPopupAttachDiagnostic(sessionId, targetId) {
+        return this.popupAttachDiagnostics.get(this.popupAttachDiagnosticKey(sessionId, targetId)) ?? null;
+    }
+    clearPopupAttachDiagnostic(sessionId, targetId) {
+        this.popupAttachDiagnostics.delete(this.popupAttachDiagnosticKey(sessionId, targetId));
+    }
+    recordPopupAttachDiagnostic(session, target, diagnostic) {
+        const entry = {
+            targetId: target.targetId,
+            tabId: target.tabId,
+            ...(target.openerTargetId ? { openerTargetId: target.openerTargetId } : {}),
+            at: Date.now(),
+            ...diagnostic
+        };
+        this.popupAttachDiagnostics.set(this.popupAttachDiagnosticKey(session.id, target.targetId), entry);
+        logError("ops.popup_attach_stage", new Error(entry.stage), {
+            code: "popup_attach_stage",
+            extra: {
+                targetId: entry.targetId,
+                tabId: entry.tabId,
+                ...(entry.openerTargetId ? { openerTargetId: entry.openerTargetId } : {}),
+                ...(entry.popupTargetId ? { popupTargetId: entry.popupTargetId } : {}),
+                ...(entry.matcher ? { matcher: entry.matcher } : {}),
+                ...(entry.initialStage ? { initialStage: entry.initialStage } : {}),
+                ...(entry.rootTargetRetryStage ? { rootTargetRetryStage: entry.rootTargetRetryStage } : {}),
+                ...(entry.attachedRootRecoveryStage ? { attachedRootRecoveryStage: entry.attachedRootRecoveryStage } : {}),
+                ...(entry.attachedRootRecoverySource ? { attachedRootRecoverySource: entry.attachedRootRecoverySource } : {}),
+                ...(entry.attachedRootRecoveryAttachTargetId
+                    ? { attachedRootRecoveryAttachTargetId: entry.attachedRootRecoveryAttachTargetId }
+                    : {}),
+                ...(typeof entry.attachedRootRecoveryRetriedAfterRegisterRoot === "boolean"
+                    ? { attachedRootRecoveryRetriedAfterRegisterRoot: entry.attachedRootRecoveryRetriedAfterRegisterRoot }
+                    : {}),
+                ...(typeof entry.attachedRootRecoveryRegisterRootChanged === "boolean"
+                    ? { attachedRootRecoveryRegisterRootChanged: entry.attachedRootRecoveryRegisterRootChanged }
+                    : {}),
+                ...(typeof entry.attachedRootRecoveryRegisterRootAttachTargetChanged === "boolean"
+                    ? { attachedRootRecoveryRegisterRootAttachTargetChanged: entry.attachedRootRecoveryRegisterRootAttachTargetChanged }
+                    : {}),
+                ...(typeof entry.attachedRootRecoveryRegisterAttachedRootSessionCalled === "boolean"
+                    ? {
+                        attachedRootRecoveryRegisterAttachedRootSessionCalled: entry.attachedRootRecoveryRegisterAttachedRootSessionCalled
+                    }
+                    : {}),
+                ...(entry.attachedRootUnavailableTerminalBranch
+                    ? { attachedRootUnavailableTerminalBranch: entry.attachedRootUnavailableTerminalBranch }
+                    : {}),
+                ...(entry.reattachRecoveryStage ? { reattachRecoveryStage: entry.reattachRecoveryStage } : {}),
+                ...(entry.reattachRecoveryReason ? { reattachRecoveryReason: entry.reattachRecoveryReason } : {}),
+                ...(entry.attachedRootRecoveryReason ? { attachedRootRecoveryReason: entry.attachedRootRecoveryReason } : {}),
+                ...(entry.refreshPath ? { refreshPath: entry.refreshPath } : {}),
+                ...(typeof entry.refreshCompleted === "boolean" ? { refreshCompleted: entry.refreshCompleted } : {}),
+                ...(typeof entry.refreshDebuggeePresent === "boolean" ? { refreshDebuggeePresent: entry.refreshDebuggeePresent } : {}),
+                ...(typeof entry.refreshRootSessionPresent === "boolean"
+                    ? { refreshRootSessionPresent: entry.refreshRootSessionPresent }
+                    : {}),
+                ...(entry.refreshRootTargetId ? { refreshRootTargetId: entry.refreshRootTargetId } : {}),
+                ...(entry.refreshProbeMethod ? { refreshProbeMethod: entry.refreshProbeMethod } : {}),
+                ...(entry.refreshProbeStage ? { refreshProbeStage: entry.refreshProbeStage } : {}),
+                ...(entry.refreshProbeReason ? { refreshProbeReason: entry.refreshProbeReason } : {}),
+                ...(entry.refreshReason ? { refreshReason: entry.refreshReason } : {}),
+                ...(entry.targetsLookupFailed ? { targetsLookupFailed: true } : {}),
+                ...(entry.reason ? { reason: entry.reason } : {})
+            }
+        });
+    }
+    toPopupRefreshDiagnostic(diagnostic) {
+        if (!diagnostic) {
+            return {};
         }
-        return session.activeTargetId || null;
+        return {
+            refreshPath: diagnostic.path,
+            refreshCompleted: diagnostic.refreshCompleted,
+            refreshDebuggeePresent: diagnostic.debuggeePresentAfterRefresh,
+            refreshRootSessionPresent: diagnostic.rootSessionPresentAfterRefresh,
+            ...(diagnostic.rootTargetIdAfterRefresh ? { refreshRootTargetId: diagnostic.rootTargetIdAfterRefresh } : {}),
+            refreshProbeMethod: diagnostic.probeMethod,
+            refreshProbeStage: diagnostic.probeStage,
+            ...(diagnostic.probeReason ? { refreshProbeReason: diagnostic.probeReason } : {}),
+            ...(diagnostic.reason ? { refreshReason: diagnostic.reason } : {})
+        };
     }
     requireActiveTarget(session, message) {
-        const targetId = this.requestedTargetId(session, message);
+        const explicitTargetId = this.extractPayloadTargetId(message.payload);
+        const targetId = explicitTargetId ?? session.activeTargetId ?? session.targetId;
         if (!targetId) {
             this.sendError(message, buildError("invalid_request", "No active target", false));
             return null;
         }
-        const target = session.targets.get(targetId);
+        const target = this.resolveRequestedTargetContext(session, targetId, explicitTargetId !== null);
         if (!target) {
             this.sendError(message, buildError("invalid_request", "Active target missing", false));
             return null;
         }
         if (target.url) {
             const restriction = isRestrictedUrl(target.url);
-            if (restriction.restricted && !this.isAllowedCanvasTargetUrl(target.url)) {
+            if (restriction.restricted && !this.isAllowedCanvasRestrictionTarget(session, targetId, target)) {
                 this.sendError(message, buildError("restricted_url", restriction.message ?? "Restricted tab.", false));
                 return null;
             }
         }
-        return { tabId: target.tabId, targetId: target.targetId, url: target.url };
+        if (target.synthetic && !target.sessionId && !this.isSyntheticRootPreviewTarget(session, targetId, target)) {
+            this.sendPopupAttachPendingError(message, session, targetId);
+            return null;
+        }
+        if (target.openerTargetId && !this.hasUsableDebuggee(target)) {
+            this.sendPopupAttachPendingError(message, session, targetId);
+            return null;
+        }
+        return target;
+    }
+    isAllowedCanvasRestrictionTarget(session, targetId, target) {
+        if (this.isAllowedCanvasTargetUrl(target.url)) {
+            return true;
+        }
+        if (isHtmlDataUrl(target.url ?? "") && this.isRegisteredCanvasTarget(session, targetId)) {
+            return true;
+        }
+        return this.isSyntheticRootPreviewTarget(session, targetId, target)
+            && isHtmlDataUrl(target.url ?? "");
+    }
+    isRegisteredCanvasTarget(session, targetId) {
+        return this.isAllowedCanvasTargetUrl(session.targets.get(targetId)?.url);
+    }
+    isSyntheticRootPreviewTarget(session, _targetId, target) {
+        const rootSynthetic = this.sessions.getSyntheticTarget(session.id, session.targetId);
+        const effectiveUrl = target.url ?? rootSynthetic?.url;
+        return isHtmlDataUrl(rootSynthetic?.url ?? "")
+            && isHtmlDataUrl(effectiveUrl ?? "")
+            && !rootSynthetic?.openerTargetId
+            && rootSynthetic?.tabId === session.tabId
+            && !target.openerTargetId
+            && target.tabId === session.tabId;
     }
     isAllowedCanvasTargetUrl(rawUrl) {
         if (typeof rawUrl !== "string" || rawUrl.length === 0) {
@@ -1517,7 +3702,73 @@ export class OpsRuntime {
             return null;
         }
     }
-    resolveSelector(session, refOrPayload, message) {
+    resolveRefContext(session, ref, targetId) {
+        const target = this.resolveTargetContext(session, targetId);
+        if (!target) {
+            return null;
+        }
+        const entry = session.refStore.resolve(targetId, ref);
+        if (!entry) {
+            return null;
+        }
+        const snapshotId = session.refStore.getSnapshotId(targetId);
+        if (!snapshotId || entry.snapshotId !== snapshotId) {
+            return null;
+        }
+        return {
+            target,
+            ref,
+            selector: entry.selector,
+            backendNodeId: entry.backendNodeId,
+            snapshotId: entry.snapshotId,
+            ...(entry.frameId ? { frameId: entry.frameId } : {}),
+            ...(entry.role ? { role: entry.role } : {}),
+            ...(entry.name ? { name: entry.name } : {})
+        };
+    }
+    async captureSnapshotPayload(message, session, options) {
+        const explicitTargetId = this.extractPayloadTargetId(message.payload);
+        if (explicitTargetId) {
+            try {
+                await this.preparePopupTarget(session, explicitTargetId);
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : "Debugger attach failed";
+                this.sendError(message, buildError("cdp_attach_failed", detail, false, this.getDirectAttachErrorDetails(error)));
+                return null;
+            }
+        }
+        const target = this.requireActiveTarget(session, message);
+        if (!target)
+            return null;
+        const start = Date.now();
+        const entriesData = await buildSnapshot((method, params) => this.cdp.sendCommand(target.debuggee, method, params), options.mode, () => session.refStore.nextRef(target.targetId), options.mode !== "actionables", options.maxNodes);
+        const snapshot = session.refStore.setSnapshot(target.targetId, entriesData.entries);
+        const startIndex = parseCursor(options.cursor);
+        const { content, truncated, nextCursor } = paginate(entriesData.lines, startIndex, options.maxChars);
+        const contentBytes = this.encoder.encode(content).length;
+        if (contentBytes > MAX_SNAPSHOT_BYTES) {
+            this.sendError(message, buildError("snapshot_too_large", "Snapshot exceeded max size.", false, {
+                maxSnapshotBytes: MAX_SNAPSHOT_BYTES,
+                actualBytes: contentBytes
+            }));
+            return null;
+        }
+        const tab = await this.tabs.getTab(target.tabId);
+        return {
+            target,
+            snapshotId: snapshot.snapshotId,
+            url: resolveReportedTargetUrl(target, tab),
+            title: resolveReportedTargetTitle(target, tab),
+            content,
+            truncated,
+            ...(nextCursor ? { nextCursor } : {}),
+            refCount: snapshot.count,
+            timingMs: Date.now() - start,
+            warnings: entriesData.warnings
+        };
+    }
+    resolveRefFromPayload(session, refOrPayload, message) {
         const ref = typeof refOrPayload === "string"
             ? refOrPayload
             : (isRecord(refOrPayload) && typeof refOrPayload.ref === "string" ? refOrPayload.ref : null);
@@ -1530,12 +3781,183 @@ export class OpsRuntime {
             this.sendError(message, buildError("invalid_request", "No active target", false));
             return null;
         }
-        const entry = session.refStore.resolve(targetId, ref);
-        if (!entry) {
-            this.sendError(message, buildError("invalid_request", `Unknown ref: ${ref}`, false));
+        const resolved = this.resolveRefContext(session, ref, targetId);
+        if (!resolved) {
+            this.sendError(message, buildError("invalid_request", `Unknown ref: ${ref}. Take a new snapshot first.`, false));
+            return null;
+        }
+        if (resolved.target.synthetic && !resolved.target.sessionId) {
+            this.sendPopupAttachPendingError(message, session, resolved.target.targetId);
             return null;
         }
-        return entry.selector;
+        return resolved;
+    }
+    formatPopupAttachDiagnosticSuffix(diagnostic) {
+        if (!diagnostic?.stage) {
+            return "";
+        }
+        const parts = [`stage: ${diagnostic.stage}`];
+        if (diagnostic.rootTargetRetryStage) {
+            parts.push(`root-target-retry: ${diagnostic.rootTargetRetryStage}`);
+        }
+        if (diagnostic.attachedRootRecoveryStage) {
+            const attachedRootPart = diagnostic.attachedRootRecoverySource
+                ? `${diagnostic.attachedRootRecoveryStage} via ${diagnostic.attachedRootRecoverySource}`
+                : diagnostic.attachedRootRecoveryStage;
+            parts.push(`attached-root: ${attachedRootPart}`);
+        }
+        if (diagnostic.attachedRootUnavailableTerminalBranch) {
+            parts.push(`terminal: ${diagnostic.attachedRootUnavailableTerminalBranch}`);
+        }
+        return ` (${parts.join("; ")})`;
+    }
+    sendPopupAttachPendingError(message, session, targetId) {
+        const diagnostic = session && typeof targetId === "string"
+            ? this.getPopupAttachDiagnostic(session.id, targetId)
+            : null;
+        const stageSuffix = this.formatPopupAttachDiagnosticSuffix(diagnostic);
+        this.sendError(message, buildError("execution_failed", `Popup target has not finished attaching yet${stageSuffix}. Take a new review or snapshot and retry.`, true, diagnostic
+            ? {
+                stage: diagnostic.stage,
+                ...(diagnostic.popupTargetId ? { popupTargetId: diagnostic.popupTargetId } : {}),
+                ...(diagnostic.matcher ? { matcher: diagnostic.matcher } : {}),
+                ...(diagnostic.initialStage ? { initialStage: diagnostic.initialStage } : {}),
+                ...(diagnostic.rootTargetRetryStage ? { rootTargetRetryStage: diagnostic.rootTargetRetryStage } : {}),
+                ...(diagnostic.attachedRootRecoveryStage
+                    ? { attachedRootRecoveryStage: diagnostic.attachedRootRecoveryStage }
+                    : {}),
+                ...(diagnostic.attachedRootRecoverySource
+                    ? { attachedRootRecoverySource: diagnostic.attachedRootRecoverySource }
+                    : {}),
+                ...(diagnostic.attachedRootRecoveryAttachTargetId
+                    ? { attachedRootRecoveryAttachTargetId: diagnostic.attachedRootRecoveryAttachTargetId }
+                    : {}),
+                ...(typeof diagnostic.attachedRootRecoveryRetriedAfterRegisterRoot === "boolean"
+                    ? { attachedRootRecoveryRetriedAfterRegisterRoot: diagnostic.attachedRootRecoveryRetriedAfterRegisterRoot }
+                    : {}),
+                ...(typeof diagnostic.attachedRootRecoveryRegisterRootChanged === "boolean"
+                    ? { attachedRootRecoveryRegisterRootChanged: diagnostic.attachedRootRecoveryRegisterRootChanged }
+                    : {}),
+                ...(typeof diagnostic.attachedRootRecoveryRegisterRootAttachTargetChanged === "boolean"
+                    ? {
+                        attachedRootRecoveryRegisterRootAttachTargetChanged: diagnostic.attachedRootRecoveryRegisterRootAttachTargetChanged
+                    }
+                    : {}),
+                ...(typeof diagnostic.attachedRootRecoveryRegisterAttachedRootSessionCalled === "boolean"
+                    ? {
+                        attachedRootRecoveryRegisterAttachedRootSessionCalled: diagnostic.attachedRootRecoveryRegisterAttachedRootSessionCalled
+                    }
+                    : {}),
+                ...(diagnostic.attachedRootUnavailableTerminalBranch
+                    ? { attachedRootUnavailableTerminalBranch: diagnostic.attachedRootUnavailableTerminalBranch }
+                    : {}),
+                ...(diagnostic.reattachRecoveryStage
+                    ? { reattachRecoveryStage: diagnostic.reattachRecoveryStage }
+                    : {}),
+                ...(diagnostic.reattachRecoveryReason
+                    ? { reattachRecoveryReason: diagnostic.reattachRecoveryReason }
+                    : {}),
+                ...(diagnostic.attachedRootRecoveryReason
+                    ? { attachedRootRecoveryReason: diagnostic.attachedRootRecoveryReason }
+                    : {}),
+                ...(diagnostic.refreshPath ? { refreshPath: diagnostic.refreshPath } : {}),
+                ...(typeof diagnostic.refreshCompleted === "boolean" ? { refreshCompleted: diagnostic.refreshCompleted } : {}),
+                ...(typeof diagnostic.refreshDebuggeePresent === "boolean"
+                    ? { refreshDebuggeePresent: diagnostic.refreshDebuggeePresent }
+                    : {}),
+                ...(typeof diagnostic.refreshRootSessionPresent === "boolean"
+                    ? { refreshRootSessionPresent: diagnostic.refreshRootSessionPresent }
+                    : {}),
+                ...(diagnostic.refreshRootTargetId ? { refreshRootTargetId: diagnostic.refreshRootTargetId } : {}),
+                ...(diagnostic.refreshProbeMethod ? { refreshProbeMethod: diagnostic.refreshProbeMethod } : {}),
+                ...(diagnostic.refreshProbeStage ? { refreshProbeStage: diagnostic.refreshProbeStage } : {}),
+                ...(diagnostic.refreshProbeReason ? { refreshProbeReason: diagnostic.refreshProbeReason } : {}),
+                ...(diagnostic.refreshReason ? { refreshReason: diagnostic.refreshReason } : {}),
+                ...(diagnostic.targetsLookupFailed ? { targetsLookupFailed: true } : {}),
+                ...(diagnostic.reason ? { reason: diagnostic.reason } : {})
+            }
+            : undefined));
+    }
+    resolveSelector(session, refOrPayload, message) {
+        return this.resolveRefFromPayload(session, refOrPayload, message)?.selector ?? null;
+    }
+    async callFunctionOnRef(resolved, functionDeclaration, args = [], ref = resolved.ref) {
+        try {
+            const resolvedNode = await this.cdp.sendCommand(resolved.target.debuggee, "DOM.resolveNode", {
+                backendNodeId: resolved.backendNodeId
+            });
+            const objectId = resolvedNode.object?.objectId;
+            if (!objectId) {
+                throw buildStaleSnapshotError(ref);
+            }
+            const result = await this.cdp.sendCommand(resolved.target.debuggee, "Runtime.callFunctionOn", {
+                objectId,
+                functionDeclaration,
+                arguments: args.map((value) => ({ value })),
+                returnByValue: true
+            });
+            if (result.exceptionDetails) {
+                throw new Error(result.exceptionDetails.text ?? "Runtime.callFunctionOn failed");
+            }
+            return result.result?.value;
+        }
+        catch (error) {
+            if (isSnapshotStaleMessage(error)) {
+                throw buildStaleSnapshotError(ref);
+            }
+            throw error;
+        }
+    }
+    async resolveRefPoint(resolved) {
+        try {
+            const box = await this.cdp.sendCommand(resolved.target.debuggee, "DOM.getBoxModel", {
+                backendNodeId: resolved.backendNodeId
+            });
+            const quad = Array.isArray(box.model?.content) ? box.model?.content : [];
+            if (quad.length >= 8) {
+                const xs = [quad[0], quad[2], quad[4], quad[6]].filter((value) => typeof value === "number");
+                const ys = [quad[1], quad[3], quad[5], quad[7]].filter((value) => typeof value === "number");
+                if (xs.length === 4 && ys.length === 4) {
+                    return {
+                        x: Math.round((Math.min(...xs) + Math.max(...xs)) / 2),
+                        y: Math.round((Math.min(...ys) + Math.max(...ys)) / 2)
+                    };
+                }
+            }
+        }
+        catch (error) {
+            if (isSnapshotStaleMessage(error)) {
+                throw buildStaleSnapshotError(resolved.ref);
+            }
+        }
+        const point = await this.callFunctionOnRef(resolved, DOM_REF_POINT_DECLARATION);
+        const x = typeof point?.x === "number" && Number.isFinite(point.x) ? Math.round(point.x) : null;
+        const y = typeof point?.y === "number" && Number.isFinite(point.y) ? Math.round(point.y) : null;
+        if (x === null || y === null) {
+            throw new Error(`Could not resolve a clickable point for ref: ${resolved.ref}`);
+        }
+        return { x, y };
+    }
+    normalizeScreenshotClip(value, ref) {
+        const x = typeof value?.x === "number" && Number.isFinite(value.x) ? value.x : null;
+        const y = typeof value?.y === "number" && Number.isFinite(value.y) ? value.y : null;
+        const width = typeof value?.width === "number" && Number.isFinite(value.width) ? value.width : null;
+        const height = typeof value?.height === "number" && Number.isFinite(value.height) ? value.height : null;
+        if (x === null || y === null || width === null || height === null || width <= 0 || height <= 0) {
+            throw new Error(`Could not resolve screenshot bounds for ref: ${ref}`);
+        }
+        return { x, y, width, height, scale: 1 };
+    }
+    async waitForFileChooser(sessionId, targetId, timeoutMs = SCREENSHOT_TIMEOUT_MS) {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < timeoutMs) {
+            const chooser = this.sessions.getFileChooser(sessionId, targetId);
+            if (chooser?.open) {
+                return chooser;
+            }
+            await delay(50);
+        }
+        throw new Error("File chooser did not open");
     }
     async waitForSelector(target, selector, state, timeoutMs) {
         const start = Date.now();
@@ -1551,6 +3973,22 @@ export class OpsRuntime {
         }
         throw new Error("Wait for selector timed out");
     }
+    async waitForRefState(resolved, state, timeoutMs) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            const snapshot = await this.callFunctionOnRef(resolved, DOM_SELECTOR_STATE_DECLARATION);
+            const attached = snapshot?.attached === true;
+            const visible = snapshot?.visible === true;
+            if (state === "attached" && attached)
+                return;
+            if (state === "visible" && visible)
+                return;
+            if (state === "hidden" && (!attached || !visible))
+                return;
+            await delay(200);
+        }
+        throw new Error("Wait for selector timed out");
+    }
     cleanupSession(session, event) {
         this.clearClosingTimer(session.id);
         const waiters = this.parallelWaiters.get(session.id);
@@ -1568,13 +4006,7 @@ export class OpsRuntime {
         for (const target of session.targets.values()) {
             void this.cdp.detachTab(target.tabId).catch(() => undefined);
         }
-        this.sendEvent({
-            type: "ops_event",
-            clientId: session.ownerClientId,
-            opsSessionId: session.id,
-            event,
-            payload: { tabId: session.tabId, targetId: session.targetId }
-        });
+        this.emitSessionEvent(session, event);
     }
     handleClosedTarget(tabId, event) {
         const session = this.sessions.getByTabId(tabId);
@@ -1590,7 +4022,7 @@ export class OpsRuntime {
             this.cleanupSession(session, event);
         }
     }
-    handleDebuggerDetachForTab(tabId) {
+    async handleDebuggerDetachForTab(tabId) {
         const session = this.sessions.getByTabId(tabId);
         if (!session)
             return;
@@ -1598,6 +4030,21 @@ export class OpsRuntime {
             // Root tab detach can be transient during child-target shutdown; tab removal handler owns root teardown.
             return;
         }
+        const targetId = this.sessions.getTargetIdByTabId(session.id, tabId);
+        const target = targetId ? session.targets.get(targetId) ?? null : null;
+        const liveTab = await this.tabs.getTab(tabId);
+        if (target && this.isAllowedCanvasTargetUrl(target.url ?? liveTab?.url)) {
+            if (liveTab && targetId) {
+                session.targets.set(targetId, {
+                    ...target,
+                    url: liveTab.url ?? target.url,
+                    title: liveTab.title ?? target.title
+                });
+            }
+            // Design tabs can detach transiently while the extension page stays open; retain the target so `/ops`
+            // can reattach it later via `targets.use`.
+            return;
+        }
         this.handleClosedTarget(tabId, "ops_session_closed");
     }
     async closeTabBestEffort(tabId) {
@@ -1675,9 +4122,19 @@ export class OpsRuntime {
     sendEvent(event) {
         this.sendEnvelope(event);
     }
+    emitSessionEvent(session, event) {
+        this.sendEvent({
+            type: "ops_event",
+            clientId: session.ownerClientId,
+            opsSessionId: session.id,
+            event,
+            payload: { tabId: session.tabId, targetId: session.targetId }
+        });
+    }
     markSessionClosing(session, reason) {
-        if (session.state === "closing")
-            return;
+        if (session.state === "closing") {
+            return false;
+        }
         session.state = "closing";
         session.closingReason = reason;
         session.expiresAt = Date.now() + SESSION_TTL_MS;
@@ -1689,13 +4146,18 @@ export class OpsRuntime {
             }
         }, SESSION_TTL_MS);
         this.closingTimers.set(session.id, timeoutId);
+        return true;
     }
     reclaimSession(session, clientId) {
+        const wasClosing = session.state === "closing";
         session.ownerClientId = clientId;
         session.state = "active";
         session.expiresAt = undefined;
         session.closingReason = undefined;
         this.clearClosingTimer(session.id);
+        if (wasClosing) {
+            this.emitSessionEvent(session, "ops_session_reclaimed");
+        }
     }
     clearClosingTimer(sessionId) {
         const timer = this.closingTimers.get(sessionId);
@@ -1909,6 +4371,18 @@ const toCookieListRecord = (entry) => {
 const isRecord = (value) => {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
 };
+const parseCanvasOverlaySelection = (value, targetId) => {
+    const record = isRecord(value) ? value : {};
+    const updatedAt = typeof record.updatedAt === "string" && record.updatedAt.trim().length > 0
+        ? record.updatedAt
+        : undefined;
+    return {
+        pageId: typeof record.pageId === "string" && record.pageId.trim().length > 0 ? record.pageId : null,
+        nodeId: typeof record.nodeId === "string" && record.nodeId.trim().length > 0 ? record.nodeId : null,
+        targetId: typeof record.targetId === "string" && record.targetId.trim().length > 0 ? record.targetId : targetId,
+        ...(updatedAt ? { updatedAt } : {})
+    };
+};
 const parseCursor = (cursor) => {
     if (!cursor)
         return 0;
@@ -1943,13 +4417,23 @@ const paginate = (lines, startIndex, maxChars) => {
 };
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const parseTabTargetId = (targetId) => {
-    const raw = targetId.startsWith("tab-") ? targetId.slice(4) : targetId;
-    const parsed = Number.parseInt(raw, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
+    const match = /^tab-(\d+)$/.exec(targetId);
+    if (!match) {
         return null;
     }
+    const parsed = Number.parseInt(match[1], 10);
     return parsed;
 };
+const parseTargetAliasTabId = (targetId) => {
+    if (typeof targetId !== "string" || targetId.length === 0) {
+        return null;
+    }
+    if (targetId.startsWith("target-")) {
+        const parsed = Number.parseInt(targetId.slice(7), 10);
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+    }
+    return parseTabTargetId(targetId);
+};
 const extractBodyHtml = (html) => {
     const bodyMatch = html.match(/<body\b[^>]*>[\s\S]*<\/body>/i);
     if (bodyMatch) {
@@ -2131,27 +4615,102 @@ const escapeCanvasAttribute = (value) => {
         .replaceAll("'", "&#39;");
 };
 const CANVAS_CAPTURE_UNITLESS_STYLES = new Set(["fontWeight", "lineHeight", "opacity", "zIndex"]);
-const resolveReportedTargetUrl = (target, liveUrl, synthetic) => {
-    if (typeof synthetic?.url === "string" && isHtmlDataUrl(synthetic.url)) {
-        return synthetic.url;
+const buildStaleSnapshotError = (ref) => (new Error(`Unknown ref: ${ref}. ${STALE_REF_ERROR_SUFFIX}`));
+const isSnapshotStaleMessage = (error) => {
+    const message = error instanceof Error ? error.message : String(error ?? "");
+    if (message.includes(STALE_REF_ERROR_SUFFIX)) {
+        return true;
+    }
+    const normalized = message.toLowerCase();
+    return normalized.includes("no node with given id")
+        || normalized.includes("could not find node with given id")
+        || normalized.includes("cannot find object with id")
+        || normalized.includes("cannot find context with specified id")
+        || normalized.includes("execution context was destroyed")
+        || normalized.includes("inspected target navigated or closed");
+};
+const extractTargetInfo = (params) => {
+    const payload = isRecord(params) && isRecord(params.targetInfo) ? params.targetInfo : params;
+    if (!isRecord(payload) || typeof payload.targetId !== "string" || typeof payload.type !== "string") {
+        return null;
+    }
+    return {
+        targetId: payload.targetId,
+        type: payload.type,
+        ...(typeof payload.url === "string" ? { url: payload.url } : {}),
+        ...(typeof payload.title === "string" ? { title: payload.title } : {}),
+        ...(typeof payload.openerId === "string" ? { openerId: payload.openerId } : {})
+    };
+};
+const isSyntheticPageTarget = (session, targetId, type) => {
+    if (type !== "page" || targetId === session.targetId) {
+        return false;
+    }
+    const parsedTabId = parseTabTargetId(targetId);
+    return session.targets.has(targetId) || parsedTabId === null || parsedTabId !== session.tabId;
+};
+const resolveReportedTargetUrl = (target, tab) => {
+    if (target?.synthetic === true && typeof target.url === "string" && target.url.length > 0) {
+        return target.url;
     }
     if (typeof target?.url === "string" && isHtmlDataUrl(target.url)) {
         return target.url;
     }
-    return liveUrl ?? target?.url;
+    if (typeof target?.url === "string" && isCanvasExtensionUrl(target.url)) {
+        return target.url;
+    }
+    return getReportedTabUrl(tab) ?? target?.url;
 };
-const resolveReportedTargetTitle = (target, liveTitle, synthetic) => {
-    if (typeof synthetic?.title === "string" && synthetic.title.length > 0) {
-        return synthetic.title;
+const resolveReportedTargetTitle = (target, tab) => {
+    if (target?.synthetic === true && typeof target.title === "string" && target.title.length > 0) {
+        return target.title;
     }
     if (typeof target?.url === "string" && isHtmlDataUrl(target.url) && typeof target.title === "string" && target.title.length > 0) {
         return target.title;
     }
-    return liveTitle ?? target?.title;
+    if (typeof target?.url === "string" && isCanvasExtensionUrl(target.url) && typeof target.title === "string" && target.title.length > 0) {
+        return target.title;
+    }
+    if (isTabNavigationPending(tab)) {
+        return undefined;
+    }
+    return getReportedTabTitle(tab) ?? target?.title;
+};
+const getReportedTabSeed = (tab) => {
+    return {
+        url: getReportedTabUrl(tab),
+        title: getReportedTabTitle(tab)
+    };
+};
+const getReportedTabUrl = (tab) => {
+    if (!tab) {
+        return undefined;
+    }
+    const pendingUrl = typeof tab.pendingUrl === "string" && tab.pendingUrl.length > 0 ? tab.pendingUrl : undefined;
+    const liveUrl = typeof tab.url === "string" && tab.url.length > 0 ? tab.url : undefined;
+    return pendingUrl ?? liveUrl;
+};
+const getReportedTabTitle = (tab) => {
+    if (!tab || isTabNavigationPending(tab)) {
+        return undefined;
+    }
+    return typeof tab.title === "string" && tab.title.length > 0 ? tab.title : undefined;
+};
+const isTabNavigationPending = (tab) => {
+    return tab?.status === "loading";
 };
 const isHtmlDataUrl = (url) => {
     return url.startsWith("data:text/html");
 };
+const isCanvasExtensionUrl = (url) => {
+    try {
+        const canvasUrl = chrome.runtime.getURL("canvas.html");
+        return url === canvasUrl || url.startsWith(`${canvasUrl}#`) || url.startsWith(`${canvasUrl}?`);
+    }
+    catch {
+        return false;
+    }
+};
 const decodeHtmlDataUrl = (url) => {
     if (!isHtmlDataUrl(url)) {
         return null;