lazycodex-ai 5.0.0-beta.85 → 5.0.0-beta.87

package/packages/shared-skills/skills/browser/references/commands.md

@@ -1,90 +1,105 @@
-# Command semantics
+# Session methods
 
-Everything here cost a failed attempt to learn. Read it before improvising.
+`connectBrowserSkill()` returns a `BskSession`. Every method is one call on the BrowserSkill
+daemon's tool surface; options are the daemon's parameter names in camelCase.
 
 ## Sessions
 
-```bash
-bsk session start --json --no-focus --name "<task>"   # keep session_id
-bsk session list
-bsk session stop <id> --json                          # positional id, not --session
+```js
+const session = await omowright.connectBrowserSkill({ name: "<task>", focused: false, browser: "<instance id>", width: 1200, height: 800 })
+session.sessionId            // four letters, e.g. "ckhg"
+session.browserInstanceId    // which connected browser owns the Agent Window
+await session.stop()         // ALWAYS, on success and failure
 ```
 
-Every session-scoped command needs `--session <id>`. `--no-focus` keeps the Agent Window from
-stealing focus; drop it only when the user is watching on purpose.
+`browser` is needed only when more than one browser is connected (`bskDoctor()` lists them).
+`focused: false` keeps the Agent Window from stealing focus; drop it only when the user is watching
+on purpose. Throws `BskRpcError` `no_browser_connected` when no extension is attached — that is a
+stop, not a cue to launch something else.
 
-## Reading
+## Targets
 
-| Command | Returns |
+| Form | Meaning |
 |---|---|
-| `observe --session <id>` | semantic tree with `@eN` refs and perception probes — **the default read** |
-| `snapshot --session <id>` | static accessibility tree |
-| `get-html --session <id>` | exact markup, hidden metadata |
-| `screenshot --session <id> --out <path>` | PNG; add `--full-page` for a long capture |
-| `evaluate "<js>" --session <id> --json` | `{ok, value}` — **check `.ok`; exit code 0 does not mean the script succeeded** |
-| `console` / `network` | buffered log lines and responses |
+| `"@e3"` / `"e3"` | a ref from the last `observe()` / `snapshot()` |
+| `"#login > button"` | a CSS selector, resolved live |
+| `{ captureId, x, y }` | a point in a screenshot, from `screenshot()` |
+| `css.e3` from `bskSnapshot` | the light-DOM CSS path of an OmOWright ref (`null` inside shadow roots — use the daemon ref instead) |
 
-**Refs are reissued by every `observe` and `snapshot`.** Read a ref and act on it in the same
-cycle. A ref captured two calls ago silently addresses a different element — this is how a click
-lands on the neighbouring row.
+## Reading
 
-`observe --max-tokens <n>` bounds a large page. There is no default cap.
+| Call | Returns |
+|---|---|
+| `bskSnapshot(session, { interactive, maxDepth })` | `{ tree, refs, css }` — the OmOWright accessibility tree with refs, computed in the page **without** leaving a global or touching the DOM |
+| `session.observe({ maxTokens, cursor, probeHover })` | the daemon's semantic tree (`@vom`) with `@eN` refs, layers and hover probes — **the default read for shadow DOM and iframes** |
+| `session.snapshot({ maxDepth, maxTokens })` | the daemon's plain accessibility tree |
+| `session.getHtml({ ref, maxBytes })` | exact markup |
+| `session.screenshot({ ref })` / `screenshot({ fullPage: true })` | `{ buffer, width, height, captureId }`; full-page captures stream back in chunks |
+| `session.evaluate(expression, { awaitPromise, timeoutMs })` | `{ ok, value, error }` — **check `.ok`**; a resolved promise does not mean the script succeeded |
+| `session.console({ since })` / `session.network({ since })` | buffered console entries / request metadata (no bodies) |
+
+**Refs are reissued by every read.** Read a ref and act on it in the same cycle. A ref captured
+two calls ago silently addresses a different element — this is how a click lands on the
+neighbouring row.
 
 ## Acting
 
-| Need | Command |
+| Need | Call |
 |---|---|
-| Click | `click @e3 --session <id>` |
-| Fill | `fill @e3 --value "text" --session <id>` |
-| Select | `select @e3 --value "<option value>" --session <id>` |
-| Key | `press Enter --ref @e3 --session <id>` |
-| Hover | `hover @e3 --session <id>` |
-| Scroll into view | `scroll-to @e3 --session <id>` |
-| Wheel | `wheel --delta-y 600 --session <id>` |
-| Focus / blur | `focus @e3` / `blur @e3` |
-| Upload / download | `upload --file <path>` / `download --out <path>` |
+| Click | `session.click(target, { button, clickCount, modifiers })` |
+| Fill | `session.fill(target, value, { clearBefore })` |
+| Select | `session.select(target, ["<option value>"])` |
+| Key | `session.press("Enter", { target, modifiers, holdMs })` |
+| Hover | `session.hover(target, { settleMs })` |
+| Scroll into view | `session.scrollTo(target)` |
+| Wheel | `session.wheel({ deltaY: 600, target })` |
+| Focus / blur | `session.focus(target)` / `session.blur(target)` |
+| Navigate | `session.navigate(url, { waitUntil: "load" \| "domcontentloaded" \| "networkidle" \| "commit", timeoutMs })`, `back()`, `forward()`, `reload({ hard })`, `waitForNavigation()` |
+| Window | `session.resize(width, height)`, `session.emulate({ overrides: { width, mobile } })` |
 
 Traps:
 
 - `select` takes the option's **value attribute**, not its visible label.
-- `fill` and `click` accept a CSS selector; **`press --ref` does not** — it answers
-  `ref_not_found` for a selector. `press` without `--ref` goes to the focused node.
-- A menu that a `click` opens can be toggled shut by that same click. `focus` then
-  `press Enter` opens it reliably.
-- Hover-only controls report `element not visible`: hover the trigger, observe, then act on the
-  revealed item's fresh ref. Markers like `[has-submenu]` and `[expanded]` identify triggers;
-  `observe --probe-hover` finds one when no marker does, at the cost of touching the live page.
-- The clipboard is unavailable in a window started `--no-focus` (no document focus), so read
-  values out of the DOM instead.
-
-## Borrowing a user tab
-
-```bash
-bsk tab list --scope user
-bsk tab borrow <tab-id>
-bsk tab return <tab-id>
+- `press` without `target` goes to the focused node; `press` with a CSS selector is fine, but a
+  daemon ref must come from the current read.
+- A menu that a `click` opens can be toggled shut by that same click. `focus` then `press("Enter")`
+  opens it reliably.
+- Hover-only controls report `element not visible`: hover the trigger, read again, then act on the
+  revealed item's fresh ref. `observe({ probeHover: true })` finds one when no marker does, at the
+  cost of touching the live page.
+- The clipboard is unavailable in a window started `focused: false`, so read values out of the DOM.
+
+## Tabs
+
+```js
+const { tabs } = await session.tabList({ scope: "user" })   // "user" | "agent" | "all"
+await session.tabBorrow(tabId)                                // the user confirms in the browser (60 s)
+await session.tabReturn(tabId)                                // stop() returns anything still borrowed
+await session.tabCreate({ url }); await session.tabSelect(id); await session.tabClose(id)
+```
+
+Never invent tab ids and never repeat a denied borrow.
+
+## Humans
+
+```js
+const { outcome } = await session.requestHelp({ prompt, title, targets: ["@e4"], completionCriteria, timeoutMs })
+// outcome: "completed" | "continued" | "cancelled" | "timed_out" | "navigated" | "disabled"
 ```
 
