@browserbridge/bbx 1.7.8 → 1.9.0

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`, `dom.get_accessibility_tree`, `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
 
@@ -25,14 +25,16 @@ Avoid debugger-backed methods until they are clearly necessary. In Browser Bridg
 5. **Need layout metrics?** → `layout.get_box_model` (no budget needed)
 6. **Need styles?** → `styles.get_computed` with explicit `properties` list
 7. **Need runtime errors?** → `page.get_console` with `level: 'error'`
-8. **Need full page text?** → `page.get_text` (cheaper than `dom.query` on body)
-9. **Need API call history?** → `page.get_network` (intercepted fetch/XHR log)
-10. **Need framework/app state and no lighter read can expose it?** → `page.evaluate` (debugger-backed)
-11. **Need semantic structure and role/text queries are insufficient?** → `dom.get_accessibility_tree` (debugger-backed)
-12. **Need performance data?** → `performance.get_metrics` (debugger-backed)
-13. **Testing responsive with an exact forced viewport?** → `viewport.resize` (debugger-backed)
-14. **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)
-15. **Content-script blocked?** → `cdp.get_document` or `cdp.get_dom_snapshot` (debugger-backed fallback)
+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 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
 
@@ -57,7 +59,7 @@ Omitting allowlists or leaving the text budget wide open often returns 3–5× t
 | Screenshot before structured read        | ~1500 tok wasted    | Always `dom.query` or `styles.get_computed` first                                            |
 | Re-querying DOM for same element         | ~500 tok/call       | Reuse `elementRef` from prior result                                                         |
 | Full-page screenshot                     | ~3000 tok           | Use `screenshot.capture_element`, or `screenshot.capture_region` with a tight rect           |
-| Requesting all computed styles           | ~800 tok            | Set `properties` list (usually 3–8 props)                                                    |
+| Requesting broad computed styles via CDP | ~800 tok            | Use `styles.get_computed`; omission returns five core props, or pass 3-8 explicit props      |
 | Multiple CLI calls for independent reads | overhead/call       | Use `batch` command                                                                          |
 | Guessing selectors for known labels      | ~300 tok wasted/try | Use `dom.find_by_text` or `dom.find_by_role`                                                 |
 | Polling page state with repeated queries | ~500 tok/poll       | Use `dom.wait_for` (single call, waits async)                                                |
@@ -68,6 +70,9 @@ Omitting allowlists or leaving the text budget wide open often returns 3–5× t
 | Guessing interactive elements from DOM   | ~600 tok/try        | Use `dom.get_accessibility_tree` for semantic roles                                          |
 | 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
 
@@ -107,11 +112,12 @@ Install early - the buffer auto-activates on first call. Captured levels: log, w
 
 ## Page Text Instead of DOM Scan
 
-When you need the page's visible text - for summarization, search, or content extraction - use `page.get_text` instead of `dom.query` on `body`:
+When you need every visible UI label, use `page.get_text` instead of `dom.query` on `body`. For articles, documentation, or long issues, prefer `page.extract_content` so navigation and repeated chrome are removed first:
 
 ```bash
 bbx page-text           # default 8000 char budget
 bbx page-text 8000      # larger budget for long pages
+bbx call page.extract_content '{"format":"markdown","textBudget":8000}'
 ```
 
 This is 3–5× cheaper than querying the body's subtree with `dom.query`.
@@ -127,15 +133,25 @@ bbx network 50           # last 50 entries
 
 The interceptor auto-installs on first call. Before reproducing an event, call `page.get_network` once with `clear: true` to install capture and remove old entries. Trigger the action, then read again without `clear`. Each entry shows `method`, `url`, `status`, `duration`.
 
+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:
 
 ```bash
-bbx a11y-tree 30 3       # 30 nodes, depth 3
+bbx call dom.get_accessibility_tree '{"maxNodes":30,"maxDepth":4,"interactiveOnly":true}'
 ```
 
-Returns role/name/interactive flag per node. Much cheaper than screenshot + OCR, and more accurate than `dom.query` on generic selectors.
+Filtering before `maxNodes` makes compact/interactive-only output much cheaper than screenshot + OCR. AX depth is always partial and `interactive` is semantic metadata, not current actionability; use role/name to find a DOM ref before input.
 
 ## Semantic finding Saves Selector Guessing