@browserbridge/bbx 1.0.0 → 1.1.0

package/packages/extension/src/debugger-coordinator.js

@@ -1,188 +0,0 @@
-// @ts-check
-
-/** @typedef {{ tabId: number }} DebuggerTarget */
-/** @typedef {(target: DebuggerTarget, protocolVersion: string) => Promise<void>} DebuggerAttach */
-/** @typedef {(target: DebuggerTarget) => Promise<void>} DebuggerDetach */
-
-/**
- * Serialize Chrome debugger sessions per tab so concurrent bridge requests do
- * not race on `chrome.debugger.attach`.
- */
-export class TabDebuggerCoordinator {
-  /**
-   * @param {{
-   *   attach: DebuggerAttach,
-   *   detach: DebuggerDetach,
-   *   protocolVersion?: string,
-   *   burstIdleMs?: number
-   * }} options
-   */
-  constructor({ attach, detach, protocolVersion = '1.3', burstIdleMs = 5_000 }) {
-    this.attach = attach;
-    this.detach = detach;
-    this.protocolVersion = protocolVersion;
-    this.burstIdleMs = burstIdleMs;
-    /** @type {Map<number, Promise<void>>} */
-    this.pendingByTab = new Map();
-    /** @type {Map<number, number>} */
-    this.holdsByTab = new Map();
-    /** @type {Map<number, ReturnType<typeof setTimeout>>} */
-    this.burstTimers = new Map();
-  }
-
-  /**
-   * Run one serialized operation for a tab.
-   *
-   * @template T
-   * @param {number} tabId
-   * @param {() => Promise<T>} task
-   * @returns {Promise<T>}
-   */
-  async runExclusive(tabId, task) {
-    const previous = this.pendingByTab.get(tabId) ?? Promise.resolve();
-    /** @type {(value?: void | PromiseLike<void>) => void} */
-    let releaseTurn = () => {};
-    const turn = new Promise((resolve) => {
-      releaseTurn = resolve;
-    });
-    const queuedTurn = previous.catch(() => {}).then(() => turn);
-    this.pendingByTab.set(tabId, queuedTurn);
-
-    await previous.catch(() => {});
-
-    try {
-      return await task();
-    } finally {
-      releaseTurn();
-      if (this.pendingByTab.get(tabId) === queuedTurn) {
-        this.pendingByTab.delete(tabId);
-      }
-    }
-  }
-
-  /**
-   * Run one debugger-backed task for a tab once earlier tasks for that tab
-   * have finished.
-   *
-   * @template T
-   * @param {number} tabId
-   * @param {(target: DebuggerTarget) => Promise<T>} task
-   * @returns {Promise<T>}
-   */
-  async run(tabId, task) {
-    return this.runExclusive(tabId, async () => {
-      const target = { tabId };
-      const held = (this.holdsByTab.get(tabId) ?? 0) > 0;
-      const hasBurst = this.burstTimers.has(tabId);
-      /** @type {T | undefined} */
-      let result;
-      /** @type {unknown} */
-      let taskError = null;
-
-      try {
-        if (!held && !hasBurst) {
-          await this.attach(target, this.protocolVersion);
-        }
-        result = await task(target);
-      } catch (error) {
-        taskError = error;
-      }
-
-      // Schedule a burst-idle detach instead of detaching immediately.
-      if (!held) {
-        this._resetBurstTimer(tabId, target);
-      }
-
-      if (taskError) {
-        throw taskError;
-      }
-      return /** @type {T} */ (result);
-    });
-  }
-
-  /**
-   * Reset or start the burst idle timer for a tab. When it fires, detach
-   * the debugger if no explicit hold is active.
-   *
-   * @param {number} tabId
-   * @param {DebuggerTarget} target
-   * @returns {void}
-   */
-  _resetBurstTimer(tabId, target) {
-    const existing = this.burstTimers.get(tabId);
-    if (existing) clearTimeout(existing);
-    const timer = setTimeout(async () => {
-      this.burstTimers.delete(tabId);
-      if ((this.holdsByTab.get(tabId) ?? 0) > 0) return;
-      try {
-        await this.detach(target);
-      } catch {
-        // Already detached or tab closed.
-      }
-    }, this.burstIdleMs);
-    timer.unref?.();
-    this.burstTimers.set(tabId, timer);
-  }
-
-  /**
-   * Attach and keep a debugger session alive across multiple runs for the same
-   * tab. Nested holds are reference-counted.
-   *
-   * @param {number} tabId
-   * @param {(target: DebuggerTarget) => Promise<void>} [initialize]
-   * @returns {Promise<void>}
-   */
-  async acquire(tabId, initialize = async () => {}) {
-    await this.runExclusive(tabId, async () => {
-      const target = { tabId };
-      const holdCount = this.holdsByTab.get(tabId) ?? 0;
-      if (holdCount === 0) {
-        let attached = false;
-        try {
-          await this.attach(target, this.protocolVersion);
-          attached = true;
-          await initialize(target);
-        } catch (error) {
-          if (attached) {
-            await this.detach(target).catch(() => {});
-          }
-          throw error;
-        }
-      }
-      this.holdsByTab.set(tabId, holdCount + 1);
-    });
-  }
-
-  /**
-   * Release one persistent debugger hold for a tab.
-   *
-   * @param {number} tabId
-   * @param {(target: DebuggerTarget) => Promise<void>} [cleanup]
-   * @returns {Promise<void>}
-   */
-  async release(tabId, cleanup = async () => {}) {
-    await this.runExclusive(tabId, async () => {
-      const target = { tabId };
-      const holdCount = this.holdsByTab.get(tabId) ?? 0;
-      if (holdCount === 0) {
-        return;
-      }
-      if (holdCount > 1) {
-        this.holdsByTab.set(tabId, holdCount - 1);
-        return;
-      }
-
-      this.holdsByTab.delete(tabId);
-      let cleanupError = null;
-      try {
-        await cleanup(target);
-      } catch (error) {
-        cleanupError = error;
-      }
-      await this.detach(target);
-      if (cleanupError) {
-        throw cleanupError;
-      }
-    });
-  }
-}