-Borrowing asks the user to confirm. Never invent a tab id, never repeat a denied borrow, and
-always return what you borrowed (`session stop` also returns them).
+## Errors
 
-## Failures
+Every refusal is a `BskRpcError` with the daemon's own `code`:
 
-| Symptom | Meaning | Response |
+| `code` | Meaning | Do |
 |---|---|---|
-| `browsers: []` | extension not connected | ask the user to open the browser / enable the extension |
-| daemon missing | idle exit or reboot | none; the next call restarts it |
-| `cdp_failed: Cannot access a chrome-extension:// URL of different extension` | another extension injected a frame, so the debugger cannot attach to that tab | transient and page-specific; collapse the work into one `evaluate` and retry, or navigate away and back |
-| `permission_denied: element not visible` | hover-gated or clipped control | drive its menu instead |
-| `ref_not_found` | stale ref, or a selector passed to `press` | observe again; use a real ref |
-| version skew warning | CLI and extension disagree | `bsk update` after finishing sessions; the extension updates through its store |
-
-**Two identical failures select a different approach. A third identical attempt is a defect.**
-
-## Sandboxed hosts
-
-If the host kills background children after each command, the daemon cannot survive between calls.
-Set `BSK_AUTO_START=0`, share one `BSK_HOME` across every call, and start
-`bsk daemon start --foreground` in the host's persistent background task. Check readiness with
-`bsk status --json` in a separate call before continuing. Do not loop on launches, delete runtime
-files, or restart a daemon another task is using.
+| `no_browser_connected` | no extension attached | run the onboarding script, relay the human step, wait |
+| `not_found` | stale ref or unknown session | read again; if the session is gone, start a new one |
+| `invalid_params` | wrong option shape | fix the call, do not retry as-is |
+| `permission_denied` | `evaluate` on a tab outside the Agent Window, or a denied borrow | stop; the user said no |
+| `timeout` | the tool did not finish in its budget | read the page state before retrying once |
+| `user_aborted` | the user pressed Stop in the browser | stop the task and report |
+| `cdp_failed` | the page cannot be attached (restricted URL, DevTools open) | say which page and why |
+
+Long calls can be cancelled: `const h = session.client.callWithHandle("tool.navigate", {...})`
+then `await session.client.cancel(h.rpcId)`.

