@browserbridge/bbx 1.8.0 → 1.9.0

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

@@ -27,7 +27,7 @@ The table below includes the legacy capability bucket for each method so agents
 - `-` means the method is global/system-scoped and was never gated by a former capability bucket.
 - Capability names are descriptive coverage labels only. Browser Bridge access is window-scoped now; there are no capability-scoped sessions.
 
-## All Methods (67)
+## All Methods (75)
 
 | Method                             | Tab? | CDP?       | Group       | Capability           | Notes                                                                                      |
 | ---------------------------------- | ---- | ---------- | ----------- | -------------------- | ------------------------------------------------------------------------------------------ |
@@ -39,18 +39,20 @@ The table below includes the legacy capability bucket for each method so agents
 | `skill.get_runtime_context`        | No   | -          | system      | `-`                  | Live budget presets and method groups                                                      |
 | `setup.get_status`                 | No   | -          | system      | `-`                  | Global MCP config and CLI skill install status                                             |
 | `setup.install`                    | No   | -          | system      | `-`                  | Install or uninstall MCP/skill integration targets                                         |
-| `health.ping`                      | No   | -          | system      | `-`                  | Connectivity, enabled-window routing, debugger, and capture state                          |
+| `health.ping`                      | No   | -          | system      | `-`                  | Connectivity, routing, capture, and daemon/routed-extension recovery summaries             |
 | `log.tail`                         | No   | -          | system      | `-`                  | Recent redacted bridge logs                                                                |
-| `daemon.metrics`                   | No   | -          | system      | `-`                  | Daemon health and performance metrics                                                      |
+| `daemon.metrics`                   | No   | -          | system      | `-`                  | Daemon health, performance, and process-local recovery metrics                              |
 | `page.get_state`                   | Yes  | -          | page        | `page.read`          | URL, readiness, focus, viewport, and observable dialog status                              |
 | `page.evaluate`                    | Yes  | CDP        | page        | `page.evaluate`      | JS expression in page context; last resort                                                 |
 | `page.get_console`                 | Yes  | -          | page        | `page.read`          | Buffered console messages; filter by `level`, `limit`                                      |
 | `page.handle_dialog`               | Yes  | CDP        | page        | `navigation.control` | Inspect or explicitly accept/dismiss the currently observable dialog                       |
 | `page.wait_for_load_state`         | Yes  | -          | wait        | `page.read`          | Wait for truthful tab `complete` state and/or a URL condition                              |
-| `page.get_storage`                 | Yes  | -          | page        | `page.read`          | `localStorage`/`sessionStorage`; optional `keys`                                           |
+| `page.get_storage`                 | Yes  | -          | page        | `page.read`          | Bounded storage key/presence metadata; optional `keys`; never values                        |
+| `sensitive.read`                   | Yes  | -          | sensitive   | `sensitive.read`     | One exact local/session storage key; sequential, non-retryable, whole-or-error              |
 | `page.get_text`                    | Yes  | -          | page        | `page.read`          | Full page text; `textBudget` limits size                                                   |
 | `page.extract_content`             | Yes  | -          | page        | `page.read`          | Node-processed semantic text/Markdown with bounded HTML snapshots and optional settlement   |
 | `page.get_network`                 | Yes  | Conditional | page        | `network.read`       | Fetch/XHR by default; explicit CDP all-resource capture lifecycle                          |
+| `network.export_har`               | Yes  | No*        | page        | `network.read`       | Read an already armed CDP capture as bounded metadata-only HAR 1.2                         |
 | `network.intercept.add`            | Yes  | CDP        | page        | `network.intercept`  | Add interception rule; action fulfill/continue/block                                       |
 | `network.intercept.remove`         | Yes  | CDP        | page        | `network.intercept`  | Remove rule by `ruleId`                                                                    |
 | `network.intercept.list`           | Yes  | CDP        | page        | `network.intercept`  | List active rules (rules drop on debugger detach)                                          |
