@browserbridge/bbx 1.0.1 → 1.2.0

package/docs/usage-scenarios.md

@@ -1,136 +0,0 @@
-# Usage Scenarios
-
-Browser Bridge is best when you need the state that already exists in a real Chrome tab: logged-in sessions, seeded storage, feature flags, SPA state, and whatever the page actually rendered.
-
-If you need repeatable clean-room automation for tests or CI, use Playwright or another browser automation stack instead.
-
-## 1. Debug a broken layout in the real page
-
-Use this when the bug only reproduces in your current logged-in or feature-flag state.
-
-Ask an MCP-capable agent:
-
-> Use Browser Bridge MCP to inspect why the sidebar overlaps the main content.
->
-> If your client supports subagents, delegate the investigation to a smaller low-cost worker first.
-
-Ask a CLI-skill agent:
-
-> Use the browser-bridge skill to inspect the broken sidebar layout and tell me which computed styles are causing it.
-
-Useful direct commands:
-
-```bash
-bbx batch '[{"method":"page.get_state"},{"method":"dom.query","params":{"selector":".sidebar","maxNodes":20,"maxDepth":4,"textBudget":600}}]'
-bbx dom-query .sidebar
-bbx box .sidebar
-bbx styles .sidebar display,position,width,left,right,gap
-bbx matched-rules .sidebar
-```
-
-## 2. Verify that a local code change actually rendered
-
-Use this after editing source, before assuming the fix worked.
-
-Typical prompt:
-
-> Check whether the latest navbar change rendered correctly in the browser, and compare the live spacing against the intended layout.
-
-Useful direct commands:
-
-```bash
-bbx call page.get_state
-bbx dom-query nav
-bbx styles nav gap,padding,align-items
-bbx call input.scroll_into_view '{"target":{"selector":"nav"}}'
-bbx screenshot nav ./tmp/navbar.png
-```
-
-## 3. Debug a form or interaction issue
-
-Use this when a click, keyboard interaction, or form control does not behave as expected.
-
-Typical prompt:
-
-> Use Browser Bridge to inspect the submit button, confirm whether it is disabled or covered, then try the interaction again.
-
-Useful direct commands:
-
-```bash
-bbx describe button[type="submit"]
-bbx box button[type="submit"]
-bbx call input.scroll_into_view '{"target":{"selector":"button[type=\"submit\"]"}}'
-bbx click button[type="submit"]
-bbx console error
-bbx network 20
-```
-
-## 4. Prove a live CSS or DOM fix before editing source
-
-Use this when you want to validate the fix in the page first, then port it into
-the codebase.
-
-Typical prompt:
-
-> Inspect the hero spacing, patch the live page until it looks correct, then tell me the minimal source change to make.
-
-Useful direct commands:
-
-```bash
-bbx patch-style .hero gap=24px padding=32px
-bbx patch-text .hero-title "New heading"
-bbx patches
-bbx rollback <patchId>
-```
-
-## 5. Collect compact evidence instead of taking full screenshots
-
-Use this when you want token-efficient evidence for the agent.
-
-Typical prompt:
-
-> Read the visible page state, console errors, and the box model for the checkout summary without dumping the whole DOM.
-
-Useful direct commands:
-
-```bash
-bbx call page.get_state
-bbx console all
-bbx network 20
-bbx box .checkout-summary
-bbx text .checkout-summary medium
-```
-
-If `page.get_console` or `page.get_network` returns `dropped`, the page was
-noisy enough to evict older buffered entries. Narrow the repro and re-run the
-read before assuming you saw the full history.
-
-## 6. Capture the whole document only when the page-level layout is the issue
-
-Use this when a bug spans multiple viewports and tight crops cannot express the
-problem.
-
-Typical prompt:
-
-> Capture the full page so we can verify how the header, hero, and footer line up across the whole document.
-
-Useful direct commands:
-
-```bash
-bbx call input.scroll_into_view '{"target":{"selector":"main"}}'
-bbx call screenshot.capture_full_page '{}'
-```
-
-## 7. Drop to the raw protocol when shortcuts are not enough
-
-Use this when you need a method or parameter that the higher-level commands do
-not expose.
-
-```bash
-bbx call page.get_state
-bbx call dom.query '{"selector":".card","maxNodes":10}'
-bbx batch '[{"method":"page.get_state"},{"method":"page.get_console","params":{"level":"error"}}]'
-```
-
-For a command-oriented walkthrough, see [cli-guide.md](./cli-guide.md). For
-integration choices, see [mcp-vs-cli.md](./mcp-vs-cli.md).

