oh-my-opencode 5.0.0-beta.86 → 5.0.0-beta.87

package/dist/skills/browser/SKILL.md

@@ -1,89 +1,102 @@
 ---
 name: browser
-description: "Drives a real browser: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, and a human handoff for login, CAPTCHA or OTP. Works through the BrowserSkill extension and its bsk CLI, inside the user's own browser, in a separate Agent Window. Use for any interactive browser task; not for a plain search or an unblocked static fetch."
+description: "Drives a real browser through the omowright library from the js eval kernel: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, a human handoff for login, CAPTCHA or OTP, and a browser you own for scraping, bot-scored targets, network capture and QA traces. Use for any interactive browser task; not for a plain search or an unblocked static fetch."
 ---
 
 # Browser
 
-Two engines live behind this skill. Choose before you act:
+One library, two engines. omowright ships inside this skill; choose the engine before you act:
 
-| You need | Engine | Where |
+| You need | Engine | Entry point |
 |---|---|---|
-| A site the user is signed into, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser | this file |
-| A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control | **owned** — a browser your code launches | [references/owned-engine/README.md](references/owned-engine/README.md) |
+| A site the user is signed into, their open tabs, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser through BrowserSkill | `connectBrowserSkill()` |
+| A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control, headless runs | **owned** — a browser your code launches | `connectPipe()` / `connectCloakProfile()` — [references/owned-engine/README.md](references/owned-engine/README.md) |
 | Text out of a URL, a 403 bypass, a platform that blocks fetchers | neither | the `ultimate-browsing` skill |
 
 **Attached is the default,** because it is the only engine carrying the user's logins and the only
-one where a human is a single command away. The owned engine is an opt-in local install, not part
-of this package.
+one where a human is a single call away. Never substitute one engine for the other silently: if
+the attached engine is not set up, run the onboarding script and tell the user its one remaining
+step.
 
-## Step 0 — prove the stack before you drive it
+## Step 0 — load omowright and prove the stack
 
-```bash
-node "<skill-root>/scripts/browser-doctor.mjs"
+```js
+const { loadOmowright } = await import("<skill-root>/scripts/omowright.mjs")
+const { omowright } = await loadOmowright()          // { connectBrowserSkill, bskSnapshot, connectPipe, ... }
 ```
 
-It reports one of four states and what to do next:
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs" --json
+```
 
 | State | Meaning | Next |
 |---|---|---|
 | `ready` | CLI, daemon and a connected browser | start a session |