@@ -60,6 +62,10 @@ The table below includes the legacy capability bucket for each method so agents
 | `navigation.go_back`               | Yes  | -          | navigate    | `navigation.control` | History back                                                                               |
 | `navigation.go_forward`            | Yes  | -          | navigate    | `navigation.control` | History forward                                                                            |
 | `dom.query`                        | Yes  | -          | inspect     | `dom.read`           | Query subtree with budget constraints                                                      |
+| `dom.baseline.create`              | Yes  | -          | inspect     | `dom.read`           | Retain a short-lived memory-only semantic snapshot; sequential only                        |
+| `dom.baseline.compare`             | Yes  | -          | inspect     | `dom.read`           | Compare current semantic DOM to an explicit retained baseline; batch-safe                  |
+| `dom.baseline.describe`            | Yes  | -          | inspect     | `dom.read`           | Return exact baseline scope, options, expiry, and snapshot statistics; batch-safe          |
+| `dom.baseline.release`             | Yes  | -          | inspect     | `dom.read`           | Idempotently release retained baseline state; sequential only                              |
 | `dom.describe`                     | Yes  | -          | inspect     | `dom.read`           | Single element details via `elementRef`                                                    |
 | `dom.get_text`                     | Yes  | -          | inspect     | `dom.read`           | Text content with `textBudget`                                                             |
 | `dom.get_attributes`               | Yes  | -          | inspect     | `dom.read`           | Targeted attribute read                                                                    |
@@ -87,18 +93,24 @@ The table below includes the legacy capability bucket for each method so agents
 | `screenshot.capture_element`       | Yes  | CDP        | capture     | `screenshot.partial` | Complete element screenshot with explicit completeness metadata                            |
 | `screenshot.capture_region`        | Yes  | CDP        | capture     | `screenshot.partial` | Cropped viewport region in PNG, JPEG, or WebP                                               |
 | `screenshot.capture_full_page`     | Yes  | CDP        | capture     | `screenshot.partial` | Full document screenshot; fails coherently above Chrome capture limits                     |
+| `artifact.read`                    | No   | daemon     | raw         | None                 | Read one bounded chunk from an owner-scoped artifact handle                                 |
+| `artifact.delete`                  | No   | daemon     | raw         | None                 | Delete an owner-scoped artifact handle                                                      |
 | `patch.apply_styles`               | Yes  | -          | patch       | `patch.styles`       | Reversible CSS patch; `verify` returns computed result                                     |
-| `patch.apply_dom`                  | Yes  | -          | patch       | `patch.dom`          | Reversible DOM mutation; `verify` returns result                                           |
+| `patch.apply_dom`                  | Yes  | -          | patch       | `patch.dom`          | Reversible text, attribute, add/remove/toggle-class mutation; `verify` returns result       |
 | `patch.list`                       | Yes  | -          | patch       | `patch.dom`          | Active rollback records in the current document                                            |
 | `patch.rollback`                   | Yes  | -          | patch       | `patch.dom`          | Revert one active patch                                                                    |
 | `patch.commit_session_baseline`    | Yes  | -          | patch       | `patch.dom`          | Keep current mutations and discard their rollback history                                  |
 | `performance.get_metrics`          | Yes  | CDP        | performance | `performance.read`   | Chrome performance counters                                                                |
 | `cdp.get_document`                 | Yes  | CDP        | cdp         | `cdp.dom_snapshot`   | DevTools document tree                                                                     |
-| `cdp.get_dom_snapshot`             | Yes  | CDP        | cdp         | `cdp.dom_snapshot`   | DevTools DOM snapshot                                                                      |
+| `cdp.get_dom_snapshot`             | Yes  | CDP        | cdp         | `cdp.dom_snapshot`   | DevTools DOM snapshot; optional bounded `computedStyles` property names                     |
 | `cdp.get_box_model`                | Yes  | CDP        | cdp         | `cdp.box_model`      | DevTools-backed element geometry                                                           |
 | `cdp.get_computed_styles_for_node` | Yes  | CDP        | cdp         | `cdp.styles`         | DevTools-backed computed styles                                                            |
 | `cdp.dispatch_key_event`           | Yes  | CDP        | cdp         | `cdp.input`          | DevTools keyDown/keyUp without foreground focus                                            |
 