package/manifest.json

@@ -1,38 +0,0 @@
-{
-  "manifest_version": 3,
-  "minimum_chrome_version": "114",
-  "name": "Browser Bridge",
-  "version": "1.0.0",
-  "description": "Local bridge between your coding agent and browser. Structured access to DOM, styles, console, network, and reversible patches.",
-  "icons": {
-    "16": "packages/extension/assets/icon-16.png",
-    "32": "packages/extension/assets/icon-32.png",
-    "48": "packages/extension/assets/icon-48.png",
-    "128": "packages/extension/assets/icon-128.png"
-  },
-  "permissions": [
-    "alarms",
-    "debugger",
-    "nativeMessaging",
-    "scripting",
-    "sidePanel",
-    "storage",
-    "tabs"
-  ],
-  "host_permissions": ["<all_urls>"],
-  "background": {
-    "service_worker": "packages/extension/src/background.js",
-    "type": "module"
-  },
-  "action": {
-    "default_title": "Browser Bridge",
-    "default_popup": "packages/extension/ui/popup.html",
-    "default_icon": {
-      "16": "packages/extension/assets/icon-16.png",
-      "32": "packages/extension/assets/icon-32.png"
-    }
-  },
-  "side_panel": {
-    "default_path": "packages/extension/ui/sidepanel.html"
-  }
-}

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