package/packages/extension/src/sidepanel-helpers.js

@@ -1,102 +0,0 @@
-// @ts-check
-
-/**
- * @typedef {{
- *   configured: boolean
- * }} McpClientInstallState
- */
-
-/**
- * @typedef {{
- *   exists: boolean
- * }} SkillInstallState
- */
-
-/**
- * @typedef {{
- *   skills: SkillInstallState[]
- * }} SkillTargetInstallState
- */
-
-/**
- * @typedef {{
- *   mcpClients: McpClientInstallState[],
- *   skillTargets: SkillTargetInstallState[]
- * }} SetupStatusInstallState
- */
-
-/**
- * @param {SetupStatusInstallState} setupStatus
- * @returns {{ hasConfiguredMcp: boolean, hasInstalledCliSkill: boolean }}
- */
-function getSetupInstallState(setupStatus) {
-  const hasConfiguredMcp = setupStatus.mcpClients.some((client) => client.configured);
-  const hasInstalledCliSkill = setupStatus.skillTargets.some((target) => target.skills.some((skill) => skill.exists));
-  return { hasConfiguredMcp, hasInstalledCliSkill };
-}
-
-/**
- * Auto-expand Host Setup when the panel opens into a completely unconfigured
- * machine: no MCP clients configured and no CLI skill present anywhere.
- *
- * @param {SetupStatusInstallState | null} setupStatus
- * @returns {boolean}
- */
-export function shouldAutoExpandHostSetup(setupStatus) {
-  if (!setupStatus) {
-    return false;
-  }
-
-  const { hasConfiguredMcp, hasInstalledCliSkill } = getSetupInstallState(setupStatus);
-  if (hasConfiguredMcp) {
-    return false;
-  }
-  return !hasInstalledCliSkill;
-}
-
-/**
- * Pick which prompt-example set to show in the side panel.
- *
- * - `mcp`: MCP is installed, CLI skill is not.
- * - `cli`: CLI skill is installed, MCP is not.
- * - `grouped`: neither is installed, or both are installed.
- *
- * @param {SetupStatusInstallState | null} setupStatus
- * @returns {'mcp' | 'cli' | 'grouped'}
- */
-export function getPromptExamplesMode(setupStatus) {
-  if (!setupStatus) {
-    return 'grouped';
-  }
-
-  const { hasConfiguredMcp, hasInstalledCliSkill } = getSetupInstallState(setupStatus);
-  if (hasConfiguredMcp && !hasInstalledCliSkill) {
-    return 'mcp';
-  }
-  if (hasInstalledCliSkill && !hasConfiguredMcp) {
-    return 'cli';
-  }
-  return 'grouped';
-}
-
-/**
- * Pick the activity source tag to display in the side panel. Prefer explicit
- * request metadata, but fall back to setup state when only one host path is
- * configured so older log entries stay understandable.
- *
- * @param {string | null | undefined} source
- * @param {SetupStatusInstallState | null} setupStatus
- * @returns {'' | 'cli' | 'mcp'}
- */
-export function getActivitySourceTag(source, setupStatus) {
-  if (source === 'cli' || source === 'mcp') {
-    return source;
-  }
-
-  const promptMode = getPromptExamplesMode(setupStatus);
-  if (promptMode === 'cli' || promptMode === 'mcp') {
-    return promptMode;
-  }
-
-  return '';
-}

