OmOWright

Browser automation as a code library. Install it with bun add github:code-yeongyu/omowright (or import it by the path of a local checkout). Bun >= 1.4 recommended, Node >= 22 supported.

Two engines, one library:

Engine	Use when	Entry point
Owned (default)	scraping, WAF/bot-scored targets, headless, anything that must not touch the user's profile	connectPipe / connectCloakProfile — no CLI, no daemon, no open CDP port
Attached	the task needs the user's logged-in sessions, cookies, or open tabs	connectBrowserSkill — stock BrowserSkill daemon + extension; references/browserskill.md

Never substitute one for the other silently: if the attached engine is not set up, run bskOnboard() and tell the user its single remaining step. It installs the extension only into the browser the user actually uses; when it returns needsChoice, ask which browser that is and pass { browser: "<id>" }.

Core loop (owned engine)

const { connectPipe, compactSnapshot } = await import("omowright");
const browser = await connectPipe({
  browserPath: "<CloakBrowser binary>",           // DEFAULT engine
  browserArgs: ["--no-first-run", `--user-data-dir=${profileDir}`],
  storageRoot: profileDir,
});
const page = await browser.newTab("https://example.com");
const tree = compactSnapshot(await page.snapshot());  // ALWAYS compact before reading
await page.locator("e1").click();                     // refs come from the snapshot
await browser.close();                                // then rm -rf the profile dir

Default engine: CloakBrowser

Use the CloakBrowser binary by default, not a plain headless shell — most real targets sit behind WAFs or bot scoring, and CloakBrowser's source-level fingerprint patches (Cloudflare Turnstile, FingerprintJS, BrowserScan) make it the safe default. Plain headless shell is the speed fallback for trivially open pages: any Chrome/Chromium or ~/Library/Caches/ms-playwright/chromium_headless_shell-*/.../chrome-headless-shell.

python3 -c "import cloakbrowser; print(cloakbrowser.binary_info()['binary_path'])"
# -> ~/.cloakbrowser/chromium-<ver>/Chromium.app/Contents/MacOS/Chromium

For a reused authenticated profile, use connectCloakProfile({ profileDir, fingerprintSeed }) from the package (or the omowright-cloak --profile "$HOME/.local/share/omowright-cloak" --url <url> --once --snapshot launcher). First use pins a fingerprint seed in a mode-0600 metadata file inside the mode-0700 profile; later runs reuse it and REJECT a conflicting seed instead of silently changing identity. It passes the fixed --fingerprint=<seed> plus the platform flag on every connectPipe() launch. The seed is an identity pin, not a credential store.

