@browserbridge/bbx 1.0.0 → 1.1.0

package/packages/native-host/src/native-host.js

@@ -1,16 +1,13 @@
 // @ts-check
 
-import { spawn } from 'node:child_process';
 import net from 'node:net';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { createFailure, ERROR_CODES } from '../../protocol/src/index.js';
-import { getSocketPath } from './config.js';
+import { createSocketBridgeTransport, getBridgeTransport } from './config.js';
+import { spawnBridgeDaemonProcess } from './daemon-process.js';
 import { createNativeMessageReader, writeJsonLine, writeNativeMessage } from './framing.js';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const daemonEntryPath = path.resolve(__dirname, '../bin/bridge-daemon.js');
+/** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
 
 /**
  * @typedef {{
@@ -54,10 +51,10 @@ const daemonEntryPath = path.resolve(__dirname, '../bin/bridge-daemon.js');
  */
 function isHostBridgeRequest(message) {
   return Boolean(
-    message
-    && typeof message === 'object'
-    && /** @type {Record<string, unknown>} */ (message).type === 'host.bridge_request'
-    && typeof /** @type {Record<string, unknown>} */ (message).request === 'object'
+    message &&
+    typeof message === 'object' &&
+    /** @type {Record<string, unknown>} */ (message).type === 'host.bridge_request' &&
+    typeof (/** @type {Record<string, unknown>} */ (message).request) === 'object'
   );
 }
 