package/packages/shared-skills/skills/browser/references/install.md

@@ -1,71 +1,68 @@
 # Installing the attached engine
 
-Three pieces. The agent can install exactly one of them.
+Three pieces. The onboarding script prepares all three; a human finishes exactly one.
 
 | Piece | Channel | Automatable |
 |---|---|---|
 | `bsk` CLI + daemon | upstream installer, GitHub Releases | **yes** |
-| Browser extension | Chrome Web Store / Edge Add-ons | **no — a human clicks Install** |
-| Daemon process | auto-starts on any `bsk` call | nothing to do |
+| Browser extension | registered from the Web Store listing through Chrome's external-extension mechanism | **yes, up to one click** — the browser asks the user to enable it |
+| Daemon process | auto-starts on the first call | nothing to do |
 
 ## Supported
 
 | | |
 |---|---|
 | Operating systems | macOS (Apple Silicon and Intel), Linux (x64, ARM64), Windows x64 |
-| Browsers | Chrome, Microsoft Edge. Other Chromium browsers work where they accept store builds. |
+| Browsers | Chrome, Microsoft Edge, Brave, Chromium — any profile the doctor lists under `browsersDetected` |
 
-## 1. The CLI
+## One command
 
 ```bash
-node "<skill-root>/scripts/browser-install.mjs"
+node "<skill-root>/scripts/browser-install.mjs" [--json] [--wait-ms=180000]
 ```
 
-That wraps upstream's official installer:
+In order it: runs upstream's official `install.sh` / `install.ps1` into `~/.local/bin` (any PATH
+line the installer appends to a shell rc file is reverted — the library calls the binary by
+absolute path); starts the daemon with `bsk status`; and, for every Chromium-family profile it
+finds, registers the Web Store listing as an external extension:
 
-```bash
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
-export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
-
-# Windows (PowerShell)
-irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
-```
-
-The Unix installer cannot change its parent shell's `PATH`. A shell opened before the install may
-still miss it, so either re-export in each call or use the absolute path (`$HOME/.local/bin/bsk`,
-`bsk.exe` on Windows). Verify with `bsk --version`.
+| Platform | Where the entry goes | The user's one step |
+|---|---|---|
+| macOS | `<user data dir>/External Extensions/<id>.json` | quit the browser completely, open it again, click **Enable** in the dialog |
+| Windows | `HKCU\Software\<vendor>\<browser>\Extensions\<id>` (`reg add`, no admin) | click **Enable** on the toolbar badge; no restart |
+| Linux (Chromium) | `<user data dir>/External Extensions/<id>.json` | relaunch; installs without a prompt |
+| Linux (Chrome / Edge / Brave) | `/opt/google/chrome/extensions/<id>.json` and siblings — root only | otherwise open the store link it prints and click **Add** |
 
