@btraut/browser-bridge 0.13.1 → 0.14.0

package/extension/dist/background.js

@@ -102,7 +102,6 @@ var DEFAULT_PERMISSION_PROMPT_WAIT_MS = 3e4;
 var SITE_PERMISSIONS_MODE_KEY = "sitePermissionsMode";
 var DEBUGGER_CAPABILITY_ENABLED_KEY = "debuggerCapabilityEnabled";
 var DEFAULT_SITE_PERMISSIONS_MODE = "granular";
-var DEFAULT_DEBUGGER_CAPABILITY_ENABLED = false;
 var siteKeyFromUrl = (rawUrl) => {
   if (!rawUrl || typeof rawUrl !== "string") {
     return null;
@@ -204,24 +203,12 @@ var readPermissionPromptWaitMs = async () => {
     );
   });
 };
-var readDebuggerCapabilityEnabled = async () => {
+var writeDebuggerCapabilityEnabled = async (enabled) => {
+  void enabled;
   return await new Promise((resolve) => {
-    chrome.storage.local.get(
-      [DEBUGGER_CAPABILITY_ENABLED_KEY],
-      (result) => {
-        const raw = result?.[DEBUGGER_CAPABILITY_ENABLED_KEY];
-        if (typeof raw === "boolean") {
-          resolve(raw);
-          return;
-        }
-        try {
-          chrome.storage.local.set({
-            [DEBUGGER_CAPABILITY_ENABLED_KEY]: DEFAULT_DEBUGGER_CAPABILITY_ENABLED
-          });
-        } catch {
-        }
-        resolve(DEFAULT_DEBUGGER_CAPABILITY_ENABLED);
-      }
+    chrome.storage.local.set(
+      { [DEBUGGER_CAPABILITY_ENABLED_KEY]: true },
+      () => resolve()
     );
   });
 };
@@ -436,6 +423,416 @@ var PermissionPromptController = class {
   }
 };
 
+// packages/extension/src/restricted-url.ts
+var RESTRICTED_URL_PREFIXES = [
+  "chrome://",
+  "chrome-extension://",
+  "chrome-devtools://",
+  "devtools://",
+  "edge://",
+  "brave://",
+  "view-source:"
+];
+var isRestrictedUrl = (url) => {
+  if (!url || typeof url !== "string") {
+    return false;
+  }
+  const lowered = url.toLowerCase();
+  if (RESTRICTED_URL_PREFIXES.some((prefix) => lowered.startsWith(prefix))) {
+    return true;
+  }
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname === "chromewebstore.google.com") {
+      return true;
+    }
+    if (parsed.hostname === "chrome.google.com") {
+      return parsed.pathname.startsWith("/webstore");
+    }
+  } catch (error) {
+    console.debug("Ignoring invalid URL in restriction check.", error);
+  }
+  return false;
+};
+var getRestrictedUrlKind = (url) => {
+  const lowered = url.toLowerCase();
+  if (lowered.startsWith("chrome-extension://")) {
+    return "extension_internal";
+  }
+  if (lowered.startsWith("chrome://") || lowered.startsWith("edge://") || lowered.startsWith("brave://")) {
+    return "browser_internal";
+  }
+  if (lowered.includes("chromewebstore.google.com") || lowered.includes("chrome.google.com/webstore")) {
+    return "webstore";
+  }
+  return "restricted_url";
+};
+var getAlternativeCommands = (url) => {
+  const lowered = url.toLowerCase();
+  if (lowered.startsWith("chrome-extension://") || lowered.startsWith("chrome://extensions")) {
+    return ["browser-bridge diagnostics doctor", "browser-bridge dev info"];
+  }
+  return ["browser-bridge dev info", "browser-bridge diagnostics doctor"];
+};
+var buildRestrictedUrlError = (options) => {
+  const alternatives = getAlternativeCommands(options.url);
+  const operationLabel = options.operation === "navigate" ? "Navigation" : options.operation === "screenshot" ? "Screenshots" : options.operation === "debugger" ? "Debugger attach" : "This action";
+  return {
+    code: "NOT_SUPPORTED",
+    message: `${operationLabel} is not supported for browser internal URLs.`,
+    retryable: false,
+    details: {
+      reason: "restricted_internal_url",
+      url: options.url,
+      url_kind: getRestrictedUrlKind(options.url),
+      rationale: "Chrome restricts extension automation on internal browser surfaces (for example chrome:// and chrome-extension://).",
+      action: options.action,
+      next_step: alternatives[0],
+      alternatives
+    }
+  };
+};
+
+// packages/extension/src/tab-resolution.ts
+var invalidTabIdError = (message) => ({
+  code: "INVALID_ARGUMENT",
+  message,
+  retryable: false
+});
+var readOptionalTabId = (params, message = "tab_id must be a number when provided.") => {
+  const tabId = params.tab_id;
+  if (tabId !== void 0 && typeof tabId !== "number") {
+    return {
+      ok: false,
+      error: invalidTabIdError(message)
+    };
+  }
+  return {
+    ok: true,
+    tabId: typeof tabId === "number" ? tabId : void 0
+  };
+};
+var readRequiredTabId = (params, message = "tab_id must be a number.") => {
+  const tabId = params.tab_id;
+  if (typeof tabId !== "number") {
+    return {
+      ok: false,
+      error: invalidTabIdError(message)
+    };
+  }
+  return {
+    ok: true,
+    tabId
+  };
+};
+var resolveOptionalTabId = async (params, deps, message = "tab_id must be a number when provided.") => {
+  const parsed = readOptionalTabId(params, message);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  return {
+    ok: true,
+    tabId: parsed.tabId ?? await deps.getDefaultTabId()
+  };
+};
+var requireTab = async (tabId, getTab2) => {
+  try {
+    return {
+      ok: true,
+      tab: await getTab2(tabId)
+    };
+  } catch {
+    return {
+      ok: false,
+      error: {
+        code: "TAB_NOT_FOUND",
+        message: `tab_id ${tabId} was not found.`,
+        retryable: false,
+        details: { tab_id: tabId }
+      }
+    };
+  }
+};
+
+// packages/extension/src/action-permissions.ts
+var GATED_ACTIONS = /* @__PURE__ */ new Set([
+  "drive.navigate",
+  "drive.go_back",
+  "drive.go_forward",
+  "drive.click",
+  "drive.hover",
+  "drive.select",
+  "drive.type",
+  "drive.fill_form",
+  "drive.drag",
+  "drive.handle_dialog",
+  "drive.key",
+  "drive.key_press",
+  "drive.scroll",
+  "drive.screenshot",
+  "drive.wait_for"
+]);
+var gateDriveAction = async (options) => {
+  const { action, params, getDefaultTabId: getDefaultTabId2, getTab: getTab2, permissionPrompts: permissionPrompts2 } = options;
+  if (!GATED_ACTIONS.has(action)) {
+    return { ok: true, siteKey: null, touchOnSuccess: false };
+  }
+  let siteKey = null;
+  if (action === "drive.navigate") {
+    const url = params.url;
+    if (typeof url !== "string" || url.length === 0) {
+      return { ok: true, siteKey: null, touchOnSuccess: false };
+    }
+    if (isRestrictedUrl(url)) {
+      return {
+        ok: false,
+        error: buildRestrictedUrlError({
+          url,
+          operation: "navigate",
+          action
+        })
+      };
+    }
+    siteKey = siteKeyFromUrl(url);
+    if (!siteKey) {
+      return {
+        ok: false,
+        error: {
+          code: "INVALID_ARGUMENT",
+          message: "Unable to resolve site permission key for url.",
+          retryable: false,
+          details: { url }
+        }
+      };
+    }
+  } else {
+    const parsedTabId = readOptionalTabId(params);
+    if (!parsedTabId.ok) {
+      return { ok: true, siteKey: null, touchOnSuccess: false };
+    }
+    const resolvedTabId = parsedTabId.tabId ?? await getDefaultTabId2();
+    const tab = await getTab2(resolvedTabId);
+    const url = tab.url;
+    if (typeof url !== "string" || url.length === 0) {
+      return {
+        ok: false,
+        error: {
+          code: "FAILED_PRECONDITION",
+          message: "Active tab URL is unavailable for permission gating.",
+          retryable: false,
+          details: { tab_id: resolvedTabId }
+        }
+      };
+    }
+    if (isRestrictedUrl(url)) {
+      return {
+        ok: false,
+        error: buildRestrictedUrlError({
+          url,
+          operation: action === "drive.screenshot" ? "screenshot" : "action",
+          action
+        })
+      };
+    }
+    siteKey = siteKeyFromUrl(url);
+    if (!siteKey) {
+      return {
+        ok: false,
+        error: {
+          code: "FAILED_PRECONDITION",
+          message: "Unable to resolve site permission key for active tab.",
+          retryable: false,
+          details: { url, tab_id: resolvedTabId }
+        }
+      };
+    }
+  }
+  if (await readSitePermissionsMode() === "bypass") {
+    return { ok: true, siteKey, touchOnSuccess: false };
+  }
+  if (await isSiteAllowed(siteKey)) {
+    return { ok: true, siteKey, touchOnSuccess: true };
+  }
+  const decision = await permissionPrompts2.requestPermission({
+    siteKey,
+    action
+  });
+  if (decision.kind === "timed_out") {
+    return {
+      ok: false,
+      error: {
+        code: "PERMISSION_PROMPT_TIMEOUT",
+        message: `Permission prompt timed out for ${siteKey}.`,
+        retryable: true,
+        details: {
+          reason: "prompt_timed_out",
+          site: siteKey,
+          action,
+          wait_ms: decision.waitMs
+        }
+      }
+    };
+  }
+  if (decision.kind === "deny") {
+    return {
+      ok: false,
+      error: {
+        code: "PERMISSION_DENIED",
+        message: `User denied Browser Bridge permission for ${siteKey}.`,
+        retryable: false,
+        details: {
+          reason: "user_denied",
+          site: siteKey,
+          action,
+          next_step: "Ask the user to approve the permission prompt (Allow/Always allow) or allow the site in the extension options page, then retry the command."
+        }
+      }
+    };
+  }
+  if (decision.kind === "allow_always") {
+    await allowSiteAlways(siteKey);
+    return { ok: true, siteKey, touchOnSuccess: true };
+  }
+  return { ok: true, siteKey, touchOnSuccess: false };
+};
+
+// packages/extension/src/popup-trigger-state.ts
+var popupTriggerStateChanged = (before, after) => {
+  if (!before || !after) {
+    return before !== after;
+  }
+  return before.ariaExpanded !== after.ariaExpanded || before.dataState !== after.dataState || before.open !== after.open;
+};
+var coercePopupTriggerState = (value) => {
+  if (!value || typeof value !== "object") {
+    return void 0;
+  }
+  const record = value;
+  if (record.kind !== "popup_trigger") {
+    return void 0;
+  }
+  const ariaHasPopup = typeof record.ariaHasPopup === "string" ? record.ariaHasPopup : void 0;
+  const ariaExpanded = typeof record.ariaExpanded === "string" ? record.ariaExpanded : void 0;
+  const dataState = typeof record.dataState === "string" ? record.dataState : void 0;
+  const open = typeof record.open === "boolean" ? record.open : void 0;
+  return {
+    kind: "popup_trigger",
+    ...ariaHasPopup ? { ariaHasPopup } : {},
+    ...ariaExpanded !== void 0 ? { ariaExpanded } : {},
+    ...dataState !== void 0 ? { dataState } : {},
+    ...open !== void 0 ? { open } : {}
+  };
+};
+
+// packages/extension/src/popup-click-verification.ts
+var POPUP_TRIGGER_CLICK_SETTLE_MS = 50;
+var POPUP_TRIGGER_RECHECK_MS = 125;
+var readPopupTriggerAfterClick = async (options) => {
+  const after = await options.resolveLocatorPoint(options.locator);
+  if (!after.ok) {
+    if (shouldTreatPostClickReadErrorAsSuccess(after.error)) {
+      return {
+        ok: false,
+        error: {
+          code: "NOT_FOUND",
+          message: "Popup trigger disappeared after click.",
+          retryable: false,
+          details: { reason: "popup_trigger_disappeared" }
+        }
+      };
+    }
+    return after;
+  }
+  return after;
+};
+var shouldTreatPostClickReadErrorAsSuccess = (error) => {
+  return error.code === "LOCATOR_NOT_FOUND" || error.code === "NOT_FOUND" || error.retryable === true && (error.code === "TIMEOUT" || error.details?.reason === "transient_tab_channel_error");
+};
+var verifyPopupTriggerClick = async (options) => {
+  if (options.prepareTarget) {
+    await options.prepareTarget();
+  }
+  try {
+    await options.dispatchCdpClick(
+      options.point.x,
+      options.point.y,
+      options.clickCount
+    );
+  } catch (error) {
+    return { ok: false, error: options.mapDispatchError(error) };
+  }
+  await options.delayMs(options.settleMs ?? POPUP_TRIGGER_CLICK_SETTLE_MS);
+  const after = await readPopupTriggerAfterClick(options);
+  if (!after.ok) {
+    if (after.error.details?.reason === "popup_trigger_disappeared") {
+      return { ok: true };
+    }
+    return after;
+  }
+  if (popupTriggerStateChanged(
+    options.point.targetState ?? null,
+    after.point.targetState ?? null
+  )) {
+    return { ok: true };
+  }
+  if (options.clickCount === 1) {
+    await options.delayMs(POPUP_TRIGGER_RECHECK_MS);
+    const lateAfter = await readPopupTriggerAfterClick(options);
+    if (!lateAfter.ok) {
+      if (lateAfter.error.details?.reason === "popup_trigger_disappeared") {
+        return { ok: true };
+      }
+      return lateAfter;
+    }
+    if (popupTriggerStateChanged(
+      options.point.targetState ?? null,
+      lateAfter.point.targetState ?? null
+    )) {
+      return { ok: true };
+    }
+    try {
+      await options.dispatchCdpClick(
+        options.point.x,
+        options.point.y,
+        options.clickCount
+      );
+    } catch (error) {
+      return { ok: false, error: options.mapDispatchError(error) };
+    }
+    await options.delayMs(options.settleMs ?? POPUP_TRIGGER_CLICK_SETTLE_MS);
+    const retryAfter = await readPopupTriggerAfterClick(options);
+    if (!retryAfter.ok) {
+      if (retryAfter.error.details?.reason === "popup_trigger_disappeared") {
+        return { ok: true };
+      }
+      return retryAfter;
+    }
+    if (popupTriggerStateChanged(
+      options.point.targetState ?? null,
+      retryAfter.point.targetState ?? null
+    )) {
+      return { ok: true };
+    }
+  }
+  return {
+    ok: false,
+    error: {
+      code: "FAILED_PRECONDITION",
+      message: "Click focused the popup trigger but did not change its open state.",
+      retryable: false,
+      details: {
+        reason: "click_state_unchanged",
+        control: "popup_trigger",
+        aria_haspopup: options.point.targetState?.ariaHasPopup,
+        aria_expanded_before: options.point.targetState?.ariaExpanded,
+        aria_expanded_after: after.point.targetState?.ariaExpanded,
+        data_state_before: options.point.targetState?.dataState,
+        data_state_after: after.point.targetState?.dataState
+      }
+    }
+  };
+};
+
 // packages/extension/src/drive-reliability.ts
 var TRANSIENT_TAB_CHANNEL_ERROR_PATTERNS = [
   "receiving end does not exist",
@@ -462,6 +859,15 @@ var isTransientTabChannelError = (message) => {
     (pattern) => normalized.includes(pattern)
   );
 };