@@ -67,10 +64,10 @@ function isHostBridgeRequest(message) {
  */
 function isHostStatusRequest(message) {
   return Boolean(
-    message
-    && typeof message === 'object'
-    && /** @type {Record<string, unknown>} */ (message).type === 'host.setup_status.request'
-    && typeof /** @type {Record<string, unknown>} */ (message).requestId === 'string'
+    message &&
+    typeof message === 'object' &&
+    /** @type {Record<string, unknown>} */ (message).type === 'host.setup_status.request' &&
+    typeof (/** @type {Record<string, unknown>} */ (message).requestId) === 'string'
   );
 }
 
@@ -80,9 +77,9 @@ function isHostStatusRequest(message) {
  */
 function isHostIdentity(message) {
   return Boolean(
-    message
-    && typeof message === 'object'
-    && /** @type {Record<string, unknown>} */ (message).type === 'host.identity'
+    message &&
+    typeof message === 'object' &&
+    /** @type {Record<string, unknown>} */ (message).type === 'host.identity'
   );
 }
 
@@ -92,10 +89,10 @@ function isHostIdentity(message) {
  */
 function isHostAccessUpdate(message) {
   return Boolean(
-    message
-    && typeof message === 'object'
-    && /** @type {Record<string, unknown>} */ (message).type === 'host.access_update'
-    && typeof /** @type {Record<string, unknown>} */ (message).accessEnabled === 'boolean'
+    message &&
+    typeof message === 'object' &&
+    /** @type {Record<string, unknown>} */ (message).type === 'host.access_update' &&
+    typeof (/** @type {Record<string, unknown>} */ (message).accessEnabled) === 'boolean'
   );
 }
 
@@ -105,20 +102,24 @@ function isHostAccessUpdate(message) {
  */
 function isHostActivity(message) {
   return Boolean(
-    message
-    && typeof message === 'object'
-    && /** @type {Record<string, unknown>} */ (message).type === 'host.activity'
+    message &&
+    typeof message === 'object' &&
+    /** @type {Record<string, unknown>} */ (message).type === 'host.activity'
   );
 }
 
 /**
- * @param {{ socketPath?: string }} [options={}]
+ * @param {{ transport?: BridgeTransport, socketPath?: string }} [options={}]
  * @returns {Promise<void>}
  */
-export async function runNativeHost({ socketPath = getSocketPath() } = {}) {
+export async function runNativeHost({
+  transport = getBridgeTransport(),
+  socketPath = undefined,
+} = {}) {
+  const resolvedTransport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
   let socket;
   try {
-    socket = await connectWithBootstrap(socketPath);
+    socket = await connectWithBootstrap(resolvedTransport);
   } catch (error) {
     await writeNativeMessage(process.stdout, {
       type: 'agent.response',
@@ -126,13 +127,23 @@ export async function runNativeHost({ socketPath = getSocketPath() } = {}) {
         'native_bootstrap',
         ERROR_CODES.NATIVE_HOST_UNAVAILABLE,
         error instanceof Error ? error.message : String(error)
-      )
+      ),
     });
     return;
   }
 
   socket.setEncoding('utf8');
   bindBridgeSocketLifecycle(socket);
+  const handleStdinEnd = () => {
+    socket.destroy();
+  };
+  process.stdin.once('end', handleStdinEnd);
+  const cleanupStdinEndListener = () => {
+    process.stdin.removeListener('end', handleStdinEnd);
+  };
+  socket.once('close', cleanupStdinEndListener);
+  socket.once('end', cleanupStdinEndListener);
+  socket.once('error', cleanupStdinEndListener);
   await writeJsonLine(socket, { type: 'register', role: 'extension' });
 
   let lineBuffer = '';
@@ -159,72 +170,88 @@ export async function runNativeHost({ socketPath = getSocketPath() } = {}) {
         if (message.type === 'agent.response') {
           await writeNativeMessage(process.stdout, {
             type: 'host.bridge_response',
-            response: message.response
+            response: message.response,
           });
           return;
         }
-        if (message.type === 'extension.setup_status.response' || message.type === 'extension.setup_status.error') {
+        if (
+          message.type === 'extension.setup_status.response' ||
+          message.type === 'extension.setup_status.error'
+        ) {
           await writeNativeMessage(process.stdout, {
-            type: message.type === 'extension.setup_status.response'
-              ? 'host.setup_status.response'
-              : 'host.setup_status.error',
+            type:
+              message.type === 'extension.setup_status.response'
+                ? 'host.setup_status.response'
+                : 'host.setup_status.error',
             requestId: message.requestId,
             status: message.status,
-            error: message.error
+            error: message.error,
           });
         }
       })().catch((err) => {
-        console.error('native-host: socket message handler failed:', err instanceof Error ? err.message : err);
+        console.error(
+          'native-host: socket message handler failed:',
+          err instanceof Error ? err.message : err
+        );
       });
     }
   });
 
-  createNativeMessageReader(process.stdin, (message) => {
-    void (async () => {
-      if (isHostBridgeRequest(message)) {
-        await writeJsonLine(socket, {
-          type: 'agent.request',
-          request: message.request
-        });
-        return;
-      }
-      if (isHostStatusRequest(message)) {
-        await writeJsonLine(socket, {
-          type: 'extension.setup_status.request',
-          requestId: message.requestId
-        });
-        return;
-      }
-      if (isHostIdentity(message)) {
-        await writeJsonLine(socket, {
-          type: 'extension.identity',
-          browserName: message.browserName,
-          profileLabel: message.profileLabel
-        });
-        return;
-      }
-      if (isHostAccessUpdate(message)) {
-        await writeJsonLine(socket, {
-          type: 'extension.access_update',
-          accessEnabled: message.accessEnabled
-        });
-        return;
-      }
-      if (isHostActivity(message)) {
+  createNativeMessageReader(
+    process.stdin,
+    (message) => {
+      void (async () => {
+        if (isHostBridgeRequest(message)) {
+          await writeJsonLine(socket, {
+            type: 'agent.request',
+            request: message.request,
+          });
+          return;
+        }
+        if (isHostStatusRequest(message)) {
+          await writeJsonLine(socket, {
+            type: 'extension.setup_status.request',
+            requestId: message.requestId,
+          });
+          return;
+        }
+        if (isHostIdentity(message)) {
+          await writeJsonLine(socket, {
+            type: 'extension.identity',
+            browserName: message.browserName,
+            profileLabel: message.profileLabel,
+          });
+          return;
+        }
+        if (isHostAccessUpdate(message)) {
+          await writeJsonLine(socket, {
+            type: 'extension.access_update',
+            accessEnabled: message.accessEnabled,
+          });
+          return;
+        }
+        if (isHostActivity(message)) {
+          await writeJsonLine(socket, {
+            type: 'extension.activity',
+            at: message.at,
+          });
+          return;
+        }
         await writeJsonLine(socket, {
-          type: 'extension.activity',
-          at: message.at
+          type: 'extension.response',
+          response: message,
         });
-        return;
-      }
-      await writeJsonLine(socket, {
-        type: 'extension.response',
-        response: message
+      })().catch((err) => {
+        console.error(
+          'native-host: stdin message handler failed:',
+          err instanceof Error ? err.message : err
+        );
       });
-    })().catch((err) => {
-      console.error('native-host: stdin message handler failed:', err instanceof Error ? err.message : err);
-    });
-  });
+    },
+    () => {
+      socket.destroy();
+    }
+  );
 }
 
 /**
@@ -235,9 +262,12 @@ export async function runNativeHost({ socketPath = getSocketPath() } = {}) {
  * @param {() => void} [onTerminate]
  * @returns {void}
  */
-export function bindBridgeSocketLifecycle(socket, onTerminate = () => {
-  process.exit(0);
-}) {
+export function bindBridgeSocketLifecycle(
+  socket,
+  onTerminate = () => {
+    process.exit(0);
+  }
+) {
   let terminated = false;
 
   /**
@@ -257,28 +287,49 @@ export function bindBridgeSocketLifecycle(socket, onTerminate = () => {
 }
 
 /**
- * @param {string} socketPath
+ * @typedef {{
+ *   connectSocketFn?: (transport: BridgeTransport) => Promise<net.Socket>,
+ *   shouldBootstrapFn?: (error: unknown) => boolean,
+ *   spawnBridgeDaemonFn?: () => void,
+ *   delayFn?: (ms: number) => Promise<void>,
+ *   maxAttempts?: number,
+ * }} ConnectWithBootstrapOptions
+ */
+
+/**
+ * @param {BridgeTransport | string} transport
+ * @param {ConnectWithBootstrapOptions} [options]
  * @returns {Promise<net.Socket>}
  */
-async function connectWithBootstrap(socketPath) {
+export async function connectWithBootstrap(transport, options = {}) {
+  const {
+    connectSocketFn = connectSocket,
+    shouldBootstrapFn = shouldBootstrap,
+    spawnBridgeDaemonFn = spawnBridgeDaemon,
+    delayFn = delay,
+    maxAttempts = 10,
+  } = options;
+  const resolvedTransport =
+    typeof transport === 'string' ? createSocketBridgeTransport(transport) : transport;
+
   try {
-    return await connectSocket(socketPath);
+    return await connectSocketFn(resolvedTransport);
   } catch (error) {
-    if (!shouldBootstrap(error)) {
+    if (!shouldBootstrapFn(error)) {
       throw error;
     }
   }
 
-  spawnBridgeDaemon();
+  spawnBridgeDaemonFn();
 
   let lastError = null;
-  for (let attempt = 0; attempt < 10; attempt += 1) {
-    await delay(200);
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    await delayFn(200);
     try {
-      return await connectSocket(socketPath);
+      return await connectSocketFn(resolvedTransport);
     } catch (error) {
       lastError = error;
-      if (!shouldBootstrap(error)) {
+      if (!shouldBootstrapFn(error)) {
         throw error;
       }
     }
@@ -288,12 +339,15 @@ async function connectWithBootstrap(socketPath) {
 }
 
 /**
- * @param {string} socketPath
+ * @param {BridgeTransport} transport
  * @returns {Promise<net.Socket>}
  */
-function connectSocket(socketPath) {
+function connectSocket(transport) {
   return new Promise((resolve, reject) => {
-    const socket = net.createConnection(socketPath);
+    const socket =
+      transport.type === 'tcp'
+        ? net.createConnection({ host: transport.host, port: transport.port })
+        : net.createConnection(transport.socketPath);
     /**
      * @param {Error} error
      * @returns {void}
@@ -315,21 +369,19 @@ function connectSocket(socketPath) {
  * @returns {void}
  */
 function spawnBridgeDaemon() {
-  const child = spawn(process.execPath, [daemonEntryPath], {
-    detached: true,
-    stdio: 'ignore'
-  });
-  child.unref();
+  spawnBridgeDaemonProcess();
 }
 
 /**
  * @param {unknown} error
  * @returns {boolean}
  */
-function shouldBootstrap(error) {
-  return error instanceof Error
-    && 'code' in error
-    && (error.code === 'ENOENT' || error.code === 'ECONNREFUSED');
+export function shouldBootstrap(error) {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    (error.code === 'ENOENT' || error.code === 'ECONNREFUSED')
+  );
 }
 
 /**

package/packages/protocol/src/budget.js

@@ -4,11 +4,7 @@
 /** @typedef {import('./types.js').BudgetOptions} BudgetOptions */
 /** @typedef {import('./types.js').TruncateResult} TruncateResult */
 
-import {
-  DEFAULT_MAX_DEPTH,
-  DEFAULT_MAX_NODES,
-  DEFAULT_TEXT_BUDGET,
-} from './defaults.js';
+import { DEFAULT_MAX_DEPTH, DEFAULT_MAX_NODES, DEFAULT_TEXT_BUDGET } from './defaults.js';
 
 /**
  * @param {BudgetOptions} [options={}]
@@ -20,7 +16,7 @@ export function applyBudget(options = {}) {
     maxDepth: clamp(options.maxDepth ?? DEFAULT_MAX_DEPTH, 1, 20),
     textBudget: clamp(options.textBudget ?? DEFAULT_TEXT_BUDGET, 32, 10000),
     includeBbox: options.includeBbox !== false,
-    attributeAllowlist: normalizeList(options.attributeAllowlist)
+    attributeAllowlist: normalizeList(options.attributeAllowlist),
   };
 }
 
@@ -41,7 +37,7 @@ export function truncateText(value, budget) {
   return {
     value: `${value.slice(0, Math.max(0, budget - 1))}\u2026`,
     truncated: true,
-    omitted: value.length - budget
+    omitted: value.length - budget,
   };
 }
 

package/packages/protocol/src/capabilities.js

@@ -17,10 +17,11 @@ export const CAPABILITIES = Object.freeze({
   CDP_DOM_SNAPSHOT: 'cdp.dom_snapshot',
   CDP_BOX_MODEL: 'cdp.box_model',
   CDP_STYLES: 'cdp.styles',
+  CDP_INPUT: 'cdp.input',
   AUTOMATION_INPUT: 'automation.input',
   TABS_MANAGE: 'tabs.manage',
   PERFORMANCE_READ: 'performance.read',
-  NETWORK_READ: 'network.read'
+  NETWORK_READ: 'network.read',
 });
 
 export const DEFAULT_CAPABILITIES = Object.freeze([
@@ -38,9 +39,10 @@ export const DEFAULT_CAPABILITIES = Object.freeze([
   CAPABILITIES.CDP_DOM_SNAPSHOT,
   CAPABILITIES.CDP_BOX_MODEL,
   CAPABILITIES.CDP_STYLES,
+  CAPABILITIES.CDP_INPUT,
   CAPABILITIES.TABS_MANAGE,
   CAPABILITIES.PERFORMANCE_READ,
-  CAPABILITIES.NETWORK_READ
+  CAPABILITIES.NETWORK_READ,
 ]);
 
 /** @type {Readonly<Record<CapabilityMethod, Capability | null>>} */
@@ -99,9 +101,10 @@ export const METHOD_CAPABILITIES = Object.freeze({
   'cdp.get_dom_snapshot': CAPABILITIES.CDP_DOM_SNAPSHOT,
   'cdp.get_box_model': CAPABILITIES.CDP_BOX_MODEL,
   'cdp.get_computed_styles_for_node': CAPABILITIES.CDP_STYLES,
+  'cdp.dispatch_key_event': CAPABILITIES.CDP_INPUT,
   'performance.get_metrics': CAPABILITIES.PERFORMANCE_READ,
   'log.tail': null,
-  'health.ping': null
+  'health.ping': null,
 });
 
 /**

package/packages/protocol/src/defaults.js

@@ -65,6 +65,7 @@ export const DEBUGGER_BACKED_METHODS = new Set([
   'cdp.get_dom_snapshot',
   'cdp.get_box_model',
   'cdp.get_computed_styles_for_node',
+  'cdp.dispatch_key_event',
 ]);
 
 /**

package/packages/protocol/src/errors.js

@@ -12,7 +12,7 @@ export const ERROR_CODES = Object.freeze({
   INVALID_REQUEST: 'INVALID_REQUEST',
   NATIVE_HOST_UNAVAILABLE: 'NATIVE_HOST_UNAVAILABLE',
   EXTENSION_DISCONNECTED: 'EXTENSION_DISCONNECTED',
-  TIMEOUT: 'TIMEOUT'
+  TIMEOUT: 'TIMEOUT',
 });
 
 /**
@@ -23,47 +23,51 @@ export const ERROR_CODES = Object.freeze({
 export const ERROR_RECOVERY = Object.freeze({
   [ERROR_CODES.ACCESS_DENIED]: {
     retry: false,
-    hint: 'Access is off for this window. Ask the user to click Enable in the Browser Bridge popup or side panel. Do not request access again until that window is enabled.'
+    hint: 'Access is off for this window. Ask the user to click Enable in the Browser Bridge popup or side panel. Do not request access again until that window is enabled.',
+  },
+  [ERROR_CODES.RESULT_TRUNCATED]: {
+    retry: false,
+    hint: 'Result was truncated to fit the response budget. Narrow the query or raise the relevant budget if more detail is required.',
   },
   [ERROR_CODES.ELEMENT_STALE]: {
     retry: false,
     alternativeMethod: 'dom.query',
-    hint: 'Element was removed from the DOM. Re-query with the same selector to get a fresh elementRef.'
+    hint: 'Element was removed from the DOM. Re-query with the same selector to get a fresh elementRef.',
   },
   [ERROR_CODES.TAB_MISMATCH]: {
     retry: false,
     alternativeMethod: 'tabs.list',
-    hint: 'Tab was closed or not found. Use tabs.list to find an available tab.'
+    hint: 'Tab was closed or not found. Use tabs.list to find an available tab.',
   },
   [ERROR_CODES.TIMEOUT]: {
     retry: true,
     retryAfterMs: 1000,
-    hint: 'Operation exceeded the time limit. Retry once, or simplify the request (smaller maxNodes, narrower selector).'
+    hint: 'Operation exceeded the time limit. Retry once, or simplify the request (smaller maxNodes, narrower selector).',
   },
   [ERROR_CODES.RATE_LIMITED]: {
     retry: true,
     retryAfterMs: 2000,
-    hint: 'Too many requests. Back off and retry after a short delay.'
+    hint: 'Too many requests. Back off and retry after a short delay.',
   },
   [ERROR_CODES.EXTENSION_DISCONNECTED]: {
     retry: true,
     retryAfterMs: 3000,
     alternativeMethod: 'health.ping',
-    hint: 'Extension not connected. Check Chrome is running, then retry. Use health.ping to verify connectivity.'
+    hint: 'Extension not connected. Check Chrome is running, then retry. Use health.ping to verify connectivity.',
   },
   [ERROR_CODES.NATIVE_HOST_UNAVAILABLE]: {
     retry: false,
-    hint: 'Native host not reachable. Run `bbx doctor` to diagnose the installation.'
+    hint: 'Native host not reachable. Run `bbx doctor` to diagnose the installation.',
   },
   [ERROR_CODES.INVALID_REQUEST]: {
     retry: false,
-    hint: 'Malformed method or params. Check the method name and parameter types.'
+    hint: 'Malformed method or params. Check the method name and parameter types.',
   },
   [ERROR_CODES.INTERNAL_ERROR]: {
     retry: true,
     retryAfterMs: 1000,
-    hint: 'Unexpected extension error. Retry once; if persistent, check page.get_console for details.'
-  }
+    hint: 'Unexpected extension error. Retry once; if persistent, check page.get_console for details.',
+  },
 });
 
 /**

package/packages/protocol/src/payload-cost.js

@@ -22,7 +22,9 @@ export function getUtf8ByteLength(value) {
   if (!value) {
     return 0;
   }
-  return textEncoder.encode(value).length;
+  return typeof Buffer !== 'undefined'
+    ? Buffer.byteLength(value, 'utf8')
+    : textEncoder.encode(value).length;
 }
 
 /**
@@ -45,14 +47,25 @@ export function estimateSerializedPayloadCost(serialized) {
 }
 
 /**
- * Estimate cost for a JSON-serializable payload.
+ * Serialize a JSON payload for transport-oriented cost estimation.
  *
  * @param {unknown} value
- * @returns {PayloadCost}
+ * @returns {string}
  */
-export function estimateJsonPayloadCost(value) {
+export function serializeJsonPayload(value) {
   if (typeof value === 'undefined') {
-    return estimateSerializedPayloadCost('');
+    return '';
   }
-  return estimateSerializedPayloadCost(JSON.stringify(value) ?? '');
+  return JSON.stringify(value) ?? '';
+}
+
+/**
+ * Estimate cost for a JSON-serializable payload.
+ *
+ * @param {unknown} value
+ * @param {string} [serialized]
+ * @returns {PayloadCost}
+ */
+export function estimateJsonPayloadCost(value, serialized = serializeJsonPayload(value)) {
+  return estimateSerializedPayloadCost(serialized);
 }