-## 2. The extension
+The script prints that step as `humanStep`. **Relay it verbatim and wait**; with `--wait-ms` it
+keeps polling the daemon until the extension connects. An empty `browsersConnected` afterwards is
+not a failure to work around — the browser is closed or the user has not clicked yet; say which
+and ask.
 
-Give the user the listing for their browser and wait:
+If the user removed the extension from the browser before, Chrome blocklists its id for external
+installs. The script detects that (`reason: "blocklisted"`) and prints the store link instead:
 
 - Chrome: https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi
 - Edge: https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg
 
-Then confirm it landed:
-
-```bash
-bsk status --json     # a non-empty "browsers" array means connected
-```
-
-An empty `browsers` list is not a failure to work around. Either the browser is closed or the
-extension is not enabled; say which and ask.
+Enterprise force-install policies are deliberately not used: they brand the browser "managed by
+your organization" and the user cannot remove the extension.
 
-## 3. Do not install upstream's skill
+## Do not install upstream's skill
 
 Upstream ships its own agent skill through `bsk install-skill`. **Do not run it here.** This
 package already provides the skill, and upstream's copy installs under a different name into the
 user skill directory, which takes precedence over a shipped skill — two descriptions of the same
-CLI, one of them shadowing the one that knows about this package's recipes and helper scripts.
+engine, one of them shadowing the one that knows about omowright and this package's scripts.
 
 ## Diagnosing
 
 ```bash
-node "<skill-root>/scripts/browser-doctor.mjs"          # this package's view
+node "<skill-root>/scripts/browser-doctor.mjs" --json   # this package's view: cli, daemon, profiles, registrations, connections
 bsk doctor                                              # upstream's own checks
 bsk logs                                                # daemon log
 ```
 