+`No*` means HAR export issues no CDP command itself, but its source capture must
+already be armed and continues to hold debugger ownership until explicitly
+stopped.
+
 ## CLI
 
 ```bash
@@ -108,7 +120,7 @@ bbx call --tab 123 <method> '{...}'         # explicit tab target inside enabled
 bbx batch '[{"method":"...","params":{}}]'  # parallel calls
 ```
 
-**Convenience shortcuts:** `access-request`, `dom-query`, `describe`, `text`, `styles`, `box`, `click`, `focus`, `type`, `press-key`, `cdp-press-key`, `patch-style`, `patch-text`, `patches`, `rollback`, `screenshot`, `eval`, `console`, `wait`, `find`, `find-role`, `html`, `hover`, `navigate`, `storage`, `tab-create`, `tab-close`, `page-text`, `network`, `a11y-tree`, `perf`, `scroll`, `resize`, `reload`, `back`, `forward`, `attrs`, `matched-rules`
+**Convenience shortcuts:** `access-request`, `dom-query`, `describe`, `text`, `styles`, `box`, `click`, `focus`, `type`, `press-key`, `cdp-press-key`, `patch-style`, `patch-text`, `patches`, `rollback`, `screenshot`, `har`, `eval`, `console`, `wait`, `find`, `find-role`, `html`, `hover`, `navigate`, `storage`, `tab-create`, `tab-close`, `page-text`, `network`, `a11y-tree`, `perf`, `scroll`, `resize`, `reload`, `back`, `forward`, `attrs`, `matched-rules`
 
 Newer bridge methods such as `input.scroll_into_view` and `screenshot.capture_full_page` currently use the raw path: `bbx call <method> '{...}'`.
 
@@ -181,7 +193,7 @@ bbx call page.wait_for_load_state '{"url":"/dashboard","urlMatch":"contains","wa
 
 ### page.get_storage
 
-Read `localStorage` or `sessionStorage` entries. Values truncated at 500 chars each.
+Read bounded `localStorage` or `sessionStorage` key/presence metadata. Values are never returned.
 
 ```bash
 bbx storage                        # all localStorage
@@ -189,6 +201,17 @@ bbx storage session token,user     # specific sessionStorage keys
 bbx call page.get_storage '{"type":"session","keys":["token"]}'
 ```
 
+### sensitive.read
+
+Deliberately read one exact Web Storage value after discovering its key. The
+value bypasses token truncation, is never batched or automatically retried, and
+is returned whole or rejected whole. Every attempt creates a Sensitive access
+Recent Activity warning without retaining the key or value.
+
+```bash
+bbx call sensitive.read '{"source":"session_storage","key":"token"}'
+```
+
 ### dom.query
 
 Run a bounded breadth-first DOM summary rooted at a selector or existing ref. Returns `{nodes, revision, truncated, registrySize}` and may also include `_registryPruned: true` when the element registry evicted older refs.
@@ -200,6 +223,23 @@ bbx call dom.query '{"selector":"main","maxNodes":10,"attributeAllowlist":["clas
 
 If `_registryPruned` is true, refresh previously cached refs before reusing them.
 
