@flrande/browserctl 0.1.0-dev.7.1

package/extensions/chrome-relay/background.js

@@ -0,0 +1,1687 @@
+const CONFIG_KEY = "browserctlRelayConfig";
+const DEFAULT_BRIDGE_URL = "ws://127.0.0.1:9223/bridge";
+const RECONNECT_DELAY_MS = 1500;
+const DEBUGGER_PROTOCOL_VERSION = "1.3";
+const TELEMETRY_BODY_MAX_CHARS = 262144;
+
+let socket = null;
+let reconnectTimer = null;
+let connectInFlight = false;
+let telemetryRequestSequence = 1;
+let runtimeState = {
+  connected: false,
+  bridgeUrl: DEFAULT_BRIDGE_URL,
+  token: "",
+  lastError: "",
+  lastConnectedAt: ""
+};
+
+const attachedDebuggerTabs = new Set();
+const networkRequestMetaByTab = new Map();
+
+function normalizeString(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+
+  return value.trim();
+}
+
+function normalizeBridgeUrl(value) {
+  const rawValue = normalizeString(value);
+  if (rawValue.length === 0) {
+    return DEFAULT_BRIDGE_URL;
+  }
+
+  try {
+    const parsed = new URL(rawValue);
+    if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+      return DEFAULT_BRIDGE_URL;
+    }
+
+    return parsed.toString();
+  } catch {
+    return DEFAULT_BRIDGE_URL;
+  }
+}
+
+function toErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function buildSocketUrl(config) {
+  return normalizeBridgeUrl(config.bridgeUrl);
+}
+
+async function readConfig() {
+  const stored = await chrome.storage.local.get(CONFIG_KEY);
+  const rawConfig = stored?.[CONFIG_KEY];
+  const config = {
+    bridgeUrl: DEFAULT_BRIDGE_URL,
+    token: ""
+  };
+
+  if (rawConfig !== null && typeof rawConfig === "object") {
+    config.bridgeUrl = normalizeBridgeUrl(rawConfig.bridgeUrl);
+    config.token = normalizeString(rawConfig.token);
+  }
+
+  runtimeState.bridgeUrl = config.bridgeUrl;
+  runtimeState.token = config.token;
+  return config;
+}
+
+async function writeConfig(nextConfig) {
+  const normalized = {
+    bridgeUrl: normalizeBridgeUrl(nextConfig.bridgeUrl),
+    token: normalizeString(nextConfig.token)
+  };
+  await chrome.storage.local.set({
+    [CONFIG_KEY]: normalized
+  });
+  runtimeState.bridgeUrl = normalized.bridgeUrl;
+  runtimeState.token = normalized.token;
+  return normalized;
+}
+
+function setDisconnectedState(reason) {
+  runtimeState.connected = false;
+  if (reason.length > 0) {
+    runtimeState.lastError = reason;
+  }
+}
+
+function clearReconnectTimer() {
+  if (reconnectTimer === null) {
+    return;
+  }
+
+  clearTimeout(reconnectTimer);
+  reconnectTimer = null;
+}
+
+function scheduleReconnect() {
+  if (reconnectTimer !== null) {
+    return;
+  }
+
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = null;
+    void connectToBridge(false);
+  }, RECONNECT_DELAY_MS);
+}
+
+function sendSocketEnvelope(payload) {
+  if (socket === null || socket.readyState !== WebSocket.OPEN) {
+    return false;
+  }
+
+  socket.send(JSON.stringify(payload));
+  return true;
+}
+
+function sendBridgeEvent(event) {
+  sendSocketEnvelope({
+    type: "event",
+    event
+  });
+}
+
+function sendHello() {
+  sendSocketEnvelope({
+    type: "hello",
+    role: "extension",
+    extensionId: chrome.runtime.id,
+    version: chrome.runtime.getManifest().version,
+    token: runtimeState.token
+  });
+}
+
+async function executeInTab(tabId, func, args = []) {
+  const results = await chrome.scripting.executeScript({
+    target: { tabId },
+    func,
+    args
+  });
+
+  if (!Array.isArray(results) || results.length === 0) {
+    return undefined;
+  }
+
+  return results[0]?.result;
+}
+
+function toTabSummary(tab) {
+  return {
+    tabId: typeof tab.id === "number" ? tab.id : undefined,
+    windowId: typeof tab.windowId === "number" ? tab.windowId : undefined,
+    active: tab.active === true,
+    url: typeof tab.url === "string" ? tab.url : "",
+    title: typeof tab.title === "string" ? tab.title : ""
+  };
+}
+
+function requireNonEmptyString(value, fieldName) {
+  const normalized = normalizeString(value);
+  if (normalized.length === 0) {
+    throw new Error(`${fieldName} must be a non-empty string.`);
+  }
+
+  return normalized;
+}
+
+function requireTabId(value, fieldName = "tabId") {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${fieldName} must be a number.`);
+  }
+
+  return value;
+}
+
+function getNetworkRequestMap(tabId) {
+  const existing = networkRequestMetaByTab.get(tabId);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = new Map();
+  networkRequestMetaByTab.set(tabId, created);
+  return created;
+}
+
+function clearNetworkRequestState(tabId) {
+  networkRequestMetaByTab.delete(tabId);
+}
+
+function getOrCreateNetworkRequestMeta(tabId, rawRequestId) {
+  const requestMap = getNetworkRequestMap(tabId);
+  const existing = requestMap.get(rawRequestId);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = {
+    requestId: `request:extension:${tabId}:${telemetryRequestSequence}`,
+    rawRequestId,
+    url: "",
+    method: undefined,
+    resourceType: undefined,
+    status: undefined
+  };
+  telemetryRequestSequence += 1;
+  requestMap.set(rawRequestId, created);
+  return created;
+}
+
+function readRemoteObjectValue(value) {
+  if (value === null || typeof value !== "object") {
+    return "";
+  }
+
+  if ("value" in value && value.value !== undefined) {
+    try {
+      if (typeof value.value === "string") {
+        return value.value;
+      }
+
+      return JSON.stringify(value.value);
+    } catch {
+      return String(value.value);
+    }
+  }
+
+  if ("unserializableValue" in value && typeof value.unserializableValue === "string") {
+    return value.unserializableValue;
+  }
+
+  if ("description" in value && typeof value.description === "string") {
+    return value.description;
+  }
+
+  return "";
+}
+
+function toConsoleEntry(params) {
+  const args = Array.isArray(params?.args) ? params.args : [];
+  const text = args.map((item) => readRemoteObjectValue(item)).join(" ");
+  const stackFrames = Array.isArray(params?.stackTrace?.callFrames)
+    ? params.stackTrace.callFrames
+    : [];
+  const firstFrame = stackFrames[0];
+
+  return {
+    type: normalizeString(params?.type) || "log",
+    text,
+    ...(firstFrame !== undefined
+      ? {
+          location: {
+            ...(normalizeString(firstFrame.url).length > 0 ? { url: firstFrame.url } : {}),
+            ...(typeof firstFrame.lineNumber === "number"
+              ? { lineNumber: firstFrame.lineNumber }
+              : {}),
+            ...(typeof firstFrame.columnNumber === "number"
+              ? { columnNumber: firstFrame.columnNumber }
+              : {})
+          }
+        }
+      : {})
+  };
+}
+
+function normalizeTelemetryBody(body, base64Encoded) {
+  if (typeof body !== "string") {
+    return {
+      body: "",
+      encoding: "utf8"
+    };
+  }
+
+  const sliced = body.slice(0, TELEMETRY_BODY_MAX_CHARS);
+  return {
+    body: sliced,
+    encoding: base64Encoded === true ? "base64" : "utf8"
+  };
+}
+
+async function attachDebuggerToTab(tabId) {
+  if (attachedDebuggerTabs.has(tabId)) {
+    return;
+  }
+
+  let attachSucceeded = false;
+  try {
+    await chrome.debugger.attach({ tabId }, DEBUGGER_PROTOCOL_VERSION);
+    attachSucceeded = true;
+  } catch (error) {
+    const errorMessage = toErrorMessage(error).toLowerCase();
+    if (errorMessage.includes("already attached")) {
+      attachSucceeded = true;
+    } else if (errorMessage.includes("another debugger")) {
+      throw new Error(`Tab ${tabId} is already attached by another debugger.`);
+    } else {
+      throw error;
+    }
+  }
+
+  if (!attachSucceeded) {
+    return;
+  }
+
+  attachedDebuggerTabs.add(tabId);
+  try {
+    await chrome.debugger.sendCommand({ tabId }, "Runtime.enable");
+  } catch {
+    // Ignore optional domain initialization failures.
+  }
+
+  try {
+    await chrome.debugger.sendCommand({ tabId }, "Network.enable");
+  } catch {
+    // Ignore optional domain initialization failures.
+  }
+
+  try {
+    await chrome.debugger.sendCommand({ tabId }, "DOM.enable");
+  } catch {
+    // Ignore optional domain initialization failures.
+  }
+}
+
+async function detachDebuggerFromTab(tabId) {
+  if (!attachedDebuggerTabs.has(tabId)) {
+    clearNetworkRequestState(tabId);
+    return;
+  }
+
+  attachedDebuggerTabs.delete(tabId);
+  clearNetworkRequestState(tabId);
+  try {
+    await chrome.debugger.detach({ tabId });
+  } catch {
+    // Ignore detach errors for already closed tabs.
+  }
+}
+
+async function ensureDebuggerAttached(tabId) {
+  try {
+    await attachDebuggerToTab(tabId);
+    return true;
+  } catch (error) {
+    runtimeState.lastError = `Debugger attach failed for tab ${tabId}: ${toErrorMessage(error)}`;
+    return false;
+  }
+}
+
+async function emitNetworkResponseEvent(tabId, rawRequestId) {
+  const requestMap = networkRequestMetaByTab.get(tabId);
+  const requestMeta = requestMap?.get(rawRequestId);
+  if (requestMeta === undefined) {
+    return;
+  }
+
+  let responseBodyPayload = {
+    body: "",
+    encoding: "utf8"
+  };
+  try {
+    const responseBody = await chrome.debugger.sendCommand(
+      { tabId },
+      "Network.getResponseBody",
+      { requestId: rawRequestId }
+    );
+    responseBodyPayload = normalizeTelemetryBody(
+      responseBody?.body,
+      responseBody?.base64Encoded === true
+    );
+  } catch {
+    // Some resource types do not expose bodies; keep empty body payload.
+  }
+
+  sendBridgeEvent({
+    kind: "response",
+    tabId,
+    response: {
+      requestId: requestMeta.requestId,
+      url: requestMeta.url,
+      ...(typeof requestMeta.status === "number" ? { status: requestMeta.status } : {}),
+      ...(typeof requestMeta.method === "string" ? { method: requestMeta.method } : {}),
+      ...(typeof requestMeta.resourceType === "string"
+        ? { resourceType: requestMeta.resourceType }
+        : {}),
+      ...responseBodyPayload
+    }
+  });
+
+  requestMap.delete(rawRequestId);
+}
+
+function handleDebuggerEvent(source, method, params) {
+  if (typeof source?.tabId !== "number") {
+    return;
+  }
+
+  const tabId = source.tabId;
+  if (method === "Runtime.consoleAPICalled") {
+    sendBridgeEvent({
+      kind: "console",
+      tabId,
+      entry: toConsoleEntry(params)
+    });
+    return;
+  }
+
+  if (method === "Network.requestWillBeSent") {
+    const rawRequestId = normalizeString(params?.requestId);
+    if (rawRequestId.length === 0) {
+      return;
+    }
+
+    const requestMeta = getOrCreateNetworkRequestMeta(tabId, rawRequestId);
+    requestMeta.url = normalizeString(params?.request?.url);
+    const methodValue = normalizeString(params?.request?.method);
+    if (methodValue.length > 0) {
+      requestMeta.method = methodValue;
+    }
+    return;
+  }
+
+  if (method === "Network.responseReceived") {
+    const rawRequestId = normalizeString(params?.requestId);
+    if (rawRequestId.length === 0) {
+      return;
+    }
+
+    const requestMeta = getOrCreateNetworkRequestMeta(tabId, rawRequestId);
+    const responseUrl = normalizeString(params?.response?.url);
+    if (responseUrl.length > 0) {
+      requestMeta.url = responseUrl;
+    }
+    if (typeof params?.response?.status === "number") {
+      requestMeta.status = params.response.status;
+    }
+    const resourceType = normalizeString(params?.type);
+    if (resourceType.length > 0) {
+      requestMeta.resourceType = resourceType;
+    }
+    return;
+  }
+
+  if (method === "Network.loadingFinished") {
+    const rawRequestId = normalizeString(params?.requestId);
+    if (rawRequestId.length === 0) {
+      return;
+    }
+
+    void emitNetworkResponseEvent(tabId, rawRequestId);
+    return;
+  }
+
+  if (method === "Network.loadingFailed") {
+    const rawRequestId = normalizeString(params?.requestId);
+    if (rawRequestId.length === 0) {
+      return;
+    }
+
+    const requestMap = networkRequestMetaByTab.get(tabId);
+    requestMap?.delete(rawRequestId);
+  }
+}
+
+function registerDebuggerTelemetryHandlers() {
+  chrome.debugger.onEvent.addListener((source, method, params) => {
+    handleDebuggerEvent(source, method, params);
+  });
+
+  chrome.debugger.onDetach.addListener((source) => {
+    if (typeof source?.tabId !== "number") {
+      return;
+    }
+
+    attachedDebuggerTabs.delete(source.tabId);
+    clearNetworkRequestState(source.tabId);
+  });
+
+  chrome.tabs.onRemoved.addListener((tabId) => {
+    void detachDebuggerFromTab(tabId);
+  });
+}
+
+async function handleTabOpen(params) {
+  const url = requireNonEmptyString(params?.url, "url");
+  const tab = await chrome.tabs.create({
+    url,
+    active: true
+  });
+  if (typeof tab.id === "number") {
+    await ensureDebuggerAttached(tab.id);
+  }
+  return toTabSummary(tab);
+}
+
+async function handleTabGoto(params) {
+  const tabId = requireTabId(params?.tabId);
+  const url = requireNonEmptyString(params?.url, "url");
+  await ensureDebuggerAttached(tabId);
+  const tab = await chrome.tabs.update(tabId, {
+    url,
+    active: true
+  });
+  return toTabSummary(tab);
+}
+
+async function handleTabFocus(params) {
+  const tabId = requireTabId(params?.tabId);
+  await ensureDebuggerAttached(tabId);
+  const tab = await chrome.tabs.get(tabId);
+  if (typeof tab.windowId === "number") {
+    await chrome.windows.update(tab.windowId, { focused: true });
+  }
+  const updated = await chrome.tabs.update(tabId, { active: true });
+  return toTabSummary(updated);
+}
+
+async function handleTabClose(params) {
+  const tabId = requireTabId(params?.tabId);
+  await detachDebuggerFromTab(tabId);
+  await chrome.tabs.remove(tabId);
+  return {
+    tabId,
+    closed: true
+  };
+}
+
+async function handleTabInfo(params) {
+  const tabId = requireTabId(params?.tabId);
+  await ensureDebuggerAttached(tabId);
+  const tab = await chrome.tabs.get(tabId);
+  return toTabSummary(tab);
+}
+
+async function handleTabSnapshot(params) {
+  const tabId = requireTabId(params?.tabId);
+  await ensureDebuggerAttached(tabId);
+  const result = await executeInTab(
+    tabId,
+    () => ({
+      url: window.location.href,
+      title: document.title ?? "",
+      html: document.documentElement ? document.documentElement.outerHTML : ""
+    }),
+    []
+  );
+
+  if (result !== null && typeof result === "object") {
+    return {
+      tabId,
+      url: typeof result.url === "string" ? result.url : "",
+      title: typeof result.title === "string" ? result.title : "",
+      html: typeof result.html === "string" ? result.html : ""
+    };
+  }
+
+  const tab = await chrome.tabs.get(tabId);
+  return {
+    tabId,
+    url: typeof tab.url === "string" ? tab.url : "",
+    title: typeof tab.title === "string" ? tab.title : "",
+    html: ""
+  };
+}
+
+function parseCapturedImageDataUrl(dataUrl) {
+  const normalized = normalizeString(dataUrl);
+  const match = /^data:([^;,]+);base64,(.+)$/i.exec(normalized);
+  if (match === null) {
+    throw new Error("tabs.captureVisibleTab returned unsupported image payload.");
+  }
+
+  const mimeType = match[1] || "image/png";
+  const imageBase64 = match[2] || "";
+  if (imageBase64.length === 0) {
+    throw new Error("tabs.captureVisibleTab returned empty image payload.");
+  }
+
+  return {
+    mimeType,
+    imageBase64
+  };
+}
+
+async function cropCapturedImageDataUrl(dataUrl, bounds) {
+  const fallback = parseCapturedImageDataUrl(dataUrl);
+  if (
+    typeof OffscreenCanvas !== "function" ||
+    typeof createImageBitmap !== "function" ||
+    typeof bounds !== "object" ||
+    bounds === null
+  ) {
+    return fallback;
+  }
+
+  const x = typeof bounds.x === "number" && Number.isFinite(bounds.x) ? bounds.x : 0;
+  const y = typeof bounds.y === "number" && Number.isFinite(bounds.y) ? bounds.y : 0;
+  const width = typeof bounds.width === "number" && Number.isFinite(bounds.width) ? bounds.width : 0;
+  const height = typeof bounds.height === "number" && Number.isFinite(bounds.height) ? bounds.height : 0;
+  if (width <= 0 || height <= 0) {
+    return fallback;
+  }
+
+  try {
+    const response = await fetch(dataUrl);
+    const imageBlob = await response.blob();
+    const bitmap = await createImageBitmap(imageBlob);
+    const sx = Math.max(0, Math.min(bitmap.width - 1, Math.floor(x)));
+    const sy = Math.max(0, Math.min(bitmap.height - 1, Math.floor(y)));
+    const sw = Math.max(1, Math.min(bitmap.width - sx, Math.ceil(width)));
+    const sh = Math.max(1, Math.min(bitmap.height - sy, Math.ceil(height)));
+    const canvas = new OffscreenCanvas(sw, sh);
+    const context = canvas.getContext("2d");
+    if (context === null) {
+      return fallback;
+    }
+
+    context.drawImage(bitmap, sx, sy, sw, sh, 0, 0, sw, sh);
+    const croppedBlob = await canvas.convertToBlob({
+      type: "image/png"
+    });
+    const croppedBuffer = await croppedBlob.arrayBuffer();
+    const bytes = new Uint8Array(croppedBuffer);
+    let binary = "";
+    for (let index = 0; index < bytes.length; index += 1) {
+      binary += String.fromCharCode(bytes[index]);
+    }
+
+    return {
+      mimeType: "image/png",
+      imageBase64: btoa(binary),
+      width: sw,
+      height: sh
+    };
+  } catch {
+    return fallback;
+  }
+}
+
+async function handleTabScreenshot(params) {
+  const tabId = requireTabId(params?.tabId);
+  await ensureDebuggerAttached(tabId);
+  const tab = await chrome.tabs.get(tabId);
+  if (typeof tab.windowId !== "number") {
+    throw new Error(`Unable to resolve window for tab ${tabId}.`);
+  }
+
+  await chrome.windows.update(tab.windowId, { focused: true });
+  await chrome.tabs.update(tabId, { active: true });
+
+  const rawDataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {
+    format: "png"
+  });
+  const parsedImage = parseCapturedImageDataUrl(rawDataUrl);
+
+  const dimensions = await executeInTab(
+    tabId,
+    () => ({
+      width:
+        typeof window.innerWidth === "number" && typeof window.devicePixelRatio === "number"
+          ? Math.max(1, Math.round(window.innerWidth * window.devicePixelRatio))
+          : undefined,
+      height:
+        typeof window.innerHeight === "number" && typeof window.devicePixelRatio === "number"
+          ? Math.max(1, Math.round(window.innerHeight * window.devicePixelRatio))
+          : undefined
+    }),
+    []
+  );
+
+  return {
+    tabId,
+    mimeType: parsedImage.mimeType,
+    encoding: "base64",
+    imageBase64: parsedImage.imageBase64,
+    ...(typeof dimensions?.width === "number" ? { width: dimensions.width } : {}),
+    ...(typeof dimensions?.height === "number" ? { height: dimensions.height } : {})
+  };
+}
+
+async function handleTabDomQuery(params) {
+  const tabId = requireTabId(params?.tabId);
+  const selector = requireNonEmptyString(params?.selector, "selector");
+  await ensureDebuggerAttached(tabId);
+  const result = await executeInTab(
+    tabId,
+    (selectorValue) => {
+      let element = null;
+      try {
+        element = document.querySelector(selectorValue);
+      } catch {
+        return {
+          selector: selectorValue,
+          found: false
+        };
+      }
+
+      if (element === null) {
+        return {
+          selector: selectorValue,
+          found: false
+        };
+      }
+
+      const attributes = {};
+      for (const attribute of Array.from(element.attributes)) {
+        attributes[attribute.name] = attribute.value;
+      }
+
+      return {
+        selector: selectorValue,
+        found: true,
+        node: {
+          tagName: element.tagName.toLowerCase(),
+          id: element.id || undefined,
+          className: element.className || undefined,
+          text: (element.textContent || "").trim().slice(0, 300),
+          attributes
+        }
+      };
+    },
+    [selector]
+  );
+
+  if (result !== null && typeof result === "object") {
+    return result;
+  }
+
+  return {
+    selector,
+    found: false
+  };
+}
+
+async function handleTabDomQueryAll(params) {
+  const tabId = requireTabId(params?.tabId);
+  const selector = requireNonEmptyString(params?.selector, "selector");
+  await ensureDebuggerAttached(tabId);
+  const result = await executeInTab(
+    tabId,
+    (selectorValue) => {
+      let elements = [];
+      try {
+        elements = Array.from(document.querySelectorAll(selectorValue));
+      } catch {
+        return {
+          selector: selectorValue,
+          count: 0,
+          nodes: []
+        };
+      }
+
+      const nodes = elements.map((element, index) => {
+        const attributes = {};
+        for (const attribute of Array.from(element.attributes)) {
+          attributes[attribute.name] = attribute.value;
+        }
+
+        return {
+          index,
+          tagName: element.tagName.toLowerCase(),
+          id: element.id || undefined,
+          className: element.className || undefined,
+          text: (element.textContent || "").trim().slice(0, 300),
+          attributes
+        };
+      });
+
+      return {
+        selector: selectorValue,
+        count: nodes.length,
+        nodes
+      };
+    },
+    [selector]
+  );
+
+  if (result !== null && typeof result === "object") {
+    return result;
+  }
+
+  return {
+    selector,
+    count: 0,
+    nodes: []
+  };
+}
+
+async function handleTabElementScreenshot(params) {
+  const tabId = requireTabId(params?.tabId);
+  const selector = requireNonEmptyString(params?.selector, "selector");
+  await ensureDebuggerAttached(tabId);
+  const tab = await chrome.tabs.get(tabId);
+  if (typeof tab.windowId !== "number") {
+    throw new Error(`Unable to resolve window for tab ${tabId}.`);
+  }
+
+  await chrome.windows.update(tab.windowId, { focused: true });
+  await chrome.tabs.update(tabId, { active: true });
+  const elementMeta = await executeInTab(
+    tabId,
+    (selectorValue) => {
+      let element = null;
+      try {
+        element = document.querySelector(selectorValue);
+      } catch {
+        return {
+          selector: selectorValue,
+          found: false
+        };
+      }
+
+      if (element === null) {
+        return {
+          selector: selectorValue,
+          found: false
+        };
+      }
+
+      element.scrollIntoView({
+        block: "center",
+        inline: "center",
+        behavior: "auto"
+      });
+      const rect = element.getBoundingClientRect();
+      const dpr = typeof window.devicePixelRatio === "number" ? window.devicePixelRatio : 1;
+      return {
+        selector: selectorValue,
+        found: true,
+        x: rect.left * dpr,
+        y: rect.top * dpr,
+        width: Math.max(1, Math.round(rect.width * dpr)),
+        height: Math.max(1, Math.round(rect.height * dpr))
+      };
+    },
+    [selector]
+  );
+
+  if (elementMeta === null || typeof elementMeta !== "object" || elementMeta.found !== true) {
+    return {
+      selector,
+      found: false
+    };
+  }
+
+  const rawDataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {
+    format: "png"
+  });
+  const parsedImage = await cropCapturedImageDataUrl(rawDataUrl, elementMeta);
+  return {
+    selector,
+    found: true,
+    mimeType: parsedImage.mimeType,
+    encoding: "base64",
+    imageBase64: parsedImage.imageBase64,
+    ...(typeof elementMeta.width === "number" ? { width: elementMeta.width } : {}),
+    ...(typeof elementMeta.height === "number" ? { height: elementMeta.height } : {})
+  };
+}
+
+async function handleTabA11ySnapshot(params) {
+  const tabId = requireTabId(params?.tabId);
+  const selector = normalizeString(params?.selector);
+  await ensureDebuggerAttached(tabId);
+  const result = await executeInTab(
+    tabId,
+    (selectorValue) => {
+      const root =
+        selectorValue.length > 0
+          ? document.querySelector(selectorValue)
+          : document.body ?? document.documentElement;
+      if (root === null) {
+        return {
+          selector: selectorValue,
+          found: false
+        };
+      }
+
+      const build = (element, depth) => {
+        const role =
+          element.getAttribute("role") ||
+          (element.tagName.toLowerCase() === "a"
+            ? "link"
+            : element.tagName.toLowerCase() === "button"
+              ? "button"
+              : element.tagName.toLowerCase() === "input"
+                ? "textbox"
+                : "generic");
+        const name =
+          element.getAttribute("aria-label") ||
+          element.getAttribute("alt") ||
+          (element.textContent || "").trim().slice(0, 120);
+        if (depth >= 5) {
+          return {
+            role,
+            ...(name.length > 0 ? { name } : {})
+          };
+        }
+
+        const children = Array.from(element.children)
+          .slice(0, 30)
+          .map((child) => build(child, depth + 1));
+        return {
+          role,
+          ...(name.length > 0 ? { name } : {}),
+          ...(children.length > 0 ? { children } : {})
+        };
+      };
+
+      return {
+        selector: selectorValue,
+        found: true,
+        snapshot: build(root, 0)
+      };
+    },
+    [selector]
+  );
+
+  if (result !== null && typeof result === "object") {
+    return result;
+  }
+
+  return {
+    selector,
+    found: false
+  };
+}
+
+function toCookieSummary(cookie) {
+  return {
+    name: typeof cookie.name === "string" ? cookie.name : "",
+    value: typeof cookie.value === "string" ? cookie.value : "",
+    ...(typeof cookie.domain === "string" ? { domain: cookie.domain } : {}),
+    ...(typeof cookie.path === "string" ? { path: cookie.path } : {}),
+    ...(typeof cookie.expires === "number" ? { expires: cookie.expires } : {}),
+    ...(typeof cookie.httpOnly === "boolean" ? { httpOnly: cookie.httpOnly } : {}),
+    ...(typeof cookie.secure === "boolean" ? { secure: cookie.secure } : {}),
+    ...(typeof cookie.sameSite === "string" ? { sameSite: cookie.sameSite } : {})
+  };
+}
+
+function toCookieRemovalUrl(cookie, fallbackUrl) {
+  if (typeof fallbackUrl === "string" && fallbackUrl.length > 0) {
+    return fallbackUrl;
+  }
+
+  const domain = normalizeString(cookie?.domain).replace(/^\./, "");
+  const path = normalizeString(cookie?.path) || "/";
+  const secure = cookie?.secure === true;
+  if (domain.length === 0) {
+    throw new Error("Unable to resolve cookie domain for removal.");
+  }
+
+  return `${secure ? "https" : "http"}://${domain}${path}`;
+}
+
+async function handleTabCookieGet(params) {
+  const tabId = requireTabId(params?.tabId);
+  await ensureDebuggerAttached(tabId);
+  const tab = await chrome.tabs.get(tabId);
+  const tabUrl = requireNonEmptyString(tab?.url, "tab.url");
+  const name = normalizeString(params?.name);
+  const cookies = await chrome.cookies.getAll({
+    url: tabUrl,
+    ...(name.length > 0 ? { name } : {})
+  });
+
+  return {
+    cookies: cookies.map((cookie) => toCookieSummary(cookie)),
+    ...(name.length > 0 ? { name } : {})
+  };
+}
+
+async function handleTabCookieSet(params) {
+  const tabId = requireTabId(params?.tabId);
+  await ensureDebuggerAttached(tabId);
+  const tab = await chrome.tabs.get(tabId);
+  const tabUrl = requireNonEmptyString(tab?.url, "tab.url");
+  const name = requireNonEmptyString(params?.name, "name");
+  const value = requireNonEmptyString(params?.value, "value");
+  const cookieUrl = normalizeString(params?.url) || tabUrl;
+
+  const cookie = await chrome.cookies.set({
+    url: cookieUrl,
+    name,
+    value
+  });
+
+  return {
+    set: true,
+    cookie: cookie !== null && cookie !== undefined
+      ? toCookieSummary(cookie)
+      : {
+          name,
+          value
+        }
+  };
+}
+
+async function handleTabCookieClear(params) {
+  const tabId = requireTabId(params?.tabId);
+  await ensureDebuggerAttached(tabId);
+  const tab = await chrome.tabs.get(tabId);
+  const tabUrl = requireNonEmptyString(tab?.url, "tab.url");
+  const name = normalizeString(params?.name);
+  const cookies = await chrome.cookies.getAll({
+    url: tabUrl,
+    ...(name.length > 0 ? { name } : {})
+  });
+
+  let removed = 0;
+  for (const cookie of cookies) {
+    const removeResult = await chrome.cookies.remove({
+      url: toCookieRemovalUrl(cookie, tabUrl),
+      name: cookie.name,
+      ...(typeof cookie.storeId === "string" ? { storeId: cookie.storeId } : {})
+    });
+    if (removeResult !== null && removeResult !== undefined) {
+      removed += 1;
+    }
+  }
+
+  return {
+    cleared: true,
+    count: removed,
+    ...(name.length > 0 ? { name } : {})
+  };
+}
+
+async function handleTabStorageGet(params) {
+  const tabId = requireTabId(params?.tabId);
+  const scope = requireNonEmptyString(params?.scope, "scope");
+  if (scope !== "local" && scope !== "session") {
+    throw new Error("scope must be local or session.");
+  }
+
+  const key = requireNonEmptyString(params?.key, "key");
+  await ensureDebuggerAttached(tabId);
+  const result = await executeInTab(
+    tabId,
+    (scopeValue, keyValue) => {
+      const storage = scopeValue === "session" ? window.sessionStorage : window.localStorage;
+      const value = storage.getItem(keyValue);
+      return {
+        scope: scopeValue,
+        key: keyValue,
+        exists: value !== null,
+        ...(value !== null ? { value } : {})
+      };
+    },
+    [scope, key]
+  );
+
+  if (result !== null && typeof result === "object") {
+    return result;
+  }
+
+  return {
+    scope,
+    key,
+    exists: false
+  };
+}
+
+async function handleTabStorageSet(params) {
+  const tabId = requireTabId(params?.tabId);
+  const scope = requireNonEmptyString(params?.scope, "scope");
+  if (scope !== "local" && scope !== "session") {
+    throw new Error("scope must be local or session.");
+  }
+
+  const key = requireNonEmptyString(params?.key, "key");
+  const value = requireNonEmptyString(params?.value, "value");
+  await ensureDebuggerAttached(tabId);
+  await executeInTab(
+    tabId,
+    (scopeValue, keyValue, valueText) => {
+      const storage = scopeValue === "session" ? window.sessionStorage : window.localStorage;
+      storage.setItem(keyValue, valueText);
+    },
+    [scope, key, value]
+  );
+
+  return {
+    scope,
+    key,
+    value,
+    set: true
+  };
+}
+
+async function handleTabFrameList(params) {
+  const tabId = requireTabId(params?.tabId);
+  await ensureDebuggerAttached(tabId);
+  const result = await executeInTab(
+    tabId,
+    () => {
+      const frames = [];
+
+      const walk = (currentWindow, framePath, depth) => {
+        let url = "";
+        let title = "";
+        try {
+          url = String(currentWindow.location.href || "");
+          title = String(currentWindow.document.title || "");
+        } catch {
+          // cross-origin frame
+        }
+
+        frames.push({
+          frameId: framePath,
+          url,
+          ...(title.length > 0 ? { name: title } : {}),
+          isMainFrame: framePath === "frame:0",
+          depth
+        });
+
+        let childCount = 0;
+        try {
+          childCount = currentWindow.frames.length;
+        } catch {
+          childCount = 0;
+        }
+
+        for (let index = 0; index < childCount; index += 1) {
+          try {
+            walk(currentWindow.frames[index], `${framePath}.${index}`, depth + 1);
+          } catch {
+            frames.push({
+              frameId: `${framePath}.${index}`,
+              url: "",
+              isMainFrame: false,
+              depth: depth + 1,
+              crossOrigin: true
+            });
+          }
+        }
+      };
+
+      walk(window, "frame:0", 0);
+      return {
+        frames
+      };
+    },
+    []
+  );
+
+  if (result !== null && typeof result === "object") {
+    return result;
+  }
+
+  return {
+    frames: []
+  };
+}
+
+async function handleTabFrameSnapshot(params) {
+  const tabId = requireTabId(params?.tabId);
+  const frameId = requireNonEmptyString(params?.frameId, "frameId");
+  await ensureDebuggerAttached(tabId);
+  const result = await executeInTab(
+    tabId,
+    (frameIdValue) => {
+      const normalized = String(frameIdValue || "");
+      const match = /^frame:(\d+(?:\.\d+)*)$/.exec(normalized);
+      if (match === null) {
+        return {
+          frameId: normalized,
+          found: false
+        };
+      }
+
+      const indexPath = match[1]
+        .split(".")
+        .map((segment) => Number.parseInt(segment, 10))
+        .filter((segment) => Number.isFinite(segment));
+      if (indexPath.length === 0 || indexPath[0] !== 0) {
+        return {
+          frameId: normalized,
+          found: false
+        };
+      }
+
+      let currentWindow = window;
+      for (let pointer = 1; pointer < indexPath.length; pointer += 1) {
+        const childIndex = indexPath[pointer];
+        if (!Number.isFinite(childIndex) || childIndex < 0 || childIndex >= currentWindow.frames.length) {
+          return {
+            frameId: normalized,
+            found: false
+          };
+        }
+
+        currentWindow = currentWindow.frames[childIndex];
+      }
+
+      try {
+        const doc = currentWindow.document;
+        return {
+          frameId: normalized,
+          found: true,
+          url: String(currentWindow.location.href || ""),
+          ...(String(doc.title || "").length > 0 ? { name: String(doc.title) } : {}),
+          html: doc.documentElement ? doc.documentElement.outerHTML : "",
+          crossOrigin: false
+        };
+      } catch {
+        return {
+          frameId: normalized,
+          found: true,
+          html: "",
+          crossOrigin: true
+        };
+      }
+    },
+    [frameId]
+  );
+
+  if (result !== null && typeof result === "object") {
+    return result;
+  }
+
+  return {
+    frameId,
+    found: false
+  };
+}
+
+async function handleTabAct(params) {
+  const tabId = requireTabId(params?.tabId);
+  const debuggerReady = await ensureDebuggerAttached(tabId);
+  const action = params?.action;
+  const actionType = normalizeString(action?.type);
+
+  if (actionType === "setFiles") {
+    if (!debuggerReady) {
+      throw new Error(
+        `Unable to attach debugger for tab ${tabId}. Close DevTools/other debugger and retry file upload.`
+      );
+    }
+
+    const payload = action?.payload !== null && typeof action?.payload === "object" ? action.payload : {};
+    const selector = requireNonEmptyString(payload?.selector, "selector");
+    const files = Array.isArray(payload?.files)
+      ? payload.files
+          .map((file) => normalizeString(file))
+          .filter((file) => file.length > 0)
+      : [];
+    if (files.length === 0) {
+      throw new Error("files must contain at least one file path.");
+    }
+
+    const evaluateResult = await chrome.debugger.sendCommand(
+      { tabId },
+      "Runtime.evaluate",
+      {
+        expression: `document.querySelector(${JSON.stringify(selector)})`,
+        objectGroup: "browserctl-upload",
+        includeCommandLineAPI: false,
+        silent: true
+      }
+    );
+    const objectId = evaluateResult?.result?.objectId;
+    if (typeof objectId !== "string" || objectId.length === 0) {
+      throw new Error(`Element not found for file upload selector: ${selector}`);
+    }
+
+    let nodeId;
+    try {
+      const nodeResult = await chrome.debugger.sendCommand(
+        { tabId },
+        "DOM.requestNode",
+        { objectId }
+      );
+      nodeId = nodeResult?.nodeId;
+    } finally {
+      try {
+        await chrome.debugger.sendCommand(
+          { tabId },
+          "Runtime.releaseObject",
+          { objectId }
+        );
+      } catch {
+        // Ignore release errors.
+      }
+    }
+
+    if (typeof nodeId !== "number") {
+      throw new Error(`Unable to resolve DOM node for selector: ${selector}`);
+    }
+
+    await chrome.debugger.sendCommand(
+      { tabId },
+      "DOM.setFileInputFiles",
+      {
+        nodeId,
+        files
+      }
+    );
+
+    return { executed: true };
+  }
+
+  const result = await executeInTab(
+    tabId,
+    (actionPayload) => {
+      if (actionPayload === null || typeof actionPayload !== "object") {
+        throw new Error("action must be an object.");
+      }
+
+      const type =
+        typeof actionPayload.type === "string" && actionPayload.type.trim().length > 0
+          ? actionPayload.type.trim()
+          : "";
+      if (type.length === 0) {
+        throw new Error("action.type must be a non-empty string.");
+      }
+
+      const payload =
+        actionPayload.payload !== null && typeof actionPayload.payload === "object"
+          ? actionPayload.payload
+          : {};
+      const selector =
+        typeof payload.selector === "string" && payload.selector.trim().length > 0
+          ? payload.selector.trim()
+          : "";
+
+      const resolveElement = () => {
+        if (selector.length === 0) {
+          throw new Error("selector is required.");
+        }
+
+        const element = document.querySelector(selector);
+        if (element === null) {
+          throw new Error(`Element not found: ${selector}`);
+        }
+        return element;
+      };
+
+      if (type === "click") {
+        const element = resolveElement();
+        if (typeof element.click === "function") {
+          element.click();
+        }
+        return { executed: true };
+      }
+
+      if (type === "fill") {
+        const element = resolveElement();
+        const value = typeof payload.value === "string" ? payload.value : "";
+        if ("value" in element) {
+          element.value = value;
+          element.dispatchEvent(new Event("input", { bubbles: true }));
+          element.dispatchEvent(new Event("change", { bubbles: true }));
+        }
+        return { executed: true };
+      }
+
+      if (type === "type") {
+        const element = resolveElement();
+        const text = typeof payload.text === "string" ? payload.text : "";
+        if ("value" in element) {
+          const previousValue = typeof element.value === "string" ? element.value : "";
+          element.value = `${previousValue}${text}`;
+          element.dispatchEvent(new Event("input", { bubbles: true }));
+          element.dispatchEvent(new Event("change", { bubbles: true }));
+        }
+        return { executed: true };
+      }
+
+      if (type === "press") {
+        const key =
+          typeof payload.key === "string" && payload.key.trim().length > 0
+            ? payload.key.trim()
+            : "Enter";
+        const target = document.activeElement ?? document.body;
+        target.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true }));
+        target.dispatchEvent(new KeyboardEvent("keyup", { key, bubbles: true }));
+        return { executed: true };
+      }
+
+      if (type === "scroll") {
+        const deltaX =
+          typeof payload.deltaX === "number" && Number.isFinite(payload.deltaX)
+            ? payload.deltaX
+            : 0;
+        const deltaY =
+          typeof payload.deltaY === "number" && Number.isFinite(payload.deltaY)
+            ? payload.deltaY
+            : 900;
+        window.scrollBy({
+          left: deltaX,
+          top: deltaY
+        });
+        return {
+          executed: true,
+          deltaX,
+          deltaY,
+          scrollX: window.scrollX,
+          scrollY: window.scrollY
+        };
+      }
+
+      return {
+        executed: false
+      };
+    },
+    [action]
+  );
+
+  if (result !== null && typeof result === "object") {
+    return result;
+  }
+
+  return {
+    executed: false
+  };
+}
+
+async function dispatchBridgeRequest(method, params) {
+  switch (method) {
+    case "tab.open":
+      return await handleTabOpen(params);
+    case "tab.goto":
+      return await handleTabGoto(params);
+    case "tab.focus":
+      return await handleTabFocus(params);
+    case "tab.close":
+      return await handleTabClose(params);
+    case "tab.info":
+      return await handleTabInfo(params);
+    case "tab.snapshot":
+      return await handleTabSnapshot(params);
+    case "tab.dom.query":
+      return await handleTabDomQuery(params);
+    case "tab.dom.queryAll":
+      return await handleTabDomQueryAll(params);
+    case "tab.screenshot":
+      return await handleTabScreenshot(params);
+    case "tab.element.screenshot":
+      return await handleTabElementScreenshot(params);
+    case "tab.a11y.snapshot":
+      return await handleTabA11ySnapshot(params);
+    case "tab.cookie.get":
+      return await handleTabCookieGet(params);
+    case "tab.cookie.set":
+      return await handleTabCookieSet(params);
+    case "tab.cookie.clear":
+      return await handleTabCookieClear(params);
+    case "tab.storage.get":
+      return await handleTabStorageGet(params);
+    case "tab.storage.set":
+      return await handleTabStorageSet(params);
+    case "tab.frame.list":
+      return await handleTabFrameList(params);
+    case "tab.frame.snapshot":
+      return await handleTabFrameSnapshot(params);
+    case "tab.act":
+      return await handleTabAct(params);
+    default:
+      throw new Error(`Unsupported method: ${method}`);
+  }
+}
+
+async function handleSocketMessage(rawMessage) {
+  let parsedMessage;
+  try {
+    parsedMessage = JSON.parse(String(rawMessage));
+  } catch {
+    return;
+  }
+
+  if (parsedMessage === null || typeof parsedMessage !== "object") {
+    return;
+  }
+
+  if (parsedMessage.type !== "request") {
+    return;
+  }
+
+  const requestId = normalizeString(parsedMessage.id);
+  const method = normalizeString(parsedMessage.method);
+  if (requestId.length === 0 || method.length === 0) {
+    return;
+  }
+
+  try {
+    const result = await dispatchBridgeRequest(method, parsedMessage.params);
+    sendSocketEnvelope({
+      type: "response",
+      id: requestId,
+      ok: true,
+      result
+    });
+  } catch (error) {
+    sendSocketEnvelope({
+      type: "response",
+      id: requestId,
+      ok: false,
+      error: {
+        message: toErrorMessage(error)
+      }
+    });
+  }
+}
+
+async function connectToBridge(forceReconnect) {
+  if (connectInFlight) {
+    return;
+  }
+
+  if (
+    !forceReconnect &&
+    socket !== null &&
+    (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)
+  ) {
+    return;
+  }
+
+  connectInFlight = true;
+  clearReconnectTimer();
+
+  try {
+    const config = await readConfig();
+    const socketUrl = buildSocketUrl(config);
+
+    if (socket !== null) {
+      try {
+        socket.close(1000, "Reconnect requested.");
+      } catch {
+        // Ignore close errors while reconnecting.
+      }
+      socket = null;
+    }
+
+    const ws = new WebSocket(socketUrl);
+    socket = ws;
+    runtimeState.bridgeUrl = config.bridgeUrl;
+    runtimeState.token = config.token;
+
+    ws.onopen = () => {
+      runtimeState.connected = true;
+      runtimeState.lastError = "";
+      runtimeState.lastConnectedAt = new Date().toISOString();
+      connectInFlight = false;
+      sendHello();
+    };
+
+    ws.onmessage = (event) => {
+      void handleSocketMessage(event.data);
+    };
+
+    ws.onerror = () => {
+      runtimeState.lastError = "WebSocket connection error.";
+    };
+
+    ws.onclose = (event) => {
+      if (socket === ws) {
+        socket = null;
+      }
+      connectInFlight = false;
+      setDisconnectedState(`WebSocket closed (${event.code}).`);
+      scheduleReconnect();
+    };
+  } catch (error) {
+    connectInFlight = false;
+    setDisconnectedState(toErrorMessage(error));
+    scheduleReconnect();
+  }
+}
+
+function getStatusPayload() {
+  return {
+    connected: runtimeState.connected,
+    bridgeUrl: runtimeState.bridgeUrl,
+    tokenConfigured: runtimeState.token.length > 0,
+    lastConnectedAt: runtimeState.lastConnectedAt,
+    lastError: runtimeState.lastError,
+    debuggerAttachedTabs: attachedDebuggerTabs.size
+  };
+}
+
+function registerRuntimeMessageHandlers() {
+  chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
+    const requestType = normalizeString(request?.type);
+
+    if (requestType === "relay.getStatus") {
+      sendResponse({
+        ok: true,
+        status: getStatusPayload()
+      });
+      return;
+    }
+
+    if (requestType === "relay.getConfig") {
+      void (async () => {
+        const config = await readConfig();
+        sendResponse({
+          ok: true,
+          config
+        });
+      })();
+      return true;
+    }
+
+    if (requestType === "relay.saveConfig") {
+      void (async () => {
+        try {
+          const config = await writeConfig(request?.config ?? {});
+          await connectToBridge(true);
+          sendResponse({
+            ok: true,
+            config,
+            status: getStatusPayload()
+          });
+        } catch (error) {
+          sendResponse({
+            ok: false,
+            error: toErrorMessage(error)
+          });
+        }
+      })();
+      return true;
+    }
+
+    if (requestType === "relay.reconnect") {
+      void (async () => {
+        try {
+          await connectToBridge(true);
+          sendResponse({
+            ok: true,
+            status: getStatusPayload()
+          });
+        } catch (error) {
+          sendResponse({
+            ok: false,
+            error: toErrorMessage(error)
+          });
+        }
+      })();
+      return true;
+    }
+
+    if (requestType === "relay.event") {
+      const tabId =
+        typeof request?.tabId === "number"
+          ? request.tabId
+          : typeof sender?.tab?.id === "number"
+            ? sender.tab.id
+            : undefined;
+      if (typeof tabId === "number" && request?.event !== undefined) {
+        sendBridgeEvent({
+          ...request.event,
+          tabId
+        });
+      }
+
+      sendResponse({
+        ok: true
+      });
+      return;
+    }
+
+    return undefined;
+  });
+}
+
+chrome.runtime.onInstalled.addListener(() => {
+  void connectToBridge(true);
+});
+
+chrome.runtime.onStartup.addListener(() => {
+  void connectToBridge(false);
+});
+
+registerRuntimeMessageHandlers();
+registerDebuggerTelemetryHandlers();
+void connectToBridge(false);