-| `no-extension` | CLI works, no browser is connected | give the user the store link the doctor printed, wait, re-run |
-| `no-cli` | `bsk` is not installed | `node "<skill-root>/scripts/browser-install.mjs"`, then re-run |
-| `no-browser-support` | the platform has no supported browser | say so and stop |
-
-**Never substitute another browser for a missing one.** A headless browser you launch yourself has
-none of the user's sessions, so every login turns into a ladder you should not be climbing. If the
-attached engine is unavailable, say which state you hit and ask the user.
-
-## The loop
-
-```bash
-bsk session start --json --no-focus --name "<task>"     # keep session_id
-bsk navigate https://example.com --session <id> --json
-bsk observe --session <id>                              # @eN refs live here
-bsk click @e1 --session <id> --json
-bsk screenshot --session <id> --out ./shot.png --json
-bsk session stop <id> --json                            # success AND failure
+| `no-cli` / `no-daemon` / `no-extension` | something is missing | `node "<skill-root>/scripts/browser-install.mjs"` prepares everything it can, then prints the **single** step only the user can do (relaunch the browser and click **Enable**); relay it verbatim, wait, re-run the doctor |
+| `no-browser-support` | no Chromium-family profile on this machine | say so and stop |
+
+**Never launch a headless browser because the attached one is missing.** It has none of the
+user's sessions, so every login turns into a ladder you should not be climbing. Say which state
+you hit and ask.
+
+## The loop (attached)
+
+```js
+const session = await omowright.connectBrowserSkill({ name: "<task>", focused: false })
+try {
+  await session.navigate("https://example.com/", { waitUntil: "load" })
+  const { tree, refs, css } = await omowright.bskSnapshot(session, { interactive: true })  // OmOWright tree + refs, no trace in the page
+  await session.click({ selector: css.e3 })                                                 // css[ref] is null inside shadow roots:
+  const vom = await session.observe({ maxTokens: 4000 })                                    //   then read the daemon's own tree ...
+  await session.click("@e7")                                                                //   ... and click its @eN ref
+  await session.fill(css.e5, "hello")
+  await session.press("Enter")
+  await session.waitForNavigation({ waitUntil: "load" })
+  const shot = await session.screenshot()                                                   // { buffer, width, height, captureId }
+} finally {
+  await session.stop()                                                                      // success AND failure; returns borrowed tabs
+}
 ```
 
-1. **Observe before every action.** `observe` returns a semantic tree whose `@eN` refs are reissued
-   on each call. Read a ref and use it in the same cycle; a ref from two calls ago points somewhere
-   else now.
-2. **Navigation and large DOM changes stale every ref.** Observe again rather than reusing.
+1. **Read before every action.** `bskSnapshot` refs and `observe` `@eN` refs are reissued on each
+   call; use a ref in the same cycle you read it.
+2. **Navigation and large DOM changes stale every ref.** Read again rather than reusing.
 3. **Two identical failures mean change approach, not retry.** A third identical attempt is a defect.
-4. **Borrow a user tab explicitly** (`tab list --scope user`, `tab borrow <id>`, `tab return <id>`).
+4. **Borrow a user tab explicitly** (`tabList({ scope: "user" })`, `tabBorrow(id)`, `tabReturn(id)`).
    Borrowing prompts the user; never invent tab ids and never repeat a denied borrow.
-5. **Always stop the session,** on success and on failure. Stopping also returns borrowed tabs.
+5. **Always `stop()` the session,** on success and on failure.
 
-Command semantics, the flags that behave differently than they read, and the failure table are in
-[references/commands.md](references/commands.md).
+Every method, its options, and the failure codes are in [references/commands.md](references/commands.md).
 
 ## When a human is the only way through
 
 Login, CAPTCHA, OTP, a payment confirmation, a consent dialog:
 
-```bash
-bsk request-help --session <id> --prompt "<what you need done>" [--target @eN]
+```js
+const outcome = await session.requestHelp({ prompt: "<what you need done>", targets: ["@e4"], timeoutMs: 300_000 })
 ```
 
-Then observe again. Respect a `cancelled` or `timed_out` answer; do not work around it by changing
-the extension's automation settings.
+Then read the page again. Respect a `cancelled` or `timed_out` outcome; do not work around it by
+changing the extension's automation settings.
 
 ## Rules
 
-- **Never read credentials through the page.** No `evaluate` that extracts a password, token, cookie
-  or recovery code. The value of this engine is that the browser is already signed in.
+- **Never read credentials through the page.** No `evaluate` that extracts a password, token,
+  cookie or recovery code. The value of the attached engine is that the browser is already signed in.
 - **Never clear cookies, cache or site data.** It is the user's real profile; clearing it logs them
   out everywhere. No flow here needs it.
-- **`--no-focus` by default.** The browser belongs to someone who is probably using it.
+- **`focused: false` by default.** The browser belongs to someone who is probably using it.
 - **One short, named session per task,** always stopped.
-- Do not toggle the extension's automation settings, and do not restart the browser to fix a state.
-
-## More
-
-- [references/install.md](references/install.md) — installing the CLI and the extension, per OS
-- [references/commands.md](references/commands.md) — command semantics, refs, failure table
-- [references/remote.md](references/remote.md) — agent on one machine, browser on another
-- [references/recipes/1password.md](references/recipes/1password.md) — reading a vault the user has unlocked
-- [references/owned-engine/README.md](references/owned-engine/README.md) — the code-driven engine
+- **Bot-scored or WAF targets go to the owned engine.** The attached engine's daemon enables console
+  capture on every tab it drives, which is a known automation signal; CloakBrowser through
+  `connectCloakProfile()` is the stealth path.
+
+## Where the rest lives
+
+| Topic | Read |
+|---|---|
+| Session methods, targets, options, error codes | [references/commands.md](references/commands.md) |
+| Installing: CLI, daemon, extension, the one human step, blocklisted extension | [references/install.md](references/install.md) |
+| Agent on one machine, browser on another | [references/remote.md](references/remote.md) |
+| Owned engine: launch, snapshot ladder, network, frames, human handoff | [references/owned-engine/README.md](references/owned-engine/README.md) |
+| Reading a 1Password vault the user has unlocked | [references/recipes/1password.md](references/recipes/1password.md) |

package/dist/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/dist/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/dist/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/dist/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.