CLOAKBROWSER ALLOWS ONE INSTANCE. Probe before launching (curl -s -m 2 http://127.0.0.1:9242/json/version). If one answers, connectPipe HANGS during early init — attach with connect() instead. Full pattern: references/stealth.md.

Getting past obstacles

A blocked page is a rung to climb, not a reason to stop and report.

Rung	Use	Advance when
1. snapshot() + locator(ref)	Anything with a usable ref	Ref absent, stale, obscured, or the click hits the wrong node twice
1b. snapshotWithLayers / describeLayers	A blocking overlay explains two identical misses; dismiss it first	@layers none, or the overlay is gone and the click still misses
2. createCua(page) coordinates	Canvas, extension popups, custom controls	Click misses, or screenshot and coordinates disagree
3. Pin the viewport, retry rung 2	Coordinate drift after a resize, DPI scale, or foreign tab	Coordinates land right but the widget still refuses input
4. createCaptcha(page)	A challenge widget is the blocker	Widget solved, flow still stalls
5. Read the browser log	Browser-level failure	The log names a cause outside the page

TWO IDENTICAL FAILURES SELECT THE NEXT RUNG — A THIRD IDENTICAL ATTEMPT IS A DEFECT. Verify after every page-changing action: fresh snapshot for DOM state, fresh screenshot for visual state. Report a stop only when all rungs are exhausted, naming which rung failed with what evidence.

RUNG 5 ENDS IN A WRITTEN DIAGNOSIS, NEVER A SPECULATIVE CODE CHANGE. A browser process problem (missing entitlement, extension service-worker failure, FIDO unavailable) is not fixed by editing automation code; editing it only burns a debugging cycle.

Pin the viewport before trusting coordinates

CUA acts in viewport pixels. When the render surface and coordinate space disagree, every coordinate is off by a constant and retrying repeats the miss:

await page._sendToTarget("Emulation.setDeviceMetricsOverride", {
  width: 1440, height: 900, deviceScaleFactor: 1, mobile: false,
  screenWidth: 1440, screenHeight: 900,
  viewport: { x: 0, y: 0, width: 1440, height: 900, scale: 1 },
});
await page.refreshViewportSize();   // -> { width: 1440, height: 900 }

Pin every page you act on, including tabs you did not open, then take a fresh screenshot — coordinates read off an unpinned screenshot are stale.

Route by task

Task	Read
The user's own signed-in browser and tabs, BrowserSkill sessions, trace-free bskSnapshot, one-click extension onboarding	references/browserskill.md
Visual browsing, coordinate UI, viewport pinning, extension popups	presets/visual-browse/SKILL.md — consider delegating, below
CAPTCHA (checkbox, slider, text OCR, image grid)	presets/captcha/SKILL.md — consider delegating, below
WAF/Cloudflare/bot-detection pages, CloakBrowser, cookie rules	references/stealth.md
First use, page API, snapshot options, locator rules	references/quickstart.md; dialogs and readiness in TOOLS.md
Driving a browser inside eval cells, kernel persistence, parallel lanes	references/eval-kernel.md
Tabs/windows/bookmarks/history/downloads/topSites (Chrome MV3)	presets/chrome/SKILL.md
API JSON instead of DOM scraping, wait for a request, infinite scroll, QA flight trace (jsonl/HAR), request routes	presets/network/SKILL.md
Cross-origin iframes and shadow DOM, overlays that swallow clicks, login/OTP handoff to a human, device emulation	references/frames-layers-human.md
Reading an item from the 1Password web vault (tab-scoped session, sign-in check, secret handling)	references/1password.md

Preset and TOOLS.md paths are relative to the package root.

Hard rules

• NEVER extract and inject cookies for Google (any property) or 1Password. Google's risk engine kills the session server-side and logs the user out of their own browser; 1Password sessions are device-bound and never work from cookies. Detail in references/stealth.md. Cookie reuse is fine for ordinary sessions (Grafana, internal tools).
• Always compactSnapshot() before sending a snapshot to a model — the refs map is ~54% of bytes and resolves in-page, so dropping it is free.
• Refs die on every new snapshot. Pass page.locator("e1") straight from the latest snapshot; never reuse a ref across snapshots, never put one in CSS.
• Refs stay page-level. Child-frame refs look like f1e3 and still go to page.locator("f1e3"); never fetch a frame handle to click inside an iframe.
• Dialogs never block: alert/confirm/prompt/beforeunload are answered by the dialog policy (default accept: confirm() -> true, prompt() -> ""). Change it with connectPipe({ dialogPolicy }) or browser.setDialogPolicy(); observe with page.on('dialog'). Details in TOOLS.md.
• goto waits for meaningful content, not readyState: body plus (interactive elements OR landmarks OR >= 20 text chars). Near-empty pages time out — use page.goto(url, { waitUntil: "commit" }) for those.
• Cleanup is paired: await browser.close() then rm -rf the profile dir in the same finally.

Delegating the pixel loop

CAPTCHA solving and pixel-level visual browsing are iterative (screenshot, reason, act, verify). When that loop would consume your own context, delegate the blocked page to a deep subagent that loads these references. Drive it yourself when the flow is short or the state is already in your hands.

When every rung fails on a login, a one-time code, or a challenge the captcha preset can't clear, the human is the fallback: requestHuman(page, { prompt, until }) brings the tab to front, shows a Done banner, and resumes when the condition holds. Recipe in references/frames-layers-human.md.

task(category: "deep", run_in_background: true, prompt: `
TASK: Get past the CAPTCHA blocking <url> and return the post-solve state.
1. Read `presets/captcha/SKILL.md`, `presets/visual-browse/SKILL.md` (package
   root), and `references/stealth.md` (this skill).
2. connectPipe with the CloakBrowser binary (default engine).
3. Pin the viewport (setDeviceMetricsOverride 1440x900 + refreshViewportSize)
   before computing any coordinate.
4. createCaptcha(page) - click(bounds) for checkbox widgets, drag(from, to,
   {steps}) for sliders, readText(bounds) for text (macOS Vision OCR default).
   Image grids: page.annotatedScreenshot() + cua.click per cell.
5. VERIFY with captcha.waitFor({ until }) on an application acceptance condition;
   only outcome "matched" counts, a snapshot is not proof. Two failures of one
   strategy select the next strategy; do not repeat a third time.
STOP WHEN the page is past the challenge, or all strategies are exhausted -
then report which failed and the browser-log evidence.
DELIVERABLE: post-solve snapshot tree + screenshot path.`)

Choosing this over everything else

Plain webfetch/curl is fine for one static page. The moment a page needs JS, interaction, login, screenshots, CAPTCHAs, or WAF bypass, use this skill rather than ultimate-browsing: one library covers tiers 1-2 with a persistent browser, smaller snapshots, and no agent-browser/CloakBrowser CLI plumbing. For ulw-research browsing lanes, spawn deep lanes that import() this package in eval cells — the browser persists across cells via globalThis, and compactSnapshot keeps dozens of pages inside the context budget.