+### dom.baseline.create, compare, describe, and release
+
+Use an explicit semantic baseline when an action must be verified against a known before-state without returning two full DOM snapshots. Baselines retain bounded structured summaries in extension memory only; they do not add attributes, scripts, or markers to the application page.
+
+```bash
+bbx call dom.baseline.create '{"selector":"main","maxNodes":100,"maxDepth":8,"textBudget":160,"attributeAllowlist":["data-testid"]}'
+bbx call dom.baseline.compare '{"baselineId":"baseline_...","maxChanges":50}'
+bbx call dom.baseline.describe '{"baselineId":"baseline_..."}'
+bbx call dom.baseline.release '{"baselineId":"baseline_..."}'
+```
+
+The create result is a destination-bound opaque handle plus creation/expiry timestamps, window/tab/frame/document/selector/representation scope, effective capture options, and snapshot counts. It never returns retained nodes. `compare` reports exact `added`, `removed`, `changed`, `moved`, `unchanged`, and total counts while bounding returned examples with `maxChanges`; ambiguity and omitted evidence are explicit. `describe` returns the exact descriptor. `release` is idempotent.
+
+Creation and release are stateful and excluded from read-only batch. Compare and describe do not mutate the baseline or extend its five-minute expiry, so they are batch-safe. Navigation, document replacement, tab/window cleanup, access disable, destination disconnect, expiry, quota eviction, or explicit release makes the handle unavailable. Navigation and document replacement return `DOM_BASELINE_INVALIDATED`; missing, expired, released, or evicted handles return `DOM_BASELINE_NOT_FOUND`.
+
+Capture defaults to stable semantic fields and safe attributes. Form values and event-handler attributes are never retained, URL credentials/fragments/query values are removed, opaque URL payloads are redacted, and caller-provided attribute names are canonicalized and bounded. Use a narrow selector for dialogs, forms, lists, or application regions.
+
 ### dom.wait_for
 
 Wait for a DOM condition using MutationObserver + 250 ms polling fallback. A text-only wait searches all elements. `hidden` succeeds when no matching visible element remains, including when it is absent. Returns `{found, elementRef, duration}`.
@@ -359,6 +399,42 @@ bbx call page.get_network '{"source":"cdp","capture":"stop"}'
 
 CDP URL output removes credentials and fragments, replaces every query value with `[redacted]`, and summarizes data/blob URLs. Request/response bodies, cookies, authorization values, and complete headers are not returned. This mode captures all observed resource classes and is materially more expensive and intrusive than fetch/XHR instrumentation; always stop it when finished.
 
+### network.export_har
+
+Export metadata-only HAR 1.2 from a CDP capture that is currently armed. The
+method is a read and does not attach, start, stop, clear, or otherwise change the
+capture. Use this exact sequence:
+
+```bash
+bbx call page.get_network '{"source":"cdp","capture":"start"}'
+# reproduce the activity
+bbx har --limit 100 --url-pattern /api/ reproduction.har
+bbx call page.get_network '{"source":"cdp","capture":"stop"}'
+```
+
+Parameters are `limit` (1-200, default 50), `urlPattern` (at most 2048
+characters; substring match on sanitized URLs), and `delivery` (`auto` default,
+`inline`, or `artifact`). Count and inline byte/token limits retain the newest
+matching entries and remove complete oldest entries; fields are not truncated to
+fit. `auto` uses an artifact above 256 KiB, while explicit `artifact` always
+returns one. Artifacts last five minutes, are readable/deletable only by their
+requesting client, use private daemon files, and expose no browser-host path.
+
+HAR URLs preserve schemes, hosts, paths, and query names, remove credentials and
+fragments, and replace query values with `[redacted]`. `queryString`, headers,
+and cookies are empty; bodies and authorization data are absent. Unsupported
+header/body/content sizes and send/wait/receive timing phases are `-1`.
+`entry.time` is observed total duration. Redirects are separate observed entries;
+`_bbx` reports resource type, failure reason, and memory/disk/prefetch cache and
+service-worker observations. Result counters expose completed-entry loss as
+`dropped`, discarded unfinished activity as `abandoned`, and requests still
+unfinished and omitted from the HAR as `inflight`.
+
+MCP uses `browser_page` with `action: "har"`. `bbx har` accepts the same limit,
+URL pattern, and delivery choices, then uses one client connection to download
+owner-scoped chunks, verify byte length/SHA-256 and HAR shape, delete the
+artifact, and atomically write the output on the CLI host.
+
 ### dom.get_accessibility_tree
 
 Retrieve a depth-limited accessibility tree via CDP. Full reads use `Accessibility.getFullAXTree`; an optional unique `selector` resolves through CDP DOM methods and uses `Accessibility.getPartialAXTree`, retaining only the selected subtree and required ancestor chain. Missing and ambiguous selectors return typed errors instead of selecting an arbitrary candidate. Nodes include `role`, `name`, `description`, `value`, state fields, `interactive`, `semanticInteractive`, `focusable`, `focusableAndEnabled`, `ignored`, and `childIds`. `interactive` is semantic/focusability metadata, not current pointer actionability.