+var shouldRetryTabChannelFailure = (action, error) => {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  if (isTransientTabChannelError(error.message)) {
+    return true;
+  }
+  return action === "drive.wait_for" && error.code === "TIMEOUT" && error.retryable === true && typeof error.message === "string" && error.message.includes("Timed out waiting for content response");
+};
 var getTabChannelRetryDelayMs = (attempt) => {
   if (!Number.isInteger(attempt) || attempt < 1) {
     return void 0;
@@ -558,9 +964,228 @@ var ConnectionStateTracker = class {
   }
 };
 
-// packages/extension/src/background.ts
+// packages/extension/src/debugger-dispatch.ts
+var dispatchDebuggerRequest = async (message, deps, responders) => {
+  const { respondAck, respondError } = responders;
+  try {
+    switch (message.action) {
+      case "debugger.attach": {
+        const parsedTabId = readRequiredTabId(
+          message.params ?? {}
+        );
+        if (!parsedTabId.ok) {
+          respondError(parsedTabId.error);
+          return;
+        }
+        const error = await deps.ensureDebuggerAttached(parsedTabId.tabId);
+        if (error) {
+          respondError(error);
+          return;
+        }
+        respondAck({ ok: true });
+        return;
+      }
+      case "debugger.detach": {
+        const parsedTabId = readRequiredTabId(
+          message.params ?? {}
+        );
+        if (!parsedTabId.ok) {
+          respondError(parsedTabId.error);
+          return;
+        }
+        const error = await deps.detachDebugger(parsedTabId.tabId);
+        if (error) {
+          respondError(error);
+          return;
+        }
+        respondAck({ ok: true });
+        return;
+      }
+      case "debugger.command": {
+        const params = message.params ?? {};
+        const parsedTabId = readRequiredTabId(
+          params
+        );
+        if (!parsedTabId.ok) {
+          respondError(parsedTabId.error);
+          return;
+        }
+        if (typeof params.method !== "string" || params.method.length === 0) {
+          respondError({
+            code: "INVALID_ARGUMENT",
+            message: "method must be a non-empty string.",
+            retryable: false
+          });
+          return;
+        }
+        const session = deps.getSession(parsedTabId.tabId);
+        if (session?.attachPromise) {
+          try {
+            await session.attachPromise;
+          } catch (error) {
+            const info = deps.mapDebuggerErrorMessage(
+              error instanceof Error ? error.message : "Debugger attach failed."
+            );
+            deps.clearDebuggerSession(parsedTabId.tabId);
+            respondError(info);
+            return;
+          }
+        }
+        const attachedSession = deps.getSession(parsedTabId.tabId);
+        if (!attachedSession?.attached) {
+          respondError({
+            code: "FAILED_PRECONDITION",
+            message: "Debugger is not attached to the requested tab.",
+            retryable: false
+          });
+          return;
+        }
+        try {
+          const result = await deps.sendDebuggerCommand(
+            parsedTabId.tabId,
+            params.method,
+            params.params,
+            deps.debuggerCommandTimeoutMs
+          );
+          deps.touchDebuggerSession(parsedTabId.tabId);
+          respondAck(result);
+        } catch (error) {
+          const info = deps.mapDebuggerErrorMessage(
+            error instanceof Error ? error.message : "Debugger command failed."
+          );
+          respondError(info);
+        }
+        return;
+      }
+      default:
+        respondError({
+          code: "NOT_IMPLEMENTED",
+          message: `${message.action} not implemented in extension yet.`,
+          retryable: false
+        });
+    }
+  } catch (error) {
+    const messageText = error instanceof Error ? error.message : "Unexpected debugger error.";
+    respondError({
+      code: "INSPECT_UNAVAILABLE",
+      message: messageText,
+      retryable: false
+    });
+  }
+};
+
+// packages/extension/src/screenshot-errors.ts
+var isCaptureVisibleTabRateLimitedMessage = (message) => {
+  const normalized = message.toLowerCase();
+  const hasCaptureSignal = normalized.includes("capturevisibletab");
+  const hasRateSignal = normalized.includes("max_capture_visible_tab_calls_per_second") || normalized.includes("too often") || normalized.includes("rate limit") || normalized.includes("rate-limit");
+  return hasCaptureSignal && hasRateSignal;
+};
+var isCaptureVisibleTabPermissionMessage = (message) => {
+  const normalized = message.toLowerCase();
+  const hasCaptureSignal = normalized.includes("capturevisibletab");
+  const hasPermissionSignal = normalized.includes("permission is required") || normalized.includes("requires permission") || normalized.includes("requires either");
+  const hasPermissionTarget = normalized.includes("all_urls") || normalized.includes("activetab");
+  return hasCaptureSignal && hasPermissionSignal && hasPermissionTarget;
+};
+var isCaptureVisibleTabRateLimitedError = (error) => error instanceof Error && isCaptureVisibleTabRateLimitedMessage(error.message);
+var isCaptureVisibleTabPermissionError = (error) => error instanceof Error && isCaptureVisibleTabPermissionMessage(error.message);
+var mapScreenshotCaptureError = (error, fallbackMessage) => {
+  const message = error instanceof Error && error.message ? error.message : fallbackMessage;
+  if (isCaptureVisibleTabRateLimitedError(error)) {
+    return {
+      code: "RATE_LIMITED",
+      message: "Screenshot capture hit Chrome capture rate limits. Please retry shortly.",
+      retryable: true,
+      details: {
+        reason: "capture_visible_tab_rate_limited",
+        original_message: message
+      }
+    };
+  }
+  if (isCaptureVisibleTabPermissionError(error)) {
+    return {
+      code: "PERMISSION_REQUIRED",
+      message: "Screenshot capture requires captureVisibleTab permission (<all_urls> or activeTab).",
+      retryable: false,
+      details: {
+        reason: "capture_visible_tab_permission_required",
+        required_any_of: ["<all_urls>", "activeTab"],
+        next_step: "Reload the Browser Bridge extension in chrome://extensions and retry screenshot capture.",
+        original_message: message
+      }
+    };
+  }
+  return {
+    code: "ARTIFACT_IO_ERROR",
+    message,
+    retryable: false
+  };
+};
+
+// packages/extension/src/core-endpoint-config.ts
+var DEFAULT_CORE_HOST = "127.0.0.1";
 var DEFAULT_CORE_PORT = 3210;
-var CORE_PORT_KEY = "corePort";
+var LEGACY_CORE_PORT_KEY = "corePort";
+var hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+var readCoreEndpointConfig = async () => ({
+  host: DEFAULT_CORE_HOST,
+  port: DEFAULT_CORE_PORT,
+  portSource: "default"
+});
+var clearLegacyCorePort = async (storage) => {
+  return await new Promise((resolve) => {
+    storage.get([LEGACY_CORE_PORT_KEY], (items) => {
+      if (!hasOwn(items, LEGACY_CORE_PORT_KEY)) {
+        resolve(false);
+        return;
+      }
+      storage.remove([LEGACY_CORE_PORT_KEY], () => resolve(true));
+    });
+  });
+};
+
+// packages/extension/src/tab-activation.ts
+var resolveTabActivationOutcome = ({
+  tabId,
+  windowId,
+  activated,
+  focusErrorMessage,
+  windowFocused
+}) => {
+  if (!activated) {
+    return {
+      ok: false,
+      error: {
+        code: "FAILED_PRECONDITION",
+        message: `Failed to activate tab_id ${tabId}.`,
+        retryable: true,
+        details: { tab_id: tabId }
+      }
+    };
+  }
+  const warnings = [];
+  if (typeof windowId === "number") {
+    if (focusErrorMessage) {
+      warnings.push(
+        `Activated tab_id ${tabId}, but failed to focus window_id ${windowId}: ${focusErrorMessage}`
+      );
+    } else if (windowFocused === false) {
+      warnings.push(
+        `Activated tab_id ${tabId}, but window_id ${windowId} did not report focused state.`
+      );
+    }
+  }
+  return {
+    ok: true,
+    result: {
+      ok: true,
+      ...warnings.length > 0 ? { warnings } : {}
+    }
+  };
+};
+
+// packages/extension/src/background.ts
 var CORE_WS_PATH = "/drive";
 var CORE_HEALTH_PATH = "/health";
 var CORE_HEALTH_TIMEOUT_MS = 1200;
@@ -598,6 +1223,7 @@ var BASE_NEGOTIATED_CAPABILITIES = Object.freeze({
   "drive.tab_list": true,
   "drive.tab_activate": true,
   "drive.tab_close": true,
+  "drive.set_debugger_capability": true,
   "drive.ping": true
 });
 var DEBUGGER_CAPABILITY_ACTIONS = [
@@ -605,26 +1231,15 @@ var DEBUGGER_CAPABILITY_ACTIONS = [
   "debugger.detach",
   "debugger.command"
 ];
-var buildNegotiatedCapabilities = (debuggerCapabilityEnabled) => {
+var buildNegotiatedCapabilities = () => {
   const capabilities = {
     ...BASE_NEGOTIATED_CAPABILITIES
   };
   for (const action of DEBUGGER_CAPABILITY_ACTIONS) {
-    capabilities[action] = debuggerCapabilityEnabled;
+    capabilities[action] = true;
   }
   return capabilities;
 };
-var debuggerCapabilityDisabledError = () => {
-  return {
-    code: "ATTACH_DENIED",
-    message: "Debugger capability is disabled. Enable debugger-based inspect in extension options and retry.",
-    retryable: false,
-    details: {
-      reason: "debugger_capability_disabled",
-      next_step: "Open Browser Bridge extension options, enable debugger-based inspect, then retry."
-    }
-  };
-};
 var getAgentTabBootstrapUrl = () => {
   return typeof chrome.runtime?.getURL === "function" ? chrome.runtime.getURL(AGENT_TAB_BOOTSTRAP_PATH) : AGENT_TAB_BOOTSTRAP_PATH;
 };
@@ -687,15 +1302,6 @@ var CAPTURE_VISIBLE_TAB_MAX_RETRIES = 3;
 var CAPTURE_VISIBLE_TAB_RETRY_BASE_DELAY_MS = 500;
 var captureVisibleTabQueue = Promise.resolve();
 var captureVisibleTabLastCallAt = 0;
-var isCaptureVisibleTabRateLimitedMessage = (message) => {
-  const normalized = message.toLowerCase();
-  const hasCaptureSignal = normalized.includes("capturevisibletab") || normalized.includes("max_capture_visible_tab_calls_per_second");
-  const hasRateSignal = normalized.includes("too often") || normalized.includes("rate limit") || normalized.includes("rate-limit");
-  return hasCaptureSignal && hasRateSignal;
-};
-var isCaptureVisibleTabRateLimitedError = (error) => {
-  return error instanceof Error && isCaptureVisibleTabRateLimitedMessage(error.message);
-};
 var randomJitterMs = (maxMs) => {
   return Math.floor(Math.random() * Math.max(1, maxMs));
 };
@@ -737,25 +1343,6 @@ var captureVisibleTabWithThrottle = async (windowId) => {
     throw new Error("captureVisibleTab failed unexpectedly.");
   });
 };
-var mapScreenshotCaptureError = (error, fallbackMessage) => {
-  const message = error instanceof Error && error.message ? error.message : fallbackMessage;
-  if (isCaptureVisibleTabRateLimitedError(error)) {
-    return {
-      code: "RATE_LIMITED",
-      message: "Screenshot capture hit Chrome capture rate limits. Please retry shortly.",
-      retryable: true,
-      details: {
-        reason: "capture_visible_tab_rate_limited",
-        original_message: message
-      }
-    };
-  }
-  return {
-    code: "ARTIFACT_IO_ERROR",
-    message,
-    retryable: false
-  };
-};
 var parseDataUrl = (dataUrl) => {
   const match = /^data:([^;]+);base64,(.*)$/s.exec(dataUrl);
   if (!match) {
@@ -801,40 +1388,6 @@ var renderDataUrlToFormat = async (dataUrl, format, quality) => {
     bitmap.close();
   }
 };
-var readCoreEndpointConfig = async () => {
-  return await new Promise((resolve) => {
-    chrome.storage.local.get(
-      [CORE_PORT_KEY],
-      (result) => {
-        const raw = result?.[CORE_PORT_KEY];
-        if (typeof raw === "number" && Number.isFinite(raw)) {
-          resolve({
-            host: "127.0.0.1",
-            port: raw,
-            portSource: "storage"
-          });
-          return;
-        }
-        if (typeof raw === "string") {
-          const parsed = Number(raw);
-          if (Number.isFinite(parsed)) {
-            resolve({
-              host: "127.0.0.1",
-              port: parsed,
-              portSource: "storage"
-            });
-            return;
-          }
-        }
-        resolve({
-          host: "127.0.0.1",
-          port: DEFAULT_CORE_PORT,
-          portSource: "default"
-        });
-      }
-    );
-  });
-};
 var readDebuggerIdleTimeoutMs = async () => {
   return await new Promise((resolve) => {
     chrome.storage.local.get(
@@ -857,36 +1410,6 @@ var readDebuggerIdleTimeoutMs = async () => {
     );
   });
 };
-var RESTRICTED_URL_PREFIXES = [
-  "chrome://",
-  "chrome-extension://",
-  "chrome-devtools://",
-  "devtools://",
-  "edge://",
-  "brave://",
-  "view-source:"
-];
-var isRestrictedUrl = (url) => {
-  if (!url || typeof url !== "string") {
-    return false;
-  }
-  const lowered = url.toLowerCase();
-  if (RESTRICTED_URL_PREFIXES.some((prefix) => lowered.startsWith(prefix))) {
-    return true;
-  }
-  try {
-    const parsed = new URL(url);
-    if (parsed.hostname === "chromewebstore.google.com") {
-      return true;
-    }
-    if (parsed.hostname === "chrome.google.com") {
-      return parsed.pathname.startsWith("/webstore");
-    }
-  } catch (error) {
-    console.debug("Ignoring invalid URL in restriction check.", error);
-  }
-  return false;
-};
 var mapDebuggerErrorMessage = (message, fallbackCode = "INSPECT_UNAVAILABLE") => {
   const normalized = message.toLowerCase();
   if (normalized.includes("already attached") || normalized.includes("another debugger") || normalized.includes("attached to this target")) {
@@ -943,6 +1466,25 @@ var buildTabInfo = (tab) => {
     last_active_at: ensureLastActiveAt(tabId)
   };
 };
+var tabRecencyScore = (tab) => {
+  const parsed = Date.parse(tab.last_active_at);
+  return Number.isFinite(parsed) ? parsed : -Infinity;
+};
+var compareTabsForReport = (a, b) => {
+  const aActive = a.active === true ? 1 : 0;
+  const bActive = b.active === true ? 1 : 0;
+  if (aActive !== bActive) {
+    return bActive - aActive;
+  }
+  const recencyDelta = tabRecencyScore(b) - tabRecencyScore(a);
+  if (recencyDelta !== 0) {
+    return recencyDelta;
+  }
+  if (a.window_id !== b.window_id) {
+    return a.window_id - b.window_id;
+  }
+  return a.tab_id - b.tab_id;
+};
 var queryTabs = async () => {
   const tabs = await wrapChromeCallback(
     (callback) => chrome.tabs.query({}, callback)
@@ -954,6 +1496,7 @@ var queryTabs = async () => {
       result.push(info);
     }
   }
+  result.sort(compareTabsForReport);
   return result;
 };
 var getTab = async (tabId) => {
@@ -961,6 +1504,21 @@ var getTab = async (tabId) => {
     (callback) => chrome.tabs.get(tabId, callback)
   );
 };
+var getWindow = async (windowId) => {
+  return await wrapChromeCallback(
+    (callback) => chrome.windows.get(windowId, callback)
+  );
+};
+var withResolvedTabTarget = async (tabId, result) => {
+  const payload = result && typeof result === "object" && !Array.isArray(result) ? { ...result } : {};
+  const tab = await getTab(tabId).catch(() => void 0);
+  const windowId = tab && typeof tab.windowId === "number" ? tab.windowId : void 0;
+  return {
+    ...payload,
+    tab_id: tabId,
+    ...typeof windowId === "number" ? { window_id: windowId } : {}
+  };
+};
 var getActiveTabId = async () => {
   const tabs = await wrapChromeCallback(
     (callback) => chrome.tabs.query({ active: true, lastFocusedWindow: true }, callback)
@@ -1199,7 +1757,7 @@ var sendToTab = async (tabId, action, params, options) => {
     if (result.ok) {
       return result;
     }
-    if (!isTransientTabChannelError(result.error?.message)) {
+    if (!shouldRetryTabChannelFailure(action, result.error)) {
       return result;
     }
     const retryDelayMs = getTabChannelRetryDelayMs(attempt);
@@ -1480,7 +2038,6 @@ var DriveSocket = class {
   async sendHello() {
     const manifest = chrome.runtime.getManifest();
     const endpoint = await readCoreEndpointConfig();
-    const debuggerCapabilityEnabled = await readDebuggerCapabilityEnabled();
     let tabs = [];
     try {
       tabs = await queryTabs();
@@ -1489,9 +2046,10 @@ var DriveSocket = class {
       tabs = [];
     }
     const params = {
+      extension_id: chrome.runtime.id,
       version: manifest.version,
       protocol_version: DRIVE_WS_PROTOCOL_VERSION,
-      capabilities: buildNegotiatedCapabilities(debuggerCapabilityEnabled),
+      capabilities: buildNegotiatedCapabilities(),
       core_host: endpoint.host,
       core_port: endpoint.port,
       core_port_source: endpoint.portSource,
@@ -1567,16 +2125,10 @@ var DriveSocket = class {
     }
   }
   async refreshDebuggerCapabilityState() {
-    const enabled = await readDebuggerCapabilityEnabled();
-    if (!enabled) {
-      await this.detachAllDebuggerSessions();
-    }
     this.refreshCapabilities();
   }
   async handleDebuggerCapabilityChange(enabled) {
-    if (!enabled) {
-      await this.detachAllDebuggerSessions();
-    }
+    void enabled;
     this.refreshCapabilities();
   }
   async handleRequest(message) {
@@ -1617,15 +2169,6 @@ var DriveSocket = class {
         return;
       }
       if (message.action.startsWith("debugger.")) {
-        if (!await readDebuggerCapabilityEnabled()) {
-          this.sendMessage({
-            id: message.id,
-            action: message.action,
-            status: "error",
-            error: sanitizeDriveErrorInfo(debuggerCapabilityDisabledError())
-          });
-          return;
-        }
         await this.handleDebuggerRequest(message);
         return;
       }
@@ -1633,162 +2176,58 @@ var DriveSocket = class {
         return;
       }
       driveMessage = message;
-      const gatedActions = /* @__PURE__ */ new Set([
-        "drive.navigate",
-        "drive.go_back",
-        "drive.go_forward",
-        "drive.click",
-        "drive.hover",
-        "drive.select",
-        "drive.type",
-        "drive.fill_form",
-        "drive.drag",
-        "drive.handle_dialog",
-        "drive.key",
-        "drive.key_press",
-        "drive.scroll",
-        "drive.screenshot",
-        "drive.wait_for"
-      ]);
-      const gateDriveAction = async () => {
-        const action = message.action;
-        if (!gatedActions.has(action)) {
-          return { ok: true, siteKey: null, touchOnSuccess: false };
-        }
-        const params = message.params ?? {};
-        let siteKey = null;
-        if (action === "drive.navigate") {
-          const url = params.url;
-          if (typeof url !== "string" || url.length === 0) {
-            return { ok: true, siteKey: null, touchOnSuccess: false };
-          }
-          if (isRestrictedUrl(url)) {
-            return {
-              ok: false,
-              error: {
-                code: "NOT_SUPPORTED",
-                message: "Navigation is not supported for this URL.",
-                retryable: false,
-                details: { url }
-              }
-            };
-          }
-          siteKey = siteKeyFromUrl(url);
-          if (!siteKey) {
-            return {
-              ok: false,
-              error: {
-                code: "INVALID_ARGUMENT",
-                message: "Unable to resolve site permission key for url.",
-                retryable: false,
-                details: { url }
-              }
-            };
-          }
-        } else {
-          const tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            return { ok: true, siteKey: null, touchOnSuccess: false };
-          }
-          const resolvedTabId = typeof tabId === "number" ? tabId : await getDefaultTabId();
-          const tab = await getTab(resolvedTabId);
-          const url = tab.url;
-          if (typeof url !== "string" || url.length === 0) {
-            return {
-              ok: false,
-              error: {
-                code: "FAILED_PRECONDITION",
-                message: "Active tab URL is unavailable for permission gating.",
-                retryable: false,
-                details: { tab_id: resolvedTabId }
-              }
-            };
-          }
-          if (isRestrictedUrl(url)) {
-            const message2 = action === "drive.screenshot" ? "Screenshots are not supported for this URL." : "This action is not supported for this URL.";
-            return {
-              ok: false,
-              error: {
-                code: "NOT_SUPPORTED",
-                message: message2,
-                retryable: false,
-                details: { url }
-              }
-            };
-          }
-          siteKey = siteKeyFromUrl(url);
-          if (!siteKey) {
-            return {
-              ok: false,
-              error: {
-                code: "FAILED_PRECONDITION",
-                message: "Unable to resolve site permission key for active tab.",
-                retryable: false,
-                details: { url, tab_id: resolvedTabId }
-              }
-            };
-          }
-        }
-        if (await readSitePermissionsMode() === "bypass") {
-          return { ok: true, siteKey, touchOnSuccess: false };
-        }
-        if (await isSiteAllowed(siteKey)) {
-          return { ok: true, siteKey, touchOnSuccess: true };
-        }
-        const decision = await permissionPrompts.requestPermission({
-          siteKey,
-          action
-        });
-        if (decision.kind === "timed_out") {
-          return {
-            ok: false,
-            error: {
-              code: "PERMISSION_PROMPT_TIMEOUT",
-              message: `Permission prompt timed out for ${siteKey}.`,
-              retryable: true,
-              details: {
-                reason: "prompt_timed_out",
-                site: siteKey,
-                action,
-                wait_ms: decision.waitMs
-              }
-            }
-          };
-        }
-        if (decision.kind === "deny") {
-          return {
-            ok: false,
-            error: {
-              code: "PERMISSION_DENIED",
-              message: `User denied Browser Bridge permission for ${siteKey}.`,
-              retryable: false,
-              details: {
-                reason: "user_denied",
-                site: siteKey,
-                action,
-                next_step: "Ask the user to approve the permission prompt (Allow/Always allow) or allow the site in the extension options page, then retry the command."
-              }
-            }
-          };
-        }
-        if (decision.kind === "allow_always") {
-          await allowSiteAlways(siteKey);
-          return { ok: true, siteKey, touchOnSuccess: true };
-        }
-        return { ok: true, siteKey, touchOnSuccess: false };
-      };
-      const gated = await gateDriveAction();
+      const gated = await gateDriveAction({
+        action: message.action,
+        params: message.params ?? {},
+        getDefaultTabId,
+        getTab,
+        permissionPrompts
+      });
       if (!gated.ok) {
         respondError(gated.error);
         return;
       }
       gatedSiteKey = gated.siteKey;
       touchGatedSiteOnSuccess = gated.touchOnSuccess;
+      const resolveActionTabId = async (params) => await resolveOptionalTabId(params, { getDefaultTabId });
       switch (message.action) {
         case "drive.ping": {
           respondOk({ ok: true });
           return;
         }
+        case "drive.set_debugger_capability": {
+          const params = message.params ?? {};
+          const enabled = typeof params.enabled === "boolean" ? params.enabled : true;
+          const expectedExtensionId = params.extension_id;
+          if (expectedExtensionId !== void 0 && typeof expectedExtensionId !== "string") {
+            respondError({
+              code: "INVALID_ARGUMENT",
+              message: "extension_id must be a string when provided.",
+              retryable: false
+            });
+            return;
+          }
+          if (typeof expectedExtensionId === "string" && expectedExtensionId.length > 0 && expectedExtensionId !== chrome.runtime.id) {
+            respondError({
+              code: "FAILED_PRECONDITION",
+              message: "Connected extension id does not match the requested extension.",
+              retryable: false,
+              details: {
+                expected_extension_id: expectedExtensionId,
+                connected_extension_id: chrome.runtime.id
+              }
+            });
+            return;
+          }
+          await writeDebuggerCapabilityEnabled(enabled);
+          await this.refreshDebuggerCapabilityState();
+          respondOk({
+            ok: true,
+            enabled,
+            extension_id: chrome.runtime.id
+          });
+          return;
+        }
         case "drive.navigate": {
           const params = message.params ?? {};
           const url = params.url;
@@ -1800,21 +2239,38 @@ var DriveSocket = class {
             });
             return;
           }
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
+            return;
+          }
+          const tabId = tabTarget.tabId;
+          const requestedWaitMode = params.wait;
+          if (requestedWaitMode !== void 0 && requestedWaitMode !== "none" && requestedWaitMode !== "domcontentloaded" && requestedWaitMode !== "networkidle") {
             respondError({
               code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
+              message: `Unsupported wait mode: ${String(requestedWaitMode)}.`,
+              retryable: false,
+              details: {
+                field: "wait",
+                supported_wait_modes: [
+                  "none",
+                  "domcontentloaded",
+                  "networkidle"
+                ],
+                mapped_wait_mode: "domcontentloaded"
+              }
             });
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
-          const waitMode = params.wait === "none" || params.wait === "domcontentloaded" ? params.wait : "domcontentloaded";
+          const waitMode = requestedWaitMode === "none" ? "none" : "domcontentloaded";
           const domContentLoadedSignal = waitMode === "domcontentloaded" ? waitForDomContentLoaded(tabId, 3e4) : null;
           const warnings = [];
+          if (requestedWaitMode === "networkidle") {
+            warnings.push(
+              "wait=networkidle is mapped to domcontentloaded in this runtime."
+            );
+          }
           await wrapChromeVoid(
             (callback) => chrome.tabs.update(tabId, { url }, () => callback())
           );
@@ -1841,39 +2297,30 @@ var DriveSocket = class {
           if (tabId === agentTabId) {
             void refreshAgentTabBranding(tabId);
           }
-          respondOk({
-            ok: true,
-            ...warnings.length > 0 ? { warnings } : {}
-          });
+          respondOk(
+            await withResolvedTabTarget(tabId, {
+              ok: true,
+              ...warnings.length > 0 ? { warnings } : {}
+            })
+          );
           return;
         }
         case "drive.go_back":
         case "drive.go_forward": {
           const params = message.params ?? {};
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const navigationSignal = waitForHistoryNavigationSignal(
             tabId,
             HISTORY_NAVIGATION_SIGNAL_TIMEOUT_MS
           );
-          const result = await sendToTab(
-            tabId,
-            message.action,
-            void 0,
-            {
-              timeoutMs: HISTORY_DISPATCH_TIMEOUT_MS
-            }
-          );
+          const result = await sendToTab(tabId, message.action, void 0, {
+            timeoutMs: HISTORY_DISPATCH_TIMEOUT_MS
+          });
           if (!result.ok && result.error.code !== "TIMEOUT") {
             respondError(result.error);
             return;
@@ -1899,9 +2346,11 @@ var DriveSocket = class {
           if (tabId === agentTabId) {
             void refreshAgentTabBranding(tabId);
           }
-          respondOk({
-            ok: true
-          });
+          respondOk(
+            await withResolvedTabTarget(tabId, {
+              ok: true
+            })
+          );
           return;
         }
         case "drive.tab_list": {
@@ -1911,44 +2360,66 @@ var DriveSocket = class {
           return;
         }
         case "drive.tab_activate": {
-          const tabId = message.params?.tab_id;
-          if (typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number.",
-              retryable: false
-            });
+          const parsedTabId = readRequiredTabId(
+            message.params ?? {}
+          );
+          if (!parsedTabId.ok) {
+            respondError(parsedTabId.error);
             return;
           }
-          const tab = await getTab(tabId);
+          const tabId = parsedTabId.tabId;
+          const tabLookup = await requireTab(tabId, getTab);
+          if (!tabLookup.ok) {
+            respondError(tabLookup.error);
+            return;
+          }
+          const tab = tabLookup.tab;
           await wrapChromeVoid(
             (callback) => chrome.tabs.update(tabId, { active: true }, () => callback())
           );
           const windowId = tab.windowId;
+          let focusErrorMessage;
           if (typeof windowId === "number") {
-            await wrapChromeVoid(
-              (callback) => chrome.windows.update(
-                windowId,
-                { focused: true },
-                () => callback()
-              )
-            );
+            try {
+              await wrapChromeVoid(
+                (callback) => chrome.windows.update(
+                  windowId,
+                  { focused: true },
+                  () => callback()
+                )
+              );
+            } catch (error) {
+              focusErrorMessage = error instanceof Error ? error.message : "Unknown focus error.";
+            }
+          }
+          const activatedTab = await getTab(tabId).catch(() => void 0);
+          const focusedWindow = typeof windowId === "number" ? await getWindow(windowId).catch(() => void 0) : void 0;
+          const windowFocused = focusedWindow && typeof focusedWindow.focused === "boolean" ? focusedWindow.focused : void 0;
+          const outcome = resolveTabActivationOutcome({
+            tabId,
+            windowId: typeof windowId === "number" ? windowId : void 0,
+            activated: Boolean(activatedTab?.active === true),
+            focusErrorMessage,
+            windowFocused
+          });
+          if (!outcome.ok) {
+            respondError(outcome.error);
+            return;
           }
           markTabActive(tabId);
-          respondOk({ ok: true });
+          respondOk(outcome.result);
           this.sendTabReport();
           return;
         }
         case "drive.tab_close": {
-          const tabId = message.params?.tab_id;
-          if (typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number.",
-              retryable: false
-            });
+          const parsedTabId = readRequiredTabId(
+            message.params ?? {}
+          );
+          if (!parsedTabId.ok) {
+            respondError(parsedTabId.error);
             return;
           }
+          const tabId = parsedTabId.tabId;
           await wrapChromeVoid(
             (callback) => chrome.tabs.remove(tabId, () => callback())
           );
@@ -1980,18 +2451,12 @@ var DriveSocket = class {
             });
             return;
           }
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const error = await this.ensureDebuggerAttached(tabId);
           if (error) {
             respondError(error);
@@ -2008,7 +2473,7 @@ var DriveSocket = class {
               DEFAULT_DEBUGGER_COMMAND_TIMEOUT_MS
             );
             this.touchDebuggerSession(tabId);
-            respondOk({ ok: true });
+            respondOk(await withResolvedTabTarget(tabId, { ok: true }));
           } catch (error2) {
             const info = mapDebuggerErrorMessage(
               error2 instanceof Error ? error2.message : "Dialog handling failed."
@@ -2019,18 +2484,12 @@ var DriveSocket = class {
         }
         case "drive.click": {
           const params = message.params ?? {};
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const clickCount = params.click_count;
           const count = typeof clickCount === "number" && Number.isFinite(clickCount) ? Math.max(1, Math.floor(clickCount)) : 1;
           const error = await this.ensureDebuggerAttached(tabId);
@@ -2046,31 +2505,48 @@ var DriveSocket = class {
             respondError(pointResult.error);
             return;
           }
-          const { x, y } = pointResult.point;
-          self.setTimeout(() => {
-            void this.dispatchCdpClick(tabId, x, y, count).catch(
-              (error2) => {
-                console.debug("Deferred CDP click failed.", error2);
-              }
+          const { x, y, targetState } = pointResult.point;
+          if (targetState) {
+            const verified = await verifyPopupTriggerClick({
+              clickCount: count,
+              locator: params.locator,
+              point: pointResult.point,
+              prepareTarget: async () => await this.focusLocator(tabId, params.locator),
+              resolveLocatorPoint: async (locator) => await this.resolveLocatorPoint(tabId, locator),
+              dispatchCdpClick: async (clickX, clickY, clickCount2) => await this.dispatchCdpClick(tabId, clickX, clickY, clickCount2),
+              mapDispatchError: (error2) => mapDebuggerErrorMessage(
+                error2 instanceof Error ? error2.message : "Click dispatch failed."
+              ),
+              delayMs
+            });
+            if (!verified.ok) {
+              respondError(verified.error);
+              return;
+            }
+            respondOk(await withResolvedTabTarget(tabId, { ok: true }));
+            return;
+          }
+          try {
+            await this.dispatchCdpClick(tabId, x, y, count);
+          } catch (error2) {
+            respondError(
+              mapDebuggerErrorMessage(
+                error2 instanceof Error ? error2.message : "Click dispatch failed."
+              )
             );
-          }, 0);
-          respondOk({ ok: true });
+            return;
+          }
+          respondOk(await withResolvedTabTarget(tabId, { ok: true }));
           return;
         }
         case "drive.hover": {
           const params = message.params ?? {};
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const error = await this.ensureDebuggerAttached(tabId);
           if (error) {
             respondError(error);
@@ -2091,15 +2567,17 @@ var DriveSocket = class {
             if (waitMs > 0) {
               await delayMs(waitMs);
             }
-            const snapshot = await sendToTab(
-              tabId,
-              "drive.snapshot_html"
-            );
+            const snapshot = await sendToTab(tabId, "drive.snapshot_html");
             if (!snapshot.ok) {
               respondError(snapshot.error);
               return;
             }
-            respondOk(snapshot.result ?? { format: "html", snapshot: "" });
+            respondOk(
+              await withResolvedTabTarget(
+                tabId,
+                snapshot.result ?? { format: "html", snapshot: "" }
+              )
+            );
           } catch (error2) {
             const info = mapDebuggerErrorMessage(
               error2 instanceof Error ? error2.message : "Hover dispatch failed."
@@ -2110,35 +2588,23 @@ var DriveSocket = class {
         }
         case "drive.drag": {
           const params = message.params ?? {};
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const error = await this.ensureDebuggerAttached(tabId);
           if (error) {
             respondError(error);
             return;
           }
-          const fromResult = await this.resolveLocatorPoint(
-            tabId,
-            params.from
-          );
+          const fromResult = await this.resolveLocatorPoint(tabId, params.from);
           if (!fromResult.ok) {
             respondError(fromResult.error);
             return;
           }
-          const toResult = await this.resolveLocatorPoint(
-            tabId,
-            params.to
-          );
+          const toResult = await this.resolveLocatorPoint(tabId, params.to);
           if (!toResult.ok) {
             respondError(toResult.error);
             return;
@@ -2151,7 +2617,7 @@ var DriveSocket = class {
               toResult.point,
               steps
             );
-            respondOk({ ok: true });
+            respondOk(await withResolvedTabTarget(tabId, { ok: true }));
           } catch (error2) {
             const info = mapDebuggerErrorMessage(
               error2 instanceof Error ? error2.message : "Drag dispatch failed."
@@ -2171,30 +2637,20 @@ var DriveSocket = class {
             });
             return;
           }
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const error = await this.ensureDebuggerAttached(tabId);
           if (error) {
             respondError(error);
             return;
           }
           try {
-            await this.dispatchCdpKeyPress(
-              tabId,
-              key,
-              params.modifiers
-            );
-            respondOk({ ok: true });
+            await this.dispatchCdpKeyPress(tabId, key, params.modifiers);
+            respondOk(await withResolvedTabTarget(tabId, { ok: true }));
           } catch (error2) {
             const info = mapDebuggerErrorMessage(
               error2 instanceof Error ? error2.message : "Keyboard dispatch failed."
@@ -2214,18 +2670,12 @@ var DriveSocket = class {
             });
             return;
           }
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const count = typeof params.repeat === "number" && Number.isFinite(params.repeat) ? Math.max(1, Math.min(50, Math.floor(params.repeat))) : 1;
           const error = await this.ensureDebuggerAttached(tabId);
           if (error) {
@@ -2234,13 +2684,9 @@ var DriveSocket = class {
           }
           try {
             for (let i = 0; i < count; i += 1) {
-              await this.dispatchCdpKeyPress(
-                tabId,
-                key,
-                params.modifiers
-              );
+              await this.dispatchCdpKeyPress(tabId, key, params.modifiers);
             }
-            respondOk({ ok: true });
+            respondOk(await withResolvedTabTarget(tabId, { ok: true }));
           } catch (error2) {
             const info = mapDebuggerErrorMessage(
               error2 instanceof Error ? error2.message : "Keyboard dispatch failed."
@@ -2260,18 +2706,12 @@ var DriveSocket = class {
             });
             return;
           }
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const error = await this.ensureDebuggerAttached(tabId);
           if (error) {
             respondError(error);
@@ -2287,23 +2727,17 @@ var DriveSocket = class {
             respondError(result.error);
             return;
           }
-          respondOk({ ok: true });
+          respondOk(await withResolvedTabTarget(tabId, { ok: true }));
           return;
         }
         case "drive.select": {
           const params = message.params ?? {};
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const error = await this.ensureDebuggerAttached(tabId);
           if (error) {
             respondError(error);
@@ -2331,16 +2765,17 @@ var DriveSocket = class {
             respondError(info);
             return;
           }
-          const selectResult = await sendToTab(
-            tabId,
-            "drive.select",
-            params
-          );
+          const selectResult = await sendToTab(tabId, "drive.select", params);
           if (!selectResult.ok) {
             respondError(selectResult.error);
             return;
           }
-          respondOk(selectResult.result ?? { ok: true });
+          respondOk(
+            await withResolvedTabTarget(
+              tabId,
+              selectResult.result ?? { ok: true }
+            )
+          );
           return;
         }
         case "drive.fill_form": {
@@ -2354,18 +2789,12 @@ var DriveSocket = class {
             });
             return;
           }
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const error = await this.ensureDebuggerAttached(tabId);
           if (error) {
             respondError(error);
@@ -2426,13 +2855,9 @@ var DriveSocket = class {
               filled += 1;
               continue;
             }
-            const fallback = await sendToTab(
-              tabId,
-              "drive.fill_form",
-              {
-                fields: [field]
-              }
-            );
+            const fallback = await sendToTab(tabId, "drive.fill_form", {
+              fields: [field]
+            });
             if (!fallback.ok) {
               errors.push(
                 `Field ${index} could not be filled: ${fallback.error.message}`
@@ -2451,39 +2876,32 @@ var DriveSocket = class {
             }
             errors.push(`Field ${index} could not be filled.`);
           }
-          respondOk({
-            filled,
-            attempted: fields.length,
-            errors: errors.length > 0 ? errors : []
-          });
+          respondOk(
+            await withResolvedTabTarget(tabId, {
+              filled,
+              attempted: fields.length,
+              errors: errors.length > 0 ? errors : []
+            })
+          );
           return;
         }
         case "drive.scroll":
         case "drive.wait_for": {
           const params = message.params ?? {};
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const timeoutMs = message.action === "drive.wait_for" && typeof params.timeout_ms === "number" && Number.isFinite(params.timeout_ms) ? Math.max(1, Math.floor(params.timeout_ms) + 1e3) : void 0;
-          const result = await sendToTab(
-            tabId,
-            message.action,
-            params,
-            {
-              timeoutMs
-            }
-          );
+          const result = await sendToTab(tabId, message.action, params, {
+            timeoutMs
+          });
           if (result.ok) {
-            respondOk(result.result ?? { ok: true });
+            respondOk(
+              await withResolvedTabTarget(tabId, result.result ?? { ok: true })
+            );
           } else {
             respondError(result.error);
           }
@@ -2491,30 +2909,25 @@ var DriveSocket = class {
         }
         case "drive.screenshot": {
           const params = message.params ?? {};
-          let tabId = params.tab_id;
-          if (tabId !== void 0 && typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number when provided.",
-              retryable: false
-            });
+          const tabTarget = await resolveActionTabId(params);
+          if (!tabTarget.ok) {
+            respondError(tabTarget.error);
             return;
           }
-          if (tabId === void 0) {
-            tabId = await getDefaultTabId();
-          }
+          const tabId = tabTarget.tabId;
           const mode = params.mode === "full_page" || params.mode === "viewport" || params.mode === "element" ? params.mode : "viewport";
           const format = params.format === "jpeg" || params.format === "webp" ? params.format : "png";
           const quality = typeof params.quality === "number" && Number.isFinite(params.quality) ? Math.max(0, Math.min(100, Math.floor(params.quality))) : void 0;
           const tab = await getTab(tabId);
           const url = tab.url;
           if (typeof url === "string" && isRestrictedUrl(url)) {
-            respondError({
-              code: "NOT_SUPPORTED",
-              message: "Screenshots are not supported for this URL.",
-              retryable: false,
-              details: { url }
-            });
+            respondError(
+              buildRestrictedUrlError({
+                url,
+                operation: "screenshot",
+                action: "drive.screenshot"
+              })
+            );
             return;
           }
           const windowId = tab.windowId;
@@ -2679,7 +3092,7 @@ var DriveSocket = class {
                 format,
                 quality
               );
-              respondOk(rendered);
+              respondOk(await withResolvedTabTarget(tabId, rendered));
             } catch (error) {
               respondError(
                 mapScreenshotCaptureError(
@@ -2786,7 +3199,12 @@ var DriveSocket = class {
                     srcW2,
                     srcH2
                   );
-                  respondOk(await canvasToResult(cropCanvas2));
+                  respondOk(
+                    await withResolvedTabTarget(
+                      tabId,
+                      await canvasToResult(cropCanvas2)
+                    )
+                  );
                 } finally {
                   bitmap.close();
                 }
@@ -2816,7 +3234,12 @@ var DriveSocket = class {
                 srcW,
                 srcH
               );
-              respondOk(await canvasToResult(cropCanvas));
+              respondOk(
+                await withResolvedTabTarget(
+                  tabId,
+                  await canvasToResult(cropCanvas)
+                )
+              );
             } catch (error) {
               respondError(
                 mapScreenshotCaptureError(
@@ -2835,7 +3258,12 @@ var DriveSocket = class {
           try {
             const metaInfo = await getMetaInfo();
             const canvas = await captureFullPageCanvas(metaInfo);
-            respondOk(await canvasToResult(canvas));
+            respondOk(
+              await withResolvedTabTarget(
+                tabId,
+                await canvasToResult(canvas)
+              )
+            );
           } catch (error) {
             respondError(
               mapScreenshotCaptureError(
@@ -2973,7 +3401,23 @@ var DriveSocket = class {
         }
       };
     }
-    return { ok: true, point: { x, y } };
+    const targetState = coercePopupTriggerState(record.target_state);
+    return {
+      ok: true,
+      point: {
+        x,
+        y,
+        ...targetState ? { targetState } : {}
+      }
+    };
+  }
+  async focusLocator(tabId, locator) {
+    const focused = await sendToTab(tabId, "drive.focus_locator", {
+      locator
+    });
+    if (!focused.ok) {
+      throw new Error(focused.error.message);
+    }
   }
   async performCdpType(tabId, options) {
     const targetPoint = await sendToTab(tabId, "drive.type_target_point", {
@@ -3163,132 +3607,25 @@ var DriveSocket = class {
         error: sanitizeDriveErrorInfo(error)
       });
     };
-    try {
-      switch (message.action) {
-        case "debugger.attach": {
-          const params = message.params ?? {};
-          const tabId = params.tab_id;
-          if (typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number.",
-              retryable: false
-            });
-            return;
-          }
-          const error = await this.ensureDebuggerAttached(tabId);
-          if (error) {
-            respondError(error);
-            return;
-          }
-          respondAck({ ok: true });
-          return;
-        }
-        case "debugger.detach": {
-          const params = message.params ?? {};
-          const tabId = params.tab_id;
-          if (typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number.",
-              retryable: false
-            });
-            return;
-          }
-          const error = await this.detachDebugger(tabId);
-          if (error) {
-            respondError(error);
-            return;
-          }
-          respondAck({ ok: true });
-          return;
-        }
-        case "debugger.command": {
-          const params = message.params ?? {};
-          const tabId = params.tab_id;
-          if (typeof tabId !== "number") {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "tab_id must be a number.",
-              retryable: false
-            });
-            return;
-          }
-          if (typeof params.method !== "string" || params.method.length === 0) {
-            respondError({
-              code: "INVALID_ARGUMENT",
-              message: "method must be a non-empty string.",
-              retryable: false
-            });
-            return;
-          }
-          const session = this.debuggerSessions.get(tabId);
-          if (session?.attachPromise) {
-            try {
-              await session.attachPromise;
-            } catch (error) {
-              const info = mapDebuggerErrorMessage(
-                error instanceof Error ? error.message : "Debugger attach failed."
-              );
-              this.clearDebuggerSession(tabId);
-              respondError(info);
-              return;
-            }
-          }
-          const attachedSession = this.debuggerSessions.get(tabId);
-          if (!attachedSession?.attached) {
-            respondError({
-              code: "FAILED_PRECONDITION",
-              message: "Debugger is not attached to the requested tab.",
-              retryable: false
-            });
-            return;
-          }
-          try {
-            const result = await this.sendDebuggerCommand(
-              tabId,
-              params.method,
-              params.params,
-              DEFAULT_DEBUGGER_COMMAND_TIMEOUT_MS
-            );
-            this.touchDebuggerSession(tabId);
-            respondAck(result);
-          } catch (error) {
-            if (error instanceof DebuggerTimeoutError) {
-              respondError({
-                code: "TIMEOUT",
-                message: error.message,
-                retryable: true
-              });
-              return;
-            }
-            const info = mapDebuggerErrorMessage(
-              error instanceof Error ? error.message : "Debugger command failed."
-            );
-            respondError(info);
-          }
-          return;
-        }
-        default:
-          respondError({
-            code: "NOT_IMPLEMENTED",
-            message: `${message.action} not implemented in extension yet.`,
-            retryable: false
-          });
+    await dispatchDebuggerRequest(
+      message,
+      {
+        getSession: (tabId) => this.debuggerSessions.get(tabId),
+        ensureDebuggerAttached: async (tabId) => await this.ensureDebuggerAttached(tabId),
+        detachDebugger: async (tabId) => await this.detachDebugger(tabId),
+        sendDebuggerCommand: async (tabId, method, params, timeoutMs) => await this.sendDebuggerCommand(tabId, method, params, timeoutMs),
+        touchDebuggerSession: (tabId) => this.touchDebuggerSession(tabId),
+        clearDebuggerSession: (tabId) => this.clearDebuggerSession(tabId),
+        mapDebuggerErrorMessage,
+        debuggerCommandTimeoutMs: DEFAULT_DEBUGGER_COMMAND_TIMEOUT_MS
+      },
+      {
+        respondAck,
+        respondError
       }
-    } catch (error) {
-      const messageText = error instanceof Error ? error.message : "Unexpected debugger error.";
-      respondError({
-        code: "INSPECT_UNAVAILABLE",
-        message: messageText,
-        retryable: false
-      });
-    }
+    );
   }
   async handleDebuggerEvent(source, method, params) {
-    if (!await readDebuggerCapabilityEnabled()) {
-      return;
-    }
     const tabId = source.tabId;
     if (typeof tabId !== "number") {
       return;
@@ -3307,9 +3644,6 @@ var DriveSocket = class {
       return;
     }
     this.clearDebuggerSession(tabId);
-    if (!await readDebuggerCapabilityEnabled()) {
-      return;
-    }
     this.sendDebuggerEvent({
       tab_id: tabId,
       method: "Debugger.detached",
@@ -3402,12 +3736,11 @@ var DriveSocket = class {
       const tab = await getTab(tabId);
       const url = typeof tab.url === "string" ? tab.url : void 0;
       if (isRestrictedUrl(url)) {
-        return {
-          code: "NOT_SUPPORTED",
-          message: "Debugger cannot attach to restricted pages.",
-          retryable: false,
-          details: { url }
-        };
+        return buildRestrictedUrlError({
+          url: url ?? "about:blank",
+          operation: "debugger",
+          action: "debugger.attach"
+        });
       }
     } catch (error) {
       return mapDebuggerErrorMessage(
@@ -3542,6 +3875,17 @@ chrome.runtime.onConnect.addListener((port) => {
 chrome.windows.onRemoved.addListener((windowId) => {
   permissionPrompts.handleWindowRemoved(windowId);
 });
+chrome.windows.onFocusChanged.addListener((windowId) => {
+  if (windowId === chrome.windows.WINDOW_ID_NONE) {
+    return;
+  }
+  void queryActiveTabIdInWindow(windowId).then((tabId) => {
+    markTabActive(tabId);
+    socket.sendTabReport();
+  }).catch(() => {
+    socket.sendTabReport();
+  });
+});
 chrome.tabs.onActivated.addListener((activeInfo) => {
   markTabActive(activeInfo.tabId);
   socket.sendTabReport();
@@ -3615,26 +3959,23 @@ chrome.storage.onChanged.addListener(
     if (areaName !== "local") {
       return;
     }
-    const debuggerChange = changes[DEBUGGER_CAPABILITY_ENABLED_KEY];
-    if (!debuggerChange) {
+    const corePortChange = changes[LEGACY_CORE_PORT_KEY];
+    if (!corePortChange) {
       return;
     }
-    if (typeof debuggerChange.newValue === "boolean") {
-      void socket.handleDebuggerCapabilityChange(debuggerChange.newValue).catch((error) => {
-        console.error(
-          "DriveSocket handleDebuggerCapabilityChange failed:",
-          error
-        );
+    let work = Promise.resolve();
+    if (corePortChange) {
+      work = work.then(async () => {
+        await clearLegacyCorePort(chrome.storage.local);
       });
-      return;
     }
-    void socket.refreshDebuggerCapabilityState().catch((error) => {
-      console.error(
-        "DriveSocket refreshDebuggerCapabilityState failed:",
-        error
-      );
+    void work.catch((error) => {
+      console.error("DriveSocket storage change handling failed:", error);
     });
   }
 );
+void clearLegacyCorePort(chrome.storage.local).catch((error) => {
+  console.warn("Failed to clear legacy corePort storage.", error);
+});
 socket.start();
 //# sourceMappingURL=background.js.map