package/packages/extension/ui/offscreen.html

@@ -1,6 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <body>
-    <script type="module" src="./offscreen.js"></script>
-  </body>
-</html>

package/packages/extension/ui/offscreen.js

@@ -1,61 +0,0 @@
-// @ts-check
-
-/**
- * @typedef {{
- *   type?: string,
- *   image?: string,
- *   rect?: { x: number, y: number, width: number, height: number }
- * }} CropMessage
- */
-
-chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
-  if (message?.type !== 'bridge.crop-image') {
-    return false;
-  }
-
-  const typedMessage = /** @type {CropMessage} */ (message);
-  crop(typedMessage.image || '', typedMessage.rect || { x: 0, y: 0, width: 1, height: 1 }).then(sendResponse);
-  return true;
-});
-
-/**
- * @param {string} imageUrl
- * @param {{ x: number, y: number, width: number, height: number }} rect
- * @returns {Promise<string>}
- */
-async function crop(imageUrl, rect) {
-  const response = await fetch(imageUrl);
-  const blob = await response.blob();
-  const bitmap = await createImageBitmap(blob);
-
-  // Clamp crop rect to bitmap bounds to prevent out-of-bounds draws
-  const x = Math.max(0, Math.min(rect.x, bitmap.width - 1));
-  const y = Math.max(0, Math.min(rect.y, bitmap.height - 1));
-  const w = Math.max(1, Math.min(rect.width, bitmap.width - x));
-  const h = Math.max(1, Math.min(rect.height, bitmap.height - y));
-
-  const canvas = new OffscreenCanvas(w, h);
-  const context = canvas.getContext('2d');
-  if (!context) {
-    throw new Error('Failed to create 2D offscreen canvas context.');
-  }
-  context.drawImage(bitmap, x, y, w, h, 0, 0, w, h);
-  bitmap.close();
-  const croppedBlob = await canvas.convertToBlob({ type: 'image/png' });
-  return blobToDataUrl(croppedBlob);
-}
-
-/**
- * @param {Blob} blob
- * @returns {Promise<string>}
- */
-async function blobToDataUrl(blob) {
-  const arrayBuffer = await blob.arrayBuffer();
-  const bytes = new Uint8Array(arrayBuffer);
-  const chunks = [];
-  for (let i = 0; i < bytes.length; i += 8192) {
-    chunks.push(String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + 8192))));
-  }
-  const base64 = btoa(chunks.join(''));
-  return `data:${blob.type};base64,${base64}`;
-}

package/packages/extension/ui/popup.html

@@ -1,35 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Browser Bridge</title>
-    <link rel="stylesheet" href="./ui.css">
-  </head>
-  <body>
-    <main class="panel panel-popup">
-      <header class="panel-header">
-        <h1 class="popup-title">Browser Bridge</h1>
-        <div class="control-links">
-          <a class="setup-link" href="https://github.com/koltyakov/browser-bridge" target="_blank"
-            rel="noopener noreferrer">GitHub ↗</a>
-          <a class="setup-link" href="https://github.com/koltyakov/browser-bridge/blob/main/PRIVACY.md"
-            target="_blank" rel="noopener noreferrer">Privacy policy ↗</a>
-        </div>
-      </header>
-      <section class="card control-card popup-control-card">
-        <div class="control-copy">
-          <div id="popup-access-eyebrow" class="eyebrow">Window access</div>
-          <p id="popup-access-detail" class="control-detail">
-            Enable Browser Bridge to let your connected agent inspect and interact with pages in this Chrome window.
-          </p>
-          <p id="popup-disclosure" class="control-detail control-disclosure">
-            When enabled, Browser Bridge may access page content, styles and layout, console output, network metadata, screenshots, and browser storage when requested.
-          </p>
-        </div>
-        <button id="communication-action" class="popup-action popup-power-button" type="button">Enable Window Access</button>
-      </section>
-    </main>
-    <script type="module" src="./popup.js"></script>
-  </body>
-</html>

package/packages/extension/ui/popup.js

@@ -1,279 +0,0 @@
-// @ts-check
-
-/**
- * @typedef {{
- *   tabId: number,
- *   windowId: number,
- *   title: string,
- *   url: string,
- *   enabled: boolean,
- *   accessRequested: boolean,
- *   restricted: boolean
- * }} PopupCurrentTab
- */
-
-/**
- * @typedef {{
- *   type: 'state.sync',
- *   state: {
- *     nativeConnected: boolean,
- *     currentTab: PopupCurrentTab | null
- *   }
- * }} PopupStateMessage
- */
-
-const nativeIndicator = /** @type {HTMLSpanElement} */ (document.getElementById('native-indicator'));
-const button = /** @type {HTMLButtonElement} */ (document.getElementById('communication-action'));
-const accessEyebrow = /** @type {HTMLDivElement} */ (document.getElementById('popup-access-eyebrow'));
-const accessDetail = /** @type {HTMLParagraphElement} */ (document.getElementById('popup-access-detail'));
-const accessDisclosure = /** @type {HTMLParagraphElement} */ (document.getElementById('popup-disclosure'));
-const controlCard = /** @type {HTMLElement | null} */ (document.querySelector('.popup-control-card'));
-const windowedPopup = isWindowedPopup();
-/** @type {number | null} */
-let popupScopeTabId = null;
-
-/** @param {PopupStateMessage} message */
-function handlePopupMessage(message) {
-  if (message.type === 'state.sync') {
-    renderNativeStatus(message.state.nativeConnected);
-    renderPopupState(message.state.currentTab);
-  }
-}
-
-/** @type {chrome.runtime.Port} */
-let port;
-
-/**
- * @returns {Promise<number | null>}
- */
-async function resolveInitialScopeTabId() {
-  const explicitScopeTabId = readScopedTabId();
-  if (explicitScopeTabId) {
-    return explicitScopeTabId;
-  }
-
-  try {
-    const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });
-    return typeof activeTab?.id === 'number' ? activeTab.id : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @returns {Promise<void>}
- */
-async function connectPopupPort() {
-  popupScopeTabId = await resolveInitialScopeTabId();
-  const nextPort = chrome.runtime.connect({ name: 'ui-popup' });
-  nextPort.onMessage.addListener(handlePopupMessage);
-  nextPort.postMessage({
-    type: 'state.request',
-    ...(popupScopeTabId ? { scopeTabId: popupScopeTabId } : {})
-  });
-  port = nextPort;
-}
-
-void connectPopupPort();
-/** @type {PopupCurrentTab | null} */
-let currentTabState = null;
-/** @type {number | null} */
-let resizeFrameId = null;
-/** @type {ReturnType<typeof setTimeout> | null} */
-let nativeDiagnosticTimer = null;
-const NATIVE_DIAGNOSTIC_DELAY_MS = 10_000;
-const PUBLISHED_EXTENSION_ID = 'jjjkmmcdkpcgamlopogicbnnhdgebhie';
-
-if (windowedPopup) {
-  document.documentElement.dataset.windowed = 'true';
-  document.body.dataset.windowed = 'true';
-  window.addEventListener('load', queueWindowResize);
-}
-
-button.addEventListener('click', () => {
-  if (!currentTabState || button.dataset.pending === 'true') {
-    return;
-  }
-  button.dataset.pending = 'true';
-  button.textContent = currentTabState.enabled ? 'Disabling\u2026' : 'Enabling\u2026';
-  setCommunicationEnabled(!currentTabState.enabled);
-  window.close();
-});
-
-/**
- * @param {PopupCurrentTab | null} currentTab
- * @returns {void}
- */
-function renderPopupState(currentTab) {
-  currentTabState = currentTab;
-
-  if (!currentTab) {
-    accessEyebrow.textContent = 'Window access unavailable';
-    accessDetail.textContent = 'Open a normal web page to manage Browser Bridge for this Chrome window.';
-    accessDisclosure.hidden = false;
-    button.textContent = 'Enable Window Access';
-    button.disabled = true;
-    controlCard?.classList.remove('attention');
-    return;
-  }
-
-  accessDisclosure.hidden = currentTab.enabled;
-
-  if (currentTab.enabled && currentTab.restricted) {
-    accessEyebrow.textContent = 'Window access enabled';
-    accessDetail.textContent = 'This page cannot be interacted with. Switch to a normal web page to use Browser Bridge.';
-    accessDisclosure.hidden = false;
-  } else if (currentTab.enabled) {
-    accessEyebrow.textContent = 'Window access enabled';
-    accessDetail.textContent = 'Your connected agent can inspect and interact with pages in this Chrome window.';
-  } else if (currentTab.accessRequested) {
-    accessEyebrow.textContent = 'Window access requested';
-    accessDetail.textContent = 'An agent requested access for this Chrome window. Enable it to allow page inspection and interaction.';
-  } else {
-    accessEyebrow.textContent = 'Window access';
-    accessDetail.textContent = 'Enable Browser Bridge to let your connected agent inspect and interact with pages in this Chrome window.';
-  }
-
-  button.textContent = currentTab.enabled ? 'Disable Window Access' : 'Enable Window Access';
-  button.disabled = !currentTab.url;
-  controlCard?.classList.toggle('attention', currentTab.accessRequested && !currentTab.enabled);
-  queueWindowResize();
-}
-
-/**
- * @param {boolean} connected
- * @returns {void}
- */
-function renderNativeStatus(connected) {
-  if (!nativeIndicator) return;
-  const label = connected
-    ? 'Native host connected'
-    : 'Native host disconnected';
-  nativeIndicator.dataset.connected = String(connected);
-  nativeIndicator.title = label;
-  nativeIndicator.setAttribute('aria-label', label);
-
-  if (connected) {
-    if (nativeDiagnosticTimer) {
-      clearTimeout(nativeDiagnosticTimer);
-      nativeDiagnosticTimer = null;
-    }
-    hideDiagnostic();
-  } else if (!nativeDiagnosticTimer) {
-    nativeDiagnosticTimer = setTimeout(() => {
-      nativeDiagnosticTimer = null;
-      showDiagnostic(`Native host unreachable. Run: npm install -g @browserbridge/bbx && ${getInstallCommand()}`);
-    }, NATIVE_DIAGNOSTIC_DELAY_MS);
-  }
-}
-
-/**
- * @param {string} message
- * @returns {void}
- */
-function showDiagnostic(message) {
-  let el = document.getElementById('native-diagnostic');
-  if (!el) {
-    el = document.createElement('div');
-    el.id = 'native-diagnostic';
-    el.style.cssText = 'padding:8px 12px;margin:8px 0;background:var(--status-badge-bg,#fef3cd);color:var(--text-primary,#856404);border-radius:6px;font-size:12px;line-height:1.4';
-    const container = document.querySelector('.popup-content') || document.body;
-    container.prepend(el);
-  }
-  el.textContent = message;
-  el.hidden = false;
-  queueWindowResize();
-}
-
-function hideDiagnostic() {
-  const el = document.getElementById('native-diagnostic');
-  if (el) {
-    el.hidden = true;
-    queueWindowResize();
-  }
-}
-
-/**
- * @param {boolean} enabled
- * @returns {void}
- */
-function setCommunicationEnabled(enabled) {
-  const scopedTabId = currentTabState?.tabId ?? popupScopeTabId;
-  port.postMessage({
-    type: 'scope.set_enabled',
-    enabled,
-    ...(scopedTabId ? { tabId: scopedTabId } : {})
-  });
-}
-
-/**
- * @returns {number | null}
- */
-function readScopedTabId() {
-  const value = new URLSearchParams(window.location.search).get('tabId');
-  const tabId = Number(value);
-  return Number.isFinite(tabId) && tabId > 0 ? tabId : null;
-}
-
-/**
- * @returns {boolean}
- */
-function isWindowedPopup() {
-  return new URLSearchParams(window.location.search).get('windowed') === '1';
-}
-
-/**
- * @returns {string}
- */
-function getInstallCommand() {
-  return chrome.runtime.id === PUBLISHED_EXTENSION_ID
-    ? 'bbx install'
-    : `bbx install ${chrome.runtime.id}`;
-}
-
-/**
- * @returns {void}
- */
-function queueWindowResize() {
-  if (!windowedPopup || resizeFrameId != null) {
-    return;
-  }
-  resizeFrameId = window.requestAnimationFrame(() => {
-    resizeFrameId = null;
-    void resizeWindowToContent();
-  });
-}
-
-/**
- * @returns {Promise<void>}
- */
-async function resizeWindowToContent() {
-  if (!windowedPopup) {
-    return;
-  }
-
-  const panel = /** @type {HTMLElement | null} */ (document.querySelector('.panel-popup'));
-  const panelRect = panel?.getBoundingClientRect();
-  const contentWidth = Math.ceil(panelRect?.width ?? document.body.getBoundingClientRect().width);
-  const contentHeight = Math.ceil(panelRect?.height ?? document.body.getBoundingClientRect().height);
-  const frameWidth = Math.max(window.outerWidth - window.innerWidth, 0);
-  const frameHeight = Math.max(window.outerHeight - window.innerHeight, 0);
-  const targetWidth = Math.min(Math.max(contentWidth + frameWidth + 2, 420), 560);
-  const targetHeight = Math.min(Math.max(contentHeight + frameHeight + 2, 180), 520);
-  const currentWindow = await chrome.windows.getCurrent();
-  if (currentWindow.id == null) {
-    return;
-  }
-
-  /** @type {chrome.windows.UpdateInfo} */
-  const updateInfo = {
-    width: targetWidth,
-    height: targetHeight
-  };
-
-  if (typeof currentWindow.left === 'number' && typeof currentWindow.width === 'number') {
-    updateInfo.left = currentWindow.left + currentWindow.width - targetWidth;
-  }
-
-  await chrome.windows.update(currentWindow.id, updateInfo);
-}