@@ -389,7 +465,9 @@ bbx call viewport.resize '{"reset":true}'
 
 ### performance.get_metrics
 
-Read Chrome performance counters via CDP `Performance.getMetrics`. Returns a flat `{metrics}` object with keys like `JSHeapUsedSize`, `LayoutCount`, `TaskDuration`, etc.
+Read a browser-maintained point sample of raw Chrome counters via CDP `Performance.getMetrics`. The additive result is `{metrics, measurement}`, where `measurement` identifies the CDP source, `timeTicks` domain, sample timestamp, point-sample observation, and `webVitals: "not_measured"`. Metric names, availability, and units are defined by Chrome/CDP and can vary by browser version.
+
+BBX does not establish a navigation observation window and does not measure LCP, CLS, or INP. Do not interpret the returned counters as Web Vitals or page-load measurements.
 
 Debugger-backed. Use after lighter reads fail to explain a performance symptom.
 
@@ -400,16 +478,40 @@ bbx call performance.get_metrics
 
 ### screenshot.capture_\*
 
-Capture a complete element, a tight viewport region, or a full document. All methods accept `format: "png" | "jpeg" | "webp"`; JPEG and WebP additionally accept integer `quality` from 0 to 100. Results include matching `format`, `mimeType`, `complete`, and `clipped` metadata.
+Capture a complete element, a tight viewport region, or a full document. All methods accept `format: "png" | "jpeg" | "webp"`, `scale` from 0.1 to 4, and `delivery: "inline" | "artifact" | "auto"`; JPEG and WebP additionally accept integer `quality` from 0 to 100. Results include matching `format`, `mimeType`, encoded `byteLength`, actual `dimensions`, `complete`, `clipped`, and `delivery` metadata.
 
 Element capture uses full page-coordinate bounds with CDP capture beyond the viewport. If Browser Bridge cannot guarantee the entire element, or if an element/page exceeds Chrome capture limits, it returns a typed failure rather than a viewport-clipped image labeled complete. Use full-page capture only when element or tight region captures cannot express the issue.
 
-Raw calls return base64 JSON. Prefer `bbx screenshot [--format png|jpeg|webp] [--quality 0-100] <ref> [outPath]` when one element is enough; the CLI chooses or validates the output extension from the encoding.
+Raw calls default to inline base64 for compatibility. `auto` keeps small captures inline and returns a short-lived, daemon-owned opaque artifact handle for large captures; explicit `inline` preserves MCP image content when model vision is needed. Artifact handles expose no browser-host path and support owner-scoped bounded `artifact.read` and `artifact.delete` calls. Prefer `bbx screenshot [--format png|jpeg|webp] [--quality 0-100] <ref> [outPath]` when one element is enough; the CLI downloads, verifies, deletes, and atomically writes the artifact on the CLI host.
+
+Artifact handles expire after five minutes and can be read or deleted only by
+the requesting client. The daemon creates a private artifact directory and
+owner-only files on POSIX hosts, removes artifacts on expiry/teardown, and never
+returns its browser-host filesystem path.
 
 ```bash
-bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75}'
+bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75,"delivery":"auto","scale":0.75}'
 ```
 