-The daemon exits about ten minutes after the last browser disconnects and is not a system service,
-so a reboot also stops it. Both heal on the next `bsk` call — no repair needed.
+The daemon exits about ten minutes after the last browser disconnects and is not a system
+service, so a reboot also stops it. Both heal on the next call — `connectBrowserSkill()` starts it
+unless `BSK_AUTO_START=0` (sandboxes that reap background processes keep the daemon on the host
+and share `BSK_HOME`; see upstream's sandboxed-agents guide).

package/packages/shared-skills/skills/browser/references/owned-engine/README.md

@@ -1,11 +1,33 @@
 # The owned engine
 
-A browser **your code launches and owns**, driven over CDP, with its own profile. The opposite of
-the attached engine: no user logins, full control.
-
-**This package ships no such engine.** These documents describe the contract and the technique, so
-that a locally installed CDP library — or a script you write against one — is driven correctly.
-If no owned engine is installed, say so and stay on the attached engine.
+A browser **your code launches and owns**, driven over CDP by omowright with its own profile. The
+opposite of the attached engine: no user logins, full control.
+
+```js
+const { omowright } = await loadOmowright()
+const profile = mkdtempSync(join(tmpdir(), "omowright-"))
+const browser = await omowright.connectPipe({
+  browserPath: "<CloakBrowser or chrome-headless-shell binary>",
+  browserArgs: ["--headless", "--no-first-run", `--user-data-dir=${profile}`],
+  storageRoot: profile,
+  dialogPolicy: { accept: true },
+})
+try {
+  const page = await browser.newTab("https://example.com/")
+  const tree = omowright.compactSnapshot(await page.snapshot())   // ALWAYS compact before a model reads it
+  await page.locator("e3").click()                                 // refs come straight from the snapshot
+  await Bun.write("shot.png", await page.screenshot())
+} finally {
+  await browser.close()
+  rmSync(profile, { recursive: true, force: true })                // paired: a leftover profile is a logged-in browser nobody watches
+}
+```
+
+`connectPipe` launches over `--remote-debugging-pipe`: no listening port, stdio drained, the
+process reaped on `close()`. `connect("http://127.0.0.1:<port>")` attaches to a browser something
+else launched. `connectCloakProfile({ profileDir })` launches CloakBrowser with a pinned
+fingerprint seed — the stealth path for WAF and bot-scored targets, where the attached engine's
+console capture would be a signal.
 
 ## When it is the right engine
 
@@ -16,27 +38,25 @@ If no owned engine is installed, say so and stay on the attached engine.
 | Solving a challenge widget programmatically | needs coordinate control and OCR |
 | Reading the network instead of the DOM | needs request interception on your own target |
 | A QA flight trace (steps, HAR, screenshots) | recording someone's real session is not acceptable |
+| Headless or unattended runs | the user's browser is on their desk |
 
 For anything that needs the user's login, the attached engine wins. For extracting text from a
 blocked URL, neither: use the `ultimate-browsing` skill.
 
-## What an owned engine must give you
+## The page
 
-1. A transport that opens no listening port (launch over a pipe), or an explicit local CDP endpoint.
-2. An accessibility snapshot with stable in-page refs, and a **compact** form that drops the ref
-   map before the tree reaches a model — on a real page that map is roughly half the bytes and the
-   client never reads it.
-3. Locators that resolve those refs in-page, including refs inside cross-origin frames.
-4. Coordinate input, for what locators cannot address.
-5. A dialog policy, so `alert` / `confirm` / `beforeunload` can never block a run.
+`OmOPage` is Playwright-shaped: `goto`, `snapshot`, `locator(ref | css)`, `click`, `fill`,
+`press`, `hover`, `check`, `selectOption`, `dragTo`, `setInputFiles`, `screenshot`, `pdf`,
+`evaluate`, `waitForURL`, `keyboard`, `mouse`, `frameLocator`. A snapshot is an accessibility tree
+with virtual refs (`[ref=e3]`, cross-origin frames as `f1e3`); `compactSnapshot()` drops the refs
+map, about half the bytes. Readiness is a content probe (body plus interactive elements, landmarks
+or text), not a timer; `goto(url, { waitUntil: "commit" })` is the escape hatch for empty pages.
 
 ## Reference
 
-- [ladder.md](ladder.md) — the escalation ladder, viewport pinning, coordinate control, challenge widgets
-- [network.md](network.md) — read the network instead of the DOM; traces and request interception
-- [frames-and-humans.md](frames-and-humans.md) — cross-origin frames, overlays, dialogs, human handoff
-
-## Cleanup is paired
+- [ladder.md](ladder.md) — the escalation ladder, viewport pinning, `createCua`, `createCaptcha`
+- [network.md](network.md) — `createNetworkSnoop`, `collectWhileScrolling`, `createTrace`, `createRoutes`
+- [frames-and-humans.md](frames-and-humans.md) — `snapshotWithFrames`, `describeLayers`, dialog policy, `emulate`, `requestHuman`
 
-Close the browser and remove the profile directory in the same `finally`. A profile left behind is
-a logged-in browser nobody is watching.
+The library's own skill (`skills/omowright/SKILL.md` and `presets/*` in the omowright repository)
+is the authoritative, longer treatment of each; these pages are the routing summary.

package/packages/shared-skills/skills/browser/references/owned-engine/frames-and-humans.md

@@ -2,38 +2,51 @@
 
 ## Cross-origin frames and shadow DOM
 
-A cross-origin iframe is a separate target with its own snapshot. Reconcile the child trees into
-the parent so one tree describes the whole page, and address child elements through the page-level
-ref — never by fetching a frame handle first. Shadow roots are traversed by the snapshot engine;
-they are not a special case for you.
+A cross-origin iframe is a separate target with its own snapshot. `snapshotWithFrames(page)`
+reconciles the child trees into the parent so one tree describes the whole page, and reports
+`missingFrames` for any it could not enter; address child elements through the page-level ref
+(`f1e3`) — never by fetching a frame handle first. Shadow roots are traversed by the snapshot
+engine; they are not a special case for you.
 
 ## Overlays that swallow clicks
 
 Two identical misses on an element that is clearly visible usually means something invisible sits
 on top: a consent banner, a modal backdrop, a sticky header, a full-viewport tracking layer.
-Describe the layers at the click point before you retry. Either the overlay is named — dismiss it
-and continue — or nothing is reported, which means the miss has another cause and you climb the
-ladder instead.
+`describeLayers(page)` names the topmost fixed or sticky element covering the viewport, and
+`snapshotWithLayers(page)` prefixes a snapshot with `@layers blocking=<role> "<name>"` when one
+exists. Either the overlay is named — dismiss it and continue — or `@layers none`, which means the
+miss has another cause and you climb the ladder instead.
 
 ## Dialogs never block
 
-`alert`, `confirm`, `prompt`, and `beforeunload` must be answered by a policy set when the
-browser is created, not by a listener you hope registers in time. Default to accepting
-(`confirm` true, `prompt` empty). A run that hangs on an unhandled dialog looks exactly like a
-hang with no cause, which is the most expensive kind to diagnose.
+`alert`, `confirm`, `prompt`, and `beforeunload` are answered by the `dialogPolicy` passed to
+`connectPipe` (or `browser.setDialogPolicy`), at the protocol layer, before the page sees them.
+Default to accepting (`{ accept: true }`; a function receives `{ type, message }` and returns
+`{ accept, promptText }`). `page.on("dialog")` still fires for observability. A run that hangs on
+an unhandled dialog looks exactly like a hang with no cause, which is the most expensive kind to
+diagnose.
 
 ## Device emulation
 
-Emulating a device is viewport plus user agent plus touch, applied together. Changing only the
-viewport produces a desktop page at a phone size, which is not what you are testing. Re-read the
-viewport after emulating, and re-pin coordinates.
+`emulate(page, "iphone-14")` applies viewport, device scale factor, user agent and touch together;
+changing only the viewport produces a desktop page at a phone size, which is not what you are
+testing. `emulate(page, null)` restores. Re-read the viewport after emulating, and re-pin
+coordinates.
 
 ## Handing the page to a human
 
 When every rung fails on a login, a one-time code, or a challenge you cannot clear, the human is
-the fallback, not the failure. Bring the tab to the front, state plainly what needs doing, and
-wait on a **condition** — the URL changed, the element appeared — with a bounded timeout, rather
-than on a fixed delay.
-
-Respect the answer. A cancelled or timed-out handoff is a stop, and the correct response is to
-report which rung failed with what evidence. Working around the user's refusal is never correct.
+the fallback, not the failure:
+
+```js
+const { outcome } = await omowright.requestHuman(page, {
+  prompt: "Please finish the sign-in in this window.",
+  until: { url: /\/dashboard/ },          // or { selector } or async (page) => boolean
+  timeoutMs: 300_000,
+})
+```
+
+It brings the window to the front, shows a banner with a Done button, and waits on a
+**condition** with a bounded timeout rather than a fixed delay. Respect the answer: `timed_out`
+or `cancelled` is a stop, and the correct response is to report which rung failed with what
+evidence. Working around the user's refusal is never correct.

package/packages/shared-skills/skills/browser/references/owned-engine/ladder.md

@@ -5,12 +5,12 @@ defect.** The failure itself selects the next rung; never pause to ask which.
 
 | Rung | Use | Climb when |
 |---|---|---|
-| 1. snapshot + locator(ref) | anything with a usable ref | the ref is absent, stale, obscured, or the click lands on the wrong node twice |
-| 1b. layer description | a blocking overlay explains two identical misses | no overlay is reported, or it is gone and the click still misses |
-| 2. coordinates | canvas, extension popups, custom controls, drag surfaces | the click misses, or the screenshot and the coordinates disagree |
-| 3. pin the viewport, redo rung 2 | coordinate drift after a resize, a DPI change, or a foreign tab | coordinates land correctly but the widget still refuses input |
-| 4. the challenge widget | a challenge is the blocker | it clears and the flow still stalls |
-| 5. read the browser log | a browser-level failure | the log names a cause outside the page |
+| 1. `page.snapshot()` + `page.locator(ref)` | anything with a usable ref | the ref is absent, stale, obscured, or the click lands on the wrong node twice |
+| 1b. `snapshotWithLayers(page)` / `describeLayers(page)` | a blocking overlay explains two identical misses | `@layers none`, or the overlay is gone and the click still misses |
+| 2. `createCua(page)` coordinates | canvas, extension popups, custom controls, drag surfaces | the click misses, or the screenshot and the coordinates disagree |
+| 3. pin the viewport (`emulate(page, "desktop-1440")` / `repinViewport`), redo rung 2 | coordinate drift after a resize, a DPI change, or a foreign tab | coordinates land correctly but the widget still refuses input |
+| 4. `createCaptcha(page)` | a challenge is the blocker | it clears and the flow still stalls |
+| 5. read the browser log (`browser.close()` surfaces the stdio tail) | a browser-level failure | the log names a cause outside the page |
 
 **Rung 5 ends in a written diagnosis, never a speculative code change.** A missing entitlement, a
 dead extension service worker, an unavailable authenticator — none of those is fixed by editing
@@ -18,38 +18,40 @@ automation code.
 
 ## Pin the viewport before trusting any coordinate
 
-Coordinate input acts in viewport pixels. When the render surface and the coordinate space
+`createCua(page)` acts in viewport pixels. When the render surface and the coordinate space
 disagree, every coordinate is off by the same constant and retrying just repeats the miss. Set the
-device metrics explicitly (width, height, `deviceScaleFactor`, and a matching viewport), re-read
-the page's viewport size, then take a **fresh** screenshot. Coordinates read off an unpinned
-screenshot are stale. Pin every page you act on, including tabs you did not open.
+device metrics explicitly (`emulate` applies width, height, `deviceScaleFactor` and touch
+together), re-read the page's viewport size, then take a **fresh** `cua.getVisibleScreenshot()`.
+Coordinates read off an unpinned screenshot are stale. Pin every page you act on, including tabs
+you did not open (`createAgentTabs` re-pins on create).
 
 ## Refs
 
 - Refs die on every new snapshot. Pass a ref straight from the latest snapshot; never reuse one
   across snapshots and never put one in a CSS selector.
-- Refs stay page-level. A child-frame ref still resolves through the page, so you never fetch a
-  frame handle to click inside an iframe.
-- Always compact a snapshot before sending it to a model.
+- Refs stay page-level. A child-frame ref (`f1e3`) still resolves through `page.locator`, so you
+  never fetch a frame handle to click inside an iframe.
+- Always `compactSnapshot()` before sending a snapshot to a model.
 
 ## Challenge widgets
 
 A challenge is an obstacle on the path, not a stop sign: clear it, confirm it cleared, continue.
-Three shapes, three techniques:
+`createCaptcha(page)` gives three techniques:
 
-- **Checkbox** (the common embedded widgets): the control lives in a nested frame, so address it
-  by viewport coordinates.
-- **Slider / puzzle**: drag along a path with enough intermediate steps that the motion reads as
-  human. Raise the step count before you change the endpoints.
-- **Text or number**: OCR the region. On macOS the system vision framework is the cheapest
-  accurate option; elsewhere pass your own OCR function or a vision model.
-- **Image grid**: annotate a screenshot, then click per cell.
+- **Checkbox** (the common embedded widgets): the control lives in a nested frame, so
+  `captcha.click(bounds)` addresses it by viewport coordinates.
+- **Slider / puzzle**: `captcha.drag(from, to, { steps })` with enough intermediate steps that the
+  motion reads as human. Raise the step count before you change the endpoints.
+- **Text or number**: `captcha.readText(bounds)` OCRs the region — the macOS Vision framework by
+  default, or pass your own `ocr` function or a vision model.
+- **Image grid**: annotate a screenshot, then click per cell with `createCua`.
 
 **Bounds measured against an unpinned viewport are wrong by a constant offset.** If clicks have
 been landing wrong, drop to rung 3 first, then re-read the bounds.
 
 Verify with a fresh snapshot that the challenge is gone. Verification is part of the action, not a
-separate optimistic assumption.
+separate optimistic assumption. When every technique fails on a page a real browser passes, the
+engine is the variable: relaunch through `connectCloakProfile()`.
 
 ## Delegating the pixel loop
 

package/packages/shared-skills/skills/browser/references/owned-engine/network.md

@@ -6,37 +6,57 @@ next week. Watching traffic costs nothing on a target you own, and the page cann
 
 **Snoop before you scrape.** Scroll-and-parse is the fallback, not the default.
 
+```js
+const snoop = omowright.createNetworkSnoop(page, { maxBodyBytes: 512 * 1024 })
+await page.goto(url)
+const hit = await snoop.waitFor({ url: /\/api\/search/, mimeType: "application/json" }, { timeoutMs: 10_000 })
+const rows = snoop.popJson()                 // every buffered JSON body, drained
+console.log(snoop.summary({ max: 20 }))      // one line per request: method status mime size url
+snoop.dispose()
+```
+
 ## Wait for a request, never for a clock
 
-A fixed sleep is a guess that fails on a slower machine and wastes time on a faster one. Subscribe
-to the response you expect **before** triggering the action, then await that signal with a bounded
-timeout. This is the same rule that governs test code, for the same reason.
+A fixed sleep is a guess that fails on a slower machine and wastes time on a faster one.
+`snoop.waitFor(match)` subscribes to the response you expect **before** you trigger the action,
+then awaits it with a bounded timeout. This is the same rule that governs test code, for the same
+reason.
 
 ## Collecting through infinite scroll
 
-Drive scroll and extraction as a generator: scroll, collect what is new, stop on a target count or
-a scroll ceiling. Bound both, so a page that keeps producing cannot run forever.
+```js
+for await (const batch of omowright.collectWhileScrolling(page, snoop, { minItems: 200, maxScrolls: 10, extract: (json) => json.items })) {
+  items.push(...batch)
+}
+```
+
+Scroll, collect what is new, stop on a target count or a scroll ceiling. Bound both, so a page
+that keeps producing cannot run forever.
 
 ## Flight traces
 
-For QA evidence, record a trace: one entry per step with before/after screenshots, the network
-log, and console output, written as a line-delimited log plus an HAR. That triple is what makes a
-failure reconstructable afterwards instead of re-runnable-in-theory.
+For QA evidence, `createTrace(page, { dir })` records one entry per `trace.step(name, fn)` with
+before/after screenshots, the network log and console output, written as `trace.jsonl` plus
+`trace.har` (`toHar` builds the HAR from snoop entries). That triple is what makes a failure
+reconstructable afterwards instead of re-runnable-in-theory. Call `trace.stop()` in `finally`.
 
 Cap recorded body sizes. An untrimmed trace of a media-heavy page is mostly bytes nobody reads.
 
 ## Request interception
 
-Route matching by glob, regular expression, or predicate lets you stub an endpoint, fail one
-request to test an error path, or block third-party noise. Enable interception on the first route
-and disable it on dispose — leaving it on slows every later navigation.
+`createRoutes(page)` matches by glob, regular expression, or predicate and lets a handler
+`continue`, `fulfill({ status, body })` or `abort()`: stub an endpoint, fail one request to test an
+error path, block third-party noise. Interception is enabled on the first route and disabled on
+`dispose()` — leaving it on slows every later navigation and changes the timing fingerprint, so
+prefer passive snooping on bot-scored targets.
 
 ## Cookies
 
-Injecting a cookie export into your own profile is legitimate for ordinary sessions and useless
-for the ones you most want: accounts whose risk engines bind a session to a device will invalidate
-it, and a password manager's session is tab-bound and never portable. Sanitize what you do inject
-(drop expired entries, keep host-prefixed cookies secure and root-scoped).
+`injectCookies(page, cookies)` sanitizes what it injects (drops expired entries, keeps
+host-prefixed cookies secure and root-scoped). Injecting an export into your own profile is
+legitimate for ordinary sessions and useless for the ones you most want: accounts whose risk
+engines bind a session to a device will invalidate it, and a password manager's session is
+tab-bound and never portable.
 
 **Never copy a session out of the user's real browser profile.** If you need their login, that is
 the attached engine's job.