@@ -1,474 +0,0 @@
-// @ts-check
-
-import {
-  ERROR_CODES,
-  estimateJsonPayloadCost,
-  getMethodCapability,
-  getCostClass,
-  getUtf8ByteLength,
-  isDebuggerBackedMethod,
-} from '../../protocol/src/index.js';
-
-/** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
-/** @typedef {import('../../protocol/src/types.js').Capability} Capability */
-/** @typedef {import('../../protocol/src/types.js').ErrorCode} ErrorCode */
-
-const INTERACTIVE_AX_ROLES = new Set([
-  'button',
-  'link',
-  'textbox',
-  'checkbox',
-  'radio',
-  'combobox',
-  'listbox',
-  'menuitem',
-  'tab',
-  'switch',
-  'slider',
-  'spinbutton',
-  'searchbox',
-  'menuitemcheckbox',
-  'menuitemradio',
-  'option',
-]);
-
-/**
- * @param {chrome.tabs.Tab} tab
- * @param {string} method
- * @returns {{ method: string, tabId: number | null, windowId: number | null, url: string, title: string, status: string }}
- */
-export function summarizeTabResult(tab, method) {
-  return {
-    method,
-    tabId: typeof tab.id === 'number' ? tab.id : null,
-    windowId: typeof tab.windowId === 'number' ? tab.windowId : null,
-    url: tab.url ?? '',
-    title: tab.title ?? '',
-    status: tab.status ?? 'unknown',
-  };
-}
-
-/**
- * @param {unknown} prop
- * @returns {string}
- */
-export function axValue(prop) {
-  if (!prop || typeof prop !== 'object') return '';
-  const val = /** @type {{ value?: unknown }} */ (prop).value;
-  return typeof val === 'string' ? val : '';
-}
-
-/**
- * @param {unknown} prop
- * @returns {boolean}
- */
-export function axBool(prop) {
-  if (!prop || typeof prop !== 'object') return false;
-  return /** @type {{ value?: unknown }} */ (prop).value === true;
-}
-
-/**
- * @param {unknown} prop
- * @returns {string | null}
- */
-export function axTristateValue(prop) {
-  if (!prop || typeof prop !== 'object') return null;
-  const val = /** @type {{ value?: unknown }} */ (prop).value;
-  if (val === 'true' || val === true) return 'true';
-  if (val === 'false' || val === false) return 'false';
-  if (val === 'mixed') return 'mixed';
-  return null;
-}
-
-/**
- * @param {Record<string, unknown>} node
- * @returns {{ nodeId: string, role: string, name: string, description: string, value: string, focused: boolean, required: boolean, checked: string | null, disabled: boolean, interactive: boolean, childIds: string[] }}
- */
-export function simplifyAXNode(node) {
-  const role = axValue(node.role);
-  return {
-    nodeId: String(node.nodeId ?? ''),
-    role,
-    name: axValue(node.name),
-    description: axValue(node.description),
-    value: axValue(node.value),
-    focused: axBool(node.focused),
-    required: axBool(node.required),
-    checked: axTristateValue(node.checked),
-    disabled: axBool(node.disabled),
-    interactive: INTERACTIVE_AX_ROLES.has(role) || axBool(node.focusable),
-    childIds: Array.isArray(node.childIds) ? node.childIds.map(String) : [],
-  };
-}
-
-/**
- * @param {string} method
- * @returns {boolean}
- */
-export function shouldLogAction(method) {
-  return ![
-    'health.ping',
-    'log.tail',
-    'skill.get_runtime_context',
-    'setup.get_status',
-    'setup.install',
-    'tabs.list',
-  ].includes(method);
-}
-
-/**
- * Treat page exceptions as part of the error stream so filtered reads return
- * runtime failures alongside explicit `console.error` calls.
- *
- * @param {string} requestedLevel
- * @param {string} entryLevel
- * @returns {boolean}
- */
-export function matchesConsoleLevel(requestedLevel, entryLevel) {
-  if (requestedLevel === entryLevel) {
-    return true;
-  }
-  if (requestedLevel === 'error') {
-    return entryLevel === 'exception' || entryLevel === 'rejection';
-  }
-  return false;
-}
-
-/**
- * @param {BridgeResponse} response
- * @returns {string}
- */
-export function summarizeActionResult(response) {
-  if (!response.ok) {
-    return response.error.message;
-  }
-
-  const result =
-    response.result && typeof response.result === 'object'
-      ? /** @type {Record<string, unknown>} */ (response.result)
-      : {};
-
-  if (typeof result.patchId === 'string') {
-    return `Patch ${result.patchId} applied.`;
-  }
-
-  if (Array.isArray(result.nodes)) {
-    return `${result.nodes.length} node(s) returned.`;
-  }
-
-  if (typeof result.image === 'string') {
-    return 'Partial screenshot captured.';
-  }
-
-  return 'Completed successfully.';
-}
-
-/**
- * Estimate approximate token cost from a bridge response.
- *
- * @param {BridgeResponse} response
- * @returns {{
- *   responseBytes: number,
- *   approxTokens: number,
- *   textBytes: number,
- *   textApproxTokens: number,
- *   imageApproxTokens: number,
- *   imageBytes: number,
- *   hasScreenshot: boolean,
- *   nodeCount: number | null
- * }}
- */
-export function estimateResponseTokens(response) {
-  const payload = response.ok ? response.result : { error: response.error };
-  const estimate = estimateJsonPayloadCost(payload);
-  const responseBytes = estimate.bytes;
-  const result =
-    response.ok && response.result && typeof response.result === 'object'
-      ? /** @type {Record<string, unknown>} */ (response.result)
-      : null;
-  const hasScreenshot = result != null && typeof result.image === 'string';
-  const nodeCount = result != null && Array.isArray(result.nodes) ? result.nodes.length : null;
-  const textPayload = hasScreenshot && result != null ? omitScreenshotImage(result) : payload;
-  const textEstimate = estimateJsonPayloadCost(textPayload);
-  const imageTransportBytes = Math.max(0, responseBytes - textEstimate.bytes);
-  const imageBytes = hasScreenshot && result != null ? estimateInlineImageBytes(result.image) : 0;
-
-  return {
-    responseBytes,
-    approxTokens: estimate.approxTokens,
-    textBytes: textEstimate.bytes,
-    textApproxTokens: textEstimate.approxTokens,
-    imageApproxTokens: imageTransportBytes === 0 ? 0 : Math.ceil(imageTransportBytes / 4),
-    imageBytes,
-    hasScreenshot,
-    nodeCount,
-  };
-}
-
-/**
- * @param {string} method
- * @param {BridgeResponse} response
- * @returns {{
- *   responseBytes: number,
- *   approxTokens: number,
- *   textBytes: number,
- *   textApproxTokens: number,
- *   imageApproxTokens: number,
- *   imageBytes: number,
- *   hasScreenshot: boolean,
- *   nodeCount: number | null,
- *   costClass: 'cheap' | 'moderate' | 'heavy' | 'extreme',
- *   textCostClass: 'cheap' | 'moderate' | 'heavy' | 'extreme',
- *   debuggerBacked: boolean
- * }}
- */
-export function getResponseDiagnostics(method, response) {
-  const estimate = estimateResponseTokens(response);
-  return {
-    ...estimate,
-    costClass: getCostClass(estimate.approxTokens),
-    textCostClass: getCostClass(estimate.textApproxTokens),
-    debuggerBacked: isDebuggerBackedMethod(method),
-  };
-}
-
-/**
- * Keep screenshot metadata while excluding the large inline image payload from
- * token-oriented UI estimates.
- *
- * @param {Record<string, unknown>} result
- * @returns {Record<string, unknown>}
- */
-function omitScreenshotImage(result) {
-  const textPayload = { ...result };
-  delete textPayload.image;
-  return textPayload;
-}
-
-/**
- * Estimate decoded image bytes for data URLs so the UI can show image size
- * without pretending the base64 blob is text-token traffic.
- *
- * @param {unknown} image
- * @returns {number}
- */
-function estimateInlineImageBytes(image) {
-  if (typeof image !== 'string' || image.length === 0) {
-    return 0;
-  }
-
-  const match = /^data:[^;]+;base64,([A-Za-z0-9+/=\s]+)$/u.exec(image);
-  if (!match) {
-    return getUtf8ByteLength(image);
-  }
-
-  const base64 = match[1].replace(/\s+/gu, '');
-  if (base64.length === 0) {
-    return 0;
-  }
-
-  const padding = base64.endsWith('==') ? 2 : base64.endsWith('=') ? 1 : 0;
-  return Math.max(0, Math.floor((base64.length * 3) / 4) - padding);
-}
-
-/**
- * Deterministically trim oversized success payloads to fit within an
- * approximate token budget. This prefers shrinking large strings and slicing
- * top-level result arrays before falling back to a compact continuation payload.
- *
- * @param {string} method
- * @param {BridgeResponse} response
- * @param {number | null | undefined} tokenBudget
- * @returns {BridgeResponse}
- */
-export function enforceTokenBudget(method, response, tokenBudget) {
-  if (
-    !response.ok ||
-    typeof tokenBudget !== 'number' ||
-    !Number.isFinite(tokenBudget) ||
-    tokenBudget <= 0
-  ) {
-    return response;
-  }
-
-  const maxBytes = Math.max(128, Math.floor(tokenBudget * 4));
-  const responseBytes = estimateJsonPayloadCost(response.result).bytes;
-  if (responseBytes <= maxBytes) {
-    return {
-      ...response,
-      meta: {
-        ...response.meta,
-        budget_applied: false,
-        budget_truncated: false,
-        continuation_hint: null,
-      },
-    };
-  }
-
-  const cloned = cloneJsonValue(response.result);
-  let truncated = false;
-  let iterations = 0;
-  const MAX_BUDGET_ITERATIONS = 100;
-  while (
-    estimateJsonPayloadCost(cloned).bytes > maxBytes &&
-    shrinkForBudget(cloned) &&
-    iterations < MAX_BUDGET_ITERATIONS
-  ) {
-    truncated = true;
-    iterations += 1;
-  }
-
-  let result = cloned;
-  if (estimateJsonPayloadCost(result).bytes > maxBytes) {
-    result = {
-      truncated: true,
-      continuationHint: `Retry ${method} with a larger token budget or tighter params.`,
-    };
-    truncated = true;
-  }
-
-  return {
-    ...response,
-    result,
-    meta: {
-      ...response.meta,
-      budget_applied: true,
-      budget_truncated: truncated,
-      continuation_hint: truncated
-        ? `Retry ${method} with a larger token budget or tighter params.`
-        : null,
-    },
-  };
-}
-
-/**
- * @param {unknown} value
- * @returns {any}
- */
-function cloneJsonValue(value) {
-  return value == null ? value : JSON.parse(JSON.stringify(value));
-}
-
-/**
- * @param {any} value
- * @returns {boolean}
- */
-function shrinkForBudget(value) {
-  if (!value || typeof value !== 'object') {
-    return false;
-  }
-
-  if (Array.isArray(value)) {
-    if (value.length > 1) {
-      const nextLength = Math.max(1, Math.floor(value.length * 0.75));
-      value.splice(nextLength);
-      return true;
-    }
-    return value.length === 1 ? shrinkForBudget(value[0]) : false;
-  }
-
-  for (const key of ['image', 'html', 'text', 'value']) {
-    if (typeof value[key] === 'string' && value[key].length > 64) {
-      value[key] =
-        key === 'image'
-          ? '[omitted image over token budget]'
-          : `${value[key].slice(0, Math.max(32, Math.floor(value[key].length * 0.75) - 1))}\u2026`;
-      if (typeof value.truncated !== 'boolean') {
-        value.truncated = true;
-      }
-      return true;
-    }
-  }
-
-  for (const key of ['nodes', 'entries', 'tabs', 'patches']) {
-    if (Array.isArray(value[key]) && value[key].length > 1) {
-      const originalLength = value[key].length;
-      const nextLength = Math.max(1, Math.floor(originalLength * 0.75));
-      value[key].splice(nextLength);
-      if (typeof value.count !== 'number') {
-        value.count = originalLength;
-      }
-      if (typeof value.total !== 'number') {
-        value.total = originalLength;
-      }
-      value.truncated = true;
-      return true;
-    }
-  }
-
-  for (const entry of Object.values(value)) {
-    if (shrinkForBudget(entry)) {
-      if (typeof value.truncated !== 'boolean') {
-        value.truncated = true;
-      }
-      return true;
-    }
-  }
-
-  const keys = Object.keys(value);
-  if (keys.length > 2) {
-    delete value[keys[keys.length - 1]];
-    value.truncated = true;
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * @param {unknown} error
- * @returns {string}
- */
-export function getErrorMessage(error) {
-  if (typeof error === 'string') {
-    return error;
-  }
-  if (error instanceof Error) {
-    return error.message;
-  }
-  return 'Unexpected extension error.';
-}
-
-/**
- * @param {string} message
- * @returns {string}
- */
-export function normalizeRuntimeErrorMessage(message) {
-  return /^No tab with id[: ]/i.test(message) ? ERROR_CODES.TAB_MISMATCH : message;
-}
-
-/**
- * @param {{ x?: number, y?: number, width?: number, height?: number, scale?: number }} [rect={}]
- * @returns {{ x: number, y: number, width: number, height: number }}
- */
-export function normalizeCropRect(rect = {}) {
-  const scale = Number(rect.scale) || 1;
-  return {
-    x: Math.max(0, Math.round((rect.x || 0) * scale)),
-    y: Math.max(0, Math.round((rect.y || 0) * scale)),
-    width: Math.max(1, Math.round((rect.width || 1) * scale)),
-    height: Math.max(1, Math.round((rect.height || 1) * scale)),
-  };
-}
-
-/**
- * @param {string} url
- * @returns {string}
- */
-export function safeOrigin(url) {
-  try {
-    return new URL(url).origin;
-  } catch {
-    return '';
-  }
-}
-
-/**
- * @param {string} method
- * @returns {Capability | null}
- */
-export function inferCapability(method) {
-  return getMethodCapability(
-    /** @type {import('../../protocol/src/types.js').BridgeMethod} */ (method)
-  );
-}