+## Recovery Telemetry
+
+Recovery telemetry is process-local and uses fixed five-second buckets over a
+five-minute window. Three failures for the same hidden group within 60 seconds
+set `activeLoop` for that category. Public summaries always use only these fixed
+categories: `automatic_mcp_retry`, `stale_ref_recovery`, `debugger_reattach`,
+`content_script_reinjection`, `native_host_reconnect`, and `request_outcome`.
+They contain attempts/successes/failures/pending, bounded rates, saturation,
+last-event timestamps, and loop flags, but no page data, URL, selector, payload,
+error text, method name, tab identifier, or internal group name.
+
+`health.ping` includes daemon and available routed-extension summaries;
+`daemon.metrics` includes daemon scope. `bbx doctor` combines both, marks active
+loops as issues, and emits fixed guidance. Stop repeated attempts: re-query stale
+refs, close competing debuggers, reload extension/page after reinjection
+failures, restart for native-host reconnect failures, stop automatic MCP retry
+loops, or inspect the first typed error for request failures. Extension data
+resets with the service worker and daemon data resets with the daemon.
+
 ## Request Envelope
 
 ```json
@@ -433,6 +535,9 @@ bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75}'
 | `ELEMENT_NOT_ACTIONABLE`     | Inspect hidden/disabled/inert/zero-size target                 | `retry: false`, use `dom.describe`           |
 | `ELEMENT_OBSCURED`           | Inspect the element blocking the target point                  | `retry: false`, use `layout.hit_test`        |
 | `ELEMENT_NOT_FOUND`          | Correct or narrow the selector                                 | `retry: false`, use `dom.query`              |
+| `DOM_BASELINE_NOT_FOUND`     | Handle expired, released, evicted, or does not exist           | `retry: false`, create a new baseline        |
+| `DOM_BASELINE_INVALIDATED`   | Navigation, document, or access scope changed                  | `retry: false`, create a new baseline        |
+| `DOM_BASELINE_QUOTA_EXCEEDED` | Snapshot or retained-state quota was exceeded                 | `retry: false`, narrow selector or release   |
 | `INPUT_UNSUPPORTED`          | Use DOM execution or a CDP-supported input method              | `retry: false`                               |
 | `INPUT_INVALID_TARGET`       | Choose a control compatible with the input                     | `retry: false`, use `dom.describe`           |
 | `INPUT_FOCUS_CHANGED`        | Inspect focus handlers; do not replay native text blindly      | `retry: false`, use `dom.describe`           |
@@ -442,7 +547,6 @@ bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75}'
 | `NATIVE_HOST_UNAVAILABLE`    | Check daemon: `bbx status`                                     | `retry: false`                               |
 | `EXTENSION_DISCONNECTED`     | Extension not connected to daemon                              | `retry: true` after 3 s, check `health.ping` |
 | `TIMEOUT`                    | Wait/evaluate exceeded `timeoutMs`                             | `retry: true` after 1 s                      |
-| `RATE_LIMITED`               | Too many requests                                              | `retry: true` after 2 s                      |
 
 Timeout on content-script request → use narrower `dom.query` or CDP fallback.
 Timeout on navigation → increase `timeoutMs`, set `waitForLoad:false`, or check `page.get_state`.

package/skills/browser-bridge/references/token-efficiency.md

@@ -14,7 +14,7 @@ These presets are also available at runtime via `bbx skill`.
 
 ## Debugger Policy
 
-Avoid debugger-backed methods until they are clearly necessary. In Browser Bridge, `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, CDP network capture, CDP input execution, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and `cdp.*` attach `chrome.debugger`, which can make Chrome show its native debugging banner across the running browser instance.
+Avoid debugger-backed methods until they are clearly necessary. In Browser Bridge, `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, CDP network capture, CDP input execution, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and `cdp.*` attach `chrome.debugger`, which can make Chrome show its native debugging banner across the running browser instance. `network.export_har` does not attach by itself, but it requires the explicit CDP capture to remain armed.
 
 ## Decision Tree
 
@@ -28,12 +28,13 @@ Avoid debugger-backed methods until they are clearly necessary. In Browser Bridg
 8. **Need article or documentation content?** → `page.extract_content` (removes navigation and repeated chrome)
 9. **Need all visible page UI text?** → `page.get_text` (cheaper than `dom.query` on body)
 10. **Need API call history?** → default `page.get_network` (intercepted fetch/XHR log)
-11. **Need framework/app state and no lighter read can expose it?** → `page.evaluate` (debugger-backed)
-12. **Need semantic structure and role/text queries are insufficient?** → compact or interactive-only `dom.get_accessibility_tree` (debugger-backed)
-13. **Need performance data?** → `performance.get_metrics` (debugger-backed)
-14. **Testing responsive with an exact forced viewport?** → `viewport.resize` (debugger-backed)
-15. **Visual ambiguity after structured reads?** → `screenshot.capture_element` first, or `screenshot.capture_region` with a tight crop when one element is not enough (debugger-backed)
-16. **Content-script blocked?** → `cdp.get_document` or `cdp.get_dom_snapshot` (debugger-backed fallback)
+11. **Need portable all-resource evidence?** → explicitly arm CDP, reproduce, `network.export_har`, then stop capture
+12. **Need framework/app state and no lighter read can expose it?** → `page.evaluate` (debugger-backed)
+13. **Need semantic structure and role/text queries are insufficient?** → compact or interactive-only `dom.get_accessibility_tree` (debugger-backed)
+14. **Need a raw Chrome/CDP counter point sample?** → `performance.get_metrics` (debugger-backed; no BBX navigation window or LCP/CLS/INP measurement)
+15. **Testing responsive with an exact forced viewport?** → `viewport.resize` (debugger-backed)
+16. **Visual ambiguity after structured reads?** → `screenshot.capture_element` first, or `screenshot.capture_region` with a tight crop when one element is not enough (debugger-backed)
+17. **Content-script blocked?** → `cdp.get_document` or `cdp.get_dom_snapshot` (debugger-backed fallback)
 
 ## Allowlist Strategy
 
@@ -70,6 +71,7 @@ Omitting allowlists or leaving the text budget wide open often returns 3–5× t
 | Fetching network via evaluate hacks      | ~400 tok            | Use `page.get_network` (auto-interceptor)                                                    |
 | Full a11y tree with no limits            | ~3000 tok           | Set `maxNodes` ≤ 50, `maxDepth` ≤ 4                                                          |
 | CDP network capture for API-only traffic | debugger lifecycle  | Use default fetch/XHR capture; reserve CDP for all-resource failures                         |
+| Broad inline HAR export                  | token/byte pressure | Narrow `urlPattern`/`limit`, or use `delivery: "artifact"`; bounds remove whole entries      |
 | Repeated page-state polling for a route  | ~500 tok/poll       | Use one event-aware `page.wait_for_load_state` URL condition                                 |
 
 ## Efficient Loop
@@ -133,6 +135,14 @@ The interceptor auto-installs on first call. Before reproducing an event, call `
 
 Only escalate to `source: "cdp"` when fetch/XHR misses the relevant document, asset, socket, cache, redirect, or failed-resource metadata. CDP must be started before reproduction and explicitly stopped afterward; it holds debugger ownership, tracks in-flight state, and returns a larger entry shape. Its URLs redact credentials, fragments, and query values, and it never returns bodies, cookies, authorization values, or complete headers.
 
+For a HAR, export while that capture is still armed, then stop it. Use a narrow
+sanitized-URL `urlPattern` and small `limit` first. Inline delivery removes whole
+oldest entries to meet byte/token bounds rather than truncating fields; inspect
+`truncation`, `dropped`, `abandoned`, and `inflight`. Use `delivery: "artifact"`
+for larger evidence. The five-minute opaque handle is owner-scoped and has no
+browser-host path; `bbx har` downloads, verifies, deletes, and atomically writes
+it on the CLI host through the same client.
+
 ## Accessibility Tree for Semantic Discovery
 
 When you need to understand the page's interactive structure without guessing selectors: