@flrande/browserctl 0.5.0 → 0.6.0

package/extensions/chrome-relay/background.js

@@ -1,1687 +0,0 @@
-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);