@browserbridge/bbx 1.7.8 → 1.8.0

package/packages/agent-client/src/command-registry.js

@@ -30,103 +30,106 @@ function createShortcutCommand(method, usage, build, options = {}) {
   };
 }
 
+/**
+ * Preserve explicit refs and pass selectors directly to methods that support
+ * atomic target resolution.
+ *
+ * @param {string | undefined} value
+ * @returns {{ elementRef: string } | { selector: string }}
+ */
+function createAtomicTarget(value) {
+  if (!value) throw new Error('A ref or selector is required.');
+  return value.startsWith('el_') ? { elementRef: value } : { selector: value };
+}
+
 /** @type {Record<string, ShortcutCommand>} */
 export const SHORTCUT_COMMANDS = {
-  'access-request': createShortcutCommand('access.request', 'bbx access-request', () => ({})),
+  'access-request': createShortcutCommand('access.request', 'bbx access-request [intent]', (r) =>
+    r[0] ? { intent: r[0] } : {}
+  ),
   'dom-query': createShortcutCommand('dom.query', 'bbx dom-query [selector]', (r) => ({
     selector: r[0] || 'body',
   })),
   describe: createShortcutCommand(
     'dom.describe',
     'bbx describe <ref|selector>',
-    (_r, ref) => ({ elementRef: ref }),
-    { resolve: true, printMethod: 'dom.describe' }
+    (r) => ({ target: createAtomicTarget(r[0]) }),
+    { printMethod: 'dom.describe' }
   ),
   text: createShortcutCommand(
     'dom.get_text',
     'bbx text <ref|selector> [budget]',
-    (r, ref) => ({
-      elementRef: ref,
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       textBudget: r[1] ? parseIntArg(r[1], 'budget') : undefined,
     }),
-    { resolve: true, printMethod: 'dom.get_text' }
+    { printMethod: 'dom.get_text' }
   ),
   styles: createShortcutCommand(
     'styles.get_computed',
     'bbx styles <ref|selector> [props]',
-    (r, ref) => ({ elementRef: ref, properties: parseCommaList(r[1]) }),
-    { resolve: true, printMethod: 'styles.get_computed' }
+    (r) => ({ target: createAtomicTarget(r[0]), properties: parseCommaList(r[1]) }),
+    { printMethod: 'styles.get_computed' }
   ),
   box: createShortcutCommand(
     'layout.get_box_model',
     'bbx box <ref|selector>',
-    (_r, ref) => ({ elementRef: ref }),
-    { resolve: true, printMethod: 'layout.get_box_model' }
-  ),
-  click: createShortcutCommand(
-    'input.click',
-    'bbx click <ref|selector> [button]',
-    (r, ref) => ({ target: { elementRef: ref }, button: r[1] }),
-    { resolve: true }
-  ),
-  focus: createShortcutCommand(
-    'input.focus',
-    'bbx focus <ref|selector>',
-    (_r, ref) => ({ target: { elementRef: ref } }),
-    { resolve: true }
-  ),
-  type: createShortcutCommand(
-    'input.type',
-    'bbx type <ref|selector> <text...>',
-    (r, ref) => ({ target: { elementRef: ref }, text: r.slice(1).join(' ') }),
-    { resolve: true }
+    (r) => ({ target: createAtomicTarget(r[0]) }),
+    { printMethod: 'layout.get_box_model' }
   ),
+  click: createShortcutCommand('input.click', 'bbx click <ref|selector> [button]', (r) => ({
+    target: createAtomicTarget(r[0]),
+    button: r[1],
+  })),
+  focus: createShortcutCommand('input.focus', 'bbx focus <ref|selector>', (r) => ({
+    target: createAtomicTarget(r[0]),
+  })),
+  type: createShortcutCommand('input.type', 'bbx type <ref|selector> <text...>', (r) => ({
+    target: createAtomicTarget(r[0]),
+    text: r.slice(1).join(' '),
+  })),
   fill: createShortcutCommand(
     'input.fill',
     'bbx fill <ref|selector> <value>',
-    (r, ref) => ({
-      target: { elementRef: ref },
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       value: r.slice(1).join(' '),
       mode: 'auto',
     }),
     {
-      resolve: true,
       description: 'Set input/textarea value (React/Vue/Angular-safe, auto fallback to keystrokes)',
     }
   ),
-  hover: createShortcutCommand(
-    'input.hover',
-    'bbx hover <ref|selector>',
-    (_r, ref) => ({ target: { elementRef: ref } }),
-    { resolve: true }
-  ),
+  hover: createShortcutCommand('input.hover', 'bbx hover <ref|selector>', (r) => ({
+    target: createAtomicTarget(r[0]),
+  })),
   html: createShortcutCommand(
     'dom.get_html',
     'bbx html <ref|selector> [maxLen]',
-    (r, ref) => ({
-      elementRef: ref,
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       maxLength: r[1] ? parseIntArg(r[1], 'maxLen') : undefined,
     }),
-    { resolve: true }
+    {}
   ),
   'patch-style': createShortcutCommand(
     'patch.apply_styles',
     'bbx patch-style <ref|sel> prop=val',
-    (r, ref) => ({
-      target: { elementRef: ref },
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       declarations: parsePropertyAssignments(r.slice(1)),
     }),
-    { resolve: true }
+    {}
   ),
   'patch-text': createShortcutCommand(
     'patch.apply_dom',
     'bbx patch-text <ref|sel> <text...>',
-    (r, ref) => ({
-      target: { elementRef: ref },
+    (r) => ({
+      target: createAtomicTarget(r[0]),
       operation: 'set_text',
       value: r.slice(1).join(' '),
     }),
-    { resolve: true, description: 'Apply a reversible DOM text patch' }
+    { description: 'Apply a reversible DOM text patch' }
   ),
   patches: createShortcutCommand('patch.list', 'bbx patches', () => ({}), {
     printMethod: 'patch.list',
@@ -222,14 +225,14 @@ export const SHORTCUT_COMMANDS = {
   attrs: createShortcutCommand(
     'dom.get_attributes',
     'bbx attrs <ref|selector> [attr1,...]',
-    (r, ref) => ({ elementRef: ref, attributes: parseCommaList(r[1]) }),
-    { resolve: true, printMethod: 'dom.get_attributes' }
+    (r) => ({ target: createAtomicTarget(r[0]), attributes: parseCommaList(r[1]) }),
+    { printMethod: 'dom.get_attributes' }
   ),
   'matched-rules': createShortcutCommand(
     'styles.get_matched_rules',
     'bbx matched-rules <ref|selector>',
-    (_r, ref) => ({ elementRef: ref }),
-    { resolve: true, printMethod: 'styles.get_matched_rules' }
+    (r) => ({ target: createAtomicTarget(r[0]) }),
+    { printMethod: 'styles.get_matched_rules' }
   ),
 };
 
@@ -260,7 +263,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx install-skill [targets|all] [--global] [--project <path>]      Install/update the managed Browser Bridge CLI skill',
       'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf|agents',
       'bbx status                                                         Check bridge connection',
-      'bbx doctor                                                         Diagnose install, daemon, extension, and access readiness',
+      'bbx doctor                                                         Consolidated local runtime, setup, protocol, and readiness diagnostics',
       'bbx restart                                                        Restart the local daemon and running MCP servers',
       'bbx proxy enable [--port 9223] [--bind-host 127.0.0.1] [--rotate-token]  Enable loopback TCP proxy mode for SSH tunneling',
       '  Non-loopback binds require --unsafe-plaintext because raw TCP is unencrypted.',
@@ -270,7 +273,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx remote list                                                    List remote destinations',
       'bbx remote test <name>                                             Ping a remote destination',
       'bbx remote remove <name>                                           Remove a remote destination',
-      'bbx access-request                                                 Request Browser Bridge access for the focused window',
+      'bbx access-request [intent]                                        Request access with inspect|interact|capture|navigate|debugger|general intent',
       'bbx logs                                                           Recent bridge logs',
       'bbx tabs                                                           List available tabs',
       'bbx tab-create [url]                                               Create a new tab',
@@ -372,7 +375,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Capture',
     lines: [
-      'bbx screenshot [--tab <tabId>] <ref|selector> [path]               Capture partial element screenshot',
+      'bbx screenshot [--tab <tabId>] [--format png|jpeg|webp] [--quality 0-100] <ref|selector> [path]',
     ],
   },
 ]);

package/packages/agent-client/src/content-extract.js

@@ -0,0 +1,198 @@
+// @ts-check
+
+import { Readability } from '@mozilla/readability';
+import { parseHTML } from 'linkedom';
+
+/** @typedef {import('../../protocol/src/types.js').ExtractContentResult} ExtractContentResult */
+/** @typedef {import('../../protocol/src/types.js').NormalizedExtractContentParams} ExtractContentParams */
+
+const METADATA_LIMITS = Object.freeze({ title: 300, byline: 200, excerpt: 500, siteName: 200 });
+const EXCLUDED_SELECTOR =
+  'script,style,noscript,template,input,textarea,select,option,button,[hidden],[aria-hidden="true"]';
+
+/** @param {string | null | undefined} value @param {number} limit @returns {string | undefined} */
+function boundedText(value, limit) {
+  const normalized = String(value ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return normalized ? normalized.slice(0, limit) : undefined;
+}
+
+/** @param {ParentNode} root @returns {void} */
+function sanitize(root) {
+  for (const element of root.querySelectorAll(EXCLUDED_SELECTOR)) element.remove();
+  for (const element of root.querySelectorAll('[style]')) {
+    const style = element.getAttribute('style')?.toLowerCase() ?? '';
+    if (/display\s*:\s*none|visibility\s*:\s*hidden/.test(style)) element.remove();
+  }
+}
+
+/** @param {Element} element @returns {number} */
+function meaningfulLength(element) {
+  return (element.textContent ?? '').replace(/\s+/g, ' ').trim().length;
+}
+
+/** @param {ParentNode} root @returns {Element | null} */
+function largestSemanticRoot(root) {
+  let best = null;
+  let bestLength = 0;
+  const candidates = [];
+  if (
+    'matches' in root &&
+    typeof (/** @type {{ matches?: unknown }} */ (root).matches) === 'function' &&
+    /** @type {Element} */ (root).matches('article,main,[role="main"]')
+  ) {
+    candidates.push(/** @type {Element} */ (root));
+  }
+  candidates.push(...root.querySelectorAll('article,main,[role="main"]'));
+  for (const candidate of candidates) {
+    const length = meaningfulLength(candidate);
+    if (length > bestLength) {
+      best = candidate;
+      bestLength = length;
+    }
+  }
+  return best;
+}
+
+/** @param {Node} node @returns {string} */
+function markdownForNode(node) {
+  if (node.nodeType === 3) return (node.textContent ?? '').replace(/\s+/g, ' ');
+  if (node.nodeType !== 1) return '';
+  const element = /** @type {Element} */ (node);
+  const tag = element.tagName.toLowerCase();
+  const children = () => Array.from(element.childNodes, markdownForNode).join('');
+  if (/^h[1-6]$/.test(tag)) return `\n${'#'.repeat(Number(tag[1]))} ${children().trim()}\n\n`;
+  if (['p', 'div', 'section', 'article', 'main'].includes(tag)) {
+    return `\n${children().trim()}\n\n`;
+  }
+  if (tag === 'br') return '\n';
+  if (tag === 'hr') return '\n---\n';
+  if (tag === 'strong' || tag === 'b') return `**${children().trim()}**`;
+  if (tag === 'em' || tag === 'i') return `*${children().trim()}*`;
+  if (tag === 'code' && element.parentElement?.tagName.toLowerCase() !== 'pre') {
+    return `\`${(element.textContent ?? '').replace(/`/g, '\\`')}\``;
+  }
+  if (tag === 'pre') return `\n\`\`\`\n${element.textContent ?? ''}\n\`\`\`\n\n`;
+  if (tag === 'blockquote') {
+    return `\n${children()
+      .trim()
+      .split('\n')
+      .map((line) => `> ${line}`)
+      .join('\n')}\n\n`;
+  }
+  if (tag === 'li') {
+    const marker =
+      element.parentElement?.tagName.toLowerCase() === 'ol'
+        ? `${Array.from(element.parentElement.children).indexOf(element) + 1}.`
+        : '-';
+    return `\n${marker} ${children().trim()}`;
+  }
+  if (tag === 'ul' || tag === 'ol') return `${children()}\n\n`;
+  if (tag === 'a') {
+    const label = children().trim();
+    const href = element.getAttribute('href')?.trim();
+    return href && !/^(?:javascript|data):/i.test(href) ? `[${label}](${href})` : label;
+  }
+  return children();
+}
+
+/** @param {Element} root @param {'text' | 'markdown'} format @returns {string} */
+function formatRoot(root, format) {
+  if (format === 'markdown') {
+    return markdownForNode(root)
+      .replace(/[ \t]+\n/g, '\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim();
+  }
+  return (root.textContent ?? '')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/** @param {string} content @param {number} budget @param {'text' | 'markdown'} format */
+function truncateContent(content, budget, format) {
+  if (content.length <= budget) return { content, truncated: false, omitted: 0 };
+  const boundary = Math.max(content.lastIndexOf('\n\n', budget), content.lastIndexOf(' ', budget));
+  const end = boundary >= Math.floor(budget * 0.7) ? boundary : budget;
+  let value = content.slice(0, end).trimEnd();
+  if (format === 'markdown' && (value.match(/```/g)?.length ?? 0) % 2 === 1) {
+    value = `${value.slice(0, Math.max(0, budget - 4)).trimEnd()}\n\`\`\``;
+  }
+  return { content: value, truncated: true, omitted: content.length - value.length };
+}
+
+/**
+ * Convert one bounded browser HTML snapshot into semantic content in Node.
+ * Raw HTML is consumed here and never included in the returned result.
+ *
+ * @param {string} html
+ * @param {ExtractContentParams} params
+ * @param {{ title?: string, settlement?: ExtractContentResult['settlement'] }} [context]
+ * @returns {ExtractContentResult}
+ */
+export function extractContentFromHtml(html, params, context = {}) {
+  const escapedTitle = String(context.title ?? '').replace(/[&<>]/g, (character) => {
+    if (character === '&') return '&amp;';
+    if (character === '<') return '&lt;';
+    return '&gt;';
+  });
+  const { document } = parseHTML(
+    `<!doctype html><html><head><title>${escapedTitle}</title></head><body>${html}</body></html>`
+  );
+  sanitize(document);
+  const semanticRoot = largestSemanticRoot(document.body);
+  const semanticLength = semanticRoot ? meaningfulLength(semanticRoot) : 0;
+  let readability = null;
+  try {
+    readability = new Readability(/** @type {Document} */ (document.cloneNode(true))).parse();
+  } catch {
+    readability = null;
+  }
+
+  /** @type {Element} */
+  let resultRoot;
+  /** @type {import('../../protocol/src/types.js').ExtractContentSource} */
+  let source;
+  if (readability && (readability.length ?? 0) >= Math.max(200, Math.floor(semanticLength * 0.2))) {
+    const template = document.createElement('template');
+    template.innerHTML = readability.content ?? '';
+    sanitize(template.content);
+    const wrapper = document.createElement('article');
+    wrapper.append(template.content.cloneNode(true));
+    resultRoot = wrapper;
+    source = 'readability';
+  } else if (semanticRoot && semanticLength > 0) {
+    resultRoot = semanticRoot;
+    source = 'semantic-root';
+  } else {
+    resultRoot = document.body;
+    source = 'body';
+  }
+
+  const formatted = formatRoot(resultRoot, params.format);
+  const bounded = truncateContent(formatted, params.textBudget, params.format);
+  const metadata = params.includeMetadata
+    ? {
+        title: boundedText(readability?.title ?? context.title, METADATA_LIMITS.title),
+        byline: boundedText(readability?.byline, METADATA_LIMITS.byline),
+        excerpt: boundedText(readability?.excerpt, METADATA_LIMITS.excerpt),
+        siteName: boundedText(readability?.siteName, METADATA_LIMITS.siteName),
+      }
+    : {};
+  return {
+    format: params.format,
+    content: bounded.content,
+    ...metadata,
+    source,
+    root: {
+      tag: resultRoot.tagName.toLowerCase(),
+      ...(params.selector ? { selector: params.selector } : {}),
+    },
+    length: formatted.length,
+    truncated: bounded.truncated,
+    omitted: bounded.omitted,
+    ...(context.settlement ? { settlement: context.settlement } : {}),
+  };
+}

package/packages/agent-client/src/remotes.js

@@ -287,7 +287,7 @@ function validateAuthToken(token) {
 
 /**
  * @param {string | null | undefined} destinationId
- * @param {{ defaultTimeoutMs?: number }} [options={}]
+ * @param {{ defaultTimeoutMs?: number, checkProtocolOnConnect?: boolean }} [options={}]
  * @returns {Promise<BridgeClient>}
  */
 export async function createBridgeClientForDestination(destinationId, options = {}) {