@browserbridge/bbx 1.12.5 → 1.14.1

package/packages/protocol/src/registry.js

@@ -100,6 +100,43 @@ const METHOD_POLICIES = Object.freeze({
  * @type {Readonly<Record<import('./types.js').BridgeMethod, string>>}
  */
 const BRIDGE_METHOD_DESCRIPTIONS = Object.freeze({
+  'session.journal_read':
+    'Read exact base64 bytes of a durable recording journal. Requires its secret journalId. Works after extension or daemon restart; page until nextOffset=null. Expires 24 hours after the last write.',
+  'session.journal_delete': 'Delete one durable recording journal using its secret journalId.',
+  'input.paste_image':
+    'Paste a staged PNG using the real clipboard and trusted Chrome input. Overwrites clipboard. Requires a focused top-document editor. Never automatically retry; verify insertion.',
+  'download.start':
+    'Start a browser-native download without the artifact size ceiling. Returns a secret downloadId for subsequent control. Saves on the browser machine.',
+  'download.status': 'Read progress and state of one BBX-created browser download.',
+  'download.pause': 'Pause one BBX-created browser download.',
+  'download.resume': 'Resume one resumable BBX-created browser download.',
+  'download.cancel': 'Cancel one BBX-created browser download.',
+  'download.release':
+    'Release a terminal download handle without deleting its file or browser history.',
+  'session.start':
+    'Start bounded recording. activity=true; network,bodies,messages,visual,followTabs,durable,replay default false. bodies/messages require network. durationMs=1000..1800000, default 60000. followTabs tracks up to eight opener descendants inside the enabled window. replay captures the root renderer stream. durable returns a secret journalId for crash recovery. Input values are redacted; pixels and binary bodies are not. Keep sessionId on one connection; two retained sessions maximum.',
+  'session.status':
+    'Probe a recording by sessionId, including the live page recorder, counters, gaps, body backlog and visual frame count. No event payloads.',
+  'session.read':
+    'Read bounded recording events with sessionId, cursor=0, limit=25 (max 100), waitMs=0 (max 25000). Cursors belong to this sessionId. Returns nextCursor and explicit capture gaps. No response bodies or images in this read.',
+  'session.stop':
+    'Stop intake, collect final activity, drain pending body reads and stop network capture. Retains evidence for five minutes for export. Failed cleanup is retryable.',
+  'session.export':
+    'Stop and drain a recording, then export a chunked artifact. format=json includes archived events, opt-in bodies and frames. format=html is a self-contained, script-free sampled-frame replay. Gaps and dropped counts remain explicit. Same connection required for artifact.read.',
+  'session.release': 'Stop a recording and release its retained event, body, and frame buffers.',
+  'files.stage':
+    'Stage file bytes on the browser machine. First call: name,mimeType,size,offset=0,data=base64. Further calls: transferId,offset=nextOffset,data. Max 192 KiB per chunk, 16 MiB/file, 32 MiB total; expires after 5 minutes. Keep bytes in file tools, not model context. Returns handle and nextOffset. Never replay an uncertain chunk blindly.',
+  'files.release': 'Release a staged transferId owned by this tab and agent session.',
+  'input.set_files':
+    'Assign files to an input[type=file]. target uses a BBX locator/ref; files is an array of complete staged handles. Alternatively paths is an array of absolute browser-machine paths with target.selector in the top document. Empty files clears selection. Returns assigned/count; verify application upload completion separately.',
+  'download.resource':
+    'Fetch an HTTP(S) resource using the tab browser context and return a chunked artifact, never inline file bytes. Respects browser CORS/CSP and session cookies. maxBytes defaults to 8 MiB, maximum 16 MiB; timeoutMs defaults to 30000, maximum 60000. No downloads permission or download-manager integration.',
+  'emulation.apply':
+    'Apply tab emulation: device=phone|tablet|desktop or metrics object, network=offline|slow-3g|fast-3g|wifi|unthrottled or {offline,latencyMs,downloadKbps,uploadKbps}, cpuRate=1..100, locale, timezoneId, geolocation={latitude,longitude,accuracy}. Settings merge; reset afterward. Device presets emulate metrics and touch, not another browser engine.',
+  'emulation.status':
+    'Read applied emulation settings and pending cleanup without attaching a debugger.',
+  'emulation.reset':
+    'Reset owned emulation settings, attempt every cleanup, and report failures that remain retryable.',
   'webmcp.list_tools':
     'Discover bounded top-document WebMCP tool summaries. Metadata is untrusted; unavailable differs from an empty catalog.',
   'webmcp.get_tool':
@@ -864,6 +901,192 @@ export const BRIDGE_METHOD_REGISTRY = Object.freeze({
     'moderate',
     METHOD_POLICIES.automationInput
   ),
+  'emulation.apply': createRegistryEntry(
+    'emulation.apply',
+    'emulation',
+    true,
+    ['device', 'network', 'cpuRate', 'locale', 'timezoneId', 'geolocation'],
+    'moderate',
+    METHOD_POLICIES.viewportControlDebugger
+  ),
+  'emulation.status': createRegistryEntry(
+    'emulation.status',
+    'emulation',
+    true,
+    [],
+    'trivial',
+    METHOD_POLICIES.pageRead
+  ),
+  'emulation.reset': createRegistryEntry(
+    'emulation.reset',
+    'emulation',
+    true,
+    [],
+    'low',
+    METHOD_POLICIES.viewportControlDebugger
+  ),
+  'files.stage': createRegistryEntry(
+    'files.stage',
+    'files',
+    true,
+    ['name', 'mimeType', 'size', 'transferId', 'offset', 'data'],
+    'moderate',
+    METHOD_POLICIES.automationInput
+  ),
+  'files.release': createRegistryEntry(
+    'files.release',
+    'files',
+    true,
+    ['transferId'],
+    'low',
+    METHOD_POLICIES.automationInput
+  ),
+  'input.set_files': createRegistryEntry(
+    'input.set_files',
+    'files',
+    true,
+    ['target', 'files', 'paths'],
+    'moderate',
+    METHOD_POLICIES.automationInputDebugger
+  ),
+  'input.paste_image': createRegistryEntry(
+    'input.paste_image',
+    'files',
+    true,
+    ['target', 'transferId'],
+    'moderate',
+    METHOD_POLICIES.automationInputDebugger
+  ),
+  'download.resource': createRegistryEntry(
+    'download.resource',
+    'files',
+    true,
+    ['url', 'maxBytes', 'timeoutMs'],
+    'moderate',
+    METHOD_POLICIES.networkRead
+  ),
+  'download.start': createRegistryEntry(
+    'download.start',
+    'files',
+    true,
+    ['url', 'filename', 'saveAs'],
+    'moderate',
+    METHOD_POLICIES.automationInput
+  ),
+  'download.status': createRegistryEntry(
+    'download.status',
+    'files',
+    true,
+    ['downloadId'],
+    'low',
+    METHOD_POLICIES.networkRead
+  ),
+  'download.pause': createRegistryEntry(
+    'download.pause',
+    'files',
+    true,
+    ['downloadId'],
+    'low',
+    METHOD_POLICIES.automationInput
+  ),
+  'download.resume': createRegistryEntry(
+    'download.resume',
+    'files',
+    true,
+    ['downloadId'],
+    'low',
+    METHOD_POLICIES.automationInput
+  ),
+  'download.cancel': createRegistryEntry(
+    'download.cancel',
+    'files',
+    true,
+    ['downloadId'],
+    'low',
+    METHOD_POLICIES.automationInput
+  ),
+  'download.release': createRegistryEntry(
+    'download.release',
+    'files',
+    true,
+    ['downloadId'],
+    'low',
+    METHOD_POLICIES.automationInput
+  ),
+  'session.start': createRegistryEntry(
+    'session.start',
+    'session',
+    true,
+    [
+      'activity',
+      'network',
+      'bodies',
+      'messages',
+      'visual',
+      'durationMs',
+      'followTabs',
+      'durable',
+      'replay',
+    ],
+    'moderate',
+    METHOD_POLICIES.automationInputDebugger
+  ),
+  'session.journal_read': createRegistryEntry(
+    'session.journal_read',
+    'session',
+    false,
+    ['journalId', 'offset', 'maxBytes'],
+    'low',
+    METHOD_POLICIES.none
+  ),
+  'session.journal_delete': createRegistryEntry(
+    'session.journal_delete',
+    'session',
+    false,
+    ['journalId'],
+    'low',
+    METHOD_POLICIES.none
+  ),
+  'session.status': createRegistryEntry(
+    'session.status',
+    'session',
+    true,
+    ['sessionId'],
+    'low',
+    METHOD_POLICIES.pageRead
+  ),
+  'session.read': createRegistryEntry(
+    'session.read',
+    'session',
+    true,
+    ['sessionId', 'cursor', 'limit', 'waitMs'],
+    'low',
+    METHOD_POLICIES.pageRead
+  ),
+  'session.stop': createRegistryEntry(
+    'session.stop',
+    'session',
+    true,
+    ['sessionId'],
+    'moderate',
+    METHOD_POLICIES.automationInputDebugger
+  ),
+  'session.export': createRegistryEntry(
+    'session.export',
+    'session',
+    true,
+    ['sessionId', 'format'],
+    'moderate',
+    METHOD_POLICIES.automationInputDebugger
+  ),
+  'session.release': createRegistryEntry(
+    'session.release',
+    'session',
+    true,
+    ['sessionId'],
+    'low',
+    METHOD_POLICIES.automationInputDebugger
+  ),
 });
 
 /** @type {ReadonlyArray<import('./types.js').BridgeMethod>} */
@@ -876,6 +1099,7 @@ export const METHOD_SET = new Set(BRIDGE_METHODS);
 
 /** Methods whose read-only forms may run concurrently without side effects. */
 const BATCH_SAFE_METHODS = new Set([
+  'emulation.status',
   'webmcp.list_tools',
   'webmcp.get_tool',
   'health.ping',

package/packages/protocol/src/replay.js

@@ -0,0 +1,144 @@
+// @ts-check
+
+/** @typedef {{ frames: Array<{ at: number, data: string, width?: number, height?: number, tabId?: number }>, events: Array<Record<string, unknown>>, bodies?: Array<Record<string, unknown>>, gaps: number, dropped: number, replayMode?: string, memoryWindow?: boolean }} Replay */
+
+/** Offline renderer playback. Untrusted data is JSON text; only this fixed viewer script executes.
+ * @param {Replay} recording @returns {string} */
+export function renderReplay(recording) {
+  const gaps = Number.isSafeInteger(recording.gaps) ? recording.gaps : 0;
+  const dropped = Number.isSafeInteger(recording.dropped) ? recording.dropped : 0;
+  const nonce = crypto.randomUUID().replaceAll('-', '');
+  const frames = recording.frames
+    .filter((frame) => Number.isFinite(frame.at) && /^[A-Za-z0-9+/]+={0,2}$/u.test(frame.data))
+    .sort((a, b) => a.at - b.at);
+  const data = JSON.stringify({
+    frames,
+    clicks: recording.events.filter((event) => event.type === 'click'),
+  })
+    .replaceAll('<', '\\u003c')
+    .replaceAll('&', '\\u0026');
+  return `<!doctype html><html lang="en"><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src data:; script-src 'nonce-${nonce}'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'"><title>BBX renderer replay</title>
+<style>body{font:16px system-ui;background:#17212b;color:#fff;margin:24px}button,input{margin:8px}#stage{position:relative;display:inline-block;max-width:100%}img{max-width:100%;display:block}#click{position:absolute;width:24px;height:24px;border:3px solid #ff574a;border-radius:50%;transform:translate(-50%,-50%);display:none;pointer-events:none}input[type=range]{width:60%}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style>
+<h1>BBX renderer replay</h1><p>${gaps} capture gaps; ${dropped} dropped events.${recording.memoryWindow ? ' Retained memory window only; use the durable journal for the complete replay.' : ''} Frames represent visible pixels. External assets and page scripts are not loaded.</p>
+<div><button id="play">Play</button><select id="speed"><option value="0.5">0.5×</option><option value="1" selected>1×</option><option value="2">2×</option><option value="4">4×</option></select><input id="seek" type="range" min="0" max="1" step="1" value="0" aria-label="Replay time"><output id="time"></output></div>
+<div id="stage"><img id="frame" alt="Recorded renderer output"><span id="click"></span></div><details><summary>Activity and network events</summary><pre id="events"></pre></details>
+<script id="data" type="application/json" nonce="${nonce}">${data}</script><script id="timeline" type="application/json" nonce="${nonce}">${JSON.stringify(recording.events).replaceAll('<', '\\u003c').replaceAll('&', '\\u0026')}</script>
+<script nonce="${nonce}">
+const {frames,clicks}=JSON.parse(document.getElementById('data').textContent);
+const image=document.getElementById('frame'),seek=document.getElementById('seek'),play=document.getElementById('play'),dot=document.getElementById('click');
+document.getElementById('events').textContent=JSON.stringify(JSON.parse(document.getElementById('timeline').textContent),null,2);
+const start=frames[0]?.at||0,end=Math.max(start,frames.at(-1)?.at||0);seek.max=String(end-start);
+let playing=false,position=0,last=0,index=-1,raf=0;
+function show(){let low=0,high=frames.length-1,best=-1;while(low<=high){const mid=(low+high)>>1;if(frames[mid].at<=start+position){best=mid;low=mid+1}else high=mid-1}if(best>=0&&best!==index){index=best;image.src='data:image/jpeg;base64,'+frames[index].data}seek.value=String(position);document.getElementById('time').textContent=(position/1000).toFixed(1)+' / '+((end-start)/1000).toFixed(1)+' s';const f=frames[index];const c=clicks.findLast(c=>c.at<=start+position&&start+position-c.at<600&&(!f?.tabId||f.tabId===c.tabId));dot.style.display=c&&f?.width&&f?.height?'block':'none';if(c&&f?.width&&f?.height){dot.style.left=(100*c.x/f.width)+'%';dot.style.top=(100*c.y/f.height)+'%'}}
+play.onclick=()=>{cancelAnimationFrame(raf);playing=!playing;if(position>=end-start)position=0;play.textContent=playing?'Pause':'Play';last=performance.now();if(playing)raf=requestAnimationFrame(tick)};seek.oninput=()=>{position=Number(seek.value);show()};
+function tick(now){if(playing){position=Math.min(end-start,position+(now-last)*Number(document.getElementById('speed').value));show();if(position>=end-start){playing=false;play.textContent='Play'}}last=now;if(playing)raf=requestAnimationFrame(tick)}show();
+</script></html>`;
+}
+
+/** Recover complete records; report a partial tail instead of silently claiming a complete recording.
+ * @param {string} text @returns {Replay} */
+export function parseRecordingJournal(text) {
+  /** @type {Replay} */
+  const result = {
+    frames: [],
+    events: [],
+    bodies: [],
+    gaps: 0,
+    dropped: 0,
+    replayMode: 'renderer-stream',
+  };
+  const lines = text.split('\n');
+  /** @type {Map<number, number>} */
+  const eventIndexes = new Map();
+  let ended = false;
+  if (lines.pop()) result.gaps++;
+  for (const line of lines) {
+    if (!line) continue;
+    const entry = /** @type {Record<string, unknown>} */ (JSON.parse(line));
+    if (!entry || typeof entry !== 'object') throw new Error('Invalid journal record.');
+    if (
+      entry.kind === 'frame' &&
+      entry.frame &&
+      typeof entry.frame === 'object' &&
+      'data' in entry.frame &&
+      typeof entry.frame.data === 'string' &&
+      'at' in entry.frame &&
+      typeof entry.frame.at === 'number'
+    )
+      result.frames.push(/** @type {Replay['frames'][number]} */ (entry.frame));
+    else if (
+      (entry.kind === 'event' || entry.kind === 'event-update') &&
+      entry.event &&
+      typeof entry.event === 'object'
+    ) {
+      const event = /** @type {Record<string, unknown>} */ (entry.event);
+      const index =
+        entry.kind === 'event-update' && typeof event.seq === 'number'
+          ? eventIndexes.get(event.seq)
+          : undefined;
+      if (index !== undefined) result.events[index] = event;
+      else {
+        if (typeof event.seq === 'number') eventIndexes.set(event.seq, result.events.length);
+        result.events.push(event);
+      }
+    } else if (entry.kind === 'body' && entry.body && typeof entry.body === 'object')
+      result.bodies?.push(/** @type {Record<string, unknown>} */ (entry.body));
+    else if (entry.kind === 'end') {
+      ended = true;
+      result.gaps += Number(entry.gaps) || 0;
+      result.dropped = Number(entry.dropped) || 0;
+    }
+  }
+  if (!ended) result.gaps++;
+  result.events = correlateReplayEvents(result.events);
+  return result;
+}
+
+/** @template {Record<string, unknown>} T @param {T[]} events @returns {T[]} */
+export function correlateReplayEvents(events) {
+  /** @type {Map<unknown, T[]>} */
+  const tabs = new Map();
+  for (const event of events) {
+    if (
+      event.origin !== 'trusted-event' ||
+      !['click', 'input', 'change', 'submit'].includes(String(event.type)) ||
+      !Number.isFinite(event.at)
+    )
+      continue;
+    const list = tabs.get(event.tabId) ?? [];
+    list.push(event);
+    tabs.set(event.tabId, list);
+  }
+  for (const list of tabs.values()) list.sort((a, b) => Number(a.at) - Number(b.at));
+  return events.map((event) => {
+    if (
+      !['request', 'page-error', 'navigation'].includes(String(event.type)) ||
+      !Number.isFinite(event.at)
+    )
+      return event;
+    const actions = tabs.get(event.tabId) ?? [];
+    let low = 0,
+      high = actions.length - 1,
+      best = -1;
+    while (low <= high) {
+      const mid = (low + high) >> 1;
+      if (Number(actions[mid].at) <= Number(event.at)) {
+        best = mid;
+        low = mid + 1;
+      } else high = mid - 1;
+    }
+    const action = actions[best];
+    const deltaMs = Number(event.at) - Number(action?.at);
+    return action && deltaMs <= 2000
+      ? {
+          ...event,
+          correlation: {
+            actionSeq: action.seq,
+            deltaMs,
+            basis: 'same-tab-time-window',
+            causality: false,
+          },
+        }
+      : event;
+  });
+}

package/packages/protocol/src/summary.js

@@ -484,6 +484,55 @@ function summarizeBridgeResponseBody(response, method) {
       }),
     };
   }
+  if (method?.startsWith('emulation.')) {
+    return {
+      ok: true,
+      summary: `Emulation ${result.active ? 'active' : 'inactive'}; ${Array.isArray(result.pendingReset) ? result.pendingReset.length : 0} setting(s) retained.`,
+      evidence: result,
+    };
+  }
+  if (method === 'input.set_files') {
+    return {
+      ok: true,
+      summary: `File input ${result.assigned ? 'assigned' : 'not verified'}: ${result.count ?? 0} file(s).`,
+      evidence: result,
+    };
+  }
+  if (method?.startsWith('files.')) {
+    return {
+      ok: true,
+      summary: result.released
+        ? 'Staged file released.'
+        : `File staged: ${result.nextOffset ?? 0}/${result.size ?? 0} bytes.`,
+      evidence: result,
+    };
+  }
+  if (method === 'download.resource') {
+    return { ok: true, summary: 'Resource downloaded to a chunked artifact.', evidence: result };
+  }
+  if (method?.startsWith('download.')) {
+    return {
+      ok: true,
+      summary: result.released
+        ? 'Browser download handle released.'
+        : `Browser download ${result.state ?? 'updated'}: ${result.bytesReceived ?? 0}/${result.totalBytes ?? -1} bytes.`,
+      evidence: result,
+    };
+  }
+  if (method === 'input.paste_image') {
+    return {
+      ok: true,
+      summary: 'Native image paste dispatched. Verify insertion in the editor.',
+      evidence: result,
+    };
+  }
+  if (method?.startsWith('session.')) {
+    return {
+      ok: true,
+      summary: `Recording ${result.sessionId ?? ''}: ${result.released ? 'released' : result.delivery === 'artifact' ? 'exported' : result.active ? 'active' : 'stopped'}; ${result.gaps ?? 0} gap(s).`,
+      evidence: result,
+    };
+  }
   if (typeof result.daemon === 'string') {
     const access =
       result.access && typeof result.access === 'object'

package/packages/protocol/src/types.ts

@@ -96,6 +96,28 @@ export type ErrorCode =
   | 'TIMEOUT';
 
 export type BridgeMethod =
+  | 'session.start'
+  | 'session.journal_read'
+  | 'session.journal_delete'
+  | 'session.status'
+  | 'session.read'
+  | 'session.stop'
+  | 'session.export'
+  | 'session.release'
+  | 'files.stage'
+  | 'files.release'
+  | 'input.set_files'
+  | 'input.paste_image'
+  | 'download.resource'
+  | 'download.start'
+  | 'download.status'
+  | 'download.pause'
+  | 'download.resume'
+  | 'download.cancel'
+  | 'download.release'
+  | 'emulation.apply'
+  | 'emulation.status'
+  | 'emulation.reset'
   | 'webmcp.list_tools'
   | 'webmcp.get_tool'
   | 'webmcp.execute_tool'
@@ -214,6 +236,8 @@ export interface BridgeMeta {
   stale_recovery?: 'success' | 'failure';
   /** Agent session for sticky working-tab routing; unset callers share a default. */
   agent_session?: string;
+  /** Set by the daemon on routed requests; caller values are always overwritten. */
+  transport_owner?: string;
   /** Tab the request ran in. */
   tab_id?: number;
   /** How the tab was chosen: explicit tabId, the agent's working tab, or the active tab. */
@@ -1077,7 +1101,7 @@ export type ExtractContentConsistency = 'best_effort' | 'settled';
 export type ExtractContentSource = 'readability' | 'semantic-root' | 'body';
 export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
 export type ScreenshotDelivery = 'auto' | 'inline' | 'artifact';
-export type ArtifactKind = 'screenshot' | 'har';
+export type ArtifactKind = 'screenshot' | 'har' | 'resource';
 
 export interface ExtractContentParams {
   format?: ExtractContentFormat;
@@ -1124,6 +1148,18 @@ export interface ArtifactDescriptor<K extends ArtifactKind = ArtifactKind> {
 }
 
 export interface ScreenshotMetadata {
+  context?: {
+    startedAt: string;
+    capturedAt: string;
+    tabId: number;
+    tabActive: boolean | null;
+    windowFocused: boolean | null;
+    visibility: 'visible' | 'hidden' | null;
+    documentFocused: boolean | null;
+    rectSpace: 'viewport-css' | 'document-css';
+    pageClip: { x: number; y: number; width: number; height: number; scale: number };
+    source: 'cdp-renderer';
+  };
   mimeType: `image/${ScreenshotFormat}`;
   format: ScreenshotFormat;
   byteLength: number;

package/packages/protocol/src/workflows.ts

@@ -0,0 +1,22 @@
+import type { BridgeParams } from './types.js';
+
+export interface EmulationConfig extends BridgeParams {
+  device?: {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    mobile: boolean;
+    touch: boolean;
+  };
+  network?: { offline: boolean; latencyMs: number; downloadKbps: number; uploadKbps: number };
+  cpuRate?: number;
+  locale?: string;
+  timezoneId?: string;
+  geolocation?: { latitude: number; longitude: number; accuracy: number };
+}
+
+export interface CdpControllerDependencies {
+  acquire: (tabId: number) => Promise<void>;
+  release: (tabId: number) => Promise<void>;
+  send: (tabId: number, method: string, params: Record<string, unknown>) => Promise<unknown>;
+}

package/skills/browser-bridge/SKILL.md

@@ -87,6 +87,16 @@ have taken effect or finish after dismissal. Inspect postconditions first.
 
 ### Interact & Patch
 
+For device, network, CPU, locale, timezone, or geolocation reproduction, use the [emulation workflow](references/emulation.md). Discover its compact methods with `bbx protocol describe emulation`.
+
+For uploads and authenticated downloads, use the [file workflow](references/files.md). `bbx upload` streams local file bytes without putting base64 in model context.
+
+For repeatable tasks, record semantic locators and verified outcomes in a [task playbook](references/playbooks.md).
+
+Screenshot coordinate spaces and loaded extension build identifiers are described in [capture context](references/capture-context.md).
+
+For opt-in activity watch, network bodies/messages, and sampled visual replay, use the [recording workflow](references/recording.md).
+
 ```bash
 bbx click <ref> [button]             # click element
 bbx focus <ref>                      # focus element

package/skills/browser-bridge/references/capture-context.md

@@ -0,0 +1,9 @@
+# Capture and runtime identity
+
+Screenshot results include `context` with capture timestamps, tab ID, tab activity, window focus, document visibility/focus, and coordinate spaces. `null` means the lookup was unavailable. These flags are sampled before capture and do not prove that the user saw the image.
+
+`rectSpace` is `viewport-css` for region requests and `document-css` for element and full-page requests. `pageClip` is the document-space CSS rectangle sent to CDP after adding the visual viewport offset. `dimensions` describes encoded image pixels. Use these fields when relating a screenshot to DOM boxes. A renderer screenshot can capture a background tab.
+
+`health.ping` includes `loadedBuild` for the selected extension. `workerId` and `startedAt` identify its running service-worker instance. Packaged releases also include `sourceDigest`, a SHA-256 digest of the sorted staged paths and bytes before the build stamp is generated. Unpackaged checkouts report `null`. The stamp identifies the packaged sources; it is not a cryptographic attestation of the browser or machine.
+
+After replacing an extension package, check both `extensionVersion` and `loadedBuild`. A different worker ID confirms a worker restart, while the source digest distinguishes packaged builds with the same version. Re-discover the connection ID after reload.

package/skills/browser-bridge/references/emulation.md

@@ -0,0 +1,18 @@
+# Environment emulation
+
+Use `emulation.apply` to reproduce a device layout or environmental failure. Settings merge per tab and hold a debugger session until reset or detach. `emulation.status` is a compact read and never attaches a debugger.
+
+```bash
+bbx call --tab 123 emulation.apply '{"device":"phone","network":"slow-3g","cpuRate":4}'
+bbx call --tab 123 navigation.reload '{}'
+bbx call --tab 123 emulation.status '{}'
+bbx call --tab 123 emulation.reset '{}'
+```
+
+Device presets are `phone`, `tablet`, and `desktop`. Override metrics with `{"device":{"preset":"phone","width":412}}`. Presets change viewport, DPR, and touch. They do not turn Chrome into Safari.
+
+Network presets are `offline`, `slow-3g`, `fast-3g`, `wifi`, and `unthrottled`. Explicit fields are `offline`, `latencyMs`, `downloadKbps`, and `uploadKbps`; throughput `-1` means unthrottled. Reload when testing page loading.
+
+Other settings are `locale`, `timezoneId`, `cpuRate`, and `geolocation:{latitude,longitude,accuracy}`. Geolocation overrides do not grant website permissions. Locale changes Intl formatting; they do not rewrite request headers.
+
+Reset after the experiment. A partial application can still have changed the tab. Reset attempts every owned setting and reports `failures` and `pendingReset`; retry cleanup if needed. Window-access cleanup also resets emulation. An external debugger detach clears ownership and cancels stale cleanup commands. While device emulation owns viewport metrics, change them through `emulation.apply.device` or reset emulation before calling `viewport.resize`.

package/skills/browser-bridge/references/files.md

@@ -0,0 +1,50 @@
+# Files
+
+Keep binary bytes out of model context. For agent-local files, the CLI reads and streams bounded chunks to the selected browser machine, assigns the completed handles once, then releases staging memory:
+
+```bash
+bbx upload --tab 123 --extension CONNECTION 'input[type=file]' ./report.pdf
+bbx upload --remote office --tab 123 '#attachments' ./report.pdf ./chart.png
+```
+
+Files can be at most 16 MiB each and 32 MiB combined. The protocol equivalents are `files.stage`, `input.set_files`, and `files.release`, available through `browser_call`. `files.stage` returns only a handle, size, next offset, completion, and expiry. Handles are bound to the tab, access grant, agent session, and daemon connection. They expire after five minutes and are invalidated by worker restart. Keep multi-call transfers on one connection, such as the CLI upload helper or a persistent MCP client. After an uncertain chunk result, start a fresh transfer; never blindly replay the assignment.
+
+For files already on the browser machine, use Chrome's native file-input operation without transferring bytes. It accepts a unique top-document selector and browser-local absolute paths, including files larger than the staging limit:
+
+```bash
+bbx call --tab 123 input.set_files '{"target":{"selector":"input[type=file]"},"paths":["/Users/me/Downloads/report.pdf"]}'
+```
+
+Staged assignment also accepts BBX element refs, including refs obtained inside frames. Empty `files:[]` clears the selection. `assigned:true` means the input accepted the files; wait for the application's upload-complete result before proceeding.
+
+Authenticated downloads use the tab's fetch context and BBX's existing chunked artifacts. Browser CORS/CSP rules apply; this needs no additional extension permissions:
+
+```bash
+bbx call --tab 123 download.resource '{"url":"https://example.com/export"}'
+bbx download --tab 123 --extension CONNECTION 'https://example.com/export' ./report.csv
+```
+
+The default size ceiling is 8 MiB and the maximum is 16 MiB. Streaming stops when decoded bytes exceed the limit, even without a Content-Length header. `timeoutMs` defaults to 30 seconds and can be at most 60 seconds. The result contains an artifact descriptor, never file bytes. Retrieve it with `artifact.read` on the same connection, or use `bbx download` to fetch, verify the SHA-256 checksum, and save it in one command. Artifacts are deleted when the owning connection closes. Remote destinations still require an encrypted tunnel, such as SSH, for transport confidentiality.
+
+## Browser-native downloads
+
+Use `download.start` for large files or URLs that page fetch cannot read. Chrome streams directly to the browser machine's Downloads directory, without BBX's artifact size limit. This uses the `downloads` permission. Browser authentication, download safety checks, disk limits, and server resume support still apply.
+
+```bash
+bbx call --tab 123 --extension CONNECTION download.start '{"url":"https://example.com/export","filename":"export.zip"}'
+bbx call --tab 123 --extension CONNECTION download.status '{"downloadId":"HANDLE"}'
+bbx call --tab 123 --extension CONNECTION download.pause '{"downloadId":"HANDLE"}'
+bbx call --tab 123 --extension CONNECTION download.resume '{"downloadId":"HANDLE"}'
+bbx call --tab 123 --extension CONNECTION download.cancel '{"downloadId":"HANDLE"}'
+bbx call --tab 123 --extension CONNECTION download.release '{"downloadId":"HANDLE"}'
+```
+
+Treat `downloadId` as a secret capability. It works across CLI invocations in the same tab and access grant, and survives an extension worker restart. BBX exposes no general browser download-history search. `status` returns bytes received/total, state, pause/resume availability, and the browser-local filename. `saveAs:true` opens Chrome's save dialog; the default does not. Filenames must be single relative names, and collisions are uniquified. Release is allowed only after completion/cancellation and never deletes the file. Access revocation or tab closure cancels retained downloads. Completed handles expire after 24 hours when a new download prunes them. At most 32 handles are retained.
+
+## Trusted image paste
+
+```bash
+bbx paste-image --tab 123 --extension CONNECTION '[contenteditable=true]' ./chart.png
+```
+
+The helper stages one PNG, focuses the editor, writes the image to the real system clipboard, dispatches Chrome's native paste command, and releases staging memory. MCP can use `files.stage`, `input.paste_image` with `target` and `transferId`, then `files.release` on one connection. The browser window and tab must already be focused, and the target must be an editable control in the top document. BBX revalidates focus before clipboard writing and before paste. No clipboard-read or extra clipboard permission is requested. This overwrites the clipboard. Inspect insertion before submitting; never automatically replay after uncertainty or focus loss.